better-dsh 0.2.5 → 0.3.0-c

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/bundled/software-development/software-development-spike.md

@@ -1,217 +0,0 @@
----
-title: "Spike — 在构建前验证想法的一次性实验"
-sidebar_label: "Spike"
-description: "在构建前验证想法的一次性实验"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Spike
-
-在构建前验证想法的一次性实验。
-
-## Skill 元数据
-
-| | |
-|---|---|
-| 来源 | 内置（默认安装） |
-| 路径 | `skills/software-development/spike` |
-| 版本 | `1.0.0` |
-| 作者 | Hermes Agent（改编自 gsd-build/get-shit-done） |
-| 许可证 | MIT |
-| 平台 | linux, macos, windows |
-| 标签 | `spike`, `prototype`, `experiment`, `feasibility`, `throwaway`, `exploration`, `research`, `planning`, `mvp`, `proof-of-concept` |
-| 相关 skill | [`sketch`](/user-guide/skills/bundled/creative/creative-sketch)、[`writing-plans`](/user-guide/skills/bundled/software-development/software-development-writing-plans)、[`subagent-driven-development`](/user-guide/skills/bundled/software-development/software-development-subagent-driven-development)、`plan`（现为内置 `/plan` 命令） |
-
-## 参考：完整 SKILL.md
-
-:::info
-以下是 Hermes 在触发该 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
-:::
-
-# Spike
-
-当用户想在正式构建前**摸清一个想法**时使用此 skill——验证可行性、比较方案，或暴露单靠调研无法回答的未知问题。Spike 本质上是可丢弃的。一旦完成使命，就扔掉它。
-
-当用户说出以下内容时加载此 skill："让我试试这个"、"我想看看 X 是否可行"、"spike 一下"、"在我决定用 Y 之前"、"Z 的快速原型"、"这到底可不可能？"或"比较 A 和 B"。
-
-## 何时不使用此 skill
-
-- 答案可以从文档或阅读代码中直接获得——做调研即可，不必构建
-- 工作属于生产路径——改用 `writing-plans` / `plan`
-- 想法已经验证——直接跳到实现
-
-## 如果用户安装了完整的 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 | 验证内容（Given/When/Then） | 风险 |
-|---|-------|----------------------------|------|
-| 001 | websocket-streaming | Given 一个 WS 连接，when LLM 流式输出 token，then 客户端接收到的数据块延迟 < 100ms | 高 |
-| 002a | pdf-parse-pdfjs | Given 一个多页 PDF，when 用 pdfjs 解析，then 可提取结构化文本 | 中 |
-| 002b | pdf-parse-camelot | Given 一个多页 PDF，when 用 camelot 解析，then 可提取结构化文本 | 中 |
-
-**Spike 类型：**
-- **standard（标准型）** — 一种方案回答一个问题
-- **comparison（对比型）** — 同一问题，不同方案（共享编号，字母后缀 `a`/`b`/`c`）
-
-**好的 spike 问题：** 具体的可行性问题，有可观测的输出。
-**差的 spike 问题：** 过于宽泛、无可观测输出，或仅仅是"阅读 X 的文档"。
-
-**按风险排序。** 最可能否定整个想法的 spike 优先执行。如果难点行不通，就没必要先做简单的部分。
-
-**跳过分解**的唯一情形：用户已明确知道要 spike 什么并明确说明。此时将其想法作为单个 spike 处理。
-
-### 2. 对齐（Align，适用于多 spike 想法）
-
-展示 spike 表格。询问："按此顺序全部构建，还是需要调整？"在写任何代码之前，让用户删减、重排或重新定义。
-
-### 3. 调研（Research，每个 spike 构建前）
-
-Spike 并非不需要调研——你需要调研到足以选定正确方案，然后再构建。每个 spike 的步骤：
-
-1. **简述。** 2-3 句话：这个 spike 是什么、为何重要、关键风险。
-2. **列出竞争方案**（如果存在真实选择）：
-
-   | 方案 | 工具/库 | 优点 | 缺点 | 状态 |
-   |------|---------|------|------|------|
-   | ... | ... | ... | ... | 维护中 / 已废弃 / 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 一个目录，保持独立。
-
-<!-- ascii-guard-ignore -->
-```
-spikes/
-├── 001-websocket-streaming/
-│   ├── README.md
-│   └── main.py
-├── 002a-pdf-parse-pdfjs/
-│   ├── README.md
-│   └── parse.js
-└── 002b-pdf-parse-camelot/
-    ├── README.md
-    └── parse.py
-```
-<!-- ascii-guard-ignore-end -->
-
-**偏向构建用户可以交互的东西。** Spike 失败的常见原因是唯一输出只是一行写着"it works"的日志。用户想要*感受*到 spike 在运行。默认选择，按优先级排序：
-
-1. 可运行的 CLI，接受输入并打印可观测的输出
-2. 演示该行为的最小化 HTML 页面
-3. 带有一个端点的小型 web 服务器
-4. 用可识别断言验证问题的单元测试
-
-**深度优于速度。** 绝不在一次 happy-path 运行后就宣称"它可以用"。测试边界情况，追踪意外发现。只有调查足够诚实，结论才值得信赖。
-
-**避免**以下内容（除非 spike 明确需要）：复杂的包管理、构建工具/打包器、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")
-# 观察输出，迭代。
-```
-
-**并行对比 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"]},
-])
-```
-
-每个子 agent 返回自己的结论；由你撰写对比总结。
-
-### 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
-
-| 维度 | pdfjs (002a) | camelot (002b) |
-|------|--------------|----------------|
-| 提取质量 | 9/10 结构化 | 7/10 仅表格 |
-| 配置复杂度 | npm install，1 行代码 | pip + ghostscript |
-| 100 页 PDF 性能 | 3s | 18s |
-| 处理旋转文本 | 否 | 是 |
-
-**胜者：** pdfjs 适合我们的用例。如果后续需要以表格为主的提取，再考虑 camelot。
-```
-
-## 前沿模式（决定下一步 spike 什么）
-
-如果已有 spike 存在，且用户问"下一步应该 spike 什么？"，遍历现有目录，寻找：
-
-- **集成风险** — 两个已验证的 spike 独立测试时都访问同一资源
-- **数据交接** — spike A 的输出被假设与 spike B 的输入兼容，但从未验证
-- **愿景中的空白** — 被假设但未经验证的能力
-- **替代方案** — 针对 PARTIAL 或 INVALIDATED spike 的不同角度
-
-以 Given/When/Then 形式提出 2-4 个候选，让用户选择。
-
-## 输出
-
-- 在仓库根目录创建 `spikes/`（如果用户使用 GSD 约定，则为 `.planning/spikes/`）
-- 每个 spike 一个目录：`NNN-descriptive-name/`
-- 每个 spike 的 `README.md` 记录问题、方案、结果和结论
-- 保持代码可丢弃——一个需要花 2 天"清理以投入生产"的 spike 本身就是一个失败的 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` 安装。

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/bundled/software-development/software-development-systematic-debugging.md

