6.0 KiB
项目 Copilot
主控制台右上角的 AI Copilot 是常驻右侧入口。侧栏的展开/收起状态保存在浏览器中,项目详情页自动绑定当前项目,其他主页面可选择项目。每个项目的会话分别保存,刷新或导航后继续恢复。
用户入口
- 打开
http://127.0.0.1:3000/projects,点击右上角 AI Copilot。 - 直接询问 FAQ 或配置问题。回答分为「FAQ / 配置」「疑似 Bug」「需求」「依据不足」,有依据的回答必须带回逐字校验过的 Wiki 引文,并附页面和 Git 知识版本;点击来源可核对当前分支原文。回答不出现源码路径或行号。
- 疑似 Bug 的回答包含复现信息与当前上下文摘要。需求回答可包含由 Wiki 支撑的 Grill-me 选项卡片;选择会进入可编辑的 Wish 目标和验收标准。
- 检查草稿后点击 确认并创建 Wish。草稿会像手写愿望一样先经过 AI 优化;优化不可用时不创建 Wish,直接报错。提交沿用现有权限与幂等机制(键为
copilot:<sessionId>:<messageId>,同一答案改过草稿重试会返回IDEMPOTENCY_CONFLICT),返回/runs/<runId>真实链接。新 Wish 的预算取项目的defaultBudget,未设置时用平台默认值。FAQ 和依据不足的回答不会自动创建 Wish。
依据与缺口
- 客户可见范围只有
wiki/index.md、wiki/features/**、wiki/glossary/**;wiki/modules/**是代码地图,不参与检索、不进提示词、不作为来源。 - 每条 FAQ 必须带至少一条逐字引文(允许换行差异),引文不在被引页面里就降级为「依据不足」。
- 回答、Wish 草稿和来源摘要都会过滤源码路径与行号;Wiki 页面里的代码引用不会回传给客户。
- 「依据不足」的问题记入
wiki_gap(GET /projects/:id/wiki-gaps),作为下一次补 Wiki 的清单。
实现入口
apps/web/src/features/copilot.tsx:常驻侧栏、会话恢复、来源、分流和 Wish 确认交互。apps/web/src/components/console-shell.tsx:主控制台入口与跨页面展开状态。apps/web/src/features/wiki-source.tsx:Wiki 页面核对页。apps/api/src/domain/copilot.ts:用户项目会话、受控模型问答、结构化分流、幂等转 Wish。apps/api/src/domain/project-wiki.ts:项目鉴权、客户可见范围、路径白名单、Wiki 检索来源及版本校验;WikiReader接口留给自带仓库 Wiki 的项目(ExternalWikiReader目前报WIKI_UNAVAILABLE)。apps/git-service/src/service.ts:管理鉴权的 Git 目标分支 Wiki 读取(只读wiki/**.md,拒绝软链)。packages/contracts/src/copilot.ts:会话、来源、卡片及请求契约。
模型与凭据
Copilot 和愿望优化走同一个模型通道:每次调用都显式带 --model,同时设置 ANTHROPIC_MODEL 与 ANTHROPIC_SMALL_FAST_MODEL,不会继承本机 ~/.claude/settings.json 里选的模型。
| 设置 | 作用 | 默认 |
|---|---|---|
WF_COPILOT_MODEL |
Copilot 回答与愿望优化使用的模型 | deepseek-flash@latest |
WF_CLAUDE_ASK_MODEL |
同一设置的旧名,仍可用;WF_COPILOT_MODEL 优先 |
— |
WF_CLAUDE_ASK_FALLBACK_MODEL |
愿望优化首次超时或返回的 JSON 不可用时的兜底模型 | deepseek-pro@latest |
WF_ANTHROPIC_BASE_URL |
Claude Code 使用的 Anthropic 兼容网关 | 官方地址 |
WF_CLAUDE_BIN |
claude 可执行文件;没有它 Copilot 和优化都不可用 |
— |
凭据按下面的顺序取得,生产不读机器的本地 Claude 登录:
- 平台方的模型连接:在「模型连接」里为租户保存 Claude Code 的 Key(
POST /v1/provider-connections,需要 owner/admin;Key 加密后存provider_connection,接口只返回公开字段)。服务端解密后以ANTHROPIC_API_KEY交给 CLI,网关取WF_ANTHROPIC_BASE_URL;每次回答使用一个临时空HOME,不读任何 settings。 - 本机登录(仅开发):
WF_DEPLOYMENT_MODE=development、WF_PROVISIONER_BACKEND=local、WF_TENANT_ID与该租户一致时,可用WF_CLAUDE_LOCAL_AUTH_HOME下的登录,作为本地调试的方便路径。
生产要能解密模型连接,必须配置 Vault transit(HTTPS 的 VAULT_ADDR、VAULT_TOKEN、VAULT_TRANSIT_KEY):生产拒绝本地信封。没有任何可用凭据时,回答返回 503 COPILOT_UNAVAILABLE,转 Wish 返回 503 REFINER_UNAVAILABLE,不会把未优化的草稿交给执行器。
集群 POC 的 Secret wishforge-claude 由容器入口复制成 claude-home-api/.claude/settings.json,只服务上面第 2 条的本机登录路径(POC 是 development 模式);Copilot 代码不直接读它,生产部署也不依赖它。
运行与验证
npm run dev:all
npm run typecheck
npx vitest run tests/copilot.test.ts apps/git-service/test/service.test.ts
node --check scripts/copilot-e2e.mjs scripts/copilot-smoke.mjs
HTTP 冒烟(不需要浏览器,也不需要本机模型;可对预发或线上地址执行):
WF_API_URL=http://127.0.0.1:4000 WF_API_TOKEN=… WF_PROJECT_ID=… node scripts/copilot-smoke.mjs
它先确认部署报告 Copilot 可用,再问一个 FAQ 问题、一个 Bug 问题,并断言回答的 kind、来源只在 wiki/index.md、wiki/features/**、wiki/glossary/**、回答里没有源码路径,最后把 Bug 草稿转成 Wish。转 Wish 会真实创建一次运行,但不会 push、创建 PR 或部署;令牌从环境变量读取,不会打印。
真实浏览器闭环(需要已启动的本地环境、可用 Claude 模型和 agent-browser):
node scripts/copilot-e2e.mjs
可用 WF_WEB_URL 指定 Web 地址,COPILOT_E2E_PROJECT_ID 固定要验收的平台项目,COPILOT_E2E_ARTIFACTS 指定截图目录。脚本实际执行 FAQ 直接答复、Bug 确认转 Wish、需求 Grill-me 选择转 Wish,并检查导航后的展开状态和历史恢复;它会创建两个真实 Wish,不会 push、创建 PR 或部署。