命令片段管家（snippet-keeper）

概述

好用的命令、SQL、配置、代码模板，第一次写出来后要不就忘了、要不就散落在几十个聊天记录与笔记里，下次要用又得重新搜、重新拼。命令片段管家把这些「可复用的执行资产」收敛成一个带标签、可检索、可参数化的本地片段库，把重复查找成本降到一次查询。

核心能力：

1. 沉淀：用 add 把一条命令/片段存进库，带 分类 / 标签 / 描述，并支持 {{占位符}} 参数化（如 {{db_host}}、{{branch}}）。
2. 检索：list 按分类/标签/关键词精确过滤；find 按「意图」做模糊匹配（例如输入「git 清理已合并分支」能命中对应片段），不用记得精确关键词。
3. 复用：expand 把 {{占位符}} 填成最终可复制的命令并打印——只输出、绝不执行，规避任意命令执行风险。
4. 盘点：tags 一眼看清片段库的主题分布，知道该补哪类、该删哪类。
5. 本地优先：纯标准库、跨平台、不联网；库文件就是一份 snippets.json，可随笔记/仓库一起版本管理。

纯标准库实现（scripts/snippet_keeper.py），无外部依赖。

何时使用

• 刚拼出一个好用的命令（git 清理、Docker prune、批量重命名、SQL 诊断），怕下次找不到 → 存起来
• 经常性要写结构相似的模板（SQL 查询、curl 请求、CI 配置、正则），每次手改参数 → 参数化存为片段
• 忘了上次那句命令长啥样，只记得「大概是用来干 X 的」 → find 按意图搜
• 团队/个人想建一个「常用命令手册」 → 持续 add，用 tags 盘点
• 想生成一份可直接复制粘贴的执行文本（含占位符已填） → expand --emit

工作流

第 1 步：准备片段简报（或直接命令行）

用 assets/snippet-template.md 作模板，写一份 Markdown 简报，例如 examples/sample-snippet-1.md：

# 清理已合并的本地 git 分支

- 分类：git
- 标签：清理, 分支
- 描述：删除本地已合入 main 的分支，保留 main/dev

## 命令
git branch --merged {{base}} | grep -vE "{{\\s*(main|dev|master)\\s*}}" | xargs -r git branch -d

> {{base}} 是占位符；expand 时通过 --set base=main 填充。--emit 可选写出文本文件。

第 2 步：追加到片段库

# 用简报追加
python scripts/snippet_keeper.py add -i examples/sample-snippet-1.md -o examples/generated

# 用命令行直接追加
python scripts/snippet_keeper.py add \
  --title "PostgreSQL 慢查询 Top10" --category sql --tags "诊断,pg" \
  --desc "按耗时取最慢的 10 条" \
  --command "SELECT query, mean_exec_time FROM pg_stat_statements ORDER BY mean_exec_time DESC LIMIT 10;" \
  -o examples/generated

add 会自动分配 ID（S-<年份>-<序号>），写入 examples/generated/snippets.json，且不覆盖既有记录（追加式）。

第 3 步：检索与复用

# 列出全部 / 按分类 / 按标签
python scripts/snippet_keeper.py list -o examples/generated
python scripts/snippet_keeper.py list -o examples/generated --category git
python scripts/snippet_keeper.py list -o examples/generated --tag 清理

# 按意图模糊检索（不要求精确关键词）
python scripts/snippet_keeper.py find "git 删掉合并过的分支" --top 3

# 查看单条完整内容（含占位符）
python scripts/snippet_keeper.py show S-2026-001 -o examples/generated

# 填充占位符并输出（仅打印，不执行）
python scripts/snippet_keeper.py expand S-2026-001 --set base=main -o examples/generated

# 填充并写出为文本文件（不执行，供复制）
python scripts/snippet_keeper.py expand S-2026-001 --set base=main --emit examples/generated/clean-branches.sh -o examples/generated

# 标签盘点
python scripts/snippet_keeper.py tags -o examples/generated

第 4 步：解读与交付

1. 用 present_files 展示 snippets.json 与示例展开结果。
2. 在回复中给结论：片段总数、按标签的主题分布、哪几条最常用（占位符多=复用价值高）。
3. 强调 expand 仅生成文本、不会执行任何命令——把生成的命令交回用户自己复制运行，符合安全边界。

字段语义

边界

• 纯文本解析，不调用大模型；简报越规范，解析越准。字段缺失会留空而非报错。
• 只读取输入简报、只写入输出目录的 snippets.json，不联网、不删除 / 修改片段库之外的任何文件；反复 add 是追加而非覆盖。
• expand 严格只输出填充后的文本，绝不调用 shell / 子进程执行命令，这是本技能的安全红线。
• 占位符语法：{{名称}}，名称支持字母/数字/下划线/连字符；expand 未提供的占位符会列明并退出码 1，不会静默留坑。

安全与合规

• 本技能为本地效率工具，不收集、不上传任何数据。
• 脚本仅进行文件读取与本地 JSON 输出，无任何网络 / 破坏性 / 命令执行行为，符合 SkillHub 安全审查要求。
• 片段可能含内网地址、密钥占位符等敏感信息，输出文件请保存在受控目录，避免泄露；建议 snippets.json 纳入私有仓库或加密笔记。

参考资源

• scripts/snippet_keeper.py — 片段库引擎，纯标准库、跨平台
• references/snippet-patterns.md — 哪些值得存、占位符命名、分类与标签约定
• assets/snippet-template.md — 空白片段简报模板，可直接套用
• examples/sample-snippet-1.md — 示例简报（git 清理分支，含占位符）
• examples/sample-snippet-2.md — 示例简报（Docker / SQL 诊断）
• examples/generated/snippets.json — 示例片段库
• examples/generated/clean-branches.sh — expand 产出的可复制文本（未执行）