操作术语协议

操作术语协议

0. 目的与适用范围

这份文档是当前 docs/agent 下唯一的“操作术语协议”真源，用来约束我在面对“仓库整合 / 接入 / 迁入 / 并入 / 保留独立仓 / GitHub 归属 / 前端以谁为基础”这类请求时的默认理解方式。

当前版本先覆盖：

1. 仓库整合与跨仓接入
2. 前端基底判定
3. GitHub 远端与源码真源归属
4. 后续扩写操作术语时的稳定入口规则

后续如果还要新增别的高频操作术语，默认继续追加到这一个 canonical 文件中，不再在 docs/agent 下新建平行“术语说明 / 术语协议 / 口径约定”文档。

当前 canonical 路径：docs/agent/操作术语协议.md。

1. 核心对象定义

1.1 宿主仓

“宿主仓”是指本轮整合动作最终要落进去、继续扩展、继续部署、继续交付的那个仓库。

只要用户说“把 A 整合进 B”，默认 B 就是宿主仓。

1.2 来源仓

“来源仓”是指被接入、被吸收、被迁移、被参考的那个仓库。

在“把 A 整合进 B”里，默认 A 是来源仓。

1.3 前端基底

“前端基底”是指导航、路由、页面壳、布局层、视觉语言、组件系统、页面组织方式主要归属的那一套前端体系。

默认不是看“哪边页面更多”，而是看“整合后页面长在哪个产品壳里”。

1.4 owning repo

“owning repo”是这轮改动边界真正应该接收第一手 commit / push 的仓库。

默认情况下：

• 宿主仓 = owning repo

除非用户明确要求：

• 双仓并行维护
• 先改来源仓再由宿主仓消费
• 或者 live 边界明确不在宿主仓

1.5 canonical source

“canonical source”是后续继续迭代时默认应该优先修改的源码真源。

默认情况下：

• 被整合进去之后，宿主仓成为该整合范围内的 canonical source

1.6 source donor role

来源仓在整合完成后默认有三种角色：

1. independent source：继续独立演进，但本轮只是被宿主仓消费
2. reference / mirror：保留历史与参考价值，但不再是该功能范围的第一开发真源
3. archive：只保留归档意义，不再承担后续活开发

1.7 working copy

“working copy”是指为当前任务临时创建的本地 clone / worktree，用来编辑、验证、 构建、截图和提交，但默认不作为长期源码镜像保存。

在 GitHub 单真源模式下，默认口径是：

• canonical source 负责长期源码真源
• working copy 只是 task-scoped disposable 本地副本
• push / deploy 完成后，如无明确保留理由，默认应回收该副本

1.8 repo manifest

“repo manifest”是指为某个会反复出现的 canonical repo 预先记录的一份轻量默认值文件， 用来给 working-copy 生命周期提供稳定元数据，而不是每次都靠聊天临时重述。

在当前 GitHub 单真源模式下，默认 repo manifest：

• 一仓一文件
• 只记录 clone / branch / folder / deploy target 等默认值
• 不承担新的 registry、计划台账或第二真源职责
• 默认放在 github-delivery-mcp 的 manifests/ 目录下

2. 默认术语判定

如果用户没有补充说明，默认不要把“整合进”理解成“两边混合重组出第三套平行实现”。

3. 前端以谁为基础扩展的默认判断规则

当用户说“把 A 仓库整合进 B 仓库”时，默认按下面顺序判断前端基底：

1. 用户是否明确说“前端保留 A 风格 / 以 A 为基础”
2. 最终页面是否长在 B 的导航、路由、layout、workspace 壳层里
3. live 站点是否跟着 B 的域名、容器、运行目录、部署链走
4. 后续迭代是否默认在 B 里继续写
5. 第一手 Git 提交是否应该先落到 B

只要 2-5 没被用户显式覆盖，默认前端基底就是 B。

更直接地说：

• A 整合进 B
• 默认不是“把 A 的页面皮肤搬到 B”
• 而是“把 A 的能力、数据源、领域结构收进 B 的产品壳”

默认实现方式：

