案例二：给内容团队做文章发布前检查器

一个小团队每周发布操作教程。编辑并不缺“写得更好”的建议，缺的是稳定执行的交付标准：这篇文章写给谁？读者能按顺序完成操作吗？有没有输入与结果的具体例子？需要依据的地方有没有来源线索？每次发稿前重新讨论这些问题，既耗时，也容易因人而异。

我们做一个 Markdown 检查器。它根据版本固定的清单逐项判断，再用普通 Python 汇总为“进入发布队列”或“返回补充”。可读报告由本地模板生成。完成标准是：每一项都能找到对应判断；缺项和不明确分开显示；编辑能根据报告回到原稿修改。publish_queue 只表示满足本清单，可以进入编辑队列，不代表程序已经发布文章。

明确要检查的范围

“文章有质量”很难直接验证，因为它可能同时指正确、清晰、有趣、原创、有用或容易传播。先缩小任务：本案例只检查文本中能观察到的四类材料。模型不打开来源链接，不核验事实，不识别 AI 写作，也不预测 SEO 排名。

这里的来源判断只能表示稿件提供了来源材料，不能推出来源真实、权威或支持该结论。链接是否可访问属于另一项检查；读完页面后比较它是否支持文章主张，又是另一项工作。把这些层次分开，编辑才不会把一张通过报告误当成事实审核完成证书。

每条清单使用一个 Noul 问题，返回对该命题的数值判断。Noul 没有 Choice／Score 那样的独立 confidence；不要在代码里读取一个并不存在的字段。官方 Noul 文档

下载材料并认识三个样本

从配套代码包取得程序后，在项目根目录操作。程序只使用 Python 标准库；若还没准备环境，先看Python 接入。

这些草稿是教学样例，不来自真实客户，也不表示完整稿在任何主题上都值得发布。三份材料组成一个小实验：完整稿给你正常路径，缺项稿给你明确失败路径，模糊稿让你检查程序是否把“不明确”草率当成通过。

先打开三份 Markdown 文件，不运行程序，按四项标准手工标注。这样你才能区分“我真的同意判定”和“我看见模型的数字后才调整自己的标准”。如果你觉得完整稿的某项也不满足要求，先写下原因，不要为了维护样例名字而强行通过。

完整稿讲的是一个很小的任务：把工单对象保存为 JSON，再用 python -m json.tool 检查格式。它明确面向能运行 Python、阅读 JSON 的独立开发者；给出保存、执行、确认三个动作；展示输入对象及格式化后的预期结果；最后放上 Python 官方文档链接。内容短，仍然可以满足清单，因为本案例没有把字数作为质量代理。

缺项稿保留了读者描述，但主体只有“合理使用自动化、认真思考客户需求、持续改进”之类建议，还包含一个没有依据的节省时间比例。编辑可以直接指出缺少动作、示例与来源。检查器不会验证那个比例是对还是错；来源项失败只能说明没有提供所需出处，不能顺势推导出数字一定虚假。

输入、问题与输出怎样连接

本案例的输入是正文和清单两个部分。正文属于待检查材料；清单属于编辑政策。state_for 把正文放进 markdown 字段，问题由 checklist.json 生成，参考标签不进入模型输入。

Markdown 正文 + 清单版本
    → 每项一个 Noul 问题
    → 验证答案结构
    → pass / missing / uncertain
    → publish_queue / revise
    → JSON 记录 + 文本模板报告

原始响应会放在 raw_response；程序根据答案产生的 decision 包含 checks、needs_work 和 recommendation。这一区分非常有用：API 可能给出一个中间值，程序却因为阈值设置而建议退回，两者并没有矛盾。

本案例采用“全部必需项通过”的政策。目标读者写得再清楚，也不能抵消没有操作步骤。官方展示了先分维度再用代码组合的思路；这里选择必需项门槛，而非计算一个可互相补偿的加权总分。官方 Composite scoring

从运行到读报告

先执行离线模式：

python --version
python -m examples.hello_jev content --mode offline
python -m json.tool examples/output/content.json

用文本编辑器打开 examples/output/content.txt。第一屏应能看见证据类型和清单版本，然后是每份稿件的各项状态。若只想确认机器可读部分，可以执行：

import json
from pathlib import Path

report = json.loads(
    Path("examples/output/content.json").read_text(encoding="utf-8")
)
for row in report["records"]:
    decision = row.get("decision")
    if decision:
        print(row["id"], decision["recommendation"])
        print("Needs work:", decision["needs_work"])
    else:
        print(row["id"], row.get("error"))

要保存一次独立结果，给 JSON 文件换名字，文本报告会使用同一主文件名：

python -m examples.hello_jev content --mode offline \
  --output examples/output/content-baseline.json

查看 content-baseline.json 和 content-baseline.txt。报告是本地模板的固定组织形式，检查项名称与结果来自结构化数据。它没有编造一段模型未给出的“推理过程”，也不会自动生成文章改写。

本次离线执行中，完整稿四项通过；缺项稿的 steps、example、sources 分别为 0.05、0.01、0.01，被标成 missing；模糊稿的 sources 为 0.50，被标成 uncertain。这些数值全部是作者编写的夹具。它们演示同样的 revise 建议如何对应不同原因：缺项稿需要补足材料，模糊稿需要检查泛化主页链接与具体命令主张之间的关系。

离线输出明确标记 offline_fixture。这些判断由作者事先写入响应文件，目的是让报告与各分支可复现。因此，离线报告中完整稿通过，不是本书测得 Jev 对完整稿的判断。程序还会检查正文和问题的指纹；修改后继续回放会产生不匹配错误，而不会获得新的语义评价。

