资料核验日期：2026-10-10。公开版保留整理正文与必要证据；原始资料通过来源链接回查。验证范围在正文中分别说明。

Cindy 的工程原则与可迁移经验

核验日期：2026-10-10；Cindy 源码基线 5888d140db4f58af77f154f745ac2a047cb5da69。本章把多端、Agent 运行和配置维护中的具体约束，改写为可检查的工程方法。Cindy 既定规则按源码副本文档引用；用于 Aipcg 和个人工具的建议明确属于整理者归纳。

1. 先写原则要解决的问题

“模块化”“自动恢复”“保持一致”都需要具体对象。Cindy 的实际约束包括 Desktop 与 Mobile 分工、不同执行器事件统一、长任务状态收口、默认配置演进以及跨设备故障隔离。工程原则只有落到执行位置，才能判断它是否有效。

规范说明“应该怎样”，源码说明“当前怎样”，测试说明“在所测条件下观察到怎样”。三者相关，但证据强度不同。本章不从几份文档推导整个仓库全面符合所有规则，也不把旧测试报告作为本次实测。

2. 模块职责与依赖方向

架构不变量 要求 package 通过配置或回调取得宿主能力，避免直接 import Desktop Main／Renderer。Electron 边界规则 则按特权与输入可信程度区分职责：展示和纯计算可留在 UI，持久化、系统能力和安全裁决进入受控宿主。

这让核心逻辑可以被独立验证，平台差异集中在适配器。代价是必须维护清楚的接口、错误和生命周期；如果把所有状态塞进一个“通用回调”，仍会把耦合隐藏起来。

当前 maker-core 没有 Electron 依赖，但仍有 SDK 与 Node 环境相关实现；device-link 由宿主注入 WebSocket，却实际依赖协议包。迁移时应绘制真实依赖，而不是机械要求所有包零依赖。

对个人 TA 工具，可以先把 CSV 校验、单位换算、几何审计写成纯函数，再让 CLI、API 或 UE 适配器注入读取与保存能力。没有多端需求的小脚本不必复制 Cindy 的整套目录，只要保持关键计算与宿主副作用可分开检查。

3. 模型与确定性代码怎样分工

模型适合解释需求、提出假设、选择下一步和总结观察。确定的字段检查、路径归属、状态迁移、权限判断与保存结果应有程序落点。模型说“文件安全”“任务完成”不能成为执行层的事实依据。

maker-core 行为规则 明确不应把本可由代码保证的确定逻辑甩给 prompt。Ghost 可见性函数 展示了落实方式：输入 ID 和工作目录，依当前安装与账号状态判断可用性，返回明确错误，而不是请求模型猜测。

另一方面，并非任何问题都能简化为固定阈值。工具循环规则需要区分真实纠错、重复搜索和等待外部进度；判断仍受证据范围限制。规则增加复杂度之前，应说明它预期阻止什么错误、可能误伤什么行为。

迁移到 Aipcg，可让 Agent 给出布局意图，把单位、坐标、资产键、碰撞和导入条件交给确定性代码。几何检查通过只证明相应约束，美术质量仍需要视觉评审。模型判断和程序检查各自提供证据，不互相冒充。

4. 配置、协议与事实保持一致

配置契约 的重要点是保留“用户是否自定义”这件事实。模型显示开关采用：

effectiveEnabled = userOverride ?? currentDefaultEnabled
恢复默认 = 删除指定 override

false 是有效的自定义值，不能用 override || default 合并。系统默认后来变化时，未自定义用户跟随新默认，已自定义用户保留选择。恢复默认应重新跟随当前目录，写入旧默认快照会把恢复操作再次变成自定义。

这是一项已读取的合同，配置文档本身也登记了活动目录投影差异；本章没有遍历所有消费者，所以不宣称已全端一致。类似地，客户端白名单可以证明准入设计，不能证明服务端实现。

对 TA 工具，版本默认、用户项目参数和单次任务参数应分别保存。若某项目主动设成零，不能当成“未填写”；如果历史配置没有自定义标记，迁移应说明推断限制，不能只凭旧值猜意图。

