调研核心大包与高耦合结构拆分方案

[kxn]

背景

近期多次修复 race、SSOT、fallback、性能和重复实现问题时，反复命中同一类结构性风险：少数核心包承担了过多职责，导致局部修改需要同时理解多条状态机、多个 runtime、Feishu 投影规则和持久化同步边界。

本 issue 用于对当前代码的“大包 / 高耦合 / 改动半径过大”问题做深度调研，并形成可以拆成执行单元的计划。当前不直接要求一次性重构。

初步证据

包规模：

github.com/kxn/codex-remote-feishu/internal/core/orchestrator 133 production files, 98 test files
github.com/kxn/codex-remote-feishu/internal/app/daemon 101 production files, 93 test files
github.com/kxn/codex-remote-feishu/internal/adapter/feishu 44 production files, 66 test files

核心包 receiver 方法数量：

internal/core/orchestrator methods=855
internal/app/daemon methods=649
internal/adapter/feishu methods=291

前三个风险包生产 Go 代码合计约 69k 行，测试约 80k 行。多个单文件接近或超过 800-950 行，例如：

• internal/core/orchestrator/service.go
• internal/core/orchestrator/service_request.go
• internal/core/orchestrator/service_target_picker.go
• internal/app/daemon/app_ingress.go
• internal/app/daemon/app_surface_resume_state.go
• internal/adapter/feishu/app_autoconfig.go
• internal/adapter/feishu/projector.go

范围

本母 issue 只负责结构调研、风险分层和拆分计划，不直接承载全部重构实现。调研范围限定为：

• daemon 串行入口、recovery 编排、runtime state owner、持锁外调用边界。
• orchestrator 内部子状态机 owner、runtime cluster、claim/queue/picker/request/progress 之间的耦合。
• Feishu adapter 中 gateway transport、projector、app autoconfig、connection/API helper 的包边界。
• 测试组织是否已经成为拆分阻力，以及哪些测试应先下沉为 contract tests。

非目标

• 不做一次性大重构。
• 不为了行数好看机械拆文件。
• 不改变现有产品行为。
• 不在没有测试保护的情况下移动状态机所有权。
• 不把当前 issue 直接标记为可编码执行单元；它应先产出子 issue。

相关文档

• docs/general/remote-surface-state-machine.md
• docs/general/feishu-card-ui-state-machine.md
• docs/general/feishu-menu-card-usage-guidelines.md
• docs/general/feishu-card-content-context-guidelines.md
• docs/general/issue-orchestration-workflow.md

涉及文件

优先调研这些文件/区域：

• internal/app/daemon/app.go
• internal/app/daemon/app_ingress.go
• internal/app/daemon/app_surface_resume_state.go
• internal/app/daemon/app_vscode_migration.go
• internal/app/daemon/app_headless*.go
• internal/app/daemon/app_cron*.go
• internal/app/daemon/app_feishu_permissions.go
• internal/core/orchestrator/service.go
• internal/core/orchestrator/service_runtime_clusters.go
• internal/core/orchestrator/service_queue*.go
• internal/core/orchestrator/service_target_picker*.go
• internal/core/orchestrator/service_request*.go
• internal/core/orchestrator/service_routing_*.go
• internal/adapter/feishu/projector.go
• internal/adapter/feishu/gateway*.go
• internal/adapter/feishu/app_autoconfig.go
• internal/adapter/feishu/connection_status.go
• internal/adapter/feishu/drive_file_comments.go
• internal/adapter/feishu/im_*.go

当前观察

internal/app/daemon

App 现在是运行时总线，集中持有 relay/API/pprof server、Feishu gateway/projector、orchestrator service、headless runtime、surface resume runtime、cron runtime、upgrade runtime、turn patch runtime、external access、admin state、多个 mutex 与多类 async callback。

风险：

• 修改 ingress/tick/recovery 时容易跨 runtime 改坏锁边界或串行化假设。
• 多个入口重复编排 VS Code recovery、headless recovery、surface resume sync、workspace context sync。
• 修复 VS Code compatibility 异步刷新引发的 service race #712 的 VS Code compatibility race 是此类边界过宽的具体症状：后台 goroutine 能绕过 daemon 串行入口触碰 service state。

具体热点：

• maybeRecoverVSCodeSurfacesLocked / maybePromptDetachedVSCodeSurfacesLocked / maybeRecoverHeadlessSurfacesLocked 在 onHello、onEvents、onDisconnect、onTick 等入口重复手写组合。
• syncSurfaceResumeStateLocked、syncClaudeWorkspaceProfileStateLocked、syncWorkspaceSurfaceContextFilesLocked 分散在 command/action/hello/event/disconnect 分支中，缺少统一 “state changed -> persistence sync” runner。
• daemon 内有大量持锁外调用和 background 回调，必须靠手工约定决定哪些回调只能写 cache，哪些可以回到串行路径。

internal/core/orchestrator

Service 是状态机 SSOT，但已经同时承载 route/claim、queue/dispatch、request gate、picker、model catalog、progress、review、autocontinue、surface UI runtime、cooldown 等子状态机。

风险：

• 子状态机之间大量共享 state.Root 和 service runtime map，边界主要靠约定。
• 新功能常需要改多个 service_* 文件，测试也逐渐偏大集成 fixture。
• 不适合直接“拆包重构”，更适合先建立内部子 runtime facade 和局部 contract tests。

具体热点：

• service_runtime_clusters.go 已经把 turns/pickers/catalog/progress 聚成 runtime cluster，但调用端仍大量直接访问 s.turns、s.pickers、s.catalog、s.progress。
• claim 与 route、queue 与 progress、request gate 与 routing blocker 之间仍是同包横向调用，拆包会立刻遇到 import cycle 风险。
• 当前已有 execprogress 子包是正向例子：纯算法/数据变换先抽出包，保留状态 owner 在 Service。

internal/adapter/feishu

同一个包内混合：gateway transport、callback parsing、IM/Drive API helper、Projector、app autoconfig、connection status、card rendering helper。

风险：

• Projector 的 projectEventBase 是大型 payload switch，新 payload 容易误漏 reply lane、inline update、temporary header、card envelope 等跨切面规则。
• LiveGateway 同时持有 Lark client、broker、message/reaction tracking、大量 test hook function，transport 与 API helper 耦合明显。
• app autoconfig 与 runtime gateway 共享主包，会扩大 Feishu setup/onboarding 改动影响面。

