dev: add vision exam to alpha

Author: thirdgerb

examples/.workspace/runtime/agent_history/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

examples/.workspace/runtime/logs/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

examples/README.md

@@ -0,0 +1,33 @@
+# 关于 Examples
+
+本目录用来存放各种 Alpha 版本的测试用例. 用来展示不同的基线功能.
+每个子目录内都有 README.md 提示如何使用.
+
+> 建议使用 mac, 基线都是在 mac 上测试的. windows 可能兼容存在问题. 
+ 
+使用 examples 的步骤: 
+
+## 1. clone 仓库
+
+```bash
+git clone https://github.com/GhostInShells/MOSShell MOSShell
+cd MOSShell
+```
+
+## 2. 创建环境
+
+* 使用 `uv` 创建环境, 运行 `uv venv` . 由于依赖 live2d, 所以默认的 python 版本是 3.12
+* 进入 uv 的环境: `source .venv/bin/activate`
+* 安装所有依赖: 
+
+```bash
+uv sync --active --all-extras
+```
+
+## 3. 配置环境变量
+
+todo
+
+## 4. 运行个别例子或全部 
+
+todo

examples/vision_exam/README.md

@@ -0,0 +1,16 @@
+# ZMQ Transport
+
+用来验证 Channel 通过 provider->broker 范式进行跨进程通讯, 并且能同步上下文.
+
+测试方式:
+
+1. 确保已经运行 `uv sync --active --all-extras` 完成依赖同步.
+2. 确认 python 在 uv 的 venv 环境: `which python`
+3. 直接运行 vision_provider: `python ./examples/vision_exam/vision_provider.py`
+    * 这会启动 vision channel 的 provider 进程, 监听 5557 端口允许被访问.
+    * 会打开一个 opencv 的端口, 可以看到视觉信息.
+4. 运行 vision_proxy: `python ./examples/vision_exam/vision_proxy.py`
+    * 会与 vision provider 建立双工通讯, 可以控制对方.
+    * 打开一个 pyqt6 的 simple viewer, 周期性同步 vision channel 的信息.
+
+当 vision provider 的视觉消息同步给了 vision proxy, 能正确展示图片, 则测试成功. 

examples/vision_exam/vision_provider.py

@@ -0,0 +1,30 @@
+from ghoshell_moss_contrib.channels.opencv_vision import OpenCVVision
+from ghoshell_moss import get_container
+from ghoshell_moss.transports.zmq_channel import ZMQChannelProvider
+
+if __name__ == "__main__":
+    # 初始化容器
+    _container = get_container()
+
+    # 创建视觉模块
+    vision = OpenCVVision(_container)
+
+    # 创建ZMQ Channel Provider
+    provider = ZMQChannelProvider(
+        address="tcp://localhost:5557",
+        container=_container,
+    )
+
+    try:
+        # 将视觉模块包装为Channel并运行
+        channel = vision.as_channel()
+        provider.run_in_thread(channel)
+
+        # 启动视觉捕获循环（会阻塞）
+        vision.run_opencv_loop()
+
+    finally:
+        # 确保清理顺序正确
+        vision.close()
+        provider.close()
+        provider.wait_closed_sync()

examples/vision_exam/vision_proxy.py

@@ -0,0 +1,34 @@
+import asyncio
+
+from ghoshell_moss.transports.zmq_channel.zmq_channel import ZMQChannelProxy
+from ghoshell_moss_contrib.gui.image_viewer import SimpleImageViewer, run_img_viewer
+from ghoshell_moss.message.contents import Base64Image
+
+if __name__ == '__main__':
+    # 测试专用.
+    proxy = ZMQChannelProxy(
+        name="vision",
+        address="tcp://127.0.0.1:5557",
+    )
+
+
+    def callback(viewer: SimpleImageViewer):
+
+        async def main():
+            async with proxy.bootstrap() as broker:
+                await broker.wait_connected()
+                while True:
+                    await asyncio.sleep(2)
+                    if not proxy.is_running():
+                        continue
+                    await proxy.broker.refresh_meta()
+                    meta = proxy.broker.meta()
+                    for msg in meta.context:
+                        for ct in msg.contents:
+                            if i := Base64Image.from_content(ct):
+                                viewer.set_pil_image(i.to_pil_image())
+
+        asyncio.run(main())
+
+
+    run_img_viewer(callback)

examples/zmq_transport/README.md

@@ -32,6 +32,7 @@ contrib = [
     "python-mpv-jsonipc>=1.2.1",
     "rich>=14.2.0",
     "javascript>=1!1.2.6",
+    "opencv-python>=4.13.0.92",
 ]
 
 [tool.setuptools]