编年史 · 第五篇 · 可迁移经验（AI生成）

前言： 以下模式是在 28 天、600 会话、893 commits 中反复出现的做法。它们不是理论，是被验证过的。后续新项目可以直接复用或调整。

模式一：分阶段落地

一句话： 设计→审计→修复→下一阶段，每次只做一件事。

标准节奏

设计（纯文档）→ 自己审查/Agent 审查 → 修复歧义 → 阶段冻结
     ↓
编码（逐 Phase）→ Phase 内测 → 交叉审计 → 批修复 → Phase 冻结
     ↓
下一 Phase

实例（v2）

Phase 设计 编码 审计轮次 修复 耗时
Phase 1（服务端） 7/9 7/10 Type A × 3 A/B 两组 1 天
Phase 2（数据层） 7/9 7/10~7/11 Type B × 3 A/B 两组 1.5 天
Phase 3（UI 全量） 7/4~7/8 7/11 Type C × 3 多轮 1 天
Phase T（教师端） 7/10 7/11 Type D × 3 穿插 1 天
Phase 4（辅助系统） 7/9 7/11~7/14 综合 连续 3 天

关键发现： 设计期（7/37/9）投入 7 天，换来编码期（7/107/16）每 Phase 只需 1~3 天。设计投入是加速器，不是拖慢。

新项目可直接用的检查清单

□ 设计文档是否覆盖了：架构/API/数据库/UI原型？
□ 是否有 HTML 原型（比文字描述更快达成一致）？
□ 编码前是否有审计 checklist？
□ 每个 Phase 结束后是否有修复缓冲期？
□ Phase 间的依赖是否清晰（能否并行）？

模式二：五维度并行审计

一句话： 不是全部写完后再审计，而是每个 Phase 完成后立即审计。

审计维度

类型 审计范围 频次 工具
Type A — 服务端 API 实现 vs 设计文档、数据一致性 Phase 轮次 代码读取 + 测试
Type B — 数据层 DAO/Repository 实现 vs 设计 Phase 轮次 代码读取 + DB 查询
Type C — Flutter UI UI 实现 vs HTML 原型、布局割裂 Phase 轮次 Widget Test + 视觉检查
Type D — 教师端 教师 App vs 学生端一致性 Phase 轮次 代码对比
Type E — 部署 CI、安全性、环境变量、域名 发布前 手动检查

演进路径

第1轮（7/11）：手动审计，你逐项列问题
   ↓
第2轮（7/11）：Agent 子代理并行审计（5 维度同时跑）
   ↓
第3轮（7/11~7/12）：Agent 子代理 + 自动化验证脚本
   ↓
第4轮（7/12~7/13）：加入 Visual E2E Audit（winnav 桌面自动化）
   ↓
最终（7/14+）：跨切探查（横切局部，深挖到根因）

新项目可直接用的审计 checklist

服务端:
□ API 路径是否与设计文档一致？
□ 字段名/类型是否与设计一致？
□ 错误码是否规范化？
□ 权限控制是否正确？

Flutter:
□ Widget 实现是否与 HTML 原型一致？
□ 水平 padding/margin 是否统一？
□ 空状态/加载态/错误态是否都有？
□ 点击是否防抖/防重复？

数据层:
□ DAO 方法是否覆盖增删改查？
□ 同步队列是否覆盖离线场景？
□ 数据库迁移是否兼容已有数据？

模式三：跨切探查（Cross-Cut Investigation）

一句话： 不按模块查 bug，按主题横切全栈。

做法

选定一个主题（如"积分"、“筛选”、“同步”），沿着这个主题横切：

UI 层 → Repository/数据流 → 本地数据层（Drift）→ 服务端 API → 边界情况/异常处理

实例（“筛选"主题的跨切探查）

UI 层:     FilterPanel 空维度提示、全选/取消按钮状态、排序面板
数据流:    applyFilter 调用时序、FilterState 状态管理
数据层:    PreferenceDao 查询、筛选条件持久化
服务端:    筛选参数传递、API 响应格式
边界情况:  所有维度全未选、编辑已有偏好时覆盖、快速点击切换

为什么有效

传统 bug 排查按文件/模块分，容易漏跨层问题。跨切探查保证：

  1. 不遗漏 — 每个主题走完完整链路
  2. 发现跨层 bug — 如"UI 传参正常但服务端忽略某些字段"这类只有跨层才能发现的问题
  3. 一次性 — 一次探查解决一个主题域的所有问题，不用反复回头

在 v2 中的效果

11 个跨切探查，覆盖了全部核心功能模块，每次平均发现 10-30 个问题。这是 v2 质量的核心保障。

模式四：fix-batch-workflow

一句话： 先出方案，等你确认，再执行，然后验证。

标准流程

核实问题（复现/读代码确认）
    ↓
出修复方案（改哪些文件、怎么改）
    ↓
等审批（"执行吧" = 全权授权）
    ↓
批量执行（写文件、改代码）
    ↓
验证（读文件确认落盘、跑测试）
    ↓
提交（一批一个问题 commit）

关键纪律

规则 原因
不逐条确认 → 你说"执行吧"即全权授权 减少来回，提高效率
批次间仍需问"继续” 给你留控制权，防止翻车
修完后对照原设计文档重查 避免修复引入新问题
先 commit 再 polish 保持进度节奏
每个 commit 只解决一批相关问题 方便回滚和审查

