拆分 Workflow 的发现、创建、修订与执行

1. 设计结论

工作流参数归属

用户提供任务、证据和交付要求。执行参数归工作流管理，不通过高级选项、设置对话框或参数提问暴露给用户。

工作流有多个依赖任务的参数时，在执行前发起一次不带工具的模型请求，生成完整计划。提供真实运行时能力与应用限制，验证每个字段及跨字段约束；输出无效或规划失败时应用完整回退方案，并传播取消。固定不变量仍由代码控制，模型不得修改权限、凭证或应用上限。在可恢复工作开始前持久化生效计划，恢复时复用。

规范开发示例、参数契约和验收清单位于 工作流编写。缺失任务事实时可以澄清，但不得将执行调优交给用户。

2. 当前实现与已确认缺口

本设计复用已有的 Workflow package、Git、snapshot、checkpoint、DAG caller 和取消状态设施；不引入第二个执行Runtime、图DSL、Workflow数据库或字符串dispatcher。

代码分类与运行身份

Python目录只负责源码组织，运行身份只来自注册信息。两者不得互相推导：目录名不能自动成为Program，移动文件也不能自动改变公开函数名。

openprogram/programs/workflow/
└── workflow/                         # 分类目录，不可运行
    ├── __init__.py                   # 可放入口与共享实现
    ├── <helper>.py                   # 仅在确有独立职责时创建
    └── <subsystem>/                  # 需要时继续按职责分类

Registry / Programs 展示的运行实体：
  search_workflows
  create_workflow
  revise_workflow
  auto_workflow

不产生运行实体：
  workflow
  __init__.py
  任意 helper 文件
  任意内部子目录

3. 目标架构与两条主路径

Chat Agent 决策顺序

1. 已加载的Program或Workflow明显匹配：直接调用，不先搜索。
2. 可能存在未加载的动态Workflow：调用 search_workflows。
3. 完整匹配：直接调用候选的固定revision。
4. 只有部分能力：一次性任务可直接组合调用；需要复用、恢复、定时或稳定结构时调用 create_workflow。
5. 没有匹配：普通一次性任务仍可由Agent直接使用工具完成；用户明确要求复用资产或任务具有稳定重复结构时才创建。

4. 公共能力合同

{
  "action": "reuse | create",
  "workflow_id": "research_report",
  "workflow_revision": "<immutable git revision>",
  "result": {},
  "run_id": "<workflow run id>"
}

auto_workflow 的返回值必须说明选择了复用还是创建。搜索、创建和执行分别生成DAG子节点，不能只留下一个无法解释的总节点。

5. 搜索、组件复用与创建

唯一package合同与人类作者入口

Agent author与人类作者使用同一静态validator。新项目只能采用 pyproject.toml + README.md + __init__.py + workflow.py + tests/test_workflow.py + helper 的package格式；legacy entry.py不属于新authoring。CLI第一阶段提供 openprogram workflows validate <directory>，只读返回结构、metadata、AST、import、入口和依赖import形状诊断；依赖缺失、循环与revision pin仍由create/revise发布阶段检查。--json提供稳定脚本输出。create/revise在发布前调用同一candidate validator，不维护第二套规则。

搜索合同

搜索以catalog metadata和固定Git HEAD为输入，只做确定性文本召回，再把候选合同交给调用它的Agent判断。Chat路径由Chat Agent判断；手动auto路径由其内部唯一的可见selection Agent判断。搜索结果不是执行许可；权限、输入Schema和side effects必须随候选返回。

{
  "workflow_id": "web_research",
  "revision": "<git revision>",
  "retrieval_score": 4,
  "matched_terms": ["web", "research"],
  "input_schema": {},
  "output_schema": {},
  "permissions": ["network"]
}

创建时复用组件

create_workflow 获得可用Workflow的只读快照和公开Program目录。生成项目通过普通Python import引用Workflow package，不复制依赖源码；manifest固定每个依赖revision，并在发布前拒绝循环依赖、缺失入口和未声明权限扩张。

research_report/
├── pyproject.toml
├── README.md
├── workflows/
│   └── research_report/
│       ├── __init__.py
│       ├── collect.py      # imports web_research
│       └── synthesize.py
└── tests/
    └── test_research_report.py

6. 生命周期、失败与信任边界

边界要求

