Fenng 写了一份中文技术文档写作规范,内置 lint 脚本和 CI

项目卡片

• 项目：Tech-Doc-Style-Chinese^[1]
• 状态：v0.2.0 / 347 Stars / 2026 年 4 月发布，持续迭代
• 一句话判断：不只是一份文档规范，而是一套「规范 + 校验 + CI」三位一体的中文技术写作工具链

中文技术文档的写作规范，大部分团队靠约定和肉眼纠错。同样的错误反复出现，文档风格参差不齐。

Fenng（丁香园创始人）最近开源了一个项目 Tech-Doc-Style-Chinese。我翻完整个仓库后发现，它不只是贴了一份规范文档——还配套了 lint 脚本和 CI，试图把文档风格管理变成工程流程。

这个项目最核心的身份是一份 Codex Skill。SKILL.md 文件带完整的 frontmatter，可以被 Codex 代理直接加载使用。

安装方式也很简单：

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

安装后，在 Codex 里可以直接调用：

Use $tech-doc-style-chinese to rewrite this Chinese technical copy.

它覆盖的文档类型很实际：接口文档、参数说明、错误码、更新日志、落地页文案、界面文案、按钮文案。不碰代码字面量、JSON 键名、URL 这些机器可读内容。

有明确边界，有适用场景。不是泛泛的写作指南，是可执行的技术写作工具。

这份规范解决的是中文技术文档里几个高频痛点。

标点与称呼——中文引号统一用直角引号「」，不使用弯引号「""」；禁止出现「你」「您」「同学」这类称呼，替换为具体角色名。

中西文留白——中文与英文、数字之间加空格提高可读性，比如「获取批量 ID」而非「获取批量ID」。但它明确不碰代码块、URL、API 路径这些场景，避免机械替换。

术语大小写归一——id → ID、http → HTTP、json → JSON，附带了一份超过 50 条的扩展清单，覆盖编程语言、中间件、协议名称，甚至 AI 术语。

黑话分级治理——这是我觉得最实用的部分。高危词如「赋能」「抓手」「闭环」「沉淀」「对齐」默认禁用；中危词如「场景」「生态」「体系」允许在语义明确时使用。每条都有替换建议，比如「赋能」→「提供」、「闭环」→「完整流程」、「洞察」→「分析结论」。而且不是一刀切——用户明确要求保留、引用原文、或该词有固定业务含义时，允许保留原词。

误译词表——针对 API 文档中常见的机械直译问题。比如 Success 不应该一律翻成「成功」，而是按语义选择「已完成」「已处理」「请求已受理」；Invalid 不翻译成「非法」，而是「无效」「校验未通过」。

中文易错表达——比如「阀值」→「阈值」、「登陆」→「登录」、「缩小了 3 倍」→「缩小到原来的 1/3」。

光贴规范文档不够。项目还提供了一个零依赖的 Python 校验脚本 lint_copy_rules.py，328 行代码，解决的是「规范写了但没人遵守」的问题。

它能自动检测六类问题：

• 禁用引号（ASCII 双引号和中文弯引号）
• 禁用称呼（你、您、同学）
• 术语大小写（ID、HTTP、URL 等）
• 指定缩写（JS → JavaScript、H5 → HTML5）
• AI 术语误写（llm → LLM、embeding → embedding）
• 中文错词（阀值、登陆、布署等）

执行方式：

python scripts/lint_copy_rules.py SKILL.md NoCode-Skill.md references/

脚本做了不少细节处理：跳过 fenced code block 和行内代码、跳过 URL 和 API 路径、支持 YAML front matter 跳过。不是粗暴的全文本匹配。

CI 也配好了。.github/workflows/skill-lint.yml 在 PR 和 main 分支 push 时自动运行。文档风格守护完全自动化。

通用规范不可能适配所有项目，核心 Skill 只放通用规则，项目私有约定通过 references/Project-Overrides.md 单独管理——版本展示约定、品牌术语、文档结构偏好等。规范可复用，项目可扩展，两者不互相污染。

这个项目的受众很明确：

• 在写中文技术文档的技术团队，尤其是 API 文档较多的 SaaS / 云服务团队
• 使用 Codex 做文案改写的开发者，可以直接作为 Skill 集成到工作流
• 对文档一致性有要求的团队，lint 脚本 + CI 可以做自动化的风格守护

不太适合的场景：纯英文文档项目、对文案风格没有一致要求的个人项目。

如果这篇对你有用，建议点个关注。我会持续把 GitHub 上值得用的 AI 工具拆成「最短上手闭环 + 坑点清单 + 可复用配置」，让你少走弯路。

引用链接