在模型起草前冻结读者契约教程页

生成的教程页面只有在人类在起草开始前锁定受众、前置条件和成功检查时，才能保持可信。模型可以围绕这些由他人拥有的事实撰写连接性文字，但不应自行编造事实。本文定义了一种所有权划分、一个契约文件以及一个拒绝包含契约中未列出的假设的草稿的检查器。该检查器是一个可复现的示例提案，而非具有声称通过率的生产系统。

为何读者状态会在语法错误之前导致失败

教程失败往往始于一个无声的假设，而非措辞生硬或缺少逗号。草稿可能列出操作系统、语言版本、时间预算或成功字符串，但这些细节无人核实。这些细节看似有益，因为它们让页面看起来完整，但实际上它们会改变新手将要尝试的内容。Diátaxis 将教程视为必须保持可靠的学习路径，因此前提条件应由能够验证它们的所有者负责。

希望获取源框架的作者可以在编辑契约前阅读 Diátaxis 教程部分（https://diataxis.fr/tutorials/）。近期关于生成式软件的公开讨论指出了同一空白，但未规定文档控制措施。人们可以快速生成页面，但该页面仍可能省略使说明成立的那些枯燥约束。

此工作流不对模型进行评分，也不声称来自任何调查的量化文档错误率。它仅将已拥有的读者事实与可起草的解释分开，以便审查时间集中在可能误导新手的事实上。该方法故意范围狭窄，并将命令清单和升级页面留给其现有所有者。

决定模型可以起草什么

表格是该工作流的控制界面，后续所有步骤都假定这些权限保持不变。人类编辑契约文件，而模型可以引用契约行，并起草标记为叙述性的部分。模型不得添加前置条件、持续时间、版本、支持平台或成功字符串。

命令、升级联系人和产品限制不在此页面范围内，因为它们需要单独的拥有工件。如果句子陈述了 PagerDuty 目标、新的 shell 命令或数值限制，则草稿因需人工审查而关闭。审查者应拒绝混合页面，而不是指望在草稿落地后通过后续的叙述性编辑来理清所有权。

步骤 1：从你已信任的文件中提取读者事实

从审查者可以打开的文件开始，例如语言版本固定值、CI 镜像名称和安装说明。仅复制你可以指出的事实，并在契约中记录每个事实的来源路径。不要询问模型去虚构合理的读者、平台或结果，而是将未知字段留空。空字段是人类所有者的审查任务，而非起草模型的生成机会。

将上述 YAML 视为待定的工件，在任何人依赖它之前，请修改所有路径以匹配你的仓库。切勿将密钥、客户名称或内部主机名粘贴到合同中，即使草稿似乎需要它们也是如此。合同应描述读者状态和审查来源，而不是授予对机器、账户或私有数据的访问权限。

步骤 2：在调用模型之前标记章节

使用与合同中可起草列表和仅引用列表相匹配的标题创建教程骨架。将合同的精确行放在“仅引用”标题下，并将“可起草”标题留空或填充占位符。模型接收合同、骨架以及针对新平台、版本、持续时间、命令或成功文本的书面限制。如果模型返回新的标题或新的先决条件，请丢弃该输出并针对相同的冻结骨架重新运行。

## audience
> owned: A developer who can run git and a shell, and who has not deployed this repo before

## prerequisites
> owned: git
> owned: a Python install matching .python-version

## success
> owned: demo ready

## why-this-order
DRAFT

## orientation
DRAFT

这种顺序比你随骨架发送的提示词的确切措辞更重要。看到空白页面的模型通常会将其补全，而冻结的合同留下的填空空间更少。你仍然需要检查结果，因为提示词本身只是一种请求，而非执行机制。当检查器读取两个文件并在发现任何 smuggled reader fact（走私的读者事实）时退出非零状态时，执行才真正开始。

步骤 3：拒绝走私新读者状态的草稿

下面的 Python 代码是一个小型未执行的示例，你可以在将模式适配到你的仓库后运行它。它会标记合同中不允许的平台名称、持续时间短语、类似版本的令牌以及成功行。它会遗漏巧妙的改写，因此绿色运行（即无错误通过）是必要的，但对于发布来说仍不充分。

将脚本与契约文件存放在同一目录下，这样审查命令就不依赖于私有笔记本或聊天转录内容。使用普通的审查命令运行检查器，并在同一次更改中将契约文件保留在草稿旁边。只有当命令退出码为零且人工阅读过两者的差异后，才发布这一对文件。

python3 -m pip install pyyaml
python3 check_reader_contract.py

失败的运行结果应指出被 smuggled（隐藏/夹带）的事实，并且不应尝试重写教程页面。如果该事实真实且有来源，请更新契约；如果是模型捏造的，则删除该句子。不要通过扩大白名单使其仅匹配生成的草稿来消除红色检查标记。

步骤 4：单独审查契约哈希值

