读取时机：首次接触本仓、需要定位某个功能的代码位置、或新增代码／依赖前判断 应该放进哪个模块时
本文只做定位导航：先按用户行为找生产入口、共享判据和测试，再按目录判断代码归属。
事实源是各目录的源码、package.json 与 README；发现本文与代码不一致时，以代码为准并顺手修正本文。
依赖方向与解耦约束见 architecture-invariants.md。
模块约束从 Desktop、Mobile、
maker-core 进入；下表记录现有入口，不另建任务生命周期框架。
register.ts 仍负责部分宿主接线，按表中的函数／IPC 名定位即可，不必从头阅读。
| 用户行为 | 生产入口与共享判据 | 从哪些测试开始 |
|---|---|---|
| 发送、排队、插话、停止后继续 | AgentInputCoordinator 持有输入事务；register.ts 的 sendToSessionInternal 接宿主发送；agentInputQueue 定义队列契约。个人 IM / 官方 hook 的调用方账本见 IM 轮次流程。 |
coordinator、队列契约 |
| 普通任务、伙伴与群任务切换权限 | register.ts 的 SET_PERMISSION_MODE 与 sessionPermissionChange 处理运行期变更；未加载运行时的持久化走 sessionPermissionPersistence，伙伴专线同步走 botPermissionSync。permissionMode 统一客户端的未知档位与 Full access 确认判据；实际执行权限仍由宿主／引擎决定。 |
权限持久化与专线同步、引擎控制、跨端权限判据 |
| 重启后发现中断任务、运行中断后续跑 | 启动候选由 sessionActiveTurn 判定，interruptedResumeCandidates 补展示信息；运行期自动续跑由 interruptedTurnAutoResume 分类，再回输入协调器。两者不是同一触发条件。 | 启动中断判据、启动恢复对话框、自动续跑判据 |
| 新任务与伙伴选择默认模型 | Desktop 的 newMakerDefaultTuple 选择默认组合；botDefaultModelChain 复用推荐，但伙伴设置与新任务输入框选择独立。Mobile 的 useNewSessionDefaultSelection 调用 newSession 中的 resolveNewSessionAutoDefault，被控端默认与缓存由 useNewSessionHostDefaults 提供。目录来源与覆盖顺序见模型配置与下发。 |
默认组合、伙伴默认、手机默认与缓存 |
| 手机新建任务、创建中继续输入、失败回编辑 | new.tsx 组装页面；prepareNewSessionCreation 先保存草稿与附件，再预建 worktree；newSessionCreation 持有跨页面的乐观创建管线；useNewSessionDraftRecovery 恢复草稿。 | 乐观创建、真实恢复 hook、草稿持久化 |
同一行为涉及普通任务、伙伴、群、调度、本机与远程入口时，从公共入口反查调用方，保留产品规则明确的差异。 手机新建页的表单编辑与恢复、 工作区选择、 worktree 偏好同步、 语音与光标、 模型运行选项校准和 待发消息的会话适配可直接测试； 创建前的附件与草稿写盘复用 persistNewSessionCreationDraft。 最小草稿、附件与异步夹具复用 fixtures/newSession。 测试优先直接 import 生产模块或挂载真实 hook；价值门槛与源码契约的适用范围见 工程约定 §3.2，选测入口见开发流程。 创建中继续输入、离线历史与后台失败等已发生过的回归，见任务回归场景。
| 路径 | 说明 |
|---|---|
apps/ |
终端产品（desktop、mobile）与随包分发的二进制资产 |
packages/ |
客户端共享能力包（与 render／main 解耦，详见下表） |
config/ |
区域端点清单（CN / Global 的公共配置与本地 dev 模板）；新 worktree 的本地配置准备见环境安装 |
scripts/ |
仓库级工程脚本：dev 启动包装、agent 二进制拉取（ensure-agent-binaries.mjs）、i18n／endpoint／文档等校验 guard、worktree 管理 |
tools/ |
claude／codex／ripgrep／pi 四个 Desktop runtime 的版本 pin（latest.json）与更新器（update.mjs） |
docs/ |
规则文档：dev-rules/（工程）、product-rules/（产品）、design-rules/（设计入口）、legal/ 等 |
| 路径 | 说明 |
|---|---|
apps/desktop |
Cindy 桌面客户端（Electron + Vite），源码分 main/（主进程：业务逻辑、maker-host／maker-ipc、localDb、device-link、mcp-integrations、cindy-brain 等）、renderer/（纯渲染 UI：features、panels、themes、i18n 等）、preload/（最小桥接层）、shared/（主／渲染共享类型与常量）；SQLite migration 在 apps/desktop/drizzle/ |
apps/mobile |
Cindy 手机客户端（Expo / React Native）：同账号登录、发现并远程控制桌面设备、镜像会话 |
apps/claude-code-bin、apps/codex-bin、apps/ripgrep-bin、apps/pi-bin |
随桌面端分发的预编译 CLI 二进制（按平台分目录）。不是构建包、不进 git 历史；版本由 tools/<kind>/latest.json pin，pnpm install postinstall 按需下载 |
apps/android-platform-tools-bin |
Android platform-tools（adb 等）二进制，当前仅 win32-x64，用于连接安卓设备 |
「主要使用方」按各 package.json 的 workspace 依赖核对；mobile 只直接依赖其中
5 个（auth-client、device-link、maker-shared、model-providers、voice-input-core）。
| 包 | 一句话用途 | 主要使用方 |
|---|---|---|
maker-core |
Cindy 核心：agent 抽象（BaseAgent）、session 编排与事件流，零 Electron 依赖；改动前必读 maker-core-and-agent-behavior.md |
desktop、lizi-mcps、orca-workflow |
design-tokens |
DTCG reference / semantic / 薄 component 字典与 Terrazzo 生成合同 | DS-8 已接 Desktop 生产颜色、主题与通用基础；DS-9 消费现有链路，Mobile 后续独立接管 |
maker-shared |
桌面与手机共享的展示层契约模型，零 React／Electron／Expo 依赖 | desktop + mobile |
maker-cc-manager |
cc-remote：跑在远程 SSH 机器上的 NDJSON RPC 守护进程，封装 Claude Agent SDK，向本地桌面暴露多会话／detach-reattach 能力 | desktop（remote-ssh） |
maker-pi-manager |
pi-remote：跑在远程 SSH 机器上的 PI 单例 daemon（TS NDJSON RPC + unix socket bridge），持有 pi 会话、条件 restart、空闲回收 | desktop（remote-ssh） |
maker-remote-ssh |
SSH remote：连接池、~/.ssh/config 读写、凭据解析，零 Electron 依赖 |
desktop |
maker-scheduler |
定时任务：cron 引擎 + storage／runner／notifier 接口 | desktop、lizi-mcps |
orca-workflow |
Orca 多 worker 协同的 lead 侧：MCP 桥接 + lead prompt；改动前必读 orca-team-architecture.md |
desktop |
device-link |
跨设备远程控制（同账号互联）：envelope 协议、IPC 隧道 allowlist、重连／心跳；零依赖，WS 实现由 host 注入 | desktop + mobile |
auth-client |
平台无关的 Cindy auth-server 客户端契约（zod） | desktop + mobile |
model-providers |
模型供应商目录、Registry 资料合并与路由抽象；先读 模型配置与下发 获取代码导航 | desktop + mobile |
anthropic-compat-proxy |
本地回环 HTTP 代理：剥离 Anthropic 专有字段，让 Claude Code SDK 可经网关访问非 Anthropic 后端 | desktop |
anthropic-responses-bridge |
挂载在 anthropic-compat-proxy 回环 HTTP 代理内部的进程内协议转换处理器：作为 RoutingDecision.localHandler 完成 Anthropic Messages API ↔ OpenAI Responses API 转换 |
desktop |
responses-anthropic-bridge |
本地 Responses → Anthropic Messages 桥：请求、图片／工具／thinking 转换与 Responses SSE 回译 | desktop |
lizi-mcps |
可复用 MCP server 集合（Google 套件、GitHub／GitLab、浏览器、scheduler 等） | desktop |
cindy-tools |
意识（Ghost）系统内部工具集（MCP），含 ghost 总机（ghost_list / ghost_info / ghost_call） |
desktop |
browser-control-runtime |
浏览器自动化运行时适配层（playwright-core + MCP） | desktop、lizi-mcps |
file-browser-core |
文件浏览核心：workdir 扫描、ignore 匹配、ripgrep 搜索；本地后端与远程守护进程共享 | desktop、remote-file-service |
remote-file-service |
远程文件服务：跑在远程 SSH 机器上的 NDJSON RPC 守护进程，封装 file-browser-core | desktop |
github-client / gitlab-client |
GitHub REST v3 ／ GitLab REST v4 客户端，零运行时依赖 | desktop／lizi-mcps |
embedding-client |
OpenAI /v1/embeddings 兼容客户端（走网关） |
desktop |
heartbeat-client |
在线心跳：周期上报维持在线状态，零依赖 | desktop |
lizi-im |
IM 传输层（飞书等 WS 通道）：凭据存储、附件下载、统一发送 API；host 注入适配 | desktop |
project-context |
agent 维护的项目知识层（commit 驱动的 markdown CLI） | desktop（maker-ipc） |
voice-input-core |
语音输入核心：供应商无关的听写状态机与润色守卫 | desktop + mobile |
Desktop 的 main/local-agent/ 提供经 Cindy 主题确认授权的通用本机 Agent API，复用 maker-core 的引擎与内存 Session；应用自己的界面、记录、上下文和业务工具留在调用方。协议、存储和兼容边界见 本机应用接入，独立客户端示例在 scripts/examples/。
Desktop 发行资产统一走 main/downloader/index.ts；通用工具安装位于
main/managed-tools/。接入方法和各业务保留的边界见
校验下载与受管工具安装。