运行环境扩展#

程序包显示在 能力 → Programs → Packages。Tools 和 Workflows 是可调用能力，软件 Applications 由独立页面管理。新克隆使用 programs/packages/；已经登记在 programs/applications/ 的源码保留原位置和调用名，升级、卸载使用登记位置。分类改名不会重新下载或移动源码。

harness（一个 agentic program）是一个自包含的、由 agentic function 组成的 git 仓库。每个受支持的 release 已经包含 GUI、Research、Wiki 三项第一方 Program package 与受支持的 runtime 资产。GUI package 不包含 PyTorch、OpenCV 或 EasyOCR，具体边界见下文。openprogram programs install 用于额外第三方 Program 或开发者 source overlay，不是补齐 release 安装的步骤。 immutable product runtime 拒绝原地安装、升级和卸载 Program。

agent 在哪里读取本文档： 本文件是规范流程。 当用户要求安装某个 agent 尚未拥有的 harness 时，请遵循 下面的步骤——它们被写成可逐步执行的形式。

主要行为#

# 第一方 Programs 已经存在：
openprogram programs available

# 在可变扩展或开发环境中增加第三方 harness：
openprogram programs install https://github.com/<owner>/<Harness-Name>
openprogram programs install <owner>/<Harness-Name>     # GitHub 简写

# 管理：
openprogram programs available             # 状态，含第三方
openprogram programs uninstall <Harness-Name>   # 第三方：按目录名
openprogram programs install <ref> --upgrade    # git pull + 重新解析依赖

# ……重启 OpenProgram。完成——函数会自行注册。

第一部分 —— 使用 harness#

programs install 做了什么#

对于第三方 Program 或开发者 source overlay，该命令执行四个步骤：

1. 浅克隆（shallow-clone） 仓库到 openprogram/programs/packages/<Repo-Name>/——一个真实、可编辑的 目录（不是 site-packages）。该克隆被 OpenProgram 加入 git-ignore， 因此它始终是一份独立的检出（checkout），你可以 git pull 或就地编辑。
2. 安装 harness 自身声明的依赖——harness 是自描述的：会安装其 pyproject.toml/setup.py（优先）或 requirements.txt。OpenProgram 不携带任何按 harness 维护的 依赖清单。
3. 校验契约（contract）——克隆中必须包含一个带有 agentics/__init__.py 的 package（见第二部分）。不匹配的仓库会被 报告并直接不注册；它绝不会破坏加载过程。
4. 登记owner批准的来源。 下次启动时，registry只导入已登记的 <package>.agentics， Agent method 装饰器触发，函数随即出现在 chat / Programs 页面 / openprogram programs run 中。

防护机制：对于已存在的 dev symlink，install会校验Harness契约并登记该链接， 但不修改链接目标；同名且不是Git克隆的目录仍会被拒绝。对symlink执行uninstall 只删除链接，不删除它指向的检出。

第一方 Programs（gui / research / wiki）#

release 用户不执行 programs install all、首次启动 Program wizard 或 GUI harness 资产 installer。开发者可以用 editable checkout 替换第一方 Program， 或配置不同的 OCR/Browser backend；这些 overlay 增加开发行为，但不改变 product manifest。

第三方 harness#

任何人的 harness 仓库都用同一条命令安装——无需编辑目录清单， 任何地方都无需注册步骤：

openprogram programs install https://github.com/<owner>/<Harness-Name>
openprogram programs install <owner>/<Harness-Name>   # GitHub 简写
openprogram programs install file:///path/to/checkout # 本地 git 来源

openprogram programs available 会列出已安装的第三方 harness 及其契约状态；openprogram programs uninstall <Harness-Name> 按克隆目录名移除其中一个。

python -c "from openprogram.programs._programs import packages_dir; print(packages_dir())"

git clone <repo-url> /path/to/Harness-Name
openprogram programs install file:///path/to/Harness-Name
# 重启 OpenProgram

开发者配置（开发你正在编写的 harness）#

把你的工作检出做成 symlink，而不是克隆一份副本：

ln -s /path/to/your/Harness-Checkout "<PACKAGES>/Harness-Checkout"
openprogram programs install file:///path/to/your/Harness-Checkout

编辑会在下次重启时生效；programs install 会拒绝覆盖该链接， 而 programs uninstall <name> 只会移除该链接。（Windows 注意： symlink 需要开发者模式——在那里受支持的路径是克隆一个真实目录。）

校验一次安装#

openprogram programs available     # 安装状态（第一方与第三方）
openprogram programs list          # 所有已注册的函数

要查看一个存在但损坏的 harness 为何未加载：

OPENPROGRAM_DEBUG_REGISTRY=1 openprogram programs list

（Windows PowerShell：$env:OPENPROGRAM_DEBUG_REGISTRY=1; openprogram programs list）

然后就可以使用它——harness 的函数像任何内置函数一样可调用 （在 chat 中，或 openprogram programs run <fn> -a key=value）。

