Cindy 仓库地图实战指南:按用户行为定位代码、包职责与验证入口

原创2026-10-27 07:07:33858 阅读
文章标签:人工智能AI Agent代码智能体大模型AI 技能Agent 记忆工具调用MCP Clients多智能体浏览器控制GUI 自动化本地部署插件系统桌面应用移动开发前端跨平台语音任务调度交互助手

Cindy 仓库地图实战指南:按用户行为定位代码、包职责与验证入口

Cindy 是一个包含 Desktop(Electron + Vite)、Mobile(Expo / React Native)与 30 余个共享 package 的客户端 monorepo。面对近万级源文件,最大的成本往往不是写代码,而是"这个功能到底在哪、我该改哪一层、改完该跑什么测试"。仓库地图(repo-map.md) 正是为解决这个问题而写的定位导航:它先按用户行为给出一条从生产入口、共享判据到测试的路径,再按目录给出代码归属判据。本文以该文档为主线,结合仓库中的实际源码、package.json 与门禁脚本,逐节拆解它的使用方式与背后依据,读完后你可以独立完成"从一句用户反馈定位到可修改文件 + 可运行测试"的完整链路。

一、仓库地图的定位:导航,而非事实源

文档开篇就明确了自己的读取时机与边界,这两句话决定了它应当怎样被使用:

读取时机:首次接触本仓、需要定位某个功能的代码位置、或新增代码/依赖前判断应该放进哪个模块时。 本文只做定位导航:先按用户行为找生产入口、共享判据和测试,再按目录判断代码归属。事实源是各目录的源码、package.json 与 README;发现本文与代码不一致时,以代码为准并顺手修正本文。

可以从这段话提炼出三条使用原则:

  1. 它是入口索引,不是规格说明。每个格子给的是"去哪里看",而不是"行为必须是什么"。真正的约束在 架构不变量、工程约定 等权威文档,以及生产代码本身。
  2. 文档允许滞后,但滞后必须被修正。仓库在演进,地图的价值取决于它和代码的同步程度。当前工作区就是一个例子:apps/ 下实际还有 apps/cindy-headless/(容器友好的 headless runtime,见 README),而地图的 apps/ 表尚未列出它——按文档自身的约定,这类差异应当以代码为准并回写文档。
  3. 它强制你先看"用户行为",再看"目录"。这是地图最重要的设计决策:目录是开发者的组织方式,用户行为才是需求与回归的载体。同一句"消息发出去了但没显示"可能横跨 Desktop 主进程、maker-core、SQLite 与多端链路,从目录出发极易只改到最先找到的那一层。

二、顶层结构:六个目录各管什么

地图把仓库根划分为六块,这张表是理解整个工程的第一层筛子:

路径 说明
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/ 等

结合仓库实际内容,可以把每块再落实一层:

  • config/ 里存的是区域端点真身。config/endpoint.global.json 与 config/endpoint.json 分别对应 Global 与 CN 的 authApiBaseUrl、chatApiBaseUrl、deviceLinkApiBaseUrl、cdnBaseUrl 等字段;本地开发模板是 config/endpoint.dev.json.example。端点字面量受 pnpm check:endpoints(check-endpoint-literals.mjs)约束,所以"区域差异"应该改配置,而不是在代码里写死 URL。
  • scripts/ 是仓库级守门层。除了文档点名的二进制拉取与 worktree 巡检(repo-worktrees.mjs),还有 check-i18n.mjs、check-i18n-glossary.mjs、check-test-hygiene.mjs、ensure-deps.mjs 等。与文档相关的门禁是 pnpm check:dev-docs(dev-docs-contract.test.mjs),它会校验 CONTRIBUTING.md、environment-setup.md、desktop-development.md、mobile-development.md 里的安装与运行命令是否与 workspace 实际脚本一致——改文档不是无风险操作,文档也是被测试的东西。
  • tools/ 的实际内容比文档列举的四个 runtime 更多:除 claude/、codex/、ripgrep/、pi/ 外,还有 codex-package/(codex 的目录型分发与 codex-path 启动脚本)和 model-catalog/(例如 xai-sync.ts 与 sync-xai.mts)。判据以 ensure-agent-binaries.mjs 中的 KINDS 为准:codex 对应 binDir: 'codex-package-bin' 与 module: '../tools/codex-package/update.mjs',说明 codex 走的是"目录分发 + 主执行文件校验"路径,而 claude/ripgrep 是单文件分发。

