“熔断器像一扇会休息的门”是个容易理解的比喻。可如果原说明写着超时 200ms、失败率阈值 30%、5 秒后半开而改写只剩下“疲惫时轻轻关门”读者就无法配置和排障。技术写作的亲和力来自解释清楚。关键事实、成立条件和失败方式要比修辞更稳。先给事实一张不能随意改动的卡把原文拆成事实卡与解释文字。事实卡保留名称、数字、单位、否定条件和来源位置解释文字可以换句式或补例子。模型输出后先核对事实再讨论语气。2026 年 10 月 22 日的 ThinkingBox 研究以数据库最终状态评估 Agent而不是根据它的完成宣言打分。写作工具也可以借用这个思路评价改写结果留下了什么而非只听它保证“信息完整”。本文没有复现该研究的训练或基准。研究说明图中数值属于教学示例不是某个线上系统的实测配置。一个简单但有边界的数字检查保存为 facts.py。它只能发现明确数字与单位的遗漏不能理解“全盘加密”和“数据库加密”的范围差别。import re PATTERN r\d(?:\.\d)?\s*(?:ms|QPS|s|%) def quantities(text): return {re.sub(r\s, , v) for v in re.findall(PATTERN, text)} source 服务设计目标500 QPS超时200ms失败率30%5s后半开。 good 面向500 QPS的设计目标超过200 ms就超时失败率30%5 s后半开。 bad 请求太慢时门会休息一会儿。 def missing(original, rewritten): return sorted(quantities(original) - quantities(rewritten)) assert missing(source, good) [] assert set(missing(source, bad)) {500QPS, 200ms, 30%, 5s} print(丢失的量值, missing(source, bad))同样的数值也可能被安到错误对象上所以集合相同不是“语义保真通过”。再做一轮人工核对200ms 是哪条链路的超时30% 的分母和统计窗口是什么5 秒后是尝试半开还是完全恢复500 QPS 是设计目标还是观测结果。改写示范原句“当统计窗口内失败率达到 30%熔断器进入打开状态5s 后转入半开。”可改成“一段时间内失败率达到 30% 时熔断器先挡住后续请求。5s 后它只放行试探请求确认依赖恢复再按配置决定是否完全打开通道。”若原文没有说明半开流量大小不应加上“一次只放一个”。具体项目的打开、关闭命名可能和门的日常含义相反最后仍应对照实现。示例不是一个完整熔断器规范。Ollama 的结构化输出可以约束 JSON 形状方便返回“改写文本、保留事实、待核实项”但合法结构不会替你证明内容正确。官方文档本文只实跑了量值遗漏检测没有调用真实模型或校验生产架构。把比喻放在事实旁边读者能读懂也能拿着说明做事。
“熔断器像一扇会休息的门”是个容易理解的比喻。可如果原说明写着超时 200ms、失败率阈值 30%、5 秒后半开而改写只剩下“疲惫时轻轻关门”读者就无法配置和排障。技术写作的亲和力来自解释清楚。关键事实、成立条件和失败方式要比修辞更稳。先给事实一张不能随意改动的卡把原文拆成事实卡与解释文字。事实卡保留名称、数字、单位、否定条件和来源位置解释文字可以换句式或补例子。模型输出后先核对事实再讨论语气。2026 年 10 月 22 日的 ThinkingBox 研究以数据库最终状态评估 Agent而不是根据它的完成宣言打分。写作工具也可以借用这个思路评价改写结果留下了什么而非只听它保证“信息完整”。本文没有复现该研究的训练或基准。研究说明图中数值属于教学示例不是某个线上系统的实测配置。一个简单但有边界的数字检查保存为 facts.py。它只能发现明确数字与单位的遗漏不能理解“全盘加密”和“数据库加密”的范围差别。import re PATTERN r\d(?:\.\d)?\s*(?:ms|QPS|s|%) def quantities(text): return {re.sub(r\s, , v) for v in re.findall(PATTERN, text)} source 服务设计目标500 QPS超时200ms失败率30%5s后半开。 good 面向500 QPS的设计目标超过200 ms就超时失败率30%5 s后半开。 bad 请求太慢时门会休息一会儿。 def missing(original, rewritten): return sorted(quantities(original) - quantities(rewritten)) assert missing(source, good) [] assert set(missing(source, bad)) {500QPS, 200ms, 30%, 5s} print(丢失的量值, missing(source, bad))同样的数值也可能被安到错误对象上所以集合相同不是“语义保真通过”。再做一轮人工核对200ms 是哪条链路的超时30% 的分母和统计窗口是什么5 秒后是尝试半开还是完全恢复500 QPS 是设计目标还是观测结果。改写示范原句“当统计窗口内失败率达到 30%熔断器进入打开状态5s 后转入半开。”可改成“一段时间内失败率达到 30% 时熔断器先挡住后续请求。5s 后它只放行试探请求确认依赖恢复再按配置决定是否完全打开通道。”若原文没有说明半开流量大小不应加上“一次只放一个”。具体项目的打开、关闭命名可能和门的日常含义相反最后仍应对照实现。示例不是一个完整熔断器规范。Ollama 的结构化输出可以约束 JSON 形状方便返回“改写文本、保留事实、待核实项”但合法结构不会替你证明内容正确。官方文档本文只实跑了量值遗漏检测没有调用真实模型或校验生产架构。把比喻放在事实旁边读者能读懂也能拿着说明做事。
