文件结构
各阶段沿用本仓起步时的计划:A 是宪法和本设计,B 是结构化的源文件和确定性的编译,C 是反馈与提案 (只观察),D 是限定范围的自动采纳。C 和 D 的目录只预留,不创建。
README.md 本仓首页,英文 A
README.zh-CN.md 同一页的中文版 A
LICENSE Apache-2.0,适用于下面那部分文字以外的一切 A
LICENSE-CC-BY-4.0 CC BY 4.0,适用于 constitution/、rules/
和 skills/ 的文字 A
AGENTS.md 在本仓工作的 agent 遵守的仓库规则 A
constitution/
<YYYY-MM>/ 版目录,目前是 2026-10 (constitution.md) A
index.toml 状态、版、修订号、语言、标题、卷首 A
articles/
<NN>-<id>/ 一条一个目录,带编号 A
article.toml 条本身:标题、引言 A
<NN>[a-z]-<id>.toml 一款一个文件,带编号:状态、
各语言的正文、项 A
generated/ 由源文件构建,提交入库 A
constitution.en.md 英文宪法 A
constitution.zh.md 中文宪法 A
constitution.en.agent.md agent 版,英文 A
constitution.zh.agent.md agent 版,中文 A
docs/
design/ 本设计,一部分一个文件,
由 README.md 索引 A
zh/ 本设计的中文译文,每个文件一份同名译文 A
rules/
<id>.toml 一条通用规定一个文件,含各语言的正文 A
retired-ids.txt 已删除规定的 ID,一行一个 A
skills/
<name>/SKILL.md 一个通用 skill 一个目录,模板文件放在
旁边,原样安装 A
schema/ 规定、fixture 和 overlay manifest 的 schema B
tools/ 一个 uv workspace,每个子目录一个 Python 项目:
compiler/ 宪法编译器,包名 constitution_compiler,
命令 constitution-build A
src/constitution_compiler/
build.py 用下面这些模块构建并检查宪法 A
model.py 源文件在哪里、文件名的格式、
读入后存放的记录结构 A
schema.py schema,以及检查 1 中逐表的格式检查 A
read.py 读入源文件,检查 1 A
checks.py 检查 2 至 5 A
languages.py 各语言之间不同的地方 A
render.py 渲染宪法 A
base.py 检查 7,对照基准提交核对编号,
以及对 git 的访问 A
revision.py 检查 7,对照基准核对修订号 A
tests/ 渲染、检查、基准的测试,以及共用的测试
树 (test_constitution_fixture.py) A
site/ 包 constitution_site,依赖 compiler A
src/constitution_site/
count_tokens.py 统计静态网站显示的 token 数
(count-tokens) A
check_site_anchors.py 检查构建出的网站的链接
(check-site-anchors) A
tests/ 它们的测试,以及 test_site.py,即网站
Hugo 模板的测试 A
checks/ 包 repo_checks,本仓自己的检查 A
src/repo_checks/
check_instruction_changes.py 指令文件单独变更
(check-instruction-changes) A
check_design_translation.py 设计的中文译文与英文同步
(check-design-translation) A
lint_zh_sources.py 对 zh 源文本跑 limae (lint-zh-sources) A
tests/ 它们的测试 A
<others> 编译器、检查程序、私有词扫描程序 B
examples/
overlay/ 一份虚构的私有 overlay B
golden/ 它的编译输出和构建 manifest B
fixtures/
static/ 确定性的 fixture,happy 与红线 B
behavior/ 真实 agent 的场景 C
cases/<id>.md 已裁决的案例 C
proposals/ 为采纳流水线预留 D
web/ 静态网站的 Hugo 项目:hugo.toml、
content adapter、布局、样式表、
脚本、i18n A
themes/hugo-book/ 主题,一个固定在某个提交的 git submodule A
site/ 构建出的静态网站,不提交 A
.github/workflows/ CI A
.github/assets/ README 的图标、示意图和截图,
分浅色与深色 A
.pre-commit-config.yaml 提交钩子 A
pyproject.toml workspace 的根:成员、Python 版本、
limae、pre-commit 和 Python 检查程序的
版本固定,以及它们的配置 A
uv.lock workspace 唯一的锁文件,由 uv 写出 A
.python-version uv 运行 tools/ 所用的 Python 次版本号 A
.fleet/config.json 给 fleet 用的 issue 跟踪元数据;
工具链从不读它 A有三项阶段 B 的内容提前开始。tools/ 随宪法的构建在阶段 A 开始:宪法本身就是从一条一个目录、一款一个文件的源文件编译出来的 (见源文件格式)。rules/ 也在阶段 A 开始,放从宪法中移出的具体做法。skills/ 在阶段 A 只是普通的目录,每个目录放一个 SKILL.md,带通常的 skill front matter (name、description),不带本仓自己的元数据。编译和检查规定、构建指令文件,仍留在阶段 B。
阶段 B 按下面的顺序实现:schema/ 和 schema 检查程序,rules/ 的其余部分 (由迁移填充),编译器,examples/ 和漂移检查,引用检查程序和放宽检查程序,私有词扫描程序,fixtures/static/ 和 fixture 检查,最后是加载验证。每一步单独就能用。
宪法中关于修改的那一条所保护的,是宪法的正文 (protected-text);在核心部分,它是版目录下的源文件 (index.toml 和 articles/),以及由它们构建出的文件的措辞。改动正文就是修正案,按 approving-amendments 的规定生效 (见批准修正案)。其余一切都是依照 rule-evolution 的普通变更 (ordinary-tooling),与其他变更一样审查和测试:tools/ 和 schema/ (编译器、检查程序、fixture 检查的运行程序)、.github/workflows/、fixtures/ 和 examples/golden/。人的注意力放在宪法说了什么上;工具靠单元测试和正常路径的端到端测试保证可靠,不靠人去读。生成文件只能通过重新构建来改。对构建脚本的改动,如果只改变生成文件的编号或版式,是普通变更,它的 pull request 要展示生成文件的 diff,让人扫一眼格式;如果改变了它们的措辞,就改变了正文,是修正案 (protected-text)。构建脚本自己写的说明 (文件头一行、废止说明,以及 agent 版里的开头说明和代替条文正文的那句说明) 不是宪法的正文:它们随脚本一起改,走普通变更 (ordinary-tooling),只能说正文已经说过的话 (宪法约束每一个 agent,terms.agent)、指向完整的正文、说明版式;会改变含义的说明,要先有修正案。agent 版略去哪些条文由源文件设定 (audience,见宪法),所以改动它是修正案。