HarnessRouter Environments 功能解析：项目依赖一次构建、所有会话只读共享的原理

HarnessRouter Environments 功能解析项目依赖一次构建、所有会话只读共享的原理【免费下载链接】harnessrouterHarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.项目地址: https://gitcode.com/gh_mirrors/ha/harnessrouterHarnessRouter 是一款自托管的 AI 智能体统一接口实现统一智能体协议 UHP可以让 Codex、Claude Code、Hermes 等智能体通过一个 API 运行。它的Environments环境功能解决了项目类任务的核心痛点把项目的文件连同依赖一次构建成只读版本所有会话共享读取——每个新会话不再重新上传文件、不再重装依赖打开即就绪。该功能于 0.26 版随自托管服务器发布是 UHP2026-09-28协议的正式章节设计文档见 docs/environments.md。为什么需要 Environments每个会话重装依赖的痛点HarnessRouter 的每个会话都有一个工作目录从空开始、每轮对话后打快照、下一轮恢复。适合一次性任务但不适合项目——一个带脚本、资源、模板和上百个依赖包的项目被多个人每天打开多次时按老方式每个会话都要重新上传一遍文件、重装一遍依赖而且两个会话无法共享同一份拷贝。Environments 的答案是把项目变成一个独立对象构建一次所有会话以只读方式共享。Environments 是什么一次构建、只读共享的项目快照在 HarnessRouter 中一个环境对象 id 以henv_开头由三部分组成源文件source所有者编辑的项目文件可以逐文件上传、导入压缩包、或直接从 git 仓库导入也可在控制台在线编辑版本versions每次构建生成一个新版本——先拷贝源文件跳过node_modules、.venv等依赖目录见 runner/environments.py 的NOT_COPIED再按requirements.txt/pyproject.toml/package.json安装 Python 虚拟环境和 Node 依赖运行setup.sh最后把整棵目录树设为只读活跃版本active一个指向某个版本的指针会话读的就是它。构建成功自动成为活跃版本构建失败则什么都不改变回滚就是把指针指回旧版本无需重新构建。会话看到的世界是这样的示意/env/content-studio ← 环境完整、只读、所有会话共享 scripts/ assets/ ← 项目文件所有者放进来什么样就是什么样 .venv/ node_modules/ ← 构建时安装一次会话无需再装 /data/workspaces/sid ← 会话自己的目录可写、私有、打快照产出物只从这里来三条规则让它成为一个东西而不是共享文件夹是被构建出来的、不是拷进来的笔记本上现成的虚拟环境在容器里跑不了构建才让免重装成为承诺会话只能读不能写写操作必须真正失败而不是仅靠口头约定路径固定任何会话都能用绝对路径运行项目脚本。完整协议定义见 protocol/versions/2026-09-28/environments.md。一次构建如何做到版本、原子指针与实时进度构建在 runner/environments.py 的_build函数中执行流程分五个阶段复制文件 → Python 包 → Node 包 → 系统包apt→setup.sh全程有 1800 秒的总时限。两个设计亮点值得注意① 进度实时可见。构建记录.hr-build.json在每个阶段结束时就写盘包含当前阶段、已用秒数和日志尾部页面每 3 秒轮询你看到的是正在安装 Python 包已 87 秒这样的进度条而不是一个空转的转圈。② 依赖装错了不用等构建。在控制台声明一个包时服务端会先向 PyPI、npm 仓库或本机的 apt 列表查询runner/environments.py 的check_package名字拼错或版本从未发布过会在输入的那一刻被拒绝而不是几分钟后的构建失败。构建成功后切换版本是一次原子操作先创建临时软链接再os.replace换掉active见 runner/environments.py正在运行的会话永远看到旧的或新的完整版本不会出现既读不到旧的也读不到新的。只读共享如何强制每个环境一个用户组只读不是写进提示词里求智能体别改而是操作系统级的写墙每个环境分配一个专属用户组GID 为 60000 加 id 哈希见 runner/environments.py 的_claim环境目录的组本身就是权限记录重启后依然有效源目录是0700只有 runner 能读构建好的版本是0750/0640同组可读、无人可写见 runner/environments.py智能体进程以自己的会话 uid 运行只有在它的任务声明了某个环境时才临时加入该环境组——所以一个会话读不到别人环境里的字节写入则直接EACCES失败存储根目录权限0751可以穿过、不能列目录会话无法枚举服务器上还有哪些环境。官方实测加上这道墙之前任何会话都能列出并读取所有环境的源和版本加上之后会话只能读自己声明的那一个。会话启动时看到什么固定路径 自动配好的环境变量任务运行在环境上时gateway 在分配任何资源之前先解析环境请求里的metadata.environment优先其次是 harness 上声明的并把{id, slug, entry}传给 runner。如果环境还没有构建好的版本任务在开始前就以environment_not_ready拒绝——绝不让任务跑几分钟才因为找不到项目而失败见 gateway/app.py 的 Environments 段。一切就绪后runner 会做两件事runner/environments.py配环境变量PATH以版本的.venv/bin和node_modules/.bin开头PYTHONPATH/NODE_PATH指向项目PROJECT_ROOT记录挂载点——所以python3直接用虚拟环境的解释器from scripts.lib import x随处可 import写说明书智能体的指令文件里加入 Project environment 一节告诉它项目在哪、只读共享、依赖已装好、别装包装别复制项目、产物一律写到自己的工作目录、脚本用绝对路径运行并原样附上所有者写的entry比如python3 run.py --episode id。环境永远不参与快照——它在 workspace 之外每轮对话的 tarball 里没有它这正是只构建一次的关键。上手路径从控制台到 API控制台Environments 页面ui/src/app/(app)/environments/page.tsx/environments/page.tsx)展示你添加 → 构建一次 → 每个任务都从它启动三步流程进入环境详情页可管理文件、发起构建、切换/回滚版本构建中每 4 秒自动刷新列表APIPOST /v1/environments创建…/files/{path}读写单个文件…/import导入压缩包或 git 仓库POST …/build发起构建POST …/versions/{n}/activate激活/回滚harness 对象和POST /v1/responses上都用environment字段指定环境测试runner 侧行为在 runner/tests/test_environments.py路径逃逸、导入安全性、构建与激活gateway 侧在 gateway/tests/test_environments.py协议契约以 protocol/schema/uhp-2026-09-28.schema.json 为准。一句话总结原理源与版本分离、构建用服务器自己的工具链、活跃版本用原子指针切换、权限用每环境一组的写墙强制——四个机制叠加才有了依赖一次构建、所有会话只读共享的承诺。【免费下载链接】harnessrouterHarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.项目地址: https://gitcode.com/gh_mirrors/ha/harnessrouter创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考