ai-spec-dev 0.25.0 → 0.28.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-spec-dev",
-  "version": "0.25.0",
+  "version": "0.28.1",
   "description": "AI-driven Development Orchestrator SDK & CLI",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/prompts/codegen.prompt.ts

@@ -265,3 +265,57 @@ Actionable, concrete improvements.
 Score: X/10 — Combined architecture + implementation assessment in one paragraph.
 
 Be specific. Reference actual code, not vague principles.`;
+
+// ─── Pass 3 — Impact & Complexity review ──────────────────────────────────────
+
+/**
+ * Pass 3 — Impact Assessment + Code Complexity.
+ * Answers two questions the previous passes deliberately skip:
+ *   1. What does this change touch / break outside its own files?
+ *   2. Is the new code easy or hard to understand and maintain?
+ *
+ * Receives both arch (Pass 1) and impl (Pass 2) reviews as context.
+ * Must NOT repeat findings already raised in those passes.
+ */
+export const reviewImpactComplexitySystemPrompt = `You are a Senior Staff Engineer assessing the RISK and MAINTAINABILITY of a code change.
+
+Two previous review passes have already covered architecture compliance and implementation correctness. Do NOT repeat their findings.
+
+Your job is to answer exactly two questions:
+
+---
+
+## 🌊 影响面评估 (Impact Assessment)
+
+Evaluate what this change touches beyond its own files:
+
+1. **直接影响文件** — List the files created or modified.
+2. **间接影响范围** — Which existing modules, API consumers, or downstream services will be affected? (e.g., shared utilities modified, public interfaces changed, database schema altered)
+3. **破坏性变更 (Breaking Changes)** — Are there changes requiring coordinated updates elsewhere?
+   - API endpoint signature changes (path, method, required params)
+   - Database schema changes (renamed columns, dropped fields, new NOT NULL constraints)
+   - Config / env variable changes
+   - Exported function/type renames
+   - If none: state "无破坏性变更"
+4. **影响等级** — Rate as 低 / 中 / 高 with one sentence justification.
+   - 低: isolated to new files, no shared interface changes
+   - 中: modifies shared utilities or existing public interfaces, backwards compatible
+   - 高: breaking changes, or touches core auth / payment / data integrity paths
+
+---
+
+## 🧮 代码复杂度评估 (Complexity Assessment)
+
+Evaluate how hard the new code will be to understand and change in the future:
+
+1. **认知复杂度热点** — Identify the 1-3 most complex functions/methods. For each, explain WHY (deep nesting, multiple early returns, implicit state mutation, mixed abstraction levels).
+2. **耦合度分析** — How tightly is the new code coupled to existing modules? Are dependencies injected or hardcoded? Any circular dependency risks?
+3. **可维护性风险** — Flag patterns that will cause pain when requirements change:
+   - Magic numbers / hardcoded strings that should be constants
+   - Business logic buried in framework lifecycle hooks or constructors
+   - Implicit temporal coupling (functions that must be called in a specific order)
+4. **复杂度等级** — Rate as 低 / 中 / 高 with one sentence justification.
+
+---
+
+Format using ONLY these two sections. Be specific. Reference file names and line ranges where relevant.`;

package/purpose.md

@@ -2,7 +2,7 @@
 
 > 痛点 · 架构创新 · 边界处理 · DSL 的意义 · 当前局限 · 未来方向
 >
-> 当前版本：v0.20.0 · 最后更新：2026-03-25
+> 当前版本：v0.28.0 · 最后更新：2026-03-26
 
 ***
 
@@ -10,6 +10,8 @@
 
 1. [这个工具在解决什么问题](#1-这个工具在解决什么问题)
 2. [核心架构设计](#2-核心架构设计)
+   - 2.11 [工业级可靠性基础设施（v0.27.0+）](#211-工业级可靠性基础设施v0270)
+   - 2.12 [3-pass 代码审查（v0.28.0+）](#212-3-pass-代码审查v0280)
 3. [DSL 层的意义](#3-dsl-层的意义)
 4. [完整功能矩阵](#4-完整功能矩阵)
 5. [边界情况与兜底机制](#5-边界情况与兜底机制)
@@ -17,7 +19,7 @@
 7. [当前局限](#7-当前局限)
 8. [未来优化方向](#8-未来优化方向)
 
-> **版本记录速览**：v0.17.0 宪法截断修复 · v0.18.0 `learn` + `minSpecScore` + 行为契约提取 · v0.19.0 错误解析重写 + Auto Gate 修复 · v0.20.0 `mock --serve` 一键联调
+> **版本记录速览**：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 影响面评估 + 代码复杂度评估）
 
 ***
 
@@ -130,17 +132,27 @@ Approval Gate 设计在「Spec 润色完成 + DSL 提取完成」之后、「代
 
 ### 2.4 Task 分层：依赖感知的生成顺序
 
-代码生成的顺序不是随意的。ai-spec 要求 AI 按 **data → infra → service → api → test** 的层级顺序生成：
+代码生成的顺序不是随意的。ai-spec 按固定层级顺序生成，前端和后端共用同一套层级体系：
 
-- Service 层调用 Prisma 模型 → 模型必须先存在
-- API 层调用 Service → Service 必须先存在
-- 测试引用真实的实现 → 实现必须先存在
+```
+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 | 单测、集成测试 | 同左 |
 
