Update nexus: fix conflicts and sync local changes

openclaw/xingshu/projects/agentbase-design.md

@@ -1,303 +1,303 @@
----
-title: AgentBase 项目设计文档
-source:
-author: shenwei
-published:
-created:
-description:
-tags: []
----
-
-# AgentBase 项目设计文档
-
-> 设计日期：2026-04-05
-> 状态：已确认，等待实施
-> 项目位置：`~/Workspace/agentbase/`
-
----
-
-## 1. 项目概述
-
-**项目名**：agentbase
-**项目类型**：Django Web 应用 + 数据归档系统
-**核心目标**：遍历 OpenClaw Agent 的 session JSONL 文件，解析并保存到 MariaDB，通过 Django Admin 提供 Web 查询界面。
-
-**使用场景**：
-- 查找某个 Agent 在某天的所有对话记录
-- 查找某个 Agent 在处理任务时调用了哪些工具（特别是 `exec` 命令的具体内容）
-- 查看 Agent 的思考过程（thinking block）
-- 增量解析，只解析未处理过的文件
-
----
-
-## 2. 数据库设计
-
-### 2.1 服务器与 Agent 映射
-
-| 服务器 | 标识 | Session 根目录 |
-|--------|------|----------------|
-| Mac Mini | `macmini` | `/Users/weishen/.openclaw/agents/` |
-| Ubuntu1 | `ubuntu1` | `/home/shenwei/.openclaw/agents/` |
-| Ubuntu2 | `ubuntu2` | `/home/shenwei/.openclaw/agents/` |
-
-**纳入的 Agent**：main、xingyao、xinghui、xingjiang、opencode、sisyphus
-
-### 2.2 Session 文件类型
-
-所有 `.jsonl` 文件均需解析，包括：
-- `*.jsonl` — 正常 session
-- `*.jsonl.reset.*` — reset 快照
-- `*.jsonl.deleted.*` — 删除快照
-- `*-topic-*.jsonl` — 线程 session
-
-**session_type 判定**：
-- 文件名含 `.reset.` → `reset`
-- 文件名含 `.deleted.` → `deleted`
-- 文件名含 `-topic-` → `topic`
-- 默认 → `normal`
-
-**忽略文件**：`sessions.json`（索引文件，不解析）
-
-### 2.3 数据库 Schema
-
-#### 表：`parsed_files`（增量解析控制）
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `id` | INT AUTO_INCREMENT | 主键 |
-| `server` | VARCHAR(32) | 服务器标识 |
-| `agent_id` | VARCHAR(64) | Agent ID |
-| `file_path` | VARCHAR(512) | 文件绝对路径 |
-| `file_mtime` | BIGINT | 文件最后修改时间（Unix timestamp） |
-| `file_size` | BIGINT | 文件大小（字节） |
-| `status` | VARCHAR(16) | `pending` / `success` / `failed` |
-| `parsed_at` | DATETIME | 本次解析时间 |
-| `error_message` | TEXT | 失败时的错误信息（可空） |
-
-**UNIQUE 约束**：`UNIQUE(server, agent_id, file_path)`
-
-**增量解析逻辑**：
-```sql
--- 插入前检查：同一文件 + 同一修改时间是否已解析
-WHERE NOT EXISTS (
-  SELECT 1 FROM parsed_files
-  WHERE server=? AND agent_id=? AND file_path=?
-    AND file_mtime=? AND file_size=? AND status='success'
-)
-```
-
----
-
-#### 表：`sessions`（Session 根记录）
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `id` | INT AUTO_INCREMENT | 主键 |
-| `server` | VARCHAR(32) | 服务器标识 |
-| `agent_id` | VARCHAR(64) | Agent ID |
-| `session_uuid` | VARCHAR(64) | Session UUID（文件名去掉.jsonl等后缀） |
-| `file_path` | VARCHAR(512) | 来源文件路径 |
-| `session_type` | VARCHAR(32) | `normal` / `topic` / `reset` / `deleted` |
-| `cwd` | VARCHAR(512) | Session 工作目录 |
-| `started_at` | DATETIME(3) | Session 开始时间 |
-| `first_message_at` | DATETIME(3) | 第一条 message 的时间 |
-| `last_message_at` | DATETIME(3) | 最后一条 message 的时间 |
-| `message_count` | INT | 该 session 的消息总数 |
-| `created_at` | DATETIME | 记录创建时间 |
-
-**UNIQUE 约束**：`UNIQUE(session_uuid, server, agent_id)`
-
----
-
-#### 表：`messages`（消息内容）
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `id` | INT AUTO_INCREMENT | 主键 |
-| `session_id` | INT | 外键 → `sessions.id` |
-| `server` | VARCHAR(32) | 服务器标识 |
-| `agent_id` | VARCHAR(64) | Agent ID |
-| `session_uuid` | VARCHAR(64) | Session UUID（冗余存储，方便查询） |
-| `message_uuid` | VARCHAR(64) | 消息 UUID |
-| `parent_message_uuid` | VARCHAR(64) | 父消息 UUID（可空） |
-| `role` | VARCHAR(32) | `user` / `assistant` / `toolResult` |
-| `content_blocks` | JSON | **原文**：原始 content 数组 |
-| `text_preview` | VARCHAR(512) | 纯文本摘要（前512字符） |
-| `first_tool_call` | VARCHAR(128) | 首个 toolCall name |
-| `tool_call_count` | INT | toolCall 总数 |
-| `tool_calls_json` | JSON | **拆出**：所有 toolCall block |
-| `thinking_text` | TEXT | **拆出**：首个 thinking block |
-| `has_thinking` | TINYINT | 是否有 thinking（0/1） |
-| `has_tool_calls` | TINYINT | 是否有 toolCall（0/1） |
-| `is_error` | TINYINT | 整条 isError 标记 |
-| `provider` | VARCHAR(64) | AI Provider（如 `minimax`） |
-| `model` | VARCHAR(128) | 模型 ID（如 `MiniMax-M2.7`） |
-| `api` | VARCHAR(64) | API 类型（如 `anthropic-messages`） |
-| `stop_reason` | VARCHAR(64) | stopReason 字段值 |
-| `input_tokens` | INT | 输入 token 数 |
-| `output_tokens` | INT | 输出 token 数 |
-| `cache_read_tokens` | BIGINT | Cache Read token 数 |
-| `cache_write_tokens` | BIGINT | Cache Write token 数 |
-| `total_tokens` | INT | 总 token 数 |
-| `cost_usd` | DECIMAL(12,8) | 该消息美元成本 |
-| `timestamp` | DATETIME(3) | 消息时间 |
-| `created_at` | DATETIME | 记录创建时间 |
-
-**Indexes**：
-- `idx_agent_timestamp` ON `(agent_id, timestamp)`
-- `idx_first_tool_call` ON `(first_tool_call)`
-- `idx_session_id` ON `(session_id)`
-- `idx_role` ON `(role)`
-
-### 2.4 Content Block 结构
-
-JSONL 中每条 `type:message` 的 `content` 数组，成员类型如下：
-
-| content block type | 关键提取字段 |
-|---|---|
-| `text` | `text`（纯文本） |
-| `thinking` | `thinking`、`thinkingSignature` |
-| `toolCall` | `id`、`name`、`arguments`（JSON 对象） |
-| `toolResult` | `toolCallId`、`toolName`、`content`、`isError`、`details` |
-
-**`text_preview` 提取规则**（按优先级）：
-1. 找第一个 `type=="text"` 的 `text` 字段
-2. 找不到则找 `type=="thinking"` 的 `thinking` 字段
-3. 再找不到则找 `type=="toolResult"` 里第一个子 `type=="text"` 的内容
-4. 截取前512字符，strip HTML
-
----
-
-## 3. Django 项目结构
-
-```
-~/Workspace/agentbase/           # Git 仓库根目录
-├── manage.py
-├── agentbase/                    # Django 项目
-│   ├── __init__.py
-│   ├── settings.py              # 数据库配置在此
-│   ├── urls.py
-│   └── wsgi.py
-├── messages/                     # Django App
-│   ├── __init__.py
-│   ├── models.py                # ParsedFile / Session / Message
-│   ├── admin.py                 # Django Admin 配置
-│   ├── views.py                 # Web 查询视图
-│   ├── urls.py
-│   ├── management/
-│   │   └── commands/
-│   │       └── parse_sessions.py    # Django command
-│   └── templates/
-│       └── messages/
-│           └── message_list.html
-├── scripts/
-│   └── parse_and_import.py      # OpenClaw cron 调用的入口脚本
-├── tests/
-├── requirements.txt
-└── README.md
-```
-
-### 3.1 配置方式
-
-数据库连接信息直接写在 `settings.py` 中（不使用 config.yaml）。
-
-### 3.2 Django Admin 预期界面
-
-**Messages（核心）**：
-- 列表页支持按 `agent_id` + `timestamp` 范围 + `role` + `first_tool_call` 过滤
-- 详情页展示 `content_blocks` 原始 JSON、`thinking_text`、`tool_calls_json`
-- 适合查找"某 Agent 某天所有对话和思考记录"
-
-**Sessions**：列出所有 session，按 server/agent_id 过滤。
-
-**ParsedFiles**：记录已解析文件列表，支持按 server/agent_id/file_path 搜索。
-
----
-
-## 4. 解析脚本设计
-
-### 4.1 入口脚本
-
-`scripts/parse_and_import.py`
-
-- OpenClaw cron 任务调用此脚本
-- 也可单独运行：`python parse_and_import.py --server macmini --agent xingyao`
-- 内部加载 Django settings，调用 Django ORM 写入数据库
-
-### 4.2 解析流程
-
-1. **遍历服务器和 Agent**：macmini/ubuntu1/ubuntu2 → 各 Agent 目录
-2. **扫描 session 文件**：列出所有 `.jsonl` 文件，跳过 `sessions.json`
-3. **增量检查**：查 `parsed_files` 表，文件 mtime+size 未变且 status=success → 跳过
-4. **解析 JSONL**：逐行读取，提取 `type:session` 和 `type:message` 记录
-5. **写入数据库**：先插入 `sessions`，再批量插入 `messages`
-6. **更新 `parsed_files`**：status=success 或 status=failed + error_message
-
-### 4.3 OpenClaw Cron 任务
-
-每日 00:05 执行（00:00 照片整理完成后错开）：
-
-```bash
-python ~/Workspace/agentbase/scripts/parse_and_import.py
-```
-
-- 在 Mac Mini 上执行
-- 通过 SSH 访问 ubuntu1/2 的 session 目录
-- 所有 Agent 的当日新 session 均被解析
-
----
-
-## 5. 典型查询示例
-
-### 5.1 查某 Agent 某天的所有消息
-
-```sql
-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;
-```
-
-### 5.2 查某 Agent 某天调用过的所有 exec 命令
-
-```sql
-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';
-```
-
-### 5.3 查包含 thinking 的消息
-
-```sql
-SELECT id, message_uuid, role, thinking_text, timestamp
-FROM messages
-WHERE agent_id = 'xingyao'
-  AND has_thinking = 1
-  AND timestamp BETWEEN '2026-04-05 00:00:00' AND '2026-04-05 23:59:59';
-```
-
----
-
-## 6. 待确认事项
-
-- [ ] 数据库类型：MariaDB？SQLite（开发测试用）？
-- [ ] 数据库名称
-- [ ] MariaDB 部署在哪里？（Mac Mini 本地？NAS？独立服务器？）
-
----
-
-## 7. 后续步骤
-
-1. 用户确认以上设计
-2. 创建 Git 仓库 `~/Workspace/agentbase/`
-3. 初始化 Django 项目
-4. 编写 `settings.py`（含数据库配置）
-5. 编写 `messages/models.py`（三张表）
-6. 编写 `messages/admin.py`（Admin 配置）
-7. 编写 `scripts/parse_and_import.py`（解析入口）
-8. 编写 `messages/management/commands/parse_sessions.py`（Django command）
-9. 配置 Django Admin 模板（message_list.html）
-10. 创建 OpenClaw cron 任务
+---
+title: AgentBase 项目设计文档
+source:
+author: shenwei
+published:
+created:
+description:
+tags: []
+---
+
+# AgentBase 项目设计文档
+
+> 设计日期：2026-04-05
+> 状态：已确认，等待实施
+> 项目位置：`~/Workspace/agentbase/`
+
+---
+
+## 1. 项目概述
+
+**项目名**：agentbase
+**项目类型**：Django Web 应用 + 数据归档系统
+**核心目标**：遍历 OpenClaw Agent 的 session JSONL 文件，解析并保存到 MariaDB，通过 Django Admin 提供 Web 查询界面。
+
+**使用场景**：
+- 查找某个 Agent 在某天的所有对话记录
+- 查找某个 Agent 在处理任务时调用了哪些工具（特别是 `exec` 命令的具体内容）
+- 查看 Agent 的思考过程（thinking block）
+- 增量解析，只解析未处理过的文件
+
+---
+
+## 2. 数据库设计
+
+### 2.1 服务器与 Agent 映射
+
+| 服务器 | 标识 | Session 根目录 |
+|--------|------|----------------|
+| Mac Mini | `macmini` | `/Users/weishen/.openclaw/agents/` |
+| Ubuntu1 | `ubuntu1` | `/home/shenwei/.openclaw/agents/` |
+| Ubuntu2 | `ubuntu2` | `/home/shenwei/.openclaw/agents/` |
+
+**纳入的 Agent**：main、xingyao、xinghui、xingjiang、opencode、sisyphus
+
+### 2.2 Session 文件类型
+
+所有 `.jsonl` 文件均需解析，包括：
+- `*.jsonl` — 正常 session
+- `*.jsonl.reset.*` — reset 快照
+- `*.jsonl.deleted.*` — 删除快照
+- `*-topic-*.jsonl` — 线程 session
+
+**session_type 判定**：
+- 文件名含 `.reset.` → `reset`
+- 文件名含 `.deleted.` → `deleted`
+- 文件名含 `-topic-` → `topic`
+- 默认 → `normal`
+
+**忽略文件**：`sessions.json`（索引文件，不解析）
+
+### 2.3 数据库 Schema
+
+#### 表：`parsed_files`（增量解析控制）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | INT AUTO_INCREMENT | 主键 |
+| `server` | VARCHAR(32) | 服务器标识 |
+| `agent_id` | VARCHAR(64) | Agent ID |
+| `file_path` | VARCHAR(512) | 文件绝对路径 |
+| `file_mtime` | BIGINT | 文件最后修改时间（Unix timestamp） |
+| `file_size` | BIGINT | 文件大小（字节） |
+| `status` | VARCHAR(16) | `pending` / `success` / `failed` |
+| `parsed_at` | DATETIME | 本次解析时间 |
+| `error_message` | TEXT | 失败时的错误信息（可空） |
+
+**UNIQUE 约束**：`UNIQUE(server, agent_id, file_path)`
+
+**增量解析逻辑**：
+```sql
+-- 插入前检查：同一文件 + 同一修改时间是否已解析
+WHERE NOT EXISTS (
+  SELECT 1 FROM parsed_files
+  WHERE server=? AND agent_id=? AND file_path=?
+    AND file_mtime=? AND file_size=? AND status='success'
+)
+```
+
+---
+
+#### 表：`sessions`（Session 根记录）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | INT AUTO_INCREMENT | 主键 |
+| `server` | VARCHAR(32) | 服务器标识 |
+| `agent_id` | VARCHAR(64) | Agent ID |
+| `session_uuid` | VARCHAR(64) | Session UUID（文件名去掉.jsonl等后缀） |
+| `file_path` | VARCHAR(512) | 来源文件路径 |
+| `session_type` | VARCHAR(32) | `normal` / `topic` / `reset` / `deleted` |
+| `cwd` | VARCHAR(512) | Session 工作目录 |
+| `started_at` | DATETIME(3) | Session 开始时间 |
+| `first_message_at` | DATETIME(3) | 第一条 message 的时间 |
+| `last_message_at` | DATETIME(3) | 最后一条 message 的时间 |
+| `message_count` | INT | 该 session 的消息总数 |
+| `created_at` | DATETIME | 记录创建时间 |
+
+**UNIQUE 约束**：`UNIQUE(session_uuid, server, agent_id)`
+
+---
+
+#### 表：`messages`（消息内容）
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | INT AUTO_INCREMENT | 主键 |
+| `session_id` | INT | 外键 → `sessions.id` |
+| `server` | VARCHAR(32) | 服务器标识 |
+| `agent_id` | VARCHAR(64) | Agent ID |
+| `session_uuid` | VARCHAR(64) | Session UUID（冗余存储，方便查询） |
+| `message_uuid` | VARCHAR(64) | 消息 UUID |
+| `parent_message_uuid` | VARCHAR(64) | 父消息 UUID（可空） |
+| `role` | VARCHAR(32) | `user` / `assistant` / `toolResult` |
+| `content_blocks` | JSON | **原文**：原始 content 数组 |
+| `text_preview` | VARCHAR(512) | 纯文本摘要（前512字符） |
+| `first_tool_call` | VARCHAR(128) | 首个 toolCall name |
+| `tool_call_count` | INT | toolCall 总数 |
+| `tool_calls_json` | JSON | **拆出**：所有 toolCall block |
+| `thinking_text` | TEXT | **拆出**：首个 thinking block |
+| `has_thinking` | TINYINT | 是否有 thinking（0/1） |
+| `has_tool_calls` | TINYINT | 是否有 toolCall（0/1） |
+| `is_error` | TINYINT | 整条 isError 标记 |
+| `provider` | VARCHAR(64) | AI Provider（如 `minimax`） |
+| `model` | VARCHAR(128) | 模型 ID（如 `MiniMax-M2.7`） |
+| `api` | VARCHAR(64) | API 类型（如 `anthropic-messages`） |
+| `stop_reason` | VARCHAR(64) | stopReason 字段值 |
+| `input_tokens` | INT | 输入 token 数 |
+| `output_tokens` | INT | 输出 token 数 |
+| `cache_read_tokens` | BIGINT | Cache Read token 数 |
+| `cache_write_tokens` | BIGINT | Cache Write token 数 |
+| `total_tokens` | INT | 总 token 数 |
+| `cost_usd` | DECIMAL(12,8) | 该消息美元成本 |
+| `timestamp` | DATETIME(3) | 消息时间 |
+| `created_at` | DATETIME | 记录创建时间 |
+
+**Indexes**：
+- `idx_agent_timestamp` ON `(agent_id, timestamp)`
+- `idx_first_tool_call` ON `(first_tool_call)`
+- `idx_session_id` ON `(session_id)`
+- `idx_role` ON `(role)`
+
+### 2.4 Content Block 结构
+
+JSONL 中每条 `type:message` 的 `content` 数组，成员类型如下：
+
+| content block type | 关键提取字段 |
+|---|---|
+| `text` | `text`（纯文本） |
+| `thinking` | `thinking`、`thinkingSignature` |
+| `toolCall` | `id`、`name`、`arguments`（JSON 对象） |
+| `toolResult` | `toolCallId`、`toolName`、`content`、`isError`、`details` |
+
+**`text_preview` 提取规则**（按优先级）：
+1. 找第一个 `type=="text"` 的 `text` 字段
+2. 找不到则找 `type=="thinking"` 的 `thinking` 字段
+3. 再找不到则找 `type=="toolResult"` 里第一个子 `type=="text"` 的内容
+4. 截取前512字符，strip HTML
+
+---
+
+## 3. Django 项目结构
+
+```
+~/Workspace/agentbase/           # Git 仓库根目录
+├── manage.py
+├── agentbase/                    # Django 项目
+│   ├── __init__.py
+│   ├── settings.py              # 数据库配置在此
+│   ├── urls.py
+│   └── wsgi.py
+├── messages/                     # Django App
+│   ├── __init__.py
+│   ├── models.py                # ParsedFile / Session / Message
+│   ├── admin.py                 # Django Admin 配置
+│   ├── views.py                 # Web 查询视图
+│   ├── urls.py
+│   ├── management/
+│   │   └── commands/
+│   │       └── parse_sessions.py    # Django command
+│   └── templates/
+│       └── messages/
+│           └── message_list.html
+├── scripts/
+│   └── parse_and_import.py      # OpenClaw cron 调用的入口脚本
+├── tests/
+├── requirements.txt
+└── README.md
+```
+
+### 3.1 配置方式
+
+数据库连接信息直接写在 `settings.py` 中（不使用 config.yaml）。
+
+### 3.2 Django Admin 预期界面
+
+**Messages（核心）**：
+- 列表页支持按 `agent_id` + `timestamp` 范围 + `role` + `first_tool_call` 过滤
+- 详情页展示 `content_blocks` 原始 JSON、`thinking_text`、`tool_calls_json`
+- 适合查找"某 Agent 某天所有对话和思考记录"
+
+**Sessions**：列出所有 session，按 server/agent_id 过滤。
+
+**ParsedFiles**：记录已解析文件列表，支持按 server/agent_id/file_path 搜索。
+
+---
+
+## 4. 解析脚本设计
+
+### 4.1 入口脚本
+
+`scripts/parse_and_import.py`
+
+- OpenClaw cron 任务调用此脚本
+- 也可单独运行：`python parse_and_import.py --server macmini --agent xingyao`
+- 内部加载 Django settings，调用 Django ORM 写入数据库
+
+### 4.2 解析流程
+
+1. **遍历服务器和 Agent**：macmini/ubuntu1/ubuntu2 → 各 Agent 目录
+2. **扫描 session 文件**：列出所有 `.jsonl` 文件，跳过 `sessions.json`
+3. **增量检查**：查 `parsed_files` 表，文件 mtime+size 未变且 status=success → 跳过
+4. **解析 JSONL**：逐行读取，提取 `type:session` 和 `type:message` 记录
+5. **写入数据库**：先插入 `sessions`，再批量插入 `messages`
+6. **更新 `parsed_files`**：status=success 或 status=failed + error_message
+
+### 4.3 OpenClaw Cron 任务
+
+每日 00:05 执行（00:00 照片整理完成后错开）：
+
+```bash
+python ~/Workspace/agentbase/scripts/parse_and_import.py
+```
+
+- 在 Mac Mini 上执行
+- 通过 SSH 访问 ubuntu1/2 的 session 目录
+- 所有 Agent 的当日新 session 均被解析
+
+---
+
+## 5. 典型查询示例
+
+### 5.1 查某 Agent 某天的所有消息
+
+```sql
+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;
+```
+
+### 5.2 查某 Agent 某天调用过的所有 exec 命令
+
+```sql
+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';
+```
+
+### 5.3 查包含 thinking 的消息
+
+```sql
+SELECT id, message_uuid, role, thinking_text, timestamp
+FROM messages
+WHERE agent_id = 'xingyao'
+  AND has_thinking = 1
+  AND timestamp BETWEEN '2026-04-05 00:00:00' AND '2026-04-05 23:59:59';
+```
+
+---
+
+## 6. 待确认事项
+
+- [ ] 数据库类型：MariaDB？SQLite（开发测试用）？
+- [ ] 数据库名称
+- [ ] MariaDB 部署在哪里？（Mac Mini 本地？NAS？独立服务器？）
+
+---
+
+## 7. 后续步骤
+
+1. 用户确认以上设计
+2. 创建 Git 仓库 `~/Workspace/agentbase/`
+3. 初始化 Django 项目
+4. 编写 `settings.py`（含数据库配置）
+5. 编写 `messages/models.py`（三张表）
+6. 编写 `messages/admin.py`（Admin 配置）
+7. 编写 `scripts/parse_and_import.py`（解析入口）
+8. 编写 `messages/management/commands/parse_sessions.py`（Django command）
+9. 配置 Django Admin 模板（message_list.html）
+10. 创建 OpenClaw cron 任务

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

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