在拉取请求中记录契约哈希值，以便审查者能够查看读者事实是否确实发生了变动。仅涉及正文的编辑应保持该哈希值不变，而涉及事实的编辑则应更改哈希值并引用来源路径。请一位审查者批准契约的差异部分，并请另一位审查者阅读可发布的章节以查找残留声明。对于小型页面，单一审查者可以兼任这两个角色，但两个差异部分应在视觉上保持分离。

sha256sum reader_contract.yml | tee contract.sha256
git diff -- reader_contract.yml docs/tutorial.md

将哈希值用作审查的路由信号，而不是作为发布经理或律师的签名。匹配的哈希值仅表示契约字节未发生变化，它并不能说明正文是否忠实于原意。如果哈希值发生了变化，但描述称该编辑仅为措辞调整，请暂停并将更改再次拆分。

步骤 5：使自由草稿通道比契约更窄

披露：本文是 MonkeyCode 产品推广工作的一部分。MonkeyCode 的免费模型访问权限可以撰写标记为可撰写的部分，而免费服务器选项可以为这项狭窄的工作运行检查器。这两个可用性声明是该工作流程使用的唯二产品事实，它们是为本草稿提供的。本文未提及任何模型、配额、机器大小、保留期或基准测试结果。

在依赖免费通道之前，请先阅读当前的产品条款，因为本页面不跟踪实时可用性。你在本地计算机上编辑合同，然后将骨架和合同发送给免费模型以仅生成正文。你在免费服务器上运行检查器，或者如果更简单则在本地运行，并将绿色对勾视为仅表示审查许可。绿色对勾并非发布许可，因为改写后的发明仍可能通过词法扫描。

python3 check_reader_contract.py && python3 -m http.server 8080 --directory docs

如果免费通道不可用，相同的文件仍可在安装了 PyYAML 的任何 Python 3 环境中运行。上述预览命令仅假设一个已安装 Python 3 的 shell，且不设置任何特定于产品的标志。当审查结束时停止预览，不要将开放的端口视为文档合同的一部分。如果服务器策略禁止该预览，请依赖检查器的退出代码和正常的差异比较。

将产品语言排除在合同文件之外，因为即使你更改撰写工具，合同也应保持有用。审查者应能够在不知道哪个编辑器生成了可撰写部分的情况下运行检查器。所有权划分而非供应商名称才是值得复制到其他文档仓库的部分。

在信任绿色对勾之前，先阅读构造的失败示例

以下失败文本是构造的说明，而非针对托管模型的实时运行输出。它展示了检查器应在审查者花费时间调整语气之前捕获的句子类型。请将构造的示例保留在测试文件或审查笔记中，不要将其作为实时教程提交。

On macOS, wait 5 minutes, then you should see server started.

该行添加了平台、持续时间和成功字符串，而这些项均不存在于示例合同中。正确的修复方法是删除或基于来源的合同编辑，而不是提示模型盲目重试。修复后，重新运行检查器并确认仅在人类添加了来源事实时合同哈希才发生变化。

当仓库变更时更新合同

当 CI 镜像或语言锁定版本发生变化时，在与基础设施变更相同的拉取请求中更新合同来源。引用昨天锁定版本的教程可能会通过粗心的阅读检查，但明天在干净机器上仍会失败。如果你希望缺失的来源文件也能导致审查失败，请在词法检查器旁边添加路径存在性检查。保持第二个检查为机械式操作，不要让模型在撰写导向性正文时重写合同。

missing = [
    item['path']
    for item in contract['sources']
    if not Path(item['path']).exists()
]
if missing:
    raise SystemExit('missing source paths: ' + ', '.join(missing))

与检查器并列的限制说明

此检查器是词法性质的，因此句子可能在未匹配模式的情况下引入云账户或虚假结果。当你发现重复遗漏时，请扩展模式，并将这些模式与合同一起保存在版本控制中。合同本身可能是错误的，特别是在 CI 变更后若无人更新列出的来源路径。一篇从未被执行过的绿色教程仍然是未经测试的教程，无论其正文看起来多么整洁。

当有人手动编辑 YAML 并忘记引用路径时，引用的行可能会偏离源文件。请勿将此设计视为合规保证、安全边界或干净机器运行的替代品。该设计仅阻止一类虚构的读取器状态，而其他文档风险仍需各自的责任人负责。

谁不应使用此方法

如果团队中没有人能够针对存储库和 CI 配置验证先决条件，请跳过此工作流程。对于会产生支持职责、法律条款或计费声明的页面，也请跳过此方法，因为这些句子需要不同的责任人。纯参考页面几乎每一行都是提取出的签名，更适合采用提取检查而非读取器契约。希望模型发现受众的团队不应采用其第一条规则禁止这种发现的方案。

将这份契约置于下一个教程拉取请求中，然后观察审阅者是否将时间花在阅读事实而非句子润色上。仅在审阅者在审阅下一个教程拉取请求时实际打开该文件的情况下才保留它。如果审阅者停止打开它，请删除该契约，因为一个无人阅读的关卡只是仓库中的另一个文件。