为 Apothem 做贡献——开发者指南

本指南帮助开发者以 SOTA 质量标准维护并扩展 Apothem 生态。

快速参考：制品类型Copy Anchor Link

本指南涵盖五种制品类型，每种都有各自特定的用途。规则、命令、辅助器和技能带有 YAML frontmatter；钩子注册在 hooks.json 和 settings.json 中，不带 frontmatter。输出样式是另一类制品，带有两个必填的 frontmatter 键，即 name 和 description；参见 frontmatter schema。

工具适配器契约Copy Anchor Link

工具的身份与能力事实位于 src/apothem/lib/harness_registry.py。只有当以下各个表面彼此一致时，一项工具变更才算完成：

项目作用域的适配器必须设置 requires_project = True，在生命周期方法上接受 project: Path | None，并在写入之前拒绝缺失或不安全的项目根目录。用户作用域的适配器必须将路径保持在该工具文档所述的用户配置根目录之下。

黄金夹具策略Copy Anchor Link

tests/fixtures/harness-golden-plans.json 记录注册表中全部十七个工具的公开安装计划形态：公开 ID、物化模式、源集合/模板路径，以及 <ROOT> 下规范化后的目标路径。当注册表、清单或模板的目标行为被有意更改时，请在与源变更相同的提交中更新黄金夹具，使差异能显示出行为的变化量。

写入前验证Copy Anchor Link

共享安装驱动在第一次写入之前验证每个源与目标。它会拒绝缺失的清单源、目标路径遍历、位于所选根目录之外的目标路径，以及符号链接穿越。试运行执行相同的验证，并在不创建文件的情况下返回结构化的 skipped 或 unchanged 结果。

脱敏与示例数据Copy Anchor Link

配置档案诊断会对 token、secret、password、credential、API key、private key、authorization、auth 以及形似 header 的字段进行脱敏。文档、夹具、示例和 JSON 片段使用 example.invalid、Example User、example-user 以及显而易见的占位符，而不是看起来像真实机密或个人账户的内容。

动笔之前：规范 schemaCopy Anchor Link

