diff --git a/.github/workflows/publish-pypi.yml b/.github/workflows/publish-pypi.yml
new file mode 100644
index 000000000..abbc020f0
--- /dev/null
+++ b/.github/workflows/publish-pypi.yml
@@ -0,0 +1,133 @@
+name: Publish release to PyPI
+
+on:
+ release:
+ types: [published]
+ workflow_dispatch:
+ inputs:
+ tag:
+ description: Published stable release tag (for example v1.1.1)
+ required: true
+ type: string
+
+permissions:
+ contents: read
+
+concurrency:
+ group: pypi-${{ github.event.release.tag_name || inputs.tag }}
+ cancel-in-progress: false
+
+env:
+ RELEASE_TAG: ${{ github.event.release.tag_name || inputs.tag }}
+
+jobs:
+ prepare:
+ if: >-
+ github.repository == 'PhyAgentOS/PhyAgentOS-core' &&
+ ((github.event_name == 'release' && !github.event.release.prerelease && !github.event.release.draft) ||
+ (github.event_name == 'workflow_dispatch' && github.ref == 'refs/heads/main'))
+ runs-on: ubuntu-24.04
+ timeout-minutes: 10
+ outputs:
+ version: ${{ steps.prepare.outputs.version }}
+ missing: ${{ steps.prepare.outputs.missing }}
+ steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ with:
+ persist-credentials: false
+ - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+ with:
+ python-version: "3.12"
+ - name: Verify release assets and check existing PyPI files
+ id: prepare
+ env:
+ GH_TOKEN: ${{ github.token }}
+ run: python scripts/pypi_release.py prepare --tag "$RELEASE_TAG"
+ - name: Preserve verified release distributions
+ uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+ with:
+ name: verified-pypi-release
+ path: release-assets/
+ if-no-files-found: error
+ retention-days: 14
+ - name: Stage only distributions missing from PyPI
+ if: steps.prepare.outputs.missing != '0'
+ uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+ with:
+ name: pypi-upload
+ path: dist/
+ if-no-files-found: error
+ retention-days: 1
+
+ publish:
+ needs: prepare
+ runs-on: ubuntu-24.04
+ timeout-minutes: 15
+ environment:
+ name: pypi
+ url: https://pypi.org/project/PhyAgentOS-ai/${{ needs.prepare.outputs.version }}/
+ steps:
+ - name: Check publishing credential is configured
+ env:
+ PYPI_API_TOKEN: ${{ secrets.PYPI_API_TOKEN }}
+ run: |
+ if [ -z "$PYPI_API_TOKEN" ]; then
+ echo "::error::Configure the PYPI_API_TOKEN Actions secret. See docs/RELEASING.md."
+ exit 1
+ fi
+ - name: Download distributions to upload
+ if: needs.prepare.outputs.missing != '0'
+ uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8
+ with:
+ name: pypi-upload
+ path: dist/
+ - name: Publish verified distributions to PyPI
+ if: needs.prepare.outputs.missing != '0'
+ uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # release/v1
+ with:
+ password: ${{ secrets.PYPI_API_TOKEN }}
+ packages-dir: dist/
+ skip-existing: false
+ attestations: false # API-token authentication; see docs/RELEASING.md for OIDC.
+ - name: Report identical existing release
+ if: needs.prepare.outputs.missing == '0'
+ run: echo "All distributions already exist on PyPI with matching SHA256; upload skipped."
+
+ verify:
+ needs: [prepare, publish]
+ runs-on: ubuntu-24.04
+ timeout-minutes: 15
+ env:
+ RELEASE_VERSION: ${{ needs.prepare.outputs.version }}
+ steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ with:
+ persist-credentials: false
+ - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+ with:
+ python-version: "3.12"
+ - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8
+ with:
+ name: verified-pypi-release
+ path: release-assets/
+ - name: Verify PyPI filenames and hashes
+ run: python scripts/pypi_release.py verify --tag "$RELEASE_TAG"
+ - name: Install from official PyPI in a clean environment
+ run: |
+ python -m venv "$RUNNER_TEMP/pypi-smoke"
+ "$RUNNER_TEMP/pypi-smoke/bin/python" -m pip --isolated install \
+ --index-url https://pypi.org/simple/ --no-cache-dir \
+ --only-binary PhyAgentOS-ai --report "$RUNNER_TEMP/pypi-install.json" \
+ "PhyAgentOS-ai==$RELEASE_VERSION"
+ python scripts/pypi_release.py installed --tag "$RELEASE_TAG" \
+ --report "$RUNNER_TEMP/pypi-install.json"
+ "$RUNNER_TEMP/pypi-smoke/bin/python" -m pip check
+ "$RUNNER_TEMP/pypi-smoke/bin/python" -I -c \
+ 'import os, importlib.metadata, PhyAgentOS; v = os.environ["RELEASE_VERSION"]; assert importlib.metadata.version("PhyAgentOS-ai") == PhyAgentOS.__version__ == v'
+ cd "$RUNNER_TEMP"
+ "$RUNNER_TEMP/pypi-smoke/bin/paos" --version
+ "$RUNNER_TEMP/pypi-smoke/bin/paos" --help
+ - name: Write publication summary
+ run: |
+ printf 'Verified [%s](https://pypi.org/project/PhyAgentOS-ai/%s/) against GitHub Release hashes and a clean PyPI installation.\n' \
+ "$RELEASE_TAG" "$RELEASE_VERSION" >> "$GITHUB_STEP_SUMMARY"
diff --git a/.github/workflows/release-build.yml b/.github/workflows/release-build.yml
index 5c3812649..864b26c6e 100644
--- a/.github/workflows/release-build.yml
+++ b/.github/workflows/release-build.yml
@@ -6,7 +6,7 @@ on:
tag:
description: Tag to build
required: true
- default: v1.0.0
+ default: v1.1.1
type: string
push:
tags:
diff --git a/.github/workflows/release-checks.yml b/.github/workflows/release-checks.yml
new file mode 100644
index 000000000..9cd2ff93c
--- /dev/null
+++ b/.github/workflows/release-checks.yml
@@ -0,0 +1,33 @@
+name: Check release automation
+
+on:
+ pull_request:
+ paths:
+ - .github/workflows/publish-pypi.yml
+ - .github/workflows/release-checks.yml
+ - scripts/pypi_release.py
+ - scripts/tests/test_pypi_release.py
+ push:
+ branches: [main, dev]
+ paths:
+ - .github/workflows/publish-pypi.yml
+ - .github/workflows/release-checks.yml
+ - scripts/pypi_release.py
+ - scripts/tests/test_pypi_release.py
+
+permissions:
+ contents: read
+
+jobs:
+ checks:
+ runs-on: ubuntu-24.04
+ timeout-minutes: 5
+ steps:
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+ with:
+ persist-credentials: false
+ - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+ with:
+ python-version: "3.12"
+ - name: Test release validation and safe retries
+ run: python -m unittest discover -s scripts/tests -p test_pypi_release.py -v
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 43941e3c6..1e8457e89 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,46 @@
All notable changes to PhyAgentOS are documented here. Categories follow Keep a Changelog.
+## [v1.1.1] - 2026-10-23
+
+Skill development, execution reliability and the Opper gateway. Changes since v1.1.0.
+
+### Added
+
+- Opper as an OpenAI-compatible gateway, with provider selection, environment
+ credentials and model identifiers preserved in routed requests.
+- Bilingual Track B development guides and an independent Piper X simulation
+ Skill example covering model conversion, original Node locks, packaging,
+ and validation with its recorded runtime baseline.
+- Bilingual contribution guides, MuJoCo Quickstart GIFs, and a GOSIM Shenzhen
+ 2026 announcement.
+
+### Changed
+
+- Local workflow-document and Node-executable modifications produce warnings
+ during task creation and Runtime startup. Bindings freeze the activated
+ workflow document hash and experience records use it for attribution.
+- Consolidate bilingual manuals, developer references and documentation
+ navigation while retaining benchmark documentation links.
+- Synchronize package, CLI, bundled bridge, Docker, release-build defaults,
+ README and current documentation versions to 1.1.1.
+
+### Fixed
+
+- Keep explicit Node verification and install-cache acceptance strict for
+ modified executables, and retain Skill/Runtime version compatibility checks.
+- Record structured Gateway rejections known to occur before Action dispatch
+ as failed, allowing a later retry without the unknown-execution guard.
+ Timeouts, transport failures and identified remote invocations remain unknown.
+- Exclude pre-dispatch rejections from task finalization and cancellation
+ execution facts; a task with no executed calls still fails. Structured
+ admission rejection codes require Forge Gateway 1.1.2 or newer; older
+ unstructured responses retain conservative handling.
+- Add regression coverage for Opper routing, local Node modifications and
+ pre-dispatch Action rejection handling.
+
+[Full comparison: v1.1.0...v1.1.1](https://github.com/PhyAgentOS/PhyAgentOS-core/compare/v1.1.0...v1.1.1)
+
## [v1.1.0] - 2026-10-09
Provider management, Skill Runtime and governed interactions. Changes since v1.0.0.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 000000000..4ba5816ea
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,79 @@
+# Contributing to PhyAgentOS
+
+[English](CONTRIBUTING.md) | [简体中文](CONTRIBUTING_zh.md)
+
+We welcome bug reports, documentation improvements and contributions to physical execution capabilities.
+Read the development manuals before choosing an implementation approach. We recommend that developers
+focus primarily on **TrackB: the Forge/Dora execution framework, Nodes and Skills**.
+This is the recommended starting point for extending robot and environment support; Core fixes and
+improvements are also welcome.
+
+## Current availability
+
+The resource platform does **not yet support external contributor submissions or external changes
+to existing registered repositories**. These workflows will become available only after the approval
+service is completed and opened for use. Current resource registration and publication are
+administrator-managed; they are not a public contributor submission route.
+
+For now, use this guide to prepare and validate development locally. References to platform
+submission, review and publication in the development manuals describe the workflow to follow once
+it becomes available, not an external service that is open today. GitHub source review follows each
+repository's maintainer rules separately; a fork or PR does not grant platform approval, repository
+write access or resource-publication rights.
+
+## Start with the development manuals
+
+| Goal | Read first |
+| --- | --- |
+| Understand TrackB architecture and repository responsibilities | [TrackB framework guide](docs/user_development_guide/track_b/README.md) and [repository catalog](docs/user_development_guide/track_b/REPOSITORIES.md) |
+| Understand messages, units and Node interfaces | [Public protocols and important Node types](docs/user_development_guide/track_b/PROTOCOLS.md) |
+| Understand Skill, Tool, Endpoint and Gateway relationships | [Runtime guide](docs/user_development_guide/track_b/RUNTIME.md) |
+| Choose an extension mode | [Skill development manual](docs/user_development_guide/track_b/SKILL_DEVELOPMENT.md) |
+| Adapt a simulated robot using existing Nodes | [Piper X MuJoCo demo](docs/user_development_guide/PIPER_X_DEMO.md) |
+| Reference Bundle fields and Tool integration | [Bundle and Tool integration reference](docs/user_development_guide/README.md) |
+| Change and test Core | [Core developer manual](docs/en/03-developer-manual.md) |
+
+## Recommended contribution areas
+
+- **Robot and environment support:** robot models, joint/frame mappings, simulation scenes and deployment profiles.
+- **Reusable Nodes:** device and sensor Adapters, control/planning/perception Operators, and compatible ToolEndpoint providers.
+- **Skills:** assemble compatible Nodes, expose documented Tools, and provide reproducible workflows and examples.
+- **Integration quality:** protocol consistency, error handling, focused tests, troubleshooting and bilingual documentation.
+
+Choose the smallest extension mode that supports the capability:
+
+1. **Configure an existing profile** when compatible Nodes already support the required behavior.
+2. **Add a profile** when another robot or scene can reuse compatible Nodes.
+3. **Develop Nodes and assemble a Skill** when new device protocols, algorithms or interfaces are needed.
+
+The [Skill development manual](docs/user_development_guide/track_b/SKILL_DEVELOPMENT.md) explains the difficulty,
+required skills and steps for each mode. Use the [Piper X demo](docs/user_development_guide/PIPER_X_DEMO.md)
+as a worked example, checking its version and model assumptions before adapting it.
+
+## Prepare development and future submissions
+
+1. Reproduce the baseline and record compatible Core, Forge, Dora, Skill and Node versions as relevant.
+ For a new interface or a change spanning repositories, open an
+ [issue](https://github.com/PhyAgentOS/PhyAgentOS-core/issues) to discuss the scope first.
+2. Use the repository catalog to locate the owning source repository. Node changes belong to the
+ corresponding Node repository; Core changes and Core documentation belong here. Keep changes focused.
+3. Work in a local copy or a personal fork. If the owning repository's maintainers accept source PRs,
+ open one from your fork against the agreed target branch. This source-review process is separate
+ from the external platform submission and repository-change workflows that are not yet open.
+4. Run checks appropriate to the change. For robot integration, verify model/joint/frame consistency,
+ startup, representative native Tool calls, failure handling and shutdown. Validate in simulation
+ before attempting hardware execution. Explain the resulting behavior and any validation limits.
+5. Update documentation alongside configuration or API changes. Keep repository `README.md` in English
+ and `README_zh.md` in Chinese, with reciprocal links at the top. For Node repositories, document
+ Node count and entry points, Tool support, Endpoint IDs/operations and Tool API mappings; state
+ explicitly when a capability is not provided. See the
+ [Node README checklist](docs/user_development_guide/track_b/SKILL_DEVELOPMENT.md).
+6. Preserve model/source licenses and immutable resource versions. Source changes that alter a Node
+ artifact require a new version and matching Skill locks. Local installation, platform registration
+ and publication are separate steps. External contributors must wait for the approval service and
+ these workflows to open before submitting resources or requesting changes to existing registered
+ repositories; then follow the platform's published instructions.
+
+Do not include credentials, private environment configuration or unrelated local logs in a contribution.
+
+Maintainers publishing a version should follow the [GitHub and PyPI release guide](docs/RELEASING.md).
diff --git a/CONTRIBUTING_zh.md b/CONTRIBUTING_zh.md
new file mode 100644
index 000000000..0e48e4de2
--- /dev/null
+++ b/CONTRIBUTING_zh.md
@@ -0,0 +1,69 @@
+# 参与 PhyAgentOS 开发
+
+[English](CONTRIBUTING.md) | [简体中文](CONTRIBUTING_zh.md)
+
+欢迎报告问题、完善文档和扩展物理执行能力。建议在选择实现方式前先阅读开发手册,
+并将开发重心优先放在 **TrackB:基于 Forge/Dora 的执行框架、Node 与 Skill** 上。
+这是扩展机器人和环境支持的推荐起点;同时也欢迎修复和改进 Core。
+
+## 当前开放范围
+
+资源平台目前**暂不支持外部贡献者提交贡献,也不开放外部贡献者修改已有登记仓库的流程**。
+这些能力需等待审批服务完成并开放后再支持。当前资源登记与发布由管理员维护,
+不作为面向外部贡献者的提交入口。
+
+现阶段可参考本文与开发手册进行本地开发和验证。手册中涉及平台提交、审核和发布的步骤,
+是相应能力开放后的流程说明,不代表当前已经提供外部入口。GitHub 源码评审另行遵循各仓库维护者的规则;
+拥有 fork 或提交 PR 不等同于获得平台审批、仓库写权限或资源发布权限。
+
+## 先阅读开发手册
+
+| 目标 | 阅读入口 |
+| --- | --- |
+| 理解 TrackB 架构与仓库职责 | [TrackB 框架说明](docs/user_development_guide/track_b/README_zh.md)及[仓库目录](docs/user_development_guide/track_b/REPOSITORIES_zh.md) |
+| 理解消息、单位和节点接口 | [公共协议与重要节点类型](docs/user_development_guide/track_b/PROTOCOLS_zh.md) |
+| 理解 Skill、Tool、Endpoint 和 Gateway 的关系 | [Runtime 关系说明](docs/user_development_guide/track_b/RUNTIME_zh.md) |
+| 选择二次开发模式 | [Skill 开发手册](docs/user_development_guide/track_b/SKILL_DEVELOPMENT_zh.md) |
+| 复用现有节点接入仿真机器人 | [Piper X MuJoCo 示例](docs/user_development_guide/PIPER_X_DEMO_zh.md) |
+| 查询 Bundle 字段与 Tool 接入细节 | [Bundle 与 Tool 接入参考](docs/user_development_guide/README_zh.md) |
+| 修改与测试 Core | [Core 开发者手册](docs/zh/03-developer-manual.md) |
+
+## 建议优先参与的方向
+
+- **机器人与环境接入:** 机器人模型、关节与坐标系映射、仿真场景和部署 profile。
+- **可复用节点:** 设备与传感器 Adapter,控制、规划、感知 Operator,以及兼容的 ToolEndpoint provider。
+- **Skill:** 组装兼容节点,提供有明确文档的 Tool,并补充可复现的工作流和示例。
+- **集成质量:** 协议一致性、错误处理、有针对性的测试、故障排查和双语文档。
+
+按能力需求选择改动范围最小的开发模式:
+
+1. **修改已有 profile 的配置:** 兼容节点已支持所需行为时,优先通过配置完成。
+2. **增加 profile 分支:** 新机器人或场景可以复用兼容节点时,新增部署选项。
+3. **独立开发 Node 并组装 Skill:** 需要新的设备协议、算法或接口时,进入源码开发。
+
+[Skill 开发手册](docs/user_development_guide/track_b/SKILL_DEVELOPMENT_zh.md)说明了各模式的难度、
+能力要求与具体流程。[Piper X 示例](docs/user_development_guide/PIPER_X_DEMO_zh.md)提供完整参考;
+复用前请核对其中的版本和模型假设。
+
+## 开发准备与后续提交流程
+
+1. 先复现基线,按改动范围记录相互兼容的 Core、Forge、Dora、Skill 和 Node 版本。
+ 新增接口或涉及多个仓库时,建议先通过
+ [Issue](https://github.com/PhyAgentOS/PhyAgentOS-core/issues)讨论范围。
+2. 根据仓库目录找到所属源码仓库。Node 改动归属对应节点仓库;Core 及其文档改动归属本仓库。
+ 每次改动保持明确、集中的目标。
+3. 在本地副本或个人 fork 中开发。若所属仓库维护者接受源码 PR,可从个人 fork 向约定的目标分支提交。
+ 这一源码评审流程与尚未开放的外部平台贡献提交、仓库修改流程相互独立。
+4. 按改动选择必要检查。机器人接入应核对模型、关节和坐标系的一致性,验证启动、代表性的原生 Tool 调用、
+ 失败处理与停止;尝试真机执行前先完成仿真验证。说明最终行为与验证范围的限制。
+5. 配置或 API 改动同步更新文档。仓库 `README.md` 使用英文,`README_zh.md` 使用中文,顶部互相链接。
+ Node 仓库应说明节点数量及入口、是否支持 Tool、Endpoint ID 与 operation、Tool API 映射;
+ 未提供的能力也应明确注明。参见
+ [Node README 检查项](docs/user_development_guide/track_b/SKILL_DEVELOPMENT_zh.md)。
+6. 保留模型与源码许可证,遵守资源版本不可变原则。源码改动导致 Node 制品变化时,应发布新版本并更新
+ Skill locks。本地安装、平台登记与发布是独立步骤。外部贡献者需等待审批服务及相关流程开放,
+ 再按平台公布的说明提交资源或申请修改已有登记仓库。
+
+请勿在贡献中包含凭据、私有环境配置或无关的本地日志。
+
+维护者发布版本时,请遵循 [GitHub 与 PyPI 发布流程](docs/RELEASING_zh.md)。
diff --git a/Dockerfile b/Dockerfile
index f4a0464af..a0550ad81 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -1,7 +1,7 @@
FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim
LABEL org.opencontainers.image.title="PhyAgentOS" \
- org.opencontainers.image.version="1.0.0" \
+ org.opencontainers.image.version="1.1.1" \
org.opencontainers.image.source="https://github.com/PhyAgentOS/PhyAgentOS-core"
# Install Node.js 20 for the WhatsApp bridge
diff --git a/PhyAgentOS/__init__.py b/PhyAgentOS/__init__.py
index 2e416a1c5..9eeb2acb2 100644
--- a/PhyAgentOS/__init__.py
+++ b/PhyAgentOS/__init__.py
@@ -2,5 +2,5 @@
PhyAgentOS - A lightweight AI agent framework
"""
-__version__ = "1.1.0"
+__version__ = "1.1.1"
__logo__ = "🍞"
diff --git a/PhyAgentOS/agent/experience/coordinator.py b/PhyAgentOS/agent/experience/coordinator.py
index 3fb5595e9..a0fc52698 100644
--- a/PhyAgentOS/agent/experience/coordinator.py
+++ b/PhyAgentOS/agent/experience/coordinator.py
@@ -185,7 +185,13 @@ def schedule_forge_completion(self, task_ref: str) -> None:
else None
),
skill_document_sha256=(
- binding.get("forge_skill_binding", {}).get("skill_document_sha256")
+ # The episode must be attributed to the document the agent
+ # actually read (workflow overlay first), not the installed
+ # bundle document when the two differ.
+ (
+ binding.get("forge_skill_binding", {}).get("workflow_document_sha256")
+ or binding.get("forge_skill_binding", {}).get("skill_document_sha256")
+ )
if isinstance(binding.get("forge_skill_binding"), dict)
else None
),
diff --git a/PhyAgentOS/cli/commands.py b/PhyAgentOS/cli/commands.py
index 3eb48d929..8c5b8afe8 100644
--- a/PhyAgentOS/cli/commands.py
+++ b/PhyAgentOS/cli/commands.py
@@ -415,7 +415,12 @@ def _make_forge_components(config: Config, provider):
invocation_ids = DynamicRuntimeSet(runtime_registry, "invocation_ids")
session_ids = DynamicRuntimeSet(runtime_registry, "session_ids")
task_binding_ids = DynamicRuntimeSet(runtime_registry, "task_binding_ids")
- binding_resolver = ForgeSkillBindingResolver(runtime_registry)
+ from PhyAgentOS.agent.skills import SkillsLoader
+
+ binding_resolver = ForgeSkillBindingResolver(
+ runtime_registry,
+ skills_loader=SkillsLoader(config.workspace_path),
+ )
coordinator = AgentTaskCoordinator(
workspace=config.workspace_path,
@@ -1471,7 +1476,7 @@ def forge_node_verify(
lock = manifest.artifacts.nodes.get(node_id)
if lock is None:
raise RuntimeError(f"Skill {skill_name!r} does not lock Node {node_id!r}")
- NodeInstaller().load(lock)
+ NodeInstaller().load(lock, strict=True)
except Exception as error:
_skill_runtime_error(error)
return
diff --git a/PhyAgentOS/config/schema.py b/PhyAgentOS/config/schema.py
index b03810c4e..2a93e01f5 100644
--- a/PhyAgentOS/config/schema.py
+++ b/PhyAgentOS/config/schema.py
@@ -429,6 +429,7 @@ class ProvidersConfig(Base):
requesty: ProviderConfig = Field(default_factory=ProviderConfig) # Requesty API gateway
cheaperinference: ProviderConfig = Field(default_factory=ProviderConfig) # Cheaper Inference
api_route: ProviderConfig = Field(default_factory=ProviderConfig) # API Route gateway
+ opper: ProviderConfig = Field(default_factory=ProviderConfig) # Opper gateway
openai_codex: ProviderConfig = Field(default_factory=ProviderConfig) # OpenAI Codex (OAuth)
github_copilot: ProviderConfig = Field(default_factory=ProviderConfig) # Github Copilot (OAuth)
diff --git a/PhyAgentOS/forge/binding.py b/PhyAgentOS/forge/binding.py
index 58b0d7203..28fdbd896 100644
--- a/PhyAgentOS/forge/binding.py
+++ b/PhyAgentOS/forge/binding.py
@@ -6,8 +6,10 @@
import json
import threading
from datetime import datetime
+from pathlib import Path
from typing import Any, Literal
+from loguru import logger
from pydantic import BaseModel, ConfigDict, Field
from PhyAgentOS.skill_runtime.catalog import SkillCatalog
@@ -36,6 +38,9 @@ class ForgeSkillBindingCandidate(BindingModel):
skill_version: str
manifest_sha256: str = Field(pattern=r"^[0-9a-f]{64}$")
skill_document_sha256: str = Field(pattern=r"^[0-9a-f]{64}$")
+ workflow_document_sha256: str | None = Field(
+ default=None, pattern=r"^[0-9a-f]{64}$"
+ )
runtime_profile: str
runtime_instance_id: str
gateway_url: str
@@ -52,6 +57,9 @@ class ForgeSkillBinding(BindingModel):
skill_version: str
manifest_sha256: str = Field(pattern=r"^[0-9a-f]{64}$")
skill_document_sha256: str = Field(pattern=r"^[0-9a-f]{64}$")
+ workflow_document_sha256: str | None = Field(
+ default=None, pattern=r"^[0-9a-f]{64}$"
+ )
runtime_profile: str
runtime_instance_id: str
gateway_url: str
@@ -82,7 +90,13 @@ def _response_data(response: dict[str, Any], label: str) -> dict[str, Any]:
def _candidate_payload(candidate: ForgeSkillBindingCandidate) -> dict[str, Any]:
- value = candidate.model_dump(mode="json", exclude={"candidate_id", "created_at"})
+ value = candidate.model_dump(
+ mode="json",
+ # workflow_document_sha256 is deliberately excluded: the workflow document
+ # may be edited locally between activation and task creation, and that must
+ # not invalidate the frozen binding (task creation only warns).
+ exclude={"candidate_id", "created_at", "workflow_document_sha256"},
+ )
value["required_tools"] = sorted(value["required_tools"], key=lambda item: item["tool_id"])
return value
@@ -90,9 +104,18 @@ def _candidate_payload(candidate: ForgeSkillBindingCandidate) -> dict[str, Any]:
class ForgeSkillBindingResolver:
"""Preview, freeze, and continuously validate one active Skill runtime."""
- def __init__(self, runtime_registry: Any, *, catalog: SkillCatalog | None = None) -> None:
+ def __init__(
+ self,
+ runtime_registry: Any,
+ *,
+ catalog: SkillCatalog | None = None,
+ skills_loader: Any | None = None,
+ ) -> None:
self.runtime_registry = runtime_registry
self.catalog = catalog or SkillCatalog()
+ # Optional SkillsLoader used to hash the document the agent actually reads
+ # (workspace overlay first) instead of the installed bundle document.
+ self.skills_loader = skills_loader
self._candidates: dict[str, ForgeSkillBindingCandidate] = {}
self._lock = threading.RLock()
self.interaction_candidates: dict[str, dict] = {}
@@ -103,6 +126,33 @@ def _runtime(self) -> Any:
raise ForgeSkillBindingError("no ready Forge Skill runtime is active")
return runtime
+ def _workflow_document_sha256(self, skill_name: str) -> str | None:
+ """Hash the document the agent actually reads (workspace overlay first).
+
+ Returns None when the resolved document cannot be confirmed, so the
+ binding never substitutes the installed bundle identity for a
+ document it did not verify.
+ """
+ if self.skills_loader is None:
+ return None
+ try:
+ resolved = self.skills_loader.resolve_skill(
+ skill_name, require_available=False
+ )
+ except Exception:
+ return None
+ if resolved is None:
+ return None
+ try:
+ return hashlib.sha256(Path(resolved["path"]).read_bytes()).hexdigest()
+ except OSError:
+ logger.warning(
+ "resolved workflow document for Skill {} is unreadable; "
+ "workflow document identity will not be frozen",
+ skill_name,
+ )
+ return None
+
async def preview(self, skill_name: str) -> ForgeSkillBindingCandidate:
runtime = self._runtime()
if runtime.skill_name != skill_name:
@@ -149,6 +199,7 @@ async def preview(self, skill_name: str) -> ForgeSkillBindingCandidate:
)
manifest_path = manifest.bundle_root / "skill.yaml"
document_path = manifest.resolve_bundle_path(manifest.skill_document)
+ installed_document_sha256 = hashlib.sha256(document_path.read_bytes()).hexdigest()
seed = {
"skill": skill_name,
"runtime": runtime.runtime_instance_id,
@@ -159,7 +210,8 @@ async def preview(self, skill_name: str) -> ForgeSkillBindingCandidate:
skill_name=skill_name,
skill_version=manifest.version,
manifest_sha256=hashlib.sha256(manifest_path.read_bytes()).hexdigest(),
- skill_document_sha256=hashlib.sha256(document_path.read_bytes()).hexdigest(),
+ skill_document_sha256=installed_document_sha256,
+ workflow_document_sha256=self._workflow_document_sha256(skill_name),
runtime_profile=runtime.profile,
runtime_instance_id=runtime.runtime_instance_id,
gateway_url=runtime.gateway_url,
@@ -175,7 +227,13 @@ async def preview(self, skill_name: str) -> ForgeSkillBindingCandidate:
self.interaction_candidates[candidate.candidate_id] = extension
return candidate
- async def freeze(self, candidate_id: str, *, task_id: str) -> ForgeSkillBinding:
+ async def freeze(
+ self,
+ candidate_id: str,
+ *,
+ task_id: str,
+ activated_document_sha256: str | None = None,
+ ) -> ForgeSkillBinding:
with self._lock:
candidate = self._candidates.get(candidate_id)
if candidate is None:
@@ -188,11 +246,30 @@ async def freeze(self, candidate_id: str, *, task_id: str) -> ForgeSkillBinding:
raise ForgeSkillBindingError(
"Skill Runtime or ToolSpec changed after activation; activate the Skill again"
)
+ workflow_sha256 = current.workflow_document_sha256
+ if activated_document_sha256 is not None:
+ # The binding must attest the document the agent actually activated.
+ # Local edits after activation are allowed, but they must not silently
+ # re-attribute execution to a version the agent never read.
+ if (
+ workflow_sha256 is not None
+ and activated_document_sha256 != workflow_sha256
+ ):
+ logger.warning(
+ "workflow document changed after activation; freezing the "
+ "activated document sha256 {} (current file sha256 {})",
+ activated_document_sha256[:12],
+ workflow_sha256[:12],
+ )
+ workflow_sha256 = activated_document_sha256
binding_payload = _candidate_payload(current)
binding_payload["task_id"] = task_id
return ForgeSkillBinding(
binding_id=f"binding_{canonical_sha256(binding_payload)[:24]}",
- **current.model_dump(exclude={"candidate_id"}),
+ **{
+ **current.model_dump(exclude={"candidate_id"}),
+ "workflow_document_sha256": workflow_sha256,
+ },
)
async def validate_tool(
diff --git a/PhyAgentOS/forge/task.py b/PhyAgentOS/forge/task.py
index 243dd60b7..fe221ad8c 100644
--- a/PhyAgentOS/forge/task.py
+++ b/PhyAgentOS/forge/task.py
@@ -13,6 +13,7 @@
from typing import Any, Iterator, Literal
from uuid import uuid4
+from loguru import logger
from pydantic import BaseModel, ConfigDict, Field, field_validator
from PhyAgentOS.config.schema import ForgeConfig
@@ -95,6 +96,10 @@ class ToolExecutionRecord(BaseModel):
attempt_id: str | None = None
response: dict[str, Any] | None = None
error: dict[str, Any] | None = None
+ # True only when the Gateway proved the invoke was rejected before anything
+ # reached the provider. Such a record documents a tool call that never
+ # executed, so task finalization must neither require nor be failed by it.
+ rejected_before_dispatch: bool = False
evidence_refs: list[str] = Field(default_factory=list)
created_at: datetime = Field(default_factory=utc_now)
updated_at: datetime = Field(default_factory=utc_now)
@@ -472,12 +477,22 @@ async def _create_task_bound(
if not candidate_id:
raise AgentTaskError("primary Skill activation has no Forge binding candidate")
try:
- binding = await self.binding_resolver.freeze(candidate_id, task_id=task_id)
+ binding = await self.binding_resolver.freeze(
+ candidate_id,
+ task_id=task_id,
+ activated_document_sha256=activation.content_sha256,
+ )
except ForgeSkillBindingError as exc:
raise AgentTaskError(str(exc)) from exc
- if activation.content_sha256 != binding.skill_document_sha256:
- raise AgentTaskError(
- "activated SKILL.md does not match the installed Runtime binding"
+ if (
+ binding.workflow_document_sha256 is not None
+ and binding.workflow_document_sha256 != binding.skill_document_sha256
+ ):
+ logger.warning(
+ "workflow document sha256 {} differs from the installed bundle "
+ "document sha256 {}; proceeding with the locally modified document",
+ binding.workflow_document_sha256[:12],
+ binding.skill_document_sha256[:12],
)
task = AgentTaskRecord(
task_id=task_id,
@@ -631,13 +646,18 @@ async def start_action(
remote_invocation_id, remote_attempt_id = _remote_identity(exc)
invocation_id = remote_invocation_id or invocation_id
attempt_id = remote_attempt_id or attempt_id
+ # A structured pre-dispatch rejection leaves no remote state, so
+ # the record is definitively failed: the identical-Action guard
+ # must not arm and block a later identical resend.
+ rejected_before_dispatch = _rejected_before_dispatch(exc)
self._finish_execution(
task_id,
record_id,
- status="unknown",
+ status="failed" if rejected_before_dispatch else "unknown",
invocation_id=invocation_id,
attempt_id=attempt_id,
error={"type": type(exc).__name__, "message": str(exc)},
+ rejected_before_dispatch=rejected_before_dispatch,
)
if invocation_id and self.runtime_invocation_ids is not None:
self._track_remote_identity(
@@ -1207,6 +1227,7 @@ def _finish_execution(
attempt_id: str | None = None,
response: dict[str, Any] | None = None,
error: dict[str, Any] | None = None,
+ rejected_before_dispatch: bool = False,
) -> None:
def mutate(current: AgentTaskRecord) -> None:
record = _task_execution(current, record_id)
@@ -1215,6 +1236,7 @@ def mutate(current: AgentTaskRecord) -> None:
record.attempt_id = attempt_id or record.attempt_id
record.response = response
record.error = error
+ record.rejected_before_dispatch = rejected_before_dispatch
record.updated_at = utc_now()
self.store.update(task_id, mutate, event_type="tool_execution_finished")
@@ -1421,12 +1443,20 @@ def _cancel_terminal_status(task: AgentTaskRecord) -> AgentTaskStatus:
if item.semantics == "action"
or (item.semantics == "session" and item.ownership == "task")
]
- if not owned or all(item.status in {"cancelled", "stopped"} for item in owned):
+ if not owned or all(
+ item.status in {"cancelled", "stopped"} or item.rejected_before_dispatch
+ for item in owned
+ ):
return AgentTaskStatus.CANCELLED
return AgentTaskStatus.FAILED
def _execution_facts_succeeded(task: AgentTaskRecord) -> bool:
+ executed = [item for item in task.execution_records if not item.rejected_before_dispatch]
+ if not executed:
+ # Every recorded call was rejected before dispatch: nothing ran, so the
+ # task cannot be reported as succeeded.
+ return False
return all(
item.status == "succeeded"
or (
@@ -1439,7 +1469,7 @@ def _execution_facts_succeeded(task: AgentTaskRecord) -> bool:
)
)
)
- for item in task.execution_records
+ for item in executed
)
@@ -1454,6 +1484,35 @@ def _remote_identity(exc: Exception) -> tuple[str | None, str | None]:
)
+# Gateway error codes that are only raised before anything is dispatched to a
+# provider. An invoke that fails with one of these provably left no remote
+# state, so its execution is definitively failed rather than unknown.
+# The gateway attaches `error.code` to Action admission rejections from 1.1.2
+# onward; older releases return an unstructured 503 and are therefore still
+# recorded as unknown, which is the safe reading.
+# FORGE_TOOL_INVOKE_TIMEOUT is deliberately absent: the gateway also emits it
+# after dispatch when the synchronous caller response times out, where the
+# provider may still be executing and the outcome is genuinely unknown.
+_PRE_DISPATCH_REJECTION_CODES = frozenset(
+ (
+ "FORGE_TOOL_GATEWAY_BUSY",
+ "FORGE_TOOL_ACTION_ADMISSION_REJECTED",
+ "FORGE_TOOL_ENDPOINT_UNKNOWN",
+ "FORGE_TOOL_OPERATION_NOT_FOUND",
+ "FORGE_TOOL_ENDPOINT_UNAVAILABLE",
+ )
+)
+
+
+def _rejected_before_dispatch(exc: Exception) -> bool:
+ """True when the gateway rejected the invoke without dispatching it."""
+ error_code = getattr(exc, "error_code", None)
+ if error_code not in _PRE_DISPATCH_REJECTION_CODES:
+ return False
+ invocation_id, attempt_id = _remote_identity(exc)
+ return invocation_id is None and attempt_id is None
+
+
def _fail_replan(task: AgentTaskRecord, message: str) -> None:
task.status = AgentTaskStatus.FAILED
task.evidence_errors.append(message)
diff --git a/PhyAgentOS/providers/registry.py b/PhyAgentOS/providers/registry.py
index ec4820002..41bf43887 100644
--- a/PhyAgentOS/providers/registry.py
+++ b/PhyAgentOS/providers/registry.py
@@ -238,6 +238,25 @@ def label(self) -> str:
strip_model_prefix=False,
model_overrides=(),
),
+ # Opper: EU-hosted gateway, OpenAI-compatible, pool ids like "claude-sonnet-4-6".
+ # "custom_openai" sends the model id upstream unchanged, so pinned routes such as
+ # "anthropic/claude-sonnet-4-6" keep their vendor prefix.
+ ProviderSpec(
+ name="opper",
+ keywords=("opper",),
+ env_key="OPPER_API_KEY",
+ display_name="Opper",
+ litellm_prefix="custom_openai",
+ skip_prefixes=(),
+ env_extras=(),
+ is_gateway=True,
+ is_local=False,
+ detect_by_key_prefix="",
+ detect_by_base_keyword="opper.ai",
+ default_api_base="https://api.opper.ai/v3/compat",
+ strip_model_prefix=False,
+ model_overrides=(),
+ ),
# === Standard providers (matched by model-name keywords) ===============
# Anthropic: LiteLLM recognizes "claude-*" natively, no prefix needed.
ProviderSpec(
diff --git a/PhyAgentOS/skill_runtime/installer.py b/PhyAgentOS/skill_runtime/installer.py
index 25689a66d..d3739e7fc 100644
--- a/PhyAgentOS/skill_runtime/installer.py
+++ b/PhyAgentOS/skill_runtime/installer.py
@@ -12,6 +12,7 @@
from pathlib import Path
import yaml
+from loguru import logger
from PhyAgentOS.config.paths import get_forge_runtime_root, get_skill_bundle_root
from PhyAgentOS.skill_runtime.archive import (
@@ -265,7 +266,7 @@ def install(self, archive: Path, lock: NodeLock) -> Path:
finally:
shutil.rmtree(temporary, ignore_errors=True)
- def load(self, lock: NodeLock) -> Path:
+ def load(self, lock: NodeLock, *, strict: bool = False) -> Path:
self._verify_lock_host(lock)
install_root = self.root / lock.node_id / "versions" / lock.artifact_id
path = _entrypoint_path(lock, install_root)
@@ -291,17 +292,26 @@ def load(self, lock: NodeLock) -> Path:
):
raise InstallerError("installed Forge node receipt does not match Skill lock")
binary_sha256 = receipt.get("binary_sha256")
- if (
- not isinstance(binary_sha256, str)
- or len(binary_sha256) != 64
- or sha256_file(path) != binary_sha256
- ):
- raise InstallerError("installed Forge node executable sha256 does not match receipt")
+ if not isinstance(binary_sha256, str) or len(binary_sha256) != 64:
+ raise InstallerError("installed Forge node receipt has no usable binary sha256")
+ if sha256_file(path) != binary_sha256:
+ if strict:
+ raise InstallerError(
+ "installed Forge node executable sha256 does not match receipt"
+ )
+ logger.warning(
+ "installed Forge node executable {} sha256 differs from the receipt; "
+ "proceeding with the locally modified file",
+ lock.entrypoint,
+ )
return path
def satisfies(self, lock: NodeLock) -> bool:
try:
- self.load(lock)
+ # Install/cache acceptance must stay strict: a locally modified
+ # executable is not a valid cache hit and must not be reused by a
+ # subsequent install of the original archive.
+ self.load(lock, strict=True)
except InstallerError:
return False
return True
diff --git a/README.md b/README.md
index 68ba25391..fd7f22dad 100644
--- a/README.md
+++ b/README.md
@@ -10,22 +10,20 @@
-
+
English · 简体中文
What ·
Why ·
- v1.1.0 ·
- Quick Start ·
+ v1.1.1 ·
+ Install ·
+ Quickstart ·
Examples ·
- Control Modes ·
- Benchmark ·
- Robot Skills ·
Documentation
- GOSIM Shenzhen 2026 Spotlight · October 16–17 · Meet us in Shenzhen
+ v1.1.1 · Skill development, execution reliability and the Opper gateway
---
@@ -48,28 +46,27 @@
| **Reusable physical capabilities** | Package environment-specific tools and runtimes as versioned Skills, keeping cognitive planning separate from robot integration. |
-## What's new in v1.1.0
+## What's new in v1.1.1
-**Provider management, Skill Runtime and governed interactions.** This release adds:
+**Skill development, execution reliability and the Opper gateway.** Changes since v1.1.0:
-- **Provider management:** centralized configuration, connection tests, authentication, model discovery, saved model selection, and per-session overrides.
-- **More model connections:** direct OpenAI Responses API support for tools, multimodal input, reasoning effort, and Forge verification; Requesty, Cheaper Inference, and API Route gateways.
-- **Skill Runtime updates:** `directory_tar_gz` Node packages with bundled dependencies and validated internal relative symbolic links; profile startup timeouts, `required_tools` overrides, and startup-hook context for LIBERO 0.3.4.
-- **Governed interaction foundation (opt-in):** connect AgentTask and Session to multi-step decisions, independent root verification, and one deduplicated experience episode through frozen bindings, a persistent Runner, and a Supervisor. See [scope and enablement](docs/interaction/README.md).
-- **Reliability improvements:** preserve valid cron jobs, handle Dora status and profile environments, improve archive and image-path handling, and retain conversation history on model failures. Cancellation blocks new execution intents, late decisions are discarded, and uncertain operations retain guards until reconciliation without automatic retransmission.
-- **Guides and validation:** expanded regression and build checks, bilingual documentation, Piper and LIBERO-10 quickstarts, and clearer benchmark scope and results.
+- **Opper gateway:** OpenAI-compatible routing with provider selection, environment credentials and unchanged model identifiers.
+- **Local Skill development:** locally edited workflow documents and Node executables can run with warnings, while bindings and experience retain the activated workflow hash. Explicit Node verification and install-cache acceptance remain strict.
+- **Action rejection handling:** structured pre-dispatch Gateway rejections are recorded as failed and do not block a later retry or successful task finalization. Timeouts and uncertain remote execution retain their existing guards.
+- **Piper X development example:** bilingual Track B guides and an independent simulation Skill example cover model conversion, original Node locks, packaging and recorded validation. See the [Piper X guide](docs/user_development_guide/PIPER_X_DEMO.md) for its original runtime baseline.
+- **Clearer documentation:** consolidated bilingual manuals and contribution guidance, a MuJoCo Quickstart with live GIFs, and retained benchmark documentation links.
-See the [full changelog](CHANGELOG.md) and [changes since v1.0.0](https://github.com/PhyAgentOS/PhyAgentOS-core/compare/v1.0.0...v1.1.0).
+See the [full changelog](CHANGELOG.md) and [changes since v1.1.0](https://github.com/PhyAgentOS/PhyAgentOS-core/compare/v1.1.0...v1.1.1).
-## Quickstart · How to get started
+## Install and configure
-Start with a model-backed CLI conversation, then connect a robot or simulator Skill below. **Prerequisites:** Python 3.11 or 3.12, Git, and an API key for your model provider.
+Start with a model-backed CLI conversation, then follow the [MuJoCo Quickstart](#simulation-quickstart) below. **Prerequisites:** Python 3.11 or 3.12, Git, and an API key for your model provider.
### 1. Install and initialize
```bash
-git clone --branch v1.1.0 https://github.com/PhyAgentOS/PhyAgentOS-core.git
+git clone --branch v1.1.1 https://github.com/PhyAgentOS/PhyAgentOS-core.git
cd PhyAgentOS-core
python -m venv .venv
source .venv/bin/activate
@@ -81,7 +78,6 @@ On Windows PowerShell, replace the activation command with `.venv\Scripts\Activa
### 2. Connect a model
-
Configure credentials with hidden input, then select the default:
```bash
@@ -94,7 +90,7 @@ Docker/secret input, process overrides and session commands (`/provider`, `/mode
Session switches affect subsequent turns only and leave running tasks and other sessions unchanged.
-Full configuration reference (v1.1.0)
+Full configuration reference (v1.1.1)
The configuration file is serialized in camelCase; snake_case keys are also accepted.
@@ -163,120 +159,121 @@ paos agent
You should receive a model response; `paos agent` opens an interactive conversation. This checks the core Agent and provider connection. Physical execution additionally needs a running Skill Runtime.
-Need another provider or deployment option? See the [user manual](docs/en/02-user-manual.md) · [Docker](docs/user_manual/DOCKER_en.md).
+Need another provider or deployment option? See the [user manual](docs/en/02-user-manual.md) · [Docker](docs/user_manual/DOCKER.md).
-
-## One framework, three control modes
+
+
+## Quickstart · Control a robot in MuJoCo
-
+> [!TIP]
+> **Developers: bring your own robot — [Piper X customization demo](docs/user_development_guide/PIPER_X_DEMO.md).**
+> Follow the complete model-to-Skill example for joint and end-effector control. Use the [Skill development manual](docs/user_development_guide/track_b/SKILL_DEVELOPMENT.md) to choose between configuration changes, a new profile and Node development.
-System 1 / System 2 follow the supplied figure’s naming for general-model control and action-model control, respectively.
+Use **`robot-control-sim`** to control a simulated Piper arm through joint targets or
+end-effector poses. Complete the installation and model configuration above first.
+The prebuilt simulation Nodes used here target **Linux x86_64** and require a working
+graphical display or virtual display for MuJoCo and the image viewer.
-These describe integration patterns; model and environment availability depends on the installed Physical Execution Skill. Core does not bundle model weights, simulator assets, or robot drivers.
+### 1. Install Dora
-
-## Benchmark
+v1.1.1 retains the Dora CLI **0.4.1** (`dora-message` **0.7.0**) compatibility baseline:
-Reported task success rates on **LIBERO-Long**, **RoboDojo**, and **RoboTwin**. Purple bars show PhyAgentOS (PAOS); muted bars show public-leaderboard references.
+```bash
+curl --proto '=https' --tlsv1.2 -LsSf \
+ https://github.com/dora-rs/dora/releases/download/v0.4.1/dora-cli-installer.sh | sh
+dora --version
+```
-**Evaluation scope:** LIBERO uses `libero-10` (labeled LIBERO-Long in the figures). RoboDojo and RoboTwin each use 10 randomly sampled tasks; sample counts vary for some models. Public-leaderboard references may use different protocols.
+Dora is required to start the simulation Runtime. See the [Dora installation reference](docs/en/02-user-manual.md#dora-cli-for-managed-skill-profiles) for other installation methods.
-
+### 2. Install robot-control-sim
-
+Set `resourceRegistry.url` in your config, or `PAOS_RESOURCE_REGISTRY_URL`, to a deployment
+that provides `robot-control-sim` and its locked Node artifacts. Then run:
-
+```bash
+paos skill search robot-control-sim
+paos skill install robot-control-sim
+paos skill inspect robot-control-sim
+```
-| PhyAgentOS configuration | LIBERO-10 ↑ | RoboDojo ↑ | RoboTwin ↑ |
-| --- | ---: | ---: | ---: |
-| GPT-6 + π0.5 | 100.00% | 23.30% | 76.70% |
-| DeepSeek 4.1 Flash + π0.5 | 97.22% | 26.70% | 77.80% |
-| GLM 5.3 Flash + π0.5 | 100.00% | 20.00% | 66.70% |
-| Gemini Robotic ER2 + π0.5 | — | — | 80.00% |
-| Kimi-K3 + π0.5 | — | — | 66.70% |
-| Gemini 3.8 Flash + π0.5 | — | — | 66.70% |
-| DeepSeek 4.1 Flash | 82.00% | 8.30% | — |
-| GPT-6 | — | 8.30% | — |
-| GLM 5.3 Flash | — | 2.78% | — |
-| Kimi-K3 | 60.00% | 0.00% | — |
+`inspect` shows the installed version, profiles and dependencies. This example uses
+`mujoco-piper`; `mujoco-franka` and `mujoco-so101` select other robots. For a separately
+obtained Bundle, use `paos skill install /path/to/robot-control-sim.tar.gz --local`;
+its locked Nodes must also be available. Core does not bundle these simulation assets.
-> English translations of the latest maintainer-supplied figures. See [full results, time and token usage, and evaluation context](docs/benchmarks.md). “—” means not reported. To reproduce the LIBERO evaluation, follow the [LIBERO quickstart](example/quickstart/libero-quickstart.md).
+### 3. Start the simulation
-
-## Connect a robot or simulator
+```bash
+paos skill start robot-control-sim --profile mujoco-piper
+paos skill status robot-control-sim
+```
-A **Physical Execution Skill** packages a workflow and its runtime requirements. Install the Skill for your environment, start one of its named profiles, then ask the Agent to use it.
+Wait for the Runtime to report healthy and the simulation camera viewer to open. If startup
+fails, inspect `paos skill logs robot-control-sim` before sending a motion request.
-**1. Install Dora for managed runtimes**
+
-v1.1.0 retains the Dora CLI **0.4.1** (`dora-message` **0.7.0**) compatibility baseline. On Linux/macOS:
+### 4. Control joints and the end effector
-```bash
-curl --proto '=https' --tlsv1.2 -LsSf \
- https://github.com/dora-rs/dora/releases/download/v0.4.1/dora-cli-installer.sh | sh
-dora --version
-```
+The Agent reads `sim.get_robot_info` and live Tool context to determine joints, limits, frames
+and units, then follows the active Skill workflow. The absolute targets below are for
+`mujoco-piper` (`arm_base` / `tcp`); use the selected robot's frames and reachable targets when switching profiles.
-Dora is needed for `paos skill start`; the CLI conversation above does not require it. [Windows and Cargo instructions](docs/en/02-user-manual.md#dora-cli-for-managed-skill-profiles).
+| Control mode | Tool | Target |
+| --- | --- | --- |
+| Joint targets | `sim.set_joint_positions` | Absolute arm joint positions in radians |
+| End-effector pose | `sim.move_eef` | Absolute position in meters and quaternion orientation; the motion server solves IK |
-**2. Find and install a Skill**
+These motion demos use `verification.mode=off`, so success is derived from Tool execution results. For semantic task verification and evidence policies, see the [Core developer manual](docs/en/03-developer-manual.md#7-verification-and-recovery).
-For registry downloads, set `resourceRegistry.url` in your config or export `PAOS_RESOURCE_REGISTRY_URL` to the registry supplied by your deployment. Then run:
+Try a joint-space request:
```bash
-paos skill search
-paos skill install --version
-paos skill inspect
+paos agent -m "Use robot-control-sim (mujoco-piper). Inspect robot info and Tool context. For this \
+ motion demo use verification.mode=off. Move joint1-joint6 to [0.35, 0.55, -0.9, 0.15, \
+ 0.25, -0.1] rad via sim.set_joint_positions, with velocity_scale=0.2 and \
+ acceleration_scale=0.2. Read the action result, finalize the task and report briefly. Do \
+ not edit files or use shell tools; report any failure."
```
-Replace `` and `` with a search result. For an independently obtained local bundle:
+
+
+Then try a Cartesian request:
```bash
-paos skill install /path/to/skill-bundle.tar.gz --local
+paos agent -m "Use robot-control-sim (mujoco-piper). Inspect Tool context. For this motion demo use \
+ verification.mode=off. Call sim.move_eef for TCP in arm_base: position (0.284045, \
+ 0.007878, 0.478706) m, quaternion xyzw (-0.002904, 0.693239, 0.008319, 0.720654), \
+ position_tolerance_m=0.01, orientation_tolerance_rad=0.05, velocity_scale=0.2, \
+ acceleration_scale=0.2. Let the motion server solve IK. Read the action result, finalize \
+ the task and report briefly. Do not edit files or use shell tools; report any failure."
```
-**3. Start the runtime and submit a task**
+
-Replace `` with a profile declared by the installed Skill; follow its setup instructions for models, assets, and hardware.
+*Live recordings of the command and MuJoCo simulation; the captured command panel is held visible and model-wait pauses are shortened.*
-```bash
-paos skill start --profile
-paos skill status
-paos agent -m "Inspect the active Skill and Physical Execution capabilities, then report which tasks are available."
-```
+You can also run `paos agent` for interactive control. Motion should be visible in the simulation;
+read the returned execution result and final state rather than treating admission as completion.
-Once the runtime is healthy, describe a task supported by that Skill in `paos agent`. Starting the Agent does not automatically download or start a runtime.
+### 5. Stop the simulation
-
-Useful runtime commands
+After the motion task has finished:
```bash
-paos skill list
-paos skill logs
-paos skill stop
-paos gateway
+paos skill stop robot-control-sim
```
-`paos gateway` runs configured message channels and background services. For readiness checks and troubleshooting, see the [operations guide](docs/user_manual/README_en.md).
-
-Each Physical Execution Skill bundle declares its workflow document, required Tool IDs, named runtime profiles,
-and exact platform/architecture Node locks. Each locked archive has an exact SHA-256 and contains
-either one named root-level executable (`executable_tar_gz`) or one root directory named after the
-entrypoint that holds the executable and its runtime tree (`directory_tar_gz`). For Registry Node
-downloads, the verified Skill lock supplies the
-digest when the Registry omits that duplicate field, and the exact size is resolved before the
-download begins; installation records and verifies the extracted binary hash.
-`python scripts/package_skill.py --output-dir ` creates a deterministic
-bundle for publication. The PhyAgentOS source and release packages do not
-bundle concrete Physical Execution Skills, Physical Execution nodes, models, or simulation assets; obtain only the Skills
-needed for a deployment and install them explicitly.
-The [integration development guide](docs/user_development_guide/README_en.md#5-package-publish-and-close-the-local-loop)
-documents Bundle layout, local validation, immutable publication order, and Registry acceptance.
+### Extend this example
-
+- [TrackB framework guide](docs/user_development_guide/track_b/README.md): architecture, repository catalog and Node protocols.
+- [Skill development manual](docs/user_development_guide/track_b/SKILL_DEVELOPMENT.md): configure a profile, add a profile, or develop Nodes and assemble a Skill.
+- [Piper X development demo](docs/user_development_guide/PIPER_X_DEMO.md): adapt `robot-control-sim` to another arm, including model conversion and both control modes.
+- [Bundle and Tool integration reference](docs/user_development_guide/README.md): manifest fields, packaging and local installation.
-## Quickstart examples
+## More examples
| Platform | Coverage | Guide |
| --- | --- | --- |
@@ -289,19 +286,23 @@ documents Bundle layout, local validation, immutable publication order, and Regi
| I want to… | Start here |
| --- | --- |
| Install, configure, and run PhyAgentOS | [User manual](docs/en/02-user-manual.md) |
-| Build a Skill or connect an environment | [Integration guide](docs/user_development_guide/README_en.md) |
+| Build a Skill or connect an environment | [TrackB development guide](docs/user_development_guide/track_b/README.md) |
| Understand the Physical Execution API | [Physical Execution Tool API](docs/forge/README.md) |
-| Develop and test Core | [Developer manual](docs/en/03-developer-manual.md) |
-| Inspect benchmark values and provenance | [Benchmark](docs/benchmarks.md) |
+| Extend robot-control-sim to another arm | [Piper X development demo](docs/user_development_guide/PIPER_X_DEMO.md) |
+| Develop and test Core | [Core developer manual](docs/en/03-developer-manual.md) |
+| Inspect benchmark results and evaluation context | [Benchmark documentation](docs/benchmarks.md) |
| Browse all documentation | [Documentation index](docs/README.md) |
## News
+**2026-10-23 · v1.1.1 released:** Opper gateway support, local Skill development and Action rejection fixes, plus bilingual Track B and Piper X guides. [Release notes and packages](https://github.com/PhyAgentOS/PhyAgentOS-core/releases/tag/v1.1.1).
+
**2026-10-10 · GOSIM Shenzhen 2026:** PhyAgentOS has been selected for Spotlight and will present in the Open Source Robotics track. [Read the announcement and event details](docs/news/gosim-shenzhen-2026.md).
| Version | Date | Update |
| --- | --- | --- |
+| **v1.1.1** | 2026-10-23 | Opper gateway, local Skill development and Action rejection fixes, bilingual Track B and Piper X guides, and a MuJoCo Quickstart. |
| **v1.1.0** | 2026-10-09 | Centralized provider management, direct OpenAI Responses and new gateways, Skill Runtime packaging and startup improvements, and an opt-in governed interaction foundation. |
| **v1.0.0** | 2026-08-30 | Initial stable release of PhyAgentOS. |
| **v0.2.3** | 2026-08-27 | Physical Execution Skills can be installed and managed independently, activated into immutable AgentTask bindings, and used through governed Query, Action, and Session Tool API lifecycles with recovery and version-scoped experience. |
@@ -311,7 +312,7 @@ See the [full changelog](CHANGELOG.md).
## Contributing & community
-Contributions are welcome: report a bug, improve a Skill, add an environment integration, or help with documentation. Start with the [developer manual](docs/en/03-developer-manual.md) and open an [issue](https://github.com/PhyAgentOS/PhyAgentOS-core/issues) or pull request.
+Start with the [contribution guide](CONTRIBUTING.md) and the development manuals. We recommend focusing on TrackB Nodes, Skills and robot/environment integrations. External resource-platform submissions and changes to existing registered repositories are not yet open; they require completion and opening of the approval service. Local development and validation can proceed; see the guide for the current scope and source-review process.
Development checks
diff --git a/README_zh.md b/README_zh.md
index 24c02507e..f77cf4e25 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -4,28 +4,26 @@
技术报告 ·
官网 ·
- 文档 ·
+ 文档 ·
Discord
-
+
English · 简体中文
What ·
Why ·
- v1.1.0 ·
- 快速开始 ·
+ v1.1.1 ·
+ 安装配置 ·
+ 仿真 Quickstart ·
快速启动示例 ·
- 控制方式 ·
- Benchmark ·
- 运行机器人技能 ·
文档导航
- GOSIM Shenzhen 2026 Spotlight · 10 月 16–17 日 · 深圳现场见
+ v1.1.1 · Skill 开发、执行可靠性与 Opper 网关
---
@@ -48,28 +46,27 @@
| **可复用的物理执行能力** | 将环境相关工具与 Runtime 封装为版本化 Skill,使认知规划与机器人接入保持解耦。 |
-## v1.1.0 更新亮点
+## v1.1.1 更新亮点
-**Provider 管理、Skill Runtime 与受治理的交互。** 本次版本包含:
+**Skill 开发、执行可靠性与 Opper 网关。** 相对 v1.1.0 的主要变化:
-- **Provider 管理:** 集中配置、连接测试、认证、模型发现、模型选择保存与会话级覆盖。
-- **更多模型接入:** 直接支持 OpenAI Responses API 的工具调用、多模态输入、推理强度与 Forge 验证;新增 Requesty、Cheaper Inference 和 API Route 网关。
-- **Skill Runtime 更新:** `directory_tar_gz` Node 包可携带运行时依赖并校验内部相对符号链接;profile 支持启动超时、`required_tools` 覆盖,以及用于 LIBERO 0.3.4 前置准备的启动 hook 上下文。
-- **受治理的交互基础(默认关闭):** 通过冻结绑定、持久化 Runner 和 Supervisor,将 AgentTask、Session、多步决策、独立根目标验证与一条去重的经验 episode 连接起来。参见[适用范围与启用说明](docs/interaction/README.md)。
-- **可靠性改进:** 保留有效 cron 任务,完善 Dora 状态解析和 profile 环境注入、归档与图片路径处理,并在模型调用失败时保留对话历史。取消后拒绝新的执行意图并丢弃迟到决策;不确定操作不会自动重发,资源保护保持到执行状态完成核对。
-- **指南与验证:** 扩展回归测试和构建检查,完善双语文档、Piper 与 LIBERO-10 快速启动,以及评测范围和结果说明。
+- **Opper 网关:** 新增 OpenAI 兼容接入,支持 Provider 选择、环境变量凭据和原样传递模型标识。
+- **本地 Skill 开发:** 本地修改工作流文档和 Node 可执行文件后可带警告运行,绑定与经验仍记录实际激活的工作流哈希;显式 Node 校验和安装缓存验收保持严格。
+- **Action 拒绝处理:** Gateway 明确在分发前拒绝的请求记为失败,不再阻塞后续重试或成功任务的最终判定;超时和远端执行不确定时仍保留原有保护。
+- **Piper X 开发示例:** 双语 Track B 指南与独立仿真 Skill 示例覆盖模型转换、原始 Node locks、打包和历史验证记录;原始运行基线见 [Piper X 指南](docs/user_development_guide/PIPER_X_DEMO_zh.md)。
+- **文档整理:** 合并双语手册和贡献指南,新增带实时 GIF 的 MuJoCo Quickstart,并保留评测文档入口。
-查看[完整更新记录](CHANGELOG.md)和[相对 v1.0.0 的全部变更](https://github.com/PhyAgentOS/PhyAgentOS-core/compare/v1.0.0...v1.1.0)。
+查看[完整更新记录](CHANGELOG.md)和[相对 v1.1.0 的全部变更](https://github.com/PhyAgentOS/PhyAgentOS-core/compare/v1.1.0...v1.1.1)。
-## Quickstart · 如何开始使用
+## 安装与配置
-先运行模型驱动的 CLI 对话,再按下文接入机器人或仿真 Skill。**准备:** Python 3.11 或 3.12、Git,以及模型服务的 API Key。
+先运行模型驱动的 CLI 对话,再按下文的 [MuJoCo Quickstart](#simulation-quickstart) 操控仿真机器人。**准备:** Python 3.11 或 3.12、Git,以及模型服务的 API Key。
### 1. 安装与初始化
```bash
-git clone --branch v1.1.0 https://github.com/PhyAgentOS/PhyAgentOS-core.git
+git clone --branch v1.1.1 https://github.com/PhyAgentOS/PhyAgentOS-core.git
cd PhyAgentOS-core
python -m venv .venv
source .venv/bin/activate
@@ -81,7 +78,6 @@ Windows PowerShell 请将激活命令替换为 `.venv\Scripts\Activate.ps1`。
### 2. 配置模型
-
通过隐藏输入配置密钥,再选择默认 Provider:
```bash
@@ -94,7 +90,7 @@ Docker/Secret 输入、进程启动覆盖和 `/provider`、`/model`、`/effort`
不改变正在执行的任务及其他会话。
-完整配置参考(v1.1.0)
+完整配置参考(v1.1.1)
配置保存为 camelCase,同时也接受 snake_case 输入。
@@ -162,116 +158,123 @@ paos agent
收到模型回复即完成核心 Agent 与模型服务的连通检查;`paos agent` 会打开交互式对话。执行物理任务还需要启动对应的 Skill Runtime。
-其他模型服务与部署方式见 [用户手册](docs/zh/02-user-manual.md) · [Docker 部署](docs/user_manual/DOCKER.md).
+其他模型服务与部署方式见 [用户手册](docs/zh/02-user-manual.md) · [Docker 部署](docs/user_manual/DOCKER_zh.md).
-
-## 一套执行框架,三种控制方式
+
+
+## Quickstart · 在 MuJoCo 中操控机器人
-
+> [!TIP]
+> **开发者接入自己的机械臂:直接查看 [Piper X 完整二次开发 demo](docs/user_development_guide/PIPER_X_DEMO_zh.md)。**
+> 从模型转换到 Skill 组装,跑通关节与末端位姿控制;配合 [Skill 开发手册](docs/user_development_guide/track_b/SKILL_DEVELOPMENT_zh.md),选择配置修改、新增 profile 或独立 Node 开发。
-图中的 System 1 / System 2 沿用所提供原图的命名,分别指通用模型控制与动作模型控制。
+以 **`robot-control-sim`** 为例,通过关节目标或末端位姿控制仿真 Piper 机械臂。
+请先完成上方安装与模型配置。本例使用的预构建仿真 Node 面向 **Linux x86_64**,
+MuJoCo 和图像查看器需要可用的图形显示或虚拟显示环境。
-以上描述的是接入方式;具体模型与环境取决于安装的 Physical Execution Skill。Core 不捆绑模型权重、仿真资源或机器人驱动。
+### 1. 安装 Dora
-
-## Benchmark
+v1.1.1 沿用 Dora CLI **0.4.1**(`dora-message` **0.7.0**)兼容基线:
-以下展示 **LIBERO-Long**、**RoboDojo** 与 **RoboTwin** 上的任务成功率。深色为 PhyAgentOS(PAOS)结果,浅色为公开榜单参考值。
+```bash
+curl --proto '=https' --tlsv1.2 -LsSf \
+ https://github.com/dora-rs/dora/releases/download/v0.4.1/dora-cli-installer.sh | sh
+dora --version
+```
-**评测口径:** LIBERO 使用 `libero-10`(图中标为 LIBERO-Long);RoboDojo 和 RoboTwin 各随机抽样 10 个任务,部分模型的评测样本量不同。公开榜单参考结果可能采用不同评测协议。
+启动仿真 Runtime 需要 Dora;其他安装方式见 [Dora 安装参考](docs/zh/02-user-manual.md#托管-skill-profile-所需的-dora-cli)。
-
+### 2. 安装 robot-control-sim
-
+在配置中设置 `resourceRegistry.url`,或通过 `PAOS_RESOURCE_REGISTRY_URL` 指向提供
+`robot-control-sim` 及其锁定 Node 制品的部署,再运行:
-
+```bash
+paos skill search robot-control-sim
+paos skill install robot-control-sim
+paos skill inspect robot-control-sim
+```
-| PhyAgentOS 配置 | LIBERO-10 ↑ | RoboDojo ↑ | RoboTwin ↑ |
-| --- | ---: | ---: | ---: |
-| GPT-6 + π0.5 | 100.00% | 23.30% | 76.70% |
-| DeepSeek 4.1 Flash + π0.5 | 97.22% | 26.70% | 77.80% |
-| GLM 5.3 Flash + π0.5 | 100.00% | 20.00% | 66.70% |
-| Gemini Robotic ER2 + π0.5 | — | — | 80.00% |
-| Kimi-K3 + π0.5 | — | — | 66.70% |
-| Gemini 3.8 Flash + π0.5 | — | — | 66.70% |
-| DeepSeek 4.1 Flash | 82.00% | 8.30% | — |
-| GPT-6 | — | 8.30% | — |
-| GLM 5.3 Flash | — | 2.78% | — |
-| Kimi-K3 | 60.00% | 0.00% | — |
+`inspect` 显示已安装版本、profile 与依赖。本例使用 `mujoco-piper`;也可选择
+`mujoco-franka` 或 `mujoco-so101` 切换机器人。独立获取的 Bundle 可用
+`paos skill install /path/to/robot-control-sim.tar.gz --local` 安装,所锁定的 Node 也需可获取。
+Core 不内置这些仿真资源。
-> 使用维护者提供的最新评测原图。完整数值、耗时、Token 消耗与评测口径见 [Benchmark 说明](docs/benchmarks.md);“—”表示未提供。复现 LIBERO 评测见 [LIBERO 快速启动](example/quickstart/libero-quickstart.md)。
+### 3. 启动仿真
-
-## 接入机器人或仿真环境
+```bash
+paos skill start robot-control-sim --profile mujoco-piper
+paos skill status robot-control-sim
+```
-**Physical Execution Skill** 封装工作流及其运行需求。安装环境对应的 Skill、启动其中一个命名 profile 后,即可让 Agent 使用它。
+等待 Runtime 报告健康并打开仿真相机查看器。启动失败时,先通过
+`paos skill logs robot-control-sim` 定位问题,再提交运动请求。
-**1. 为托管 Runtime 安装 Dora**
+
-v1.1.0 沿用 Dora CLI **0.4.1**(`dora-message` **0.7.0**)兼容基线。Linux/macOS:
+### 4. 按关节目标和末端位姿控制
-```bash
-curl --proto '=https' --tlsv1.2 -LsSf \
- https://github.com/dora-rs/dora/releases/download/v0.4.1/dora-cli-installer.sh | sh
-dora --version
-```
+Agent 读取 `sim.get_robot_info` 与实时 Tool context,确认关节、限位、坐标系和单位,
+再按活动 Skill 的工作流执行。下方绝对目标适用于 `mujoco-piper`(`arm_base` / `tcp`);
+切换 profile 时应使用对应机器人的坐标系和可达目标。
-`paos skill start` 需要 Dora,上面的 CLI 对话无需安装。[Windows 与 Cargo 安装说明](docs/zh/02-user-manual.md#托管-skill-profile-所需的-dora-cli)。
+| 控制方式 | Tool | 目标 |
+| --- | --- | --- |
+| 关节目标 | `sim.set_joint_positions` | 机械臂各关节的绝对位置,单位为弧度 |
+| 末端位姿 | `sim.move_eef` | 以米表示的绝对位置及四元数姿态,由 motion server 求解 IK |
-**2. 查找并安装 Skill**
+运动演示使用 `verification.mode=off`,按 Tool 执行结果判断完成;语义任务验证与证据策略见 [Core 开发者手册](docs/zh/03-developer-manual.md#7-verification-与-recovery)。
-从 Registry 下载时,在配置中设置 `resourceRegistry.url`,或将环境变量 `PAOS_RESOURCE_REGISTRY_URL` 指向部署方提供的 Registry,然后运行:
+先尝试关节空间请求:
```bash
-paos skill search
-paos skill install --version
-paos skill inspect
+paos agent -m "使用 robot-control-sim 的 mujoco-piper。 \
+ 检查机器人信息和 Tool context,本次运动演示使用 verification.mode=off。 \
+ 通过 sim.set_joint_positions 将 joint1-joint6 移动到 [0.35, 0.55, -0.9, 0.15, 0.25, -0.1] rad, \
+ velocity_scale 和 acceleration_scale 均为 0.2。 \
+ 读取动作结果、finalize 任务并简要报告。 \
+ 不修改文件、不使用 shell 工具;失败时直接报告。"
```
-将 ``、`` 替换为搜索结果。也可以安装独立获取的本地 Bundle:
+
+
+再尝试末端位姿请求:
```bash
-paos skill install /path/to/skill-bundle.tar.gz --local
+paos agent -m "使用 robot-control-sim 的 mujoco-piper。 \
+ 检查 Tool context,本次运动演示使用 verification.mode=off。 \
+ 调用 sim.move_eef,将 TCP 移到 arm_base 下的位置 (0.284045, 0.007878, 0.478706) m, \
+ 四元数 xyzw 为 (-0.002904, 0.693239, 0.008319, 0.720654), \
+ position_tolerance_m=0.01、orientation_tolerance_rad=0.05, \
+ velocity_scale 和 acceleration_scale 均为 0.2。 \
+ 由 motion server 求解 IK;读取动作结果、finalize 任务并简要报告。 \
+ 不修改文件、不使用 shell 工具;失败时直接报告。"
```
-**3. 启动 Runtime 并提交任务**
+
-将 `` 替换为该 Skill 声明的 profile;模型、资源与硬件准备请遵循对应 Skill 的说明。
+*以上为命令与 MuJoCo 仿真的运行实录,命令画面固定保留以便阅读,并已缩短模型等待停顿。*
-```bash
-paos skill start --profile
-paos skill status
-paos agent -m "Inspect the active Skill and Physical Execution capabilities, then report which tasks are available."
-```
+也可运行 `paos agent` 进入交互控制。应能在仿真中观察到运动;以返回的执行结果和最终状态为准,
+不把请求已接纳当作动作已完成。
-Runtime 健康后,在 `paos agent` 中描述该 Skill 支持的任务。启动 Agent 不会自动下载或启动 Runtime。
+### 5. 停止仿真
-
-常用运行管理命令
+运动任务结束后执行:
```bash
-paos skill list
-paos skill logs
-paos skill stop
-paos gateway
+paos skill stop robot-control-sim
```
-`paos gateway` 运行已配置的消息渠道与后台服务。就绪检查与排障见 [运行手册](docs/user_manual/README.md).
+### 在此基础上二次开发
-每个 Physical Execution Skill Bundle 声明工作流文档、所需 Tool ID、命名 Runtime profile,以及精确的
-平台/架构 Node lock。每个锁定归档具有精确 SHA-256;`executable_tar_gz` 只包含一个指定文件名的
-根目录可执行文件,`directory_tar_gz` 则只包含一个以 entrypoint 命名的根目录(同名可执行文件及
-其运行时树置于其中)。安装时另行记录并校验解包后的 binary hash。
-`python scripts/package_skill.py --output-dir ` 可生成确定性发布 Bundle。
-PhyAgentOS 源码与发布包不内置具体 Physical Execution Skill、Physical Execution node、模型或仿真资源;
-部署者只需独立获取实际需要的 Skill 并显式安装。
-[集成开发指南](docs/user_development_guide/README.md#5-打包发布与本地闭环)说明 Bundle 布局、
-本地验证、不可变发布顺序与 Registry 验收。
-
-
+- [TrackB 框架说明](docs/user_development_guide/track_b/README_zh.md):整体架构、仓库目录与节点协议。
+- [Skill 开发手册](docs/user_development_guide/track_b/SKILL_DEVELOPMENT_zh.md):修改 profile、增加 profile,以及独立开发 Node 并组装 Skill。
+- [Piper X 二次开发 demo](docs/user_development_guide/PIPER_X_DEMO_zh.md):为 `robot-control-sim` 接入另一种机械臂,包含模型转换与两种控制方式。
+- [Bundle 与 Tool 接入参考](docs/user_development_guide/README_zh.md):manifest 字段、打包和本地安装。
-## Quickstart · 快速启动示例
+## 更多示例
| 平台 | 内容 | 指南 |
| --- | --- | --- |
@@ -284,19 +287,23 @@ PhyAgentOS 源码与发布包不内置具体 Physical Execution Skill、Physical
| 我想…… | 阅读入口 |
| --- | --- |
| 安装、配置并运行 PhyAgentOS | [用户手册](docs/zh/02-user-manual.md) |
-| 开发 Skill 或接入新环境 | [集成开发指南](docs/user_development_guide/README.md) |
+| 开发 Skill 或接入新环境 | [TrackB 开发指南](docs/user_development_guide/track_b/README_zh.md) |
| 了解 Physical Execution API | [Physical Execution Tool API](docs/forge/README_zh.md) |
-| 开发与测试 Core | [开发者手册](docs/zh/03-developer-manual.md) |
-| 查看测评数值与来源 | [Benchmark](docs/benchmarks.md) |
-| 浏览全部文档 | [文档索引](docs/README.md) |
+| 为 robot-control-sim 接入另一种机械臂 | [Piper X 二次开发 demo](docs/user_development_guide/PIPER_X_DEMO_zh.md) |
+| 开发与测试 Core | [Core 开发者手册](docs/zh/03-developer-manual.md) |
+| 查看测评结果与评测口径 | [Benchmark 文档](docs/benchmarks.md) |
+| 浏览全部文档 | [文档索引](docs/README_zh.md) |
## News · 最新动态
+**2026-10-23 · v1.1.1 发布:** 新增 Opper 网关,完善本地 Skill 开发和 Action 拒绝处理,并补充双语 Track B 与 Piper X 开发指南。[查看发布说明与安装包](https://github.com/PhyAgentOS/PhyAgentOS-core/releases/tag/v1.1.1)。
+
**2026-10-10 · GOSIM Shenzhen 2026:** PhyAgentOS 入选 Spotlight,并将在开源机器人分论坛做主题分享。[查看活动公告与现场信息](docs/news/gosim-shenzhen-2026_zh.md)。
| 版本 | 日期 | 更新 |
| --- | --- | --- |
+| **v1.1.1** | 2026-10-23 | Opper 网关、本地 Skill 开发与 Action 拒绝处理修复、双语 Track B 和 Piper X 指南,以及 MuJoCo Quickstart。 |
| **v1.1.0** | 2026-10-09 | 集中式 Provider 管理、直接 OpenAI Responses 与新网关接入、Skill Runtime 打包和启动改进,以及默认关闭的受治理交互基础。 |
| **v1.0.0** | 2026-08-30 | Initial stable release of PhyAgentOS. |
| **v0.2.3** | 2026-08-27 | Physical Execution Skill 可独立安装和管理,经显式激活冻结到 AgentTask,并通过受治理的 Query、Action、Session Tool API 生命周期执行,支持恢复和按版本限定的经验。 |
@@ -306,7 +313,7 @@ PhyAgentOS 源码与发布包不内置具体 Physical Execution Skill、Physical
## 参与贡献与社区
-欢迎报告问题、改进 Skill、接入新环境或完善文档。请先阅读[开发者手册](docs/zh/03-developer-manual.md),再提交 [Issue](https://github.com/PhyAgentOS/PhyAgentOS-core/issues) 或 Pull Request。
+请先阅读[贡献指南](CONTRIBUTING_zh.md)与开发手册,建议优先参与 TrackB 的 Node、Skill 和机器人/环境接入开发。资源平台的外部贡献提交及已有登记仓库修改暂未开放,需等待审批服务完成并开放后支持;现阶段可进行本地开发验证,具体范围与源码评审流程见贡献指南。
开发检查命令
diff --git a/bridge/package-lock.json b/bridge/package-lock.json
index 4bb56d613..c4e0bdb33 100644
--- a/bridge/package-lock.json
+++ b/bridge/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "PhyAgentOS-whatsapp-bridge",
- "version": "0.1.0",
+ "version": "1.1.1",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "PhyAgentOS-whatsapp-bridge",
- "version": "0.1.0",
+ "version": "1.1.1",
"dependencies": {
"@whiskeysockets/baileys": "7.0.0-rc14",
"pino": "^9.0.0",
diff --git a/bridge/package.json b/bridge/package.json
index 92c235e40..cf8a5945f 100644
--- a/bridge/package.json
+++ b/bridge/package.json
@@ -1,6 +1,6 @@
{
"name": "PhyAgentOS-whatsapp-bridge",
- "version": "0.1.0",
+ "version": "1.1.1",
"description": "WhatsApp bridge for PhyAgentOS using Baileys",
"type": "module",
"main": "dist/index.js",
diff --git a/docs/README.md b/docs/README.md
index 0c8e6beb4..ffcce2991 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,97 +1,58 @@
# PhyAgentOS Documentation
-版本 / Version: **1.0.0**
-实现基线 / Implementation baseline: **Forge Skill binding, Query/Action/Session Tool API, AgentTask recovery, and version-scoped experience, 2026-08-30**
+[English](README.md) | [简体中文](README_zh.md)
-本目录由 PhyAgentOS 开发团队面向用户、运维人员和生态开发者维护。文档只把仓库源码、配置 Schema 与测试实际覆盖的行为称为“当前能力”。`plan/` 中的设计报告是历史背景,不替代这里的运行契约。
+Version: **1.1.1**
+Implementation baseline: **Forge Skill binding, Query/Action/Session Tool API, AgentTask recovery, and version-scoped experience, 2026-10-23**
-The PhyAgentOS team maintains this directory for users, operators, and ecosystem developers. A feature is described as current only when it is supported by repository source, configuration schemas, and tests. Historical reports under `plan/` provide design context but do not replace the operational contract documented here.
+This directory serves users, operators and developers. Source, schemas and tests define current behavior; historical design reports do not replace runtime contracts.
+Start development with the [contribution guide](../CONTRIBUTING.md) → [TrackB overview](user_development_guide/track_b/README.md) → [three extension modes](user_development_guide/track_b/SKILL_DEVELOPMENT.md) → [Piper X example](user_development_guide/PIPER_X_DEMO.md).
+External platform submissions and changes to existing registered repositories must wait for completion and opening of the approval service; local development and validation can proceed.
-## 中文
-
-### 核心手册
-
-1. [框架介绍](zh/01-framework-introduction.md):项目定位、控制面边界、执行—证据—判定分离、生命周期与实现范围。
-2. [用户手册](zh/02-user-manual.md):安装、Provider/Forge 配置、任务描述、验证模式、Artifact 与排障。
-3. [开发者手册](zh/03-developer-manual.md):AgentTask、Tool API client、Skill Runtime、Evidence、Verifier、Recovery 与测试。
-4. [Forge 配置参考](zh/04-forge-configuration-reference.md):Forge Tool API、Resource Registry、Evidence、Verification、AgentTask 和 Embodiment 字段。
-5. [Agent 经验与 Skill 自进化](zh/05-agent-experience-and-skill-evolution.md):Skill 激活与归因、Episode、Lesson 聚类、Skill 晋升、持久化和安全门控。
-
-### 专题手册
-
-- [Game 接入前通用交互基础](interaction/README.md):可选协议、真实任务治理、后台 Runner、恢复安全门及假环境验收。
-
-- [运行手册](user_manual/README.md):上线前检查、启动顺序、状态观测、取消、重启恢复、备份与故障分层。
-- [Docker 部署指南](user_manual/DOCKER.md):基于 Docker 的快速部署,配合一键脚本完成构建、初始化与运行(仅外连网关,无入站端口)。
-- [集成开发指南](user_development_guide/README.md):Tool/Node/Skill 接入、Bundle 打包与不可变发布、本地闭环、证据源、Provider 和 PAOS 扩展边界。
-- [通信架构](user_development_guide/COMMUNICATION.md):Agent 消息、Forge HTTP/WebSocket、system event、SQLite 与 Artifact 边界。
-- [Forge Tool API 接入契约](forge/README_zh.md):Query/Action/Session、不可变 Skill binding、ToolInvocation、AgentTask、证据、验证、恢复和 Skill Runtime 契约。
-
-### 推荐阅读路径
-
-| 目标 | 建议路径 |
-|:-----|:---------|
-| 先理解项目为何区分执行与任务成功 | [框架介绍](zh/01-framework-introduction.md) → [Forge 接入契约](forge/README_zh.md) |
-| 首次部署并跑通 Agent + Forge | [用户手册](zh/02-user-manual.md) → [配置参考](zh/04-forge-configuration-reference.md) |
-| 负责长期在线和故障处理 | [运行手册](user_manual/README.md) → [通信架构](user_development_guide/COMMUNICATION.md) |
-| 用 Docker 快速部署 | [Docker 部署指南](user_manual/DOCKER.md) |
-| 在 Gateway 增加新机器人动作 | [集成开发指南](user_development_guide/README.md) → [开发者手册](zh/03-developer-manual.md) |
-| 开发、打包并发布 Forge Skill | [集成开发指南](user_development_guide/README.md#5-打包发布与本地闭环) → [Forge 接入契约](forge/README_zh.md) |
-| 修改证据、验证、恢复或持久化 | [开发者手册](zh/03-developer-manual.md) → [Forge 接入契约](forge/README_zh.md) |
-| 使用或扩展任务经验、Lesson 与 Skill 自进化 | [Agent 经验与 Skill 自进化](zh/05-agent-experience-and-skill-evolution.md) → [开发者手册](zh/03-developer-manual.md) |
-
-## English
-
-### Core manuals
+## Core manuals
1. [Framework Introduction](en/01-framework-introduction.md): positioning, control-plane boundaries, execution/evidence/verdict separation, lifecycle, and implemented scope.
2. [User Manual](en/02-user-manual.md): installation, provider and Forge configuration, task description, verification modes, artifacts, and troubleshooting.
-3. [Developer Manual](en/03-developer-manual.md): AgentTask, Tool API client, Skill Runtime, evidence, verifier, recovery, and testing.
+3. [Core Developer Manual](en/03-developer-manual.md): AgentTask, Tool API client, Skill Runtime, evidence, verifier, recovery, and testing.
4. [Forge Configuration Reference](en/04-forge-configuration-reference.md): exact Forge Tool API, Resource Registry, evidence, verification, AgentTask, and embodiment fields.
5. [Agent Experience and Skill Evolution](en/05-agent-experience-and-skill-evolution.md): Skill activation and attribution, episodes, Lesson clustering, Skill promotion, persistence, and guardrails.
-### Focused manuals
+## Focused manuals
+
+- [Benchmark documentation](benchmarks.md): results, time and token usage, and evaluation context.
- [Governed Interaction Foundation](interaction/README.md): opt-in contracts, task governance, background monitoring, recovery gates and fake-world acceptance.
-- [Operations Manual](user_manual/README_en.md): preflight checklist, startup order, observation, cancellation, restart recovery, backup, and failure layers.
-- [Docker Deployment Guide](user_manual/DOCKER_en.md): Docker-based quick deployment with a one-click script for build, init, and run (outbound-only gateway, no inbound port).
-- [Integration Development Guide](user_development_guide/README_en.md): Tool, Node, and Skill integration; Bundle packaging and immutable publication; the local loop; evidence sources; providers; and PAOS extension boundaries.
-- [Communication Architecture](user_development_guide/COMMUNICATION_en.md): Agent messages, Forge HTTP/WebSocket, system events, SQLite, and artifact boundaries.
+- [Operations Manual](user_manual/README.md): preflight checklist, startup order, observation, cancellation, restart recovery, backup, and failure layers.
+- [Docker Deployment Guide](user_manual/DOCKER.md): Docker-based quick deployment with a one-click script for build, init, and run (outbound-only gateway, no inbound port).
+- [Bundle and Tool Integration Reference](user_development_guide/README.md): ToolSpec and manifest-v2 examples, startup hooks, Bundle packaging, the local loop and conformance checks.
+- [Core Communication Architecture](user_development_guide/COMMUNICATION.md): Agent messages, Forge HTTP/WebSocket, system events, SQLite, and artifact boundaries.
- [Forge Tool API Integration Contract](forge/README.md): Query/Action/Session, immutable Skill binding, ToolInvocation, AgentTask, evidence, verification, recovery, and Skill Runtime contracts.
-### Suggested reading paths
+- [TrackB framework guide](user_development_guide/track_b/README.md).
+- [Piper X development demo](user_development_guide/PIPER_X_DEMO.md).
+
+## Suggested reading paths
| Goal | Suggested path |
|:-----|:---------------|
| Understand why execution and task success differ | [Framework Introduction](en/01-framework-introduction.md) → [Forge Integration Contract](forge/README.md) |
| Deploy Agent + Forge for the first time | [User Manual](en/02-user-manual.md) → [Configuration Reference](en/04-forge-configuration-reference.md) |
-| Operate a long-running service | [Operations Manual](user_manual/README_en.md) → [Communication Architecture](user_development_guide/COMMUNICATION_en.md) |
-| Deploy quickly with Docker | [Docker Deployment Guide](user_manual/DOCKER_en.md) |
-| Add a new robot action in Gateway | [Integration Guide](user_development_guide/README_en.md) → [Developer Manual](en/03-developer-manual.md) |
-| Develop, package, and publish a Forge Skill | [Integration Guide](user_development_guide/README_en.md#5-package-publish-and-close-the-local-loop) → [Forge Integration Contract](forge/README.md) |
-| Change evidence, verification, recovery, or persistence | [Developer Manual](en/03-developer-manual.md) → [Forge Integration Contract](forge/README.md) |
-| Use or extend task experience, Lessons, or Skill evolution | [Agent Experience and Skill Evolution](en/05-agent-experience-and-skill-evolution.md) → [Developer Manual](en/03-developer-manual.md) |
-
-## Terminology
-
-| Term | Meaning |
-|:-----|:--------|
-| AgentTask | The PAOS aggregate for a user-visible goal, immutable PlanRevisions, bound calls, evidence, and verification. It does not execute the robot. |
-| PlanRevision | One append-only planning generation inside a stable AgentTask identity. |
-| Query record | The PAOS record of one synchronous Gateway Query bound to an AgentTask. |
-| Forge Skill binding | An immutable snapshot of Skill version, Runtime identity, manifest/workflow hashes, and required live ToolSpecs. |
-| ToolInvocation | The Gateway-owned identity and lifecycle of one asynchronous Action or Session. |
-| Attempt | The Gateway execution attempt identified separately from the ToolInvocation and AgentTask. |
-| Tool execution record | A normalized PAOS Query result or Action/Session invocation reference attached to one PlanRevision. |
-| Evidence Bundle | Validated, workspace-relative artifact references and capture-quality metadata. |
-| Verdict | A structured semantic decision over every success criterion. |
-| Task lineage | One AgentTask and all of its PlanRevisions; only one AgentTask may be non-terminal globally. |
-| Skill activation | An explicit, per-turn binding between a registered workflow Skill and a task; a direct file read is not an activation. |
-| Task episode | One redacted experience record for a completed, semantically verified AgentTask lineage. |
-| Failure observation | A normalized, non-answer-specific description of a workflow-related failure pattern. |
-| Lesson cluster | Independent AgentTask observations grouped by Skill, workflow, and canonical failure pattern. |
-| Scoped Lesson | A validated Lesson with explicit applicability boundaries, dynamically loaded only for a matching activated Skill. |
+| Operate a long-running service | [Operations Manual](user_manual/README.md) → [Core Communication Architecture](user_development_guide/COMMUNICATION.md) |
+| Deploy quickly with Docker | [Docker Deployment Guide](user_manual/DOCKER.md) |
+| Add a new robot action in Gateway | [TrackB development manual](user_development_guide/track_b/SKILL_DEVELOPMENT.md) → [Node protocols](user_development_guide/track_b/PROTOCOLS.md) |
+| Develop and package a Forge Skill; publish when available | [TrackB Skill development](user_development_guide/track_b/SKILL_DEVELOPMENT.md) → [Bundle reference](user_development_guide/README.md#5-package-publish-and-close-the-local-loop) |
+| Change evidence, verification, recovery, or persistence | [Core Developer Manual](en/03-developer-manual.md) → [Forge Integration Contract](forge/README.md) |
+| Use or extend task experience, Lessons, or Skill evolution | [Agent Experience and Skill Evolution](en/05-agent-experience-and-skill-evolution.md) → [Core Developer Manual](en/03-developer-manual.md) |
+
+## Documentation ownership
+
+- Core developer manual: modules, transactions, verification and Runtime implementation.
+- Forge Tool API contract: canonical HTTP routes, identities and invocation/task semantics.
+- TrackB: Node protocols, source catalog, assembly relationships and Skill development modes.
+- Bundle and Tool integration reference: schemas, manifest, startup hooks, packaging and conformance.
+- Core communication reference: Agent bus, observation, verification-service and storage boundaries.
+- Operations and Docker manuals: deployment/runbooks; interaction remains a separate restricted extension.
## Runtime and compatibility boundaries
diff --git a/docs/README_zh.md b/docs/README_zh.md
new file mode 100644
index 000000000..dc375e420
--- /dev/null
+++ b/docs/README_zh.md
@@ -0,0 +1,62 @@
+# PhyAgentOS 文档
+
+[English](README.md) | [简体中文](README_zh.md)
+
+版本:**1.1.1**
+实现基线:**Forge Skill binding、Query/Action/Session Tool API、AgentTask recovery、版本作用域经验,2026-10-23**
+
+本目录面向用户、运维和开发者。源码、配置 Schema 与测试定义当前行为;历史设计报告不替代运行契约。
+开发从[贡献指南](../CONTRIBUTING_zh.md) → [TrackB 总览](user_development_guide/track_b/README_zh.md) → [三种开发模式](user_development_guide/track_b/SKILL_DEVELOPMENT_zh.md) → [Piper X 示例](user_development_guide/PIPER_X_DEMO_zh.md)进入。
+外部平台贡献提交及已有登记仓库修改需等待审批服务完成并开放,当前可先本地开发验证。
+
+## 核心手册
+
+1. [框架介绍](zh/01-framework-introduction.md):项目定位、控制面边界、执行—证据—判定分离、生命周期与实现范围。
+2. [用户手册](zh/02-user-manual.md):安装、Provider/Forge 配置、任务描述、验证模式、Artifact 与排障。
+3. [Core 开发者手册](zh/03-developer-manual.md):AgentTask、Tool API client、Skill Runtime、Evidence、Verifier、Recovery 与测试。
+4. [Forge 配置参考](zh/04-forge-configuration-reference.md):Forge Tool API、Resource Registry、Evidence、Verification、AgentTask 和 Embodiment 字段。
+5. [Agent 经验与 Skill 自进化](zh/05-agent-experience-and-skill-evolution.md):Skill 激活与归因、Episode、Lesson 聚类、Skill 晋升、持久化和安全门控。
+
+## 专题手册
+
+- [Benchmark 文档](benchmarks.md):测评结果、耗时、Token 消耗与评测口径。
+
+- [Game 接入前通用交互基础](interaction/README_zh.md):可选协议、真实任务治理、后台 Runner、恢复安全门及假环境验收。
+
+- [运行手册](user_manual/README_zh.md):上线前检查、启动顺序、状态观测、取消、重启恢复、备份与故障分层。
+- [Docker 部署指南](user_manual/DOCKER_zh.md):基于 Docker 的快速部署,配合一键脚本完成构建、初始化与运行(仅外连网关,无入站端口)。
+- [Bundle 与 Tool 接入参考](user_development_guide/README_zh.md):ToolSpec 与 manifest v2 示例、启动 hook、Bundle 打包、本地闭环及接口一致性检查。
+- [Core 通信架构](user_development_guide/COMMUNICATION_zh.md):Agent 消息、Forge HTTP/WebSocket、system event、SQLite 与 Artifact 边界。
+- [Forge Tool API 接入契约](forge/README_zh.md):Query/Action/Session、不可变 Skill binding、ToolInvocation、AgentTask、证据、验证、恢复和 Skill Runtime 契约。
+
+- [TrackB 框架说明](user_development_guide/track_b/README_zh.md):整体架构、仓库目录、公共协议、Runtime 关系和三种 Skill 开发模式。
+- [Piper X 二次开发 demo](user_development_guide/PIPER_X_DEMO_zh.md):复用原 pipeline 接入新机械臂。
+
+## 推荐阅读路径
+
+| 目标 | 建议路径 |
+|:-----|:---------|
+| 先理解项目为何区分执行与任务成功 | [框架介绍](zh/01-framework-introduction.md) → [Forge 接入契约](forge/README_zh.md) |
+| 首次部署并跑通 Agent + Forge | [用户手册](zh/02-user-manual.md) → [配置参考](zh/04-forge-configuration-reference.md) |
+| 负责长期在线和故障处理 | [运行手册](user_manual/README_zh.md) → [Core 通信架构](user_development_guide/COMMUNICATION_zh.md) |
+| 用 Docker 快速部署 | [Docker 部署指南](user_manual/DOCKER_zh.md) |
+| 在 Gateway 增加新机器人动作 | [TrackB 开发手册](user_development_guide/track_b/SKILL_DEVELOPMENT_zh.md) → [节点协议](user_development_guide/track_b/PROTOCOLS_zh.md) |
+| 开发与打包 Forge Skill,开放后发布 | [TrackB Skill 开发](user_development_guide/track_b/SKILL_DEVELOPMENT_zh.md) → [Bundle 参考](user_development_guide/README_zh.md#5-打包发布与本地闭环) |
+| 修改证据、验证、恢复或持久化 | [Core 开发者手册](zh/03-developer-manual.md) → [Forge 接入契约](forge/README_zh.md) |
+| 使用或扩展任务经验、Lesson 与 Skill 自进化 | [Agent 经验与 Skill 自进化](zh/05-agent-experience-and-skill-evolution.md) → [Core 开发者手册](zh/03-developer-manual.md) |
+
+## 文档分工
+
+- Core 开发者手册维护模块、事务、验证和 Runtime 实现。
+- Forge Tool API 契约统一维护 HTTP 路由、身份和 invocation/task 语义。
+- TrackB 维护节点协议、源码目录、组装关系和三种 Skill 开发流程。
+- Bundle 与 Tool 接入参考维护 schema、manifest、启动 hook、打包和接口一致性检查。
+- Core 通信架构维护 Agent bus、观测、验证服务和持久化边界。
+- 运行与 Docker 手册维护部署和运行步骤;交互基础作为独立受限扩展。
+
+## Runtime 与兼容边界
+
+PAOS 通过 `/tools` 与 `/invocations` 支持 Query、Action 和 Session。AgentTask 负责 Agent 侧聚合,
+物理执行由 Gateway ToolInvocation 与 ToolEndpoint 拥有。Skill Runtime 管理 manifest v2 Bundle
+及命名 Dora profile,与已移除的 Markdown 队列 Runtime 不同。既有经验、演化、验证及工作区数据
+原位读取;Registry 下载显式进行并校验摘要。
diff --git a/docs/RELEASING.md b/docs/RELEASING.md
new file mode 100644
index 000000000..deaac56ac
--- /dev/null
+++ b/docs/RELEASING.md
@@ -0,0 +1,85 @@
+# Releasing PhyAgentOS to GitHub and PyPI
+
+[English](RELEASING.md) | [简体中文](RELEASING_zh.md)
+
+`release-build.yml` builds and tests a tag. `publish-pypi.yml` publishes the
+**existing GitHub Release wheel and source distribution** to `PhyAgentOS-ai` on
+PyPI, then checks their hashes and installs from the official index in a fresh
+Python 3.12 environment. It does not rebuild the package or upload `SHA256SUMS`.
+
+## One-time authentication
+
+Configure the repository Actions secret `PYPI_API_TOKEN` with a PyPI API token
+authorized to publish `PhyAgentOS-ai`. Prefer a token scoped to this project.
+The `pypi` job environment identifies production publication; the token is used
+only in the publish job. Never commit a token or paste it into a workflow input.
+
+## Publish a new version
+
+1. Update the package/runtime/bridge versions, README badges, release highlights,
+ News, changelog and versioned installation examples. Review and merge the
+ release changes from `dev` into `main`.
+2. Create an **annotated** `vMAJOR.MINOR.PATCH` tag on the intended release commit,
+ following the previous release's annotation format. The tagged tree must
+ contain the publishing workflow. Do not move a published tag.
+3. Wait for **Build release package** to succeed. Download its
+ `phyagentos-vMAJOR.MINOR.PATCH` artifact containing the wheel, source archive
+ and `SHA256SUMS`.
+4. Create a **draft** GitHub Release for that tag and attach all three files
+ unchanged. Complete the release notes before publishing the draft as a
+ stable release. Attach the files **before** clicking Publish release.
+5. The `release: published` event starts **Publish release to PyPI**. Confirm all
+ three jobs (`prepare`, `publish`, `verify`) succeed before announcing PyPI
+ availability. Drafts and prereleases are excluded.
+
+This keeps tag/build/release-note decisions with maintainers while making PyPI
+publication and verification automatic. A GitHub Release created by another
+workflow using `GITHUB_TOKEN` does **not** trigger a new release workflow. Such
+automation must explicitly dispatch `publish-pypi.yml` after attaching assets,
+or use an appropriately authorized GitHub App/PAT to publish the release.
+
+## Retry or backfill a release
+
+Use Actions → **Publish release to PyPI** → **Run workflow**, choose `main` and
+enter the existing stable release tag. The CLI equivalent is:
+
+```sh
+gh workflow run publish-pypi.yml \
+ --repo PhyAgentOS/PhyAgentOS-core --ref main -f tag=v1.1.1
+```
+
+The workflow requires all three GitHub Release attachments, checks SHA256 and
+the package name/version embedded in both distributions, then checks PyPI:
+
+- Identical existing files are skipped; registry and clean-install checks still run.
+- A partial upload resumes with only the missing distribution.
+- Conflicting bytes, yanked files, unexpected files or invalid metadata fail the
+ run. Fix the release inputs or publish a new version; never overwrite a PyPI version.
+- Missing credentials or a PyPI failure fail the run visibly. Rerun after fixing
+ the cause; no package version bump is needed for an unchanged retry.
+
+An idempotent run of an already published version verifies the workflow and
+installation but does not exercise a new authenticated upload.
+
+## Optional migration to Trusted Publishing
+
+The initial integration uses the existing API token. To remove the long-lived
+secret later, add a GitHub Trusted Publisher in the PyPI project's **Publishing**
+settings with these exact values:
+
+| Field | Value |
+| --- | --- |
+| Owner | `PhyAgentOS` |
+| Repository | `PhyAgentOS-core` |
+| Workflow filename | `publish-pypi.yml` |
+| Environment | `pypi` |
+
+Then update only the `publish` job: add `permissions: {id-token: write, contents: read}`,
+remove the credential-check step and the action's `password` input, and remove
+`attestations: false` to enable attestations. After a successful authenticated
+publication, remove the GitHub secret and revoke the old token in PyPI. Do not
+remove the secret before switching the workflow and configuring the publisher.
+
+References: [PyPA publishing action](https://github.com/pypa/gh-action-pypi-publish),
+[PyPI Trusted Publisher configuration](https://docs.pypi.org/trusted-publishers/adding-a-publisher/),
+[GitHub workflow trigger behavior](https://docs.github.com/en/actions/how-tos/writing-workflows/choosing-when-your-workflow-runs/triggering-a-workflow#triggering-a-workflow-from-a-workflow).
diff --git a/docs/RELEASING_zh.md b/docs/RELEASING_zh.md
new file mode 100644
index 000000000..f879367b7
--- /dev/null
+++ b/docs/RELEASING_zh.md
@@ -0,0 +1,71 @@
+# PhyAgentOS GitHub 与 PyPI 发布流程
+
+[English](RELEASING.md) | [简体中文](RELEASING_zh.md)
+
+`release-build.yml` 负责构建并测试 tag。`publish-pypi.yml` 将 **GitHub Release 中已有的
+wheel 与源码包**上传到 PyPI 的 `PhyAgentOS-ai` 项目,再核对哈希并在全新的 Python 3.12
+环境中从官方索引安装。发布阶段不重新构建,也不向 PyPI 上传 `SHA256SUMS`。
+
+## 一次性认证配置
+
+在仓库 Actions secrets 中配置 `PYPI_API_TOKEN`,使用有权发布 `PhyAgentOS-ai` 的 PyPI API
+token,优先使用仅限该项目的 token。`pypi` environment 标识正式发布,token 仅在上传 job
+使用。不要将 token 提交到仓库或填入工作流输入参数。
+
+## 发布新版本
+
+1. 同步更新 Python 包、运行时、bridge 的版本号,以及 README 徽章、发布亮点、News、
+ changelog 和带版本的安装示例。审核并将发布改动从 `dev` 合并到 `main`。
+2. 在确定的发布提交上创建 **annotated tag**,格式为 `v主版本.次版本.补丁版本`,annotation
+ 延续上一版本的格式。tag 对应代码树必须包含发布工作流;不要移动已发布的 tag。
+3. 等待 **Build release package** 成功,下载其 `phyagentos-v主版本.次版本.补丁版本`
+ artifact,包含 wheel、源码包和 `SHA256SUMS`。
+4. 为该 tag 创建 GitHub **草稿 Release**,原样附加上述三个文件,完成发布说明后再发布为
+ 正式版本。务必在点击 Publish release **之前**上传附件。
+5. `release: published` 事件会自动启动 **Publish release to PyPI**。确认 `prepare`、
+ `publish`、`verify` 三个 job 均成功后,再宣布 PyPI 可用。草稿与预发布版本不触发上传。
+
+tag、构建和发布说明仍由维护者确认,PyPI 上传与验证自动完成。如果后续用另一个 workflow
+的 `GITHUB_TOKEN` 创建 Release,该事件**不会**再触发发布工作流;需要在附件上传完成后
+显式 dispatch `publish-pypi.yml`,或使用获得相应授权的 GitHub App/PAT 发布 Release。
+
+## 重试与补发
+
+进入 Actions → **Publish release to PyPI** → **Run workflow**,选择 `main`,输入已有的
+正式 Release tag。也可以运行:
+
+```sh
+gh workflow run publish-pypi.yml \
+ --repo PhyAgentOS/PhyAgentOS-core --ref main -f tag=v1.1.1
+```
+
+工作流要求 GitHub Release 的三个附件齐全,核对 SHA256、包内项目名称和版本,再查询 PyPI:
+
+- 文件已存在且哈希一致:跳过上传,仍检查线上哈希并重新安装验证。
+- 仅部分上传成功:重试时只上传缺失的文件。
+- 同名文件内容冲突、文件被 yank、出现非预期文件或元数据不符:明确失败。修复输入或发布
+ 新版本,不覆盖已有 PyPI 版本。
+- 凭据缺失或 PyPI 服务异常:运行明确失败;修复原因后重试,同一份制品无需提高版本号。
+
+对已发布版本的重复运行可以验证流程及安装,但不代表完成了一次新的认证上传。
+
+## 后续切换到 Trusted Publishing
+
+本次接入使用已有 API token。若后续希望取消长期 secret,可在 PyPI 项目的 **Publishing**
+设置中添加 GitHub Trusted Publisher,准确填写:
+
+| 字段 | 值 |
+| --- | --- |
+| Owner | `PhyAgentOS` |
+| Repository | `PhyAgentOS-core` |
+| Workflow filename | `publish-pypi.yml` |
+| Environment | `pypi` |
+
+然后只调整 `publish` job:添加 `permissions: {id-token: write, contents: read}`,移除凭据
+检查步骤及 action 的 `password` 参数,并移除 `attestations: false` 以启用证明文件。完成
+一次认证发布后,再删除 GitHub secret 并在 PyPI 撤销旧 token。不要先删除 secret 再配置
+publisher 和修改工作流。
+
+参考:[PyPA 发布 Action](https://github.com/pypa/gh-action-pypi-publish)、
+[PyPI Trusted Publisher 配置](https://docs.pypi.org/trusted-publishers/adding-a-publisher/)、
+[GitHub 工作流触发规则](https://docs.github.com/en/actions/how-tos/writing-workflows/choosing-when-your-workflow-runs/triggering-a-workflow#triggering-a-workflow-from-a-workflow)。
diff --git a/docs/benchmarks.md b/docs/benchmarks.md
index 956658394..701c80485 100644
--- a/docs/benchmarks.md
+++ b/docs/benchmarks.md
@@ -1,6 +1,6 @@
# Benchmark results / 测评结果
-[English README](../README.md#benchmarks) · [中文 README](../README_zh.md#benchmarks)
+[English README](../README.md) · [中文 README](../README_zh.md)
Values are transcribed from the three latest benchmark screenshots supplied by the maintainer. Model labels, ordering, and source categories follow the figures. PAOS entries are PhyAgentOS results; muted entries are labeled as public-leaderboard references in the source figures.
diff --git a/docs/en/01-framework-introduction.md b/docs/en/01-framework-introduction.md
index bc57bbb26..6fbf24561 100644
--- a/docs/en/01-framework-introduction.md
+++ b/docs/en/01-framework-introduction.md
@@ -2,7 +2,7 @@
[中文](../zh/01-framework-introduction.md) · [Documentation index](../README.md)
-> Documentation version: 1.0.0 · implementation baseline: 2026-08-30 source, schemas, and tests.
+> Documentation version: 1.1.1 · implementation baseline: 2026-10-23 source, schemas, and tests.
## 1. Positioning
@@ -173,6 +173,6 @@ outside the implemented contract.
## Next reading
- [User Manual](02-user-manual.md)
-- [Developer Manual](03-developer-manual.md)
+- [Core Developer Manual](03-developer-manual.md)
- [Forge Tool API Integration Contract](../forge/README.md)
- [Agent Experience and Skill Evolution](05-agent-experience-and-skill-evolution.md)
diff --git a/docs/en/02-user-manual.md b/docs/en/02-user-manual.md
index fbf3f51e1..c34f45e83 100644
--- a/docs/en/02-user-manual.md
+++ b/docs/en/02-user-manual.md
@@ -2,7 +2,7 @@
[中文](../zh/02-user-manual.md) · [Documentation index](../README.md)
-> Documentation version: 1.0.0.
+> Documentation version: 1.1.1.
## 1. Install and initialize
@@ -31,7 +31,7 @@ The default configuration is `~/.PhyAgentOS/config.json`; the default workspace
Dora is not needed to run the general Agent, search for a Skill, or complete `paos skill install`.
It is a host prerequisite for `paos skill start`, because RuntimeManager uses the `dora` command to
-manage the selected profile. PhyAgentOS 1.0.0 uses Dora CLI v0.4.1 and `dora-message` v0.7.0 as its
+manage the selected profile. PhyAgentOS 1.1.1 uses Dora CLI v0.4.1 and `dora-message` v0.7.0 as its
Forge Skill compatibility baseline; pin this exact release for reproducible deployments.
Linux or macOS, using the versioned official installer:
@@ -230,6 +230,22 @@ In an existing session, run `/effort none`, then `/provider api_route`, followed
`providers.api_route.defaultModel`, switching providers retains the previous model,
including any vendor prefix.
+**[Opper](https://opper.ai)** (`opper`) uses the same gateway configuration. Create a key at
+https://platform.opper.ai and put it in `providers.opper.apiKey`, or supply `OPPER_API_KEY` /
+`PAOS_OPPER_API_KEY` at startup. The default endpoint is `https://api.opper.ai/v3/compat`. Use a
+pool name such as `claude-sonnet-4-6` or `gpt-5.4-mini`, which Opper routes across the providers
+serving that model, or a `provider/model` ID such as `anthropic/claude-sonnet-4-6` to pin one
+route. This integration also uses PAOS's conservative gateway effort validation, so clear any
+explicit reasoning effort when selecting it:
+
+```bash
+paos provider use opper --model claude-sonnet-4-6 --reasoning-effort none
+```
+
+In an existing session, run `/effort none`, then `/provider opper`, followed by
+`/model `. Without `providers.opper.defaultModel`, switching providers retains the
+previous model ID.
+
In terminal chat, bare `/model` opens a picker of saved models across all configured providers,
labelled by provider. Use Up/Down and Enter to switch both provider and model for the current
session; the next message uses that choice. Esc or Ctrl+C cancels selection and returns to chat.
@@ -496,5 +512,5 @@ does not delete execution records or evolution history.
## Next reading
- [Forge Configuration Reference](04-forge-configuration-reference.md)
-- [Operations Manual](../user_manual/README_en.md)
+- [Operations Manual](../user_manual/README.md)
- [Forge Tool API Integration Contract](../forge/README.md)
diff --git a/docs/en/03-developer-manual.md b/docs/en/03-developer-manual.md
index 6ad264781..9d3fb5112 100644
--- a/docs/en/03-developer-manual.md
+++ b/docs/en/03-developer-manual.md
@@ -1,8 +1,10 @@
-# PhyAgentOS Developer Manual
+# PhyAgentOS Core Developer Manual
[中文](../zh/03-developer-manual.md) · [Documentation index](../README.md)
-> Documentation version: 1.0.0.
+> Documentation version: 1.1.1.
+
+This manual covers Core implementation: AgentTask coordination, persistence, binding, verification and Runtime management. For robot, Node and Skill development, start with the [TrackB framework guide](../user_development_guide/track_b/README.md). The [Forge Tool API contract](../forge/README.md) is the canonical reference for routes, identities and lifecycle semantics.
## 1. Development invariants
@@ -33,18 +35,7 @@
`ForgeToolClient` accepts only JSON object envelopes with `ok=true` and object-valued `data`.
Errors preserve HTTP status, error code, retryability, and any returned invocation identity.
-| Operation | HTTP contract |
-|:----------|:--------------|
-| List Tools | `GET /tools` → 200 |
-| Read ToolSpec | `GET /tools/{tool_id}` → 200 |
-| Read context | `GET /tools/{tool_id}/context` → 200 |
-| Invoke Query | resolve ToolSpec, then `POST /tools/{endpoint_id}/{operation}:invoke` → 200 |
-| Admit Action | `POST /tools/{tool_id}:invoke` → 202 |
-| Action status | `GET /invocations/{invocation_id}` → 200 |
-| Action result | `GET /invocations/{invocation_id}/result` → 200 or pending 202 |
-| Request cancel | `POST /invocations/{invocation_id}/cancel` → 200 or accepted 202 |
-| Admit Session | `POST /tools/{tool_id}:invoke` → 202 |
-| Stop Session | `POST /invocations/{invocation_id}/stop` → 200 or accepted 202 |
+Routes, response codes and pending/cancel/stop semantics are defined in the [Forge Tool API contract](../forge/README.md#2-tool-discovery-and-context). Keep the client implementation aligned with that contract rather than introducing a second route definition here.
Path components are percent-encoded. PAOS supplies `caller_id` and persists it with the intent
before Action/Session admission. Admission must contain a non-empty `invocation_id`; Action also
@@ -52,24 +43,7 @@ requires `attempt_id`. A timeout leaves an unknown record and recovery never rep
## 4. Agent-facing tools
-Task lifecycle:
-
-- `forge_task_create(task_description, verification, activation_id)`;
-- `forge_task_get(task_id)`;
-- `forge_task_begin_revision(task_id, reason)`;
-- `forge_task_finalize(task_id)`;
-- `forge_task_cancel(task_id, reason?)`.
-
-Tool transport:
-
-- `forge_tool_context(tool_id)`;
-- `forge_tool_query(tool_id, arguments, task_id?, timeout_ms?)`;
-- `forge_tool_start_action(task_id, tool_id, arguments, timeout_ms?)`;
-- `forge_tool_action_status(task_id, invocation_id)`;
-- `forge_tool_action_result(task_id, invocation_id)`;
-- `forge_tool_cancel_action(task_id, invocation_id)`;
-- `forge_tool_start_session(task_id, tool_id, arguments, ownership)`;
-- `forge_tool_session_status/result/stop_session(task_id, invocation_id)`.
+The public Agent-facing tool catalog is maintained in the [API contract](../forge/README.md#6-agent-tools). Implement wrappers in `agent/tools/forge_tool_api.py` and `agent/tools/forge_task.py`; keep transport handling in `forge/tool_client.py` and coordination in `forge/task.py`.
Diagnostic Query and bound calls invoke the same HTTP methods. Every mutating or task-attributed
wrapper validates ownership and the frozen Tool binding before network access. Tool wrappers must
@@ -85,24 +59,13 @@ timestamps. Each `PlanRevision` contains its own Tool records, verdict, and veri
inside the same transaction, enforcing one global active slot across processes. Updates write the
complete validated record and an append-only event. Callers do not modify tables directly.
-Terminal task states are `succeeded`, `failed`, and `cancelled`. Non-terminal states are
-`executing`, `cancelling`, and `awaiting_replan`. Tool status `unknown` is terminal for aggregate
-accounting but is a failure, not evidence of stop.
+The [AgentTask state contract](../forge/README.md#8-agenttask-model) defines public states. Store transitions must preserve those semantics; an `unknown` Tool record closes accounting without proving physical stop.
## 6. Bound execution lifecycle
-1. Activate the primary Skill and freeze its Runtime/ToolSpec candidate into AgentTask revision 1.
-2. On the first bound physical execution, perform best-effort before-capture.
-3. Invoke Query or admit Action/Session through ForgeToolClient.
-4. Persist caller intent before admission and then retain Gateway invocation/attempt references.
-5. Update asynchronous records only from authoritative status/result responses.
-6. After every task-owned execution is terminal, perform after-capture on finalize.
-7. Aggregate Tool records, evidence, and the task contract for verification.
-8. Persist task and revision verdicts; schedule one terminal experience episode.
+Core coordinates activation/binding, durable intent admission, authoritative response recording and finalization. Keep intent persistence before transport dispatch and write Gateway references back to the same task revision. Finalization waits for task-owned executions, collects after-evidence and applies verification before scheduling experience.
-Once a record is terminal, later observations do not rewrite it. Cancellation responses are
-stored, but `requested` or `accepted` leaves the task in `cancelling` until reconciliation and
-explicit finalization.
+The public [binding/identity](../forge/README.md#7-binding-identity-and-correlation) and [AgentTask lifecycle](../forge/README.md#8-agenttask-model) definitions are maintained in the API contract. Cancellation responses remain records of requests until reconciliation and finalization establish the aggregate result.
## 7. Verification and recovery
@@ -128,13 +91,7 @@ execution references, bundle metadata, and tombstone information required for au
## 9. Skill Runtime contracts
-A `skill.yaml` manifest must use `manifest_version: 2`, a directory-safe name/version, a relative
-Skill document, an HTTP(S) `gateway_url`, non-empty required Tools, at least one profile, and strict
-known fields. Registry-resolved nodes require artifact identity, version, platform, architecture,
-archive type (`executable_tar_gz` or `directory_tar_gz`), the entrypoint, and SHA-256. An
-`executable_tar_gz` archive contains one root-level executable named by the entrypoint; a
-`directory_tar_gz` archive contains one root directory named after the entrypoint that holds the
-same-named executable plus its runtime tree (tree-internal relative symlinks are allowed).
+Manifest fields, Node archive layouts and startup-hook environment are documented in the [Bundle and Tool integration reference](../user_development_guide/README.md#4-build-a-manifest-v2-skill-bundle). Core implements these contracts in `skill_runtime/manifest.py`, archive validators and installers.
Archive validation rejects absolute/traversing paths, links outside the node-tree cases above,
duplicate/colliding paths, oversized
@@ -196,18 +153,11 @@ Evolution failures remain fail-open.
## 12. Extension workflows
-To add a robot capability:
+For robot/model configuration, new profiles, or new Nodes, follow the [three TrackB extension modes](../user_development_guide/track_b/SKILL_DEVELOPMENT.md) and [Piper X example](../user_development_guide/PIPER_X_DEMO.md).
-1. implement or package the ToolEndpoint operation;
-2. publish a Query, Action, or Session ToolSpec with exact schemas and binding;
-3. define operation `max_concurrency` in Gateway;
-4. add the locked node and profile references to a manifest-v2 Bundle;
-5. test binding drift, context, invocation, pending, terminal, cancel/stop, ownership, and unknown outcomes;
-6. add workflow guidance to a Skill without embedding task-specific coordinates or secrets.
+Core changes should extend the existing generic client, binding, coordinator or installer only when the capability requires it. Preserve the API contract and add focused regression coverage at the affected implementation boundary. Do not add an alternate Agent-to-Dora execution path.
-Do not create a second PAOS execution protocol, direct Agent-to-Dora calls, or a cross-Tool lease.
-A new Agent tool is justified only when the generic task and Tool API tools cannot express the
-capability.
+The opt-in [interaction foundation](../interaction/README.md) is a separate restricted extension; its deployment limits also apply to Core changes.
## 13. Test gates
@@ -226,5 +176,10 @@ conditional on independently installed matching artifacts and Dora availability.
## Next reading
- [Forge Tool API Integration Contract](../forge/README.md)
-- [Integration Development Guide](../user_development_guide/README_en.md)
+- [Bundle and Tool Integration Reference](../user_development_guide/README.md)
- [Agent Experience and Skill Evolution](05-agent-experience-and-skill-evolution.md)
+
+## Node development references
+
+- [TrackB framework guide](../user_development_guide/track_b/README.md)
+- [Piper X MuJoCo development example](../user_development_guide/PIPER_X_DEMO.md)
diff --git a/docs/en/04-forge-configuration-reference.md b/docs/en/04-forge-configuration-reference.md
index e149b73a8..5c152d4e9 100644
--- a/docs/en/04-forge-configuration-reference.md
+++ b/docs/en/04-forge-configuration-reference.md
@@ -1,6 +1,6 @@
# Forge Configuration Reference
-> Applies to PhyAgentOS 1.0.0 and the unified Forge Gateway Tool API.
+> Applies to PhyAgentOS 1.1.1 and the unified Forge Gateway Tool API.
## 1. Location and naming
@@ -24,11 +24,22 @@ manifest and an explicitly started profile.
| `pollIntervalS` | number | `0.5` | Recommended Action/Session reconciliation interval in `[0.1, 5.0]` seconds. |
| `executionTimeoutS` | number | `300.0` | Default Agent-side task deadline guidance. It does not prove that a timed-out execution stopped. |
| `evidence` | object | below | AgentTask best-effort before/after capture settings. |
+| `interaction` | object | `{"enabled": false}` | Opt-in restricted interaction extension; see below. |
PAOS invokes Query, Action, and Session only through `/tools` and `/invocations`. It does not call
legacy `/agent/sessions` or `/policy/command` routes. Concurrency is decided by the selected
endpoint operation's `max_concurrency`.
+### `forge.interaction`
+
+| JSON field | Type | Default | Constraint and meaning |
+| --- | --- | --- | --- |
+| `enabled` | boolean | `false` | Permits interaction task contracts. It does not authorize production control-plane access. |
+
+The [interaction foundation](../interaction/README.md) currently requires an explicitly injected
+in-process deployment with `httpx.MockTransport`. Ordinary CLI configuration alone cannot enable
+a real environment. Keep this optional extension separate from default robot/Skill development.
+
## 2.1 `resourceRegistry`
| JSON field | Type | Default | Constraint and meaning |
@@ -77,7 +88,7 @@ Verification Service readiness is bounded. A non-`off` AgentTask is rejected whe
| JSON field | Type | Default | Constraint and meaning |
|:-----------|:-----|:--------|:-----------------------|
-| `enabled` | boolean | `true` | Enables explicit Skill activation, the experience ledger, and background evolution. Failures never block task execution. |
+| `enabled` | boolean | `true` | Enables experience reflection and guarded promotion. Explicit Skill activation remains available when false; evolution failures do not block execution. |
| `scope` | literal | `verified_forge_lineage` | Consumes AgentTask lineages with semantic verdicts; the persisted literal remains stable for compatibility. |
| `promotionMode` | literal | `guarded_auto` | Allows only validated, guarded automatic promotion. |
| `minSuccessfulEpisodes` | integer | `3` | Independent successful AgentTasks required for one candidate; at least 1. |
@@ -264,7 +275,7 @@ paos agent -m "Call forge_tool_context for the requested Tool and report its sch
## Next reading
- [User Manual](02-user-manual.md)
-- [Developer Manual](03-developer-manual.md)
+- [Core Developer Manual](03-developer-manual.md)
- [Agent Experience and Skill Evolution](05-agent-experience-and-skill-evolution.md)
-- [Operations Manual](../user_manual/README_en.md)
-- [Unified Forge Tool API Contract](../forge/UNIFIED_TOOL_API.md)
+- [Operations Manual](../user_manual/README.md)
+- [Unified Forge Tool API Contract](../forge/README.md)
diff --git a/docs/en/05-agent-experience-and-skill-evolution.md b/docs/en/05-agent-experience-and-skill-evolution.md
index 2371657ba..01b64091f 100644
--- a/docs/en/05-agent-experience-and-skill-evolution.md
+++ b/docs/en/05-agent-experience-and-skill-evolution.md
@@ -1,6 +1,6 @@
# Agent Experience and Skill Evolution
-> Documentation version: 1.0.0. This manual describes the implemented Agent-side validation, experience, Lesson, and Skill-evolution path over AgentTask records.
+> Documentation version: 1.1.1. This manual describes the implemented Agent-side validation, experience, Lesson, and Skill-evolution path over AgentTask records.
## 1. Purpose and boundary
@@ -202,6 +202,6 @@ This boundary also allows other trusted task providers to reuse Lesson clusterin
- [Framework Introduction](01-framework-introduction.md)
- [User Manual](02-user-manual.md)
-- [Developer Manual](03-developer-manual.md)
+- [Core Developer Manual](03-developer-manual.md)
- [Forge Configuration Reference](04-forge-configuration-reference.md)
- [Documentation Index](../README.md)
diff --git a/docs/forge/README.md b/docs/forge/README.md
index c0a96d746..3691b1efe 100644
--- a/docs/forge/README.md
+++ b/docs/forge/README.md
@@ -2,7 +2,9 @@
[中文](README_zh.md) · [Documentation index](../README.md)
-> Applies to PhyAgentOS 1.0.0.
+> Applies to PhyAgentOS 1.1.1.
+
+This is the canonical reference for public Tool API routes, identities and invocation/task semantics. Node-side messages and dataflow belong to [TrackB protocols](../user_development_guide/track_b/PROTOCOLS.md); optional interaction has its own [restricted extension contract](../interaction/README.md).
## 1. Execution boundary
@@ -146,8 +148,9 @@ revision keeps the same task ID and is bounded by replan count and deadline.
## 9. Evidence and verification
-PAOS performs best-effort capture before the first bound Action and after every bound Action reaches
-terminal accounting state. Evidence artifacts include source, phase, sequence, timestamps, media
+For ordinary robot workflows, PAOS performs best-effort capture before the first bound
+Action. `forge_task_finalize` collects after-evidence once task-owned Actions/Sessions have reached
+terminal accounting state, rather than after each individual Action. Evidence artifacts include source, phase, sequence, timestamps, media
metadata, size, SHA-256, and workspace-relative references. Capture errors are recorded rather than
hidden. Bundle identity, quality, capture-window, policy requirements, and retained artifact bytes
are validated before the verifier receives the task context.
@@ -220,5 +223,5 @@ recorded separately with exact artifact digests and environment.
- [Framework Introduction](../en/01-framework-introduction.md)
- [Configuration Reference](../en/04-forge-configuration-reference.md)
-- [Integration Development Guide](../user_development_guide/README_en.md)
-- [Operations Manual](../user_manual/README_en.md)
+- [Bundle and Tool Integration Reference](../user_development_guide/README.md)
+- [Operations Manual](../user_manual/README.md)
diff --git a/docs/forge/README_zh.md b/docs/forge/README_zh.md
index 84158c2d2..b6565b1cb 100644
--- a/docs/forge/README_zh.md
+++ b/docs/forge/README_zh.md
@@ -1,8 +1,10 @@
# Forge Tool API 接入契约
-[English](README.md) · [文档索引](../README.md)
+[English](README.md) · [文档索引](../README_zh.md)
-> 适用于 PhyAgentOS 1.0.0。
+> 适用于 PhyAgentOS 1.1.1。
+
+本文是公开 Tool API 路由、身份和 invocation/task 语义的统一契约。节点消息与 dataflow 参见 [TrackB 协议](../user_development_guide/track_b/PROTOCOLS_zh.md);可选交互另有[受限扩展契约](../interaction/README_zh.md)。
## 1. 执行边界
@@ -142,7 +144,8 @@ Tool record 终结后,后续 observation 不改写执行事实。Recovery revi
## 9. Evidence 与 verification
-PAOS 在第一次绑定 Action 前和所有绑定 Action 达到记账终态后进行 best-effort 采集。Evidence
+普通机器人工作流在第一次绑定 Action 前进行 best-effort 采集;`forge_task_finalize` 在
+task-owned Action/Session 达到记账终态后采集后置证据,不是每个 Action 后分别采集。Evidence
artifact 包含 source、phase、sequence、timestamp、media metadata、size、SHA-256 与工作区相对
reference。采集错误会显式记录。Verifier 接收任务上下文前,会检查 bundle 身份、质量、采集时间
窗口、policy 要求以及保留 artifact 字节。
@@ -206,5 +209,5 @@ Mock Gateway 测试可完成代码与契约验收;硬件/MuJoCo 验收单独
- [框架介绍](../zh/01-framework-introduction.md)
- [配置参考](../zh/04-forge-configuration-reference.md)
-- [集成开发指南](../user_development_guide/README.md)
-- [运行手册](../user_manual/README.md)
+- [Bundle 与 Tool 接入参考](../user_development_guide/README_zh.md)
+- [运行手册](../user_manual/README_zh.md)
diff --git a/docs/forge/UNIFIED_TOOL_API.md b/docs/forge/UNIFIED_TOOL_API.md
deleted file mode 100644
index d4e1acd63..000000000
--- a/docs/forge/UNIFIED_TOOL_API.md
+++ /dev/null
@@ -1,88 +0,0 @@
-# Unified Forge Tool API Integration
-
-> Applies to PhyAgentOS 1.0.0. See [Forge Tool API Integration Contract](README.md) for the full
-> operational and development contract.
-
-## One physical execution plane
-
-```text
-AgentTask-bound call / diagnostic Query
- → ForgeToolClient
- → Gateway /tools → ToolInvocation → ToolEndpoint
- → Dora and robot nodes
-```
-
-PAOS supports Query, Action, and Session semantics only through `/tools` and `/invocations`; it
-does not call legacy `/agent/sessions` or `/policy/command` routes and does not add a cross-Tool
-resource lease. The Gateway routes to the selected Endpoint operation and enforces its
-`max_concurrency`.
-
-## Agent tools
-
-- Task lifecycle: `forge_task_create`, `forge_task_get`, `forge_task_begin_revision`,
- `forge_task_finalize`, and `forge_task_cancel`.
-- Tool API: `forge_tool_context`, `forge_tool_query`, `forge_tool_start_action`,
- `forge_tool_action_status`, `forge_tool_action_result`, `forge_tool_cancel_action`,
- `forge_tool_start_session`, `forge_tool_session_status`, `forge_tool_session_result`, and
- `forge_tool_stop_session`.
-
-`forge_tool_query` may be diagnostic without a task. Action and task-owned Session calls require a
-task whose binding freezes the activated Skill version, Runtime identity, workflow/manifest hashes,
-and live ToolSpec hashes. Bound calls are aggregated for PAOS task verification.
-
-Action admission is not completion. `cancel_status=requested|accepted`, a local timeout, or an
-`unknown` terminal outcome never proves that the physical effect stopped and must not trigger a
-blind retry.
-
-## AgentTask and verification
-
-An AgentTask stores append-only PlanRevisions, Query records, Action/Session invocation references,
-evidence, and verification attempts. The following identities are deliberately different:
-
-- PAOS `task_id`;
-- PAOS `revision_id`;
-- PAOS Query/execution record ID;
-- PAOS-generated and pre-admission-persisted `caller_id`;
-- Gateway `invocation_id`;
-- Gateway `attempt_id`.
-
-Forge owns each Tool execution fact. PAOS captures best-effort evidence before the first bound
-Action and after all task-owned executions are terminal, then `forge_task_finalize` applies the existing
-`off`, `audit`, `enforce`, or `recovery` task semantics. A recoverable verdict appends a bounded
-PlanRevision to the same task; it does not create another execution plane.
-
-## Skill Runtime
-
-`paos skill` discovers and installs manifest-v2 bundles, verifies SHA-256 inventories, and manages
-an explicit named Dora profile. Installation uses safe extraction and atomic replacement. Each Node
-lock fixes platform, architecture, archive type (`executable_tar_gz` or `directory_tar_gz`), the
-entrypoint, and archive SHA-256; the installer also
-records the extracted binary hash. Downloads require
-either `resourceRegistry.url`, `PAOS_RESOURCE_REGISTRY_URL`, or an explicit static index.
-
-When one healthy Skill Runtime is active, its manifest provides the only Gateway URL and its Skill
-becomes available to the Agent loader and activation/evolution pipeline. PhyAgentOS distributions
-contain no concrete Forge Skill, Node, model, or simulation asset.
-
----
-
-# Forge Tool API 统一接入
-
-当前 PAOS 只有一条物理执行链:绑定 AgentTask 的调用与无任务调用都经过
-`ForgeToolClient → Gateway /tools → ToolInvocation → ToolEndpoint → Dora/机器人节点`。
-PAOS 只通过 `/tools` 与 `/invocations` 支持 Query、Action、Session,不调用旧式
-`/agent/sessions`、`/policy/command`,也不新增跨 Tool 资源租约;并发由 Endpoint operation
-的 `max_concurrency` 裁决。
-
-AgentTask 负责聚合 PlanRevision、Query record、Action/Session invocation 引用、证据与验证结论,
-但不执行机器人。Action 接受、取消接受、timeout 或 `unknown` 都不能解释为物理动作已经
-停止,也不能触发盲目重试。恢复验证在同一个 `task_id` 上追加有预算和 deadline 的
-PlanRevision。
-
-Action 与 task-owned Session 必须绑定本轮显式激活的 Skill;binding 冻结 Skill 版本、Runtime
-identity、manifest/工作流 hash 与 ToolSpec hash。PAOS 在 admission 前持久化自己生成的
-caller ID;未知结果只能按已知 invocation ID 查询,不能盲目重复 POST。
-
-Skill Runtime 使用 manifest v2、SHA-256 清单、安全解包、原子安装和持久化状态。活动 Runtime
-manifest 是 Gateway URL 的唯一来源。PhyAgentOS 分发不包含具体 Forge Skill、Node、模型或
-仿真资源;需要时由部署者显式安装。
diff --git a/docs/imgs/quickstart/robot-control-sim-eef-control.gif b/docs/imgs/quickstart/robot-control-sim-eef-control.gif
new file mode 100644
index 000000000..db3d6357a
Binary files /dev/null and b/docs/imgs/quickstart/robot-control-sim-eef-control.gif differ
diff --git a/docs/imgs/quickstart/robot-control-sim-joint-control.gif b/docs/imgs/quickstart/robot-control-sim-joint-control.gif
new file mode 100644
index 000000000..8b1c384f7
Binary files /dev/null and b/docs/imgs/quickstart/robot-control-sim-joint-control.gif differ
diff --git a/docs/imgs/quickstart/robot-control-sim-startup.gif b/docs/imgs/quickstart/robot-control-sim-startup.gif
new file mode 100644
index 000000000..30d705e41
Binary files /dev/null and b/docs/imgs/quickstart/robot-control-sim-startup.gif differ
diff --git a/docs/interaction/README.md b/docs/interaction/README.md
index 95ae05d96..065f79980 100644
--- a/docs/interaction/README.md
+++ b/docs/interaction/README.md
@@ -1,5 +1,11 @@
# Governed interaction foundation
+[English](README.md) | [简体中文](README_zh.md)
+
+This is an optional restricted Core extension, separate from the default robot development path.
+Start ordinary Node/Skill development with [TrackB](../user_development_guide/track_b/README.md).
+The [Tool API contract](../forge/README.md) remains the canonical transport and invocation reference.
+
This opt-in foundation connects a single real `AgentTask` to a Forge Session and a
bounded observation/decision loop. It is implemented against core `dev@3dcdc914`.
Minecraft operations, its Bridge, and production control-plane isolation are not
diff --git a/docs/interaction/README_zh.md b/docs/interaction/README_zh.md
new file mode 100644
index 000000000..d892abf3a
--- /dev/null
+++ b/docs/interaction/README_zh.md
@@ -0,0 +1,144 @@
+# 受治理的交互基础
+
+[English](README.md) | [简体中文](README_zh.md)
+
+这是独立于默认机器人开发流程的可选受限 Core 扩展。普通 Node/Skill 开发从
+[TrackB](../user_development_guide/track_b/README_zh.md)开始;传输与 invocation 语义仍以
+[Tool API 契约](../forge/README_zh.md)为准。
+
+该基础将一个真实 `AgentTask` 连接到 Forge Session,以及有预算约束的观测/决策循环,
+实现基于 Core `dev@3dcdc914`。不包含 Minecraft 操作、其 Bridge 或生产控制面的隔离,
+也不改变 Gateway API 或 invocation 语义。
+
+## 启用方式与公开入口
+
+`forge.interaction.enabled` 默认为 `false`。启用后允许交互任务契约,**不授权真实网络控制面**。
+当前仅接受显式注入的 `InProcessInteractionDeployment`,其中包含 `httpx.MockTransport`、
+可信环境预算及决策 callable。不存在 `private_control_plane=true` 生产绕过开关。
+未来生产 adapter 必须先证明网络/凭据隔离与 Endpoint 作用域约束,再接入这里。
+
+交互协议没有 token 或 HMAC 认证层。当前权限来自可信进程内能力与测试部署 adapter,
+协议本身不建立生产认证。
+
+沿用以下工作流:
+
+1. 使用正常的校验 installer 安装 Skill 归档并激活。
+2. 创建 `verification.mode=enforce` 或 `recovery` 的绑定任务。
+3. 使用冻结的 Session Tool 调用 `forge_tool_start_session`,指定 `ownership=task` 与
+ `arguments={"world_id":""}`。可信宿主提供预算、task/revision 身份、
+ start/run ID 和 binding digest。
+4. 读取 `forge_task_get`。原有 `data` 不变;可选同级字段 `interaction` 报告运行状态、
+ 停止/核对阻塞项及模型调用。
+5. 通过 `forge_task_cancel`、Session stop 或 `/stop` 取消。
+
+只有常驻 gateway 或交互 CLI 可以启动运行。单次 CLI/cron 上下文不得启用常驻 Supervisor。
+普通 CLI 不注入测试环境,不能据此启动未经批准的真实游戏。AgentLoop 将运行中的 bus
+生命周期标为常驻;聊天回复不拥有监控任务。关闭/重启会在 client 关闭前执行有界停止核对,
+未解决运行继续保留记录。完成/阻塞通知持久化去重,采用至多入队一次语义,不保证突发崩溃下送达。
+
+## Bundle 与协议契约
+
+可选 `interaction.yaml` 声明 `interaction_contract_v1`:
+
+```yaml
+protocol: interaction_contract_v1
+session_tool: grid.run
+snapshot_tool: grid.snapshot
+submission_tool: grid.submit
+proposal_schema_file: proposal.json
+snapshot_views: [snapshot, submission, history, run]
+event_channel:
+ mode: polling
+ event_type: progress
+ business_kind: interaction_changed
+execution_policy:
+ max_active_sessions_per_task: 1
+ max_inflight_decisions_per_run: 1
+ runner_mode: single_owner_no_hot_takeover
+ completion_policy: quiesce_then_stop
+access_policy: private_control_plane
+```
+
+三个 Tool 必须位于已有 `required_tools` 中,语义依次为 Session/Query/Action,并解析到同一
+Endpoint。Proposal schema 是自包含的 JSON Schema Draft 2020-12 object,禁止未知 object
+字段,不解析远端 schema 引用。Tool readiness 与 ToolSpec hash 继续由原 Forge binding resolver 检查。
+
+普通归档清单覆盖 sidecar 与 schema。安装在校验后、原子提交前写入
+`.paos-interaction-install.json`,Bundle 不得自行提供 receipt。普通 Bundle 不需要该 receipt;
+缺少 receipt 的交互 Bundle 必须重新校验安装。激活拒绝同名 workspace override。
+修改 sidecar/schema 后需重新安装与激活,不能替换运行中的契约。
+
+业务 wire 契约沿用已审查原型:整数 executor cursor、`snapshot/submission/history/run` 视图、
+相互独立的 start/run/step/submission 与 invocation ID,以及不可变接受/拒绝 receipt。
+业务 payload 的标准 hash 使用排序、紧凑 UTF-8 JSON,禁止 NaN;submission hash 排除
+`runner_epoch`。Query output 与 invocation result output 分别使用原有 Forge envelope。
+`accepted` 不代表物理操作或根目标成功;receipt 的 `reason`、`execution_status` 保留原名与含义。
+
+## 所有权、恢复与验证
+
+`CoordinatorInteractionClient` 使用真实 Coordinator 的 intent 与 invocation 账本。
+监控读取校验 task/run 作用域,不要求任务仍可执行。每次 operation 固定其 Runtime client,
+并在派发前最终复核身份与取消状态。Stop/status 不会把旧 invocation ID 带到替换后的 Gateway。
+模型不能通过 JSON arguments 提供 Runner 能力。
+
+独立的 `.paos/interaction/interaction.sqlite3` 保存版本化 binding、run、step、模型 attempt、
+submission 及只追加 audit event。Task event 账本中的持久标记防止扩展 journal 缺失时静默回退。
+跨数据库崩溃恢复依赖 intent,不宣称两库原子提交;可在崩溃后恢复的进程锁阻止热接管。
+
+未变化的 snapshot 不重复触发推理。模型 attempt、时间、token 和空闲进展均有预算。
+`ProviderDecider` 使用新的纯数据上下文及 `tools=None`,拒绝 tool call 和模型自报用量。
+工具注册表策略既检查公开 schema,也检查每次实际执行,包括子 agent、后续消息和同一模型响应
+中的后续工具调用。未结束的不安全工具调用会阻止启动;被取消的不安全工具协程保留本地保护,
+因为协程取消不能证明外部进程终结。这些检查覆盖 Core 模型路径,不构成操作系统/网络隔离边界。
+
+Timeout、receipt 丢失、Gateway 404、Runtime 身份变化和未解决执行都会阻止新工作。
+第一版**不自动重发 start 或 submission**,即使已经 `absent_confirmed`。
+Unknown 不免除请求停止与有界核对的责任;无法确立安全状态时,run 保持 blocked 并保留资源所有权。
+Gateway 停止确认或重复轮询不能修复丢失的 Gateway 控制交换,这仍是真实游戏接入的阻塞条件。
+
+Finalize、验证错误、重新规划和资源释放都检查 interaction gate。取消在控制 I/O 前持久关闭 admission。
+旧运行解决后,新 Session 需要新 PlanRevision。验证读取经过检查的初始/最终观测、不可变 receipt、
+step 关联与持久 executor history,而非只使用机器人证据。证据沿用 artifact hash、lineage 和
+EvidenceBundle 校验。使用 `required_kinds: [interaction_observation]`;交互 adapter 另行要求完整
+过程轨迹,不将其插入旧 before/after kind 要求。一个根任务只产生一个带轨迹引用的去重 experience
+episode;模型给出 `finish_candidate` 后,根目标仍可能验证失败。
+
+## 兼容性与运行限制
+
+Coordinator 的 `_append_execution` admission guard 同样适用于未启用交互的普通 AgentTask。
+取消请求已持久化或任务离开 `executing` 后,intent 事务在派发前拒绝新 Query、Action 和 Session
+record。这收紧了首次可执行检查后状态变化的普通任务行为,不会取消已经派发的调用,也不证明远端结果。
+
+两个进程共享 interaction journal 且原进程仍拥有未解决运行时,第二个进程在恢复中抛出
+`RunnerAlreadyOwnedError`。异常经 Coordinator 传播到 Agent 启动,导致第二个 Agent 启动失败,
+原所有者继续。此启动失败路径属于交互基础的 v1 单 Runner 策略;没有热接管或受限聊天回退。
+运维人员应避免在同一 workspace 启动第二个所有者,不得删除 owner lock 强行接管运行。
+
+Supervisor 缺失或其监控任务未运行时,仅持久化取消不能保证物理停止或持续核对。
+未解决运行保留阻塞项与资源所有权;同一 Supervisor 的通知不构成独立故障检测。
+真实游戏接入前应增加外部健康监控,并建立通过授权控制面停止环境、核对执行事实的操作流程。
+不得手动把 journal 标为 settled 或将其删除来释放资源。
+
+`verified_extension` 当前每次检查都会 hash 已安装 Bundle 的全部文件,包括 finalize 中的重复检查。
+小型测试环境可以接受,但包含大型游戏资产时可能昂贵。Manifest digest cache 属于后续工作,
+必须具备可靠的变更失效机制,不能削弱篡改检测;v1 保留完整校验。
+
+## 可复现验收
+
+```sh
+python -m pip install -e '.[dev]'
+python -m pytest tests/test_interaction_foundation.py -q
+python -m pytest tests -q
+```
+
+macOS 可用 `TMPDIR=/private/tmp` 避开既有 evidence 测试中未解析的 `/var` 与 `/private/var`
+临时目录别名。设置 `LITELLM_LOCAL_MODEL_COST_MAP=True` 可使 Provider 成本表加载保持离线。
+
+`tests/interaction_support.py` 提供 MockTransport 后的持久化 SQLite 测试 executor,安装真实校验
+Skill Bundle,创建真实 activation 与 AgentTask,并使用独立最终位置 verifier。测试覆盖正常多步循环、
+实际 AgentLoop 回复/停止、共享工具策略、迟到模型结果、根验证期间取消、传输不确定性、Runtime 替换、
+进程所有权与恢复、扩展关闭/缺失、安装篡改、证据缺口,以及唯一根任务 experience episode。
+
+真实游戏接入前,提供带认证的 Endpoint/Bridge adapter 和独立目标证据,修复游戏离线 watchdog,
+证明 shell/HTTP/委派、别名与生命周期路由的隔离,并针对实际 Gateway 和游戏验证停止失败/丢包行为。
+当前基础不提供 SSE、热故障转移、跨 Runtime 重新绑定、自动重发或 Subtask DAG。
diff --git a/docs/user_development_guide/COMMUNICATION.md b/docs/user_development_guide/COMMUNICATION.md
index f4ab81a49..fd85e632e 100644
--- a/docs/user_development_guide/COMMUNICATION.md
+++ b/docs/user_development_guide/COMMUNICATION.md
@@ -1,155 +1,126 @@
-# PhyAgentOS 通信架构
+# PhyAgentOS Core Communication Architecture
-[English](COMMUNICATION_en.md) · [文档索引](../README.md)
+[中文](COMMUNICATION_zh.md) · [Documentation index](../README.md)
-> 版本:1.0.0
+> Version: 1.1.1
-## 1. 通信边界
+This reference covers Core message, observation, verification and persistence boundaries. For Forge Node messages and dataflow ports, use [TrackB protocols](track_b/PROTOCOLS.md). HTTP routes and invocation semantics have one canonical definition in the [API contract](../forge/README.md).
-PhyAgentOS 分离六类边界:
+## 1. Communication boundaries
-1. 用户/渠道 ↔ AgentLoop 消息;
-2. Agent tools ↔ AgentTaskCoordinator;
-3. ForgeToolClient ↔ Gateway Query/Action/Session Tool API;
-4. observation collector ↔ Gateway 图像/state WebSocket;
-5. verifier ↔ 独立 Verification Service;
-6. AgentTask/experience/Runtime ↔ 各自持久化存储。
+PhyAgentOS separates six boundaries:
-边界之间共享不透明 reference,不共享执行所有权。
+1. user/channel ↔ AgentLoop messages;
+2. Agent tools ↔ AgentTaskCoordinator;
+3. ForgeToolClient ↔ Gateway Query/Action/Session Tool API;
+4. observation collector ↔ Gateway image/state WebSockets;
+5. verifier ↔ isolated Verification Service;
+6. AgentTask/experience/Runtime ↔ their own persistent stores.
-## 2. 用户消息边界
+The boundaries share opaque references, not execution ownership.
-渠道向 Agent bus 发布 `InboundMessage`。AgentLoop 构造上下文、调用模型与工具,再发送
-`OutboundMessage`。Tool call 遵循注册的 JSON schema。现有文件、目录、Shell、Web、消息、
-图片、Scene Graph、Cron、Spawn、Agent Mode、Skill activation 和动态 MCP tools 都使用同一
-Loop。
+## 2. User-message boundary
-AgentTask 的 `origin_session_key` 将 completion experience 关联到原 Agent conversation;它
-不是 Gateway execution identifier。
+Channels publish `InboundMessage` objects to the Agent bus. AgentLoop builds context, invokes the
+model and tools, then emits `OutboundMessage`. Tool calls use registered JSON schemas. The existing
+file, directory, shell, web, messaging, image, Scene Graph, Cron, Spawn, Agent Mode, Skill
+activation, and dynamic MCP tools follow this same loop.
-## 3. AgentTask 边界
+AgentTask's `origin_session_key` associates completion experience with the originating Agent
+conversation. It is not a Gateway execution identifier.
-```text
-forge_task_create
-forge_task_get
-forge_task_begin_revision
-forge_task_finalize
-forge_task_cancel
-```
+## 3. AgentTask boundary
-这些 tools 调用 AgentTaskCoordinator,不调用 Dora 或机器人。Coordinator 使用事务 SQLite
-限制一个非终态 AgentTask,并保存只追加 PlanRevision、Tool record、evidence reference 与
-verification attempt。
+Task lifecycle tools are listed in the [API contract](../forge/README.md#6-agent-tools).
-诊断 Query 可不带 `task_id`;受治理 Query 以及全部 Action/Session 必须带 task。Wrapper 先
-检查不可变 Skill/Runtime/ToolSpec binding,再围绕同一 Gateway request 创建或更新匹配 Tool
-record。这是任务聚合,不是第二条物理执行面。
+These tools call AgentTaskCoordinator and never call Dora or a robot. The coordinator uses
+transactional SQLite to enforce one non-terminal AgentTask and stores append-only PlanRevisions,
+Tool records, evidence references, and verification attempts.
-## 4. Gateway HTTP 边界
+Diagnostic Query may omit `task_id`; governed Query and every Action/Session include it. The
+wrapper checks the immutable Skill/Runtime/ToolSpec binding and creates or updates the matching
+Tool record around the same Gateway request. This is aggregation, not another execution plane.
-```text
-GET /tools
-GET /tools/{tool_id}
-GET /tools/{tool_id}/context
-POST /tools/{endpoint_id}/{operation}:invoke # Query,HTTP 200
-POST /tools/{tool_id}:invoke # Action/Session admission,HTTP 202
-GET /invocations/{invocation_id}
-GET /invocations/{invocation_id}/result # pending 时 HTTP 202
-POST /invocations/{invocation_id}/cancel
-POST /invocations/{invocation_id}/stop # Session
-```
+## 4. Gateway HTTP boundary
-Query 先读取 ToolSpec,再使用其 `endpoint_id`、`operation` 和 `semantics=query` binding。
-Action/Session 根据稳定 Tool ID 调用,两者返回 `invocation_id`,Action 还返回 `attempt_id`。
+The [API contract](../forge/README.md#2-tool-discovery-and-context) defines discovery, Query, Action and Session routes and response envelopes. Core keeps transport handling in `ForgeToolClient`; timeout leaves the remote outcome unknown.
-成功响应必须是 `ok=true` 且 `data` 为 object 的 JSON。Error envelope 可以携带 code 与
-retryability。Transport timeout 表示远端状态未知。即使后续本地持久化或追踪失败,也必须保留
-响应中已返回的 invocation identity。
+Returned invocation identities must be retained even if subsequent local persistence or tracking fails. Verification and experience components do not replace the Gateway execution owner.
-## 5. Identity 边界
+## 5. Identity boundary
-| Identity | Namespace | 可变性 |
-|:---------|:----------|:-------|
-| `task_id` | PAOS AgentTask | 对全部 revisions 稳定 |
-| `binding_id` | PAOS Forge binding | 不可变 Skill/Runtime/ToolSpec 快照 |
-| `revision_id` | PAOS PlanRevision | 不可变、只追加规划世代 |
-| `record_id` | PAOS ToolExecutionRecord | 不可变 record identity |
-| `caller_id` | PAOS ToolExecutionRecord | 异步 admission 前持久化 |
-| `invocation_id` | Gateway ToolInvocation | 稳定 Action/Session 生命周期 identity |
-| `attempt_id` | Gateway attempt | 对返回的 attempt 稳定 |
+Namespaces and correlation fields are defined in the [binding and identity contract](../forge/README.md#7-binding-identity-and-correlation). Components exchange explicit stored references; they must not derive a Gateway identity from a PAOS task or revision ID.
-组件不能从另一个 namespace 派生 identity;关联依赖显式保存的 reference。
+## 6. Invocation terminal semantics
-## 6. Invocation 终态语义
+Use the [Action](../forge/README.md#4-action-contract), [Session](../forge/README.md#5-session-contract) and [AgentTask](../forge/README.md#8-agenttask-model) contracts for terminal and cancellation behavior. Core persists request/response observations and reconciles them before finalization; local cancellation or transport completion cannot establish physical stop.
-Gateway status/result 是唯一 Action/Session 终态来源。Pending 保持非终态。已知终态包括 Gateway
-报告的 success、failure、cancellation 或 stopped。`unknown` 对 PAOS 记账是终态,因为无法
-证明继续进展,但它不是已知物理停止,并继续参与正常 Runtime stop 门控。
+## 7. Evidence WebSocket boundary
-Cancellation/stop `requested` 或 `accepted` 只确认控制消息投递,不会取消追踪,也不会直接把
-AgentTask 设为 cancelled。PAOS 继续核对并显式 finalize task。
+PAOS connects to configured image and optional state streams using bounded connection and capture
+timeouts. Messages are treated as untrusted input. Image media, decoded size, sequence, phase,
+source, local receive time, and SHA-256 are validated before persistence.
-## 7. Evidence WebSocket 边界
+For ordinary robot workflows, the collector captures before the first bound Action and during
+finalization after task-owned Actions/Sessions reach terminal accounting state. Evidence association is best-effort; Gateway ToolResult and invocation events
+remain authoritative for execution.
-PAOS 使用有界连接和采集 timeout 连接配置的图像流与可选 state 流。消息均作为不可信 input。
-持久化前校验图像 media、decoded size、sequence、phase、source、本机 receive time 与
-SHA-256。
+## 8. Verification boundary
-Collector 在第一次绑定物理执行前和全部 task-owned 执行达到记账终态后采集。Evidence association
-为 best-effort;Gateway ToolResult 与 invocation events 仍是权威执行事实。
+The Agent-side verifier sends resolved public task contracts, normalized Tool facts, evidence,
+history, and frozen scoped Lessons to the isolated Verification Service. Lessons are untrusted,
+non-authoritative advice. The service cannot invoke Gateway, create a PlanRevision, or change
+execution records.
-## 8. Verification 边界
+Verifier output must validate as the versioned verdict contract. AgentTaskCoordinator applies
+`off`, `audit`, `enforce`, or `recovery` semantics and persists every attempt.
-Agent-side verifier 把已解析公共任务契约、规范化 Tool facts、evidence、history 和冻结的
-scoped Lessons 发送给独立 Verification Service。Lesson 是不可信、非权威建议。Service 不能
-调用 Gateway、创建 PlanRevision 或修改 execution record。
+## 9. Experience boundary
-Verifier output 必须通过版本化 verdict contract。AgentTaskCoordinator 应用 `off`、`audit`、
-`enforce` 或 `recovery` 语义并持久化每次 attempt。
+ExperienceCoordinator receives an AgentTask completion reference. `AgentTaskOutcomeSource` builds a
+redacted envelope containing workflow structure, semantic verdicts, field names, and opaque task,
+revision, invocation, attempt, and evidence references. Raw arguments, results, credentials,
+endpoints, and physical coordinates are not copied into learned content.
-## 9. Experience 边界
+The episode is unique per AgentTask. PlanRevisions, repeated completion notifications, reviews,
+and replay do not create independent support.
-ExperienceCoordinator 接收 AgentTask completion reference。`AgentTaskOutcomeSource` 构造去敏
-envelope,包含 workflow structure、semantic verdict、字段名,以及不透明 task、revision、
-invocation、attempt 与 evidence references。原始 arguments、results、凭据、endpoint 和物理
-坐标不会复制到学习内容。
+## 10. Persistence boundary
-每个 AgentTask 只有一个 episode。PlanRevision、重复 completion notification、review 与
-replay 不增加独立支持。
+| Store | Content |
+|:------|:--------|
+| `.paos/agent_tasks/tasks.sqlite3` | AgentTask records and append-only events |
+| `artifacts/agent_tasks//` | Before/after snapshots, bundle metadata, evidence entities |
+| `.paos/evolution/experience.sqlite3` | Bindings, episodes, Lessons, candidates, jobs, events |
+| Skill Runtime state path | Installed Runtime state, invocation/Session IDs, task bindings, and audit events |
+| Skill Runtime logs path | Lifecycle and Dora launch logs |
-## 10. 持久化边界
+SQLite updates and artifact writes are transactional or atomic within their own boundary. A
+Gateway response is not rolled back because local experience processing failed; evolution is
+fail-open.
-| Store | 内容 |
-|:------|:-----|
-| `.paos/agent_tasks/tasks.sqlite3` | AgentTask records 与 append-only events |
-| `artifacts/agent_tasks//` | before/after snapshot、bundle metadata、evidence entity |
-| `.paos/evolution/experience.sqlite3` | binding、episode、Lesson、candidate、job、event |
-| Skill Runtime state path | installed Runtime state、invocation/Session IDs、task bindings 与 audit events |
-| Skill Runtime logs path | 生命周期与 Dora launch 日志 |
+## 11. Skill Runtime and Registry boundary
-SQLite update 与 artifact write 在各自边界中保持事务或原子。不能因为本地 experience 处理
-失败而回滚 Gateway response;evolution fail-open。
+Registry/index clients return artifact metadata and downloads. Cache and installers require size
+and SHA-256, then validate archive inventories and the Node archive contract (single root
+executable, or a single root directory tree for `directory_tar_gz`) before atomic installation.
+RuntimeManager starts a named Dora flow and observes Gateway `/tools`; it never calls an alternate
+Gateway Agent API.
-## 11. Skill Runtime 与 Registry 边界
+The active Runtime availability provider supplies Skill visibility and Gateway URL to the Agent.
+It does not mutate AgentTask or experience data.
-Registry/index client 返回 artifact metadata 与下载。Cache/installer 要求 size 与 SHA-256,
-随后校验 archive inventory 和 Node 归档契约(单根目录可执行文件,或 `directory_tar_gz` 的单根目录树),再原子安装。RuntimeManager 启动命名 Dora flow
-并观察 Gateway `/tools`,不调用另一套 Gateway Agent API。
+## 12. Trust rules
-活动 Runtime availability provider 向 Agent 提供 Skill visibility 与 Gateway URL,但不修改
-AgentTask 或 experience 数据。
+- Treat ToolSpec, Gateway responses, WebSocket payloads, task text, and learned text as untrusted data.
+- Never log credentials or raw sensitive task inputs.
+- Never infer stop from cancel acceptance, timeout, or unknown.
+- Never bypass digest or archive safety checks.
+- Never place a second execution API between Agent tools and ForgeToolClient.
+- Keep Runtime force-stop and destructive artifact cleanup as explicit operator actions.
-## 12. 信任规则
+## Next reading
-- ToolSpec、Gateway response、WebSocket payload、task text 与 learned text 都是不可信数据;
-- 不记录凭据或原始敏感任务 input;
-- 不从 cancel accepted、timeout 或 unknown 推断停止;
-- 不绕过 digest 或 archive safety check;
-- 不在 Agent tools 与 ForgeToolClient 之间增加第二套执行 API;
-- Runtime force-stop 与破坏性 artifact cleanup 必须是显式运维动作。
-
-## 后续阅读
-
-- [集成开发指南](README.md)
-- [运行手册](../user_manual/README.md)
-- [Forge Tool API 契约](../forge/README_zh.md)
+- [Bundle and Tool Integration Reference](README.md)
+- [Operations Manual](../user_manual/README.md)
+- [Forge Tool API Contract](../forge/README.md)
diff --git a/docs/user_development_guide/COMMUNICATION_en.md b/docs/user_development_guide/COMMUNICATION_en.md
deleted file mode 100644
index 2fec0fd85..000000000
--- a/docs/user_development_guide/COMMUNICATION_en.md
+++ /dev/null
@@ -1,163 +0,0 @@
-# PhyAgentOS Communication Architecture
-
-[中文](COMMUNICATION.md) · [Documentation index](../README.md)
-
-> Version: 1.0.0
-
-## 1. Communication boundaries
-
-PhyAgentOS separates six boundaries:
-
-1. user/channel ↔ AgentLoop messages;
-2. Agent tools ↔ AgentTaskCoordinator;
-3. ForgeToolClient ↔ Gateway Query/Action/Session Tool API;
-4. observation collector ↔ Gateway image/state WebSockets;
-5. verifier ↔ isolated Verification Service;
-6. AgentTask/experience/Runtime ↔ their own persistent stores.
-
-The boundaries share opaque references, not execution ownership.
-
-## 2. User-message boundary
-
-Channels publish `InboundMessage` objects to the Agent bus. AgentLoop builds context, invokes the
-model and tools, then emits `OutboundMessage`. Tool calls use registered JSON schemas. The existing
-file, directory, shell, web, messaging, image, Scene Graph, Cron, Spawn, Agent Mode, Skill
-activation, and dynamic MCP tools follow this same loop.
-
-AgentTask's `origin_session_key` associates completion experience with the originating Agent
-conversation. It is not a Gateway execution identifier.
-
-## 3. AgentTask boundary
-
-```text
-forge_task_create
-forge_task_get
-forge_task_begin_revision
-forge_task_finalize
-forge_task_cancel
-```
-
-These tools call AgentTaskCoordinator and never call Dora or a robot. The coordinator uses
-transactional SQLite to enforce one non-terminal AgentTask and stores append-only PlanRevisions,
-Tool records, evidence references, and verification attempts.
-
-Diagnostic Query may omit `task_id`; governed Query and every Action/Session include it. The
-wrapper checks the immutable Skill/Runtime/ToolSpec binding and creates or updates the matching
-Tool record around the same Gateway request. This is aggregation, not another execution plane.
-
-## 4. Gateway HTTP boundary
-
-```text
-GET /tools
-GET /tools/{tool_id}
-GET /tools/{tool_id}/context
-POST /tools/{endpoint_id}/{operation}:invoke # Query, HTTP 200
-POST /tools/{tool_id}:invoke # Action/Session admission, HTTP 202
-GET /invocations/{invocation_id}
-GET /invocations/{invocation_id}/result # HTTP 202 while pending
-POST /invocations/{invocation_id}/cancel
-POST /invocations/{invocation_id}/stop # Session
-```
-
-Query invocation first reads the ToolSpec and uses its `endpoint_id`, `operation`, and
-`semantics=query` binding. Action/Session invocation addresses the stable Tool ID; both return an
-`invocation_id`, and Action also returns an `attempt_id`.
-
-Every successful response is a JSON object with `ok=true` and object-valued `data`. Error envelopes
-may carry code and retryability. A transport timeout means remote state is unknown. Returned
-invocation identities must be retained even if later local persistence or tracking fails.
-
-## 5. Identity boundary
-
-| Identity | Namespace | Mutability |
-|:---------|:----------|:-----------|
-| `task_id` | PAOS AgentTask | Stable for all revisions |
-| `binding_id` | PAOS Forge binding | Immutable Skill/Runtime/ToolSpec snapshot |
-| `revision_id` | PAOS PlanRevision | Immutable, append-only generation |
-| `record_id` | PAOS ToolExecutionRecord | Immutable record identity |
-| `caller_id` | PAOS ToolExecutionRecord | Persisted before asynchronous admission |
-| `invocation_id` | Gateway ToolInvocation | Stable Action/Session lifecycle identity |
-| `attempt_id` | Gateway attempt | Stable for the returned attempt |
-
-No component derives one namespace from another. Correlation happens by explicit stored references.
-
-## 6. Invocation terminal semantics
-
-Gateway status/result is the only Action/Session terminal source. Pending remains non-terminal. Known
-terminal values include success, failure, cancellation, or stopped as reported by Gateway.
-`unknown` is terminal for PAOS accounting because progress cannot be proven, but it is not a known
-physical stop and remains tracked for normal Runtime-stop gating.
-
-Cancellation/stop `requested` or `accepted` acknowledges control delivery only. It does not untrack an
-invocation or set an AgentTask to cancelled. PAOS continues reconciliation and finalizes the task
-explicitly.
-
-## 7. Evidence WebSocket boundary
-
-PAOS connects to configured image and optional state streams using bounded connection and capture
-timeouts. Messages are treated as untrusted input. Image media, decoded size, sequence, phase,
-source, local receive time, and SHA-256 are validated before persistence.
-
-The collector captures before the first bound physical execution and after task-owned executions reach terminal
-accounting state. Evidence association is best-effort; Gateway ToolResult and invocation events
-remain authoritative for execution.
-
-## 8. Verification boundary
-
-The Agent-side verifier sends resolved public task contracts, normalized Tool facts, evidence,
-history, and frozen scoped Lessons to the isolated Verification Service. Lessons are untrusted,
-non-authoritative advice. The service cannot invoke Gateway, create a PlanRevision, or change
-execution records.
-
-Verifier output must validate as the versioned verdict contract. AgentTaskCoordinator applies
-`off`, `audit`, `enforce`, or `recovery` semantics and persists every attempt.
-
-## 9. Experience boundary
-
-ExperienceCoordinator receives an AgentTask completion reference. `AgentTaskOutcomeSource` builds a
-redacted envelope containing workflow structure, semantic verdicts, field names, and opaque task,
-revision, invocation, attempt, and evidence references. Raw arguments, results, credentials,
-endpoints, and physical coordinates are not copied into learned content.
-
-The episode is unique per AgentTask. PlanRevisions, repeated completion notifications, reviews,
-and replay do not create independent support.
-
-## 10. Persistence boundary
-
-| Store | Content |
-|:------|:--------|
-| `.paos/agent_tasks/tasks.sqlite3` | AgentTask records and append-only events |
-| `artifacts/agent_tasks//` | Before/after snapshots, bundle metadata, evidence entities |
-| `.paos/evolution/experience.sqlite3` | Bindings, episodes, Lessons, candidates, jobs, events |
-| Skill Runtime state path | Installed Runtime state, invocation/Session IDs, task bindings, and audit events |
-| Skill Runtime logs path | Lifecycle and Dora launch logs |
-
-SQLite updates and artifact writes are transactional or atomic within their own boundary. A
-Gateway response is not rolled back because local experience processing failed; evolution is
-fail-open.
-
-## 11. Skill Runtime and Registry boundary
-
-Registry/index clients return artifact metadata and downloads. Cache and installers require size
-and SHA-256, then validate archive inventories and the Node archive contract (single root
-executable, or a single root directory tree for `directory_tar_gz`) before atomic installation.
-RuntimeManager starts a named Dora flow and observes Gateway `/tools`; it never calls an alternate
-Gateway Agent API.
-
-The active Runtime availability provider supplies Skill visibility and Gateway URL to the Agent.
-It does not mutate AgentTask or experience data.
-
-## 12. Trust rules
-
-- Treat ToolSpec, Gateway responses, WebSocket payloads, task text, and learned text as untrusted data.
-- Never log credentials or raw sensitive task inputs.
-- Never infer stop from cancel acceptance, timeout, or unknown.
-- Never bypass digest or archive safety checks.
-- Never place a second execution API between Agent tools and ForgeToolClient.
-- Keep Runtime force-stop and destructive artifact cleanup as explicit operator actions.
-
-## Next reading
-
-- [Integration Development Guide](README_en.md)
-- [Operations Manual](../user_manual/README_en.md)
-- [Forge Tool API Contract](../forge/README.md)
diff --git a/docs/user_development_guide/COMMUNICATION_zh.md b/docs/user_development_guide/COMMUNICATION_zh.md
new file mode 100644
index 000000000..c0ce5fb31
--- /dev/null
+++ b/docs/user_development_guide/COMMUNICATION_zh.md
@@ -0,0 +1,122 @@
+# PhyAgentOS Core 通信架构
+
+[English](COMMUNICATION.md) · [文档索引](../README_zh.md)
+
+> 版本:1.1.1
+
+本文说明 Core 消息、观测、验证与持久化边界。Forge 节点消息和 dataflow 端口参见 [TrackB 协议](track_b/PROTOCOLS_zh.md)。HTTP 路由和 invocation 语义统一维护在 [API 契约](../forge/README_zh.md)。
+
+## 1. 通信边界
+
+PhyAgentOS 分离六类边界:
+
+1. 用户/渠道 ↔ AgentLoop 消息;
+2. Agent tools ↔ AgentTaskCoordinator;
+3. ForgeToolClient ↔ Gateway Query/Action/Session Tool API;
+4. observation collector ↔ Gateway 图像/state WebSocket;
+5. verifier ↔ 独立 Verification Service;
+6. AgentTask/experience/Runtime ↔ 各自持久化存储。
+
+边界之间共享不透明 reference,不共享执行所有权。
+
+## 2. 用户消息边界
+
+渠道向 Agent bus 发布 `InboundMessage`。AgentLoop 构造上下文、调用模型与工具,再发送
+`OutboundMessage`。Tool call 遵循注册的 JSON schema。现有文件、目录、Shell、Web、消息、
+图片、Scene Graph、Cron、Spawn、Agent Mode、Skill activation 和动态 MCP tools 都使用同一
+Loop。
+
+AgentTask 的 `origin_session_key` 将 completion experience 关联到原 Agent conversation;它
+不是 Gateway execution identifier。
+
+## 3. AgentTask 边界
+
+任务生命周期工具清单见 [API 契约](../forge/README_zh.md#6-agent-tools)。
+
+这些 tools 调用 AgentTaskCoordinator,不调用 Dora 或机器人。Coordinator 使用事务 SQLite
+限制一个非终态 AgentTask,并保存只追加 PlanRevision、Tool record、evidence reference 与
+verification attempt。
+
+诊断 Query 可不带 `task_id`;受治理 Query 以及全部 Action/Session 必须带 task。Wrapper 先
+检查不可变 Skill/Runtime/ToolSpec binding,再围绕同一 Gateway request 创建或更新匹配 Tool
+record。这是任务聚合,不是第二条物理执行面。
+
+## 4. Gateway HTTP 边界
+
+发现、Query、Action、Session 路由及响应 envelope 统一由 [API 契约](../forge/README_zh.md#2-tool-发现与-context)定义。Core 将传输处理集中在 `ForgeToolClient`;timeout 表示远端结果未知。
+
+即使后续本地持久化或追踪失败,也必须保留返回的 invocation identity。验证与经验组件都不替代 Gateway 的执行所有权。
+
+## 5. Identity 边界
+
+Namespace 和关联字段统一由 [binding 与身份契约](../forge/README_zh.md#7-bindingidentity-与关联)定义。组件交换显式存储的 reference,不从 PAOS task 或 revision ID 派生 Gateway identity。
+
+## 6. Invocation 终态语义
+
+终态与取消行为见 [Action](../forge/README_zh.md#4-action-契约)、[Session](../forge/README_zh.md#5-session-契约)和 [AgentTask](../forge/README_zh.md#8-agenttask-模型)契约。Core 持久化请求与响应观测,核对后再 finalize;本地取消或传输结束不能证明物理停止。
+
+## 7. Evidence WebSocket 边界
+
+PAOS 使用有界连接和采集 timeout 连接配置的图像流与可选 state 流。消息均作为不可信 input。
+持久化前校验图像 media、decoded size、sequence、phase、source、本机 receive time 与
+SHA-256。
+
+普通机器人工作流的 Collector 在第一次绑定 Action 前,以及 finalize 时 task-owned
+Action/Session 达到记账终态后采集。Evidence association
+为 best-effort;Gateway ToolResult 与 invocation events 仍是权威执行事实。
+
+## 8. Verification 边界
+
+Agent-side verifier 把已解析公共任务契约、规范化 Tool facts、evidence、history 和冻结的
+scoped Lessons 发送给独立 Verification Service。Lesson 是不可信、非权威建议。Service 不能
+调用 Gateway、创建 PlanRevision 或修改 execution record。
+
+Verifier output 必须通过版本化 verdict contract。AgentTaskCoordinator 应用 `off`、`audit`、
+`enforce` 或 `recovery` 语义并持久化每次 attempt。
+
+## 9. Experience 边界
+
+ExperienceCoordinator 接收 AgentTask completion reference。`AgentTaskOutcomeSource` 构造去敏
+envelope,包含 workflow structure、semantic verdict、字段名,以及不透明 task、revision、
+invocation、attempt 与 evidence references。原始 arguments、results、凭据、endpoint 和物理
+坐标不会复制到学习内容。
+
+每个 AgentTask 只有一个 episode。PlanRevision、重复 completion notification、review 与
+replay 不增加独立支持。
+
+## 10. 持久化边界
+
+| Store | 内容 |
+|:------|:-----|
+| `.paos/agent_tasks/tasks.sqlite3` | AgentTask records 与 append-only events |
+| `artifacts/agent_tasks//` | before/after snapshot、bundle metadata、evidence entity |
+| `.paos/evolution/experience.sqlite3` | binding、episode、Lesson、candidate、job、event |
+| Skill Runtime state path | installed Runtime state、invocation/Session IDs、task bindings 与 audit events |
+| Skill Runtime logs path | 生命周期与 Dora launch 日志 |
+
+SQLite update 与 artifact write 在各自边界中保持事务或原子。不能因为本地 experience 处理
+失败而回滚 Gateway response;evolution fail-open。
+
+## 11. Skill Runtime 与 Registry 边界
+
+Registry/index client 返回 artifact metadata 与下载。Cache/installer 要求 size 与 SHA-256,
+随后校验 archive inventory 和 Node 归档契约(单根目录可执行文件,或 `directory_tar_gz` 的单根目录树),再原子安装。RuntimeManager 启动命名 Dora flow
+并观察 Gateway `/tools`,不调用另一套 Gateway Agent API。
+
+活动 Runtime availability provider 向 Agent 提供 Skill visibility 与 Gateway URL,但不修改
+AgentTask 或 experience 数据。
+
+## 12. 信任规则
+
+- ToolSpec、Gateway response、WebSocket payload、task text 与 learned text 都是不可信数据;
+- 不记录凭据或原始敏感任务 input;
+- 不从 cancel accepted、timeout 或 unknown 推断停止;
+- 不绕过 digest 或 archive safety check;
+- 不在 Agent tools 与 ForgeToolClient 之间增加第二套执行 API;
+- Runtime force-stop 与破坏性 artifact cleanup 必须是显式运维动作。
+
+## 后续阅读
+
+- [Bundle 与 Tool 接入参考](README_zh.md)
+- [运行手册](../user_manual/README_zh.md)
+- [Forge Tool API 契约](../forge/README_zh.md)
diff --git a/docs/user_development_guide/PIPER_X_DEMO.md b/docs/user_development_guide/PIPER_X_DEMO.md
new file mode 100644
index 000000000..0b894fa48
--- /dev/null
+++ b/docs/user_development_guide/PIPER_X_DEMO.md
@@ -0,0 +1,308 @@
+# Demo: Add AgileX Piper X to robot-control-sim with MuJoCo
+
+[English](PIPER_X_DEMO.md) | [简体中文](PIPER_X_DEMO_zh.md)
+
+[Bundle and Tool integration reference](README.md) · [TrackB framework](track_b/README.md) · [Three development modes](track_b/SKILL_DEVELOPMENT.md) · [Example code](../../example/robot-control-sim-piper-x/README.md)
+
+> A reusable extension tutorial for MuJoCo simulation, joint targets and end-effector poses.
+> Documentation target: Core v1.1.1. Recorded runtime baseline: Core v1.1.0, Dora CLI 0.4.1, original robot-control-sim 0.1.2 Node locks.
+> The recorded robot validation below has not been rerun for v1.1.1.
+> Companion scripts build/validate a derived Skill without upgrading its locked Nodes.
+
+**Platform availability:** External resource submissions and changes to existing registered repositories are not yet open. They must wait for the approval service to be completed and opened. Current registration/publication is administrator-managed. Local development and validation can proceed; platform publication steps below are conditional on that workflow becoming available. See the [contribution guide](../../CONTRIBUTING.md).
+
+## 1. Goal, baseline and scope
+
+The derived Skill is `robot-control-sim-piper-x`, profile `mujoco-piper-x`, preserving this native chain:
+
+```text
+Agent / diagnostic Tool API client
+ -> Gateway -> motion_action_policy -> motion_server (joint planning / URDF IK)
+ -> joint_trajectory_controller -> mujoco_sim
+ ^ JointState feedback
+```
+
+- `sim.set_joint_positions`: six absolute arm joint angles.
+- `sim.move_eef`: absolute end-effector position/orientation; original motion_server solves IK and generates trajectories.
+- Existing gripper policy/controller handles opening; sim-control policy provides metadata/reset.
+- Preserve all nine artifact/version/SHA256 locks. New content is model, profile, Skill workflow and developer utilities.
+- This tutorial does not validate hardware, motor dynamics identification, obstacle avoidance, grasping or whole-workspace reachability.
+
+Use the [official AgileX agx_arm_urdf Piper X model](https://github.com/agilexrobotics/agx_arm_urdf/tree/680fa925cd00db7e2628563d2edc5540963045de/piper_x),
+pinned to `680fa925cd00db7e2628563d2edc5540963045de`; do not rename an ordinary Piper model.
+The catalog's Forge 2.x / Dora 1.x source is a different baseline and must not be mixed into this deployment.
+
+Development order: pin upstream/locks, prepare model, create a profile, validate FK/servo behavior,
+package/install, validate both native Actions, optionally validate AgentTask, stop resources,
+then register/publish the derived Skill. The first eight stages produce a locally runnable package;
+publication still follows the destination platform's process.
+
+## 2. Prepare the environment and upstream Skill
+
+Use Linux x86_64, Python 3.12, Git, Dora CLI 0.4.1 and a Core v1.1.1 CLI environment; reproducing the original recorded validation requires Core v1.1.0.
+Keep Core and model-building environments separate so MuJoCo/numpy do not modify Core dependencies.
+See the [Core user manual](../en/02-user-manual.md) for installation, then check:
+
+```bash
+paos --help
+dora --version
+paos skill install robot-control-sim --version 0.1.2
+paos skill inspect robot-control-sim
+```
+
+In Core v1.1.1, as in the recorded v1.1.0 baseline, Registry `--version` constrains downloaded content rather than querying historical versions.
+If the current Registry has advanced, use a retained official immutable URL or local 0.1.2 archive:
+
+```bash
+paos skill install /path/to/robot-control-sim-0.1.2.tar.gz --local
+```
+
+Do not relabel another version as 0.1.2. Installation validates Bundle/Node digests; resolve missing Nodes
+through Registry or separately acquired matching archives. Nine Nodes are required; see the
+[source mapping](track_b/REPOSITORIES.md#3-robot-control-sim-node-to-source-mapping).
+
+## 3. Generate the model and independent profile
+
+Run these commands from the repository root. `PIPER_DEMO_UPSTREAM` identifies the installation shown
+by `paos skill inspect`. The example uses the default layout; for an isolated Core instance, use its actual Skill path.
+
+```bash
+PIPER_DEMO_ROOT="$PWD/example/robot-control-sim-piper-x"
+PIPER_DEMO_WORK="$PIPER_DEMO_ROOT/work"
+PIPER_DEMO_UPSTREAM="$HOME/.PhyAgentOS/skills/robot-control-sim"
+mkdir -p "$PIPER_DEMO_WORK"
+python3.12 -m venv "$PIPER_DEMO_ROOT/.venv-model"
+"$PIPER_DEMO_ROOT/.venv-model/bin/python" -m pip install -r "$PIPER_DEMO_ROOT/requirements-model.txt"
+git clone https://github.com/agilexrobotics/agx_arm_urdf.git "$PIPER_DEMO_WORK/agx_arm_urdf"
+git -C "$PIPER_DEMO_WORK/agx_arm_urdf" checkout 680fa925cd00db7e2628563d2edc5540963045de
+"$PIPER_DEMO_ROOT/.venv-model/bin/python" "$PIPER_DEMO_ROOT/build_skill.py" \
+ --upstream "$PIPER_DEMO_UPSTREAM" \
+ --models "$PIPER_DEMO_WORK/agx_arm_urdf" \
+ --output "$PIPER_DEMO_WORK/robot-control-sim-piper-x"
+```
+
+The generator checks model revision, clean model checkout, upstream Skill identity and all nine locks,
+and refuses an existing output directory. Use a new output path when rebuilding; upstream files are preserved.
+
+Without a display server, install Xvfb and append `--headless` to the generator command.
+This optional Linux path uses display `:92` and glow/software OpenGL; display and port `19104` must be free.
+Desktop runs retain DISPLAY. Changing either requires coordinated changes to generated `skill.yaml`,
+`gateway.yaml`, start/stop hooks and diagnostic client arguments.
+
+Generated layout:
+
+```text
+robot-control-sim-piper-x/
+├── skill.yaml
+├── SKILL.md
+├── profiles/mujoco-piper-x/*.yaml
+├── assets/robots/piper_x/
+│ ├── robot.yaml
+│ ├── piper_x_with_gripper.urdf
+│ ├── mjcf/{scene.xml,piper_x.xml,meshes/}
+│ ├── LICENSE.agilex
+│ └── PROVENANCE.json
+└── start.sh / stop_display.sh # --headless only
+```
+
+## 4. Understand the changes before adding another robot
+
+### 4.1 Model and frames
+
+The generator expands official URDF/gripper xacro, retaining STL geometry, kinematic chain and inertias,
+then adds MuJoCo position actuators, damping, armature and gravity compensation.
+These are simulation parameters, not calibrated hardware servo parameters.
+
+| Item | Convention |
+| --- | --- |
+| Arm group | `piper_x_arm` |
+| Joint order | `joint1` through `joint6`, positions in rad |
+| Base frame / TCP | `base_link` / `tcp` |
+| TCP definition | `[0, 0, 0.138]` m in `gripper_base`; URDF fixed link matches MJCF site |
+| End-effector target | Position in m; explicit `qx/qy/qz/qw` unit-quaternion fields |
+| Initial joint angles | `[0, 0.65, -1.10, 0.25, 0.30, 0.10]` |
+| Gripper | Logical total opening `0..0.1` m; opposing sliders coupled by equality, actuator gear=2 |
+
+The model has eight physical joint degrees of freedom but exposes six arm joints and one logical gripper value.
+Physical qpos count is not the Tool control dimension.
+
+Only adjacent `base_link/link1` collision is explicitly excluded because imported overlapping shells obstruct joint one.
+This model-specific geometry correction does not disable all collisions. Re-evaluate it for another robot rather than copying it blindly.
+
+### 4.2 Configuration changes
+
+| File | Facts that must agree |
+| --- | --- |
+| `robot.yaml` | Joint names/order/types/limits, initial_qpos, eef_site, gripper identity |
+| `simulator.yaml` | Model paths, initial state, logical joints, actuator_order, joint_to_actuator, cameras |
+| `motion_server.yaml` | Group, URDF, base/tip, speed/acceleration and tolerances |
+| `controller.yaml` | Arm joint order and control tolerances |
+| `gripper_controller.yaml` | Logical opening name/range and control parameters |
+| `sim_control_policy.yaml` | Descriptor path, reset motion group and gripper invocation |
+| `gateway.yaml` | ToolSpec group/frames/joint order/bounds/port/robot_frame_profile |
+| `dataflow.yaml` | Original motion chain with robot state, commands and camera ports |
+| `skill.yaml` | New Skill/profile, required_assets/tools, gateway_url, original locks |
+| `SKILL.md` | Both control modes, preparation, terminal results and verification; no keys or one-off task records |
+
+The readable generator updates these files together. For another robot, establish the model/frames first,
+then adapt the profile; do not relax tolerances to conceal frame or joint mapping errors.
+
+### 4.3 Two control modes, one execution chain
+
+Joint `positions[i]` corresponds to `joint_names[i]`, matching motion group, controller and logical simulator joints.
+Arm values are radians. Send logical gripper opening through its separate Tool, not physical sliders in a six-axis goal.
+End-effector mode specifies `tcp` in `base_link`; original motion_server performs IK.
+URDF fixed TCP and the matching MuJoCo site must express the same position/orientation.
+
+Example `sim.move_eef` arguments from the synthetic `eef-a` fixture:
+
+```json
+{
+ "group_name": "piper_x_arm",
+ "reference_frame": "base_link",
+ "target_frame": "tcp",
+ "target_pose": {
+ "x": 0.2870407951459706,
+ "y": -0.03170407513342734,
+ "z": 0.5422729661601198,
+ "qw": 0.7657215005588278,
+ "qx": 0.1641599926622322,
+ "qy": 0.6218396509287355,
+ "qz": -0.006126085528408748
+ },
+ "velocity_scale": 0.2,
+ "acceleration_scale": 0.2,
+ "position_tolerance_m": 0.005,
+ "orientation_tolerance_rad": 0.03
+}
+```
+
+Field names define quaternion meaning. MuJoCo arrays use `wxyz`; do not copy them directly as `xyzw`.
+Inspect Tool schema/readiness before invoking. Source inspection, raw payloads and successful FK checks
+do not replace terminal Action results and measured residuals.
+
+## 5. Validate the model before starting the pipeline
+
+```bash
+"$PIPER_DEMO_ROOT/.venv-model/bin/python" "$PIPER_DEMO_ROOT/validate_model.py" \
+ --skill "$PIPER_DEMO_WORK/robot-control-sim-piper-x" \
+ --output-dir "$PIPER_DEMO_WORK/model-check"
+```
+
+The script compares independent URDF matrix FK with MuJoCo sites at 31 poses and checks initial servo stability.
+This is model diagnostics, not Tool API/planning-chain acceptance. Position and rotation-matrix element differences
+should be below `1e-6`; inspect axes, origins, base/tip and TCP first on failure.
+
+Package/install from the activated **Core environment**, where `python` imports PhyAgentOS:
+
+```bash
+python scripts/package_skill.py "$PIPER_DEMO_WORK/robot-control-sim-piper-x" \
+ --output-dir "$PIPER_DEMO_WORK/dist"
+paos skill install "$PIPER_DEMO_WORK/dist/robot-control-sim-piper-x-0.1.2.tar.gz" --local
+paos forge-node verify robot-control-sim-piper-x motion_server
+paos forge-node verify robot-control-sim-piper-x mujoco_sim
+paos skill inspect robot-control-sim-piper-x
+paos skill start robot-control-sim-piper-x --profile mujoco-piper-x
+paos skill status robot-control-sim-piper-x
+```
+
+Packaging refuses existing output; increment the version for revisions. The generator uses `resolver=registry`
+to resolve original Node locks. Initial installation requires all dependencies to resolve; even a populated cache
+may query Registry metadata or probe URL size, so cache presence does not establish offline installation.
+`paos forge-node install --archive ` can install a local Node for an already-installed
+manifest, but cannot bypass first-install dependency resolution. Both paths must match locks and verify digests.
+
+## 6. Native validation of both control modes
+
+Keep the Core environment active and run the LLM-free diagnostic client:
+
+```bash
+python "$PIPER_DEMO_ROOT/accept_pipeline.py" \
+ --run-id piper-x-demo-001 \
+ --output-dir "$PIPER_DEMO_WORK/acceptance"
+```
+
+Use a fresh run-id each time. The native client runs three joint goals, three end-effector goals, gripper and reset.
+`motion-fixtures.json` contains reviewable synthetic targets; first confirm scene/profile compatibility.
+It queries robot metadata and Tool context, submits one Action at a time and waits for terminal status/results.
+Cartesian tests send poses only; they do not solve client-side IK and substitute joint commands.
+
+For initial debugging, run one joint goal and one Cartesian goal separately with new run-ids:
+
+```bash
+python "$PIPER_DEMO_ROOT/accept_pipeline.py" --only joint-a \
+ --run-id piper-x-joint-001 --output-dir "$PIPER_DEMO_WORK/acceptance"
+python "$PIPER_DEMO_ROOT/accept_pipeline.py" --only eef-a \
+ --run-id piper-x-eef-001 --output-dir "$PIPER_DEMO_WORK/acceptance"
+```
+
+| Check | Success criterion |
+| --- | --- |
+| Joint target | Correct six-joint order, motion `error_code=SUCCESS`, maximum absolute residual ≤0.03 rad |
+| End-effector target | Motion `error_code=SUCCESS`, position error ≤0.005 m, orientation error ≤0.03 rad |
+| Gripper | Controller SUCCESS and reached_goal |
+| Reset | Scene reset and rehomed |
+
+Raw Gateway `phase=completed` means terminal, while success additionally requires
+`data.result.status=succeeded`. Do not wait for nonexistent `phase=succeeded`.
+After a timeout, request cancellation and stop the run. Unknown is neither pending nor success and is not automatically resent.
+
+This developer diagnostic does not create AgentTask or an independent model verdict.
+To test the complete Agent workflow, configure your model Provider and explicitly select this Skill via
+`paos agent`, requesting one fixture joint/EEF goal. The Agent activates the primary Skill, creates/binds
+AgentTask, executes, finalizes and checks the persisted verdict. If execution succeeds but verdict is empty,
+report both separately; verifier failure must not trigger another motion.
+
+## 7. Troubleshooting order
+
+| Symptom | First checks | Direction |
+| --- | --- | --- |
+| One joint stalls, others arrive | Joint feedback, actuator mapping, contacts | Distinguish missing commands from contact obstruction; correct only justified adjacent collisions |
+| Joint mode works, EEF fails | URDF/MJCF FK, base/tip, quaternion order, reachability | Correct model/frames before IK tuning |
+| Window/render startup fails | DISPLAY, Xvfb, renderer, OpenGL | Optional headless profile; check display ownership |
+| Immediate result after 202 is unknown | Invocation still dispatching? | Poll status before results; preserve existing unknown diagnostics, do not resend |
+| Timeout argument rejected | Gateway schema/limit | Example invoke timeout is 20000 ms, separate from total Action wait |
+| Empty verifier output / HTTP 500 | Provider/verifier service errors | Preserve execution facts and empty verdict; investigate verification separately |
+| Deserialization fails after replacing a Node | Dora/Forge/message versions and locks | Restore a compatible version set; organization transfer is not protocol-upgrade validation |
+
+These diagnostic patterns contain no local logs, conversations, credentials or deployment-service addresses.
+
+## 8. Stop, reproduce and maintain
+
+```bash
+paos skill stop robot-control-sim-piper-x
+# --headless builds only: use the actual installation directory
+bash "$HOME/.PhyAgentOS/skills/robot-control-sim-piper-x/stop_display.sh"
+```
+
+Do not stop unrelated flows/displays. Record your Bundle SHA256, locks, model revision, profile and environment.
+Keep runtime validation results local rather than embedding machine-specific records in the public example.
+
+Before submitting another-robot example, validate model FK/limits, both native Actions, clean installation and stop.
+Node algorithm changes additionally need unit/integration tests; a handful of tutorial goals do not prove complete control coverage.
+
+## 9. Another robot and deliverables
+
+This generator targets Piper X, not arbitrary URDF import through a universal `--robot` flag.
+When reusing the approach, check:
+
+- [ ] Model source/revision/license are verifiable; URDF/MJCF share kinematics and TCP.
+- [ ] Joint axes, units, limits, order and logical/physical gripper mapping agree.
+- [ ] Initial state/servo behavior is acceptable; collision exclusions have geometric justification.
+- [ ] Group, base/tip, Tool schemas, controller and simulator configuration agree.
+- [ ] Native joint and EEF targets pass independently; Cartesian IK runs server-side.
+- [ ] Timeout/cancel/unknown are diagnosable and failed motion is not blindly repeated.
+- [ ] Skill identity/version/assets/locks, startup/stop and isolated installation are checked.
+
+Public deliverables include model conversion instructions, profile, Skill workflow, reviewable test targets,
+locks, licenses and build guidance. Exclude credentials, internal deployments and personal conversations;
+submit execution evidence separately through the resource platform where required.
+
+The example adds a Skill, not nine duplicate Nodes. Confirm matching dependency versions/digests on the target platform,
+then submit the new Skill version, technical validation and required execution evidence. Reuse existing Node records
+only after identity checks; rebuilt Nodes need new versions and updated Skill locks.
+See [source build and provenance](track_b/SKILL_DEVELOPMENT.md#4-mode-three-develop-nodes-and-assemble-a-skill).
+
+Successful `--local` installation does not establish registration or review/publication. After publication,
+use a compatible consumer API to search by name, install into an isolated instance and verify each Node.
+Static catalog changes or upload completion are not final acceptance.
diff --git a/docs/user_development_guide/PIPER_X_DEMO_zh.md b/docs/user_development_guide/PIPER_X_DEMO_zh.md
new file mode 100644
index 000000000..eafd6c62e
--- /dev/null
+++ b/docs/user_development_guide/PIPER_X_DEMO_zh.md
@@ -0,0 +1,303 @@
+# Demo:在 robot-control-sim 中接入 AgileX Piper X(MuJoCo)
+
+[English](PIPER_X_DEMO.md) | [简体中文](PIPER_X_DEMO_zh.md)
+
+[Bundle 与 Tool 接入参考](README_zh.md) · [TrackB 框架说明](track_b/README_zh.md) · [三种开发模式](track_b/SKILL_DEVELOPMENT_zh.md) · [示例代码](../../example/robot-control-sim-piper-x/README_zh.md)
+
+> 本教程将一次实际二次开发过程整理为可复用示例。范围:MuJoCo 仿真、关节目标和末端位姿运动。
+> 文档目标版本:Core v1.1.1。历史运行基线:Core v1.1.0、Dora CLI 0.4.1、robot-control-sim 0.1.2 原始 Node locks。
+> 下文记录的机器人验证尚未在 v1.1.1 上重新执行。
+> 配套脚本生成并验证派生 Skill,不升级锁定的 Node。
+
+**平台开放范围:** 外部贡献提交及已有登记仓库修改暂未开放,需等待审批服务完成并开放。当前登记与发布由管理员维护;可先进行本地开发验证。下文的平台发布步骤以相关流程开放为前提,详见[贡献指南](../../CONTRIBUTING_zh.md)。
+
+## 1. 目标、基线与边界
+
+派生 Skill 名为 `robot-control-sim-piper-x`,profile 为 `mujoco-piper-x`,保留以下原生执行链:
+
+```text
+Agent / diagnostic Tool API client
+ → Gateway → motion_action_policy → motion_server(关节规划 / URDF IK)
+ → joint_trajectory_controller → mujoco_sim
+ ↑ JointState feedback
+```
+
+- `sim.set_joint_positions`:按六个绝对关节角运动。
+- `sim.move_eef`:按绝对末端位置与方向运动,由原 motion_server 求 IK 并生成轨迹。
+- 原有 gripper policy/controller 提供夹爪开度控制,sim-control policy 提供元数据与复位。
+- 九个 Node 的 artifact/version/SHA256 保持原样;新内容是模型、profile、Skill 工作流和开发工具。
+- 本教程不验证真机、电机动力学辨识、避障规划、抓取或全工作区可达性。
+
+模型来源为 [AgileX 官方 agx_arm_urdf](https://github.com/agilexrobotics/agx_arm_urdf/tree/680fa925cd00db7e2628563d2edc5540963045de/piper_x),
+固定 commit `680fa925cd00db7e2628563d2edc5540963045de`。使用真正的 Piper X 模型,而非重命名普通 Piper。
+源码索引中的最新 Forge 2.x / Dora 1.x 与本例运行基线不同,不得混装。
+
+完整开发顺序为:确认上游版本和锁 → 准备模型 → 生成独立 profile → 验证 FK/伺服 →
+打包与本地安装 → 验证两种原生 Action → 按需验证 AgentTask → 停止资源 → 登记并发布派生 Skill。
+前八步完成后可得到本地可运行的派生包;最后一步仍须通过所用资源平台的流程。
+
+## 2. 准备环境和上游 Skill
+
+在 Linux x86_64 上准备 Python 3.12、Git、Dora CLI 0.4.1,以及 Core v1.1.1 的 CLI 环境;复现原始验证记录时使用 Core v1.1.0。
+本文示例文件随开发手册提供;Core 运行环境与模型构建环境分开,避免 MuJoCo/numpy 依赖改变 Core 环境。
+基础安装见 [Core 用户手册](../zh/02-user-manual.md)。先确认:
+
+```bash
+paos --help
+dora --version
+paos skill install robot-control-sim --version 0.1.2
+paos skill inspect robot-control-sim
+```
+
+Registry 的 `--version` 是下载后约束,不是历史版本查询。如果当前 Registry 已更新,
+应使用保存的官方不可变 URL 或本地 0.1.2 归档:
+
+```bash
+paos skill install /path/to/robot-control-sim-0.1.2.tar.gz --local
+```
+
+不要将其他版本改名为 0.1.2。安装会验证 Bundle/Node 摘要;缺失 Node 需从 Registry 或
+独立取得的匹配归档安装。配置依赖九个节点,参见 [Node 源码映射](track_b/REPOSITORIES_zh.md#3-robot-control-sim-的-node-与源码映射)。
+
+## 3. 生成模型和独立 profile
+
+以下命令在本仓根目录执行。`PIPER_DEMO_UPSTREAM` 指向 `paos skill inspect` 对应的安装目录;
+示例给出默认安装布局;使用独立 Core 配置实例时,应改成该实例实际的 Skill 安装路径。
+
+```bash
+PIPER_DEMO_ROOT="$PWD/example/robot-control-sim-piper-x"
+PIPER_DEMO_WORK="$PIPER_DEMO_ROOT/work"
+PIPER_DEMO_UPSTREAM="$HOME/.PhyAgentOS/skills/robot-control-sim"
+mkdir -p "$PIPER_DEMO_WORK"
+python3.12 -m venv "$PIPER_DEMO_ROOT/.venv-model"
+"$PIPER_DEMO_ROOT/.venv-model/bin/python" -m pip install -r "$PIPER_DEMO_ROOT/requirements-model.txt"
+git clone https://github.com/agilexrobotics/agx_arm_urdf.git "$PIPER_DEMO_WORK/agx_arm_urdf"
+git -C "$PIPER_DEMO_WORK/agx_arm_urdf" checkout 680fa925cd00db7e2628563d2edc5540963045de
+"$PIPER_DEMO_ROOT/.venv-model/bin/python" "$PIPER_DEMO_ROOT/build_skill.py" \
+ --upstream "$PIPER_DEMO_UPSTREAM" \
+ --models "$PIPER_DEMO_WORK/agx_arm_urdf" \
+ --output "$PIPER_DEMO_WORK/robot-control-sim-piper-x"
+```
+
+生成器检查模型 revision、模型工作区无修改、上游 Skill 身份与九个 Node lock;已有输出目录会拒绝覆盖。
+重做时用新输出目录。原始上游文件保持不变。
+
+无显示服务器:先安装系统 Xvfb,在生成命令末尾增加 `--headless`。
+该选项使用独立 display `:92`、glow/software OpenGL,端口 `19104` 和 display 必须空闲。
+它是可选 Linux 示例;桌面环境保留现有 DISPLAY。需要更换端口或 display 时,统一调整生成后的
+`skill.yaml`、`gateway.yaml`、启动/停止钩子及验收客户端参数。
+
+生成目录包括:
+
+```text
+robot-control-sim-piper-x/
+├── skill.yaml
+├── SKILL.md
+├── profiles/mujoco-piper-x/*.yaml
+├── assets/robots/piper_x/
+│ ├── robot.yaml
+│ ├── piper_x_with_gripper.urdf
+│ ├── mjcf/{scene.xml,piper_x.xml,meshes/}
+│ ├── LICENSE.agilex
+│ └── PROVENANCE.json
+└── start.sh / stop_display.sh # 仅 --headless
+```
+
+## 4. 理解改动,才能接入下一种 robot
+
+### 4.1 模型和坐标
+
+生成器展开官方 URDF/夹爪 xacro,使用官方 STL、运动链和惯量;给 MuJoCo 增加 position actuators、
+阻尼、armature 和重力补偿。这些是仿真参数,不是经过标定的真机伺服参数。
+
+| 项目 | 本例约定 |
+| --- | --- |
+| arm group | `piper_x_arm` |
+| 关节顺序 | `joint1` 到 `joint6`,位置单位 rad |
+| base frame / TCP | `base_link` / `tcp` |
+| TCP 定义 | `gripper_base` 坐标系中 `[0, 0, 0.138]` m;URDF 固定 link 与 MJCF site 一致 |
+| 末端目标 | 位置 m;显式字段 `qx/qy/qz/qw`,单位四元数 |
+| 初始关节角 | `[0, 0.65, -1.10, 0.25, 0.30, 0.10]` |
+| 夹爪 | 逻辑总开度 `0..0.1` m;两个物理 slider 通过 equality 反向耦合,actuator gear=2 |
+
+模型有 8 个物理关节自由度,但对外暴露 6 个臂关节加 1 个逻辑夹爪量。
+不能把物理 qpos 数量直接当 Tool 的控制维度。
+
+仅显式排除相邻 `base_link/link1` 的碰撞:本模型导入后的外壳重叠会阻碍第一关节运动。
+这是针对模型几何的处理,不是关闭全部碰撞;换机器人时必须重新检查,不能盲目复制该例外。
+
+### 4.2 配置改动表
+
+| 文件 | 需要保持一致的内容 |
+| --- | --- |
+| `robot.yaml` | joint 名称/顺序/类型/限位、initial_qpos、eef_site、夹爪标识 |
+| `simulator.yaml` | 模型路径、初始状态、逻辑关节、actuator_order、joint_to_actuator、相机输出 |
+| `motion_server.yaml` | group、URDF、base/tip、速度/加速度与容差 |
+| `controller.yaml` | 臂关节顺序和控制容差 |
+| `gripper_controller.yaml` | 逻辑开度名称、范围及控制参数 |
+| `sim_control_policy.yaml` | descriptor 路径、reset 的 motion group 和夹爪调用 |
+| `gateway.yaml` | ToolSpec 的 group、frame、joint order、输入范围、端口与 robot_frame_profile |
+| `dataflow.yaml` | 保留原运动链;连接机器人状态、控制命令和相机端口 |
+| `skill.yaml` | 新 Skill 名称、profile、required_assets/tools、gateway_url、原 Node locks |
+| `SKILL.md` | 描述两种控制方式、准备检查、终态判断和任务验证;不嵌入密钥或一次性任务记录 |
+
+生成器同时更新上述配置,源码是可阅读的修改示例。开发另一种机器人时,应先确定模型与坐标,
+再修改 profile;不要用放宽容差来掩盖坐标或关节映射错误。
+
+### 4.3 两种控制模式共用同一执行链
+
+关节模式的 `positions[i]` 对应 `joint_names[i]`,顺序须与 motion group、controller 和模拟器的逻辑关节一致。
+六个臂关节使用 rad;夹爪通过单独 Tool 传逻辑开度,不把两个物理 slider 塞入六维臂目标。
+末端模式只给出 `base_link` 下 `tcp` 的目标位姿,由原 motion_server 求 IK;
+URDF 的 fixed TCP 与 MuJoCo 的同名 site 必须表达同一个位置和方向。
+
+下面是 `sim.move_eef` 的 Tool arguments,来自示例的 `eef-a` 合成目标:
+
+```json
+{
+ "group_name": "piper_x_arm",
+ "reference_frame": "base_link",
+ "target_frame": "tcp",
+ "target_pose": {
+ "x": 0.2870407951459706,
+ "y": -0.03170407513342734,
+ "z": 0.5422729661601198,
+ "qw": 0.7657215005588278,
+ "qx": 0.1641599926622322,
+ "qy": 0.6218396509287355,
+ "qz": -0.006126085528408748
+ },
+ "velocity_scale": 0.2,
+ "acceleration_scale": 0.2,
+ "position_tolerance_m": 0.005,
+ "orientation_tolerance_rad": 0.03
+}
+```
+
+字段名明确规定四元数含义;MuJoCo 的四元数数组使用 `wxyz`,不要将数组直接按 `xyzw` 填入。
+检查工具 context 中的 schema 和 readiness 后再调用。源码查询、原始载荷或模型 FK 的通过,
+都不能代替 Action 终态与实际残差检查。
+
+## 5. 先验证模型,再启动 pipeline
+
+```bash
+"$PIPER_DEMO_ROOT/.venv-model/bin/python" "$PIPER_DEMO_ROOT/validate_model.py" \
+ --skill "$PIPER_DEMO_WORK/robot-control-sim-piper-x" \
+ --output-dir "$PIPER_DEMO_WORK/model-check"
+```
+
+该脚本用独立 URDF 矩阵计算和 MuJoCo site 对比 31 个姿态的 FK,检查初始姿态伺服稳定性。
+它只是模型诊断,不代表 Tool API/运动规划链验收成功。预期位置差和旋转矩阵元素差均小于 `1e-6`;
+失败时先排查关节轴、origin、base/tip 和 TCP。
+
+在已激活的 **Core 环境** 中打包和安装(这里的 `python` 应能导入 PhyAgentOS):
+
+```bash
+python scripts/package_skill.py "$PIPER_DEMO_WORK/robot-control-sim-piper-x" \
+ --output-dir "$PIPER_DEMO_WORK/dist"
+paos skill install "$PIPER_DEMO_WORK/dist/robot-control-sim-piper-x-0.1.2.tar.gz" --local
+paos forge-node verify robot-control-sim-piper-x motion_server
+paos forge-node verify robot-control-sim-piper-x mujoco_sim
+paos skill inspect robot-control-sim-piper-x
+paos skill start robot-control-sim-piper-x --profile mujoco-piper-x
+paos skill status robot-control-sim-piper-x
+```
+
+打包命令默认拒绝覆盖同名输出;发布修订时递增版本。示例生成器使用 `resolver=registry`,
+以便安装时解析原有 Node locks。首次安装要求全部依赖可解析;使用预置缓存时也仍可能查询 Registry
+元数据或探测直链文件大小,不能仅凭缓存存在就宣称可完全离线安装。
+`paos forge-node install --archive ` 可为清单已安装的 Skill 安装本地 Node,
+但不能用它绕过首次 Skill 安装时的依赖解析。两种方式都必须匹配原 lock 并保留摘要校验。
+
+## 6. 两种控制方式的原生验收
+
+保持 Core 环境,运行无需 LLM 的诊断客户端:
+
+```bash
+python "$PIPER_DEMO_ROOT/accept_pipeline.py" \
+ --run-id piper-x-demo-001 \
+ --output-dir "$PIPER_DEMO_WORK/acceptance"
+```
+
+每次重跑使用新的 run-id。客户端只通过原生 Tool API,依次执行三组关节目标、三组末端目标、夹爪和复位。
+`motion-fixtures.json` 是可审阅的合成目标;执行前确认当前 scene/profile 与本例一致。
+它先查询 robot metadata 和 Tool context,随后每次只提交一个 Action,等待终态再读取 result。
+末端测试仅发送 Cartesian pose,不在客户端求 IK 后改发关节命令。
+
+初次调试也可分别执行一个关节目标和一个末端目标,每次使用新的 run-id:
+
+```bash
+python "$PIPER_DEMO_ROOT/accept_pipeline.py" --only joint-a \
+ --run-id piper-x-joint-001 --output-dir "$PIPER_DEMO_WORK/acceptance"
+python "$PIPER_DEMO_ROOT/accept_pipeline.py" --only eef-a \
+ --run-id piper-x-eef-001 --output-dir "$PIPER_DEMO_WORK/acceptance"
+```
+
+| 验收项 | 判断依据 |
+| --- | --- |
+| 关节目标 | 六关节顺序正确、motion `error_code=SUCCESS`、最大绝对残差 ≤0.03 rad |
+| 末端目标 | motion `error_code=SUCCESS`,位置误差 ≤0.005 m,方向误差 ≤0.03 rad |
+| 夹爪 | controller SUCCESS 且 reached_goal |
+| 复位 | scene reset 且 rehomed |
+
+Gateway raw invocation 的 `phase=completed` 表示终结;执行成功还需检查 result 中的
+`data.result.status=succeeded`。不能等待不存在的 `phase=succeeded`。
+超时请求取消后停止本轮;unknown 不自动重发,也不当作 pending 或成功。
+
+此脚本是开发者执行链诊断,不创建 AgentTask,也不产生独立模型 verdict。
+若要测试完整 Agent 工作流,配置自己的模型 Provider 后,通过 `paos agent` 明确选择此 Skill,
+要求只完成一个关节或末端目标。Agent 应激活 primary Skill、创建并绑定 AgentTask,
+执行终结后 finalize,再检查持久化 verdict。复用 fixtures 的一个目标即可,避免同时改变任务和模型。
+执行成功但 verdict 为空时,分别报告两个事实;Verifier 错误不应触发重新运动。
+
+## 7. 常见问题与诊断顺序
+
+| 现象 | 首先检查 | 处理方向 |
+| --- | --- | --- |
+| 一个关节卡住,其余到位 | 实际关节反馈、actuator 映射、接触对 | 区分控制未下发与接触力阻碍;只修正有依据的相邻碰撞 |
+| 关节模式正常,末端模式异常 | URDF/MJCF FK、base/tip、四元数顺序、目标可达性 | 先修正坐标和模型,再检查 IK 配置 |
+| 窗口/渲染启动失败 | DISPLAY、Xvfb、renderer 和 OpenGL | 使用可选 headless profile,确认 display 未占用 |
+| 202 后立即读 result 得到 unknown | 调用是否仍在 dispatching | 先轮询 status 到终态;已有 unknown 保留诊断,不重发 |
+| 接口拒绝 timeout | Gateway 当前 schema/上限 | 本例 invoke timeout 使用 20000 ms;它不同于整个动作等待时间 |
+| Verifier 空输出 / HTTP 500 | Provider 与 verifier 服务错误 | 保留执行事实和空 verdict;单独定位验证服务 |
+| 更新某个 Node 后反序列化失败 | Dora/Forge/message 版本和锁 | 恢复一致版本集;组织迁移不能替代协议升级验收 |
+
+这些条目来自该类集成中的实际诊断过程,教程不附带本机日志、会话记录、凭据或服务地址。
+
+## 8. 停止、复现与维护
+
+```bash
+paos skill stop robot-control-sim-piper-x
+# 仅 --headless 构建:在实际安装目录执行
+bash "$HOME/.PhyAgentOS/skills/robot-control-sim-piper-x/stop_display.sh"
+```
+
+不要停止其他 dataflow 或显示服务。记录自己构建的 Bundle SHA256、Node locks、模型 revision、
+profile 和运行环境;保留本地验收结果,不将本机运行记录混入公开示例。
+
+提交新机器人示例前至少完成:模型 FK/限位检查、两种原生 Action、干净环境安装、资源停止。
+修改 Node 算法则另外完成其单元测试和跨节点集成测试,不能只用本教程的几个目标证明完整控制能力。
+
+## 9. 接入下一种机械臂与提交交付物
+
+本例生成器专用于 Piper X,不是通过一个 `--robot` 参数导入任意 URDF 的通用工具。
+复用其方法接入下一种机器人时,按下面的清单逐项确认:
+
+- [ ] 模型来源、固定 revision 和许可证可核对;URDF/MJCF 共享同一运动链和 TCP 定义。
+- [ ] 关节轴、单位、限位、顺序及夹爪逻辑量与物理关节的映射一致。
+- [ ] 初始状态可接受,伺服稳定;碰撞排除有具体几何依据。
+- [ ] group、base/tip、Tool schema、controller 与 simulator 配置对应。
+- [ ] 原生关节目标与原生末端位姿各自通过,Cartesian 测试由服务端求 IK。
+- [ ] 超时/取消/unknown 的处理可诊断,失败动作不自动重发。
+- [ ] 新 Skill 身份、版本、资产清单、Node locks、启动/停止和独立安装均完成核对。
+
+交付的公开示例应包含模型生成/转换说明、profile、Skill 工作流、可审阅测试目标、依赖锁、
+许可证与构建说明。环境凭据、内部部署信息和个人会话记录不进入示例;运行验收材料按资源平台要求单独提交。
+
+本例只新增 Skill,不需要重复创建九个既有 Node。登记前确认这些依赖在目标平台存在且版本/摘要一致,
+再按平台要求提交新的 Skill 版本、技术校验和运行证据。已存在的 Node 记录先核对再复用;
+若确实重建了 Node,则使用新 Node 版本并更新派生 Skill lock,流程见
+[源码构建与制品溯源](track_b/SKILL_DEVELOPMENT_zh.md#4-模式三独立开发-node-并组装自己的-skill)。
+
+本地 `--local` 安装成功不代表平台已登记或审核发布。发布后,才以该平台匹配的消费者 API 验证
+按名称检索、安装到独立实例及逐 Node verify;不要把静态目录变更或上传完成当作最终验收。
diff --git a/docs/user_development_guide/README.md b/docs/user_development_guide/README.md
index bdc8281aa..2aa6f1afc 100644
--- a/docs/user_development_guide/README.md
+++ b/docs/user_development_guide/README.md
@@ -1,30 +1,24 @@
-# PhyAgentOS 集成开发指南
+# Bundle and Tool Integration Reference
-[English](README_en.md) · [文档索引](../README.md)
+[English](README.md) | [简体中文](README_zh.md)
-> 版本:1.0.0
+> Version: 1.1.1
-## 1. 选择接入点
+Use the [TrackB Skill development manual](track_b/SKILL_DEVELOPMENT.md) to choose a development mode and follow its procedure. This reference owns ToolSpec examples, manifest-v2 fields, startup hooks, packaging and conformance details. Public HTTP and lifecycle semantics are defined in the [Forge Tool API contract](../forge/README.md).
-| 能力 | 接入点 |
-|:-----|:-------|
-| 机器人读取或计算 | Gateway Query ToolSpec + ToolEndpoint operation |
-| 机器人物理效果 | Gateway Action ToolSpec + ToolEndpoint operation |
-| 有状态能力生命周期 | Gateway Session ToolSpec + ToolEndpoint operation |
-| Dora nodes 与部署资产 | manifest v2 Skill Bundle 与锁定 Node artifacts |
-| 工作流说明 | 由 SkillsLoader 发现的 `SKILL.md` |
-| 用户任务成功 | 通用 `TaskVerificationContract` 与 AgentTask finalize |
-| 新模型 Provider | 现有 provider registry/configuration |
-| 非机器人 Agent 能力 | 现有 Agent ToolRegistry 或动态 MCP |
+**Platform availability:** External resource submissions and changes to existing registered repositories are not yet open. They must wait for the approval service to be completed and opened. Current registration/publication is administrator-managed. Local development and validation can proceed; platform publication steps below are conditional on that workflow becoming available. See the [contribution guide](../../CONTRIBUTING.md).
-不要把 Agent 代码直接连接到机器人 SDK、Dora node、仿真器,或统一 Tool API 之外的旧式
-Gateway Session/Policy route。
+## 1. Choose the integration point
-## 2. 定义 ToolSpec
+Start with [TrackB](track_b/README.md) for robot models, profiles, Nodes and Skills. Read the [Core developer manual](../en/03-developer-manual.md) for AgentTask, binding, verification or installer implementation. Use the [communication reference](COMMUNICATION.md) for Agent bus, WebSocket and persistence boundaries.
-每个 ToolSpec 包含稳定 `tool_id`、implementation/endpoint binding、operation、
-`semantics: query|action|session`、description、严格 input/output JSON schema、readiness,以及空间
-输入所需 robot frame profile。
+Integrations use the governed Tool API; do not connect Agent code directly to a robot SDK, Dora Node or simulator outside that path.
+
+## 2. Define a ToolSpec
+
+Every ToolSpec has a stable `tool_id`, implementation and endpoint binding, operation,
+`semantics: query|action|session`, description, strict input/output JSON schemas, readiness requirements,
+and a robot frame profile when spatial inputs are involved.
```yaml
tool_id: motion.resolve_relative_pose
@@ -54,53 +48,32 @@ robot_frame_profile:
tool_frame: tcp
```
-同步读取或不产生机器人效果的确定性解析使用 Query;有界物理效果使用 Action;显式有所有权
-的有状态生命周期使用 Session。在执行方
-定义 Endpoint operation `max_concurrency`,PAOS 不创建跨 Tool lease。
-
-## 3. 实现 Query、Action 与 Session 行为
-
-Query 从 ToolSpec 解析并调用:
-
-```text
-POST /tools/{endpoint_id}/{operation}:invoke → HTTP 200
-```
-
-Action admission 使用:
+Use Query for synchronous reads or deterministic resolution without a robot effect. Use Action for
+bounded physical effects and Session for explicitly owned, stateful lifecycles. Define Endpoint operation `max_concurrency` at
+the execution owner; PAOS does not create a cross-Tool lease.
-```text
-POST /tools/{tool_id}:invoke → HTTP 202 + invocation_id + attempt_id
-GET /invocations/{invocation_id}
-GET /invocations/{invocation_id}/result
-POST /invocations/{invocation_id}/cancel
-```
+## 3. Implement Query, Action, and Session behavior
-Session admission 使用同一 `POST /tools/{tool_id}:invoke` 契约,通过通用 invocation routes
-核对,并以 `POST /invocations/{invocation_id}/stop` 停止。必须声明 task-owned、shared 或
-runtime-owned;一个 owner 不得停止另一个 owner 的 Session。
+Use the [Query](../forge/README.md#3-query-contract), [Action](../forge/README.md#4-action-contract) and [Session](../forge/README.md#5-session-contract) contracts for HTTP admission, reconciliation, ownership and terminal behavior. The [Node protocol guide](track_b/PROTOCOLS.md) covers provider and Dora ports.
-Action status/result 必须暴露明确生命周期;result pending 时可返回 HTTP 202。Cancel accepted
-只表示控制处理。无法恢复执行事实时应返回显式 unknown,不能伪造 cancelled 或 success。
+Inputs and outputs must be finite JSON and satisfy ToolSpec. Spatial Tools must expose frames, units, tolerances and orientation behavior through inspectable context. Use explicit unknown outcomes when execution truth cannot be recovered; admission and cancellation acceptance do not prove completion or physical stop.
-Input/output 必须是有限 JSON 并满足 ToolSpec。空间 Tool 必须说明 frame、unit、tolerance 与
-orientation behavior,避免 Agent 无法通过 `forge_tool_context` 检查的隐藏默认值。
+## 4. Build a manifest-v2 Skill Bundle
-## 4. 构建 manifest v2 Skill Bundle
-
-已安装 Skill Bundle 包含:
+An installed Skill Bundle contains:
```text
/
├── skill.yaml
├── SKILL.md
-├── start.sh # 可选,Dora 启动前准备外部资源
-├── archive-manifest.json # 打包脚本生成
+├── start.sh # optional external-resource preparation before Dora
+├── archive-manifest.json # generated by the packaging script
├── profiles//dataflow.yaml
├── profiles//...
└── assets/...
```
-最小 manifest 结构:
+Minimal manifest structure:
```yaml
manifest_version: 2
@@ -113,7 +86,7 @@ required_tools: [example.query, example.action]
profiles:
sim:
dataflow: profiles/sim/dataflow.yaml
- # 可选:覆盖 Skill 级 required_tools;省略则继承
+ # optional: overrides the Skill-wide required_tools; omit to inherit
required_tools: [example.query]
required_binaries: [gateway, example_node]
required_assets: [assets/scene.xml]
@@ -132,50 +105,57 @@ artifacts:
sha256: <64-character-sha256>
```
-所有路径必须相对并包含在 Bundle 内。每个 Node archive 具有 lock 指定的 SHA-256。
-`executable_tar_gz` 只包含一个 lock 指定文件名的根目录 executable;`directory_tar_gz`
-只包含一个以 `entrypoint` 命名的根目录,同名 executable 及其运行时树置于其中(仅允许
-解析不出树的相对符号链接)。installer 在 receipt 中另行记录解包后 binary hash。
-Bundle archive inventory 需要覆盖每个文件及 SHA-256;links、路径穿越、冲突、过度展开和未列出
-内容会被拒绝。
-
-Bundle 如需在启动前下载权重或准备其他外部资源,可在根目录提供 `start.sh`。PAOS 使用
-`bash /start.sh ` 调用它,不改变工作目录并继承终端 stdio;脚本应从
-自身路径解析 Bundle 内文件,支持重复执行,并在失败时返回非零退出码。此类 Bundle 要求主机
-`PATH` 中存在 Bash。`PAOS_SKILL_NAME` 与 `PAOS_SKILL_VERSION` 可用于 dataflow 占位符,
-也会进入 Dora 进程环境。
-
-Hook 的环境契约:除 `PAOS_SKILL_NAME` / `PAOS_SKILL_VERSION` 外,PAOS 还会传入
-`PAOS_SKILL_PROFILE`(本次启动的 profile 名)、`PAOS_SKILL_ROOT`(Bundle 根目录)和
-`PAOS_HOOK_PYTHON`(运行 PAOS Core 的解释器)。`PAOS_HOOK_PYTHON` 只保证能执行 Core 自身的依赖,
-**不保证**包含任何模型运行时依赖:要在 Hook 里准备 CUDA 版 PyTorch / transformers 之类,请自行创建
-虚拟环境或调用外部工具,不要假定它可用。
-
-`profiles..required_tools` 是可选字段:写了覆盖 Skill 级 `required_tools`,不写则继承。
-这一个字段同时承担两个契约——启动与状态健康检查要求就绪的 Tool 集合,以及 AgentTask 允许该 Skill
-调用的 Tool allowlist(`forge/binding.py` 冻结进 AgentTask 的 `required_tools` 就是同一份列表)。
-因此一个 Bundle 可以按 profile 暴露不同工具面,而同一 profile 的这两处始终一致。
-
-`profiles..required_tools` 需要支持该字段的 PAOS Core。不支持它的 Core(含 v1.0.0)会把整个
-Bundle 判为 `profiles. has unknown field(s): required_tools` 并拒绝安装,发布这类 Bundle 时
-请在说明里写明最低 Core 版本。
-
-## 5. 打包、发布与本地闭环
-
-### 5.1 构建并验证 Bundle
-
-仓库脚本会重新生成 `archive-manifest.json`,使用固定元数据构建确定性归档,再通过
-`ArchiveValidator` 安全解包复核:
+All paths are relative and contained by the Bundle. Each Node archive has the locked SHA-256.
+An `executable_tar_gz` archive contains exactly one root-level executable with the locked
+filename; a `directory_tar_gz` archive contains exactly one root directory named after the
+entrypoint that holds the same-named executable and its runtime tree (tree-internal relative
+symlinks only). The installer records the
+extracted binary hash in its receipt. The Bundle archive inventory must
+cover every file with SHA-256. Links, path traversal, collisions, oversized expansion, and unlisted
+content are rejected.
+
+When startup must download weights or prepare other external resources, the Bundle may provide a
+root-level `start.sh`. PAOS invokes it as `bash /start.sh `, preserves the
+caller's working directory, and inherits terminal stdio. The script should resolve Bundle files
+relative to its own location, tolerate repeated execution, and return non-zero on failure. Such a
+Bundle requires Bash on the host `PATH`. `PAOS_SKILL_NAME` and `PAOS_SKILL_VERSION` are available as
+dataflow placeholders and in Dora process environments.
+
+Hook environment contract: PAOS also passes `PAOS_SKILL_PROFILE` (the profile being started),
+`PAOS_SKILL_ROOT` (the Bundle root), and `PAOS_HOOK_PYTHON` (the interpreter running PAOS Core).
+`PAOS_HOOK_PYTHON` is only guaranteed to import Core's own dependencies, not any model-runtime
+dependency: create your own virtual environment or call an external tool when the hook must prepare
+CUDA PyTorch, transformers, or similar.
+
+`profiles..required_tools` is optional: when present it overrides the Skill-wide
+`required_tools`, and a profile that omits it inherits that list. The field carries two contracts at
+once - the Tool set the startup and status health checks require, and the Tool allowlist the AgentTask
+may call (`forge/binding.py` freezes the same list into the AgentTask). One Bundle can therefore
+expose a different Tool surface per profile while both checks stay in agreement for a given profile.
+
+`profiles..required_tools` needs a PAOS Core that knows the field. An older Core, including
+v1.0.0, rejects the whole Bundle with
+`profiles. has unknown field(s): required_tools`, so Bundles using it should state their
+minimum Core version.
+
+## 5. Package, publish, and close the local loop
+
+### 5.1 Build and validate a Bundle
+
+The repository script regenerates `archive-manifest.json`, builds a deterministic archive with
+fixed metadata, and safely extracts it through `ArchiveValidator` for final verification:
```bash
python scripts/package_skill.py /path/to/example-skill --output-dir dist/skills
```
-输出文件名取自 `skill.yaml` 的 `name` 与 `version`,并打印归档 SHA-256 和字节数。已有同名
-输出默认不覆盖;仅在确认尚未发布时使用 `--force`。打包脚本拒绝 links,并排除版本控制、缓存
-与 `node_modules` 目录;发布源码目录不得包含凭据、预签名 URL、本机缓存、日志或运行状态。
+The output name comes from `name` and `version` in `skill.yaml`; the script prints the archive
+SHA-256 and byte size. It refuses to replace an existing output unless `--force` is supplied; use
+that option only before publication. The script rejects links and excludes version-control, cache,
+and `node_modules` directories. Do not put credentials, presigned URLs, machine caches, logs, or
+runtime state in the source directory.
-上传前使用与用户相同的公开命令完成本地闭环:
+Before upload, run the same public local loop that users depend on:
```bash
paos skill install dist/skills/example-skill-1.0.0.tar.gz --local
@@ -186,43 +166,50 @@ paos skill status example-skill
paos skill stop example-skill
```
-本地 Bundle 与 Registry Bundle 使用相同的归档、manifest 和 Node lock 校验;缺失 Node 仍需
-通过配置的 Registry 或静态 index 解析。Installer 先 staging、校验,再原子替换,失败则
-rollback。不得要求调用方关闭摘要校验。
+A local Bundle uses the same archive, manifest, and Node-lock validation as a Registry Bundle.
+Missing Nodes still resolve through the configured Registry or static index. Installers stage,
+validate, atomically replace, and roll back on failure. Never require callers to disable digest
+verification.
+
+### 5.2 Immutable publication order
-### 5.2 不可变发布顺序
+This is the dependency/immutability order for administrators and, once enabled, the external approval workflow. It does not provide an external submission endpoint today.
-1. 先发布并登记所有 Node artifacts。`executable_tar_gz` 归档根目录只能包含一个与
- `entrypoint` 同名的 executable;`directory_tar_gz` 归档根目录只能包含一个与
- `entrypoint` 同名的目录(内含同名 executable 与运行时树)。最终归档 SHA-256 必须写入
- Skill lock。
-2. 固定 `skill.yaml` 的 name/version、profiles 与 Node locks,执行打包,并保存输出的 Bundle
- SHA-256 与 `size_bytes`。
-3. 将 Bundle 上传到不可覆盖、长期有效的 HTTPS 对象键。上传后从最终 URL 回读并重新校验
- SHA-256 与大小;修正已发布内容必须递增版本,不能覆盖原对象。
-4. 在 Resource Registry 登记当前 Skill 的 name、URL、SHA-256 与大小,并保证每个 Node
- `artifact_id` 均可通过 Node 端点解析。也可以发布等价的 schema v3 静态 index。
-5. 从干净 PAOS HOME 通过 Registry 重跑安装、启动、状态和停止命令,确认没有依赖源码仓绝对
- 路径或开发机缓存。
+1. Publish and register every Node artifact first. An `executable_tar_gz` archive contains only
+ one root-level executable named by `entrypoint`; a `directory_tar_gz` archive contains only one
+ root directory named by `entrypoint` (holding the same-named executable and its runtime tree).
+ Put the final archive SHA-256 in the Skill lock.
+2. Freeze the `skill.yaml` name/version, profiles, and Node locks, package the Bundle, and retain the
+ printed Bundle SHA-256 and `size_bytes`.
+3. Upload the Bundle to a non-overwritable, long-lived HTTPS object key. Read it back from the final
+ URL and verify size and SHA-256. Corrections require a new version instead of overwriting bytes.
+4. Register the current Skill name, URL, SHA-256, and size in the Resource Registry, and ensure every
+ Node `artifact_id` resolves through its Node endpoint. An equivalent schema-v3 static index is
+ also supported.
+5. From a clean PAOS HOME, repeat Registry install, start, status, and stop. Confirm that no source
+ checkout path or development-machine cache is required.
-公网 Registry 按名称返回当前 Skill 条目,不提供历史版本子路径。`paos skill install
- --version ` 中的版本是客户端约束:Bundle 下载后先校验 manifest version,
-不匹配时在 Node 下载和安装提交前失败。因此旧版本必须通过不可变 URL、静态 index 或本地归档
-另行保存,不能把 `--version` 当作 Registry 历史版本查询。
+The public Registry returns the current Skill entry by name and has no historical-version subpath.
+The version in `paos skill install --version ` is a client constraint: after the
+Bundle download, PAOS verifies its manifest version and rejects a mismatch before Node download or
+installation commit. Preserve old versions through immutable URLs, static indexes, or local
+archives; do not treat `--version` as a Registry history query.
-## 6. 设计 Dora profile
+## 6. Design the Dora profile
-当前分发的 Forge Skill profile 应使用 Dora CLI v0.4.1 与 `dora-message` v0.7.0 开发和验收。
-Skill lock 与主机基线整体升级前,Node 构建必须保持在同一协议代际。
+Develop and validate the currently distributed Forge Skill profiles with Dora CLI v0.4.1 and
+`dora-message` v0.7.0. Keep Node builds on that protocol generation until the Skill locks and host
+baseline are upgraded together.
-Dataflow 为每个 Node 定义明确 inputs/outputs,并使用 Gateway profile 声明的 Tool request/
-response ports。必需 executable 从不可变 Runtime environment 解析;assets 保留在 Skill Bundle
-中并使用可重定位路径。
+The dataflow should give each node explicit inputs/outputs and use the Gateway Tool request/response
+ports declared in its profile. Required executables are resolved from the immutable Runtime
+environment. Assets remain in the Skill Bundle and are referenced with relocatable paths.
-RuntimeManager 创建确定 flow name,校验 Dora 与必需文件,启动 flow,再等待 Gateway
-`/tools` 与全部 required Tool context。Manifest URL 已有 Gateway 监听时不会静默接管。
+RuntimeManager creates a deterministic flow name, verifies Dora and required files, starts the
+flow, then waits for Gateway `/tools` and every required Tool context. A Gateway already listening
+at the manifest URL is not silently adopted.
-Tool API 作为物理执行面时,应在 profile 禁用 Gateway Agent API:
+When Tool API is the physical execution plane, disable the Gateway Agent API in the profile:
```yaml
agent:
@@ -231,67 +218,78 @@ tools:
enabled: true
```
-## 7. 编写工作流说明
-
-`SKILL.md` 应说明何时激活、检查哪些 context、Query → Action/Session 顺序、task binding、
-ownership、终态核对、
-verification checkpoint 与安全恢复规则。不得嵌入 secret、Registry URL、任务特定坐标或绕过
-Gateway/verification 的指令。
-
-验证型工作流应在本轮激活 primary Skill,再由 activation 创建一个 AgentTask,把全部相关
-Query/Action/Session 绑定到同一 task,全部 task-owned 执行终结后 finalize,并只在 recovery
-verdict 允许时追加 PlanRevision。
-
-## 8. Evidence 与 verification
-
-机器人能力接入应暴露 Tool execution facts,而不是编写 action-specific verifier code。PAOS 在
-AgentTask finalize 时采集配置的 image/state source 并应用通用 verification contract。
-Tool output schema 应包含有用的终态 result semantics、final state/error 和相关 tolerance。
-
-未来若引入 authoritative evidence,应显式升级 evidence contract;不能用约定把 best-effort
-WebSocket association 提升为权威。
-
-## 9. Fake Gateway 与 conformance 测试
-
-进入真机或仿真前,使用 mock HTTP transport 测试:
-
-- Tool list/spec/context 与 Query binding resolution;
-- activation candidate 复核以及 ToolSpec/Runtime 漂移拒绝;
-- Action HTTP 202 admission 及 invocation/attempt identity;
-- Session admission、ownership、status/result 与 stop;
-- pending status/result 与已知终态;
-- cancel requested/accepted 不产生虚假停止;
-- timeout/unknown 不盲目重试;
-- endpoint concurrency rejection;
-- 诊断 Query 与绑定调用经过相同 routes;
-- AgentTask 单活动限制、revisions、evidence 与聚合 verification;
-- archive traversal/link/collision/digest 攻击与事务 rollback;
-- 有/无 `start.sh` 的启动、Bash 缺失与钩子非零退出;
-- Skill identity 注入 dataflow/Dora 环境,以及 profile 内容或 dataflow 路径变化后的重新物化;
-- 同一 Skill 的 start/stop/install/remove 跨进程冲突;
-- Runtime start/status/log/stop 与 availability 传播。
-
-随后完成模拟工作流。真实机器人或 MuJoCo 验收必须记录确切 Bundle、node digests、profile 与
-环境。
-
-## 10. 接入验收清单
-
-- [ ] Tool semantics 与 schema 明确、严格;
-- [ ] Frame、unit、tolerance 与 readiness 可检查;
-- [ ] Gateway operation 负责 `max_concurrency`;
-- [ ] Query/Action/Session 使用文档 HTTP 契约;
-- [ ] Skill/Runtime/ToolSpec binding 被冻结,并在每次受治理执行前复核;
-- [ ] Invocation/attempt ID 与 PAOS task ID 分离;
-- [ ] Cancel、stop、timeout、unknown 不推断物理停止,也不触发盲目 POST 重试;
-- [ ] Bundle/Node artifacts 有不可变 size/digest metadata;
-- [ ] Bundle 经仓库打包脚本和本地安装闭环验证,Registry 的 Skill 与全部 Node 端点可解析;
-- [ ] 可选启动钩子的参数、失败状态、重复执行与外部资源摘要经过验证;
-- [ ] Runtime profile 从干净环境启动并使全部 Tool context ready;
-- [ ] Tool-only profile 禁用 Gateway Agent API;
-- [ ] 通用 Agent tools、verification、experience、evolution 不需要能力专用分支。
-
-## 后续阅读
-
-- [开发者手册](../zh/03-developer-manual.md)
-- [通信架构](COMMUNICATION.md)
-- [Forge Tool API 契约](../forge/README_zh.md)
+## 7. Write workflow guidance
+
+`SKILL.md` should tell the Agent when to activate the Skill, which contexts to inspect, the Query →
+Action/Session ordering, task binding, ownership, terminal reconciliation, verification checkpoints, and safe recovery
+rules. It must not embed secrets, Registry URLs, task-specific coordinates, or instructions to
+bypass Gateway/verification.
+
+For a verified workflow, activate the primary Skill in the current turn, create one AgentTask from
+that activation, bind every contributing Query/Action/Session to the same task, finalize after all
+task-owned executions terminate, and append a PlanRevision only when recovery verdict
+allows it.
+
+## 8. Evidence and verification
+
+Robot capability integration should expose Tool execution facts, not action-specific verifier code.
+PAOS captures configured image/state sources and applies the generic verification contract at
+AgentTask finalize. Tool output schemas should contain useful terminal result semantics, final
+state/error data, and tolerances where relevant.
+
+If authoritative evidence is introduced later, version the evidence contract explicitly. Do not
+upgrade best-effort WebSocket association by convention.
+
+## 9. Fake Gateway and conformance tests
+
+Before real hardware or simulation, use a mock HTTP transport to test:
+
+- Tool list/spec/context and Query binding resolution;
+- activation candidate revalidation and ToolSpec/runtime drift rejection;
+- Action HTTP 202 admission with invocation and attempt identities;
+- Session admission, ownership, status/result, and stop;
+- pending status/result and known terminal results;
+- cancellation requested/accepted without false stop;
+- timeout and unknown without blind retry;
+- endpoint concurrency rejection behavior;
+- diagnostic Query and bound calls through identical routes;
+- AgentTask one-active constraint, revisions, evidence, and aggregate verification;
+- archive traversal/link/collision/digest attacks and transactional rollback;
+- startup with and without `start.sh`, missing Bash, and non-zero hook exit;
+- Skill identity injection into dataflow/Dora environments and rematerialization after profile
+ content or dataflow-path changes;
+- cross-process start/stop/install/remove conflicts for one Skill;
+- Runtime start/status/log/stop and availability propagation.
+
+Then run a complete simulated workflow. Real robot or MuJoCo acceptance must identify the exact
+Bundle, node digests, profile, and environment used.
+
+## 10. Integration acceptance checklist
+
+- [ ] Tool semantics and schemas are explicit and strict.
+- [ ] Frame, unit, tolerance, and readiness conventions are inspectable.
+- [ ] Gateway operation owns `max_concurrency`.
+- [ ] Query, Action, and Session use the documented HTTP contracts.
+- [ ] Skill/Runtime/ToolSpec binding is frozen and revalidated for every governed execution.
+- [ ] Invocation and attempt IDs remain separate from PAOS task IDs.
+- [ ] Cancel, stop, timeout, and unknown do not imply physical stop or trigger a blind POST retry.
+- [ ] Bundle and Node artifacts have immutable size/digest metadata.
+- [ ] The Bundle passes repository packaging and the local install loop, and Registry Skill and Node
+ endpoints all resolve.
+- [ ] Optional startup-hook arguments, failure state, repeated execution, and external-resource
+ digests are verified.
+- [ ] Runtime profile starts from a clean environment and reaches all Tool contexts.
+- [ ] Gateway Agent API is disabled for the Tool-only profile.
+- [ ] General Agent tools, verification, experience, and evolution require no capability-specific fork.
+
+## Next reading
+
+- [Core Developer Manual](../en/03-developer-manual.md)
+- [Core Communication Architecture](COMMUNICATION.md)
+- [Forge Tool API Contract](../forge/README.md)
+
+## TrackB framework and Skill development
+
+- [TrackB overview](track_b/README.md): execution architecture and repository ownership.
+- [Skill development manual](track_b/SKILL_DEVELOPMENT.md): three extension modes and delivery procedures.
+- [Piper X MuJoCo example](PIPER_X_DEMO.md): worked model/profile integration and both control modes.
diff --git a/docs/user_development_guide/README_en.md b/docs/user_development_guide/README_en.md
deleted file mode 100644
index 4038d1779..000000000
--- a/docs/user_development_guide/README_en.md
+++ /dev/null
@@ -1,317 +0,0 @@
-# PhyAgentOS Integration Development Guide
-
-[中文](README.md) · [Documentation index](../README.md)
-
-> Version: 1.0.0
-
-## 1. Choose the integration point
-
-| Capability | Integration point |
-|:-----------|:------------------|
-| Robot read or calculation | Gateway Query ToolSpec + ToolEndpoint operation |
-| Robot effect | Gateway Action ToolSpec + ToolEndpoint operation |
-| Stateful capability lifecycle | Gateway Session ToolSpec + ToolEndpoint operation |
-| Dora nodes and deployment assets | Manifest-v2 Skill Bundle and locked Node artifacts |
-| Workflow instructions | `SKILL.md` discovered by SkillsLoader |
-| User-task success | Generic `TaskVerificationContract` and AgentTask finalize |
-| New model provider | Existing provider registry/configuration |
-| Non-robot Agent capability | Existing Agent ToolRegistry or dynamic MCP |
-
-Do not connect Agent code directly to robot SDKs, Dora nodes, simulators, or legacy Gateway
-Session/Policy routes outside the governed Tool API.
-
-## 2. Define a ToolSpec
-
-Every ToolSpec has a stable `tool_id`, implementation and endpoint binding, operation,
-`semantics: query|action|session`, description, strict input/output JSON schemas, readiness requirements,
-and a robot frame profile when spatial inputs are involved.
-
-```yaml
-tool_id: motion.resolve_relative_pose
-implementation_id: motion.integration
-endpoint_id: motion.relative_pose
-operation: resolve
-semantics: query
-description: Resolve a relative end-effector delta into an absolute target pose.
-input_schema:
- type: object
- additionalProperties: false
- required: [translation_frame, translation_m]
- properties:
- translation_frame: {enum: [tcp, base]}
- translation_m:
- type: object
- additionalProperties: false
- required: [x, y, z]
- properties:
- x: {type: number}
- y: {type: number}
- z: {type: number}
-output_schema:
- type: object
-robot_frame_profile:
- base_frame: arm_base
- tool_frame: tcp
-```
-
-Use Query for synchronous reads or deterministic resolution without a robot effect. Use Action for
-bounded physical effects and Session for explicitly owned, stateful lifecycles. Define Endpoint operation `max_concurrency` at
-the execution owner; PAOS does not create a cross-Tool lease.
-
-## 3. Implement Query, Action, and Session behavior
-
-Query calls are resolved from ToolSpec and invoked at:
-
-```text
-POST /tools/{endpoint_id}/{operation}:invoke → HTTP 200
-```
-
-Action admission uses:
-
-```text
-POST /tools/{tool_id}:invoke → HTTP 202 + invocation_id + attempt_id
-GET /invocations/{invocation_id}
-GET /invocations/{invocation_id}/result
-POST /invocations/{invocation_id}/cancel
-```
-
-Session admission uses the same `POST /tools/{tool_id}:invoke` contract. Reconcile it through the
-common invocation routes and stop it with `POST /invocations/{invocation_id}/stop`. Declare whether
-the Session is task-owned, shared, or runtime-owned; do not let one owner stop another owner's
-Session.
-
-Action status/result must expose an explicit lifecycle. Result may remain pending with HTTP 202.
-Cancellation acceptance reports control handling only. When execution truth cannot be recovered,
-return an explicit unknown outcome rather than fabricating cancellation or success.
-
-Inputs and outputs must be finite JSON and satisfy ToolSpec. Spatial Tools must state frames,
-units, tolerances, and orientation behavior. Avoid hidden defaults that the Agent cannot inspect
-through `forge_tool_context`.
-
-## 4. Build a manifest-v2 Skill Bundle
-
-An installed Skill Bundle contains:
-
-```text
-/
-├── skill.yaml
-├── SKILL.md
-├── start.sh # optional external-resource preparation before Dora
-├── archive-manifest.json # generated by the packaging script
-├── profiles//dataflow.yaml
-├── profiles//...
-└── assets/...
-```
-
-Minimal manifest structure:
-
-```yaml
-manifest_version: 2
-name: example-skill
-version: "1.0.0"
-description: Example robot workflow.
-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
- # optional: overrides the Skill-wide required_tools; omit to inherit
- required_tools: [example.query]
- 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>
-```
-
-All paths are relative and contained by the Bundle. Each Node archive has the locked SHA-256.
-An `executable_tar_gz` archive contains exactly one root-level executable with the locked
-filename; a `directory_tar_gz` archive contains exactly one root directory named after the
-entrypoint that holds the same-named executable and its runtime tree (tree-internal relative
-symlinks only). The installer records the
-extracted binary hash in its receipt. The Bundle archive inventory must
-cover every file with SHA-256. Links, path traversal, collisions, oversized expansion, and unlisted
-content are rejected.
-
-When startup must download weights or prepare other external resources, the Bundle may provide a
-root-level `start.sh`. PAOS invokes it as `bash /start.sh `, preserves the
-caller's working directory, and inherits terminal stdio. The script should resolve Bundle files
-relative to its own location, tolerate repeated execution, and return non-zero on failure. Such a
-Bundle requires Bash on the host `PATH`. `PAOS_SKILL_NAME` and `PAOS_SKILL_VERSION` are available as
-dataflow placeholders and in Dora process environments.
-
-Hook environment contract: PAOS also passes `PAOS_SKILL_PROFILE` (the profile being started),
-`PAOS_SKILL_ROOT` (the Bundle root), and `PAOS_HOOK_PYTHON` (the interpreter running PAOS Core).
-`PAOS_HOOK_PYTHON` is only guaranteed to import Core's own dependencies, not any model-runtime
-dependency: create your own virtual environment or call an external tool when the hook must prepare
-CUDA PyTorch, transformers, or similar.
-
-`profiles..required_tools` is optional: when present it overrides the Skill-wide
-`required_tools`, and a profile that omits it inherits that list. The field carries two contracts at
-once - the Tool set the startup and status health checks require, and the Tool allowlist the AgentTask
-may call (`forge/binding.py` freezes the same list into the AgentTask). One Bundle can therefore
-expose a different Tool surface per profile while both checks stay in agreement for a given profile.
-
-`profiles..required_tools` needs a PAOS Core that knows the field. An older Core, including
-v1.0.0, rejects the whole Bundle with
-`profiles. has unknown field(s): required_tools`, so Bundles using it should state their
-minimum Core version.
-
-## 5. Package, publish, and close the local loop
-
-### 5.1 Build and validate a Bundle
-
-The repository script regenerates `archive-manifest.json`, builds a deterministic archive with
-fixed metadata, and safely extracts it through `ArchiveValidator` for final verification:
-
-```bash
-python scripts/package_skill.py /path/to/example-skill --output-dir dist/skills
-```
-
-The output name comes from `name` and `version` in `skill.yaml`; the script prints the archive
-SHA-256 and byte size. It refuses to replace an existing output unless `--force` is supplied; use
-that option only before publication. The script rejects links and excludes version-control, cache,
-and `node_modules` directories. Do not put credentials, presigned URLs, machine caches, logs, or
-runtime state in the source directory.
-
-Before upload, run the same public local loop that users depend on:
-
-```bash
-paos skill install dist/skills/example-skill-1.0.0.tar.gz --local
-paos forge-node verify example-skill gateway
-paos skill inspect example-skill
-paos skill start example-skill --profile sim
-paos skill status example-skill
-paos skill stop example-skill
-```
-
-A local Bundle uses the same archive, manifest, and Node-lock validation as a Registry Bundle.
-Missing Nodes still resolve through the configured Registry or static index. Installers stage,
-validate, atomically replace, and roll back on failure. Never require callers to disable digest
-verification.
-
-### 5.2 Immutable publication order
-
-1. Publish and register every Node artifact first. An `executable_tar_gz` archive contains only
- one root-level executable named by `entrypoint`; a `directory_tar_gz` archive contains only one
- root directory named by `entrypoint` (holding the same-named executable and its runtime tree).
- Put the final archive SHA-256 in the Skill lock.
-2. Freeze the `skill.yaml` name/version, profiles, and Node locks, package the Bundle, and retain the
- printed Bundle SHA-256 and `size_bytes`.
-3. Upload the Bundle to a non-overwritable, long-lived HTTPS object key. Read it back from the final
- URL and verify size and SHA-256. Corrections require a new version instead of overwriting bytes.
-4. Register the current Skill name, URL, SHA-256, and size in the Resource Registry, and ensure every
- Node `artifact_id` resolves through its Node endpoint. An equivalent schema-v3 static index is
- also supported.
-5. From a clean PAOS HOME, repeat Registry install, start, status, and stop. Confirm that no source
- checkout path or development-machine cache is required.
-
-The public Registry returns the current Skill entry by name and has no historical-version subpath.
-The version in `paos skill install --version ` is a client constraint: after the
-Bundle download, PAOS verifies its manifest version and rejects a mismatch before Node download or
-installation commit. Preserve old versions through immutable URLs, static indexes, or local
-archives; do not treat `--version` as a Registry history query.
-
-## 6. Design the Dora profile
-
-Develop and validate the currently distributed Forge Skill profiles with Dora CLI v0.4.1 and
-`dora-message` v0.7.0. Keep Node builds on that protocol generation until the Skill locks and host
-baseline are upgraded together.
-
-The dataflow should give each node explicit inputs/outputs and use the Gateway Tool request/response
-ports declared in its profile. Required executables are resolved from the immutable Runtime
-environment. Assets remain in the Skill Bundle and are referenced with relocatable paths.
-
-RuntimeManager creates a deterministic flow name, verifies Dora and required files, starts the
-flow, then waits for Gateway `/tools` and every required Tool context. A Gateway already listening
-at the manifest URL is not silently adopted.
-
-When Tool API is the physical execution plane, disable the Gateway Agent API in the profile:
-
-```yaml
-agent:
- enabled: false
-tools:
- enabled: true
-```
-
-## 7. Write workflow guidance
-
-`SKILL.md` should tell the Agent when to activate the Skill, which contexts to inspect, the Query →
-Action/Session ordering, task binding, ownership, terminal reconciliation, verification checkpoints, and safe recovery
-rules. It must not embed secrets, Registry URLs, task-specific coordinates, or instructions to
-bypass Gateway/verification.
-
-For a verified workflow, activate the primary Skill in the current turn, create one AgentTask from
-that activation, bind every contributing Query/Action/Session to the same task, finalize after all
-task-owned executions terminate, and append a PlanRevision only when recovery verdict
-allows it.
-
-## 8. Evidence and verification
-
-Robot capability integration should expose Tool execution facts, not action-specific verifier code.
-PAOS captures configured image/state sources and applies the generic verification contract at
-AgentTask finalize. Tool output schemas should contain useful terminal result semantics, final
-state/error data, and tolerances where relevant.
-
-If authoritative evidence is introduced later, version the evidence contract explicitly. Do not
-upgrade best-effort WebSocket association by convention.
-
-## 9. Fake Gateway and conformance tests
-
-Before real hardware or simulation, use a mock HTTP transport to test:
-
-- Tool list/spec/context and Query binding resolution;
-- activation candidate revalidation and ToolSpec/runtime drift rejection;
-- Action HTTP 202 admission with invocation and attempt identities;
-- Session admission, ownership, status/result, and stop;
-- pending status/result and known terminal results;
-- cancellation requested/accepted without false stop;
-- timeout and unknown without blind retry;
-- endpoint concurrency rejection behavior;
-- diagnostic Query and bound calls through identical routes;
-- AgentTask one-active constraint, revisions, evidence, and aggregate verification;
-- archive traversal/link/collision/digest attacks and transactional rollback;
-- startup with and without `start.sh`, missing Bash, and non-zero hook exit;
-- Skill identity injection into dataflow/Dora environments and rematerialization after profile
- content or dataflow-path changes;
-- cross-process start/stop/install/remove conflicts for one Skill;
-- Runtime start/status/log/stop and availability propagation.
-
-Then run a complete simulated workflow. Real robot or MuJoCo acceptance must identify the exact
-Bundle, node digests, profile, and environment used.
-
-## 10. Integration acceptance checklist
-
-- [ ] Tool semantics and schemas are explicit and strict.
-- [ ] Frame, unit, tolerance, and readiness conventions are inspectable.
-- [ ] Gateway operation owns `max_concurrency`.
-- [ ] Query, Action, and Session use the documented HTTP contracts.
-- [ ] Skill/Runtime/ToolSpec binding is frozen and revalidated for every governed execution.
-- [ ] Invocation and attempt IDs remain separate from PAOS task IDs.
-- [ ] Cancel, stop, timeout, and unknown do not imply physical stop or trigger a blind POST retry.
-- [ ] Bundle and Node artifacts have immutable size/digest metadata.
-- [ ] The Bundle passes repository packaging and the local install loop, and Registry Skill and Node
- endpoints all resolve.
-- [ ] Optional startup-hook arguments, failure state, repeated execution, and external-resource
- digests are verified.
-- [ ] Runtime profile starts from a clean environment and reaches all Tool contexts.
-- [ ] Gateway Agent API is disabled for the Tool-only profile.
-- [ ] General Agent tools, verification, experience, and evolution require no capability-specific fork.
-
-## Next reading
-
-- [Developer Manual](../en/03-developer-manual.md)
-- [Communication Architecture](COMMUNICATION_en.md)
-- [Forge Tool API Contract](../forge/README.md)
diff --git a/docs/user_development_guide/README_zh.md b/docs/user_development_guide/README_zh.md
new file mode 100644
index 000000000..a31380f16
--- /dev/null
+++ b/docs/user_development_guide/README_zh.md
@@ -0,0 +1,282 @@
+# Bundle 与 Tool 接入参考
+
+[English](README.md) | [简体中文](README_zh.md)
+
+> 版本:1.1.1
+
+选择开发模式及实施流程请使用 [TrackB Skill 开发手册](track_b/SKILL_DEVELOPMENT_zh.md)。本文集中维护 ToolSpec 示例、manifest v2 字段、启动 hook、打包与接口一致性检查细节。公开 HTTP 和生命周期语义以 [Forge Tool API 契约](../forge/README_zh.md)为准。
+
+**平台开放范围:** 外部贡献提交及已有登记仓库修改暂未开放,需等待审批服务完成并开放。当前登记与发布由管理员维护;可先进行本地开发验证。下文的平台发布步骤以相关流程开放为前提,详见[贡献指南](../../CONTRIBUTING_zh.md)。
+
+如果目标是在现有执行链中增加一种仿真机械臂,先从
+[Piper X 开发示例](PIPER_X_DEMO_zh.md)入手;需要修改设备驱动或节点算法时,先查
+[TrackB 架构、协议与源码入口](track_b/README_zh.md)。两条路径分别对应 Skill 配置/模型扩展与 Node 源码开发。
+
+## 1. 选择接入点
+
+机器人模型、profile、Node 与 Skill 开发从 [TrackB](track_b/README_zh.md)开始;AgentTask、binding、验证或 installer 实现参见 [Core 开发者手册](../zh/03-developer-manual.md)。Agent bus、WebSocket 与持久化边界见[通信参考](COMMUNICATION_zh.md)。
+
+集成使用受治理的 Tool API,不在该路径之外让 Agent 直连机器人 SDK、Dora Node 或模拟器。
+
+## 2. 定义 ToolSpec
+
+每个 ToolSpec 包含稳定 `tool_id`、implementation/endpoint binding、operation、
+`semantics: query|action|session`、description、严格 input/output JSON schema、readiness,以及空间
+输入所需 robot frame profile。
+
+```yaml
+tool_id: motion.resolve_relative_pose
+implementation_id: motion.integration
+endpoint_id: motion.relative_pose
+operation: resolve
+semantics: query
+description: Resolve a relative end-effector delta into an absolute target pose.
+input_schema:
+ type: object
+ additionalProperties: false
+ required: [translation_frame, translation_m]
+ properties:
+ translation_frame: {enum: [tcp, base]}
+ translation_m:
+ type: object
+ additionalProperties: false
+ required: [x, y, z]
+ properties:
+ x: {type: number}
+ y: {type: number}
+ z: {type: number}
+output_schema:
+ type: object
+robot_frame_profile:
+ base_frame: arm_base
+ tool_frame: tcp
+```
+
+同步读取或不产生机器人效果的确定性解析使用 Query;有界物理效果使用 Action;显式有所有权
+的有状态生命周期使用 Session。在执行方
+定义 Endpoint operation `max_concurrency`,PAOS 不创建跨 Tool lease。
+
+## 3. 实现 Query、Action 与 Session 行为
+
+HTTP admission、核对、ownership 和终态行为以 [Query](../forge/README_zh.md#3-query-契约)、[Action](../forge/README_zh.md#4-action-契约)和 [Session](../forge/README_zh.md#5-session-契约)契约为准。[节点协议说明](track_b/PROTOCOLS_zh.md)描述 provider 和 Dora 端口。
+
+输入输出必须是有限 JSON 并满足 ToolSpec。空间 Tool 应通过可检查的 context 暴露 frame、单位、容差和姿态行为。无法恢复执行事实时返回明确 unknown;admission 和取消接受不证明完成或物理停止。
+
+## 4. 构建 manifest v2 Skill Bundle
+
+已安装 Skill Bundle 包含:
+
+```text
+/
+├── skill.yaml
+├── SKILL.md
+├── start.sh # 可选,Dora 启动前准备外部资源
+├── archive-manifest.json # 打包脚本生成
+├── profiles//dataflow.yaml
+├── profiles//...
+└── assets/...
+```
+
+最小 manifest 结构:
+
+```yaml
+manifest_version: 2
+name: example-skill
+version: "1.0.0"
+description: Example robot workflow.
+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
+ # 可选:覆盖 Skill 级 required_tools;省略则继承
+ required_tools: [example.query]
+ 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>
+```
+
+所有路径必须相对并包含在 Bundle 内。每个 Node archive 具有 lock 指定的 SHA-256。
+`executable_tar_gz` 只包含一个 lock 指定文件名的根目录 executable;`directory_tar_gz`
+只包含一个以 `entrypoint` 命名的根目录,同名 executable 及其运行时树置于其中(仅允许
+解析不出树的相对符号链接)。installer 在 receipt 中另行记录解包后 binary hash。
+Bundle archive inventory 需要覆盖每个文件及 SHA-256;links、路径穿越、冲突、过度展开和未列出
+内容会被拒绝。
+
+Bundle 如需在启动前下载权重或准备其他外部资源,可在根目录提供 `start.sh`。PAOS 使用
+`bash /start.sh ` 调用它,不改变工作目录并继承终端 stdio;脚本应从
+自身路径解析 Bundle 内文件,支持重复执行,并在失败时返回非零退出码。此类 Bundle 要求主机
+`PATH` 中存在 Bash。`PAOS_SKILL_NAME` 与 `PAOS_SKILL_VERSION` 可用于 dataflow 占位符,
+也会进入 Dora 进程环境。
+
+Hook 的环境契约:除 `PAOS_SKILL_NAME` / `PAOS_SKILL_VERSION` 外,PAOS 还会传入
+`PAOS_SKILL_PROFILE`(本次启动的 profile 名)、`PAOS_SKILL_ROOT`(Bundle 根目录)和
+`PAOS_HOOK_PYTHON`(运行 PAOS Core 的解释器)。`PAOS_HOOK_PYTHON` 只保证能执行 Core 自身的依赖,
+**不保证**包含任何模型运行时依赖:要在 Hook 里准备 CUDA 版 PyTorch / transformers 之类,请自行创建
+虚拟环境或调用外部工具,不要假定它可用。
+
+`profiles..required_tools` 是可选字段:写了覆盖 Skill 级 `required_tools`,不写则继承。
+这一个字段同时承担两个契约——启动与状态健康检查要求就绪的 Tool 集合,以及 AgentTask 允许该 Skill
+调用的 Tool allowlist(`forge/binding.py` 冻结进 AgentTask 的 `required_tools` 就是同一份列表)。
+因此一个 Bundle 可以按 profile 暴露不同工具面,而同一 profile 的这两处始终一致。
+
+`profiles..required_tools` 需要支持该字段的 PAOS Core。不支持它的 Core(含 v1.0.0)会把整个
+Bundle 判为 `profiles. has unknown field(s): required_tools` 并拒绝安装,发布这类 Bundle 时
+请在说明里写明最低 Core 版本。
+
+## 5. 打包、发布与本地闭环
+
+### 5.1 构建并验证 Bundle
+
+仓库脚本会重新生成 `archive-manifest.json`,使用固定元数据构建确定性归档,再通过
+`ArchiveValidator` 安全解包复核:
+
+```bash
+python scripts/package_skill.py /path/to/example-skill --output-dir dist/skills
+```
+
+输出文件名取自 `skill.yaml` 的 `name` 与 `version`,并打印归档 SHA-256 和字节数。已有同名
+输出默认不覆盖;仅在确认尚未发布时使用 `--force`。打包脚本拒绝 links,并排除版本控制、缓存
+与 `node_modules` 目录;发布源码目录不得包含凭据、预签名 URL、本机缓存、日志或运行状态。
+
+上传前使用与用户相同的公开命令完成本地闭环:
+
+```bash
+paos skill install dist/skills/example-skill-1.0.0.tar.gz --local
+paos forge-node verify example-skill gateway
+paos skill inspect example-skill
+paos skill start example-skill --profile sim
+paos skill status example-skill
+paos skill stop example-skill
+```
+
+本地 Bundle 与 Registry Bundle 使用相同的归档、manifest 和 Node lock 校验;缺失 Node 仍需
+通过配置的 Registry 或静态 index 解析。Installer 先 staging、校验,再原子替换,失败则
+rollback。不得要求调用方关闭摘要校验。
+
+### 5.2 不可变发布顺序
+
+这里说明管理员及未来外部审批流程的依赖与不可变发布顺序,不代表当前已有外部提交入口。
+
+1. 先发布并登记所有 Node artifacts。`executable_tar_gz` 归档根目录只能包含一个与
+ `entrypoint` 同名的 executable;`directory_tar_gz` 归档根目录只能包含一个与
+ `entrypoint` 同名的目录(内含同名 executable 与运行时树)。最终归档 SHA-256 必须写入
+ Skill lock。
+2. 固定 `skill.yaml` 的 name/version、profiles 与 Node locks,执行打包,并保存输出的 Bundle
+ SHA-256 与 `size_bytes`。
+3. 将 Bundle 上传到不可覆盖、长期有效的 HTTPS 对象键。上传后从最终 URL 回读并重新校验
+ SHA-256 与大小;修正已发布内容必须递增版本,不能覆盖原对象。
+4. 在 Resource Registry 登记当前 Skill 的 name、URL、SHA-256 与大小,并保证每个 Node
+ `artifact_id` 均可通过 Node 端点解析。也可以发布等价的 schema v3 静态 index。
+5. 从干净 PAOS HOME 通过 Registry 重跑安装、启动、状态和停止命令,确认没有依赖源码仓绝对
+ 路径或开发机缓存。
+
+公网 Registry 按名称返回当前 Skill 条目,不提供历史版本子路径。`paos skill install
+ --version ` 中的版本是客户端约束:Bundle 下载后先校验 manifest version,
+不匹配时在 Node 下载和安装提交前失败。因此旧版本必须通过不可变 URL、静态 index 或本地归档
+另行保存,不能把 `--version` 当作 Registry 历史版本查询。
+
+## 6. 设计 Dora profile
+
+当前分发的 Forge Skill profile 应使用 Dora CLI v0.4.1 与 `dora-message` v0.7.0 开发和验收。
+Skill lock 与主机基线整体升级前,Node 构建必须保持在同一协议代际。
+
+Dataflow 为每个 Node 定义明确 inputs/outputs,并使用 Gateway profile 声明的 Tool request/
+response ports。必需 executable 从不可变 Runtime environment 解析;assets 保留在 Skill Bundle
+中并使用可重定位路径。
+
+RuntimeManager 创建确定 flow name,校验 Dora 与必需文件,启动 flow,再等待 Gateway
+`/tools` 与全部 required Tool context。Manifest URL 已有 Gateway 监听时不会静默接管。
+
+Tool API 作为物理执行面时,应在 profile 禁用 Gateway Agent API:
+
+```yaml
+agent:
+ enabled: false
+tools:
+ enabled: true
+```
+
+## 7. 编写工作流说明
+
+`SKILL.md` 应说明何时激活、检查哪些 context、Query → Action/Session 顺序、task binding、
+ownership、终态核对、
+verification checkpoint 与安全恢复规则。不得嵌入 secret、Registry URL、任务特定坐标或绕过
+Gateway/verification 的指令。
+
+验证型工作流应在本轮激活 primary Skill,再由 activation 创建一个 AgentTask,把全部相关
+Query/Action/Session 绑定到同一 task,全部 task-owned 执行终结后 finalize,并只在 recovery
+verdict 允许时追加 PlanRevision。
+
+## 8. Evidence 与 verification
+
+机器人能力接入应暴露 Tool execution facts,而不是编写 action-specific verifier code。PAOS 在
+AgentTask finalize 时采集配置的 image/state source 并应用通用 verification contract。
+Tool output schema 应包含有用的终态 result semantics、final state/error 和相关 tolerance。
+
+未来若引入 authoritative evidence,应显式升级 evidence contract;不能用约定把 best-effort
+WebSocket association 提升为权威。
+
+## 9. Fake Gateway 与 conformance 测试
+
+进入真机或仿真前,使用 mock HTTP transport 测试:
+
+- Tool list/spec/context 与 Query binding resolution;
+- activation candidate 复核以及 ToolSpec/Runtime 漂移拒绝;
+- Action HTTP 202 admission 及 invocation/attempt identity;
+- Session admission、ownership、status/result 与 stop;
+- pending status/result 与已知终态;
+- cancel requested/accepted 不产生虚假停止;
+- timeout/unknown 不盲目重试;
+- endpoint concurrency rejection;
+- 诊断 Query 与绑定调用经过相同 routes;
+- AgentTask 单活动限制、revisions、evidence 与聚合 verification;
+- archive traversal/link/collision/digest 攻击与事务 rollback;
+- 有/无 `start.sh` 的启动、Bash 缺失与钩子非零退出;
+- Skill identity 注入 dataflow/Dora 环境,以及 profile 内容或 dataflow 路径变化后的重新物化;
+- 同一 Skill 的 start/stop/install/remove 跨进程冲突;
+- Runtime start/status/log/stop 与 availability 传播。
+
+随后完成模拟工作流。真实机器人或 MuJoCo 验收必须记录确切 Bundle、node digests、profile 与
+环境。
+
+## 10. 接入验收清单
+
+- [ ] Tool semantics 与 schema 明确、严格;
+- [ ] Frame、unit、tolerance 与 readiness 可检查;
+- [ ] Gateway operation 负责 `max_concurrency`;
+- [ ] Query/Action/Session 使用文档 HTTP 契约;
+- [ ] Skill/Runtime/ToolSpec binding 被冻结,并在每次受治理执行前复核;
+- [ ] Invocation/attempt ID 与 PAOS task ID 分离;
+- [ ] Cancel、stop、timeout、unknown 不推断物理停止,也不触发盲目 POST 重试;
+- [ ] Bundle/Node artifacts 有不可变 size/digest metadata;
+- [ ] Bundle 经仓库打包脚本和本地安装闭环验证,Registry 的 Skill 与全部 Node 端点可解析;
+- [ ] 可选启动钩子的参数、失败状态、重复执行与外部资源摘要经过验证;
+- [ ] Runtime profile 从干净环境启动并使全部 Tool context ready;
+- [ ] Tool-only profile 禁用 Gateway Agent API;
+- [ ] 通用 Agent tools、verification、experience、evolution 不需要能力专用分支。
+
+## 后续阅读
+
+- [Core 开发者手册](../zh/03-developer-manual.md)
+- [Core 通信架构](COMMUNICATION_zh.md)
+- [Forge Tool API 契约](../forge/README_zh.md)
+
+## TrackB 框架与 Skill 开发
+
+- [TrackB 总览](track_b/README_zh.md):执行架构与仓库职责。
+- [Skill 开发手册](track_b/SKILL_DEVELOPMENT_zh.md):三种扩展模式与交付流程。
+- [Piper X MuJoCo 示例](PIPER_X_DEMO_zh.md):模型/profile 接入和两种控制方式的完整实战。
diff --git a/docs/user_development_guide/track_b/PROTOCOLS.md b/docs/user_development_guide/track_b/PROTOCOLS.md
new file mode 100644
index 000000000..c48245e13
--- /dev/null
+++ b/docs/user_development_guide/track_b/PROTOCOLS.md
@@ -0,0 +1,151 @@
+# TrackB Protocols and Important Node Types
+
+[English](PROTOCOLS.md) | [简体中文](PROTOCOLS_zh.md)
+
+[Overview](README.md) · [Repositories](REPOSITORIES.md) · [Protocols](PROTOCOLS.md) · [Runtime](RUNTIME.md) · [Skill development](SKILL_DEVELOPMENT.md)
+
+This page summarizes interface entrypoints and constraints; pinned source schemas/interfaces define the authoritative fields.
+See the [overview](README.md) and [catalog](REPOSITORIES.md) for categories/code organization,
+and [Runtime relationships](RUNTIME.md) for deployment mappings. These contracts describe the Forge source snapshot;
+older Skill binaries require their own compatible versions and must not be mixed indiscriminately.
+
+## 1. Data plane: Forge Msgs
+
+Standard messages use single-row Apache Arrow `RecordBatch` values. Put semantics in actual columns,
+not Arrow schema metadata that Dora/IPC may discard. There is no universal ROS Header: timing comes
+from Dora event context, while frames/fixed calibration come from configuration or Dora metadata.
+Publish-time HLC is not sensor acquisition time; preserve explicitly supplied source sampling timestamps.
+Action `goal_id` / `goal_status` are explicit event-metadata exceptions and must be recorded alongside payloads.
+
+Definitions: [schema guide](https://github.com/PhyAgentOS/forge/blob/e59693910bb5f9572cf39c5a59475c0747ba76e8/interfaces/forge_msgs/SCHEMA.md), [units and timing](https://github.com/PhyAgentOS/forge/blob/e59693910bb5f9572cf39c5a59475c0747ba76e8/interfaces/forge_msgs/common.v1.yaml).
+
+## 2. Robot Adapter
+
+Python drivers implement four `RobotDriver` methods:
+
+```python
+connect() -> None
+disconnect() -> None
+get_state() -> JointState
+set_command(command: JointCommand) -> None
+```
+
+Optional `LocomotionRobotDriver.set_locomotion_command(command)` adds base control.
+`BaseRobotDriver.joint_order` may declare fixed joint order. Drivers own connection, enabling,
+limits and device resource cleanup.
+
+| Standard runner port | Message/behavior |
+| --- | --- |
+| Input `tick` | Read state and publish `state` |
+| Input `action` / `action/` | Sparse `JointCommand`; update named joints only, retaining other targets |
+| Input `master_state` | Map leader `JointState` to a position command |
+| Input `locomotion_command` | Accept `LocomotionCommand` if supported |
+| Output `state` | `JointState`; a Node using other port names is governed by its dataflow |
+
+`JointState.name` is nonempty and unique; `position/velocity/effort` are each empty or match its length.
+`JointCommand` adds `mode` and `kp/kd`, with `position/velocity/effort/hybrid` modes; missing/null mode
+in older payloads means position. Representability does not guarantee driver support.
+Revolute joints use rad, rad/s, Nm; prismatic joints use m, m/s, N.
+Disjoint sources can update separate joints; overlapping writers still need explicit arbitration.
+
+`LocomotionCommand` is body-frame: `vx` forward, `vy` left (m/s), `wz` counterclockwise (rad/s).
+Zero velocity expresses stop; each driver must define watchdogs, limits and unsupported lateral-motion behavior.
+
+Source: [driver interface](https://github.com/PhyAgentOS/forge/blob/e59693910bb5f9572cf39c5a59475c0747ba76e8/packages/robot/src/forge_robot/robot_protocol.py), [runner](https://github.com/PhyAgentOS/forge/blob/e59693910bb5f9572cf39c5a59475c0747ba76e8/packages/robot/README.md), [control schema](https://github.com/PhyAgentOS/forge/blob/e59693910bb5f9572cf39c5a59475c0747ba76e8/interfaces/forge_msgs/control.v1.yaml).
+
+## 3. Sensor / Camera Adapter
+
+The inspected source has no unified `SensorDriver` base corresponding to `RobotDriver`.
+Shared boundaries are message schemas; camera repositories implement connection, enumeration,
+sampling, reconnection and ports individually. Do not present a proposed template as an existing API.
+
+| Message | Fields and constraints |
+| --- | --- |
+| `Image` | `height/width/encoding/step/data`; byte stride `step` may include padding; `len(data)=step*height`; multibyte pixels are little-endian |
+| `CompressedImage` | `format/data`; JPEG/PNG/WebP must not masquerade as raw Image |
+| `PointCloud` | `width/height/is_dense`, `x/y/z: list` in metres; empty lists represent absent optional attributes; organized clouds retain row/column correspondence |
+| `PointCloudBuffer` | Decoded point records preserving dynamic fields, point/row strides and byte order; not raw device packets |
+| `Imu` | Angular velocity rad/s, acceleration m/s²; null unavailable orientation; covariance empty or 9 elements; never silently normalize quaternions |
+| `AudioChunk` | `sample_rate/channels/sample_format/frame_count/data`; interleaved f32le/s16le frames |
+
+Orbbec and RealSense currently output depth as `Image(32FC1)`, float32 metres with zero invalid.
+This is their Adapter convention, not a universal scale inferred from Image encoding.
+Producers must document optical frames, alignment, calibration and sampling time.
+IMU/audio schemas do not imply that matching hardware Adapters already exist.
+
+Source: [sensor schema](https://github.com/PhyAgentOS/forge/blob/e59693910bb5f9572cf39c5a59475c0747ba76e8/interfaces/forge_msgs/sensor.v1.yaml), [Orbbec](https://github.com/PhyAgentOS/adapter-camera-orbbec/blob/de3cbc5361533d8799f586939266289d7527b203/README.md), [RealSense](https://github.com/PhyAgentOS/adapter-camera-realsense/blob/77627b4d8e3977aabf016af6846e9f6857cfcde6/README.md).
+
+## 4. Policy Operator
+
+The standard `PolicyAdapter` plugin requires at least:
+
+```python
+is_observation_needed() -> bool
+generate_action(observation: dict, alias_for_cameras: list[str] | None = None)
+```
+
+The runner handles tick, `proprio_state`, image caches and internal `PolicyCommand` lifecycle messages.
+`PolicyCommand` contains `policy_id/command/request_id/inputs_json`; optional `PolicyCommandStatus`
+uses `accepted/rejected/running/done/error`. Supported commands depend on the implementation.
+These internal messages do not replace Core's user-facing Tool API; Agents invoke declared capabilities through Gateway.
+
+Source: [plugin interface](https://github.com/PhyAgentOS/forge/blob/e59693910bb5f9572cf39c5a59475c0747ba76e8/packages/policy/src/forge_policy/policy_protocol.py), [runner](https://github.com/PhyAgentOS/forge/blob/e59693910bb5f9572cf39c5a59475c0747ba76e8/packages/policy/src/forge_policy/node_runner.py).
+
+## 5. Motion / Controller Operator
+
+| Action family | Goal | Typical execution chain |
+| --- | --- | --- |
+| `MoveJoints` | group, joint_names, positions, velocity/acceleration scales | motion policy -> motion_server -> joint trajectory |
+| `MovePose` | group, reference_frame, target_frame, target_pose, tolerances | motion policy -> motion_server IK -> joint trajectory |
+| `FollowJointTrajectory` | Ordered joints, points, relative times, tolerances | joint_trajectory_controller -> JointCommand |
+| `GripperCommand` | One configured gripper-coordinate target | gripper controller -> JointCommand |
+
+Each family has Goal/Feedback/Result. Durations are nonnegative int64 nanoseconds relative to Action/trajectory
+start, not wall-clock time. `MovePose.target_pose` expresses target_frame in reference_frame, with position
+in metres and quaternion fields `qx/qy/qz/qw`. Gripper coordinates may be linear opening or rotation;
+read Endpoint/controller configuration rather than assuming metres.
+Dora terminal Action metadata uses `succeeded/aborted/canceled`, distinct from Gateway invocation phases.
+Position trajectory controllers do not provide hard-real-time motor servos; hardware owns low-level control.
+
+Source: [motion schema](https://github.com/PhyAgentOS/forge/blob/e59693910bb5f9572cf39c5a59475c0747ba76e8/interfaces/forge_msgs/motion.v1.yaml), [Motion server](https://github.com/PhyAgentOS/operator-motion/blob/24c8a430715f697eea8431bf169c21b8cbb5eb92/packages/motion_server/README.md), [controllers](https://github.com/PhyAgentOS/operator-controls/blob/cde73dc2a6222d81b01ffc32f69f12cb12e42760/README.md).
+
+## 6. Simulator Operator
+
+MuJoCo accepts JointCommand on `action` / `action/` and publishes `proprio_state`, `image/*`
+and optional `depth/*`. Control ticks may execute multiple physics substeps; control frequency and
+physics timestep are configured separately. `joint_to_actuator`, `actuator_order` and logical gripper
+state expressions must match the model. `sim_command` / `reset_scene` is a simulator extension used
+by sim-control policy, not the general RobotDriver contract. Inspect runtime code as well as the README's I/O list.
+
+Source: [simulator runtime](https://github.com/PhyAgentOS/operator-simulator-mujoco/blob/0a84a1a81807b467338e696032a38b084cb35747/src/mujoco_sim/runtime.py), [scene-control contract](https://github.com/PhyAgentOS/operator-sim-control-policy/blob/85679a4be8953e9071de426c7c0973155121d96f/TOOL_CONTRACTS.md).
+
+## 7. Gateway / ToolEndpoint control plane
+
+Keep three layers distinct: caller-facing HTTP Tool API, Gateway/provider Endpoint Wire and provider-internal SPI.
+
+| Layer | Contract |
+| --- | --- |
+| Core -> Gateway | `/tools`, `/invocations`; see this repository's Forge Tool API guide |
+| Gateway -> provider | `forge.tool.endpoint/v1alpha1`, logical JSON envelopes in Arrow `ToolMessage` |
+| Provider SPI | Query: `query`; Action: `start/cancel/status/result`; Session: `start/stop/status/result` |
+
+Wire distinguishes `request_id` (exchange), `invocation_id` (logical invocation), `attempt_id`
+(execution attempt) and Endpoint identity. JSON numbers must be finite and integers within ±(2^53−1);
+do not place oversized monotonic nanosecond counters in JSON integers.
+High-frequency images, joint states and trajectories remain on the data plane.
+
+Check model, handler and deployed-chain capabilities separately:
+
+- The pinned Forge `packages/tool/src/forge_tool/handler.py` dispatches Query/Action/Session; Action uses cancel, Session uses stop. Library support does not mean every Node exposes every semantic.
+- The pinned standalone Gateway implementation and `tests/test_tool_session.py` support Query/Action/Session. Session has no Action runtime deadline, but handshakes remain bounded and leases still apply. This robot-control-sim example uses Query/Action only. That commit's older README claiming no Session support does not override code.
+- Core Session client contracts alone do not establish compatibility of a particular Gateway/provider pair.
+- Architecture/package guides can reflect different development stages; resolve discrepancies through matching code, tests and deployment validation.
+
+HTTP 202 acceptance, Action terminal state and AgentTask verdict are distinct stages;
+accepted cancellation does not establish physical stopping.
+
+Implementation: [provider handler](https://github.com/PhyAgentOS/forge/blob/e59693910bb5f9572cf39c5a59475c0747ba76e8/packages/tool/src/forge_tool/handler.py),
+[Gateway Session implementation](https://github.com/PhyAgentOS/adapter-forge-gateway/blob/5aaa9d16aff1c1b689dbb53acbcdef406dcb8d97/src/forge_gateway/services/tool_gateway_service.py),
+[Session tests](https://github.com/PhyAgentOS/adapter-forge-gateway/blob/5aaa9d16aff1c1b689dbb53acbcdef406dcb8d97/tests/test_tool_session.py).
+
+Source: [Endpoint Wire](https://github.com/PhyAgentOS/forge/blob/e59693910bb5f9572cf39c5a59475c0747ba76e8/interfaces/forge_tool/PROTOCOL.md), [SPI](https://github.com/PhyAgentOS/forge/blob/e59693910bb5f9572cf39c5a59475c0747ba76e8/packages/tool/src/forge_tool/endpoint/protocol.py), [ToolMessage](https://github.com/PhyAgentOS/forge/blob/e59693910bb5f9572cf39c5a59475c0747ba76e8/interfaces/forge_msgs/tool.v1.yaml); [Core contract](../../forge/README.md).
diff --git a/docs/user_development_guide/track_b/PROTOCOLS_zh.md b/docs/user_development_guide/track_b/PROTOCOLS_zh.md
new file mode 100644
index 000000000..2d6737b70
--- /dev/null
+++ b/docs/user_development_guide/track_b/PROTOCOLS_zh.md
@@ -0,0 +1,150 @@
+# TrackB 公共协议与重要节点类型
+
+[English](PROTOCOLS.md) | [简体中文](PROTOCOLS_zh.md)
+
+[整体架构](README_zh.md) · [仓库目录](REPOSITORIES_zh.md) · [公共协议](PROTOCOLS_zh.md) · [Runtime 关系](RUNTIME_zh.md) · [Skill 开发](SKILL_DEVELOPMENT_zh.md)
+
+本页是接口导航与关键约束摘要,权威字段定义以固定源码中的 schema/接口为准。
+节点类别与代码目录见 [整体架构](README_zh.md) 和 [仓库目录](REPOSITORIES_zh.md);
+Tool/Endpoint/Gateway 在部署中的对应方式见 [Runtime 关系](RUNTIME_zh.md)。
+以下以 Forge 源码快照说明公共契约,旧 Skill 二进制必须使用自己的兼容版本,不能据此直接混装。
+
+## 1. 数据平面:Forge Msgs
+
+节点之间的标准消息使用单行 Apache Arrow `RecordBatch`。语义必须位于真实列中,
+不能依赖可能被 Dora/IPC 丢弃的 Arrow schema metadata。
+标准消息没有统一的 ROS Header;时间来自 Dora event context,坐标系和固定标定来自配置或 Dora metadata。
+Dora 发布时生成的 HLC 不等于传感器采集时间。派生观测应保留明确提供的源采样时间。
+动作的 `goal_id` / `goal_status` 是 event metadata 的显式例外,录制时必须一并保存。
+
+权威定义:[Schema 导读](https://github.com/PhyAgentOS/forge/blob/e59693910bb5f9572cf39c5a59475c0747ba76e8/interfaces/forge_msgs/SCHEMA.md)、[通用单位与时间约定](https://github.com/PhyAgentOS/forge/blob/e59693910bb5f9572cf39c5a59475c0747ba76e8/interfaces/forge_msgs/common.v1.yaml)。
+
+## 2. Robot Adapter
+
+Python 驱动实现 `RobotDriver` 的四个方法:
+
+```python
+connect() -> None
+disconnect() -> None
+get_state() -> JointState
+set_command(command: JointCommand) -> None
+```
+
+可选 `LocomotionRobotDriver.set_locomotion_command(command)` 提供移动底盘控制。
+`BaseRobotDriver.joint_order` 可声明固定关节顺序。连接、使能、限位与设备资源释放由驱动实现。
+
+| 标准 runner 端口 | 消息及行为 |
+| --- | --- |
+| 输入 `tick` | 读取状态并输出 `state` |
+| 输入 `action` / `action/` | 稀疏 `JointCommand`,仅更新 `name` 指定关节;未指定关节保留原目标 |
+| 输入 `master_state` | 将 leader 的 `JointState` 映射为位置命令 |
+| 输入 `locomotion_command` | 支持移动能力时接收 `LocomotionCommand` |
+| 输出 `state` | `JointState`;具体节点若使用不同端口名,以其 dataflow 为准 |
+
+`JointState`:`name` 非空且唯一;`position/velocity/effort` 各为空列表或与 `name` 等长。
+`JointCommand` 增加 `mode` 和 `kp/kd`;mode 支持 `position/velocity/effort/hybrid`,
+旧载荷缺失或 null mode 按 position 解读。消息能表达某种模式,不表示每个驱动都实现该模式。
+旋转关节使用 rad、rad/s、Nm;移动关节使用 m、m/s、N。
+不同源可更新互不相交的关节,同一关节的多个写入源仍需显式仲裁。
+
+`LocomotionCommand`:`vx` 向前、`vy` 向左,单位 m/s;`wz` 逆时针,单位 rad/s,均为机体系。
+零速度表达停止;实际驱动仍需定义 watchdog、限速及不支持侧移时的行为。
+
+源码:[驱动接口](https://github.com/PhyAgentOS/forge/blob/e59693910bb5f9572cf39c5a59475c0747ba76e8/packages/robot/src/forge_robot/robot_protocol.py)、[标准 runner](https://github.com/PhyAgentOS/forge/blob/e59693910bb5f9572cf39c5a59475c0747ba76e8/packages/robot/README.md)、[控制消息 schema](https://github.com/PhyAgentOS/forge/blob/e59693910bb5f9572cf39c5a59475c0747ba76e8/interfaces/forge_msgs/control.v1.yaml)。
+
+## 3. Sensor / Camera Adapter
+
+本次核查没有发现与 `RobotDriver` 对应的统一 `SensorDriver` 基类;当前共享边界是消息 schema,
+设备连接、枚举、采样、重连与端口配置由各相机仓库实现。不要把建议的驱动模板写成现有 API。
+
+| 消息 | 核心字段和约束 |
+| --- | --- |
+| `Image` | `height/width/encoding/step/data`;`step` 为每行字节数,可含 padding;`len(data)=step*height`;多字节像素使用 little-endian |
+| `CompressedImage` | `format/data`,压缩 JPEG/PNG/WebP 不得伪装成 raw Image |
+| `PointCloud` | `width/height/is_dense`、`x/y/z: list`,单位 m;可选属性以空列表表达;组织化点云保留行列对应关系 |
+| `PointCloudBuffer` | 保留动态字段、point/row stride 和字节序的已解码点记录;不是设备原始包 |
+| `Imu` | 角速度 rad/s、加速度 m/s²;orientation 不可用时 null;协方差为空或 9 个数;不能静默归一化四元数 |
+| `AudioChunk` | `sample_rate/channels/sample_format/frame_count/data`;f32le/s16le,按帧交错 |
+
+当前 Orbbec 与 RealSense 节点将深度输出为 `Image(32FC1)`,float32 米,零值无效。
+这是这两个 Adapter 的输出约定;不能仅凭通用 Image 的 encoding 推断所有设备的深度比例。
+相机光学坐标系、深度对齐方式、标定和采样时刻必须由生产者说明。
+Sensor schema 包含 IMU/音频类型,不表示组织中已有对应硬件 Adapter。
+
+源码:[Sensor schema](https://github.com/PhyAgentOS/forge/blob/e59693910bb5f9572cf39c5a59475c0747ba76e8/interfaces/forge_msgs/sensor.v1.yaml)、[Orbbec 输出约定](https://github.com/PhyAgentOS/adapter-camera-orbbec/blob/de3cbc5361533d8799f586939266289d7527b203/README.md)、[RealSense 输出约定](https://github.com/PhyAgentOS/adapter-camera-realsense/blob/77627b4d8e3977aabf016af6846e9f6857cfcde6/README.md)。
+
+## 4. Policy Operator
+
+标准算法插件 `PolicyAdapter` 的最小接口为:
+
+```python
+is_observation_needed() -> bool
+generate_action(observation: dict, alias_for_cameras: list[str] | None = None)
+```
+
+runner 处理 tick、`proprio_state`、图像缓存,以及内部 `PolicyCommand` 生命周期消息。
+`PolicyCommand` 包含 `policy_id/command/request_id/inputs_json`;可选的 `PolicyCommandStatus`
+使用 `accepted/rejected/running/done/error`。具体支持的 command 取决于实现。
+这组内部消息不替代 Core 面向用户的 Tool API;Agent 应经 Gateway 调用已声明的能力。
+
+源码:[插件接口](https://github.com/PhyAgentOS/forge/blob/e59693910bb5f9572cf39c5a59475c0747ba76e8/packages/policy/src/forge_policy/policy_protocol.py)、[runner](https://github.com/PhyAgentOS/forge/blob/e59693910bb5f9572cf39c5a59475c0747ba76e8/packages/policy/src/forge_policy/node_runner.py)。
+
+## 5. Motion / Controller Operator
+
+| 动作族 | 目标 | 典型执行链 |
+| --- | --- | --- |
+| `MoveJoints` | group、joint_names、positions、速度/加速度比例 | motion policy → motion_server → 关节轨迹 |
+| `MovePose` | group、reference_frame、target_frame、target_pose、容差 | motion policy → motion_server 的 IK → 关节轨迹 |
+| `FollowJointTrajectory` | 有序关节、轨迹点、相对时间与容差 | joint_trajectory_controller → JointCommand |
+| `GripperCommand` | 配置选定的一个夹爪坐标目标 | gripper controller → JointCommand |
+
+每族都有 Goal/Feedback/Result。持续时间为非负 int64 纳秒,相对动作或轨迹起点,不能当墙钟时间。
+`MovePose.target_pose` 表达 target_frame 在 reference_frame 下的位置与姿态,位置 m,四元数字段 `qx/qy/qz/qw`。
+夹爪坐标可为平移开度或旋转角,必须看 endpoint/controller 配置,不能一律当米。
+Dora 动作 metadata 的终态是 `succeeded/aborted/canceled`;不要与 Gateway invocation phase 混用。
+位置轨迹 controller 不提供硬实时电机伺服;硬件低层控制仍由设备负责。
+
+源码:[Motion schema](https://github.com/PhyAgentOS/forge/blob/e59693910bb5f9572cf39c5a59475c0747ba76e8/interfaces/forge_msgs/motion.v1.yaml)、[Motion server](https://github.com/PhyAgentOS/operator-motion/blob/24c8a430715f697eea8431bf169c21b8cbb5eb92/packages/motion_server/README.md)、[Controllers](https://github.com/PhyAgentOS/operator-controls/blob/cde73dc2a6222d81b01ffc32f69f12cb12e42760/README.md)。
+
+## 6. Simulator Operator
+
+MuJoCo 接收 `action` / `action/` 的 JointCommand,输出 `proprio_state`、`image/*` 和可选 `depth/*`。
+控制 tick 内运行若干物理子步;控制频率与物理 timestep 分开配置。
+`joint_to_actuator`、`actuator_order`、逻辑夹爪状态表达式必须与模型匹配。
+`sim_command` 的 `reset_scene` 是此模拟器的扩展输入,由 sim-control policy 使用;它不是通用 RobotDriver 协议。
+当前 README 的 I/O 列表未穷尽该扩展,接入时同时核对 runtime 实现。
+
+源码:[Simulator runtime](https://github.com/PhyAgentOS/operator-simulator-mujoco/blob/0a84a1a81807b467338e696032a38b084cb35747/src/mujoco_sim/runtime.py)、[场景控制契约](https://github.com/PhyAgentOS/operator-sim-control-policy/blob/85679a4be8953e9071de426c7c0973155121d96f/TOOL_CONTRACTS.md)。
+
+## 7. Gateway / ToolEndpoint 控制平面
+
+分清三层:外部调用者的 HTTP Tool API、Gateway 与 provider 之间的 Endpoint Wire、provider 内部的 SPI。
+本文不将它们合并成一个协议。
+
+| 层 | 契约 |
+| --- | --- |
+| Core → Gateway | `/tools`、`/invocations`;见本仓 Forge Tool API 文档 |
+| Gateway → provider | `forge.tool.endpoint/v1alpha1`,以 Arrow `ToolMessage` 承载逻辑 JSON envelope |
+| provider SPI | Query:`query`;Action:`start/cancel/status/result`;Session:`start/stop/status/result` |
+
+Wire 明确区分 `request_id`(一次交换)、`invocation_id`(逻辑调用)、`attempt_id`(执行尝试)和 endpoint 身份。
+JSON 数字必须有限,整数在 ±(2^53−1) 内;不要把超大单调时钟纳秒数直接塞入 JSON 整数。
+高频图像、关节状态与轨迹留在数据平面。
+
+协议模型、provider handler 和整条部署链的能力必须分开核对:
+
+- 固定 Forge 快照的 `packages/tool/src/forge_tool/handler.py` 包含 Query、Action、Session dispatch,
+ Action 使用 cancel,Session 使用 stop;接口库实现不等于每个节点都暴露这些能力。
+- 独立 Gateway 当前固定快照的实现和 `tests/test_tool_session.py` 支持 Query、Action、Session;
+ Session 使用 stop,运行期无 Action deadline,但调用握手有界、provider lease 仍有效。本组 robot-control-sim 示例只使用 Query/Action。
+ 该提交的旧 README 曾写“不实现 Session”,不能据此覆盖实际代码能力。
+- Core 存在 Session 客户端契约,也不能据此推断目标 Gateway/provider 组合已支持 Session。
+- 不同仓库的架构说明和包指南可能记录不同演进阶段。出现状态描述差异时,以匹配版本的实现、测试和部署验收为依据。
+
+HTTP 202 受理、动作终态和 AgentTask verdict 是不同阶段;取消请求被接受也不证明物理停止。
+
+实现依据:[provider handler](https://github.com/PhyAgentOS/forge/blob/e59693910bb5f9572cf39c5a59475c0747ba76e8/packages/tool/src/forge_tool/handler.py)、
+[Gateway Session 实现](https://github.com/PhyAgentOS/adapter-forge-gateway/blob/5aaa9d16aff1c1b689dbb53acbcdef406dcb8d97/src/forge_gateway/services/tool_gateway_service.py)、
+[Session 测试](https://github.com/PhyAgentOS/adapter-forge-gateway/blob/5aaa9d16aff1c1b689dbb53acbcdef406dcb8d97/tests/test_tool_session.py)。
+
+源码:[Endpoint Wire](https://github.com/PhyAgentOS/forge/blob/e59693910bb5f9572cf39c5a59475c0747ba76e8/interfaces/forge_tool/PROTOCOL.md)、[SPI](https://github.com/PhyAgentOS/forge/blob/e59693910bb5f9572cf39c5a59475c0747ba76e8/packages/tool/src/forge_tool/endpoint/protocol.py)、[ToolMessage](https://github.com/PhyAgentOS/forge/blob/e59693910bb5f9572cf39c5a59475c0747ba76e8/interfaces/forge_msgs/tool.v1.yaml);[Core 调用契约](../../forge/README_zh.md)。
diff --git a/docs/user_development_guide/track_b/README.md b/docs/user_development_guide/track_b/README.md
new file mode 100644
index 000000000..e4a47ed83
--- /dev/null
+++ b/docs/user_development_guide/track_b/README.md
@@ -0,0 +1,104 @@
+# TrackB Framework Guide
+
+[English](README.md) | [简体中文](README_zh.md)
+
+[Overview](README.md) · [Repositories](REPOSITORIES.md) · [Protocols](PROTOCOLS.md) · [Runtime](RUNTIME.md) · [Skill development](SKILL_DEVELOPMENT.md)
+
+[Bundle and Tool integration reference](../README.md) · [Piper X tutorial](../PIPER_X_DEMO.md) · [Documentation index](../../README.md)
+
+**Platform availability:** External resource submissions and changes to existing registered repositories are not yet open. They must wait for the approval service to be completed and opened. Current registration/publication is administrator-managed. Local development and validation can proceed; platform publication steps below are conditional on that workflow becoming available. See the [contribution guide](../../../CONTRIBUTING.md).
+
+## 1. Scope and reading path
+
+TrackB here means the robotics execution framework built on Forge and Dora and deployed through Skill Bundles.
+Forge supplies common messages, interfaces and Node foundations; Dora hosts processes/dataflows;
+PhyAgentOS Core organizes deployment and task workflows through Skills and invokes Node capabilities through Gateway.
+
+| Document | Questions answered |
+| --- | --- |
+| This overview | Layer responsibilities, code organization, Node categories and version boundaries |
+| [Repository catalog](REPOSITORIES.md) | Source locations and responsibilities of framework, Adapter, Operator and benchmark repositories |
+| [Protocols and important Node types](PROTOCOLS.md) | Robot/Sensor/Policy/Motion messages, ports, units and Endpoint contracts |
+| [Skill, Tool, Endpoint, Gateway and Runtime](RUNTIME.md) | Logical relationships and robot-control-sim 0.1.2 configuration, routing and execution |
+| [Skill development manual](SKILL_DEVELOPMENT.md) | Procedures and difficulty for configuration changes, new profiles and independent Node development |
+
+To integrate another robot already supported by existing Nodes, read the first two development modes,
+then follow the [Piper X demo](../PIPER_X_DEMO.md) for model/configuration work and native Action validation.
+For a new driver, algorithm or Tool capability, examine protocols/source before using mode three.
+
+## 2. Overall architecture
+
+```mermaid
+flowchart TB
+ U["User / Agent / application"]
+ CORE["PhyAgentOS Core: workflows, AgentTask, verification"]
+ SKILL["Skill Bundle: SKILL.md, manifest, profiles, assets, Node locks"]
+ LIFE["Skill Runtime Manager: environments, launch, health checks, stop"]
+ STORE["Registry / artifact storage"]
+ subgraph FLOW["Dora dataflow: deployed execution graph"]
+ GW["Gateway Adapter: external API, Tool routing, invocation state"]
+ OP["Operator: policy, planning, control, simulation"]
+ AD["Adapter: devices, external services, viewer"]
+ GW <-->|"Low-frequency Tool control messages"| OP
+ GW <-->|"Low-frequency Tool control messages"| AD
+ OP <-->|"State, observations, trajectories, commands"| AD
+ end
+ EXT["Hardware, sensors, external services or display"]
+ U --> CORE
+ SKILL --> CORE
+ SKILL --> LIFE
+ STORE -.->|"Search, download, integrity checks"| LIFE
+ LIFE -->|"Launch / inspect / stop"| FLOW
+ CORE -->|"ForgeToolClient / HTTP Tool API"| GW
+ AD <--> EXT
+```
+
+Registry distributes resources; it is not involved in every robot command. The selected profile's dataflow
+connects models, cameras, IK and controllers. Operator/Adapter boxes are categories, not mandatory components
+of every Skill. MuJoCo is a Simulator Operator and can produce state without a hardware Adapter.
+
+## 3. Code layers
+
+| Layer | Main code / configuration | Responsibility |
+| --- | --- | --- |
+| Agent and Skill lifecycle | Core `forge/`, `skill_runtime/`, `SKILL.md` | Workflows, task binding/verification, deployment environments and runtime state |
+| Skill assembly | `skill.yaml`, `profiles//`, `assets/` | Robot, Nodes, Tools, models, connections and parameters |
+| External boundaries | `adapter-forge-gateway`, device/viewer Adapters | External calls, protocol translation and resource lifecycle |
+| Graph computation/execution | `operator-*` | Policy, motion planning, trajectory control, simulation |
+| Shared framework | `forge` | Common, Msgs, Robot, Policy, Kinematics and Tool families |
+| Dataflow runtime | Dora | Launch Nodes and forward typed port data/events |
+
+Repositories, Nodes, Endpoints and Tools are not one-to-one. A repository may publish several Nodes;
+a Node may implement multiple Endpoints/operations or handle data only. A Skill may reuse Nodes from
+several repositories, and the same immutable Node artifact may be locked by multiple Skills/profiles.
+See [Runtime relationships](RUNTIME.md).
+
+## 4. Adapter and Operator
+
+- **Adapter:** owns an external device/service/runtime/caller boundary, translates protocols and manages resources. Robot, Camera, Gateway and Viewer are examples.
+- **Operator:** computes policy, planning, control, perception or simulation using Forge messages as its main boundary.
+- Classification follows primary responsibility, not input/output direction; either category may expose ToolEndpoint.
+- `ToolEndpoint` is a capability interface; `PolicyAdapter` names a policy plugin interface. Neither adds a third Node category.
+- External Agent/web clients are outside the Dora Node taxonomy.
+
+Definition: [Forge Node Model](https://github.com/PhyAgentOS/forge/blob/e59693910bb5f9572cf39c5a59475c0747ba76e8/README.md).
+
+## 5. Architecture, versions and source snapshots
+
+Logical architecture describes stable responsibilities/relationships. Actual capabilities must be checked
+against compatible Gateway, provider, Core and artifact versions.
+
+| Scope | Version basis | Usage |
+| --- | --- | --- |
+| Forge source snapshot | Dora 1.x / Forge 2.x; Common 2.1.0, other five families 2.0.0 | Pin commits/locks; do not automatically replace older Nodes |
+| Forge maintenance line | `stable/1.x`, Dora 0.4 compatibility | Still verify exact tags/commits for old Nodes |
+| Current Core release | Core v1.1.1 | See the [changelog](../../../CHANGELOG.md) |
+| Recorded runtime example | Core v1.1.0, Dora CLI 0.4.1, robot-control-sim 0.1.2 | Interpret behavior using the original locked artifacts |
+| Piper X demo | Model, profile and workflow changes on that baseline | Preserve nine Node locks; no protocol upgrade |
+
+Public source and binary provenance are separate requirements. The catalog's source snapshot does not
+prove how an older Release binary was built. See [independent Node development](SKILL_DEVELOPMENT.md#4-mode-three-develop-nodes-and-assemble-a-skill)
+for modification, build, archive and provenance requirements.
+
+Twenty code repositories are now under PhyAgentOS; organization configuration `.github` remains under
+Forgelab-Robotics. See the [catalog](REPOSITORIES.md) for locations and post-transfer maintenance.
diff --git a/docs/user_development_guide/track_b/README_zh.md b/docs/user_development_guide/track_b/README_zh.md
new file mode 100644
index 000000000..44a591f8d
--- /dev/null
+++ b/docs/user_development_guide/track_b/README_zh.md
@@ -0,0 +1,102 @@
+# TrackB 框架说明
+
+[English](README.md) | [简体中文](README_zh.md)
+
+[整体架构](README_zh.md) · [仓库目录](REPOSITORIES_zh.md) · [公共协议](PROTOCOLS_zh.md) · [Runtime 关系](RUNTIME_zh.md) · [Skill 开发](SKILL_DEVELOPMENT_zh.md)
+
+[Bundle 与 Tool 接入参考](../README_zh.md) · [Piper X 完整示例](../PIPER_X_DEMO_zh.md) · [文档索引](../../README_zh.md)
+
+**平台开放范围:** 外部贡献提交及已有登记仓库修改暂未开放,需等待审批服务完成并开放。当前登记与发布由管理员维护;可先进行本地开发验证。下文的平台发布步骤以相关流程开放为前提,详见[贡献指南](../../../CONTRIBUTING_zh.md)。
+
+## 1. 框架范围与阅读路径
+
+本文将基于 Forge 和 Dora、由 Skill Bundle 配置部署的机器人执行框架称为 TrackB。
+Forge 提供公共消息、接口和节点实现基础;Dora 承载进程与数据流;PhyAgentOS Core 使用 Skill
+组织部署与任务工作流,并经 Gateway 调用节点能力。
+
+| 文档 | 解决的问题 |
+| --- | --- |
+| 本文:整体架构 | 各层职责、代码组成、节点分类与版本边界 |
+| [仓库目录](REPOSITORIES_zh.md) | 基础库、Adapter、Operator、benchmark 的源码位置和职责 |
+| [公共协议与重要节点类型](PROTOCOLS_zh.md) | Robot/Sensor/Policy/Motion 消息、端口、单位及 Endpoint 契约 |
+| [Skill、Tool、Endpoint、Gateway 与 Runtime](RUNTIME_zh.md) | 理论关系与 robot-control-sim 0.1.2 的实际配置、路由、执行链 |
+| [Skill 开发手册](SKILL_DEVELOPMENT_zh.md) | 修改原 profile、新增 profile、独立 Node 开发三种模式的流程与难度 |
+
+只想接入现有节点支持的新机器人时,先阅读 Skill 开发手册的前两种模式,再跟随
+[Piper X demo](../PIPER_X_DEMO_zh.md)完成模型、配置和原生 Action 验收。
+需要新增设备驱动、算法或 Tool 能力时,先查协议和源码,再进入第三种模式。
+
+## 2. 整体架构
+
+```mermaid
+flowchart TB
+ U["用户 / Agent / 应用"]
+ CORE["PhyAgentOS Core:工作流、AgentTask、验证"]
+ SKILL["Skill Bundle:SKILL.md、manifest、profiles、资产、Node locks"]
+ LIFE["Skill Runtime Manager:安装环境、启动、健康检查、停止"]
+ STORE["Registry / 制品存储"]
+ subgraph FLOW["Dora dataflow:部署后的执行图"]
+ GW["Gateway Adapter:外部 API、Tool 路由、调用状态"]
+ OP["Operator:策略、规划、控制、仿真"]
+ AD["Adapter:设备、外部服务、Viewer"]
+ GW <-->|"低频 Tool 控制消息"| OP
+ GW <-->|"低频 Tool 控制消息"| AD
+ OP <-->|"状态、观测、轨迹、命令"| AD
+ end
+ EXT["真机、传感器、外部服务或显示端"]
+ U --> CORE
+ SKILL --> CORE
+ SKILL --> LIFE
+ STORE -.->|"检索、下载与完整性校验"| LIFE
+ LIFE -->|"启动 / 核对 / 停止"| FLOW
+ CORE -->|"ForgeToolClient / HTTP Tool API"| GW
+ AD <--> EXT
+```
+
+图中 Registry 属于资源分发阶段,不参与每一条机器人命令。模型、相机、IK 和控制器的连接由
+选定 profile 的 dataflow 决定;图中的 Operator/Adapter 方框代表类别,并不要求每个 Skill 包含所有类别。
+MuJoCo 在当前分类中属于 Simulator Operator,本身可以产生仿真状态,无需一个真机 Adapter。
+
+## 3. 代码按什么层次组成
+
+| 层次 | 主要代码 / 配置 | 职责 |
+| --- | --- | --- |
+| Agent 与 Skill 生命周期 | Core 的 `forge/`、`skill_runtime/`、`SKILL.md` | 工作流、任务绑定与验证、部署环境与运行状态 |
+| Skill 组装 | `skill.yaml`、`profiles//`、`assets/` | 选择机器人、节点、Tool、模型、连接与参数 |
+| 外部访问边界 | `adapter-forge-gateway`、设备和 Viewer Adapter | 外部调用、协议转换与资源生命周期 |
+| 图内计算与执行 | `operator-*` | 策略、运动规划、轨迹控制、仿真等节点实现 |
+| 公共框架 | `forge` | Common、Msgs、Robot、Policy、Kinematics、Tool 六个家族 |
+| 数据流运行底座 | Dora | 按 dataflow 启动节点,转发有类型的端口数据和事件 |
+
+仓库、Node、Endpoint、Tool 不是一一对应关系。一个仓库可以发布多个 Node;一个 Node 可以实现
+多个 Endpoint/operation,也可以只处理数据而不暴露 Endpoint。一个 Skill 可以复用多个仓库的 Node,
+相同 Node 制品也可以被多个 Skill/profile 锁定。详见 [Runtime 关系](RUNTIME_zh.md)。
+
+## 4. Adapter 与 Operator
+
+- **Adapter(对外边界)**:与外部设备、服务、运行时或调用者通信,转换协议并管理资源生命周期。
+ Robot、Camera、Gateway、Viewer 属于这一侧。
+- **Operator(图内计算)**:以 Forge 消息为主要输入/输出,进行策略、规划、控制、感知或仿真计算。
+- 分类依据主要职责,不依据输入/输出方向;两类节点都可以暴露 ToolEndpoint。
+- `ToolEndpoint` 是能力接口;`PolicyAdapter` 是策略插件接口名,均不额外构成节点大类。
+- 外部 Agent/Web 客户端不属于 Dora 节点分类。
+
+定义依据:[Forge Node Model](https://github.com/PhyAgentOS/forge/blob/e59693910bb5f9572cf39c5a59475c0747ba76e8/README.md)。
+
+## 5. 理论边界、实现版本与源码快照
+
+“理论架构”描述稳定职责和连接关系;实际功能必须按 Gateway、provider、Core 和制品版本共同核对。
+
+| 范围 | 版本依据 | 使用方式 |
+| --- | --- | --- |
+| Forge 源码快照 | Dora 1.x / Forge 2.x;Common 2.1.0,其余五家族 2.0.0 | 以固定提交和依赖锁为准,不自动替代旧 Node |
+| Forge 维护线 | `stable/1.x`,Dora 0.4 兼容线 | 旧节点维护仍需核对具体 tag/commit |
+| 当前 Core 发布版本 | Core v1.1.1 | 参见 [更新记录](../../../CHANGELOG.md) |
+| 本组历史运行示例 | Core v1.1.0、Dora CLI 0.4.1、robot-control-sim 0.1.2 | 依照原 Skill 锁定的制品解释行为 |
+| Piper X demo | 在上行基线上修改模型、profile 和工作流 | 保留九个 Node locks,未进行协议升级 |
+
+代码已开源和二进制可追溯是不同的交付条件;索引中的最新源码不证明某个旧 Release 二进制由它构建。
+Node 修改、构建、归档和溯源要求见 [独立 Node 开发](SKILL_DEVELOPMENT_zh.md#4-模式三独立开发-node-并组装自己的-skill)。
+
+20 个代码仓库已迁入 PhyAgentOS;组织配置 `.github` 保留在 Forgelab-Robotics。
+完整目录和迁移后的维护约束见 [仓库目录](REPOSITORIES_zh.md)。
diff --git a/docs/user_development_guide/track_b/REPOSITORIES.md b/docs/user_development_guide/track_b/REPOSITORIES.md
new file mode 100644
index 000000000..248929a5c
--- /dev/null
+++ b/docs/user_development_guide/track_b/REPOSITORIES.md
@@ -0,0 +1,148 @@
+# TrackB Repository Catalog and Code Organization
+
+[English](REPOSITORIES.md) | [简体中文](REPOSITORIES_zh.md)
+
+[Overview](README.md) · [Repositories](REPOSITORIES.md) · [Protocols](PROTOCOLS.md) · [Runtime](RUNTIME.md) · [Skill development](SKILL_DEVELOPMENT.md)
+
+## 1. Scope
+
+This catalog covers 20 transferred public code repositories: 10 Adapters, 8 Operators, Forge and one benchmark.
+It also lists the Forgelab-Robotics `.github` organization configuration; it is not the entire PhyAgentOS organization.
+Core task/Skill lifecycle code lives in [this repository](../../../PhyAgentOS), separately from downstream Nodes.
+
+Repository links follow current locations; commit links pin the inspected source snapshot.
+Classification does not establish integration in one Skill or validation of every platform, language or hardware capability.
+
+## 2. Categorized catalog
+
+### 2.1 Shared framework
+
+| Category | Current source | Description | Source snapshot |
+| --- | --- | --- | --- |
+| Framework | [forge](https://github.com/PhyAgentOS/forge) | Common, Msgs, Robot, Policy, Kinematics, Tool; cross-language messages and interfaces | [e59693910bb5](https://github.com/PhyAgentOS/forge/tree/e59693910bb5f9572cf39c5a59475c0747ba76e8) |
+
+### 2.2 Adapters: external boundaries
+
+| Category | Current source | Description | Source snapshot |
+| --- | --- | --- | --- |
+| Adapter · Sensor | [adapter-camera-orbbec](https://github.com/PhyAgentOS/adapter-camera-orbbec) | Orbbec color/depth/IR/optional point clouds, initialization and publishing | [de3cbc536153](https://github.com/PhyAgentOS/adapter-camera-orbbec/tree/de3cbc5361533d8799f586939266289d7527b203) |
+| Adapter · Sensor | [adapter-camera-realsense](https://github.com/PhyAgentOS/adapter-camera-realsense) | RealSense D400 color/depth/IR/optional point-cloud acquisition and publishing | [77627b4d8e39](https://github.com/PhyAgentOS/adapter-camera-realsense/tree/77627b4d8e3977aabf016af6846e9f6857cfcde6) |
+| Adapter · Sensor | [adapter-camera-usb](https://github.com/PhyAgentOS/adapter-camera-usb) | Rust/V4L2 USB camera; raw/compressed images and device checks | [bdbe5ebb016d](https://github.com/PhyAgentOS/adapter-camera-usb/tree/bdbe5ebb016da299ff1e0b461260ce1ddd52d234) |
+| Adapter · Gateway | [adapter-forge-gateway](https://github.com/PhyAgentOS/adapter-forge-gateway) | HTTP/WebSocket access, Tool routing, Registry and readiness | [5aaa9d16aff1](https://github.com/PhyAgentOS/adapter-forge-gateway/tree/5aaa9d16aff1c1b689dbb53acbcdef406dcb8d97) |
+| Adapter · Robot | [adapter-franka-fr3](https://github.com/PhyAgentOS/adapter-franka-fr3) | Franka FR3v2 and Franka Hand drivers/models | [efd7a6bd019c](https://github.com/PhyAgentOS/adapter-franka-fr3/tree/efd7a6bd019c7135ae506274ca73ef5879f4a384) |
+| Adapter · Robot | [adapter-robot-piper](https://github.com/PhyAgentOS/adapter-robot-piper) | AgileX Piper hardware driver, Dora examples and multi-format robot models | [3ea5156cb369](https://github.com/PhyAgentOS/adapter-robot-piper/tree/3ea5156cb369c302bb2e3ff6f1ebfb6af90a08d8) |
+| Adapter · Robot | [adapter-robot-so101](https://github.com/PhyAgentOS/adapter-robot-so101) | SO101 serial/Feetech driver, device utilities and MJCF model | [fb6b59292366](https://github.com/PhyAgentOS/adapter-robot-so101/tree/fb6b59292366059acd10cb2439d155c4c8015cfc) |
+| Adapter · Robot | [adapter-robot-xlerobot](https://github.com/PhyAgentOS/adapter-robot-xlerobot) | XLeRobot dual-arm mobile robot integration, configuration and models | [5ceb37fdea4d](https://github.com/PhyAgentOS/adapter-robot-xlerobot/tree/5ceb37fdea4d6c7e454914b1b5e180b4728ef0fa) |
+| Adapter · Robot | [adapter-robot-zerith_h1_pro](https://github.com/PhyAgentOS/adapter-robot-zerith_h1_pro) | Zerith H1 Pro joint/base integration, SDK and examples | [e36dc9b0bdfd](https://github.com/PhyAgentOS/adapter-robot-zerith_h1_pro/tree/e36dc9b0bdfd68342d55180485b561c73162cfc3) |
+| Adapter · Viewer | [adapter-viewer-image](https://github.com/PhyAgentOS/adapter-viewer-image) | Image viewer consuming Forge image messages | [ea5900a7225c](https://github.com/PhyAgentOS/adapter-viewer-image/tree/ea5900a7225c2bfadd89bbfe23c023ec9fbe1bb6) |
+
+### 2.3 Operators: graph computation
+
+| Category | Current source | Description | Source snapshot |
+| --- | --- | --- | --- |
+| Operator · Control | [operator-controls](https://github.com/PhyAgentOS/operator-controls) | joint_trajectory_controller, gripper_action_controller and fake plant | [cde73dc2a622](https://github.com/PhyAgentOS/operator-controls/tree/cde73dc2a6222d81b01ffc32f69f12cb12e42760) |
+| Operator · Policy | [operator-gripper-action-policy](https://github.com/PhyAgentOS/operator-gripper-action-policy) | Translate Tool opening requests to gripper Actions and execution results | [bb69223497b9](https://github.com/PhyAgentOS/operator-gripper-action-policy/tree/bb69223497b944dd1a0f6fe9ecb36486168a8cc4) |
+| Operator · Policy | [operator-kai0](https://github.com/PhyAgentOS/operator-kai0) | Kai0 policy source, inference execution and Node packaging | [94baa639fe6d](https://github.com/PhyAgentOS/operator-kai0/tree/94baa639fe6d36bb5d41d214923108993aa002cc) |
+| Operator · Policy | [operator-lerobot-runner](https://github.com/PhyAgentOS/operator-lerobot-runner) | LeRobot policy execution, observations and control | [f6b26f4f89bb](https://github.com/PhyAgentOS/operator-lerobot-runner/tree/f6b26f4f89bbd9831f64e3fc43d36499d6c86a92) |
+| Operator · Motion | [operator-motion](https://github.com/PhyAgentOS/operator-motion) | motion_server and motion_action_policy; goals, IK and trajectories | [24c8a430715f](https://github.com/PhyAgentOS/operator-motion/tree/24c8a430715f697eea8431bf169c21b8cbb5eb92) |
+| Operator · Policy | [operator-relative-pose-policy](https://github.com/PhyAgentOS/operator-relative-pose-policy) | Relative end-effector pose resolution and motion.relative_pose integration | [4749b696a8b3](https://github.com/PhyAgentOS/operator-relative-pose-policy/tree/4749b696a8b3210e193860d6aeed92382fbad113) |
+| Operator · Policy | [operator-sim-control-policy](https://github.com/PhyAgentOS/operator-sim-control-policy) | Robot descriptor queries, simulation reset and deferred re-home | [85679a4be895](https://github.com/PhyAgentOS/operator-sim-control-policy/tree/85679a4be8953e9071de426c7c0973155121d96f) |
+| Operator · Simulator | [operator-simulator-mujoco](https://github.com/PhyAgentOS/operator-simulator-mujoco) | MuJoCo stepping, joint commands, images and state output | [0a84a1a81807](https://github.com/PhyAgentOS/operator-simulator-mujoco/tree/0a84a1a81807b467338e696032a38b084cb35747) |
+
+### 2.4 Benchmark and organization configuration
+
+| Category | Current source | Description | Source snapshot |
+| --- | --- | --- | --- |
+| Organization configuration | [.github](https://github.com/Forgelab-Robotics/.github) | Organization profile/overview; returned to Forgelab-Robotics | [2df5cc313ca9](https://github.com/Forgelab-Robotics/.github/tree/2df5cc313ca9193d6ceb75b87a85e77072d9d1aa) |
+| Benchmark | [benchmark-libero](https://github.com/PhyAgentOS/benchmark-libero) | LIBERO simulation/evaluation and Node packaging; classified by responsibility without adding another Node category | [e01cd66167b8](https://github.com/PhyAgentOS/benchmark-libero/tree/e01cd66167b85522afe427c5b85da8af30c00c97) |
+
+### 2.5 Six families inside forge
+
+| Family | Main directories | Capabilities |
+| --- | --- | --- |
+| Common | `packages/common`, `crates/forge_common`, `cpp/forge_common` | Logging, tracing, utilities and optional publish/receive observability |
+| Msgs | `interfaces/forge_msgs`, `packages/msgs`, `crates/forge_msgs`, `cpp/forge_msgs` | Authoritative schemas, message models and Arrow serialization |
+| Robot | `packages/robot`, `cpp/forge_robot` | Driver protocols, joint-limit helpers and optional Dora runners |
+| Policy | `packages/policy` | Policy plugin protocols, observation cache and Operator loop |
+| Kinematics | `packages/kinematics` | URDF FK, Jacobian and IK helpers |
+| Tool | `interfaces/forge_tool`, `packages/tool` | Endpoint SPI, Wire models, handlers and carrier bindings |
+
+These are framework families, not six mandatory processes. Check language coverage and releases per family;
+Python/Rust/C++ directories do not imply equal implementation of every interface.
+
+## 3. robot-control-sim Node-to-source mapping
+
+| Node in Skill lock | Source repository | Source entrypoint |
+| --- | --- | --- |
+| `gateway` | [adapter-forge-gateway](https://github.com/PhyAgentOS/adapter-forge-gateway) | [README.md](https://github.com/PhyAgentOS/adapter-forge-gateway/blob/5aaa9d16aff1c1b689dbb53acbcdef406dcb8d97/README.md) |
+| `sim_control_policy` | [operator-sim-control-policy](https://github.com/PhyAgentOS/operator-sim-control-policy) | [README.md](https://github.com/PhyAgentOS/operator-sim-control-policy/blob/85679a4be8953e9071de426c7c0973155121d96f/README.md) |
+| `motion_server / motion_action_policy` | [operator-motion](https://github.com/PhyAgentOS/operator-motion) | [packages/motion_server](https://github.com/PhyAgentOS/operator-motion/tree/24c8a430715f697eea8431bf169c21b8cbb5eb92/packages/motion_server) |
+| `joint_trajectory_controller` | [operator-controls](https://github.com/PhyAgentOS/operator-controls) | [packages/joint_trajectory_controller](https://github.com/PhyAgentOS/operator-controls/tree/cde73dc2a6222d81b01ffc32f69f12cb12e42760/packages/joint_trajectory_controller) |
+| `gripper_action_controller` | [operator-controls](https://github.com/PhyAgentOS/operator-controls) | [packages/gripper_action_controller](https://github.com/PhyAgentOS/operator-controls/tree/cde73dc2a6222d81b01ffc32f69f12cb12e42760/packages/gripper_action_controller) |
+| `gripper_action_policy` | [operator-gripper-action-policy](https://github.com/PhyAgentOS/operator-gripper-action-policy) | [README.md](https://github.com/PhyAgentOS/operator-gripper-action-policy/blob/bb69223497b944dd1a0f6fe9ecb36486168a8cc4/README.md) |
+| `mujoco_sim` | [operator-simulator-mujoco](https://github.com/PhyAgentOS/operator-simulator-mujoco) | [src/mujoco_sim](https://github.com/PhyAgentOS/operator-simulator-mujoco/tree/0a84a1a81807b467338e696032a38b084cb35747/src/mujoco_sim) |
+| `image_viewer` | [adapter-viewer-image](https://github.com/PhyAgentOS/adapter-viewer-image) | [README.md](https://github.com/PhyAgentOS/adapter-viewer-image/blob/ea5900a7225c2bfadd89bbfe23c023ec9fbe1bb6/README.md) |
+
+This table locates implementations; it does not prove binary build provenance. Original artifact IDs,
+versions and SHA256 values come from the installed `skill.yaml`. Rebuilt replacements require their own
+published version/digest and validation.
+
+`operator-motion` provides motion server and motion action policy; `operator-controls` provides two controllers.
+The example's nine Nodes therefore come from seven repositories. Repository count is not process count.
+See [actual runtime relationships](RUNTIME.md#4-actual-robot-control-sim-assembly) for Endpoint routes and Node IDs.
+
+## 4. Maintenance after transfer
+
+- Use PhyAgentOS source URLs and the actual Forgelab-Robotics owner for `.github`.
+- Organization transfer preserves repository/source identity and existing release assets. Owner changes do not upgrade package names, artifact IDs, tags or archive digests.
+- Check old repository/Release compatibility links; do not occupy transferred repositories' old paths.
+- Before publishing again, check CI credentials, package permissions, webhooks and branch protection; transfer alone does not validate build/publish access.
+- Register catalog/database resources through the destination platform separately; GitHub transfer does not update a consumer Registry automatically.
+- Dora/Forge upgrades require new Node/Skill versions. Check [protocols](PROTOCOLS.md) and dependency locks before cross-repository changes.
+
+See the [development manual](SKILL_DEVELOPMENT.md) for registration vs local installation, immutable artifacts and rollback.
+
+## 5. Node, Endpoint and Tool capability catalog
+
+Counts follow public entrypoints, builds and descriptors, excluding helper functions, CLI aliases and example processes.
+Direct Tool support means provider/caller/Gateway implementation; data-plane Nodes may participate indirectly through
+existing providers. Optional-mode counts describe enabled provider capabilities, not default registration.
+
+| Repository | Production Nodes | Direct Tool role | Endpoints / operations |
+| --- | --- | --- | --- |
+| forge | 0 (library) | SPI, Wire, runners | No concrete business Endpoint |
+| adapter-camera-orbbec | 1 | None | 0 / 0; device enumeration/probe CLIs separate |
+| adapter-camera-realsense | 1 | None | 0 / 0; aliases do not add Nodes |
+| adapter-camera-usb | 1 | None | 0 / 0; test sink is auxiliary |
+| adapter-forge-gateway | 1 | Gateway | Own business Endpoints 0; routes/operations/Tools depend on configuration and registrations |
+| adapter-franka-fr3 | 1 | None | 0 / 0 |
+| adapter-robot-piper | 1 | None | 0 / 0 |
+| adapter-robot-so101 | 1 | None | 0 / 0; device-maintenance CLIs separate |
+| adapter-robot-xlerobot | 1 | None | 0 / 0 |
+| adapter-robot-zerith_h1_pro | 2 (robot, camera) | None | 0 / 0; compatibility aliases do not add Nodes |
+| adapter-viewer-image | 1 | None | 0 / 0 |
+| operator-controls | 2, plus fake plant | None | 0 / 0; Dora Action messages are not ToolEndpoint |
+| operator-gripper-action-policy | 1 | Provider | 1 / 1: gripper.controller / set_opening (Action) |
+| operator-kai0 | 1 | Optional provider | 1 / 1: policy.runner / serve (Session); mode=session_endpoint |
+| operator-lerobot-runner | 1 | Optional provider | 1 / 1: policy.runner / serve (Session); mode=session_endpoint |
+| operator-motion | 2 | Policy Node is provider | 1 / 2: motion.server / move_joints, move_pose (Action) |
+| operator-relative-pose-policy | 1 | Provider | 1 / 1: motion.relative_pose / resolve (Query) |
+| operator-sim-control-policy | 1 | Provider + caller | 1 / 2: sim.control / get_robot_info (Query), reset (Action) |
+| operator-simulator-mujoco | 1 | None | 0 / 0; commands arrive via sim_command |
+| benchmark-libero | 1 | Optional provider | 1 / 2: benchmark.controller / describe (Query), run (Session); serve=true |
+
+Seven provider repositories plus Gateway directly implement Tool integration. Kai0 and LeRobot share `policy.runner`:
+they are deployment alternatives for one route, not automatically separate Endpoints in one Gateway.
+Each Endpoint ID has one current instance in the Gateway Directory.
+
+Current LIBERO serve source composes the Endpoint and benchmark loop in one Node. Its older README described
+an independent `bench_endpoint`, but the directory is absent from this snapshot, so it does not supply a second Node.
+See [main.py](https://github.com/PhyAgentOS/benchmark-libero/blob/e01cd66167b85522afe427c5b85da8af30c00c97/main.py)
+and [descriptor](https://github.com/PhyAgentOS/benchmark-libero/blob/e01cd66167b85522afe427c5b85da8af30c00c97/bench_tool/descriptor.py).
+
+These providers do not directly serve HTTP Tool APIs; Gateway owns the caller-facing Tool/Invocation routes.
+The pinned Gateway source has 10 such HTTP route templates, including Session stop, excluding other
+runtime/record/playback/WS APIs. See its [HTTP controller](https://github.com/PhyAgentOS/adapter-forge-gateway/blob/5aaa9d16aff1c1b689dbb53acbcdef406dcb8d97/src/forge_gateway/controllers/tool_controller.py).
+Check historical Skill binary capabilities using their locked versions.
+
+Required README fields/template: [development manual](SKILL_DEVELOPMENT.md#required-node-repository-readme-content).
diff --git a/docs/user_development_guide/track_b/REPOSITORIES_zh.md b/docs/user_development_guide/track_b/REPOSITORIES_zh.md
new file mode 100644
index 000000000..0ed688c05
--- /dev/null
+++ b/docs/user_development_guide/track_b/REPOSITORIES_zh.md
@@ -0,0 +1,147 @@
+# TrackB 仓库目录与代码组成
+
+[English](REPOSITORIES.md) | [简体中文](REPOSITORIES_zh.md)
+
+[整体架构](README_zh.md) · [仓库目录](REPOSITORIES_zh.md) · [公共协议](PROTOCOLS_zh.md) · [Runtime 关系](RUNTIME_zh.md) · [Skill 开发](SKILL_DEVELOPMENT_zh.md)
+
+## 1. 范围与定位
+
+本页索引本次迁移涉及的 20 个公开代码仓库:10 个 Adapter、8 个 Operator、Forge 基础库和
+1 个 benchmark;另列出 Forgelab-Robotics 的组织配置 `.github`。它不是 PhyAgentOS 组织全部项目的清单。
+Core 的任务与 Skill 生命周期代码位于 [本仓源码](../../../PhyAgentOS),与这些节点仓库分层维护。
+
+目录链接指向当前仓库;提交链接固定源码核查快照。职责分类不代表各节点都已在同一 Skill 中集成,
+也不表示所有平台、语言或硬件能力均已验收。
+
+## 2. 分类索引
+
+### 2.1 基础框架
+
+| 类别 | 当前仓库源码 | 描述 / 主要内容 | 核查提交 |
+| --- | --- | --- | --- |
+| 基础库 | [forge](https://github.com/PhyAgentOS/forge) | Common、Msgs、Robot、Policy、Kinematics、Tool;跨语言消息与接口 | [e59693910bb5](https://github.com/PhyAgentOS/forge/tree/e59693910bb5f9572cf39c5a59475c0747ba76e8) |
+
+### 2.2 Adapter:对外边界
+
+| 类别 | 当前仓库源码 | 描述 / 主要内容 | 核查提交 |
+| --- | --- | --- | --- |
+| Adapter · Sensor | [adapter-camera-orbbec](https://github.com/PhyAgentOS/adapter-camera-orbbec) | Orbbec 彩色/深度/IR/可选点云采集、设备初始化和发布 | [de3cbc536153](https://github.com/PhyAgentOS/adapter-camera-orbbec/tree/de3cbc5361533d8799f586939266289d7527b203) |
+| Adapter · Sensor | [adapter-camera-realsense](https://github.com/PhyAgentOS/adapter-camera-realsense) | RealSense D400 彩色/深度/IR/可选点云采集与发布 | [77627b4d8e39](https://github.com/PhyAgentOS/adapter-camera-realsense/tree/77627b4d8e3977aabf016af6846e9f6857cfcde6) |
+| Adapter · Sensor | [adapter-camera-usb](https://github.com/PhyAgentOS/adapter-camera-usb) | Rust/V4L2 USB 相机;raw/压缩图像与设备检查 | [bdbe5ebb016d](https://github.com/PhyAgentOS/adapter-camera-usb/tree/bdbe5ebb016da299ff1e0b461260ce1ddd52d234) |
+| Adapter · Gateway | [adapter-forge-gateway](https://github.com/PhyAgentOS/adapter-forge-gateway) | HTTP/WebSocket 外部接口、Tool 路由、Registry 和就绪状态 | [5aaa9d16aff1](https://github.com/PhyAgentOS/adapter-forge-gateway/tree/5aaa9d16aff1c1b689dbb53acbcdef406dcb8d97) |
+| Adapter · Robot | [adapter-franka-fr3](https://github.com/PhyAgentOS/adapter-franka-fr3) | Franka FR3v2 与 Franka Hand 驱动及模型 | [efd7a6bd019c](https://github.com/PhyAgentOS/adapter-franka-fr3/tree/efd7a6bd019c7135ae506274ca73ef5879f4a384) |
+| Adapter · Robot | [adapter-robot-piper](https://github.com/PhyAgentOS/adapter-robot-piper) | AgileX Piper 真机驱动、Dora 示例与多格式机器人模型 | [3ea5156cb369](https://github.com/PhyAgentOS/adapter-robot-piper/tree/3ea5156cb369c302bb2e3ff6f1ebfb6af90a08d8) |
+| Adapter · Robot | [adapter-robot-so101](https://github.com/PhyAgentOS/adapter-robot-so101) | SO101 串口/Feetech 驱动、设备工具和 MJCF 模型 | [fb6b59292366](https://github.com/PhyAgentOS/adapter-robot-so101/tree/fb6b59292366059acd10cb2439d155c4c8015cfc) |
+| Adapter · Robot | [adapter-robot-xlerobot](https://github.com/PhyAgentOS/adapter-robot-xlerobot) | XLeRobot 双臂轮式机器人适配、配置和模型 | [5ceb37fdea4d](https://github.com/PhyAgentOS/adapter-robot-xlerobot/tree/5ceb37fdea4d6c7e454914b1b5e180b4728ef0fa) |
+| Adapter · Robot | [adapter-robot-zerith_h1_pro](https://github.com/PhyAgentOS/adapter-robot-zerith_h1_pro) | Zerith H1 Pro 关节/底盘适配、SDK 集成与示例 | [e36dc9b0bdfd](https://github.com/PhyAgentOS/adapter-robot-zerith_h1_pro/tree/e36dc9b0bdfd68342d55180485b561c73162cfc3) |
+| Adapter · Viewer | [adapter-viewer-image](https://github.com/PhyAgentOS/adapter-viewer-image) | 图像显示窗口,消费 Forge 图像消息 | [ea5900a7225c](https://github.com/PhyAgentOS/adapter-viewer-image/tree/ea5900a7225c2bfadd89bbfe23c023ec9fbe1bb6) |
+
+### 2.3 Operator:图内计算
+
+| 类别 | 当前仓库源码 | 描述 / 主要内容 | 核查提交 |
+| --- | --- | --- | --- |
+| Operator · Control | [operator-controls](https://github.com/PhyAgentOS/operator-controls) | joint_trajectory_controller、gripper_action_controller 与 fake plant | [cde73dc2a622](https://github.com/PhyAgentOS/operator-controls/tree/cde73dc2a6222d81b01ffc32f69f12cb12e42760) |
+| Operator · Policy | [operator-gripper-action-policy](https://github.com/PhyAgentOS/operator-gripper-action-policy) | 将 Tool 夹爪请求转换为 gripper action 并返回执行结果 | [bb69223497b9](https://github.com/PhyAgentOS/operator-gripper-action-policy/tree/bb69223497b944dd1a0f6fe9ecb36486168a8cc4) |
+| Operator · Policy | [operator-kai0](https://github.com/PhyAgentOS/operator-kai0) | kai0 策略源码、推理运行与节点发布 | [94baa639fe6d](https://github.com/PhyAgentOS/operator-kai0/tree/94baa639fe6d36bb5d41d214923108993aa002cc) |
+| Operator · Policy | [operator-lerobot-runner](https://github.com/PhyAgentOS/operator-lerobot-runner) | LeRobot 策略运行、观测与控制流程 | [f6b26f4f89bb](https://github.com/PhyAgentOS/operator-lerobot-runner/tree/f6b26f4f89bbd9831f64e3fc43d36499d6c86a92) |
+| Operator · Motion | [operator-motion](https://github.com/PhyAgentOS/operator-motion) | motion_server、motion_action_policy;运动目标、IK 和轨迹生成 | [24c8a430715f](https://github.com/PhyAgentOS/operator-motion/tree/24c8a430715f697eea8431bf169c21b8cbb5eb92) |
+| Operator · Policy | [operator-relative-pose-policy](https://github.com/PhyAgentOS/operator-relative-pose-policy) | 相对末端位姿解析与 motion.relative_pose 工具接入 | [4749b696a8b3](https://github.com/PhyAgentOS/operator-relative-pose-policy/tree/4749b696a8b3210e193860d6aeed92382fbad113) |
+| Operator · Policy | [operator-sim-control-policy](https://github.com/PhyAgentOS/operator-sim-control-policy) | 机器人 descriptor 查询、仿真复位与延迟 re-home | [85679a4be895](https://github.com/PhyAgentOS/operator-sim-control-policy/tree/85679a4be8953e9071de426c7c0973155121d96f) |
+| Operator · Simulator | [operator-simulator-mujoco](https://github.com/PhyAgentOS/operator-simulator-mujoco) | MuJoCo 状态推进、关节命令、图像和状态输出 | [0a84a1a81807](https://github.com/PhyAgentOS/operator-simulator-mujoco/tree/0a84a1a81807b467338e696032a38b084cb35747) |
+
+### 2.4 Benchmark 与组织配置
+
+| 类别 | 当前仓库源码 | 描述 / 主要内容 | 核查提交 |
+| --- | --- | --- | --- |
+| 组织配置 | [.github](https://github.com/Forgelab-Robotics/.github) | 组织 profile 和公共介绍;已转回 Forgelab-Robotics | [2df5cc313ca9](https://github.com/Forgelab-Robotics/.github/tree/2df5cc313ca9193d6ceb75b87a85e77072d9d1aa) |
+| Benchmark | [benchmark-libero](https://github.com/PhyAgentOS/benchmark-libero) | LIBERO 仿真/基准运行与节点发布;按实际节点职责归类,不新增第三类节点 | [e01cd66167b8](https://github.com/PhyAgentOS/benchmark-libero/tree/e01cd66167b85522afe427c5b85da8af30c00c97) |
+
+### 2.5 forge 仓库内部的六个家族
+
+| 家族 | 主要目录 | 提供的能力 |
+| --- | --- | --- |
+| Common | `packages/common`、`crates/forge_common`、`cpp/forge_common` | 日志、tracing、公共工具及可选发布/接收观测 |
+| Msgs | `interfaces/forge_msgs`、`packages/msgs`、`crates/forge_msgs`、`cpp/forge_msgs` | 权威 schema、消息模型与 Arrow 序列化 |
+| Robot | `packages/robot`、`cpp/forge_robot` | 驱动接口、关节限制辅助、可选标准 Dora runner |
+| Policy | `packages/policy` | 策略插件接口、观测缓存与标准 Operator loop |
+| Kinematics | `packages/kinematics` | URDF FK、Jacobian 和 IK 辅助 |
+| Tool | `interfaces/forge_tool`、`packages/tool` | Endpoint SPI、Wire 模型、handler 与 carrier binding |
+
+六家族是框架能力划分,不是必须启动的六个进程。语言覆盖和版本发布按各家族说明核对,
+不能把 Python、Rust、C++ 目录存在等同于所有接口均同等实现。
+
+## 3. robot-control-sim 的 Node 与源码映射
+
+| Skill lock 中的 Node | 源码仓库 | 源码入口 |
+| --- | --- | --- |
+| `gateway` | [adapter-forge-gateway](https://github.com/PhyAgentOS/adapter-forge-gateway) | [README.md](https://github.com/PhyAgentOS/adapter-forge-gateway/blob/5aaa9d16aff1c1b689dbb53acbcdef406dcb8d97/README.md) |
+| `sim_control_policy` | [operator-sim-control-policy](https://github.com/PhyAgentOS/operator-sim-control-policy) | [README.md](https://github.com/PhyAgentOS/operator-sim-control-policy/blob/85679a4be8953e9071de426c7c0973155121d96f/README.md) |
+| `motion_server / motion_action_policy` | [operator-motion](https://github.com/PhyAgentOS/operator-motion) | [packages/motion_server](https://github.com/PhyAgentOS/operator-motion/tree/24c8a430715f697eea8431bf169c21b8cbb5eb92/packages/motion_server) |
+| `joint_trajectory_controller` | [operator-controls](https://github.com/PhyAgentOS/operator-controls) | [packages/joint_trajectory_controller](https://github.com/PhyAgentOS/operator-controls/tree/cde73dc2a6222d81b01ffc32f69f12cb12e42760/packages/joint_trajectory_controller) |
+| `gripper_action_controller` | [operator-controls](https://github.com/PhyAgentOS/operator-controls) | [packages/gripper_action_controller](https://github.com/PhyAgentOS/operator-controls/tree/cde73dc2a6222d81b01ffc32f69f12cb12e42760/packages/gripper_action_controller) |
+| `gripper_action_policy` | [operator-gripper-action-policy](https://github.com/PhyAgentOS/operator-gripper-action-policy) | [README.md](https://github.com/PhyAgentOS/operator-gripper-action-policy/blob/bb69223497b944dd1a0f6fe9ecb36486168a8cc4/README.md) |
+| `mujoco_sim` | [operator-simulator-mujoco](https://github.com/PhyAgentOS/operator-simulator-mujoco) | [src/mujoco_sim](https://github.com/PhyAgentOS/operator-simulator-mujoco/tree/0a84a1a81807b467338e696032a38b084cb35747/src/mujoco_sim) |
+| `image_viewer` | [adapter-viewer-image](https://github.com/PhyAgentOS/adapter-viewer-image) | [README.md](https://github.com/PhyAgentOS/adapter-viewer-image/blob/ea5900a7225c2bfadd89bbfe23c023ec9fbe1bb6/README.md) |
+
+该表是实现位置映射,不是二进制构建来源证明。demo 的原始 artifact ID/version/SHA256 从安装后的
+`skill.yaml` 继承;若要自行构建替换,必须发布自己的版本及摘要并重新验收。
+
+同一个 `operator-motion` 仓库提供 motion server 和 motion action policy;
+`operator-controls` 提供两个 controller。因此,本例的九个 Node 来自七个仓库,仓库数量不等于进程数量。
+Gateway 的 Endpoint 路由与 Node ID 对照见 [实际运行关系](RUNTIME_zh.md#4-robot-control-sim-的实际组装)。
+
+## 4. 迁移后维护
+
+- 源码索引使用迁移后的 PhyAgentOS URL;`.github` 使用其实际所属 Forgelab-Robotics URL。
+- 组织迁移保留仓库名、源码身份和既有发布资产;包名、artifact ID、tag、归档摘要不因 owner 改变而升级。
+- 对旧代码仓库和 Release 地址实际检查兼容入口;不要重新占用已转移代码仓库的旧路径。
+- 下一次发布前,维护者核对 CI 凭据、包仓库权限、webhook 和分支保护,不能仅凭 transfer 判断构建发布权限已验证。
+- 资源目录或数据库登记要按目标平台的流程单独完成;GitHub 转移不自动更新消费者 Registry。
+- Dora/Forge 协议升级使用新的 Node/Skill 版本;跨仓修改前先核对 [公共协议](PROTOCOLS_zh.md) 和依赖锁。
+
+资源登记与本地安装的区别,以及不可变制品与回退方式,见 [Skill 开发手册](SKILL_DEVELOPMENT_zh.md)。
+
+## 5. Node、Endpoint 与 Tool 能力清单
+
+以下按公开源码入口、构建配置和 descriptor 分类,不把仓库中的工具函数、CLI 别名或示例进程计为生产 Node。
+这里的 Tool 支持指直接实现 provider/caller/Gateway;数据平面 Node 可以通过已有 provider 间接参与 Tool 执行。
+对可选模式,Endpoint 数和 operation 数均指启用 provider 后的能力,不代表默认会注册。
+
+| 仓库 | 生产 Node 数 | 直接 Tool 角色 | Endpoint / operation 数与范围 |
+| --- | --- | --- | --- |
+| forge | 0(基础库) | SPI、Wire、runner | 无具体业务 Endpoint |
+| adapter-camera-orbbec | 1 | 无 | 0 / 0;设备列举/探测 CLI 另计 |
+| adapter-camera-realsense | 1 | 无 | 0 / 0;命令别名不重复计数 |
+| adapter-camera-usb | 1 | 无 | 0 / 0;test sink 为辅助程序 |
+| adapter-forge-gateway | 1 | Gateway | 自有业务 Endpoint 0;路由/operation/Tool 数按配置与当前注册决定 |
+| adapter-franka-fr3 | 1 | 无 | 0 / 0 |
+| adapter-robot-piper | 1 | 无 | 0 / 0 |
+| adapter-robot-so101 | 1 | 无 | 0 / 0;设备维护 CLI 另计 |
+| adapter-robot-xlerobot | 1 | 无 | 0 / 0 |
+| adapter-robot-zerith_h1_pro | 2(robot、camera) | 无 | 0 / 0;兼容命令别名不重复计数 |
+| adapter-viewer-image | 1 | 无 | 0 / 0 |
+| operator-controls | 2(另有 fake plant) | 无 | 0 / 0;Dora Action 消息不等于 ToolEndpoint |
+| operator-gripper-action-policy | 1 | provider | 1 / 1:gripper.controller / set_opening(Action) |
+| operator-kai0 | 1 | 可选 provider | 1 / 1:policy.runner / serve(Session);mode=session_endpoint |
+| operator-lerobot-runner | 1 | 可选 provider | 1 / 1:policy.runner / serve(Session);mode=session_endpoint |
+| operator-motion | 2 | policy Node 为 provider | 1 / 2:motion.server / move_joints、move_pose(Action) |
+| operator-relative-pose-policy | 1 | provider | 1 / 1:motion.relative_pose / resolve(Query) |
+| operator-sim-control-policy | 1 | provider + caller | 1 / 2:sim.control / get_robot_info(Query)、reset(Action) |
+| operator-simulator-mujoco | 1 | 无 | 0 / 0;经 sim_command 接受命令 |
+| benchmark-libero | 1 | 可选 provider | 1 / 2:benchmark.controller / describe(Query)、run(Session);serve=true |
+
+七个 provider 仓库与 Gateway 是八个直接涉及 Tool 的仓库。Kai0 和 LeRobot 使用相同的
+`policy.runner` ID,是同一路由的部署候选;不是同一 Gateway 下天然独立的两个 Endpoint。
+每个 Endpoint ID 在 Gateway 当前目录中只有一个 current instance。
+
+LIBERO 当前源码的 serve 模式把 Endpoint 和 benchmark loop 放在同一个 Node;
+虽然旧 README 曾描述独立 `bench_endpoint`,当前源码树没有该目录,不能据此宣称提供第二个 Node。
+入口见 [main.py](https://github.com/PhyAgentOS/benchmark-libero/blob/e01cd66167b85522afe427c5b85da8af30c00c97/main.py),
+操作定义见 [descriptor](https://github.com/PhyAgentOS/benchmark-libero/blob/e01cd66167b85522afe427c5b85da8af30c00c97/bench_tool/descriptor.py)。
+
+这些 provider 不直接监听 HTTP Tool API,外部调用由 Gateway 的 Tool/Invocation 接口提供。
+Gateway 当前源码有 10 个此类 HTTP 路由模板(含 Session stop),不含其他 runtime/record/playback/WS 接口;
+见 [HTTP controller](https://github.com/PhyAgentOS/adapter-forge-gateway/blob/5aaa9d16aff1c1b689dbb53acbcdef406dcb8d97/src/forge_gateway/controllers/tool_controller.py)。
+历史 Skill 二进制的能力须按其锁定版本单独确认。
+
+后续仓库 README 的必填内容和模板见 [Skill 开发手册](SKILL_DEVELOPMENT_zh.md#node-仓库-readme-必填内容)。
diff --git a/docs/user_development_guide/track_b/RUNTIME.md b/docs/user_development_guide/track_b/RUNTIME.md
new file mode 100644
index 000000000..ab94e33ff
--- /dev/null
+++ b/docs/user_development_guide/track_b/RUNTIME.md
@@ -0,0 +1,296 @@
+# TrackB Runtime: Skill, Tool, Endpoint and Gateway
+
+[English](RUNTIME.md) | [简体中文](RUNTIME_zh.md)
+
+[Overview](README.md) · [Repositories](REPOSITORIES.md) · [Protocols](PROTOCOLS.md) · [Runtime](RUNTIME.md) · [Skill development](SKILL_DEVELOPMENT.md)
+
+This page explains logical responsibilities, then the public robot-control-sim 0.1.2 `mujoco-piper` deployment.
+This guide targets Core v1.1.1; the recorded example uses Core v1.1.0, Dora CLI 0.4.1 and original Node locks. See the
+[overview](README.md#5-architecture-versions-and-source-snapshots) for source/binary version boundaries.
+
+## 1. Three meanings of Runtime
+
+| Name | Layer / implementation | Managed concerns |
+| --- | --- | --- |
+| Skill Runtime | Core `RuntimeManager`, runtime environment, `RuntimeState` | Profile choice, artifact verification, Dora launch, readiness and stop |
+| Tool Runtime | Logical responsibility usually hosted by Gateway | Tool catalog, implementation selection, invocation/attempt, status/results |
+| Node / Dora runtime | Dora and Node processes | Port traffic, compute loops, device/simulator lifecycles |
+
+Tool Runtime does not require another process named runtime; Skill Runtime is not a control algorithm.
+AgentTask manages goals, bindings, evidence and verdicts without replacing Gateway/provider execution facts.
+
+## 2. Logical architecture and relationships
+
+### 2.1 From Agent to executor
+
+```mermaid
+flowchart LR
+ A["External Agent / application"]
+ C["Core: Skill workflows and AgentTask"]
+ subgraph G["Gateway Adapter"]
+ API["Caller API"]
+ CAT["Logical ToolSpec catalog"]
+ RT["Tool Runtime: invocation and implementation selection"]
+ ROUTER["Endpoint Registry and routing"]
+ API --> CAT
+ API --> RT
+ CAT --> RT
+ RT --> ROUTER
+ end
+ subgraph P["Provider: Operator or Adapter Node"]
+ B["Carrier binding / Endpoint handler"]
+ E["ToolEndpoint operation"]
+ X["Algorithm, device or downstream Action execution"]
+ B --> E --> X
+ end
+ A --> C
+ C <-->|"HTTP Tool API"| API
+ ROUTER <-->|"Low-frequency Endpoint Wire"| B
+ X <-->|"State, observations, commands, trajectories"| DATA["Dora data plane"]
+```
+
+A Tool is a stable caller-facing capability; Gateway bindings select an implementation and Endpoint operation.
+Endpoint is the provider's logical capability boundary, not an HTTP server, process name or repository.
+Caller HTTP and provider Wire are separate edges and need not share formats/fields.
+
+This diagram expresses responsibilities, not complete implementation by every published Gateway.
+The worked version uses Action `/tools/{tool_id}:invoke` and Query `/tools/{endpoint_id}/{operation}:invoke`,
+retaining Endpoint-directed Query URLs. Use the matching [Core Tool API contract](../../forge/README.md);
+do not describe the goal of hidden provider routing as functionality already present in every older API.
+
+Architecture: [Forge Tool architecture](https://github.com/PhyAgentOS/forge/blob/e59693910bb5f9572cf39c5a59475c0747ba76e8/interfaces/forge_tool/ARCHITECTURE.md).
+
+### 2.2 Definitions, deployment and capabilities
+
+```mermaid
+flowchart TB
+ S["Skill Bundle"] -->|"Contains workflow"| MD["SKILL.md"]
+ S -->|"Declares deployment"| MF["skill.yaml"]
+ MF -->|"Defines several"| PR["Profiles"]
+ MF -->|"Locks artifact identity and digest"| LOCK["Node artifacts"]
+ RUN["One Skill Runtime"] -->|"Chooses one"| PR
+ PR -->|"Specifies connections"| FLOW["dataflow.yaml"]
+ PR -->|"Declares required capabilities"| TOOLS["required_tools"]
+ FLOW -->|"Launches several"| N["Dora Node processes"]
+ LOCK -.->|"Provides executables"| N
+ N -->|"Some Nodes host"| EP["Endpoint / operations"]
+ GW["Gateway ToolSpec and routing"] -->|"Binds capabilities"| EP
+ TOOLS -->|"Matches tool_id"| GW
+ MD -->|"Guides Agent selection and invocation"| GW
+```
+
+| Object | Role | Example location |
+| --- | --- | --- |
+| Skill workflow | When to use capabilities, what to query and how to decide completion | `SKILL.md` |
+| Skill Bundle | Versioned deployment of workflow, profiles, models and dependency locks | `skill.yaml`, `profiles/`, `assets/` |
+| Profile | Robot, connections, parameters and environment within a Bundle | `profiles/mujoco-piper/` |
+| Tool / ToolSpec | Caller-visible ID, semantics, schemas, frames, readiness | `tools.specs` in `gateway.yaml` |
+| Endpoint operation | Provider query/start/status/result/cancel contract | Endpoint ID + operation + matching implementation |
+| Provider | Node hosting the Endpoint | motion/gripper/sim control policy |
+| Gateway | HTTP boundary, ToolSpec, provider routing and invocation state | `gateway` Node |
+| Dataflow | Node IDs, executable entrypoints, configuration and port connections | `dataflow.yaml` |
+
+An Endpoint may have multiple operations and multiple Tool bindings. Controllers, simulators and viewers
+may participate only in the data plane. Repository, binary entrypoint, Dora Node ID, Tool ID and Endpoint ID
+are different identities; do not infer one-to-one mapping from matching strings.
+
+Core `forge_tool_start_action` and related tools are generic Agent wrappers;
+`sim.move_eef` is a Skill's concrete Tool ID; `SKILL.md` is workflow documentation.
+These are three different concepts.
+
+## 3. Creating a Skill Runtime
+
+1. Acquire/validate the Skill Bundle and locked Node artifacts; install manifest/assets.
+2. Select a profile, prepare binary environments, materialize launch dataflow and configuration/asset references.
+3. `RuntimeManager` checks Dora, binaries, assets, environment and Gateway address, running Bundle `start.sh` when needed.
+4. Launch Dora with placeholders such as `${FORGE_RUNTIME_BIN}` bound to that environment.
+5. Inspect flow, Gateway and profile Tool context/readiness; record runtime state and Gateway identity.
+6. Activate workflow and create a bound task; recheck Skill/profile, Runtime identity, ToolSpec, allowlist and readiness when invoking.
+7. Stop according to active invocation/task binding rules; accepted cancellation does not prove execution has stopped.
+
+When present, `profiles..required_tools` overrides the top-level list for readiness and frozen task Tool allowlists.
+The same Skill name does not imply identical Tools across profiles. Core stores current RuntimeState per installed Skill;
+multiple profile definitions do not imply concurrent profiles for one Skill. Stop before switching and resolve
+port, device and display contention separately.
+
+Runtime and invocation identities are also layered:
+
+| Identity | Meaning |
+| --- | --- |
+| `runtime_instance_id` | This Core Skill Runtime instance |
+| `gateway_identity` | Bound Gateway service identity |
+| `endpoint_instance_id` | Provider registration instance, not static Endpoint ID |
+| `invocation_id` | Logical Gateway invocation |
+| `attempt_id` | Provider execution attempt |
+
+Task, Runtime, Gateway and provider identities are not interchangeable. An Endpoint with the same name
+after provider restart is not automatically the original execution instance.
+
+Implementation:
+[environment materialization](../../../PhyAgentOS/skill_runtime/installer.py),
+[RuntimeManager](../../../PhyAgentOS/skill_runtime/manager.py),
+[manifest/profiles](../../../PhyAgentOS/skill_runtime/manifest.py),
+[RuntimeState](../../../PhyAgentOS/skill_runtime/state.py),
+[task binding](../../../PhyAgentOS/forge/binding.py).
+
+## 4. Actual robot-control-sim assembly
+
+### 4.1 Configuration files
+
+Inspect the validated robot-control-sim 0.1.2 Bundle:
+
+```text
+robot-control-sim/
+├── SKILL.md
+├── skill.yaml
+├── profiles/mujoco-piper/
+│ ├── dataflow.yaml
+│ ├── gateway.yaml
+│ ├── sim_control_policy.yaml
+│ ├── motion_server.yaml
+│ ├── controller.yaml
+│ ├── gripper_controller.yaml
+│ ├── simulator.yaml
+│ └── image_viewer.yaml
+└── assets/robots/piper/...
+```
+
+`skill.yaml` locks nine Nodes. `mujoco-piper` requires nine binaries and Gateway
+`http://127.0.0.1:19002`, exposing five Tools rather than the top-level minimal two.
+`mujoco-franka` also exposes five; `mujoco-so101` omits `sim.set_gripper_opening` and runs seven Nodes.
+Nine artifact locks do not imply nine running processes in every profile.
+
+Piper X uses separate profile `mujoco-piper-x` and port `19104`; do not mix its group/frames with original Piper.
+See [PIPER_X_DEMO.md](../PIPER_X_DEMO.md).
+
+### 4.2 Five Tools, three Endpoints, three providers
+
+| Tool ID | Semantics | implementation_id | Endpoint / operation | Actual provider Node |
+| --- | --- | --- | --- | --- |
+| `sim.get_robot_info` | query | `sim.control` | `sim.control` / `get_robot_info` | `sim_control_policy` |
+| `sim.set_joint_positions` | action | `motion.integration` | `motion.server` / `move_joints` | `motion_action_policy` |
+| `sim.move_eef` | action | `motion.integration` | `motion.server` / `move_pose` | `motion_action_policy` |
+| `sim.set_gripper_opening` | action | `piper.gripper` | `gripper.controller` / `set_opening` | `gripper_action_policy` |
+| `sim.reset` | action | `sim.control` | `sim.control` / `reset` | `sim_control_policy` |
+
+`motion.server` is a logical Endpoint ID. Gateway first routes to `motion_action_policy`,
+not directly to the compute Node `motion_server`. `implementation_id` is not an executable filename either.
+
+The actual `gateway.yaml` provider routes are:
+
+```yaml
+tools:
+ providers:
+ - endpoint_id: sim.control
+ input_id: sim_tool_in
+ output_id: sim_tool_out
+ - endpoint_id: motion.server
+ input_id: action_tool_in
+ output_id: action_tool_out
+ - endpoint_id: gripper.controller
+ input_id: gripper_tool_in
+ output_id: gripper_tool_out
+```
+
+Inputs/outputs below are named from Gateway's perspective; dataflow chooses the peer:
+
+```yaml
+# Excerpt of dataflow.yaml, not an independently runnable graph.
+nodes:
+ - id: gateway
+ inputs:
+ action_tool_in: motion_action_policy/tool_out
+ outputs: [action_tool_out]
+ - id: motion_action_policy
+ inputs:
+ tool_in: gateway/action_tool_out
+ outputs: [tool_out]
+```
+
+### 4.3 Execution and state feedback
+
+```mermaid
+flowchart TB
+ C["Core / native diagnostic client"]
+ subgraph FLOW["mujoco-piper dataflow: 9 Nodes"]
+ G["gateway"]
+ G <-->|"sim_tool_out / sim_tool_in"| S["sim_control_policy"]
+ G <-->|"action_tool_out / action_tool_in"| P["motion_action_policy"]
+ G <-->|"gripper_tool_out / gripper_tool_in"| GP["gripper_action_policy"]
+ S <-->|"tool_request / tool_response: reuse other Tools"| G
+ P -->|"move_joints_goal / move_pose_goal"| M["motion_server"]
+ M -->|"trajectory_goal"| J["joint_trajectory_controller"]
+ GP -->|"gripper_goal"| GC["gripper_action_controller"]
+ J -->|"joint_command to action/arm"| SIM["mujoco: entrypoint mujoco_sim"]
+ GC -->|"joint_command to action/gripper"| SIM
+ S -->|"sim_command"| SIM
+ SIM -->|"proprio_state"| M
+ SIM -->|"proprio_state"| J
+ SIM -->|"proprio_state"| GC
+ SIM -->|"image/*"| V["image_viewer"]
+ J -.->|"trajectory_feedback / result"| M
+ M -.->|"move_joints or move_pose feedback / result"| P
+ GC -.->|"gripper_feedback / result"| GP
+ end
+ C <-->|"HTTP Tool API"| G
+```
+
+Timers/cancel ports are omitted; main command/state/result directions are shown. Joint and end-effector
+modes share motion server -> trajectory controller -> MuJoCo; the entry operation and URDF IK step differ.
+Images flow directly to Viewer, outside HTTP Tool requests.
+
+`sim.reset` does not write simulator state directly from Core. Sim-control policy uses `sim_command`
+and reuses Motion/Gripper Tools over `tool_request/tool_response` to restore the initial pose as configured.
+Sending reset and successfully re-homing are different events.
+
+### 4.4 One end-effector invocation
+
+```mermaid
+sequenceDiagram
+ participant C as Core / client
+ participant G as Gateway
+ participant P as motion_action_policy
+ participant M as motion_server
+ participant J as joint_trajectory_controller
+ participant S as MuJoCo
+ C->>G: GET Tool context / readiness
+ C->>G: POST /tools/sim.move_eef:invoke
+ G-->>C: 202 + invocation_id + attempt_id
+ G->>P: motion.server / move_pose
+ P->>M: move_pose_goal
+ M->>M: Validate group/frame, solve IK, generate trajectory
+ M->>J: trajectory_goal
+ loop Trajectory execution and state feedback
+ J->>S: JointCommand
+ S-->>J: JointState
+ S-->>M: JointState
+ end
+ J-->>M: trajectory_result
+ M-->>P: move_pose_result
+ P-->>G: Tool execution result
+ C->>G: GET invocation status, then result
+ G-->>C: Terminal result and residuals
+```
+
+Gateway admission and provider dispatch are asynchronous; HTTP 202 does not mean arrival.
+Native diagnostics wait for `phase=completed`, then inspect `data.result.status=succeeded`,
+motion `error_code=SUCCESS` and position/orientation residuals. AgentTask adds independent verification
+and verdicts: execution success alone is not task verification success. Timeout, accepted cancel or unknown
+must not trigger blind motion resubmission.
+
+Original Piper uses group `piper_arm`, reference frame `arm_base`, target frame `tcp`.
+Query `sim.get_robot_info` and Tool context first; do not substitute Piper X `piper_x_arm` / `base_link`.
+
+## 5. Following configuration into source
+
+| Responsibility | Implementation |
+| --- | --- |
+| Gateway HTTP/provider routing | [adapter-forge-gateway](https://github.com/PhyAgentOS/adapter-forge-gateway/blob/5aaa9d16aff1c1b689dbb53acbcdef406dcb8d97/README.md) |
+| Motion Tool provider and compute Node | [policy_nodes.py](https://github.com/PhyAgentOS/operator-motion/blob/24c8a430715f697eea8431bf169c21b8cbb5eb92/packages/motion_server/src/forge_motion_server/policy_nodes.py), [server.py](https://github.com/PhyAgentOS/operator-motion/blob/24c8a430715f697eea8431bf169c21b8cbb5eb92/packages/motion_server/src/forge_motion_server/server.py) |
+| Simulation descriptor/reset orchestration | [sim-control runner](https://github.com/PhyAgentOS/operator-sim-control-policy/blob/85679a4be8953e9071de426c7c0973155121d96f/src/sim_control_policy_node/runner.py) |
+| Gripper Tool provider | [gripper_action_policy runner](https://github.com/PhyAgentOS/operator-gripper-action-policy/blob/bb69223497b944dd1a0f6fe9ecb36486168a8cc4/src/gripper_action_policy_node/runner.py) |
+| Controllers, simulator, viewer | [Node source mapping](REPOSITORIES.md#3-robot-control-sim-node-to-source-mapping) |
+| Core HTTP client and Agent wrappers | [ForgeToolClient](../../../PhyAgentOS/forge/tool_client.py), [Agent tools](../../../PhyAgentOS/agent/tools/forge_tool_api.py) |
+
+This table locates responsibilities; Release/build provenance must establish any source-to-historical-binary mapping.
+For Node publication and Skill lock updates, see the [development manual](SKILL_DEVELOPMENT.md).
diff --git a/docs/user_development_guide/track_b/RUNTIME_zh.md b/docs/user_development_guide/track_b/RUNTIME_zh.md
new file mode 100644
index 000000000..5e897562d
--- /dev/null
+++ b/docs/user_development_guide/track_b/RUNTIME_zh.md
@@ -0,0 +1,297 @@
+# TrackB Runtime:Skill、Tool、Endpoint 与 Gateway
+
+[English](RUNTIME.md) | [简体中文](RUNTIME_zh.md)
+
+[整体架构](README_zh.md) · [仓库目录](REPOSITORIES_zh.md) · [公共协议](PROTOCOLS_zh.md) · [Runtime 关系](RUNTIME_zh.md) · [Skill 开发](SKILL_DEVELOPMENT_zh.md)
+
+本文先说明逻辑职责,再按公开 `robot-control-sim` 0.1.2 的 `mujoco-piper` profile 解释实际组装。
+本指南面向 Core v1.1.1;历史实例使用 Core v1.1.0、Dora CLI 0.4.1 及原始 Node locks;最新 Forge 源码与旧二进制的版本边界见
+[总览](README_zh.md#5-理论边界实现版本与源码快照)。
+
+## 1. 先区分三个 Runtime 含义
+
+| 名称 | 所属层 / 实现位置 | 管理什么 |
+| --- | --- | --- |
+| Skill Runtime | Core 的 `RuntimeManager`、运行环境和 `RuntimeState` | 选 profile、核对制品、启动 Dora flow、等待就绪和停止 |
+| Tool Runtime | 通常由 Gateway 承载的逻辑职责 | Tool 目录、实现选择、invocation/attempt、状态与结果 |
+| Node / Dora 运行环境 | Dora 和各节点进程 | 端口收发、计算循环、设备/模拟器生命周期 |
+
+Tool Runtime 不要求另起一个叫 runtime 的进程;Skill Runtime 也不是一个控制算法。
+Core 任务层的 AgentTask 管理目标、绑定、证据和 verdict,不替代 Gateway/provider 的执行事实。
+
+## 2. 理论架构与对象关系
+
+### 2.1 从 Agent 到执行者的逻辑边界
+
+```mermaid
+flowchart LR
+ A["外部 Agent / 应用"]
+ C["Core:Skill 工作流与 AgentTask"]
+ subgraph G["Gateway Adapter"]
+ API["调用者 API"]
+ CAT["逻辑 ToolSpec 目录"]
+ RT["Tool Runtime:invocation 与实现选择"]
+ ROUTER["Endpoint Registry 与路由"]
+ API --> CAT
+ API --> RT
+ CAT --> RT
+ RT --> ROUTER
+ end
+ subgraph P["Provider:Operator 或 Adapter 节点"]
+ B["Carrier binding / Endpoint handler"]
+ E["ToolEndpoint operation"]
+ X["算法、设备或下游动作执行"]
+ B --> E --> X
+ end
+ A --> C
+ C <-->|"HTTP Tool API"| API
+ ROUTER <-->|"低频 Endpoint Wire"| B
+ X <-->|"状态、观测、命令、轨迹"| DATA["Dora 数据平面"]
+```
+
+理论上,Tool 是对调用者稳定的能力入口,Gateway 的内部绑定把它映射到实现与 Endpoint operation。
+Endpoint 是 provider 提供能力的逻辑边界,不等于 HTTP 服务、进程名或源码仓库。
+外部调用协议与 provider Wire 是两条边;它们不要求使用相同数据格式或字段。
+
+本图描述职责,不承诺每个已发布 Gateway 版本都完整实现目标架构。
+本例实际 API 为 Action 的 `/tools/{tool_id}:invoke` 和 Query 的
+`/tools/{endpoint_id}/{operation}:invoke`,仍保留 Endpoint 定向的 Query 路径。
+应按匹配版本的 [Core Tool API 契约](../../forge/README_zh.md) 调用,
+不把“隐藏 provider 路由”的目标边界误写成旧 API 已具备的全部行为。
+
+架构依据:[Forge Tool architecture](https://github.com/PhyAgentOS/forge/blob/e59693910bb5f9572cf39c5a59475c0747ba76e8/interfaces/forge_tool/ARCHITECTURE.md)。
+
+### 2.2 定义、部署和能力之间的关系
+
+```mermaid
+flowchart TB
+ S["Skill Bundle"] -->|"包含工作流"| MD["SKILL.md"]
+ S -->|"声明部署"| MF["skill.yaml"]
+ MF -->|"定义多个"| PR["Profiles"]
+ MF -->|"锁定制品身份和摘要"| LOCK["Node artifacts"]
+ RUN["一次 Skill Runtime"] -->|"选择一个"| PR
+ PR -->|"指定连接图"| FLOW["dataflow.yaml"]
+ PR -->|"声明所需能力"| TOOLS["required_tools"]
+ FLOW -->|"启动多个"| N["Dora Node 进程"]
+ LOCK -.->|"提供可执行文件"| N
+ N -->|"部分节点承载"| EP["Endpoint / operations"]
+ GW["Gateway ToolSpec 与路由"] -->|"绑定能力"| EP
+ TOOLS -->|"按 tool_id 对应"| GW
+ MD -->|"指导 Agent 选择和调用"| GW
+```
+
+| 对象 | 作用 | 本例位置 |
+| --- | --- | --- |
+| Skill 工作流 | 告诉 Agent 何时使用能力、先查什么、如何判断完成 | `SKILL.md` |
+| Skill Bundle | 把工作流、profile、模型和依赖锁作为版本化部署单元 | `skill.yaml`、`profiles/`、`assets/` |
+| Profile | 同一 Bundle 下的一组机器人、连接、参数和环境选择 | `profiles/mujoco-piper/` |
+| Tool / ToolSpec | 调用者可见的能力名、语义、schema、frame 和 readiness | `gateway.yaml` 中 `tools.specs` |
+| Endpoint operation | provider 实现的 query/start/status/result/cancel 等契约 | Endpoint ID + operation + 匹配版本实现 |
+| Provider | 实际承载 Endpoint 的节点 | motion/gripper/sim control policy |
+| Gateway | HTTP 边界、ToolSpec、provider 路由与调用状态 | `gateway` 节点 |
+| Dataflow | 节点 ID、可执行入口、配置文件及端口连接 | `dataflow.yaml` |
+
+一个 Endpoint 可以有多个 operation,多个 Tool 可以映射到它。并非每个 Node 都需要暴露 Endpoint;
+控制器、模拟器和 Viewer 可以只参与数据平面。仓库、二进制 entrypoint、Dora node ID、Tool ID 和 Endpoint ID
+分别承担不同身份,不能按同名字符串猜测一一对应关系。
+
+Core 的 `forge_tool_start_action` 等工具是通用 Agent wrapper;`sim.move_eef` 等是该 Skill 暴露的
+具体 Tool ID;`SKILL.md` 是工作流文档。这三者也不能混为同一种“工具”。
+
+## 3. 一个 Skill Runtime 如何产生
+
+1. 获取并校验 Skill Bundle 和其锁定的 Node 制品,安装清单与资产。
+2. 选择 profile,准备所需 binary 的运行环境,物化 launch dataflow 和配置/资产引用。
+3. `RuntimeManager` 检查 Dora、binary、资产、环境及 Gateway 地址,按需运行 Bundle 的 `start.sh`。
+4. 启动 Dora flow,使 `${FORGE_RUNTIME_BIN}` 等占位符指向该运行环境。
+5. 核对 flow、Gateway 以及该 profile 的 Tool context/readiness,随后记录运行状态和 Gateway 身份。
+6. Agent 激活工作流并创建绑定任务;调用时复核 Skill/profile、Runtime 身份、ToolSpec、allowlist 和 readiness。
+7. 停止时按该 Runtime 的活动调用与任务绑定规则处理,不把取消已受理当作执行已停止。
+
+`profiles..required_tools` 若存在,会覆盖 Skill 顶层列表,既用于就绪检查,也影响冻结的任务 Tool allowlist。
+因此“同一 Skill 名称”不表示“所有 profile 暴露相同工具”。当前 Core 为每个已安装 Skill 保存当前 RuntimeState;
+不要从“可定义多个 profile”推断它支持同一 Skill 的多 profile 并发。切换前先停止当前 Runtime,
+并分别解决端口、设备和显示资源占用。
+
+运行与调用身份也分层管理:
+
+| Identity | 含义 |
+| --- | --- |
+| `runtime_instance_id` | Core 本次 Skill Runtime 实例 |
+| `gateway_identity` | 绑定到的 Gateway 服务身份 |
+| `endpoint_instance_id` | provider 注册实例,不是静态 Endpoint ID |
+| `invocation_id` | Gateway 逻辑调用 |
+| `attempt_id` | 对 provider 的一次执行尝试 |
+
+Task、Runtime、Gateway 和 provider 的身份不能互相替代;provider 重启后的同名 Endpoint
+不能仅凭字符串相同就被认作原来的执行实例。
+
+实现入口:
+[环境物化](../../../PhyAgentOS/skill_runtime/installer.py)、
+[RuntimeManager](../../../PhyAgentOS/skill_runtime/manager.py)、
+[manifest 与 profile](../../../PhyAgentOS/skill_runtime/manifest.py)、
+[RuntimeState](../../../PhyAgentOS/skill_runtime/state.py)、
+[任务绑定](../../../PhyAgentOS/forge/binding.py)。
+
+## 4. robot-control-sim 的实际组装
+
+### 4.1 从哪几个文件读出运行关系
+
+在取得已校验的 `robot-control-sim` 0.1.2 Bundle 后,查看:
+
+```text
+robot-control-sim/
+├── SKILL.md
+├── skill.yaml
+├── profiles/mujoco-piper/
+│ ├── dataflow.yaml
+│ ├── gateway.yaml
+│ ├── sim_control_policy.yaml
+│ ├── motion_server.yaml
+│ ├── controller.yaml
+│ ├── gripper_controller.yaml
+│ ├── simulator.yaml
+│ └── image_viewer.yaml
+└── assets/robots/piper/...
+```
+
+`skill.yaml` 锁定九个 Node;`mujoco-piper` profile 需要九个 binary,Gateway 地址为
+`http://127.0.0.1:19002`。它暴露五个 Tool,而不是清单顶层的两个最小 Tool。
+`mujoco-franka` 也暴露这五个 Tool;`mujoco-so101` 不暴露 `sim.set_gripper_opening`,dataflow 使用七个 Node。
+九个 artifact locks 不等于每个 profile 都启动九个进程。
+
+Piper X 派生示例另用 `mujoco-piper-x` 和端口 `19104`,不能与本节原始 Piper 的 group/frame 配置混用。
+派生过程见 [PIPER_X_DEMO.md](../PIPER_X_DEMO_zh.md)。
+
+### 4.2 五个 Tool、三个 Endpoint、三个 provider
+
+| Tool ID | Semantics | implementation_id | Endpoint / operation | 实际 provider node |
+| --- | --- | --- | --- | --- |
+| `sim.get_robot_info` | query | `sim.control` | `sim.control` / `get_robot_info` | `sim_control_policy` |
+| `sim.set_joint_positions` | action | `motion.integration` | `motion.server` / `move_joints` | `motion_action_policy` |
+| `sim.move_eef` | action | `motion.integration` | `motion.server` / `move_pose` | `motion_action_policy` |
+| `sim.set_gripper_opening` | action | `piper.gripper` | `gripper.controller` / `set_opening` | `gripper_action_policy` |
+| `sim.reset` | action | `sim.control` | `sim.control` / `reset` | `sim_control_policy` |
+
+这里的 `motion.server` 是逻辑 Endpoint ID;Gateway 先将请求交给 `motion_action_policy`,
+不是直接把 Endpoint 消息送进名为 `motion_server` 的计算节点。
+`implementation_id` 也不是可执行文件名。
+
+`gateway.yaml` 的实际 provider 路由为:
+
+```yaml
+tools:
+ providers:
+ - endpoint_id: sim.control
+ input_id: sim_tool_in
+ output_id: sim_tool_out
+ - endpoint_id: motion.server
+ input_id: action_tool_in
+ output_id: action_tool_out
+ - endpoint_id: gripper.controller
+ input_id: gripper_tool_in
+ output_id: gripper_tool_out
+```
+
+这些 input/output 名称属于 Gateway 视角,具体对端由 dataflow 决定。例如:
+
+```yaml
+# dataflow.yaml 节选;不是独立可启动的完整图。
+nodes:
+ - id: gateway
+ inputs:
+ action_tool_in: motion_action_policy/tool_out
+ outputs: [action_tool_out]
+ - id: motion_action_policy
+ inputs:
+ tool_in: gateway/action_tool_out
+ outputs: [tool_out]
+```
+
+### 4.3 实际执行与数据反馈图
+
+```mermaid
+flowchart TB
+ C["Core / 原生诊断客户端"]
+ subgraph FLOW["mujoco-piper dataflow:9 个节点"]
+ G["gateway"]
+ G <-->|"sim_tool_out / sim_tool_in"| S["sim_control_policy"]
+ G <-->|"action_tool_out / action_tool_in"| P["motion_action_policy"]
+ G <-->|"gripper_tool_out / gripper_tool_in"| GP["gripper_action_policy"]
+ S <-->|"tool_request / tool_response:复用其他 Tool"| G
+ P -->|"move_joints_goal / move_pose_goal"| M["motion_server"]
+ M -->|"trajectory_goal"| J["joint_trajectory_controller"]
+ GP -->|"gripper_goal"| GC["gripper_action_controller"]
+ J -->|"joint_command 到 action/arm"| SIM["mujoco:entrypoint 为 mujoco_sim"]
+ GC -->|"joint_command 到 action/gripper"| SIM
+ S -->|"sim_command"| SIM
+ SIM -->|"proprio_state"| M
+ SIM -->|"proprio_state"| J
+ SIM -->|"proprio_state"| GC
+ SIM -->|"image/*"| V["image_viewer"]
+ J -.->|"trajectory_feedback / result"| M
+ M -.->|"move_joints 或 move_pose feedback / result"| P
+ GC -.->|"gripper_feedback / result"| GP
+ end
+ C <-->|"HTTP Tool API"| G
+```
+
+图省略 timer 和 cancel 端口,保留主要命令、状态与结果方向。
+关节模式和末端模式共用 motion server → trajectory controller → MuJoCo 执行链;区别是入口 operation
+以及是否先做 URDF IK。图像直接进入 Viewer,不绕行 HTTP Tool 请求。
+
+`sim.reset` 不是在 Core 里直接写模拟器状态:sim-control policy 既连接 `sim_command`,
+也通过 `tool_request/tool_response` 路径复用运动和夹爪 Tool,按配置执行回到初始姿态的流程。
+“重置命令发出”和“回到初始姿态成功”不能等同。
+
+### 4.4 一次末端运动的调用过程
+
+```mermaid
+sequenceDiagram
+ participant C as Core / 客户端
+ participant G as Gateway
+ participant P as motion_action_policy
+ participant M as motion_server
+ participant J as joint_trajectory_controller
+ participant S as MuJoCo
+ C->>G: GET Tool context / readiness
+ C->>G: POST /tools/sim.move_eef:invoke
+ G-->>C: 202 + invocation_id + attempt_id
+ G->>P: motion.server / move_pose
+ P->>M: move_pose_goal
+ M->>M: 核对 group/frame,求 IK,生成轨迹
+ M->>J: trajectory_goal
+ loop 轨迹执行与状态反馈
+ J->>S: JointCommand
+ S-->>J: JointState
+ S-->>M: JointState
+ end
+ J-->>M: trajectory_result
+ M-->>P: move_pose_result
+ P-->>G: Tool 执行结果
+ C->>G: GET invocation status,再读 result
+ G-->>C: 终态结果与误差
+```
+
+Gateway admission 和 provider dispatch 是异步阶段;HTTP 202 不表示机器人已到位。
+原生诊断按 Gateway 的 `phase=completed` 终态读取 result,并检查
+`data.result.status=succeeded`、motion `error_code=SUCCESS` 及位置/方向残差。
+Core 的 AgentTask 还会在执行后完成独立验证并保存 verdict;执行成功不自动等于任务验证成功。
+超时、cancel accepted 或 unknown 不触发盲目重复运动。
+
+原始 Piper 的 motion group 为 `piper_arm`,reference frame 为 `arm_base`,target frame 为 `tcp`。
+先查询 `sim.get_robot_info` 并读取 Tool context,不能套用 Piper X 的 `piper_x_arm` / `base_link`。
+
+## 5. 从配置继续追到源码
+
+| 实际职责 | 实现入口 |
+| --- | --- |
+| Gateway HTTP 和 provider 路由 | [adapter-forge-gateway](https://github.com/PhyAgentOS/adapter-forge-gateway/blob/5aaa9d16aff1c1b689dbb53acbcdef406dcb8d97/README.md) |
+| motion Tool provider 与计算节点 | [policy_nodes.py](https://github.com/PhyAgentOS/operator-motion/blob/24c8a430715f697eea8431bf169c21b8cbb5eb92/packages/motion_server/src/forge_motion_server/policy_nodes.py)、[server.py](https://github.com/PhyAgentOS/operator-motion/blob/24c8a430715f697eea8431bf169c21b8cbb5eb92/packages/motion_server/src/forge_motion_server/server.py) |
+| 仿真 descriptor / reset 编排 | [sim-control runner](https://github.com/PhyAgentOS/operator-sim-control-policy/blob/85679a4be8953e9071de426c7c0973155121d96f/src/sim_control_policy_node/runner.py) |
+| gripper Tool provider | [gripper_action_policy runner](https://github.com/PhyAgentOS/operator-gripper-action-policy/blob/bb69223497b944dd1a0f6fe9ecb36486168a8cc4/src/gripper_action_policy_node/runner.py) |
+| controller、模拟器和 Viewer | [Node 源码映射](REPOSITORIES_zh.md#3-robot-control-sim-的-node-与源码映射) |
+| Core 的 HTTP client 与 Agent wrapper | [ForgeToolClient](../../../PhyAgentOS/forge/tool_client.py)、[Agent tools](../../../PhyAgentOS/agent/tools/forge_tool_api.py) |
+
+上表用于定位实现职责;固定源码快照与历史二进制的构建对应关系仍须由 Release/构建溯源证明。
+修改 Node 后重新发布和更新 Skill locks 的流程见 [Skill 开发手册](SKILL_DEVELOPMENT_zh.md)。
diff --git a/docs/user_development_guide/track_b/SKILL_DEVELOPMENT.md b/docs/user_development_guide/track_b/SKILL_DEVELOPMENT.md
new file mode 100644
index 000000000..a235cea39
--- /dev/null
+++ b/docs/user_development_guide/track_b/SKILL_DEVELOPMENT.md
@@ -0,0 +1,289 @@
+# TrackB Skill Development Manual
+
+[English](SKILL_DEVELOPMENT.md) | [简体中文](SKILL_DEVELOPMENT_zh.md)
+
+[Overview](README.md) · [Repositories](REPOSITORIES.md) · [Protocols](PROTOCOLS.md) · [Runtime](RUNTIME.md) · [Skill development](SKILL_DEVELOPMENT.md)
+
+Choose among three extension modes based on whether compatible Nodes already implement the target capability,
+then decide whether binaries must be rebuilt. The executable model/profile example is [PIPER_X_DEMO.md](../PIPER_X_DEMO.md).
+
+**Platform availability:** External resource submissions and changes to existing registered repositories are not yet open. They must wait for the approval service to be completed and opened. Current registration/publication is administrator-managed. Local development and validation can proceed; platform publication steps below are conditional on that workflow becoming available. See the [contribution guide](../../../CONTRIBUTING.md).
+
+## 1. Three development modes and difficulty
+
+| Mode | Typical goal | Main changes | Node artifacts | Difficulty and skills |
+| --- | --- | --- | --- | --- |
+| 1: Configure an existing profile | Initial state, control parameters, camera, allowed speed/tolerances | Existing YAML, related assets/docs | Usually preserve locks | Low: schemas, units, startup/debugging; still assess physical effects |
+| 2: Add a profile | Another robot/scene alongside existing choices | Profile, model/descriptor, manifest, Tool frames, workflow | Preserve locks when supported | Medium: kinematics, model conversion, joint/frame mapping, configuration consistency |
+| 3: Develop Nodes and assemble a Skill | New device protocol, algorithm, message capability or Tool | Source, tests, build/publication, dataflow, Skill | New versions/identities/digests | High: relevant Python/C++/Rust, Dora/Arrow, lifecycles and integration |
+
+Difficulty follows boundaries, not file count. Configuration can affect contact, stability or hardware;
+a new profile can reveal unsupported degrees of freedom/control modes, requiring mode three.
+
+```mermaid
+flowchart TD
+ Q["Can existing compatible Nodes implement the capability?"]
+ Q -->|"Yes"| P["Keep existing profiles and add a deployment choice?"]
+ P -->|"No"| M1["Mode 1: change an existing profile"]
+ P -->|"Yes"| M2["Mode 2: add a profile"]
+ Q -->|"No"| M3["Mode 3: develop Nodes, then assemble a Skill"]
+ M1 --> V["Package, install locally, validate native Tools"]
+ M2 --> V
+ M3 --> V
+ V --> R["Register, review/publish, then verify search and installation"]
+```
+
+## 2. Mode one: configure an existing profile
+
+### 2.1 Applicable scope
+
+Existing Nodes support the model/messages and the requested change fits their public configuration schemas:
+initial joint angles, camera output, controller gains or allowed Tool speed scales, for example.
+Unknown YAML keys do not add binary capabilities; relaxed tolerances must not hide model/frame errors.
+
+### 2.2 Procedure
+
+1. Pin baseline Skill/profile, Core/Dora and Node locks; first run the unchanged profile.
+2. Create an independent copy of the validated Bundle, preserving the original rather than editing a running/shared installation.
+3. Change target parameters and dependent configuration together: initial limits, gripper units, controller and descriptor must agree.
+4. If groups, frames, Tool bounds or asset locations change, update Gateway ToolSpec, required_assets and workflow documentation.
+5. Use your own Skill identity/new revision, package with the official script, stop the old Runtime and install locally.
+6. Check inspect, dependency digests, startup, Tool context, representative native Actions, failure handling and stop.
+7. Keep validation evidence locally; register/publish through the platform when sharing, without overwriting existing version assets.
+
+Example: the [Piper X configuration table](../PIPER_X_DEMO.md#42-configuration-changes) shows cross-file consistency;
+[native validation](../PIPER_X_DEMO.md#6-native-validation-of-both-control-modes) supplies checks after tuning.
+Full Piper X integration changes the model and exceeds parameter tuning; this mode reuses its configuration/validation procedure.
+
+## 3. Mode two: add a profile
+
+### 3.1 Goal and layout
+
+Keep profiles such as `mujoco-piper`, adding another entry to the Skill's `profiles` mapping:
+
+```text
+my-skill/
+├── skill.yaml
+├── SKILL.md
+├── profiles/
+│ ├── mujoco-piper/...
+│ └── mujoco-my-arm/...
+└── assets/robots/
+ ├── piper/...
+ └── my_arm/...
+```
+
+A profile is a deployment choice, not a Node type. Existing simulator, motion server, controller and
+Gateway/provider versions must collectively support the new dimensions, joint types, modes and state representation.
+
+### 3.2 Procedure
+
+1. Copy a suitable original profile into a new directory; preserve original profiles/assets and avoid editing installed files.
+2. Pin model source/revision/license; define logical joints, limits, initial pose, base and TCP.
+3. Convert URDF/MJCF and check FK/servo behavior, logical/physical gripper mapping and actuators.
+4. Update simulator, motion, controller, sim-control and Gateway configuration; verify paths, groups, frames, units and schemas.
+5. Keep/adapt port connections. Preserve immutable Node locks if binaries are unchanged; remove matching required_tools/binaries when removing capabilities.
+6. Register the complete profile in the manifest: dataflow, required_assets, required_binaries, required_tools and environment.
+7. Update robot selection/constraints in SKILL.md, increment Skill version, package/install and validate old and new profiles.
+8. Stop the current Runtime before switching; resolve port/device contention and validate dependencies, native motion and stop before registration.
+
+This is a profile fragment to add to `skill.yaml`, not a complete manifest; assets must exist.
+It assumes the existing six-axis-arm/parallel-gripper chain. Adapt it for other capabilities:
+
+```yaml
+profiles:
+ mujoco-my-arm:
+ dataflow: profiles/mujoco-my-arm/dataflow.yaml
+ required_tools:
+ - sim.get_robot_info
+ - sim.set_joint_positions
+ - sim.move_eef
+ - sim.set_gripper_opening
+ - sim.reset
+ required_binaries:
+ - gateway
+ - sim_control_policy
+ - motion_action_policy
+ - motion_server
+ - joint_trajectory_controller
+ - gripper_action_policy
+ - gripper_action_controller
+ - mujoco_sim
+ - image_viewer
+ required_assets:
+ - assets/robots/my_arm/robot.yaml
+ - assets/robots/my_arm/my_arm.urdf
+ - assets/robots/my_arm/mjcf/scene.xml
+ - assets/robots/my_arm/mjcf/my_arm.xml
+ required_environment: []
+ environment: {}
+```
+
+Keep existing `profiles`; do not replace the manifest with this fragment.
+`required_tools` overrides rather than appends the top-level list, so list every Tool required by this profile.
+`gateway_url` is Skill-level in the current manifest and must match the selected Gateway configuration.
+Concurrent deployments need explicit Skill/address/resource isolation; profiles alone are not concurrent instances.
+
+### 3.3 Reusing the Piper X example
+
+See [PIPER_X_DEMO.md](../PIPER_X_DEMO.md) for model/configuration steps and
+[another-arm checklist](../PIPER_X_DEMO.md#9-another-robot-and-deliverables).
+
+**The generator creates a separate `robot-control-sim-piper-x` Skill and keeps only its Piper X profile.**
+It illustrates profile internals, not automatic merging of a fourth profile beside three existing ones.
+For this mode, start from an unpruned upstream Bundle, integrate the model/profile as above and preserve old choices.
+The generator is Piper X-specific, not an arbitrary URDF importer; check its model transformations for another arm.
+
+## 4. Mode three: develop Nodes and assemble a Skill
+
+### 4.1 Interfaces and assembly
+
+Select source using the [catalog](REPOSITORIES.md), then define ports, fields, units, timing, errors,
+resource cleanup and cancellation according to [protocols](PROTOCOLS.md).
+External device integration is usually Adapter responsibility; graph computation is usually Operator responsibility.
+
+Two integration paths are available:
+
+- **Data-plane Node:** consumes/produces state, observations, trajectories or JointCommand; connect it to existing providers/controllers without adding an Endpoint.
+- **New callable capability:** implement an Endpoint operation, configure Gateway ToolSpec/provider routes and connect ToolMessage ports.
+
+A new Tool needs stable tool_id, semantics, input/output schemas, frames/units, readiness,
+operation concurrency and terminal results. Implement Query/Action/Session contracts individually;
+a Session field alone does not establish a compatible end-to-end Session implementation.
+
+### 4.2 Development and validation order
+
+1. Choose compatible Core/Gateway/Dora/Forge versions; pin locks, source branch and version.
+2. Separate deterministic algorithm/driver interfaces from Dora transport and Endpoint handling.
+3. Validate serialization, units and ports before ticks, resource lifecycle, timeout/cancel, reconnection and exceptional exit.
+4. Test algorithms with unit tests/fake plants; device integration needs device-level checks, not just imports/help.
+5. Build for the target OS/architecture; check entrypoint, dependencies, licenses and archive layout.
+6. Assemble Gateway configuration, dataflow, assets and manifest; align required_binaries/entrypoints and Tool allowlists/exposure.
+7. Update Skill locks using new Node identities/digests; validate local installation and the complete execution chain.
+8. Register Node and Skill resources separately; after required review/publication, validate consumer search and installation.
+
+The [Piper X demo](../PIPER_X_DEMO.md) covers Skill assembly and both motion modes while reusing original Nodes;
+it does not replace Node source development/testing. Current Forge 2.x source cannot be mixed directly into its older Dora 0.4 locks.
+
+Readable source helps inspect implementations/configuration; binary replacement additionally requires reproducible
+source/build/version correspondence. The operator-controls example below uses a catalog-pinned snapshot, not proof
+that its commit built the demo's historical binary. Align Dora, messages and related Nodes before replacement.
+
+### Required Node repository README content
+
+New or changed Node repositories must maintain a root capability summary alongside interface changes.
+Keep English `README.md` and Chinese `README_zh.md` separate with reciprocal links; synchronize interface facts,
+counts, examples and commands in the same change. Count production Nodes, Endpoints, operations and Gateway Tools
+separately; CLI aliases, offline utilities and fake plants are not production Nodes.
+
+| Required item | Content |
+| --- | --- |
+| Production Nodes | Count, names, source/CLI and packaged entrypoints; auxiliary programs separate |
+| Tool support | Data-plane only, provider, caller or Gateway; activation and default mode |
+| Endpoint | Count, endpoint_id, provider Node, descriptor source; 0 if absent |
+| Operation | Per-Endpoint count/names, Query/Action/Session, concurrency, lifecycle controls |
+| HTTP Tool API | Methods/paths and request/result contracts; 0 for non-HTTP providers, with Gateway reference |
+| Tool binding | tool_id -> endpoint_id / operation -> provider; explicitly configuration-dependent when appropriate |
+| Compatibility/build | Wire/schema versions, locks, configuration, build provenance and artifact boundaries |
+
+Suggested root README structure:
+
+```markdown
+## Node, Endpoint and Tool API
+
+| Item | Implementation |
+| --- | --- |
+| Production Nodes | |
+| Tool support | |
+| Endpoints | |
+| Operations | |
+| Direct HTTP Tool API | |
+| Gateway Tools | |
+
+
+```
+
+`gripper_action_policy` is one Node, one Endpoint and one Action operation. Downstream
+`gripper_action_controller` accepts Dora Action-shaped goals/feedback/results without implementing ToolEndpoint.
+`motion_action_policy` exposes two operations at one Endpoint; `motion_server` is a separate compute Node.
+Gateway owns zero business Endpoints, with deployment-defined routed Endpoints and Tools.
+
+Review against package scripts, build outputs, descriptors, handlers, ToolSpecs and dataflow,
+not directory names, class names or old READMEs. See the [capability catalog](REPOSITORIES.md#5-node-endpoint-and-tool-capability-catalog).
+
+### 4.3 Source build example
+
+Prepare Git, uv and Python 3.12 on target Linux x86_64:
+
+```bash
+git clone https://github.com/PhyAgentOS/operator-controls.git
+cd operator-controls
+git checkout cde73dc2a6222d81b01ffc32f69f12cb12e42760
+uv sync --frozen --all-groups
+uv run pytest -q
+bash scripts/build_pyinstaller.sh
+```
+
+The frozen-lock build recreates `.venv_build`, produces `dist/joint_trajectory_controller`,
+`dist/gripper_action_controller`, `dist/fake_joint_plant`, and checks help/argument errors.
+These checks do not replace cross-Node motion validation. Publish algorithm changes from a pinned source revision;
+the target must match the client, and macOS executables must not be labeled Linux artifacts.
+
+Source: [build script](https://github.com/PhyAgentOS/operator-controls/blob/cde73dc2a6222d81b01ffc32f69f12cb12e42760/scripts/build_pyinstaller.sh),
+[Ubuntu build environment](https://github.com/PhyAgentOS/operator-controls/blob/cde73dc2a6222d81b01ffc32f69f12cb12e42760/.github/workflows/build-ubuntu20.yml).
+
+### 4.4 Archives and build provenance
+
+An `executable_tar_gz` archive must contain the single executable named by entrypoint at its root:
+
+```bash
+# Example version: align it with your own source and release.
+FORGE_NODE_VERSION=0.1.1
+FORGE_NODE_ARCHIVE="joint_trajectory_controller-${FORGE_NODE_VERSION}-linux-x86_64.tar.gz"
+tar -C dist -czf "$FORGE_NODE_ARCHIVE" joint_trajectory_controller
+sha256sum "$FORGE_NODE_ARCHIVE"
+wc -c < "$FORGE_NODE_ARCHIVE"
+```
+
+For `directory_tar_gz`, retain the entrypoint-named root directory and its runtime tree.
+Do not confuse onefile and onedir layouts. Associate at least the following provenance with each release:
+
+| Information | Required check |
+| --- | --- |
+| Repository URL, full commit, tag | Identify actual build source; current default branch is not a substitute |
+| Build command, lock, OS/architecture | Rebuild/explain runtime dependencies; pin CI workflow revision |
+| Entrypoint, archive type | Match layout, executable permissions and installer rules |
+| Filename, bytes, archive SHA256 | Storage, Release, Registry metadata and consumer locks identify the same bytes |
+| Node name, version, artifact ID | New builds get new immutable identities, without overwriting old assets |
+| Licenses/notices | Include statements required by distributed binaries/dependencies |
+
+Update derived Skill `artifacts.nodes.` with the new artifact ID/version/SHA256, platform,
+archive type and entrypoint. Align dataflow Node IDs, binary placeholders and required_binaries;
+increment Skill version, repackage, install locally and validate with `forge-node verify` and native Tools.
+Rollback uses previous published immutable artifacts, not replacement bytes under the same version.
+
+## 5. Shared validation and delivery process
+
+| Stage | Facts to establish |
+| --- | --- |
+| Static consistency | Manifest/profiles parse; paths, units, groups, frames, Tools and binaries agree |
+| Model/algorithm checks | Scope-appropriate FK, limits, servo or unit tests; state coverage boundaries |
+| Packaging/local installation | Archive layout, size, SHA256, locks, entrypoint, inspect and verify |
+| Runtime | Profile startup, Tool context/readiness, representative native terminal results/residuals and stop |
+| Agent workflow | If needed: activation, task binding, finalize and verdict; native success is not independent verification |
+| Registration/review | Reuse matching existing Nodes; submit resource versions/dependencies/evidence through the platform |
+| After publication | Search/install with a compatible consumer API in an isolated instance, then inspect and verify every Node |
+
+GitHub push/Release, platform registration, technical validation, review/publication and Core installation
+are separate stages. Editing a static catalog does not establish registration in a new platform.
+Use the matching platform version's account/upload/review APIs; pending-review web entries are not necessarily downloadable.
+
+Keep source/model revisions, locks, Bundle/Node digests, build instructions and licenses for each version.
+State any missing source/binary provenance instead of substituting the newest default branch.
+Rollback restores previous immutable artifacts/locks without overwriting versioned archives.
+
+## 6. Further reading
+
+- [Piper X tutorial](../PIPER_X_DEMO.md): official model, profile, native joint/EEF Actions and stop commands.
+- [Runtime relationships](RUNTIME.md): five Tools, three Endpoints/providers and nine Nodes in robot-control-sim.
+- [Bundle and Tool integration reference](../README.md): manifest, ToolSpec, task binding and common validation contracts.
diff --git a/docs/user_development_guide/track_b/SKILL_DEVELOPMENT_zh.md b/docs/user_development_guide/track_b/SKILL_DEVELOPMENT_zh.md
new file mode 100644
index 000000000..8ecb08a3f
--- /dev/null
+++ b/docs/user_development_guide/track_b/SKILL_DEVELOPMENT_zh.md
@@ -0,0 +1,290 @@
+# TrackB Skill 开发手册
+
+[English](SKILL_DEVELOPMENT.md) | [简体中文](SKILL_DEVELOPMENT_zh.md)
+
+[整体架构](README_zh.md) · [仓库目录](REPOSITORIES_zh.md) · [公共协议](PROTOCOLS_zh.md) · [Runtime 关系](RUNTIME_zh.md) · [Skill 开发](SKILL_DEVELOPMENT_zh.md)
+
+本页区分三种二次开发模式。先根据现有 Node 是否支持目标能力选择改动范围,再决定是否重建二进制。
+模型/profile 的完整可执行示例见 [PIPER_X_DEMO.md](../PIPER_X_DEMO_zh.md)。
+
+**平台开放范围:** 外部贡献提交及已有登记仓库修改暂未开放,需等待审批服务完成并开放。当前登记与发布由管理员维护;可先进行本地开发验证。下文的平台发布步骤以相关流程开放为前提,详见[贡献指南](../../../CONTRIBUTING_zh.md)。
+
+## 1. 三种模式与难度
+
+| 模式 | 典型目标 | 主要改动 | Node 制品 | 相对难度与要求 |
+| --- | --- | --- | --- | --- |
+| 一:已有 profile 内配置调整 | 改初始状态、控制参数、相机、允许的速度/容差 | 既有 profile 的 YAML、相关资产或说明 | 通常继承原 locks | 低;理解配置 schema、单位、启动和调试即可,仍需评估物理效果 |
+| 二:增加 profile 分支 | 在原机器人列表旁增加一个新的机器人/场景选择 | 新 profile、模型/descriptor、manifest、Tool frame 与工作流 | 现有节点支持时继承 locks | 中;需要运动学、模型转换、关节/坐标映射和跨配置核对能力 |
+| 三:独立 Node 开发并组装自己的 Skill | 新设备协议、新算法、新消息能力或新 Tool | Node 源码、测试、构建发布、dataflow 和 Skill | 新版本、新 artifact 身份与摘要 | 高;需要 Python/C++/Rust 中所用语言、Dora/Arrow、生命周期及系统联调能力 |
+
+难度按改动边界划分,不按改了几个文件判断。配置改动也可能影响接触、稳定性或真实设备,
+新增 profile 也可能暴露现有 Node 不支持的自由度/控制模式,届时须转入第三种模式。
+
+```mermaid
+flowchart TD
+ Q["目标能力是否可由现有兼容 Node 实现?"]
+ Q -->|"是"| P["是否需要保留原 profile,并新增一个部署选择?"]
+ P -->|"否"| M1["模式一:已有 profile 内调整"]
+ P -->|"是"| M2["模式二:新增 profile 分支"]
+ Q -->|"否"| M3["模式三:开发 Node,再组装 Skill"]
+ M1 --> V["打包、本地安装、原生 Tool 验收"]
+ M2 --> V
+ M3 --> V
+ V --> R["按目标平台登记、审核发布,再验收检索安装"]
+```
+
+## 2. 模式一:已有 profile 内配置调整
+
+### 2.1 适用边界
+
+现有 Node 已支持目标模型和消息,所需变化在它公开的配置 schema 内。例如:
+调整仿真初始关节角、相机输出、controller gains 或已有 Tool 允许的速度比例。
+不要通过增加未知 YAML 字段假定二进制会获得新能力,也不要放宽容差掩盖模型/坐标问题。
+
+### 2.2 具体流程
+
+1. 固定基线 Skill、profile、Core/Dora 版本和 Node locks;先运行未修改的 profile,确认环境可用。
+2. 从已校验 Bundle 建立独立工作副本。修改工作副本,保留原包,不直接编辑正在运行或共享的已安装目录。
+3. 只改目标参数,同时检查依赖配置。例如初始状态须满足限位;夹爪单位和 controller、descriptor 必须一致。
+4. 若 group、frame、工具范围或资产位置发生变化,同步 Gateway ToolSpec、required_assets 和工作流说明。
+5. 使用自己的 Skill 身份或新的修订版本,运行官方打包脚本,停止旧 Runtime 后本地安装。
+6. 检查 inspect、依赖 Node 摘要、启动、Tool context、代表性原生 Action、失败处理及停止。
+7. 保留本地验收材料;需要共享时,按目标平台完成登记与发布,不覆盖已有版本资产。
+
+**对应示例**:[Piper X 配置改动表](../PIPER_X_DEMO_zh.md#42-配置改动表)说明多个配置如何保持一致;
+[Piper X 原生验收](../PIPER_X_DEMO_zh.md#6-两种控制方式的原生验收)可作为调参后的检查方法。
+Piper X 整体接入包含模型变化,超出单纯调参;这里复用的是配置核对与验收步骤。
+
+## 3. 模式二:增加 profile 分支
+
+### 3.1 目标与文件结构
+
+保留原 `mujoco-piper` 等分支,在同一 Skill 的 `profiles` 映射中增加一个选择:
+
+```text
+my-skill/
+├── skill.yaml
+├── SKILL.md
+├── profiles/
+│ ├── mujoco-piper/...
+│ └── mujoco-my-arm/...
+└── assets/robots/
+ ├── piper/...
+ └── my_arm/...
+```
+
+Profile 是部署选择,不是新的 Node 类型。新机械臂的关节维度、关节类型、执行模式和状态表达
+必须能由现有 simulator、motion server、controller 和 Gateway/provider 版本共同支持。
+
+### 3.2 具体流程
+
+1. 从原 Bundle 的合适 profile 复制出新目录,保留原目录与资产;不要在已安装目录操作。
+2. 固定新模型的来源/revision/许可证,定义逻辑关节、限位、初始姿态、base 和 TCP。
+3. 完成 URDF/MJCF 转换和 FK/伺服检查;确认逻辑夹爪与物理关节、actuator 的映射。
+4. 更新新分支中的 simulator、motion、controller、sim-control 和 Gateway 配置,核对路径、group、frame、单位与 schema。
+5. 保留或调整 dataflow 端口连接。若 Node 未变,保持其不可变 locks;移除能力时也同步 required_tools/binaries。
+6. 在 manifest 注册新 profile,填写完整 dataflow、required_assets、required_binaries、required_tools 和 environment。
+7. 更新 SKILL.md 的机器人选择和约束,递增 Skill 版本,再打包、本地安装并验证新旧分支。
+8. 切换 profile 前停止当前 Runtime,检查端口/设备占用;完成依赖解析、原生动作和停止验收后再登记发布。
+
+以下是添加到 `skill.yaml` 的 profile 结构示例;它不是完整 manifest,资产文件也须实际提供。
+该示例假设复用支持六维臂和平行夹爪的既有链,其他机器人应按实际能力调整:
+
+```yaml
+profiles:
+ mujoco-my-arm:
+ dataflow: profiles/mujoco-my-arm/dataflow.yaml
+ required_tools:
+ - sim.get_robot_info
+ - sim.set_joint_positions
+ - sim.move_eef
+ - sim.set_gripper_opening
+ - sim.reset
+ required_binaries:
+ - gateway
+ - sim_control_policy
+ - motion_action_policy
+ - motion_server
+ - joint_trajectory_controller
+ - gripper_action_policy
+ - gripper_action_controller
+ - mujoco_sim
+ - image_viewer
+ required_assets:
+ - assets/robots/my_arm/robot.yaml
+ - assets/robots/my_arm/my_arm.urdf
+ - assets/robots/my_arm/mjcf/scene.xml
+ - assets/robots/my_arm/mjcf/my_arm.xml
+ required_environment: []
+ environment: {}
+```
+
+新增键时保留已有 `profiles` 内容;不能用上面的片段覆盖原 manifest。
+`required_tools` 是覆盖而非追加顶层列表,应列全该分支需要的工具。
+当前清单的 `gateway_url` 是 Skill 级字段;同一地址要与所选分支的 gateway 配置一致。
+需要同时运行不同部署时,应另行设计独立 Skill/地址及资源隔离,不把 profile 分支当作并发实例机制。
+
+### 3.3 Piper X 示例如何复用
+
+模型与配置步骤见 [PIPER_X_DEMO.md](../PIPER_X_DEMO_zh.md),检查项见
+[接入下一种机械臂](../PIPER_X_DEMO_zh.md#9-接入下一种机械臂与提交交付物)。
+
+**示例生成器创建的是独立 `robot-control-sim-piper-x` Skill,并裁剪为仅保留 Piper X profile。**
+它示范了新 profile 的内部配置,不是“保留三个旧 profile、再追加一个分支”的自动化工具。
+要完成本节模式,需以未裁剪的上游 Bundle 为工作基础,按上述步骤合入新的模型/profile,并保留原分支。
+生成器也不是任意 URDF 的通用导入器,下一种机械臂需核对其具体模型处理逻辑。
+
+## 4. 模式三:独立开发 Node 并组装自己的 Skill
+
+### 4.1 决定接口与组装方式
+
+先按 [仓库目录](REPOSITORIES_zh.md) 选择基础代码,并依 [公共协议](PROTOCOLS_zh.md) 定义端口、字段、
+单位、时序、错误、资源释放与取消行为:设备对外接入通常属于 Adapter,图内算法通常属于 Operator。
+
+存在两种组装方式:
+
+- **数据平面 Node**:仅消费/产生状态、观测、轨迹或 JointCommand。可连接到已有 provider 和控制链,不必新增 Endpoint。
+- **新调用能力 Node**:需要由调用者直接使用时,实现 Endpoint operation,配置 Gateway ToolSpec/provider 路由,并接入 ToolMessage 端口。
+
+如果新增 Tool,应同时明确稳定 tool_id、semantics、input/output schema、frame/单位、readiness、
+operation 的并发限制及终态结果。Query/Action/Session 按各自契约实现;不能仅增加一个 Session 字段
+就假定所选 Gateway/provider 版本支持完整 Session 链路。
+
+### 4.2 开发与验证顺序
+
+1. 选择兼容的 Core/Gateway/Dora/Forge 消息版本;固定依赖锁,建立自己的源码分支和版本。
+2. 把可确定性测试的算法/驱动接口与 Dora 收发、Endpoint handler 分离。
+3. 先验证状态/命令序列化、单位和端口,再验证 tick、资源开关、超时/取消、重连或异常退出。
+4. 对算法用单元测试和 fake plant;对设备适配补设备层验证,不将 import/帮助检查当作真机验收。
+5. 在目标 OS/架构构建可执行制品,验证 entrypoint、依赖、许可证和归档结构。
+6. 组装自己的 Gateway 配置、dataflow、资产和 manifest。使 required_binaries 与 entrypoint、Tool allowlist 与暴露能力一致。
+7. 使用新的 Node artifact 身份和摘要更新 Skill locks,再执行本地安装与完整执行链验收。
+8. 按平台流程分别登记新增 Node 和 Skill,等待所需审核发布后验证消费者检索与安装。
+
+[Piper X demo](../PIPER_X_DEMO_zh.md)展示后半段的 Skill 组装和双控制模式验收;它复用原始 Node,
+不代替这里要求的 Node 源码开发与测试。特别是,当前 Forge 2.x 源码不能直接混入该 demo 的 Dora 0.4 旧锁集合。
+
+源码可读解决实现和配置查询;要替换二进制,还需建立可复现的构建与版本对应关系。
+以下以 `operator-controls` 为入口示范构建步骤,使用仓库目录中的固定源码快照。
+它不证明该提交是 Piper X 示例锁定二进制的构建来源,也不能直接替换示例的旧版 Node。
+使用新构建前,须在目标 Skill 中统一 Dora、Forge 消息和相关节点的兼容版本。
+
+### Node 仓库 README 必填内容
+
+后续新建或修改 Node 仓库时,必须在根 README 维护能力摘要,并随接口修改一并更新。
+英文使用 `README.md`,中文使用 `README_zh.md`,顶部互相链接;两份独立排版,不在同一份正文中交错翻译。
+接口事实、数量、示例与命令保持一致,修改时同步维护两份。
+独立统计生产 Node、Endpoint、operation 和 Gateway Tool;CLI 别名、离线工具和 fake plant 不计为生产 Node。
+
+| 必填项 | 写清什么 |
+| --- | --- |
+| 生产 Node | 数量、名称、源码/CLI 与打包 entrypoint;辅助程序另列 |
+| Tool 支持 | 仅数据平面、provider、caller 或 Gateway;启用配置及默认模式 |
+| Endpoint | 数量、endpoint_id、provider Node、descriptor 源码链接;不支持时填 0 |
+| operation | 每个 Endpoint 的数量与名称、Query/Action/Session、并发和生命周期控制 |
+| HTTP Tool API | 方法/路径、参数/结果契约;provider 不监听 HTTP 时填 0,并指向 Gateway |
+| Tool 绑定 | tool_id → endpoint_id / operation → provider Node;绑定依赖配置时明确说明 |
+| 兼容性与构建 | schema/Wire 版本、依赖锁、配置示例、构建来源与制品版本边界 |
+
+推荐根 README 结构:
+
+```markdown
+## Node、Endpoint 与 Tool API
+
+| 项目 | 当前实现 |
+| --- | --- |
+| 生产 Node | <数量、入口;别名和辅助程序单列> |
+| Tool 支持 | <模式与启用条件> |
+| Endpoint 数 | <数量、ID、provider、descriptor 链接> |
+| operation 数 | <名称、语义、并发与 cancel/stop/status/result> |
+| 直接 HTTP Tool API | <方法/路径,或 0:由 Gateway 暴露> |
+| Gateway Tool 数 | <配置决定;指向具体 profile 的 ToolSpec> |
+
+<调用映射、请求/结果、单位/frame、错误、数据流和兼容性链接>
+```
+
+例如 `gripper_action_policy` 是一个 Node、一个 Endpoint、一个 Action operation;
+其下游 `gripper_action_controller` 虽接收 Dora Action 形状的目标/反馈/结果,却没有 ToolEndpoint。
+`motion_action_policy` 提供一个 Endpoint 的两个 operation,`motion_server` 是另一个计算 Node。
+Gateway 的业务 Endpoint 数为 0,其路由数量与外部 Tool 数取决于部署配置。
+
+审阅时对照 package scripts、构建输出、descriptor、handler、ToolSpec 和 dataflow,
+不要由目录名、类名或旧 README 推断当前能力。完整仓库核查摘要见
+[Node 与 Tool 能力清单](REPOSITORIES_zh.md#5-nodeendpoint-与-tool-能力清单)。
+
+### 4.3 源码构建示例
+
+在目标 Linux x86_64 构建环境中准备 Git、uv 和 Python 3.12:
+
+```bash
+git clone https://github.com/PhyAgentOS/operator-controls.git
+cd operator-controls
+git checkout cde73dc2a6222d81b01ffc32f69f12cb12e42760
+uv sync --frozen --all-groups
+uv run pytest -q
+bash scripts/build_pyinstaller.sh
+```
+
+脚本使用 frozen lock 重建 `.venv_build`,生成 `dist/joint_trajectory_controller`、
+`dist/gripper_action_controller` 和 `dist/fake_joint_plant`,并检查帮助与参数错误处理。
+这些检查不替代跨节点运动测试。修改算法后,应先更新对应源码版本并提交到自己的分支,再构建最终发布制品。
+构建目标须与客户端匹配;macOS 可执行文件不能标记为 Linux 制品。
+
+实现依据:[构建脚本](https://github.com/PhyAgentOS/operator-controls/blob/cde73dc2a6222d81b01ffc32f69f12cb12e42760/scripts/build_pyinstaller.sh)、
+[Ubuntu 构建环境](https://github.com/PhyAgentOS/operator-controls/blob/cde73dc2a6222d81b01ffc32f69f12cb12e42760/.github/workflows/build-ubuntu20.yml)。
+
+### 4.4 归档与制品溯源
+
+单文件制品按 `executable_tar_gz` 打包,归档根目录必须是 entrypoint 指定的可执行文件:
+
+```bash
+# 示例版本;应与自己的源码和发布版本一致。
+FORGE_NODE_VERSION=0.1.1
+FORGE_NODE_ARCHIVE="joint_trajectory_controller-${FORGE_NODE_VERSION}-linux-x86_64.tar.gz"
+tar -C dist -czf "$FORGE_NODE_ARCHIVE" joint_trajectory_controller
+sha256sum "$FORGE_NODE_ARCHIVE"
+wc -c < "$FORGE_NODE_ARCHIVE"
+```
+
+若使用 `directory_tar_gz`,则保留 entrypoint 同名根目录及其运行时树;
+不要把 onefile 和 onedir 两类归档混用。每个发布资产至少关联以下信息:
+
+| 信息 | 对应的检查 |
+| --- | --- |
+| 仓库 URL、完整 commit、tag | 能定位实际参与构建的源码;公开最新分支不能代替 commit |
+| 构建命令、依赖锁、系统与架构 | 能重建或解释运行环境;保留 CI workflow 的固定版本 |
+| entrypoint、archive type | 与归档结构、可执行权限和安装器规则一致 |
+| 文件名、字节数、归档 SHA256 | 对象存储、Release、Registry 元数据和消费者 lock 指向相同字节 |
+| Node 名称、版本、artifact ID | 新构建使用新的不可变身份,不覆盖原版本资产 |
+| 许可证及第三方声明 | 包含分发二进制及其依赖所需的声明 |
+
+在派生 Skill 的 `artifacts.nodes.` 中填写新 artifact ID/version/SHA256、
+目标平台、归档类型和 entrypoint。保持 dataflow 使用的 node ID、binary 占位符及 required_binaries 一致,
+再递增 Skill 版本、重新打包,并通过本地安装、`forge-node verify` 和原生 Tool API 验收。
+回退时安装上一组已发布的不可变版本,不用原版本号覆盖新旧归档。
+
+## 5. 三种模式共用的验收与交付流程
+
+| 阶段 | 必须确认的事实 |
+| --- | --- |
+| 静态核对 | manifest/profile 可解析,所有路径、单位、group、frame、Tool 和 binary 声明一致 |
+| 模型/算法检查 | 按改动范围验证 FK、限位、伺服或算法单元测试;说明覆盖边界 |
+| 打包与本地安装 | 归档结构、字节数、SHA256、Node locks 和 entrypoint 一致,inspect/verify 通过 |
+| Runtime 验收 | 从所选 profile 启动,Tool context/readiness 可用;执行代表性原生调用并检查终态、误差和停止 |
+| Agent 工作流验收 | 需要 Agent 时单独检查激活、任务绑定、finalize 与 verdict,不用原生动作成功替代独立验证 |
+| 平台登记/审核 | 先比对已有身份,复用匹配的 Node;提交新的资源版本、依赖和所需证据,经过目标平台流程 |
+| 发布后验收 | 通过与该平台 API 匹配的消费者检索、安装到独立实例,再 inspect 并逐 Node verify |
+
+GitHub push/Release、资源平台登记、技术校验、审核发布、Core 下载安装是不同阶段。
+三种开发模式都不通过“修改静态目录”来证明新平台登记已生效;账号和上传/审核接口以目标平台对应版本说明为准。
+也不要把网页显示待审核条目当作该版本已可被消费者下载。
+
+每个新版本保留源码/模型 revision、依赖锁、Bundle/Node 摘要、构建说明与许可证。
+完整源码对应关系未证明时,明确保留这个限制,不以最新默认分支冒充旧二进制来源。
+回退使用上一组不可变制品和 locks,不覆盖同版本归档。
+
+## 6. 进一步阅读
+
+- [Piper X 完整 demo](../PIPER_X_DEMO_zh.md):从官方模型到 profile、两种原生 Action 和停止的完整命令。
+- [Runtime 实际关系](RUNTIME_zh.md):robot-control-sim 的五个 Tool、三个 Endpoint、三个 provider 与九节点图。
+- [Bundle 与 Tool 接入参考](../README_zh.md):manifest、ToolSpec、任务绑定和通用验收契约。
diff --git a/docs/user_manual/DOCKER.md b/docs/user_manual/DOCKER.md
index a91565014..903f41827 100644
--- a/docs/user_manual/DOCKER.md
+++ b/docs/user_manual/DOCKER.md
@@ -1,108 +1,110 @@
-# Docker 部署指南
+# Docker Deployment Guide
-> 版本:1.0.0 · [English](DOCKER_en.md)
+> Version: 1.1.1 · [中文](DOCKER_zh.md)
-PhyAgentOS 提供基于 Docker 的快速部署方案,无需手动配置 Python / Node.js 环境。配合 [`scripts/install.sh`](../../scripts/install.sh) 一键脚本,可在一分钟内完成构建、初始化与运行。
+PhyAgentOS ships with a Docker-based quick deployment that requires no manual Python / Node.js setup. Together with the [`scripts/install.sh`](../../scripts/install.sh) one-click script, you can build, initialize, and run in under a minute.
-> 镜像基础:`ghcr.io/astral-sh/uv:python3.12-bookworm-slim`(CPU,约几百 MB)
+> Image base: `ghcr.io/astral-sh/uv:python3.12-bookworm-slim` (CPU, a few hundred MB)
---
-## 📦 镜像包含什么
+## 📦 What's in the Image
-| 组件 | 说明 |
+| Component | Description |
|:-----|:-----|
-| Python 3.12 运行时 | 由 `uv` 安装 `pyproject.toml` 中的全部依赖 |
-| `paos` CLI | 已注册为入口命令(`ENTRYPOINT`) |
-| Node.js 20 | 从锁定的 npm 依赖严格编译 WhatsApp bridge |
-| 配置目录 | `/root/.PhyAgentOS`(通过卷挂载到宿主机持久化) |
-| 默认服务 | 交互式 CLI(`paos agent`),可切换为长驻网关 |
-
-镜像**不包含** Dora CLI、具体 Forge Skill 或 Node、GPU / CUDA、Isaac Sim、BEHAVIOR-1K
-及其他机器人 Runtime 依赖。标准镜像运行通用 Agent 与消息总线 gateway,不提供托管 Forge
-Skill Runtime。需要该 Runtime 时,应按[用户手册](../zh/02-user-manual.md#托管-skill-profile-所需的-dora-cli)
-使用宿主机原生 PhyAgentOS 环境运行,或者构建包含 Dora CLI v0.4.1、`dora-message` v0.7.0
-与所选 Skill profile 全部前置条件的定制镜像。仅在宿主机安装 Dora 不会使其出现在标准容器内。
-
-> **关于网关端口**:`paos gateway` 是消息总线服务(Agent + 频道 + Cron + Heartbeat + Forge 编排),**仅主动外连**(连接 LLM provider、Telegram/钉钉等频道),不监听入站端口。`config.json` 中的 `gateway.port` 当前仅用于启动日志展示,未绑定 socket,因此容器**无需** `-p` 端口映射。
+| Python 3.12 runtime | All `pyproject.toml` deps installed via `uv` |
+| `paos` CLI | Registered as the entrypoint (`ENTRYPOINT`) |
+| Node.js 20 | Strictly builds the WhatsApp bridge from locked npm dependencies |
+| Config directory | `/root/.PhyAgentOS` (persisted to the host via a volume mount) |
+| Default service | Interactive CLI (`paos agent`); switchable to a long-running gateway |
+
+The image does **not** include Dora CLI, concrete Forge Skills or nodes, GPU / CUDA, Isaac Sim,
+BEHAVIOR-1K, or other robot Runtime dependencies. The stock image runs the general Agent and its
+message-bus gateway; it does not provide a managed Forge Skill Runtime. Run that Runtime from a
+host-native PhyAgentOS installation following the
+[user manual](../en/02-user-manual.md#dora-cli-for-managed-skill-profiles), or build a custom image
+containing Dora CLI v0.4.1 with `dora-message` v0.7.0 and every prerequisite of the selected Skill
+profile. Installing Dora only on the host does not make it visible inside the stock container.
+
+> **About the gateway port**: `paos gateway` is a message-bus service (Agent + channels + Cron + Heartbeat + Forge orchestration) that makes **outbound connections only** (LLM providers, Telegram/DingTalk, etc.) and does **not** bind an inbound port. `gateway.port` in `config.json` is currently shown only in the startup log and is not bound to a socket, so the container needs **no** `-p` port mapping.
---
-## ✅ 前置条件
+## ✅ Prerequisites
-- **Docker 20.10+**(含 daemon 运行中)
-- 可选:**Docker Compose v2**(若使用 `docker-compose.yml`)
+- **Docker 20.10+** (with the daemon running)
+- Optional: **Docker Compose v2** (if you use `docker-compose.yml`)
-检查环境:
+Check your environment:
```bash
docker --version
-docker info # 确认 daemon 正常运行
+docker info # confirm the daemon is up
```
---
-## 🚀 一键安装与运行
+## 🚀 One-click install & run
-> 以下 `./scripts/install.sh` 命令均在**仓库根目录**执行。
+> The `./scripts/install.sh` commands below are run from the **repository root**.
-最简流程,两条命令:
+Minimal flow, two commands:
```bash
-# 1. 构建镜像 + 写入默认配置(首次使用)
+# 1. Build the image + write the default config (first run)
./scripts/install.sh
-# 2. 编辑配置,填入 LLM API Key
+# 2. Edit the config and add your LLM API key
# macOS / Linux: vi ~/.PhyAgentOS/config.json
-# 在 providers..apiKey 处填入你的密钥
+# Put it under providers..apiKey
-# 3. 进入交互式 CLI
+# 3. Enter the interactive CLI
./scripts/install.sh chat
```
-### 完整命令列表
+### Full command list
-| 命令 | 作用 |
+| Command | Purpose |
|:-----|:-----|
-| `./scripts/install.sh` | (默认)构建镜像 + 初始化配置 |
-| `./scripts/install.sh build` | 仅构建镜像 |
-| `./scripts/install.sh onboard` | 仅写入默认配置到 `~/.PhyAgentOS/config.json` |
-| `./scripts/install.sh chat` | 交互式 CLI(镜像默认服务) |
-| `./scripts/install.sh gateway` | 启动长驻网关(消息总线,仅外连,无入站端口) |
-| `./scripts/install.sh status` | 查看 PhyAgentOS 状态 |
-| `./scripts/install.sh stop` | 停止网关容器 |
-| `./scripts/install.sh logs` | 跟踪网关日志 |
-| `./scripts/install.sh help` | 显示帮助 |
+| `./scripts/install.sh` | (default) build image + initialize config |
+| `./scripts/install.sh build` | build the image only |
+| `./scripts/install.sh onboard` | write the default config to `~/.PhyAgentOS/config.json` only |
+| `./scripts/install.sh chat` | interactive CLI (default service) |
+| `./scripts/install.sh gateway` | long-running gateway (message bus, outbound only, no inbound port) |
+| `./scripts/install.sh status` | show PhyAgentOS status |
+| `./scripts/install.sh stop` | stop the gateway container |
+| `./scripts/install.sh logs` | tail gateway logs |
+| `./scripts/install.sh help` | show help |
---
-## ⚙️ 配置与环境变量
+## ⚙️ Configuration & environment
-### 数据目录
+### Data directory
-所有配置、工作区、会话历史都保存在宿主机的 `~/.PhyAgentOS`,通过卷挂载(`-v`)注入容器:
+All config, workspace, and session history live on the host under `~/.PhyAgentOS`, injected into the container via a volume mount (`-v`):
```
-宿主机 ~/.PhyAgentOS ⟷ 容器 /root/.PhyAgentOS
+Host ~/.PhyAgentOS ⟷ Container /root/.PhyAgentOS
```
-因此**卸载镜像不会丢失数据**,重新运行脚本即可恢复。
+So **removing the image does not lose data**; re-running the script restores everything.
-### 可配置环境变量
+### Configurable environment variables
-| 变量 | 默认值 | 说明 |
+| Variable | Default | Description |
|:-----|:-------|:-----|
-| `PAOS_DATA_DIR` | `~/.PhyAgentOS` | 配置与工作区目录 |
+| `PAOS_DATA_DIR` | `~/.PhyAgentOS` | Config & workspace directory |
-示例:自定义数据目录启动网关。
+Example: start the gateway with a custom data directory.
```bash
PAOS_DATA_DIR=/data/paos ./scripts/install.sh gateway
```
-### API Key 配置
+### API key configuration
-交互式 CLI 与网关都需要 LLM provider 的 API Key。安装脚本会在 `onboard` 阶段写入默认配置模板,编辑其中的 `providers` 段:
+Both the interactive CLI and the gateway need an LLM provider API key. The install script writes a default config template during `onboard`; edit the `providers` section:
```json
{
@@ -114,42 +116,42 @@ PAOS_DATA_DIR=/data/paos ./scripts/install.sh gateway
}
```
-支持的 provider 及 OAuth 流程见 `paos provider login`。
+See `paos provider login` for supported providers and OAuth flows.
---
-## 🧩 使用 Docker Compose
+## 🧩 Using Docker Compose
-仓库已提供 [`docker-compose.yml`](../../docker-compose.yml),适合需要常驻服务的场景。
+The repo ships a [`docker-compose.yml`](../../docker-compose.yml) for scenarios that need a persistent service.
```bash
-# 启动网关(后台常驻,自动重启)
+# Start the gateway (background, auto-restart)
docker compose up -d phyagentos-gateway
-# 查看日志
+# View logs
docker compose logs -f phyagentos-gateway
-# 进入交互式 CLI(独立 profile)
+# Enter the interactive CLI (separate profile)
docker compose run --rm phyagentos-cli
```
---
-## 🔧 直接使用 Docker(不用脚本)
+## 🔧 Using Docker directly (without the script)
-如需完全手动控制(`docker build` 需在**仓库根目录**执行):
+For full manual control (`docker build` must be run from the **repository root**):
```bash
-# 构建
+# Build
docker build -t phyagentos:latest .
-# 初始化配置(首次)
+# Initialize config (first run)
docker run --rm -v ~/.PhyAgentOS:/root/.PhyAgentOS phyagentos:latest onboard
-# 交互式 CLI
+# Interactive CLI
docker run --rm -it -v ~/.PhyAgentOS:/root/.PhyAgentOS phyagentos:latest agent
-# 长驻网关(消息总线,仅外连,无需端口映射)
+# Long-running gateway (message bus, outbound only, no port mapping needed)
docker run -d --name phyagentos-gateway \
-v ~/.PhyAgentOS:/root/.PhyAgentOS \
phyagentos:latest gateway
@@ -157,40 +159,41 @@ docker run -d --name phyagentos-gateway \
---
-## ⚠️ 已知限制
+## ⚠️ Known limitations
-### 1. 不包含托管 Forge Skill Runtime
+### 1. Managed Forge Skill Runtime is not included
-标准镜像没有 Dora CLI 或具体 Forge Runtime 制品。因此,除非显式扩展镜像并安装 Dora CLI
-v0.4.1、`dora-message` v0.7.0 与所选 Skill 的平台依赖,否则该镜像不支持
-`paos skill start`。仅使用 Agent 和消息渠道时不需要 Dora。
+The stock image has no Dora CLI or concrete Forge Runtime artifacts. `paos skill start` therefore
+is not supported in this image without an explicitly extended image containing Dora CLI v0.4.1,
+`dora-message` v0.7.0, and the selected Skill's platform dependencies. Agent-only and
+message-channel use does not require Dora.
-### 2. 容器以 root 运行
+### 2. Container runs as root
-为保持与 `~/.PhyAgentOS:/root/.PhyAgentOS` 的卷挂载约定一致,镜像默认以 root 用户运行。如需生产硬化,建议后续添加非 root 用户与 healthcheck。
+To stay consistent with the `~/.PhyAgentOS:/root/.PhyAgentOS` volume-mount convention, the image runs as root by default. For production hardening, consider adding a non-root user and a healthcheck later.
-### 3. 不含 GPU 支持
+### 3. No GPU support
-本镜像为 CPU 版,不支持 Isaac Sim / BEHAVIOR-1K 等需要 CUDA 的仿真。如需 GPU,需改用 `nvidia/cuda` 基础镜像并以 `--gpus all` 运行。
+This is a CPU image and does not support Isaac Sim / BEHAVIOR-1K or other CUDA-based simulation. For GPU, switch the base image to `nvidia/cuda` and run with `--gpus all`.
---
-## 🧯 排错
+## 🧯 Troubleshooting
-| 现象 | 解决方案 |
+| Symptom | Solution |
|:-----|:---------|
-| `docker: command not found` | 安装 Docker: |
-| `Cannot connect to the Docker daemon` | 启动 Docker Desktop 或 `sudo systemctl start docker` |
-| 构建 OOM / 过慢 | 增大 Docker 内存分配;首次构建需下载依赖,后续走缓存 |
-| `paos agent` 报 `No API key configured` | 编辑 `~/.PhyAgentOS/config.json` 填入 `apiKey` |
-| 网关启动后立即退出 | 多为缺 API Key;`./scripts/install.sh logs` 查看日志确认 |
-| 网关容器无法启动 | `docker rm -f phyagentos-gateway` 后重试 |
+| `docker: command not found` | Install Docker: |
+| `Cannot connect to the Docker daemon` | Start Docker Desktop or `sudo systemctl start docker` |
+| Build OOM / slow | Increase Docker memory; first build downloads deps, later builds use cache |
+| `paos agent` reports `No API key configured` | Edit `~/.PhyAgentOS/config.json` and set `apiKey` |
+| Gateway exits immediately after start | Usually a missing API key; confirm with `./scripts/install.sh logs` |
+| Gateway container fails to start | `docker rm -f phyagentos-gateway` and retry |
---
-## 📚 相关文件
+## 📚 Related files
-- [`Dockerfile`](../../Dockerfile) — 镜像构建定义
-- [`docker-compose.yml`](../../docker-compose.yml) — Compose 编排
-- [`.dockerignore`](../../.dockerignore) — 构建忽略规则
-- [`scripts/install.sh`](../../scripts/install.sh) — 一键安装脚本
+- [`Dockerfile`](../../Dockerfile) — image build definition
+- [`docker-compose.yml`](../../docker-compose.yml) — Compose orchestration
+- [`.dockerignore`](../../.dockerignore) — build-ignore rules
+- [`scripts/install.sh`](../../scripts/install.sh) — one-click install script
diff --git a/docs/user_manual/DOCKER_en.md b/docs/user_manual/DOCKER_en.md
deleted file mode 100644
index 87b49914e..000000000
--- a/docs/user_manual/DOCKER_en.md
+++ /dev/null
@@ -1,199 +0,0 @@
-# Docker Deployment Guide
-
-> Version: 1.0.0 · [中文](DOCKER.md)
-
-PhyAgentOS ships with a Docker-based quick deployment that requires no manual Python / Node.js setup. Together with the [`scripts/install.sh`](../../scripts/install.sh) one-click script, you can build, initialize, and run in under a minute.
-
-> Image base: `ghcr.io/astral-sh/uv:python3.12-bookworm-slim` (CPU, a few hundred MB)
-
----
-
-## 📦 What's in the Image
-
-| Component | Description |
-|:-----|:-----|
-| Python 3.12 runtime | All `pyproject.toml` deps installed via `uv` |
-| `paos` CLI | Registered as the entrypoint (`ENTRYPOINT`) |
-| Node.js 20 | Strictly builds the WhatsApp bridge from locked npm dependencies |
-| Config directory | `/root/.PhyAgentOS` (persisted to the host via a volume mount) |
-| Default service | Interactive CLI (`paos agent`); switchable to a long-running gateway |
-
-The image does **not** include Dora CLI, concrete Forge Skills or nodes, GPU / CUDA, Isaac Sim,
-BEHAVIOR-1K, or other robot Runtime dependencies. The stock image runs the general Agent and its
-message-bus gateway; it does not provide a managed Forge Skill Runtime. Run that Runtime from a
-host-native PhyAgentOS installation following the
-[user manual](../en/02-user-manual.md#dora-cli-for-managed-skill-profiles), or build a custom image
-containing Dora CLI v0.4.1 with `dora-message` v0.7.0 and every prerequisite of the selected Skill
-profile. Installing Dora only on the host does not make it visible inside the stock container.
-
-> **About the gateway port**: `paos gateway` is a message-bus service (Agent + channels + Cron + Heartbeat + Forge orchestration) that makes **outbound connections only** (LLM providers, Telegram/DingTalk, etc.) and does **not** bind an inbound port. `gateway.port` in `config.json` is currently shown only in the startup log and is not bound to a socket, so the container needs **no** `-p` port mapping.
-
----
-
-## ✅ Prerequisites
-
-- **Docker 20.10+** (with the daemon running)
-- Optional: **Docker Compose v2** (if you use `docker-compose.yml`)
-
-Check your environment:
-
-```bash
-docker --version
-docker info # confirm the daemon is up
-```
-
----
-
-## 🚀 One-click install & run
-
-> The `./scripts/install.sh` commands below are run from the **repository root**.
-
-Minimal flow, two commands:
-
-```bash
-# 1. Build the image + write the default config (first run)
-./scripts/install.sh
-
-# 2. Edit the config and add your LLM API key
-# macOS / Linux: vi ~/.PhyAgentOS/config.json
-# Put it under providers..apiKey
-
-# 3. Enter the interactive CLI
-./scripts/install.sh chat
-```
-
-### Full command list
-
-| Command | Purpose |
-|:-----|:-----|
-| `./scripts/install.sh` | (default) build image + initialize config |
-| `./scripts/install.sh build` | build the image only |
-| `./scripts/install.sh onboard` | write the default config to `~/.PhyAgentOS/config.json` only |
-| `./scripts/install.sh chat` | interactive CLI (default service) |
-| `./scripts/install.sh gateway` | long-running gateway (message bus, outbound only, no inbound port) |
-| `./scripts/install.sh status` | show PhyAgentOS status |
-| `./scripts/install.sh stop` | stop the gateway container |
-| `./scripts/install.sh logs` | tail gateway logs |
-| `./scripts/install.sh help` | show help |
-
----
-
-## ⚙️ Configuration & environment
-
-### Data directory
-
-All config, workspace, and session history live on the host under `~/.PhyAgentOS`, injected into the container via a volume mount (`-v`):
-
-```
-Host ~/.PhyAgentOS ⟷ Container /root/.PhyAgentOS
-```
-
-So **removing the image does not lose data**; re-running the script restores everything.
-
-### Configurable environment variables
-
-| Variable | Default | Description |
-|:-----|:-------|:-----|
-| `PAOS_DATA_DIR` | `~/.PhyAgentOS` | Config & workspace directory |
-
-Example: start the gateway with a custom data directory.
-
-```bash
-PAOS_DATA_DIR=/data/paos ./scripts/install.sh gateway
-```
-
-### API key configuration
-
-Both the interactive CLI and the gateway need an LLM provider API key. The install script writes a default config template during `onboard`; edit the `providers` section:
-
-```json
-{
- "providers": {
- "openrouter": {
- "apiKey": "YOUR_API_KEY"
- }
- }
-}
-```
-
-See `paos provider login` for supported providers and OAuth flows.
-
----
-
-## 🧩 Using Docker Compose
-
-The repo ships a [`docker-compose.yml`](../../docker-compose.yml) for scenarios that need a persistent service.
-
-```bash
-# Start the gateway (background, auto-restart)
-docker compose up -d phyagentos-gateway
-
-# View logs
-docker compose logs -f phyagentos-gateway
-
-# Enter the interactive CLI (separate profile)
-docker compose run --rm phyagentos-cli
-```
-
----
-
-## 🔧 Using Docker directly (without the script)
-
-For full manual control (`docker build` must be run from the **repository root**):
-
-```bash
-# Build
-docker build -t phyagentos:latest .
-
-# Initialize config (first run)
-docker run --rm -v ~/.PhyAgentOS:/root/.PhyAgentOS phyagentos:latest onboard
-
-# Interactive CLI
-docker run --rm -it -v ~/.PhyAgentOS:/root/.PhyAgentOS phyagentos:latest agent
-
-# Long-running gateway (message bus, outbound only, no port mapping needed)
-docker run -d --name phyagentos-gateway \
- -v ~/.PhyAgentOS:/root/.PhyAgentOS \
- phyagentos:latest gateway
-```
-
----
-
-## ⚠️ Known limitations
-
-### 1. Managed Forge Skill Runtime is not included
-
-The stock image has no Dora CLI or concrete Forge Runtime artifacts. `paos skill start` therefore
-is not supported in this image without an explicitly extended image containing Dora CLI v0.4.1,
-`dora-message` v0.7.0, and the selected Skill's platform dependencies. Agent-only and
-message-channel use does not require Dora.
-
-### 2. Container runs as root
-
-To stay consistent with the `~/.PhyAgentOS:/root/.PhyAgentOS` volume-mount convention, the image runs as root by default. For production hardening, consider adding a non-root user and a healthcheck later.
-
-### 3. No GPU support
-
-This is a CPU image and does not support Isaac Sim / BEHAVIOR-1K or other CUDA-based simulation. For GPU, switch the base image to `nvidia/cuda` and run with `--gpus all`.
-
----
-
-## 🧯 Troubleshooting
-
-| Symptom | Solution |
-|:-----|:---------|
-| `docker: command not found` | Install Docker: |
-| `Cannot connect to the Docker daemon` | Start Docker Desktop or `sudo systemctl start docker` |
-| Build OOM / slow | Increase Docker memory; first build downloads deps, later builds use cache |
-| `paos agent` reports `No API key configured` | Edit `~/.PhyAgentOS/config.json` and set `apiKey` |
-| Gateway exits immediately after start | Usually a missing API key; confirm with `./scripts/install.sh logs` |
-| Gateway container fails to start | `docker rm -f phyagentos-gateway` and retry |
-
----
-
-## 📚 Related files
-
-- [`Dockerfile`](../../Dockerfile) — image build definition
-- [`docker-compose.yml`](../../docker-compose.yml) — Compose orchestration
-- [`.dockerignore`](../../.dockerignore) — build-ignore rules
-- [`scripts/install.sh`](../../scripts/install.sh) — one-click install script
diff --git a/docs/user_manual/DOCKER_zh.md b/docs/user_manual/DOCKER_zh.md
new file mode 100644
index 000000000..907694a5a
--- /dev/null
+++ b/docs/user_manual/DOCKER_zh.md
@@ -0,0 +1,196 @@
+# Docker 部署指南
+
+> 版本:1.1.1 · [English](DOCKER.md)
+
+PhyAgentOS 提供基于 Docker 的快速部署方案,无需手动配置 Python / Node.js 环境。配合 [`scripts/install.sh`](../../scripts/install.sh) 一键脚本,可在一分钟内完成构建、初始化与运行。
+
+> 镜像基础:`ghcr.io/astral-sh/uv:python3.12-bookworm-slim`(CPU,约几百 MB)
+
+---
+
+## 📦 镜像包含什么
+
+| 组件 | 说明 |
+|:-----|:-----|
+| Python 3.12 运行时 | 由 `uv` 安装 `pyproject.toml` 中的全部依赖 |
+| `paos` CLI | 已注册为入口命令(`ENTRYPOINT`) |
+| Node.js 20 | 从锁定的 npm 依赖严格编译 WhatsApp bridge |
+| 配置目录 | `/root/.PhyAgentOS`(通过卷挂载到宿主机持久化) |
+| 默认服务 | 交互式 CLI(`paos agent`),可切换为长驻网关 |
+
+镜像**不包含** Dora CLI、具体 Forge Skill 或 Node、GPU / CUDA、Isaac Sim、BEHAVIOR-1K
+及其他机器人 Runtime 依赖。标准镜像运行通用 Agent 与消息总线 gateway,不提供托管 Forge
+Skill Runtime。需要该 Runtime 时,应按[用户手册](../zh/02-user-manual.md#托管-skill-profile-所需的-dora-cli)
+使用宿主机原生 PhyAgentOS 环境运行,或者构建包含 Dora CLI v0.4.1、`dora-message` v0.7.0
+与所选 Skill profile 全部前置条件的定制镜像。仅在宿主机安装 Dora 不会使其出现在标准容器内。
+
+> **关于网关端口**:`paos gateway` 是消息总线服务(Agent + 频道 + Cron + Heartbeat + Forge 编排),**仅主动外连**(连接 LLM provider、Telegram/钉钉等频道),不监听入站端口。`config.json` 中的 `gateway.port` 当前仅用于启动日志展示,未绑定 socket,因此容器**无需** `-p` 端口映射。
+
+---
+
+## ✅ 前置条件
+
+- **Docker 20.10+**(含 daemon 运行中)
+- 可选:**Docker Compose v2**(若使用 `docker-compose.yml`)
+
+检查环境:
+
+```bash
+docker --version
+docker info # 确认 daemon 正常运行
+```
+
+---
+
+## 🚀 一键安装与运行
+
+> 以下 `./scripts/install.sh` 命令均在**仓库根目录**执行。
+
+最简流程,两条命令:
+
+```bash
+# 1. 构建镜像 + 写入默认配置(首次使用)
+./scripts/install.sh
+
+# 2. 编辑配置,填入 LLM API Key
+# macOS / Linux: vi ~/.PhyAgentOS/config.json
+# 在 providers..apiKey 处填入你的密钥
+
+# 3. 进入交互式 CLI
+./scripts/install.sh chat
+```
+
+### 完整命令列表
+
+| 命令 | 作用 |
+|:-----|:-----|
+| `./scripts/install.sh` | (默认)构建镜像 + 初始化配置 |
+| `./scripts/install.sh build` | 仅构建镜像 |
+| `./scripts/install.sh onboard` | 仅写入默认配置到 `~/.PhyAgentOS/config.json` |
+| `./scripts/install.sh chat` | 交互式 CLI(镜像默认服务) |
+| `./scripts/install.sh gateway` | 启动长驻网关(消息总线,仅外连,无入站端口) |
+| `./scripts/install.sh status` | 查看 PhyAgentOS 状态 |
+| `./scripts/install.sh stop` | 停止网关容器 |
+| `./scripts/install.sh logs` | 跟踪网关日志 |
+| `./scripts/install.sh help` | 显示帮助 |
+
+---
+
+## ⚙️ 配置与环境变量
+
+### 数据目录
+
+所有配置、工作区、会话历史都保存在宿主机的 `~/.PhyAgentOS`,通过卷挂载(`-v`)注入容器:
+
+```
+宿主机 ~/.PhyAgentOS ⟷ 容器 /root/.PhyAgentOS
+```
+
+因此**卸载镜像不会丢失数据**,重新运行脚本即可恢复。
+
+### 可配置环境变量
+
+| 变量 | 默认值 | 说明 |
+|:-----|:-------|:-----|
+| `PAOS_DATA_DIR` | `~/.PhyAgentOS` | 配置与工作区目录 |
+
+示例:自定义数据目录启动网关。
+
+```bash
+PAOS_DATA_DIR=/data/paos ./scripts/install.sh gateway
+```
+
+### API Key 配置
+
+交互式 CLI 与网关都需要 LLM provider 的 API Key。安装脚本会在 `onboard` 阶段写入默认配置模板,编辑其中的 `providers` 段:
+
+```json
+{
+ "providers": {
+ "openrouter": {
+ "apiKey": "YOUR_API_KEY"
+ }
+ }
+}
+```
+
+支持的 provider 及 OAuth 流程见 `paos provider login`。
+
+---
+
+## 🧩 使用 Docker Compose
+
+仓库已提供 [`docker-compose.yml`](../../docker-compose.yml),适合需要常驻服务的场景。
+
+```bash
+# 启动网关(后台常驻,自动重启)
+docker compose up -d phyagentos-gateway
+
+# 查看日志
+docker compose logs -f phyagentos-gateway
+
+# 进入交互式 CLI(独立 profile)
+docker compose run --rm phyagentos-cli
+```
+
+---
+
+## 🔧 直接使用 Docker(不用脚本)
+
+如需完全手动控制(`docker build` 需在**仓库根目录**执行):
+
+```bash
+# 构建
+docker build -t phyagentos:latest .
+
+# 初始化配置(首次)
+docker run --rm -v ~/.PhyAgentOS:/root/.PhyAgentOS phyagentos:latest onboard
+
+# 交互式 CLI
+docker run --rm -it -v ~/.PhyAgentOS:/root/.PhyAgentOS phyagentos:latest agent
+
+# 长驻网关(消息总线,仅外连,无需端口映射)
+docker run -d --name phyagentos-gateway \
+ -v ~/.PhyAgentOS:/root/.PhyAgentOS \
+ phyagentos:latest gateway
+```
+
+---
+
+## ⚠️ 已知限制
+
+### 1. 不包含托管 Forge Skill Runtime
+
+标准镜像没有 Dora CLI 或具体 Forge Runtime 制品。因此,除非显式扩展镜像并安装 Dora CLI
+v0.4.1、`dora-message` v0.7.0 与所选 Skill 的平台依赖,否则该镜像不支持
+`paos skill start`。仅使用 Agent 和消息渠道时不需要 Dora。
+
+### 2. 容器以 root 运行
+
+为保持与 `~/.PhyAgentOS:/root/.PhyAgentOS` 的卷挂载约定一致,镜像默认以 root 用户运行。如需生产硬化,建议后续添加非 root 用户与 healthcheck。
+
+### 3. 不含 GPU 支持
+
+本镜像为 CPU 版,不支持 Isaac Sim / BEHAVIOR-1K 等需要 CUDA 的仿真。如需 GPU,需改用 `nvidia/cuda` 基础镜像并以 `--gpus all` 运行。
+
+---
+
+## 🧯 排错
+
+| 现象 | 解决方案 |
+|:-----|:---------|
+| `docker: command not found` | 安装 Docker: |
+| `Cannot connect to the Docker daemon` | 启动 Docker Desktop 或 `sudo systemctl start docker` |
+| 构建 OOM / 过慢 | 增大 Docker 内存分配;首次构建需下载依赖,后续走缓存 |
+| `paos agent` 报 `No API key configured` | 编辑 `~/.PhyAgentOS/config.json` 填入 `apiKey` |
+| 网关启动后立即退出 | 多为缺 API Key;`./scripts/install.sh logs` 查看日志确认 |
+| 网关容器无法启动 | `docker rm -f phyagentos-gateway` 后重试 |
+
+---
+
+## 📚 相关文件
+
+- [`Dockerfile`](../../Dockerfile) — 镜像构建定义
+- [`docker-compose.yml`](../../docker-compose.yml) — Compose 编排
+- [`.dockerignore`](../../.dockerignore) — 构建忽略规则
+- [`scripts/install.sh`](../../scripts/install.sh) — 一键安装脚本
diff --git a/docs/user_manual/README.md b/docs/user_manual/README.md
index 0b64a33f4..24f6dab9a 100644
--- a/docs/user_manual/README.md
+++ b/docs/user_manual/README.md
@@ -1,60 +1,62 @@
-# PhyAgentOS 运行手册
+# PhyAgentOS Operations Manual
-[English](README_en.md) · [文档索引](../README.md)
+[English](README.md) | [简体中文](README_zh.md)
-> 版本:1.0.0
+> Version: 1.1.1
-## 1. 运行模型
+This is the operations reference for startup, reconciliation, stop, recovery and backups. Development starts with the [contribution guide](../../CONTRIBUTING.md). If the optional [interaction extension](../interaction/README.md) is enabled, also follow its journal/Runner ownership and shutdown limits; ordinary robot procedures do not replace them.
+
+## 1. Runtime model
```text
-用户/渠道 → AgentLoop → Forge task 与 Tool API tools
- │
- 绑定调用或诊断 Query
- ▼
- ForgeToolClient
- ▼
-Gateway /tools → ToolInvocation → ToolEndpoint → Dora → 机器人/仿真器
-
-绑定调用 → 不可变 Skill binding → AgentTask SQLite → verification/experience
+User/Channel → AgentLoop → Forge task and Tool API tools
+ │
+ bound call or diagnostic Query
+ ▼
+ ForgeToolClient
+ ▼
+Gateway /tools → ToolInvocation → ToolEndpoint → Dora → robot/simulator
+
+bound calls → immutable Skill binding → AgentTask SQLite → verification/experience
```
-Gateway 负责执行,PAOS 负责用户任务聚合与语义判定。Skill Runtime 负责已安装 Bundle profile
-的显式生命周期,但不替代 Gateway execution truth。
+Gateway owns execution. PAOS owns user-task aggregation and semantic verdicts. Skill Runtime owns
+the explicit lifecycle of installed Bundle profiles; it does not replace Gateway execution truth.
-## 2. 上线前检查
+## 2. Pre-deployment checks
-### PAOS 主机
+### PAOS host
-- 已安装 Python 3.11/3.12 和目标 v1.0.0 环境;
-- `paos status` 指向预期 config、workspace、model 和 provider;
-- Workspace、PAOS data paths 和 artifact paths 具备权限与磁盘空间;
-- 允许非 `off` 任务时,Verification provider 凭据可用。
+- Python 3.11 or 3.12 and the intended v1.1.1 environment are installed.
+- `paos status` resolves the expected config, workspace, model, and provider.
+- Workspace, PAOS data paths, and artifact paths have sufficient permissions and disk space.
+- Verification provider credentials are available when non-`off` tasks are allowed.
### Skill Runtime
-- Skill Bundle metadata 包含 size 与 SHA-256,每个 Node lock 具有精确 SHA-256,并能解析为大小
- 明确的直接下载;
-- required binaries 可执行,required assets 存在,required environment 已设置;
-- Dora CLI v0.4.1 与 `dora-message` v0.7.0(当前 Forge Skill 兼容基线)已安装且位于
- `PATH`,`dora --version` 同时指向预期版本;安装方式见
- [用户手册](../zh/02-user-manual.md#托管-skill-profile-所需的-dora-cli);
-- profile Gateway 地址没有被非托管进程占用。
+- Skill Bundle metadata includes size and SHA-256; every Node lock has an exact SHA-256 and resolves
+ to a sized direct download.
+- Required binaries are executable, required assets exist, and required environment variables are set.
+- Dora CLI v0.4.1 with `dora-message` v0.7.0, the current Forge Skill compatibility baseline, is
+ installed and on `PATH`; `dora --version` reports both expected versions. Installation is
+ documented in the [user manual](../en/02-user-manual.md#dora-cli-for-managed-skill-profiles).
+- The profile Gateway address is not occupied by an unmanaged process.
### Forge Gateway
-- `GET /tools` 返回成功 object envelope;
-- required ToolSpecs 与 `/tools/{tool_id}/context` 存在并 ready;
-- Endpoint operation `max_concurrency` 符合机器人安全并发;
-- ToolSpec semantics、schema、binding 和 readiness 与已安装 Skill manifest 一致。
+- `GET /tools` returns a successful object envelope.
+- Required ToolSpecs and `/tools/{tool_id}/context` are present and ready.
+- Endpoint operation `max_concurrency` matches the robot's safe concurrency.
+- ToolSpec semantics, schemas, bindings, and readiness match the installed Skill manifest.
-### 持久化
+### Persistence
-- `.paos/agent_tasks`、`.paos/evolution`、Agent conversation history 与 Skill Runtime state 位于可靠存储;
-- 轮转机器人证据时,备份和 retention 不删除 evolution 数据。
+- `.paos/agent_tasks`, `.paos/evolution`, Agent conversation history, and Skill Runtime state are on durable storage.
+- Backup and retention procedures do not delete evolution data when rotating robot evidence.
-## 3. 启动与健康检查
+## 3. Startup and health
-托管 Skill profile:
+For a managed Skill profile:
```bash
paos skill inspect
@@ -62,89 +64,94 @@ paos skill start --profile
paos skill status
paos skill switch --profile
paos agent
-# 或:paos gateway
+# or: paos gateway
```
-`paos skill start` 会运行 `dora check`,本地 coordinator 和 daemon 尚未 ready 时调用
-`dora up`;运维人员无需另行启动。Runtime 启动后,`dora check` 应当成功。
+`paos skill start` runs `dora check` and invokes `dora up` if the local coordinator and daemon are
+not ready; operators do not need to start them separately. After startup, `dora check` should
+succeed.
-Runtime 健康要求持久化状态为 `running`、命名 Dora flow 存活、Gateway `/tools` 可用,并且
-manifest 中每个 `required_tool` context ready。使用 `paos skill logs ` 查看生命周期和
-Dora launch 日志。仅在没有非终态 AgentTask 时允许切换 Runtime;目标通过 ready 校验后才会
-被选中,共用 Gateway 的目标启动失败时恢复先前 Runtime。长期运行的 Agent 会在下一次
-activation 或 Tool call 前跟随持久化选择。
+Healthy Runtime status requires persisted `running`, a live named Dora flow, Gateway `/tools`, and
+ready context for every Tool resolved from the selected profile's `required_tools` override, or the manifest-wide `required_tools` when the profile omits it. Use `paos skill logs ` for lifecycle and
+Dora launch logs. Runtime switching is permitted only with no non-terminal AgentTask; the target
+must become ready before selection, and a failed same-Gateway switch restores the previous
+Runtime. Long-running Agents follow the persisted selection before the next activation or Tool
+call.
-Agent 只使用该托管活动 Runtime 的 Gateway identity 与 URL。`paos status` 只检查本地配置;
-实时 Tool readiness 应使用 `forge_tool_context`。
+The Agent uses only the Gateway identity and URL of this managed active Runtime. `paos status`
+checks local configuration only; use `forge_tool_context` for live Tool readiness.
-## 4. 任务监控
+## 4. Task monitoring
-分别记录以下 identity:
+Record these identities separately:
-| Identity | 责任方 | 用途 |
-|:---------|:-------|:-----|
-| `task_id` | PAOS | 用户任务聚合与验证 |
-| `binding_id` | PAOS | 冻结的 Skill 版本、Runtime 与 ToolSpec 集合 |
-| `revision_id` | PAOS | 只追加规划世代 |
-| `record_id` | PAOS | 一次绑定 Query、Action 或 Session record |
-| `caller_id` | PAOS | 异步 admission 前持久化的身份 |
-| `invocation_id` | Gateway | 一次异步 Action 或 Session 生命周期 |
-| `attempt_id` | Gateway | 一次执行尝试 |
+| Identity | Owner | Use |
+|:---------|:------|:----|
+| `task_id` | PAOS | User-visible aggregate and verification |
+| `binding_id` | PAOS | Frozen Skill version, Runtime, and ToolSpec set |
+| `revision_id` | PAOS | Append-only planning generation |
+| `record_id` | PAOS | One bound Query, Action, or Session record |
+| `caller_id` | PAOS | Persisted before asynchronous admission |
+| `invocation_id` | Gateway | One asynchronous Action or Session lifecycle |
+| `attempt_id` | Gateway | One execution attempt |
-使用 `forge_task_get(task_id)` 读取聚合状态与 Tool records;使用
-对应 task-bound Action 或 Session status/result tool 读取执行事实。result endpoint 在 pending
-时可以返回 HTTP 202。
+Use `forge_task_get(task_id)` for aggregate state and Tool records. Use
+the task-bound Action or Session status/result tools for execution truth. A result endpoint may
+return HTTP 202 while pending.
-任务状态:
+Expected task states:
-| 状态 | 运维含义 |
-|:-----|:---------|
-| `executing` | 规划或绑定 Tool calls 仍在继续。 |
-| `cancelling` | 已请求取消,但尚未证明物理停止。 |
-| `awaiting_replan` | Verification 允许在 deadline 前追加有预算 PlanRevision。 |
-| `succeeded` / `failed` / `cancelled` | PAOS 聚合终结;必要时仍独立检查 invocation facts。 |
+| State | Operator meaning |
+|:------|:-----------------|
+| `executing` | Planning or bound Tool calls continue. |
+| `cancelling` | Cancellation was requested; physical stop is not yet proven. |
+| `awaiting_replan` | Verification permits a bounded new PlanRevision before its deadline. |
+| `succeeded` / `failed` / `cancelled` | PAOS aggregate is terminal. Inspect invocation facts separately when needed. |
-## 5. 取消与停止
+## 5. Cancellation and stop
-取消单个 Action 时调用 `forge_tool_cancel_action(task_id, invocation_id)`,随后继续核对 status/result。
-取消一个任务的全部 Action 时调用 `forge_task_cancel(task_id, reason)`,核对每个 invocation,
-物理效果不确定时检查现场。Task cancel 同时停止 task-owned Session;shared 与 runtime-owned
-Session 保持各自独立生命周期。
+For one Action, call `forge_tool_cancel_action(task_id, invocation_id)`, then continue status/result
+reconciliation. For all Actions bound to a task, call `forge_task_cancel(task_id, reason)`, reconcile
+each invocation, and inspect physical state when effects are uncertain. Task cancellation also
+stops task-owned Sessions; shared and runtime-owned Sessions retain their independent lifecycle.
-绝不能把 `requested`、`accepted`、timeout 或 `unknown` 报告成物理停止证明。效果核实完成前
-不要重试运动。
+Never report `requested`, `accepted`, a timeout, or `unknown` as proof of physical stop. Do not
+retry the motion until effect reconciliation is complete.
-被追踪 invocation、Session 全部终结且无 task binding 后再停止托管 Runtime:
+Stop a managed Runtime only after tracked invocations and Sessions are terminal and no task binding remains:
```bash
paos skill stop
```
-`--force` 只供已独立评估物理系统的运维人员使用。停止托管 Dora flow 前,它会尽力向已追踪
-Action/Session 发出 cancel/stop,并把请求结果与未决引用写入 Runtime audit。请求被接受不证明
-执行已终止,也不会改写 Gateway invocation result。
+`--force` is reserved for an operator who has independently assessed the physical system. Before
+stopping the managed Dora flow it makes best-effort cancel/stop requests for tracked Actions and
+Sessions, then records each request and unresolved reference in the Runtime audit. Acceptance does
+not prove termination and Gateway invocation results are not rewritten.
-## 6. 正常停机
+## 6. Graceful shutdown
-1. 停止接纳新用户任务;
-2. 读取活动 AgentTask 并核对每个 Action/Session invocation;
-3. Finalize,或 cancel 后 finalize AgentTask;
-4. 停止 PAOS channels 或 Agent;
-5. 停止 Skill Runtime profile;
-6. 只有没有其他 profile 使用时才停止共享基础设施。
+1. Stop admitting new user tasks.
+2. Read the active AgentTask and reconcile every Action/Session invocation.
+3. Finalize or cancel/finalize the AgentTask.
+4. Stop PAOS channels or Agent.
+5. Stop the Skill Runtime profile.
+6. Stop shared infrastructure only if no other profile uses it.
-## 7. 异常重启
+## 7. Crash restart
-PAOS 重启后,用已知 `task_id` 打开持久化 AgentTask。不要根据本地 intent 重建或重发 Action/Session。
-查询每个已保存 `invocation_id`,根据 Gateway status/result 更新 record。Gateway 无法解析
-invocation 时,将效果视为 unknown 并升级到物理现场检查。
+After a PAOS restart, open the persisted AgentTask with its known `task_id`. Do not recreate or
+resubmit an Action or Session from local intent. Query every persisted `invocation_id` and update the record
+from Gateway status/result. If Gateway can no longer resolve an invocation, treat the effect as
+unknown and escalate to physical-state inspection.
-`paos skill status ` 会根据 Dora 与 Gateway health 核对 Runtime state。当 flow 或 Tool
-contexts 不可用时,它可将持久化 starting/running 改为 failed;重新启动前先诊断原 flow。
+`paos skill status ` reconciles Runtime state against Dora and Gateway health. It can move a
+persisted starting/running state to failed when the flow or Tool contexts are unavailable; restart
+only after diagnosing the previous flow.
-## 8. 备份与磁盘管理
+## 8. Backup and disk management
-停止 PAOS 后,将数据库、WAL/SHM 和引用目录一起备份:
+With PAOS stopped, back up the database together with WAL/SHM files and the referenced trees:
```text
/.paos/agent_tasks/tasks.sqlite3*
@@ -154,39 +161,39 @@ contexts 不可用时,它可将持久化 starting/running 改为 failed;重
/skills/
```
-还应按部署的 PAOS data-path 策略保留 installed Bundle/Node manifest、Runtime state 与生命周期
-日志。Evidence retention 可以在验证后清理实体文件,但不能删除 task records、invocation
-references 或 evolution 历史。
-
-## 9. 故障分层
-
-| 层级 | 常见现象 | 首要处置 |
-|:-----|:---------|:---------|
-| Registry/install | Digest、size、manifest 或 lock 失败 | 修正可信 metadata 或 artifact,不绕过校验。 |
-| Runtime | Dora flow 或 Gateway health 不可用 | 检查 `paos skill status` 与 `logs`。 |
-| Tool context | Tool 缺失、未绑定或未 ready | 检查 ToolSpec、Endpoint、frame 与 required profile。 |
-| Admission | HTTP/contract 失败 | 保留响应中已有 invocation ID,判断 Gateway 是否接纳。 |
-| Execution | pending、failed、cancelled 或 unknown | 使用相同 invocation ID 核对;不确定时检查现场。 |
-| Evidence | before/after source 缺失 | 检查 source readiness 与 bundle errors,ToolResult 仍为权威。 |
-| Verification | invalid/inconclusive/service error | 检查任务契约、evidence、provider 与 mode。 |
-| Evolution | reflection 或 promotion blocked | 检查 evolution events;执行不受影响。 |
-
-## 10. 运行验收清单
-
-- [ ] Package 与 runtime version 均为 1.0.0;
-- [ ] 通用 Agent tools 与动态 MCP tools 仍注册;
-- [ ] 所需 Skill Bundle 与全部 Node artifact 校验通过;
-- [ ] 托管 Runtime ready,所有 Tool contexts 健康;
-- [ ] 诊断 Query 与绑定 Query/Action/Session 使用同一 Gateway Tool API;
-- [ ] 已覆盖 Action/Session admission、pending、terminal、cancel/stop、timeout、ownership 与 unknown;
-- [ ] 已覆盖单活动 AgentTask 与 PlanRevision recovery;
-- [ ] 绑定工作流完成 evidence 与任务级 verification;
-- [ ] Experience 记录 AgentTask、Skill activation、verification 与 invocation references;
-- [ ] 备份包含 AgentTask 与 evolution 持久化;
-- [ ] 具体 Skill/硬件验收单独记录确切 assets、nodes 与环境。
-
-## 后续阅读
-
-- [用户手册](../zh/02-user-manual.md)
-- [通信架构](../user_development_guide/COMMUNICATION.md)
-- [Forge Tool API 契约](../forge/README_zh.md)
+Also retain installed Bundle/Node manifests, Runtime state, and lifecycle logs according to the
+deployment's PAOS data-path policy. Evidence retention may prune entity files after verification;
+it must not remove task records, invocation references, or evolution history.
+
+## 9. Failure layers
+
+| Layer | Typical symptom | First action |
+|:------|:----------------|:-------------|
+| Registry/install | Digest, size, manifest, or lock failure | Correct the signed metadata or artifact; do not bypass validation. |
+| Runtime | Dora flow or Gateway health unavailable | Inspect `paos skill status` and `logs`. |
+| Tool context | Tool missing, unbound, or not ready | Inspect ToolSpec, Endpoint, frame, and required profile. |
+| Admission | HTTP/contract failure | Preserve any returned invocation ID; determine whether Gateway accepted work. |
+| Execution | pending, failed, cancelled, or unknown | Reconcile using the same invocation ID and inspect physical state when uncertain. |
+| Evidence | before/after source missing | Inspect source readiness and bundle errors; keep ToolResult authoritative. |
+| Verification | invalid/inconclusive/service error | Inspect task contract, evidence, provider, and mode semantics. |
+| Evolution | reflection or promotion blocked | Inspect evolution events; execution remains unaffected. |
+
+## 10. Operational acceptance checklist
+
+- [ ] Package and runtime version report 1.1.1.
+- [ ] General Agent tools and dynamic MCP tools remain registered.
+- [ ] Required Skill Bundle and all node artifacts verify.
+- [ ] Managed Runtime reaches ready and all Tool contexts are healthy.
+- [ ] Diagnostic Query and bound Query/Action/Session use the same Gateway Tool API.
+- [ ] Action/Session admission, pending, terminal, cancel/stop, timeout, ownership, and unknown behavior are exercised.
+- [ ] One-active-AgentTask enforcement and PlanRevision recovery are exercised.
+- [ ] Evidence and task-level verification complete for a bound workflow.
+- [ ] Experience records AgentTask, Skill activation, verification, and invocation references.
+- [ ] Backups include AgentTask and evolution persistence.
+- [ ] Concrete Skill/hardware acceptance is recorded separately with exact assets, nodes, and environment.
+
+## Next reading
+
+- [User Manual](../en/02-user-manual.md)
+- [Core Communication Architecture](../user_development_guide/COMMUNICATION.md)
+- [Forge Tool API Contract](../forge/README.md)
diff --git a/docs/user_manual/README_en.md b/docs/user_manual/README_en.md
deleted file mode 100644
index 99987d6c7..000000000
--- a/docs/user_manual/README_en.md
+++ /dev/null
@@ -1,197 +0,0 @@
-# PhyAgentOS Operations Manual
-
-[中文](README.md) · [Documentation index](../README.md)
-
-> Version: 1.0.0
-
-## 1. Runtime model
-
-```text
-User/Channel → AgentLoop → Forge task and Tool API tools
- │
- bound call or diagnostic Query
- ▼
- ForgeToolClient
- ▼
-Gateway /tools → ToolInvocation → ToolEndpoint → Dora → robot/simulator
-
-bound calls → immutable Skill binding → AgentTask SQLite → verification/experience
-```
-
-Gateway owns execution. PAOS owns user-task aggregation and semantic verdicts. Skill Runtime owns
-the explicit lifecycle of installed Bundle profiles; it does not replace Gateway execution truth.
-
-## 2. Pre-deployment checks
-
-### PAOS host
-
-- Python 3.11 or 3.12 and the intended v1.0.0 environment are installed.
-- `paos status` resolves the expected config, workspace, model, and provider.
-- Workspace, PAOS data paths, and artifact paths have sufficient permissions and disk space.
-- Verification provider credentials are available when non-`off` tasks are allowed.
-
-### Skill Runtime
-
-- Skill Bundle metadata includes size and SHA-256; every Node lock has an exact SHA-256 and resolves
- to a sized direct download.
-- Required binaries are executable, required assets exist, and required environment variables are set.
-- Dora CLI v0.4.1 with `dora-message` v0.7.0, the current Forge Skill compatibility baseline, is
- installed and on `PATH`; `dora --version` reports both expected versions. Installation is
- documented in the [user manual](../en/02-user-manual.md#dora-cli-for-managed-skill-profiles).
-- The profile Gateway address is not occupied by an unmanaged process.
-
-### Forge Gateway
-
-- `GET /tools` returns a successful object envelope.
-- Required ToolSpecs and `/tools/{tool_id}/context` are present and ready.
-- Endpoint operation `max_concurrency` matches the robot's safe concurrency.
-- ToolSpec semantics, schemas, bindings, and readiness match the installed Skill manifest.
-
-### Persistence
-
-- `.paos/agent_tasks`, `.paos/evolution`, Agent conversation history, and Skill Runtime state are on durable storage.
-- Backup and retention procedures do not delete evolution data when rotating robot evidence.
-
-## 3. Startup and health
-
-For a managed Skill profile:
-
-```bash
-paos skill inspect
-paos skill start --profile
-paos skill status
-paos skill switch --profile
-paos agent
-# or: paos gateway
-```
-
-`paos skill start` runs `dora check` and invokes `dora up` if the local coordinator and daemon are
-not ready; operators do not need to start them separately. After startup, `dora check` should
-succeed.
-
-Healthy Runtime status requires persisted `running`, a live named Dora flow, Gateway `/tools`, and
-ready context for every manifest `required_tool`. Use `paos skill logs ` for lifecycle and
-Dora launch logs. Runtime switching is permitted only with no non-terminal AgentTask; the target
-must become ready before selection, and a failed same-Gateway switch restores the previous
-Runtime. Long-running Agents follow the persisted selection before the next activation or Tool
-call.
-
-The Agent uses only the Gateway identity and URL of this managed active Runtime. `paos status`
-checks local configuration only; use `forge_tool_context` for live Tool readiness.
-
-## 4. Task monitoring
-
-Record these identities separately:
-
-| Identity | Owner | Use |
-|:---------|:------|:----|
-| `task_id` | PAOS | User-visible aggregate and verification |
-| `binding_id` | PAOS | Frozen Skill version, Runtime, and ToolSpec set |
-| `revision_id` | PAOS | Append-only planning generation |
-| `record_id` | PAOS | One bound Query, Action, or Session record |
-| `caller_id` | PAOS | Persisted before asynchronous admission |
-| `invocation_id` | Gateway | One asynchronous Action or Session lifecycle |
-| `attempt_id` | Gateway | One execution attempt |
-
-Use `forge_task_get(task_id)` for aggregate state and Tool records. Use
-the task-bound Action or Session status/result tools for execution truth. A result endpoint may
-return HTTP 202 while pending.
-
-Expected task states:
-
-| State | Operator meaning |
-|:------|:-----------------|
-| `executing` | Planning or bound Tool calls continue. |
-| `cancelling` | Cancellation was requested; physical stop is not yet proven. |
-| `awaiting_replan` | Verification permits a bounded new PlanRevision before its deadline. |
-| `succeeded` / `failed` / `cancelled` | PAOS aggregate is terminal. Inspect invocation facts separately when needed. |
-
-## 5. Cancellation and stop
-
-For one Action, call `forge_tool_cancel_action(task_id, invocation_id)`, then continue status/result
-reconciliation. For all Actions bound to a task, call `forge_task_cancel(task_id, reason)`, reconcile
-each invocation, and inspect physical state when effects are uncertain. Task cancellation also
-stops task-owned Sessions; shared and runtime-owned Sessions retain their independent lifecycle.
-
-Never report `requested`, `accepted`, a timeout, or `unknown` as proof of physical stop. Do not
-retry the motion until effect reconciliation is complete.
-
-Stop a managed Runtime only after tracked invocations and Sessions are terminal and no task binding remains:
-
-```bash
-paos skill stop
-```
-
-`--force` is reserved for an operator who has independently assessed the physical system. Before
-stopping the managed Dora flow it makes best-effort cancel/stop requests for tracked Actions and
-Sessions, then records each request and unresolved reference in the Runtime audit. Acceptance does
-not prove termination and Gateway invocation results are not rewritten.
-
-## 6. Graceful shutdown
-
-1. Stop admitting new user tasks.
-2. Read the active AgentTask and reconcile every Action/Session invocation.
-3. Finalize or cancel/finalize the AgentTask.
-4. Stop PAOS channels or Agent.
-5. Stop the Skill Runtime profile.
-6. Stop shared infrastructure only if no other profile uses it.
-
-## 7. Crash restart
-
-After a PAOS restart, open the persisted AgentTask with its known `task_id`. Do not recreate or
-resubmit an Action or Session from local intent. Query every persisted `invocation_id` and update the record
-from Gateway status/result. If Gateway can no longer resolve an invocation, treat the effect as
-unknown and escalate to physical-state inspection.
-
-`paos skill status ` reconciles Runtime state against Dora and Gateway health. It can move a
-persisted starting/running state to failed when the flow or Tool contexts are unavailable; restart
-only after diagnosing the previous flow.
-
-## 8. Backup and disk management
-
-With PAOS stopped, back up the database together with WAL/SHM files and the referenced trees:
-
-```text
-/.paos/agent_tasks/tasks.sqlite3*
-/.paos/evolution/experience.sqlite3*
-/.paos/evolution/revisions/
-/artifacts/agent_tasks/
-/skills/
-```
-
-Also retain installed Bundle/Node manifests, Runtime state, and lifecycle logs according to the
-deployment's PAOS data-path policy. Evidence retention may prune entity files after verification;
-it must not remove task records, invocation references, or evolution history.
-
-## 9. Failure layers
-
-| Layer | Typical symptom | First action |
-|:------|:----------------|:-------------|
-| Registry/install | Digest, size, manifest, or lock failure | Correct the signed metadata or artifact; do not bypass validation. |
-| Runtime | Dora flow or Gateway health unavailable | Inspect `paos skill status` and `logs`. |
-| Tool context | Tool missing, unbound, or not ready | Inspect ToolSpec, Endpoint, frame, and required profile. |
-| Admission | HTTP/contract failure | Preserve any returned invocation ID; determine whether Gateway accepted work. |
-| Execution | pending, failed, cancelled, or unknown | Reconcile using the same invocation ID and inspect physical state when uncertain. |
-| Evidence | before/after source missing | Inspect source readiness and bundle errors; keep ToolResult authoritative. |
-| Verification | invalid/inconclusive/service error | Inspect task contract, evidence, provider, and mode semantics. |
-| Evolution | reflection or promotion blocked | Inspect evolution events; execution remains unaffected. |
-
-## 10. Operational acceptance checklist
-
-- [ ] Package and runtime version report 1.0.0.
-- [ ] General Agent tools and dynamic MCP tools remain registered.
-- [ ] Required Skill Bundle and all node artifacts verify.
-- [ ] Managed Runtime reaches ready and all Tool contexts are healthy.
-- [ ] Diagnostic Query and bound Query/Action/Session use the same Gateway Tool API.
-- [ ] Action/Session admission, pending, terminal, cancel/stop, timeout, ownership, and unknown behavior are exercised.
-- [ ] One-active-AgentTask enforcement and PlanRevision recovery are exercised.
-- [ ] Evidence and task-level verification complete for a bound workflow.
-- [ ] Experience records AgentTask, Skill activation, verification, and invocation references.
-- [ ] Backups include AgentTask and evolution persistence.
-- [ ] Concrete Skill/hardware acceptance is recorded separately with exact assets, nodes, and environment.
-
-## Next reading
-
-- [User Manual](../en/02-user-manual.md)
-- [Communication Architecture](../user_development_guide/COMMUNICATION_en.md)
-- [Forge Tool API Contract](../forge/README.md)
diff --git a/docs/user_manual/README_zh.md b/docs/user_manual/README_zh.md
new file mode 100644
index 000000000..8d37d4bf7
--- /dev/null
+++ b/docs/user_manual/README_zh.md
@@ -0,0 +1,194 @@
+# PhyAgentOS 运行手册
+
+[English](README.md) | [简体中文](README_zh.md)
+
+> 版本:1.1.1
+
+本文是启动、核对、停止、恢复与备份的运行参考。开发请从[贡献指南](../../CONTRIBUTING_zh.md)开始。若启用可选[交互扩展](../interaction/README_zh.md),还需遵循其 journal/Runner 所有权与停机限制,普通机器人流程不替代这些要求。
+
+## 1. 运行模型
+
+```text
+用户/渠道 → AgentLoop → Forge task 与 Tool API tools
+ │
+ 绑定调用或诊断 Query
+ ▼
+ ForgeToolClient
+ ▼
+Gateway /tools → ToolInvocation → ToolEndpoint → Dora → 机器人/仿真器
+
+绑定调用 → 不可变 Skill binding → AgentTask SQLite → verification/experience
+```
+
+Gateway 负责执行,PAOS 负责用户任务聚合与语义判定。Skill Runtime 负责已安装 Bundle profile
+的显式生命周期,但不替代 Gateway execution truth。
+
+## 2. 上线前检查
+
+### PAOS 主机
+
+- 已安装 Python 3.11/3.12 和目标 v1.1.1 环境;
+- `paos status` 指向预期 config、workspace、model 和 provider;
+- Workspace、PAOS data paths 和 artifact paths 具备权限与磁盘空间;
+- 允许非 `off` 任务时,Verification provider 凭据可用。
+
+### Skill Runtime
+
+- Skill Bundle metadata 包含 size 与 SHA-256,每个 Node lock 具有精确 SHA-256,并能解析为大小
+ 明确的直接下载;
+- required binaries 可执行,required assets 存在,required environment 已设置;
+- Dora CLI v0.4.1 与 `dora-message` v0.7.0(当前 Forge Skill 兼容基线)已安装且位于
+ `PATH`,`dora --version` 同时指向预期版本;安装方式见
+ [用户手册](../zh/02-user-manual.md#托管-skill-profile-所需的-dora-cli);
+- profile Gateway 地址没有被非托管进程占用。
+
+### Forge Gateway
+
+- `GET /tools` 返回成功 object envelope;
+- required ToolSpecs 与 `/tools/{tool_id}/context` 存在并 ready;
+- Endpoint operation `max_concurrency` 符合机器人安全并发;
+- ToolSpec semantics、schema、binding 和 readiness 与已安装 Skill manifest 一致。
+
+### 持久化
+
+- `.paos/agent_tasks`、`.paos/evolution`、Agent conversation history 与 Skill Runtime state 位于可靠存储;
+- 轮转机器人证据时,备份和 retention 不删除 evolution 数据。
+
+## 3. 启动与健康检查
+
+托管 Skill profile:
+
+```bash
+paos skill inspect
+paos skill start --profile
+paos skill status
+paos skill switch --profile
+paos agent
+# 或:paos gateway
+```
+
+`paos skill start` 会运行 `dora check`,本地 coordinator 和 daemon 尚未 ready 时调用
+`dora up`;运维人员无需另行启动。Runtime 启动后,`dora check` 应当成功。
+
+Runtime 健康要求持久化状态为 `running`、命名 Dora flow 存活、Gateway `/tools` 可用,并且
+所选 profile 的 `required_tools`(未配置时继承 manifest-wide `required_tools`)全部 context ready。使用 `paos skill logs ` 查看生命周期和
+Dora launch 日志。仅在没有非终态 AgentTask 时允许切换 Runtime;目标通过 ready 校验后才会
+被选中,共用 Gateway 的目标启动失败时恢复先前 Runtime。长期运行的 Agent 会在下一次
+activation 或 Tool call 前跟随持久化选择。
+
+Agent 只使用该托管活动 Runtime 的 Gateway identity 与 URL。`paos status` 只检查本地配置;
+实时 Tool readiness 应使用 `forge_tool_context`。
+
+## 4. 任务监控
+
+分别记录以下 identity:
+
+| Identity | 责任方 | 用途 |
+|:---------|:-------|:-----|
+| `task_id` | PAOS | 用户任务聚合与验证 |
+| `binding_id` | PAOS | 冻结的 Skill 版本、Runtime 与 ToolSpec 集合 |
+| `revision_id` | PAOS | 只追加规划世代 |
+| `record_id` | PAOS | 一次绑定 Query、Action 或 Session record |
+| `caller_id` | PAOS | 异步 admission 前持久化的身份 |
+| `invocation_id` | Gateway | 一次异步 Action 或 Session 生命周期 |
+| `attempt_id` | Gateway | 一次执行尝试 |
+
+使用 `forge_task_get(task_id)` 读取聚合状态与 Tool records;使用
+对应 task-bound Action 或 Session status/result tool 读取执行事实。result endpoint 在 pending
+时可以返回 HTTP 202。
+
+任务状态:
+
+| 状态 | 运维含义 |
+|:-----|:---------|
+| `executing` | 规划或绑定 Tool calls 仍在继续。 |
+| `cancelling` | 已请求取消,但尚未证明物理停止。 |
+| `awaiting_replan` | Verification 允许在 deadline 前追加有预算 PlanRevision。 |
+| `succeeded` / `failed` / `cancelled` | PAOS 聚合终结;必要时仍独立检查 invocation facts。 |
+
+## 5. 取消与停止
+
+取消单个 Action 时调用 `forge_tool_cancel_action(task_id, invocation_id)`,随后继续核对 status/result。
+取消一个任务的全部 Action 时调用 `forge_task_cancel(task_id, reason)`,核对每个 invocation,
+物理效果不确定时检查现场。Task cancel 同时停止 task-owned Session;shared 与 runtime-owned
+Session 保持各自独立生命周期。
+
+绝不能把 `requested`、`accepted`、timeout 或 `unknown` 报告成物理停止证明。效果核实完成前
+不要重试运动。
+
+被追踪 invocation、Session 全部终结且无 task binding 后再停止托管 Runtime:
+
+```bash
+paos skill stop
+```
+
+`--force` 只供已独立评估物理系统的运维人员使用。停止托管 Dora flow 前,它会尽力向已追踪
+Action/Session 发出 cancel/stop,并把请求结果与未决引用写入 Runtime audit。请求被接受不证明
+执行已终止,也不会改写 Gateway invocation result。
+
+## 6. 正常停机
+
+1. 停止接纳新用户任务;
+2. 读取活动 AgentTask 并核对每个 Action/Session invocation;
+3. Finalize,或 cancel 后 finalize AgentTask;
+4. 停止 PAOS channels 或 Agent;
+5. 停止 Skill Runtime profile;
+6. 只有没有其他 profile 使用时才停止共享基础设施。
+
+## 7. 异常重启
+
+PAOS 重启后,用已知 `task_id` 打开持久化 AgentTask。不要根据本地 intent 重建或重发 Action/Session。
+查询每个已保存 `invocation_id`,根据 Gateway status/result 更新 record。Gateway 无法解析
+invocation 时,将效果视为 unknown 并升级到物理现场检查。
+
+`paos skill status ` 会根据 Dora 与 Gateway health 核对 Runtime state。当 flow 或 Tool
+contexts 不可用时,它可将持久化 starting/running 改为 failed;重新启动前先诊断原 flow。
+
+## 8. 备份与磁盘管理
+
+停止 PAOS 后,将数据库、WAL/SHM 和引用目录一起备份:
+
+```text
+/.paos/agent_tasks/tasks.sqlite3*
+/.paos/evolution/experience.sqlite3*
+/.paos/evolution/revisions/
+/artifacts/agent_tasks/
+/skills/
+```
+
+还应按部署的 PAOS data-path 策略保留 installed Bundle/Node manifest、Runtime state 与生命周期
+日志。Evidence retention 可以在验证后清理实体文件,但不能删除 task records、invocation
+references 或 evolution 历史。
+
+## 9. 故障分层
+
+| 层级 | 常见现象 | 首要处置 |
+|:-----|:---------|:---------|
+| Registry/install | Digest、size、manifest 或 lock 失败 | 修正可信 metadata 或 artifact,不绕过校验。 |
+| Runtime | Dora flow 或 Gateway health 不可用 | 检查 `paos skill status` 与 `logs`。 |
+| Tool context | Tool 缺失、未绑定或未 ready | 检查 ToolSpec、Endpoint、frame 与 required profile。 |
+| Admission | HTTP/contract 失败 | 保留响应中已有 invocation ID,判断 Gateway 是否接纳。 |
+| Execution | pending、failed、cancelled 或 unknown | 使用相同 invocation ID 核对;不确定时检查现场。 |
+| Evidence | before/after source 缺失 | 检查 source readiness 与 bundle errors,ToolResult 仍为权威。 |
+| Verification | invalid/inconclusive/service error | 检查任务契约、evidence、provider 与 mode。 |
+| Evolution | reflection 或 promotion blocked | 检查 evolution events;执行不受影响。 |
+
+## 10. 运行验收清单
+
+- [ ] Package 与 runtime version 均为 1.1.1;
+- [ ] 通用 Agent tools 与动态 MCP tools 仍注册;
+- [ ] 所需 Skill Bundle 与全部 Node artifact 校验通过;
+- [ ] 托管 Runtime ready,所有 Tool contexts 健康;
+- [ ] 诊断 Query 与绑定 Query/Action/Session 使用同一 Gateway Tool API;
+- [ ] 已覆盖 Action/Session admission、pending、terminal、cancel/stop、timeout、ownership 与 unknown;
+- [ ] 已覆盖单活动 AgentTask 与 PlanRevision recovery;
+- [ ] 绑定工作流完成 evidence 与任务级 verification;
+- [ ] Experience 记录 AgentTask、Skill activation、verification 与 invocation references;
+- [ ] 备份包含 AgentTask 与 evolution 持久化;
+- [ ] 具体 Skill/硬件验收单独记录确切 assets、nodes 与环境。
+
+## 后续阅读
+
+- [用户手册](../zh/02-user-manual.md)
+- [Core 通信架构](../user_development_guide/COMMUNICATION_zh.md)
+- [Forge Tool API 契约](../forge/README_zh.md)
diff --git a/docs/zh/01-framework-introduction.md b/docs/zh/01-framework-introduction.md
index 2bca8bdb3..d4f3d134b 100644
--- a/docs/zh/01-framework-introduction.md
+++ b/docs/zh/01-framework-introduction.md
@@ -1,8 +1,8 @@
# PhyAgentOS 框架介绍
-[English](../en/01-framework-introduction.md) · [文档索引](../README.md)
+[English](../en/01-framework-introduction.md) · [文档索引](../README_zh.md)
-> 文档版本:1.0.0 · 实现基线:2026-08-30 源码、配置 Schema 与测试。
+> 文档版本:1.1.1 · 实现基线:2026-10-23 源码、配置 Schema 与测试。
## 1. 项目定位
@@ -165,6 +165,6 @@ Runtime 清理不会删除现有 evolution 数据。
## 后续阅读
- [用户手册](02-user-manual.md)
-- [开发者手册](03-developer-manual.md)
+- [Core 开发者手册](03-developer-manual.md)
- [Forge Tool API 接入契约](../forge/README_zh.md)
- [Agent 经验与 Skill 自进化](05-agent-experience-and-skill-evolution.md)
diff --git a/docs/zh/02-user-manual.md b/docs/zh/02-user-manual.md
index 688e02a89..b25a23100 100644
--- a/docs/zh/02-user-manual.md
+++ b/docs/zh/02-user-manual.md
@@ -1,8 +1,8 @@
# PhyAgentOS 用户手册
-[English](../en/02-user-manual.md) · [文档索引](../README.md)
+[English](../en/02-user-manual.md) · [文档索引](../README_zh.md)
-> 文档版本:1.0.0。
+> 文档版本:1.1.1。
## 1. 安装与初始化
@@ -31,7 +31,7 @@ ruff check PhyAgentOS tests
运行通用 Agent、搜索 Skill 或完成 `paos skill install` 不需要 Dora。`paos skill start` 需要
主机预先安装 Dora CLI,因为 RuntimeManager 使用 `dora` 命令管理所选 profile。PhyAgentOS
-1.0.0 以 Dora CLI v0.4.1 及 `dora-message` v0.7.0 作为 Forge Skill 兼容基线;可复现部署
+1.1.1 以 Dora CLI v0.4.1 及 `dora-message` v0.7.0 作为 Forge Skill 兼容基线;可复现部署
应固定该精确版本。
Linux 或 macOS 使用带版本的官方 installer:
@@ -173,7 +173,7 @@ Custom endpoint 或 Azure 部署别名的能力未知时应使用 `none`;显
从 `minimal / low / medium / high / xhigh / max` 中仅展示支持的档位。
额外档位需要本地目录明确支持且适配器可映射;网关可选档位可能与原厂接口不同。
支持 `max` 的自适应 Claude 使用 `output_config.effort`,传统 Claude 使用思考预算。
-`none` 始终表示模型默认行为,不代表关闭思考。详见[推理强度](reasoning-effort.md)。
+`none` 始终表示模型默认行为,不代表关闭思考。详见[Provider、模型与推理强度配置](#2-配置模型与-forge)。
**Requesty 的推理强度限制:** 当前 PAOS 的 Requesty 接入尚不支持显式推理强度档位。
即使所选模型本身支持推理,`high` 等覆盖值仍会被 PAOS 的本地能力校验拒绝,请求不会发送到
@@ -218,6 +218,20 @@ paos provider use api_route --model gpt-6.1-sol --reasoning-effort none
`/model `,填写密钥可用且不带厂商前缀的模型 ID。未设置
`providers.api_route.defaultModel` 时,切换 Provider 会沿用原模型,包括其厂商前缀。
+**[Opper](https://opper.ai)**(`opper`)使用相同的网关配置方式。在 https://platform.opper.ai
+创建密钥,填入 `providers.opper.apiKey`,或在启动时提供 `OPPER_API_KEY` /
+`PAOS_OPPER_API_KEY`。默认地址为 `https://api.opper.ai/v3/compat`。模型 ID 可以填写
+`claude-sonnet-4-6`、`gpt-5.4-mini` 这类模型池名称,由 Opper 在提供该模型的服务商之间路由;
+也可以填写 `anthropic/claude-sonnet-4-6` 这类 `provider/model` ID,固定使用某一条路由。
+本接入同样沿用 PAOS 对网关推理强度的保守校验,选择时请清除显式推理强度:
+
+```bash
+paos provider use opper --model claude-sonnet-4-6 --reasoning-effort none
+```
+
+在已有会话中,依次执行 `/effort none`、`/provider opper`,然后执行 `/model `。
+未设置 `providers.opper.defaultModel` 时,切换 Provider 会沿用原模型 ID。
+
优先级为 **会话覆盖 → 进程启动参数 → 配置默认值**。每轮请求及其重试、工具调用固定使用
开始时的 Provider、模型和思考程度。切换只影响同一会话的后续请求;其他会话、正在运行的
子 Agent、Forge 任务、verification、evolution、记忆整理、Cron 和 Heartbeat 继续使用启动配置。
@@ -465,5 +479,5 @@ evidence。Evolution fail-open,反思错误不会改变执行或验证。
## 后续阅读
- [Forge 配置参考](04-forge-configuration-reference.md)
-- [运行手册](../user_manual/README.md)
+- [运行手册](../user_manual/README_zh.md)
- [Forge Tool API 接入契约](../forge/README_zh.md)
diff --git a/docs/zh/03-developer-manual.md b/docs/zh/03-developer-manual.md
index 72aba8f41..125447640 100644
--- a/docs/zh/03-developer-manual.md
+++ b/docs/zh/03-developer-manual.md
@@ -1,8 +1,10 @@
-# PhyAgentOS 开发者手册
+# PhyAgentOS Core 开发者手册
-[English](../en/03-developer-manual.md) · [文档索引](../README.md)
+[English](../en/03-developer-manual.md) · [文档索引](../README_zh.md)
-> 文档版本:1.0.0。
+> 文档版本:1.1.1。
+
+本文面向 Core 实现:AgentTask 协调、持久化、binding、验证和 Runtime 管理。机器人、Node 与 Skill 开发请从 [TrackB 框架说明](../user_development_guide/track_b/README_zh.md)开始。HTTP 路由、身份和生命周期语义以 [Forge Tool API 契约](../forge/README_zh.md)为准。
## 1. 开发不变量
@@ -33,18 +35,7 @@
`ForgeToolClient` 只接受 `ok=true` 且 `data` 为 object 的 JSON envelope。错误保留 HTTP status、
error code、retryability 以及响应中已有的 invocation identity。
-| 操作 | HTTP 契约 |
-|:-----|:----------|
-| 列出 Tools | `GET /tools` → 200 |
-| 读取 ToolSpec | `GET /tools/{tool_id}` → 200 |
-| 读取 context | `GET /tools/{tool_id}/context` → 200 |
-| 调用 Query | 解析 ToolSpec 后 `POST /tools/{endpoint_id}/{operation}:invoke` → 200 |
-| 接纳 Action | `POST /tools/{tool_id}:invoke` → 202 |
-| Action status | `GET /invocations/{invocation_id}` → 200 |
-| Action result | `GET /invocations/{invocation_id}/result` → 200 或 pending 202 |
-| 请求 cancel | `POST /invocations/{invocation_id}/cancel` → 200 或 accepted 202 |
-| 接纳 Session | `POST /tools/{tool_id}:invoke` → 202 |
-| 停止 Session | `POST /invocations/{invocation_id}/stop` → 200 或 accepted 202 |
+HTTP 路由、响应码及 pending/cancel/stop 语义统一维护在 [Forge Tool API 契约](../forge/README_zh.md#2-tool-发现与-context)。Client 实现应遵循该契约,本文不重复定义路由表。
路径组件经过 percent encoding。PAOS 生成 `caller_id`,并在 Action/Session admission 前与
intent 一同持久化。Admission 必须包含非空 `invocation_id`,Action 还要求 `attempt_id`。
@@ -52,24 +43,7 @@ Timeout 形成 unknown record,恢复不会重复 POST。
## 4. Agent tools
-Task lifecycle:
-
-- `forge_task_create(task_description, verification, activation_id)`;
-- `forge_task_get(task_id)`;
-- `forge_task_begin_revision(task_id, reason)`;
-- `forge_task_finalize(task_id)`;
-- `forge_task_cancel(task_id, reason?)`。
-
-Tool transport:
-
-- `forge_tool_context(tool_id)`;
-- `forge_tool_query(tool_id, arguments, task_id?, timeout_ms?)`;
-- `forge_tool_start_action(task_id, tool_id, arguments, timeout_ms?)`;
-- `forge_tool_action_status(task_id, invocation_id)`;
-- `forge_tool_action_result(task_id, invocation_id)`;
-- `forge_tool_cancel_action(task_id, invocation_id)`;
-- `forge_tool_start_session(task_id, tool_id, arguments, ownership)`;
-- `forge_tool_session_status/result/stop_session(task_id, invocation_id)`。
+公开的 Agent 工具清单统一维护在 [API 契约](../forge/README_zh.md#6-agent-tools)。Wrapper 位于 `agent/tools/forge_tool_api.py` 和 `agent/tools/forge_task.py`;传输处理放在 `forge/tool_client.py`,任务协调放在 `forge/task.py`。
诊断 Query 与绑定调用使用相同 HTTP 方法;每个变更或任务归因 wrapper 都在网络访问前校验
ownership 与冻结 binding。Tool wrapper 不能自行生成 Gateway identity 或 result。
@@ -84,22 +58,13 @@ PlanRevision、evidence refs、verification attempts、取消状态和时间戳
保证跨进程全局单活动槽位。更新写入完整的已校验 record 和 append-only event;业务代码不直接
修改表。
-终态任务状态为 `succeeded`、`failed`、`cancelled`;非终态为 `executing`、`cancelling`、
-`awaiting_replan`。Tool status `unknown` 对聚合记账是终态,但它表示失败,不表示已停止。
+公开状态由 [AgentTask 状态契约](../forge/README_zh.md#8-agenttask-模型)定义。Store 转移必须保持这些语义;`unknown` Tool record 结束记账,但不证明物理停止。
## 6. 绑定执行生命周期
-1. 激活 primary Skill,把其 Runtime/ToolSpec candidate 冻结到 AgentTask revision 1;
-2. 第一次绑定物理执行前进行 best-effort 前置采集;
-3. 通过 ForgeToolClient 调用 Query 或接纳 Action/Session;
-4. Admission 前持久化 caller intent,再保留 Gateway invocation/attempt 引用;
-5. 仅根据权威 status/result 更新异步 record;
-6. 全部 task-owned 执行终结后,finalize 进行后置采集;
-7. 聚合 Tool records、evidence 与任务契约进行验证;
-8. 持久化 task/revision verdict,并调度唯一终态 experience episode。
+Core 协调激活与 binding、持久化 intent admission、权威响应记录和 finalize。Intent 必须先于网络派发持久化,Gateway 引用写回同一个 task revision。Finalize 等待 task-owned 执行终结,采集后置证据并应用验证,再调度 experience。
-record 一旦终结,后续 observation 不会重写它。Cancellation response 会保存,但
-`requested` 或 `accepted` 仍使任务保持 `cancelling`,直到核对并显式 finalize。
+公开的 [binding 与身份](../forge/README_zh.md#7-bindingidentity-与关联)和 [AgentTask 生命周期](../forge/README_zh.md#8-agenttask-模型)统一维护在 API 契约。Cancellation response 只记录请求,聚合结果仍需核对与 finalize 确立。
## 7. Verification 与 recovery
@@ -124,13 +89,7 @@ metadata 和审计所需 tombstone。
## 9. Skill Runtime 契约
-`skill.yaml` 必须使用 `manifest_version: 2`,包含目录安全的 name/version、相对 Skill
-document、HTTP(S) `gateway_url`、非空 required Tools、至少一个 profile,并拒绝未知字段。
-Registry resolver 的 Node 必须包含 artifact identity、version、platform、architecture、
-archive type(`executable_tar_gz` 或 `directory_tar_gz`)、entrypoint 与 SHA-256。
-`executable_tar_gz` 归档只含一个由 entrypoint 命名的根目录 executable;`directory_tar_gz`
-归档只含一个以 entrypoint 命名的根目录,内放同名 executable 及其运行时树(允许树内相对
-符号链接)。
+Manifest 字段、Node 归档结构和启动 hook 环境见 [Bundle 与 Tool 接入参考](../user_development_guide/README_zh.md#4-构建-manifest-v2-skill-bundle)。Core 在 `skill_runtime/manifest.py`、归档校验器与 installer 中实现这些契约。
归档校验拒绝绝对/穿越路径、links(上述节点树内相对链接除外)、重复或冲突路径、超大文件、展开限制违规、清单缺项与摘要
不一致。Skill/Node installer 先 staging 与校验,再原子替换目标,并支持 rollback。
@@ -185,17 +144,11 @@ attempt。Outcome source 将每个 revision verdict 映射到该 revision
## 12. 扩展工作流
-新增机器人能力时:
+模型与机器人配置、新增 profile 或独立 Node 开发,请使用 [TrackB 三种开发模式](../user_development_guide/track_b/SKILL_DEVELOPMENT_zh.md)与 [Piper X 示例](../user_development_guide/PIPER_X_DEMO_zh.md)。
-1. 实现或打包 ToolEndpoint operation;
-2. 发布带精确 schema 与 binding 的 Query/Action/Session ToolSpec;
-3. 在 Gateway 定义 operation `max_concurrency`;
-4. 在 manifest v2 Bundle 中加入锁定 Node 与 profile 引用;
-5. 测试 binding 漂移、context、invoke、pending、terminal、cancel/stop、ownership 与 unknown;
-6. 在 Skill 中加入工作流指导,不写入任务特定坐标或凭据。
+只有能力确实需要时,才扩展 Core 已有的通用 client、binding、coordinator 或 installer。保持 API 契约,并在受影响的实现边界补充有针对性的回归检查;不新增 Agent 直连 Dora 的另一条执行路径。
-不要创建第二套 PAOS 执行协议、Agent 直连 Dora 或跨 Tool lease。只有通用 task/Tool API tools
-无法表达能力时,才应新增 Agent tool。
+可选的[交互基础](../interaction/README_zh.md)是独立受限扩展,Core 改动也需遵守其部署限制。
## 13. 测试门禁
@@ -213,5 +166,10 @@ pytest -q
## 后续阅读
- [Forge Tool API 接入契约](../forge/README_zh.md)
-- [集成开发指南](../user_development_guide/README.md)
+- [Bundle 与 Tool 接入参考](../user_development_guide/README_zh.md)
- [Agent 经验与 Skill 自进化](05-agent-experience-and-skill-evolution.md)
+
+## 节点开发与实战示例
+
+- [TrackB 框架说明](../user_development_guide/track_b/README_zh.md)
+- [Piper X MuJoCo 二次开发](../user_development_guide/PIPER_X_DEMO_zh.md)
diff --git a/docs/zh/04-forge-configuration-reference.md b/docs/zh/04-forge-configuration-reference.md
index 880b8cfc3..1ed03e750 100644
--- a/docs/zh/04-forge-configuration-reference.md
+++ b/docs/zh/04-forge-configuration-reference.md
@@ -1,6 +1,6 @@
# Forge 配置参考
-> 适用于 PhyAgentOS 1.0.0 与统一的 Forge Gateway Tool API。
+> 适用于 PhyAgentOS 1.1.1 与统一的 Forge Gateway Tool API。
## 1. 配置位置与命名
@@ -23,10 +23,20 @@ Runtime 选择与 Gateway URL 来自已安装 Skill manifest 和显式启动的
| `pollIntervalS` | number | `0.5` | Action/Session status/result 建议对账间隔,范围 `[0.1, 5.0]` 秒。 |
| `executionTimeoutS` | number | `300.0` | Agent 侧任务 deadline 指引;timeout 不能证明远端执行已停止。 |
| `evidence` | object | 见下表 | AgentTask 的 best-effort 前后证据采集设置。 |
+| `interaction` | object | `{"enabled": false}` | 可选的受限交互扩展,见下文。 |
PAOS 只通过 `/tools` 与 `/invocations` 调用 Query、Action 和 Session,不调用旧式
`/agent/sessions` 或 `/policy/command`。并发由所选 Endpoint operation 的 `max_concurrency` 裁决。
+### `forge.interaction`
+
+| JSON 字段 | 类型 | 默认值 | 约束与含义 |
+| --- | --- | --- | --- |
+| `enabled` | boolean | `false` | 允许交互任务契约,不授权生产控制面访问。 |
+
+[交互基础](../interaction/README_zh.md)当前要求显式注入使用 `httpx.MockTransport` 的进程内部署。
+仅修改普通 CLI 配置不能启用真实环境;该可选扩展与默认机器人/Skill 开发流程分开。
+
## 2.1 `resourceRegistry`
| JSON 字段 | 类型 | 默认值 | 约束与含义 |
@@ -75,7 +85,7 @@ Verification Service 启动 readiness 等待为有界操作。服务不可用时
| JSON 字段 | 类型 | 默认值 | 约束与含义 |
|:----------|:-----|:-------|:-----------|
-| `enabled` | boolean | `true` | 启用显式 Skill 激活、经验账本和后台演化。故障不会阻塞任务执行。 |
+| `enabled` | boolean | `true` | 启用经验反思与受控晋升;false 时显式 Skill 激活仍可用,演化故障不阻塞执行。 |
| `scope` | literal | `verified_forge_lineage` | 消费有 semantic verdict 的 AgentTask lineage;持久化 literal 为兼容保持稳定。 |
| `promotionMode` | literal | `guarded_auto` | 只允许经过门控验证的自动晋升。 |
| `minSuccessfulEpisodes` | integer | `3` | 相同候选晋升所需的独立成功 AgentTask 数,至少为 1。 |
@@ -258,7 +268,7 @@ paos agent -m "调用 forge_tool_context 读取指定 Tool 的 schema、binding
## 后续阅读
- [用户手册](02-user-manual.md)
-- [开发者手册](03-developer-manual.md)
+- [Core 开发者手册](03-developer-manual.md)
- [Agent 经验与 Skill 自进化](05-agent-experience-and-skill-evolution.md)
-- [运行手册](../user_manual/README.md)
-- [统一 Forge Tool API 契约](../forge/UNIFIED_TOOL_API.md)
+- [运行手册](../user_manual/README_zh.md)
+- [统一 Forge Tool API 契约](../forge/README_zh.md)
diff --git a/docs/zh/05-agent-experience-and-skill-evolution.md b/docs/zh/05-agent-experience-and-skill-evolution.md
index d1c920ec9..52eafed1d 100644
--- a/docs/zh/05-agent-experience-and-skill-evolution.md
+++ b/docs/zh/05-agent-experience-and-skill-evolution.md
@@ -1,6 +1,6 @@
# Agent 经验与 Skill 自进化
-> 文档版本:1.0.0。本文描述基于 AgentTask record 的 Agent 校验、经验、Lesson 与 Skill 演化链。
+> 文档版本:1.1.1。本文描述基于 AgentTask record 的 Agent 校验、经验、Lesson 与 Skill 演化链。
## 1. 目标与边界
@@ -202,6 +202,6 @@ Built-in Skill 永不原地修改:基线先归档,再复制为 workspace ove
- [框架介绍](01-framework-introduction.md)
- [用户手册](02-user-manual.md)
-- [开发者手册](03-developer-manual.md)
+- [Core 开发者手册](03-developer-manual.md)
- [Forge 配置参考](04-forge-configuration-reference.md)
-- [文档索引](../README.md)
+- [文档索引](../README_zh.md)
diff --git a/example/robot-control-sim-piper-x/.gitignore b/example/robot-control-sim-piper-x/.gitignore
new file mode 100644
index 000000000..fe80780b3
--- /dev/null
+++ b/example/robot-control-sim-piper-x/.gitignore
@@ -0,0 +1,3 @@
+.venv*/
+work/
+__pycache__/
diff --git a/example/robot-control-sim-piper-x/README.md b/example/robot-control-sim-piper-x/README.md
new file mode 100644
index 000000000..a5075a0de
--- /dev/null
+++ b/example/robot-control-sim-piper-x/README.md
@@ -0,0 +1,32 @@
+# Piper X MuJoCo Skill development example
+
+[English](README.md) | [简体中文](README_zh.md)
+
+For the full procedure, see the [development tutorial](../../docs/user_development_guide/PIPER_X_DEMO.md).
+
+This example derives a Skill from installed public `robot-control-sim` 0.1.2,
+using the pinned official AgileX Piper X model. It keeps all nine original Node
+locks. It does not download or execute robot hardware drivers.
+
+- `build_skill.py`: portable model/profile generator; refuses existing output.
+- `node-locks.json`: expected original Node lock declarations.
+- `validate_model.py`: URDF/MJCF FK and simulation servo checks.
+- `accept_pipeline.py`: diagnostic native Tool API acceptance, without an LLM.
+- `motion-fixtures.json`: synthetic reachable joint and Cartesian targets.
+- `headless/`: optional Linux Xvfb hooks; display :92 must be available.
+
+Generated artifacts, local logs and downloaded model assets belong under `work/`
+and are ignored. The AgileX model license is copied into the generated Skill;
+upstream Skill files retain their notices. Protocol/source lookup:
+[TrackB framework guide](../../docs/user_development_guide/track_b/README.md).
+
+The generator targets Piper X specifically. For another robot, use the model,
+joint/frame mapping and acceptance checklist in the tutorial; it is not a generic
+URDF import interface. The tutorial also documents one-target diagnostics with
+`--only joint-a` and `--only eef-a`.
+
+A locally installed derived Skill is not automatically registered or published
+on a resource platform. Reuse matching published Node identities, submit the new
+Skill through the target platform's registration/review workflow, and verify its
+consumer API after publication. Source Node changes require new Node versions
+and updated Skill locks.
diff --git a/example/robot-control-sim-piper-x/README_zh.md b/example/robot-control-sim-piper-x/README_zh.md
new file mode 100644
index 000000000..1867082f1
--- /dev/null
+++ b/example/robot-control-sim-piper-x/README_zh.md
@@ -0,0 +1,25 @@
+# Piper X MuJoCo Skill 开发示例
+
+[English](README.md) | [简体中文](README_zh.md)
+
+完整步骤见 [开发手册 demo](../../docs/user_development_guide/PIPER_X_DEMO_zh.md)。
+
+本例基于已安装的公开 `robot-control-sim` 0.1.2 和固定版本的 AgileX 官方 Piper X 模型生成派生 Skill,
+保留九个原始 Node locks,不下载或执行真机驱动。
+
+- `build_skill.py`:可移植模型/profile 生成器,拒绝已有输出目录。
+- `node-locks.json`:原始 Node 依赖声明。
+- `validate_model.py`:URDF/MJCF 正运动学及仿真伺服检查。
+- `accept_pipeline.py`:无需 LLM 的原生 Tool API 执行链诊断。
+- `motion-fixtures.json`:合成的可达关节与末端位姿目标。
+- `headless/`:可选 Linux Xvfb 钩子,需要空闲的 display `:92`。
+
+生成制品、本地日志和下载的模型资产放在被忽略的 `work/` 中。
+生成 Skill 包含 AgileX 模型许可证,上游 Skill 文件保留原声明。
+协议与源码入口见 [TrackB 框架说明](../../docs/user_development_guide/track_b/README_zh.md)。
+
+生成器专用于 Piper X;其他机器人需按教程核对模型、关节/坐标映射及验收清单,
+不能把它当成通用 URDF 导入器。教程也提供 `--only joint-a` 与 `--only eef-a` 单目标诊断。
+
+本地安装不等于平台登记或发布。复用匹配的既有 Node 身份,按目标平台流程提交新 Skill,
+经过审核发布后验证消费者 API。修改 Node 源码时需发布新 Node 版本,并更新 Skill locks。
diff --git a/example/robot-control-sim-piper-x/accept_pipeline.py b/example/robot-control-sim-piper-x/accept_pipeline.py
new file mode 100644
index 000000000..51749b263
--- /dev/null
+++ b/example/robot-control-sim-piper-x/accept_pipeline.py
@@ -0,0 +1,115 @@
+"""Live acceptance through native ForgeToolClient and the original Dora pipeline.
+
+Never writes simulator state, solves IK, or replays an unknown Action.
+Pose targets are precomputed reachable fixtures; only Cartesian poses go to Tool API.
+"""
+import argparse
+import asyncio
+from datetime import datetime, timezone
+import json
+from pathlib import Path
+import time
+
+from PhyAgentOS.forge.tool_client import ForgeToolClient, ForgeToolAPIError
+
+ROOT=Path(__file__).resolve().parent
+JOINTS=[f'joint{i}' for i in range(1,7)]
+
+
+def find_motion(value):
+ if isinstance(value,dict):
+ if 'error_code' in value and 'joint_names' in value: return value
+ for child in value.values():
+ found=find_motion(child)
+ if found is not None: return found
+ return None
+
+
+async def execute(c, label, tool, arguments, destination, expected_success=True):
+ row={'label':label,'tool_id':tool,'arguments':arguments,
+ 'started_at':datetime.now(timezone.utc).isoformat(),'status_samples':[]}
+ def save(): destination.write_text(json.dumps(row,indent=2))
+ save()
+ try:
+ row['context']=await c.get_tool_context(tool)
+ assert row['context']['data']['ready'], row['context']
+ row['admission']=await c.invoke_action(tool,arguments,timeout_ms=20000)
+ ident=row['admission']['data']['invocation_id']; save()
+ deadline=time.monotonic()+70
+ while time.monotonic() unchanged motion Nodes -> MuJoCo','actions':[]}
+ try:
+ async with ForgeToolClient(args.gateway_url) as c:
+ summary['tools']=await c.list_tools()
+ summary['robot_info']=await c.invoke_query_tool('sim.get_robot_info',{})
+ (output/'discovery.json').write_text(json.dumps(summary,indent=2))
+ # Query result is checked by output schema; robot identity must be explicit.
+ assert 'agilex_piper_x' in json.dumps(summary['robot_info'])
+ if args.only:
+ fixtures=[f for f in fixtures if f['label']==args.only]
+ assert len(fixtures)==1, args.only
+ for f in fixtures:
+ row=await execute(c,f['label'],f['tool_id'],f['arguments'],output/(f['label']+'.json'),f.get('expected_success',True))
+ summary['actions'].append({'label':f['label'],'passed':row['check_passed'],'invocation_id':row['admission']['data']['invocation_id']})
+ summary['passed']=all(x['passed'] for x in summary['actions'])
+ finally:
+ (output/'summary.json').write_text(json.dumps(summary,indent=2))
+
+
+if __name__=='__main__':
+ p=argparse.ArgumentParser(description=__doc__)
+ p.add_argument('--run-id',required=True)
+ p.add_argument('--only')
+ p.add_argument('--output-dir',type=Path,required=True)
+ p.add_argument('--gateway-url',default='http://127.0.0.1:19104')
+ asyncio.run(main(p.parse_args()))
diff --git a/example/robot-control-sim-piper-x/build_skill.py b/example/robot-control-sim-piper-x/build_skill.py
new file mode 100644
index 000000000..a1bf8d910
--- /dev/null
+++ b/example/robot-control-sim-piper-x/build_skill.py
@@ -0,0 +1,328 @@
+"""Reproducible Piper X model/profile extension of public robot-control-sim 0.1.2.
+
+Uses the official AgileX Piper X URDF, not the bundled ordinary Piper model.
+Runtime planning/control Nodes are preserved byte for byte.
+"""
+import argparse
+import copy
+import hashlib
+import json
+from pathlib import Path
+import shutil
+import subprocess
+import xml.etree.ElementTree as ET
+
+import mujoco
+import yaml
+
+ROOT = Path(__file__).resolve().parent
+UPSTREAM = None
+AGX = None
+DEST = None
+HEADLESS = False
+MODEL_REVISION = '680fa925cd00db7e2628563d2edc5540963045de'
+PROFILE = 'mujoco-piper-x'
+JOINTS = [f'joint{i}' for i in range(1, 7)]
+INITIAL = dict(zip(JOINTS, [0.0, 0.65, -1.10, 0.25, 0.30, 0.10])) | {'gripper': 0.04}
+
+
+def sha(p):
+ return hashlib.sha256(p.read_bytes()).hexdigest()
+
+
+def write_xml(root, path):
+ ET.indent(root)
+ ET.ElementTree(root).write(path, encoding='utf-8', xml_declaration=True)
+
+
+def yload(p):
+ return yaml.safe_load(p.read_text())
+
+
+def ywrite(p, d):
+ p.write_text(yaml.safe_dump(d, sort_keys=False))
+
+
+def main():
+ revision = subprocess.check_output(['git', '-C', str(AGX), 'rev-parse', 'HEAD'], text=True).strip()
+ if revision != MODEL_REVISION:
+ raise SystemExit(f'Model checkout must be {MODEL_REVISION}; found {revision}')
+ if subprocess.check_output(['git', '-C', str(AGX), 'status', '--porcelain'], text=True).strip():
+ raise SystemExit('Model checkout must be clean')
+ manifest = yload(UPSTREAM / 'skill.yaml')
+ if (manifest.get('name'), str(manifest.get('version'))) != ('robot-control-sim', '0.1.2'):
+ raise SystemExit('Expected installed robot-control-sim 0.1.2')
+ expected = json.loads((ROOT / 'node-locks.json').read_text())
+ if manifest.get('artifacts', {}).get('nodes') != expected:
+ raise SystemExit('Upstream Node locks differ from the demo baseline')
+ if DEST.exists():
+ raise SystemExit('Preserve existing source; remove only the generated tree explicitly before rebuilding.')
+ shutil.copytree(UPSTREAM, DEST, ignore=shutil.ignore_patterns('archive-manifest.json'))
+ robot = DEST / 'assets/robots/piper_x'
+ model_dir = robot / 'mjcf'
+ meshes = model_dir / 'meshes'
+ meshes.mkdir(parents=True)
+ source_path = AGX / 'piper_x/urdf/piper_x_description.urdf'
+ gripper_path = AGX / 'piper_x/urdf/piper_x_with_gripper_description.xacro'
+ root = ET.parse(source_path).getroot()
+ for el in ET.parse(gripper_path).getroot():
+ if not el.tag.startswith('{'):
+ root.append(copy.deepcopy(el))
+ root.append(ET.Element('link', {'name': 'tcp'}))
+ tcp = ET.SubElement(root, 'joint', {'name': 'tcp_fixed', 'type': 'fixed'})
+ ET.SubElement(tcp, 'parent', {'link': 'gripper_base'})
+ ET.SubElement(tcp, 'child', {'link': 'tcp'})
+ ET.SubElement(tcp, 'origin', {'xyz': '0 0 0.138', 'rpy': '0 0 0'})
+ sources = [source_path, gripper_path]
+ for link in root.findall('link'):
+ for mesh in link.findall('.//mesh'):
+ original = mesh.get('filename').split('agx_arm_urdf/', 1)[1]
+ source = AGX / original
+ if source.suffix == '.dae':
+ source = source.parent.parent / (source.stem + '.stl')
+ prefix = original.split('/')[0]
+ filename = prefix + '_' + source.name
+ shutil.copy2(source, meshes / filename)
+ mesh.set('filename', 'mjcf/meshes/' + filename)
+ sources.append(source)
+ # Official STL shape is used for both visual/collision; DAE color is not retained.
+ vis = link.find('visual')
+ if vis is not None:
+ material = ET.SubElement(vis, 'material', {'name': link.get('name') + '_gray'})
+ ET.SubElement(material, 'color', {'rgba': '0.65 0.69 0.73 1'})
+ write_xml(root, robot / 'piper_x_with_gripper.urdf')
+ # The URDF's "gripper" is a massless logical opening used by ROS mimic.
+ # MuJoCo instead has the two physical sliders coupled q2=-q1, and gear=2.
+ sim_root = copy.deepcopy(root)
+ for el in list(sim_root):
+ if (el.tag == 'link' and el.get('name') == 'gripper_link') or (el.tag == 'joint' and el.get('name') == 'gripper'):
+ sim_root.remove(el)
+ for mesh in sim_root.findall('.//mesh'):
+ mesh.set('filename', str(meshes / Path(mesh.get('filename')).name))
+ extension = ET.SubElement(sim_root, 'mujoco')
+ ET.SubElement(extension, 'compiler', {'discardvisual': 'false', 'fusestatic': 'false', 'strippath': 'false'})
+ temp_urdf = model_dir / 'compile-input.urdf'
+ write_xml(sim_root, temp_urdf)
+ imported = mujoco.MjModel.from_xml_path(str(temp_urdf))
+ intermediate = model_dir / 'imported.xml'
+ mujoco.mj_saveLastXML(str(intermediate), imported)
+ mj = ET.parse(intermediate).getroot()
+ mj.set('model', 'agilex_piper_x')
+ compiler = mj.find('compiler')
+ compiler.set('meshdir', 'meshes')
+ compiler.set('angle', 'radian')
+ for mesh in mj.findall('./asset/mesh'):
+ mesh.set('file', Path(mesh.get('file')).name)
+ opt = ET.SubElement(mj, 'option', {'timestep': '0.002', 'integrator': 'implicitfast', 'gravity': '0 0 -9.81'})
+ for body in mj.findall('.//body'):
+ body.set('gravcomp', '1')
+ for joint in mj.findall('.//body/joint'):
+ joint.set('damping', '1')
+ joint.set('armature', '0.01' if joint.get('name') in JOINTS[:3] else '0.002')
+ tcp_body = next(b for b in mj.findall('.//body') if b.get('name') == 'tcp')
+ ET.SubElement(tcp_body, 'site', {'name': 'tcp', 'size': '0.008', 'rgba': '1 0.2 0.1 1'})
+ eq = ET.SubElement(mj, 'equality')
+ ET.SubElement(eq, 'joint', {'joint1': 'gripper_joint2', 'joint2': 'gripper_joint1', 'polycoef': '0 -1 0 0 0'})
+ actuators = ET.SubElement(mj, 'actuator')
+ for i, joint in enumerate(root.findall('joint')):
+ name = joint.get('name')
+ if name not in JOINTS:
+ continue
+ lim = joint.find('limit')
+ ET.SubElement(actuators, 'position', {'name': name, 'joint': name,
+ 'kp': '600' if name in JOINTS[:3] else '120',
+ 'kv': '35' if name in JOINTS[:3] else '8',
+ 'ctrlrange': lim.get('lower') + ' ' + lim.get('upper'),
+ 'forcerange': '-100 100'})
+ ET.SubElement(actuators, 'position', {'name': 'gripper', 'joint': 'gripper_joint1',
+ 'gear': '2', 'kp': '200', 'kv': '5', 'ctrlrange': '0 0.1', 'forcerange': '-10 10'})
+ contact = ET.SubElement(mj, 'contact')
+ # The fixed pedestal and shoulder housing overlap by design in the URDF.
+ # Their convex mesh contact otherwise pins joint1. Ordinary upstream Piper
+ # uses this same adjacent-body exclusion; all other contacts remain enabled.
+ ET.SubElement(contact, 'exclude', {'body1': 'base_link', 'body2': 'link1'})
+ write_xml(mj, model_dir / 'piper_x.xml')
+ temp_urdf.unlink()
+ intermediate.unlink()
+ scene = ET.Element('mujoco', {'model': 'piper_x_scene'})
+ ET.SubElement(scene, 'include', {'file': 'piper_x.xml'})
+ visual = ET.SubElement(scene, 'visual')
+ ET.SubElement(visual, 'global', {'offwidth': '1280', 'offheight': '960'})
+ ET.SubElement(visual, 'headlight', {'ambient': '0.5 0.5 0.5', 'diffuse': '0.6 0.6 0.6'})
+ asset = ET.SubElement(scene, 'asset')
+ ET.SubElement(asset, 'texture', {'name': 'floor', 'type': '2d', 'builtin': 'checker', 'rgb1': '.18 .21 .24', 'rgb2': '.23 .27 .30', 'width': '512', 'height': '512'})
+ ET.SubElement(asset, 'material', {'name': 'floor', 'texture': 'floor', 'texrepeat': '4 4', 'texuniform': 'true'})
+ world = ET.SubElement(scene, 'worldbody')
+ ET.SubElement(world, 'light', {'pos': '0 -1 2', 'dir': '0 0 -1'})
+ ET.SubElement(world, 'geom', {'name': 'floor', 'type': 'plane', 'size': '2 2 .1', 'pos': '0 0 -0.002', 'material': 'floor'})
+ ET.SubElement(world, 'camera', {'name': 'angle', 'pos': '1.0 -1.0 .85', 'xyaxes': '.707 .707 0 -.27 .27 .924', 'fovy': '48'})
+ ET.SubElement(world, 'camera', {'name': 'top', 'pos': '.15 0 1.5', 'xyaxes': '1 0 0 0 1 0', 'fovy': '55'})
+ write_xml(scene, model_dir / 'scene.xml')
+ shutil.copy2(AGX / 'LICENSE', robot / 'LICENSE.agilex')
+ limits = {j.get('name'): [float(j.find('limit').get('lower')), float(j.find('limit').get('upper'))]
+ for j in root.findall('joint') if j.get('name') in JOINTS}
+ descriptor = {'name': 'agilex_piper_x', 'source': 'mjcf', 'model': 'mjcf/scene.xml',
+ 'joints': [{'name': j, 'kind': 'revolute', 'limits_rad': limits[j]} for j in JOINTS]
+ + [{'name': 'gripper', 'kind': 'prismatic', 'limits_m': [0, .1]}],
+ 'eef_site': 'tcp', 'initial_qpos': INITIAL, 'has_gripper': True,
+ 'notes': 'Official AgileX Piper X geometry/kinematics/inertias; simulation position servos with gravity compensation. TCP is defined at gripper_base + [0,0,0.138] m. No hardware calibration or collision-free planning claim.'}
+ ywrite(robot / 'robot.yaml', descriptor)
+ profile = DEST / 'profiles' / PROFILE
+ shutil.copytree(DEST / 'profiles/mujoco-piper', profile)
+ sim = yload(profile / 'simulator.yaml')
+ sim['model_path'] = '../../assets/robots/piper_x/mjcf/scene.xml'
+ sim['initial_state']['joint_positions'] = INITIAL
+ sim['joints'][-1]['state_from_joints'] = ['gripper_joint1', 'gripper_joint2']
+ sim['robots'][0]['prefix'] = ''
+ sim['image_forward'] = {c: {'output': 'image/' + c, 'fps': 15, 'width': 640, 'height': 480} for c in ['angle', 'top']}
+ ywrite(profile / 'simulator.yaml', sim)
+ motion = yload(profile / 'motion_server.yaml')
+ group = motion['groups'].pop('piper_arm')
+ group.update(urdf_path='../../assets/robots/piper_x/piper_x_with_gripper.urdf', base_frame='base_link', tip_frame='tcp')
+ motion['groups']['piper_x_arm'] = group
+ ywrite(profile / 'motion_server.yaml', motion)
+ policy = yload(profile / 'sim_control_policy.yaml')
+ policy['robot_descriptor_path'] = '../../assets/robots/piper_x/robot.yaml'
+ policy['reset']['motion']['arguments']['group_name'] = 'piper_x_arm'
+ ywrite(profile / 'sim_control_policy.yaml', policy)
+ grip = yload(profile / 'gripper_controller.yaml'); grip['max_position'] = .1
+ ywrite(profile / 'gripper_controller.yaml', grip)
+ gateway = yload(profile / 'gateway.yaml'); gateway['port'] = 19104
+ for spec in gateway['tools']['specs']:
+ frames = spec['robot_frame_profile']
+ frames.update(robot_id='agilex_piper_x', base_frame='base_link', tool_frame='tcp')
+ frames['directions']['forward']['frame'] = 'base_link'
+ props = spec['input_schema']['properties']
+ if 'group_name' in props: props['group_name'] = {'const': 'piper_x_arm'}
+ if 'reference_frame' in props: props['reference_frame'] = {'const': 'base_link'}
+ if 'target_frame' in props: props['target_frame'] = {'const': 'tcp'}
+ for k in ['velocity_scale', 'acceleration_scale']:
+ if k in props: props[k]['maximum'] = .3
+ if spec['tool_id'] == 'sim.set_joint_positions':
+ props['joint_names'] = {'const': JOINTS}
+ props['positions'].update(minItems=6, maxItems=6)
+ if 'opening_m' in props:
+ props['opening_m']['maximum'] = .1
+ spec['description'] = 'Set the Piper X parallel gripper logical opening, 0..0.1 meters.'
+ ywrite(profile / 'gateway.yaml', gateway)
+ flow = yload(profile / 'dataflow.yaml')
+ sim_node = next(n for n in flow['nodes'] if n['id'] == 'mujoco')
+ sim_node['outputs'] = ['proprio_state', 'image/angle', 'image/top']
+ viewer = next(n for n in flow['nodes'] if n['id'] == 'image_viewer')
+ viewer['inputs'] = {'image/' + c: 'mujoco/image/' + c for c in ['angle', 'top']}
+ ywrite(profile / 'dataflow.yaml', flow)
+ ywrite(profile / 'image_viewer.yaml', {'images': ['image/angle'], 'renderer': 'glow'})
+ manifest = yload(DEST / 'skill.yaml')
+ manifest.update(name='robot-control-sim-piper-x', version='0.1.2', gateway_url='http://127.0.0.1:19104',
+ description='AgileX Piper X MuJoCo control through native joint and end-effector pose Actions, with the original robot-control-sim planning/control Nodes.')
+ new = copy.deepcopy(manifest['profiles']['mujoco-piper'])
+ new['dataflow'] = f'profiles/{PROFILE}/dataflow.yaml'
+ new['required_assets'] = ['assets/robots/piper_x/' + p for p in ['robot.yaml', 'mjcf/scene.xml', 'mjcf/piper_x.xml', 'piper_x_with_gripper.urdf']]
+ new['environment'] = ({'DISPLAY': ':92', 'LIBGL_ALWAYS_SOFTWARE': '1', 'XDG_RUNTIME_DIR': '/tmp/paos-piper-x-xvfb'} if HEADLESS else {})
+ # This separately named deployment includes only Piper X. The pristine
+ # original bundle remains alongside it; its robots/ports are not overwritten.
+ manifest['profiles'] = {PROFILE: new}
+ # Resolve the original locked archives through the configured registry.
+ manifest['artifacts']['resolver'] = 'registry'
+ ywrite(DEST / 'skill.yaml', manifest)
+ if HEADLESS:
+ for name in ['start.sh', 'stop_display.sh']:
+ shutil.copy2(ROOT / 'headless' / name, DEST / name)
+ (DEST / name).chmod(0o755)
+ for directory in (DEST / 'profiles').iterdir():
+ if directory.name != PROFILE: shutil.rmtree(directory)
+ for directory in (DEST / 'assets/robots').iterdir():
+ if directory.name != 'piper_x': shutil.rmtree(directory)
+ generator = DEST / 'scripts/gen_robot_table.py'
+ generator.write_text(generator.read_text().replace('ROBOT_PROFILES = {', 'ROBOT_PROFILES = {\n "piper_x": "mujoco-piper-x",'))
+ skill = DEST / 'SKILL.md'
+ skill.write_text(SKILL_DOCUMENT)
+ subprocess.run([__import__('sys').executable, str(generator)], check=True)
+ revision = subprocess.check_output(['git', '-C', str(AGX), 'rev-parse', 'HEAD'], text=True).strip()
+ provenance = {'model_source': 'https://github.com/agilexrobotics/agx_arm_urdf', 'revision': revision,
+ 'source_files': {str(p.relative_to(AGX)): sha(p) for p in sorted(set(sources))},
+ 'mujoco_builder_version': mujoco.__version__, 'upstream_skill': 'robot-control-sim 0.1.2',
+ 'upstream_manifest_sha256': sha(UPSTREAM / 'skill.yaml'),
+ 'changes': ['Expand official gripper xacro include without ROS', 'Use provided STL meshes for visuals as well as collision',
+ 'Add explicitly defined tcp fixed frame at gripper_base z=0.138m',
+ 'Remove massless logical gripper from MuJoCo, couple physical sliders with equality and gear=2 actuator',
+ 'Add tunable simulation position servos, damping/armature and gravity compensation; not calibrated hardware dynamics',
+ 'Exclude only adjacent base_link/link1 contact to remove designed-in shoulder housing overlap, as in upstream ordinary Piper',
+ 'Add Piper X-only deployment profile; pristine original bundle retained separately; runtime Nodes unchanged']}
+ (robot / 'PROVENANCE.json').write_text(json.dumps(provenance, indent=2))
+ print(json.dumps({'destination': str(DEST), 'model_revision': revision, 'joint_limits': limits, 'initial': INITIAL}, indent=2))
+
+
+SKILL_DOCUMENT = '''---
+name: robot-control-sim-piper-x
+description: Control an AgileX Piper X in MuJoCo through joint targets or absolute end-effector poses.
+metadata: {"PhyAgentOS":{"always":false,"requires":{"runtime":["robot-control-sim-piper-x"]}}}
+---
+
+# Piper X MuJoCo control / Piper X 仿真控制
+
+This is a Piper X-only derivative of public robot-control-sim 0.1.2. It uses the
+official AgileX Piper X model, not ordinary Piper. All nine runtime Nodes retain
+the original immutable hashes. Simulation only; no hardware interfaces exist.
+
+## Workflow / 工作流
+
+1. Select profile `mujoco-piper-x`. Activate this Skill as primary, discover
+ `sim.get_robot_info`, then obtain live context/schema of the intended tool.
+ Require readiness and identity agilex_piper_x. The descriptor is model metadata,
+ not a live joint-state Query.
+2. Create one AgentTask for the explicit user goal and measurable success criteria.
+ Bind the requested Action to this task. For encoder/FK-only verification choose
+ audit mode, minimum_association=best_effort, required_kinds=[], required_sources=[].
+ In verification.constraints include: Verifier evidence_refs must copy exact
+ strings from valid_evidence_refs; do not invent concise labels or prefixes such
+ as gateway_terminal_result: or tool_execution_record:.
+3. Path 1: `sim.set_joint_positions` sends six absolute radians, exactly ordered
+ [joint1,joint2,joint3,joint4,joint5,joint6], group_name=piper_x_arm.
+ Path 2: `sim.move_eef` sends target_pose={x,y,z,qx,qy,qz,qw}, position in meters,
+ unit quaternion in xyzw fields, reference_frame=base_link, target_frame=tcp,
+ group_name=piper_x_arm. The existing motion_server solves IK and plans the
+ trajectory; never calculate joints and substitute joint control for a pose goal.
+4. Use explicit speed and acceleration scales in (0,0.3], typically 0.2. Reject
+ ambiguous/out-of-limits goals; never silently clip or invent a pose. TCP is
+ gripper_base + [0,0,0.138] m. It is a simulation frame definition, not calibrated
+ hardware TCP. Usual test tolerances: 0.005 m position and 0.03 rad orientation.
+5. Submit exactly one requested motion. Admission is not completion. Retain its ID,
+ poll status/result at most 12 times, and require a terminal succeeded result plus
+ motion_result.error_code=SUCCESS. The raw Gateway invocation phase is completed;
+ success is in result.status=succeeded, not phase=succeeded. For joints require max absolute residual
+ <=0.03 rad; for EEF require both returned pose residuals within requested limits.
+ Never automatically resend an unknown/failed Action. Do not use exec/shell,
+ direct HTTP, robot SDK or simulator state mutation. Use framework tools only.
+6. Finalize after all owned execution is terminal, then inspect forge_task_get.
+ Report execution facts separately from the persisted independent verdict.
+ audit status=succeeded with verdict=null is not verification success.
+
+## Supported robot / 机器人
+
+
+
+
+Parallel gripper: sim.set_gripper_opening accepts 0..0.1 meters. sim.reset resets
+physics and re-homes through the original native motion/gripper tool pipeline.
+Reset or gripper commands are separate user requests, never automatic motion retries.
+
+## Runtime / 运行
+
+Gateway 127.0.0.1:19104. The optional headless profile uses Xvfb :92 and glow/software OpenGL.
+Start through paos skill start; for headless builds stop the runtime then run stop_display.sh.
+Gravity-compensated position servos are simulation tuning, not identified hardware
+dynamics. Pose planning does not establish obstacle avoidance or grasping success.
+'''
+
+
+if __name__ == '__main__':
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument('--upstream', type=Path, required=True, help='Installed robot-control-sim 0.1.2 directory')
+ parser.add_argument('--models', type=Path, required=True, help='Clean official AgileX model checkout at pinned revision')
+ parser.add_argument('--output', type=Path, required=True, help='New output directory; existing paths are refused')
+ parser.add_argument('--headless', action='store_true', help='Linux Xvfb :92 + software OpenGL; requires Xvfb')
+ args = parser.parse_args()
+ UPSTREAM, AGX, DEST = args.upstream.resolve(), args.models.resolve(), args.output.resolve()
+ HEADLESS = args.headless
+ main()
diff --git a/example/robot-control-sim-piper-x/headless/start.sh b/example/robot-control-sim-piper-x/headless/start.sh
new file mode 100755
index 000000000..b67cd9a9d
--- /dev/null
+++ b/example/robot-control-sim-piper-x/headless/start.sh
@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+set -euo pipefail
+command -v Xvfb >/dev/null || { echo "Xvfb is required for this server profile" >&2; exit 1; }
+paos_trial_display_dir="/tmp/paos-piper-x-xvfb"
+mkdir -p "$paos_trial_display_dir"
+chmod 700 "$paos_trial_display_dir"
+if [ -f "$paos_trial_display_dir/pid" ]; then
+ paos_trial_display_pid="$(cat "$paos_trial_display_dir/pid")"
+ if kill -0 "$paos_trial_display_pid" 2>/dev/null && grep -zq 'Xvfb' "/proc/$paos_trial_display_pid/cmdline" && grep -zq ':92' "/proc/$paos_trial_display_pid/cmdline"; then
+ exit 0
+ fi
+fi
+if [ -S /tmp/.X11-unix/X92 ]; then
+ echo "Display :92 is occupied by another X server" >&2
+ exit 1
+fi
+nohup Xvfb :92 -screen 0 1280x800x24 -nolisten tcp >"$paos_trial_display_dir/xvfb.log" 2>&1 "$paos_trial_display_dir/pid"
+for paos_trial_attempt in $(seq 1 30); do
+ [ ! -S /tmp/.X11-unix/X92 ] || exit 0
+ sleep 0.1
+done
+echo "Dedicated Xvfb did not become ready" >&2
+exit 1
diff --git a/example/robot-control-sim-piper-x/headless/stop_display.sh b/example/robot-control-sim-piper-x/headless/stop_display.sh
new file mode 100755
index 000000000..f37e59ed2
--- /dev/null
+++ b/example/robot-control-sim-piper-x/headless/stop_display.sh
@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+set -euo pipefail
+paos_trial_display_dir="/tmp/paos-piper-x-xvfb"
+if [ -f "$paos_trial_display_dir/pid" ]; then
+ paos_trial_display_pid="$(cat "$paos_trial_display_dir/pid")"
+ if [ -r "/proc/$paos_trial_display_pid/cmdline" ] && grep -zq 'Xvfb' "/proc/$paos_trial_display_pid/cmdline" && grep -zq ':92' "/proc/$paos_trial_display_pid/cmdline"; then
+ kill "$paos_trial_display_pid"
+ fi
+ rm -f "$paos_trial_display_dir/pid"
+fi
diff --git a/example/robot-control-sim-piper-x/motion-fixtures.json b/example/robot-control-sim-piper-x/motion-fixtures.json
new file mode 100644
index 000000000..4fe1a9b97
--- /dev/null
+++ b/example/robot-control-sim-piper-x/motion-fixtures.json
@@ -0,0 +1,155 @@
+[
+ {
+ "label": "joint-a",
+ "tool_id": "sim.set_joint_positions",
+ "arguments": {
+ "group_name": "piper_x_arm",
+ "joint_names": [
+ "joint1",
+ "joint2",
+ "joint3",
+ "joint4",
+ "joint5",
+ "joint6"
+ ],
+ "positions": [
+ -0.15,
+ 0.8,
+ -1.25,
+ 0.15,
+ 0.2,
+ -0.1
+ ],
+ "velocity_scale": 0.2,
+ "acceleration_scale": 0.2
+ }
+ },
+ {
+ "label": "joint-b",
+ "tool_id": "sim.set_joint_positions",
+ "arguments": {
+ "group_name": "piper_x_arm",
+ "joint_names": [
+ "joint1",
+ "joint2",
+ "joint3",
+ "joint4",
+ "joint5",
+ "joint6"
+ ],
+ "positions": [
+ 0.2,
+ 0.6,
+ -0.9,
+ -0.2,
+ 0.4,
+ 0.25
+ ],
+ "velocity_scale": 0.2,
+ "acceleration_scale": 0.2
+ }
+ },
+ {
+ "label": "joint-home",
+ "tool_id": "sim.set_joint_positions",
+ "arguments": {
+ "group_name": "piper_x_arm",
+ "joint_names": [
+ "joint1",
+ "joint2",
+ "joint3",
+ "joint4",
+ "joint5",
+ "joint6"
+ ],
+ "positions": [
+ 0,
+ 0.65,
+ -1.1,
+ 0.25,
+ 0.3,
+ 0.1
+ ],
+ "velocity_scale": 0.2,
+ "acceleration_scale": 0.2
+ }
+ },
+ {
+ "label": "eef-a",
+ "tool_id": "sim.move_eef",
+ "arguments": {
+ "group_name": "piper_x_arm",
+ "reference_frame": "base_link",
+ "target_frame": "tcp",
+ "target_pose": {
+ "x": 0.2870407951459706,
+ "y": -0.03170407513342734,
+ "z": 0.5422729661601198,
+ "qw": 0.7657215005588278,
+ "qx": 0.1641599926622322,
+ "qy": 0.6218396509287355,
+ "qz": -0.006126085528408748
+ },
+ "velocity_scale": 0.2,
+ "acceleration_scale": 0.2,
+ "position_tolerance_m": 0.005,
+ "orientation_tolerance_rad": 0.03
+ }
+ },
+ {
+ "label": "eef-b",
+ "tool_id": "sim.move_eef",
+ "arguments": {
+ "group_name": "piper_x_arm",
+ "reference_frame": "base_link",
+ "target_frame": "tcp",
+ "target_pose": {
+ "x": 0.26220754945611513,
+ "y": -0.07584908836668063,
+ "z": 0.5653411741297875,
+ "qw": 0.8005078003734996,
+ "qx": 0.15001903453597412,
+ "qy": 0.5713479547474468,
+ "qz": -0.10120803043229705
+ },
+ "velocity_scale": 0.2,
+ "acceleration_scale": 0.2,
+ "position_tolerance_m": 0.005,
+ "orientation_tolerance_rad": 0.03
+ }
+ },
+ {
+ "label": "eef-home",
+ "tool_id": "sim.move_eef",
+ "arguments": {
+ "group_name": "piper_x_arm",
+ "reference_frame": "base_link",
+ "target_frame": "tcp",
+ "target_pose": {
+ "x": 0.2558384528449723,
+ "y": -0.052454819814354174,
+ "z": 0.5522704688371596,
+ "qw": 0.795475677980765,
+ "qx": 0.14913411735079685,
+ "qy": 0.585235291451576,
+ "qz": -0.04977061806558024
+ },
+ "velocity_scale": 0.2,
+ "acceleration_scale": 0.2,
+ "position_tolerance_m": 0.005,
+ "orientation_tolerance_rad": 0.03
+ }
+ },
+ {
+ "label": "gripper-smoke",
+ "tool_id": "sim.set_gripper_opening",
+ "arguments": {
+ "opening_m": 0.06
+ }
+ },
+ {
+ "label": "reset",
+ "tool_id": "sim.reset",
+ "arguments": {}
+ }
+]
diff --git a/example/robot-control-sim-piper-x/node-locks.json b/example/robot-control-sim-piper-x/node-locks.json
new file mode 100644
index 000000000..069447d36
--- /dev/null
+++ b/example/robot-control-sim-piper-x/node-locks.json
@@ -0,0 +1,83 @@
+{
+ "gateway": {
+ "artifact_id": "gateway-1.0.2-linux-x86_64-tar-gz",
+ "version": "1.0.2",
+ "platform": "linux",
+ "arch": "x86_64",
+ "artifact_type": "executable_tar_gz",
+ "entrypoint": "gateway",
+ "sha256": "07584846f16012c6137b10cf743073cd2fe9a7f64564ba2322a7090e66fd3076"
+ },
+ "sim_control_policy": {
+ "artifact_id": "sim_control_policy-0.1.2-linux-x86_64-tar-gz",
+ "version": "0.1.2",
+ "platform": "linux",
+ "arch": "x86_64",
+ "artifact_type": "executable_tar_gz",
+ "entrypoint": "sim_control_policy",
+ "sha256": "8a66d4cacd49e018b1acee8f44712c4e3eccf95c0f40b7e45e1825503e086198"
+ },
+ "motion_action_policy": {
+ "artifact_id": "motion_action_policy-0.1.0-linux-x86_64-tar-gz",
+ "version": "0.1.0",
+ "platform": "linux",
+ "arch": "x86_64",
+ "artifact_type": "executable_tar_gz",
+ "entrypoint": "motion_action_policy",
+ "sha256": "c64c3c8a725ce70174f9f545c3bb3b793680544adc551afb9ee504a4010c50d9"
+ },
+ "gripper_action_policy": {
+ "artifact_id": "gripper_action_policy-0.1.0-linux-x86_64-tar-gz",
+ "version": "0.1.0",
+ "platform": "linux",
+ "arch": "x86_64",
+ "artifact_type": "executable_tar_gz",
+ "entrypoint": "gripper_action_policy",
+ "sha256": "1afc5157bae3ddf8cf673db3375d6e05d6a82b1d061f0dcb142ff6480b9d38d0"
+ },
+ "motion_server": {
+ "artifact_id": "motion_server-0.1.0-linux-x86_64-tar-gz",
+ "version": "0.1.0",
+ "platform": "linux",
+ "arch": "x86_64",
+ "artifact_type": "executable_tar_gz",
+ "entrypoint": "motion_server",
+ "sha256": "91041350abbef24226527ffc8a9f3854ef1c57d4d488972b9ff536f8db265c99"
+ },
+ "joint_trajectory_controller": {
+ "artifact_id": "joint_trajectory_controller-0.1.0-linux-x86_64-tar-gz",
+ "version": "0.1.0",
+ "platform": "linux",
+ "arch": "x86_64",
+ "artifact_type": "executable_tar_gz",
+ "entrypoint": "joint_trajectory_controller",
+ "sha256": "a57da3fa4211a5df4e1485724f2d11ef402fbce844950a176b64d2e4ab681efc"
+ },
+ "gripper_action_controller": {
+ "artifact_id": "gripper_action_controller-0.1.0-linux-x86_64-tar-gz",
+ "version": "0.1.0",
+ "platform": "linux",
+ "arch": "x86_64",
+ "artifact_type": "executable_tar_gz",
+ "entrypoint": "gripper_action_controller",
+ "sha256": "a210987c1694d8fb9ed6576af469027c934ab707e470b43f164be3aee876c0f1"
+ },
+ "mujoco_sim": {
+ "artifact_id": "mujoco_sim-1.1.1-linux-x86_64-tar-gz",
+ "version": "1.1.1",
+ "platform": "linux",
+ "arch": "x86_64",
+ "artifact_type": "executable_tar_gz",
+ "entrypoint": "mujoco_sim",
+ "sha256": "4bb658e32aad1e4cb8c61d085e6dc5670611fb41760da6c705989f8fda19c826"
+ },
+ "image_viewer": {
+ "artifact_id": "image_viewer-1.0.1-linux-x86_64-tar-gz",
+ "version": "1.0.1",
+ "platform": "linux",
+ "arch": "x86_64",
+ "artifact_type": "executable_tar_gz",
+ "entrypoint": "image_viewer",
+ "sha256": "d336210e7a4c638cfba785081e9b939e0767fc17c5d7b60dbcf72c2b6d91e0fb"
+ }
+}
diff --git a/example/robot-control-sim-piper-x/requirements-model.txt b/example/robot-control-sim-piper-x/requirements-model.txt
new file mode 100644
index 000000000..542780939
--- /dev/null
+++ b/example/robot-control-sim-piper-x/requirements-model.txt
@@ -0,0 +1,3 @@
+mujoco==3.3.7
+numpy==2.3.4
+PyYAML==6.0.3
diff --git a/example/robot-control-sim-piper-x/validate_model.py b/example/robot-control-sim-piper-x/validate_model.py
new file mode 100644
index 000000000..4467d2b04
--- /dev/null
+++ b/example/robot-control-sim-piper-x/validate_model.py
@@ -0,0 +1,100 @@
+"""Independent URDF-vs-MuJoCo FK plus servo stability checks (no PAOS bypass acceptance)."""
+import argparse
+import json
+import math
+from pathlib import Path
+import xml.etree.ElementTree as ET
+
+import mujoco
+import numpy as np
+import yaml
+
+ROOT = Path(__file__).resolve().parent
+ROBOT = ROOT / 'robot-control-sim-piper-x/assets/robots/piper_x'
+JOINTS = [f'joint{i}' for i in range(1, 7)]
+
+
+def rotation(rpy):
+ r, p, y = rpy
+ cr, sr, cp, sp, cy, sy = math.cos(r), math.sin(r), math.cos(p), math.sin(p), math.cos(y), math.sin(y)
+ return np.array([[cy*cp, cy*sp*sr-sy*cr, cy*sp*cr+sy*sr],
+ [sy*cp, sy*sp*sr+cy*cr, sy*sp*cr-cy*sr], [-sp, cp*sr, cp*cr]])
+
+
+def fk(q):
+ urdf = ET.parse(ROBOT / 'piper_x_with_gripper.urdf').getroot()
+ by_child = {j.find('child').get('link'): j for j in urdf.findall('joint')}
+ chain, child = [], 'tcp'
+ while child != 'base_link':
+ j = by_child[child]; chain.append(j); child = j.find('parent').get('link')
+ t = np.eye(4)
+ for j in reversed(chain):
+ origin = j.find('origin')
+ transform = np.eye(4)
+ if origin is not None:
+ transform[:3, 3] = np.fromstring(origin.get('xyz', '0 0 0'), sep=' ')
+ transform[:3, :3] = rotation(np.fromstring(origin.get('rpy', '0 0 0'), sep=' '))
+ t = t @ transform
+ if j.get('name') in JOINTS:
+ axis = np.fromstring(j.find('axis').get('xyz'), sep=' ')
+ theta = q[JOINTS.index(j.get('name'))]
+ k = np.array([[0,-axis[2],axis[1]],[axis[2],0,-axis[0]],[-axis[1],axis[0],0]])
+ transform = np.eye(4)
+ transform[:3, :3] = np.eye(3) + math.sin(theta)*k + (1-math.cos(theta))*(k@k)
+ t = t @ transform
+ quat = np.zeros(4); mujoco.mju_mat2Quat(quat, t[:3,:3].reshape(-1))
+ pose = dict(zip(['x','y','z','qw','qx','qy','qz'], [*t[:3,3], *quat]))
+ return t, pose
+
+
+def main():
+ descriptor = yaml.safe_load((ROBOT/'robot.yaml').read_text())
+ model = mujoco.MjModel.from_xml_path(str(ROBOT/'mjcf/scene.xml'))
+ data = mujoco.MjData(model)
+ ids = [model.joint(j).id for j in JOINTS]
+ qidx = [model.jnt_qposadr[i] for i in ids]
+ initial = [descriptor['initial_qpos'][j] for j in JOINTS]
+ rng = np.random.default_rng(20261020)
+ cases = [initial] + [rng.uniform([-.5,.2,-1.7,-.5,-.6,-.8], [.5,1.3,-.4,.5,.6,.8]).tolist() for _ in range(30)]
+ rows = []
+ for q in cases:
+ data.qpos[qidx] = q; mujoco.mj_forward(model,data)
+ t, pose = fk(q)
+ pos_err = float(np.linalg.norm(data.site('tcp').xpos-t[:3,3]))
+ rot_err = float(np.max(np.abs(data.site('tcp').xmat.reshape(3,3)-t[:3,:3])))
+ assert pos_err < 1e-6 and rot_err < 1e-6, (pos_err,rot_err)
+ rows.append({'q':q,'position_error_m':pos_err,'rotation_matrix_max_error':rot_err})
+ # Test the same model's physical servos separately from runtime acceptance.
+ mujoco.mj_resetData(model,data)
+ data.qpos[qidx] = initial
+ data.joint('gripper_joint1').qpos[:] = .02
+ data.joint('gripper_joint2').qpos[:] = -.02
+ data.ctrl[:] = initial + [.04]
+ mujoco.mj_forward(model,data)
+ initial_contacts = data.ncon
+ for _ in range(2500): mujoco.mj_step(model,data)
+ residual = np.abs(data.qpos[qidx]-initial)
+ assert np.isfinite(data.qpos).all() and max(residual)<.03, residual
+ targetq = [.12,.75,-1.18,.33,.38,.18]
+ _, target = fk(targetq)
+ report = {'mujoco_version':mujoco.__version__,'fk_cases':len(rows),
+ 'max_fk_position_error_m':max(r['position_error_m'] for r in rows),
+ 'max_fk_rotation_matrix_error':max(r['rotation_matrix_max_error'] for r in rows),
+ 'cases':rows,'initial_contacts':initial_contacts,'final_contacts':data.ncon,
+ 'hold_max_error_rad':float(max(residual)), 'initial_pose':fk(initial)[1],
+ 'eef_target_seed_joints':targetq,'eef_target_pose':target,
+ 'actuator_order':[model.actuator(i).name for i in range(model.nu)],
+ 'physical_dof':model.nq,'logical_dof':len(descriptor['joints'])}
+ (ROOT/'model-validation.json').write_text(json.dumps(report,indent=2))
+ print(json.dumps({k:v for k,v in report.items() if k!='cases'},indent=2))
+
+
+if __name__ == '__main__':
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument('--skill', type=Path, required=True)
+ parser.add_argument('--output-dir', type=Path, required=True)
+ args = parser.parse_args()
+ ROBOT = args.skill.resolve() / 'assets/robots/piper_x'
+ ROOT = args.output_dir.resolve()
+ ROOT.mkdir(parents=True, exist_ok=True)
+ main()
diff --git a/pyproject.toml b/pyproject.toml
index 1160431d9..1b3f753aa 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "PhyAgentOS-ai"
-version = "1.1.0"
+version = "1.1.1"
description = "A lightweight personal AI assistant framework"
readme = "README.md"
requires-python = ">=3.11"
diff --git a/scripts/pypi_release.py b/scripts/pypi_release.py
new file mode 100644
index 000000000..520b5c69c
--- /dev/null
+++ b/scripts/pypi_release.py
@@ -0,0 +1,208 @@
+"""Verify GitHub release distributions before publishing the same bytes to PyPI.
+
+Uses only the standard library; never imports or executes the release package.
+"""
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import shutil
+import subprocess
+import tarfile
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import zipfile
+from email.parser import BytesParser
+from pathlib import Path
+
+PROJECT = "PhyAgentOS-ai"
+REPOSITORY = "PhyAgentOS/PhyAgentOS-core"
+
+
+def version_for(tag):
+ if not re.fullmatch(r"v(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)\.(?:0|[1-9][0-9]*)", tag):
+ raise ValueError("Only stable vMAJOR.MINOR.PATCH tags are supported")
+ return tag[1:]
+
+
+def filenames(version):
+ return (
+ f"phyagentos_ai-{version}-py3-none-any.whl",
+ f"phyagentos_ai-{version}.tar.gz",
+ )
+
+
+def canonical_name(name):
+ return re.sub(r"[-_.]+", "-", name).lower()
+
+
+def validate_metadata(data, version):
+ metadata = BytesParser().parsebytes(data)
+ if canonical_name(metadata.get("Name", "")) != canonical_name(PROJECT):
+ raise ValueError("Distribution project name does not match PhyAgentOS-ai")
+ if metadata.get("Version") != version:
+ raise ValueError("Distribution version does not match release tag")
+
+
+def verify_assets(directory, tag):
+ version = version_for(tag)
+ expected = set(filenames(version))
+ checksums = {}
+ for line in (directory / "SHA256SUMS").read_text().splitlines():
+ match = re.fullmatch(r"([0-9a-f]{64}) [ *](\S+)", line)
+ if not match or match[2] not in expected or match[2] in checksums:
+ raise ValueError("SHA256SUMS must list each expected distribution exactly once")
+ checksums[match[2]] = match[1]
+ if set(checksums) != expected:
+ raise ValueError("SHA256SUMS is missing a distribution")
+ for filename, digest in checksums.items():
+ path = directory / filename
+ if path.is_symlink() or hashlib.sha256(path.read_bytes()).hexdigest() != digest:
+ raise ValueError(f"SHA256 mismatch: {filename}")
+ if filename.endswith(".whl"):
+ with zipfile.ZipFile(path) as archive:
+ members = [n for n in archive.namelist() if n.endswith(".dist-info/METADATA")]
+ if len(members) != 1:
+ raise ValueError("Wheel must contain exactly one METADATA file")
+ validate_metadata(archive.read(members[0]), version)
+ else:
+ with tarfile.open(path, "r:gz") as archive:
+ member = archive.getmember(f"phyagentos_ai-{version}/PKG-INFO")
+ if not member.isfile():
+ raise ValueError("Source distribution PKG-INFO must be a regular file")
+ validate_metadata(archive.extractfile(member).read(), version)
+ return checksums
+
+
+def release_assets(release, tag):
+ version = version_for(tag)
+ if release["tag_name"] != tag or release["draft"] or release["prerelease"]:
+ raise ValueError("Only a published stable GitHub release can be uploaded")
+ if not release.get("published_at"):
+ raise ValueError("GitHub release has not been published")
+ expected = {*filenames(version), "SHA256SUMS"}
+ assets = [a for a in release["assets"] if a["name"] in expected]
+ if len(assets) != 3 or {a["name"] for a in assets} != expected:
+ raise ValueError("Release must include wheel, source distribution and SHA256SUMS")
+ return assets
+
+
+def download_assets(tag, directory):
+ release = json.loads(subprocess.check_output([
+ "gh", "api", f"repos/{REPOSITORY}/releases/tags/{tag}",
+ ]))
+ assets = release_assets(release, tag)
+ directory.mkdir(parents=True, exist_ok=True)
+ for asset in assets:
+ path = directory / asset["name"]
+ with path.open("wb") as output:
+ subprocess.run([
+ "gh", "api", f"repos/{REPOSITORY}/releases/assets/{asset['id']}",
+ "-H", "Accept: application/octet-stream",
+ ], stdout=output, check=True)
+ if path.stat().st_size != asset["size"]:
+ raise ValueError(f"Release asset size mismatch: {path.name}")
+ digest = asset.get("digest")
+ if digest and digest != f"sha256:{hashlib.sha256(path.read_bytes()).hexdigest()}":
+ raise ValueError(f"GitHub asset digest mismatch: {path.name}")
+
+
+def pypi_files(version):
+ try:
+ with urllib.request.urlopen(
+ f"https://pypi.org/pypi/{PROJECT}/{version}/json", timeout=30,
+ ) as response:
+ return json.load(response)["urls"]
+ except urllib.error.HTTPError as error:
+ if error.code == 404:
+ return []
+ raise
+
+
+def missing_files(checksums, published):
+ seen = set()
+ for item in published:
+ name = item["filename"]
+ if name not in checksums or name in seen:
+ raise ValueError(f"Unexpected or duplicate file on PyPI: {name}")
+ if item.get("yanked"):
+ raise ValueError(f"PyPI file is yanked: {name}")
+ if item["digests"]["sha256"] != checksums[name]:
+ raise ValueError(f"PyPI already has different bytes for {name}; use a new version")
+ seen.add(name)
+ return sorted(set(checksums) - seen)
+
+
+def stage_missing(directory, upload_dir, checksums, published):
+ missing = missing_files(checksums, published)
+ upload_dir.mkdir(parents=True, exist_ok=False)
+ for filename in missing:
+ shutil.copyfile(directory / filename, upload_dir / filename)
+ return missing
+
+
+def verify_pypi(checksums, version, attempts=12, delay=10):
+ for attempt in range(attempts):
+ try:
+ missing = missing_files(checksums, pypi_files(version))
+ if not missing:
+ print("PyPI filenames and SHA256 hashes match the GitHub release")
+ return
+ except urllib.error.HTTPError as error:
+ if error.code < 500 and error.code != 429:
+ raise
+ except urllib.error.URLError:
+ pass
+ if attempt + 1 < attempts:
+ time.sleep(delay)
+ raise ValueError("PyPI did not expose all expected distributions before the timeout")
+
+
+def verify_install_report(report_path, checksums, version):
+ installs = json.loads(report_path.read_text())["install"]
+ matches = [i for i in installs if canonical_name(i["metadata"]["name"]) == canonical_name(PROJECT)]
+ if len(matches) != 1 or matches[0]["metadata"]["version"] != version:
+ raise ValueError("pip did not install the requested project and version")
+ download = matches[0]["download_info"]
+ # pip must fetch the release wheel from the official PyPI file service.
+ url = urllib.parse.urlparse(download["url"])
+ wheel = filenames(version)[0]
+ if url.scheme != "https" or url.hostname != "files.pythonhosted.org" or not url.path.endswith("/" + wheel):
+ raise ValueError("pip did not download the expected wheel from official PyPI")
+ if download["archive_info"]["hashes"]["sha256"] != checksums[wheel]:
+ raise ValueError("Installed wheel SHA256 differs from the GitHub release")
+
+
+def main():
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("mode", choices=["prepare", "verify", "installed"])
+ parser.add_argument("--tag", required=True)
+ parser.add_argument("--assets", type=Path, default=Path("release-assets"))
+ parser.add_argument("--upload-dir", type=Path, default=Path("dist"))
+ parser.add_argument("--report", type=Path)
+ args = parser.parse_args()
+ version = version_for(args.tag)
+ if args.mode == "prepare":
+ download_assets(args.tag, args.assets)
+ checksums = verify_assets(args.assets, args.tag)
+ if args.mode == "prepare":
+ missing = stage_missing(args.assets, args.upload_dir, checksums, pypi_files(version))
+ print(f"Verified {args.tag}: {len(missing)} distribution(s) need uploading")
+ if os.environ.get("GITHUB_OUTPUT"):
+ with open(os.environ["GITHUB_OUTPUT"], "a") as output:
+ output.write(f"version={version}\nmissing={len(missing)}\n")
+ elif args.mode == "verify":
+ verify_pypi(checksums, version)
+ else:
+ if args.report is None:
+ parser.error("--report is required for installed mode")
+ verify_install_report(args.report, checksums, version)
+ print("Installed wheel came from official PyPI and matches the release SHA256")
+
+
+if __name__ == "__main__":
+ main()
diff --git a/scripts/tests/test_pypi_release.py b/scripts/tests/test_pypi_release.py
new file mode 100644
index 000000000..3e4ef22c8
--- /dev/null
+++ b/scripts/tests/test_pypi_release.py
@@ -0,0 +1,161 @@
+"""Release checks must fail closed and support retries without changing bytes."""
+
+import hashlib
+import io
+import json
+import tarfile
+import tempfile
+import unittest
+import urllib.error
+import zipfile
+from pathlib import Path
+from unittest.mock import patch
+
+from scripts import pypi_release as release
+
+
+class ReleaseTests(unittest.TestCase):
+ def setUp(self):
+ self.temp = tempfile.TemporaryDirectory()
+ self.addCleanup(self.temp.cleanup)
+ self.directory = Path(self.temp.name)
+ self.tag = "v1.2.3"
+ self.version = "1.2.3"
+ self.wheel, self.sdist = release.filenames(self.version)
+ self.make_assets()
+
+ def make_assets(self, name="PhyAgentOS-ai", version="1.2.3"):
+ metadata = f"Metadata-Version: 2.4\nName: {name}\nVersion: {version}\n\n".encode()
+ with zipfile.ZipFile(self.directory / self.wheel, "w") as archive:
+ archive.writestr("phyagentos_ai-1.2.3.dist-info/METADATA", metadata)
+ with tarfile.open(self.directory / self.sdist, "w:gz") as archive:
+ member = tarfile.TarInfo("phyagentos_ai-1.2.3/PKG-INFO")
+ member.size = len(metadata)
+ archive.addfile(member, io.BytesIO(metadata))
+ self.checksums = {
+ name: hashlib.sha256((self.directory / name).read_bytes()).hexdigest()
+ for name in (self.wheel, self.sdist)
+ }
+ (self.directory / "SHA256SUMS").write_text("".join(
+ f"{digest} *{name}\n" for name, digest in self.checksums.items()
+ ))
+
+ def published(self):
+ return [{"filename": name, "digests": {"sha256": digest}, "yanked": False}
+ for name, digest in self.checksums.items()]
+
+ def test_verified_assets(self):
+ self.assertEqual(release.verify_assets(self.directory, self.tag), self.checksums)
+
+ def test_invalid_tags(self):
+ for tag in ["1.2.3", "v1.2.3rc1", "v01.2.3", "v1.2.3\n", "v1.2.3; echo bad"]:
+ with self.subTest(tag=tag), self.assertRaises(ValueError):
+ release.version_for(tag)
+
+ def test_corrupt_artifact(self):
+ (self.directory / self.wheel).write_bytes(b"corrupted")
+ with self.assertRaisesRegex(ValueError, "SHA256 mismatch"):
+ release.verify_assets(self.directory, self.tag)
+
+ def test_missing_artifact(self):
+ (self.directory / self.sdist).unlink()
+ with self.assertRaises(FileNotFoundError):
+ release.verify_assets(self.directory, self.tag)
+
+ def test_manifest_rejects_traversal_duplicates_and_missing_entries(self):
+ path = self.directory / "SHA256SUMS"
+ original = path.read_text()
+ for text in [original.replace(self.wheel, "../" + self.wheel),
+ original + original, original.splitlines()[0] + "\n"]:
+ with self.subTest(text=text), self.assertRaises(ValueError):
+ path.write_text(text)
+ release.verify_assets(self.directory, self.tag)
+
+ def test_wrong_package_name_or_version(self):
+ for name, version in [("unrelated-project", self.version), (release.PROJECT, "9.9.9")]:
+ with self.subTest(name=name, version=version), self.assertRaises(ValueError):
+ self.make_assets(name, version)
+ release.verify_assets(self.directory, self.tag)
+
+ def test_unpublished_or_incomplete_release(self):
+ good = {"tag_name": self.tag, "draft": False, "prerelease": False,
+ "published_at": "2026-10-27T00:00:00Z",
+ "assets": [{"name": n} for n in [self.wheel, self.sdist, "SHA256SUMS"]]}
+ self.assertEqual(len(release.release_assets(good, self.tag)), 3)
+ for change in [{"draft": True}, {"prerelease": True}, {"published_at": None},
+ {"tag_name": "v9.9.9"}, {"assets": good["assets"][:-1]}]:
+ with self.subTest(change=change), self.assertRaises(ValueError):
+ release.release_assets(good | change, self.tag)
+
+ def test_new_version_stages_only_package_files(self):
+ target = self.directory / "upload"
+ missing = release.stage_missing(self.directory, target, self.checksums, [])
+ self.assertEqual(set(missing), set(self.checksums))
+ self.assertEqual({p.name for p in target.iterdir()}, set(self.checksums))
+ for name in missing:
+ self.assertEqual((target / name).read_bytes(), (self.directory / name).read_bytes())
+
+ def test_same_version_is_noop(self):
+ self.assertEqual(release.missing_files(self.checksums, self.published()), [])
+
+ def test_partial_upload_stages_only_missing_file(self):
+ target = self.directory / "upload"
+ self.assertEqual(release.stage_missing(
+ self.directory, target, self.checksums, self.published()[:1],
+ ), [self.sdist])
+ self.assertEqual([p.name for p in target.iterdir()], [self.sdist])
+
+ def test_conflicting_hash_blocks_upload(self):
+ published = self.published()
+ published[0]["digests"]["sha256"] = "0" * 64
+ with self.assertRaisesRegex(ValueError, "different bytes"):
+ release.stage_missing(self.directory, self.directory / "upload", self.checksums, published)
+ self.assertFalse((self.directory / "upload").exists())
+
+ def test_yanked_unexpected_and_duplicate_files_fail(self):
+ published = self.published()
+ for files in [[published[0] | {"yanked": True}],
+ [published[0] | {"filename": "other.whl"}], published + published]:
+ with self.subTest(files=files), self.assertRaises(ValueError):
+ release.missing_files(self.checksums, files)
+
+ def test_only_pypi_404_means_not_published(self):
+ for status in [404, 403, 503]:
+ error = urllib.error.HTTPError("https://pypi.org", status, "error", {}, None)
+ with patch.object(release.urllib.request, "urlopen", side_effect=error):
+ if status == 404:
+ self.assertEqual(release.pypi_files(self.version), [])
+ else:
+ with self.assertRaises(urllib.error.HTTPError):
+ release.pypi_files(self.version)
+
+ def test_post_upload_waits_for_registry(self):
+ with patch.object(release, "pypi_files", side_effect=[[], self.published()]) as query:
+ release.verify_pypi(self.checksums, self.version, attempts=2, delay=0)
+ self.assertEqual(query.call_count, 2)
+
+ def test_post_upload_never_accepts_conflicts(self):
+ published = self.published()
+ published[0]["digests"]["sha256"] = "0" * 64
+ with patch.object(release, "pypi_files", return_value=published) as query:
+ with self.assertRaises(ValueError):
+ release.verify_pypi(self.checksums, self.version, attempts=2, delay=0)
+ self.assertEqual(query.call_count, 1)
+
+ def test_install_report_origin_and_hash(self):
+ info = {"url": f"https://files.pythonhosted.org/packages/{self.wheel}",
+ "archive_info": {"hashes": {"sha256": self.checksums[self.wheel]}}}
+ item = {"metadata": {"name": release.PROJECT, "version": self.version},
+ "download_info": info}
+ report = self.directory / "report.json"
+ report.write_text(json.dumps({"install": [item]}))
+ release.verify_install_report(report, self.checksums, self.version)
+ for change in [{"url": f"https://example.com/{self.wheel}"},
+ {"archive_info": {"hashes": {"sha256": "0" * 64}}}]:
+ report.write_text(json.dumps({"install": [item | {"download_info": info | change}]}))
+ with self.subTest(change=change), self.assertRaises(ValueError):
+ release.verify_install_report(report, self.checksums, self.version)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/test_forge_action_rejection_status.py b/tests/test_forge_action_rejection_status.py
new file mode 100644
index 000000000..5f0767571
--- /dev/null
+++ b/tests/test_forge_action_rejection_status.py
@@ -0,0 +1,272 @@
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+from PhyAgentOS.config.schema import ForgeConfig
+from PhyAgentOS.forge.task import AgentTaskCoordinator, AgentTaskError
+from PhyAgentOS.forge.tool_client import ForgeToolAPIError, ForgeToolAPITimeoutError
+from PhyAgentOS.verification.contracts import (
+ CriterionVerdict,
+ TaskVerificationContract,
+ VerificationAttempt,
+ VerificationVerdict,
+)
+
+
+class FlakyActionClient:
+ """Raises the configured error on the first invoke_action, then succeeds."""
+
+ def __init__(self, error: Exception) -> None:
+ self.error = error
+ self.raised = False
+
+ async def invoke_action(
+ self,
+ tool_id: str,
+ arguments: dict[str, Any],
+ **_: Any,
+ ) -> dict[str, Any]:
+ if not self.raised:
+ self.raised = True
+ raise self.error
+ return {
+ "ok": True,
+ "data": {
+ "tool_id": tool_id,
+ "invocation_id": "inv_recovered",
+ "attempt_id": "attempt_recovered",
+ "arguments": arguments,
+ },
+ }
+
+
+class AcceptingVerifier:
+ """Returns a satisfied verdict; audit mode only looks at execution facts."""
+
+ async def verify_agent_task(self, task: Any, **_: Any):
+ criterion = task.verification.success_criteria[0]
+ return (
+ VerificationVerdict(
+ verdict="success",
+ criteria=[CriterionVerdict(criterion=criterion, status="satisfied")],
+ reason="audit verification accepted",
+ ),
+ None,
+ VerificationAttempt(attempt_id="verify_1"),
+ )
+
+
+def _coordinator(
+ tmp_path, client: FlakyActionClient, *, verifier: Any | None = None
+) -> AgentTaskCoordinator:
+ return AgentTaskCoordinator(
+ workspace=tmp_path,
+ config=ForgeConfig(),
+ client=client, # type: ignore[arg-type]
+ verifier=verifier,
+ )
+
+
+def _new_task(coordinator: AgentTaskCoordinator) -> str:
+ task = coordinator.create_task(
+ task_description="move the arm",
+ verification=TaskVerificationContract(mode="off"),
+ )
+ return task.task_id
+
+
+async def test_pre_dispatch_rejection_records_failed_and_allows_identical_resend(
+ tmp_path,
+) -> None:
+ client = FlakyActionClient(
+ ForgeToolAPIError(
+ "operation concurrency 1 is exhausted",
+ status_code=503,
+ error_code="FORGE_TOOL_GATEWAY_BUSY",
+ retryable=True,
+ )
+ )
+ coordinator = _coordinator(tmp_path, client)
+ task_id = _new_task(coordinator)
+
+ with pytest.raises(ForgeToolAPIError):
+ await coordinator.start_action(task_id, "motion.move_pose", {"distance_m": 0.05})
+ records = coordinator.store.get(task_id).execution_records
+ assert [record.status for record in records] == ["failed"]
+
+ # The gateway never dispatched anything, so the identical resend must
+ # not be blocked by the unknown-remote-state guard.
+ response = await coordinator.start_action(task_id, "motion.move_pose", {"distance_m": 0.05})
+ assert response["data"]["invocation_id"] == "inv_recovered"
+ records = coordinator.store.get(task_id).execution_records
+ assert [record.status for record in records] == ["failed", "accepted"]
+
+
+async def test_action_admission_rejection_records_failed_and_allows_resend(
+ tmp_path,
+) -> None:
+ # Gateway 1.1.2+ reports admission refusal separately from busy; both mean
+ # the invoke never reached the provider.
+ client = FlakyActionClient(
+ ForgeToolAPIError(
+ "endpoint 'motion.server' has no active provider instance",
+ status_code=503,
+ error_code="FORGE_TOOL_ACTION_ADMISSION_REJECTED",
+ retryable=True,
+ )
+ )
+ coordinator = _coordinator(tmp_path, client)
+ task_id = _new_task(coordinator)
+
+ with pytest.raises(ForgeToolAPIError):
+ await coordinator.start_action(task_id, "motion.move_pose", {"distance_m": 0.05})
+ records = coordinator.store.get(task_id).execution_records
+ assert [record.status for record in records] == ["failed"]
+ assert records[0].rejected_before_dispatch is True
+
+ response = await coordinator.start_action(task_id, "motion.move_pose", {"distance_m": 0.05})
+ assert response["data"]["invocation_id"] == "inv_recovered"
+
+
+async def test_http_timeout_stays_unknown_and_arms_identical_guard(tmp_path) -> None:
+ client = FlakyActionClient(ForgeToolAPITimeoutError("exchange timed out"))
+ coordinator = _coordinator(tmp_path, client)
+ task_id = _new_task(coordinator)
+
+ with pytest.raises(ForgeToolAPITimeoutError):
+ await coordinator.start_action(task_id, "motion.move_pose", {"distance_m": 0.05})
+ records = coordinator.store.get(task_id).execution_records
+ assert [record.status for record in records] == ["unknown"]
+
+ with pytest.raises(AgentTaskError, match="identical Action"):
+ await coordinator.start_action(task_id, "motion.move_pose", {"distance_m": 0.05})
+
+
+async def test_invoke_timeout_error_code_is_not_treated_as_pre_dispatch(
+ tmp_path,
+) -> None:
+ # FORGE_TOOL_INVOKE_TIMEOUT is also emitted after dispatch when the
+ # synchronous caller response times out, so a structured code alone must
+ # not downgrade the record to failed.
+ client = FlakyActionClient(
+ ForgeToolAPIError(
+ "Action deadline elapsed",
+ status_code=504,
+ error_code="FORGE_TOOL_INVOKE_TIMEOUT",
+ retryable=False,
+ )
+ )
+ coordinator = _coordinator(tmp_path, client)
+ task_id = _new_task(coordinator)
+
+ with pytest.raises(ForgeToolAPIError):
+ await coordinator.start_action(task_id, "motion.move_pose", {"distance_m": 0.05})
+ records = coordinator.store.get(task_id).execution_records
+ assert [record.status for record in records] == ["unknown"]
+
+
+def _rejection() -> ForgeToolAPIError:
+ return ForgeToolAPIError(
+ "operation concurrency 1 is exhausted",
+ status_code=503,
+ error_code="FORGE_TOOL_GATEWAY_BUSY",
+ retryable=True,
+ )
+
+
+async def test_finalization_succeeds_after_a_rejected_attempt_is_retried(
+ tmp_path,
+) -> None:
+ coordinator = _coordinator(tmp_path, FlakyActionClient(_rejection()))
+ task_id = _new_task(coordinator)
+
+ with pytest.raises(ForgeToolAPIError):
+ await coordinator.start_action(task_id, "motion.move_pose", {"distance_m": 0.05})
+ response = await coordinator.start_action(task_id, "motion.move_pose", {"distance_m": 0.05})
+ coordinator.observe_action(
+ task_id,
+ response["data"]["invocation_id"],
+ {"phase": "completed"},
+ )
+
+ finalized = await coordinator.finalize_task(task_id)
+
+ assert finalized.status.value == "succeeded"
+ assert [record.status for record in finalized.execution_records] == [
+ "failed",
+ "succeeded",
+ ]
+ assert [record.rejected_before_dispatch for record in finalized.execution_records] == [
+ True,
+ False,
+ ]
+
+
+async def test_finalization_fails_when_every_attempt_was_rejected_before_dispatch(
+ tmp_path,
+) -> None:
+ coordinator = _coordinator(tmp_path, FlakyActionClient(_rejection()))
+ task_id = _new_task(coordinator)
+
+ with pytest.raises(ForgeToolAPIError):
+ await coordinator.start_action(task_id, "motion.move_pose", {"distance_m": 0.05})
+
+ finalized = await coordinator.finalize_task(task_id)
+
+ # A rejected call never executed, so it can neither satisfy nor poison the
+ # task; with no actual execution the task did not succeed.
+ assert finalized.status.value == "failed"
+ assert [record.rejected_before_dispatch for record in finalized.execution_records] == [True]
+
+
+async def test_finalization_fails_when_a_dispatched_attempt_failed(
+ tmp_path,
+) -> None:
+ coordinator = _coordinator(tmp_path, FlakyActionClient(_rejection()))
+ task_id = _new_task(coordinator)
+
+ with pytest.raises(ForgeToolAPIError):
+ await coordinator.start_action(task_id, "motion.move_pose", {"distance_m": 0.05})
+ response = await coordinator.start_action(task_id, "motion.move_pose", {"distance_m": 0.05})
+ coordinator.observe_action(
+ task_id,
+ response["data"]["invocation_id"],
+ {"phase": "failed"},
+ )
+
+ finalized = await coordinator.finalize_task(task_id)
+
+ assert finalized.status.value == "failed"
+
+
+async def test_audit_finalization_ignores_a_rejected_attempt(tmp_path) -> None:
+ coordinator = _coordinator(
+ tmp_path, FlakyActionClient(_rejection()), verifier=AcceptingVerifier()
+ )
+ task = coordinator.create_task(
+ task_description="move the arm",
+ verification=TaskVerificationContract(
+ mode="audit",
+ goal="move the arm to the target",
+ success_criteria=["the arm reached the target"],
+ ),
+ )
+
+ with pytest.raises(ForgeToolAPIError):
+ await coordinator.start_action(
+ task.task_id, "motion.move_pose", {"distance_m": 0.05}
+ )
+ response = await coordinator.start_action(
+ task.task_id, "motion.move_pose", {"distance_m": 0.05}
+ )
+ coordinator.observe_action(
+ task.task_id,
+ response["data"]["invocation_id"],
+ {"phase": "completed"},
+ )
+
+ finalized = await coordinator.finalize_task(task.task_id)
+
+ assert finalized.status.value == "succeeded"
diff --git a/tests/test_node_installer_directory.py b/tests/test_node_installer_directory.py
index a25437ab5..8029565c7 100644
--- a/tests/test_node_installer_directory.py
+++ b/tests/test_node_installer_directory.py
@@ -161,10 +161,14 @@ def test_directory_receipt_pins_nested_binary_sha256(tmp_path: Path) -> None:
)
receipt = yaml.safe_load(receipt_text)
assert receipt["binary_sha256"] == hashlib.sha256(b"#!/bin/sh\nexit 0\n").hexdigest()
- # Tampering with the executable must fail the load-time verification.
+ # A locally modified executable only warns on the runtime start path; the
+ # strict entry points (forge-node verify, install cache acceptance) reject it.
entrypoint = _version_dir(installer, lock) / "lerobot_infer" / "lerobot_infer"
entrypoint.write_bytes(b"tampered")
+ assert installer.load(lock).is_file()
assert not installer.satisfies(lock)
+ with pytest.raises(InstallerError):
+ installer.load(lock, strict=True)
# ---------------------------------------------------------------------------
diff --git a/tests/test_opper_provider.py b/tests/test_opper_provider.py
new file mode 100644
index 000000000..13bd6957a
--- /dev/null
+++ b/tests/test_opper_provider.py
@@ -0,0 +1,77 @@
+"""Opper gateway selection and OpenAI-compatible request routing."""
+
+from __future__ import annotations
+
+from unittest.mock import AsyncMock
+
+import litellm
+import pytest
+
+from PhyAgentOS.config.schema import Config
+from PhyAgentOS.providers.litellm_provider import LiteLLMProvider
+from PhyAgentOS.providers.registry import find_by_name, find_gateway
+from PhyAgentOS.providers.service import ProviderService
+
+
+@pytest.mark.parametrize("provider_name", ["opper", "auto"])
+def test_config_selects_gateway_when_only_gateway_is_configured(provider_name: str) -> None:
+ config = Config.model_validate(
+ {
+ "agents": {"defaults": {"model": "claude-sonnet-4-6", "provider": provider_name}},
+ "providers": {"opper": {"apiKey": "test-opper-key"}},
+ }
+ )
+ assert config.get_provider_name() == "opper"
+ assert config.get_api_key() == "test-opper-key"
+ assert config.get_api_base() == "https://api.opper.ai/v3/compat"
+ assert find_gateway(api_base=config.get_api_base()) is find_by_name("opper")
+
+
+@pytest.mark.parametrize(
+ ("provider_name", "expected_provider"), [("auto", "anthropic"), ("opper", "opper")]
+)
+def test_config_respects_provider_selection_with_native_credentials(
+ provider_name: str, expected_provider: str
+) -> None:
+ config = Config.model_validate(
+ {
+ "agents": {"defaults": {"model": "claude-sonnet-4-6", "provider": provider_name}},
+ "providers": {
+ "anthropic": {"apiKey": "test-anthropic-key"},
+ "opper": {"apiKey": "test-opper-key"},
+ },
+ }
+ )
+ assert config.get_provider_name() == expected_provider
+ assert config.get_api_key() == getattr(config.providers, expected_provider).api_key
+
+
+def test_runtime_reads_provider_key_without_persisting_it(monkeypatch: pytest.MonkeyPatch) -> None:
+ monkeypatch.setenv("OPPER_API_KEY", "test-opper-key")
+ monkeypatch.delenv("PAOS_OPPER_API_KEY", raising=False)
+ config = Config()
+ service = ProviderService(config)
+ assert service.config.providers.opper.api_key == "test-opper-key"
+ assert config.providers.opper.api_key == ""
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize(
+ "model", ["claude-sonnet-4-6", "anthropic/claude-sonnet-4-6", "opper/gpt-5.4-mini"]
+)
+async def test_request_uses_gateway_and_preserves_model_id(
+ model: str, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ completion = AsyncMock(
+ return_value=litellm.ModelResponse(
+ choices=[{"message": {"role": "assistant", "content": "ok"}}]
+ )
+ )
+ monkeypatch.setattr("PhyAgentOS.providers.litellm_provider.acompletion", completion)
+ provider = LiteLLMProvider(api_key="test-opper-key", provider_name="opper")
+ response = await provider.chat(messages=[{"role": "user", "content": "hello"}], model=model)
+ assert response.content == "ok"
+ kwargs = completion.call_args.kwargs
+ assert kwargs["model"] == f"custom_openai/{model.removeprefix('opper/')}"
+ assert kwargs["api_key"] == "test-opper-key"
+ assert kwargs["api_base"] == "https://api.opper.ai/v3/compat"