Skip to content

armgit / Orkas

Public Imported from GitHub
0

Orkas is an open-source (MIT), local-first AI team for your desktop: a Commander turns your goal into to-dos and coordinates 16 built-in specialist agents plus Claude Code, Codex, OpenCode, OpenClaw and Hermes, with projects, scheduled automations and connectors. Free app for macOS & Windows; built-in models or your own keys.

del docs

wyt6ba4419e912e
diff --git a/docs/plans/connectors-feishu-dingtalk-wecom.md b/docs/plans/connectors-feishu-dingtalk-wecom.md
deleted file mode 100644
index 94db1785..00000000
--- a/docs/plans/connectors-feishu-dingtalk-wecom.md
+++ /dev/null
@@ -1,221 +0,0 @@
-# 连接器扩展:飞书 / 钉钉 / 企业微信
-
-## Motivation
-
-对标 Google 五件套的国内场景。三家平台都没有官方 hosted MCP, 按 §6.5 既有
-stdio adapter pattern 自营: 每个 service 一个 `PC/bin/<svc>-mcp-server.cjs`,
-wrap vendor REST API; OAuth 走 Server 端 bridge (同 `google.py` 模式)。
-
-## 现状关键事实
-
-### 飞书 (Feishu)
-- 标准 OAuth 2.0 Authorization Code grant; `open.feishu.cn`; refresh_token
- **会轮换** (同 GitHub / Notion) → 沿用 `manager._refreshGrantIfStale` 的
- per-instance lock, 无新约束。
-- 三种 token (app / tenant / user) — 我们要 **user_access_token**, scope 在
- 用户授权时挑选。
-- 海外版 Lark (`open.larksuite.com`) 接口形同 host 不同; **v1 只做国内
- feishu.cn**, 海外 host 入 v2。
-- 候选 services (照 Google 模式按 service 拆 entry):
- - **feishu_im** — `im:message`, `im:chat`: list_chats / get_chat /
- list_messages / send_text_message
- - **feishu_calendar** — `calendar:calendar`, `calendar:calendar.event`:
- list_calendars / list_events / get_event / create_event
- - **feishu_docs** — `docx:document`: get_document / create_document
- - **feishu_sheets** — `sheets:spreadsheet`: list_sheets / read_range /
- write_range
- - **feishu_bitable** — `bitable:app`: list_apps / list_tables /
- list_records / create_record / update_record (低代码用户量大, 主推)
- - **feishu_task** — `task:task`: list_tasks / create_task / update_task
-
-### 钉钉 (DingTalk)
-- 标准 OAuth 2.0 Authorization Code grant (用户身份); `api.dingtalk.com`
- (v2.0)。
-- API 1.0 vs 2.0 严重撕裂, **v1 完全用 2.0** (`x-acs-dingtalk-access-token`
- header, 不是 Authorization Bearer)。adapter 里硬编码 header 名, 不走通用
- Bearer helper。
-- 用户级 refresh_token 30d, access_token 2h, refresh 路径标准。
-- 候选 services:
- - **dingtalk_todo** — `Todo.Read.Write`: list / create / update / complete
- - **dingtalk_calendar** — `Calendar.Read.Write`: list / get / create
- - 文档 / 钉盘 API 暴露面比飞书弱, v1 不做。
-
-### 企业微信 (WeCom) — 架构 blocker
-**关键问题**: 授权模型是 `corp ↔ app` (企业管理员把 App 装到本企业,
-员工在企微里授权这个 App), 不是 `user ↔ app`。三条路:
-
-1. **ISV 第三方应用** — 腾讯资质审核, 数月级 + 需企业主体, 暂无。
-2. **BYO 企业应用配置** — 用户自己当企业管理员, 创建自建应用,
- 把 `corpid / agentid / corpsecret` 填给 Orkas。corpsecret 是长期密钥,
- 不是 OAuth token, **强冲突 §6.5「no API-key / PAT entry」**。
-3. **只做扫码登录** — `snsapi_userinfo` 拿 `userid + corpid`, 后续无工具能力,
- 不值得。
-
-**v1 建议**: catalog 加 `id: wecom` 占位 entry, 标
-`unavailable_reason: '需要 ISV 资质, 敬请期待'`, 不实现 OAuth + MCP。
-等 ISV 资质到位单独一波。**等用户确认这个处理**。
-
-## Components
-
-### 1. Catalog entries — `PC/src/main/features/connectors/catalog.ts`
-
-新增 6 (飞书) + 2 (钉钉) + 1 占位 (企微) = 9 个 entry。
-
-```ts
-{ id: 'feishu_im',
- display_name: '飞书消息',
- category: 'communication',
- description_zh: '飞书 IM: 列群组 / 读消息 / 发消息',
- description_en: 'Feishu IM: list chats / read messages / send text',
- auth_mode: 'server_bridge',
- oauth: { provider_id: 'feishu' },
- transport_template: {
- kind: 'stdio',
- command: '${ORKAS_NODE}',
- args: ['${ORKAS_PC_DIR}/bin/feishu-im-mcp-server.cjs'],
- oauth_env_key: 'FEISHU_ACCESS_TOKEN',
- },
- icon_svg: '<svg…/>' }
-// 其余飞书 5 个 + 钉钉 2 个同结构, 改 id / display_name / args / env_key
-{ id: 'wecom',
- display_name: '企业微信',
- category: 'communication',
- description_zh: '企业微信 (需要 ISV 资质, 敬请期待)',
- description_en: 'WeCom (requires ISV verification, coming soon)',
- auth_mode: 'server_bridge',
- oauth: { provider_id: 'wecom' },
- unavailable_reason: '需要 ISV 资质, 敬请期待',
- transport_template: null }
-```
-
-Icon SVG: 现状用 placeholder, 交付前由用户给最终 SVG 或我从 brand center
-抓。沿用既有 Google 套件的简化几何风格, 不引入彩色 brand SVG。
-
-### 2. Stdio MCP adapter scripts — `PC/bin/*.cjs`
-
-新增 8 个 (企微不建)。每个 ~200 行, 结构同 `gmail-mcp-server.cjs`: CJS +
-`@modelcontextprotocol/sdk/server/{index,stdio}` + StdioServerTransport,
-token 走 env, 每个 tool fetch 对应 REST endpoint。统一约束:
-
-- 长 list 默认 ≤50 条, 超长返回元数据 + `truncated: true`
-- 写工具默认 dry-run=false, 描述里强调有 side-effect
-- 错误码 → MCP tool error 解包 (复用 `gmailFetch` 同模式的小 helper)
-- 钉钉 adapter 用 `x-acs-dingtalk-access-token` header (其他都是
- `Authorization: Bearer`)
-
-#### 飞书 — 各 service 起步集 (读多写少)
-
-| Service | Endpoint base | Tools |
-|---|---|---|
-| feishu_im | `/open-apis/im/v1` | list_chats, get_chat, list_messages, send_text_message |
-| feishu_calendar | `/open-apis/calendar/v4` | list_calendars, list_events, get_event, create_event |
-| feishu_docs | `/open-apis/docx/v1` | get_document (walk blocks → 合 textRun → plain text), create_document |
-| feishu_sheets | `/open-apis/sheets/{v2,v3}` | list_sheets, read_range, write_range |
-| feishu_bitable | `/open-apis/bitable/v1` | list_apps, list_tables, list_records, create_record, update_record |
-| feishu_task | `/open-apis/task/v2` | list_tasks, create_task, update_task |
-
-#### 钉钉
-
-| Service | Endpoint base | Tools |
-|---|---|---|
-| dingtalk_todo | `/v1.0/todo` | list_todos, create_todo, update_todo |
-| dingtalk_calendar | `/v1.0/calendar` | list_events, get_event, create_event |
-
-### 3. OAuth provider modules — Server 端
-
-新建 `Server/biz/connectors/oauth/{feishu,dingtalk,wecom}.py`, 实现
-`start / exchange / refresh`, scope 按 `_SCOPES_BY_CATALOG_ID[catalog_id]`
-选择, 照 `google.py` 既有模式。`wecom.py` v1 在 start 直接抛
-`E_PROVIDER_UNAVAILABLE` (catalog 也标 unavailable_reason, 双层防护)。
-
-环境变量:
-- `ORKAS_OAUTH_FEISHU_CLIENT_ID` / `..._SECRET` (即 app_id / app_secret)
-- `ORKAS_OAUTH_DINGTALK_CLIENT_ID` / `..._SECRET` (即 AppKey / AppSecret)
-- `ORKAS_OAUTH_WECOM_CLIENT_ID` / `..._SECRET` (v1 留位)
-
-### 4. apply-template.ts / manager.ts / oauth.ts / registry.ts
-
-**不动**。占位符解析 / per-instance refresh lock / 加密存储 /
-registry.update(patch) 都是通用层, 已经在 Google 套件验证过, 本批 100% 复用。
-
-### 5. UI
-
-- 渲染端 `connectors.js` 卡片网格自动收新 entry, **无新代码**。
-- i18n: category 标签 `category.communication` / `productivity` 已有, 无新
- key。`unavailable_reason` 在 catalog 字段直接出 zh 文本 (保持现状), 不
- i18n。
-
-### 6. 测试
-
-按 §9 "Don't write" 准则, **不为每个 adapter 写单元测试** (外部 API mock 价值低)。
-验收靠对话手测。
-
-`PC/test/main/features/connectors/apply-template.test.ts` 现有 placeholder
-fixture 覆盖通用解析, 不需改。
-
-## Change list
-
-**新增** (不算企微 adapter):
-- `PC/bin/feishu-{im,calendar,docs,sheets,bitable,task}-mcp-server.cjs` — 6
-- `PC/bin/dingtalk-{todo,calendar}-mcp-server.cjs` — 2
-- `Server/biz/connectors/oauth/feishu.py` — 新
-- `Server/biz/connectors/oauth/dingtalk.py` — 新
-- `Server/biz/connectors/oauth/wecom.py` — 占位 (start 抛 unavailable)
-
-**修改**:
-- `PC/src/main/features/connectors/catalog.ts` — +9 entries (含 wecom 占位)
-- `Server/biz/connectors/oauth/__init__.py` (或同等注册点) — 注册 3 个
- provider
-
-**不动**:
-- `PC/src/main/features/connectors/{manager,apply-template,oauth,registry,mcp-client,oauth-config}.ts`
-- `PC/src/renderer/modules/connectors.js`
-
-## CLAUDE.md sync
-
-§6.5 当前规则已经覆盖 stdio adapter pattern / 视野 / refresh lock / 凭据
-存储, 本批是按既有规则执行, **无新约束**。
-
-Why: stdio adapter pattern 是为绕开 vendor-blocked MCP 设计的, 三家国内
-厂商都属同一类 (无 hosted MCP), pattern 直接复用, 不催生新规则。
-
-如果未来企微走 ISV 路线, 到时给 `§6.5` 加一段 "WeCom corp-bound OAuth"
-专项说明 (corpid / agentid 在 OAuth flow 中的位置)。
-
-## Open questions
-
-1. **企微 v1 处理**: 占位 + `unavailable_reason`, 还是冒着 §6.5 冲突走
- BYO corpsecret? 我倾向占位。
-2. **飞书 / 钉钉 catalog 拆分粒度**: 6+2 个细粒度 entry vs 一个
- `feishu_workspace` umbrella? 倾向拆分 (同 Google 模式), UI 可读性好且
- 单 service 故障不影响别的。
-3. **Icon SVG**: 现在 placeholder, 交付前你给最终 SVG 还是我去 brand
- center 抓?
-4. **飞书 IM `send_text_message`**: 算 high-impact side-effect, 是否默认从
- `enabled_subtools` 排除, 用户在连接器面板里手动启用? (同样问题: 飞书
- calendar `create_event`, bitable `create_record/update_record`, 钉钉
- `create_todo/update_todo` 等)
-
-## 验收
-
-每个 service 在对话里跑通一条最简 read tool:
-
-- feishu_im: "列出我的飞书群" → `list_chats`
-- feishu_calendar: "今天的飞书会议" → `list_events`
-- feishu_docs: "读飞书文档 :id" → `get_document`
-- feishu_sheets: "读 :token 的 A1:C10" → `read_range`
-- feishu_bitable: "列 :app 的 :table 前 10 条" → `list_records`
-- feishu_task: "列我的飞书任务" → `list_tasks`
-- dingtalk_todo: "列我的钉钉待办" → `list_todos`
-- dingtalk_calendar: "今天的钉钉日程" → `list_events`
-
-加一条 write 路径 sanity (任选一个 service 跑通 `send` / `create`)。
-
-通过后删本计划文件。
-
-## 工作量预估
-
-- 8 adapter × ~200 行 ≈ 1600 行 CJS, ~6h
-- 3 Python provider 模块 ~200 行 × 3 ≈ 600 行, ~2h
-- catalog + scope 表 ~100 行, ~30min
-- 总计 ~1.5 个工作日 (不含飞书 / 钉钉 OAuth 应用申请 + 审核等待)
diff --git a/docs/plans/connectors.md b/docs/plans/connectors.md
deleted file mode 100644
index d7227588..00000000
--- a/docs/plans/connectors.md
+++ /dev/null
@@ -1,434 +0,0 @@
-# Connectors(MCP-based)— 方案
-
-> 状态:草稿,按 CLAUDE.md「Plan first」流程落地后实施。
-> 跨项目:仅 PC(核心改动在 main + renderer + core-agent 装配点)。
-> 验收后按约定**删除本文件**。
-
----
-
-## 0. 决议汇总(来自前置对话)
-
-- **不自营 MCP server**。Orkas 客户端只做 MCP host(client),不托管任何 first-party MCP server。每个 catalog entry 指向社区/官方的 MCP server(本地 stdio 子进程或远端 URL),跑通的形态都是「Orkas 拿到 access_token → 注入到 MCP server 的 env / Authorization header → MCP server 自己代表用户调 provider API」。
-- **MCP 是连接器唯一形态**。不写"原生 TS Gmail handler",所有连接器都通过 MCP 协议接入。
-- **全内置 catalog,不支持自定义安装**。所有连接器从 `features/connectors/catalog.ts::CONNECTOR_CATALOG` 这一份精选表里来;UI 没有"添加自定义 / 粘贴 URL"入口。
-- **OAuth 是唯一鉴权方式**。砍掉 API-key / PAT 入口(一次性产品方向决议)。任何不能提供 OAuth 流程的服务不进 catalog。
-- **OAuth 客户端在 PC 端**。PKCE + 临时 127.0.0.1 listener(§1 单点豁免),无 Server 中转。`client_id` / `client_secret` 来源:env var(Hosted Orkas 打包时注入)或 `<uid>/local/config/connector-oauth.json`(BYO)。
-- **授权信息本地、不云同步**。所有 token / refresh_token / client_secret 都落 `<uid>/local/config/`(machine-private 目录,从设计上就不进 sync)。
-- **加密落地**:`util/crypto-vault.ts` 走 PBKDF2 + AES-256-GCM,密钥派生 = uid + 编译期常量 salt。**保护级别:obfuscation-grade**——只挡同步泄露 / 日志泄露 / 肉眼浏览;不挡能跑 Orkas 代码的攻击者。**故意不用 keychain**(用户决议:保持 data 目录可移植、无 OS keystore 依赖)。同一 vault 同时包了 `auth-profiles.json`(模型 provider 凭据)。
-- **连接器授权 ≠ 登录授权**。代码模块、存储文件、IPC namespace 全分离,不复用 `features/account/` 任何资源。
-- **Phase 0 可装的内置(提供商已注册 OAuth App 后即可用)**:GitHub、Notion、Slack。**OAuth-pending(catalog 中但 MCP server 目标未选定)**:Google 套件、Microsoft 365、Discord。
-- **指挥官默认全部已连接连接器可用**。智能体默认不带任何连接器,由用户在编辑页勾选。
-- **新依赖**:`@modelcontextprotocol/sdk`(仅 main 端使用,client 模式)。
-
----
-
-## 1. Motivation
-
-Orkas 的指挥官 / 智能体当前能用的工具集是 `model/core-agent/` 内的固定一套(bash / write_file / kb_* / web_search / image-gen…)。要让它们使用 Gmail / Slack / Notion / GitHub / Drive 等第三方服务,**必须把工具集从静态变成可扩展的**。MCP 是为这件事设计的标准协议:
-
-- 协议层标准化 → 一个 client 接一切 server
-- 工具发现由 server 动态报告 → Orkas 不再需要为每个服务写代码
-- 授权由 MCP server 维护方持有 → Orkas 公司不必去每个 provider 注册 OAuth App(除非自营 server)
-- 长尾用户自定义直接复用同一条链路
-
-最小可行形态:用户在「连接器」面板里安装/接入 MCP server,连接成功后该 server 的 tools 自动加入指挥官 / 选定智能体的可用工具集,LLM 可以像调 `bash` 一样直接调 `gmail_send`。
-
----
-
-## 2. 架构总览
-
-```
-┌──────────────────────────────────────────────────────┐
-│ Renderer (panel-connectors) │
-│ - Gallery: 推荐 + 自定义入口 │
-│ - 已连接列表 + 详情 + 断开 │
-└──────────────────────────────────────────────────────┘
- │ window.orkas.invoke('connectors.*', …)
- ▼
-┌──────────────────────────────────────────────────────┐
-│ ipc/index.ts: connectors.* handlers │
-└──────────────────────────────────────────────────────┘
- │
- ▼
-┌──────────────────────────────────────────────────────┐
-│ features/connectors/ │
-│ ├─ types.ts Connector / Tool / Config shapes │
-│ ├─ registry.ts <uid>/local/config/connectors.json │
-│ ├─ mcp-client.ts MCP client wrapper(stdio + http)│
-│ ├─ manager.ts lifecycle: connect / list / call │
-│ ├─ tools-adapter.ts MCP tool → core-agent AgentTool │
-│ ├─ bootstrap.ts boot + IPC binding │
-│ └─ index.ts feature exports │
-└──────────────────────────────────────────────────────┘
- │ tools 装配
- ▼
-┌──────────────────────────────────────────────────────┐
-│ model/core-agent/runner.ts::buildRunner() │
-│ - 第 8 步:注入 enabled connectors 的 tools │
-└──────────────────────────────────────────────────────┘
- │ runStream({ tools })
- ▼
- AgentRunner (in-process LLM tool-use loop)
- │
- ┌─────┴──────────┐
- │ Commander │
- │ Agent worker │
- └────────────────┘
-```
-
-**spawn 边界**(§1 单 spawn 入口原则):MCP stdio server 子进程的 `child_process.spawn` 必须**只**在 `features/connectors/mcp-client.ts` 内调用。`features/local_agents/` 依然是 5 个编码 CLI 的唯一 spawn 入口;二者职责完全分离(编码 CLI = 派发任务的 actor;MCP server = 工具提供方)。其他 features 模块要起 MCP server,必须通过 `connectors/manager.ts` 的接口,不直接 spawn。
-
----
-
-## 3. 存储 layout
-
-**单文件**:`<uid>/local/config/connectors.json`
-
-```json
-{
- "version": 1,
- "connections": {
- "gh-pat-default": {
- "id": "gh-pat-default",
- "display_name": "GitHub",
- "icon": "github",
- "transport": {
- "kind": "stdio",
- "command": "npx",
- "args": ["-y", "@modelcontextprotocol/server-github"],
- "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "<plaintext>" }
- },
- "enabled_subtools": null,
- "tools_cache": [
- { "name": "create_issue", "description": "...", "input_schema": {...} }
- ],
- "tools_cached_at": 1747200000000,
- "status": { "kind": "connected", "since": 1747200000000 },
- "created_at": "2026-05-14T...",
- "updated_at": "2026-05-14T..."
- },
- "notion-api-key": {
- "id": "notion-api-key",
- "display_name": "Notion",
- "transport": {
- "kind": "streamable-http",
- "url": "https://mcp.notion.com/mcp",
- "headers": { "Authorization": "Bearer <token>" }
- },
- ...
- }
- }
-}
-```
-
-字段说明:
-- `id`:连接实例 id(不是 connector 类型 id),用户可以连同一个服务的多个账号(gmail-personal + gmail-work)
-- `transport`:MCP transport 描述。Phase 0 支持 `stdio` + `streamable-http`,不实现 SSE(已 deprecated)
-- `enabled_subtools`:`null` = 全部启用;`string[]` = 白名单子集(上下文预算治理)
-- `tools_cache` / `tools_cached_at`:list_tools 结果缓存。冷启动时先用 cache 让 UI 立即出,后台再 reconnect 拉新
-- `status`:运行时态,**也持久化**(用于 UI 显示上次状态),但每次启动重新探测
-
-**Why 单文件不分目录**:连接器不像 skill/agent 有 blob 内容(脚本 + 多个文件),只是配置 + token + tool schema 缓存。单文件 JSON 写起来事务简单,跟 `account.json` 同档。如果未来引入 marketplace-style connector packages,再拆 `<uid>/local/marketplace/connectors/<id>/`。
-
-**敏感度**:跟 `account.json` 同档(plaintext under machine-private dir),但**这里存的是访问 MCP server 的 token,不是 provider 的 token**(provider token 由 MCP server 维护方自己存)。失效爆炸半径比 provider token 小。Phase 0 接受,Phase 1(任何 OAuth 接入之前)必上 keytar 包一层。
-
-**path 助手**(新增到 `paths.ts`):
-
-```ts
-export const userConnectorsConfigFile = (uid: string) =>
- path.join(userLocalConfigDir(uid), 'connectors.json');
-```
-
----
-
-## 4. 组件设计
-
-### 4.1 `types.ts`
-
-```ts
-export type Transport =
- | { kind: 'stdio'; command: string; args: string[]; env?: Record<string, string>; cwd?: string }
- | { kind: 'streamable-http'; url: string; headers?: Record<string, string> };
-
-export interface ToolSchema {
- name: string; // 原始 MCP tool name
- description: string;
- input_schema: Record<string, unknown>;
-}
-
-export interface ConnectorInstance {
- id: string; // 用户连接实例 id(业务唯一)
- display_name: string;
- icon?: string; // 内置图标 key 或 emoji
- transport: Transport;
- enabled_subtools: string[] | null;
- tools_cache: ToolSchema[];
- tools_cached_at: number;
- status: ConnectorStatus;
- created_at: string;
- updated_at: string;
-}
-
-export type ConnectorStatus =
- | { kind: 'connected'; since: number }
- | { kind: 'connecting' }
- | { kind: 'disconnected' }
- | { kind: 'error'; message: string; at: number };
-```
-
-### 4.2 `registry.ts`
-
-纯持久化层:`load(uid)` / `save(uid, state)` / `upsert(uid, instance)` / `remove(uid, id)`。
-所有写都过 `util/locks` 串行化,避免并发覆盖。
-
-### 4.3 `mcp-client.ts`
-
-封装 `@modelcontextprotocol/sdk` 的 `Client`,提供:
-
-```ts
-export class McpConnection {
- constructor(private readonly cfg: Transport, private readonly log: Logger) {}
- async connect(): Promise<void>;
- async listTools(): Promise<ToolSchema[]>;
- async callTool(name: string, args: Record<string, unknown>): Promise<unknown>;
- async close(): Promise<void>;
- get isConnected(): boolean;
-}
-```
-
-实现细节:
-- **stdio**:用 SDK 的 `StdioClientTransport`,内部 `child_process.spawn`。**这里是连接器 spawn 子进程的唯一调用点**(§1 单入口)。
-- **streamable-http**:用 SDK 的 `StreamableHTTPClientTransport`。
-- 进程退出时(`before-quit`)批量 close 所有连接(参考 §5 group_chat 的清理模式)。
-- spawn 失败 / list_tools 失败 / call_tool 异常 → 各自 `log.warn`/`log.error`,按 §10 logging 规范。
-
-### 4.4 `manager.ts`
-
-进程级单例,持有 `Map<connectorId, McpConnection>`。提供:
-
-```ts
-export async function bootstrap(uid: string): Promise<void>; // 启动时调用:load + reconnect all
-export async function listInstances(uid: string): Promise<ConnectorInstance[]>;
-export async function installInstance(uid: string, cfg: NewInstanceInput): Promise<ConnectorInstance>;
-export async function removeInstance(uid: string, id: string): Promise<void>;
-export async function refreshTools(uid: string, id: string): Promise<ToolSchema[]>;
-export async function setEnabledSubtools(uid: string, id: string, subset: string[] | null): Promise<void>;
-export async function callTool(uid: string, id: string, name: string, args: Record<string, unknown>): Promise<unknown>;
-export async function shutdownAll(): Promise<void>;
-```
-
-`install` 流程:写 registry → 实例化 `McpConnection` → connect → listTools → 缓存 → 返回。任一步失败回滚 registry 写入。
-
-### 4.5 `tools-adapter.ts`
-
-把 `ToolSchema` 映射成 core-agent 期待的 `AgentTool` shape:
-
-```ts
-export function buildConnectorAgentTools(uid: string, instances: ConnectorInstance[]): AgentTool[] {
- return instances.flatMap(inst => {
- const allowed = inst.enabled_subtools;
- return inst.tools_cache
- .filter(t => allowed === null || allowed.includes(t.name))
- .map(t => ({
- name: `${inst.id}__${t.name}`, // 防撞前缀
- description: t.description,
- inputSchema: t.input_schema,
- execute: async (input, _ctx) => {
- const result = await callTool(uid, inst.id, t.name, input);
- return { ok: true, output: JSON.stringify(result) };
- },
- }));
- });
-}
-```
-
-**Tool 命名**:`<instance_id>__<mcp_tool_name>`(双下划线分隔)。Why:MCP tool 原名可能重复(多个 server 都有 `list`),且 instance_id 本身就是用户给的(GH-personal / GH-work),二者拼起来防撞 + 用户 / LLM 阅读时能判断"哪个连接器的"。
-
-**§3 anti-drift 妥协**:core-agent 的 `tool-catalog.ts::TOOL_CATALOG` 是静态表,MCP 工具动态无法 enumerate。处理:在 catalog 加一个 `mcp_connector` 占位条目作为类别说明,并在 catalog 头注释加上「带 `<inst>__` 前缀的工具走 connector 链路、不在本表 enumerate」。anti-drift 测试需要相应豁免前缀模式(具体改法在 §6 change list)。
-
-### 4.6 `bootstrap.ts` + `index.ts`
-
-- `bootstrap.ts::bootstrap()`:在 `main/index.ts` 的 `app.whenReady()` 后调用一次。读 registry → 重连所有 connections(best-effort,失败的实例 status 变 `error` 但不影响启动)。
-- `before-quit` hook:调 `manager.shutdownAll()` 干净退出。
-- `index.ts`:feature 公共 API re-export。
-
----
-
-## 5. core-agent 集成
-
-### 5.1 `runner.ts` 注入
-
-在 `buildRunner()`(lines 224-322)第 7 步(caller extraTools)之后插入第 8 步:
-
-```ts
-// Step 8: connector tools (MCP-based)
-const connectorTools = await loadConnectorToolsForActor({
- userId,
- agentId, // undefined = commander
-});
-wrappedTools.push(...connectorTools);
-```
-
-`loadConnectorToolsForActor` 在 `features/connectors/tools-adapter.ts`:
-- `agentId` 为 undefined(commander)→ 取**所有 connected 实例**的 tools
-- `agentId` 存在 → 读 agent.json 的 `enabled_connectors`(见 5.2),取交集
-- 任一实例 `status.kind !== 'connected'` → 跳过,写 `log.warn` 但不阻塞 buildRunner
-
-### 5.2 `agents.ts` 字段
-
-`Agent` interface 增加:
-
-```ts
-enabled_connectors?: string[]; // undefined = legacy(不带任何连接器);[] = 显式空;非空 = 白名单
-```
-
-**三态语义**(对齐 §6 `skill_list` 已有约定):
-- `undefined` → **空集合**(智能体默认不带连接器)。与 `skill_list` 的「`undefined`=不过滤=全开」语义**故意不同**:连接器是用户主动赋权的能力,默认应该收紧,避免存量 agent 一升级就拿到所有连接器
-- `[]` → 显式空
-- `string[]` → 白名单(instance id 集合)
-
-**为什么和 `skill_list` 语义不同**:skill 是用户预先 curate 的能力集,给 agent 多曝光风险低;connector 携带外部副作用(发邮件、改文档),保守语义更安全。这条要在 CLAUDE.md §6 同步说明。
-
-指挥官没有 agent.json,由 `runner.ts` 内部判断 `agentId === undefined` 走「全部 connected」路径。
-
-### 5.3 Tool descriptions 缓存稳定性
-
-§3 提到 KV-cache 前缀稳定性。MCP tools 进 `wrappedTools` 后,pi-ai 把 description + schema 编进 tool-use API 字段,**不进 prompt 文本**——天然不破坏 prompt 前缀缓存。tool 顺序:固定按 `instances` 数组顺序 + 每个 instance 内按 `tools_cache` 顺序;`tools_cache` 写入按 MCP `list_tools` 返回顺序保持。**不要**按字母排或按使用频率排(会让 tools 数组本身飘)。
-
----
-
-## 6. 变更清单(按文件)
-
-### 新增
-
-- `PC/src/main/features/connectors/types.ts`
-- `PC/src/main/features/connectors/registry.ts`
-- `PC/src/main/features/connectors/mcp-client.ts`
-- `PC/src/main/features/connectors/manager.ts`
-- `PC/src/main/features/connectors/tools-adapter.ts`
-- `PC/src/main/features/connectors/bootstrap.ts`
-- `PC/src/main/features/connectors/index.ts`
-- `PC/src/renderer/modules/connectors.js`
-
-### 改动
-
-- `PC/package.json`
- - dependencies 加 `@modelcontextprotocol/sdk`(具体版本 install 时定)
- - §1 allow-list 注释里点名加入
-
-- `PC/src/main/paths.ts`
- - 加 `userConnectorsConfigFile(uid)`
-
-- `PC/src/main/index.ts`
- - `app.whenReady()` 后 `await connectors.bootstrap(uid)`(在 `account.bootstrap()` 之后)
- - `before-quit` 调 `connectors.shutdownAll()`
-
-- `PC/src/main/ipc/index.ts`
- - 加 channels:`connectors.list` / `connectors.install` / `connectors.remove` / `connectors.refresh` / `connectors.set_enabled_subtools` / `connectors.test_connection`
-
-- `PC/src/main/model/core-agent/runner.ts`
- - buildRunner 装配链第 8 步注入 connector tools
-
-- `PC/src/main/model/core-agent/tool-catalog.ts`
- - 加 `mcp_connector` 占位 entry + 头注释豁免 `<inst>__` 前缀
- - 同步 anti-drift 测试豁免规则(在 `test/main/core-agent/tool-catalog.test.ts` 或对应位置)
-
-- `PC/src/main/features/agents.ts`
- - `Agent` interface 加 `enabled_connectors?: string[]`
- - `normalizeAgent` 默认空数组
- - `updateCustomAgent` 接收该字段
-
-- `PC/src/renderer/index.html`
- - 第 33 行后插入 `connectors-btn`
- - 第 274 行后插入 `panel-connectors` section(grid + 详情双视图,对齐 `panel-skills`)
- - 加 `<script src="modules/connectors.js"></script>`
-
-- `PC/src/renderer/modules/boot.js`
- - `setView` 路由加 `view === 'connectors'`
- - 按钮高亮 toggle
-
-- `PC/src/main/locales/zh.json` + `en.json`
- - `sidebar.connectors`
- - `connectors.title` / `.empty` / `.add_custom` / `.tabs.available` / `.tabs.connected` / `.detail.*` / `.errors.*`
-
-- `PC/CLAUDE.md`(sync items 见 §8)
-
-### **不**改动
-
-- `OpenSource/SyncCode/strip-rules.json`:连接器无 Server 依赖,OrkasOpen 自动可用
-- `features/account/*`:完全不复用账号体系
-- `features/local_agents/*`:MCP server spawn 走 connectors,不混进 CLI 派发
-- 任何 prompt md:连接器 tool 通过 SDK tools 字段进 LLM,不进 prompt 文本
-
----
-
-## 7. IPC contract
-
-| channel | payload | response |
-|---|---|---|
-| `connectors.catalog` | `{}` | `{ ok: true, catalog: CatalogEntry[] }` |
-| `connectors.list` | `{}` | `{ ok: true, instances: ConnectorInstance[] }` |
-| `connectors.probe` | `{ catalog_id, fields }` | `{ ok: true, tools } \| error` |
-| `connectors.install_from_catalog` | `{ catalog_id, fields }` | `{ ok: true, instance } \| error` |
-| `connectors.remove` | `{ id }` | `{ ok: true, removed }` |
-| `connectors.refresh` | `{ id }` | `{ ok: true, tools }` |
-| `connectors.set_subtools` | `{ id, subtools: string[] \| null }` | `{ ok: true, instance }` |
-
-UI 流程:用户在 `connectors.catalog` 返回的 catalog 卡片里点「连接」→ 渲染该 entry 的 `auth_fields[]` 表单 → 可选先调 `connectors.probe` → 调 `connectors.install_from_catalog` 落地。`probe` / `install_from_catalog` 内部都走 `apply-template.ts::applyTemplate` 把字段套进 `transport_template`(含 `env_synthesizer` 钩子处理 Notion 那种 JSON 头打包的特例)。
-
-**没有 free-form 的 install 入口** —— `manager.installInstance` 已改为模块内部 `_installInstance`,所有公开路径都过 `installFromCatalog`。
-
----
-
-## 8. CLAUDE.md sync items
-
-实施完成后在 PC/CLAUDE.md 加 / 改:
-
-- §1 npm 依赖 allow-list:增 `@modelcontextprotocol/sdk`
-- §3 spawn 边界:补一行「`features/connectors/` is the sole spawn entry point for MCP stdio servers」
-- §3 tool-catalog 说明:补 `<inst>__<tool>` 前缀豁免约定
-- 新增 §6.5 或扩展 §6:Connectors(连接器)—— MCP-based、`<uid>/local/config/connectors.json`、agent.enabled_connectors 三态语义、tool 命名 `<inst>__<name>` 前缀、不进 prompt(走 SDK tools 字段)、Phase 1 才上 keytar
-- §9 Don't do:
- - 不在 `features/connectors/` 外 spawn MCP server
- - 不把 connector token 写进 cloud/(machine-private)
- - 不把 connector tools 注入 prompt(破坏 KV-cache)
- - 不复用 `account.*` 的 i18n / IPC namespace
-- OrkasOpen:连接器不进 strip-rules(无 Server 依赖)
-
----
-
-## 9. 验证路径(Phase 0 出口)
-
-1. `npm install` 后 `./run.sh` 启动正常,无新报错
-2. 侧边栏出现「连接器」tab,进入空态显示「未安装任何连接器」
-3. 点「添加自定义」→ 填入 `@modelcontextprotocol/server-filesystem` stdio 配置 + 一个允许目录 → 测试连接成功 → 看到工具列表
-4. 在指挥官里输入「列出 ~/Desktop 下的文件」,LLM 调用 `<inst>__list_directory` 成功,看到正确结果
-5. 重启应用,连接器自动重连,工具继续可用
-6. 退出应用,无 zombie 进程(`pgrep -af server-filesystem` 应该空)
-7. GitHub MCP 实例(PAT 模式):能调 `<inst>__list_repositories` 或类似 tool 拿到真实数据
-8. 创建一个智能体,在编辑页勾选 GitHub 连接器→该 agent 能调,未勾选的智能体不能调
-
----
-
-## 10. Phase 1+ 延后项(明确不在 Phase 0)
-
-- **MCP authorization (OAuth) flow**:按 MCP spec 实现 Dynamic Client Registration + OAuth 2.0 + PKCE。回调走 `orkas://connectors/callback` deep link(沿用 `account/oauth_flow.ts` 的 protocol handler 模式,但**不复用代码**,新建 `features/connectors/oauth.ts`)。
-- **keytar 加密**:token 包一层 AES-GCM,主密钥存 OS keychain。**OAuth 接入前必做**。
-- **Marketplace 推荐列表**:从 Server 拉一个 curated 的 connectors 目录(可一键安装的 MCP server 列表),跟 marketplace skill/agent 同模式但走独立 endpoint。Phase 0 完全没有 marketplace,只有「添加自定义」。
-- **Lazy tool discovery**:连接器数量上去后,暴露 meta-tool `discover_connector_tools(id, intent)` 让 LLM 按需查 tools,而不是把所有 tools 一次塞进 prompt。
-- **写操作的 chat 内 confirm UI**:MCP spec 没有「读 vs 写」标注(annotations 字段是 hint),暂走「全部 auto-execute」;Phase 1 接入 MCP annotations + Orkas 现有 tool-use confirmation 通道。
-- **多账号同 provider**:UI 显式支持同一服务连多个实例(gmail-personal + gmail-work),实例 id 由用户起名。Phase 0 schema 已经支持,但 UI 不重点展示。
-
----
-
-## 11. 待定项 / 风险
-
-1. **`@modelcontextprotocol/sdk` 版本兼容性**:SDK API 在快速迭代,install 时锁版本,并在 PR 描述里贴版本号。
-2. **stdio server 启动开销**:每个 stdio server = 一个 Node/Python 子进程,N 个连接器 = N 个常驻进程。Phase 0 不做按需启停(首次 tool call 才 spawn),全在 bootstrap 起;用户量大时再优化。
-3. **streamable-http 的健康探测**:Phase 0 不做 keepalive ping,依赖每次 callTool 的失败感知。
-4. **错误传播给 LLM**:connector tool execute 失败时返回 `{ ok: false, error }`,core-agent 把 error 作为 tool result 给 LLM 看,让模型决定 retry / 切换路径。**不**把异常吃掉。
-5. **Tool description 国际化**:MCP server 自己负责,Orkas 不翻译。zh 用户看到英文 description 是接受的(同 §6 skill description 早期阶段处理方式)。
-
----
-
-实施按 §6 文件清单从 main 端往 renderer 推;E2E 验证按 §9 跑通后本文件删除(CLAUDE.md「Plan first」流程要求)。
diff --git a/docs/plans/multi-device-sync.md b/docs/plans/multi-device-sync.md
deleted file mode 100644
index 3fbef8f9..00000000
--- a/docs/plans/multi-device-sync.md
+++ /dev/null
@@ -1,576 +0,0 @@
-# 多设备同步(multi-device-sync)— 方案
-
-> 状态:草稿,按批次确认中。
-> 跨项目:PC(Electron 主进程 + renderer)+ Server(FastAPI + COS)。
-> 验收后按 CLAUDE.md「Plan first」约定删除本文件。
-
----
-
-## 0. 决议日志(按批次)
-
-### 批次 1(COS 访问通道) — ✅ 已决议
-- **方案 B:STS 直传**。PC 调 `/sync/sts` 拿 1h 临时凭据后直发 COS;manifest commit 与配额计账仍由 Server 端点(保 CAS 原子)。
-- **新依赖** `cos-nodejs-sdk-v5` 加入 `PC/package.json` 的 allow-list(要在 PC/CLAUDE.md §1 同步)。
-- **marketplace 上传保持 server-proxy**,不迁 STS 直传。Why:dev-only 频次极低、server 居中做 id 分配 + spec 重写、ACL public-read 维度与同步 private 不同,迁移收益负值。
-
-### 批次 8(传输优化与增量同步) — ✅ 已决议
-- **单文件 gzip**(BYO encoding 模式):PC 两端自己加解压;COS 完全不感知压缩、永远不解压;不设 `Content-Encoding` 头(避免 SDK 自动解压);扩展名白名单 + 明文 > 4 KB 阈值;路径不加 `.gz` 后缀(COS path 与本地一对一镜像);sha 算明文,`size` 算压缩后字节(与配额对齐)。
-- **不做 bundle zip**:会破坏 manifest per-file diff 模型。
-- **配额按实际 COS 占用计**(压缩后字节,不是明文)。Why:资源被限制的应该按真实占用算;不耦合压缩策略;用户得到压缩率高的文件类型的隐性福利。
-- **大文件 multipart + 续传**:> 5 MB 自动 multipart;状态进 `local/sync/state.json::pending_uploads[]`,断点续传,upload_id 7 天过期。
-- **批量删除走 DeleteMultipleObjects**(≤ 1000 / 批)。
-- **Rename 优化 v1 做**:local_index 维护 `sha → [paths]` 反查;命中时本地 `fs.copyFile` 或远端 `PutObjectCopy`,避免重复传输。
-- **不做 byte-level dedup**(rsync 风格):复杂度跳一档,COS 不原生支持,业界主流不暴露。
-- **活跃 jsonl 整文件重传**作为 v1 已知开销接受,靠 debounce 缓解;v1.x 看带宽用量决定是否做分片。
-- **增量分三层**:manifest ETag(L1)→ 文件 sha diff(L2)→ multipart part 续传(L3)。
-
-### 批次 7(业界对照后修订) — ✅ 已决议
-- **同 message_id 双侧编辑也留底**(append-only 假设的盲区):原 plan "按 mtime 取较晚胜出" 会**默默丢失败者修改**。修订为:新 id 双侧追加直接 union;**同 id 双侧编辑 = 冲突**,败者那一条 message 写入 `local/sync/conflicts/<ts>-<rel_path>.jsonl`(仅含被覆盖的那条),走与可变 JSON 同款的恢复 UX。Why:业界(Dropbox / Obsidian / git)面对这种场景都不会默默丢——我们对外宣称"自动合并 jsonl",必须在覆盖发生时给用户保留路径。
-- **冲突留底保留期改为 profile 配置项** `sync_conflict_retention_days`(默认 30 天)。Why:Obsidian Sync 付费档最高保留 1 年,30 天硬编码偏短;改成 profile 字段后,未来按会员等级可调到 90 / 180 / 365 天(与配额分级同设计模式)。
-
-### 批次 5(实施保障) — ✅ 已决议
-- **冲突合并器单测必做**(按 PC/CLAUDE.md §9 "Hard rule for LLM-output text munging" 同标准):set A 真实命中 + set B 似是而非不命中;走 `npm test`,绝不用 `npx vitest`(会留下 sqlite ABI 烂摊子)。
-- CLAUDE.md / strip-rules 三处改动表述按 §9 草稿落地(vector.db 反转 / 新增 §N sync 引擎 / OrkasOpen strip 名单)。
-
-### 批次 6(设置页结构 + 通知策略,追加) — ✅ 已决议
-- **设置页 4 tabs**(用户指定):
- | Tab | i18n key | 内容 |
- |---|---|---|
- | 账号 | `settings.tab.account` | Account 卡片(登录 / 退出 / profile) |
- | 数据 | `settings.tab.data` | **Sync 卡片**(含状态 / 进度 / 配额 / 冲突 / 隐私说明)+ Data root + Clear all conversations |
- | 通用 | `settings.tab.general` | Language / Commander avatar / Local Execution / Metacognition |
- | 配置 | `settings.tab.credentials` (en="Credentials") | Models & credentials + Search API Key + Image API Key |
-- **Sync 归"数据"tab**:sync 是云端数据管理;与本地 data root / clear-convs 一起归口,用户不用在多处找"我的数据在哪、占多大、怎么清"。
-- **完全去 toast**。所有需用户知晓的事件靠:
- 1. 侧边栏 settings 按钮右上角圆点(红 = error / login_required / quota_full;橙 = warning / quota_near_full / conflict_pending / 连续失败 ≥ 3 次)
- 2. 进入设置页时,对应 tab 标题也带圆点(导航到具体 tab)
- 3. 卡片内部展开详情
-- **连续失败阈值 N=3**(单次网络抖动不告警)。
-- **v1 不做 in-flow ribbon**(编辑器内联提示);接受"用户被覆盖时当下不知道"的弱点,靠圆点 + 进设置看到。v1.x 视反馈再决。
-- **OrkasOpen 看到 3 tabs**:账号 tab 整体 strip(与 `#settings-account-group` 同进退),数据 tab 内 sync 卡片 strip(gate `typeof window.orkas?.sync !== 'undefined'`),OrkasOpen 数据 tab 只剩 data root + clear convs。
-
-### 批次 4(用户体验:配额 + 冲突 UX) — ✅ 已决议
-- **默认配额 5 GB / user**。Why:附件全同步场景下 1 GB 易爆、10 GB+ COS 成本走高;5 GB 覆盖 80% 用户。**未来按会员等级分档**——Orkas DB 表 `user_sync_usage` 的 `quota` 字段 per-row 可配,配额来源链路:默认值(profile 配置)→ 会员等级表(v1.x 加) → user override(管理员后台)。
-- **超配额规则按 size delta 判定**(不是粗暴拒所有 push):
- - manifest commit 计算 push 集的 net size delta(新增 - 删除 - 修改前后差)
- - `delta ≤ 0` → **允许**(删除 / 等大修改 / 缩小修改都放行;用户腾空间的路径不能被堵)
- - `delta > 0 && used + delta > quota` → **拒绝**,返回 `{ok:false, error:"QUOTA_EXCEEDED", delta, used, quota}`
- - **pull 永远允许**(不增加占用;断了用户进入"什么都看不到"死锁)
- - **manifest 自身大小**计入 used,但 tombstones 不计(30 天后自清)
-- **配额满时 UI 引导**:设置页 sync 卡片满额时展开「占用 Top 10」列表(大到小,显示 path 摘要 + size + mtime),每行带「删除」按钮 → 走正常 delete + 墓碑流程。**v1 必做**——否则用户没释放路径。
-- **冲突 UX = C + 可恢复**(用户提出的闭环):
- - 写冲突时本机旧版本写入 `local/sync/conflicts/<ts>-<rel_path>`
- - **toast 提示**:"`agent.json` 已被另一台设备的修改覆盖。[查看历史]"
- - 设置页 sync 卡片下有可折叠「冲突记录」列表(最近 30 天),每条带两个按钮:
- - **「恢复此版本」**:把 conflicts/ 里的旧内容覆盖回 cloud/ 路径 + `_v+1` + 标 dirty → 下次 sync 这版本胜出推到其他设备。点击前弹二次确认:"这会撤销你在本机自冲突以来的修改,并把旧版本推到其他设备,确认?"
- - **「忽略并删除留底」**:清掉 conflicts/ 那条记录
- - **conflicts/ 默认保留 30 天**,改成 profile 配置项 `sync_conflict_retention_days`(批次 7 修订);后续按会员等级可调到 90 / 180 / 365 天;到期自动清;用户也可在列表里手动清。
-
-### 批次 3(隐私 / 加密) — ✅ 已决议
-- **v1 不做应用层加密**。安全模型 = **STS + private bucket + COS SSE-COS(免费透明)**。Why:STS scope 锁死已挡住绝大多数现实威胁(外部攻击者 / 其他用户 / 网络中间人);应用层加密的增量只在「COS / Orkas 内部威胁 + 执法调取」,v1 不投这块工程复杂度(密钥管理占 80% 成本)。
-- **取消 codec.ts 抽象层**:无 v1 实现 → 抽象阅读成本反成负担。manifest 直接存**明文 sha256**,便于校验 / 去重 / 排障。v2 真要上 E2EE 时单独立项做(届时会破坏性变更数据格式,已写入 §10 风险)。
-- **UI 设置页 sync 卡片**显示一行说明:"数据通过加密通道(HTTPS)上传到私有云存储,仅你的账号可访问"。**不写**"端到端加密"——诚实表达能力边界。
-
-### 批次 2(同步范围) — ✅ 已决议
-- **vector.db 不同步**(方案 B)。云端只放 `contexts/` 源文件;各设备本地 `kb_indexer.reconcile` 自行 rebuild 索引。**必须改 PC/CLAUDE.md §4 constraint 5**(当前规则相反)。Why:改一篇文档触发几百 MB db 全量上传不可持续;索引按定义可重建。
-- **附件三家全同步**:`chat_attachments/`、`chat_artifacts/`、`saved_apps/` 均纳入 v1 同步集。无 size 阈值、无懒拉。Why:体验一致性优先,"chats 同步了但附件缺"会让对话残缺。**代价**:单条 4K 视频可能 GB 级,几台设备并发上传会快速吃配额——批次 4 决配额时要正视这点;engine 需支持 COS 分块上传(`cos-nodejs-sdk-v5` SDK 原生支持,对 > 5MB 文件用 multipart)。
-- **workspace.json 不同步**(沿用 PC/CLAUDE.md §4 既有归类)。Why:路径在异机无效;用户对"在哪台机器干什么"有直觉边界。
-
-### 术语澄清(贯穿全文)
-- **OAuth `user_id`**:登录后 server 返回,写入 `<local_uid>/local/config/account.json::user_id`,**COS 前缀就用它**。
-- **本地 `uid`**:8-digit 数字、每台机器独立生成(`features/users.ts::initActiveUser`),仅用于本地容器路径 `<container>/data/<uid>/`,不上云、不做 COS scope。
-- **device_id**:sync engine 首次启动时生成的 UUID,存 `<local_uid>/local/sync/state.json::device_id`,仅用于 manifest 里 `last_writer_device_id` 排障字段(不是安全凭据,与 account.json 无关)。
-
-**Why**:同一 OAuth 账号在不同机器上有不同本地 `uid`,云端必须按 OAuth `user_id` 聚合数据,否则跨机看不到同一份云端内容。
-
----
-
-## 1. Motivation
-
-用户在登录态下使用 Orkas,希望本地数据(聊天、agent/skill 自定义、KB 源文件、preferences 等)在多设备间自动同步:
-- 第二台设备登录同一账号 → 自动拉取已有数据
-- 在 A 设备修改 → B 设备下次启动或运行中能看到
-- 设置页有「立即同步」按钮 + 上次同步时间
-- 显示当前云端占用,为后续配额限制铺路
-
-现状利好:
-- `<uid>/cloud/` vs `<uid>/local/` 切分早已落到 PC/CLAUDE.md §4,「哪些该同步」结构上已经回答
-- Server 端 COS(`qcloud_cos` + private bucket + `temp/` lifecycle)已就绪
-- `marketplace_reconcile.ts` 提供了"manifest → 本地状态"心智模型可复用
-- IPC、启动 hook、settings 页面 Data 段位均有干净的扩展点
-
-## 2. 设计目标 / 非目标
-
-**目标**
-- 跨设备最终一致:所有 `cloud/` 下数据可在合理时间内对齐
-- 私有性:bucket 全 private;STS scope 按 OAuth `user_id` 锁死;启用 COS SSE-COS;`session_id` / API key 永不上云
-- 频控 + 实时兼顾:按域 debounce + 退出/进入后台强制 flush
-- 启动主动同步、运行中按需 push、配额可观察
-- OrkasOpen 构建中**整套 sync 必须被 strip 掉**(与 `features/account/` 同进退,遵 PC/CLAUDE.md §4 + §11 strip-rules 约定)
-
-**非目标(v1 不做)**
-- 应用层加密(含 codec 抽象层;v2 真做 E2EE 时单独立项)
-- 实时多端协作(v1 最终一致 + LWW + 提示,不做 CRDT)
-- 按域选择性同步 UI(数据模型留位,UI v2)
-- 付费配额 / 配额升级
-
-## 3. Components
-
-### 3.1 COS 端布局
-
-单一 private bucket,按 **OAuth `user_id`** 前缀强隔离(不是本地 uid,原因见 §0 术语):
-
-```
-orkas-user-data/<oauth_user_id>/
- manifest.json # 真值索引(见 §4.1)
- cloud/chats/<cid>.jsonl
- cloud/chats/<cid>/{members,state,plan,visibility/}
- cloud/chats/{skill,agent}/<id>/chat.jsonl
- cloud/chat_attachments/<cid>/<file>
- cloud/chat_artifacts/<cid>/<artifactId>/<files...>
- cloud/saved_apps/<appId>/<files...>
- cloud/sessions/<sid>.jsonl
- cloud/contexts/... # KB 源文件;vector.db 策略待批次 2 决(§7.2,CLAUDE.md §4 当前规则与方案有冲突)
- cloud/memory/{MEMORY.md, USER.md}
- cloud/agents/<aid>/{agent.json, meta/, skills/}
- cloud/skills/<sid>/...
- cloud/projects/<pid>/{project.json, bindings.json}
- cloud/marketplace/installs.json
- cloud/config/{preferences.json, component-enabled.json}
- tombstones/<rel_path> # 删除墓碑,30 天后清理
-```
-
-- pretty-path 镜像本地 `cloud/` 一对一(便于排障,不做 content-addressed dedup)
-- ACL:bucket 全 private;对象 inherit
-- Bucket lifecycle:`tombstones/` 30 天自动清;老版本对象不保留多版本(v1 不做时间机器)
-- COS server-side encryption 启用(free)
-
-### 3.2 本地端布局(machine-private,不上云)
-
-```
-<container>/data/<local_uid>/local/sync/
- index.json # 上次同步成功时的快照:{rel_path: {sha256, size, mtime_ms, _v}}
- state.json # {device_id, last_sync_ts, last_pulled_generation, in_progress, pending_uploads[]}
- conflicts/<ts>-<rel_path> # 被覆盖的可变 JSON 整文件留底
- conflicts/<ts>-<rel_path>.jsonl # append-only 同 id 编辑冲突,仅含被覆盖那条 message(批次 7 决议)
- preferences.json # 按域开关(v1 仅初始化默认值,UI v2 加)
-```
-
-`device_id` 在首次启动 sync engine 时生成(UUID v4),写入 state.json 后不变;用于 manifest `last_writer_device_id` 字段,不参与鉴权。
-
-### 3.3 模块拆分
-
-**PC 端(新增 `PC/src/main/features/sync/`)**
-- `engine.ts` — 调度、debounce 表、startup/quit hook、运行中 dirty 事件订阅
-- `manifest.ts` — manifest 拉取 / diff / 三集计算(pull/push/delete)
-- `transport.ts` — STS 获取 + COS SDK 调用封装(PUT/GET/DELETE/HEAD;大文件走 multipart)
-- `local_index.ts` — `local/sync/index.json` 维护、本地文件 sha 缓存
-- `dirty_bus.ts` — 各 feature 写入后 emit 的事件总线,按域 debounce
-- `merge/` — 按数据形态划分的冲突合并器:`jsonl_append.ts`、`mutable_json.ts`、`binary.ts`
-
-**Server 端(新增 `Server/api/sync.py` + `Server/biz/sync/`)**
-- 所有 sync 端点都过现有 `utils/auth.py::check_login`(`user_id` + `session_id` 头部,SessionMgr 滑动续期)。**绝不接受请求参数里传入的 `user_id`**——scope 推导只能来自校验后的 session。
-- `POST /sync/sts` — 颁发 1h COS 临时凭据,scope 锁死 `<oauth_user_id>/*`
-- `POST /sync/manifest/commit` — 唯一的 manifest 写入口;CAS(按 generation);同时算账更新 usage
-- `GET /sync/usage` — 返回 `{used_bytes, quota_bytes, last_sync_ts}`
-- `Server/biz/sync/quota.py` — 配额计账与软硬阈值判定
-- DB 新表 `user_sync_usage(user_id PK, bytes BIGINT, quota BIGINT, updated_at)`(PK 用 OAuth `user_id`,与现有 account 体系对齐)
-
-### 3.4 IPC 接口(新增)
-
-| Channel | 类型 | Payload | 返回/事件 |
-|---|---|---|---|
-| `sync.runNow` | invoke | `{}` | `{ok, error}`;进度通过 push 事件 |
-| `sync.status` | invoke | `{}` | `{state, last_sync_ts, last_error, progress}` |
-| `sync.usage` | invoke | `{}` | `{used_bytes, quota_bytes}` |
-| `sync.progress` | push event | — | `{state, current, total, current_path}` |
-| `sync.subscribeStatus` | stream | `{}` | yields status changes |
-
-新 features → IPC 的方向遵守 PC/CLAUDE.md §3(ipc → features,不反向)。
-
-## 4. 关键机制
-
-### 4.1 Manifest 格式
-
-```jsonc
-{
- "manifest_v": 1,
- "generation": 42, // 单调递增,CAS 用
- "last_writer_device_id": "...",
- "last_writer_ts_ms": 1731600000000,
- "entries": {
- "cloud/chats/abc.jsonl": {
- "sha256": "...", // 明文内容的 sha(不是压缩后字节)
- "size": 12345, // **实际存到 COS 的字节数**——压了就是压缩后;配额按此累加(批次 8 决议)
- "mtime_ms": 1731599000000,
- "_v": 7, // 文件级单调版本(每次本地写入 +1)
- "schema_v": 1,
- "compressed": "gzip" // null | "gzip"(批次 8 决议)
- },
- "...": { ... }
- },
- "tombstones": {
- "cloud/chats/deleted.jsonl": { "deleted_at_ms": 1731500000000, "_v": 9 }
- }
-}
-```
-
-**generation 作为主时序**(不信任客户端 mtime;mtime 仅作辅助二级排序)。
-
-### 4.2 单次 sync 流程
-
-```
-1. GET manifest.json (带 If-None-Match / ETag),未变跳到 5
-2. diff(remote.entries, local_index)
- ├─ need_pull: remote 新 / 本地缺
- ├─ need_push: 本地新 / remote 缺
- ├─ need_delete_local: tombstones 中有,本地存在
- └─ need_delete_remote: 本地有删除标记,remote 仍存在
-3. 串行 delete local(清本地被墓碑标记的文件)
-4. 并发 pull → 并发 push(受 max-concurrency 限制,单文件失败独立重试)
-5. POST /sync/manifest/commit (带 base_generation = 拉到的 generation)
- ├─ 成功 → 写 local/sync/index.json + state.json
- └─ CAS 冲突 → goto 1,重试 1 次后退避到下个周期
-```
-
-### 4.3 冲突解决(按数据形态分类)
-
-| 数据形态 | 策略 |
-|---|---|
-| `chats/*.jsonl`、`sessions/*.jsonl`(append-only) | 新 id 双侧追加直接 union;**同 id 双侧编辑 = 冲突**(批次 7 决议):较晚 mtime/_v 胜出,败者那一条 message 写入 `local/sync/conflicts/<ts>-<rel_path>.jsonl`(仅含被覆盖那条),同样进设置页"冲突记录"列表 + 「恢复此版本」按钮 |
-| `preferences.json` / `agent.json` / `project.json`(可变 JSON) | 文件内嵌 `_v`;双侧都 > base = 冲突,LWW(_v 大者胜,并列时 generation 大者),老版本写入 `local/sync/conflicts/<ts>-<rel_path>` 留底 30 天,toast + 设置页「冲突记录」列表(含「恢复此版本」按钮 → 把 conflicts/ 内容覆盖回去 + `_v+1` + 标 dirty,二次确认)|
-| 附件(二进制) | 按 sha256 内容寻址,永不冲突(同 path 不同 sha 视作可变 JSON 同策略) |
-| `marketplace/installs.json` | 视作可变 JSON;本地 reconcile 再消费 |
-
-### 4.4 Schema 防降级
-
-每个可变 JSON 顶层带 `_schema_v`。pull 阶段若 `remote.schema_v > local_known_v` → **拒绝覆盖本地**,UI 提示「其他设备运行的版本较新,请升级」。push 阶段不会发生(本设备只能写自己已知的 schema)。
-
-### 4.5 频控
-
-- **运行中**:feature 写入后 emit `dirty(domain, rel_path)` → `dirty_bus` 按 domain 启动 debounce 计时器
-- **域级 debounce 默认**:
- - `preferences` 2s
- - `chats` / `sessions` / `memory` 5s
- - `agents` / `skills` / `projects` 10s
- - `chat_artifacts` / `saved_apps` 10s(小 bundle,与 agents 同档)
- - `chat_attachments` 30s(大文件域,含视频;分块上传单独并发上限)
- - `contexts`(KB 源) 15s
-- **到点合并**:所有过期 timer 合并成一次 sync pass(同一窗口内多次 dirty 只触发一次 sync)
-- **强制 flush 触发**:app `before-quit`、用户点「立即同步」、startup
-- **全局 floor**:两次自动 sync 间至少 30s(防异常风暴)
-
-### 4.6 启动同步 hook
-
-`PC/src/main/index.ts` 在现有 `marketplaceReconcile` 之后追加:
-
-```ts
-setImmediate(() => syncFeature.syncNow(uid).catch(err => logger.error('sync.startup', err)));
-```
-
-fire-and-forget,与现有 KB/search/marketplace reconcile 同列。UI 通过 push 事件感知进度。
-
-### 4.7 COS 访问通道:STS 直传(批次 1 已决议)
-
-- 新依赖:`cos-nodejs-sdk-v5`(已确认加入 PC/package.json allow-list)
-- 流程:PC → `POST /sync/sts`(带 `user_id` + `session_id` 头部,走现有 `check_login`)→ Server 从 SessionMgr 校验得到的 `user_id` 构造 scope 严格锁死 `<oauth_user_id>/*` 的临时凭据(1h)→ PC 用 SDK 直接 PUT/GET/DELETE
-- **安全核心**:scope 来源**只能**是 SessionMgr 校验后的 `user_id`,**禁止**信任请求参数里传入的 uid / user_id
-- Server 只保留三件事:发 STS、守 manifest CAS commit、配额计账
-- manifest.json 的 PUT/DELETE **必须**走 Server 端点(保证 CAS 与计账的原子性),其余对象 PC 直发
-- **marketplace 上传维持 server-proxy**(批次 1 已决议;与 sync 通道分离)
-
-### 4.8 配额(批次 4 已决议)
-
-- DB:`user_sync_usage(user_id PK, bytes BIGINT, quota BIGINT, updated_at)`;PK 是 OAuth `user_id`
-- 默认 `quota = 5 GB`(从 profile `sync_quota_default_bytes` 读,可 per-row override,未来对接会员等级)
-- 每次 `commit` 计算 push 集的 net size delta = `sum(add) - sum(del) - sum(modify_size_diff)`
-- **判定规则**(批次 4 决议):
- - `delta ≤ 0` → 允许(删除 / 等大修改 / 缩小修改放行)
- - `delta > 0 && used + delta > quota` → 拒绝,返回 `{ok:false, error:"QUOTA_EXCEEDED", delta, used, quota}`
- - `0 < delta && used + delta ≤ quota` → 允许并更新 `used`
-- **pull 永远允许**,不查配额
-- 软提醒 80% → manifest commit 成功响应附带 `warn: "QUOTA_NEAR_FULL"`,PC 端进侧边栏 dot(无 toast,批次 6 决议)
-- manifest.json 自身大小计入 `used`;tombstones 不计(30 天后自清)
-- **`used` 和 entries 的 `size` 都按"实际存到 COS 的字节"算**(压缩后字节,不是明文大小)——批次 8 决议。Why:资源被限制的东西(COS 存储)应该按实际占用计;不耦合压缩策略;用户压缩率高的文件类型隐性"白嫖"是合理福利
-- 设置页:配额满时展开「占用 Top 10」列表 + 每行「删除」按钮(v1 必做)
-
-### 4.9 设置页 UI 重构(4 tabs,批次 6 决议)
-
-**整体改造**:把现有滚动式 `#panel-settings` 拆成 4 tab 容器。tab 切换视觉复用 `.marketplace-tabs` / `.marketplace-tab` 原语(`index.html:368` 已有;遵 PC/CLAUDE.md 「Reuse UI components」)。
-
-**4 tabs**(中文标签按用户指定顺序):
-
-| Tab | i18n key | 包含的卡片(已有 + 新) |
-|---|---|---|
-| 账号 | `settings.tab.account` | Account(既有 `#settings-account-group`) |
-| 数据 | `settings.tab.data` | **Sync 卡片(新)** + Data root(既有)+ Clear all conversations(既有)|
-| 通用 | `settings.tab.general` | Language / Commander avatar / Local Execution / Metacognition(全部既有) |
-| 配置 | `settings.tab.credentials` (en="Credentials") | Models & credentials + Search API Key + Image API Key(既有 sections 合并) |
-
-**触点**:
-- `index.html#panel-settings`:包 `.settings-tabs` + 4 个 `.settings-tab-pane`;现有 4 个 `.settings-section-head` 改造成 tab pane(账号 tab 内不需 section-head 因为只有一个卡片)
-- 新增 CSS:复用 `.marketplace-tabs` 配色 / 间距;新 `.has-dot::after` 圆点
-- `modules/settings.js`:tab 切换逻辑 + **按 tab 懒加载**(不要进设置页就刷全部状态——现 `loadSettings()` 并行刷 7+ 个状态是浪费)
-- i18n key 新增 `settings.tab.{account,data,general,credentials}`
-
-#### Sync 卡片内容(数据 tab 内部,从上到下)
-
-1. **整体状态徽章** + **上次同步时间**("5 分钟前",hover 显示绝对 UTC)+ **「立即同步」按钮**(loading 态由 `sync.progress` push 驱动)
-2. **配额条** `12.4 MB / 5 GB`(≥ 80% 黄、≥ 95% 红)
-3. **同步中实时刷新**:阶段(pull / push / commit)+ 进度(`上传 3/8 · 下载 1/5`)+ 当前文件路径(截断显示)
-4. **异常态展开**:
- - error → 错误详情 + "查看日志"链接(打开 `data/logs/<today>.log`)
- - quota_full → 「占用 Top 10」列表 + 每行「删除」(批次 4 决议)
- - login_required → "重新登录" CTA
-5. **冲突记录**(可折叠面板,标题带计数 `冲突记录 (3)`):最近 30 天列表,每条 `时间 / path / [恢复此版本] [忽略]`(批次 4 决议)
-6. **隐私说明**:i18n key `settings.sync_privacy_note`,文案 "数据通过加密通道(HTTPS)上传到私有云存储,仅你的账号可访问"(批次 3 决议,**不写"端到端加密"**)
-
-#### 通知策略(批次 6 决议:完全去 toast)
-
-事件 → 圆点级别映射:
-
-| 事件 | 级别 | 显示在 |
-|---|---|---|
-| 同步中 / 成功 / 首次失败 | 无 | 卡片内 |
-| 同步连续失败 ≥ 3 次 | 橙 | 侧边栏 dot + 数据 tab dot |
-| 网络断开 | 无 | 卡片内 "⏸ 离线" |
-| 登录失效 | 红 | 侧边栏 dot + 账号 tab dot |
-| 配额 ≥ 80% | 橙 | 侧边栏 dot + 数据 tab dot |
-| 配额满(push 拒)| 红 | 侧边栏 dot + 数据 tab dot |
-| 新冲突写入 conflicts/ | 橙 | 侧边栏 dot + 数据 tab dot |
-
-实施:新 module `modules/sidebar-status.js`——订阅 `sync.subscribeStatus` + `account:changed` push,聚合后决定侧边栏 settings 按钮的 dot 颜色(红 > 橙 > 无)。
-
-**v1 已知弱点**:用户在 agent / project 编辑页改了内容、被另一设备覆盖——当下没 toast 提示,要等他看到圆点进设置才发现。v1 接受这个 trade-off;v1.x 视反馈再加内联 ribbon「此版本已被其他设备覆盖 · [还原]」。
-
-#### OrkasOpen 行为
-
-- **账号 tab 整体 strip**(与 `#settings-account-group` 同进退)
-- **数据 tab 内 sync 卡片 strip**(gate `typeof window.orkas?.sync !== 'undefined'`)
-- OrkasOpen 用户看到 **3 tabs**:数据(只剩 data root + clear convs)/ 通用 / 配置
-- `sidebar-status.js` 在 OrkasOpen 下整体无效(永远不 dot),可一并 strip
-
-#### 同步触发时机(汇总,批次 6 补全)
-
-| # | 时机 | 行为 |
-|---|---|---|
-| 1 | **应用启动** | `setImmediate` 触发首次 sync(pull-first),与 marketplace_reconcile 同列 |
-| 2 | **运行中写入** | features emit `dirty(domain, rel_path)` → 按域 debounce → 到点合并;两次自动 sync 间至少 30s |
-| 3 | **应用退出** `before-quit` | 强制 flush pending |
-| 4 | **用户点「立即同步」** | 立即触发 full sync,跳过 debounce |
-| 5 | **登入 OAuth** | init engine + 首次 full pull(新设备场景) |
-| 6 | **登出 / session 失效** | teardown engine,pending 保留 |
-| 7 | **切 OAuth user_id** | teardown 旧 → 清 `local/sync/` → 按新 user 重建 |
-| 8 | **从后台回前台**(browserWindow `focus` / `activate`) | 距上次成功 sync > 5min 时触发一次轻量 sync(HEAD manifest,generation 变了才走完整 sync) |
-| 9 | **网络恢复**(`navigator.onLine = true`) | 重试 pending_uploads(指数退避:30s / 1min / 2min / 5min 封顶) |
-| 10 | **配额释放后**(用户删大文件) | 通过 #2 dirty 路径自然重试(删除的 commit 刷新 used,下个 push 不再 QUOTA_EXCEEDED)|
-
-### 4.10 删除 / 登录态变化
-
-- 任何 `cloud/` 下删除操作必须经 sync engine 记墓碑(features 层直接 unlink 是 bug;要在 §6 里硬约束)
-- **登录/登出/账号切换**——监听 `account:changed` push 事件:
- - 登入(首次拿到 OAuth `user_id`):初始化 sync engine、生成或读取 `device_id`、调度首次 full pull
- - 登出 / session 失效:立即 teardown engine、停所有 in-flight、`local/sync/state.json` 保留(便于下次同账号登入续传),但 `pending_uploads` 不再触发
- - 切到另一个 OAuth `user_id`:先 teardown 旧 engine → 清 `local/sync/`(不同 OAuth user 的本地索引不能复用)→ 按新 user_id 初始化
-- **本地切 active uid**(`features/users.ts::activateUser` 切 8-digit uid,常见场景:同机两个本地 profile):teardown 当前 engine,新 uid 启动后再走「初始化 or 续传」分支
-- **未登录态下不启动 sync**(无 OAuth user_id 没有云端 scope;UI 侧 sync 卡片显示"登录以启用",登录后再启)
-
-### 4.11 传输优化与增量同步(批次 8 决议)
-
-#### 压缩(单文件 gzip,BYO encoding 模式)
-
-- **谁压**:PC 端 upload 前自己 gzip,download 后自己解;COS 完全不感知压缩、永远不解压
-- **协议层**:上传**不设** `Content-Encoding: gzip` 头(否则 cos-nodejs-sdk-v5 会自动解压,PC 端拿不到压缩字节);Content-Type 设 `application/gzip`;附加自定义元数据 `x-cos-meta-compressed: gzip` 给 COS 控制台一个可见提示
-- **白名单**(按扩展名匹配):`.jsonl`、`.json`、`.md`、`.txt`、`.csv`、`.log`
-- **大小阈值**:明文 > 4 KB 才压(更小的压缩 metadata 开销不划算)
-- **黑名单**(永不压):`.jpg / .jpeg / .png / .webp / .gif / .mp4 / .webm / .mov / .pdf / .docx / .xlsx / .pptx / .zip / .gz / .br`
-- **sha256 算明文**(跨设备一致性可靠;gzip 输出受压缩级别 / 库版本影响不完全确定)
-- **`size` 算压缩后字节**(COS 实际占用,与配额对齐 —— 批次 8 决议)
-- **路径不加 `.gz` 后缀**(COS path 与本地 rel_path 一对一镜像,压缩状态由 manifest `compressed` 字段标)
-
-#### 不做 bundle 压缩
-不把目录打 zip 上传(如把整个 `agents/<aid>/` 打包)。Why:破坏 manifest per-file diff 模型——改一个文件要重打整 bundle 重传,增量同步退化成 bundle 级。
-
-#### 大文件 multipart 上传 + 续传
-- > 5 MB 文件自动走 cos-nodejs-sdk-v5 的 multipart API(SDK 内置)
-- **续传状态**进 `local/sync/state.json::pending_uploads[]`,每条 `{rel_path, sha256, upload_id, part_etags[], completed_parts, total_parts}`
-- 中断(网络 / 应用退出 / 配额暂时满)→ 下次 sync 从 `completed_parts` 之后继续;超过 7 天的 upload_id 视作失效,从头来过
-- 并发:chat_attachments 域单独限并发 2(避免一台机器猛传堵住整个 sync pass),其他域并发 5
-
-#### 批量操作
-- **删除**走 COS `DeleteMultipleObjects`,每批 ≤ 1000 个对象(COS API 上限)
-- 多文件 push 用 SDK 内置 sliced upload,复用 HTTPS 连接
-
-#### Rename 优化(v1 必做)
-- `local_index.ts` 同时维护 `path → entry` 和 `sha → [paths]` 两个索引
-- diff 阶段:
- - `need_pull` 文件的 sha 已存在本地另一 path → 本地 `fs.copyFile` 即可,**不下载**
- - `need_push` 文件的 sha 已存在远端另一 path → 调 `PutObjectCopy`(COS 服务端内部 copy,**不消耗 PC 上下行带宽**)+ 之后正常 delete old
-- 典型场景:用户重命名 agent / 移动 contexts 文档
-
-#### 不做 byte-level / chunk-level dedup
-- rsync 风格 rolling hash 实现复杂、COS 不原生支持、对小文件无收益,业界(Dropbox / Obsidian / OneDrive)也都不暴露
-- 整文件级粒度 + multipart 续传 + rename 优化 = 已经覆盖 v1 需要的场景
-
-#### 增量同步分三层(汇总)
-
-| 层 | 机制 | 何时跳过传输 |
-|---|---|---|
-| **L1 manifest 级** | `GET manifest.json` 带 `If-None-Match: <last_etag>` | 304 → 跳过整次 sync |
-| **L2 文件级** | manifest.entries 与 local_index 的 sha 对比 | sha 相同 → 跳过该文件传输 |
-| **L3 multipart 级** | 大文件分块上传 + 续传状态 | 已完成的 part 跳过 |
-
-#### 活跃 jsonl 整文件重传(已知开销)
-- 一条 chat jsonl 每加一条 message → 整文件 dirty → 整文件重传
-- 缓解:域级 debounce(chats 5s)把窗口内多次写并成一次传
-- v1 接受这个开销;写入 §10 风险,v1.x 看带宽用量再决定要不要做 jsonl 分片(按 message_id 范围分文件)
-
-## 5. 同步集合(明确清单)
-
-**✅ 同步(`cloud/` 下,批次 2 决议)**
-- chats(jsonl + members/state/plan + visibility/)
-- chats/{skill,agent}/<id>/chat.jsonl(编辑会话)
-- chat_attachments(全量同步,含视频 / PDF 等大文件;> 5MB 走 COS multipart 上传)
-- chat_artifacts(全量同步,硬上限 ≤ 1MB / bundle ≤ 20 文件,体量受 PC/CLAUDE.md §5 约束)
-- saved_apps(全量同步)
-- sessions
-- contexts **仅源文件**(vector.db 不同步,各设备本地 rebuild via `kb_indexer.reconcile`)
-- memory/{MEMORY.md, USER.md}
-- agents(含 meta/ + skills/,整目录)
-- skills、projects
-- marketplace/installs.json(仅清单,本地 reconcile 拉真包)
-- config/preferences.json、config/component-enabled.json
-
-**❌ 不同步(`local/` 下)**
-- config/account.json(OAuth `user_id` + `session_id` + `user_info`,machine-private)
-- config/auth-profiles.json(LLM API keys)
-- config/permissions.json、reflection-state.json、web-search-cache.json
-- biz/marketplace.json(24h TTL 缓存)
-- local/marketplace/{agents,skills}/(reconcile 时按清单从 COS 拉)
-- cache/<bucket>/(user-clearable 缓存伞)
-- search/(派生索引)
-- file_cache/、tool-results/(按 PC/CLAUDE.md §4 constraint 6 即将迁入 cache/)
-- workspace.json(机器私有,路径异机无效;批次 2 已决议)
-- test/(dev-only LLM 归档)
-- **顶层** `users.json`、`logs/`(machine-private,与 OAuth 账号无关)
-
-**`cloud/` 内 v1 跳过同步**:vector.db(只同步 `contexts/` 源文件)
-
-## 6. Change list
-
-### PC 端
-- `PC/src/main/features/sync/` 新建(engine / manifest / transport / codec / local_index / dirty_bus / merge/)
-- `PC/src/main/index.ts` 增加 startup hook + before-quit flush
-- `PC/src/main/ipc/index.ts` 注册 `sync.runNow` / `sync.status` / `sync.usage` / stream
-- `PC/src/main/features/marketplace.ts::apiBase()` 复用(同步 API 也通过它)
-- `PC/src/main/features/users.ts` 切账号路径调用 `syncFeature.teardown()`
-- 各 cloud 写入方 feature(chats、agents、skills、projects、preferences)写完后 emit `dirty()`:
- - `features/chats/*` 收尾处
- - `features/agents.ts` / `features/skills.ts`
- - `features/projects/*`
- - `features/app_config.ts`(preferences 写入处)
- - `features/marketplace.ts`(installs.json 写入处)
-- 各 cloud 删除方 feature 改走 `syncFeature.markDeleted(rel_path)` 而不是直接 unlink
-- `PC/src/renderer/modules/settings.js` **重构成 4 tab**(账号 / 数据 / 通用 / 配置),按 tab 懒加载状态;数据 tab 内新增 sync 卡片(gate `typeof window.orkas?.sync !== 'undefined'`)
-- `PC/src/renderer/index.html#panel-settings` 整体改造:`.settings-tabs` + 4 个 `.settings-tab-pane`
-- `PC/src/renderer/styles.css`(或对应文件):复用 `.marketplace-tabs` 视觉,新增 `.has-dot::after` 圆点
-- 新模块 `PC/src/renderer/modules/sidebar-status.js`:聚合 sync + account 状态决定侧边栏 dot
-- `PC/src/renderer/locales/{zh,en}.json` 加 sync 相关字串(key 前缀 `settings.sync_*`)+ 4 个 tab 标签 key(`settings.tab.{account,data,general,credentials}`)
-- `PC/package.json` 新增 `cos-nodejs-sdk-v5`(批次 1 已确认)
-- `features/account/` 订阅点:监听 OAuth 登录/登出/切账号,分别触发 sync engine 的 init / teardown / reset
-- `OpenSource/SyncCode/strip-rules.json` 增加整套 sync 的剥离规则(见 §9)
-
-### Server 端
-- `Server/api/sync.py` 新建(sts / manifest commit / usage 三端点)
-- `Server/biz/sync/quota.py` 新建(计账 + 阈值)
-- `Server/biz/sync/sts.py` 新建(COS STS 临时凭据签发,scope 强约束)
-- `Server/utils/store/file_store.py` 复用 / 扩展(不动现有接口)
-- DB migration:新表 `user_sync_usage`
-- `Server/conf/cn.conf` 增加 `sync_quota_default_bytes`、`sync_sts_duration_seconds`、`sync_conflict_retention_days`(批次 7 决议)
-
-### Profile / 部署
-- COS bucket lifecycle 规则:`tombstones/*` 30d 过期
-- COS bucket policy:默认 private(已有)
-- CAM 子账号 / 角色:sync STS 所用主账号需有 sts:GetFederationToken 权限
-
-## 7. 待决策项(按批次推进)
-
-> ✅ = 已决议(见 §0 决议日志);🟡 = 当前 / 下一批;⚪ = 待批次。
-
-- ✅ **批次 1** — STS 直传 / 新依赖 / marketplace 通道分离(见 §0)
-- ✅ **批次 2** — vector.db 不同步 / 附件三家全同步 / workspace.json 不同步(见 §0)
-- ✅ **批次 3** — v1 不做应用层加密,靠 STS + private + SSE-COS;取消 codec 抽象;UI 加诚实隐私说明(见 §0)
-- ✅ **批次 4** — 配额 5 GB(按 size delta 判定)/ 配额满时 Top 10 释放 UI / 冲突 UX = toast + 历史列表 + 可恢复(见 §0)
-- 🟡 **批次 5 — 实施保障**
- - 7.9 **冲突合并器单测**:jsonl append / mutable json 合并器是「文本处理 / 解析」类代码,按 PC/CLAUDE.md §9 "Hard rule for LLM-output text munging" 必须配 fixture 单测(set A 真实命中 + set B 似是而非不命中)。
- - 7.10 **CLAUDE.md 同步**:本方案落地后需同步以下条目(见 §9),先确认表述。
-
-## 8. Verification
-
-实施后需通过:
-- **单测**:
- - `merge/jsonl_append.ts` — 双侧追加新 id 消息(union)、**双侧改同 id(冲突 → 留底 + 较晚胜出)**、空文件 / 末行无换行 fixture(批次 7 决议要求覆盖留底分支)
- - `merge/mutable_json.ts` — 双侧 _v 同 / 异、schema_v 倒置拒绝覆盖、墓碑场景
- - `manifest.ts` — diff 三集计算、CAS 冲突重试、**rename 检测**(sha 反查命中本地 copy / 远端 PutObjectCopy 分支,批次 8)
- - `transport.ts` — gzip 白名单 / 阈值 / 黑名单决策、压缩字节与明文 sha 一致性(批次 8)
- - `dirty_bus.ts` — debounce 合并、强制 flush 优先
-- **集成测**:
- - 起两个临时数据根(模拟 A/B 设备),共享同一伪 COS(local fs mock)
- - 场景:单边写入 → 另一边 pull、双边并发 → CAS 冲突、删除 → 墓碑 → 另一边删本地
- - 配额硬阻断场景
-- **手工验证**:
- - 真实双设备 Mac + Win 同账号登录,跑一遍:聊天、改 agent、删聊天、配额接近上限
- - 验证 `session_id` / API key / `account.json` 内容**永远没**出现在云端任何对象里(list bucket + grep STS 直传日志)
- - OrkasOpen 构建:sync 模块整体被 strip 干净(不存在 `features/sync/`、preload 无 `sync` 命名空间、settings 页无 sync 卡片)
-- **回归**:
- - 现有 KB reconcile、marketplace reconcile、search reconcile 行为不变
- - dev 包与 packaged 包行为一致(CLAUDE.md「OrkasOpen has no dev-vs-prod behavior split」)
-
-## 9. CLAUDE.md / strip-rules 同步项
-
-实施后需同步:
-
-### PC/CLAUDE.md
-- §1 npm allow-list 增加 `cos-nodejs-sdk-v5`
-- §4「数据同步域」修订:
- - **COS 前缀 = OAuth `user_id`**(不是本地 8-digit `uid`);本地 `<container>/data/<uid>/cloud/` ↔ 云端 `orkas-user-data/<oauth_user_id>/cloud/` 一对一镜像
- - vector.db 策略改写——**待批次 2 决议**:若决「不同步」,需明确撤销当前 constraint 5 的 "KB vector store is part of cloud sync",改成「只同步 `contexts/` 源文件,vector.db 每设备本地 rebuild via `kb_indexer.reconcile`」
- - `cloud/` 下任何删除**必须**经 `syncFeature.markDeleted(rel_path)`,禁止 features 层直接 unlink(否则会被其他设备复活)
-- 新增「§N sync 引擎」一节:
- - manifest 是云端真值,generation 单调;客户端 mtime 仅辅助
- - `local/sync/` 结构 + 永不上云
- - 按域 debounce 表(防止有人到处加 dirty 调用而不知道频控位置)
- - schema_v 防降级语义
- - device_id 在 sync engine 首启时生成,存 `state.json`,仅作排障字段
-- §9「Don't do」追加:禁止在 sync engine 外读写 manifest.json;禁止把 OAuth `user_id` 当作本地路径段;禁止用 8-digit 本地 uid 做 COS scope
-
-### Server/CLAUDE.md
-- §3 追加:`/sync/*` 全部端点必须经 `utils/auth.py::check_login`;STS scope **只能**从 SessionMgr 校验后的 `user_id` 推导,禁止信请求参数
-- `/sync/manifest/commit` 是 manifest 唯一写入口,CAS + 配额计账原子
-
-### OrkasOpen strip-rules(`OpenSource/SyncCode/strip-rules.json`)
-- 与 `features/account/` 同进退——整个 `features/sync/` 目录、`ipc/sync.ts`(若拆出)、`renderer/modules/sync*.js`、`renderer/modules/sidebar-status.js`、`renderer/locales/{zh,en}.json` 里 `settings.sync_*` 键、`#settings-sync-group` 块、`window.orkas.sync` 命名空间——全部加入 strip 名单
-- 数据 tab 内的 sync 卡片用 `typeof window.orkas?.sync !== 'undefined'` gate(与 `marketplace_dev` 的 `typeof openMarketplaceUpload === 'function'` 同模式),避免 sync strip 后还要手改 renderer
-- 账号 tab:与既有 `#settings-account-group` 的 strip 同步——账号 tab 整体在 OrkasOpen 不显示(4 tabs → 3 tabs);tab 切换 JS 要能优雅跳过被 strip 的 tab(不报错不空白)
-- 新依赖 `cos-nodejs-sdk-v5` 仅在主仓使用;OrkasOpen 不安装(package.json 同步流程会自然过滤)
-
-### 日志 / 遥测(PC/CLAUDE.md §10)
-- sync engine 使用 `createLogger('sync')` + 子 scope(`sync:engine` / `sync:transport` / `sync:manifest` / `sync:merge`)
-- 关键节点 `log.info`(startup 同步开始 / 单次 sync 起止 / 文件数 / 用时 ms)
-- 失败必 `log.warn`(可恢复,如网络抖动)或 `log.error`(不变量违例,如 CAS 反复冲突)
-- Umami 事件可记 `sync_started` / `sync_completed` / `sync_failed`(data 只放计数与耗时,**绝不**含 path / cid / 文件内容)
-
-## 10. 风险与未尽事项
-
-- **首登耗时**:新设备首次同步可能下载几百 MB ~ 数 GB 附件 + 本地 rebuild KB 索引;需要 UI 明确分段进度(聊天文本 / 附件 / KB rebuild)而非"卡住"假象
-- **附件大小爆炸(批次 2 已知风险)**:附件三家全同步,单条视频可能 GB 级。配额(批次 4)必须早设硬上限;engine 必须支持 multipart 续传、并对 chat_attachments 用更窄的并发(避免一台机器猛上传把整个 sync 堵住);超配额时 push 端点返回 `QUOTA_EXCEEDED`,UI 引导用户「删大附件」或「升级配额(未来)」
-- **CAS 雪崩**:极端场景多个设备同时频繁 commit → 退避策略要好;v1 简单线性退避 + 拉抖动
-- **活跃 jsonl 整文件重传**(批次 8 已知开销):当前没做 jsonl 尾部分片协议(COS 无原生 append),每次新消息整文件重传。靠域级 debounce(chats 5s)缓解。v1.x 若带宽问题严重,考虑按 message_id 范围分片(如 1000 条一片),新片不影响旧片
-- **压缩库版本漂移**:不同 Node 版本的 zlib 输出可能略有差异(同明文压出来字节级不同)→ sha 必须算明文(已锁),否则跨设备验证会假阳性。Node 自带 zlib 跨版本相对稳定,可接受
-- **device_id 与隐私**:manifest 暴露 `last_writer_device_id` 给同账号其他设备;这是同账号自己的设备,可接受,但不要把它写进日志/上报
-- **时区与"上次同步时间"显示**:用 UTC 存,渲染层按 OS locale 显示,沿用现有 i18n
-- **多 active user(CLAUDE.md 说"framework-ready but not yet shipped")**:v1 仍按单 active user 设计,但 sync engine 实例按 OAuth `user_id` 创建/销毁,避免后续重写
-- **session 过期 → 同步中断**:`/sync/sts` 返回 401 → engine 暂停、UI 提示重新登录、`pending_uploads` 保留待恢复
-- **本地 uid ↔ OAuth user_id 多对一**:同一 OAuth 账号在两台机器各有独立本地 uid;teardown 时清的是 `<local_uid>/local/sync/`,不会误删另一台
-- **未登录态写入**:登录前的本地修改在登入后能否一次性 push 上去——v1 行为是「能」(首次 sync 把当前 `cloud/` 内容当作待 push),但要在 UI 上明示「首次同步可能将本机数据视为云端真值」,避免新设备误用旧机操作
-- **v2 加密带破坏性变更(批次 3 决议遗留)**:若 v2 要上 E2EE,所有现存对象需重新加密 + manifest 字段扩 `cipher/iv`;老客户端拉到密文版本将无法解读。届时必须:(a) 锁老版本不能再写、(b) 服务端做全量重密迁移、(c) 提供"丢失密钥 = 丢失数据"的明示同意 UX。**v1 不预埋 codec 抽象的代价就是 v2 这一刀;预估收益(v1 简化)> 成本(v2 一次性迁移)**。