WP Codebox是一个为AI代理工作流设计的运行时合约，基于WordPress Playground提供可隔离、可复现、可审查的一次性沙箱环境，让平台能够在受控环境中执行代理任务并导出持久化产物。

WP Codebox：为AI代理工作流打造的一次性WordPress沙箱环境\n\n## 背景：AI代理执行环境的安全困境\n\n随着AI代理在软件开发、内容管理等领域的应用日益广泛，一个核心问题逐渐凸显：如何让AI代理安全地执行任务，同时又不给生产环境带来风险？\n\n传统的解决方案往往面临两难选择：\n- 给予代理广泛的生产环境访问权限，带来安全风险\n- 限制代理权限，又无法完成复杂的实际任务\n\nCI/CD环境虽然提供了隔离性，但通常只适用于批量任务，难以支持实时的交互式代理工作流。本地机器虽然灵活，但环境一致性难以保证，且存在数据泄露风险。\n\nWP Codebox项目正是为了解决这一困境而设计的。\n\n## 项目概述\n\nWP Codebox不是一个应用程序，也不是一个代理框架或CI/CD工具。它是一个运行时合约，为需要创建隔离环境、挂载输入、执行受控操作、观察状态并在沙箱消失前导出持久化产物的平台提供标准化接口。\n\n其核心使用场景是实时的、沙箱化的代理工作。产品可以让用户与代理进行对话，在一次性沙箱中运行工作，流式传输观察结果，并仅将最终产物应用到真实项目或站点。\n\n对于WordPress生态系统，这意味着像Studio、Data Machine或WordPress.com这样的控制平面可以让代理在WordPress Playground沙箱中运行，而不是授予对生产站点的广泛访问权限。\n\n## 架构设计\n\nWP Codebox的架构遵循清晰的分层设计：\n\n\n应用或代理平台\n ↓\nWP Codebox合约\n ↓\n后端适配器\n ↓\n隔离环境\n ↓\n可复现的产物包\n\n\n这种分层设计使得WP Codebox可以支持不同的后端实现。目前，WordPress Playground是第一个后端实现，但架构本身并不局限于WordPress。\n\n## 核心组件\n\nWP Codebox项目包含以下核心包：\n\n### 1. @chubes4/wp-codebox-core\n\n提供后端无关的运行时接口和共享类型定义。这是整个框架的基础层，定义了所有后端实现必须遵循的合约。\n\n### 2. @chubes4/wp-codebox-playground\n\n第一个后端适配器，基于WordPress Playground构建。它实现了将WP Codebox合约映射到WordPress Playground的具体逻辑。\n\n### 3. @chubes4/wp-codebox-cli\n\n为外部消费者提供的命令行工具wp-codebox，支持通过命令行与运行时交互。\n\n### 4. packages/wordpress-plugin\n\n用于父站点的WordPress插件，提供启动沙箱化代理任务的能力接口。\n\n## 核心功能特性\n\n### 1. 惰性启动机制\n\nWP Codebox采用惰性启动策略，只有在第一次调用execute()时才启动Playground环境。这种设计避免了不必要的资源消耗，特别是在只需要验证配置而不实际执行的场景。\n\n### 2. 挂载系统\n\n支持将本地目录挂载到沙箱中的指定位置：\n\n```bash\nnpm run wp-codebox -- run \\

