文档 / extending / custom-kinds

自定义 kind

28 种 kind 在 v1 的 parser 里是写死的。新增一种要改 4 个文件，再加一份 Tier-2 RFC。 一种新 kind 进规范，按 1 周评审周期算。

什么时候该加 kind

三个条件都满足再动手：

1. 28 种里没一种装得下你领域要的结构。
2. 这个结构通用到能服务多个 corpus，不止你一家用。
3. L3 检查器需要对它的语义做推理，否则一个 type 原子加 tag 就够了。

如果只是你自己的 corpus 在用，正确答案通常是：一个 type 原子，再在 domain.yaml 里加一项 axes。

要改的 4 个文件

1. 类型定义 —— packages/types/src/ast.ts

// Add the literal to the union
export type AtomKind =
  | 'fact' | 'term' | 'value' | 'category'
  | 'example' | 'counter-example' | 'source' | 'metric'
  | 'step' | 'check' | 'transform' | 'tool'
  | 'method' | 'rule' | 'taxonomy' | 'pattern'
  | 'anti-pattern' | 'type' | 'constraint'
  | 'collection' | 'scope' | 'tradeoff' | 'principle' | 'feedback'
  | 'persona' | 'voice' | 'template' | 'provocation'
  | 'recipe';   // ←  your new kind

2. Lexer 关键字 —— packages/parser/src/lexer.ts

const KEYWORDS = new Set<AtomKind>([
  'fact', 'term', 'value', 'category',
  // ...
  'recipe',   // ← here
]);

3. L1 schema —— packages/compiler/src/checker-l1.ts

const SCHEMAS: Record<AtomKind, FieldSchema> = {
  // ...
  'recipe': {
    required: ['ingredients', 'steps', 'serves'],
    optional: ['source', 'time-minutes'],
  },
};

4. Chunker splitter —— packages/compiler/src/chunker.ts

const SPLITTERS: Record<AtomKind, Splitter> = {
  // ...
  'recipe': recipeSplitter,
};

function recipeSplitter(atom: AtomDeclaration): ChunkLevels {
  return {
    summary: `# ${atom.name}\n\n${atom.fields.find('description')?.value}`,
    core: ...,
    full: ...,
  };
}

5. 加一个 fixture 测试

// packages/parser/test/fixtures/atom-recipe.prime
recipe Spaghetti {
  id: "@kitchen/recipe-spaghetti"
  version: "1.0.0"
  description: "Classic spaghetti."
  domain: cooking

  ingredients: [
    { name: "spaghetti", weight-g: 200 },
    { name: "garlic", count: 3 },
  ]
  steps: [...]
  serves: 2
}

// packages/parser/test/parser.test.ts
test("parses recipe kind", () => {
  const ast = parse(readFixture("atom-recipe.prime"));
  expect(ast.atoms[0].kind).toBe("recipe");
});

6. 提 RFC

带这 5 处改动开 PR，附一段简短理由（要解决什么问题、考虑过哪些替代方案、预期影响）。 Tier-2 RFC 的意思是：1 位协议组成员评审，加 7 天异议窗口。详见 governance.md。

YAML 声明的 custom-kind（路线图）

v0.2 计划中：在 domain.yaml 里用 YAML 直接声明一种 kind，不用 patch parser。 取舍是：你拿到了结构，但 L3 不会对这种 kind 做语义推理。详见 roadmap。