wishforge-ide/docs/copilot.md
wishforge 5855d5a43c
Some checks failed
CI / Format, types and tests (pull_request) Has been cancelled
CI / PostgreSQL migrations and integration tests (pull_request) Has been cancelled
CI / IDE gateway, collaboration and policy tests (pull_request) Has been cancelled
✨ Render diagnosis cards, tool steps, safe Markdown, and editable Wish drafts
Display structured Copilot diagnoses with verdict badges, server-stamped evidence chips, confidence-tagged hypotheses, missing-evidence callouts, and an explicit handoff path when evidence is insufficient.

Add progressive start/end tool step rows, path-scrubbed Markdown rendering via react-markdown and remark-gfm, typed stream error banners, sticky-threshold auto-scroll, copy actions, Grill-me choice previews, editable Wish drafts, and the accompanying design and operations docs.
2026-11-11 07:59:03 -08:00

7.2 KiB
Raw Permalink Blame History

项目 Copilot

主控制台右上角的 AI Copilot 是常驻右侧入口。侧栏的展开/收起状态保存在浏览器中,项目详情页自动绑定当前项目,其他主页面可选择项目。每个项目的会话分别保存,刷新或导航后继续恢复。

用户入口

  1. 打开 http://127.0.0.1:3000/projects,点击右上角 AI Copilot。
  2. 直接询问 FAQ 或配置问题。回答分为「FAQ / 配置」「疑似 Bug」「需求」「依据不足」,有依据的回答必须带回逐字校验过的 Wiki 引文,并附页面和 Git 知识版本;点击来源可核对当前分支原文。回答不出现源码路径或行号。
  3. 疑似 Bug 的回答包含复现信息与当前上下文摘要。需求回答可包含由 Wiki 支撑的 Grill-me 选项卡片;选择会进入可编辑的 Wish 目标和验收标准。
  4. 检查草稿后点击 确认并创建 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 登录:

  1. 平台方的模型连接:在「模型连接」里为租户保存 Claude Code 的 Key(POST /v1/provider-connections,需要 owner/admin;Key 加密后存 provider_connection,接口只返回公开字段)。服务端解密后以 ANTHROPIC_API_KEY 交给 CLI,网关取 WF_ANTHROPIC_BASE_URL;每次回答使用一个临时空 HOME,不读任何 settings。
  2. 本机登录(仅开发):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 代码不直接读它,生产部署也不依赖它。

线上诊断(只读)

开了诊断的项目,Copilot 在客户反馈异常时会先追问,再查线上证据,最后给出诊断卡:结论(发现问题 / 符合规则 / 证据不足)、已确认的事实(每条带来源和证据时间)、推测和还缺的证据。设计见 docs/copilot-diagnostics-plan.md。

设置 作用
WF_DIAGNOSTIC_KIT_DIR 只读诊断包目录,服务端从里面按文件读 agent.key 和 ca.crt;也可用 WF_DIAGNOSTIC_KEY_FILE、WF_DIAGNOSTIC_CA_FILE 分别指定
WF_DIAGNOSTIC_BASE_URL 诊断网关地址,默认 https://120.48.180.80/agent
WF_COPILOT_DIAGNOSTICS_PROJECTS 逗号分隔的项目 ID;只有这些项目的 Copilot 能看到诊断工具
  • key 只在服务端模块内部,不进环境变量、提示词、工具结果、日志或回答。
  • 每分钟最多 40 次(共享 key 留余量),并发 2;资源快照缓存 30 秒,任务和请求记录缓存 15 秒。
  • 429、503 和网络错误等 15 秒重试一次,仍失败就记为「拿不到」,不会当成正常;401/403 不重试,暂停 10 分钟。
  • 请求记录只保留最近 15 分钟。查不到时,诊断卡会提示客户复现并记下 X-Request-ID。

运行与验证

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 或部署。