CODEX KNOWLEDGE

Token Pool README 与 project.json 写作模式拆解

2026/04/26 13 min read CODEX KNOWLEDGE TOKEN POOL README PROJECTJSON WRITING PATTERN

Token Pool README 与 project.json 写作模式拆解

说明：本文保留为 README.md + project.json 配对写法的专项拆解。更上位的全局规范见 engineering-document-writing-standard.md。

1. 目标

这份规范不是复述 Token Pool 的业务内容，而是拆解它的文档写法，沉淀为我后续在其他项目里也能复用的写作模板。

核心结论只有一句：

  • README.md 写给人看，是控制平面手册、唯一真源和工程运行说明。
  • project.json 写给机器看，是最小机器可读合同、路径索引和自动化入口表。
  • 两者必须互相映射，但不能互相复制粘贴成两份松散文本。

2. 总体写法模型

以后遇到中大型工程仓库，默认采用这套双文件模型：

README.md
  -> 面向人类
  -> 解释当前真相、边界、禁止事项、验证顺序、路线图、附录
  -> 承担唯一真源职责
 
project.json
  -> 面向机器
  -> 给出固定键名、路径、URL、脚本、工作流、服务名、兼容入口
  -> 承担自动化发现与索引职责

这套模式的关键不是“一个长一个短”，而是：

  • 人类文档负责语义、上下文、边界和解释。
  • 机器文档负责稳定字段、工具读取和程序化索引。
  • 机器字段在 README 顶部必须能找到人类解释。
  • README 里的 canonical 入口、runtime 根、public URL、health/debug 契约，必须与 project.json 一致。

3. README.md 写法规范

3.1 角色定位

以后我写这类 README，默认把它写成下面三种身份叠加：

  • 项目说明入口
  • 工程实施手册
  • 控制平面真源文档

不要把它写成营销介绍，也不要写成零散开发笔记。

3.2 开头固定结构

推荐固定为下面顺序：

  1. frontmatter
  2. 一级标题
  3. 文档定位 blockquote
  4. 0. 项目说明入口
  5. 0.1 对外简介
  6. 0.2 快速开始
  7. 0.3 仓库信息卡
  8. 0.4 仓库卫生与运行入口
  9. 0.5 Truth Layer
  10. 0.6 Constraint Layer
  11. 0.7 Strategy Layer
  12. 目录
  13. 深层设计、结构、验收、路线图、附录

也就是说，最重要的运行真相必须顶在最前面，不能埋在文档中后段。

3.3 顶部 blockquote 的写法

README 标题下面先给三句定性信息：

  • 版本定位：这个文件在项目里是什么
  • 文档策略：先写什么，后写什么
  • 冲突处理：和派生文档冲突时谁为准

这三句的作用是先定义文档治理规则，再开始正文。

3.4 0. 项目说明入口 的写法

这个区块是整个 README 的压缩控制面板，必须用一个短 yaml 代码块承载最关键事实，常见字段包括：

  • projectName
  • canonicalDoc
  • machineReadableEntry
  • localSourceRoot
  • serverRuntimeRoot
  • publicBaseUrl
  • publicHealthContractPath
  • public...DebugContractPath
  • consoleDomain
  • consoleUrl
  • githubRepo
  • defaultBranch
  • serverHost
  • runtimeHealthUrl
  • runtimeApiBaseUrl
  • managementUrl
  • runtimeServiceName
  • deploymentMode
  • deploymentRunner

写法要求：

  • 只放当前有效事实
  • 名称稳定，值精确
  • 不混入建议语气
  • 不塞历史解释

3.5 信息层次写法

Token Pool 的 README 好用，不是因为长，而是因为层次很清楚。以后继续复用这套分层：

  • Truth Layer：只写当前真实运行状态
  • Constraint Layer：只写禁止行为和系统不变量
  • Strategy Layer：只写验证顺序、执行协议、未来路线和实施策略

硬规则：

  • 真相不能和策略混写
  • 历史兼容信息要显式标成 legacy
  • 目标态、路线图、未落地能力不能伪装成当前现实

3.6 区块的最佳表达形式

以后按下面规则挑表达形式：

  • 稳定键值集合：用 yaml 或表格
  • 请求链路、拓扑、层级映射：用 text 代码块箭头图
  • 明确事实和限制：用短 bullet
  • 同类静态字段对照：用表格
  • 结构目录、路由归属、职责映射：用分节标题 + 表格

不要把所有东西都堆成大段 prose。

3.7 语气与句式

以后默认沿用这套语气：

  • 中文为主
  • 当前真相用完成态、事实态
  • 禁止事项用硬限制语气
  • 路线图和目标态单独分区
  • 对架构、入口、端点、服务名的描述必须绝对具体

推荐句式：

  • “X 是唯一对外 canonical API 入口”
  • “Y 当前仅保留为 legacy alias，不再是 canonical 命名”
  • “本层只写当前真实运行状态；不写理想态，不写客户端本地配置”

避免句式：

  • “建议将来可以考虑”
  • “可能是”
  • “大概在”
  • “通常应该”

除非本节本来就是 roadmap 或 open questions。

3.8 内容排序原则

以后 README 内容排序遵守这个优先级：

  1. 当前入口与真相
  2. 当前边界与禁令
  3. 当前验证与排障顺序
  4. 当前结构与职责映射
  5. 目标态与路线图
  6. 附录与参考

也就是先让陌生人搞清楚“系统现在是什么”，再讲“将来要变成什么”。

3.9 README 必备章节模板

以后可直接套下面骨架：

---
title: <Project Name>
status: canonical
---
 
# <Project Name>
## 总体设计与实施手册
 
