wishforge-ide/docs/copilot.md

74 lines
6.0 KiB
Markdown
Raw 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 代码不直接读它,生产部署也不依赖它。
## 运行与验证
```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 或部署。