跟踪 core runtime 架构拆解闭环

[limityan]

背景

Core 拆解已经从低风险的类型抽取、compatibility facade 和 owner container 建立，进入高风险的 runtime owner 迁移阶段。PR #964 建立了当前架构基线和后续执行计划：

• docs/architecture/core-decomposition.md：描述当前架构快照、目标分层、接口与实现分离、Product Assembly 注册模型、provider 分类和主要风险。
• docs/architecture/agent-runtime-services-design.md：描述 Agent Runtime SDK、Runtime Services、Tool Runtime、Harness、Product Capabilities、typed service injection、Remote ports、hooks/events 和验证策略。
• docs/plans/core-decomposition-plan.md：描述活跃迁移节奏、剩余 owner 队列、目标 crate 创建准入、暂停条件和验证矩阵。
• docs/plans/core-decomposition-completed.md：归档历史已完成内容，避免活跃计划继续膨胀为流水账。

本 Issue 用于跟踪 PR #964 之后的整体架构优化，确保后续实现 PR 按文档中的分层、边界和验证策略推进，而不是退化为零散重构补丁。

关联 PR

当前文档基线：

• docs(architecture): clarify runtime decomposition layers #964

历史关键 core 拆解和 runtime owner 工作：

• P0/P1/P2 保护线与 owner container：refactor(core): finalize P1 decomposition safeguards #635、refactor(core): move service integrations to owner crate #680、Refactor core owner contracts for Remote SSH and MCP #684、Harden core decomposition service boundaries #694、docs(core): close low-risk decomposition prep #789
• Tool / runtime contract 抽取：refactor(agent-tools): extract tool manifest contracts #770、refactor(tools): move GetToolSpec presentation contracts #785、refactor(tools): move generic runtime assembly contracts #810、refactor(tools): add catalog runtime facades #811、refactor(tools): complete H1 provider boundary #815、refactor(agent-tools): own portable tool runtime contracts #837、refactor(core): centralize tool context runtime bindings #839、refactor(runtime): move tool context owner boundary #884
• Product-domain 与 MiniApp / function-agent 边界：refactor(miniapp): move builtin contracts to product domains #784、refactor(product-domains): move function agent response policy #817、refactor(miniapp): move runtime decisions to product domains #885
• Feature / dependency 与 product-full 保护：refactor(runtime): centralize core runtime owners #824、refactor(core): tighten feature-gated runtime facade #826、refactor(core): narrow no-default dependency profile #832、refactor(core): prepare high-risk runtime owner migration #841
• Service / Agent 与 Remote runtime owner 准备：refactor(runtime): centralize service agent adapters #877、refactor: move local filesystem owner to services-core #891、refactor(runtime-ports): extract dialog and subagent contracts #924、refactor(runtime-ports): complete HR-C contract closure #935、refactor(remote-connect): move runtime presentation policies #938、refactor(remote-connect): move service agent runtime assembly #941、refactor(runtime-ports): move scheduler queue decisions #942、refactor(remote-connect): migrate command orchestration owner #946

架构目标

将 bitfun-core 逐步收敛为 compatibility facade 和 product assembly point，而不是继续作为不断膨胀的 runtime owner。目标依赖方向为：

Product Surfaces -> Product Assembly / Capabilities -> Harness / Tool Runtime / Agent Runtime SDK -> Runtime Services -> Stable Contracts / External providers

目标不是简单增加 crate 数量。每个新增 owner 边界都必须减少 concrete dependency 压力，让行为更容易验证，并防止产品形态、平台实现或具体 service 细节继续向下泄漏。

工作范围

1. Product Assembly / Runtime Services Foundation

   • 建立最小 typed registration 路径，用于注册 runtime services 和 providers。
   • 建立 Remote connection、workspace、projection、capability facts ports。
   • 增加 fake provider 测试支撑和 boundary check 入口。
   • 本阶段不迁移 concrete remote runtime、tool IO、product-domain IO，不调整 default features 或构建脚本。

2. Service / Agent Remote Runtime Owner

   • 从 remote connection、remote workspace、remote FS / terminal projection、workspace-root / persistence、ImageContextData、remote-SSH 或 relay provider 中选择完整 owner 主题逐步迁移。
   • 保留旧路径兼容，并验证 remote / session / file / image / terminal / scheduler 行为等价。

3. Agent Runtime SDK Owner

   • 将 session、dialog turn、model round、scheduler / queue / cancel、prompt loop、subagent registry facts、background delivery、permission coordination 和 runtime events 隔离到稳定契约之后。
   • 在 facts、queue policy 和 compatibility tests 落地前，不直接迁移 concrete scheduler 生命周期。

