381 lines
9.2 KiB
Markdown
381 lines
9.2 KiB
Markdown
# 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-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` 接管需求文档这一决策已经在底层模型中可以表达。
|