内容
# livekit-agent-simulator
独立的MCP服务器和命令行界面（`lk-sim`），可与**任何LiveKit语音代理**对接，通过AI模拟呼叫者（Gemini Live）并记录完整的法医行为日志——转录文本、工具事件、流程事件、房间事件——所有事件均按时间顺序记录。
**零接触：** 被测试的代理是一个黑盒。模拟器只需要代理注册的`agent_name`；它永远不会读取或修改目标项目的代码、`.env`或模型配置。
命令行界面和MCP公开**相同的公共操作**（共享`ops.py`）。没有重复的“运行vs执行”路径——使用`execute_*`进行验证然后运行。
## 工作原理
1. 读取`<your-repo>/.agent-sim/config.yaml`（LiveKit凭证 + `agent_name` + 模拟器语音）。
2. 创建一个全新的房间`lk-sim-<run-id>`，并通过`RoomAgentDispatch`调度代理。
3. 作为参与者`lk-sim-caller`加入，桥接音频与Gemini Live会话（`gemini-3.1-flash-live-preview`）播放场景角色。
4. 从房间内部观察一切：`lk.transcription`文本流、自定义数据主题（当配置时）、音频时间、打断、沉默。
5. 编写`reports/<run-id>/`——`events.jsonl`、`timeline.md`、`summary.json`、`meta.json`，可选`conversation.wav`——并镜像到`runs.sqlite`。
6. 可选的LLM评判器（`gemini-2.5-flash`）根据场景的PassCriteria对转录文本+工具范围进行评分。
## 安装（用户机器）
```bash
curl -fsSL https://raw.githubusercontent.com/quangdang46/livekit-agent-simulator/main/install.sh | bash
# 需要uv（或pipx）。然后：
lk-sim guide
lk-sim web --root /path/to/target # 不需要Node——播放器已预构建到软件包中
```
### 报告播放器（维护者）
来源：`web/`（Vite + TypeScript）。用户从不运行此程序。
```bash
pnpm --dir web install
pnpm --dir web build # → templates/report-player/（由lk-sim web提供）
pnpm --dir web dev # HMR；代理/api + /runs → lk-sim web on :8765
```
## 快速开始
```bash
# 在要测试的仓库中（代理工作器必须运行； 在配置文件中设置`agent_name`）：
lk-sim init --root /path/to/target
# → 搭建.agent-sim/（gitignored）——填写config.yaml
lk-sim preflight --root /path/to/target
lk-sim execute smoke-hello --root /path/to/target
lk-sim report <run-id> --root /path/to/target
lk-sim web --root /path/to/target # 音频+转录文本播放器（Ctrl+C停止）
```
## Cursor MCP 配置
```json
{
"mcpServers": {
"livekit-agent-simulator": {
"command": "uv",
"args": ["run", "--directory", "/abs/path/livekit-agent-simulator", "livekit-agent-simulator-mcp"]
}
}
}
```
## 公共操作（命令行界面↔ MCP）
| 命令行界面 | MCP 工具 | 目的 |
|-----|----------|---------|
| `init` | `init_project` | 搭建`.agent-sim/` + gitignore |
| `guide` | `guide` | 按需设置/操作指南（markdown） |
| `web` | `web` | 本地报告播放器（音频+转录文本同步） |
| `preflight` | `preflight` | 配置 + LiveKit 连接性 |
| `scenarios` | `list_scenarios` | 列出`scenarios/*.jsonl` |
| `plugins` | `list_plugins` | 验证插件 |
| `validate` | `validate_scenario` | 模式 + 校验 |
| `export` | `export_scenario` | 解析场景JSON |
| `scenario-init` | `init_scenario` | 搭建`.jsonl`并带有`//`指南 + 示例 |
| `execute` | `execute_scenario` | 验证然后运行一个JSONL场景 |
| `execute-all` | `execute_scenarios` | 批量（可选ID/标签） |
| `execute-dict` | `execute_scenario_dict` | 验证然后运行内存字典 |
| `status` | `get_run_status` | SQLite 运行状态 |
| `log` | `get_run_log` | 过滤的`events.jsonl` |
| `report` | `get_run_report` | 摘要 + 裁决 + 音频路径 |
| `compare` | `compare_runs` | 差异两个运行 |
| `runs` | `list_runs` | 运行历史 |
## 文档
- [AGENTS.md](AGENTS.md) — AI代理规则（研究循环，包边界）
- [docs/smoke-test.md](docs/smoke-test.md) — 首次端到端运行
- [docs/portability.md](docs/portability.md) — 消费者特定调度/观察设置
- [docs/plugins.md](docs/plugins.md) — 验证插件 + Python API
## CI / 发布
| 工作流 | 触发 | 执行操作 |
|----------|---------|--------------|
| [CI](.github/workflows/ci.yml) | PR / 推送到 `main` | `pytest`（Python 3.10 + 3.12），`lk-sim --help`，`uv build` |
| [发布](.github/workflows/release.yml) | 标签 `v*` | 测试 → 构建 → GitHub 发布（轮子 + sdist）；如果设置了 `PYPI_API_TOKEN` 密钥，则发布到 PyPI |
本地检查：
```bash
uv sync --extra dev
uv run pytest -q
uv build
```
发布：
```bash
git tag v0.1.0
git push origin v0.1.0
```
