refactor(core): layer crates and close product assembly facade

AGENTS-CN.md

@@ -13,39 +13,29 @@ BitFun 是一个由 Rust workspace 与 React 前端组成的项目。
 3. 修改 Rust 文件后，优先使用 `pnpm run fmt:rs`，只格式化已改动或已暂存的 `.rs` 文件。只有在你明确需要更大范围格式化时才使用 `cargo fmt`。
 4. 改完后按下方表格执行与改动范围匹配的最小验证。
 
-## 模块索引
-
-| 模块 | 路径 | Agent 文档 |
-|---|---|---|
-| Core（产品逻辑） | `src/crates/core` | [AGENTS.md](src/crates/core/AGENTS.md) |
-| Core 共享 DTO | `src/crates/core-types` | [AGENTS.md](src/crates/core-types/AGENTS.md) |
-| 事件契约 | `src/crates/events` | [AGENTS.md](src/crates/events/AGENTS.md) |
-| Agent stream 归一化 | `src/crates/agent-stream` | [AGENTS.md](src/crates/agent-stream/AGENTS.md) |
-| Runtime ports | `src/crates/runtime-ports` | [AGENTS.md](src/crates/runtime-ports/AGENTS.md) |
-| Runtime services | `src/crates/runtime-services` | [AGENTS.md](src/crates/runtime-services/AGENTS.md) |
-| Terminal 基础设施 | `src/crates/terminal` | [AGENTS.md](src/crates/terminal/AGENTS.md) |
-| 底层 tool runtime | `src/crates/tool-runtime` | [AGENTS.md](src/crates/tool-runtime/AGENTS.md) |
-| Agent runtime owner crate | `src/crates/agent-runtime` | [AGENTS.md](src/crates/agent-runtime/AGENTS.md) |
-| Harness workflow contracts | `src/crates/harness` | [AGENTS.md](src/crates/harness/AGENTS.md) |
-| 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) |
-| Tool pack provider plan | `src/crates/tool-packs` | [AGENTS.md](src/crates/tool-packs/AGENTS.md) |
-| 产品领域 crate | `src/crates/product-domains` | [AGENTS.md](src/crates/product-domains/AGENTS.md) |
-| 产品能力包 | `src/crates/product-capabilities` | [AGENTS.md](src/crates/product-capabilities/AGENTS.md) |
-| Transport 适配层 | `src/crates/transport` | [AGENTS.md](src/crates/transport/AGENTS.md) |
-| API layer | `src/crates/api-layer` | [AGENTS.md](src/crates/api-layer/AGENTS.md) |
-| ACP 集成 | `src/crates/acp` | [AGENTS.md](src/crates/acp/AGENTS.md) |
-| AI adapters | `src/crates/ai-adapters` | [AGENTS.md](src/crates/ai-adapters/AGENTS.md) |
-| 嵌入式 WebDriver | `src/crates/webdriver` | [AGENTS.md](src/crates/webdriver/AGENTS.md) |
-| 桌面应用 | `src/apps/desktop` | [AGENTS.md](src/apps/desktop/AGENTS.md) |
-| Server | `src/apps/server` | （使用 core 指南） |
-| CLI | `src/apps/cli` | （使用 core 指南） |
-| 中继服务器 | `src/apps/relay-server` | （使用 core 指南） |
-| 共享前端 | `src/web-ui` | [AGENTS.md](src/web-ui/AGENTS.md) |
-| Mobile web | `src/mobile-web` | [AGENTS.md](src/mobile-web/AGENTS.md) |
-| 安装器 | `BitFun-Installer` | [AGENTS.md](BitFun-Installer/AGENTS.md) |
-| E2E 测试 | `tests/e2e` | [AGENTS.md](tests/e2e/AGENTS.md) |
+## 分层模块索引
+
+依赖关系按自上而下读取：某一行代码只能依赖更下方的层级。可复用行为放到能够拥有它的最低层；入口、协议外观和交付形态选择留在对应的最高入口层。
+
+| # | 层级 | 路径 | 职责 | 模块 / 入口 | 层级文档 |
+|---|---|---|---|---|---|
+| 1 | 产品入口与协议入口层 | `src/apps/*`, `src/web-ui`, `src/mobile-web`, `BitFun-Installer`, `tests/e2e`, `src/crates/surfaces` | UI、命令、路由、交付形态、宿主集成、协议入口和跨形态测试 | desktop、CLI、server、relay、Web UI、mobile web、installer、E2E、`acp` | 最近的本地 `AGENTS.md`；[surfaces](src/crates/surfaces/AGENTS.md) |
+| 2 | 门面与产品组装层 | `src/crates/facade` | 兼容导出、product-full 组装、交付形态接线和 provider 注册 | `core` | [AGENTS.md](src/crates/facade/AGENTS.md) |
+| 3 | 具体适配实现层 | `src/crates/integrations` | 低层外部协议、provider、transport 和平台 adapter | `ai-adapters`, `api-layer`, `transport`, `webdriver` | [AGENTS.md](src/crates/integrations/AGENTS.md) |
+| 4 | 可复用服务与服务适配层 | `src/crates/services` | 具体非 UI 服务实现，以及窄产品领域 port adapter | `services-core`, `services-integrations`, `terminal` | [AGENTS.md](src/crates/services/AGENTS.md) |
+| 5 | 产品策略与能力层 | `src/crates/product` | 产品领域、feature facts、capability packs、非 UI 产品策略和窄领域 port | `product-domains`, `product-capabilities` | [AGENTS.md](src/crates/product/AGENTS.md) |
+| 6 | 执行原语层 | `src/crates/execution` | provider-neutral 的 agent、tool、harness、stream 和 typed-service 构件 | `agent-runtime`, `agent-stream`, `agent-tools`, `harness`, `runtime-services`, `tool-packs`, `tool-runtime` | [AGENTS.md](src/crates/execution/AGENTS.md) |
+| 7 | 稳定契约层 | `src/crates/contracts` | 跨层共享 DTO、事件形状和 port | `core-types`, `events`, `runtime-ports` | [AGENTS.md](src/crates/contracts/AGENTS.md) |
+
+边界规则：
+
+- 产品入口与协议入口只选择交付形态并调用 facade 或 adapter API；可复用行为应下移。
+- facade 只负责兼容和产品组装接线，不实现 provider、protocol、OS 或 service 细节。
+- 具体适配实现只翻译外部系统；依赖已组装产品行为的协议入口应放入 `surfaces`。
+- 通用 service 不依赖产品 crate；feature-gated service adapter 只能实现窄 `product-domains` port。
+- product 拥有产品策略和能力事实，不拥有 UI、protocol、host 或具体 service 实现。
+- execution 只放可移植执行构件，不等同于完整产品 runtime 或宿主 runtime。
+- contracts 只放轻行为契约，不得向上依赖。
 
 ## 常用命令
 
