放进 ~/.claude/skills/tool-scout/SKILL.md：

---
name: tool-scout
description: 从用户的工作轨迹里找出能提效的开源工具。读用户指定 agent 的会话历史(回溯模式)或就新项目访谈(立项模式),提炼工作画像,再从 SummFlow 工具目录语义匹配能解决观察到的摩擦的工具,给出推荐理由 + 安装命令。需要「帮我看看有什么工具能改进我的工作流 / 这个新项目该上哪些工具」时使用。
---

# tool-scout:把工作轨迹匹配成工具推荐

你在帮用户从 SummFlow 工具目录里找出能提效的工具。

**铁律**:历史**就地读、就地脱敏**,只有**受控结构化信号**能离开本机进程 —— profile 里没有对话原文、没有命令参数、没有路径、没有密钥,那些字段**根本不存在**(不是被过滤)。匹配推理由**用户当前使用的 AI 助手**完成,因此 profile 会进入该助手的模型上下文;这一点必须对用户说清楚,不得宣称「不外发」。唯一的主动网络动作是 read-only GET 拉目录;不替用户装任何东西,只给命令。每条推荐都要绑定一条观察到的具体摩擦,绝不泛泛而谈。

## 模式判定
- 用户想「看看现有工作流能上什么工具」→ **回溯模式**(读历史)。
- 新项目起步、无历史可读、或用户明确想就需求咨询 → **立项模式**(访谈)。

---

## 回溯模式

> **脚本路径**:本 skill 的辅助脚本随插件分发,`node ${CLAUDE_SKILL_DIR}/scripts/…` 里的 `${CLAUDE_SKILL_DIR}` 由 Claude Code 替换成本 skill 所在目录(装在哪都对、与当前工作目录无关)。逐字保留这个前缀,别改成裸 `scripts/…`(那样只在 repo 检出目录里才找得到)。

### R0 · 同意闸(必做,先于一切文件读取)

逐字告诉用户(不得改写成更宽松的说法):

> 本地读取并提取脱敏后的任务与工具使用信号;推荐匹配由你当前使用的 AI 助手完成。不会发送对话原文、文件正文、命令参数、密钥或绝对路径。

补充说明三件事:①出推荐前会对目录工具做**只读**的「装没装」检查(本地 `command -v` 等,不写);②写到本地的只有两样 —— 一行「上次运行日期」(`~/.summflow/scout-last-run`,只是个 YYYY-MM-DD)和目录未命中清单(`~/.summflow/tool-scout-misses.jsonl`,**只有受控码与月份桶,没有任何自由文本**,见 R4);③随时可以 `--clear` 清掉未命中清单。

**同意只覆盖本次运行。** 下次再跑要重新问,不得把一次同意当成长期授权。若将来引入长期授权,必须是独立的、可随时撤销的开关,且默认关闭。

**未得明确许可,不读任何历史文件、不生成任何缓存或 miss log。** 用户拒绝 → 转立项模式或退出。

> **不得恢复旧承诺**:即使用户说自己的宿主是本地模型,也不能改回「内容不外发」——
> tool-scout 无法可靠证明宿主模型的实际部署位置,承诺一件自己验证不了的事就是撒谎。

### R1 · 探测 + 选范围
- 运行 `node ${CLAUDE_SKILL_DIR}/scripts/scout-history.mjs --detect`,把探测到的 provider 列给用户(present 的、各自 file_count)。
- 让用户选要分析的 provider。**广泛支持**:解析逻辑移植自成熟多-agent 阅读器(claude-code-history-viewer)+ 官方文档,覆盖 Claude Code / OpenCode / Codex / Gemini / Cline / Cursor / ForgeCode / Hermes / CodeBuddy / Aider 等。读不到时(node 版本不够读 SQLite、路径不在、格式漂移)会在 profile 里给 `unreadable` 提示并优雅留空——**空 signals 是「没读到」不是「没摩擦」**,这种情况如实告知并建议改用 Claude Code 或转立项模式,绝不据空信号臆断。
- 范围默认近期(`--limit 50`,即最近 50 个会话文件)。用户要更宽/更窄就调 `--limit`。

