Reef Harness 适配器开发指南如何快速接入 pi、opencode、Claude Code、Codex 等 8 种 Agent 框架【免费下载链接】reefContinual learning infra for self-improving agents项目地址: https://gitcode.com/gh_mirrors/reef7/reefReef 是一个面向自我改进智能体的持续学习基础设施其核心能力之一是Harness 适配器Harness Adapter机制它把 pi、opencode、Claude Code、Codex、dsh、Hermes 等第三方 Agent 框架统一封装成可驱动、可评估、可进化的标准运行单元。这篇指南带你从原理到落地搞懂适配器内部结构并学会在 4 步内接入自己的 Agent 框架。一、适配器解决什么问题 在 Reef 中Agent 运行框架harness 模型。框架侧的全部差异——配置文件在哪、无头模式怎么启动、会话日志什么格式——都被收敛到一层薄薄的声明式适配器中Reef 把一棵harness 树规则、技能、命令、扩展代码渲染成某个 CLI 期望的具体文件适配器声明的binaryargv以无头方式执行一次任务运行结束后Reef 按trajectory声明读回会话日志得到轨迹数据轨迹进入训练/评估闭环模型与框架一起被持续改进。也就是说适配器就是让任意 Agent 框架插上 Reef 插座的接口标准。理解它你既能为现有框架写适配器也能看懂 Reef 内置的 8 个实现。二、内置的 8 种适配器一览Reef 在 reef/harness/adapters/ 目录下内置了 8 个适配器每个目录包含一个descriptor.yaml声明和可选的quirks.py特例处理适配器主要配置目标安装渠道版本锁定声明文件pipi-agent/settings.json、pi-agent/models.jsonnpmearendil-works/pi-coding-agent0.84.2descriptor.yamlopencodeopencode/opencode.jsonnpmopencode-ai1.18.18descriptor.yamlclaudeClaude Codeclaude/settings.jsonnpmanthropic-ai/claude-code2.1.257descriptor.yamlcodexCodex CLIcodex/config.tomlnpmopenai/codex0.152.1descriptor.yamldshDeepSeek Harnessdsh/profiles/headless/cordis.patch.yml、dsh/.envnpmdeepseek-ai/dsh0.1.2-alpha.5descriptor.yamlhermesHermes Agenthermes/config.yamlgit 检出安装v2026.8.31 / 0.21.0descriptor.yamlnativeReef 自有 Agentnative/config.json、native/models.json随 Reef 自带reef-nativedescriptor.yamlterminusTerminus 2terminus/config.json随 Reef 自带reef-terminusdescriptor.yaml其中 6 个驱动的是第三方 CLI 工具native是 Reef 自己的 Agent 循环工具、钩子、图都是可进化的树节点terminus比较特殊——它不是 CLI而是 Harbor 的 Agent 类由 Reef 自带的 runner 驱动详见官方文档 docs/developer-guide/harness-adapters.rst。三、descriptor.yaml 解剖适配器的 6 个核心字段所有适配器的行为都由一个 YAML 声明完全定义加载时由 reef/harness/adapters/descriptor.py 统一校验。以 pi 适配器为例核心字段如下3.1binaryargv无头启动命令binary: pi argv: [--mode, json, -p, {prompt}]{prompt}会在每个回合episode被替换为具体任务文本。这是适配器最基本的职责——告诉 Reef 怎么跑一次任务。3.2env把 Agent 的家搬进回合根目录env: PI_CODING_AGENT_DIR: {root}/pi-agent PI_OFFLINE: 1{root}替换为回合根目录。pi 靠PI_CODING_AGENT_DIR整体搬迁配置根Claude Code 用CLAUDE_CONFIG_DIRCodex 用CODEX_HOMEdsh 用DSH_HOMEHermes 用HERMES_HOME。统一搬迁整个状态目录是保证每个回合隔离、确定性的关键手法——不碰用户真实的~/.claude、不触发信任弹窗、不产生网络抖动。3.3filesharness 树节点的渲染路径声明树中每类节点落到哪个文件。rules和skill是必填项其余可选files: config: primary: { path: pi-agent/settings.json, defaults: {} } models: { path: pi-agent/models.json, defaults: {} } rules: pi-agent/AGENTS.md agent_command: pi-agent/prompts/{name}.md skill: pi-agent/skills/{name}/SKILL.md code_extension: pi-agent/extensions/{name}.ts注意一个设计细节某个节点类型如果适配器没声明路径对应变更会在准入admission和渲染时被拒绝而不是被静默丢弃。例如 native 适配器刻意不声明agent_command和code_extension因为它的循环根本不读这两类文件。3.4trajectory会话日志的格式与路径trajectory: format: pi-session-jsonl path: sessions每个适配器对接的日志格式都不同pi-session-jsonl、claude-session-jsonl、opencode-storage-json、hermes-session-json、terminus-atif-json……Reef 用对应的 reader 把它们归一化成统一轨迹。日志位置也各有讲究比如 Claude Code 的 transcript 在projects/cwd-slug/session-id.jsonlopencode 的存储在xdg-data/opencode/storage。3.5model_binding如何把模型端点接上按 API 方言openai/responses/anthropic声明评测回合中要追加的配置节点{base_url}、{api_key}、{model}在渲染时替换。例如 Codex 适配器走responses方言在config.toml里注入model_providers.reefHermes 则写一个 custom provider 到config.yaml。发布的树永远不含 provider 和密钥——模型绑定只在评测运行时注入。3.6quirkscleanup_whitelist特例与白名单quirks指向一个 Python 模块如reef.harness.adapters.opencode.quirks负责适配器特有的渲染检查和启动修正——比如强制 opencode 保持autoupdate: false任何想翻转该值的组合都会在渲染期被拒绝cleanup_whitelist列出 Agent 启动/运行时会合法产生的文件会话库、缓存、auth.json等避免被误判为残留污染。这些白名单大多来自真实二进制的冒烟测试观察tests/smoke/ 下每个框架都有对应的test_real_*.py。四、8 个适配器的差异速查 框架无头命令形态状态搬迁值得注意的细节pi--mode json -p taskPI_CODING_AGENT_DIRPI_OFFLINE、PI_SKIP_VERSION_CHECK保证回合确定性opencoderun --format json --auto taskOPENCODE_CONFIG_DIR XDG 四件套默认值钉死autoupdate:false、share:disabled、全权限 allowClaude Code-p task --output-format json --permission-mode autoCLAUDE_CONFIG_DIRDISABLE_AUTOUPDATER、DISABLE_TELEMETRY等关闭启动网络行为Codexexec --json --strict-config --sandbox workspace-write taskCODEX_HOME大量默认值关闭分析、钩子、Web 搜索等特性dsh--profile headless -- -- task双--穿透两层解析DSH_HOME配置目标是插件补丁层quirks 把对象转成 YAML 列表输出Hermeschat -Q --oneshot -q taskHERMES_HOME关闭扫描器下载、标题生成、后台记忆回顾开启 JSON 会话快照nativereef-native -p taskREEF_NATIVE_DIR额外支持native_tool/native_hook/native_graph/native_loop等可进化节点还有tree.json随行文件terminusreef-terminus --task task-dirREEF_TERMINUS_DIR提示词本身是 Harbor 任务目录self_isolating自带容器隔离五、4 步接入你的 Agent 框架 官方文档docs/developer-guide/harness-adapters.rst 的 Connect a new agent 一节给出了最小路径第 1 步配置入口 →files.config目标找到框架读取配置的文件声明为config目标至少一个primary并在defaults里写死保证回合隔离的默认值。第 2 步无头命令 →binaryargv找到跑一次提示词就退出的命令行形式作为binary和argv用{prompt}占位同时用env把框架的状态目录整体搬到{root}之下。第 3 步会话日志 →trajectory确定它的会话日志路径与格式。若现有 reader 不认就在 reef/harness/episodes/trajectory.py 中子类化TrajectoryReader并用register_trajectory_reader注册。第 4 步启动产物 →cleanup_whitelist用真实二进制跑一次空白回合把启动时产生的文件会话存储、缓存、凭据库等列入白名单。dir/**容忍整棵子树单个文件需写全路径如pi-agent/auth.json。完成后把适配器放进 reef/harness/adapters/ 并通过reef.harness_adapters入口点entry point组注册每个条目解析为AdapterDescriptor或返回它的零参可调用对象再补一个quirks模块处理该框架的坑。内置适配器就是最完整的参考实现逐行对照即可。六、进一步学习资料 官方开发文档docs/developer-guide/harness-adapters.rst含 native 工具/钩子/图/循环的完整事件协议、terminus 沙箱要求适配器声明模型reef/harness/adapters/descriptor.py轨迹读取器reef/harness/episodes/trajectory.py真实二进制冒烟测试tests/smoke/如test_real_pi.py、test_real_codex.py实战教程tutorials/evolve-your-harness/从部署配置到进化循环的完整演练相关文档docs/developer-guide/、docs/contributing/adding-components.rst掌握 descriptor.yaml 的声明式写法你就拥有了让任意 Agent 框架接入 Reef 持续学习闭环的能力——这正是自我改进智能体基础设施最有趣的入口。【免费下载链接】reefContinual learning infra for self-improving agents项目地址: https://gitcode.com/gh_mirrors/reef7/reef创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Reef Harness 适配器开发指南：如何快速接入 pi、opencode、Claude Code、Codex 等 8 种 Agent 框架
Reef Harness 适配器开发指南如何快速接入 pi、opencode、Claude Code、Codex 等 8 种 Agent 框架【免费下载链接】reefContinual learning infra for self-improving agents项目地址: https://gitcode.com/gh_mirrors/reef7/reefReef 是一个面向自我改进智能体的持续学习基础设施其核心能力之一是Harness 适配器Harness Adapter机制它把 pi、opencode、Claude Code、Codex、dsh、Hermes 等第三方 Agent 框架统一封装成可驱动、可评估、可进化的标准运行单元。这篇指南带你从原理到落地搞懂适配器内部结构并学会在 4 步内接入自己的 Agent 框架。一、适配器解决什么问题 在 Reef 中Agent 运行框架harness 模型。框架侧的全部差异——配置文件在哪、无头模式怎么启动、会话日志什么格式——都被收敛到一层薄薄的声明式适配器中Reef 把一棵harness 树规则、技能、命令、扩展代码渲染成某个 CLI 期望的具体文件适配器声明的binaryargv以无头方式执行一次任务运行结束后Reef 按trajectory声明读回会话日志得到轨迹数据轨迹进入训练/评估闭环模型与框架一起被持续改进。也就是说适配器就是让任意 Agent 框架插上 Reef 插座的接口标准。理解它你既能为现有框架写适配器也能看懂 Reef 内置的 8 个实现。二、内置的 8 种适配器一览Reef 在 reef/harness/adapters/ 目录下内置了 8 个适配器每个目录包含一个descriptor.yaml声明和可选的quirks.py特例处理适配器主要配置目标安装渠道版本锁定声明文件pipi-agent/settings.json、pi-agent/models.jsonnpmearendil-works/pi-coding-agent0.84.2descriptor.yamlopencodeopencode/opencode.jsonnpmopencode-ai1.18.18descriptor.yamlclaudeClaude Codeclaude/settings.jsonnpmanthropic-ai/claude-code2.1.257descriptor.yamlcodexCodex CLIcodex/config.tomlnpmopenai/codex0.152.1descriptor.yamldshDeepSeek Harnessdsh/profiles/headless/cordis.patch.yml、dsh/.envnpmdeepseek-ai/dsh0.1.2-alpha.5descriptor.yamlhermesHermes Agenthermes/config.yamlgit 检出安装v2026.8.31 / 0.21.0descriptor.yamlnativeReef 自有 Agentnative/config.json、native/models.json随 Reef 自带reef-nativedescriptor.yamlterminusTerminus 2terminus/config.json随 Reef 自带reef-terminusdescriptor.yaml其中 6 个驱动的是第三方 CLI 工具native是 Reef 自己的 Agent 循环工具、钩子、图都是可进化的树节点terminus比较特殊——它不是 CLI而是 Harbor 的 Agent 类由 Reef 自带的 runner 驱动详见官方文档 docs/developer-guide/harness-adapters.rst。三、descriptor.yaml 解剖适配器的 6 个核心字段所有适配器的行为都由一个 YAML 声明完全定义加载时由 reef/harness/adapters/descriptor.py 统一校验。以 pi 适配器为例核心字段如下3.1binaryargv无头启动命令binary: pi argv: [--mode, json, -p, {prompt}]{prompt}会在每个回合episode被替换为具体任务文本。这是适配器最基本的职责——告诉 Reef 怎么跑一次任务。3.2env把 Agent 的家搬进回合根目录env: PI_CODING_AGENT_DIR: {root}/pi-agent PI_OFFLINE: 1{root}替换为回合根目录。pi 靠PI_CODING_AGENT_DIR整体搬迁配置根Claude Code 用CLAUDE_CONFIG_DIRCodex 用CODEX_HOMEdsh 用DSH_HOMEHermes 用HERMES_HOME。统一搬迁整个状态目录是保证每个回合隔离、确定性的关键手法——不碰用户真实的~/.claude、不触发信任弹窗、不产生网络抖动。3.3filesharness 树节点的渲染路径声明树中每类节点落到哪个文件。rules和skill是必填项其余可选files: config: primary: { path: pi-agent/settings.json, defaults: {} } models: { path: pi-agent/models.json, defaults: {} } rules: pi-agent/AGENTS.md agent_command: pi-agent/prompts/{name}.md skill: pi-agent/skills/{name}/SKILL.md code_extension: pi-agent/extensions/{name}.ts注意一个设计细节某个节点类型如果适配器没声明路径对应变更会在准入admission和渲染时被拒绝而不是被静默丢弃。例如 native 适配器刻意不声明agent_command和code_extension因为它的循环根本不读这两类文件。3.4trajectory会话日志的格式与路径trajectory: format: pi-session-jsonl path: sessions每个适配器对接的日志格式都不同pi-session-jsonl、claude-session-jsonl、opencode-storage-json、hermes-session-json、terminus-atif-json……Reef 用对应的 reader 把它们归一化成统一轨迹。日志位置也各有讲究比如 Claude Code 的 transcript 在projects/cwd-slug/session-id.jsonlopencode 的存储在xdg-data/opencode/storage。3.5model_binding如何把模型端点接上按 API 方言openai/responses/anthropic声明评测回合中要追加的配置节点{base_url}、{api_key}、{model}在渲染时替换。例如 Codex 适配器走responses方言在config.toml里注入model_providers.reefHermes 则写一个 custom provider 到config.yaml。发布的树永远不含 provider 和密钥——模型绑定只在评测运行时注入。3.6quirkscleanup_whitelist特例与白名单quirks指向一个 Python 模块如reef.harness.adapters.opencode.quirks负责适配器特有的渲染检查和启动修正——比如强制 opencode 保持autoupdate: false任何想翻转该值的组合都会在渲染期被拒绝cleanup_whitelist列出 Agent 启动/运行时会合法产生的文件会话库、缓存、auth.json等避免被误判为残留污染。这些白名单大多来自真实二进制的冒烟测试观察tests/smoke/ 下每个框架都有对应的test_real_*.py。四、8 个适配器的差异速查 框架无头命令形态状态搬迁值得注意的细节pi--mode json -p taskPI_CODING_AGENT_DIRPI_OFFLINE、PI_SKIP_VERSION_CHECK保证回合确定性opencoderun --format json --auto taskOPENCODE_CONFIG_DIR XDG 四件套默认值钉死autoupdate:false、share:disabled、全权限 allowClaude Code-p task --output-format json --permission-mode autoCLAUDE_CONFIG_DIRDISABLE_AUTOUPDATER、DISABLE_TELEMETRY等关闭启动网络行为Codexexec --json --strict-config --sandbox workspace-write taskCODEX_HOME大量默认值关闭分析、钩子、Web 搜索等特性dsh--profile headless -- -- task双--穿透两层解析DSH_HOME配置目标是插件补丁层quirks 把对象转成 YAML 列表输出Hermeschat -Q --oneshot -q taskHERMES_HOME关闭扫描器下载、标题生成、后台记忆回顾开启 JSON 会话快照nativereef-native -p taskREEF_NATIVE_DIR额外支持native_tool/native_hook/native_graph/native_loop等可进化节点还有tree.json随行文件terminusreef-terminus --task task-dirREEF_TERMINUS_DIR提示词本身是 Harbor 任务目录self_isolating自带容器隔离五、4 步接入你的 Agent 框架 官方文档docs/developer-guide/harness-adapters.rst 的 Connect a new agent 一节给出了最小路径第 1 步配置入口 →files.config目标找到框架读取配置的文件声明为config目标至少一个primary并在defaults里写死保证回合隔离的默认值。第 2 步无头命令 →binaryargv找到跑一次提示词就退出的命令行形式作为binary和argv用{prompt}占位同时用env把框架的状态目录整体搬到{root}之下。第 3 步会话日志 →trajectory确定它的会话日志路径与格式。若现有 reader 不认就在 reef/harness/episodes/trajectory.py 中子类化TrajectoryReader并用register_trajectory_reader注册。第 4 步启动产物 →cleanup_whitelist用真实二进制跑一次空白回合把启动时产生的文件会话存储、缓存、凭据库等列入白名单。dir/**容忍整棵子树单个文件需写全路径如pi-agent/auth.json。完成后把适配器放进 reef/harness/adapters/ 并通过reef.harness_adapters入口点entry point组注册每个条目解析为AdapterDescriptor或返回它的零参可调用对象再补一个quirks模块处理该框架的坑。内置适配器就是最完整的参考实现逐行对照即可。六、进一步学习资料 官方开发文档docs/developer-guide/harness-adapters.rst含 native 工具/钩子/图/循环的完整事件协议、terminus 沙箱要求适配器声明模型reef/harness/adapters/descriptor.py轨迹读取器reef/harness/episodes/trajectory.py真实二进制冒烟测试tests/smoke/如test_real_pi.py、test_real_codex.py实战教程tutorials/evolve-your-harness/从部署配置到进化循环的完整演练相关文档docs/developer-guide/、docs/contributing/adding-components.rst掌握 descriptor.yaml 的声明式写法你就拥有了让任意 Agent 框架接入 Reef 持续学习闭环的能力——这正是自我改进智能体基础设施最有趣的入口。【免费下载链接】reefContinual learning infra for self-improving agents项目地址: https://gitcode.com/gh_mirrors/reef7/reef创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
