diff --git a/docs/milestone3-inference-retro.md b/docs/milestone3-inference-retro.md new file mode 100644 index 0000000..01bd115 --- /dev/null +++ b/docs/milestone3-inference-retro.md @@ -0,0 +1,69 @@ +# 里程碑 3.1 回顾报告(2026-08-09) + +> 首次冲刺回顾(无 prior 对比基线)。快照:`.superpowers/sdd/retro-2026-08-09.json`,下次回顾将可输出趋势对比。 + +## 1. 速览 + +- **范围**:里程碑 3.1「InferenceEngine」(base `2fbff07` .. `8ec63d1`) +- **Commits:8**(solo + AI 协作,全部 master 直推,无 PR,符合项目惯例) +- **净增 LOC**:+2572(插入 2592 / 删除 20) +- **测试占比**:56.2%(tests 609 行 / src+tests 1083 行) +- **验证**:117 passed / 覆盖率 100.00%(785 stmts / 186 br),`fail_under=99` 红线守住 +- **活跃**:1 天 / 2 个会话 + +## 2. 交付总览 + +``` +8ec63d1 docs: 里程碑3.1 InferenceEngine 设计规格与实施计划 +1eb07db docs: 里程碑3.1 InferenceEngine 交付报告与进度账本 +14062d1 fix: 客户端响应结构损坏归入 LLMResponseError;3xx 不再误判成功 +8bc5e5e feat: InferenceEngine chat/chat_structured 全流程 + 文档补丁(补丁1/2/3) +add7b15 feat: HttpLLMClient(httpx + 重试退避/超时/鉴权) +59c1ea7 feat: PromptRegistry 注册/版本/渲染(jinja2) +71d38b9 feat: Token 估算(approximate 内置 / tiktoken 可选回落) +c2fad77 feat: 推理引擎数据模型与异常层(types/exceptions)及 httpx/jinja2 依赖 +``` + +- **贡献者**:1(lhl)+ AI 协作(deepseek-v4-flash-free),全程记录于 `_AI_USAGE_LOG.md` +- **焦点得分**:100%(全部实现集中在 `src/genesis/inference/`,零上下文切换) +- **Ship of the Milestone**:`8bc5e5e`(InferenceEngine 全流程 495+ 行,5 个任务合拢点) + +## 3. 时间与模式 + +- 两段式会话:早段 05:53–11:00 前 2 任务(需求层 + 基础)→ 午段 08:03–08:36 后 3 任务 + 1 修复 + 文档定稿 +- 无深夜 commit(≥22:00 为 0),节奏健康 + +``` +08:36 docs 定稿与交付报告 +08:36 fix 响应逃逸 + 3xx 判定 +08:26 feat Task5 InferenceEngine +08:08 feat Task4 HttpLLMClient +08:03 feat Task3 PromptRegistry +06:58 feat Task2 Token 估算 +05:53 feat Task1 types/exceptions + 依赖 +``` + +## 4. 代码质量信号 + +- **fix 比率**:12.5%(1/8)≪ 50% 红线——无「发得快修得快」,前置 plan-design-review 有效 +- **测试占比**:56.2%,强 TDD 纪律;零真实网络(全量注入 FakeLLMClient / httpx.MockTransport) +- **热点**:`_AI_USAGE_LOG.md` ×5(每次 commit 追加日志,符合 AGENTS.md):`client.py` ×2(实现+评审修复) + +## 5. 3 项成就 + +1. **5 模块 spec→plan→TDD 证据链完整**:每任务 RED→GREEN→REFACTOR 记录在 `.superpowers/sdd/task-ie-N-report.md` +2. **最终评审抓到 2 个真缺陷并修复**:`LLMResponseError` 从 spec 类型到真实触发点闭环;3xx 显式 2xx 判定;补测试 RED→GREEN 记录在册 +3. **文档零漂移**:spec(含 2 项补丁)→ plan → 实现 → 3 处文档修订(agent-runtime §2.2 / api-design §8 / config-design §4)全部对应 + +## 6. 待改进(backlog) + +| 优先级 | 项目 | 位置 | 建议 | +|--------|------|------|------| +| P1 | `chat_structured` 未做 token 超限检测 | `src/genesis/inference/engine.py`(与 `chat` 流程不一致) | 复用 `_apply_truncation` 流程 | +| P2 | 测试套件未用导入 | `tests/test_inference_engine.py`(pytest/json/ChatMessage) | 代码卫生,回;历史 | +| P2 | HttpLLMClient 无上下文管理器 | `src/genesis/inference/client.py` | 调用方负责关闭,README 注明 | + +## 7. 下个里程碑的习惯 + +1. 任务完成后立即追加 `_AI_USAGE_LOG.md` 行(本次有后补) +2. 评审发现 Minor 项立即登 `progress.md` backlog,下个 milestone 开头清理(当前 backlog 9 项) \ No newline at end of file