制品 Schema 规范

所有 Apothem 生态系统制品的逐类 YAML frontmatter 模板与必填字段。

权威来源。 机器可读、由闸门强制执行的契约， 是 src/apothem/schemas/ 下的逐类 JSON Schema， 即 agent.schema.json、command.schema.json、skill.schema.json 等。 skill 和 command 的 schema 声明了 additionalProperties: false，因此会拒绝未知键； agent、输出样式与 plan 的 schema 则声明 additionalProperties: true。 本页与 frontmatter-schema.mdx 是这些 schema 的两份人类可读投影： 本页承载逐类的模板与完整示例， frontmatter-schema 页面则提供简明的必需键索引。 若某一页与 JSON Schema 不一致， 以 schema 为准。

概述Copy Anchor Link

Apothem 源码树中的所有制品（位于 src/apothem/ 下以及根配置表面中）都必须包含一个 YAML frontmatter 块（位于 --- 分隔符之间），其中带有特定于其制品类型的必填字段与可选字段。本文档为每种类型定义规范 schema。

通用规则：

• frontmatter 符合 YAML 1.2
• 所有字符串值都使用双引号，空字符串写作 ""
• 字段顺序：必填字段在前，可选字段按相关性分组
• frontmatter 中的注释使用 # 加一个空格：# comment
• 路径值必须为相对路径（不带前导 /），并使用正斜杠（/）以保证跨平台兼容性

版本约定（带版本的制品类别——命令、辅助器、技能、CLAUDE.md）：

• version 为语义化版本（MAJOR.MINOR.PATCH）。破坏性的模式或契约变更递增 MAJOR；增量式的非破坏性变更（新的可选字段、新增章节、新增反模式）递增 MINOR；在不破坏契约的前提下修正现有指令的行为变更，递增 PATCH。
• 拼写修正、链接修正、格式调整，以及仅限注释或仅限文档的编辑，都不改变 version。只有行为变更才会递增它。
• updated 是最近一次编辑的 ISO 8601 日期（YYYY-MM-DD）。它必须随每次 version 递增而改变；在不递增版本的拼写或链接修正中，它同样会改变。
• 新工件从 v0.Y.Z 起步。提升到 vX.Y.Z 表示该工件的契约已足够稳定，可作为公开承诺。
• 计划套件不适用本约定。计划套件的错字修正会递增该套件版本的 PATCH 号（vX.Y.Z 变为 vX.Y.(Z+1)），并追加一行修订历史。开发者指南在其计划套件修订一节中描述了计划套件规则。

Schema：规则Copy Anchor Link

路径模式： src/apothem/rules/*.md

用途： 行为强制规定与操作指令。

必填字段Copy Anchor Link

---
name: "kebab-case-identifier"
description: "One-line description"
pathFilter: "**/*.py, **/*.toml"
alwaysApply: true | false
---

可选字段Copy Anchor Link

规则不带任何可选 frontmatter 字段，并且——与其他制品类别不同——也不带 version / updated / scope / portability 字段。上述四个必填字段就是由 frontmatter_grep 强制执行的完整规则 frontmatter 契约。

示例Copy Anchor Link

---
name: "operational-mandates"
description: "Behavioral definitions for CM-1 through CM-10: violation indicators and recovery actions"
pathFilter: ""
alwaysApply: true
---

# Rule: Operational Mandates
...

Schema：命令Copy Anchor Link

路径模式： src/apothem/commands/*.md

用途： 斜杠命令定义（/plan-execute、/freshify 等）。

必填字段Copy Anchor Link

---
name: "command-name"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "What this command does"
argument-hint: "[argument-pattern]"
disable-model-invocation: true | false
portability: "universal"
allowed-tools: "Read, Glob, Grep"
---

可选字段Copy Anchor Link

命令不带任何可选 frontmatter 字段——上述八个必填字段就是由 command.schema.json（additionalProperties: false）强制执行的完整命令 frontmatter 契约。

示例Copy Anchor Link

---
name: "plan-execute"
version: "X.Y.Z"
updated: "2026-04-20"
description: "Executes a specific phase from a Master Plan Suite with conformity checking and quality gates"
argument-hint: "[path/to/plan-suite/] [phase-id] [--dry-run]"
disable-model-invocation: true
portability: "universal"
allowed-tools: "Read, Glob, Grep"
---

# /plan-execute — Execute a Specific Phase
...

Schema：辅助器Copy Anchor Link

路径模式：

src/apothem/agents/*.md

用途： 用于并行探索、审计和质量闸门的持久化辅助器定义（也称为委派工作者）。

必填字段Copy Anchor Link

---
name: "agent-name"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "What this agent specializes in"
tools: "Tool1, Tool2, Tool3"
disallowedTools: "Write, Edit"
maxTurns: 20
effort: "high" | "medium" | "low"
---

可选字段Copy Anchor Link

permissionMode: "default"       # Permission handling
memory: user | project | local  # Persistent-memory scope; omit for none
pattern: "Research" | "Audit" | "Implementation" | "Quality"  # Agent team pattern
portability: "universal"

示例Copy Anchor Link

---
name: "codebase-explorer"
version: "X.Y.Z"
updated: "2026-04-20"
description: "Deep codebase exploration — find patterns, trace dependencies, discover conventions, map architecture"
tools: "Read, Glob, Grep, Bash"
disallowedTools: "Write, Edit, TodoWrite"
maxTurns: 20
effort: "high"
permissionMode: "default"
portability: "universal"
---

You are a codebase exploration specialist...

Schema：技能Copy Anchor Link

路径模式： src/apothem/skills/*/SKILL.md

用途： 带有检测信号和执行流程的可复用技术定义。

