diff --git a/docs/superpowers/specs/2026-04-05-openclaw-session-archival-design.md b/docs/superpowers/specs/2026-04-05-openclaw-session-archival-design.md index 4bd0133..8a69dca 100644 --- 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 服务端