编程模型 · 迁移计划

Agentic Function、Workflow 与 Skills 的固定边界

本页是实现分类和迁移的权威合同。目录只组织源码；装饰器注册函数才是运行实体。普通 Agentic Function 只允许一次模型调用，复杂编排全部归入 Workflow。

状态：代码已按目录分类落地 · 未标 Implemented范围：Programs 源码、注册、Skills 迁移、Programs UI不新增执行抽象

1. 固定结论

Vanilla Function

确定性 Python 能力，不调用模型，不启动 Agent，不创建 Goal。

模型调用次数 = 0

Agentic Function

Prompt 与少量确定性代码组成的单次模型能力，用于替代一部分第一方文本 Skill。

恰好调用一次 llm()

Workflow

包含多步控制流、Agent 工具循环、Goal、多次模型调用、文件副作用或持久化的组合。

复杂执行只放这里

Agent method 是现有注册装饰器，不等于“允许任意 Agent 行为”。公开 Workflow 入口目前仍可用它注册，但源码必须放在 workflow/ 或 programs/workflow/ 的 Workflow 分类中。分类依据是执行语义，不是装饰器名称。

能力	Vanilla	Agentic Function	Workflow
`llm()`	禁止	恰好一次	允许一次或多次
`agent()` / `goal()`	禁止	禁止	允许
模型工具循环	禁止	禁止	允许
确定性预处理、解析、校验	允许	允许	允许
多阶段控制流、checkpoint、持久副作用	禁止	禁止	允许

2. 当前实现需要重新分类

当前能力类型	目标分类	处理
纯文本分类、提取、总结、翻译、润色	Agentic Function	保留一个 `llm()`，允许确定性输入整理与输出校验。
PDF 图表/表格提取中的模型判断	Agentic Function	单次模型判断保留；无模型的 PDF 布局和文件 helper 下沉 Vanilla 或内部 helper。
`browser_agent`、`web_use`、docs question、security review、`goal`	Workflow	它们包含 Agent、工具循环、多阶段执行或 Goal，不得继续作为普通 Agentic Function 分类。
research pipeline、deep work 等复合流程	Workflow	保留组合结构；单个纯转换阶段可拆成 Agentic Function 复用。
word count、JSON、文件扫描、PDF layout helper	Vanilla / 内部辅助函数	不调用模型；只有需要公开调用时才注册为 Function。
交互示例、测试框架、恢复示例	测试或删除	不得作为产品 Program 出现在 Programs 目录。

不要用文件名、目录名或代码行数自动分类。实现者必须基于可达调用图判断模型调用次数、是否出现 agent()/goal()、循环和副作用。

3. 目标执行模型

Workflow 之间继续使用静态 Python import 和普通函数调用。运行注册、权限、取消、DAG caller 和 Runtime 沿用现有实现；本设计不新增 DSL、dispatcher、注册器或数据库。

4. Skills 的保留与迁移边界

来源	处理	原因
第三方或用户安装的 Skill	保留 `SKILL.md`、资源文件和现有加载机制	它们是可安装扩展格式，不应被仓库内 Python 迁移破坏。
第一方、纯 Prompt、一次模型即可完成的 Skill	逐个迁移为 Agentic Function	获得类型化参数、注册发现、测试和 DAG 记录。
第一方、含脚本/工具/多阶段状态的 Skill	迁移为 Workflow，或继续保留 Skill	不能为满足“一次模型调用”而删除必要控制流。
只提供说明文档和参考资料的 Skill	保留 Skill	按需加载的上下文资源不是运行函数。

迁移单位是单个 Skill。每次迁移必须先证明输入输出合同等价，再删除第一方旧入口；不进行全量机械转换，不改第三方安装协议。

参考框架对照与采用范围

参考	官方边界	OpenProgram 采用	不采用
OpenAI Agents SDK · 工具	普通 Python 函数可转为有类型 Schema 的 Function Tool；Agent 作为工具时产生嵌套 Agent 执行。	保留注册函数的类型化参数；把自主工具循环明确归入 Workflow。	不把每个 Agentic Function 都解释为 Agent。
LangGraph · 工作流与 agent	Workflow 使用预定代码路径，Agent 动态决定过程和工具使用。	Workflow 负责 Python 控制流，并可显式调用 `agent()`。	不新增图 DSL 或第二执行引擎。
Anthropic · Agent 技能	Skill 是按需加载的 `SKILL.md` 与可选脚本、模板和资源。	保留第三方、用户安装和资料型 Skill；只迁移第一方可执行能力。	不将所有 Skill 强制转换成 Python 函数。

