@symerian/symi 3.0.21 → 3.0.22

package/docs/zh-CN/tools/chrome-extension.md

@@ -1,183 +0,0 @@
----
-read_when:
-  - 你希望智能体驱动现有的 Chrome 标签页（工具栏按钮）
-  - 你需要通过 Tailscale 实现远程 Gateway 网关 + 本地浏览器自动化
-  - 你想了解浏览器接管的安全影响
-summary: Chrome 扩展：让 Symi 驱动你现有的 Chrome 标签页
-title: Chrome 扩展
-x-i18n:
-  generated_at: "2026-02-03T07:55:32Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 3b77bdad7d3dab6adb76ff25b144412d6b54b915993b1c1f057f36dea149938b
-  source_path: tools/chrome-extension.md
-  workflow: 15
----
-
-# Chrome 扩展（浏览器中继）
-
-Symi Chrome 扩展让智能体控制你**现有的 Chrome 标签页**（你的正常 Chrome 窗口），而不是启动一个单独的 symi 管理的 Chrome 配置文件。
-
-附加/分离通过一个**单独的 Chrome 工具栏按钮**实现。
-
-## 它是什么（概念）
-
-有三个部分：
-
-- **浏览器控制服务**（Gateway 网关或节点）：智能体/工具调用的 API（通过 Gateway 网关）
-- **本地中继服务器**（loopback CDP）：在控制服务器和扩展之间桥接（默认 `http://127.0.0.1:18792`）
-- **Chrome MV3 扩展**：使用 `chrome.debugger` 附加到活动标签页，并将 CDP 消息传送到中继
-
-然后 Symi 通过正常的 `browser` 工具界面控制附加的标签页（选择正确的配置文件）。
-
-## 安装/加载（未打包）
-
-1. 将扩展安装到稳定的本地路径：
-
-```bash
-symi browser extension install
-```
-
-2. 打印已安装扩展的目录路径：
-
-```bash
-symi browser extension path
-```
-
-3. Chrome → `chrome://extensions`
-
-- 启用"开发者模式"
-- "加载已解压的扩展程序" → 选择上面打印的目录
-
-4. 固定扩展。
-
-## 更新（无构建步骤）
-
-扩展作为静态文件包含在 Symi 发布版（npm 包）中。没有单独的"构建"步骤。
-
-升级 Symi 后：
-
-- 重新运行 `symi browser extension install` 以刷新 Symi 状态目录下的已安装文件。
-- Chrome → `chrome://extensions` → 点击扩展上的"重新加载"。
-
-## 使用它（无需额外配置）
-
-Symi 附带一个名为 `chrome` 的内置浏览器配置文件，它指向默认端口上的扩展中继。
-
-使用它：
-
-- CLI：`symi browser --browser-profile chrome tabs`
-- 智能体工具：`browser` 配合 `profile="chrome"`
-
-如果你想要不同的名称或不同的中继端口，创建你自己的配置文件：
-
-```bash
-symi browser create-profile \
-  --name my-chrome \
-  --driver extension \
-  --cdp-url http://127.0.0.1:18792 \
-  --color "#00AA00"
-```
-
-## 附加/分离（工具栏按钮）
-
-- 打开你希望 Symi 控制的标签页。
-- 点击扩展图标。
-  - 附加时徽章显示 `ON`。
-- 再次点击以分离。
-
-## 它控制哪个标签页？
-
-- 它**不会**自动控制"你正在查看的任何标签页"。
-- 它**仅**控制你通过点击工具栏按钮**明确附加的标签页**。
-- 要切换：打开另一个标签页并在那里点击扩展图标。
-
-## 徽章 + 常见错误
-
-- `ON`：已附加；Symi 可以驱动该标签页。
-- `…`：正在连接到本地中继。
-- `!`：中继不可达（最常见：浏览器中继服务器未在此机器上运行）。
-
-如果你看到 `!`：
-
-- 确保 Gateway 网关在本地运行（默认设置），或者如果 Gateway 网关在其他地方运行，在此机器上运行一个节点主机。
-- 打开扩展选项页面；它会显示中继是否可达。
-
-## 远程 Gateway 网关（使用节点主机）
-
-### 本地 Gateway 网关（与 Chrome 在同一台机器上）——通常**无需额外步骤**
-
-如果 Gateway 网关运行在与 Chrome 相同的机器上，它会在 loopback 上启动浏览器控制服务并自动启动中继服务器。扩展与本地中继通信；CLI/工具调用发送到 Gateway 网关。
-
-### 远程 Gateway 网关（Gateway 网关运行在其他地方）——**运行节点主机**
-
-如果你的 Gateway 网关运行在另一台机器上，在运行 Chrome 的机器上启动一个节点主机。Gateway 网关将把浏览器操作代理到该节点；扩展 + 中继保持在浏览器机器本地。
-
-如果连接了多个节点，使用 `gateway.nodes.browser.node` 固定一个或设置 `gateway.nodes.browser.mode`。
-
-## 沙箱隔离（工具容器）
-
-如果你的智能体会话在沙箱中（`agents.defaults.sandbox.mode != "off"`），`browser` 工具可能受到限制：
-
-- 默认情况下，沙箱隔离的会话通常指向**沙箱浏览器**（`target="sandbox"`），而不是你的主机 Chrome。
-- Chrome 扩展中继接管需要控制**主机**浏览器控制服务器。
-
-选项：
-
-- 最简单：从**非沙箱隔离**的会话/智能体使用扩展。
-- 或者为沙箱隔离的会话允许主机浏览器控制：
-
-```json5
-{
-  agents: {
-    defaults: {
-      sandbox: {
-        browser: {
-          allowHostControl: true,
-        },
-      },
-    },
-  },
-}
-```
-
-然后确保工具未被工具策略拒绝，并（如果需要）以 `target="host"` 调用 `browser`。
-
-调试：`symi sandbox explain`
-
-## 远程访问提示
-
-- 将 Gateway 网关和节点主机保持在同一个 tailnet 上；避免将中继端口暴露到 LAN 或公共 Internet。
-- 有意配对节点；如果你不想要远程控制，禁用浏览器代理路由（`gateway.nodes.browser.mode="off"`）。
-
-## "extension path"的工作原理
-
-`symi browser extension path` 打印包含扩展文件的**已安装**磁盘目录。
-
-CLI 有意**不**打印 `node_modules` 路径。始终先运行 `symi browser extension install` 将扩展复制到 Symi 状态目录下的稳定位置。
-
-如果你移动或删除该安装目录，Chrome 将把扩展标记为损坏，直到你从有效路径重新加载它。
-
-## 安全影响（请阅读此内容）
-
-这是强大且有风险的。将其视为给模型"在你的浏览器上动手"。
-
-- 扩展使用 Chrome 的调试器 API（`chrome.debugger`）。附加时，模型可以：
-  - 在该标签页中点击/输入/导航
-  - 读取页面内容
-  - 访问标签页已登录会话可以访问的任何内容
-- **这不像**专用的 symi 管理配置文件那样隔离。
-  - 如果你附加到你的日常使用配置文件/标签页，你就是在授予对该账户状态的访问权限。
-
-建议：
-
-- 对于扩展中继使用，优先使用专用的 Chrome 配置文件（与你的个人浏览分开）。
-- 将 Gateway 网关和任何节点主机保持在仅限 tailnet；依赖 Gateway 网关身份验证 + 节点配对。
-- 避免通过 LAN（`0.0.0.0`）暴露中继端口，避免使用 Funnel（公开）。
-- 中继阻止非扩展来源，并要求 CDP 客户端提供内部身份验证令牌。
-
-相关：
-
-- 浏览器工具概述：[浏览器](/tools/browser)
-- 安全审计：[安全](/gateway/security)
-- Tailscale 设置：[Tailscale](/gateway/tailscale)