5. 明确失败、取消与恢复

Pi 取证案例在 CY-02 展开。工程原则是：进程 exit、输出管道 close、终止请求和任务成功各有不同证据。transport.ts 确认执行器退出后有界排空尾帧，再通知上层；250ms 不限制正常工具。

确认 Pi 退出不证明后代构建成功或安全停止；收到 kill 错误也不证明进程已经退出。结果丢失需要保留未知状态，不能补写成功或自动重跑已有副作用。Stop 表达取消意图，也不能把正在运行的外部操作瞬间视作没有发生。

跨设备恢复还涉及故障半径。远程适配规则 说明单请求、单 peer 和共享 relay 连接的层级不同。一个控制端休眠时重建整条共享连接，可能波及健康控制端。先写明触发层级，再选择最小恢复动作；多 peer 用例才能检查这一设计。

小型工具不必实现同样的网络拓扑，但仍应记录任务 ID、外部进程、已产生文件和未知结果。重试前先核实当前状态；对于导出或导入动作，重复执行是否覆盖、追加或重复创建必须明确。

6. 验证支持持续修改

验证要能区分原问题与替代解释。Pi fixture 检查父进程已退出、后代仍活着，才有资格检验“管道继承导致通知缺失”。Windows 旧 fixture 没建立该前提，于是修正测试后代的 detached 设置；这不能扩大成生产进程策略变更。后续 EBUSY 清理问题又要求确认退出与有界异步删除，而非吞掉清理失败。

研究记录 中的 134 定向用例、511 根级通过和 1 跳过是历史结果，类型检查的基线 TS2322、未覆盖真实 Windows 打包和新 CI 状态都需要保留。本次学习稿没有重跑这些检查。

开发工作流 支持按影响面选测并如实说明。验证只证明自己的目标：类型检查不验证模型输出质量；测试跳过不等于通过；界面收到广播不等于持久化结束。最终变更说明应该写行为变化、证据和实际限制，避免靠检查数量营造可靠性。

对于 prompt、模型路由和事件热路径，静态检查之外还需要对应运行指标。本章没有修改这些路径，因此没有产生新的性能结果；把测试成本和需要的证据分开，有助于避免无目标地重复整仓测试。

7. 维护项目知识的最小方法

入口文档负责导航，合同负责约束，实现负责运行，案例负责保留判断条件。开发工作流 要求行为变化时核对受影响文档；发现错误修原依据，入口遗漏补入口，能自动验证的补回归。一次环境故障不自动升级为长期规则。

本次阅读发现两项维护点：device-link 的描述仍称零依赖，而包清单已经包含协议包；Ghost 文档部分判序未列出当前代码中的 retirement 分支。学习稿登记差异，原始副本保持不变。若在真实仓库执行维护，应修对应摘要并链接事实来源。

知识条目最好带来源、核验日期和失效条件。历史验证保存原日期与版本，新的行为检查写新记录。这样下一位 Agent 能判断哪些结论可直接用，哪些需要回读，而不是把所有旧经验都当成永久指令。

8. 迁移到 Aipcg 或个人工具

下表是整理者提出的最小采用方式，不能写成 Cindy 已规定所有 TA 工具照办。

这些规则的执行位置要具体。配置合并在运行入口，范围校验在副作用之前，终态由掌握执行证据的模块发出，知识更新跟随实际变更。没有多任务共享状态时，第四条暂不引入额外框架；没有升级配置时，也可以用更简单的显式参数方案。

练习与验收

使用 Cindy 工程迁移规则模板，为自己的工具选三条规则，逐条填写问题、机制、来源、条件、执行位置、检查和不适用情形。至少包含一个边界样本，不能只写“测试通过”。

验收时，读者应能找到规则落在哪个函数或入口，理解它阻止什么错误，以及现有证据还不能支持什么结论。任何“已修复”“已完成”都要限定对象、版本与环境。

来源与衔接

来源为上述 Cindy 规则、当前源码和历史 Pi 记录。结构和调用证据分别见 CY-01、CY-02。TA 场景迁移与 PCG-01、PCG-02 对照阅读。