@saluzi/saluzi-edu 0.2.67 → 0.2.68

package/dist/guide/guide-data.json

@@ -80,6 +80,10 @@
           "title": "Remote Control 与 ACP",
           "path": "docs/guide/remote-control-acp"
         },
+        {
+          "title": "Artifacts",
+          "path": "docs/guide/artifacts"
+        },
         {
           "title": "Parade 桌面悬浮提示",
           "path": "docs/guide/parade"
@@ -7258,6 +7262,25 @@
       },
       "content": "\n## 主目录位置\n\nSaluzi 把所有用户数据集中放在主目录下的 `~/.saluzi-edu` 文件夹。路径由 `getSaluziConfigHomeDir()` 统一决定：\n\n- **Linux / macOS**：`~/.saluzi-edu`\n- **Windows**：`%USERPROFILE%\\.saluzi-edu`（即 `C:\\Users\\<你>\\.saluzi-edu`）\n\n可通过环境变量 `SALUZI_CONFIG_DIR` 覆盖到任意位置（支持 `~` 展开），适合多套配置切换或放在加密分区。\n\n> 注意：企业受管配置 `managed-settings.json` **不在此目录**，而是放在系统级路径——macOS 为 `/Library/Application Support/SaluziCode`，Windows 为 `C:\\Program Files\\SaluziCode`，Linux 为 `/etc/saluzi-edu`。普通用户一般不需要动它。\n\n## 子目录与文件清单\n\n启动后 `~/.saluzi-edu` 下会按需出现以下条目。各子目录在首次写入时自动 `mkdir -p`，不需要手动创建。\n\n### 配置与凭证\n\n| 路径 | 作用 | 删除影响 |\n|------|------|---------|\n| `settings.json` | 用户全局设置（env、权限、模型、hooks 等）。详见下文 | 重置为默认配置 |\n| `settings.local.json` | 项目级本地设置（gitignored）。仅在 `<cwd>/.saluzi-edu/` 下生效 | 丢失本地覆盖 |\n| `.credentials.json` | OAuth 登录凭证 | 需重新 `/login` |\n| `.config.json` | 内部运行配置，不要手编 | 自动重建 |\n| `keybindings.json` | 自定义快捷键 | 恢复默认按键 |\n| `SALUZI.md` | 用户级记忆（跨项目的个人偏好） | 丢失用户记忆 |\n| `rules/` | 用户级规则文件 | 丢失规则 |\n\n### 项目数据（按 cwd 隔离）\n\n| 路径 | 作用 |\n|------|------|\n| `projects/<sanitized-cwd>/` | 每个工作目录一个子目录，存放该项目专属的会话与记忆 |\n| `projects/<cwd>/memory/` | 自动记忆：`MEMORY.md` + `logs/YYYY/MM/` 日志 |\n| `projects/<cwd>/*.jsonl` | 该项目的会话转录 |\n\n项目子目录名是 cwd 路径的 sanitized 形式（特殊字符替换），所以同时多个项目互不干扰。\n\n### 扩展与自定义\n\n| 路径 | 作用 |\n|------|------|\n| `skills/` | 用户技能（由 `/skill-learning` 自动生成或手写） |\n| `commands/` | 用户自定义 slash 命令 |\n| `agents/` | 用户自定义 agent（Markdown 文件） |\n| `teams/` | 团队配置 |\n| `templates/` | 任务模板 |\n| `plugins/` | 插件安装目录（由 `/plugin` 管理） |\n| `plugin-options/` | 插件运行时选项 |\n\n### 运行时状态\n\n| 路径 | 作用 |\n|------|------|\n| `sessions/` | 并发会话状态 |\n| `jobs/` | 后台任务状态 |\n| `tasks/` | 任务数据 |\n| `plans/` | plan 文件 |\n| `daemon/` | daemon 进程状态（`<name>.json`） |\n| `shell-snapshots/` | Shell 环境快照（`!` 命令用） |\n| `history.jsonl` | 全局命令历史 |\n| `stats-cache.json` | 使用统计缓存 |\n| `usage-data/` | `/insights` 用量数据 |\n| `pr-subscriptions.json` | PR 订阅列表 |\n| `file-history/` | 文件修改历史 |\n| `session-env/` | 会话环境变量 |\n| `uploads/<sessionId>/` | 入站附件 |\n\n### 缓存与日志\n\n| 路径 | 作用 |\n|------|------|\n| `cache/model-capabilities.json` | 模型能力缓存 |\n| `backups/` | 配置文件备份 |\n| `debug/<sessionId>.txt` | 调试日志 |\n| `traces/` | Perfetto 性能追踪 |\n| `startup-perf/` | 启动性能分析 |\n| `.update.lock` | 自动更新锁文件 |\n\n### IDE 与集成\n\n| 路径 | 作用 |\n|------|------|\n| `ide/` | IDE 集成数据 |\n| `local/` | 本地安装文件 |\n| `magic-docs/prompt.md` | MagicDocs prompt |\n| `skill-learning/` | 技能学习上下文 |\n| `autonomy/` | 自治运行记录（`runs.json`、`flows.json`） |\n\n所有缓存与运行时状态目录都可安全删除——Saluzi 会按需重建。配置类（`settings.json`、`SALUZI.md`、`keybindings.json`）删除会丢失个人定制，需要重新配置。\n\n## settings.json 配置\n\n`~/.saluzi-edu/settings.json` 是用户全局配置文件，JSON 格式，所有字段均可选。下面按主题分组说明。完整 JSON Schema 发布在 `https://json.schemastore.org/saluzi-edu-settings.json`，编辑器开启 JSON Schema 支持后可自动补全。\n\n### 来源与优先级\n\nSaluzi 合并 5 个来源的配置，后者覆盖前者：\n\n| 优先级 | 来源 | 路径 | 可编辑 |\n|--------|------|------|--------|\n| 1（低） | userSettings | `~/.saluzi-edu/settings.json` | 是 |\n| 2 | projectSettings | `<cwd>/.saluzi-edu/settings.json` | 是（共享，入 git） |\n| 3 | localSettings | `<cwd>/.saluzi-edu/settings.local.json` | 是（gitignored） |\n| 4 | flagSettings | `--settings <path>` CLI 参数 | 否 |\n| 5（高） | policySettings | 系统级 managed-settings.json | 否 |\n\n合并规则：标量高优先级直接覆盖；对象深度合并；数组拼接去重。policySettings 内部还按 remote > MDM (HKLM/plist) > managed-settings.json > HKCU 排序。\n\n### 1. 模型与推理\n\n| 字段 | 类型 | 默认 | 说明 |\n|------|------|------|------|\n| `modelType` | enum | `anthropic` | API 提供商：`anthropic`/`openai`/`gemini`/`grok` |\n| `model` | string | - | 覆盖默认模型 ID |\n| `availableModels` | string[] | - | 企业模型白名单（通常 managed） |\n| `modelOverrides` | Record<string,string> | - | 模型 ID 映射（如 Bedrock ARN） |\n| `effortLevel` | enum | `medium` | `low`/`medium`/`high`/`xhigh`/`max` |\n| `alwaysThinkingEnabled` | boolean | true | 是否启用 thinking |\n| `fastMode` | boolean | false | 启用 fast 模式 |\n| `fastModePerSessionOptIn` | boolean | false | fast 不跨会话持久化 |\n| `advisorModel` | string | - | 服务端 advisor 工具模型 |\n| `mom` | object | - | Mixture of Model 配置，见 [MOM 章节](./mom-mixed-models) |\n\n### 2. 环境变量\n\n`env` 是 `Record<string, string>`，写入后会注入到会话进程的环境变量。常用于配置 API Key 和端点：\n\n```json\n{\n  \"env\": {\n    \"ANTHROPIC_API_KEY\": \"sk-ant-...\",\n    \"ANTHROPIC_BASE_URL\": \"https://api.anthropic.com\",\n    \"SALUZI_EFFORT_LEVEL\": \"high\"\n  }\n}\n```\n\n常用键：\n\n| 键 | 作用 |\n|----|------|\n| `ANTHROPIC_API_KEY` | Anthropic API Key（设置后免 `/login`） |\n| `ANTHROPIC_BASE_URL` | Anthropic 端点（自建反代用） |\n| `OPENAI_API_KEY` / `OPENAI_BASE_URL` / `OPENAI_MODEL` | OpenAI 兼容 |\n| `GEMINI_API_KEY` / `GEMINI_BASE_URL` | Gemini |\n| `GROK_API_KEY` / `GROK_BASE_URL` / `GROK_MODEL` | Grok/xAI |\n| `SALUZI_EFFORT_LEVEL` | 推理深度（覆盖 effortLevel） |\n| `SALUZI_MAX_CONTEXT_TOKENS` | 最大上下文 token |\n| `SALUZI_DISABLE_1M_CONTEXT` | 禁用 1M 上下文 |\n| `SALUZI_CLIENT_CERT` / `SALUZI_CLIENT_KEY` | mTLS 证书 |\n\n### 3. 权限\n\n`permissions` 控制工具调用的授权策略：\n\n```json\n{\n  \"permissions\": {\n    \"defaultMode\": \"default\",\n    \"allow\": [\"Bash(npm test:*)\", \"Read(./src/**)\"],\n    \"deny\": [\"Bash(rm -rf:*)\"],\n    \"ask\": [\"Write(**)\"],\n    \"additionalDirectories\": [\"../other-project\"]\n  }\n}\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `defaultMode` | enum | `default`/`acceptEdits`/`bypassPermissions`/`dontAsk`/`plan`/`auto` |\n| `allow` | string[] | 自动放行的工具规则 |\n| `deny` | string[] | 直接拒绝的规则 |\n| `ask` | string[] | 总是弹出确认的规则 |\n| `additionalDirectories` | string[] | 额外允许访问的目录 |\n| `disableBypassPermissionsMode` | `\"disable\"` | 禁用 bypass 模式 |\n\n规则语法如 `Bash(npm test:*)`、`Read(./src/**)`，可用 `*` 通配。\n\n### 4. Hooks\n\n`hooks` 在工具执行前后触发自定义命令。事件类型有 25+ 种，常用的：\n\n| 事件 | 触发时机 |\n|------|---------|\n| `PreToolUse` | 工具调用前 |\n| `PostToolUse` | 工具调用后 |\n| `UserPromptSubmit` | 用户提交输入时 |\n| `SessionStart` / `SessionEnd` | 会话开始/结束 |\n| `Stop` / `StopFailure` | 主循环停止 |\n| `Notification` | 通知发送时 |\n| `PreCompact` / `PostCompact` | 上下文压缩前后 |\n| `PermissionRequest` / `PermissionDenied` | 权限请求/拒绝时 |\n\n每个 hook 是 `{ matcher?: string, hooks: HookCommand[] }`，HookCommand 有四种类型：\n\n```json\n{\n  \"hooks\": {\n    \"PreToolUse\": [\n      {\n        \"matcher\": \"Bash\",\n        \"hooks\": [\n          { \"type\": \"command\", \"command\": \"echo 'running bash'\", \"shell\": \"bash\" },\n          { \"type\": \"prompt\", \"prompt\": \"检查这个命令是否安全\" },\n          { \"type\": \"http\", \"url\": \"https://audit.example.com/hook\", \"headers\": {} },\n          { \"type\": \"agent\", \"prompt\": \"评估风险\", \"model\": \"pro\" }\n        ]\n      }\n    ]\n  }\n}\n```\n\n| 字段 | 适用类型 | 说明 |\n|------|---------|------|\n| `command` / `shell` / `timeout` | command | 执行 shell 命令 |\n| `prompt` / `model` | prompt / agent | 让模型评估 |\n| `url` / `headers` / `allowedEnvVars` | http | HTTP 回调 |\n| `statusMessage` / `once` / `async` / `if` | 全部 | 通用控制 |\n\n`disableAllHooks: true` 可一键禁用所有 hooks 和 statusLine。\n\n### 5. 沙箱\n\n`sandbox` 控制工具执行的隔离边界：\n\n```json\n{\n  \"sandbox\": {\n    \"enabled\": true,\n    \"failIfUnavailable\": false,\n    \"autoAllowBashIfSandboxed\": true,\n    \"network\": {\n      \"allowedDomains\": [\"api.anthropic.com\", \"registry.npmjs.org\"]\n    },\n    \"filesystem\": {\n      \"allowWrite\": [\"./src\", \"./tests\"],\n      \"denyWrite\": [\".env\", \".git\"]\n    }\n  }\n}\n```\n\n| 字段 | 说明 |\n|------|------|\n| `enabled` | 启用沙箱 |\n| `failIfUnavailable` | 沙箱不可用时直接失败（通常 managed） |\n| `autoAllowBashIfSandboxed` | 沙箱内自动放行 Bash |\n| `allowUnsandboxedCommands` | 允许未沙箱化的命令 |\n| `network.allowedDomains` | 允许访问的域名 |\n| `network.allowManagedDomainsOnly` | 仅用 managed 域名白名单 |\n| `filesystem.allowWrite` / `denyWrite` | 读写路径规则 |\n| `excludedCommands` | 排除沙箱的命令 |\n\n### 6. UI 与输出\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `outputStyle` | string | 响应输出样式 |\n| `language` | string | 首选语言（如 `chinese`、`japanese`） |\n| `theme` | string | 主题名 |\n| `prefersReducedMotion` | boolean | 减少动画 |\n| `syntaxHighlightingDisabled` | boolean | 禁用 diff 语法高亮 |\n| `terminalTitleFromRename` | boolean | `/rename` 同步终端标题 |\n| `spinnerTipsEnabled` | boolean | spinner 显示提示 |\n| `spinnerVerbs` | object | 自定义 spinner 动词 |\n| `spinnerTipsOverride` | object | 覆盖 spinner tips |\n| `statusLine` | object | 自定义状态行（`{ type: \"command\", command, padding? }`） |\n\n### 7. MCP 服务器\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `enableAllProjectMcpServers` | boolean | 自动批准项目所有 MCP 服务器 |\n| `enabledMcpjsonServers` | string[] | 已批准的 .mcp.json 服务器 |\n| `disabledMcpjsonServers` | string[] | 已拒绝的 .mcp.json 服务器 |\n| `allowedMcpServers` | array | 企业 MCP 白名单 |\n| `deniedMcpServers` | array | 企业 MCP 黑名单（优先于白名单） |\n\n### 8. 插件\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `enabledPlugins` | Record<string, string[]\\|boolean> | 已启用插件（plugin-id@marketplace-id） |\n| `extraKnownMarketplaces` | Record<string, object> | 额外插件市场源 |\n| `pluginConfigs` | Record<string, {mcpServers?, options?}> | 每插件配置 |\n| `strictPluginOnlyCustomization` | boolean\\|enum[] | 阻止非插件自定义（surfaces: `skills`/`agents`/`hooks`/`mcp`） |\n\n### 9. 记忆与技能\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `autoMemoryEnabled` | boolean | 项目自动记忆开关 |\n| `autoMemoryDirectory` | string | 自动记忆存储目录（projectSettings 中忽略） |\n| `autoDreamEnabled` | boolean | 后台记忆整合 |\n| `memoryV2Enabled` | boolean | Memory V2 总开关 |\n| `memoryV2` | object | V2 子特性（gatedWrites、hybridStorage、smartRetrieval 等） |\n| `skillSearchEnabled` | boolean | 技能搜索预取 |\n| `skillLearningEnabled` | boolean | 自动技能学习 |\n| `skillImprovementEnabled` | boolean | 自动技能改进 |\n\n### 10. 自动更新与启动\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `autoUpdatesChannel` | enum | `latest`/`stable` |\n| `minimumVersion` | string | 最低版本（防降级） |\n| `cleanupPeriodDays` | number | 聊天转录保留天数（默认 30，0=禁用持久化） |\n| `includeGitInstructions` | boolean | 系统提示是否含 git 工作流（默认 true） |\n| `respectGitignore` | boolean | 文件选择器是否尊重 .gitignore（默认 true） |\n| `skipWebFetchPreflight` | boolean | 跳过 WebFetch 黑名单检查 |\n\n### 11. 登录与认证\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `forceLoginMethod` | enum | `claudeai`/`console` 强制登录方式 |\n| `forceLoginOrgUUID` | string | OAuth 组织 UUID |\n| `apiKeyHelper` | string | 输出认证值的脚本路径 |\n| `awsCredentialExport` / `awsAuthRefresh` | string | AWS 凭证脚本 |\n| `gcpAuthRefresh` | string | GCP 认证刷新命令 |\n| `otelHeadersHelper` | string | OpenTelemetry headers 脚本 |\n\n### 12. 提交与归属\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `attribution` | object | 提交/PR 归属文本（`{ commit, pr }`） |\n| `includeCoAuthoredBy` | boolean | 已弃用，改用 attribution |\n\n### 13. API Key 绑定\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `keys` | KeyEntry[] | API key 条目（`/keys` 命令） |\n| `keyBindings` | object | 模型 slot→key 索引（`{ default?, max?, pro?, std?, subagent? }`） |\n| `keyModelNames` | Record<string,string> | slot→模型名映射 |\n\n详见 [API Key 绑定章节](./keys-binding)。\n\n### 14. 企业受管字段\n\n以下字段设计上只从 managed-settings.json 读取，普通 settings.json 中写会被忽略：\n\n- `allowManagedHooksOnly` — 仅运行 managed 的 hooks\n- `allowManagedPermissionRulesOnly` — 仅用 managed 的权限规则\n- `allowManagedMcpServersOnly` — 仅从 managed 读 MCP 白名单\n- `strictPluginOnlyCustomization` — 阻止非插件自定义\n- `strictKnownMarketplaces` / `blockedMarketplaces` — 插件市场白/黑名单\n- `pluginTrustMessage` — 插件信任警告附加消息\n- `sandbox.failIfUnavailable` — 沙箱不可用即失败\n- `sandbox.network.allowManagedDomainsOnly` — 仅用 managed 域名\n- `sandbox.filesystem.allowManagedReadPathsOnly` — 仅用 managed 读路径\n\n### 15. 其他\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `defaultShell` | enum | `bash`/`powershell`，`!` 命令默认 shell |\n| `worktree` | object | git worktree 配置（`symlinkDirectories`, `sparsePaths`） |\n| `plansDirectory` | string | plan 文件自定义目录 |\n| `feedbackSurveyRate` | number(0-1) | 会话反馈调查出现概率 |\n| `channelsEnabled` | boolean | 团队/企业频道通知 opt-in |\n| `showClearContextOnPlanAccept` | boolean | plan 批准对话框显示 clear context |\n| `saluziMdExcludes` | string[] | 排除加载 SALUZI.md 的 glob 模式 |\n| `remote.defaultEnvironmentId` | string | 远程会话默认环境 |\n| `sshConfigs` | array | SSH 远程配置（`{ id, name, sshHost, sshPort?, sshIdentityFile?, startDirectory? }`） |\n\n## 编辑建议\n\n- **优先用 userSettings**：`~/.saluzi-edu/settings.json` 放跨项目偏好（主题、模型、env）\n- **项目共享配置用 projectSettings**：`<cwd>/.saluzi-edu/settings.json`，入 git 团队共享\n- **个人项目覆盖用 localSettings**：`<cwd>/.saluzi-edu/settings.local.json`，gitignored\n- **不要手编 .config.json / .credentials.json**：用 `/login` 等命令让 Saluzi 自己写\n- **删除前备份**：`settings.json`、`SALUZI.md`、`keybindings.json` 删了不可恢复\n\n## 下一步\n\n- [排障](./troubleshooting) — `/doctor` 全面体检配置\n- [上下文管理](./context-tips) — SALUZI.md 项目记忆机制\n- [API Key 绑定](./keys-binding) — `/keys` 多 Key 调度\n"
     },