具体热点：

• PlanAppAutoConfig / ApplyAppAutoConfig / PublishAppAutoConfig 与 LiveGateway 共用 LiveGatewayConfig、Lark client 和 broker，但产品生命周期完全不同。
• GetLongConnectionStatus / GetBotInfo 是 setup/admin 检测能力，不应强依赖 runtime gateway 包内细节。
• IM file/image/video、Drive comments、message patch/reply 等 API helper 可以形成 feishuapi 或 feishuclient 层，gateway runtime 只编排。

深度调研结论

值得优先做

1. daemon 串行 recovery pipeline 收口。
   这是最高优先级，因为它直接降低 race、漏同步和“一个入口修了另一个入口没修”的风险。目标不是拆包，而是先把重复的 recovery/sync 编排变成单一 helper/runner。

2. daemon runtime controller 边界收口。
   将 surface resume、VS Code compatibility、managed headless、Feishu permission refresh 这类有 in-flight/backoff/follow-up 的 runtime state 分别收敛为小 controller 或至少统一的 locked method contract。目标是明确 background goroutine 只产出结果，业务推进必须回串行入口。

3. Feishu app autoconfig / setup API helper 从 runtime gateway 主包中分离。
   这类改动主要是包边界和 API facade 调整，行为风险相对可控；同时能降低 websetup/onboarding 后续迭代的影响面。

4. Projector payload projection registry / helper 收口。
   不建议马上拆整个 projector 包；先把 projectEventBase 的重复 Operation 构造、reply lane、temporary header、inline update 统一 helper 化或 registry 化，保证新增 payload 不会漏跨切面规则。

5. orchestrator 内部 runtime facade。
   不建议第一批做大拆包。优先在同包内把 turns/pickers/catalog/progress/claims 的直接 map 访问减少为 facade 方法，并补 contract tests。等调用点变少后再考虑包级拆分。

暂不建议先做

• 直接把 internal/core/orchestrator 拆成多个 Go package：当前共享 state.Root、route/claim/queue/request/progress 横向调用太多，直接拆会产生 import cycle 或大量临时 adapter。
• 机械按文件长度拆文件：不能降低 ownership 风险，反而会让搜索和回归更困难。
• 先改 Feishu projector 的视觉/卡片行为：这会触发 UI state-machine 和 card limits 的额外验证面，不适合作为结构性第一步。
• 给 orchestrator.Service 加全局锁：这会掩盖 daemon 串行边界问题，不解决 owner 不清晰。

推荐拆分结构

本 issue 应作为母 issue，拆出以下子 issue；推荐顺序如下。

子 issue A：收口 daemon VS Code/headless recovery 串行 pipeline

目标：把 onHello、onEvents、onDisconnect、onTick 中重复的 VS Code compatibility follow-up、VS Code prompt/recovery、headless recovery、surface resume sync 编排收成统一 locked runner。

非目标：不改变 recovery 策略，不改用户提示文案，不移动 orchestrator ownership。

验收：

• 入口不再各自手写同一组 recovery 组合。
• 修复 VS Code compatibility 异步刷新引发的 service race #712 相关 race 测试继续通过。
• go test ./internal/app/daemon -run 'VSCode|SurfaceResume|Headless' -count=1 通过。
• 若触及 remote surface 状态机，运行 remote-state-machine guardrail。

优先级：P1。

子 issue B：收口 daemon 持锁外调用 / async result contract

目标：盘点 daemon 内所有 a.mu.Unlock() 后执行 I/O 或启动 goroutine 的路径，建立统一 contract：background 只能产出 result/cache/follow-up；业务状态推进必须由 daemon serial runner 消费。

非目标：不重写全部 goroutine；先覆盖风险最高的 Feishu permission refresh、upgrade check、admin async UI follow-up、cron writeback、VS Code migration/apply。

验收：

• 有一份代码内或文档内的 async result contract。
• 高风险路径要么接入 serial runner，要么明确证明不触碰 orchestrator service/UI mutable state。
• 目标 race 测试和 daemon race smoke 通过。

优先级：P1，建议在 A 后做。

子 issue C：拆出 Feishu setup/autoconfig client facade

目标：把 app autoconfig、connection status、bot info、permission/scope 检测相关 API facade 从 runtime gateway 关注点中分离，服务 websetup/onboarding 后续迭代。

非目标：不改 websetup UI，不改配置流程语义，不改 LiveGateway runtime 行为。

验收：

• setup/autoconfig 调用入口不需要理解 LiveGateway runtime message/reaction tracking。
• go test ./internal/adapter/feishu ./internal/app/daemon -run 'Feishu|Onboarding|Setup|AutoConfig|Connection' -count=1 通过。
• 若改 docs/websetup 方案，另行触发页面/文档规则；本子单默认只做代码边界。

优先级：P2。

子 issue D：Projector cross-cutting operation builder 收口

目标：降低 projectEventBase switch 中重复 Operation 构造和跨切面处理遗漏风险，统一 reply lane、temporary session header、inline update、card envelope、theme fallback 的 builder。

非目标：不改变卡片视觉，不重做 projector 架构。

验收：

• 新增/现有 payload 构造路径复用统一 builder。
• Feishu projector 相关测试通过。
• 触发 Feishu card content / UI state-machine guardrail。

优先级：P2/P3，建议在 C 后做。

子 issue E：orchestrator runtime facade 与 contract tests

目标：在同包内逐步收口 s.turns、s.pickers、s.catalog、s.progress、claim map 的直接访问，形成 facade 方法和局部 contract tests，为未来包拆分做准备。

非目标：不跨包拆 orchestrator，不改变状态机语义。

验收：

• 选一个 runtime cluster 作为切片，例如 pickers 或 progress，减少直接 map 访问。
• 对应状态机 contract tests 覆盖 owner 边界。
• remote-state-machine guardrail 视触及路径决定是否运行。

优先级：P3；收益大但风险和工作量也最大，应在 A/B 降低 daemon 边界风险后推进。

拆分结构

本 issue 是母 issue，不直接编码。拆分为五个候选子 issue：

