Script Library Guide

Script Library 指南

何时用 inline，何时用 library

• 只服务一个 Workflow、与模板一起演进的脚本使用 inline，位于 data/workflows/{workflow_id}/script/{name}.{sh|py}。
• 被多个 Workflow 复用、需要独立说明的脚本使用 library，实例可写目录是 data/script-library/{group}/{name}/。
• Plugin 可提供只读 Script Library roots；修改它们必须回到 Plugin 源码。

涉及完整 Workflow 拓扑、变量和 Task 生命周期时同时加载 workflow-guide。

目录与身份

data/script-library/{group}/{name}/
├── {name}.sh        # 或 {name}.py，二选一
└── SCRIPT.md        # 推荐：说明用途、输入、输出、副作用和版本

group 与 name 只使用字母、数字、下划线或连字符。入口文件名必须与脚本目录名一致。 同一个 {group}/{name} 只能有一个 active owner；用户资源与 Plugin 资源重名会 fail closed， 不会按优先级静默覆盖。

Task 创建时会冻结 library 脚本的 owner、revision 与文件摘要。执行前再次核验；脚本或 Plugin revision 漂移时拒绝执行。因此更新脚本后要创建新 Task，不能期待旧 Task 自动采用 新内容。

Script 节点配置

新节点使用数组形式 script_argv：

{
  "node_type": "script",
  "node_params": {
    "script_source": "library",
    "script_type": "python",
    "script_group": "utils",
    "script_name": "normalize",
    "script_argv": ["--input", "{{source_file}}", "--mode", "strict"],
    "timeout": "300"
  }
}

• script_source 是 inline 或 library。
• script_type 是 shell 或 python，必须与真实入口一致。
• script_group 仅在 library 模式必需。
• script_argv 每项是一个完整 argv，变量中的空格、引号和 JSON 不会被 Shell 再拆分。
• script_args 只兼容历史定义，新建和修改不要使用。
• timeout 是正整数秒；根据真实最坏耗时设置，不用无限超时掩盖卡死。

引擎直接以 argv 启动，不经过 Shell。执行工作目录是 Workflow 共享 workspace。环境变量 包括 WORKFLOW_ID、TASK_ID、SCRIPT_DIR、WORKSPACE_DIR；Plugin owner 还可提供其 声明的运行环境。

输出协议

脚本通过 stdout 与 Workflow 交换结构化结果：

<WF_VAR>result_key:value</WF_VAR>
<script_out>给节点历史与下游摘要使用的短说明</script_out>

• 标签大小写必须完全一致。
• 每个 WF_VAR 的 key 使用稳定变量名；list/dict 值输出合法 JSON 双引号格式。
• 业务日志不要伪造协议标签。
• stdout/stderr 会截断，长产物写入共享 workspace，只输出路径与摘要。
• 退出码非 0、超时、入口缺失、身份漂移或协议解析错误都应视为节点失败。

管理 API

写 API 只写用户 root。读取 API 可解析 active user/Plugin roots。不要用 API 修改只读 Plugin 脚本；同名冲突时先解决 owner 边界。

SCRIPT.md 内容

说明至少包含：

• 脚本用途和不适用场景；
• script_type、argv 参数和必需环境变量；
• 读取与写入的 workspace 路径；
• WF_VAR 与 script_out 输出；
• 外部副作用、幂等性和重试风险；
• version 与 owner。

不要在说明或脚本中写 Secret；通过受控环境注入。

验证顺序

1. 列出 catalog，确认 owner、group、name 与 type 唯一且正确。
2. 在隔离 workspace 直接运行脚本，覆盖正常输入、空输入与错误输入。
3. 检查退出码、stdout 协议、stderr 和产物路径。
4. 创建新 Workflow Task，确认创建时身份冻结成功。
5. 运行 Script 节点，核对变量池、节点 summary 和下游消费。
6. 有副作用的脚本验证幂等性；不幂等时禁用自动重试或增加显式保护。

常见错误

• 目录叫 hello-world，入口却叫 hello_world.sh：入口必须与目录名相同。
• library 节点没填 script_group：解析失败。
• 更新脚本后运行旧 Task：身份守卫因漂移拒绝执行。
• 把 JSON 放进 script_args：Shell 拆分破坏参数，改用 script_argv。
• 从脚本目录写相对产物：当前工作目录是共享 workspace，不是 SCRIPT_DIR。
• 用户与 Plugin 定义同 ID：catalog 冲突，必须改名或停用 owner。