什么时候写插件，什么时候 fork

前面六个模块讲的都是「这套设计是什么」。这一页讲「你真要动手改的时候会撞上什么」——这是最容易被架构文章跳过、也最贵的一段。

7.1　判断题：什么时候树外插件就够

先把结论摆出来，再解释：

7.2　一个新 provider 到底要写哪些文件

把 packages/web/web-search-exa 完整摊开——这是一个真实的、在树内跑着的搜索 provider 的全部：

package.json          # 名字、exports、peerDeps（cordis + 它要用的 seam）
tsconfig.json
README.md             # 含 Model Experience 三节 + 已知限制节
README.zh.md          # 中文对照，与英文等权威
README.i18n.yaml      # 双语一致性记录：两侧的 git blob hash
src/index.ts          # 插件本体：name / inject / Config / apply —— 约 70 行
src/provider.ts       # 真正干活的：请求映射、错误映射
src/types.ts
src/invariant.ts      # 不变量伴生插件（这个包显式声明为空）
tests/exa.spec.ts     # 单测，逐文件 100% 行覆盖
tests/exa.e2e.ts      # 真 API e2e，无 EXA_API_KEY 时自跳过

插件本体本身薄得出乎意料。它的核心就是一个 apply：

/** Cordis 插件名，loader 诊断用。 */
export const name = 'web-search-exa'

/** 它注册进去的那个 seam。 */
export const inject = ['web']

/** 把 Exa 搜索 provider 注册到 `ctx.web`。 */
export function apply(ctx: Context, config: Config): void {
  ctx.web.registerSearchProvider(new ExaSearchProvider({
    apiKey: config.apiKey ?? launchEnvironmentOf(ctx).get('EXA_API_KEY')?.value ?? '',
    baseURL: config.baseURL ?? EXA_DEFAULT_BASE_URL,
    // …其余默认值
  }))
}

文件头那段 JSDoc 才是这个包最值钱的部分，它把角色说得清清楚楚：

这句话是从一次真实事故里长出来的。docs/postmortem/0001 记的就是：一个插件用了 default export，导致 inject 被丢掉。所以现在 「Namespace plugin：具名导出 name / inject / apply，无 default export」 这句话，出现在几乎每个包的 README 的「Export shape」一节里。

那个「空的」不变量伴生插件

src/invariant.ts 值得单独说，因为它体现了一条很少见的规矩。AGENTS.md 写着：「运行时不变量断言的是自己拥有的关系……在没有一个说得通的关系时，一个被解释过的空伴生插件才是正确的。」

/**
 * 没有运行时不变量：这个包除了它所属 seam 已经强制的契约之外，
 * 不暴露任何独立的事件序列或可变数据关系。
 */
const install: InvariantInstaller = () => {}

「我检查过了，这里确实没有可断言的东西，原因是这个」——这比「我没写」多出来的信息，正是 review 需要的。这跟 M4.1.2 那个「审计过的零」是同一套思路：把「有意的缺席」和「忘了」在结构上区分开。

7.3　守规矩的 delta 长什么样

假设你要往这个仓库里加一个包（或者往你的 fork 里加）。除了代码，你还欠这些：

7.4　fork 维护的残酷算术

说服力最强的不是道理，是数字。本站在 commit b150a55 上实测：

表 7.4　「合并数」用 git rev-list --first-parent 数，即真正落在主线上的改动批次；「提交数」是全部 commit。73 天，13,147 个 commit。你可以自己复现：git log --first-parent --since='7 days ago' --oneline | wc -l。

如果你确实必须 fork：三条生存策略

1. 把 delta 分层。能进 cordis.patch.yml 的进配置层，能进新包的进新包，实在必须改的核心文件单独列一张清单——每次同步只需要人工看那张清单上的文件。
2. 让 delta 长在别人不动的地方。加一个新包，冲突概率接近零；改一个既有文件的中间，冲突概率接近一。dsh 的包粒度细到 227 个，恰恰让「新增而不修改」这条路特别好走。
3. 盯着仓库自己的「预发布姿态」。根 AGENTS.md 里有一段叫「Pre-release stance: foundation over blast radius」，明写着「在第一个正式发布时删掉本节」——在那之前，官方明确保留了自由重命名、自由重构包结构的权利，后端会直接拒绝旧的磁盘格式。这段话还在，就意味着你的 fork 随时可能撞上一次大规模重命名。