@baimingtao/lbs-agent 1.0.0

package/extensions/skills/builtin/software-development/node-inspect-debugger/SKILL.md

@@ -0,0 +1,319 @@
+---
+name: node-inspect-debugger
+description: "通过 --inspect + Chrome DevTools Protocol CLI 调试 Node.js。"
+version: 1.0.0
+author: Hermes Agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [debugging, nodejs, node-inspect, cdp, breakpoints, ui-tui]
+    related_skills: [systematic-debugging, python-debugpy, debugging-hermes-tui-commands]
+---
+
+# Node.js Inspect Debugger
+
+## 概览
+
+当 `console.log` 不够用时，可以通过终端以编程方式驱动 Node 内置的 V8 inspector。你可以获得真实的断点、单步跳入/跳过/跳出、调用栈遍历、局部/闭包作用域转储，以及在暂停帧中执行任意表达式求值。
+
+提供两种工具，任选其一：
+
+- **`node inspect`** — 内置、免安装、CLI REPL。最适合快速排查。
+- **`ndb` / 通过 `chrome-remote-interface` 使用 CDP** — 可通过 Node/Python 脚本化；适合需要自动化设置大量断点、收集多次运行状态，或从 agent 循环中进行非交互式调试的场景。
+
+**首选 `node inspect`。** 它随时可用且 REPL 速度很快。
+
+## 使用场景
+
+- Node 测试失败，需要查看中间状态
+- ui-tui 崩溃或表现异常，想在渲染前检查 React/Ink 状态
+- tui_gateway 子进程（`_SlashWorker`、PTY 桥接 worker）表现异常
+- 需要检查 `console.log` 在不修改代码的情况下无法触及的闭包中的值
+- 性能分析：附加到运行中的进程以捕获 CPU profile 或 heap snapshot
+
+**不适用于：** `console.log` 在一分钟内就能解决的问题。基于断点的调试成本较高；仅在确有成效时使用。
+
+## 快速参考：`node inspect` REPL
+
+在首行暂停启动：
+
+```bash
+node inspect path/to/script.js
+# 或配合 tsx
+node --inspect-brk $(which tsx) path/to/script.ts
+```
+
+`debug>` 提示符支持的命令：
+
+| 命令 | 动作 |
+|---|---|
+| `c` 或 `cont` | 继续执行 |
+| `n` 或 `next` | 单步跳过 |
+| `s` 或 `step` | 单步跳入 |
+| `o` 或 `out` | 单步跳出 |
+| `pause` | 暂停运行中的代码 |
+| `sb('file.js', 42)` | 在 file.js 第 42 行设置断点 |
+| `sb(42)` | 在当前文件第 42 行设置断点 |
+| `sb('functionName')` | 在函数被调用时中断 |
+| `cb('file.js', 42)` | 清除断点 |
+| `breakpoints` | 列出所有断点 |
+| `bt` | 回溯（调用栈） |
+| `list(5)` | 显示当前位置周围 5 行源码 |
+| `watch('expr')` | 在每次暂停时对表达式求值 |
+| `watchers` | 显示监视的表达式 |
+| `repl` | 进入当前作用域的 REPL（按 Ctrl+C 退出 REPL） |
+| `exec expr` | 对表达式求值一次 |
+| `restart` | 重启脚本 |
+| `kill` | 终止脚本 |
+| `.exit` | 退出 debugger |
+
+**在 `repl` 子模式中：** 输入任何 JS 表达式，包括访问局部/闭包变量。按 `Ctrl+C` 退回 `debug>`。
+
+## 附加到运行中的进程
+
+当进程已经在运行时（例如长期运行的开发服务器或 TUI gateway）：
+
+```bash
+# 1. 发送 SIGUSR1 以在现有进程上启用 inspector
+kill -SIGUSR1 <pid>
+# Node 输出：Debugger listening on ws://127.0.0.1:9229/<uuid>
+
+# 2. 附加调试器 CLI
+node inspect -p <pid>
+# 或通过 URL
+node inspect ws://127.0.0.1:9229/<uuid>
+```
+
+要从一开始就启用 inspector 启动进程：
+
+```bash
+node --inspect script.js           # 监听 127.0.0.1:9229，保持运行
+node --inspect-brk script.js       # 监听并在首行暂停
+node --inspect=0.0.0.0:9230 script.js   # 自定义 host:port
+```
+
+通过 tsx 运行 TypeScript：
+
+```bash
+node --inspect-brk --import tsx script.ts
+# 或旧版 tsx
+node --inspect-brk -r tsx/cjs script.ts
+```
+
+## 可编程 CDP（通过终端脚本化）
+
+当你想要自动化时——例如设置大量断点、捕获作用域状态、编写复现脚本——可以使用 `chrome-remote-interface`：
+
+```bash
+npm i -g chrome-remote-interface        # 或安装到项目本地
+# 启动目标：
+node --inspect-brk=9229 target.js &
+```
+
+驱动脚本（保存为 `/tmp/cdp-debug.js`）：
+
+```javascript
+const CDP = require('chrome-remote-interface');
+
+(async () => {
+  const client = await CDP({ port: 9229 });
+  const { Debugger, Runtime } = client;
+
+  Debugger.paused(async ({ callFrames, reason }) => {
+    const top = callFrames[0];
+    console.log(`PAUSED: ${reason} @ ${top.url}:${top.location.lineNumber + 1}`);
+
+    // Walk scopes for locals
+    for (const scope of top.scopeChain) {
+      if (scope.type === 'local' || scope.type === 'closure') {
+        const { result } = await Runtime.getProperties({
+          objectId: scope.object.objectId,
+          ownProperties: true,
+        });
+        for (const p of result) {
+          console.log(`  ${scope.type}.${p.name} =`, p.value?.value ?? p.value?.description);
+        }
+      }
+    }
+
+    // Evaluate an expression in the paused frame
+    const { result } = await Debugger.evaluateOnCallFrame({
+      callFrameId: top.callFrameId,
+      expression: 'typeof state !== "undefined" ? JSON.stringify(state) : "n/a"',
+    });
+    console.log('state =', result.value ?? result.description);
+
+    await Debugger.resume();
+  });
+
+  await Runtime.enable();
+  await Debugger.enable();
+
+  // Set a breakpoint by URL regex + line
+  await Debugger.setBreakpointByUrl({
+    urlRegex: '.*app\\.tsx$',
+    lineNumber: 119,       // 0-indexed
+    columnNumber: 0,
+  });
+
+  await Runtime.runIfWaitingForDebugger();
+})();
+```
+
+运行它：
+
+```bash
+node /tmp/cdp-debug.js
+```
+
+Hermes 特别提示：`chrome-remote-interface` 并未包含在 `ui-tui/package.json` 中。如果你不想污染项目，可以将其安装到一个临时的位置：
+
+```bash
+mkdir -p /tmp/cdp-tools && cd /tmp/cdp-tools && npm i chrome-remote-interface
+NODE_PATH=/tmp/cdp-tools/node_modules node /tmp/cdp-debug.js
+```
+
+## 调试 Hermes ui-tui
+
+TUI 基于 Ink + tsx 构建。有两种常见场景：
+
+### 开发环境下调试单个 Ink 组件
+
+`ui-tui/package.json` 包含 `npm run dev` (tsx --watch)。通过直接运行 tsx 来添加 `--inspect-brk`：
+
+```bash
+cd /home/bb/hermes-agent/ui-tui
+npm run build    # 先生成一次 dist/，这样首次加载时就不需要转译了
+node --inspect-brk dist/entry.js
+# 在另一个终端中：
+node inspect -p <node pid>
+```
+
+然后在 `debug>` 中：
+
+```
+sb('dist/app.js', 220)     # 或者在可疑渲染发生的地方
+cont
+```
+
+当它暂停时，使用 `repl` → 检查 `props`、state refs、`useInput` handler 的值等。
+
+### 调试运行中的 `hermes --tui`
+
+TUI 是通过 Python CLI 产生的 Node 进程。最简单的方式：
+
+```bash
+# 1. 启动 TUI
+hermes --tui &
+TUI_PID=$(pgrep -f 'ui-tui/dist/entry' | head -1)
+
+# 2. 在那个 Node PID 上启用 inspector
+kill -SIGUSR1 "$TUI_PID"
+
+# 3. 找到 WS URL
+curl -s http://127.0.0.1:9229/json/list | jq -r '.[0].webSocketDebuggerUrl'
+
+# 4. 附加
+node inspect ws://127.0.0.1:9229/<uuid>
+```
+
+与 TUI 交互（在其窗口中输入）会继续推进执行；你的 debugger 可以随时通过 `sb(...)` 断点将其暂停。
+
+### 调试 `_SlashWorker` / PTY 子进程
+
+这些是 Python 进程，而不是 Node —— 请为它们使用 `python-debugpy` 技能。只有 Node 部分（Ink UI、tui_gateway client、`ui-tui/` 下由 tsx 运行的测试）才使用此技能。
+
+## 在 Debugger 下运行 Vitest 测试
+
+```bash
+cd /home/bb/hermes-agent/ui-tui
+# 运行单个测试文件，并在入口处暂停
+node --inspect-brk ./node_modules/vitest/vitest.mjs run --no-file-parallelism src/app/foo.test.tsx
+```
+
+在另一个终端中：`node inspect -p <pid>`，然后执行 `sb('src/app/foo.tsx', 42)`，`cont`。
+
+使用 `--no-file-parallelism`（vitest）或 `--runInBand`（jest），这样就只会存在一个 worker —— 调试进程池是非常痛苦的。
+
+## Heap Snapshots 与 CPU Profiles（非交互式）
+
+在上面的 CDP 驱动脚本中，将 Debugger 替换为 `HeapProfiler` / `Profiler`：
+
+```javascript
+// 5 秒的 CPU profile
+await client.Profiler.enable();
+await client.Profiler.start();
+await new Promise(r => setTimeout(r, 5000));
+const { profile } = await client.Profiler.stop();
+require('fs').writeFileSync('/tmp/cpu.cpuprofile', JSON.stringify(profile));
+// 在 Chrome DevTools → Performance 标签页中打开 /tmp/cpu.cpuprofile
+```
+
+```javascript
+// Heap snapshot
+await client.HeapProfiler.enable();
+const chunks = [];
+client.HeapProfiler.addHeapSnapshotChunk(({ chunk }) => chunks.push(chunk));
+await client.HeapProfiler.takeHeapSnapshot({ reportProgress: false });
+require('fs').writeFileSync('/tmp/heap.heapsnapshot', chunks.join(''));
+```
+
+## 常见陷阱
+
+1. **TS 源码行号不匹配。** 断点命中在生成的 JS 中，而不是 `.ts` 文件。可以 (a) 在构建出的 `dist/*.js` 中打断点，或者 (b) 启用 sourcemaps（`node --enable-source-maps`）并使用 `sb('src/app.tsx', N)` —— 但仅适用于遵循 sourcemaps 的 CDP 客户端。`node inspect` CLI 并不遵循它。
+
+2. **`--inspect` 与 `--inspect-brk` 的区别。** `--inspect` 会启动 inspector 但不会暂停；如果你附加得太晚，脚本会直接越过你的第一个断点。当你需要在任何代码运行之前设置断点时，请使用 `--inspect-brk`。
+
+3. **端口冲突。** 默认端口是 `9229`。如果有多个 Node 进程正在被调试，请传递 `--inspect=0`（随机端口）并从 `/json/list` 读取实际的 URL：
+   ```bash
+   curl -s http://127.0.0.1:9229/json/list   # 列出主机上所有可检查的目标
+   ```
+
+4. **子进程。** 在父进程上使用 `--inspect` 不会检查其子进程。使用 `NODE_OPTIONS='--inspect-brk' node parent.js` 将其传播给每个子进程；注意它们都需要唯一的端口（当继承 `NODE_OPTIONS='--inspect'` 时，Node 会自动递增端口）。
+
+5. **后台终止。** 如果你在目标暂停时通过 `Ctrl+C` 退出 `node inspect`，目标将保持暂停状态。请先执行 `cont`，或者显式地 `kill` 目标。
+
+6. **通过 agent 终端运行 `node inspect`。** 它是一个对 PTY 友好的 REPL。在 Hermes 中，使用 `terminal(pty=true)` 或 `background=true` + `process(action='submit', data='...')` 启动它。非 PTY 的前台模式适用于一次性命令，但不适用于交互式单步调试。
+
+7. **安全。** `--inspect=0.0.0.0:9229` 会暴露任意代码执行权限。除非你处于隔离的网络环境中，否则请始终绑定到 `127.0.0.1`（默认行为）。
+
+## 验证清单
+
+建立调试会话后，请验证：
+
+- [ ] `curl -s http://127.0.0.1:9229/json/list` 准确返回了你预期的目标
+- [ ] 第一个断点确实命中了（如果没有，很可能是因为你遗漏了 `--inspect-brk` 或在执行完成后才附加）
+- [ ] 暂停时的源码列表显示了正确的文件（不匹配意味着 sourcemap 问题，参见陷阱 1）
+- [ ] 在 `repl` 中执行 `exec process.pid` 返回了你打算附加的 PID
+
+## 一键配方
+
+**“为什么这个变量在第 X 行是 undefined？”**
+```bash
+node --inspect-brk script.js &
+node inspect -p $!
+# debug>
+sb('script.js', X)
+cont
+# paused. Now:
+repl
+> myVariable
+> Object.keys(this)
+```
+
+**“进入这个函数的调用路径是什么？”**
+```
+debug> sb('suspectFn')
+debug> cont
+# paused on entry
+debug> bt
+```
+
+**“这个 async 链卡住了 —— 在哪里？”**
+```
+# Start with --inspect (no -brk), let it run to the hang, then:
+debug> pause
+debug> bt
+# Now you see the stuck frame
+```

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

