AI 写中文技术文档总有一股宣传味?我试了 Fenng 的这个 Skill

AI 写中文技术文档总有一股宣传味？我试了 Fenng 的这个 Skill

最近看到 Fenng 开源了一个很有意思的项目：

Tech-Doc-Style-Chinese

简单来说，这是一套可以安装到 Codex、Claude Code 等 AI 编程工具中的中文技术写作 Skill。

它不负责让文章变得更华丽，也不负责制造所谓的「高级感」。

它主要解决一个很朴素的问题：

怎么让 AI 写出来的中文技术文档更准确、更克制，也更像一个真正做过项目的人写的。

这恰好是我最近比较关心的问题。

因为随着 AI 越来越多地参与编程，除了生成代码，我们还会让它写 README、接口说明、故障排查文档、产品介绍、更新日志和操作手册。

代码写得对不对，可以通过测试和运行验证。

但文档里的问题往往没有那么明显。

有时候一句话看起来很通顺，却可能悄悄扩大了产品能力、删除了限制条件，或者把一个「可能发生」的情况写成了「必然发生」。

这类问题，比标点不统一更值得警惕。

先介绍一下 Fenng

Fenng 是冯大辉的网名。

很多早期互联网从业者应该都知道他。他早年因 Oracle、数据库和技术博客受到关注，曾担任支付宝数据库架构师、丁香园 CTO，同时长期运营微信公众号「小道消息」。

这不是一个普通的「润色提示词」

刚看到项目名称时，我以为它可能只是一份中文排版规范。

比如：

• 中文和英文之间加空格；
• 统一标点；
• 少用网络黑话；
• 句子不要写得太长。

看完仓库后，我发现它比这个完整得多。

整个项目除了 SKILL.md，还包含：

• 术语与排版规则；
• API 状态和错误文案规范；
• 故障排查与运维文档写法；
• 项目级覆盖模板；
• 中文文案检查脚本；
• 检查器的自动化测试。

也就是说，它不只是告诉 AI「文档写得专业一点」，而是给出了比较明确的判断顺序。

其中最重要的一条是：

文案优化不能改变事实。

例如，AI 在改写文档时不能凭空增加：

• 日期和数字；
• 处理期限和 SLA；
• 产品已经具备的能力；
• 前置条件；
• 因果关系；
• 确定性结论。

资料不足时，可以保留原来的不确定性，也可以标记为「待确认」，但不能为了让句子更完整而自行补充事实。

这套 Skill 的优先级也很清楚：

事实和安全含义
-> 项目自身约定
-> 技术术语和机器可读内容
-> 文档结构与语气
-> 标点和排版

这点很符合我的使用习惯。

技术文档首先要正确，然后才轮到好不好看。

我拿自己的文档做了一次实测

为了避免只看项目介绍，我拿自己的两份内容跑了一次仓库里的检查器：

• 小学生记单词项目的 README.md；
• 一篇 ShardingSphere 元数据问题的技术复盘。

检查结果是：

检查文件：2 个
error：0
warning：0
style：27

27 个风格提示主要集中在两个地方。

第一个是中文引号。

我的原文习惯使用：

“表不存在”
“同步作业建表之前”
“已掌握”

这套 Skill 默认建议使用：

「表不存在」
「同步作业建表之前」
「已掌握」

这属于风格选择，不是事实错误。检查器也只是把它标记为 style，没有武断地判定文档不合格。

第二个提示出现在 H5。

项目标题原来是：

词航英语小助手 H5

检查器提醒，需要根据语境确认这里的 H5 究竟表示移动 Web 页面，还是 HTML5 技术。

这个提醒看起来很小，但确实有价值。

我们日常习惯使用的缩写，团队内部可能都能理解；一旦文档交给外部用户，含义就未必清楚。

我又试着改写了一段 README

原来的语音功能说明是：

发音使用浏览器语音合成功能；跟读识别使用浏览器 Web Speech API。
首次使用麦克风时需要允许权限。
若浏览器不支持或用户拒绝授权，页面会播放范读并允许手动进入下一题。

按照这个 Skill 的思路，可以整理成：

发音使用浏览器的语音合成功能，跟读识别使用 Web Speech API。

首次使用跟读功能时，浏览器会请求麦克风权限。

出现以下任一情况时，系统不执行跟读识别：

