oh-my-claudecode 源码清理实战：多 Agent「专属所有权矩阵」分车道编排全解

oh-my-claudecode 是一套面向 Claude Code 的 Teams-first 多 Agent 编排系统，其 .omx/plans/source-overall-cleanup/ownership-matrix.md 定义了一次代号 Source-Overall Aggressive Cleanup 的大规模源码清理行动如何被拆分为互不冲突的"所有权车道（Lane）"。本指南以该所有权矩阵为骨架，逐层拆解 Lane 0～Lane 5 的目标文件归属、串行化约束与交接规则，并结合仓库中真实存在的源码与测试文件，说明"哪些代码可安全清理、哪些必须保留、谁在何时才能动手"，帮助读者理解大型 TS 代码库在多 Agent 并行协作下控制改动冲突与公共契约风险的工程方法。

矩阵是什么：一份"谁拥有哪个文件"的并行改造契约

在 oh-my-claudecode 中，多 Agent（如 planner、architect、executor、test-engineer、verifier 等角色）会围绕一个大型目标并行推进。Source-Overall Aggressive Cleanup 的目标不是小修小补，而是对 src/ 下大量模块做整体瘦身与"缝合点（seam）"重构。若多个执行者同时改同一文件族，必然产生合并冲突与语义漂移。因此规划阶段先落地一份专属所有权矩阵（Exclusive Ownership Matrix），作为后续所有清理批次的"协调真相源"。

该矩阵文档位于 .omx/plans/source-overall-cleanup/ownership-matrix.md，与同目录下的 fallback-classification-inventory.md、first-safe-cleanup-batch.md、generated-artifact-policy.md 共同构成规划期的"就绪产物（readiness artifacts）"。矩阵文档本身声明其真相来源为 PRD、测试规格与一次上下文快照（.omx/context/source-overall-aggressive-cleanup-20260521T053809Z.md），即它是在正式动源码之前的编排蓝图。

从仓库目录结构看，这套计划与 oh-my-claudecode 的既有多 Agent 机制高度吻合：src/agents/、src/hooks/、src/team/ 中大量模块本身就以"可独立委派、可交接"为设计目标，清理行动恰好是对这些模块的又一次压力测试。

四条铁律：所有权矩阵的核心规则

矩阵在正文前先立下四条约束，它们是整个清理行动的"宪法"：

1. 一个文件/一个串行化模块族，同一时刻只有一个活跃 Owner（One active owner per file or serialized module family）。这是消除并行写冲突的第一手段。
2. src/tools/state-tools.ts 禁止并行编辑：它从 Lane 2 起步，只有通过显式交接才允许进入 Lane 3 做缝合点抽取。该文件是全仓库唯一的"显式串行化文件族"，在 PRD 中被特别点名，任何后续改动都必须等 Lane 2 完成。
3. 测试文件可与源码文件独立归属所有权。即测试加固可以先行，不必等待对应源码的 Owner。
4. 生成产物（generated artifacts）不是源码车道的目标，它们在流程末尾统一验证。这一条与同目录 generated-artifact-policy.md 的"规划期不重新生成、实现期随源码一起提交生成物"决策前后呼应。

Lane 0：基线锁定与清单盘点（只读，任何人不得动源码）

Lane 0 的 Owner 只有 planner / verifier，明确标注 no source edits。其职责有两类：