@@ -1,385 +0,0 @@
----
-title: "系统化调试 — 4阶段根因调试：先理解缺陷再修复"
-sidebar_label: "系统化调试"
-description: "4阶段根因调试：先理解缺陷再修复"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# 系统化调试
-
-4阶段根因调试：先理解缺陷再修复。
-
-## Skill 元数据
-
-| | |
-|---|---|
-| 来源 | 内置（默认安装） |
-| 路径 | `skills/software-development/systematic-debugging` |
-| 版本 | `1.1.0` |
-| 作者 | Hermes Agent（改编自 obra/superpowers） |
-| 许可证 | MIT |
-| 平台 | linux, macos, windows |
-| 标签 | `debugging`, `troubleshooting`, `problem-solving`, `root-cause`, `investigation` |
-| 相关 skill | [`test-driven-development`](/user-guide/skills/bundled/software-development/software-development-test-driven-development), [`writing-plans`](/user-guide/skills/bundled/software-development/software-development-writing-plans), [`subagent-driven-development`](/user-guide/skills/bundled/software-development/software-development-subagent-driven-development) |
-
-## 参考：完整 SKILL.md
-
-:::info
-以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
-:::
-
-# 系统化调试
-
-## 概述
-
-随机修复浪费时间并引入新缺陷。快速补丁会掩盖根本问题。
-
-**核心原则：** 在尝试修复之前，务必找到根因。修复症状即是失败。
-
-**违反此流程的字面规定，即违反了调试的精神。**
-
-## 铁律
-
-```
-在完成根因调查之前，禁止任何修复
-```
-
-如果尚未完成阶段 1，则不得提出修复方案。
-
-## 适用场景
-
-适用于任何技术问题：
-- 测试失败
-- 生产环境缺陷
-- 非预期行为
-- 性能问题
-- 构建失败
-- 集成问题
-
-**尤其在以下情况下使用：**
-- 时间紧迫（紧急情况容易诱发猜测）
-- "只需一个快速修复"看似显而易见
-- 已经尝试了多次修复
-- 上一次修复未生效
-- 对问题尚未完全理解
-
-**以下情况不得跳过：**
-- 问题看似简单（简单的缺陷同样有根因）
-- 时间紧迫（仓促只会导致返工）
-- 有人要求立即修复（系统化比反复折腾更快）
-
-## 四个阶段
-
-必须完成每个阶段后，才能进入下一阶段。
-
----
-
-## 阶段 1：根因调查
-
-**在尝试任何修复之前：**
-
-### 1. 仔细阅读错误信息
-
-- 不要跳过错误或警告
-- 其中往往包含确切的解决方案
-- 完整阅读堆栈跟踪
-- 记录行号、文件路径、错误代码
-
-**操作：** 对相关源文件使用 `read_file`。使用 `search_files` 在代码库中查找错误字符串。
-
-### 2. 稳定复现
-
-- 能否可靠地触发该问题？
-- 确切步骤是什么？
-- 是否每次都会发生？
-- 若无法复现 → 收集更多数据，不要猜测
-
-**操作：** 使用 `terminal` 工具运行失败的测试或触发缺陷：
-
-```bash
-# 运行特定失败测试
-pytest tests/test_module.py::test_name -v
-
-# 使用详细输出运行
-pytest tests/test_module.py -v --tb=long
-```
-
-### 3. 检查近期变更
-
-- 哪些变更可能导致此问题？
-- Git diff、近期提交
-- 新依赖、配置变更
-
-**操作：**
-
-```bash
-# 近期提交
-git log --oneline -10
-
-# 未提交的变更
-git diff
-
-# 特定文件的变更
-git log -p --follow src/problematic_file.py | head -100
-```
-
-### 4. 在多组件系统中收集证据
-
-**当系统包含多个组件时（API → 服务 → 数据库，CI → 构建 → 部署）：**
-
-**在提出修复方案之前，添加诊断埋点：**
-
-对每个组件边界：
-- 记录进入该组件的数据
-- 记录离开该组件的数据
-- 验证环境/配置的传播
-- 检查每一层的状态
-
-运行一次以收集证据，确定问题在哪里断裂。
-然后分析证据，识别出故障组件。
-再针对该具体组件展开调查。
-
-### 5. 追踪数据流
-
-**当错误深藏于调用栈时：**
-
-- 错误值从哪里产生？
-- 是什么以错误值调用了此函数？
-- 持续向上游追踪，直到找到源头
-- 在源头修复，而非在症状处修复
-
-**操作：** 使用 `search_files` 追踪引用：
-
-```python
-# 查找函数被调用的位置
-search_files("function_name(", path="src/", file_glob="*.py")
-
-# 查找变量被赋值的位置
-search_files("variable_name\\s*=", path="src/", file_glob="*.py")
-```
-
-### 阶段 1 完成检查清单
-
-- [ ] 错误信息已完整阅读并理解
-- [ ] 问题已稳定复现
-- [ ] 近期变更已识别并审查
-- [ ] 证据已收集（日志、状态、数据流）
-- [ ] 问题已定位到具体组件/代码
-- [ ] 根因假设已形成
-
-**停止：** 在理解问题发生的原因之前，不得进入阶段 2。
-
----
-
-## 阶段 2：模式分析
-
-**在修复之前找到规律：**
-
-### 1. 查找可用示例
-
-- 在同一代码库中找到类似的可用代码
-- 有哪些与故障代码相似但正常运行的代码？
-
-**操作：** 使用 `search_files` 查找可比较的模式：
-
-```python
-search_files("similar_pattern", path="src/", file_glob="*.py")
-```
-
-### 2. 与参考实现对比
-
-- 若在实现某个模式，请完整阅读参考实现
-- 不要略读——逐行阅读
-- 在应用之前完全理解该模式
-
-### 3. 识别差异
-
-- 可用代码与故障代码之间有何不同？
-- 列出每一处差异，无论多小
-- 不要假设"那不可能有影响"
-
-### 4. 理解依赖关系
-
-- 此组件需要哪些其他组件？
-- 需要哪些设置、配置、环境？
-- 它做了哪些假设？
-
----
-
-## 阶段 3：假设与验证
-
-**科学方法：**
-
-### 1. 形成单一假设
-
-- 清晰陈述："我认为 X 是根因，因为 Y"
-- 将其写下来
-- 要具体，不要模糊
-
-### 2. 最小化测试
-
-- 做出最小可能的变更来验证假设
-- 每次只改变一个变量
-- 不要同时修复多处
-
-### 3. 继续前验证
-
-- 有效？→ 进入阶段 4
-- 无效？→ 形成新假设
-- 不要在原有修复上叠加更多修复
-
-### 4. 当你不确定时
-
-- 说"我不理解 X"
-- 不要假装知道
-- 向用户寻求帮助
-- 进一步研究
-
----
-
-## 阶段 4：实施
-
-**修复根因，而非症状：**
-
-### 1. 创建失败测试用例
-
-- 尽可能简单的复现
-- 尽可能使用自动化测试
-- 修复前必须先有测试
-- 使用 `test-driven-development` skill
-
-### 2. 实施单一修复
-
-- 针对已识别的根因进行修复
-- 每次只做一处变更
-- 不做"顺手"的改进
-- 不捆绑重构
-
-### 3. 验证修复
-
-```bash
-# 运行特定回归测试
-pytest tests/test_module.py::test_regression -v
-
-# 运行完整测试套件——确认无回归
-pytest tests/ -q
-```
-
-### 4. 若修复无效——三次规则
-
-- **停止。**
-- 计数：已尝试了多少次修复？
-- 若 < 3：返回阶段 1，结合新信息重新分析
-- **若 ≥ 3：停止并质疑架构（见下方步骤 5）**
-- 不得在未进行架构讨论的情况下尝试第 4 次修复
-
-### 5. 若 3 次以上修复均失败：质疑架构
-
-**表明存在架构问题的模式：**
-- 每次修复都在不同位置暴露出新的共享状态/耦合
-- 修复需要"大规模重构"才能实施
-- 每次修复都在其他地方产生新症状
-
-**停止并质疑根本问题：**
-- 此模式从根本上是否合理？
-- 我们是否"出于惯性而坚持"？
-- 应该重构架构，还是继续修复症状？
-
-**在尝试更多修复之前，与用户讨论。**
-
-这不是假设失败——这是架构错误。
-
----
-
-## 红色警报——停止并遵循流程
-
-如果你发现自己在想：
-- "先快速修复，之后再调查"
-- "试着改一下 X，看看是否有效"
-- "添加多处变更，运行测试"
-- "跳过测试，我会手动验证"
-- "可能是 X，让我修复它"
-- "我还不完全理解，但这可能有效"
-- "模式说 X，但我会以不同方式调整"
-- "以下是主要问题：[列出修复方案，未经调查]"
-- 在追踪数据流之前提出解决方案
-- **"再试一次修复"（已尝试 2 次以上时）**
-- **每次修复都在不同位置暴露出新问题**
-
-**以上所有情况均意味着：停止。返回阶段 1。**
-
-**若 3 次以上修复均失败：** 质疑架构（阶段 4 步骤 5）。
-
-## 常见借口
-
-| 借口 | 现实 |
-|--------|---------|
-| "问题很简单，不需要流程" | 简单问题同样有根因。流程对简单缺陷而言很快。 |
-| "紧急情况，没时间走流程" | 系统化调试比猜测式反复折腾更快。 |
-| "先试试这个，再调查" | 第一次修复奠定了模式。从一开始就做对。 |
-| "确认修复有效后再写测试" | 未经测试的修复无法持久。先写测试才能证明有效。 |
-| "同时做多处修复节省时间" | 无法隔离有效的那个。会引入新缺陷。 |
-| "参考太长，我来调整模式" | 理解不完整必然导致缺陷。完整阅读。 |
-| "我看到问题了，让我修复" | 看到症状 ≠ 理解根因。 |
-| "再试一次修复"（2 次以上失败后） | 3 次以上失败 = 架构问题。质疑模式，不要再修复。 |
-
-## 快速参考
-
-| 阶段 | 关键活动 | 成功标准 |
-|-------|---------------|------------------|
-| **1. 根因** | 阅读错误、复现、检查变更、收集证据、追踪数据流 | 理解是什么以及为什么 |
-| **2. 模式** | 查找可用示例、对比、识别差异 | 知道差异所在 |
-| **3. 假设** | 形成理论、最小化测试、每次一个变量 | 已确认或形成新假设 |
-| **4. 实施** | 创建回归测试、修复根因、验证 | 缺陷已解决，所有测试通过 |
-
-## Hermes Agent 集成
-
-### 调查工具
-
-在阶段 1 中使用以下 Hermes 工具：
-
-- **`search_files`** — 查找错误字符串、追踪函数调用、定位模式
-- **`read_file`** — 带行号读取源代码，用于精确分析
-- **`terminal`** — 运行测试、检查 git 历史、复现缺陷
-- **`web_search`/`web_extract`** — 研究错误信息、查阅库文档
-
-### 与 delegate_task 配合使用
-
-对于复杂的多组件调试，派发调查子 agent：
-
-```python
-delegate_task(
-    goal="调查为何 [特定测试/行为] 失败",
-    context="""
-    遵循 systematic-debugging skill：
-    1. 仔细阅读错误信息
-    2. 复现问题
-    3. 追踪数据流以找到根因
-    4. 报告发现——暂不修复
-
-    错误：[粘贴完整错误]
-    文件：[故障代码路径]
-    测试命令：[确切命令]
-    """,
-    toolsets=['terminal', 'file']
-)
-```
-
-### 与 test-driven-development 配合使用
-
-修复缺陷时：
-1. 编写能复现缺陷的测试（RED）
-2. 系统化调试以找到根因
-3. 修复根因（GREEN）
-4. 测试证明修复有效并防止回归
-
-## 实际影响
-
-来自调试会话的数据：
-- 系统化方法：15–30 分钟完成修复
-- 随机修复方法：2–3 小时反复折腾
-- 首次修复成功率：95% vs 40%
-- 引入新缺陷：几乎为零 vs 普遍存在
-
-**没有捷径。没有猜测。系统化永远胜出。**