版本 / Version: 1.0.0
实现基线 / Implementation baseline: Forge Skill binding, Query/Action/Session Tool API, AgentTask recovery, and version-scoped experience, 2026-08-30
本目录由 PhyAgentOS 开发团队面向用户、运维人员和生态开发者维护。文档只把仓库源码、配置 Schema 与测试实际覆盖的行为称为“当前能力”。plan/ 中的设计报告是历史背景，不替代这里的运行契约。
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.
- 框架介绍：项目定位、控制面边界、执行—证据—判定分离、生命周期与实现范围。
- 用户手册：安装、Provider/Forge 配置、任务描述、验证模式、Artifact 与排障。
- 开发者手册：AgentTask、Tool API client、Skill Runtime、Evidence、Verifier、Recovery 与测试。
- Forge 配置参考：Forge Tool API、Resource Registry、Evidence、Verification、AgentTask 和 Embodiment 字段。
- Agent 经验与 Skill 自进化：Skill 激活与归因、Episode、Lesson 聚类、Skill 晋升、持久化和安全门控。
- 运行手册：上线前检查、启动顺序、状态观测、取消、重启恢复、备份与故障分层。
- Docker 部署指南：基于 Docker 的快速部署，配合一键脚本完成构建、初始化与运行（仅外连网关，无入站端口）。
- 集成开发指南：Tool/Node/Skill 接入、Bundle 打包与不可变发布、本地闭环、证据源、Provider 和 PAOS 扩展边界。
- 通信架构：Agent 消息、Forge HTTP/WebSocket、system event、SQLite 与 Artifact 边界。
- Forge Tool API 接入契约：Query/Action/Session、不可变 Skill binding、ToolInvocation、AgentTask、证据、验证、恢复和 Skill Runtime 契约。
| 目标 | 建议路径 |
|---|---|
| 先理解项目为何区分执行与任务成功 | 框架介绍 → Forge 接入契约 |
| 首次部署并跑通 Agent + Forge | 用户手册 → 配置参考 |
| 负责长期在线和故障处理 | 运行手册 → 通信架构 |
| 用 Docker 快速部署 | Docker 部署指南 |
| 在 Gateway 增加新机器人动作 | 集成开发指南 → 开发者手册 |
| 开发、打包并发布 Forge Skill | 集成开发指南 → Forge 接入契约 |
| 修改证据、验证、恢复或持久化 | 开发者手册 → Forge 接入契约 |
| 使用或扩展任务经验、Lesson 与 Skill 自进化 | Agent 经验与 Skill 自进化 → 开发者手册 |
- Framework Introduction: positioning, control-plane boundaries, execution/evidence/verdict separation, lifecycle, and implemented scope.
- User Manual: installation, provider and Forge configuration, task description, verification modes, artifacts, and troubleshooting.
- Developer Manual: AgentTask, Tool API client, Skill Runtime, evidence, verifier, recovery, and testing.
- Forge Configuration Reference: exact Forge Tool API, Resource Registry, evidence, verification, AgentTask, and embodiment fields.
- Agent Experience and Skill Evolution: Skill activation and attribution, episodes, Lesson clustering, Skill promotion, persistence, and guardrails.
- Operations Manual: preflight checklist, startup order, observation, cancellation, restart recovery, backup, and failure layers.
- Docker Deployment Guide: Docker-based quick deployment with a one-click script for build, init, and run (outbound-only gateway, no inbound port).
- Integration Development Guide: Tool, Node, and Skill integration; Bundle packaging and immutable publication; the local loop; evidence sources; providers; and PAOS extension boundaries.
- Communication Architecture: Agent messages, Forge HTTP/WebSocket, system events, SQLite, and artifact boundaries.
- Forge Tool API Integration Contract: Query/Action/Session, immutable Skill binding, ToolInvocation, AgentTask, evidence, verification, recovery, and Skill Runtime contracts.
| Goal | Suggested path |
|---|---|
| Understand why execution and task success differ | Framework Introduction → Forge Integration Contract |
| Deploy Agent + Forge for the first time | User Manual → Configuration Reference |
| Operate a long-running service | Operations Manual → Communication Architecture |
| Deploy quickly with Docker | Docker Deployment Guide |
| Add a new robot action in Gateway | Integration Guide → Developer Manual |
| Develop, package, and publish a Forge Skill | Integration Guide → Forge Integration Contract |
| Change evidence, verification, recovery, or persistence | Developer Manual → Forge Integration Contract |
| Use or extend task experience, Lessons, or Skill evolution | Agent Experience and Skill Evolution → Developer Manual |
| 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. |
PAOS supports Forge Query, Action, and Session through /tools and /invocations. The Agent-side aggregate
is AgentTask, while physical execution remains owned by Gateway ToolInvocation and ToolEndpoint.
Skill Runtime manages manifest-v2 bundles and named Dora profiles; it is distinct from the removed
Markdown queue Runtime. Existing evolution, experience, verification, and Agent workspace data are
read in place. Registry downloads are explicit and digest-verified.