机器可读、由闸门强制执行的契约，是 src/apothem/schemas/*.schema.json 下按类别划分的 JSON Schema——additionalProperties 会拒绝未知键，因此合规闸门拥有最终决定权。 有两份供人阅读的投影跟随这些 schema：site/content/docs/reference/frontmatter-schema.mdx（必填键索引）和 site/content/docs/reference/artifact-schema.mdx（按类别的模板与完整示例）。当某个页面与 JSON Schema 不一致时，以 schema 为准。

• 阅读 src/apothem/schemas/ 下对应你的制品类型的 JSON Schema
• 阅读 site/content/docs/reference/artifact-schema.mdx §“Schema”，获取模板和一个完整示例
• 复制必填字段，填入必需的值，并按需添加可选字段

frontmatter 快速检查Copy Anchor Link

每个制品的 frontmatter 都必须通过以下检查。version、updated 和 portability 这三项检查只适用于带有对应键的类别：规则一个都不带，技能不带 portability。

✓ Valid YAML syntax (use tools: `yamllint` or PowerShell `ConvertFrom-Yaml` where available)
✓ All mandatory fields present (per schema for artifact type)
✓ name: uses kebab-case
✓ version: semantic MAJOR.MINOR.PATCH
✓ updated: ISO 8601 date (YYYY-MM-DD)
✓ description: single-line, non-empty
✓ scope fields valid per artifact type (rules: pathFilter + alwaysApply; CLAUDE.md root: scope)
✓ portability: string, for example `universal` (the schemas do not enumerate its values)
✓ No typos in field names — must match canonical schema exactly
✓ Optional fields use correct enum values

命名约定Copy Anchor Link

制品名称（kebab-case）Copy Anchor Link

• 规则： operational-mandates、clean-room-generation、context-management
• 命令： plan-execute、plan-spec、plan-generate
• 辅助器： codebase-explorer、convention-auditor、quality-gate
• 技能： plan-suite、ecosystem-audit

模式：小写，单词之间用连字符，不含空格或下划线。

文件命名Copy Anchor Link

• 规则： {name}.md
• 命令： {name}.md
• 辅助器： {name}.md
• 技能： 位于文件夹 src/apothem/skills/{name}/SKILL.md 中（大小写须精确：SKILL.md）
• 钩子： 位于文件夹 src/apothem/hooks/ 中。所有事件处理器都用 Python 编写。Claude Code settings.json 模板中的每条钩子命令都使用 exec 形式：command 是在安装时解析的解释器占位符 ${PYTHON_BIN}，args 则保存脚本路径及其参数。该模板通过绝对路径运行 ${HARNESS_ROOT}/.apothem/support/hooks/dispatch.py <event> [<message-name>] 和 ${HARNESS_ROOT}/.apothem/support/conformity/gate.py --hook，因此已安装的副本无需可导入的 apothem 包。Claude Code 插件则改为在 src/apothem/hooks/hooks.json 中注册钩子，这些钩子是通过 bash 运行 hooks/lib/bootstrap.sh 的 shell 命令；该存根会定位 Python 并运行 dispatch.py，因此处理器仍然是 Python。在 hooks.json 和 Claude Code settings.json 模板中注册新钩子。dispatch.py 将 SessionStart 路由到 session_start_bootstrap.main()，并将其他每个白名单内的事件路由到 emit_hook_context.main()。src/apothem/hooks/ 或 scripts/ 下唯一允许的 shell 存根是六个定位器与引导文件（find-python.{ps1,sh}、find-pwsh.{ps1,sh}、bootstrap.{ps1,sh}）；任何其他 .ps1 / .sh 文件都无法通过 scripts/dev/validate_hooks.py 的卫生检查。

交叉引用Copy Anchor Link

引用其他制品时，使用精确名称：

• 规则："operational-mandates"（name 字段值）
• 命令：/plan-execute（面向人类的文档中带斜杠；代码中不带）
• 辅助器：codebase-explorer（name 字段值）
• 技能：plan-suite（name 字段值）

在正文叙述中绝不要使用文件路径或截断的名称。

可移植性：Windows 与 UnixCopy Anchor Link

每个命令都必须在 portability 字段中显式声明其可移植性状态。辅助器可以声明。技能、规则和输出样式不带 portability 字段。

通用Copy Anchor Link

• 在 Windows、macOS 和 Linux 上的行为完全相同
• 不对 shell 作任何假设
• 路径使用正斜杠（/）
• 没有硬编码的绝对路径
• 没有 Windows 特有的 PowerShell 语法

portability: "universal"

通用但带 Windows 注意事项Copy Anchor Link

• 在各 POSIX 主机上通用；所指明的注意事项适用于内容中声明的 Windows 平台变体
• 在内容中显式记录该注意事项
• 示例：“Win 10 之前的 Windows 不支持符号链接”

portability: "universal-with-windows-caveats"

在标题之后紧接着用一条说明记录该注意事项。

仅 Unix / 仅 WindowsCopy Anchor Link

• 明确限定于单一平台
• 在 Apothem 中很少见——大多数应当是通用的
• 仅当平台特有的功能不可或缺时才使用

portability: "unix-only"

在制品的第一节中记录原因。

作用域：始终生效与路径过滤Copy Anchor Link

始终生效Copy Anchor Link

规则在所有位置都适用。有五条规则始终生效：agnostic-posture、authority-inquiry、session-closure、context-management，以及规则索引（apothem-rule-index）。这一集合之所以很小，是因为每条始终生效规则在每个会话中都会占用上下文。

pathFilter: ""
alwaysApply: true

路径过滤Copy Anchor Link

规则根据文件路径有条件地适用。

pathFilter: "**/*.py, **/*.toml"
alwaysApply: false

pathFilter 使用 glob 模式（与 .gitignore 格式相同）。当某个文件匹配该过滤器时，规则即被激活。

版本语义Copy Anchor Link

每个带版本的制品都带有其自身的语义化版本（MAJOR.MINOR.PATCH）。命令和技能要求带有它，辅助器和输出样式可以带有它，规则则不带：

• PATCH——行为层面的变更，在不破坏契约的前提下修正现有指令。
• MINOR——增量式的非破坏性变更：新的可选章节、新的可选 frontmatter 字段、新的示例。现有使用方无需任何改动即可继续工作。
• MAJOR——破坏性的 schema 或契约变更：移除章节、重命名字段、改变现有指令的行为，以及要求下游制品作出适配的变更。

拼写修正、链接修正、格式调整，以及仅限注释或仅限文档的编辑，都不改变版本号。只有行为变更才会递增版本号。此类编辑仍需更新制品的 updated 日期。

示例：

• vX.Y.Z → vX.Y.(Z+1)（PATCH：修正了一条会改变行为的指令）
• vX.Y.Z → vX.Y.Z（不递增：拼写或链接修正；updated 随之变更）
• vX.Y.Z → vX.(Y+1).0（MINOR：新增一个可选章节）
• v0.Y.Z → v(0+1).0.0（MAJOR：宣布契约稳定；新制品以 v0.Y.Z 起始）
• vX.Y.Z → v(X+1).0.0（MAJOR：移除必填 frontmatter 字段）

对于带有 version 和 updated 的制品，在每次改变行为的编辑中，一并提升这两个字段。对于捆绑了制品变更的发布，在生态级的 CHANGELOG.md 中追加一条相应的行。

计划套件修订Copy Anchor Link

上文的工件规则不适用于计划套件。计划套件的版本是其 MASTER-PLAN.md 页首与修订历史表中记录的 vX.Y.Z 值。计划套件的错字修正属于一次修订，应递增 PATCH 号。/plan-review 的第 10.2 步负责确定分类，并追加修订历史行。

• vX.Y.Z → vX.Y.(Z+1)（计划套件，错字修正：PATCH）
• vX.Y.Z → vX.Y.Z（工件，错字修正：不递增；适用上文的工件规则）

何时编辑制品Copy Anchor Link

规则Copy Anchor Link

• 将必需/可选结构视为承重结构——重构它会波及每个依赖它的制品。
• 随着理解加深，精炼反模式、严肃度分级示例和引用。
• 在相关的记忆主题文件中记录任何结构性变更的理由。

命令Copy Anchor Link

• 参数形态是公开契约的一部分——只有在有明确意图时才打破它，并将该变更传播到每个调用方（MAJOR 递增）。
• 保持工作流步骤和返回契约精简且最新。
• 以内联方式记录不明显的步骤顺序。

辅助器Copy Anchor Link

• 让 disallowedTools 保持最小但足够；在它变更时记录理由。
• 随着辅助器角色的成熟，精炼操作原则和返回契约（MINOR 递增）。
• 以内联方式追踪能力变化，以便调用方重新校准预期。

技能Copy Anchor Link

• 保持流程步骤和示例与实际情况同步。
• 检测信号必须反映当前使用中用户的实际措辞。
• 技能一旦超过约 150 行就将其拆分（参见 auto-memory.md § Topic File Management）。

分步指南：添加新规则Copy Anchor Link

1. 评估正交性Copy Anchor Link

这条规则是否与现有规则重叠？在 src/apothem/rules/ 中搜索相关内容。

如果重叠超过 50%，请考虑改为扩展一条现有规则。参见 persistent-conventions-vigilance.md § Artifact Evolution。

2. 撰写内容Copy Anchor Link

遵循以下结构：

• 标题：# Rule: {Title}
• 用途章节
• 义务 / 核心指令（编号、带链接）
• 严肃度分级表（始终必需）
• 反模式章节
• 强制执行章节

3. 创建 frontmatterCopy Anchor Link

使用 site/content/docs/reference/artifact-schema.mdx § Schema: Rules 中的 schema。设置：

• name: kebab-case 标识符
• description: 用于注册表的单行摘要
• pathFilter: 路径过滤规则使用 glob 列表；始终生效规则使用空字符串（""）
• alwaysApply: 始终生效规则为 true，路径过滤规则为 false

规则只携带这四个字段——没有 version / updated / scope / portability / implements。

新规则默认是路径过滤规则。新增一条始终生效规则时，需要在同一变更中扩充核心列表并提高字节上限：列表位于 tests/unit/test_always_on_core.py，上限位于 conformity/always_on_budget_grep.py。配套规则（<parent>-<aspect>）沿用其父规则的 pathFilter，或使用更窄的过滤器。

示例：

---
name: "my-new-rule"
description: "Brief one-liner"
pathFilter: "**/*.py"
alwaysApply: false
---

