mcpField
P
puda

puda

github.com/pudap其他1103 次安装3 天前更新
代码仓库

关于 puda

PUDA 是面向 Physical AI、兼容不同硬件和大模型的运行时，通过统一控制平面连接 Agent 规划与实体机器执行。其架构采用 NATS 消息机制、命令行优先界面、声明式协议、边缘服务及保留溯源信息的项目记录。

主要功能

  1. 01兼容不同硬件和大模型的运行时
  2. 02基于 NATS 的消息驱动架构
  3. 03供 Agent 和人工使用的命令行
  4. 04声明式实验与工作流协议
  5. 05将命令转换为原生机器驱动调用的边缘服务
  6. 06保留命令溯源信息的项目记录

适用场景

  1. 01连接 Agent 规划与机器执行
  2. 02通过声明式协议运行实验
  3. 03检查可响应的机器和遥测信息
  4. 04保留命令与数据的溯源记录

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/pudap/skills --skill puda

安装后在 Claude Code 中输入/puda确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
chrony.md
cli-profiles-and-telemetry.md
livestream.md
scripts/
sync-clock.ps1
sync-clock.sh

详细介绍

PUDA 上下文

PUDA（Physical Unified Device Architecture，物理统一设备架构）是一种与硬件和大模型无关的 Physical AI 运行时。它通过将高层 Agent 逻辑与底层机器执行分离，为 AI Agent 和软件系统提供统一、可验证的物理机器控制平面。

概括来说，PUDA 采用以 NATS 为核心的消息驱动架构，为 Agent 和人类提供 CLI 优先的界面，使用声明式协议执行实验或工作流，通过边缘服务将命令转换为原生机器驱动调用，并通过项目记录保留命令和数据的溯源信息。可以将 PUDA 视为连接规划、机器控制、执行日志和生成报告的 Agent 原生桥梁。

有关 PUDA、设置或其他问题的更多信息，请参阅 https://docs.puda.co/llms.txt。

设置 puda

  1. 安装 CLI：确保已安装 puda，且它位于 PATH 中，以便全局调用。如果尚未安装，请从 Puda releases page 下载适用于你平台的二进制文件，安装后将其添加到 PATH。
  2. 确保依赖项齐全：确保 python3、pip 和 npx 均可用；如果缺少，请先安装。
  3. 登录：如果尚不知道用户的用户名，请向用户询问——不要自行假设。使用 puda login -u <username> 登录。
  4. 选择 NATS 配置：查看 puda profile list 和 puda profile current。使用 puda profile switch <name> 切换到已有的目标配置。若要新建配置，请从用户或部署配置中获取名称和代理 URL；不要自行假设实验室。明文连接：puda profile add <name> --servers <nats-urls>。加密连接：puda profile add <name> --servers <tls-urls> --ca <local-ca-path> --key <local-key-path>。加密 CLI 配置必须同时提供这两个文件。如果尚未选择配置，系统会自动激活第一个配置；否则，请明确切换到目标配置。配置或迁移连接时，请阅读 CLI 配置和遥测。
  5. 安装技能：运行 puda skills install，为 puda 安装 Agent 技能。

设置项目

运行 puda init（例如 puda init . 或 puda init <folder_name>）。

只有在完成 puda 设置并初始化项目后，才能继续生成协议、执行机器命令或运行实验工作流。

CLI 0.1.x 配置和机器检查

使用 puda --version 和命令 --help 检查已安装的界面。此技能适用于 CLI 0.1.3；Python SDK 的版本单独管理（0.0.21）。

  • puda config list/get/set 仅管理 user.user_id 和 user.username。代理 URL 和安全路径属于 puda profile；项目设置属于 puda project config。不要使用已移除的 puda config set nats_servers 工作流。
  • puda machine list 用于发现有响应的机器。puda machine info <id>（别名 ping）会返回实时状态、SDK 版本、已注册的实时视频流和公布的遥测流。请读取 results[].tlm_streams[].subject；不要根据机器名称猜测流是否存在。
  • puda machine watch <full-subject> --timeout 15 用于观察实时流量。请使用已公布的主题，例如 puda.first.tlm.stream.pos。位置参数是主题，而非机器 ID。若要监视指定机器的所有主题，请使用 --machines first,balance，而不要传入主题。
  • 配置和机器检查的输出默认为 JSON；watch 输出为 NDJSON。只有在需要文本时才使用 --human。检查时优先使用有时限的 watch；只有在用户要求时才使用持续 watch。这些只读命令不需要初始化项目或启动机器运行。

有关配置迁移、可编辑配置字段、机器信息输出、watch 通配符、心跳筛选和主题示例，请阅读 CLI 配置和遥测。

项目文件夹结构

.
├── project.md                        # single source of truth (puda-memory skill)
├── protocols/                        # generated protocol files (puda-protocol skill)
├── puda.config                       # puda config file
└── puda.db                           # puda database file

时钟同步（Chrony / NTP）

PUDA 时间戳、发现租约和实验溯源都依赖主机时钟。设置站点或边缘主机时，或者涉及时钟、Chrony 或 NTP 时，请阅读 references/chrony.md。在边缘主机上，请向用户询问站点 NTP 服务器的 IP，并运行 scripts/sync-clock.sh 或 scripts/sync-clock.ps1。不要假设 IP。不要在边缘容器内运行 Chrony。

直播（USB / IP 摄像头）

如果机器主机连接了 USB 摄像头、网络摄像头或 IP 摄像头，并且操作人员需要实时视频，请阅读 references/livestream.md。使用 PUDAP/livestream。

请向用户询问摄像头（USB /dev/video* 路径或网络 rtsp:// URL）、直播名称、简短描述、MediaMTX 主机（MagicDNS、Tailscale IP，或没有 Tailscale 时的机器 IP），以及应该使用此视频源的机器 ID（一个或多个）。不要假设其中任何一项。然后启动 Docker 堆栈，并使用 puda livestream add --name --host --description --machines 注册。直播是整个设备群的记录，而不是边缘配置。

更新 puda 技能

刷新或更新 puda 技能：

puda skills update

评论

支持 Markdown