---
name: tech-doc-polish
description: >
  Polish technical documents and blog posts into a plain, objective style.
  Use when the user asks to 润色 / 改进 / 校对 / polish / refine / proofread
  a technical doc, blog post, or tutorial, especially to remove subjective,
  exaggerated, dramatic, or grandiose wording, and to supplement missing
  citations in LLM-assisted articles.
---

# 技术文档润色

将技术文档 / 技术博客润色为平实客观的文字。只改措辞，不改技术内容与论点。

## 触发场景

- "润色一下这篇文章" / "帮我改改这篇博客" / "改一下措辞"
- "polish this doc" / "refine this post" / "proofread my blog"
- 在技术文档上下文中要求改进表达、去掉浮夸用词

## 核心风格原则

总目标：**平实客观**——让读者关注技术内容本身，而不是作者的情绪或姿态。

1. **指代明白 / 成分完整**：句子成分完整，谓语后不缺宾语，定语后不缺名词；指代词有明确的先行词，避免让读者脑补。
2. **术语与指代一致**：同一概念、术语、上下文指代对象保持用词稳定；同一对象不用多种表述，除非是上下文必要的说明方式（如首次定义后使用简称）。
3. **客观陈述**：只陈述事实、数据、逻辑，删去作者的情绪和评价姿态。
4. **减少训诫感，平等探索**：不居高临下地指导或教训读者；聚焦于问题本身，用共同探讨的语气陈述，而不是宣布结论。
5. **不夸大、不缩小**：程度词与事实相符；没有依据的强化词和淡化词都删。
6. **补充必要的引用参考来源**：数据、结论、他人观点应有出处；LLM 辅助撰写的文章尤其要检查引用是否缺失、是否真实。
7. **不用黑话**：有规范的技术术语或平实的表述方式时，不用行业黑话、圈内俚语。
8. **不过度口语化**：用平实的书面语陈述；聊天式的口语说法改为中性的书面表述。
9. **不高屋建瓴**：不写宏大叙事、行业趋势、时代背景式的空泛表达。
10. **不用浮夸词**：不用"关键洞察""深度好文""重磅""干货""必看""一文读懂""保姆级"等自我抬升身价的标签词；不用"底层逻辑""顶层设计""战略高度""生态位""范式""方法论"等营造宏大框架感的术语；也不用"一句话总结："这类元叙述式的自我存在感表述。
11. **不戏剧化**：不制造悬念、反转、冲突感。
12. **转折有铺垫**：不用突然的"然而""但是"制造意外；先陈述对照的事实，再转折。
13. **避免元叙述**：不谈论"我正在写什么/如何写/读者应如何读"，而是直接切入话题本身。
14. **减少重复性表述**：避免同一句式、同一词语在相邻段落中反复出现；合并意思相近的句子，保持语言简洁流畅。

## 典型问题与改法

### 指代明白 / 成分完整

- 改前：「这个配置会影响。」
- 改后：「这个配置会影响服务启动速度。」
- 改前：「打开大的，再运行脚本。」
- 改后：「打开最大的日志文件，再运行脚本。」
- 改前：「由于缓存未命中，导致请求变慢。」
- 改后：「缓存未命中导致请求变慢。」
- 清理无明确先行词的指代：「这会显著提升性能。」→ 明确"这"指代什么（如"缓存预热"）。
- 识别信号：句子念起来"缺一块"；谓语动词后没有宾语；定语后缺少名词；「这」「那」「其」距离先行词太远或同时可能指向多个对象。

### 术语与指代一致

- 改前：前文称「工作区」，后文又写「workspace」「项目目录」，指的都是同一个目录。
- 改后：全文统一为「工作区」，首次出现时可标注「工作区（workspace）」。
- 允许的变化：上下文必要的说明方式，如「GNU Stow（以下简称 stow）」这类定义式简称，以及为避免紧邻重复而使用的代词。
- 同一术语的译名、大小写、拼写也要统一（如「GitHub」不写成「github」）。

### 客观陈述