1. 路由注册在宿主仓
2. 导航入口挂在宿主仓
3. 页面壳、布局、卡片、tab、视觉层级沿用宿主仓
4. 复用来源仓的数据源、领域结构、已有逻辑时，优先做桥接或模块迁移
5. 不默认使用 iframe 薄嵌入
6. 不默认整页复制来源仓 CSS / token / 页面骨架

4. GitHub 远端与源码真源的默认处理

4.1 单一第一真源原则

一条整合任务默认只允许有一个第一开发真源。

默认口径：

• 宿主仓的 GitHub 远端 = 本轮主交付远端
• 宿主仓 = 该整合范围内的 canonical source

除非用户明确要求“双仓长期并行维护”，否则不要把宿主仓和来源仓同时维持为同一功能范围的双活真源。

4.2 默认远端交付顺序

默认交付顺序是：

1. 先在 owning repo 完成 status -> commit -> push
2. 如果还有 umbrella / mirror / backup repo 需要吸收结果，再做第二层同步
3. 不要反过来先推镜像仓、再补宿主仓

4.3 来源仓的默认处理方式

来源仓默认按三种整合模式之一处理：

a. 消费式整合

• 宿主仓只消费来源仓的 API、MCP、数据、SDK 或运行输出
• 来源仓继续独立存在
• 默认不搬整块源码

b. 吸收式整合

• 只把来源仓里真正需要的源码、模块、资源、配置迁进宿主仓
• 迁入范围后续默认在宿主仓继续开发
• 来源仓保留历史，但不再是该范围的第一开发真源

c. 迁移式整合

• 某一整块能力整体迁到宿主仓
• 宿主仓成为唯一活真源
• 来源仓默认降级为 reference / mirror / archive

如果用户没有明确说“保留来源仓继续作为主要开发面”，默认优先按 消费式 或 吸收式 理解，而不是长期双边维护。

5. 源码处理的默认顺序

默认不要把“整合”理解成“先整仓复制再慢慢收拾”。

更稳的默认顺序是：

1. 先判断宿主仓是谁
2. 先判断前端基底是谁
3. 先判断 live deploy target 跟谁走
4. 先判断来源仓是 independent source、reference 还是 archive
5. 再决定源码是桥接、局部迁移，还是整块吸收

默认源码处理优先级：

1. 先接能力
2. 再接结构
3. 最后才考虑是否搬完整源码

默认做法：

• 页面：在宿主仓里重建页面入口、路由和壳层
• 数据：桥接来源仓的数据源或 API
• 逻辑：迁最小必要模块，或按宿主仓风格重写
• 样式：默认沿用宿主仓，不直接照搬来源仓整页视觉
• 资源：只迁当前功能真正需要的部分
• 文档：补清楚 source-map，说明“哪些来自来源仓，现在哪里继续维护”

默认不做的事情：

• 不把整个来源仓连同 .git 一起塞进宿主仓
• 不把来源仓的 README、脚手架、历史布局、旧 CSS 全量复制进宿主仓
• 不把双边路由、双边页面、双边导航长期并存

6. 扩展术语定义

6.1 接管 / 收口 / 归档 / 镜像

接管

• 默认含义：某个宿主仓、宿主系统或宿主团队开始承担该边界的主交付责任、主维护责任和第一手变更责任。
• 默认不含义：不自动等于“所有源码已经整块迁完”；如果只是先接运行、接导航、接交付，但源码还在别处，需要显式说明。
• 默认执行后果：
  • owning repo 默认切到接管方
  • 后续默认以接管方作为 canonical source 或至少作为主交付面
  • 原边界如果不再承担第一手开发，默认进入 降级 判断
• 与相近术语区别：
  • 接管 强调责任与控制权转移
  • 迁移 强调边界/源码/流量从哪里移到哪里
  • 替换 强调旧实现被新实现换掉

收口

• 默认含义：把原本分散、并行、容易歧义的路径、口径、入口、真源或命名压回一个 canonical 面。
• 默认不含义：不自动等于删库、删目录、删历史；如果只是统一解释权，也可以先不做物理删除。
• 默认执行后果：
  • 要明确唯一 canonical 路径、唯一 live 入口或唯一默认说法
  • 并行说明、并行入口、并行命名默认要被移除、改写或降级为兼容说明