### R2 · 提炼画像(闭集信号)
- 运行 `node ${CLAUDE_SKILL_DIR}/scripts/scout-history.mjs --provider <id> --limit <n>`(拉过目录后可加 `--catalog <file>`,用于把本地 MCP/skill 名映射成公开的目录 slug;不传则相关字段留空)。
- 拿到的 profile 是 `schema: "closed-set-v1"`,`signals` 只有**闭集字段**:`task_categories`、`languages`、`frameworks`、`tool_names`、`package_names`、`command_names`、`mcp_capabilities`、`observed_friction_codes`、`installed_tool_ids`,外加一个 `dropped` 计数。**没有对话原文,也没有任何自由文本字段** —— 不要去找、更不要要求用户手动贴原文来「补充上下文」。
- **先看 `unreadable`**:有就说明该 provider 格式未解析、信号是空的(是「没读到」不是「没摩擦」)——别拿空信号当结论,告知用户改用 Claude Code 或转立项模式。
- **再看 `insufficient_signal`**:有就说明脱敏后没剩下可用信号。**如实告诉用户「没有足够的脱敏信号」并转立项模式**,不要凭 `dropped` 计数或猜测编造需求。
- `dropped` 里的计数(`secret_records` / `unclassified_commands` / `unknown_packages` / `pathy_or_url_texts`)只用于向用户解释「有多少内容因含疑似密钥或路径被整条丢弃」,**它们不含内容**,也不能拿来推断摩擦。
- 读 `observed_friction_codes` 与 `command_names`/`task_categories` 组合出摩擦判断。**这些是候选信号,判断由你来下** —— 不要把每个命令都当摩擦(`git`/`ls` 是日常,不是摩擦)。

### R3 · 拉目录
GET `https://summflow.com/tools-index.json`(用 WebFetch 或 `curl -fsSL`)。这是唯一外发动作,read-only。失败 → 告知「目录拉取失败」并停,不用任何陈旧副本冒充。

> **契约版本:`tools-index-v2`。** 每条记录带 `capabilities`(人工核实、逐条带证据码)与 `ledger_state`。候选投影脚本会在投影前验一次;拿到旧结构会**直接报错**,不会静默当成「这些工具没有能力」。报错时告知用户重新拉取目录,**不要**退回用 `tags` 猜能力。
>
> `ledger_state` 不是 `current` 的条目(输入已变 / 无台账记录 / 身份存疑),`capabilities` 恒为空集且不可推荐 —— 它们仍有页面,但**不给确定的安装建议**。

### R3.5 · 标注已装(全目录预探)
把拉到的目录存成文件,跑 `node ${CLAUDE_SKILL_DIR}/scripts/scout-detect.mjs --catalog <file> --since auto`,拿回标注过的目录:
- 命中本机安装的卡带 `already_installed:true` + `installed_via`(如 `cli:docling`)。脚本对每张卡的 `detect` 句柄做**只读**存在性检查(`cli`→`command -v`、`skill/mcp/plugin`→宿主原生清点),只读、不外发。脚本整体失败 → 退回纯名字匹配(见 R4 fallback),不阻断出推荐。
- `--since auto` 读 `~/.summflow/scout-last-run`(上次运行日期)。**有上次记录** → 每张卡带 `is_new`(该卡 `added_date` 在上次运行日当天或之后);这是**增量重跑**,告诉用户「距上次运行 <日期> 目录新增了 N 张卡」。**首次运行**(无记录)→ 无 `is_new` 字段,正常全量推荐。要看指定日期之后的新增,可手动 `--since 2026-06-01`。

### R4 · 在候选集内排序(不是自由匹配)

> **P4-1C1.1 起,你不能直接从整个目录里挑工具。** 流程是:
> `闭集 profile → 本地确定性候选投影 → 你只排序和解释候选 → 确定性校验 → 展示/拒答`
> 理由:实测出现过虚构 slug(`ggml-org__llama.cpp`,真值 `-cpp`,链接会 404)
> 与「拿推理运行时冒充量化工具」。让你在给定集合内排序,这两类错误在结构上就不可能。

1. 先拿候选:
   `node ${CLAUDE_SKILL_DIR}/scripts/scout-recommend.mjs --candidates --profile <f> --catalog <f>`
2. 返回里若有 `short_circuit`(候选为空或信号不足)→ **直接照它拒答,不要再自己找工具**。
   候选为空是**目录事实**(目录里没有具备该能力的卡),不是你没找到。
3. 否则从 `candidates` 里挑,最多 4 条。你**只能**输出:
   - `slug` —— 必须逐字来自候选集合;
   - `reason_code` —— 必须来自该候选自己的 `reasons` 数组;
   - `suggest_install` —— 布尔。
   **不得**创造新 slug、新能力、新安装命令、自由 URL,或目录里没有的兼容性事实。
   自由理由不要写:展示文案由本地模板按 reason code 渲染。
4. 校验:
   `node ${CLAUDE_SKILL_DIR}/scripts/scout-recommend.mjs --validate --candidates <f> --model-output <f>`
   **以校验器的输出为准**。被丢弃的条目不要试图重提或绕过 —— 那是硬闸,不是建议。