4. 更新规则 READMECopy Anchor Link

在 src/apothem/rules/README.md 的“Rule families”一节中，向该规则所属系列的表格添加一行：

| `my-new-rule.md` | One-line concern of the new rule. |

选择其关注点与该规则相符的那张系列表格。同时，在 src/apothem/rules/apothem-rule-index.md 中对应需要该规则的情形的那一行里写上这条规则的名称；规则缺失于索引时，tests/unit/test_always_on_core.py 会失败。

5. 追加到 CHANGELOG.mdCopy Anchor Link

在下一个发布的 ### Added 部分下添加一行，描述这条新规则。

6. 运行验证Copy Anchor Link

调用 ecosystem-audit 技能来验证新规则，并聚焦于规则区域：

Invoke the ecosystem-audit skill with --focus rules --fix

确认没有针对你的新规则报告任何错误。

分步指南：添加新命令Copy Anchor Link

命令是诸如 /plan-spec、/plan-execute、/security-audit 等斜杠命令。

1. 确定角色Copy Anchor Link

命令是由用户触发的工作流。只有当命令的 disable-model-invocation 设置为 false 时（步骤 2），模型才会自行运行它。请自问：

• 这是一个用户键入 /command-name 的工作流吗？
• 它是否编排多个步骤？
• 它是否可能超时，或在执行中途需要用户输入？

