# CY-03｜Cindy 的工程原则与可迁移经验

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

![从工程约束到验证证据的逻辑架构图](<../../图表/CY-03_架构.svg>)

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

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

| 约束 | 规则层的要求 | 可观察的实现或记录 |
|---|---|---|
| 平台与共享能力解耦 | packages 不能反向导入宿主 | 包依赖与注入接口 |
| 用户选择随升级保留 | 默认值与 override 分开 | 配置存在性与合并语义 |
| 执行器退出必须被通知 | 退出与管道关闭分开 | Pi transport 与受控记录 |
| 插件能力按当前状态使用 | 发现文本不是授权 | 可见性函数与调用门禁 |

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

## 2. 模块职责与依赖方向

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

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

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

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

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

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

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

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

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

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

[配置契约](<../../sources.html#ref-956e829fccbcc1>) 的重要点是保留“用户是否自定义”这件事实。模型显示开关采用：

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

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

| 当前默认 | 用户 override | 有效值 | 默认以后变化时 |
|---|---|---|---|
| true | 无 | true | 跟随新默认 |
| true | false | false | 保留关闭 |
| false | true | true | 保留开启 |

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

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

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

Pi 取证案例在 [CY-02](<CY-02_Agent使用与开发过程.md>) 展开。工程原则是：进程 `exit`、输出管道 `close`、终止请求和任务成功各有不同证据。[transport.ts](<../../sources.html#ref-1b03bfd8dbd588>) 确认执行器退出后有界排空尾帧，再通知上层；250ms 不限制正常工具。

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

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

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

## 6. 验证支持持续修改

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

[研究记录](<../../sources.html#ref-73fa23b0a5e810>) 中的 134 定向用例、511 根级通过和 1 跳过是历史结果，类型检查的基线 `TS2322`、未覆盖真实 Windows 打包和新 CI 状态都需要保留。本次学习稿没有重跑这些检查。

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

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

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

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

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

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

## 8. 迁移到 Aipcg 或个人工具

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

| 原问题 | Cindy 机制与来源 | 迁移条件 | TA 最小规则与检查 |
|---|---|---|---|
| 核心被平台绑住 | package 注入；架构不变量 | 计算需要 CLI／API／UE 共用 | 计算模块不导入 UE；用保存样本验证输出 |
| 默认更新覆盖用户选择 | 默认＋override；配置契约 | 配置会升级且允许自定义 | 保存显式自定义；检查缺省、false／零和恢复默认 |
| 错误时重复执行 | 接受边界、Pi 退出通知 | 有长任务或副作用 | 区分受理、执行、终态；未知结果先核实，日志关联任务 ID |
| 单任务故障扩大 | 故障半径；远程适配规则 | 多任务共享执行或连接 | 单任务失败不清共享状态；双任务检查健康任务继续 |
| 文档与代码漂移 | 索引＋事实来源；开发工作流 | 项目被持续修改 | 行为变更核对入口、合同、样例；差异表登记未完成项 |

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

## 练习与验收

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

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

![本章思维导图](<../../图表/CY-03_思维导图.svg>)

## 来源与衔接

来源为上述 Cindy 规则、当前源码和历史 Pi 记录。结构和调用证据分别见 [CY-01](<CY-01_文档与软件结构.md>)、[CY-02](<CY-02_Agent使用与开发过程.md>)。TA 场景迁移与 [PCG-01](<../Aipcg/PCG-01_让Agent学习已有项目.md>)、[PCG-02](<../Aipcg/PCG-02_Agent辅助TA开发案例.md>) 对照阅读。