完善spec：本地解析推送结构化数据 & Django Admin每日导出
- 架构调整：三节点本地解析JSONL，推送结构化JSON而非原始文件 - API改为bulk_upsert接口，接收sessions/messages/tool_calls数组 - 推送脚本改用纯标准库，由OpenClaw cron job每天凌晨触发 - 新增Admin按时间范围查询对话和Daily Markdown导出功能 - Markdown导出精简thinking，保留user/assistant对话和tool调用 - 非技术决策：原始JSONL保留在各节点本地 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -21,22 +21,24 @@ OpenClaw 多 Agent 系统运行于 Mac Mini + Ubuntu1 + Ubuntu2 三节点，每
|
|||||||
## 2. 架构总览
|
## 2. 架构总览
|
||||||
|
|
||||||
```
|
```
|
||||||
┌─────────────────┐ push ┌──────────────────┐
|
┌─────────────────┐ parse push ┌──────────────────┐
|
||||||
│ Ubuntu1 │ ────────► │ Mac Mini │
|
│ Ubuntu1 │ ──────────► │ Mac Mini │
|
||||||
└─────────────────┘ │ │
|
└─────────────────┘ structured data │ │
|
||||||
┌─────────────────┐ push │ Django + DRF │
|
┌─────────────────┐ (JSON) push │ Django + DRF │
|
||||||
│ Ubuntu2 │ ────────► │ │
|
│ Ubuntu2 │ ──────────► │ │
|
||||||
└─────────────────┘ │ ├─ API接收 │
|
└─────────────────┘ structured data │ ├─ API接收 │
|
||||||
┌─────────────────┐ local │ ├─ 解析引擎 │
|
┌─────────────────┐ (JSON) push │ ├─ 数据写入 │
|
||||||
│ Mac Mini (本地) │ ────────► │ ├─ Django Admin │
|
│ Mac Mini (本地) │ ──────────────────► │ ├─ Django Admin │
|
||||||
└─────────────────┘ └────┬─────────────┘
|
└─────────────────┘ structured data └────┬─────────────┘
|
||||||
│
|
(JSON) │
|
||||||
┌─────┴─────────────┐
|
┌─────┴─────────────┐
|
||||||
│ PostgreSQL + │
|
│ PostgreSQL + │
|
||||||
│ TimescaleDB │
|
│ TimescaleDB (NAS) │
|
||||||
└───────────────────┘
|
└───────────────────┘
|
||||||
```
|
```
|
||||||
|
|
||||||
|
各节点解析脚本负责：读取 JSONL → 本地解析为结构化数据（sessions / messages / tool_calls）→ POST JSON 到 Django API → 服务端幂等写入数据库。Django 服务端不再做 JSONL 解析。
|
||||||
|
|
||||||
## 3. 数据源
|
## 3. 数据源
|
||||||
|
|
||||||
### 3.1 JSONL 文件结构
|
### 3.1 JSONL 文件结构
|
||||||
@@ -161,23 +163,63 @@ class ToolCall(models.Model):
|
|||||||
|
|
||||||
## 5. 推送机制
|
## 5. 推送机制
|
||||||
|
|
||||||
### 5.1 推送脚本
|
### 5.1 解析与推送脚本
|
||||||
|
|
||||||
Python 脚本部署在所有三个节点。
|
Python 脚本部署在所有三个节点（Mac Mini / Ubuntu1 / Ubuntu2）。
|
||||||
|
|
||||||
```
|
```
|
||||||
Usage: python sync_sessions.py --remote-url http://macmini:8000/api/sessions/upload/
|
Usage: python sync_sessions.py --remote-url http://macmini:8000/api/sessions/bulk_upsert/
|
||||||
```
|
```
|
||||||
|
|
||||||
- 扫描各节点的 sessions 目录
|
**职责**：
|
||||||
- 维护本地 `.sync_state` 文件，记录已推送文件的 mtime
|
1. 扫描本地 `agents/{agent_name}/sessions/` 目录
|
||||||
- 筛选条件：只推 mtime 较新的 `.jsonl` 文件（排除 `.deleted.`）
|
2. 读取 `.sync_state` 文件，找出新增/变更的 `.jsonl` 文件（排除 `.deleted.`）
|
||||||
- 用 multipart/form-data 上传，同时发送 `agent_name` 和 `source_node`
|
3. 本地解析每个 JSONL：逐行 JSON → 提取 session 元信息 / messages / tool_calls
|
||||||
- 上传成功后更新 `.sync_state`
|
4. POST 结构化 JSON 到 Django API（`POST /api/sessions/bulk_upsert/`）
|
||||||
|
5. 上传成功后更新 `.sync_state`
|
||||||
|
|
||||||
|
**脚本特点**：
|
||||||
|
- 纯 Python 标准库，无外部依赖
|
||||||
|
- 本地完成解析，服务端只负责结构化写入
|
||||||
|
- 幂等：服务端根据 `session_id + agent_name` 判断重复，重复推送跳过
|
||||||
|
|
||||||
|
**请求体示例**：
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"agent_name": "xingyao",
|
||||||
|
"source_node": "macmini",
|
||||||
|
"sessions": [
|
||||||
|
{
|
||||||
|
"session_id": "xxx-xxx",
|
||||||
|
"session_version": 1,
|
||||||
|
"model_provider": "anthropic",
|
||||||
|
"model_id": "claude-sonnet-4-6",
|
||||||
|
...
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"messages": [
|
||||||
|
{
|
||||||
|
"session_id": "xxx-xxx",
|
||||||
|
"message_id": "yyy",
|
||||||
|
"role": "user",
|
||||||
|
...
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"tool_calls": [
|
||||||
|
{
|
||||||
|
"session_id": "xxx-xxx",
|
||||||
|
"message_id": "yyy",
|
||||||
|
"tool_call_id": "call_function_xxx_0",
|
||||||
|
"tool_name": "exec",
|
||||||
|
...
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
### 5.2 定时任务
|
### 5.2 定时任务
|
||||||
|
|
||||||
各节点 crontab 每天凌晨 2:00 执行一次：
|
各节点由 OpenClaw cron job 每天凌晨 2:00 触发一次：
|
||||||
|
|
||||||
```
|
```
|
||||||
0 2 * * * cd /path/to/script && python sync_sessions.py
|
0 2 * * * cd /path/to/script && python sync_sessions.py
|
||||||
@@ -185,16 +227,20 @@ Usage: python sync_sessions.py --remote-url http://macmini:8000/api/sessions/upl
|
|||||||
|
|
||||||
## 6. API 设计
|
## 6. API 设计
|
||||||
|
|
||||||
### POST /api/sessions/upload/
|
### POST /api/sessions/bulk_upsert/
|
||||||
|
|
||||||
接收 JSONL 文件上传。
|
接收结构化 JSON 批量写入。
|
||||||
|
|
||||||
```
|
```
|
||||||
Content-Type: multipart/form-data
|
Content-Type: application/json
|
||||||
Fields:
|
Body:
|
||||||
- file: JSONL 文件内容
|
{
|
||||||
- agent_name: str
|
"agent_name": "xingyao",
|
||||||
- source_node: str
|
"source_node": "macmini",
|
||||||
|
"sessions": [...],
|
||||||
|
"messages": [...],
|
||||||
|
"tool_calls": [...]
|
||||||
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
响应：
|
响应：
|
||||||
@@ -202,13 +248,13 @@ Fields:
|
|||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"status": "ok",
|
"status": "ok",
|
||||||
"session_id": "xxx",
|
"sessions_upserted": 3,
|
||||||
"messages_parsed": 42,
|
"messages_upserted": 42,
|
||||||
"tool_calls_parsed": 15
|
"tool_calls_upserted": 15
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
幂等：根据 `session_id + agent_name` 组合判断重复，已存在则跳过。
|
幂等：根据 `session_id + agent_name` 组合判断重复，已存在则跳过。整个请求在一个事务中写入，任一失败则全部回滚。
|
||||||
|
|
||||||
## 7. Django Admin
|
## 7. Django Admin
|
||||||
|
|
||||||
@@ -217,7 +263,7 @@ Fields:
|
|||||||
- 可排序列：时间、Agent、模型、token 总量、message 数量
|
- 可排序列：时间、Agent、模型、token 总量、message 数量
|
||||||
- 侧边栏筛选：agent_name、source_node、model_id、日期范围
|
- 侧边栏筛选：agent_name、source_node、model_id、日期范围
|
||||||
- 搜索框：session_id、cwd
|
- 搜索框：session_id、cwd
|
||||||
- 自定义列表操作：查看完整对话原文（渲染 JSONL 为人类可读 HTML）
|
- 查看完整对话原文（渲染为人类可读 HTML）
|
||||||
|
|
||||||
### 7.2 Session 详情页（Inline）
|
### 7.2 Session 详情页（Inline）
|
||||||
|
|
||||||
@@ -238,21 +284,73 @@ Fields:
|
|||||||
- 按 tool_name、is_error、exit_code 筛选
|
- 按 tool_name、is_error、exit_code 筛选
|
||||||
- 排序：duration_ms、token 消耗
|
- 排序：duration_ms、token 消耗
|
||||||
|
|
||||||
|
### 7.5 按时间范围查询对话
|
||||||
|
|
||||||
|
- Admin 增加自定义视图：`/admin/openclaw/daily/`
|
||||||
|
- 支持选择日期范围 + agent_name
|
||||||
|
- 按 session 分组，按时间顺序展示完整对话内容
|
||||||
|
- 每条消息区分 user / assistant / toolResult，去掉 thinking 部分
|
||||||
|
- 人类可读 HTML，支持折叠/展开
|
||||||
|
|
||||||
|
### 7.6 Daily 复盘导出（Markdown）
|
||||||
|
|
||||||
|
- Admin Session 列表页增加自定义 Action：选中 sessions → 导出 Markdown
|
||||||
|
- 按天为单位生成 `daily-report-{YYYY-MM-DD}.md` 文件并下载
|
||||||
|
- 精简规则：
|
||||||
|
- 去掉所有 `thinking` 内容块
|
||||||
|
- 保留 agent 纯文本回复
|
||||||
|
- 保留 user 原始输入
|
||||||
|
- 保留 tool 调用（工具名 + 参数摘要 + 执行结果文本）
|
||||||
|
- 保留 token 消耗、模型信息等摘要统计
|
||||||
|
- Markdown 格式示例：
|
||||||
|
```markdown
|
||||||
|
# Daily Report: 2026-04-05
|
||||||
|
|
||||||
|
## Session: abc12345 (Agent: xingyao)
|
||||||
|
**模型**: claude-sonnet-4-6 | **Token**: 45,230
|
||||||
|
|
||||||
|
### 10:23 User
|
||||||
|
帮我看看这个 bug...
|
||||||
|
|
||||||
|
### 10:23 Assistant
|
||||||
|
问题出在第 45 行...
|
||||||
|
|
||||||
|
### 10:24 Assistant → [Tool: exec]
|
||||||
|
`grep -n "bug" file.py`
|
||||||
|
**结果**: 匹配到 3 行
|
||||||
|
```
|
||||||
|
|
||||||
## 8. 解析引擎
|
## 8. 解析引擎
|
||||||
|
|
||||||
同步解析，流程：
|
### 8.1 客户端解析（sync_sessions.py）
|
||||||
|
|
||||||
|
运行在各节点，负责读取 JSONL 并提取结构化数据：
|
||||||
|
|
||||||
```
|
```
|
||||||
接收文件 → 逐行 JSON → 构建事件流 →
|
逐行读取 JSONL →
|
||||||
提取 session 元信息 →
|
提取 session 事件（id、version、cwd）→
|
||||||
写入 Session →
|
跟踪 model_change / thinking_level_change 状态 →
|
||||||
按 parentId 树关系遍历 message →
|
遍历 message 事件 →
|
||||||
写入 Message（提取 assistant usage、toolResult 元信息）→
|
提取 assistant usage（tokens、cost）→
|
||||||
提取 toolCall 内容块 →
|
提取 content 数组中的 text / toolCall 块 →
|
||||||
写入 ToolCall（关联 message 和对应的 toolResult）
|
遍历 toolResult 事件 → 关联到 toolCall
|
||||||
|
构建 JSON 批量提交
|
||||||
```
|
```
|
||||||
|
|
||||||
解析失败处理：单条 JSON 行解析失败记录日志但不中断，整文件解析失败时回滚整个事务。
|
### 8.2 服务端写入（Django API）
|
||||||
|
|
||||||
|
接收客户端推送的结构化 JSON：
|
||||||
|
|
||||||
|
```
|
||||||
|
验证 agent_name + source_node →
|
||||||
|
批量 upsert Session（幂等：session_id + agent_name 去重）→
|
||||||
|
批量写入 Message（外键关联 Session）→
|
||||||
|
批量写入 ToolCall（外键关联 Message）→
|
||||||
|
更新 Session 聚合字段（token 总数、cost、message count 等）→
|
||||||
|
返回写入结果
|
||||||
|
```
|
||||||
|
|
||||||
|
整个写入在一个事务中完成，任一失败则全部回滚。
|
||||||
|
|
||||||
## 9. 技术栈
|
## 9. 技术栈
|
||||||
|
|
||||||
@@ -399,9 +497,9 @@ docker compose run --rm web python manage.py migrate
|
|||||||
|
|
||||||
启用前需将 `nginx/nginx.conf.placeholder` 重命名为 `nginx.conf` 并根据实际域名和证书路径修改配置。
|
启用前需将 `nginx/nginx.conf.placeholder` 重命名为 `nginx.conf` 并根据实际域名和证书路径修改配置。
|
||||||
|
|
||||||
## 11. 非技术决策
|
## 12. 非技术决策
|
||||||
|
|
||||||
- 不接收 `.deleted.` 文件
|
- 不接收 `.deleted.` 文件
|
||||||
- 幂等上传：同一 session 重复推送时跳过（基于 session_id + agent_name 组合键）
|
- 幂等推送：同一 session 重复推送时跳过（基于 session_id + agent_name 组合键）
|
||||||
- Mac Mini 本地 session 同样通过推送脚本入库（保证统一流程，不走特殊路径）
|
- Mac Mini 本地 session 同样通过推送脚本入库（保证统一流程，不走特殊路径）
|
||||||
- 原始 JSONL 保留一份到指定归档路径，供原始数据追溯
|
- 原始 JSONL 保留在各节点本地，不推送到 Django 服务端
|
||||||
|
|||||||
Reference in New Issue
Block a user