Codex 与线上知识库同步

目标

让 Codex、本地 Git、线上 Quartz 文档站保持同一套项目知识。

实际规则是：

• Codex 工作时读取本地 docs/，这是可编辑真源。
• GitHub private 仓库保存版本历史。
• 腾讯云 Quartz 站点展示已发布版本。
• 线上站点只用于阅读和验证，不直接在线改文档。

Codex 每次工作的固定流程

1. 先读本文件。
2. 再读本次任务对应的项目页，例如 docs/Codex项目/百度网盘自动转存飞书播报.md。
3. 修改代码或配置后，同步更新项目页、运行手册、接口说明或业务规则。
4. 项目完成或阶段完成时，在 docs/交接记录/ 新增交接文档。
5. 运行 ./scripts/docs-check.sh。
6. 提交 Git。
7. 推送 GitHub private 仓库。
8. 推送腾讯云 server 远端，触发 Quartz 自动构建。
9. 用线上 URL 验证页面已更新。

交接文档写什么

每个交接文档至少包含：

• 项目名称
• 本次目标
• 已完成内容
• 代码仓库和本地路径
• 运行方式
• 测试结果
• 部署或发布状态
• 风险和待办
• 不得写入的敏感信息说明

可以用脚本生成模板：

./scripts/new-handoff.sh "项目名"

生成后填写内容，再运行：

./scripts/docs-check.sh

发布命令

只发布文档站时：

./scripts/publish-docs.sh "更新项目交接文档"

脚本会执行文档检查、提交、推送 GitHub，并推送腾讯云 server 远端。

Codex 如何调用知识库

同一台电脑上的 Codex：

• 优先读取本地文件：/Users/ayang/Projects/product-mapping/docs
• 需要验证线上效果时访问：https://docs.gogo996.com

新设备或只有网页时：

• 先打开 https://docs.gogo996.com
• 搜索项目名
• 读取项目页和最近交接记录

如果线上站点启用访问口令，口令线下保存，不写入 Git、文档或脚本。

自动规则与 Skill

本机已配置两层自动化：

• 全局规则：/Users/ayang/.codex/AGENTS.md 中的 codex-knowledge-sync 段。
• 个人 skill：/Users/ayang/.codex/skills/codex-knowledge-sync/SKILL.md。

后续 Codex 项目任务应自动触发：

1. 开始前读取本文件。
2. 根据项目名读取 docs/Codex项目/ 下的相关项目页。
3. 完成项目或阶段时写入 docs/交接记录/。
4. 检查、提交并发布到 GitHub private 和 docs.gogo996.com。

限制：Codex 不能在没有权限或凭据的情况下静默推送服务器；如果 SSH、网络或 GitHub 权限不可用，必须在最终回复中明确说明缺少什么。

重要边界

• 不把 API Key、密码、Cookie、私钥、真实账号令牌写入文档。
• 不把 .env、数据库、日志、浏览器状态、构建缓存上传 Git。
• 线上文档只记录项目知识，不承载生产密钥。
• 代码和文档必须同版本提交，避免线上说明和实际代码不一致。