dotagents 源码解析:buildLinkPlan 如何智能识别 link、noop 与 conflict 三种状态
dotagents 源码解析:buildLinkPlan 如何智能识别 link、noop 与 conflict 三种状态
dotagents 是一个面向 AI 编码工具的配置文件管理工具,它把 .agents 目录作为唯一的“事实来源”(single source of truth),再用符号链接(symlink)把 AGENTS.md、CLAUDE.md、commands、hooks、skills 等映射到 Claude、Codex、Factory、Cursor、OpenCode、Gemini、GitHub Copilot 等各家工具的目录。它的核心函数 buildLinkPlan 负责在真正动手改文件前,先“勘察”每一条链接当前处于什么状态,从而决定该新建、该跳过、还是该提示冲突。
下面我们就以源码为线索,拆解 buildLinkPlan 是如何智能识别 link、noop、conflict 这三种状态的。
🧭 先看全景:一次运行的四步走
在深入之前,先理解 buildLinkPlan 在整个工具里的位置,避免“只见树木不见森林”。一次 dotagents 运行大致经历:
| 阶段 | 入口文件 | 做了什么 |
|---|---|---|
| 1. 解析根目录 | src/core/paths.ts | 根据 global/project 作用域算出 .agents 与各工具家目录 |
| 2. 生成映射表 | src/core/mappings.ts | 把 source → targets 的对应关系列成一张表 |
| 3. 构建计划 | src/core/plan.ts | 逐条判断状态,产出 link / noop / conflict 任务 |
| 4. 执行计划 | src/core/apply.ts | 按计划创建链接、备份、跳过或报冲突 |
buildLinkPlan 就是第 3 步,它是整个工具“聪明”的关键——它只读不改,把风险都提前暴露出来。
📋 第一步:把“要链接什么”整理成任务
buildLinkPlan 的第一件事是拿到映射表:
const mappings = await getMappings(opts);
const tasks: LinkTask[] = [];
getMappings 会输出一组 Mapping,每项描述“从哪个源、链到哪些目标、源是文件还是目录”。比如:
claude-md:.agents/CLAUDE.md(存在)或.agents/AGENTS.md(兜底)→~/.claude/CLAUDE.mdagents-md:.agents/AGENTS.md→.factory、.codex、.config/opencode等的AGENTS.mdcommands/hooks/skills:目录级链接,分发到各家工具
紧接着,对每条映射先跑 ensureSourceTask 校验源本身:
- 源不存在 → 生成
ensure-source任务(之后执行阶段会自动创建) - 源存在但“类型不对”(想要文件却是个目录,或反之)→ 直接判为
conflict,理由写成Expected file but found directory
这一步保证了:即便目标目录一片空白,工具也能先“补全源”,再谈链接。
🔍 第二步:analyzeTarget 判定每个目标的三种状态
真正的状态识别发生在 analyzeTarget。对每个目标路径,它按“存在吗?是不是符号链接?指向谁?”三连问下结论:
const exists = await pathExists(target);
if (!exists) return { type: 'link', source, target, kind };
link:目标缺失,或需要重建符号链接
出现 link 任务有三种情形:
- 目标不存在——最常见,首次运行全是
link。 - 指向已正确,但链接写法需要迁移:目标符号链接已经指向
source,但当前是“绝对路径”而理想状态是“相对路径”。此时返回{ type: 'link', replaceSymlink: true },让执行阶段把链接改写成相对形式,保证项目目录改名或迁移后链接依然可用。 - 指向可替换的“兄弟文件”(见下文
relinkableSources)。
noop:符号链接已正确,跳过不动
当目标是个符号链接,且它指向的地址解析后正好等于 source、写法也无需迁移时,返回:
return { type: 'noop', source, target };
noop(no operation)表示“已经是对的,什么都不用做”。这正是 dotagents 可以安全反复运行的底气——第二次运行几乎全是 noop,不产生任何写操作。
conflict:目标被占用,需要用户介入
这是最“谨慎”的分支,覆盖两类情况:
- 符号链接指向了别处:
resolved存在且既不是source、也不在可替换列表里 →conflict,理由Symlink points elsewhere: <resolved>。 - 目标是个“真文件/真目录”:它不是符号链接,而是实打实占着位置 →
conflict,理由Target exists and is not a symlink (file|directory|path)。
conflict 的设计意图是绝不静默覆盖。它把冲突抛给上层,等用户决定是手动处理,还是用 force 强制接管(接管前会先做备份)。
🔄 一个隐藏的小聪明:relinkableSources
注意 buildLinkPlan 里这段:
if (mapping.name === 'claude-md') {
relinkableSources = [
path.join(path.dirname(mapping.source), 'AGENTS.md'),
path.join(path.dirname(mapping.source), 'CLAUDE.md'),
];
}
Claude 的规则文件存在“优先级”:有 CLAUDE.md 就用它,否则回退到 AGENTS.md。于是 buildLinkPlan 给 claude-md 和 gemini-md 特别标注了一份“可替换源清单”。
这样当某条链接原本指向 AGENTS.md,而用户后来新增了 CLAUDE.md 时,analyzeTarget 会发现旧链接指向的是“可替换源”之一,于是返回 link 并带上 replaceSymlink: true,自动把链接切到更优的那个文件,而不是一声不响地报冲突。gemini-md 同理(GEMINI.md / AGENTS.md)。
⚙️ 计划如何被执行:applyLinkPlan
buildLinkPlan 的产物是一个 LinkPlan:tasks(全部任务)、changes(link + ensure-source)、conflicts(冲突清单)。执行由 applyLinkPlan 按类型分流:
| 任务类型 | 执行动作 |
|---|---|
conflict |
计入冲突;若开启 force 且 target !== source,先备份再强建链接 |
noop |
skipped += 1,直接跳过 |
ensure-source |
自动创建缺失的源目录/文件,并记录以便撤销 |
link |
创建符号链接;若 replaceSymlink 且目标是旧链接,则强制替换;覆盖前经 BackupSession 备份 |
其中相对/绝对链接的选择由 getLinkTarget 决定:Windows 上目录链接用绝对路径(junction),其余场景优先生成相对链接以提升可移植性。
✅ 三种状态换来的三大好处
为什么非要分得这么细?因为它让工具同时做到了三点:
- 安全:
conflict不静默覆盖,force前必先备份,误操作可经 “Undo last change” 还原。 - 幂等(可重跑):已正确的链接判为
noop,反复执行零副作用,随时“修复/校准”都无压力。 - 可追溯:
link/noop/conflict三态清晰,状态检查(src/core/status.ts)也能据此把每个目标标记为linked/missing/conflict,一目了然。
🧪 想验证?看看测试用例
这些状态机逻辑都有对应的自动化测试,读它们是最快的理解路径:
- 重复执行不再产生变更:
idempotent apply produces no changes on second run - 强制接管冲突目标:
force apply replaces conflicting targets - 绝对链接迁移为相对链接:
migrates absolute symlinks to relative when supported - 新增
CLAUDE.md后自动切换链接:relinks Claude prompt when CLAUDE.md is added
📁 核心文件清单
- 状态识别主逻辑:src/core/plan.ts
- 任务/计划类型定义:src/core/types.ts
- 映射表生成:src/core/mappings.ts
- 链接目标相对/绝对计算:src/core/link-target.ts
- 计划执行与备份:src/core/apply.ts
- 运行状态检查:src/core/status.ts
小结:
buildLinkPlan把“该不该改、能不能改、要不要问用户”这三件事,用link、noop、conflict三种状态表达清楚。理解它,就理解了dotagents何以做到“简单设置、单一事实来源、随时可安全重跑”。