如果其中任何一项的回答为“否”，那么它很可能是一个技能，而不是命令。

2. 创建文件Copy Anchor Link

路径：src/apothem/commands/{name}.md

frontmatter（来自 site/content/docs/reference/artifact-schema.mdx § Schema: Commands）：

---
name: "my-command"
version: "X.Y.Z"
updated: "2026-04-20"
description: "What this command does"
argument-hint: "[path/to/input] [--flag VALUE]"
disable-model-invocation: false
portability: "universal"
allowed-tools: "Read, Glob, Grep"
---

disable-model-invocation: true 使命令只能由操作者调用；设为 false 时，当某个请求与其描述相匹配，模型可以运行它。只读命令和咨询类命令默认使用 false，其描述以使用场景开头；45 个命令中有 35 个采用该设置。若命令会改变工作树之外的状态，或依赖操作者选择执行时机，则保持 true（10 个命令）。src/apothem/commands/README.md 中的调用表列出了每个命令的设置；新增命令时要为其添加一行。让 allowed-tools 保持只读：遵循该字段的工具会直接运行其中所列的工具，而不先询问。有副作用的工具只能以限定作用域的规则形式授予，例如 Bash(git log *)；schema 会拒绝 "*"，也会拒绝任何一个未带作用域限定而写出的 Bash、PowerShell、Write、Edit、NotebookEdit 或 WebFetch。

3. 撰写内容Copy Anchor Link

结构：

• 标题：# /{name} — Human-Readable Title
• 角色章节（由谁执行）
• 高层级指令
• 带步骤的工作流章节
• 返回契约 / 输出格式

某个工具的技能产出会按 H2 章节把每个命令拆分为一个精简的 SKILL.md 和若干 references/ 文件。为命令只设一个 ## Workflow 章节，闭合每个代码围栏，并在 src/apothem/lib/claude_skill_split.py 中为任何新的 H2 种类进行分类；遇到未分类的种类时，tests/unit/test_claude_skill_split.py 会失败。相关规则见 src/apothem/commands/README.md 中的 Skill-emission split contract（技能产出拆分契约）。

4. 更新 README 与 CHANGELOG.mdCopy Anchor Link

除了步骤 2 中的调用表那一行之外，还要向 src/apothem/commands/README.md 中该命令所在章节对应的表格添加一行；在下一个发布的 ### Added 部分下添加 CHANGELOG 行。

5. 验证Copy Anchor Link

调用 ecosystem-audit 技能，聚焦于命令：

Invoke the ecosystem-audit skill with --focus commands --fix

分步指南：添加新辅助器Copy Anchor Link

辅助器是用于并行工作的持久化委派工作者定义。

1. 识别模式Copy Anchor Link

这个辅助器是否符合下面列出的某种团队模式？

• 研究团队：只读，收集信息
• 审计团队：验证，一致性检查
• 实现团队：并行代码变更
• 质量团队：代码检查、测试、类型检查、安全
• 文档团队：文档更新
• 其他：专项任务

2. 创建文件Copy Anchor Link

路径：

src/apothem/agents/{name}.md

frontmatter：