以下匹配原则仍然适用(用于在候选集内排序):
- **绑定摩擦**:每条推荐 = 「你的信号里出现了 `format_conversion` 摩擦码,且 `command_names` 含 `pdftotext` → 工具 Y 能解决」。**引用的证据只能是 profile 里的闭集字段值**,不得引用(也无从引用)对话原文。
- **去重(确定性优先)**:`already_installed:true` 的卡**直接排除**(可在末尾一句说明「`installed_via` 你已装」);某摩擦的最佳匹配已装 → 改推目录里未装的次优替代。**无 `already_installed` 标的卡**(detect 句柄推不准 / R3.5 失败)→ 回落 profile 的 `installed_tool_ids`(目录 slug 列表),命中的不推。
- **诚实空态**:目录里没有对应工具就说「这块目前没有匹配的卡」,不硬凑、不降格塞沾边的。
- **未命中落盘**:每个「没有匹配」的摩擦,归到**受控码**再落盘:
  `node ${CLAUDE_SKILL_DIR}/scripts/scout-miss-log.mjs --log '{"scenario":"<受控场景码>","gap":"<受控缺口码>","no_match":true}'`。
  场景码与缺口码的合法取值见脚本里的 `MISS_SCENARIOS` / `MISS_GAPS`;**不在词表里的一律拒写**(脚本会抛错,不要改成 `other` 蒙混)。落盘的只有月份桶 + 两个码 + 布尔,**没有需求原话、没有你的理由、没有路径** —— 这是 R0 已披露的第②个本地文件。报告里如实告诉用户已记下,并提一句:之后若自己找到了顺手的工具,欢迎提交到 submit.summflow.com。回看清单 `--list`,清空 `--clear`。
- **排序**:按「摩擦严重度 × 匹配贴合度」取 top 3–5。
- **增量重跑(卡带 `is_new` 时)**:优先呈现 `is_new:true` 的卡作为「自上次以来的新增推荐」。非新增的卡**不丢**——它们仍可用于匹配摩擦(老工具也可能正好治你的痛点),但默认少推/折叠,别拿用户上次已经看过的卡刷屏。无 `is_new`(首次运行)→ 正常全量。

### R5 · 出报告(见下「报告格式」),然后跑 `node ${CLAUDE_SKILL_DIR}/scripts/scout-detect.mjs --record-run` 把今天记为「上次运行日期」(为下次增量重跑铺路;只写本地那一行日期)。

---

## 立项模式

### G1 · 访谈
一轮结构化提问问清:项目类型、技术栈、要解决的核心问题、现有工具链、最头疼的环节。在脑中形成同样的「画像」(领域/栈 + 痛点)。

### G2–G4
同回溯的 R3(拉目录)→ R4(匹配,摩擦换成访谈得到的痛点)→ R5(报告)。去重时若用户提了已有工具链,同样不重复推荐。

---

## 报告格式
对话内排序报告,每条:
- **工具名 + 一句它解决什么**(取卡片 `positioning`)。
- **为什么推给你**:绑定的那条摩擦/痛点(引用具体证据)。
- **怎么装**:卡片 `install` 数组里的命令(逐字,可直接复制);没有就略过。
- **看详情**:`https://summflow.com<url>`(卡片 `url` 字段)。

语气沉稳、只陈述不安利(沿用站点卡片去 AI 味规范:不堆形容词、不替用户下惊叹)。无任何匹配时如实说明,不出空骨架。

结尾问一句:**要不要把这份推荐存成 markdown 存档?**(默认不存;用户确认才写到用户指定路径。)
再补一句节奏提示:**工具目录每周更新,隔段时间(如每月)重跑一次即可只看新增的卡**——已装的会自动过滤,你的近期会话也会带出新摩擦。增量重跑时报出距上次的天数(如「距上次运行 23 天」),让这句提示落到具体时间。

## 绝不
- 读历史前不征得许可;把同意当成长期授权;用陈旧目录副本冒充。
- **向用户宣称「内容不外发」或「只在本地推理」** —— 匹配发生在宿主模型上下文里,
  而 tool-scout 无法验证宿主部署在哪。R0 的措辞逐字使用,不得软化。
- **绕过闭集**:要求用户手动粘贴对话原文、把原文写进 miss log 的任何字段、
  或在报告里复述 profile 之外的用户内容。
- 拿 `dropped` 计数当摩擦证据,或在 `insufficient_signal` 时硬出推荐。
- **绕过候选硬闸**:推荐候选集合之外的 slug、自己写安装命令或 URL、
  或在校验器丢弃某条后换个说法重提。候选为空就是拒答,不是让你再想办法。
- 替用户执行安装命令 / 改用户环境(只给命令,用户自己跑)。
- 推荐目录里不存在的工具,或硬凑沾边的凑数。