• 具身智能
• 人工智能
• AI Agent
• 机器人
• 计算机视觉
• Agent 编排

JiuwenSymbiosis 是一个构建在openjiuwen之上的具身智能体框架，核心目标是用一套安全、可审计的 Agent 工作流适配不同机器人本体。本文以仓库中文入口 README.zh.md 为骨架，完整介绍其核心特性、架构闭环、安装配置、内置适配器与真机 Quick Start，并结合源码（动作词表、能力词表、执行器、技能库与真实配置文件）给出可验证的实现细节。读完本文，你将理解"构型无关"的动作契约机制如何在规划器与硬件之间解耦、fastagent两级规划与运行时重规划如何工作，以及如何用一条命令把 SO-101、Cruzr 等不同机器人跑起来。

一、核心特性：从"写死调用序列"到"动态编排"

README 将 JiuwenSymbiosis 的核心竞争力概括为十三个特性，下面结合源码逐一展开。

1.1 构型无关：ActionSpec + Capability 门控

共享动作契约ActionSpec与 Capability（能力）门控是整套框架的基石。一句话概括：一个动作 = 一份与本体无关的契约 + N 个本体实现。

• 动作契约ActionSpec定义在 jiuwensymbiosis/api/decorators.py，包含name、capability、params、result、requires/provides/invalidates（机器人自状态）、produces_location/consumes_location/invalidates_locations（位置有效性）等字段；30 个共享动作实例集中声明在 jiuwensymbiosis/api/actions.py。
• 适配器方法通过@implements(SPEC)绑定契约，运行时方法上附加ToolMeta，工具构建器读取这些元数据生成工具；调用的是绑定后的方法，不会重新执行装饰器。
• 能力词表KNOWN_CAPABILITIES定义在 jiuwensymbiosis/env/base.py，覆盖运动（motion.cartesian/joint/servo/base/lift/waist/goal/dual_arm）、末端（grasp.parallel/suction/paddle）、视觉（vision.camera/depth/detection/eye_to_hand/search）与规划（planning.reachability）等轴。

@implements在导入时就会校验实现方法的签名能否接受契约承诺的全部参数，契约与实现一旦漂移会直接抛ContractViolation，"一个契约有两个作者就会漂移"的问题被从根上消除。

1.2 任务组合：规划器把"目标"组织成动作序列

任务不是写死的调用序列，而是由动作契约和技能动态组合出来的。fastagent路径下 jiuwensymbiosis/agent/run.py 的run_fast_task依次完成：

1. 任务解析（LLM①，尽力而为，失败则 scene-blind 编译）；
2. 场景感知（无 LLM，复用检测器，analyze_scene汇总目标与参照物）；
3. 编译规划（LLM②，技能组合 Tier 1 + 动作组合 Tier 2）；
4. 序列校验（parse_sequence）后交给run_sequence顺序执行。

1.3 环境 + 本体感知的动态编排：冲突即重规划

规划器以当前本体状态与环境感知结果为输入，动态编排动作契约与技能；执行过程中一旦现实状态与下一步骤的前提条件冲突，就自动触发重规划，而非照本宣科。见 jiuwensymbiosis/agent/run.py 的replan回调：重新感知场景、重新规划剩余动作，受execution.fastagent.max_replans上限约束。未报告的状态视为未知、不据此判定冲突。

1.4 执行记忆：感知即入账、移动即作废

BaseRobotApi.memory持有ExecutionMemory。经动作工具分派的成功调用按契约记账：产生的位置按目标记录时间戳、声明失效的位置被清除（同时清除感知缓存）。"感知即入账、移动即作废"无需手写缓存；已执行动作的状态沉淀下来供后续步骤继承引用。直接调用 API/Env 的代码不会自动走这条记账路径。

1.5 实时追踪伺服：边感知边执行

fastagent支持TRACK_DETECT/TRACK_GRASP追踪复合步骤，检测与控制分开运行：

• BackgroundTracker：后台线程持续检测，保存最近目标与时间，staleness_s过期过滤；
• ServoController：按control_hz（配置默认 30 Hz，真机配置如 SO-101 为 20 Hz）读取当前位姿与目标，限制每步位姿变化量后发非阻塞命令；
• ServoBinding：每个下发位姿先经SafetyRail.validate_pose再调用api.servo_to_tip或env.servo_to_flange，要求 Env 声明motion.servo。

