Builderforce

Builderforce.ai

人在回路的全自主云 —— 训练你自己的 AI Agent，并在自己的 Agent 内使用它们；在看板上管理整个工作团队，并在不离开 VS Code 的情况下审核和批准每项操作。

---

最新动态

• 2026-10-12 — 本地推理运行时中的顺序批处理。 builderforce-inference 中的 Engine::generate_batch 可在不重新加载的情况下，使用一个已加载的模型运行多个提示词（e4c07ee）。本次更新尚未包含并发 token 混合／分页注意力。变更日志：DONE.md。

---

什么是 Builderforce.ai？

Builderforce.ai 是一个人在回路的全自主云，让创意变成软件，再让软件变成 Agent。你始终掌控每个步骤，而 AI Agent 负责执行工作——训练自己的专用 Agent，并让它们在自己的 Agent 内工作；通过看板管理整个工作团队；无需离开编辑器，即可审核、验证和批准所有内容。它将完整的浏览器内 IDE、AI 训练流水线、专用 Agent 工作力量注册中心，以及用于管理可自托管 BuilderForce Agents 网格的编排门户融为一体。

三项核心能力：

能力	功能
🔁 训练 Agent，并在自己的 Agent 内使用	在浏览器中训练自定义 Agent（WebGPU LoRA + AI 评估），将其发布到工作力量注册中心，然后聘用它，并在自己的 Agent 内调用它——你的专用 Agent 会成为主 Agent 可以委派任务的工具。
▦ 看板与项目管理	将工作整理到项目中，然后在实时看板上规划、分配和跟踪每项任务（按状态或 Agent 划分泳道，并提供表格、日历和甘特图视图）。人类与 AI Agent 共用同一看板。
🧩 无需离开 VS Code	BuilderForce VS Code 扩展可在编辑器中运行整个平台——与 Agent 聊天、分配并运行任务、审核和验证其工作，并批准人在回路的操作，无需离开代码。

一个平台。三种角色：

角色	功能
企业级 IDE	浏览器内开发运行时（BuilderForce WebContainers，我们自研的 MIT 运行时）+ Monaco + xterm.js；实时协作；AI 结对编程
AI 训练工作室	在浏览器中对指令数据集进行 LoRA 微调；由 WebGPU 加速；支持最多 2B 参数的模型；无需云端 GPU
编排门户	BuilderForce Agent 集群管理；任务分配；心跳监控；Agent 间网格中继；审批关卡

---

核心能力

浏览器内 IDE

• 浏览器内开发运行时，由 BuilderForce WebContainers（@seanhogg/builderforce-webcontainers）提供，是我们自主开发的开源（MIT）运行时。通过使用 esbuild-wasm 按需编译每个文件并从 esm.sh 加载软件包，为 Vite（React、Vue、Svelte）、Create React App 和静态项目提供预览；运行 Node 程序、从真实的注册表执行 npm install，并提供 bfsh shell，每个进程使用一个 Web Worker。无需 COOP/COEP 标头，也没有会话数量上限。预览和进程由 preview.builderforce.ai 提供服务，与您的 Builderforce 会话隔离。不支持 Next.js/Nuxt/SvelteKit/Remix/Astro 开发服务器、原生插件和安装脚本；检测到这些内容时会说明原因并拒绝运行。
• Monaco Editor，支持语法高亮、IntelliSense、多文件标签页，以及通过 Yjs CRDT 实现的实时协同编辑
• xterm.js 终端，连接到运行时的 bfsh shell（行编辑、历史记录、管道、npm、npx），供协作者共享
• AI 聊天面板 — 支持流式输出的 AI 助手，可获取完整项目文件上下文；能够直接应用代码更改并创建文件
• 实时预览 — 由浏览器内开发服务器提供服务的 iframe；每次保存都会重新加载所有已打开的预览
• 在标签页中检查和发布 — 类型检查（createChecker()）和生产构建（runtime.build()）都在浏览器中运行，无需安装，因此“检查”和“发布”可直接对文件执行

AI 训练工作室

• 在浏览器内进行 LoRA 微调 — 使用 @seanhogg/builderforce-memory / Transformers.js 和 WebGPU；完全在客户端训练 Mamba-1/2/3 和 GPT 风格模型，参数量最高可达 2B
• 混合本地大脑 — Mamba State Engine（mamba-engine.ts）在 Transformer 推理的同时运行 O(n) 选择性扫描；Agent 状态以紧凑的 Float32 状态向量形式持久化到 IndexedDB，并嵌入导出的 AgentPackage JSON 中
• 数据集生成 — 在 LLM 辅助下创建 JSONL 指令数据集，并通过 SSE 流式传输进度
• AI 评估 — 独立裁判按代码正确性、推理质量和幻觉率（0.0–1.0）对模型输出评分
• WebGPU 回退 — 通过 forceFallbackAdapter: true 使用 CPU 软件路径；平台会明确报告 gpuMode: 'cpu-fallback'

人力资源注册表

• 发布专业 Agent — 将 LoRA 适配器、能力档案和 MambaStateSnapshot 打包为可移植的 AgentPackage JSON 工件
• 基于技能的发现 — 可按技能、评估分数和雇用次数搜索 Agent
• 雇用并部署 — 一键在您的 BuilderForce Agents 网格中注册 Agent；提供用于本地部署的 PowerShell 安装脚本
• 迭代改进 — training_sessions 表会跟踪数据集 → 训练 → 评估 → 重新训练的循环，以持续提升 Agent 质量

本地 LLM 推理流水线

• 按 Agent 设置推理端点 — POST /api/ide/agents/:id/chat 通过 OpenRouter 路由推理，并将 Agent 的角色设定注入系统提示词；X-Inference-Mode: lora | hybrid | base | fallback-base 标头会指示实际运行的路径
• Mamba 状态注入 — v2.0 Agent 携带 MambaStateSnapshot；每次推理调用都会在系统提示词前添加 [Memory: step=N signal=X context="..."]，使 Agent 无需重新训练即可保留对话记忆
• Mamba 状态同步 — 每次会话结束后，PUT /api/ide/agents/:id/mamba-state 会接收 builderforce CLI 发送的 MambaStateSnapshot；随后将 Agent 包升级到 v2.0，并重新计算 inference_mode；GET /api/ide/agents/:id/mamba-state 用于获取存储的快照
• 包版本控制 — Agent 包分为 v1.0（仅 LoRA）和 v2.0（LoRA + Mamba 状态）；GET /api/ide/agents/:id/package 会返回正确格式并递增 request_count
• 聊天中的 Workforce 路由 — 使用 model: "builderforce/workforce-<agentId>" 调用 POST /api/ai/chat，会自动路由到 Agent 推理端点（仍接受旧版 coderclawllm/ 前缀）；无需更改客户端
• 推理日志记录 — agent_inference_logs 表会记录每个请求的模型引用、延迟、令牌数量、状态和推理模式，以便观测和计费

BuilderForce Agents 编排门户

Builderforce.ai 是 BuilderForce Agents 可自托管 Agent 的云端控制平面：

• 集群注册 — Agent 主机通过 POST /api/agent-hosts 注册，并提交机器配置文件（IP、工作区目录、端口、隧道元数据）
• 心跳与能力同步 — PATCH /api/agent-hosts/:id/heartbeat 用于更新能力映射和机器配置文件
• 分配上下文 — GET /api/agent-hosts/:id/assignment-context 提供已分配项目的元数据和上下文提示；运行时会同步到 .builderforce/context.yaml
• 主机间网状中继 — AgentHostRelayDO Durable Object 会在 Agent 主机之间代理 WebSocket 连接；POST /api/agent-hosts/:id/forward 会将任务分派给远程主机，使用源主机自己的 API 密钥进行身份验证（?from=<id>&key=… 或 X-AgentHost-From 标头），并拒绝跨租户请求
• 审批关卡 — 对影响重大的 Agent 操作实施人工介入控制；Agent 在执行前请求审批，审批结果会被审计
• 任务管理 — tasks 和 executions 表用于跟踪分配给特定 Agent 主机的工作；POST /api/tasks/next 会向等待中的 Agent 提供下一个任务
• 旧版挂载点 — 尚未迁移的集群仍可使用 /api/claws 和 /api/agentNodes，但会返回 Deprecation: true 和指向 /api/agent-hosts 的 Link: rel="successor-version"（presentation/middleware/legacyAlias.ts）。新的调用方应使用规范路径。

多租户平台

• JWT 身份验证：采用 Web 令牌（全局）与租户令牌（限定工作区）的双令牌模型
• 多种身份验证方式 — 电子邮件/密码、OAuth 社交登录（Google、GitHub、LinkedIn、Microsoft）和魔法链接登录可在同一账户中共存
• 租户隔离 — 所有资源（项目、Agent 主机、Agent、训练任务）均限定在租户范围内；无法跨租户访问数据
• 多工作区 — 用户可加入多个租户；登录时由 bf_default_tenant_id 自动选择默认租户
• 管理员可观测性 — 为平台管理员提供 /admin 界面（superadmin 标记）；R2 中的 logs/global-errors.txt；用于查看 LLM 使用指标的 /observability

