完善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>
2026-04-05 13:32:24 +08:00
parent fc6d2c728f
commit 1d2531a71f
1 changed files with 145 additions and 47 deletions
--- a/docs/superpowers/specs/2026-04-05-openclaw-session-archival-design.md
+++ b/docs/superpowers/specs/2026-04-05-openclaw-session-archival-design.md
@@ -21,22 +21,24 @@ OpenClaw 多 Agent 系统运行于 Mac Mini + Ubuntu1 + Ubuntu2 三节点，每
 ## 2. 架构总览

 ```
-┌─────────────────┐    push    ┌──────────────────┐
-│ Ubuntu1         │ ────────►  │  Mac Mini        │
-└─────────────────┘            │                  │
-┌─────────────────┐    push    │  Django + DRF    │
-│ Ubuntu2         │ ────────►  │                  │
-└─────────────────┘            │  ├─ API接收       │
-┌─────────────────┐    local   │  ├─ 解析引擎      │
-│ Mac Mini (本地)  │ ────────►  │  ├─ Django Admin  │
-└─────────────────┘            └────┬─────────────┘
-                                    │
-                              ┌─────┴─────────────┐
-                              │ PostgreSQL +      │
-                              │ TimescaleDB       │
-                              └───────────────────┘
+┌─────────────────┐    parse    push    ┌──────────────────┐
+│ Ubuntu1         │ ──────────►         │  Mac Mini        │
+└─────────────────┘   structured data    │                  │
+┌─────────────────┐    (JSON)     push   │  Django + DRF    │
+│ Ubuntu2         │ ──────────►         │                  │
+└─────────────────┘   structured data    │  ├─ API接收       │
+┌─────────────────┐    (JSON)     push   │  ├─ 数据写入      │
+│ Mac Mini (本地)  │ ──────────────────►  │  ├─ Django Admin  │
+└─────────────────┘   structured data    └────┬─────────────┘
+                     (JSON)                   │
+                                        ┌─────┴─────────────┐
+                                        │ PostgreSQL +      │
+                                        │ TimescaleDB (NAS) │
+                                        └───────────────────┘
 ```

+各节点解析脚本负责：读取 JSONL → 本地解析为结构化数据（sessions / messages / tool_calls）→ POST JSON 到 Django API → 服务端幂等写入数据库。Django 服务端不再做 JSONL 解析。
+
 ## 3. 数据源

 ### 3.1 JSONL 文件结构
@@ -161,23 +163,63 @@ class ToolCall(models.Model):

 ## 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
- 筛选条件：只推 mtime 较新的 `.jsonl` 文件（排除 `.deleted.`）
- 用 multipart/form-data 上传，同时发送 `agent_name` 和 `source_node`
- 上传成功后更新 `.sync_state`
+**职责**：
+1. 扫描本地 `agents/{agent_name}/sessions/` 目录
+2. 读取 `.sync_state` 文件，找出新增/变更的 `.jsonl` 文件（排除 `.deleted.`）
+3. 本地解析每个 JSONL：逐行 JSON → 提取 session 元信息 / messages / tool_calls
+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 定时任务

-各节点 crontab 每天凌晨 2:00 执行一次：
+各节点由 OpenClaw cron job 每天凌晨 2:00 触发一次：

 ```
 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 设计

-### POST /api/sessions/upload/
+### POST /api/sessions/bulk_upsert/

-接收 JSONL 文件上传。
+接收结构化 JSON 批量写入。

 ```
-Content-Type: multipart/form-data
-Fields:
-  - file: JSONL 文件内容
-  - agent_name: str
-  - source_node: str
+Content-Type: application/json
+Body:
+  {
+    "agent_name": "xingyao",
+    "source_node": "macmini",
+    "sessions": [...],
+    "messages": [...],
+    "tool_calls": [...]
+  }
 ```

 响应：
@@ -202,13 +248,13 @@ Fields:
 ```json
 {
  "status": "ok",
-  "session_id": "xxx",
-  "messages_parsed": 42,
-  "tool_calls_parsed": 15
+  "sessions_upserted": 3,
+  "messages_upserted": 42,
+  "tool_calls_upserted": 15
 }
 ```

-幂等：根据 `session_id + agent_name` 组合判断重复，已存在则跳过。
+幂等：根据 `session_id + agent_name` 组合判断重复，已存在则跳过。整个请求在一个事务中写入，任一失败则全部回滚。

 ## 7. Django Admin

@@ -217,7 +263,7 @@ Fields:
 - 可排序列：时间、Agent、模型、token 总量、message 数量
 - 侧边栏筛选：agent_name、source_node、model_id、日期范围
 - 搜索框：session_id、cwd
- 自定义列表操作：查看完整对话原文（渲染 JSONL 为人类可读 HTML）
+- 查看完整对话原文（渲染为人类可读 HTML）

 ### 7.2 Session 详情页（Inline）

@@ -238,21 +284,73 @@ Fields:
 - 按 tool_name、is_error、exit_code 筛选
 - 排序：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.1 客户端解析（sync_sessions.py）
+
+运行在各节点，负责读取 JSONL 并提取结构化数据：

 ```
-接收文件 → 逐行 JSON → 构建事件流 → 
-提取 session 元信息 → 
-写入 Session → 
-按 parentId 树关系遍历 message → 
-写入 Message（提取 assistant usage、toolResult 元信息）→ 
-提取 toolCall 内容块 → 
-写入 ToolCall（关联 message 和对应的 toolResult）
+逐行读取 JSONL → 
+提取 session 事件（id、version、cwd）→ 
+跟踪 model_change / thinking_level_change 状态 →
+遍历 message 事件 →
+  提取 assistant usage（tokens、cost）→
+  提取 content 数组中的 text / toolCall 块 →
+遍历 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. 技术栈

@@ -399,9 +497,9 @@ docker compose run --rm web python manage.py migrate

 启用前需将 `nginx/nginx.conf.placeholder` 重命名为 `nginx.conf` 并根据实际域名和证书路径修改配置。

-## 11. 非技术决策
+## 12. 非技术决策

 - 不接收 `.deleted.` 文件
- 幂等上传：同一 session 重复推送时跳过（基于 session_id + agent_name 组合键）
+- 幂等推送：同一 session 重复推送时跳过（基于 session_id + agent_name 组合键）
 - Mac Mini 本地 session 同样通过推送脚本入库（保证统一流程，不走特殊路径）
- 原始 JSONL 保留一份到指定归档路径，供原始数据追溯
+- 原始 JSONL 保留在各节点本地，不推送到 Django 服务端