8.0
热点
AI SCORE
编程提效2026-10-11 03:23
给 AI 产品文档加一道事实校验关
dev.to · AI#AI 文档#事实校验#自动化检查
Editor brief · 编辑速览
文章要求产品可用性描述依据人工维护的事实来源，防止模型擅自补出额度、时长、地区或硬件规格。通过文件结构和 Python 检查示例，将无来源的承诺拦截在文档发布前。
由模型起草的产品页面，只有在每一句涉及可用性的表述都复制自人工负责维护的 pin（事实锁定文件）时，才能发布。只要草稿擅自添加配额、时长、区域或硬件规格，一个真实存在的选项就会变成一条虚假的支持信息。下面的工作流将可以交给模型起草的操作流程与必须由人工负责的可用性事实分开，并在违反这条边界时让文档检查失败。读者可以使用下文给出的文件布局和 Python 示例复现这项检查。
常规文档审查能发现一条有问题的命令，却仍可能漏掉一条语气笃定、但从未由任何运营负责人提供来源的额外信息。页面可以准确地说，存在免费模型访问选项，也存在免费服务器选项，同时并不知道任何具体的额度。当生成器把这种信息缺失当成需要填补的空白时，就可能输出 token 数量、保留期限、实例类型或模型标识符。这些补充不是文风问题，因为后来的读者可能把其中每一项都当成实际运营承诺。
每周的新闻标题无法弥补这个缺口，即使团队希望页面显得紧跟最新动态。社区信息流中出现的标题，只是一个不可信的话题信号，并不是访问限制或服务器条款的一手来源。因此，本教程忽略没有来源的新闻说法，只使用为起草步骤提供的两个可用性选项。如果供应商文档中出现了更新的限制，必须先由人工将它加入 pin，模型才能复述。
模型可以起草步骤顺序、衔接文字和注意事项，前提是这些句子都不宣称任何产品限制。人工必须负责 pin、来源说明、审查日期，以及每一句提及访问或计算资源可用性的表述。模型不得添加 pin 的键、改写允许使用的短语，也不得从相邻句子中推断出限制。正是这种分工，让生成的文字不会触碰维护者尚未明确认可的事实。
这张表就是审查约定。如果草稿添加了一列估算限制，就已经越过了边界。只有检查器通过后，才能讨论操作流程的质量；责任归属问题尚未解决时，不能先讨论文案。措辞谨慎的形容词，并不能把一条没有来源的限制变成审查者可以信任、有人负责的声明。有人负责，意味着这条声明存在于 pin 中，而不是草稿中的句子听起来有多可信。
将 pin 存放在固定的责任归属路径下，并将缺少审查日期视为文档构建失败。每条声明都包含一个标识符、一种类型、一条陈述、一个来源标签，以及草稿可以原样复述的确切短语。示例中的两条声明，是运营负责人提供的可用性选项，既不是经过测量的配额，也不是永久有效的承诺。如果一条陈述无法提供来源，就不能进入 pin，草稿也不得提及。
{
"schema_version": 1,
"owner": "docs-platform",
"reviewed_on": "2026-10-10",
"claims": [
{
"id": "AVAIL-001",
"kind": "access_option",
"statement": "A free model access option is available for the drafting step.",
"source": "operator-supplied",
"allowed_phrases": ["free model access"]
},
{
"id": "AVAIL-002",
"kind": "compute_option",
"statement": "A free server option is available for the drafting step.",
"source": "operator-supplied",
"allowed_phrases": ["free server option"]
}
]
}
文件中的日期，是为本次讲解冻结教程内容的日期，并不是对某个未指明产品条款的认证。采用这一 schema 的维护者，需要将两条陈述都替换为运营负责人仍能提供依据的表述。修改陈述却不更新审查日期，应该无法通过审查，即使检查器尚未将这条规则编码进去。只有在陈述含义完全不变的情况下，声明标识符才能保持不变。
维护者只复制为本次发布提供的陈述，并在开启起草会话之前设置审查日期。任何模型调用都不得创建这个文件、追加声明，或补全空白的数字字段。引入 pin 的 commit 不应包含任何生成的页面，这样就能单独看清责任归属的 diff。之后修改陈述，需要人工提交 commit、设置新的审查日期，并附上一条明确指出一手来源的说明。
页面模板应将可用性陈述放在起草区域之外，或者只以允许使用的确切短语复述。模型可以在操作流程区域填写运行检查器、阅读失败输出和发起审查的步骤。它不得编辑 pin、披露段落、责任归属表，也不得编辑任何用于定义失败情况的 fixture。标记让这条边界清晰可见，因此 diff 审查可以拒绝越界的修改。
Draft only inside the PROCEDURE markers.
Do not add numbers, durations, hardware nouns, model names, or availability claims.
Repeat an availability phrase only if it appears in allowed_phrases.
If a fact is missing, write OWNER_MUST_SUPPLY rather than guessing.
这个 prompt 只是一项约束，不能证明某个具体模型一定会遵守。检查器仍然是必需的，因为指令文本无法约束后续修改、从聊天中粘贴的内容，或从其他分支合并的内容。跳过检查器、只相信 prompt 的团队，并没有真正将责任归属与起草工作分开。遵守 prompt 只是让输入环节更方便，而 pin 检查才是真正的发布门槛。
下面的示例是一份方案，本文并未在生产环境的文档目录树中实际执行它。它只使用 Python 标准库，读取 pin，并在移除允许使用的确切短语后扫描 Markdown。剩余的数字、时长词、硬件名词或符合模型标识符模式的内容，都会连同行号一起报告，并返回非零退出状态。扫描前会移除对 pin 中短语的原样复述，因此允许使用的可用性措辞可以出现在页面上，而不会导致检查失败。
#!/usr/bin/env python3
"""Proposal checker: reject availability prose that extends the human pin.
Unexecuted example. Run it locally before adopting it in a docs build.
"""
import json
import re
import sys
from pathlib import Path
DURATION = re.compile(
r"\b(day|days|month|months|year|years|forever|permanent|hourly)\b",
re.IGNORECASE,
)
HARDWARE = re.compile(
r"\b(gpu|cpu|core|cores|region|regions|ram|ssd)\b",
re.IGNORECASE,
)
NUMBER = re.compile(r"\b\d[\d,._]*\b")
MODEL_ID = re.compile(
r"\b(?:gpt|claude|gemini|llama|qwen|deepseek)[\w.-]*\b",
re.IGNORECASE,
)
def load_pin(path: Path) -> tuple[list[str], str]:
data = json.loads(path.read_text(encoding="utf-8"))
reviewed = str(data.get("reviewed_on") or "")
if not reviewed:
raise SystemExit("pin missing reviewed_on")
phrases = []
for claim in data.get("claims", []):
phrases.append(claim.get("statement", ""))
phrases.extend(claim.get("allowed_phrases", []))
return [phrase for phrase in phrases if phrase], reviewed
def scan(markdown: str, phrases: list[str], reviewed: str) -> list[str]:
redacted = markdown.replace(reviewed, " ")
for phrase in phrases:
redacted = redacted.replace(phrase, " ")
errors = []
rules = (
("number", NUMBER),
("duration", DURATION),
("hardware", HARDWARE),
("model_id", MODEL_ID),
)
for index, line in enumerate(redacted.splitlines(), start=1):
for label, pattern in rules:
for match in pattern.finditer(line):
errors.append(
f"{label} not in pin at line {index}: {match.group(0)}"
)
return errors
def main() -> int:
if len(sys.argv) != 3:
raise SystemExit(
"usage: check_availability_pin.py PIN.json PAGE.md"
)
phrases, reviewed = load_pin(Path(sys.argv[1]))
text = Path(sys.argv[2]).read_text(encoding="utf-8")
errors = scan(text, phrases, reviewed)
if errors:
print("\n".join(errors))
return 1
print("availability pin check passed")
return 0
if __name__ == "__main__":
raise SystemExit(main())
用于验证通过情况的 fixture，只在审查者可以批准发布的普通操作流程句子中，复述 pin 中已有的短语。数字 fixture 添加了一个没有来源的整数，时长 fixture 则在没有来源支持的有效期限时，将某个选项称为永久有效。只有这两个反例 fixture 都以状态码 1 退出，才能认为这道发布门槛已经定义完整。这些文件属于有人负责维护的交付物，不是后续草稿可以随意删除的可选示例。
Run the checker against the frozen pin, then read the exit status before editing prose.
The drafting step may use free model access.
The drafting step may use the free server option.
The drafting step includes 123456 units at no cost.
The free server option is permanent.
python3 scripts/check_availability_pin.py \
docs/ownership/availability-pin.json \
docs/fixtures/availability_pass.md
python3 scripts/check_availability_pin.py \
docs/ownership/availability-pin.json \
docs/fixtures/availability_number.md
第一条命令用于验证通过路径，在没有违规内容的 fixture 上，应以状态码 0 退出。第二条命令的 fixture 包含 123456 这样的无来源整数时，应以状态码 1 退出。将选项称为 permanent 的时长 fixture 也必须失败，即使该句没有任何数字。将这些 fixture 与 pin 一起存放，防止后续修改悄悄从测试计划中移除反例。
检查失败的行应作为责任归属缺陷退回给负责人，而不是要求把句子改得更谨慎。将没有来源的整数替换为模糊的数量描述，仍然违反规则，即使第一版检查器只能捕获列出的模式。能长期解决问题的做法，是删除这条内容，或者由人工更新 pin，并附上一手来源。只有待审页面的检查器以状态码 0 退出后，才应开始文案审查。
起草可以使用 MonkeyCode 的免费模型访问选项；如果希望起草过程不在笔记本电脑上运行，也可以使用免费服务器选项。披露：本文是 MonkeyCode 产品推广活动的一部分。这两个选项的作用，仅限于在人工已经冻结 pin 之后，提供生成操作流程文字的场所。它们不能作为配额、模型名称、硬件规格的来源，也不能支持任何关于这两个选项永久有效的声明。
检查器仍然在仓库中运行，因为在托管环境中生成的草稿，不会因此变成有人负责的事实。推广关系不会扩大 pin 的范围，也不意味着页面可以添加额外的能力声明。这里没有列出模型清单、token 额度、服务器规格或保留期限，因为没有任何一项被作为有来源的 pin 条目提供。需要这些细节的团队应该暂停起草，取得一手来源，并先添加一条范围明确的声明，再继续起草。
这道门槛不理解同义表达，因此草稿仍可能通过不常见的措辞夹带没有来源的限制。它也不会验证运营负责人提供的陈述日后是否仍然成立，所以必须由人工更新审查日期。如果版本号、benchmark 表格，以及 core 这样的普通词没有放进单独的 allowlist，它们也会被误判为失败。需要大量数字信息的团队，应该拆分这些页面，而不是不断放宽检查器，直到它接受所有数字。
如果没有明确指定 pin 的负责人，团队就不应该使用这套工作流，因为无人负责的文件只是另一份草稿。对于法律条款、安全公告或定价页面，也不应将它作为唯一控制措施，这些页面的全文必须由法律顾问或财务负责人负责。团队不应拿供应商博客或社区综述作为检查对象，因为这些页面不是可用性信息的来源。一个从不发布产品声明的私人笔记本，也很难从维护这个额外文件中获得多少收益。
发布规则很简单：冻结 pin，只起草操作流程，并将每一个没有来源的数字视为构建失败。复制这份 schema，将示例声明替换为运营负责人能够提供来源的陈述，并在下一次发布前运行 fixture。如果免费模型访问和免费服务器选项已经是起草步骤的一部分，就将它们以确切短语保留在 pin 中。排除所有没有来源的限制，包括那些会让页面显得比 pin 更新、更及时的限制。
如需采取进一步行动，可以考虑屏蔽此人和／或举报滥用行为。