• 与相近术语区别：
  • 收口 强调“减少歧义、压成一口径”
  • 接管 强调“谁负责”
  • 归档 强调“退出活开发”

归档

• 默认含义：某个仓、目录、页面、文档或能力退出 live 主线，只保留历史、审计、追溯或应急恢复价值。
• 默认不含义：不自动等于删除；也不自动等于仍然参与日常迭代。
• 默认执行后果：
  • 默认不再接第一手写入
  • 默认不再作为 live 导航入口、默认读取入口或默认开发入口
  • 如仍保留文件，应明确标成 archive / historical / snapshot
• 与相近术语区别：
  • 归档 是冻结后的保留
  • 镜像 仍可能持续跟随 canonical source 同步
  • 降级 只是角色下降，未必已经冻结到 archive

镜像

• 默认含义：从 canonical source 派生出来的复制面、同步面或备份面，用于备份、分发、消费层展示或灾备。
• 默认不含义：不自动等于第一开发真源；也不自动等于可以先在镜像上做第一手修改。
• 默认执行后果：
  • 默认 canonical source -> mirror 单向或主从同步
  • 默认先推 canonical source，再同步 mirror
  • mirror 若接受修改，也应视为例外流程而不是默认工作面
• 与相近术语区别：
  • 镜像 强调“复制与同步”
  • 归档 强调“冻结与保留”
  • 双活 则意味着镜像侧也成了第一手活写入面，这是默认不允许的

6.2 单写 / 双写 / 双活 / 降级

单写

• 默认含义：同一边界只有一个第一手写入真源，其它位置要么只读、要么镜像、要么由它生成。
• 默认不含义：不代表没有备份、没有镜像、没有消费层；只是这些面不承担第一手变更。
• 默认执行后果：
  • 这是本协议的默认目标态
  • 汇报时应能明确指出唯一 owning repo / canonical source

双写

• 默认含义：出于过渡、兼容、迁移窗口或风险控制，同一批变更需要同时落到两个写入面。
• 默认不含义：不等于长期双活；也不等于两个面都拥有独立解释权。
• 默认执行后果：
  • 必须说明哪一边是主写入源，哪一边是跟随写入面
  • 必须说明双写的结束条件，避免永久化
  • 默认只作为阶段性策略，而不是常态架构

双活

• 默认含义：两个仓、两个系统或两个运行面在同一边界上都可接受第一手活写入，并都可能成为事实真源。
• 默认不含义：不等于普通镜像、备份、消费层接入，也不等于短期双写。
• 默认执行后果：
  • 这是高成本例外态，不是默认值
  • 若用户明确要求双活，必须补清冲突解决规则、同步顺序和退场条件
  • 如果没有这些条件，默认不按双活执行

降级

• 默认含义：某个仓、系统、页面、文档或能力从主角色退到次角色，例如从 canonical source 退到 mirror / reference / compat / archive。
• 默认不含义：不自动等于删除；也不自动等于完全失效。
• 默认执行后果：
  • 默认不再承担第一手 commit / push / 文档解释权 / live 入口
  • 必要时保留 compatibility note、legacy wrapper 或历史说明
• 与相近术语区别：
  • 降级 是角色变化动作
  • 归档 是更靠后的冻结状态
  • 收口 常常会导致某些对象被降级，但两者不是同义词

6.3 替换 / 迁移 / 吸收 / 消费式整合

替换

• 默认含义：在同一交付边界内，用新的实现、页面、入口、能力或路径取代旧的那一个。
• 默认不含义：不自动等于源码真源也一起迁走；有时只是同仓内实现替换。
• 默认执行后果：
  • 旧实现默认退出主路径
  • 新实现默认接 live 流量、主导航或主调用入口
  • 需要同步清理旧入口、旧说明和旧默认口径
• 与相近术语区别：
  • 替换 更关注“谁上谁下”
  • 迁移 更关注“边界搬到哪里”
  • 接管 更关注“谁开始负责”

迁移

