@baimingtao/lbs-agent 1.0.0

package/extensions/skills/builtin/software-development/simplify-code/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: simplify-code
+description: "对最近的代码变更进行 3 个 agent 并行清理。"
+version: 1.0.0
+author: Hermes Agent (inspired by Claude Code /simplify)
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [code-review, cleanup, refactor, delegation, subagent, parallel, simplify]
+    related_skills: [requesting-code-review, test-driven-development, plan]
+---
+
+# Simplify Code — 并行审查与清理
+
+使用三个并行运行的专注型审查者来审查你最近的代码变更，汇总他们的发现，并应用值得应用的修复。
+
+**核心原则：** 三个专注的审查者胜过一个宽泛的审查者。每个人都在代码库中深入搜寻单一类别的问题——reuse（复用）、quality（质量）或 efficiency（效率）——而不会将注意力分散在所有三个类别上。他们并发运行，因此你只需付出一次审查的延迟成本，而不是三次。
+
+## 何时使用
+
+当用户提到以下任何内容时，触发此 skill：
+
+- "simplify" / "simplify my changes" / "simplify these changes"
+- "review my code" / "review my recent changes" / "clean up my changes"
+- "/simplify"（如果他们保留了 Claude Code 的习惯）
+
+用户可能会添加的可选修饰符——请予以遵循：
+
+- **Focus（聚焦）：** "simplify focus on efficiency" → 仅运行 efficiency 审查者（或在汇总时增加其权重）。认可的 focus 包括：`reuse`、`quality`、`efficiency`。
+- **Dry run（试运行）：** "simplify but don't change anything" / "just report" → 运行三个审查者，展示发现结果，不应用任何更改。在应用之前必须询问。
+- **Scope（范围）：** "simplify the last commit" / "simplify staged" / "simplify src/foo.py" → 相应缩小 diff 来源（参见 Phase 1）。
+
+**不要**在每次编辑后自动运行此功能。它会消耗相当于三个 subagent 的 token——仅在用户明确要求时调用它。
+
+## 处理流程
+
+### Phase 1 — 识别变更
+
+捕获要审查的 diff。根据用户的请求选择来源，默认顺序如下：
+
+```bash
+# 1. 默认：未提交的工作区变更（已追踪文件）
+git diff
+
+# 2. 如果为空，包含暂存区的变更
+git diff HEAD
+
+# 3. 用户可能请求的特定范围变体：
+git diff --staged                 # "staged changes"
+git diff HEAD~1                    # "the last commit"
+git diff main...HEAD              # "this branch" / "my PR"
+git diff -- src/foo.py            # specific file(s)
+```
+
+如果 `git diff` 和 `git diff HEAD` 都为空，并且没有 git 仓库或没有变更，则回退到用户明确指定的文件，或者在本次会话中最近创建/编辑的文件。如果你确实找不到任何已更改的代码，请说明情况并停止——没有需要简化的内容。
+
+捕获完整的 diff 文本。注意其大小：如果非常大（例如 >2000 行更改），警告用户三个 subagent 各自携带完整的 diff 会消耗大量 token，并提议在继续之前缩小范围（按目录、按提交）。
+
+### Phase 2 — 并行启动三个审查者
+
+使用 `delegate_task` **批量模式（batch mode）** ——在一个 `tasks` 数组中传递所有三个任务，以便它们并发运行。对于这种模式，三个是合适的扇出数量；它在任何默认安装配置中都能很好地满足 `delegation.max_concurrent_children` 预算。
+
+给**每个**审查者提供**完整的 diff**（而不是片段——跨文件的问题往往隐藏在间隙中）以及代码库的绝对路径，以便他们可以搜索更广泛的代码库。每个审查者都会获得 `terminal`、`file` 和 `search` 工具集（以便他们能够使用 `git`、`read_file` 和 `search_files`/grep）。
+
+告诉每个审查者：
+- 搜索现有代码库以寻找证据（不要仅凭 diff 进行推理）。
+- **运用 Chesterton's Fence（切斯特顿栅栏）原则：** 在标记要删除任何内容之前，对该行运行 `git blame` 以了解它存在的原因。如果你无法确定其最初目的，将其标记为 `confidence: low`——不要猜测。
+- 将发现作为带有 confidence（置信度）和 risk（风险）的结构化输出报告：
+  ```
+  file:line → problem → suggested fix | confidence: high/medium/low | risk: SAFE/CAREFUL/RISKY
+  ```
+  - **SAFE** = 已证明不会影响行为（未使用的导入、注释掉的代码、直通包装器）。自动应用这些。
+  - **CAREFUL** = 在不改变语义的前提下进行改进（重命名局部变量、展平嵌套的三元运算符、提取辅助函数）。在测试验证下应用。
+  - **RISKY** = 可能改变行为或破坏公共契约（N+1 重构、公共 API 重命名、内存生命周期变更）。标记为需要人工审查——**不要**自动应用。
+- 跳过吹毛求疵和仅涉及风格的变动。只标记能实质性改进代码的内容。
+
+传递这三个目标（如果用户指定的 focus 排除了某些目标，则删除它们）：
+
+**Reviewer 1 — Code Reuse（代码复用）**
+> 审查此 diff 中是否存在与代码库中已有功能重复的代码。搜索工具模块、共享辅助函数和相邻文件（使用 search_files / grep），寻找新代码可以调用的现有函数、常量或模式，而不是重新实现它们。标记：重复现有功能的新函数；现有工具已经实现的手动编写逻辑（手动字符串/路径操作、自定义环境检查、临时类型守卫、重新实现的解析）。对于每一项，指出应该使用的现有组件名称及其位置。
+
+**Reviewer 2 — Code Quality（代码质量）**
+> 审查此 diff 中的质量问题。寻找：冗余状态（与现有状态重复或可以从中派生的值；不必要的缓存）；参数蔓延（在原本应该重构函数的情况下强行添加的新参数）；复制粘贴带变体（本应共享抽象的近乎重复的代码块）；抽象泄漏（暴露内部实现，破坏现有的封装边界）；stringly-typed 代码（在已有常量/枚举/注册表的情况下使用原始字符串——在标记之前检查规范的注册表）；AI 生成的冗余模式（在 `count++` 上面加上重述明显代码的额外注释，如 `// increment counter`；对已验证输入的不必要防御性 null 检查；绕过类型系统的 `as any` 强制类型转换；与文件其余部分不一致的模式）。对于每一项，给出具体的重构方案。
+
+**Reviewer 3 — Efficiency（效率）**
+> 审查此 diff 中的效率问题。寻找：不必要的计算（冗余计算、重复读取文件、重复的 API 调用、N+1 访问模式）；错失的并发机会（独立操作串行运行）；热路径膨胀（启动或每次请求路径上的繁重/阻塞工作）；TOCTOU 反模式（操作前进行存在性预检查，而不是执行操作并处理错误）；内存问题（无限增长、缺乏清理、监听器/句柄泄漏）；读取范围过广（只需读取片段时加载整个文件）；静默失败（空的 catch 块、被忽略的错误返回、`except: pass`、没有处理的 `.catch(() => {})`、错误传播断层——这些会隐藏 bug，至少应该在吞没错误前记录日志）。对于每一项，给出具体的修复方案以及为什么它更快或更安全。
+
+### Phase 3 — 汇总与应用
+
+等待三者全部返回（批量模式会一起返回它们）。
+
+1. **合并**发现到一个列表中，对审查者重叠的部分进行去重。
+2. **剔除误报**——你拥有最全面的上下文；你不需要与审查者争论，只需静默丢弃薄弱或错误的建议。
+3. **解决冲突。** 审查者之间可能产生分歧（Reviewer 1：“使用现有的 util X”；Reviewer 3：“X 很慢，将其内联”）。默认的解决优先级：**正确性 > 用户设定的 focus > 可读性/复用 > 微性能。** 不要应用损害代码清晰度的性能“修复”，除非该路径确实是热路径。当两个建议互斥但都有道理时，选择改动代码较少的那个，并注明另一个备选方案。
+4. **按风险等级顺序应用：**
+   - **先应用 SAFE**（自动应用）：未使用的导入、注释掉的代码、直通包装器、冗余的类型断言。之后运行测试。
+   - **接着应用 CAREFUL**（在验证下应用，一次处理一个文件）：重命名局部变量、展平三元运算符、提取辅助函数、合并重复项。每处理完一个文件就运行一次测试。恢复任何导致破坏的更改。
+   - **最后是 RISKY**（标记为需要审查——**不要**自动应用）：N+1 重构、公共 API 变更、并发修复、错误处理变更。展示每一项及其风险描述和测试覆盖状态。
+   如果用户选择了 dry run，展示所有三个等级，但不应用任何更改。
+5. **验证**你没有破坏任何东西：针对被修改的文件运行项目的定向测试（不是完整套件），并重新运行仓库使用的任何 linter/type check。如果某个修复破坏了测试，恢复该修复并报告。
+6. **总结**你所做的更改：按审查者类别和风险等级分组的已应用修复简短列表，以及你刻意跳过的发现及其原因。
+
+## 潜在陷阱
+
+- **不要将扇出数量增加到 ~3 个以上。** 更多的审查者意味着更高的成本和更多需要调和的冲突建议，而不是更好的覆盖率。这三个类别已经覆盖了整个空间。
+- **向每个审查者提供完整的 diff。** 将 diff 拆分给各个审查者违背了设计初衷——跨文件的重复和 N+1 问题只有在全貌下才会显现。
+- **审查者负责搜索，而不是猜测。** 一个没有指向现有工具的 reuse 发现（“可能有一个辅助工具处理这个”）只是噪音。要求提供 `file:line` 证据；丢弃缺乏证据的发现。
+- **应用 ≠ 重写。** 这是对用户最近变更的清理，而不是重构整个模块的许可证。将编辑范围限制在 diff 涉及的内容加上修复所需的最小周边变更。
+- **尊重项目约定。** 如果仓库有 AGENTS.md / CLAUDE.md / HERMES.md 或 linter 配置，请将这些规则融入到审查者提示中，以便建议符合内部风格而不是与其冲突。
+- **庞大的 diff 会撑爆上下文。** 如果 diff 非常大，请在委派之前缩小其范围——三个 subagent 每个都携带 5000 行的 diff 代价高昂且可能被截断。
+- **过度信任死代码工具。** `knip`、`ts-prune` 和 `depcheck` 会标记出那些实际上被动态使用的 export（基于字符串的导入、反射）。在删除之前务必 grep 该符号名称——工具报告显示干净并不能作为证明。
+- **未检查公共契约就进行重命名。** Export 名称、API 路由路径、DB 列名和配置项键都是契约——即使名字很糟糕，重命名也会破坏调用方。将公共契约的变更标记为 RISKY；绝对不要自动重命名它们。
+- **移除“不必要”的错误处理。** 空的 catch 块或被忽略的错误可能是故意的——在特定上下文下，错误是预期内且良性的。将其标记出来，不要直接移除；让人类来决定。
+
+## 相关
+
+如果你的安装中包含 `subagent-driven-development` skill（可选），它涵盖了互补的场景：在实现过程中（针对每个任务）进行并行审查。本 skill 是独立的、事后清理步骤。使用 `requesting-code-review` 作为提交前的安全/质量门禁。

