【AI Agent 实战】cindy 中文版：开箱即用的开源 AI 代理上手指南

一、cindy 是什么

Cindy 是一个开箱即用的开源 AI 代理（2249 stars，Apache-2.0），跑在你本地的电脑上。它把多个工具框架（harness）、模型和工具整合进一个代理，用你的真实文件和已登录应用完成实际工作。

首批支持的 harness 是 Claude Code 和 Codex，模型和 harness 可以自由组合、在任务中途切换，而工作区、记忆、技能、工具保持连续。

这个仓库是 Cindy 的开源客户端：桌面端（Electron）+ 移动端（Expo/React Native）+ 共享包，组织为 pnpm monorepo。

二、核心能力

能力	说明
多 harness	统一入口编排 Claude Code / Codex
多模型	官方服务 / 已付费订阅 / 自有 API key / 本地模型
记忆	纠正一次就照做，跨 harness 共享
技能	教一次工作方式，随处复用
自动化	重复工作自排期、自运行、自汇报
MCP	接入内部工具和业务系统
插件	重塑功能、UI、交互（开发中）
跨设备	驱动浏览器、电脑、手机，从 IM/日程接手任务

三、环境要求

Node.js 22.x
pnpm 10.x（v11 尚不支持）
Git LFS

四、快速上手

bash 复制代码

# 克隆仓库
git clone https://github.com/makecindy/cindy.git
cd cindy

# 拉取 LFS 大文件
git lfs pull

# 安装依赖（会自动按平台下载 claude-code、codex、ripgrep）
pnpm install

启动桌面端开发：

bash 复制代码

# 中国大陆账号
pnpm restart:desktop:remote --region=cn

# 全球账号
pnpm restart:desktop:remote --region=global

登录界面选择「跳过登录」（Skip Sign-In），可以不用 Cindy 账号直接跑本地代理（此状态下服务端能力不可用）。

五、仓库结构

复制代码

apps/desktop        Electron 桌面客户端
apps/mobile         Expo / React Native 移动客户端
packages/*          共享能力（认证、设备链接、代理编排、模型提供商）
apps/*-bin          随桌面应用发布的工具二进制（claude-code、codex、ripgrep 等，按平台下载）

后端服务在独立仓库，不属于此 monorepo。

六、模型接入的四种方式

官方服务：登录 Cindy 云账户，用量透明扣费；
复用订阅：授权已付费的 Claude Code / Codex 编码计划，在 Cindy 内继续使用，不重复扣费；
自有 key：连接你自己的 API key；
本地模型：使用本地部署的模型。

七、架构文档索引

DESIGN.md ------ 视觉设计系统、颜色令牌、UI 规范
docs/README.md ------ 完整文档和规则索引
docs/dev-rules/ ------ 深度架构文档（含 Orca 多代理编排）
AGENTS.md ------ 工程规则、启动/运行时契约、模块边界
CONTRIBUTING.en.md ------ 贡献者配置、验证、提交流程

八、贡献与安全

贡献走 PR，每个 commit 需要 DCO 签名（git commit -s）；
绝不把凭证或授权文件提交进工作树；
第三方组件版权与 SPDX SBOM 管理在 docs/legal/；
安全问题请走 SECURITY.en.md 私下报告，不要开公开 issue。

九、隐私与遥测说明

官方发行版内置 TapDB 统计（仅设备/OS/版本等产品级元数据，不收集聊天内容、文件内容、工作目录）。从源码构建时：

移动端默认关闭统计（无 TapDB 凭证时 mobileTapdb.ts 是 no-op）；
桌面端移除 apps/desktop/src/renderer/index.tsx 里的 initTapdb() 调用即可完全剥离。

十、中文版

我已将 cindy 完整中文化，发布中文版仓库，README、架构文档、开发规则、贡献指南均可中文阅读：

https://github.com/yangshun2005/cindy-cn

如果这个项目对你有帮助，也欢迎动动小手去原仓库点个 Star，支持作者持续维护。