dotagents 源码解析:buildLinkPlan 如何智能识别 link、noop 与 conflict 三种状态

原创2026-10-31 20:53:031,983 阅读

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.md
  • agents-md:.agents/AGENTS.md → .factory、.codex、.config/opencode 等的 AGENTS.md
  • commands / 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 任务有三种情形:

  1. 目标不存在——最常见,首次运行全是 link。
  2. 指向已正确,但链接写法需要迁移:目标符号链接已经指向 source,但当前是“绝对路径”而理想状态是“相对路径”。此时返回 { type: 'link', replaceSymlink: true },让执行阶段把链接改写成相对形式,保证项目目录改名或迁移后链接依然可用。
  3. 指向可替换的“兄弟文件”(见下文 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,一目了然。

🧪 想验证?看看测试用例

这些状态机逻辑都有对应的自动化测试,读它们是最快的理解路径:

📁 核心文件清单

小结:buildLinkPlan 把“该不该改、能不能改、要不要问用户”这三件事,用 link、noop、conflict 三种状态表达清楚。理解它,就理解了 dotagents 何以做到“简单设置、单一事实来源、随时可安全重跑”。

登录后查看全文
dotagents