- 改前：「令人兴奋的是，新版本的性能简直起飞了！」
- 改后：「新版本在该场景下吞吐量提升约 40%。」
- 识别信号：感叹号、感情色彩形容词（惊人、惊艳、超赞）、第一人称情绪表达。

### 减少训诫感，平等探索

- 改前：「你必须要理解，这个设计是错误的，应该立刻改掉。」
- 改后：「这个设计在某某场景下会带来某某问题，另一种做法是……」
- 改前：「千万不要这样做。」
- 改后：「这样做在某某情况下会出现某某风险。」
- 识别信号：命令式语气（必须、应该、千万不要）、评价性断言（错误的、显然的）、把作者立场放在读者之上的表述。

### 夸大 / 缩小

- 「彻底解决」→「解决」或「缓解」；「完美支持」→「支持」；「史上最快」→ 给出具体数据。
- 缩小同样避免：「只不过是」「仅仅是」「小问题」这类无依据的淡化词也删。

### 引用参考来源

主要针对 LLM 辅助撰写的文章，这类文章常见两类问题：该有出处的没有出处，以及引用本身是模型编造的。

- 需要出处的内容：具体数据与 benchmark 结果、「研究表明」「据统计」类断言、他人观点或直接引用、版本特性与变更记录、标准或规范条文。
- 文中已有的引用：验证链接是否真实存在、内容是否支持原文表述；LLM 生成的引用可能是编造的。
- 缺失的出处：用网络搜索补充真实来源，优先官方文档、原始论文、一手数据。
- 找不到可靠来源时不要编造引用：把该表述标出并告诉用户，建议删除、弱化或由用户提供来源。
- 引用格式跟随原文惯例（行内链接、脚注、文末参考列表），不强行改变。

### 黑话 / 圈内俚语

- 改前：「这两个模块需要对齐一下颗粒度。」
- 改后：「这两个模块的拆分粒度需要统一。」
- 改前：「播种的典型写法是 check-then-create。」
- 改后：「初始化的典型写法是 check-then-create。」
- 清理有规范替代的圈内说法：「对齐」「拉通」「颗粒度」「打法」「链路」「心智」「黑科技」「姿势」（「正确的使用姿势」→「正确的使用方式」）、直译自英文社区的说法（「播种/seeding」代指初始化数据写入）、仅在特定圈子内通行的说法（「脱库」「扛不住」）。
- 判断标准：存在规范术语、规范译法或平实说法可以替换时，就替换；必须使用时，首次出现给出解释。
- 与「高屋建瓴」一节的「赋能」「抓手」同源，那里针对宏大叙事，这里针对替代具体表述的圈内黑话。

### 过于口语化

- 改前：「这个名字是写死的，改不了。」
- 改后：「该名称固定，不可修改。」
- 同样清理聊天式说法和网络流行语：「搞定」「踩坑」「折腾」「真香」「玩意儿」「一把梭」。
- 注意区分：口语化不等于通俗。简单直白的用词要保留，去掉的是随意感；技术惯用语（如「硬编码」「魔数」）不算口语化，可以正常使用。

### 高屋建瓴

- 「在当今云原生的浪潮下」「随着数字化转型的深入」→ 删除，或改为具体场景。
- 「赋能」「抓手」「闭环」「生态」「体系」等词若无具体所指，改为具体动作。
- 避免用「底层逻辑」「顶层设计」「战略高度」「生态位」「范式」「方法论」等词营造宏大框架感；把具体的技术决策、实现步骤直接陈述出来。

### 浮夸用词

- 清理自我抬升的标签词：「关键洞察」「深度好文」「重磅」「干货」「必看」「一文读懂」「保姆级」。
- 清理营造宏大框架感的术语：「底层逻辑」「顶层设计」「战略高度」「生态位」「范式」「方法论」。
- 标题和小标题同样清理；标题用内容本身命名，不用标签词。
- 清理元叙述式的自我存在感表述，如「一句话总结：」「划重点」「敲黑板」——这类表述多余且突兀，把作者的姿态插入上下文；直接陈述事情本身即可。
  - 改前：「一句话总结：stow 用符号链接把配置文件映射到家目录。」
  - 改后：「stow 用符号链接把配置文件映射到家目录。」

