@baimingtao/lbs-agent 1.0.0

package/extensions/skills/builtin/autonomous-ai-agents/hermes-agent/references/native-mcp.md

@@ -0,0 +1,344 @@
+# Native MCP Client
+
+Hermes Agent 内置了 MCP 客户端，它会在启动时连接到 MCP 服务器，发现其工具，并将其作为 agent 可直接调用的一等工具提供。无需 bridge CLI —— 来自 MCP 服务器的工具会与 `terminal`、`read_file` 等内置工具并列显示。
+
+## 何时使用
+
+当你想要执行以下操作时，请使用此功能：
+- 连接到 MCP 服务器并在 Hermes Agent 中使用其工具
+- 通过 MCP 添加外部功能（文件系统访问、GitHub、数据库、API）
+- 运行基于本地 stdio 的 MCP 服务器（npx、uvx 或任何命令）
+- 连接到远程 HTTP/StreamableHTTP MCP 服务器
+- 让 MCP 工具在每次对话中被自动发现并可用
+
+如果想要在不进行任何配置的情况下，直接从终端进行临时的一次性 MCP 工具调用，请参阅 `mcporter` skill。
+
+## 前置条件
+
+- **mcp Python package** —— 可选依赖；使用 `pip install mcp` 安装。如果未安装，MCP 支持将被静默禁用。
+- **Node.js** —— 基于的 `npx` 的 MCP 服务器（大多数社区服务器）所必需。
+- **uv** —— 基于的 `uvx` 的 MCP 服务器（基于 Python 的服务器）所必需。
+
+安装 MCP SDK：
+
+```bash
+pip install mcp
+# or, if using uv:
+uv pip install mcp
+```
+
+## 快速开始
+
+在 `~/.hermes/config.yaml` 中的 `mcp_servers` 键下添加 MCP 服务器：
+
+```yaml
+mcp_servers:
+  time:
+    command: "uvx"
+    args: ["mcp-server-time"]
+```
+
+重启 Hermes Agent。在启动时，它会：
+1. 连接到服务器
+2. 发现可用工具
+3. 以 `mcp_time_*` 为前缀注册它们
+4. 将它们注入到所有平台工具集中
+
+然后你就可以自然地使用这些工具了 —— 只需让 agent 获取当前时间即可。
+
+## 配置参考
+
+`mcp_servers` 下的每个条目都是一个映射到其配置的服务器名称。有两种传输类型：**stdio**（基于命令）和 **HTTP**（基于 url）。
+
+### Stdio Transport (command + args)
+
+```yaml
+mcp_servers:
+  server_name:
+    command: "npx"             # (required) executable to run
+    args: ["-y", "pkg-name"]   # (optional) command arguments, default: []
+    env:                       # (optional) environment variables for the subprocess
+      SOME_API_KEY: "value"
+    timeout: 120               # (optional) per-tool-call timeout in seconds, default: 120
+    connect_timeout: 60        # (optional) initial connection timeout in seconds, default: 60
+```
+
+### HTTP Transport (url)
+
+```yaml
+mcp_servers:
+  server_name:
+    url: "https://my-server.example.com/mcp"   # (required) server URL
+    headers:                                     # (optional) HTTP headers
+      Authorization: "Bearer sk-..."
+    timeout: 180               # (optional) per-tool-call timeout in seconds, default: 120
+    connect_timeout: 60        # (optional) initial connection timeout in seconds, default: 60
+```
+
+### 所有配置选项
+
+| 选项 | 类型 | 默认值 | 说明 |
+|-------------------|--------|---------|---------------------------------------------------|
+| `command` | string | -- | Executable to run (stdio transport, required) |
+| `args` | list | `[]` | Arguments passed to the command |
+| `env` | dict | `{}` | Extra environment variables for the subprocess |
+| `url` | string | -- | Server URL (HTTP transport, required) |
+| `headers` | dict | `{}` | HTTP headers sent with every request |
+| `timeout` | int | `120` | Per-tool-call timeout in seconds |
+| `connect_timeout` | int | `60` | Timeout for initial connection and discovery |
+
+注意：一个服务器配置必须包含 `command` (stdio) 或 `url` (HTTP) 两者之一，不能同时包含。
+
+## 工作原理
+
+### 启动发现
+
+当 Hermes Agent 启动时，会在工具初始化期间调用 `discover_mcp_tools()`：
+
+1. 从 `~/.hermes/config.yaml` 读取 `mcp_servers`
+2. 对于每个服务器，在专用的后台事件循环中生成一个连接
+3. 初始化 MCP 会话并调用 `list_tools()` 来发现可用工具
+4. 在 Hermes 工具注册表中注册每个工具
+
+### 工具命名约定
+
+MCP 工具使用以下命名模式注册：
+
+```
+mcp_{server_name}_{tool_name}
+```
+
+为了兼容 LLM API，名称中的连字符和点会被替换为下划线。
+
+示例：
+- Server `filesystem`, tool `read_file` → `mcp_filesystem_read_file`
+- Server `github`, tool `list-issues` → `mcp_github_list_issues`
+- Server `my-api`, tool `fetch.data` → `mcp_my_api_fetch_data`
+
+### 自动注入
+
+发现完成后，MCP 工具会自动注入到所有 `hermes-*` 平台工具集（CLI、Discord、Telegram 等）中。这意味着 MCP 工具在每次对话中都可用，无需任何额外配置。
+
+### 连接生命周期
+
+- 每个服务器都作为长期运行的 asyncio Task 在后台守护线程中运行
+- 连接在整个 agent 进程的生命周期内持续存在
+- 如果连接断开，会自动进行带有指数退避的重连（最多重试 5 次，最长 60 秒退避）
+- 在 agent 关闭时，所有连接都会被优雅地关闭
+
+### 幂等性
+
+`discover_mcp_tools()` 是幂等的 —— 多次调用它只会连接到尚未连接的服务器。失败的服务器将在后续调用中重试。
+
+## 传输类型
+
+### Stdio Transport
+
+最常见的传输方式。Hermes 将 MCP 服务器作为子进程启动，并通过 stdin/stdout 进行通信。
+
+```yaml
+mcp_servers:
+  filesystem:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
+```
+
+子进程继承**已过滤的**环境（请参阅下文的安全部分）以及你在 `env` 中指定的任何变量。
+
+### HTTP / StreamableHTTP Transport
+
+用于远程或共享的 MCP 服务器。要求 `mcp` 包包含 HTTP 客户端支持 (`mcp.client.streamable_http`)。
+
+```yaml
+mcp_servers:
+  remote_api:
+    url: "https://mcp.example.com/mcp"
+    headers:
+      Authorization: "Bearer sk-..."
+```
+
+如果你安装的 `mcp` 版本不支持 HTTP，该服务器将抛出 ImportError 失败，而其他服务器将继续正常运行。
+
+## 安全
+
+### 环境变量过滤
+
+对于 stdio 服务器，Hermes 不会将你完整的 shell 环境传递给 MCP 子进程。仅继承安全的基线变量：
+
+- `PATH`, `HOME`, `USER`, `LANG`, `LC_ALL`, `TERM`, `SHELL`, `TMPDIR`
+- 任何 `XDG_*` 变量
+
+除非你通过 `env` 配置键显式添加，否则所有其他环境变量（API keys、tokens、secrets）都将被排除。这可以防止意外将凭证泄露给不受信任的 MCP 服务器。
+
+```yaml
+mcp_servers:
+  github:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-github"]
+    env:
+      # Only this token is passed to the subprocess
+      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..."
+```
+
+### 错误消息中的凭证脱敏
+
+如果 MCP 工具调用失败，错误消息中的任何类凭证模式在显示给 LLM 之前都会自动进行脱敏处理。这涵盖：
+
+- GitHub PATs (`ghp_...`)
+- OpenAI 风格的密钥 (`sk-...`)
+- Bearer tokens
+- 通用的 `token=`、`key=`、`API_KEY=`、`password=`、`secret=` 模式
+
+## 故障排查
+
+### "MCP SDK not available -- skipping MCP tool discovery"
+
+未安装 `mcp` Python 包。安装它：
+
+```bash
+pip install mcp
+```
+
+### "No MCP servers configured"
+
+`~/.hermes/config.yaml` 中没有 `mcp_servers` 键，或者该键为空。请至少添加一个服务器。
+
+### "Failed to connect to MCP server 'X'"
+
+常见原因：
+- **Command not found**：`command` 二进制文件不在 PATH 中。请确保已安装 `npx`、`uvx` 或相关命令。
+- **Package not found**：对于 npx 服务器，npm 包可能不存在，或者可能需要在 args 中使用 `-y` 来自动安装。
+- **Timeout**：服务器启动时间过长。请增加 `connect_timeout`。
+- **Port conflict**：对于 HTTP 服务器，URL 可能无法访问。
+
+### "MCP server 'X' requires HTTP transport but mcp.client.streamable_http is not available"
+
+你的 `mcp` 包版本不包含 HTTP 客户端支持。请升级：
+
+```bash
+pip install --upgrade mcp
+```
+
+### 工具未出现
+
+- 检查服务器是否列在 `mcp_servers` 下（而不是 `mcp` 或 `servers`）
+- 确保 YAML 缩进正确
+- 查看 Hermes Agent 启动日志中的连接消息
+- 工具名称以 `mcp_{server}_{tool}` 为前缀 —— 查找该模式
+
+### 连接持续断开
+
+客户端最多重试 5 次，采用指数退避（1秒、2秒、4秒、8秒、16秒，上限为 60 秒）。如果服务器根本无法访问，它将在尝试 5 次后放弃。请检查服务器进程和网络连接。
+
+## 示例
+
+### Time Server (uvx)
+
+```yaml
+mcp_servers:
+  time:
+    command: "uvx"
+    args: ["mcp-server-time"]
+```
+
+注册诸如 `mcp_time_get_current_time` 之类的工具。
+
+### Filesystem Server (npx)
+
+```yaml
+mcp_servers:
+  filesystem:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/documents"]
+    timeout: 30
+```
+
+注册诸如 `mcp_filesystem_read_file`、`mcp_filesystem_write_file`、`mcp_filesystem_list_directory` 之类的工具。
+
+### GitHub Server with Authentication
+
+```yaml
+mcp_servers:
+  github:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-github"]
+    env:
+      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxxxxxxxxxx"
+    timeout: 60
+```
+
+注册诸如 `mcp_github_list_issues`、`mcp_github_create_pull_request` 等工具。
+
+### Remote HTTP Server
+
+```yaml
+mcp_servers:
+  company_api:
+    url: "https://mcp.mycompany.com/v1/mcp"
+    headers:
+      Authorization: "Bearer sk-xxxxxxxxxxxxxxxxxxxx"
+      X-Team-Id: "engineering"
+    timeout: 180
+    connect_timeout: 30
+```
+
+### Multiple Servers
+
+```yaml
+mcp_servers:
+  time:
+    command: "uvx"
+    args: ["mcp-server-time"]
+
+  filesystem:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+
+  github:
+    command: "npx"
+    args: ["-y", "@modelcontextprotocol/server-github"]
+    env:
+      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxxxxxxxxxxxxxxxxxxx"
+
+  company_api:
+    url: "https://mcp.internal.company.com/mcp"
+    headers:
+      Authorization: "Bearer sk-xxxxxxxxxxxxxxxxxxxx"
+    timeout: 300
+```
+
+来自所有服务器的所有工具都会被注册并同时可用。每个服务器的工具都以其名称作为前缀，以避免冲突。
+
+## Sampling (Server-Initiated LLM Requests)
+
+Hermes 支持 MCP 的 `sampling/createMessage` 功能 —— MCP 服务器可以在工具执行期间通过 agent 请求 LLM 补全。这支持 agent-in-the-loop 工作流（数据分析、内容生成、决策制定）。
+
+Sampling **默认启用**。按服务器进行配置：
+
+```yaml
+mcp_servers:
+  my_server:
+    command: "npx"
+    args: ["-y", "my-mcp-server"]
+    sampling:
+      enabled: true           # default: true
+      model: "gemini-3-flash" # model override (optional)
+      max_tokens_cap: 4096    # max tokens per request
+      timeout: 30             # LLM call timeout (seconds)
+      max_rpm: 10             # max requests per minute
+      allowed_models: []      # model whitelist (empty = all)
+      max_tool_rounds: 5      # tool loop limit (0 = disable)
+      log_level: "info"       # audit verbosity
+```
+
+服务器还可以在 sampling 请求中包含 `tools`，用于多轮工具增强工作流。`max_tool_rounds` 配置可防止无限工具循环。每个服务器的审计指标（请求、错误、token、工具使用次数）通过 `get_mcp_status()` 进行追踪。
+
+对于不受信任的服务器，可以使用 `sampling: { enabled: false }` 禁用 sampling。
+
+## 说明
+
+- 从 agent 的角度来看，MCP 工具是同步调用的，但它们在专用的后台事件循环上异步运行
+- 工具结果以 JSON 格式返回，包含 `{"result": "..."}` 或 `{"error": "..."}`
+- 原生 MCP 客户端独立于 `mcporter` —— 你可以同时使用两者
+- 服务器连接是持久化的，并在同一个 agent 进程中的所有对话之间共享
+- 添加或删除服务器需要重启 agent（目前不支持热重载）

