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.
18 KiB
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
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 不进模型(四层)
- 结构隔离:key 只在
copilot-diagnostics.ts的闭包里。模型拿到的是Evidence对象,没有任何字段能装 key。 - 出口脱敏:工具结果照常过
redactSecrets。 - 固定错误文案:错误只给枚举码,不透传上游 body 和异常 message。
- 单测兜底:用假 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 追问 → 调证据 → 结论
↑______________|(证据不够就回去追问)
- 收集现象:模型先判断这是不是“东西坏了 / 结果不对”的问题。是的话,核对五要素: 谁(角色)、什么时候、在哪个页面/哪个任务、做了什么、期望 vs 实际。
- Grill-me 追问:一次只问最缺的 1
2 个,每个问题带 24 个quickReplies。例如:- “大概什么时间?” →
刚刚今天上午昨天记不清 - “方便给一下任务编号吗?在任务详情页地址栏里,以 annotation-task- 开头。”
- 问题能马上复现时:“请再点一次,然后把浏览器开发者工具里那次请求的 X-Request-ID 发给我。”(日志只保留最近 15 分钟,历史请求基本查不到,所以复现后马上查最有效) 追问最多 3 轮。到第 3 轮还缺,就带着现有证据下结论,并写明缺什么。
- “大概什么时间?” →
- 调证据:按线索选工具:
- 有任务 ID →
task_diagnosis - 有请求 ID →
request_trace - 说“很慢 / 500 / 打不开” →
cluster_overview(看 Pod 重启、未就绪、资源打满) - 说“下载慢 / 视频卡” →
egress(现在会返回未接入,照实说) - 要解释“为什么会这样” →
search_wiki查业务规则,search_code/read_file查实现
- 有任务 ID →
- 结论:三选一,由
submit_answer的新字段diagnosis.verdict表达:problem:确实有问题。kind:'bug',出诊断卡 + Wish 草稿。草稿的contextSummary自动带上证据 ID、任务 ID、请求 ID、证据时间。expected:系统按规则在工作。kind:'faq',用业务规则引文解释,不出 Wish。insufficient:证据不够。kind:'unknown',列出缺失证据和客户能补什么,可选“仍然提交给工程师”按钮(生成 Wish 草稿,标注“证据不足”)。
2.3 事实和推测分开:服务端校验
submit_answer 增加:
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/,所以:
- 在本地 WishForge 里把 droboticflow 建成平台项目,导入线上版本
e36617c0(只在平台 git service 的副本里,不动客户共享仓库)。 - 在这个副本上补一套 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命中。
- 代码工具读同一个 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)
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 定稿,前端照此接)
// 每次查看发两帧,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 拍板
- droboticflow 的 Wiki 由谁写:建议我来写(我已经读过它的 docs),Dev 负责把项目导入本地平台。
- 平台帮助页合并进 droboticflow 项目检索(第 3.3 节):本轮做,还是只回答 droboticflow?建议做,改动约 40 行。
- 限流定 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 不出现在任何工具结果、事件、落库记录和日志里。