feat(skillhub): 完善Skill多引擎用量诊断与证据归因

[NothingToDooo]

这次改了什么

摘要

Skill 用量诊断需要依据真实执行记录定位问题。原有统计对 Pi 的覆盖不完整，重复归档可能影响证据归因，首次索引的空结果又会隐藏诊断入口；创建诊断任务时也未完整沿用所选引擎的常规配置。

本 PR 完善 Claude、Codex、Pi 的日志分析、证据索引和本地化诊断草稿，区分尚无统计快照与真实零记录，并在刷新失败时保护已有有效证据。诊断入口复用常规 Agent 选择器和配置，支持索引等待、取消及重试。诊断草稿使用普通消息流程，诊断读取与其他 Skill 读取采用相同的统计规则。

变更类型

• feat 新功能
• fix 缺陷修复
• refactor / perf 重构或性能优化
• docs / test / chore 文档、测试或工程维护
• 其他：

范围

• 关联 Issue / 需求：维护者确认 #5431，涉及 Skill 用量诊断的统计口径、交互和派生缓存架构；需维护者在本 PR 正式 Approve。
• 本 PR 包含：原生任务身份与重复归档去重、文档版本和接触内容区分、Pi 来源统计、代表性证据筛选及 Pi 分支上下文保存；格式 7 的派生缓存、更新事务和刷新状态；带原始文件/行号入口的本地化诊断草稿；诊断入口的引擎配置、等待和重试；账号切换后的过期响应隔离；追加媒体附件时保留当前草稿。
• 明确不包含：服务端、Mobile UI、插件运行时、历史数据库 migration 修改，以及根据过程指标直接评定 Skill 质量。
• 用户可见变化：诊断可选择 Pi；统计显示 Pi 来源；首次索引期间可打开诊断入口并等待结果，已有快照在后台刷新期间仍可用于诊断；刷新失败保留已有有效证据；输入框保持普通草稿编辑体验。
• 是否存在 breaking change：无持久表结构或跨端消息协议变更。派生缓存保持格式 7。

保留 4 个独立提交：账号切换边界、用量证据与诊断上下文、媒体附件草稿保留、诊断入口配置与状态；每个提交均带 DCO。

UI 变化

• 平台：Windows Desktop。用户已在本分支开发版上试用并确认可以推送；未留存本次最终界面的截图或录屏。
• 引用的设计规范：docs/design-rules/DESIGN.md §4 Buttons / Select & Dropdown / Dialog & Modal，复用标准 Button、AgentSelect 和上游统一的 modal-scrim / modal-panel；外框、阴影和动画由共享样式提供，对话框保留 16px 内边距、最大 460px 宽度及视窗两侧 16px 留白。§5 Border Radius Scale / Interaction constraints，沿用标准控件的圆角与交互尺寸。§10 Light / Dark Dual-Mode Delivery Gate，新增状态使用语义 token 实现双模式；未完成 Light、Dark 分别实机目检。§11 Voice & Content，状态、错误与诊断草稿通过五种语言资源提供。

怎么验证的

自动验证

2026-10-05 将原有 4 个提交 rebase 到上游 755166499。唯一内容冲突位于诊断弹窗外观：保留上游共享 modal 样式、原有诊断交互和布局，同时更新对应样式断言。git range-diff 确认前三个提交补丁不变，第四个仅作上述适配；当前 head 为 3a4b0bb66。

pnpm --filter desktop run typecheck
结果：通过。

pnpm --filter desktop exec vitest run src/main/localDb/client/__tests__/tx.test.ts src/main/skillhub/__tests__/registerIpcUsage.test.ts src/main/skillhub/__tests__/usageAnalyzer.test.ts src/main/skillhub/__tests__/usageDiagnosisPrompt.test.ts src/main/skillhub/__tests__/usageIndexer.test.ts src/main/skillhub/__tests__/usageStore.test.ts src/renderer/features/skillhub/__tests__/SkillhubUsageDiagnosis.test.tsx src/renderer/features/skillhub/lib/__tests__/skillUsageDiagnosisSessionPrefs.test.ts src/renderer/features/skillhub/lib/__tests__/skillUsageState.test.ts src/renderer/features/skillhub/lib/__tests__/skillUsageViewModel.test.ts src/renderer/__tests__/modalSurfaceContract.test.ts src/renderer/__tests__/sessionsStoreAccountBoundary.test.tsx src/renderer/lib/__tests__/composerDraftStore.test.ts src/renderer/components/new-chat/__tests__/chatInputModelLoading.test.tsx --maxWorkers=1
结果：首次 408 项通过，1 项仍要求旧局部背景类；更新为共享 modal-panel 断言后，重跑该文件。

pnpm --filter desktop exec vitest run src/renderer/features/skillhub/__tests__/SkillhubUsageDiagnosis.test.tsx --maxWorkers=1
结果：23 项全部通过。上述最终结果去重后为 14 个文件、409 项通过。

git diff --check
结果：通过。

pnpm check:dco
结果：4 个提交均通过。

本次包含 #5431 特别提出的数据库事务 tx.test.ts（98 项）和 registerIpcUsage.test.ts（86 项）；另覆盖分析器、索引/存储、诊断提示词、入口状态/配置、账号边界、草稿附件及上游统一弹窗合同。独立复核确认上游弹窗改动完整保留，等待取消、过期结果隔离和零记录保护未变。

之前 bf1056729 的 13 文件、986 项定向测试记录属于此前版本；本次没有把未重跑项目计入上述 409 项。未执行格式检查或自动格式修复。

手工验证

• 此前 Windows、Global、隔离 dev 环境运行 bf1056729，启动命令返回 DESKTOP_DEV_VERDICT=ready，用户试用后确认可以推送。
• 本次 rebase 后尚未重新启动应用或做界面实机检查；不将此前试用表述为当前 head 的实机验证。

