Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
Desktop 多账号数据库与数据所有权架构
状态:架构基线(先梳理,不代表多账号功能已实现) 范围:Desktop 本地数据、SQLite、凭证命名空间、Profile 生命周期与运行时隔离。 跟踪 Issue:#1266 当前结论:本阶段不新增业务功能,不批量给现有业务表增加
owner_id,也不直接写 migration;先冻结所有权边界,再按后续实现需要追加最小迁移。
1. 结论先行
未来多账号采用 一个账号一个 Profile、一个 Profile 一份 Profile DB、一个 Profile 一个 独立运行时 的模型。
- Profile 是内部隔离边界,用户界面可以只称为“账号”。
- Profile 代表一个稳定的 Data Owner / membership,不代表一次登录窗口,也不等同于
region。 - Profile DB 内的业务表天然属于该 Profile,因此不需要在每张表重复保存
owner_id。 - 同一 Profile 的第二次启动只聚焦或复用已有运行时;同一账号不允许在两个 Profile 运行时中同时作为 active owner。
- 多个账号同时运行通过多个 Profile 运行时完成,不通过一个主进程切换多个全局单例。
- CN / Global 仍是构建期固定维度,不能作为多账号隔离键,也不能变成用户可选项。
这意味着当前最重要的工作不是改表,而是把“数据库文件、数据库之外的持久化文件、凭证、 运行时租约”归到同一套 Profile 边界下。
2. 术语与边界
| 术语 | 含义 | 不是它 |
|---|---|---|
| Machine | 当前安装、当前 userData 根目录对应的一台机器 / 一个本地安装 |
账号、组织或服务器 membership |
| Profile | 本地稳定的账号容器;持有一个 Data Owner 的本地数据、配置与凭证命名空间 | 一次窗口、一个 renderer、一个登录请求 |
| Data Owner | 服务端确认的 membership / owner id;用于服务端权限和数据归属 | profileId,也不应直接作为文件名 |
| Profile DB | 一个 Profile 的 SQLite 数据库,包含该 Profile 的业务数据 | 机器级缓存或机器注册表 |
| Runtime Lease | 防止同一 Profile 被多个进程同时运行的短期租约 | 任务历史、消息或账号配置 |
| Machine Registry | 登录前即可读取的 Profile 目录与运行时协调控制面 | refresh token、业务消息 |
profileId 是本地生成的 opaque id;dataOwnerId 是服务端身份。两者必须分开,避免
“重新登录同一账号”“membership 变化”“本地 Profile 重命名”互相改写文件路径。
3. 现状盘点
当前 Desktop 已经是“按账号分数据库文件”的模型:
<userData>/<dbFilePrefix>-<userId>.db
localDb/index.ts、localDb/client/current.ts、authManager.ts、Scheduler、Maker、
IM、Device Link 等仍是模块级单例。切账号时是 teardown 旧 owner,再打开新 DB,而不是
同一进程同时拥有多个数据库上下文。
数据库以外已经存在一部分 owner 命名空间:
<userData>/owners/<hash(dataOwnerId)>/...
但仍有一些持久化路径直接落在 <userData> 根目录,例如历史 auth session、部分
Device Link 设置、layout / provider runtime 文件、媒体字节仓和旧集成缓存。它们与 SQLite
按账号分文件的语义并不完全一致,这正是未来多账号最容易串号的地方。
4. 目标分层
4.1 Machine Registry:独立小型 SQLite
选择独立 SQLite,而不是 JSON,原因是未来会同时有多个 Profile 进程,需要原子地完成:
- Profile 创建、删除、默认 Profile 与最近打开时间更新;
- 同一账号去重;
- 启动前抢占 / 释放 Profile Runtime Lease;
- 崩溃后的过期租约接管;
- 多进程并发写入不丢字段。
建议路径:
<userData>/profile-registry.sqlite
建议逻辑表(不是本阶段要直接创建的 schema):
profiles
profile_id TEXT PRIMARY KEY -- 本地 opaque UUID
data_owner_id TEXT -- cloud membership;local 模式使用 `local-v1`
auth_realm TEXT -- 观测到的 auth realm,仅用于校验/诊断
display_name TEXT NOT NULL
status TEXT NOT NULL -- active / signed_out / needs_login / deleting
storage_mode TEXT NOT NULL -- legacy_user_db / profile_dir
legacy_user_id TEXT -- 兼容旧 <prefix>-<userId>.db,迁完可为空
created_at INTEGER NOT NULL
last_opened_at INTEGER
last_verified_at INTEGER
profile_runtime_leases
profile_id TEXT PRIMARY KEY
lease_id TEXT NOT NULL
pid INTEGER NOT NULL
started_at INTEGER NOT NULL
heartbeat_at INTEGER NOT NULL
machine_meta
key TEXT PRIMARY KEY
value TEXT
约束:
- cloud Profile 对
(auth_realm, data_owner_id)建唯一约束,保证一个账号只有一个本地 Profile;local Profile 使用固定的LOCAL_DATA_OWNER_ID语义。 - Registry 不存 access token、refresh token、OAuth code、API key 或私钥。
- 不存任意用户可控绝对路径;Profile DB 路径由
profile_id派生,旧库路径只通过storage_mode + legacy_user_id兼容。 auth_realm不是账号隔离键,更不是用户可修改的区域选择;它只用于阻止跨 realm 误用凭证和帮助诊断。
4.2 Profile DB:默认保持一库一 Profile
目标路径:
<userData>/profiles/<profileId>/profile.db
在兼容阶段,已有库可以继续使用:
<userData>/<dbFilePrefix>-<legacyUserId>.db
Registry 将该文件登记为一个 Profile 的 legacy storage,不在首次迁移时复制或重写大库。
新建的 Profile 使用 profiles/<profileId>/profile.db;旧 Profile 后续可单独做可回滚的
物理搬迁。
Profile DB 的规则:
- 业务表默认都属于当前 Profile,不加重复的
owner_id。 - 表间 FK 继续在同一 DB 内表达,删除和事务语义不改变。
- 跨 Profile 的导入 / 分享必须通过显式 envelope 携带来源 Profile 与授权信息,不能 直接把一张业务表当作跨账号共享表。
DbClient必须绑定profileId/ scope key;未绑定 Profile 的查询 fail closed。- DB 内的
migration_meta、migration_history仍是该 DB 的 schema 控制面,不搬到业务 表,也不承担 Machine Registry 的职责。
跨账号实时协作不是 Profile DB 的隐式能力。未来若需要账号 A 与账号 B 共同访问同一个 任务,应单独建立 Shared Workspace / Shared Task 层和 ACL;Profile DB 只保存私有数据或 受控镜像,不能因为两个账号在同一台机器上就自动互相可见。
4.3 Runtime / Lease State:与业务数据分开
同一 Profile 的多个进程必须有单一 active runtime。Runtime Lease 位于 Machine Registry
或等价的机器级 broker 中,按 profile_id CAS + heartbeat 处理;它不应与 sessions、
messages 等业务表混在一起。
现有 device_link_ownership 的行为仍然需要保留,但目标是把它看成 Profile Runtime Lease,
而不是账号业务数据:
- 旧库阶段可以继续使用该表完成兼容仲裁;
- 新架构由
profile_runtime_leases统一承载; - Lease 失效只影响进程 / Device Link 连接,不删除 Profile 数据;
- 不同账号的 Profile 不共享同一行,也不互相顶号。
4.4 Machine Shared Cache:默认不承载用户内容
机器级缓存可以共享 agent 二进制、模型下载、插件包和明确可再生的公开缓存,但必须满足:
- 缓存本身不表达账号归属;
- 任何用户内容的归属由 Profile DB ledger / refs 表达;
- 没有 Profile 授权时,缓存命中不能直接成为可读权限;
- 共享缓存不能绕过现有安全协议与内容授权。
第一阶段不把私人媒体字节做跨 Profile 共享。这样可以保持媒体读取与 Profile DB 的权限 一致,避免“知道 hash 就能读取另一个账号媒体”的隐患。需要共享媒体时,另建机器级 cache ledger 和授权协议,不把它作为本次数据库改造的顺手优化。
5. Ownership Matrix
“是否需要 owner_id”按目标架构回答,不按当前文件布局回答:Profile DB 本身已经是
owner 边界,所以大多数行答案是“否”。
| 表 / 虚表 | 当前归属 | 目标归属 | owner_id 列 |
后续迁移 |
|---|---|---|---|---|
sessions |
当前账号 DB | Profile DB | 否 | 无 schema 迁移 |
messages / messages_fts |
当前账号 DB | Profile DB | 否 | 无 schema 迁移 |
session_pr_refs |
当前账号 DB | Profile DB | 否 | 无 schema 迁移 |
session_goals |
当前账号 DB | Profile DB | 否 | 无 schema 迁移 |
orca_teams / orca_workers / orca_worker_creation_reservations |
当前账号 DB | Profile DB | 否 | 无 schema 迁移 |
schedules / schedule_runs |
当前账号 DB | Profile DB | 否 | 无 schema 迁移 |
im_bindings |
当前账号 DB | Profile DB | 否 | 无 schema 迁移 |
wechat_sync_state / wechat_inbox / wechat_outbox / wechat_file_attachments |
当前账号 DB | Profile DB | 否 | 无 schema 迁移;凭证与 staging 路径需按 Profile 收口 |
recent_workdirs / project_aliases / project_automation_consents |
当前账号 DB | Profile DB | 否 | 无 schema 迁移 |
right_sidebar_tabs / agent_input_queue_snapshots |
当前账号 DB | Profile DB | 否 | 无 schema 迁移 |
account_usage_snapshots / daily_spend / daily_model_usage |
当前账号 DB | Profile DB | 否 | 无 schema 迁移 |
embedding_jobs / embedding_meta / vec_table_meta / chat_messages_vec_v1 |
当前账号 DB | Profile DB | 否 | 无 schema 迁移 |
skill_usage_sources / skill_usage_exposures |
当前账号 DB | Profile DB | 否 | 无 schema 迁移;raw transcript 路径必须按 Profile 可解析 |
custom_providers / custom_mcp_servers |
当前账号 DB | Profile DB | 否 | 无 schema 迁移;secret key 迁到 Profile namespace |
media_refs |
当前账号 DB | Profile DB | 否 | 保持 ledger 语义;路径与协议改造另行设计 |
media_blobs |
当前账号 DB 元数据;字节仓当前落在 userData 根下 | Profile DB 元数据 + Profile 私有媒体仓 | 否 | 需要单独的媒体路径兼容迁移,不能直接共享现有根目录 |
ghost_cards |
当前账号 DB | Profile DB | 否 | 无 schema 迁移 |
hook_group_messages |
当前账号 DB | Profile DB | 否 | 无 schema 迁移;hook 连接配置需按 Profile 收口 |
device_link_ownership |
当前账号 DB 中的单行运行时仲裁 | Runtime Lease(按 Profile) | 否 | 后续把租约抽到 Registry / broker;旧表兼容期保留 |
migration_meta / migration_history |
当前账号 DB 控制面 | 各 Profile DB 控制面 | 否 | 保持现有 append-only 规则 |
5.1 特殊边界
媒体
mediaBlobs 是内容寻址元数据,mediaRefs 是归属与生命周期账本。当前物理字节在
<userData>/cindy-media,这在多 Profile 下不应继续作为默认写入位置。第一阶段目标是
把字节仓也放进 Profile 私有目录;内容寻址仍可在同一 Profile 内去重。跨 Profile 共享
字节属于另一个“机器缓存 + 授权 ledger”问题,不能只把 mediaBlobs 搬到共享 DB。
Device Link
Device Link 的 relay 身份和本地授权都跟 Profile / Data Owner 绑定。device_link_ownership
不是消息数据;它的长期归属是 Runtime Lease。即使多个账号并行运行,也只能在各自 Profile
范围内仲裁,不应使用一个全局单行表把不同账号串在一起。
Embedding
embedding job 的 source_id 通常指向 message / document 等 Profile 内容;向量表和
元信息也必须跟随 Profile。机器级模型缓存可以共享,但向量结果不能共享为无 owner 的全局
数据。
Provider / MCP
custom_providers 与 custom_mcp_servers 继续只保存非秘密配置;API key、OAuth 凭证、
MCP token 仍走 safeStorage。未来 safeStorage 的物理 key 应以 profileId 命名空间隔离,
并通过兼容映射读取现有 dataOwnerId 命名空间,不能要求用户重新填写密钥。
6. 数据库之外的必须同步收口项
这部分不是本阶段的实现,但它决定多账号是否真正安全:
| 当前形态 | 目标 | 备注 |
|---|---|---|
| auth refresh session / realm 在 userData 根目录 | Registry 只保存 Profile 元数据;凭证落 safeStorage 的 Profile namespace | 不因新 Profile 覆盖旧 Profile token |
owners/<hash(dataOwnerId)> |
profiles/<profileId>/... 为 canonical;旧 owner 路径作为迁移 alias |
保留 dataOwnerId 作为服务端身份 |
device-link-settings.json 根目录 |
每个 Profile 一份;机器级偏好与账号授权拆开 | keepAwake 这类机器偏好可另留 Machine 层 |
cindy-media/ 根目录 |
Profile 私有媒体仓;可再生共享缓存另行设计 | 不能让 hash 直接跨 Profile 可读 |
| layout / provider runtime / hook / IM 辅助文件 | 按其语义明确标为 Profile 或 Machine | 不能因为“只是 JSON”就默认共享 |
| Agent / model / plugin 下载缓存 | Machine Shared Cache | 缓存命中不等于账号授权 |
此外,跨物理设备的“互相登出”不由本地 Profile DB 单独解决。服务端需要按设备 / 登录会话 维护独立 refresh-token family;普通 logout 只撤销当前 family,“退出所有设备”才撤销全部 family。客户端收到当前 family 失效时,只清理当前 Profile。
7. Legacy 兼容迁移顺序
迁移必须先建立边界,再搬数据;不做“一次性把所有文件移动到新目录”的大迁移。
- 引入 Registry(不动现有 Profile DB):首次成功验证已有 refresh session 后,创建
一个 Profile 记录,绑定
dataOwnerId,并把现有<prefix>-<userId>.db登记为legacy_user_db。用户不需要重新登录。 - 统一 Profile Context:运行时从 Registry 选择 Profile,
DbClient、auth、secret store、Scheduler、Maker、IM、Device Link 全部接收同一个 Profile scope。 - 新账号走新目录:新建账号使用
profiles/<profileId>/profile.db和 Profile 私有 文件树;旧 Profile 继续读旧文件,直到对应迁移完成。 - 按模块迁移旁路存储:凭证、IM、hook、Device Link 授权、layout、媒体等逐项做 可重试、可回滚、幂等迁移;每项都保留旧路径只读兼容窗口。
- 最后再考虑物理搬迁旧 DB:确认所有运行时与备份工具都支持新路径后,才将 legacy DB 改名或移动。这个动作不是多账号上线的前置条件。
任何迁移都必须满足:
- 不丢聊天、附件、Provider 配置或已有 safeStorage 凭证;
- 不因切换 Profile 删除另一个账号的 refresh token;
- 失败可重试,重复执行不产生第二份数据;
- SQLite schema 变化仍只用 Drizzle 追加 migration,并通过
db:validate与 replay; - 未合入 migration 不连接共享 userData,使用隔离数据库验证。
8. 暂不做的事情
- 不给
sessions、messages、schedules等所有表批量加owner_id。 - 不在一个主进程中把多个账号的 DB client / Scheduler / Maker 单例强行改成多租户容器。
- 不把 CN / Global 当作 Profile 维度,也不增加用户选择区域的入口。
- 不把 refresh token、OAuth 凭证、Provider key 放入 SQLite。
- 不在本阶段新增业务功能、账号切换 UI 或多账号并行启动流程。
- 不为了“统一目录”直接移动用户现有数据库或媒体文件。
9. 验收不变量
后续实现多账号时,至少必须保持:
- 任意运行时只打开一个 Profile DB;DB client 的 scope 与 Profile Registry 选择一致。
- 同一
(auth_realm, data_owner_id)只有一个 Profile 记录。 - 同一 Profile 同时最多一个 active Runtime Lease;崩溃后只能按 heartbeat / CAS 接管。
- Profile A 的查询、凭证、媒体 URL、Device Link 事件不能在 Profile B 可见。
- 手机 / 远程控制请求必须携带并校验目标 Profile / Data Owner 路由,不能只靠当前全局
currentUser猜测。 - Profile DB 业务表继续保持无
owner_id的单 owner 语义;跨 Profile 操作必须显式授权。 - 旧用户升级后什么都不做,现有聊天、配置和凭证继续可用。
10. 本阶段交付边界
本阶段已先落下不依赖 Electron/真实用户目录的 Registry 纯模型:
apps/desktop/src/main/profile/profileRegistryModel.ts 负责 Profile 描述、账号唯一性、
旧库路径派生、Profile DB 路径派生和凭证字段 allow-list;对应测试位于
apps/desktop/src/main/profile/__tests__/profileRegistryModel.test.ts。它还不是
profile-registry.sqlite 的运行时实现,也不改变现有 localDb 打开路径。
下一步仍应为 Registry SQLite 适配器、Profile Context、Runtime Lease 和旁路文件建立单独 任务;在这些边界得到实现验证前,不应创建新的业务表或批量 migration。
11. 聊天数据投影补充(2026-10-26)
状态:优化分支已实现首批 Chat 投影,尚未发布;没有迁移全库 Profile。11.2 的完整逻辑集合仍为后续设计,当前物理表见下文。 当前路径与账号代次按 modelDefaultsProfile.ts 和 appSessionState.ts 核对;消息同步、恢复与可靠发送见 伙伴群聊 第 11 节。
11.1 账号分区
复用当前账号数据库生命周期。当前实现路径来自 ownerDatabasePath(),格式为 <userData>/<品牌前缀>-<ownerId>.db;部分其他状态位于 owners/<owner哈希>/。不得把 本文架构基线 的未来 Profile 路径描述成已经全面实现,也不为本次改造批量给所有旧表加 owner_id。
在账号库中增加 Chat namespace:可信服务端点/realm + 已验证 issuer + membership 身份映射。一个账号访问不同 Chat 服务的数据不得串用,同一房间在直连、device-link 两种路径上不得重复。deviceId 是执行地点,不能成为聊天归属主键;消息作者也不等于缓存所有者。
本轮 Desktop 的具体实现是捕获当前 owner 的 DbClient,以规范化 endpoint、服务端 /me 验证的 human actor ID 和实际 reader actor ID 的 SHA256 作为 namespace。服务端 actor 已绑定 issuer-qualified membership;客户端不自行解析未验证 JWT 来建立归属。migration 0133 新增:
| 物理表 | 主键 | 内容 |
|---|---|---|
chat_cache_rooms |
namespace + room_id | snapshot 元数据、cursor、reset generation、确切页覆盖、metadataDirty、CAS version |
chat_cache_messages |
namespace + room_id + message_id | 当前服务器消息 JSON,保留 revision、十进制 seq、tombstone 和未知内容块 |
两表由 chatCache.execute worker 事务原子读写;只更新发生变化的消息行。Desktop 与 Mobile 的单房间删除同写入一样校验 version + generation,旧实例不得删除另一实例刚提交或重建的投影;撤权清理碰到并发冲突时仍向当前调用者返回撤权错误,下次读取重新校验权限。账号退出的全量清理仍先失效实例并等待在途写入。查询范围由本地 coverage 决定,seq 用 BigInt 排序,不以 JSON 文本字符串顺序替代消息顺序。每房间最多 500 个已下载页;缺页从服务器补齐。缓存与 canonical messages、未确认发送、附件实际文件分离,reset 只清 Chat 投影。
Mobile 使用现有文件缓存后端的 cache/chat-history-v1/ 目录,以稳定 ownerId、realm、endpoint、human actor 和 roomId 的 SHA-256 作为文件名;不使用登录 generation 作为永久主键。一个房间的消息、页覆盖与游标放入同一原子替换文件,进程内按文件串行加 version + generation CAS,避免多个挂载回写旧版。正文不占用 AsyncStorage 的共享容量,不新增原生依赖。切账号和退出清理先同步撤销旧实例写权,等待在途文件操作结束后尝试删除全部文件;失败会保留待重试内容,下一次登录在激活身份前重新清理。系统回收可重建缓存后重新 bootstrap,服务器仍保存权威历史。
运行时捕获 ownerGeneration 与数据库句柄;每次跨 await 的写入、事件分发、ACK 和 outbox 执行都复核当前代次。账号切换时停止旧发送和订阅,再切换读取。generation 是运行时代次,不能写进永久主键,避免再次登录制造新库。
退出登录清除凭证并阻断读取;草稿、未确认发送等私有数据按现行账号保留/明确删除策略处理,不能为了重建缓存顺带删除。匿名/本地 Profile 不冒充服务器账号。首次账号映射或迁移有歧义时保留原库并停止关联,不能猜测合并。
11.2 推荐表/集合
下表是后续完整逻辑模型,不是本轮新增表清单或可直接执行的 migration。Desktop 与 Mobile 已共用 maker-shared/chat-history 算法、分别注入上述存储适配;未来新增原生 SQLite 依赖若触发 fingerprint 变化,仍须走 Mobile 冷更规则。
| 建议集合 | 核心字段/索引 | 用途 |
|---|---|---|
chat_namespaces |
local namespace id、可信 endpoint key、issuer、membership binding、schema version | 账号库内进一步区分服务器与身份域 |
chat_actors |
namespace + actorId;kind、资料、owner、版本/同步代次 | 群与私聊复用参与者;不强绑本机 bot_profiles |
chat_conversations |
namespace + conversationId;kind、状态、元数据版本、lastMessage、activity、summary version | 本地列表与打开入口;个人列表状态单独存 |
chat_members |
conversation + actor;role/state/historyFrom/accessRevision | 可见性和权限投影;执行时仍由服务器核验 |
chat_messages |
稳定 localId、可空 serverId、conversation、author/requester、thread/reply、content、revision、createdSeq、createdAt、deleted | 唯一 serverId;按房间/话题和顺序分页;未知块保留原数据 |
chat_message_sources |
namespace、sourceKind、sourceSessionId、sourceMessageId、partIndex、serverMessageId | 私聊镜像、长消息拆块与 canonical 主 Session 的精确映射 |
chat_reactions、chat_reads |
message + actor + emoji;conversation + actor + thread + readSeq/个人标记 | 表情与读位独立更新,不能依赖正文 revision 一起增长 |
chat_plans、chat_executions |
服务端实体 ID、revision/epoch、状态、来源消息 | 安排卡与执行状态投影;不保存其他成员私有工具明细 |
chat_media_refs |
message、server mediaId、本机引用、下载/校验状态 | 复用媒体仓;短期签名 URL 不作持久身份 |
chat_sync_scopes |
namespace + scope;durableCursor、head/floor、bootstrap/reset generation、状态 | 持久化同步进度;每个 actor/房间独立 |
chat_pending_refreshes |
scope、entity/range、目标版本/触发 cursor | 不能直接应用的变化先持久化为待补任务 |
chat_history_ranges |
conversation、thread、order kind、边界、snapshot watermark、complete/stale | 区分已下载页面、缺口与需重新校验的旧范围 |
chat_outbox |
stable clientId/operationId、immutable payload、目标身份、状态、retryAt、回执、附件引用 | 跨重启可靠发送与未知结果恢复;不随投影重建删除 |
chat_drafts、chat_view_state |
conversation/thread、草稿、滚动锚点、设备内偏好 | 切群恢复;草稿默认仅本设备,跨端草稿另行定义 |
chat_runtime_links |
conversation + companion + lane/grant → 本机 Session、执行地点 | 复用既有私聊主 Session、群主线/话题/分工 Session |
sequence/cursor 在协议上保留十进制字符串,计算不得经过不安全的 JavaScript Number;本地索引使用经过范围校验的 64 位表示,或可保持数值顺序的编码,不能直接按可变长字符串排序。原始 JSON 不足以替代分页与关联索引。
旧本地 bot_group_members.lastSeenSequence 是伙伴交付进度,不是用户已读;旧 bot_profile 外键无法代表跨账号人类成员。新模型需明确区分,不能只把旧表改名后直接作为统一 Chat 表。