GCWing · limityan · May 30, 2026 · May 30, 2026
diff --git a/AGENTS-CN.md b/AGENTS-CN.md
@@ -18,7 +18,7 @@ BitFun 是一个由 Rust workspace 与 React 前端组成的项目。
 | 模块 | 路径 | Agent 文档 |
 |---|---|---|
 | Core（产品逻辑） | `src/crates/core` | [AGENTS.md](src/crates/core/AGENTS.md) |
-| 已拆出的 core 支撑 crate | `src/crates/{core-types,agent-stream,runtime-ports,terminal,tool-runtime}` | （使用 core 指南） |
+| 已拆出的 core 支撑 crate | `src/crates/{core-types,agent-stream,runtime-ports,runtime-services,terminal,tool-runtime}` | （使用 core 指南） |
 | Service core owner crate | `src/crates/services-core` | [AGENTS.md](src/crates/services-core/AGENTS.md) |
 | Service integrations owner crate | `src/crates/services-integrations` | [AGENTS.md](src/crates/services-integrations/AGENTS.md) |
 | Agent tool contracts | `src/crates/agent-tools` | [AGENTS.md](src/crates/agent-tools/AGENTS.md) |

diff --git a/AGENTS.md b/AGENTS.md
@@ -18,7 +18,7 @@ Repository rule: **keep product logic platform-agnostic, then expose it through
 | Module | Path | Agent doc |
 |---|---|---|
 | Core (product logic) | `src/crates/core` | [AGENTS.md](src/crates/core/AGENTS.md) |
-| Extracted core support | `src/crates/{core-types,agent-stream,runtime-ports,terminal,tool-runtime}` | (use core guide) |
+| Extracted core support | `src/crates/{core-types,agent-stream,runtime-ports,runtime-services,terminal,tool-runtime}` | (use core guide) |
 | Service core owner crate | `src/crates/services-core` | [AGENTS.md](src/crates/services-core/AGENTS.md) |
 | Service integrations owner crate | `src/crates/services-integrations` | [AGENTS.md](src/crates/services-integrations/AGENTS.md) |
 | Agent tool contracts | `src/crates/agent-tools` | [AGENTS.md](src/crates/agent-tools/AGENTS.md) |

