资料核验日期：2026-10-10。公开版保留整理正文与必要证据；原始资料通过来源链接回查。验证范围在正文中分别说明。
Cindy 的文档与软件结构
核验日期：2026-10-10。本章以复制到本版本的 Cindy 文档和源码为依据，学习怎样从需求找到规则，再把规则对应到实现。阅读基线为 5888d140db4f58af77f154f745ac2a047cb5da69，采集时工作区状态为空，见 仓库版本记录。本次只读分析客户端相关模块，没有启动 Cindy 或验证外部服务。
1. 建立项目阅读入口
理解一个大型仓库，首先需要三种不同的入口。项目规则说明改动应遵守什么；规范索引说明哪里有适用规则；仓库地图帮助找到实现位置。它们不能互相替代：地图中的一句话不等于完整接口契约，规则提出的要求也不能证明所有旧代码已经满足要求。
docs/README.md 逐项登记文档类型、状态和治理模块。仓库地图 明确自己只做定位导航，目录的 package.json、README 和实现代码才是具体事实来源。阅读时记下提交、工作区状态和文件位置，避免把旧整理稿的路径当成当前事实。
本章使用的阅读顺序是：先看索引和地图，找到涉及的规则；再看包清单和接口；最后沿一条任务调用链追到代码。源码副本方便离线回查，并不代表复制了整个可运行仓库。
2. 文档分类决定适用范围
索引把 authoritative 定义为对治理模块有约束力，参考材料则可能是设计、研究或历史记录，需要看正文判断完成状态。权威性来自登记与适用范围，不能只看文件名、篇幅或修改时间。
| 文档类型 | 回答的问题 | 阅读时的判断 |
|---|---|---|
| 产品规则 | 用户看到什么行为、功能边界是什么？ | 核对治理的产品场景 |
| 开发规则 | 依赖、进程、配置、数据和交付怎样组织？ | 核对改动是否命中读取时机 |
| 设计规则 | 界面语言、组件与交互遵守什么？ | 不以源码旧样式代替规则 |
| 技术设计／参考 | 某项方案怎样设想或落地？ | 继续确认实现与当前版本 |
| 研究／历史记录 | 某次问题发现了什么？ | 保留当时条件与未覆盖项 |
| 索引／地图 | 到哪里继续查？ | 不把导航摘要升级为事实合同 |
例如 Pi 长工具研究 给出了具体取证和旧测试记录，可以支持开发案例；它不自动成为所有 Agent 的统一恢复规范。遇到规则与代码不一致，应登记“规则要求”和“当前观察”两列，再确定维护位置，不能任意选择一项抹掉另一项。
3. 从需求定位文档
以“手机发起一项只读资产清单检查，并把执行状态显示回来”为阅读需求。先列出涉及的行为：手机控制桌面、指定工作目录、调用工具、事件返回和持久记录。随后进入 远程与手机适配规则、Electron 进程边界 和 maker-core 行为规则。
这条路线会把三个容易混淆的问题拆开：文件实际在哪里，谁有执行能力，谁展示结果。手机路径不能自然当成本机路径；界面显示“运行中”不能证明执行进程仍存活；提供一个工具说明不能证明本次调用已经被授权。
然后查 Mobile 控制入口、device-link 白名单、被控 Desktop 的发送入口与事件链，最后寻找覆盖对应行为的测试或记录。这是一条静态阅读路线，本章没有实际发起手机调用。
4. 多端与共享模块地图
Desktop 使用 Electron，Mobile 使用 Expo／React Native。两者共享部分契约与能力包，但运行位置不同。当前 Mobile 包清单 直接依赖 device-link、maker-shared 等包，没有直接依赖 maker-core；因此不能把手机画成在本地执行同一套 Agent 核心。
| 模块 | 本次确认的职责 | 不能由此推出的结论 |
|---|---|---|
apps/desktop |
UI、宿主、IPC、持久化和本地执行适配 | 所有逻辑都应放在 Main |
apps/mobile |
控制端连接、会话展示与设备交互 | 手机上运行完整桌面 Agent |
maker-core |
Agent 抽象、Session 与事件编排 | 不需要 Node 或供应商依赖 |
maker-shared |
跨端展示契约 | 负责桌面数据库副作用 |
device-link |
跨设备协议客户端、隧道准入等 | 客户端代码证明服务端鉴权正确 |
maker-core/package.json 不含 Electron 依赖，但包含 SDK、模型资料包等依赖，部分实现使用 Node。所谓“零 Electron 依赖”是明确的解耦边界，不是“零依赖”或可直接在浏览器运行。
仓库地图和 device-link 包清单 的描述仍写“零依赖”，实际 dependencies 已包含 @cindy/device-link-protocol。可以保留 WebSocket 由宿主注入的设计认识，依赖图则必须包含协议包。这个差异说明摘要也需要随实现维护。
5. 界面与执行之间的边界
Renderer 负责展示、表单、交互状态与无特权纯计算。preload 通过 contextBridge 暴露按用途命名的方法；Main 管理持久化、系统能力与相关校验。可复用领域逻辑进入 packages，通过接口接收宿主能力，不能反向导入 Desktop Main 或 Renderer。
当前输入主路径可以在 makerChatStore.ts 看到 input.enqueue 调用；preload.ts 把它映射到 maker:input:enqueue。Main 的 register.ts 接入输入协调器，实际派发委托 sendToAgentAccepted。
兼容的直接发送入口仍存在：sessionSendHandler.ts 校验入口并委托 makerSendTransaction.ts。因此图中应画“现代入队路径”和“兼容直接入口”汇入同一事务，不能把所有 UI 发送都简化成直接 maker:send。
preload 暴露的方法名清楚，并不意味着参数天然可信。规则要求 Main 在产生副作用之前校验来源、结构和归属；规则同时承认存量 handler 仍有未统一部分。本次阅读不能支持“所有 IPC 都已完成审计”的结论。
6. Agent、模型与工具的接口位置
BaseAgent 给不同执行器提供统一抽象，包括能力声明和 startSession。不支持的能力可以明确报错，不能因接口名称相同就推定 Claude Code、Codex、Pi 的所有行为相同。
Maker 组织 Agent 与存储等依赖，创建会话时调用对应 agent.startSession，取得执行句柄后建立 Session。供应商／运行器事件经过适配形成共享事件，宿主再消费。模型提出工具动作、执行器运行工具、宿主维护产品状态，职责各有落点。
Ghost 相关能力由 发现文档、MCP 工具入口 和 Desktop 适配 共同定位。工具发现、手册阅读与实际派发是不同环节，具体调用过程放在 CY-02。
7. 状态、数据和配置的归属
至少区分输入队列状态、执行 Session 状态、持久消息记录和界面投影。Renderer 中的缓存可以重建，不能代替持久事实；收到一条广播也不能证明所有异步写入已经完成。
sessionEventPipeline.ts 按顺序调用准备、静默输出投影、流记录、事件交付、终态处理、快照和 usage 记录。源码把它称为同步交付边界，同时说明被接受的异步写入仍保留原轮次；不能把函数同步返回误解为数据库全部 flush。
数据库规则 只治理 Desktop SQLite，不含服务端数据库。媒体也不是消息正文中的任意路径，本次未追完媒体实现，因此这里只确认其属于宿主受控资源层。
配置还要区分系统默认与用户自定义。配置契约 要求保留 override 的存在性。模型显示开关采用 override ?? 当前 defaultEnabled，显式 false 有效；恢复默认删除对应 override。该合同与所有消费方已经一致是两项不同结论，后者需要逐项验证。
沿状态追踪时，先给每项事实找归属，再问界面怎样投影它。例如用户点发送、协调器入队、执行器接受、工具返回和消息保存，应分别记录触发者与观察值。发生争议时回查拥有该事实的模块，不能凭界面文字反推全部底层行为。
8. 把结构与证据放在一起
| 需求／规则 | 模块或接口 | 可回查证据 | 当前证据边界 |
|---|---|---|---|
| 用户输入进入执行 | preload、输入协调器、发送事务 | 上述三段代码入口 | 静态调用关系，未真实发送 |
| Agent 核心可复用 | BaseAgent、Maker、Session | 包清单与核心源码 | 不证明所有平台可运行 |
| 手机远控准入 | device-link allowlist | allowlist.ts | 双层准入设计，非服务端审计 |
| 插件实时可见性 | classifyGhostVisibility |
ghostVisibility.ts | 当前源码含下线分支 |
| 默认与覆盖分离 | 配置消费者 | 配置权威文档 | 未遍历全部消费者 |
还有一项细节差异：Ghost 发现文档的部分旧判序没有列出下线状态；当前函数在账号可用之后、工作目录停用之前检查 retirement，返回 GHOST_RETIRED。判断当前执行关系应以该函数为依据，维护文档时补上遗漏。
练习与验收
为“远程读取一份资产清单”写一条阅读路线，使用 调用与开发交接模板 登记执行位置、适用规则、入口、参数、返回与未验证项。交付一张调用图和一张证据表。
验收时，读者应能沿链接找到每个关键节点，分清控制端和执行端，并解释“入队接受”“工具完成”“持久记录”“用户目标完成”的区别。图中若出现未经读取的服务端模块，只能标成外部边界，不能填入臆测的内部步骤。
来源与衔接
来源为上述 V2.0 内 Cindy 文档和源码副本，导航到完整规范见 规范索引，结构约束见 架构不变量。运行与开发两条线见 CY-02，工程迁移见 CY-03。用户提供的“TapTap CEO 与纯 AI 开发”属于项目背景，本次客户端源码阅读不能证明具体人员身份、贡献比例或开发方式。