计费与订阅（Stripe）

• 仅支持 Stripe — src/infrastructure/payment/StripeProvider.ts（Stripe Checkout + Billing，托管支付页面，通过 webhook 激活）。这里刻意不提供服务商切换，也没有手动备用方案：此前有一种备用方案会在未扣款的情况下激活套餐，导致未配置的部署免费发放付费套餐。
• PaymentProvider 接口 — src/infrastructure/payment/PaymentProvider.ts 让 TenantService 不直接依赖具体的 Stripe 客户端，并允许测试注入伪对象；它不是用于切换服务商的扩展点。
• 结账流程 — POST /api/tenants/:id/subscription/checkout 始终返回托管的 checkoutUrl。只有经过签名验证的 webhook 确认付款后，套餐才会激活；绝不会由请求本身触发激活。
• Webhook 处理器 — POST /api/webhooks/payment 接收 Stripe 事件；通过 HMAC 验证，并设置 5 分钟的重放窗口；通过规范化的 WebhookEvent 激活或取消订阅。
• 配置 — 设置 STRIPE_* Worker 密钥（参见 src/infrastructure/payment/index.ts）。密钥采用延迟验证：缺少密钥时，计费路由会返回 503，且不会影响 Worker 启动。

开发分析与团队洞察

• 贡献者档案 — 跨平台开发者身份关联（GitHub、Jira、Bitbucket）；GET /api/contributors
• 活动数据接收 — POST /api/contributors/activity 接收 PR 开启、合并、评审、提交和 issue 事件，并自动汇总每日指标
• 加权活动分数 — 按贡献者计算每日分数（提交×1 + PR×3 + 评审×2 + issue×1.5）；活跃开发日 = ≥1 次提交或 PR 操作
• PR 周期时间 — 跟踪每条活动记录中从 pr_opened 到 pr_merged 事件的端到端耗时（小时）
• 集成凭证管理器 — 使用 AES-256-GCM 加密并按租户存储平台凭证；GET/POST/PUT/DELETE /api/integrations；提供按服务商划分的连通性测试（POST /api/integrations/:id/test）
• 团队层级 — 支持嵌套开发团队及经理与成员关系；GET/POST/PATCH/DELETE /api/dev-teams；提供添加和移除成员的端点
• 站会报告 — GET /api/reports/standup — 每日摘要：活跃贡献者、提交、已合并的 PR、已解决的 issue；近期 PR 和已解决的 issue
• 代码评审报告 — GET /api/reports/code-review — 14 天时间窗口；过期 PR（超过 7 天）、平均周期时间、评审者活动
• 高管摘要 — GET /api/reports/executive — 可配置日期范围内的 KPI：贡献者人数、提交总数、已合并的 PR、新增代码行数、平均活动分数、顶尖贡献者
• 报告计划 — GET/POST/PATCH/DELETE /api/reports/schedules；采用 cron 风格的发送配置（每日/每周），包含小时和收件人列表
• 报告订阅 — GET/POST /api/reports/subscriptions；用户可按报告类型选择订阅或退订

平台基础设施

• 按租户限流 — TenantRateLimiterDO Cloudflare Durable Object；滑动窗口（FREE 60 RPM、PRO 300 RPM、TEAMS 1000 RPM）；返回 X-RateLimit-Limit/Remaining/Reset 和 Retry-After 标头
• 自动审批规则 — GET/POST/PATCH/DELETE /api/approval-rules；在 POST /api/approvals 中按 actionType、最高成本和变更文件数评估规则；条件匹配时绕过人工审批
• 审批通知 — 新审批请求和审批决定会触发 Slack webhook 与 Resend 邮件提醒；通过 SLACK_APPROVAL_WEBHOOK_URL 和 RESEND_API_KEY 配置
• 升级 cron — GET /api/approvals/escalate?secret= 使超时的待处理审批失效并触发 Slack 提醒；适用于 Cloudflare Cron Triggers
• OTel 遥测代理 — 使用 POST /api/telemetry/spans 接收数据；使用 GET /api/telemetry/spans 查询；使用 GET /api/telemetry/traces 列出记录；成本以毫分整数存储；从 builderforce CLI 转发 W3C X-Trace-Id 标头

---

最新功能

该平台已从 IDE 加培训工作室，发展为完整的Agent 工作记录系统。以下是最近新增的功能——面向企业交付、质量、知识和 FinOps 的功能模块，构建于 Agent 团队之上。

规划主干——从项目组合到任务（mig 0213、0225）

• 单一、带日期和成本的层级结构——portfolio → initiative → epic → task，并可在任意层级关联目标与关键结果作为目标层。每个层级都带有日期，并显示在同一张嵌套式甘特图（PlanningSpineGantt）中。
• 成本从叶节点向上汇总——大模型支出（在写入时根据 llm_usage_log 定价）以及人工投入（成员成本费率 × 小时数）会汇总至所有上级节点。无需并行财务系统，也无需回填。
• CAPEX / OPEX 拆分——每个节点都有一个 cost_class，按以下优先级确定：显式设置 → 继承 → Agent 按投资类别分类 → GAAP 保守默认值。子节点类别与父节点不一致时，会标记为异常，供 PM 协调处理。
• 端点——GET /api/pmo/spine、GET /api/pmo/spine/export.csv、GET /api/pmo/rollup（项目组合/项目/工作区）、PATCH /api/pmo/cost-class、POST /api/pmo/cost-class/classify、项目 POST/DELETE /api/pmo/dependencies（检查循环依赖）→ 按需计算关键路径。入口：/projects?tab=portfolio，受 insights.portfolio / insights.pm 权限控制。

质量——错误可观测性 + 一键修复 Agent（mig 0240）