--mount ./examples/simple-plugin:/wordpress/wp-content/plugins/simple-plugin \
--command wordpress.run-php \
--arg code-file=./examples/simple-plugin/probe.php \
--artifacts ./artifacts \
--json\n\n\n挂载系统支持读写模式，允许代理在沙箱中修改文件，并将变更捕获到产物包中。\n\n### 3. 命令体系\n\nWP Codebox提供三类核心命令：\n\n**wordpress.run-php**：在Playground中运行PHP代码\n- 支持通过`--arg code-file=<path>`指定代码文件\n- 支持通过`--arg code=<php>`直接传入PHP代码\n- 默认加载`/wordpress/wp-load.php`，使WordPress函数默认可用\n- 可通过`--arg bootstrap=none`禁用WordPress引导\n\n**wordpress.wp-cli**：在Playground中运行WP-CLI命令\n- 自动启用Playground的wp-cli扩展库\n- 通过`--arg command='wp option get home'`传递命令\n- 命令前的`wp`前缀可选\n\n**wordpress.ability**：执行注册的WordPress Ability\n- 通过`name=<ability>`指定能力名称\n- 通过`input=<object>`传递JSON输入\n- 在REST风格的WordPress请求中运行\n\n### 4. 产物捕获\n\n执行完成后，WP Codebox会生成完整的产物包，包含：\n- `manifest.json`：产物清单\n- `blueprint.after.json`：执行后的环境蓝图\n- `blueprint.after-notes.json`：执行备注\n- `events.jsonl`：事件流\n- `commands.jsonl`：命令记录\n- `observations.jsonl`：观察结果\n- `files/mounted-files.json`：挂载文件捕获\n\n这种详细的记录机制确保了执行过程的可审计性和可复现性。\n\n## Recipe系统：可移植的实验室合约\n\nWP Codebox引入了Recipe（配方）概念，将可重复的沙箱设置和工作流打包为JSON格式。Recipe是以下场景的便携实验室合约：\n\n- 工作坊环境\n- 贡献者日活动\n- 隔离测试\n- 评估任务\n- 可复现的Bug报告套件\n\n### Recipe结构\n\n一个典型的Recipe包含以下部分：\n\njson\n{\n "schema": "wp-codebox/workspace-recipe/v1",\n "runtime": {\n "backend": "wordpress-playground",\n "name": "simple-plugin-lab",\n "wp": "7.0"\n },\n "inputs": {\n "workspaces": [...],\n "extra_plugins": [...],\n "mounts": [...],\n "secretEnv": []\n },\n "workflow": {\n "steps": [...]\n },\n "artifacts": {\n "directory": "./artifacts"\n }\n}\n\n\n### 工作空间种子\n\nRecipe支持多种工作空间种子类型：\n\n- **plugin_scaffold**：创建最小化的插件结构（.php和README.md），默认挂载到`/wordpress/wp-content/plugins/`\n- **theme_scaffold**：创建主题结构（style.css、index.php、README.md），默认挂载到`/wordpress/wp-content/themes/`\n- **directory**：将现有目录复制到一次性工作空间，需要显式指定目标路径\n\n### Recipe验证\n\nWP Codebox提供验证命令，可以在启动沙箱前检查Recipe的有效性：\n\nbash\nnpm run wp-codebox -- recipe validate \
--recipe ./examples/recipes/simple-plugin.json \
--json\n```\n\n验证内容包括：\n- Recipe模式合规性\n- 源路径存在性\n- 额外插件入口点有效性\n- 工作空间种子配置\n- 工作流命令支持情况\n- JSON能力输入格式\n- 命令参数正确性\n\n## 版本策略\n\nWP Codebox默认使用WordPress 7.0，因为现代AI插件栈需要较新的WordPress AI接口。同时支持通过--wp参数指定其他版本：\n- --wp trunk：使用最新开发版\n- --wp nightly：使用夜间构建版\n- --wp 6.5：使用特定版本\n\n## 应用场景\n\n### 场景一：实时代理对话\n\n用户与AI代理进行对话，代理在WP Codebox沙箱中执行代码变更，用户可以实时观察执行结果，最终只将满意的产物应用到生产站点。\n\n### 场景二：安全评估\n\n在合并Pull Request前，使用WP Codebox运行自动化评估任务，在隔离环境中验证变更的安全性和功能性。\n\n### 场景三：教学与工作坊\n\n通过Recipe定义标准化的实验环境，参与者可以快速获得一致的沙箱，专注于学习内容而非环境配置。\n\n### 场景四：插件开发\n\n插件开发者可以使用WP Codebox快速搭建测试环境，验证插件在不同WordPress版本和配置下的行为。\n\n## 技术意义\n\nWP Codebox的设计体现了几个重要的技术理念：\n\n### 1. 合约优先设计\n\n通过定义清晰的运行时合约，WP Codebox实现了平台与后端的解耦。这种设计使得未来可以支持其他后端（如Docker、Kubernetes等），而无需修改上层应用。\n\n### 2. 不可变基础设施\n\n每次执行都在全新的沙箱中进行，执行完成后沙箱被销毁。这种不可变性消除了环境漂移问题，确保了执行结果的可复现性。\n\n### 3. 产物导向\n\nWP Codebox强调产物的导出和持久化，而非沙箱本身的长期运行。这种设计符合现代CI/CD的最佳实践，也适应了AI代理工作流的特点。\n\n### 4. 可审计性\n\n详细的事件流、命令记录和观察结果捕获，使得每次执行都可以被事后审查。这对于安全敏感的场景和合规要求至关重要。\n\n## 项目展望\n\nWP Codebox目前以WordPress Playground为首个后端，但其架构设计具有更广泛的适用性。未来可能的发展方向包括：\n\n- 支持更多后端实现（Docker、云端容器等）\n- 扩展产物类型支持（静态站点、数据集、补丁等）\n- 与更多AI代理框架集成\n- 增强Recipe生态系统\n\n对于WordPress生态系统和更广泛的Web开发社区，WP Codebox提供了一个重要的基础设施组件，让AI代理能够在安全、隔离、可复现的环境中工作，为AI辅助开发的大规模应用奠定了基础。

WP Codebox：为AI代理工作流打造的一次性WordPress沙箱环境\n\n背景：AI代理执行环境的安全困境\n\n随着AI代理在软件开发、内容管理等领域的应用日益广泛，一个核心问题逐渐凸显：如何让AI代理安全地执行任务，同时又不给生产环境带来风险？\n\n传统的解决方案往往面临两难选择：\n- 给予代理广泛的生产环境访问权限，带来安全风险\n- 限制代理权限，又无法完成复杂的实际任务\n\nCI/CD环境虽然提供了隔离性，但通常只适用于批量任务，难以支持实时的交互式代理工作流。本地机器虽然灵活，但环境一致性难以保证，且存在数据泄露风险。\n\nWP Codebox项目正是为了解决这一困境而设计的。\n\n项目概述\n\nWP Codebox不是一个应用程序，也不是一个代理框架或CI/CD工具。它是一个运行时合约，为需要创建隔离环境、挂载输入、执行受控操作、观察状态并在沙箱消失前导出持久化产物的平台提供标准化接口。\n\n其核心使用场景是实时的、沙箱化的代理工作。产品可以让用户与代理进行对话，在一次性沙箱中运行工作，流式传输观察结果，并仅将最终产物应用到真实项目或站点。\n\n对于WordPress生态系统，这意味着像Studio、Data Machine或WordPress.com这样的控制平面可以让代理在WordPress Playground沙箱中运行，而不是授予对生产站点的广泛访问权限。\n\n架构设计\n\nWP Codebox的架构遵循清晰的分层设计：\n\n\n应用或代理平台\n ↓\nWP Codebox合约\n ↓\n后端适配器\n ↓\n隔离环境\n ↓\n可复现的产物包\n\n\n这种分层设计使得WP Codebox可以支持不同的后端实现。目前，WordPress Playground是第一个后端实现，但架构本身并不局限于WordPress。\n\n核心组件\n\nWP Codebox项目包含以下核心包：\n\n1. @chubes4/wp-codebox-core\n\n提供后端无关的运行时接口和共享类型定义。这是整个框架的基础层，定义了所有后端实现必须遵循的合约。\n\n2. @chubes4/wp-codebox-playground\n\n第一个后端适配器，基于WordPress Playground构建。它实现了将WP Codebox合约映射到WordPress Playground的具体逻辑。\n\n3. @chubes4/wp-codebox-cli\n\n为外部消费者提供的命令行工具wp-codebox，支持通过命令行与运行时交互。\n\n4. packages/wordpress-plugin\n\n用于父站点的WordPress插件，提供启动沙箱化代理任务的能力接口。\n\n核心功能特性\n\n1. 惰性启动机制\n\nWP Codebox采用惰性启动策略，只有在第一次调用execute()时才启动Playground环境。这种设计避免了不必要的资源消耗，特别是在只需要验证配置而不实际执行的场景。\n\n2. 挂载系统\n\n支持将本地目录挂载到沙箱中的指定位置：\n\n```bash\nnpm run wp-codebox -- run \\

