ai-spec-dev 0.31.0 → 0.35.0

package/purpose.md

@@ -1,8 +1,11 @@
 # ai-spec 设计思考文档
 
+<details open>
+<summary>中文</summary>
+
 > 痛点 · 架构创新 · 边界处理 · DSL 的意义 · 当前局限 · 未来方向
 >
-> 当前版本：v0.31.0 · 最后更新：2026-03-29
+> 当前版本：v0.35.0 · 最后更新：2026-04-01
 
 ***
 
@@ -12,6 +15,10 @@
 2. [核心架构设计](#2-核心架构设计)
    - 2.11 [工业级可靠性基础设施（v0.27.0+）](#211-工业级可靠性基础设施v0270)
    - 2.12 [3-pass 代码审查（v0.28.0+）](#212-3-pass-代码审查v0280)
+   - 2.13 [Harness Engineer：从 Prompt Hash 到质量数据闭环（v0.31.0+）](#213-harness-engineer从-prompt-hash-到质量数据闭环v0310)
+   - 2.14 [两条 Pipeline 反馈环：让流水线可纠偏（v0.33.0+）](#214-两条-pipeline-反馈环让流水线可纠偏v0330)
+   - 2.15 [DSL 的多出口价值：类型、Dashboard 与可观测性（v0.34.0+）](#215-dsl-的多出口价值类型dashboard-与可观测性v0340)
+   - 2.16 [Pipeline 可靠性强化与 VCR 离线回放（v0.35.0+）](#216-pipeline-可靠性强化与-vcr-离线回放v0350)
 3. [DSL 层的意义](#3-dsl-层的意义)
 4. [完整功能矩阵](#4-完整功能矩阵)
 5. [边界情况与兜底机制](#5-边界情况与兜底机制)
@@ -19,7 +26,7 @@
 7. [当前局限](#7-当前局限)
 8. [未来优化方向](#8-未来优化方向)
 
-> **版本记录速览**：v0.17.0 宪法截断修复 · v0.18.0 `learn` + `minSpecScore` + 行为契约提取 · v0.19.0 错误解析重写 + Auto Gate 修复 · v0.20.0 `mock --serve` 一键联调 · v0.21.0 store 公开 API 提取修复 · v0.22.0 service/api 层分离 · v0.23.0 view/route 双层 + 文件名幻觉修复 · v0.24.0 四项质量修复（export default、impliesRegistration、依赖拓扑排序、lesson 计数）· v0.25.0 HTTP import 正则、分页提取、isToolCrash 三项修复 · v0.26.0 多仓库 review 目录、batch 容错、tasks JSON 健壮性 · **v0.27.0 可靠性三件套**（Provider retry/timeout/分类、文件快照 + `restore`、RunId 结构化日志）· **v0.28.0 3-pass review**（Pass 3 影响面评估 + 代码复杂度评估）· **v0.29.0 全量审查修复**（RunLogger 完整插桩、update 快照/日志/knowledge、Score Trend 显示影响/复杂度等级、死代码清理）· **v0.30.0 错误修复依赖图排序 + 前端 Import 多行感知解析** · **v0.31.0 Harness Engineer：Prompt Hash + Create 内联 Self-Eval**
+> **版本记录速览**：v0.17.0 宪法截断修复 · v0.18.0 `learn` + `minSpecScore` + 行为契约提取 · v0.19.0 错误解析重写 + Auto Gate 修复 · v0.20.0 `mock --serve` 一键联调 · v0.21.0 store 公开 API 提取修复 · v0.22.0 service/api 层分离 · v0.23.0 view/route 双层 + 文件名幻觉修复 · v0.24.0 四项质量修复（export default、impliesRegistration、依赖拓扑排序、lesson 计数）· v0.25.0 HTTP import 正则、分页提取、isToolCrash 三项修复 · v0.26.0 多仓库 review 目录、batch 容错、tasks JSON 健壮性 · **v0.27.0 可靠性三件套**（Provider retry/timeout/分类、文件快照 + `restore`、RunId 结构化日志）· **v0.28.0 3-pass review**（Pass 3 影响面评估 + 代码复杂度评估）· **v0.29.0 全量审查修复**（RunLogger 完整插桩、update 快照/日志/knowledge、Score Trend 显示影响/复杂度等级、死代码清理）· **v0.30.0 错误修复依赖图排序 + 前端 Import 多行感知解析** · **v0.31.0 Harness Engineer：Prompt Hash + Create 内联 Self-Eval** · **v0.32.0 logs / trend + DSL Coverage 细化评分** · **v0.33.0 两条 Pipeline 反馈环（DSL Gap Loop + Review→DSL Loop）** · **v0.34.0 Harness Dashboard + DSL → TypeScript 类型生成** · **v0.35.0 VCR 录制回放 + JSONL 崩溃恢复 + 熔断 + §9 知识闭环 + Approval Gate 预估**
 
 ***
 
@@ -50,8 +57,10 @@ ai-spec 对每个痛点都有对应的架构设计，不是功能堆砌，而是
 | 缺乏结构化中间层   | Spec + DSL 双层契约      | Markdown Spec 供人审查，JSON DSL 供机器消费                     |
 | 生成粒度太粗     | Task 分层 + 断点续传       | data→infra→service→api→test 层级，逐 task 生成 + `--resume` |
 | 生成后无质量验证   | 错误反馈闭环               | 自动运行 test/lint → AI 修复 → 验证，最多 2 轮                    |
+| 流水线纠偏成本高   | 局部反馈环                 | DSL 稀疏时先补 Spec 再提取；Review 发现结构性问题时先修契约再 `update --codegen` |
 | 经验不断流失     | 知识记忆机制               | 审查 issue 自动写入宪法 §9，下次运行即生效；`init --consolidate` 定期精简  |
 | 跨 task 一致性 | Generated File Cache | 已生成的 API/store 文件内容缓存，后续 task 可见真实导出名                 |
+| 难以判断系统是否在变好 | Harness 可观测层          | `promptHash` + `harnessScore` + `logs/trend/dashboard`，把生成质量变成可比较数据 |
 
 **核心定位**：ai-spec 不是代码补全工具，而是一个「AI 辅助工程流程编排器」。它的目标是让工程师用最少的时间获得一个符合项目规范、通过基本质检、可直接进入 Review 的代码分支。
 
@@ -59,58 +68,54 @@ ai-spec 对每个痛点都有对应的架构设计，不是功能堆砌，而是
 
 > 在进入各模块细节之前，先建立一个全局视图。
 
-```mermaid
-flowchart TD
-    subgraph INPUT["输入层"]
-        IDEA["💬 需求描述\n自然语言"]
-        CONST["📜 项目宪法\n§1-§8 规则 + §9 教训"]
-        CTX["🗂️ 项目上下文\n代码结构 / 依赖 / 路由"]
-    end
-
-    subgraph CONTRACT["双层契约"]
-        SPEC["📄 Spec\nMarkdown 人类可读"]
-        DSL["📊 DSL\nJSON 机器可读"]
-    end
-
-    subgraph GATE["质量门控"]
-        SCORE_GATE["🎯 Spec 质量评分\nminSpecScore 阈值"]
-        APPROVAL["🧑‍💻 Approval Gate\n人工确认后才开始生成"]
-    end
-
-    subgraph GENERATE["生成层"]
-        CODEGEN["⚙️ Task 分层代码生成\ndata→service→api→view→route\n层内拓扑排序 + batch 并行"]
-        CACHE[("🗄️ File Cache\n行为契约 / 函数签名")]
-    end
-
-    subgraph VERIFY["验证层"]
-        ERRLOOP["🔄 错误反馈闭环\n≤2 cycle · 依赖图排序修复"]
-        REVIEW["🔬 3-pass 代码审查\n架构 + 实现 + 影响面"]
-    end
-
-    subgraph LEARN["学习层（闭环）"]
-        KNOW["📚 §9 知识积累\n审查 issue 自动写入"]
-        EVAL["📈 Harness Self-Eval\nharnessScore + promptHash"]
-    end
-
-    IDEA --> SPEC
-    CONST -->|"全文注入所有 prompt"| SPEC
-    CTX --> SPEC
-
-    SPEC --> SCORE_GATE
-    SCORE_GATE -->|"通过"| APPROVAL
-    SCORE_GATE -->|"不足"| STOP1(["🚫 中止"])
-    APPROVAL -->|"Proceed"| DSL
-    APPROVAL -->|"Abort"| STOP2(["🚫 退出，无残留"])
-
-    DSL --> CODEGEN
-    CODEGEN <-->|"读写"| CACHE
-    CODEGEN --> ERRLOOP
-    ERRLOOP --> REVIEW
-    REVIEW --> KNOW
-    KNOW -->|"更新宪法 §9"| CONST
-    REVIEW --> EVAL
+![ai-spec 整体架构鸟瞰](docs-assets/purpose/architecture-overview.svg)
+
+<details>
+<summary>查看纯文本版</summary>
+
+```text
+输入层
+  💬 需求描述（自然语言）
+  📜 项目宪法（§1-§8 规则 + §9 教训）
+  🗂️ 项目上下文（代码结构 / 依赖 / 路由）
+          │
+          ├──────────────→ 📄 Spec（Markdown，人类可读）
+          │
+          ├─ 宪法全文注入所有 prompt ───────→ 📄 Spec
+          │
+          └──────────────→ 📄 Spec
+
+双层契约
+  📄 Spec
+    ↓
+  🎯 Spec 质量评分（minSpecScore 阈值）
+    ├─ 通过 → 🧑‍💻 Approval Gate（人工确认后才开始生成）
+    │          ├─ Proceed → 📊 DSL（JSON，机器可读）
+    │          └─ Abort   → 🚫 退出，无残留
+    └─ 不足 → 🚫 中止
+
+生成层
+  📊 DSL
+    ↓
+  ⚙️ Task 分层代码生成（data→service→api→view→route，层内拓扑排序 + batch 并行）
+    ↔ 🗄️ File Cache（行为契约 / 函数签名）
+
+验证层
+  Task 分层代码生成
+    ↓
+  🔄 错误反馈闭环（≤2 cycle · 依赖图排序修复）
+    ↓
+  🔬 3-pass 代码审查（架构 + 实现 + 影响面）
+
+学习层（闭环）
+  🔬 3-pass 代码审查
+    ├─→ 📚 §9 知识积累（审查 issue 自动写入）
+    │      └─→ 更新宪法 §9 → 📜 项目宪法
+    └─→ 📈 Harness Self-Eval（harnessScore + promptHash）
 ```
 
+</details>
+
 ***
 
 ## 2. 核心架构设计
@@ -119,41 +124,70 @@ flowchart TD
 
 > 以下流程图展示了运行一次 `ai-spec create` 时所有步骤的完整执行路径，包括每个决策门和反馈循环。后续 §2.1—§2.13 各节是对图中各模块的深度解析。
 
-```mermaid
-flowchart TD
-    START(["▶ ai-spec create &lt;idea&gt;"])
-
-    START --> S1["Step 1 · 加载项目上下文\nContextLoader 扫描代码结构 / 依赖 / 路由 / schema"]
-    S1 --> S2["Step 2 · Spec + Tasks 生成\n宪法全文注入 prompt 最高优先级"]
-    S2 --> S3["Step 3 · 交互式润色\nDiff 预览，可多轮修改"]
-    S3 --> S34["Step 3.4 · Spec 质量评估\n覆盖度 / 清晰度 / 宪法符合度打分"]
-
-    S34 --> G1{Score ≥ minSpecScore?}
-    G1 -->|"否"| ABORT1(["🚫 exit(1)\n--force 可强制继续"])
-    G1 -->|"是"| G2{"Approval Gate\n展示 Spec + DSL 摘要\n等待人工决策"}
-    G2 -->|"Abort"| ABORT2(["🚫 退出\nSpec 不写入磁盘"])
-    G2 -->|"Proceed"| DSL["DSL 提取 + 9 条规则校验\n失败最多重试 2 次"]
-
-    DSL --> TRACK["RunId 生成 + 文件快照初始化\nPrompt Hash 写入 RunLog"]
-    TRACK --> CG["Step 5–6 · Task 分层代码生成\ndata → infra → service → api → view → route → test\n层内拓扑排序 → batch 并行 → 缓存更新"]
-    CG --> TG["Step 7 · 测试骨架生成"]
-
-    TG --> EF["Step 8 · 错误反馈闭环"]
-    EF --> EF_RUN["运行 test / lint / tsc"]
-    EF_RUN --> EF_CHECK{全部通过?}
-    EF_CHECK -->|"通过"| RV
-    EF_CHECK -->|"有错误 · cycle ≤ 2"| EF_FIX["依赖图排序\nAI 逐文件修复\n携带 DSL 上下文"]
-    EF_FIX --> EF_RUN
-    EF_CHECK -->|"cycle 2 仍失败"| EF_WARN["⚠️ 黄色警告，继续"]
-    EF_WARN --> RV
-
-    RV["Step 9 · 3-pass 代码审查\nPass1 架构 · Pass2 实现 · Pass3 影响面/复杂度"]
-    RV --> KNOW["§9 知识积累\n审查 issue 自动追加宪法"]
-
-    KNOW --> SE["Step 10 · Harness Self-Eval\nDSL 覆盖 + Compile + Review → harnessScore\nPromptHash 关联，零 AI 调用"]
-    SE --> DONE(["✔ Done\nSpec / DSL / 代码 / RunLog 全部落盘"])
+![ai-spec create 完整流水线](docs-assets/purpose/create-pipeline.svg)
+
+<details>
+<summary>查看纯文本版</summary>
+
+```text
+▶ ai-spec create <idea>
+  ↓
+Step 1 · 加载项目上下文
+  ContextLoader 扫描代码结构 / 依赖 / 路由 / schema
+  ↓
+Step 2 · Spec + Tasks 生成
+  宪法全文注入 prompt 最高优先级
+  ↓
+Step 3 · 交互式润色
+  Diff 预览，可多轮修改
+  ↓
+Step 3.4 · Spec 质量评估
+  覆盖度 / 清晰度 / 宪法符合度打分
+  ↓
+判断：Score ≥ minSpecScore ?
+  ├─ 否 → 🚫 exit(1)（--force 可强制继续）
+  └─ 是 → Approval Gate
+           展示 Spec + DSL 摘要，等待人工决策
+           ├─ Abort   → 🚫 退出，Spec 不写入磁盘
+           └─ Proceed → DSL 提取 + 9 条规则校验（失败最多重试 2 次）
+                        ↓
+                      RunId 生成 + 文件快照初始化
+                      Prompt Hash 写入 RunLog
+                        ↓
+                      Step 5–6 · Task 分层代码生成
+                      data → infra → service → api → view → route → test
+                      层内拓扑排序 → batch 并行 → 缓存更新
+                        ↓
+                      Step 7 · 测试骨架生成
+                        ↓
+                      Step 8 · 错误反馈闭环
+                        ↓
+                      运行 test / lint / tsc
+                        ↓
+                      判断：全部通过？
+                        ├─ 通过 → Step 9 · 3-pass 代码审查
+                        │          Pass1 架构 · Pass2 实现 · Pass3 影响面/复杂度
+                        ├─ 有错误，且 cycle ≤ 2
+                        │    → 依赖图排序
+                        │    → AI 逐文件修复（携带 DSL 上下文）
+                        │    → 回到 test / lint / tsc
+                        └─ cycle 2 仍失败
+                             → ⚠️ 黄色警告，继续
+                             → Step 9 · 3-pass 代码审查
+                                  ↓
+                                §9 知识积累
+                                审查 issue 自动追加宪法
+                                  ↓
+                                Step 10 · Harness Self-Eval
+                                DSL 覆盖 + Compile + Review → harnessScore
+                                PromptHash 关联，零 AI 调用
+                                  ↓
+                                ✔ Done
+                                Spec / DSL / 代码 / RunLog 全部落盘
 ```
 
+</details>
+
 ***
 
 ### 2.1 项目宪法：可进化的项目记忆
@@ -235,51 +269,60 @@ Approval Gate 设计在「Spec 润色完成 + DSL 提取完成」之后、「代
 data → infra → service → api → view → route → test
 ```
 
-| 层 | 后端含义 | 前端含义 |
-|----|---------|---------|
-| data | DB schema、migrations、TS 类型定义 | 同左 |
-| infra | 配置、环境变量、外部服务 | 同左 |
-| service | 业务逻辑、service class | HTTP API 调用文件（`src/api/`） |
-| api | Controller、路由、中间件 | 状态管理 store（`src/stores/`） |
-| view | — | 页面/视图组件（`src/views/`） |
-| route | — | 路由模块文件（`src/router/routes/`） |
-| test | 单测、集成测试 | 同左 |
+| 层       | 后端含义                         | 前端含义                         |
+| ------- | ---------------------------- | ---------------------------- |
+| data    | DB schema、migrations、TS 类型定义 | 同左                           |
+| infra   | 配置、环境变量、外部服务                 | 同左                           |
+| service | 业务逻辑、service class           | HTTP API 调用文件（`src/api/`）    |
+| api     | Controller、路由、中间件            | 状态管理 store（`src/stores/`）    |
+| view    | —                            | 页面/视图组件（`src/views/`）        |
+| route   | —                            | 路由模块文件（`src/router/routes/`） |
+| test    | 单测、集成测试                      | 同左                           |
 
 **执行模型图解：**
 
-```mermaid
-flowchart TB
-    subgraph LAYERS["七层顺序（跨层串行）"]
-        direction LR
-        LA["data"] --> LB["infra"] --> LC["service"] --> LD["api"] --> LE["view"] --> LF["route"] --> LG["test"]
-    end
-
-    subgraph WITHIN["单层内部执行（以 api 层为例）"]
-        direction TB
-        TOPO["拓扑排序\n按 dependencies 字段分 batch"]
-
-        subgraph B1["Batch 1 · 无依赖 → 并行"]
-            T1["userController.ts"]
-            T2["authController.ts"]
-        end
-
-        subgraph B2["Batch 2 · 依赖 Batch 1 → 并行"]
-            T3["adminController.ts\n需要 import userController"]
-        end
-
-        TOPO --> B1
-        B1 -->|"batch 完成\n更新 FileCache"| B2
-    end
-
-    CACHE[("generatedFileCache\n函数签名 / 文件路径\nbehavioral contracts")]
-
-    B1 <-->|"读写"| CACHE
-    B2 <-->|"读写"| CACHE
-
-    LAYERS -->|"进入当层"| WITHIN
-    WITHIN -->|"层完成\n更新共享 config 文件\n(routes/index.ts 等)"| NEXT(["下一层"])
+![Task 分层与层内执行模型](docs-assets/purpose/task-layering.svg)
+
+<details>
+<summary>查看纯文本版</summary>
+
+```text
+七层顺序（跨层串行）
+  data → infra → service → api → view → route → test
+
+单层内部执行（以 api 层为例）
+  1. 先做拓扑排序
+     - 按 tasks.json 里的 dependencies 字段分 batch
+
+  2. Batch 1（无依赖，可并行）
+     - userController.ts
+     - authController.ts
+     - 执行完成后，更新 generatedFileCache
+
+  3. Batch 2（依赖 Batch 1，可并行）
+     - adminController.ts
+       需要 import userController
+     - 执行完成后，再更新 generatedFileCache
+
+generatedFileCache 的作用
+  - 记录函数签名
+  - 记录文件路径
+  - 记录 behavioral contracts
+  - Batch 1 / Batch 2 都会读写它
+
+整层执行关系
+  进入当前层
+    ↓
+  层内拓扑排序 + batch 并行
+    ↓
+  层完成后统一更新共享 config 文件
+  例如：routes/index.ts
+    ↓
+  进入下一层
 ```
 
+</details>
+
 > **为什么 route 必须在 view 之后？** view 完成后，`TaskManagement.vue` 的真实路径进入 FileCache；route task 生成时 prompt 里已经有 `// exists: src/views/task-management/TaskManagement.vue`，AI 不会再猜测 `index.vue`（v0.23.0 文件名幻觉修复）。
 
 **前端四层链路设计（v0.22.0+）**：`service`（api 调用函数）→ `api`（store，导入 service 函数）→ `view`（页面，使用 store action）→ `route`（路由模块，导入 view 组件）。`route` 必须在 `view` 之后生成，因为路由文件需要知道 view 组件的确切文件名（如 `TaskManagement.vue` 而非猜测的 `index.vue`）——这是 v0.23.0 修复文件名幻觉的核心机制。
@@ -347,9 +390,8 @@ flowchart TB
 
 **v0.25.0 提取质量修复：**
 
-- **`httpClientImport` 正则扩展**：旧版只识别 `axios`、`ky` 和 `@/` 路径，漏掉了所有使用 `~/`、`#/`、`@@/` 别名以及 `undici`、`got`、`alova` 等库的项目，提取结果为 `undefined` 时 AI 会自由发挥 import 路径。新版覆盖所有常见别名 + 路径含 http/request/fetch/client/api 关键词的相对 import + 完整 HTTP 库列表，并排除 `import type` 语句（仅类型导入，运行时无效）。
-
-- **`paginationExample` 逐行提取重写**：旧版正则用 `[^}]*` 匹配接口体，遇到嵌套对象字段（`filter: { status?: string }`）立即截断；函数匹配用 `\n\}` 要求闭合括号紧接换行，缩进的 `  }` 永远不匹配；且只支持 `export function`，遗漏了现代代码中更常见的 `export const = () =>` 写法。新版全部改为逐行扫描 + 大括号深度计数器，支持嵌套对象、任意缩进的闭合括号、arrow function，提取可靠性从「经常为空」提升到「能找到就找到」。
+- **`httpClientImport`** **正则扩展**：旧版只识别 `axios`、`ky` 和 `@/` 路径，漏掉了所有使用 `~/`、`#/`、`@@/` 别名以及 `undici`、`got`、`alova` 等库的项目，提取结果为 `undefined` 时 AI 会自由发挥 import 路径。新版覆盖所有常见别名 + 路径含 http/request/fetch/client/api 关键词的相对 import + 完整 HTTP 库列表，并排除 `import type` 语句（仅类型导入，运行时无效）。
+- **`paginationExample`** **逐行提取重写**：旧版正则用 `[^}]*` 匹配接口体，遇到嵌套对象字段（`filter: { status?: string }`）立即截断；函数匹配用 `\n\}` 要求闭合括号紧接换行，缩进的   `  }` 永远不匹配；且只支持 `export function`，遗漏了现代代码中更常见的 `export const = () =>` 写法。新版全部改为逐行扫描 + 大括号深度计数器，支持嵌套对象、任意缩进的闭合括号、arrow function，提取可靠性从「经常为空」提升到「能找到就找到」。
 
 **v0.30.0 — 多行感知 Import 解析：**
 
@@ -382,10 +424,10 @@ import {
 
 缓存策略按文件类型分层（v0.23.0+）：
 
-| 文件类型 | 缓存内容 | 原因 |
-|---------|---------|------|
-| `src/api*/`、`src/service*/`、`src/store*/`、`src/composable*/` | 完整文件内容（或提取的行为契约） | 下游 task 需要准确的函数名/类型签名 |
-| `src/views*/`、`src/pages*/` | 仅路径 sentinel：`// exists: src/views/task-management/TaskManagement.vue` | 路由 task 只需要组件的确切文件名 |
+| 文件类型                                                         | 缓存内容                                                                   | 原因                    |
+| ------------------------------------------------------------ | ---------------------------------------------------------------------- | --------------------- |
+| `src/api*/`、`src/service*/`、`src/store*/`、`src/composable*/` | 完整文件内容（或提取的行为契约）                                                       | 下游 task 需要准确的函数名/类型签名 |
+| `src/views*/`、`src/pages*/`                                  | 仅路径 sentinel：`// exists: src/views/task-management/TaskManagement.vue` | 路由 task 只需要组件的确切文件名   |
 
 **文件名幻觉的根因与修复（v0.23.0）**：路由文件里的 `import('@/views/xxx/index.vue')` vs 实际的 `TaskManagement.vue` 是高频幻觉。根因是「route task 在 view task 之前生成，AI 猜不出文件名，fallback 到 `index.vue`」。`view` 层在 `route` 层之前完成，view 文件的路径 sentinel 进入缓存，route task 的 prompt 中已经有 `// exists: src/views/task-management/TaskManagement.vue`，配合 Rule 17 强制使用该确切路径，幻觉消除。
 
@@ -469,7 +511,7 @@ ai-spec learn "登录态校验中间件是 authMiddleware，不是 verifyToken"
 
 认证错误不重试（key 已无效，重试无意义）；网络抖动和限流错误重试。所有错误附带结构化的 `ProviderError`（含 `kind` 字段），上层可按 kind 差异化处理。
 
-**② 写前文件快照 + `ai-spec restore <runId>`（`run-snapshot.ts`）**
+**② 写前文件快照 +** **`ai-spec restore <runId>`（`run-snapshot.ts`）**
 
 每次生成运行生成唯一 `RunId`（格式：`YYYYMMDD-HHMMSS-xxxx`）。在写入任何文件之前，先将原始内容备份到 `.ai-spec-backup/<runId>/`（如果文件不存在则跳过）。
 
@@ -521,10 +563,10 @@ Run 结束后自动打印摘要（RunId、总耗时、写入文件数、日志
 
 `ai-spec review` 从「2-pass」升级为「3-pass」，新增 Pass 3 影响面与复杂度评估：
 
-| Pass | 关注维度 | 核心问题 |
-|------|---------|---------|
-| **Pass 1 架构审查** | Spec 符合度、层级分离、认证中间件使用 | 这次改动是否破坏了架构边界？ |
-| **Pass 2 实现审查** | 参数校验、错误处理、边界值、历史问题复现检测 | 实现细节是否健壮、有没有老问题重演？ |
+| Pass                 | 关注维度                                           | 核心问题               |
+| -------------------- | ---------------------------------------------- | ------------------ |
+| **Pass 1 架构审查**      | Spec 符合度、层级分离、认证中间件使用                          | 这次改动是否破坏了架构边界？     |
+| **Pass 2 实现审查**      | 参数校验、错误处理、边界值、历史问题复现检测                         | 实现细节是否健壮、有没有老问题重演？ |
 | **Pass 3 影响面 + 复杂度** | 直接文件 / 间接传播范围 / Breaking Change / 认知复杂度 / 耦合分析 | 这次改动的波及范围和维护风险有多大？ |
 
 **Pass 3 输出结构**：
@@ -549,17 +591,29 @@ Pass 3 不重复 Pass 1 / Pass 2 的发现，而是站在更高的系统视角
 
 ***
 
-### 2.13 Harness Engineer：Prompt Hash + Self-Eval（v0.31.0+）
+### 2.13 Harness Engineer：从 Prompt Hash 到质量数据闭环（v0.31.0+）
+
+#### 背景：ai-spec 不能只是“会生成代码”
+
+v0.30.0 之前，ai-spec 已经具备了从 Spec 到代码的自动化能力，但它本质上还是一个**缺少量化反馈回路的生成 Harness**。你可以主观感受到某次生成“看起来不错”，却很难系统回答：
+
+- 改了 codegen prompt 之后，整体质量到底是提升还是下降了？
+- 哪个 provider / model 在当前项目上最稳定？
+- 某次宪法、DSL、review 规则收紧之后，compile 通过率有没有变好？
+- 最近 10 次生成里，分数下滑是 prompt 变了，还是模型随机波动？
+
+这正是 **Harness Engineer** 视角要解决的问题：工程师不只是把 AI 工作流串起来，更要把它变成一个**可比较、可回看、可量化优化**的系统。
 
-#### 背景：缺失的自我评估能力
+#### 设计转向：Harness Engineer 不再只是一个想法
 
-v0.30.0 之前，ai-spec 是一个能自动生成代码的 Harness，但它是一个**没有自我量化能力的 Harness**。你可以感知到某次生成质量好坏，但无法回答：
+现在这个设计已经不只停留在概念层。它已经开始进入 ai-spec 的真实运行路径：
 
-- 修改了 codegen prompt 之后，整体质量是提升还是下降了？
-- 哪个 provider / model 在这个项目上生成质量最稳定？
-- 加严宪法 §9 之后，compile 通过率有没有提高？
+- `create` 运行开始时记录 prompt 版本
+- `create` 结束前做确定性 self-eval
+- 每次运行写入结构化 RunLog
+- CLI 已提供 `logs` / `trend` 命令做历史回看和跨运行对比
 
-这正是 **Harness Engineer** 理念的核心缺口：工程师不只是构建 AI 生成系统，还必须能**量化证明这个系统在变好**。
+也就是说，**Harness Engineer 在 ai-spec 里不再只是“给一次生成打分”**，而是在逐步形成一个围绕 prompt、生成结果、review、编译结果和历史趋势的观测与优化层。
 
 #### Prompt Hash（`core/prompt-hasher.ts`）
 
@@ -574,17 +628,19 @@ v0.30.0 之前，ai-spec 是一个能自动生成代码的 Harness，但它是
 }
 ```
 
-任何 prompt 文件的改动都会产生不同的 hash。跨多个 RunLog 对比 `harnessScore` 时，先按 `promptHash` 分组，就能把「prompt 版本差异」从「模型随机性」中解耦，知道分数变化是因为 prompt 改了还是 LLM 本身的波动。
+任何 prompt 文件的改动都会产生不同的 hash。跨多个 RunLog 对比 `harnessScore` 时，先按 `promptHash` 分组，就能把「prompt 版本差异」从「模型随机性」中解耦，知道分数变化是因为 prompt 改了，还是 LLM 本身的波动。
+
+这一步的意义不是“记录一个 hash”本身，而是给后续所有分析建立了**版本坐标系**：没有这个坐标，趋势分析就很容易失真。
 
 #### Create 内联 Self-Eval（`core/self-evaluator.ts`）
 
 `ai-spec create` 在 Step 9（code review）之后新增 **Step 10: Harness Self-Eval**，零 AI 调用，纯确定性评分：
 
-| 维度 | 评分逻辑 | 权重 |
-|------|---------|------|
-| **DSL Coverage** (0-10) | 检查生成文件是否覆盖了 DSL 声明的 endpoint 层和 model 层 | 40% |
-| **Compile Score** (0-10) | error feedback 全部通过 → 10；未通过 / 跳过 → 5 | 30% |
-| **Review Score** (0-10) | 从 3-pass review 文本提取 `Score: X/10` | 30% |
+| 维度                       | 评分逻辑                                                                       | 权重  |
+| ------------------------ | -------------------------------------------------------------------------- | --- |
+| **DSL Coverage** (0-10)  | 检查生成文件是否覆盖了 DSL 声明的 endpoint 层和 model 层，并进一步细化 model 命名覆盖率与 endpoint 文件充足性 | 40% |
+| **Compile Score** (0-10) | error feedback 全部通过 → 10；未通过 / 跳过 → 5                                      | 30% |
+| **Review Score** (0-10)  | 从 3-pass review 文本提取 `Score: X/10`                                         | 30% |
 
 当 review 被跳过（`--skip-review`）时，权重自动调整为 DSL 55% + Compile 45%。
 
@@ -594,11 +650,184 @@ v0.30.0 之前，ai-spec 是一个能自动生成代码的 Harness，但它是
 ─── Harness Self-Eval ───────────────────────────
   Score  : [████████░░] 7.8/10
   DSL    : 8/10  Compile: pass  Review: 7.2/10
+  Detail : Models: 3/4 (75%)  Endpoints: 5  Files: 9
   Prompt : a3f2c1d8
 ─────────────────────────────────────────────────
 ```
 
-`harnessScore` 和 `promptHash` 同时写入 RunLog，为日后实现跨运行趋势分析奠定数据基础。
+`harnessScore` 和 `promptHash` 会同时写入 RunLog。这样一次 `create` 不再只是“生成完就结束”，而是变成一条可追踪、可横向比较的数据记录。
+
+#### RunLog、`logs` 与 `trend`：从单次打分走向历史分析
+
+如果只有 Step 10 的即时分数，Harness Engineer 仍然只是局部能力；真正让它变成工具层设计的，是后面的历史观测链路：
+
+- `RunLog` 持久化保存 `promptHash`、`harnessScore`、阶段耗时、错误数、产出文件数
+- `ai-spec logs` 负责回看某次运行发生了什么
+- `ai-spec trend` 负责跨运行聚合，按 `promptHash` 分组看 avg / best / worst / current
+
+这意味着工具已经开始支持一类过去无法回答的问题：
+
+- 当前 prompt 版本是不是比上一个版本更稳定？
+- 某个模型虽然偶尔分高，但平均分和最差分是不是更差？
+- 一次回归是发生在 prompt 版本切换之后，还是同一 prompt 下的正常波动？
+
+这就是我对 **Harness Engineer** 的核心理解：它不是单个 feature，而是一套让 AI 工具具备**实验能力、观测能力和持续优化能力**的工程设计。
+
+#### 当前边界：已经落地，但还没有完全展开
+
+目前这套设计已经真实进入了工具主流程，但还不是最终形态。
+
+已经落地的部分：
+
+- `create` 级别的 prompt 版本追踪
+- 确定性 self-eval 打分
+- RunLog 持久化
+- `logs` / `trend` 的历史分析入口
+
+还可以继续扩展的方向：
+
+- 把更多质量信号纳入评分，而不只限于 DSL / compile / review
+- 让不同 repo 类型的评估维度更贴近语言与框架特性
+- 把 prompt 演进、模型切换、错误回归之间的关系展示得更清楚
+
+因此，Harness Engineer 在 ai-spec 里的角色，已经从一个“补充性想法”变成了一个正在形成的**上层设计原则**：不仅要生成代码，还要让生成系统本身可以被测量、被比较、被持续改进。
+
+***
+
+### 2.14 两条 Pipeline 反馈环：让流水线可纠偏（v0.33.0+）
+
+v0.32.0 之前，ai-spec 虽然已经具备了 DSL、error feedback、review、self-eval 等模块，但整体上仍偏向**单向流水线**：上一步的输出一旦进入下一步，后面最多只能“带着问题继续往前走”。
+
+这会产生两个典型成本：
+
+- DSL 虽然合法，但明显太稀疏，后续 codegen 质量已经注定受限
+- review 虽然指出了结构性问题，但问题根源在 Spec / DSL，不在生成代码本身
+
+v0.33.0 为此引入了两条局部反馈环，让流水线第一次具备“先纠偏契约，再继续生成”的能力。
+
+#### Loop 1：DSL Gap Feedback
+
+在 DSL 提取成功、进入 worktree 之前，系统会做一次**纯启发式的 DSL 丰富度检查**。它不判断 DSL 是否“合法”，而是判断 DSL 是否“足够有信息量”。
+
+目前会检测几类典型缺口：
+
+- 没有 models，也没有 endpoints
+- endpoint 描述过于泛化
+- 多个 endpoint 全部缺少 `errors`
+- model 字段过少，明显不足以支撑代码生成
+
+一旦发现缺口，交互模式下会提供两个动作：
+
+- `Refine spec`：AI 不扩大功能范围，只补全当前 Spec 中缺失的结构细节，然后自动重新提取 DSL
+- `Skip`：接受当前 DSL，继续后续流水线
+
+这一步的设计价值是：**尽量在 codegen 之前修契约，而不是在 codegen 之后修实现**。前者便宜，后者昂贵。
+
+#### Loop 2：Review→DSL Loop
+
+review 完成后，系统不再把所有问题都一股脑记入 §9。对于那些明显属于“契约层缺失”的问题，会优先整理成对 Spec / DSL 的修订建议。
+
+例如：
+
+- 缺失错误码定义
+- 接口 auth 约束没写清
+- endpoint 或 model 信息过于稀疏
+- 当前实现偏差，本质来自上游契约不完整
+
+此时推荐动作不是直接手改代码，而是：
+
+```bash
+ai-spec update "补充缺失的结构约束" --codegen
+```
+
+也就是说，review 第一次成为了**上游契约的纠偏入口**，而不是只作为末端的“问题清单生成器”。
+
+#### 设计意义
+
+这两条反馈环把 ai-spec 从“可测量的流水线”进一步推进成“可纠偏的流水线”：
+
+- 错误反馈闭环修的是**实现错误**
+- DSL Gap Feedback 修的是**结构稀疏**
+- Review→DSL Loop 修的是**契约缺口**
+
+三者叠加后，ai-spec 不再只是会往前跑的 pipeline，而是开始具备工程系统应有的弹性。
+
+***
+
+### 2.15 DSL 的多出口价值：类型、Dashboard 与可观测性（v0.34.0+）
+
+一开始 DSL 的核心价值是“给 codegen 更稳定的输入”。但到 v0.34.0，DSL 已经不再只是中间态，而是开始成为**多个下游产物的统一源头**。
+
+#### `ai-spec types`
+
+`ai-spec types` 让 DSL 直接产出 TypeScript 类型文件，包括：
+
+- `models` 对应的 interface
+- endpoint 的 request / query / params 类型
+- `API_ENDPOINTS` 常量映射
+- 前端组件 props 类型
+
+这意味着 DSL 第一次不只是“喂给 AI 看”，而是开始变成**工程师可直接 import 使用的契约资产**。
+
+#### Harness Dashboard
+
+`ai-spec dashboard` 则把 RunLog 中沉淀下来的运行数据可视化，形成真正面向人的观测面板：
+
+- 总运行数 / 平均分 / 编译通过率
+- 最近 30 次评分走势
+- Prompt 版本对比（avg / best / worst）
+- 阶段耗时
+- Top 错误频次
+
+这使得 Harness Engineer 不再停留在终端里的 `harnessScore` 一行输出，而是升级成**可回看、可比较、可讨论的可视化报告**。
+
+#### 从“中间文件”到“统一契约源”
+
+到这个阶段，DSL 的作用已经扩展为：
+
+- codegen 的约束输入
+- mock / OpenAPI / workspace 契约桥接的上游来源
+- TypeScript 类型生成的输入
+- Harness 可观测体系中的关键结构化基础
+
+这说明 ai-spec 的设计重点已经不仅是”生成代码”，而是围绕 DSL、RunLog、promptHash、harnessScore 形成一套越来越完整的工程数据面。
+
+***
+
+### 2.16 Pipeline 可靠性强化与 VCR 离线回放（v0.35.0+）
+
+v0.35.0 是一次专注于**基础设施可靠性**的版本，借鉴 Claude Code 等工业级工具的工程实践，补齐了四个维度的短板。
+
+#### VCR 录制 & 零成本回放
+
+受 Claude Code VCR token 计数测试模式启发，引入 AI 响应快照机制：
+
+- `--vcr-record` — 录制当次 pipeline 所有 AI 调用（spec + codegen），保存到 `.ai-spec-vcr/{runId}.json`
+- `--vcr-replay <runId>` — 从快照逐序返回录制响应，**零 API 调用、零 token 消耗**，完全确定性
+- `ai-spec vcr list` / `ai-spec vcr show <runId>` — 查看和检视录制内容
+
+核心用途：迭代 Harness 评分权重、调试 Pipeline 阶段逻辑时，不需要每次都烧真实 token，直接在录制数据上反复测试。
+
+#### JSONL Append-Only Shadow（崩溃恢复）
+
+原有 `RunLogger.flush()` 是全量 JSON 重写，进程崩溃时当次记录全丢。新增逐行追加的 `.jsonl` 影子文件，每次 `push()`、`stageFail()`、`finish()` 都同步落盘。`loadRunLogs()` 能从孤儿 `.jsonl` 自动重建 `RunLog`，保证崩溃后数据可恢复。
+
+#### ErrorFeedback 无进展熔断
+
+修复循环新增”进展检测”：若两轮修复前后错误数未减少（`>= prevErrorCount`），立即熔断退出，不再浪费额外 AI 调用。参考 Claude Code `MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES` 防死循环设计。
+
+#### §9 知识积累的三角闭环
+
+至此，§9 知识积累真正形成三角闭环：
+1. **Review → 写入 §9**：Pass 1 发现问题，`accumulateReviewKnowledge` 将 issue 写入宪法 §9
+2. **§9 → Spec 生成**：`specPrompt` 有明确指令逐条审阅 §9 教训，在 §8 中标注规避方式
+3. **§9 → Reviewer 检验**：`loadAccumulatedLessons` 将 §9 注入 Pass 1 arch review，让 reviewer 能交叉检验是否复现已知问题
+
+§9 积累改为 **fire-and-await** 模式（异步启动、`runLogger.finish()` 前 await），Loop 2 交互不再被阻塞。
+
+#### Approval Gate DSL 范围预估
+
+Approval Gate 新增基于正则的 DSL 规模预估（无 AI 调用），在用户点击 Proceed 前展示 `~N endpoint(s), ~M model(s) → ~K files`，让用户对代码生成的工作量有量化感知。
 
 ***
 
@@ -661,19 +890,21 @@ DSL 提取本身是高幻觉风险操作。ai-spec 做了几个针对性设计
 
 ## 4. 完整功能矩阵
 
-截至 v0.29.0，ai-spec 的完整能力覆盖：
-
-| 阶段 | 命令 | 核心能力 |
-|------|------|---------|
-| **初始化** | `ai-spec init` | 扫描项目 → 生成宪法 §1-§8（`--global` 生成全局宪法，`--consolidate` 整合 §9） |
-| **新功能** | `ai-spec create` | 宪法（全文注入）→ context → Spec+Tasks → **Spec 质量评估 + minSpecScore Gate** → Approval Gate → DSL → Worktree → 逐 task codegen（**七层顺序 + 层内拓扑排序 + 行为契约缓存**）→ **TDD（`--tdd`）** → 错误反馈闭环（全文扫描，≤2 轮）→ 测试骨架 → **3-pass review** |
-| **变更迭代** | `ai-spec update` | 最小化更新 Spec → 定向更新 DSL（delta 对比）→ 识别受影响文件 → 可选重新生成（**`--codegen` 附带写前快照 + RunId 日志 + knowledge 积累，v0.29.0**） |
-| **接口导出** | `ai-spec export` | DSL → OpenAPI 3.1.0 YAML/JSON，纯 TypeScript 实现，零外部依赖 |
-| **前后端联调** | `ai-spec mock` | DSL → Express Mock Server + Proxy 配置 + MSW Handlers；`--serve` 一键后台启动服务器 + 自动 patch 前端 Proxy（Vite/CRA）；`--restore` 一键还原 |
-| **知识注入** | `ai-spec learn` | 零摩擦向宪法 §9 注入工程教训，不调用 AI，实时去重 |
-| **代码审查** | `ai-spec review` | git diff + Spec → AI **3-pass** 审查（架构层 + 实现层 + 影响面/复杂度）→ issue 写入宪法 §9 |
-| **快照回滚** | `ai-spec restore <runId>` | 按 RunId 回滚本次生成写入的所有文件（v0.27.0+） |
-| **多 Repo 工作区** | workspace 模式 | 一句需求 → AI 拆分职责+UX 决策 → [后端流水线 → DSL 契约] → [前端流水线（注入后端契约）]；`--serve` 完成后自动启动联调环境 |
+截至 v0.34.0，ai-spec 的完整能力覆盖：
+
+| 阶段             | 命令                        | 核心能力                                                                                                                                                                                                             |
+| -------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **初始化**        | `ai-spec init`            | 扫描项目 → 生成宪法 §1-§8（`--global` 生成全局宪法，`--consolidate` 整合 §9）                                                                                                                                                       |
+| **新功能**        | `ai-spec create`          | 宪法（全文注入）→ context → Spec+Tasks → **Spec 质量评估 + minSpecScore Gate** → Approval Gate → DSL → **DSL Gap Feedback** → Worktree → 逐 task codegen（**七层顺序 + 层内拓扑排序 + 行为契约缓存**）→ **TDD（`--tdd`）** → 错误反馈闭环（全文扫描，≤2 轮）→ 测试骨架 → **3-pass review** → **Review→DSL Loop** → **Harness Self-Eval** |
+| **变更迭代**       | `ai-spec update`          | 最小化更新 Spec → 定向更新 DSL（delta 对比）→ 识别受影响文件 → 可选重新生成（**`--codegen`** **附带写前快照 + RunId 日志 + knowledge 积累，v0.29.0**）                                                                                                  |
+| **接口导出**       | `ai-spec export`          | DSL → OpenAPI 3.1.0 YAML/JSON，纯 TypeScript 实现，零外部依赖                                                                                                                                                              |
+| **前后端联调**      | `ai-spec mock`            | DSL → Express Mock Server + Proxy 配置 + MSW Handlers；`--serve` 一键后台启动服务器 + 自动 patch 前端 Proxy（Vite/CRA）；`--restore` 一键还原                                                                                           |
+| **类型产物**       | `ai-spec types`           | DSL → TypeScript 类型文件（models、endpoint request types、`API_ENDPOINTS`、component props）                                                                                                                               |
+| **知识注入**       | `ai-spec learn`           | 零摩擦向宪法 §9 注入工程教训，不调用 AI，实时去重                                                                                                                                                                                     |
+| **代码审查**       | `ai-spec review`          | git diff + Spec → AI **3-pass** 审查（架构层 + 实现层 + 影响面/复杂度）→ issue 写入宪法 §9                                                                                                                                           |
+| **运行观测**       | `ai-spec logs` / `trend` / `dashboard` | 基于 RunLog 做单次回看、跨运行趋势分析、Prompt 版本对比、阶段耗时与错误频次可视化                                                                                                                                                |
+| **快照回滚**       | `ai-spec restore <runId>` | 按 RunId 回滚本次生成写入的所有文件（v0.27.0+）                                                                                                                                                                                  |
+| **多 Repo 工作区** | workspace 模式              | 一句需求 → AI 拆分职责+UX 决策 → \[后端流水线 → DSL 契约] → \[前端流水线（注入后端契约）]；`--serve` 完成后自动启动联调环境                                                                                                                                |
 
 **单 Repo 流水线总图（v0.29.0）：**
 
@@ -751,15 +982,15 @@ Spec + Tasks 在同一次 AI 调用中生成。Tasks 部分解析失败时：
 
 ### 5.5 错误反馈循环的边界处理
 
-| 场景                    | 处理方式                                                  |
-| --------------------- | ----------------------------------------------------- |
-| 项目无 test 命令也无 lint 命令 | 跳过整个 error feedback 步骤，打印提示                           |
-| 测试命令超时（>60s）          | `execSync` timeout 触发，视为失败，进入修复流程                     |
-| 修复后测试仍失败（cycle 2 结束）  | 黄色警告提示，继续后续步骤（不硬停）                                    |
-| 修复的文件不存在              | 跳过该文件，记录 `fixed: false`，继续其他文件                        |
-| AI 修复调用失败             | 记录失败，继续其他错误文件，不中断整个修复循环                               |
-| 错误输出过长 | 扫描全文，只保留含 `file:line` 模式的行（v0.19.0 重写），过滤 `node_modules` / npm timing / stack trace 噪音，上限 20 条可操作错误 |
-| 类型检查工具自身崩溃（如 vue-tsc 版本不兼容） | 检测到「unhandled ReferenceError/TypeError + stack frame 指向 node_modules 内部」时识别为工具崩溃，打印提示跳过，不将工具内部错误送进修复循环（v0.25.0 精确判断）|
+| 场景                          | 处理方式                                                                                                                  |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| 项目无 test 命令也无 lint 命令       | 跳过整个 error feedback 步骤，打印提示                                                                                           |
+| 测试命令超时（>60s）                | `execSync` timeout 触发，视为失败，进入修复流程                                                                                     |
+| 修复后测试仍失败（cycle 2 结束）        | 黄色警告提示，继续后续步骤（不硬停）                                                                                                    |
+| 修复的文件不存在                    | 跳过该文件，记录 `fixed: false`，继续其他文件                                                                                        |
+| AI 修复调用失败                   | 记录失败，继续其他错误文件，不中断整个修复循环                                                                                               |
+| 错误输出过长                      | 扫描全文，只保留含 `file:line` 模式的行（v0.19.0 重写），过滤 `node_modules` / npm timing / stack trace 噪音，上限 20 条可操作错误                   |
+| 类型检查工具自身崩溃（如 vue-tsc 版本不兼容） | 检测到「unhandled ReferenceError/TypeError + stack frame 指向 node\_modules 内部」时识别为工具崩溃，打印提示跳过，不将工具内部错误送进修复循环（v0.25.0 精确判断） |
 
 ### 5.6 Git Worktree 边界
 
@@ -834,13 +1065,14 @@ DSL 设计主要针对 REST API 场景（HTTP 端点 + 数据模型）。对于
 
 ### 7.4 宪法长度限制
 
-~~代码中存在 `constitution.slice(0, 2000)` 的硬截断。随着宪法增长，末尾内容（通常是 §9 最新教训）会被截断。~~ **→ v0.17.0 已修复**：移除了全部 6 处 `.slice()` 硬截断（`spec-generator`、`task-generator`、`spec-assessor`、`code-generator`、`prompts/update` 共 6 处），宪法现在全文注入所有 prompt。
+~~代码中存在~~ ~~`constitution.slice(0, 2000)`~~ ~~的硬截断。随着宪法增长，末尾内容（通常是 §9 最新教训）会被截断。~~ **→ v0.17.0 已修复**：移除了全部 6 处 `.slice()` 硬截断（`spec-generator`、`task-generator`、`spec-assessor`、`code-generator`、`prompts/update` 共 6 处），宪法现在全文注入所有 prompt。
 
 **当前状态**：无截断。宪法越长，prompt 消耗的 token 越多，但不会丢失内容。`init --consolidate` 仍建议定期执行以保持宪法的高信噪比（而不再是为了绕过截断问题）。
 
 ### 7.5 错误修复能力有上限
 
 错误反馈循环最多运行 2 次，每次修复以文件为粒度。仍存在的限制：
+
 - 修复上限固定为 2 cycle，无法动态调整
 - 同一文件内多个相互依赖的逻辑错误需要多轮才能全部消除
 - Python、Java 等语言的 import 语法暂不参与依赖排序（当前仅解析 TS/JS 相对 import）
@@ -866,3 +1098,197 @@ DSL 设计主要针对 REST API 场景（HTTP 端点 + 数据模型）。对于
 ***
 
 *ai-spec v0.26.0 · Design Rationale Document · 2026-03-26*
+
+</details>
+
+<details>
+<summary>English</summary>
+
+# ai-spec Design Rationale
+
+This document explains why ai-spec exists, what engineering problems it tries to solve, and how its architecture evolves from simple AI-assisted code generation into a more reliable software-delivery system.
+
+## Contents
+
+- [1. What problem this tool solves](#1-what-problem-this-tool-solves)
+- [2. Core architecture](#2-core-architecture)
+- [3. Why the DSL layer matters](#3-why-the-dsl-layer-matters)
+- [4. Feature matrix](#4-feature-matrix)
+- [5. Edge cases and safeguards](#5-edge-cases-and-safeguards)
+- [6. Suitable project types](#6-suitable-project-types)
+- [7. Current limitations](#7-current-limitations)
+- [8. Future directions](#8-future-directions)
+
+## 1. What problem this tool solves
+
+### 1.1 The core limitation of current AI coding tools
+
+Most AI coding tools are strong at local generation but weak at project-aware delivery. They can produce code quickly, yet often fail at:
+
+- respecting repository-specific architecture and naming rules
+- preserving API and data-layer conventions
+- keeping output consistent across files and across multiple tasks
+- turning a fuzzy requirement into a stable implementation contract
+
+### 1.2 ai-spec’s response
+
+ai-spec addresses those issues by inserting explicit structure between requirement and code:
+
+- a project constitution as evolving project memory
+- a human-readable feature spec
+- a machine-readable DSL contract
+- dependency-aware task orchestration
+- repair, review, and feedback loops after generation
+
+### 1.3 Architectural overview
+
+The system is designed as a staged pipeline rather than a single prompt. Each stage narrows ambiguity, adds project-specific constraints, and improves downstream reliability.
+
+## 2. Core architecture
+
+### 2.0 Full `ai-spec create` pipeline
+
+The pipeline moves through requirement understanding, constitution loading, project context extraction, spec generation, refinement, approval, DSL extraction, isolated generation, testing, error feedback, review, and historical learning.
+
+### 2.1 Project Constitution
+
+The constitution is an editable, project-specific memory layer. It stores architecture rules, naming conventions, API contracts, forbidden patterns, and accumulated lessons. It helps the tool stop guessing the same repository-level rules on every run.
+
+### 2.2 Dual contracts: Spec + DSL
+
+- The Spec is human-friendly and decision-oriented
+- The DSL is machine-friendly and deterministic
+
+The Spec helps humans review intent. The DSL helps downstream modules operate against a stable, explicit structure.
+
+### 2.3 Approval Gate
+
+Humans should intervene at the point of maximum leverage: after the spec becomes concrete but before code generation begins. Approval Gate enforces that control point.
+
+### 2.4 Task layering
+
+Generation follows dependency-aware task ordering instead of naive linear execution. This reduces breakage when later files depend on types, interfaces, stores, or APIs created earlier in the pipeline.
+
+### 2.5 Error feedback loop
+
+Instead of treating compile/test/lint errors as terminal failures, ai-spec feeds real errors back into an automated repair stage. This keeps the pipeline grounded in actual project feedback rather than pure prompt speculation.
+
+### 2.6 Frontend context awareness
+
+The tool extracts frontend-specific context such as API wrapper usage, hook/store conventions, pagination patterns, route structure, and testing setup so generated UI code matches the real codebase more closely.
+
+### 2.7 Cross-task consistency
+
+Generated File Cache helps preserve consistency across tasks so later outputs do not invent incompatible names, duplicate modules, or drift away from already-generated files.
+
+### 2.8 Behavioral contract extraction
+
+Behavioral rules such as list fetching, mutation flow, pagination, and status transitions are treated as project facts, not incidental examples. This reduces API/store hallucinations in frontend generation.
+
+### 2.9 `ai-spec learn`
+
+The `learn` command turns repeated issues discovered during review into low-friction knowledge injection by appending experience back into Constitution §9.
+
+### 2.10 Multi-language backend support
+
+The tool is designed to work across multiple backend stacks rather than being tied to one language ecosystem.
+
+### 2.11 Industrial reliability infrastructure
+
+This includes structured Run IDs, runtime logging, failure recovery, snapshot-based restore, and provider reliability work. The goal is to make the pipeline debuggable and restartable, not merely impressive when it succeeds once.
+
+### 2.12 Three-pass review
+
+The review stage evolved from a simpler review flow into a 3-pass process:
+
+- architecture review
+- implementation review
+- impact and complexity review
+
+This helps distinguish local code issues from broader system risk.
+
+### 2.13 Harness Engineer: from Prompt Hash to a quality data loop
+
+Harness Engineer is not just a label for a self-eval step. In ai-spec it is becoming an upper-layer design principle:
+
+- `create` records a `promptHash`
+- the run ends with deterministic self-evaluation
+- RunLog persists the result
+- `logs`, `trend`, and related tools support historical comparison
+
+The purpose is to turn the generation system into something measurable, comparable, and continuously optimizable, rather than a black-box sequence of prompts.
+
+## 3. Why the DSL layer matters
+
+### 3.1 Removing ambiguity between spec and code
+
+Natural-language specs leave too many details implicit. The DSL makes endpoints, models, auth, error codes, and behaviors explicit, so downstream generation does not need to guess.
+
+### 3.2 A shared contract for multiple downstream modules
+
+The DSL is not just for code generation. It becomes a reusable contract for review, export, mock generation, type generation, frontend injection, and future orchestration features.
+
+### 3.3 Anti-hallucination design
+
+The DSL narrows the output space and reduces free-form invention. It is a structural defense against hallucination, not merely a prompt tweak.
+
+## 4. Feature matrix
+
+The feature matrix shows how the system evolved from baseline spec generation into a multi-stage engineering pipeline with review, testing, repair, workspace orchestration, and harness observability.
+
+## 5. Edge cases and safeguards
+
+The document explicitly defines fallback behavior for failure scenarios such as:
+
+- DSL extraction failure
+- constitution loading or generation failure
+- task JSON corruption
+- interrupted code generation
+- bounded repair loops
+- git worktree edge cases
+- approval abort behavior
+- API key handling
+
+The core philosophy is graceful degradation: partial failure should not always collapse the entire pipeline.
+
+## 6. Suitable project types
+
+Best fit:
+
+- repositories with meaningful project conventions
+- teams that want repeatable feature delivery rather than one-off prompting
+- multi-step backend or frontend feature work
+- multi-repo systems with contract dependencies
+
+Lower fit:
+
+- highly experimental throwaway code
+- projects without stable conventions
+- tasks where architectural alignment matters less than speed
+
+Recommended model combinations are also documented for different cost/performance preferences.
+
+## 7. Current limitations
+
+The document is explicit about current constraints, including:
+
+- frontend context extraction still depends on repository consistency
+- the DSL only captures the classes of structure it is designed to model
+- constitutions can become too long
+- repair loops have practical upper bounds
+
+These limitations are treated as design boundaries, not hidden failure modes.
+
+## 8. Future directions
+
+Documented future work includes:
+
+- better multi-repo contract sync such as `ai-spec sync`
+- deeper CI/CD integration
+- stronger cross-run observability and evaluation signals
+
+The overall direction is clear: ai-spec is moving from “AI writes code for me” toward “AI-assisted delivery becomes a measurable engineering system.”
+
+*ai-spec v0.26.0 · Design Rationale Document · 2026-03-26*
+
+</details>