适用版本：ChengOS v0.1.0+ ｜ 最后核对：2026-08-13 ｜ 来源：
crates/cheng-nodes/src/nodes/builtin/tools
工作流审视工作流。tools/workflow_inspect 列出并检索实例上的工作流， 也包括找出所有包含某个节点类型的工作流。tools/import_workflow 负责把工作流定义导入进来。 tools/get_execution_trace 读回历史执行做了什么，提供三种深度 —— 概要、工具调用、有上限的明细 —— 让智能体不必拉取整条轨迹就能定位失败。tools/read_artifact 取回工件引用背后的内容。
工作流检查器 — tools/workflow_inspect
只读查询工作流定义,节点模式和执行状态.list_workflows=列出模板工作流(is_template=true,名称/标签过滤,sort_by 确定性排序,分页);find_workflows_by_node_type=反向查找包含某个精确 node_type 的模板工作流(created_at 降序);get_workflow=获取工作流详情(view=both 保持兼容,summary 减少 token,full 返回可导入定义);list_node_types=列出节点类型(可选 node_filter 模糊匹配 + category_filter,compact 精简投影);get_node_schema=获取节点输入/输出模式(describe_node_type 的别名);list_ports=列出紧凑端口信息(名称/类型/是否必填);find_replacements=给定节点类型返回有效候选并明确提示类型已存在;get_execution=按 execution_id 查询执行状态和节点输出(execution_node_filter/node_status_filter 可启用增强的逐节点记录和 matched_count);list_executions=列出工作流的执行历史(需要 workflow_id).
输入
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
mode |
enum | — | manual |
执行模式:Manual=用户手动填写参数,Llm=LLM 自动填充参数. 控件：select. 取值：manual, llm |
action |
string | — | "" |
操作类型:list_workflows(sort_by 确定性排序) / find_workflows_by_node_type(按精确 node_type 反查工作流) / get_workflow(view=both/summary/full) / list_node_types(默认精简,verbose=true 返回完整信息,支持 node_filter/category_filter) / get_node_schema(describe_node_type 的别名) / list_ports(列出紧凑端口信息) / find_replacements(建议有效节点类型并提示已存在类型) / get_execution(支持 execution_node_filter/node_status_filter) / list_executions. 控件：select. 取值：list_workflows (模板工作流列表), find_workflows_by_node_type (按节点类型查工作流), get_workflow (获取工作流), list_node_types (节点类型列表), get_node_schema (获取节点模式), list_ports (列出端口), find_replacements (查找替换候选), validate_workflow (验证工作流), get_execution (获取执行), list_executions (执行历史) |
workflow_id |
string | — | null |
工作流 UUID(get_workflow 必需). |
view |
enum | — | both |
仅 get_workflow:both(默认,保留兼容的完整响应) / summary(仅 agentSummary 和元信息,减少 token) / full(仅可导入 definition 和元信息). 控件：select. 取值：both (保留 agentSummary、definition 和旧版顶层副本，完全兼容现有调用方。), summary (仅返回紧凑的 agentSummary 和工作流元数据。), full (仅返回可导入的 definition 和工作流元数据。) |
name_filter |
string | — | null |
工作流名称过滤(可选,用于 list_workflows,模糊匹配). |
tag_filter |
string | — | null |
工作流标签过滤(可选,用于 list_workflows,精确匹配). |
limit |
integer | — | 50 |
最大返回数量(默认 50,最大 200). |
offset |
integer | — | 0 |
分页偏移量(默认 0). |
node_type |
string | — | null |
节点类型 ID(get_node_schema 必需,例如 agent/llm). |
compact |
boolean | — | false |
仅 get_node_schema：为 true 时 input_schema 和 output_schema 返回顶层字段名数组而非完整 JSON Schema。只需端口名时先用此选项；留 false（默认）获取类型、必填字段和嵌套约束。 控件：switch |
category_filter |
string | — | null |
节点分类筛选(可选,用于 list_node_types). |
node_filter |
string | — | null |
list_node_types 的模糊节点过滤器(匹配节点类型,名称和描述,不区分大小写,例如 ‘chat’). |
node_types |
array | — | null |
用于查找替换候选的节点类型列表(find_replacements 必需,例如 [“io/chat_input”];可传多个). |
execution_id |
string | — | null |
执行 UUID(get_execution 必需). |
definition |
object | — | null |
validate_workflow 要校验的草稿图：含 camelCase nodes[]（nodeId, nodeType）和 edges[]（sourceNode, sourcePort, targetNode, targetPort）的对象。提供 definition 或 workflow_id 之一。 |
verbose |
boolean | — | false |
list_node_types 详细程度:默认(false)每项仅返回 node_type/name/category,便于以极低 token 成本扫描全部节点类型;设为 true 时额外返回 description/version/is_tool_node.单个节点的完整信息可用 get_node_schema / list_ports 获取.不影响过滤,总数,分页,分类,候选或提示. 控件：switch |
sort_by |
enum | — | null |
list_workflows / find_workflows_by_node_type 的排序方式:created_at(降序,默认) / updated_at(降序) / name(升序,大小写无关) / node_count(降序).每种模式都带稳定的工作流 ID tie-break. 控件：select. 取值：created_at (创建时间降序（最新在前）——默认排序。), updated_at (更新时间降序（最近改动在前）。), name (名称升序，大小写无关。), node_count (节点数量降序。) |
execution_node_filter |
string | — | null |
仅 get_execution:对执行节点 ID 做大小写敏感的子串匹配.与 node_filter(模糊匹配已注册节点类型)不同.提供后会启用增强的逐节点记录和 matched_count. |
node_status_filter |
enum | — | null |
仅 get_execution:保留处于该状态的节点(waiting/ready/running/completed/failed/skipped).与 execution_node_filter 按 AND 组合.提供后会启用增强的逐节点记录和 matched_count. 控件：select. 取值：waiting, ready, running, completed, failed, skipped |
输出
| 字段 | 类型 | 说明 |
|---|---|---|
status |
string | 操作状态:ok / not_found / error. |
data |
any | 查询结果(JSON 格式). |
count |
integer | 当前页结果数量. |
total |
integer | 总数(过滤后,分页前). |
categories |
array | 排序去重的节点分类（list_node_types 无过滤时）。data 仍持有节点数组。 |
candidates |
any | node_filter 无匹配时最多五个排序的替换候选 |
hint |
string | 给 Agent 的可操作提示 |
truncated |
boolean | 当前页是否被 limit 截断.truncated=true 时用 offset=next_offset 继续翻页. |
next_offset |
integer | 下一页偏移量(仅 truncated=true 时返回). |
error |
string | 错误信息. |
导入工作流 — tools/import_workflow
将工作流注册为当前工作区的文件托管工作流。两种模式：(1) 结构化创建——传入 name + nodes[]（每个节点含唯一 ‘key’ 和 ‘nodeType’）+ edges[]（sourceKey/sourcePort/targetKey/targetPort）；工具会根据实时节点 schema 校验、生成所有 UUID，仅在校验通过后导入。(2) 传统导入——传入规范 V1 ‘content’。切勿将 ‘content’ 与结构化字段混用。文件写入成功不等于导入成功——仅本调用的结果为权威。
输入
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
workflow_key |
string | ✅ | — | 此工作流文件夹的稳定小写 kebab-case 标识 |
name |
string | — | — | 结构化创建：工作流显示名称（勿与 ‘content’ 混用） |
description |
string | — | — | 结构化创建：可选的工作流描述 |
nodes |
array | — | — | 结构化创建：nodes[]，每个含唯一 ‘key’、’nodeType’，可选 ‘name’/’position’/’config’。ID 由工具生成。 |
edges |
array | — | — | 结构化创建：edges[]，每个含 sourceKey、sourcePort、targetKey、targetPort |
content |
string | — | — | 传统导入：规范 V1 workflow.json 内容（勿与结构化字段混用） |
输出
| 字段 | 类型 | 说明 |
|---|---|---|
workflow_id |
string | 成功时解析得到的工作流 ID |
outcome |
string | 成功时的结果类型：created、updated 或 unchanged |
source_path |
string | 成功时存储的源文件路径 |
node_ids |
any | 结构化模式：按临时 key 生成的节点 ID 映射 |
validation |
any | 结构化模式：完整的校验报告（错误 + 警告） |
warnings |
array<string> | 非致命的提示信息列表 |
error_code |
string | 失败时的稳定错误码 |
error |
string | 操作失败时的错误信息 |
读取执行 Trace — tools/get_execution_trace
按 trace_key 从 session_store 读取完整执行 trace,供 LLM 按需展开查看
输入
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
trace_key |
string | — | null |
追踪检索键,从对话历史摘要获取(格式:session_id:turn) |
archive_ref |
string | — | null |
不透明的持久执行存档引用，取自对话历史中的 execution_record 标记 |
mode |
string | — | null |
查询模式：’summary’（计数和工具名）、’tool_calls’（每步调用、ID、状态、参数）或 ‘detail’（附加有界结果载荷）。用 tool_calls 询问’你用了哪些工具’。 |
输出
| 字段 | 类型 | 说明 |
|---|---|---|
content |
string | 完整的执行追踪内容(未找到时为空字符串) |
found |
boolean | 是否找到对应的追踪记录 |
unavailable_reason |
string | found=false 时的显式不可用状态：not_available、expired 或 forbidden。不可用记录不代表没有调用工具。 |
读取制品 — tools/read_artifact
按引用读取文本制品的有界字节/行窗口。仅接受制品引用——不接受原始文件路径——并返回分页续读信息。对于源快照制品，传入 snapshot_path 可读取清单中指定的一个文本文件。
输入
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
artifact |
object （端口） | — | null |
要读取的制品引用（唯一接受的来源）. 连接端口，不是表单字段。 |
start_byte |
integer | — | 0 |
字节模式：开始读取的字节偏移 |
max_bytes |
integer | — | 16384 |
本次窗口读取的最大字节数（默认 16 KiB，硬上限 1 MiB） |
start_line |
integer | — | null |
1-based 起始行号（启用行模式） |
max_lines |
integer | — | null |
行模式下读取的最大行数 |
snapshot_path |
string | — | null |
源快照内一个文本文件的清单相对路径（如 ‘src/main.py’）。仅当制品为源快照时有效。 |
输出
| 字段 | 类型 | 说明 |
|---|---|---|
content |
string | 本次窗口的有界纯文本内容 |
source_artifact |
object | 实际读取的制品 |
bytes_read |
integer | 已读字节数 |
total_bytes |
integer | 总字节数 |
truncated |
boolean | 窗口之外是否还有更多内容 |
next_offset |
integer | 下次分页读取的 start_byte 偏移（字节模式且已截断时存在） |
warning |
string | 非敏感的读取提示信息 |
error |
string | 操作失败时的错误信息 |
下一步
© 版权声明
文章版权归作者所有，未经允许请勿转载。
THE END
暂无评论内容