ARTICLE DETAIL

资讯详情

深耕郑州网站建设与运营推广的一线实战洞察。

PhyAgentOS Forge Skill Runtime完全指南:Bundle打包、SHA-256校验与Dora生命周期管理

PhyAgentOS Forge Skill Runtime完全指南:Bundle打包、SHA-256校验与Dora生命周期管理 PhyAgentOS Forge Skill Runtime完全指南Bundle打包、SHA-256校验与Dora生命周期管理【免费下载链接】PhyAgentOS-corePhyAgentOS is a Recursive Self-Improving (RSI) physical agent operating system that enables agents to recursively self-improve through agentic workflows.项目地址: https://gitcode.com/gh_mirrors/ph/PhyAgentOS-corePhyAgentOS是一个面向具身智能体的递归自我进化操作系统RSI而Forge Skill Runtime是它管理机器人工作流的核心模块——它负责 Skill Bundle 打包、SHA-256 完整性校验以及命名 Dora profile 的启动、健康检查与停止。本文用最直观的方式带你从打包一个 Skill到安全启动并管理 Dora 生命周期走完整个闭环。图中展示了 PhyAgentOS 的三大执行边界AgentLoop Planner、ForgeToolClient AgentTask、以及Gateway /tools → ToolEndpoint → Dora → 机器人/仿真器。Forge Skill Runtime 恰好是连接Skill 制品与Dora 实际执行的关键枢纽。一、为什么 Forge Skill Runtime 值得学习在 PhyAgentOS 中机器人的一切动作都必须穿过统一的Forge Gateway 契约Agent 永远不会直接访问策略、仿真器、Dora 节点或硬件 SDK。这种唯一执行边界设计让系统具备四大特性特性说明确定性 Bundle每个 Skill 打包为含archive-manifest.json的tar.gz同源码同哈希双重 SHA-256Bundle 级 每个 Node 归档级 解包后 binary 级共三层摘要校验⚡安全事务安装先 staging、校验、再原子os.replace失败自动 rollback命名 Dora profile每个 profile 有确定 flow name持久化健康状态二、Skill Bundle 的解剖图一个 manifest v2 Skill Bundle 的标准结构如下详见 集成开发指南skill/ ├── skill.yaml # 严格校验的 manifest ├── SKILL.md # 工作流说明 ├── start.sh # 可选Dora 启动前的外部资源准备 ├── archive-manifest.json # 打包脚本自动生成每文件 SHA-256 ├── profiles/profile/dataflow.yaml └── assets/...最小 skill.yaml 结构manifest_version: 2 name: example-skill version: 1.0.0 skill_document: SKILL.md gateway_url: http://127.0.0.1:19002 required_tools: [example.query, example.action] profiles: sim: dataflow: profiles/sim/dataflow.yaml required_binaries: [gateway, example_node] required_assets: [assets/scene.xml] required_environment: [] environment: {} artifacts: resolver: registry nodes: gateway: artifact_id: gateway-1.0.0-linux-x86_64 version: 1.0.0 platform: linux arch: x86_64 artifact_type: executable_tar_gz entrypoint: gateway sha256: 64-character-sha256核心约束源码见 PhyAgentOS/skill_runtime/manifest.pysha256字段必须是精确 64 位小写十六进制artifact_type目前只允许executable_tar_gzentrypoint只能是单个目录安全文件名name必须与 Bundle 目录名一致。三、Bundle 打包一条命令的确定性构建打包脚本 scripts/package_skill.py 是仓库自带的确定性发布工具python scripts/package_skill.py /path/to/example-skill --output-dir dist/skills它做了什么源码 scripts/package_skill.py#L68-L127拒绝 symlink任何符号链接都会立即PackagingError防止恶意链接逃逸排除噪音目录.git、.hg、.svn、__pycache__、node_modules自动剔除生成archive-manifest.json每个文件记录path、size、sha256确定性归档mtime0、uidgid0、unamegname、PAX_FORMAT同源码产出同字节打包时自校验通过ArchiveValidator解包复核再os.replace原子落盘打印哈希与大小sha256: ...、size_bytes: ...可直接登记 Registry。已有同名输出时默认拒绝覆盖仅当确认未发布才用--force。四、SHA-256 校验三层摘要防篡改PhyAgentOS 在三个层级强制执行摘要校验任何一层失败都会阻断安装。4.1 Bundle 级校验PhyAgentOS/skill_runtime/archive.py 提供sha256_file()分块读取哈希def sha256_file(path: Path) - str: digest hashlib.sha256() with path.open(rb) as handle: for chunk in iter(lambda: handle.read(1024 * 1024), b): digest.update(chunk) return digest.hexdigest()ArchiveValidator.extract()首先比对归档总 SHA-256然后解包前检查成员数上限默认 10,000单文件上限512 MB、总大小上限2 GB压缩比上限200×防 zip bomb路径安全拒绝绝对路径、..、空字节、反斜杠内嵌 manifest 校验archive-manifest.json中每个文件的sha256与大小必须精确匹配重复路径、冲突覆盖、未列出内容一律拒绝4.2 Node 归档级校验PhyAgentOS/skill_runtime/installer.py 的NodeInstaller.install()会先比对下载归档 SHA-256与 manifest 中NodeLock.sha256if sha256_file(archive) ! lock.sha256: raise InstallerError(downloaded Forge node archive sha256 does not match Skill lock)4.3 解包后 binary 级校验Node 归档只允许包含一个与entrypoint同名的可执行文件。安装时会在 receipt 中记录解包后的 binary SHA-256receipt { archive_sha256: lock.sha256, binary_sha256: sha256_file(staged), # 解包后再次校验 ... }下次load()或satisfies()时会重新比对 receipt任何不匹配都会立即报错。三层 SHA-256 的意义即使 Registry 被中间人攻击替换了 Bundle 或 Node 归档也无法通过摘要校验即使归档合法Node 内部文件被篡改也无法通过解包后 binary 校验。这是 PhyAgentOS 先证据后结论哲学的具象化。五、安全事务安装staging → 校验 → 原子替换 → rollbackSkillInstaller.install()installer.py#L68-L150采用先 staging 再原子替换策略1. 下载/复制 Bundle 到 staging 临时目录 2. ArchiveValidator.extract() 完整解包 三层摘要校验 3. os.replace(payload, normalized) 原子落到安装目录 4. 失败时 os.replace(backup, target) 回滚关键不变量安装过程中任何时刻磁盘上都是合法 Bundle网络中断、磁盘写满、校验失败都会自动 rollback不会出现半安装状态同一 Skill 的install / start / stop / remove通过 PhyAgentOS/skill_runtime/locking.py 的SkillOperationLock互斥防止并发冲突。六、Dora 生命周期启动、健康检查、停止Dora 是 PhyAgentOS 的物理执行引擎Skill Bundle 声明了多个命名 profile每个 profile 对应一个确定 flow name。paos skill start触发 PhyAgentOS/skill_runtime/manager.py 的RuntimeManager.start()paos-{skill_name}-{profile} # 确定性 flow name6.1 启动流程七步走_start_locked()manager.py#L92-L165严格按以下顺序执行步骤操作失败行为①SkillOperationLock获取排他锁抛SkillOperationBusyError②SkillCatalog.get(skill)加载 manifest抛RuntimeManagerError③SkillEnvironmentBuilder.prepare()物化 binary 与 assets抛InstallerError④_preflight()检查 dora CLI、必需文件、环境变量抛RuntimeManagerError⑤_gateway_snapshot()探测 gateway_url 是否已被占用拒绝静默接管直接报错⑥持久化starting状态 执行start.shhook记录failed回滚⑦_ensure_dora_up_start_flow_wait_until_ready抛异常时自动_stop_flow(forceTrue)6.2 启动前钩子 start.shBundle 根目录可选提供start.shPAOS 会调用bash bundle/start.sh name versionresult subprocess.run( [bash, str(hook), skill.name, skill.version], checkFalse, ) if result.returncode ! 0: raise RuntimeManagerError( fbundle start.sh hook exited with code {result.returncode}; fskill start aborted )钩子失败会阻止 Dora 启动状态记录为failed。这是为外部权重下载、模型缓存预热等场景设计的唯一合法入口。6.3 健康检查_wait_until_readyRuntimeManager启动后进入轮询循环默认 30s 超时while time.monotonic() deadline: if not self._flow_running(flow_name): last_reason Dora flow is not running elif self._gateway_snapshot(manifest) is None: last_reason Gateway GET /tools is unavailable else: contexts self._tool_context_readiness(manifest) missing [tool for tool in manifest.required_tools if not contexts.get(tool, False)] if not missing: return last_reason fTool context is not ready: {, .join(missing)} time.sleep(self.poll_interval_s) raise RuntimeManagerError(fRuntime health check timed out: {last_reason})只有当Dora flow 存活 Gateway/tools可达 所有required_toolscontext ready时状态才持久化为running。6.4 状态持久化五态机PhyAgentOS/skill_runtime/state.py 定义RuntimeState包含 5 种状态starting → running → stopping → stopped ↓ failedstartingDora 正在启动Gateway 尚未 readyrunning全部健康检查通过stopping停止流程进行中stopped正常停止failed启动或运行中异常状态通过原子 JSON 文件持久化tempfile fsync os.replace每次paos skill status都会调用status()实时对账若 Dora flow 存活 Gateway ready 所有 tool ready且持久化状态为starting/running/failed自动校正为running若持久化状态为running但 flow 已挂自动降级为failed并记录具体原因Dora flow is not running/Gateway GET /tools is unavailable/Tool context is not ready: xxx。6.5 停止优雅与强制paos skill stop name调用RuntimeManager.stop()if active_refs and not force: raise RuntimeManagerError( Runtime has non-terminal invocation/session/task binding(s); reconcile them before stopping, or pass --force )默认拒绝停止存在非终态invocation/session/task binding的 Runtime避免物理动作中断--force尽力向 Gateway 发送cancel/stop请求并记录force_stop_with_active_references审计事件terminal_proven: False明确不把 accepted 当作物理停止证明停止 Dora flowdora stop --name flow --grace-duration 5s非 force或--force。6.6 日志paos skill logs name读取两类日志{skill}.logPAOS 自身的生命周期事件starting、runtime ready、startup failed等{flow_name}-dora.logdora start的 stdout/stderr七、完整闭环从打包到停止的最小命令序列以下是 集成开发指南 推荐的可复现发布路径# 1. 打包 python scripts/package_skill.py /path/to/example-skill --output-dir dist/skills # 2. 本地安装--local 跳过 Registry paos skill install dist/skills/example-skill-1.0.0.tar.gz --local # 3. 验证 Node 归档 paos forge-node verify example-skill gateway # 4. 查看已安装 Skill 详情 paos skill inspect example-skill # 5. 启动 Dora profile paos skill start example-skill --profile sim # 6. 查看健康状态 paos skill status example-skill # 7. 查看生命周期日志 paos skill logs example-skill # 8. 停止 paos skill stop example-skill上传到 Registry 前务必完成这套本地闭环并从干净 HOME 重跑一次确保没有依赖源码仓绝对路径。八、关键文件速查表模块职责PhyAgentOS/skill_runtime/manifest.pymanifest v2 严格校验、NodeLock 定义PhyAgentOS/skill_runtime/archive.py安全解包、三层 SHA-256 校验PhyAgentOS/skill_runtime/installer.py事务安装、Node receipt 记录PhyAgentOS/skill_runtime/manager.pyDora flow 生命周期、健康检查PhyAgentOS/skill_runtime/state.py五态持久化、原子 JSON 替换PhyAgentOS/skill_runtime/locking.py跨进程操作互斥锁scripts/package_skill.py确定性 Bundle 构建九、常见问题排查现象排查方向dora is not installed or not available on PATH安装 Dora CLI v0.4.1dora-message: 0.7.0确认which doraGateway address is already in usemanifest 的gateway_url已被其他进程监听停止后重启或换端口bundle start.sh hook exited with code 1检查start.sh逻辑确保外部资源下载成功Dora flow is not runningdora list --format json --name flow查看 flow 状态查看{flow}-dora.logTool context is not ready: xxx检查 Gateway/tools/xxx/context的ready与binding_errorRuntime has non-terminal invocation/session/task binding(s)先核对所有forge_tool_action_status再考虑--forcedownloaded Forge node archive sha256 does not match Skill lockRegistry 上的 Node 归档与 manifest lock 不匹配联系 Skill 发布者十、总结Forge Skill Runtime 是 PhyAgentOS 连接Skill 制品与Dora 物理执行的关键枢纽。它通过确定性 Bundle 打包scripts/package_skill.py保证可复现发布三层 SHA-256 校验Bundle / Node / binary保证端到端完整性事务安装 原子替换保证任何时刻磁盘都是合法状态五态持久化 实时对账保证paos skill status永远反映真实健康度优雅停止 --force审计事件保证物理动作安全终结。掌握这五条主线你就能完整理解并参与 PhyAgentOS 的机器人工作流开发。下一步建议阅读 Forge Tool API 契约 与 开发者手册把 ToolSpec 接入 Dora profile让 Skill 真正跑起来。【免费下载链接】PhyAgentOS-corePhyAgentOS is a Recursive Self-Improving (RSI) physical agent operating system that enables agents to recursively self-improve through agentic workflows.项目地址: https://gitcode.com/gh_mirrors/ph/PhyAgentOS-core创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表