Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions AGENTS-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ BitFun 是一个由 Rust workspace 与共享 React 前端组成的项目。
|---|---|---|
| Core(产品逻辑) | `src/crates/core` | [AGENTS.md](src/crates/core/AGENTS.md) |
| 已拆出的 core 支撑 crate | `src/crates/{core-types,agent-stream,runtime-ports,terminal,tool-runtime}` | (使用 core 指南) |
| Core owner crate | `src/crates/{services-core,services-integrations,agent-tools,tool-packs,product-domains}` | (使用 core 指南 + 拆解护栏) |
| Transport 适配层 | `src/crates/transport` | (使用 core 指南) |
| API layer | `src/crates/api-layer` | (使用 core 指南) |
| AI adapters | `src/crates/ai-adapters` | [AGENTS.md](src/crates/ai-adapters/AGENTS.md) |
Expand Down
1 change: 1 addition & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ Repository rule: **keep product logic platform-agnostic, then expose it through
|---|---|---|
| Core (product logic) | `src/crates/core` | [AGENTS.md](src/crates/core/AGENTS.md) |
| Extracted core support | `src/crates/{core-types,agent-stream,runtime-ports,terminal,tool-runtime}` | (use core guide) |
| Core owner crates | `src/crates/{services-core,services-integrations,agent-tools,tool-packs,product-domains}` | (use core guide + decomposition guardrails) |
| Transport adapters | `src/crates/transport` | (use core guide) |
| API layer | `src/crates/api-layer` | (use core guide) |
| AI adapters | `src/crates/ai-adapters` | [AGENTS.md](src/crates/ai-adapters/AGENTS.md) |
Expand Down
11 changes: 11 additions & 0 deletions docs/architecture/core-decomposition.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,14 @@ owner 边界,否则不要把一个 feature group 继续拆成更小的 crate

- 新拆出的 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 facade、MCP tool contract facade、MCP protocol types facade、
MCP config location facade 和 announcement types facade 由边界脚本检查,不得重新承载实现逻辑。
- 对仍嵌在 core runtime 文件中的旧公开类型,必须至少保留禁止回流检查;例如 MCP server
type/status 已由 owner crate 拥有,`MCPServerProcess` 只保留 runtime 逻辑。
- `bitfun-runtime-ports` 必须保持 DTO/trait-only;不得依赖 concrete manager、
service implementation、app crate 或 platform adapter。
- `bitfun-core-types` 不得依赖 runtime manager、service crate、agent runtime、
Expand All @@ -97,6 +105,9 @@ owner 边界,否则不要把一个 feature group 继续拆成更小的 crate
代码必须面向 port contract,而不是新增对 coordinator 或 manager 的直接依赖。
- Agent runtime 必须通过 ports/providers 依赖 service 行为,不要依赖 concrete 的重集成
crate。
- 最新主干已把 subagent 可见性做成 mode-scoped registry 行为。迁移 agent registry 或
subagent definitions 前,必须先保留 mode visibility、hidden/custom/review 分组和 desktop
subagent API 等价测试;在此之前它们仍属于 `bitfun-core` product runtime assembly。
- Tool framework crate 不得依赖 concrete service implementation。
- 产品 crate 可以通过显式 product feature 组装完整 runtime。