阅读真正负责决策的代码

配套代码中的核心策略如下。完整输入加载、响应验证、错误处理和文件写入请使用下载包，不必从正文拼装另一套程序。

def content_decision(answers):
    checks = {}
    for key, answer in answers.items():
        value = answer['noul']
        status = 'pass' if value >= 0.85 else (
            'missing' if value <= 0.15 else 'uncertain'
        )
        checks[key] = {'value': value, 'status': status}
    needs_work = [
        key for key, check in checks.items()
        if check['status'] != 'pass'
    ]
    return {
        'recommendation': 'revise' if needs_work else 'publish_queue',
        'checks': checks,
        'needs_work': needs_work,
    }

数值达到 0.85 才视作通过；不高于 0.15 标为缺项；两者之间为不明确。0.85 和 0.15 是本书演示政策，不是经过行业校准的阈值。“不明确”与“缺项”都返回补充，但编辑的动作不同：缺项需要补材料；不明确需要先查看原文，判断是标准模糊还是内容表达不充分。

注意边界：0.85 通过，0.15 缺项。手写条件时如果分别用了不同的 < 或 <=，边界结果可能改变。自动化测试应覆盖边界，而不是只测试 0 和 1。若你以后让某一项只作提醒，修改的是组合政策，不能直接删掉原始结果。

用缺项实验修正清单

先拿完整稿作为基线，一次只移除一个要素：删除读者说明、删除动作步骤、删除具体示例或删除来源信息。每次保留其他文字，人工写下预期变化。这样可以观察某条标准是否真的在检查所声称的内容。

这些是设计上的边界示例，不是本书声称在线捕获到的模型错误。真实实验要保存原文、清单版本、原始响应和人工判定，才能知道修改是否有效。编辑先看正文再看结果；必要时请第二位编辑独立标注有争议的样本。

一个合理修正过程是：发现“标题冒充步骤”问题；把 steps 的标准从“包含步骤”改成可执行动作；增加一份只含标题的保留样本；用在线调用验证新标准；最后检查原来正常的文章有没有被误伤。不能只看刚修过的那一篇，也不能用离线夹具的变化宣称模型变好。

以缺项稿为例，编辑可以把第一句宽泛建议改成“把示例对象保存到 ticket.json”，第二步加入明确运行命令，再给出成功时应该看到的对象字段。之后补上与命令用途相邻的来源。这个修改计划回应的是可观察缺口，尚不代表修改稿已经通过；要获得新判断，需保存新的稿件版本并进行在线检查或人工复核，而不是继续引用旧报告。

版本管理比总分更重要

清单变更会改变通过的含义。今天要求“有来源链接”，明天要求“每个外部数据有对应来源”，两次通过率便不能直接比较。保存清单文件中的版本，报告顶层的 policy_version 会带出它。

建议把修改说明写成可检查的句子：“示例项新增预期输出要求”，不要只写“优化提示词”。同时保存一组未参与修改的稿件，复测时比较每一项，而非只看总通过数。新增严格要求造成通过率下降，可能正是预期行为，不一定是模型退步。

稿件本身也要有稳定版本。对真实流程，记录原稿路径、内容摘要或内容哈希，确保报告对应的是哪一版。当前演示通过样本清单与本地文件建立对应关系；若后续把它接到多人编辑平台，需要额外实现文档版本绑定，不能默认为报告会自动跟随最新正文。

在线运行与验证记录

配置好 TypeSafe 访问权限与 TYPESAFE_API_KEY 后，可运行：

python -m examples.hello_jev content --mode live \
  --output examples/output/content-live.json
python -m unittest discover -s tests -p 'test_examples.py' -v

本章编写于 2026-09-20。示例的默认请求模型为 jev-latest，在线请求通过 POST https://api.typesafe.ai/v1/systemone 发送。没有 API Key 的交付环境只检查离线路径与程序测试，本章没有在线漏检率、误报率、耗时或费用数据。真实运行后，应保留服务返回模型、usage、HTTP 耗时与错误；如何计费见成本计算。

本地核对使用 Python 3.12.14，共用的 20 项测试通过。三份稿件的实际回放结果为：complete 进入 publish_queue，missing 和 ambiguous 返回 revise，文本报告成功生成。夹具模型字段为 authored-fixture-not-a-model，耗时、token 与费用测量均为空。这些是程序验证记录，不能换算成模型判断三篇文章的准确率。

漏检是人工确认缺项却被程序通过；误报是人工确认满足却被程序退回。两者必须逐项统计。把整篇“至少有一个不通过”算成一次错误，无法分辨是步骤标准太宽，还是来源标准太严。小样本最有价值的产物往往是一份能解释的失败清单，而非漂亮的准确率。

记录人工改判时保留具体段落与理由，下一次修订清单才有可用依据。

把它接进编辑工作

第一步只让检查器生成附在稿件旁边的报告。编辑逐项接受或改判，记录简短理由。等团队对标准达成一致，再考虑将 publish_queue 接到任务看板。当前代码没有发布按钮或外部平台操作。

迁移到产品更新日志、帮助中心或课程讲义时，优先改变清单，不要沿用“文章质量”的抽象问题。例如更新日志可检查受影响用户、变更行为与迁移步骤；帮助中心可检查前置条件、操作路径与错误恢复。这些必须项由业务负责人决定。

如果要自动补写缺失段落，可在检查之后接另一段生成流程，但修改后的全文要重新检查，编辑仍要核对事实。检测缺项与生成正确内容是两个完成标准。下一章将讨论另一种边界：模型可以选择候选工具，程序仍需负责参数与权限校验。