378 lines
12 KiB
Markdown
378 lines
12 KiB
Markdown
---
|
||
title: AgentBase 项目需求文档
|
||
source:
|
||
author: shenwei
|
||
published:
|
||
created:
|
||
description:
|
||
tags: []
|
||
---
|
||
|
||
# AgentBase 项目需求文档
|
||
|
||
> **文档版本：** v1.0
|
||
> **创建日期：** 2026-04-05
|
||
> **状态：** 待确认
|
||
> **负责人：** 星枢（协调）、星匠（实施）
|
||
> **项目位置：** `~/Workspace/agentbase/`
|
||
|
||
---
|
||
|
||
## 1. 项目概述
|
||
|
||
### 1.1 项目背景
|
||
|
||
OpenClaw 多 Agent 系统运行于 Mac Mini + Ubuntu1 + Ubuntu2 三节点，每日产生大量 session JSONL 文件。这些文件记录了 Agent 的完整对话历史、思考过程（thinking block）、工具调用（toolCall）等核心数据，目前以原始文件形式散落各服务器，无法高效查询。
|
||
|
||
### 1.2 项目目标
|
||
|
||
构建一套 **session 解析与归档系统**，将多节点、多 Agent 的 JSONL 会话数据统一解析入库，通过 Django Admin 提供可查询、可筛选、可追溯的 Web 管理界面。
|
||
|
||
### 1.3 核心价值
|
||
|
||
- **可审计**：任何 Agent 的任何操作记录可追溯
|
||
- **可分析**：按 Agent/时间/工具类型等多维度分析 Agent 行为模式
|
||
- **可优化**：基于真实调用数据优化 Agent 工作流
|
||
|
||
---
|
||
|
||
## 2. 系统范围
|
||
|
||
### 2.1 纳入系统
|
||
|
||
| 服务器 | 角色 | Session 根目录 |
|
||
|---|---|---|
|
||
| Mac Mini (`macmini`) | 中央控制节点 | `/Users/weishen/.openclaw/agents/` |
|
||
| Ubuntu1 (`ubuntu1`) | 准生产服务器 | `/home/shenwei/.openclaw/agents/` |
|
||
| Ubuntu2 (`ubuntu2`) | 开发服务器 | `/home/shenwei/.openclaw/agents/` |
|
||
|
||
### 2.2 纳入 Agent
|
||
|
||
`main` / `xingyao` / `xinghui` / `xingjiang` / `opencode` / `sisyphus`
|
||
|
||
### 2.3 纳入文件类型
|
||
|
||
| 文件类型 | 说明 | session_type |
|
||
|---|---|---|
|
||
| `*.jsonl` | 正常 session | `normal` |
|
||
| `*.jsonl.reset.*` | reset 快照 | `reset` |
|
||
| `*.jsonl.deleted.*` | 删除快照 | `deleted` |
|
||
| `*-topic-*.jsonl` | 线程 session | `topic` |
|
||
|
||
**忽略文件：** `sessions.json`（索引文件，不解析）
|
||
|
||
### 2.4 不纳入范围
|
||
|
||
- 实时流式解析（仅定时批量解析）
|
||
- Session 内容编辑（只读归档）
|
||
- 跨 Agent 关联分析（v1）
|
||
- 移动端界面
|
||
|
||
---
|
||
|
||
## 3. 功能需求
|
||
|
||
### 3.1 增量解析引擎
|
||
|
||
**FR-PARSE-001**：扫描指定服务器 + Agent 的 session 目录，列出所有符合类型的 `.jsonl` 文件
|
||
|
||
**FR-PARSE-002**：对每个文件，基于「文件路径 + mtime + size」判断是否需要重新解析（增量控制）
|
||
|
||
**FR-PARSE-003**：解析 JSONL 中的 `type:session` 记录，提取 session 元信息
|
||
|
||
**FR-PARSE-004**：解析 JSONL 中的 `type:message` 记录，提取消息内容、toolCall、thinking 等
|
||
|
||
**FR-PARSE-005**：对于 `type:message`，正确提取并拆分以下 content block 类型：
|
||
- `text` → 纯文本内容
|
||
- `thinking` → 思考过程文本
|
||
- `toolCall` → 工具调用（id/name/arguments）
|
||
- `toolResult` → 工具结果（toolCallId/content/isError）
|
||
|
||
**FR-PARSE-006**：从 message 元数据中提取 AI Provider / Model / API / Token 计数 / Cost 等计量数据
|
||
|
||
**FR-PARSE-007**：解析完成后更新 `parsed_files` 表（status: success / failed + error_message）
|
||
|
||
### 3.2 数据库存储
|
||
|
||
**FR-DB-001**：维护 `parsed_files` 表，记录每个已解析文件的元数据及状态（增量控制）
|
||
|
||
**FR-DB-002**：维护 `sessions` 表，记录每个 session 的根信息（去重依据：session_uuid + server + agent_id）
|
||
|
||
**FR-DB-003**：维护 `messages` 表，记录每条消息的完整信息（content 原文、提取字段、计量数据）
|
||
|
||
**FR-DB-004**：对 `messages` 表建立合理索引，支持按 `agent_id + timestamp` / `first_tool_call` / `session_id` 等常用查询模式
|
||
|
||
### 3.3 Django Admin 管理界面
|
||
|
||
**FR-ADMIN-001**：`Messages` 列表页
|
||
- 支持按 `agent_id` 过滤
|
||
- 支持按 `timestamp` 范围过滤
|
||
- 支持按 `role`（user/assistant/toolResult）过滤
|
||
- 支持按 `first_tool_call` 过滤
|
||
- 列表显示：id / message_uuid / role / text_preview（前100字符） / has_thinking / first_tool_call / timestamp
|
||
|
||
**FR-ADMIN-002**：`Messages` 详情页
|
||
- 显示 `content_blocks` 原始 JSON（完整展开）
|
||
- 显示 `thinking_text`（独立字段）
|
||
- 显示 `tool_calls_json`（完整展开）
|
||
- 显示所有计量字段（tokens / cost）
|
||
|
||
**FR-ADMIN-003**：`Sessions` 列表页
|
||
- 支持按 `server` / `agent_id` / `session_type` 过滤
|
||
- 列表显示：id / session_uuid / server / agent_id / session_type / started_at / message_count
|
||
|
||
**FR-ADMIN-004**：`ParsedFiles` 列表页
|
||
- 支持按 `server` / `agent_id` / `status` 过滤
|
||
- 列表显示：id / server / agent_id / file_path / file_mtime / status / parsed_at
|
||
- 支持按 `file_path` 搜索
|
||
|
||
### 3.4 定时任务
|
||
|
||
**FR-CRON-001**：每日定时（建议 00:05）自动执行解析任务，覆盖所有服务器、所有 Agent
|
||
|
||
**FR-CRON-002**：解析任务通过 OpenClaw cron 触发，调用 `scripts/parse_and_import.py`
|
||
|
||
### 3.5 命令行接口
|
||
|
||
**FR-CLI-001**：支持按服务器 + Agent 指定解析范围
|
||
```
|
||
python parse_and_import.py --server macmini --agent xingyao
|
||
```
|
||
|
||
**FR-CLI-002**：支持 `--dry-run` 参数，仅扫描文件不写入数据库
|
||
|
||
**FR-CLI-003**：支持 `--force` 参数，强制重新解析（忽略增量状态）
|
||
|
||
---
|
||
|
||
## 4. 非功能需求
|
||
|
||
### 4.1 性能
|
||
|
||
**NFR-PERF-001**：单次解析 10,000 条消息应在 60 秒内完成
|
||
|
||
**NFR-PERF-002**：Django Admin 列表页加载时间不超过 3 秒（百万级数据量下）
|
||
|
||
**NFR-PERF-003**：JSONL 文件逐行解析，不一次性加载到内存（流式处理）
|
||
|
||
### 4.2 可靠性
|
||
|
||
**NFR-RELI-001**：解析失败的文件需记录 `error_message`，不影响同批次其他文件
|
||
|
||
**NFR-RELI-002**：数据库操作使用事务保证一致性（单文件解析失败回滚）
|
||
|
||
**NFR-RELI-003**：重复解析同一文件（mtime+size 未变）应被跳过，不重复写入
|
||
|
||
### 4.3 可维护性
|
||
|
||
**NFR-MAIN-001**：数据库 schema 变更通过 Django Migration 管理
|
||
|
||
**NFR-MAIN-002**：配置信息（数据库连接）集中写在 `settings.py`，不散落多处
|
||
|
||
### 4.4 安全性
|
||
|
||
**NFR-SEC-001**：数据库凭据不硬编码在代码中，通过环境变量或 Django settings 管理
|
||
|
||
**NFR-SEC-002**：Django Admin 仅本地访问（暂不开放远程）
|
||
|
||
---
|
||
|
||
## 5. 数据库 Schema（摘要）
|
||
|
||
### 5.1 `parsed_files`
|
||
|
||
| 字段 | 类型 | 约束 |
|
||
|---|---|---|
|
||
| id | INT AUTO_INCREMENT | PK |
|
||
| server | VARCHAR(32) | NOT NULL |
|
||
| agent_id | VARCHAR(64) | NOT NULL |
|
||
| file_path | VARCHAR(512) | NOT NULL |
|
||
| file_mtime | BIGINT | NOT NULL |
|
||
| file_size | BIGINT | NOT NULL |
|
||
| status | VARCHAR(16) | NOT NULL |
|
||
| parsed_at | DATETIME | |
|
||
| error_message | TEXT | NULL |
|
||
|
||
**UNIQUE**：`(server, agent_id, file_path)`
|
||
|
||
### 5.2 `sessions`
|
||
|
||
| 字段 | 类型 | 约束 |
|
||
|---|---|---|
|
||
| id | INT AUTO_INCREMENT | PK |
|
||
| server | VARCHAR(32) | NOT NULL |
|
||
| agent_id | VARCHAR(64) | NOT NULL |
|
||
| session_uuid | VARCHAR(64) | NOT NULL |
|
||
| file_path | VARCHAR(512) | |
|
||
| session_type | VARCHAR(32) | |
|
||
| cwd | VARCHAR(512) | |
|
||
| started_at | DATETIME(3) | |
|
||
| first_message_at | DATETIME(3) | |
|
||
| last_message_at | DATETIME(3) | |
|
||
| message_count | INT | DEFAULT 0 |
|
||
|
||
**UNIQUE**：`(session_uuid, server, agent_id)`
|
||
|
||
### 5.3 `messages`
|
||
|
||
| 字段 | 类型 | 约束 |
|
||
|---|---|---|
|
||
| id | INT AUTO_INCREMENT | PK |
|
||
| session_id | INT | FK → sessions.id |
|
||
| server | VARCHAR(32) | NOT NULL |
|
||
| agent_id | VARCHAR(64) | NOT NULL |
|
||
| session_uuid | VARCHAR(64) | NOT NULL |
|
||
| message_uuid | VARCHAR(64) | NOT NULL |
|
||
| parent_message_uuid | VARCHAR(64) | NULL |
|
||
| role | VARCHAR(32) | NOT NULL |
|
||
| content_blocks | JSON | 原文 |
|
||
| text_preview | VARCHAR(512) | 摘要 |
|
||
| first_tool_call | VARCHAR(128) | NULL |
|
||
| tool_call_count | INT | DEFAULT 0 |
|
||
| tool_calls_json | JSON | 拆出 |
|
||
| thinking_text | TEXT | NULL |
|
||
| has_thinking | TINYINT | DEFAULT 0 |
|
||
| has_tool_calls | TINYINT | DEFAULT 0 |
|
||
| is_error | TINYINT | DEFAULT 0 |
|
||
| provider | VARCHAR(64) | |
|
||
| model | VARCHAR(128) | |
|
||
| api | VARCHAR(64) | |
|
||
| stop_reason | VARCHAR(64) | |
|
||
| input_tokens | INT | |
|
||
| output_tokens | INT | |
|
||
| cache_read_tokens | BIGINT | |
|
||
| cache_write_tokens | BIGINT | |
|
||
| total_tokens | INT | |
|
||
| cost_usd | DECIMAL(12,8) | |
|
||
| timestamp | DATETIME(3) | |
|
||
|
||
**INDEX**：`idx_agent_timestamp(agent_id, timestamp)` / `idx_first_tool_call(first_tool_call)` / `idx_session_id(session_id)` / `idx_role(role)`
|
||
|
||
---
|
||
|
||
## 6. 用户故事
|
||
|
||
### US-001：查询某 Agent 某天的完整对话
|
||
|
||
> 作为管理员，我想查看「星曜 2026-04-05 所有消息」，以便审计当天的操作记录
|
||
|
||
**验收标准：**
|
||
- 在 Messages 列表页输入 agent_id = xingyao + date range = 2026-04-05
|
||
- 返回结果按 timestamp 升序排列
|
||
- 每条结果显示 text_preview / has_thinking / first_tool_call
|
||
|
||
### US-002：查看某条消息的完整思考过程
|
||
|
||
> 作为管理员，我想查看某条消息的 thinking_text 和 toolCalls 详情，以便分析 Agent 的决策逻辑
|
||
|
||
**验收标准：**
|
||
- 点击任意消息进入详情页
|
||
- thinking_text 字段完整展示（无截断）
|
||
- tool_calls_json 以可读 JSON 格式展示
|
||
|
||
### US-003：查询某天某 Agent 执行过的所有 exec 命令
|
||
|
||
> 作为管理员，我想查看「星曜今天执行了哪些 exec 命令」，以便审计系统操作
|
||
|
||
**验收标准：**
|
||
- 过滤器 first_tool_call = exec + agent_id = xingyao + date range
|
||
- 返回结果包含每条 exec 的 text_preview（截取前512字符）
|
||
|
||
### US-004：追踪已解析文件状态
|
||
|
||
> 作为管理员，我想查看哪些 session 文件已成功解析、哪些失败，以便监控数据入库情况
|
||
|
||
**验收标准：**
|
||
- ParsedFiles 列表页显示所有文件的解析状态
|
||
- 失败条目显示 error_message
|
||
- 可按 server / agent_id / status 过滤
|
||
|
||
### US-005：增量同步最新 session
|
||
|
||
> 作为系统，我需要在每日定时任务中自动解析新增的 session 文件，不重复解析已入库且未变化的文件
|
||
|
||
**验收标准：**
|
||
- 同一文件 mtime+size 未变时，parsed_files 中 status=success 的记录被识别为「已解析」
|
||
- 新增文件或变化文件被正确解析入库
|
||
|
||
---
|
||
|
||
## 7. 技术选型
|
||
|
||
| 组件 | 选型 | 说明 |
|
||
|---|---|---|
|
||
| Web 框架 | Django 4.x | 成熟稳定，Admin 功能强大 |
|
||
| 数据库 | MariaDB | 与 NAS/现有基础设施兼容 |
|
||
| Python 版本 | 3.10+ | OpenClaw 生态兼容 |
|
||
| 部署位置 | Mac Mini | 与 OpenClaw 同节点，SSH 访问 ubuntu1/2 |
|
||
| ORM | Django ORM | 与 Django 深度集成 |
|
||
| 定时任务 | OpenClaw cron | 与现有任务系统统一 |
|
||
|
||
---
|
||
|
||
## 8. 项目目录结构
|
||
|
||
```
|
||
~/Workspace/agentbase/ # Git 仓库
|
||
├── manage.py
|
||
├── agentbase/ # Django 项目
|
||
│ ├── __init__.py
|
||
│ ├── settings.py # 数据库配置
|
||
│ ├── urls.py
|
||
│ └── wsgi.py
|
||
├── messages/ # Django App
|
||
│ ├── __init__.py
|
||
│ ├── models.py # 三张表
|
||
│ ├── admin.py # Admin 配置
|
||
│ ├── views.py # Web 视图
|
||
│ ├── urls.py
|
||
│ ├── management/
|
||
│ │ └── commands/
|
||
│ │ └── parse_sessions.py
|
||
│ └── templates/
|
||
│ └── messages/
|
||
├── scripts/
|
||
│ └── parse_and_import.py # CLI 入口脚本
|
||
├── tests/
|
||
├── requirements.txt
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## 9. 后续步骤（待用户确认后执行）
|
||
|
||
- [ ] 确认数据库部署位置（Mac Mini 本地 MariaDB？NAS？其他？）
|
||
- [ ] 确认数据库名称
|
||
- [ ] 创建 Git 仓库
|
||
- [ ] 初始化 Django 项目
|
||
- [ ] 实施解析引擎
|
||
- [ ] 配置 Django Admin
|
||
- [ ] 编写定时任务
|
||
- [ ] 编写测试
|
||
- [ ] 部署上线
|
||
|
||
---
|
||
|
||
## 10. 附录：典型查询参考
|
||
|
||
```sql
|
||
-- US-001：查某 Agent 某天所有消息
|
||
SELECT id, message_uuid, role, text_preview, has_thinking, first_tool_call, timestamp
|
||
FROM messages
|
||
WHERE agent_id = 'xingyao'
|
||
AND timestamp BETWEEN '2026-04-05 00:00:00' AND '2026-04-05 23:59:59'
|
||
ORDER BY timestamp;
|
||
|
||
-- US-003：查某 Agent 某天所有 exec 调用
|
||
SELECT m.id, m.timestamp, m.text_preview, m.session_uuid
|
||
FROM messages m
|
||
WHERE m.agent_id = 'xingyao'
|
||
AND m.timestamp BETWEEN '2026-04-05 00:00:00' AND '2026-04-05 23:59:59'
|
||
AND m.first_tool_call = 'exec';
|
||
```
|
||
|
||
---
|
||
|
||
*本文档由星枢整理，基于 2026-04-05 与比利哥的讨论*
|