diff --git a/Cargo.toml b/Cargo.toml
@@ -5,6 +5,7 @@ members = [
     "src/crates/ai-adapters",
     "src/crates/agent-stream",
     "src/crates/runtime-ports",
+    "src/crates/runtime-services",
     "src/crates/services-core",
     "src/crates/services-integrations",
     "src/crates/product-domains",

diff --git a/docs/architecture/agent-runtime-services-design.md b/docs/architecture/agent-runtime-services-design.md
@@ -1,8 +1,9 @@
 # Agent Runtime SDK 与 Runtime Services 设计
 
 本文是 [`core-decomposition.md`](core-decomposition.md) 的开发设计文档，描述目标模块、
-接口、crate 内部结构和迁移保护。本文中的 `bitfun-runtime-services`、
-`bitfun-agent-runtime`、`bitfun-harness` 是目标 crate；在实际创建前不得把它们当作
+接口、crate 内部结构和迁移保护。`bitfun-runtime-services` 已建立 PR1 基础壳层，
+当前只承载 typed service bundle、builder、provider registry、capability availability 和
+fake provider；`bitfun-agent-runtime`、`bitfun-harness` 仍是目标 crate，在实际创建前不得把它们当作
 已完成事实。
 
 ## 1. 设计目标与边界
@@ -20,7 +21,7 @@
 bitfun-core-types
 bitfun-events
 bitfun-runtime-ports
-bitfun-runtime-services      # 目标
+bitfun-runtime-services      # PR1 基础壳层
 bitfun-agent-tools
 tool-runtime
 bitfun-agent-runtime         # 目标
@@ -68,8 +69,7 @@ tool-runtime
 
 bitfun-runtime-services
   -> bitfun-runtime-ports
-  -> bitfun-core-types
-  -> bitfun-events
+  -> bitfun-core-types / bitfun-events（仅当 service DTO 或 event contract 需要时引入）
 
 具体 service crates
   -> bitfun-runtime-ports
@@ -87,10 +87,10 @@ bitfun-runtime-services
 - `bitfun-agent-runtime` -> Tauri / CLI / ACP protocol / Web UI
 - `bitfun-harness` -> 具体 filesystem / Git / terminal manager
 
-目标 crate 创建准入：
+目标 crate 创建或继续扩展准入：
 
 - 只有当 owner 边界、旧路径兼容、focused tests、依赖收益和 boundary check 都能同时落地时，才创建新的目标 crate。
-- `bitfun-runtime-services` 的创建前提是 typed builder 至少承载本地 service、remote service 和 fake provider 三类注入路径。
+- `bitfun-runtime-services` 已按该准入建立基础壳层；继续扩展时仍必须保持 typed builder、本地 service、remote service 和 fake provider 三类注入路径可测试。
 - `bitfun-agent-runtime` 的创建前提是 session / turn / scheduler / prompt loop 中至少一个 owner 可以脱离 `bitfun-core` 构建，并有旧路径 facade。
 - `bitfun-harness` 的创建前提是至少两个 workflow 可以通过 provider contract 注册，例如 Deep Review 与 MiniApp / DeepResearch。
 - 若目标 crate 只能承接单个 helper 或只能通过 `bitfun-core` 才能测试，继续留在迁移期 facade，不提前拆 crate。
@@ -157,7 +157,7 @@ pub trait WorkspacePort: Send + Sync {
 
 ### 2.2 Runtime Services
 
-目标 crate：`bitfun-runtime-services`。
+当前 crate：`bitfun-runtime-services`。
 
 职责：
 

diff --git a/docs/architecture/core-decomposition.md b/docs/architecture/core-decomposition.md
@@ -323,7 +323,7 @@ flowchart TB
 | 注册器 / 组装点 | 所属目标层级 | 目标或迁移期模块 | 注册内容 |
 |---|---|---|---|
 | `ProductAssembler` / `ProductAssemblyPlan` | 产品组装层（Product Assembly） | 迁移期在 `bitfun-core` facade 或产品入口；目标可收敛为 assembly owner | `DeliveryProfile`、`CapabilitySet`、feature group、provider 选择 |
-| `RuntimeServicesBuilder` | 运行时服务层（Runtime Services） | 目标 `bitfun-runtime-services`；迁移期连接 `bitfun-runtime-ports`、`bitfun-services-*` 和 `bitfun-core` service wiring | filesystem、workspace、session store、Git、terminal、network、MCP catalog、remote connection / workspace / projection port |
+| `RuntimeServicesBuilder` | 运行时服务层（Runtime Services） | `bitfun-runtime-services` PR1 基础壳层；迁移期连接 `bitfun-runtime-ports`、`bitfun-services-*` 和 `bitfun-core` service wiring | filesystem、workspace、session store、Git、terminal、network、MCP catalog、remote connection / workspace / projection port |
 | `ToolRuntimeBuilder` | 工具运行时（Tool Runtime） | `tool-runtime`、`bitfun-agent-tools`、`bitfun-tool-packs` | tool provider、tool pack、manifest、permission gate、tool hook |
 | `HarnessRegistryBuilder` | 工作流编排层（Harness Layer） | 目标 `bitfun-harness`；迁移期在 `bitfun-core` 和产品能力代码中 | SDD、Deep Review、DeepResearch、MiniApp 等 harness provider |
 | `AgentDefinitionRegistry` | Agent 运行时 SDK（Agent Runtime SDK） | 目标 `bitfun-agent-runtime`；迁移期在 `bitfun-core` agent definition 代码中 | agent、subagent、prompt module、skill definition |

diff --git a/docs/plans/core-decomposition-plan.md b/docs/plans/core-decomposition-plan.md
@@ -38,10 +38,10 @@
 - SSH、relay、本地隧道、远端 OS 差异、认证方式属于具体 Remote provider。
 - remote workspace、terminal pre-warm、scheduler submit、session restore、file chunk / image fallback 等行为必须用等价测试保护。
 
-### 2.4 目标 crate 创建准入
+### 2.4 目标 crate 创建或扩展准入
 
 - 新目标 crate 不能为了“架构完整”提前创建。必须同时满足 owner 边界清晰、旧路径兼容可保留、focused tests 可落地、依赖收益可解释、boundary check 可防回流。
-- `bitfun-runtime-services` 优先级最高，但创建前必须先有最小 `RuntimeServicesBuilder` skeleton、Remote ports 和 fake provider 测试。
+- `bitfun-runtime-services` 已按该准入建立基础壳层；继续扩展时仍必须保持 `RuntimeServicesBuilder` skeleton、Remote ports 和 fake provider 测试同时成立。
 - `bitfun-agent-runtime` 只能在 session / turn / scheduler / prompt loop 中至少一个 owner 可脱离 `bitfun-core` 构建时创建。
 - `bitfun-harness` 只能在至少两个 workflow 通过 provider contract 接入时创建，不能只为单个 Deep Review 或 MiniApp helper 拆 crate。
 - 若某项迁移只能承接单个 helper，或测试仍必须依赖完整 `bitfun-core`，继续留在迁移期 facade。
@@ -60,17 +60,31 @@
 
 ## 4. 后续迁移队列
 
-| 顺序 | 主题 | 完整范围 | 不允许混入 | 合入门禁 |
+后续迁移固定收敛为 7 个大块 PR。每个 PR 都必须先补保护，再迁移 owner，最后回看文档和边界；如果发现必须改变功能语义，需要在 PR 中单独说明原因、影响范围和回滚边界。
+
+| PR | 主题 | 完整范围 | 不允许混入 | 合入门禁 |
 |---|---|---|---|---|
-| 0 | Product Assembly / Runtime Services Foundation | 建立最小 Product Assembly skeleton、`RuntimeServicesBuilder` skeleton、Remote ports、fake provider 和 boundary check 入口 | 具体 remote runtime、tool IO、product-domain IO、default feature 调整 | provider 注册路径可测试，Remote ports 不暴露 SSH / relay concrete handle |
-| 1 | Service / Agent Remote Runtime Owner | 在 remote connection、remote workspace、remote FS / terminal projection、workspace-root / persistence、`ImageContextData`、remote-SSH / relay provider 中选择一个 owner 主题，完成 port、provider、旧路径兼容和行为等价验证 | tool runtime、product-domain runtime、feature matrix、产品命令或 UI 行为变更 | remote/session/file/image/terminal/scheduler 行为等价，产品 surface 不变 |
-| 2 | Agent Runtime SDK Owner | 拆分 mode-scoped subagent visibility、agent registry facts、queue policy decision、scheduler submit/cancel facts 和 background delivery 边界；concrete scheduler 生命周期按保护程度逐步外移 | remote provider、tool IO、product-domain IO、默认 feature 调整 | subagent 可见性、queue/preempt/cancel、background reply、DeepResearch hook 等价 |
-| 3 | Harness / Product Capability Boundary | 建立 Harness provider contract，让 Deep Review、DeepResearch、MiniApp 等 workflow 通过 provider 注册，不侵入 Agent Runtime SDK | concrete service IO、tool IO、surface 命令语义变更 | 至少两个 workflow 可通过 provider contract 表达，旧路径兼容 |
-| 4 | Product-Domain Runtime Owner | MiniApp filesystem IO / worker / host / builtin seed 或 function-agent Git/AI 中选择一个 owner 主题，建立最小 port/provider 和 core adapter | tool runtime、service/agent runtime、surface 行为变更 | MiniApp/function-agent focused regression，PathManager/process/Git/AI 边界清晰 |
-| 5 | Tool Runtime Owner | 仅在收益明确时迁移 `ToolUseContext` projection、manifest execution、`GetToolSpecTool` execution、snapshot wrapper、collapsed unlock state 或具体工具 IO 中的一个 owner 主题 | service/agent runtime、product-domain runtime、feature matrix、产品行为变更 | tool visibility、manifest、`GetToolSpec`、snapshot、Deep Review tool flow 等价 |
-| 6 | Feature / Build-Benefit Evaluation | 评估 feature matrix、dependency profile、no-default 编译面和构建收益数据 | runtime owner 迁移、default feature 副作用、构建脚本变更 | cargo metadata / cargo tree 证据，产品入口完整能力不变 |
-
-当前优先级更偏向 **Product Assembly / Runtime Services Foundation**，随后进入 **Service / Agent Remote Runtime Owner**。原因是 Remote 与 OS/terminal/file/network 的实现边界最容易继续牵引 core，但必须先有 typed registration 和 Remote ports，避免继续临时接线。
+| PR1 | Product Assembly / Runtime Services Foundation | 创建 `bitfun-runtime-services`，补 `RuntimeServicesBuilder`、typed provider registration、capability availability、Remote ports、fake provider 和 boundary check 入口 | 具体 remote runtime、tool IO、product-domain IO、default feature 调整 | provider 注册路径可测试，Remote ports 不暴露 SSH / relay concrete handle，新增 crate 不依赖 `bitfun-core` |
+| PR2 | Service / Agent Remote Runtime Owner | 在 remote connection、remote workspace、remote FS / terminal projection、workspace-root / persistence、`ImageContextData`、remote-SSH / relay provider 中完成一个完整 owner 主题的 port、provider、旧路径兼容和行为等价验证 | tool runtime、product-domain runtime、feature matrix、产品命令或 UI 行为变更 | remote/session/file/image/terminal/scheduler 行为等价，产品 surface 不变 |
+| PR3 | Agent Runtime SDK Owner | 拆分 mode-scoped subagent visibility、agent registry facts、queue policy decision、scheduler submit/cancel facts 和 background delivery 边界；concrete scheduler 生命周期按保护程度逐步外移 | remote provider、tool IO、product-domain IO、默认 feature 调整 | subagent 可见性、queue/preempt/cancel、background reply、DeepResearch hook 等价 |
+| PR4 | Harness / Product Capability Boundary | 建立 Harness provider contract，让 Deep Review、DeepResearch、MiniApp 等 workflow 通过 provider 注册，不侵入 Agent Runtime SDK | concrete service IO、tool IO、surface 命令语义变更 | 至少两个 workflow 可通过 provider contract 表达，旧路径兼容 |
+| PR5 | Product-Domain Runtime Owner | MiniApp filesystem IO / worker / host / builtin seed 或 function-agent Git/AI 中完成一个完整 owner 主题，建立最小 port/provider 和 core adapter | tool runtime、service/agent runtime、surface 行为变更 | MiniApp/function-agent focused regression，PathManager/process/Git/AI 边界清晰 |
+| PR6 | Tool Runtime Owner | 在 `ToolUseContext` projection、manifest execution、`GetToolSpecTool` execution、snapshot wrapper、collapsed unlock state 或具体工具 IO 中完成一个收益明确的完整 owner 主题 | service/agent runtime、product-domain runtime、feature matrix、产品行为变更 | tool visibility、manifest、`GetToolSpec`、snapshot、Deep Review tool flow 等价 |
+| PR7 | Feature / Build-Benefit Evaluation | 评估 feature matrix、dependency profile、no-default 编译面和构建收益数据，确认是否具备收敛默认 feature 的条件 | runtime owner 迁移、default feature 副作用、构建脚本变更 | cargo metadata / cargo tree 证据，产品入口完整能力不变 |
+
+### 4.1 PR1 具体实施计划
+
+PR1 是后续高风险迁移的前置门禁，目标是提供可测试的 typed assembly 基础，而不是移动任何既有业务行为。
+
+1. 新建 `bitfun-runtime-services` crate，并加入 workspace。
+2. 在 `bitfun-runtime-ports` 中补齐 Runtime Services 所需的轻量 port trait 和 Remote port trait；这些 trait 只能描述能力和请求边界，不携带 SSH、relay、Tauri、process、filesystem manager 等 concrete handle。
+3. 在 `bitfun-runtime-services` 中实现 `RuntimeServices`、`RuntimeServicesBuilder`、capability availability、typed unsupported error 和 provider registry。
+4. 提供 `test_support` fake provider，覆盖本地 mandatory service、optional remote service 和 unsupported capability 三类注入路径。
+5. 更新 `scripts/check-core-boundaries.mjs`，把 `bitfun-runtime-services` 纳入 no-core dependency 和轻量依赖边界检查。
+6. 更新仓库入口文档中的模块索引，说明 `bitfun-runtime-services` 仍使用 core decomposition guardrails。
+7. 运行 focused tests、边界检查和最小 Rust 验证；提交前从第三方视角检查是否出现 service locator、全局 mutable registry、反向依赖或功能语义漂移。
+
+PR1 不迁移任何 concrete service owner，因此预期不会修改产品行为、默认能力集合、权限语义、工具曝光、事件语义、session 生命周期或构建脚本。
 
 ## 5. 每类 PR 的保护重点
 

diff --git a/scripts/check-core-boundaries.mjs b/scripts/check-core-boundaries.mjs
@@ -14,6 +14,7 @@ const noCoreDependencyCrates = [
   'ai-adapters',
   'agent-stream',
   'runtime-ports',
+  'runtime-services',
   'services-core',
   'services-integrations',
   'agent-tools',
@@ -84,6 +85,34 @@ const lightweightBoundaryRules = [
       'syntect-tui',
     ],
   },
+  {
+    crateName: 'runtime-services',
+    reason: 'runtime-services must stay a typed service assembly contract without concrete runtime implementations',
+    forbiddenDeps: [
+      'bitfun-core',
+      'bitfun-ai-adapters',
+      'bitfun-agent-stream',
+      'bitfun-services-core',
+      'bitfun-services-integrations',
+      'bitfun-agent-tools',
+      'bitfun-tool-packs',
+      'bitfun-product-domains',
+      'bitfun-transport',
+      'terminal-core',
+      'tool-runtime',
+      'tauri',
+      'reqwest',
+      'git2',
+      'rmcp',
+      'image',
+      'tokio-tungstenite',
+      'bitfun-cli',
+      'ratatui',
+      'crossterm',
+      'arboard',
+      'syntect-tui',
+    ],
+  },
   {
     crateName: 'agent-tools',
     reason: 'agent-tools must not depend on concrete service or product runtime implementations',
@@ -215,6 +244,35 @@ const dependencyProfileRules = [
       'syntect-tui',
     ],
   },
+  {
+    crateName: 'runtime-services',
+    profileName: 'default runtime service assembly profile',
+    reason: 'runtime-services default profile must not compile concrete service or product runtime implementations',
+    forbiddenNonOptionalDeps: [
+      'bitfun-core',
+      'bitfun-ai-adapters',
+      'bitfun-agent-stream',
+      'bitfun-services-core',
+      'bitfun-services-integrations',
+      'bitfun-agent-tools',
+      'bitfun-tool-packs',
+      'bitfun-product-domains',
+      'bitfun-transport',
+      'terminal-core',
+      'tool-runtime',
+      'tauri',
+      'reqwest',
+      'git2',
+      'rmcp',
+      'image',
+      'tokio-tungstenite',
+      'bitfun-cli',
+      'ratatui',
+      'crossterm',
+      'arboard',
+      'syntect-tui',
+    ],
+  },
   {
     crateName: 'agent-tools',
     profileName: 'tool contract-only profile',
@@ -6730,6 +6788,21 @@ function runManifestParserSelfTest() {
   if (!runtimePortsProfile?.forbiddenNonOptionalDeps.includes('bitfun-services-core')) {
     throw new Error('runtime-ports dependency profile must forbid service implementations');
   }
+  const runtimeServicesRule = lightweightBoundaryRules.find(
+    (rule) => rule.crateName === 'runtime-services',
+  );
+  if (!runtimeServicesRule?.forbiddenDeps.includes('bitfun-core')) {
+    throw new Error('runtime-services lightweight boundary must forbid bitfun-core');
+  }
+  if (!runtimeServicesRule?.forbiddenDeps.includes('bitfun-services-integrations')) {
+    throw new Error('runtime-services lightweight boundary must forbid concrete service integrations');
+  }
+  const runtimeServicesProfile = dependencyProfileRules.find(
+    (rule) => rule.crateName === 'runtime-services',
+  );
+  if (!runtimeServicesProfile?.forbiddenNonOptionalDeps.includes('tool-runtime')) {
+    throw new Error('runtime-services dependency profile must forbid tool runtime implementations');
+  }
   const agentToolsManifestRule = forbiddenContentUnderRules.find(
     (rule) => rule.path === 'src/crates/agent-tools/src',
   );
@@ -6827,6 +6900,28 @@ function runManifestParserSelfTest() {
         'subagent_context_mode_preserves_fork_wire_value',
       ],
     },
+    {
+      path: 'src/crates/runtime-services/src/lib.rs',
+      contracts: [
+        'RuntimeServices',
+        'RuntimeServicesBuilder',
+        'CapabilityAvailability',
+        'RuntimeServicesProvider',
+        'RuntimeServicesRegistry',
+        'CapabilityMismatch',
+        'require_capability',
+      ],
+    },
+    {
+      path: 'src/crates/runtime-services/tests/runtime_services_contracts.rs',
+      contracts: [
+        'builder_requires_mandatory_runtime_services',
+        'fake_provider_registers_required_and_remote_services_through_registry',
+        'missing_optional_capability_returns_typed_unsupported_error',
+        'capability_availability_reports_optional_service_status_without_side_effects',
+        'builder_rejects_port_registered_under_the_wrong_capability',
+      ],
+    },
     {
       path: 'src/crates/core/src/agentic/subagent_runtime/mod.rs',
       contracts: [