@@ -179,7 +169,7 @@ await api.invoke('your_command', { request: { ... } });
 | `core`、`transport`、`api-layer` 或共享服务中的 Rust 逻辑 | `cargo check --workspace`；行为变化时再加最近的 focused `cargo test` |
 | 桌面端集成、Tauri API、browser/computer-use 或桌面专属行为 | `cargo check -p bitfun-desktop`；行为变化时再加 focused desktop tests |
 | 被桌面端 smoke/functional 流覆盖的行为 | 优先运行最近的 focused E2E/smoke check；除非改动影响构建，否则 broad build/test 交给 CI |
-| `src/crates/ai-adapters` | 运行上面相关 Rust 检查；只有 stream contract 改动时再加 `cargo test -p bitfun-agent-stream` |
+| `src/crates/integrations/ai-adapters` | 运行上面相关 Rust 检查；只有 stream contract 改动时再加 `cargo test -p bitfun-agent-stream` |
 | 不涉及打包的安装器前端或 i18n runtime | `pnpm --dir BitFun-Installer run type-check` |
 | 安装器 Tauri/Rust 改动 | `cargo check --manifest-path BitFun-Installer/src-tauri/Cargo.toml` |
 | 安装器打包、payload、安装/卸载流程或 native bundling | `pnpm run installer:build` |

AGENTS.md

@@ -13,39 +13,32 @@ Repository rule: **keep product logic platform-agnostic, then expose it through
 3. After Rust file changes, prefer `pnpm run fmt:rs` to format only changed or staged `.rs` files. Use `cargo fmt` only when you intentionally want broader formatting coverage.
 4. After changes, run the smallest matching verification from the table below.
 
