better-dsh 0.2.5 → 0.3.0

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

@@ -1,327 +0,0 @@
----
-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

@@ -1,126 +0,0 @@
----
-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

@@ -1,209 +0,0 @@
----
-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，一次会话，一份报告