# 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; task(taskId: string): Promise; trace(requestId: string): Promise; egress(): Promise; } 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=`(本轮只放 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 不出现在任何工具结果、事件、落库记录和日志里。