Merge pull request #17 from GhostInShells/alpha

merge alpha branch

Author: thirdgerb

README.md

@@ -1,6 +1,6 @@
 # 项目概述
 
-项目名为 `MOS-Shell` (Model-oriented Operating System Shell), 包含两个几个核心目标:
+项目名为 `MOS-Shell` (Model-oriented Operating System Shell), 包含几个核心目标:
 
 1. `MOS`: 为 AI 大模型提供一个 "面向模型的操作系统", 可以将 跨设备/跨进程 的功能模块, 以 "树" 的形式提供给模型操作.
 1. `Shell Runtime`: 为 AI Agent 提供一个持续运转的运行时 (Runtime), 联通所有功能模块 (称之为 Channel, 对标 python 的
@@ -13,8 +13,9 @@
 目标是 AI 大模型作为大脑, 不仅可以思考, 还可以 实时/并行/有序 地操作包括 计算机/具身躯体 来进行交互.
 
 MOS-Shell 是 Ghost In Shells (中文名: 灵枢) 项目创建的新交互范式架构, 是第二代 MOSS 架构 (完善了 ChannelApp 和
-Realtime-Actions 思想).
-第一代 MOSS 架构 (全代码驱动 + FunctionToken) 详见 [GhostOS](https://github.com/ghostInShells/ghostos)
+Realtime-Actions 思想). 第一代 MOSS 架构 (全代码驱动 + FunctionToken) 详见 [GhostOS](https://github.com/ghostInShells/ghostos)
+
+**更多设计思路请访问飞书文档**: [核心设计思想综述](https://ycnrlabqki3v.feishu.cn/wiki/QCKUwAX7tiUs4GkJTkLcMeWqneh)
 
 ## Alpha 版本声明
 
@@ -27,9 +28,66 @@ Realtime-Actions 思想).
 
 如果想要试用项目, 请直接联系 灵枢开发组 配合.
 
+想要阅读架构的设计思想, 推荐直接看 [concepts 目录](src/ghoshell_moss/core/concepts).
+
 ## Examples
 
-本处放置如何使用 Alpha 版本的说明. 预计 2026-02-08 完成.
+在 [examples](examples) 目录下有当前 alpha 版各种用例. 具体的情况请查阅相关目录的 readme 文档. 
+
+体验 examples 的方法: 
+
+> 建议使用 mac, 基线都是在 mac 上测试的. windows 可能兼容存在问题. 
+ 
+## 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
+# examples 的依赖大多在 ghoshell-moss[contrib] 中, 没有拆分. 所以需要安装全部依赖. 
+uv sync --active --all-extras
+```
+
+## 3. 配置环境变量
+
+启动 demo 时需要配置模型和音频 (可选), 目前 alpha 版本的基线全部使用的是火山引擎.
+需要把环境变量配置上. 
+
+```bash
+# 复制 env 文件为目标文件. 
+cp examples/.env.example examples/.env
+
+# 修改相关配置项为真值. 
+vim examples/.env
+```
+
+配置时需要在火山引擎创建 大模型流式tts 服务. 不好搞定可以先设置 USE_VOICE_SPEECH 为 `no`
+
+## 4. 运行  moss agent
+
+```bash
+# 基于当前环境的 python 运行 moss_agent 脚本
+.venv/bin/python examples/moss_agent.py
+
+# 打开后建议问它, 你可以做什么. 
+```
+
+已知的问题: 
+1. 语音输入模块 alpha 版本没有开发完.  
+2. 目前使用的 simple agent 是测试专用, 打断的生命周期还有问题.
+3. 由于 shell 的几个控制原语未开发完, 一些行为阻塞逻辑会错乱. 
+4. interpreter 的生命周期计划 beta 完成, 现在交互的 ReACT 模式并不是最佳实践 (模型会连续回复)
+
+更多测试用例, 请看 examples 目录下的各个文件夹 readme. 
+
 
 ## Beta Roadmap
 

…kspace/configs/instructions/behaviors.md …e/configs/moss_instructions/behaviors.mdexamples/.workspace/configs/instructions/behaviors.md renamed to examples/.workspace/configs/moss_instructions/behaviors.md examples/.workspace/configs/instructions/behaviors.md renamed to examples/.workspace/configs/moss_instructions/behaviors.md

@@ -32,6 +32,20 @@
 
 我希望你也对这样的愿景感兴趣，我们能共同成长。
 
+## 你能做什么
+
+我们希望你能帮助用户理解 MOSS 架构的原理. 所以我们在 README.md 里会引导用户和你交互.
+但是用户肯定不知道要和你说什么. 所以你先需要了解我们为你提供的能力想要展示哪些功能: 
+
+1. 给你一个 hub, 让你展示未来 AIOS 是可以用  打开/关闭  的方式将 channel 作为 app 的控制中心来使用. 同时是树形的渐进式披露.
+2. 当你同时打开视觉模块, 和数字躯体模块, 这两个模块是完全离散, 可拆卸的. 但你却通过 channel 拥有了上下文的组合, 从而能够将之联动.
+3. 其它的辅助工具是让你可以帮助用户了解这个项目的. 不要一次性打开太多. 
+4. 有几个工具我们隐藏了开关, 只有用户开启你才能使用. 比如用 jxa 控制 mac 上的软件. 毕竟这个功能有点过于强大了. 
+5. 我们在 beta 版本 (当前是 alpha) 会给你配备更多的能力, 比如 ppt, 阅读你自己的源码, 阅读你的项目文档等等.  
+6. 由于现在架构的 ReACT 范式还没实现好, 你可能在做完一个操作后, 又看到了 command 的操作结果. 这时不要重复执行动作, 只需要询问用户还有什么需要即可. 
+
+你需要引导用户来了解你的能力. 但是, 请注意不要急于直接打开能力, 而是和用户先进行沟通, 告知会发生什么, 确认后才执行比较好 (用户不会被意外冒犯).
+
 ## 基本模式
 
 你需要遵循的行为模式如下：

…orkspace/configs/instructions/persona.md …ace/configs/moss_instructions/persona.mdexamples/.workspace/configs/instructions/persona.md renamed to examples/.workspace/configs/moss_instructions/persona.md examples/.workspace/configs/instructions/persona.md renamed to examples/.workspace/configs/moss_instructions/persona.md

@@ -1,4 +1,3 @@
-# from class: demo.linxu_demo.channels.no_ppt_channel:NoPPTConfig
 ppt_list:
   - dirname: example
     description: 一个测试的ppt，介绍了人和AI的关系

examples/.workspace/configs/no_ppt.yaml

@@ -1,4 +1,8 @@
 web_list:
+  - id: "moss-repository"
+    url: "https://github.com/GhostInShells/MOSShell"
+    description: |-
+      MOSShell 当前项目库 github 地址
   - id: "moss-architecture-doc"
     url: "https://ycnrlabqki3v.feishu.cn/wiki/QCKUwAX7tiUs4GkJTkLcMeWqneh"
     description: "MOSS (模型可操作系统 - 流式代码解释器) 系统原理与应用综述"
@@ -14,25 +18,25 @@ web_list:
   - id: "ghostos-repository"
     url: "https://github.com/GhostInShells/ghostos"
     description: |-
-      GhostOS 代码仓库地址，是用来做 ghost in shells 架构思想探索的验证库。
+      GhostOS 代码仓库地址，是 2024 年用来做 ghost in shells 架构思想探索的验证库。目前已经终止迭代.
   - id: "moss-article"
     url: "https://arxiv.org/abs/2409.16120"
     description: |-
-      这是我们24年研究 AI 通过全代码驱动系统的相关论文预印版
+      这是我们24年研究 AI 通过全代码驱动系统的相关论文预印版. 是第一代 MOSS 架构思想. 现在是第二代. 
   - id: "机械臂演示视频汇总"
     url: "https://ycnrlabqki3v.feishu.cn/wiki/FiOOwBKG0iSEONkGRKvcyDHOnaf"
     description: |-
-      这里提供了我们 6dof jetarm 机械臂积累的展示视频
+      这里提供了我们 6dof jetarm 机械臂积累的展示视频. 是当前 MOSShell 的展示视频之一.
   - id: "20年语音交互视频展示视频"
     url: "https://www.bilibili.com/video/BV1tK4y1a75B/?share_source=copy_web&vd_source=d16eb4aa121a670f02fa576471d30a41"
     description: |-
-      朱明 20年项目中，通过微信语音控制网页，通过网页的小视频做对话式视频的案例
+      ZhuMing 20年项目中，通过微信语音控制网页，通过网页的小视频做对话式视频的案例. 是 GhostInShells 项目理念起点的示例之一.
   - id: "20年语音交互控制网页游戏视频"
     url: "https://www.bilibili.com/video/BV1tK4y1a75B/?share_source=copy_web&vd_source=d16eb4aa121a670f02fa576471d30a41&t=290"
     description: |-
-      朱明 20年项目中，通过微信语音控制网页 “方向迷宫” 小游戏的视频，将网页游戏和微信进行了跨设备的同构。
+      ZhuMing 20年项目中，通过微信语音控制网页 “方向迷宫” 小游戏的视频，将网页游戏和微信进行了跨设备的同构。 是 MOSS 控制具身智能思路起点的示例之一.
   - id: "20年关于自然语言编程的视频"
     url: "https://www.bilibili.com/video/BV1tK4y1a75B/?share_source=copy_web&vd_source=d16eb4aa121a670f02fa576471d30a41&t=672"
     description: |-
-      朱明 20年项目中，讨论到未来实现自然语言编程，对话式编程的设想。 
+      ZhuMing 20年项目中，讨论到未来实现自然语言编程，对话式编程的设想。 是 MOSS 代码驱动理念起点的示例之一.
     

examples/.workspace/configs/web.yaml

@@ -3,31 +3,3 @@
 本目录用来存放各种 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/README.md

@@ -12,6 +12,14 @@
 import live2d.v3 as live2d
 import pygame
 from ghoshell_container import Container
+
+current_dir = os.path.dirname(os.path.abspath(__file__))
+try:
+    import miku_channels
+except ImportError:
+    # 加载当前路径.
+    sys.path.append(current_dir)
+
 from miku_channels.arm import left_arm_chan, right_arm_chan
 from miku_channels.body import body_chan
 from miku_channels.elbow import left_elbow_chan, right_elbow_chan
@@ -21,40 +29,18 @@
 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 miku_provider import init_live2d, init_pygame
 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
 WIDTH = 600
 HEIGHT = 800
 
+model: live2d.LAppModel | None = None
 
 # 初始化Pygame和Live2D
-def init_pygame():
-    pygame.init()
-    display = (WIDTH, HEIGHT)
-    screen = pygame.display.set_mode(display, pygame.DOUBLEBUF | pygame.OPENGL)
-    pygame.display.set_caption("Digital Human Demo with PyChannel")
-    return screen, display
-
-
-# 初始化Live2D模型
-def init_live2d(model_path: str, container: Container):
-    global model
-    live2d.init()
-    live2d.glInit()
-    model = live2d.LAppModel()
-    model.LoadModelJson(model_path)
-    model.Resize(WIDTH, HEIGHT)
-    # model.SetAutoBlinkEnable(False)
-    # model.SetAutoBreathEnable(True)
-    container.bind(live2d.LAppModel, model)
 
 
 async def speak(duration: float = 5.0, speed: float = 1.0, max_open: float = 0.9, min_open: float = 0.0):
@@ -160,9 +146,10 @@ async def speaking():
 
 async def run_agent_and_render(container: Container, speech: Speech | None = None):
     # 初始化 Pygame 和 Live2D
+    global model
     screen, display = init_pygame()
     model_path = join(dirname(__file__), "model/miku.model3.json")
-    init_live2d(model_path, container)
+    model = init_live2d(model_path, container)
 
     # 保持窗口打开，直到用户关闭
     running = True
@@ -215,7 +202,7 @@ async def run_agent_and_render(container: Container, speech: Speech | None = Non
 def main():
     # 运行异步主函数
     with workspace_container(WORKSPACE_DIR) as container:
-        speech = get_example_speech(container)
+        speech = get_example_speech(container, default_speaker='saturn_zh_female_keainvsheng_tob')
         asyncio.run(run_agent_and_render(container, speech))