-乱序生成时，AI 会假设依赖存在并生成引用，结果所有文件都互相依赖但没有一个完整——这是 AI 代码生成最常见的「幻觉依赖」问题。层级顺序从根本上消除了这类问题。
+**前端四层链路设计（v0.22.0+）**：`service`（api 调用函数）→ `api`（store，导入 service 函数）→ `view`（页面，使用 store action）→ `route`（路由模块，导入 view 组件）。`route` 必须在 `view` 之后生成，因为路由文件需要知道 view 组件的确切文件名（如 `TaskManagement.vue` 而非猜测的 `index.vue`）——这是 v0.23.0 修复文件名幻觉的核心机制。
 
-每个 task 完成后立即写入 `status: done` 到 `tasks.json`，`--resume` 标志让流水线跳过已完成 task，中断恢复精确到 task 粒度。
+每个 task 完成后立即写入 `status: done` 到 `tasks.json`，`--resume` 标志让流水线跳过已完成 task，中断恢复精确到 task 粒度。`tasks.json` 文件损坏时（意外截断等）能检测并优雅降级，提示重新生成（v0.26.0）。
 
-**同层并行执行**：同一层内的多个 task（如 3 个 service）通过 `Promise.all` 并发执行，可将多 task 功能的生成时间从线性缩短到接近单 task 耗时。跨层依赖（service 依赖 data）严格串行保障；同层 task 共享本层开始前的 `generatedFileCache` 快照，层全部完成后统一写入缓存供下一层使用。共享配置文件（如 `routes/index.ts`）从并行 filePlan 中剥离，改为层完成后统一 batch update，避免并发覆写冲突。
+**同层并行 + 层内拓扑排序（v0.24.0+）**：同一层内的多个 task 通过 `Promise.all` 并发执行。若某 task 声明了对同层另一 task 的 `dependencies`，则先通过 Kahn 算法分拆为多个 batch，batch 间串行，batch 内并行；每个 batch 完成后立即更新 `generatedFileCache`，确保后续 batch 能看到前驱 task 的导出名。跨层依赖由层级顺序本身保障。单个 task 的意外异常（磁盘满、provider 超时）只影响自身，不中断同层其他 task（v0.26.0 `.catch` 降级）。共享配置文件（如 `routes/index.ts`）从并行 filePlan 中剥离，层完成后统一 batch update，避免并发覆写冲突。
 
 ***
 
@@ -198,17 +210,32 @@ Approval Gate 设计在「Spec 润色完成 + DSL 提取完成」之后、「代
 
 扫描覆盖范围：`src/api/`、`src/apis/`、`src/services/`、`src/router/`、`src/routes/`、`src/store/`、`src/stores/`、`src/components/`、`src/views/`、`src/pages/`。
 
+**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，提取可靠性从「经常为空」提升到「能找到就找到」。
+
 ***
 
 ### 2.7 跨 Task 一致性（Generated File Cache）
 
 多文件功能由多次独立 AI 调用完成。Task B 的 AI 实例无法感知 Task A 刚写了什么——这是跨 task 函数名幻觉的根本原因（`getTaskList` 被猜成 `getTasks`）。
 
-**解决方案**：`generatedFileCache` — 每个 task 完成后，将写入的 `src/api*` / `src/service*` / `src/store*` / `src/composable*` 文件读回并缓存到内存 Map；后续每个 task 的 prompt 中追加 `=== Files Already Generated in This Run ===` 区段，内容为缓存文件的实际代码。
+**解决方案**：`generatedFileCache` — 每个 task 完成后，将写入的文件读回并缓存到内存 Map（批次完成后更新，v0.24.0 引入批次级更新）；后续每个 task 的 prompt 中追加 `=== Files Already Generated in This Run ===` 区段。
 