5. 目标目录只表达源码分类

openprogram/programs/
├── functions/
│   ├── vanilla/                         # 0 次模型调用
│   └── agentic/
│       ├── document/                    # 单次模型的文档能力
│       ├── text/                        # 总结、翻译、改写、分类
│       ├── research/                    # 只放单次模型阶段
│       └── workflow/                    # Workflow 可复用的管理与运行支持
│           ├── search_workflows.py
│           ├── create_workflow.py
│           ├── revise_workflow.py
│           ├── resume_workflow.py
│           ├── errors.py
│           ├── _generation/             # 内部生成，不作为技能展示
│           ├── _project/                # 内部项目管理，不作为技能展示
│           ├── _runtime/                # 内部执行，不作为技能展示
│           ├── browser/
│           ├── docs_question/
│           ├── security_review/
│           └── goal/
├── workflows/                           # 可直接运行的完整 Workflow
│   ├── auto_workflow.py                 # 内置自动选择、创建与执行流程
│   └── <workflow-project>/             # 生成、发布、复用的 Git 项目
└── applications/

目录节点只用于导航。入口文件、helper 和子目录按常规 Python 代码组织，需要独立职责时才拆文件。禁止预先创建空的 runtime.py、legacy.py 或一函数一目录；Programs 只显示实际文件夹路径和已注册函数。

6. 交给实现者的五个独立任务

冻结分类合同

新增静态合同测试：Vanilla 的可达调用图不得触达模型；普通 Agentic Function 恰好触达一次 llm()，且不得触达 agent()/goal()；Workflow 分类不受此限制。

RED：先让当前 browser/docs/security/goal 错误分类被测试捕获。

整理真正的 Agentic Functions

按 document、text、research 等真实职责归类。保留确定性预处理/后处理；无模型 helper 下沉 Vanilla 或模块内部。Registry 名称、Schema 和公开调用方式不得因移动改变。

Gate：注册清单前后等价；所有 Agentic Function 满足一次 llm 合同。

把复杂能力移入 workflow 分类

迁移 browser/web、docs question、security review、goal、deep work 和复合 research。只移动代码所有权和 import，不引入新运行时；具体目录按子系统组织。

Gate：调用图显示真实入口和依赖；目录本身不成为 Program。

逐个处理第一方 Skills

建立清单并标记 keep / agentic / workflow。纯 Prompt 单次能力迁移为 Agentic Function；复杂流程迁移为 Workflow；第三方和用户 Skill 不动。

Gate：每个被删除的第一方 Skill 都有参数、输出和失败语义等价测试。

删除演示和无职责结构

将 interaction demo、test framework、resume demo 移至测试或删除；清除空目录、空入口和无调用方 helper。不要保留兼容 alias，除非存在真实外部公开合同。

Gate：Programs 页面无演示项、无空目录、无 helper 假实体。

7. 验收与完成条件

分类合同

Vanilla = 0 次模型；Agentic Function = 1 次 llm()；复杂执行 = Workflow。

目录展示

Programs 按实际文件夹路径显示；不展开成伪目录，不显示空目录和 helper。

运行身份

只有 Registry 中的函数可运行；移动文件不改变名称、Schema、exposure 或 execution ID。

技能

第三方/用户 Skill 保持兼容；第一方迁移有逐项清单与等价测试。

架构限制

没有新增 @workflow、call_workflow()、DSL、第二注册器或第二 Runtime。

产品验收

默认 App Programs 树无空项，函数详情调用图来自所选函数的实际可达调用。

最低验证：分类合同测试、Programs discovery/graph 测试、相关 unit/component tests、Ruff、Web typecheck、文档链接检查和 git diff --check。默认 App Programs 树仍需在 /Applications/OpenProgram.app 上确认后，才能把本页改为 Implemented。

工作流包导入

from workflows.NAME import NAME 在活动目录中引用同一个已授权公开 callable；snapshot 执行显式拥有自己的 workflows namespace，保持固定依赖版本。包内 helpers 使用相对 import，运行依然是普通 Python 函数调用。人工和生成包的发布都经过结构验证与强制沙箱行为测试，详见 Workflow 包合同。