@baimingtao/lbs-agent 1.0.0

package/extensions/skills/builtin/creative/touchdesigner-mcp/references/troubleshooting.md

@@ -0,0 +1,244 @@
+# TouchDesigner 故障排除 (twozero MCP)
+
+> 查看 `references/pitfalls.md` 获取完整的经验教训列表。
+
+## 1. 连接问题
+
+### Port 40404 not responding
+
+按顺序检查以下各项：
+
+1. TouchDesigner 是否正在运行？
+   ```bash
+   pgrep TouchDesigner
+   ```
+
+1b. 快速 Hub 健康检查（无需 JSON-RPC）：
+   对 MCP URL 发起普通的 GET 请求会返回实例信息：
+   ```
+   curl -s http://localhost:40404/mcp
+   ```
+   返回：`{"hub": true, "pid": ..., "instances": {"127.0.0.1_PID": {"project": "...", "tdVersion": "...", ...}}}`
+   如果返回了 JSON 但 `instances` 为空，说明 TD 正在运行，但 twozero 尚未注册。
+
+2. TD 中是否安装了 twozero？
+   打开 TD Palette Browser > 应该列出 twozero。如果没有，请安装它。
+
+3. twozero 设置中是否启用了 MCP？
+   在 TD 中，打开 twozero 首选项并确认 MCP server 已开启。
+
+4. 直接测试端口：
+   ```bash
+   nc -z 127.0.0.1 40404
+   ```
+
+5. 测试 MCP 端点：
+   ```bash
+   curl -s http://localhost:40404/mcp
+   ```
+   应该返回包含 hub 信息的 JSON。如果是这样，说明服务器正在运行。
+
+### Hub 响应但没有 TD 实例
+
+twozero MCP hub 正在运行，但 TD 尚未注册。原因：
+- TD 项目尚未加载（仍停留在启动画面）
+- twozero COMP 未在当前项目中初始化
+- twozero 版本不匹配
+
+修复：打开/重新加载包含 twozero COMP 的 TD 项目。使用 td_list_instances
+检查哪些 TD 实例已注册。
+
+### 多实例设置
+
+twozero 会为多个 TD 实例自动分配端口：
+- 第一个实例：40404
+- 第二个实例：40405
+- 第三个实例：40406
+- 以此类推。
+
+使用 `td_list_instances` 发现所有正在运行的实例及其端口。
+
+## 2. MCP Tool 错误
+
+### td_execute_python 返回错误
+
+td_execute_python 的错误消息通常包含 Python 堆栈追踪。
+如果不清楚，请使用 `td_read_textport` 查看完整的 TD 控制台输出 ——
+Python 异常总是会打印在那里。
+
+常见原因：
+- 脚本中有语法错误
+- 引用了不存在的节点（op() 返回 None，然后你调用了 None 的 .par）
+- 使用了错误的参数名称（参见 pitfalls.md）
+
+### td_set_operator_pars 失败
+
+参数名称不匹配是首要原因。该工具会验证参数名称并
+返回清晰的错误，但你必须使用完全一致的名称。
+
+修复：始终先调用 `td_get_par_info` 来发现真实的参数名称：
+```
+td_get_par_info(op_type='glslTOP')
+td_get_par_info(op_type='noiseTOP')
+```
+
+### td_create_operator 类型名称错误
+
+Operator 类型名称使用 camelCase 并带有族后缀：
+- 正确：noiseTOP, glslTOP, levelTOP, compositeTOP, audiospectrumCHOP
+- 错误：NoiseTOP, noise_top, NOISE TOP, Noise
+
+### 使用 td_get_operator_info 进行深度检查
+
+如果对 operator 的任何方面（参数、输入、输出、状态）不确定：
+```
+td_get_operator_info(path='/project1/noise1', detail='full')
+```
+
+## 3. Parameter Discovery（参数发现）
+
+关键：始终使用 td_get_par_info 来发现参数名称。
+
+Agent 的 LLM 训练数据中包含 TouchDesigner 的错误参数名称。
+不要相信它们。已知错误的名称包括 dat vs pixeldat, colora vs alpha,
+sizex vs size 等等。完整列表请参见 pitfalls.md。
+
+工作流：
+1. td_get_par_info(op_type='glslTOP') — 获取某个类型的所有参数
+2. td_get_operator_info(path='/project1/mynode', detail='full') — 获取特定实例的参数
+3. 仅使用这些工具返回的名称
+
+## 4. 性能
+
+### 诊断运行缓慢
+
+使用 `td_get_perf` 查看哪些 operator 运行缓慢。查看 cook 时间 ——
+任何每帧超过 1ms 的情况都值得调查。
+
+常见原因：
+- 分辨率过高（特别是在 Non-Commercial 许可证下）
+- 复杂的 GLSL shader
+- 过多的 TOP-to-CHOP 或 CHOP-to-TOP 传输（GPU-CPU 内存复制）
+- 没有衰减的 Feedback 循环（数值不断累积，内存占用增加）
+
+### Non-Commercial 许可证限制
+
+- 分辨率上限：1280x1280。设置 resolutionw=1920 会被静默限制为 1280。
+- H.264/H.265/AV1 编码需要 Commercial 许可证。请改用 ProRes 或 Hap。
+- 输出不得用于商业用途。
+
+创建后始终检查实际生效的分辨率：
+```python
+n.cook(force=True)
+actual = str(n.width) + 'x' + str(n.height)
+```
+
+## 5. Hermes 配置
+
+### 配置 location
+
+`$HERMES_HOME/config.yaml`（当未设置 `HERMES_HOME` 时，默认为 `~/.hermes/config.yaml`）
+
+### MCP entry 格式
+
+twozero TD 的 entry 应如下所示：
+```yaml
+mcpServers:
+  twozero_td:
+    url: http://localhost:40404/mcp
+```
+
+### 修改配置后
+
+重启 Hermes 会话以使更改生效。MCP 连接在
+会话启动时建立。
+
+### 验证 MCP tools 是否可用
+
+重启后，会话日志应显示 twozero MCP tools 已注册。
+如果 tools 显示为已注册但无法调用，请检查：
+- twozero MCP hub 是否仍在运行（执行上文的 curl 测试）
+- TD 是否仍在运行并加载了项目
+- 是否有防火墙阻止了 localhost:40404
+
+## 6. 节点创建问题
+
+### "Node type not found" 错误
+
+类型字符串错误。使用带有族后缀的 camelCase 格式：
+- 错误：NoiseTop, noise_top, NOISE TOP
+- 正确：noiseTOP
+
+### 节点已创建但不可见
+
+检查 parentPath —— 使用绝对路径，如 /project1。默认的 project
+根目录是 /project1。系统节点位于 /, /ui, /sys, /local, /perform。
+不要在 /project1 之外创建用户节点。
+
+### 无法在 non-COMP 内创建节点
+
+只有 COMP operators（Container, Base, Geometry 等）可以包含子节点。
+你不能在 TOP, CHOP, SOP, DAT 或 MAT 内部创建节点。
+
+## 7. 连线问题
+
+### 跨族连线
+
+TOP 连接到 TOP，CHOP 连接到 CHOP，SOP 连接到 SOP，DAT 连接到 DAT。
+使用转换 operators 进行桥接：choptoTOP, topToCHOP, soptoDAT 等。
+
+注意：choptoTOP 没有输入连接器。请改用 par.chop 引用：
+```python
+spec_tex.par.chop = resample_node  # 正确
+# 不是：resample.outputConnectors[0].connect(spec_tex.inputConnectors[0])
+```
+
+### Feedback 循环
+
+永远不要直接创建 A -> B -> A。使用 Feedback TOP：
+```python
+fb = root.create(feedbackTOP, 'fb')
+fb.par.top = comp.path          # 仅引用，不需要连线到 fb 输入
+fb.outputConnectors[0].connect(next_node)
+```
+在此链条上出现 "Cook dependency loop detected" 警告是预期且正确的。
+
+## 8. GLSL 问题
+
+### Shader 编译错误是静默的
+
+GLSL TOP 在 UI 中会显示黄色警告，但 node.errors() 可能返回空。
+请同时检查 node.warnings()。创建一个 Info DAT 指向该 GLSL TOP 以
+获取完整的编译器输出。
+
+### TD GLSL 细节
+
+- 使用 GLSL 4.60（Vulkan 后端）。GLSL 3.30 及更早版本已被移除。
+- UV 坐标：vUV.st（不是 gl_FragCoord）
+- 输入纹理：sTD2DInputs[0]
+- 输出：layout(location = 0) out vec4 fragColor
+- macOS 关键提示：始终使用 TDOutputSwizzle(color) 包装输出
+- 没有内置的 time uniform。通过 GLSL TOP Values 页面或 Constant TOP 传递时间。
+
+## 9. 录制问题
+
+### H.264/H.265/AV1 需要 Commercial 许可证
+
+在 macOS 上使用 Apple ProRes（硬件加速，不受许可证限制）：
+```python
+rec.par.videocodec = 'prores'  # macOS 上首选 —— 无损，Non-Commercial 可用
+# rec.par.videocodec = 'mjpa'  # 备选方案 —— 有损，全平台兼容
+```
+
+### MovieFileOut 没有 .record() 方法
+
+使用 toggle 参数：
+```python
+rec.par.record = True   # 开始
+rec.par.record = False  # 停止
+```
+
+### 所有导出的帧完全相同
+
+快速连续调用时，TOP.save() 会截获相同的帧。请使用 MovieFileOut 进行
+实时录制。设置 project.realTime = False 以实现精确到帧的输出。