package/docs/zh-CN/tools/creating-skills.md

@@ -1,61 +0,0 @@
----
-title: 创建 Skills
-x-i18n:
-  generated_at: "2026-02-03T10:10:19Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: ad801da34fe361ffa584ded47f775d1c104a471a3f7b7f930652255e98945c3a
-  source_path: tools/creating-skills.md
-  workflow: 15
----
-
-# 创建自定义 Skills 🛠
-
-Symi 被设计为易于扩展。"Skills"是为你的助手添加新功能的主要方式。
-
-## 什么是 Skill？
-
-Skill 是一个包含 `SKILL.md` 文件（为 LLM 提供指令和工具定义）的目录，可选包含一些脚本或资源。
-
-## 分步指南：你的第一个 Skill
-
-### 1. 创建目录
-
-Skills 位于你的工作区中，通常是 `~/.symi/workspace/skills/`。为你的 Skill 创建一个新文件夹：
-
-```bash
-mkdir -p ~/.symi/workspace/skills/hello-world
-```
-
-### 2. 定义 `SKILL.md`
-
-在该目录中创建一个 `SKILL.md` 文件。此文件使用 YAML frontmatter 作为元数据，使用 Markdown 作为指令。
-
-```markdown
----
-name: hello_world
-description: A simple skill that says hello.
----
-
-# Hello World Skill
-
-When the user asks for a greeting, use the `echo` tool to say "Hello from your custom skill!".
-```
-
-### 3. 添加工具（可选）
-
-你可以在 frontmatter 中定义自定义工具，或指示智能体使用现有的系统工具（如 `bash` 或 `browser`）。
-
-### 4. 刷新 Symi
-
-让你的智能体"刷新 skills"或重启 Gateway 网关。Symi 将发现新目录并索引 `SKILL.md`。
-
-## 最佳实践
-
-- **简洁明了**：指示模型*做什么*，而不是如何成为一个 AI。
-- **安全第一**：如果你的 Skill 使用 `bash`，确保提示词不允许来自不受信任用户输入的任意命令注入。
-- **本地测试**：使用 `symi agent --message "use my new skill"` 进行测试。
-
-## 共享 Skills
-
-你也可以在 [SymiHub](https://symihub.com) 上浏览和贡献 Skills。

package/docs/zh-CN/tools/elevated.md

@@ -1,62 +0,0 @@
----
-read_when:
-  - 调整提升模式默认值、允许列表或斜杠命令行为
-summary: 提升的 exec 模式和 /elevated 指令
-title: 提升模式
-x-i18n:
-  generated_at: "2026-02-03T07:55:23Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 83767a01609304026d145feb0aa0b0533e8cf8b16cd200f724d9e3e8cf2920c3
-  source_path: tools/elevated.md
-  workflow: 15
----
-
-# 提升模式（/elevated 指令）
-
-## 功能说明
-
-- `/elevated on` 在 Gateway 网关主机上运行并保留 exec 审批（与 `/elevated ask` 相同）。
-- `/elevated full` 在 Gateway 网关主机上运行**并**自动批准 exec（跳过 exec 审批）。
-- `/elevated ask` 在 Gateway 网关主机上运行但保留 exec 审批（与 `/elevated on` 相同）。
-- `on`/`ask` **不会**强制 `exec.security=full`；配置的安全/询问策略仍然适用。
-- 仅在智能体被**沙箱隔离**时改变行为（否则 exec 已经在主机上运行）。
-- 指令形式：`/elevated on|off|ask|full`、`/elev on|off|ask|full`。
-- 仅接受 `on|off|ask|full`；其他任何内容返回提示且不改变状态。
-
-## 它控制什么（以及不控制什么）
-
-- **可用性门控**：`tools.elevated` 是全局基线。`agents.list[].tools.elevated` 可以进一步限制每个智能体的提升（两者都必须允许）。
-- **每会话状态**：`/elevated on|off|ask|full` 为当前会话键设置提升级别。
-- **内联指令**：消息内的 `/elevated on|ask|full` 仅适用于该消息。
-- **群组**：在群聊中，仅当智能体被提及时才遵守提升指令。绕过提及要求的纯命令消息被视为已提及。
-- **主机执行**：elevated 强制 `exec` 到 Gateway 网关主机；`full` 还设置 `security=full`。
-- **审批**：`full` 跳过 exec 审批；`on`/`ask` 在允许列表/询问规则要求时遵守审批。
-- **非沙箱隔离智能体**：对位置无影响；仅影响门控、日志和状态。
-- **工具策略仍然适用**：如果 `exec` 被工具策略拒绝，则无法使用 elevated。
-- **与 `/exec` 分开**：`/exec` 为授权发送者调整每会话默认值，不需要 elevated。
-
-## 解析顺序
-
-1. 消息上的内联指令（仅适用于该消息）。
-2. 会话覆盖（通过发送仅含指令的消息设置）。
-3. 全局默认值（配置中的 `agents.defaults.elevatedDefault`）。
-
-## 设置会话默认值
-
-- 发送一条**仅**包含指令的消息（允许空白），例如 `/elevated full`。
-- 发送确认回复（`Elevated mode set to full...` / `Elevated mode disabled.`）。
-- 如果 elevated 访问被禁用或发送者不在批准的允许列表中，指令会回复一个可操作的错误且不改变会话状态。
-- 发送不带参数的 `/elevated`（或 `/elevated:`）以查看当前的 elevated 级别。
-
-## 可用性 + 允许列表
-
-- 功能门控：`tools.elevated.enabled`（即使代码支持，也可以通过配置将默认值设为关闭）。
-- 每智能体门控：`agents.list[].tools.elevated.enabled`（可选；只能进一步限制）。
-- 每智能体允许列表：`agents.list[].tools.elevated.allowFrom`（可选；设置时，发送者必须同时匹配全局 + 每智能体允许列表）。
-- 所有门控都必须通过；否则 elevated 被视为不可用。
-
-## 日志 + 状态
-
-- Elevated exec 调用以 info 级别记录。
-- 会话状态包括 elevated 模式（例如 `elevated=ask`、`elevated=full`）。

package/docs/zh-CN/tools/exec-approvals.md

@@ -1,233 +0,0 @@
----
-read_when:
-  - 配置执行审批或允许列表
-  - 在 macOS 应用中实现执行审批用户体验
-  - 审查沙箱逃逸提示及其影响
-summary: 执行审批、允许列表和沙箱逃逸提示
-title: 执行审批
-x-i18n:
-  generated_at: "2026-02-03T08:19:51Z"
-  model: claude-opus-4-5
-  provider: pi
-  source_hash: 97736427752eb905bb5d1f5b54bddbdea38eb5ac5824e2bf99258fcf44ee393c
-  source_path: tools/exec-approvals.md
-  workflow: 15
----
-
-# 执行审批
-
-执行审批是**配套应用/节点主机的安全护栏**，用于允许沙箱隔离的智能体在真实主机（`gateway` 或 `node`）上运行命令。可以将其理解为安全联锁：只有当策略 + 允许列表 +（可选的）用户审批都同意时，命令才会被允许执行。
-执行审批是**附加于**工具策略和提权门控之上的（除非 elevated 设置为 `full`，这会跳过审批）。
-生效策略取 `tools.exec.*` 和审批默认值中**更严格**的一方；如果审批字段被省略，则使用 `tools.exec` 的值。
-
-如果配套应用 UI **不可用**，任何需要提示的请求都将由 **ask fallback**（默认：deny）决定。
-
-## 适用范围
-
-执行审批在执行主机上本地强制执行：
-
-- **gateway 主机** → gateway 机器上的 `symi` 进程
-- **node 主机** → 节点运行器（macOS 配套应用或无头节点主机）
-
-macOS 分工：
-
-- **node 主机服务**通过本地 IPC 将 `system.run` 转发给 **macOS 应用**。
-- **macOS 应用**执行审批并在 UI 上下文中执行命令。
-
-## 设置和存储
-
-审批信息存储在执行主机上的本地 JSON 文件中：
-
-`~/.symi/exec-approvals.json`
-
-示例结构：
-
-```json
-{
-  "version": 1,
-  "socket": {
-    "path": "~/.symi/exec-approvals.sock",
-    "token": "base64url-token"
-  },
-  "defaults": {
-    "security": "deny",
-    "ask": "on-miss",
-    "askFallback": "deny",
-    "autoAllowSkills": false
-  },
-  "agents": {
-    "main": {
-      "security": "allowlist",
-      "ask": "on-miss",
-      "askFallback": "deny",
-      "autoAllowSkills": true,
-      "allowlist": [
-        {
-          "id": "B0C8C0B3-2C2D-4F8A-9A3C-5A4B3C2D1E0F",
-          "pattern": "~/Projects/**/bin/rg",
-          "lastUsedAt": 1737150000000,
-          "lastUsedCommand": "rg -n TODO",
-          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"
-        }
-      ]
-    }
-  }
-}
-```
-
-## 策略选项
-
-### Security（`exec.security`）
-
-- **deny**：阻止所有主机执行请求。
-- **allowlist**：仅允许在允许列表中的命令。
-- **full**：允许所有命令（等同于提权模式）。
-
-### Ask（`exec.ask`）
-
-- **off**：从不提示。
-- **on-miss**：仅在允许列表未匹配时提示。
-- **always**：每次命令都提示。
-
-### Ask fallback（`askFallback`）
-
-如果需要提示但无法访问 UI，fallback 决定：
-
-- **deny**：阻止。
-- **allowlist**：仅在允许列表匹配时允许。
-- **full**：允许。
-
-## 允许列表（按智能体）
-
-允许列表是**按智能体**配置的。如果存在多个智能体，请在 macOS 应用中切换要编辑的智能体。模式匹配**不区分大小写**。
-模式应解析为**二进制路径**（仅包含基本名称的条目会被忽略）。
-旧版 `agents.default` 条目在加载时会迁移到 `agents.main`。
-
-示例：
-
-- `~/Projects/**/bin/bird`
-- `~/.local/bin/*`
-- `/opt/homebrew/bin/rg`
-
-每个允许列表条目会跟踪：
-
-- **id** 用于 UI 标识的稳定 UUID（可选）
-- **last used** 时间戳
-- **last used command**
-- **last resolved path**
-
-## 自动允许 skill CLI
-
-启用 **Auto-allow skill CLIs** 后，已知 Skills 引用的可执行文件在节点（macOS 节点或无头节点主机）上被视为已列入允许列表。这通过 Gateway RPC 的 `skills.bins` 获取 skill 二进制列表。如果你想要严格的手动允许列表，请禁用此选项。
-
-## 安全二进制（仅限标准输入）
-
-`tools.exec.safeBins` 定义了一小组**仅限标准输入**的二进制文件（例如 `jq`），这些文件可以在允许列表模式下运行，**无需**显式的允许列表条目。安全二进制会拒绝位置文件参数和类路径标记，因此它们只能操作传入的流。
-在允许列表模式下，shell 链式命令和重定向不会被自动允许。
-
-当每个顶级段都满足允许列表（包括安全二进制或 skill 自动允许）时，允许 shell 链式命令（`&&`、`||`、`;`）。重定向在允许列表模式下仍不受支持。
-命令替换（`$()` / 反引号）在允许列表解析期间会被拒绝，包括在双引号内；如果你需要字面的 `$()` 文本，请使用单引号。
-
-默认安全二进制：`jq`、`grep`、`cut`、`sort`、`uniq`、`head`、`tail`、`tr`、`wc`。
-
-## Control UI 编辑
-
-使用 **Control UI → Nodes → Exec approvals** 卡片来编辑默认值、按智能体的覆盖设置和允许列表。选择一个作用域（Defaults 或某个智能体），调整策略，添加/删除允许列表模式，然后点击 **Save**。UI 会显示每个模式的 **last used** 元数据，以便你保持列表整洁。
-
-目标选择器可选择 **Gateway**（本地审批）或 **Node**。节点必须通告 `system.execApprovals.get/set`（macOS 应用或无头节点主机）。
-如果节点尚未通告执行审批，请直接编辑其本地的 `~/.symi/exec-approvals.json`。
-
-CLI：`symi approvals` 支持 gateway 或 node 编辑（参见 [Approvals CLI](/cli/approvals)）。
-
-## 审批流程
-
-当需要提示时，gateway 向操作员客户端广播 `exec.approval.requested`。
-Control UI 和 macOS 应用通过 `exec.approval.resolve` 进行处理，然后 gateway 将已批准的请求转发给节点主机。
-
-当需要审批时，exec 工具会立即返回一个审批 id。使用该 id 来关联后续的系统事件（`Exec finished` / `Exec denied`）。如果在超时前没有收到决定，请求将被视为审批超时，并作为拒绝原因显示。
-
-确认对话框包括：
-
-- 命令 + 参数
-- cwd
-- 智能体 id
-- 解析后的可执行文件路径
-- 主机 + 策略元数据
-
-操作：
-
-- **Allow once** → 立即运行
-- **Always allow** → 添加到允许列表 + 运行
-- **Deny** → 阻止
-
-## 审批转发到聊天渠道
-
-你可以将执行审批提示转发到任何聊天渠道（包括插件渠道），并使用 `/approve` 进行批准。这使用正常的出站投递管道。
-
-配置：
-
-```json5
-{
-  approvals: {
-    exec: {
-      enabled: true,
-      mode: "session", // "session" | "targets" | "both"
-      agentFilter: ["main"],
-      targets: [
-        { channel: "slack", to: "U12345678" },
-        { channel: "telegram", to: "123456789" },
-      ],
-    },
-  },
-}
-```
-
-在聊天中回复：
-
-```
-/approve <id> allow-once
-/approve <id> allow-always
-/approve <id> deny
-```
-
-### macOS IPC 流程
-
-```
-Gateway -> Node Service (WS)
-                 |  IPC (UDS + token + HMAC + TTL)
-                 v
-             Mac App (UI + approvals + system.run)
-```
-
-安全注意事项：
-
-- Unix socket 模式 `0600`，token 存储在 `exec-approvals.json` 中。
-- 同 UID 对端检查。
-- 挑战/响应（nonce + HMAC token + 请求哈希）+ 短 TTL。
-
-## 系统事件
-
-执行生命周期以系统消息的形式呈现：
-
-- `Exec running`（仅当命令超过运行通知阈值时）
-- `Exec finished`
-- `Exec denied`
-
-这些消息在节点报告事件后发布到智能体的会话中。
-Gateway 主机执行审批在命令完成时（以及可选地在运行时间超过阈值时）发出相同的生命周期事件。
-经过审批门控的执行会复用审批 id 作为这些消息中的 `runId`，以便于关联。
-
-## 影响
-
-- **full** 权限很大；尽可能优先使用允许列表。
-- **ask** 让你保持知情，同时仍允许快速审批。
-- 按智能体的允许列表可防止一个智能体的审批泄漏到其他智能体。
-- 审批仅适用于来自**授权发送者**的主机执行请求。未授权的发送者无法发出 `/exec`。
-- `/exec security=full` 是为授权操作员提供的会话级便利功能，设计上会跳过审批。
-  要完全阻止主机执行，请将审批 security 设置为 `deny`，或通过工具策略拒绝 `exec` 工具。
-
-相关内容：
-
-- [Exec 工具](/tools/exec)
-- [提权模式](/tools/elevated)
-- [Skills](/tools/skills)