# Tracer 与 Playground

用一个配置字段保存每轮对话到磁盘，在本地查看器中读取。

Source: https://mmsp.penguin.ooo/zh/docs/tracing/

## 追踪对话

在配置中设置 `trace_id`。MMSP 会在每次响应后、返回 `stop` 事件前，自动保存完整的历史记录和配置。

```typescript
for await (const event of client.streamingResponseStateful({
  message: { role: "user", content_items: [{ type: "text.done", text: "Hello" }] },
  config: { trace_id: "agent1/conversation_001" },
})) {
  // ...
}
```

```python
async for event in client.streaming_response_stateful(
    message={"role": "user", "content_items": [{"type": "text.done", "text": "Hello"}]},
    config={"trace_id": "agent1/conversation_001"},
):
    pass
```

追踪文件默认保存在 `cache` 目录下，也可通过环境变量 `MMSP_CACHE_DIR` 指定其他目录。上面的 id 会生成两个文件：

| 文件 | 内容 |
| --- | --- |
| `cache/agent1/conversation_001.json` | 完整的历史和配置数据 |
| `cache/agent1/conversation_001.txt` | 可读的对话文本记录 |

`.json` 和 `.txt` 直接接在 id 后面，所以 `v1.2` 会写成 `v1.2.json`。id 为空、是绝对路径，或者经由 `..` 或符号链接指向缓存目录之外时，请求发出之前就会抛出 `UnsupportedParameterError`。

无需数据库，也无需额外配置。

## 查看追踪

启动查看器，然后访问 `http://127.0.0.1:25750`。

```typescript
import { Tracer } from "@prismshadow/mmsp/integration/tracer";

new Tracer().startWebServer("127.0.0.1", 25750);
```

```python
from mmsp.integration.tracer import Tracer

Tracer().start_web_server(host="127.0.0.1", port=25750)
```

也可以在 shell 中启动（TypeScript 脚本在仓库的 `src_ts` 目录下运行）：

```bash
npm run tracer
```

```bash
python -m mmsp.integration.tracer --cache_dir ./cache --host 127.0.0.1 --port 25750
```

## Playground

Playground 是一个本地聊天页面，用于手动测试模型：选择模型、设置配置、发送消息、观察事件。选择模型后，会自动填入它的客户端类型和该客户端访问的端点（环境变量里的，或厂商官方的）；改动其中任意一项，就能经由另一种协议或网关试用这个模型。List models 会把端点提供的模型加进列表，每一项记住列出时的客户端类型和端点，以及最近用的 key；只换了 key 再次列出时不新增。向另一个模型、客户端类型或端点发送消息时，会在分隔线下开始新对话，分隔线以上的消息不会发送；只改 key 或额外 header 时对话继续。访问 `http://127.0.0.1:25751`；tracer 页面位于其旁边的 `/tracer/` 路径。`/server/` 路径上的 server 页面根据保存到配置文件的模型表启动 MMSP 服务端。

```typescript
import { startPlaygroundServer } from "@prismshadow/mmsp/integration/playground";

startPlaygroundServer("127.0.0.1", 25751);
```

```python
from mmsp.integration.playground import start_playground_server

start_playground_server(host="127.0.0.1", port=25751)
```

在 shell 中启动：

```bash
npm run playground
```

```bash
python -m mmsp.integration.playground --host 127.0.0.1 --port 25751
```