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

89 lines
7.2 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 项目 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。
## 运行与验证
```bash
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 冒烟(不需要浏览器,也不需要本机模型;可对预发或线上地址执行):
```bash
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`):
```bash
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 或部署。