ai-spec-dev 0.33.0 → 0.35.0

package/README.md

@@ -1,20 +1,25 @@
 # ai-spec
 
-GitHub: https://github.com/hzhongzhong/ai-spec
+<details open>
+<summary>中文</summary>
+
+GitHub: <https://github.com/hzhongzhong/ai-spec>
 
 > AI 驱动的功能开发编排工具 — 从一句话需求到可运行代码的完整流水线，支持单 Repo 及多 Repo 跨端联动
 
 **单 Repo 模式：**
+
 ```
-需求描述 → 项目宪法 → 项目感知 → Spec+Tasks → 交互式润色(Diff预览) → Spec质量预评估 → Approval Gate → DSL提取+校验 → Git 隔离 → 代码生成(同层并行) → TDD测试(--tdd) / 测试骨架 → 错误反馈自动修复 → 3-pass 代码审查 → 经验积累(宪法§9)
+需求描述 → 项目宪法 → 项目感知 → Spec+Tasks → 交互式润色(Diff预览) → Spec质量预评估 → Approval Gate → DSL提取+校验 → DSL Gap Feedback（稀疏时定向补全文档） → Git 隔离 → 代码生成(同层并行) → TDD测试(--tdd) / 测试骨架 → 错误反馈自动修复 → 3-pass 代码审查 → Review→DSL Loop（结构性问题反写契约） → Harness Self-Eval → 经验积累(宪法§9)
 ```
 
 **多 Repo 模式（工作区）：**
+
 ```
 一句需求 → AI 拆分职责+UX决策 → [后端流水线 → DSL契约] → [前端流水线（注入后端契约）] → 全链路完成
 ```
 
----
+***
 
 ## 目录
 
