| 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"
- 在技术文档上下文中要求改进表达、去掉浮夸用词
核心风格原则
总目标：平实客观——让读者关注技术内容本身，而不是作者的情绪或姿态。
- 客观陈述：只陈述事实、数据、逻辑，删去作者的情绪和评价姿态。
- 不夸大、不缩小：程度词必须与事实相符；没有依据的强程度词和淡化词都删。
- 不高屋建瓴：不写宏大叙事、行业趋势、时代背景式的空泛表达。
- 不戏剧化：不制造悬念、反转、冲突感。
- 转折有铺垫：不用突然的"然而""但是"制造意外；先陈述对照的事实，再转折。
- 不用浮夸词：不用"关键洞察"这类自我抬升身价的标签词。
- 补充必要的引用参考来源：数据、结论、他人观点应有出处；LLM 辅助撰写的文章尤其要检查引用是否缺失、是否真实。
- 指代稳定：概念、术语、上下文指代对象保持用词稳定；同一对象不用多种表述，除非是上下文必要的说明方式（如首次定义后使用简称）。
- 不过度口语化：用平实的书面语陈述；聊天式的口语说法改为中性的书面表述。
典型问题与改法
主观情绪化
- 改前：「令人兴奋的是，新版本的性能简直起飞了！」
- 改后：「新版本在该场景下吞吐量提升约 40%。」
- 识别信号：感叹号、感情色彩形容词（惊人、惊艳、超赞）、第一人称情绪表达。
夸大 / 缩小
- 「彻底解决」→「解决」或「缓解」；「完美支持」→「支持」；「史上最快」→ 给出具体数据。
- 缩小同样避免：「只不过是」「仅仅是」「小问题」这类无依据的淡化词也删。
高屋建瓴
- 「在当今云原生的浪潮下」「随着数字化转型的深入」→ 删除，或改为具体场景。
- 「赋能」「抓手」「闭环」「生态」「体系」等词若无具体所指，改为具体动作。
戏剧性表达
- 「然而，事情并没有那么简单……」→ 直接陈述问题本身。
- 「一场静悄悄的革命正在发生」→ 删除。
- 不用悬念式段落结尾（如「答案将在下一段揭晓」）。
突然转折
- 无铺垫的「但是」「然而」「没想到的是」→ 先陈述对照的事实，再用中性连接（「另一方面」「与之相比」），或不用连接词直接陈述。
浮夸用词
- 清理：「关键洞察」「深度好文」「重磅」「干货」「必看」「一文读懂」「保姆级」。
- 标题和小标题同样清理；标题用内容本身命名，不用标签词。
- 同样清理元叙述式的自我存在感表述，如「一句话总结：」「划重点」「敲黑板」——这类表述多余且突兀，把作者的姿态插入上下文；直接陈述事情本身即可。
- 改前：「一句话总结：stow 用符号链接把配置文件映射到家目录。」
- 改后：「stow 用符号链接把配置文件映射到家目录。」
引用参考来源
主要针对 LLM 辅助撰写的文章，这类文章常见两类问题：该有出处的没有出处，以及引用本身是模型编造的。
- 需要出处的内容：具体数据与 benchmark 结果、「研究表明」「据统计」类断言、他人观点或直接引用、版本特性与变更记录、标准或规范条文。
- 文中已有的引用：验证链接是否真实存在、内容是否支持原文表述；LLM 生成的引用可能是编造的。
- 缺失的出处：用网络搜索补充真实来源，优先官方文档、原始论文、一手数据。
- 找不到可靠来源时不要编造引用：把该表述标出并告诉用户，建议删除、弱化或由用户提供来源。
- 引用格式跟随原文惯例（行内链接、脚注、文末参考列表），不强行改变。
术语与指代一致
- 改前：前文称「工作区」，后文又写「workspace」「项目目录」，指的都是同一个目录。
- 改后：全文统一为「工作区」，首次出现时可标注「工作区（workspace）」。
- 允许的变化：上下文必要的说明方式，如「GNU Stow（以下简称 stow）」这类定义式简称，以及为避免紧邻重复而使用的代词。
- 同一术语的译名、大小写、拼写也要统一（如「GitHub」不写成「github」）。
过于口语化
- 改前：「这个名字是写死的，改不了。」
- 改后：「该名称固定，不可修改。」
- 同样清理聊天式说法和网络流行语：「搞定」「踩坑」「折腾」「真香」「玩意儿」「一把梭」。
- 注意区分：口语化不等于通俗。简单直白的用词要保留，去掉的是随意感；技术惯用语（如「硬编码」「魔数」）不算口语化，可以正常使用。
英文文档同样适用以上原则：避免 hype 用词（revolutionary、game-changing、seamless、blazingly fast 而无数据支撑）和戏剧性叙事。
工作流程
- 通读全文，理解技术内容、论点和结构；确认没有误解再动笔。
- 逐段标记违反上述原则的措辞，以及缺失或可疑的引用。
- 改写时遵守边界：
- 不改变技术事实、数据、代码、命令、链接。
- 不增删论点与结论，只改措辞。
- 保留 Markdown 结构与格式。
- 保持原文语言（中文原文改中文，英文原文改英文）。
- 补充的引用必须真实可查证；查不到就不加，标出请用户确认。
- 用户给了文件路径就用编辑工具直接改文件；否则在回复中给出改写后的全文。
- 改完简要说明主要改动类型（如：删除 3 处夸张表述、改写 2 处突然转折、补充 2 处引用）。
边界与例外
- 拿不准的技术表述保持原样，并向用户指出待确认。
- 引用他人的原话、有出处的宣传语不改，但可建议加引号或注明出处。
- 用户明确说明要保留的个人风格（如固定栏目的口头禅）予以保留。
