Skip to content

输入契约

Workflow Builder 的业务输入位于业务根目录下的 input/。该目录由用户维护，Makefile 在启动时复制到构建工作区的 workspace/input/。复制后的工作区输入是本次运行快照，修改源输入后需要重新启动相应流程才能保证一致。

必需结构

1
2
3
4
<business-root>/
└── input/
    ├── guide.md
    └── test_input/

guide.md 是唯一固定需求入口。test_input/ 必须是目录，可以包含多个文件和子目录；其中内容应代表一个最小但完整的真实业务案例。

guide.md 应包含的内容

  1. 工作流目标和明确不做的事情。
  2. 每种用户输入的路径、格式、必选性和限制。
  3. 每种公开输出的路径、格式和验收条件。
  4. 期望工具的阶段、参数、结果、异常和示例。
  5. 期望 Checker 的检查对象、证据、通过和失败条件。
  6. 运行环境、Python 依赖和系统依赖。
  7. 用户文档和开发者文档要求。
  8. 是否需要独立评估流程、增量流程及专业知识目录。

需求不应预先要求用户生成 testbench、配置、Checker 或工具源码；这些是工作流应自动生成的能力。用户提供的是业务代码、描述、验证需求、素材和专业知识。

test_input 设计

样例必须覆盖主路径，又不能大到拖慢每次回归。文件名、扩展名和目录层级应与未来 input/<TARGET>/ 一致。若真实业务允许可选文件，样例和需求都要说明缺失时的行为，避免生成 Checker 把所有可选项强制化。

二进制素材应采用可公开的小文件，文本使用 UTF-8。不要放 Token、私有证书、客户数据、超大媒体或依赖外网才能解释的链接。

res 专业知识

评估和增量使用的用户专业知识位于构建工作区 res/，不是源 input/ 的替代。典型内容包括领域验收规则、已知工具限制、组织规范和用户判断。初始化程序会创建结构化文件，Agent 只能读取或通过允许的结构化工具访问，不能伪造用户知识。

输入变更

构建中途修改 guide.md 会导致需求清单、计划和已生成 spec 不一致。重大变更应停止当前运行、保存需要的报告，然后使用干净工作区重新构建。小的修复需求在工作流已经生成后，优先通过用户 suggestion 和增量流程处理。

输入自检

1
2
3
test -f <business-root>/input/guide.md
test -d <business-root>/input/test_input
find <business-root>/input -type l -print

不建议输入包含指向业务根目录外的符号链接。需求中的示例路径应使用相对业务路径，不写某台机器的绝对路径。

推荐需求模板

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# <业务名称>工作流需求
## 用户目标与不做事项
## 输入文件契约
## 公开输出契约
## 处理阶段和数据流
## 工具需求
## Checker 与验收证据
## 环境和依赖
## 用户文档与开发者文档
## 评估、增量和专业知识

每种文件契约应说明相对路径、格式版本、编码、顶层结构、必选字段、允许大小和错误处理。目录输入要说明是否递归、允许扩展名、排序规则和空目录行为。二进制输入要说明解析库和损坏文件行为。

工具需求不是要求用户编写源码，而是说明业务能力。Checker 需求说明用什么证据判定，而不是只写“检查结果”。母工作流首阶段要把这些内容扩展为实现级计划；保守推断必须记录为设计决策，不能伪装成用户明确要求。

res/ 中的领域要求要标明适用范围和来源。评估 Agent可以读取，但不能修改为有利于自己的结论。运行开始后建议记录 guide.md 和样例树 revision；构建中途输入改变时，应停止并选择重建或后续增量。