适用版本：ChengOS v0.1.0+ ｜ 最后核对：2026-08-13 ｜ 来源：
crates/cheng-nodes/src/nodes/builtin/tools
把技能当作可构建、可校验的对象，而不只是拿来运行。tools/skill 执行一个技能。 tools/write_skill_package 产出技能包，tools/validate_skill_spec 在有人尝试发布或导入之前 按包格式对其做校验 —— 先校验再分发正是要点所在，因为已发布的产物不可变更。 tools/cli_install 执行技能包声明的安装步骤。
执行技能 — tools/skill
按名称查找并执行已注册的技能.
输入
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
skill_name |
string | ✅ | — | 要执行的技能名称(唯一标识). |
input_data |
any | — | null |
传递给工作流的输入数据(可选). |
timeout_seconds |
integer | — | 3600 |
最大等待时间(秒),默认 3600. |
async_execution |
boolean | — | false |
如果为 true,启动工作流后立即返回,不等待完成. |
env_vars |
object | — | null |
来自技能凭证注入节点的环境变量(可选) |
输出
| 字段 | 类型 | 说明 |
|---|---|---|
status |
string | 技能执行状态（参见 SkillOutput::status 文档了解闭枚举和前端映射） |
skill_id |
string | 匹配的技能 ID. |
skill_name |
string | 匹配的技能名称. |
execution_id |
string | 工作流执行 ID(如已启动). |
outputs |
any | 工作流输出数据 |
instructions |
string | 技能使用说明(无关联工作流时返回). |
next_action |
string | 建议的下一步操作(供 LLM 参考). |
error |
string | 错误信息 |
missing_binaries |
array | PATH 上未找到的必要二进制文件;安装它们或在使用它们的宿主机上运行技能. |
missing_credentials |
array | 无法解析的凭证绑定列表；渲染到凭证设置界面。 |
approval_outcome |
string | 高风险技能的审批门结果 |
normalization_status |
string | 规范规范规范化状态 |
policy_warnings |
array<string> | 运行时策略警告 |
operation |
string | 产生此输出的 Hub 操作 |
data |
any | 操作特定的载荷（发现页面或状态报告） |
写入技能包 — tools/write_skill_package
受限:安全地将技能包写入 skills/<name>/ 目录下,遵守管理员锁定并防止路径遍历.
输入
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
package |
object | — | — | 来自 tools/validate_skill_spec 的组合验证包.优先将 Validate.validated_package 连接到单个端口. |
skill_name |
string | — | "" |
稳定的技能 slug.接受普通字符串或 JSON 字符串形式 {“skill_name”: “…”}(生成器提示形状). |
files |
array<object> | — | — | 要写入的文件负载.接受结构化数组或相同数组的 JSON 字符串,因此可直接连接到返回 JSON 文本的 AI/LLM 响应. |
force_admin_override |
boolean | — | false |
调用方必须在获得明确管理员同意后才能设置此参数,以覆盖锁定技能. |
workspace_id |
string | — | null |
导入技能的所属工作区。设置后，写入器通过 SKILL.md 导入元数据将技能标记为该工作区私有。通常从执行上下文解析而非直接提供。 |
source_snapshot |
object | — | null |
来自 tools/fetch_repository 的不透明源快照工件引用。原样转发；切勿重建、枚举或省略源字节。 |
输出
| 字段 | 类型 | 说明 |
|---|---|---|
success |
boolean | 指示包是否通过验证、审批并提交。 |
status |
string | 稳定状态：written \ |
retryable |
boolean | 调用方可以合理修复并重试时为 true（如可修复的验证失败或过时目标）。 |
skill_name |
string | 实际写入的技能 slug(已通过 slug 校验). |
written_paths |
array<string> | 已写入磁盘的文件的绝对路径列表.仅写入通过白名单(SKILL.md / skill.yaml / workflow.json / references/*)的文件. |
package_digest |
string | 已提交（消毒 + 受信任元数据）包字节的 sha256 摘要。成功时存在。 |
validation |
any | 包确定性验证失败时的结构化验证结果（valid, issue_fingerprint, issues, warnings）。 |
error |
string | 失败时的错误描述信息.仅当 success=false 时存在. |
error_code |
string | 结构化错误代码(如 INVALID_SKILL_NAME,EMPTY_PAYLOAD,SKILL_LOCKED,PATH_TRAVERSAL,DISALLOWED_FILE 等),便于上层做条件分支.仅当 success=false 时存在. |
验证技能规范 — tools/validate_skill_spec
在文件写入前验证 LLM 生成的技能包是否符合 ChengOS 规范与契约.
输入
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
name_path |
string | — | null |
组合的技能名称和包路径输入.这是手工构建导入工作流的单端口路径:普通字符串作为 package_path 处理,skill_name 从最终路径段推断;JSON 字符串或对象则使用 { “skill_name”: “…”, “package_path”: “…” }. |
skill_name |
string | — | "" |
稳定的技能 slug.必须与规范中的 name 匹配. |
files |
array<object> | — | [] |
导入器将写入的文件负载——通常为 SKILL.md,skill.yaml,workflow.json 以及引用.接受结构化数组或相同形状的 JSON 字符串,因此可直接连接到返回 JSON 文本的 AI/LLM 响应. |
package_path |
string | — | null |
chengflow/workspaces 下的可选暂存路径(或 CHENG_VALIDATE_SKILL_STAGING_ROOT).当 files 为空时,这可能指向:包含 [{path, content}, …] 的 JSON 清单文件,或 { “files”: […] };也可能是包含 SKILL.md,skill.yaml,可选 workflow.json 和可选 references/* 的技能包目录. |
sandbox_root |
string | — | null |
package_path 解析的基准目录。填入与文件操作工具写入包时使用的相同 sandbox_root — 即该工具 [Instance Constraints] 块和 view_file/edit_file 结果中显示的绝对目录（如 /home/cheng/works/chengos/chengflow/skills）。然后在 package_path 中只传包文件夹名。这是验证器找到写入器创建文件的方式。 |
skip_review |
boolean | — | false |
可信导入：仅跳过 LLM/人工审查阶段（提升为 ready），适用于已知安全的包。确定性验证始终运行。仅在服务器启用 CHENG_ALLOW_SKILL_SKIP_REVIEW、包无错误且工具面非高风险时生效。 |
skip_review_reason |
string | — | null |
skip_review 生效时记录的审计原因（如 owned-package-reimport）。 |
trusted_source |
boolean | — | false |
导入来源可信的建议性提示；本身不绕过任何检查。 |
输出
| 字段 | 类型 | 说明 |
|---|---|---|
valid |
boolean | 指示技能包是否通过验证. |
errors |
array<string> | 验证失败时返回的结构化错误列表. |
warnings |
array<string> | 验证过程中的警告信息. |
skill_name_out |
string | 运行时条件验证后的技能名称.仅当验证成功时存在. |
normalization_status |
string | 验证后的规范归一化状态. |
canonical_spec |
any | 运行时条件的规范对象.仅当验证成功时存在. |
sanitized_files |
array<object> | 原始文件列表,其中 skill.yaml 被清理后的规范替换(normalization.status 强制为 needs_review,execution.auto_execute 强制为 false,移除任何 LLM 注入的前端信任开关).下游 tools/write_skill_package 必须使用 sanitized_files,绝不能使用原始 LLM 输出,因此磁盘上的 skill.yaml 反映已验证的策略. |
sanitized_files_if_valid |
array | 运行时条件清理后的文件.仅当验证成功时存在. |
validated_package |
object | 运行时条件包,包含 skill_name 和清理后的文件.仅当验证成功时存在. |
approval_summary |
string | 运行时条件 JSON 摘要,用于管理员审批.仅当验证成功时存在. |
backend_type |
string | 验证通过的后端类型(workflow \ |
llm_tools |
any | 智能体技能的 LLM 可见工具表层(llm_tools.expose).非智能体技能无此输出. |
requires_tool_review |
boolean | 当公开的工具表层授予广泛/高风险访问权限时为 true,必须在技能被提升为就绪状态前由管理员进行审查. |
review_skipped |
boolean | 可信跳过审查生效时为 true（跳过 LLM/人工审查阶段提升为 ready）。确定性验证仍会运行。 |
issues |
array<object> | 结构化验证问题，含稳定代码、严重性、文件/字段位置和可重试性。兼容错误/警告从同一集合渲染。 |
issue_fingerprint |
string | 基于排序的 (severity, code, file, path) 元组的稳定指纹；排除消息文本和源内容。无问题时不存在。 |
CLI 安装 — tools/cli_install
从可信 CLI 包索引确定性地生成、验证并按顺序执行安装步骤；LLM 只提供 CLI 名称，高风险步骤仍需审批。
输入
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
cli_name |
string | ✅ | — | 要安装的 CLI 名称，例如 gh、jq 或 rg；必须存在于可信包索引中。 |
working_subdir |
string | — | null |
执行边界内的可选相对工作目录。 |
timeout_ms |
integer | — | 120000 |
每个安装步骤的执行超时时间（毫秒）。 |
memory_mb |
integer | — | 512 |
每个安装步骤的内存限制（MB）。 |
输出
| 字段 | 类型 | 说明 |
|---|---|---|
success |
boolean | 是否成功 |
status |
string | 稳定状态：ok、not_found 或 error。 |
cli_name |
string | CLI 名称 |
provider_id |
string | 提供商 ID |
package_manager |
string | 包管理器 |
steps |
array<object> | 步骤结果 |
error |
string | 错误信息 |
下一步
© 版权声明
文章版权归作者所有，未经允许请勿转载。
THE END
暂无评论内容