-系统提示中有对应的强制规则（Rule 17）：该区段中的导出函数名是权威来源，NEVER 重命名或猜测替代名。
+缓存策略按文件类型分层（v0.23.0+）：
 
-**路由模块注册**：当 task 新建路由模块文件时，`routes/index.ts` 被注入为 shared config file，purpose 字段精确指定需要 import 的模块名（而非通用描述），配合 Rule 16 强制要求 AI 同时更新 index 文件。
+| 文件类型 | 缓存内容 | 原因 |
+|---------|---------|------|
+| `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 强制使用该确切路径，幻觉消除。
+
+系统提示 Rule 17：`=== Files Already Generated ===` 区段中的导出函数名和文件路径是唯一权威来源，NEVER 重命名、猜测替代名、或将 `// exists:` 路径替换为 `index.vue` 等默认名。
+
+**路由模块注册**：当 task 新建路由模块文件时，`routes/index.ts` 被注入为 shared config file，purpose 字段精确指定需要 import 的模块名，配合 Rule 16 强制要求 AI 同时更新 index 文件。`route`/`view`/`api` 层 task 创建新文件时无论 task 描述是否含关键词，均无条件触发注册更新（v0.24.0 层级直接判断修复，消除关键词匹配漏报）。
 
 ***
 
@@ -217,15 +244,25 @@ Approval Gate 设计在「Spec 润色完成 + DSL 提取完成」之后、「代
 跨 task 一致性的另一个维度：Task B 的 AI 不只需要知道「已生成了哪些文件」，还需要知道「这些文件里导出了什么、接受什么参数、会抛出什么异常」。`generatedFileCache` 存文件内容；`extractBehavioralContract` 从中蒸馏出精确的接口合约：
 
 ```typescript
-// 提取逻辑：
+// 提取逻辑（按优先级）：
 // 1. 完整捕获 export interface / type X = { / class / abstract class / enum
-//    → 使用大括号深度计数器，直到对应 } 为止（v0.19.0 修复了只取第一行的 bug）
-// 2. 捕获单行 export function / export const 签名
-// 3. 提取 throw new XxxError / throw createXxx 模式（最多 20 条）
-// 4. 所有以上内容均无法提取时，回退到文件前 3000 字符
+//    → 使用大括号深度计数器直到对应 } 为止（v0.19.0 修复了只取第一行的 bug）
+// 2. 完整捕获 export const X = defineStore/createStore/createSlice(...)
+//    → 使用圆括号深度计数器，将整个 defineStore 调用体（含 return {}）捕获
+//    → v0.21.0 修复：之前只捕获第一行，AI 看不到 return { fetchTasks } 导致猜成 fetchTaskList
+// 3. 完整捕获 return { ... }（composable/store 公开 API）
+//    → 标注 "// public API (return object):"，是消费者调用的唯一合法来源
+//    → v0.21.0 新增
+// 4. 完整捕获 export default function/class（React 组件、class 组件）
+//    → v0.24.0 新增，与 defineStore 捕获对称
+// 5. 单行 export function / export const / export type 签名
+// 6. throw new XxxError / throw createXxx 模式（最多 20 条）
+// 7. 所有以上均无法提取时，回退到文件前 3000 字符
 ```
 
-**为什么不直接传整个文件内容**：多 task 并行时，context 窗口压力大。一个 service 文件可能 500 行，但真正影响下游 task 的「接口合约」只有 20-30 行。蒸馏出来的 Behavioral Contract 让 AI 准确知道「我可以调用 `UserService.getUser(id: string): Promise<User | null>`」，而不是要从 500 行代码里自己推断。
+**store/composable 文件特殊处理**：这类文件的「接口合约」不是类型签名，而是 `return {}` 里暴露的 action 名。`extractBehavioralContract` 对 store 文件会捕获整个 `defineStore(...)` 调用体，确保 `return { fetchTasks, createTask }` 可见，避免 AI 在调用 store 时发明 `fetchTaskList`、`addTask` 等替代名。
+
+**为什么不直接传整个文件内容**：多 task 并行时，context 窗口压力大。一个 service 文件可能 500 行，但真正影响下游 task 的「接口合约」只有 20-30 行。蒸馏出来的 Behavioral Contract 让 AI 准确知道「我可以调用 `UserService.getUser(id: string): Promise<User | null>`」，而不是要从 500 行代码里自己推断。例外：store/composable 文件传完整内容，因为整个文件本身就是契约（action 名散布在函数体中，蒸馏后可能遗漏）。
 
 ### 2.9 `ai-spec learn`：零摩擦知识注入（v0.18.0+）
 
