# 会话跟踪格式

Claude Code、Codex、Pi、Hermes Agent 和 Factory Droid 的 Agent traces 开箱即用（参见 [Agent Traces](./agent-traces)）。如果您自行构建 harness，可以按照下文描述的 **Session Trace Simple Format (STS-Format)** 编写其会话，使其在相同的查看器中渲染。

**会话跟踪简单格式（STS-Format）** 是一种 [JSONL](https://jsonlines.org) 文件（每行一个 JSON 对象），Hugging Face Hub 会检测该文件并在其跟踪查看器中渲染。它通过一个头部行后跟若干消息行来捕获单个智能体/聊天会话。

## 1. 会话标题（第一行）

```json
{ "type": "session", "harness": "my-agent", "id": "b1a2c3", "name": "Implementing a new API" }
```

| field     | 必需 | notes                                             |
| --------- | -------- | ------------------------------------------------- |
| `type`    | 是的      | 必须为 `"session"`                               |
| `harness` | 是的      | 生成该跟踪记录的**harness 的 id** |
| `id`      | 是的      | 唯一的会话 ID                                 |
| `name`    | no       | 人类可读的标题                              |
| …         | no       | 任何额外的元数据都是允许的，但会被忽略         |

`harness` 是关键字段：它是 **harness 的 id**，用于告知 Hub 该为会话使用哪个渲染器、图标和标签。当前已识别的 id 为：`llama.app`。在此处添加新的 harness 标识符非常容易。

> 正在构建自己的测试框架？请通知我们，我们将为其添加图标和标签，以便您的会话以您的品牌样式呈现。

## 2. 消息（后续每一行）

每一行都是信封中的一条消息：

```json
{ "type": "message", "message": { "role": "assistant", "content": "…" } }
```

`message` 对象：

| field              | 必需 | notes                                                                                                  |
| ------------------ | -------- | ------------------------------------------------------------------------------------------------------ |
| `role`             | 是的      | `"user"` · `"assistant"` · `"system"` · `"tool"`                                                       |
| `content`          | 是的      | 文本（可以为空）                                                                                    |
| `reasoningContent` | no       | 模型推理，显示为独立的思考块                                                    |
| `toolCalls`        | no       | 助手工具调用：`[{ "id", "function": { "name", "arguments" } }]`（`arguments` 是一个 JSON 字符串） |
| `toolCallId`       | no       | 在 `role: "tool"` 消息上，将结果与其所响应的 `toolCalls[].id` 关联起来                       |
| `timestamp`        | no       | epoch 毫秒                                                                                     |
| `model`            | no       | 模型名称                                                                                             |

工具结果是带有 `role: "tool"` 并携带 `toolCallId` 的消息；查看器会将每个结果拼接在产生它的调用旁边。

### 示例

```jsonl
{"type":"session","harness":"my-agent","id":"abc123","name":"what time is it"}
{"type":"message","message":{"role":"user","content":"what time is it?"}}
{"type":"message","message":{"role":"assistant","content":"","toolCalls":[{"id":"t1","function":{"name":"get_time","arguments":"{}"}}]}}
{"type":"message","message":{"role":"tool","toolCallId":"t1","content":"2026-07-01T15:00:00Z"}}
{"type":"message","message":{"role":"assistant","content":"it is 15:00 UTC"}}
```

将生成的 `.jsonl` 上传到 [Dataset](https://huggingface.co/datasets) 或 [Storage Bucket](./storage-buckets)，即可在 trace viewer 中打开。

## 替代方案：Pi 的会话格式

如果您不想采用上述格式，可以输出 **Pi 的会话格式**（[session-format.md](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/session-format.md)），Hub 已支持该格式。在这种情况下，请在 Pi 的会话头行中也添加一个 `harness: "..."` 字段，以便 Hub 能够将追踪记录归属到您的 harness。