better-dsh 0.2.4 → 0.2.5

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

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

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

@@ -0,0 +1,155 @@
+# 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。