企业官网建设流程全解析

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

本文是 jiuwensymbiosis 示例工程（examples/）的实战指南。它围绕仓库自带的「通用任务运行器」展开：同一个入口examples/run_task.py（安装后为jiuwensymbiosis-run）如何通过--config选定机器人、用--query下达自然语言任务，并在fastagent（一次编译、逐步骤不调 LLM）与stepagent（逐步 LLM 调试）两种执行模式之间切换。读完本文，你将掌握 SO-101 与 Cruzr 两套真机示例的配置要点、safety_validated安全门禁的正确使用方式，以及如何用jiuwensymbiosis-replay回放样例执行轨迹（trace）产物。文中所有结论均可回到对应配置、源码与测试中验证。

一、示例工程的结构与使用前提

examples/目录从仓库根目录即可直接运行，其内容分为两大部分：

• 通用任务运行器：examples/run_task.py，是所有机器人和任务的统一入口；
• 样例执行轨迹：examples/sample_trace/，保存一份脱敏的轨迹 JSON、HTML 回放和逐步图像，用于了解 trace 产物。

运行前需先按中文 README 安装依赖。pyproject.toml中声明了与真机相关的可选依赖组：SO-101 需要so101组（lerobot[feetech,kinematics]>=0.6.0,<0.7，且仅支持 Python>=3.12），Cruzr 需要cruzr组（pin>=4.1提供臂 IK 与自碰撞检测；rclpy由 ROS 2 工作区提供，不属于 pip 依赖）。

二、通用任务运行器：一个入口，任意机器人与任务

1. 设计思想：任务不在配置里

examples/run_task.py的核心设计可以用一句话概括：任务不在 config 里。机器人和环境参数写进 YAML 配置，任务则在运行时由--query给出，因此新增一个任务只需换一条--query，接入新机器人只需换一份--config——不需要新增任何 Python 文件。源码开头即点明这一点：