平台说明#

• 受支持的 CLI/server release 主机包括 macOS、Linux 和 Windows x86_64/arm64。 Windows Desktop 同时支持两种架构；Windows 沙箱命令执行使用可选的 WSL2 与 bubblewrap。
• 这些 Program 命令需要可变环境。 source-development checkout 可以使用； CLI release 仅在对应 release notes 明确支持 Program mutation 时使用。 packaged desktop 在 Program 拥有隔离的外部环境前会拒绝这些修改命令。
• 受支持的可变环境无需 symlink——安装器默认会把真实 checkout 登记到 <PACKAGES>。
• harness 在自身代码中仍可以是平台相关的（例如，桌面 GUI harness 可能只实现 macOS / Linux 后端）。 在受支持主机上能否安装、每个函数能否运行，取决于 harness 声明的依赖和 平台支持；需要检查它的 README。
• 编码 / 路径： OpenProgram 自身的工具链全程基于 UTF-8 和 os.path；一个表现良好的 harness 也应如此。

故障排查#

第二部分 —— 编写你自己的可安装 harness#

任何满足某一布局契约的仓库，都会成为每个 OpenProgram 用户的 一键安装项。

契约#

<Harness-Name>/                      ← 仓库（任意名称）
├── pyproject.toml                   ← 只声明 harness 自身的依赖
└── <package>/                       ← 一个可导入的 package（ascii 名称）
    ├── __init__.py                  ← 保持依赖轻量
    └── agentics/
        └── __init__.py              ← 暴露 PROGRAM_ENTRIES = [...]

注册的入口点是 agentics 子 package——在启动时 OpenProgram 导入 <package>.agentics；该次导入会触发 Agent method 装饰器，它们自行注册到共享的 registry 中。harness 根目录也可以附带（vendor）其他 package—— 发现机制会找到带有 agentics/ 子 package 的那一个，并将 harness 根 放到 sys.path 上，于是 harness 自身的绝对导入 （from <package>.foo import bar）就能解析。

最小可用模板#

# <package>/agentics/__init__.py
from openprogram import Agent




PROGRAM_ENTRIES = [my_tool]

class ExampleAgent(Agent):
    method_options = {
        'my_tool': {'tool': True},
    }

    def my_tool(self, text: str = "") -> str:
        "一行：说明它做什么（会显示在目录中）。"
        return text.upper()

_example_agent = ExampleAgent()
my_tool = _example_agent.my_tool

# <package>/__init__.py
"""我的 harness —— 保持本导入轻量（见硬性规则 2）。"""

# pyproject.toml
[project]
name = "my-harness"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = []          # harness 自身的依赖——绝不要写 openprogram

这就是一个完整的可安装 harness。

两条硬性规则#

1. 绝不要把 openprogram 声明为依赖（无论在 pyproject.toml 还是 requirements.txt 中）。harness 在一个已存在的 OpenProgram 安装内运行；一条声明的 openprogram @ git+… 会让 pip 从 git 重新安装 host，从而覆盖用户本地的（通常是可编辑的）安装。

2. 保持顶层 <package>/__init__.py 依赖轻量，并在 agentics/__init__.py 中为重量级导入做保护。 发现机制在每次启动 时都会导入 <package>.agentics，包括在那些尚未安装你的可选/重量级 依赖的机器上——顶层导入 cv2/torch/等会破坏整个 registry 的加载。 把重量级模块在函数体内做惰性导入，并为入口导入做保护：

   # agentics/__init__.py —— 缺少依赖的机器不能破坏加载
   try:
       from my_package.main import my_tool
       PROGRAM_ENTRIES = [my_tool]
   except ImportError:
       PROGRAM_ENTRIES = []
   

三个第一方 harness 都遵循这一确切形态——把它们中的任何一个 当作可用模板来阅读。

发布前在本地测试#

安装命令接受 file:// 来源，因此可以针对你的本地检出测试完整的 用户流程：

cd /path/to/My-Harness && git add -A && git commit -m wip
openprogram programs install file:///path/to/My-Harness
openprogram programs available        # 应显示：My-Harness [ok] (package: …)
OPENPROGRAM_DEBUG_REGISTRY=1 openprogram programs list   # 函数是否出现？
openprogram programs run my_tool -a text=hello           # 冒烟测试
openprogram programs uninstall My-Harness                # 清理

发布前的检查清单：

• <package>/agentics/__init__.py 暴露了 PROGRAM_ENTRIES
• pyproject/requirements 中没有 openprogram（硬性规则 1）
• 在只安装了 OpenProgram 的纯净 venv 中 python -c "import <package>.agentics" 成功（硬性规则 2）
• 上面的 file:// 安装往返测试通过

发布#

推送到 GitHub。用户用以下命令安装：

openprogram programs install <owner>/<Harness-Name>

任何地方都无需注册——仓库 URL 就是分发形式。