• 多源接入——五种适配器共用一种规范事件格式：原生（@seanhogg/builderforce-quality 浏览器 SDK）、OTLP、Sentry、PostHog、LogRocket（通过 HMAC 验证 Webhook；Sentry 连接支持回填）。
• 指纹分组——事件按 (tenant, project, fingerprint) 写入或更新 error_groups；指纹可以显式指定，也可以根据堆栈顶部帧和规范化消息生成；统计发生次数和精确的不重复用户数；已解决的 Bug 再次发生时会重新打开。
• 一键修复循环——POST /api/quality/groups/:id/fix 会创建一个看板任务（根据错误命名并确定优先级，附上堆栈跟踪作为简报），并派发一个云端 Agent 提交拉取请求。崩溃 → 分组 → 任务 → PR，全程在同一界面完成。
• 端点——需认证的 /api/quality/*（收集器、集成、规则、分组、修复）；使用公开密钥/HMAC 认证的接入端点 /api/quality-ingest/{events,otlp/v1/logs,otlp/v1/traces,webhooks/:collectorId/:provider}。仪表板：/quality。按 error_events 计量。

知识管理与合规（mig 0227）

• 带版本的 SOP、流程和文档——正文可实时编辑，每次发布都会生成一个不可变快照（版本号 + 变更说明 + 发布者）。
• 可供审计的确认记录——阅读确认与特定版本及时间戳绑定；每位用户的状态为已确认 / 待处理 / 已逾期，管理者可通过 GET /api/knowledge/compliance 汇总查看——为 SOX、TISAX、ISO 27001 提供证据。
• AI 编写 + 分析——POST /api/knowledge/ai/draft 会流式生成 Markdown 草稿；POST /api/knowledge/documents/:id/analyze 会返回结构化分析结果（低效 / 缺口 / 风险 / 清晰度）以及改进后的流程。通过大模型网关计量。
• 实时协同编辑——通过 NEXT_PUBLIC_COLLAB_WS_URL 使用 Yjs CRDT，并支持在线状态感知；在工作区角色权限之上，可为每份文档指定编辑者/查看者协作者；未配置协作时会回退到自动保存。入口：/knowledge。

单面板看板连接器 (mig 0221)

• 10 个系统间双向同步 — 每个提供方都会实现 fetchTicketsSince(cursor) + pushUpdate(externalId, changeSet)，将数据规范化为统一的工单结构，并标记其来源。
  • 项目管理 / 工作： GitHub Issues、Jira、Linear、monday.com、Asana、ClickUp
  • ITSM： ServiceNow、Freshservice
  • 事件管理： Sentry、PagerDuty
• 支持时使用 Webhook（GitHub、Jira、Linear、monday、Sentry、PagerDuty），否则使用轮询。Agent 可在工单或事件的来源系统中对其进行处理；更改会同步回源系统——单面板，无需迁移。
• 端点 — GET /api/board-connections/providers（目录）、CRUD /api/board-connections、POST /api/board-connections/:id/sync、GET /api/board-connections/:id/links。

平台迁移与集成中心 (mig 0256)

放心从竞争对手的跟踪工具迁出，或者只同步数据进来——这是基于连接器框架构建的分阶段导入器。在提交之前，任何内容都不会进入实际项目、任务或成员中。

• 提供方发现 — discover() 会枚举 Jira、monday、Rally、GitLab、Bitbucket、GitHub 中的外部项目、条目类型和用户（符合迁移条件的提供方；新增 Rally/GitLab/Bitbucket 适配器）。
• 暂存缓冲区 — import_runs + import_staged_{projects,items,users} + import_type_mappings；可将多个外部项目合并到一个 BuilderForce 项目中，将条目类型映射为任务类型/状态，并邀请/映射用户——所有内容都会在导入前接受审核。
• 迁移 / 同步 / 两者兼有 — 一次性历史数据导入、持续的 board_connections 同步，或两者兼有。持久化的 board_type_mappings 可确保持续同步将任务写入映射的类型/状态（而非硬编码的待办列表）。导入的条目会保留其受派人（映射到成员）和故事点。
• 集成库 — /settings/integrations 是工作区主页：按类别展示卡片（项目管理 / SCM / ITSM / 事件管理），提供按提供方配置的面板（凭据 · 连接 · 活动/诊断），以及“开始迁移”入口。GitHub/GitLab/Bitbucket 可同时连接问题（迁移）和代码仓库（代码）。
• 可由 Brain 驱动 — 整个流程都在网关 MCP 目录中提供（integrations.create_credential/test、migrations.start/set_mappings/stage/commit）；Brain（停靠在右侧）会通过 open_migration_panel 在左侧打开迁移面板。
• 端点 — /api/migrations（start/list/get/:id/mappings/:id/stage/:id/commit，MANAGER+，支持缓存 + 版本递增）。

Agentic Tester — 自主 QA (mig 0063, 0206)

• 按热度图排名的探索 — 旅程事件（POST /api/qa/events）会根据加权近期频率为路由与元素区域排名（GET /api/qa/heatmap）；探索会在预算范围内从最热门的区域制定计划。
• AI 生成 Playwright — POST /api/qa/generate 会将流程转换为可执行规范，并解析角色凭据；也提供仅基于确定性热度图的计划（无模型成本）。
• 经过身份验证的容器运行 — 测试框架会领取一项探索任务，以真实角色身份登录（凭据经过加密，并受开发者权限控制），按计划执行，并捕获控制台/页面错误、失败的请求、断言失败和崩溃。
• 发现 → 看板 → 修复 — 发现结果会按指纹去重；启用自动路由后，任何达到或超过严重性阈值的发现结果都会成为修复泳道中的看板任务，并触发与人工拖动看板时相同的泳道自动运行 → 修复 Agent 会创建 PR。定时任务会按 cron 运行。可通过 GET /api/qa/quality 查看质量趋势（逃逸与捕获的缺陷）。

用量计量 (mig 0218)

• 按消耗计量，而非按可见性计量 — 一个框架（/api/consumption）会报告本月至今的 ai_tokens、ingestion（字节）和 error_events 用量，并与套餐额度对比；它使用网关和摄取门所执行的同一套计量逻辑，因此成员看到的“已用百分比”与实际执行的上限一致。缓存 60 秒，按租户和日历月作为键。

协同参与与责任追踪 (mig 0334)

• 由合适的角色完成工作 — 一等 Agent↔角色能力 (ide_agents.role_keys) 驱动基于角色的分派：生产者阶段根据工单的 action_type 确定角色，并分派具备相应角色能力的 Agent 或人类成员，绝不误派。避免出现“把编写代码的任务分派给产品经理”这类问题。
• 每张工单都有参与者清单 — ticket_participants 根据看板泳道要求确定所需角色，按能力匹配各个名额，并追踪每位参与者的状态（待处理 / 已分派 / 进行中 / 已完成 / 已请求修改 / 已豁免 / 无人承担）。
• 不可变的责任报告 — 仅追加写入的 ticket_role_signoffs 账本按角色记录人员 / 时间 / 结论 / 评论 / 贡献；默认拒绝的 RBAC（只有具备相应角色能力的成员才能以该角色签核）；每次签核都会写入统一活动日志。资源评估控件可在模板之外添加所需角色；未解决的新增角色会显示为阻塞性资源缺口。
• 端点 — GET /api/kanban/tasks/:id/accountability、/participants、POST /participants（评估）/ /materialize，以及 MCP kanban.participants / kanban.accountability / kanban.assess_resource。界面：工单抽屉中的责任追踪标签页 + 看板上的 X/Y 参与者标记。

售前 RFP / RFQ 响应 (mig 0335)

• 将代码仓库转化为提案 — 内置的 CTO + 产品负责人 Agent 根据对项目能力的分析，生成带品牌标识和成本估算的提案，其中包含成本 / 损益、阶段甘特图、风险、依赖项，以及与需求相匹配的能力人员名单。
• 联合品牌输出 — 将请求方的配色方案和 Logo 与响应方的品牌元素融合，生成独立完整的提案文档（可打印为 PDF / 下载）；基于新鲜度门槛确保依据可靠（扫描数据超过 5 天未更新时，会在响应前重新运行确定性系统审计）。
• 界面 — Projects RFP 标签页（列表 / 创建）+ /projects/rfp/[id] 详情页；/api/rfp 路由。

事件管理与主动监控 (mig 0292)

• 事件处理形成闭环 — 配备服务台 / 事件经理 Agent、Freshdesk 连接器、值班轮换、定时升级、Teams / Slack / 电子邮件寻呼，以及逐事件的战情室信息流。事件解决后，根因分析报告会发布到知识库，并写入项目的 Evermind，让工作团队从中学习，避免重复出现同类原因。
• 监控画布 — 在上传的架构图上标注心跳 / HTTP / webhook / 指标监控器；每隔 */5 扫描一次并评估监控器，发生违规时会自动启动值班调查（监控器 → 信号 → 事件 → 寻呼），并在时间线上提供报告。

会议与实时协作 (mig 0292, 0330)

• Agent 参与的视频 / 音频会议 — 通过 CeremonyRoomDO 中继实现网状 WebRTC；Agent 与会者通过字幕 / 转录桥接实时发言；录制和转录会生成 AI 会议纪要。同步 Google / Microsoft 日历。界面：/meetings。

AI 经理 — 类型与辅导 (mig 0327)

• 与角色目录关联的类型化经理 — 开发 / QA / 服务台 / DevOps 经理类型映射到 roleCatalog（自定义角色会成为 role:<key> 类型）；人类 → 经理的辅导会话支持指令 | 任务模式，并具有到期 / 完成状态，用于指导经理 Agent 如何管理其下属。

记忆优先回答 — 跳过付费 LLM

• 优先从项目自身的记忆中作答，避免消耗模型调用 — Web 端和 VS Code webview Brain 会先查询项目的 project_facts 事实层及其 Evermind；若置信度足够，则跳过 LLM（包括精确重复问答缓存 + 可选的 Evermind 优先推理），统一由 resolveMemoryAnswer 提供答案。学习内容会通过一个共享的 contributeTextToProjectEverminds 扩散到项目下的每个 Evermind（其自身的 head 以及 IDE 构建的各个 head）。端点：GET/POST /api/projects/:id/answer、GET /api/projects/:id/evermind/targets。

---

身份验证

Builderforce.ai 支持三种可在同一账户上共存的登录方式。单个用户可以关联多个 OAuth 提供商、设置密码，并交替使用魔法链接。

登录方式

方式	工作原理
邮箱 + 密码	POST /api/auth/web/login — PBKDF2（100k 次迭代，SHA-256）；邮箱错误或密码错误时返回相同的通用错误
OAuth 社交登录	GET /api/auth/oauth/:provider → 提供商授权 → GET /api/auth/oauth/:provider/callback → 签发 JWT；浏览器重定向至 /auth/callback?token=…
魔法链接	POST /api/auth/magic-link 通过电子邮件发送一个有效期为 15 分钟、只能使用一次的令牌；GET /api/auth/magic-link/verify?token=… 签发 JWT；始终返回 200（不会泄露邮箱是否存在）

支持的 OAuth 提供商：google、github、linkedin、microsoft。

身份验证流程图

Browser
  │
  ├─ Email/password ──────────────────────────► POST /api/auth/web/login
  │                                              Returns JWT in JSON body
  │
  ├─ OAuth (click button) ────────────────────► GET /api/auth/oauth/:provider
  │                                              302 → provider consent screen
  │                                              Provider → GET /api/auth/oauth/:provider/callback
  │                                              API issues JWT
  │                                              302 → /auth/callback?token=JWT
  │                                              Frontend page writes token to localStorage
  │
  └─ Magic link ──────────────────────────────► POST /api/auth/magic-link
                                                 Email sent with /auth/magic-link?token=…
                                                 Frontend page calls GET /api/auth/magic-link/verify
                                                 Returns JWT in JSON body

JWT 策略

• Web 令牌（localStorage key: bf_web_token）— 有效期为 24 小时的 HMAC-SHA-256 JWT；负载：{ sub, email, username, amr?, sa?, jti, sid }
• 租户令牌（localStorage key: bf_tenant_token）— 有效期为 1 小时、限定于工作区的 JWT；由 POST /api/auth/tenant-token 签发
• 每个签发的令牌都会记录在 auth_tokens 表中（JTI + 会话 ID）；webAuthMiddleware 会在每次请求时根据此表进行验证，从而支持即时撤销

账户管理端点