---
name: "my-helper"
version: "X.Y.Z"
updated: "2026-04-20"
description: "What this helper specializes in"
tools: "Read, Glob, Grep, Bash"
disallowedTools: "Write, Edit"
maxTurns: 15
portability: "universal"
---

省略 model、effort 和 permissionMode，使辅助器继承会话的选择（与宿主无关的姿态）；并且除非辅助器需要持久记忆作用域（user、project 或 local），否则省略 memory。

3. 撰写内容Copy Anchor Link

章节：

• 操作原则（只读、基于证据、二元裁决、穷尽）
• 工作流（编号步骤）
• 返回契约（最大 token 数、结构、必填字段）

4. 更新 README 与 CHANGELOG.mdCopy Anchor Link

向 src/apothem/agents/README.md 中的 Index 表添加一行；在下一个发布的 ### Added 部分下添加 CHANGELOG 行。

5. 测试Copy Anchor Link

在真实场景中部署该辅助器，并验证它按文档所述工作。

分步指南：添加新技能Copy Anchor Link

技能是可复用、可检测的技法。

1. 识别可复用性Copy Anchor Link

在编写技能之前：

• 你是否已经见过这个问题/技法 3 次或更多？
• 它是否可被检测？（是否有某种用户请求模式能标示它？）
• 你能否以可复现的方式将它编码下来？

如果三项的回答都为“是”，就编写一个技能。

2. 创建结构Copy Anchor Link

%%{ init: { "theme": "neutral" } }%%
%% verified: 2026-04-27 %%
%% provenance: site/content/docs/reference/artifact-schema.mdx (skill artifact schema) %%
%% cross-reference: src/apothem/skills/plan-suite/SKILL.md (canonical example) %%
flowchart TD
    accTitle: New skill directory structure
    accDescr: Top-down flowchart of the directory structure for a new skill under src/apothem/skills: a {skill-name} folder holding the required SKILL.md plus optional examples and templates subfolders.
    SKILLS["src/apothem/skills/"]
    SKILLS --> NAME["{skill-name}/"]
    NAME --> SKILLMD["SKILL.md<br/>(main definition · required)"]
    NAME --> EX["examples/<br/>(optional · example workflows)"]
    NAME --> TPL["templates/<br/>(optional · reusable templates)"]

3. 编写 SKILL.mdCopy Anchor Link

frontmatter：

---
name: "skill-name"
version: "X.Y.Z"
updated: "2026-04-20"
description: "What this skill teaches"
archetype: "workflow-template"
userInvocable: true | false
disable-model-invocation: true | false
allowed-tools: "Read, Glob, Grep"
argument-hint: "[args]"               # optional; if userInvocable
---

内容结构：

• 用途
• 何时使用此技能
• 前置条件
• 分步流程
• 常见错误
• 示例

4. 更新 README 与 CHANGELOG.mdCopy Anchor Link

向 src/apothem/skills/README.md 中的 Index 表添加一行，并向 Folder contents 表为该技能的每个文件各添加一行；在下一个发布的 ### Added 部分下添加 CHANGELOG 行。

5. 验证Copy Anchor Link

调用 ecosystem-audit 技能，聚焦于技能：

Invoke the ecosystem-audit skill with --focus skills --fix

提交前验证清单Copy Anchor Link

• frontmatter 通过 YAML 语法检查
• schema 要求的所有必填字段均已齐备
• name 字段使用 kebab-case
• version（仅限带版本的类别；规则不带）为语义化版本（MAJOR.MINOR.PATCH），并且在行为变更时已递增
• 对于你改动过的任何带有该字段的制品，updated 与今天的日期一致
• portability 字段已设置且有效（命令必填，辅助器可选）
• CHANGELOG.md 在下一个发布的部分下、以合适的类别记录了该变更
• 没有计划内部引用（符合 CM-7）
• 交叉引用与其他制品保持一致
• 新制品已登记在其文件夹的 README 索引中
• 制品已经过测试（如适用）
• ecosystem-audit 技能运行无错误
• 内容遵循结构约定（标题格式、章节等）

引用其他制品Copy Anchor Link

使用以下确切约定：

引用规则Copy Anchor Link

See `src/apothem/rules/operational-mandates.md` or shorthand: the Operational Mandates rule.
In prose: ... per CM-1–10 (Operational Mandates rule) ...

引用命令Copy Anchor Link