--mount ./examples/simple-plugin:/wordpress/wp-content/plugins/simple-plugin \
--command wordpress.run-php \
--arg code-file=./examples/simple-plugin/probe.php \
--artifacts ./artifacts \
--json\n\n\n挂载系统支持读写模式，允许代理在沙箱中修改文件，并将变更捕获到产物包中。\n\n3. 命令体系\n\nWP Codebox提供三类核心命令：\n\n**wordpress.run-php**：在Playground中运行PHP代码\n- 支持通过`--arg code-file=<path>`指定代码文件\n- 支持通过`--arg code=<php>`直接传入PHP代码\n- 默认加载`/wordpress/wp-load.php`，使WordPress函数默认可用\n- 可通过`--arg bootstrap=none`禁用WordPress引导\n\n**wordpress.wp-cli**：在Playground中运行WP-CLI命令\n- 自动启用Playground的wp-cli扩展库\n- 通过`--arg command='wp option get home'`传递命令\n- 命令前的`wp`前缀可选\n\n**wordpress.ability**：执行注册的WordPress Ability\n- 通过`name=<ability>`指定能力名称\n- 通过`input=<object>`传递JSON输入\n- 在REST风格的WordPress请求中运行\n\n4. 产物捕获\n\n执行完成后，WP Codebox会生成完整的产物包，包含：\n- `manifest.json`：产物清单\n- `blueprint.after.json`：执行后的环境蓝图\n- `blueprint.after-notes.json`：执行备注\n- `events.jsonl`：事件流\n- `commands.jsonl`：命令记录\n- `observations.jsonl`：观察结果\n- `files/mounted-files.json`：挂载文件捕获\n\n这种详细的记录机制确保了执行过程的可审计性和可复现性。\n\nRecipe系统：可移植的实验室合约\n\nWP Codebox引入了Recipe（配方）概念，将可重复的沙箱设置和工作流打包为JSON格式。Recipe是以下场景的便携实验室合约：\n\n- 工作坊环境\n- 贡献者日活动\n- 隔离测试\n- 评估任务\n- 可复现的Bug报告套件\n\nRecipe结构\n\n一个典型的Recipe包含以下部分：\n\njson\n{\n "schema": "wp-codebox/workspace-recipe/v1",\n "runtime": {\n "backend": "wordpress-playground",\n "name": "simple-plugin-lab",\n "wp": "7.0"\n },\n "inputs": {\n "workspaces": [...],\n "extra_plugins": [...],\n "mounts": [...],\n "secretEnv": []\n },\n "workflow": {\n "steps": [...]\n },\n "artifacts": {\n "directory": "./artifacts"\n }\n}\n\n\n工作空间种子\n\nRecipe支持多种工作空间种子类型：\n\n- **plugin_scaffold**：创建最小化的插件结构（.php和README.md），默认挂载到`/wordpress/wp-content/plugins/`\n- **theme_scaffold**：创建主题结构（style.css、index.php、README.md），默认挂载到`/wordpress/wp-content/themes/`\n- **directory**：将现有目录复制到一次性工作空间，需要显式指定目标路径\n\nRecipe验证\n\nWP Codebox提供验证命令，可以在启动沙箱前检查Recipe的有效性：\n\nbash\nnpm run wp-codebox -- recipe validate \\