-## Module index
-
-| Module | Path | Agent doc |
-|---|---|---|
-| Core (product logic) | `src/crates/core` | [AGENTS.md](src/crates/core/AGENTS.md) |
-| Core shared DTOs | `src/crates/core-types` | [AGENTS.md](src/crates/core-types/AGENTS.md) |
-| Event contracts | `src/crates/events` | [AGENTS.md](src/crates/events/AGENTS.md) |
-| Agent stream normalization | `src/crates/agent-stream` | [AGENTS.md](src/crates/agent-stream/AGENTS.md) |
-| Runtime ports | `src/crates/runtime-ports` | [AGENTS.md](src/crates/runtime-ports/AGENTS.md) |
-| Runtime services | `src/crates/runtime-services` | [AGENTS.md](src/crates/runtime-services/AGENTS.md) |
-| Terminal infrastructure | `src/crates/terminal` | [AGENTS.md](src/crates/terminal/AGENTS.md) |
-| Low-level tool runtime | `src/crates/tool-runtime` | [AGENTS.md](src/crates/tool-runtime/AGENTS.md) |
-| Agent runtime owner crate | `src/crates/agent-runtime` | [AGENTS.md](src/crates/agent-runtime/AGENTS.md) |
-| Harness workflow contracts | `src/crates/harness` | [AGENTS.md](src/crates/harness/AGENTS.md) |
-| 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) |
-| Tool pack provider plan | `src/crates/tool-packs` | [AGENTS.md](src/crates/tool-packs/AGENTS.md) |
-| Product domains | `src/crates/product-domains` | [AGENTS.md](src/crates/product-domains/AGENTS.md) |
-| Product capabilities | `src/crates/product-capabilities` | [AGENTS.md](src/crates/product-capabilities/AGENTS.md) |
-| Transport adapters | `src/crates/transport` | [AGENTS.md](src/crates/transport/AGENTS.md) |
-| API layer | `src/crates/api-layer` | [AGENTS.md](src/crates/api-layer/AGENTS.md) |
-| ACP integration | `src/crates/acp` | [AGENTS.md](src/crates/acp/AGENTS.md) |
-| AI adapters | `src/crates/ai-adapters` | [AGENTS.md](src/crates/ai-adapters/AGENTS.md) |
-| Embedded WebDriver | `src/crates/webdriver` | [AGENTS.md](src/crates/webdriver/AGENTS.md) |
-| Desktop app | `src/apps/desktop` | [AGENTS.md](src/apps/desktop/AGENTS.md) |
-| Server | `src/apps/server` | (use core guide) |
-| CLI | `src/apps/cli` | (use core guide) |
-| Relay server | `src/apps/relay-server` | (use core guide) |
-| Shared frontend | `src/web-ui` | [AGENTS.md](src/web-ui/AGENTS.md) |
-| Mobile web | `src/mobile-web` | [AGENTS.md](src/mobile-web/AGENTS.md) |
-| Installer | `BitFun-Installer` | [AGENTS.md](BitFun-Installer/AGENTS.md) |
-| E2E tests | `tests/e2e` | [AGENTS.md](tests/e2e/AGENTS.md) |
+## Layered Module Index
+
+Dependencies flow top to bottom: code in a row may depend only on lower rows.
+Put reusable behavior in the lowest layer that can own it; put entrypoint and
+profile selection in the highest layer that owns the surface.
+
+| # | Layer | Path | Owns | Modules / entries | Layer doc |
+|---|---|---|---|---|---|
+| 1 | Product surfaces and protocol surfaces | `src/apps/*`, `src/web-ui`, `src/mobile-web`, `BitFun-Installer`, `tests/e2e`, `src/crates/surfaces` | UI, commands, routes, delivery profiles, host integration, protocol entrypoints, and cross-surface tests | desktop, CLI, server, relay, Web UI, mobile web, installer, E2E, `acp` | nearest local `AGENTS.md`; [surfaces](src/crates/surfaces/AGENTS.md) |
+| 2 | Facade and product assembly | `src/crates/facade` | Compatibility exports, product-full assembly, delivery-profile wiring, and provider registration | `core` | [AGENTS.md](src/crates/facade/AGENTS.md) |
+| 3 | Concrete provider adapters | `src/crates/integrations` | Low-level external protocol, provider, transport, and platform adapters | `ai-adapters`, `api-layer`, `transport`, `webdriver` | [AGENTS.md](src/crates/integrations/AGENTS.md) |
+| 4 | Reusable services and service adapters | `src/crates/services` | Concrete non-UI services and narrow product-domain port adapters | `services-core`, `services-integrations`, `terminal` | [AGENTS.md](src/crates/services/AGENTS.md) |
+| 5 | Product policy and capabilities | `src/crates/product` | Product domains, feature facts, capability packs, product-owned non-UI policy, and narrow domain ports | `product-domains`, `product-capabilities` | [AGENTS.md](src/crates/product/AGENTS.md) |
+| 6 | Execution primitives | `src/crates/execution` | Provider-neutral agent, tool, harness, stream, and typed-service building blocks | `agent-runtime`, `agent-stream`, `agent-tools`, `harness`, `runtime-services`, `tool-packs`, `tool-runtime` | [AGENTS.md](src/crates/execution/AGENTS.md) |
+| 7 | Stable contracts | `src/crates/contracts` | Shared DTOs, event shapes, and ports | `core-types`, `events`, `runtime-ports` | [AGENTS.md](src/crates/contracts/AGENTS.md) |
+
+Boundary rules:
+
+- Surfaces and protocol surfaces choose delivery profiles and call facade or adapter APIs; reusable behavior moves down.
+- Facade wires lower layers for compatibility and product assembly; it must not implement provider, protocol, OS, or service details.
+- Concrete provider adapters translate external systems; product-facing protocol entrypoints that depend on assembled product behavior belong in `surfaces`.
+- Generic services stay product-independent; feature-gated service adapters may implement narrow `product-domains` ports.
+- Product owns product policy and capability facts, not UI, protocol, host, or concrete service implementations.
+- Execution primitives are portable building blocks, not the full product runtime or host-specific runtime.
+- Contracts stay behavior-light and must not depend upward.
+
 
 ## Common commands
 
