FlexGodX/自主代理开发周期

自主代理开发周期（质量门控流水线）

本技能形式化了在自主创建 Quest Nova（Flutter + Go + PostgreSQL 16 + Drift/SQLite）期间开发和验证的5阶段工程工作流和多代理仲裁流水线。

它保证了高架构保真度、零数据丢失、严格的安全性（零信任/IDOR）以及在无需人工干预的情况下经过数学验证的分布式同步。

[!NOTE] 逆向工程已排除： 逆向工程阶段已被省略/禁用。流水线直接从目标定义和功能规范编写（或接受现有的产品简介作为输入）开始。

---

1. 核心架构原则

1. 零中断自主性： 编排器自主推进所有阶段。确认仅来自严格的质量门控审计，而非用户询问。
2. 清洁上下文独立验证： 评审者和法官作为具备清洁上下文的专用子代理生成（他们仅接收可验证的目标工件、参考规范和明确的评估标准——不受先前聊天推理的影响）。
3. 全体一致批准屏障： 除非所有审计者/法官明确给出 APPROVED 裁决，否则无法进入下一阶段。缺陷列表（CHANGES_REQUESTED）会触发立即的修正-重新审计循环。
4. 备用模型路由： 当主要推理模型遇到速率限制（例如 HTTP 429 配额耗尽）时，流水线无缝地将任务路由到可用的高吞吐量模型（例如 Gemini 3.8 Flash），同时严格保持代理角色和清洁上下文边界。

---

2. 5阶段流水线

flowchart TD
    P1["阶段 1: 目标制定与功能规范"] --> QG1{"质量门控 1: 规范审计"}
    QG1 -->|"CHANGES_REQUESTED"| P1Fix["规范缺陷修正"]
    P1Fix --> QG1
    QG1 -->|"APPROVED (全体一致)"| P2["阶段 2: 系统设计与架构"]
    P2 --> QG2{"质量门控 2: 三代理法庭"}
    QG2 -->|"CHANGES_REQUESTED"| P2Fix["架构优化"]
    P2Fix --> QG2
    QG2 -->|"APPROVED (全体一致)"| P3["阶段 3: QA工件与实现计划"]
    P3 --> QG3{"质量门控 3: 可追溯性交叉审查"}
    QG3 -->|"CHANGES_REQUESTED"| P3Fix["计划与QA对齐"]
    P3Fix --> QG3
    QG3 -->|"APPROVED (全体一致)"| P4["阶段 4: 实现 (后端 + 客户端)"]
    P4 --> P5["阶段 5: 完整验证、压力测试与发布"]

---

3. 工件命名约定

流水线产生的每个工件都是一个版本化文件。切勿原地覆盖工件——而是创建下一个版本。

<ARTIFACT-NAME>-<date>-<NN>.md

• <ARTIFACT-NAME> — 工件的大写蛇形名称：GOAL、SPECIFICATION、DESIGN、QA_ARTIFACT、IMPLEMENTATION_PLAN、RELEASE_NOTES。
• <date> — ISO 格式 YYYY-MM-DD 的创建日期。
• <NN> — 两位序列号（01，02，...），用于区分同一天内创建的相同名称的工件。在给定日期的第一个工件上从 01 开始，并在当天对该相同工件的每次后续修订递增。该计数器按工件名称独立计数，因此同一天创建的不同工件可以共享相同的编号（例如 GOAL-2026-11-10-01.md 和 DESIGN-2026-11-10-01.md）。新的一天计数器重新从 01 开始。

示例：

工件	当天的第一个工件	当天的第二个工件
目标	docs/GOAL-2026-11-10-01.md	docs/GOAL-2026-11-10-02.md
规范	docs/SPECIFICATION-2026-11-10-01.md	docs/SPECIFICATION-2026-11-10-02.md
设计	docs/DESIGN-2026-11-10-01.md	docs/DESIGN-2026-11-10-02.md

规则：

1. 阶段交付物以及所有交叉引用（质量门控提示、计划、发布说明）必须引用确切的版本化文件名，决不能引用像 docs/GOAL.md 这样的无版本名称。
2. 工件名称的最高 <NN> 是当前权威版本；早期版本保持不变作为审计线索。
3. 质量门控审计提交给它们的特定版本，并在其裁决中记录该文件名。