• 默认含义：把源码真源、运行边界、部署边界、配置归属或数据流从原位置转移到新位置。
• 默认不含义：不自动要求新旧实现长得完全不同；也不自动等于宿主仓已经吸收了所有历史内容。
• 默认执行后果：
  • 要明确迁移前后的位置、边界、角色和完成判据
  • 迁移完成后，旧位置默认进入 降级、镜像 或 归档
• 与相近术语区别：
  • 迁移 强调位置和归属转换
  • 替换 强调旧实现被新实现换掉
  • 吸收 强调宿主仓把所需部分纳入自身继续开发

吸收

• 默认含义：宿主仓把来源仓中的某部分源码、模块、资源、配置或知识吸进自己，后续在宿主仓继续维护。
• 默认不含义：不自动等于整仓搬迁；默认是按边界、按模块、按必要范围吸收。
• 默认执行后果：
  • 被吸收范围内，宿主仓成为 canonical source
  • 来源仓在该范围内默认降级为 reference / mirror / archive
• 与相近术语区别：
  • 吸收 是源码/结构层面被宿主仓内化
  • 消费式整合 则是不接管源码真源，只消费输出

消费式整合

• 默认含义：宿主仓接入来源仓的 API、MCP、SDK、数据、静态产物或运行输出，但不拿走其源码真源地位。
• 默认不含义：不自动等于源码迁移，也不自动等于接管。
• 默认执行后果：
  • 宿主仓负责自己的接入层、桥接层、导航层和展示层
  • 来源仓仍可保持 independent source
  • 双方默认不是双活，而是“宿主消费、来源供给”

6.4 易混淆术语对照

7. 我在执行前必须先明确的 8 个判断

以后只要任务命中下面这些说法之一：

• 整合进
• 接入到
• 迁入
• 并入
• 保留独立仓
• 双活维护
• 前端以谁为基础
• GitHub 推哪个仓
• 源码归谁
• 接管
• 收口
• 归档
• 镜像
• 单写
• 双写
• 双活
• 降级
• 替换
• 迁移
• 吸收
• 消费式整合

默认在真正开改前先明确下面这 8 个判断：

1. 宿主仓是谁
2. 前端基底是谁
3. owning repo 是谁
4. canonical source 是谁
5. live deploy target 跟谁走
6. 来源仓后续扮演什么角色
7. 写入模式是 单写、双写 还是 双活
8. 当前是否发生 接管 / 收口 / 替换 / 迁移 / 降级 / 镜像 / 归档

如果用户没额外覆盖，默认值按本协议执行。

8. 默认输出口径

以后我在汇报这类任务时，默认要把结论压成下面这组固定字段：

• 宿主仓
• 前端基底
• owning repo
• canonical source
• live deploy target
• source donor role
• 整合模式：消费式 / 吸收式 / 迁移式
• working copy
• repo manifest
• 写入模式：单写 / 双写 / 双活
• 角色动作：接管 / 收口 / 替换 / 迁移 / 降级 / 镜像 / 归档
• 是否需要回收本地副本

这套字段是为了减少语义歧义，不代表必须每次都长篇解释，但至少内部判断必须完整。

9. 扩展规则

这份文档以后承担 docs/agent 下“高频操作术语协议”的唯一 canonical 入口。

后续若再新增其他操作术语，例如：

• 接管
• 收口
• 镜像
• 归档
• 替换
• 迁移
• 吸收
• 消费式整合
• 双写
• 单写
• 双活
• 降级

默认执行下面这组规则：

1. 继续追加到 操作术语协议.md
2. 不另建并行“术语说明 / 术语补充 / 口径约定”文档
3. 如果新术语会改变实际执行规则，要在同一工作周期同步更新：
   • 本文
   • 第一库文档管理规范.md
   • .gitignore（若 tracked whitelist 有变化）
   • PROJECT-CONTEXT.md
   • C:\Users\ASUS-KL\.codex\AGENTS.md
   • C:\Users\ASUS-KL\.codex\AGENTS.annotated.md
4. 如果新术语影响 repo 角色或同步顺序，再同步 REPO-OWNERSHIP-MAP.md

目标不是“积累很多术语页”，而是持续维护一个稳定、可触发、可扩展的操作语义真源。