端点	身份验证	描述
GET /api/auth/linked-accounts	Web JWT	列出已关联的 OAuth 提供商，以及账户是否设置了密码
DELETE /api/auth/unlink/:provider	Web JWT	取消关联某个提供商；如果这会移除最后一种登录方式，则无法执行
POST /api/auth/add-password	Web JWT	为仅使用 OAuth 的账户添加密码

OAuth 安全性

• CSRF 防护 — OAuth state 参数使用 JWT_SECRET 进行 HMAC-SHA-256 签名，并包含随机数，有效期为 10 分钟；无需数据库
• 账户关联 — 如果 OAuth 邮箱与现有账户匹配，系统会自动关联该提供商；由于用户控制自己的邮箱，因此此操作是安全的
• 仅使用邮箱的用户 — 尚未设置密码的 OAuth 用户无法使用取消关联端点；必须先调用 POST /api/auth/add-password

启用 OAuth 提供商

为各提供商提供客户端凭据作为 Cloudflare Worker 密钥，即可启用该提供商。缺少凭据的提供商会静默返回 503 — 只需配置你想使用的提供商。

# Google
wrangler secret put GOOGLE_CLIENT_ID
wrangler secret put GOOGLE_CLIENT_SECRET

# GitHub
wrangler secret put GITHUB_CLIENT_ID
wrangler secret put GITHUB_CLIENT_SECRET

# LinkedIn
wrangler secret put LINKEDIN_CLIENT_ID
wrangler secret put LINKEDIN_CLIENT_SECRET

# Microsoft
wrangler secret put MICROSOFT_CLIENT_ID
wrangler secret put MICROSOFT_CLIENT_SECRET

在各提供商的控制面板中注册 OAuth 回调 URL：

https://api.builderforce.ai/api/auth/oauth/{provider}/callback

将 {provider} 替换为小写的提供商名称：google、github、linkedin、microsoft。

提供商设置

提供商	设置时间	需要人工审核？	关键注意事项
Google	~10 分钟	登录无需审核；Gmail/Calendar/Drive/YouTube 权限范围需要审核	一个 OAuth 客户端可用于所有 Google 流程 — 必须为每个流程注册一个重定向 URI，否则连接器会因 redirect_uri_mismatch 返回 400，即使登录正常
LinkedIn	~10 分钟	不需要（自动批准）	必须添加 “Sign In with LinkedIn using OpenID Connect” 产品 — 否则 /v2/userinfo 端点不会返回邮箱地址
GitHub	~5 分钟	不需要	每个应用只能设置一个回调 URL — 请为本地开发另建一个 OAuth App
Microsoft	~10 分钟	不需要	与 Google 一样，存在一个客户端用于多个流程的问题 — 除登录外，还要注册邮箱/日历/云盘的重定向 URI

---

Google

1. 前往 console.cloud.google.com，创建或选择一个项目

2. APIs & Services → OAuth consent screen

   • User Type：External
   • 应用名称、支持邮箱，添加范围：email、profile、openid（非敏感，无需审核）
   • 连接器也需要在此列出其范围，而且这些范围并非免费：Gmail （gmail.modify、gmail.send）属于受限范围；Calendar/Drive/YouTube 属于 敏感范围。在应用处于 Testing 状态时，这两类范围均可供列为测试用户的账号使用；但若要公开使用，则需要通过 Google 的验证审核。
   • 开发期间，将你的邮箱添加为测试用户

3. APIs & Services → Credentials → Create Credentials → OAuth 2.0 Client ID

   • Application type：Web application
   • Authorized redirect URIs —— 每种流程都要添加一条，而不只是登录流程。 GOOGLE_CLIENT_ID 由所有 Google 系列连接器共用，每个连接器都会根据请求来源生成自己的回调路径。此处缺少路径会导致用户在授权时遇到 Error 400: redirect_uri_mismatch —— 登录流程正常并不能说明其他流程也正常。为每种计划使用的流程添加生产环境 URI，以及对应开发环境 URI http://localhost:8787：

     https://api.builderforce.ai/api/auth/oauth/google/callback   # 登录 / 创建账号
     https://api.builderforce.ai/api/mailbox/callback/google      # 连接收件箱（Gmail）
     https://api.builderforce.ai/api/calendar/callback/google     # Google Calendar
     https://api.builderforce.ai/api/drive/callback/google        # Google Drive
     https://api.builderforce.ai/api/youtube/callback             # 发布 YouTube 内容
     

4. 复制 Client ID 和 Client Secret：

   wrangler secret put GOOGLE_CLIENT_ID
   wrangler secret put GOOGLE_CLIENT_SECRET
   

5. OAuth consent screen → App domain —— 填写应用隐私政策链接和 应用服务条款链接。没有这些内容，Google 不会验证应用；在设置这些链接之前，授权页面会告知用户无法显示你的政策链接：

   https://builderforce.ai/legal/privacy
   https://builderforce.ai/legal/terms
   

   两者都必须是公开的、由服务器渲染的页面，并展示当前已发布的文档版本（请参阅 frontend/src/lib/legalDocs.ts —— 页面、页脚链接、信任中心导航和站点地图共用的一张路由表）。同时在 Authorized domains 下添加 builderforce.ai。

发布： 处于“Testing”模式时，只有测试用户可以登录，而且只有测试用户可以完成连接器授权，无论注册了多少个重定向 URI。准备好投入生产后，请在授权页面点击 Publish App —— email/profile/openid 是标准范围，通常会立即获批，无需人工审核；但上述 Gmail/Calendar/Drive/YouTube 范围属于敏感或受限范围，需要通过 Google 的验证审核。审核需要提供第 5 步中的隐私政策和服务条款链接，以及一段展示授权流程的演示视频。

---

LinkedIn

1. 前往 linkedin.com/developers → Create App
   • 应用名称、LinkedIn 公司主页（必填 —— 如有需要，请创建一个）、徽标
2. Auth 标签页 → Authorized redirect URLs —— 添加以下两项：

   https://api.builderforce.ai/api/auth/oauth/linkedin/callback
   http://localhost:8787/api/auth/oauth/linkedin/callback
   

3. Products 标签页 → 申请 “Sign In with LinkedIn using OpenID Connect” —— 点击 Request access（自动即时获批）。这会启用代码中使用的 openid profile email 范围。没有此权限，/v2/userinfo 端点不会返回电子邮箱地址。
4. 返回 Auth 标签页，复制 Client ID 和 Client Secret：

   wrangler secret put LINKEDIN_CLIENT_ID
   wrangler secret put LINKEDIN_CLIENT_SECRET
   

---

GitHub

1. GitHub → Settings → Developer settings → OAuth Apps → New OAuth App
   • 首页 URL：https://builderforce.ai
   • 授权回调 URL：

     https://api.builderforce.ai/api/auth/oauth/github/callback
     

2. 点击 Register application，然后点击 Generate a new client secret
3. 设置密钥：

   wrangler secret put GITHUB_CLIENT_ID
   wrangler secret put GITHUB_CLIENT_SECRET
   

本地开发： GitHub 每个应用仅允许设置一个回调 URL。请创建一个单独的 OAuth App（例如“builderforce-dev”），将其指向 http://localhost:8787/api/auth/oauth/github/callback，并在 api/.dev.vars 中使用其凭据。

---

Microsoft

1. Azure Portal → Microsoft Entra ID → App registrations → New registration
   • 支持的帐户类型：“任何组织目录中的帐户和个人 Microsoft 帐户”
   • 重定向 URI（Web）——所有 Microsoft 流程共用 MICROSOFT_CLIENT_ID，因此请为要使用的每个流程分别注册一个 URI（本地开发时添加对应的 http://localhost:8787 URI）：

     https://api.builderforce.ai/api/auth/oauth/microsoft/callback   # 登录／创建帐户
     https://api.builderforce.ai/api/mailbox/callback/microsoft      # 连接收件箱（Outlook）
     https://api.builderforce.ai/api/calendar/callback/microsoft     # Outlook Calendar
     https://api.builderforce.ai/api/drive/callback/microsoft        # OneDrive / SharePoint
     

2. Certificates & secrets → New client secret — 立即复制该值（它只会显示一次）
3. 在 Overview 页面复制 Application (client) ID
4. 设置密钥：

   wrangler secret put MICROSOFT_CLIENT_ID
   wrangler secret put MICROSOFT_CLIENT_SECRET
   

---

本地开发

本地开发时，请使用 api/.dev.vars — Wrangler 会在运行 wrangler dev 时自动加载此文件，并且该文件已加入 gitignore：

# api/.dev.vars
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
LINKEDIN_CLIENT_ID=your_linkedin_client_id
LINKEDIN_CLIENT_SECRET=your_linkedin_client_secret
GITHUB_CLIENT_ID=your_github_dev_app_client_id
GITHUB_CLIENT_SECRET=your_github_dev_app_client_secret
APP_URL=http://localhost:3000

OAuth 回调 URL 会在运行时根据传入请求的 Origin 标头生成，因此无需额外设置 API_URL 变量 — 本地会自动解析为 http://localhost:8787，生产环境则会自动解析为 https://api.builderforce.ai。

魔法链接邮件

