--- name: tech-doc-style-chinese description: 在撰写、改写或审阅中文技术文档、文档首页、产品文案、界面文案、Markdown 文档或接口说明时使用。采用克制、准确、可扫读的中文技术写作风格：避免第二人称和宣传腔，统一使用直角引号，在可见正文中处理中文与英文或数字的留白，不改动代码字面量、JSON 键名、URL、API 路径等机器可读内容。如项目存在专属术语、版本展示或信息架构约定，再按需补充项目覆盖规则。 --- # NoCode Skill 这是一份可公开分享的中文技术文档与产品文案排版 Skill。 如果要在 Codex 中实际作为 Skill 使用，应将本文件命名为 `SKILL.md`，并放在技能目录根部。 如果项目存在专属术语、版本展示、品牌语气或信息架构约定，建议另建一份项目覆盖文件，例如 `references/Project-Overrides.md`，避免把项目私有约定混进通用规范。 # 中文技术文档与产品文案排版规范 在以下任务中使用这份 Skill： - 文档首页、落地页、首屏文案 - 接口文档、参数说明、常见问题、更新日志 - 产品能力介绍、解决方案页、能力说明页 - 界面文案、按钮文案、导航标签、提示信息 不要用这份 Skill 去改写代码字面量、JSON 键名、URL、API 路径、数据库字段名或其他机器可读标识符。 ## 目标 - 准确先于修辞 - 清晰先于热闹 - 导航感先于宣传感 - 可扫读先于堆砌解释 - 以信息架构和内容组织引导阅读，而不是依赖修辞或口号式表达 ## 语气 - 使用克制、直接、可执行的中文 - 以说明、界定、引导为主，不用夸张宣传语 - 避免「领先」「强大」「重磅」「颠覆」「震惊」「炸裂」「恭喜」等空泛形容 - 优先陈述「是什么、适用于什么、下一步看哪里」 - 不用第二人称 - 避免问候式开场、平台营销话术和口号式抽象表达 - 避免使用 `Hello`、`Hi` 这类问候式开场 ### 黑话短名单 默认避免以下高危黑话词，除非用户明确要求保留，或该词在当前语境中有严格业务定义： - `赋能` - `抓手` - `闭环` - `沉淀` - `对齐` - `对标` - `拉通` - `打通` - `协同` - `联动` - `洞察` - `赛道` - `心智` - `调性` - `战役` - `链路` - `势能` - `兜底` 以下中危词只有在语义明确时才使用： - `场景` - `生态` - `体系` - `路径` - `触点` - `卡点` - `布局` - `矩阵` - `颗粒度` - `复盘` - `梳理` - `输出` - `提炼` 优先替换为更具体的表达： - `赋能` -> `提供` - `抓手` -> `关键措施` - `闭环` -> `完整流程` - `沉淀` -> `形成` / `积累` - `对齐` -> `统一` - `拉通` / `打通` -> `连接` / `贯通` - `洞察` -> `分析结论` - `兜底` -> `保障机制` 仅在以下情况允许保留黑话原词： - 用户明确要求保留原词 - 正在引用原始材料、访谈、方案原文或外部文档 - 该词在特定行业语境里有固定含义，替换后会损失准确性 - 该词是产品名称、功能名称、方法论名称或组织内部正式术语 如果保留黑话原词，优先采用以下处理方式： - 首次出现时给出更具体解释 - 在同一句或下一句说明它实际指什么 - 避免连续堆叠多个黑话词 ## 强制规则 ### 1. 标点 - 中文引号统一使用直角引号：`「」` - 不使用中文双引号：`“”` - 正文中避免连续使用多个感叹号、省略号、宣传口号式断句 - 避免使用感叹号 ### 2. 称呼与受众 - 不使用：`你`、`您`、`同学` - 根据语境替换为：`开发者`、`技术负责人`、`实施人员`、`业务负责人`、`产品经理` - 如无必要，不直接点名读者，用无主句或说明句即可 ### 3. 中文与英文、数字之间的留白 在可见正文中，中文与可读的半角英文单词、英文缩写、独立数字和版本号之间保留空格，以提高可读性。 推荐写法： - `获取批量 ID` - `HTTP 请求` - `版本 2.0` - `AI 服务` - `与 PM 协作` - `读取系统日志` 以下内容不要机械加空格： - 行内代码和代码块 - JSON 键名 - URL - API 路径 - 数据库字段名 - 表头中直接镜像接口字段定义的标签 - 用户明确指定的拼写或大小写 示例： - `user_id` 保持原样 - `/api/example` 保持原样 - `statusCode` 保持原样 - 请求头字段名如 `Content-Type` 在代码里保持原样 说明： - 将中西文留白视为最终校对规则，而不是机械替换规则 - 不直接使用 `pangu.js` 批量处理 Markdown 文档 - 如遇字段名、协议名、路径或术语边界不清的情况，优先保持原样并人工判断 ### 4. 可见术语的大小写归一 仅对可见正文中的自然语言短语做归一： - `Id` / `id` / `ID` -> `ID` - `http` / `Http` / `HTTP` -> `HTTP` - `url` / `URL` / `Url` -> `URL` - `json` / `JSON` / `Json` -> `JSON` - `api` / `Api` / `API` -> `API` - `ai` / `Ai` / `AI` -> `AI` #### 术语大小写归一扩展清单（高频） 以下清单用于补充高频技术术语，写法统一为 `错写 -> 推荐`。仅作用于可见正文，不作用于代码、路径、字段和配置项字面量。 - `java` -> `Java` - `javascript` -> `JavaScript` - `typescript` -> `TypeScript` - `JS` / `Js` -> `JavaScript` - `llm` / `Llm` -> `LLM` - `aigc` / `Aigc` -> `AIGC` - `rag` / `Rag` -> `RAG` - `chatgpt` / `Chatgpt` -> `ChatGPT` - `openai api` / `OpenAI api` -> `OpenAI API` - `embeding` -> `embedding` - `finetune` / `fine tune` -> `fine-tuning`（如语义是训练过程，也可直接写 `微调`） - `python` -> `Python` - `golang` / `go`（指语言名） -> `Go` - `rust` -> `Rust` - `kotlin` -> `Kotlin` - `swift` -> `Swift` - `php` -> `PHP` - `ruby` -> `Ruby` - `scala` -> `Scala` - `dart` -> `Dart` - `sql` -> `SQL` - `bash` -> `Bash` - `powershell` -> `PowerShell` - `nodejs` / `node`（指运行时或平台名） -> `Node.js` - `dotnet` -> `.NET` - `reactjs` -> `React` - `vuejs` -> `Vue` - `nextjs` -> `Next.js` - `nuxtjs` -> `Nuxt` - `vitejs` -> `Vite` - `tailwind` -> `Tailwind CSS` - `nginx` -> `Nginx` - `redis` -> `Redis` - `postgres` / `postgresql` -> `PostgreSQL` - `mysql` -> `MySQL` - `mongodb` -> `MongoDB` - `elasticsearch` -> `Elasticsearch` - `kafka` -> `Kafka` - `rabbitmq` -> `RabbitMQ` - `github` -> `GitHub` - `gitlab` -> `GitLab` - `docker` -> `Docker` - `k8s`（正式文案） -> `Kubernetes` - `https` -> `HTTPS` - `grpc` -> `gRPC` - `graphql` -> `GraphQL` - `websocket` -> `WebSocket` - `yaml` -> `YAML` - `xml` -> `XML` - `jwt` -> `JWT` - `oauth` -> `OAuth 2.0` - `H5` -> `HTML5`（如语义是移动 Web 页面，优先直接写 `移动 Web 页面`） 适用示例： - `批量 id` -> `批量 ID` - `接口 url` -> `接口 URL` - `响应 json` -> `响应 JSON` - `启用 rag` -> `启用 RAG` - `接入 chatgpt` -> `接入 ChatGPT` - `调用 openai api` -> `调用 OpenAI API` 以下内容不要改写： - 机器可读标识符 - 字段化标签，如 `user_id` - 直接镜像接口定义的表头 - 用户明确指定的大小写 ### 5. 行动按钮文案 - 按钮文案应体现下一步动作，避免与标题重复 - 优先使用「动作 + 结果」或「动作 + 目标」 示例： - `从这里开始` - `核对调用规则` - `初步了解` 避免： - `阅读平台介绍` - `查看认证规则` 当标题已经表达同一信息时，不要在行动按钮文案里重复。 ## 常见内容类型模板 以下模板是通用写法参考，不是强制结构。项目如有专属信息架构，应由项目覆盖规则单独约定。 ### 入口页或总览页 首段通常回答三件事： - 覆盖什么 - 适合谁使用 - 从哪里开始读 段落保持紧凑，不要叠加口号式表达。 ### 介绍页 第一段通常说明： - 这页给谁看 - 这页解决什么问题 - 建议接着读哪里 ### 解决方案页 按业务用途组织，而不是按接口清单平铺。 可参考的顺序： 1. 适用场景 2. 典型问题 3. 推荐方案 4. 推荐调用顺序 5. 实施建议 6. 能力边界 ### 接口说明页 - 请求方法行放进代码块，不要裸露在正文里 - 参数说明尽量一列一义，不写含混描述 - 错误码文案要统一口径 - 不要机械直译常见英文状态词和错误词 常见误译词表： - `Success` - 不默认写成 `成功` - 按语义选择：`已完成`、`已处理`、`请求已受理` - `Invalid` - 不翻译成 `非法` - 按语义选择：`无效`、`格式无效`、`有误`、`校验未通过` - `Available` - 不机械翻译成 `可用` - 按语义选择：`已开通`、`可获取`、`可访问`、`可使用` - `Unsupported` - 优先翻译为：`暂不支持`、`不支持该类型`、`当前不支持` - `Pending` - 优先翻译为：`待处理`、`处理中`、`待确认` - `Expired` - 优先翻译为：`已过期` - `Missing` - 优先翻译为：`缺少`、`未提供` - `Denied` - 优先翻译为：`被拒绝`、`不予通过` - `Forbidden` - 不直接翻译成 `禁止` - 按语义选择：`无权限访问`、`当前不允许访问` - `Not Found` - 优先翻译为：`未找到对应内容`、`未找到对应数据` - `Accepted` - 不机械翻译成 `已接受` - 按语义选择：`已受理`、`已接收，等待处理` - `Completed` - 优先翻译为：`已完成` - `Failed` - 优先翻译为：`失败` - 如上下文更偏流程处理，可用：`处理失败` - `Conflict` - 不机械翻译成 `冲突` - 按语义选择：`状态冲突`、`资源状态不一致`、`请求与当前状态冲突` - `Unauthorized` - 不翻译成 `未授权` - 优先翻译为：`未登录`、`认证未通过`、`缺少认证信息` - `Bad Request` - 不机械翻译成 `错误请求` - 优先翻译为：`请求参数有误`、`请求格式有误` - `Timeout` - 优先翻译为：`超时` - 如需更完整，可写为：`请求超时`、`处理超时` ### 常见问题与排查页 - 先给判断路径，再给例外 - 优先说明「先查什么」，而不是只罗列概念 - 错误排查文本要偏操作性，不要写成泛泛说明 ## 排版与结构规则 - 一个段落只承载一个主要信息点 - 长句可以保留，但避免连续堆叠两个以上长句 - 列表项要平行，不要有的写定义、有的写宣传、有的写结论 - 标题要能反映用途，不要只写抽象名词 当同一标题下出现 4 个及以上并列项时： - 统一命名结构 - 统一句式 - 统一信息密度 ## 界面文案规则 - 按钮文案短，不解释背景 - 卡片描述补信息，不重复标题 - 导航标题偏名词 - 行动文案偏动作 ## 移动端可读性规则 - 三列表参数表在移动端不应靠缩字硬挤 - 常见 `参数 / 是否必填 / 说明` 表优先改卡片式行布局 - 真正宽表再使用横向滚动 ## 编辑流程 1. 先判断内容类型。 例如：入口页、介绍页、解决方案页、接口说明页、常见问题、界面文案。 2. 先去重复。 如果标题、正文和行动按钮文案在表达同一件事，优先重写行动按钮文案。 3. 应用强制规则。 统一标点、称呼、留白和常见误译词。 4. 再收句子。 只保留准确阅读和下一步导航所必需的信息。 5. 最后通读。 检查语气、术语、留白、标题和扫读节奏。 ## 中文易错表达清单 用于排查词义错位、数量逻辑错误和表达歧义。优先写成「具体、可验证、不歧义」的表达。 - `出生于技术团队` -> `出身于技术团队`（`出生` 仅用于生理出生） - `阀值` -> `阈值` - `请先登陆系统` -> `请先登录系统`（`登陆` 多用于登岸） - `截止 4 月 12 日` -> `截至 2026 年 4 月 12 日`（时间范围优先用 `截至`，并给完整日期） - `布署到生产环境` -> `部署到生产环境` - `配制服务器参数` -> `配置服务器参数` - `起用该功能` -> `启用该功能` - `反回结果` -> `返回结果` - `回朔历史版本` -> `回溯历史版本` - `标示字段` -> `标识字段`（指 ID、标签、标记物时） - `帐户余额` -> `账户余额`（金融语境） - `帐号登录` -> `账号登录`（平台用户语境，建议统一） - `搜寻日志` -> `搜索日志` - `即时通信` -> `实时通信`（系统能力描述语境） - `做为默认配置` -> `作为默认配置` - `系统发布到生产环境` -> `部署到生产环境` / `发布新版本`（区分 `部署` 与 `发布`） - `完成授权`（语义为身份校验） -> `完成认证`（认证 = 确认身份，授权 = 授予权限） - `缩小了 3 倍` -> `缩小到原来的 1/3` / `减少了 2/3` - `增长到 30%`（原来 20%） -> `从 20% 提高到 30%` / `相对增长 50%` - `转化率提升了 5%`（20% -> 25%） -> `提升了 5 个百分点` / `相对提升 25%` - `翻了 1 倍` -> `变为原来的 2 倍` - `不超过 100 以上` -> `不超过 100` - `预计大约在 3 点左右` -> `预计 3 点` / `预计 3 点左右` - `是否可以 A 或者 B` -> `可以 A 或者 B` / `是否可以 A` - `尽快处理` -> `30 分钟内处理`（将模糊词改为明确时限） - `使用提示工程学优化输出` -> `使用提示工程优化输出` - `模型出现幻听` -> `模型出现幻觉` ## 最终检查清单 交付前检查： - 是否出现 `你`、`您`、`同学` - 是否出现中文双引号 `“”` - 中文与英文、数字之间是否需要留白 - 文案是否重复标题 - 行动按钮文案是否与标题重复 - 是否存在过强的宣传口吻 - 文案是否便于扫读 ## 改写示例 ### 示例 1 改写前： `阅读平台介绍` 改写后： `从这里开始` ### 示例 2 改写前： `本页适合第一次进入文档中心的业务负责人、产品经理、技术负责人和实施同学。` 改写后： `本页适合首次访问文档中心的业务负责人、产品经理、技术负责人和实施人员。` ### 示例 3 改写前： `获取数据批量ID` 改写后： `获取数据批量 ID` ### 示例 4 改写前： `集中说明请求头、签名算法、时间戳与错误码，适合发起请求前逐项核对。` 改写后： `集中说明通用技术约定，适合发起请求前快速逐项核对。`