适用版本：ChengOS v0.1.0+ ｜ 最后核对：2026-08-13 ｜ 来源：
crates/cheng-nodes/src/nodes/builtin/tools、crates/cheng-workspace-tools/src
工作区工具中与文件无关的那一半，而且刻意做得不对称：tools/workspace_git、 tools/workspace_markdown、tools/workspace_preview 提供的都是只读操作， 而任何可能改变机器状态的动作 —— 执行任意 shell 命令，或真正跑一遍测试 —— 都需要经过审批。 这种不对称正是设计意图：检查应当零负担，变更应当是一次决定。 tools/workspace_tests 也按同一条线切开：detect 只读，run 需要审批。
工作区 Shell — tools/workspace_shell
运行工作区命令（构建/测试/lint/诊断），带策略检查、有界输出、超时和取消。结构化命令形式优先；shell 字符串为可选且高风险。
输入
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
command |
string | — | "" |
要运行的可执行程序，如 “ls”、”cargo”、”pnpm”、”pytest”。这不是工具名。 |
args |
array<string> | — | [] |
命令的字面参数，如 command=”ls”, args=[“-la”]。不支持 shell 语法。 |
shell_string |
string | — | null |
兼容输入。简单值如 “ls -la” 会被转换为 command+args。原始 shell 语法在 allow_shell_string 和本地策略均允许前被禁用。 |
cwd |
string | — | null |
工作目录相对于工作区根目录。省略表示根目录。 |
env |
object | — | {} |
额外环境变量。仅接受安全基线和操作员配置的允许列表；PATH 和加载器变量被拒绝。 |
timeout_ms |
integer | — | null |
墙钟预算（毫秒，默认 60000，最大 600000）。超时时进程树被终止并返回部分输出。 |
purpose |
string | — | null |
一句话说明为何需要此命令；显示在审批卡片上。 |
sandbox_root |
string | — | null |
服务器本地沙箱根目录（引擎注入；不对 LLM 暴露） |
allow_shell_string |
boolean | — | false |
原始 shell 字符串的静态可选开关（仅作者；默认关闭）。管道、重定向、变量等 shell 语法在此开启前被禁用。 控件：switch |
command_whitelist |
string | — | "" |
用户配置的命令白名单。每行一个程序名。非空时仅允许列出的程序，且拒绝 shell 字符串。 控件：textarea |
输出
| 字段 | 类型 | 说明 |
|---|---|---|
success |
boolean | 命令是否成功（退出码 0） |
summary |
string | 命令结果的人类可读摘要 |
command_display |
string | 已执行命令的显示形式 |
cwd |
string | 命令使用的工作目录 |
exit_code |
integer | 进程退出码（进程非正常退出时为 null） |
termination |
string | 终止原因：exited、timed_out、cancelled、signalled 或 spawn_failed |
duration_ms |
integer | 命令的墙钟耗时（毫秒） |
stdout |
string | 截断的标准输出文本（超限时头尾截断） |
stdout_truncated |
boolean | 标准输出是否因字节上限而头尾截断 |
stderr |
string | 截断的标准错误文本（超限时头尾截断） |
stderr_truncated |
boolean | 标准错误是否因字节上限而头尾截断 |
error_kind |
string | 失败时的稳定机器码（LOCAL_EXECUTOR_* 词汇） |
terminal |
boolean | 错误是否为终止性（不可重试） |
error |
string | 命令失败时的错误信息 |
工作区 Git — tools/workspace_git
只读 Git 检查（status/diff/log/show/branch），输出结构化且有界。不支持破坏性 Git 操作。
输入
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
operation |
string | — | "" |
只读 Git 操作：status、diff、log、show 或 branch |
cwd |
string | — | null |
仓库目录相对于工作区根目录。省略表示根目录。 |
pathspecs |
array<string> | — | [] |
相对路径过滤，缩小 diff/log/status 范围。不支持绝对路径和 ‘..’ |
revision |
string | — | null |
show 操作：纯本地版本（HEAD、HEAD~2、分支名、提交哈希）。拒绝范围/reflog/远程语法。 |
max_bytes |
integer | — | null |
输出字节上限（diff/show 默认 262144）。超限时头尾截断并标记。 |
max_count |
integer | — | null |
log 操作：提交数量（默认 20，最大 100） |
sandbox_root |
string | — | null |
服务器本地沙箱根目录（引擎注入；不对 LLM 暴露） |
输出
| 字段 | 类型 | 说明 |
|---|---|---|
operation |
string | 执行的 Git 操作 |
success |
boolean | 操作是否成功 |
summary |
string | 操作结果的人类可读摘要 |
files |
any | 结构化 status 条目（变更/暂存/未跟踪文件） |
commits |
any | 结构化 log 条目（哈希/作者/日期/主题） |
branches |
any | 本地分支名列表 |
current_branch |
string | 当前分支名（在分支列表中标记） |
stdout |
string | 截断的标准输出文本（diff/show 输出） |
stdout_truncated |
boolean | 标准输出是否因字节上限而头尾截断 |
stderr |
string | 截断的标准错误文本 |
error_kind |
string | 失败时的稳定机器码（LOCAL_EXECUTOR_* 词汇） |
terminal |
boolean | 错误是否为终止性（不可重试） |
error |
string | 操作失败时的错误信息 |
工作区测试 — tools/workspace_tests
检测项目的工具链和测试命令（只读），并运行显式测试命令，返回结构化的通过/失败摘要、超时和取消。
输入
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
operation |
string | — | "" |
detect = 只读项目检测；run = 执行显式测试命令（需审批） |
command |
string | — | null |
run 操作：测试程序，如 “cargo”、”pnpm”、”pytest”。run 必填；不从检测结果推断。 |
args |
array<string> | — | [] |
run 操作：字面命令参数，如 [“test”, “–no-fail-fast”] |
cwd |
string | — | null |
相对于工作区根目录的目录（monorepo 中的项目子目录） |
timeout_ms |
integer | — | null |
run 操作：墙钟预算（毫秒，默认 300000，最大 600000） |
sandbox_root |
string | — | null |
服务器本地沙箱根目录（引擎注入；不对 LLM 暴露） |
输出
| 字段 | 类型 | 说明 |
|---|---|---|
operation |
string | 执行的测试操作（detect 或 run） |
success |
boolean | 操作是否成功 |
summary |
string | 测试结果的人类可读摘要 |
detected_project |
any | 检测到的项目类型、包管理器、建议命令、置信度和证据（仅 detect） |
command_display |
string | 已执行测试命令的显示形式（仅 run） |
passed |
integer | 通过的测试数量（仅 run） |
failed |
integer | 失败的测试数量（仅 run） |
duration_ms |
integer | 测试运行的墙钟耗时（毫秒，仅 run） |
failure_summary |
any | 失败提示（名称/文件/行/消息），尽力而为（仅 run） |
termination |
string | 终止原因：exited、timed_out、cancelled、signalled 或 spawn_failed（仅 run） |
stdout |
string | 截断的标准输出文本（超限时头尾截断） |
stdout_truncated |
boolean | 标准输出是否因字节上限而头尾截断 |
stderr |
string | 截断的标准错误文本（超限时头尾截断） |
stderr_truncated |
boolean | 标准错误是否因字节上限而头尾截断 |
error_kind |
string | 失败时的稳定机器码（LOCAL_EXECUTOR_* 词汇） |
terminal |
boolean | 错误是否为终止性（不可重试） |
error |
string | 操作失败时的错误信息 |
工作区 Markdown — tools/workspace_markdown
只读 Markdown 分析：标题大纲、结构化诊断、格式建议（edit_file 可用的替换）和本地链接检查。
输入
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
operation |
string | — | "" |
只读 Markdown 分析：outline、diagnostics、format_suggestions 或 link_check_local |
path |
string | — | "" |
Markdown 文件路径相对于工作区根目录 |
sandbox_root |
string | — | null |
服务器本地沙箱根目录（引擎注入；不对 LLM 暴露） |
输出
| 字段 | 类型 | 说明 |
|---|---|---|
operation |
string | 执行的 Markdown 分析操作 |
path |
string | 分析的 Markdown 文件路径 |
success |
boolean | 分析是否成功 |
summary |
string | 分析结果的人类可读摘要 |
outline |
any | 标题树条目，包含层级、1-indexed 行号和 GitHub 风格锚点 |
diagnostics |
any | 结构化诊断：重复标题、标题层级跳跃、空链接目标等 |
suggested_edits |
any | 机械修复建议，格式为 edit_file 可用的替换；本工具不写入文件 |
error_kind |
string | 失败时的稳定机器码（LOCAL_EXECUTOR_* 词汇） |
terminal |
boolean | 错误是否为终止性（不可重试） |
error |
string | 操作失败时的错误信息 |
工作区预览 — tools/workspace_preview
渲染有界、安全的预览：Markdown 转安全 HTML、HTML 转文本摘要、或文件元数据。只读；持久化输出需通过文件操作。
输入
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
operation |
string | — | "" |
预览操作：markdown、html 或 artifact_summary |
path |
string | — | null |
源文件相对于工作区根目录。优先于 content。 |
content |
string | — | null |
内联源文本（不涉及工作区文件时使用） |
max_bytes |
integer | — | null |
预览字节上限（默认和最大 524288） |
sandbox_root |
string | — | null |
服务器本地沙箱根目录（引擎注入；不对 LLM 暴露） |
输出
| 字段 | 类型 | 说明 |
|---|---|---|
operation |
string | 执行的预览操作 |
success |
boolean | 预览是否成功 |
summary |
string | 预览结果的人类可读摘要 |
format |
string | 输出格式：html、text 或 metadata |
preview |
string | 渲染或派生的预览文本（有界） |
preview_truncated |
boolean | 预览是否因字节上限而头尾截断 |
source_bytes |
integer | 源内容的字节大小 |
source_path |
string | 预览来自工作区文件时的源文件路径 |
error_kind |
string | 失败时的稳定机器码（LOCAL_EXECUTOR_* 词汇） |
terminal |
boolean | 错误是否为终止性（不可重试） |
error |
string | 操作失败时的错误信息 |
下一步
© 版权声明
文章版权归作者所有，未经允许请勿转载。
THE END
暂无评论内容