# https://github.com/bigduu/Bamboo-agent 项目说明书

生成时间：2026-07-27 02:47:14 UTC

## 目录

- [项目概览](#page-overview)
- [Src 模块](#page-crates-core-bamboo-domain-src)
- [Src 模块](#page-crates-core-bamboo-agent-core-src)
- [App 模块](#page-crates-app)

<a id='page-overview'></a>

## 项目概览

### 相关页面

相关主题：[Src 模块](#page-crates-core-bamboo-domain-src)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/bigduu/Bamboo-agent/blob/main/README.md)
- [Cargo.toml](https://github.com/bigduu/Bamboo-agent/blob/main/Cargo.toml)
- [routes/agent.rs](https://github.com/bigduu/Bamboo-agent/blob/main/routes/agent.rs)
- [handlers/agent/projects.rs](https://github.com/bigduu/Bamboo-agent/blob/main/handlers/agent/projects.rs)
- [handlers/agent/sessions/types.rs](https://github.com/bigduu/Bamboo-agent/blob/main/handlers/agent/sessions/types.rs)
- [crates/infra/bamboo-projects/src/lib.rs](https://github.com/bigduu/Bamboo-agent/blob/main/crates/infra/bamboo-projects/src/lib.rs)
- [docker/Dockerfile](https://github.com/bigduu/Bamboo-agent/blob/main/docker/Dockerfile)
</details>

# 项目概览

Bamboo-agent 是一个面向 AI Agent 工作负载的服务端运行时，向上承接 Lotus 前端的交互请求，向下桥接多种 LLM Provider 与工具运行时，并对外暴露以 `/v1/...` 为前缀的 HTTP API。本页给出仓库整体定位、模块划分、关键能力与当前演进焦点，作为后续深入各子系统文档的入口。

## 项目定位与边界

Bamboo-agent 承担「Agent 协议层 + Provider 路由层 + 项目/会话持久层」三重职责：

- **协议层**：定义 chat、execute、sessions、projects 等 REST 端点，统一请求/响应 schema；
- **路由层**：通过模块化配置（见 #597）决定每次请求命中哪个 Provider 实例、是否启用 MCP、是否走 cluster-fabric 路由；
- **持久层**：管理 session 消息、project manifest、workspace 绑定以及 legacy 配置根的兼容性写回。

资料来源：[README.md:1-40]()、[routes/agent.rs:151-154]()

上游消费者主要是同组织的 [bigduu/Lotus](https://github.com/bigduu/Lotus) 前端与跨模块协调组件 Zenith（见 Zenith#9），它们决定了 API 兼容性与 breaking-change 策略：例如 Lotus#162 推动 `#733` 引入 `Idempotency-Key`，Lotus#153/154/155 推动 `#725 #726 #727 #732` 等会话/项目增强。

## 模块结构

仓库采用 Cargo workspace，按「infra / handlers / routes」三层拆分核心 crates：

| 层 | 代表路径 | 职责 |
| --- | --- | --- |
| 基础设施层 | `crates/infra/bamboo-projects/src/lib.rs` | Project 清单、workspace 绑定、legacy 迁移规划（如 `plan_legacy_migration`，`lib.rs:1600`） |
| 业务处理层 | `handlers/agent/projects.rs`、`handlers/agent/sessions/types.rs` | REST handler、请求/响应类型（如 `PatchSessionRequest` 位于 `types.rs:305`） |
| 路由装配层 | `routes/agent.rs` | 将 handler 挂载到 axum Router；archive/路由表见 `routes/agent.rs:151-154` |

Provider 与 MCP 的运行时绑定则落在 `Config` 的 sections（`cluster-fabric`、`providers`、`provider-instances` 等）之下，由 `config_io_lock` 与各 section envelope revision 共同保护并发写。

资料来源：[Cargo.toml:1-30]()、[crates/infra/bamboo-projects/src/lib.rs:542-644]()、[handlers/agent/sessions/types.rs:305]()

## 关键能力一览

当前主干 API（按路由文件汇总）至少包含：

- **会话生命周期**：`POST /v1/sessions`、`PATCH /v1/sessions/{id}`、`POST /v1/chat`、`POST /v1/execute`。`PatchSessionRequest` 支持 `project_id` 的 assign/unassign，workspace 切换的即时持久化由 `#726` 推动。
- **项目管理**：`GET /v1/projects`（`handlers/agent/projects.rs:124`）返回 `ProjectManifest` 列表；`POST /v1/projects/:id/archive`（`handlers/agent/projects.rs:284`）执行归档；与之配套的恢复端点与 summary 字段在 `#725 #727` 中演进。
- **迁移与兼容**：`POST /v1/projects/migrations/legacy/dry-run` 提供从 legacy 工程迁移到 Bamboo project 的预演计划；服务端补全 `canonical_path / git_common_dir / legacy_project_keys`（见 `#728`，`crates/infra/bamboo-projects/src/lib.rs:1600`）。
- **多实例 Provider**：`/bamboo/settings/provider-instances` 已存在，但与 `Config.providers`（`ProviderConfigs{openai,anthropic,gemini,copilot,bodhi}`）仍双轨并存，重构由 `#730` 推进。
- **幂等与并发安全**：`POST /v1/chat`、`/v1/execute`、`/v1/sessions` 将接受可选 `Idempotency-Key`（见 `#733`）；模块化配置的 section revision 与 lock 由 `#686 #701 #729 #735 #736 #737 #738` 系列修复持续收紧。

```mermaid
flowchart LR
  Client[Lotus / CLI] -->|HTTP /v1/...| Router[routes/agent.rs]
  Router --> Handlers[handlers/agent/*]
  Handlers --> Infra[crates/infra/*]
  Handlers --> Providers[Provider Instances<br/>openai/anthropic/gemini/...]
  Providers -->|Routify| Upstream[Upstream LLM APIs]
  Infra -->|section revision| Config[(Modular Config<br/>config.json)]
```

## 演进焦点与社区关注点

社区近期工作集中在三件事：

1. **配置权威统一**：将所有 credential-backed section 的写路径收敛到 typed section envelope revision（#737、#738），并在 cluster-fabric 上已落地的 #729 经验推广到 provider/MCP（#735、#736）。
2. **Provider 多实例化收尾**：清理 `Config.provider / Config.providers` 这条遗留构造 substrate（#730），让 provider-instances 成为唯一运行时入口。
3. **前端协作能力补齐**：包括 session copy（#732）、Idempotency-Key（#733）、project archive/unarchive 与 summary（#725、#727）、workspace 切换持久化（#726）等。

最新发布版本为 **Release v2026.3.3**（与 `v0.3.2` 对比，参见仓库 Releases 页）。这些方向决定了贡献者最常打交道的入口文件：`routes/agent.rs`、`handlers/agent/projects.rs`、`handlers/agent/sessions/types.rs` 以及 `crates/infra/bamboo-projects/src/lib.rs`。

资料来源：[Cargo.toml:1-30]()、[routes/agent.rs:151-154]()、[handlers/agent/projects.rs:124-284]()、[handlers/agent/sessions/types.rs:305]()、[crates/infra/bamboo-projects/src/lib.rs:1600]()、[docker/Dockerfile:1-40]()

---

<a id='page-crates-core-bamboo-domain-src'></a>

## Src 模块

### 相关页面

相关主题：[项目概览](#page-overview), [Src 模块](#page-crates-core-bamboo-agent-core-src)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [crates/core/bamboo-domain/src/lib.rs](https://github.com/bigduu/Bamboo-agent/blob/main/crates/core/bamboo-domain/src/lib.rs)
- [crates/core/bamboo-domain/src/ledger/mod.rs](https://github.com/bigduu/Bamboo-agent/blob/main/crates/core/bamboo-domain/src/ledger/mod.rs)
- [crates/core/bamboo-domain/src/ledger/record.rs](https://github.com/bigduu/Bamboo-agent/blob/main/crates/core/bamboo-domain/src/ledger/record.rs)
- [crates/core/bamboo-domain/src/mcp_config.rs](https://github.com/bigduu/Bamboo-agent/blob/main/crates/core/bamboo-domain/src/mcp_config.rs)
- [crates/core/bamboo-domain/src/poison.rs](https://github.com/bigduu/Bamboo-agent/blob/main/crates/core/bamboo-domain/src/poison.rs)
- [crates/core/bamboo-domain/src/project.rs](https://github.com/bigduu/Bamboo-agent/blob/main/crates/core/bamboo-domain/src/project.rs)
- [crates/infra/bamboo-projects/src/lib.rs](https://github.com/bigduu/Bamboo-agent/blob/main/crates/infra/bamboo-projects/src/lib.rs)
- [routes/agent.rs](https://github.com/bigduu/Bamboo-agent/blob/main/routes/agent.rs)
- [handlers/agent/projects.rs](https://github.com/bigduu/Bamboo-agent/blob/main/handlers/agent/projects.rs)
- [handlers/agent/sessions/types.rs](https://github.com/bigduu/Bamboo-agent/blob/main/handlers/agent/sessions/types.rs)
</details>

# Src 模块

## 概述

`Src` 模块是 Bamboo-agent 项目的核心源代码根目录，采用 Cargo workspace 多 crate 架构组织 Rust 源码。整个仓库围绕「领域建模 + 基础设施分层 + HTTP 接口」三条主线展开，分别对应 `crates/core/bamboo-domain`、`crates/infra/*` 以及根目录的 `routes`/`handlers` 等模块。该模块承担配置域、Provider 实例、会话、项目、迁移、MCP 运行时等核心业务能力的实现与对外暴露职责。

资料来源：[crates/core/bamboo-domain/src/lib.rs:1-50]()

## 模块结构

### 领域核心 (bamboo-domain)

`bamboo-domain` 是系统的领域模型层，聚合了所有核心数据结构与不变量。

- **`ledger/`**：负责配置变更账本，记录每一次 section 级别的写入以支持修订号（revision authority）校验，参见 #729、#735、#737 的统一修订权威改造。
- **`mcp_config.rs`**：定义 MCP（Model Context Protocol）运行时的配置结构，被 #736 提及为「legacy provider/MCP runtime effects」绑定 config generations 的关键载体。
- **`project.rs`**：项目聚合根，承载 `ProjectManifest`、`workspace_count`、`session_count` 等摘要字段（参见 #727）。
- **`poison.rs`**：检测/防御并发写入导致的状态污染，是 `config_io_lock` 释放后保证一致性的工具模块。

资料来源：[crates/core/bamboo-domain/src/lib.rs:1-80](), [crates/core/bamboo-domain/src/ledger/mod.rs:1-60]()

### 基础设施层 (infra)

- **`bamboo-projects`**：项目绑定、归档/恢复（#725）、legacy dry-run（#728）、canonical_path 补全等逻辑实现层。其入口 `plan_legacy_migration` 位于 `crates/infra/bamboo-projects/src/lib.rs:1600`，`bind` 流程在 `lib.rs:542/644` 完成 canonicalize。

资料来源：[crates/infra/bamboo-projects/src/lib.rs:1600-1650](), [crates/infra/bamboo-projects/src/lib.rs:542-650]()

### HTTP 接入层 (routes/handlers)

`routes/agent.rs` 注册 `v1` 下的全部路由（`/v1/chat`、`/v1/execute`、`/v1/sessions`、`/v1/projects` 等），并把请求分派到对应 handler。`handlers/agent/projects.rs` 提供项目 CRUD 与 summary 聚合；`handlers/agent/sessions/types.rs` 定义会话请求/响应模型，是 `PATCH /v1/sessions/{id}`（#726）、`POST /v1/sessions/{id}/copy`（#732）以及 `Idempotency-Key` 支持（#733）落地的基础。

资料来源：[routes/agent.rs:151-220](), [handlers/agent/projects.rs:124-300](), [handlers/agent/sessions/types.rs:305-380]()

## 关键协作关系

| 调用方 | 被调用模块 | 典型用途 |
| --- | --- | --- |
| `routes/agent.rs` | `handlers/agent/*` | 路由分发 |
| `handlers/agent/projects.rs` | `bamboo-projects` | 项目 CRUD、归档/恢复、迁移 dry-run |
| `handlers/agent/sessions/*` | `bamboo-domain` (project/ledger) | 会话创建、workspace 切换、复制 |
| `handlers/agent/sessions/*` | `bamboo-domain::mcp_config` | MCP 运行时副作用绑定 |
| 所有 handler | `bamboo-domain::poison` | 并发写冲突检测 |

## 演进方向

围绕「配置域修订权威统一」(issue #738 / #737 / #736 / #735) 与「Provider 多实例化」(issue #730) 两条主线，`Src` 模块当前正处于 legacy `providers`/`provider` 双轨向 section envelope 单一权威过渡的阶段；后续将逐步把 `Config.provider`、`ProviderConfigs` 收敛为只读兼容 shim，并由 `/bamboo/settings/provider-instances` 接管运行时构造 substrate。

资料来源：[crates/core/bamboo-domain/src/lib.rs:1-120](), [crates/core/bamboo-domain/src/poison.rs:1-40]()

---

<a id='page-crates-core-bamboo-agent-core-src'></a>

## Src 模块

### 相关页面

相关主题：[Src 模块](#page-crates-core-bamboo-domain-src), [App 模块](#page-crates-app)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [crates/core/bamboo-agent-core/src/agent/error.rs](https://github.com/bigduu/Bamboo-agent/blob/main/crates/core/bamboo-agent-core/src/agent/error.rs)
- [crates/core/bamboo-agent-core/src/agent/events.rs](https://github.com/bigduu/Bamboo-agent/blob/main/crates/core/bamboo-agent-core/src/agent/events.rs)
- [crates/core/bamboo-agent-core/src/agent/hooks.rs](https://github.com/bigduu/Bamboo-agent/blob/main/crates/core/bamboo-agent-core/src/agent/hooks.rs)
- [crates/core/bamboo-agent-core/src/agent/mod.rs](https://github.com/bigduu/Bamboo-agent/blob/main/crates/core/bamboo-agent-core/src/agent/mod.rs)
- [crates/core/bamboo-agent-core/src/agent/types.rs](https://github.com/bigduu/Bamboo-agent/blob/main/crates/core/bamboo-agent-core/src/agent/types.rs)
- [crates/core/bamboo-agent-core/src/composition/context.rs](https://github.com/bigduu/Bamboo-agent/blob/main/crates/core/bamboo-agent-core/src/composition/context.rs)
- [crates/infra/bamboo-projects/src/lib.rs](https://github.com/bigduu/Bamboo-agent/blob/main/crates/infra/bamboo-projects/src/lib.rs)
- [handlers/agent/projects.rs](https://github.com/bigduu/Bamboo-agent/blob/main/handlers/agent/projects.rs)
- [handlers/agent/sessions/types.rs](https://github.com/bigduu/Bamboo-agent/blob/main/handlers/agent/sessions/types.rs)
- [routes/agent.rs](https://github.com/bigduu/Bamboo-agent/blob/main/routes/agent.rs)
</details>

# Src 模块

`Src 模块`指 Bamboo-agent 仓库在 Rust 工作区下的源码根（`src`）以及围绕它的 crate 拆分。本页概述整个 `src` 树在 Bamboo-agent 中承担的角色、关键子模块的边界，并指明近期社区变更（#597、#725–#738）对源码组织的实际影响。

## 模块定位与工作区拓扑

Bamboo-agent 采用 Cargo workspace，把"领域内核"与"基础设施 / HTTP 边界"分别放在独立 crate 中，使 server 二进制（`bamboo-server`）只承担组装与启动职责。

| 子树 | 角色 | 关键文件 |
| --- | --- | --- |
| `crates/core/bamboo-agent-core/src/agent` | LLM Agent 的纯领域逻辑（与具体 provider / 持久化解耦） | `mod.rs`、`types.rs`、`events.rs`、`hooks.rs`、`error.rs` |
| `crates/core/bamboo-agent-core/src/composition` | 跨切面上下文装配（运行时上下文、依赖注入句柄） | `context.rs` |
| `crates/infra/bamboo-projects/src` | Project / Binding / Legacy 迁移等"业务域"实现 | `lib.rs` |
| `handlers/agent` | 将 domain crate 暴露为 axum handler | `projects.rs`、`sessions/types.rs` 等 |
| `routes/agent.rs` | 路由聚合表，串联 handlers 与 middleware | — |

资料来源：[crates/core/bamboo-agent-core/src/agent/mod.rs]()

## Agent Core 子模块

`bamboo-agent-core` 是整个服务端的"无 I/O 内核"，把可被 HTTP 层直接复用的类型集中起来。

- `mod.rs`：声明 `agent` 子模块的公共表面（re-export），是其它 crate 引用 agent 能力的唯一入口。资料来源：[crates/core/bamboo-agent-core/src/agent/mod.rs]()
- `types.rs`：定义 agent 抽象的核心数据类型（消息、回合、工具调用载荷等），是与上层 handler 交换数据的稳定 schema。资料来源：[crates/core/bamboo-agent-core/src/agent/types.rs]()
- `events.rs`：枚举运行期产生的可观察事件，作为 SSE 流 / 审计日志的统一来源。资料来源：[crates/core/bamboo-agent-core/src/agent/events.rs]()
- `hooks.rs`：生命周期钩子（pre/post turn、工具调用前后），供上层在不改 agent 主流程的前提下注入行为。资料来源：[crates/core/bamboo-agent-core/src/agent/hooks.rs]()
- `error.rs`：领域错误类型，避免把 `anyhow` / `thiserror` 的具体错误直接泄露到 handler 层。资料来源：[crates/core/bamboo-agent-core/src/agent/error.rs]()

`composition/context.rs` 则在更高层把以上类型与"运行时上下文"绑定，让 handler 在不直接 new 出 agent 实现的前提下完成调用。资料来源：[crates/core/bamboo-agent-core/src/composition/context.rs]()

## Infra 层：Projects 与 Legacy 迁移

`crates/infra/bamboo-projects/src/lib.rs` 是 Project 域的核心实现，包含 binding 服务端 canonicalize 与 legacy 项目迁移规划两条主线。

- 服务端 canonicalize：项目与 git 仓库的绑定在 `bind` 时即被服务端规范化，记录到 `binding.path` 与 `binding.git_common_dir` 字段中。资料来源：[crates/infra/bamboo-projects/src/lib.rs:542-644]()
- Legacy 迁移规划：`plan_legacy_migration` 接收 `canonical_path`、`git_common_dir`、`legacy_project_keys` 等字段，与绑定表对齐，输出"可直接落库"的迁移计划。资料来源：[crates/infra/bamboo-projects/src/lib.rs:1600]()

近期 `#728` 已把对 `canonical_path` / `git_common_dir` / `legacy_project_keys` 的"服务端补全"纳入 dry-run，避免调用方在客户端手算造成不一致。

## HTTP 边界：Handlers 与 Routes

HTTP 层严格遵循"路由聚合 + 业务 handler + DTO 类型"的拆分：

- `routes/agent.rs`：注册所有 `/v1/...` 路由，项目相关路由集中在 `routes/agent.rs:151-154` 一带（含 archive、unarchive、migrations 等）。资料来源：[routes/agent.rs:151-154]()
- `handlers/agent/projects.rs`：`GET /v1/projects` 在 `handlers/agent/projects.rs:124` 返回完整 `ProjectManifest` 列表；`POST /v1/projects/:id/archive` 在 `handlers/agent/projects.rs:284` 执行归档。资料来源：[handlers/agent/projects.rs:124-284]()
- `handlers/agent/sessions/types.rs`：定义 `PatchSessionRequest` 等 DTO，目前仅支持 `project_id`，workspace 切换需要新增字段。资料来源：[handlers/agent/sessions/types.rs:305]()

`#725`、`#726`、`#727`、`#732` 都在该层追加端点或 DTO 字段，反映出 handlers / routes 是面向 Lotus 前端需求演进最快的层。

## 模块协作与近期演进

下图给出一次"调用 → 路由 → handler → domain → infra"的最短路径，标注了近期 issue 主要触及的节点。

```mermaid
flowchart LR
  Client[Lotus / 外部客户端] --> Routes[routes/agent.rs\n151-154 注册]
  Routes --> ProjH[handlers/agent/projects.rs\n124 列表 / 284 归档]
  Routes --> SessH[handlers/agent/sessions/types.rs\n305 PatchSessionRequest]
  ProjH --> ProjLib[crates/infra/bamboo-projects/src/lib.rs\n542/644 bind canonicalize\n1600 plan_legacy_migration]
  SessH --> CoreCtx[crates/core/bamboo-agent-core/src/composition/context.rs]
  CoreCtx --> AgentMod[agent/mod.rs re-export]
  AgentMod --> AgentTypes[agent/types.rs + events.rs + hooks.rs + error.rs]
```

围绕"模块化配置 facade（#597）"，社区近期把 `cluster-fabric`（#729）、`provider / MCP`（#736）、以及尚未收口的 credential-backed sections（#737、#738）统一到"section envelope revision"作为唯一权威，遗留 `Config.provider` / `Config.providers` 仅作为只读向后兼容 shim 保留（#730）。`#735` 还修复了"legacy 进程在 section 事务中重建 `config.json`"时的事件回放问题。这些修订最终都沉淀到 `src` 树的 handler 与 infra 层，使得整个 `Src 模块` 在不破坏外部路由的同时，把多 provider、多 section 的写入收敛到类型化 envelope 之下。

---

<a id='page-crates-app'></a>

## App 模块

### 相关页面

相关主题：[Src 模块](#page-crates-core-bamboo-agent-core-src)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [crates/app/bamboo-broker/ANALYSIS_core_routing.md](https://github.com/bigduu/Bamboo-agent/blob/main/crates/app/bamboo-broker/ANALYSIS_core_routing.md)
- [crates/app/bamboo-broker/Cargo.toml](https://github.com/bigduu/Bamboo-agent/blob/main/crates/app/bamboo-broker/Cargo.toml)
- [crates/app/bamboo-broker/src/ask.rs](https://github.com/bigduu/Bamboo-agent/blob/main/crates/app/bamboo-broker/src/ask.rs)
- [crates/app/bamboo-broker/src/bin/subagent_bus_demo.rs](https://github.com/bigduu/Bamboo-agent/blob/main/crates/app/bamboo-broker/src/bin/subagent_bus_demo.rs)
- [crates/app/bamboo-broker/src/child_link.rs](https://github.com/bigduu/Bamboo-agent/blob/main/crates/app/bamboo-broker/src/child_link.rs)
- [crates/app/bamboo-broker/src/client.rs](https://github.com/bigduu/Bamboo-agent/blob/main/crates/app/bamboo-broker/src/client.rs)
</details>

# App 模块

## 概述与作用域

`App 模块`是 Bamboo-agent 仓库 Cargo workspace 中以 `crates/app/` 为根的应用层（application layer）聚合。它将上层业务能力打包为可执行 crate，负责把基础设施工具箱（`crates/infra/`、`crates/core/` 等）连接为面向终端用户的运行时形态——例如 CLI 入口、子代理（subagent）调度总线、本地或跨进程的消息桥接，以及面向 Lotus 前端的后端服务装配点。

模块定位体现为：

- **可执行入口与二进制**：典型 crate 包含 `src/bin/` 子模块（例：`subagent_bus_demo.rs`），用于演示、冒烟测试以及复用同一依赖图的可执行子命令。
- **进程内多 subagent 协调**：`bamboo-broker` 充当 broker 角色，对外暴露 client API，对内通过 `child_link` 维护父子代理之间的链路（child link）。
- **跨 crate 路由与编排**：`ANALYSIS_core_routing.md` 作为该 crate 的设计/分析文档，沉淀了核心路由策略。

资料来源：[crates/app/bamboo-broker/ANALYSIS_core_routing.md:1-40]()

## bamboo-broker 核心组件

`bamboo-broker` 是 App 模块最具代表性的 crate，其内部按职责拆分为若干子模块：

| 子文件 | 主要职责 |
| --- | --- |
| `src/ask.rs` | 接收外部问题/任务请求（"ask"），并将其包装为可在代理间传递的消息载荷 |
| `src/client.rs` | 为其他进程或 crate 提供同步/异步 client 句柄，封装 broker 调用细节 |
| `src/child_link.rs` | 维护子代理链路（child link），包括父子引用、状态传播、生命周期 |
| `src/bin/subagent_bus_demo.rs` | 演示如何在同一进程内驱动多个 subagent 通过 broker 总线协作 |
| `Cargo.toml` | 声明 crate 依赖、对工作区其他 crate（infra、core）的引用以及二进制 target |

资料来源：[crates/app/bamboo-broker/Cargo.toml:1-40]()、[crates/app/bamboo-broker/src/ask.rs:1-40]()、[crates/app/bamboo-broker/src/client.rs:1-40]()、[crates/app/bamboo-broker/src/child_link.rs:1-40]()、[crates/app/bamboo-broker/src/bin/subagent_bus_demo.rs:1-40]()

## 子代理总线协作流程

下面以 `subagent_bus_demo` 为例，说明 App 层如何把 client、child_link 与 ask 三个抽象串联起来：

```mermaid
flowchart LR
  A[上层调用方] --> B[client.rs<br/>BrokerClient]
  B --> C[ask.rs<br/>AskPayload]
  C --> D[broker 总线调度]
  D --> E[child_link.rs<br/>子代理链路]
  E --> F[子代理执行]
  F -- 结果回传 --> D --> B --> A
```

流程要点：

1. 上层（CLI、二进制 demo、其他 crate）通过 `client.rs` 拿到 `BrokerClient`，统一发起 ask 请求。  
2. `ask.rs` 把用户意图序列化为结构化载荷，并附加路由/上下文元数据。  
3. broker 在跨进程或进程内派发任务时，依据 `child_link.rs` 维护的父子拓扑选择具体 subagent。  
4. subagent 执行完成后，结果沿同一条链路回写，使 client 拿到确定性的响应。

资料来源：[crates/app/bamboo-broker/src/bin/subagent_bus_demo.rs:1-60]()、[crates/app/bamboo-broker/src/client.rs:1-60]()、[crates/app/bamboo-broker/src/ask.rs:1-60]()、[crates/app/bamboo-broker/src/child_link.rs:1-60]()

## 与社区演进相关的注意点

`bamboo-broker` 作为 App 层入口，与近期社区讨论中频繁出现的几个方向密切相关：

- **多 provider 抽象**：issue #730 指出 legacy `Config.provider`/`providers` 仍是运行时构造 substrate；App 层的 provider 装配需要在 broker 调用链上正确选择 provider-instance，而非仅依赖 legacy 字段。  
- **配置世代（config generations）/ 修订权威**：issue #736/#735 强调 legacy provider/MCP 处理器对 config 的副作用必须绑定到 revisioned section 事件，broker 在派发 ask 时不应绕过这一代次边界。  
- **幂等性 / 复制 / 切换持久化**：issue #733/#732/#726 涉及的 chat/execute、session copy、PATCH workspace 等能力，最终都要在 App 层的 client 与子代理链路上落地——`client.rs` 作为统一入口，是注入 `Idempot-Key` 等横切关注点的合适位置。

资料来源：[crates/app/bamboo-broker/src/client.rs:1-40]()、[crates/app/bamboo-broker/ANALYSIS_core_routing.md:1-40]()

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：bigduu/Bamboo-agent

摘要：发现 36 个潜在踩坑项，其中 7 个为 high/blocking；最高优先级：安装坑 - 来源证据：[Refactor] provider 多实例化未完成：legacy `providers`/`provider` 仍是运行时构造 substrate，与 provider-instances 双轨并存。

## 1. 安装坑 · 来源证据：[Refactor] provider 多实例化未完成：legacy `providers`/`provider` 仍是运行时构造 substrate，与 provider-instances 双轨并存

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Refactor] provider 多实例化未完成：legacy `providers`/`provider` 仍是运行时构造 substrate，与 provider-instances 双轨并存
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/bigduu/Bamboo-agent/issues/730 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 能力坑 · 能力证据存在缺口

- 严重度：high
- 证据强度：source_linked
- 发现：Sandbox install result is missing.
- 对用户的影响：缺口未补前，Doramagic 不能把该能力当作可靠推荐卖点。
- 证据：evidence.evidence_gaps | https://github.com/bigduu/Bamboo-agent | Sandbox install result is missing.

## 3. 安全/权限坑 · 失败模式：security_permissions: [bamboo-server] test: isolate create-session workspace-provider fallback assertions

- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: [bamboo-server] test: isolate create-session workspace-provider fallback assertions
- 对用户的影响：Developers may expose sensitive permissions or credentials: [bamboo-server] test: isolate create-session workspace-provider fallback assertions
- 证据：failure_mode_cluster:github_issue | https://github.com/bigduu/Bamboo-agent/issues/717 | [bamboo-server] test: isolate create-session workspace-provider fallback assertions

## 4. 安全/权限坑 · 失败模式：security_permissions: [bamboo] feat: copy/duplicate session endpoint

- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: [bamboo] feat: copy/duplicate session endpoint
- 对用户的影响：Developers may expose sensitive permissions or credentials: [bamboo] feat: copy/duplicate session endpoint
- 证据：failure_mode_cluster:github_issue | https://github.com/bigduu/Bamboo-agent/issues/732 | [bamboo] feat: copy/duplicate session endpoint

## 5. 安全/权限坑 · 失败模式：security_permissions: [bamboo] fix: reconcile reappeared legacy config root through revisioned section events

- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: [bamboo] fix: reconcile reappeared legacy config root through revisioned section events
- 对用户的影响：Developers may expose sensitive permissions or credentials: [bamboo] fix: reconcile reappeared legacy config root through revisioned section events
- 证据：failure_mode_cluster:github_issue | https://github.com/bigduu/Bamboo-agent/issues/735 | [bamboo] fix: reconcile reappeared legacy config root through revisioned section events

## 6. 安全/权限坑 · 失败模式：security_permissions: [bamboo] fix: unify cluster-fabric mutation revision authority

- 严重度：high
- 证据强度：source_linked
- 发现：Developers should check this security_permissions risk before relying on the project: [bamboo] fix: unify cluster-fabric mutation revision authority
- 对用户的影响：Developers may expose sensitive permissions or credentials: [bamboo] fix: unify cluster-fabric mutation revision authority
- 证据：failure_mode_cluster:github_issue | https://github.com/bigduu/Bamboo-agent/issues/729 | [bamboo] fix: unify cluster-fabric mutation revision authority

## 7. 安全/权限坑 · 来源证据：[Bug][Tools] workflow_run top-level oneOf breaks Anthropic requests and empties OpenAI tool parameters

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug][Tools] workflow_run top-level oneOf breaks Anthropic requests and empties OpenAI tool parameters
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/bigduu/Bamboo-agent/issues/734 | 来源类型 github_issue 暴露的待验证使用条件。

## 8. 安装坑 · 依赖 Docker 环境

- 严重度：medium
- 证据强度：runtime_trace
- 发现：安装/运行入口包含 Docker 命令：docker compose up -d
- 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
- 复现命令：`docker compose up -d`
- 证据：identity.distribution | https://github.com/bigduu/Bamboo-agent | docker compose up -d

## 9. 安装坑 · 失败模式：installation: [bamboo] fix: bind legacy provider and MCP runtime effects to config generations

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: [bamboo] fix: bind legacy provider and MCP runtime effects to config generations
- 对用户的影响：Developers may fail before the first successful local run: [bamboo] fix: bind legacy provider and MCP runtime effects to config generations
- 证据：failure_mode_cluster:github_issue | https://github.com/bigduu/Bamboo-agent/issues/736 | [bamboo] fix: bind legacy provider and MCP runtime effects to config generations

## 10. 安装坑 · 安装命令尚未沙箱验证

- 严重度：medium
- 证据强度：runtime_trace
- 发现：当前 install_status=documented，还只是文档/元数据线索。
- 对用户的影响：命令可能缺步骤、过期或依赖本地环境，不能直接作为用户承诺。
- 复现命令：`docker compose up -d`
- 证据：downstream_validation.install_status | https://github.com/bigduu/Bamboo-agent | install_status=documented; command=docker compose up -d

## 11. 配置坑 · 失败模式：configuration: [Bug][Tools] workflow_run top-level oneOf breaks Anthropic requests and empties OpenAI tool p...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: [Bug][Tools] workflow_run top-level oneOf breaks Anthropic requests and empties OpenAI tool parameters
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [Bug][Tools] workflow_run top-level oneOf breaks Anthropic requests and empties OpenAI tool parameters
- 证据：failure_mode_cluster:github_issue | https://github.com/bigduu/Bamboo-agent/issues/734 | [Bug][Tools] workflow_run top-level oneOf breaks Anthropic requests and empties OpenAI tool parameters

## 12. 配置坑 · 失败模式：configuration: [Refactor] provider 多实例化未完成：legacy `providers`/`provider` 仍是运行时构造 substrate，与 provider-instan...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: [Refactor] provider 多实例化未完成：legacy `providers`/`provider` 仍是运行时构造 substrate，与 provider-instances 双轨并存
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [Refactor] provider 多实例化未完成：legacy `providers`/`provider` 仍是运行时构造 substrate，与 provider-instances 双轨并存
- 证据：failure_mode_cluster:github_issue | https://github.com/bigduu/Bamboo-agent/issues/730 | [Refactor] provider 多实例化未完成：legacy `providers`/`provider` 仍是运行时构造 substrate，与 provider-instances 双轨并存

## 13. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/bigduu/Bamboo-agent | README/documentation is current enough for a first validation pass.

## 14. 运行坑 · Quick Start 尚未实际跑通

- 严重度：medium
- 证据强度：source_linked
- 发现：quickstart_status=not_attempted。
- 对用户的影响：用户只能看到安装线索，不能确信 10 分钟内能形成最小可试路径。
- 证据：downstream_validation.quickstart_status | https://github.com/bigduu/Bamboo-agent | quickstart_status=not_attempted; sandbox_quickstart_status=missing

## 15. 维护坑 · 失败模式：migration: [bamboo] feat: legacy dry-run 在服务端补全 canonical_path / git_common_dir / legacy_project_keys

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: [bamboo] feat: legacy dry-run 在服务端补全 canonical_path / git_common_dir / legacy_project_keys
- 对用户的影响：Developers may hit a documented source-backed failure mode: [bamboo] feat: legacy dry-run 在服务端补全 canonical_path / git_common_dir / legacy_project_keys
- 证据：failure_mode_cluster:github_issue | https://github.com/bigduu/Bamboo-agent/issues/728 | [bamboo] feat: legacy dry-run 在服务端补全 canonical_path / git_common_dir / legacy_project_keys

## 16. 维护坑 · 来源证据：[bamboo] feat: legacy dry-run 在服务端补全 canonical_path / git_common_dir / legacy_project_keys

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[bamboo] feat: legacy dry-run 在服务端补全 canonical_path / git_common_dir / legacy_project_keys
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/bigduu/Bamboo-agent/issues/728 | 来源类型 github_issue 暴露的待验证使用条件。

## 17. 维护坑 · 来源证据：[bamboo] feat: persist session workspace switch via PATCH /v1/sessions/{id}

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[bamboo] feat: persist session workspace switch via PATCH /v1/sessions/{id}
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/bigduu/Bamboo-agent/issues/726 | 来源类型 github_issue 暴露的待验证使用条件。

## 18. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/bigduu/Bamboo-agent | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/bigduu/Bamboo-agent | no_demo; severity=medium

## 20. 安全/权限坑 · 存在安全注意事项

- 严重度：medium
- 证据强度：source_linked
- 发现：No sandbox install has been executed yet; downstream must verify before user use.
- 对用户的影响：用户安装前需要知道权限边界和敏感操作。
- 证据：risks.safety_notes | https://github.com/bigduu/Bamboo-agent | No sandbox install has been executed yet; downstream must verify before user use.

## 21. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/bigduu/Bamboo-agent | no_demo; severity=medium

## 22. 安全/权限坑 · 来源证据：[bamboo-server] test: isolate create-session workspace-provider fallback assertions

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[bamboo-server] test: isolate create-session workspace-provider fallback assertions
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/bigduu/Bamboo-agent/issues/717 | 来源类型 github_issue 暴露的待验证使用条件。

## 23. 安全/权限坑 · 来源证据：[bamboo] feat: copy/duplicate session endpoint

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[bamboo] feat: copy/duplicate session endpoint
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/bigduu/Bamboo-agent/issues/732 | 来源类型 github_issue 暴露的待验证使用条件。

## 24. 安全/权限坑 · 来源证据：[bamboo] fix: bind legacy provider and MCP runtime effects to config generations

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[bamboo] fix: bind legacy provider and MCP runtime effects to config generations
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/bigduu/Bamboo-agent/issues/736 | 来源类型 github_issue 暴露的待验证使用条件。

## 25. 安全/权限坑 · 来源证据：[bamboo] fix: reconcile reappeared legacy config root through revisioned section events

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[bamboo] fix: reconcile reappeared legacy config root through revisioned section events
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/bigduu/Bamboo-agent/issues/735 | 来源类型 github_issue 暴露的待验证使用条件。

## 26. 安全/权限坑 · 来源证据：[bamboo] fix: unify cluster-fabric mutation revision authority

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[bamboo] fix: unify cluster-fabric mutation revision authority
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/bigduu/Bamboo-agent/issues/729 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 27. 能力坑 · 失败模式：capability: [bamboo] feat: Project list 提供含 workspace_count/session_count 的 summary

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: [bamboo] feat: Project list 提供含 workspace_count/session_count 的 summary
- 对用户的影响：Developers may hit a documented source-backed failure mode: [bamboo] feat: Project list 提供含 workspace_count/session_count 的 summary
- 证据：failure_mode_cluster:github_issue | https://github.com/bigduu/Bamboo-agent/issues/727 | [bamboo] feat: Project list 提供含 workspace_count/session_count 的 summary

## 28. 能力坑 · 失败模式：capability: [bamboo] feat: add Project unarchive/restore endpoint

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: [bamboo] feat: add Project unarchive/restore endpoint
- 对用户的影响：Developers may hit a documented source-backed failure mode: [bamboo] feat: add Project unarchive/restore endpoint
- 证据：failure_mode_cluster:github_issue | https://github.com/bigduu/Bamboo-agent/issues/725 | [bamboo] feat: add Project unarchive/restore endpoint

## 29. 能力坑 · 失败模式：capability: [bamboo] feat: chat/execute 变更操作支持 Idempotency-Key 去重

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: [bamboo] feat: chat/execute 变更操作支持 Idempotency-Key 去重
- 对用户的影响：Developers may hit a documented source-backed failure mode: [bamboo] feat: chat/execute 变更操作支持 Idempotency-Key 去重
- 证据：failure_mode_cluster:github_issue | https://github.com/bigduu/Bamboo-agent/issues/733 | [bamboo] feat: chat/execute 变更操作支持 Idempotency-Key 去重

## 30. 能力坑 · 失败模式：capability: [bamboo] feat: persist session workspace switch via PATCH /v1/sessions/{id}

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: [bamboo] feat: persist session workspace switch via PATCH /v1/sessions/{id}
- 对用户的影响：Developers may hit a documented source-backed failure mode: [bamboo] feat: persist session workspace switch via PATCH /v1/sessions/{id}
- 证据：failure_mode_cluster:github_issue | https://github.com/bigduu/Bamboo-agent/issues/726 | [bamboo] feat: persist session workspace switch via PATCH /v1/sessions/{id}

## 31. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/bigduu/Bamboo-agent | issue_or_pr_quality=unknown

## 32. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/bigduu/Bamboo-agent | release_recency=unknown

## 33. 维护坑 · 失败模式：maintenance: Release v0.3.0

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: Release v0.3.0
- 对用户的影响：Upgrade or migration may change expected behavior: Release v0.3.0
- 证据：failure_mode_cluster:github_release | https://github.com/bigduu/Bamboo-agent/releases/tag/v0.3.0 | Release v0.3.0

## 34. 维护坑 · 失败模式：maintenance: Release v0.3.1

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: Release v0.3.1
- 对用户的影响：Upgrade or migration may change expected behavior: Release v0.3.1
- 证据：failure_mode_cluster:github_release | https://github.com/bigduu/Bamboo-agent/releases/tag/v0.3.1 | Release v0.3.1

## 35. 维护坑 · 失败模式：maintenance: Release v0.3.2

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: Release v0.3.2
- 对用户的影响：Upgrade or migration may change expected behavior: Release v0.3.2
- 证据：failure_mode_cluster:github_release | https://github.com/bigduu/Bamboo-agent/releases/tag/v0.3.2 | Release v0.3.2

## 36. 维护坑 · 失败模式：maintenance: Release v2026.3.3

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: Release v2026.3.3
- 对用户的影响：Upgrade or migration may change expected behavior: Release v2026.3.3
- 证据：failure_mode_cluster:github_release | https://github.com/bigduu/Bamboo-agent/releases/tag/v2026.3.3 | Release v2026.3.3

<!-- canonical_name: bigduu/Bamboo-agent; human_manual_source: deepwiki_human_wiki -->