package/extensions/skills/builtin/creative/touchdesigner-mcp/scripts/setup.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+# setup.sh — Automated setup for twozero MCP plugin for TouchDesigner
+# Idempotent: safe to run multiple times.
+set -euo pipefail
+
+GREEN='\033[0;32m'; RED='\033[0;31m'; YELLOW='\033[1;33m'; CYAN='\033[0;36m'; NC='\033[0m'
+OK="${GREEN}✔${NC}"; FAIL="${RED}✘${NC}"; WARN="${YELLOW}⚠${NC}"
+
+TWOZERO_URL="https://www.404zero.com/pisang/twozero.tox"
+TOX_PATH="$HOME/Downloads/twozero.tox"
+HERMES_HOME_DIR="${HERMES_HOME:-$HOME/.hermes}"
+HERMES_CFG="${HERMES_HOME_DIR}/config.yaml"
+MCP_PORT=40404
+MCP_ENDPOINT="http://localhost:${MCP_PORT}/mcp"
+
+manual_steps=()
+
+echo -e "\n${CYAN}═══ twozero MCP for TouchDesigner — Setup ═══${NC}\n"
+
+# ── 1. Check if TouchDesigner is running ──
+# Match on process *name* (not full cmdline) to avoid self-matching shells
+# that happen to have "TouchDesigner" in their args. macOS and Linux pgrep
+# both support -x for exact name match.
+if pgrep -x TouchDesigner >/dev/null 2>&1 || pgrep -x TouchDesignerFTE >/dev/null 2>&1; then
+    echo -e " ${OK} TouchDesigner is running"
+    td_running=true
+else
+    echo -e " ${WARN} TouchDesigner is not running"
+    td_running=false
+fi
+
+# ── 2. Ensure twozero.tox exists ──
+if [[ -f "$TOX_PATH" ]]; then
+    echo -e " ${OK} twozero.tox already exists at ${TOX_PATH}"
+else
+    echo -e " ${WARN} twozero.tox not found — downloading..."
+    if curl -fSL -o "$TOX_PATH" "$TWOZERO_URL" 2>/dev/null; then
+        echo -e " ${OK} Downloaded twozero.tox to ${TOX_PATH}"
+    else
+        echo -e " ${FAIL} Failed to download twozero.tox from ${TWOZERO_URL}"
+        echo "       Please download manually and place at ${TOX_PATH}"
+        manual_steps+=("Download twozero.tox from ${TWOZERO_URL} to ${TOX_PATH}")
+    fi
+fi
+
+# ── 3. Ensure Hermes config has twozero_td MCP entry ──
+if [[ ! -f "$HERMES_CFG" ]]; then
+    echo -e " ${FAIL} Hermes config not found at ${HERMES_CFG}"
+    manual_steps+=("Create ${HERMES_CFG} with twozero_td MCP server entry")
+elif grep -q 'twozero_td' "$HERMES_CFG" 2>/dev/null; then
+    echo -e " ${OK} twozero_td MCP entry exists in Hermes config"
+else
+    echo -e " ${WARN} Adding twozero_td MCP entry to Hermes config..."
+    python3 -c "
+import yaml, sys, copy
+
+cfg_path = '$HERMES_CFG'
+with open(cfg_path, 'r') as f:
+    cfg = yaml.safe_load(f) or {}
+
+if 'mcp_servers' not in cfg:
+    cfg['mcp_servers'] = {}
+
+if 'twozero_td' not in cfg['mcp_servers']:
+    cfg['mcp_servers']['twozero_td'] = {
+        'url': '${MCP_ENDPOINT}',
+        'timeout': 120,
+        'connect_timeout': 60
+    }
+    with open(cfg_path, 'w') as f:
+        yaml.dump(cfg, f, default_flow_style=False, sort_keys=False)
+" 2>/dev/null && echo -e " ${OK} twozero_td MCP entry added to config" \
+              || { echo -e " ${FAIL} Could not update config (is PyYAML installed?)"; \
+                   manual_steps+=("Add twozero_td MCP entry to ${HERMES_CFG} manually"); }
+    manual_steps+=("Restart Hermes session to pick up config change")
+fi
+
+# ── 4. Test if MCP port is responding ──
+if nc -z 127.0.0.1 "$MCP_PORT" 2>/dev/null; then
+    echo -e " ${OK} Port ${MCP_PORT} is open"
+
+    # ── 5. Verify MCP endpoint responds ──
+    resp=$(curl -s --max-time 3 "$MCP_ENDPOINT" 2>/dev/null || true)
+    if [[ -n "$resp" ]]; then
+        echo -e " ${OK} MCP endpoint responded at ${MCP_ENDPOINT}"
+    else
+        echo -e " ${WARN} Port open but MCP endpoint returned empty response"
+        manual_steps+=("Verify MCP is enabled in twozero settings")
+    fi
+else
+    echo -e " ${WARN} Port ${MCP_PORT} is not open"
+    if [[ "$td_running" == true ]]; then
+        manual_steps+=("In TD: drag twozero.tox into network editor → click Install")
+        manual_steps+=("Enable MCP: twozero icon → Settings → mcp → 'auto start MCP' → Yes")
+    else
+        manual_steps+=("Launch TouchDesigner")
+        manual_steps+=("Drag twozero.tox into the TD network editor and click Install")
+        manual_steps+=("Enable MCP: twozero icon → Settings → mcp → 'auto start MCP' → Yes")
+    fi
+fi
+
+# ── Status Report ──
+echo -e "\n${CYAN}═══ Status Report ═══${NC}\n"
+
+if [[ ${#manual_steps[@]} -eq 0 ]]; then
+    echo -e " ${OK} ${GREEN}Fully configured! twozero MCP is ready to use.${NC}\n"
+    exit 0
+else
+    echo -e " ${WARN} ${YELLOW}Manual steps remaining:${NC}\n"
+    for i in "${!manual_steps[@]}"; do
+        echo -e "   $((i+1)). ${manual_steps[$i]}"
+    done
+    echo ""
+    exit 1
+fi

package/extensions/skills/builtin/data-science/DESCRIPTION.md

@@ -0,0 +1,3 @@
+---
+description: 用于数据科学工作流的 Skills —— 交互式探索、Jupyter notebooks、数据分析与可视化。
+---

package/extensions/skills/builtin/data-science/jupyter-live-kernel/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: jupyter-live-kernel
+description: "通过实时 Jupyter kernel (hamelnb) 进行迭代式 Python 开发。"
+version: 1.0.0
+author: Hermes Agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [jupyter, notebook, repl, data-science, exploration, iterative]
+    category: data-science
+---
+
+# Jupyter Live Kernel (hamelnb)
+
+通过实时运行的 Jupyter kernel 为您提供一个**有状态的 Python REPL**。变量在不同执行之间会保持持久化。当您需要增量构建状态、探索 API、检查 DataFrames 或迭代复杂代码时，请使用此工具而不是 `execute_code`。
+
+## 何时使用此工具与其他工具
+
+| 工具 | 使用场景 |
+| ------ | ---------- |
+| **此技能** | 迭代探索、跨步骤状态、数据科学、机器学习、“让我试一下并检查结果” |
+| `execute_code` | 需要 hermes 工具访问权限（web_search、文件操作）的一次性脚本。无状态。 |
+| `terminal` | Shell 命令、构建、安装、git、进程管理 |
+
+**经验法则：** 如果您觉得这项任务适合用 Jupyter notebook 来完成，就使用此技能。
+
+## 前置条件
+
+1. 必须安装 **uv**（检查方式：`which uv`）
+2. 必须安装 **JupyterLab**：`uv tool install jupyterlab`
+3. 必须有一个正在运行的 Jupyter 服务器（参见下方的设置说明）
+
+## 配置
+
+hamelnb 脚本位置：
+```
+SCRIPT="$HOME/.agent-skills/hamelnb/skills/jupyter-live-kernel/scripts/jupyter_live_kernel.py"
+```
+
+如果尚未克隆：
+```
+git clone https://github.com/hamelsmu/hamelnb.git ~/.agent-skills/hamelnb
+```
+
+### 启动 JupyterLab
+
+检查是否已有服务器正在运行：
+```
+uv run "$SCRIPT" servers
+```
+
+如果没有找到服务器，请启动一个：
+```
+jupyter-lab --no-browser --port=8888 --notebook-dir=$HOME/notebooks \
+  --IdentityProvider.token='' --ServerApp.password='' > /tmp/jupyter.log 2>&1 &
+sleep 3
+```
+
+注意：为了方便本地 Agent 访问，已禁用 Token/密码。服务器以无头（headless）模式运行。
+
+### 为 REPL 创建 Notebook
+
+如果您只是需要一个 REPL（没有现成的 notebook），请创建一个最小的 notebook 文件：
+```
+mkdir -p ~/notebooks
+```
+编写一个仅包含一个空代码单元的最小 .ipynb JSON 文件，然后通过 Jupyter REST API 启动一个 kernel 会话：
+```
+curl -s -X POST http://127.0.0.1:8888/api/sessions \
+  -H "Content-Type: application/json" \
+  -d '{"path":"scratch.ipynb","type":"notebook","name":"scratch.ipynb","kernel":{"name":"python3"}}'
+```
+
+## 核心工作流
+
+所有命令都会返回结构化的 JSON。请始终使用 `--compact` 以节省 token。
+
+### 1. 发现服务器与 notebook
+
+```
+uv run "$SCRIPT" servers --compact
+uv run "$SCRIPT" notebooks --compact
+```
+
+### 2. 执行代码（主要操作）
+
+```
+uv run "$SCRIPT" execute --path <notebook.ipynb> --code '<python code>' --compact
+```
+
+状态会在多次 execute 调用之间保持持久化。变量、导入和对象都会被保留。
+
+多行代码可以使用 $'...' 引号包裹：
+```
+uv run "$SCRIPT" execute --path scratch.ipynb --code $'import os\nfiles = os.listdir(".")\nprint(f"Found {len(files)} files")' --compact
+```
+
+### 3. 检查实时变量
+
+```
+uv run "$SCRIPT" variables --path <notebook.ipynb> list --compact
+uv run "$SCRIPT" variables --path <notebook.ipynb> preview --name <varname> --compact
+```
+
+### 4. 编辑 notebook 单元
+
+```
+# 查看当前单元
+uv run "$SCRIPT" contents --path <notebook.ipynb> --compact
+
+# 插入新单元
+uv run "$SCRIPT" edit --path <notebook.ipynb> insert \
+  --at-index <N> --cell-type code --source '<code>' --compact
+
+# 替换单元源码（使用 contents 输出中的 cell-id）
+uv run "$SCRIPT" edit --path <notebook.ipynb> replace-source \
+  --cell-id <id> --source '<new code>' --compact
+
+# 删除单元
+uv run "$SCRIPT" edit --path <notebook.ipynb> delete --cell-id <id> --compact
+```
+
+### 5. 验证（重启 + 运行全部）
+
+仅当用户要求进行干净的验证，或者您需要确认 notebook 从上到下都能正常运行时才使用：
+
+```
+uv run "$SCRIPT" restart-run-all --path <notebook.ipynb> --save-outputs --compact
+```
+
+## 实用经验技巧
+
+1. **服务器启动后的首次执行可能会超时** —— kernel 需要一点时间来初始化。如果遇到超时，直接重试即可。
+
+2. **Kernel 使用的 Python 环境就是 JupyterLab 的 Python 环境** —— 必须在该环境中安装所需的依赖包。如果您需要额外的包，请先将其安装到 JupyterLab 的工具环境中。
+
+3. **--compact 参数可大幅节省 token** —— 请务必始终使用。如果不加此参数，JSON 输出会非常冗长。
+
+4. **如果仅作为纯 REPL 使用**，只需创建一个 scratch.ipynb 并忽略单元编辑。只需反复调用 `execute` 即可。
+
+5. **参数顺序很重要** —— 像 `--path` 这样的子命令参数必须放在次级子命令之前。例如：应使用 `variables --path nb.ipynb list` 而不是 `variables list --path nb.ipynb`。
+
+6. **如果会话尚不存在**，您需要先通过 REST API 启动一个（参见“配置”章节）。没有活跃的 kernel 会话，工具就无法执行代码。
+
+7. **错误信息会以 JSON 格式连同 traceback 一起返回** —— 阅读 `ename` 和 `evalue` 字段即可了解出错原因。
+
+8. **偶发的 websocket 超时** —— 某些操作可能会在首次尝试时超时，尤其是在 kernel 重启之后。在升级报错前，请至少重试一次。
+
+## 默认超时时间
+
+该脚本每次执行的默认超时时间为 30 秒。如果是长时间运行的操作，请传入 `--timeout 120`。在初始设置或进行大量计算时，请设置宽松一些的超时时间（60 秒以上）。

package/extensions/skills/builtin/dogfood/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: dogfood
+description: "Web 应用的探索性 QA：发现 bug、收集证据并生成报告。"
+version: 1.0.0
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [qa, testing, browser, web, dogfood]
+    related_skills: []
+---
+
+# Dogfood：系统化的 Web 应用 QA 测试
+
+## 概览
+
+本技能将指导你使用浏览器工具集对 Web 应用进行系统化的探索性 QA 测试。你将浏览应用程序、与元素进行交互、捕获问题的证据，并生成结构化的 bug 报告。
+
+## 前置条件
+
+- 必须提供浏览器工具集（`browser_navigate`、`browser_snapshot`、`browser_click`、`browser_type`、`browser_vision`、`browser_console`、`browser_scroll`、`browser_back`、`browser_press`）
+- 用户需提供目标 URL 和测试范围
+
+## 输入
+
+由用户提供：
+1. **目标 URL** — 测试的入口点
+2. **范围** — 需要重点关注的区域/功能（或填写 "full site" 以进行全面测试）
+3. **输出目录**（可选） — 用于保存截图和报告的位置（默认为：`./dogfood-output`）
+
+## 工作流程
+
+请遵循以下 5 阶段的系统化工作流程：
+
+### 阶段 1：规划
+
+1. 创建输出目录结构：
+   ```
+   {output_dir}/
+   ├── screenshots/       # 问题证据截图
+   └── report.md          # 最终报告（在阶段 5 中生成）
+   ```
+2. 根据用户输入确定测试范围。
+3. 通过规划要测试的页面和功能来构建一个大致的站点地图：
+   - 着陆页/主页
+   - 导航链接（页眉、页脚、侧边栏）
+   - 关键用户流程（注册、登录、搜索、结账等）
+   - 表单和交互元素
+   - 边缘情况（空状态、错误页面、404 等）
+
+### 阶段 2：探索
+
+对于计划中的每个页面或功能：
+
+1. **导航**至该页面：
+   ```
+   browser_navigate(url="https://example.com/page")
+   ```
+
+2. **获取快照**以了解 DOM 结构：
+   ```
+   browser_snapshot()
+   ```
+
+3. **检查控制台**是否存在 JavaScript 错误：
+   ```
+   browser_console(clear=true)
+   ```
+   每次导航和每次重要交互之后都要执行此操作。隐蔽的 JS 错误是极具价值的发现。
+
+4. **截取带注释的屏幕截图**，以直观评估页面并识别交互元素：
+   ```
+   browser_vision(question="Describe the page layout, identify any visual issues, broken elements, or accessibility concerns", annotate=true)
+   ```
+   `annotate=true` 标志会在交互元素上叠加带编号的 `[N]` 标签。每个 `[N]` 都会映射到后续浏览器命令中的 ref `@eN`。
+
+5. 系统地**测试交互元素**：
+   - 点击按钮和链接：`browser_click(ref="@eN")`
+   - 填写表单：`browser_type(ref="@eN", text="test input")`
+   - 测试键盘导航：`browser_press(key="Tab")`, `browser_press(key="Enter")`
+   - 滚动浏览内容：`browser_scroll(direction="down")`
+   - 使用无效输入测试表单验证
+   - 测试空提交
+
+6. **每次交互后**，检查：
+   - 控制台错误：`browser_console()`
+   - 视觉变化：`browser_vision(question="What changed after the interaction?")`
+   - 预期行为与实际行为对比
+
+### 阶段 3：收集证据
+
+对于发现的每个问题：
+
+1. **截取屏幕截图**以展示问题：
+   ```
+   browser_vision(question="Capture and describe the issue visible on this page", annotate=false)
+   ```
+   保存响应中的 `screenshot_path` — 你将在报告中引用它。
+
+2. **记录详细信息**：
+   - 出现问题的 URL
+   - 复现步骤
+   - 预期行为
+   - 实际行为
+   - 控制台错误（如果有）
+   - 截图路径
+
+3. 使用问题分类法对问题进行**分类**（参见 `references/issue-taxonomy.md`）：
+   - 严重程度：Critical / High / Medium / Low
+   - 类别：Functional / Visual / Accessibility / Console / UX / Content
+
+### 阶段 4：归类
+
+1. 审查所有收集到的问题。
+2. 去重 — 合并那些在不同地方表现为同一个 bug 的问题。
+3. 为每个问题分配最终的严重程度和类别。
+4. 按严重程度排序（首先是 Critical，然后依次是 High、Medium、Low）。
+5. 按严重程度和类别统计问题数量，用于执行摘要。
+
+### 阶段 5：报告
+
+使用 `templates/dogfood-report-template.md` 中的模板生成最终报告。
+
+报告必须包含：
+1. **执行摘要**，包含问题总数、按严重程度划分的明细以及测试范围
+2. **针对每个问题的部分**，包含：
+   - 问题编号和标题
+   - 严重程度和类别徽章
+   - 观察到问题的 URL
+   - 问题描述
+   - 复现步骤
+   - 预期行为与实际行为对比
+   - 截图引用（内联图片请使用 `MEDIA:<screenshot_path>`）
+   - 相关的控制台错误（如果有）
+3. 所有问题**汇总表**
+4. **测试说明** — 测试了什么、未测试什么、以及遇到的任何阻碍
+
+将报告保存到 `{output_dir}/report.md`。
+
+## 工具 参考
+
+| 工具 | 用途 |
+| ------ | --------- |
+| `browser_navigate` | 前往指定的 URL |
+| `browser_snapshot` | 获取 DOM 文本快照（无障碍树） |
+| `browser_click` | 通过 ref (`@eN`) 或文本点击元素 |
+| `browser_type` | 在输入框中输入内容 |
+| `browser_scroll` | 在页面上上下滚动 |
+| `browser_back` | 在浏览器历史记录中后退 |
+| `browser_press` | 按下键盘上的键 |
+| `browser_vision` | 截图 + AI 分析；使用 `annotate=true` 获取元素标签 |
+| `browser_console` | 获取 JS 控制台输出和错误 |
+
+## 提示
+
+- **务必在导航后和重要交互后检查 `browser_console()`。** 隐蔽的 JS 错误是最有价值的发现之一。
+- 当需要分析交互元素的位置或快照 ref 不清晰时，**结合 `browser_vision` 使用 `annotate=true`**。
+- **同时使用有效和无效的输入进行测试** — 表单验证 bug 非常常见。
+- **滚动浏览长页面** — 折叠下方的内容可能会存在渲染问题。
+- **测试导航流程** — 完整点击多步骤流程进行端到端测试。
+- 通过记录截图中可见的任何布局问题来**检查响应式行为**。
+- **不要忘记边缘情况**：空状态、超长文本、特殊字符、快速连续点击。
+- 向用户报告截图时，请包含 `MEDIA:<screenshot_path>`，以便他们能够看到内联的证据。