更新运行进度 `flow.progress`

进度节点把可检查的里程碑、数量和短说明写入运行历史。它适合批处理完成数、导入阶段和长任务状态，让控制面在运行没有结束时展示已确认进展。进度只提供观测信息，不替代决定后续分支所需的业务状态，也不会调用宿主任务。

进度字段

progress_id 是一次更新的稳定身份，通常使用图节点 ID。completed 表示已完成数量，total 可选且有值时不能小于已完成数量。message 用于简短说明当前里程碑，details 保存小型结构数据或对象引用。所有表达式都应读取已经持久化的数据，避免重放产生不同进度内容。

提交成功后，控制从 recorded 继续。相同 progress_id 不应写入彼此冲突的内容。需要多次上报时，可以给各里程碑使用不同稳定节点，或在受控循环中把明确的迭代身份带入进度键。高频细粒度遥测应写入指标系统，不能把每个字节或每个模型 token 都变成历史事件。

展示与验证

界面应说明进度来自最近一次已提交事件，并区分运行中、等待、失败和终态。测试要覆盖未知总量、零值、完成数超过总量、重复提交、进程恢复和大型 details。发布前还应确定进度保留策略、访问权限和本地化文案，确保操作者看到的数字能够对应真实业务单位。

用它写入可检查的运行里程碑、计数和短说明。进度不会调用宿主任务，也不会替代业务状态。

运行方式

节点 ID 绑定进度命令身份，progress_id 标识具体更新。提交后运行立即重放，并从 recorded 端口继续。

节点契约

类型: flow.progress
角色: 持久运行命令
运行绑定: record_progress
持久身份: 图节点 ID

配置属性

属性	类型与控件	默认值	规则
`progress_id`进度 ID	`str`StrInput	`progress`	同一进度项始终使用相同 ID。再次写入时会更新原记录。必填
`completed`已完成数量	`dict`A3SFlowExpressionInput	`{"apiVersion":"a3s.dev/flow-expression/v1","expression":{"op":"literal","value":0}}`	填写已处理的任务数、记录数或其他可计数单位。必填
`total`总数量	`dict`A3SFlowExpressionInput	`{"apiVersion":"a3s.dev/flow-expression/v1","expression":{"op":"literal","value":null}}`	知道总量时填写；留空时只展示已完成数量。可选 · 高级设置
`message`进度说明	`dict`A3SFlowExpressionInput	`{"apiVersion":"a3s.dev/flow-expression/v1","expression":{"op":"literal","value":""}}`	补充当前正在处理的内容，会显示在运行详情中。可选 · 高级设置
`details`进度详情	`dict`A3SFlowExpressionInput	`{"apiVersion":"a3s.dev/flow-expression/v1","expression":{"op":"literal","value":null}}`	需要程序读取更多信息时，可以附加 JSON 数据。可选 · 高级设置

端口

方向	端口 ID	种类	数据类型
输入	`in`进入	control	`FlowControl`
输出	`recorded`进度已更新	control	`FlowControl`

节点 JSON 示例

CLI 会用 manifest 默认值生成同样的节点结构。画布位置、标题和选中状态属于展示数据。

workflow.json

{
  "position": {
    "x": 320,
    "y": 160
  },
  "id": "example-flow-progress",
  "data": {
    "progress_id": "progress",
    "completed": {
      "apiVersion": "a3s.dev/flow-expression/v1",
      "expression": {
        "op": "literal",
        "value": 0
      }
    },
    "total": {
      "apiVersion": "a3s.dev/flow-expression/v1",
      "expression": {
        "op": "literal",
        "value": null
      }
    },
    "message": {
      "apiVersion": "a3s.dev/flow-expression/v1",
      "expression": {
        "op": "literal",
        "value": ""
      }
    },
    "details": {
      "apiVersion": "a3s.dev/flow-expression/v1",
      "expression": {
        "op": "literal",
        "value": null
      }
    },
    "type": "flow.progress"
  }
}

CLI 用法

先查看当前安装版本的 manifest，再创建节点并验证完整工作流。所有命令输出 JSON。

Terminal

a3s-flow node flow.progress --pretty
a3s-flow new flow.progress --id example-flow-progress --pretty
a3s-flow validate workflow.json --pretty
a3s-flow compile workflow.json --pretty
a3s-flow digest workflow.json --pretty

Skill 用法

安装包内附带 a3s-flow Skill。它会先查询 CLI 的节点清单，再创建、校验、编译并计算语义摘要。

Prompt

Use $a3s-flow to add the "flow.progress" node to workflow.json, connect valid ports, and validate the result.

CLI 用法 · Skill 用法

使用注意

同一个 progress_id 不要写入不同内容。
total 有值时应不小于 completed。
details 只保存小型结构数据或对象引用。

#更新运行进度 flow.progress

#进度字段

#展示与验证