10分钟看懂Cindy monorepo：pnpm workspace项目结构全览

Cindy 是一个开源、开箱即用的 AI Agent——「想到，就能做到」，她能把 Claude Code、Codex 等多种模型与工具收进同一个智能体里，在你的电脑上完成真实任务。本文带你用 10 分钟看懂 Cindy monorepo 的项目结构：从 pnpm workspace 的依赖管理方式，到 apps/ 与 packages/ 的分工逻辑，帮你快速建立这张「仓库地图」。

一、Cindy 是什么？一个开箱即用的开源 AI Agent

在拆解目录之前，先明确这个仓库的定位：

• 它只是客户端仓库：包含桌面端（desktop）、移动端（mobile）以及它们共享的能力包，服务端在独立仓库中，不在本 monorepo 内。
• 它用 pnpm workspace 组织：一个仓库、一套依赖锁、多个子包，这是理解全部目录结构的前提。
• 它自带完整工程设施：脚本、工具版本 pin、文档规则、设计资产一应俱全，属于「生产级」monorepo 的典型样本。

根目录的 package.json 一句话说明了仓库身份："Cindy open-source client monorepo — desktop, mobile, and shared packages"，并且声明了 Apache-2.0 开源协议。

二、顶层目录总览：monorepo 的完整地图

仓库官方维护了一份 仓库地图（docs/dev-rules/repo-map.md），是定位功能代码的最佳入口。按它和源码核对，顶层结构如下：

路径	一句话说明
apps/	终端产品：desktop 桌面端、mobile 移动端、headless 服务与随包分发的二进制资产
packages/	客户端共享能力包：Agent 编排、设备互联、模型目录、语音输入等 30 余个包
config/	区域端点清单（CN / Global 公共配置与本地 dev 模板）
scripts/	仓库级工程脚本：依赖安装、启动包装、i18n 与设计色值校验、worktree 管理
tools/	claude / codex / pi / ripgrep 四个运行时的版本 pin（latest.json）与更新器
docs/	规则文档：dev-rules/（工程）、product-rules/（产品）、design-rules/（设计）
i18n/	多语言术语表与术语规则，配合门禁脚本保证翻译一致性
dependency-patches/	对 react-native、expo、rollup 等第三方依赖的补丁文件
prototypes/	产品原型的 HTML 与预览图

其中 AGENTS.md 是面向 AI 编程助手（也是人类新手）的项目指令正本，开头就讲清了「仓库边界」与「按模块进入」的入口表，建议第一次打开仓库时先读它。

三、pnpm workspace 是怎么工作的：3 个文件看懂依赖管理

整个 monorepo 的依赖管理只需要看懂 3 个文件：

1. pnpm-workspace.yaml —— 谁属于这个工作区

