Software Systems Atlas

中文

English

中文

English

主题

Software Systems Atlas 全仓文章审校设计 ​

1. 目标 ​

对批准本设计时 docs/ 下已有的 555 篇 Markdown 做可追踪的逐篇审校，并同步整理项目入口 README.md。审校同时解决四类问题：

  1. 删除机械排比、空泛总结、翻译腔、营销腔和滥用破折号等 AI 写作痕迹；
  2. 纠正错别字、病句、术语、技术事实和示例代码；
  3. 保留既有背景故事，让叙述更自然、更完整，但不改变人物、地点、事件、关系、事件顺序或跨卷钩子；
  4. 让初学者能按步骤学习，也让专业读者能快速定位定义、边界、取舍和生产注意事项。

完成标准不是“脚本跑过所有文件”，而是每篇文章都有与当前内容绑定的审校证据。

2. 范围 ​

2.1 必须处理 ​

  • 批准本设计时已有的 555 篇 docs/**/*.md，包括 345 篇中文和 210 篇英文；
  • README.md：作为仓库入口单独处理；
  • 主章节、拆分子章节、卷首页、学习路径、站点入口和说明页都在范围内。

这 555 篇文章由实施阶段生成的基线清单固定。此后新增的 docs/superpowers/** 设计和实施计划属于过程文档，不进入课程审校范围，也不改变基线计数。

2.2 不修改 ​

  • PLAN.md：它是内部执行计划，不是公开课程正文；
  • EVALUATION_AND_OUTLOOK.md：当前未被 Git 跟踪，视为用户正在维护的文件；
  • JSON 课程数据和 VitePress 配置，除非正文修改暴露了必须同步的链接或标题问题。

docs/语气.md 和 docs/.vitepress/CHAPTER-DECOMPOSITION-PLAN.md 位于 555 篇清单内，但属于内部规范。它们只做文字、术语和事实审校，不强行套用课程章节结构。

3. 权威来源与冲突顺序 ​

发生冲突时，按以下顺序处理：

  1. 技术正确性和可运行性；
  2. 本设计与 PLAN.md 的课程原则；
  3. docs/语气.md 的世界观、角色和叙事密度；
  4. 中文主版本；
  5. 英文版本。

中文是内容主版本。英文文章要在对应中文文章审校后再处理；英文不是逐字翻译，而是保持事实、结构和故事锚点一致的自然英文版本。

4. 背景故事不变量 ​

4.1 不得改变的内容 ​

  • 读者从变量村出发，依次经过既有各卷区域；
  • 老陈师傅、阿花、馆长、林将军的身份、性格、关系和出现范围；
  • 每卷现有区域、冒险阶段和跨卷钩子；
  • 已经发生的故事事件、事件顺序、角色行为动机和故事结论；
  • Vol 0–2、Vol 3–5、Vol 6–8、Vol 9+ 的叙事密度递减规则。

4.2 允许的编辑 ​

  • 修正叙事段落中的病句、重复、视角跳跃和生硬翻译；
  • 补充能解释当前技术问题的环境、动作或因果，但不得创造新事件；
  • 缩短干扰技术理解的装饰性比喻；
  • 在比喻后补充正式定义、适用边界和失效条件；
  • 调整对话措辞，使语气符合角色，但不得改变对话意图。

每篇涉及世界观的文章必须完成一次故事核对：人物、地点、事件、顺序、钩子和叙事密度六项全部通过，才能标记为已审校。

5. 文章的双读者结构 ​

课程文章按内容需要提供以下入口，不要求每篇机械地使用完全相同的标题。

5.1 初学者路径 ​

  1. 说明学习前需要掌握什么；
  2. 先给出一个具体问题，解释为什么现在需要这个概念；
  3. 展示最小可理解或可运行的例子；
  4. 按因果关系解释每一步，而不是一次倾倒完整定义；
  5. 给出结果检查点，让读者知道自己是否做对；
  6. 说明常见错误、概念边界和下一步练习。

扩写必须补充理解所需的因果、示例、边界或练习。禁止用重复总结、形容词和新故事填充篇幅。

5.2 专业读者路径 ​

专业读者应能在文章前部或清晰目录中快速找到：

  • 核心定义和结论；
  • 关键接口、算法、协议或数据结构；
  • 时间与空间复杂度、性能特征或安全边界；
  • 方案取舍、适用场景和不适用场景；
  • 生产环境注意事项和进一步阅读入口。

短小的实验页、练习页和索引页可以用简洁的摘要或表格满足这一要求，不必人为增加“专业读者”章节。

6. Humanizer 编辑规则 ​

每篇中文文章使用 humanizer-zh 与 chinese-writing 的标准逐段检查。英文文章使用等价的英文编辑规则。

必须处理：

  • 空泛开场、过度总结和万能式积极结尾；
  • “不仅仅是……而是……”等否定式排比；
  • 为了显得完整而强凑的三项列举；
  • “至关重要”“深入探讨”“格局”“赋能”等没有提供信息的词；
  • 过量的粗体、表情符号、长破折号和戏剧性单句；
  • 模糊归因、无来源的权威判断和知识截止日期式免责声明；
  • 同义词循环、翻译腔、系动词回避和句长单一。

不做机械禁词。某个词若承担准确技术含义，可以保留；问题在于它是否提供信息。每篇完成后按直接性、节奏、信任度、真实性和精炼度五项评分，目标至少 45/50。评分只作为编辑复核，不替代技术验证。

7. 技术纠错与示例验证 ​

7.1 事实 ​

  • 技术事实优先查规范、标准、论文和官方文档；
  • 可能随版本变化的内容必须记录所依据的版本或日期；
  • 无法可靠确认的说法不猜测：删除、缩小结论或明确标注限制；
  • 中文和英文冲突时先确认事实，再同时修正，不能直接以其中一篇为准。

7.2 代码块分类 ​

每个代码块归入以下一种：

  • runnable：可以在声明的运行环境中执行；
  • partial：片段依赖文章上下文，必须写明缺失部分；
  • pseudocode：用于解释算法，不能伪装成可运行代码；
  • output：命令输出或结构示意；
  • config：配置片段，必须写明适用版本和放置位置。

标记为 runnable 的示例必须实际运行。无法安全运行或依赖外部服务的示例要做静态验证，并在文章中说明验证边界。命令必须区分 Linux、macOS、Windows 或明确仅适用的平台。

7.3 已知基线问题 ​

第一轮已经确认至少存在以下问题，实施时必须修复对应中英文文章：

  • Java 入门英文章把“编译和运行两个阶段”错误推广到所有语言；
  • 密码学章用 RSA 预主密钥流程描述现代 TLS，未区分 TLS 1.2 与 TLS 1.3；
  • 个别 C 代码示例存在缺少逗号等语法错误；
  • 两篇英文卷首页仍保留中文标题；
  • 部分英文内容是生硬直译，不能独立阅读。

这些例子只证明问题存在，不代表纠错范围仅限于此。

8. 审校状态与可追踪性 ​

新增一份机器可读的内容审校清单。每个文件记录：

  • 文件路径；
  • 当前内容哈希；
  • humanize_status；
  • technical_review_status；
  • example_verification_status；
  • narrative_check_status；
  • translation_sync_status；
  • 最后审校日期和简短备注。

状态至少包括 pending、in_review、reviewed、verified 和 not_applicable。文章内容哈希变化后，旧状态必须失效。任何批处理不得直接把全部文件标为 reviewed。

审校脚本负责检查清单覆盖率、内容哈希、必填状态、代码围栏、内部链接和中英文对应关系。它用于发现遗漏，不自动宣称文字已经自然或事实已经正确。

9. 分批顺序 ​

批次 A：入口与标准 ​

  • README.md；
  • 中文和英文首页、Start Here、课程目录、学习路径；
  • docs/语气.md；
  • 审校清单与验证工具。

这一批先建立读者入口、术语和验收基线。

批次 B：Vol 0–2 ​

先处理拆分子章节，再处理同主题主章节。两者都保留，不用自动复制覆盖。主章节负责完整地图，子章节负责更细的学习步长；相同概念和示例必须一致。

批次 C：Vol 3–8 ​

重点检查系统、网络、数据库、分布式和安全内容的正式模型、版本、边界条件与代码。

批次 D：Vol 9–13 ​

重点检查抽象定义、数学符号、论文结论、模型术语和时效性。按照既有规则降低叙事密度。

批次 E：英文版 ​

按中文已审校版本逐卷同步，修复直译、残留中文、术语漂移和中英文事实冲突。

每个大批次再拆成可独立复核的小批，每批以一组紧密相关的文章为单位。一个批次未通过验证时，不继续传播到英文版。

10. 验收与回归检查 ​

10.1 单篇验收 ​

一篇文章标记为已审校前，必须证明：

  • 含义和故事不变量保持；
  • Humanizer 五项评分达到 45/50；
  • 初学者能找到前置、步骤、检查点和常见错误；
  • 专业读者能快速找到定义、边界和取舍；
  • 技术事实已经核对，无法验证的部分有明确说明；
  • 代码块分类正确，runnable 示例已经运行；
  • 标题、前置知识、链接和下一篇指向没有失效；
  • 若有双语版本，中英文事实和故事锚点一致。

10.2 每批验收 ​

  • 运行内容审校清单校验；
  • 运行 npm run validate:docs；
  • 运行与本批示例相关的语言或工具测试；
  • 检查本批 Git diff，确认没有意外删除故事段落或代码；
  • 对至少一篇初学者文章和一篇高阶文章做人工结构复核。

10.3 全仓验收 ​

  • 555 篇基线文章和 README.md 均有与当前哈希匹配的最终状态；
  • 当前仓库中的全部站点 Markdown（包括过程文档）通过现有文档校验；
  • npm run build 成功；
  • 所有 runnable 示例有实际验证记录；
  • 故事核对、技术审校和中英文同步没有待处理项；
  • 抽样阅读不能发现批量替换痕迹、机械模板或未经证实的“已完成”声明。

只有这些证据同时成立，才能宣布全仓工作完成。

11. 失败处理 ​

  • 资料冲突：优先保留较窄、可证明的结论，并记录来源差异；
  • 示例失败：先修示例或环境说明，不能只改预期输出；
  • 故事与技术冲突：保留故事事件，重写隐喻并补充正式模型；
  • 中英文无法一一对应：保证事实与学习目标一致，允许段落结构不同；
  • 单篇过长：可以在现有拆分体系内改善导航，但不在本项目中擅自删除或重构章节；
  • 验证未通过：状态保持 in_review，不计入完成数。

12. 非目标 ​

  • 不新增卷、角色、世界区域或故事主线；
  • 不把所有文章强制改成同一模板；
  • 不为了篇幅而扩写；
  • 不用搜索替换结果代替逐篇阅读；
  • 不因为已有 555 篇文件就宣称课程已经完成；
  • 不在本次工作中重做站点视觉设计。

Built with VitePress | Software Systems Atlas

Copyright 2026 Steven Yang