api/src/presentation/routes/oauthRoutes.ts 中的 sendMagicLinkEmail 函数目前是一个占位实现，会将链接记录到控制台。在生产环境中使用魔法链接前，请将其接入你的邮件服务提供商（Resend、SendGrid、Mailgun 等）：

// api/src/presentation/routes/oauthRoutes.ts  ~line 253
async function sendMagicLinkEmail(to, name, token, frontendUrl) {
  const magicUrl = `${frontendUrl}/auth/magic-link?token=${encodeURIComponent(token)}`;
  // TODO: call your email provider here
}

新增的前端路由

路由	文件	用途
/auth/callback	frontend/src/app/auth/callback/page.tsx	接收 OAuth 重定向中的 ?token=JWT，保存会话并跳转
/auth/magic-link	frontend/src/app/auth/magic-link/page.tsx	调用 /api/auth/magic-link/verify，保存会话并跳转

---

与 BuilderForce Agents 集成

Developer workstation
  └─ BuilderForce Agents (self-hosted, MIT)
       ├─ 7-role agent DAG (Code, Review, Test, Debug, Refactor, Document, Architect)
       ├─ Staged diff review (accept/reject before writing to disk)
       ├─ Agent-to-agent mesh (remote:<id>, remote:auto[caps], HMAC-signed dispatch)
       ├─ Workflow telemetry → .builderforce/telemetry/ + portal timeline
       ├─ Execution lifecycle → running/completed/failed reported to portal
       ├─ Approval gate → blocks on manager decision from portal
       ├─ Skill registry → loads portal-assigned skills at startup
       ├─ Cron scheduler → executes portal-managed jobs on schedule
       └─ BUILDERFORCE_API_KEY → heartbeat → Builderforce.ai
                                                      │  ←task.assign / task.broadcast
                                                      │  ←approval.decision
                                                      │  ←cron jobs / skill assignments
                                              ┌───────▼───────┐
                                              │ Builderforce  │
                                              │  .ai          │
                                              │               │
                                              │ • Fleet view  │
                                              │ • Task assign │
                                              │ • Approvals   │
                                              │ • Audit log   │
                                              │ • AI training │
                                              │ • Registry    │
                                              │ • Cron jobs   │
                                              │ • Skills mkt  │
                                              └───────────────┘

配置 BuilderForce Agents 以建立连接（使用 npm install -g @seanhogg/builderforce-agents 或 curl -fsSL https://builderforce.ai/install.sh | bash 安装）：

export BUILDERFORCE_API_KEY=<your-api-key>
export BUILDERFORCE_URL=https://api.builderforce.ai
builderforce gateway

BuilderForce Agents 无需 Builderforce 即可完全独立运行。建立连接后，可解锁 Agent 群组可见性、带实时执行跟踪的任务分配、强制审批关卡、由门户管理的技能分配、定时 cron 执行，以及 Workforce Registry 的访问权限。

---

设备端 AI 技术栈

Builderforce.ai 基于开源的 @seanhogg/builderforce-memory 技术栈构建，用于设备端 AI：

@seanhogg/builderforce-memory-engine  (engine)
  └─ WebGPU WGSL kernels: Mamba-1 (S6), Mamba-2 (SSD), Mamba-3 (complex MIMO+ET), causal attention
        ↓
@seanhogg/builderforce-memory  (runtime)
  └─ MambaSession.create() — one-call GPU init, tokenizer, model, checkpoint, persistence
  └─ Inference routing · distillation · semantic memory · SSMAgent
        ↓
Builderforce.ai IDE
  └─ mamba-engine.ts  — Hybrid Local Brain (SSM state + IndexedDB)
  └─ agent-runtime.ts — step() → inference → confidence scoring → cloud escalation
  └─ webgpu-trainer.ts — LoRA fine-tuning pipeline (Transformers.js + WebGPU)

设备端 AI 层的运行时间复杂度为 O(n)（注意力机制为 O(n²)），适合在浏览器中持续进行低延迟状态更新和微调。

两个软件包均已发布到 npm：@seanhogg/builderforce-memory-engine（引擎）和 @seanhogg/builderforce-memory（运行时）。

跨界面语义缓存（节省 Token）

整个技术栈中最能降低成本的机制是以嵌入为键的语义缓存：当新提示词是已回答提示词的释义时，复用先前的答案，因此不会为语义重复的工作调用前沿模型。该缓存分为两层，并在不同界面间共享：

• **L1（本地，免费）：**使用设备端 SSM 嵌入，在进程内进行余弦匹配——运行于浏览器 IDE 和各个 Agent 中。
• L2（共享）：网关的 POST /v1/semantic-cache/{lookup,store}（按租户划分范围，由 KV 提供支持）。在Web 应用中回答过的释义问题可供 Agent 复用，反之亦然。

来自 @builderforce/memory 的同一可移植 SemanticCache 为这两个界面提供支持——嵌入器（设备端 SSM）和 L2 后端均采用注入方式，因此无需区分浏览器和 Node。设备端嵌入让 L1 免费；网关 L2 则将单个租户的缓存命中转化为全平台的成本节省。

混合检索与答案评估

Builderforce.ai 实现了完整的七层 Agent 技术栈——而大多数技术栈仍较为简略的两层（RAG 检索和评估）也已构建完善：

• 混合 RAG。 检索融合稠密（SSM / OpenAI 嵌入，余弦相似度）与稀疏（Okapi BM25 关键词）信号，并通过互惠排名融合进行合并，然后使用 MMR 重新排序，兼顾相关性与多样性——检索对象是通过递归分割器加重叠方式切分的文档。单独使用稠密搜索会遗漏精确词项（标识符、错误代码、罕见名称）；混合路径则能捕捉这些内容。系统可平稳降级（无嵌入 → 仅使用 BM25；无重叠 → 仅使用稠密检索）。相关功能在 @seanhogg/builderforce-memory/retrieval 中实现，零依赖（chunkText、bm25Search、reciprocalRankFusion、maximalMarginalRelevance、hybridRetrieve、MemoryStore.recallHybrid），并为 LanceDB 长期记忆扩展提供支持。
• 语义评估与漂移。 每次云端运行都会对忠实度、答案相关性和幻觉率进行评分——评分在行内完成且零成本（基于词汇分析），需要时可升级为 LLM-as-judge，通过 POST /api/eval 调用（费用经计量网关计费）。评分会保存在运行记录中；漂移监控器（均值偏移 z 分数 + 总体稳定性指数）按 (action-type × model) 比较基线窗口与近期窗口，并在质量下降时发出警报——按计划每日运行，也可通过 GET /api/eval/drift 按需运行。错误答案不再能躲在绿色仪表盘后面。

详见说明：构建 AI Agent 技术栈。

---

开源

Builderforce.ai 所基于的运行时均采用 MIT 许可证开源，并且支持派生。概览：builderforce.ai/open-source。

软件包	功能
builderforce-webcontainers	为 IDE 和画布预览提供支持的浏览器内开发运行时：实时预览、生产构建、类型检查、Node 进程、npm install 和 Shell，不需要 COOP/COEP，也没有会话上限。npm：@seanhogg/builderforce-webcontainers。
builderforce-memory	适用于任何 Agent 的持久化、可在浏览器中训练的 SSM 记忆：WebGPU Mamba 引擎、运行时、语义缓存和 Evermind 写入直通记忆，另附 MCP 服务。npm：@seanhogg/builderforce-memory。
builderforce-inference	Synapse，桌面应用和本地 AI 运行时：使用原生 bfi 引擎在你的设备上运行模型，保留私有 Evermind 记忆并托管 MCP 连接器。
builderforce-spawn	Spawn，一款通过对话来构建 Roblox 游戏并提供 Roblox Studio 桥接功能的桌面应用。

---

架构

┌─────────────────────────── Browser ──────────────────────────────┐
│                                                                   │
│  Next.js (App Router)           BuilderForce WebContainers        │
│  ┌─────────────────────┐        ┌──────────────────────────────┐ │
│  │  Monaco Editor      │◄──────►│  Dev server (esbuild-wasm)   │ │
│  │  xterm.js Terminal  │        │  Node processes · npm · bfsh │ │
│  │  Preview <iframe>   │        │  Service worker on preview.* │ │
│  │  AI Chat Panel      │        │  Virtual FS (synced to R2)   │ │
│  │  Train Panel        │        └──────────────────────────────┘ │
│  │  Agent Publish      │                                          │
│  └──────────┬──────────┘                                          │
│             │ HTTP / WebSocket                                     │
└─────────────┼────────────────────────────────────────────────────┘
              │
