ai-workflow/docs/inbox-v2-database.md

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. 表关系图

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