• 就绪产物本身：.omx/plans/source-overall-cleanup/* 全部只作为可读性依据存在；
• 基线验证命令：git status、npm test -- --run、npm run build、npm run lint，在任何人动手前先把全量基线测绿；
• Fallback 清单盘点：对源码中的各类 fallback 行为做预分类（是"掩盖问题的 slop"还是"有依据的兼容/故障安全"）。

这一设计非常关键：没有基线数据，后面任何"我改了没弄坏东西"的结论都不可信。事实上 oh-my-claudecode 在 src/__tests__/ 下就存放了大量回归测试，Lane 0 的 npm test -- --run 正是为这些测试建立"改造前快照"。

Lane 1：测试契约加固（只测不改源，先行锁定行为）

Lane 1 的 Owner 是 test-engineer / executor，但权限范围仅限于测试文件。其核心理念是：先行为锁定（behavior lock），后源码重构。矩阵列出了九份必须优先加固的测试锚点，每份都有明确的契约目的：

测试文件	锁定的契约
src/config/tests/loader.test.ts	配置加载与路由契约
src/config/tests/models.test.ts	Provider/模型推断契约
src/tests/state-root-resolution.test.ts	集中式 state-root 回归锁
src/tests/hooks.test.ts	Hook 桥 / 持久模式行为
src/hooks/tests/bridge-routing.test.ts	Hook 路由矩阵与前置条件门控
src/tools/python-repl/tests/python-sandbox.test.ts	沙箱执行边界
src/tools/python-repl/tests/tcp-fallback.test.ts	Unix socket / TCP 回退路径
src/team/tests/runtime-cli.test.ts	Runtime CLI 产物与终端保真
src/team/tests/teardown-invariant.test.ts	drain/stop 停机不变量

从仓库实际布局看，这些测试文件全部真实存在：src/config/__tests__/、src/hooks/__tests__/、src/tools/python-repl/__tests__/、src/team/__tests__/ 均已被大量测试覆盖。矩阵刻意挑选的是**"契约形、小而聚焦"**的模块测试，而非最大的编排器，目的是让 Lane 2/3 的每个改动都能立刻有测试判定"行为是否改变"。

Lane 2：Fallback / State 契约清理（串行化目标，一次一个执行者）

Lane 2 的 Owner 是单个 executor 车道，只允许串行处理目标。这是整个清理中最敏感的环节，因为矩阵点名的文件族几乎都承载"兼容性回退"：

• src/tools/state-tools.ts：首个探测目标（first probe target），必须先串行分类、再考虑缝合点抽取；
• src/config/loader.ts、src/config/models.ts：配置/模型回退与继承规则；
• src/features/state-manager：状态路径 / 持久化行为；
• src/tools/python-repl：运行时边界上的有依据兼容回退；
• src/tools/diagnostics 与 src/tools/lsp：工具链回退边界，删除前必须先分类；
• src/features/delegation-routing：路由默认值 / 继承回退；
• src/features/rate-limit-wait：围绕 tmux / capture 的运行时 smoke / 回退行为；
• src/features/auto-update.ts：更新路径兼容与 stale-root 处理；
• src/openclaw：外部网关兼容行为。

为什么这些文件要"先分类再动刀"？参考配套的 fallback-classification-inventory.md，清理前必须对每处 fallback 做出三选一判定：

• Masking slop（掩盖性垃圾代码）：隐藏了可操作的失败、静默禁用行为、让备选行为难以观察——这类是最优先的清理对象；
• Grounded compatibility / fail-safe（有依据的兼容/故障安全）：刻意保留的运行时兼容或安全边界，有界、有可观察证据——禁止在反 slop 清理中删除；
• Ambiguous escalation（语义存疑）：可能合理，但需要 leader/ralplan 决策后才可删或保留。

仓库中的源码可以佐证这些分类的含义。例如 src/openclaw/config.ts 对"禁用 env 标志、缺失配置、非法配置"统一收敛为 null，被归为 Ambiguous escalation（环境禁用可保留为 opt-in 语义，但非法 JSON 应产生可调试证据）；而 src/openclaw/dispatcher.ts 将网关调用设计为对 hook 显式非阻塞，被归为 Grounded compatibility——这正是 oh-my-claudecode 让"hook 执行不依赖外部网关可用性"的核心设计，清理时绝不能破坏。

Lane 3：编排器缝合点抽取（与 Lane 2 串行文件零重叠）

Lane 3 的 Owner 同样是单个 executor 车道，且与 Lane 2 的串行化文件不得重叠。目标是被刻意回避的最大编排器——它们在 Lane 1 的测试契约成型前是"高危区"，现在则轮到它们被拆出缝合点：

文件	待抽取的缝合点
src/hooks/bridge.ts	Hook 分发 / 规范化 / 状态 IO
src/hooks/persistent-mode/index.ts	统一 stop handler
src/team/runtime-v2.ts	Team 收敛与 teardown 缝合
src/installer/index.ts	安装器编排缝合
src/cli/index.ts	CLI 解析 / 命令注册缝合
src/cli/team.ts	Team CLI 表面缝合
src/hooks/subagent-tracker/index.ts	Subagent 追踪 / 清理缝合

从仓库看，src/team/ 是 oh-my-claudecode 最庞大的目录之一（runtime-v2.ts、runtime.ts、merge-coordinator.ts 等众多文件并存），src/hooks/ 下也确有 src/hooks/bridge.ts、src/hooks/persistent-mode/、src/hooks/subagent-tracker/。这些"缝合点"文件被编排到 Lane 3 单独处理，是因为它们横跨多个子系统：一旦动错，hook 事件语义、CLI 退出码、team 运行时状态都会变成公共面（public surface）破坏。

Lane 4：重复 / 边界清理（前置车道完成后方可接手）

Lane 4 的 Owner 约束是"only after owning lane completes its previous target family"——即必须等所属车道完成前一目标族后才允许动手。它的两个目标是：

• 前面车道触碰过的共享辅助模块：合并重复的 path / rendering / state helper；
• 错层导入或隐藏副作用：只有在 Lane 1 的测试锁已就位后才能移除。

这一条的工程智慧在于：重复代码与隐藏副作用的清理风险极高，必须建立在"前序车道已把相关模块测牢 + 只清理自己触碰过的文件"的双重保险之上，避免一个清理动作破坏八处引用却无从追溯。

Lane 5：死代码 / 告警清理（唯一终点车道）

Lane 5 是 final pass，Owner 只能在功能测试通过后清理"被触碰文件"中的：

• 未使用的 import / 变量；
• 测试中的 slop（as any、eslint disable）——前提是移除后覆盖率等同或更好。

注意 Lane 5 也限定"touched files"，而非全仓库扫荡，进一步印证了"专属所有权"贯穿始终：任何文件的最终归宿都由它的 Owner 车道负责到底。

交接规则：串行化与显式交接

矩阵末尾给出两条交接规则，是整个编排能收敛的关键：

1. 一个文件只有在上一车道产生完整产物或显式交接说明后，才能移入下一车道。即"改完要有据可查，才能交棒"。
2. src/tools/state-tools.ts 是 PRD 中唯一显式串行化的文件族，所有后续工作必须等 Lane 2 完成。配套清单也强调：在清单被接受、后续交接明确允许 Lane 3 缝合点抽取之前，src/tools/state-tools.ts 始终属于 Lane 2 的 fallback/state-contract 文件。

这套"交接 = 产物 + 许可"的规则，与 oh-my-claudecode 团队机制中"任务必须有 owner、有完成证据"的理念一致——矩阵只是把同一套治理逻辑下沉到文件级。

与配套规划产物的协同

所有权矩阵不是孤立文件，它和 .omx/plans/source-overall-cleanup/ 下其他三份产物构成闭环：

• fallback-classification-inventory.md 为 Lane 2 提供分类方法（关键词检索 fallback/legacy/default/catch/silent/best-effort/non-blocking/unavailable/timeout/compat），并给出"先保护再清理"的名单——例如 diagnostics 的 tsc→LSP 回退、Python REPL 的安全运行时目录回退、OpenClaw 非阻塞分发、rate-limit-wait 的不可用 API/tmux/dead-pane 行为，都被列为"禁止在反 slop 清理中删除"的 grounded fallback；
• first-safe-cleanup-batch.md 选取了六个"已有聚焦测试的小模块"（state-manager、models、delegation-routing resolver、python-repl socket-client、openclaw dispatcher、diagnostics lsp-aggregator）作为首批实施切片，并给出改动前后必须运行的 Vitest 命令清单；
• generated-artifact-policy.md 规定：dist/、bridge/*.cjs、bridge/team.js、docs/shared/ 等由 package.json 发布流程产出的文件，实现车道改源后必须随 PR 一起重新生成提交，规划期则不得触碰。

矩阵的 Lane 0 正好消费这三份产物的输出（基线命令、fallback 清单、生成物策略），Lane 2/3 的改动则以它们的测试锚点作为行为判据。这也解释了为何清理计划中的批处理文档反复强调：任何存疑项都必须先补行为锁定测试、再由 leader/ralplan 决策，不能仅凭清单就编辑源码。

小结：这套矩阵解决了什么问题

把 oh-my-claudecode 的 ownership-matrix 提炼成方法论，它解决的是并行源码改造的四个经典难题：

1. 冲突：通过"一文件一 Owner、串行化文件族"从源头消灭并行写冲突；
2. 行为漂移：通过 Lane 1"先锁测试、后动源码"保证每次重构都有可验证的契约；
3. 误删兼容逻辑：通过 Lane 2 的 fallback 三分类（masking slop / grounded / ambiguous）区分"该删的"与"绝不能删的"；
4. 失控的公共面：通过 Lane 3 集中处理编排器缝合点、Lane 5 限定"touched files"，把大型清理拆成每步都可审查、可回滚的串行切片。

对于任何有 src/ 下大量交错模块、且由多 Agent 或多人并行维护的 TS 项目，这份矩阵都是可复用的治理模板。想深入验证文中提到的文件族，可直接在仓库中对照 src/tools/state-tools.ts（串行化标杆）、src/config/models.ts（公共配置面）、src/openclaw/dispatcher.ts（非阻塞边界）、src/features/state-manager（状态回退）及其对应 __tests__/ 目录阅读源码与测试，观察"行为锁定后再清理"的完整证据链。