@@ -190,7 +183,7 @@ change directly affects build, packaging, or CI cannot protect the path.
 | Shared Rust logic in `core`, `transport`, `api-layer`, or services | `cargo check --workspace`, plus the nearest focused `cargo test` when behavior changed |
 | Desktop integration, Tauri APIs, browser/computer-use, or desktop-only behavior | `cargo check -p bitfun-desktop`, plus focused desktop tests when behavior changed |
 | Behavior covered by desktop smoke/functional flows | Prefer the nearest focused E2E/smoke check; rely on CI for broad build/test coverage unless build behavior changed |
-| `src/crates/ai-adapters` | Relevant Rust checks above; add `cargo test -p bitfun-agent-stream` only when stream contracts changed |
+| `src/crates/integrations/ai-adapters` | Relevant Rust checks above; add `cargo test -p bitfun-agent-stream` only when stream contracts changed |
 | Installer frontend or i18n runtime without packaging changes | `pnpm --dir BitFun-Installer run type-check` |
 | Installer Tauri/Rust changes | `cargo check --manifest-path BitFun-Installer/src-tauri/Cargo.toml` |
 | Installer packaging, payload, install/uninstall flow, or native bundling | `pnpm run installer:build` |

BitFun-Installer/src-tauri/Cargo.toml