@@ -29,7 +34,7 @@ GitHub: https://github.com/hzhongzhong/ai-spec
 - [项目结构](#项目结构)
 - [Release Log](RELEASE_LOG.md)
 
----
+***
 
 ## 快速开始
 
@@ -72,6 +77,9 @@ ai-spec create "给用户模块增加登录功能"
           Behaviors : 1
           POST   /api/v1/auth/login  → 200
           ...
+[DSL+]  DSL Gap feedback...                               ← DSL 稀疏时出现
+        Found gap: missing_errors
+        🔧 Refine spec / ⏭ Skip
 [4/6]   Setting up git worktree...
 [5/6]   ✔ Spec saved : specs/feature-user-login-v1.md (v1)
         ✔ DSL saved  : specs/feature-user-login-v1.dsl.json
@@ -81,11 +89,11 @@ ai-spec create "给用户模块增加登录功能"
         [████░░░░░░░░░░░░░░░░]  20% → TASK-001 💾 Add schema
         [████████░░░░░░░░░░░░]  40% → TASK-002 🔧 Service 层
         ✔ Task-based generation: 8/8 files written across 5 tasks.
-[7/9]   Test skeleton generation...                        ← --skip-tests 可跳过
+[7/10]  Test skeleton generation...                        ← --skip-tests 可跳过
         + tests/auth.test.ts                               ← --tdd 时改为 TDD 真实断言
         + tests/auth.service.test.ts
         ✔ 2 test file(s) generated.
-[8/9]   Error feedback loop...                             ← --skip-error-feedback 可跳过
+[8/10]  Error feedback loop...                             ← --skip-error-feedback 可跳过
         [cycle 1/2] Running tests: npm test
         ✘ Tests failed (3 error(s) captured)
         Attempting auto-fix (3 error(s))...
@@ -98,6 +106,15 @@ ai-spec create "给用户模块增加登录功能"
         Pass 2/3: Implementation review...
         Pass 3/3: Impact & complexity assessment...
         🌊 影响等级: 中  🧮 复杂度等级: 低
+[9.5/10] Review → DSL feedback...
+         Found 1 structural issue that should be fixed in Spec/DSL
+         Suggested next step: ai-spec update "补充错误码与鉴权约束" --codegen
+[10/10] Harness Self-Eval...
+─── 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
 ─── Knowledge Memory ─────────────────────────────
         ✔ 2 lesson(s) appended to constitution (§9).
   Run ID: 20260326-143022-ab3f in 94.3s · 8 files written
@@ -105,37 +122,38 @@ ai-spec create "给用户模块增加登录功能"
   To undo changes: ai-spec restore 20260326-143022-ab3f
 ```
 
----
+***
 
 ## 支持的模型
 
-| Provider | 关键词 | API Key 环境变量 | 默认模型 |
-|---|---|---|---|
-| MiMo (Xiaomi) | `mimo` | `MIMO_API_KEY` | `mimo-v2-pro` |
-| Google Gemini | `gemini` | `GEMINI_API_KEY` | `gemini-2.5-pro` |
-| Anthropic Claude | `claude` | `ANTHROPIC_API_KEY` | `claude-opus-4-6` |
-| OpenAI | `openai` | `OPENAI_API_KEY` | `o3` |
-| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | `deepseek-chat` |
-| 通义千问 | `qwen` | `DASHSCOPE_API_KEY` | `qwen3-235b-a22b` |
-| 智谱 GLM | `glm` | `ZHIPU_API_KEY` | `glm-5` |
-| MiniMax | `minimax` | `MINIMAX_API_KEY` | `MiniMax-Text-2.7` |
-| 豆包 Doubao | `doubao` | `ARK_API_KEY` | `doubao-pro-256k` |
+| Provider         | 关键词        | API Key 环境变量        | 默认模型               |
+| ---------------- | ---------- | ------------------- | ------------------ |
+| MiMo (Xiaomi)    | `mimo`     | `MIMO_API_KEY`      | `mimo-v2-pro`      |
+| Google Gemini    | `gemini`   | `GEMINI_API_KEY`    | `gemini-2.5-pro`   |
+| Anthropic Claude | `claude`   | `ANTHROPIC_API_KEY` | `claude-opus-4-6`  |
+| OpenAI           | `openai`   | `OPENAI_API_KEY`    | `o3`               |
+| DeepSeek         | `deepseek` | `DEEPSEEK_API_KEY`  | `deepseek-chat`    |
+| 通义千问             | `qwen`     | `DASHSCOPE_API_KEY` | `qwen3-235b-a22b`  |
+| 智谱 GLM           | `glm`      | `ZHIPU_API_KEY`     | `glm-5`            |
+| MiniMax          | `minimax`  | `MINIMAX_API_KEY`   | `MiniMax-Text-2.7` |
+| 豆包 Doubao        | `doubao`   | `ARK_API_KEY`       | `doubao-pro-256k`  |
 
 **各 provider 可用模型：**
 
-| Provider | 模型列表 |
-|---|---|
-| mimo | `mimo-v2-pro` |
-| gemini | `gemini-2.5-pro` · `gemini-2.5-flash` · `gemini-2.0-flash` · `gemini-2.0-flash-lite` · `gemini-1.5-pro` |
-| claude | `claude-opus-4-6` · `claude-sonnet-4-6` · `claude-haiku-4-5` · `claude-3-7-sonnet-20250219` |
-| openai | `o3` · `o3-mini` · `o1` · `o1-mini` · `gpt-4o` · `gpt-4o-mini` |
-| deepseek | `deepseek-chat`（V3）· `deepseek-reasoner`（R1） |
-| qwen | `qwen3-235b-a22b` · `qwen3-72b` · `qwen3-32b` · `qwen3-8b` · `qwen-max` · `qwen-plus` |
-| glm | `glm-5` · `glm-5-flash` · `glm-z1`（推理）· `glm-z1-flash` · `glm-4-plus` · `glm-4-flash` |
-| minimax | `MiniMax-Text-2.7` · `MiniMax-Text-01` · `abab6.5s-chat` |
-| doubao | `doubao-pro-256k` · `doubao-pro-128k` · `doubao-pro-32k` · `doubao-lite-128k` |
+| Provider | 模型列表                                                                                                    |
+| -------- | ------------------------------------------------------------------------------------------------------- |
+| mimo     | `mimo-v2-pro`                                                                                           |
+| gemini   | `gemini-2.5-pro` · `gemini-2.5-flash` · `gemini-2.0-flash` · `gemini-2.0-flash-lite` · `gemini-1.5-pro` |
+| claude   | `claude-opus-4-6` · `claude-sonnet-4-6` · `claude-haiku-4-5` · `claude-3-7-sonnet-20250219`             |
+| openai   | `o3` · `o3-mini` · `o1` · `o1-mini` · `gpt-4o` · `gpt-4o-mini`                                          |
+| deepseek | `deepseek-chat`（V3）· `deepseek-reasoner`（R1）                                                            |
+| qwen     | `qwen3-235b-a22b` · `qwen3-72b` · `qwen3-32b` · `qwen3-8b` · `qwen-max` · `qwen-plus`                   |
+| glm      | `glm-5` · `glm-5-flash` · `glm-z1`（推理）· `glm-z1-flash` · `glm-4-plus` · `glm-4-flash`                   |
+| minimax  | `MiniMax-Text-2.7` · `MiniMax-Text-01` · `abab6.5s-chat`                                                |
+| doubao   | `doubao-pro-256k` · `doubao-pro-128k` · `doubao-pro-32k` · `doubao-lite-128k`                           |
 
 > **兼容说明：**
+>
 > - MiMo：Anthropic messages 格式，自定义 `api-key` 鉴权头（非标准 Bearer），通过 axios 直接调用
 > - DeepSeek / Qwen / GLM / MiniMax / Doubao：OpenAI 兼容接口
 > - OpenAI o1/o3：自动切换为 `developer` role（不使用 `system`）
@@ -147,7 +165,7 @@ ai-spec create "给用户模块增加登录功能"
 ai-spec model --list
 ```
 
----
+***
 
 ## 命令总览
 
@@ -158,7 +176,9 @@ ai-spec create [idea]       完整工作流：宪法 → context → spec → ta
 ai-spec update [change]     增量更新：修改现有 Spec → 重提取 DSL → 识别受影响文件 → 可选重新生成代码
 ai-spec learn [lesson]      零摩擦知识注入：直接将工程决策或教训写入宪法 §9（无需运行 review）
 ai-spec export              DSL → OpenAPI 3.1.0 YAML/JSON（可导入 Postman / Swagger UI / openapi-generator）
+ai-spec types               DSL → TypeScript 类型文件（models / endpoint request types / API_ENDPOINTS 常量）
 ai-spec mock                从 DSL 生成 Mock Server / 前端 Proxy 配置 / MSW Handlers（联调利器）
+ai-spec dashboard           生成静态 HTML Harness Dashboard（评分趋势 / prompt 版本对比 / 阶段耗时 / 错误统计）
 ai-spec review [file]       对当前 git diff 运行 3-pass AI 代码审查（架构层 + 实现层 + 影响面/复杂度），并打印评分趋势
 ai-spec restore <runId>     回滚指定 run 修改的所有文件至原始状态（配合 Run ID 使用）
 ai-spec model               交互式切换 AI provider / model，写入 .ai-spec.json
@@ -222,6 +242,7 @@ ai-spec create                      # 省略 idea 时交互式询问
 ```
 
 > **Worktree 自动策略：**
+>
 > - 后端项目（Node.js / Go / PHP 等）：默认创建 worktree 隔离分支
 > - 前端项目（React / Vue / Next / React-Native）：**自动跳过 worktree**，直接在当前仓库生成代码
 >   - 原因：worktree 不含 `node_modules`，前端 dev server 无法启动
@@ -257,8 +278,9 @@ ai-spec config --reset              # 清空配置文件
 ```
 
 > **Spec 质量门槛（minSpecScore）**
+>
 > - 设置后，`create` 在 Approval Gate 前会运行质量评估，`overallScore` 低于阈值时阻断流程
-> - **`--auto` 模式同样生效**：CI 环境中配置了门槛则强制执行，避免低质量 Spec 静默通过
+> - **`--auto`** **模式同样生效**：CI 环境中配置了门槛则强制执行，避免低质量 Spec 静默通过
 > - `--force` 可临时绕过（输出黄色警告）
 > - 未配置（默认 0）时评估仅为建议性，不阻断
 
@@ -315,7 +337,7 @@ ai-spec mock --serve --frontend <path>          # 生成后直接启动 Mock 服
 ai-spec mock --restore --frontend <path>        # 撤销 Proxy patch，停止 Mock 服务器
 ```
 
----
+***
 
 ## 命令详解
 
@@ -354,15 +376,15 @@ ai-spec init --force
 
 **选项：**
 
-| 选项 | 说明 |
-|---|---|
-| `--provider <name>` | 使用的 AI provider |
-| `--model <name>` | 使用的模型 |
-| `-k, --key <key>` | API Key |
-| `--force` | 覆盖已有宪法文件 |
-| `--global` | 生成团队级全局宪法（`.ai-spec-global-constitution.md`）而非项目宪法 |
-| `--consolidate` | 整合宪法：将 §9 提炼归并到 §1–§8，清理冗余 |
-| `--dry-run` | 配合 `--consolidate`：预览不写入 |
+| 选项                  | 说明                                                 |
+| ------------------- | -------------------------------------------------- |
+| `--provider <name>` | 使用的 AI provider                                    |
+| `--model <name>`    | 使用的模型                                              |
+| `-k, --key <key>`   | API Key                                            |
+| `--force`           | 覆盖已有宪法文件                                           |
+| `--global`          | 生成团队级全局宪法（`.ai-spec-global-constitution.md`）而非项目宪法 |
+| `--consolidate`     | 整合宪法：将 §9 提炼归并到 §1–§8，清理冗余                         |
+| `--dry-run`         | 配合 `--consolidate`：预览不写入                           |
 
 > **全局宪法 vs 项目宪法**：全局宪法定义团队通用规范（错误码体系、认证模式、日志格式）；项目宪法定义本项目特有规范（数据模型、路由前缀、特定限制）。运行时自动合并，项目宪法优先。
 
@@ -381,13 +403,14 @@ ai-spec init --consolidate
 ```
 
 整合过程：
+
 1. AI 逐条审阅 §9，决定每条教训的去向：**LIFT**（提升至 §1–§8）/ **KEEP**（保留，最多 5 条）/ **DROP**（删除重复/已失效）
 2. 展示彩色 diff，显示前后对比
 3. 自动创建备份（`.ai-spec-constitution.backup-YYYY-MM-DD-HH-MM-SS.md`）后写入
 
 典型效果：§9 从 14 条压缩到 4 条，宪法总行数减少 10–20%，核心章节获得新的精确规则。
 
----
+***
 
 ### `ai-spec create [idea]`
 
@@ -419,36 +442,36 @@ ai-spec create "小功能" --skip-tasks
 
 **完整选项：**
 
-| 选项 | 说明 | 默认值 |
-|---|---|---|
-| `--provider <name>` | Spec 生成使用的 provider | `gemini` |
-| `--model <name>` | Spec 生成使用的模型 | provider 默认模型 |
-| `-k, --key <key>` | API Key（优先级高于环境变量） | — |
-| `--codegen <mode>` | 代码生成模式：`claude-code` / `api` / `plan` | `claude-code` |
-| `--codegen-provider <name>` | 代码生成使用的 provider | 同 `--provider` |
-| `--codegen-model <name>` | 代码生成使用的模型 | — |
-| `--codegen-key <key>` | 代码生成的 API Key | — |
-| `--skip-worktree` | 跳过 git worktree 创建 | — |
-| `--skip-review` | 跳过最终代码审查 | — |
-| `--skip-tasks` | 跳过 Tasks 分解（只生成 Spec） | — |
-| `--auto` | 非交互模式：用 `claude -p` 执行，同时跳过 Approval Gate（节省 token） | — |
-| `--fast` | 跳过交互式 Spec 润色，直接进入代码生成（适合全自动流水线） | — |
-| `--resume` | 续跑模式：跳过 tasks.json 中已标记为 `done` 的任务 | — |
-| `--skip-dsl` | 跳过 DSL 提取步骤（适合简单功能或快速迭代） | — |
-| `--skip-tests` | 跳过测试骨架生成（需要 DSL；`--skip-dsl` 时自动跳过） | — |
-| `--skip-error-feedback` | 跳过错误反馈自动修复循环 | — |
-| `--tdd` | TDD 模式：代码生成前先写含真实断言的测试，error feedback loop 驱动实现让测试通过（最多 3 轮）。仅支持后端项目 | — |
-| `--skip-assessment` | 跳过 Approval Gate 前的 Spec 质量预评估（节省一次 AI 调用） | — |
-
-**`--codegen` 三种模式：**
-
-| 模式 | 说明 |
-|---|---|
+| 选项                          | 说明                                                                   | 默认值            |
+| --------------------------- | -------------------------------------------------------------------- | -------------- |
+| `--provider <name>`         | Spec 生成使用的 provider                                                  | `gemini`       |
+| `--model <name>`            | Spec 生成使用的模型                                                         | provider 默认模型  |
+| `-k, --key <key>`           | API Key（优先级高于环境变量）                                                   | —              |
+| `--codegen <mode>`          | 代码生成模式：`claude-code` / `api` / `plan`                                | `claude-code`  |
+| `--codegen-provider <name>` | 代码生成使用的 provider                                                     | 同 `--provider` |
+| `--codegen-model <name>`    | 代码生成使用的模型                                                            | —              |
+| `--codegen-key <key>`       | 代码生成的 API Key                                                        | —              |
+| `--skip-worktree`           | 跳过 git worktree 创建                                                   | —              |
+| `--skip-review`             | 跳过最终代码审查                                                             | —              |
+| `--skip-tasks`              | 跳过 Tasks 分解（只生成 Spec）                                                | —              |
+| `--auto`                    | 非交互模式：用 `claude -p` 执行，同时跳过 Approval Gate（节省 token）                  | —              |
+| `--fast`                    | 跳过交互式 Spec 润色，直接进入代码生成（适合全自动流水线）                                     | —              |
+| `--resume`                  | 续跑模式：跳过 tasks.json 中已标记为 `done` 的任务                                  | —              |
+| `--skip-dsl`                | 跳过 DSL 提取步骤（适合简单功能或快速迭代）                                             | —              |
+| `--skip-tests`              | 跳过测试骨架生成（需要 DSL；`--skip-dsl` 时自动跳过）                                  | —              |
+| `--skip-error-feedback`     | 跳过错误反馈自动修复循环                                                         | —              |
+| `--tdd`                     | TDD 模式：代码生成前先写含真实断言的测试，error feedback loop 驱动实现让测试通过（最多 3 轮）。仅支持后端项目 | —              |
+| `--skip-assessment`         | 跳过 Approval Gate 前的 Spec 质量预评估（节省一次 AI 调用）                           | —              |
+
+**`--codegen`** **三种模式：**
+
+| 模式            | 说明                                                                           |
+| ------------- | ---------------------------------------------------------------------------- |
 | `claude-code` | 启动 Claude Code CLI。`--auto` 时改为逐 task 运行 `claude -p`（增量执行，失败可 `--resume` 续跑） |
-| `api` | 调用 AI API 自动规划文件并逐文件生成。有 Tasks 文件时按 task 顺序生成，支持 `--resume` 续跑 |
-| `plan` | 仅输出实施方案，不写任何代码 |
+| `api`         | 调用 AI API 自动规划文件并逐文件生成。有 Tasks 文件时按 task 顺序生成，支持 `--resume` 续跑               |
+| `plan`        | 仅输出实施方案，不写任何代码                                                               |
 
----
+***
 
 ### `ai-spec review [specFile]`
 
@@ -495,7 +518,7 @@ ai-spec review --provider glm --model glm-5
 
 > 提示：先执行 `git add .` 再运行 `ai-spec review`，确保所有变更都被纳入审查。
 
----
+***
 
 ### `ai-spec model`
 
@@ -509,7 +532,7 @@ ai-spec model
 ai-spec model --list
 ```
 
----
+***
 
 ### `ai-spec config`
 
@@ -522,17 +545,17 @@ ai-spec config --codegen-provider glm --codegen-model glm-5
 ai-spec config --reset
 ```
 
-| 选项 | 说明 |
-|---|---|
-| `--provider <name>` | 默认 spec provider |
-| `--model <name>` | 默认 spec model |
-| `--codegen <mode>` | 默认代码生成模式 |
+| 选项                          | 说明                  |
+| --------------------------- | ------------------- |
+| `--provider <name>`         | 默认 spec provider    |
+| `--model <name>`            | 默认 spec model       |
+| `--codegen <mode>`          | 默认代码生成模式            |
 | `--codegen-provider <name>` | 默认 codegen provider |
-| `--codegen-model <name>` | 默认 codegen model |
-| `--show` | 打印当前配置 |
-| `--reset` | 清空配置文件 |
+| `--codegen-model <name>`    | 默认 codegen model    |
+| `--show`                    | 打印当前配置              |
+| `--reset`                   | 清空配置文件              |
 
----
+***
 
 ### `ai-spec workspace`
 
@@ -549,7 +572,7 @@ ai-spec workspace init
 ai-spec workspace status
 ```
 
-**`workspace init` 输出示例：**
+**`workspace init`** **输出示例：**
 
 ```
 ✔ Detected 2 repos:
@@ -572,12 +595,12 @@ ai-spec workspace status
 
 初始化完成后，在同一目录运行 `ai-spec create` 会自动进入**多 Repo 联动模式**（参见[多 Repo 工作区模式](#多-repo-工作区模式)）。
 
-| 选项 | 说明 |
-|---|---|
-| `--name <name>` | 工作区名称（默认取父目录名） |
+| 选项              | 说明                                                                                                       |
+| --------------- | -------------------------------------------------------------------------------------------------------- |
+| `--name <name>` | 工作区名称（默认取父目录名）                                                                                           |
 | `--repos <a,b>` | 只纳入指定目录（逗号分隔），不指定则自动扫描所有含 `package.json` / `go.mod` / `Cargo.toml` / `pom.xml` / `requirements.txt` 的子目录 |
 
----
+***
 
 ### `ai-spec update [change]`
 
@@ -613,20 +636,21 @@ ai-spec update "修复描述文字" --skip-affected
       → --codegen 时自动重新生成这些文件
 ```
 
-| 选项 | 说明 |
-|---|---|
-| `--codegen` | 识别受影响文件后自动重新生成 |
-| `--spec <path>` | 指定要更新的 Spec 文件（默认自动找最新） |
-| `--skip-affected` | 跳过受影响文件识别 |
-| `--provider <name>` | Spec 更新使用的 provider |
-| `--codegen-provider <name>` | 代码生成使用的 provider |
+| 选项                          | 说明                      |
+| --------------------------- | ----------------------- |
+| `--codegen`                 | 识别受影响文件后自动重新生成          |
+| `--spec <path>`             | 指定要更新的 Spec 文件（默认自动找最新） |
+| `--skip-affected`           | 跳过受影响文件识别               |
+| `--provider <name>`         | Spec 更新使用的 provider     |
+| `--codegen-provider <name>` | 代码生成使用的 provider        |
 
-> **`--codegen` 附带行为（v0.29.0+）**：
+> **`--codegen`** **附带行为（v0.29.0+）**：
+>
 > - 每次 update 自动生成独立 Run ID，运行摘要（耗时、写入文件数）在结束时打印
 > - 写每个受影响文件前先快照原始内容（`.ai-spec-backup/<runId>/`），可用 `ai-spec restore <runId>` 精确回滚
 > - 完成后自动对更新后的 Spec 运行代码审查，结论写入宪法 §9（与 `create` 的知识积累机制一致）
 
----
+***
 
 ### `ai-spec export`
 
@@ -666,14 +690,14 @@ openapi-generator generate -i openapi.yaml -g go -o sdk/go/
 npx @stoplight/prism-cli mock openapi.yaml
 ```
 
-| 选项 | 说明 |
-|---|---|
-| `--format yaml\|json` | 输出格式（默认 yaml） |
-| `--server <url>` | OpenAPI servers[0].url（默认 http://localhost:3000） |
-| `--output <path>` | 输出文件路径（默认 openapi.yaml） |
-| `--dsl <path>` | 指定 DSL 文件（默认自动寻找最新） |
+| 选项                    | 说明                                                  |
+| --------------------- | --------------------------------------------------- |
+| `--format yaml\|json` | 输出格式（默认 yaml）                                       |
+| `--server <url>`      | OpenAPI servers\[0].url（默认 <http://localhost:3000）> |
+| `--output <path>`     | 输出文件路径（默认 openapi.yaml）                             |
+| `--dsl <path>`        | 指定 DSL 文件（默认自动寻找最新）                                 |
 
----
+***
 
 ### `ai-spec mock`
 
@@ -703,9 +727,10 @@ ai-spec mock --serve --frontend ../my-frontend
 ai-spec mock --restore --frontend ../my-frontend
 ```
 
-**`--serve` 详解：**
+**`--serve`** **详解：**
 
 `--serve` 做以下三件事：
+
 1. 在后台启动 `node mock/server.js`（PID 记录在 `.ai-spec-mock.lock.json`）
 2. 根据前端框架自动 patch Proxy 配置：
    - **Vite**：生成 `vite.config.ai-spec-mock.ts`（mergeConfig 方式，非破坏性），在 `package.json` 添加 `dev:mock` 脚本
@@ -717,17 +742,17 @@ ai-spec mock --restore --frontend ../my-frontend
 
 **生成的文件：**
 
-| 文件 | 说明 |
-|---|---|
-| `mock/server.js` | 独立 Express Mock 服务器，每个 DSL 端点对应一个路由，返回 fixture 数据 |
-| `mock/README.md` | 启动指南和端点表 |
-| `mock/proxy.vite.comment.txt` | Vite proxy 配置片段（检测到 vite.config.* 时生成） |
-| `mock/proxy.next.comment.txt` | Next.js rewrites 配置片段（检测到 next.config.* 时生成） |
-| `mock/proxy.webpack.comment.txt` | webpack devServer.proxy 配置片段（默认 fallback） |
-| `src/mocks/handlers.ts` | MSW 请求拦截 handlers（`--msw`） |
-| `src/mocks/browser.ts` | MSW browser worker 初始化（`--msw`） |
-| `vite.config.ai-spec-mock.ts` | 前端临时 Vite 配置（`--serve`，非破坏性，`--restore` 后删除） |
-| `.ai-spec-mock.lock.json` | Proxy patch 记录 + Mock 服务器 PID（`--restore` 后删除） |
+| 文件                               | 说明                                                |
+| -------------------------------- | ------------------------------------------------- |
+| `mock/server.js`                 | 独立 Express Mock 服务器，每个 DSL 端点对应一个路由，返回 fixture 数据 |
+| `mock/README.md`                 | 启动指南和端点表                                          |
+| `mock/proxy.vite.comment.txt`    | Vite proxy 配置片段（检测到 vite.config.\* 时生成）           |
+| `mock/proxy.next.comment.txt`    | Next.js rewrites 配置片段（检测到 next.config.\* 时生成）     |
+| `mock/proxy.webpack.comment.txt` | webpack devServer.proxy 配置片段（默认 fallback）         |
+| `src/mocks/handlers.ts`          | MSW 请求拦截 handlers（`--msw`）                        |
+| `src/mocks/browser.ts`           | MSW browser worker 初始化（`--msw`）                   |
+| `vite.config.ai-spec-mock.ts`    | 前端临时 Vite 配置（`--serve`，非破坏性，`--restore` 后删除）      |
+| `.ai-spec-mock.lock.json`        | Proxy patch 记录 + Mock 服务器 PID（`--restore` 后删除）    |
 
 **Mock Server 特性：**
 
@@ -775,7 +800,7 @@ ai-spec create "用户登录功能" --serve
 # 完成后自动：生成 Mock → 启动服务器 → patch 前端 Proxy → 打印 dev 命令
 ```
 
----
+***
 
 ## 工作流详解
 
@@ -800,13 +825,13 @@ ai-spec create "用户登录功能" --serve
 
 ContextLoader 会自动扫描以下类别的"单例配置文件"，并将其路径和内容片段注入所有 Spec/Codegen prompt：
 
-| 类别 | 扫描路径 |
-|---|---|
-| i18n | `src/locales/**`, `src/i18n/**`, `locales/**`, `public/locales/**` |
-| constants | `src/constants/**`, `src/**/constants.{ts,js}` |
-| enums | `src/enums/**`, `src/**/enums.{ts,js}` |
-| config | `src/config/**` |
-| route-index | `src/routes/**/index.{ts,js}`, `src/router/index.{ts,js}` |
+| 类别          | 扫描路径                                                               |
+| ----------- | ------------------------------------------------------------------ |
+| i18n        | `src/locales/**`, `src/i18n/**`, `locales/**`, `public/locales/**` |
+| constants   | `src/constants/**`, `src/**/constants.{ts,js}`                     |
+| enums       | `src/enums/**`, `src/**/enums.{ts,js}`                             |
+| config      | `src/config/**`                                                    |
+| route-index | `src/routes/**/index.{ts,js}`, `src/router/index.{ts,js}`          |
 
 这些文件会被标记为 **Append-Only**，AI 在规划阶段会收到明确指令：
 
@@ -814,7 +839,7 @@ ContextLoader 会自动扫描以下类别的"单例配置文件"，并将其路
 
 **项目宪法 §8** 也会自动记录这些文件路径，确保 `ai-spec init --force` 重跑后约束持久化。
 
----
+***
 
 ### Step 2 — Spec 生成 + Tasks 分解
 
@@ -860,7 +885,7 @@ Spec 保存后自动生成 `specs/feature-xxx-tasks.json`，包含按实施层
 
 代码生成时（`api` 模式）如果检测到 Tasks 文件，自动切换为 **task-by-task 模式**，逐任务生成代码，精度更高。
 
----
+***
 
 ### Step 3 — 交互式 Spec 润色
 
@@ -887,7 +912,7 @@ Spec 保存后自动生成 `specs/feature-xxx-tasks.json`，包含按实施层
   ────────────────────────────────────────────
 ```
 
----
+***
 
 ### Step 3.4 — Spec 质量预评估
 
@@ -895,11 +920,11 @@ Approval Gate 之前，系统对 Spec 进行一次 AI 质量检查，给出**建
 
 **三个评分维度（0-10）：**
 
-| 维度 | 衡量内容 |
-|---|---|
-| **Coverage（覆盖度）** | 错误处理、边界条件、auth 规则是否都有描述？ |
-| **Clarity（清晰度）** | API 契约是否清晰到可以可靠提取 DSL？response 结构是否明确？ |
-| **Constitution（一致性）** | 是否与项目宪法保持一致？命名、错误码、约定有没有冲突？ |
+| 维度                    | 衡量内容                                   |
+| --------------------- | -------------------------------------- |
+| **Coverage（覆盖度）**     | 错误处理、边界条件、auth 规则是否都有描述？               |
+| **Clarity（清晰度）**      | API 契约是否清晰到可以可靠提取 DSL？response 结构是否明确？ |
+| **Constitution（一致性）** | 是否与项目宪法保持一致？命名、错误码、约定有没有冲突？            |
 
 ```
 [3.4/6] Spec quality assessment...
@@ -925,7 +950,7 @@ Approval Gate 之前，系统对 Spec 进行一次 AI 质量检查，给出**建
 - **DSL 可提取性预警**：Clarity < 6 且无结构化 API 章节时，提示 DSL 提取可能不准确
 - `--skip-assessment` 跳过此步骤（节省一次 AI 调用）；`--auto` 模式下自动跳过
 
----
+***
 
 ### Step 3.5 — Approval Gate（人工确认）
 
@@ -955,7 +980,7 @@ Approval Gate 之前，系统对 Spec 进行一次 AI 质量检查，给出**建
 
 > `--auto` 模式自动选 Proceed，跳过此步骤。
 
----
+***
 
 ### Step DSL — DSL 提取与校验
 
@@ -1012,12 +1037,12 @@ Approval Gate 通过后，系统自动将 Spec Markdown 转换为 **结构化 JS
 
 系统根据项目的 `package.json` 依赖自动检测是否为前端项目（`react` / `vue` / `next` / `react-native` / `expo`），并切换到对应的 DSL 提取策略：
 
-| 项目类型 | DSL 输出重心 |
-|---|---|
-| 后端（Node/Express/Prisma）| `endpoints[]` + `models[]` + `behaviors[]` |
-| 前端（React/Vue/Next）| `endpoints[]`（本前端调用的接口）+ `components[]`（ComponentSpec） |
+| 项目类型                    | DSL 输出重心                                               |
+| ----------------------- | ------------------------------------------------------ |
+| 后端（Node/Express/Prisma） | `endpoints[]` + `models[]` + `behaviors[]`             |
+| 前端（React/Vue/Next）      | `endpoints[]`（本前端调用的接口）+ `components[]`（ComponentSpec） |
 
-**`ComponentSpec` 结构（前端专属）：**
+**`ComponentSpec`** **结构（前端专属）：**
 
 ```json
 {
@@ -1041,9 +1066,34 @@ Approval Gate 通过后，系统自动将 Spec Markdown 转换为 **结构化 JS
 
 **用于 codegen：** DSL（含 `components[]`）被转换为紧凑文本摘要注入 codegen prompt，提供精确的组件接口定义和端点签名。
 
+**用于下游产物：**
+
+- `ai-spec types`：DSL → TypeScript 类型文件（models、endpoint request types、`API_ENDPOINTS` 常量）
+- `ai-spec export`：DSL → OpenAPI
+- `ai-spec mock`：DSL → Mock Server / MSW / Proxy
+- 工作区模式：后端 DSL 契约可直接注入前端流水线
+
+### Step DSL+ — DSL Gap Feedback
+
+DSL 校验通过后，系统还会做一次**纯启发式的丰富度检查**，判断当前 DSL 是否“合法但过于稀疏”。
+
+当前会检测几类典型缺口：
+
+- 没有 models 也没有 endpoints
+- endpoint 描述过于泛化
+- 多个 endpoint 全部没有 `errors`
+- model 只有极少字段
+
+交互模式下，如果检测到缺口，会给出两个选择：
+
+- `🔧 Refine spec`：AI 定向补全 Spec 中缺失的结构细节，然后自动重新提取 DSL
+- `⏭ Skip`：保留当前 DSL，继续后续流水线
+
+> 这个反馈环只在 DSL 提取完成后、进入 worktree 之前运行；`--auto`、`--fast`、`--skip-dsl` 下会跳过。
+
 > `--skip-dsl` 跳过此步骤，`--auto` 模式下提取失败时自动跳过（不中断流水线）。
 
----
+***
 
 ### Step 4 — Git Worktree（隔离工作区）
 
@@ -1056,7 +1106,7 @@ worktree: ~/code/my-app-add-user-login/   ← 独立分支 feature/add-user-logi
 - 不是 git 仓库时跳过，在原目录继续
 - `--skip-worktree` 强制跳过
 
----
+***
 
 ### Step 5 — 代码生成（增量 · 断点续传）
 
@@ -1070,10 +1120,10 @@ specs/
 └── feature-user-login-v2-tasks.json
 ```
 
-**`claude-code` 模式（默认）**
+**`claude-code`** **模式（默认）**
 
 - **交互模式**（默认）：在 worktree 目录启动 Claude Code CLI，有 Tasks 文件时将任务列表注入 `.claude-prompt.txt`
-- **`--auto` 增量模式**：改为对每个 task 单独运行 `claude -p`，每个 task 完成后写入 checkpoint，进度实时显示：
+- **`--auto`** **增量模式**：改为对每个 task 单独运行 `claude -p`，每个 task 完成后写入 checkpoint，进度实时显示：
 
 ```
   [████░░░░░░░░░░░░░░░░]  20% → TASK-001 💾 Add UserFavorite Prisma model
@@ -1084,7 +1134,7 @@ specs/
 
 检测到 `rtk` 已安装时自动切换为 `rtk claude` 执行。
 
-**`api` 模式**
+**`api`** **模式**
 
 有 Tasks 文件时按 task 顺序生成，每个 task 单独 AI 调用：
 
@@ -1112,17 +1162,17 @@ ai-spec create "用户收藏功能" --auto
 ai-spec create "用户收藏功能" --auto --resume
 ```
 
-**`plan` 模式**
+**`plan`** **模式**
 
 仅输出实施方案，不写入任何文件。
 
----
+***
 
 ### Step 7 — 测试生成
 
 测试生成有两种模式：**普通骨架模式**（默认）和 **TDD 模式**（`--tdd`）。
 
----
+***
 
 #### 普通骨架模式（默认）
 
@@ -1146,7 +1196,7 @@ ai-spec create "用户收藏功能" --auto --resume
 > 测试骨架只生成 `describe/it` 结构，不实现断言（用 TODO 注释标出），供开发者补全。
 > `--skip-tests` 跳过此步骤；`--skip-dsl` 时自动跳过。
 
----
+***
 
 #### TDD 模式（`--tdd`）
 
@@ -1195,11 +1245,12 @@ ai-spec create "任务管理功能" --tdd --codegen api
 ```
 
 **注意事项：**
+
 - 仅支持**后端项目**（使用 supertest 做 HTTP 集成测试）
 - 依赖 DSL 提取成功（Spec 需要有清晰的 API 设计章节）；DSL 为空时退化为普通骨架模式
 - error feedback loop 在 TDD 模式下最多运行 **3 轮**（普通模式 2 轮）
 
----
+***
 
 ### Step 8 — 错误反馈自动修复
 
@@ -1230,15 +1281,15 @@ Attempting auto-fix (3 error(s))...
 
 > `--skip-error-feedback` 跳过此步骤。
 
----
+***
 
 ### Step 9 — 代码审查 + 经验积累
 
 与 Spec 一起发送给 AI，输出结构化审查报告：
 
-| 代码生成模式 | 审查方式 |
-|---|---|
-| `api` | 直接读取生成的文件内容（不依赖 git diff，生成后立即可审查） |
+| 代码生成模式        | 审查方式                                    |
+| ------------- | --------------------------------------- |
+| `api`         | 直接读取生成的文件内容（不依赖 git diff，生成后立即可审查）      |
 | `claude-code` | 抓取 worktree 中的 git diff（需先 `git add .`） |
 
 审查完成后，系统自动从审查报告的 **⚠️ 问题** 章节提取可操作 issue，追加到项目宪法的 **§9 积累教训** 中：
@@ -1257,17 +1308,35 @@ Attempting auto-fix (3 error(s))...
 
 > 审查每运行一次，宪法就"学到"一些新东西，随项目迭代持续进化。
 
----
+### Step 9.5 — Review→DSL Loop
+
+从 v0.33.0 开始，审查阶段不再只是“找问题并记到 §9”。如果 review 里发现的是**结构性问题**，例如：
+
+- Spec 缺失错误码 / 鉴权要求
+- DSL 中 endpoint / model 信息过于稀疏
+- 当前实现问题本质上来自契约不完整
+
+系统会把这些发现整理成对 Spec / DSL 的改进建议，而不是直接把问题留给下一次人工返工。
+
+推荐动作是：
+
+```bash
+ai-spec update "补充缺失的结构约束" --codegen
+```
+
+也就是说，流水线从“单向生成”升级成了“review 之后还能反向修契约，再定向重生代码”的闭环。
+
+***
 
 ### Step 10 — Harness Self-Eval
 
 代码审查完成后自动执行，**零 AI 调用**，纯确定性评分：
 
-| 维度 | 评分逻辑 |
-|------|---------|
-| DSL Coverage (0-10) | 生成文件是否覆盖 DSL 声明的 endpoint 层和 model 层 |
+| 维度                   | 评分逻辑                                 |
+| -------------------- | ------------------------------------ |
+| DSL Coverage (0-10)  | 生成文件是否覆盖 DSL 声明的 endpoint 层和 model 层 |
 | Compile Score (0-10) | error feedback 全通过 → 10；未通过 / 跳过 → 5 |
-| Review Score (0-10) | 从 3-pass review 文本提取 `Score: X/10` |
+| Review Score (0-10)  | 从 3-pass review 文本提取 `Score: X/10`   |
 
 **Harness Score** = 加权平均（DSL 40% + Compile 30% + Review 30%）
 
@@ -1281,9 +1350,9 @@ Attempting auto-fix (3 error(s))...
 
 - `harnessScore` 和 `promptHash` 写入 RunLog（`.ai-spec-logs/<runId>.json`）
 - 每次改动 prompt 文件后，`promptHash` 自动变化，结合 `harnessScore` 可量化 prompt 改动的效果
-- 后续可通过脚本聚合多个 RunLog，绘制 harnessScore × promptHash 的趋势图
+- `ai-spec logs` / `trend` / `dashboard` 会直接消费这些 RunLog，做运行回看、趋势对比和可视化报告
 
----
+***
 
 ## 多 Repo 工作区模式
 
@@ -1351,69 +1420,69 @@ ai-spec create "实现用户点赞功能"
 
 ### 核心设计
 
-| 能力 | 说明 |
-|---|---|
-| **需求自动拆分** | AI 将一句需求分解为每个 repo 的职责描述 |
-| **UX 决策注入** | 前端自动获得：节流/防抖时间、是否乐观更新、失败回滚策略、成功后需 re-fetch 的接口列表 |
-| **基于真实代码的 UX 决策** | 分解时注入前端已有的 hook/store/API wrapper 文件列表，AI 的 specIdea 会直接引用真实文件名而非泛泛描述 |
-| **Contract Bridge** | 后端 DSL → TypeScript 接口定义 → 注入前端 Spec 生成 prompt，确保路径/方法/类型严格对齐 |
-| **前端 Codegen 上下文** | API 模式代码生成时自动注入前端项目的 hook/store/API wrapper 现有代码，附注"extend, do NOT recreate" |
-| **依赖顺序执行** | 按 backend → shared → frontend → mobile 顺序运行，后端先出产 contract |
-| **容错隔离** | 单个 repo 失败不影响其他 repo；失败时打印错误并继续 |
-| **优雅降级** | 未找到 `.ai-spec-workspace.json` 时静默退回单 repo 模式，无需任何配置 |
+| 能力                  | 说明                                                                           |
+| ------------------- | ---------------------------------------------------------------------------- |
+| **需求自动拆分**          | AI 将一句需求分解为每个 repo 的职责描述                                                     |
+| **UX 决策注入**         | 前端自动获得：节流/防抖时间、是否乐观更新、失败回滚策略、成功后需 re-fetch 的接口列表                             |
+| **基于真实代码的 UX 决策**   | 分解时注入前端已有的 hook/store/API wrapper 文件列表，AI 的 specIdea 会直接引用真实文件名而非泛泛描述        |
+| **Contract Bridge** | 后端 DSL → TypeScript 接口定义 → 注入前端 Spec 生成 prompt，确保路径/方法/类型严格对齐                |
+| **前端 Codegen 上下文**  | API 模式代码生成时自动注入前端项目的 hook/store/API wrapper 现有代码，附注"extend, do NOT recreate" |
+| **依赖顺序执行**          | 按 backend → shared → frontend → mobile 顺序运行，后端先出产 contract                   |
+| **容错隔离**            | 单个 repo 失败不影响其他 repo；失败时打印错误并继续                                              |
+| **优雅降级**            | 未找到 `.ai-spec-workspace.json` 时静默退回单 repo 模式，无需任何配置                          |
 
 ### UxDecision 字段说明
 
 需求拆分时 AI 会为前端/移动端 repo 生成 `uxDecisions`：
 
-| 字段 | 类型 | 说明 |
-|---|---|---|
-| `throttleMs` | `number?` | 按钮点击节流（ms），适用于频繁操作如点赞 |
-| `debounceMs` | `number?` | 输入防抖（ms），适用于搜索框 |
-| `optimisticUpdate` | `boolean` | 是否在服务端确认前先更新 UI |
-| `reloadOnSuccess` | `string[]?` | 成功后需 re-fetch 的接口路径列表 |
-| `errorRollback` | `boolean` | 乐观更新失败时是否回滚 UI 状态 |
-| `loadingState` | `boolean` | 请求期间是否显示加载指示器 |
-| `notes` | `string?` | 补充协调说明 |
+| 字段                 | 类型          | 说明                    |
+| ------------------ | ----------- | --------------------- |
+| `throttleMs`       | `number?`   | 按钮点击节流（ms），适用于频繁操作如点赞 |
+| `debounceMs`       | `number?`   | 输入防抖（ms），适用于搜索框       |
+| `optimisticUpdate` | `boolean`   | 是否在服务端确认前先更新 UI       |
+| `reloadOnSuccess`  | `string[]?` | 成功后需 re-fetch 的接口路径列表 |
+| `errorRollback`    | `boolean`   | 乐观更新失败时是否回滚 UI 状态     |
+| `loadingState`     | `boolean`   | 请求期间是否显示加载指示器         |
+| `notes`            | `string?`   | 补充协调说明                |
 
----
+***
 
 ## 多语言后端支持
 
 ai-spec 不绑定特定后端语言。`workspace init` 和 `detectRepoType()` 会自动识别以下项目类型：
 
-| 语言 / 框架 | 识别依据 | RepoType | Role |
-|---|---|---|---|
-| Node.js / Express | `package.json` 含 `express` | `node-express` | backend |
-| Node.js / Koa | `package.json` 含 `koa` | `node-koa` | backend |
-| Go | 根目录存在 `go.mod` | `go` | backend |
-| Rust | 根目录存在 `Cargo.toml` | `rust` | backend |
-| Java (Maven) | 根目录存在 `pom.xml` | `java` | backend |
-| Java (Gradle) | 根目录存在 `build.gradle` / `build.gradle.kts` | `java` | backend |
+| 语言 / 框架           | 识别依据                                      | RepoType       | Role    |
+| ----------------- | ----------------------------------------- | -------------- | ------- |
+| Node.js / Express | `package.json` 含 `express`                | `node-express` | backend |
+| Node.js / Koa     | `package.json` 含 `koa`                    | `node-koa`     | backend |
+| Go                | 根目录存在 `go.mod`                            | `go`           | backend |
+| Rust              | 根目录存在 `Cargo.toml`                        | `rust`         | backend |
+| Java (Maven)      | 根目录存在 `pom.xml`                           | `java`         | backend |
+| Java (Gradle)     | 根目录存在 `build.gradle` / `build.gradle.kts` | `java`         | backend |
 
 > **Java 上下文提取**：`ContextLoader` 会解析 `pom.xml`（正则提取 `<artifactId>` 依赖列表 + `<maven.compiler.source>` Java 版本）并推断技术栈（Spring Boot、MyBatis、Dubbo、RocketMQ、Redis、OpenFeign 等）；扫描 `**/src/main/java/**/*Controller.java` 作为 API 结构；读取 `application.properties/yml` 作为路由摘要。workspace `[W1]` 阶段会正常显示 `Java, Java 11, Spring Boot, RocketMQ... (N deps)` 而非 `unknown (0 deps)`。
-| Python | 根目录存在 `requirements.txt` / `pyproject.toml` / `setup.py` | `python` | backend |
-| **PHP / Lumen / Laravel** | **根目录存在 `composer.json`** | **`php`** | **backend** |
-| React | `package.json` 含 `react` | `react` | frontend |
-| Next.js | `package.json` 含 `next` | `next` | frontend |
-| Vue | `package.json` 含 `vue` | `vue` | frontend |
-| React Native / Expo | `package.json` 含 `react-native` / `expo` | `react-native` | mobile |
+> \| Python | 根目录存在 `requirements.txt` / `pyproject.toml` / `setup.py` | `python` | backend |
+> \| **PHP / Lumen / Laravel** | **根目录存在** **`composer.json`** | **`php`** | **backend** |
+> \| React | `package.json` 含 `react` | `react` | frontend |
+> \| Next.js | `package.json` 含 `next` | `next` | frontend |
+> \| Vue | `package.json` 含 `vue` | `vue` | frontend |
+> \| React Native / Expo | `package.json` 含 `react-native` / `expo` | `react-native` | mobile |
 
 **错误反馈自动修复** (`error-feedback.ts`) 也针对各语言自动选择测试/Lint 命令：
 
-| 语言 | 测试命令 | Lint 命令 |
-|---|---|---|
-| Node.js | `npm test` / `npx vitest run` | `npm run lint` / `npx eslint .` |
-| Go | `go test ./...` | `go vet ./...` |
-| Rust | `cargo test` | `cargo clippy -- -D warnings` |
-| Java (Maven) | `mvn test -q` | — |
-| Java (Gradle) | `./gradlew test` | — |
-| Python | `pytest` | `ruff check .` / `flake8 .` |
-| **PHP** | **`./vendor/bin/phpunit`** 或 **`php artisan test`** | **`./vendor/bin/phpstan analyse`**（如已安装） |
+| 语言            | 测试命令                                                | Lint 命令                                  |
+| ------------- | --------------------------------------------------- | ---------------------------------------- |
+| Node.js       | `npm test` / `npx vitest run`                       | `npm run lint` / `npx eslint .`          |
+| Go            | `go test ./...`                                     | `go vet ./...`                           |
+| Rust          | `cargo test`                                        | `cargo clippy -- -D warnings`            |
+| Java (Maven)  | `mvn test -q`                                       | —                                        |
+| Java (Gradle) | `./gradlew test`                                    | —                                        |
+| Python        | `pytest`                                            | `ruff check .` / `flake8 .`              |
+| **PHP**       | **`./vendor/bin/phpunit`** 或 **`php artisan test`** | **`./vendor/bin/phpstan analyse`**（如已安装） |
 
-> **代码生成 Prompt 策略**：`ai-spec create` 和 `ai-spec update --codegen` 会根据自动检测的 `RepoType` 选择对应语言的 system prompt（`getCodeGenSystemPrompt(repoType)`）。Go 使用 Go 惯用写法，Python 匹配 FastAPI/Flask/Django，Java 使用 Spring Boot 分层模式，Rust 使用 Result<T,E> 风格，**PHP 匹配 Lumen/Laravel 路由约定，使用 Eloquent ORM，PSR-12 规范**。
+> **代码生成 Prompt 策略**：`ai-spec create` 和 `ai-spec update --codegen` 会根据自动检测的 `RepoType` 选择对应语言的 system prompt（`getCodeGenSystemPrompt(repoType)`）。Go 使用 Go 惯用写法，Python 匹配 FastAPI/Flask/Django，Java 使用 Spring Boot 分层模式，Rust 使用 Result\<T,E> 风格，**PHP 匹配 Lumen/Laravel 路由约定，使用 Eloquent ORM，PSR-12 规范**。
 
----
+***
 
 ## 配置文件
 
@@ -1433,10 +1502,10 @@ ai-spec 不绑定特定后端语言。`workspace init` 和 `detectRepoType()`
 
 项目根目录还有两个自动生成的文件：
 
-| 文件 | 说明 |
-|---|---|
-| `.ai-spec-constitution.md` | 项目宪法，`init` 生成，所有命令自动读取 |
-| `.ai-spec.json` | 模型配置，`config` / `model` 命令管理 |
+| 文件                         | 说明                           |
+| -------------------------- | ---------------------------- |
+| `.ai-spec-constitution.md` | 项目宪法，`init` 生成，所有命令自动读取      |
+| `.ai-spec.json`            | 模型配置，`config` / `model` 命令管理 |
 
 ### 共享宪法（跨项目规范）
 
@@ -1488,11 +1557,11 @@ ai-spec init --global
   Project rules take priority over global rules.
 ```
 
----
+***
 
 ## RTK 集成
 
-> RTK 仅对 **`claude-code` 模式**有效，不影响 `api` 模式下对 GLM / Qwen / Gemini 等 provider 的直接 API 调用。
+> RTK 仅对 **`claude-code`** **模式**有效，不影响 `api` 模式下对 GLM / Qwen / Gemini 等 provider 的直接 API 调用。
 
 RTK（Rust Token Killer）作为 Claude Code 的 hook 运行，拦截 Claude Code 会话中的 shell 命令输出（`git diff`、`git status`、`npm` 等），压缩后再返回给 Claude，从而减少 context 中的 token 消耗。
 
@@ -1509,7 +1578,7 @@ RTK（Rust Token Killer）作为 Claude Code 的 hook 运行，拦截 Claude Cod
 ai-spec create "功能描述" --auto
 ```
 
----
+***
 
 ## 全局安装
 
@@ -1527,15 +1596,31 @@ ai-spec review                        # 代码审查
 ai-spec model --list                  # 查看所有模型
 ```
 
----
+***
 
 ## 项目结构
 
 ```
 ai-spec-dev-poc/
 ├── cli/
-│   ├── index.ts                    # CLI 入口，定义所有命令
-│   └── welcome.ts                  # 欢迎界面（无参数运行时展示）
+│   ├── index.ts                    # CLI 入口（42 行），组装所有命令
+│   ├── utils.ts                    # 共享工具：loadConfig / resolveApiKey / AiSpecConfig
+│   └── commands/
+│       ├── create.ts               # create — 完整单/多 Repo 流水线
+│       ├── review.ts               # review — AI 代码审查
+│       ├── init.ts                 # init — 项目/全局宪法生成
+│       ├── config.ts               # config — 项目默认配置
+│       ├── model.ts                # model — 交互式 Provider/Model 选择
+│       ├── workspace.ts            # workspace — 多 Repo 工作区管理
+│       ├── update.ts               # update — Spec 变更增量代码生成
+│       ├── export.ts               # export — DSL → OpenAPI 导出
+│       ├── mock.ts                 # mock — 独立 Mock Server 生成与启动
+│       ├── learn.ts                # learn — 直接向宪法 §9 追加经验
+│       ├── restore.ts              # restore — 回滚上次 run 写入的文件
+│       ├── trend.ts                # trend — Harness 评分趋势报表
+│       ├── logs.ts                 # logs — 运行日志列表 / 阶段详情
+│       ├── types.ts                # types — DSL → TypeScript 类型文件
+│       └── dashboard.ts            # dashboard — 静态 HTML Harness Dashboard
 ├── core/
 │   ├── spec-generator.ts           # 所有 AI Provider + SpecGenerator
 │   ├── context-loader.ts           # 项目上下文 + 宪法加载
@@ -1579,3 +1664,236 @@ ai-spec-dev-poc/
 ├── README.md
 └── RELEASE_LOG.md                  # 版本变更记录
 ```
+
+</details>
+
+<details>
+<summary>English</summary>
+
+# ai-spec
+
+GitHub: <https://github.com/hzhongzhong/ai-spec>
+
+> An AI-driven feature delivery orchestrator that turns a short requirement into runnable code, with support for both single-repo development and multi-repo cross-stack workflows.
+
+**Single-repo pipeline**
+
+```text
+Requirement → Project Constitution → Project Context → Spec + Tasks → Interactive Refinement (with diff preview) → Spec Quality Assessment → Approval Gate → DSL Extraction + Validation → DSL Gap Feedback → Git Isolation → Code Generation (parallel by dependency layer) → TDD / Test Skeleton → Error Feedback Auto-Fix → 3-pass Review → Review→DSL Loop → Harness Self-Eval → Lesson Accumulation (§9)
+```
+
+**Workspace pipeline**
+
+```text
+One requirement → AI decomposition + UX decisions → [Backend pipeline → DSL contract] → [Frontend pipeline with injected contract] → End-to-end delivery
+```
+
+---
+
+## Table of Contents
+
+- [Quick Start](#quick-start)
+- [Supported Models](#supported-models)
+- [Command Overview](#command-overview)
+- [Workflow](#workflow)
+- [Multi-Repo Workspace Mode](#multi-repo-workspace-mode)
+- [Multi-language Backend Support](#multi-language-backend-support)
+- [Configuration](#configuration)
+- [Global Installation](#global-installation)
+- [Project Structure](#project-structure)
+- [Release Log](RELEASE_LOG.md)
+
+---
+
+## Quick Start
+
+```bash
+# 1. Install dependencies and build
+npm install
+npm run build
+
+# 2. Set an API key (Gemini example)
+export GEMINI_API_KEY=your_key_here
+
+# 3. Optional first run: generate a project constitution
+ai-spec init
+
+# 4. Start developing from a natural-language requirement
+ai-spec create "add login support to the user module"
+```
+
+`ai-spec create` runs a structured pipeline: context loading, spec generation, interactive refinement, DSL extraction, optional DSL gap feedback, isolated git worktree setup, code generation, optional tests, error-feedback repair, review, contract feedback, and harness self-evaluation.
+
+## Supported Models
+
+- Supports 9 AI providers: Gemini, Claude, OpenAI, DeepSeek, Qwen, GLM, MiniMax, Doubao, and MiMo
+- Allows separate providers/models for spec generation and code generation
+- Exposes interactive model switching through `ai-spec model`
+- Adapts provider-specific request behavior internally
+
+## Command Overview
+
+Core commands:
+
+- `ai-spec init` — generate or regenerate the project constitution
+- `ai-spec create [idea]` — run the end-to-end generation pipeline
+- `ai-spec review [specFile]` — run an independent 3-pass code review
+- `ai-spec update [change]` — update the latest spec and regenerate impacted files
+- `ai-spec export` — export OpenAPI and SDK artifacts
+- `ai-spec mock` — generate mock servers, proxies, and MSW handlers
+- `ai-spec workspace` — initialize and inspect workspace orchestration
+- `ai-spec model` / `config` — manage provider and project defaults
+- `ai-spec trend` / `logs` / `dashboard` — inspect harness-quality history
+- `ai-spec types` — generate TypeScript types from DSL
+
+Important execution options:
+
+- Provider and model selection for spec/codegen
+- Codegen mode selection: `claude-code`, `api`, `plan`
+- Flow control flags such as `--auto`, `--fast`, `--skip-*`
+- Worktree control for isolated generation
+- Enhanced modes such as `--tdd`
+
+## Workflow
+
+### Step 1 — Constitution + Context
+
+- Loads `.ai-spec-constitution.md` if present
+- Auto-generates one when missing
+- Extracts project context such as dependencies, routes, schema, and structure
+
+### Step 2 — Spec + Tasks
+
+- Generates a structured feature spec in Markdown
+- Produces tasks that preserve dependency order
+- Keeps the spec as the high-level human-readable contract
+
+### Step 3 — Interactive Refinement
+
+- Lets the user inspect AI edits before code generation
+- Shows a diff preview
+- Supports a fast path for non-interactive execution
+
+### Step 3.4 — Spec Quality Assessment
+
+- Scores coverage, clarity, and constitution alignment before codegen
+- Highlights weak spots that may cause DSL or implementation drift
+
+### Step 3.5 — Approval Gate
+
+- Requires explicit approval before code generation unless auto mode is enabled
+- Keeps humans in the loop at the highest-leverage decision point
+
+### Step DSL — DSL Extraction and Validation
+
+- Converts the spec into a structured DSL
+- Validates endpoint, model, and behavior declarations
+- Provides a stable, machine-readable contract for downstream stages
+- Also powers downstream outputs such as TypeScript types, OpenAPI export, mock generation, and workspace contract injection
+
+### Step DSL+ — DSL Gap Feedback
+
+- Detects “valid but too sparse” DSL structures after extraction
+- Lets the user refine the spec before entering code generation
+- Prevents weak contracts from flowing into later stages unchanged
+
+### Step 4 — Git Worktree
+
+- Creates an isolated worktree for safer generation
+- Reduces the risk of polluting the main working directory
+
+### Step 5 — Code Generation
+
+- Generates code incrementally
+- Runs tasks in dependency-aware layers
+- Uses frontend and backend context to reduce hallucination
+
+### Step 7 — Test Generation
+
+- Can generate test skeletons or run in TDD mode
+- Reuses the project’s testing conventions when possible
+
+### Step 8 — Error Feedback Auto-Fix
+
+- Detects compile, lint, and test failures
+- Feeds real errors back into the repair loop
+- Includes dependency-order fixes and project-aware remediation
+
+### Step 9 — Review + Lesson Accumulation
+
+- Uses a 3-pass review strategy: architecture, implementation, and impact/complexity
+- Writes recurring issues back into Constitution §9 as accumulated lessons
+
+### Step 9.5 — Review→DSL Loop
+
+- Turns structural review findings into contract-level follow-up actions
+- Encourages updating Spec / DSL first, then regenerating with `ai-spec update --codegen`
+- Upgrades the pipeline from one-way generation to a corrective loop
+
+### Step 10 — Harness Self-Eval
+
+- Computes deterministic quality signals with zero extra AI calls
+- Records `harnessScore` and `promptHash`
+- Feeds `logs`, `trend`, and `dashboard` for historical observability
+
+## Multi-Repo Workspace Mode
+
+Workspace mode is designed for backend + frontend or multi-service repositories:
+
+- Detects or configures multiple repos under one workspace
+- Runs backend repos first when they provide contracts
+- Injects backend DSL contracts into downstream frontend spec generation
+- Adds UX decisions so cross-repo work remains consistent
+
+Typical use cases:
+
+- Backend API + Web frontend
+- Backend API + Mobile app
+- Shared contract packages + multiple product surfaces
+
+## Multi-language Backend Support
+
+The tool is not limited to one backend language. Current repo detection and context support cover:
+
+- Node.js / Express / Koa
+- Java (Maven / Gradle)
+- PHP / Lumen / Laravel
+- Go
+- Rust
+- Python
+
+Code generation prompts are selected according to detected repo type so each stack receives stack-appropriate conventions.
+
+## Configuration
+
+Supported configuration layers:
+
+- Project-level `.ai-spec.json`
+- Workspace-level `.ai-spec-workspace.json`
+- Project constitution `.ai-spec-constitution.md`
+- Shared global constitution for cross-project rules
+
+The global constitution mechanism lets teams define reusable API, naming, and architectural rules once, then merge them into project-specific constitutions.
+
+## Global Installation
+
+```bash
+npm install -g .
+ai-spec
+```
+
+Running without arguments shows the welcome screen, current provider/model, and recent specs.
+
+## Project Structure
+
+Main directories:
+
+- `cli/` — command entrypoints
+- `core/` — orchestration, generation, review, validation, logging, and harness modules
+- `prompts/` — provider-facing system prompts
+- `specs/` — generated specs, DSL files, and task files
+- `git/` — worktree management
+
+Key modules include constitution generation, DSL extraction, code generation, error feedback, self-evaluation, workspace loading, frontend context loading, logs/trend/dashboard reporting, and type generation.
+
+</details>