在 v2 中的效果

至少 10+ 轮 fix-batch 流程，从 7/11 到 7/17 贯穿全程。是本项目最高效的 bug 处理模式。

模式五：代码复用路径

一句话： 能复制就别抽象；真重复了再抽共享包。

三阶段演进

第1阶段（7/11）：教师端代码从学生端复制后改
  └─ 成本：快，但有重复代码（17 对重复组件）

第2阶段（7/14~7/15）：意识到重复成本 > 抽取成本
  └─ 决策：抽取 shared 包

第3阶段（7/15 单次 commit）：17 对重复组件 → packages/shared/
  └─ 成本：1 次大重构，commit 82495d2

教训

错误做法 正确做法
一开始就设计共享包（过度抽象） 先复制，到第 3 次重复时再抽
复制后重写（“让学生版更好看”） 复制后只改 import 路径，不改逻辑
两端各自优化（步调不一致） 共享包 + 版本号统一管理

决策时机

遇到代码重复时：
  第 1 次重复：别抽（还不知道需求会不会变）
  第 2 次重复：标记（记录重复位置）
  第 3 次重复：抽（重复 > 3 次，抽取成本已低于维护成本）

模式六：HTML 原型 → Flutter 映射

一句话： 先做纯 HTML 原型，再写 Flutter 代码。

工作流

你描述需求 → Hermes 生成 HTML/CSS 原型
    ↓
你在浏览器中审查 → 指出问题 → Hermes 修改
    ↓
原型冻结 → 进入编码 → Flutter 代码精确还原原型

为什么要先做原型

  1. 审查成本低： HTML 在浏览器打开即可，比编译 Flutter App 快 100 倍
  2. 迭代快： 改 CSS 比改 Flutter Widget 快 10 倍
  3. 共识工具： 你看到的是最终效果，不是抽象描述
  4. 可复用到 doc： HTML 原型本身就是设计文档的一部分

v2 中有 76 页 HTML 原型，覆盖了所有页面

在 7/3~7/9 的设计期内，Hermes 生成了全量 HTML 原型。编码时（7/11），Agent 直接参考这些原型写 Flutter 代码，不需要再问你"这个按钮长什么样"。

模式七：子代理（Subagent）并行

一句话： 需要同时做 N 件独立的事时，别串行，派子代理。

适用场景

场景 串行代价 子代理方案
5 维度审计 5 倍时间 5 个子代理并行，≈ 1 倍时间
参数化批量修复 逐个改，容易回退 子代理各改一部分，一次性合入
多文件搜索+分析 逐个文件读，上下文撑爆 子代理各读一部分，汇总结果

子代理"代理" vs 手动

手动串行：
  read_file(A) → read_file(B) → read_file(C) → 思考 → 写代码
  → 上下文被中间结果撑满 → compact → 丢细节

子代理并行：
  delegate_task(审计A)、delegate_task(审计B)...
  → 每个子代理只读自己需要的文件
  → 返回精简报告
  → 主会话汇总 → 决策

限制

  • 子代理不能问你问题（无交互能力）
  • 子代理不能改记忆/Skill
  • 结果靠自我报告，关键操作需要主会话验证

模式八：两阶段文档写作

一句话： 编年史的文档结构本身就是经过验证的模式。

结构（本项目验证过）

01-项目总览.md         ← 给外人看的（5 分钟速览）
02-v1-网页端时代.md    ← 按时间线（发生了什么）
03-v2-Flutter双端时代.md ← 按时间线（发生了什么）
04-Agent对话全统计.md  ← 数据维度（花了多少钱、多少 token、你打了多少字）
05-模式总结.md          ← 可复用经验（新项目该怎么干）

关键原则

原则 说明
总览要薄 01 不超过 3 页，给决策者看
编年要厚 02+03 可以 20+ 页，按 Phase 展开
数据要准 04 的双口径 token 是重要的纠错——单一口径会误导
模式要干 05 只写能直接在下一个项目用的，不写鸡汤

附录：给我的提醒清单（新项目启动前看）

第一天

□ 确保 state.db 的 git_repo_root 正确设置（否则会话无法关联到项目）
□ 设置 Hermes 工作目录
□ 项目编年史目录建立（空壳也行，后面补）

设计期必做

□ 先产出一份 HTML 原型（哪怕只有 3 页）
□ 确定架构文档 -> API 文档 -> 数据库文档 -> UI 原型的先后顺序
□ 每个 Phase 要有验收标准
□ 设计文档写完后，跑一轮审计再编码

编码期必做

□ 每个 Phase 完成后：审计 → 修复 → 冻结
□ 复用先用复制后改（第 3 次重复再抽共享）
□ 审计用子代理并行（Type A~E 同时跑）
□ 修复用 fix-batch-workflow（方案 → 确认 → 执行 → 验证）

费用管控

□ 长会话（>200 条）注意 compact
□ 系统提示词中的 Skill/Memory 不要冗余
□ 子代理用完即止，不要留 idle 会话

收尾期必做

□ 更新编年史 01~05
□ state.db 快照存档
□ 费用截图（DeepSeek 后台）
□ 清除 .hermes/tmp/