当一个起草模型写下没有库存可以证明的承诺时，操作文档就失败了。公共签名可以支持参数表和过程框架，但是它们不能证明安装路径、支持窗口或示例输出。这个工作流程建立了一个机器可读的清单，让一个模型起草未标记的骨架，并要求一个人签署环境声明。该方法是过程控制，而不是结果自述文件是否正确的证明。
从聊天重新生成入门页面的库的失败模式是一致的。一个模型流利地重述函数名，然后发明一个pip extra，一个Python floor，或者一个没人执行的样本脚本。读者将这些句子视为合同。评论家错过了它们，因为周围的散文看起来局部连贯。修复不是一个更好的提示。修复是一个lane文件，它禁止模型填充库存不支持的索赔类别。
清单可以证明什么
快速遍历公共函数可以证明名称、参数列表、默认值、注释和文档字符串的存在。它还可以证明哪些符号是在中导出的__all__当名单存在时。它不能证明默认值在生产中是安全的，类型提示与运行时匹配，或者docstring仍然为真。这些缺口定义了人类的道路。将每一个未经证实的条款视为未签名，直到有人将它写在库存哈希旁边。
下表是合同。草稿文本只能占据左栏。任何暗示工作机器、支持的版本或合法阅读的东西都属于右边，即使模型可以流畅地表达它。
索赔类别 模型可以绘制 人类必须拥有
操作指南的章节大纲 是，从库存标题 不，除非大纲增加了产品承诺
参数表 是，从签名复制 暗示安全或单位的默认值
过程框架 是的，用TODO(human)步伐 在阅读器上必须成功的任何步骤
符号之间的交叉链接 是的，如果两个符号都是公共的 跨版本的兼容性声明
安装和附加功能 不 确切的命令、额外服务和口译员楼层
标准输出/截图示例 否，除非标记为未执行 观察到的任何副本
支持、许可、安全性 不 许可证含义、联系方式、威胁声明
1冻结公共符号库存
第一个工件是一个JSON清单，以限定名为关键字。www.iissbbs.com在git中对该文件进行哈希处理，以便以后的README diffs可以指向特定的符号集。下面的脚本是一个带有标签的小型图书馆布局示例。它不是一个生产索引器，它忽略了重新导出、C扩展和运行时生成的API。
# labeled example: inventory_extractpy
from __future__ import annotations
import ast
import hashlib
import json
from pathlib import Path
from typing import Any
ROOT = Path("src")
OUT = Path("doc_inventoryjson")
def public_functions(path: Path module: str) -> list[dict[str Any]]:
tree = astparse(pathread_text(encoding="utf-8") filename=str(path))
rows: list[dict[str Any]] = []
for node in treebody:
if not isinstance(node (astFunctionDef astAsyncFunctionDef)):
continue
if nodenamestartswith("_"):
continue
args = []
for arg in nodeargsargs:
anno = astunparse(argannotation) if argannotation else None
argsappend({"name": argarg "annotation": anno})
rowsappend(
{
"qualname": f"{module}{nodename}"
"args": args
"returns": astunparse(nodereturns) if nodereturns else None
"has_docstring": astget_docstring(node) is not None
"lineno": nodelineno
}
)
return rows
def main() -> None:
items: list[dict[str Any]] = []
for path in sorted(ROOTrglob("*py")):
rel = pathwith_suffix("")relative_to(ROOT)
module = ""join(relparts)
itemsextend(public_functions(path module))
payload = {"items": items}
text = jsondumps(payload indent=2 sort_keys=True) + "\n"
digest = hashlibsha256(textencode("utf-8"))hexdigest()[:12]
payload["inventory_sha256_12"] = digest
OUTwrite_text(jsondumps(payload indent=2 sort_keys=True) + "\n" encoding="utf-8")
print(f"wrote {OUT} items={len(items)} sha={digest}")
if __name__ == "__main__":
main()
指向之后，从存储库根目录运行它ROOT你实际运送的包裹。
python inventory_extractpy
python -c "import json; print(jsonload(open('doc_inventoryjson'))['inventory_sha256_12'])"
将十二个字符的摘要存储在lane文件中。www.ycsjb.com如果摘要移动了，每一个先前签名的install语句都是陈旧的，直到有人重新阅读它。那个规则是机械的。它不需要在盘点阶段判断散文的质量。
2在任何草稿存在之前写入通道文件
创造doc_lanesyaml用手。不要要求模型对声明所有权进行分类，因为分类是控制平面。保持人类拥有的密钥为空或充满UNSIGNED。草稿拥有的关键字可能包含仍使用占位符的框架降价。
# labeled example: doc_lanesyaml
inventory_sha256_12: "replace-after-extract"
draft_allowed:
outline: |
## Install
TODO(human): interpreter extras lockfile
## Call the public entrypoints
TODO(model): parameter tables from inventory only
## Next steps
TODO(human): support path
human_owned:
python_requires: UNSIGNED
install_command: UNSIGNED
extras: UNSIGNED
observed_example_exit_code: UNSIGNED
license_summary: UNSIGNED
support_contact: UNSIGNED
forbidden_in_draft:
- "pip install"
- "conda install"
- "tested on"
- "production ready"
- "we support"
- "output:"
- "SLA"
禁止列表是一个绊网，而不是语义解析器。它抓住了通常的自述承诺，库存不能证明。当你的语料库使用其他合同动词时，扩展它。不要把一个干净的扫描当作该如何做是正确的证据。
3仅在允许的骨架内拔模
给模型输入清单JSON、大纲和它可能重写的指令TODO(model)街区。它必须离开TODO(human)街区未动。它不能添加安装命令、版本下限或示例程序输出。如果您需要一个远程绘图环境，MonkeyCode的免费模型访问和免费服务器选项可以托管这一狭窄通道。披露:本文是MonkeyCode产品推广的一部分。无论如何，都要在git中保存lane文件和库存；不要在聊天记录中留下所有权状态。
合同中的提示如下所示。这是一个模板，而不是一个测量的质量声明，它没有命名模型。
You receive doc_inventoryjson and the draft_allowedoutline field
Rewrite only sections marked TODO(model)
Use parameter names and annotations exactly as given
Do not invent extras Python versions install commands or program output
Leave every TODO(human) line unchanged
Return markdown for the outline only
如果草稿插入了清单中从未包含的命令，则丢弃草稿。重新生成比签署一个错误的安装路径更便宜。人类通道是为知识库没有编码的知识准备的，不是用来清理模型残羹剩饭的。
4在自述文件合并之前验证通道
下面的检查器是一个带标签的例子。它实施了三个关口:库存摘要匹配、草稿文件中没有禁用短语、没有剩余UNSIGNED按键时间--require-signed已设置。它不评分可读性，也不执行例子。
# labeled example: verify_doc_lanespy
from __future__ import annotations
import argparse
import json
import re
import sys
from pathlib import Path
try:
import yaml
except ImportError:
sysstderrwrite("install pyyaml before running this checker\n")
raise
def main() -> int:
parser = argparseArgumentParser()
parseradd_argument("--inventory" default="doc_inventoryjson")
parseradd_argument("--lanes" default="doc_lanesyaml")
parseradd_argument("--draft" default="howtodraftmd")
parseradd_argument("--require-signed" action="store_true")
args = parserparse_args()
inventory = jsonloads(Path(argsinventory)read_text(encoding="utf-8"))
lanes = yamlsafe_load(Path(argslanes)read_text(encoding="utf-8"))
draft = Path(argsdraft)read_text(encoding="utf-8")
errors: list[str] = []
expected = inventoryget("inventory_sha256_12")
if lanesget("inventory_sha256_12") != expected:
errorsappend("lane digest does not match inventory")
lowered = draftlower()
for needle in lanesget("forbidden_in_draft" []):
if needlelower() in lowered:
errorsappend(f"forbidden phrase in draft: {needle!r}")
if research(r"TODO\(model\)" draft):
errorsappend("unresolved TODO(model) remains in draft")
if argsrequire_signed:
for key value in (lanesget("human_owned") or {})items():
if value == "UNSIGNED" or not str(value)strip():
errorsappend(f"unsigned human key: {key}")
if errors:
sysstderrwrite("\n"join(errors) + "\n")
return 1
print("lane check passed")
return 0
if __name__ == "__main__":
raise SystemExit(main())
在没有签名密钥要求的情况下，将廉价网关连接到CI。奔跑--require-signed仅在发布分支上，在一个人替换了每个UNSIGNED用一句他们愿意辩护的话来值。这种分割保持了拉取请求的畅通，同时仍然阻止了标记的操作方法发送空的承诺。
pip install pyyaml
python verify_doc_lanespy
python verify_doc_lanespy --require-signed # release branch only
5用证据，而不是语气，在人的车道上签名
当你替换UNSIGNED，附上另一个工程师可以重放的指针。口译员发言应引用requires-python包装元数据，而不是一个记住的走廊号码。安装命令应该在pyprojecttoml。一份样本记录应该引用一个记录的会议或保持标记为未执行。支持文本应引用实际问题跟踪者或邮件别名。这些指针没有一个是装饰性的。它们是下一个评审者在不信任文章的情况下检查声明的方式。
如果打包元数据和操作方法不一致，那么操作方法就是错误的。不要通过要求模型协调语气来“解决”冲突。如果移动了公共符号，请更改人线或更改包元数据，然后重新散列库存。不能命名其证据的文档仍然是草稿，不管它读起来有多完整。
限制
包装纸的库存不完整，__getattr__导出和编译模块。禁用短语扫描遗漏了诸如“把这个放进一个venv”之类的仍然暗示正在安装的解释。树中的文档字符串可以是假的，提取器仍然会报告has_docstring: true。自由绘图环境仍然能够流畅地处理从未运行过的程序文本。车道档案记录所有权；它不在干净的机器上执行操作方法。
此工作流还会增加合并摩擦。发布一页纸内部会议要点的团队会花更多时间在YAML会议上，而不是在会议上。当读者将命令复制到产品shells中时，这个成本是可以接受的。当文档是没有外部合同的便笺时，它就被浪费了。
谁不应该使用这个
如果您正在编写已经要求在质量系统下执行方案和签署方案的监管认证包，请跳过lane文件。如果公共符号每天都在变动，并且没有摘要可以在审查周期中保持最新，则跳过它。如果文档的唯一读者是作者，请跳过它，因为控制平面的存在是为了约束其他人会信任的声明。在这些情况下，没有模型传递的手写段落是较小的真实工件。
对于已经保留打包元数据和小型公共表面的库，这种分割足以阻止常见的README故障。将骨骼放在通风道中。将安装路径、支持、许可含义和观察到的输出保留在人的通道中。仅当摘要匹配且未签名的密钥消失时才进行合并。如果您在自由模型访问中起草这些框架，那么在与清单相同的提交中导出lane文件，这样review就保留在git中，而不是聊天历史中。