目标丢失超过lost_target_grace_s时控制器终止追踪。详见 docs/zh/explanation/architecture.md 的"实时追踪伺服"一节。

1.6 主动搜索与可达性推理

• 目标不在视野时原地扫视、报方位（search_target返回bearing_rad，不移动本体、不声明三维位置），并逐步逼近（approach_for_grasp/approach_for_place承担扫视寻靶与重新测量）。
• 规划器使用"在抽屉里""在箱子下"等空间关系（on/under/in/beside/near）约束目标选择，并结合本体提供的可达性判据（planning.reachability，由 URDF + 臂链派生）规划动作。序列校验器将声明payload.held效果的抓取动作视为清除被抓取的障碍；开门等专用操作需要对应动作声明opens_access——当前内置动作尚未声明该效果，README 对此有明确说明。

1.7 动作契约：声明前置条件、效果与结果形状

ActionSpec不编码顺序，只拒绝前置条件不满足的排列。契约字段见下表（源码位置：jiuwensymbiosis/api/decorators.py）：

1.8 安全闭环

运动边界检查、异常恢复、视觉反馈、执行诊断共同保护物理执行。Rails 在工具调用、异常和模型调用等事件处工作：

软件边界检查不替代设备急停与硬件保护——这是 README 强调的边界。

1.9 通用视觉感知

开箱即用的可复用感知管线：取帧、深度、开放词汇检测与分割（GroundingDINO + SAM2）、质心与深度估计、像素到基座反投影、标定、坐标变换与校正。eye-in-hand 与 eye-to-hand 只差一个投影函数——Piper 用T_base_flange(live) @ T_flange_cam，SO-101 用固定T_base_cam，Cruzr 优先实时 TF 查找、静态标定回退。检测服务统一走detector.mode：remote（外部 HTTP 服务）/local（Session 托管子进程）/disabled（默认）。

1.10 技能工作流与可审计执行

内置visual_pick、visual_place、transport三个技能（SKILL.md 位于 jiuwensymbiosis/skills/），规范抓取、放置与移动的常见流程。执行轨迹结构化落盘：工具动作名、参数、结果摘要、成功/错误、耗时、观测快照与可选 JPEG 帧，任务结束写入<workspace>/traces/{run_token}.json，可用jiuwensymbiosis-replay生成自包含 HTML 回放。

二、架构设计：感知 → 规划 → 执行 → 观测 → 反馈闭环

运行时形成"感知 → 规划 → 执行 → 观测 → 反馈"闭环：命令依次经过 Agent、Rails、Tools、API、Env 和 Hardware，观测、失败与轨迹证据反向反馈给 Agent。各层职责与输入输出（详见 docs/zh/explanation/architecture.md）：

perception/和motion/提供可复用算法；kinematics/提供 URDF、FK/IK 等模型计算，与相机检测、实时观测职责不同。

2.1 两种编排方式：fastagent 与 stepagent

调用者先with session:建立连接，再调用run_robot_task(session, query, config)：

• fastagent（默认）：plan_task一次性生成动作序列，run_sequence通过能力执行器调用robot_control顺序执行，不调用agent.invoke()、不为每个普通步骤调用 LLM；初始规划、修正重试与重新规划仍可能调用模型。
• stepagent：构建 Agent 后调用agent.invoke()，由模型根据工具结果逐步选择后续调用，用于单步调试/验证。--mock会隐含强制 stepagent。

两级规划（fastagent）具体为：Tier 1 技能组合（compile_sequence，对能力过滤后的技能选择并展开为平坦动作序列）→Tier 2 动作组合（compose_actions，无可用技能 / Tier 1 显式空序列 / 修正重试后仍无效时接管）→序列校验（parse_sequence，两级共用校验器）。任务解析、规划重试与运行时重规划可能带来额外模型调用，编译阶段的一次请求不等于整个任务只调用一次模型。

2.2 工具层：三种工具策略可共存

agent/builder.py根据execution.stepagent.mode构建工具，再按modules.skills.enabled添加技能入口：

RobotControlTool通过action/params分派动作，SafetyRail先读这两个字段再检查，因此独立动作工具与统一入口共用同一套运动检查。注意execution.stepagent.mode决定逐步工具配置，execution.mode决定任务由模型逐步编排还是先编译序列，二者含义不同。

三、环境要求

README 明确给出了当前验证过的运行环境：

四、安装指南

