Skip to content

Cindy — 仓库研究综述（待验证版本 / awaiting promotion）

状态：agent-verified, awaiting human confirmation
研究对象：makecindy/cindy @ 764d0b94279dc81acf3ad5fdfc2ca57ea86b22cd (HEAD of main, 2026-08-12)
许可证：Apache-2.0 · 客户端 monorepo · 后端服务不在本仓库
体量：1.89M 代码行（apps + packages），TypeScript 占 82%

1. 一句话定位

Cindy 是 开源 AI Agent 客户端：把 Claude Code / Codex / Pi 三个外部 harness 通过标准化事件流统一成同一会话/UI/IM 控制面，让用户在桌面（Electron）、移动端（Expo/React Native）和 IM 渠道（飞书等）上持久使用同一份记忆、技能、权限和团队配置；后端是独立仓库。

仓库固定 commit：764d0b94279dc81acf3ad5fdfc2ca57ea86b22cd（HEAD of main, 2026-08-12）。

2. 顶层结构（事实，固定 commit）

makecindy/cindy/  @ 764d0b9427
├── apps/                # 终端产品
│   ├── desktop/         # Electron + Vite（main / renderer / preload / shared）
│   ├── mobile/          # Expo / React Native（与 desktop 共用同一账号 + device-link）
│   ├── claude-code-bin/ codex-bin/ ripgrep-bin/   # 运行时下载的 CLI 二进制（不在 git 历史）
│   └── android-platform-tools-bin/                # adb 等
├── packages/            # 30 个共享能力包（与 render/main 解耦，零 Electron 依赖）
│   ├── maker-core/      # ★ Agent 抽象 / event loop / prompt 拼接 / translator
│   ├── maker-shared/    # 展示层契约模型
│   ├── orca-workflow/   # Orca Lead↔Worker 协同 prompt 与桥接
│   ├── device-link/     # 跨设备远程控制（同账号）
│   ├── auth-client/     # auth-server 客户端契约（zod）
│   ├── model-providers/ # 供应商路由
│   ├── anthropic-compat-proxy/ + responses-anthropic-bridge/  # 本地回环协议转换
│   ├── lizi-mcps/       # 可复用 MCP 集合（含 cindy_orca）
│   ├── cindy-tools/     # Ghost 总机
│   ├── file-browser-core/ + remote-file-service/  # 文件浏览 / 远端 RPC 守护
│   ├── maker-cc-manager/ + maker-remote-ssh/      # 远端 SSH 守护 / SDK 封装
│   └── …（30 个，共 21 万 LOC）
├── config/              # endpoint.json / endpoint.dev.json / endpoint.global.json（按区域）
├── tools/               # claude / codex / ripgrep / pi 四个 runtime 的版本 pin + 更新器
├── docs/                # dev-rules / product-rules / design-rules / legal
└── scripts/             # dev 启动 / agent 二进制拉取 / i18n guard / worktree 管理

证据：pnpm-workspace.yaml、docs/dev-rules/repo-map.md、apps/desktop/package.json、packages/ 目录扫描。

3. 三个真正"核心"模块

3.1 packages/maker-core — Agent 抽象与事件流中枢

  • BaseAgent + 三个 harness 子目录，每个 harness 都有 index.ts（宿主装配 + RPC）+ translator.ts（vendor 事件 → 统一 AgentEvent union）。
  • Claude Code：claude-code/index.ts 6260 LOC，translator.ts 1861 LOC。
  • Codex：codex/index.ts 11596 LOC（含 app-server + subagent + MCP context），translator.ts 2151 LOC。
  • Pi：pi/index.ts 2858 LOC，translator.ts 712 LOC（最轻）。
  • 关键不变量（来源 docs/dev-rules/maker-core-and-agent-behavior.md）：
  • system prompt 拼接按字节稳定前缀，禁止往里塞易变内容（保护 Anthropic prompt cache）。
  • 拒绝裸别名 'opus'/'sonnet'，model 必须走显式版本号。
  • translator 必须无丢失、无错序地映射 text/thinking/tool_use/tool_result。
  • system prompt 改动是 owner-confirmed gate，任何人不得擅自改。
  • 热路径（AsyncQueue、translator、handle.send）禁止同步阻塞 / 串行 await。

3.2 apps/desktop/src/main/maker-ipc/orca* — Orca 多 Agent 协同

  • Lead + 多 Worker 的多 agent 协同子系统；一个 Lead 最多一个 active team（partial unique），worker focused partial unique。
  • MCP cindy_orca 顶层注册 16 工具（13 写 + 3 只读诊断），host service 拒绝越权；Worker 权限走 workerCreationPrefs（renderer localStorage 真源）。
  • 维护 7 条"协同运行时行为契约"（详见 SUMMARY §7）；核心不变量：Codex HTTP bridge 只认 params._meta.threadId，不用 mcp-session-id 当路由依据（fail-closed）；worker 控制入口按 caller 自身 Lead 身份做归属校验（纵深防御）。
  • 服务边界（PR #101 之后）：OrcaLifecycleService / OrcaWorkerCreationService / OrcaTeamService / OrcaInterAgentDispatcher，禁止在 IPC 或 MCP handler 内各自实现状态机。
  • ADB：Codex per-role 工具隔离不走 proxy 改写 tools（决策已记录在文档）。

