write-doc-zh

name	write-doc-zh
description	写或修改 README、技术文档、接口文档、注释时使用。按中文技术文档规范写作：结构清晰、去翻译腔、术语规范、示例可运行。特别适合把英文文档转成地道的简体中文。

中文工程规范 · 技术写作（write-doc-zh）

当任务涉及写 README、Wiki、接口文档、变更说明、代码注释时，激活本技能。

写作目标

让读者3 秒知道是什么、30 秒知道怎么用、3 分钟能跑起来。中文要地道、准确、克制，像人写的，不像机翻的。

文档结构模板（README 用）

# 项目名

> 一句话定位：这是什么、解决什么问题（给外行的读者看）。

## 特性        （2-5 条，每条一行动词开头）
## 快速开始    （粘贴即用，先给最快的路径）
## 安装        （如果快速开始已含，此处省略）
## 使用示例    （真实场景，输出也要展示）
## 配置        （表格：参数/类型/默认值/说明）
## 工作原理    （可选，架构图 Mermaid）
## 贡献        （如何提 issue/PR）
## 许可证
## 致谢 / 相关项目

• 中文文档优先，术语可保留英文（Deploy、API、token）。
• 顶部放一张效果图/GIF 或 ASCII 演示，比 1000 字管用。

语言规范：去翻译腔

❌ 翻译腔	✅ 地道中文
对数据进行一个排序的操作	给数据排序
通过使用 X 的方式实现	用 X 实现
需要注意的是	注意
请确保你已经安装了 Node	请先装好 Node
我们可以这样做	可以这样做
这是一个用于…的工具	一个…的工具
被广泛地使用	使用广泛
实现以下功能	支持以下功能

准则

• 一句话只表达一个意思；能用逗号不用分号；删掉"的、了、进行、通过、从而"里能删的。
• 命令语气 > 建议语气 > 客气语气。文档少说"请"，多说"执行 npm i"。
• 数字用阿拉伯数字（3 秒、2 个），度量单位用标准写法（5 GB、300 ms）。
• 中英文之间加空格（使用 Node.js，不用 使用Node.js）。
• 专业术语首次出现可附英文（脚手架（scaffold））。

示例代码规范

• 示例必须可运行，跑不通的示例比没有示例更糟。
• 先给"最小可用"再给"完整版"。
• 输出结果一并展示，用注释标注：# 输出：hello zh-skills
• 涉及密钥/地址用占位符：your_api_key、http://localhost:3000。

接口文档规范

• 每个接口：请求方法 + 路径 → 请求参数表 → 响应示例 → 错误码表。
• 参数表列：参数 | 类型 | 必填 | 默认值 | 说明。
• 状态码用 HTTP 标准；业务错误码有独立文档。
• 写清楚谁在什么时候调用它（使用场景），不只写参数。

交接清单

• 标题能独立看懂（不含"项目""模块"等无信息量词）
• 开头有"一句话定位"
• 快速开始可以照着跑通
• 无翻译腔句式
• 中英文空格、数字规范
• 没有遗留 TODO / 占位图 / 假的截图链接