在本技能中，<date> 和 <NN> 代表上面描述的日期和序列号。

---

4. 分阶段执行指南

阶段 1: 目标制定与功能规范（质量门控 1）

• 目标： 直接根据需求/简介制定明确的系统边界、用户循环、领域模型和技术规范。
• 交付物：
  • docs/GOAL-<date>-<NN>.md：全局系统范围、核心不变量、完成定义（DoD）。
  • docs/SPECIFICATION-<date>-<NN>.md：实体模式、时间机制、同步协议、OCC版本控制、三向合并规则、IDOR保护、DDL模式。
• 质量门控 1（清洁上下文审计者）：
  • 生成子代理（typeName: "research"）。
  • 仅提供 docs/SPECIFICATION-<date>-<NN>.md 和标准（完整性、安全性、数据完整性、一致性）。
  • 循环直到 APPROVED。

阶段 2: 系统设计与“三代理法庭”（质量门控 2）

• 目标： 构建可扩展、容错的后端和响应式客户端。
• 交付物： docs/DESIGN-<date>-<NN>.md（系统设计文档：后端、客户端、安全性）。
• 质量门控 2（三代理法庭）： 生成3个具有清洁上下文的独立子代理：
  1. 法官 1（后端与系统架构师）： 评估数据库模式、事务边界、行级锁、拓扑DAG排序、分区方案和OCC。
  2. 法官 2（客户端与UI架构师）： 评估离线优先数据库（Drift/SQLite）、后台隔离区、帧预算（< 16.6 ms）、变异队列合并和BLoC状态机。
  3. 法官 3（安全与边界情况审查者）： 识别竞争条件、冷启动死锁、回显循环、令牌重放（RTR）、会话窃取和IDOR漏洞。
  • 所有3位法官必须在继续之前返回 APPROVED。

阶段 3: QA工件、可追溯性计划与质量门控 3

• 目标： 在编写代码之前确保规范、架构和测试之间100%的双向可追溯性。
• 交付物：
  • docs/QA_ARTIFACT-<date>-<NN>.md：完整的验收标准（AC-XX）、单元测试、集成测试、分布式同步测试（TC-SYNC-XX）和压力测试场景（STRESS-XX）。
  • docs/IMPLEMENTATION_PLAN-<date>-<NN>.md：分阶段任务分解，直接映射到QA用例。
• 质量门控 3（交叉审计者）：
  • 验证 docs/QA_ARTIFACT-<date>-<NN>.md 中的每个验收标准和边界情况是否直接映射到 docs/IMPLEMENTATION_PLAN-<date>-<NN>.md 中的一个实现步骤。
  • 循环直到 APPROVED。

阶段 4: 实现与测试验证

1. 数据库迁移： 应用所有具有复合索引和分区的DDL迁移。
2. 后端引擎：
   • 整洁架构：domain/、repository/、usecase/、delivery/http/。
   • 单元与集成测试执行：cd backend && go test -v ./...。
3. 客户端引擎：
   • 核心时间工具（PlainDate、FloatingTime、SparseSortOrder）。
   • 三向差异合并引擎（5个检查清单场景，零数据丢失说明）。
   • 原地变异合并与飞行中竞争处理（MutationQueueManager）。
   • BLoC架构与自适应UI（桌面三窗格 + 移动导航）。
   • 客户端测试执行：cd client && flutter test。
   • Linter验证：cd client && flutter analyze（0个问题）。

阶段 5: 压力测试、发布与移交

1. 分布式同步验证： 执行多设备并发、OCC冲突、回显抑制和HTTP 410引导协调。
2. 压力测试：
   • 数据库连接池饱和（STRESS-01）：并发工作线程，0个泄漏点。
   • UI帧预算基准测试（STRESS-02）：在 < 16.6 ms 内处理1000个任务（稳定60/120 FPS）。
3. 工件编译：
   • 构建原生后端二进制文件：go build -o bin/<service> cmd/<service>/main.go。
   • 构建客户端包：flutter build bundle / flutter build macos / flutter build web。
4. 发布说明： 生成 docs/RELEASE_NOTES-<date>-<NN>.md，记录经过验证的指标、DoD检查清单和运行说明。

---

5. 审计者与法官提示模板

关于在质量门控1、2和3中调用清洁上下文子代理时使用的提示模板，请参阅 references/auditor_prompts.md。