- 浏览器不支持 Web Speech API；
- 用户拒绝麦克风权限。

此时，页面仍会播放范读，并允许手动进入下一题。

这次改写没有增加新功能，也没有改变失败后的处理方式。

它只是把几个信息拆清楚了：

用了什么能力
什么时候申请权限
哪些情况会失败
失败以后还能做什么

我觉得这正是技术文档需要的改进。

不是让句子更「高级」，而是让使用者更快找到自己关心的信息。

我最认可的三个地方

1. 事实保真排在语言优化之前

AI 特别擅长把句子补完整。

但技术文档里，「补完整」有时反而是一种风险。

原文只说「支持部分浏览器」，AI 可能改成「支持主流浏览器」；原文说「建议尽快处理」，AI 可能自行补成「30 分钟内处理」。

句子更具体了，事实却可能错了。

这套 Skill 明确要求保留条件、限制、风险和不确定程度。我认为这是它最有价值的地方。

2. 它知道什么内容不能随便改

代码字面量、JSON 键名、URL、API 路径、数据库字段、命令和配置项，都不属于普通中文润色范围。

这听起来理所当然，但 AI 在批量改写文档时，确实可能顺手修改代码块、字段名或者路径。

这套 Skill 会先划出机器可读内容的边界，再处理自然语言。

3. 它允许项目拥有自己的规则

通用规范不可能适合所有团队。

有的项目使用直角引号，有的项目使用弯引号；有的产品强调简洁，有的产品需要更友好的用户语气；不同团队也有自己的术语表和版本命名方式。

这个项目没有把所有偏好写成不可改变的规则，而是提供了项目级覆盖机制。

这一点比较务实。

它也不是什么万能写作工具

实测以后，我觉得它的边界同样需要说清楚。

第一，它主要面向技术文档、产品文案和界面文案，不是公众号写作 Skill。

如果想写一篇有故事、有个人经历、有情绪变化的文章，它不会自动帮你完成这些内容。

第二，检查器只能发现一部分高频问题。

我测试的两份文档没有出现 error 和 warning，不代表内容已经没有问题。事实是否准确、因果关系是否成立、排查过程是否完整，仍然需要作者自己判断。

仓库本身也明确说明：自动检查不能证明语义正确，更不能代替人工复核。

项目规则说明

第三，部分规则属于风格偏好。

例如是否统一使用「直角引号」，可以根据自己的项目约定决定，没有必要机械执行所有建议。

所以，我更愿意把它理解成：

一个中文技术写作的审稿框架，而不是一台自动把文档变好的机器。

怎么安装到 Codex

如果本机已经有 Node.js，可以在项目目录执行：

npx skills add https://github.com/Fenng/tech-doc-style-chinese -a codex

这样默认安装到当前项目范围。

如果确认希望所有项目都能使用，可以再考虑全局安装：

npx -y skills add https://github.com/Fenng/tech-doc-style-chinese -a codex -g

安装后建议重启 Codex。

使用时可以明确告诉 Codex：

使用 tech-doc-style-chinese 检查并改写这份中文技术文档。
保留原有事实、数字、限制、代码和配置项。

也可以直接让它处理：

• README；
• API 文档；
• 故障排查记录；
• 运维操作手册；
• FAQ；
• 产品能力说明；
• 按钮和错误提示。

完整安装方式可以查看项目 README。

需要提醒的是，Skill 本质上会向 AI 提供指令，有些 Skill 还会附带可执行脚本。安装第三方 Skill 前，最好先看一下 SKILL.md 和脚本内容，再决定安装到单个项目还是全局。

最后

这次体验下来，我觉得这个 Skill 最值得推荐的地方，不是统一引号，也不是帮中文和英文加空格。

它真正解决的是另一个问题：

当 AI 开始替我们写大量技术内容时，如何约束它不要为了表达流畅而改变事实。

AI 可以帮助我们提高写作速度，但速度越快，越需要明确边界。

哪些内容可以改？

哪些内容不能动？

哪些是事实？

哪些只是建议？

哪些地方资料不足，需要标记为待确认？

Fenng 的这套 Skill 没有试图让所有文档都变成同一种风格，而是先守住了中文技术写作最重要的底线：

准确先于修辞，清晰先于热闹。

对经常使用 Codex、Claude Code 写 README、接口文档、排障记录和产品说明的程序员来说，这是一套值得尝试的基础能力。