1. 子 issue A：收口 daemon VS Code/headless recovery 串行 pipeline。
2. 子 issue B：收口 daemon 持锁外调用 / async result contract。
3. 子 issue C：拆出 Feishu setup/autoconfig client facade。
4. 子 issue D：Projector cross-cutting operation builder 收口。
5. 子 issue E：orchestrator runtime facade 与 contract tests。

第一批只建议创建 A/B。C/D/E 等 A/B 边界稳定后再创建，避免母 issue 一次性制造过多待办。

当前执行点

深度调研已完成，当前母 issue 处于 status:needs-plan。下一步是创建子 issue A/B，并把链接和状态回卷到总调度表；随后从子 issue A 进入 prepare。

恢复步骤

1. 读取本 issue 的 总调度表 和 执行快照。
2. 如果子 issue A/B 还没有创建，先按 推荐拆分结构 创建。
3. 把子 issue 链接写回本 issue 的 总调度表。
4. 从子 issue A 开始运行 issue workflow prepare。
5. 只有子 issue A 达到 status:implementable-now 且 lint 通过后才开始编码。

推荐顺序

1. 子 issue A：daemon recovery pipeline。
2. 子 issue B：daemon async result contract。
3. 子 issue C：Feishu setup/autoconfig facade。
4. 子 issue D：Projector operation builder。
5. 子 issue E：orchestrator runtime facade。

A/B 是 correctness 风险优先；C/D 是影响面收敛；E 是长期结构治理。

可并行组

• A 和 B 不建议并行，二者都动 daemon serial/async 边界。
• C 可以与 A/B 并行，前提是不同时改 onboarding runtime apply 锁边界。
• D 可以与 C 并行度较低，因为都在 Feishu 包，建议顺序执行。
• E 不建议与 A/B 并行，因为 remote/recovery 状态机验证面会重叠。

当前风险

• 最大短期风险：daemon recovery/sync 编排继续分散，未来类似 修复 VS Code compatibility 异步刷新引发的 service race #712 的修复容易漏入口。
• 最大长期风险：orchestrator 子状态机继续横向增长，最终无法安全区分 queue/request/picker/progress 的 owner。
• 最大测试风险：大测试文件继续作为唯一保护面，导致后续重构难以定位失败边界。

目标

• 深度调研当前大包和高耦合点，形成分阶段、可验证、低风险的拆分方案。
• 明确哪些问题值得拆 issue，哪些暂时只需要 guardrail / 文档 / 测试边界。
• 优先降低后续功能修改引发 race、SSOT 漏同步、重复 fallback 和状态机回归的概率。

完成标准

• issue 内形成可执行的调研结论：风险排序、推荐拆分顺序、每个阶段的验收面。
• 明确第一批可开工子 issue，至少包含目标、非目标、涉及文件、验证方式和风险。
• 若发现需要产品侧决策的拆分边界，单独列为待决策；否则默认技术内部推进。
• 不要求本 issue 直接提交代码，除非调研中发现很小且确定的机械整理。

建议范围

1. 盘点三个风险包的职责边界、核心状态 owner、入口和输出。
2. 找出重复编排和高改动半径热点，尤其是 daemon ingress/tick/recovery pipeline。
3. 判断可安全先做的拆分：纯机械搬移、facade 提取、测试 helper 下沉、controller/runtimes owner 收口。
4. 输出拆分计划和子 issue 列表，优先选择低行为风险、能减少后续 race/SSOT 问题的工作。

执行决策

• 是否拆分：拆分。本 issue 作为母调研 issue，不直接承载所有实现。
• 当前执行单元：本轮调研已达到 research closure，并推进到 needs-plan；下一步应创建至少子 issue A/B，再选择第一子 issue 进入 execution closure。
• verifier：本 issue 只产出调研和子 issue，不强制代码 verifier；每个执行子 issue按自身规模决定 verifier。

实现参考

优先从子 issue A 开始，因为它最直接降低 race 和漏同步风险。实现时应保持行为不变，先抽 runner/helper，再通过现有 VS Code/SurfaceResume/Headless 测试证明等价。

检查参考

调研命令：

• go list -f '{{.ImportPath}} {{len .GoFiles}} {{len .TestGoFiles}}' ./...
• find internal/core/orchestrator internal/app/daemon internal/adapter/feishu -maxdepth 1 -name '*.go' -not -name '*_test.go' -print0 | xargs -0 wc -l | sort -nr
• rg -n '^func \(' internal/core/orchestrator internal/app/daemon internal/adapter/feishu --glob '*.go' --glob '!*_test.go'
• rg -n 'maybeRecoverVSCodeSurfacesLocked|maybePromptDetachedVSCodeSurfacesLocked|maybeRecoverHeadlessSurfacesLocked|syncSurfaceResumeState|syncWorkspaceSurfaceContextFilesLocked|syncClaudeWorkspaceProfileStateLocked|consumeVSCodeCompatibilityFollowupLocked' internal/app/daemon --glob '*.go' --glob '!*_test.go'

若后续进入实现子 issue，按触及逻辑分别触发 remote/Feishu UI state-machine guardrail。

收尾参考

• 本 issue 应保留母调研结论和子 issue 链接。
• 创建子 issue 后，把链接和状态回卷到本 issue 的总调度表。
• 若形成新的长期架构边界，考虑同步 docs/general/ 或相关 skill/AGENTS guardrail。

A/B 后重新评估

重新评估结论：实际情况没有偏离原计划，A/B 完成后 C 仍是下一优先级。

证据：

• daemon recovery pipeline 与 async result contract 已先完成，Feishu setup/autoconfig 不再与这两类 daemon 串行边界治理互相阻塞。
• connection_status.go、scopes.go、app_autoconfig*.go 仍在 internal/adapter/feishu 主包内，并共用 LiveGatewayConfig / FeishuCallBroker / Lark client，但这些路径不依赖 runtime gateway 的 message/reaction tracking、inbound routing 或 projector 状态。
• daemon setup/onboarding 当前仍直接调用 feishu.PlanAppAutoConfig / ApplyAppAutoConfig / PublishAppAutoConfig / GetLongConnectionStatus / GetBotInfo，适合先收口为 setup client/facade 语义。
• D 会触发 Feishu card/projector cross-cutting guardrail，E 会触发 orchestrator 状态机风险；二者仍应排在 C 后。