3.3 apps/desktop/src/main/im/shared/turnRunner.ts — IM 渠道 turn 编排

  • 3117 LOC 的工厂化 turn 编排（从原 im/feishu/runAgentTurn.ts 抽离为 channel-agnostic）。
  • 每 (botContextId, userId) 维护一份 TurnState、StreamingTextHandle（rich-card 输出面）、presenter（buffer-replace 策略）。
  • HEAD commit #2498 修复 #2164：飞书 rich-card 渠道 startStreamingText 失败时正文静默丢失——已加 streamingStartFailed 抑制重试 + 收口降级到 sendText，新增 5 条回归测试（见 turnRunner.ts 与 turnRunnerSendOutcome.test.ts）。

4. 架构不变量（验证清单）

来源：docs/dev-rules/architecture-invariants.md、electron-security-and-process-boundaries.md、maker-core-and-agent-behavior.md、pi-harness.md。

不变量 事实来源 风险路径
package 与 render/main 解耦 architecture-invariants.md §1 新 package 直接 import renderer 组件
main 进程禁止运行时 import() architecture-invariants.md §2 动态依赖引入打包/加载不确定性
chat-main 在布局树中唯一可见不可关闭 architecture-invariants.md §3 树变换未保持结构合法
Renderer 不直接读写磁盘/数据库/凭证 electron-security-and-process-boundaries.md §2 新增 require/Node API
BrowserWindow 显式沙箱配置 electron-security-and-process-boundaries.md §3 字段被覆盖为更宽松
preload 只暴露固定方法，剥离 IpcRendererEvent electron-security-and-process-boundaries.md §4 暴露 ipcRenderer 通用函数
IPC 是授权边界；senderFrame + 资源归属验证 electron-security-and-process-boundaries.md §5 不验证即放行
system prompt 不擅自改 maker-core-and-agent-behavior.md §4 prompt cache 命中率静默崩
凭证路径判定三处同步 pi-harness.md §4.2 只改一处致口径漂移
Pi 权限档位顺序 [ask, auto, bypassPermissions] pi-harness.md §4.1 顺序错致静默放宽到 Full Access
Pi bypassPermissions ≠ 强沙箱 pi-harness.md §1（已 warning：regex 拦截是 defense-in-depth，可被绕过） 把它当安全边界
Orca worker 终态不被失败回滚覆盖 orca-team-architecture.md 协同运行时行为契约 1 修一个分支把 done 改回 running
Codex MCP context 路由只认 threadId orca-team-architecture.md 坑点 #1/#2 用 mcp-session-id 猜身份
旧插件必须向后兼容 AGENTS.md「存量插件兼容是红线」 升级要求用户重装/重配
日志脱敏白名单 deny-by-default AGENTS.md log-upload-and-redaction.md 改黑名单致用户内容泄漏

5. 启动/分发链路

git clone https://github.com/makecindy/cindy.git
cd cindy && git lfs pull && pnpm install        # Git LFS 是硬要求
pnpm dev:desktop                                  # 桌面开发模式
pnpm restart:desktop:remote -- --region=cn       # 中国大陆区远端开发
pnpm restart:desktop:remote -- --region=global   # 全球区
  • Node ≥ 22.12, pnpm 10.7 ≤ v < 11（package.json engines + packageManager 10.33.2）。
  • 默认 endpoint.json 指向 Cindy 官方 CDN；远端开发用自己的 Cindy 账号登录走真实环境。
  • 桌面二进制发布走独立工程 cindy-binary-release（本仓只 pin 版本：pnpm update:claude/codex/ripgrep/pi 与 install:*），所以本仓根目录的 apps/-bin 不进 git 历史，下载器经 ensure-agent-binaries.mjs postinstall + digest 校验。
  • pi-host.resolvePiBinaryPath 只读 getReadyBinaryPath('pi')，不回落 getCachedBinaryStatus——离线时 pi 不可用（与 Claude Code 行为一致，与 Codex 不同；这是有意的不变量）。

6. 关键演进时间线（节选）