• authoring写入仅限本次candidate和run state；网络、凭据和外部工具遵循当前会话权限。
• 同一目标Workflow发布必须串行；不同项目可以并行。运行snapshot不受并发发布影响。
• 取消、权限拒绝、timeout、provider terminal error和外部Stop不进入repair。
• 调用表单继承会话顶部Project；不提供第二个工作目录覆盖项。
• 本地App刷新检测到活动run时拒绝刷新，不能通过重启把运行状态改写为失败或取消。
• 旧 code.py、legacy snapshot和历史run只读恢复；新调用不再产生旧格式。

7. 官方框架对照

对照只用于确定边界，不把其他框架的Runtime或DSL引入OpenProgram。下表的“未覆盖”表示所列官方页面没有定义自动生成并发布持久Python Workflow的完整产品合同。

采用、修改与拒绝

8. 实施计划

每个阶段独立提交，并依次经过公共RED、最小GREEN、规格审查和质量审查。前一阶段未通过两类审查时不进入下一阶段。现有 tests/component/agent/test_agentic_workflow.py 锚定单体入口，各阶段必须同步迁移对应测试归属，避免最后删入口时测试整体失效。

最小文件边界

9. 公共验收矩阵

10. 实现状态

参数归属是设计要求，并有开发示例。现有工作流需逐个采用；Goal 当前自动选择推理强度，其他设置保留默认值。本文不将全目录的完整参数规划标为已实现。

Phase 0–6 的源码实现、组件回归、CLI公共路径、文档构建与两类独立复审已完成；强制sandbox行为测试门和默认App真实验收仍待完成。

11. 明确排除

• 不新增 @workflow、图DSL、第二个Runtime、字符串 call_workflow() dispatcher。
• 不自动把所有用户消息转成Workflow，也不为一次性任务默认创建项目。
• 不自动修改已发布Workflow，不在普通执行错误后隐式发布revision。
• 不建立Workflow数据库、后台Git轮询、远程push、Marketplace或远程依赖解析。
• 本阶段不实现scaffold、人工publish命令、catalog状态目录迁移或执行未信任测试；这些分别进入后续任务。
• 不改变Agent、Program和Workflow现有Python调用语义；本设计只拆入口与生命周期。

可迁移工作流包契约

工作流是位于以下目录的自包含 Python 包： openprogram/programs/workflow/<workflow_id>。移动 OpenProgram 检出目录时，公开函数名与包相对位置保持稳定。包元数据、导入、依赖版本、UI 链接和调用请求不得包含开发者主目录。

编写与发布生命周期

正式手动接口为 openprogram workflows validate DIRECTORY, openprogram workflows test DIRECTORY，以及 openprogram workflows publish DIRECTORY。Validate 只读。Test 将验证后的候选和固定依赖复制到临时工作区，在必需的操作系统沙箱中运行测试，禁用网络、不含凭证、保护源文件并限制进程寿命。手动发布与生成式 create/revise 入口共用同一个必需的行为测试检查。Publish 对实际提交的快照重新验证和测试，不信任旧成功报告。现有包要求显式提供 --replace ，且目标目录干净。失败、超时、沙箱不可用或测试失败时均不发布。

文档中的 from workflows.NAME import NAME 导入与实时目录中的 openprogram.programs.workflow.NAME 解析到同一获授权可调用对象。实时别名仅暴露命名且获授权的入口。快照执行明确管理自己的 workflows 命名空间并持续加载固定内容，不回退到实时目录。包 README 说明用途、输入、输出、影响、失败/取消行为、依赖、测试与可复现调用。

验收

• 登记后移动检出目录，无需编辑包元数据或逐包路径即可发现并解析同一获授权工作流。
• 从失效的检出目录前缀恢复已登记的周报包，不授权无关目录。
• 拒绝路径穿越、未知作用域、未授权包和歧义解析；保留显式安装的外部源。
• 默认已安装 App 中显示原有 weekly_report 收藏，点击“使用”打开任务表单；验收期间不执行或提交报告。
• 英文编写指南与中文译文规定相同的创建、验证、发布、迁移和故障排查行为，命令已对照 CLI 核实。

实现状态

带作用域的源码持久化、获授权旧路径迁移、已安装目录导入和共享表单启动已通过独立规格与质量审查。手动测试/发布、文档化导入别名与编写文档也通过独立审查。全仓验证尚未完成，不代表完整测试集通过。已安装 App 验收与部署记录在发布证据中。