xinyin025/LangBot
1
0
Fork 0
mirror of https://github.com/langbot-app/LangBot.git synced 2026-09-08 10:37:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

refactor(skill): compose generic box mounts in core

Browse Source
This commit is contained in:
huanghuoguoguo
2026-09-05 23:09:46 +08:00
parent c15f668126
commit a61b0f0068
22 changed files with 476 additions and 565 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/review/box-architecture.md
+24 -21
View File
@@ -22,6 +22,7 @@
│ │ │ (shared 容器, 多 process) │
│ │ │ │
│ │ ├──> SkillToolLoader (activate 工具) │
│ │ │ └─ build_execution_mounts() │
│ │ │ │
│ │ ├──> SkillAuthoringToolLoader │
│ │ │ │
@@ -33,7 +34,7 @@
│ ├─ Workspace quota 检查 │
│ ├─ 输出截断 (head+tail) │
│ ├─ Session ID 模板解析 (resolve_box_session_id) │
│ ├─ 技能挂载组装 (build_skill_extra_mounts) │
│ ├─ 通用只读挂载接收 (read_only_mounts) │
│ ├─ 重连循环 (_reconnect_loop, 指数退避) │
│ └─ BoxRuntimeConnector │
│ ├─ 心跳 loop (20s ping) │
@@ -59,10 +60,8 @@
│ NsjailBackend ──┘ (本地 CLI 或 fallback 到容器内 CLI) │
│ E2BBackend (云沙箱, 需要 E2B_API_KEY) │
│ │
│ BoxSkillStore │
│ ├─ list / get / create / update / delete │
│ ├─ scan_skill_directory / read_skill_file / write_skill_file │
│ └─ preview_skill_zip / install_skill_zip (zip 或 GitHub) │
│ Generic mount admission │
│ └─ allow-list + read-only + normalized target validation │
│ │
│ aiohttp 单端口服务 (默认 :5410): │
│ /rpc/ws — Action RPC │
@@ -85,7 +84,7 @@
**核心设计原则**:
- Box Runtime 作为独立进程运行，通过 Action RPC 与 LangBot 主进程通信，两者复用 SDK 的 IO 层（Handler → Connection → Controller）
- 一个 session_id 对应一个容器/沙箱实例。同一 session 内可并存多条 mount 与多个 managed process
- Skill / 默认 exec / MCP Server 共享同一个 session 容器（详见 [box-session-scope.md](./box-session-scope.md)）
- Skill 仅是 Core 组装 mount 的业务来源；Box 与默认 exec / MCP Server 只共享通用 session 和 mount 机制（详见 [box-session-scope.md](./box-session-scope.md)）
---
@@ -93,7 +92,7 @@
### 2.1 BoxService (`pkg/box/service.py`, 722 行)
应用层门面，协调 Profile、安全校验、配额、连接、Skill 挂载与 Session 模板：
应用层门面，协调 Profile、安全校验、配额、连接、Core 生成的只读挂载与 Session 模板：
主要公开方法（按定义顺序）：
@@ -105,7 +104,7 @@ BoxService
├─ available (property) 连接状态
│
├─ resolve_box_session_id(query) 从 pipeline 模板解析 session_id
├─ build_skill_extra_mounts(query) 组装 pipeline-bound skill 的挂载列表
├─ execute_tool(..., read_only_mounts=...) 接收 Core 组装的通用只读挂载
│
├─ execute_tool(parameters, query) Agent 调用 exec 时的入口
│ ├─ _apply_profile / build_spec
@@ -122,12 +121,6 @@ BoxService
├─ stop_managed_process(session_id, pid) 单独停止某个 managed process
├─ get_managed_process_websocket_url(...) 返回 WS attach URL
│
├─ list_skills() / get_skill(name) Skill 元数据
├─ create_skill / update_skill / delete_skill Skill CRUD
├─ scan_skill_directory(path) 扫描目录
├─ list_skill_files / read_skill_file / write_skill_file
├─ preview_skill_zip / install_skill_zip zip / GitHub 安装
│
├─ shutdown() / dispose() 清理：RPC SHUTDOWN + 进程终止
├─ get_status() / get_sessions() / get_recent_errors()
└─ get_system_guidance() LLM 系统提示
@@ -137,7 +130,7 @@ BoxService
**输出截断**: 默认 4000 字符上限，保留前 60% + 后 40%，中间插入 `[...truncated...]`。
**Skill 挂载合并**: `execute_tool()` 调用时，`build_skill_extra_mounts(query)` 会把当前 pipeline-bound 的所有 skill 的 `package_root` 作为 `extra_mounts` 加入 BoxSpec，挂在 `/workspace/.skills/<name>`。LLM 通过 `activate` 工具显式激活某个 skill 后，工具调用才允许引用这个 skill 的虚拟路径。
**Skill 挂载合并**: native loader 调用 `skill.build_execution_mounts()`，把当前 pipeline-bound 的所有 skill 的 `package_root` 转成普通只读 mount，再通过 `BoxService.execute_tool(..., read_only_mounts=...)` 交给 Box，挂在 `/workspace/.skills/<name>`。LLM 通过 `activate` 工具显式激活某个 skill 后，工具调用才允许引用这个 skill 的虚拟路径；BoxService 和 Box Runtime 都不知道这些 mount 来自 Skill。
### 2.2 BoxRuntimeConnector (`pkg/box/connector.py`, 357 行)
@@ -294,7 +287,7 @@ start_managed_process(session, spec):
单端口 aiohttp 服务（默认 5410），通过路径区分（commit `8c71ec5` 合并端口）：
1. **Action RPC** (`/rpc/ws`): `BoxServerHandler` 处理所有 action，包括 `INIT` 配置注入、skill store 操作等
1. **Action RPC** (`/rpc/ws`): `BoxServerHandler` 处理 `INIT`、exec、session、managed-process 与状态等通用 action
2. **WS Relay** (`/v1/sessions/{id}/managed-process/ws` 与 `/v1/sessions/{id}/managed-process/{pid}/ws`): 双向桥接 WebSocket ↔ 指定 managed process stdin/stdout
stdio 模式同样会在 5410 启动 aiohttp，专门承担 managed process attach；Action RPC 走 stdin/stdout。
@@ -303,7 +296,7 @@ stdio 模式同样会在 5410 启动 aiohttp，专门承担 managed process atta
`ActionRPCBoxClient` 封装 `Handler.call_action()` 调用：
- 25+ 方法对应 25+ 个 RPC action（exec / session / managed-process / skill / status / shutdown）
- 方法对应 exec / session / managed-process / status / shutdown 等通用 RPC action，不暴露 Skill CRUD
- 错误还原: `_translate_action_error()` 通过字符串前缀匹配还原 SDK 侧异常类型
- `execute()` timeout = 300s，其他默认 15s
- `BoxRuntimeClient` 是 ABC，供后续可能的非 RPC 实现复用
@@ -344,7 +337,7 @@ stdio 模式同样会在 5410 启动 aiohttp，专门承担 managed process atta
### 3.7 SkillStore (`langbot_plugin.skill_store`)
Skill 包存储最初位于 Box Runtime；issue #2410 将通用实现抽到 Plugin SDK 顶层，Core 与 Box 使用同一套存储和 revision 语义：
Skill 包存储最初位于 Box Runtime；issue #2410 将通用实现抽到 Plugin SDK 顶层，由 Core 独占存储和 revision 语义：
```
SkillStore
@@ -359,7 +352,15 @@ SkillStore
└─ 支持 source_subdir / target_suffix（commit 1aa043f）
```
`langbot_plugin.box.skill_store.BoxSkillStore` 仅保留为旧 Box 配置到通用 `SkillStore` 的兼容适配器，不再拥有存储实现。GitHub 安装路径由 Core HTTP 层下载归档，再交给 SkillRepository。Skill 文件继续存放于 `box.local.skills_root`（默认 `skills`，相对 `host_root`），执行时只读挂载到 `/workspace/.skills/`。
GitHub 安装路径由 Core HTTP 层下载归档，再交给 SkillRepository。Skill 文件位于独立的 `skills.root`，执行时由 Core 组装成通用只读 `BoxMountSpec` 并挂载到 `/workspace/.skills/`。Box 的正常模型、客户端和 Runtime 不包含 `skill_name`、Skill CRUD、revision 或 `SKILL.md` 语义。
滚动升级只保留一个隔离桥：`box/legacy_skill_compat.py` 让旧 Core 暂时调用新 Box，并把旧 `skill_name` 转为普通只读 mount。部署顺序必须先升级 Box、再升级 Core。该模块有 `TODO(next-major)`，下一大版本删除；正常架构不依赖它。
下一大版本的删除清单（当前均有 `TODO(next-major)`）：
1. 删除 SDK `box/legacy_skill_compat.py` 及 Server 中唯一的注册/转换钩子。
2. 删除 Core 对 `box.local.skills_root` 的配置 fallback。
3. 新安装默认从历史 `./data/box/skills` 切到 `./data/skills`；届时 Box 部署只需只读访问 Core 明确下发的通用 artifact root。
### 3.8 Security (`box/security.py`, 52 行)
@@ -504,6 +505,9 @@ Box 额外做了 RPC SHUTDOWN 通知 Runtime 主动清理容器，比 Plugin 的
### config.yaml (重构后)
```yaml
skills:
root: './data/box/skills' # Core-owned；Box 关闭时仍可管理/读取
box:
enabled: true # 整个 Box 子系统的总开关。设为 false 时：
# - 不连接远程 Box runtime，不 fork 本地 stdio 子进程
@@ -522,7 +526,6 @@ box:
image: '' # 覆盖 profile 默认 image
host_root: './data/box' # 工作区挂载根，Docker 部署需绝对路径
default_workspace: '' # 默认 '<host_root>/default'
skills_root: 'skills' # Core 管理且与 Box 共享的 skill 包目录
allowed_mount_roots: # 默认 ['<host_root>']
- './data/box'
- '/tmp'
@@ -571,7 +574,7 @@ volumes:
| Pipeline 扩展页 `enable_all_skills` / 绑定 skill | 可编辑 | 可编辑 |
| 仪表盘 Box 状态卡片 | 绿点 / "已连接" | 灰点 / "已禁用"(disabled) 或 红点 / "已断开"(failed) |
> Core 的 SkillRepository 是 `langbot_plugin.skill_store.SkillStore` 的异步 Workspace 适配层，保持原 `data/box/skills/tenants/...` 布局，升级时无需移动已安装 Skill。Box 只在执行发生时消费同一份只读 package revision。
> Core 的 SkillRepository 是 `langbot_plugin.skill_store.SkillStore` 的异步 Workspace 适配层。默认 `skills.root` 保持原 `data/box/skills/tenants/...` 布局，升级时无需移动已安装 Skill；旧 `box.local.skills_root` 仅作为在线升级 fallback，并将在下一大版本删除。Box 只消费 Core 下发的通用只读 mount。
### Pipeline 配置 (templates/metadata/pipeline/ai.yaml)
docs/review/box-issues.md
+2 -2
View File
@@ -52,8 +52,8 @@
### S5. 挂载校验缺口 — Med-High
- **位置**: SDK `box/security.py` `_BLOCKED_HOST_PATHS_POSIX`；`box/backend.py` 的 `extra_mounts` 处理
- **现状**: ① SDK 黑名单仍不含 `/`（前缀匹配，`host_path="/"` 可通过，挂载整个宿主 fs）；用户 home、`/usr`、`/opt`、`/tmp` 也未拦截。② `validate_sandbox_security` 只校验 `spec.host_path`，**从不遍历 `spec.extra_mounts`**——LangBot 侧 `allowed_mount_roots` 也只校验 `host_path`。当前 `extra_mounts` 仅由 `build_skill_extra_mounts` 内部填充（agent 不可达），但缺乏纵深防御：一旦 S1 的无认证 RPC 被触达，extra_mounts 可挂任意宿主路径，两层都不拦。
- **要求**: SDK 黑名单加入 `/`（或改白名单）；`extra_mounts` 在 SDK 与 LangBot 两侧都纳入挂载校验。
- **现状**: grant-enforced 模式已经由 Core 与 Runtime 双重校验通用只读 mount（绝对路径 allow-list、存在性、只读模式、规范化且位于 `/workspace` 下的目标）；它不再有 Skill 特例。遗留风险仅在 admission-disabled 的低信任直连场景：通用 `extra_mounts` 仍未统一套用 grant-enforced 白名单。
- **要求**: admission-disabled 的外部控制面也复用同一套通用 mount 校验；SDK 黑名单加入 `/`（或全面改白名单）。
### S6. 容器加固缺失 — Med
docs/review/box-session-scope.md
+1 -1
View File
@@ -18,7 +18,7 @@ has shipped the design largely as written:
| Docker / nsjail / E2B backends apply extra mounts | ✅ Shipped | Last gap closed by SDK commit `0fea9b1` (E2B) |
| `box-session-id-template` in `local-agent` pipeline config | ✅ Shipped | `templates/metadata/pipeline/ai.yaml`, default `{launcher_type}_{launcher_id}` |
| `BoxService.resolve_box_session_id(query)` | ✅ Shipped | `pkg/box/service.py:166` |
| `BoxService.build_skill_extra_mounts(query)` | ✅ Shipped | `pkg/box/service.py:189` |
| `skill.build_execution_mounts(ap, query)` | ✅ Shipped | Core composes read-only packages; Box receives generic mounts |
| Skill exec uses unified container + extra mounts | ✅ Shipped | `pkg/provider/tools/loaders/native.py` skill branch |
| MCP-in-Box uses shared persistent session, multi-process | ✅ Shipped (earlier than originally scoped) | SDK commit `529088e`, LangBot `mcp_stdio.py:_build_box_session_id` |
| `BoxManagedProcessSpec.process_id` + multi-process per session | ✅ Shipped | `BoxRuntime` keeps `managed_processes: dict[pid, _ManagedProcess]` |
docs/review/box-test-coverage.md
+1 -1
View File
@@ -51,7 +51,7 @@
| BoxService workspace quota | 优秀 | 前置/后置配额检查、超额清理 |
| BoxService 输出截断 | 优秀 | 短/精确边界/长输出、独立 stderr |
| BoxService 可观测性 | 优秀 | 状态报告、error ring buffer、buffer 上限 |
| BoxService session 模板 | 良好 | `resolve_box_session_id` + `build_skill_extra_mounts` 在 service / native / mcp 三处都有覆盖 |
| BoxService session / mount contract | 良好 | `resolve_box_session_id` + generic `read_only_mounts`; Skill mount composition is covered in the Core loader |
| RPC client/server 协议 | 优秀 | execute/get_sessions/delete/create/conflict error |
| BoxRuntimeConnector | 良好 | local/remote 模式、Docker 平台、relay URL、心跳与重连回调 |
| BoxWorkspaceSession | 良好 | payload 构建、managed process 路径重写、stage host file |