┌─────────────▼──────────── Cloudflare Edge ──────────────────────┐
│                                                                   │
│  API (api.builderforce.ai — Hono)    Durable Objects             │
│  ┌────────────────────────────┐      ┌──────────────────────┐   │
│  │ /api/auth  /api/tenants    │      │  AgentHostRelayDO    │   │
│  │ /api/agent-hosts /api/tasks│      │  - host mesh relay   │   │
│  │ /api/brain /api/projects   │      │  - heartbeat proxy   │   │
│  │ /api/runtime/executions    │      └──────────────────────┘   │
│  └────────────────────────────┘      ┌──────────────────────┐   │
│                                       │  CollaborationRoom   │   │
│  Worker (worker.builderforce.ai)      │  - Yjs CRDT sync     │   │
│  ┌────────────────────────────┐      │  - cursor presence   │   │
│  │ /api/projects (IDE files)  │      │  - terminal relay    │   │
│  │ /api/datasets /api/training│      └──────────────────────┘   │
│  │ /api/agents (Registry)     │                                   │
│  │ /api/ai/chat (streaming)   │      R2 Buckets                  │
│  └────────────────────────────┘      ┌──────────────────────┐   │
│                                       │ project files        │   │
│  Neon Postgres                        │ datasets (.jsonl)    │   │
│  ┌────────────────────────────┐      │ LoRA artifacts       │   │
│  │ users · tenants · projects │      │ agent packages       │   │
│  │ agent_hosts · tasks        │      └──────────────────────┘   │
│  │ agents · training_jobs     │                                   │
│  │ agent_inference_logs       │                                   │
│  │ contributors · dev_teams   │                                   │
│  │ activity_events · metrics  │                                   │
│  │ integrations · telemetry   │                                   │
│  └────────────────────────────┘                                   │
└───────────────────────────────────────────────────────────────────┘

两个 Cloudflare Workers，一个平台：

	api (api.builderforce.ai)	worker (worker.builderforce.ai)
用途	身份验证、租户、Agent 主机、任务、知识库、市场、开发分析	IDE 项目、文件、数据集、训练、协作
身份验证	JWT + 租户隔离	CORS（目前不需要身份验证）
Durable Objects	AgentHostRelayDO（主机网格中继）	CollaborationRoom（Yjs 同步）
存储	R2 UPLOADS（知识库文件、Agent 主机资源）	R2 STORAGE（项目文件、构件、数据集）

---

快速开始

本地开发

git clone https://github.com/SeanHogg/Builderforce.ai
cd Builderforce.ai

# Install deps
pnpm install          # or npm install in each sub-directory

# Configure
echo "NEXT_PUBLIC_WORKER_URL=http://localhost:8787" > frontend/.env.local
echo "NEON_DATABASE_URL=postgresql://..." > worker/.env

# Run migrations
cd worker && npm run migrate && cd ..

# Start (in separate terminals)
cd worker && npx wrangler dev     # :8787
cd frontend && npm run dev        # :3000

打开 http://localhost:3000。WebGPU 训练需要 Chrome 113+。

部署到 Cloudflare

cd api && npm run secrets:from-env && npm run deploy
# Frontend: CI/CD via .github/workflows/deploy-frontend.yml

必需的密钥： CF_API_TOKEN、CF_ACCOUNT_ID、NEON_DATABASE_URL、JWT_SECRET、OPENROUTER_API_KEY。（SDK 发布使用 npm Trusted Publishing OIDC——无需 NPM_TOKEN 密钥；见下文。）

发布： release.yml 会并行运行四个独立作业：npm 打包、API 部署、前端部署和帮助网站部署。package-npm 作业会构建、测试并发布每个公共软件包，但仅当其 package.json 版本尚未发布到 npm 时才会执行，从而确保重复运行不会产生副作用。身份验证使用 npm Trusted Publishing OIDC（NPM_TOKEN 可作为可选的初始配置备用方案）。为每个软件包配置受信任的发布方：Organization 为 SeanHogg，Repository 为 Builderforce.ai，Workflow 为 release.yml。

可选 OAuth 密钥（仅添加所需的提供方）： GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET、GITHUB_CLIENT_ID、GITHUB_CLIENT_SECRET、LINKEDIN_CLIENT_ID、LINKEDIN_CLIENT_SECRET、MICROSOFT_CLIENT_ID、MICROSOFT_CLIENT_SECRET

---

浏览器要求

功能	要求
浏览器内 IDE 运行时（BuilderForce WebContainers）	任意支持 service workers 的现代浏览器，且处于安全上下文中（https 或 localhost）。无需 COOP/COEP 标头。
WebGPU LoRA 训练	Chrome 113+
协同编辑	任意现代浏览器
CPU 回退训练	任意浏览器（通过 forceFallbackAdapter）

IDE 运行时可在当前版本的 Chrome、Edge、Firefox 和 Safari 中运行。只有 WebGPU 功能（训练、设备端推理）有各自的浏览器要求，详见上表。

---

设计系统

UI 采用 BuilderForce 深空美学风格，在 Builderforce.ai 和 BuilderForce Agents 运行时中保持一致：

令牌	深色	浅色
--bg-deep	#050810	#fcfeff
--bg-surface	#0a0f1a	#ffffff
--coral-bright	#4d9eff	#3b82f6
--cyan-bright	#00e5cc	#008f87
--font-display	Clash Display	Clash Display
--font-body	Satoshi	Satoshi

主题会保存到 localStorage('bf-theme')，并通过内联脚本在首次绘制前应用，以避免 FOUC。

---

路线图与差距登记表

计划中的里程碑（包括 PHASE 4 — 大规模多 Agent 编排）以及完整的 整合差距登记表——共 341 项（53 项已解决 · 288 项未解决，按收入影响分组），另附已归档的主题背景——现已发布在 ROADMAP.md 中。该文件是计划工作和延期问题的唯一事实来源。新增的延期问题会追加到其中。

---

Cloud Agent 类型

Builderforce 在两个执行平面上运行 Agent——本地部署（托管）和云端。只有一个 Agent 引擎（当前版本），因此 Cloud 平面只有一个Cloud Agent，它运行在两个表面之一：Durable Object 或 Node/Container。路由决策的唯一事实来源是 cloudDispatch.ts（resolveCloudSurface / cloudAgentTypeLabel）和 runtimeRoutes.ts（resolveCloudAgent）；表面列位于 ide_agents（迁移 0105 中的 runtime_surface）。引擎版本不会从数据库读取——始终使用当前版本。

Cloud 与本地部署之间有明确的边界。 Cloud Agent 仅在云端执行（所有组件都在 Cloudflare 上——Worker、Durable Object 或 Container）。Cloud Agent 绝不会被派发到客户端机器。本地部署（托管） Agent——即 agentHost，一台机器上可以运行多个——只有在明确指定某个主机时才会执行任务。请参阅 Agent 分类（[[agent-types-taxonomy]]）。

一览

Cloud Agent 表面	运行位置	是否有持久 Shell？	最适用场景
Cloud Agent（Durable Object）	durable — CloudRunnerDO，每个 alarm() 调用周期执行一个 LLM 步骤。默认表面。	否（由 CI 验证构建）	大多数云端任务：按需运行，无需常驻计算资源，可完成长时间运行任务
Cloud Agent（Node/Container）	container — 长期运行的 Cloudflare Container（AgentContainerDO）	是（run_command）	非常长时间或持续运行的任务，需要真实 Shell 来安装依赖并运行构建、测试和 lint
（本地部署托管——用于对比）	客户端机器（agentHost），仅在指定后运行	是（主机自身的机器）	使用自有机器执行；不是 Cloud Agent

Cloud Agent（Durable Object）——表面 durable

默认表面。通过 Durable Object 的 alarm() 调用周期，在云端完整运行 Claude Agent SDK 工具循环——每个周期执行一个 LLM 步骤，并在周期之间将对话状态持久化到 DO 存储中（CloudRunnerDO）。推理通过 LLM Gateway，使用租户的 BYO Anthropic 密钥。

功能

• 每个 alarm() 调用周期执行一个步骤；每个周期都是一次全新的 Worker 调用，拥有全新的 CPU/子请求预算，因此多步骤运行不会触及会终止临时 Worker 执行器的约 30 秒 waitUntil 时限。
• state.storage 中的游标是幂等性和恢复锚点——循环会从上次停止的位置准确恢复。
• 每个周期都会更新 executions.updated_at 心跳，因此孤立任务回收器会将持续运行的任务视为存活状态，只回收确实已静默的任务。
• DO 表面会为一次运行的每个周期固定使用同一个模型。

优点

• 按需无服务器——无需常驻计算资源，也无需保持预热状态。
• 能可靠处理长时间运行和驱逐；这是标准且推荐的云端表面。
• 完整的 Claude Agent SDK 循环：逐工具时间线、引导/聊天和审批关卡。

缺点

• 没有 Shell——无法自行运行构建或测试；正确性由 CI 验证，而不是由 Agent 在完成前验证。
• 每个周期都有额外开销（调度 alarm、重新加载状态），因此对于单次特别漫长、交互频繁的会话，其效率不如持久进程。
• 需要通过 Gateway 配置租户的 Anthropic 密钥。

如果缺少 CloudRunnerDO 绑定，不会回退到其他执行器——派发会解析为 unavailable，并以该原因快速失败。这里以前记录过一种在请求内运行的 Worker 执行器，作为临时回退方案；但它无法在多步骤运行中撑过约 30 秒的 waitUntil 时限，因此从未能被选用，现已移除：明确提示“未绑定执行器”的错误，胜过任务在中途悄然终止后被孤立任务回收器回收。

云端 Agent（Node/容器）——表面 container