+    "docs/guide/artifacts": {
+      "frontmatter": {
+        "title": "Artifacts - 可分享的交互式 HTML 页面",
+        "description": "让 agent 把进度面板、报告、数据看板发布为稳定链接的 HTML 页面。Markdown 自动转样式化 HTML，hash 覆盖更新不换链接，接入 RCS 后自动进入团队画廊。",
+        "keywords": [
+          "Artifacts",
+          "artifact",
+          "HTML",
+          "Markdown",
+          "分享链接",
+          "团队画廊",
+          "RCS",
+          "hash 覆盖",
+          "TTL",
+          "交互页面"
+        ]
+      },
+      "content": "\n## Artifacts 是什么\n\nArtifacts 是 agent 替你发布的**可分享 HTML 页面**：你在对话里让 agent 产出报告、看板或交互界面，它写好文件后用 `artifact` 工具上传，立刻得到一个稳定 URL，发给谁都能在浏览器打开。\n\n典型用途：\n\n- **团队交互界面** — PR 审查板、事故时间线、数据看板、发布清单（HTML 原样托管，`<script>` 可运行）\n- **进度与交付物** — 任务进度面板、调研报告、设计文档、数据可视化\n- **团队共享** — 接入 RCS 后，上传的页面自动出现在团队 Web 画廊，全员可见\n\n## 30 秒上手\n\n最短路径 — 直接在对话里说：\n\n```text\n把刚才的分析整理成一个 HTML 报告页，发布成 artifact 给我链接\n```\n\nagent 会自动完成：写文件 → 调用 `artifact` 工具上传 → 返回 `{ id, url, expiresAt }`。打开 `url` 即可查看。\n\n想更系统化地使用（复杂任务全程用一个「活文档」跟踪进度），让 agent 加载内置技能：\n\n```text\n/use-artifacts\n```\n\n它会教会 agent 何时该建 artifact、何时该更新、Markdown 与 HTML 怎么选。\n\n## 两种内容形态\n\n| 形态 | 适合场景 | 说明 |\n|------|---------|------|\n| **Markdown**（`.md`） | 文字为主的报告、设计文档、调研笔记 | 上传前自动转为带样式的 HTML（标题、GFM 表格、代码块高亮、引用、mermaid 图）。你只管写内容，排版交给工具 |\n| **HTML**（`.html`） | 定制布局、内嵌 SVG 图表、交互脚本 | 原样托管（包括 `<script>`），适合 PR 审查板、看板等可交互页面 |\n\n两者都要求**绝对路径**，单文件不超过 **10MB**。\n\n## 更新而不换链接：hash 覆盖\n\n每次上传默认生成新 id（也就是新 URL）。要迭代同一个页面时，让 agent 把第一次返回的 `id` 作为 `hash` 传回：\n\n- URL **保持不变**，内容更新，版本号 +1，TTL 重新计时\n- 你可以把链接发出去后就不管了，agent 每完成一个阶段就原地更新\n\n这是「任务全程活文档」工作流的基础：任务开始先发布骨架，之后里程碑时用 `hash` 刷新，结束时就是最终交付物。\n\n## 会话内管理：/artifacts\n\n```text\n/artifacts\n```\n\n列出当前会话上传过的所有 artifact（最新的在最上面），含文件名、id、URL 和过期时间。键位：\n\n| 按键 | 作用 |\n|------|------|\n| `↑` / `↓` | 选择条目 |\n| `Enter` | 在浏览器打开选中项的 URL |\n| `c` | 复制 URL 到剪贴板 |\n| `Esc` / `q` | 退出 |\n\n## 团队画廊：RCS Web UI\n\n接入 RCS（见「Remote Control 与 ACP」章节）后，artifact 会上传到自托管服务器并归属当前会话，自动进入团队画廊：\n\n- **画廊页** `http://<rcs-host>:3000/code/artifacts` — 浏览所有你有权限查看的 artifact，展示大小、过期倒计时、所属会话\n- **从模板新建** — 画廊内可基于 5 个内置模板直接创建：空白页、PR 审查板、事故时间线、数据看板、发布清单（纯前端运行，无需构建）\n- **会话详情页内嵌画廊** — 只显示该会话上传的 artifact，方便按会话回溯\n- **复制 / 删除** — 一键复制分享链接；创建者、会话/团队管理者或系统 admin 可删除\n- **可见性跟随会话** — 会话对谁可见，其 artifact 就对谁可见；画廊里新建的无会话 artifact 仅创建者与所属团队可见\n\n## 上传到哪：目标解析与配置\n\n`artifact` 工具按以下优先级选择上传目标（命中即停）：\n\n| 优先级 | 条件 | 上传地址 |\n|-------|------|---------|\n| 1 | 设置了 `SALUZI_ARTIFACTS_URL` | `{该地址}/v1/artifacts`（设 `SALUZI_ARTIFACTS_KIND=cloud` 则为 `{该地址}/upload`） |\n| 2 | 已连接自托管 RCS bridge | `{SALUZI_BRIDGE_BASE_URL}/v1/artifacts`，归属当前会话，进入团队画廊 |\n| 3 | 都没有 | 默认云端 artifacts 服务（无需任何配置即可用，但不进 RCS 画廊） |\n\n相关环境变量：\n\n| 环境变量 | 说明 |\n|---------|------|\n| `SALUZI_ARTIFACTS_URL` | 指定自托管上传地址（RCS 或云端兼容服务） |\n| `SALUZI_ARTIFACTS_TOKEN` | 上传认证 token（默认复用 bridge token） |\n| `SALUZI_ARTIFACTS_KIND` | 设为 `cloud` 表示目标是云端兼容服务（`/upload` 路径） |\n\nRCS 服务端还有一个开关：`RCS_ARTIFACTS_PUBLIC_ACCESS=false` 可把内容读取从「URL 即密钥」改为需要登录凭证（默认关闭公开访问开关，即默认任何人持链接可读）。\n\n## 限制与生命周期\n\n| 项目 | 值 |\n|------|-----|\n| 单文件上限 | 10MB |\n| 支持扩展名 | `.html` / `.htm` / `.md` / `.markdown` |\n| 保存时长（TTL） | 7 天（默认）或 30 天，上传时二选一 |\n| 过期行为 | 到期即删，链接失效（`hash` 重新上传可复活同一 id） |\n| 覆盖规则 | `hash` 仅接受字母/数字/`-`/`_`，最长 128 字符 |\n\n## 安全须知\n\n- **URL 即密钥**：id 是不可猜测的随机串，拿到链接的人即可查看 — 不要在 artifact 内容里放敏感信息（密钥、内网地址等）\n- 对外分享前确认内容可以公开；内网团队内容建议部署在受保护的 RCS 上并考虑设置 `RCS_ARTIFACTS_PUBLIC_ACCESS=false`\n- HTML 页面会原样执行脚本，仅上传可信内容\n\n## 故障排查\n\n| 问题 | 排查 |\n|------|------|\n| 上传报 `unauthorized` | 检查 `SALUZI_ARTIFACTS_TOKEN`；未设置时应复用 bridge token — 确认 `SALUZI_BRIDGE_OAUTH_TOKEN` 与 RCS 的 `RCS_API_KEYS` 匹配 |\n| 上传报 `payload_too_large` | 文件超过 10MB，精简内容或拆分页面 |\n| 报不支持扩展名 | 只接受 `.html` / `.htm` / `.md` / `.markdown`；把内容另存为这两种格式之一 |\n| 链接打不开（404） | artifact 可能已过期（默认 7 天）；让 agent 用原 `hash` 重新上传即可恢复同一 URL |\n| 团队画廊看不到 artifact | 确认 CLI 已连接 RCS bridge（`/rc` 状态正常）且未设置 `SALUZI_ARTIFACTS_URL` 指向别处；可见性跟随会话，确认你对会话有权限 |\n| 想让 artifact 不进云端 | 设置 `SALUZI_ARTIFACTS_URL` 指向自己的 RCS，或确保 bridge 已连接（优先级 2 自动生效） |\n"
+    },
     "docs/guide/weixin-login": {
       "frontmatter": {
         "title": "微信控制 - 通过微信远程操控 Saluzi",
@@ -7368,7 +7391,7 @@
           "可见域"
         ]
       },
