先读 README 找到要改的内容；涉及项目边界看 SPEC，涉及证据、时效与退役看 生命周期。本仓库的公共内容以中文为主，代码标识、命令、产品名保留原文。
本地环境#
Python 3.11+ 用于维护与出版，Node.js 20+ 用于 health Worker 和阅读交互的离线测试。创建项目内虚拟环境，避免修改系统 Python：
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-render.txt -r requirements-design.txt
PDF 渲染还需要系统 Pango 和合适的中文字体；字体仅从本机读取，不随仓库分发。只跑基础离线检查时无需 PDF 或浏览器依赖。
macOS 已安装 Homebrew Pango/GLib、却遇到 cannot load library libgobject-2.0-0 时，在出版命令前设置本机实际的库目录，例如 DYLD_FALLBACK_LIBRARY_PATH="$(brew --prefix)/lib"。先确认目录确有相应 dylib；这是 WeasyPrint 官方的缺失库排查路径，不是需要再安装一套 Python。
修改应该落在哪里#
正文解释归各自 Markdown；来源登记归 catalog/sources.json；决策模型路线与价格归 catalog/decision-routes.json；内容关系归 catalog/entries.json。请求外壳、任务状态等行为改 examples/ 源码。图形结构改 diagrams/src/*.mmd，导出方法见 图示说明。
作品编排改 catalog/publications.json；章节身份用正文的稳定 chapter 标记，改标题、插章或重排不要改掉已发布的锚点。Observability 费用数值改 catalog/observability-pricing.json，未来计费日期归 catalog/launches.json；tools/content.py 根据 source_cutoff 或明确 as-of 生成对应时间的说明。报告新增为独立条目，历史报告不参与同步。资料架例子改三份 materials/ 原件后，运行 python3 examples/reading-shelf/build.py 重建页面。
先查一项变更影响哪里，再判断哪些候选真的需要修改：
python3 tools/fieldbook.py impact data.decision-routes
python3 tools/fieldbook.py impact-source S117
python3 tools/fieldbook.py due --as-of 2026-11-01
related 是相关阅读；不驱动重写。旧报告只进入历史核对候选，后来的改价不自动成为旧报告的错误。
impact-source 接受来源 ID，先扫描登记条目的正文引用与 JSON sources 字段，再沿同一个 depends_on 查询传播；正文代码、注释、来源定义／附录和总书目不构成使用点。直接引用的条目也进入相应候选组；历史条目仍是传播终点。未找到引用仅表示书内登记范围没有命中，不表示项目未使用该接口。项目采用理由、当前调用和重评条件由项目已有文档持有，参考项目判断任务单。
提交前检查#
python3 tools/fieldbook.py check
python3 tools/check.py
python3 tools/content.py check
.venv/bin/python -m unittest discover -s tests -v
node --test examples/health-worker/worker.test.mjs
node --test tests/*.test.cjs
这些检查默认不登录、不调用模型 API、不创建云资源。搜索回归使用实际生成的小节索引，构建后运行 node --test tests/*.test.cjs；页面变化后看桌面与手机真实渲染、真实问法跳转、释义的 Escape／焦点返回和无 JavaScript 阅读。恢复演示还要验证场景切换、时间、播放与重置。图示变化后查看 SVG；出版变更按 出版流程 检查冻结版次。
词条定义只改 docs/glossary.md 的对应首段，网页与冻结版次自行读取。恢复演示数据由 tools/recovery_demo.py 调用现有 Jobs 模型生成；不要在 JavaScript 或说明文字里另写一份状态判断。读者可以直接使用离线恢复工单。入口路线与任务状态的手机图由 python3 tools/figures.py 同源生成，改后同时复看横版与窄版。
提交内容与证据#
新增实践从可公开的失败因果开始，重新构造合成输入；不要把私人生产目录复制过来再删账号。说明实际运行的命令、观察结果和没有证明的部分。源码测试、来源核验、云端实测分别记录。修改措辞或重新排版不能刷新产品事实核验日期。
提交前检查完整 diff 与 staged files。私人记录、原始聊天、账号配置、凭据、临时 QA 文件、依赖缓存不进 Git。开发产物留在被忽略的 .build/；继承的 r3 出版物在 dist/ 固定保留，仅用于历史引用。新内容不得覆盖它们。
贡献时只提交你有权提供的材料；除非另有明确约定，对相应材料的贡献按 许可与权利范围 中已有的条款提供，不表示转让著作权。新引入的第三方材料须保留适用许可与来源，不得套用项目默认许可覆盖。合入主分支后，现有 workflow 会更新静态阅读站；新增远端、域名、云端实验或收费操作需要独立授权。
站点构建、部署失败处理与回退见阅读站运行说明。