git clone https://gitcode.com/openJiuwen/jiuwensymbiosis.git cd jiuwensymbiosis conda create -n jiuwensymbiosis python=3.12 conda activate jiuwensymbiosis python -m pip install -e .

按需安装可选能力（README 原样继承，全部命令可复制运行）：

python -m pip install -e ".[dev]" # 测试与开发工具 python -m pip install -e ".[piper]" # Piper SDK python -m pip install -e ".[so101]" # SO-101 / LeRobot；Python 3.12 python -m pip install -e ".[cruzr]" # Cruzr 双臂（pinocchio 臂 IK；rclpy 由 ROS 工作区提供，非 pip 依赖） python -m pip install -e ".[voice]" # ASR 与录音 python -m pip install -e ".[gui]" # 现有工作台 GUI（NiceGUI 浏览器界面） python -m pip install -e ".[calib]" # 手眼标定 python -m pip install -e ".[full]" \ --extra-index-url https://download.pytorch.org/whl/cu128 # 视觉/GPU 栈

• 可选依赖可以组合安装，如.[full,piper]、.[full,so101]、.[full,cruzr]；凡是包含[full]的命令仍需 PyTorch CUDA 12.8 附加源。
• 安装固定版本运行依赖可执行python -m pip install -r requirements.txt && python -m pip install -e . --no-deps（requirements.txt 不是完整环境锁文件）。
• 统一 GUI 启动器通过插件 key 选择界面：

jiuwensymbiosis-gui --list-guis jiuwensymbiosis-gui --gui workbench # 等价模块入口 python -m jiuwensymbiosis_gui --gui workbench

.[gui]安装现有工作台（NiceGUI 浏览器界面）的依赖；单独发布的 GUI 插件安装到同一 Python 环境后经--gui <key>选择。更详细的安装步骤见 docs/zh/tutorial/01-quick-start.md。

4.1 代理导入安全（自定义 Python 入口必读）

HTTP 代理环境变量可能破坏本地 vLLM 和检测调用。自行编写 Python 入口时，必须在导入openjiuwen或任何间接导入它的模块前调用clear_proxy_env()：

from jiuwensymbiosis.utils.proxy import clear_proxy_env clear_proxy_env() # 在下方导入 openjiuwen 或其余 JiuwenSymbiosis Agent 模块。

仓库内置 CLI（examples/run_task.py）和示例已处理这一步。

五、内置适配器

README 列出的内置适配器及其能力如下：

MockArmEnv仍作为内置内存模拟 Env 提供，并用于--mock（仅 Piper），但它不是硬件适配器。SCARA 和吸盘属于框架已支持的扩展契约（grasp.suction有完整契约但无内置真机适配器），准确的启用条件见 docs/zh/reference/feature-matrix.md。

从源码看各适配器的能力差异可以直接映射到配置：SO-101 声明了motion.cartesian、motion.joint、motion.servo、grasp.parallel、vision.camera/depth/detection/eye_to_hand；Cruzr 独有motion.base/base_servo/lift/waist/goal/dual_arm、grasp.paddle、vision.search与planning.reachability（URDF 双臂 + 自适应升降判据）。

5.1 真实配置示例：SO-101（桌面抓放）

configs/so101/so101.yaml包含已验收设备的示例值。关键字段：adapter: so101、串口port、robot_id、关节软限位joint_limits（度）、z_min_safe_mm/z_max_safe_mm安全边界、夹爪参数（gripper_open_pos/gripper_close_pos百分比、接触判定三件套gripper_contact_min_travel/stall_tolerance/stall_samples）、相机camera_mount: eye_to_hand+camera_serial、detector块（mode: local，GDINO/SAM2 模型路径、box_threshold、text_threshold、use_sam2），以及agent.execution.mode: fastagent与实时伺服参数（control_hz: 20.0、max_lin_step_mm: 3.0）。

5.2 真实配置示例：Cruzr（移动双臂）

configs/cruzr/cruzr.yaml描述"这台机器人"：ros_workspace、腰部/头部相机话题（waist_color_topic等）、urdf_path与urdf_package_dir（自碰撞依赖）、夹板夹取参数（contact_force_threshold_n、grasp_inset_mm、place_squeeze_mm）、底盘接近与连续视觉伺服参数（approach_k_*、grasp_servo_enabled等），以及agent.modules.safety/recovery.enabled。该配置声明motion.base，因此transport技能通过能力门；固定臂机型不具备移动能力，同一条任务编排出的序列并不相同。

