Appearance
用 Codex 更新文档并准备发布
文档任务最大的风险不是语句不够漂亮，而是命令、参数、路径、版本或业务行为与真实系统不一致。本章建立“代码事实 → 文档修改 → 渲染验证 → 发布检查”的闭环。
第一步：定义读者要完成的任务
差目标：“完善 README”。
可执行目标：
text
更新 README 的本地启动章节，让第一次克隆仓库的开发者能在 macOS 和 Linux 完成安装、配置、启动和健康检查。
必须使用仓库当前 package.json、环境变量示例和启动脚本。保留现有标题锚点和链接。不要写生产密钥，不要修改代码。说明读者、起点、完成结果和不能改的公开 URL。
第二步：让 Codex 先核对事实
text
先不要编辑。把目标文档中的命令、路径、环境变量、版本和 URL 与当前代码、配置、CI 和部署文件逐项核对。
输出表格：文档原文、代码证据、是否一致、建议修改。无法运行验证的内容单独标记。对于外部产品行为、版本、价格或参数，要求使用当前官方文档或发布说明。社区文章可以帮助发现主题，不能替代第一方事实。
第三步：按用户流程重写
实操文档优先顺序：
- 适用人群和完成结果；
- 前置条件；
- 可复制步骤；
- 每一步预期现象；
- 验证方法；
- 常见错误；
- 下一步和相关链接；
- 版本或核验日期。
不要先写长篇背景，再把关键命令藏在结尾。
第四步：保护精确内容
任务中明确：
text
以下内容必须保持精确，不做语言润色：
- 命令和参数；
- 文件路径和环境变量名；
- API 路由、Header 和配置字段；
- 错误文本；
- 已批准业务术语和品牌名称。Codex 可以改解释，但不能为了顺口改变可搜索的技术句柄。
第五步：运行文档验证
根据项目执行：
bash
npm run docs:build
git diff --check还要检查：
- 页面能否正常渲染；
- 内部链接、外部链接和锚点；
- 代码块语言和复制结果；
- 导航、侧边栏、搜索和 sitemap；
- canonical、Base 和静态资源路径；
- 移动端表格和长代码是否溢出；
- 新页面是否能从相关入口发现。
构建成功只说明语法和打包基本正常，不代表链接和内容事实正确。
第六步：做敏感信息检查
至少搜索：
sk-、token、password、cookie、authorization；- 真实邮箱、手机号、账号和内部域名；
.env、认证文件和本机绝对私有路径；- 用户数据、订单、日志和截图元信息。
使用明显占位符：
text
YOUR_API_KEY
https://api.example.com/v1
user@example.com不要使用看起来像真实凭证的随机长字符串。
第七步：写发布说明
发布说明回答用户关心的变化：
- 新增或修复了什么；
- 谁会受影响；
- 是否需要迁移或重新配置；
- 兼容性和已知限制；
- 怎样验证升级成功；
- 出现问题怎样回退。
不要把 Git 提交列表原样当发布说明。
第八步：发布动作与内容修改分开
文档准备完成不等于已经发布。发布前再次确认：
- 正确仓库、分支和远程；
- staged diff 范围；
- CI 和部署工作流；
- 域名、Base 和环境变量；
- 是否需要人工审批；
- 线上验证 URL。
只有用户明确要求时才提交、推送或部署。部署后还要检查线上页面、资源哈希和 Pages/平台状态，不能只看本地构建。
常见失败
文档比代码更“理想”
命令和行为必须来自当前实现。计划中的功能要明确标注，未验证内容不要写成已支持。
修改路径破坏搜索流量
已有公开 URL 优先保留；确需重命名时更新导航、内链、sitemap、llms.txt，并提供兼容或重定向。
只做语法检查
还要打开渲染页面、复制运行命令、检查移动端和线上地址。
把资料笔记直接发布
公开教程需要事实核验、示例验证、敏感信息清理和面向读者的重新组织。
完成报告模板
text
更新页面：[列表]
事实依据：[代码/运行结果/官方来源]
验证：[构建、链接、页面、命令]
敏感信息检查：[范围与结果]
未验证项：[列表]
发布状态：[未提交/已提交/已推送/已上线]下一步
你已经完成基础和项目工作流。下一阶段从 AGENTS.md 实战 开始，把这些规则固化到每次任务中。