@@ -0,0 +1,338 @@
+---
+name: plan
+description: "计划模式：编写可执行的 markdown 计划到 .hermes/plans/，不执行任何操作。小步拆解任务，提供精确路径和完整代码。"
+version: 2.0.0
+author: Hermes Agent (writing-craft adapted from obra/superpowers)
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [planning, plan-mode, implementation, workflow, design, documentation]
+    related_skills: [subagent-driven-development, test-driven-development, requesting-code-review]
+---
+
+# 计划模式 (Plan Mode)
+
+当用户需要一个计划而不是执行时，使用此 skill。
+
+## 核心行为
+
+在这一轮对话中，你只负责制定计划。
+
+- 不要实现代码。
+- 除了计划 markdown 文件外，不要编辑任何项目文件。
+- 不要运行会改变系统状态的终端命令，不要 commit、push 或执行任何外部操作。
+- 如有需要，你可以使用只读命令/工具检查 repo 或其他上下文。
+- 你的交付物是一份保存在当前工作区 `.hermes/plans/` 目录下的 markdown 计划。
+
+## 输出要求
+
+编写具体且可执行的 markdown 计划。
+
+在相关时包含以下内容：
+- 目标
+- 当前上下文 / 假设
+- 建议的方法
+- 逐步计划
+- 可能修改的文件
+- 测试 / 验证
+- 风险、权衡和待解决问题
+
+如果任务与代码相关，请提供确切的文件路径、可能的测试目标和验证步骤。
+
+## 保存位置
+
+使用 `write_file` 将计划保存至：
+- `.hermes/plans/YYYY-MM-DD_HHMMSS-<slug>.md`
+
+将此视为相对于当前工作目录 / 后端工作区的路径。Hermes 文件工具具备后端感知能力，因此使用此相对路径可以确保计划与 local、docker、ssh、modal 和 daytona 后端上的工作区保持关联。
+
+如果运行时提供了特定的目标路径，请使用该确切路径。
+如果没有，请在 `.hermes/plans/` 下自行创建一个合理的带有时间戳的文件名。
+
+## 交互风格
+
+- 如果请求足够明确，直接编写计划。
+- 如果 `/plan` 没有附带明确的指令，请从当前的对话上下文中推断任务。
+- 如果确实定义不明确，请提出简短的澄清问题，而不是盲目猜测。
+- 保存计划后，简短回复你规划的内容以及保存的路径。
+
+---
+
+# 编写优秀的计划
+
+本 skill 的其余部分是关于编写*优秀*实现计划的手艺，即上述 markdown 文件中的具体内容。
+
+## 概览
+
+在编写全面的实现计划时，应假设实施者对代码库毫无了解，且审美品味堪忧。记录下他们需要的一切：要修改哪些文件、完整的代码、测试命令、要查阅的文档以及如何验证。为他们提供小步拆解的任务。遵循 DRY、YAGNI、TDD 原则。频繁提交。
+
+假设实施者是一位有能力的开发者，但对工具链或问题领域几乎一无所知。假设他们不太懂得如何设计优秀的测试。
+
+**核心原则：** 优秀的计划能让实现变得显而易见。如果有人需要猜测，说明计划还不够完整。
+
+## 何时需要完整的实现计划
+
+**务必在以下情况前使用：**
+- 实现多步骤的特性
+- 拆解复杂需求
+- 通过 subagent-driven-development 委派给子代理 (subagents)
+
+**在这些情况也不要跳过：**
+- 特性看起来很简单（假设往往会导致 bug）
+- 你打算自己来实现它（未来的你也需要指导）
+- 独立工作（文档很重要）
+
+## 小步拆解的任务粒度
+
+**每个任务 = 2-5 分钟的专注工作。**
+
+每一步只做一个动作：
+- “编写失败的测试” — 一步
+- “运行测试确保它失败” — 一步
+- “编写最少的代码使测试通过” — 一步
+- “运行测试并确保它们通过” — 一步
+- “提交” — 一步
+
+**太大了：**
+```markdown
+### Task 1: Build authentication system
+[50 lines of code across 5 files]
+```
+
+**大小适中：**
+```markdown
+### Task 1: Create User model with email field
+[10 lines, 1 file]
+
+### Task 2: Add password hash field to User
+[8 lines, 1 file]
+
+### Task 3: Create password hashing utility
+[15 lines, 1 file]
+```
+
+## 计划文档结构
+
+### 头部信息 (必需)
+
+每个计划必须以以下内容开头：
+
+```markdown
+# [Feature Name] Implementation Plan
+
+> **For Hermes:** Use subagent-driven-development skill to implement this plan task-by-task.
+
+**Goal:** [One sentence describing what this builds]
+
+**Architecture:** [2-3 sentences about approach]
+
+**Tech Stack:** [Key technologies/libraries]
+
+---
+```
+
+### 任务结构
+
+每个任务遵循以下格式：
+
+````markdown
+### Task N: [Descriptive Name]
+
+**Objective:** What this task accomplishes (one sentence)
+
+**Files:**
+- Create: `exact/path/to/new_file.py`
+- Modify: `exact/path/to/existing.py:45-67` (line numbers if known)
+- Test: `tests/path/to/test_file.py`
+
+**Step 1: Write failing test**
+
+```python
+def test_specific_behavior():
+    result = function(input)
+    assert result == expected
+```
+
+**Step 2: Run test to verify failure**
+
+Run: `pytest tests/path/test.py::test_specific_behavior -v`
+Expected: FAIL — "function not defined"
+
+**Step 3: Write minimal implementation**
+
+```python
+def function(input):
+    return expected
+```
+
+**Step 4: Run test to verify pass**
+
+Run: `pytest tests/path/test.py::test_specific_behavior -v`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add tests/path/test.py src/path/file.py
+git commit -m "feat: add specific feature"
+```
+````
+
+## 编写过程
+
+### Step 1: 理解要求
+
+阅读并理解：
+- 特性需求
+- 设计文档或用户描述
+- 验收标准
+- 约束条件
+
+### Step 2: 探索代码库
+
+使用 Hermes 工具了解项目：
+
+```python
+# Understand project structure
+search_files("*.py", target="files", path="src/")
+
+# Look at similar features
+search_files("similar_pattern", path="src/", file_glob="*.py")
+
+# Check existing tests
+search_files("*.py", target="files", path="tests/")
+
+# Read key files
+read_file("src/app.py")
+```
+
+### Step 3: 设计方法
+
+决定：
+- 架构模式
+- 文件组织结构
+- 所需依赖
+- 测试策略
+
+### Step 4: 编写任务
+
+按以下顺序创建任务：
+1. 配置/基础设施
+2. 核心功能（每一项都采用 TDD）
+3. 边缘情况
+4. 集成
+5. 清理/文档
+
+### Step 5: 添加完整细节
+
+对于每个任务，包含：
+- **确切的文件路径**（不是“配置文件”，而是 `src/config/settings.py`）
+- **完整的代码示例**（不是“添加验证”，而是实际代码）
+- **确切的命令**及其预期输出
+- **验证步骤**，证明任务有效
+
+### Step 6: 审查计划
+
+检查：
+- [ ] 任务是有序且合乎逻辑的
+- [ ] 每个任务都是小步拆解的（2-5 分钟）
+- [ ] 文件路径是确切的
+- [ ] 代码示例是完整的（可直接复制粘贴）
+- [ ] 命令是确切的且带有预期输出
+- [ ] 没有遗漏上下文
+- [ ] 应用了 DRY、YAGNI、TDD 原则
+
+## 原则
+
+### DRY (Don't Repeat Yourself)
+
+**反面教材：** 在 3 个地方复制粘贴验证逻辑
+**正面教材：** 提取验证函数，在所有地方复用
+
+### YAGNI (You Aren't Gonna Need It)
+
+**反面教材：** 为未来的需求添加“灵活性”
+**正面教材：** 只实现当前需要的功能
+
+```python
+# Bad — YAGNI violation
+class User:
+    def __init__(self, name, email):
+        self.name = name
+        self.email = email
+        self.preferences = {}  # Not needed yet!
+        self.metadata = {}     # Not needed yet!
+
+# Good — YAGNI
+class User:
+    def __init__(self, name, email):
+        self.name = name
+        self.email = email
+```
+
+### TDD (测试驱动开发)
+
+每个生成代码的任务都应包含完整的 TDD 循环：
+1. 编写失败的测试
+2. 运行以验证失败
+3. 编写最少的代码
+4. 运行以验证通过
+
+详情请参阅 `test-driven-development` skill。
+
+### 频繁提交
+
+在每个任务完成后提交：
+```bash
+git add [files]
+git commit -m "type: description"
+```
+
+## 常见错误
+
+### 任务模糊
+
+**反面教材：** “添加身份验证”
+**正面教材：** “创建包含 email 和 password_hash 字段的 User model”
+
+### 代码不完整
+
+**反面教材：** “Step 1: 添加验证函数”
+**正面教材：** “Step 1: 添加验证函数”，后跟完整的函数代码
+
+### 缺少验证
+
+**反面教材：** “Step 3: 测试是否有效”
+**正面教材：** “Step 3: 运行 `pytest tests/test_auth.py -v`，预期：3 passed”
+
+### 缺少文件路径
+
+**反面教材：** “创建模型文件”
+**正面教材：** “创建：`src/models/user.py`”
+
+## 执行交接
+
+保存计划后，提供执行方案：
+
+**“计划已完成并保存。准备好使用 subagent-driven-development 来执行了——我将为每个任务分发一个新的子代理，并进行两阶段审查（先检查规范符合性，再检查代码质量）。要我继续吗？”**
+
+在执行时，使用 `subagent-driven-development` skill：
+- 为每个任务分发带有完整上下文的全新 `delegate_task`
+- 每个任务完成后进行规范符合性审查
+- 规范通过后进行代码质量审查
+- 只有在两项审查都通过时才继续
+
+## 切记
+
+```
+Bite-sized tasks (2-5 min each)
+Exact file paths
+Complete code (copy-pasteable)
+Exact commands with expected output
+Verification steps
+DRY, YAGNI, TDD
+Frequent commits
+```
+
+**优秀的计划能让实现变得显而易见。**