package/extensions/skills/builtin/software-development/spike/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: spike
+description: "在实际构建之前用于验证想法的抛弃型实验。"
+version: 1.0.0
+author: Hermes Agent (adapted from gsd-build/get-shit-done)
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [spike, prototype, experiment, feasibility, throwaway, exploration, research, planning, mvp, proof-of-concept]
+    related_skills: [sketch, subagent-driven-development, plan]
+---
+
+# Spike
+
+当用户想要在正式投入实际开发前**摸索某个想法**时，请使用此 skill —— 用于验证可行性、对比不同方案，或者暴露出再多研究也无法解答的未知因素。Spike 在设计上就是一次性的。一旦它们完成了探索使命，就可以将其丢弃。
+
+当用户说类似以下的话时，加载此 skill：“让我试试这个”、“我想看看 X 是否可行”、“spike this out”、“在我投入 Y 之前”、“快速弄个 Z 的原型”、“这到底可能吗？”或“对比一下 A 和 B”。
+
+## 何时不使用此 skill
+
+- 答案可以通过查阅文档或阅读代码获得 —— 只需进行研究，不要构建
+- 工作属于生产路径 —— 改用 `plan` skill
+- 想法已经过验证 —— 直接进入实现阶段
+
+## 如果用户安装了完整的 GSD 系统
+
+如果 `gsd-spike` 作为同级 skill 出现（通过 `npx get-shit-done-cc --hermes` 安装），当用户需要完整的 GSD 工作流时，请优先使用 **`gsd-spike`**：持久化的 `.planning/spikes/` 状态、跨会话的 MANIFEST 追踪、Given/When/Then 验证格式，以及与 GSD 其他部分集成的提交模式。本 skill 是为没有（或不需要）完整系统的用户提供的轻量级独立版本。
+
+## 核心方法
+
+无论规模大小，每个 spike 都遵循以下循环：
+
+```
+decompose  →  research  →  build  →  verdict
+   ↑__________________________________________↓
+                  iterate on findings
+```
+
+### 1. Decompose
+
+将用户的想法拆解为 **2-5 个独立的可行性问题**。每个问题就是一个 spike。以表格形式展示它们，并采用 Given/When/Then 框架：
+
+| # | Spike | Validates (Given/When/Then) | Risk |
+| --- | ------- | ---------------------------- | ------ |
+| 001 | websocket-streaming | Given a WS connection, when LLM streams tokens, then client receives chunks < 100ms | High |
+| 002a | pdf-parse-pdfjs | Given a multi-page PDF, when parsed with pdfjs, then structured text is extractable | Medium |
+| 002b | pdf-parse-camelot | Given a multi-page PDF, when parsed with camelot, then structured text is extractable | Medium |
+
+**Spike 类型：**
+- **standard** — 一种方法回答一个问题
+- **comparison** — 相同问题，不同方法（共享数字，字母后缀 `a`/`b`/`c`）
+
+**好的 spike 问题：** 具体的可行性，带有可观察的输出。
+**坏的 spike 问题：** 太宽泛、没有可观察的输出，或者仅仅是“阅读关于 X 的文档”。
+
+**按风险排序。** 最有可能扼杀该想法的 spike 优先执行。如果最难的部分行不通，那么对简单部分进行原型设计就毫无意义。
+
+**跳过 decompose**：仅当用户已经确切知道他们想要 spike 什么并明确表示时。此时将他们的想法作为一个单独的 spike。
+
+### 2. Align (针对多 spike 的想法)
+
+展示 spike 表格。询问：“按此顺序全部构建，还是进行调整？” 在你编写任何代码之前，让用户进行丢弃、重新排序或重新定义。
+
+### 3. Research (针对每个 spike，在构建之前)
+
+Spikes 并非不需要研究 —— 你需要进行足够的研究来选择正确的方法，然后再进行构建。针对每个 spike：
+
+1. **简要说明。** 2-3 句话：此 spike 是什么，为何重要，关键风险是什么。
+2. **提出竞争方案**，如果存在真正的选择：
+
+   | Approach | Tool/Library | Pros | Cons | Status |
+   | ---------- | ------------- | ------ | ------ | -------- |
+   | ... | ... | ... | ... | maintained / abandoned / beta |
+
+3. **选择一个。** 说明原因。如果有 2 个以上的方案可行，可以在 spike 中构建快速的变体。
+4. **跳过研究**：适用于没有外部依赖的纯逻辑问题。
+
+在研究步骤中使用 Hermes 工具：
+
+- `web_search("python websocket streaming libraries 2025")` — 查找候选方案
+- `web_extract(urls=["https://websockets.readthedocs.io/..."])` — 阅读实际文档（返回 markdown）
+- `terminal("pip show websockets | grep Version")` — 检查项目的 venv 中安装了什么
+
+对于没有文档页面的库，通过 `read_file` 克隆并阅读它们的 `README.md` / `examples/`。Context7 MCP（如果用户已配置）也是一个很好的来源 —— 使用 `mcp_*_resolve-library-id`，然后使用 `mcp_*_query-docs`。
+
+### 4. Build
+
+每个 spike 一个目录。保持其独立性。
+
+```
+spikes/
+├── 001-websocket-streaming/
+│   ├── README.md
+│   └── main.py
+├── 002a-pdf-parse-pdfjs/
+│   ├── README.md
+│   └── parse.js
+└── 002b-pdf-parse-camelot/
+    ├── README.md
+    └── parse.py
+```
+
+**偏向于让用户能够交互的东西。** 如果 spike 的唯一输出只是一行写着“成功了”的日志，那它就失败了。用户想要*感受*到 spike 在运行。默认选择，按优先顺序：
+
+1. 一个可运行的 CLI，接受输入并打印可观察的输出
+2. 一个用于演示该行为的最小化 HTML 页面
+3. 带有一个端点的小型 Web 服务器
+4. 一个单元测试，通过可识别的断言来验证问题
+
+**深度重于速度。** 永远不要在运行了一次 happy-path（理想路径）后就宣布“它起作用了”。测试边缘情况。追踪令人惊讶的发现。只有当调查是诚实的，得出的结论才值得信赖。
+
+**除非 spike 特别要求，否则应避免：** 复杂的包管理、构建工具/bundler、Docker、env 文件、配置系统。将一切硬编码 —— 因为它只是个 spike。
+
+**构建单个 spike** —— 典型的工具序列：
+
+```
+terminal("mkdir -p spikes/001-websocket-streaming")
+write_file("spikes/001-websocket-streaming/README.md", "# 001: websocket-streaming\n\n...")
+write_file("spikes/001-websocket-streaming/main.py", "...")
+terminal("cd spikes/001-websocket-streaming && python3 main.py")
+# Observe output, iterate.
+```
+
+**并行比较型 spike (002a / 002b) —— 委派。** 当两种方法可以并行运行且都需要真正的工程设计（而不是 10 行代码的原型）时，使用 `delegate_task` 进行分发：
+
+```
+delegate_task(tasks=[
+    {"goal": "Build 002a-pdf-parse-pdfjs: ...", "toolsets": ["terminal", "file", "web"]},
+    {"goal": "Build 002b-pdf-parse-camelot: ...", "toolsets": ["terminal", "file", "web"]},
+])
+```
+
+每个 subagent 返回其各自的 verdict；你来撰写对比总结。
+
+### 5. Verdict
+
+每个 spike 的 `README.md` 结尾应包含：
+
+```markdown
+## Verdict: VALIDATED | PARTIAL | INVALIDATED
+
+### What worked
+- ...
+
+### What didn't
+- ...
+
+### Surprises
+- ...
+
+### Recommendation for the real build
+- ...
+```
+
+**VALIDATED** = 核心问题得到了“是”的回答，且有证据支持。
+**PARTIAL** = 在 X、Y、Z 约束条件下可行 —— 记录下这些条件。
+**INVALIDATED** = 不可行，因为某个原因。这是一个成功的 spike。
+
+## 比较型 Spike
+
+当两种方法回答同一个问题时（002a / 002b），将它们**背靠背**进行构建，最后进行一次面对面的比较：
+
+```markdown
+## Head-to-head: pdfjs vs camelot
+
+| Dimension | pdfjs (002a) | camelot (002b) |
+|-----------|--------------|----------------|
+| Extraction quality | 9/10 structured | 7/10 table-only |
+| Setup complexity | npm install, 1 line | pip + ghostscript |
+| Perf on 100-page PDF | 3s | 18s |
+| Handles rotated text | no | yes |
+
+**Winner:** pdfjs for our use case. Camelot if we need table-first extraction later.
+```
+
+## 边界模式（选择下一个要 spike 的内容）
+
+如果 spike 已经存在且用户询问“我接下来该 spike 什么？”，请遍历现有目录并寻找：
+
+- **集成风险** —— 两个经过验证的 spike 涉及相同的资源，但却是独立测试的
+- **数据交接** —— 假定 spike A 的输出与 spike B 的输入兼容；但从未经过证实
+- **愿景中的空白** —— 设想存在但未经证实的能力
+- **替代方案** —— 针对状态为 PARTIAL 或 INVALIDATED 的 spike 的不同切入点
+
+提供 2-4 个以 Given/When/Then 格式书写的候选项。让用户进行挑选。
+
+## 输出
+
+- 在仓库根目录下创建 `spikes/`（如果用户使用 GSD 约定，则为 `.planning/spikes/`）
+- 每个 spike 一个目录：`NNN-descriptive-name/`
+- 每个 spike 的 `README.md` 记录其问题、方法、结果和 verdict
+- 保持代码的抛弃性 —— 如果一个 spike 需要 2 天时间来“为了生产环境进行清理”，那它就是一个糟糕的 spike
+
+## 致谢
+
+改编自 GSD (Get Shit Done) 项目的 `/gsd-spike` 工作流 —— MIT © 2025 Lex Christopherson ([gsd-build/get-shit-done](https://github.com/gsd-build/get-shit-done))。完整的 GSD 系统提供持久化的 spike 状态、MANIFEST 追踪，以及与更广泛的规范驱动开发流水线的集成；可通过 `npx get-shit-done-cc --hermes --global` 安装。