better-dsh 0.2.5-c → 0.2.5-d

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/messaging/mattermost.md

@@ -1,340 +0,0 @@
----
-sidebar_position: 8
-title: "Mattermost"
-description: "将 Hermes Agent 配置为 Mattermost 机器人"
----
-
-# Mattermost 配置
-
-Hermes Agent 以机器人身份集成到 Mattermost，让你可以通过私信或团队频道与 AI 助手对话。Mattermost 是一个自托管的开源 Slack 替代品——运行在你自己的基础设施上，完全掌控数据。机器人通过 Mattermost 的 REST API（v4）和 WebSocket 连接以接收实时事件，将消息通过 Hermes Agent 管道（包括工具调用、记忆和推理）处理后实时响应。支持文本、文件附件、图片和斜杠命令。
-
-无需额外的 Mattermost 库——适配器使用 `aiohttp`，该库已作为 Hermes 的依赖项包含在内。
-
-在开始配置之前，先了解大多数人最关心的部分：Hermes 进入你的 Mattermost 实例后的行为方式。
-
-## Hermes 的行为方式
-
-| 场景 | 行为 |
-|---------|----------|
-| **私信（DM）** | Hermes 响应每一条消息，无需 `@提及`。每个私信有独立的会话。 |
-| **公开/私有频道** | Hermes 仅在被 `@提及` 时响应。未被提及时，Hermes 忽略消息。 |
-| **线程（Thread）** | 若设置 `MATTERMOST_REPLY_MODE=thread`，Hermes 在你的消息下方以线程形式回复。线程上下文与父频道隔离。 |
-| **多用户共享频道** | 默认情况下，Hermes 在频道内按用户隔离会话历史。同一频道中的两个人不会共享同一份对话记录，除非你明确禁用该设置。 |
-
-:::tip
-如果你希望 Hermes 以线程对话方式回复（嵌套在原始消息下方），请设置 `MATTERMOST_REPLY_MODE=thread`。默认值为 `off`，即在频道中发送普通消息。
-:::
-
-### Mattermost 中的会话模型
-
-默认情况下：
-
-- 每个私信有独立的会话
-- 每个线程有独立的会话命名空间
-- 共享频道中的每个用户在该频道内有独立的会话
-
-这由 `config.yaml` 控制：
-
-```yaml
-group_sessions_per_user: true
-```
-
-仅当你明确希望整个频道共享一个对话时，才将其设为 `false`：
-
-```yaml
-group_sessions_per_user: false
-```
-
-共享会话在协作频道中可能有用，但也意味着：
-
-- 用户共享上下文增长和 token 消耗
-- 一个人的长时间重度工具调用任务会使所有人的上下文膨胀
-- 一个人正在进行的任务可能会打断同一频道中另一个人的后续操作
-
-本指南将带你完成完整的配置流程——从在 Mattermost 上创建机器人到发送第一条消息。
-
-## 第一步：启用机器人账户
-
-在创建机器人账户之前，必须先在 Mattermost 服务器上启用该功能。
-
-1. 以**系统管理员**身份登录 Mattermost。
-2. 前往**系统控制台** → **集成** → **机器人账户**。
-3. 将**启用机器人账户创建**设置为 **true**。
-4. 点击**保存**。
-
-:::info
-如果你没有系统管理员权限，请联系 Mattermost 管理员启用机器人账户并为你创建一个。
-:::
-
-## 第二步：创建机器人账户
-
-1. 在 Mattermost 中，点击左上角的 **☰** 菜单 → **集成** → **机器人账户**。
-2. 点击**添加机器人账户**。
-3. 填写详细信息：
-   - **用户名**：例如 `hermes`
-   - **显示名称**：例如 `Hermes Agent`
-   - **描述**：可选
-   - **角色**：`Member` 即可
-4. 点击**创建机器人账户**。
-5. Mattermost 将显示**机器人 token**。**立即复制。**
-
-:::warning[Token 仅显示一次]
-机器人 token 仅在创建机器人账户时显示一次。如果丢失，需要在机器人账户设置中重新生成。切勿公开分享你的 token 或将其提交到 Git——任何持有此 token 的人都能完全控制该机器人。
-:::
-
-将 token 保存在安全的地方（例如密码管理器）。第五步中会用到它。
-
-:::tip
-你也可以使用**个人访问 token** 代替机器人账户。前往**个人资料** → **安全** → **个人访问 Token** → **创建 Token**。如果你希望 Hermes 以你自己的用户身份发帖而非独立的机器人用户，这种方式很有用。
-:::
-
-## 第三步：将机器人添加到频道
-
-机器人需要成为你希望它响应的频道的成员：
-
-1. 打开你希望添加机器人的频道。
-2. 点击频道名称 → **添加成员**。
-3. 搜索你的机器人用户名（例如 `hermes`）并添加。
-
-对于私信，直接与机器人开启私信即可——它将立即能够响应。
-
-## 第四步：查找你的 Mattermost 用户 ID
-
-Hermes Agent 使用你的 Mattermost 用户 ID 来控制谁可以与机器人交互。查找方式：
-
-1. 点击左上角的**头像** → **个人资料**。
-2. 用户 ID 显示在个人资料对话框中——点击即可复制。
-
-你的用户 ID 是一个 26 位字母数字字符串，例如 `3uo8dkh1p7g1mfk49ear5fzs5c`。
-
-:::warning
-你的用户 ID **不是**你的用户名。用户名是 `@` 后面显示的内容（例如 `@alice`）。用户 ID 是 Mattermost 内部使用的长字母数字标识符。
-:::
-
-**替代方法**：你也可以通过 API 获取用户 ID：
-
-```bash
-curl -H "Authorization: Bearer YOUR_TOKEN" \
-  https://your-mattermost-server/api/v4/users/me | jq .id
-```
-
-:::tip
-要获取**频道 ID**：点击频道名称 → **查看信息**。频道 ID 显示在信息面板中。如果你想手动设置主频道，需要用到它。
-:::
-
-## 第五步：配置 Hermes Agent
-
-### 方式 A：交互式配置（推荐）
-
-运行引导式配置命令：
-
-```bash
-hermes gateway setup
-```
-
-在提示时选择 **Mattermost**，然后按提示粘贴你的服务器 URL、机器人 token 和用户 ID。
-
-### 方式 B：手动配置
-
-在你的 `~/.hermes/.env` 文件中添加以下内容：
-
-```bash
-# 必填
-MATTERMOST_URL=https://mm.example.com
-MATTERMOST_TOKEN=***
-MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c
-
-# 多个允许的用户（逗号分隔）
-# MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c,8fk2jd9s0a7bncm1xqw4tp6r3e
-
-# 可选：回复模式（thread 或 off，默认：off）
-# MATTERMOST_REPLY_MODE=thread
-
-# 可选：无需 @提及 即可响应（默认：true = 需要提及）
-# MATTERMOST_REQUIRE_MENTION=false
-
-# 可选：机器人无需 @提及 即可响应的频道（逗号分隔的频道 ID）
-# MATTERMOST_FREE_RESPONSE_CHANNELS=channel_id_1,channel_id_2
-```
-
-`~/.hermes/config.yaml` 中的可选行为设置：
-
-```yaml
-group_sessions_per_user: true
-```
-
-- `group_sessions_per_user: true` 使每个参与者在共享频道和线程中的上下文保持隔离
-
-### 启动 Gateway
-
-配置完成后，启动 Mattermost gateway：
-
-```bash
-hermes gateway
-```
-
-机器人应在几秒内连接到你的 Mattermost 服务器。发送一条消息——私信或在已添加机器人的频道中——进行测试。
-
-:::tip
-你可以在后台运行 `hermes gateway`，或将其配置为 systemd 服务以持续运行。详情参见部署文档。
-:::
-
-## 主频道
-
-你可以指定一个"主频道"，机器人将在此频道发送主动消息（例如 cron 任务输出、提醒和通知）。有两种设置方式：
-
-### 使用斜杠命令
-
-在机器人所在的任意 Mattermost 频道中输入 `/sethome`。该频道即成为主频道。
-
-### 手动配置
-
-在你的 `~/.hermes/.env` 中添加：
-
-```bash
-MATTERMOST_HOME_CHANNEL=abc123def456ghi789jkl012mn
-```
-
-将 ID 替换为实际的频道 ID（点击频道名称 → 查看信息 → 复制 ID）。
-
-## 回复模式
-
-`MATTERMOST_REPLY_MODE` 设置控制 Hermes 发布响应的方式：
-
-| 模式 | 行为 |
-|------|----------|
-| `off`（默认） | Hermes 在频道中发送普通消息，与普通用户一样。 |
-| `thread` | Hermes 在你的原始消息下方以线程形式回复。在大量来回交流时保持频道整洁。 |
-
-在你的 `~/.hermes/.env` 中设置：
-
-```bash
-MATTERMOST_REPLY_MODE=thread
-```
-
-## 提及行为
-
-默认情况下，机器人仅在频道中被 `@提及` 时响应。你可以更改此行为：
-
-| 变量 | 默认值 | 描述 |
-|----------|---------|-------------|
-| `MATTERMOST_REQUIRE_MENTION` | `true` | 设为 `false` 可响应频道中的所有消息（私信始终有效）。 |
-| `MATTERMOST_FREE_RESPONSE_CHANNELS` | _（无）_ | 逗号分隔的频道 ID，机器人在这些频道中无需 `@提及` 即可响应，即使 require_mention 为 true。 |
-
-在 Mattermost 中查找频道 ID：打开频道，点击频道名称标题，在 URL 或频道详情中查找 ID。
-
-当机器人被 `@提及` 时，提及内容会在处理前自动从消息中去除。
-
-## 频道白名单（`allowed_channels`）
-
-将机器人限制在固定的 Mattermost 频道集合中。设置后，机器人**仅**在 ID 出现在列表中的频道响应——来自其他频道的消息将被静默忽略，即使机器人被 `@提及`。
-
-**私信不受此过滤器限制**，因此授权用户始终可以通过私信联系机器人。
-
-```yaml
-mattermost:
-  allowed_channels:
-    - "abc123def456ghi789jkl012mno"   # #ops
-    - "xyz987uvw654rst321opq098nml"   # #incident-response
-```
-
-或通过环境变量设置（逗号分隔）：
-
-```bash
-MATTERMOST_ALLOWED_CHANNELS="abc123def456ghi789jkl012mno,xyz987uvw654rst321opq098nml"
-```
-
-行为说明：
-
-- 空值/未设置 → 无限制（完全向后兼容）。
-- 非空值 → 频道 ID 必须在列表中，否则消息在任何其他门控（提及要求、`MATTERMOST_FREE_RESPONSE_CHANNELS` 等）运行之前即被丢弃。
-- 通过 Mattermost UI → 频道标题 → "查看信息"查找频道 ID，或从频道 URL 中读取。
-
-另请参阅：[管理员/用户斜杠命令分离](../../reference/slash-commands.md#permissions-and-adminuser-split)。
-
-## 故障排查
-
-### 机器人不响应消息
-
-**原因**：机器人不是该频道的成员，或 `MATTERMOST_ALLOWED_USERS` 中未包含你的用户 ID。
-
-**解决方法**：将机器人添加到频道（频道名称 → 添加成员 → 搜索机器人）。确认你的用户 ID 在 `MATTERMOST_ALLOWED_USERS` 中。重启 gateway。
-
-### 403 Forbidden 错误
-
-**原因**：机器人 token 无效，或机器人没有在该频道发帖的权限。
-
-**解决方法**：检查 `.env` 文件中的 `MATTERMOST_TOKEN` 是否正确。确认机器人账户未被停用。确认机器人已被添加到频道。如果使用个人访问 token，确保你的账户具有所需权限。
-
-### WebSocket 断开连接/重连循环
-
-**原因**：网络不稳定、Mattermost 服务器重启，或防火墙/代理对 WebSocket 连接的干扰。
-
-**解决方法**：适配器会以指数退避方式（2s → 60s）自动重连。检查服务器的 WebSocket 配置——反向代理（nginx、Apache）需要配置 WebSocket 升级头。确认没有防火墙阻止 Mattermost 服务器上的 WebSocket 连接。
-
-对于 nginx，确保你的配置包含：
-
-```nginx
-location /api/v4/websocket {
-    proxy_pass http://mattermost-backend;
-    proxy_set_header Upgrade $http_upgrade;
-    proxy_set_header Connection "upgrade";
-    proxy_read_timeout 600s;
-}
-```
-
-### 启动时出现"Failed to authenticate"
-
-**原因**：token 或服务器 URL 不正确。
-
-**解决方法**：确认 `MATTERMOST_URL` 指向你的 Mattermost 服务器（包含 `https://`，末尾无斜杠）。检查 `MATTERMOST_TOKEN` 是否有效——用 curl 测试：
-
-```bash
-curl -H "Authorization: Bearer YOUR_TOKEN" \
-  https://your-server/api/v4/users/me
-```
-
-如果返回机器人的用户信息，则 token 有效。如果返回错误，请重新生成 token。
-
-### 机器人离线
-
-**原因**：Hermes gateway 未运行，或连接失败。
-
-**解决方法**：检查 `hermes gateway` 是否正在运行。查看终端输出中的错误信息。常见问题：URL 错误、token 过期、Mattermost 服务器无法访问。
-
-### "User not allowed"/机器人忽略你
-
-**原因**：你的用户 ID 不在 `MATTERMOST_ALLOWED_USERS` 中。
-
-**解决方法**：将你的用户 ID 添加到 `~/.hermes/.env` 中的 `MATTERMOST_ALLOWED_USERS`，然后重启 gateway。注意：用户 ID 是 26 位字母数字字符串，不是你的 `@用户名`。
-
-## 按频道设置 Prompt
-
-为特定 Mattermost 频道分配临时系统 prompt（提示词）。该 prompt 在每次对话轮次中于运行时注入——从不持久化到对话记录——因此更改立即生效。
-
-```yaml
-mattermost:
-  channel_prompts:
-    "channel_id_abc123": |
-      You are a research assistant. Focus on academic sources,
-      citations, and concise synthesis.
-    "channel_id_def456": |
-      Code review mode. Be precise about edge cases and
-      performance implications.
-```
-
-键为 Mattermost 频道 ID（在频道 URL 或通过 API 查找）。匹配频道中的所有消息都会将该 prompt 作为临时系统指令注入。
-
-## 安全
-
-:::warning
-务必设置 `MATTERMOST_ALLOWED_USERS` 以限制谁可以与机器人交互。若未设置，gateway 默认拒绝所有用户作为安全措施。仅添加你信任的人的用户 ID——授权用户对 agent 的所有功能拥有完整访问权限，包括工具调用和系统访问。
-:::
-
-有关保护 Hermes Agent 部署的更多信息，请参阅[安全指南](../security.md)。
-
-## 说明
-
-- **自托管友好**：适用于任何自托管的 Mattermost 实例。无需 Mattermost Cloud 账户或订阅。
-- **无额外依赖**：适配器使用 `aiohttp` 处理 HTTP 和 WebSocket，该库已包含在 Hermes Agent 中。
-- **兼容团队版**：同时支持 Mattermost 团队版（免费）和企业版。

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/messaging/msgraph-webhook.md

@@ -1,137 +0,0 @@
----
-sidebar_position: 23
-title: "Microsoft Graph Webhook 监听器"
-description: "在 Hermes 中接收 Microsoft Graph 变更通知（会议、日历、聊天等）"
----
-
-# Microsoft Graph Webhook 监听器
-
-`msgraph_webhook` gateway 平台是一个入站事件监听器。它是 Hermes 接收来自 Microsoft Graph 的**变更通知**的方式——"一个 Teams 会议已结束"、"此聊天中收到了一条新消息"、"此日历事件已更新"。与 `teams` 平台（用户向其发送消息的聊天机器人）不同——此平台是 M365 告知 Hermes 某事已发生，而非来自用户的消息。
-
-目前主要的消费者是 Teams 会议摘要流水线：Graph 在会议产生转录文本时发出通知，流水线获取该内容，Hermes 将摘要发回 Teams。其他 Graph 资源（`/chats/.../messages`、`/users/.../events`）使用同一监听器——流水线消费者通过各自的 PR 接入。
-
-## 前提条件
-
-- Microsoft Graph 应用凭据——[注册 Microsoft Graph 应用程序](/guides/microsoft-graph-app-registration)
-- 一个 Microsoft Graph 可访问的**公开 HTTPS URL**（Graph 不会调用私有端点）。测试时可使用 dev tunnel；生产环境需要具有有效证书的真实域名。
-- 一个强共享密钥，用作 `clientState` 的值。使用 `openssl rand -hex 32` 生成，并以 `MSGRAPH_WEBHOOK_CLIENT_STATE` 写入 `~/.hermes/.env`。
-
-## 快速开始
-
-最小化 `~/.hermes/config.yaml`：
-
-```yaml
-platforms:
-  msgraph_webhook:
-    enabled: true
-    extra:
-      port: 8646
-      client_state: "replace-with-a-strong-secret"
-      accepted_resources:
-        - "communications/onlineMeetings"
-```
-
-或通过 `~/.hermes/.env` 中的环境变量（启动时自动合并）：
-
-```bash
-MSGRAPH_WEBHOOK_ENABLED=true
-MSGRAPH_WEBHOOK_PORT=8646
-MSGRAPH_WEBHOOK_CLIENT_STATE=<generate-with-openssl-rand-hex-32>
-MSGRAPH_WEBHOOK_ACCEPTED_RESOURCES=communications/onlineMeetings
-```
-
-启动 gateway：`hermes gateway run`。监听器暴露以下端点：
-
-- `POST /msgraph/webhook` — 来自 Graph 的变更通知
-- `GET /msgraph/webhook?validationToken=...` — Graph 订阅验证握手
-- `GET /health` — 就绪探针，包含已接受/重复计数器
-
-将监听器公开暴露（反向代理、dev tunnel、ingress）。Graph 订阅的通知 URL 为你的公开 HTTPS 源地址加上 `/msgraph/webhook`：
-
-```
-https://ops.example.com/msgraph/webhook
-```
-
-## 配置
-
-所有设置位于 `platforms.msgraph_webhook.extra` 下：
-
-| 设置 | 默认值 | 说明 |
-|------|--------|------|
-| `host` | `0.0.0.0` | HTTP 监听器的绑定地址。 |
-| `port` | `8646` | 绑定端口。 |
-| `webhook_path` | `/msgraph/webhook` | Graph POST 请求的 URL 路径。 |
-| `health_path` | `/health` | 就绪端点。 |
-| `client_state` | — | Graph 在每条通知中回传的共享密钥。使用 `hmac.compare_digest` 进行比较——使用 `openssl rand -hex 32` 生成。 |
-| `accepted_resources` | `[]`（接受全部） | Graph 资源路径/模式的白名单。末尾 `*` 作为前缀匹配。可容忍开头的 `/`。示例：`["communications/onlineMeetings", "chats/*/messages"]`。 |
-| `max_seen_receipts` | `5000` | 通知 ID 的去重缓存大小。达到上限时淘汰最旧的条目。 |
-| `allowed_source_cidrs` | `[]`（允许全部） | 可选的源 IP 白名单。见下文。 |
-
-大多数设置也有对应的环境变量（`MSGRAPH_WEBHOOK_*`），在 gateway 启动时合并到配置中（例外是 `host`，它仅可通过配置文件设置——参见上方说明）——参见[环境变量参考](/reference/environment-variables#microsoft-graph-teams-meetings)。
-
-## 安全加固
-
-### clientState 是主要的认证检查
-
-每条 Graph 通知都包含你在订阅时注册的 `clientState` 字符串。监听器使用时序安全比较拒绝任何 `clientState` 不匹配的通知。这是 Microsoft 的官方机制——请将该值视为强共享密钥。
-
-如果未设置 `client_state`，监听器将接受所有格式正确的 POST 请求。**生产环境中请勿在未设置的情况下运行。**
-
-### 源 IP 白名单（生产部署）
-
-在生产环境中，将监听器限制为 Microsoft 公布的 Graph webhook 源 IP 范围。Microsoft 在 [Office 365 IP 地址和 URL Web 服务](https://learn.microsoft.com/en-us/microsoft-365/enterprise/urls-and-ip-address-ranges)中记录了出口范围。配置方式如下：
-
-```yaml
-platforms:
-  msgraph_webhook:
-    enabled: true
-    extra:
-      client_state: "..."
-      allowed_source_cidrs:
-        - "52.96.0.0/14"
-        - "52.104.0.0/14"
-        # ...添加当前 Microsoft 365 "Common" + "Teams" 类别的出口范围
-```
-
-或通过环境变量：
-
-```bash
-MSGRAPH_WEBHOOK_ALLOWED_SOURCE_CIDRS="52.96.0.0/14,52.104.0.0/14"
-```
-
-空白名单 = 接受来自任何地址的请求（默认；保留 dev tunnel 工作流）。无效的 CIDR 字符串会记录警告并被忽略。**请每季度审查 Microsoft IP 列表**——它会变更。
-
-### HTTPS 终止
-
-监听器使用纯 HTTP。在你的反向代理（Caddy、Nginx、Cloudflare Tunnel、AWS ALB）处终止 TLS，并通过本地网络代理到监听器。Graph 拒绝向非 HTTPS 端点投递，因此来自 Graph 的未加密流量不存在可达路径。
-
-### 响应规范
-
-成功时，监听器返回 `202 Accepted` 且响应体为空——内部计数器不会出现在响应中。运维人员可通过 `/health` 观察计数。
-
-状态码说明：
-
-| 结果 | 状态码 |
-|------|--------|
-| 通知已接受或已去重 | 202 |
-| 验证握手（带 `validationToken` 的 GET） | 200（原样回传 token） |
-| 批次中所有条目的 clientState 均失败 | 403 |
-| JSON 格式错误 / 缺少 `value` 数组 / 未知资源 | 400 |
-| 源 IP 不在白名单中 | 403 |
-| 不带 `validationToken` 的裸 GET | 400 |
-
-## 故障排查
-
-| 问题 | 检查项 |
-|------|--------|
-| Graph 订阅验证失败 | 公开 URL 可访问，`/msgraph/webhook` 路径匹配，带 `validationToken` 的 GET 在 10 秒内以 `text/plain` 原样回传 token。 |
-| 通知 POST 成功但无内容被摄取 | `client_state` 与订阅时注册的值一致。如值已漂移，重新运行 `openssl rand -hex 32` 并创建新订阅。检查 `accepted_resources` 是否包含 Graph 发送的资源路径。 |
-| 每条通知均返回 403 | `clientState` 不匹配（伪造，或订阅时使用了不同的值）。使用 `hermes teams-pipeline subscribe --client-state "$MSGRAPH_WEBHOOK_CLIENT_STATE" ...` 重新创建订阅（随流水线运行时 PR 一同发布）。 |
-| 监听器已启动，但 `curl http://localhost:8646/health` 挂起 | 端口绑定冲突。检查 `ss -tlnp \| grep 8646`，如有需要更改 `port:`。 |
-| 来自 Microsoft 的真实 Graph 请求返回 403 | 源 IP 白名单范围过窄。临时移除 `allowed_source_cidrs`，确认流量正常后，将列表扩展至包含当前 Microsoft 出口范围。 |
-
-## 相关文档
-
-- [注册 Microsoft Graph 应用程序](/guides/microsoft-graph-app-registration) — Azure 应用注册前提条件
-- [环境变量 → Microsoft Graph](/reference/environment-variables#microsoft-graph-teams-meetings) — 完整环境变量列表
-- [Microsoft Teams 机器人设置](/user-guide/messaging/teams) — 允许用户在 Teams 中与 Hermes 聊天的另一平台

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/messaging/ntfy.md

@@ -1,155 +0,0 @@
-# ntfy
-
-[ntfy](https://ntfy.sh/) 是一个简单的基于 HTTP 的发布-订阅通知服务。它可与 `ntfy.sh` 上的免费公共服务器或任何自托管实例配合使用，支持任何能发起 HTTP 请求的客户端——手机、浏览器、脚本、手表。
-
-ntfy 是 Hermes 的轻量级推送渠道的理想选择：通过 [ntfy 移动应用](https://ntfy.sh/docs/subscribe/phone/) 订阅一个 topic（主题），向该 topic 发送消息与 agent 对话，然后在手机上收到回复。
-
-## 前提条件
-
-- 一个 topic 名称（任意唯一字符串——`hermes-myname-2026` 即可）
-- 已安装 [ntfy 移动应用](https://ntfy.sh/docs/subscribe/phone/) 并订阅该 topic
-- 可选：自托管的 ntfy 服务器，或用于私有/保留 topic 的 `ntfy.sh` 账户 token
-
-仅此而已。无需 SDK、无需守护进程、无需 Node.js。适配器使用 `httpx`，该库已是 Hermes 的依赖项。
-
-## 配置 Hermes
-
-### 通过设置向导
-
-```bash
-hermes gateway setup
-```
-
-选择 **ntfy** 并按提示操作。
-
-### 通过环境变量
-
-将以下内容添加到 `~/.hermes/.env`：
-
-```
-NTFY_TOPIC=hermes-myname-2026
-NTFY_ALLOWED_USERS=hermes-myname-2026
-NTFY_HOME_CHANNEL=hermes-myname-2026
-```
-
-| 变量 | 是否必填 | 说明 |
-|---|---|---|
-| `NTFY_TOPIC` | 是 | 要订阅的 topic（接收消息） |
-| `NTFY_SERVER_URL` | 可选 | 服务器 URL（默认：`https://ntfy.sh`）——指向自托管 ntfy 以保护隐私 |
-| `NTFY_TOKEN` | 可选 | Bearer token（如 `tk_xyz`）或用于 Basic 认证的 `user:pass` |
-| `NTFY_PUBLISH_TOPIC` | 可选 | 用于发送回复的不同 topic（默认与 `NTFY_TOPIC` 相同） |
-| `NTFY_MARKDOWN` | 可选 | 设为 `true` 以使用 `X-Markdown: true` 请求头发送回复 |
-| `NTFY_ALLOWED_USERS` | 推荐 | 允许的 topic 名称（逗号分隔，视为用户 ID；见下文） |
-| `NTFY_ALLOW_ALL_USERS` | 可选 | 设为 `true` 以允许所有发布者——仅在具有读取 token 的私有 topic 下安全 |
-| `NTFY_HOME_CHANNEL` | 可选 | cron 任务/通知投递的默认 topic |
-| `NTFY_HOME_CHANNEL_NAME` | 可选 | 主渠道的可读标签 |
-
-## 身份模型——部署前请阅读
-
-ntfy 没有原生的已认证用户身份。已发布消息中的 `title` 字段由**发布者控制**，可以是发布者想要的任何内容。Hermes 适配器**不**使用 `title` 进行授权——否则任何知道 topic 的发布者都可以伪造允许的用户。
-
-相反，**topic 名称本身即为身份**。发布到该 topic 的每条消息都被视为来自同一个逻辑用户（即该 topic）。因此 `NTFY_ALLOWED_USERS` 通常就是 topic 名称本身——一个控制整个渠道访问的单条目白名单。
-
-这意味着**任何知道 topic 的人都可以与 agent 对话**。要将其变为真正的信任边界：
-
-- **自托管 ntfy** 并通过[访问控制](https://docs.ntfy.sh/config/#access-control)锁定 topic。只有持有读/写 token 的授权客户端才能发布。
-- 或**在 ntfy.sh 上使用私有 topic**（[保留 topic](https://docs.ntfy.sh/publish/#reserved-topics) 需要账户），并通过 `NTFY_TOKEN` 保护。
-- 或**选择一个长且难以猜测的 topic 名称**（`hermes-7d4f9c8b-2026`），将其视为共享密钥。这是最轻量的方案，但 topic 名称可能通过日志或截图泄露。
-
-在任何情况下，除非底层 topic 已启用访问控制，否则不要通过 ntfy 传输敏感数据。
-
-## 快速开始——从手机与 agent 对话
-
-1. 选择一个 topic 名称：`hermes-myname-2026`
-2. 在手机上：安装 [ntfy 应用](https://ntfy.sh/docs/subscribe/phone/)，点击 **+**，输入 `hermes-myname-2026`
-3. 在主机上：
-   ```bash
-   echo 'NTFY_TOPIC=hermes-myname-2026' >> ~/.hermes/.env
-   echo 'NTFY_ALLOWED_USERS=hermes-myname-2026' >> ~/.hermes/.env
-   hermes gateway restart
-   ```
-4. 从 ntfy 应用向该 topic 发送一条消息。agent 的回复将以推送通知的形式送达。
-
-## 在 cron 任务中使用 ntfy
-
-设置 `NTFY_HOME_CHANNEL` 后，cron 任务即可投递到 ntfy：
-
-```python
-cronjob(
-    action="create",
-    schedule="every 1h",
-    deliver="ntfy",          # uses NTFY_HOME_CHANNEL
-    prompt="Check for alerts and summarise."
-)
-```
-
-或显式指定目标 topic：
-
-```python
-send_message(target="ntfy:alerts-channel", message="Done!")
-```
-
-即使 cron 在 gateway 进程外运行，此功能也有效——插件注册了一个 `standalone_sender_fn`，会自行建立 HTTP 连接。
-
-## 自托管 ntfy
-
-如需完全掌控：
-
-```bash
-# Docker
-docker run -p 80:80 -it binwiederhier/ntfy serve
-
-# Native
-go install heckel.io/ntfy/v2@latest
-ntfy serve
-```
-
-然后将 Hermes 指向该实例：
-
-```
-NTFY_SERVER_URL=https://ntfy.mydomain.com
-NTFY_TOPIC=hermes
-NTFY_TOKEN=tk_abc123  # if you've set up access control
-```
-
-自托管可提供 topic 访问控制、消息持久化策略、附件和 emoji 标签。参见 [ntfy 服务器文档](https://docs.ntfy.sh/install/)。
-
-## Markdown 格式化
-
-当发布者设置 `X-Markdown: true` 请求头时，ntfy 客户端会渲染 Markdown。要为 Hermes 的出站回复启用此功能：
-
-```
-NTFY_MARKDOWN=true
-```
-
-或在 `config.yaml` 中配置：
-
-```yaml
-platforms:
-  ntfy:
-    extra:
-      markdown: true
-```
-
-移动应用支持 CommonMark 的子集——粗体、斜体、列表、链接、围栏代码块。确切支持范围参见 [ntfy 的 Markdown 文档](https://docs.ntfy.sh/publish/#markdown-formatting)。
-
-## 仅出站设置（只推送通知，不接收消息）
-
-如果只希望 Hermes *推送*通知到 ntfy（cron 摘要、告警），而不接受任何回复消息，可将 `NTFY_TOPIC` 和 `NTFY_PUBLISH_TOPIC` 设为相同值，并完全省略 `NTFY_ALLOWED_USERS`。没有白名单时，agent 不会响应任何入站消息——手机可收到推送，但对话是单向的。
-
-## 限制
-
-- **消息大小**：ntfy 将消息体上限设为 4096 个字符。超出时 Hermes 会截断并发出警告。
-- **无输入状态指示**：协议不支持此功能；`send_typing` 为空操作。
-- **无线程或附件**：ntfy 是纯推送通知。长回复保留在消息体中，不会分线程展开。
-- **无原生用户身份**：参见上文的身份模型章节。
-
-## 故障排查
-
-**认证失败 / 401** — `NTFY_TOKEN` 有误，或该 token 对此 topic 没有发布/订阅权限。适配器在收到 401 时会停止重连循环，gateway 运行时状态将显示 `fatal: ntfy_unauthorized`。修正 token 后重启 gateway。
-
-**Topic 未找到 / 404** — `NTFY_TOPIC` 在所配置的服务器上不存在。对于 ntfy.sh，topic 在首次发布时自动创建，因此 404 意味着你指向的自托管服务器尚未创建该 topic。适配器会停止重连循环并显示 `fatal: ntfy_topic_not_found`。
-
-**已连接但收不到消息** — 检查 `NTFY_ALLOWED_USERS` 是否包含 topic 名称本身。在 ntfy 的身份模型中，topic 即用户；白名单为空时所有消息都会被拒绝。
-
-**每 60 秒重连一次** — 流式 keepalive 默认为 55 秒；ntfy 可能存在间歇性网络问题。适配器采用指数退避（2 → 5 → 10 → 30 → 60 秒），一旦流保持存活 ≥60 秒则重置为 0。