# qingbao_hermes_mcp

WSL Hermes 经 `cmd.exe` 调用的 Windows PPT 放映 MCP。

## 安装

```bat
py -3 -m pip install -r E:\work\qingbao_hermes_mcp\requirements.txt
```

## Hermes 配置（`~/.hermes/config.yaml`）

只需注册 MCP 入口，**业务配置在项目内 `config.yaml`**：

```yaml
mcp_servers:
  ppt-presenter-win:
    command: cmd.exe
    args: [/c, py, -3, E:\work\qingbao_hermes_mcp\server.py]
    timeout: 60
    enabled: true
```

## 项目配置（`E:\work\qingbao_hermes_mcp\config.yaml`）

修改此文件后重启 Hermes。

```yaml
presentations_dir: pptx_default_list   # 放映稿目录
state_dir: .                           # 日志/state 根目录（项目根）
speech_backend: local                  # inject | local

cloud:
  host: 47.96.7.235
  port: 8003
  robot_id: h1_003

logging:
  level: DEBUG
  stderr: false

tts:
  model_dir: models/vits-melo-tts-zh_en
```

完整字段见仓库内 [`config.yaml`](config.yaml)。

## MCP 工具

| 工具 | 说明 |
|------|------|
| `list_presentations` | 列出放映目录中的 PPT 文件 |
| `play_presentation` | 后台启动全屏放映（立即返回） |
| `get_playback_status` | 查询 idle/playing/paused 及 checkpoint |
| `pause_presentation` | 暂停口播，保持全屏当前页 |
| `resume_presentation` | 从 checkpoint 续播 |
| `stop_presentation` | 结束放映并 cleanup |
| `get_slide_context` | 获取指定页备注与分句（问答用） |

## 日志与状态

默认路径（`state_dir: .` 时）：

- 日志：`E:\work\qingbao_hermes_mcp\logs\worker.log`、`mcp.log`
- 状态：`E:\work\qingbao_hermes_mcp\playback_state.json`
- 锁：`E:\work\qingbao_hermes_mcp\playback.lock`

## 环境变量（可选覆盖）

测试或临时覆盖时使用；正常运行读 `config.yaml` 即可。

| 变量 | 对应 config 项 |
|------|----------------|
| `PPT_CONFIG_PATH` | 指定其它配置文件路径 |
| `PPT_STATE_DIR` | `state_dir` |
| `PRESENTATION_INCOMING_DIR` | `presentations_dir` |
| `PPT_SPEECH_BACKEND` | `speech_backend` |
| `PPT_LOG_LEVEL` | `logging.level` |

## 本地 TTS 模型

```bat
cd /d E:\work\qingbao_hermes_mcp\models
curl -SL -O https://github.com/k2-fsa/sherpa-onnx/releases/download/tts-models/vits-melo-tts-zh_en.tar.bz2
tar xf vits-melo-tts-zh_en.tar.bz2
```

`config.yaml` 中设 `speech_backend: local` 启用本地播放。

## 布局

```text
config.yaml               # 项目配置（主配置）
docs/
  PLAYBACK-FLOW.md        # 放映流程、失败暂停、风险说明
server.py
ppt_presenter/
  settings.py             # 读取 config.yaml
  mcp_server.py
  worker.py
  player.py
  ...
logs/
pptx_default_list/
models/vits-melo-tts-zh_en/
```

Skill：`~/.hermes/skills/productivity/ppt-presenter/SKILL.md`

## 放映流程与风险

详见 [`docs/PLAYBACK-FLOW.md`](docs/PLAYBACK-FLOW.md)（状态机、口播失败暂停、抢话时序、已知风险与日志排查）。