better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/optional/devops/devops-pinggy-tunnel.md

@@ -0,0 +1,327 @@
+---
+title: "Pinggy Tunnel — 通过 Pinggy 实现零安装 SSH localhost 隧道"
+sidebar_label: "Pinggy Tunnel"
+description: "通过 Pinggy 实现零安装 SSH localhost 隧道"
+---
+
+{/* 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. */}
+
+# Pinggy Tunnel
+
+通过 Pinggy 实现零安装 SSH localhost 隧道。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 可选 — 使用 `hermes skills install official/devops/pinggy-tunnel` 安装 |
+| 路径 | `optional-skills/devops/pinggy-tunnel` |
+| 版本 | `0.1.0` |
+| 作者 | Teknium (teknium1), Hermes Agent |
+| 许可证 | MIT |
+| 平台 | linux, macos, windows |
+| 标签 | `Pinggy`, `Tunnel`, `Networking`, `SSH`, `Webhook`, `Localhost` |
+| 相关 skill | |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。
+:::
+
+# Pinggy Tunnel Skill
+
+使用 Pinggy SSH 反向隧道将本地服务（开发服务器、webhook 接收器、MCP 端点、演示）暴露到公共互联网。无需安装任何守护进程——用户的标准 SSH 客户端连接到 `a.pinggy.io:443`，Pinggy 返回一个公共 HTTP/HTTPS URL。
+
+免费套餐：60 分钟隧道，随机子域名，无需注册。Pro 套餐（$3/月）需要 token，按需选用。
+
+## 使用时机
+
+- 用户要求"暴露本地服务"、"分享我的开发服务器"、"将此 URL 公开"、"隧道端口 N"、"为 webhook 获取公共 URL"
+- 在本地任务期间需要接收 webhook 回调（Stripe、GitHub、Discord、AgentMail）
+- 与远程方分享一次性 HTTP 演示（MCP 服务器、Ollama/vLLM 端点、仪表盘）
+- 主机有 SSH 但没有 `cloudflared` / `ngrok` 二进制文件，安装一个又显得多余
+
+如果主机已配置 `cloudflared`，优先使用 `cloudflared-quick-tunnel` skill——Cloudflare 快速隧道不会在 60 分钟后过期。
+
+## 前提条件
+
+- PATH 中有 `ssh`（`ssh -V`）。Linux、macOS 和 Windows 10+ 默认自带。无需其他安装。
+- 隧道启动前，本地服务已在 `127.0.0.1:<port>` 上监听。Pinggy 会返回 URL，但在本地源服务启动之前访问会返回 502。
+
+可选：
+
+- `PINGGY_TOKEN` 环境变量，用于付费 Pro 功能（持久子域名、自定义域名、多隧道、无 60 分钟限制）。免费套餐无需凭据。
+
+## 快速参考
+
+```bash
+# 端口 8000 的普通 HTTP/HTTPS 隧道（免费套餐）
+ssh -p 443 -o StrictHostKeyChecking=no -o ServerAliveInterval=30 \
+    -R0:localhost:8000 free@a.pinggy.io
+
+# TCP 隧道（数据库、原始 SSH 等）
+ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:5432 tcp@a.pinggy.io
+
+# TLS 隧道（Pinggy 无法解密——在源端自带证书）
+ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:443 tls@a.pinggy.io
+
+# Basic auth 认证（b:user:pass）
+ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:8000 \
+    "b:admin:secret+free@a.pinggy.io"
+
+# Bearer token 认证（k:token）
+ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:8000 \
+    "k:mysecrettoken+free@a.pinggy.io"
+
+# IP 白名单（w:CIDR）
+ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:8000 \
+    "w:203.0.113.0/24+free@a.pinggy.io"
+
+# 启用 CORS + 强制 HTTPS 重定向
+ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:8000 \
+    "co+x:https+free@a.pinggy.io"
+
+# Pro 套餐（持久 URL，无 60 分钟限制）
+ssh -p 443 -o StrictHostKeyChecking=no -R0:localhost:8000 "$PINGGY_TOKEN+a.pinggy.io"
+```
+
+## 操作流程——启动隧道并获取 URL
+
+模型应使用 `terminal` 工具。隧道在共享期间必须保持存活，因此以后台进程方式运行，并从 stdout 解析公共 URL。
+
+### 1. 确认本地源服务已启动
+
+```bash
+curl -sI http://127.0.0.1:8000/ | head -1
+# 期望返回 HTTP/1.x 200（或任何非连接拒绝的响应）
+```
+
+如果尚无服务在监听，先启动它（例如 `python3 -m http.server 8000 --bind 127.0.0.1`）。Pinggy 会正常返回 URL，但在本地源服务启动之前用户会看到 502。
+
+### 2. 以后台进程方式启动隧道
+
+使用 `terminal(background=True)` 并将输出捕获到日志文件（Pinggy 在 stdout 打印 URL 后保持连接）：
+
+```bash
+LOG=/tmp/pinggy-8000.log
+nohup ssh -p 443 \
+    -o StrictHostKeyChecking=no \
+    -o UserKnownHostsFile=/dev/null \
+    -o ServerAliveInterval=30 \
+    -o ServerAliveCountMax=3 \
+    -R0:localhost:8000 free@a.pinggy.io \
+    > "$LOG" 2>&1 &
+echo $! > /tmp/pinggy-8000.pid
+```
+
+`StrictHostKeyChecking=no` + `UserKnownHostsFile=/dev/null` 跳过首次运行的主机密钥确认提示。`ServerAliveInterval=30` 防止 SSH 会话因空闲 NAT 而被断开。
+
+### 3. 从日志中解析 URL
+
+```bash
+sleep 4
+grep -oE 'https://[a-z0-9-]+\.[a-z]+\.pinggy\.link' /tmp/pinggy-8000.log | head -1
+```
+
+预期输出如下：
+
+```
+You are not authenticated.
+Your tunnel will expire in 60 minutes.
+http://yqycl-98-162-69-48.a.free.pinggy.link
+https://yqycl-98-162-69-48.a.free.pinggy.link
+```
+
+将 `https://...pinggy.link` URL 提供给用户。
+
+### 4. 验证
+
+```bash
+curl -sI https://<the-url>/ | head -3
+# 期望返回 200/302/本地源服务实际返回的状态码
+```
+
+如果返回 `502 Bad Gateway`，说明 SSH 会话已建立但本地源服务未在监听——先修复步骤 1。
+
+### 5. 关闭隧道
+
+```bash
+kill "$(cat /tmp/pinggy-8000.pid)"
+# 或者，如果 pid 文件丢失：
+pkill -f 'ssh -p 443 .* free@a\.pinggy\.io'
+```
+
+如果有来自 `terminal(background=True)` 的 session_id，优先使用 `process(action='kill', session_id=...)`。
+
+## 通过用户名关键字进行访问控制
+
+Pinggy 将控制标志以 `+` 分隔堆叠到 SSH 用户名中。当 `user@host` 参数包含 `+` 时，始终用引号括起整个参数：
+
+| 关键字 | 效果 |
+|---------|--------|
+| `b:user:pass` | HTTP Basic auth 认证门控 |
+| `k:token` | Bearer token 请求头门控（`Authorization: Bearer <token>`） |
+| `w:CIDR` | IP 白名单（单个 IP 或 CIDR，可重复使用） |
+| `co` | 添加 `Access-Control-Allow-Origin: *`（CORS） |
+| `x:https` | 强制 HTTPS——自动将 HTTP 重定向到 HTTPS |
+| `a:Name:Value` | 添加请求头 |
+| `u:Name:Value` | 更新请求头 |
+| `r:Name` | 删除请求头 |
+| `qr` | 将 URL 的二维码打印到 stdout（便于移动端分享） |
+
+可自由组合：`"b:admin:secret+co+x:https+free@a.pinggy.io"`。
+
+## Web 调试器（可选）
+
+Pinggy 可将入站流量镜像到 `localhost:4300` 以供检查。在 SSH 命令中添加本地转发：
+
+```bash
+ssh -p 443 -L4300:localhost:4300 -R0:localhost:8000 free@a.pinggy.io
+```
+
+然后在浏览器中打开 `http://localhost:4300`，查看实时请求/响应对。
+
+## 注意事项
+
+- **免费套餐有 60 分钟硬性限制。** SSH 会话在 60 分钟时终止，URL 失效。如需更长时间的共享，使用 `PINGGY_TOKEN`（Pro）或用 shell 循环自动重启（注意免费套餐每次重启 URL 都会变化）。
+- **免费套餐 URL 是随机的，重启后会变化。** 不要收藏，不要粘贴到配置文件中。每次都从日志重新解析。
+- **同一源 IP 的并发免费隧道限制为一个。** 从同一台机器启动第二个隧道通常会终止第一个。Pro 套餐取消此限制。
+- **用户名中的 `+` 必须加引号。** 裸命令 `ssh ... b:admin:secret+free@a.pinggy.io` 在 bash 中可以工作，但在将 `+` 视为特殊字符的 shell 中或以编程方式组装时会出错。始终用双引号括起。
+- **不加访问控制标志不要隧道任何敏感内容。** 裸 HTTP 隧道对任何知道 URL 的人都可访问。对非公开服务使用 `b:`、`k:` 或 `w:`。
+- **`process(action='log')` 可能会遗漏 SSH banner 输出。** Pinggy 打印 URL 后 SSH 会话进入交互模式。始终重定向到日志文件并直接 `grep` 文件——与 `cloudflared-quick-tunnel` 相同的模式。
+- **首次运行时的主机密钥提示。** 默认 OpenSSH 配置会要求用户接受 Pinggy 的主机密钥。无人值守运行时始终传入 `-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null`。
+- **TCP 和 TLS 隧道返回 `<subdomain>.a.pinggy.online:<port>` 对，而非 https URL。** 使用不同的正则表达式解析（`tcp://` 加端口）。不要假设每个 Pinggy 隧道都是 HTTP。
+- **Pro 模式需要将 token 作为用户名，而非标志。** 使用 `"$PINGGY_TOKEN+a.pinggy.io"`（无 `free@`）。使用 token 还可以添加 `:persistent` 获得稳定子域名——参见 `pinggy.io/docs/`。
+
+## 示例配方
+
+将本地源服务与 Pinggy 隧道结合的复合模式。每个配方均自包含——启动源服务、启动隧道、解析 URL、返回给用户。
+
+### 配方 1——接收 webhook 回调
+
+当外部服务（Stripe、GitHub、Discord、AgentMail 等）需要在本地任务期间 POST 到公开可达的 URL 时使用。
+
+```bash
+# 1. 简易捕获服务器：每个请求都追加到 /tmp/webhook-hits.log
+cat >/tmp/webhook-server.py <<'PY'
+import http.server, json, datetime, pathlib
+LOG = pathlib.Path("/tmp/webhook-hits.log")
+class H(http.server.BaseHTTPRequestHandler):
+    def _capture(self):
+        n = int(self.headers.get("content-length") or 0)
+        body = self.rfile.read(n).decode("utf-8", "replace") if n else ""
+        rec = {"t": datetime.datetime.utcnow().isoformat(), "path": self.path,
+               "method": self.command, "headers": dict(self.headers), "body": body}
+        with LOG.open("a") as f: f.write(json.dumps(rec) + "\n")
+        self.send_response(200); self.send_header("content-type","application/json")
+        self.end_headers(); self.wfile.write(b'{"ok":true}\n')
+    def do_GET(self): self._capture()
+    def do_POST(self): self._capture()
+    def log_message(self,*a,**k): pass
+http.server.HTTPServer(("127.0.0.1", 18080), H).serve_forever()
+PY
+nohup python3 /tmp/webhook-server.py >/tmp/webhook-server.log 2>&1 &
+echo $! >/tmp/webhook-server.pid
+
+# 2. 隧道——使用 bearer token 门控，防止无关请求污染捕获日志
+nohup ssh -p 443 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+    -o ServerAliveInterval=30 \
+    -R0:localhost:18080 "k:$(openssl rand -hex 12)+free@a.pinggy.io" \
+    >/tmp/webhook-pinggy.log 2>&1 &
+echo $! >/tmp/webhook-pinggy.pid
+sleep 5
+URL=$(grep -oE 'https://[a-z0-9-]+\.[a-z]+\.pinggy\.link' /tmp/webhook-pinggy.log | head -1)
+echo "Webhook URL: $URL"
+
+# 3. 在 agent 工作期间，监视请求到达
+tail -f /tmp/webhook-hits.log
+```
+
+将 `$URL` 提供给需要调用你的服务。关闭：`kill $(cat /tmp/webhook-server.pid) $(cat /tmp/webhook-pinggy.pid)`。
+
+### 配方 2——通过 HTTP/SSE 暴露 MCP 服务器
+
+当远程 MCP 客户端（另一台机器上的 Claude Desktop、队友的编辑器等）需要访问本地运行的 MCP 服务器时使用。仅适用于使用 HTTP transport 的 MCP 服务器——stdio 模式的服务器无法被隧道。
+
+```bash
+# 1. 以 HTTP 模式启动 MCP 服务器（示例：端口 8765 上的 FastMCP 服务器）
+nohup python3 my_mcp_server.py --transport http --port 8765 \
+    >/tmp/mcp-server.log 2>&1 &
+echo $! >/tmp/mcp-server.pid
+
+# 2. 使用 bearer token 建立隧道——MCP 流量不应对互联网开放
+TOKEN=$(openssl rand -hex 16)
+nohup ssh -p 443 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+    -o ServerAliveInterval=30 \
+    -R0:localhost:8765 "k:$TOKEN+free@a.pinggy.io" \
+    >/tmp/mcp-pinggy.log 2>&1 &
+echo $! >/tmp/mcp-pinggy.pid
+sleep 5
+URL=$(grep -oE 'https://[a-z0-9-]+\.[a-z]+\.pinggy\.link' /tmp/mcp-pinggy.log | head -1)
+echo "MCP URL: $URL"
+echo "Bearer token: $TOKEN"
+```
+
+远程客户端使用 `Authorization: Bearer $TOKEN` 连接到 `$URL`。Hermes 原生 MCP 客户端配置：`{"transport": "http", "url": "<URL>", "headers": {"Authorization": "Bearer <TOKEN>"}}`。
+
+### 配方 3——暴露本地 LLM 端点（Ollama / vLLM / llama.cpp）
+
+与远程调用方（另一个 agent、手机、队友）共享本地模型。Ollama 监听 `:11434`，vLLM 和 llama.cpp 通常监听 `:8000`。
+
+```bash
+# 前提：模型服务器已在 127.0.0.1:11434 上运行（Ollama 默认端口）
+TOKEN=$(openssl rand -hex 16)
+nohup ssh -p 443 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+    -o ServerAliveInterval=30 \
+    -R0:localhost:11434 "k:$TOKEN+co+free@a.pinggy.io" \
+    >/tmp/llm-pinggy.log 2>&1 &
+echo $! >/tmp/llm-pinggy.pid
+sleep 5
+URL=$(grep -oE 'https://[a-z0-9-]+\.[a-z]+\.pinggy\.link' /tmp/llm-pinggy.log | head -1)
+echo "Endpoint: $URL"
+echo "Token:    $TOKEN"
+
+# 验证
+curl -s "$URL/api/tags" -H "Authorization: Bearer $TOKEN" | head
+```
+
+`co` 启用 CORS，使浏览器调用方可以访问端点。纯后端调用方可去掉 `co`。对于兼容 OpenAI 的 vLLM/llama.cpp 端点，调用方使用基础 URL `$URL/v1` 加 `Authorization: Bearer $TOKEN`——但请注意 Pinggy 不会修改请求体中的任何内容，因此本地服务器实际上会看到 Pinggy 的 token；本地服务器应配置为忽略认证（它已在 `127.0.0.1` 上），让 Pinggy 负责门控。
+
+### 配方 4——用一次性密码共享开发服务器
+
+最快的"让队友访问我正在运行的应用"模式。随机密码，打印一次，Ctrl-C 后终止。
+
+```bash
+PASS=$(openssl rand -base64 12 | tr -d '+/=' | head -c 12)
+echo "Dev server password: $PASS"
+ssh -p 443 -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
+    -o ServerAliveInterval=30 \
+    -R0:localhost:3000 "b:dev:$PASS+co+x:https+free@a.pinggy.io"
+# URL 打印到终端。分享 URL + 密码。Ctrl-C 关闭隧道。
+```
+
+`b:dev:$PASS` 使用 HTTP Basic auth 对 URL 进行门控。`x:https` 强制 TLS。`co` 为 SPA 前端添加 CORS。
+
+## 验证
+
+```bash
+# 端到端：启动一个简单的源服务，建立隧道，访问它，然后关闭
+python3 -m http.server 18000 --bind 127.0.0.1 >/tmp/origin.log 2>&1 &
+ORIGIN_PID=$!
+
+nohup ssh -p 443 \
+    -o StrictHostKeyChecking=no \
+    -o UserKnownHostsFile=/dev/null \
+    -R0:localhost:18000 free@a.pinggy.io >/tmp/pinggy-verify.log 2>&1 &
+SSH_PID=$!
+
+sleep 5
+URL=$(grep -oE 'https://[a-z0-9-]+\.[a-z]+\.pinggy\.link' /tmp/pinggy-verify.log | head -1)
+echo "URL: $URL"
+curl -sI "$URL/" | head -1
+
+kill "$SSH_PID" "$ORIGIN_PID"
+```
+
+预期结果：一个 `pinggy.link` URL 以及 curl 返回的 `HTTP/2 200`。

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/optional/devops/devops-watchers.md

