150 lines
6.8 KiB
Markdown
150 lines
6.8 KiB
Markdown
# PicoBot 数据库表结构
|
||
|
||
数据库为 SQLite，默认位于 workspace 下的 `picobot.db`。
|
||
|
||
连接启用 WAL、`synchronous=NORMAL`、foreign keys、5 秒 busy timeout，连接池最多 8 个连接。当前 `PRAGMA user_version=4`；启动时会在事务内补齐旧库字段和索引，遇到比程序更新的 schema version 会拒绝启动。
|
||
|
||
## sessions 表
|
||
|
||
会话表，一个 session 对应一个 (channel, chat_id, dialog_id) 组合。
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | TEXT PK | session ID，格式 `<channel>:<chat_id>:<dialog_id>` |
|
||
| `channel` | TEXT | 渠道名称 |
|
||
| `chat_id` | TEXT | 聊天/群组标识 |
|
||
| `dialog_id` | TEXT | 对话标识 |
|
||
| `title` | TEXT | 会话标题（默认 "新对话"） |
|
||
| `created_at` | INTEGER | 创建时间（Unix 毫秒） |
|
||
| `last_active_at` | INTEGER | 最后活跃时间（Unix 毫秒） |
|
||
| `message_count` | INTEGER | 消息计数 |
|
||
| `routing_info` | TEXT | 路由信息 |
|
||
| `archived_at` | INTEGER | 归档时间（Unix 毫秒），NULL 表示未归档 |
|
||
| `deleted_at` | INTEGER | 软删除时间戳 |
|
||
| `last_consolidated_at` | INTEGER | 上次记忆归并时间 |
|
||
| `last_compressed_message_at` | INTEGER | 上次上下文压缩边界时间戳 |
|
||
|
||
`(channel, chat_id, dialog_id)` 唯一。普通列表排除 `deleted_at`；是否包含归档记录由查询参数决定。
|
||
|
||
## messages 表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | TEXT PK | 消息 UUID |
|
||
| `session_id` | TEXT FK | 所属会话，外键关联 sessions(id) |
|
||
| `seq` | INTEGER | 消息序号 |
|
||
| `role` | TEXT | 角色: user / assistant / tool / system |
|
||
| `content` | TEXT | 消息内容 |
|
||
| `media_refs` | TEXT | 多媒体引用 JSON |
|
||
| `tool_call_id` | TEXT | 工具调用 ID |
|
||
| `tool_name` | TEXT | 工具名称 |
|
||
| `tool_calls` | TEXT | 工具调用参数 JSON |
|
||
| `source` | TEXT | 消息来源（跨会话消息时标记来源 session_id） |
|
||
| `created_at` | INTEGER | 创建时间（Unix 毫秒） |
|
||
| `reasoning_content` | TEXT | 可展示的模型 reasoning（如有） |
|
||
| `provider_state` | TEXT | Provider 私有回放状态 JSON；只回放给匹配 Provider，不下发客户端或 Channel |
|
||
| `turn_id` | TEXT | 产生该消息的活动 Turn ID |
|
||
| `iteration` | INTEGER | Agent 工具循环中的迭代序号 |
|
||
| `completion_status` | TEXT | `completed` / `cancelled` / `interrupted`，旧数据默认 completed |
|
||
|
||
`(session_id, seq)` 有唯一索引，防止并发写入重复序号。删除 session 会通过外键级联删除 messages。
|
||
|
||
## background_tasks 表
|
||
|
||
delegate 后台子任务表。`session_id` 不使用数据库外键，因为 session 使用软删除，关联关系由应用层维护。
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | TEXT PK | 后台任务 ID |
|
||
| `session_id` | TEXT | 所属会话 |
|
||
| `channel` | TEXT | 回传渠道 |
|
||
| `chat_id` | TEXT | 回传目标对话 |
|
||
| `prompt` | TEXT | 子任务提示 |
|
||
| `allowed_tools` | TEXT | 允许工具 JSON |
|
||
| `status` | TEXT | pending / running / completed / failed / cancelled |
|
||
| `result` | TEXT | 执行结果 |
|
||
| `error` | TEXT | 错误信息 |
|
||
| `tool_calls_count` | INTEGER | 工具调用次数 |
|
||
| `iterations` | INTEGER | Agent 迭代次数 |
|
||
| `started_at` | INTEGER | 开始时间 |
|
||
| `finished_at` | INTEGER | 结束时间 |
|
||
| `created_at` | INTEGER | 创建时间 |
|
||
|
||
## task_plans / task_items 表
|
||
|
||
`task_plans` 保存 session 级任务计划，通过部分唯一索引保证每个 session 最多一个 `status='active'` 的计划。`version` 在任何子项变化时递增，用于 WebSocket 快照排序和乐观并发检查。
|
||
|
||
`task_items` 以 `(plan_id, id)` 为复合主键，因此每个计划都可使用 `T1`、`T2` 等稳定显示 ID。子项状态为 `pending`、`in_progress`、`completed` 或 `blocked`；`executor_kind` 和 `execution_id` 将并行子 Agent 执行绑定到具体子项。只有 active plan 且 execution ID 匹配时，异步结果才能提交。
|
||
|
||
## memories 表
|
||
|
||
长期记忆存储。
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | TEXT PK | 记忆 UUID |
|
||
| `key` | TEXT UNIQUE | 记忆唯一键 |
|
||
| `content` | TEXT | 记忆内容 |
|
||
| `category` | TEXT | 类别: knowledge / timeline |
|
||
| `importance` | REAL | 重要性权重 (0-1) |
|
||
| `session_id` | TEXT | 关联会话 |
|
||
| `created_at` | TEXT | 创建时间 |
|
||
| `updated_at` | TEXT | 更新时间 |
|
||
|
||
配套 FTS5 全文索引虚拟表 `memory_fts(key, content)`，用于关键词搜索，通过触发器自动同步。
|
||
|
||
## scheduled_jobs 表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | TEXT PK | 任务 UUID |
|
||
| `name` | TEXT | 任务名称 |
|
||
| `schedule` | TEXT | 调度规则 JSON（at/every/cron） |
|
||
| `prompt` | TEXT | 任务提示词 |
|
||
| `channel` | TEXT | 执行渠道 |
|
||
| `chat_id` | TEXT | 目标对话 |
|
||
| `model` | TEXT | 可选模型标记；当前会存储/展示，但 Scheduler 执行仍使用默认 Agent 模型 |
|
||
| `enabled` | INTEGER | 是否启用 (1/0) |
|
||
| `delete_after_run` | INTEGER | 执行后自动删除 (1/0) |
|
||
| `next_run_at` | INTEGER | 下次执行时间 |
|
||
| `last_run_at` | INTEGER | 上次执行时间 |
|
||
| `last_status` | TEXT | 上次执行状态 |
|
||
| `last_error` | TEXT | 上次错误信息 |
|
||
| `locked_at` | INTEGER | 本次领取时间 |
|
||
| `lock_owner` | TEXT | 领取任务的 Scheduler owner UUID |
|
||
| `lease_until` | INTEGER | 租约到期时间；进程崩溃后允许其他实例重新领取 |
|
||
| `created_at` | INTEGER | 创建时间（Unix 毫秒） |
|
||
| `updated_at` | INTEGER | 更新时间（Unix 毫秒） |
|
||
|
||
Scheduler 使用原子 `UPDATE ... RETURNING` 领取到期任务。任务结果、下次运行时间和租约释放在同一事务中提交，并校验 owner，防止过期 worker 覆盖已恢复的任务。
|
||
|
||
## job_runs 表
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | INTEGER PK | 自增 ID |
|
||
| `job_id` | TEXT FK | 关联任务，外键关联 scheduled_jobs(id) |
|
||
| `started_at` | INTEGER | 开始时间 |
|
||
| `finished_at` | INTEGER | 结束时间 |
|
||
| `status` | TEXT | 执行状态 |
|
||
| `output` | TEXT | 执行输出 |
|
||
| `error` | TEXT | 错误信息 |
|
||
| `duration_ms` | INTEGER | 耗时（毫秒） |
|
||
|
||
## llm_calls 表
|
||
|
||
记录所有 LLM API 调用的请求/响应详情，自动保留最近 1000 条。
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `id` | INTEGER PK | 自增 ID |
|
||
| `created_at` | INTEGER | 调用时间 |
|
||
| `provider` | TEXT | 提供商类型 |
|
||
| `model` | TEXT | 模型名称 |
|
||
| `request_body` | TEXT | 请求摘要 JSON；旧记录可能是完整请求体 |
|
||
| `response_body` | TEXT | 响应体 JSON |
|
||
| `error` | TEXT | 错误信息 |
|
||
| `duration_ms` | INTEGER | 耗时（毫秒） |
|
||
|
||
旧数据中的 `request_body`/`response_body` 可能包含用户内容，排障和导出数据库时应按敏感数据处理。新 Provider 请求的 `request_body` 只保存模型、消息数、工具数和 stream 标志等摘要；错误响应仍可能包含服务端回显内容。
|