读取时机：首次克隆、创建新 worktree、缺少依赖或安装命令失败时
- Node.js 与 pnpm 版本以根
package.json的engines和packageManager为准。 - Git 与 Git LFS。
先核对实际版本：
node --version
pnpm --version
git lfs versiongit clone https://github.com/makecindy/cindy.git
cd cindy
git lfs pull
pnpm installpnpm install 的 postinstall 会按当前平台 best-effort 自动下载 Desktop runtime
二进制（claude／codex／ripgrep／pi，不入 git；失败只告警不阻断）。dev 启动前
的 guard 会按同一份 runtime kind 清单再确认：全新 clone／worktree 缺少任何一项时都会
自动补下载，仍无法准备才会中止 dev 启动并给出明确错误。
正常情况下无需手动安装二进制。
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，上述补装都在安装
脚本里完成。
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 上重试，不重置个人分支。
较新的 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。