它只有两行核心配置：apps/* 和 packages/*。也就是说，这两个目录下的每一个子目录都是一个独立工作区包，各自拥有 package.json，但共享同一个锁文件与安装树。

2. package.json —— 仓库级的「总控台」

根 package.json 承担了三层职责：

• 环境声明：engines 锁定 Node.js ≥ 22.12、pnpm 10.x（见 package.json#L18-L21），packageManager 字段保证所有协作者用完全一致的 pnpm 版本。
• 统一命令入口：pnpm dev:desktop、pnpm test:unit、pnpm check:i18n 等脚本都定义在这里，底层通过 pnpm --filter desktop 这样的过滤器命令把任务派发给具体子包——新手不需要记每个包的目录，一条命令启动桌面端即可。
• 依赖治理：overrides 统一锁版本，patchedDependencies 把 dependency-patches/ 下的补丁挂到具体依赖上（如 react-native、expo-router），这是 monorepo 中处理"第三方依赖有 bug 但上游没修"的常见手段。

3. pnpm-lock.yaml —— 唯一的依赖真相

全仓库只有一个锁文件，保证桌面端、移动端和所有共享包看到的依赖版本完全一致，这也是 pnpm monorepo 相对"多个仓库各装各依赖"的核心优势。

四、apps/：终端产品的家底

apps/ 下按产品形态划分，是用户能直接感知到的一切：

目录	说明
apps/desktop	Electron 桌面客户端，源码分 main/（主进程业务）、renderer/（UI）、preload/（桥接）、shared/ 四层，SQLite 迁移文件在 drizzle/
apps/mobile	Expo / React Native 移动端：同账号登录、发现并远程控制桌面设备、镜像会话
apps/cindy-headless	无界面运行形态，含 Claude / Codex / Pi 三套生产 profile 与分发脚本
apps/*-bin	随桌面端分发的预编译 CLI 二进制（claude-code、codex、ripgrep、pi），不入库，pnpm install 时按需下载并做 sha256 校验

桌面端目录结构值得新手记住一个模式：main / renderer / preload 严格分层，业务逻辑尽量留在主进程，UI 保持"纯渲染"，这也是它内部 桌面开发文档 反复强调的边界。移动端则只直接依赖 5 个共享包（auth-client、device-link、maker-shared、model-providers、voice-input-core），刻意保持轻量。

五、packages/：monorepo 的心脏——共享能力包

真正体现 monorepo 价值的，是 packages/ 下 30 多个可复用能力包。挑几个核心的讲：

• maker-core：Cindy 核心，负责 Agent 抽象（BaseAgent）、会话编排与事件流，零 Electron 依赖，是整个产品的"引擎"；
• maker-shared：桌面与手机共享的展示层契约模型，零 React / Electron 依赖；
• device-link：跨设备远程控制协议——手机远程操控电脑全靠它；
• model-providers：模型供应商目录与路由抽象，决定你能接入哪些模型；
• auth-client：平台无关的登录鉴权客户端契约；
• voice-input-core：供应商无关的语音输入听写状态机。

可以看到一条清晰的依赖纪律：包与包之间零重型依赖、按能力切割，桌面和移动端各自挑选需要的包组装。完整的包清单与"主要使用方"对照表在 repo-map.md 的 packages 章节，建议收藏。

六、scripts/ 与 tools/：看不见的工程骨架

大型 monorepo 的功力往往藏在工具链里：

• scripts/：仓库级脚本中枢。ensure-deps.mjs 负责一键装好依赖，test-workspaces.mjs 按 unit / integration / e2e 分层调度所有工作区的测试，check-i18n.mjs、hardcoded-color-audit.mjs 等门禁脚本保证术语与设计色值不被写歪——每个脚本基本都有对应的 __tests__ 自测。
• tools/：tools/claude/、tools/codex/、tools/pi/、tools/ripgrep/ 各放一份 latest.json 版本 pin 与 update.mjs 更新器，把外部运行时工具变成"仓库内可审计的受管资产"。
• docs/：规则文档三分天下——dev-rules/ 管工程、product-rules/ 管产品行为、design-rules/ 管视觉，另有验收截图与设计决策日志留档。
• i18n/GLOSSARY.md：产品术语表，已裁决的译法统一照用，配套门禁脚本自动检查。

七、快速上手：新手导航路线

如果你刚 clone 仓库（地址：https://gitcode.com/GitHub_Trending/cind/cindy），推荐这条 10 分钟路线：

1. 读 AGENTS.md：5 分钟了解仓库边界与规则入口；
2. 读 docs/dev-rules/repo-map.md：按"用户行为"反查功能代码位置；
3. 读 docs/dev-rules/environment-setup.md：完成首次安装；
4. 跑 pnpm dev:desktop：直接看到 monorepo 的产出物；
5. 想改代码时，按模块进入对应子目录的 AGENTS.md（如 apps/desktop/AGENTS.md、packages/maker-core/AGENTS.md）。

总结

Cindy monorepo 是一个教科书级的 pnpm workspace 实践：pnpm-workspace.yaml 划界、根 package.json 统一命令与依赖治理、apps/ 放产品、packages/ 放能力、scripts/ 与 tools/ 撑起工程自动化、docs/ 用规则文档约束协作。看懂这张地图，你就拿到了进入这个开源 AI Agent 项目的第一把钥匙——想到，就能做到。