技术文档改写规范：固定英文术语、中文解释与 Mermaid 一致性

AI 参与说明（Agent：Codex）：本文整理技术文档的编辑约定、改写示例和验收流程，供人工编辑与 Coding Agent 分批维护知识库时使用。这里的语言规则是本站写作约定；示范中的技术概念以所链接文章及其官方来源为准。运行记录：模型 gpt-6-astra，reasoning effort ultra，执行入口 Codex Desktop，提供方 openai，CLI 版本 0.153.4（不代表桌面 App 版本）。

阅读前先看这几个词

本文讨论怎样让中文读者顺畅阅读包含英文术语的技术文章。先对照中文名称与简要解释，认识下面几个贯穿示例的英文名称，再看具体规则。

核心规则：同一概念固定一个名称

One concept, one canonical name. Use English for technical names and concise technical facts; use Simplified Chinese to explain relationships, examples, and trade-offs.

这是一条编辑规则。文章仍以简体中文为主体，但同一技术概念只使用选定的英文名称。中文负责解释它做什么、为什么需要它、与其他概念有什么关系；不要把中文译名当成第二个可交替使用的名称。

例如，全文固定使用 Contract Testing，就不要在后续段落又称它为“契约测试”“接口契约验证”，也不要仅为避免重复而换成 Contract Test。需要区分某一次具体测试与整种方法时，应把指代写清楚。

先给读者一张简短参考表

在开头、首次英文核心论述或密集使用专有术语之前，放置“英文术语｜中文名称｜简要解释”参考表。先让读者知道它叫什么，再说明它是什么意思；只有作用描述还不够。优先覆盖标题、开篇段落和第一张图中最关键、最可能陌生的词。

例如 Contract Testing 的中文名称是“契约测试”，简要解释是“检查两个系统交换的数据是否符合双方约定”。Test Oracle 对应“测试预言机”，再解释“判断实际结果是否符合预期的依据或机制”。名称帮助对应词义，解释消除直译可能带来的陌生感，不能省掉其中一项。

中文名称采用通行译名或准确直译，不声称它一定是官方中文名称；Mermaid 等工具名没有合适的中文名称时保留原名。每个解释用一句普通中文，必要时加一个小例子，不用更多尚未解释的英文术语去解释另一个英文词。

本站的开篇参考表使用 <div class="reader-glossary"> 与 </div> 包裹，起止标签与 Markdown 表格之间各留一个空行。验收时确认窄屏上也能看清每个英文名称对应的中文名称与解释，不需要横向滚动才能找到解释。

参考表应短而有针对性；长文可以在后续专题第一次展开时补充局部对照与说明，不必把全文所有词一次塞到开头。例如 Contract 对应“契约”，解释为“接口交互双方必须遵守的数据约定”，不必让读者先理解 Consumer 和 Provider 才能看懂这句话。

读者参考表负责建立理解，中文名称留在对照处，后文仍固定使用英文名称。编辑时使用的“固定名称、待消除别名、概念边界”表用于检查改写，两者用途不同；不能把查错清单直接当作给读者的入门解释，也不能在清理别名时误删参考表中的中文名称。

推荐阅读顺序是：简短中文导语 → 术语参考表 → 英文核心事实 → 中文关系解释与例子。保留必要的 AI 参与说明；较长的历史修订记录可以折叠展示，避免挤占开篇导读。

编辑前建立术语表，再修改句子

每批先选少量文章，通读后列出下面四项。已有同主题示范时，复用其固定名称；新出现的专有名称再核对官方来源。表中的中文别名仅用于查找问题，不作为文章后续的备用名称。

这张表是测试主题的起点，不是所有文章都必须引入的词汇表。角色、过程和产物应分别命名：Consumer Test 是验证 Consumer 的测试，Provider Verification 是验证 Provider 的过程，Contract 是它们使用的约定。不能为了“统一”而把三者都改成 Contract Testing。

大小写、单复数和缩写也要检查。方法名称统一为 Contract Testing；英文句子中的 Contracts 可以表示多个 Contract。真实 API 的拼写、英文语法所需的变化和官方引用标题，不属于自行发明的别名。缩写只有在确实有必要、已明确对应关系且后文用法一致时才使用；短文优先保留完整名称。

正文不交替使用中文译名

开篇参考表保留中文名称，正文统一使用英文名称。下面的反例针对正文中来回切换名称的情况，不是在禁止术语对照。