See `/plan-execute` command. Or: Run `/plan-execute`.
In prose: The `/plan-execute` command handles phase execution.

引用辅助器Copy Anchor Link

Deploy the `codebase-explorer` delegated worker.
In prose: The codebase-explorer worker finds patterns.

引用技能Copy Anchor Link

Use the `plan-suite` skill.
In prose: The plan-suite skill provides the Master Plan Suite template.

引用 CLAUDE.md 章节Copy Anchor Link

See CLAUDE.md § Harness Adapter Pattern.
Or: § Plans Discipline.

代码检查与格式Copy Anchor Link

所有制品都使用：

• Markdown： GFM（GitHub Flavored Markdown）
• YAML： 符合 YAML 1.2
• 行尾： LF（Unix 风格）
• 编码： UTF-8
• 行宽： 内容在 100 个字符处软换行（不使用硬换行）

对 Python 文件使用 Ruff 格式化器 / 代码检查器。对 Markdown，使用 prettier 或同等工具。

测试与度量Copy Anchor Link

运行测试套件Copy Anchor Link

python -m pytest                      # unit, integration, property, conformity, scripts
python -m pytest tests/property       # Hypothesis properties (profile loader, frontmatter, merge)

该套件是封闭的：即使检出位于 $TMPDIR 之下，并且 PATH 上的 python 缺少 CLI 的前置依赖，它也能通过，因为集成测试运行的是正在运行 pytest 的那个解释器，并按最长优先的顺序对嵌套的临时路径和源路径进行标记化。

按包统计的覆盖率Copy Anchor Link

CI 度量三个包，并让每个包遵守各自的下限。它们之中没有任何一个被并入另一个。

该数值是行覆盖率加分支覆盖率，即 coverage.py 在 branch = true 时报告的同一百分比；指标产物还会在 coverage_lines 下记录仅语句覆盖的数值。每个包的下限是实测的行加分支覆盖值向下取整的结果。覆盖率上升时提高下限；绝不要为了让某项变更通过而降低下限。在本地检查：

python -m pytest --cov=src/apothem --cov-report=json:coverage.json
python scripts/dev/collect_metrics.py --coverage-json coverage.json --check-floors \
  --skip-hooks --skip-coldstart --harness zed

指标产物Copy Anchor Link

CI 的 metrics 作业在每次推送和拉取请求时运行 scripts/dev/collect_metrics.py，并上传 metrics.json（schema_version: 1）。每个为 null 的值都在 nulls 下附有其原因。

哪些文件算作在启动时加载，是按工具分别制定的规则，取自各厂商文档所述的指令表面。仅携带描述的列表项（技能、命令、子代理）不计入。该规则文本也会写入产物的 rules.always_on_bytes 下：

antigravity     ~/.gemini/{GEMINI,AGENTS}.md, ~/.gemini/config/{GEMINI,AGENTS}.md,
                ~/.gemini/config/rules/*.md with trigger: always_on, project
                GEMINI.md and AGENTS.md. The plugin rules/ folder is not a
                documented launch surface.
claude-code     ~/.claude/CLAUDE.md and ~/.claude/rules/**/*.md without paths:
                frontmatter, plus the project equivalents.
codebuddy       .codebuddy/rules/**/*.md (project and home) unless
                alwaysApply: false, plus CODEBUDDY.md.
codex           ~/.codex/AGENTS.md and the project AGENTS.md.
cursor          .cursor/rules/**/*.mdc with alwaysApply: true, and AGENTS.md.
gemini-cli      ~/.gemini/GEMINI.md and the project GEMINI.md.
github-copilot  .github/copilot-instructions.md and the project AGENTS.md.
hermes          ~/.hermes/SOUL.md, project .hermes.md, AGENTS.md, CLAUDE.md.
                The support tree and apothem/rules/ are not launch surfaces.
kimi-code       ~/.kimi-code/AGENTS.md, project AGENTS.md and .kimi-code/AGENTS.md.
kiro            .kiro/steering/**/*.md with inclusion: always or no inclusion
                key, and the project AGENTS.md.
