Elijah N. Dean 发布 TOKENME.txt 规范，分离代码库声明状态与 AGENTS.md

作者：Elijah N. Dean，BSME 组织：Dean Innovative Design LLC 日期：2026年11月 版本：1.1（公开规范） 许可：Creative Commons Attribution 4.0 International (CC-BY 4.0) / MIT Specification 规范仓库：https://github.com/endean-eng/tokenme 网页镜像：https://deaninnovativedesign.com

随着软件工程从单轮聊天补全转向自主的多智能体流水线，仓库上下文管理已成为主要的故障瓶颈。现有约定分别针对人类上手（README.md）、外部网页爬虫索引（llms.txt）以及命令式执行规则（AGENTS.md）。然而，对于活跃代码库的被动声明式状态——其架构不变量、数据模式边界以及实时函数/符号目录——尚不存在厂商中立的约定。

当工程团队将动态代码库映射强行塞入 AGENTS.md 或 README.md 时，系统提示会遭受严重的 token 膨胀、解析器截断错误以及指令遵循能力下降。本文介绍 TOKENME.txt，一种有界的原始文本仓库约定，专为多智能体交接、冷启动维护和跨团队 LLM 可移植性中的高密度机器摄入而设计。

在多智能体开发工作流中（例如一个 Orchestrator 将任务路由给专门的 Architect、Builder 和只读 QC Auditor 模式），每次模式切换都需要让接收模型扎根于仓库的物理现实。

目前，团队试图通过两种有缺陷的方法来解决这一扎根问题：

150 行命令式上限：针对 AGENTS.md 的行业 linting 标准明确将行为指令文件限制在 60 到 150 行。当命令式行为规则（智能体必须如何行动）被稀释在数千行声明式代码库状态（仓库中存在什么）之中时，注意力机制会退化，智能体开始违反核心构建和安全约束。

为消除语义冲突，仓库文档必须根据目标消费者和语言模式沿三个正交轴进行划分：

4.1 为何选择原始 .txt 而非 Markdown（.md）

虽然 Markdown 是人类可读文档的默认标准，但它在自动化智能体流水线中引入了三种不同的故障模式：

在四阶段智能体流水线中（例如 Plan -> Implement -> Audit -> Archive），项目概览文档在每个功能周期中至少被摄入 $N \ge 4$ 次。

具有 $H$ 次交接的任务流水线中的累计 token 开销 $C_{\text{total}}$ 定义为：

$$C_{\text{total}} = \sum_{i=1}^{H} \left( T_{\text{system}, i} + T_{\text{TOKENME}} + T_{\text{ephemeral}, i} \right)$$

由于 $T_{\text{TOKENME}}$ 在每次交接 $H$ 中都会相乘，项目概览中每 1,000 个 token 的叙述性冗余内容，在每个已完成任务中就会转化为 4,000 到 8,000 个浪费的 token。TOKENME.txt 强制执行严格的键值密度，使 $T_{\text{TOKENME}}$ 保持最小，同时最大化结构召回。

静态架构文档一旦落后于工作树两个提交，就会变成负担。为防止智能体重新发明现有工具，TOKENME.txt 将人工策展的架构不变量与在构建或提交周期中自动重新生成的符号和函数目录配对：

冷启动与跨技术栈连续性：由于 TOKENME.txt 是纯文本，并且与源代码一起存放在 Git 工作树中，它充当永久的机构记忆。如果一个仓库六个月无人触碰，或被移交给使用完全不同 LLM 技术栈的外部承包商，新智能体摄入 TOKENME.txt 后即可在单轮中实现完整的架构定位。

5.1 为何需要分片

单体 /TOKENME.txt 文件对于中小型仓库效果良好。然而，当代码库从 15 个文件的微服务扩展到 500 个文件的企业级 monorepo 时，在单个根文件中索引每个导出的函数签名会违反有界上下文法则。

让不断扩展的 TOKENME.txt 保持不分片会引入三种系统性退化：

不应在小型仓库上过早进行分片，因为单个文件可以轻松放入内存，而不必要的文件跳转会增加的 tool-call 延迟。反之，等到智能体开始幻觉出重复函数时才分片，意味着分片已经太晚。

当以下四个确定性阈值中的任何一个被跨越时，仓库必须从单体根过渡到分片层级：

当仓库跨越分片触发条件时，单体 /TOKENME.txt 会通过三步协议重构为两层（或 $N$ 层）树：

分片路由下每次交接的数学 token 节省量 $\Delta C$ 为：

$$\Delta C = T_{\text{monolith}} - \left( T_{\text{root}} + \sum_{k \in \text{Active}} T_{\text{shard}, k} \right)$$

对于一个拥有 6 个子系统、每个平均 1,500 个 token 的仓库（$T_{\text{monolith}} = 9,000$ 个 token），在单个子系统内工作的智能体只需加载 $T_{\text{root}}$（800 个 token）+ $T_{\text{shard}, 1}$（1,500 个 token）= 2,300 个 token，实现 74.4% 的上下文开销减少，同时提高符号召回准确率。

%%{init: {'theme': 'base', 'flowchart': {'wrappingWidth': 360, 'nodeSpacing': 35, 'rankSpacing': 45, 'curve': 'basis'}, 'themeVariables': { 'primaryColor': '#1e293b', 'primaryTextColor': '#f8fafc', 'primaryBorderColor': '#64748b', 'lineColor': '#94a3b8', 'edgeLabelBackground': '#0f172a', 'fontFamily': 'Consolas, monospace', 'fontSize': '16px'}}}%% flowchart TB Start(["Agent Handoff Initiated (Turn 1)"]) Root["<b>Hop 1: Ingest Root /TOKENME.txt</b><br/>Global Invariants + Subsystem Shard Map<br/>(<= 1,000 Tokens)"] Gate{"Evaluate Active Task Scope<br/>Which Subsystem Is Targeted?"} subgraph Shards["Hop 2: Selective Subsystem Shard Ingestion (<= 2,000 Tokens Each)"] direction LR

（原文较长，此处译出前 6000 字，完整内容请点「打开原文」。）