@@ -260,6 +297,88 @@ ai-spec learn "登录态校验中间件是 authMiddleware，不是 verifyToken"
 | Python / FastAPI      | `requirements.txt` / `pyproject.toml` | Pydantic 模型、`APIRouter` 注册、type annotations           |
 | Rust / Axum           | `Cargo.toml`                          | `Result<T,E>`、no `unwrap()` in production、tokio async |
 
+### 2.11 工业级可靠性基础设施（v0.27.0+）
+
+实验性工具和生产可用工具之间的差距，很大程度上体现在「出错时的行为」上。v0.27.0 引入三项底层可靠性机制：
+
+**① Provider 重试 / 超时 / 错误分类（`provider-utils.ts`）**
+
+所有 AI provider 调用统一通过 `withReliability()` 包装：
+
+```
+超时：90s（可配置）
+重试：最多 2 次，指数退避（2s → 6s）
+错误分类：auth（401/403，不重试）| rate_limit | timeout | network | provider
+```
+
+认证错误不重试（key 已无效，重试无意义）；网络抖动和限流错误重试。所有错误附带结构化的 `ProviderError`（含 `kind` 字段），上层可按 kind 差异化处理。
+
+**② 写前文件快照 + `ai-spec restore <runId>`（`run-snapshot.ts`）**
+
+每次生成运行生成唯一 `RunId`（格式：`YYYYMMDD-HHMMSS-xxxx`）。在写入任何文件之前，先将原始内容备份到 `.ai-spec-backup/<runId>/`（如果文件不存在则跳过）。
+
+```bash
+ai-spec restore 20260326-143022-a7f2
+# → 将该 runId 覆盖的所有文件还原到生成前的状态
+# → 打印每个还原文件的路径
+```
+
+**适用场景**：生成结果不满意、AI 覆盖了不该覆盖的文件、想对比生成前后差异时——无需 `git checkout`，一条命令精确还原。
+
+**③ RunId + 结构化 JSON 日志（`run-logger.ts`）**
+
+每次运行在 `.ai-spec-logs/<runId>.json` 写入结构化日志：
+
+```json
+{
+  "runId": "20260326-143022-a7f2",
+  "startedAt": "2026-03-26T14:30:22.000Z",
+  "finishedAt": "...",
+  "durationMs": 42310,
+  "filesWritten": ["src/api/task.ts", "src/stores/taskStore.ts", ...],
+  "events": [
+    { "event": "spec_gen_start", "ts": "..." },
+    { "event": "codegen_task", "ts": "...", "data": { "task": "api" } },
+    { "event": "review_pass1", "ts": "..." },
+    ...
+  ]
+}
+```
+
+Run 结束后自动打印摘要（RunId、总耗时、写入文件数、日志路径）。日志供排查问题、统计各阶段耗时、追踪历史运行使用。
+
+***
+
+### 2.12 3-pass 代码审查（v0.28.0+）
+
+`ai-spec review` 从「2-pass」升级为「3-pass」，新增 Pass 3 影响面与复杂度评估：
+
+| Pass | 关注维度 | 核心问题 |
+|------|---------|---------|
+| **Pass 1 架构审查** | Spec 符合度、层级分离、认证中间件使用 | 这次改动是否破坏了架构边界？ |
+| **Pass 2 实现审查** | 参数校验、错误处理、边界值、历史问题复现检测 | 实现细节是否健壮、有没有老问题重演？ |
+| **Pass 3 影响面 + 复杂度** | 直接文件 / 间接传播范围 / Breaking Change / 认知复杂度 / 耦合分析 | 这次改动的波及范围和维护风险有多大？ |
+
+**Pass 3 输出结构**：
+
+```
+影响面评估
+  ├─ 直接文件：本次 diff 涉及的文件（逐一列出）
+  ├─ 间接范围：调用这些文件的上游模块（分析依赖关系）
+  ├─ Breaking Change 风险：接口签名 / 类型定义 / 错误码是否变更
+  └─ 影响等级：低 | 中 | 高
+
+代码复杂度评估
+  ├─ 认知复杂度热点：嵌套层数深、条件分支多的函数（具体指出）
+  ├─ 耦合分析：与多少个模块产生了新依赖
+  ├─ 可维护性风险：魔法数字、职责混淆、测试困难点
+  └─ 复杂度等级：低 | 中 | 高
+```
+
+**影响等级** 和 **复杂度等级** 被写入审查历史（`.ai-spec-reviews.json`），下次 review 的历史趋势图中可见，帮助团队长期追踪代码质量走势。
+
+Pass 3 不重复 Pass 1 / Pass 2 的发现，而是站在更高的系统视角回答「这次 PR 的风险有多大、后续维护成本是多少」这两个问题。
+
 ***
 
 ## 3. DSL 层的意义