@@ -0,0 +1,126 @@
+---
+title: "Watchers — 使用水印去重轮询 RSS、JSON API 和 GitHub"
+sidebar_label: "Watchers"
+description: "使用水印去重轮询 RSS、JSON API 和 GitHub"
+---
+
+{/* 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. */}
+
+# Watchers
+
+使用水印去重轮询 RSS、JSON API 和 GitHub。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 可选 — 通过 `hermes skills install official/devops/watchers` 安装 |
+| 路径 | `optional-skills/devops/watchers` |
+| 版本 | `1.0.0` |
+| 作者 | Hermes Agent |
+| 许可证 | MIT |
+| 平台 | linux, macos |
+| 标签 | `cron`, `polling`, `rss`, `github`, `http`, `automation`, `monitoring` |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
+:::
+
+# Watchers
+
+按固定间隔轮询（polling）外部数据源，仅对新条目作出响应。提供三个现成脚本及一个共享水印（watermark）辅助模块；可将其接入 cron 任务，也可从终端临时运行。
+
+## 使用场景
+
+- 用户希望监控 RSS/Atom feed 并在有新条目时收到通知
+- 用户希望监控 GitHub 仓库的 issues / pulls / releases / commits
+- 用户希望轮询任意 JSON 端点并在有新条目时收到通知
+- 用户请求"为 X 创建一个 watcher"或"当 X 变化时通知我"
+
+## 工作原理
+
+一个 watcher 本质上是一个脚本，执行以下操作：
+
+1. 从外部数据源获取数据
+2. 与记录已处理 ID 的水印文件进行比对
+3. 将新水印写回文件
+4. 将新条目打印到 stdout（无变化则不输出）
+
+以下三个脚本均实现了上述逻辑。agent 通过终端工具运行它们——来自 cron 任务、webhook 或交互式对话——并报告新内容。
+
+## 现成脚本
+
+安装 skill 后，三个脚本均位于 `$HERMES_HOME/skills/devops/watchers/scripts/`。每个脚本读取 `WATCHER_STATE_DIR`（默认为 `$HERMES_HOME/watcher-state/`）作为状态文件目录，以 `--name` 参数作为键名。
+
+| 脚本 | 监控对象 | 去重键 |
+|---|---|---|
+| `watch_rss.py` | RSS 2.0 或 Atom feed URL | `<guid>` / `<id>` |
+| `watch_http_json.py` | 任意返回对象列表的 JSON 端点 | 可配置的 id 字段 |
+| `watch_github.py` | GitHub 仓库的 issues / pulls / releases / commits | `id` / `sha` |
+
+三个脚本的共同特性：
+
+- 首次运行记录基线——不会重放已有 feed 内容
+- 水印为有界 ID 集合（最多 500 条），以限制内存占用
+- 输出格式：每条条目为 `## <title>\n<url>\n\n<optional body>`
+- 无新内容时 stdout 为空——调用方将此视为静默
+- 获取出错时返回非零退出码
+
+## 用法
+
+直接从终端工具运行 watcher：
+
+```bash
+python $HERMES_HOME/skills/devops/watchers/scripts/watch_rss.py \
+  --name hn --url https://news.ycombinator.com/rss --max 5
+```
+
+监控 GitHub 仓库（在 `~/.hermes/.env` 中设置 `GITHUB_TOKEN` 以避免匿名请求限制 60 次/小时）：
+
+```bash
+python $HERMES_HOME/skills/devops/watchers/scripts/watch_github.py \
+  --name hermes-issues --repo NousResearch/hermes-agent --scope issues
+```
+
+轮询任意 JSON API：
+
+```bash
+python $HERMES_HOME/skills/devops/watchers/scripts/watch_http_json.py \
+  --name api --url https://api.example.com/events \
+  --id-field event_id --items-path data.events
+```
+
+## 接入 cron
+
+向 agent 发送如下 prompt（提示词）以调度 cron 任务：
+
+> 每 15 分钟运行一次 `watch_rss.py --name hn --url https://news.ycombinator.com/rss`。如果有输出，则汇总标题并推送；如果没有输出，则保持静默。
+
+agent 在 cron 任务的 agent 循环中通过终端工具调用脚本，无需修改 cron 内置的 `--script` 标志。
+
+## 状态文件
+
+每个 watcher 将状态写入 `$HERMES_HOME/watcher-state/<name>.json`。查看状态：
+
+```bash
+cat $HERMES_HOME/watcher-state/hn.json
+```
+
+强制重放（下次运行视为首次轮询）：
+
+```bash
+rm $HERMES_HOME/watcher-state/hn.json
+```
+
+## 自定义 watcher
+
+三个脚本使用相同的模板：加载水印、获取数据、差异比对、保存、输出。`scripts/_watermark.py` 是共享辅助模块；导入它即可免费获得原子写入、有界 ID 集合及首次运行基线功能。参考任意一个脚本，即可了解所需的样板代码有多少。
+
+## 常见问题
+
+1. **每次 tick 都打印"无新条目"的标题。** 调用方依赖 stdout 为空来判断静默。若在空 delta 时打印任何内容，将导致频道被刷屏。已提供的脚本已处理此问题；自定义脚本也必须如此。
+2. **期望首次运行就输出条目。** 首次运行只记录基线，不会输出内容。如需初始摘要，可在首次运行后删除状态文件，或在自定义脚本中添加 `--prime-with-latest N` 标志。
+3. **水印无限增长。** 共享辅助模块上限为 500 个 ID。对于高频更新的 feed 可适当提高；在存储受限的文件系统上可适当降低。
+4. **状态目录位于 agent 沙箱无法写入的位置。** `$HERMES_HOME/watcher-state/` 始终可写。Docker/Modal 后端可能无法访问任意宿主机路径。

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/optional/dogfood/dogfood-adversarial-ux-test.md

