stk-analyze

# SKILL: stk-analyze 收集用户的使用场景与当前仓库的代码/文档情况，结合 `stk diagnose` 诊断报告，并行派发多个专注不同优化点的子 Agent，每个子 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`：输入产物（诊断字段 / `context.json` / `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 摘要）为可读源，避免直接解析过长的 `diagnosis-report.json`。子 Agent 派发时仍从源报告读取所需字段；若某字段 Markdown 摘要未涵盖，回退读取 `diagnosis-report.json`。 **步骤 2: 收集使用场景（含图谱工具倾向性）** 检查 `./save-token/context.json`：存在且 `collectedAt` 在 7 天内 → 复用，跳到阶段 2。 否则用 `AskUserQuestion` 分轮收集（不猜测，必须询问）： **第一轮（必问）— 使用场景与用户角色：3 个问题 MUST 合并为一次 `AskUserQuestion` 调用**（该工具单次最多支持 4 问，禁止拆成 3 次连续打断用户）： - 问题 1: 主要使用目的 → 代码编写 / 文档写作 / 通用办公 / 通用 - 问题 2: 代码与文档是否在同一仓库 → 是（同仓）/ 否（独立仓库）/ 不适用（纯文档/办公） - 问题 3: 用户角色画像 → 前端开发 / 后端开发 / 测试 / 产品经理 / 全栈 / 其他 > 用户角色（`role`）用于精准判定 Plugin 的适用性：特定领域 Plugin（如前端 UI 套件、移动端 SDK）仅对对应角色的项目有价值，跨角色全局启用即为浪费。角色与 `purpose`/`sameRepo` 共同构成推荐依据。 **第二轮（条件触发）— 代码知识图谱工具倾向性：** - **触发条件**：仓库扫描已完成（`repo-scan.json` 存在）且 `codeFileCount >= 5` - **前置判定（决定是否询问）**：进入询问前，先读取 `diagnosis-report.md` / `diagnosis-report.json` 中的代码知识库对象（如 `graphify` / `codebase-memory-mcp` / `codegraph` / `gitnexus` 等，对应 `knowledge-base` 维度字段），按以下规则判定： 1. **已启用** → 直接写入 `context.json` 的 `graphTool` 为该工具，**不再** `AskUserQuestion` 询问选哪个知识库。 2. **已安装但仅 1 个且未启用** → 默认使用该唯一已安装知识库，直接写入 `graphTool`，**不再** 询问是否使用。 3. **已安装但多个且均未启用 / 全部未安装 / 触发条件不满足但用户主动提及** → 才走下方 `AskUserQuestion` 询问。 > 判定依据一律取自诊断报告，不猜测；若报告字段缺失无法判定，降级为正常询问。 - **询问内容（仅当前置判定不满足时触发）**：列出已知工具，附简要描述： - `Graphify`（本地 CLI，轻量图谱） - `Codebase-Memory MCP`（本地 MCP，跨语言图谱） - `CodeGraph`（语义+历史层） - `GitNexus`（monorepo/影响分析） - `暂不需要` - **推荐标记**：基于仓库扫描特征在对应选项标注"（推荐）"： - TypeScript/JavaScript 为主且有项目级指令主文件（`memoryMd` 存在）→ 推荐 **Graphify** - 多语言大型仓库（codeFileCount > 50 且 topLanguages ≥ 3）→ 推荐 **Codebase-Memory MCP** - monorepo 结构 → 推荐 **GitNexus** - 规模达标但无上述特征 → 推荐 **Graphify**（默认） - 用户可选"暂不需要"跳过，或"其他"输入自定义工具。推荐仅供参考，用户自主决定。 **第三轮（可选）— 模糊点澄清：** - 若存在边界情况（如多主流语言并存、上下文 Token 量临界、同名 marketplace/project Skill 并存），用额外 `AskUserQuestion` 确认倾向。 将结果写入 `./save-token/context.json`： ```json { "collectedAt": "<ISO8601>", "purpose": "code|doc|office|general", "sameRepo": "same|separate", "role": "frontend|backend|test|pm|fullstack|other", "graphTool": "graphify|codebase-memory-mcp|codegraph|gitnexus|none|<自定义>" } ``` > `graphTool` 仅在第二轮相关时写入；仓库过小不触发则不写该字段（向后兼容）。若诊断报告显示已启用或仅 1 个已安装知识库，由前置判定直接写入，不触发询问。 ### 阶段 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`（规则见 `@agents/repo-scan.md`），读取 `repo-scan.json` + `context.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 接收：诊断报告相关字段 + `context.json` + `repo-scan.json`（按需），并**自行落盘**统一 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 启动条件表** | # | 子 Agent | 关注对象 | 启动条件 | 详细规则 | |---|------------------|-----------------------------------|-----------------------------------------|---------------------------| | 1 | `tool-enable` | `toolDetection[]` | 数组非空 | @agents/tool-enable.md | | 2 | `mcp-opt` | `mcpList[]` | 数组非空 | @agents/mcp-opt.md | > **MCP 优化关键约束**：TAPD（`mcp-server-tapd`）、工蜂（`gongfeng-mcp`）、GitHub（`github-mcp`）等开发协作平台 MCP 是开发必备工具，**不得建议禁用**。应建议用对应 CLI（`tapd-cli` / `gongfeng` / `gh`）替代 MCP，保留功能同时移除工具定义的 Token 开销。领域匹配判定（如 purpose=code/role=backend）不适用于此类开发协作平台——它们对所有开发角色均必要。 | 3 | `plugin-opt` | `pluginList[]` | 数组非空 | @agents/plugin-opt.md | | 4 | `agent-opt` | `agentList[]` | 数组非空 | @agents/agent-opt.md | | 5 | `skill-opt` | `skillList[]` | 数组非空 | @agents/skill-opt.md | | 6 | `knowledge-base` | `repo-scan.json` + `context.json` | 仓库超阈值 **且** `graphTool` 非 `none` | @agents/knowledge-base.md | > **`knowledge-base` 启动前置判定**（派发前执行，依据诊断报告）： > - 诊断报告显示某代码知识库 `enabled === true`（已启用）→ **不启动**该 Agent（已就绪，无需建议）。 > - `graphTool` 指定某工具且诊断报告该工具 `installed === true` 但 `enabled === false` → **启动**，Agent 工作即产出"启用该知识库"建议。 > - `graphTool` 指定某工具且未安装 / 用户主动选择 → 启动，按规模产出"启用"建议。 > - `graphTool === 'none'` 或缺失 → 不启动。 > 判定依据一律取自诊断报告，不猜测；报告字段缺失时降级为按原"仓库超阈值且 graphTool 非 none"条件启动。 | 7 | `command-opt` | `commandList[]`（主 Agent 从诊断报告提取后传入） | `commandList[]` 非空 | @agents/command-opt.md | | 8 | `rules-opt` | `ruleList[]` | 数组非空 | @agents/rules-opt.md | | 9 | `memory-md` | 项目级指令主文件（`memoryMd`） | `hasMemoryMd === true` | @agents/memory-md.md | | 10 | `hook-audit` | `hookList[]` | 数组非空 | @agents/hook-audit.md | | 11 | `tool-opt` | `builtinTools[]` | `agentName ∈ {codebuddy, workbuddy, claude}` **且** 数组非空 **且**（codebuddy/workbuddy：无 `cblite` alias；claude：无已 deny 候选） | @agents/tool-opt.md | > **`tool-opt` 启动前置判定**（派发前执行）： > - **平台限制**：仅当诊断报告 `agentName` 为 `codebuddy`、`workbuddy` 或 `claude` 时启动；**CodeX 不启动**（无内置工具延迟/禁用统一开关；`mcp_servers.<id>.enabled_tools`/`disabled_tools` 仅 MCP 工具且为白/黑名单禁用）。 > - **CodeBuddy / WorkBuddy**：走 `cblite` alias + `--tools "Defer(...)"`（延迟加载，低频批量收窄）。WorkBuddy 基于 CodeBuddy CLI 内核，支持相同 `--tools` Defer 语法。 > - **Claude Code**：走 `~/.claude/settings.json` 的 `permissions.deny`（**禁用**语义），且**只对用户明确确认不使用**的工具建议 deny。 > - **CodeBuddy / WorkBuddy 幂等**：运行 `type cblite 2>/dev/null`（或 `alias cblite`），能解析到 → 已存在 `cblite` alias，**不启动**（已就绪）。 > - **Claude 幂等**：读取 `~/.claude/settings.json` 的 `permissions.deny`，若候选低频工具均已 deny → **不启动**（已就绪）。 > - 判定失败/无法确认时，按"未就绪"处理并启动（避免漏建议）。