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.
89 lines
7.2 KiB
Markdown
89 lines
7.2 KiB
Markdown
# 项目 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 或部署。
|