5.3 会话构建：make_builder 消除样板代码

各适配器的build_xxx_session由adapters/_common/builder.py的make_builder生成，封装配置解析、Env/API 构造、客户端与可选本地进程的资源登记和 Session 装配：

build_xxx_session = make_builder( XxxConfig, XxxEnv, XxxApi, api_kwargs_from_cfg=["z_correction_mm"], sidecar_builders=[make_detector_sidecar()], managed_detector=True, decorate=_set_extra_globals, ) # build_xxx_session(cfg) # build_xxx_session.from_yaml("path.yaml") # build_xxx_session.from_dict({...})

api_kwargs_from_cfg支持同名字段、cfg:api重命名和嵌套点路径；managed_detector=True创建懒加载 HTTP 检测客户端注入 Api；make_detector_sidecar()只为mode: local提供模型子进程。

六、Quick Start：两个真机验证过的运行示例

先在配置里填入自己的串口、序列号和端点，并完成安全边界验收。

SO-101 —— 桌面抓放：

python examples/run_task.py \ --config configs/so101/so101.yaml \ --query "把香蕉放到盘子里" \ --api-key "$OPENJIUWEN_API_KEY"

Cruzr —— 优必选轮式人形机器人移动搬运（先 source ROS 2 + Cruzr 工作区）：

python examples/run_task.py \ --config configs/cruzr/cruzr.yaml \ --query "把棕色箱子上的白色箱子搬到有香蕉的白桌子上" \ --api-key "$OPENJIUWEN_API_KEY"

examples/run_task.py是通用任务入口：--config选机器人（YAML 顶层adapter:字段从注册表选中，--robot可覆盖），--query（或--voice）给任务——任务不在 config 里。--mock仅对 Piper 提供无硬件干跑（MockArmEnv+ 离线MockModelClient），其他机器人走各自的真机会话。完整的 CLI 参数（--server-url、--model、--api-key、--stepagent、--no-skill、--mode、--control-hz、--servo-step-mm、--workspace等）见 examples/run_task.py 与 docs/zh/reference/cli.md。各自完整的前置条件见 examples/README.md。

6.1 无硬件快速验证：Piper Mock 干跑

安装后无需机器人、GPU 与真实 LLM 即可验证 Agent 接线（来自 docs/zh/tutorial/01-quick-start.md）：

python examples/run_task.py \ --config configs/piper/piper.yaml \ --mock \ --max-iter 1 \ --no-visual-feedback \ --workspace /tmp/jiuwensymbiosis-demo \ --query "把黑色盒子放到白色盒子上面"

该命令使用MockArmEnv和离线MockModelClient，建立RobotSession、构造 Agent、加载内置技能与工具并执行一次模型调用，不连接 CAN、相机、检测服务或模型端点。最终结果应包含"mock: no real model, task skipped"并以退出码0结束。Mock 模式是接线冒烟测试，不代表物理操作成功。

七、配套工具与文档导航

• CLI 自省工具：jiuwensymbiosis-actions --vocabulary（共享动作词表）、jiuwensymbiosis-actions --config <robot>.yaml（门控到本体的动作词表）、jiuwensymbiosis-skills（技能库 + 契约）、jiuwensymbiosis-state --config <robot>.yaml（实时世界状态），是规划器/编码智能体读取的机器可读视图。
• 轨迹回放：jiuwensymbiosis-replay <trace.json>默认生成自包含 HTML 回放，--text输出文本时间线；样例见 examples/sample_trace/。
• 手眼标定：安装.[calib]后提供jiuwensymbiosis-calibrate-hand-eye（mount-neutral 统一入口）及 eye-in-hand / eye-to-hand 两个强制安装方式的入口。
• 文档中心：docs/README.md 汇集 Tutorial、How-to、Reference 与 Explanation；架构细节见 docs/zh/explanation/architecture.md，能力支持状态见 docs/zh/reference/feature-matrix.md，远程推理部署见 docs/zh/how-to/remote-inference.md 与 deploy/inference/README.md。

八、License 与合规说明

本项目基于 Apache License 2.0 开源。本产品仅作为流程编排工具，不包含 AI 模型能力；用户在连接 AI 模型用于特定业务场景时，需自行承担欧盟 AI 法案等相关合规义务。

• 具身智能
• 人工智能
• AI Agent
• 机器人
• 计算机视觉
• Agent 编排