791 lines
27 KiB
Markdown
791 lines
27 KiB
Markdown
# Inbox V2 数据库设计
|
||
|
||
本文档是 `inbox v2` 的数据库开发基线。
|
||
|
||
它服务于三件事：
|
||
|
||
1. 明确 `v2` 到底使用哪些数据库。
|
||
2. 明确每张表的字段、主键、外键和作用。
|
||
3. 明确各张表之间的关系，作为后续 `store / app / http` 实现依据。
|
||
|
||
## 1. 物理数据库
|
||
|
||
`v2` 先只使用 **1 个物理数据库**：
|
||
|
||
| 数据库 | 引擎 | 是否采用 | 用途 |
|
||
| --- | --- | --- | --- |
|
||
| `inbox.db` | SQLite | 是 | 所有运行时业务数据、在线可编辑配置、配置审计 |
|
||
| Redis | - | 否 | 当前不需要单独缓存或队列 |
|
||
| PostgreSQL | - | 否 | 当前先不引入额外运维复杂度 |
|
||
| 独立日志库 | - | 否 | 执行日志先跟主库放一起 |
|
||
| 向量库 | - | 否 | 当前主流程不依赖向量检索 |
|
||
|
||
一句话：
|
||
|
||
- `V2` 先只有一个库：`inbox.db`
|
||
|
||
## 2. 关键决策
|
||
|
||
### 2.1 配置入库
|
||
|
||
因为 `roles / prompts / skills / config` 需要满足：
|
||
|
||
- 前端可编辑
|
||
- 保存后立即生效
|
||
- 不需要改文件后再发版
|
||
|
||
所以第二版里，这些内容的**运行时真源就是数据库**。
|
||
|
||
文件只保留这些作用：
|
||
|
||
- 默认模板
|
||
- 初始化导入源
|
||
- 内置技能的原始资产
|
||
|
||
### 2.2 立即生效的定义
|
||
|
||
这里的“立即生效”定义为：
|
||
|
||
- 配置保存成功后
|
||
- **下一次新的 agent run / 新的消息处理 / 新的 HTTP 请求** 立即读取最新配置
|
||
|
||
不包含：
|
||
|
||
- 已经运行中的 agent 进程半路热切换配置
|
||
|
||
### 2.3 配置覆盖规则
|
||
|
||
在线配置支持两层作用域：
|
||
|
||
1. `global`
|
||
2. `workspace override`
|
||
|
||
解析优先级固定为：
|
||
|
||
`workspace row > global row`
|
||
|
||
也就是说：
|
||
|
||
- 如果某个 workspace 有自己的 prompt/config/binding，就优先使用它
|
||
- 否则回退到全局默认
|
||
|
||
### 2.4 统一建模原则
|
||
|
||
1. 所有业务主键统一使用 `TEXT`
|
||
2. 所有时间统一使用 UTC RFC3339
|
||
3. 核心业务关系用结构化表，不用 JSON blob 代替
|
||
4. JSON 只用于快照和弱结构扩展字段
|
||
5. `topic` 是业务主实体
|
||
6. `product` 接管需求整理文档
|
||
7. `clarifier_state / clarifier_artifacts / topic_records` 在 `v2` 中不再保留
|
||
|
||
## 3. 数据域划分
|
||
|
||
| 数据域 | 表 |
|
||
| --- | --- |
|
||
| 系统 | `schema_migrations` |
|
||
| 项目与工作区 | `projects`, `workspaces` |
|
||
| 在线角色配置 | `roles`, `role_prompts`, `role_configs`, `skills`, `role_skill_bindings` |
|
||
| Topic 与文档 | `topics`, `topic_documents` |
|
||
| 消息协作 | `messages`, `message_deliveries` |
|
||
| Requirement / Discovery / Workflow / Merge | `requirements`, `discovery_rounds`, `discovery_candidates`, `discovery_votes`, `workflow_runs`, `workflow_run_logs`, `merge_requests` |
|
||
|
||
## 4. 表清单总览
|
||
|
||
| 表名 | 数据域 | 说明 |
|
||
| --- | --- | --- |
|
||
| `schema_migrations` | 系统 | 迁移历史 |
|
||
| `projects` | 项目 | 项目主表 |
|
||
| `workspaces` | 工作区 | 工作区主表 |
|
||
| `roles` | 在线角色配置 | 角色定义 |
|
||
| `role_prompts` | 在线角色配置 | 角色提示词 |
|
||
| `role_configs` | 在线角色配置 | 角色模型和运行配置 |
|
||
| `skills` | 在线角色配置 | 技能定义 |
|
||
| `role_skill_bindings` | 在线角色配置 | 角色与技能绑定 |
|
||
| `topics` | Topic | 统一 topic 主实体 |
|
||
| `topic_documents` | Topic | `PRD`、`Decision Log`、Discovery 文档 |
|
||
| `messages` | 消息协作 | 消息信封与正文 |
|
||
| `message_deliveries` | 消息协作 | 消息收件与归档状态 |
|
||
| `requirements` | Requirement | pool 队列项 |
|
||
| `discovery_rounds` | Discovery | discovery 轮次 |
|
||
| `discovery_candidates` | Discovery | discovery 候选项 |
|
||
| `discovery_votes` | Discovery | discovery 投票 |
|
||
| `workflow_runs` | Workflow | 角色执行记录 |
|
||
| `workflow_run_logs` | Workflow | 执行日志流 |
|
||
| `merge_requests` | Merge | merge 请求记录 |
|
||
|
||
## 5. 表字段定义
|
||
|
||
### 5.1 `schema_migrations`
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `version` | `INTEGER` | PK | 迁移版本号 |
|
||
| `name` | `TEXT` | NOT NULL | 迁移名称 |
|
||
| `applied_at` | `TEXT` | NOT NULL | 执行时间 |
|
||
|
||
### 5.2 `projects`
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `id` | `TEXT` | PK | 项目 ID |
|
||
| `slug` | `TEXT` | NOT NULL, UNIQUE | 项目标识 |
|
||
| `name` | `TEXT` | NOT NULL | 展示名称 |
|
||
| `root_path` | `TEXT` | NOT NULL, UNIQUE | 项目根目录 |
|
||
| `default_branch` | `TEXT` | NOT NULL | 默认分支 |
|
||
| `status` | `TEXT` | NOT NULL | `active / archived` |
|
||
| `created_at` | `TEXT` | NOT NULL | 创建时间 |
|
||
| `updated_at` | `TEXT` | NOT NULL | 更新时间 |
|
||
|
||
关系：
|
||
|
||
- `projects 1 -> N workspaces`
|
||
|
||
### 5.3 `workspaces`
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `id` | `TEXT` | PK | 工作区 ID |
|
||
| `project_id` | `TEXT` | FK -> `projects.id` | 所属项目 |
|
||
| `slug` | `TEXT` | NOT NULL, UNIQUE | 工作区标识 |
|
||
| `name` | `TEXT` | NOT NULL | 展示名称 |
|
||
| `root_path` | `TEXT` | NOT NULL, UNIQUE | 工作区路径 |
|
||
| `base_branch` | `TEXT` | NOT NULL | 基线分支 |
|
||
| `worktree_branch` | `TEXT` | NOT NULL, UNIQUE | 工作分支 |
|
||
| `runtime_backend` | `TEXT` | NOT NULL | `local / container / remote` |
|
||
| `status` | `TEXT` | NOT NULL | `active / paused / archived` |
|
||
| `created_at` | `TEXT` | NOT NULL | 创建时间 |
|
||
| `updated_at` | `TEXT` | NOT NULL | 更新时间 |
|
||
|
||
关系：
|
||
|
||
- `workspaces N -> 1 projects`
|
||
- `workspaces 1 -> N topics`
|
||
- `workspaces 1 -> N messages`
|
||
- `workspaces 1 -> N requirements`
|
||
- `workspaces 1 -> N discovery_rounds`
|
||
- `workspaces 1 -> N workflow_runs`
|
||
- `workspaces 1 -> N merge_requests`
|
||
|
||
### 5.4 `roles`
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `name` | `TEXT` | PK | 角色名，例如 `product` |
|
||
| `title` | `TEXT` | NOT NULL | 展示名称 |
|
||
| `category` | `TEXT` | NOT NULL | `product / delivery / review / discovery` |
|
||
| `description` | `TEXT` | NOT NULL DEFAULT `''` | 角色说明 |
|
||
| `is_enabled` | `INTEGER` | NOT NULL | 1 启用，0 禁用 |
|
||
| `is_builtin` | `INTEGER` | NOT NULL | 1 内置，0 自定义 |
|
||
| `sort_order` | `INTEGER` | NOT NULL DEFAULT `0` | 排序 |
|
||
| `created_at` | `TEXT` | NOT NULL | 创建时间 |
|
||
| `updated_at` | `TEXT` | NOT NULL | 更新时间 |
|
||
|
||
关系：
|
||
|
||
- `roles 1 -> N role_prompts`
|
||
- `roles 1 -> N role_configs`
|
||
- `roles 1 -> N role_skill_bindings`
|
||
- `roles 1 -> N messages`
|
||
- `roles 1 -> N message_deliveries`
|
||
- `roles 1 -> N requirements`
|
||
- `roles 1 -> N discovery_candidates`
|
||
- `roles 1 -> N discovery_votes`
|
||
- `roles 1 -> N workflow_runs`
|
||
|
||
### 5.5 `role_prompts`
|
||
|
||
当前生效的提示词表。
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `id` | `TEXT` | PK | 提示词记录 ID |
|
||
| `role_name` | `TEXT` | FK -> `roles.name` | 所属角色 |
|
||
| `workspace_id` | `TEXT` | FK -> `workspaces.id`, NULLABLE | 为空表示全局默认；非空表示 workspace override |
|
||
| `prompt_kind` | `TEXT` | NOT NULL | `system / clarification / plan / review / freeze / execution / verification / discovery` |
|
||
| `content_markdown` | `TEXT` | NOT NULL | 提示词正文 |
|
||
| `version` | `INTEGER` | NOT NULL | 当前版本号 |
|
||
| `updated_by` | `TEXT` | NOT NULL DEFAULT `''` | 修改人或修改来源 |
|
||
| `created_at` | `TEXT` | NOT NULL | 创建时间 |
|
||
| `updated_at` | `TEXT` | NOT NULL | 更新时间 |
|
||
|
||
唯一约束：
|
||
|
||
- 全局：每个 `(role_name, prompt_kind)` 只能有 1 条全局默认记录
|
||
- 工作区：每个 `(role_name, workspace_id, prompt_kind)` 只能有 1 条 override 记录
|
||
|
||
关系：
|
||
|
||
- `role_prompts N -> 1 roles`
|
||
- `role_prompts N -> 1 workspaces`（可空）
|
||
|
||
### 5.6 `role_configs`
|
||
|
||
当前生效的角色运行配置表。
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `id` | `TEXT` | PK | 配置记录 ID |
|
||
| `role_name` | `TEXT` | FK -> `roles.name` | 所属角色 |
|
||
| `workspace_id` | `TEXT` | FK -> `workspaces.id`, NULLABLE | 为空表示全局默认；非空表示 workspace override |
|
||
| `model` | `TEXT` | NOT NULL DEFAULT `''` | 默认模型 |
|
||
| `model_provider` | `TEXT` | NOT NULL DEFAULT `''` | 模型提供方 |
|
||
| `provider_name` | `TEXT` | NOT NULL DEFAULT `''` | Provider 名称 |
|
||
| `provider_base_url` | `TEXT` | NOT NULL DEFAULT `''` | Provider Base URL |
|
||
| `provider_wire_api` | `TEXT` | NOT NULL DEFAULT `''` | Provider Wire API |
|
||
| `reasoning_effort` | `TEXT` | NOT NULL DEFAULT `''` | 默认 reasoning 等级 |
|
||
| `plan_model` | `TEXT` | NOT NULL DEFAULT `''` | 规划阶段专用模型 |
|
||
| `plan_reasoning_effort` | `TEXT` | NOT NULL DEFAULT `''` | 规划阶段 reasoning |
|
||
| `disable_response_storage` | `INTEGER` | NOT NULL DEFAULT `0` | 是否关闭响应持久化 |
|
||
| `shell_env_inherit` | `TEXT` | NOT NULL DEFAULT `core` | 继承环境变量策略 |
|
||
| `shell_env_overrides_json` | `TEXT` | NOT NULL DEFAULT `{}` | 环境变量覆盖项 |
|
||
| `extra_config_json` | `TEXT` | NOT NULL DEFAULT `{}` | 其他扩展配置 |
|
||
| `version` | `INTEGER` | NOT NULL | 当前版本号 |
|
||
| `updated_by` | `TEXT` | NOT NULL DEFAULT `''` | 修改人或修改来源 |
|
||
| `created_at` | `TEXT` | NOT NULL | 创建时间 |
|
||
| `updated_at` | `TEXT` | NOT NULL | 更新时间 |
|
||
|
||
唯一约束：
|
||
|
||
- 全局：每个 `role_name` 只能有 1 条全局默认配置
|
||
- 工作区：每个 `(role_name, workspace_id)` 只能有 1 条 override 配置
|
||
|
||
关系：
|
||
|
||
- `role_configs N -> 1 roles`
|
||
- `role_configs N -> 1 workspaces`（可空）
|
||
|
||
### 5.7 `skills`
|
||
|
||
技能定义表。运行时真正使用数据库中的技能内容。
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `id` | `TEXT` | PK | 技能 ID |
|
||
| `skill_key` | `TEXT` | NOT NULL, UNIQUE | 稳定标识 |
|
||
| `name` | `TEXT` | NOT NULL | 展示名称 |
|
||
| `description` | `TEXT` | NOT NULL DEFAULT `''` | 技能说明 |
|
||
| `source_type` | `TEXT` | NOT NULL | `builtin / imported / custom` |
|
||
| `content_markdown` | `TEXT` | NOT NULL DEFAULT `''` | 技能正文内容 |
|
||
| `status` | `TEXT` | NOT NULL | `active / disabled / archived` |
|
||
| `version` | `INTEGER` | NOT NULL | 当前版本号 |
|
||
| `created_at` | `TEXT` | NOT NULL | 创建时间 |
|
||
| `updated_at` | `TEXT` | NOT NULL | 更新时间 |
|
||
|
||
关系：
|
||
|
||
- `skills 1 -> N role_skill_bindings`
|
||
|
||
### 5.8 `role_skill_bindings`
|
||
|
||
角色与技能的绑定表。
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `id` | `TEXT` | PK | 绑定记录 ID |
|
||
| `role_name` | `TEXT` | FK -> `roles.name` | 角色 |
|
||
| `workspace_id` | `TEXT` | FK -> `workspaces.id`, NULLABLE | 为空表示全局默认；非空表示 workspace override |
|
||
| `skill_id` | `TEXT` | FK -> `skills.id` | 技能 |
|
||
| `is_enabled` | `INTEGER` | NOT NULL | 1 启用，0 禁用 |
|
||
| `sort_order` | `INTEGER` | NOT NULL DEFAULT `0` | 排序 |
|
||
| `config_json` | `TEXT` | NOT NULL DEFAULT `{}` | 绑定级配置 |
|
||
| `version` | `INTEGER` | NOT NULL | 当前版本号 |
|
||
| `updated_by` | `TEXT` | NOT NULL DEFAULT `''` | 修改人或修改来源 |
|
||
| `created_at` | `TEXT` | NOT NULL | 创建时间 |
|
||
| `updated_at` | `TEXT` | NOT NULL | 更新时间 |
|
||
|
||
唯一约束：
|
||
|
||
- 全局：每个 `(role_name, skill_id)` 只能有 1 条全局默认绑定
|
||
- 工作区：每个 `(role_name, workspace_id, skill_id)` 只能有 1 条 override 绑定
|
||
|
||
关系：
|
||
|
||
- `role_skill_bindings N -> 1 roles`
|
||
- `role_skill_bindings N -> 1 skills`
|
||
- `role_skill_bindings N -> 1 workspaces`（可空）
|
||
|
||
### 5.10 `topics`
|
||
|
||
这是第二版的主实体表。
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `id` | `TEXT` | PK | topic ID |
|
||
| `workspace_id` | `TEXT` | FK -> `workspaces.id` | 所属工作区 |
|
||
| `slug` | `TEXT` | NOT NULL | 稳定标识 |
|
||
| `title` | `TEXT` | NOT NULL | 标题 |
|
||
| `space` | `TEXT` | NOT NULL | `discovery / clarify / pool / workflow` |
|
||
| `status` | `TEXT` | NOT NULL | 当前状态 |
|
||
| `source_topic_id` | `TEXT` | FK -> `topics.id`, NULLABLE | 来源 topic |
|
||
| `owner_role_name` | `TEXT` | FK -> `roles.name`, NULLABLE | 当前主责角色 |
|
||
| `summary` | `TEXT` | NOT NULL DEFAULT `''` | 摘要 |
|
||
| `meta_json` | `TEXT` | NOT NULL DEFAULT `{}` | 扩展元数据 |
|
||
| `created_at` | `TEXT` | NOT NULL | 创建时间 |
|
||
| `updated_at` | `TEXT` | NOT NULL | 更新时间 |
|
||
| `closed_at` | `TEXT` | NULLABLE | 关闭时间 |
|
||
|
||
唯一约束：
|
||
|
||
- 每个 workspace 下 `slug` 唯一
|
||
|
||
关系：
|
||
|
||
- `topics N -> 1 workspaces`
|
||
- `topics N -> 1 topics`（`source_topic_id`）
|
||
- `topics N -> 1 roles`（`owner_role_name`）
|
||
- `topics 1 -> N topic_documents`
|
||
- `topics 1 -> N messages`
|
||
- `topics 1 -> N requirements`
|
||
- `topics 1 -> N discovery_rounds`
|
||
- `topics 1 -> N workflow_runs`
|
||
- `topics 1 -> N merge_requests`
|
||
|
||
### 5.11 `topic_documents`
|
||
|
||
topic 持有的正式文档。
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `id` | `TEXT` | PK | 文档 ID |
|
||
| `topic_id` | `TEXT` | FK -> `topics.id` | 所属 topic |
|
||
| `kind` | `TEXT` | NOT NULL | `prd / decision_log / discovery_request / discovery_result` |
|
||
| `content_markdown` | `TEXT` | NOT NULL | Markdown 正文 |
|
||
| `version` | `INTEGER` | NOT NULL | 版本号 |
|
||
| `updated_by_role_name` | `TEXT` | FK -> `roles.name`, NULLABLE | 最后更新角色 |
|
||
| `created_at` | `TEXT` | NOT NULL | 创建时间 |
|
||
| `updated_at` | `TEXT` | NOT NULL | 更新时间 |
|
||
|
||
唯一约束：
|
||
|
||
- 每个 topic 下每种 `kind` 只能有 1 条当前文档
|
||
|
||
说明：
|
||
|
||
- `PRD` 与 `Decision Log` 在 `v2` 中归 `product` 所有
|
||
|
||
### 5.12 `messages`
|
||
|
||
消息主表。
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `id` | `TEXT` | PK | 消息 ID |
|
||
| `workspace_id` | `TEXT` | FK -> `workspaces.id` | 所属工作区 |
|
||
| `topic_id` | `TEXT` | FK -> `topics.id` | 所属 topic |
|
||
| `from_role_name` | `TEXT` | FK -> `roles.name` | 发送角色 |
|
||
| `to_expr` | `TEXT` | NOT NULL | 原始收件表达式，例如 `backend`、`all` |
|
||
| `type` | `TEXT` | NOT NULL | `chat / proposal / question / decision / summary` |
|
||
| `stage` | `TEXT` | NOT NULL | `clarification / plan / review / freeze / execution / verification / discovery` |
|
||
| `round` | `INTEGER` | NULLABLE | 回合号 |
|
||
| `reply_to_message_id` | `TEXT` | FK -> `messages.id`, NULLABLE | 回复目标消息 |
|
||
| `body_markdown` | `TEXT` | NOT NULL | 消息正文 |
|
||
| `created_at` | `TEXT` | NOT NULL | 创建时间 |
|
||
|
||
关系：
|
||
|
||
- `messages N -> 1 workspaces`
|
||
- `messages N -> 1 topics`
|
||
- `messages N -> 1 roles`
|
||
- `messages N -> 1 messages`（`reply_to_message_id`）
|
||
- `messages 1 -> N message_deliveries`
|
||
|
||
### 5.13 `message_deliveries`
|
||
|
||
每个实际收件人的投递状态。
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `message_id` | `TEXT` | FK -> `messages.id` | 对应消息 |
|
||
| `recipient_role_name` | `TEXT` | FK -> `roles.name` | 实际收件角色 |
|
||
| `state` | `TEXT` | NOT NULL | `pending / received / read / archived` |
|
||
| `delivered_at` | `TEXT` | NOT NULL | 投递时间 |
|
||
| `read_at` | `TEXT` | NULLABLE | 已读时间 |
|
||
| `archived_at` | `TEXT` | NULLABLE | 归档时间 |
|
||
| `updated_at` | `TEXT` | NOT NULL | 更新时间 |
|
||
|
||
主键：
|
||
|
||
- `PRIMARY KEY (message_id, recipient_role_name)`
|
||
|
||
说明：
|
||
|
||
- `to: all` 会在这里展开成多条记录
|
||
|
||
|
||
- 它只表达“线程绑定”
|
||
- 不表达“这次执行的历史”
|
||
|
||
### 5.15 `requirements`
|
||
|
||
pool 阶段的结构化队列项。
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `id` | `TEXT` | PK | requirement ID |
|
||
| `workspace_id` | `TEXT` | FK -> `workspaces.id` | 所属工作区 |
|
||
| `topic_id` | `TEXT` | FK -> `topics.id` | 来源 topic |
|
||
| `title` | `TEXT` | NOT NULL | 标题 |
|
||
| `body_markdown` | `TEXT` | NOT NULL | 详细说明 |
|
||
| `status` | `TEXT` | NOT NULL | `pending / dispatched / completed / archived` |
|
||
| `priority` | `INTEGER` | NOT NULL | 优先级 |
|
||
| `created_by_role_name` | `TEXT` | FK -> `roles.name` | 创建角色，通常是 `product` |
|
||
| `created_at` | `TEXT` | NOT NULL | 创建时间 |
|
||
| `updated_at` | `TEXT` | NOT NULL | 更新时间 |
|
||
| `completed_at` | `TEXT` | NULLABLE | 完成时间 |
|
||
|
||
说明：
|
||
|
||
- `requirements` 以 `workspace + topic` 为来源
|
||
- 不再把 `project_id` 当成 requirement 的主归属
|
||
|
||
### 5.16 `discovery_rounds`
|
||
|
||
discovery 轮次主表。
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `id` | `TEXT` | PK | round ID |
|
||
| `workspace_id` | `TEXT` | FK -> `workspaces.id` | 所属工作区 |
|
||
| `topic_id` | `TEXT` | FK -> `topics.id` | 关联 topic |
|
||
| `phase` | `TEXT` | NOT NULL | `collecting / voting / completed / cancelled` |
|
||
| `request_document_id` | `TEXT` | FK -> `topic_documents.id`, NULLABLE | discovery request 文档 |
|
||
| `result_document_id` | `TEXT` | FK -> `topic_documents.id`, NULLABLE | discovery result 文档 |
|
||
| `started_at` | `TEXT` | NOT NULL | 开始时间 |
|
||
| `completed_at` | `TEXT` | NULLABLE | 完成时间 |
|
||
| `updated_at` | `TEXT` | NOT NULL | 更新时间 |
|
||
|
||
关系：
|
||
|
||
- `discovery_rounds N -> 1 workspaces`
|
||
- `discovery_rounds N -> 1 topics`
|
||
- `discovery_rounds 1 -> N discovery_candidates`
|
||
|
||
### 5.17 `discovery_candidates`
|
||
|
||
discovery 候选项结构化表。
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `id` | `TEXT` | PK | candidate ID |
|
||
| `round_id` | `TEXT` | FK -> `discovery_rounds.id` | 所属 round |
|
||
| `proposer_role_name` | `TEXT` | FK -> `roles.name` | 提出角色 |
|
||
| `status` | `TEXT` | NOT NULL | `draft / ready / accepted / rejected / archived` |
|
||
| `title` | `TEXT` | NOT NULL | 候选标题 |
|
||
| `problem` | `TEXT` | NOT NULL DEFAULT `''` | 问题描述 |
|
||
| `evidence` | `TEXT` | NOT NULL DEFAULT `''` | 证据 |
|
||
| `proposal` | `TEXT` | NOT NULL DEFAULT `''` | 提案内容 |
|
||
| `expected_impact` | `TEXT` | NOT NULL DEFAULT `''` | 预期收益 |
|
||
| `risk` | `TEXT` | NOT NULL DEFAULT `''` | 风险 |
|
||
| `how_to_verify` | `TEXT` | NOT NULL DEFAULT `''` | 验证方式 |
|
||
| `created_at` | `TEXT` | NOT NULL | 创建时间 |
|
||
| `updated_at` | `TEXT` | NOT NULL | 更新时间 |
|
||
|
||
关系：
|
||
|
||
- `discovery_candidates N -> 1 discovery_rounds`
|
||
- `discovery_candidates N -> 1 roles`
|
||
- `discovery_candidates 1 -> N discovery_votes`
|
||
|
||
### 5.18 `discovery_votes`
|
||
|
||
discovery 候选项投票表。
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `id` | `TEXT` | PK | vote ID |
|
||
| `round_id` | `TEXT` | FK -> `discovery_rounds.id` | 所属 round |
|
||
| `candidate_id` | `TEXT` | FK -> `discovery_candidates.id` | 所投候选项 |
|
||
| `voter_role_name` | `TEXT` | FK -> `roles.name` | 投票角色 |
|
||
| `vote` | `TEXT` | NOT NULL | `agree / reject / unclear` |
|
||
| `reason` | `TEXT` | NOT NULL DEFAULT `''` | 原因 |
|
||
| `created_at` | `TEXT` | NOT NULL | 创建时间 |
|
||
|
||
唯一约束：
|
||
|
||
- 每个角色对每个候选项最多投 1 票
|
||
|
||
### 5.19 `workflow_runs`
|
||
|
||
执行阶段主表。
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `id` | `TEXT` | PK | run ID |
|
||
| `workspace_id` | `TEXT` | FK -> `workspaces.id` | 所属工作区 |
|
||
| `topic_id` | `TEXT` | FK -> `topics.id` | 所属 topic |
|
||
| `role_name` | `TEXT` | FK -> `roles.name` | 执行角色 |
|
||
| `stage` | `TEXT` | NOT NULL | `plan / review / execution / verification` |
|
||
| `mode` | `TEXT` | NOT NULL DEFAULT `''` | 运行模式 |
|
||
| `status` | `TEXT` | NOT NULL | `running / succeeded / failed / cancelled` |
|
||
| `request_message_id` | `TEXT` | FK -> `messages.id`, NULLABLE | 触发消息 |
|
||
| `config_snapshot_json` | `TEXT` | NOT NULL DEFAULT `{}` | 启动时解析出的 prompt/config/skills 快照 |
|
||
| `command_json` | `TEXT` | NOT NULL DEFAULT `[]` | 执行命令快照 |
|
||
| `reply_message_id` | `TEXT` | FK -> `messages.id`, NULLABLE | 执行完成后的回复消息 |
|
||
| `exit_code` | `INTEGER` | NOT NULL DEFAULT `0` | 退出码 |
|
||
| `started_at` | `TEXT` | NOT NULL | 开始时间 |
|
||
| `completed_at` | `TEXT` | NULLABLE | 完成时间 |
|
||
| `error_message` | `TEXT` | NOT NULL DEFAULT `''` | 错误信息 |
|
||
|
||
说明：
|
||
|
||
- 新的 run 启动时必须把解析后的角色配置快照写入 `config_snapshot_json`
|
||
- 这样后续即使 prompt/config 被改动，历史 run 仍然可追溯
|
||
|
||
### 5.20 `workflow_run_logs`
|
||
|
||
执行日志流。
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `run_id` | `TEXT` | FK -> `workflow_runs.id` | 所属 run |
|
||
| `seq` | `INTEGER` | NOT NULL | 行序号 |
|
||
| `stream` | `TEXT` | NOT NULL | `stdout / stderr / system` |
|
||
| `content` | `TEXT` | NOT NULL | 日志内容 |
|
||
| `created_at` | `TEXT` | NOT NULL | 创建时间 |
|
||
|
||
主键：
|
||
|
||
- `PRIMARY KEY (run_id, seq)`
|
||
|
||
关系：
|
||
|
||
- `workflow_run_logs N -> 1 workflow_runs`
|
||
|
||
### 5.21 `merge_requests`
|
||
|
||
merge 请求记录。
|
||
|
||
| 字段 | 类型 | 约束 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `id` | `TEXT` | PK | merge request ID |
|
||
| `workspace_id` | `TEXT` | FK -> `workspaces.id` | 所属工作区 |
|
||
| `topic_id` | `TEXT` | FK -> `topics.id` | 所属 topic |
|
||
| `workflow_run_id` | `TEXT` | FK -> `workflow_runs.id`, NULLABLE | 来源执行记录 |
|
||
| `requested_by_role_name` | `TEXT` | FK -> `roles.name`, NULLABLE | 发起角色 |
|
||
| `target_branch` | `TEXT` | NOT NULL | 目标分支 |
|
||
| `status` | `TEXT` | NOT NULL | `pending / merged / failed / cancelled` |
|
||
| `summary` | `TEXT` | NOT NULL DEFAULT `''` | 摘要 |
|
||
| `files_changed` | `INTEGER` | NOT NULL DEFAULT `0` | 改动文件数 |
|
||
| `insertions` | `INTEGER` | NOT NULL DEFAULT `0` | 新增行数 |
|
||
| `deletions` | `INTEGER` | NOT NULL DEFAULT `0` | 删除行数 |
|
||
| `changed_files_json` | `TEXT` | NOT NULL DEFAULT `[]` | 改动文件列表 |
|
||
| `created_at` | `TEXT` | NOT NULL | 创建时间 |
|
||
| `merged_at` | `TEXT` | NULLABLE | 合并时间 |
|
||
| `error_message` | `TEXT` | NOT NULL DEFAULT `''` | 失败原因 |
|
||
|
||
关系：
|
||
|
||
- `merge_requests N -> 1 workspaces`
|
||
- `merge_requests N -> 1 topics`
|
||
- `merge_requests N -> 1 workflow_runs`
|
||
- `merge_requests N -> 1 roles`
|
||
|
||
## 6. 表关系图
|
||
|
||
```mermaid
|
||
erDiagram
|
||
PROJECTS ||--o{ WORKSPACES : has
|
||
WORKSPACES ||--o{ TOPICS : owns
|
||
WORKSPACES ||--o{ MESSAGES : owns
|
||
WORKSPACES ||--o{ REQUIREMENTS : owns
|
||
WORKSPACES ||--o{ DISCOVERY_ROUNDS : owns
|
||
WORKSPACES ||--o{ WORKFLOW_RUNS : owns
|
||
WORKSPACES ||--o{ MERGE_REQUESTS : owns
|
||
|
||
ROLES ||--o{ ROLE_PROMPTS : has
|
||
ROLES ||--o{ ROLE_CONFIGS : has
|
||
ROLES ||--o{ ROLE_SKILL_BINDINGS : binds
|
||
SKILLS ||--o{ ROLE_SKILL_BINDINGS : used_by
|
||
|
||
TOPICS ||--o{ TOPIC_DOCUMENTS : has
|
||
TOPICS ||--o{ MESSAGES : contains
|
||
TOPICS ||--o{ REQUIREMENTS : produces
|
||
TOPICS ||--o{ DISCOVERY_ROUNDS : drives
|
||
TOPICS ||--o{ WORKFLOW_RUNS : executes
|
||
TOPICS ||--o{ MERGE_REQUESTS : results_in
|
||
|
||
MESSAGES ||--o{ MESSAGE_DELIVERIES : fans_out
|
||
MESSAGES ||--o{ MESSAGES : replies_to
|
||
|
||
DISCOVERY_ROUNDS ||--o{ DISCOVERY_CANDIDATES : includes
|
||
DISCOVERY_CANDIDATES ||--o{ DISCOVERY_VOTES : receives
|
||
|
||
WORKFLOW_RUNS ||--o{ WORKFLOW_RUN_LOGS : emits
|
||
WORKFLOW_RUNS ||--o| MERGE_REQUESTS : may_create
|
||
```
|
||
|
||
## 7. 关系说明
|
||
|
||
### 7.1 配置关系
|
||
|
||
| 主表 | 从表 | 关系 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `roles` | `role_prompts` | 1:N | 一个角色可有多种 prompt kind，也可有 workspace override |
|
||
| `roles` | `role_configs` | 1:N | 一个角色可有全局配置和多个 workspace override |
|
||
| `roles` | `role_skill_bindings` | 1:N | 一个角色可绑定多个技能 |
|
||
| `skills` | `role_skill_bindings` | 1:N | 一个技能可被多个角色使用 |
|
||
| `workspaces` | `role_prompts / role_configs / role_skill_bindings` | 1:N | workspace 级覆盖配置 |
|
||
|
||
### 7.2 业务关系
|
||
|
||
| 主表 | 从表 | 关系 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `projects` | `workspaces` | 1:N | 一个项目下有多个工作区 |
|
||
| `workspaces` | `topics` | 1:N | 一个工作区下有多个 topic |
|
||
| `topics` | `topic_documents` | 1:N | 一个 topic 下有多种文档 |
|
||
| `topics` | `messages` | 1:N | 一个 topic 下有多条消息 |
|
||
| `messages` | `message_deliveries` | 1:N | 一条消息可投递给多个角色 |
|
||
| `topics` | `requirements` | 1:N | 一个 topic 可产生多个 requirement |
|
||
| `topics` | `discovery_rounds` | 1:N | 一个 topic 可有多轮 discovery |
|
||
| `discovery_rounds` | `discovery_candidates` | 1:N | 一轮 discovery 可有多个候选项 |
|
||
| `discovery_candidates` | `discovery_votes` | 1:N | 一个候选项可收到多个角色投票 |
|
||
| `topics` | `workflow_runs` | 1:N | 一个 topic 可有多次执行 |
|
||
| `workflow_runs` | `workflow_run_logs` | 1:N | 一次执行有多条日志 |
|
||
| `topics` | `merge_requests` | 1:N | 一个 topic 可产生多个 merge 请求 |
|
||
|
||
### 7.3 特殊关系
|
||
|
||
| 字段 | 关系 | 说明 |
|
||
| --- | --- | --- |
|
||
| `topics.source_topic_id` | 自关联 | topic 可从另一个 topic 派生 |
|
||
| `messages.reply_to_message_id` | 自关联 | 消息可回复另一条消息 |
|
||
| `discovery_rounds.request_document_id` | 指向 `topic_documents` | discovery 输入文档 |
|
||
| `discovery_rounds.result_document_id` | 指向 `topic_documents` | discovery 输出文档 |
|
||
| `workflow_runs.config_snapshot_json` | 快照，不是 FK | 保存运行时解析后的配置结果 |
|
||
|
||
## 8. 读取优先级
|
||
|
||
以下三张配置表都采用相同规则：
|
||
|
||
- `role_prompts`
|
||
- `role_configs`
|
||
- `role_skill_bindings`
|
||
|
||
读取顺序固定为：
|
||
|
||
1. 先查当前 `workspace_id` 的覆盖记录
|
||
2. 如果没有，再查全局默认记录
|
||
|
||
这个规则是 `v2` 的硬约束，服务端、测试和前端都按这套理解实现。
|
||
|
||
## 9. 写入规则
|
||
|
||
### 9.1 配置写入
|
||
|
||
当用户在前端修改：
|
||
|
||
- 角色
|
||
- 提示词
|
||
- 技能
|
||
- 角色配置
|
||
- 技能绑定
|
||
|
||
服务端必须同时做两件事：
|
||
|
||
1. 更新当前生效表
|
||
|
||
### 9.2 新执行启动
|
||
|
||
当新的 `workflow_runs` 启动时：
|
||
|
||
1. 解析角色最终生效配置
|
||
- prompt
|
||
- role config
|
||
- skill binding
|
||
- skill 内容
|
||
2. 将解析结果写入 `workflow_runs.config_snapshot_json`
|
||
3. 再启动实际执行
|
||
|
||
这样可以同时满足：
|
||
|
||
- 配置立即生效
|
||
- 历史执行可追溯
|
||
|
||
## 10. V2 明确不保留的旧表
|
||
|
||
| 旧表 | V2 处理 |
|
||
| --- | --- |
|
||
| `topic_records` | 删除，合并进 `topics` |
|
||
| `clarifier_state` | 删除，状态回归 `topics` |
|
||
| `clarifier_artifacts` | 删除，合并进 `topic_documents` |
|
||
| `message_mailboxes` | 改为 `message_deliveries` |
|
||
| `dispatches` | 改为 `workflow_runs` |
|
||
| `dispatch_live_lines` | 改为 `workflow_run_logs` |
|
||
| `discovery_round_proposals` | 删除，改为 `discovery_candidates` |
|
||
| `discovery_round_votes` JSON blob | 删除，改为结构化 `discovery_votes` |
|
||
|
||
## 11. 对开发的直接约束
|
||
|
||
这份文档对 `v2` 开发有三条直接约束：
|
||
|
||
1. 不允许再出现“同一业务对象散落多个旧表”的设计。
|
||
2. 不允许再把在线可编辑配置只放文件、不进数据库。
|
||
3. 不允许再把 discovery 和 workflow 的核心结构塞回 JSON blob。
|
||
|
||
这份文档就是 `inbox v2` 的数据库基线，后续如果要改，应该直接更新这份文档，而不是各模块各自理解一版。
|
||
|
||
## 当前工作流图扩展
|
||
|
||
当前运行时已经在 `chains` / `tasks` / `workflow_runs` 上扩展了 leader-managed graph 字段，作为后续 DAG planning 的基础。
|
||
|
||
### chains
|
||
|
||
除基础标识与运行态字段外，`chains` 当前还包含：
|
||
|
||
- `purpose`：这条 chain 的目标与职责摘要
|
||
|
||
### tasks
|
||
|
||
除基础标题、正文、状态、依赖字段外，`tasks` 当前还包含：
|
||
|
||
- `task_kind`
|
||
- `execution`
|
||
- `gate`
|
||
- `verification`
|
||
- `milestone`
|
||
- `gate_policy`
|
||
- `none`
|
||
- `hard_stop`
|
||
- `ask_user`
|
||
- `leader_replan`
|
||
- `deliverables_json`
|
||
- `verification_mode`
|
||
- `none`
|
||
- `auto`
|
||
- `human`
|
||
- `batch_key`
|
||
- `replan_policy`
|
||
- `patch`
|
||
- `clarify`
|
||
- `stop`
|
||
|
||
说明：
|
||
|
||
- `task_kind = milestone` 是当前 milestone 的落地方式，不单独建表。
|
||
- `gate` task 用于前置检查；存在 gate 时，其它 task 默认先不放行。
|
||
|
||
### workflow_runs
|
||
|
||
`leader` 的结构化 planning 结果当前会持久化到：
|
||
|
||
- `workflow_runs.command_json`
|
||
|
||
其中包含：
|
||
|
||
- `plan_version`
|
||
- `plan_mode`
|
||
- `replan_reason`
|
||
- `supersedes`
|
||
- `execution_mode`
|
||
- `leader_reply`
|
||
- `chains`
|
||
- `tasks`
|
||
- `start_nodes`
|
||
|
||
说明：
|
||
|
||
- 空图首次规划使用 `plan_mode = initial`
|
||
- 主题已有 graph 时，leader 必须使用 `plan_mode = patch`
|
||
- 当前系统不允许 patch 模式扩图；patch 只能复用现有 graph
|