-      "content": "\n## Remote Control Server (RCS)\n\nRCS 是 Saluzi 的自托管远程控制服务器，提供 Web UI 和会话管理。启动后，团队成员通过浏览器访问 Web UI，登录后即可创建会话、查看 worker 状态、与 agent 交互。\n\n## 启动 RCS\n\n```bash\n# 设置 API Key（管理员密码，也是 worker 连接 token）\nexport RCS_API_KEYS=sk-your-key\n\n# 启动（在 Saluzi CLI 中运行）\n> /rcs\n```\n\n也可通过 CLI 子命令直接启动：\n\n```bash\nslz rcs\n```\n\n默认端口 3000，Web UI 在 `http://localhost:3000/code/`。\n\n## RCS Web UI 使用\n\nWeb UI 是团队成员日常使用的控制面板：登录后可创建会话、查看 worker、审批权限、管理团队与环境。下面按首次部署到日常使用的顺序介绍。\n\n### 管理员初始化（首次访问）\n\n第一次打开 Web UI 时，系统没有任何用户。第一个登录的账号会成为系统管理员（role=admin），流程如下：\n\n1. 浏览器打开 `http://localhost:3000/code/`，自动跳转到 Setup 页面\n2. 填写表单：\n   - **API Key**：必须与 RCS 启动时设置的 `RCS_API_KEYS` 中的某个 key 完全一致\n   - **用户名**：登录用，后续不可改\n   - **密码**：至少 8 位\n   - **确认密码**\n3. 提交后第一个用户即成为 admin，进入管理面板\n\n后续访问的用户分两种：\n\n- **自注册**：如果 `RCS_ALLOW_REGISTRATION` 未设为 `false`（默认开放），新访问者可在登录页注册账户（用户名 + 密码）。密码以 argon2id 加密存储，登录有速率限制（5 次失败后锁定 5 分钟）。\n- **邀请制**：将 `RCS_ALLOW_REGISTRATION=false` 后，只有管理员预先创建的账户或通过团队邀请链接加入的用户能登录。\n\n管理员 API Key 拥有系统级权限，可直接访问所有 API（不通过 Web UI 登录流程）。\n\n登录后浏览器会保存 session cookie（`rcs_access`），后续请求自动认证。\n\n### 团队与角色\n\nRCS 用「团队」组织成员、环境和会话。每个登录用户都有一个「个人空间」（无需创建），可被加入一个或多个团队。\n\n**系统级角色**（`users.role`）：\n\n| 角色 | 能力 |\n|------|------|\n| `admin` | 看到所有会话（含无主孤儿）、管理所有团队、转移任意环境；通常由 Setup 流程产生 |\n| 普通用户 | 仅看到自己拥有的、所属团队可见的、显式共享给自己的会话 |\n| `guest` | 不能创建团队；通常对应被降级的账户 |\n\n**团队级角色**（`team_members.role`）：\n\n| 角色 | 团队内能力 |\n|------|-----------|\n| `owner` | 修改团队信息、删除团队、加/减成员、改成员角色、创建/撤销邀请、转移或解绑环境 |\n| `admin` | 加成员、创建/撤销邀请，但不能改 owner/admin 的角色，也不能删团队 |\n| `member` | 只能自退团队，看不到团队级管理按钮 |\n\n团队至少要保留一个 owner — 系统禁止降级或移除最后一个 owner。系统 admin 在任何团队中都视为 owner。\n\n**邀请加入**：团队 owner/admin 可在「团队详情 → 邀请」页面创建邀请链接，链接形如 `/join/<inv_xxx>`，可设置：\n\n- 角色：新成员加入后的角色（仅 `admin` 或 `member`，不能邀请为 owner）\n- 过期时间（默认 24 小时）\n- 最大使用次数（默认 1）\n\n也可以「添加已有用户」：通过用户名或用户 ID 搜索已注册账户，直接加入团队。\n\n### 环境管理\n\n「环境」（environment）是 worker 向 RCS 注册后产生的实体，代表一台正在提供 agent 服务的工作机。每个环境有：\n\n- 拥有者（owner_user_id，可能为空 → 需要认领）\n- 关联团队（可选，关联后团队内成员可见该环境及其会话）\n- worker 类型（slz CLI / ACP agent）、容量、心跳\n\n**环境的归属**：\n\n- 启动 worker 时通过 `--user-id` / `--team-id` 指定 → 直接归属到该用户或团队\n- 未指定且使用共享 API Key → 生成 `claim_token`，进入待认领状态（见下文 claim 机制）\n\n**环境与团队的关联**：\n\n- 在「团队详情 → 环境」页面可把个人环境链接到团队，或把团队环境解绑回个人\n- 环境可在团队之间转移（需要源团队和目标团队的 owner/admin 权限）\n- 转移环境时，该环境下的所有会话归属随之转移到目标团队\n\n### Claim 机制（环境认领）\n\n当 worker 使用共享 API Key 启动、且未指定 `--user-id` / `--team-id` 时，RCS 不会把环境直接归属给任何人，而是生成一个 `claim_token`（形如 `clm_xxxxxxxx`）并打印认领 URL：\n\n```\n/code/claim/clm_xxxxxxxx\n```\n\n**认领流程**：\n\n1. worker 启动后在终端看到认领 URL\n2. 把这个 URL 发给任意已登录用户\n3. 该用户在浏览器打开 URL → 自动调用 `/environments/claim` 接口\n4. 该环境的 `owner_user_id` 写入此用户，`claim_token` 清空\n5. 该环境下已经创建的会话也会一并 backfill 到该用户名下（否则会成为无主孤儿会话）\n\n`claim_token` 有过期时间（`claim_expires_at`），过期后无法认领。已被认领的环境再次访问会返回 409。\n\n这个机制让团队成员用共享 API Key 启动 worker 后，再由具体的人认领，避免环境长期处于无主状态。\n\n### 会话可见域\n\n每个会话有 `visibility` 字段，控制谁能看到它：\n\n| 可见域 | 谁能看到 |\n|--------|---------|\n| `private` | 仅会话的 user owner |\n| `team` | 会话所属团队的所有成员 |\n| `public` | 所有登录用户 |\n\n实际的可见规则综合考虑了 ownership、visibility 和显式共享：\n\n1. 系统 admin 能看到所有会话（含无主孤儿会话）\n2. 用户作为 user owner 拥有的会话\n3. 用户所属团队作为 team owner 拥有、且 visibility 为 `team` 或 `public` 的会话\n4. 通过 `session_shares` 显式共享给该用户的会话（未过期）\n5. 通过 `session_shares` 显式共享给该用户所属团队的会话（未过期）\n6. visibility=`public` 的会话\n7. 无主孤儿会话：仅 admin 可见\n\n**会话转移**：会话 owner（或团队 admin）可把会话从个人空间转到团队（visibility 自动变 `team`），或从团队转回个人（visibility 自动变 `private`）。转移时需要目标是该团队的 owner/admin。\n\n**会话分享**：会话 owner 可生成分享链接，授予指定用户或团队「只读」或「读写」权限，可设置过期时间。被分享者会在自己的会话列表里看到该会话。\n\n### 权限审批\n\nRCS Web UI 在 agent 请求工具调用时弹出审批面板。权限模式（permissionMode）有 6 种，决定 agent 是否需要等待人工确认：\n\n| 模式 | 行为 |\n|------|------|\n| `default` | 每次工具调用都请求确认 |\n| `auto` | agent 自动判断是否需要确认 |\n| `acceptEdits` | 自动接受文件编辑，其他工具仍需确认 |\n| `plan` | 规划模式，仅制定计划不执行 |\n| `dontAsk` | 不询问，直接执行 |\n| `bypassPermissions` | 绕过所有权限检查（仅 sandbox 环境可用，非 root） |\n\n权限模式可在创建会话时指定，也可在会话进行中切换。fallback 顺序：客户端传值 > acp-link 启动时的 `ACP_PERMISSION_MODE` 环境变量。\n\n**三种审批面板**：\n\n- **工具调用审批**：显示工具名、参数和描述，提供 Approve / Reject 按钮\n- **多问题面板**（AskUserQuestion）：agent 一次提多个问题，用户在标签页中切换回答，每题可选预设选项或填写「Other」自定义文本\n- **计划审批**：显示 plan 内容，提供「Yes, auto-accept edits」「Yes, manually approve edits」「No, keep planning」三个选项，选 No 时可附反馈让 agent 重新规划\n\n### Worker 状态\n\nWeb UI 显示所有已连接的 worker（包括 slz CLI worker 和 acp-link agent）：\n\n- **在线状态**：worker 当前是否可接受会话\n- **最大并发**：worker 配置的 `--capacity`\n- **最后活动时间**：最近一次心跳\n\n## RCS 服务器配置\n\n| 环境变量 | 默认 | 说明 |\n|---------|------|------|\n| `RCS_PORT` | 3000 | HTTP 端口 |\n| `RCS_HOST` | 0.0.0.0 | 监听地址 |\n| `RCS_API_KEYS` | — | 逗号分隔的 API Key（管理员权限，也是 worker 连接 token） |\n| `RCS_ALLOW_REGISTRATION` | true | 是否允许开放注册（设为 false 改为邀请制） |\n| `RCS_BASE_URL` | — | 外部访问 URL（反代时设置） |\n| `RCS_DB_PATH` | — | SQLite 数据库路径（默认内存，生产环境建议持久化） |\n| `RCS_WEB_CORS_ORIGINS` | — | Web UI CORS 允许的源（逗号分隔） |\n| `RCS_JWT_EXPIRES_IN` | 3600 | JWT 有效期（秒） |\n| `RCS_DISCONNECT_TIMEOUT` | 300 | 断开连接超时（秒） |\n| `RCS_WS_CLIENT_INACTIVITY_TIMEOUT` | 300 | WebSocket 客户端无活动超时（秒） |\n\n## Worker 接入\n\nWorker 是连接到 RCS 的 Saluzi CLI 实例，执行来自 Web UI 或其他客户端的会话。\n\n### 前置：设置环境变量\n\n**所有 worker 启动方式都需要先设置以下两个环境变量**：\n\n```bash\nexport SALUZI_BRIDGE_BASE_URL=http://rcs-host:3000\nexport SALUZI_BRIDGE_OAUTH_TOKEN=sk-your-key\n```\n\n- `SALUZI_BRIDGE_BASE_URL`：RCS 服务器地址\n- `SALUZI_BRIDGE_OAUTH_TOKEN`：必须与 RCS 启动时设置的 `RCS_API_KEYS` 中的某个 key 一致\n\n两个变量必须**同时设置**才生效。只设置一个会进入\"部分配置\"状态，启动时会提示补全。\n\n可选环境变量（用于归属和团队关联）：\n\n| 环境变量 | 说明 |\n|---------|------|\n| `SALUZI_BRIDGE_USERNAME` | 归属用户名（发送为 `X-Username` 头，RCS 自动认领 env 到该用户） |\n| `SALUZI_BRIDGE_USER_ID` | 归属用户 ID（绕过自动认领，直接绑定到该用户） |\n| `SALUZI_BRIDGE_TEAM_ID` | 关联团队 ID（env 注册到指定团队） |\n| `SALUZI_ENVIRONMENT_KIND` | 设为 `bridge` 标记会话来源为 remote-control |\n| `SALUZI_USE_CCR_V2` | 启用 CCR v2 传输协议 |\n| `SALUZI_BRIDGE_ALLOW_INSECURE_HTTP` | 设为 `1` 允许非 localhost 的 HTTP 连接（自托管内网场景，见下文） |\n| `SALUZI_BRIDGE_AUTO_CONNECT` | 设为 `1` 启用启动时自动连接 RCS（默认关闭；未设置时需在 CLI 内手动运行 `/rc` 或使用 `slz rc` 启动） |\n\n**关于 HTTP 连接**：默认情况下，`SALUZI_BRIDGE_BASE_URL` 如果是 `http://` 且不是 `localhost`/`127.0.0.1`，worker 会拒绝启动——这是为了防止 credentials 明文传输。如果远程 RCS 部署在可信内网（例如 TLS 由上游反代终止、或网络已加密），可设置 `SALUZI_BRIDGE_ALLOW_INSECURE_HTTP=1` 放开此限制。生产环境建议优先用 HTTPS 或 SSH 隧道转发到 localhost。\n\n如果不设置 `SALUZI_BRIDGE_USERNAME`/`SALUZI_BRIDGE_USER_ID`/`SALUZI_BRIDGE_TEAM_ID`，且 token 是共享的管理员 API Key，RCS 会生成 `claim_token` 并打印认领 URL，worker 终端会显示该 URL 供用户认领（详见上文「Claim 机制」）。\n\n### 启动方式\n\n设置好环境变量后，推荐直接运行：\n\n```bash\nslz rc\n```\n\n`slz rc` 是最简的启动方式，默认配置即可作为 worker 连接到 RCS。它是 `slz remote-control` 的简写，也接受 `slz remote`、`slz sync`、`slz bridge` 作为别名。\n\n其他可选方式：\n\n```bash\n# 交互式会话 + worker（既可本地用，也接受远程请求）\nslz --remote-control\n\n# 普通会话自动连接（需额外设置 SALUZI_BRIDGE_AUTO_CONNECT=1，否则普通会话不自动连接）\nSALUZI_BRIDGE_AUTO_CONNECT=1 slz\n```\n\n### 高级参数\n\n需要调整 worker 行为时，`slz rc` 支持以下参数：\n\n| 参数 | 说明 | 示例 |\n|------|------|------|\n| `--spawn <mode>` | Spawn 模式：`same-dir`、`worktree`、`session` | `--spawn=worktree` |\n| `--capacity <N>` | 最大并发会话数（仅 worktree/session 模式） | `--capacity=5` |\n| `--create-session-in-dir` | 启动时在当前目录预创建会话（默认开启） | `--no-create-session-in-dir` 禁用 |\n| `--session-id <id>` | 恢复指定会话 | `--session-id=abc123` |\n| `--continue` | 恢复最近会话 | — |\n| `--name <name>` | 会话名称（也用于 RCS 显示） | `--name=\"我的会话\"` |\n| `--username <name>` | 归属用户名（对应 `SALUZI_BRIDGE_USERNAME`） | `--username=alice` |\n| `--user-id <id>` | 归属用户 ID（对应 `SALUZI_BRIDGE_USER_ID`） | `--user-id=u-123` |\n| `--team-id <id>` | 关联团队 ID（对应 `SALUZI_BRIDGE_TEAM_ID`） | `--team-id=team-abc` |\n\n### Spawn 模式\n\n| 模式 | 说明 | 适用场景 |\n|------|------|---------|\n| `same-dir`（默认） | 所有会话在同一工作目录创建 | 单项目快速响应 |\n| `worktree` | 每个会话在独立 git worktree 中创建 | 多项目隔离，避免文件冲突 |\n| `session` | 单会话模式（容量固定为 1） | 简单场景，不需要并发 |\n\n## 会话接入（Attach）\n\n默认情况下，`/remote-control` 会为当前终端**新建**一个远程会话。Attach 模式改变这一行为：不新建会话，而是把一个**已经存在**的 RCS 会话接入当前终端，在本地继续这段对话，Web UI 上同步可见。\n\n适合场景：会话是在 Web UI 上创建的、或由其他终端发起，想换到自己的终端里继续；团队协作中接手队友的会话；或者把多台机器上的工作收拢到一个终端。\n\n### 三种接入方式\n\n| 方式 | 命令 | 行为 |\n|------|------|------|\n| 指定会话 | `/rc --attach <会话ID>` | 直接接入指定会话 |\n| 交互式选择 | `/rc --attach` | 打开会话选择器：模糊搜索列表（标题 — 状态 (会话ID)），回车接入，Esc 取消 |\n| 等待接入 | `/rc --wait`（或 `/rc --attach --wait`） | 注册后待命，等待 Web UI 侧把会话接到这台终端 |\n\n选择器里只会列出**你有权限管理**的会话；已结束、正被占用的会话和 ACP agent 的会话不会出现。\n\n**等待接入**时，终端会显示提示并持续待命。此时在 RCS Web UI 中把会话绑定到这个 worker（例如新建会话时在环境中选择该 worker），接入立即完成；若该环境还没有归属，终端会同时给出认领 URL，先认领才能接入。\n\n### 接入后发生什么\n\n- 该会话的既有对话历史会合并进本地终端（本地已有内容时保留在后面，并有提示行说明合并了多少条）\n- 之后终端与 Web UI 实时共享同一个会话：任意一端发送消息、发起审批，另一端都同步可见\n- 历史拉取失败时接入会中止并报错——不会出现「半接入」状态\n\n### 启动时自动接入（环境变量）\n\n除在会话内执行 `/rc` 命令外，也可以在启动 CLI 时通过环境变量直接进入接入模式：\n\n| 环境变量 | 说明 |\n|---------|------|\n| `SALUZI_BRIDGE_SESSION_ID` | 启动时直接接入指定会话（等效 `/rc --attach <会话ID>`） |\n| `SALUZI_BRIDGE_SESSION_MODE` | 设为 `attach`：启动后进入等待接入状态 |\n| `SALUZI_BRIDGE_ATTACH_TIMEOUT_MS` | 等待接入的超时时间（毫秒，默认 24 小时） |\n\n```bash\n# 启动即接入指定会话\nexport SALUZI_BRIDGE_SESSION_ID=sess-abc123\nslz\n\n# 或启动后等待 Web UI 分配会话\nexport SALUZI_BRIDGE_SESSION_MODE=attach\nslz\n```\n\n### 已连接时切换绑定\n\n已处于远程控制连接状态时，再次执行 `/rc --attach …`、`/rc --wait`（或带 `--team-id` 等归属参数）会弹出确认框：确认后断开当前远程会话，按新的目标重新绑定；取消则保持现状。\n\n## Worker 与 RCS 的关系\n\n```\n┌─────────────────┐\n│   RCS Server    │  ← 运行 slz rcs\n│  (Web UI + API) │\n└────────┬────────┘\n         │ Bridge 协议\n         │\n    ┌────┴────┐\n    │         │\n┌───▼──┐  ┌──▼───┐\n│Worker│  │Worker│  ← slz rc / slz --remote-control / slz\n│  1   │  │  2   │\n└──────┘  └──────┘\n```\n\n- **RCS**：中央服务器，管理会话、用户、权限\n- **Worker**：通过 bridge 协议连接，从 RCS 获取任务，汇报状态\n- **Web UI**：通过浏览器访问 RCS，创建/查看会话\n\n## ACP 协议\n\nACP（Agent Control Protocol）让**外部 agent**（非 slz CLI，如 Claude Code、其他 ACP 兼容 agent）接入 RCS 的会话系统。slz CLI 自身使用 bridge 协议，不走 ACP。\n\n`acp-link` 是 ACP 桥接工具，随 `@saluzi/saluzi-edu` 一起安装，无需单独安装。\n\n### 连接 slz 到 RCS\n\n如果要让 slz CLI 作为 ACP agent 接入 RCS（而非 bridge worker），使用 `acp-link` 桥接：\n\n#### 1. 设置环境变量\n\n```bash\nexport ACP_RCS_URL=http://rcs-host:3000\nexport ACP_RCS_TOKEN=sk-your-key\n```\n\n- `ACP_RCS_URL`：RCS 服务器地址\n- `ACP_RCS_TOKEN`：必须与 RCS 的 `RCS_API_KEYS` 中的某个 key 一致\n\n可选环境变量：\n\n| 环境变量 | 说明 |\n|---------|------|\n| `ACP_RCS_GROUP` | Channel group ID（字母、数字、下划线、连字符） |\n| `ACP_RCS_USERNAME` | 归属用户名（自动认领 env 到该用户） |\n| `ACP_RCS_USER_ID` | 归属用户 ID（绕过自动认领） |\n| `ACP_RCS_TEAM_ID` | 关联团队 ID |\n| `ACP_AUTH_TOKEN` | 本地 WS 认证 token（不设则自动生成） |\n| `ACP_PERMISSION_MODE` | 默认权限模式 |\n\n#### 2. 启动 acp-link\n\n```bash\nacp-link slz -- --acp\n```\n\n`acp-link` 会启动 slz 作为子进程，通过 ACP 协议代理它与 RCS 之间的通信。slz 会出现在 RCS Web UI 的 agent 列表中，可接受会话请求。\n\n`--` 之后是传递给 slz 的参数（`--acp` 让 slz 进入 ACP 兼容模式）。\n\n### 连接 Claude Code 到 RCS\n\n`acp-link` 支持任何遵循 ACP 协议的 agent。Claude Code 通过专用的 ACP 适配包 `@agentclientprotocol/claude-agent-acp` 接入，接入命令是 `acp-link claude-agent-acp`（**不是** `acp-link claude`，因为 Claude Code 本身不直接说 ACP 协议，需要先装适配包）。\n\n#### 1. 安装 claude-agent-acp\n\nClaude Code 的 ACP 适配包需要单独安装：\n\n```bash\nnpm install -g @agentclientprotocol/claude-agent-acp\n```\n\n安装后会注册 `claude-agent-acp` 命令。\n\n#### 2. 设置环境变量\n\n```bash\nexport ACP_RCS_URL=http://rcs-host:3000\nexport ACP_RCS_TOKEN=sk-your-key\n```\n\n#### 3. 启动 acp-link 桥接\n\n```bash\nacp-link claude-agent-acp\n```\n\n`acp-link` 的第一个参数是 agent 的可执行命令名（这里是 `claude-agent-acp`）。`claude-agent-acp` 本身不需要额外参数，因此不需要 `--`。\n\n连接成功后，Claude Code 会作为 ACP agent 出现在 RCS Web UI 中，与 slz agent 并列，团队成员可在 Web UI 中选择它创建会话。\n\n其他 ACP 兼容 agent 的接入方式类似：安装对应的 ACP 适配包，然后用 `acp-link <命令名>` 启动。可在 npm 官网搜索 `@agentclientprotocol/*` 查找已适配的 agent。\n\n## 团队协作场景\n\n### 共享会话\n\n在 RCS Web UI 中创建会话，分享链接给队友（需登录才能查看），他们可查看或加入对话。也可通过 `session_shares` 显式授予指定用户或团队「只读」/「读写」权限，并设置过期时间。\n\n### 多 Worker 协作\n\n团队多个成员各自启动 worker，连接到同一 RCS：\n\n```bash\n# 成员 A：默认配置\nslz rc\n\n# 成员 B：worktree 隔离，5 并发\nslz rc --spawn=worktree --capacity=5\n```\n\nWeb UI 显示所有 worker 状态，会话与权限集中管理。\n\n### 外部 Agent 接入\n\n用 ACP 让非 slz 的 agent 接入 RCS。Claude Code 通过 `claude-agent-acp` 适配包接入：\n\n```bash\n# 先装适配包（仅一次）\nnpm install -g @agentclientprotocol/claude-agent-acp\n\n# 设置 RCS 连接\nexport ACP_RCS_URL=http://rcs-host:3000\nexport ACP_RCS_TOKEN=sk-your-key\n\n# 启动桥接\nacp-link claude-agent-acp\n```\n\n接入后所有 agent 在 Web UI 中统一管理，团队成员可选择任意 agent 创建会话。\n\n## 安全建议\n\n- RCS 默认监听 0.0.0.0，生产环境建议用反代 + HTTPS\n- 用强 API Key，定期轮换\n- 生产环境关闭 `RCS_ALLOW_REGISTRATION` 改为邀请制\n- 使用 `RCS_WEB_CORS_ORIGINS` 限制 Web UI 访问来源\n- 设置 `RCS_DB_PATH` 持久化 SQLite 数据库\n- 限制 worker 的权限（`/permissions` 配置）\n- `bypassPermissions` 模式仅在 sandbox 环境中启用，避免在主机直接放行所有工具调用\n\n## 故障排查\n\n| 问题 | 排查 |\n|------|------|\n| Worker 无法连接 | 检查 `SALUZI_BRIDGE_BASE_URL` 和 `SALUZI_BRIDGE_OAUTH_TOKEN` 是否同时设置；确认 token 与 RCS 的 `RCS_API_KEYS` 匹配 |\n| `Only HTTPS or localhost HTTP is allowed` | 远程 RCS 用 HTTP 被拒。优先用 HTTPS；或 SSH 隧道转发到 localhost；可信内网可设 `SALUZI_BRIDGE_ALLOW_INSECURE_HTTP=1` |\n| Web UI 登录失败 | 检查用户名密码；5 次失败后锁定 5 分钟 |\n| Web UI 401 | 确认使用 `RCS_API_KEYS` 中的 key 或有效的 session token |\n| 看不到某个会话 | 检查会话 visibility（private/team/public）；确认是否在所属团队的成员列表里；admin 可看所有 |\n| `/rc --attach` 列表为空 | 只列出你有权限管理、且未结束/未被占用的会话；确认目标会话的可见域与你的归属，或让会话 owner 共享 |\n| 接入报「环境无主」 | 该环境还没被认领，先在终端提示的 `/code/claim/clm_xxx` URL 完成认领，再重新接入 |\n| 等待接入一直没有会话 | 在 Web UI 把会话绑定到该 worker；超过超时（默认 24 小时）会放弃，可用 `SALUZI_BRIDGE_ATTACH_TIMEOUT_MS` 调整 |\n| 接入后历史没出现 | 接入会拉取会话历史，失败即中止；确认网络可达 RCS 后重试 `/rc --attach` |\n| 环境显示「待认领」 | worker 没指定 `--user-id`/`--team-id`，找到终端里的 `/code/claim/clm_xxx` URL，已登录用户打开即可认领 |\n| acp-link 无法连接 RCS | 检查 `ACP_RCS_URL` 和 `ACP_RCS_TOKEN` 是否设置 |\n| Agent 不出现在 Web UI | 确认 acp-link 已启动且 `ACP_RCS_TOKEN` 与 `RCS_API_KEYS` 匹配 |\n| 邀请链接失效 | 邀请 token 可能过期或达到 max_uses 上限；让团队 owner/admin 重新创建 |\n| 会话超时 | 调整 `RCS_DISCONNECT_TIMEOUT` 和 `RCS_WS_CLIENT_INACTIVITY_TIMEOUT` |\n"
+      "content": "\n## Remote Control Server (RCS)\n\nRCS 是 Saluzi 的自托管远程控制服务器，提供 Web UI 和会话管理。启动后，团队成员通过浏览器访问 Web UI，登录后即可创建会话、查看 worker 状态、与 agent 交互。\n\n## 启动 RCS\n\n```bash\n# 设置 API Key（管理员密码，也是 worker 连接 token）\nexport RCS_API_KEYS=sk-your-key\n\n# 启动（在 Saluzi CLI 中运行）\n> /rcs\n```\n\n也可通过 CLI 子命令直接启动：\n\n```bash\nslz rcs\n```\n\n默认端口 3000，Web UI 在 `http://localhost:3000/code/`。\n\n### Docker 部署（推荐用于常驻服务）\n\n不想在终端里常驻跑 `/rcs`，可以用 Docker 把 RCS 部署为随开机自启的常驻服务：\n\n```bash\n# 构建镜像（项目根目录执行）\ndocker build -t rcs:latest -f packages/remote-control-server/Dockerfile .\n\n# 启动容器\ndocker run -d \\\n  --name rcs \\\n  -p 3000:3000 \\\n  -e RCS_API_KEYS=sk-your-key \\\n  -e RCS_BASE_URL=https://rcs.example.com \\\n  -v rcs-data:/app/data \\\n  --restart unless-stopped \\\n  rcs:latest\n```\n\n- `-v rcs-data:/app/data`：数据持久化卷（SQLite 数据库），重启容器不丢数据\n- `RCS_BASE_URL`：外部访问地址，反代 + HTTPS 部署时必须设置，且与客户端实际访问地址一致\n- Docker Compose 写法、健康检查（`curl /health`）与反代注意事项见仓库内 `docs/features/remote-control-self-hosting.md`\n\n## RCS Web UI 使用\n\nWeb UI 是团队成员日常使用的控制面板：登录后可创建会话、查看 worker、审批权限、管理团队与环境。下面按首次部署到日常使用的顺序介绍。\n\n### 管理员初始化（首次访问）\n\n第一次打开 Web UI 时，系统没有任何用户。第一个登录的账号会成为系统管理员（role=admin），流程如下：\n\n1. 浏览器打开 `http://localhost:3000/code/`，自动跳转到 Setup 页面\n2. 填写表单：\n   - **API Key**：必须与 RCS 启动时设置的 `RCS_API_KEYS` 中的某个 key 完全一致\n   - **用户名**：登录用，后续不可改\n   - **密码**：至少 8 位\n   - **确认密码**\n3. 提交后第一个用户即成为 admin，进入管理面板\n\n后续访问的用户分两种：\n\n- **自注册**：如果 `RCS_ALLOW_REGISTRATION` 未设为 `false`（默认开放），新访问者可在登录页注册账户（用户名 + 密码）。密码以 argon2id 加密存储，登录有速率限制（5 次失败后锁定 5 分钟）。\n- **邀请制**：将 `RCS_ALLOW_REGISTRATION=false` 后，只有管理员预先创建的账户或通过团队邀请链接加入的用户能登录。\n\n管理员 API Key 拥有系统级权限，可直接访问所有 API（不通过 Web UI 登录流程）。\n\n登录后浏览器会保存 session cookie（`rcs_access`），后续请求自动认证。\n\n### 团队与角色\n\nRCS 用「团队」组织成员、环境和会话。每个登录用户都有一个「个人空间」（无需创建），可被加入一个或多个团队。\n\n**系统级角色**（`users.role`）：\n\n| 角色 | 能力 |\n|------|------|\n| `admin` | 看到所有会话（含无主孤儿）、管理所有团队、转移任意环境；通常由 Setup 流程产生 |\n| 普通用户 | 仅看到自己拥有的、所属团队可见的、显式共享给自己的会话 |\n| `guest` | 不能创建团队；通常对应被降级的账户 |\n\n**团队级角色**（`team_members.role`）：\n\n| 角色 | 团队内能力 |\n|------|-----------|\n| `owner` | 修改团队信息、删除团队、加/减成员、改成员角色、创建/撤销邀请、转移或解绑环境 |\n| `admin` | 加成员、创建/撤销邀请，但不能改 owner/admin 的角色，也不能删团队 |\n| `member` | 只能自退团队，看不到团队级管理按钮 |\n\n团队至少要保留一个 owner — 系统禁止降级或移除最后一个 owner。系统 admin 在任何团队中都视为 owner。\n\n**邀请加入**：团队 owner/admin 可在「团队详情 → 邀请」页面创建邀请链接，链接形如 `/join/<inv_xxx>`，可设置：\n\n- 角色：新成员加入后的角色（仅 `admin` 或 `member`，不能邀请为 owner）\n- 过期时间（默认 24 小时）\n- 最大使用次数（默认 1）\n\n也可以「添加已有用户」：通过用户名或用户 ID 搜索已注册账户，直接加入团队。\n\n### 环境管理\n\n「环境」（environment）是 worker 向 RCS 注册后产生的实体，代表一台正在提供 agent 服务的工作机。每个环境有：\n\n- 拥有者（owner_user_id，可能为空 → 需要认领）\n- 关联团队（可选，关联后团队内成员可见该环境及其会话）\n- worker 类型（slz CLI / ACP agent）、容量、心跳\n\n**环境的归属**：\n\n- 启动 worker 时通过 `--user-id` / `--team-id` 指定 → 直接归属到该用户或团队\n- 未指定且使用共享 API Key → 生成 `claim_token`，进入待认领状态（见下文 claim 机制）\n\n**环境与团队的关联**：\n\n- 在「团队详情 → 环境」页面可把个人环境链接到团队，或把团队环境解绑回个人\n- 环境可在团队之间转移（需要源团队和目标团队的 owner/admin 权限）\n- 转移环境时，该环境下的所有会话归属随之转移到目标团队\n\n### Claim 机制（环境认领）\n\n当 worker 使用共享 API Key 启动、且未指定 `--user-id` / `--team-id` 时，RCS 不会把环境直接归属给任何人，而是生成一个 `claim_token`（形如 `clm_xxxxxxxx`）并打印认领 URL：\n\n```\n/code/claim/clm_xxxxxxxx\n```\n\n**认领流程**：\n\n1. worker 启动后在终端看到认领 URL\n2. 把这个 URL 发给任意已登录用户\n3. 该用户在浏览器打开 URL → 自动调用 `/environments/claim` 接口\n4. 该环境的 `owner_user_id` 写入此用户，`claim_token` 清空\n5. 该环境下已经创建的会话也会一并 backfill 到该用户名下（否则会成为无主孤儿会话）\n\n`claim_token` 有过期时间（`claim_expires_at`），过期后无法认领。已被认领的环境再次访问会返回 409。\n\n这个机制让团队成员用共享 API Key 启动 worker 后，再由具体的人认领，避免环境长期处于无主状态。\n\n### 会话可见域\n\n每个会话有 `visibility` 字段，控制谁能看到它：\n\n| 可见域 | 谁能看到 |\n|--------|---------|\n| `private` | 仅会话的 user owner |\n| `team` | 会话所属团队的所有成员 |\n| `public` | 所有登录用户 |\n\n实际的可见规则综合考虑了 ownership、visibility 和显式共享：\n\n1. 系统 admin 能看到所有会话（含无主孤儿会话）\n2. 用户作为 user owner 拥有的会话\n3. 用户所属团队作为 team owner 拥有、且 visibility 为 `team` 或 `public` 的会话\n4. 通过 `session_shares` 显式共享给该用户的会话（未过期）\n5. 通过 `session_shares` 显式共享给该用户所属团队的会话（未过期）\n6. visibility=`public` 的会话\n7. 无主孤儿会话：仅 admin 可见\n\n**会话转移**：会话 owner（或团队 admin）可把会话从个人空间转到团队（visibility 自动变 `team`），或从团队转回个人（visibility 自动变 `private`）。转移时需要目标是该团队的 owner/admin。\n\n**会话分享**：会话 owner 可生成分享链接，授予指定用户或团队「只读」或「读写」权限，可设置过期时间。被分享者会在自己的会话列表里看到该会话。\n\n### 权限审批\n\nRCS Web UI 在 agent 请求工具调用时弹出审批面板。权限模式（permissionMode）有 6 种，决定 agent 是否需要等待人工确认：\n\n| 模式 | 行为 |\n|------|------|\n| `default` | 每次工具调用都请求确认 |\n| `auto` | agent 自动判断是否需要确认 |\n| `acceptEdits` | 自动接受文件编辑，其他工具仍需确认 |\n| `plan` | 规划模式，仅制定计划不执行 |\n| `dontAsk` | 不询问，直接执行 |\n| `bypassPermissions` | 绕过所有权限检查（仅 sandbox 环境可用，非 root） |\n\n权限模式可在创建会话时指定，也可在会话进行中切换。fallback 顺序：客户端传值 > acp-link 启动时的 `ACP_PERMISSION_MODE` 环境变量。\n\n**三种审批面板**：\n\n- **工具调用审批**：显示工具名、参数和描述，提供 Approve / Reject 按钮\n- **多问题面板**（AskUserQuestion）：agent 一次提多个问题，用户在标签页中切换回答，每题可选预设选项或填写「Other」自定义文本\n- **计划审批**：显示 plan 内容，提供「Yes, auto-accept edits」「Yes, manually approve edits」「No, keep planning」三个选项，选 No 时可附反馈让 agent 重新规划\n\n### Worker 状态\n\nWeb UI 显示所有已连接的 worker（包括 slz CLI worker 和 acp-link agent）：\n\n- **在线状态**：worker 当前是否可接受会话\n- **最大并发**：worker 配置的 `--capacity`\n- **最后活动时间**：最近一次心跳\n\n### Artifacts 托管与团队画廊\n\nRCS 内置 Artifacts 存储服务。CLI 会话中用 `artifact` 工具发布的 HTML/Markdown 页面（进度面板、报告、交互式看板）会上传到 RCS 并归属到当前会话：\n\n- **会话详情页**：内嵌该会话上传的全部 artifact，可复制分享链接\n- **团队画廊** `/code/artifacts`：浏览所有你有权限查看的 artifact，可基于内置模板（PR 审查板、事故时间线、数据看板、发布清单）直接新建，也可删除\n- **可见性跟随会话**：会话对谁可见，其 artifact 就对谁可见；画廊新建的无会话 artifact 仅创建者与所属团队可见\n- **访问模型**：内容链接形如 `{BASE_URL}/v1/artifacts/{id}/content`，默认「URL 即密钥」（id 为不可猜测的随机串）；设 `RCS_ARTIFACTS_PUBLIC_ACCESS=false` 可改为读取也需登录凭证\n\nCLI 侧完整用法（Markdown 自动转换、hash 覆盖更新、TTL、环境变量）见「Saluzi 特色 → Artifacts」章节（[Artifacts](./artifacts)）。\n\n## RCS 服务器配置\n\n| 环境变量 | 默认 | 说明 |\n|---------|------|------|\n| `RCS_PORT` | 3000 | HTTP 端口 |\n| `RCS_HOST` | 0.0.0.0 | 监听地址 |\n| `RCS_API_KEYS` | — | 逗号分隔的 API Key（管理员权限，也是 worker 连接 token） |\n| `RCS_ALLOW_REGISTRATION` | true | 是否允许开放注册（设为 false 改为邀请制） |\n| `RCS_BASE_URL` | — | 外部访问 URL（反代时设置） |\n| `RCS_DB_PATH` | — | SQLite 数据库路径（默认内存，生产环境建议持久化） |\n| `RCS_WEB_CORS_ORIGINS` | — | Web UI CORS 允许的源（逗号分隔） |\n| `RCS_JWT_EXPIRES_IN` | 3600 | JWT 有效期（秒） |\n| `RCS_DISCONNECT_TIMEOUT` | 300 | 断开连接超时（秒） |\n| `RCS_WS_CLIENT_INACTIVITY_TIMEOUT` | 300 | WebSocket 客户端无活动超时（秒） |\n| `RCS_ARTIFACTS_PUBLIC_ACCESS` | true | artifact 内容读取是否公开（URL 即密钥）；设为 `false` 需登录凭证 |\n\n## Worker 接入\n\nWorker 是连接到 RCS 的 Saluzi CLI 实例，执行来自 Web UI 或其他客户端的会话。\n\n### 前置：设置环境变量\n\n**所有 worker 启动方式都需要先设置以下两个环境变量**：\n\n```bash\nexport SALUZI_BRIDGE_BASE_URL=http://rcs-host:3000\nexport SALUZI_BRIDGE_OAUTH_TOKEN=sk-your-key\n```\n\n- `SALUZI_BRIDGE_BASE_URL`：RCS 服务器地址\n- `SALUZI_BRIDGE_OAUTH_TOKEN`：必须与 RCS 启动时设置的 `RCS_API_KEYS` 中的某个 key 一致\n\n两个变量必须**同时设置**才生效。只设置一个会进入\"部分配置\"状态，启动时会提示补全。\n\n可选环境变量（用于归属和团队关联）：\n\n| 环境变量 | 说明 |\n|---------|------|\n| `SALUZI_BRIDGE_USERNAME` | 归属用户名（发送为 `X-Username` 头，RCS 自动认领 env 到该用户） |\n| `SALUZI_BRIDGE_USER_ID` | 归属用户 ID（绕过自动认领，直接绑定到该用户） |\n| `SALUZI_BRIDGE_TEAM_ID` | 关联团队 ID（env 注册到指定团队） |\n| `SALUZI_ENVIRONMENT_KIND` | 设为 `bridge` 标记会话来源为 remote-control |\n| `SALUZI_USE_CCR_V2` | 启用 CCR v2 传输协议 |\n| `SALUZI_BRIDGE_ALLOW_INSECURE_HTTP` | 设为 `1` 允许非 localhost 的 HTTP 连接（自托管内网场景，见下文） |\n| `SALUZI_BRIDGE_AUTO_CONNECT` | 设为 `1` 启用启动时自动连接 RCS（默认关闭；未设置时需在 CLI 内手动运行 `/rc` 或使用 `slz rc` 启动） |\n\n**关于 HTTP 连接**：默认情况下，`SALUZI_BRIDGE_BASE_URL` 如果是 `http://` 且不是 `localhost`/`127.0.0.1`，worker 会拒绝启动——这是为了防止 credentials 明文传输。如果远程 RCS 部署在可信内网（例如 TLS 由上游反代终止、或网络已加密），可设置 `SALUZI_BRIDGE_ALLOW_INSECURE_HTTP=1` 放开此限制。生产环境建议优先用 HTTPS 或 SSH 隧道转发到 localhost。\n\n如果不设置 `SALUZI_BRIDGE_USERNAME`/`SALUZI_BRIDGE_USER_ID`/`SALUZI_BRIDGE_TEAM_ID`，且 token 是共享的管理员 API Key，RCS 会生成 `claim_token` 并打印认领 URL，worker 终端会显示该 URL 供用户认领（详见上文「Claim 机制」）。\n\n### 启动方式\n\n设置好环境变量后，推荐直接运行：\n\n```bash\nslz rc\n```\n\n`slz rc` 是最简的启动方式，默认配置即可作为 worker 连接到 RCS。它是 `slz remote-control` 的简写，也接受 `slz remote`、`slz sync`、`slz bridge` 作为别名。\n\n其他可选方式：\n\n```bash\n# 交互式会话 + worker（既可本地用，也接受远程请求）\nslz --remote-control\n\n# 普通会话自动连接（需额外设置 SALUZI_BRIDGE_AUTO_CONNECT=1，否则普通会话不自动连接）\nSALUZI_BRIDGE_AUTO_CONNECT=1 slz\n```\n\n### 高级参数\n\n需要调整 worker 行为时，`slz rc` 支持以下参数：\n\n| 参数 | 说明 | 示例 |\n|------|------|------|\n| `--spawn <mode>` | Spawn 模式：`same-dir`、`worktree`、`session` | `--spawn=worktree` |\n| `--capacity <N>` | 最大并发会话数（仅 worktree/session 模式） | `--capacity=5` |\n| `--create-session-in-dir` | 启动时在当前目录预创建会话（默认开启） | `--no-create-session-in-dir` 禁用 |\n| `--session-id <id>` | 恢复指定会话 | `--session-id=abc123` |\n| `--continue` | 恢复最近会话 | — |\n| `--name <name>` | 会话名称（也用于 RCS 显示） | `--name=\"我的会话\"` |\n| `--username <name>` | 归属用户名（对应 `SALUZI_BRIDGE_USERNAME`） | `--username=alice` |\n| `--user-id <id>` | 归属用户 ID（对应 `SALUZI_BRIDGE_USER_ID`） | `--user-id=u-123` |\n| `--team-id <id>` | 关联团队 ID（对应 `SALUZI_BRIDGE_TEAM_ID`） | `--team-id=team-abc` |\n\n### Spawn 模式\n\n| 模式 | 说明 | 适用场景 |\n|------|------|---------|\n| `same-dir`（默认） | 所有会话在同一工作目录创建 | 单项目快速响应 |\n| `worktree` | 每个会话在独立 git worktree 中创建 | 多项目隔离，避免文件冲突 |\n| `session` | 单会话模式（容量固定为 1） | 简单场景，不需要并发 |\n\n## 会话接入（Attach）\n\n默认情况下，`/remote-control` 会为当前终端**新建**一个远程会话。Attach 模式改变这一行为：不新建会话，而是把一个**已经存在**的 RCS 会话接入当前终端，在本地继续这段对话，Web UI 上同步可见。\n\n适合场景：会话是在 Web UI 上创建的、或由其他终端发起，想换到自己的终端里继续；团队协作中接手队友的会话；或者把多台机器上的工作收拢到一个终端。\n\n### 三种接入方式\n\n| 方式 | 命令 | 行为 |\n|------|------|------|\n| 指定会话 | `/rc --attach <会话ID>` | 直接接入指定会话 |\n| 交互式选择 | `/rc --attach` | 打开会话选择器：模糊搜索列表（标题 — 状态 (会话ID)），回车接入，Esc 取消 |\n| 等待接入 | `/rc --wait`（或 `/rc --attach --wait`） | 注册后待命，等待 Web UI 侧把会话接到这台终端 |\n\n选择器里只会列出**你有权限管理**的会话；已结束、正被占用的会话和 ACP agent 的会话不会出现。\n\n**等待接入**时，终端会显示提示并持续待命。此时在 RCS Web UI 中把会话绑定到这个 worker（例如新建会话时在环境中选择该 worker），接入立即完成；若该环境还没有归属，终端会同时给出认领 URL，先认领才能接入。\n\n### 接入后发生什么\n\n- 该会话的既有对话历史会合并进本地终端（本地已有内容时保留在后面，并有提示行说明合并了多少条）\n- 之后终端与 Web UI 实时共享同一个会话：任意一端发送消息、发起审批，另一端都同步可见\n- 历史拉取失败时接入会中止并报错——不会出现「半接入」状态\n\n### 启动时自动接入（环境变量）\n\n除在会话内执行 `/rc` 命令外，也可以在启动 CLI 时通过环境变量直接进入接入模式：\n\n| 环境变量 | 说明 |\n|---------|------|\n| `SALUZI_BRIDGE_SESSION_ID` | 启动时直接接入指定会话（等效 `/rc --attach <会话ID>`） |\n| `SALUZI_BRIDGE_SESSION_MODE` | 设为 `attach`：启动后进入等待接入状态 |\n| `SALUZI_BRIDGE_ATTACH_TIMEOUT_MS` | 等待接入的超时时间（毫秒，默认 24 小时） |\n\n```bash\n# 启动即接入指定会话\nexport SALUZI_BRIDGE_SESSION_ID=sess-abc123\nslz\n\n# 或启动后等待 Web UI 分配会话\nexport SALUZI_BRIDGE_SESSION_MODE=attach\nslz\n```\n\n### 已连接时再次执行 /rc\n\n已处于远程控制连接状态时，再次执行 `/rc`（不带参数）会弹出连接管理对话框，包含三个选项：\n\n- **Disconnect this session** — 断开当前远程控制连接\n- **Show QR code** — 显示/隐藏会话 URL 二维码（手机扫码直接打开）\n- **Continue** — 保持连接，关闭对话框继续使用\n\n### 已连接时切换绑定\n\n再次执行 `/rc --attach …`、`/rc --wait`（或带 `--team-id` 等归属参数）会弹出确认框：确认后断开当前远程会话，按新的目标重新绑定；取消则保持现状。\n\n## Worker 与 RCS 的关系\n\n```\n┌─────────────────┐\n│   RCS Server    │  ← 运行 slz rcs\n│  (Web UI + API) │\n└────────┬────────┘\n         │ Bridge 协议\n         │\n    ┌────┴────┐\n    │         │\n┌───▼──┐  ┌──▼───┐\n│Worker│  │Worker│  ← slz rc / slz --remote-control / slz\n│  1   │  │  2   │\n└──────┘  └──────┘\n```\n\n- **RCS**：中央服务器，管理会话、用户、权限\n- **Worker**：通过 bridge 协议连接，从 RCS 获取任务，汇报状态\n- **Web UI**：通过浏览器访问 RCS，创建/查看会话\n\n## ACP 协议\n\nACP（Agent Control Protocol）让**外部 agent**（非 slz CLI，如 Claude Code、其他 ACP 兼容 agent）接入 RCS 的会话系统。slz CLI 自身使用 bridge 协议，不走 ACP。\n\n`acp-link` 是 ACP 桥接工具，随 `@saluzi/saluzi-edu` 一起安装，无需单独安装。\n\n### 连接 slz 到 RCS\n\n如果要让 slz CLI 作为 ACP agent 接入 RCS（而非 bridge worker），使用 `acp-link` 桥接：\n\n#### 1. 设置环境变量\n\n```bash\nexport ACP_RCS_URL=http://rcs-host:3000\nexport ACP_RCS_TOKEN=sk-your-key\n```\n\n- `ACP_RCS_URL`：RCS 服务器地址\n- `ACP_RCS_TOKEN`：必须与 RCS 的 `RCS_API_KEYS` 中的某个 key 一致\n\n可选环境变量：\n\n| 环境变量 | 说明 |\n|---------|------|\n| `ACP_RCS_GROUP` | Channel group ID（字母、数字、下划线、连字符） |\n| `ACP_RCS_USERNAME` | 归属用户名（自动认领 env 到该用户） |\n| `ACP_RCS_USER_ID` | 归属用户 ID（绕过自动认领） |\n| `ACP_RCS_TEAM_ID` | 关联团队 ID |\n| `ACP_AUTH_TOKEN` | 本地 WS 认证 token（不设则自动生成） |\n| `ACP_PERMISSION_MODE` | 默认权限模式 |\n\n#### 2. 启动 acp-link\n\n```bash\nacp-link slz -- --acp\n```\n\n`acp-link` 会启动 slz 作为子进程，通过 ACP 协议代理它与 RCS 之间的通信。slz 会出现在 RCS Web UI 的 agent 列表中，可接受会话请求。\n\n`--` 之后是传递给 slz 的参数（`--acp` 让 slz 进入 ACP 兼容模式）。\n\n### 连接 Claude Code 到 RCS\n\n`acp-link` 支持任何遵循 ACP 协议的 agent。Claude Code 通过专用的 ACP 适配包 `@agentclientprotocol/claude-agent-acp` 接入，接入命令是 `acp-link claude-agent-acp`（**不是** `acp-link claude`，因为 Claude Code 本身不直接说 ACP 协议，需要先装适配包）。\n\n#### 1. 安装 claude-agent-acp\n\nClaude Code 的 ACP 适配包需要单独安装：\n\n```bash\nnpm install -g @agentclientprotocol/claude-agent-acp\n```\n\n安装后会注册 `claude-agent-acp` 命令。\n\n#### 2. 设置环境变量\n\n```bash\nexport ACP_RCS_URL=http://rcs-host:3000\nexport ACP_RCS_TOKEN=sk-your-key\n```\n\n#### 3. 启动 acp-link 桥接\n\n```bash\nacp-link claude-agent-acp\n```\n\n`acp-link` 的第一个参数是 agent 的可执行命令名（这里是 `claude-agent-acp`）。`claude-agent-acp` 本身不需要额外参数，因此不需要 `--`。\n\n连接成功后，Claude Code 会作为 ACP agent 出现在 RCS Web UI 中，与 slz agent 并列，团队成员可在 Web UI 中选择它创建会话。\n\n其他 ACP 兼容 agent 的接入方式类似：安装对应的 ACP 适配包，然后用 `acp-link <命令名>` 启动。可在 npm 官网搜索 `@agentclientprotocol/*` 查找已适配的 agent。\n\n## 团队协作场景\n\n### 共享会话\n\n在 RCS Web UI 中创建会话，分享链接给队友（需登录才能查看），他们可查看或加入对话。也可通过 `session_shares` 显式授予指定用户或团队「只读」/「读写」权限，并设置过期时间。\n\n### 多 Worker 协作\n\n团队多个成员各自启动 worker，连接到同一 RCS：\n\n```bash\n# 成员 A：默认配置\nslz rc\n\n# 成员 B：worktree 隔离，5 并发\nslz rc --spawn=worktree --capacity=5\n```\n\nWeb UI 显示所有 worker 状态，会话与权限集中管理。\n\n### 外部 Agent 接入\n\n用 ACP 让非 slz 的 agent 接入 RCS。Claude Code 通过 `claude-agent-acp` 适配包接入：\n\n```bash\n# 先装适配包（仅一次）\nnpm install -g @agentclientprotocol/claude-agent-acp\n\n# 设置 RCS 连接\nexport ACP_RCS_URL=http://rcs-host:3000\nexport ACP_RCS_TOKEN=sk-your-key\n\n# 启动桥接\nacp-link claude-agent-acp\n```\n\n接入后所有 agent 在 Web UI 中统一管理，团队成员可选择任意 agent 创建会话。\n\n## 安全建议\n\n- RCS 默认监听 0.0.0.0，生产环境建议用反代 + HTTPS\n- 用强 API Key，定期轮换\n- 生产环境关闭 `RCS_ALLOW_REGISTRATION` 改为邀请制\n- 使用 `RCS_WEB_CORS_ORIGINS` 限制 Web UI 访问来源\n- 设置 `RCS_DB_PATH` 持久化 SQLite 数据库\n- 限制 worker 的权限（`/permissions` 配置）\n- `bypassPermissions` 模式仅在 sandbox 环境中启用，避免在主机直接放行所有工具调用\n\n## 故障排查\n\n| 问题 | 排查 |\n|------|------|\n| Worker 无法连接 | 检查 `SALUZI_BRIDGE_BASE_URL` 和 `SALUZI_BRIDGE_OAUTH_TOKEN` 是否同时设置；确认 token 与 RCS 的 `RCS_API_KEYS` 匹配 |\n| `Only HTTPS or localhost HTTP is allowed` | 远程 RCS 用 HTTP 被拒。优先用 HTTPS；或 SSH 隧道转发到 localhost；可信内网可设 `SALUZI_BRIDGE_ALLOW_INSECURE_HTTP=1` |\n| Web UI 登录失败 | 检查用户名密码；5 次失败后锁定 5 分钟 |\n| Web UI 401 | 确认使用 `RCS_API_KEYS` 中的 key 或有效的 session token |\n| 看不到某个会话 | 检查会话 visibility（private/team/public）；确认是否在所属团队的成员列表里；admin 可看所有 |\n| `/rc --attach` 列表为空 | 只列出你有权限管理、且未结束/未被占用的会话；确认目标会话的可见域与你的归属，或让会话 owner 共享 |\n| 接入报「环境无主」 | 该环境还没被认领，先在终端提示的 `/code/claim/clm_xxx` URL 完成认领，再重新接入 |\n| 等待接入一直没有会话 | 在 Web UI 把会话绑定到该 worker；超过超时（默认 24 小时）会放弃，可用 `SALUZI_BRIDGE_ATTACH_TIMEOUT_MS` 调整 |\n| 接入后历史没出现 | 接入会拉取会话历史，失败即中止；确认网络可达 RCS 后重试 `/rc --attach` |\n| 环境显示「待认领」 | worker 没指定 `--user-id`/`--team-id`，找到终端里的 `/code/claim/clm_xxx` URL，已登录用户打开即可认领 |\n| acp-link 无法连接 RCS | 检查 `ACP_RCS_URL` 和 `ACP_RCS_TOKEN` 是否设置 |\n| Agent 不出现在 Web UI | 确认 acp-link 已启动且 `ACP_RCS_TOKEN` 与 `RCS_API_KEYS` 匹配 |\n| 邀请链接失效 | 邀请 token 可能过期或达到 max_uses 上限；让团队 owner/admin 重新创建 |\n| 会话超时 | 调整 `RCS_DISCONNECT_TIMEOUT` 和 `RCS_WS_CLIENT_INACTIVITY_TIMEOUT` |\n"
     },
     "docs/guide/conversation-basics": {
       "frontmatter": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saluzi/saluzi-edu",
-  "version": "0.2.67",
+  "version": "0.2.68",
   "description": "Saluzi CLI - interactive AI coding assistant in the terminal",
   "license": "MIT",
   "type": "module",

package/packages/remote-control-server/src/routes/web/artifacts.ts

@@ -205,9 +205,7 @@ app.post('/artifacts', sessionAuth, async c => {
     })
     const row = getArtifactRow(result.id)
     return c.json(
-      row
-        ? toResponse(row)
-        : { id: result.id, expires_at: result.expiresAt },
+      row ? toResponse(row) : { id: result.id, expires_at: result.expiresAt },
       201,
     )
   } catch (err) {