chinese-tech-plain-writing

中文技术清晰写作

Purpose

把中文技术文字改到“工程师一眼能读懂”。适用对象不是某一种文档格式，而是所有需要表达技术判断、方案、变更、风险、步骤或结论的中文 prose。

核心目标：

• 不改事实：保留技术含义、范围、数字、名称、约束、风险和因果关系。
• 降低理解成本：让句子顺、逻辑清、重点先出现。
• 保留工程语境：代码标识符、API、命令、错误信息、协议名和产品名保持原样。
• 少写套话：删掉不提供信息的铺垫、形容词和口号。

Workflow

1. 判断读者和场景：这是设计文档、PR 描述、issue、评审意见、README、事故复盘、发布说明，还是临时说明？输出要匹配这个场景的密度和语气。
2. 找主线：先识别结论、背景、改动、原因、影响、风险、下一步。缺少主线时，重排段落；不要只逐句润色。
3. 保真改写：只改表达，不改技术判断。遇到不确定含义，保守保留原意，必要时用“这里可能是指……”标注疑问。
4. 压缩噪声：删除空话、重复、过度强调和 AI 腔，但保留有用的限定条件。
5. 补齐逻辑连接：把隐含的条件、因果、对比、取舍、例外写清楚。
6. 交付可读版本：优先输出完整改写稿；如果用户要求审稿，先列主要问题，再给建议改写。

Rewrite Principles

1. 先说结论，再给理由

技术读者通常先找答案：做什么、为什么、影响什么、需要谁行动。把结论放在段首或小节开头。

原文	改写
由于当前实现里状态分散在多个入口，后续需求还会继续增加类似判断，所以这里考虑做一次统一收口。	建议把状态判断统一收口。原因是当前状态分散在多个入口，后续需求还会继续增加类似判断。
这个方案整体上可以减少很多复杂度。	这个方案把三处重复判断合并到一个入口，后续新增状态时只需要改一处。

2. 把压缩短语拆成自然句

不要把条件、手段、结果、目的压进一个短语。中文技术文档可以短，但不能让读者猜关系。

原文	改写
零改动自动兼容	不需要改调用方，现有路径会自动兼容。
配置驱动多环境发布	发布流程由配置决定，因此同一套逻辑可以用于多个环境。
灰度异常自动回滚	灰度期间如果核心指标异常，系统会自动回滚。

3. 解释术语之间的关系

连续堆术语会让句子像标签。保留必要术语，但补上“谁影响谁、谁依赖谁、谁负责什么”。

原文	改写
网关限流 Redis 原子扣减	网关用 Redis 记录限流状态，并通过原子扣减避免并发请求绕过限制。
React Suspense 降级兜底	在 React Suspense 边界内加载失败或等待时，显示降级 UI 作为兜底。
K8s HPA 自定义指标弹性伸缩	K8s 的 HPA 根据自定义指标自动扩缩容。

4. 让英文术语服从中文语法

代码和术语可以保留英文，但句子本身要像中文。

原文	改写
bump 版本	提升版本号
dispatch 到 parser	分发给 parser
escape 字符串	对字符串做转义
deploy 到 staging	部署到 staging 环境

保留 git push、commit、PR、CI、OAuth、PostgreSQL、API 名、函数名、命令和错误信息。不要为了中文化而翻译稳定术语。

5. 拆长句，显式标出逻辑

如果一句话同时包含背景、动作、目的、结果或例外，拆成两句以上。常见结构：

• 因为 A，所以 B
• 为了 A，我们做 B
• 如果 A，就 B；否则 C
• 相比 A，B 的代价是 C，但收益是 D

6. 去掉空话，但保留限制条件

删除不提供信息的词：

• “众所周知”“毋庸置疑”“非常重要”“显著提升”“全面赋能”
• “通过完善机制提升整体能力”“打造统一闭环”“形成良好支撑”
• 重复的“可靠、稳定、高效、灵活、可扩展”

不要删除有技术含义的限定：

• “仅影响新建任务”
• “在 Redis 不可用时 fail open”
• “兼容 1.2.x，但不兼容 1.1.x”
• “只在灰度期间开启”

7. 按场景调整语气和粒度

• 设计文档 / RFC：写清背景、目标、非目标、方案、取舍、风险。
• PR 描述：突出改了什么、为什么改、如何验证、影响范围。
• Issue / Bug：写清现象、期望、复现步骤、环境、怀疑原因。
• 评审意见：直接指出问题和风险，给出可执行建议。
• README / 指南：先给最短可用路径，再补概念和高级用法。
• 复盘：区分事实、影响、根因、修复、预防措施；不要模糊责任链。
• 发布说明：面向用户或调用方说明变化、迁移动作和兼容性。

What Not To Change

• 不改代码标识符、API 名、协议名、命令、日志、错误信息。
• 不改数字、版本、路径、配置项、状态名、枚举值。
• 不把不确定内容写成确定结论。
• 不把作者没有说的收益、风险或实现细节补进去。
• 不为了“更正式”而加套话。
• 不把短标签、表格字段、commit message、CLI 输出强行改成散文。

Output Patterns

根据用户请求选择输出形态：

• 直接改写：输出改写后的完整文本，不额外解释。
• 审稿 + 改写：先列 3-7 个主要问题，再给改写稿。
• 局部优化：只改用户选中的段落，保留原有结构。
• 风格统一：统一术语、语气、标题层级和列表格式。

如果原文很长，优先按小节改写，并保留标题层级。

Checklist

交付前检查：

1. 技术含义是否完全保留？
2. 结论是否比原文更早出现？
3. 条件、因果、取舍、例外是否写清楚？
4. 是否删除了空话但保留了限制条件？
5. 代码、命令、API、版本、路径是否原样保留？
6. 中文是否自然，不像英文直译或内部日志？

Relationship To doc-visualizer

• 只需要改写中文技术表达：用 chinese-tech-plain-writing。
• 需要生成可视化 HTML、目录、折叠原文、Mermaid 图：用 doc-visualizer。
• 两者可以叠加：先用本 skill 改清楚中文表达，再用 doc-visualizer 做阅读页面。