From 71b986a4e0103852b96d0ca30f121ef21f7d2ebd Mon Sep 17 00:00:00 2001
From: root <root@v2202604268673447256.ultrasrv.de>
Date: Thu, 16 Apr 2026 14:52:08 +0800
Subject: [PATCH] docs add codex collaboration handoff guide

---
 ...1270-SEONexus-Codex多版本协作交接总文档.md | 484 ++++++++++++++++++
 1 file changed, 484 insertions(+)
 create mode 100644 doc/1270-SEONexus-Codex多版本协作交接总文档.md

diff --git a/doc/1270-SEONexus-Codex多版本协作交接总文档.md b/doc/1270-SEONexus-Codex多版本协作交接总文档.md
new file mode 100644
index 0000000..289fcf3
--- /dev/null
+++ b/doc/1270-SEONexus-Codex多版本协作交接总文档.md
@@ -0,0 +1,484 @@
+# 1270-SEONexus Codex 多版本协作交接总文档
+
+## 目的
+
+这份文档用于让多个 Codex 在 `SEONexus` 新版与旧版本之间长期协作时，保持：
+
+- 交接清楚
+- 边界清楚
+- 合并节奏清楚
+- 不互相覆盖
+- 不重复试错
+
+适用场景：
+
+- 你会在正式环境再安装一个或多个 Codex
+- 一个 Codex 主要盯新版优化
+- 另一个 Codex 主要盯旧版本蜘蛛抓取与优化
+- 后续还可能出现第 3 个、第 4 个 Codex
+
+---
+
+## 核心原则
+
+### 1. 同一时间只优化一份代码
+
+这是最重要的规则。
+
+任何时刻只允许：
+
+- 新版在优化
+或
+- 旧版本在优化
+
+不允许两个 Codex 同时分别改两份代码后再互相猜着合。
+
+正确节奏是：
+
+1. 先在一份代码上完成一轮优化
+2. 验证通过
+3. 合并/同步到另一份代码
+4. 再开始另一份代码的分析与优化
+
+---
+
+### 2. 另一份代码在未同步最新前，只做“观察”，不做“改动”
+
+如果旧版本还没合并新版最新修复，则旧版本 Codex：
+
+- 可以看日志
+- 可以写分析
+- 可以整理建议
+- 不能先改一套自己的实现
+
+否则后面很容易出现：
+
+- 同一问题两边各修一版
+- 路由/模板/观测逻辑走偏
+- 合并时冲突越来越重
+
+---
+
+### 3. 新版是主验证场，旧版本是回灌场
+
+除非明确说明某个问题只在旧版本存在，否则默认：
+
+- 新版先验证
+- 旧版本后回灌
+
+这条规则适用于：
+
+- 蜘蛛抓取分析
+- 路由兼容
+- 抓取入口修复
+- sitemap / rss / robots 修复
+- 前端站群 Nginx 动态回源策略
+
+不适用于：
+
+- 旧模板专属结构问题
+- 旧模板专属页面 bug
+- 旧模板专属样式/模板分支问题
+
+---
+
+## 版本边界
+
+### 新版负责什么
+
+新版主要承担：
+
+- SEO 主线优化
+- 蜘蛛抓取分析
+- 新路由兼容策略验证
+- 抓取入口修复
+- 深页 `301/404/500` 治理
+- RSS / sitemap / canonical 规范
+- 新功能验证
+
+### 旧版本负责什么
+
+旧版本主要承担：
+
+- 已验证能力的回灌
+- 老模板抓取稳定性修复
+- 老模板历史路由兼容
+- 老模板蜘蛛行为观察
+- 老模板入口层与规范层修复
+
+### 不要让旧版本先承担的内容
+
+这些优先在新版验证，不要先在旧版本自由发挥：
+
+- Bootstrap 总控台整条链
+- 站外 SEO 全量工作台
+- 大型后台运营工作流
+- 新模板展示层重构
+- URL 主输出风格大改
+
+---
+
+## 多 Codex 协作角色建议
+
+### Codex-A：新版主线 Codex
+
+职责：
+
+- 新版 SEO 优化
+- 蜘蛛日志分析
+- 路由兼容修复
+- 抓取入口修复
+- 新功能验证
+- 输出可回灌结论
+
+### Codex-B：旧版本回灌 Codex
+
+职责：
+
+- 等待旧版本合并最新版代码
+- 分析旧版本蜘蛛抓取
+- 验证回灌效果
+- 只做老模板特有问题修复
+- 不先发明与新版不同的实现
+
+### Codex-C / Codex-D：后续扩展 Codex
+
+职责建议：
+
+- 专项观察
+- 文档整理
+- 日志归纳
+- 回归验收
+
+不建议一上来让多个 Codex 同时改核心路由/模板。
+
+---
+
+## 每次开始工作前必须确认的事项
+
+任何一个 Codex 开工前，先确认以下 6 条：
+
+1. 当前自己负责的是：
+- 新版
+还是
+- 旧版本
+
+2. 另一份代码是否已经合并了最新修复
+
+3. 当前轮次是：
+- 观察
+- 修复
+- 回灌
+- 验收
+
+4. 这轮是否允许改代码
+
+5. 是否已有上一个 Codex 的交接结论
+
+6. 本轮修复目标是否只限定在一个主题
+
+例如：
+
+- 蜘蛛抓取概览
+- 深页兼容
+- RSS 修复
+- 旧模板入口规范
+
+不要一轮里又修蜘蛛、又修广告、又修 Bootstrap、又补后台工作台。
+
+---
+
+## 严格边界
+
+### 1. 不自动跨版本做“顺手修复”
+
+例如当前在旧版本分析蜘蛛问题时，不要顺手：
+
+- 改新版模板
+- 改新版站外 SEO 面板
+- 改新版 Bootstrap
+
+反过来也一样。
+
+### 2. 不自动提交
+
+除非用户明确要求，否则：
+
+- 不自动 commit
+- 不自动 push
+
+先把改动留在工作区，等用户确认。
+
+### 3. 不整包恢复历史提交
+
+像 `22cc72ee` 这种历史提交，只能作为：
+
+- 缺失源码来源
+
+不能整包恢复。
+
+因为这类提交往往还混着：
+
+- 运行产物
+- 测试数据
+- storage 输出
+- 临时样板文件
+
+正确做法是：
+
+- 定点恢复源码
+- 然后继续冒烟验证
+
+### 4. 不在两个版本上同时独立发明方案
+
+例如：
+
+- 新版把深页兼容做成 A
+- 旧版本同时自己做成 B
+
+这是最容易制造后续冲突的做法。
+
+### 5. Git 推送只能使用 `www` 用户
+
+这是当前机器的固定约束，不要忽略。
+
+原因：
+
+- `root` 用户可以排查问题、读日志、跑测试
+- 但 `root` 没有 `origin2` 的可用 SSH 私钥
+- `www` 用户已经配置好可用私钥，且已验证可正常推送到 `origin2`
+
+因此后续所有 Codex 都必须遵守：
+
+- 可以用 `root` 做分析、读取、验证
+- 一旦涉及 `git push`，只能切到 `www`
+- 不要再直接用 `root` 执行 `git push origin2 dev`
+
+标准推送命令：
+
+```bash
+su -s /bin/bash www -c 'git -C /www/wwwroot/diff-maccms/SEONexus push origin2 dev'
+```
+
+如果需要先查看状态，也建议保持同一口径：
+
+```bash
+su -s /bin/bash www -c 'git -C /www/wwwroot/diff-maccms/SEONexus status'
+su -s /bin/bash www -c 'git -C /www/wwwroot/diff-maccms/SEONexus log --oneline -n 3'
+```
+
+已验证结论：
+
+- `root` 推送会报 `Permission denied (publickey...)`
+- `www` 推送 `origin2` 正常成功
+
+所以这不是代码问题，也不是远端仓库问题，而是当前机器上的 Git 身份边界。
+
+---
+
+## 工作顺序标准流程
+
+### 场景 A：新版先优化，旧版本后回灌
+
+1. 新版 Codex 分析问题
+2. 新版 Codex 实施修复
+3. 新版验证通过
+4. 文档记录“哪些能力适合回灌旧版本”
+5. 旧版本合并最新代码
+6. 旧版本 Codex 开始观察与回灌验证
+7. 只补旧模板特有问题
+
+### 场景 B：旧版本先发现问题
+
+1. 先判断该问题是不是旧模板专属
+2. 如果不是旧模板专属，先回新版验证
+3. 新版验证后再回灌旧版本
+4. 如果是旧模板专属，再只在旧版本修
+
+---
+
+## 哪些优化适合回灌旧版本
+
+### 适合
+
+这些通常适合回灌：
+
+- 蜘蛛抓取日志分析
+- 抓取概览工作台
+- `robots.txt` 修复
+- `rss/baidu.xml` 修复
+- `sitemap` 修复
+- canonical 规范
+- 历史 `detail/play/category` 路由兼容
+- 深页 `404/301` 治理
+- 前端站群 Nginx 统一动态回源策略
+
+### 慎回灌
+
+这些要单独评估：
+
+- 坏链随机视频兜底
+- 播放页 SEO 策略大改
+- URL 主输出规则变更
+- 复杂站外 SEO 面板
+- 导入健康台全家桶
+- Bootstrap 总控台整条链
+
+---
+
+## 多 Codex 的交接模板
+
+每个 Codex 每轮结束时，至少留下以下内容：
+
+### 1. 本轮工作对象
+
+- 新版 / 旧版本
+- 目录路径
+- 当前分支
+
+### 2. 本轮目标
+
+例如：
+
+- 修复百度深页 `301 -> 404`
+- 验证旧模板蜘蛛抓取概览
+- 补回 rebase 丢失 helper
+
+### 3. 本轮已改动文件
+
+必须列路径。
+
+### 4. 本轮未提交改动
+
+说明是否：
+
+- 仅工作区修改
+- 已暂存
+- 已提交但未 push
+
+### 5. 本轮验证结果
+
+至少说明：
+
+- 哪些通过
+- 哪些没通过
+- 哪些未验证
+
+### 6. 下一位 Codex 的注意事项
+
+必须写明：
+
+- 不要碰哪些文件
+- 先看哪个文档
+- 下一个最值动作是什么
+
+---
+
+## 文档同步规则
+
+每轮有效优化后，至少同步两类文档中的一种：
+
+### 1. 主题执行文档
+
+例如：
+
+- [1269-SEONexus-老模板第一阶段回灌执行文档](/www/wwwroot/diff-maccms/docs/1269-SEONexus-老模板第一阶段回灌执行文档.md)
+
+适合记录：
+
+- 旧模板回灌目标
+- 分阶段策略
+- 验收口径
+
+### 2. Codex 交接总文档
+
+也就是当前这份文档，适合记录：
+
+- 协作规则
+- 边界
+- 交接模板
+- 多版本协作方法
+
+如果后续发现某条规则经常踩坑，就更新本文件，不要只留在聊天记录里。
+
+---
+
+## 特别注意事项
+
+### 1. 前端 Nginx 不要继续按 URL 模板枚举
+
+前端站群应坚持：
+
+- 静态资源缓存
+- 非静态请求 MISS 后统一回后端
+
+不要每新增一种 URL family，就去补前端 Nginx 前缀。
+
+### 2. 旧版本不要轻易改主输出 URL 风格
+
+旧版本更适合：
+
+- 加兼容层
+- 不推翻当前主输出
+
+### 3. 观测和修复要分开记录
+
+不要把：
+
+- 日志观察
+- 推测
+- 已验证修复
+
+写混。
+
+### 4. 真实缺失源码与 CLI 冒烟假阳性要区分
+
+像之前的：
+
+- `Class not found`
+- 路由没挂
+- helper 丢失
+
+这类是真缺失。
+
+但像：
+
+- `Undefined array key 9999`
+
+在 CLI 直接调控制器时，可能只是 admin 配置上下文不完整，不一定是真缺源码。
+
+---
+
+## 推荐的交接口径
+
+每个 Codex 对下一个 Codex 的交接，建议用这种结构：
+
+1. 当前负责版本
+2. 当前主题
+3. 已完成
+4. 未完成
+5. 禁止动作
+6. 下一步建议
+
+例如：
+
+1. 当前负责版本：旧版本
+2. 当前主题：蜘蛛抓取概览与深页兼容验证
+3. 已完成：日志分析、入口检查、深页 `404` 修复验证
+4. 未完成：下一轮百度深抓效果观察
+5. 禁止动作：不要先改新版，不要整包恢复历史提交，不要自动 commit
+6. 下一步建议：先合并最新版后，再观察旧模板的 `detail/play` 抓取变化
+
+---
+
+## 最后的工作纪律
+
+多个 Codex 长期协作时，最重要的不是“每个都很聪明”，而是：
+
+- 同步节奏一致
+- 边界清楚
+- 不抢改
+- 不乱回滚
+- 不各自发明一套实现
+
+只要坚持这几条，后面就算扩到 3 个、4 个 Codex，也仍然能稳。