#a3s-flow CLI

a3s-flow 随 @a3s-lab/flow-ui 发布。它读取包内同一份节点 manifest，因此命令行、网页节点卡片、配置面板和文档使用一致的字段、端口与默认值。CLI 只处理工作流文档和标准输入输出，不连接模型服务，不读取凭据，也不替宿主执行任务。

#安装与确认

npm install @a3s-lab/flow-ui @a3s-lab/ui
npx a3s-flow help --pretty

第二条命令应返回 ok 为 true 的 JSON，并列出 nodes、new、validate、compile 和 digest。如果终端找不到命令，先确认依赖安装在当前项目，再通过 npx 或项目脚本调用本地二进制。

项目脚本可以直接调用本地二进制。

{
  "scripts": {
    "flow:check": "a3s-flow validate workflow.json --pretty"
  }
}

所有命令都输出 JSON。退出码 0 表示命令成功，退出码 1 表示工作流结构或节点配置没有通过校验。参数、文件读取或 CLI 调用本身有问题时，进程以 2 退出。自动化脚本应同时检查退出码和输出中的 ok 字段。

#命令清单

--pretty 让输出便于阅读。--output <file> 把 JSON 写入文件。文件参数使用 - 时从标准输入读取。--include-internal 仅用于 nodes 和 node，它会显示容器内部的 iteration-start 与 loop-start，这两个类型不能通过 new 作为公开节点创建。

#查询与创建节点

先查目录，再查目标节点，最后创建带稳定 ID 的实例。

a3s-flow nodes --pretty
a3s-flow node flow.hook --pretty
a3s-flow new flow.hook --id approval --pretty

node 输出是字段和端口的事实来源。编辑器或脚本不应自行拼写字段名、枚举值和连接句柄。new 会填入 manifest 默认值，并保留运行所需的数据结构。节点 ID 在运行创建后属于持久身份，修改它可能让历史中的步骤、Hook、进度或子运行无法对应到新图。

#生成工作流样例

a3s-flow sample --output workflow.json --pretty
a3s-flow validate workflow.json --pretty

样例只注册图结构，不会执行 task.run。宿主需要提供同名任务处理器，再选择事件存储、调度器和 worker。把样例用于新项目时，应先修改工作流名称和节点 ID，再开始创建真实运行。

#校验、编译与摘要

每次修改语义字段或连线以后，按下面的顺序运行。

a3s-flow validate workflow.json --pretty
a3s-flow compile workflow.json --output workflow.plan.json --pretty
a3s-flow digest workflow.json --output workflow.digest.json --pretty

校验会检查文档外壳、节点类型、字段约束、端口连接、重复 ID、悬空边、自环、普通环路和容器作用域。编译成功说明顶层图以及每个遍历或循环子画布都有稳定顺序。摘要会忽略画布位置、标题、说明和选择状态，但会绑定影响执行的节点配置与连线。宿主需要完整性固定值时，应把摘要保存在发布记录中，不要反写进工作流文档。

#标准输入与 CI

git show HEAD:workflows/order-review.json |
  a3s-flow validate - --pretty

CI 中建议先运行校验，再把编译计划和摘要作为构建产物保存。失败输出中的每个问题都包含 code、path 和 message。修复应落在对应字段或边上，不要删除未知扩展字段来绕过错误。工作流来自外部来源时，还应审查任务名称、运行入口、公开回调和宿主绑定，CLI 不替代权限与凭据审核。

#自定义节点边界

CLI 只携带官方内置 registry，也不会加载宿主应用模块。包含自定义类型的文档会收到 flow.node.unknown_type，项目不应关闭这项检查。使用自定义节点的项目需要提供类型化发布命令，导入项目 catalog，再调用 compileA3SFlowWorkflowDagForPublication。自定义节点列出了注册与发布契约。

#常见错误

unknown_node 说明当前安装版本没有这个公开类型，先运行 nodes 核对清单。flow.node.internal_scope_required 说明内部入口离开了匹配容器。图校验问题通常来自错误端口、跨作用域连线或回边。字段问题会指向 workflow.graph.nodes 下的具体节点数据。

文件读取失败时，先检查命令所在目录和传入路径。标准输入一直等待时，说明上游命令还没有关闭输出，可以先把文档写入临时文件再单独运行校验。修复完成后重新执行校验、编译和摘要，最终计划应与准备发布的文档来自同一次检查。