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-core

PhyAgentOS是一个面向具身智能体的递归自我进化操作系统（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-256	Bundle 级 + 每个 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.py）：

sha256字段必须是精确 64 位小写十六进制；
artifact_type目前只允许executable_tar_gz；
entrypoint只能是单个目录安全文件名；
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；
确定性归档：mtime=0、uid=gid=0、uname=gname=""、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.sha256：

if 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-256：

receipt = { "archive_sha256": lock.sha256, "binary_sha256": sha256_file(staged), # 解包后再次校验 ... }

下次load()或satisfies()时会重新比对 receipt，任何不匹配都会立即报错。

🎯三层 SHA-256 的意义：即使 Registry 被中间人攻击替换了 Bundle 或 Node 归档，也无法通过摘要校验；即使归档合法，Node 内部文件被篡改也无法通过解包后 binary 校验。这是 PhyAgentOS "先证据，后结论"哲学的具象化。

五、安全事务安装：staging → 校验 → 原子替换 → rollback

SkillInstaller.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 name

6.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.sh`hook	记录`failed`，回滚
⑦	`_ensure_dora_up`+`_start_flow`+`_wait_until_ready`	抛异常时自动`_stop_flow(force=True)`

6.2 启动前钩子 start.sh

Bundle 根目录可选提供start.sh，PAOS 会调用bash <bundle>/start.sh <name> <version>：

result = subprocess.run( [bash, str(hook), skill.name, skill.version], check=False, ) if result.returncode != 0: raise RuntimeManagerError( f"bundle start.sh hook exited with code {result.returncode}; " f"skill start aborted" )

钩子失败会阻止 Dora 启动，状态记录为failed。这是为外部权重下载、模型缓存预热等场景设计的唯一合法入口。

6.3 健康检查：`_wait_until_ready`

RuntimeManager启动后进入轮询循环（默认 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 = f"Tool context is not ready: {', '.join(missing)}" time.sleep(self.poll_interval_s) raise RuntimeManagerError(f"Runtime 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 ↓ failed

starting：Dora 正在启动，Gateway 尚未 ready
running：全部健康检查通过
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 flow：dora stop --name <flow> --grace-duration 5s（非 force）或--force。

6.6 日志

paos skill logs <name>读取两类日志：

{skill}.log：PAOS 自身的生命周期事件（starting、runtime ready、startup failed等）
{flow_name}-dora.log：dora 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.py	manifest v2 严格校验、NodeLock 定义
PhyAgentOS/skill_runtime/archive.py	安全解包、三层 SHA-256 校验
PhyAgentOS/skill_runtime/installer.py	事务安装、Node receipt 记录
PhyAgentOS/skill_runtime/manager.py	Dora 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.1（`dora-message: 0.7.0`），确认`which dora`
`Gateway address is already in use`	manifest 的`gateway_url`已被其他进程监听，停止后重启或换端口
`bundle start.sh hook exited with code 1`	检查`start.sh`逻辑，确保外部资源下载成功
`Dora flow is not running`	`dora list --format json --name <flow>`查看 flow 状态，查看`{flow}-dora.log`
`Tool context is not ready: xxx`	检查 Gateway`/tools/xxx/context`的`ready`与`binding_error`
`Runtime has non-terminal invocation/session/task binding(s)`	先核对所有`forge_tool_action_status`，再考虑`--force`
`downloaded Forge node archive sha256 does not match Skill lock`	Registry 上的 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 真正跑起来。🚀

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

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