跟踪 core runtime 架构拆解闭环

[limityan]

1. 核心目标

将 bitfun-core 从承载大量 concrete runtime / product logic 的中心模块，逐步收敛为兼容层与产品组装入口。重构完成后，核心能力应按稳定接口、runtime owner、product capability 和产品入口分层组合，避免不同交付形态都被迫依赖全量底层实现。

目标依赖方向：

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

本重构不以新增 crate 数量为目标。每次 owner 迁移都必须同时减少、迁移或显著简化既有 core 路径，并保持旧路径兼容和产品行为等价。

2. 重构方案

• 接口与实现分离：下层只暴露 typed ports、DTO、event facts、capability availability 和 hook contracts；具体 filesystem、terminal、Git、AI、MCP、remote、Tauri 等实现由上层组装注册。
• Product Assembly 负责组装：不同平台、产品形态和交付形态通过组装器选择 provider 和 capability，不把平台 handle 或 app state 下沉到 runtime owner。
• Owner crate 承接真实逻辑：Agent Runtime、Runtime Services、Tool Runtime、Harness、Product Domains 只迁移可被测试证明等价的事实、策略、状态机或 runtime 决策。
• Core 保留兼容层：在迁移期保留旧 import path、adapter、具体 IO 接线和产品入口兼容，避免一次性大改导致功能漂移。
• Feature / 构建收益后置：只有 owner 边界稳定后，才评估 default feature、no-default build、交付形态裁剪和构建收益。

3. 关键阶段

阶段	目标	准出要求
分层与 owner 基线	明确 core、runtime services、agent runtime、tool runtime、harness、product domains 的边界	文档、AGENTS、boundary check 与实际代码一致
低风险 owner 收敛	迁移纯策略、DTO、manifest、catalog、facts、状态派生和无副作用决策	focused tests 证明旧行为等价，旧路径继续可用
高风险 runtime 迁移	逐步迁移 scheduler、event、permission、tool execution、remote、MiniApp、function-agent 等 concrete runtime owner	先补等价保护，再移动实现；不得混入用户可见行为变更
Harness / capability 组装	将多步骤 workflow、capability pack 和 hook/event contract 纳入可扩展组装体系	hook 顺序、错误策略、timeout、权限和旧路径兼容均可测
Feature / 构建收益评估	基于稳定 owner 边界评估 feature matrix、依赖裁剪和构建收益	使用 cargo metadata / cargo tree / build check 数据证明收益与风险

4. 质量保护

• 每个 owner 迁移必须有旧路径兼容、focused regression、boundary check 和最小必要 build/check 证据。
• 涉及权限、工具曝光、session 生命周期、scheduler 时序、remote workspace、MiniApp worker / host、Git / AI provider 的变更，必须先补可观测等价测试。
• Runtime / contract crate 不允许吸收 Tauri、app state、process execution、network client、Git provider、AI provider 等 concrete dependency，除非该 crate 明确就是 concrete integration owner。
• 文档只维护稳定设计和活跃计划；已完成事实归档，避免计划文档继续膨胀为流水账。
• 如果发现需要改变功能逻辑、权限边界、事件语义、工具 schema 或交付形态，必须单独评审，不能伪装成结构重构。

5. 主要风险

风险	控制方式
只新增抽象，旧逻辑仍留在 core，导致代码膨胀	owner PR 必须迁移或简化现有路径；纯 facade / guard 不算完成
边界模糊，runtime owner 反向依赖 core 或平台实现	boundary check、cargo tree、AGENTS 和 crate feature 持续约束
高风险路径迁移导致功能降级或时序漂移	先迁移 facts / decisions，再迁移 lifecycle；无法证明等价则暂停
为追求构建收益提前裁剪 feature	feature / build-benefit 只在 owner 稳定后处理
不同产品形态遗漏 provider 或 capability	Product Assembly 必须显式注册能力，并验证桌面、CLI、server、remote 等入口的能力范围
文档与代码漂移	每次阶段性变更只更新 plan / completed / issue 状态；设计文档仅在目标设计变化时更新

6. 完成标准

• bitfun-core 不再是 concrete runtime 和产品能力的默认聚合点，而是兼容 facade 与组装入口。
• Agent Runtime、Runtime Services、Tool Runtime、Harness、Product Domains 均可通过稳定接口独立承接对应 owner 逻辑。
• 不同平台和交付形态可以通过 feature 或 Product Assembly 最小化依赖，而不影响既有功能范围。
• 高风险路径均具备等价保护、旧路径兼容和明确回滚边界。
• 构建收益、依赖裁剪和 feature matrix 有数据证明，且没有功能降级、权限漂移或性能劣化。

7. Issue 生命周期

本 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 描述中列出。

[limityan]

PR4 已提交：#989。

本次完成范围：

