stk-report

# SKILL: stk-report 本 SKILL 指导 AI Agent 执行 `/stk-report`，量化本次 Token 优化的前后对比与任务效果。 ## 目标 基于优化前/后两份 proxy 结构化诊断报告（`DiagnosisReport` JSON），量化优化节省，并按分类归因、标注变化，产出可程序化消费的对比报告。 ## 数据源 对比源为 **proxy 透明代理采集的诊断报告**（由 `stk diagnose` 拦截真实请求产出）： - 优化前：`save-token/diagnosis-report.md`（`stk diagnose` 首次采集） - 优化后：`save-token/diagnosis-report2.md`（优化后运行 `stk diagnose --report-path=./save-token/diagnosis-report2.md` 产出） > 注：`stk diagnose` 默认同时写 `diagnosis-report.json`（结构化）+ `diagnosis-report.md`（Markdown）。但优化后用 `--report-path` 重定向时，**JSON 仍覆盖写回 `save-token/diagnosis-report.json`**，会冲掉优化前基线。因此对比统一以两份 **Markdown** 报告为准：优化前 `diagnosis-report.md`、优化后 `diagnosis-report2.md`。 ## 执行流程 1. **采集优化后报告（必须）**：运行 `stk diagnose --report-path=./save-token/diagnosis-report2.md`，通过 proxy 透明代理拦截真实请求，产出优化后诊断报告 `diagnosis-report2.md`。此步是后续分析的前提，不可跳过。 - 仅当 `diagnosis-report2.md` 已存在且用户要求复用（如 `--no-diagnose`）时，可跳过重新采集。 2. 读取文件（路径见数据源）：优化前 `diagnosis-report.md`、优化后 `diagnosis-report2.md`。Markdown 解析失败报具体文件与位置，**不崩溃**。 3. **缺失数据引导**（不臆造）： - 缺 `diagnosis-report.md`（前）→ 提示"缺少优化前诊断基线，请先运行 `stk diagnose` 采集"，退出不写报告。 - 缺 `diagnosis-report2.md`（后）→ 提示"缺少优化后诊断报告，请先运行 `stk diagnose --report-path=./save-token/diagnosis-report2.md` 采集"，退出不写报告。 4. 从两份 Markdown 解析： - 总 Token：定位"总 Token / 总估算 Token"行，取数值。 - 分类明细：解析类别表格（System Prompt / Tools / Skills / Memory / Messages / Rules / Hooks 等），提取每类 `estimatedTokens`。 - 得出 `beforeTotalTokens` / `afterTotalTokens`。 5. 计算差值： - `totalSavedTokens` = 前 - 后；`savingsPercentage` = 节省 / 前 - 分类 `TokenChange`：`beforeTokens` / `afterTokens` / `deltaTokens`（负=节省）/ `deltaPercentage`（按类别对齐；报告无某类时按 0 处理） 6. 任务效果归因（基于 `tasks.md` 中的复选框状态 + 优化前报告实测占用）： - 读取 `tasks.md`，按已完成（`- [x]`）与未完成（`- [ ]`）判断每条任务状态。 - **预估必须来自优化前报告实测，禁止照搬 `tasks.md` 里的文案数字**： - `tasks.md` 中的"预估节省 ~XXX Token"是分析阶段粗估，常偏高（如禁用某插件被估 1000，实际仅移除该 skill 的 name+description 常驻占用）。报告一律**忽略该文案数字**，改为从优化前 `diagnosis-report.md` 实测占用推导： - 禁用插件 / 禁用 skill：取优化前报告中该 skill 条目的实测 `~NNN tok`（name + description 常驻部分）。无对应条目则记 0。 - 移除 MCP：取优化前报告中该 MCP 条目实测 `~NNN tok`。无则记 0。 - 改写子代理工具列表 / 限定 rule paths / enable-tool 等结构性改动：优化前报告无法直接给出该项自身的常驻占用，**记 0** 并在 `deviation` 注明"预估无法从报告实测，按 0 处理"，不得臆造数值。 - 即 `estimatedSavingTokens` = 优化前报告里被该任务移除/缩减的那部分 token；报告中找不到对应项即为 0。 - `actualSavingTokens` 取值规则： - 已完成：取对应分类前后 delta 中可归属部分；无法精确归属按占比估算，并在 `deviation` 注明"可能存在任务间重叠节省" - 未完成 / 跳过：记 0 - 实际 ≠ 预估时 `deviation` 必非空，说明偏差原因（如"插件禁用仅移除 skill 定义，系统/工具上下文未等量削减"）。 - 汇总 `summary`：`completedTasks` / `failedTasks` / `skippedTasks` / `partialTasks` 计数 + 总节省与百分比 7. **必须**写入 `save-token/save-token-report.json`（结构见 `src/types/index.ts` 的 `SaveTokenReport` 契约：generatedAt / beforeSource / afterSource / beforeTotalTokens / afterTotalTokens / changes[] / taskResults[] / summary）。 8. 对话中输出中文摘要：总节省 Token 与百分比、分类变化表、任务效果表（含预估/实际偏差标记）；可另写 `save-token-report.md` 展示。 ## 边界 - 不修改任何配置或前置文件，仅读取与对比（只读闭环）。 - Token 估算为 `length/4` 经验值（非真实 tokenizer），报告须注明"估算值，仅用于相对比较"。 - 无法归因的节省统一记 0 并在 `deviation` 说明，不夸大效果。 - 所有产物统一落在 `save-token/`。