执行结果：已创建子 issue #716，作为 C 的执行单元。

A/B/C 后重新评估

重新评估结论：实际技术顺序没有偏离原计划；只有旧执行快照文字曾停在 #716 close-out，需要修正。C 完成后未发现必须先处理的 setup-client follow-up，D 仍是下一执行单元。

证据：

• feishu.SetupClient 与 daemon 单一 setup facade 已落地，feishuRuntime.setup 和分散 setup hook 已由结构测试防回归。
• projectEventBase 与相邻 projector 文件仍存在多处手写 Operation{...}、cardEnvelopeV2、rawCardDocument(...)、send/update 判定、reply lane 与 temporary session header 组合。
• D 的改动面集中在 Feishu projector/card operation construction，虽然会触发 Feishu card constraints/content/UI guardrail，但可通过“不改视觉/语义、只收口 builder”的执行边界控制风险。
• E 涉及 orchestrator runtime facade 与更多状态机 owner 边界，风险和验证面仍大于 D，继续排在 D 后。

执行结果：已创建子 issue #717，作为 D 的执行单元。

D 后重新评估

重新评估结论：E 不适合直接创建一个大范围 orchestrator runtime facade 执行单元。当前 s.turns / s.progress / s.pickers / s.catalog direct access 仍横跨多条状态机，若一次推进会把 queue、snapshot、compact、request cleanup、picker owner-flow 混成一个验证面。

第一执行切片选择 remote turn binding facade：

• pendingRemote / activeRemote 已经有一半逻辑集中在 service_queue_binding.go，比 progress 或 compact 更容易形成稳定执行闭包。
• 该切片直接服务 queue/dispatch ownership SSOT，能降低后续 route/queue 修改绕过清理逻辑的风险。
• pendingSteers、compactTurns、progress 暂不混入，后续按验证面另拆。

执行结果：已创建子 issue #718，作为 E 的第一执行单元。

E1 后重新评估

重新评估结论：E 的下一切片选择 compactTurns，不选择 progress 或 pendingSteers。

证据：

• compactTurns direct access 主要集中在 compact lifecycle 与少量 command binding，状态 owner 边界更清晰。
• progress 横跨 final text、plan snapshot、MCP progress、request cleanup 和 queue，验证面更大。
• pendingSteers 分布在 reply auto-steer 与 snapshot runtime，和用户追加输入/steer 恢复语义更近，适合 compact 后再单独切。

执行结果：已创建子 issue #719，作为 E 的第二执行单元。

E3 后重新评估

重新评估结论：progress 不适合作为一个整体执行单元，下一步应拆成更小的 progress 子切片；第一片选择 pendingTurnText / pendingPlanProposal。

证据：

• progress 当前同时覆盖 final text、plan proposal、plan snapshot、MCP tool progress、file change summary、turn diff snapshot 和 compact gating，直接开大单会把多套生命周期和验证面混在一起。
• pendingTurnText 与 pendingPlanProposal 同属 completed text item 暂存，direct access 集中在 queue completion、turn completed、cleanup 和 proposal presentation，能形成稳定执行闭包。
• MCP progress、plan snapshot、file change/diff 后续应按各自生命周期另拆，不混入 收口 orchestrator pending completed text/proposal facade #721。

执行结果：已创建子 issue #721，作为 E 的第四执行单元。

E4 后重新评估

重新评估结论：#721 完成后，progress 剩余 map 仍不应开大单；下一片选择 turnPlanSnapshots。

证据：

• turnPlanSnapshots direct access 集中在 plan update upsert/dedup 和 turn cleanup，验证面小于 MCP tool progress。
• MCP tool progress 牵涉 exec progress entry、final/non-final item progress 和 tool status，适合后续单独切。
• turnFileChanges / turnDiffSnapshots 已有较多 runtime method，是否还需要结构测试收口应后续再评估。

执行结果：已创建子 issue #722，作为 E 的第五执行单元。

E5 后重新评估

重新评估结论：#722 完成后，下一片选择 mcpToolCallProgress。

证据：

• mcpToolCallProgress direct access 集中在 upsert/dedup 与 cleanup，能形成稳定执行闭包。
• 它的验证面涉及 MCP tool progress 与 exec progress entry，但不必混入 file change / turn diff。
• turnFileChanges / turnDiffSnapshots 仍留待后续单独评估。

执行结果：已创建子 issue #723，作为 E 的第六执行单元。

总调度表