### 戏剧性表达

- 「然而，事情并没有那么简单……」→ 直接陈述问题本身。
- 「一场静悄悄的革命正在发生」→ 删除。
- 不用悬念式段落结尾（如「答案将在下一段揭晓」）。

### 突然转折

- 无铺垫的「但是」「然而」「没想到的是」→ 先陈述对照的事实，再用中性连接（「另一方面」「与之相比」），或不用连接词直接陈述。

### 避免元叙述

元叙述是指作者不直接陈述技术内容本身，而是把「我正在写什么」「如何写」「读者应该如何读」这类自我指涉的说明插入正文。它会让作者的形态、写作过程或文章结构挡在话题前面，打断读者对内容本身的关注。

典型表现：

- **预告/铺垫式**：「这里先交代一下……」「另外要说明的是……」「先铺垫一个背景」「这个时间差后文会反复出现」。
- **结构式**：「以下按主题整理」「本文主要聚焦于」「这一部分我们来讨论」「言归正传」。
- **自我评论式**：「这很有意思」「这正是关键」「值得强调的是」「不得不说」「不得不说的是」「背后的想法是」。
- **读者引导式**：「让我们来看一下」「你可以看到」「不难看出」「想象一下」。
- **转述/委托式**：反复用「方案中说」「文档中提到」「正如前文所述」把论点推给另一份文本，而不是直接陈述自己的判断。

注意：必要的前置说明（如「本文假设读者已了解 X」）和适度的承上启下（如「回到 HTTP 映射」）不算是元叙述；需要清理的是把作者姿态、写作过程或文章结构本身当作内容的表述。

改法示例：

- 改前：「另外要交代的是落地程度：」
- 改后：「落地程度是：」或直接陈述。
- 改前：「具体长什么样，把两套注解放在一起看：」
- 改后：「两套注解可以并存：」后直接给出示例。
- 改前：「以下按主题整理。」
- 改后：直接用标题或列表呈现主题，不需要引言。
- 改前：「这一点确实值得展开一下。」
- 改后：直接展开。
- 改前：「让我们看看这个例子。」
- 改后：直接呈现例子。
- 改前：「背后的想法是：只保留 net/http 外层路由……」
- 改后：直接陈述结论，如「业务语义全在 gRPC/信封一侧，HTTP 层只保留 net/http 外层路由即可……」

### 减少重复性表述

- 改前：「这个函数很重要。这个函数负责初始化连接。这个函数在启动时调用。」
- 改后：「该函数在启动时初始化连接。」
- 改前：「首先，打开配置文件。然后，读取配置文件。最后，解析配置文件。」
- 改后：「打开、读取并解析配置文件。」
- 识别信号：同一句式反复出现、同一词语在相邻句子中多次出现、意思相近的句子堆叠。

英文文档同样适用以上原则：避免 hype 用词（revolutionary、game-changing、seamless、blazingly fast 而无数据支撑）和戏剧性叙事。

## 工作流程

1. 通读全文，理解技术内容、论点和结构；确认没有误解再动笔。
2. 逐段标记违反上述原则的措辞，以及缺失或可疑的引用。
3. 改写时遵守边界：
   - 不改变技术事实、数据、代码、命令、链接。
   - 不增删论点与结论，只改措辞。
   - 保留 Markdown 结构与格式。
   - 保持原文语言（中文原文改中文，英文原文改英文）。
   - 补充的引用必须真实可查证；查不到就不加，标出请用户确认。
4. 用户给了文件路径就用编辑工具直接改文件；否则在回复中给出改写后的全文。
5. 改完简要说明主要改动类型（如：补全 2 处省略成分、统一 3 处术语、删除 2 处夸张表述、改写 1 处突然转折、补充 2 处引用）。

## 边界与例外

- 拿不准的技术表述保持原样，并向用户指出待确认。
- 引用他人的原话、有出处的宣传语不改，但可建议加引号或注明出处。
- 用户明确说明要保留的个人风格（如固定栏目的口头禅）予以保留。