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？

核心模块

1. Logger（懒初始化日志）

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（统一数据库接口）

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（跨运行时路径工具）

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生成工具）

import { generateId, generateRequestId } from "commonxjs/id";

const msgId = generateId("msg");
// => "msg_1704067200000_a1b2c3"

const reqId = generateRequestId();
// => "req_1704067200000_x7y8z9"

在Deepractice生态中的作用

三、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（资源）

// 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

{
  "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工具

# 安装
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使用

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");

自托管注册表

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执行代码的安全困境

SandboX的解决方案：统一API，多种隔离策略

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. 多语言支持

// 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）

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模式）

// 启用记录
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模式）

// 自动持久化到磁盘
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

隔离策略对比

架构设计

createSandbox({ isolator, runtime, state })
         │
    ┌────┴────┐
    ▼         ▼
┌────────┐ ┌──────────┐
│ Node.js│ │ Python   │
│Sandbox │ │ Sandbox  │
└────┬───┘ └────┬─────┘
     │          │
     └────┬─────┘
          ▼
    ┌─────────────┐
    │ State Layer │
    │  - fs       │
    │  - env      │
    │  - storage  │
    └──────┬──────┘
           ▼
    ┌─────────────────┐
    │ Isolator Layer  │
    ├────────┬────────┤
    │ Local  │ Cloud  │
    │(process)│(container)│
    └────────┴────────┘

在Deepractice生态中的作用

五、三个项目的协同关系

数据流示例：Agent执行用户代码

用户输入代码
     ↓
AgentX接收请求
     ↓
SandboX创建安全沙箱
     ↓
CommonX提供跨运行时工具
     ↓
ResourceX加载所需资源（工具/prompt）
     ↓
在沙箱中执行代码
     ↓
SandboX记录状态变化
     ↓
返回结果给用户

依赖关系

SandboX
  ├── CommonX（基础工具）
  └── ResourceX（资源加载）

AgentX
  ├── SandboX（代码执行）
  ├── CommonX（工具）
  └── ResourceX（资源管理）

AgentVM
  └── SandboX（底层运行时）

PromptX
  └── ResourceX（角色资源管理）

六、与业界方案的对比

CommonX vs 其他工具库

ResourceX vs 其他资源管理

SandboX vs 其他沙箱

七、开发者如何参与

使用场景建议

贡献方式

GitHub组织：Deepractice
├── CommonX - MIT License
├── ResourceX - Apache-2.0 License
└── SandboX - MIT License

八、总结：基础设施决定生态高度

Deepractice的三个基础设施项目，分别解决了AI应用开发的三个根本问题：

一句话总结：

如果说PromptX、AgentX是Deepractice生态的"面子"，那么CommonX、ResourceX、SandboX就是"里子"——没有扎实的基础设施，上层应用只能是空中楼阁。

参考资源

本文基于Deepractice开源仓库公开资料整理。

思考题：在你的AI项目中，最头疼的是运行时兼容性、资源管理，还是代码执行安全？欢迎在评论区分享你的经验。🚀