@@ -0,0 +1,209 @@
+---
+title: "对抗性 UX 测试 — 扮演产品最难搞的技术抵触用户"
+sidebar_label: "对抗性 UX 测试"
+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. */}
+
+# 对抗性 UX 测试
+
+扮演产品最难搞、最抵触技术的用户。以该角色身份浏览应用，找出所有 UX 痛点，再通过实用主义过滤层将真实问题与噪音区分开来。仅针对真实问题创建可执行的工单。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 可选 — 通过 `hermes skills install official/dogfood/adversarial-ux-test` 安装 |
+| 路径 | `optional-skills/dogfood/adversarial-ux-test` |
+| 版本 | `1.0.0` |
+| 作者 | Omni @ Comelse |
+| 许可证 | MIT |
+| 平台 | linux, macos, windows |
+| 标签 | `qa`, `ux`, `testing`, `adversarial`, `dogfood`, `personas`, `user-testing` |
+| 相关 skill | [`dogfood`](/user-guide/skills/bundled/software-development/software-development-dogfood) |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发该 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时看到的指令内容。
+:::
+
+# 对抗性 UX 测试
+
+扮演产品的最差情况用户——那个讨厌技术、不想用你软件、并且会找各种理由抱怨的人。然后通过实用主义过滤层筛选他们的反馈，将真实的 UX 问题与"我讨厌电脑"的噪音区分开来。
+
+可以把它理解为自动化的"妈妈测试"——但更愤怒。
+
+## 为什么有效
+
+大多数 QA 找的是 bug。这个方法找的是**摩擦点**。一个技术上正确的应用对真实用户来说仍可能无法使用。对抗性角色（persona）能捕捉到：
+- 对开发者有意义但用户看不懂的术语
+- 完成基本任务需要太多步骤
+- 缺少引导或"顿悟时刻"
+- 无障碍问题（字体大小、对比度、点击目标）
+- 冷启动问题（空状态、无演示内容）
+- 阻碍转化的付费墙/注册摩擦
+
+**实用主义过滤器**（第 3 阶段）是让这个方法有用而不只是有趣的关键。没有它，你会因为爷爷搞不定 PDF 就在每个页面都加一个"打印此页"按钮。
+
+## 使用方法
+
+告诉 agent：
+```
+"Run an adversarial UX test on [URL]"
+"Be a grumpy [persona type] and test [app name]"
+"Do an asshole user test on my staging site"
+```
+
+你可以提供一个 persona，也可以让 agent 根据你的产品目标受众自动生成一个。
+
+## 第一步：定义 Persona
+
+如果未提供 persona，通过回答以下问题来生成一个：
+
+1. **谁是这个产品最难搞的用户？**（50 岁以上，非技术岗位，几十年来一直用"老方法"做事）
+2. **他们的技术熟练程度如何？**（越低越好——只用 WhatsApp、用纸质笔记本、邮箱是老婆帮设置的）
+3. **他们需要完成的那一件事是什么？**（他们的核心工作，不是你的功能列表）
+4. **什么会让他们放弃？**（点击太多、术语、速度慢、令人困惑）
+5. **他们沮丧时怎么说话？**（直接、带脏话、不屑一顾、叹气）
+
+### 好的 Persona 示例
+> **"大迈克"麦卡利斯特** — 58 岁的力量与体能教练。只用 WhatsApp，仅此而已。他的"电子表格"是一本纸质笔记本。"如果我 10 秒内搞不明白，我就回去用我的笔记本。"需要记录 25 名球员的训练结果。讨厌小字、术语和密码。
+
+### 差的 Persona 示例
+> "一个不喜欢这个应用的用户"——太模糊，没有约束，没有声音。
+
+Persona 必须**足够具体，能在 20 分钟的测试中保持角色一致性**。
+
+## 第二步：成为那个混蛋（以 Persona 身份浏览）
+
+1. 阅读所有可用的项目文档，了解应用背景和 URL
+2. **完全代入 persona**——他们的挫败感、局限性、目标
+3. 使用浏览器工具导航到应用
+4. **尝试完成 persona 的实际任务**（不是功能巡览）：
+   - 他们能做到想做的事吗？
+   - 完成任务需要多少次点击/页面跳转？
+   - 什么让他们困惑？
+   - 什么让他们愤怒？
+   - 他们在哪里迷路？
+   - 什么会让他们放弃，回到原来的方式？
+
+5. 测试以下摩擦类别：
+   - **第一印象** — 他们会不会在落地页就放弃？
+   - **核心工作流** — 他们最常需要做的那一件事
+   - **错误恢复** — 他们做错了什么会发生什么？
+   - **可读性** — 文字大小、对比度、信息密度
+   - **速度** — 感觉比他们现在的方法更快吗？
+   - **术语** — 有他们看不懂的行话吗？
+   - **导航** — 他们能找到回去的路吗？他们知道自己在哪里吗？
+
+6. 对每个痛点截图
+7. 在每个页面检查浏览器控制台的 JS 错误
+
+## 第三步：发泄（以角色身份写反馈）
+
+以 **PERSONA 的身份**写反馈——用他们的声音，带着他们的挫败感。这不是 bug 报告，这是一个真实的人在发泄。
+
+```
+[PERSONA NAME]'s Review of [PRODUCT]
+
+Overall: [Would they keep using it? Yes/No/Maybe with conditions]
+
+THE GOOD (grudging admission):
+- [things even they have to admit work]
+
+THE BAD (legitimate UX issues):
+- [real problems that would stop them from using the product]
+
+THE UGLY (showstoppers):
+- [things that would make them uninstall/cancel immediately]
+
+SPECIFIC COMPLAINTS:
+1. [Page/feature]: "[quote in persona voice]" — [what happened, expected]
+2. ...
+
+VERDICT: "[one-line persona quote summarizing their experience]"
+```
+
+## 第四步：实用主义过滤器（关键——不可跳过）
+
+走出 persona。以产品人的身份评估每条投诉：
+
+- **红色：真实 UX BUG** — 任何用户都会遇到这个问题，不只是爱抱怨的用户。修复它。
+- **黄色：有效但优先级低** — 真实问题，但只影响极端用户。记录下来。
+- **白色：Persona 噪音** — 是"我讨厌电脑"在说话，不是产品问题。跳过。
+- **绿色：功能需求** — 投诉中隐藏的好想法。考虑一下。
+
+### 过滤标准
+1. 一个 35 岁、有能力但很忙的用户会有同样的投诉吗？→ 红色
+2. 这是真实的无障碍问题（字体大小、对比度、点击目标）吗？→ 红色
+3. 这是"我想让它像纸一样工作"的数字化抵触吗？→ 白色
+4. 这是 persona 偶然发现的真实工作流低效问题吗？→ 黄色或红色
+5. 修复这个问题会给 80% 没有问题的用户增加复杂性吗？→ 白色
+6. 这条投诉是否揭示了缺失的引导时刻？→ 绿色
+
+**此过滤器是强制性的。** 永远不要将原始 persona 投诉直接作为工单提交。
+
+## 第五步：创建工单
+
+仅针对**红色**和**绿色**条目：
+- 清晰、可执行的标题
+- 包含 persona 的原话（有趣且令人印象深刻）
+- 其背后的真实 UX 问题（客观）
+- 建议的修复方案（可执行）
+- 标签/标记："ux-review"
+
+针对**黄色**条目：创建一个汇总所有备注的综合工单。
+
+**白色**条目仅出现在报告中，不创建工单。
+
+**每次会话最多 10 个工单** — 专注于最严重的问题。
+
+## 第六步：报告
+
+交付内容：
+1. Persona 发泄内容（第三步）——有趣且直击痛点
+2. 过滤后的评估（第四步）——务实且可执行
+3. 已创建的工单（第五步）——附链接
+4. 关键问题的截图
+
+## 技巧
+
+- **每次会话只用一个 persona。** 不要混合视角。
+- **在第二步和第三步期间保持角色。** 只在第四步才打破角色。
+- **优先测试核心工作流。** 不要被设置页面分散注意力。
+- **空状态是金矿。** 新用户体验揭示的摩擦最多。
+- **最好的发现是 persona 在做其他事情时意外发现的红色条目。**
+- **如果 persona 零投诉，说明你的 persona 技术水平太高了。** 让他们更老、更没耐心、更固执。
+- **在演示、发布前或发布一批功能后运行此测试。**
+- **尽可能以新用户身份注册。** 不要使用预置的管理员账户——冷启动体验才是大多数摩擦所在。
+- **零白色条目是一个信号，不是失败。** 如果实用主义过滤器没有发现噪音，说明你的产品有真实的 UX 问题，而不只是一个爱抱怨的 persona。
+- **测试结束后再查看项目文档中的已知问题。** 如果 persona 发现了一个已在已知问题列表中的 bug，这实际上是最有力的发现——这意味着团队知道这个问题，但从未真正感受过用户的痛苦。
+- **订阅/付费墙测试至关重要。** 用已过期的账户测试，而不只是活跃账户。"无法付款时会发生什么"的体验揭示了产品是否尊重用户，还是扣押他们的数据。
+- **统计完成 persona 那一件核心任务所需的点击次数。** 如果超过 5 次，无论 persona 的技术水平如何，这几乎总是一个红色发现。
+
+## 各行业 Persona 示例
+
+以下是起点——请根据你的具体产品进行定制：
+
+| 产品类型 | Persona | 年龄 | 关键特征 |
+|-------------|---------|-----|-----------|
+| CRM | 养老院院长 | 68 | 文件柜就是现在的 CRM |
+| 摄影 SaaS | 农村婚礼摄影师 | 62 | 电话接单，纸质开票 |
+| AI/ML 工具 | 百货公司采购 | 55 | 被 3 个失败的科技创业公司坑过 |
+| 健身应用 | 老派健身教练 | 58 | 纸质笔记本、手指粗、眼睛不好 |
+| 会计 | 家庭面包店老板 | 64 | 一鞋盒收据，讨厌订阅制 |
+| 电商 | 集市摊主 | 60 | 只收现金，智能手机只用来打电话 |
+| 医疗 | 资深全科医生 | 63 | 口述笔记，护士负责操作电脑 |
+| 教育 | 资深教师 | 57 | 粉笔加讲授，活页夹里的讲义 |
+
+## 规则
+
+- 在第二步和第三步期间保持角色
+- 真实地刻薄但公平——找真实问题，不要制造问题
+- 实用主义过滤器（第四步）是**强制性的**
+- 每条投诉都需要截图
+- 每次会话最多 10 个工单
+- 在 staging/已部署的应用上测试，不要在本地开发环境测试
+- 一个 persona，一次会话，一份报告