@symerian/symi 3.0.21 → 3.0.22

package/docs/zh-CN/concepts/multi-agent.md

@@ -1,371 +0,0 @@
----
-read_when: You want multiple isolated agents (workspaces + auth) in one gateway process.
-status: active
-summary: 多智能体路由：隔离的智能体、渠道账户和绑定
-title: 多智能体路由
-x-i18n:
-  generated_at: "2026-02-03T07:47:38Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 1848266c632cd6c96ff99ea9eb9c17bbfe6d35fa1f90450853083e7c548d5324
-  source_path: concepts/multi-agent.md
-  workflow: 15
----
-
-# 多智能体路由
-
-目标：多个*隔离的*智能体（独立的工作区 + `agentDir` + 会话），加上多个渠道账户（例如两个 WhatsApp）在一个运行的 Gateway 网关中。入站消息通过绑定路由到智能体。
-
-## 什么是"一个智能体"？
-
-一个**智能体**是一个完全独立作用域的大脑，拥有自己的：
-
-- **工作区**（文件、AGENTS.md/SYMICORE.md/USER.md、本地笔记、人设规则）。
-- **状态目录**（`agentDir`）用于认证配置文件、模型注册表和每智能体配置。
-- **会话存储**（聊天历史 + 路由状态）位于 `~/.symi/agents/<agentId>/sessions` 下。
-
-认证配置文件是**每智能体独立的**。每个智能体从自己的位置读取：
-
-```
-~/.symi/agents/<agentId>/agent/auth-profiles.json
-```
-
-主智能体凭证**不会**自动共享。切勿在智能体之间重用 `agentDir`（这会导致认证/会话冲突）。如果你想共享凭证，请将 `auth-profiles.json` 复制到另一个智能体的 `agentDir`。
-
-Skills 通过每个工作区的 `skills/` 文件夹实现每智能体独立，共享的 Skills 可从 `~/.symi/skills` 获取。参见 [Skills：每智能体 vs 共享](/tools/skills#per-agent-vs-shared-skills)。
-
-Gateway 网关可以托管**一个智能体**（默认）或**多个智能体**并行。
-
-**工作区注意事项：** 每个智能体的工作区是**默认 cwd**，而不是硬性沙箱。相对路径在工作区内解析，但绝对路径可以访问主机的其他位置，除非启用了沙箱隔离。参见 [沙箱隔离](/gateway/sandboxing)。
-
-## 路径（快速映射）
-
-- 配置：`~/.symi/symi.json`（或 `SYMI_CONFIG_PATH`）
-- 状态目录：`~/.symi`（或 `SYMI_STATE_DIR`）
-- 工作区：`~/.symi/workspace`（或 `~/.symi/workspace-<agentId>`）
-- 智能体目录：`~/.symi/agents/<agentId>/agent`（或 `agents.list[].agentDir`）
-- 会话：`~/.symi/agents/<agentId>/sessions`
-
-### 单智能体模式（默认）
-
-如果你什么都不做，Symi 运行单个智能体：
-
-- `agentId` 默认为 **`main`**。
-- 会话键为 `agent:main:<mainKey>`。
-- 工作区默认为 `~/.symi/workspace`（或当设置了 `SYMI_PROFILE` 时为 `~/.symi/workspace-<profile>`）。
-- 状态默认为 `~/.symi/agents/main/agent`。
-
-## 智能体助手
-
-使用智能体向导添加新的隔离智能体：
-
-```bash
-symi agents add work
-```
-
-然后添加 `bindings`（或让向导完成）来路由入站消息。
-
-验证：
-
-```bash
-symi agents list --bindings
-```
-
-## 多个智能体 = 多个人、多种人格
-
-使用**多个智能体**，每个 `agentId` 成为一个**完全隔离的人格**：
-
-- **不同的电话号码/账户**（每渠道 `accountId`）。
-- **不同的人格**（每智能体工作区文件如 `AGENTS.md` 和 `SYMICORE.md`）。
-- **独立的认证 + 会话**（除非明确启用，否则无交叉通信）。
-
-这让**多个人**共享一个 Gateway 网关服务器，同时保持他们的 AI"大脑"和数据隔离。
-
-## 一个 WhatsApp 号码，多个人（私信分割）
-
-你可以将**不同的 WhatsApp 私信**路由到不同的智能体，同时保持**一个 WhatsApp 账户**。使用 `peer.kind: "dm"` 匹配发送者 E.164（如 `+15551234567`）。回复仍然来自同一个 WhatsApp 号码（无每智能体发送者身份）。
-
-重要细节：直接聊天折叠到智能体的**主会话键**，因此真正的隔离需要**每人一个智能体**。
-
-示例：
-
-```json5
-{
-  agents: {
-    list: [
-      { id: "alex", workspace: "~/.symi/workspace-alex" },
-      { id: "mia", workspace: "~/.symi/workspace-mia" },
-    ],
-  },
-  bindings: [
-    { agentId: "alex", match: { channel: "whatsapp", peer: { kind: "dm", id: "+15551230001" } } },
-    { agentId: "mia", match: { channel: "whatsapp", peer: { kind: "dm", id: "+15551230002" } } },
-  ],
-  channels: {
-    whatsapp: {
-      dmPolicy: "allowlist",
-      allowFrom: ["+15551230001", "+15551230002"],
-    },
-  },
-}
-```
-
-注意事项：
-
-- 私信访问控制是**每 WhatsApp 账户全局的**（配对/允许列表），而不是每智能体。
-- 对于共享群组，将群组绑定到一个智能体或使用 [广播群组](/channels/broadcast-groups)。
-
-## 路由规则（消息如何选择智能体）
-
-绑定是**确定性的**，**最具体的优先**：
-
-1. `peer` 匹配（精确私信/群组/频道 id）
-2. `teamId`（Slack）
-3. 渠道的 `accountId` 匹配
-4. 渠道级匹配（`accountId: "*"`）
-5. 回退到默认智能体（`agents.list[].default`，否则列表中的第一个条目，默认：`main`）
-
-## 多账户/电话号码
-
-支持**多账户**的渠道（如 WhatsApp）使用 `accountId` 来识别每个登录。每个 `accountId` 可以路由到不同的智能体，因此一个服务器可以托管多个电话号码而不混合会话。
-
-## 概念
-
-- `agentId`：一个"大脑"（工作区、每智能体认证、每智能体会话存储）。
-- `accountId`：一个渠道账户实例（例如 WhatsApp 账户 `"personal"` vs `"biz"`）。
-- `binding`：通过 `(channel, accountId, peer)` 以及可选的 guild/team id 将入站消息路由到 `agentId`。
-- 直接聊天折叠到 `agent:<agentId>:<mainKey>`（每智能体"主"；`session.mainKey`）。
-
-## 示例：两个 WhatsApp → 两个智能体
-
-`~/.symi/symi.json`（JSON5）：
-
-```js
-{
-  agents: {
-    list: [
-      {
-        id: "home",
-        default: true,
-        name: "Home",
-        workspace: "~/.symi/workspace-home",
-        agentDir: "~/.symi/agents/home/agent",
-      },
-      {
-        id: "work",
-        name: "Work",
-        workspace: "~/.symi/workspace-work",
-        agentDir: "~/.symi/agents/work/agent",
-      },
-    ],
-  },
-
-  // 确定性路由：第一个匹配获胜（最具体的优先）。
-  bindings: [
-    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
-    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
-
-    // 可选的每对等方覆盖（示例：将特定群组发送到 work 智能体）。
-    {
-      agentId: "work",
-      match: {
-        channel: "whatsapp",
-        accountId: "personal",
-        peer: { kind: "group", id: "1203630...@g.us" },
-      },
-    },
-  ],
-
-  // 默认关闭：智能体到智能体的消息必须明确启用 + 加入允许列表。
-  tools: {
-    agentToAgent: {
-      enabled: false,
-      allow: ["home", "work"],
-    },
-  },
-
-  channels: {
-    whatsapp: {
-      accounts: {
-        personal: {
-          // 可选覆盖。默认：~/.symi/credentials/whatsapp/personal
-          // authDir: "~/.symi/credentials/whatsapp/personal",
-        },
-        biz: {
-          // 可选覆盖。默认：~/.symi/credentials/whatsapp/biz
-          // authDir: "~/.symi/credentials/whatsapp/biz",
-        },
-      },
-    },
-  },
-}
-```
-
-## 示例：WhatsApp 日常聊天 + Telegram 深度工作
-
-按渠道分割：将 WhatsApp 路由到快速日常智能体，Telegram 路由到 Opus 智能体。
-
-```json5
-{
-  agents: {
-    list: [
-      {
-        id: "chat",
-        name: "Everyday",
-        workspace: "~/.symi/workspace-chat",
-        model: "anthropic/claude-sonnet-4-5",
-      },
-      {
-        id: "opus",
-        name: "Deep Work",
-        workspace: "~/.symi/workspace-opus",
-        model: "anthropic/claude-opus-4-5",
-      },
-    ],
-  },
-  bindings: [
-    { agentId: "chat", match: { channel: "whatsapp" } },
-    { agentId: "opus", match: { channel: "telegram" } },
-  ],
-}
-```
-
-注意事项：
-
-- 如果你有一个渠道的多个账户，请在绑定中添加 `accountId`（例如 `{ channel: "whatsapp", accountId: "personal" }`）。
-- 要将单个私信/群组路由到 Opus 而保持其余在 chat 上，请为该对等方添加 `match.peer` 绑定；对等方匹配始终优先于渠道级规则。
-
-## 示例：同一渠道，一个对等方到 Opus
-
-保持 WhatsApp 在快速智能体上，但将一个私信路由到 Opus：
-
-```json5
-{
-  agents: {
-    list: [
-      {
-        id: "chat",
-        name: "Everyday",
-        workspace: "~/.symi/workspace-chat",
-        model: "anthropic/claude-sonnet-4-5",
-      },
-      {
-        id: "opus",
-        name: "Deep Work",
-        workspace: "~/.symi/workspace-opus",
-        model: "anthropic/claude-opus-4-5",
-      },
-    ],
-  },
-  bindings: [
-    { agentId: "opus", match: { channel: "whatsapp", peer: { kind: "dm", id: "+15551234567" } } },
-    { agentId: "chat", match: { channel: "whatsapp" } },
-  ],
-}
-```
-
-对等方绑定始终获胜，因此将它们放在渠道级规则之上。
-
-## 绑定到 WhatsApp 群组的家庭智能体
-
-将专用家庭智能体绑定到单个 WhatsApp 群组，使用提及限制和更严格的工具策略：
-
-```json5
-{
-  agents: {
-    list: [
-      {
-        id: "family",
-        name: "Family",
-        workspace: "~/.symi/workspace-family",
-        identity: { name: "Family Bot" },
-        groupChat: {
-          mentionPatterns: ["@family", "@familybot", "@Family Bot"],
-        },
-        sandbox: {
-          mode: "all",
-          scope: "agent",
-        },
-        tools: {
-          allow: [
-            "exec",
-            "read",
-            "sessions_list",
-            "sessions_history",
-            "sessions_send",
-            "sessions_spawn",
-            "session_status",
-          ],
-          deny: ["write", "edit", "apply_patch", "browser", "canvas", "nodes", "cron"],
-        },
-      },
-    ],
-  },
-  bindings: [
-    {
-      agentId: "family",
-      match: {
-        channel: "whatsapp",
-        peer: { kind: "group", id: "120363999999999999@g.us" },
-      },
-    },
-  ],
-}
-```
-
-注意事项：
-
-- 工具允许/拒绝列表是**工具**，不是 Skills。如果 skill 需要运行二进制文件，请确保 `exec` 被允许且二进制文件存在于沙箱中。
-- 对于更严格的限制，设置 `agents.list[].groupChat.mentionPatterns` 并为渠道保持群组允许列表启用。
-
-## 每智能体沙箱和工具配置
-
-从 v2026.1.6 开始，每个智能体可以有自己的沙箱和工具限制：
-
-```js
-{
-  agents: {
-    list: [
-      {
-        id: "personal",
-        workspace: "~/.symi/workspace-personal",
-        sandbox: {
-          mode: "off",  // 个人智能体无沙箱
-        },
-        // 无工具限制 - 所有工具可用
-      },
-      {
-        id: "family",
-        workspace: "~/.symi/workspace-family",
-        sandbox: {
-          mode: "all",     // 始终沙箱隔离
-          scope: "agent",  // 每智能体一个容器
-          docker: {
-            // 容器创建后的可选一次性设置
-            setupCommand: "apt-get update && apt-get install -y git curl",
-          },
-        },
-        tools: {
-          allow: ["read"],                    // 仅 read 工具
-          deny: ["exec", "write", "edit", "apply_patch"],    // 拒绝其他
-        },
-      },
-    ],
-  },
-}
-```
-
-注意：`setupCommand` 位于 `sandbox.docker` 下，在容器创建时运行一次。
-当解析的 scope 为 `"shared"` 时，每智能体 `sandbox.docker.*` 覆盖会被忽略。
-
-**好处：**
-
-- **安全隔离**：限制不受信任智能体的工具
-- **资源控制**：沙箱隔离特定智能体同时保持其他智能体在主机上
-- **灵活策略**：每智能体不同的权限
-
-注意：`tools.elevated` 是**全局的**且基于发送者；不能按智能体配置。
-如果你需要每智能体边界，使用 `agents.list[].tools` 拒绝 `exec`。
-对于群组定向，使用 `agents.list[].groupChat.mentionPatterns` 使 @提及清晰地映射到目标智能体。
-
-参见 [多智能体沙箱和工具](/tools/multi-agent-sandbox-tools) 了解详细示例。

package/docs/zh-CN/concepts/oauth.md

@@ -1,151 +0,0 @@
----
-read_when:
-  - 你想全面了解 Symi 的 OAuth 流程
-  - 你遇到了令牌失效/登出问题
-  - 你想了解 setup-token 或 OAuth 认证流程
-  - 你想使用多账户或配置文件路由
-summary: Symi 中的 OAuth：令牌交换、存储和多账户模式
-title: OAuth
-x-i18n:
-  generated_at: "2026-02-01T20:23:29Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: af714bdadc4a89295a18da1eba5f5b857c8d533ebabe9b0758b722fe60c36124
-  source_path: concepts/oauth.md
-  workflow: 14
----
-
-# OAuth
-
-Symi 支持通过 OAuth 进行"订阅认证"，适用于提供此功能的提供商（特别是 **OpenAI Codex（ChatGPT OAuth）**）。对于 Anthropic 订阅，请使用 **setup-token** 流程。本页说明：
-
-- OAuth **令牌交换**的工作原理（PKCE）
-- 令牌**存储**在哪里（以及原因）
-- 如何处理**多账户**（配置文件 + 按会话覆盖）
-
-Symi 还支持**提供商插件**，它们自带 OAuth 或 API 密钥流程。通过以下命令运行：
-
-```bash
-symi models auth login --provider <id>
-```
-
-## 令牌汇聚点（为什么需要它）
-
-OAuth 提供商通常在登录/刷新流程中发放**新的刷新令牌**。某些提供商（或 OAuth 客户端）在为同一用户/应用发放新令牌时，可能会使旧的刷新令牌失效。
-
-实际症状：
-
-- 你通过 Symi _和_ Claude Code / Codex CLI 登录 → 其中一个稍后会随机"登出"
-
-为减少这种情况，Symi 将 `auth-profiles.json` 视为**令牌汇聚点**：
-
-- 运行时从**同一个位置**读取凭据
-- 我们可以保留多个配置文件并确定性地路由它们
-
-## 存储（令牌存放位置）
-
-密钥按**智能体**存储：
-
-- 认证配置文件（OAuth + API 密钥）：`~/.symi/agents/<agentId>/agent/auth-profiles.json`
-- 运行时缓存（自动管理；请勿编辑）：`~/.symi/agents/<agentId>/agent/auth.json`
-
-仅用于导入的旧版文件（仍然支持，但不是主存储）：
-
-- `~/.symi/credentials/oauth.json`（首次使用时导入到 `auth-profiles.json`）
-
-以上所有路径也遵循 `$SYMI_STATE_DIR`（状态目录覆盖）。完整参考：[/gateway/configuration](/gateway/configuration#auth-storage-oauth--api-keys)
-
-## Anthropic setup-token（订阅认证）
-
-在任意机器上运行 `claude setup-token`，然后将其粘贴到 Symi 中：
-
-```bash
-symi models auth setup-token --provider anthropic
-```
-
-如果你在其他地方生成了令牌，可以手动粘贴：
-
-```bash
-symi models auth paste-token --provider anthropic
-```
-
-验证：
-
-```bash
-symi models status
-```
-
-## OAuth 交换（登录工作原理）
-
-Symi 的交互式登录流程在 `@mariozechner/pi-ai` 中实现，并集成到向导/命令中。
-
-### Anthropic（Claude Pro/Max）setup-token
-
-流程概要：
-
-1. 运行 `claude setup-token`
-2. 将令牌粘贴到 Symi
-3. 作为令牌认证配置文件存储（无刷新）
-
-向导路径为 `symi onboard` → 认证选择 `setup-token`（Anthropic）。
-
-### OpenAI Codex（ChatGPT OAuth）
-
-流程概要（PKCE）：
-
-1. 生成 PKCE 验证器/质询 + 随机 `state`
-2. 打开 `https://auth.openai.com/oauth/authorize?...`
-3. 尝试在 `http://127.0.0.1:1455/auth/callback` 捕获回调
-4. 如果回调无法绑定（或你在远程/无头环境中），手动粘贴重定向 URL/代码
-5. 在 `https://auth.openai.com/oauth/token` 进行交换
-6. 从访问令牌中提取 `accountId` 并存储 `{ access, refresh, expires, accountId }`
-
-向导路径为 `symi onboard` → 认证选择 `openai-codex`。
-
-## 刷新 + 过期
-
-配置文件存储 `expires` 时间戳。
-
-运行时：
-
-- 如果 `expires` 在未来 → 使用已存储的访问令牌
-- 如果已过期 → 刷新（在文件锁下）并覆盖已存储的凭据
-
-刷新流程是自动的；你通常不需要手动管理令牌。
-
-## 多账户（配置文件）+ 路由
-
-两种模式：
-
-### 1）推荐：独立智能体
-
-如果你希望"个人"和"工作"永远不交叉，请使用隔离的智能体（独立的会话 + 凭据 + 工作区）：
-
-```bash
-symi agents add work
-symi agents add personal
-```
-
-然后按智能体配置认证（向导），并将聊天路由到正确的智能体。
-
-### 2）高级：单个智能体中的多个配置文件
-
-`auth-profiles.json` 支持同一提供商的多个配置文件 ID。
-
-选择使用哪个配置文件：
-
-- 通过配置顺序全局设置（`auth.order`）
-- 通过 `/model ...@<profileId>` 按会话设置
-
-示例（会话覆盖）：
-
-- `/model Opus@anthropic:work`
-
-如何查看存在哪些配置文件 ID：
-
-- `symi channels list --json`（显示 `auth[]`）
-
-相关文档：
-
-- [/concepts/model-failover](/concepts/model-failover)（轮换 + 冷却规则）
-- [/tools/slash-commands](/tools/slash-commands)（命令界面）

package/docs/zh-CN/concepts/presence.md

@@ -1,99 +0,0 @@
----
-read_when:
-  - 调试实例标签页
-  - 排查重复或过期的实例行
-  - 更改 Gateway 网关 WS 连接或系统事件信标
-summary: Symi 在线状态条目如何生成、合并和显示
-title: 在线状态
-x-i18n:
-  generated_at: "2026-02-03T07:46:37Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: c752c76a880878fed673d656db88beb5dbdeefff2491985127ad791521f97d00
-  source_path: concepts/presence.md
-  workflow: 15
----
-
-# 在线状态
-
-Symi"在线状态"是以下内容的轻量级、尽力而为的视图：
-
-- **Gateway 网关**本身，以及
-- **连接到 Gateway 网关的客户端**（mac 应用、WebChat、CLI 等）
-
-在线状态主要用于渲染 macOS 应用的**实例**标签页，并为运维人员提供快速可见性。
-
-## 在线状态字段（显示的内容）
-
-在线状态条目是具有以下字段的结构化对象：
-
-- `instanceId`（可选但强烈推荐）：稳定的客户端身份（通常是 `connect.client.instanceId`）
-- `host`：人类友好的主机名
-- `ip`：尽力而为的 IP 地址
-- `version`：客户端版本字符串
-- `deviceFamily` / `modelIdentifier`：硬件提示
-- `mode`：`ui`、`webchat`、`cli`、`backend`、`probe`、`test`、`node`，...
-- `lastInputSeconds`："自上次用户输入以来的秒数"（如果已知）
-- `reason`：`self`、`connect`、`node-connected`、`periodic`，...
-- `ts`：最后更新时间戳（自纪元以来的毫秒数）
-
-## 生产者（在线状态来源）
-
-在线状态条目由多个来源生成并**合并**。
-
-### 1）Gateway 网关自身条目
-
-Gateway 网关始终在启动时植入一个"self"条目，这样即使在任何客户端连接之前，UI 也能显示 Gateway 网关主机。
-
-### 2）WebSocket 连接
-
-每个 WS 客户端都以 `connect` 请求开始。在成功握手后，Gateway 网关为该连接更新插入一个在线状态条目。
-
-#### 为什么一次性 CLI 命令不会显示
-
-CLI 经常为短暂的一次性命令进行连接。为避免实例列表被刷屏，`client.mode === "cli"` **不会**被转换为在线状态条目。
-
-### 3）`system-event` 信标
-
-客户端可以通过 `system-event` 方法发送更丰富的周期性信标。mac 应用使用此方法报告主机名、IP 和 `lastInputSeconds`。
-
-### 4）节点连接（role: node）
-
-当节点通过 Gateway 网关 WebSocket 以 `role: node` 连接时，Gateway 网关为该节点更新插入一个在线状态条目（与其他 WS 客户端流程相同）。
-
-## 合并 + 去重规则（为什么 `instanceId` 很重要）
-
-在线状态条目存储在单个内存映射中：
-
-- 条目以**在线状态键**为索引。
-- 最佳键是稳定的 `instanceId`（来自 `connect.client.instanceId`），它在重启后仍然有效。
-- 键不区分大小写。
-
-如果客户端在没有稳定 `instanceId` 的情况下重新连接，它可能会显示为**重复**行。
-
-## TTL 和有界大小
-
-在线状态是有意设计为短暂的：
-
-- **TTL：** 超过 5 分钟的条目会被修剪
-- **最大条目数：** 200（最旧的优先删除）
-
-这使列表保持新鲜并避免无限制的内存增长。
-
-## 远程/隧道注意事项（回环 IP）
-
-当客户端通过 SSH 隧道/本地端口转发连接时，Gateway 网关可能会看到远程地址为 `127.0.0.1`。为避免覆盖客户端报告的有效 IP，回环远程地址会被忽略。
-
-## 消费者
-
-### macOS 实例标签页
-
-macOS 应用渲染 `system-presence` 的输出，并根据最后更新的时间应用一个小的状态指示器（活跃/空闲/过期）。
-
-## 调试技巧
-
-- 要查看原始列表，对 Gateway 网关调用 `system-presence`。
-- 如果你看到重复项：
-  - 确认客户端在握手中发送稳定的 `client.instanceId`
-  - 确认周期性信标使用相同的 `instanceId`
-  - 检查连接派生的条目是否缺少 `instanceId`（这种情况下重复是预期的）