在真实 Cloudflare Container 中运行的 Claude Agent SDK 循环，位于持久 Node 进程内（AgentContainerDO）。容器会启动一个小型 HTTP 服务；DO 是 Cloudflare-Containers 控制平面，负责启动 / 停止该服务并代理运行请求。容器驱动循环，并在每个 LLM 步骤、仓库遥测和最终 PR 时回调 Worker，因此 Worker 始终是 Gateway、用量计量和 PR 最终处理的唯一事实来源。

功能

• 真实 Shell（run_command）：克隆仓库、安装依赖、运行实际构建 / 测试 / lint，并在完成前进行验证。
• 持久进程——可持续运行极长时间的任务，无需承担逐次 tick 的开销。
• 使用 enableInternet，以便在容器内访问 Gateway + GitHub；最后一次请求后保持热状态 20m，随后休眠以停止计费。
• 这也是明确固定的主机映射到的表面（通过中继访问的长驻运行时）。

优点

• 真正的端到端验证（Agent 自行运行构建 / 测试，而不仅仅依赖 CI）。
• 最适合长时间运行、持续运行或大量依赖 Shell 的工作。

缺点

• 容器基础设施是未来计划。 在实现之前，container 运行会回退到持久 DO，因此仍会在云端执行——也就是说，目前选择此项并不会实际获得持久 Shell。
• 开销最高 / 成本最贵的表面（近乎始终运行的进程、保持热状态的计费）。
• 与持久表面一样，需要 Gateway / 租户 Anthropic 密钥。

分派时如何选择类型

resolveCloudAgent 会从 ide_agents 读取 Agent 的 runtime_surface（引擎始终使用当前版本，不会读取）；随后 resolveCloudSurface(agentSurface, hasExplicitHost) 会选择表面——明确固定的主机 ⇒ container，否则使用 Agent 选择的表面，默认值为 durable。cloudAgentTypeLabel(surface) 会生成用于运行归属标记的人类可读标签（Cloud Agent (Durable Object) / Cloud Agent (Node/Container)）。

---

LLM 表面

Builderforce 提供三种不同的 LLM 系统——它们很容易混淆，而且各自有独立的代码路径。请针对正确的系统开展工作：

#	表面	内容	状态	入口点
A	LLM Gateway	多供应商托管聊天代理（故障转移、冷却时间、按租户划分的预算）。为 IDE Brain 聊天和工作室提示词扩展提供支持。	✅ 已发布	api/src/application/llm/、DONE.md（Gateway PRD 已发布；后续工作见 ROADMAP.md）
B	自定义 LLM 支持	将用户微调后的 LoRA Agent 提供给 builderforce CLI（POST /api/agents/:id/chat）。	🟡 已编写规格说明 — P0 缺口仍待解决（见下文）	下文的“## 自定义 LLM 支持”部分
C	IDE 内的 llm 模态	在浏览器中构建 + 训练自定义模型（数据集 → WebGPU LoRA/Mamba → 发布），然后与其聊天。	🟢 云端路径已上线；本地 / 混合模式待完成	frontend/src/lib/modality.ts、frontend/src/components/LlmStudioPanel.tsx

IDE 内模态（C）的云端推理通过 Gateway（A）路由。在设备端进行的本地和混合推理（C）尚未开放，需等待 Mamba WGSL 内核和 R2 权重到位——详见《汇总缺口登记表》。

---

自定义 LLM 支持

IDE 规格参考： 仓库根目录中的 ide-architecture (1).md——Builderforce.ai IDE 架构文档（v2.0，2026 年 3 月）。

本节详细说明 Builderforce.ai 平台（IDE 前端 + Cloudflare Worker 后端）必须进行的所有更改，以全面支持通过 IDE 构建的自定义 LLM — 使微调后的 Agent 能够在生产环境中存储、提供服务、进行版本管理，并供 builderforce CLI 客户端使用。

当前状态与目标状态

当前已有的内容

组件	状态	说明
浏览器内 LoRA 训练（WebGPU）	✅	frontend/src/lib/webgpu-trainer.ts
在 R2 中存储适配器	✅	artifacts/{projectId}/{jobId}/adapter.bin
Workforce Registry（发布 / 浏览）	✅	POST /api/agents、GET /api/agents
Agent 软件包下载	✅	GET /api/agents/:id/package → v1.0 JSON
AI 聊天推理	✅	POST /api/ai/chat → Cloudflare AI / OpenRouter
Mamba State Engine（浏览器内）	✅	frontend/src/lib/mamba-engine.ts
Agent Runtime SDK（浏览器内）	✅	frontend/src/lib/agent-runtime.ts

缺少的内容

缺口	影响	优先级
没有自定义 Agent 的推理端点	builderforce CLI 无法运行训练好的 Agent	P0
推理服务端没有 LoRA 适配器加载功能	训练会生成 .bin，但没有任何服务提供它	P0
数据库 / 软件包中没有 mamba_state	v2.0 Agent 无法往返其记忆	P0
没有 CLI 身份验证令牌	CLI 无法调用 Builderforce 推理 API	P0
POST /api/ai/chat 忽略 model 字段	无法路由到 workforce-<id>	P1
没有 Agent 流式推理	CLI 需要 SSE 分块响应	P1
没有按 API 密钥进行速率限制	推理端点容易遭到滥用	P1
没有 Agent 软件包 v2.0	下载内容不包含 Mamba 状态	P1
没有按 Agent 跟踪使用情况	无法对自定义模型的使用情况计费或监控	P2
没有模型产物版本控制	无法区分不同代的适配器	P2

数据库架构变更

agents 表 — 新增列

ALTER TABLE agents
  ADD COLUMN package_version  TEXT    NOT NULL DEFAULT '1.0',
  ADD COLUMN mamba_state      JSONB,
  ADD COLUMN inference_mode   TEXT    NOT NULL DEFAULT 'base',
  --   'base'    → use base_model directly (no adapter)
  --   'lora'    → load LoRA adapter from r2_artifact_key
  --   'hybrid'  → LoRA + Mamba state injection
  ADD COLUMN request_count    INTEGER NOT NULL DEFAULT 0,
  ADD COLUMN last_used_at     TIMESTAMPTZ;

新增 cli_api_keys 表

CREATE TABLE cli_api_keys (
  id            TEXT PRIMARY KEY,
  user_id       TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
  key_hash      TEXT NOT NULL UNIQUE,
  label         TEXT,
  scopes        TEXT NOT NULL DEFAULT 'inference:read',
  last_used_at  TIMESTAMPTZ,
  request_count INTEGER NOT NULL DEFAULT 0,
  rate_limit    INTEGER NOT NULL DEFAULT 1000,
  created_at    TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  revoked_at    TIMESTAMPTZ
);

CREATE INDEX cli_api_keys_user_idx ON cli_api_keys(user_id);
CREATE INDEX cli_api_keys_hash_idx ON cli_api_keys(key_hash);

新增 agent_inference_logs 表

