wishforge-ide/docs/copilot-diagnostics-plan.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

295 lines
18 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 定位问题:诊断工具与对话流程方案
状态:Chief 已确认,按此实现。日期 2026-11-10。
范围:本轮 8 小时基础版。不做 MCP、不做集群部署、不重构执行器。
## 0. 现状(已读代码)
- 流式回答走 `apps/api/src/domain/copilot-stream.ts` 的 `answerStreaming`,最多 6 轮、15 次工具调用,结束必须调用 `submit_answer`。
- 只读工具在 `apps/api/src/domain/copilot-tools.ts`:Wiki、代码(git service)、提交记录、Run 摘要、日志(`WF_COPILOT_LOG_URL`,未配置)。结果统一过 `redactSecrets`、截断 24 KiB。
- 回答落库前有三道闸:引文逐字校验(`verifiedCitations`)、泄密检查(`leaksAnything`)、客户可见过滤(`customerSafe`)。
- `StreamEvent` 已经预留了 `card: 'diagnosis'`,前端还没渲染。
- **缺口 1:没有多轮上下文。** `answerStreaming` 只把当前这一句发给模型(copilot-stream.ts 第 335 行),追问后模型不记得前一句。Grill-me 必须先补上。
- **缺口 2:没有线上证据。** 只读诊断包(`.wishforge/diagnostics/fanyu-agent-readonly-kit/`)还没接进来。`capabilities` 实测:v2,`tasks`、`logs` 已配置,`egress` 未接入,`mutations: false`。
- **缺口 3:droboticflow 仓库没有 `wiki/`。** 业务规则散在它的 `docs/`(如 `annotation-five-rules.md`、`annotation-boundaries.md`、`account-management-permissions.md`)。
## 1. 服务端诊断工具
### 1.1 新模块 `apps/api/src/domain/copilot-diagnostics.ts`
```ts
export type Evidence = {
id: string; // ev-1, ev-2…:本次回答内唯一,模型下结论时要引用它
tool: 'cluster_overview' | 'task_diagnosis' | 'request_trace' | 'egress';
available: boolean; // false = 拿不到,不是“正常”
observedAt?: string; // 接口返回的采集时间
subject?: string; // 任务 ID / 请求 ID / “全部节点”
facts: string[]; // 服务端从返回值里提炼的事实句子,不是模型写的
limitations: string[]; // 接口自带 limitations + 我们固定补充的覆盖范围说明
error?: 'unavailable' | 'rate_limited' | 'not_found' | 'invalid_id' | 'auth_failed';
};
export interface Diagnostics {
clusterOverview(): Promise<Evidence>;
task(taskId: string): Promise<Evidence>;
trace(requestId: string): Promise<Evidence>;
egress(): Promise<Evidence>;
}
export function fanyuDiagnostics(env: NodeJS.ProcessEnv): Diagnostics | undefined;
```
四个模型工具,一一对应:
| 工具 | 上游路径 | 入参校验 | 服务端整理成的事实 |
| --- | --- | --- | --- |
| `cluster_overview` | nodes + pods + node-usage + pod-usage | 无入参 | 节点可分配/使用率;未就绪、Pending、重启次数 >0 的 Pod;镜像版本;各自 observedAt |
| `task_diagnosis` | `tasks/{id}` | `^annotation-task-[A-Za-z0-9_-]{1,100}$` | 任务/条目/校验状态、尝试次数、错误类别、最近事件(≤20 条) |
| `request_trace` | `logs/api/{requestId}` | `^[a-f0-9]{32}$` | 匹配到的结构化请求记录:时间、路径模板、状态码、耗时 |
| `egress` | `egress` | 无入参 | 现在固定 503 → `available:false`,说明“带宽监控未接入,不代表零流量” |
`cluster_overview` 四个接口在服务端合并成一次工具调用,算 1 次工具、4 次上游请求。只返回提炼后的摘要,不把原始 JSON 整个塞给模型。
### 1.2 key 加载
- 只认一个环境变量:`WF_DIAGNOSTIC_KIT_DIR`(本地指向 `.wishforge/diagnostics/fanyu-agent-readonly-kit`)。也可分别用 `WF_DIAGNOSTIC_KEY_FILE`、`WF_DIAGNOSTIC_CA_FILE`。base URL 用 `WF_DIAGNOSTIC_BASE_URL`,默认 `https://120.48.180.80/agent`。
- key 在第一次调用时由服务端从**文件路径**读入,存在模块闭包里。不放进 `process.env`,不进 `ToolContext`,不进日志、错误信息、审计记录。
- 未配置任何一项 → `fanyuDiagnostics` 返回 `undefined`,四个工具不出现在工具列表里,模型也就不会调用。
- TLS:用 `node:https` 带 `ca` 选项校验,不关证书校验;不跟随重定向(3xx 当失败);超时 15 s;响应上限 1 MiB。
- 只对开了诊断的项目生效:`WF_COPILOT_DIAGNOSTICS_PROJECTS=<projectId,...>`(本轮只放 droboticflow 项目)。
### 1.3 限流
- 进程内令牌桶:**每分钟 40 次**(上限 60,这个 key 是多个 agent 共用的,留余量),并发 2。
- 拿不到令牌 → 直接返回 `error:'rate_limited'`,不排队等。模型照实告诉客户“查询太频繁,稍后再试”。
- 不做 ID 枚举:一次回答里 `task_diagnosis` 和 `request_trace` 各最多 3 次,超出返回固定提示。
### 1.4 缓存
| 资源 | TTL | 说明 |
| --- | --- | --- |
| nodes / pods / usage | 30 s | 上游本来就 30 s 刷新一次 |
| tasks / logs | 15 s | 上游也缓存 15 s,失败结果同样缓存 |
| egress | 60 s | 失败也缓存,避免每次都打一遍 503 |
同一个 key 的并发请求合并成一次(single-flight)。
### 1.5 错误处理
| 上游 | 处理 |
| --- | --- |
| 401 / 403 | 不重试。`auth_failed`,记 warn 日志(只记状态码),整个进程熔断 10 分钟 |
| 404 | `not_found`(任务不存在或已删除)。说明“查不到不等于没发生” |
| 400 | `invalid_id` |
| 429 | 等 15 s 重试 1 次,再不行 `rate_limited` |
| 503 / 网络错误 / 超时 | 等 15 s 重试 1 次,再不行 `available:false, error:'unavailable'`,limitations 写“证据暂时拿不到,不能当成正常” |
一次回答整体预算 240 s,重试最多吃掉 30 s,够用。
503 一律映射成 `available:false`。不允许把它整理成“0 个异常”之类的事实句子,单测覆盖这一点。
### 1.6 key 不进模型(四层)
1. **结构隔离**:key 只在 `copilot-diagnostics.ts` 的闭包里。模型拿到的是 `Evidence` 对象,没有任何字段能装 key。
2. **出口脱敏**:工具结果照常过 `redactSecrets`。
3. **固定错误文案**:错误只给枚举码,不透传上游 body 和异常 message。
4. **单测兜底**:用假 key `fake-key-0123456789abcdef0123456789abcdef` 跑全流程,断言它不出现在:工具结果、所有 `StreamEvent`、`copilot_session`、`copilot_provider_request`、`console.warn` 输出。
另外把 `deniedToolPath` 加上 `diagnostics`、`agent.key`、`ca.crt`,代码工具碰都碰不到诊断包目录。
### 1.7 审计
沿用 `ToolAudit`:工具名、参数 hash,`detail` 里只放任务 ID / 请求 ID(不是秘密),供事后复盘。
## 2. 「定位问题」的对话流程
### 2.1 先补多轮上下文
`answerStreaming` 增加 `history` 入参:本会话最近 **10 条**已完成消息(用户原话 + 助手 `content`,再附上上一轮的诊断摘要:已取证据的 ID、结论、缺失项)。
**不回放上一轮的原始工具结果**,省 token,也避免旧证据被当成新证据。
### 2.2 四个阶段
```
收集现象 → Grill-me 追问 → 调证据 → 结论
↑______________|(证据不够就回去追问)
```
1. **收集现象**:模型先判断这是不是“东西坏了 / 结果不对”的问题。是的话,核对五要素:
谁(角色)、什么时候、在哪个页面/哪个任务、做了什么、期望 vs 实际。
2. **Grill-me 追问**:一次只问最缺的 1~2 个,每个问题带 2~4 个 `quickReplies`。例如:
- “大概什么时间?” → `刚刚` `今天上午` `昨天` `记不清`
- “方便给一下任务编号吗?在任务详情页地址栏里,以 annotation-task- 开头。”
- 问题能马上复现时:“请再点一次,然后把浏览器开发者工具里那次请求的 X-Request-ID 发给我。”(日志只保留最近 15 分钟,历史请求基本查不到,所以复现后马上查最有效)
追问最多 **3 轮**。到第 3 轮还缺,就带着现有证据下结论,并写明缺什么。
3. **调证据**:按线索选工具:
- 有任务 ID → `task_diagnosis`
- 有请求 ID → `request_trace`
- 说“很慢 / 500 / 打不开” → `cluster_overview`(看 Pod 重启、未就绪、资源打满)
- 说“下载慢 / 视频卡” → `egress`(现在会返回未接入,照实说)
- 要解释“为什么会这样” → `search_wiki` 查业务规则,`search_code` / `read_file` 查实现
4. **结论**:三选一,由 `submit_answer` 的新字段 `diagnosis.verdict` 表达:
- `problem`:确实有问题。`kind:'bug'`,出诊断卡 + Wish 草稿。草稿的 `contextSummary` 自动带上证据 ID、任务 ID、请求 ID、证据时间。
- `expected`:系统按规则在工作。`kind:'faq'`,用业务规则引文解释,不出 Wish。
- `insufficient`:证据不够。`kind:'unknown'`,列出缺失证据和客户能补什么,可选“仍然提交给工程师”按钮(生成 Wish 草稿,标注“证据不足”)。
### 2.3 事实和推测分开:服务端校验
`submit_answer` 增加:
```ts
diagnosis?: {
verdict: 'problem' | 'expected' | 'insufficient';
facts: { text: string; evidenceId: string }[]; // 必须引用本轮工具返回的 evidence id
hypotheses: { text: string; confidence: 'high' | 'medium' | 'low' }[];
missing: string[];
}
```
服务端照 `verifiedCitations` 的思路做 `verifiedFacts`:
- `evidenceId` 不在本轮证据账本里,或那条证据 `available:false` → 这条“事实”降级为推测(`confidence:'low'`)。
- `verdict:'problem'` 但一条已核实事实都没有 → 降级为 `insufficient`。
- `verdict:'expected'` 必须至少有一条核实过的 Wiki 引文,否则降级为 `insufficient`。
- 所有 `available:false` 的证据,自动加进 `missing`(如“带宽监控未接入”“日志只覆盖前两个 API Pod、最近 15 分钟”)。
- 证据时间(`observedAt`)由服务端从账本里填,不信模型写的时间。
这样“已观察到的事实”永远来自接口,模型只能组织语言、不能造事实。
### 2.4 提示词补充(加在 `TOOL_GUIDANCE` 后,仅诊断项目)
- 客户反馈异常时,先按五要素核对;缺任务编号或时间,先问,别急着下结论。
- 线上证据工具只读,只查客户给出的编号,不猜编号。
- 返回“拿不到”的证据,绝不能说成“正常”或“没有问题”。
- 当前任务状态不能证明历史上第一次失败的原因;接口延迟不能单独证明是数据库或带宽问题。
- 结论里用“已确认”“可能”区分事实和推测。
注意:`SYSTEM` 禁止出现“集群”“命名空间”,诊断卡里来源写成“线上任务记录”“线上请求记录”“线上资源情况”“带宽监控”。
## 3. droboticflow 的问题怎么答
### 3.1 资料来源
客户可见范围不变:`wiki/index.md`、`wiki/features/**`、`wiki/glossary/**`。
droboticflow 仓库本身没有 `wiki/`,所以:
1. 在本地 WishForge 里把 droboticflow 建成平台项目,导入线上版本 `e36617c0`(只在平台 git service 的副本里,不动客户共享仓库)。
2. 在这个副本上补一套 Wiki(一次提交):
- `wiki/index.md`:产品简介和页面导航
- `wiki/glossary/business-rules.md`:从 `docs/annotation-five-rules.md`、`annotation-boundaries.md`、`account-management-permissions.md` 等提炼的业务规则(送检、验收、领取、作废切片、角色权限)
- `wiki/features/*.md`:标注、送检、验收、看板各一页
规则写成可逐字引用的短句,方便 `verifiedCitations` 命中。
3. 代码工具读同一个 ref,Wiki 和代码不会错版本。
### 3.2 回答策略
- **规则类**(“为什么不能领这个任务”“验收怎么算时长”):先 `search_wiki` 找业务规则,带逐字引文,`kind:'faq'`。
- **现象类**(“送检后任务回退了”):走第 2 节诊断流程;规则用来判断是 `expected` 还是 `problem`。
- **规则文档没写**:再 `search_code` / `read_file` 看实现。回答里只说行为,不提文件和函数。没有 Wiki 引文的 faq 会被降级为 unknown,同时记入 `wiki_gap`,作为下次补 Wiki 的清单。这是现有机制,不用改。
### 3.3 WishForge 平台用法问题
本仓库的 `wiki/features/**` 是平台说明,但 Copilot 按项目取 Wiki,droboticflow 项目里查不到。
建议:服务端启动时读本仓库的 `wiki/index.md`、`wiki/features/**`、`wiki/glossary/**`,作为只读的“平台帮助”页合并进检索,路径前缀 `platform:`。引文同样逐字校验,来源显示“平台帮助”,不链到项目 Wiki 页。(需要 Chief 拍板,见第 6 节第 2 条)
## 4. 契约改动(`packages/contracts/src/copilot.ts`)
```ts
export type CopilotEvidenceSource = 'task' | 'trace' | 'cluster' | 'egress';
export type CopilotEvidence = {
id: string;
source: CopilotEvidenceSource;
label: string; // “线上任务记录”等,给客户看
subject?: string; // 任务 ID / 请求 ID
available: boolean;
observedAt?: string;
};
export type CopilotDiagnosis = {
verdict: 'problem' | 'expected' | 'insufficient';
facts: { text: string; evidenceId: string }[];
hypotheses: { text: string; confidence: 'high' | 'medium' | 'low' }[];
missing: string[];
evidence: CopilotEvidence[];
};
// CopilotMessage 增加:
// diagnosis?: CopilotDiagnosis;
```
`copilotMessageInput.context` 增加可选的 `taskId`、`requestId`(同样的正则校验):页面能拿到时由前端带上,模型不用再问。
`kind` 枚举不变,老会话和现有测试不受影响。
流式事件不新增类型:
- `tool_use.progress` 新增四句:`正在查看任务状态…`、`正在查找这次请求的记录…`、`正在查看线上运行情况…`、`正在查看带宽情况…`
- `card` 用已有的 `cardType:'diagnosis'`,`object` 为 `CopilotDiagnosis`,在 `wish` 卡之前发
- `done.summary` 带上 `diagnosis`
### 4.1 SSE 帧(11-10 定稿,前端照此接)
```ts
// 每次查看发两帧,stepId 相同
{ type:'tool_use', stepId:'step-1', phase:'start', name, progress }
{ type:'tool_use', stepId:'step-1', phase:'end', name, progress,
outcome:'ok'|'missing'|'failed', evidenceId?:'ev-1', observedAt?:string }
// 线上证据拿不到(503、过期、查无)一律 outcome:'missing',不能画成绿勾
{ type:'card', cardType:'diagnosis', object: CopilotDiagnosis } // 在 wish 卡之前
{ type:'done', summary:{ ..., diagnosis? } }
{ type:'error', code, message }
// code: rate_limited | upstream_unavailable | upstream_refused | timeout
// | no_answer | not_configured | not_found | invalid_input | internal
```
刷新后从 `CopilotMessage.diagnosis` 恢复。步骤列表不落库,只在流式时显示。
没有 `thinking` 帧(11-10 Chief 决定):模型推理会复述内部规则和猜测,只留在服务端交回模型,不下发给客户。
## 5. 前端展示(`apps/web/src/features/copilot.tsx`)
新增 `DiagnosisCard`,位置在回答正文之下、Wish 卡之上:
```
┌ 诊断结论 ─────────────── [发现问题 | 符合规则 | 证据不足] ┐
│ 已确认 │
│ • 任务 annotation-task-xxx 校验失败,第 5 次尝试, │
│ 错误类别 imu_invalid [线上任务记录 · 09:41] │
│ 可能的原因 │
│ • 送检保存时与其他写入冲突(中) │
│ 还缺的证据 │
│ • 当时那次请求的记录(日志只保留最近 15 分钟) │
└────────────────────────────────────────────────────────────┘
```
- 结论徽标三色:发现问题(红)、符合规则(绿)、证据不足(黄)。
- 每条事实后面挂来源 chip:来源名 + 本地时间;`available:false` 的来源灰掉,悬停提示“暂时拿不到,不代表正常”。
- 推测用浅色、带“高/中/低”。
- `insufficient` 时底部给两个按钮:`我去补充信息`(聚焦输入框)、`仍然交给工程师`(展开 Wish 草稿)。
- 进度行复用现有 `copilot-progress`,显示上面四句中文。
- 刷新后从 `message.diagnosis` 恢复,和 Wish 卡一致。
## 6. 需要 Chief 拍板
1. droboticflow 的 Wiki 由谁写:建议我来写(我已经读过它的 docs),Dev 负责把项目导入本地平台。
2. 平台帮助页合并进 droboticflow 项目检索(第 3.3 节):本轮做,还是只回答 droboticflow?建议做,改动约 40 行。
3. 限流定 40 次/分钟(共享 key 留 1/3 给其他 agent),是否可以。
## 7. 实现顺序与时间
| 步骤 | 内容 | 预计 |
| --- | --- | --- |
| 1 | `copilot-diagnostics.ts`:key 加载、TLS、令牌桶、缓存、错误映射 + 单测 | 60 分钟 |
| 2 | 四个工具接入 `copilot-tools.ts`;`deniedToolPath` 补诊断包目录 | 20 分钟 |
| 3 | `answerStreaming` 加 `history`;证据账本;`submit_answer.diagnosis`;`verifiedFacts` + 单测 | 60 分钟 |
| 4 | 契约 + 落库 + `card:'diagnosis'` 事件 | 20 分钟 |
| 5 | droboticflow Wiki 补页(依赖 Dev 导入项目) | 40 分钟 |
| 6 | 前端 `DiagnosisCard` | 45 分钟 |
| 7 | 用 case-1 跑真实对话,截图贴群 | 30 分钟 |
验证只跑 `npm run typecheck` 和相关单测:`tests/copilot-diagnostics.test.ts`(新增)、`tests/copilot.test.ts`、`tests/copilot-security.test.ts`。
## 8. 验收
- 用 `.wishforge/cases/case-1.md` 的客户原话开场,Copilot 追问不超过 3 轮,至少调一次线上证据工具。
- 诊断卡里“已确认”每条都有来源和时间;拿不到的证据出现在“还缺的证据”里。
- 结论大致定位到 case-1 后来的真实结论;如果是 `problem`,确认后创建出真实 Run 链接。
- 假 key 单测通过:key 不出现在任何工具结果、事件、落库记录和日志里。