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.
295 lines
18 KiB
Markdown
295 lines
18 KiB
Markdown
# 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 不出现在任何工具结果、事件、落库记录和日志里。
|