dev: fix miku and jetarm-agent, add workspace for examples

Author: thirdgerb

examples/.env.example

@@ -24,8 +24,8 @@ MOSS_LLM_MODEL="volcengine/doubao-seed-1-6-251015"
 # 访问模型接口的 api key
 MOSS_LLM_API_KEY=your_api_key_here
 
-# 是否开启语音回复.
-USE_VOCIE_SPEECH="yes"   # yes or no
+# 是否开启语音回复. 开启的前提是配置了火山引擎的生成.
+USE_VOICE_SPEECH="yes"   # yes or no
 
 # 创建一个火山引擎的 "大模型流式 tts 合成应用"
 # 获得 app id 和 access token 放在此.

examples/jetarm_demo/README.md

@@ -0,0 +1,16 @@
+# jetarm demo
+
+用来验证对 幻尔 6dof 机械臂 的控制.
+
+运行前需要:
+
+1. 真的有幻尔 6dof jetarm 机械臂.
+2. 在机械臂开发板上, 已经实装了 jetarm_ws, 完成编译可运行, 并启动了 jetarm_channel 和 jetarm_control 节点.
+3. 已经完成了 examples 的依赖安装.
+
+运行:
+
+1. 测试 `python connect_pychannel_with_rcply.py --address=jetarm_control监听的地址端口`, 看看是否能运动.
+2. 启动 agent `python jetarm_agent.py --address=jetarm_control监听的地址端口`
+
+这个例子不必特别测试. jetarm 本身二次开发难度比较大. 看看样例知道怎么回事就可以了. 

examples/jetarm_demo/connect_pychannel_with_rcply.py

@@ -1,4 +1,5 @@
 import asyncio
+import argparse
 
 from ghoshell_moss.transports.zmq_channel.zmq_channel import ZMQChannelProxy
 