“中文解释”应是描述作用的句子，例如“Verifier 根据共享密钥与时间计算候选值”。不要写出一个中文名称，再让它接替 Verifier 出现在后文。

也不要把词表中的英文扩散到所有相似中文词。讨论 Pact 角色时用 Consumer 和 Provider；讨论手机应用的生命周期时仍可说“客户端”。“准备初始数据”不是在命名 Precondition；“比较实际值和期望值”也不必把两个值重新命名为 Test Oracle。

英文短事实与中文说明如何衔接

读者已通过开篇参考表认识相关名称后，可以先用一两句英文陈述经核实的技术事实，紧接着用中文解释工程含义。

Pact uses Contract Testing to verify message agreement between a Consumer and a Provider. Side Effects, such as database writes, require separate Functional Testing.

因此，即使返回的数据符合 Contract，也还需要检查订单是否真的写入数据库。针对字段和类型的验证，与针对实际写入的验证，回答的是两个问题。Pact：Contract tests are not functional tests

英文段落是对来源的转述，不能伪装成官方逐字引文。不要随手把官方文档中的 may、must、by default 等限定词删掉；中文衔接也不能把有条件的保证扩展成无条件保证。不设英文占比，不逐句重复翻译。

Mermaid 与正文共用一套术语

Mermaid 节点、边标签、图注和正文必须使用同一张术语表。图中的 Provider Verification 不能在正文里改叫另一套中文名称，正文中的 Contract 也不能在图中变成 Specification。

关系和动作仍可用中文，例如“重放 Request”“比对 Response 与 Contract”。如果一段中文只是描述用户操作，例如“请求超时后返回上一页”，不必为词表中的 Request 机械改写整段业务叙述。

选图依据问题本身：流程与分支使用 flowchart，参与方交互使用 sequenceDiagram，状态转换使用 stateDiagram-v2。flowchart 默认 TB / TD。英文名称变长后，优先缩短动作说明、合理换行，或按阶段拆图；不要靠缩小字体把所有内容塞进一张图。

实际改写按下面的顺序推进：

flowchart TB
    A["通读本批文章"] --> B["确定固定名称<br/>区分不同概念"]
    B --> C["同步正文、图表<br/>与教学示例"]
    C --> D["查别名残留<br/>读句子是否自然"]
    D --> E["运行相关示例<br/>检查 HTML 与 SVG"]
    E --> F["人工 review<br/>再扩大批次"]

一张图只回答一个主要问题。保留失败分支和必要条件，删除已经由图清楚表达的重复步骤；与事实边界有关的文字仍应留在图附近。

示例代码、引用与页面地址的边界

正文改名后，自包含教学示例也要检查。例如，JSON 记录的是跨端业务 Specification，就应使用含义一致的自定义字段与变量：

JSON field: specificationVersion
Python variable: specification
Expected output: 4 cases passed; specification 1.0.0

修改这样的示例时，需要同步 JSON、读取代码、错误提示、运行命令涉及的文件名和预期输出，并重新执行。只有名称一致、示例仍能运行，才能作为后续批量改写的参考。

以下内容必须另行判断：

• 官方 API 与外部协议：保留 SDK 导出名、配置键、JSON 协议字段及命令的精确拼写，不能为了文章用词而改动它们。
• 历史路径与来源：源文件名、relref 目标、slug、canonical URL、官方引用标题都有独立用途。可修改链接显示文字，不能用无差别替换破坏地址。需要改页面标题时，按本站 Giscus pathname 规则核验。
• 历史 AI 参与记录：保留实际参与阶段与参数；追加本轮修订范围，不把当前运行信息归给过去的写作过程。
• 未知概念或事实变化：核对官方文档后再决定名称。不要凭字面相似合并概念，也不要为完成替换而补造英文名称或技术保证。

分批执行与验收

先用两三篇不同结构的文章校准：有长文论证的、有代码的、有 Mermaid 的。通过人工 review 后，再按用户指定的文件清单扩大批次。每批应能独立审阅与回退，不把“全站改写”理解成一次无条件替换。

验收同时检查四件事：

