SEONexus/doc/1270-SEONexus-Codex多版本协作交接总文档.md

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

标准推送命令：

su -s /bin/bash www -c 'git -C /www/wwwroot/diff-maccms/SEONexus push origin2 dev'

如果需要先查看状态，也建议保持同一口径：

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 身份边界。

6. SEONexus 与 SEONexusAdmin 是同机双仓协作

当前机器上：

• SEONexus
• SEONexusAdmin

都位于同一台机器的 /www/wwwroot/ 下。

这意味着：

• 它们适合联合排查
• 但仍然是两个独立仓库
• 不能因为同机就默认一起改

推荐理解方式：

• SEONexus 主要负责后端接口、路由、helper、model、日志、返回结构
• SEONexusAdmin 主要负责前端页面、接口调用、参数、token/header、错误展示
• Nginx / 域名 / 反代 / CORS / 登录态链路属于同机环境层

因此遇到后台报错时：

• 可以跨仓一起查
• 但修复时先判断主战场
• 一轮优先只改一个主仓

例如：

• 如果是接口 500、类缺失、helper 丢失、路由没挂，主战场通常是 SEONexus
• 如果是 axios 参数、header、token、前端展示层误报，主战场通常是 SEONexusAdmin
• 如果是跨域、代理、cookie、header 丢失，主战场通常是 Nginx / 反代配置

这条规则的核心不是“分开”，而是：

• 同机便于联查
• 分仓便于控边界

7. 不建议现在把所有项目硬并成一个 Git 仓库

当前更适合的结构是：

• 多个独立 Git 仓库
• 通过仓库内 doc/ 文档同步协作规则
• 通过明确边界控制多 Codex 并行协作

不建议现在把所有项目直接并成一个大仓，原因包括：

• SEONexus、SEONexusAdmin、node 工具链、蜘蛛代理脚本、历史参考目录，生命周期并不一致
• 不同项目的提交节奏不同，强行并仓后日志会很乱
• 后续回滚、比对、定向发布会更重
• 正式服未必需要开发机当前的总目录结构
• 现在真正需要同步的是规则和关键文档，不是把所有杂项目录绑成一个提交历史

当前阶段更推荐：

• 业务主仓继续独立维护
• 关键协作文档同步到主仓的 doc/
• 需要跨仓排查时，通过文档说明目录关系和排查顺序

只有在未来满足以下条件时，才考虑是否要做 monorepo：

• 多个仓长期高度耦合
• 发布必须严格同版本号
• CI/CD 也准备统一
• 权限、分支策略、回滚策略都已经设计清楚

在当前阶段，最稳的结论是：

• 不要把所有项目硬归成一个 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-老模板第一阶段回灌执行文档

适合记录：

• 旧模板回灌目标
• 分阶段策略
• 验收口径

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，也仍然能稳。