@@ -27,9 +28,23 @@ async def main():
     测试 jetarm 的脚本, 通过 zmq proxy 调用 zmq provider 的方式, 与 jetarm channel 进行通讯.
     然后测试脚本可以运行.
     """
+    # 创建参数解析器
+    parser = argparse.ArgumentParser(description="运行 jetarm 测试轨迹例程")
+
+    # 添加 --address 参数，设置默认值
+    parser.add_argument(
+        "--address",
+        type=str,
+        default=JETARM_ADDRESS,
+        help=f"代理地址，默认值: {JETARM_ADDRESS}",
+    )
+
+    # 解析命令行参数
+    args = parser.parse_args()
+
     chan = ZMQChannelProxy(
         name="jetarm",
-        address=JETARM_ADDRESS,
+        address=args.address,
     )
 
     async with chan.bootstrap() as broker:

examples/jetarm_demo/jetarm_agent.py

@@ -1,6 +1,7 @@
 import asyncio
 
 from ghoshell_container import Container
+import argparse
 
 from ghoshell_moss.core.shell import new_shell
 from ghoshell_moss.speech import make_baseline_tts_speech
@@ -9,20 +10,21 @@
 from ghoshell_moss.transports.zmq_channel.zmq_channel import ZMQChannelProxy
 from ghoshell_moss_contrib.agent import ModelConf, SimpleAgent
 from ghoshell_moss_contrib.agent.chat import ConsoleChat
-
-container = Container(name="jetarm_agent_container")
+from ghoshell_moss_contrib.example_ws import workspace_container, get_container
+from pathlib import Path
 
 ADDRESS = "tcp://192.168.1.15:9527"
 """填入正确的 ip, 需要先对齐 jetarm_ws 运行的机器设备和监听的端口. """
 
 
-async def run_agent():
+async def run_agent(address: str = ADDRESS, container: Container | None = None):
+    container = container or get_container()
     # 创建 Shell
     shell = new_shell(container=container)
 
     jetarm_chan = ZMQChannelProxy(
         name="jetarm",
-        address=ADDRESS,
+        address=address,
     )
 
     shell.main_channel.import_channels(jetarm_chan)
@@ -56,8 +58,24 @@ async def run_agent():
 
 
 def main():
-    # 运行异步主函数
-    asyncio.run(run_agent())
+    # 创建参数解析器
+    parser = argparse.ArgumentParser(description="运行 jetarm agent 程序")
+
+    # 添加 --address 参数，设置默认值
+    parser.add_argument(
+        "--address",
+        type=str,
+        default="tcp://192.168.1.15:9527",
+        help="代理地址，默认值: tcp://192.168.1.15:9527"
+    )
+
+    # 解析命令行参数
+    args = parser.parse_args()
+
+    ws_dir = Path(__file__).resolve().parent.parent.joinpath('.workspace')
+    with workspace_container(workspace_dir=ws_dir) as container:
+        # 运行异步主函数，传入地址参数
+        asyncio.run(run_agent(address=args.address, container=container))
 
 
 # 运行主函数

examples/jetarm_ws/README.md

@@ -108,18 +108,18 @@ source install/setup.zsh
 ## 核心目录说明
 
 - `src`: 核心库目录
-  - `jetarm_6dof_description`:
-    用来存放 jetarm 的机器人描述相关讯息,
-    也可以启动 rviz `ros2 launch jetarm_6dof_description view_model.launch.py`
-  - `jetarm_driver`:
-    是验证 python 驱动的节点, 想用 python 实现 ros2 control 的 interface. 不过现在不用了.
-  - `jetarm_control`:
-    核心的 ros2 control 实现. 启动这个节点, 机器人就可以驱动了. 详见后面的测试用例. deepseek 等也能给出 ros2
-    control 支持的各种命令.
-    运行这个节点的脚本是 `ros2 launch jetarm_control jetarm_control.launch.py`
-  - `jetarm_moveit2`:
-    这个是基于 ros2 control (jetarm_control) 实现的 moveit 节点, 所有的代码应该都由 moveit2 的 assitant 生成.
-    具体方法可以问模型, 需要提前安装 moveit2 到全局环境里.
+    - `jetarm_6dof_description`:
+      用来存放 jetarm 的机器人描述相关讯息,
+      也可以启动 rviz `ros2 launch jetarm_6dof_description view_model.launch.py`
+    - `jetarm_driver`:
+      是验证 python 驱动的节点, 想用 python 实现 ros2 control 的 interface. 不过现在不用了.
+    - `jetarm_control`:
+      核心的 ros2 control 实现. 启动这个节点, 机器人就可以驱动了. 详见后面的测试用例. deepseek 等也能给出 ros2
+      control 支持的各种命令.
+      运行这个节点的脚本是 `ros2 launch jetarm_control jetarm_control.launch.py`
+    - `jetarm_moveit2`:
+      这个是基于 ros2 control (jetarm_control) 实现的 moveit 节点, 所有的代码应该都由 moveit2 的 assitant 生成.
+      具体方法可以问模型, 需要提前安装 moveit2 到全局环境里.
 
 # 常用测试命令
 

examples/miku/main.py

@@ -1,17 +1,11 @@
 import os
 import sys
 
-import dotenv
-from ghoshell_common.contracts import LocalWorkspaceProvider
-
-from ghoshell_moss.speech import make_baseline_tts_speech
+from ghoshell_moss.speech import make_baseline_tts_speech, Speech
 from ghoshell_moss.speech.player.pyaudio_player import PyAudioStreamPlayer
 from ghoshell_moss.speech.volcengine_tts import VolcengineTTS, VolcengineTTSConf
 from ghoshell_moss_contrib.agent import ModelConf, SimpleAgent
 
-current_dir = os.path.dirname(os.path.abspath(__file__))
-sys.path.append(current_dir)
-
 import asyncio
 from os.path import dirname, join
 
@@ -27,18 +21,19 @@
 from miku_channels.head import head_chan
 from miku_channels.leg import left_leg_chan, right_leg_chan
 from miku_channels.necktie import necktie_chan
-
 from ghoshell_moss.core.shell import new_shell
+from ghoshell_moss_contrib.example_ws import workspace_container, get_example_speech
+import pathlib
+
+# 加载当前路径.
+current_dir = os.path.dirname(os.path.abspath(__file__))
+sys.path.append(current_dir)
 
 # 全局状态
 model: live2d.LAppModel | None = None
-container = Container()
 WIDTH = 600
 HEIGHT = 800
 
-WORKSPACE_DIR = ".workspace"
-dotenv.load_dotenv(f"{WORKSPACE_DIR}/.env")
-
 
 # 初始化Pygame和Live2D
 def init_pygame():
@@ -50,7 +45,7 @@ def init_pygame():
 
 
 # 初始化Live2D模型
-def init_live2d(model_path: str):
+def init_live2d(model_path: str, container: Container):
     global model
     live2d.init()
     live2d.glInit()
@@ -101,11 +96,9 @@ def stop_speak(*args):
     speaking_event.clear()
 
 
-async def run_agent():
+async def run_agent(container: Container, speech: Speech | None = None):
     loop = asyncio.get_running_loop()
 
-    container.register(LocalWorkspaceProvider(".workspace"))
-
     # 创建 Shell
     shell = new_shell(container=container)
 
@@ -142,12 +135,15 @@ async def speaking():
     player = PyAudioStreamPlayer()
     player.on_play(start_speak)
     player.on_play_done(stop_speak)
-    tts = VolcengineTTS(conf=VolcengineTTSConf(default_speaker="saturn_zh_female_keainvsheng_tob"))
+    speech = speech or container.get(Speech)
+    if speech is None:
+        tts = VolcengineTTS(conf=VolcengineTTSConf(default_speaker="saturn_zh_female_keainvsheng_tob"))
+        speech = make_baseline_tts_speech(player=player, tts=tts)
 
     agent = SimpleAgent(
         instruction="你是miku, 拥有 live2d 数字人躯体. 你是可爱和热情的数字人. ",
         shell=shell,
-        speech=make_baseline_tts_speech(player=player, tts=tts),
+        speech=speech,
         model=ModelConf(
             kwargs={
                 "thinking": {
@@ -162,22 +158,22 @@ async def speaking():
     await speaking_task
 
 
-async def run_agent_and_render():
+async def run_agent_and_render(container: Container, speech: Speech | None = None):
     # 初始化 Pygame 和 Live2D
     screen, display = init_pygame()
     model_path = join(dirname(__file__), "model/miku.model3.json")
-    init_live2d(model_path)
+    init_live2d(model_path, container)
 
     # 保持窗口打开，直到用户关闭
     running = True
     clock = pygame.time.Clock()
     font = pygame.font.SysFont(None, 24)
 
     # 创建一个任务来运行 agent
-    agent_task = asyncio.create_task(run_agent())
+    agent_task = asyncio.create_task(run_agent(container, speech))
 
     try:
-        while running:
+        while running and not agent_task.done():
             # 处理pygame事件
             for event in pygame.event.get():
                 if event.type == pygame.QUIT:
@@ -201,20 +197,26 @@ async def run_agent_and_render():
         pass
     finally:
         # 取消agent任务
-        agent_task.cancel()
-        try:
-            await agent_task
-        except asyncio.CancelledError:
-            pass
+        if not agent_task.done():
+            agent_task.cancel()
+            try:
+                await agent_task
+            except asyncio.CancelledError:
+                pass
 
         # 清理资源
         live2d.dispose()
         pygame.quit()
 
 
+WORKSPACE_DIR = pathlib.Path(__file__).parent.parent.joinpath('.workspace')
+
+
 def main():
     # 运行异步主函数
-    asyncio.run(run_agent_and_render())
+    with workspace_container(WORKSPACE_DIR) as container:
+        speech = get_example_speech(container)
+        asyncio.run(run_agent_and_render(container, speech))
 
 
 # 运行主函数

examples/miku/miku_channels/body.py

@@ -24,6 +24,8 @@ async def on_policy_run():
         # 等待 其他 Motions 完成
         while not model.IsMotionFinished():
             await asyncio.sleep(0.1)
+        if not body_chan.is_running():
+            break
         model.ResetExpressions()  # 防止表情重叠
         model.ResetExpression()
         # Policy的Priority设置为1（较低），是为了确保其他Motion可打断Policy Motion

pyproject.toml

@@ -33,6 +33,7 @@ contrib = [
     "rich>=14.2.0",
     "javascript>=1!1.2.6",
     "opencv-python>=4.13.0.92",
+    "loadenv>=0.1.1",
 ]
 
 [tool.setuptools]

src/ghoshell_moss/message/abcd.py

@@ -386,16 +386,16 @@ class Message(BaseModel, WithAdditional):
     seq: Literal["head", "delta", "incomplete", "completed"] = Field(
         default="completed",
         description="消息的传输状态, 目前分为首包, 间包和尾包."
-        "- 首包: 用来提示一个消息流已经被生产. 通常用来通知前端界面, 提前渲染消息容器"
-        "- 间包: 用最少的讯息传递一个 delta 包, 用于流式传输"
-        "- 尾包: 包含所有 delta 包粘包后的完整结果, 用来存储或展示."
-        "尾包分为 completed 和 incomplete 两种. "
-        "- completed 表示一个消息体完全传输完毕."
-        "- incomplete 表示虽然没传输完毕, 但可能也要直接使用."
-        "我们举一个具体的例子, 在模型处理多端输入时, 一个视觉信号让模型要反馈, 但一个 asr 输入还未全部完成;"
-        "这个时候, 大模型仍然要看到未完成的语音输入, 也就是 incomplete 消息."
-        "但是下一轮对话, 当 asr 已经完成时, 历史消息里不需要展示 incomplete 包."
-        "所以 incomplete 主要是用来在大模型思考的关键帧中展示一个粘包中的中间结果.",
+                    "- 首包: 用来提示一个消息流已经被生产. 通常用来通知前端界面, 提前渲染消息容器"
+                    "- 间包: 用最少的讯息传递一个 delta 包, 用于流式传输"
+                    "- 尾包: 包含所有 delta 包粘包后的完整结果, 用来存储或展示."
+                    "尾包分为 completed 和 incomplete 两种. "
+                    "- completed 表示一个消息体完全传输完毕."
+                    "- incomplete 表示虽然没传输完毕, 但可能也要直接使用."
+                    "我们举一个具体的例子, 在模型处理多端输入时, 一个视觉信号让模型要反馈, 但一个 asr 输入还未全部完成;"
+                    "这个时候, 大模型仍然要看到未完成的语音输入, 也就是 incomplete 消息."
+                    "但是下一轮对话, 当 asr 已经完成时, 历史消息里不需要展示 incomplete 包."
+                    "所以 incomplete 主要是用来在大模型思考的关键帧中展示一个粘包中的中间结果.",
     )
     delta: Optional[Delta] = Field(
         default=None,
@@ -405,11 +405,11 @@ class Message(BaseModel, WithAdditional):
 
     @classmethod
     def new(
-        cls,
-        *,
-        role: Literal["assistant", "system", "developer", "user", ""] = "",
-        name: Optional[str] = None,
-        id: Optional[str] = None,
+            cls,
+            *,
+            role: Literal["assistant", "system", "developer", "user", ""] = "",
+            name: Optional[str] = None,
+            id: Optional[str] = None,
     ):
         """
         语法糖, 用来创建一条消息.

src/ghoshell_moss/speech/__init__.py

@@ -1,14 +1,14 @@
 from ghoshell_common.contracts import LoggerItf
 
-from ghoshell_moss.core.concepts.speech import TTS, StreamAudioPlayer
+from ghoshell_moss.core.concepts.speech import TTS, StreamAudioPlayer, Speech, SpeechStream
 from ghoshell_moss.speech.mock import MockSpeech
 from ghoshell_moss.speech.stream_tts_speech import TTSSpeech, TTSSpeechStream
 
 
 def make_baseline_tts_speech(
-    player: StreamAudioPlayer | None = None,
-    tts: TTS | None = None,
-    logger: LoggerItf | None = None,
+        player: StreamAudioPlayer | None = None,
+        tts: TTS | None = None,
+        logger: LoggerItf | None = None,
 ) -> TTSSpeech:
     """
     基线示例.