单元	状态	推荐顺序	说明	结果回卷	verifier 状态	当前结论
子 issue A：daemon recovery pipeline (#714)	已完成，commit 11c13f61	1	最高优先级，降低 race/漏同步风险	已收口为统一 runSurfaceRecoveryPipelineLocked；入口不再手写 VS Code/headless recovery 组合；G7 文档已同步	独立 verifier：pass	完成
子 issue B：daemon async result contract (#715)	已完成，commit a75fca62	2	依赖 #714 的 serial runner 边界更清晰	已建立 daemon async result queue；第一阶段高风险 async UI/service 回写路径已迁移	独立 verifier：pass	完成
子 issue C：Feishu setup/autoconfig facade (#716)	已完成，commit 328f93fa	3	A/B 后重新评估确认仍是下一优先级	已建立 feishu.SetupClient 与 daemon 单一 setup facade	独立 verifier：pass	完成
子 issue D：Projector operation builder (#717)	已完成，commit bf282ad2	4	Feishu card constraints/content/UI guardrail 已复核；行为等价收口	已建立 newEventCardOperation，收口普通 card Operation 构造；Snapshot reply-lane 漂移已由回归测试锁住	独立 verifier：pass	完成
子 issue E1：remote turn binding facade (#718)	已完成，commit 76d8d90f	5	E 不直接开大单，先切 pending/active remote binding facade	已收口 pending/active remote binding direct map access 到 runtime/service facade	独立 verifier：pass	完成
子 issue E2：compact turn binding facade (#719)	已完成，commit 5658199d	6	继续治理 serviceTurnRuntime，只切 compact lifecycle，不混入 pendingSteers/progress	已收口 compactTurns direct map access 到 compact facade	独立 verifier：pass	完成
子 issue E3：pending steer binding facade (#720)	已完成，commit 8575f9e9	7	继续治理 serviceTurnRuntime，只切 pendingSteers，不混入 progress	已收口 pendingSteers direct map access 到 runtime/service facade	独立 verifier：pass	完成
子 issue E4：pending completed text/proposal facade (#721)	已完成，commit 4e10614c	8	progress 不开大单，先切 pendingTurnText/pendingPlanProposal	已收口 pending completed text/proposal direct map access 到 runtime/service facade	独立 verifier：pass	完成
子 issue E5：turn plan snapshot facade (#722)	已完成，commit e25a9d80	9	继续拆小 progress，只切 turnPlanSnapshots	已收口 turnPlanSnapshots direct map access 到 runtime/service facade	独立 verifier：pass	完成
子 issue E6：MCP tool call progress facade (#723)	已完成，commit 186cf634	10	继续拆小 progress，只切 mcpToolCallProgress	已收口 mcpToolCallProgress direct map access 到 runtime/service facade	独立 verifier：pass	完成
子 issue E7：remaining progress maps guard (#724)	已完成，commit bb7de26e	11	剩余 progress map 已有 runtime helper，只补结构防回归和 owner 命名	已为 turnFileChanges / turnDiffSnapshots 补结构测试并重命名 owner 文件	独立 verifier：pass	完成
子 issue E8：item buffer facade (#725)	已完成，commit c7e626c6	12	同型底层 map 外传问题，切 itemBuffers	已收口 itemBuffers direct map access 到 Service facade	独立 verifier：pass	完成
子 issue E9：route claim map facade (#726)	已完成，commit 25705de4	13	route ownership 核心 carrier，切 claim map owner	已收口 workspace/instance/thread claim map direct access 到 claim owner/facade	独立 verifier：pass	完成
子 issue E10：catalog runtime availability facade (#727)	已完成，commit 7b83af68	14	小切片，收口 catalog 内部字段可用性判断	已收口 catalog persistedThreads direct field check 到 runtime facade	独立 verifier：pass	完成

执行快照

• 当前阶段：execution orchestration
• 当前执行点：子 issue A/收口 daemon VS Code/headless recovery 串行 pipeline #714、B/收口 daemon async result contract #715、C/拆出 Feishu setup/autoconfig client facade #716、D/收口 Feishu projector card Operation builder #717、E1/收口 orchestrator remote turn binding facade #718、E2/收口 orchestrator compact turn binding facade #719、E3/收口 orchestrator pending steer binding facade #720、E4/收口 orchestrator pending completed text/proposal facade #721、E5/收口 orchestrator turn plan snapshot facade #722、E6/收口 orchestrator MCP tool call progress facade #723、E7/收口剩余 progress file change / turn diff 结构防回归 #724、E8/收口 orchestrator item buffer facade #725、E9/收口 orchestrator route claim map facade #726、E10/收口 orchestrator catalog runtime 内部字段访问 #727 均已完成并关闭；已完成当前结构治理阶段复核
• 已完成：规模量化、风险包识别、热点路径扫描、推荐拆分结构、推荐顺序、可并行关系、非目标确认；收口 daemon VS Code/headless recovery 串行 pipeline #714/收口 daemon async result contract #715/拆出 Feishu setup/autoconfig client facade #716/收口 Feishu projector card Operation builder #717/收口 orchestrator remote turn binding facade #718/收口 orchestrator compact turn binding facade #719/收口 orchestrator pending steer binding facade #720/收口 orchestrator pending completed text/proposal facade #721/收口 orchestrator turn plan snapshot facade #722/收口 orchestrator MCP tool call progress facade #723/收口剩余 progress file change / turn diff 结构防回归 #724/收口 orchestrator item buffer facade #725/收口 orchestrator route claim map facade #726/收口 orchestrator catalog runtime 内部字段访问 #727 均已完成并回卷结果；剩余 pickers/surfaceUIRuntime 扫描未发现同等优先级的底层 map 外传或跨 owner direct access 问题
• 下一步：执行 parent verifier / close-plan，若通过则关闭本母 issue
• 当前阻塞：无产品决策阻塞；全部是技术内部拆分
• 最后一致状态：master 已推送到 7b83af68；所有已创建子 issue 均已关闭并回卷；本 issue 已达到当前结构治理阶段收口点
• 未完成尾项：parent verifier、close-plan、finish --close
• 恢复步骤：读取本 issue，确认 收口 daemon VS Code/headless recovery 串行 pipeline #714-收口 orchestrator catalog runtime 内部字段访问 #727 均已关闭并回卷；运行 parent close-plan/finish --close

低优先级待办

• 后续可考虑增加一个 repo health 脚本，定期输出大包文件数、方法数、超长测试文件和热点包趋势；当前不作为第一批执行单元。

子 issue 回卷

子 issue #714 已完成并关闭，结果回卷如下：

• 完成内容：daemon VS Code/headless recovery 串行编排已收口为统一 runSurfaceRecoveryPipelineLocked；onHello、onEvents、onDisconnect、onTick 与 stamped /mode vscode 后续恢复不再各自手写 recovery 组合。
• SSOT 边界：consumeVSCodeCompatibilityFollowupLocked 只消费 async follow-up 标记，不再直接运行 prompt/recovery primitives；实际 prompt/recovery 统一由 surface recovery pipeline 执行。
• 验证：目标结构测试、VS Code/SurfaceResume/Headless 回归、目标 race 测试、go test ./internal/app/daemon -count=1、go test ./...、文件长度与 diff check 均通过。
• verifier：独立 verifier 结果为 pass。
• durable knowledge：docs/general/remote-surface-state-machine.md 的 G7 VSCodeCompatibilityBlocked 已同步统一 pipeline 边界。
• commit：11c13f61。
• 后续：收口 daemon async result contract #715 已从依赖阻塞解锁为 status:implementable-now，下一步推进 daemon async result contract。

子 issue #715 已完成并关闭，结果回卷如下：

• 完成内容：建立 daemon async result queue，background goroutine 只提交 daemonAsyncResult；实际 UI/service mutation 由 daemon 串行入口或 queued drain 在 a.mu 下消费。
• 第一阶段迁移范围：release upgrade check、dev upgrade check、upgrade start progress/failure/restarting、standalone Codex upgrade completion、admin web external link result、cron background command result。
• SSOT 边界：删除未使用的非 locked UI queue 便捷入口；保留通用 result enqueue 与 locked UI queue，避免新增重复入口。
• 未扩大范围：Feishu permission refresh 仍按 isolated runtime/cache 分类；Feishu runtime apply retry 仍按 request-scoped sync path 分类，留待后续 setup/autoconfig facade 阶段重新评估。
• 验证：结构测试、Upgrade/Cron/Admin/CodexUpgrade 目标回归、目标 race smoke、daemon 回归、go test ./...、文件长度与 diff check 均通过。
• verifier：独立 verifier 结果为 pass。
• commit：a75fca62。
• 后续：A/B 已完成，下一步应重新评估是否创建 C/D/E；优先建议 C：Feishu setup/autoconfig facade。

子 issue #716 已完成并关闭，结果回卷如下：

• 完成内容：新增 feishu.SetupClientConfig / feishu.SetupClient / NewSetupClient，把 setup/admin API helper 从 runtime LiveGateway 语义中分离。
• Adapter 边界：GetBotInfo、GetLongConnectionStatus、ListAppScopes、PlanAppAutoConfig、ApplyAppAutoConfig、PublishAppAutoConfig 都已有 SetupClient method；旧 exported functions 保留薄桥接以兼容现有调用面。
• Daemon 边界：新增单一 daemonFeishuSetupFacade，收敛 plan/apply/publish/long-connection/describe-app 调用；移除 feishuRuntime.setup、旧 feishuSetupClient runtime field 和多个分散包级 hook。
• SSOT 防回归：新增 adapter 结构测试和 daemon 结构测试，防止旧函数重新承载实现或 daemon 重新引入多套 setup hook。
• 未扩大范围：未改 websetup UI、onboarding 产品步骤、LiveGateway.Start / Apply runtime 行为，也未触碰 projector/card payload。
• 验证：adapter facade 目标测试、daemon setup/onboarding 目标测试、adapter+daemon 包级回归、go test ./...、文件长度与 diff check 均通过。
• verifier：独立 verifier 结果为 pass。
• commit：328f93fa。
• 后续：A/B/C 已完成，下一步重新评估 D/E 是否创建；优先建议 D，除非先发现 setup client 还有小的独立 follow-up。

子 issue #717 已完成实现与 verifier，结果回卷如下：

• 完成内容：新增 newEventCardOperation / eventCardOperationSpec，统一普通 card operation 的基础字段、send/update 判定、reply lane、temporary session header、card envelope 与 raw card document 构造。
• 迁移范围：projectEventBase 中 Snapshot / Notice / PlanUpdate / Selection / Page / Request / PathPicker / TargetPicker 普通 card payload，以及 projectExecCommandProgress、projectThreadHistory 的同类 send/update path。
• 行为保护：reply lane 改为 ApplyReplyLane 显式 opt-in，保留 Snapshot 状态卡顶层发送语义；新增 TestProjectSnapshotIgnoresExplicitReplyLane 防止统一 builder 再次引入行为漂移。
• 保留边界：text/image/reaction/delete 非 card operation 继续手写；final reply 专用 card document 与 final/exec transport-size probe 继续保留手写临时 op，避免改变 markdown split 与预算测量语义。
• Guardrail：Feishu card API constraints、content context、UI state-machine 已复核；未改变 callback payload、inline replace、old-card/freshness 或卡片内容 contract，不需要更新 canonical docs。
• 验证：结构测试红灯/绿灯、projector 目标回归、adapter 包回归、go test ./...、Feishu guardrail 聚焦包测试、文件长度与 diff check 均通过。
• verifier：独立 verifier 结果为 pass。
• commit：bf282ad2。
• 后续：收口 Feishu projector card Operation builder #717 close 后重新评估 E：orchestrator runtime facade。

子 issue #718 已完成实现与 verifier，结果回卷如下：

• 完成内容：新增 serviceTurnRuntime pending/active remote binding facade，并新增 Service 级语义 helper，收口 queue/dispatch/snapshot 相关 remote binding 查询和写入。
• 迁移范围：service_dispatch_core.go、service_queue.go、service_autowhip.go、service_autocontinue.go、service_compact.go、service_snapshot_query.go、service_snapshot_binding.go、service_snapshot_runtime.go、service_reply_auto_steer.go。
• SSOT 防回归：新增 TestRemoteTurnBindingMapsStayBehindFacade，禁止非 owner/facade 文件直接访问 s.turns.pendingRemote / s.turns.activeRemote。
• 保留边界：pendingSteers、compactTurns、progress、picker/catalog runtime 未混入本切片。
• Guardrail：remote-state-machine guardrail 已复核；未改变 attach/use/follow/new、queue dispatch、request gate、compact、interrupt 或 command availability 语义，不需要更新 canonical doc。
• 验证：结构测试红灯/绿灯、queue/dispatch/remote/snapshot 目标测试、orchestrator 包、daemon/control/orchestrator 聚焦包、go test ./...、文件长度与 diff check 均通过。
• verifier：独立 verifier 结果为 pass。
• commit：76d8d90f。
• 后续：收口 orchestrator remote turn binding facade #718 close 后重新评估 E 的下一切片，候选为 pendingSteers / compactTurns / progress facade。

子 issue #719 已完成实现与 verifier，结果回卷如下：

• 完成内容：新增 compact facade helper，收口 compact command id binding 与 compact completion notice 对 compactTurns 的直接访问。
• SSOT 防回归：新增 TestCompactTurnBindingMapStaysBehindFacade，禁止非 owner/facade 文件直接访问 .turns.compactTurns。
• 保留边界：service_compact.go 继续作为 compact lifecycle owner/facade；pendingSteers、pending/active remote binding、progress runtime 未混入本切片。
• Guardrail：remote-state-machine guardrail 已复核；未改变 /compact busy 判断、owner card lifecycle、dispatch failure restore、command rejected restore、problem handling、completion notice 或 queue dispatch 状态迁移，不需要更新 canonical doc。
• 验证：结构测试红灯/绿灯、compact/queue/dispatch/remote/snapshot 目标测试、orchestrator 包、daemon/control/orchestrator 聚焦包、go test ./...、文件长度与 diff check 均通过。
• verifier：独立 verifier 结果为 pass。
• commit：5658199d。
• 后续：收口 orchestrator compact turn binding facade #719 close 后重新评估 E 的下一切片，候选为 pendingSteers 或 progress facade。

子 issue #720 已完成并关闭，结果回卷如下：

• 完成内容：新增 pending steer binding facade，收口 pendingSteers 的 bind/get/delete/iterate、command binding、instance/surface pending 判断和 restore key 查询。
• 迁移范围：reply auto-steer、/steerall / surface action、command ack/reject、dispatch failure restore、snapshot restore、surface/instance pending query。
• SSOT 防回归：新增 TestPendingSteerBindingMapStaysBehindFacade，禁止非 owner/facade 文件直接访问 .turns.pendingSteers；测试断言也改走 facade helper。
• 保留边界：progress、pending/active remote binding、compactTurns、picker/catalog runtime 未混入本切片。
• Guardrail：remote-state-machine guardrail 已复核；未改变 steering overlay、turn.steer ack/restore、disconnect restore、command matrix 或用户可见语义，不需要更新 canonical doc。
• 验证：结构测试红灯/绿灯、steer/queue/dispatch/remote/snapshot 目标测试、orchestrator 包、daemon/control/orchestrator 聚焦包、go test ./...、文件长度与 diff check 均通过。
• verifier：独立 verifier 结果为 pass。
• commit：8575f9e9。
• 后续：收口 orchestrator pending steer binding facade #720 close 后重新评估 E 后续是否继续拆 progress facade。

子 issue #721 已完成并关闭，结果回卷如下：

• 完成内容：新增 pending completed text/proposal facade，收口 pendingTurnText / pendingPlanProposal 的 store/get/take/delete/cleanup。
• 迁移范围：completed agent text 暂存、completed plan item proposal 暂存、turn completed final text 读取、turn artifact cleanup、instance removal cleanup、plan proposal 测试断言。
• SSOT 防回归：新增 TestProgressPendingTextMapsStayBehindFacade，禁止非 owner/facade 文件直接访问 .progress.pendingTurnText / .progress.pendingPlanProposal。
• 保留边界：turnPlanSnapshots、mcpToolCallProgress、turnFileChanges、turnDiffSnapshots、exec progress card、MCP progress 和 compact gating 未混入本切片。
• Guardrail：remote-state-machine guardrail 已复核；未改变 completed plan item、final output、turn completed 或用户可见语义，不需要更新 canonical doc。
• 验证：结构测试红灯/绿灯、final text / turn completed / plan proposal / queue / cleanup 目标测试、orchestrator 包、daemon/control/orchestrator 聚焦包、go test ./...、文件长度与 diff check 均通过。
• verifier：独立 verifier 结果为 pass。
• commit：4e10614c。
• 后续：收口 orchestrator pending completed text/proposal facade #721 close 后重新评估 E 后续是否继续拆剩余 progress map。

子 issue #722 已完成并关闭，结果回卷如下：

• 完成内容：新增 turn plan snapshot facade，收口 turnPlanSnapshots 的 upsert/dedup 与 cleanup。
• 迁移范围：plan update dedup/upsert、turn completed cleanup、clear turn artifacts。
• SSOT 防回归：新增 TestProgressPlanSnapshotMapStaysBehindFacade，禁止非 owner/facade 文件直接访问 .progress.turnPlanSnapshots。
• 保留边界：mcpToolCallProgress、turnFileChanges、turnDiffSnapshots、completed plan proposal handoff 未混入本切片。
• Guardrail：remote-state-machine guardrail 已复核；未改变 plan update、completed plan item、提案计划或用户可见语义，不需要更新 canonical doc。
• 验证：结构测试红灯/绿灯、plan update / turn completed / routing cleanup 目标测试、orchestrator 包、daemon/control/orchestrator 聚焦包、go test ./...、文件长度与 diff check 均通过。
• verifier：独立 verifier 结果为 pass。
• commit：e25a9d80。
• 后续：收口 orchestrator turn plan snapshot facade #722 close 后重新评估 E 后续是否继续拆剩余 progress map。

子 issue #723 已完成并关闭，结果回卷如下：

• 完成内容：新增 MCP tool call progress facade，收口 mcpToolCallProgress 的 duplicate check、store 和 cleanup。
• 迁移范围：MCP tool call progress handler、turn completed cleanup、instance removal cleanup、clear turn artifacts cleanup。
• SSOT 防回归：新增 TestProgressMCPToolCallProgressMapStaysBehindFacade，禁止非 owner/facade 文件直接访问 .progress.mcpToolCallProgress。
• 保留边界：MCP progress payload、exec progress entry、final/non-final 判断、Feishu card 表现、request gate/MCP approval/tool callback 语义未改变；turnFileChanges / turnDiffSnapshots 未混入本切片。
• Guardrail：remote-state-machine guardrail 已复核；未改变 route/state transition 或用户可见语义，不需要更新 canonical doc。
• 验证：结构测试红灯/绿灯、MCP/progress/routing/snapshot 目标测试、orchestrator 包、daemon/control/orchestrator 聚焦包、go test ./...、文件长度与 diff check 均通过。
• verifier：独立 verifier 结果为 pass。
• commit：186cf634。
• 后续：收口 orchestrator MCP tool call progress facade #723 close 后重新评估 progress 剩余 turnFileChanges / turnDiffSnapshots 是否需要继续结构测试 facade。

子 issue #724 已完成并关闭，结果回卷如下：

• 完成内容：为 turnFileChanges / turnDiffSnapshots 补齐结构测试，并将 owner 文件重命名为 service_progress_file_change.go / service_progress_turn_diff.go。
• 迁移范围：仅文件命名和结构测试；生产代码逻辑 100% rename，无行为 diff。
• SSOT 防回归：新增 TestProgressFileChangeMapStaysBehindFacade 与 TestProgressTurnDiffMapStaysBehindFacade，禁止非 owner/facade 文件直接访问 .turnFileChanges / .turnDiffSnapshots。
• 保留边界：file change summary、turn diff snapshot、turn completed final output、Feishu card、routing/request 行为未改变。
• Guardrail：未改变 route/state transition 或用户可见语义，不需要更新 canonical doc。
• 验证：结构测试红灯/绿灯、file change / turn diff / turn completed 目标测试、orchestrator 包、daemon/control/orchestrator 聚焦包、go test ./...、文件长度与 diff check 均通过。
• verifier：独立 verifier 结果为 pass。
• commit：bb7de26e。
• 后续：收口剩余 progress file change / turn diff 结构防回归 #724 close 后重新评估 调研核心大包与高耦合结构拆分方案 #713 是否已达到当前结构治理阶段收口点。

子 issue #725 已完成并关闭，结果回卷如下：

• 完成内容：新增 item buffer facade，收口 itemBuffers 的 get/delete/cleanup，并移除底层 map 参数 helper。
• 迁移范围：item completion、turn completed cleanup、instance removal cleanup、clear turn artifacts cleanup。
• SSOT 防回归：新增 TestItemBufferMapStaysBehindFacade，禁止非 owner/facade 文件直接访问 .itemBuffers。
• 保留边界：item delta/completed 渲染、file_change、dynamic tool call、image generation、context compaction、plan proposal、final turn output、claims/route/request gate 语义未改变。
• Guardrail：未改变 route/state transition 或用户可见语义，不需要更新 canonical doc。
• 验证：结构测试红灯/绿灯、item/file/tool/image/compact/plan/turn completed/routing/snapshot 目标测试、orchestrator 包、daemon/control/orchestrator 聚焦包、go test ./...、文件长度与 diff check 均通过。
• verifier：独立 verifier 结果为 pass。
• commit：c7e626c6。
• 后续：收口 orchestrator item buffer facade #725 close 后重新评估 调研核心大包与高耦合结构拆分方案 #713 是否已达到当前结构治理阶段收口点。

子 issue #726 已完成并关闭，结果回卷如下：

• 完成内容：新增 route claim facade，收口 workspaceClaims / instanceClaims / threadClaims 的非 owner direct access。
• 迁移范围：route transition 中的 claim 写入、instance disconnect/remove cleanup，以及 raw workspace claim lookup 的 owner 文件归属。
• SSOT 防回归：新增 TestRouteClaimMapsStayBehindFacade，禁止非 owner/facade 文件直接访问 .workspaceClaims / .instanceClaims / .threadClaims。
• 保留边界：attach/detach/use/follow/new、workspace/instance/thread conflict、route transition、surface resume、headless recovery、queue dispatch、request gate 语义未改变。
• Guardrail：remote-state-machine guardrail 已复核；未改变状态图或用户可见语义，不需要更新 canonical doc。
• 验证：结构测试红灯/绿灯、claim/route/attach/detach/workspace/thread/headless/snapshot/disconnect/remove 目标测试、orchestrator 包、daemon/control/orchestrator 聚焦包、go test ./...、文件长度与 diff check 均通过。
• verifier：独立 verifier 结果为 pass。
• commit：25705de4。
• 后续：收口 orchestrator route claim map facade #726 close 后重新评估 调研核心大包与高耦合结构拆分方案 #713 是否已达到当前结构治理阶段收口点。

子 issue #727 已完成并关闭，结果回卷如下：

• 完成内容：新增 serviceCatalogRuntime.hasPersistedThreads()，收口非 owner 文件对 catalog 内部字段的可用性判断。
• 迁移范围：persisted recent threads merge、persisted thread view、workspace selection recency。
• SSOT 防回归：新增 TestCatalogRuntimeFieldsStayBehindFacade，禁止非 owner 文件直接访问 .catalog.persistedThreads* / .catalog.persistedWorkspaces。
• 保留边界：persisted thread/workspace 查询、缓存、fallback、backend filtering、thread merge、workspace selection、target picker 行为未改变。
• Guardrail：未改变状态机或用户可见语义，不需要更新 canonical doc。
• 验证：结构测试红灯/绿灯、catalog/persisted/thread/workspace/target picker/surface selection 目标测试、orchestrator 包、daemon/control/orchestrator 聚焦包、go test ./...、文件长度与 diff check 均通过。
• verifier：独立 verifier 结果为 pass。
• commit：7b83af68。
• 后续：收口 orchestrator catalog runtime 内部字段访问 #727 close 后重新评估 调研核心大包与高耦合结构拆分方案 #713 是否已达到当前结构治理阶段收口点。

E 阶段收口复核

#727 关闭后重新扫描 runtime direct access，结论如下：

• progress 已按子切片完成 pending text/proposal、plan snapshot、MCP progress、file change、turn diff 的 owner/facade 或结构测试收口。
• itemBuffers 已完成底层 map 外传收口。
• route claim maps 已完成 owner/facade 收口，并通过 remote-state-machine guardrail 复核。
• catalog runtime 剩余内部字段可用性判断已收口。
• pickers 剩余访问主要是 next*Token / consumer/filter lookup/register 等 runtime method 调用，不是内部 map direct access；当前不建议为“调用 runtime method”继续拆机械子单。
• surfaceUIRuntime direct access 集中在 service_ui_runtime.go owner 文件；当前不建议只为已在 owner 内的 map 访问继续开子单。

当前判断：#713 的本轮结构治理已达到可收口状态。后续若继续做更大拆包，应另开新母 issue 重新调研，而不是在本母 issue 内无限延伸。

[kxn]

#713 深度调研已完成并推进到 status:needs-plan。

本轮完成：

• 写入大包/高耦合量化证据。
• 写入风险排序、推荐拆分结构、推荐顺序、可并行组和当前风险。
• 创建第一批子 issue：
  • 收口 daemon VS Code/headless recovery 串行 pipeline #714 收口 daemon VS Code/headless recovery 串行 pipeline
  • 收口 daemon async result contract #715 收口 daemon async result contract
• 回卷 收口 daemon VS Code/headless recovery 串行 pipeline #714/收口 daemon async result contract #715 到母 issue 总调度表。

当前结论：先推进 #714；#715 阻塞于 #714 完成后的 serial runner 边界。

[kxn]

继续推进 #713：已确认母 issue 当前调度结论仍有效。

下一执行单元是 #714；#713 本身保持 status:needs-plan 作为母调度 issue，不直接编码。本次释放 #713 processing，随后进入 #714 prepare。