必填字段Copy Anchor Link

---
name: "skill-name"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "What this skill teaches"
archetype: "workflow-template"
userInvocable: true | false
disable-model-invocation: true | false
allowed-tools: "Read, Glob, Grep"
---

可选字段Copy Anchor Link

argument-hint: "[args...]"                           # Usage pattern if userInvocable

示例Copy Anchor Link

---
name: "ecosystem-audit"
version: "X.Y.Z"
updated: "2026-04-20"
description: "Comprehensive blind audit of the apothem ecosystem"
archetype: "audit-template"
userInvocable: true
disable-model-invocation: false
allowed-tools: "Read, Glob, Grep, Agent, TodoWrite"
argument-hint: "[--focus area] [--fix]"
---

## Purpose
...

Schema：钩子Copy Anchor Link

路径模式： settings.json 的 hooks 块，加上 src/apothem/hooks/ 下的 Python 实现。

用途： 声明由事件触发的校验器和状态管理处理器，由宿主在明确定义的生命周期节点调用。

设置文件 SchemaCopy Anchor Link

顶层键 hooks 将事件名称映射到匹配器块数组：

"hooks": {
  "<EventName>": [
    {
      "matcher": "<pattern>",
      "hooks": [
        {
          "type": "command",
          "command": "${PYTHON_BIN}",
          "args": ["${HARNESS_ROOT}/.apothem/support/hooks/dispatch.py", "<EventName>", "<message-name>"],
          "timeout": <seconds>,
          "statusMessage": "<short human-readable label>"
        }
      ]
    }
  ]
}

-m apothem.hooks.dispatch 形式仅用于在设置了 PYTHONPATH=src 的源码检出中进行开发。

必需事件Copy Anchor Link

Claude Code 模板注册四个事件：SessionStart、PreToolUse、PostToolUse 和 Stop。scripts/dev/validate_hooks.py 在 settings.json 中检查下表中的五个事件，这是不同的一组事件，并将其未找到的每一个事件作为警告而非失败报告。PostToolUse 已注册，但不在这五个事件之列。PreCompact 与 PostCompact 属于这五个事件，但未在 Claude Code 上注册（参见钩子参考），因此检查器在 Claude Code 上会对这两者都发出警告。

超时值镜像规范的钩子事件预算——下表为方便读者而复现了这些值；以规范来源为准。

dispatch.py 还在其事件白名单中接受 UserPromptSubmit 和 Notification，以实现向前兼容；两者都没有在随附模板中接线。添加一个采用相同 exec 形式模式的匹配器块即可启用。

Python 层Copy Anchor Link

每条钩子命令都经由同一个 Python 调度器路由：

校验Copy Anchor Link

scripts/dev/validate_hooks.py 强制执行钩子契约：

• settings.json 可解析为 JSON，并声明表中五个事件中的每一个；缺失某个事件是警告，而非失败。
• 全部三个 Python 脚本都存在，并可解析为有效的 Python。
• 由 --context-file 参数引用的所有消息文件都存在。
• src/apothem/hooks/**.py 中不出现硬编码的绝对用户路径（C:\Users\... 等）。
• src/apothem/hooks/ 和 scripts/ 下的 shell 制品仅限于已批准的定位器 / 引导桩。

Schema：CLAUDE.mdCopy Anchor Link

路径： CLAUDE.md（根目录）

用途： 项目范围的 Claude Code 指令。

必填 YAML FrontmatterCopy Anchor Link

---
name: "CLAUDE"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "Project-scoped Claude Code instructions for the Apothem source repository"
scope: "project"
portability: "project-local"
---

章节Copy Anchor Link

CLAUDE.md 以散文式章节编写，详见 CLAUDE.md。没有任何校验器要求固定的章节列表：scripts/dev/validate_ecosystem.py 检查上述 frontmatter 键。

校验清单Copy Anchor Link

每个制品都必须满足以下检查：

Frontmatter 校验Copy Anchor Link

• YAML 在语法上有效（无解析错误）
• 该制品类型的所有必填字段都存在
• name 遵循 kebab-case 约定
• version 为语义化版本（MAJOR.MINOR.PATCH）
• updated 为 ISO 8601 日期格式（YYYY-MM-DD）
• description 为非空字符串，且为单行
• 可选字段与预期的枚举值匹配（如适用）
• 字段名中没有拼写错误（使用 schema 中的规范名称）
• 没有多余的空白或格式问题

内容校验Copy Anchor Link

• 内容在闭合 --- 之后另起一行开始；在 Markdown 系列文件上，规范的 SPDX 头部行是其后的第一项内容
• 没有计划内部引用（符合 CM-7）
• 交叉引用可以解析（若列出了其他制品）
• 链接使用带正斜杠的相对路径

可移植性校验Copy Anchor Link

• 没有硬编码的绝对路径（使用相对路径）
• universal 范围的制品中没有 Windows 专用语法
• 路径分隔符使用正斜杠
• 环境变量使用与平台无关的格式（${VAR} 或工具原生格式）

说明Copy Anchor Link

• 一致性即安全： 规范的 frontmatter 使自动化校验、工具支持和跨制品验证成为可能。偏差会迅速累积。
• 可移植性声明： 并非所有制品都能做到通用。显式声明约束——记录一条注意事项，胜过交付一个无声的缺陷。
• 名称使用 kebab-case： 便于在 URL、脚本和命令行环境中使用。名称应避免空格、下划线和 camelCase。
• 版本递增卫生： 每次改变行为的编辑都必须同时递增 version 和 updated。拼写修正、链接修正和格式调整不改变版本号；新增可选章节或反模式递增 MINOR；结构性重组或契约变更递增 MAJOR。