Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
开发环境与依赖准备
读取时机:首次克隆、创建新 worktree、缺少依赖或安装命令失败时
环境要求
- Node.js 与 pnpm 版本以根
package.json的engines和packageManager为准。 - Git 与 Git LFS。
先核对实际版本:
node --version
pnpm --version
git lfs version
安装
git clone https://github.com/makecindy/cindy.git
cd cindy
git lfs pull
pnpm install
pnpm install 的 postinstall 会按当前平台 best-effort 自动下载 Desktop runtime
二进制(claude/codex/ripgrep/pi,不入 git;失败只告警不阻断)。dev 启动前
的 guard 会按同一份 runtime kind 清单再确认:全新 clone/worktree 缺少任何一项时都会
自动补下载,仍无法准备才会中止 dev 启动并给出明确错误。
正常情况下无需手动安装二进制。
macOS/Linux 的 apps/codex-package-bin/<平台>/codex-path/codex 由上述检查流程在
完整包校验通过后补入,并更新目录清单;运行中的开发版不改包目录。脚本转发到同包的
bin/codex,使任务里的 shell 使用与任务相同的版本;已有的非 Cindy 脚本不会被覆盖。
postinstall 最后还会按 Electron install.js 的语义复核 node_modules/electron/dist,
缺失或版本不符就补装(node scripts/ensure-deps.mjs --electron-binary;设置了
ELECTRON_SKIP_BINARY_DOWNLOAD 或 ELECTRON_OVERRIDE_DIST_PATH 时跳过)。原因:pnpm 的
side-effects cache 一旦记下「electron 已构建但没有产物」,同机之后每次安装都会跳过 Electron
自己的 postinstall,留下缺 dist 的安装,桌面端单测会整片报 Electron failed to install correctly。pnpm test:unit 等 workspace 测试开跑前也会只读检查一次依赖与 Electron,
未就绪时以 DEPENDENCY_SETUP_INCOMPLETE 直接给出处置命令,不再让几十个测试文件各自报错。
新 worktree 不共享 node_modules。确认 checkout 已完成且根 package.json 存在后,
在该 worktree 内重新运行 pnpm install;不要加 --ignore-scripts,上述补装都在安装
脚本里完成。
Mobile 的 Global / CN 开发与打包只需仓内公开端点清单,不要求本机存在
config/endpoint.dev.json。Metro 在这两个区域将私有 dev 清单排除出依赖图;不能靠从
另一个 checkout 复制私有配置来修复新 worktree。只有显式选择 --region=dev 时才需要
按 config/endpoint.dev.json.example 准备该文件,缺失时保持明确失败,不切换区域或端点。
模拟器与运行源码身份检查使用 Mobile 开发入口。
Cindy Make 的设置入口和指令前置弹窗共用源码准备流程:切到 cindy-personal 后,
按锁文件预热包含开发依赖的 pnpm store 缓存,成功后才标记源码就绪。预热使用
pnpm fetch --frozen-lockfile --prefer-offline --prod=false --ignore-scripts --config.node-linker=isolated --config.enable-modules-dir=false,只下载/复用缓存,
不为个人分支建立依赖目录、不执行安装脚本;这两个 config 参数仅作用于预热子进程。
每次准备都由 pnpm 校验当前锁文件和缓存,缺失或变化的包才补下载,不用就绪标记跳过校验。
实现与回归见 sourcePreparation.ts
及其测试。
用户继续后,开发任务的 worktree 使用已选定的系统或 Cindy 管理
工具(含原生依赖构建所需的 Python),并通过
pnpm install --frozen-lockfile --prefer-offline --prod=false 优先复用
准备阶段填充的 pnpm store 缓存,并执行必要的安装脚本;各 worktree 仍保留独立的 node_modules,不复制或
链接个人分支的依赖目录。安装失败或取消可在现有 checkout 上重试,不重置个人分支。
macOS:iOS 模拟器构建工具链
首次安装开发包不等于首次完整编译。先按 Mobile 模拟器流程
检查已安装包;需要安装或更新原生包时,mobile:sim:rebuild 会先检查跨 worktree 的
fingerprint 缓存。命中兼容产物就直接安装,不要求 CocoaPods;只有缓存不可复用时才编译。
完整编译需要选中的完整 Xcode、iOS Simulator SDK、目标设备所需的已安装 runtime,
以及当前 Agent 的 PATH 中可运行的 CocoaPods。仅安装 Command Line Tools 不够。
在实际运行任务的终端核对(终端 App 可用不代表 Agent 子进程也可用):
xcode-select -p
xcodebuild -version
xcrun --sdk iphonesimulator --show-sdk-path
xcrun simctl list runtimes
pod --version
Xcode 选择由本机 xcode-select 或本次进程的 DEVELOPER_DIR 决定;首次启动设置、许可和
runtime 下载在 Xcode 完成。机器上的实际安装位置、选中的设备和工具是否可用应现场检测,
不写成仓库默认值。模拟器的 SDK/runtime 不等于 CocoaPods,也不等于可复用 App。
CocoaPods 使用开发者已有的工具管理方式:
- 已安装 Homebrew:
brew install cocoapods,随后确认当前 Agent 的PATH能找到它。 - 已有独立 Ruby(例如 rbenv/RVM 管理):先核对
ruby --version和gem --version, 然后gem install cocoapods --user-install;将ruby -r rubygems -e 'puts Gem.user_dir'输出目录下的bin加到该工具环境的PATH,再验证pod --version。 - 两者都没有:先按开发者选定的方式准备独立 Ruby 或 Homebrew,再安装 CocoaPods。 不因系统带有 Ruby 2.6 就假定当前 CocoaPods 及其依赖可安装,也不自动替换系统 Ruby。
这遵循 CocoaPods 官方安装说明 推荐的独立 Ruby 与用户目录安装方式;安装命令成功仍须通过上面的本机检查。工具链安装、 系统路径调整与许可证接受遵循当前用户授权,不由仓库脚本静默执行。
缓存未命中时,rebuild 在生成 ios/ 前运行只读工具检查,输出 SIM_BUILD_PREFLIGHT;
缺失、执行失败或超时以 IOS_BUILD_TOOLS_UNAVAILABLE 结束。先修复回执中失败的工具,
用原来的 region / UDID / --mock 参数重试,不通过换区域、清缓存或换真机掩盖环境故障。
Linux:Electron SUID sandbox 权限
较新的 Ubuntu(23.10+ 默认用 AppArmor 限制非特权 user namespace)上,Electron 会退回
SUID sandbox,dev 启动时报
The SUID sandbox helper binary was found, but is not configured correctly。修复:
cd node_modules/electron/dist
# 先原位复制一次,断开与 pnpm store 的硬链接——pnpm 的 side-effects cache 会把
# electron postinstall 产物 hardlink 进共享 store,直接 chown/chmod 会把 store 副本
# 一并改成 root+setuid,波及本机其它复用同版本 Electron 的项目/worktree。
cp chrome-sandbox chrome-sandbox.tmp && mv -f chrome-sandbox.tmp chrome-sandbox
sudo chown root:root chrome-sandbox
sudo chmod 4755 chrome-sandbox
注意:
node_modules/electron/dist由 electron postinstall 解包/从 store 链接,每次重装 依赖或 electron 升版本后该权限都会被重置,每个 worktree 需要各自重跑上面的步骤 (包括断链那一步)。- 只做上述针对性修复;不要放开系统级 user namespace 限制,更不要用
--no-sandbox绕过(违反 Electron 安全边界,参见electron-security-and-process-boundaries.md)。
不变量
- 公开版本不包含内建插件种子;插件通过 SkillHub 或手动安装。不要把任何访问令牌写入 仓库、Git 配置或脚本。
- Desktop runtime 二进制(claude/codex/ripgrep/pi)的版本由仓库维护者统一判断与升级;贡献者和
Agent 不要修改
tools/<kind>/latest.json的版本 pin,也不要主动升级二进制。 - 依赖和命令的事实源是当前 checkout 的
package.json与脚本。文档和脚本冲突时, 先核对代码并修正文档,不要继续执行已失效命令。 - 不要把其他 checkout 的
node_modules、用户数据、授权文件或数据库复制进当前工作区。
贡献方式与 PR 流程见仓库根 CONTRIBUTING.md。