适用版本：ChengOS v0.1.0+ ｜ 最后核对：2026-08-13 ｜ 来源：crates/cheng-nodes/src/nodes/builtin/tools、crates/cheng-runtime/src
脚本执行，运行在沙箱内。tools/code_shell 默认可用；tools/code_python 与 tools/code_js 受 CHENG_ENABLE_CODE_PYTHON、CHENG_ENABLE_CODE_JS 两个环境变量控制，未设置时根本不会注册。 脚本需要访问沙箱之外的内容时，一律走申请只读路径的字段，且每条路径都要人工批准本次执行。 tools/runtime 不是脚本节点：它把配置好的工具集合展开给智能体，并执行其中一次调用。
Shell 执行器 — tools/code_shell
在 bubblewrap 沙箱中运行 Shell 脚本（OS 命名空间隔离：PID/IPC/UTS/网络）。失败即关闭：bubblewrap 不可用时直接报错 — 不会静默降级。适用于 curl、wget、系统命令、文件操作、管道处理等外部进程。不适用于纯计算（→ JS）或数据转换（→ Python）。需要 allow_network=true 才能进行出站 HTTP。示例：{“script”:”curl -s ‘wttr.in/Tokyo?format=3′”,”allow_network”:true}
输入
| 字段 |
类型 |
必填 |
默认值 |
说明 |
input |
any |
— |
null |
输入数据(任意 JSON),脚本中通过 $INPUT 环境变量访问 |
script |
string |
— |
null |
[必填]Shell 脚本.示例:curl -s ‘wttr.in/Tokyo?format=3’. 控件：code-editor |
working_subdir |
string |
— |
null |
执行边界内的相对工作子目录（如 project-alpha）。仅设置进程 cwd；不能扩大文件系统访问范围。 |
allow_filesystem |
boolean |
— |
false |
是否允许脚本写入工作区文件. 控件：switch |
allow_full_disk_readonly |
boolean |
— |
false |
是否允许只读访问整个磁盘(用于全盘搜索/文件查找).写入仍需 allow_filesystem. 控件：switch |
request_read_paths |
array<string> |
— |
[] |
申请访问沙箱之外的宿主机绝对路径,仅只读(例如 /home/me/project)。每条路径都需要人工批准本次执行;获批路径以只读方式挂载。仅在脚本必须读取沙箱看不到的文件时使用。 |
allow_network |
boolean |
— |
false |
是否允许网络访问(curl,HTTP 请求等需要设为 true). 控件：switch |
timeout_ms |
integer |
— |
5000 |
超时时间(毫秒).默认 5000ms,最大 300000ms. 控件：number |
memory_mb |
integer |
— |
128 |
内存限制(MB).通过 Bubblewrap 下的 prlimit 强制执行.默认 128MB. 控件：number |
输出
| 字段 |
类型 |
说明 |
result |
any |
脚本执行结果 |
isolation_level |
string |
实际使用的隔离级别:bubblewrap > quickjs > python |
metrics |
object |
执行性能指标 |
stdout |
string |
标准输出 |
stderr |
string |
标准错误 |
warnings |
array<string> |
脚本验证警告 |
Python 执行器 — tools/code_python
在 bubblewrap 沙箱中运行 Python 3 脚本（与 Shell 节点共享 OS 命名空间隔离）。失败即关闭：安全启动器或 python3 不可用时直接报错 — 不会降级到宿主机原生执行。适用于算法、文本处理、数据转换和科学计算。不适用于网络请求（用 Shell）或简单 JSON/字符串转换（用 JavaScript）。网络访问在设计上被禁用。JSON 输入通过 input 变量可用。
输入
| 字段 |
类型 |
必填 |
默认值 |
说明 |
input |
any |
— |
null |
暴露给脚本作为 input 变量的 JSON 输入 |
script |
string |
— |
null |
[必填] Python 3 脚本。示例：result = sum(input['values']). 控件：code-editor |
working_subdir |
string |
— |
null |
执行边界内的相对工作子目录（如 project-alpha）。仅设置进程 cwd；不能扩大文件系统访问范围。 |
allow_filesystem |
boolean |
— |
false |
是否允许脚本向工作区写入文件. 控件：switch |
allow_full_disk_readonly |
boolean |
— |
false |
是否允许只读访问整个磁盘（用于全盘搜索和文件查找）。写入仍被禁止。 控件：switch |
request_read_paths |
array<string> |
— |
[] |
申请访问沙箱之外的宿主机绝对路径,仅只读(例如 /home/me/project)。每条路径都需要人工批准本次执行;获批路径以只读方式挂载。仅在脚本必须读取沙箱看不到的文件时使用。 |
timeout_ms |
integer |
— |
5000 |
超时时间（毫秒）。默认：5000 毫秒。最大：300000 毫秒。 控件：number |
memory_mb |
integer |
— |
128 |
内存限制（MB）。可用时通过 cgroup v2 硬性执行，否则回退到 prlimit。默认：128 MB。 控件：number |
输出
| 字段 |
类型 |
说明 |
result |
any |
脚本返回的结果 |
isolation_level |
string |
运行时实际使用的隔离级别：bubblewrap、quickjs、python、shell 或 container |
metrics |
object |
运行时执行指标 |
stdout |
string |
标准输出流 |
stderr |
string |
标准错误流 |
warnings |
array<string> |
执行前生成的验证警告 |
JavaScript 执行器 — tools/code_js
在 QuickJS 沙箱中运行 JavaScript，无系统调用、网络或文件系统访问。QuickJS 不可用时直接报错（fail-closed）。适用于纯计算、JSON/对象转换、字符串操作和数学运算。不适用于网络请求（用 Shell）或依赖库较多的数据处理（用 Python）。
输入
| 字段 |
类型 |
必填 |
默认值 |
说明 |
input |
any |
— |
null |
暴露给脚本作为 input 变量的 JSON 输入 |
script |
string |
— |
null |
[必填] JavaScript 脚本。最终表达式的值作为 result 返回。 控件：code-editor |
timeout_ms |
integer |
— |
5000 |
超时时间（毫秒）。默认：5000 毫秒。最大：300000 毫秒。 控件：number |
memory_mb |
integer |
— |
128 |
内存限制（MB）。QuickJS 将此作为内部软限制执行。默认：128 MB。 控件：number |
输出
| 字段 |
类型 |
说明 |
result |
any |
脚本返回的结果 |
isolation_level |
string |
运行时实际使用的隔离级别：bubblewrap、quickjs、python、shell 或 container |
metrics |
object |
运行时执行指标 |
stdout |
string |
标准输出流 |
stderr |
string |
标准错误流 |
warnings |
array<string> |
执行前生成的验证警告 |
工具运行时 — tools/runtime
可配置的工具包:一次性连接 to an LLM/Agent,并公开一组受策略限制的精选工具.
输入
| 字段 |
类型 |
必填 |
默认值 |
说明 |
action |
enum |
— |
list_tools |
操作: list_tools \ |
tool_call |
object |
— |
— |
当 action=execute 时的工具调用信息 |
exposed_tools |
array<object> |
— |
[] |
精选工具包 |
dry_run |
boolean |
— |
false |
仅验证而不分发执行 |
输出
| 字段 |
类型 |
说明 |
status |
string |
运行时操作状态 |
functions |
array<any> |
展开的 LLM 函数 |
result |
any |
工具执行结果 |
errors |
array<string> |
配置错误信息 |
warnings |
array<string> |
配置警告信息 |
下一步
暂无评论内容