multica sync is all u need

把 Codex、OpenCode 和 Claude Code 的本地工作状态同步进 Multica 看板，并在 Multica Desktop 内用一个原生页面管理同步——不需要浏览器控制台，也不需要用 Agent 承担工作区管理，因此不会污染 Agent prompt。

本项目基于 Multica 官方 v0.4.33，提供可与官方版本并行安装的 Multica Local macOS 客户端，以及一个独立运行的本地同步服务。

当前范围：首版面向 Apple Silicon Mac 和当前工作区。它不会修改 Multica Cloud 后端，也不会自动跟随官方版本升级。

这个项目解决什么问题

Codex、OpenCode 和 Claude Code 各自保存会话、状态与工作目录。项目一多，常见问题也会一起出现：

• 很难在一个地方看清哪些任务正在进行、等待复核、已经完成或发生错误；
• 同一项目可能被多个 Agent 工具使用，但缺少统一的路径索引和幂等映射；
• 用“工作区管家 Agent”维护状态会把管理说明带入 prompt，影响正常对话；
• 浏览器控制台要求额外端口、控制令牌和页面部署，生命周期与桌面应用割裂。

Multica Local 将这些能力拆成两层：桌面应用负责原生交互，本地服务负责持续同步。关闭桌面应用后，launchd 服务仍可继续工作。

主要能力

能力	行为
多来源同步	读取 Codex SQLite/rollout、OpenCode SQLite/todo 和 Claude Code JSONL/history
路径路由	将本地目录映射到不同 Multica 项目；嵌套路径按最长前缀优先
原生控制台	在左侧“配置 → 本地同步”完成预览、保存、立即同步和服务重启
幂等写入	使用持久映射更新或移动已有卡片，不因重复同步再次建卡
后台运行	launchd 登录时启动、异常退出后重启；退出 Multica Local 不停止同步
隐私保护	不同步完整 prompt、模型推理、工具输出或凭据；敏感标题会脱敏
安全控制面	Electron main 通过 Unix Domain Socket 调用服务；renderer 没有 Node 或文件系统权限

工作方式

Codex / OpenCode / Claude Code 本地状态
                  │
                  ▼
       local-agent-sync 服务
       ├─ 脱敏与状态归一化
       ├─ 最长路径路由
       └─ 幂等映射与增量写入
                  │
                  ▼
             Multica 看板

Multica Local renderer
        │ 白名单 IPC
        ▼
Electron main ── Unix socket ── local-agent-sync

同步服务不监听 TCP。旧 127.0.0.1:17654 控制台和浏览器控制 API 已完全停用。

快速使用

前提是 Multica Local 和 com.multica.local-agent-sync 服务已经安装。

1. 打开 /Applications/Multica Local.app。
2. 首次启动时使用邮件验证码登录。此应用使用独立 userData，不复用官方 Multica 的前端登录状态。
3. 在左侧“配置”分组选择“本地同步”。
4. 开启需要的 Codex、OpenCode 或 Claude Code 来源，并设置归档会话、子 Agent 和同步间隔策略。
5. 使用系统目录选择器添加本地目录，为每条目录路由选择目标 Multica 项目。
6. 先点“预览变更”，检查新建、更新、移动、资源绑定和错误数量。
7. 点“保存配置”，再点“立即同步”。

暂停自动同步 只会停止定时轮询；手动预览和立即同步始终可用。删除目录路由只停止后续同步，不会删除已有卡片、映射或项目资源。

从源码构建 Multica Local

环境要求

依赖	版本或要求
macOS	Apple Silicon；当前版本在 macOS 14 验证
Node.js	22+；本项目构建使用 Node.js 24
pnpm	10.28.2，通过 Corepack 使用
Go	1.26.6，用于打包内置 Multica CLI
Xcode Command Line Tools	Electron arm64 构建和签名所需

在仓库根目录执行：

corepack pnpm install --frozen-lockfile
corepack pnpm --filter @multica/desktop typecheck
corepack pnpm --filter @multica/desktop test
CSC_IDENTITY_AUTO_DISCOVERY=false \
  corepack pnpm --filter @multica/desktop package -- \
  --mac --arm64 --publish never

构建结果位于：

apps/desktop/dist/mac-arm64/Multica Local.app
apps/desktop/dist/multica-local-<version>-mac-arm64.dmg
apps/desktop/dist/multica-local-<version>-mac-arm64.zip

安装应用：

ditto \
  "apps/desktop/dist/mac-arm64/Multica Local.app" \
  "/Applications/Multica Local.app"

codesign --verify --deep --strict "/Applications/Multica Local.app"

应用标识为 ai.multica.desktop.local，不会注册 multica://，不会抢占官方 Multica 的深链接，也不会启动官方自动更新。

配置同步服务

服务源码位于 services/local-agent-sync。先创建本机私有配置：

cd services/local-agent-sync
cp config.example.json config.json

编辑 config.json 时至少需要确认：

