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

Inbox V2 P1

本文档定义 inbox v2 的 P1 范围。
P1 只包含“独立模块”。

这里的独立模块，不是指“所有包彼此完全隔离”，而是指：

• 不依赖 store、runtime、agent runner、HTTP route、app service
• 可以单独实现、单独测试
• 可以作为后续 HTTP、app service、store、client 的公共基础
• 允许按分层方向依赖更底层的 P1 模块

换句话说：

• P1 要先固定“底层规则和模型”
• P1 不要先混入“流程装配和基础设施”
• P1 内部允许存在清晰的自底向上依赖

P1 的目标不是先把服务跑起来，而是先把最底层、最稳定、最可复用的规则和模型固定下来。

数据库设计草案见 docs/inbox-v2-database.md。

背景

inbox v2 的主线已经明确：

• HTTP 是唯一业务入口
• server 是唯一正式启动入口
• CLI 只是给 AI 使用的 HTTP 封装
• clarifier 角色移除
• product 接管需求整理，并继续输出：
  • PRD
  • Decision Log
• discovery 保留
• 交互路径暂时保持：
  • discovery
  • 需求整理
  • pool
  • workflow

在这条主线下，最先该实现的不是 server，也不是 client，而是底层独立模块。

P1 设计原则

1. P1 模块必须独立于基础设施层，但允许依赖更底层的 P1 模块。
2. P1 模块优先承载“稳定规则”，而不是“流程编排”。
3. P1 模块一旦定型，后续 P2/P3 都应复用它们，而不是复制一份。
4. P1 模块必须有单元测试。
5. P1 不实现 HTTP route、不实现 runtime 装配、不实现数据库。

P1 分层

为了让后续实现可落地，P1 采用下面这套分层：

层级	类型	可以依赖
L0	基础工具	Go 标准库
L1	文档规范	L0 + Go 标准库
L2	核心领域	L0/L1 + Go 标准库
L3	领域组合规则	L0/L1/L2 + Go 标准库

约束只有一条：

• 依赖只能向下，不能横向乱连，更不能回依赖 P2/P3

P1 模块清单

下面这些是 inbox v2 第一阶段应先落下的独立模块。

模块	建议路径	作用	说明
时间模块	internal/base/timeutil	UTC 时间、标准时间格式、可注入 clock	给记录、文档更新时间、事件时间统一格式
标识符模块	internal/base/idgen	topic / message / requirement / merge request 等 ID 生成规则	先固定命名和生成策略
slug 模块	internal/base/slug	topic、workspace、project 的 slug 规范化	这是所有上层都会复用的基础规则
HTTP 通用模块	internal/base/httpx	状态错误、JSON 编解码、通用响应封装	只做 transport 基础工具，不做具体业务
文档模板模块	internal/domain/docspec	PRD、Decision Log、Discovery request/result 的模板与渲染规则	product 将直接依赖它
消息模块	internal/domain/message	message envelope、front matter 解析、渲染、收件人规则	统一所有消息文档格式
Topic 模块	internal/domain/topic	topic 的 space/status 生命周期规则	明确 clarify/pool/workflow/discovery 的推进规则
Role 模块	internal/domain/role	角色分类、角色定义、角色能力边界	包括 product、backend、frontend、reviewer、discovery 系列
Requirement 模块	internal/domain/requirement	requirement 的结构、状态、优先级与验证规则	pool 的结构化实体先独立出来
Discovery 模块	internal/domain/discovery	discovery 提案、投票、共识计算、结果文档规则	保留 discovery 的核心领域逻辑
Workflow 模块	internal/domain/workflow	workflow 阶段枚举、阶段合法流转、角色协作规则	只管规则，不管看板聚合
Merge 模块	internal/domain/merge	merge request 状态、元数据结构、状态流转规则	只管领域规则，不管 git 命令

P1 依赖关系

下面是建议的依赖方向。

模块	层级	可依赖模块
timeutil	L0	无
slug	L0	无
idgen	L0	timeutil, slug
httpx	L0	无
docspec	L1	timeutil
role	L2	无
topic	L2	slug
workflow	L2	role, topic
requirement	L2	slug
merge	L2	timeutil, idgen, slug
message	L3	role, topic, workflow, slug, timeutil
discovery	L3	role, docspec, idgen, timeutil, slug

这张表的意义是：

• P1 仍然是独立模块集合
• 但不是人为禁止复用
• 后续实现时可以从 L0 往上逐层推进

P1 模块详细职责

1. timeutil

负责：