package/extensions/skills/builtin/autonomous-ai-agents/hermes-agent/references/webhooks.md

@@ -0,0 +1,193 @@
+# Webhook 订阅
+
+创建动态 webhook 订阅，以便外部服务（GitHub、GitLab、Stripe、CI/CD、IoT 传感器、监控工具）可以通过向 URL 发送 POST 事件来触发 Hermes agent 运行。
+
+## 配置 (必需先执行)
+
+在创建订阅之前，必须先启用 webhook 平台。使用以下命令检查：
+```bash
+hermes webhook list
+```
+
+如果提示 "Webhook platform is not enabled"，请进行设置：
+
+### 选项 1：设置向导
+```bash
+hermes gateway setup
+```
+按照提示启用 webhook，设置端口并设置全局 HMAC 密钥。
+
+### 选项 2：手动配置
+添加到 `~/.hermes/config.yaml`：
+```yaml
+platforms:
+  webhook:
+    enabled: true
+    extra:
+      host: "0.0.0.0"
+      port: 8644
+      secret: "generate-a-strong-secret-here"
+```
+
+### 选项 3：环境变量
+添加到 `${HERMES_HOME:-~/.hermes}/.env`：
+```bash
+WEBHOOK_ENABLED=true
+WEBHOOK_PORT=8644
+WEBHOOK_SECRET=generate-a-strong-secret-here
+```
+
+配置完成后，启动（或重启）gateway：
+```bash
+hermes gateway run
+# Or if using systemd:
+systemctl --user restart hermes-gateway
+```
+
+验证其是否正在运行：
+```bash
+curl http://localhost:8644/health
+```
+
+## 命令
+
+所有管理操作均通过 `hermes webhook` CLI 命令完成：
+
+### 创建订阅
+```bash
+hermes webhook subscribe <name> \
+  --prompt "Prompt template with {payload.fields}" \
+  --events "event1,event2" \
+  --description "What this does" \
+  --skills "skill1,skill2" \
+  --deliver telegram \
+  --deliver-chat-id "12345" \
+  --secret "optional-custom-secret"
+```
+
+返回 webhook URL 和 HMAC 密钥。用户配置其服务以 POST 方式发送数据到该 URL。
+
+### 列出订阅
+```bash
+hermes webhook list
+```
+
+### 移除订阅
+```bash
+hermes webhook remove <name>
+```
+
+### 测试订阅
+```bash
+hermes webhook test <name>
+hermes webhook test <name> --payload '{"key": "value"}'
+```
+
+## Prompt 模板
+
+Prompt 支持 `{dot.notation}` 来访问嵌套的 payload 字段：
+
+- `{issue.title}` — GitHub issue 标题
+- `{pull_request.user.login}` — PR 作者
+- `{data.object.amount}` — Stripe 支付金额
+- `{sensor.temperature}` — IoT 传感器读数
+
+如果未指定 prompt，完整的 JSON payload 将被转储到 agent prompt 中。
+
+## 常见模式
+
+### GitHub：新建 issue
+```bash
+hermes webhook subscribe github-issues \
+  --events "issues" \
+  --prompt "New GitHub issue #{issue.number}: {issue.title}\n\nAction: {action}\nAuthor: {issue.user.login}\nBody:\n{issue.body}\n\nPlease triage this issue." \
+  --deliver telegram \
+  --deliver-chat-id "-100123456789"
+```
+然后在 GitHub 仓库的 Settings → Webhooks → Add webhook 中：
+- Payload URL：返回的 webhook_url
+- Content type：application/json
+- Secret：返回的 secret
+- Events："Issues"
+
+### GitHub：PR 审查
+```bash
+hermes webhook subscribe github-prs \
+  --events "pull_request" \
+  --prompt "PR #{pull_request.number} {action}: {pull_request.title}\nBy: {pull_request.user.login}\nBranch: {pull_request.head.ref}\n\n{pull_request.body}" \
+  --skills "github-code-review" \
+  --deliver github_comment
+```
+
+### Stripe：支付事件
+```bash
+hermes webhook subscribe stripe-payments \
+  --events "payment_intent.succeeded,payment_intent.payment_failed" \
+  --prompt "Payment {data.object.status}: {data.object.amount} cents from {data.object.receipt_email}" \
+  --deliver telegram \
+  --deliver-chat-id "-100123456789"
+```
+
+### CI/CD：构建通知
+```bash
+hermes webhook subscribe ci-builds \
+  --events "pipeline" \
+  --prompt "Build {object_attributes.status} on {project.name} branch {object_attributes.ref}\nCommit: {commit.message}" \
+  --deliver discord \
+  --deliver-chat-id "1234567890"
+```
+
+### 通用监控告警
+```bash
+hermes webhook subscribe alerts \
+  --prompt "Alert: {alert.name}\nSeverity: {alert.severity}\nMessage: {alert.message}\n\nPlease investigate and suggest remediation." \
+  --deliver origin
+```
+
+### 直接投递（无 agent，零 LLM 成本）
+
+对于你只想将通知推送到用户聊天的使用场景——不需要推理，不需要 agent 循环——请添加 `--deliver-only`。渲染后的 `--prompt` 模板将成为字面消息体，并直接分派到目标 adapter。
+
+可用于：
+- 外部服务推送通知（Supabase/Firebase webhooks → Telegram）
+- 需要原样转发的监控告警
+- agent 间的 Ping 消息（一个 agent 告诉另一个 agent 的用户某些事情）
+- 任何进行 LLM 往返纯属浪费精力的 webhook
+
+```bash
+hermes webhook subscribe antenna-matches \
+  --deliver telegram \
+  --deliver-chat-id "123456789" \
+  --deliver-only \
+  --prompt "🎉 New match: {match.user_name} matched with you!" \
+  --description "Antenna match notifications"
+```
+
+POST 请求在投递成功时返回 `200 OK`，在目标失败时返回 `502`——以便上游服务可以智能地进行重试。HMAC 身份验证、速率限制和幂等性仍然适用。
+
+要求 `--deliver` 必须是一个真实存在的目标（telegram、discord、slack、github_comment 等）——会拒绝 `--deliver log`，因为仅记录日志的直接投递毫无意义。
+
+## 安全
+
+- 每个订阅都会获得一个自动生成的 HMAC-SHA256 密钥（或者使用 `--secret` 提供你自己的密钥）
+- Webhook adapter 会验证每个传入 POST 请求的签名
+- config.yaml 中的静态路由不能被动态订阅覆盖
+- 订阅将持久化保存到 `~/.hermes/webhook_subscriptions.json`
+
+## 工作原理
+
+1. `hermes webhook subscribe` 会写入 `~/.hermes/webhook_subscriptions.json`
+2. Webhook adapter 会在每个传入请求时热重载此文件（受 mtime 限制，开销可忽略不计）
+3. 当到达的 POST 请求匹配某个路由时，adapter 会格式化 prompt 并触发 agent 运行
+4. agent 的响应将被投递到配置的目标（Telegram、Discord、GitHub 评论等）
+
+## 故障排查
+
+如果 Webhook 不起作用：
+
+1. **gateway 正在运行吗？** 使用 `systemctl --user status hermes-gateway` 或 `ps aux | grep gateway` 检查
+2. **webhook 服务器正在监听吗？** `curl http://localhost:8644/health` 应该返回 `{"status": "ok"}`
+3. **检查 gateway 日志：** `grep webhook ~/.hermes/logs/gateway.log | tail -20`
+4. **签名不匹配？** 验证你服务中的密钥是否与 `hermes webhook list` 中的密钥一致。GitHub 发送 `X-Hub-Signature-256`，GitLab 发送 `X-Gitlab-Token`。
+5. **防火墙/NAT？** 必须能从外部服务访问该 webhook URL。对于本地开发，请使用隧道（ngrok, cloudflared）。
+6. **事件类型错误？** 检查 `--events` 过滤器是否与服务发送的内容匹配。使用 `hermes webhook test <name>` 来验证路由是否正常工作。