From 190e8f6eee31433a5d0e4e1f22a505447f1b7a16 Mon Sep 17 00:00:00 2001 From: limityan Date: Sat, 30 May 2026 15:43:18 +0800 Subject: [PATCH] docs(architecture): clarify runtime decomposition layers --- .../agent-runtime-services-design.md | 880 +++++++ docs/architecture/core-decomposition.md | 902 +++---- docs/plans/core-decomposition-completed.md | 64 + docs/plans/core-decomposition-plan.md | 2212 +---------------- 4 files changed, 1410 insertions(+), 2648 deletions(-) create mode 100644 docs/architecture/agent-runtime-services-design.md create mode 100644 docs/plans/core-decomposition-completed.md diff --git a/docs/architecture/agent-runtime-services-design.md b/docs/architecture/agent-runtime-services-design.md new file mode 100644 index 000000000..35178e595 --- /dev/null +++ b/docs/architecture/agent-runtime-services-design.md @@ -0,0 +1,880 @@ +# Agent Runtime SDK 与 Runtime Services 设计 + +本文是 [`core-decomposition.md`](core-decomposition.md) 的开发设计文档，描述目标模块、 +接口、crate 内部结构和迁移保护。本文中的 `bitfun-runtime-services`、 +`bitfun-agent-runtime`、`bitfun-harness` 是目标 crate；在实际创建前不得把它们当作 +已完成事实。 + +## 1. 设计目标与边界 + +- Agent Runtime SDK 可被 Desktop、CLI、Server、Remote、ACP 等产品形态嵌入。 +- Runtime 不感知平台差异、工具实现差异和构建形态差异。 +- Tool 使用通用接口和 provider 注册，不绑定底层实现。 +- 具体 service 实现由上层 Product Assembly 注入。 +- Harness 可扩展，新增 SDD 等工作流不侵入 runtime kernel。 +- 每个 crate 只依赖最小稳定集合，依赖方向可检查。 + +### 1.1 crate 划分 + +```text +bitfun-core-types +bitfun-events +bitfun-runtime-ports +bitfun-runtime-services # 目标 +bitfun-agent-tools +tool-runtime +bitfun-agent-runtime # 目标 +bitfun-harness # 目标 +bitfun-services-core +bitfun-services-integrations +bitfun-product-domains +bitfun-acp +bitfun-core +apps/* +``` + +目标依赖： + +```text +apps/* + -> bitfun-core 或 Product Assembly crate + -> 按需依赖 bitfun-acp / transport / api-layer + +Product Assembly + -> product capability packs + -> bitfun-agent-runtime + -> bitfun-harness + -> tool-runtime + -> bitfun-runtime-services + -> 具体 service crates + +Product Capability packs + -> bitfun-harness + -> bitfun-agent-runtime + -> tool-runtime + -> bitfun-product-domains + +bitfun-agent-runtime + -> bitfun-runtime-ports + -> bitfun-events + -> bitfun-agent-stream + -> tool-runtime + -> bitfun-runtime-services + +tool-runtime + -> bitfun-agent-tools + -> bitfun-runtime-ports + -> bitfun-events + +bitfun-runtime-services + -> bitfun-runtime-ports + -> bitfun-core-types + -> bitfun-events + +具体 service crates + -> bitfun-runtime-ports + -> bitfun-core-types + -> 允许的 third-party 依赖 + -> External Systems +``` + +禁止依赖： + +- `bitfun-runtime-ports` -> `bitfun-core` +- `bitfun-agent-tools` -> 具体 service crate +- `tool-runtime` -> 具体 tool 实现 crate +- `bitfun-agent-runtime` -> `bitfun-core` +- `bitfun-agent-runtime` -> Tauri / CLI / ACP protocol / Web UI +- `bitfun-harness` -> 具体 filesystem / Git / terminal manager + +目标 crate 创建准入： + +- 只有当 owner 边界、旧路径兼容、focused tests、依赖收益和 boundary check 都能同时落地时，才创建新的目标 crate。 +- `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。 + +## 2. 稳定接口与运行时服务 + +### 2.1 稳定契约（Stable Contracts） + +所属 crate： + +- `bitfun-core-types` +- `bitfun-events` +- `bitfun-runtime-ports` + +建议模块： + +```text +bitfun-core-types + error/ + identity/ + artifact/ + usage/ + surface/ + +bitfun-events + runtime/ + tool/ + permission/ + product/ + +bitfun-runtime-ports + agent/ + service/ + permission/ + subagent/ + tool/ + workspace/ +``` + +接口原则： + +- DTO 必须可序列化，避免携带 runtime handle。 +- port trait 只描述能力，不描述产品 UI。 +- permission / approval 必须包含 surface、thread、turn、agent、subagent identity。 +- artifact ref 使用稳定 URI / logical path，不暴露本地绝对路径。 + +示例接口： + +```rust +pub trait RuntimeEventSink: Send + Sync { + fn emit(&self, event: RuntimeEvent); +} + +#[async_trait::async_trait] +pub trait PermissionPort: Send + Sync { + async fn request(&self, request: PermissionRequest) -> PermissionDecision; +} + +#[async_trait::async_trait] +pub trait WorkspacePort: Send + Sync { + async fn resolve(&self, identity: WorkspaceIdentity) -> Result; +} +``` + +### 2.2 Runtime Services + +目标 crate：`bitfun-runtime-services`。 + +职责： + +- 承载 runtime 可消费的 typed service bundle。 +- 提供 provider 注册和 capability resolution。 +- 把具体实现与 runtime port 隔离。 +- 提供统一的 unavailable / unsupported 错误。 +- 为测试提供 fake provider builder。 + +建议内部模块： + +```text +bitfun-runtime-services + bundle.rs # RuntimeServices / ToolServices / HarnessServices + builder.rs # typed builder + capability.rs # capability ids 与 availability + registry.rs # provider 注册 + errors.rs # unsupported / unavailable 映射 + test_support.rs # fake providers +``` + +核心结构： + +```rust +pub struct RuntimeServices { + pub filesystem: Arc, + pub workspace: Arc, + pub session_store: Arc, + pub permission: Arc, + pub events: Arc, + pub clock: Arc, + pub terminal: Option>, + pub network: Option>, + pub git: Option>, + pub mcp_catalog: Option>, + pub remote_connection: Option>, + pub remote_workspace: Option>, + pub remote_projection: Option>, + pub remote_capabilities: Option>, +} + +pub struct RuntimeServicesBuilder { + // 仅 typed 字段 +} + +impl RuntimeServicesBuilder { + pub fn with_filesystem(self, port: Arc) -> Self; + pub fn with_optional_network(self, port: Option>) -> Self; + pub fn with_optional_git(self, port: Option>) -> Self; + pub fn with_optional_remote_connection(self, port: Option>) -> Self; + pub fn with_optional_remote_workspace(self, port: Option>) -> Self; + pub fn with_optional_remote_projection(self, port: Option>) -> Self; + pub fn with_optional_remote_capabilities(self, port: Option>) -> Self; + pub fn build(self) -> Result; +} +``` + +Remote ports 的边界： + +- `RemoteConnectionPort` 只描述连接身份、状态、认证上下文和连接生命周期请求，不暴露 SSH / relay / tunnel concrete handle。 +- `RemoteWorkspacePort` 只描述 remote workspace identity、root resolution、startup guard 和 persistence/session facts。 +- `RemoteProjectionPort` 只描述 file、terminal、image/context projection 的 request / response shape，不直接执行具体 OS 命令。 +- `RemoteCapabilityPort` 只描述 remote host capability facts，例如 filesystem、terminal、review platform、model catalog 支持状态。 +- SSH、relay、本地隧道、远端 OS、认证和 transport 实现必须留在具体 Remote provider，由 Product Assembly 注册。 + +设计约束： + +- 不提供 `get() -> Any` 作为主路径。 +- capability 缺失必须返回 typed unsupported 错误。 +- 不在 runtime services 中执行产品命令。 +- 不在 runtime services 中创建 concrete manager；创建发生在 Product Assembly。 +- `RuntimeServices` 是运行时依赖集合，不是全局 mutable app state。 + +## 3. Runtime / Tool / Harness 内核 + +### 3.1 Agent Runtime SDK + +目标 crate：`bitfun-agent-runtime`。 + +职责： + +- session 生命周期。 +- dialog turn / model round 生命周期。 +- scheduler / queue / cancellation。 +- prompt loop 和 context assembly。 +- prompt cache 协调。 +- subagent registry 查询和 delegation policy。 +- fork context seeding。 +- tool call 调度。 +- permission 协调。 +- runtime events。 +- post-turn processor。 + +建议内部模块： + +```text +bitfun-agent-runtime + lib.rs + runtime.rs # AgentRuntime 公共 API + config.rs # RuntimeConfig + session/ + manager.rs + state.rs + persistence.rs + turn/ + dialog_turn.rs + model_round.rs + continuation.rs + scheduler/ + queue.rs + cancellation.rs + priority.rs + prompt/ + assembly.rs + cache.rs + compression.rs + agents/ + definitions.rs + registry.rs + prompts.rs + subagent/ + delegation.rs + fork_context.rs + background.rs + tools/ + dispatcher.rs + permission.rs + result_bridge.rs + hooks/ + registry.rs + prompt.rs + post_turn.rs + events/ + mapper.rs +``` + +公共 API： + +```rust +pub struct AgentRuntime { + services: RuntimeServices, + tools: Arc, + agents: Arc, + hooks: Arc, + config: RuntimeConfig, +} + +impl AgentRuntime { + pub fn new(parts: AgentRuntimeParts) -> Result; + + pub async fn start_session( + &self, + request: StartSessionRequest, + ) -> Result; + + pub async fn submit_turn( + &self, + request: SubmitTurnRequest, + ) -> Result; + + pub async fn cancel_turn( + &self, + request: CancelTurnRequest, + ) -> Result; +} +``` + +输入： + +- `RuntimeServices` +- `ToolRuntime` +- `AgentDefinitionRegistry` +- `RuntimeHookRegistry` +- model / stream adapter +- 产品注入的 `RuntimeConfig` + +输出： + +- `RuntimeEvent` +- transcript delta +- artifact refs +- permission requests +- session state +- turn outcome + +不得拥有： + +- 具体 filesystem / Git / terminal / MCP client。 +- Tauri、CLI TUI、Web rendering。 +- ACP protocol。 +- 产品 feature matrix。 +- 具体 tool 实现。 + +关键保护： + +- `SessionManager -> Session -> DialogTurn -> ModelRound` 语义不变。 +- `/goal` custom metadata、post-turn verification、continuation event 不漂移。 +- `Task.run_in_background` delivery 不漂移。 +- `Task.fork_context` 禁止字段、prompt cache clone、context seeding 不漂移。 +- DeepResearch citation renumber post-turn hook 保持 deterministic。 + +### 3.2 Tool Runtime + +所属 crate： + +- `bitfun-agent-tools` +- `tool-runtime` +- `bitfun-tool-packs` + +目标职责： + +- `bitfun-agent-tools`：tool DTO、manifest、exposure、schema、path policy、result policy。 +- `tool-runtime`：provider registry、permission gate、execution pipeline、hook。 +- `bitfun-tool-packs`：tool pack feature metadata 和 provider plan。 + +建议 `tool-runtime` 模块： + +```text +tool-runtime + runtime.rs + registry.rs + provider.rs + context.rs + permission.rs + execution.rs + hooks.rs + result.rs + catalog.rs +``` + +核心接口： + +```rust +#[async_trait::async_trait] +pub trait ToolProvider: Send + Sync { + fn id(&self) -> ToolProviderId; + fn manifest(&self, ctx: ToolManifestContext) -> ToolManifest; + async fn get(&self, name: &str) -> Option>; +} + +#[async_trait::async_trait] +pub trait RuntimeTool: Send + Sync { + fn spec(&self, ctx: ToolSpecContext) -> ToolSpec; + + async fn execute( + &self, + ctx: ToolExecutionContext, + input: ToolInput, + ) -> Result; +} + +pub struct ToolExecutionContext { + pub facts: ToolContextFacts, + pub services: ToolExecutionServices, + pub cancellation: CancellationToken, +} +``` + +设计约束： + +- `ToolExecutionContext` 不暴露具体 manager。 +- `ToolContextFacts` 只包含 portable facts。 +- Tool Runtime 只消费 `ToolExecutionServices` 这样的窄 service 视图，不依赖完整 + `RuntimeServices` bundle。 +- path policy、runtime artifact ref、remote POSIX containment 由 `bitfun-agent-tools` 承载。 +- MCP tool 作为 external tool provider 注入，不内置在 Agent Runtime SDK。 +- `GetToolSpec` 是 tool runtime/catalog 能力，不是产品 UI。 + +必须保护： + +- prompt-visible manifest。 +- expanded / collapsed exposure。 +- `GetToolSpec` schema / assistant detail / detail JSON。 +- collapsed unlock state。 +- readonly / enabled snapshot filter。 +- MCP / ACP / desktop tool catalog 等价。 +- oversized tool result persistence、flush、preview、artifact ref。 +- Write/Edit/Read file-read-state guardrail。 + +### 3.3 Harness Layer + +目标 crate：`bitfun-harness`。 + +职责： + +- 把 SDD、DeepReview、DeepResearch、MiniApp、function-agent 等工作流从 runtime kernel + 中分离。 +- 定义 workflow plan、step、policy、artifact、review gate、post-processor。 +- 通过 Agent Runtime SDK、Tool Runtime 和 service ports 编排。 + +建议内部模块： + +```text +bitfun-harness + provider.rs + registry.rs + plan.rs + context.rs + artifact.rs + hooks.rs + review_gate.rs + sdd/ + deep_review/ + deep_research/ + miniapp/ +``` + +核心接口： + +```rust +#[async_trait::async_trait] +pub trait HarnessProvider: Send + Sync { + fn id(&self) -> HarnessId; + fn capabilities(&self) -> HarnessCapabilities; + + async fn plan( + &self, + ctx: HarnessPlanningContext, + input: HarnessInput, + ) -> Result; + + async fn execute( + &self, + ctx: HarnessExecutionContext, + plan: HarnessPlan, + ) -> Result; +} + +pub struct HarnessExecutionContext { + pub runtime: Arc, + pub tools: Arc, + pub services: HarnessServices, + pub events: Arc, +} +``` + +设计约束： + +- harness 可以编排 runtime/tool，但不拥有 session manager internals。 +- harness 不直接访问 concrete filesystem / Git / terminal。 +- 产品命令只映射到 harness capability，不把命令展示逻辑下沉。 +- 新 harness 通过 provider 注册，不改 Agent Runtime SDK 内核。 + +## 4. 产品组装与扩展 + +### 4.1 Product Assembly + +Product Assembly 是 composition root。它可以位于 `bitfun-core` 迁移期 facade 内，也可以在 +后续拆成独立 Product Assembly crate。 + +职责： + +- 创建具体 service 实现。 +- 构建 `RuntimeServices`。 +- 注册 tool providers。 +- 注册 harness providers。 +- 注册 agent definitions、subagents、skills、prompt modules。 +- 建立产品 feature matrix。 +- 把 surface 命令映射到 capability / harness / runtime request。 +- 根据交付形态选择 `DeliveryProfile`、`CapabilitySet` 和 service provider 集合。 +- 对不支持能力返回 typed unsupported / unavailable 错误，而不是让下层 runtime 判断产品形态。 + +建议模块： + +```text +product-assembly + full.rs + delivery_profile.rs + capability_set.rs + desktop.rs + cli.rs + server.rs + remote.rs + acp.rs + feature_matrix.rs + commands.rs +``` + +核心结构： + +```rust +pub enum DeliveryProfile { + Desktop, + Cli, + Server, + Remote, + Acp, + Web, +} + +pub struct CapabilitySet { + pub agent_modes: Vec, + pub tool_packs: Vec, + pub harness_packs: Vec, + pub service_capabilities: Vec, + pub command_providers: Vec, +} + +pub struct ProductAssemblyPlan { + pub profile: DeliveryProfile, + pub capabilities: CapabilitySet, + pub feature_groups: Vec, +} + +pub trait ProductAssembler { + fn plan(&self, profile: DeliveryProfile) -> Result; + fn build(&self, plan: ProductAssemblyPlan) -> Result; +} +``` + +实现注册方式： + +```rust +pub struct ProductAssemblyInput { + pub profile: DeliveryProfile, + pub services: ConcreteServiceProviders, + pub tool_providers: Vec>, + pub harness_providers: Vec>, + pub agents: Arc, + pub commands: Vec, + pub hooks: RuntimeHookRegistry, +} + +pub struct ProductRuntimeParts { + pub services: RuntimeServices, + pub tools: Arc, + pub harnesses: Arc, + pub agents: Arc, + pub commands: ProductCommandRegistry, + pub hooks: RuntimeHookRegistry, +} +``` + +注册路径： + +- concrete service provider 只注册到 `RuntimeServicesBuilder`。 +- tool provider 只注册到 `ToolRuntimeBuilder::install_provider`。 +- harness provider 只注册到 `HarnessRegistryBuilder`。 +- agent、subagent、prompt、skill 只注册到 `AgentDefinitionRegistry` 或对应 registry。 +- 输入框命令、审核入口、MiniApp 入口只注册到 `ProductCommandRegistry`，再映射到 capability 或 harness。 +- unsupported / unavailable 能力在 `CapabilityAvailability` 中表达，不让 runtime kernel 读取产品形态。 + +示例构建流程： + +```rust +pub fn build_desktop_runtime(input: DesktopAssemblyInput) -> Result { + let services = RuntimeServicesBuilder::new() + .with_filesystem(input.desktop_fs) + .with_workspace(input.workspace) + .with_permission(input.permission) + .with_optional_git(input.git) + .build()?; + + let tools = ToolRuntimeBuilder::new() + .install_provider(input.core_tools) + .install_provider(input.mcp_tools) + .build()?; + + let runtime = AgentRuntime::new(AgentRuntimeParts { + services, + tools, + agents: input.agents, + hooks: input.runtime_hooks, + config: input.config, + })?; + + Ok(ProductRuntime { runtime }) +} +``` + +约束： + +- Product Assembly 可以依赖具体实现；runtime kernel 不可以。 +- 不同产品可以注册不同 surface command，但必须映射到稳定 capability。 +- 输入框命令、审核、MiniApp、ACP client、自定义 tool/subagent/skill 均通过 assembly 注册。 +- assembly 不得改变底层 runtime 语义来适配某个 surface。 +- `DeliveryProfile` 只能影响 capability/provider 选择，不得让下层出现 `if desktop` + 或 `if cli` 这样的 product 分支。 +- feature group 是构建时能力边界，`CapabilitySet` 是产品运行时能力边界；两者必须在 + assembly 中显式对应。 +- 任何交付形态减少能力前，必须先更新 product matrix 并补产品入口验证。 + +### 4.2 产品形态与组装差异 + +| 产品形态 | 关键差异 | 组装时必须稳定的下层契约 | +|---|---|---| +| Desktop | Tauri window、desktop API、本地 permission UI | runtime events、permission facts、artifact refs、desktop service providers | +| CLI | TUI、命令输入、终端展示、package workflow | command provider、agent/session/tool contract、CLI-safe service providers | +| Server | HTTP/WebSocket route、server workspace policy | transport DTO、runtime request/response、workspace identity | +| Remote / mobile | remote workspace、relay/bot、file/terminal projection | remote state、logical path、permission/event facts | +| ACP | ACP protocol、client lifecycle、remote probing | external agent/tool capability、environment facts | +| Web UI / mobile web | UI state、hydration、pairing、session 展示 | API/transport DTO、runtime event facts | + +### 4.3 Product Capability 设计 + +Product Capability 位于 Product Assembly 与 Harness / Runtime / Tool 之间，负责把大块产品能力 +拆成可组装的 capability pack。它不拥有 UI，也不直接执行具体 IO。 + +建议模块： + +```text +product-capabilities + code_agent.rs + deep_review.rs + deep_research.rs + miniapp.rs + function_agent.rs + remote_control.rs + mcp_app.rs + computer_use.rs + command_mapping.rs +``` + +核心接口： + +```rust +pub trait CapabilityPack: Send + Sync { + fn id(&self) -> CapabilityId; + fn required_services(&self) -> Vec; + fn tool_packs(&self) -> Vec; + fn harness_packs(&self) -> Vec; + fn agent_definitions(&self) -> Vec; + fn command_providers(&self) -> Vec; +} +``` + +分层规则： + +- Code Agent pack 可以声明 agent modes、tool packs、prompt modules，但不拥有 tool execution。 +- Deep Review pack 可以声明 harness provider、report artifact contract、queue/retry policy， + 但 target resolution 和 UI construction 留在 surface。 +- MiniApp pack 可以声明 MiniApp harness、domain ports、artifact policy，但 worker process 和 + filesystem IO 通过 Runtime Services provider。 +- MCP App pack 可以声明 MCP tool/resource/prompt capability，但 MCP transport 属于 + `bitfun-services-integrations`。 +- Input command pack 只声明 command 到 capability/harness/runtime request 的映射，不共享具体 UI。 + +### 4.4 ACP 扩展方式 + +`bitfun-acp` 保持 integration owner。 + +继续拥有： + +- ACP protocol。 +- ACP client lifecycle。 +- config persistence。 +- remote probing。 +- startup timeout。 +- workspace surface selection。 + +向上暴露： + +```rust +pub trait ExternalAgentProvider: Send + Sync { + fn list_agents(&self) -> Vec; + async fn start(&self, request: ExternalAgentStartRequest) -> Result; +} + +pub trait ExternalToolProvider: Send + Sync { + fn tool_manifest(&self, ctx: ToolManifestContext) -> ToolManifest; +} +``` + +Agent Runtime SDK 只能看到 external agent/tool capability，不感知 ACP protocol、进程管理、 +remote probing 或 startup timeout。 + +### 4.5 Skills / Prompt / Subagent + +建议归属： + +- prompt module：Agent Runtime SDK 的 prompt assembly contract。 +- skill：prompt / resource / instruction 扩展，作为 agent definition 或 harness input 的一部分。 +- subagent definition：Agent Definition Registry。 +- subagent execution：Agent Runtime SDK。 +- Task tool：Tool Runtime entrypoint，调用 Agent Runtime SDK。 + +约束： + +- skills 不直接授予 service handle。 +- subagent permission 来源必须包含 parent session、parent agent、target agent、surface。 +- prompt module 只声明可组合内容，不执行 IO。 +- skill resource 访问通过 filesystem/workspace port。 + +### 4.6 Hook 与 Event 设计 + +事件： + +```rust +pub enum RuntimeEvent { + SessionStarted(SessionStarted), + TurnStarted(TurnStarted), + PromptAssembled(PromptAssembled), + ToolCallStarted(ToolCallStarted), + PermissionRequested(PermissionRequested), + SubagentSpawned(SubagentSpawned), + ArtifactWritten(ArtifactWritten), + TurnCompleted(TurnCompleted), +} +``` + +Runtime hook： + +```rust +#[async_trait::async_trait] +pub trait PromptDecorator: Send + Sync { + async fn decorate(&self, ctx: PromptHookContext, prompt: PromptBundle) + -> Result; +} + +#[async_trait::async_trait] +pub trait PostTurnProcessor: Send + Sync { + async fn process(&self, ctx: PostTurnContext, outcome: TurnOutcome) + -> Result; +} +``` + +Tool hook： + +```rust +#[async_trait::async_trait] +pub trait BeforeToolExecution: Send + Sync { + async fn before(&self, ctx: ToolExecutionContext, input: ToolInput) + -> Result; +} +``` + +规则： + +- hook registry 必须有稳定顺序。 +- hook 必须有 timeout。 +- hook error 必须可分类：fail turn、skip hook、deny tool、record warning。 +- hook 不得获取未声明的具体 service。 +- 修改 prompt / manifest / output 的 hook 必须有 snapshot 测试。 + +## 5. 质量保护与完成定义 + +### 5.1 鲁棒性设计 + +错误： + +- contract 层使用 portable error facts。 +- runtime 层做错误分类和事件上报。 +- Product Surface 只负责展示逻辑。 +- unsupported capability 必须明确，不允许泛化为 unknown failure。 + +取消： + +- turn、tool、subagent、harness step 都必须接收 cancellation。 +- cancellation outcome 必须可观测。 +- background task 必须有 result delivery 或 explicit detached state。 + +持久化： + +- session persistence 通过 port。 +- artifact write 通过 port。 +- oversized tool result 必须 flush 后再返回 ref。 +- remote/local workspace path 通过 logical identity 表达。 + +并发： + +- scheduler queue、subagent background、fork context 必须定义并发限制。 +- fork context 继续保留禁止字段和递归 subagent 保护。 +- provider registry 构建后应尽量 immutable，避免 runtime 期间 materialization 漂移。 + +### 5.2 计划边界 + +本文只描述目标接口、crate 内部结构和行为保护要求，不定义 PR 顺序。Runtime Services、 +Tool Runtime、Agent Runtime SDK、Harness Layer 和 Product Assembly 的阶段边界、PR 范围和执行安排 +由 [`core-decomposition-plan.md`](../plans/core-decomposition-plan.md) 维护。 + +### 5.3 测试策略 + +Contract 测试： + +- DTO serialization round-trip。 +- permission facts source identity。 +- artifact ref logical path。 +- unsupported capability error。 + +Tool 测试： + +- manifest ordering。 +- expanded / collapsed exposure。 +- `GetToolSpec` detail。 +- readonly / enabled filter。 +- oversized result persistence。 + +Runtime 测试： + +- session start / turn submit / cancel。 +- prompt assembly snapshot。 +- post-turn processor deterministic output。 +- subagent delegation policy。 +- fork context seeding。 +- background result delivery。 + +Harness 测试： + +- provider 注册。 +- plan 结构。 +- artifact 输出。 +- review gate。 +- hook order。 + +Product 测试： + +- Desktop / CLI / ACP product check。 +- Remote workspace 行为。 +- MCP dynamic tool catalog。 +- MiniApp 与 review workflow。 + +### 5.4 完成定义 + +- `bitfun-agent-runtime` 能在不依赖 `bitfun-core` 的情况下构建 runtime kernel。 +- `bitfun-runtime-services` 提供 typed service injection，并由 boundary check 保护。 +- `tool-runtime` 承担 provider registry 和 execution pipeline，具体 tool 通过 provider 注入。 +- `bitfun-harness` 支持工作流 provider 扩展。 +- `bitfun-core` 只作为迁移期 facade / product-full assembly。 +- 所有产品形态通过 Product Assembly 显式启用能力。 +- 所有高风险行为有 snapshot、focused regression 或 product check 保护。 diff --git a/docs/architecture/core-decomposition.md b/docs/architecture/core-decomposition.md index 8eb021e49..1717c32f8 100644 --- a/docs/architecture/core-decomposition.md +++ b/docs/architecture/core-decomposition.md @@ -1,553 +1,365 @@ -# BitFun Core 拆解护栏（Core Decomposition Guardrails） - -本文是逐步拆解 `bitfun-core` 的执行护栏（execution guardrail）。它用于补充 -[`bitfun-core-decomposition-plan.md`](../plans/core-decomposition-plan.md) -中的详细里程碑计划。 - -目标是在不改变任何受支持构建形态（build shape）下产品行为的前提下，把稳定、 -边界清晰的逻辑从较重的 `bitfun-core` runtime 聚合体中移出，从而减少不必要的 -Rust 编译和链接面。 - -## 不可协商的不变量 - -- 拆解过程中不得改变产品行为。 -- 不得为了提升本地速度而减少 CI 或 release 覆盖范围。 -- 除非后续有明确的产品变更要求，否则产品 crate 必须保持相同的能力集合 - （capability set）。 -- 构建脚本和安装器脚本不属于本次重构范围： - - `package.json` - - `scripts/dev.cjs` - - `scripts/desktop-tauri-build.mjs` - - `scripts/ensure-openssl-windows.mjs` - - `scripts/ci/setup-openssl-windows.ps1` - - `BitFun-Installer/**` -- 共享产品逻辑必须保持平台无关（platform-agnostic）。桌面端专属逻辑应保留在 - app adapters 中，再通过 transport/API layers 回流。 -- 不要引入仓库级、机器相关的编译器或链接器默认配置，例如 `sccache`、`lld-link` - 或 `mold`。 - -## 执行顺序 - -按里程碑执行，不按孤立的重构想法零散推进： - -1. **安全保护和最小编译面验证** - - 在任何默认 feature 变轻之前，先加入 `product-full` feature 安全网。 - - 把已经独立成 crate 的 nested crate 移到 workspace 顶层路径。 - - 先抽取 `core-types`，承载稳定 DTO 和 port DTO；只有在 concrete runtime / - network 转换依赖完成解耦后，才移动 `BitFunError`。 - - 如果 stream 测试可以不依赖完整 core 运行，则抽取 stream processing。 - - 移动重服务之前先引入 ports。第一层轻量边界位于 `bitfun-runtime-ports`； - 该 crate 只包含 DTO 和 trait。 - - 第一批 adapter 实现只视为边界搭建。只有相关 service migration 和回归测试 - 完成后，才能声明 service/agent 的 concrete call site 已经被替换。 -2. **中等粒度 owner crate** - - 优先使用 8 到 12 个 owner crate，而不是大量小 crate。 - - 使用 `services-core` 和 `services-integrations`，不要为每个 service 文件夹 - 单独建立 crate。 - - 使用 `agent-tools` 加 `tool-packs` feature group，不要为每个具体工具族 - 单独建立 crate。 -3. **Facade 收敛和边界强制** - - `bitfun-core` 收敛为兼容门面（compatibility facade）和完整产品 runtime - 组装点（full product runtime assembly）。 - - 新 crate 抽出后，再加入轻量边界检查。 - - 更轻的默认 feature 只能作为单独且完整验证过的 PR 进行评估。 - -## Crate 归属目标（Crate Ownership Targets） - -初始目标 crate 应保持中等粒度。下表同时包含目标 owner、当前完成态，以及属于拆解 -边界的一些已有基础 crate；不得把 `target` 或 `partial` 误读为已完成迁移。 - -| 目标 crate | 归属职责 | 当前状态 | +# BitFun Core 拆解架构 + +本文描述 BitFun 当前 runtime 架构快照、目标分层形态和模块边界。它只回答“系统应该如何分层、 +每层负责什么、crate 与能力如何归属”；具体执行顺序、PR 范围和验证命令见 +[`core-decomposition-plan.md`](../plans/core-decomposition-plan.md)。详细接口、crate 内部模块和 +测试设计见 [`agent-runtime-services-design.md`](agent-runtime-services-design.md)。 + +## 1. 背景与目标 + +BitFun 当前已经从 `bitfun-core` 中抽出了若干 owner crate，但 `bitfun-core` 仍承担兼容 facade、 +完整产品 runtime 组装、agent loop、service 接线、tool materialization 和部分 product domain +adapter。这个形态在功能上可运行，但会让后续 runtime 迁移持续面临三个问题： + +- 产品逻辑、平台接入和具体 service 实现边界不够稳定。 +- Desktop、CLI、Server、Remote、ACP、Web 等产品形态容易被完整 `bitfun-core` 牵引。 +- Tool、MCP、ACP、subagent、skills、harness 等扩展点缺少统一的分层归属。 + +目标形态不是在 `bitfun-core` 内继续扩张完整 `AgentRuntime`，而是形成可独立嵌入的 +Agent Runtime SDK。稳定契约定义上层可依赖的接口，Product Assembly 负责注册具体实现， +Runtime Services、Tool Runtime 和 Harness Layer 分别隔离 service、tool、工作流和产品形态差异。 + +迁移期间不得改变产品行为、默认能力集合、权限语义、工具曝光、事件语义或 release 构建形态。 + +## 2. 架构原则 + +- 依赖只能从产品层流向 runtime 层，再流向 contract 层；下层不得感知上层产品形态。 +- 接口和实现必须分开：接口属于稳定契约、Runtime Services、Tool Runtime 或 Harness contract； + 具体实现属于 Product Assembly 或具体实现层。 +- Product Surface 可以有差异，capability contract 必须收敛。不同产品入口可以选择不同能力集合， + 但不能通过下沉 UI、命令或协议逻辑来换取复用。 +- `bitfun-core` 在迁移期保留 facade 和 `product-full` 组装点；新 owner crate 不得依赖回 + `bitfun-core`。 +- Hook 是受控扩展点，Event 是事实通知。能改变行为的 hook 必须有顺序、timeout、错误策略和等价保护。 +- feature group 是构建边界，CapabilitySet 是产品运行时能力边界；两者必须由 Product Assembly + 显式映射。 + +## 3. 现状逻辑视图 + +当前架构的核心事实是：多个 crate 已经承接了稳定类型、事件、stream、tool contract、部分 service +helper 和 product domain 纯逻辑，但完整运行时仍以 `bitfun-core` 为中心。 + +```mermaid +flowchart TB + Surfaces["产品入口
Desktop / CLI / Server / Relay / Remote / Web"] + Core["bitfun-core
兼容 facade + 完整产品 runtime 组装"] + Acp["bitfun-acp
ACP protocol / client integration"] + Transport["transport / api-layer
API 与传输 adapter"] + CoreTypes["bitfun-core-types
稳定 DTO 子集"] + Events["bitfun-events
事件事实与 emitter 抽象"] + Ports["bitfun-runtime-ports
trait-only runtime 边界"] + Stream["bitfun-agent-stream
stream 聚合"] + AgentTools["bitfun-agent-tools
tool contract 与纯策略"] + ToolRuntime["tool-runtime
既有 tool runtime crate"] + ToolPacks["bitfun-tool-packs
feature group / provider plan"] + ServicesCore["bitfun-services-core
基础 service helper / filesystem facade"] + ServicesIntegrations["bitfun-services-integrations
MCP / Git / Remote helper owner"] + ProductDomains["bitfun-product-domains
MiniApp / function-agent 纯 domain"] + Terminal["terminal-core
terminal domain"] + Ai["bitfun-ai-adapters
模型 provider adapter"] + External["外部系统
OS / Git / MCP / ACP / AI provider / remote host"] + + Surfaces --> Core + Surfaces --> Transport + Surfaces --> Acp + Acp --> Core + Core --> CoreTypes + Core --> Events + Core --> Ports + Core --> Stream + Core --> AgentTools + Core --> ToolRuntime + Core --> ToolPacks + Core --> ServicesCore + Core --> ServicesIntegrations + Core --> ProductDomains + Core --> Terminal + Core --> Ai + Core --> Transport + ServicesCore --> External + ServicesIntegrations --> External + Terminal --> External + Ai --> External +``` + +当前主要模块范围： + +| 模块 | 当前定位 | 架构影响 | |---|---|---| -| `bitfun-core` | 兼容门面和完整产品 runtime 组装点 | active：仍是完整 runtime assembly 和旧路径 facade | -| `bitfun-core-types` | 稳定 DTO、port DTO、纯 domain type，以及最终的纯错误类型 | partial：AI 错误 DTO / helper 已迁入；`BitFunError` 仍保留在 core | -| `bitfun-events` | 已有的传输层无关事件 DTO 和事件抽象 | done：既有基础 crate | -| `bitfun-ai-adapters` | 已有 AI provider adapter，以及 provider / protocol DTO 归属 | done：既有 adapter crate | -| `bitfun-agent-stream` | Stream 聚合和 stream-focused 测试 | done：stream 聚合已独立 | -| `bitfun-runtime-ports` | 面向 service/agent 边界的轻量跨层 DTO 和 trait | partial：DTO/trait-only 边界已建立，包含 agent submission/transcript/cancel、remote state、runtime event、remote image attachment、dialog submission policy/outcome、subagent context mode 与 delegation policy 契约；不拥有 runtime 实现 | -| `bitfun-agent-runtime` | Sessions、execution、coordination、agent system | target：crate 尚不存在，agent runtime 仍在 core | -| `bitfun-agent-tools` | 轻量 tool DTO / contract、portable tool context facts / provider、runtime restriction、host path normalization / runtime artifact URI / remote POSIX path pure contract、provider-neutral tool path resolution / absolute-path check / runtime artifact reference assembly、file guidance marker、file-read freshness comparison、oversized tool-result preview/rendering policy、tool execution result/error/invalid-call presentation policy、allowed-list / collapsed-tool execution gate policy、provider-neutral path policy root matching / denial message、pure manifest/exposure and GetToolSpec presentation/schema/static metadata/detail/result assembly / execution-plan contract、provider-backed tool catalog / GetToolSpec runtime facade、provider-backed GetToolSpec execution result helper / Tool-result vector adapter、generic contextual manifest resolver、generic catalog snapshot provider / GetToolSpec catalog provider、generic registry / static-provider / dynamic-provider / decorator-ref / snapshot-decorator adapter / runtime assembly container、generic readonly/enabled snapshot filter | partial：product registry snapshot access、`ToolUseContext` adapter、session file-read state storage、tool-result filesystem writes、`GetToolSpec` Tool impl 和 concrete tools 仍在 core，并由 core `tools/product_runtime.rs` 作为单一 product runtime owner 组装；core 当前从 `bitfun-tool-packs` provider plan 物化内置工具列表，static-provider 安装 assembly、decorator reference、generic snapshot decorator adapter、provider-backed catalog runtime facade、readonly/enabled 过滤规则、provider-neutral tool path resolution / runtime artifact reference assembly、file guidance/freshness policy、oversized result rendering、tool execution presentation 与 path policy 判定已委托给 `bitfun-agent-tools` | -| `bitfun-tool-packs` | 由 feature group 隔离的工具 provider plan | partial：提供 basic / git / mcp / browser-web / computer-use / image-analysis / miniapp / agent-control feature-group 元数据和 product provider group plan；不得声明 concrete tools 已迁移 | -| `bitfun-services-core` | Config、session、workspace、storage、filesystem、system services | partial：部分 pure helper 已迁出；通用本地 filesystem operations/tree/search/listing/service facade 已迁入；config/workspace/runtime/persistence 以及 filesystem 的 remote overlay、product runtime binding 仍在 core | -| `bitfun-services-integrations` | Git、MCP、remote SSH、remote connect、file watch integrations | partial：MCP runtime 已迁入；remote SSH 仍只迁移低风险 contracts/helpers；remote-connect 已拥有 wire DTO、request builder、tracker state / registry lifecycle、tracker event reduction、dialog submission orchestration port/provider、workspace/session/initial-sync/poll/interaction command orchestration、file IO/path resolution helper、remote file command / response assembly、dialog/cancel/execution accepted response helper、workspace/session response assembly helper、remote model selection policy、remote chat history presentation assembly helper 与 image-context adapter contract；concrete scheduler/session restore/terminal adapter、workspace-root source、persistence/workspace service reads 与 product execution 仍在 core | -| `bitfun-product-domains` | Miniapp 和 function-agent 产品子域 | partial：pure decision、port、MiniApp create/update/draft/apply/import state transition、storage/builtin contract、imported meta timestamp policy、seed meta timestamp policy、runtime detection concrete owner、worker/host/export 纯决策已迁入；filesystem IO、worker process、host dispatch execution、built-in asset seeding、export skeleton 与 Git/AI service runtime 仍在 core | -| `terminal-core` | 已有 terminal package，移动到 workspace 顶层 `src/crates/terminal` 路径 | done：已在 workspace 顶层 | -| `tool-runtime` | 已有 tool runtime，移动到 workspace 顶层路径 | done：已在 workspace 顶层 | - -除非有实测证据证明继续拆分可以减少关键编译目标或测试目标，并且该模块已经具备稳定的 -owner 边界，否则不要把一个 feature group 继续拆成更小的 crate。 - -## 依赖方向规则（Dependency Direction Rules） - -- 新拆出的 crate 不得反向依赖 `bitfun-core`。 -- `bitfun-core` 可以依赖新拆出的 crate，并通过 re-export 保持旧路径兼容。 -- 在声明 P3 边界收敛前，运行 `node scripts/check-core-boundaries.mjs`，确认已拆出的 - owner crate 没有新增 `bitfun-core` 反向依赖，并确认 `core-types`、`runtime-ports` - 和 `agent-tools` 没有引入重 runtime / concrete service 依赖。 -- 已迁移回 `bitfun-core` 的 legacy facade 只能 re-export owner crate 或做窄错误 / 路径注入映射；例如 Git 旧路径、 - remote SSH types/workspace path + unresolved-key helper facade、MCP tool contract facade、MCP protocol types / JSON-RPC - request builder facade、MCP config location / cursor-format / JSON config / config service helper facade、 - MCP server config facade、MCP OAuth auth facade、MCP server process auth/header helper、 - MCP remote transport Authorization normalization / client capability / rmcp mapping helper 和 announcement types facade - 由边界脚本检查，不得重新承载实现逻辑。 -- 对仍嵌在 core runtime 文件中的旧公开类型，必须至少保留禁止回流检查；例如 MCP server - type/status/config 已由 owner crate 拥有，`MCPServerProcess` 只保留 lifecycle、process 和 connection runtime 逻辑。 -- `bitfun-runtime-ports` 必须保持 DTO/trait-only；不得依赖 concrete manager、 - service implementation、app crate 或 platform adapter。 -- remote runtime port baseline 当前只提供契约和 core-owned adapter：`AgentSubmissionPort` - 仍拒绝 generic attachments；remote image DTO、turn cancellation、remote state 和 event facts - 不等于 remote-connect runtime 或多模态执行路径已经迁移。 -- remote-connect command/response wire DTO、remote model catalog DTO / config-shape assembly、 - poll response assembly / model catalog poll delta、 - tracker state / registry lifecycle、remote tool preview slimming、remote model selection policy、legacy image context fallback / - preference、restore target decision、cancel decision、cancel-task orchestration、 - RemoteRelay/Bot dialog submission orchestration port/provider、dialog scheduler outcome assembly、 - workspace/session/initial-sync/poll/interaction command orchestration、 - remote workspace path/MIME/full-read/chunk/info helper、 - remote file command / response assembly、dialog/cancel/execution accepted response helper 与 remote file transfer - size/chunk/name policy、workspace/session response assembly helper、remote chat history presentation assembly helper 可由 - `bitfun-services-integrations` 拥有；core 只保留 tracker host adapter、 - global dispatcher compatibility wrapper、session restore 执行、terminal pre-warm adapter、 - concrete scheduler submit adapter、workspace-root source、persistence/workspace service reads、 - model config loading / model-reference resolver injection、remote chat history projection / image compression / enhanced-input cleanup 与 - `ImageContextData` concrete adapter implementation。 - 不要把 tracker state、wire DTO、dialog orchestration 或纯策略 helper 回写到 core。 -- remote-connect runtime owner 进一步外移前必须保持迁移前快照：remote command/response - shape、restore target、active-turn poll snapshot、cancel decision / cancel orchestration、image context fallback - / preference、tracker fanout、file transfer、RemoteRelay/Bot queue policy，以及 - restore -> terminal pre-warm -> scheduler submit 的 dialog orchestration 顺序。 -- `bitfun-core-types` 不得依赖 runtime manager、service crate、agent runtime、 - app crate、Tauri、network client、process execution，或 `git2`、`rmcp`、`image`、 - `tokio-tungstenite` 等重集成依赖。 -- 轻量 contract crate 不得吸收 CLI/TUI 依赖；`bitfun-cli`、`ratatui`、`crossterm`、 - `arboard`、`syntect-tui` 等仍属于 `src/apps/cli` app adapter / presentation layer。 -- `ErrorCategory`、`AiErrorDetail` 以及纯 AI 错误分类/detail helper 应放在 - `bitfun-core-types` 中，并通过已有更高层路径 re-export 或委托，以保持公开行为稳定。 -- 在剩余 concrete error-wrapper 依赖完成审核前，不要把 `BitFunError` 移入 - `bitfun-core-types`。错误边界中已经移除了 `reqwest::Error` 和 - `tokio::sync::AcquireError` 引用；`serde_json::Error`、`anyhow::Error` 以及历史 - `From` 行为仍需要单独做兼容性处理后，才能移动该类型。 -- Service crate 必须通过小型 port 调用 agent runtime，不要直接访问全局 coordinator。 -- 迁移期间，adapter implementation 可以暂时放在 `bitfun-core` 中，但新的 service - 代码必须面向 port contract，而不是新增对 coordinator 或 manager 的直接依赖。 -- Agent runtime 必须通过 ports/providers 依赖 service 行为，不要依赖 concrete 的重集成 - crate。 -- 最新主干已把 subagent 可见性做成 mode-scoped registry 行为，并且 CLI `/subagents` - 管理入口也复用该查询 / override 语义；后续又新增 `Multitask` mode、内置 - `GeneralPurpose` subagent、`SubagentSessionLinked` routing 和 `Task.run_in_background` 后台结果投递。迁移 agent - registry、subagent definitions 或 agent scheduler 前，必须先保留 mode visibility、 - hidden/custom/review 分组、desktop subagent API、CLI mode-aware list/config、 - background result running-turn injection 与 idle-session follow-up turn 等价测试；在此之前它们仍属于 - `bitfun-core` product runtime assembly 与各 app surface adapter 的组合边界。 -- DeepResearch 现在包含 citation renumber post-turn hook。迁移 agent runtime 或 prompt/report - 处理前，必须保留 `report.md` / `citations.md` / `display_map.json` 的 deterministic post-processing 行为； - 在此之前该 hook 仍属于 `bitfun-core` agent runtime assembly。 -- 最新主干新增 on-demand tool spec discovery。`ToolExposure`、`GetToolSpec` 名称、 - collapsed stub、manifest ordering、generic collapsed exposure query、generic contextual - prompt-manifest resolver、generic catalog snapshot provider、ToolCatalogRuntime / GetToolSpec catalog provider / - prompt / schema / assistant-detail rendering / detail JSON 等 provider-neutral 契约可由 `bitfun-agent-tools` - 拥有；但产品 registry snapshot、`dyn Tool` - / `ToolUseContext` adapter、product collapsed-tool catalog、context-aware tool - schema/description 的实际调用、`GetToolSpecTool` Tool impl / `BitFunError` 映射和 - `ToolUseContext.unlocked_collapsed_tools` 仍属于 `bitfun-core` product tool runtime。 - 继续迁移前必须证明 prompt-visible manifest、expanded/collapsed exposure、unlock state - 与 desktop/MCP/ACP tool catalog 等价。 -- 当前 tool runtime 外移的低风险入口是 `StaticToolProvider` / `install_static_provider` - / `ToolRuntimeAssembly` 合约归属 `bitfun-agent-tools`，并让 core 通过 - `tools/product_runtime.rs` 将内置工具列表收敛为 - `core.basic`、`core.agent`、`core.session`、`core.integration` provider group。 - 这不代表 concrete tools、`ToolUseContext`、product registry snapshot adapter 或 - `GetToolSpecTool` 执行已经迁移。 -- `ToolContextFacts` 只记录 tool call、agent/session/turn、workspace kind/root - 与 runtime restriction 等可移植事实。它不携带 collapsed-tool unlock state、 - `computer_use_host`、workspace services、cancellation token、custom data 或任何 - 可执行 service handle；workspace root 使用 session identity 的 logical path - （remote 为 normalized remote root）。`PortableToolContextProvider` 只是只读 facts - provider 合约，当前由 core `ToolUseContext` 实现；`ToolUseContext` 本体仍归 core 拥有。 -- host path normalization、runtime artifact URI、provider-neutral tool path resolution / - effective absolute-path check、runtime artifact reference assembly 与 remote - POSIX path containment 现在是 - `bitfun-agent-tools` 的纯路径契约；core `workspace_paths` / `restrictions` - 只保留 `BitFunError` 映射、workspace runtime-root lookup、local canonicalize 回调 - 与 `ToolUseContext` 集成。 -- tool allowed-list 与 collapsed tool 的直接执行 gate policy 现在由 - `bitfun-agent-tools` 作为纯契约持有；core pipeline 仍保存 - `ToolUseContext.unlocked_collapsed_tools`，负责失败状态更新与 `BitFunError` - 映射，不改变 `GetToolSpecTool` 执行、runtime restriction 顺序或 unlock state 生命周期。 -- 最新主干的 remote workspace guard 和 search fallback/context 修复提高了 workspace/search - 迁移门槛。后续迁移 workspace 或 search runtime 时，必须保留 remote workspace metadata、 - startup runtime ensure、remote flashgrep fallback、preview mapping 和 local/remote fallback 语义。 -- ACP startup timeout 和 operation diff fallback 属于 ACP/Web product surface 行为；后续只能通过 - stable contract 共享事实，不得把 ACP timeout、tool diff fallback 或 Web diff rendering 下沉到 - core-types、runtime-ports、agent-tools 等 contract crate。 -- 最新主干的 remote ACP agents config 继续强化 ACP/app adapter owner：remote workspace - 复用 local ACP config，并通过 ACP client manager、remote shell、remote capability store 与 - workspace menu 串联。后续只能把 environment / capability facts 抽成 contract；ACP config - persistence、remote probing 和 workspace surface selection 仍留在 ACP/app surface。 -- 最新主干的 usage/cache 与 OpenAI Responses 修复提高了 AI adapter / stream 迁移门槛。 - `cached_content_token_count` 表示 cache reads / hits，`cache_creation_token_count` 与 - DeepSeek `prompt_cache_hit_tokens` mapping 必须保留为独立语义，不能在 `agent-stream`、 - `session_usage` 或 runtime budget 迁移中重新合并为 total usage。OpenAI Responses / - Codex ChatGPT flat tool schema 是 provider adapter serialization，不应写死进 - `bitfun-agent-tools` 的 provider-neutral manifest contract。 -- 2026-05-25 latest main 又新增或强化了多个 runtime 边界，后续计划必须以当前代码为准： - `/goal` 模式的目标生成、custom metadata、post-turn 验证、continuation、事件与 Flow Chat - pending/verifying surface 属于 agent runtime + product surface 组合；file read/edit/write - guardrails、`file_read_state_runtime` 与 `file_tool_guidance` 仍依赖 session-scoped runtime - state 与 `ToolUseContext`；`tool_result_storage` 会写入 session runtime artifact 并替换 - assistant-only 大结果；workspace `related_paths` 会进入 workspace service、remote/local - validation 与 request context prompt；request-context policy、prompt compression 与 cache-stable - assembly 也属于 agent runtime 行为。迁移这些 owner 前必须先同步文档、补保护测试并保留旧路径。 -- 2026-05-28 latest main 进一步把 Task/subagent runtime 变成 fork-aware 语义： - `Task.fork_context=true` 会复用父会话 agent/workspace/tools/prompt cache，但禁止 - `subagent_type`、`workspace_path`、`model_id` 与 DeepReview retry 字段，并且不再是并发安全 - Task 调用。迁移 agent scheduler、subagent runtime、session branch 或 prompt-cache owner 前， - 必须保留 delegation policy、forked context seeding、prompt cache clone、已有上下文 dialog turn - 持久化和递归 subagent 禁止语义。`DialogTriggerSource`、`DialogQueuePriority`、 - `DialogSubmissionPolicy`、`DialogSubmitOutcome`、submit queue routing decision、 - interactive preempt decision 与 agent-session cancel-reply suppression decision 已作为 - runtime-port 契约，`DelegationPolicy` 与 `SubagentContextMode` 也已作为 - DTO/decision primitive 迁入 `bitfun-runtime-ports`，core 保留旧路径 re-export；当前 - boundary check 已锁定 fork-aware Task 启动回执、child delegation policy 和 - `` 结构化标记，防止后续 owner 迁移误删 - assistant-visible delivery contract。 -- 2026-05-28 latest main 还强化了工具可靠性边界：Write 内容生成会拒绝/清理 - tool-invocation syntax，AskUserQuestion / TodoWrite 支持受限 truncation recovery， - `ToolRuntimeRestrictions` 支持 per-tool denial message，`tool_result_storage` 在返回前显式 - flush 持久化文件。迁移 tool pipeline、concrete Write/Edit/Read/Task、runtime artifact 或 - tool-result persistence 时，必须把这些行为作为等价 baseline，而不能只看类型是否可移动。 -- MCP local stdio runtime 的 initialize 现在有局部 timeout、`notifications/initialized` - 发送和 pending waiter drain；该 timeout 不应被误推广成所有 MCP tool/resource request 的 - 默认 request timeout。后续 MCP owner 迁移或服务集成收敛必须保留 initialize/request timeout - 作用域、channel close cleanup 和 remote/local transport 差异。 -- CLI package workflow / Homebrew notifier 与 mobile-web session search、rename、delete 已进入主干。 - 它们扩大了产品矩阵验证范围，但不改变 contract crate 归属：CLI TUI / packaging 仍在 - `src/apps/cli` 和 CI workflow，mobile session 操作仍是 mobile product surface + 既有 session - API 的组合，不应下沉到 `core-types`、`runtime-ports`、`agent-tools` 或 service owner crate。 -- 最新 Web 启动优化把 startup trace、deferred background scheduler、narrow tool initializer - 与历史会话 hydrate 放在 web app / Flow Chat surface。后续不能为了“共享启动能力”把 - `startupTrace`、`backgroundTaskScheduler`、history hydration 或 tool warmup 下沉到 core contract - crate；只能通过 product checks 证明 app 仍可组装。 -- 最新 CLI 重构新增大量 TUI、theme、selector、dialog 和 chat-state 代码，但仍位于 - `src/apps/cli`。后续 core decomposition 只能通过产品 check 验证 CLI 仍可组装，不应把 - CLI presentation 依赖迁入 core-types、runtime-ports 或 agent-tools。 -- 最新 desktop close button 默认最小化到 system tray 是 desktop lifecycle surface 行为； - 后续若调整 desktop app lifecycle / window state，只能用 desktop product check 验证， - 不应把 close/minimize 策略抽入 shared core service。 -- Tool framework crate 不得依赖 concrete service implementation。 -- 产品 crate 可以通过显式 product feature 组装完整 runtime。 -- 后续迁移必须先按风险分层处理： - - 低风险：文档、boundary check、Cargo feature graph / dependency profile 基线、纯 DTO / - contract 搬迁、旧路径 re-export、序列化 round-trip 测试、未启用的新 feature group 声明。 - - 中风险：在 owner crate 内为纯模块补 feature group、把 core 中的重依赖改为 optional 但 - 仍由 `product-full` 启用、把只依赖 port 的 helper 迁入 owner crate。 - - 当前 `product-domains` 可继续承载 MiniApp runtime detection 搜索编排与 concrete PATH / fs / version-process - probe（仅限 `miniapp/runtime.rs` 的受保护 detector owner）、worker install / pool policy、 - package.json storage-shape helper、lifecycle / revision helper、host routing / allowlist / fs access decision helper、 - host fs policy scope / resolved-path decision helper、shell exec cwd / timeout / env / empty-input plan helper、export check result policy、 - customization metadata / permission diff、built-in MiniApp bundle/hash/marker/source payload - seed-decision contract、seed plan / marker wire helper 等决策 / 解析逻辑；实际 - worker process / concrete pool storage、storage IO、PathManager、host dispatch 执行、export skeleton、customization draft 存储 / 应用与 builtin - asset include / seeding / marker IO / recompile 仍留在 core product runtime。最新内置 PR Review - MiniApp 依赖 core asset include、user-data seed、customized update runtime 与 source-hash input - lookup；这些不是 `product-domains` runtime owner 已迁移的证据。 - - `product-domains` 可以先定义 MiniApp runtime/storage 与 function-agent Git/AI 的 port - contract，并承载 function-agent 的纯 prompt / AI response parsing policy；core-owned adapter - 只能在不改变执行路径的前提下委托现有 service，并先补等价测试。IO/进程/AI/Git 执行 owner - 迁移仍属于后续高风险步骤。 - - 2026-05-18 product-domain readiness update: MiniApp draft DTO/response shape, - draft/customization storage path shape, import layout / fallback payload - contracts, manager lifecycle state-transition helpers, runtime executable - search-plan helpers, customization draft-apply / built-in update-decline - metadata policy, and Git function-agent diff truncation / commit prompt - preparation now live in `bitfun-product-domains`. The same PR adds - migration-before snapshots for core-owned MiniApp import / sync / recompile / - rollback / dependency state paths and function-agent Git / AI response - boundaries. Core still owns MiniApp filesystem IO, worker process execution, - built-in asset seeding/source-hash input lookup, host-dispatch execution, - `PathManager` integration, and function-agent Git/AI calls. Function-agent - prompt templates, response JSON extraction, and domain error-mapping policy - may move only with focused behavior-equivalence tests. The built-in MiniApp bundle/hash/marker/source payload - seed-decision contract plus seed plan / marker wire helper can live in - `bitfun-product-domains`, but bundled - asset includes, marker IO, customized update runtime, and recompile - orchestration remain core-owned. - - 高风险：`ToolUseContext`、file read/write state、tool result storage、product tool registry / - runtime manifest assembly / `GetToolSpec` 执行 owner 化、MCP concrete tool integration、 - remote-connect、remote SSH runtime、miniapp / function-agent runtime、goal mode、 - request-context compression/cache、workspace related-path prompt facts、agent registry、`bitfun-core default = []` - 或任何产品 crate feature set 调整。 -- 高风险项不能作为 P2/P3 普通收尾任务顺带执行，必须先有等价性测试、port/provider 设计、 - 旧路径兼容策略和用户确认。 -- 从 2026-05-22 起，后续 PR 不再按 helper / guard / facade 小块拆分；已合入的保护闭环 - 只作为后续高风险迁移的门禁基线，每次 PR 都必须围绕一个完整高风险 owner 主题推进，并在动代码前 - 先写清设计、预保护、验证矩阵和对抗性审核方式。 -- 后续 runtime 迁移以 `docs/plans/core-decomposition-plan.md` 的里程碑表为准，不再按零散 - “剩余 PR 数量”临时拆分。LR1 已闭环为文档/边界/基线校准，不包含 runtime owner - 迁移；后续高风险队列只允许按 H1-H5 的单一 owner 主题推进： - - H1：tool runtime owner 迁移。当前只完成迁移前/迁移中边界收敛：`bitfun-agent-tools` - 承载 provider-neutral tool contract、generic registry/static/dynamic provider、 - contextual manifest resolver、provider-backed tool catalog runtime facade、 - GetToolSpec presentation/schema/static tool surface/detail/ - result assembly / execution-plan helper、provider-backed runtime facade / execution result helper / - Tool-result vector adapter， - generic decorator reference / snapshot-decorator adapter / static-provider runtime assembly - container，以及 generic readonly/enabled registry snapshot filter； - core 仍持有 `ToolUseContext`、`GetToolSpecTool` - Tool impl、collapsed unlock state source、product snapshot wrapper adapter、product registry - snapshot access 与 concrete tools。 - 已合入 PR #803 把 core `Tool` 到 provider-neutral contract 的 adapter 收敛到 - `tool_adapter.rs`；HR1 本轮把 product catalog / manifest / GetToolSpec catalog-detail - provider、static provider materialization 和 snapshot wrapper 注入收敛到 - `product_runtime.rs`；本阶段把 provider-neutral GetToolSpec static tool surface - （name / description / schema / readonly / concurrency / permission / validation / tool-use message）、 - execution plan / result assembly 与 provider-backed execution result helper 收敛到 - `bitfun-agent-tools`；本阶段继续把 provider-backed visible-tools / manifest / readonly - catalog 查询收敛到 `ToolCatalogRuntime`，core 只保留 product registry snapshot、agent - policy、`dyn Tool` / `ToolUseContext` adapter；本阶段继续把 static-provider 安装 assembly 委托到 - `ToolRuntimeAssembly`，并把 product provider group plan 迁入 `bitfun-tool-packs`； - core 只在 `product_runtime.rs` 保留 concrete tool materialization、product snapshot wrapper adapter、product provider/context 注入、 - `GetToolSpecTool` Tool impl、unlock state source 和错误映射；本阶段也把 decorator reference contract、generic snapshot decorator adapter、 - GetToolSpec runtime facade、Tool-result vector adapter 与 readonly enabled filtering 的通用规则委托给 - `bitfun-agent-tools`，不改变工具行为。 - HR-A 本轮已把 latest-main 的 file guidance marker、file-read freshness comparison、 - oversized tool-result preview/rendering policy 与 tool execution result/error/invalid-call presentation policy - 收敛到 provider-neutral `bitfun-agent-tools`， - 并保留 core 对 session-scoped read state、stale-write guardrail 的 coordinator/storage - 绑定，以及 runtime artifact path/reference、assistant-only result compaction、workspace - root/path policy 和实际 filesystem write owner。不能据此声明 `ToolUseContext`、Read/Edit/Write - IO 或 tool-result persistence runtime 已迁出 core。 - - H2：product-domain runtime owner 迁移。MiniApp / function-agent 的纯 DTO/helper/port - facade 已外移；本阶段进一步把 MiniApp runtime detection concrete owner、worker policy、 - host routing / fs / shell plan、export check result policy，以及 function-agent prompt template、AI response JSON - extraction 与 domain error mapping 策略迁入 `product-domains`。filesystem IO、 - worker process、host dispatch execution、export skeleton、built-in asset seeding / marker IO 与 Git/AI 调用仍显式 - core-owned；HR2 进一步将这些 core-owned product-domain runtime 绑定收敛到 - `src/crates/core/src/product_domain_runtime.rs`，不改变实际执行路径。 - - H3：remaining service/runtime owner。remote-connect 已把 dialog submission - orchestration、cancel-task orchestration、terminal pre-warm decision、remote workspace file IO/path helper、 - workspace/session response assembly helper、workspace/session/initial-sync/poll/interaction - command orchestration 与 image-context adapter contract 收敛到 owner crate port/provider； - concrete scheduler/session restore/terminal adapter、workspace-root source、 - persistence/workspace service reads、remote-SSH runtime、agent registry/scheduler 等仍必须 - 另起 port/provider 设计和等价评审；HR3 进一步把这些仍 core-owned 的 - service/agent runtime 绑定入口集中到 `src/crates/core/src/service_agent_runtime.rs`： - remote dialog/cancel/file/workspace/session/poll/interaction/tracker host adapter、remote model catalog/session-model - selection adapter、remote chat history persistence/projection adapter、 - remote image-context conversion 和 coordinator runtime-port binding 均由该入口承载，不改变 remote-connect、 - remote-SSH 或 scheduler 执行路径。 - 本轮进一步把 remote chat history 的 message ordering、tool preview、assistant - presentation assembly 迁入 `bitfun-services-integrations`；core 只把已持久化的 - `DialogTurnData` 投影为 owner DTO，并继续持有 persistence read、mobile image - compression 和 enhanced remote user input cleanup。 - remote model catalog 的 config-shape assembly、dialog scheduler outcome assembly 以及 - remote session/model selection 的 alias/config-reference 归一策略也迁入 - `bitfun-services-integrations`；core 继续负责读取 `AIConfig` 并注入 model reference - resolver。 - HR-C 已把 agent-session reply route、scheduler submit queue decision、interactive - preempt decision、agent-session cancel-reply suppression decision、steering buffered - outcome、round injection kind / target / message / source traits、goal-mode DTO、prompt - compression contract 与 workspace related-path fact 等纯契约迁入 `bitfun-runtime-ports`，core 只保留兼容 - re-export；round injection buffer、scheduler 生命周期、remote-SSH runtime 与 terminal - adapter 仍显式 core-owned。 - 最新 main 的 `/goal` 模式、goal verification events、request-context section policy、 - prompt compression/cache、workspace related-path prompt facts、subagent cancellation 与 - running-turn/continuation 语义必须纳入 HR-C 保护；这些不是普通 DTO 移动项。 - - H4：facade and boundary finalization。当前以 boundary script / AGENTS / architecture - docs 一致性闭环为准，确认 `bitfun-core` 继续作为 legacy facade + full product - runtime assembly；未完成等价评审的 runtime owner 继续显式 core-owned。 - - H5：optional feature/build-benefit evaluation。`bitfun-core default = []`、per-product - feature matrix、依赖版本收敛和构建收益评估只能在 H1-H4 后独立进行。 -- H4 之后的剩余工作口径必须区分“低风险准备已完成”和“后续深度 runtime 迁移”： - 不再把 deferred/core-owned runtime 当作 HR-C 未完成项或零散漏项；若继续外移高风险 owner， - 只允许按 tool runtime、product-domain runtime、service/agent runtime 这 3 个 - 大型 PR 重新评审和实施。H5 仍是单独且可选的 feature/build-benefit evaluation， - 只能在选择继续外移的 HR 项完成或明确 defer 后评估。 -- HR1-HR3 的共同底线是功能影响范围可控、无性能劣化且不改变产品发布形态： - 不修改 default feature、产品 crate feature set、CI/release 覆盖、desktop/installer - build scripts 或任一 surface command/UI 语义；不得新增无界锁、重复 registry / - manifest materialization、额外 network/process startup 或反向 runtime 依赖。HR1 - 重点保护 tool visibility / manifest / unlock / snapshot / Deep Review tool flow； - HR2 重点保护 MiniApp IO/worker/asset seed 与 function-agent Git/AI 时序； - HR3 重点保护 remote workspace/SSH/terminal、scheduler/registry、subagent visibility - 和 DeepResearch post-turn hook。 -- HR1 当前已完成 core 内部 owner closure：`tools/product_runtime.rs` 统一承接 - product provider plan materialization、product registry snapshot/catalog facade、 - manifest / GetToolSpec facade 与 snapshot wrapper 注入。该收口不改变工具执行路径， - 也不声明 `ToolUseContext`、collapsed unlock state、`GetToolSpecTool` Tool impl、 - snapshot runtime 或 concrete tools 已迁出 core。 -- HR1 后续收口进一步把 `ToolUseContext` 本体、portable facts projection、workspace service accessor、runtime artifact - lookup、path policy enforcement、tool pipeline/description/preflight context - materialization、tool-call cancellation/post-call hook wrapper、unified `Tool::call` - runtime hook facade 和 Deep Review light checkpoint 绑定集中到 - core-owned `tools/tool_context_runtime.rs`；`framework.rs` 只保留 `Tool` trait - 与 `ToolUseContext` 旧路径兼容 re-export，core runtime/adapter 模块直接引用 - `tool_context_runtime::ToolUseContext`。该调整仍不迁移 runtime service handles - 或 concrete tool behavior，并通过 remote workspace - containment、runtime URI scope、path policy、task/description/preflight context materialization、 - cancellation hook 与 Deep Review post-call hook 回归测试保护现有工具语义。 -- 当前受保护 HR1 迁移只把 provider-neutral tool path resolution / effective - absolute-path check、runtime artifact reference assembly、path policy root matching 与拒绝消息移入 - `bitfun-agent-tools`；core 仍负责 workspace/runtime root 获取、allowed root - 解析、local canonicalize、remote POSIX containment 回调、`BitFunError` 映射和 - `ToolUseContext` runtime binding。 -- 已完成的 MCP runtime/dynamic tools、remote-connect tracker/wire/pure policy、 - semantic baseline、product-domain port/facade 与 tool contract/helper 外移不得重复规划； - 如果后续发现这些已完成项存在实现错误，应在对应 H 阶段记录问题、风险和修复方案， - 不把行为变更混入当前结构收敛 PR。 -- 已合入的 `Services/Product Runtime Owner Closure` 只收口已经有 port/contract 保护的低风险 owner： - remote-SSH session identity / mirror path / unresolved-session layout 归属 - `bitfun-services-integrations`，MiniApp storage/import file layout、fallback payload - 和纯 lifecycle state transition 归属 `bitfun-product-domains`。 - core 继续持有 SSH manager、remote FS / terminal、MiniApp filesystem IO、worker runtime、 - `PathManager` 注入和兼容 facade；不声明 remote-connect、MiniApp IO、function-agent Git/AI - runtime 或 tool runtime 已迁移。 -- 本轮 product-domain runtime preflight PR 已补等价快照和边界锚点：MiniApp - `import_from_path` / `sync_from_fs` / `recompile` / `rollback` / deps state、 - function-agent staged diff snapshot，以及 function-agent AI response JSON extraction 与 - error mapping 的策略等价测试。H2 仅迁移 function-agent prompt/response policy owner； - 后续若继续移动 MiniApp IO/worker 或 Git/AI 调用 runtime owner，必须以这些快照为行为等价基线。 -- 当前 `product-domains` runtime port/facade closure 只迁移 port-backed owner - orchestration：MiniApp 的 deps/restart/recompile/sync/rollback/import 状态持久化可经 - storage facade 执行；MiniApp create/update/draft/apply 的 version/runtime/meta 组装和 - imported meta identity/timestamp stamping、built-in seed meta timestamp policy 已作为纯状态 helper 归入 `product-domains`； - MiniApp runtime detection concrete owner、worker pool 容量 / idle / LRU policy、 - install-deps plan、host method / fs access / resolved path / shell token / cwd / timeout / env decision、 - export check result policy 也归入 `product-domains`； - function-agent commit / work-state facade 可基于 Git/AI port 组装结果。Git commit-message 与 Startchat work-state 产品路径可通过 core-owned Git/AI - adapter 接入该 facade；Startchat 接线必须保留 legacy git-state、git-diff fallback、 - `analyze_git=false` time-info 与 `analyzed_at` 时序。 - core 仍持有 MiniApp filesystem IO、compiler 调度、worker process、host dispatch execution、export skeleton、 - built-in asset include / seed / marker IO / recompile，以及 function-agent Git/AI service adapter - 和 AI client 调用；`product-domains` 现在承接 function-agent prompt template、AI response JSON - extraction、domain error mapping 与 JSON-to-domain DTO parsing policy。本轮 HR2 只把 - core-owned MiniApp/function-agent runtime 绑定集中到 `product_domain_runtime.rs`，用于 - 统一审查和边界检测；MiniApp IO/worker/host/builtin seed 与 Git/AI 调用没有外移。 - -## 产品表面边界（Product Surface Boundary） - -BitFun 的重构目标不是把 Desktop、CLI、Remote、Server 和 ACP 强行收敛成同一套命令或 UI。 -这些产品表面可以保持不同交互语义，但应逐步共享稳定的运行时事实和能力契约。简短原则是： -**surface divergence, capability convergence**。 - -- Surface presentation 留在 app adapters：Desktop pane / command center、CLI TUI、Remote card、 - ACP protocol 和 Server routes 不进入 `core-types`、`runtime-ports`、`agent-tools` 或 owner runtime crate。 -- 可共享的是 capability contract：session/thread identity、environment identity、permission facts、 - artifact refs、event facts、review/diff/terminal/usage/report 等稳定 DTO，以及必要的 port trait。 -- CLI/Desktop parity 不是迁移 presentation dependency 的理由；`ratatui`、`crossterm`、`arboard`、 - `syntect-tui`、Tauri、Web UI 或 remote card rendering 依赖必须继续留在对应 surface adapter。 -- 命令是产品 affordance，能力是 runtime contract。类似 `/diff`、快捷键、状态卡或协议方法可以映射到 - 同一 capability contract，但不要求共享命令实现。 -- Permission / approval contract 必须能表达来源 surface、thread、turn 和 subagent identity；各 surface - 的审批 UI 可以不同。 -- Product-surface refactor 只能在 contract 层先做 observational DTO / port 补强；若要改变 UI、命令、 - 权限策略或功能逻辑，必须作为单独产品变更 PR，而不是 core decomposition 的副作用。 - -## Feature 安全规则 - -- 在让任何默认 feature 变轻之前，先引入 `product-full`。 -- 当前 `bitfun-core/product-full` 是阶段性 capability guardrail，不是最终 feature matrix - 或 capability source of truth。评估默认 feature 缩减前，必须先生成当前 feature graph baseline。 -- 评估默认 feature 缩减之前，产品 crate 必须显式启用完整产品 runtime。 -- `product-full` 是产品能力保护开关（product capability guardrail），不是新的万能聚合点 - （dumping ground）。每个新的 owner crate 都应暴露具体 feature group；只有为了保持既有 - 产品形态时，`product-full` 才可以包含它们。 -- 最终要么让 `bitfun-core/product-full` 显式聚合已经验证过的 owner crate capability feature， - 要么持续声明它不是完整能力矩阵；不得用它证明未迁移 runtime 已经完成 owner 化。 -- H5 已启动的第一步只允许补齐现有 optional feature 的编译边界。当前先让 - `cargo check -p bitfun-core --no-default-features` 通过，并在 `ssh-remote` 关闭时保留 - remote workspace identity/helper、让实际 SSH/SFTP/terminal/search runtime 返回明确 - unsupported；这不是 remote-SSH runtime owner 迁移，也不改变 `product-full` 或产品发布形态。 -- H5 后续推进只允许把 owner crate feature 传播显式化，保持 - `default = ["product-full"]`、产品 crate `features = ["product-full"]` 和 release/CI - 形态不变。no-default core 可以收敛为 runtime-surface-light facade；`tool-packs` 和 - `product-domains` 可由 core feature 显式启用为 optional dependency，但这不代表整体 - dependency graph 或构建收益已经完成优化。agentic runtime、MiniApp/function-agent、 - Git/MCP/remote-connect/review-platform 等完整产品入口必须继续由 `product-full` 或对应 - owner feature 打开。 -- H5 direct-dependency profile 只能把源码已经由 `product-full`、`service-integrations` - 或 `ssh-remote` 门禁保护的 runtime 依赖改成 optional，并由完整产品 feature 显式启用。 - 当前 no-default 直连层已移除 tool/runtime、snapshot/cron、Git/MCP/remote-connect、 - image/browser-control 和 relay 相关 product-only 依赖，但 `reqwest`、`axum`、 - `tower-http`、`terminal-core`、`zip`、`notify` 等仍因 AI/debug-log/terminal/LSP/search - 等 no-default facade 保留；不得据此声明 `default = []`、per-product feature matrix - 或构建收益已经完成。 -- Boundary check 必须同时保护两个层面：这些 product/runtime 依赖不得回流为 - non-optional dependency，也必须继续由 `product-full`、`service-integrations`、 - `ssh-remote`、`tool-packs` 或 `product-domains` 这些明确 feature owner 显式启用。 - 后续新增 optional dependency 时，必须同步更新 owner feature 规则，避免出现隐式或孤儿 - feature 引用。 -- 当前 boundary check 已把该规则变成全量覆盖检查：凡列入 no-default product/runtime - forbidden list 且仍存在为 optional dependency 的条目，必须在 feature-owner 规则中声明； - owner feature 缺失或未显式启用对应依赖都会失败。 -- Boundary check 也必须保护产品入口的完整能力装配：Desktop、CLI、ACP 对 - `bitfun-core` 的依赖必须保持 `default-features = false` 且显式启用 `product-full`， - 避免产品完整 runtime 退回到隐式默认 feature；脚本会扫描产品入口范围内新增的 - `bitfun-core` 依赖，防止遗漏显式装配规则。 -- 在单独完成产品矩阵评审前，Boundary check 必须继续锁定 - `bitfun-core default = ["product-full"]`，不得把默认 feature 变轻作为依赖裁剪的副作用。 -- `bitfun-core/product-full` 必须继续显式聚合当前 owner feature group：`ssh-remote`、 - `product-domains`、`service-integrations` 和 `tool-packs`，防止完整产品 runtime - 在后续依赖裁剪中被隐式拆散。 -- Boundary check 还必须锁定 owner crate 的 feature graph：`tool-packs`、 - `services-integrations`、`product-domains` 的 `default` 保持空，`product-full` - 只显式聚合当前 owner crate 已声明的 feature group，且不得夹带未纳入规则的 feature - 或 dependency shortcut。`services-integrations` 与 `product-domains` 的 runtime/domain - optional dependency 也必须由对应 feature group 显式拥有，避免 owner crate default-light - 边界回退。 -- Core 的 `service-integrations` feature 当前仍是完整 `product-full` runtime assembly 的一部分， - 不是可单独发布或单独验证的产品形态；MCP/remote-connect/review-platform 仍引用 agentic、 - snapshot 或 product execution owner。若未来要让该 feature 独立可编译，必须先做 - port/provider 设计和等价测试，而不能只补 manifest 依赖。 -- 拆解完成后不要自动移除或减轻 `product-full`。如果未来要用 per-product explicit - feature set 替代它，必须作为 P3 之后的独立评估，并且先通过完整产品矩阵。 -- 不要把 feature 默认值变更和模块移动放在同一个变更中。 -- 不要把改变产品构建产物能力集合作为减少本地测试编译面的副作用。 -- 在任何 feature optionalization 之前，先提交只读保护网：记录 `bitfun-core`、desktop、CLI、 - ACP 和相关 owner crate 的 feature graph，明确哪些目标允许出现 `rmcp`、`git2`、`image`、 - `tokio-tungstenite`、`bitfun-relay-server`、Tauri / CLI presentation 依赖。 -- owner crate 的 `product-full` 只聚合已经迁入且可独立验证的能力；不能为了让产品构建通过， - 让空 scaffold 或未迁移 runtime 假装已经拥有对应能力。 - -## 测试和验证策略（Test And Verification Policy） - -先运行能够证明当前变更的最小验证，再在进入下一个里程碑前运行里程碑门禁。 - -对于保持行为不变的重构： - -- 如果被移动的行为尚未被测试覆盖，先补测试，再移动逻辑。 -- 当模块已经移出 `bitfun-core` 后，优先使用小 crate 测试。 -- 如果变更影响 feature assembly、产品 crate manifest、desktop integration、CLI、 - server 或 transport path，则必须保留完整产品检查。 -- 对功能逻辑偏移风险较高的迁移，必须先补“迁移前快照”测试或脚本输出，例如 tool registry - 工具清单、expanded/collapsed manifest、`GetToolSpec` 插入与 unlock state、 - dynamic provider metadata、snapshot wrapping 覆盖、file read-state freshness、tool result - artifact reference、goal verification events、request-context related-path sections、 - prompt compression/cache event、remote-connect 消息字段、 - MCP tool/resource/prompt wire shape、miniapp permission policy、function-agent 输入输出契约。 -- `product-domains` 与 core runtime 存在双路径阶段时，已抽出的 pure helper 必须配套 core - adapter 等价测试或 snapshot；legacy function-agent runtime 在迁移前仍视为 core-owned - runtime adapter，不得只修改 owner crate 一侧。 -- boundary check 只能证明依赖方向，不能替代产品等价性验证。任何会移动 runtime owner 的 PR - 都必须同时说明旧路径兼容方式、产品能力不变证据和失败时的回滚边界。 -- 编译收益必须和边界收敛分开陈述。若 PR 声明 build/check 收益，需记录 - `cargo check -p bitfun-core`、workspace check 和目标 crate check 的前后数据。 - -对于仅调整文档护栏的变更： - -```powershell -git diff -- package.json scripts/dev.cjs scripts/desktop-tauri-build.mjs scripts/ensure-openssl-windows.mjs scripts/ci/setup-openssl-windows.ps1 BitFun-Installer +| `bitfun-core` | 兼容 facade、agent runtime、tool runtime 组装、service 接线和完整产品能力集合 | 仍是事实上的 runtime owner，迁移必须先保护行为等价 | +| `bitfun-runtime-ports` | 面向 runtime/service 边界的 DTO 和 trait | 只定义 contract，不拥有 runtime 实现 | +| `bitfun-agent-tools` | provider-neutral tool DTO、manifest、path/result policy 和 catalog contract | 已适合承接更多 tool contract，但不应拥有具体 IO tool | +| `tool-runtime` | 既有工具执行相关 crate | 目标是收敛 provider registry、permission gate 和 execution pipeline | +| `bitfun-services-core` | 基础 service helper、本地 filesystem facade、部分通用 service 逻辑 | 适合作为本地基础 service owner，但不能吸收产品 runtime 语义 | +| `bitfun-services-integrations` | MCP、Git、remote-connect、remote-SSH 等 integration helper | 适合拥有外部协议和重依赖 adapter，不应反向感知产品 surface | +| `bitfun-product-domains` | MiniApp、function-agent 等纯状态、策略、port 和部分决策逻辑 | 适合承接 pure domain，不应直接执行 filesystem/Git/AI concrete call | +| `bitfun-acp` | ACP protocol 和 client integration | 应保持 external capability owner，不下沉到 Agent Runtime SDK | +| `transport` / `api-layer` | surface 到 runtime 的 API/transport adapter | 应保持传输层，不拥有 runtime owner | + +## 4. 当前主要问题 + +### 4.1 分层不清晰 + +同一能力经常同时包含 UI/command、runtime orchestration、tool execution、service IO 和 domain +decision。当前代码中这些部分仍大量通过 `bitfun-core` 串联，导致后续迁移时难以判断“移动的是接口、 +实现、组装逻辑还是产品行为”。 + +### 4.2 接口与实现边界不稳定 + +已有 `runtime-ports` 和若干 contract crate，但许多 call site 仍依赖 concrete manager、 +core-owned context 或完整 product runtime snapshot。接口没有稳定到足以让 runtime 与具体 service +实现独立演进。 + +### 4.3 产品形态被完整 core 牵引 + +Desktop、CLI、Server、Remote、ACP 和 Web 的入口差异较大，但当前大多仍通过完整 `bitfun-core` +获得能力。这会让轻量交付形态继承不必要的 tool、service、UI 或平台依赖。 + +### 4.4 Tool contract 与 tool execution 混合 + +provider-neutral manifest、path policy、result policy 已部分外移，但 concrete tool execution、 +`ToolUseContext`、collapsed unlock state、runtime artifact persistence 和产品 catalog 仍在 core。 +工具迁移如果没有快照保护，容易改变 prompt-visible manifest、`GetToolSpec`、MCP/ACP catalog 或 +oversized result 行为。 + +### 4.5 Service、MCP、ACP 与 runtime kernel 容易交叉 + +MCP 和 ACP 是外部协议/能力接入，不应变成 Agent Runtime SDK 的内部协议依赖。Runtime kernel 只应看见 +external capability、tool provider 或 service port；连接生命周期、鉴权、transport 和 timeout 策略应由 +integration owner 或 Product Assembly 管理。 + +### 4.6 扩展点缺少统一语义 + +agent definitions、subagents、skills、prompt modules、tool providers、MCP providers、hooks 和 +product commands 都是扩展点，但目前没有统一表达它们分别属于哪一层、如何注册、是否允许改变行为、 +以及如何做权限和测试保护。 + +### 4.7 feature graph 还不是产品能力矩阵 + +`product-full` 当前是完整产品能力的安全网，不是最终按产品拆分的 feature matrix。直接减轻默认 feature +或把 feature group 当成产品能力边界，都会引入构建形态和发布能力漂移。 + +### 4.8 构建与测试牵引过大 + +重依赖和完整 runtime 聚合在 `bitfun-core` 周围，导致局部测试、owner crate 测试和轻量产品入口容易被 +不相关依赖拖入编译和链接路径。中间阶段不保证每个 PR 都变快，但目标架构必须让依赖收益可度量。 + +## 5. 对照分析 + +本节只提炼对 BitFun 分层有用的架构信号，不把其他项目的实现形态直接复制到 BitFun。 + +### 5.1 Claude Code 相关实现参考 + +Claude Code 相关 Rust 实现参考中，workspace 将 CLI binary、provider API、runtime、tools、 +commands、plugins、telemetry 和 mock harness 拆成不同 crate。其 `runtime` 负责 session、config、 +permission、MCP、prompt 和 runtime loop；`tools` 负责 tool specs 与执行；`commands` 负责 slash command +registry；`plugins` 负责 plugin metadata、hook 和 install/enable/disable surfaces。该结构说明： + +- 工具规格、命令 surface、plugin/hook 和 runtime loop 可以分开演进。 +- permission、MCP lifecycle、task registry、LSP registry 等可作为 runtime/service owner 管理，而不是散落在 UI。 +- 如果 runtime crate 同时吸收 session、MCP、permission、prompt 和 tool bridge，也会变成新的重聚合点。 + +总结：拆分 crate 不是目标本身，关键是让 CLI/TUI、commands、tools、plugins、runtime 和 +service integrations 通过稳定 contract 组合，避免把 `bitfun-core` 的聚合问题搬到新的 runtime crate。 + +### 5.2 Opencode + +Opencode 官方文档展示了更偏产品化的扩展模型：同一个 agent 可以运行在 terminal、desktop 或 IDE； +agents 分为 primary agents 和 subagents，可配置 prompt、model 与 tool access；tools 通过 permission 控制， +并可通过 custom tools 或 MCP servers 扩展；plugins 订阅 command、file、permission、session、tool、TUI +等事件；skills 通过独立目录按需发现和加载。 + +总结： + +- Agent、Tool、MCP、Plugin/Hook、Skill 和 Product Surface 应该是互相连接的扩展面，而不是同一个模块内部的分支。 +- 权限和工具可见性必须是 runtime 可观测的 contract，不能只存在于 UI 或 prompt 拼接中。 +- 多产品形态需要 Product Assembly 做 capability/provider 选择，而不是让 Agent Runtime SDK 判断当前是 + Desktop、CLI、Remote 还是 ACP。 + +## 6. 目标逻辑视图 + +目标架构以层级为入口描述系统。每层只暴露本层 contract，具体实现由上层组装或下层 integration 提供。 + +```mermaid +flowchart TB + Surface["产品入口（Product Surfaces）
UI / command / protocol / route"] + Assembly["产品组装层（Product Assembly）
capability selection / provider registration"] + Capabilities["产品能力层（Product Capabilities）
feature-level capability packs"] + Harness["工作流编排层（Harness Layer）
workflow orchestration"] + AgentRuntime["Agent 运行时 SDK（Agent Runtime SDK）
session / turn / scheduler / prompt / subagent"] + ToolRuntime["工具运行时（Tool Runtime）
manifest / permission / execution / catalog"] + RuntimeServices["运行时服务层（Runtime Services）
typed service bundle / capability availability"] + Integrations["具体实现层（Concrete Integrations）
Tool / OS / Remote / Protocol providers"] + Contracts["稳定契约层（Stable Contracts）
DTO / event / permission / artifact / port"] + External["外部系统（External Systems）
OS / Git / MCP server / ACP client / AI provider"] + + Surface --> Assembly + Assembly --> Capabilities + Assembly --> AgentRuntime + Assembly --> ToolRuntime + Assembly --> RuntimeServices + Assembly --> Integrations + Capabilities --> Harness + Capabilities --> AgentRuntime + Capabilities --> ToolRuntime + Harness --> AgentRuntime + Harness --> ToolRuntime + Harness --> RuntimeServices + AgentRuntime --> ToolRuntime + AgentRuntime --> RuntimeServices + ToolRuntime --> Contracts + RuntimeServices --> Contracts + Integrations --> Contracts + Integrations --> External ``` -期望结果：无 diff。 +## 7. 目标层级 + +目标层级以职责边界为入口。每层可以由多个 crate 承载，关键判断标准是依赖方向、接口归属和实现归属是否清楚。 + +### 7.1 产品入口（Product Surfaces） + +产品入口（Product Surfaces）是用户、协议或外部系统进入 BitFun 的入口，负责展示、路由、协议适配和命令外观。 +它不拥有共享 runtime 行为，只把请求转换为 capability、runtime request 或 transport DTO。 +对应范围是 `src/apps/*`、`src/web-ui` 和 `src/mobile-web`，这些入口可以有形态差异，但差异不能下沉到 runtime。 + +### 7.2 产品组装层（Product Assembly） + +产品组装层（Product Assembly）是唯一的组装入口，负责选择产品能力、tool pack、harness pack、agent definition、 +command provider 和 service provider，并把具体实现注册到稳定接口。迁移期它可以留在 `bitfun-core` +facade 或产品入口中，目标形态可以收敛为独立 assembly crate 或清晰的 facade 模块。 + +### 7.3 产品能力层（Product Capabilities） + +产品能力层（Product Capabilities）描述 Code Agent、Deep Review、DeepResearch、MiniApp、Remote Control、MCP App、 +Computer Use 等能力的组合边界。它负责定义一个产品能力需要哪些 agent、tool、harness、domain policy +和 service capability，不负责 UI，也不直接执行 IO。当前主要落在 `bitfun-product-domains` 和 +`bitfun-core` 的能力组装代码中，后续应收敛为 capability pack 和 domain policy。 + +### 7.4 工作流编排层（Harness Layer） + +工作流编排层（Harness Layer）承载多步骤工作流和策略编排，例如 SDD、Deep Review、DeepResearch、MiniApp 生成或更新流程。 +它可以调用 Agent Runtime SDK、Tool Runtime 和 Runtime Services，但不拥有 session manager 内部状态、 +具体 filesystem/Git/terminal manager 或产品 UI。当前相关逻辑仍分散在 `bitfun-core` 和产品能力中， +目标归属是 `bitfun-harness` 或等价的 harness owner。 + +### 7.5 Agent 运行时 SDK（Agent Runtime SDK） + +Agent 运行时 SDK（Agent Runtime SDK）是可嵌入的 agent kernel，负责 session、turn、scheduler、prompt loop、subagent、 +background task、permission coordination 和 runtime events。它只依赖稳定契约、tool runtime 和注入的 +service ports，不感知 Desktop、CLI、Remote、ACP、Tauri 或 Web UI。当前主体仍在 `bitfun-core`， +目标归属是 `bitfun-agent-runtime`。 + +### 7.6 工具运行时（Tool Runtime） + +工具运行时（Tool Runtime）负责工具 manifest、catalog、permission gate、execution pipeline、tool hook 和结果归一化。 +它只消费 `ToolExecutionServices` 这类窄 service 视图，不直接创建 filesystem、Git、terminal、MCP 等具体实现。 +当前相关 crate 包括 `tool-runtime`、`bitfun-agent-tools`、`bitfun-tool-packs` 以及 `bitfun-core` +中的 tool materialization 代码。 + +### 7.7 运行时服务层（Runtime Services） + +运行时服务层（Runtime Services）是 runtime 可消费的 typed service bundle 和 capability availability 层。它提供 +filesystem、workspace、session store、Git、terminal、network、MCP catalog、remote connection / projection +等端口，不执行产品命令， +不作为无类型 service locator，也不创建平台实现。当前相关 crate 包括 `bitfun-runtime-ports`、 +`bitfun-services-core`、`bitfun-services-integrations` 和 `bitfun-core` 中的 service 接线代码。 + +### 7.8 具体实现层（Concrete Integrations） + +具体实现层拥有外部系统连接和重依赖，但它不是一个混合大筐，需要按实现类型保持边界： +Tool 实现器负责具体 tool provider 和 tool pack；OS 实现器负责 filesystem、terminal、process、network、 +environment 等平台能力；协议实现器负责 MCP、ACP、AI provider、Git 等外部协议；Remote 实现器负责 remote +connection、remote workspace projection 和 remote host capability。 + +Remote 不应作为 Agent Runtime SDK 的内部能力，也不应只按 Desktop/CLI 入口区分。它的稳定接口应拆为 +remote connection、remote workspace、remote filesystem/terminal projection、remote capability facts 等 port； +SSH、relay、本地隧道、远端 OS 差异和认证方式属于具体 Remote provider，由 Product Assembly 按产品形态注册。 +当前相关 crate 包括 `bitfun-services-*`、`bitfun-ai-adapters`、`terminal-core`、`bitfun-acp` 和 app adapters。 + +### 7.9 稳定契约层（Stable Contracts） + +稳定契约层提供跨层共享的数据结构和接口语言，包括 DTO、event、permission facts、artifact refs、identity +和 port traits。它只描述事实和能力，不包含 IO、网络、进程、UI、runtime manager 或产品策略。当前相关 +crate 包括 `bitfun-core-types`、`bitfun-events` 和 `bitfun-runtime-ports`。 + +## 8. 接口与实现关系 + +接口由稳定契约、Runtime Services、Tool Runtime 或 Harness contract 定义；具体实现由产品入口或具体实现层创建； +注册动作只能发生在 Product Assembly。Agent Runtime SDK、Tool Runtime 和 Harness 只接收已经组装好的接口或 +provider registry，不直接创建平台实现。 + +```mermaid +flowchart TB + Surface["产品入口（Product Surfaces）
选择入口和 DeliveryProfile"] + Assembly["产品组装层（Product Assembly）
唯一注册点"] + ServiceBuilder["运行时服务层（Runtime Services）
RuntimeServicesBuilder"] + ToolBuilder["工具运行时（Tool Runtime）
ToolRuntimeBuilder"] + HarnessBuilder["工作流编排层（Harness Layer）
HarnessRegistryBuilder"] + AgentRegistry["Agent 运行时 SDK（Agent Runtime SDK）
AgentDefinitionRegistry"] + CommandRegistry["产品入口 / 产品组装层
ProductCommandRegistry"] + Runtime["Agent Runtime SDK / Tool Runtime / Harness
只消费接口"] + Impl["具体实现层（Concrete Integrations）
Tool / OS / Remote / Protocol providers"] + Contracts["稳定契约层（Stable Contracts）
DTO / event / port trait"] + + Surface --> Assembly + Assembly --> ServiceBuilder + Assembly --> ToolBuilder + Assembly --> HarnessBuilder + Assembly --> AgentRegistry + Assembly --> CommandRegistry + Assembly --> Impl + ServiceBuilder --> Runtime + ToolBuilder --> Runtime + HarnessBuilder --> Runtime + AgentRegistry --> Runtime + CommandRegistry --> Surface + Runtime --> Contracts + Impl --> Contracts +``` + +注册器与前文目标层级的对应关系如下： + +| 注册器 / 组装点 | 所属目标层级 | 目标或迁移期模块 | 注册内容 | +|---|---|---|---| +| `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 | +| `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 | +| `ProductCommandRegistry` | 产品入口（Product Surfaces）与产品组装层（Product Assembly）的边界 | 产品入口或 assembly 模块 | 输入框命令、审核入口、MiniApp 入口到 capability / harness / runtime request 的映射 | +| concrete provider set | 具体实现层（Concrete Integrations） | `bitfun-services-*`、`bitfun-ai-adapters`、`terminal-core`、`bitfun-acp`、app adapters | Tool、OS、Remote、Protocol 的具体 provider；Remote provider 内部继续区分 SSH、relay、本地隧道、远端 OS 支持 | + +注册路径必须是显式、typed、可测试的： -详细计划中列出了各里程碑门禁。没有针对对应门禁的最新验证证据时，不要声明里程碑完成。 +- 产品入口（Product Surfaces）只选择 `DeliveryProfile` 和产品配置，不直接把 concrete manager 传入 runtime。 +- 产品组装层（Product Assembly）根据产品形态创建或接收具体 provider，并调用 typed builder 完成注册。 +- Tool、OS、Remote、Protocol provider 分别留在对应 app 或 integration owner 中，通过同一组 port 暴露。 +- Remote provider 必须拆分稳定连接接口和具体远端 OS / transport 实现，避免把 SSH、relay 或远端平台差异泄漏到 runtime。 +- 不支持的能力在 assembly 的 capability availability 中显式返回 unsupported / unavailable，不在 runtime 内写产品分支。 +- 禁止使用无类型 `Any` service locator、全局 mutable registry 或下层 crate 反向读取产品配置。 -## 冗余清理策略（Redundancy Cleanup Policy） +## 9. 风险 -冗余清理不是主要的编译提速手段。只有在输入、输出、错误路径、副作用、日志、时序和平台 -条件都能证明等价时，才抽取重复逻辑。 +| 风险 | 保护方式 | +|---|---| +| 产品组装层（Product Assembly）膨胀为新的全局状态中心 | assembly 只做构建期注册，输出不可变 runtime parts；产品状态仍归 surface 或 runtime owner | +| 接口拆得过细，导致复杂度和动态分发成本上升 | 以 capability 和稳定用例定义 port 粒度，热路径避免运行时 map lookup，优先 builder-time 注入 | +| 平台实现泄漏到 Agent Runtime SDK、Tool Runtime 或 Harness | 依赖检查禁止 runtime owner 依赖 app crate、Tauri、CLI TUI、ACP protocol 和 concrete service crate | +| 不同产品形态能力矩阵漂移 | Product Assembly 维护 capability matrix；减少或替换能力时补产品入口验证和 unsupported 行为测试 | +| Tool、MCP、ACP 的 manifest、permission 或事件语义迁移后不等价 | 保留旧路径兼容 facade，增加 manifest snapshot、permission 决策和事件映射等价测试 | +| `bitfun-core` 只是改名为新的巨型 runtime crate | 新 owner crate 必须有单一职责和最小依赖；产品能力、harness、service 实现不得继续堆入 agent kernel | +| 目标 crate 先行创建但没有真实 owner | 只有 owner 边界、旧路径兼容、focused tests、依赖收益和 boundary check 同时成立时才创建 crate；否则继续留在 facade | -如果等价性不清晰，就保留重复代码。不要仅仅因为两个流程看起来相似，就创建新的共享抽象。 +## 10. 总结 -冗余清理 PR 必须独立于 crate splitting、feature 默认值变更和依赖升级。 +- 当前架构影响：`bitfun-core` 从事实上的完整 runtime owner 收缩为兼容 facade 和迁移期组装点；Agent Runtime SDK、 + Tool Runtime、Runtime Services、Harness 和 Product Capabilities 分别成为可审查的 owner。 +- 接口与实现边界：稳定契约和各 runtime owner 定义接口，具体 Tool、OS、Remote、Protocol provider 留在具体实现层， + 由产品组装层（Product Assembly）通过 typed builder / registry 注册。 +- Remote 拆分方向：runtime 只依赖 remote connection、remote workspace、remote projection 和 capability facts 等 + port；SSH、relay、本地隧道、远端 OS 差异和认证方式属于具体 Remote provider。 +- 后续工作范围：抽出可独立构建的 runtime kernel；把 service、tool、harness 和 product capability 改为 typed + provider 注册；建立产品形态与 capability matrix 的对应关系。 +- 质量保护：用等价测试保护权限、工具曝光、事件、session、remote workspace 和构建形态不发生功能偏移。 +- 非目标：不改变默认产品能力、命令语义、权限策略或 release 构建形态。 diff --git a/docs/plans/core-decomposition-completed.md b/docs/plans/core-decomposition-completed.md new file mode 100644 index 000000000..904d50d3c --- /dev/null +++ b/docs/plans/core-decomposition-completed.md @@ -0,0 +1,64 @@ +# BitFun Core 拆解已完成内容归档 + +本文只记录已完成事实和明确未完成边界。活跃执行计划见 +[`core-decomposition-plan.md`](core-decomposition-plan.md)。 + +## 1. 已完成主线 + +### 1.1 P0 / P1：安全边界与最小编译面验证 + +- 已建立 `product-full` 默认能力保护，产品 crate 显式启用完整能力。 +- 已把既有 nested `terminal-core` 和 `tool-runtime` 移到 workspace 顶层，保持旧 package / lib 语义。 +- 已抽出 `bitfun-core-types` 第一批纯类型、错误分类和轻量 helper。 +- 已抽出 `bitfun-agent-stream`，让 stream processor 和相关测试可绕开完整 `bitfun-core`。 +- 已引入 `bitfun-runtime-ports` 初始边界和旧路径 compatibility wrapper。 +- 已补 `AgentSubmissionRequest.source` / `turnId` 显式化，以及 dynamic tool provider metadata 基线。 + +明确未完成： + +- `BitFunError` / `BitFunResult` 仍继续 core-owned。 +- remote-connect / cron / MCP concrete call-site、generic attachment / image context 接入、产品逻辑或边界行为变更不属于 P1 完成范围。 + +### 1.2 P2：中等粒度 owner crate 成型 + +- `bitfun-services-core`、`bitfun-services-integrations`、`bitfun-agent-tools`、`bitfun-tool-packs`、`bitfun-product-domains` 已加入 workspace。 +- `bitfun-core` 通过 facade / re-export 保持旧路径兼容。 +- 已迁移 Git feature group、remote-SSH identity / path helper、MCP runtime / dynamic provider、remote-connect wire / tracker / file / image / dialog helper。 +- 已迁移 generic tool registry / provider / catalog / `GetToolSpec` helper 和 product provider plan。 +- 已迁移 MiniApp / function-agent 的纯 domain helper、port / facade 和部分决策逻辑。 +- 已补 `core-types`、`runtime-ports`、`agent-tools`、`product-domains`、`services-integrations` 的 boundary check 和 feature graph 保护。 + +明确未完成： + +- remote-SSH runtime、remote FS / terminal、workspace-root source、persistence / workspace service reads、`ImageContextData` concrete impl 仍未迁移。 +- `ToolUseContext`、runtime manifest / `GetToolSpecTool` execution、collapsed unlock state、concrete tools 仍未迁移。 +- MiniApp filesystem IO / worker / host dispatch / builtin asset runtime、function-agent Git / AI concrete service 仍未迁移。 +- agent registry / scheduler 仍未迁移。 + +### 1.3 H1-H5 基线收口 + +- Tool runtime 已完成 provider-neutral contract、file guidance marker、file-read freshness facts、tool-result storage policy / preview / rendered replacement contract 和 execution presentation policy。 +- Product-domain 已完成 MiniApp 纯状态 owner、runtime detection policy、worker capacity / idle / LRU policy、host method / fs access / shell token / env 等纯决策，以及 function-agent prompt / response policy。 +- Service / agent 已完成 remote-connect presentation assembly、remote model policy、remote command orchestration、dialog scheduler outcome assembly、scheduler queue routing / cancel suppression 等 portable contract closure。 +- Core 内部已形成 `product_runtime.rs`、`product_domain_runtime.rs`、`service_agent_runtime.rs` 等 owner closure 入口，便于后续审查。 +- H5 当前只完成 feature / dependency baseline：`bitfun-core --no-default-features` 可编译面、`product-full` 显式 owner feature 聚合、optional dependency owner 映射和产品入口显式装配检查。 + +明确未完成： + +- H5 不代表 per-product feature matrix、构建收益或 runtime owner 深迁移完成。 +- `bitfun-core default = []` 仍是独立评估项，不能混入 runtime owner 迁移。 +- 具体 IO、scheduler 生命周期、workspace-root、persistence、MiniApp worker / host / builtin、function-agent Git / AI 仍需后续完整 owner PR。 + +## 2. 已建立保护 + +- 新 owner crate 不得依赖回 `bitfun-core`。 +- `product-full` 是完整产品能力保护开关。 +- 构建脚本和 installer 相关脚本不作为 core 拆解的一部分修改。 +- boundary check 覆盖已外移 owner 的旧路径 facade-only / 禁止回流状态。 +- tool manifest、`GetToolSpec`、MiniApp storage layout adapter、product-domain pure helper、remote workspace search fallback、MCP config / catalog / dynamic manifest 等已有 focused baseline。 + +## 3. 当前剩余结论 + +- 低风险准备项已经完成，不再新增零散小 PR。 +- 后续只按高风险 owner 主题推进：Remote / Service-Agent、Agent Registry / Scheduler、Product-Domain Runtime、Tool Runtime、Feature / Build-Benefit Evaluation。 +- 缺陷修复、行为变更、冗余清理、三方库升级和构建脚本调整必须独立评估，不能伪装成 core decomposition 剩余里程碑。 diff --git a/docs/plans/core-decomposition-plan.md b/docs/plans/core-decomposition-plan.md index 764961877..96a31f80a 100644 --- a/docs/plans/core-decomposition-plan.md +++ b/docs/plans/core-decomposition-plan.md @@ -1,2147 +1,153 @@ -# BitFun Core 拆解与构建提速可执行计划 +# BitFun Core 拆解与运行时迁移执行计划 -> **执行约定：** 后续实施本计划时，按完整 owner 主题分步推进。低风险准备项已经收敛，后续 PR 不再提交零散 helper / guard 小块；每个高风险 PR 必须先补设计、预保护、等价验证和对抗性审核方案，再移动 runtime owner。 +本文只记录活跃计划、执行节奏、剩余迁移队列和验收门禁。已完成事实移入 +[`core-decomposition-completed.md`](core-decomposition-completed.md)，避免主计划继续膨胀为历史流水账。 -**目标：** 将当前职责过重的 `bitfun-core` 逐步拆成边界明确、依赖可控、可独立验证的 Rust crate 和能力 feature，同时不改变任何产品功能、CI/release 构建内容、关键构建脚本执行逻辑或各形态产品的依赖范围。 +架构基线见 [`core-decomposition.md`](../architecture/core-decomposition.md)，详细接口和 crate 内部设计见 +[`agent-runtime-services-design.md`](../architecture/agent-runtime-services-design.md)。 -**总体策略：** 采用 Strangler Facade（绞杀者门面）迁移。`bitfun-core` 在迁移期继续作为兼容门面和完整产品 runtime 组装点，旧公开路径尽量保持可用；新的实现逐步迁移到独立 owner crate 中，跨层调用通过端口接口、provider、adapter 连接。 +## 1. 当前判断 -**拆分粒度修正：** 不追求把每个目录都拆成独立 crate。目标是先形成 8 到 12 个中等粒度 owner crate，并在 crate 内用模块和 feature group 继续隔离能力。过多小 crate 会增加 Cargo metadata、check 调度、增量编译管理和测试链接成本，可能抵消一部分优化收益。 +- P0/P1/P2 的低风险准备和 owner container 化已经完成，不再拆成 helper、guard、facade cleanup 小 PR。 +- 当前迁移已经进入高风险 runtime owner 阶段。后续 PR 必须按完整 owner 主题推进，不能把 PR 当作单个 commit 使用。 +- `bitfun-core` 迁移期继续作为兼容 facade 和完整产品 runtime 组装点；新 owner crate 不得依赖回 `bitfun-core`。 +- 目标不是立即让 `bitfun-core default = []`，而是先把接口、provider 注册、旧路径兼容和行为等价保护做实。 +- 产品能力、权限语义、工具曝光、事件语义、session 行为、release / fast build 脚本和各产品形态能力集合不得因迁移改变。 -**核心收益：** +## 2. 迁移关键内容 -- 让单元测试和局部测试可以依赖更小 crate，减少不必要编译和链接。 -- 让重依赖归属到真正需要它们的能力模块，例如 `git2`、`rmcp`、`russh`、`image`、`tokio-tungstenite`。 -- 用 crate 边界和接口阻止新的循环引用，而不是只靠文件夹、注释或团队约定。 -- 为后续依赖版本收敛和 feature 最小化提供稳定边界。 +### 2.1 接口与实现分离 ---- +- 稳定接口属于 Stable Contracts、Runtime Services、Tool Runtime 或 Harness contract。 +- 具体实现按 Tool、OS、Remote、Protocol provider 分类，保留在 app 或 integration owner 中。 +- Product Assembly 是唯一注册点，负责把具体 provider 注入 typed builder / registry。 +- Runtime、Tool、Harness 只消费接口或 registry，不直接创建 filesystem、terminal、MCP、ACP、remote host 等 concrete manager。 -## 0. 不可变更边界 +### 2.2 Runtime owner 拆分 -以下约束优先级高于所有优化收益： +- Agent Runtime SDK：session、turn、scheduler、prompt loop、subagent、background task、permission coordination、runtime events。 +- Runtime Services：filesystem、workspace、session store、Git、terminal、network、MCP catalog、remote connection / projection 等 port 和 capability availability。 +- Tool Runtime：manifest、catalog、permission gate、execution pipeline、tool hook、结果归一化。 +- Harness Layer：SDD、Deep Review、DeepResearch、MiniApp 等多步骤工作流和策略编排。 +- Product Capabilities：Code Agent、MiniApp、function-agent、Remote Control、MCP App、Computer Use 等能力包。 -- 重构期间产品行为不变。 -- `bitfun-desktop`、`bitfun-cli`、`bitfun-server`、`bitfun-relay-server`、`bitfun-acp`、installer 相关构建能力不被削减。 -- 不通过减少 CI 覆盖来换取速度。 -- 不在仓库级默认引入 `.cargo/config.toml` 强制 `sccache`、`lld-link`、`mold` 或其它机器相关工具。 -- 不把 `bitfun-core` 重新包装成另一个 `common`、`shared`、`platform` 式超级 crate。 -- 新拆出的 crate 不允许依赖回 `bitfun-core`。 -- `bitfun-core` 可以依赖新 crate 并 re-export 旧路径，用于兼容。 -- 任何会减少 `bitfun-core` 默认能力的 feature 调整，必须先让所有产品 crate 显式启用等价的完整产品能力。 -- 以下关键脚本不作为 core 拆解的一部分修改： - - `package.json` - - `scripts/dev.cjs` - - `scripts/desktop-tauri-build.mjs` - - `scripts/ensure-openssl-windows.mjs` - - `scripts/ci/setup-openssl-windows.ps1` - - `BitFun-Installer/**` +### 2.3 Remote 拆分原则 -每个阶段合并前必须执行脚本保护检查： +- Remote 不是 Agent Runtime SDK 的内部能力，也不只按 Desktop / CLI 入口区分。 +- 稳定接口应拆为 remote connection、remote workspace、remote filesystem / terminal projection、remote capability facts。 +- SSH、relay、本地隧道、远端 OS 差异、认证方式属于具体 Remote provider。 +- remote workspace、terminal pre-warm、scheduler submit、session restore、file chunk / image fallback 等行为必须用等价测试保护。 -```powershell -git diff -- package.json scripts/dev.cjs scripts/desktop-tauri-build.mjs scripts/ensure-openssl-windows.mjs scripts/ci/setup-openssl-windows.ps1 BitFun-Installer -``` - -期望结果：没有 diff。若某个阶段确实需要改构建脚本，必须从本文计划中拆出，作为独立的显式产品构建变更评审。 - ---- - -## 0A. 架构原则复核与偏移防线 - -后续每个 PR 都必须先对照本节。若发现任意原则无法满足，应暂停该 PR，并将问题拆成更小的前置重构或独立设计评审。 - -### 0A.1 平台边界不能偏移 - -必须保持： - -- product logic 仍保持 platform-agnostic。 -- Tauri、desktop-only、server-only、CLI-only 能力仍留在 platform adapter 或 product assembly 层。 -- shared core、runtime、services crate 不直接引入 `tauri::AppHandle`、desktop API 或其它 host-specific 依赖。 -- Web UI 到 desktop/server 的调用路径仍经过现有 adapter/API/transport 边界。 - -禁止： - -- 为了拆 crate，把 desktop-only 逻辑下沉到 `core-types`、`agent-runtime` 或 `services-core`。 -- 为了方便调用，让新 service crate 反向依赖 app crate。 - -验收方式： - -- 检查新增 crate 的 `Cargo.toml`，确认没有不应出现的平台依赖。 -- 对涉及 desktop/server/CLI 的 PR，执行对应产品 check，而不是只执行新 crate 的测试。 - -### 0A.2 功能集合不能偏移 - -必须保持： - -- `product-full` 是完整产品能力保护开关。 -- 产品 crate 显式启用完整能力后，才允许继续拆能力 feature。 -- `bitfun-core` 的旧公开路径通过 facade 或 re-export 保持 import-compatible。 -- tool registry、MCP dynamic tools、remote SSH、remote connect、miniapp、function agents 的产品可见行为保持一致。 - -禁止： - -- 在同一个 PR 中同时“拆模块”和“改变产品默认能力”。 -- 以减少编译为理由删除 CI 或 release 覆盖。 -- 在没有完整产品矩阵验证前修改 `bitfun-core default`。 - -验收方式： - -- 拆分前记录关键清单，例如 tool registry 工具列表、feature graph、产品 crate 对 `bitfun-core` 的 feature 使用。 -- 拆分后用等价性测试或产品 check 证明能力仍存在。 - -### 0A.3 依赖方向不能偏移 - -必须保持： - -- 新 crate 不依赖回 `bitfun-core`。 -- `bitfun-core` 作为 facade 可以依赖新 crate。 -- service crate 不直接依赖 agent runtime concrete implementation；通过 ports 调用。 -- agent runtime 不依赖 heavy integration concrete service；通过 ports/provider 调用。 -- `core-types` 只承载错误、DTO、port DTO、纯 domain type。 - -禁止： - -- 新增万能上下文，例如 `CoreContext`、`AppContext`，把所有 manager 都挂进去绕过依赖边界。 -- 通过 `pub use` 掩盖实际反向依赖。 -- 在 `core-types` 中引入 IO、网络、进程、Tauri、`git2`、`rmcp`、`image` 等运行时依赖。 - -验收方式： - -- 每个新增 crate 的 `Cargo.toml` 必须能说明依赖原因。 -- 至少在关键 crate 拆出后，用 boundary check 阻止 forbidden imports 回流。 - -### 0A.4 性能方向不能反向 - -本计划不保证每个中间 PR 都立即变快，但不得明显变慢。 - -必须保持： - -- 不新增大量微小 crate；默认目标是 8 到 12 个中等粒度 owner crate。 -- heavy dependency 通过 owner crate 和 feature group 隔离。 -- 局部测试优先落到小 crate，例如 `agent-stream`、`services-core`、`agent-tools`。 -- 不引入团队机器相关的 repo-wide 编译参数或 linker 默认配置。 - -禁止： - -- 为了“架构纯粹”把高频一起变化的模块拆成多个互相调用的小 crate。 -- 为了局部快，把产品完整构建路径变复杂或变脆弱。 -- 在没有实测依据时继续把 feature group 拆成独立 crate。 - -验收方式： - -- 每个里程碑结束时至少对比一次关键目标： - - 新增 crate 数量是否仍在中等粒度范围。 - - 关键局部测试是否能依赖更小 crate。 - - `cargo check -p bitfun-core --features product-full` 没有因为 facade 组装明显恶化。 - - 产品矩阵仍通过。 - -### 0A.5 阶段边界必须明确 - -每个 PR 只能落入以下一种类型： - -- 文档/基线/边界检查。 -- feature 安全网，不移动业务实现。 -- 类型或 port 抽取，不移动重 service。 -- 单个中等粒度 crate 抽取。 -- 单个 feature group 迁移。 -- facade/re-export 收敛。 -- 低风险直接依赖版本收敛。 -- 单个高风险 owner 迁移，且必须先满足 `0A.7` 的设计和保护门禁。 - -禁止： - -- 同一个 PR 同时改 feature 默认值、移动大量模块、调整产品调用路径。 -- 同一个 PR 同时做架构拆分和三方库大版本升级。 -- 同一个 PR 同时修改构建脚本和 core 拆分。 - -暂停条件： - -- 发现需要改变产品行为才能继续。 -- 发现产品 crate 需要减少能力才能编译通过。 -- 发现新 crate 必须依赖回 `bitfun-core`。 -- 发现某个 feature group 拆分会导致多个平台产品使用不同代码路径。 -- 发现构建脚本必须修改才能完成当前拆分。 - -### 0A.6 冗余清理只处理绝对等价逻辑 - -冗余清理不是本计划的主线性能优化。除非能证明逻辑完全等价，否则不因为“看起来类似”就抽公共函数或合并流程。 - -允许处理： - -- 逐行对照后可以证明输入、输出、错误处理、日志、副作用、超时、平台条件完全一致的重复代码。 -- 纯 helper 层重复，例如同一目录内完全一致的常量映射、权限字符串格式化、pairing 过期判断。 -- 有现成测试或可以先补等价性测试的重复逻辑。 - -暂不处理： - -- 不同平台、不同第三方协议、不同产品入口之间只是流程形状相似的代码。 -- MIME by extension 与 MIME by bytes 这类语义不同的检测逻辑。 -- Telegram、Feishu、Weixin 这种 provider 协议逻辑，除非抽取点只覆盖完全一致的本地状态管理。 -- UI 组件或样式中相似但承载不同交互语义的结构。 - -执行要求： - -- 冗余清理必须是独立 PR，不能混入 crate 拆分或 feature 默认值调整。 -- PR 描述中必须列出“等价证明”：调用方、输入、输出、错误路径、副作用是否一致。 -- 如果等价性说不清，宁可保留重复代码。 -- 不为了减少代码行数引入新的公共抽象中心。 - -当前仅作为候选观察，不默认执行： - -- Remote Connect bot 的 pairing store，如果逐行确认 `register_pairing` / `verify_pairing_code` 行为完全一致，可以抽 `BotPairingStore`。 -- filesystem 中 extension-based MIME mapping 和 permission string formatting，如果逐行确认行为完全一致，可以抽本地 helper。 - -这些候选不阻塞里程碑推进，也不应优先于 feature 安全网和 `core-types` / `agent-stream` 拆分。 - -### 0A.7 高风险 owner 迁移 PR 门禁 - -已合入的文档/保护补强只作为后续高风险迁移的门禁基线， -后续 core decomposition PR 默认进入高风险 runtime owner 迁移队列。不得再把单个 helper、单条边界检查或 -小型 facade 移动包装成独立 PR；这些只能作为同一个 owner 迁移 PR 的预保护或收尾。 - -每个高风险 PR 开始写代码前，必须在本文或最近的模块文档中先记录： - -- **Owner 设计：** 当前 core-owned runtime 是什么，新 owner crate / core adapter - 分别负责什么，旧公开路径如何兼容。 -- **行为盘点：** 列出输入、输出、错误映射、日志、异步时序、feature gate、缓存 / - registry / manifest 副作用、产品表面差异。 -- **预保护：** 先补或复用迁移前 snapshot / focused regression / boundary check。 - 没有可执行保护时，不移动 runtime owner。 -- **实施边界：** 每个 PR 只迁移一个 owner 主题；不同时改产品 feature set、 - default feature、构建脚本、UI/命令语义或第三方依赖大版本。 -- **回滚边界：** 保留旧路径 facade 或 core adapter，保证可以回退到 core-owned - runtime 而不影响产品入口。 -- **验证矩阵：** 至少覆盖 owner crate tests、core focused tests、boundary check、 - `cargo check -p bitfun-core --features product-full`，并按影响面增加 desktop / - CLI / ACP / remote / web product checks。 -- **对抗性审核：** 提交前从第三方角度检查是否存在行为漂移、性能劣化、重复 - runtime materialization、锁/任务生命周期变化、产品发布形态变化、依赖方向回流。 - -暂停条件： - -- 需要改变用户可见行为、权限策略、产品命令或默认能力才能完成迁移。 -- owner crate 必须依赖回 `bitfun-core` 才能工作。 -- 等价测试无法表达关键行为，或者只能依赖人工观察确认。 -- 迁移会引入额外进程/网络启动、重复 registry/manifest 构建、无界缓存或更重的 - 默认编译面。 -- 最新 `main` 合入改变了相关 runtime 行为，但文档和保护测试尚未同步。 - -**最新主干行为基线：** - -- `/goal` 模式已经进入主干，包含 AI goal synthesis、session custom metadata、 - post-turn verification events、continuation planning、main-session-only 约束和 Flow Chat - pending/verifying surface。HR-C 与后续 service/agent deep optional 触碰 - scheduler/coordinator/session metadata 时必须先保护这些语义。 -- 文件工具保护已新增 `file_read_state_runtime` / `file_tool_guidance`，Read/Edit/Write - 依赖 session-scoped read state、stale-write guardrail、`ToolUseContext` 和 workspace path - policy。HR-A 不得把这些误归类为 provider-neutral tool contract。 -- `tool_result_storage` 会把超大工具结果写入 session runtime artifact，并向 assistant-only - transcript 注入 preview/reference。HR-A 迁移 tool pipeline、runtime artifact 或 tool-result - adapter 前必须保护存储路径、引用格式、跳过规则和 session view compaction。 -- workspace `related_paths` 已进入 workspace service、desktop/web surface、remote/local - validation 与 request-context prompt。HR-C 与后续 workspace/search 迁移必须保留存储字段、 - canonicalization、remote validation 和 prompt section 输出。 -- request-context policy、prompt compression、prompt-cache friendly assembly 与 OpenAI-compatible - streaming 都提高了 agent runtime / AI adapter 边界门槛；HR-C 与后续 AI/stream 相关工作不得把 - provider-specific reasoning/tool-call schema 写入 provider-neutral manifest。 - -**最新主干补充基线：** - -- `TaskTool` 已支持 `fork_context=true`。该模式复用父会话 agent/workspace/tools/prompt cache， - 但禁止 `subagent_type`、`workspace_path`、`model_id` 和 DeepReview retry 字段，并且 - forked Task 不是并发安全调用。HR-C 与后续 service/agent deep optional 触碰 - scheduler/coordinator/subagent runtime/session branch 前，必须保护 delegation policy、forked context seeding、prompt cache clone、 - `start_dialog_turn_with_existing_context` 和递归 subagent 禁止语义。 -- `DialogTriggerSource` 已复用 `AgentSubmissionSource` 的 `bitfun-runtime-ports` - 契约；`DialogQueuePriority`、`DialogSubmissionPolicy` 与 `DialogSubmitOutcome` - 也已迁入 `bitfun-runtime-ports`。本轮进一步把 scheduler submit queue routing、 - interactive preempt 与 agent-session cancel-reply suppression 的纯决策迁入 - `bitfun-runtime-ports`；core `DialogScheduler` 仍持有队列、active-turn map、round-yield - buffer、outcome loop 和 concrete coordinator submit，不改变执行生命周期。 - `DelegationPolicy` 与 `SubagentContextMode` 已迁入 `bitfun-runtime-ports`，core - `agentic::subagent_runtime` 只保留旧路径 re-export 和 core-owned `queue_timing`。这一步 - 只移动 portable DTO/decision primitive，不移动 scheduler、coordinator、session branch、 - prompt cache 或 background delivery runtime。 -- HR-C portable contract closure 已把 agent-session reply route、steering buffered outcome、 - round injection kind / target / message / source traits、goal-mode DTO、prompt compression - contract 与 workspace related-path fact 迁入 `bitfun-runtime-ports`；core 旧路径只保留 - compatibility re-export，round injection buffer、scheduler 生命周期和 concrete remote/runtime - 继续 core-owned。 -- 工具可靠性最新变化必须纳入 HR-A 或任何 tool pipeline 迁移 baseline：Write 内容生成会拒绝 - tool-invocation syntax；AskUserQuestion / TodoWrite 只在安全边界恢复 truncation； - `ToolRuntimeRestrictions` 支持 per-tool denial message；`tool_result_storage` 写 runtime - artifact 后显式 flush，不能在 owner 迁移中退化为仅依赖 drop。 -- MCP local stdio initialize timeout 已限定在 initialize 阶段，并补充 - `notifications/initialized` 与 pending waiter drain。后续 MCP/service-integrations 迁移不得把 - initialize timeout 扩散为普通 tool/resource request timeout，也不得丢失 channel close cleanup。 -- CLI package workflow / Homebrew notifier 和 mobile-web session search / rename / delete - 已进入产品矩阵。H5 或产品形态验证需要覆盖 `bitfun-cli`、CLI packaging 影响面和 - `pnpm run build:mobile-web`；但 CLI TUI/packaging 与 mobile session UI 仍是 app surface， - 不作为 core/service owner 外移前置条件。 -- `scripts/check-core-boundaries.mjs` 已同步 latest-main 的 fork-aware Task 保护锚点： - `fork_context`、`SubagentContextMode::Fork`、child `DelegationPolicy` 传递、 - `background_task_id` 与 `` 启动回执均在 core - 侧锁定，并禁止 core 重新定义已迁入 `runtime-ports` 的 dialog/subagent portable contract； - 后续迁移 agent runtime 前必须先保留或替换这些等价保护。 -- 同一 guardrail PR 也已把 prompt cache clone、existing-context dialog turn、tool-call - truncation recovery、per-tool denial message、tool-result file flush、MCP - initialize-scoped timeout、`notifications/initialized` 和 pending waiter drain 纳入 - boundary check。后续 HR-A / service/agent deep optional / MCP 迁移不得绕过这些 latest-main 行为基线。 - ---- - -## 1. 当前问题与风险合集 - -### 1.1 `bitfun-core` 已经是完整产品 runtime 聚合 - -现状： - -- `src/crates/core/src/lib.rs` 暴露 `agentic`、`service`、`infrastructure`、`miniapp`、`function_agents`、`util`。 -- `src/crates/core/Cargo.toml` 直接承载大量重依赖，例如 `git2`、`rmcp`、`image`、`notify`、`qrcode`、`tokio-tungstenite`、`bitfun-relay-server`、`terminal-core`、`tool-runtime`。 - -风险： - -- 一个很小的纯逻辑测试也可能触发大块 runtime 依赖编译。 -- `cargo test` 需要为大量测试 target 链接可执行文件，Windows MSVC 下会产生多个 `Microsoft Incremental Linker` 进程。 -- 新功能只要被放进 core，就天然继承整个重依赖图。 - -解决方向： - -- 保留 `bitfun-core` 作为兼容门面。 -- 将实现迁移到明确 owner crate。 -- 测试逐步改为依赖最小 crate，而不是默认依赖完整 core。 - -### 1.2 `service` 与 `agentic` 存在双向耦合 - -观察到的耦合方向： - -- `service -> agentic`：remote connect、MCP、cron、snapshot、config canonicalization、token usage、session usage 等。 -- `agentic -> service`：tools、coordinator、agents、persistence、session、execution、insights 等。 - -风险： - -- 直接把 `service` 和 `agentic` 拆成 crate 会立刻形成循环依赖。 -- 只用文件夹或注释约束不能阻止新代码继续反向引用。 - -解决方向： - -- 先抽取 port trait，再移动实现。 -- 典型端口： - - `AgentSubmissionPort` - - `ToolRegistryPort` - - `DynamicToolProvider` - - `WorkspaceIdentityProvider` - - `SessionTranscriptReader` - - `ConfigReadPort` - - `EventSink` - - `StorageRootProvider` - -### 1.3 feature 边界不完整，不能直接改默认 feature - -现状： - -- `bitfun-core` 当前有 `default = ["ssh-remote"]`。 -- `ssh-remote` 控制 `russh`、`russh-sftp`、`russh-keys`、`shellexpand`、`ssh_config`。 -- 其它重能力多数还是无条件依赖。 - -风险： - -- 如果直接把 default 改轻，可能改变 desktop、CLI、server、ACP 的实际产品能力。 -- Cargo feature 是 additive 的，无法可靠表达“某能力关闭后其它模块就完全不可见”的业务边界。 - -解决方向： - -- 先引入 `product-full`，保持 default 行为不变。 -- 产品 crate 显式启用 `product-full`。 -- 只有在产品显式启用完整能力后，才逐步考虑拆 feature 或调整 default。 - -### 1.4 tool registry 会牵引所有工具实现 - -现状： - -- `agentic/tools/registry.rs` 直接注册所有工具。 -- snapshot service 在 registry 注册阶段参与包装。 -- MCP service 会向全局 registry 注册动态工具。 - -风险： - -- 任何依赖 registry 的测试都会编译所有具体工具及其依赖。 -- registry 成为 service 和 agentic 互相引用的粘合点。 - -解决方向： - -- 拆出 tool framework、registry、tool provider、tool pack。 -- 使用 Provider Registry 和 Decorator： - - `ToolProvider` 注册一组工具。 - - `DynamicToolProvider` 提供 MCP 等动态工具。 - - `ToolDecorator` 处理 snapshot 等横切逻辑。 - -### 1.5 shared type 位于错误层级 - -例子： - -- `util/types/config.rs` 依赖 `service::config::types::AIModelConfig`。 -- `service::session` 使用 `agentic::core::SessionKind`。 -- 远程 workspace identity 同时被 service 和 agentic 使用。 - -风险： - -- 看似基础的类型依赖高层 runtime 模块。 -- 拆 crate 时容易产生循环引用或复制 DTO。 - -解决方向： - -- 建立 `bitfun-core-types`。 -- 只放稳定 DTO、错误类型、轻量 domain type。 -- 不放 manager、service、global registry、IO、runtime orchestration。 - -### 1.6 nested crate 已经存在，但位置仍在 core 内部 - -现状： - -- `src/crates/core/src/service/terminal/Cargo.toml` 包名 `terminal-core`。 -- `src/crates/core/src/agentic/tools/implementations/tool-runtime/Cargo.toml` 包名 `tool-runtime`。 - -风险： - -- 物理路径仍暗示它们属于 core 内部实现。 -- 后续拆分时 workspace 依赖关系不清晰。 - -解决方向： - -- 先移动到 `src/crates/terminal` 和 `src/crates/tool-runtime`。 -- 保持 package/lib 名称不变，降低兼容风险。 - ---- - -## 2. 目标 crate 版图 - -这是目标方向，不要求一个 PR 完成。目标不是把所有 service 都拆成单独 crate，而是先用中等粒度 owner crate 降低编译面，同时避免 crate 数量膨胀。 - -下方列表同时包含“新 owner crate 目标”和已经存在的基础 crate（例如 `events`、`ai-adapters`、`terminal`、`tool-runtime`）。`8 到 12 个中等粒度 owner crate` 的约束主要用于新增拆分边界，不把这些已存在基础 crate 误算成继续拆小的理由。 - -### 2.1 推荐目标：中等粒度合并 - -```text -src/crates/core # 兼容门面 + 完整产品 runtime 组装 -src/crates/core-types # 错误、DTO、port DTO、纯 domain type -src/crates/events # 现有事件定义 -src/crates/ai-adapters # 现有 AI adapter；只接收纯协议 stream 逻辑 -src/crates/agent-stream # stream processor 与相关测试，若无法干净放入 ai-adapters -src/crates/agent-runtime # session、execution、coordination、agent system -src/crates/agent-tools # tool trait、registry、provider contract -src/crates/tool-packs # feature-group 元数据与 provider plan；未来可按 feature group 承载具体工具 -src/crates/services-core # config/session/workspace/storage/filesystem/system 等基础服务 -src/crates/services-integrations # git/MCP/remote SSH/remote connect 等重集成，按 feature group 隔离 -src/crates/product-domains # miniapp、function agents 等产品子域 -src/crates/tool-runtime # 现有 tool-runtime 移出 core 子树 -src/crates/terminal # 现有 terminal-core 移出 core 子树 -``` - -### 2.2 为什么不拆成三十个 crate - -- 每个 crate 都会带来 Cargo metadata、fingerprint、增量编译缓存和 dependency graph 管理成本。 -- `cargo test` 的主要链接压力来自测试二进制数量和每个测试二进制需要链接的代码量；crate 过碎虽然可能减少局部重编译，但也会增加调度和 rlib 组合成本。 -- service 目录中很多模块会一起变化，例如 config/session/workspace/storage，强行拆开会提高跨 crate API 维护成本。 -- 重依赖真正需要隔离的是能力族，而不是文件夹数量。更合理的边界是 `services-core` 与 `services-integrations`，再用 feature group 控制 `git`、`mcp`、`remote-ssh`、`remote-connect`。 - -### 2.3 何时允许继续拆小 - -只有满足以下条件之一，才把中等粒度 crate 继续拆小： - -- 该能力有独立重依赖，并且大多数测试不需要它。 -- 该能力的变更频率和 owner 明显独立。 -- 该能力已经通过 port/provider 与其它模块解耦。 -- 实测显示拆分后能减少关键测试或 check 的编译面。 - -不满足这些条件时，优先用同一 crate 内的模块、feature group 和边界检查约束。 - ---- - -## 3. 模块覆盖矩阵 - -拆解时不能遗漏当前 core 模块。下表给出每个模块的中等粒度目标归属。 - -| 当前模块 | 目标 owner | 说明 | -|---|---|---| -| `util::errors` | `bitfun-core-types` | `BitFunError`、`BitFunResult`，不包含 runtime | -| `util::types` | `bitfun-core-types` / `bitfun-ai-adapters` | 纯 DTO 入 types，AI 协议 DTO 优先留在 ai-adapters | -| `util::types::ai` 和 provider 协议 DTO | `bitfun-ai-adapters` | provider 请求/响应、stream 协议和 adapter-owned DTO 留在 AI adapter 边界内 | -| `util::process_manager` | `bitfun-services-core` | 涉及进程执行，不进入纯 types | -| `infrastructure::app_paths` | `bitfun-services-core` | 通过 `StorageRootProvider` 暴露 | -| `infrastructure::events` | `bitfun-events` / transport | 事件定义和发送抽象从 core 解耦 | -| `infrastructure::ai` | `bitfun-ai-adapters` + assembly | 通过 `ConfigReadPort` 消除反向依赖 | -| `infrastructure::storage` | `bitfun-services-core` | 依赖路径抽象，不依赖全局 core | -| `infrastructure::filesystem` | `bitfun-services-core` | 本地/远程文件系统通过 provider 隔离 | -| `infrastructure::debug_log` | `bitfun-services-integrations` feature `debug-log` | HTTP server 依赖需要 feature-gate | -| `service::config` | `bitfun-services-core` | agent/tool canonicalization 移到 runtime assembly | -| `service::session` | `bitfun-services-core` | `SessionKind` 等共享类型先移入 types | -| `service::workspace` | `bitfun-services-core` | workspace identity 独立 | -| `service::workspace_runtime` | `bitfun-services-core` | workspace runtime layout owner | -| `service::remote_ssh` | `bitfun-services-integrations` feature `remote-ssh` | 第一批重依赖隔离候选 | -| `service::mcp` | `bitfun-services-integrations` feature `mcp` | 动态工具通过 provider 注入 | -| `service::remote_connect` | `bitfun-services-integrations` feature `remote-connect` | 依赖 agent submission port | -| `service::git` | `bitfun-services-integrations` feature `git` | `git2` 边界清晰，适合早拆 | -| `service::lsp` | `bitfun-services-core` feature `lsp` | 依赖 workspace/runtime port | -| `service::search` | `bitfun-services-core` feature `search` | 依赖 workspace/filesystem provider | -| `service::snapshot` | `bitfun-services-core` feature `snapshot` | tool wrapping 改为 decorator | -| `service::cron` | `bitfun-services-core` feature `cron` | 调 agent runtime 通过 `AgentSubmissionPort` | -| `service::token_usage` | `bitfun-services-core` | 只依赖事件和 usage DTO | -| `service::session_usage` | `bitfun-services-core` | 依赖 transcript 边界 | -| `service::project_context` | `bitfun-services-core` | 避免直接依赖 coordinator | -| `service::announcement` | `bitfun-services-integrations` feature `announcement` | 远程 fetch 依赖独立 feature-gate | -| `service::filesystem` | `bitfun-services-core` | 本地/远程 provider | -| `service::file_watch` | `bitfun-services-integrations` feature `file-watch` | `notify` 依赖独立 | -| `service::system` | `bitfun-services-core` | 命令检测和执行 | -| `service::runtime` | `bitfun-services-core` | runtime capability detection | -| `service::i18n` | `bitfun-services-core` | config 依赖保持单向 | -| `service::ai_rules` | `bitfun-services-core` | 只依赖 paths/storage | -| `service::ai_memory` | `bitfun-services-core` | 只依赖 paths/storage | -| `service::agent_memory` | `bitfun-agent-runtime` 或 `bitfun-services-core` | prompt helper 随 runtime/prompt builder 迁移 | -| `service::bootstrap` | `bitfun-services-core` | workspace persona bootstrap | -| `service::diff` | `bitfun-core-types` 或 `bitfun-services-core` | 纯 diff 可入 types，否则入 services-core | -| `agentic::core` | `bitfun-agent-runtime` + `bitfun-core-types` | DTO 入 types，行为入 runtime | -| `agentic::events` | `bitfun-events` + runtime router | 事件定义不留在 core | -| `agentic::execution` | `bitfun-agent-runtime`，stream 可入 `bitfun-agent-stream` | stream processor 先拆以验证收益 | -| `agentic::coordination` | `bitfun-agent-runtime` | 依赖 service port，不依赖具体 service | -| `agentic::session` | `bitfun-agent-runtime` | persistence/config 通过 port | -| `agentic::persistence` | `bitfun-agent-runtime` + `bitfun-services-core` | DTO storage 和 orchestration 分离 | -| `agentic::agents` | `bitfun-agent-runtime` | registry 通过 config port | -| `agentic::tools::framework` | `bitfun-agent-tools` | 不包含具体工具实现 | -| `agentic::tools::registry` | `bitfun-agent-tools` | provider-based registration | -| `agentic::tools::implementations` | `bitfun-tool-packs` | 同一 crate 内按 feature group 分模块 | -| `agentic::deep_review_policy` | `bitfun-agent-runtime` | config input 通过 port | -| `agentic::fork_agent` | `bitfun-agent-runtime` | runtime concern | -| `agentic::round_preempt` | `bitfun-agent-runtime` | runtime concern | -| `agentic::image_analysis` | `bitfun-tool-packs` feature `image-analysis` 或 runtime feature | 隔离 `image` 依赖 | -| `agentic::side_question` | `bitfun-agent-runtime` | runtime concern | -| `agentic::insights` | `bitfun-agent-runtime` feature `insights` | 依赖 config/i18n/session ports | -| `agentic::workspace` | `bitfun-core-types` + `bitfun-agent-runtime` | remote identity DTO 入 types | -| `miniapp` | `bitfun-product-domains` feature `miniapp` | desktop API 先走 core facade | -| `function_agents` | `bitfun-product-domains` feature `function-agents` | 依赖 runtime 和 service ports | - ---- - -## 4. 设计模式与关键接口 - -### 4.1 Facade：保留旧路径，不让迁移影响调用方 - -`bitfun-core` 迁移期只做兼容门面和完整 runtime 组装： - -```rust -//! Compatibility facade and full product runtime assembly. -//! -//! New implementation code should live in owner crates under `src/crates/*`. -//! This crate re-exports legacy paths and wires the full BitFun product runtime. -``` - -旧路径示例： - -```rust -pub mod service { - pub use bitfun_services_git as git; -} -``` - -要求： - -- 新实现不继续堆到 `bitfun-core`。 -- re-export 必须加注释说明这是兼容层。 -- 不要把 facade 变成新的业务实现聚合。 - -### 4.2 Dependency Inversion：先抽接口，再移动实现 - -示例端口： - -```rust -#[async_trait::async_trait] -pub trait AgentSubmissionPort: Send + Sync { - async fn submit_user_message( - &self, - request: AgentSubmissionRequest, - ) -> Result; -} -``` - -使用原则： - -- service crate 调 agent runtime 时，只依赖 port。 -- agent runtime 调 config/session/workspace 时，也只依赖 port。 -- port DTO 必须在 `core-types` 或专门的 `runtime-ports` crate 中，不能依赖 concrete manager。 - -### 4.3 Provider Registry：工具按能力包注册 - -示例： - -```rust -pub trait ToolProvider: Send + Sync { - fn provider_id(&self) -> &'static str; - fn register_tools(&self, registry: &mut dyn ToolRegistryPort) -> BitFunResult<()>; -} -``` - -使用原则： - -- `agent-tools` 只包含 tool trait、context、registry、provider contract。 -- `tool-packs` 当前只拥有 feature-group 元数据和 product provider group plan；具体工具实现迁移必须在后续高风险 owner 设计中按单一 feature group 处理。 -- 产品完整 runtime 由 assembly 层安装所有 provider，保证产品行为不变。 - -### 4.4 Decorator：snapshot 等横切逻辑不侵入 registry - -示例： - -```rust -pub trait ToolDecorator: Send + Sync { - fn decorate(&self, tool: Arc) -> Arc; -} -``` - -使用原则： - -- snapshot service 不再直接改 registry 内部实现。 -- registry 支持 decorator chain。 -- 产品完整 runtime 默认安装同等 snapshot wrapping，保持原行为。 - -### 4.5 Adapter：平台差异留在产品 adapter 层 - -要求： - -- Tauri、desktop-only、server-only、CLI-only 逻辑不下沉到纯 domain crate。 -- platform adapter 组装 runtime 后，通过 `bitfun-core` facade 或明确 concrete crate 暴露。 -- shared product logic 仍保持 platform-agnostic。 - ---- - -## 5. 分阶段执行计划 - -### Plan 0：基线与安全护栏 - -**目的：** 在开始移动代码前建立可度量基线和团队约束。 - -**文件范围：** - -- 新增：`docs/architecture/core-decomposition.md` -- 修改：`AGENTS.md` -- 修改：`src/crates/core/AGENTS.md` - -**任务：** - -- [x] 记录依赖和构建基线，生成文件只放 `target/`，不提交。LR1 已重新生成 - `target/core-decomposition-metadata-baseline.json`、 - `target/core-decomposition-core-duplicates.txt` 和 - `target/core-decomposition-desktop-features.txt`；这些文件只作为本地基线，不提交。 - -```powershell -cargo metadata --format-version 1 --locked > target/core-decomposition-metadata-baseline.json -cargo tree -p bitfun-core -d > target/core-decomposition-core-duplicates.txt -cargo tree -p bitfun-desktop -e features > target/core-decomposition-desktop-features.txt -cargo test -p bitfun-core --no-run --timings -``` - -- [x] 在 `docs/architecture/core-decomposition.md` 记录 invariants、crate 归属、禁止依赖规则。 -- [x] 在 `AGENTS.md` 增加短链接，说明 core 拆解期间先看架构文档。 -- [x] 在 `src/crates/core/AGENTS.md` 增加约束： - -```markdown -During core decomposition, `bitfun-core` is a compatibility facade. New modules -should prefer the extracted owner crate listed in `docs/architecture/core-decomposition.md`. -Do not add new cross-layer references from `service` to `agentic` without a port. -``` - -- [x] 执行脚本保护检查。 - -**验证：** - -```powershell -git diff -- package.json scripts/dev.cjs scripts/desktop-tauri-build.mjs scripts/ensure-openssl-windows.mjs scripts/ci/setup-openssl-windows.ps1 BitFun-Installer -``` - -**风险与处理：** - -- 风险：基线命令在低性能机器耗时较长。 -- 处理：只在需要建立基线的机器运行；生成文件不提交；普通开发者不强制执行 timing。 - ---- - -### Plan 1：引入 `product-full` feature 安全网 - -**目的：** 在任何默认 feature 变轻之前，先让产品 crate 显式声明完整能力，避免多形态产品构建内容被意外改变。 - -**文件范围：** - -- 修改：`src/crates/core/Cargo.toml` -- 修改：`src/apps/desktop/Cargo.toml` -- 修改：`src/apps/cli/Cargo.toml` -- 修改：`src/crates/acp/Cargo.toml` -- 不修改：`src/apps/server/Cargo.toml`，除非它已经在当前产品构建中显式依赖 `bitfun-core` -- 不修改：`src/apps/relay-server/Cargo.toml`，除非它已经在当前产品构建中显式依赖 `bitfun-core` - -**任务：** - -- [x] 在 `bitfun-core` 中新增 `product-full`，但保持当前 default 行为不变。 - -```toml -[features] -# Full product runtime feature set. Product binaries must depend on this -# explicitly before `bitfun-core` default features are made lighter. -default = ["product-full"] -product-full = ["ssh-remote"] -tauri-support = ["tauri"] -ssh-remote = ["russh", "russh-sftp", "russh-keys", "shellexpand", "ssh_config"] -``` - -- [x] 产品 crate 显式启用完整能力。 - -```toml -bitfun-core = { path = "../../crates/core", default-features = false, features = ["product-full"] } -``` - -- [x] 这个阶段禁止把 `default` 改成空。 -- [x] 为 `product-full` 增加注释，说明它是多形态产品能力保护开关。 -- [x] 只更新当前已经依赖 `bitfun-core` 的 crate。不要为了统一写法给 server 或 relay-server 新增 `bitfun-core` 依赖。 - -**生命周期说明：** - -- `product-full` 是迁移期和发布期的完整能力保护开关，不是新功能的万能聚合点。新增 owner crate 时，必须先定义具体 feature group，再由产品完整 runtime 显式选择是否纳入 `product-full`。 -- P3 结束前不评估移除或减轻 `product-full`。如果未来希望用更细粒度的 per-product feature set 替代它，必须作为独立发布风险评估执行，并先通过完整产品矩阵。 -- 不允许在模块移动 PR 中同时做 `product-full` 淘汰、`default = []` 或产品能力裁剪。 - -**验证：** - -```powershell -cargo check -p bitfun-core --features product-full -cargo check -p bitfun-desktop -cargo check -p bitfun-cli -cargo check -p bitfun-server -cargo check -p bitfun-acp -cargo check --workspace -``` - -**风险与处理：** - -- 风险：某产品 crate 之前依赖隐式 default，现在路径写错导致能力缺失。 -- 处理：每个产品 crate 单独 check；不改构建脚本；不减少 release feature。 - ---- - -### Plan 2：把现有 nested crate 移到 workspace 顶层 - -**目的：** 先处理已经是 crate 的模块，降低后续拆分歧义，且风险较低。 - -**文件范围：** - -- 移动：`src/crates/core/src/service/terminal` -> `src/crates/terminal` -- 移动：`src/crates/core/src/agentic/tools/implementations/tool-runtime` -> `src/crates/tool-runtime` -- 修改：workspace 根 `Cargo.toml` -- 修改：`src/crates/core/Cargo.toml` -- 必要时修改：旧路径 re-export - -**任务：** - -- [x] 移动 `terminal-core` 目录到 `src/crates/terminal`。 -- [x] 保持 package name `terminal-core` 和 lib name `terminal_core` 不变。 -- [x] 移动 `tool-runtime` 到 `src/crates/tool-runtime`。 -- [x] 保持 package name `tool-runtime` 和 lib name `tool_runtime` 不变。 -- [x] 更新 workspace members。 -- [x] 更新 `src/crates/core/Cargo.toml` path： - -```toml -terminal-core = { path = "../terminal" } -tool-runtime = { path = "../tool-runtime" } -``` - -- [x] 在旧 re-export 点加关键节点注释： - -```rust -// Terminal is implemented in the workspace-level `terminal-core` crate. -// This re-export preserves the legacy `bitfun_core::service::terminal` path. -pub use terminal_core as terminal; -``` - -**验证：** - -```powershell -cargo check -p terminal-core -cargo check -p tool-runtime -cargo check -p bitfun-core --features product-full -cargo check --workspace -``` - -**风险与处理：** - -- 风险：路径移动影响相对路径、测试 fixture 或 include。 -- 处理：保持 package/lib 名称不变；只改 Cargo path；不改行为。 - ---- - -### Plan 3：抽取 `bitfun-core-types` - -**目的：** 建立真正底层的共享类型 crate，让后续服务和 agent runtime 不需要依赖 `bitfun-core`。 - -**文件范围：** - -- 新增：`src/crates/core-types/Cargo.toml` -- 新增：`src/crates/core-types/src/lib.rs` -- 新增：`src/crates/core-types/src/errors.rs` -- 后续按依赖确认再新增：`session.rs`、`workspace.rs`、`config.rs` -- 修改：workspace 根 `Cargo.toml` -- 修改：`src/crates/core/Cargo.toml` -- 修改：旧模块 re-export - -**第一批只移动：** - -- 纯 error DTO：`ErrorCategory`、`AiErrorDetail` -- 纯 AI 错误分类/detail 构造 helper -- 已去除 runtime/network 依赖后的 `BitFunError`（当前未移动） -- 已去除 runtime/network 依赖后的 `BitFunResult`（当前未移动） -- 已确认无 runtime 依赖的 session/workspace/config DTO - -**第一批禁止移动：** - -- manager -- global service -- registry -- 文件 IO -- process spawning -- async runtime orchestration -- 任何需要 Tauri、git2、rmcp、reqwest、image 的类型实现 - -**任务：** - -- [x] 建立轻依赖 crate，当前只允许 `serde`： - -```toml -[dependencies] -serde = { workspace = true } -``` - -- [x] 先把 `ErrorCategory` / `AiErrorDetail` 抽到 `core-types`，并由 `bitfun-events::agentic` re-export 保持旧路径不变。 -- [x] 把 AI 错误分类和 detail 构造 helper 下沉到 `core-types`，`BitFunError::error_category` / `error_detail` 只做委托。 -- [x] 将原本依赖完整 `bitfun-core` 的 AI 错误分类测试迁移到 `bitfun-core-types` 单元测试，作为后续错误边界移动的轻量保护。 -- [x] 先拆解 `BitFunError` 的 runtime/network 依赖边界。`reqwest::Error` 已改为字符串承载，`tokio::sync::AcquireError` 已改为调用点显式映射，错误模块不再直接引用这两个类型。 -- [x] LR1 已复核 `BitFunError` 剩余 concrete error-wrapper 依赖。当前仍保留 - `serde_json::Error`、`anyhow::Error`、`std::io::Error` 和相关 `From` 兼容行为； - 处理决策是继续 core-owned，不在 LR1 字符串化或改变错误边界。 -- [x] `BitFunError`、`BitFunResult` 迁移标记为 deferred：只有当错误类型不再需要 - concrete wrapper，或单独 PR 明确接受 `core-types` 的轻量 error 依赖后才可移动。 -- [x] `BitFunError` 移动后的旧路径 re-export 约束已记录；实际 re-export 只在未来迁移 PR 执行： - -```rust -pub use bitfun_core_types::errors::{BitFunError, BitFunResult}; -``` - -- [x] crate 顶部增加边界注释： - -```rust -//! Shared BitFun domain types. -//! -//! This crate must not depend on `bitfun-core`, service crates, agent runtime, -//! platform adapters, process execution, or network clients. -``` - -- [x] 已移动第一批 shared DTO/helper，并确认依赖方向为 `bitfun-events -> bitfun-core-types`、`bitfun-core -> bitfun-core-types`。 -- [x] LR1 已校准后续 shared DTO 归属：当前没有适合继续批量移动的 DTO。后续只能按 - 单个 owner/单个 DTO 推进，并在移动时确认依赖方向。 - -**当前状态：** Plan 3 是部分完成。`ErrorCategory`、`AiErrorDetail` 和第一批纯 helper 已进入 `core-types`；LR1 已明确 `BitFunError` / `BitFunResult` 继续 core-owned，后续 DTO 不批量移动。未完成迁移不阻塞低风险准备闭环，但会阻塞“错误类型完全归属 core-types”的完成声明。 - -**验证：** - -```powershell -cargo test -p bitfun-core-types -cargo check -p bitfun-core --features product-full -cargo check --workspace -``` - -**风险与处理：** - -- 风险：把带行为的类型误放入 types，导致 types 变重。 -- 处理：核心判断是“是否需要 IO、全局状态、网络、平台 API、runtime manager”。需要则不能进入 types。 -- 当前阻塞：`BitFunError` 还带有 `serde_json::Error` / `anyhow::Error` concrete wrapper 和 `From` 兼容行为。先保持在 `bitfun-core`，后续单独评估是把这些 wrapper 字符串化，还是允许 `core-types` 引入轻量 error 依赖后再移动。 - ---- - -### Plan 4：抽取 `bitfun-agent-stream` - -**目的：** 让 stream processor 相关测试脱离完整 `bitfun-core`，这是较容易验证构建提速收益的拆分点。 - -**文件范围：** - -- 新增：`src/crates/agent-stream/Cargo.toml` -- 新增：`src/crates/agent-stream/src/lib.rs` -- 移动/适配：`src/crates/core/src/agentic/execution/stream_processor.rs` -- 移动/适配测试： - - `src/crates/core/tests/stream_processor_openai.rs` - - `src/crates/core/tests/stream_processor_anthropic.rs` - - `src/crates/core/tests/stream_processor_tool_arguments.rs` - - `src/crates/core/tests/stream_replay_regressions.rs` - - 相关 fixture/helper -- 修改：`src/crates/core/src/agentic/execution/mod.rs` -- 修改：`src/crates/core/Cargo.toml` -- 修改：workspace 根 `Cargo.toml` - -**任务：** - -- [x] 创建 `bitfun-agent-stream`，依赖控制在 stream 所需范围： - -```toml -anyhow = { workspace = true } -async-trait = { workspace = true } -bitfun-events = { path = "../events" } -bitfun-ai-adapters = { path = "../ai-adapters" } -futures = { workspace = true } -serde = { workspace = true } -tokio = { workspace = true } -tokio-util = { workspace = true } -serde_json = { workspace = true } -log = { workspace = true } -uuid = { workspace = true } -``` - -- [x] 移动 stream result/error/context processor。 -- [x] 消除对 `crate::agentic` 的直接引用，改为依赖 `bitfun-events`、`bitfun-ai-adapters`。 -- [x] 旧路径 compatibility wrapper： - -```rust -//! Compatibility wrapper for the extracted agent stream processor. - -pub struct StreamProcessor { - inner: bitfun_agent_stream::StreamProcessor, -} -``` - -- [x] stream 测试迁移到 `src/crates/agent-stream/tests`，fixture harness 改为测试内事件 sink，不再依赖完整 `bitfun-core`。 - -**验证：** - -```powershell -cargo test -p bitfun-agent-stream -cargo test -p bitfun-core --lib stream_processor -cargo check -p bitfun-core --features product-full -cargo check --workspace -``` - -**风险与处理：** - -- 风险：stream test 依赖旧 core test helper。 -- 处理：只迁移 stream 所需 fixture；不要把 core test helper 整体搬成新重依赖。 - ---- - -### Plan 5：引入 runtime ports，准备打断 `service <-> agentic` 循环 - -**目的：** 在真正移动 service crate 之前，先建立可替换的 cross-layer 调用边界；具体 service call-site 迁移按后续 owner crate 阶段逐步完成。 - -**文件范围：** - -- 新增：`src/crates/core-types/src/ports.rs` 或独立 `src/crates/runtime-ports` -- 修改：`src/crates/core/src/service/remote_connect/**` -- 修改：`src/crates/core/src/service/mcp/**` -- 修改：`src/crates/core/src/service/cron/**` -- 修改：`src/crates/core/src/service/snapshot/**` -- 修改：`src/crates/core/src/agentic/tools/registry.rs` -- 修改：`src/crates/core/src/agentic/coordination/**` - -**任务：** - -- [x] 先定义 port DTO 和 trait，不移动大模块。 -- [x] 新增独立轻量 `bitfun-runtime-ports`，只包含 DTO / trait，不依赖 `bitfun-core`、manager、service concrete、app crate 或平台 adapter。 -- [x] 为 `ConversationCoordinator` 提供 `AgentSubmissionPort` / `SessionTranscriptReader` adapter，作为 remote connect / service 后续迁移入口。 -- [x] 为 `ConversationCoordinator` 提供 `AgentTurnCancellationPort` / `RemoteControlStatePort` adapter，复用现有取消与 session state 读取语义，不引入新的队列或取消策略。 -- [x] 为 `ToolRegistry` 提供 `DynamicToolProvider` adapter。 -- [x] 用 `ToolDecorator` 注入 registry 注册装饰入口，保留默认 snapshot wrapping 行为。 -- [x] 为 `ConfigService` 提供 `ConfigReadPort` adapter，先建立读取边界，不移动 config service。 -- [x] 新增 `RuntimeEventEnvelope` / `RuntimeEventSink` 观测事件契约，当前只作为后续 remote runtime 解耦入口，不注册新的运行时事件发布实现。 -- [x] LR1 已复核 remote connect / cron / MCP concrete call-site 状态：MCP runtime 迁移已在 - 后续 PR 闭环；remote-connect dialog submission、cron 调度和剩余 product execution - call-site 继续显式 core-owned，进入 H3 时才按单一 owner 补 port/provider 与 regression。 -- [x] 已补 `remote_image` attachment DTO 与 remote-connect image submission request builder 契约；`AgentSubmissionPort` 仍显式拒绝 generic attachments，直到多模态行为等价测试和接入方案单独完成。 -- [x] P2 concrete call-site 迁移前，已把 `AgentSubmissionRequest.turn_id` 提升为显式可选 DTO 字段（序列化为 `turnId`）；coordinator 兼容期先读显式字段再回退 `metadata["turnId"]`，并补充序列化与 adapter 回归测试。 -- [x] P2/P3 tool owner 迁移前，`DynamicToolProvider` 已停止从 `mcp__server__tool` 注册名反推 `provider_id`；MCP wrapper 显式携带 provider metadata，并用特殊 provider id / MCP-like 名称测试证明 provider 身份不依赖注册名格式。 - -示例： - -```rust -#[async_trait::async_trait] -pub trait SessionTranscriptReader: Send + Sync { - async fn read_session_transcript( - &self, - request: SessionTranscriptRequest, - ) -> PortResult; -} -``` - -**验证：** - -```powershell -cargo check -p bitfun-core --features product-full -cargo test -p bitfun-core remote_connect -cargo test -p bitfun-core mcp -cargo check --workspace -``` +### 2.4 目标 crate 创建准入 -**风险与处理：** +- 新目标 crate 不能为了“架构完整”提前创建。必须同时满足 owner 边界清晰、旧路径兼容可保留、focused tests 可落地、依赖收益可解释、boundary check 可防回流。 +- `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。 -- 风险：接口抽象过大，变成另一个 service god object。 -- 处理：每个 port 只覆盖一个调用方向和一个能力集合；避免 `CoreContext` 这种万能接口。 +## 3. 执行节奏 ---- +每个高风险 PR 按同一节奏执行： -### Plan 6：抽取中等粒度 service crate +1. **同步主干。** 变基到远端 `main`，检查最新主干是否引入新的 tool、remote、session、scheduler、CLI、mobile-web 或 product-surface 行为。 +2. **确认组装门禁。** 高风险迁移前必须先有最小 Product Assembly / Runtime Services skeleton，能把 provider 注册到 typed builder / registry。 +3. **确定 owner 主题。** 每个 PR 只迁移一个完整 owner 主题；预保护、迁移、旧路径兼容、文档更新和对抗性审核属于同一个 PR。 +4. **先补保护。** 在移动 owner 前补 owner 设计、输入输出盘点、旧路径兼容方案、等价测试或 snapshot。 +5. **再移动实现。** 只移动已被 port/provider 保护的逻辑；发现需要改变产品行为时暂停并单独评审。 +6. **回看边界。** 检查是否新增反向依赖、万能 context、无类型 service locator、全局 mutable registry 或重复 runtime materialization。 +7. **提交前审核。** 从第三方角度审查功能偏移、性能劣化、产品形态遗漏和文档一致性；不满足时不提交 PR。 -**目的：** 用两个 service owner crate 承载当前 `service` 目录，而不是把每个 service 都拆成独立 crate。这样可以隔离重依赖，同时避免 crate 数量过多。 +## 4. 后续迁移队列 -#### Plan 6A：抽取 `bitfun-services-core` +| 顺序 | 主题 | 完整范围 | 不允许混入 | 合入门禁 | +|---|---|---|---|---| +| 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，避免继续临时接线。 -- 新增：`src/crates/services-core/**` -- 移动/适配基础服务： - - `src/crates/core/src/service/config/**` - - `src/crates/core/src/service/session/**` - - `src/crates/core/src/service/workspace/**` - - `src/crates/core/src/service/workspace_runtime/**` - - `src/crates/core/src/service/filesystem/**` - - `src/crates/core/src/service/system/**` - - `src/crates/core/src/service/runtime/**` - - `src/crates/core/src/service/i18n/**` - - `src/crates/core/src/service/ai_rules/**` - - `src/crates/core/src/service/ai_memory/**` - - `src/crates/core/src/service/bootstrap/**` - - `src/crates/core/src/service/diff/**` - - `src/crates/core/src/service/session_usage/**` - - `src/crates/core/src/service/token_usage/**` - - `src/crates/core/src/service/project_context/**` -- 暂留或 feature-gate： - - `src/crates/core/src/service/search/**` - - `src/crates/core/src/service/lsp/**` - - `src/crates/core/src/service/cron/**` - - `src/crates/core/src/service/snapshot/**` +## 5. 每类 PR 的保护重点 -**任务：** +### 5.1 Service / Agent Remote Runtime Owner -- [x] 新建 `bitfun-services-core`，默认 feature 尽量轻。 -- [x] 基础 DTO 从 `bitfun-core-types` 引入。 -- [x] LR1 已复核 services-core 与 agent runtime 的调用边界：现有可替换入口通过 - `runtime-ports`/窄 adapter 承载；未完成的 scheduler、agent registry 或执行 runtime - 调用不在 LR1 移动，后续进入 H3 前需单独设计 port/provider。 -- [x] LR1 决策：`search`、`lsp`、`cron`、`snapshot` 继续按同 crate 内 feature group - 处理，不新增独立 crate；真正 runtime owner 迁移必须等 H3 风险评审。 -- [x] 已迁移模块的 core 旧路径通过 re-export 保持。 +- 先定义 remote connection、workspace、projection、capability facts port。 +- 保留 core adapter 读取 workspace-root、persistence、session restore、scheduler submit，直到有端到端 remote regression。 +- SSH、relay、tunnel、远端 OS、认证差异留在 Remote provider。 +- 验证 remote command/response wire、restore -> terminal pre-warm -> scheduler submit 顺序、file full/chunk/info、image context fallback、remote workspace startup guard。 -**当前安全迁移状态：** +### 5.2 Agent Registry / Scheduler Owner -- `bitfun-services-core` 已承接 `system`、`diff`、`process_manager`、session / usage / token usage 类型与通用本地 filesystem facade；core 旧路径继续 re-export。 -- `SessionKind` 已归属 `bitfun-core-types`，Deep Review session manifest / cache 字段随 session 类型迁移，并由序列化兼容测试保护。 -- `config`、`workspace`、`workspace_runtime`、`runtime`、`i18n`、`bootstrap`、`project_context` 仍保留在 core；remote workspace overlay、`BitFunError` 映射、MiniApp filesystem IO、tool-result persistence、`PathManager` 绑定和产品 runtime 接线继续显式 core-owned。 +- 先迁移只读 facts、queue policy decision、runtime event facts，不先移动 concrete scheduler 生命周期。 +- 保留 mode-scoped visibility、hidden/custom/review grouping、background result delivery、running-turn injection 和 idle-session follow-up 语义。 +- 验证 subagent availability、queue/preempt/cancel suppression、DeepResearch citation / post-turn hook、goal verification events。 -**验证：** +### 5.3 Product-Domain Runtime Owner -```powershell -cargo test -p bitfun-services-core -cargo check -p bitfun-core --features product-full -cargo check -p bitfun-desktop -``` - -#### Plan 6B：抽取 `bitfun-services-integrations` - -**文件范围：** - -- 新增：`src/crates/services-integrations/**` -- 移动/适配重集成服务： - - `src/crates/core/src/service/git/**` - - `src/crates/core/src/service/mcp/**` - - `src/crates/core/src/service/remote_ssh/**` - - `src/crates/core/src/service/remote_connect/**` - - `src/crates/core/src/service/announcement/**` - - `src/crates/core/src/service/file_watch/**` - -**feature group：** - -```toml -[features] -default = [] -git = ["git2"] -mcp = ["rmcp"] -remote-ssh = ["russh", "russh-sftp", "russh-keys", "shellexpand", "ssh_config"] -remote-connect = ["tokio-tungstenite", "qrcode", "image", "bitfun-relay-server"] -announcement = ["reqwest"] -file-watch = ["notify"] -debug-log = ["axum"] -product-full = ["git", "mcp", "remote-ssh", "remote-connect", "announcement", "file-watch", "debug-log"] -``` - -**任务：** - -- [x] 先迁移 `git`，因为边界相对清晰。 -- [x] LR1 已复核 `remote-ssh`：当前仅保持 path/session identity 等 contract/helper - 外移；SSH channel、SFTP、remote FS、remote terminal 和 manager assembly 继续 core-owned。 - 若 H3 继续迁移，必须保留 `ssh-remote` 语义并补 remote 等价测试。 -- [x] 先迁移 `remote-ssh` 的纯 contract/type、workspace path/identity helper 与 unresolved-session-key helper，runtime manager / fs / terminal 仍保留在 core。 -- [x] 迁移 `mcp` 的 PR2 runtime 与 dynamic provider：config service orchestration、server process / transport lifecycle、resource/prompt adapter、catalog cache、list-changed/reconnect policy、dynamic descriptor / provider / result rendering 均归属 `bitfun-services-integrations`。 -- [x] `bitfun-core` 保留 core `ConfigService` store adapter、OAuth data-dir 注入、`BitFunError` 映射、旧路径 facade 和全局 tool registry / manifest 组装；product tool runtime manifest / `GetToolSpec` 执行 owner 化不混入本 PR。 -- [x] 先迁移 `announcement` 的纯 types contract，scheduler / state store / content loader / remote fetch 仍保留在 core。 -- [x] 先完成 `remote-connect` contract slice：remote chat/image/tool/session wire DTO 与 relay/bot session/submission request builder 由 `bitfun-services-integrations` 拥有，relay/bot session 创建通过 `AgentSubmissionPort`。 -- [x] 已补齐 remote runtime 迁移前的第一层 port baseline：`SessionTranscriptReader`、`AgentTurnCancellationPort`、`RemoteControlStatePort`、`RuntimeEventSink` 与 remote image attachment/request DTO；完整 `remote-connect` runtime 仍需后续单独迁移并补 queue/event/image 行为等价测试。 -- [x] `RemoteSessionStateTracker`、`TrackerEvent`、tracker registry lifecycle 与 remote tool preview slimming helper 已迁入 `bitfun-services-integrations`；core 只保留 tracker host adapter、dispatcher、session restore、terminal pre-warm 与实际 dialog submission routing。 -- [x] 已补齐 remote-connect runtime 迁移前快照：remote command/response wire shape、session restore target、active turn poll snapshot、cancel decision、legacy image fallback / unified image context preference、tracker completion/fanout 与 RemoteRelay/Bot queue policy 均有 focused regression。 -- [x] 已将 remote-connect wire / poll 边界与纯运行时策略 helper 迁入 `bitfun-services-integrations`：command/response wire DTO、remote model catalog DTO / config-shape assembly、poll response assembly / model catalog poll delta、remote model selection policy、legacy image context fallback / explicit context preference、restore target decision、cancel decision、dialog scheduler outcome assembly、remote workspace file IO/path helper、remote file command / response assembly、dialog/cancel/interaction response helper、workspace/session response assembly helper、remote chat history presentation assembly、image-context adapter contract 与 remote file transfer size/chunk/name policy 由 owner crate 提供；core 仅保留 dispatcher、session restore 执行、workspace-root source、persistence/workspace service reads、model config loading / resolver injection、remote chat history projection / image compression / enhanced-input cleanup、`ImageContextData` concrete impl、terminal pre-warm adapter 与实际 dialog submission routing。 -- [x] H3 remote-connect closure：RemoteRelay/Bot dialog submission orchestration、agent type normalization、turn id resolution、restore decision、terminal pre-warm decision、queue policy、dialog scheduler outcome assembly、remote model catalog config-shape assembly、remote model selection policy、remote workspace file IO/path helper、remote file command / response assembly、dialog/cancel/interaction response helper、remote chat history presentation assembly 与 image-context adapter contract 归属 `bitfun-services-integrations`；core 继续作为 concrete scheduler/session restore/terminal adapter、workspace-root source、workspace/session response adapter、model config resolver adapter 与 persisted history projection adapter，不改变产品行为。 -- [x] 已迁移的集成能力保持 core 旧路径 re-export。 -- [x] 产品完整 runtime 通过 `services-integrations/product-full` 启用已迁移集成能力。 - -**当前安全迁移状态：** - -- `bitfun-services-integrations` 已承接 `file_watch`、`git`、remote-SSH 纯 contract/helper、MCP protocol/config/runtime/dynamic provider、announcement 纯 types，以及 remote-connect 的 wire DTO、poll/model catalog、model selection policy、tracker、file/image/dialog helper、RemoteRelay/Bot orchestration policy 与 remote chat history presentation assembly。 -- core 继续持有 `ConfigService` store adapter、OAuth data-dir 注入、`BitFunError` 映射、legacy facade、全局 tool registry / manifest 组装、SSH runtime manager / fs / terminal、workspace-root source、persistence/workspace service reads、`ImageContextData` concrete impl、terminal adapter、concrete scheduler/session restore 执行和 announcement scheduler/state/content/fetch runtime。 -- Deep Review queue/cost/context、session manifest、stream dedupe、search fallback、session rollback persistence 等 latest-main 行为仍属于 core runtime 或对应产品 runtime；继续迁移 remote-connect / MCP / search / session 前必须先补运行状态 port 合约和等价测试。 - -**验证：** - -```powershell -cargo test -p bitfun-services-integrations --features git -cargo check -p bitfun-services-integrations --features product-full -cargo check -p bitfun-core --features product-full -cargo check -p bitfun-desktop -cargo check -p bitfun-cli -``` - -**Plan 6 总体风险与处理：** - -- 风险：`services-integrations` 内 feature 互相污染，导致局部测试仍编译过多依赖。 -- 处理：默认 feature 为空；局部测试显式启用单一 feature；产品 crate 只通过 `product-full` 启用完整能力。 -- 风险：两个 service crate 仍然偏大。 -- 处理：先接受中等粒度。只有实测某个 feature group 仍显著拖慢关键测试时，再把它升级为独立 crate。 - ---- - -### Plan 7：拆解 agent tools - -**目的：** 避免 tool registry 拉入所有工具实现和对应 service 依赖。 - -**目标 crate：** - -- `src/crates/agent-tools` -- `src/crates/tool-packs` - -**任务：** - -- [x] 抽出 tool result、validation、dynamic metadata、runtime restriction、path resolution DTO、provider-neutral tool execution result/error/invalid-call presentation policy，以及 generic registry / dynamic provider container 到 `agent-tools`。 -- [x] 抽出纯 manifest/exposure / GetToolSpec presentation 契约到 `agent-tools`：`ToolExposure`、`GetToolSpec` 名称、纯 manifest policy、collapsed prompt stub、prompt-visible ordering、GetToolSpec prompt description / input schema / validation / assistant-detail rendering / collapsed summary-detail / duplicate-load hint；core 继续拥有 runtime assembly 和执行 owner。 -- [x] 抽出 static tool provider 安装合约到 `agent-tools`，并将 core 内置工具列表收敛到 `product_runtime.rs` 的 core-owned provider groups；不迁移 concrete tool implementation。 -- [x] 抽出 `ToolContextFacts` / `ToolWorkspaceKind` 轻量上下文事实契约，并由 core `ToolUseContext` 提供只读投影；workspace root fact 使用 session identity 的 logical path，remote 场景输出 normalized remote root；不迁移 collapsed unlock state、runtime handles、workspace services 或 cancellation token。 -- [x] 增加 `PortableToolContextProvider` 只读 facts provider 合约，并由 core `ToolUseContext` 兼容实现；该合约不暴露 workspace services、cancellation token、computer-use host 或 collapsed unlock state。 -- [x] LR1 已锁定 tool runtime port/provider 设计前置条件：`PortableToolContextProvider` - 只能提供只读 facts，不能携带 runtime handles、workspace services、cancellation token - 或 collapsed unlock state；`Tool` trait 与 `ToolUseContext` 在 H1 前继续 core-owned。 -- [x] `agent-tools` 不依赖任何 concrete service。 -- [x] 具体工具实现迁移 deferred 到 H1；LR1 不迁移 concrete tools。未来迁移到 - `tool-packs` 时按 feature group 分模块： - - basic file/search/terminal - - git - - MCP - - browser/web - - computer use - - miniapp - - cron/task/agent control -- [x] `tool-packs` 默认 feature 为空，产品完整 runtime 启用 `product-full`；当前仅提供 basic / git / mcp / browser-web / computer-use / image-analysis / miniapp / agent-control feature-group 元数据，不注册或迁移任何具体工具。 -- [x] 产品 runtime assembly provider 注册 deferred 到 H1；LR1 继续由 core product tool - runtime 安装 provider： - -```rust -registry.install_provider(BasicToolProvider::new()); -registry.install_provider(GitToolProvider::new(git_service)); -registry.install_provider(McpToolProvider::new(mcp_service)); -``` - -- [x] 兼容构造函数迁移 deferred 到 H1；LR1 继续保持现有 core 旧构造路径： - -```rust -pub fn create_tool_registry() -> ToolRegistry { - product_full_tool_registry() -} -``` - -- [x] registry / manifest 迁移前等价基线已在 LR1 复核：现有 - `registry_preserves_builtin_tool_manifest_for_owner_migration`、 - `registry_preserves_readonly_tool_manifest_for_owner_migration`、 - `manifest_snapshot_preserves_collapsed_tool_discovery_contract` 与 - `bitfun-agent-tools` tool contract 测试覆盖当前低风险拆分；H1 迁移前仍需扩展为完整产品 - registry、expanded/collapsed exposure 与 prompt-visible manifest 等价快照。 -- [x] runtime manifest assembly / `GetToolSpec` 执行迁移前的 baseline 已作为 H1 进入条件： - 保留并扩展 expanded/collapsed manifest、 - prompt-visible stub、unlock state 和 desktop/MCP/ACP catalog 等价测试。 -- [x] H1 解锁契约切片只抽出 `GetToolSpec` 结果到 collapsed 工具名集合的纯收集规则； - `ToolUseContext.unlocked_collapsed_tools`、执行消息解析、runtime manifest assembly 和 - `GetToolSpecTool` 执行仍由 core 拥有。 -- [x] H1 manifest builder 切片只抽出 prompt-visible manifest definition 的纯组装规则： - expanded 工具的 description/schema 仍由 core 按 `ToolUseContext` 获取，collapsed stub - 渲染和排序由 `bitfun-agent-tools` 统一；runtime manifest owner 仍未迁移。 -- [x] H1 catalog/exposure 切片继续抽出 registry snapshot 到 manifest policy input、 - generic collapsed exposure 查询、`GetToolSpec` catalog description 和 detail JSON 的纯规则；core - 仍负责 tool availability、product catalog source、product snapshot wrapper adapter、runtime unlock state 和工具执行。 - -**当前安全迁移状态：** - -- `bitfun-agent-tools` 已承接 tool DTO / validation / render options、runtime restrictions、path/runtime artifact/remote POSIX path 纯契约、tool execution presentation policy、portable context facts/provider、generic registry、static/dynamic provider contract、decorator reference、readonly/enabled filter、catalog / GetToolSpec provider、contextual manifest resolver、GetToolSpec runtime facade 和 Tool-result vector adapter。 -- `bitfun-tool-packs` 只承载 feature group 元数据和 product provider group plan；默认 feature 为空，不注册或迁移 concrete tools。 -- core 通过 `product_runtime.rs` / `tool_adapter.rs` 保留 product registry snapshot、product catalog / manifest facade、snapshot wrapper 注入、`dyn Tool` adapter、`GetToolSpecTool` Tool impl、`ToolUseContext` runtime handles、collapsed unlock state、`BitFunError` 映射和 concrete tool materialization。 -- boundary check 已锁定：`agent-tools` / `tool-packs` 不得拥有 product tool runtime assembly、`GetToolSpecTool` Tool impl、collapsed unlock state、snapshot wrapper implementation 或 concrete tools；core 也不得回退到散落的 dynamic metadata map / 手工 provider 注册。 -- 后续若继续迁移 tool runtime，只能按完整高风险 owner 主题推进，并先证明 tool visibility、expanded/collapsed manifest、`GetToolSpec` unlock、snapshot wrapper、runtime restrictions、cancellation、Deep Review hooks 和具体 IO 行为等价。 - -**验证：** - -```powershell -cargo test -p bitfun-agent-tools -cargo test -p bitfun-agent-tools get_tool_spec_contract --test tool_contracts -cargo test -p bitfun-tool-packs --features basic -cargo check -p bitfun-tool-packs --features product-full -cargo check -p bitfun-core --features product-full -cargo test -p bitfun-core registry_ --lib -cargo test -p bitfun-core manifest_ --lib -cargo test -p bitfun-core get_tool_spec --lib -cargo test -p bitfun-core dynamic_tool_provider_ --lib -cargo check -p bitfun-desktop -``` - -**风险与处理：** - -- 风险：工具列表遗漏导致产品能力缺失。 -- 处理：拆分前生成工具清单基线；拆分后 registry 等价性测试必须通过。 -- 风险：expanded/collapsed exposure、`GetToolSpec` 插入、prompt stub 或 unlock state 不等价，会改变模型实际可见工具和调用顺序。 -- 处理：迁移前补 manifest / `GetToolSpec` 快照和执行解锁 regression；迁移后同时验证 desktop/MCP/ACP tool catalog。 -- 风险：单个 `tool-packs` crate 过重。 -- 处理：先用 feature group 控制编译面；只有某个工具族被实测证明明显拖慢局部测试时，再拆成独立 crate。 - ---- - -### Plan 8：抽取产品子域到 `bitfun-product-domains` - -**目的：** 把相对独立的产品子域移出 core，但不为每个子域创建独立 crate。 - -**文件范围：** - -- 新增：`src/crates/product-domains/**` -- 移动/适配： - - `src/crates/core/src/miniapp/**` - - `src/crates/core/src/function_agents/**` - -**feature group：** - -```toml -[features] -default = [] -miniapp = [] -function-agents = [] -product-full = ["miniapp", "function-agents"] -``` - -**任务：** - -- [x] miniapp compiler 迁移到 `product-domains::miniapp::compiler`，core 保留原 `miniapp::compiler::compile` 返回 `BitFunResult` 的兼容 wrapper。 -- [x] miniapp exporter DTO、runtime detection DTO、runtime search plan、worker install 命令选择与 package.json storage-shape helper 迁移到 `product-domains::miniapp`；当前 HR-B 进一步迁移 concrete runtime detector owner，core 保留实际 export / worker pool / storage IO 执行逻辑。 -- [x] LR1 已完成 MiniApp runtime 迁移前 owner 审视：runtime、storage、manager、host - dispatch、exporter、builtin 中涉及 filesystem IO、worker process、asset seed、marker IO、 - host dispatch execution 或 recompile orchestration 的部分继续 core-owned，actual owner - 迁移 deferred 到 H2。 -- [x] LR1 已完成 function-agent runtime 迁移前 owner 审视：pure DTO/helper/parser/facade - 可由 `product-domains::function_agents` 承载；Git service 与 AI call 继续 core-owned。 - prompt template、JSON extraction 和 domain error mapping 已在 H2 迁入 product-domain policy。 -- [x] 已为 miniapp runtime/storage 与 function-agent Git/AI 边界定义迁移前 provider / port contract，并补充 core-owned MiniApp storage/runtime 与 function-agent Git snapshot adapter 等价测试；实际 IO/进程/Git/AI 执行 owner 迁移仍待后续 port/provider 方案确认后推进。 -- [x] 已迁移模块的 core 旧路径 re-export。 -- [x] function-agent agent-runtime port 依赖 deferred 到 H2；LR1 不引入新的 agent runtime - port，也不改变现有 service manager 调用语义。 -- [x] LR1 未改 server/desktop 调用路径；后续 H2/H3 若迁移 runtime owner，必须用现有 - product check 和 focused regression 证明调用路径等价。 - -**当前安全迁移状态：** - -- `bitfun-product-domains::miniapp` 已承接 MiniApp types / bridge / permission policy、compiler、export DTO、runtime detection DTO、runtime search plan、concrete runtime detector、worker install plan、package/storage layout、lifecycle/revision helpers、host routing / allowlist policy、customization metadata、builtin bundle / marker / seed policy、runtime/storage port contract 和 create/update/draft/apply/import 纯状态转换。 -- `bitfun-product-domains::function_agents` 已承接 git/startchat function-agent DTO、prompt template、commit/work-state helper、AI response JSON extraction / repair / parser、domain error mapping、Git/AI port contract 和只读 project context analyzer。 -- core 继续持有 MiniApp source/storage/marker filesystem IO、compile orchestration、worker process、host dispatch execution、export skeleton、built-in asset include / seed / recompile、`PathManager` 注入，以及 function-agent Git/AI service adapter、AI client 调用、provider acquisition 和 transport error mapping。 -- 通用本地 filesystem owner 已迁入 `bitfun-services-core::filesystem`；这不改变 MiniApp filesystem IO、tool-result persistence、remote SSH runtime 或产品持久化接线仍显式 core-owned 的结论。 -- boundary check 已锁定 product-domain owner anchor 和 core-owned runtime anchor，防止把 port contract、response policy 或 runtime detector 误读成 storage IO、worker process、host dispatch、builtin asset seeding runtime 或 Git/AI service runtime 已完成迁移。 - -**验证：** - -```powershell -cargo test -p bitfun-product-domains --no-default-features -cargo test -p bitfun-product-domains --features miniapp -cargo test -p bitfun-product-domains --features product-full -cargo check -p bitfun-product-domains --features product-full -cargo check -p bitfun-core --features product-full -cargo check -p bitfun-desktop -cargo check -p bitfun-server -``` - ---- - -### Plan 9：将 `bitfun-core` 收敛为 facade + product runtime assembly - -**目的：** 完成迁移收束，让 `bitfun-core` 不再是新实现承载点。 - -**文件范围：** - -- 修改：`src/crates/core/src/lib.rs` -- 修改：`src/crates/core/src/service/mod.rs` -- 修改：`src/crates/core/src/agentic/mod.rs` -- 修改：`src/crates/core/Cargo.toml` - -**任务：** - -- [x] 将可替换的实现模块改为 re-export（限本轮已迁移 owner crate；高耦合 runtime 保留为 core-owned runtime）。 -- [x] 在顶层加入关键节点注释： - -```rust -//! Compatibility facade and full product runtime assembly. -//! -//! New implementation code should live in owner crates under `src/crates/*`. -//! This crate re-exports legacy paths and wires the full BitFun product runtime. -``` - -- [x] `bitfun-core/Cargo.toml` 依赖裁剪 deferred 到 H4/H5；LR1 已确认当前仍因 - core-owned runtime 保留 concrete runtime 依赖，不强行删减。 -- [x] 旧路径保持 import-compatible。 -- [x] `default = []` / per-product feature matrix 评估 deferred 到 H5；只有所有产品 crate - 都显式启用完整 runtime 且有 feature graph baseline 后，才可以在独立 PR 中评估： - -```toml -default = [] -``` - -**当前收敛状态：** - -- 本轮不把 `remote-ssh` runtime、`remote-connect`、announcement runtime、concrete tool implementations、`ToolUseContext`、product registry snapshot / manifest / exposure assembly、miniapp runtime/compiler/builtin、function-agent 运行逻辑声明为已迁移；它们继续作为 `bitfun-core` 的 product runtime assembly 或后续 owner PR 拥有路径。`git` feature group 已外移；`remote-ssh` 目前只外移 contract/type、workspace path/identity helper 与 unresolved-session-key helper；MCP PR2 已外移 config service orchestration、server process / transport lifecycle、adapter 和 dynamic tool/resource/prompt provider；generic tool registry / static provider installation / dynamic descriptor assembly 已由 `bitfun-agent-tools` 拥有，product provider group plan 由 `bitfun-tool-packs` 拥有，core 只保留 ConfigService store adapter、OAuth data-dir 注入、BitFunError 映射、legacy facade、concrete tool materialization、tool manifest/exposure product facade 和 snapshot decorator assembly；`announcement` 目前只外移 types contract。 -- 新增 `scripts/check-core-boundaries.mjs`，用于阻止已拆出的 owner crate 反向依赖 `bitfun-core`。该脚本只证明 crate graph 方向，不替代产品等价性测试。 -- `default = []` 仍保持为后续独立评估项，本轮不调整默认 feature、构建脚本或 release 脚本。 - -**验证：** - -```powershell -node scripts/check-core-boundaries.mjs -cargo check -p bitfun-core --features product-full -cargo check -p bitfun-desktop -cargo check -p bitfun-cli -cargo check -p bitfun-server -cargo check -p bitfun-relay-server -cargo check -p bitfun-acp -cargo check --workspace -``` - -**风险与处理：** - -- 风险：facade re-export 引发公开路径破坏。 -- 处理：每个旧路径迁移都必须有兼容 shim；必要时加 compile-only compatibility test。 - ---- - -## 6. 依赖版本收敛计划 - -依赖版本收敛必须和 crate 拆解并行但不要混入高风险移动 PR。 - -### 6.1 先做低风险直接依赖收敛 - -候选： - -- `base64 0.21/0.22` -- `dirs 5/6` -- `toml 0.8/0.9` - -执行原则： - -- 只处理本仓库直接依赖。 -- 不为了收敛版本强行升级外部库。 -- 每次只收敛一类库。 - -示例检查： - -```powershell -cargo tree -d -i base64 -cargo tree -d -i dirs -cargo tree -d -i toml -``` - -验证： - -```powershell -cargo check --workspace -cargo test -p -``` - -### 6.2 高风险重复依赖暂不优先强收敛 - -候选： - -- `image 0.24/0.25` -- `rmcp 0.12/1.5` -- `reqwest 0.12/0.13` -- `windows*` - -原因： - -- 这些通常来自传递依赖或大版本 API 变化。 -- 贸然统一可能比保留重复版本风险更高。 - -处理方式： - -- 优先通过 crate 边界隔离它们的编译范围。 -- 等 owner crate 独立后，再在对应 crate 内评估升级。 - ---- - -## 7. 边界强制规则 - -在至少两个 crate 被抽出后，增加轻量检查脚本，而不是一开始就把工具链复杂化。 - -**建议新增：** `scripts/check-core-boundaries.mjs` - -检查规则： - -- `bitfun-core-types` 不允许依赖： - - `bitfun-core` - - service crate - - agent runtime - - Tauri - - `reqwest` - - `git2` - - `rmcp` - - `image` - - `tokio-tungstenite` -- service crate 不允许依赖 `bitfun-core`。 -- agent runtime 不允许依赖 concrete heavy service crate，只依赖 ports。 -- tool framework 不允许依赖 concrete service implementation。 -- product crate 可以依赖 facade 或明确 concrete crate。 - -运行： - -```powershell -node scripts/check-core-boundaries.mjs -``` - -注意： - -- 不要在大型移动 PR 中同时新增复杂检查。 -- 检查脚本应简单扫描 Cargo.toml 和 `src/**/*.rs` 的 forbidden imports。 - ---- - -## 8. 验证矩阵 - -### 8.1 每个 PR 的最小验证 - -```powershell -cargo check -p -cargo test -p -cargo check -p bitfun-core --features product-full -``` - -### 8.2 产品矩阵 - -```powershell -cargo check -p bitfun-desktop -cargo check -p bitfun-cli -cargo check -p bitfun-server -cargo check -p bitfun-relay-server -cargo check -p bitfun-acp -cargo check --workspace -``` - -### 8.3 default feature 变更前的完整门禁 - -```powershell -cargo test --workspace -cargo build -p bitfun-desktop -pnpm run desktop:build:fast -pnpm run desktop:build:release-fast -``` - -### 8.4 构建脚本保护 - -```powershell -git diff -- package.json scripts/dev.cjs scripts/desktop-tauri-build.mjs scripts/ensure-openssl-windows.mjs scripts/ci/setup-openssl-windows.ps1 BitFun-Installer -``` - -期望： - -- 没有脚本或 installer diff。 -- 如果出现 diff，该 PR 不应作为 core 拆解 PR 合并。 - ---- - -## 9. 风险登记表 - -| 风险 | 概率 | 影响 | 缓解方式 | -|---|---:|---:|---| -| 产品 feature set 被意外改变 | 中 | 高 | `product-full` 先行；产品 crate 显式启用；产品矩阵验证 | -| 新 crate 依赖回 `bitfun-core` | 高 | 高 | boundary script；code review；`core-types` 先行 | -| service-agentic 循环阻塞拆分 | 高 | 高 | 先引入 ports，再移动 crate | -| port DTO 仍依赖非结构化 metadata | 中 | 中 | `turnId` 已显式化；后续新增跨边界字段继续优先进入 DTO，metadata fallback 只作为兼容期 | -| tool registry / manifest 行为变化 | 中 | 高 | 完整工具清单、expanded/collapsed manifest、`GetToolSpec` 与 provider 等价性测试 | -| 动态工具 provider 身份耦合注册名 | 中 | 中 | MCP wrapper / registry entry 已显式携带 provider metadata；后续 provider owner 迁移继续禁止从 `mcp__...` 名称反推身份 | -| remote SSH 行为变化 | 中 | 高 | workspace identity DTO 稳定后再拆；保留 `ssh-remote` 语义 | -| MCP 动态工具丢失 | 中 | 高 | `DynamicToolProvider` contract；MCP regression test | -| desktop 构建脚本被误改 | 低 | 高 | 每 PR 执行 build script guard | -| facade 阶段编译速度收益不明显 | 中 | 中 | 预期中间态；衡量小 crate 测试收益，不把 facade 视为终点 | -| 抽象过度导致开发复杂度上升 | 中 | 中 | port 粒度小；禁止万能 `CoreContext` | -| crate 拆得过碎导致链接和调度成本上升 | 中 | 中 | 采用中等粒度目标；默认只拆 8 到 12 个 owner crate；后续拆小必须有实测依据 | - ---- - -## 10. 三个关键里程碑 - -后续执行按里程碑推进，而不是按单个技术点零散推进。每个里程碑都必须独立可验收，并且不改变产品功能集合。 - -### 执行优先级 - -优先级从高到低： - -1. **P0：安全边界。** 文档、feature 安全网、构建脚本保护、产品能力不变。 -2. **P1：最小编译面验证。** `core-types`、`agent-stream`、runtime ports，优先验证小 crate 测试是否能绕开完整 core。 -3. **P2：中等粒度 owner crate。** `services-core`、`services-integrations`、`agent-tools`、`tool-packs`、`product-domains`。 -4. **P3：facade 收敛与边界强制。** `bitfun-core` 只做兼容门面和 product runtime assembly。 -5. **P4：冗余清理。** 只处理绝对等价重复，且必须独立 PR。P4 不阻塞任何里程碑。 - -不允许跳过 P0/P1 直接进入重 service 拆分。任何 P2/P3 任务如果需要改变产品功能集合、默认 feature、构建脚本或平台边界，必须回退到 P0/P1 重新补安全网。 - -### 里程碑一：边界安全网与最小收益验证 - -**覆盖计划：** - -- Plan 0：基线与安全护栏。 -- Plan 1：`product-full` feature 安全网。 -- Plan 2：移动 nested `terminal-core` 和 `tool-runtime`。 -- Plan 3：抽取 `bitfun-core-types`。 -- Plan 4：抽取 `bitfun-agent-stream`。 -- Plan 5：引入 runtime ports。 - -**目标：** - -- 建立后续拆分不会偏移产品能力的 feature 安全网。 -- 建立底层共享类型和 port 基础，避免后续循环依赖。 -- 通过 `agent-stream` 先验证“小 crate 承载局部测试”是否能减少编译面。 -- 不移动重 service，不调整产品构建脚本，不改变 release/CI 行为。 - -**启动队列：** - -1. 文档和基线护栏：只记录边界、验证命令、禁止项，不移动代码。 -2. `product-full` feature：保持 default 行为不变，让产品 crate 显式启用完整能力。 -3. nested crate 位置整理：移动已经独立的 `terminal-core` 和 `tool-runtime`，保持 package/lib 名称不变。 -4. `core-types`：只抽错误和纯 DTO，不引入运行时依赖。 -5. `agent-stream`：迁移 stream processor 和 stream 测试，验证小 crate 测试收益。 -6. runtime ports：新增轻量 ports crate 和第一批 adapter，建立后续替换跨层 concrete 调用的入口，不移动重 service。 - -**实现边界：** - -- 可以新增 `core-types`、`agent-stream`、workspace 顶层 `terminal`、`tool-runtime`。 -- 可以新增 port trait 和 DTO。 -- 可以在 core 中添加兼容 re-export。 -- 不允许改变 `bitfun-core default` 为轻量模式。 -- 不允许修改 `package.json`、`scripts/*`、`BitFun-Installer/**`。 -- 不允许把 desktop/server/CLI 的平台逻辑下沉到 shared crate。 - -**验收门：** - -```powershell -cargo check -p bitfun-core --features product-full -cargo test -p bitfun-runtime-ports -cargo test -p bitfun-agent-stream -cargo check -p bitfun-desktop -cargo check -p bitfun-cli -cargo check -p bitfun-server -git diff -- package.json scripts/dev.cjs scripts/desktop-tauri-build.mjs scripts/ensure-openssl-windows.mjs scripts/ci/setup-openssl-windows.ps1 BitFun-Installer -``` - -期望： - -- 产品 crate 仍显式拥有完整能力。 -- `agent-stream` 测试不需要依赖完整 `bitfun-core`。 -- 旧公开 import 路径可用。 -- 构建脚本无 diff。 - -**当前验收状态：** - -- P1 已完成：`product-full` 默认能力保护、workspace 顶层 crate 移动、`core-types` 第一批类型、`agent-stream` 独立测试、runtime ports 初始边界和旧路径 compatibility wrapper 均已建立。 -- 已补 P2 前置 contract hardening：`AgentSubmissionRequest.source` / `turnId` 显式化，coordinator 保留 metadata fallback；dynamic tool provider 身份改为显式 provider metadata，不再从 MCP 注册名反推。 -- 已通过的验证类型包括 runtime-ports / agent-stream / core focused tests、`cargo check --workspace`、`cargo test --workspace`、Web UI lint/type-check/test 和构建脚本保护范围检查；后续小范围文档修正不要求重复全量 Web 验证。 -- 不属于 P1 完成范围：remote-connect / cron / MCP concrete call-site 迁移、`AgentSubmissionPort` attachment / image context 接入，以及任何产品逻辑或边界行为变更。 - -**暂停条件：** - -- `core-types` 需要引入运行时依赖才能通过编译。 -- port 设计开始变成万能 context。 -- `agent-stream` 无法脱离完整 core，说明应重新评估 stream 边界。 -- 任何任务需要顺手清理非绝对等价重复代码。 - -### 里程碑二：中等粒度 owner crate 成型 - -**覆盖计划：** - -- Plan 6：抽取 `bitfun-services-core` 和 `bitfun-services-integrations`。 -- Plan 7：拆解 `bitfun-agent-tools` 和 `bitfun-tool-packs`。 -- Plan 8：抽取 `bitfun-product-domains`。 -- 低风险直接依赖版本收敛只允许作为独立小 PR 插入。 - -**目标：** - -- 将当前 core 中最重的 service、tool、product domain 职责迁移到中等粒度 owner crate。 -- 用 feature group 隔离重依赖，而不是拆成大量小 crate。 -- 让局部 service/tool/domain 测试可以绕开完整 product runtime。 -- 保持产品完整 runtime 通过 `product-full` 组装同等能力。 -- 在重 service/tool 迁移前先收紧 P1 暴露出的 port/tool contract：显式 `turnId`、显式 dynamic tool provider metadata、以及迁移路径的回归测试入口。 - -**主要工作：** - -- `bitfun-services-core`：先迁移 config、session、workspace、storage、filesystem、system、session_usage、token_usage 等基础服务，保持旧 core 路径 re-export。 -- `bitfun-services-integrations`：按 git、remote-ssh、MCP、remote-connect 顺序迁移重集成；每迁移一个 feature group 都保留产品完整 runtime 等价性。 -- `bitfun-agent-tools` / `bitfun-tool-packs`：拆出 tool trait、context、registry、provider contract；`tool-packs` 先承载 feature-group 元数据和 provider plan，具体工具实现仅作为后续按 feature group 外移的目标。 -- `bitfun-product-domains`：承接 miniapp 和 function-agent 产品子域，避免继续扩大 `bitfun-core` 的产品职责。 - -**影响面：** - -- Rust crate graph、workspace manifests、core compatibility re-export、feature group 组装。 -- `src/crates/core/src/service/**`、`agentic/tools/**`、MCP / remote SSH / remote connect / git integration。 -- Desktop、CLI、server 通过 `product-full` 组装的完整能力验证。 - -**优先风险：** - -- service/tool 迁移改变产品 feature set 或默认能力。 -- 新 owner crate 反向依赖 `bitfun-core`，导致 facade 计划失效。 -- remote connect / cron / MCP 接入 ports 时丢失 `turnId`、attachment、subagent、cancellation 或 transcript 关联语义。 -- MCP 动态工具 provider metadata 在 registry/tool owner 迁移中断裂。 -- 工具清单、expanded/collapsed manifest、`GetToolSpec` unlock state、snapshot wrapping、permission / concurrency safety 行为与迁移前不等价。 - -**实现边界：** - -- service 侧只拆成 `services-core` 和 `services-integrations`，继续拆小必须有实测依据。 -- tool 侧只拆成 `agent-tools` 和 `tool-packs`，具体工具族通过 feature group 控制。 -- miniapp 和 function agents 先合并到 `product-domains`，不分别建独立 crate。 -- 每次只迁移一个 feature group 或一个模块簇。 -- 不允许在同一 PR 中做三方库大版本升级。 -- 不允许改变产品默认能力、CI 覆盖或 release 脚本。 - -**验收门：** - -```powershell -cargo test -p bitfun-services-core -cargo check -p bitfun-services-integrations --features product-full -cargo test -p bitfun-agent-tools -cargo check -p bitfun-tool-packs --features product-full -cargo check -p bitfun-product-domains --features product-full -cargo check -p bitfun-core --features product-full -cargo check -p bitfun-desktop -cargo check -p bitfun-cli -cargo check -p bitfun-server -cargo check --workspace -``` - -期望： - -- 新 owner crate 不依赖回 `bitfun-core`。 -- 产品完整 runtime 的工具、MCP、remote SSH、remote connect、miniapp、function agents 仍可用。 -- 新增 crate 数量仍保持中等粒度。 -- heavy dependency 所属 crate 清晰。 - -**当前 P2 执行状态：** - -- 中等粒度 owner crate 已成型：`bitfun-services-core`、`bitfun-services-integrations`、`bitfun-agent-tools`、`bitfun-tool-packs`、`bitfun-product-domains` 均已加入 workspace，并通过 core facade 保持旧路径兼容。 -- 已完成的安全迁移包括：Git feature group、remote-SSH 纯 identity/path helper、MCP runtime/dynamic provider、remote-connect wire/tracker/file/image/dialog helper、generic tool registry / provider / catalog / GetToolSpec helper、product provider plan、MiniApp / function-agent 纯 domain helper 与 port/facade。 -- 已补轻量 contract crate 与 feature graph 保护：`core-types`、`runtime-ports`、`agent-tools`、`product-domains`、`services-integrations` 的默认 profile 和禁止依赖由 boundary check 覆盖；`ToolImageAttachment`、dynamic provider metadata、runtime restrictions、path resolution、tool registry snapshot 等作为迁移前基线保留。 -- 不声明完成的部分：remote-SSH runtime、workspace-root source、persistence/workspace service reads、`ImageContextData` concrete impl、`ToolUseContext`、runtime manifest / `GetToolSpecTool` execution、collapsed unlock state、concrete tools、MiniApp filesystem / worker / host dispatch / builtin asset runtime、function-agent Git/AI concrete service、agent registry / scheduler。 -- 结论：P2 已完成低风险 owner container 化和行为基线，不再拆成小 PR；剩余项必须按高风险 runtime owner 主题进入 HR 队列。 - -P2 后产品表面契约轨道（contract-only）： - -- 背景：最新 CLI TUI、Desktop、Remote、Server 和 ACP 都是 first-class product surface。后续重构不应把它们 - 拉平成同一套命令实现，而应共享 runtime capability facts。 -- 原则：**surface divergence, capability convergence**。命令、快捷键、pane/card/TUI rendering 属于 surface - presentation；session/thread identity、environment identity、permission facts、artifact refs、event facts 和 - capability request/response 属于可共享 contract。 -- 候选 contract：`SurfaceKind`、`ThreadEnvironment`、`RuntimeArtifactKind`、`RuntimeArtifactRef`、 - `PermissionDecision`、`PermissionScope`、`ApprovalSource`、`CapabilityRequest`。纯 DTO 优先放入 - `bitfun-core-types`；必要 port trait 放入 `bitfun-runtime-ports`。 -- 明确不做：不改 CLI slash command / TUI、不改 Desktop command palette 或 pane 行为、不新增 command engine crate、 - 不调整 `product-full`、不做 per-product feature set，也不把 `ratatui`、`crossterm`、Tauri 或 Web UI 依赖带入 - contract crate。 -- 进入方式：该轨道可作为 PR3 前的 contract-only 前置提交或 PR3 的第一组无行为变更提交；一旦需要改变 UI、 - 命令语义、权限策略或运行时调用路径，必须拆成单独产品变更 PR 并先确认。 -- 验证：DTO/port 只做 serialization round-trip、conversion/no-op check 与 boundary check；不能只凭 - `cargo check` 声明产品行为等价。 - -需要单独审视的高风险项： - -- `ToolUseContext`、runtime manifest assembly / `GetToolSpec` 执行、product tool provider assembly、concrete tool implementation 外移。 -- MCP concrete tool implementation / product registry / manifest assembly 外移。 -- remote-connect、remote-SSH runtime、announcement runtime 外移。 -- miniapp runtime/compiler/builtin 与 function-agent 运行逻辑外移。 -- agent registry / subagent visibility 外移，特别是 hidden/custom/review 分组、mode-scoped visibility 和 desktop API contract。 -- `bitfun-core default = []`、per-product feature set、构建脚本或 release 能力调整。 - -这些高风险项的进入条件： - -- 先有 port/provider 设计，且不依赖回 `bitfun-core`。 -- 先有迁移前后等价测试或脚本快照，不能只依赖 `cargo check`。 -- 保留旧公开路径兼容，或者明确记录需要用户确认的行为合约变化。 -- 产品完整 runtime 通过 `product-full` 保持同等能力；任一产品需要减少 feature 才能通过时必须暂停。 -- 每个 PR 只移动一个 runtime owner 或一个 feature group，不和默认 feature、构建脚本、依赖升级混合。 - -**暂停条件：** - -- 某个迁移必须让产品 crate 减少 feature 才能通过。 -- `services-integrations` 的 feature group 互相强耦合，无法单独 check。 -- product registry / manifest assembly 或 concrete tool implementation 迁移后工具清单、expanded/collapsed exposure、`GetToolSpec` unlock state 无法证明等价。 -- 新 owner crate 反向依赖 core。 - -**已完成内容摘要：** - -- P1 / P2 的低风险拆分已闭环：workspace 顶层 crate、`core-types`、`agent-stream`、runtime ports、`services-core`、`services-integrations`、`agent-tools`、`tool-packs`、`product-domains` 均已有明确 owner 边界和旧路径兼容。 -- 低风险准备项已合并为 LR1 并完成：错误边界、shared DTO 归属、悬空 port/call-site、feature/dependency baseline、boundary check 与文档/AGENTS 校准不再作为独立小 PR 重复提交。 -- H1-H4 的安全收口已完成：tool runtime 的 provider-neutral contract、product-domain pure/port facade、service/agent remote-connect contract、core 内部 `product_runtime.rs` / `product_domain_runtime.rs` / `service_agent_runtime.rs` owner 收口，以及 facade / boundary finalization 均已有当前状态描述。 -- H5 已完成当前基线：`bitfun-core --no-default-features` 可编译面、`product-full` 显式 owner feature 聚合、optional dependency owner 映射和产品入口显式装配检查已建立；这只是 feature/dependency baseline，不代表完整构建收益或 runtime owner 深迁移完成。 +- MiniApp 优先拆 storage/process/asset/Git/AI 的最小 port，避免把 PathManager、worker process、host dispatch、builtin marker IO 下沉到 domain crate。 +- function-agent 保留 Git/AI provider acquisition、error mapping、no-HEAD diff fallback、非 Git workspace fallback、`analyzed_at` 时序。 +- 验证 MiniApp import/sync/recompile/rollback/deps state、builtin seed marker、customized update metadata、function-agent prompt/response policy。 -**当前后续执行队列：** +### 5.4 Tool Runtime Owner -| 队列项 | 范围 | 不允许混入 | 合入门禁 | -|---|---|---|---| -| HR-A deep optional | 仅在决定继续深迁 tool runtime 时，评审 `ToolUseContext`、concrete tool IO、manifest execution、snapshot wrapper、collapsed unlock state 等单一 owner | product-domain runtime、service/agent runtime、feature matrix、产品行为变更 | tool registry / manifest / `GetToolSpec` / snapshot / Deep Review tool flow 等价，且有 port/provider 设计 | -| HR-B deep optional | MiniApp filesystem IO / worker / host / builtin seed 或 function-agent Git/AI 中一个 owner 主题 | tool runtime、service/agent runtime、surface 行为变更 | MiniApp/function-agent focused regression、PathManager/process/Git/AI 边界清晰 | -| service/agent deep optional | 仅在决定继续深迁 HR-C 之外的 concrete runtime 时，在 remote-SSH / remote FS / terminal、workspace-root / persistence、`ImageContextData`、agent registry / scheduler 中选择一个 owner 主题 | tool runtime、product-domain runtime、feature matrix、产品逻辑变更 | remote/session/subagent/citation/goal/request-context 行为等价，旧路径兼容 | -| H5 optional | feature matrix、dependency profile、构建收益数据评估 | runtime owner 迁移、default feature 副作用、构建脚本变更 | feature graph / cargo metadata 证据，产品入口完整能力不变 | +- 不直接搬全部 concrete tools。先拆 portable facts projection、manifest/catalog snapshot、`GetToolSpec`、snapshot wrapper 或 collapsed unlock 中一个 owner。 +- 保留 tool name、schema、prompt stub、readonly/enabled/filtering、unlock state 生命周期。 +- 验证 builtin tool list、provider order、expanded/collapsed exposure、dynamic provider metadata、Deep Review 修改类工具 checkpoint hook。 -执行口径： +## 6. 不可变更边界 -- 后续不再新增低风险碎片 PR；helper、guard、facade cleanup 只能作为同一 owner 迁移的预保护或收尾。 -- `bitfun-core default = []`、per-product feature set、构建矩阵和 release 能力调整仍属于 H5 独立评估，不得与 HR-A / HR-B 或 service/agent deep optional 混合。 -- 最新主干新增的 Write sanitizer、AskUserQuestion/TodoWrite truncation recovery、per-tool denial message、tool-result flush、`fork_context`、prompt cache clone、existing-context dialog turn、MCP initialize timeout scope、pending waiter drain、CLI package workflow 和 mobile-web session 操作，必须按触碰 owner 纳入等价测试或产品矩阵影响面。 +- 不改变产品行为、默认能力集合、权限语义、工具曝光、事件语义或 session 生命周期。 +- 不修改 `package.json`、`scripts/dev.cjs`、`scripts/desktop-tauri-build.mjs`、`scripts/ensure-openssl-windows.mjs`、`scripts/ci/setup-openssl-windows.ps1`、`BitFun-Installer/**`，除非单独作为产品构建变更评审。 +- 不让新 crate 依赖回 `bitfun-core`。 +- 不把 `bitfun-core` 重新包装成新的 `common`、`platform`、`app context` 或 service locator。 +- 不在同一 PR 中同时做 runtime owner 迁移、default feature 调整、三方库大版本升级和构建脚本变更。 +- 不为了减少代码行数抽象语义并不等价的跨产品或跨平台流程。 -**HR 风险与优化清单：** - -所有 HR PR 都必须满足以下共同约束： - -- 功能影响范围：只能移动 owner 或引入 port/provider adapter；不得改变用户可见命令、 - 默认权限、remote/session 生命周期、tool 可见性、MiniApp/function-agent 输出、CLI/Desktop/ACP/Server - 交互语义。 -- 产品发布形态：不得修改 `bitfun-core` default feature、产品 crate feature set、 - `package.json`、desktop/installer build scripts、release/fast build 脚本或 CI 覆盖范围。 - 若某项迁移必须改变这些内容，必须从 HR PR 中拆出并先单独评审。 -- 性能门禁：不得新增无界全局锁、阻塞 IO、重复 registry rebuild、重复 manifest - materialization、额外 network/process startup 或跨 crate 的重依赖反向引入。PR 如果声明 - build/check 收益，必须记录迁移前后数据；如果不声明收益，也至少不能让 workspace - check/test 或关键产品 check 明显劣化。 -- 依赖边界：owner crate 不得依赖回 `bitfun-core`；contract crate 不得吸收 - Tauri、CLI/TUI presentation、network client、process execution、`git2`、`rmcp`、 - `image`、`tokio-tungstenite` 等 concrete runtime 依赖。 -- 回滚边界：每个 HR PR 必须保留旧路径 facade 或 adapter，使失败时可以把新 owner - 路径回退到 core-owned adapter，而不需要同步修改产品 surface。 - -HR1：tool runtime deep owner migration 的主要风险和控制点： - -- 当前已完成的低侵入部分：`product_runtime.rs` 统一承接 product provider plan - materialization、product registry snapshot/catalog facade、manifest / GetToolSpec facade 和 - snapshot wrapper 注入；这只是 core 内部 owner closure，不改变工具执行路径。 -- 风险：`ToolUseContext` 携带 workspace services、cancellation、computer-use host、 - custom data、Deep Review checkpoint hook 与 collapsed unlock state；若直接移动， - 可能改变工具可见性、权限、snapshot wrapper、Deep Review tool flow 或取消语义。 -- 风险：manifest / `GetToolSpec` / catalog 组装若重复计算，可能增加每轮 agent - prompt 构建成本；若 dynamic metadata 顺序或去重语义漂移，可能改变模型看到的工具集合。 -- 可优化点：只先抽 `ToolUseContext` 的 capability/read-only projection 或小型 - service port；concrete tools 仍按 feature group 分批评审，避免一次性迁移全部 IO 工具。 -- 可优化点：把 manifest/catalog 快照缓存边界显式化，避免迁移后每次 prompt - resolution 都重建 registry；保留现有 provider order 和 dynamic provider metadata order。 -- 必须新增或复用的保护：builtin tool list、provider group order、readonly/enabled - filtering、expanded/collapsed exposure、`GetToolSpec` duplicate-load/unlock state、 - snapshot wrapper、runtime restriction、cancellation 和 Deep Review tool flow regression。 -- 产品形态门禁：Desktop MCP catalog、ACP catalog、CLI agent tool surface、Deep Review - tool flow 必须继续使用同一行为矩阵；不得为了 tool owner 外移改变任何 surface command。 - -HR2：product-domain runtime deep owner migration 的主要风险和控制点： - -- 当前 HR2 结论：本轮只完成 core 内部 owner closure。`CoreProductDomainRuntime` - 集中创建 MiniApp runtime-state facade、function-agent Git/AI adapters 和 - function-agent runtime facade；这让后续迁移审查有唯一入口，但不改变 MiniApp - filesystem IO、worker process、host dispatch、built-in asset seed / marker IO / - recompile，或 function-agent Git/AI service call 的 owner。 -- 风险：MiniApp filesystem IO、worker process、host dispatch、builtin asset seed / - marker IO / recompile 都有外部副作用；迁移不当会改变用户数据目录、更新标记、 - rollback、dependency state 或编译/运行顺序。 -- 风险：function-agent Git/AI 调用涉及 provider acquisition、transport error mapping、 - prompt 输入、JSON extraction/repair 和 `analyzed_at` 时序；移动过深可能改变 commit - message、Startchat work-state 或非 Git workspace fallback。 -- 可优化点：优先抽 storage/process/Git/AI 的最小 port contract，让 - `product-domains` 拥有纯 orchestration，core 继续注入 PathManager、process runner、 - Git/AI adapter 和 asset source。 -- 可优化点：把 MiniApp import/sync/recompile/rollback/deps state 的快照基线作为 - 迁移前后对比入口；对 function-agent 保留 no-HEAD diff fallback、非 Git 空状态、 - `analyze_git=false` time-info 和 post-analysis `analyzed_at` 赋值语义。 -- 必须新增或复用的保护：MiniApp import/sync/recompile/rollback/deps state focused - tests、builtin seed marker round-trip、customized update metadata、function-agent - prompt/response policy、Git/AI adapter error mapping 和 Startchat work-state regression。 -- 产品形态门禁：Desktop MiniApp、server/remote workspace、CLI function-agent 路径和 - packaged built-in MiniApp asset 必须继续组装；不得改变 installer、desktop release 或 - user-data seed 产物。 - -HR3：service / agent runtime deep owner migration 的主要风险和控制点： - -- 当前 HR3 结论：本轮只完成 core 内部 owner closure。`CoreServiceAgentRuntime` - 集中创建 remote dialog/cancel/file/tracker host、remote model catalog/session-model - selection adapter、remote image context adapter 和 - `ConversationCoordinator` 的 runtime-port binding；这让后续 service/agent - runtime 深迁移有唯一审查入口，但不改变 remote-connect / remote-SSH / - scheduler / registry 的实际执行路径。 -- 当前 service/agent 深迁移新增完成项：remote chat history 的 message ordering、 - tool preview、assistant presentation assembly 已迁入 `bitfun-services-integrations`。 - core 只保留 persisted `DialogTurnData` 读取、owner DTO 投影、mobile image compression - 和 enhanced remote user input cleanup；remote-SSH、terminal pre-warm、scheduler submit、 - workspace-root source 与 session/workspace persistence read 没有迁移或行为调整。 -- 当前 service/agent 深迁移新增完成项：remote session/model selection 的 alias、 - default/auto、primary/fast 与 config-reference 归一策略已迁入 `bitfun-services-integrations`。 - core 继续负责读取 `AIConfig` 并注入 `resolve_model_reference`，保留缺失 config service - 的既有错误边界。 -- 当前 service/agent 深迁移新增完成项：remote model catalog 的 config-shape assembly - 已迁入 `bitfun-services-integrations`。core 只投影 model capability / reasoning mode - 等 owner facts，并继续持有 config service 读取与 session model resolver 注入；catalog - version 裁剪、capability/reasoning wire 字段和默认模型/session 模型字段装配由 owner crate - 的 contract test 保护。 -- 当前 service/agent 深迁移新增完成项：dialog scheduler outcome assembly 已迁入 - `bitfun-services-integrations`。core 只投影 concrete `DialogSubmitOutcome` 为 owner fact， - scheduler submit、queue policy 映射和 terminal pre-warm 仍留在 core adapter，避免改变 - restore -> prewarm -> submit 的执行顺序。 -- 当前 service/agent 深迁移新增完成项：remote workspace、session、initial-sync、poll - 与 tool/question interaction command orchestration 已迁入 `bitfun-services-integrations`。 - core 只通过 `CoreServiceAgentRuntime` 提供 workspace service、persistence/session restore、 - coordinator、tracker、model catalog 和 user-input host adapter，不改变 response shape、 - poll persistence dirty 判定、默认 reject/cancel reason 或 session/workspace 错误边界。 -- 当前 HR-C 结论：portable contract closure 已完成，新增迁移范围限于 - runtime-ports 可承载的 DTO/trait/fact；concrete remote/runtime 执行路径仍按上方 HR3 - 风险门禁作为后续可选深迁移主题处理。 -- 当前 service/agent 深迁移新增完成项：scheduler submit queue routing、 - interactive preempt 与 agent-session cancel-reply suppression 的纯决策已迁入 - `bitfun-runtime-ports`。core 继续持有 `DialogScheduler` 生命周期、queue storage、 - active-turn map、round-yield flags、outcome loop、coordinator submit 和 agent-session reply - delivery；这一步不改变 queue depth、preempt、cancel suppression 或 background reply - 行为。 -- 风险：remote-SSH manager / remote FS / terminal 与 remote-connect workspace-root - source、persistence/workspace service reads、`ImageContextData` concrete impl 都连接实际远端执行环境； - 迁移不当会破坏 remote workspace guard、terminal pre-warm、response shape、 - image fallback 或 file chunk range 行为。 -- 风险：agent registry / scheduler 现在承载 mode-scoped subagent visibility、 - `Multitask` / `GeneralPurpose` registration、background result delivery、running-turn - injection 和 idle-session follow-up；迁移不当会改变 subagent 可见性、排队、确认边界 - 或 DeepResearch post-turn hook。 -- 可优化点：先把 scheduler/registry 的 observable facts、queue policy decision、 - runtime event fact 与 remote workspace identity 抽成只读 contract；concrete - execution、session restore、terminal binding、workspace-root source 和 persistence/workspace service reads - 继续由 core adapter 注入。 -- 可优化点：对 remote-connect 保持 owner crate 只管 orchestration policy， - core 继续拥有 workspace-root source、persistence/workspace service reads 和 concrete scheduler submit， - 直到有端到端 remote product regression。 -- 可优化点：继续沿用本轮模式拆分“presentation assembly”和“runtime execution”：前者可在 - owner crate 中用 DTO + focused contract test 保护，后者必须等到 remote product regression、 - port/provider 设计和回滚路径齐备后再移动。 -- 必须新增或复用的保护：remote command/response wire、restore -> terminal pre-warm -> - scheduler submit 顺序、file full/chunk/info、image context fallback/preference、 - mode-scoped subagent availability、background delivery、DeepResearch citation - renumber hook、queue/confirmation boundary 和 remote workspace startup guard regression。 -- 产品形态门禁：Desktop remote connect、relay/bot、server, ACP remote config reuse、 - CLI subagent management 和 Review Team 可见性必须继续按当前产品差异运行；不得为了 - service/agent owner 外移统一 surface presentation 或命令语义。 - -剩余数量口径已经收敛到上方队列：低风险准备为 0 个新增小 PR，后续只按完整高风险 owner 主题推进；缺陷修复、行为变更、冗余清理和构建脚本调整必须独立评估，不能伪装成 core decomposition 剩余里程碑。 - -### 里程碑三：facade 收敛、边界强制与可选默认轻量化评估 - -**覆盖计划：** - -- Plan 9：`bitfun-core` 收敛为 facade + product runtime assembly。 -- 边界检查脚本。 -- 依赖版本收敛复查。 -- 可选评估 `bitfun-core default = []`，但仅在完整门禁通过后单独执行。 - -**目标：** - -- `bitfun-core` 不再承载新实现，只负责旧路径兼容和完整产品 runtime 组装。 -- 用边界检查防止新 crate 重新依赖回 core。 -- 评估是否值得让 `bitfun-core` default 变轻，但不把它作为默认结论。 -- 保证整体性能没有明显负向影响。 - -**实现边界：** - -- 可以把旧模块改为 re-export。 -- 可以新增 boundary check 脚本。 -- 可以做低风险直接依赖版本收敛。 -- `default = []` 必须是单独 PR，且只在所有产品 crate 显式启用完整 runtime 后评估。 -- 不允许把 facade 变成新的业务实现聚合。 - -**P3 进入条件与主干补充：** - -- P3 只能在 P2/HR 剩余 runtime owner 已完成迁移，或被显式标为 core-owned / deferred 后启动；不得把 `ToolUseContext`、concrete tools、remote-connect / remote-SSH、MiniApp IO / worker / host / builtin、function-agent Git/AI、agent registry / scheduler 通过 re-export 伪装成已迁移。 -- 最新主干新增的 Deep Review context/cost/queue、agent-stream tool-call dedupe、search fallback、session rollback、remote workspace guard、ACP/Web fallback、mode-scoped subagent visibility、background subagent delivery、DeepResearch citation renumber、tool spec discovery、usage/cache token、Responses flat schema、CLI mode-aware subagent management、desktop lifecycle 与内置 MiniApp seed/update 行为，均必须按触碰 owner 纳入等价测试或明确保留在 product surface。 -- 产品表面仍采用 “surface divergence, capability convergence”：CLI / Desktop / Remote / ACP / Server 可以共享 capability facts 或 ports，但不能为了复用下沉 surface command、UI rendering、timeout policy、presentation 或 app-layer dependency。 -- P3 闭环检查必须同时覆盖 crate graph 与产品 runtime 行为；boundary check 只证明依赖方向，不能替代 Deep Review、MCP dynamic tools、tool manifest / `GetToolSpec`、remote connect、snapshot wrapping、MiniApp/function-agent 的产品等价验证。 - -**阶段复核摘要：** - -- 已完成的语义 baseline 覆盖 MCP config failure、catalog replacement invalidation、dynamic manifest、tool manifest / `GetToolSpec`、MiniApp storage layout adapter、product-domain pure helper 与 core adapter 等价、remote workspace search fallback，以及 core-types / runtime-ports / agent-tools 的轻量边界。 -- boundary check 已锁定已外移 owner 的旧路径 facade-only / 禁止回流状态，并禁止 contract crate 吸收重 runtime、platform adapter、CLI/TUI presentation 或 concrete service 依赖。 -- 后续迁移必须 owner-by-owner 推进：先补 port/provider 设计和等价测试，再移动 runtime owner，最后证明旧路径兼容；`bitfun-core default = []`、per-product feature set、依赖版本收敛和构建收益仍是独立评估项，不与 runtime 外移混合。 - -**验收门：** +构建脚本保护命令： ```powershell -node scripts/check-core-boundaries.mjs -cargo check -p bitfun-core --features product-full -cargo check -p bitfun-cli -cargo test --workspace -cargo build -p bitfun-desktop -pnpm run build:mobile-web -pnpm run desktop:build:fast -pnpm run desktop:build:release-fast git diff -- package.json scripts/dev.cjs scripts/desktop-tauri-build.mjs scripts/ensure-openssl-windows.mjs scripts/ci/setup-openssl-windows.ps1 BitFun-Installer ``` -期望： - -- `bitfun-core` 旧路径兼容。 -- 边界检查通过。 -- 完整 workspace 测试和 desktop build 通过。 -- 构建脚本无 diff。 -- 若性能收益不明显，也不能有明显退化；必要时保留中等粒度边界，不继续拆小。 - -**暂停条件：** - -- 完整产品矩阵无法通过。 -- default feature 轻量化会改变任一产品能力。 -- boundary check 发现 extracted crate 依赖回 core。 -- 构建或链接时间因 crate 过碎出现明显退化且无法通过合并修正。 - ---- - -## 11. 推荐 PR 顺序 - -**已完成主线：** - -- 基础拆分已完成：文档护栏、`product-full` 安全网、workspace crate 移动、`core-types`、`agent-stream`、runtime ports、`services-core`、`services-integrations`、`agent-tools`、`tool-packs` 与 `product-domains` 的低风险 owner 边界。 -- runtime 前置保护已完成：MCP dynamic runtime、remote-connect tracker / wire / pure policy、product-domain pure/facade、tool registry / manifest / GetToolSpec baseline、feature/dependency profile、boundary check 与关键语义回归基线。 -- 当前 core-owned runtime 收口已完成：tool、product-domain、service/agent 三类 runtime 均已有 core 内部单一 owner 入口，并明确列出仍保留在 core 的 concrete IO、scheduler、workspace-root、persistence、MiniApp worker / host / builtin、function-agent Git/AI 等高风险路径。 -- H5 当前只完成 feature/dependency baseline：默认完整产品能力、产品入口显式 `product-full` 装配和 no-default 编译面受保护；不声明 per-product feature matrix、构建收益或 runtime owner 深迁移完成。 - -**后续推荐顺序：** - -| 顺序 | 主题 | 完整范围 | 关键门禁 | -|---|---|---|---| -| 1 | service / agent runtime 深迁移（HR-C 之后可选） | 在 remote-SSH、remote FS / terminal、workspace-root / persistence、`ImageContextData`、agent registry / scheduler 中选择一个 owner 主题，完成端口、adapter、旧路径兼容和行为等价验证 | remote/session/subagent/citation/goal/request-context 等价，产品 surface 不变 | -| 2 | HR-B product-domain runtime 深迁移 | 在 MiniApp filesystem IO / worker / host / builtin seed 或 function-agent Git/AI 中选择一个 owner 主题，不混入 tool/service runtime | MiniApp/function-agent focused regression，PathManager/process/Git/AI 边界清晰 | -| 3 | HR-A tool runtime 深迁移（可选） | 仅在收益明确时评审 `ToolUseContext`、concrete tool IO、manifest execution、snapshot wrapper 或 collapsed unlock state | tool visibility、manifest、GetToolSpec、snapshot、Deep Review tool flow 等价 | -| 4 | H5 feature / build-benefit evaluation（可选） | 只评估 feature matrix、dependency profile 和构建收益数据 | 不迁移 runtime owner，不改产品 feature set、default feature 或构建脚本 | - -执行要求：每次 PR 必须按一个完整 owner 主题推进；预保护、迁移、旧路径兼容、文档更新和对抗性审核属于同一个 PR 的组成部分，不再拆成独立小 PR。 - -### 11A. 后续高风险 PR 队列 - -后续不再新增低风险碎片 PR。每个 PR 必须按一个完整 owner 主题提交，先设计保护网， -再移动 runtime owner，最后用对抗性审核确认没有功能偏移。 - -#### HR-A：Tool Runtime Owner Migration - -目标：在不改变工具可见性、manifest、`GetToolSpec`、collapsed unlock、snapshot wrapper、 -Deep Review tool flow 或具体工具 IO 的前提下，继续收敛 tool runtime owner。 - -当前 HR-A 基线： - -- `bitfun-agent-tools` 新增 provider-neutral file guidance marker、file-read freshness facts / - comparison policy、oversized tool-result storage policy / preview / rendered replacement - contract、tool execution result/error/invalid-call presentation policy，并用 owner-crate contract tests - 锁定这些纯规则。 -- core `file_tool_guidance` 变为兼容 re-export；`file_read_state_runtime` 继续持有 - session/coordinator/read-state storage 与文件 re-read IO，但 freshness 比较委托给 - `agent-tools`；`tool_result_storage` 继续持有 session runtime artifact path、filesystem - write、assistant-only replacement 接线与 `BitFunError` 映射，但 preview/rendering/round - budget selection 委托给 `agent-tools`。 -- `ToolUseContext` 本体、portable facts projection、workspace service accessor、runtime artifact - lookup、path policy enforcement、pipeline/description/preflight context materialization、 - cancellation/post-call hook wrapper、unified `Tool::call` runtime hook facade 与 - Deep Review light checkpoint 绑定已集中到 core `tool_context_runtime.rs`；`framework.rs` - 只保留 `Tool` trait 与旧路径兼容 re-export，core runtime/adapter 模块直接引用 - `tool_context_runtime::ToolUseContext`。 -- 未外移出 core：workspace services、cancellation token、Read/Edit/Write - concrete IO、tool-result filesystem persistence、dynamic MCP concrete execution、snapshot - wrapper 与 collapsed unlock state。它们仍需单独 port/provider 设计和更强等价测试。 - -预保护： - -- 固化 product registry snapshot、expanded/collapsed exposure、prompt-visible manifest、 - `GetToolSpec` summary/detail/result、dynamic provider metadata、snapshot wrapper 覆盖顺序。 -- 覆盖 desktop/MCP/ACP catalog 等价、Deep Review 修改类工具 checkpoint hook、 - cancellation/post-call hook、runtime artifact URI 和 remote workspace path policy。 -- 新增覆盖 Read/Edit/Write 的 session-scoped read state、stale-write guardrail、 - `file_tool_guidance` 文案触发条件、`tool_result_storage` 的大结果跳过/持久化/preview/reference - 行为，以及 session view 对 assistant-only tool result 的 compact/omit 规则。 -- 边界脚本继续禁止 `agent-tools` / `tool-packs` 依赖 core 或 concrete service。 - -实施边界： - -- 可迁移 provider-neutral runtime contract、adapter facade、只依赖 portable facts 的 - registry/manifest assembly 规则。 -- workspace services、cancellation token、Deep Review hook、file read-state storage / - coordinator binding、tool-result filesystem persistence、 - concrete tools、dynamic MCP concrete execution 和 tool IO 只有在已有 port/provider - 设计和等价测试后才能移动。 -- 不改变 tool name、schema、prompt stub、readonly/enabled/filtering、unlock state 生命周期。 - -审核门： - -- 对比迁移前后 registry / manifest / `GetToolSpec` snapshot。 -- 对比 Read/Edit/Write guardrail、runtime artifact reference、assistant transcript compaction - 与 session-view 输出，确认没有隐藏改变工具结果语义或磁盘副作用。 -- 检查是否新增重复 registry/materialization 或额外 async/runtime work。 -- 执行 `cargo test -p bitfun-agent-tools`、`cargo test -p bitfun-core file_read_state_runtime -- --nocapture`、 - `cargo test -p bitfun-core tool_result_storage -- --nocapture`、`node scripts/check-core-boundaries.mjs`、 - `cargo check -p bitfun-core --features product-full`； - 若触碰 dynamic MCP / Deep Review / desktop catalog，再补对应 focused tests。 - -#### HR-B：Product-Domain Runtime Owner Migration - -目标：在不改变 MiniApp filesystem IO、worker process、host dispatch、built-in asset seed / -marker IO、function-agent Git/AI 调用和 Startchat 时序的前提下，继续推进 -`bitfun-product-domains` owner 化。 - -当前 HR-B 执行结论：MiniApp 纯状态 owner 已覆盖 create/update/draft/apply/import -的 version/runtime/meta 组装、imported meta identity/timestamp 规则和 built-in seed meta -timestamp 策略；本轮进一步把 concrete runtime detection、worker pool 容量 / idle / LRU -策略、install-deps 执行计划、host method / fs access / resolved path / shell token / cwd / -timeout / env 等纯决策，以及 export check result policy 迁入 `product-domains`。 -function-agent runtime facade、prompt/response policy 已在前序 H2/HR2 收口；Git/AI service -adapter、AI client、provider acquisition、MiniApp filesystem IO、worker process、host dispatch -执行、export skeleton 和 builtin seed / marker IO 仍保持 core-owned，不在本轮改变行为或边界。 - -预保护： - -- 复用并扩展 MiniApp import/sync/recompile/rollback/deps-state、runtime detection、 - worker install / eviction policy、host-routing decision、built-in seed/update marker、 - customization metadata、function-agent staged diff、prompt/JSON extraction/domain error mapping - 等价测试。 -- 补齐 Git/AI port adapter 的输入输出、错误映射、fallback、`analyze_git=false`、非 Git - 目录和 no-HEAD diff 行为快照。 - -实施边界： - -- 可迁移受保护的 product-domain owner、DTO、port-backed facade、domain parsing policy 和 core adapter 委托层。 - MiniApp runtime detection 已允许作为受保护 owner 迁入 `product-domains`，但 process 执行例外只允许存在于 - `miniapp/runtime.rs`，不得扩散到 worker、host dispatch、storage 或其它 product-domain 模块。 -- MiniApp export check result 可以迁移 ready/runtime/missing/warning 组装策略，但真正 export - skeleton 和后续打包执行必须留在 core adapter，直到另起实现评审。 -- MiniApp filesystem IO、worker process、asset include/seed、marker IO、host dispatch、 - function-agent Git service / AI client / provider acquisition 继续 core-owned，除非本 PR - 先补完整 port/provider 设计和回归。 -- 不改变 MiniApp permission policy、bundle/update semantics、Git commit-message 生成行为、 - Startchat work-state 输出或产品 surface。 - -审核门： - -- 对比 core adapter 与 owner facade 的快照输出。 -- 检查是否把 PathManager、Git/AI concrete service、worker process、host dispatch execution - 或 builtin marker/source IO 下沉到 - `product-domains`。 -- 执行 `cargo test -p bitfun-product-domains`、相关 `bitfun-core` MiniApp/function-agent focused - tests、`node scripts/check-core-boundaries.mjs`、`cargo check -p bitfun-core --features product-full`。 - -#### HR-C：Service / Agent Runtime Contract Closure - -目标：在不改变 remote-connect、remote-SSH、terminal pre-warm、scheduler/registry、 -subagent visibility、background delivery、DeepResearch citation renumber hook 和 session restore -语义的前提下，完成 service/agent runtime 的 portable contract closure；不把 concrete runtime -owner 深迁移混入本里程碑。 - -预保护： - -- 固化 remote command/response wire、poll/model catalog delta、queue/event fanout、restore -> - terminal pre-warm -> scheduler submit 顺序、file full/chunk/info、image context - fallback/preference、remote workspace startup guard。 -- 固化 mode-scoped subagent availability、`Multitask` / `GeneralPurpose` registration、 - background result delivery、running-turn injection、idle-session follow-up、DeepResearch - post-turn citation artifact 语义。 -- 固化 `/goal` activation、AI-generated goal fallback、session custom metadata patch/clear、 - `GoalVerificationStarted` / `GoalVerificationFinished` events、continuation planning、 - main-session-only gate、Flow Chat local pending/verifying turn 的现有语义。 -- 固化 request-context section ordering、workspace `related_paths` prompt output、local - canonicalization、remote validation、prompt compression events、cache-stable prompt assembly - 和 provider adapter 的 reasoning/tool-call serialization 边界。 - -实施边界： - -- 可迁移只读 facts、queue/restore decision、remote workspace DTO、workspace/session response - assembly helper、port/provider contract 和 core adapter binding。 -- 已迁移的低风险 contract：dialog submission source / priority / policy / outcome、 - agent-session reply route、steering buffered outcome、round injection kind / target / message / - source traits、subagent context mode、delegation policy、goal-mode DTO、prompt compression - contract 与 workspace related-path fact 归属 `bitfun-runtime-ports`；core 旧路径只作为兼容 - re-export。queue wait timer 因依赖 - `Instant` / `Duration` 且服务 DeepReview admission timing，仍保留 core-owned，后续若外移需 - 单独证明不是把 runtime state 放入 DTO/trait crate。 -- 已迁移的 remote-connect presentation assembly：remote chat history 的 user/assistant - message shape、thinking/text/tool item ordering、tool preview slimming、in-progress assistant - skip 与 tool input exposure policy 由 `bitfun-services-integrations` 组装；core 只负责把 - persisted session 数据投影为 `RemoteChatHistoryTurn`，并继续持有 image compression 与增强输入清理。 -- 已迁移的 remote model policy：remote session model id normalization、model selection - alias handling 与 config-reference resolution policy 由 `bitfun-services-integrations` 提供； - core adapter 只负责读取 `AIConfig` 并注入 resolver，保持原有 config service 缺失错误。 -- 已迁移的 remote command orchestration：workspace、session、initial-sync、poll 与 - interaction command handler 由 `bitfun-services-integrations` 拥有；core adapter 只注入 - workspace service、persistence/session restore、coordinator、tracker、model catalog 与 - user-input manager，并继续保留 concrete runtime 生命周期。 -- concrete scheduler/session restore、workspace-root source、persistence/workspace service reads、 - `ImageContextData` concrete impl、remote-SSH runtime、terminal adapter、agent registry/scheduler、 - round injection buffer、goal-mode coordinator binding、request-context assembly 与 prompt compression runtime 继续 - core-owned，除非本 PR 有端到端 regression 和明确回滚路径。 -- 不统一 Desktop / CLI / ACP / Remote / Server surface 命令或 presentation。 - -审核门： - -- 对比 remote/session/subagent/citation 行为快照。 -- 对比 goal verification、request-context related-path sections、compression/cache events 与 - provider stream/tool-call shape，确认迁移没有改变上下文内容或触发时序。 -- 检查是否引入新全局 coordinator 访问、反向依赖 core、额外 network/process startup 或 - scheduler 生命周期变化。 -- 执行 owner crate tests、remote-connect / scheduler / agent runtime focused tests、 - `node scripts/check-core-boundaries.mjs`、`cargo check -p bitfun-core --features product-full`； - 按触碰范围补 desktop / CLI / ACP / server checks。 - -#### H5：Feature / Build-Benefit Evaluation - -目标：只评估 feature matrix、dependency profile 和构建收益，不迁移 runtime owner。 - -预保护： - -- 先记录 `bitfun-core`、owner crates、Desktop、CLI、ACP、Server、Relay 的 feature graph / - dependency profile。 -- 确认产品 crate 继续显式启用完整能力，release/CI/fast build 脚本无 diff。 +期望结果：没有 diff。 -实施边界： +## 7. 验证矩阵 -- 可补 boundary check、cargo metadata/cargo tree 证据和文档。 -- 不修改 default feature、产品 feature set、构建脚本或产品能力。 +按触碰范围选择最小但足够的验证： -审核门： +| 触碰范围 | 最小验证 | +|---|---| +| contract / DTO / boundary 文档 | `pnpm run check:repo-hygiene`，必要时补 `node scripts/check-core-boundaries.mjs` | +| Runtime ports / service boundary | `cargo test -p bitfun-runtime-ports`，`cargo check -p bitfun-core --features product-full` | +| Service integrations / Remote | owner crate focused tests，remote-connect / remote-SSH focused tests，`cargo check -p bitfun-core --features product-full` | +| Remote product surfaces | 触碰 remote connection / workspace / projection 时，按范围补 Desktop remote connect、relay / mobile session、ACP remote config reuse、CLI subagent / remote-adjacent path 验证 | +| Tool runtime | `cargo test -p bitfun-agent-tools`，tool manifest / `GetToolSpec` / snapshot focused tests，`node scripts/check-core-boundaries.mjs` | +| Product domains | `cargo test -p bitfun-product-domains`，MiniApp / function-agent focused tests | +| Product surface 或 Tauri/API 触碰 | `cargo check -p bitfun-desktop`，必要时补 Web UI 或 mobile-web 验证 | +| 大范围 owner 迁移 | `cargo check --workspace`；若行为面广，再补 `cargo test --workspace` | -- 对比 no-default、product-full、产品入口依赖面。 -- 明确哪些 owner 已能绕开 heavy runtime，哪些仍因 core facade 阻塞；不得把局部收益写成 - 整体构建收益。 +任何声明构建收益的 PR 必须记录迁移前后 cargo metadata / cargo tree / check 数据；不声明收益时，也不得造成明显编译或运行时退化。 -冗余清理 PR 不进入上述主线序号。只有在满足 `0A.6` 的绝对等价要求时，才可以插入到相邻里程碑之间，并且不得与主线拆分 PR 混合。 +## 8. 暂停条件 ---- +- 必须改变用户可见行为、权限策略、产品命令、默认能力或 release 构建形态才能继续。 +- 新 owner crate 必须依赖回 `bitfun-core` 才能编译。 +- contract crate 开始吸收 Tauri、CLI/TUI、network client、process execution、`git2`、`rmcp`、`image`、`tokio-tungstenite` 等 concrete runtime 依赖。 +- Remote / Tool / MiniApp / function-agent / scheduler 迁移无法给出迁移前后等价测试或可复核 snapshot。 +- Product Assembly 变成无类型 service locator 或全局 mutable app state。 +- 某个产品 crate 需要减少 feature 才能通过编译。 -## 12. 完成标准 +## 9. 完成标准 -- stream processor 和纯 service 测试可以在不编译完整产品 runtime 的情况下运行。 -- 至少有一组 dependency profile 证明低层 contract / owner crate 可以绕开 `bitfun-core` 和对应 heavy dependency；若只有极少数模块可做到，必须在文档中明确剩余阻塞 owner，而不能声明重构完成。 -- 产品构建脚本和 release/fast build 脚本没有因为 core 拆解被修改。 -- 产品 crate 仍拥有拆解前的完整能力集合。 -- `bitfun-core` 对现有调用方保持 import-compatible。 -- 新拆出的 crate 不依赖回 `bitfun-core`。 -- 新增 crate 数量保持在中等粒度范围；继续拆小必须有依赖、owner 或实测收益依据。 -- 重依赖归属于真正需要它们的 owner crate。 -- `service` 与 `agentic` 的跨层调用通过 ports/providers，而不是 global concrete access。 -- 至少在关键 crate 拆出后，有边界检查脚本防止回退。 -- 每个关键迁移点都有注释说明兼容门面、owner crate 或接口边界。 -- 冗余清理只处理已证明绝对等价的重复代码；不因为相似流程引入新抽象。 +- `bitfun-core` 只保留兼容 facade 和产品组装，不再承载新 runtime owner 实现。 +- Agent Runtime SDK、Runtime Services、Tool Runtime、Harness、Product Capabilities 与 Concrete Integrations 的依赖方向可由边界检查证明。 +- 至少有一组低层 contract / owner crate 可以绕开完整 `bitfun-core` 和对应 heavy dependency。 +- 产品 crate 仍拥有拆解前的完整能力集合，且旧公开 import 路径保持兼容。 +- Remote、Tool、MiniApp/function-agent、scheduler/registry 等高风险路径都有等价测试、旧路径兼容和回滚边界。 +- 新增 crate 数量保持中等粒度；继续拆小必须有 owner、依赖或实测收益依据。 +- 已完成事实只记录在归档文档中，主计划持续聚焦当前方向和待完成事项。