docs sync collaboration guides into repository docs

2026-04-16 15:20:36 +08:00
parent 71b986a4e0
commit 327c5f506c
4 changed files with 1198 additions and 0 deletions
--- a/doc/1270-SEONexus-Codex多版本协作交接总文档.md
+++ b/doc/1270-SEONexus-Codex多版本协作交接总文档.md
@@ -274,6 +274,79 @@ su -s /bin/bash www -c 'git -C /www/wwwroot/diff-maccms/SEONexus log --oneline -
 所以这不是代码问题，也不是远端仓库问题，而是当前机器上的 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/docs/1269-SEONexus-老模板第一阶段回灌执行文档.md
+++ b/docs/1269-SEONexus-老模板第一阶段回灌执行文档.md
@@ -0,0 +1,562 @@
 # 1269-SEONexus 老模板第一阶段回灌执行文档
 ## 关联文档
 - 协作与交接总规则：
  [1270-SEONexus-Codex多版本协作交接总文档](/www/wwwroot/diff-maccms/docs/1270-SEONexus-Codex多版本协作交接总文档.md)
 ## 目标
 这份文档只覆盖老模板的第一阶段回灌，原则是：
 - 不改老模板大骨架
 - 不依赖后台逐站编辑
 - 先统一抓取入口、观测链、规范输出
 - 先看蜘蛛访问和抓取变化
 适用前提：
 - 老模板共 5 套
 - 域名会随机绑定其中一套模板
 - 当前不准备把 `videoGpt1` 的整套结构层直接迁过去
 ---
 ## 为什么第一阶段要“直接改代码”
 当前站点运行时链路是：
 1. `DomainModel.t_id`
   决定域名使用哪套视图模板
 2. `SiteContext`
   根据 `t_id` 读取模板路径
 3. 模板本身再结合站点自己的 `t_cfg / d_seo_cfg` 输出页面
 这意味着：
 - 同一套老模板代码，被多个域名共用
 - 第一阶段如果只是统一抓取入口、sitemap、canonical、观测能力
 - 最稳的方式就是直接改这套老模板代码本身
 不建议第一阶段依赖后台逐站编辑，因为后台编辑会触碰：
 - `t_id`
 - `t_cfg`
 - `d_seo_cfg`
 这些字段都可能改变老模板站点当前行为。
 ---
 ## 第一阶段要做什么
 只做以下 4 层：
 1. 抓取入口层
 2. 输出规范层
 3. 观测层
 4. 静态资源发布层
 明确先不做：
 - 首页结构重排
 - 列表卡片重构
 - 评论区整体换骨架
 - 深页整体布局替换
 - 逐站后台批量套 SEO 策略包
 ---
 ## 第一步：选 1 套老模板做试点
 不要 5 套一起动。
 优先选择这类模板：
 - 结构相对规整
 - 已有基础抓取，但还没形成明显深抓
 - 线上有一定流量，但不是最核心起量模板
 - `robots / sitemap / canonical / footer` 这些基础层容易统一
 暂时不要选：
 - 起量最高的模板
 - 历史补丁最多的模板
 - 路径规则最杂的模板
 ---
 ## 第二步：先统一抓取入口层
 ### 2.1 统一 `robots.txt`
 要求：
 - 老模板必须稳定输出 `robots.txt`
 - `robots.txt` 里必须声明百度 sitemap
 - 百度不能被引到无效入口
 建议统一成：
 - `Sitemap: https://当前域名/rss/baidu.xml`
 检查项：
 - `robots.txt` 是否返回 `200`
 - 内容里是否已有 `Sitemap:` 声明
 - 是否仍然指向旧的死入口
 ### 2.2 统一 `rss/baidu.xml`
 要求：
 - 老模板必须稳定输出百度可用的 XML
 - 优先输出详情页入口
 - 链接协议统一 `https://`
 检查项：
 - `rss/baidu.xml` 是否返回 `200`
 - 是否有真实 `<item><link>...` 内容
 - 链接是否已经是最终规范地址
 ### 2.3 给 `sitemap_index.xml` 做兜底
 老模板如果历史上已有：
 - `/sitemap_index.xml`
 不要直接让它继续 `404`。
 建议：
 - 如果旧入口仍有历史外链或蜘蛛命中
 - 让它兜底回落到当前实际可用的 sitemap 输出
 目的：
 - 减少历史路径继续浪费抓取机会
 ---
 ## 第三步：统一输出规范层
 ### 3.1 统一 canonical
 检查项：
 - 首页 canonical
 - 分类页 canonical
 - 详情页 canonical
 - 播放页 canonical
 目标：
 - 都指向最终规范地址
 - 尽量统一 `https://`
 ### 3.2 统一主要链接协议
 重点看：
 - sitemap 输出
 - 页面 head 里的 canonical / og:url
 - 页面内主要入口链接
 目标：
 - 减少 `http -> https` 跳转消耗
 - 让百度尽量直接拿到最终 URL
 ### 3.3 统一 footer / sitemap 暴露入口
 检查项：
 - footer 里是否有百度 sitemap 或 XML 地图入口
 - 是否还暴露旧死入口
 目标：
 - 对外暴露路径统一
 - 不再继续给蜘蛛错误入口
 ---
 ## 第四步：接入观测层
 这一步和模板结构解耦，但必须同步做。
 要求：
 - 前端站群 Nginx 已输出蜘蛛日志
 - `spiderlog-agent` 已在前端机定时推送
 - 后台蜘蛛抓取概览能观察到该模板站点的百度行为
 重点只看：
 - `baiduspider`
 - `home`
 - `robots`
 - `sitemap`
 - `category`
 - `detail`
 - `play`
 第一阶段的观测目标不是“马上深抓”，而是先确认：
 1. 百度是否稳定进入首页
 2. 是否开始命中 `robots`
 3. 是否开始命中 `sitemap`
 4. 是否开始出现 `category`
 ---
 ## 第五步：统一静态资源发布层
 老模板第一阶段也建议统一吃当前这套：
 - 自动重编
 - `STATIC_FILE_VERSION` 强制刷新兜底
 使用原则：
 - 平时样式/脚本变更依赖自动重编
 - 只有前端站群 / CDN / 浏览器仍命中旧静态文件时，再手动提高 `STATIC_FILE_VERSION`
 ---
 ## 阶段观察记录
 ### 2026-04-15 蜘蛛抓取观察结论
 本轮重点观察的是：
 - 深页兼容修复
 - 前端站群统一动态回源
 - `rss/baidu.xml` 深链恢复
 观察口径：
 - 只看 `baiduspider`
 - 重点只看：
  - `home`
  - `category`
  - `detail`
  - `play`
 #### 结论
 当前可以确认：
 1. 修复方向是对的
 2. 已出现真实成功样本
 3. 但还没有扩大成全站稳定放量
 也就是：
 - 不是“修了没效果”
 - 而是“已经开始出现正反馈，但还在观察窗口”
 #### 关键成功样本
 ### 2026-04-16 深页残余 500 修复结论
 本轮新增确认的不是入口层问题，而是深页随机兜底分支里的实现问题。
 #### 新发现的问题
 以下残余深页在外网直测时会返回 `500`：
 - `jingxifa.com /video-detail/mo-ri-yi-jia-qin-172009`
 - `sjzyunyang.com /video-detail/a-te-yu-pei-pei-185677`
 错误页正文一致，核心报错为：
 - `the match filter must be an expression in an object`
 #### 根因
 问题位于：
 - [VideoService.php](/www/wwwroot/diff-maccms/SEONexus/code/app/services/VideoService.php)
 当原始 `v_id` 查不到真实视频时，系统会进入随机兜底逻辑：
 1. 先尝试读取随机绑定
 2. 未命中时走 Mongo `aggregate + sample`
 3. 旧实现会在无筛选条件时传入：
   - `['$match' => []]`
 4. 该写法会触发 Mongo 聚合报错，从而把原来的 `301 -> 404` 残余坏链升级成：
   - `301 -> 500`
 #### 已做修复
 当前已调整为：
 - 只有在存在筛选条件时才注入 `$match`
 - 无筛选条件时直接走 `$sample`
 也就是：
 - 不再把空数组作为 `$match` 表达式传给 Mongo
 #### 修复后回测结果
 以下链接已重新回测为 `200`：
 - `https://jingxifa.com/video-detail/mo-ri-yi-jia-qin-172009`
 - `https://sjzyunyang.com/video-detail/a-te-yu-pei-pei-185677`
 - `https://www.lgyz.net/voddetail/mo-shi-chao-neng-li-zhe-dong-tai-man-hua-69869`
 - `https://www.lgyz.net/vodplay/bi-she-tang-yuan-bi-yi-zheng-fu-jin-di-yi-ji-53027-youzhi-8`
 - `https://www.lgyz.net/voddetail/69869`
 - `https://www.lgyz.net/vodplay/53027-youzhi-8`
 并且本地兜底探针日志已出现真实命中：
 - `requested_v_id = 172009 -> candidate_v_id = 119106`
 - `requested_v_id = 185677 -> candidate_v_id = 50302`
 这说明：
 - 随机兜底逻辑已经真正执行成功
 - 不再停在 Mongo 异常层
 - 深页残余坏链继续从 `500` 向 `200` 收敛
 #### 当前阶段判断
 截至 `2026-04-16` 当前窗口，可以把这轮优化效果概括为：
 1. 深页兼容入口已生效
 2. 多站点已出现 `301 -> 200`
 3. 随机兜底分支残余 `500` 主因已修掉
 4. `www.lgyz.net` 这类此前仍偏弱的站点，当前外网回测也已恢复到 `200`
 后续继续重点观察：
 - `baiduspider` 是否重新放量回打 `detail / play`
 - 新命中的深页是否继续保持 `200`
 - 是否还会出现新的局部 `500` 或数据异常型落点
 #### 2026-04-16 14:00 最新补充观察
 截至当前最新一轮：
 - `2026-04-16 14:00:02`
 还没有出现更晚的抓取汇总文件。
 这一轮里，最重要的新样本是：
 - `sjzyunyang.com /video-bofang/zhe-zhi-172193-default-1`
 - `page_type = play`
 - 状态链为：
  - `301`
  - `200 (MISS)`
  - `200 (HIT)`
 这说明：
 1. 百度在今天这轮里仍然继续命中新 `play` 深页
 2. 系统不仅能把它接住，而且第一次已经真实回源生成成功
 3. 后续立刻进入缓存命中，说明链路已经不是偶发通过
 当前可以把这条样本理解为：
 - 不是旧坏链修复后的被动回测
 - 而是今天新命中的播放页也已经开始成功落地
 因此，截至当前窗口，对这轮优化更准确的判断是：
 - 深页兼容层有效
 - 随机兜底层有效
 - 新命中的 `play` 深页也开始持续出现 `301 -> 200`
 ##### `jingxifa.com`
 在 `2026-04-15 17:40:03` 这一轮，百度命中：
 - `/video-bofang/hao-bu-liu-qing-185887-default-1`
 结果出现：
 - `301 -> 200`
 这说明：
 - `play` 深页历史兼容开始生效
 - 不再只表现为 `301 -> 404`
 ##### `www.vikau.com`
 在 `2026-04-15 18:40:02` 这一轮，百度命中：
 - `/voddetail/ma-xiang-lou-zhi-zao-meng-xian-sheng-47065`
 结果出现：
 - `301 -> 200`
 这说明：
 - `detail` 深页兼容也开始出现正向落地样本
 #### 仍需继续观察的站点
 以下站点在本轮观察窗口内，仍主要看到失败样本：
 1. `www.lgyz.net`
 2. `sjzyunyang.com`
 3. `www.codohealth.com`
 4. `gxhongzhuang.com`
 这些站点的问题表现仍以：
 - `301 -> 404`
 为主，但失败样本主要集中在修复后的早期窗口，后续还需继续观察是否会像 `jingxifa.com` 一样转为成功样本。
 #### 当前阶段判断
 当前应将本轮结果理解为：
 - 深页兼容修复已开始起效
 - 但百度还没有重新形成稳定深抓
 因此下一阶段的重点不是立即继续大改，而是：
 1. 继续观察百度是否重新命中更多 `detail/play`
 2. 继续记录哪些站从 `301 -> 404` 转成 `301 -> 200`
 3. 将还未转正的域名继续列为重点观察对象
 #### 观察建议
 下一轮继续观察时，优先盯：
 1. `jingxifa.com`
 2. `www.vikau.com`
 3. `www.lgyz.net`
 4. `sjzyunyang.com`
 目的：
 - 确认成功样本是否持续出现
 - 确认失败样本是否继续减少
 这样第一阶段如果需要修老模板样式，不会卡在缓存上。
 ---
 ## 第六步：明确哪些不要碰
 第一阶段明确不碰这些：
 ### 6.1 不要用后台逐站编辑改模板绑定
 避免碰：
 - `t_id`
 - `t_cfg`
 原因：
 - `t_id` 会直接决定该站用哪套视图模板
 - `t_cfg` 会影响该站冻结模板配置和 URL 模板映射
 ### 6.2 不要先批量套 `d_seo_cfg`
 原因：
 - 第一阶段先做基础设施层
 - 不要让老模板先承受太多 SEO 输出行为变化
 ### 6.3 不要先改结构层
 包括：
 - 首页模块结构
 - 列表卡片结构
 - 评论区整体结构
 - 全站导航结构
 ---
 ## 第七步：验收标准
 第一阶段不看“感觉”，只看这 4 组信号。
 ### 7.1 百度入口命中
 后台重点看：
 - `home`
 - `robots`
 - `sitemap`
 ### 7.2 百度入口状态码
 希望看到：
 - `200`
 尽量减少：
 - `301`
 - `404`
 - `444`
 ### 7.3 是否开始出现 `category`
 这是第一阶段最关键的推进信号。
 如果 `category` 开始出现，说明：
 - 百度已经不只是停在首页和入口层
 ### 7.4 静态资源是否可控
 验证：
 - 改样式能自动重编生效
 - 必要时提升 `STATIC_FILE_VERSION` 能强制刷新
 ---
 ## 第八步：建议观察周期
 试点模板完成第一阶段后，建议观察：
 - `3-5` 天抓取变化
 - `7` 天收录信号变化
 如果信号对，再复制到其余老模板。
 如果这一步还没看到明显入口改善，不要急着推进第二阶段内容增强。
 ---
 ## 第一阶段完成后的下一步
 只有在第一阶段稳定后，才建议进入第二阶段：
 - 详情页事实池轻接入
 - 描述增强
 - 播放页导语增强
 - FAQ / 评论导语轻增强
 第二阶段仍然建议：
 - 先 1 套模板试点
 - 不 5 套一起上
 ---
 ## 一句话版本
 老模板第一阶段不是“升级成 gpt 模板”，而是：
 - 先统一抓取入口
 - 先统一输出规范
 - 先统一观测能力
 - 先统一静态资源发布能力
 先把底座拉齐，再看第二阶段内容增强。
--- a/docs/1270-SEONexus-Codex多版本协作交接总文档.md
+++ b/docs/1270-SEONexus-Codex多版本协作交接总文档.md
@@ -0,0 +1,557 @@
 # 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 身份边界。
 ### 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 交接总文档
 也就是当前这份文档，适合记录：
 - 协作规则
 - 边界
 - 交接模板
 - 多版本协作方法
 如果后续发现某条规则经常踩坑，就更新本文件，不要只留在聊天记录里。
 ---
 ## 特别注意事项
 ### 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，也仍然能稳。
--- a/docs/README.md
+++ b/docs/README.md
@@ -0,0 +1,6 @@
 # SEONexus docs 同步说明
 - 当前目录用于承接外部 `/www/wwwroot/diff-maccms/docs` 中需要随仓库同步的关键文档。
 - 现阶段优先同步多 Codex 协作总规则与老模板回灌执行文档。
 - 原有 `SEONexus/doc` 目录暂不删除，避免影响项目内历史引用。
 - 后续若继续迁移，以 `SEONexus/docs` 作为正式协作文档入口。