Pick the robot with--config(the YAML'sadapter:field selects the adapter from the registry;--robotoverrides). Give the task at run time with--query "..."or--voice— thetask is not in the config.

这也解释了为何configs/下的三份机器人配置（so101.yaml、cruzr.yaml、piper.yaml）都不包含任务字段——它们只描述「这台机器人是谁、有哪些安全边界、用什么模型编排」，任务永远来自运行时。

2. 机器人如何被选中：adapter 注册表

运行器通过配置顶层adapter:字段从适配器注册表选中机器人。_robot_session_builders()维护了一张注册表（run_task.py）：

from jiuwensymbiosis.adapters.cruzr import build_cruzr_session from jiuwensymbiosis.adapters.piper import build_piper_session from jiuwensymbiosis.adapters.so101 import build_so101_session return {"piper": build_piper_session, "cruzr": build_cruzr_session, "so101": build_so101_session}

机器人身份解析的优先级是：--robot命令行参数 > config 顶层adapter:>piper（向后兼容，见_resolve_robot）。例如 so101.yaml 第 3 行adapter: so101、cruzr.yaml 第 9 行adapter: cruzr，各自选中对应适配器。真正的会话构建是build.from_yaml(args.config)——每个适配器都暴露.from_yaml(path)，把 YAML 一键变成可用的RobotSession。

3. 执行模式：fastagent 与 stepagent

执行模式取自 YAML 的agent.execution.mode，默认fastagent。两种模式的区别（run.py）：

• fastagent（任务运行默认）：一次 LLM 推理读取候选技能的 SKILL.md，并在同一次调用中输出扁平的动作序列（技能选择 + 工作流转录一体完成），随后通用执行器run_sequence按序执行——没有逐步 LLM，检测结果在步骤间传递，track_detect步骤接入实时跟踪目标。每次技能的选择依据是其 SKILL.md 单一事实源，不存在逐个技能的 Python 执行器，因此 fast 与逐步 agent 不会漂移，新技能就是一份新的 SKILL.md。
• stepagent（单步调试）：构建DeepAgent并invoke，每步都由 LLM 编排，多次往返，适合单步调试与验证。--stepagent可强制切换。

run_task.py的--mock（仅 piper 可用）会自动隐含--stepagent，用MockArmEnv+ 离线模型做无硬件干跑。需要留意：逐步视觉反馈（visual_feedback）与失败诊断（diagnosis）目前只支持 stepagent，不能在 fastagent 中显式启用（详见 agent-config.md）。

4. CLI 参数速查表

main()中的argparse定义了完整参数（run_task.py）：

运行器还会做「无任务」保护：非语音模式下必须给出非空--query，否则返回退出码 2 并提示「config 不内置任务」。这从机制上杜绝了「默默跑一个默认任务」的隐患。

5. 模型规格的构建优先级

_build_model_spec展示了 CLI 与 YAML 的合并规则：--server-url会去掉尾部/chat/completions后写入api_base；API Key 的优先级是--api-key>$OPENJIUWEN_API_KEY> YAMLmodel.api_key。这与 so101.yaml 中api_key: "" # 用 --api-key 覆盖的注释完全对应——密钥不应写入配置文件。

三、SO-101 真机示例：从安全门禁到部署字段

1. 前置条件

SO-101（5-DoF + 平行夹爪，基于 LeRobot 0.6.x SOFollower）需要：

• Python 3.12（pyproject.toml中so101依赖组明确仅支持 Python>=3.12）；
• LeRobot 0.6.x（lerobot[feetech,kinematics]>=0.6.0,<0.7）；
• 电机标定（首次部署须先运行lerobot-calibrate --robot.id=so101生成标定文件，否则驱动connect()会在标定预检阶段直接报错）；
• 有效的眼在手外（eye-to-hand）标定。

2.safety_validated安全门禁

configs/so101/so101.yaml包含已验收设备的示例值。动手前必须先把safety_validated改为false，再填写串口、相机序列号、标定路径和本机安全边界；只有完成限位、工作空间和急停验收后，才能重新改为true。

从 config_template.yaml 可以看到这一门禁的底层行为：

false时 Driver.connect() 会在打开串口前拒绝连接。home_use_init_pose: true可豁免此门禁（须先上电才能读当前关节角）。

模板还给出了真机风险提示：关节软限位以真机和官方资料为准，上表数值仅为占位，务必实测收紧；z_min_safe/workspace_bounds是 TCP 边界，不等于整臂碰撞检测，真机验收必须覆盖连杆碰桌、底座、自碰风险。未完成真机验收前保持safety_validated=false，不要仅为绕过门禁而改成 true。

3. 运行命令

完成配置与验收后运行：

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

4. 部署字段与默认值

configs/so101/so101.yaml中env.cfg.low_level段集中了本机参数，其中几类值得重点说明：

• 连接与运动学：robot_id: "so101_left"必须与lerobot-calibrate --robot.id=一致；ik_target_frame: "gripper_frame_link"是 IK 控制帧；ik_orientation_weight: 0.01表示姿态权重小、更偏向位置求解；cartesian_orientation_policy: preserve让 5-DoF 普通移动保持实时姿态，避免被无条件切到rx=180/ry=0；grasp_orientation: null表示真机示教前不启用 grasp 姿态策略，显式使用会安全拒绝。
• 到位判定：move_timeout_s: 10.0是最终点完全不收敛时的最长等待；settle_z_only_lift_enabled: true表示持物上移时若关节已稳定但 Z 仍偏低，只优化 Z、允许 XY 小幅漂移（受软限位与最大关节偏置保护）。
• 安全边界：z_min_safe_mm: -10.0是 gripper_frame_link 控制帧下限（不是桌面或指尖高度），z_max_safe_mm: 400.0拦截高处近奇异姿态；table_z_mm: null时实体最低点模型保持禁用。
• 夹爪接触判定：gripper_contact_min_travel: 5.0配合 stall 容差与采样数，用于「关闭时明显运动且连续稳定在非全闭位置」→ 判定为接触香蕉而非超时。
• 视觉：桌面固定 eye-to-hand RealSense D405，camera_mount: "eye_to_hand"（SO-101 相机桌面固定，只接受该值）。

完整的部署字段与默认值清单见 SO-101 配置模板，模板按[必填] / [选填] / [真机风险]标注，并统一单位约定：关节=度、夹爪=0..100 百分比、位移=mm、姿态=intrinsic XYZ Euler 度。

5. 检测服务与模型配置

so101.yaml 的detector块采用mode: local，由框架启动/关闭本地 GPU 模型（GroundingDINO + SAM2）；切换remote时只需替换为endpoint.url（如http://127.0.0.1:8114），Agent 主机无需安装模型权重。model块是非视觉编排模型——视觉由检测工具完成，因此运行时配合--no-visual-feedback避免向非 VLM 模型发送图像。检测服务的完整部署说明见服务部署 README。

四、Cruzr 真机示例：ROS 2 双臂与能力门控

1. 前置条件

Cruzr 需要 ROS 2（Jazzy）工作区、腰部/头部相机、标定和检测服务。运行前需sourceROS + Cruzr 工作区（配置中ros_workspace: "~/Robot/Cruzr_ws"、ros_backend: auto）并启动检测服务。

2. 配置要点

在 cruzr.yaml 中保持adapter: cruzr，然后填写：ROS 工作区路径、相机话题（腰部 RGBD 三话题：color / depth / camera_info，头部点云/sensor/camera/stereo/pointcloud/jazzy）、标定文件camera_calib_path: cruzr_camera_calib.json（相对本 YAML 所在目录）、URDF 路径与urdf_package_dir（自碰撞检查依赖它，不配会静默失效）、检测服务地址与编排 LLM 端点，并验收安全边界。这份配置还沉淀了大量真机调优参数，例如头部搜索head_search_yaw_positions_rad: [0.6, -0.6]（2-look）、驱近头部偏航跟踪增益head_yaw_track_gain: 0.9、底盘「搜索快 + 接近准」两组分离的轮速旋钮、以及夹取/放置各阶段独立的 ramp 时长。

3. 运行命令

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

4. 能力门控：为什么 Cruzr 能「搬」而固定臂不能

原文档特别指出：Cruzr 声明了motion.base，transport技能因此通过能力门。这在源码层面有两处印证：

• cruzr/env.py 的capabilities集合包含"motion.base"、"motion.base_servo"、"motion.dual_arm"、"grasp.paddle"等；
• transport/SKILL.md 明确要求机器人api.capabilities含motion.base或motion.waist至少一种才启用本技能，且只在移动动作的候选表（rotate_base/navigate_relative/turn_waist）中调用能力内的动作。

因此，同一句「把 X 搬到 Y」的任务，在固定臂机型（无motion.base/motion.waist）上编排出的序列与 Cruzr 并不相同——固定臂不具备移动能力，transport技能直接不适用。

5. 敏感信息管理：*.local.yaml

不想让串口、序列号和密钥出现在git status里，可以复制成configs/<机器人>/<机器人>.local.yaml再改——.gitignore里的*.local.yaml会忽略它，--config指向该副本即可。

仓库.gitignore第 7 行确认为*.local.yaml。这一约定同样适用于 so101 与 piper 的真机参数（SO-101 配置模板的视觉段也提示「真机参数放在不提交的本地调试 YAML 中」）。它是保护硬件身份信息与密钥的第一道防线。

五、样例执行轨迹：JSON、HTML 与逐步图像

sample_trace/保存一份 Piper 演示的脱敏执行轨迹，包含三部分产物：

• *.json：结构化ExecutionTrace（含 conversation_id、robot_name、query、每个步骤的工具名/参数/耗时/观察快照/rail 事件）；
• *.html：可直接在浏览器打开的自包含回放（每步图像以 base64 内联，图像与参数/错误/rail 事件在同一卡片中）；
• frames/：轨迹步骤引用的图像帧。

安装本项目后，从仓库根目录进行文本回放：

jiuwensymbiosis-replay \ examples/sample_trace/piper-demo-77816242_20260626_113438_033124_1743847.json \ --text

去掉--text会生成自包含 HTML 回放。预期结果：终端显示步骤时间线，或生成并打印 HTML 回放路径。

轨迹回放 CLI 对应 cli.py 的replay()：按步骤打印[step] ✅/❌ tool_name(params)与耗时，trace_log保留完整日志。其底层产物由 trace.py 的TraceRail在modules.tracing.enabled时写入工作区traces/目录——sample_trace就是这类产物的脱敏样本。重要提醒：样例轨迹仅用于了解 trace 产物形态，不应作为机器人正确性基准。

从示例轨迹 JSON 可以看到一次典型执行的开端：step 1 list_skill（列出候选技能 visual_pick / visual_place 等）、step 2 skill_tool……每步都记录了observation（位姿、关节角、z_min_safe）与frame_path，这正是回放页面的数据来源。

六、安全须知

原文档的告诫值得全文引用：运行前必须完成硬件、标定、检测服务和安全边界验收，不要在未验证的工作空间无人值守运行。两份示例都经过真机验证，但验证结果依赖你本机的设备状态——串口、相机序列号、标定文件、软限位与安全边界必须按真机逐项确认，safety_validated从false回到true只应在完成限位、工作空间与急停验收之后。

七、小结

examples/是 jiuwensymbiosis「一条命令跑真机任务」的最短路径：jiuwensymbiosis-run --config <机器人>.yaml --query "<任务>"。其背后的机制是 adapter 注册表选机器人、SKILL.md 单一事实源编译动作序列、能力门控决定技能可用性、trace 产物记录每一步执行证据。从「通用任务运行器」到「SO-101 / Cruzr 真机示例」再到「样例轨迹回放」，整个示例工程的脉络清晰可循，相关源码与配置路径均已在上文逐一给出，可直接回到仓库验证。

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