# 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 与比利哥的讨论*