> 版本定位：本文件是...
> 文档策略：正文先给出...
> 冲突处理：若本文件与任何派生文档冲突...
 
## 0. 项目说明入口
 
```yaml
projectName: <Project Name>
canonicalDoc: README.md
machineReadableEntry: project.json
...

0.1 对外简介

0.2 快速开始

0.3 仓库信息卡

0.4 仓库卫生与运行入口

0.5 Truth Layer

0.6 Constraint Layer

0.7 Strategy Layer

目录

1. 摘要

2. 关键词

3. 阅读指南

...


## 4. project.json 写法规范

### 4.1 角色定位

以后我把 `project.json` 当成“项目机器合同”，不是随手堆字段的配置垃圾桶。

它要解决的是：

- 自动化工具第一跳该读什么
- 仓库的 canonical 文档和机器入口是谁
- 源码根、运行根、服务名、域名、脚本、工作流分别是什么
- 哪些是兼容入口，哪些是正式入口

### 4.2 字段分组顺序

推荐按这个顺序组织字段，和 `Token Pool` 保持同型：

1. schema 与身份
2. 仓库与源码真相
3. 公开入口与控制台入口
4. 本地/服务器运行路径
5. 安装与包管理策略
6. 配置入口
7. 部署脚本
8. 验证脚本
9. 部署工作流
10. runner 信息
11. legacy 路径
12. secrets / artifacts
13. compatibility 入口
14. 其他稳定标签

### 4.3 project.json 常用字段模板

```json
{
  "$schema": "./templates/project-contract/project.schema.json",
  "projectName": "<Project Name>",
  "canonicalDoc": "README.md",
  "machineReadableEntry": "project.json",
  "githubRepo": "<repo-url>",
  "defaultBranch": "main",
  "localSourceRoot": "<local-root>",
  "serverRuntimeRoot": "<runtime-root>",
  "serverHost": "<host-or-ip>",
  "runtimeServiceName": "<service-name>",
  "deploymentMode": "<deploy-mode>",
  "publicBaseUrl": "<public-api-base>",
  "publicConsoleUrl": "<public-console-url>",
  "healthUrl": "<internal-health-url>",
  "managementUrl": "<internal-management-url>",
  "installEntry": {
    "windows": "install-and-run.ps1",
    "batch": "install-and-run.bat",
    "unix": "install-and-run.sh"
  },
  "deploymentScripts": {},
  "verificationScripts": {},
  "deploymentWorkflows": {},
  "compatibilityEntrypoints": {},
  "status": "active"
}

4.4 project.json 写法规则

  • 键名稳定、语义清楚、尽量显式
  • URL、路径、服务名、脚本名必须写完整
  • 同一概念不要起两个近义字段
  • 正式入口和兼容入口分开写
  • 部署脚本、验证脚本、workflow、secrets、artifacts 要分组
  • 不把解释性长 prose 塞进字段值

也就是说：

  • README.md 负责解释“为什么”
  • project.json 负责告诉工具“在哪里”

4.5 project.json 不该怎么写

以后避免这些坏味道：

  • 把临时值、调试值、实验值直接混进正式字段
  • 把历史路径继续写成当前默认路径
  • 用模糊字段名，比如 path1、serverPath、misc
  • 既没有 canonicalDoc 也没有 machineReadableEntry
  • 没把 verificationScripts 和 deploymentScripts 分开

5. README 与 project.json 的映射规则

以后两者要满足下面映射：

  • README 0. 项目说明入口 <- 对应 project.json 的核心身份字段
  • README Truth Layer <- 对应 project.json 的 URL / 路径 / service / host 字段
  • README 仓库卫生与运行入口 <- 对应 installEntry、deploymentScripts、verificationScripts
  • README 兼容入口与历史边界 <- 对应 compatibilityEntrypoints、deploymentLegacyPaths

判断是否写对，可以问四个问题：

  1. 机器能不能只靠 project.json 找到主入口、脚本和运行根？
  2. 人能不能只靠 README 快速理解当前真相和禁止事项？
  3. README 顶部事实和 project.json 是否逐项一致？
  4. legacy 是否被明确隔离，而不是伪装成当前真相？

6. 我以后复用时的默认落地规则

以后只要用户要我给一个项目写“详细、有条理、可当真源”的文档，默认采用：

  • 一个 canonical README.md
  • 一个机器合同 project.json
  • README 顶部固定有“项目说明入口 + Truth / Constraint / Strategy”
  • project.json 固定有“身份 / 路径 / 入口 / 脚本 / workflow / compatibility”
  • 先写当前真相，再写目标态
  • 先把人和机器入口固定，再扩写后续章节

7. 快速检查清单

以后写完后，用这份清单自查：

  • README 开头是否先给出项目说明入口，而不是先讲背景故事
  • README 是否把真相、约束、策略分层
  • 是否明确唯一 public API 入口、唯一 console 入口、唯一 runtime root
  • 是否显式写出 legacy / compatibility，而不是混在现状里
  • project.json 是否能单独被工具读取并找到脚本、路径、工作流
  • README 和 project.json 是否对齐而非互相打架
  • 文档是否主要使用事实态，而不是建议态
  • 表格、yaml、拓扑图是否用在最合适的位置

8. 最终记忆锚点

以后跨项目写这类文档时，优先复用下面这句话：

README 写成人类控制平面手册，project.json 写成机器可读合同；
README 顶部先固化项目说明入口，再分 Truth / Constraint / Strategy；
project.json 只保留稳定入口、路径、脚本、工作流、兼容项；
两者镜像对齐，但绝不把历史、计划、临时值伪装成当前真相。