CREATE TABLE agent_inference_logs (
  id              TEXT PRIMARY KEY,
  agent_id        TEXT NOT NULL REFERENCES agents(id) ON DELETE CASCADE,
  cli_key_id      TEXT REFERENCES cli_api_keys(id) ON DELETE SET NULL,
  model_ref       TEXT NOT NULL,
  prompt_tokens   INTEGER,
  completion_tokens INTEGER,
  latency_ms      INTEGER,
  status          TEXT NOT NULL,
  error_message   TEXT,
  created_at      TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE INDEX agent_inference_logs_agent_idx ON agent_inference_logs(agent_id);
CREATE INDEX agent_inference_logs_key_idx   ON agent_inference_logs(cli_key_id);

新增 Worker 路由

POST /api/agents/:id/chat — Agent 推理

接受兼容 OpenAI 的聊天补全请求，解析 Agent 的 LoRA 适配器，运行推理并将令牌流式传回。

app.post("/api/agents/:id/chat", async (c) => {
  const keyId = await authenticateCliKey(c);
  if (!keyId) return c.json({ error: "Unauthorized" }, 401);

  const agent = await db.query("SELECT * FROM agents WHERE id = $1", [c.req.param("id")]);
  if (!agent) return c.json({ error: "Agent not found" }, 404);

  const body = await c.req.json<ChatRequest>();
  const result = await runAgentInference({ agent, messages: body.messages, stream: body.stream ?? false, env: c.env });

  c.executionCtx.waitUntil(logInference({ agentId: agent.id, keyId, ...result.usage, env: c.env }));
  return result.response;
});

GET/PUT /api/agents/:id/mamba-state — Mamba 状态同步

• GET — 返回存储的 Mamba 状态快照（如果有）
• PUT — 接受 CLI 会话提供的更新状态；使服务端状态与 .builderforce/memory/mamba-state.json 保持同步

POST /api/auth/cli-key — 签发 CLI API 密钥

签发一个限定用于推理的新 CLI 密钥。需要有效的 Web 令牌。rawKey 只返回一次，存储时仅保存其 SHA-256 哈希值。用户将其保存为 BUILDERFORCE_AGENTS_LINK_API_KEY。

DELETE /api/auth/cli-key/:keyId — 撤销 CLI 密钥

更新 Worker 路由

POST /api/ai/chat — Workforce 路由

检测 workforce-<agentId> 模型前缀，并将请求转交给 Agent 推理服务：

// `coderclawllm/` is the legacy prefix, still accepted for existing clients.
const workforceMatch = body.model?.match(/^(?:(?:builderforce|coderclawllm)\/)?workforce-(.+)$/);
if (workforceMatch) {
  return forwardToAgentInference(c, workforceMatch[1], body);
}
return runStandardInference(c, body);

builderforce CLI 可以使用 model: "builderforce/workforce-<agentId>"，无需更改端点。

POST /api/agents — 发布时接受 Mamba 状态

接受 mamba_state 和 package_version 字段。设置 inference_mode：

• 如果没有 r2_artifact_key，则为 "base"
• 如果存在 r2_artifact_key，但没有 mamba_state，则为 "lora"
• 如果两者都存在，则为 "hybrid"

推理服务架构

Hono Worker 按以下优先级选择推理后端：

1. r2_artifact_key IS NOT NULL AND inference service available
   → Custom inference service (LoRA adapter applied)

2. base_model matches a Cloudflare Workers AI model id
   → Cloudflare Workers AI (base model only)

3. base_model matches an OpenRouter model id
   → OpenRouter (base model only)

4. Fallback
   → Return 503 with { error: "Inference unavailable for this agent" }

LoRA 推理服务不可用时，系统会平稳降级。CLI 会在会话横幅中显示 X-Inference-Mode 标头（lora | hybrid | base | fallback-base | unavailable）。

推理服务调用路径：

builderforce CLI
    │
    ▼  POST /api/agents/:id/chat  (Hono Worker)
Cloudflare Worker (api.builderforce.ai)
    │  pre-sign R2 URL for adapter.bin (1hr TTL)
    ▼  POST https://inference.builderforce.ai/v1/lora-chat
Inference Service (GPU Worker / Durable Object)
    │  LRU-cached adapter loading, base model, LoRA application
    ▼  SSE chunks forwarded back through the Hono Worker
builderforce CLI

推荐技术栈： Rust/Axum 或 Python/FastAPI；candle 或 transformers+PEFT；SSE 流式传输；用于缓存适配器字节和已加载模型的 LRU 缓存。

BuilderForce Agents CLI 身份验证

1. builderforce init  →  link wizard
2. POST /api/auth/cli-key  { label: machineName }
3. rawKey saved to ~/.builderforce/.env as BUILDERFORCE_AGENTS_LINK_API_KEY
4. Future requests: Authorization: Bearer <rawKey>

IDE 前端变更

训练面板（AITrainingPanel.tsx）：

• 混合训练成功完成后，添加“导出 Mamba 状态”按钮
• 在已完成的任务上显示推理模式指示器：LoRA (r=8) 🧠 +Mamba → Hybrid

发布面板（AgentPublishPanel.tsx）：

• 在发布载荷中加入 Mamba 状态复选框（v2.0）
• 显示 v2.0 🧠 / v1.0 软件包版本徽标
• 显示 CLI 安装命令：builderforce agent install <agentId>

Agent 状态查看器（AgentStateViewer.tsx — 新组件）：

• 右侧面板中的 🔬 State 标签页，显示 Mamba 状态摘要、通道热力图和交互历史
• “同步到服务器”按钮，调用 PUT /api/agents/:id/mamba-state

API 参考 — 新增和变更的端点

方法	路径	身份验证	说明
POST	/api/agents/:id/chat	CLI 密钥	对自定义 Agent 运行推理（流式 SSE 或 JSON）
GET	/api/agents/:id/mamba-state	CLI 密钥	获取已存储的 Mamba SSM 状态快照
PUT	/api/agents/:id/mamba-state	CLI 密钥	从 CLI 会话推送更新后的 Mamba 状态
POST	/api/auth/cli-key	Web 令牌	签发新的 CLI API 密钥
DELETE	/api/auth/cli-key/:keyId	Web 令牌	撤销 CLI API 密钥
GET	/api/auth/cli-keys	Web 令牌	列出当前用户的所有 CLI API 密钥

方法	路径	变更
POST	/api/agents	接受请求体中的 mamba_state、package_version；设置 inference_mode
GET	/api/agents/:id/package	当存在 mamba_state 时，返回 v2.0 格式
POST	/api/ai/chat	检测 workforce-<id> 模型前缀 → 委托给 Agent 推理

端到端流程：通过自定义 LLM 进行 CLI 推理

1. [CLI] Load project context → modelRef = "builderforce/workforce-<agentId>"
2. [CLI] Advance Mamba state → memoryContext
3. [CLI] POST https://api.builderforce.ai/api/ai/chat { model, messages, stream: true }
4. [Worker] Detect workforce prefix → agentId
5. [Worker] Authenticate CLI key → check rate limit
6. [Worker] Load agent from Neon → generate pre-signed R2 URL
7. [Worker] POST https://inference.builderforce.ai/v1/lora-chat
8. [Inference] Load/cache adapter → apply LoRA → stream tokens
9. [CLI] Render tokens in TUI
10. [CLI] Persist updated Mamba state → PUT /api/agents/<agentId>/mamba-state

---

头像筛选器

头像筛选器是一项面向用户的功能，通过多个维度展示项目状态，主要通过每个项目的红—黄—绿（RAG）状态指示器来呈现。此功能可帮助利益相关者快速评估项目健康状况，并妥善安排工作优先级。

功能

功能	描述
项目状态指示器	项目以颜色标记状态： • 🟢 绿色 – 健康、进展顺利或问题已解决 • 🟡 琥珀色 – 有风险、已延迟或需要关注 • 🔴 红色 – 受阻、情况危急或需要立即采取行动
审计轨迹	每次状态变更都会记录到 audit_log，以透明呈现变更者及变更时间
列表和详情视图	可在列表、表格和详情视图中按状态筛选和排序项目；项目详情页会显示每次状态变更的原因和时间戳，并可在详情面板中查看各项目的审计记录
项目组合小组件	项目组合级小组件汇总该项目组合中所有项目的 RAG 状态，便于从高层视角审查整个项目组合的计划健康状况
通知	可按 RAG 状态类别配置通知目标项目，例如在项目状态变为琥珀色或红色时通知，或对所有有风险的项目发出提醒；用户可选择订阅，并可配置保留策略

工作原理

1. 状态分配： 根据可配置的业务规则为项目分配 RAG 状态。默认状态为绿色。状态可通过手动操作（需记录原因）或自动规则更新。
2. 审计记录： 每次状态变更都会在 audit_log 中记录 project_id、old_status、new_status、changed_by、reason 和时间戳，以便全面追踪。
3. 展示： 项目组合小组件以及看板列表和详情视图会显示当前状态和近期状态变更，并支持按状态筛选和排序。
4. 通知： 可选择特定类别（例如有风险的项目），当项目状态低于阈值时主动发送提醒，具体取决于用户的通知偏好设置。

配置选项

• 默认项目状态： 绿色（可按项目组合或租户配置）。
• 合规标记（360 指标）： 控制 360“方向”健康状况是否跟踪并显示 RAG 状态元指标。
• 情绪阈值： 决定项目何时从琥珀色转为红色的规则（例如近期问题数量、与计划的偏差或逾期任务）。
• 保留期限： 配置状态变更审计日志条目的保留时长（按租户 / 行级策略）。

实施阶段

1. 扩展架构： 扩展项目和 audit_log 记录，加入 RAG 状态字段及变更原因。
2. 业务规则和权重： 定义将项目指标（问题、偏差、逾期任务）转换为 RAG 状态的逻辑。
3. 状态变更工作流： 提供用于手动变更状态的 UI 小组件并要求填写原因，同时支持基于规则的自动状态变更。
4. 审计详情粒度： 配置每条状态审计记录的详细程度，包括规范化字段、变更摘要或自由格式备注。
5. 项目组合和看板展示： 构建列表 / 详情视图和项目组合小组件，显示 RAG 状态汇总分布并支持下钻筛选。
6. 按类别发送通知： 实现按触发条件分类的通知，用于发送有风险的计划提醒。

项目健康状况仪表板

• 列表和详情视图显示状态标签（绿色 / 琥珀色 / 红色），支持按状态筛选和排序。
• 项目详情页显示最近一次状态变更（变更者、时间和原因），以及完整的审计记录历史。
• 项目组合小组件汇总各 RAG 状态的项目数量，并支持下钻到筛选后的项目列表。
• 通知可按 RAG 状态向项目组发送，以主动监控项目健康状况。

状态转换

• 标记为琥珀色的项目，在创建可执行的整改子任务或触发事件得到解决后，可降级为绿色。
• 标记为红色的项目，在阻塞条件得到解决并通过标准工作流批准解决方案后，可恢复为绿色。
• 所有转换都会连同变更原因记录在审计日志中，确保项目健康状况决策的完整追溯记录。

---

贡献

完整的贡献指南请参阅 CONTRIBUTING.md，其中包括分支命名约定、PR 模板、代码质量门禁和拉取请求生命周期。

---

许可证

本项目基于 MIT License 许可 — 详情请参阅 LICENSE 文件。