• NowUTC()
• RFC3339 / RFC3339Nano 格式化
• 可注入 clock

不负责：

• 调度
• 轮询
• timeout 策略

2. idgen

负责：

• message ID 规则
• requirement ID 规则
• merge request ID 规则
• discovery round ID / candidate ID 规则

不负责：

• 数据库存储
• 去重查询

3. slug

负责：

• topic slugify
• workspace slugify
• project slugify
• 安全截断规则

不负责：

• 校验是否重名
• 路径解析

4. httpx

负责：

• WriteJSON
• WriteError
• ErrorWithStatus
• 通用 JSON decode 辅助
• CORS 等通用 transport helper

不负责：

• route 注册
• 业务 request/response

5. docspec

这是 P1 里非常关键的模块。

负责：

• PRD 模板
• Decision Log 模板
• Discovery request 文档格式
• Discovery result 文档格式
• 文档 front matter 规范
• 文档固定章节顺序

不负责：

• 文档存储
• 文档版本管理
• 文档归属权限

这里要明确：

• 第二版中 product 会直接使用 PRD 和 Decision Log
• 模板沿用当前澄清模板，但所有权从 clarifier 转到 product

6. message

负责：

• message envelope 结构
• YAML front matter 解析
• markdown 渲染
• from / to / type / topic / stage / reply_to / round 规则
• 收件人解析
• 基础合法性校验
• 面向消息文档的稳定结构定义

不负责：

• 消息存储
• mailbox 查询
• HTTP handler

7. topic

负责：

• topic space
  • clarify
  • pool
  • workflow
  • discovery
• topic status
• space/status 的默认值
• 合法推进规则
• “能升不能降”之类的基础约束

不负责：

• topic record 存储
• topic 列表聚合

注意：

虽然 v2 去掉 clarifier 角色，但 clarify 这个对话整理阶段可以在兼容期继续存在；只是它背后的角色从 clarifier 变成 product。

8. role

负责：

• 角色枚举和分类
• 角色合法性校验
• 角色阶段边界
• 哪些角色属于 discovery
• 哪些角色属于 workflow
• product 的正式职责定义

不负责：

• role 存储
• role 技能绑定

9. requirement

负责：

• requirement 结构
• requirement 状态
  • pending
  • dispatched
  • completed
  • archived
• 优先级范围和校验
• requirement 文本字段校验

不负责：

• requirement 查询
• requirement dispatch 执行

10. discovery

负责：

• discovery candidate 结构
• vote 结构
• 共识判断
• result markdown 生成
• discovery request 文本格式规则
• discovery 阶段的固定角色集合规则

不负责：

• 并发执行
• codex 调用
• round 持久化

11. workflow

负责：

• workflow 阶段枚举
  • plan
  • review
  • execution
  • verification
• workflow 阶段流转规则
• workflow 角色协作边界
• workflow 消息的基础规则

不负责：

• workflow board 聚合
• dispatch 查询

12. merge

负责：

• merge request 结构
• merge request 状态流转
• merge metadata 规则

不负责：

• git diff
• merge 命令执行

P1 明确不做的东西

下面这些不属于 P1：

• server
• client
• http route
• app service
• store
• runtime
• agent runner
• workflow board
• pool dispatch
• merge 的 git 执行

这些模块都依赖更高层或外部设施，不属于独立底层模块。

P1 实现顺序

建议顺序如下：

1. timeutil
2. slug
3. idgen
4. httpx
5. docspec
6. role
7. topic
8. workflow
9. requirement
10. merge
11. message
12. discovery

原因很简单：

• 先做通用基础能力
• 再做文档规范
• 再做核心领域规则
• 最后做组合型领域模块
• 最后才进入 P2 的 server/app/store

P1 输出结果

P1 完成后，应该得到这些结果：

1. 一组独立于基础设施的底层模块。
2. 一组稳定的领域结构、模板和状态流转规则。
3. 第二版可以明确复用的文档标准：
   • PRD
   • Decision Log
   • Discovery request
   • Discovery result
4. 一套从 L0 -> L3 的清晰依赖方向。
5. 后续 P2 实现 HTTP server 和 app services 时，不再需要重新发明这些规则。

P1 完成标准

满足下面条件，P1 才算完成：

1. 上述每个模块都有明确目录。
2. 每个模块都有单元测试。
3. 每个模块都只依赖下层 P1 模块，不依赖任何 P2/P3 模块。
4. 文档模板和领域规则已经固定。
5. product 接管需求文档这一决策已经在底层模型中可以表达。