4. Harness / Product Capability Boundary

   • 为 Deep Review、DeepResearch、MiniApp 等 workflow 建立 provider contract，避免它们成为 Agent Runtime SDK 的内部逻辑。
   • Hook 必须具备明确顺序、timeout、错误策略和行为等价保护。

5. Product-Domain Runtime Owner

   • MiniApp 或 function-agent 的 IO-adjacent ownership 只能通过明确 ports / providers 迁移。
   • pure domain state 和 decision logic 必须与 filesystem / Git / AI concrete call 分离。

6. Tool Runtime Owner

   • 继续从 portable facts、manifest / catalog snapshots、GetToolSpec、snapshot wrappers、permission gates 和 result normalization 推进。
   • 没有 prompt-visible manifest 与 permission 等价测试前，不迁移大范围 concrete tool execution。

7. Feature / Build-Benefit Evaluation

   • owner 边界稳定后，再评估 dependency profile、no-default 编译面、feature matrix 和实测构建收益。
   • runtime owner 迁移 PR 不混入 default feature、release 形态或构建脚本调整。

分阶段风险与质量门禁

阶段	主要风险	质量保护
Product Assembly / Runtime Services Foundation	组装层变成新的 service locator，Remote ports 过早暴露具体 SSH / relay / OS handle	先定义 typed builder、fake provider、capability availability 和 Remote port 边界；provider 注册路径可测试，boundary check 覆盖新边界
Service / Agent Remote Runtime Owner	remote workspace、terminal pre-warm、scheduler submit、file / image fallback 时序漂移	迁移前固定 wire shape、restore 顺序、workspace-root / persistence 读取路径和旧 facade；补 remote product surface 验证
Agent Runtime SDK Owner	scheduler 生命周期、subagent 可见性、background delivery 或 permission coordination 发生功能偏移	先迁移 facts、queue policy decision 和事件 facts；保留 concrete lifecycle 在旧路径，验证 queue / cancel / background reply / hook 等价
Harness / Product Capability Boundary	Harness 抽象过度，或 workflow provider 反向依赖 concrete service	至少两个 workflow 验证 provider contract；hook 必须有顺序、timeout、错误策略和 snapshot 保护
Product-Domain Runtime Owner	domain crate 吸收 filesystem、Git、AI、process concrete IO	先定义最小 port / provider 与 core adapter；MiniApp / function-agent focused regression 和 boundary check 必须覆盖 concrete IO 回流
Tool Runtime Owner	prompt-visible manifest、permission、GetToolSpec 或 collapsed unlock state 不等价	固定 manifest / catalog snapshot、permission decision 和 result rendering baseline；验证 tool visibility、snapshot 和 Deep Review tool flow
Feature / Build-Benefit Evaluation	为追求构建收益提前减少能力或调整 release shape	只在 owner 边界稳定后评估；用 cargo metadata / cargo tree / check 前后数据证明收益，default feature 或构建脚本调整单独评审

任何阶段如果需要改变用户可见行为、权限语义、产品命令、默认能力、release 形态或跨 owner 同时迁移，应暂停当前 PR 并拆出单独评审。

保护线

• 架构重构不得改变用户可见行为、权限语义、工具曝光、事件语义、session 生命周期或产品命令。
• 新目标 crate 必须同时满足：owner 边界清晰、旧路径兼容、focused tests 可落地、依赖收益可解释、boundary check 可防回流。
• Runtime、Tool 和 Harness 层只消费 interfaces 或 registries，不直接创建 filesystem、terminal、MCP、ACP、remote host 或 platform managers。
• Product Assembly 可以注册 concrete providers，但不能变成 untyped service locator 或 global mutable app state。
• Remote connection interface 必须与具体 remote OS / SSH / relay / tunnel 实现保持可拆分。
• Desktop、CLI、Server、Remote、ACP、Web、mobile / relay 等产品入口必须保持当前能力集合，除非单独通过产品行为 PR 明确变更。

验证要求

每个实现 PR 按活跃计划选择最小但足够的验证集合；触碰高风险路径时补充对应验证：