open-claw       Workspace bootstrap files ~/.openclaw/workspace/*.md.
opencode        ~/.config/opencode/AGENTS.md, the project AGENTS.md, and every
                file the instructions globs in opencode.json match.
qwen-code       The context files named by context.fileName in
                ~/.qwen/settings.json (default QWEN.md), in ~/.qwen/ and the project.
trae            .trae/rules/**/*.md with alwaysApply: true, and
                ~/.trae/user_rules/*.md.
windsurf        .devin/rules/**/*.md and .windsurf/rules/**/*.md with
                trigger: always_on, the global global_rules.md, and AGENTS.md.
zed             The first of .rules, .cursorrules, .windsurfrules, .clinerules,
                .github/copilot-instructions.md, AGENT.md, AGENTS.md, CLAUDE.md,
                GEMINI.md in the project, plus ~/.config/zed/AGENTS.md.
glm             Nothing: GLM is a model backend and loads no instruction files.

行为评估Copy Anchor Link

evals/ 下的套件度量的是行为而非形式：148 个触发用例（每个可由模型调用的命令、技能和子代理都会在其领域内的请求上触发，并在似是而非的请求上保持静默，另有六个仅由用户调用的命令不会自行启动）、32 个结果用例（每个规划阶段、研究阶段和审计维度各一个），以及 6 个规则效果对（某条抽样规则的文本开启与关闭）。这些用例是纯数据，由 python -m pytest tests/unit/test_eval_suite.py 免费校验；运行它们则需付费，且须手动进行。关于 Evals 工作流、本地运行以及如何添加用例，参见运行行为评估。编辑一条带有对应规则效果对的规则之后，运行 python scripts/dev/sync_eval_rule_cases.py。

基准测试Copy Anchor Link

make benchmarks 运行 src/apothem/benchmarks/ 下按类别划分的驱动程序，但 bench_agents.py 除外。每个驱动程序的退出码为：0 通过，1 超出预算，2 错误（被测运行未执行），或 3 未测量。

• bench_hooks.py 按每个事件和匹配器，在真实负载上按原样运行 hooks/hooks.json 注册的每条 shell: bash 命令，并报告中位总耗时、最慢的命令（对照该事件的预算进行检查）以及注入的字符数。无法按注册方式运行的命令（脚本缺少可执行位时退出码为 126）算作错误，而不是通过。
• bench_agents.py 报告 NOT MEASURED（退出码 3）：生成子代理需要一个宿主工具和一次模型调用。make benchmarks 不会运行它。

始终生效预算检查（always-on-budget-grep）统计以空白分隔的单词数，并排除 Bindings 部分和配套指针行。其 JSON 报告还带有 always-on-loaded：某个工具加载的、去除 frontmatter 后的正文的字节数、字符数和单词数，按所有始终生效规则求和。当指向随附的规则目录时，若该总和超过字节上限（报告为 always-on-ceiling-bytes），或规则索引超过其自身的上限，该检查也会失败。Claude Code 加载的规则副本不含 Bindings 部分，因此其加载大小小于该检查报告的数值。

生态审计：运行验证Copy Anchor Link

两个互补的验证表面覆盖整个生态：

可由机器检查（Python 验证器）——在每次提交之前运行：

python scripts/dev/validate_hooks.py       # Hook structure + Python-only hygiene
python scripts/dev/validate_ecosystem.py   # Full tree + frontmatter + delegated hook checks
python scripts/dev/chaos_pass.py           # Adversarial sweep across configured hooks
pytest tests                                    # Unit tests for the hook runtime

由助手驱动——用于交叉引用、叙述和约定审计：

/ecosystem-audit --focus all --fix

它会并行运行：

• 结构审计： 注册表准确性、文件存在性、frontmatter 有效性
• 制品审计： 交叉引用、强制规定覆盖、流水线顺序
• 记忆审计： 记忆文件中的声明与文件系统状态的对照

预期输出：两个表面均为 PASS，且零发现项。

如果报告了 FINDINGS：

• 审查每个发现项的严重程度（Critical / Important / Advisory）
• 立即处理 Critical 项
• 为下一个周期规划 Important 项
• 在下一次迭代中考虑 Advisory 项

有疑问？Copy Anchor Link

请参考：

• frontmatter schema：site/content/docs/reference/artifact-schema.mdx
• 制品生命周期：src/apothem/rules/persistent-conventions-vigilance.md § Artifact Evolution
• 操作强制规定：src/apothem/rules/operational-mandates.md CM-1–10
• 计划套件参考：src/apothem/skills/plan-suite/master-template.md
• 发布说明：CHANGELOG.md