ishenwei/nexus

Fork 0

Files

weishen 68831201ec Batch: enforce full 7-field frontmatter on all 360 notes (obsidian_frontmatter.py v3)

2026-04-09 19:31:45 +08:00

12 KiB

Raw Blame History

title, source, author, published, created, description, tags

title

source

author

published

created

description

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. 附录：典型查询参考

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

12 KiB Raw Blame History Unescape Escape

AgentBase 项目需求文档

1. 项目概述

1.1 项目背景

1.2 项目目标

1.3 核心价值

2. 系统范围

2.1 纳入系统

2.2 纳入 Agent

2.3 纳入文件类型

2.4 不纳入范围

3. 功能需求

3.1 增量解析引擎

3.2 数据库存储

3.3 Django Admin 管理界面

3.4 定时任务

3.5 命令行接口

4. 非功能需求

4.1 性能

4.2 可靠性

4.3 可维护性

4.4 安全性

5. 数据库 Schema（摘要）

5.1 parsed_files

5.2 sessions

5.3 messages

6. 用户故事

US-001：查询某 Agent 某天的完整对话

US-002：查看某条消息的完整思考过程

US-003：查询某天某 Agent 执行过的所有 exec 命令

US-004：追踪已解析文件状态

US-005：增量同步最新 session

7. 技术选型

8. 项目目录结构

9. 后续步骤（待用户确认后执行）

10. 附录：典型查询参考

12 KiB

Raw Blame History

5.1 `parsed_files`

5.2 `sessions`

5.3 `messages`