1. 名称一致：标题、正文、表格、图、Prompt 和输出中没有同概念的竞争性名称。搜索别名后逐项判断，代码、路径、引用和正反例中的合理命中应单独区分。
2. 概念正确：没有把相关但不同的概念合并，没有删除关键条件，没有改变技术行为。产品术语、机制或 API 不确定时，用 Context7 找到官方资料并核对上下文；公开引用落到官方原页。
3. 中文流畅：开篇参考表包含英文术语、中文名称与简要解释，读者既能对应词义，也不必先懂另一串英文术语才能理解。正文中的中文句子仍清楚解释行为与关系。英文专有名称放在自然语序中，不出现随机英文动词，也不写逐句中英重复段落。
4. 产物可用：相关代码能运行；Astro 构建后的 HTML 中链接、标题与强调正确；开篇参考表的三个信息项在窄屏可直接对应；Mermaid 生成 SVG，标签完整，在桌面与窄屏可读。源文件通过搜索不等于页面通过验收。

最终交付应简短列出改了哪些文件、采用哪些固定名称、保留了哪些有意不替换的标识，以及实际完成的验证。未解决项留在任务报告中，不把待办清单塞进公开文章。

可交给 Coding Agent 的任务模板

填写明确的文件范围后使用；批次大小只是工作安排，不授予改动未列出文件、发布内容或修改外部协议的额外权限。

Revise only the files listed below for terminology consistency and readability.

Files: <explicit file list>
Approved terminology: <canonical names, aliases to remove, and concept boundaries>
Reference examples:
- docs/Agents/contract-testing-cross-platform-ai-agents.md
- docs/Agents/agent-led-development-testing-concepts.md

Follow the repository's Agents.md and
docs/Agents/technical-terminology-and-mermaid-style-guide.md.
Use one canonical English name for each technical concept in the body. Do not
alternate between English names, Chinese translations, abbreviations, or aliases.
Explain relationships, examples, and trade-offs in natural Simplified Chinese.
Before the first technical discussion, add a short reader-facing table with
three columns: English term, Chinese name, and a brief Simplified Chinese
explanation. Include both the translated name and its meaning: for example,
Contract Testing / 契约测试 / 检查两个系统交换的数据是否符合双方约定.
Use an established or accurate direct translation without claiming it is an
official Chinese name. Retain product names that have no suitable translation.
Cover the key terms in the title, opening paragraphs, and first diagram.
Do not explain unfamiliar terms using more unexplained jargon. Keep the table
distinct from the editing alias map. Preserve its Chinese names during alias
cleanup; this introductory comparison is intentional, not inconsistent naming.
Wrap the opening table in <div class="reader-glossary">...</div>,
with blank lines between the HTML tags and the Markdown table. Verify that
all three pieces of information stay associated and readable on narrow screens
without horizontal scrolling.
After this introduction, use the canonical English names consistently
and write concise English statements for verified core technical facts.

Before editing, read every target file and identify distinct concepts.
Do not merge Contract with Specification, Test Vector with Test Case, or
Test Oracle with Test Runner. Do not replace ordinary Chinese words merely
because they resemble a glossary entry.

Apply the same terminology to headings, prose, tables, Mermaid labels,
captions, link labels, prompts, and tutorial outputs. Preserve exact API names,
external protocol fields, URLs, source paths, and quoted source titles.
If a self-contained tutorial misnames a concept, update its data, code, and
expected output together, then run it. Follow the repository's compatibility
rules before changing a published title or URL. Preserve existing draft states.

Use Context7 and original official documentation to verify library and product
terms, mechanisms, APIs, and version-specific facts, even when they seem familiar.
Reuse relevant evidence already obtained in this task. Do not invent terminology
or weaken technical conditions.
Keep Mermaid diagrams accurate and readable; prefer vertical flowcharts.
Split dense diagrams by responsibility instead of shrinking the text.

Review alias-search matches in context. Run relevant examples, build the site,
inspect generated HTML, and render Mermaid diagrams in desktop and narrow
viewports. Preserve historical AI participation records and add this revision's
scope and verifiable runtime metadata.

Report changed files, terminology decisions, validation results, and unresolved
ambiguities. Stop expanding the batch when a decision needs clarification.

已修订示范

• Contract Testing：接口兼容、多端功能一致性与 AI Agent 编码：同一术语贯穿正文、Mermaid、JSON、Python 与 Prompt；明确 Contract 与 Specification 的边界。
• Agent 开发中的测试方法：Specification、Test Oracle 与验证证据：在多种测试方法之间保持命名一致，同时区分规则、方法、执行过程与判断依据。
• Agent 工程实践导航。