• 三个来源数据库或历史目录是否存在；
• 每条 routes[].pathPrefix 是否为需要同步的工作目录；
• routes[].projectId 和 multica.workspaceId 是否属于当前 Multica 工作区；
• multica.profile 是否与 Desktop 使用的 profile 一致；
• excludedPathPrefixes 是否覆盖 Multica runtime 自己的工作目录。

然后按顺序验证：

npm test
npm run doctor
npm run dry-run
npm run sync
npm run health

只有在 dry-run 的 routed、excluded、unrouted 和拟写入数量都符合预期后，才应执行真实同步。

启用 launchd

仓库提供 launchd/com.multica.local-agent-sync.plist 模板。安装前必须把其中的 Node、用户目录、配置和日志绝对路径改成当前机器的实际路径。

cp launchd/com.multica.local-agent-sync.plist \
  "$HOME/Library/LaunchAgents/com.multica.local-agent-sync.plist"

launchctl bootstrap \
  "gui/$(id -u)" \
  "$HOME/Library/LaunchAgents/com.multica.local-agent-sync.plist"

launchctl print "gui/$(id -u)/com.multica.local-agent-sync"

运行副本、配置、映射、健康状态和日志统一放在：

~/Library/Application Support/MulticaLocalAgentSync/

详细的部署、恢复和升级步骤见 services/local-agent-sync/docs/OPERATIONS.md。

配置规则

设置	规则
同步间隔	5 秒至 5 分钟
目录	必须存在、可读且为绝对路径
宽泛路径	拒绝磁盘根目录和整个用户主目录
重复路径	拒绝完全重复；允许嵌套路由
项目资源	优先复用相同路径的 local_directory，否则创建 in_place 资源
更换目标项目	下一轮移动已有卡片并更新父卡关系，不重新创建
删除路由	保留已有卡片、映射和项目资源
新导入卡片	默认不分配 Agent，不自动执行历史任务

配置保存使用修订号乐观锁。预览、保存、手动同步和自动同步共用单飞队列，避免并发操作互相覆盖。

本地接口

Renderer 只能调用以下 preload API：

• getState()
• preview(draft)
• saveSettings(revision, draft)
• runSync()
• restartService()

Electron main 再通过以下 Unix Socket API 与服务通信：

方法	路径	用途
GET	/v1/state	获取配置修订号、健康状态、路由和项目列表
POST	/v1/preview	预览尚未保存的草稿
PUT	/v1/settings	使用修订号保存配置
POST	/v1/sync	立即执行一次同步

默认 Socket 路径：

~/Library/Application Support/MulticaLocalAgentSync/control/control.sock

父目录权限为 0700，Socket 权限为 0600。接口不会返回登录凭据。

隐私边界

会写入 Multica 的内容仅限任务识别和看板所需摘要，例如来源、脱敏标题、工作目录、状态、进度和最近活动时间。

以下内容不会被同步：

• 完整用户 prompt 或聊天全文；
• 模型推理、turn 详情和工具输出；
• API key、OAuth token、Cookie 或本地凭据；
• Multica runtime 自身产生的会话工作目录。

如果标题包含疑似密钥、Token、密码或其他敏感模式，服务会用稳定哈希标题替代原文。

开发与验证

# Desktop 类型检查与测试
corepack pnpm --filter @multica/desktop typecheck
corepack pnpm --filter @multica/desktop test

# 同步服务测试
cd services/local-agent-sync
npm test

当前定制版本已验证：

• Desktop Vitest：518 项通过；
• 同步服务：29 项通过；
• arm64 DMG/ZIP 构建通过；
• codesign --verify --deep --strict 通过；
• v2 → v3 迁移、Socket 权限、修订冲突、请求大小、单飞锁和卡片移动均有自动化覆盖。

常见问题

页面显示服务离线

launchctl print "gui/$(id -u)/com.multica.local-agent-sync"
launchctl kickstart -k "gui/$(id -u)/com.multica.local-agent-sync"

再检查 ~/Library/Application Support/MulticaLocalAgentSync/logs/。

Multica 项目列表为空

先在 Multica Local 完成邮件验证码登录，再进入服务目录运行：

npm run doctor

如果 Desktop profile 过期，需要重新登录后再同步。

同步后出现重复卡片

不要删除 data/mappings-v2.json。它是本地会话与 Multica Issue 的幂等映射。先备份映射和配置，再针对单条异常记录修复。

官方 Multica 升级了怎么办

Multica Local 不自动合并上游。为新版本创建升级分支，重新应用三个定制提交，完成 Desktop 测试、服务测试、arm64 打包和签名验证后再替换现有应用。

项目结构

路径	内容
apps/desktop/	Multica Local Electron main、preload、renderer 与打包配置
services/local-agent-sync/	schema v3 同步服务、来源适配器、Socket API 和测试
packages/core/	共享路由、平台和状态逻辑
packages/views/	共享 Multica React 视图和侧边栏插槽
docs/	上游 Multica 文档与资源

上游与许可证

本项目是 Multica v0.4.33 的定制分支，不是 Multica 官方发布版本。上游项目、品牌和原始实现归其各自权利人所有。

代码继续遵循仓库中的 LICENSE 与 NOTICE。