星枢：新增AgentBase项目需求文档(v1.0)

openclaw/xingshu/projects/agentbase-需求文档.md

@@ -0,0 +1,367 @@
+# 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 与比利哥的讨论*