@@ -321,35 +440,40 @@ DSL 提取本身是高幻觉风险操作。ai-spec 做了几个针对性设计
 
 ## 4. 完整功能矩阵
 
-截至 v0.20.0，ai-spec 的完整能力覆盖：
+截至 v0.28.0，ai-spec 的完整能力覆盖：
 
 | 阶段 | 命令 | 核心能力 |
 |------|------|---------|
 | **初始化** | `ai-spec init` | 扫描项目 → 生成宪法 §1-§8（`--global` 生成全局宪法，`--consolidate` 整合 §9） |
-| **新功能** | `ai-spec create` | 宪法（全文，v0.17.0 移除截断）→ context → Spec+Tasks → **Spec质量评估 + minSpecScore Gate** → Approval Gate → DSL → Worktree → 逐 task codegen（同层并行 + 行为契约缓存）→ **TDD（`--tdd`）** → 错误反馈闭环（全文扫描，v0.19.0）→ 测试骨架 → **2-pass review** |
+| **新功能** | `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 对比）→ 识别受影响文件 → 可选重新生成 |
 | **接口导出** | `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，实时去重（v0.18.0+） |
-| **代码审查** | `ai-spec review` | git diff + Spec → AI 架构审查 → issue 写入宪法 §9 |
+| **知识注入** | `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` 完成后自动启动联调环境 |
 
-**单 Repo 流水线总图：**
+**单 Repo 流水线总图（v0.28.0）：**
 
 ```
 需求描述
-  → 项目宪法（全文注入）+ 多语言 Context 感知
+  → 项目宪法（全文注入）+ 多语言 Context 感知 + 前端 Context 提取
     → Spec + Tasks（合并生成）
       → 交互式润色（Diff 预览）
         → Spec 质量评估（minSpecScore 阈值）
           → Approval Gate
-            → DSL 提取 + 校验（抗幻觉）
-              → Git Worktree 隔离
-                → 逐 task 代码生成（依赖层级 + 行为契约缓存）
-                  → 错误反馈闭环（全文扫描解析，≤2 轮）
-                    → 测试骨架生成
-                      → AI 代码审查
-                        → 经验写入宪法 §9
+            → RunId 生成 + RunSnapshot 初始化（v0.27.0）
+              → DSL 提取 + 校验（抗幻觉，≤2 次 retry）
+                → Git Worktree 隔离
+                  → 逐 task 代码生成（每次写文件前先快照原内容）
+                      data → infra → service → api → view → route → test
+                      同层内：拓扑排序分 batch → batch 内并行 → 批次间串行更新缓存
+                    → 错误反馈闭环（全文扫描解析，≤2 轮，写前快照）
+                      → 测试骨架生成
+                        → AI 代码审查（3-pass：架构 + 实现 + 影响面/复杂度）
+                          → Run 结构化日志写入（v0.27.0）
+                            → 经验写入宪法 §9
 ```
 
 **多 Repo 工作区 + 一键联调（v0.20.0+）：**
@@ -414,6 +538,7 @@ Spec + Tasks 在同一次 AI 调用中生成。Tasks 部分解析失败时：
 | 修复的文件不存在              | 跳过该文件，记录 `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 边界
 
@@ -474,6 +599,8 @@ ai-spec 不是通用工具。它在特定类型的项目上效果非常好，在
 
 `frontend-context-loader` 的提取逻辑基于约定俗成的目录结构（`src/apis/`、`src/stores/` 等）和代码特征（interface 字段名、import 路径模式）。对于不遵循常规结构的前端项目，提取可能失败，AI 会回退到通用默认值，输出一致性下降。
 
+v0.25.0 已修复两个高频提取失败场景：`httpClientImport` 正则过窄（现已覆盖所有主流别名和 HTTP 库），`paginationExample` 正则无法匹配含嵌套对象的接口和 arrow function（现已全部改为逐行提取）。仍可能提取失败的场景：目录结构高度定制、API 文件内无分页参数、项目完全无 HTTP 封装层。
+
 ### 7.3 DSL 的有效范围
 
 DSL 设计主要针对 REST API 场景（HTTP 端点 + 数据模型）。对于以下场景，DSL 无法有效提取结构：
@@ -514,4 +641,4 @@ DSL 设计主要针对 REST API 场景（HTTP 端点 + 数据模型）。对于
 
 ***
 
-*ai-spec v0.20.0 · Design Rationale Document · 2026-03-25*
+*ai-spec v0.26.0 · Design Rationale Document · 2026-03-26*