初始化 agent_ops 文档治理体系
This commit is contained in:
@@ -0,0 +1,120 @@
|
||||
# 迭代工作流与四步法
|
||||
|
||||
**版本：** 2026-08-07
|
||||
**适用范围：** 所有后续 LineUp 迭代
|
||||
|
||||
## 1. 为什么要统一四步法
|
||||
|
||||
从 `04A.agent_tool_route` 开始，一次迭代不再只是某个前端仓的局部改动，而可能同时联动：
|
||||
|
||||
- Runtime
|
||||
- Adapter
|
||||
- AppServer
|
||||
- 协议文档
|
||||
- Host 验收
|
||||
- 联调与证据
|
||||
|
||||
如果没有统一方法，很容易出现：
|
||||
|
||||
- 规划写在一个地方；
|
||||
- 评审写在另一个地方；
|
||||
- 技术规范散落在实现仓；
|
||||
- 跨项目边界没有统一判断依据。
|
||||
|
||||
因此，从现在开始，每次迭代都至少经过四个固定步骤。
|
||||
|
||||
## 2. 固定四步
|
||||
|
||||
### 第一步：规划
|
||||
|
||||
目标：
|
||||
|
||||
- 说明为什么做这个迭代；
|
||||
- 冻结范围边界；
|
||||
- 说明涉及哪些项目和端；
|
||||
- 给出完成标准和不在范围内的内容。
|
||||
|
||||
标准产物：
|
||||
|
||||
- `01.迭代规划.md`
|
||||
|
||||
### 第二步：设计评审
|
||||
|
||||
目标：
|
||||
|
||||
- 用独立视角检查规划中的产品边界、架构边界、状态机和风险；
|
||||
- 清理 P0～P3 问题；
|
||||
- 把必须回填的结论反映回主规划文档。
|
||||
|
||||
标准产物：
|
||||
|
||||
- `02.设计评审.md`
|
||||
- 如有多轮，可继续编号：`03.设计评审（二）.md`、`04.设计评审（三）.md`
|
||||
|
||||
### 第三步：技术实施规范
|
||||
|
||||
目标：
|
||||
|
||||
- 把已经冻结的产品/架构结论映射到具体模块、协议、状态、存储、测试和验收实现；
|
||||
- 明确每个项目各自承担什么修改；
|
||||
- 说明跨仓联调和验证方式。
|
||||
|
||||
标准产物：
|
||||
|
||||
- `05.技术实施规范.md`
|
||||
|
||||
### 第四步：技术实施规范评审
|
||||
|
||||
目标：
|
||||
|
||||
- 检查技术规范是否真实覆盖冻结边界；
|
||||
- 识别实现层遗漏、跨仓接口风险、测试缺口和不可实施部分；
|
||||
- 清理 P0～P3 技术问题。
|
||||
|
||||
标准产物：
|
||||
|
||||
- `06.技术实施规范评审.md`
|
||||
- 如有第二轮，可继续编号
|
||||
|
||||
## 3. 实施后的补充步骤
|
||||
|
||||
虽然用户当前强调的是四步法，但一个完整迭代通常还需要：
|
||||
|
||||
- 实施
|
||||
- 验收评审
|
||||
- 证据归档
|
||||
|
||||
因此建议默认继续补齐：
|
||||
|
||||
- `08.验收评审.md`
|
||||
- `09.验收评审（二）.md`
|
||||
- `evidence/`
|
||||
|
||||
## 4. 进入实现的门槛
|
||||
|
||||
每个迭代在开始大规模实现前，至少应满足：
|
||||
|
||||
1. 主规划文档已写明范围与完成标准；
|
||||
2. 设计评审中的 P0～P3 已清零；
|
||||
3. 技术实施规范已把跨项目责任拆开；
|
||||
4. 技术实施规范评审中的 P0～P3 已清零。
|
||||
|
||||
## 5. 状态定义
|
||||
|
||||
建议统一使用以下阶段状态：
|
||||
|
||||
- `规划中`
|
||||
- `设计评审中`
|
||||
- `技术规范中`
|
||||
- `技术评审中`
|
||||
- `开发实施中`
|
||||
- `待验收`
|
||||
- `已完成`
|
||||
- `已归档`
|
||||
|
||||
## 6. 这套方法的核心收益
|
||||
|
||||
- 让每次迭代都有统一入口；
|
||||
- 让跨项目修改不再只挂在某一个代码仓名下；
|
||||
- 让设计结论、技术规范和验收标准之间形成可追溯链路；
|
||||
- 让后续 agent 可以稳定接手迭代文档工作。
|
||||
@@ -0,0 +1,62 @@
|
||||
# 迭代目录与命名规范
|
||||
|
||||
**版本：** 2026-08-07
|
||||
**适用范围：** `agent_ops/03.迭代规划/` 下的新迭代目录
|
||||
|
||||
## 1. 迭代目录命名
|
||||
|
||||
迭代目录统一使用：
|
||||
|
||||
```text
|
||||
<迭代编号>.<简短名称>/
|
||||
```
|
||||
|
||||
例如：
|
||||
|
||||
- `04.runtime_workspace/`
|
||||
- `04A.agent_tool_route/`
|
||||
- `05.first_isolated_miniapp/`
|
||||
|
||||
## 2. 每个迭代目录的推荐结构
|
||||
|
||||
```text
|
||||
<迭代目录>/
|
||||
├── 01.迭代规划.md
|
||||
├── 02.设计评审.md
|
||||
├── 03.设计评审（二）.md # 按需要增加
|
||||
├── 05.技术实施规范.md
|
||||
├── 06.技术实施规范评审.md
|
||||
├── 07.技术实施规范评审（二）.md # 按需要增加
|
||||
├── 08.验收评审.md
|
||||
├── 09.验收评审（二）.md # 按需要增加
|
||||
└── evidence/
|
||||
```
|
||||
|
||||
## 3. 命名原则
|
||||
|
||||
- 主规划始终用 `01.迭代规划.md`
|
||||
- 第一轮设计评审固定用 `02.设计评审.md`
|
||||
- 技术实施规范固定用 `05.技术实施规范.md`
|
||||
- 技术实施规范评审固定用 `06.技术实施规范评审.md`
|
||||
- 验收评审从 `08` 开始，避免和前四步混淆
|
||||
|
||||
## 4. 为什么保留编号空位
|
||||
|
||||
保留 `03 / 04 / 07 / 09` 等位置，是为了支持：
|
||||
|
||||
- 多轮设计评审；
|
||||
- 多轮技术规范评审；
|
||||
- 多轮验收评审；
|
||||
- 不打乱主文件的稳定编号。
|
||||
|
||||
## 5. 跨项目迭代的写法
|
||||
|
||||
从 `04A` 开始，主规划和技术规范都必须明确写出涉及项目，例如：
|
||||
|
||||
- `lineup-app`
|
||||
- `lineup-adapter/hermes`
|
||||
- `lineup-app-server`
|
||||
- `infra/wukongim-v3`
|
||||
- 文档目录本身
|
||||
|
||||
不能再把跨项目迭代只写成某一个仓的局部事项。
|
||||
@@ -0,0 +1,65 @@
|
||||
# 跨项目迭代边界与协作方式
|
||||
|
||||
**版本：** 2026-08-07
|
||||
**适用范围：** 从 `04A.agent_tool_route` 开始的跨项目迭代
|
||||
|
||||
## 1. 当前现实
|
||||
|
||||
从 `04A` 开始，一次迭代已经不再只作用于 `lineup-app/`。
|
||||
|
||||
一个完整闭环可能同时涉及：
|
||||
|
||||
- `lineup-app/`：Runtime、Host、UI、SDK
|
||||
- `lineup-adapter/hermes/`：协议转换、Agent 兼容层
|
||||
- `lineup-app-server/`：必要时的传输边界
|
||||
- `agent_ops/`：规划、设计、协议与验收文档
|
||||
|
||||
因此，迭代必须以“能力闭环”为单位，而不是以“某个仓库”命名。
|
||||
|
||||
## 2. 规划时必须写清的三件事
|
||||
|
||||
### 2.1 涉及哪些项目
|
||||
|
||||
每份 `01.迭代规划.md` 都必须列清：
|
||||
|
||||
- 主要改动项目；
|
||||
- 次要联动项目；
|
||||
- 只需验证、不需修改的项目。
|
||||
|
||||
### 2.2 哪个项目负责什么
|
||||
|
||||
规划和技术规范都要写清：
|
||||
|
||||
- Runtime 责任；
|
||||
- Adapter 责任；
|
||||
- 服务端责任；
|
||||
- Host / 验收责任；
|
||||
- 文档与协议责任。
|
||||
|
||||
### 2.3 哪些层不应被修改
|
||||
|
||||
跨项目迭代最常见的问题，不是“漏改一个文件”，而是“把不该动的边界动了”。
|
||||
|
||||
所以规划里必须明确：
|
||||
|
||||
- 哪一层是执行权威；
|
||||
- 哪一层只做兼容；
|
||||
- 哪一层视为透明传输；
|
||||
- 哪些旧语义在本轮保持不变。
|
||||
|
||||
## 3. 评审时的检查顺序
|
||||
|
||||
跨项目迭代建议按以下顺序评审：
|
||||
|
||||
1. 先看产品与架构边界是否清楚；
|
||||
2. 再看跨仓责任是否分清；
|
||||
3. 再看协议与状态机是否闭环；
|
||||
4. 最后看实施和验收能否真正跨端跑通。
|
||||
|
||||
## 4. 当前统一入口
|
||||
|
||||
从现在开始：
|
||||
|
||||
- 迭代规划、设计评审、技术规范、技术评审都在 `agent_ops/03.迭代规划/` 下组织；
|
||||
- 具体实现仍分布在各代码仓；
|
||||
- 但“本次迭代到底在做什么”只在这里定义和冻结。
|
||||
@@ -0,0 +1,54 @@
|
||||
# LineUp App 迭代文档
|
||||
|
||||
每个迭代使用一个独立目录，目录名固定为“迭代编号.简短名称”。目录内至少保留该迭代的主定义文档；
|
||||
每进行一次设计、架构或实现评审，都必须新增一份独立评审记录，不覆盖之前的记录。
|
||||
|
||||
```text
|
||||
迭代/
|
||||
├── plan.md # 当前阶段之后的总体路线和排期原则
|
||||
├── 00.base/
|
||||
│ └── 00.base.md
|
||||
├── 01.kernel/
|
||||
│ └── 01.kernel.md
|
||||
└── 03.sdk_and_coreapp/
|
||||
├── 03.sdk_and_coreapp.md # 本迭代的权威目标、范围、契约、步骤和验收
|
||||
├── 01.design_review.md # 第 1 次评审记录
|
||||
├── 02.design_review.md # 第 2 次评审记录
|
||||
└── 03.design_review.md # 第 3 次评审记录
|
||||
```
|
||||
|
||||
约定如下：
|
||||
|
||||
1. 主定义文档命名为 `<迭代目录名>.md`，是当前实施依据；
|
||||
2. 评审记录按发生顺序编号，命名为 `<两位序号>.design_review.md`；
|
||||
3. 每份评审记录必须在元信息之后、评审正文之前维护“问题清单（Outline）”，格式参考
|
||||
[`01.design_review.md`](03.sdk_and_coreapp/01.design_review.md)：列出状态、编号、问题和当前结论/下一步；
|
||||
4. 评审记录必须写明评审日期、编号、对象、方式和总体结论。新问题先在 Outline 中登记；问题确认后先
|
||||
更新 Outline 状态，再回填主定义文档、验收项和评审正文；
|
||||
5. 已确认的结论需要回填主定义文档和验收项；评审记录保留原始意见，用于追溯，不能替代主定义文档；
|
||||
6. 迭代完成后的实现验收、发布复盘等文档也保留在对应目录内，并使用清晰的递增编号。
|
||||
|
||||
## 后续总计划
|
||||
|
||||
当前阶段之后的路线、迭代拆分、范围边界和完成标准见 [plan.md](plan.md)。该文件记录已确认的整体方向；
|
||||
每个具体迭代开始后，仍需在自己的目录中创建主定义文档和独立评审记录。
|
||||
|
||||
## 评审优先级与遗留问题
|
||||
|
||||
评审问题使用 `P0`～`P5` 标示处理优先级。优先级表达的是“最晚何时必须解决”，而不是问题描述的
|
||||
修辞强弱。
|
||||
|
||||
| 级别 | 含义 | 当前迭代的处理规则 |
|
||||
|---|---|---|
|
||||
| P0 | 根本性阻塞：安全边界、数据正确性或总体架构不能成立。 | 立即处理；在解决前不得进入相关实现。 |
|
||||
| P1 | 关键规则未定：不解决会让不同实现互相冲突或明显返工。 | 在开始相关模块实现前处理。 |
|
||||
| P2 | 交付或验收缺口：核心方向正确，但缺失会使恢复、安全验证或验收不完整。 | 必须在本迭代验收前处理。 |
|
||||
| P3 | 局部行为、一致性或质量问题：存在安全默认行为，但相关模块完成前仍需收敛。 | 必须在本迭代结束前处理。 |
|
||||
| P4 | 优化、可读性或维护性建议。 | 可以登记为遗留问题，不阻塞当前迭代。 |
|
||||
| P5 | 观察记录或未来机会，当前没有足够的产品需求或证据进入排期。 | 可以登记为遗留问题，不纳入当前迭代。 |
|
||||
|
||||
因此，**P0～P3 必须在当前迭代处理完毕，P4～P5 可以作为遗留问题延期处理。**
|
||||
|
||||
延期不是删除：评审中出现 P4/P5 时，必须在该评审文件的 Outline 或“遗留问题”段落中保留编号、问题、
|
||||
延期原因和建议重新评估的阶段/条件。只有在对应迭代主定义文档或新的评审记录中明确重新纳入后，才将
|
||||
其提升为当前迭代的 P0～P3 问题。
|
||||
Reference in New Issue
Block a user