@@ -35,7 +35,7 @@ reqwest = { version = "0.12", default-features = false, features = ["json", "rus
 urlencoding = "2"
 futures = "0.3"
 eventsource-stream = "0.2"
-bitfun-ai-adapters = { path = "../../src/crates/ai-adapters" }
+bitfun-ai-adapters = { path = "../../src/crates/integrations/ai-adapters" }
 
 [target.'cfg(windows)'.dependencies]
 winreg = "0.52"

CONTRIBUTING.md

@@ -94,10 +94,10 @@ We welcome contributions beyond standard feature or bug-fix PRs. Examples includ
 
 | Contribution area | Location / files | Example |
 | --- | --- | --- |
-| Prompts | `src/crates/core/src/agentic/agents/prompts/` | Add or refine prompts, and update related logic as needed |
-| Tools | `src/crates/core/src/agentic/tools/implementations/`, `src/crates/core/src/agentic/tools/registry.rs` | Add tool implementations and register them in the tool registry |
-| Subagents | `src/crates/core/src/agentic/agents/custom_subagents/`, `src/crates/core/src/agentic/agents/registry.rs` | Add subagent implementations and register them in the subagent registry |
-| Mode contributions | `src/crates/core/src/agentic/agents/*_mode.rs`, `src/crates/core/src/agentic/agents/prompts/*_mode.md`, `src/web-ui/src/locales/*/settings/modes.json` | Add/improve agent modes (e.g. Plan/Debug/Agentic or custom modes) and keep prompts + UI copy in sync |
+| Prompts | `src/crates/facade/core/src/agentic/agents/prompts/` | Add or refine prompts, and update related logic as needed |
+| Tools | `src/crates/facade/core/src/agentic/tools/implementations/`, `src/crates/facade/core/src/agentic/tools/registry.rs` | Add tool implementations and register them in the tool registry |
+| Subagents | `src/crates/facade/core/src/agentic/agents/custom_subagents/`, `src/crates/facade/core/src/agentic/agents/registry.rs` | Add subagent implementations and register them in the subagent registry |
+| Mode contributions | `src/crates/facade/core/src/agentic/agents/*_mode.rs`, `src/crates/facade/core/src/agentic/agents/prompts/*_mode.md`, `src/web-ui/src/locales/*/settings/modes.json` | Add/improve agent modes (e.g. Plan/Debug/Agentic or custom modes) and keep prompts + UI copy in sync |
 | Scenario guides for Code Agent and AIIde | `website/src/docs/` | Add workflows, playbooks, and real-world scenario docs (or link them from `README.md`) |
 
 ### Before you start

CONTRIBUTING_CN.md

@@ -86,10 +86,10 @@ DevTools；`Cmd/Ctrl + Shift + I` 切换 BitFun 元素检查器，`Cmd/Ctrl + Sh
 
 | 贡献方向 | 位置/文件 | 示例说明 |
 | --- | --- | --- |
-| Prompts | `src/crates/core/src/agentic/agents/prompts/` | 新增或优化提示词，并按需更新相关逻辑 |
-| Tools | `src/crates/core/src/agentic/tools/implementations/`、`src/crates/core/src/agentic/tools/registry.rs` | 新增工具实现，并在工具注册表中注册 |
-| Subagents | `src/crates/core/src/agentic/agents/custom_subagents/`、`src/crates/core/src/agentic/agents/registry.rs` | 新增子代理实现，并在子代理注册表中注册 |
-| 模式贡献 | `src/crates/core/src/agentic/agents/*_mode.rs`、`src/crates/core/src/agentic/agents/prompts/*_mode.md`、`src/web-ui/src/locales/*/settings/modes.json` | 新增/优化 Agent 模式（例如 Plan/Debug/Agentic 或自定义模式）的逻辑与提示词，并同步前端模式文案 |
+| Prompts | `src/crates/facade/core/src/agentic/agents/prompts/` | 新增或优化提示词，并按需更新相关逻辑 |
+| Tools | `src/crates/facade/core/src/agentic/tools/implementations/`、`src/crates/facade/core/src/agentic/tools/registry.rs` | 新增工具实现，并在工具注册表中注册 |
+| Subagents | `src/crates/facade/core/src/agentic/agents/custom_subagents/`、`src/crates/facade/core/src/agentic/agents/registry.rs` | 新增子代理实现，并在子代理注册表中注册 |
+| 模式贡献 | `src/crates/facade/core/src/agentic/agents/*_mode.rs`、`src/crates/facade/core/src/agentic/agents/prompts/*_mode.md`、`src/web-ui/src/locales/*/settings/modes.json` | 新增/优化 Agent 模式（例如 Plan/Debug/Agentic 或自定义模式）的逻辑与提示词，并同步前端模式文案 |
 | Code Agent 与 AIIde 场景指南 | `website/src/docs/` | 补充流程、playbook 与真实场景说明（或从 `README.md` 链接） |
 
 ### 开始前

Cargo.toml

@@ -1,30 +1,30 @@
 [workspace]
 members = [
-    "src/crates/core-types",
-    "src/crates/events",
-    "src/crates/ai-adapters",
-    "src/crates/agent-stream",
-    "src/crates/agent-runtime",
-    "src/crates/harness",
-    "src/crates/product-capabilities",
-    "src/crates/runtime-ports",
-    "src/crates/runtime-services",
-    "src/crates/services-core",
-    "src/crates/services-integrations",
-    "src/crates/product-domains",
-    "src/crates/agent-tools",
-    "src/crates/tool-packs",
-    "src/crates/acp",
-    "src/crates/core",
-    "src/crates/terminal",
-    "src/crates/tool-runtime",
-    "src/crates/transport",
-    "src/crates/api-layer",
-    "src/crates/webdriver",
     "src/apps/cli",
     "src/apps/desktop",
     "src/apps/server",
     "src/apps/relay-server",
+    "src/crates/surfaces/acp",
+    "src/crates/facade/core",
+    "src/crates/integrations/ai-adapters",
+    "src/crates/integrations/webdriver",
+    "src/crates/integrations/api-layer",
+    "src/crates/integrations/transport",
+    "src/crates/services/services-core",
+    "src/crates/services/services-integrations",
+    "src/crates/services/terminal",
+    "src/crates/product/product-capabilities",
+    "src/crates/product/product-domains",
+    "src/crates/execution/agent-runtime",
+    "src/crates/execution/agent-stream",
+    "src/crates/execution/agent-tools",
+    "src/crates/execution/harness",
+    "src/crates/execution/runtime-services",
+    "src/crates/execution/tool-packs",
+    "src/crates/execution/tool-runtime",
+    "src/crates/contracts/core-types",
+    "src/crates/contracts/events",
+    "src/crates/contracts/runtime-ports",
 ]
 
 exclude = [