• Contract / DTO / docs：pnpm run check:repo-hygiene，crate 依赖变化时补 boundary checks。
• Runtime ports / services：owner focused tests，加 cargo check -p bitfun-core --features product-full。
• Remote product surfaces：按范围验证 Desktop remote connect、relay / mobile session、ACP remote config reuse、CLI subagent 或 remote-adjacent path。
• Tool runtime：验证 manifest、permission、GetToolSpec、snapshot 和 Deep Review tool flow 等价。
• Product-domain runtime：补 MiniApp 或 function-agent focused regressions。
• 大范围 owner 迁移：执行 cargo check --workspace；行为面较广时补 cargo test --workspace。

完成标准

• bitfun-core 对已迁移区域只保留 compatibility facade 和 product assembly 责任。
• Agent Runtime SDK、Runtime Services、Tool Runtime、Harness、Product Capabilities 和 Concrete Integrations 之间具备可检查的单向依赖边界。
• 至少一组低层 contract / owner crate 可以绕开完整 bitfun-core 和对应 heavy dependency 独立构建与测试。
• 现有产品入口在每次迁移后保持相同的行为和能力集合。
• Remote、Tool、MiniApp / function-agent、scheduler / registry 等高风险路径具备等价测试、旧路径兼容和回滚边界。
• 已完成事实持续归档到 completed 文档，活跃计划只保留当前方向和剩余工作。

Issue 生命周期

• 本 Issue 在完整架构迁移达到上述完成标准前保持打开。
• 单个实现 PR 合入时不要关闭本 Issue，只更新对应范围、状态、风险和剩余工作。
• 如果关联 PR 改变迁移顺序、范围边界、风险评估、验证策略或完成标准，需要同步更新本 Issue 和相关架构 / 计划文档。
• 只有剩余 runtime owner 迁移、product capability boundaries、feature / build-benefit evaluation 和文档化验证门禁全部完成，或被正式架构决策明确替代后，才关闭本 Issue。

[limityan]

PR1 已提交：#975

本次状态更新：

• 已完成 Product Assembly / Runtime Services Foundation 的基础实现：新增 bitfun-runtime-services、typed builder、provider registry、capability availability、fake provider 和 focused tests。
• 已把后续迁移计划收敛为 PR1-PR7，并在 docs/plans/core-decomposition-plan.md 中细化 PR1 的实施门禁。
• 当前没有迁移 concrete runtime owner，不改变产品行为、默认能力集合、权限语义、工具曝光、事件语义、session 生命周期或构建脚本。
• 设计说明：bitfun-runtime-services 当前保持最小依赖，仅依赖 bitfun-runtime-ports、async-trait、thiserror；bitfun-core-types / bitfun-events 保留为后续 service DTO 或 event contract 需要时才引入的允许依赖，避免 PR1 提前扩大依赖面。
• 对抗性审查中发现并修复了 provider capability mismatch 风险；builder 现在会拒绝字段类型正确但 port 自报 capability 错误的注入。

已验证：

• cargo test -p bitfun-runtime-services
• cargo test -p bitfun-runtime-ports
• node scripts/check-core-boundaries.mjs
• pnpm run check:repo-hygiene
• git diff --check gcwing/main..HEAD
• cargo check -p bitfun-core --features product-full
• cargo check --workspace

下一阶段仍按计划进入 PR2：Service / Agent Remote Runtime Owner。该 Issue 继续保持打开，后续根据关联 PR 更新迁移状态和计划调整。

[limityan]

PR2 + PR3 合并实现已提交：#978

本次进展：

• PR2：remote workspace/session/file-projection 的稳定 owner contract 已迁入 bitfun-runtime-ports，bitfun-services-integrations::remote_connect 保留旧路径 re-export；具体 SSH / relay / terminal pre-warm / session restore / scheduler submit 仍留在 core。
• PR3：新增 bitfun-agent-runtime，当前只承接 scheduler/background delivery 的纯决策；concrete scheduler lifecycle、session manager、prompt loop、subagent registry 和 post-turn hook 未外移。
• 已同步更新 plan、架构文档、AGENTS 边界说明和 scripts/check-core-boundaries.mjs，避免把未完成迁移误描述为已完成。

风险与保护：

• 未修改产品命令、UI、默认 feature、release / fast build 脚本或产品能力集合。
• 提交前已按第三方对抗视角检查依赖方向、旧路径兼容、行为等价、性能额外开销和文档一致性；发现并修复了 background delivery action 暴露无意义 submission policy 的 API 风险。
• GitHub Actions CI run #1859 已通过：Frontend Build、Windows / Ubuntu / macOS Rust checks 全部成功。
• 本 issue 保持 open，后续会继续按关联 PR 更新迁移状态，不在 refactor: add runtime owner boundaries #978 合并时关闭。

验证命令已在 PR 描述中列出。