Bamboo-agent 项目说明书

Doramagic 项目包 · 项目说明书

Bamboo-agent 项目

Bamboo 是一个本地优先的 AI Agent 框架与运行时，基于 Rust 开发。它支持持久化记忆、内置 22 个工具、技能、MCP、子智能体、工作流与定时任务，并通过统一的 HTTP + WebSocket API 提供服务，既可作为 crate 嵌入，也能作为独立服务器运行。

项目概览

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 前端与跨模块协调组件 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 系列修复持续收紧。

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)]

演进焦点与社区关注点

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

配置权威统一：将所有 credential-backed section 的写路径收敛到 typed section envelope revision（#737、#738），并在 cluster-fabric 上已落地的 #729 经验推广到 provider/MCP（#735、#736）。
Provider 多实例化收尾：清理 Config.provider / Config.providers 这条遗留构造 substrate（#730），让 provider-instances 成为唯一运行时入口。
前端协作能力补齐：包括 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

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

Src 模块

Src 模块是 Bamboo-agent 项目的核心源代码根目录，采用 Cargo workspace 多 crate 架构组织 Rust 源码。整个仓库围绕「领域建模 + 基础设施分层 + HTTP 接口」三条主线展开，分别对应 crates/core/bamboo-domain、crates/infra/ 以及根目录的 routes/handlers 等模块。该模块承担...

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 领域核心 (bamboo-domain)

继续阅读本节完整说明和来源证据。

章节 基础设施层 (infra)

继续阅读本节完整说明和来源证据。

章节 HTTP 接入层 (routes/handlers)

继续阅读本节完整说明和来源证据。

概述

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

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

App 模块

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

章节 相关页面

继续阅读本节完整说明和来源证据。

概述与作用域

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 三个抽象串联起来：

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

流程要点：

上层（CLI、二进制 demo、其他 crate）通过 client.rs 拿到 BrokerClient，统一发起 ask 请求。
ask.rs 把用户意图序列化为结构化载荷，并附加路由/上下文元数据。
broker 在跨进程或进程内派发任务时，依据 child_link.rs 维护的父子拓扑选择具体 subagent。
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

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

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

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

可能增加新用户试用和生产接入成本。

high 能力证据存在缺口

缺口未补前，Doramagic 不能把该能力当作可靠推荐卖点。

high 失败模式：security_permissions: [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

high 失败模式：security_permissions: [bamboo] feat: copy/duplicate session endpoint

Developers may expose sensitive permissions or credentials: [bamboo] feat: copy/duplicate session endpoint

Pitfall Log / 踩坑日志

项目：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

来源：Doramagic 发现、验证与编译记录