未执行的验证

• 未在本地运行整仓全量测试，采用影响面匹配的定向验证；完整门禁由 CI 执行。
• 未完成 macOS、Light / Dark 分别目检及三个真实引擎的完整端到端验证。
• 已按 Pi v0.85.1 / v1.0.2 官方源码核对：会话目录、JSONL version 3、身份/分支字段、原生 Skill 展开及 read/toolResult 形态兼容，现有检索和分析无需为常规路径调整。本机运行包仍为 0.85.1，此结论不等于 1.0.2 实机通过。
• Pi 1.0.2 新增的可选 codemode 嵌套读取未纳入当前曝光识别；子调用只记录名称、参数和状态，不能据此保证文件正文已进入模型上下文。参考 工具结果与 nestedCalls 类型、codemode 启用规则。该扩展默认不激活，本次未增加推测性计数或修改 Pi runtime。
• 未运行 migration replay：没有 SQL、snapshot、journal 或 companion script 变更，schema.ts 仅补充 Pi 来源的 TypeScript 枚举。

风险

风险分类

• 无已知风险
• SQLite / migration
• system prompt
• 协议兼容
• 权限 / 安全 / 用户数据
• 存量插件兼容（批准状态 / 指纹 / manifest 校验 / 安装布局 / 包格式）
• 原生层 / fingerprint / OTA
• 跨平台差异
• 其他：

影响与回滚

• 影响范围：Desktop Skill 用量派生索引、诊断任务创建、媒体附件追加及账号切换后的异步响应。
• SQLite：修改派生缓存的准备与更新事务，不变更持久表结构、不改历史 migration；从格式 6 升到 7 时清空旧派生索引并重建，不继续读取旧格式证据；重建期间可能暂时没有可用快照，入口展示等待状态。读取、解析或 stat 失败时保留已有有效证据，确认源文件已消失或没有有效证据时允许其他副本补位。原始引擎日志不修改。
• 提示词与数据：改动的是用户可编辑的诊断草稿，不修改 system prompt。诊断按用户操作读取本地证据，统计信号不被当成质量结论；账号代次检查阻止旧账号响应更新当前界面。消息、队列和重试不携带诊断用途元数据，也不按诊断用途排除统计。
• 跨平台：分析器涉及各引擎日志格式与文件路径；实际启动和手工试用在 Windows，macOS 待验证。
• 存量插件影响：无插件批准、manifest、权限、安装布局或运行时变更；媒体交接仅复用草稿附件追加入口。
• 回滚 / 降级方式：按依赖顺序逆序回退这 4 个提交并重启 Desktop。用量数据属于可重建派生缓存，可由回退版本重新索引；无需回退数据库 migration，原始任务日志保留。

提交前检查

• 已 review 完整 diff
• 每个 commit 都带 DCO 签名（git commit -s，见 DCO）
• UI 改动已在「UI 变化」注明引用的设计规范章节
• 未提交凭证、令牌或授权文件
• 已核对受影响的文档，无需修改既有权威结论
• 已确认测试结果或说明未执行原因

[greptile-apps]

Confidence Score: 2/5

[High risk] Extends database schema and alters skill usage tracking queries.

暂不建议合并；首次索引入口、重复日志替换和普通消息误带诊断用途需要先修复。

Findings

1.  首次索引隐藏诊断入口 ▶
2.  失败日志被旧副本替换 ▶
3.  普通消息继承诊断用途 ▶

Fix with agent prompt

### Issue 1
apps/desktop/src/main/skillhub/usageIndexer.ts:136
格式 7 首次建索引会先清空旧统计，而这里立即将空结果作为正常摘要返回。详情页只在使用次数大于零时显示“诊断”按钮，因此此时用户看到的是“无使用记录”，无法进入新增的索引进度和等待流程。请区分“尚无快照”与“确实没有使用记录”，并保留诊断入口。

### Issue 2
apps/desktop/src/main/skillhub/usageIndexer.ts:333-338
如果同一原生任务的较新实时日志本轮读取或解析失败，它不会进入用于比较的身份索引。随后较旧的归档副本仍可写入，并按任务身份删除原有证据。刷新虽然标为不完整，统计和证据路径却已退回旧归档。请避免失败刷新用较旧副本替换该任务的有效证据。

### Issue 3
apps/desktop/src/renderer/components/new-chat/ChatInput.tsx:5970-5974
用户在诊断草稿中全选正文、直接替换为普通任务并发送时，非空编辑仍保留原诊断用途，而发送时只排除了斜杠命令。普通用户轮因此带上目标 Skill 的诊断标记，分析器会排除该轮对 Skill 的真实使用。需要让替换诊断草稿能够取消用途，而不要求用户先清空正文。

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

本 PR 为 Claude、Codex 和 Pi 增加用量证据归因，重建派生索引，并将诊断用途从可编辑草稿传递到发送及重试流程。

• 首次建索引的空摘要会隐藏诊断入口。
• 重复日志处理和草稿用途保留仍可能导致证据回退或真实使用漏计。

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[原生任务日志] --> B[发现与身份去重]
  B --> C[格式 7 派生索引]
  C --> D[用量摘要与证据入口]
  D --> E[诊断草稿]
  E --> F[发送时写入用途标记]
  F --> A

Loading

_{Reviews (1) · Last reviewed commit: "feat(skillhub): 完善诊断入口的引擎配置与证据状态"}

[MagicLizi]

本 PR 命中维护者确认（产品 / UI 变更与技术架构调整），已在讨论 issue 中写明本次改动与确认理由：#5431

请维护者直接在本 PR 上 Approve；需要作者修改则 Request Changes 并写明要求。