Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
947a56a
feat(providers): add Opper gateway
Felixkw12 Oct 8, 2026
2a6d647
Merge pull request #130 from Felixkw12/feat/opper-provider
sxshco Oct 15, 2026
0265736
fix: warn instead of blocking on locally modified Skill files
mrgh97 Oct 19, 2026
3677e31
fix: address review - strict verify path, frozen workflow document hash
mrgh97 Oct 19, 2026
55d3cbf
fix: freeze activated workflow hash, strict install cache acceptance
mrgh97 Oct 19, 2026
99314a4
Merge pull request #135 from mrgh97/fix/warn-instead-of-block-on-skil…
mrgh97 Oct 19, 2026
5e3c0ec
Merge main into dev
mrgh97 Oct 19, 2026
6abb0a5
fix(forge): record pre-dispatch Action rejections as failed, not unknown
mrgh97 Oct 20, 2026
bdc7303
fix(forge): exclude pre-dispatch rejections from task finalization
mrgh97 Oct 20, 2026
a6d3fc3
Merge pull request #136 from PhyAgentOS/fix/pre-dispatch-rejection-st…
mrgh97 Oct 21, 2026
3f06fae
Merge main into dev
mrgh97 Oct 21, 2026
6b1cdd5
docs: add bilingual TrackB guide and Piper X development demo
Oct 22, 2026
a55a31e
docs: add contribution guide focused on TrackB development
Oct 23, 2026
52b32ad
docs: clarify external contributions await approval service
Oct 23, 2026
8d9dace
Merge pull request #138 from PhyAgentOS/codex/track-b-developer-guide…
mrgh97 Oct 23, 2026
87caf05
Merge pull request #139 from mrgh97/codex/track-b-contributing
mrgh97 Oct 23, 2026
3b0e2ca
docs: consolidate developer guides and bilingual navigation
Oct 23, 2026
91fa641
docs: replace README benchmarks with robot-control-sim quickstart
Oct 23, 2026
8e369d1
Merge pull request #140 from mrgh97/codex/docs-consolidation
mrgh97 Oct 23, 2026
f22faa9
docs: retain benchmark documentation navigation
Oct 23, 2026
ce34242
Merge pull request #141 from mrgh97/codex/benchmark-doc-links
mrgh97 Oct 23, 2026
2aecf2a
docs: add live simulation GIFs and highlight Piper X demo
Oct 23, 2026
8f50cca
Merge pull request #142 from mrgh97/codex/quickstart-live-gifs
mrgh97 Oct 23, 2026
9fbcc4d
chore(release): prepare v1.1.1 metadata, changelog and documentation
sxshco Oct 23, 2026
c59f476
Merge pull request #143 from PhyAgentOS/dev
sxshco Oct 23, 2026
cbc1c7e
ci: publish verified GitHub releases to PyPI
sxshco Oct 27, 2026
5ea7313
Merge pull request #146 from PhyAgentOS/codex/automate-pypi-release
sxshco Oct 27, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
133 changes: 133 additions & 0 deletions .github/workflows/publish-pypi.yml
Original file line number Diff line number Diff line change
@@ -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"
2 changes: 1 addition & 1 deletion .github/workflows/release-build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ on:
tag:
description: Tag to build
required: true
default: v1.0.0
default: v1.1.1
type: string
push:
tags:
Expand Down
33 changes: 33 additions & 0 deletions .github/workflows/release-checks.yml
Original file line number Diff line number Diff line change
@@ -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
40 changes: 40 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
79 changes: 79 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -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).
69 changes: 69 additions & 0 deletions CONTRIBUTING_zh.md
Original file line number Diff line number Diff line change
@@ -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)。
2 changes: 1 addition & 1 deletion Dockerfile
Original file line number Diff line number Diff line change
@@ -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
Expand Down
2 changes: 1 addition & 1 deletion PhyAgentOS/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,5 +2,5 @@
PhyAgentOS - A lightweight AI agent framework
"""

__version__ = "1.1.0"
__version__ = "1.1.1"
__logo__ = "🍞"
Loading