Authoring Workflows zh

编写工作流

工作流 spec 就是一个描述图的 YAML 文件。这页讲两条编写路径、文件结构和怎么让 spec 可复用。

路径一：让智能体写

最快的路。在会话里说：

"把这个存成可复用的工作流：审计依赖并给出升级顺序"

智能体用内置的 create-dag-workflow skill：先跟你确认阶段和门禁，把 spec 写进你选的作用域（项目 .opencode/workflows/ 或全局目录），然后真跑一次证明它能用。

临时图则用 workflow(action="draft")：你用结构化工具参数描述图，harness 渲染并校验出 YAML 文件，返回 spec_path。字段名错误在 provider 边界就被工具 schema 拒掉——根本到不了文件。

路径二：自己写 YAML

最小完整 spec：

title: Dependency audit
config:
  name: dependency-audit
  nodes:
    - id: inventory
      name: inventory
      worker_type: explore
      depends_on: []
      required: true
      prompt_template:
        id: config-explore
        input:
          target: "package.json files and lockfiles"

    - id: report
      name: report
      worker_type: general
      depends_on: [inventory]
      report_to_parent: true
      prompt_template:
        inline: "Flag outdated or duplicated dependencies in {{inventory}} and propose an upgrade order."

值得知道的非显然字段：

字段	用处
condition	基于上游输出的表达式；为假跳过节点，纯下游级联跳过
input_mapping	给模板重命名上游输出（count: "node-b.output.count"）
output_schema	JSON Schema；子智能体必须 submit_result 提交匹配结果
review	标记 design/diff 审查节点，指纹绑定实现
timeout_ms	节点级截止时间；排队等待也计入

或者用块——块会编译成节点，审查路由契约自动处理：

config:
  name: fix-a-defect
  objective: 复现、修复并验证报告的缺陷。
  blocks:
    - id: reproduce
      kind: debug
      instruction: 为报告的症状写一个红色测试。
    - id: fix
      kind: coding
      depends_on: [reproduce]
      instruction: 修复根因，让测试变绿。
    - id: verify
      kind: verify
      depends_on: [fix]
    - id: review
      kind: review
      depends_on: [verify]

命名与三个作用域

作用域	路径	可用范围
项目级	.opencode/workflows/<name>.yaml	本仓库，随仓库提交
全局级	<opencode 配置目录>/workflows/<name>.yaml	本机所有项目
内嵌级	编译进正式版二进制	兜底层

按顺序取第一个命中：项目遮蔽全局，二者都遮蔽内嵌。命名之后，一句"跑 dependency-audit 工作流"就能启动，不需要路径。

存盘 spec 必须守的规矩

• 不钉死模型——分层来自 dag.jsonc，永远不来自 spec。
• worker_type 必须存在于智能体目录。
• 模板必需变量必须给全（input 或 input_mapping），否则节点在 spawn 时大声失败——这是故意的。
• 全局工作流建议用 inline prompt，免得依赖某个仓库本地的模板文件。

报告文件

节点最终回复是一个绝对文件路径时，运行时捕获 {content_ref, size, sha256, summary}；workflow(action="result") 返回指针。写到 .opencode/workflow-reports/ 下的报告自动进 gitignore——首次写入时追加条目。长报告放文件里，别挤转录。