本页目录

Edges · 14 个 verb

边声明的是原子之间带类型的关系。每个 verb 都有写清楚的语义，L3 跨原子检查器靠这些语义做推理，运行时也是顺着这些边走才能满足 contract。

为什么要带类型的 verb，而不是平铺的 `related`

一份平铺的 related: [...]——就像 SKILL.md 里那种 see also——根本没法拿来推理。系统不知道被引用的那个原子到底是依赖、例证、反例还是特化。这四种在运行时要走完全不同的路：

依赖——必须一起加载（requires）
例证——可选的软增强（enhances、example）
反例 / 矛盾——标出来并发警告（contradicts、conflicts）
特化——更窄的版本（specializes、extends）

14 个 verb

Verb	语义	允许的源 kind	允许的目标 kind
`related`	泛关联，提供可发现性。	任意	任意
`requires`	强依赖。A 加载就必须加载 B。	`method`、`pattern`、`persona`、`rule`	任意
`enhances`	软依赖。B 让 A 更好，但可选。	任意	任意
`validates-with`	A 的正确性靠 B 来验证。	`rule`、`fact`、`pattern`	`source`、`metric`、`check`
`contradicts`	A 和 B 的断言互不相容。	任意	任意
`specializes`	A 是 B 的更窄版本。	任意	与源同 kind
`conflicts`	A 和 B 不能同时加载（变体之间的开关）。	任意	任意
`extends`	A 从 B 继承结构。	`type`、`persona`、`method`	与源同 kind
`derived-from`	A 是从 B 算出来 / 推出来的。	任意	任意
`compatible`	A 和 B 可以无冲突地组合。	任意	任意
`supplies-to`	A 的输出被 B 消费。	`tool`、`transform`、`method`	`method`、`tool`
`see-also`	纯交叉引用，不带语义断言。	任意	任意
`includes`	结构性包含（collection→atoms）。	`collection`、`scope`	任意
`relationships`	自由形式的标签关系（兜底逃生口）。	任意	任意

L3 检查器查的是什么

跨原子检查器（checker-l3-cross.ts）在解析后的边图上跑一遍，会暴露三类错误：

循环：requires 链里的环。A requires B，B requires C，C 又 requires A——这种加载顺序运行时根本满足不了。
矛盾：A contradicts B，但某个 method 的 contract 把它俩拉进同一个组合，那要在 agent 看到之前就抛硬错。
kind 不匹配：validates-with 边从一条 rule 指向另一条 rule（而不是指向 source、metric 或 check），属于 schema 错。

代码里走一条边

编译之后，每个原子的边存在它目录旁的 graph.yaml 里。运行时按需读：

// packages/runtime/src/atom-loader.ts (excerpt)
async function loadAtom(id: string): Promise<AtomMeta> {
  const dir = atomDirFor(id);
  const meta  = parseYaml(await read(`${dir}/atom.yaml`));
  const graph = parseYaml(await read(`${dir}/graph.yaml`));
  return {
    ...meta,
    edges: graph.edges, // [{ verb, target, ... }]
  };
  // Note: chunk content is *not* read here. Only metadata.
}

怎么写一条边

边其实就是原子 body 里的一个字段赋值：字段名是 verb，值是一组 atom id。

rule MyRule {
  id: "@my/rule-x"
  version: "1.0.0"
  description: "..."
  domain: my-domain

  claim: "..."
  severity: recommended

  // edges:
  requires: [@my/term-x, @my/term-y]
  validates-with: [@my/source-rfc-1234]
  contradicts: [@my/anti-pattern-y]
  see-also: [@my/pattern-z]
}

加新的 verb

14 个 verb 在 v1 的 parser 里是写死的。要加新 verb，得改 parser 并走一份 Tier-2 RFC。详见自定义 verb。