Architecture contract

Programs 四层代码结构

本页定义 openprogram/programs/ 中 Functions、Workflows 与 Applications 的代码所有权、依赖方向、发现方式和迁移验收。读者是实现注册器、Workflow 生成器、Programs 页面和打包流程的开发者。

状态：已实现并验证范围：源码、发现、导入、打包不包含：运行历史版本系统

1. 唯一目录合同

openprogram/programs/
├── functions/
│   ├── vanilla/       # 确定性的普通 @function
│   └── agentic/       # 使用模型能力的 @agentic_function
├── workflows/         # Agent 生成并可复用的 Python 小项目
├── applications/      # 可调用上述全部能力的完整应用，可包含 UI/assets
├── _registry.py       # 统一注册与发现
└── _programs.py       # Application 元数据与加载

所有实体代码都位于仓库内的 openprogram/programs/。不使用 ~/.openprogram/workflows/ 作为源码目录，也不保留 openprogram.programs.functions.agentic 兼容包。

2. 四类实体的职责

Functions / vanilla

确定性能力。使用现有 @function 注册，可被 Agentic Function、Workflow 和 Application 普通 import。

Functions / agentic

需要模型、Agent loop 或 Goal 的可调用能力。使用现有 @agentic_function，不引入新的装饰器。

Workflows

Agent 写出的可维护多文件 Python 项目。入口仍是 @agentic_function；Workflow 之间通过静态 import 和普通函数调用复用。

Applications

面向完整使用场景的应用，可调用 Vanilla、Agentic 与 Workflow，并可包含服务、配置、UI 与资源文件。

3. 依赖方向

ApplicationsFunctions + Workflows + UI

←

Workflows组合 Functions 或其他 Workflow

←

FunctionsVanilla / Agentic 基础能力

调用方	允许调用	禁止
Vanilla Function	标准库、批准的依赖、其他无环 Vanilla helper	依赖 Workflow 或 Application
Agentic Function	Vanilla Function、`llm()`、`agent()`、`goal()`	依赖 Application
Workflow	Vanilla、Agentic、其他无环 Workflow	字符串 dispatcher、隐式全局 Workflow 注入
Application	上述全部公开入口	修改被调用实体的源码或运行快照

4. Workflow 与 Goal / Agent / LLM

Goal以 Agent loop 完成有判定条件的目标

→

Agent基于 LLM 的多轮工具循环

→

LLM单次模型调用

三者仍由 openprogram/agentic_programming/ 提供，不移动到 Programs。Workflow 是最高层组合，可以直接调用其中任意一层，也可以在不同步骤组合多层；依赖顺序始终是 goal → agent → llm。

5. 发现与加载只有一套语义

阶段	合同
导入	`openprogram.programs.functions.vanilla` 导入 `vanilla` 与 `agentic`，触发现有装饰器注册副作用。
Agentic 扫描	注册器和 Web 函数列表只扫描 `openprogram.programs.functions.agentic`。
Workflow 路径	生成器以 `openprogram/programs/workflows/` 为唯一源码根，不依赖调用模块的父目录层数。
跨 Workflow 调用	静态 `from ... import ...` 加普通 Python 调用；不增加 `@workflow`、`call_workflow()` 或 `invoke_workflow()`。
Application	由现有 application catalog 发现；内部可按公开 Python 路径导入 Function 与 Workflow。

6. 失败、隔离与信任边界

情况	行为
旧路径 import	立即产生 `ImportError`，促使仓库内引用一次性迁移；不维护双路径。
缺失 Workflow 依赖	发布或执行前失败，报告具体静态 import；不在运行时猜测同名项目。
Workflow 环	在隔离 worker 启动前拒绝。
运行隔离	执行使用固定代码快照、同一 Runtime、权限、取消和 DAG caller；其他进程更新源码不改变当前 run。
Application UI	UI 与外部服务属于 Application 边界，不使 Functions 或 Workflows 获得额外权限。

7. 迁移验收

源码结构

新四层目录存在；旧 agentic_functions/ 不存在。

公开导入

仓库内代码与测试全部使用 functions.vanilla 或 functions.agentic。

注册发现

Vanilla 与 Agentic 工具数量、名称和 schema 在迁移前后保持一致。

Workflow

生成、发布、复用与项目根路径仍指向仓库内 programs/workflows。

打包

Wheel 与封装 App 包含新目录且不包含旧路径；App/Web/TUI 共用默认 18100 实例。

文档与技能

示例、CLI 帮助和 bundled skill 不再给出旧 import 路径。

8. 实现与验证记录

项目	实现证据	验证
目录迁移	Vanilla 与 Agentic 源码分别迁移到 `functions/vanilla` 和 `functions/agentic`；旧目录删除且无 alias。	四层仓库合同 3 项通过；旧模块 `find_spec` 返回空。
注册与发现	Programs import、Agentic registry、Web discovery、CLI 与源码编辑路由统一使用新路径。	迁移前后注册工具名称逐项一致；Programs 定向测试 939 项通过。
Workflow 根	`_workflow_projects_root()` 从 Programs package 根解析，不再依赖调用文件层数。	Workflow / 三层模型 / 控制流测试共 76 项通过。
跨仓库影响	三个 Applications 独立仓库不含旧 Programs import。	对 applications 全目录执行旧路径扫描，结果为空。
发布产物	Setuptools 自动发现新包；CJS package-data 路径迁移到 Agentic 新目录。	Wheel 同时包含四层入口，不包含 `programs/agentic_functions`。
回归与文档	仓库内 Python、测试、bundled skill、说明与设计链接同步迁移。	unit/component/contracts 5649 项初次通过；8 个失败修正或补齐环境后逐项通过；Ruff、链接检查与桌面/窄屏渲染通过。