编写或审校中文技术文档/产品文案时，统一排版、术语…

适用于重写、优化或 lint 中文技术文案、API 文档、FAQ、更新日志、落地页与 UI 文案。

适用场景

解决思路

1. 安装：交互安装运行 `npx skills add https://github.com/Fenng/tech-doc-style-chinese`；非交互全局安装到 Codex 运行 `npx -y skills add https://github.com/Fenng/tech-doc-style-chinese -a codex -g`。
2. 固定指定发布版本安装：执行 `CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"`，`mkdir -p "$CODEX_HOME/skills"`，再执行 `git clone --depth 1 --branch v0.1.0.2.4 https://github.com/Fenng/tech-doc-style-chinese.git "$CODEX_HOME/skills/tech-doc-style-chinese"`。
3. 本地/开发安装：执行 `CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"`，`mkdir -p "$CODEX_HOME/skills/tech-doc-style-chinese"`，`cp -R ./* "$CODEX_HOME/skills/tech-doc-style-chinese/"`，最后用 `test -f "$CODEX_HOME/skills/tech-doc-style-chinese/SKILL.md" && echo "installed"` 验证。
4. 运行 lint 脚本：执行 `python scripts/lint_copy_rules.py` 检查全部；检查指定文件或目录执行 `python scripts/lint_copy_rules.py SKILL.md NoCode-Skill.md references/`。
5. CI 配置：在 `pull_request` 和推送到 `main` 时通过 `.github/workflows/skill-lint.yml` 自动运行。
6. 仓库结构要点：维护 `SKILL.md` 作为 Codex 技能入口，`NoCode-Skill.md` 作为人读规范，`README.md`，`agents/openai.yaml` 技能元数据，`references/Project-Overrides.md` 项目定制示例。
7. 排版与空格：在可见正文中，中文与英文/数字之间加空格，例如「支持 JSON 格式和 XML 格式」「版本号为 1.2.3，发布于 2024 年」。
8. 空格例外：不要对代码字面量、JSON 键、URL、API 路径、数据库字段名或任何机器可读标识符应用空格规则。
9. 引号：可见中文正文使用角括号「」；不要使用弯引号。
10. 避免直接称呼：不要用 你/您/同学；改写为无直接称呼，例如「通过以下步骤完成配置。」「欢迎使用本产品。」
11. 状态词翻译：不要机械翻译英文 HTTP/API 状态词；使用：Success→请求已完成/操作成功，Invalid→参数格式不正确，Bad Request→请求参数有误，Forbidden→无访问权限，Not Found→资源不存在。
12. 禁用黑话：可见正文中 linter 标记以下词为错误：赋能、抓手、闭环、打通、沉淀、链路、颗粒度、生态、矩阵、倒逼、落地、变现、复盘、对齐、拉齐。
13. 常见中文错别字：linter 捕捉并改为：阀值→阈值、登陆→登录、布署→部署、配制→配置、起用→启用、反回→返回、回朔→回溯、标示→标识、帐户→账户、帐号→账号、截止→截至。
14. 术语大小写：linter 强制：id→ID、http→HTTP、url→URL、json→JSON、api→API、ai→AI、JS/Js→JavaScript、H5→HTML5、llm→LLM、aigc→AIGC、rag→RAG。
15. 落地页/首屏：开头先说明产品做什么，不写「赋能」；在首屏放具体数字（延迟、限制、定价）；每屏一个主要 CTA；按钮文案必须命名下一步动作。示例：支持 REST 和 GraphQL 接口，5 分钟完成接入，每月免费额度 100 万次调用。
16. API 与参数文档：用表格列出参数名、类型、必填、说明；明确类型、是否必填、默认值、约束；必填用 是/否，不用 required/optional；错误码必须说明原因和恢复动作。
17. 错误码文档：用表格列出错误码、说明、处理建议；每条说明原因并给处理建议，例如 40001 缺少必填参数 `user_id`→检查请求体是否包含 `user_id` 字段；40301 无权限→联系管理员确认角色权限配置；50001 服务端超时→稍后重试，持续出现提交工单。
18. FAQ 页面：不要重复问题；直接回答。例如问「如何重置密码？」答「进入「账号设置」→「安全」→「修改密码」，输入手机验证码后设置新密码。」
19. 更新日志：使用「## v2.3.0 — 2024-03-15」式标题；分「新增」「修复」「变更」；写具体功能和修复，例如支持 API 批量导入用户、修复 Safari 16 登录页闪烁、`GET /v1/users` 返回结构新增 `created_at` 字段。
20. 按钮与 UI 文案：不要用抽象且与周边标题重复的文案（立即体验、了解更多、点击查看）；改为命名下一步动作（开始免费试用、查看接口文档、下载 SDK）。
21. 项目级覆盖：核心技能保持通用；项目特定约定写进 `references/Project-Overrides.md`，例如版本号格式统一为 `vMAJOR.MINOR.PATCH` 且不加「版本」二字；术语表中「工作流」指 Workflow 功能模块且不用「流程」、「智能体」指 Agent 且不用「代理」；文档结构偏好中每个功能页必须包含「适用场景」和「限制说明」两节；调用时同时使用 `$tech-doc-style-chinese` 和 `references/Project-Overrides.md`。
22. 调用技能：安装后在任务中显式引用，例如使用 `$tech-doc-style-chinese` 重写这段中文技术文案、清理这个 API 错误码表、优化这个落地页文案、审查 FAQ 部分的风格违规。
23. 排查代码块误报：lint 只针对可见正文；把代码样例包进 fenced blocks（```）后，linter 会跳过代码块内容。
24. 排查 URL/JSON 键被空格规则标记：这些明确不在范围内；若被标记，通常不在代码块内，将其移入代码块。
25. 排查技能安装后未加载：重启 Codex；用 `test -f "$CODEX_HOME/skills/tech-doc-style-chinese/SKILL.md" && echo "OK"` 验证。
26. 排查团队 lint 结果不一致：固定 release tag，例如 `git clone --depth 1 --branch v0.1.0.2.4 https://github.com/Fenng/tech-doc-style-chinese.git "$CODEX_HOME/skills/tech-doc-style-chinese"`。

适用边界 · 注意事项

• 不适用于非中文技术文案，或需要营销夸张、黑话和模糊宣传语的品牌/广告文案。
• 不应对代码字面量、JSON 键、URL、API 路径、数据库字段名或机器可读标识符应用空格和标点规则。
• 如果团队已有强制中文规范，应通过 `references/Project-Overrides.md` 覆盖，而不要直接改核心技能规则。