@symerian/symi 3.0.21 → 3.0.22

package/docs/zh-CN/channels/googlechat.md

@@ -1,257 +0,0 @@
----
-read_when:
-  - 开发 Google Chat 渠道功能时
-summary: Google Chat 应用支持状态、功能和配置
-title: Google Chat
-x-i18n:
-  generated_at: "2026-02-03T07:43:39Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 3b2bb116cdd12614c3d5afddd0879e9deb05c3606e3a2385cbc07f23552b357e
-  source_path: channels/googlechat.md
-  workflow: 15
----
-
-# Google Chat（Chat API）
-
-状态：已支持通过 Google Chat API webhooks（仅 HTTP）使用私信和空间。
-
-## 快速设置（新手）
-
-1. 创建一个 Google Cloud 项目并启用 **Google Chat API**。
-   - 前往：[Google Chat API Credentials](https://console.cloud.google.com/apis/api/chat.googleapis.com/credentials)
-   - 如果 API 尚未启用，请启用它。
-2. 创建一个**服务账号**：
-   - 点击 **Create Credentials** > **Service Account**。
-   - 随意命名（例如 `symi-chat`）。
-   - 权限留空（点击 **Continue**）。
-   - 有访问权限的主账号留空（点击 **Done**）。
-3. 创建并下载 **JSON 密钥**：
-   - 在服务账号列表中，点击刚刚创建的账号。
-   - 前往 **Keys** 标签页。
-   - 点击 **Add Key** > **Create new key**。
-   - 选择 **JSON** 并点击 **Create**。
-4. 将下载的 JSON 文件存储在 Gateway 网关主机上（例如 `~/.symi/googlechat-service-account.json`）。
-5. 在 [Google Cloud Console Chat Configuration](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat) 中创建一个 Google Chat 应用：
-   - 填写 **Application info**：
-     - **App name**：（例如 `Symi`）
-     - **Avatar URL**：（例如 `https://symi.ai/logo.png`）
-     - **Description**：（例如 `Personal AI Assistant`）
-   - 启用 **Interactive features**。
-   - 在 **Functionality** 下，勾选 **Join spaces and group conversations**。
-   - 在 **Connection settings** 下，选择 **HTTP endpoint URL**。
-   - 在 **Triggers** 下，选择 **Use a common HTTP endpoint URL for all triggers** 并将其设置为你的 Gateway 网关公网 URL 后加 `/googlechat`。
-     - _提示：运行 `symi status` 查看你的 Gateway 网关公网 URL。_
-   - 在 **Visibility** 下，勾选 **Make this Chat app available to specific people and groups in <Your Domain>**。
-   - 在文本框中输入你的邮箱地址（例如 `user@example.com`）。
-   - 点击底部的 **Save**。
-6. **启用应用状态**：
-   - 保存后，**刷新页面**。
-   - 找到 **App status** 部分（通常在保存后位于顶部或底部附近）。
-   - 将状态更改为 **Live - available to users**。
-   - 再次点击 **Save**。
-7. 使用服务账号路径和 webhook audience 配置 Symi：
-   - 环境变量：`GOOGLE_CHAT_SERVICE_ACCOUNT_FILE=/path/to/service-account.json`
-   - 或配置：`channels.googlechat.serviceAccountFile: "/path/to/service-account.json"`。
-8. 设置 webhook audience 类型和值（与你的 Chat 应用配置匹配）。
-9. 启动 Gateway 网关。Google Chat 将向你的 webhook 路径发送 POST 请求。
-
-## 添加到 Google Chat
-
-Gateway 网关运行后，且你的邮箱已添加到可见性列表中：
-
-1. 前往 [Google Chat](https://chat.google.com/)。
-2. 点击 **Direct Messages** 旁边的 **+**（加号）图标。
-3. 在搜索栏（通常用于添加联系人的位置）中，输入你在 Google Cloud Console 中配置的 **App name**。
-   - **注意**：该机器人*不会*出现在"Marketplace"浏览列表中，因为它是私有应用。你必须按名称搜索。
-4. 从结果中选择你的机器人。
-5. 点击 **Add** 或 **Chat** 开始一对一对话。
-6. 发送"Hello"来触发助手！
-
-## 公网 URL（仅 Webhook）
-
-Google Chat webhooks 需要一个公网 HTTPS 端点。为了安全起见，**只将 `/googlechat` 路径暴露到互联网**。将 Symi 仪表板和其他敏感端点保留在你的私有网络上。
-
-### 方案 A：Tailscale Funnel（推荐）
-
-使用 Tailscale Serve 提供私有仪表板，使用 Funnel 提供公网 webhook 路径。这样可以保持 `/` 私有，同时只暴露 `/googlechat`。
-
-1. **检查你的 Gateway 网关绑定的地址：**
-
-   ```bash
-   ss -tlnp | grep 18789
-   ```
-
-   记下 IP 地址（例如 `127.0.0.1`、`0.0.0.0` 或你的 Tailscale IP 如 `100.x.x.x`）。
-
-2. **仅将仪表板暴露给 tailnet（端口 8443）：**
-
-   ```bash
-   # 如果绑定到 localhost（127.0.0.1 或 0.0.0.0）：
-   tailscale serve --bg --https 8443 http://127.0.0.1:18789
-
-   # 如果仅绑定到 Tailscale IP（例如 100.106.161.80）：
-   tailscale serve --bg --https 8443 http://100.106.161.80:18789
-   ```
-
-3. **仅公开暴露 webhook 路径：**
-
-   ```bash
-   # 如果绑定到 localhost（127.0.0.1 或 0.0.0.0）：
-   tailscale funnel --bg --set-path /googlechat http://127.0.0.1:18789/googlechat
-
-   # 如果仅绑定到 Tailscale IP（例如 100.106.161.80）：
-   tailscale funnel --bg --set-path /googlechat http://100.106.161.80:18789/googlechat
-   ```
-
-4. **授权节点访问 Funnel：**
-   如果出现提示，请访问输出中显示的授权 URL，以在你的 tailnet 策略中为此节点启用 Funnel。
-
-5. **验证配置：**
-   ```bash
-   tailscale serve status
-   tailscale funnel status
-   ```
-
-你的公网 webhook URL 将是：
-`https://<node-name>.<tailnet>.ts.net/googlechat`
-
-你的私有仪表板仅限 tailnet 访问：
-`https://<node-name>.<tailnet>.ts.net:8443/`
-
-在 Google Chat 应用配置中使用公网 URL（不带 `:8443`）。
-
-> 注意：此配置在重启后会保留。如需稍后移除，请运行 `tailscale funnel reset` 和 `tailscale serve reset`。
-
-### 方案 B：反向代理（Caddy）
-
-如果你使用像 Caddy 这样的反向代理，只代理特定路径：
-
-```caddy
-your-domain.com {
-    reverse_proxy /googlechat* localhost:18789
-}
-```
-
-使用此配置，任何发往 `your-domain.com/` 的请求将被忽略或返回 404，而 `your-domain.com/googlechat` 会安全地路由到 Symi。
-
-### 方案 C：Cloudflare Tunnel
-
-配置你的隧道入口规则，只路由 webhook 路径：
-
-- **路径**：`/googlechat` -> `http://localhost:18789/googlechat`
-- **默认规则**：HTTP 404（未找到）
-
-## 工作原理
-
-1. Google Chat 向 Gateway 网关发送 webhook POST 请求。每个请求都包含一个 `Authorization: Bearer <token>` 头。
-2. Symi 根据配置的 `audienceType` + `audience` 验证令牌：
-   - `audienceType: "app-url"` → audience 是你的 HTTPS webhook URL。
-   - `audienceType: "project-number"` → audience 是 Cloud 项目编号。
-3. 消息按空间路由：
-   - 私信使用会话键 `agent:<agentId>:googlechat:dm:<spaceId>`。
-   - 空间使用会话键 `agent:<agentId>:googlechat:group:<spaceId>`。
-4. 私信访问默认为配对模式。未知发送者会收到配对码；使用以下命令批准：
-   - `symi pairing approve googlechat <code>`
-5. 群组空间默认需要 @提及。如果提及检测需要应用的用户名，请使用 `botUser`。
-
-## 目标标识符
-
-使用这些标识符进行消息投递和允许列表：
-
-- 私信：`users/<userId>` 或 `users/<email>`（接受邮箱地址）。
-- 空间：`spaces/<spaceId>`。
-
-## 配置要点
-
-```json5
-{
-  channels: {
-    googlechat: {
-      enabled: true,
-      serviceAccountFile: "/path/to/service-account.json",
-      audienceType: "app-url",
-      audience: "https://gateway.example.com/googlechat",
-      webhookPath: "/googlechat",
-      botUser: "users/1234567890", // 可选；帮助提及检测
-      dm: {
-        policy: "pairing",
-        allowFrom: ["users/1234567890", "name@example.com"],
-      },
-      groupPolicy: "allowlist",
-      groups: {
-        "spaces/AAAA": {
-          allow: true,
-          requireMention: true,
-          users: ["users/1234567890"],
-          systemPrompt: "Short answers only.",
-        },
-      },
-      actions: { reactions: true },
-      typingIndicator: "message",
-      mediaMaxMb: 20,
-    },
-  },
-}
-```
-
-注意事项：
-
-- 服务账号凭证也可以通过 `serviceAccount`（JSON 字符串）内联传递。
-- 如果未设置 `webhookPath`，默认 webhook 路径为 `/googlechat`。
-- 当 `actions.reactions` 启用时，可通过 `reactions` 工具和 `channels action` 使用表情回应。
-- `typingIndicator` 支持 `none`、`message`（默认）和 `reaction`（reaction 需要用户 OAuth）。
-- 附件通过 Chat API 下载并存储在媒体管道中（大小受 `mediaMaxMb` 限制）。
-
-## 故障排除
-
-### 405 Method Not Allowed
-
-如果 Google Cloud Logs Explorer 显示如下错误：
-
-```
-status code: 405, reason phrase: HTTP error response: HTTP/1.1 405 Method Not Allowed
-```
-
-这意味着 webhook 处理程序未注册。常见原因：
-
-1. **渠道未配置**：配置中缺少 `channels.googlechat` 部分。使用以下命令验证：
-
-   ```bash
-   symi config get channels.googlechat
-   ```
-
-   如果返回"Config path not found"，请添加配置（参见[配置要点](#配置要点)）。
-
-2. **插件未启用**：检查插件状态：
-
-   ```bash
-   symi plugins list | grep googlechat
-   ```
-
-   如果显示"disabled"，请在配置中添加 `plugins.entries.googlechat.enabled: true`。
-
-3. **Gateway 网关未重启**：添加配置后，重启 Gateway 网关：
-   ```bash
-   symi gateway restart
-   ```
-
-验证渠道是否正在运行：
-
-```bash
-symi channels status
-# 应显示：Google Chat default: enabled, configured, ...
-```
-
-### 其他问题
-
-- 检查 `symi channels status --probe` 以查看认证错误或缺少 audience 配置。
-- 如果没有收到消息，请确认 Chat 应用的 webhook URL 和事件订阅。
-- 如果提及门控阻止了回复，请将 `botUser` 设置为应用的用户资源名称并验证 `requireMention`。
-- 在发送测试消息时使用 `symi logs --follow` 查看请求是否到达 Gateway 网关。
-
-相关文档：
-
-- [Gateway 网关配置](/gateway/configuration)
-- [安全](/gateway/security)
-- [表情回应](/tools/reactions)

package/docs/zh-CN/channels/grammy.md

@@ -1,38 +0,0 @@
----
-read_when:
-  - 开发 Telegram 或 grammY 相关功能时
-summary: 通过 grammY 集成 Telegram Bot API，附设置说明
-title: grammY
-x-i18n:
-  generated_at: "2026-02-03T10:03:55Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: ea7ef23e6d77801f4ef5fc56685ef4470f79f5aecab448d644a72cbab53521b7
-  source_path: channels/grammy.md
-  workflow: 15
----
-
-# grammY 集成（Telegram Bot API）
-
-# 为什么选择 grammY
-
-- 以 TS 为核心的 Bot API 客户端，内置长轮询 + webhook 辅助工具、中间件、错误处理和速率限制器。
-- 媒体处理辅助工具比手动编写 fetch + FormData 更简洁；支持所有 Bot API 方法。
-- 可扩展：通过自定义 fetch 支持代理，可选的会话中间件，类型安全的上下文。
-
-# 我们发布的内容
-
-- **单一客户端路径：** 移除了基于 fetch 的实现；grammY 现在是唯一的 Telegram 客户端（发送 + Gateway 网关），默认启用 grammY throttler。
-- **Gateway 网关：** `monitorTelegramProvider` 构建 grammY `Bot`，接入 mention/allowlist 网关控制，通过 `getFile`/`download` 下载媒体，并使用 `sendMessage/sendPhoto/sendVideo/sendAudio/sendDocument` 发送回复。通过 `webhookCallback` 支持长轮询或 webhook。
-- **代理：** 可选的 `channels.telegram.proxy` 通过 grammY 的 `client.baseFetch` 使用 `undici.ProxyAgent`。
-- **Webhook 支持：** `webhook-set.ts` 封装了 `setWebhook/deleteWebhook`；`webhook.ts` 托管回调，支持健康检查和优雅关闭。当设置了 `channels.telegram.webhookUrl` + `channels.telegram.webhookSecret` 时，Gateway 网关启用 webhook 模式（否则使用长轮询）。
-- **会话：** 私聊折叠到智能体主会话（`agent:<agentId>:<mainKey>`）；群组使用 `agent:<agentId>:telegram:group:<chatId>`；回复路由回同一渠道。
-- **配置选项：** `channels.telegram.botToken`、`channels.telegram.dmPolicy`、`channels.telegram.groups`（allowlist + mention 默认值）、`channels.telegram.allowFrom`、`channels.telegram.groupAllowFrom`、`channels.telegram.groupPolicy`、`channels.telegram.mediaMaxMb`、`channels.telegram.linkPreview`、`channels.telegram.proxy`、`channels.telegram.webhookSecret`、`channels.telegram.webhookUrl`。
-- **草稿流式传输：** 可选的 `channels.telegram.streamMode` 在私有话题聊天中使用 `sendMessageDraft`（Bot API 9.3+）。这与渠道分块流式传输是分开的。
-- **测试：** grammY mock 覆盖了私信 + 群组 mention 网关控制和出站发送；欢迎添加更多媒体/webhook 测试用例。
-
-待解决问题
-
-- 如果遇到 Bot API 429 错误，考虑使用可选的 grammY 插件（throttler）。
-- 添加更多结构化媒体测试（贴纸、语音消息）。
-- 使 webhook 监听端口可配置（目前固定为 8787，除非通过 Gateway 网关配置）。

package/docs/zh-CN/channels/group-messages.md

@@ -1,89 +0,0 @@
----
-read_when:
-  - 更改群组消息规则或提及设置时
-summary: WhatsApp 群组消息处理的行为和配置（mentionPatterns 在各平台间共享）
-title: 群组消息
-x-i18n:
-  generated_at: "2026-02-03T10:05:00Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 181a72f12f5021af77c2e4c913120f711e0c0bc271d218d75cb6fe80dab675bb
-  source_path: channels/group-messages.md
-  workflow: 15
----
-
-# 群组消息（WhatsApp 网页渠道）
-
-目标：让 Symi 留在 WhatsApp 群组中，仅在被提及时唤醒，并将该对话线程与个人私信会话分开。
-
-## 已实现的功能（2025-12-03）
-
-- 激活模式：`mention`（默认）或 `always`。`mention` 需要被提及（通过 `mentionedJids` 的真实 WhatsApp @提及、正则表达式模式，或文本中任意位置的机器人 E.164 号码）。`always` 会在每条消息时唤醒智能体，但它应该只在能提供有意义价值时才回复；否则返回静默令牌 `NO_REPLY`。默认值可在配置中设置（`channels.whatsapp.groups`），并可通过 `/activation` 为每个群组单独覆盖。当设置了 `channels.whatsapp.groups` 时，它同时充当群组允许列表（包含 `"*"` 以允许所有群组）。
-- 群组策略：`channels.whatsapp.groupPolicy` 控制是否接受群组消息（`open|disabled|allowlist`）。`allowlist` 使用 `channels.whatsapp.groupAllowFrom`（回退：显式的 `channels.whatsapp.allowFrom`）。默认为 `allowlist`（在你添加发送者之前被阻止）。
-- 独立群组会话：会话键格式为 `agent:<agentId>:whatsapp:group:<jid>`，因此 `/verbose on` 或 `/think high`（作为独立消息发送）等命令仅作用于该群组；个人私信状态不受影响。群组线程会跳过心跳。
-- 上下文注入：**仅待处理**的群组消息（默认 50 条），即*未*触发运行的消息，会以 `[Chat messages since your last reply - for context]` 为前缀注入，触发行在 `[Current message - respond to this]` 下。已在会话中的消息不会重复注入。
-- 发送者显示：每个群组批次现在以 `[from: Sender Name (+E164)]` 结尾，让 Pi 知道是谁在说话。
-- 阅后即焚/一次性查看：我们在提取文本/提及之前会先解包这些消息，因此其中的提及仍会触发。
-- 群组系统提示：在群组会话的第一轮（以及每当 `/activation` 更改模式时），我们会向系统提示注入一段简短说明，如 `You are replying inside the WhatsApp group "<subject>". Group members: Alice (+44...), Bob (+43...), … Activation: trigger-only … Address the specific sender noted in the message context.` 如果元数据不可用，我们仍会告知智能体这是一个群聊。
-
-## 配置示例（WhatsApp）
-
-在 `~/.symi/symi.json` 中添加 `groupChat` 块，以便在 WhatsApp 剥离文本正文中的可视 `@` 时，显示名称提及仍能正常工作：
-
-```json5
-{
-  channels: {
-    whatsapp: {
-      groups: {
-        "*": { requireMention: true },
-      },
-    },
-  },
-  agents: {
-    list: [
-      {
-        id: "main",
-        groupChat: {
-          historyLimit: 50,
-          mentionPatterns: ["@?symi", "\\+?15555550123"],
-        },
-      },
-    ],
-  },
-}
-```
-
-注意：
-
-- 正则表达式不区分大小写；它们涵盖了像 `@symi` 这样的显示名称提及，以及带或不带 `+`/空格的原始号码。
-- 当有人点击联系人时，WhatsApp 仍会通过 `mentionedJids` 发送规范的提及，因此号码回退很少需要，但作为安全网很有用。
-
-### 激活命令（仅所有者）
-
-使用群聊命令：
-
-- `/activation mention`
-- `/activation always`
-
-只有所有者号码（来自 `channels.whatsapp.allowFrom`，或未设置时使用机器人自己的 E.164）可以更改此设置。在群组中发送 `/status` 作为独立消息以查看当前激活模式。
-
-## 使用方法
-
-1. 将你的 WhatsApp 账号（运行 Symi 的账号）添加到群组。
-2. 说 `@symi …`（或包含号码）。只有允许列表中的发送者才能触发，除非你设置 `groupPolicy: "open"`。
-3. 智能体提示将包含最近的群组上下文以及尾部的 `[from: …]` 标记，以便它能够回应正确的人。
-4. 会话级指令（`/verbose on`、`/think high`、`/new` 或 `/reset`、`/compact`）仅适用于该群组的会话；将它们作为独立消息发送以使其生效。你的个人私信会话保持独立。
-
-## 测试/验证
-
-- 手动冒烟测试：
-  - 在群组中发送 `@symi` 提及，确认收到引用发送者名称的回复。
-  - 发送第二次提及，验证历史记录块被包含，然后在下一轮清除。
-- 检查 Gateway 网关日志（使用 `--verbose` 运行）以查看 `inbound web message` 条目，显示 `from: <groupJid>` 和 `[from: …]` 后缀。
-
-## 已知注意事项
-
-- 群组有意跳过心跳以避免嘈杂的广播。
-- 回声抑制使用组合的批次字符串；如果你发送两次相同的文本但没有提及，只有第一次会得到响应。
-- 会话存储条目将在会话存储中显示为 `agent:<agentId>:whatsapp:group:<jid>`（默认为 `~/.symi/agents/<agentId>/sessions/sessions.json`）；缺失条目只是意味着该群组尚未触发运行。
-- 群组中的输入指示器遵循 `agents.defaults.typingMode`（默认：未被提及时为 `message`）。