Deepractice生态深度解析：CommonX、ResourceX、SandboX——AI Agent的三大基础设施支柱

**导语**：在前面的文章中，我们介绍了Deepractice生态的PromptX、AgentX、AgentVM等面向用户的产品。今天我们来深挖支撑这一切的基础设施层——CommonX、ResourceX、SandboX。它们分别是：跨运行时工具库、AI资源包管理器、多语言安全沙箱。这三个项目构成了Deepractice生态的"地基"，让上层应用能够稳定、安全、高效地运行。 --- ## 一、Deepractice生态全景回顾 ### 生态分层架构 ``` ┌─────────────────────────────────────────┐ │ 应用层（用户直接接触） │ │ PromptX（角色平台） │ │ AgentX（Agent框架） │ │ AgentVM（Agent虚拟机） │ ├─────────────────────────────────────────┤ │ 基础设施层（本文重点） │ │ CommonX（跨运行时工具库） │ │ ResourceX（AI资源包管理器） │ │ SandboX（多语言安全沙箱） │ ├─────────────────────────────────────────┤ │ 协议层 │ │ MCP（Model Context Protocol） │ │ DARP（Deepractice Agent Runtime Protocol）│ ├─────────────────────────────────────────┤ │ 模型层 │ │ Claude / GPT / 其他LLM │ └─────────────────────────────────────────┘ ``` **关键洞察**：基础设施层的三个项目解决了AI应用开发的三个核心问题——**代码复用**（CommonX）、**资源管理**（ResourceX）、**安全执行**（SandboX）。 --- ## 二、CommonX：跨运行时工具库 ### 一句话定位 **Bun和Node.js的"通用标准库"**——让代码在两个运行时之间无缝迁移。 ### 为什么需要CommonX？ | 问题 | 传统方案 | CommonX方案 | |------|---------|------------| | Bun和Node.js API不兼容 | 写两套代码 | **统一抽象层** | | SQLite实现不同 | `bun:sqlite` vs `node:sqlite` | **统一接口** | | 路径处理差异 | 手动判断运行时 | **跨运行时path工具** | | 日志系统不统一 | 各自实现 | **懒初始化Logger** | ### 核心模块 #### 1. Logger（懒初始化日志） ```typescript import { createLogger } from "commonxjs/logger"; const logger = createLogger("my-app"); logger.info("Hello, world!"); logger.debug("Debug message", { userId: "123" }); ``` **特点**： - 懒初始化，按需加载 - 可插拔后端（console、file、remote） - 结构化日志输出 #### 2. SQLite（统一数据库接口） ```typescript import { openDatabase } from "commonxjs/sqlite"; // 同一套代码，Bun和Node.js都可用 const db = openDatabase("./data/app.db"); db.exec("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)"); const stmt = db.prepare("INSERT INTO users (name) VALUES (?)"); stmt.run("Alice"); const users = db.prepare("SELECT * FROM users").all(); db.close(); ``` **运行时适配**： - Bun → 使用 `bun:sqlite`（原生，高性能） - Node.js 22+ → 使用 `node:sqlite`（实验性API） #### 3. Path（跨运行时路径工具） ```typescript import { getModuleDir, getPackageRoot, getMonorepoRoot } from "commonxjs/path"; // 获取当前模块目录（__dirname的跨运行时替代） const __dirname = getModuleDir(import.meta); // 获取package.json所在目录 const pkgRoot = getPackageRoot(import.meta); // 获取monorepo根目录 const monoRoot = getMonorepoRoot(import.meta); ``` #### 4. ID（ID生成工具） ```typescript import { generateId, generateRequestId } from "commonxjs/id"; const msgId = generateId("msg"); // => "msg_1704067200000_a1b2c3" const reqId = generateRequestId(); // => "req_1704067200000_x7y8z9" ``` ### 在Deepractice生态中的作用 | 项目 | 如何使用CommonX | |------|----------------| | AgentX | SQLite持久化、日志、路径处理 | | AgentVM | ID生成、跨运行时兼容 | | ResourceX | 日志、路径工具 | | SandboX | 底层依赖 | --- ## 三、ResourceX：AI资源的"npm" ### 一句话定位 **AI资源的包管理器**——像管理npm包一样管理prompts、tools、agents。 ### 核心问题：AI资源的混乱现状 ``` 传统方式： ├── prompts/ │ ├── code-review.txt # 不知道版本 │ ├── code-review-v2.txt # 手动命名 │ └── code-review-final.txt # 最终版？ ├── tools/ │ └── （散落在各处代码中） └── agents/ └── （配置在Notion里，找不到了） ``` **ResourceX的解决方案**： ``` ResourceX方式： ├── code-review@1.0.0 # 版本化 ├── code-review@1.1.0 # 语义化版本 └── my-agent@2.0.0-beta # 预发布版本 ``` ### 核心概念 #### 1. Resource（资源） ```json // resource.json { "name": "code-review", "type": "text", "tag": "1.0.0", "description": "代码审查专家prompt" } ``` **支持类型**： - `text` - 文本prompt - `tool` - 工具定义 - `agent` - Agent配置 - 可扩展自定义类型 #### 2. Locator（定位符） ``` code-review:1.0.0 # 精确版本 code-review:latest # 最新版本 code-review:^1.0.0 # 兼容版本 @scope/package:1.0.0 # 命名空间 ``` #### 3. Registry（注册中心） - 本地注册表：~/.resourcex/ - 远程注册表：可自托管 - 类似npm的发布/拉取机制 ### 快速开始 #### 配置MCP ```json { "mcpServers": { "resourcex": { "command": "npx", "args": ["@resourcexjs/mcp-server"] } } } ``` #### 在Claude中使用 ``` 你：搜索代码审查资源 Claude：找到以下资源... - code-review:1.0.0 - code-review:1.1.0 - advanced-review:2.0.0 你：使用code-review:1.0.0审查这段代码 Claude：使用code-review:1.0.0资源进行审查... ``` ### CLI工具 ```bash # 安装 npm install -g @resourcexjs/cli # 常用命令 rx add ./my-prompt # 添加本地资源 rx list # 列出所有资源 rx use name:1.0.0 # 使用资源 rx search keyword # 搜索资源 rx push name:1.0.0 # 发布到注册表 rx pull name:1.0.0 # 从注册表拉取 ``` ### SDK使用 ```typescript import { createResourceX, setProvider } from "resourcexjs"; import { NodeProvider } from "@resourcexjs/node-provider"; setProvider(new NodeProvider()); const rx = createResourceX(); // 添加资源 await rx.add("./my-prompt"); // 解析资源 const result = await rx.resolve("my-prompt:1.0.0"); const content = await result.execute(); // 搜索 const results = await rx.search("code review"); ``` ### 自托管注册表 ```typescript import { createRegistryServer } from "@resourcexjs/server"; import { FileSystemRXAStore, FileSystemRXMStore } from "@resourcexjs/node-provider"; const app = createRegistryServer({ rxaStore: new FileSystemRXAStore("./data/blobs"), rxmStore: new FileSystemRXMStore("./data/manifests"), }); export default app; // 可部署到任何支持Hono的平台 ``` ### 与PromptX的关系 ``` PromptX角色 → ResourceX资源 → 版本化管理 ↓ ↓ 女娲创建 鲁班集成工具 ↓ ↓ 发布到 从注册表 ResourceX 拉取使用 ``` --- ## 四、SandboX：多语言安全执行沙箱 ### 一句话定位 **AI Agent的"操作系统"**——统一API支持多种隔离策略，从开发到生产无缝切换。 ### 核心问题：Agent执行代码的安全困境 | 场景 | 需求 | 传统方案 | |------|------|---------| | 开发调试 | 快速迭代 | `child_process.exec`（无隔离） | | 本地测试 | 安全隔离 | Docker（重、慢） | | 生产部署 | 强隔离 | 云服务（贵、复杂） | | 边缘执行 | 低延迟 | 难以实现 | **SandboX的解决方案**：统一API，多种隔离策略 ```typescript import { createSandbox } from "sandboxxjs"; // 开发：无隔离，最快 const dev = createSandbox({ isolator: "none", runtime: "node" }); // 本地安全测试：OS级隔离 const secure = createSandbox({ isolator: "srt", runtime: "node" }); // 生产：容器隔离 const prod = createSandbox({ isolator: "cloudflare", runtime: "node" }); // 同一代码，不同隔离级别 await dev.execute("console.log('Hello')"); await secure.execute("console.log('Hello')"); await prod.execute("console.log('Hello')"); ``` ### 核心特性 #### 1. 多语言支持 ```typescript // Node.js const nodeSandbox = createSandbox({ isolator: "none", runtime: "node" }); await nodeSandbox.execute("console.log(process.version)"); // Python const pythonSandbox = createSandbox({ isolator: "none", runtime: "python" }); await pythonSandbox.execute("import sys; print(sys.version)"); // Shell命令（所有运行时通用） await nodeSandbox.shell("echo $SHELL"); await pythonSandbox.shell("ls -la"); ``` #### 2. 状态层（State Layer） ```typescript const sandbox = createSandbox({ isolator: "none", runtime: "node" }); // 文件系统 await sandbox.fs.write("/app/data.json", '{"key": "value"}'); const content = await sandbox.fs.read("/app/data.json"); const files = await sandbox.fs.list("/app"); // 环境变量 sandbox.env.set("NODE_ENV", "production"); const env = sandbox.env.get("NODE_ENV"); // Key-value存储 sandbox.storage.setItem("token", "abc123"); const token = sandbox.storage.getItem("token"); ``` #### 3. 状态记录与回放（Binlog模式） ```typescript // 启用记录 const sandbox = createSandbox({ isolator: "none", runtime: "node", state: { enableRecord: true }, }); // 操作自动记录 await sandbox.fs.write("config.json", "{}"); sandbox.env.set("DEBUG", "true"); // 获取记录日志 const log = sandbox.getStateLog(); console.log(log.toJSON()); // [ // { op: "fs.write", args: { path: "config.json", data: "{}" } }, // { op: "env.set", args: { key: "DEBUG", value: "true" } } // ] ``` #### 4. 状态持久化（AOF模式） ```typescript // 自动持久化到磁盘 const sandbox = createSandbox({ isolator: "none", runtime: "node", state: { enableRecord: true }, // 自动持久化 }); console.log(sandbox.id); // "sandbox-V1StGXR8_Z5jdHi" // 操作自动追加到： // ~/.agentvm/sandbox/state-logs/sandbox-V1StGXR8_Z5jdHi.jsonl ``` ### 隔离策略对比 | Isolator | 状态 | 隔离级别 | 启动时间 | 适用场景 | |----------|------|---------|---------|---------| | **none** | ✅ | 无 | ~10ms | 开发调试 | | **srt** | ✅ | OS级 | ~50ms | 安全本地开发 | | **cloudflare** | ✅ | 容器 | ~100ms | 本地+边缘部署 | | **e2b** | 🚧 | MicroVM | ~150ms | 生产环境（规划中） | ### 架构设计 ``` createSandbox({ isolator, runtime, state }) │ ┌────┴────┐ ▼ ▼ ┌────────┐ ┌──────────┐ │ Node.js│ │ Python │ │Sandbox │ │ Sandbox │ └────┬───┘ └────┬─────┘ │ │ └────┬─────┘ ▼ ┌─────────────┐ │ State Layer │ │ - fs │ │ - env │ │ - storage │ └──────┬──────┘ ▼ ┌─────────────────┐ │ Isolator Layer │ ├────────┬────────┤ │ Local │ Cloud │ │(process)│(container)│ └────────┴────────┘ ``` ### 在Deepractice生态中的作用 | 项目 | 如何使用SandboX | |------|----------------| | AgentX | 执行用户代码、工具调用 | | AgentVM | 作为底层执行环境 | | PromptX | 鲁班集成外部工具时的安全执行 | --- ## 五、三个项目的协同关系 ### 数据流示例：Agent执行用户代码 ``` 用户输入代码 ↓ AgentX接收请求 ↓ SandboX创建安全沙箱 ↓ CommonX提供跨运行时工具 ↓ ResourceX加载所需资源（工具/prompt） ↓ 在沙箱中执行代码 ↓ SandboX记录状态变化 ↓ 返回结果给用户 ``` ### 依赖关系 ``` SandboX ├── CommonX（基础工具） └── ResourceX（资源加载） AgentX ├── SandboX（代码执行） ├── CommonX（工具） └── ResourceX（资源管理） AgentVM └── SandboX（底层运行时） PromptX └── ResourceX（角色资源管理） ``` --- ## 六、与业界方案的对比 ### CommonX vs 其他工具库 | 方案 | 定位 | 跨运行时 | Bun支持 | |------|------|---------|---------| | **CommonX** | AI基础设施 | ✅ 专门设计 | ✅ 原生 | | lodash | 通用工具 | ❌ | ⚠️ 需适配 | | zx | Shell工具 | ❌ Node only | ⚠️ | ### ResourceX vs 其他资源管理 | 方案 | 类型 | 版本控制 | MCP集成 | 自托管 | |------|------|---------|---------|--------| | **ResourceX** | 包管理器 | ✅ 语义化 | ✅ 原生 | ✅ | | LangChain Hub | 平台 | ⚠️ 有限 | ❌ | ❌ | | Hugging Face | 模型仓库 | ✅ | ❌ | ❌ | | 自建Git | 代码 | ✅ | ❌ | ✅ | ### SandboX vs 其他沙箱 | 方案 | 多语言 | 多隔离策略 | 状态持久化 | AI优化 | |------|--------|-----------|-----------|--------| | **SandboX** | ✅ | ✅ 4种 | ✅ Binlog | ✅ | | E2B | ✅ | ❌ MicroVM | ⚠️ | ✅ | | Docker | ⚠️ | ✅ 容器 | ❌ | ❌ | | WebContainers | ❌ Web | ❌ 浏览器 | ❌ | ❌ | --- ## 七、开发者如何参与 ### 使用场景建议 | 场景 | 推荐项目 | 原因 | |------|---------|------| | 开发Bun/Node.js应用 | CommonX | 跨运行时兼容 | | 管理AI prompts/tools | ResourceX | 版本化、可复用 | | 执行不可信代码 | SandboX | 安全隔离 | | 构建AI应用 | 全套 | 完整生态 | ### 贡献方式 ``` GitHub组织：Deepractice ├── CommonX - MIT License ├── ResourceX - Apache-2.0 License └── SandboX - MIT License ``` --- ## 八、总结：基础设施决定生态高度 Deepractice的三个基础设施项目，分别解决了AI应用开发的三个根本问题： | 项目 | 解决的问题 | 核心价值 | |------|-----------|---------| | **CommonX** | 运行时兼容性 | 一次编写，Bun/Node.js通吃 | | **ResourceX** | 资源管理混乱 | AI资源的"npm"，版本化、可复用 | | **SandboX** | 代码执行安全 | 从开发到生产，统一API，分级隔离 | **一句话总结**： > 如果说PromptX、AgentX是Deepractice生态的"面子"，那么CommonX、ResourceX、SandboX就是"里子"——没有扎实的基础设施，上层应用只能是空中楼阁。 这三个项目的开源，也体现了Deepractice的开放态度：**不仅做产品，更做基础设施；不仅自己用，更让整个社区受益**。 --- ## 参考资源 | 项目 | GitHub | npm | 协议 | |------|--------|-----|------| | CommonX | github.com/Deepractice/CommonX | commonxjs | MIT | | ResourceX | github.com/Deepractice/ResourceX | resourcexjs | Apache-2.0 | | SandboX | github.com/Deepractice/SandboX | sandboxxjs | MIT | --- *本文基于Deepractice开源仓库公开资料整理。* **思考题**：在你的AI项目中，最头疼的是运行时兼容性、资源管理，还是代码执行安全？欢迎在评论区分享你的经验。🚀