Expand Down
55 changes: 41 additions & 14 deletions docs/plans/core-decomposition-plan.md
Original file line number Diff line number Diff line change
Expand Up @@ -965,18 +965,21 @@ product-full = ["git", "mcp", "remote-ssh", "remote-connect", "announcement", "f

**任务:**

- [ ] 先迁移 `git`,因为边界相对清晰。
- [x] 先迁移 `git`,因为边界相对清晰。
- [ ] 再迁移 `remote-ssh`,保留 `ssh-remote` 语义。
- [x] 先迁移 `remote-ssh` 的纯 contract/type,runtime manager / fs / terminal 仍保留在 core。
- [ ] 再迁移 `mcp`,动态工具通过 `DynamicToolProvider` 接入。
- [x] 先迁移 `mcp` 的纯 tool-name / tool-info / protocol types / config location / server type-status contract,config service / server process / adapter / auth / dynamic tools 仍保留在 core。
- [x] 先迁移 `announcement` 的纯 types contract,scheduler / state store / content loader / remote fetch 仍保留在 core。
- [ ] 最后迁移 `remote-connect`,通过 `AgentSubmissionPort`、`SessionTranscriptReader`、`EventSink` 解耦 agent runtime。
- [x] 已迁移的集成能力保持 core 旧路径 re-export。
- [x] 产品完整 runtime 通过 `services-integrations/product-full` 启用已迁移集成能力。

**当前安全迁移状态(2026-05-11):**
**当前安全迁移状态(2026-05-12):**

- 已迁移到 `bitfun-services-integrations`:`service::file_watch`,通过 `file-watch` / `product-full` feature 启用,并保持 `core::service::file_watch` 旧路径。
- `git`、`remote-ssh``mcp`、`remote-connect`、`announcement` 尚未迁移它们涉及 Git service、SSH runtime、MCP dynamic tool provider、remote agent submission 与 announcement config/path 边界,继续前需要单独确认端口方案与等价性测试。
- 最新主干的 Deep Review capacity / cost / queue 控制仍属于 core runtime 与 review-team orchestration,不在本轮 `services-integrations` 迁移范围内;如果后续迁移 remote-connect / MCP,需要先定义这些运行状态的 port 合约
- `git` 已完成 DTO/params/graph/raw command output/text parser/arg builder、`GitError`、`GitService` runtime implementation 与 git utils 迁移;`bitfun-core::service::git::*` 仅保留 legacy facade re-export。`remote-ssh` 仅迁移了纯 contract/type,SSH runtime manager / fs / terminal 仍保留在 core;`mcp` 仅迁移了 tool-name / tool-info / protocol types / config location / server type-status contract,config service / json config / cursor format / jsonrpc / transport / server process / adapter / auth / dynamic tools 仍保留在 core;`announcement` 仅迁移了纯 types contract,scheduler / state store / content loader / remote fetch 仍保留在 core;`remote-connect` 尚未迁移它们涉及 SSH runtime、MCP dynamic tool provider、remote agent submission 与 announcement config/path 边界,继续前需要单独确认端口方案与等价性测试。
- 最新主干的 Deep Review capacity / cost / queue、context profile、evidence ledger、session manifest、stream dedupe、search remote/fallback 与 session rollback persistence 仍属于 core runtime 或对应产品 runtime,不在本轮 `services-integrations` 迁移范围内;如果后续迁移 remote-connect / MCP / search / session,需要先定义运行状态 port 合约和等价测试

**验证:**

Expand Down Expand Up @@ -1125,8 +1128,8 @@ cargo check -p bitfun-server

**任务:**

- [ ] 将可替换的实现模块改为 re-export。
- [ ] 在顶层加入关键节点注释:
- [x] 将可替换的实现模块改为 re-export(限本轮已迁移 owner crate;高耦合 runtime 保留为 core-owned runtime)
- [x] 在顶层加入关键节点注释:

```rust
//! Compatibility facade and full product runtime assembly.
Expand All @@ -1135,17 +1138,24 @@ cargo check -p bitfun-server
//! This crate re-exports legacy paths and wires the full BitFun product runtime.
```

- [ ] `bitfun-core/Cargo.toml` 只保留 facade 和 product assembly 所需依赖。
- [ ] 旧路径保持 import-compatible。
- [ ] `bitfun-core/Cargo.toml` 只保留 facade 和 product assembly 所需依赖;当前仍因 core-owned runtime 保留 concrete runtime 依赖,不在本 PR 强行删减
- [x] 旧路径保持 import-compatible。
- [ ] 只有所有产品 crate 都显式启用完整 runtime 后,才可以在独立 PR 中评估:

```toml
default = []
```

**当前收敛状态(2026-05-11):**

- 本轮不把 `remote-ssh` runtime、MCP runtime、`remote-connect`、announcement runtime、concrete tool implementations、tool registry、miniapp runtime/compiler/builtin、function-agent 运行逻辑声明为已迁移;它们继续作为 `bitfun-core` 的 product runtime assembly 拥有路径。`git` feature group 已外移;`remote-ssh` 目前只外移 contract/type;`mcp` 目前只外移 tool-name / tool-info / protocol types / config location / server type-status contract;`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
Expand Down Expand Up @@ -1494,12 +1504,14 @@ cargo check --workspace
- 新增 crate 数量仍保持中等粒度。
- heavy dependency 所属 crate 清晰。

**当前 P2 执行状态(2026-05-11):**
**当前 P2 执行状态(2026-05-12):**

- 已完成中等粒度 owner crate 成型的安全部分:`bitfun-services-core`、`bitfun-services-integrations`、`bitfun-agent-tools`、`bitfun-tool-packs`、`bitfun-product-domains` 均已加入 workspace。
- 已迁移的模块均由 core facade re-export,未改变产品默认 feature、构建脚本或 release 脚本。
- 未声明完成的 P2 剩余部分:重 service 迁移、concrete tool implementation 迁移、tool registry/provider 化、miniapp/function-agent 运行逻辑迁移。这些会触碰 `PathManager`、`BitFunError`、`ToolUseContext`、workspace service、snapshot wrapper、`AgentSubmissionPort` 或 Git/AI service 边界,需要在继续前显式确认。
- 本次 rebase 后重新核对最新主干 Deep Review capacity/cost/queue、context profile、evidence ledger 与 session manifest 变更:当前 PR 只迁移已声明的纯类型/低耦合模块并保留 core facade,未改动这些行为路径;后续迁移必须补端口设计和等价测试后再推进。
- Git feature group 已闭环迁移到 `bitfun-services-integrations` 的 `git` feature:DTO/params/graph/raw command output/text parser/arg builder、`GitError`、`GitService` runtime implementation 与 git utils 均由 integrations owner crate 拥有,并通过 `bitfun-core::service::git::*` 保留旧路径兼容。`GitService` 所需的 Windows `libgit2` system-link 边界挂在该 crate 的 `git` feature 上;`bitfun-core` 仍因未迁移的 remote-connect runtime 保留其它 `git2` 使用。
- 未声明完成的 P2 剩余部分:remote-ssh runtime、MCP server/adapter/auth/dynamic tools、remote-connect 等重 service 迁移、concrete tool implementation 迁移、tool registry/provider 化、miniapp/function-agent 运行逻辑迁移。这些会触碰 `PathManager`、`BitFunError`、`ToolUseContext`、workspace service、snapshot wrapper、`AgentSubmissionPort` 或 AI service 边界,需要在继续前显式确认。
- 本次 rebase 后重新核对最新主干 Deep Review capacity/cost/queue、context profile、evidence ledger 与 session manifest 变更:当前 PR 已完成 Git feature group 的 owner crate 归属迁移,但未改动这些 Deep Review 行为路径;后续迁移必须补端口设计和等价测试后再推进。
- 本次 P2 后续复核结论:上述高耦合剩余项不是纯文件搬迁;若继续迁移会改变依赖方向或需要新增 port/provider 行为合约。因此当前 PR 将它们显式保留为 core-owned runtime,并通过 P3 boundary check 防止已拆 owner crate 回流依赖 core。

**暂停条件:**

Expand Down Expand Up @@ -1532,12 +1544,27 @@ cargo check --workspace
- `default = []` 必须是单独 PR,且只在所有产品 crate 显式启用完整 runtime 后评估。
- 不允许把 facade 变成新的业务实现聚合。

**P3 进入条件与最新主干补充(2026-05-11):**
**P3 进入条件与最新主干补充(2026-05-12):**

- P3 只能在 P2 剩余迁移闭环后启动:重 service 迁移、concrete tool implementation 迁移、tool registry/provider 化、miniapp/function-agent 运行逻辑迁移都必须先完成或显式保留为 core-owned runtime。
- 最近 `origin/main` 的 Deep Review 变更增加了 context profile、evidence ledger、capacity/cost/queue 控制、`deep_review_run_manifest` / `deep_review_cache`、以及 review-team UI orchestration。P3 facade 收敛前必须确认这些行为要么仍由 core product runtime assembly 拥有,要么已有对应 owner crate + port/provider 合约和等价测试。
- `ToolUseContext` 的 shared-context / evidence checkpoint hook、`TaskTool` / `CodeReviewTool` 的 Deep Review capacity flow、以及 session manifest/cache persistence 不能在 P3 中只通过 re-export 消失;如果外移,需要先补 boundary contract、旧路径兼容和 Deep Review regression。
- 最近 `origin/main` 的 Deep Review 变更增加了 context profile、evidence ledger、capacity/cost/queue 控制、`deep_review_run_manifest` / `deep_review_cache`、以及 review-team UI orchestration;最新主干还补充了 agent-stream tool-call dedupe、search remote/fallback、session rollback persistence 和 companion typewriter。P3 facade 收敛前必须确认这些行为要么仍由 core product runtime assembly 拥有,要么已有对应 owner crate + port/provider 合约和等价测试。
- 最新主干的 mode-scoped subagent visibility 将 `agentic::agents` 重组为 definitions / registry / visibility 边界,并扩展了 desktop subagent API 与 Review Team 可见性测试;后续若迁移 agent registry,不能只做路径 re-export,必须保留 mode 可见性过滤、hidden/custom/review 分组语义和前后端 API contract。
- `ToolUseContext` 的 shared-context / evidence checkpoint hook、`TaskTool` / `CodeReviewTool` 的 Deep Review capacity flow、session manifest/cache persistence、rollback persisted-turn cleanup、search fallback chain 与 stream finish/tool-call contract 不能在 P3 中只通过 re-export 消失;如果外移,需要先补 boundary contract、旧路径兼容和对应 regression。
- P3 的闭环检查应同时覆盖 Rust crate graph 与产品 runtime 行为:边界脚本只证明依赖方向,不能替代 Deep Review、MCP dynamic tools、remote connect、snapshot wrapping、miniapp/function-agent 的产品等价性验证。
- 当前 PR 的 P3 范围按“显式保留 core-owned runtime + 强制 owner crate 边界”闭环;后续如果要继续外移这些 runtime 路径,需要作为新的迁移批次先补 port 设计、等价测试和用户确认。

**阶段复核与后续拆分(2026-05-12 rebase 后):**

- 当前分支保持小粒度:只包含 boundary check、facade/product runtime 注释、阶段文档和 Git feature group 归属迁移;不继续混入 remote-connect、MCP dynamic tools、tool registry、miniapp 或 function-agent runtime 迁移。
- 本次 rebase 到 `fork/main` 的新增主干提交 `2e0e2dda` 没有和当前分支产生路径重叠;其 agent visibility 重构不改变本轮 `services-integrations` / service facade 迁移内容,但会把后续 agent registry/provider 外移的等价性门槛抬高。
- 质量边界:本阶段只证明已拆 owner crate 不依赖回 `bitfun-core`,并证明 Git 旧路径仍通过当前 Rust workspace 检查;不声明 remote connect、MCP dynamic tools、snapshot wrapping、miniapp/function-agent runtime 的外移完成。
- boundary check 已扩展到 `core-types`、`runtime-ports` 和 `agent-tools` 的轻量边界,并覆盖 Cargo inline 依赖和 dependency table 依赖声明,后续不能绕过脚本把重 runtime、concrete service 或 platform adapter 依赖带入这些 contract crate。
- boundary check 也已锁定 `bitfun-core::service::git`、`bitfun-core::service::remote_ssh::types`、`bitfun-core::service::mcp::{tool_info,tool_name}`、`bitfun-core::service::mcp::protocol::types`、`bitfun-core::service::mcp::config::location` 和 `bitfun-core::service::announcement::types` 的旧路径 facade-only 状态,并禁止在 `MCPServerProcess` runtime 文件重新定义已外移的 server type/status contract。
- 后续迁移必须拆成可独立审核的提交:先补 port/provider 设计和等价测试,再按 `remote-ssh` runtime、MCP runtime、`remote-connect` 的顺序一次迁移一个 service feature group。
- tool registry / concrete tool implementation 外移必须先有工具清单等价测试,并保留 dynamic provider metadata;不能把注册名解析、snapshot wrapper 或 runtime restriction 行为改成隐式约定。
- 已新增内置工具清单基线测试,后续 registry/provider 外移必须先保持该清单和注册顺序等价,再评估 owner crate 边界。
- miniapp 与 function-agent runtime 外移必须先明确 Git/AI service、PathManager、process execution 和 permission policy 边界;如果需要行为合约变化,必须作为后续单独 PR 并先确认。
- `bitfun-core default = []` 和依赖版本收敛仍是后续独立评估项,不与 runtime 外移或构建脚本调整混在同一批提交。

**验收门:**

Expand Down
Loading
Loading