stk-analyze

# SKILL: stk-analyze 基于 `stk diagnose` 诊断报告（含 `usageStats` 真实调用数据）与当前仓库的代码/文档扫描结果，并行派发多个专注不同优化点的子 Agent——**全程不询问用户意图，所有判定均以 usage 数据与仓库特征为依据**。每个子 Agent 将统一 Schema 的 JSON 落盘到 `save-token/suggestions-<agent-name>.json` 并**自行用 `stk verify --file` 校验格式**（程序化死逻辑，失败则覆盖重写自纠），最后汇总为 `save-token/tasks.md` 待办清单。 ## 编排模型（状态机） 采用**显式状态机**驱动，避免子 Agent 之间自由对话、各自为政。每个对象（子 Agent / 前置调研）在其生命周期内处于一个状态，由主 Agent 依据**产物是否落盘且校验通过**来推进： ```text PENDING → READY → RUNNING → SUCCESS └── FAILED → (RETRYING) → SUCCESS / FAILED ``` - `PENDING`：对象存在性判定通过、尚未派发。 - `READY`：输入产物（诊断字段 / `repo-scan.json`）齐备，可进入并行派发。 - `RUNNING`：子 Agent 已派发、正在产出并落盘 `suggestions-<name>.json`。 - `SUCCESS`：产物已落盘且通过 `stk verify --file`（或按对象为前置 `repo-analysis.json`）。 - `FAILED`：达到重试上限仍失败 / 超时 → 跳过该维度，汇总其余，摘要标注。 - `RETRYING`：`stk verify` 校验失败后子 Agent 自我修复并覆盖重写的中间态（有限重试，见"失败处理"）。 > 主 Agent 只依据**落盘产物的存在性 + 校验结果**推进状态，不靠子 Agent 的自我声称"我完成了"。这与"Artifact 而非 Conversation"一致——Agent 之间通过结构化 JSON 产物通信，不传聊天记录。 ## 目标 通过"检查诊断 → 扫描仓库 → 派发子 Agent → 汇总 tasks.md"四阶段，产出可一键执行的 Token 优化待办。每个子 Agent 仅关注一类对象，对象不存在则不启动该 Agent。 ## 执行流程 ### 平台识别（全局前置） 先判定当前 AI 平台，确定**项目级指令主文件**（下称 `memoryMd`，即每次会话自动全量加载到上下文的项目级记忆/指令文件）： | 平台 | 项目级指令主文件 | | ----------- | ---------------- | | CodeBuddy | `CODEBUDDY.md` | | Claude Code | `CLAUDE.md` | | CodeX | `AGENTS.md` | 判定方式：以当前运行平台为准（Agent 自知身份）；无法确定时检查项目根目录，存在 `./CODEBUDDY.md` 视为 CodeBuddy，存在 `./CLAUDE.md` 视为 Claude Code，存在 `./AGENTS.md` 视为 CodeX，多者并存时以当前平台为准。 下文所有涉及主文件的分析（`repo-scan.json` 字段、`memory-md` 子 Agent 启动条件、建议 `target`、tasks.md 分组标题等）统一用 `memoryMd` 指代实际文件名，**不写死**为具体平台文件名。 ### 阶段 1: 诊断数据检查 **步骤 1: 检查诊断数据** ```bash cat save-token/diagnosis-report.md 2>/dev/null || echo "NOT_FOUND" ``` - 文件存在且其中 `扫描时间:` 行（即 `scanTimestamp`）距当前 ≤ 5 分钟 → 复用，跳到阶段 2。 - 不存在或过期 → 提示用户先运行 `stk diagnose` 或 `/stk-diagnose`，**停止**，不产生任何输出文件。 > 诊断以 `diagnosis-report.md`（由 `stk diagnose` 生成的终端友好 Markdown 摘要）为可读源。**注意：Markdown 摘要不渲染 `usageStats`**——各子 Agent 判定所需的调用频次数据必须直读 `diagnosis-report.json` 的 `usageStats` 字段（5 个维度 `toolUsage` / `skillUsage` / `subagentUsage` / `mcpServerUsage` / `mcpToolUsage`，各有 `all` / `last90Days` / `last30Days` 三个时间桶，`ranking` 为 `{name, count}[]`）。本 SKILL **不询问用户使用场景**（已废除用户场景收集文件），所有画像类判定（scenario / 领域 / 频次）均由 `usageStats` 与 `repo-scan.json` 推断。 ### 阶段 2: 仓库代码/文档采集 **步骤 3: 扫描仓库** 在派发子 Agent 前扫描当前工作目录： ```bash # 代码文件数（按扩展名） find . -type f \( -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' -o -name '*.py' -o -name '*.go' -o -name '*.rs' -o -name '*.java' -o -name '*.c' -o -name '*.cpp' -o -name '*.vue' -o -name '*.svelte' \) \ -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/coverage/*' -not -path '*/.cache/*' | wc -l # 文档文件数 find . -type f \( -name '*.md' -o -name '*.mdx' -o -name '*.rst' -o -name '*.txt' \) \ -not -path '*/node_modules/*' ... | wc -l # 项目级指令主文件（按平台识别结果检测，见"平台识别"） ls CODEBUDDY.md CLAUDE.md AGENTS.md 2>/dev/null || true # monorepo 检测：根外是否存在多个 package.json / Cargo.toml / go.mod ``` 统计并写入 `./save-token/repo-scan.json`（字段见下方 RepoScan Schema）： | 字段 | 说明 | | --------------- | ------------------------------------------------------------------------------------- | | `scannedAt` | ISO 8601 | | `codeFileCount` | 代码文件数 | | `docFileCount` | 文档文件数 | | `codeLineCount` | 代码总行数（量级） | | `docLineCount` | 文档总行数（量级） | | `topLanguages` | Top 3 语言（按文件数降序，≤ 3） | | `hasDocsDir` | 是否存在 `docs/` 或 `README*` | | `hasMemoryMd` | 是否存在项目级指令主文件（memoryMd） | | `memoryMd` | 项目级指令主文件文件名（如 `CODEBUDDY.md` / `CLAUDE.md` / `AGENTS.md`），不存在时省略 | | `isMonorepo` | 是否 monorepo | | `scanError` | 失败信息；成功为 `null` | 排除目录：`node_modules` `.git` `dist` `build` `coverage` `.cache`。 **扫描失败处理**：`scanError` 非 null 时不阻塞流程；摘要标注扫描失败。 **步骤 3.5: 前置仓库调研（单独调用，非并行）** 扫描完成后、进入并行派发前，**单独调用一次**前置调研 Agent `repo-scan`（规则见 `../stk-analyze/agents/repo-scan.md`），读取 `repo-scan.json`，产出 `save-token/repo-analysis.json`（含 `flags` 结构化结论 + `suggestions[]`）。 - 此 Agent **不进入阶段 3 并行列表**，由主流程在步骤 3 后单发。 - `flags`（如 `docsOverInjected` / `needsMonorepoSplit` / `needsIndex`）供并行子 Agent 按需读取，避免各 Agent 重复计算仓库特征。 - `suggestions[]` 由汇总阶段（步骤 5）直接消费进 tasks.md 第 7 组"仓库专项"，不再经由并行 suggestion 文件。 - 该 Agent 失败/超时 → 跳过仓库专项维度，汇总其余，摘要标注。 ### 阶段 3: 并行子 Agent 派发 **步骤 4: 按对象存在性动态启动** 读取诊断报告，仅对**存在且非空**的对象启动对应子 Agent。对象为空 → 不启动，摘要标注跳过。 在**单条消息**中并行发起所有需启动的子 Agent（多次 `Agent` 调用）。每个子 Agent 接收：诊断报告相关字段（**含 `usageStats`**）+ `repo-scan.json` + `repo-analysis.json` 的 `flags`（按需），并**自行落盘**统一 Schema JSON 到 `save-token/suggestions-<agent-name>.json`。 **落盘与格式校验（子 Agent 自验，程序化死逻辑）**： 1. 子 Agent 完成分析后，将建议写入自己的文件 `save-token/suggestions-<agent-name>.json`。 2. 子 Agent **随即运行** `stk verify --file save-token/suggestions-<agent-name>.json` 校验**自己这一个文件**的格式（字段齐全、`operationType`/`risk`/`level` 合法、`estimatedSavingTokens ≥ 0`、`agentName` 与文件名匹配等）。 3. **校验失败** → 子 Agent 依据 `stk verify` 输出的具体错误行**自我修复并覆盖重写**该文件，再次 `stk verify --file`，直至通过。 4. **有限重试**：同一文件连续校验失败达 3 次仍不通过 → 放弃该维度，标记该子 Agent 为 `FAILED`（**不再无限重试**），汇总其余，摘要标注失败原因。 5. 校验通过 → 状态推进到 `SUCCESS`，汇总阶段（步骤 5）直接消费该文件。 > **校验是确定性死逻辑，归程序（`stk verify`）而非 LLM 重读自检**：子 Agent 负责"产出建议 + 依据错误修复"，`stk verify` 负责"判定格式对错"，二者职责分离（Generate → Independent Verify）。格式校验不涉及主观质量判断，不存在"执行者自我验收的确认偏差"。 > > **覆盖重写不触发删除**：修复采用覆盖写（`writeFileSync` 同路径），不删除旧文件，避免权限摩擦。 **失败分类与处理**（任一子 Agent 失败/超时）： | 失败类型 | 判定 | 处理 | | ----------------- | ------------------------------ | ----------------------------------------- | | `tool_error` | `stk verify` 报错/命令执行失败 | 重试一次 | | `context_missing` | 子 Agent 反馈缺少必要输入字段 | 补全输入后重派发该 Agent | | `impl_error` | `stk verify` 返回格式错误清单 | 子 Agent 按清单覆盖重写（见上"有限重试"） | | `plan_error` | 连续 3 次 `impl_error` 仍失败 | 放弃该维度，标记 `FAILED`，不重规划 | | `unknown` | 超时 / 未产出文件 | 跳过该维度，汇总其余 | **子 Agent 启动条件表** 下表仅指向**本阶段（stk-analyze）**的 agents，一律使用相对于本 SKILL.md 的锚定路径 `../stk-analyze/agents/`；**禁止**引用 stk-optimize 下的同名 agent（两者语义相反：analyze 只产建议 JSON，optimize 直接改配置）。 | # | 子 Agent | 关注对象 | 启动条件 | 详细规则 | | --- | ---------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | 1 | `toolkit-enable` | `toolkitDetection[]` | 数组非空 | ../stk-analyze/agents/toolkit-enable.md | | 2 | `mcp-opt` | `mcpList[]` | 数组非空 | ../stk-analyze/agents/mcp-opt.md | | 3 | `plugin-opt` | `pluginList[]` | 数组非空 | ../stk-analyze/agents/plugin-opt.md | | 4 | `agent-opt` | `agentList[]` | 数组非空 | ../stk-analyze/agents/agent-opt.md | | 5 | `skill-opt` | `skillList[]` | 数组非空 | ../stk-analyze/agents/skill-opt.md | | 6 | `knowledge-base` | `toolkitDetection[]` + `repo-scan.json` | 存在已装未启用的知识库 **或**（全部未装且 `codeFileCount ≥ 100`）；且无任何知识库 `enabled === true` | ../stk-analyze/agents/knowledge-base.md | | 7 | `command-opt` | `commandList[]`（主 Agent 从诊断报告提取后传入） | `commandList[]` 非空 | ../stk-analyze/agents/command-opt.md | | 8 | `rules-opt` | `ruleList[]` | 数组非空 | ../stk-analyze/agents/rules-opt.md | | 9 | `memory-md` | 项目级指令主文件（`memoryMd`） | `hasMemoryMd === true` | ../stk-analyze/agents/memory-md.md | | 10 | `hook-audit` | `hookList[]` | 数组非空 | ../stk-analyze/agents/hook-audit.md | | 11 | `tool-opt` | `builtinTools[]` | `agentName ∈ {codebuddy, workbuddy, claude}` **且** 数组非空 **且**（codebuddy/workbuddy：无 `cblite` alias；claude：无已 deny 候选） | ../stk-analyze/agents/tool-opt.md | > **MCP 优化关键约束**：TAPD（`mcp-server-tapd`）、工蜂（`gongfeng-mcp`）、GitHub（`github-mcp`）等开发协作平台 MCP 是开发必备工具，**不得建议禁用**。应建议用对应 CLI（`tapd-cli` / `gongfeng` / `gh`）替代 MCP，保留功能同时移除工具定义的 Token 开销。调用频次判定（如 `mcpServerUsage` 零调用）不适用于此类开发协作平台——它们对所有开发场景均必要，零调用也仅走 CLI 替代。 > **`knowledge-base` 启动前置判定**（派发前执行，依据诊断报告 `toolkitDetection[]` + `repo-scan.json`，自动推断不询问用户）： > > - 任一知识库 `enabled === true`（已启用）→ **不启动**该 Agent（已就绪，无需建议）。 > - 存在 `installed === true` 且 `enabled === false` 的知识库 → **启动**（恰 1 个即该工具；多个按 repo 特征选 1：isMonorepo→GitNexus，topLanguages≥3 且 codeFileCount>50→Codebase-Memory-MCP，否则→Graphify）。 > - 全部知识库未安装且 `codeFileCount ≥ 100` → **启动**，按 repo 特征推荐安装（选法同上）。 > - 其余（全未装且 `codeFileCount < 100`）→ 不启动。 > - 判定依据一律取自诊断报告与扫描结果，不猜测。 > **`tool-opt` 启动前置判定**（派发前执行）： > > - **平台限制**：仅当诊断报告 `agentName` 为 `codebuddy`、`workbuddy` 或 `claude` 时启动；**CodeX 不启动**（无内置工具延迟/禁用统一开关；`mcp_servers.<id>.enabled_tools`/`disabled_tools` 仅 MCP 工具且为白/黑名单禁用）。 > - **CodeBuddy / WorkBuddy**：走 `cblite` alias + `--tools "Defer(...)"`（延迟加载，Top 20 常驻、其余收窄）。WorkBuddy 基于 CodeBuddy CLI 内核，支持相同 `--tools` Defer 语法。 > - **Claude Code**：走 `~/.claude/settings.json` 的 `permissions.deny`（**禁用**语义），候选由 `toolUsage.last30Days` 零调用筛选，**且只对用户明确确认不使用**的工具建议 deny。