Programs 代码结构

1. 唯一目录合同

openprogram/
├── agentic_programming/
│   ├── llm.py                  # 单次模型调用原语
│   └── agent.py                # 带工具调用的 Agent 循环原语
└── programs/
    ├── tools/                  # 确定性、可直接调用的工具
    │   ├── files/  web/  code/  planning/  ...
    ├── workflow/               # 所有模型推理、Agent 编排和复合能力
    │   ├── auto_workflow.py    # 单文件完整 Workflow，不建同名空目录
    │   ├── goal/               # 唯一 Goal Workflow 与会话 Goal 机制
    │   │   ├── __init__.py
    │   │   ├── goal.py         # 公开入口 goal()
    │   │   ├── command.py      # /goal 命令适配
    │   │   ├── judge.py        # 完成条件判定
    │   │   ├── refinement.py   # 目标规格与验收清单
    │   │   ├── loop.py         # 唯一循环的状态迁移、重试与停止规则
    │   │   ├── state.py        # 同一 GoalRun 的持久状态与事件
    │   │   └── notices.py      # 会话状态通知
    │   ├── browser/  document/  research/  ...
    ├── packages/               # 提供可调用能力的独立程序包
    ├── _registry.py            # 统一注册与发现
    └── _programs.py            # Application 来源与安装元数据

2. 三类 Program

3. 基础原语与 Workflow

4. Goal 只有一个执行函数

4.1 实现与验证记录

本节只记录已审查的实现证据，不改变上方的设计合同。

5. 文件与目录的选择

不为形式统一而给每个 Workflow 创建同名文件夹。文件数量与职责边界决定是否拆包。

6. 允许的依赖方向

7. 注册与 Programs UI

8. 一次性迁移验收

9. 不引入的设计

源码、注册表、Programs explorer 与 /goal 均按本页目录合同加载。公开名称和 Schema 不因源码移动而改变。

已安装 Wiki 的提示词字段替换

已安装 wiki_agent 的生成与 enrichment 提示词只替换已声明的内容字段。alert-{info|warning|success|error} 等 CSS 示例在 Python 格式化后完整保留，不作为替换字段。默认提示词不因示例花括号抛出格式化异常，ingest 与 enrich 继续执行既有模型调用和自有 vault 操作。修复仅转义原提示词中的两处字面量，保留 Wiki 的生成、slot、Git 和索引机制。公开验收分别调用两个动作的真实注册入口，在受控生成处核对示例未变，并验证自有页面和 slot 写入。提示词字面量修复已通过独立规格和质量审查，并导入本地包。组合源码与已安装界面验收分别记录。

工具参数的动态 mapping

工具的 canonical schema 区分调用时才确定键名的 mapping 与声明固定字段的对象。公开 program.args 接受已注册程序合法的关键字参数，包括 task。匿名 object mapping 与 Python dict/Mapping 注解保留开放键名及已声明的值类型。含 properties 的对象，包括显式空字段集合，保留固定字段限制。显式 additionalProperties: false 不会被打开；nullable mapping 保留原有 null 语义。本次不额外关闭既有隐式开放的顶层参数对象。

共享 provider schema adapter 不得把开放 mapping 转成只能为空的关闭对象。OpenAI function calling 要求 strict 模式使用关闭对象，并说明 Responses 通过显式 strict: false 保留非 strict 行为。因此动态 mapping 工具在 Responses、Codex 与 Chat Completions 中显式使用该标志；可兼容的固定字段工具继续 strict。Anthropic strict tool use 同样逐工具启用 strict 验证；mapping 工具保留普通 input schema，不设置 strict 标志。原 provider 可用性、认证、请求级能力开关和其他 schema dialect 不变。

验收在自有 session 中调用真实公开 schema、生产本地 validator 和注册程序 consumer。合法 task 参数到达 consumer；未知程序和 child 不支持的关键字保留现有错误，mapping 的错误类型或值仍无效。生产 provider payload 保留动态 mapping，同时关闭对象的 companion 工具继续 strict。固定 execute_code schema 保持 strict，不给它新增动态参数。测试包括固定对象额外键拒绝、nullable 与 typed nested mapping、不修改输入、受影响 provider/program 测试与 repository contracts。现有 live session、App、worker 和用户 state 不参与受控测试。

实现状态：canonical 设计已完成；实现、独立 SPEC、不同作者 fresh QUALITY 与单独安装验收仍待完成。