一句话看懂 数据流
用户指令 → Agent 的规划 → 写进文件 → Watchdog 读取 → 驱动执行 → 状态再写回文件。而框架运行的整个生命周期都围绕着协议中指定的Markdown文件，它们是框架运行的核心。
%%{init: {
'theme': 'base',
'themeVariables':
{
'primaryColor': '#fffaf3',
'primaryTextColor': '#1d2a30',
'primaryBorderColor': '#20323a',
'lineColor': '#66757d',
'secondaryColor': '#f5efe6',
'tertiaryColor': '#ffffff',
'fontFamily': 'Inter, system-ui, sans-serif',
'fontSize': '15px',
'textColor': '#1d2a30',
'nodeBkg': '#fffaf3',
'nodeBorder': '#20323a',
'nodeTextColor': '#1d2a30',
'clusterBkg': '#f5efe6',
'clusterBorder': '#20323a',
'titleColor': '#1d2a30',
'edgeLabelBackground': '#ffffff',
'edgeLabelColor': '#66757d',
'arrowheadColor': '#66757d'
}
}
}%%
flowchart LR
classDef cognitive fill:#dff0e6,stroke:#5f9e77,stroke-width:2px,color:#2d5a3f
classDef safety fill:#f8e5b7,stroke:#cc951e,stroke-width:2px,color:#7a5a0a
classDef protocol fill:#f6d0c3,stroke:#ca6a49,stroke-width:2px,color:#7a3a28
classDef execute fill:#dbe8f7,stroke:#4b7eb4,stroke-width:2px,color:#2a4a6a
classDef file fill:#ffffff,stroke:#66757d,stroke-width:1.5px,color:#1d2a30
subgraph A["🧠 认知层"]
USER([用户输入]):::cognitive
AGENT[AgentLoop ']:::cognitive
TOOL[具身工具]:::cognitive
end
subgraph B["🛡️ 校验层"]
CRITIC{Critic}:::safety
end
subgraph C["📄 协议层"]
EMBODIED([EMBODIED.md ']):::file
ACTION([ACTION.md]):::protocol
ENV([ENVIRONMENT.md ']):::file
end
subgraph D["🔧 执行层"]
WATCH[Watchdog ']:::execute
DRIVER[Driver]:::execute
ROBOT([机器人]):::execute
end
USER --> AGENT --> TOOL --> CRITIC
EMBODIED -.-> CRITIC
CRITIC -->|通过| ACTION
CRITIC -.->|拒绝| ENV
ACTION --> WATCH --> DRIVER --> ROBOT
ROBOT -.->|更新| ENV
六个步骤：从一句话到机器人动作
下面按真实执行顺序拆开。如果你调试时卡住了，就对照这六步定位：问题出在理解层？校验层？还是执行层没回写状态？
1. 用户指令
→
2. Agent 包装上下文
→
3. 决定要做什么动作
→
4. Critic 检验
→
5. 写成 ACTION.md
→
6. Watchdog 执行
步骤 1~3：认知层
用户通过 CLI 或网关发任务，AgentLoop 把会话历史、工作区状态拼成提示词，让 LLM 决定调用哪个工具。涉及物理世界时，通常命中 execute_robot_action 或 target_navigation。
步骤 4：Critic 校验
Critic 会扒开 EMBODIED.md 和 ENVIRONMENT.md，看看这个动作是否合法、可达。不合法就直接拒掉，把原因写进 LESSONS.md。
步骤 5：落盘
校验通过后，动作不会直接 RPC 到硬件，而是被格式化成 JSON，写进 ACTION.md。这个动作队列就是认知层留给执行层的唯一接口。
步骤 6：执行与回写
HAL Watchdog 轮询 ACTION.md，发现有 pending 动作就交给 Driver。执行完后，Driver 把最新环境状态回写到 ENVIRONMENT.md，完成闭环。
动态协同与认知状态空间
PhyAgentOS 在运行时维护一组结构化的文本文件，用于表征全局状态。
Agent 仅对这些降维后的符号表示进行处理，避免了多模态底层特征的直接干扰。
不同进程之间不直接调函数，而是读同一份 Markdown。
这让整个系统变得清晰可观察，你随时能打开文件看当前状态。
%%{init: {
'theme': 'default',
'themeVariables': {
'primaryColor': '#fffaf3',
'primaryTextColor': '#1d2a30',
'primaryBorderColor': '#20323a',
'lineColor': '#66757d',
'secondaryColor': '#f5efe6',
'tertiaryColor': '#ffffff',
'fontFamily': 'Inter, system-ui, sans-serif',
'textColor': '#1d2a30',
'nodeBkg': '#ffffff',
'nodeBorder': '#20323a',
'nodeTextColor': '#1d2a30',
'clusterBkg': '#f5efe6',
'clusterBorder': '#20323a',
'titleColor': '#1d2a30',
'edgeLabelBackground': '#ffffff',
'edgeLabelColor': '#66757d',
'arrowheadColor': '#66757d'
},
'flowchart': {
'htmlLabels': true,
'curve': 'basis',
'padding': 20,
'nodeSpacing': 50,
'rankSpacing': 100, // 关键：大幅增加层间距，防止标题被上层节点遮挡
'useMaxWidth': false
}
}%%
flowchart TB
classDef sharedFile fill:#f6d0c3,stroke:#ca6a49,stroke-width:2.5px,color:#7a3a28,font-weight:500
classDef robotFile fill:#dff0e6,stroke:#5f9e77,stroke-width:2.5px,color:#2d5a3f,font-weight:500
classDef agentRole fill:#dbe8f7,stroke:#4b7eb4,stroke-width:2px,color:#2a4a6a
classDef criticRole fill:#f8e5b7,stroke:#cc951e,stroke-width:2px,color:#7a5a0a
classDef watchdogRole fill:#ece3f6,stroke:#7f62ac,stroke-width:2px,color:#5a3d7a
%% 上层控制节点（去掉了单引号，用 padding 撑开宽度）
AG([Agent]):::agentRole
CR([Critic]):::criticRole
WD([Watchdog]):::watchdogRole
%% 下层工作区：改为 LR 横向排列，线从侧面走
subgraph SHARED["📁 Shared Workspace"]
direction LR
E([ENVIRONMENT.md]):::sharedFile
R([ROBOTS.md]):::sharedFile
L([LESSONS.md ]):::sharedFile
T([TASK.md ]):::sharedFile
end
subgraph ROBOT["🤖 Robot Workspace"]
direction LR
A([ACTION.md]):::robotFile
M([EMBODIED.md]):::robotFile
end
%% 连线
AG -."读取环境".->E
AG -."读取任务".->T
AG ==>|"写入动作"| A
CR -."读取约束".->M
CR -."读取状态".->E
WD -."轮询动作".->A
WD ==>|"更新环境"| E
WD -."安装配置".->M
| 文件 | 一句话解释 | 谁写 | 谁读 |
|---|
ENVIRONMENT.md | 当前环境真相源：场景图、机器人位姿、导航状态 | Watchdog / 感知 | Agent / Critic |
EMBODIED.md | 这台机器人能干什么、不能干什么 | Watchdog 从 profile 安装 | Critic / Agent |
ACTION.md | 发给机器人的动作队列 | EmbodiedActionTool | HAL Watchdog |
LESSONS.md | 失败经验，避免重复踩坑 | Critic 拒绝逻辑 | Agent / 你 |
ROBOTS.md | 多机器人索引，能力摘要 | EmbodimentRegistry | Planner / 运维 |
三层结构
在 PhyAgent 框架中，认知层（云端大模型）与物理执行层（硬件本体）被严格物理隔离。
这种隔离不仅体现在代码结构上，更体现在运行时的进程边界上。
连接这两个异构世界的唯一桥梁，是基于文件系统的状态协议空间（Workspace API）以及负责轮询该空间的硬件看门狗守护进程 (HAL Watchdog Daemon)。
认知层
PhyAgentOS/agent、providers、cli
负责理解任务、规划动作、调用工具、做安全判断。不碰具体机器人 SDK。
协议层
workspace / workspaces
用 Markdown 承载共享状态，让 Agent、Watchdog、Critic 都能读同一份上下文。
执行层
hal/、drivers、navigation、perception
负责连接硬件、执行动作、刷新环境。不做高层规划。
Single 与 Fleet：最简模式与进阶模式
Single
最简模式下，系统只负责一台机器人和一个工作区。此外，本地运行仿真环境也属于这个模式。
Fleet
多台机器人共享一个 ENVIRONMENT.md，但各自有独立的 ACTION.md 和 EMBODIED.md。
Runtime 会话循环
除了单动作的 ACTION.md 循环之外，PhyAgentOS 现在拥有了以会话为中心的运行时。它读取 SESSIONS.md，按优先级选择待处理的会话，执行 preflight 健康检查，通过 skill runtime 对 rollout target 执行操作，并写回结果。串行 WatchdogSupervisor 按 high → normal → low 优先级调度。
%%{init: {
'theme': 'base',
'themeVariables':
{
'primaryColor': '#fffaf3',
'primaryTextColor': '#1d2a30',
'primaryBorderColor': '#20323a',
'lineColor': '#66757d',
'secondaryColor': '#f5efe6',
'tertiaryColor': '#ffffff',
'fontFamily': 'Inter, system-ui, sans-serif',
'fontSize': '14px',
'textColor': '#1d2a30',
'nodeBkg': '#fffaf3',
'nodeBorder': '#20323a',
'nodeTextColor': '#1d2a30',
'clusterBkg': '#f5efe6',
'clusterBorder': '#20323a',
'titleColor': '#1d2a30',
'edgeLabelBackground': '#ffffff',
'edgeLabelColor': '#66757d',
'arrowheadColor': '#66757d'
}
}
}%%
flowchart LR
classDef file fill:#f6d0c3,stroke:#ca6a49,stroke-width:2px,color:#7a3a28
classDef runtime fill:#ece3f6,stroke:#7f62ac,stroke-width:2px,color:#5a3d7a
classDef target fill:#dbe8f7,stroke:#4b7eb4,stroke-width:2px,color:#2a4a6a
classDef output fill:#dff0e6,stroke:#5f9e77,stroke-width:2px,color:#2d5a3f
S([SESSIONS.md]):::file
T([TARGETS.md]):::file
K([SKILLS.md]):::file
SUP[WatchdogSupervisor]:::runtime
PF{Preflight}:::runtime
SK[SkillRuntime]:::runtime
TGT[RolloutTarget]:::target
PC[PolicyClient]:::target
ART([episode.json]):::output
ENV([ENVIRONMENT.md]):::output
S --> SUP
T --> SUP
K --> SUP
SUP --> PF
PF -->|通过| SK
PF -.->|拒绝| S
SK --> TGT
SK --> PC
TGT --> ART
SK -.->|感知| ENV
SESSIONS.md
会话队列，包含 target/skill 路由、优先级、超时和重试策略。在 runtime 路径中替代 ACTION.md。
WatchdogSupervisor
组件化串行监督器：选择待处理会话，运行 preflight，编排 skill runtime，写回重试/失败状态。
Artifacts
Episode 摘要、感知输出和环境状态写入 artifacts/runtime/ 和 ENVIRONMENT.md。
为什么要用 Markdown 做协议？
这可以构建层次化的提示，并且可以渐进式披露与大模型。这样可以极高地增加了系统的灵活性与节省token调度。同样的，这种方式也可以给层次化管理相关信息，以便于人类调式与理解。
- 人类可读：出问题先 cat 文件，不用attach debugger。
- 模型可读：Markdown 天然适合放进 LLM 上下文。
- 进程间松耦合：Agent 和 Watchdog 不需要 RPC，只要约定文件格式。