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

18 KiB
Raw Blame History

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 不进模型(四层)

  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 追问:一次只问最缺的 12 个,每个问题带 24 个 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 增加:

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)

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 拍板

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