三、按用户行为定位:五条主干链路

地图的核心是一张"用户行为 → 生产入口与共享判据 → 从哪些测试开始"的表格。它先给出三条使用前提:

模块约束从 Desktop、Mobile、maker-core 进入;下表记录现有入口,不另建任务生命周期框架。register.ts 仍负责部分宿主接线,按表中的函数/IPC 名定位即可,不必从头阅读。

这条提示非常实用:register.ts 体量极大(当前超过一万行),用函数名或 IPC 名做锚点远比顺序阅读高效——例如 sendToSessionInternal 的定义与调用点都可以直接 grep 到(定义位于 apps/desktop/src/main/maker-ipc/register.ts#L11843),SET_PERMISSION_MODE 的分发位于 apps/desktop/src/main/maker-ipc/register.ts#L24405。

3.1 发送、排队、插话、停止后继续

这条链路的关键设计写在 agent-input-coordinator.ts 的模块注释里,值得完整理解,因为它解释了"为什么 renderer 不能做事务 owner":一条用户输入会跨过四个状态 owner——队列 projection、可见气泡、SQLite message row、maker-core dispatch 边界。历史上插话能力反复回归,根因都是 renderer 乐观推进了其中一个 owner,而 main 或 maker-core 尚未真正派发。

注释里给出一张状态迁移表,本文原样继承并按代码补注:

路径 queue 侧行为 bubble / DB 侧行为
send 入队后由 main drain 队首 onAccepted 时只落库;send 返回 accepted=true 后才算已派发
steer marker 阻塞 drain maker.steer 接受后落库,失败则保留或回退队列态
stop 保留并暂停 pending rows 不新建 DB row;只在 abort 边界释放 drain
close abort in-flight steer markers 不新建 DB row;closing 释放 abort lock 后再 drain
retry typed recovery,不重发文本 重新 drain 队首或 clone accepted turn
remove 只允许 pending rows 不删 DB;未接受的 row 从未持久化
edit 只允许 pending rows 接受前更新队列快照

队列契约本身把端点收敛成两个词:agentInputQueue.ts 的 AgentInputDelivery = 'turn' | 'steer',恢复形态则是 { kind: 'queue-head' }、{ kind: 'active-turn', item } 或 null(#L470-L473)。同一文件还定义了"非真人输入"判据 isAutomaticInputOriginKind:scheduler、goal、orca、session 四类来源会推进同一会话,但不代表用户本人介入,因此不能为中断续跑的 episode 额度充值(#L475-L482)。这类共享判据放在 shared/ 的原因也很直接——两侧若各自定义一次,同一条队列行就会产生两种含义。

3.2 普通任务、伙伴与群任务切换权限

跨端判据的实现非常短,因此可以完整看懂 permissionMode.ts:

/** 所有客户端共同识别的权限档位;未知值必须按最安全的 ask 处理。 */
export type SharedPermissionMode =
  | 'ask' | 'default' | 'acceptEdits' | 'plan' | 'auto' | 'bypassPermissions';

export function permissionModeOrAsk(value: unknown): SharedPermissionMode {
  return typeof value === 'string' && PERMISSION_MODES.has(value as SharedPermissionMode)
    ? value as SharedPermissionMode
    : 'ask';
}

/** 从任意非 Full access 档位进入 Full access 时都必须显式确认。 */
export function requiresFullAccessConfirmation(currentMode: unknown, nextMode: unknown): boolean {
  return permissionModeOrAsk(nextMode) === 'bypassPermissions'
    && permissionModeOrAsk(currentMode) !== 'bypassPermissions';
}

两个事实值得记住:一是未知档位 fail-closed 到 ask,因此客户端旧版本遇到服务端新增档位不会误放权;二是文档特别强调的"实际执行权限仍由宿主/引擎决定"——共享函数只负责展示语义与确认门槛,不能替代主进程的授权检查。若要继续深挖运行期流程,按地图指引去读 maker-core 的 session-control 测试 比读散落的 IPC handler 更快。

3.3 重启后发现中断任务、运行中断后续跑

"两者不是同一触发条件"是地图里最有含金量的提醒之一。启动侧的候选来自本地数据库记录的活动轮次标记(markSessionTurnStarted/markSessionTurnEnded 及其 barrier 版本,见 sessionActiveTurn.ts);运行期自动续跑则是一套带预算的分类决策:

export type InterruptedTurnResumeDecision =
  | ({ action: 'resume'; delayMs: number } & InterruptedTurnResumeProgress)
  | { action: 'exhausted'; reason: 'consecutive' | 'episode'; consecutiveAttempts: number; episodeAttempts: number }
  | { action: 'skip'; why: 'disabled' | 'superseded' | 'pending' };

从 interruptedTurnAutoResume.ts 的类型可以读出三层语义:resume 带延迟;exhausted 区分"连续失败"与"单次人工介入周期内累计"两种耗尽;skip 区分 kill switch(disabled)、被新轮次取代(superseded)、已有待处理 attempt(pending)。旁边的 guard state 注释说明了两类计数器的差异:consecutiveAttempts 在"模型有产出或人工介入"时归零,episodeAttempts 只在真人介入时才归零。做这块改动时,先确认你改的是"启动展示候选"还是"运行期续跑预算",避免在错误的层加判据。

3.4 新任务与伙伴选择默认模型

Desktop 侧的默认模型不是"取目录第一项",而是一条有优先级的产品策略。newMakerDefaultTuple.ts 的注释与 DEFAULT_POLICIES 说明了顺序:Codex / Claude 订阅优先,其次服务端指定的 Cindy Auto,最后保留 xAI 回退。四条策略按序是 openai(subscription,codex)、anthropic(subscription,claude-code)、xd(managed,pi,serverMarkedAuto: true、allowOtherModels: false)、xai(subscription,可跑 pi / codex / claude-code)。

resolveNewMakerDefaultTuples 的实现还包含两个易踩坑的细节(#L178-L233):

  • 服务端每个引擎只应标一个默认;管理员恰在两次拉取之间改配置时,Cindy AI 与号池可能各标一个,此时以 Cindy AI 为准,用 sort 排序而非依赖来源列表顺序。
  • 搜索顺序是 serverMarkedAuto → preferred → other 的多趟(pass)遍历,注释写明"earlier account 的 fallback 不能掩盖 later account 的推荐";resolveNewMakerDefaultTuple 只是取第一个结果作为普通新任务默认。

Mobile 侧的入口函数签名同样把"默认来自哪"讲清楚了:newSession.ts 的 resolveNewSessionAutoDefault 接收 hostDefaultsSettled、hostRuntime(被控电脑的新建任务默认,null 表示没有)、rowsAgentKind、catalogReady 等参数,返回 source: 'host-default' | 'catalog-default'。这意味着手机上的默认模型可能是"被控端给的",也可能是"本地目录算的",两者不能混为一谈——调试显示错误时先看 source。

3.5 手机新建任务、创建中继续输入、失败回编辑

这条链路是"跨页面状态"的典型:用户点创建后立刻离开页面、在创建中继续输入、失败后回到编辑态。地图的第二段继续给出可单独测试的拆分点,本文完整继承:

手机新建页的表单编辑与恢复、工作区选择、worktree 偏好同步、语音与光标、模型运行选项校准和待发消息的会话适配可直接测试;创建前的附件与草稿写盘复用 persistNewSessionCreationDraft。最小草稿、附件与异步夹具复用 fixtures/newSession。测试优先直接 import 生产模块或挂载真实 hook;价值门槛与源码契约的适用范围见工程约定 §3.2,选测入口见开发流程。创建中继续输入、离线历史与后台失败等已发生过的回归,见任务回归场景。

源码层面可以验证"先落盘、再建 worktree"的顺序:prepareNewSessionCreation.ts 同时引入 persistNewSessionCreationDraft、registerPendingPrecreatedWorktree、compensatePrecreatedWorktree 与 buildWorktreeCreateRequest,暴露 newSessionCreationPreparationServices 作为测试可替换的持久化/传输边界。newSessionCreation.ts 则提供完整的状态机 API:startNewSessionCreation、retryNewSessionCreation、dismissNewSessionCreation、beginNewSessionReturnToEdit、stashNewSessionDraftForEdit、drainStashedNewSessionDraft、markNewSessionDurableEditReady。要改"失败回编辑",入口是 beginNewSessionReturnToEdit 与草稿 stash/drain 这一组函数,而不是页面组件的事件回调。

四、apps/ 目录:产品与二进制资产

路径 说明
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,用于连接安卓设备

几个便于验证的事实:

  • 二进制确实不入库。根 .gitignore 明确忽略 apps/claude-code-bin/、apps/codex-bin/、apps/codex-package-bin/、apps/pi-bin/、apps/ripgrep-bin/,但 apps/android-platform-tools-bin/win32-x64/ 下的 adb.exe、AdbWinApi.dll 等(#L60-L62)与 source.properties、NOTICE.txt 保留在仓库中。这解释了为什么新 clone 直接 ls apps/ 看不到 claude/codex 目录。
  • runtime kind 的唯一真源是 ensure-agent-binaries.mjs 的 KINDS:claude → claude-code-bin、codex → codex-package-bin(dirDist: true,并要求 codex-package.json、bin/codex-code-mode-host、codex-path/rg 齐全)、ripgrep → ripgrep-bin、pi → pi-bin(dirDist: true,要求 theme/dark.json、theme/light.json、theme/theme-schema.json)。新增 runtime 只需改这一处,dev 启动 guard 与 postinstall 共用它。
  • 安装与按需下载由根脚本提供:pnpm install:agent-binaries、pnpm install:claude、pnpm install:codex、pnpm install:ripgrep、pnpm install:pi;postinstall 走 --best-effort,失败只告警不阻断(见根 package.json 的 scripts)。
  • apps/desktop/src 的四个分区各自可独立搜索:main/、renderer/、preload/、shared/。判据不是"哪个文件最方便",而是这段逻辑需要在哪个进程里运行、是否需要跨进程共享。地图在 packages/ 一节里反复强调的"零 Electron 依赖",正是为了让 shared/ 与 packages/ 在结构上不可能偷偷依赖 renderer 或 main。

五、packages/ 目录:33 个共享包的职责与使用方

地图说明:"主要使用方"按各 package.json 的 workspace 依赖核对;mobile 只直接依赖其中 5 个(auth-client、device-link、maker-shared、model-providers、voice-input-core)。这一点可在 apps/mobile/package.json 的 dependencies 中直接核对,是一个很好的"依赖方向自查"示例:手机端不依赖 maker-core,它通过 device-link 远程驱动桌面。

下表完整继承地图内容,并在两列之外补充了当前仓库中可核对的 package.json 名称差异——目录名不等于包名,用 pnpm --filter 时必须用包名:

包(目录) 一句话用途 主要使用方
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

补充三条从 package.json 核对到的事实,能避免实际行动中的低级错误:

  1. 包名与目录名不一致的样本:packages/lizi-mcps/package.json 的 name 是 @cindy/mcps,packages/lizi-im/package.json 是 @cindy/im,packages/cindy-tools/package.json 的 name 为 cindy-tools(无 scope),project-context 同样无 scope。所以类型检查命令应写成 pnpm --filter <该 package.json 里的 name> run --if-present typecheck,而非按目录猜测。
  2. 地图表未列出但真实存在的包:model-compat(供应商协议兼容与路由策略)、responses-chat-bridge、slack-hook-protocol、wechat-ilink、plugin-protocol、device-link-protocol、opencli-vendor、remote-credentials-native 等同样位于 packages/ 下,apps/desktop/package.json 中可以看到对 @cindy/model-compat、@cindy/plugin-protocol、@cindy/responses-chat-bridge、@cindy/slack-hook-protocol、@cindy/wechat-ilink 的 workspace 依赖。地图定位的是"任务主干包",遇到未列出的包时,判断归依仍按下一节的依赖方向规则。
  3. maker-core 的被依赖范围:grep workspace 依赖可直接确认,当前只有 apps/desktop、packages/lizi-mcps、packages/orca-workflow 声明了 @cindy/maker-core(packages/maker-core 自身除外)。这为"改 maker-core 要连带验证谁"提供了机械答案。

六、本机应用 Agent 接入

地图单独用一节记录了一个非主流程入口:

Desktop 的 main/local-agent/ 提供经 Cindy 主题确认授权的通用本机 Agent API,复用 maker-core 的引擎与内存 Session;应用自己的界面、记录、上下文和业务工具留在调用方。协议、存储和兼容边界见 本机应用接入,独立客户端示例在 scripts/examples/。

需要强调的边界有三条,均可在 local-agent-api.md 中读到:

  • 它不是一个 OpenAI / Anthropic 风格的模型 API。客户端接入的是 Cindy,由 Cindy 管理供应商、凭据、模型路由与 Claude Code / Codex / Pi 执行;调用方只管理自己的界面、记录、上下文与业务权限。
  • 兼容策略是「加字段不换版本」。协议保持 v1,旧客户端可忽略新增能力字段;不提供跨机访问。
  • 凭据边界:示例客户端只用进程内存持有令牌,退出时关闭会话并撤销授权;长期连接的产品应通过 OS 凭据库保存本应用令牌,不得复制供应商登录,命令行参数也不接收秘密。

实现分布在 apps/desktop/src/main/local-agent/ 的 runtime.ts、service.ts、server.ts、messages.ts、confirmation.ts、catalog.ts 六个文件里,"主题确认授权"与"会话内存化"分别对应 confirmation.ts 与 runtime.ts。做这块改动时,地图给出的价值是:你知道不必在 maker-ipc 里找入口,也不必把授权逻辑塞进 register.ts。

七、校验下载与受管工具安装

地图最后两条指向一个横向基础设施:

Desktop 发行资产统一走 main/downloader/index.ts;通用工具安装位于 main/managed-tools/。接入方法和各业务保留的边界见校验下载与受管工具安装。

downloader/index.ts 的契约注释写得很克制,但每条都能用来做 code review 判据:

  1. download() 只会 resolve DownloadResult 或 reject DownloadError,没有第三种返回。
  2. onProgress 上报的是原始传输字节;跨重试的显示归一化由调用方负责(服务器可能拒绝 Range 并从零重下)。
  3. resolve 即意味着 SHA-256 已校验完成,调用方不需要再验一次。

入口层还做了参数校验,可以直接当作接入模板:url 非空、targetPath 必须是绝对路径、sha256 必须是 64 位十六进制、expectedSize/maxBytes 必须是非负安全整数且 expectedSize 不得大于 maxBytes、timeout 的每个值必须是正整数。createDownloader() 返回一个由 Scheduler({ maxConcurrent: 1 }) 支撑的入队函数,注释说明"consumer-owned queue:批量插件下载不会插到应用更新前面"。

verified-downloads.md 补充了更完整的行为合同,这些是接入新资产时最常被漏掉的点:

  • sha256 必填;expectedSize 同时检查响应头与实际字节;maxBytes 在写盘前限制流大小。
  • isUrlAllowed 检查初始 URL 和每一次重定向;统一下载不得放宽调用方已有来源限制。
  • signal 取消排队、请求、缓存/续传哈希与重试等待;连接/闲置超时可重试,timeout.totalMs 只限制取得下载槽位后的活动时长。业务取消与超时分别返回 ABORTED 与 TIMEOUT。
  • 默认保留部分文件以续传;一次性安装暂存目录可用 resume: false,该模式不写续传元数据(避免把一次性授权 URL 留在磁盘),失败时删除部分文件。
  • 默认校验成功后替换目标,失败保留原目标;existingTarget: 'error' 原子拒绝覆盖。校验失败或发布失败不能主动删除旧目标。
  • 同一目标同时只能有一份下载;完全相同参数可复用在途 Promise,来源/策略/回调/取消信号不同则拒绝冲突。
  • 缓存命中同样检查来源策略、大小与哈希;进度只描述当前尝试。

main/managed-tools/ 的 installer.ts 与 archive.ts 负责发行包解压、版本检查、完整代次发布与安装路径发现;调用方传入可信的 ToolArtifact 与用户数据根目录,成功后拿到绝对执行路径,不依赖系统 PATH 或 Homebrew。下载与解压共用 160 MiB 归档上限,下载时在写盘前截停超限内容。典型落地是 GitHub CLI:使用 git-context/ghArtifact.ts 中固定版本的官方发行包与摘要,安装到 userData/managed-tools;Ollama 复用下载层但保留自己的解压与启动布局。

八、地图背后的硬约束:依赖方向与布局树

地图第一段就把依赖方向的权威位置交出去:

依赖方向与解耦约束见 architecture-invariants.md。

该文件把约束收成三条,并把"事实来源"也列成了表:布局树结构定义在 layoutTree.ts,布局持久化在 LayoutStore.ts,面板注册在 registry.ts 与 builtinPanels.tsx。

(1) package 解耦。 package 不 import Desktop Renderer 组件,也不反向 import Desktop Main;关联部分通过初始化或运行时配置/回调注入。这解释了为什么 maker-core、device-link、voice-input-core 的 package.json 描述里都强调"零 Electron 依赖"——描述本身就是约束的一部分。

(2) main 进程禁止运行时动态 import()。 依赖一律顶层静态 import。理由是打包、加载时机与错误路径上的不确定性。这条在 code review 里很容易被忽略,但它没有例外说明。

(3) 主界面布局树不变量。 布局真身是全局递归 split/pane 树;面板身份只认 panelKind,禁止用「左栏/右栏」等当前位置充当业务身份;chat-main 在整棵树中必须恰好一个、始终可见、不可关闭、不可折叠,最小宽 400px;布局是用户级配置而非 session 数据,启动时必须随首帧同步就位,禁止"先画默认布局再跳成用户布局";未注册/沉睡/已抽离的面板允许保留在存档中但不渲染,重新注入后必须原位恢复,不要用清理未知 panelKind 的方式破坏位置记忆。

源码可以佐证这些约束不是纸面要求:layoutTree.ts 的 BUILTIN_PANEL_KINDS 只含 session-list、chat-main、right-tabs 三种内建 kind;createDefaultLayout() 产出的 chat pane 带 minWidth: 400(#L135),默认是会话列表 + 内容区 50/50 竖切(注释说明 0.5 对齐既有 DEFAULT_FRACTION,不能引入视觉变化);校验逻辑显式检查"content 中 chat-main 恰好一个、不可折叠"(#L292-L327);页签组 id 为 TAB_GROUP_IDS = ['left', 'right', 'top', 'bottom'](#L508),与文档描述的"右侧组沿用 right-tabs、边组用 tab-group:<边>"一致。

地图与不变量文档是互补关系:地图告诉你代码在哪,不变量告诉你改法不能越过哪条线。 两者都建议在改布局时至少跑 layoutTree 相关定向测试与 typecheck。

九、实战:用仓库地图完成一次定位

把上面的内容串成一个可复用流程。假设你收到反馈:"手机上新建任务时网络断了,回来后草稿没了。"

第 1 步:判断行为类别。 这是"手机新建任务、创建中继续输入、失败回编辑",直接命中地图第三行第二段,不需要先打开 app/sessions/new.tsx。

第 2 步:锁定生产入口与判据。 已知涉及 prepareNewSessionCreation(先存草稿与附件、再预建 worktree)、newSessionCreation(跨页面乐观创建管线)、persistNewSessionCreationDraft(草稿写盘)、useNewSessionDraftRecovery(恢复 hook)。用纯文本搜索确认符号位置:

rg -n "persistNewSessionCreationDraft|beginNewSessionReturnToEdit|drainStashedNewSessionDraft" apps/mobile/src/session

第 3 步:先看现有测试定义了什么契约。

rg -n "草稿|draft" apps/mobile/src/__tests__/newSessionCreationPersistence.test.ts | head
ls apps/mobile/src/__tests__/fixtures/newSession.ts

地图明确"测试优先直接 import 生产模块或挂载真实 hook",所以这里的测试文件通常就是最接近运行时的事实说明。新增测试前还必须读工程约定 §3.2:必须有新的结果、错误、权限、持久化、协议或时序差异,且新文件单独运行要在 5 秒内。

第 4 步:跑定向验证,不做全仓重跑。

pnpm test:unit:related
pnpm --filter mobile run --if-present typecheck

pnpm test:unit:related 是根 AGENTS.md 指定的默认选测入口;只有跨模块、高风险或基础设施改动才追加更广验证(如 pnpm test:all),最终以 CI 门禁为准。根 package.json 还提供 test:runner(脚本自身测试)、test:unit、test:integration、test:e2e、test:db、test:guard 等分层入口。

第 5 步:如果定位发生在桌面端,先确认进程归属。 需要主进程能力(文件、数据库、子进程、IPC)→ apps/desktop/src/main/;纯 UI → renderer/;跨进程共享的类型与常量 → shared/;可被其他宿主复用的能力 → packages/。违反这条的典型症状是把业务逻辑写进 renderer,之后无法在 Mobile 或 headless 场景复用。

第 6 步:环境不确定时先读环境文档。 首次克隆、创建新 worktree 或依赖失败时,先看 environment-setup.md。当前仓库要求 Node >=22.12、pnpm >=10.7 <11(根 package.json 的 engines 与 packageManager: pnpm@10.33.2),并且需要 Git LFS;pnpm install 的 postinstall 会按当前平台 best-effort 拉取 runtime 二进制,dev 启动 guard 会再确认一次。

十、常见误区与文档维护约定

误区 地图给出的正确做法
从目录出发找功能,先打开最像的页面 先按用户行为查表,再顺着"生产入口与共享判据"进入
把 register.ts 从头读完 按表中的函数名/IPC 名定位(如 sendToSessionInternal、SET_PERMISSION_MODE)
只改最先找到的渠道 地图开篇即要求"同一行为涉及普通任务、伙伴、群、调度、本机与远程入口时,从公共入口反查调用方,保留产品规则明确的差异"
在 renderer 里做排队与持久化 输入事务归 main 的 coordinator,renderer 只提交 intent payload 与可序列化附件/mention
把"启动恢复"和"运行期自动续跑"当成一个判据 两者触发条件不同,分别在 localDb 与 maker-ipc
用目录名执行 pnpm --filter 用该 package.json 的 name(存在 lizi-mcps → @cindy/mcps 这类差异)
发现文档与代码不一致就绕开 以代码为准,并顺手修正文档;文档本身也受 pnpm check:dev-docs 门禁

最后一条值得单独说明:地图不是一次性写成的清单,而是一份需要跟着代码演进的活文档。仓库对此有明确机制——docs/dev-rules/README.md 规定了收录标准(写清触发条件、必须做什么、禁止做什么、验证方法与例外;能被 lint/测试/类型检查强制的必须落到自动化检查),而 AGENTS.md 要求新代码归属模块前先读地图。这意味着"补地图"不是可选的整理工作,而是与改动同批交付的一部分:当你新增了一个用户行为入口,正确做法是同时补上"生产入口与共享判据"和"从哪些测试开始"两格——否则下一个人(或下一个 Agent)会重新经历一遍你刚走过的搜索过程。

十一、延伸阅读入口

登录后查看全文
cindy