• 新增 bitfun-harness，作为 Harness Layer 的 provider-neutral contract crate，承接 workflow descriptor、route plan、outcome/error 和 registry wiring。
• 在 bitfun-core::agentic::harness 注册 Deep Review、DeepResearch、MiniApp 三个 legacy-facade provider，满足至少两个 workflow 可通过 provider contract 表达的 PR4 准入。
• 将 bitfun-harness 纳入 boundary check，禁止依赖 bitfun-core、具体 service crate、product-domain implementation、AI adapter、transport、Tauri、Git/MCP/image/WebSocket runtime deps、CLI/TUI 或 concrete tool pack。
• 更新架构、详细设计、执行计划、已完成归档和 AGENTS 文档，明确 PR4 只完成 contract / registry boundary。

明确未完成边界：

• Deep Review、DeepResearch、MiniApp 的 concrete workflow execution 未迁移。
• legacy_facade provider 只生成旧路径 route plan，execute 仍返回 unsupported；这用于防止误判为执行语义已外移。
• Product command registry、capability pack、Harness 对 Tool Runtime / Runtime Services 的实际 orchestration 仍属于后续迁移。

验证：

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

该 issue 继续保持打开，等待后续 Product-Domain Runtime、Tool Runtime、Feature / Build-Benefit Evaluation，以及单独保护后的 Harness execution / Product Capability pack 迁移。

[limityan]

PR5 已提交：#991

本次完成内容：

• 在 bitfun-product-domains 中补齐 MiniApp / function-agent typed runtime service view。
• MiniApp dependency install 已通过 runtime port 路由，保留 worker process、pool.stop、state persistence、事件发送等旧路径语义。
• function-agent Git/AI facade 改为通过 service view 组装，concrete Git command、AI provider acquisition、AI transport error mapping 仍在 core adapter。
• 更新了 boundary check、架构文档、执行计划和 product-domains AGENTS 文档，明确 PR5 的完成边界。

仍未关闭的后续边界：

• MiniApp filesystem IO、worker process、host dispatch、builtin asset seed / marker IO 仍在 core / app adapter。
• function-agent Git/AI concrete adapter 与 provider acquisition 仍在 core。
• 后续重点仍是 Tool Runtime owner、Feature / Build-Benefit Evaluation，以及需要单独保护的更深 Product-Domain concrete provider 或 Harness execution / Product Capability pack 迁移。

本 issue 继续保持打开，等完整架构迁移闭环后再关闭。

[limityan]

更新 #991：本次 PR 已重做为文档纠偏，不再提交 Product-Domain runtime service-view 代码。

关键变化：

• 移除本轮“只新增 service view / facade / boundary 锚点”的代码尝试，不将其计入 PR5 完成。
• 明确新增抽象的准入标准：必须同时删除、迁移或显著简化既有代码路径，否则只能作为计划说明，不能算 runtime owner 迁移。
• 主计划收敛为剩余 PR5-PR7：Product-Domain Runtime 实迁移复核、Tool Runtime 真实 owner 迁移、Feature / Build-Benefit Closure。
• Product-Domain Runtime 需要先证明可迁移的完整 owner 候选；若无法减少旧路径复杂度，应明确跳过代码迁移。

该 issue 保持打开，后续会继续按关联 PR 更新迁移状态、风险和计划变化。

[limityan]

迁移进展更新：PR #1030

本次 PR 完成 Agent Runtime Kernel Closure 的一块实际 owner 迁移：

• 将 prompt-loop 中不依赖 workspace / remote / config IO 的纯事实迁入 bitfun-agent-runtime：UserContextPolicy、UserContextSection、ToolListingSections、PrependedPromptReminders。
• bitfun-core 仅保留旧路径 re-export 和具体 PromptBuilder 组装逻辑，避免调用方 import 路径漂移。
• 增加 bitfun-agent-runtime contract tests 与 boundary check，防止这些 prompt facts 回流 core。
• 同步更新架构、计划、完成归档和模块 AGENTS 文档，明确“prompt-loop 纯事实已迁移，concrete prompt assembly / workspace context IO / prompt cache 协调仍未迁移”。

保护与验证：

• cargo test -p bitfun-agent-runtime
• cargo test -p bitfun-core --features product-full prompt -- --nocapture
• cargo check -p bitfun-core --features product-full
• cargo check -p bitfun-core --no-default-features
• node scripts/check-core-boundaries.mjs
• pnpm run check:repo-hygiene
• git diff --check

后续仍保持 issue 打开，继续按全局里程碑推进 concrete scheduler lifecycle、prompt module / prompt cache contract、runtime events、permission coordination、Product-Domain Runtime 和 Tool Runtime 剩余主体迁移。

[limityan]

文档维护口径更新

本次对 PR #1030 做了补充调整：architecture / design 文档不再承载每个 PR 的完成状态或过程日志。

后续维护规则：

• docs/architecture/core-decomposition.md 和 docs/architecture/agent-runtime-services-design.md 只描述稳定分层、接口归属、行为边界、风险与目标态判定口径。
• PR 是否完成、已迁移项、待迁移项和阶段范围通过 docs/plans/core-decomposition-plan.md、docs/plans/core-decomposition-completed.md 与本 issue 维护。
• 只有当目标分层、接口归属、行为边界或关键风险判断需要修正时，才修改 architecture / design 文档。

这个口径用于防止设计文档随着每次 PR 膨胀，也避免把阶段性完成状态误写成长期架构事实。