取自 git log --oneline + 文档内 PR 编号；本节仅列已被作者或文档明确记录的里程碑；推断标 ⚠️。

  • 2026-07-22 仓库创建
  • 2026-07-30 ⚠️ Orca 多 Agent 协同基线（Lead/Worker 数据模型 + cindy_orca MCP）
  • 2026-07-30 ⚠️ Chris 裁决：Pi 是 Cindy 未来的基座 harness（pi-harness.md §3）
  • 2026-08-XX PR #107 — side_chat 底层 fork 数据动作（user/assistant 都可 fork）
  • 2026-08-XX PR #101 — Orca main 侧业务边界收敛到 4 个 service（OrcaLifecycleService 等）
  • 2026-08-09 Pi 上线 v0.83.0，六平台 digest pin；2026-08 起走 CDN 分发，与 cc/codex 同链路
  • 2026-08-12 #2498 — 飞书渠道 startStreamingText 失败时正文静默消失（#2164）→ 加 streamingStartFailed + 收口降级

7. 未决议 / 已知 follow-up（来自文档）

项 状态 来源
forkedAtMessageId schema 注释滞后（应同时描述 user + assistant 来源） follow-up orca-team-architecture.md 坑点 #8
orca_worker_bridge 对 Codex 全局可见 → handler 必须做 role 校验兜底 follow-up orca-team-architecture.md 坑点 #4
side_chat 已落 fork 数据动作但未登记为 side activity，也未挂进 pane 待落地 orca-team-architecture.md Part 2
workflow_run / CC Workflow 编排尚未纳入 Orca 待落地 orca-team-architecture.md Part 1 当前边界
persistent / ephemeral Worker 分型：当前只有 idle release 基础（PR #340），分型字段未落地 待落地 orca-team-architecture.md Part 2
pi-host 离线不可用是有意行为；要改需 owner 确认 不变量 pi-harness.md §6

8. 复用 / 改造 / 重设计路线（评估）

评分仅作研究建议，不构成最终决策。

方向 评估 主要依据
A. 直接复用 as developer client ★★★★ Electron + Electron 41 sandbox / 上下文隔离齐全；Orca 多 agent 模式稀缺；事件流设计扎实；缺点是 Pin/Codex/CC 三种 agent 接入和 license 跟踪有持续维护成本。
B. 抽 maker-core + orca-workflow 到独立项目 ★★★ BaseAgent + 三个 translator 是真可复用的部分；Orca 协同设计是 Cindy 独有的强项。但耦合紧密（IM/turnRunner/desktop 状态机），抽出成本高。
C. 借鉴 IM turnRunner 与 StreamingTextHandle 模式 ★★★★ 工厂化 createTurnRunner 与"流式输出面创建失败 → 收口降级"模式可推广到其它多渠道场景；3000+ LOC 单一文件仍是改造点。
D. 复用 plugin / ghost 系统 ★★★ Ghost 总机（cindy-tools）+ 插件 manifest/批准 schema + 安全清单基线；但与 desktop 状态机深度耦合。
E. 替换/参考 device-link 协议 ★★ envelope 协议 + WS tunnel + allowlist 设计清晰；安全模型严谨。但非通用通信方案。
F. 重新设计：仅参考 + 在新项目独立做 IM AI Agent ★★★ 体量过大（1.89M LOC）不适合 fork；建议先以 maker-core 抽象为学习样本，针对单场景重做。

9. 风险与未尽事项

  • 二进制 pin 风险：pi-host 离线时不可用是有意行为，若下游需要离线则需自加 fallback（属行为变更，须确认）。
  • TapDB 隐私：README 已说明并提供 opt-out 路径（mobile 默认 off，desktop 删 initTapdb()）。下游 fork 需注意。
  • DCO Sign-off 硬要求：每个 commit 必须 git commit -s，且 name/email 与 author 一致；自动 code review 不豁免。
  • 提交前测试门禁：pnpm test:unit + 各受影响 package 的 typecheck 必须通过；CI 才是最终判据。
  • 本研究的未覆盖范围：
  • 客户端 monorepo 未执行构建/运行（按 Profile 规则默认只读）。
  • apps/*-bin/ 与 tools/<kind>/latest.json 的具体 digest 未核对（执行构建/下载才需要）。
  • IM 渠道 turnRunner 的逐项测试未抽检（3117 LOC 单一文件太大，仅看头注释 + HEAD commit patch）。
  • pnpm-lock.yaml（762KB）的依赖审计未做（建议下游用 Trivy 单独做）。

10. 已请求的"扩展资料 / 待用户确认"

  • 发布：本综述已在 /tmp/cindy-site/research/cindy/ 沉淀为待验证版本。是否发布到 Cloudflare Pages technical-research.pages.dev，以及是否合并进 research/cindy/ 子路径——需要用户明确确认（不要把"研究"等同于"发布"授权）。
  • 横向比较：本节按用户此前偏好（"后续再考虑横向比较"）推迟；如需恢复请告知对照对象。
  • MVP 还原：本项目无明显"产品 MVP"节点（仓库 2026-07-22 才创建），故未执行独立 MVP 章节；演进时间线见 §6。