709 lines
16 KiB
Markdown
709 lines
16 KiB
Markdown
# 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 身份边界。
|
||
|
||
### 5.1 仓库 ownership 也必须保持 `www:www`
|
||
|
||
除了 `git push` 只能使用 `www`，当前机器上还要额外遵守一条：
|
||
|
||
- `SEONexus` 仓库目录本身也必须保持 `www:www`
|
||
|
||
尤其不能让下面这些路径长期混入 `root:root`：
|
||
|
||
- `.git`
|
||
- `.git/index`
|
||
- `.git/objects/*`
|
||
- `docs/`
|
||
- 其它会被 `git pull` / `git checkout` 自动写入的目录
|
||
|
||
已经验证过的真实故障现象包括：
|
||
|
||
- `error: insufficient permission for adding an object to repository database .git/objects`
|
||
- `fatal: failed to write object`
|
||
- `fatal: unpack-objects failed`
|
||
- `error: unable to create file docs/...: Permission denied`
|
||
|
||
这类问题的根因不是远端仓库异常，而是：
|
||
|
||
- 前面曾用 `root` 对仓库做过 `commit`、写文件或目录创建
|
||
- 导致 `www` 后续执行 `pull` / `push` / `stash` 时权限链断掉
|
||
|
||
因此后续建议固定为：
|
||
|
||
- 与 Git 直接相关的操作优先都用 `www`
|
||
- `root` 只做日志排查、系统命令、权限修复
|
||
- 不要再用 `root` 在仓库里直接 `commit`、`pull`、`push`
|
||
|
||
如果已经出现 ownership 混乱，优先修复命令为：
|
||
|
||
```bash
|
||
chown -R www:www /www/wwwroot/diff-maccms/SEONexus
|
||
```
|
||
|
||
如果只是 `.git` 或仓库内同步文档目录出错，也至少要修：
|
||
|
||
```bash
|
||
chown -R www:www /www/wwwroot/diff-maccms/SEONexus/.git
|
||
chown -R www:www /www/wwwroot/diff-maccms/SEONexus/docs
|
||
```
|
||
|
||
这条规则和“只能 `www` 推送”应视为同一组约束，不能只做一半。
|
||
|
||
### 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-老模板第一阶段回灌执行文档](/www/wwwroot/diff-maccms/docs/1269-SEONexus-老模板第一阶段回灌执行文档.md)
|
||
|
||
适合记录：
|
||
|
||
- 旧模板回灌目标
|
||
- 分阶段策略
|
||
- 验收口径
|
||
|
||
### 2. Codex 交接总文档
|
||
|
||
也就是当前这份文档，适合记录：
|
||
|
||
- 协作规则
|
||
- 边界
|
||
- 交接模板
|
||
- 多版本协作方法
|
||
|
||
如果后续发现某条规则经常踩坑，就更新本文件，不要只留在聊天记录里。
|
||
|
||
### 3. 单次线上事件排障文档
|
||
|
||
这类文档适合记录：
|
||
|
||
- 某一次正式服报错的完整排查过程
|
||
- 问题阶段
|
||
- 根因
|
||
- 线上改动
|
||
- 验证结果
|
||
- 下一位 Codex 的接手建议
|
||
|
||
当前已沉淀样例：
|
||
|
||
- [2026-04-16-admin2-spider-workbench-production-fix.md](/www/wwwroot/diff-maccms/SEONexus/docs/2026-04-16-admin2-spider-workbench-production-fix.md)
|
||
|
||
使用原则：
|
||
|
||
- `1269` 这类文档负责阶段执行
|
||
- `1270` 这类文档负责长期协作规则
|
||
- `2026-xx-xx-...production-fix` 这类文档负责单次线上事件闭环
|
||
|
||
这样后续主 Codex 接手时：
|
||
|
||
- 先看长期规则
|
||
- 再看当前阶段执行文档
|
||
- 最后看最近一次线上事件文档
|
||
|
||
就不会只靠聊天记录反推上下文。
|
||
|
||
### 4. 项目本地持续分析文档
|
||
|
||
除了需要进入 Git 的正式文档外，每个项目还允许保留一套“只服务当前项目持续优化”的本地分析文档。
|
||
|
||
这类文档推荐放在项目自己的：
|
||
|
||
- `code/storage/_analysis/`
|
||
|
||
使用原因：
|
||
|
||
- 每个项目都有自己的蜘蛛日志来源、观察窗口和异常轨迹
|
||
- 这类分析如果完全不记录，后续优化容易断档
|
||
- 但如果全部提交进 Git，又会把大量过程性观察和未确认判断写进正式历史
|
||
|
||
因此这类文档的定位是：
|
||
|
||
- 允许持续记录
|
||
- 默认不提交
|
||
- 以项目私有观察为主
|
||
- 适合记录尚在观察期的中间结论
|
||
|
||
推荐最少按两层组织：
|
||
|
||
- `code/storage/_analysis/sources/`
|
||
- `code/storage/_analysis/domains/`
|
||
|
||
例如：
|
||
|
||
- `code/storage/_analysis/sources/baiduspider.md`
|
||
- `code/storage/_analysis/sources/sogou.md`
|
||
- `code/storage/_analysis/domains/sjzyunyang.com.md`
|
||
- `code/storage/_analysis/domains/jingxifa.com.md`
|
||
|
||
边界规则：
|
||
|
||
- 可以在每个独立项目里持续写自己的分析文档
|
||
- 也允许每个独立项目优化“本项目私有层”
|
||
- 但不建议每个项目独立发明一套公共核心方案
|
||
|
||
也就是：
|
||
|
||
- 项目私有观察可以分散记录
|
||
- 公共核心方案仍应集中验证、集中沉淀、再回灌
|
||
|
||
### 5. 本地分析必须回流主文档
|
||
|
||
`code/storage/_analysis/` 只负责本地持续观察，不应成为最终知识沉淀的终点。
|
||
|
||
只要本地分析满足以下任一条件，就必须再整理回主文档：
|
||
|
||
1. 已确认根因
|
||
2. 已验证修复有效
|
||
3. 结论能跨机器复用
|
||
4. 结论能跨模板族复用
|
||
5. 结论能减少其它 Codex 的重复劳动
|
||
6. 结论会影响协作边界或排查顺序
|
||
|
||
推荐回流判断方式：
|
||
|
||
- 如果只是某台机器、某个时间窗口的临时观察，可以先留在 `storage/_analysis/`
|
||
- 如果已经形成“别人以后不用再重新验证”的结论，就应升级到 `SEONexus/docs/`
|
||
|
||
推荐回流路径：
|
||
|
||
- 全局协作规则 -> `1270`
|
||
- 阶段执行 / 回灌策略 -> `1269`
|
||
- 单次正式服事件闭环 -> `2026-xx-xx-...production-fix.md`
|
||
- 其它模板族或专题结论 -> 对应专题正式文档
|
||
|
||
这条规则的目标是：
|
||
|
||
- 本地分析负责探索
|
||
- 主文档负责共享
|
||
- 不让每台机器都重复学习同一件事
|
||
|
||
---
|
||
|
||
## 特别注意事项
|
||
|
||
### 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，也仍然能稳。
|