# 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. 项目本地持续分析文档 除了需要进入 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` 边界规则： - 可以在每个独立项目里持续写自己的分析文档 - 也允许每个独立项目优化“本项目私有层” - 但不建议每个项目独立发明一套公共核心方案 也就是： - 项目私有观察可以分散记录 - 公共核心方案仍应集中验证、集中沉淀、再回灌 --- ## 特别注意事项 ### 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，也仍然能稳。