ai-spec-dev 0.31.0 → 0.35.0

package/RELEASE_LOG.md

@@ -1,5 +1,393 @@
 # Release Log
 
+<details open>
+<summary>中文</summary>
+
+---
+
+## [Unreleased] 2026-04-01 — P1 Task 验证步骤 + P2 设计方案对话
+
+### 新增 / 增强
+
+**Feature 1 — Task verificationSteps（`core/task-generator.ts`、`prompts/tasks.prompt.ts`、`core/combined-generator.ts`）**
+
+受 Superpowers writing-plans 启发，每个 Task 新增 `verificationSteps` 字段，要求具体可执行的验证命令 + 预期结果，防止"works correctly"式模糊验收标准。
+
+- `SpecTask` 新增 `verificationSteps: string[]`，语义为"the how to verify"（区别于 `acceptanceCriteria` 的"the what"）
+- `tasksSystemPrompt` 新增 verificationSteps 规则段：每条步骤必须是具体命令 + 可观察预期结果，给出 Good/Bad 示例，要求 2-5 条/task，backend 必须含 HTTP 检查，frontend 必须含 UI render + state 检查
+- `combined-generator.ts` 的内联 tasks instruction 同步更新，包含 `verificationSteps` 字段定义
+- `printTasks` 每个 task 输出前 2 条 verificationSteps（灰色），超过 2 条显示 "+ N more"
+
+**Feature 2 — Design Options Dialogue（`core/design-dialogue.ts`、`prompts/design.prompt.ts`、`cli/commands/create.ts`）**
+
+受 Superpowers brainstorming 启发，在 Spec 生成前新增 Step 1.5：AI 提出 2-3 个架构方案供用户选择，选定方案作为约束注入 spec prompt，防止 Spec 生成完后才发现方向不对。
+
+- `prompts/design.prompt.ts` — `designOptionsSystemPrompt`：每个方案含 Approach / Trade-offs（2-3条）/ Best when，保持简短（≤2分钟阅读），附 Recommended 建议
+- `core/design-dialogue.ts` — `DesignDialogue` 类：提案展示 → 用户选择（Option A/B/C / Blend / Skip）→ Blend 模式让 AI 融合多方案；解析 AI 输出的方案标签，提取选定方案全文（最多 400 字符）注入 spec
+- `create.ts` Step 1.5：在 context load 完成后、spec gen 前运行；`--fast` / `--auto` / `--vcr-replay` 自动跳过；`architectureDecision` 传入 `generateSpecWithTasks` 和 `SpecGenerator.generateSpec`
+- `combined-generator.ts` / `spec-generator.ts` 均新增 `architectureDecision?: string` 参数，以 `=== Architecture Decision ===` 段注入 prompt
+
+---
+
+## [Unreleased] 2026-04-01 — Pass 0 Spec Compliance Check + 项目索引 + 抗幻觉 Skills
+
+### 新增 / 增强
+
+**Feature 1 — Pass 0 Spec Compliance Check（`prompts/codegen.prompt.ts`、`core/reviewer.ts`、`core/self-evaluator.ts`）**
+
+受 Superpowers 工作流启发，在现有 3-pass review 前新增专用的 Spec 合规性检查 Pass 0。
+
+- `specComplianceSystemPrompt` — 穷举式审计：从 Spec 中提取所有需求（endpoints、models、business rules、auth、error cases、side effects），逐条标 ✅ / ⚠️ / ❌，输出 `ComplianceScore: X/10` + Blockers 列表
+- `Pass 1 架构 Review` 去除原有"是否覆盖所有需求"条款，Pass 0 已处理，Pass 1 聚焦层分离 / 契约设计 / 安全姿态
+- Pass 1 prompt 注入 Pass 0 合规报告作为上下文，避免重复发现
+- `extractComplianceScore` / `extractMissingCount` 公开导出，供下游消费
+- `create.ts` 在 `stageEnd("review")` 后即时打印合规分 + 缺失需求数
+- `SelfEvalResult` 新增 `complianceScore` 字段；harnessScore 权重更新：当 compliance + review 均可用时，compliance 0.30 · dsl 0.25 · compile 0.20 · review 0.25
+- `printSelfEval` 输出新增 `Compliance: X/10` 行，低于 6 显示红色 ⚠
+- Review History 记录新增 `complianceScore` 字段
+
+**Feature 2 — 项目索引 `ai-spec scan`（`core/project-index.ts`、`cli/commands/scan.ts`）**
+
+- `core/project-index.ts` — 扫描根目录下所有子项目（识别 `package.json` / `go.mod` / `Cargo.toml` / `pom.xml` 等 manifest），持久化到 `.ai-spec-index.json`
+- 增量逻辑：新项目 → 添加 `firstSeen`；已有项目 → 更新 `techStack / hasConstitution / lastSeen`；目录消失 → 标记 `missing:true`（不删除记录）
+- Git Worktree 过滤：`.git` 为文件（非目录）时跳过，防止 ai-spec 生成的 worktree 被误识别为项目
+- `ai-spec scan` — 扫描并输出变更摘要（added / updated / unchanged / missing）
+- `ai-spec scan --list` — 不重新扫描，直接展示当前 index
+- `ai-spec init --global` 联动：优先读取 index，对每个活跃项目提取 type / techStack / constitution §1-§6 前 2000 字符，作为全局宪法生成的多项目上下文；无 index 时 fallback 并提示先 `scan`
+
+**Feature 3 — 抗幻觉 Skill 文件（`.claude/commands/`）**
+
+从 ai-spec 现有抗幻觉设计中提炼 5 个可复用 Claude Code slash command skill，供团队共享：
+
+- `/scan-singletons` — 扫描项目所有单例 config 文件（i18n / constants / routes / store-index），输出"只能修改、绝不重建"清单
+- `/add-lesson` — 将 review 发现写入宪法 §9，含去重（前 60 字符比对）+ 分类（bug/security/pattern/perf/convention）+ 时间戳
+- `/installed-deps` — 列出 `package.json` 所有依赖作为 codegen 白名单，附检测常用替代品歧义提示
+- `/recall-lessons` — 读取 §9，按与当前任务的相关度（High/Medium/Low）筛选并展示历史教训
+- `/verify-imports` — 验证文件中所有 import 路径（alias 解析 + 相对路径 + 包名白名单），输出 broken imports 及修复建议
+
+---
+
+## [Unreleased] 2026-04-01 — VCR 录制回放 + 异步 §9 + Approval Gate 增强
+
+### 新增 / 增强
+
+**Feature 1 — VCR 录制 & 零成本回放（`core/vcr.ts`、`cli/commands/vcr.ts`、`cli/commands/create.ts`）**
+
+受 Claude Code VCR token 计数测试模式启发，将所有 AI 响应录制成 JSON 快照，供离线无 API 调用地回放。
+
+- `VcrRecordingProvider` — 透明包装任意 `AIProvider`，拦截每次 `generate()` 并记录 `(index, promptPreview, callHash, response, providerName, modelName, ts, durationMs)`；`save()` 支持合并 spec + codegen 两个 recorder 并按时间戳排序
+- `VcrReplayProvider` — 按序返回预录响应，入参 prompt 被忽略；录制耗尽时抛出明确错误
+- 快照存储在 `.ai-spec-vcr/{runId}.json`，与 RunLog 使用相同 `runId`，可交叉查询
+- `ai-spec vcr list` — 列出所有录制（runId、AI 调用数、provider/model、录制日期）
+- `ai-spec vcr show <runId>` — 逐条展示每次 AI 调用的 promptPreview + callHash + 耗时
+- CLI 选项：`--vcr-record`（当次运行录制）、`--vcr-replay <runId>`（零 API 调用回放）
+- 实现 fire-and-await 模式：spec 和 codegen 两个 provider 分别包装，运行结束后统一 merge 保存
+
+**Enhancement 1 — §9 知识积累改为异步 fire-and-await（`cli/commands/create.ts`）**
+
+原来 `await accumulateReviewKnowledge(...)` 阻塞在 Loop 2 结构性反馈之前，拉长了关键路径。
+
+- 将调用改为立即启动、在 `runLogger.finish()` 前 `await`（fire-and-await 模式）
+- Loop 2 交互式结构分析不再等待 §9 写入，用户体验更流畅
+- 错误通过 `.catch()` 打印 `⚠ §9 accumulation failed: ...`，不影响主流程
+
+**Enhancement 2 — Approval Gate DSL 范围预估（`cli/commands/create.ts`）**
+
+原来 Approval Gate 只显示行数和字数，用户难以判断代码生成规模。
+
+- 新增 `estimateFromSpec(spec)` 内联逻辑（正则，无 AI 调用）：从 spec 文本统计 HTTP 端点数（`GET/POST/PUT/PATCH/DELETE /`）和数据模型数（`## Model`、`**Xxx**:`）
+- Approval Gate 增加 `Est. DSL scope : ~N endpoint(s), ~M model(s) → ~K files` 预估行
+- 让用户在点击 Proceed 前对代码生成规模有量化感知
+
+---
+
+## [Unreleased] 2026-04-01 — Pipeline 可靠性强化（二）：JSONL 崩溃恢复 + 熔断 + Token Budget
+
+### 功能增强
+
+**Enhancement 1 — RunLog JSONL Append-Only Shadow（`core/run-logger.ts`、`core/run-trend.ts`）**
+
+原有 `RunLogger.flush()` 是异步 fire-and-forget 的全量 JSON 重写，进程崩溃时当次 RunLog 全丢。
+
+- 新增 `appendJsonlLine(filePath, record)` — 用 `fs.appendFileSync` 同步追加，保证每条记录落盘后才继续执行
+- `RunLogger` 构造时立即写 `header` 行到 `{runId}.jsonl`；每个 `push()`、`stageFail()`、`setPromptHash()`、`setHarnessScore()`、`fileWritten()`、`finish()` 均追加对应类型的 JSONL 行（`header` / `entry` / `error` / `file` / `meta` / `footer`）
+- 原有 `.json` 全量文件保留不变（消费者 `trend`、`dashboard`、`logs` 无需改动）
+- 新增 `reconstructRunLogFromJsonl(path)` — 从 JSONL 行逐条重建 `RunLog`，供崩溃恢复使用
+- `loadRunLogs()` 新增孤儿 `.jsonl` 恢复路径：扫描到没有对应 `.json` 的 `.jsonl` 文件时，自动重建并纳入返回结果
+
+**Enhancement 2 — ErrorFeedback 无进展熔断（`core/error-feedback.ts`）**
+
+原有修复循环没有"进展检测"，即使每次修复后错误数未减少，仍会消耗完所有 `maxCycles`。
+
+- 新增 `prevErrorCount` 跟踪上一轮的错误数量
+- 每次 fix 后重新检查：若 `allErrors.length >= prevErrorCount`（错误数未减少），立即中止并打印 `⚠ Auto-fix made no progress` 提示，不再浪费额外 AI 调用
+- 参考：Claude Code `MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3` 防止 compact 死循环的同类设计
+
+**Enhancement 3 — Command Output + File Content Token Budget（`core/error-feedback.ts`）**
+
+- 新增 `MAX_COMMAND_OUTPUT_CHARS = 50_000`（约 10K tokens）：`runCommand` 返回的 stderr/stdout 超过此限时截断，防止巨型构建输出撑满 AI context
+- 新增 `MAX_FIX_FILE_CHARS = 60_000`（约 12K tokens）：`attemptFix` 中发给 AI 的 `existingContent` 超过此限时截断并附加提示，AI 仍可通过错误行号定位问题
+- 参考：Claude Code `applyToolResultBudget(toolResult, maxTokens)` 工具输出预算设计
+
+---
+
+## [Unreleased] 2026-04-01 — Pipeline 可靠性强化：结构化 Review Findings + §9 知识闭环
+
+### 功能增强
+
+**Enhancement 1 — Loop 2 结构性发现：正则 → 结构化 JSON（`prompts/codegen.prompt.ts`、`core/dsl-feedback.ts`）**
+
+原有 `extractStructuralFindings` 用正则解析 AI 生成的 review 自然语言，格式漂移会导致静默漏报，且只覆盖硬编码的 4 种关键词。
+
+- `reviewArchitectureSystemPrompt` Pass 1 格式末尾新增 `## 🔍 结构性发现 JSON` 段，要求 AI 强制输出 `{"structuralFindings": [...]}` JSON block（即使无发现也输出空数组），category 枚举与原有一致：`auth_design` / `api_contract` / `model_design` / `layer_violation` / `other_design`
+- `extractStructuralFindings` 改为**优先解析 JSON block**：从 Pass 1 文本提取 ` ```json{...}``` `，parse `structuralFindings` 数组并做类型守卫过滤；解析失败或旧格式 review 才 fallback 到原有正则逻辑（向后兼容）
+- 结果：Loop 2 发现的问题不再受限于关键词列表，任何被 Pass 1 明确指出的设计问题都会进入反馈环
+
+**Enhancement 2 — §9 知识积累真正形成双向闭环（`prompts/spec.prompt.ts`、`core/reviewer.ts`）**
+
+原有实现的两个断层：
+1. constitution 虽然注入到 spec 生成 prompt，但 `specPrompt` 没有明确指令让 AI 去应用 §9 教训
+2. Reviewer 三 Pass 完全不读 constitution，无法检验新代码是否重蹈 §9 记录的问题
+
+修复：
+- `specPrompt` 末尾新增 CRITICAL 指令：如果 constitution 含 §9，spec 生成前必须逐条审阅教训；对直接相关的教训，在 §8 实施要点末尾追加「⚠ 基于历史教训：[简述规避方式]」
+- `reviewer.ts` 新增 `loadAccumulatedLessons(projectRoot)` — 读取 constitution 中 §9 段落（`## 9. 积累教训` 到下一 `## \d` 或 EOF）；注入到 Pass 1 arch review prompt（`=== §9 历史积累教训 ===`），让 reviewer 能交叉检验新代码是否复现已知问题，发现则写入 JSON findings 块触发 Loop 2
+
+**两个闭环现在都真正贯通：**
+```
+Review → §9 写入 constitution
+              ↓
+    下次 create spec 时 → spec 生成读取 §9 → 设计时规避
+              ↓
+    Review Pass 1 读取 §9 → 检验代码是否复现 → 若复现触发 Loop 2 修正 DSL
+```
+
+---
+
+## [Unreleased] 2026-03-31 — 文档同步：README / purpose / RELEASE_LOG
+
+### 文档更新
+
+- README 首页主流程同步到最新架构：
+  - 补入 **DSL Gap Feedback**
+  - 补入 **Review→DSL Loop**
+  - 明确 `logs` / `trend` / `dashboard` 消费 Harness Self-Eval 的 RunLog 数据
+  - 补充 DSL 的下游产物说明（`types` / `export` / `mock` / workspace 契约注入）
+- purpose 文档升级到 **v0.34.0** 口径：
+  - 版本记录速览补入 v0.32.0 / v0.33.0 / v0.34.0
+  - 新增“两条 Pipeline 反馈环”章节
+  - 新增“DSL 的多出口价值：类型、Dashboard 与可观测性”章节
+  - 完整功能矩阵扩展到 `types`、`logs`、`trend`、`dashboard`
+- purpose 的 Mermaid 流程图已切换为 **SVG 图片 + 折叠纯文本备用版**，方便在不支持 Mermaid 的文档平台中阅读
+- RELEASE_LOG 新增当前文档同步记录，保证产品叙事与代码实现保持一致
+
+---
+
+## [0.34.0] 2026-03-31 — Harness Dashboard + TypeScript 类型生成
+
+### 新增内容
+
+**Feature 1 — `ai-spec dashboard`（`core/dashboard-generator.ts`、`cli/commands/dashboard.ts`）**
+
+- 基于现有 `.ai-spec-logs/` RunLog 数据，一键生成静态 HTML Harness Dashboard
+- 包含：
+  - Overview 统计（总运行数 / 平均分 / 编译通过率）
+  - Score Trend 折线图（SVG，最近 30 次有评分运行）
+  - Prompt 版本对比表（avg / best / worst，当前版本高亮）
+  - 近 10 次运行历史（带评分条形）
+  - 阶段耗时柱状图（平均 ms，前 8 阶段）
+  - Top 5 错误频次统计
+- 零外部依赖（纯 inline CSS + SVG）
+- `--open` 选项：生成后自动打开浏览器
+
+```bash
+ai-spec dashboard              # 生成 .ai-spec/dashboard.html
+ai-spec dashboard --open       # 生成后自动在浏览器打开
+ai-spec dashboard --last 20    # 只分析最近 20 次运行
+ai-spec dashboard --output ./report.html
+```
+
+---
+
+**Feature 2 — `ai-spec types`（`core/types-generator.ts`、`cli/commands/types.ts`）**
+
+- DSL → TypeScript 类型文件，前端可直接 import，无需手写
+- 生成内容：
+  - 所有 `models` → `export interface ModelName { ... }`（含可选/必填、类型映射）
+  - 所有 `endpoints.request.body/query/params` → `export interface PostXxxRequest { ... }`
+  - `export const API_ENDPOINTS = { ... } as const`（含 method / path / auth）
+  - 前端 `components[].props` → `export interface ComponentNameProps { ... }`
+- 类型映射：`String→string`，`Int/Float→number`，`Boolean→boolean`，`DateTime→string`，`PascalCase→该 interface 引用`
+
+```bash
+ai-spec types                  # 生成 .ai-spec/<feature>.types.ts
+ai-spec types --stdout         # 打印到 stdout（适合管道）
+ai-spec types --output src/types/api.ts
+ai-spec types --no-endpoint-map   # 不生成 API_ENDPOINTS 常量
+```
+
+---
+
+## [0.33.0] 2026-03-30 — Pipeline 反馈环：DSL Gap Loop + Review→DSL Loop
+
+### 新增内容
+
+**Feature — 两条 Pipeline 反馈环（`core/dsl-feedback.ts`、`cli/index.ts`）**
+
+原有流水线是严格单向的——每一步的输出只能向前传递，review 发现的问题只能写入 §9，DSL 提取稀疏也只能硬着头皮继续。v0.33.0 在两个关键位置插入局部反馈环，让 pipeline 在保持可测量性的前提下具备弹性。
+
+---
+
+**Loop 1 — DSL Gap Feedback（DSL 提取完成 → Worktree 之前）**
+
+- 新增 `assessDslRichness(dsl)` — 纯启发式检查，零 AI 调用，检测四类常见 DSL 缺口：
+
+  | 缺口类型 | 检测逻辑 |
+  |----------|---------|
+  | `no_models_no_endpoints` | DSL 完全为空——spec 可能太抽象 |
+  | `generic_endpoint_desc`  | endpoint description < 15 字符或以模糊动词开头（handles/管理/处理…）|
+  | `missing_errors`         | ≥2 个 endpoint 且全部无 errors 定义 |
+  | `sparse_model`           | model 字段数 < 2 |
+
+- 发现缺口时，交互模式下展示具体缺口列表并提供选择：
+  - `🔧 Refine spec` — AI 执行定向 spec 补全（`buildDslGapRefinementPrompt`），不改变功能范围，只填充缺失细节 → 自动重新提取 DSL
+  - `⏭ Skip` — 继续用当前 DSL
+
+- `--auto` / `--fast` / `--skip-dsl` 模式下完全跳过此 Loop
+- 结果写入 RunLog `dsl_gap_feedback` 阶段（action: `refined` / `skipped` / `refinement_error`）
+
+---
+
+**Loop 2 — Review → DSL Structural Feedback（§9 知识积累 → Self-Eval 之前）**
+
+- 新增 `extractStructuralFindings(reviewText)` — 解析 Pass 1（架构审查）文本，识别设计层问题（而非实现层问题）：
+
+  | 类别 | 触发模式 |
+  |------|---------|
+  | `auth_design`      | 缺少认证 / missing auth / 鉴权缺 |
+  | `api_contract`     | 接口设计问题 / API design / 接口缺少 |
+  | `model_design`     | 模型缺少字段 / model missing field / schema incomplete |
+  | `layer_violation`  | 层级违反 / layer violation / 分层问题 |
+
+  Pass 1 得分 ≥ 8 时认为架构没问题，自动跳过分类
+
+- 发现结构性问题时展示区别于 §9 的"设计层警告"，并提供三种选择：
+  - `🔧 Amend spec + update DSL` — AI 根据结构性发现定向修订 spec → 重新提取 DSL → 覆盖保存 spec 文件和 DSL 文件 → 提示 `ai-spec update --codegen` 重新生成受影响文件
+  - `📝 Note in §9 only` — §9 已由 knowledge accumulation 写入，DSL 不变
+  - `⏭ Skip`
+
+- 关键设计决策：Loop 2 **不自动触发 codegen**。DSL 修正后提示用户主动运行 `update --codegen`，保持人在决策节点的控制权
+- `--auto` 模式下完全跳过此 Loop（不增加 CI 耗时）
+- 结果写入 RunLog `review_dsl_feedback` 阶段
+
+---
+
+**新流水线结构：**
+
+```
+Spec → DSL 提取
+         ↓
+    [Loop 1] DSL Gap 检测
+         ↓ (不满足 → 定向 spec 补全 → 重新提取 DSL)
+    Approval Gate → Worktree → Codegen → ErrorFix → Review
+                                                        ↓
+                                                   §9 知识积累
+                                                        ↓
+                                               [Loop 2] 结构性问题检测
+                                                        ↓ (发现 → spec 修订 → DSL 更新)
+                                                   Self-Eval → Done
+```
+
+---
+
+**内部重构（2026-03-31）— CLI 命令拆分**
+
+- `cli/index.ts` 从 2533 行拆分为 42 行入口 + 13 个独立命令文件（`cli/commands/*.ts`）+ 共享工具层（`cli/utils.ts`）
+- 无任何用户可见功能变化，编译输出与重构前等价
+
+---
+
+## [0.32.0] 2026-03-30 — Harness 数据闭环：`trend` / `logs` 命令 + DSL Coverage 细化评分
+
+### 新增内容
+
+**Feature #1 — `ai-spec trend` 跨运行趋势命令（`core/run-trend.ts`、`cli/index.ts`）**
+
+- 新增 `core/run-trend.ts` — 趋势分析模块：
+  - `loadRunLogs(workingDir)` — 扫描 `.ai-spec-logs/*.json`，按运行时间倒序排列，静默跳过损坏文件
+  - `buildTrendReport(logs, opts)` — 从 RunLog 数组生成趋势报告：按 `promptHash` 分组，统计 avg / best / worst；支持 `last` 和 `promptFilter` 选项
+  - `printTrendReport(report, workingDir)` — 彩色表格输出，分为「Prompt 版本摘要」和「运行历史」两区，当前 prompt 版本用 `◀ current` 标记
+- 新增 CLI 命令 `ai-spec trend`：
+  ```bash
+  ai-spec trend              # 最近 15 次有评分的运行，按 promptHash 分组
+  ai-spec trend --last 30    # 最近 30 次
+  ai-spec trend --prompt a3f # 只看 hash 以 a3f 开头的 prompt 版本
+  ai-spec trend --json       # 输出原始 JSON，适合脚本聚合分析
+  ```
+  输出示例：
+  ```
+  ─── Harness Trend ───────────────────────────────────────────────
+    Prompt Versions:
+    Hash        Runs   Avg  Best Worst  Last seen
+    ─────────────────────────────────────────────────────────
+    a3f2c1d8       3   7.6   8.2   6.9  2026-03-30 ◀ current
+    b1e4a2f0       5   6.8   7.4   5.5  2026-03-29
+
+    Run History:
+    2026-03-30  [████████░░] 7.8  a3f2c1d8  1m24s  feature-login-v1.md
+    2026-03-30  [████████░░] 8.2  a3f2c1d8  1m18s  feature-user-v1.md
+    ...
+  ```
+
+**Feature #2 — `ai-spec logs` 运行日志列表命令（`cli/index.ts`）**
+
+- 新增 CLI 命令 `ai-spec logs`：
+  ```bash
+  ai-spec logs               # 列出最近 10 次运行（runId、日期、score、文件数、耗时）
+  ai-spec logs --last 20     # 列出最近 20 次
+  ai-spec logs <runId>       # 展示该次运行的完整阶段耗时表格
+  ```
+  单次运行详情示例：
+  ```
+  ─── Run: 20260330-143022-a7f2 ─────────────────────────────────
+    Started : 2026-03-30T14:30:22.000Z
+    Provider: gemini / gemini-2.5-pro
+    Prompt  : a3f2c1d8
+    Score   : 7.8/10
+    Stages:
+      ✔  context_load            0.3s
+      ✔  spec_gen                18.4s
+      ✔  dsl_extract             6.1s
+      ✔  codegen                 51.2s
+      ✔  review                  14.8s
+      ✔  self_eval               0.0s
+  ```
+- 结尾提示 `ai-spec logs <runId>` 和 `ai-spec trend`，引导用户进入分析工作流
+
+### 功能增强
+
+**Enhancement — DSL Coverage Score 三层细化评分（`core/self-evaluator.ts`）**
+
+原有评分只做二元判断（endpoint 层有无、model 层有无），无法反映实际覆盖深度。新增两个 Tier：
+
+| Tier | 检查项 | 扣分规则 |
+|------|--------|--------|
+| Tier 1（原有）| endpoint 层存在 / model 层存在 | -4 / -3（同前）|
+| **Tier 2（新增）** | Model name 覆盖率：对每个 DSL 声明的 model，检查其名称（含 camelCase → snake_case 规范化）是否出现在任何生成文件路径中 | coverage < 50% → -2；50-79% → -1；≥80% → 0 |
+| **Tier 3（新增）** | Endpoint 文件充足性：≥5 个端点但 endpoint 层文件 < 2 个 | -1 |
+
+- 新增 `modelNameTokens(name)` — 将 PascalCase 模型名规范化为多种路径匹配 token（`OrderItem` → `orderitem` / `order-item` / `order_item`）
+- `SelfEvalResult.detail` 新增 `endpointLayerFiles`、`modelNameCoverage`、`modelNameMatched` 字段，写入 RunLog 供后续分析
+- `printSelfEval()` 当存在 DSL model 时新增 Detail 行：
+  ```
+  ─── 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
+  ─────────────────────────────────────────────────
+  ```
+
 ---
 
 ## [0.31.0] 2026-03-29 — Harness Engineer：Prompt Hash + Create 内联 Self-Eval
@@ -2130,3 +2518,75 @@ Spec + Tasks 通过单次 AI 调用完成（`core/combined-generator.ts`），
 - `ai-spec review`：独立代码审查命令
 - 支持 `claude-code` / `api` / `plan` 三种代码生成模式
 - 项目上下文自动扫描（package.json / Prisma schema / 路由文件）
+
+</details>
+
+<details>
+<summary>English</summary>
+
+# Release Log
+
+This section provides an English companion view for the detailed Chinese changelog above. It keeps the same chronological direction while summarizing each version at a higher level for bilingual reading.
+
+## Version Summary
+
+- **Unreleased** — Synced README, purpose, and RELEASE_LOG to reflect the latest pipeline, feedback loops, SVG diagrams, and observability narrative.
+- **0.34.0** — Added a static Harness Dashboard and DSL-to-TypeScript type generation.
+- **0.33.0** — Introduced two pipeline feedback loops: DSL Gap Loop and Review→DSL Loop.
+- **0.32.0** — Closed the harness data loop with `trend`, `logs`, and more detailed DSL coverage scoring.
+- **0.31.0** — Introduced the Harness Engineer layer with `promptHash` and inline self-evaluation during `create`.
+- **0.30.0** — Improved error-fix dependency ordering and multiline import awareness for frontend context extraction.
+- **0.29.0** — Performed a broad hardening pass across RunLogger instrumentation, update snapshots, score trend output, and dead-code cleanup.
+- **0.28.0** — Upgraded review from 2-pass to 3-pass by adding impact assessment and code complexity analysis.
+- **0.27.0** — Added industrial reliability foundations: provider robustness, snapshot restore, and structured RunLog / RunId support.
+- **0.26.0** — Fixed stability issues in multi-repo review, parallel batch tolerance, and corrupted tasks JSON recovery.
+- **0.25.0** — Repaired context extraction for HTTP imports, pagination examples, and false crash detection.
+- **0.24.0** — Fixed lesson counting, `export default`, `impliesRegistration`, and dependency topological sorting issues.
+- **0.23.0** — Eliminated a filename hallucination bug by correcting `index.vue` generation toward the actual component name.
+- **0.22.0** — Strengthened frontend three-layer separation by introducing a `view` layer and fixing API→Store naming hallucinations.
+- **0.21.0** — Fixed store behavior contract extraction, including `fetchTasks` vs `fetchTaskList` hallucination issues.
+- **0.20.0** — Added one-command mock integration with `--serve` and `--restore`.
+- **0.19.0** — Rewrote error parsing, completed behavior contract extraction, and fixed Auto Gate behavior.
+- **0.18.0** — Added `ai-spec learn`, behavior contract injection, and made Approval Gate a hard gate.
+- **0.17.0** — Injected the full constitution into generation, improved export caching, and added constitution length warnings.
+- **0.16.0** — Added spec quality pre-assessment, layered code review, and TDD mode.
+- **0.15.0** — Added parallel task execution for tasks within the same dependency layer.
+- **0.14.5** — Added extraction and injection of real frontend pagination patterns.
+- **0.14.4** — Improved frontend output reliability with route index auto-registration and cross-task function-name consistency.
+- **0.14.3** — Added the welcome screen.
+- **0.14.2** — Added Java / Maven / Gradle project context awareness.
+- **0.14.1** — Fixed a critical bug where non-Node repos incorrectly generated TypeScript-oriented output.
+- **0.14.0** — Unified frontend framework detection and injected frontend context explicitly in task mode.
+- **0.13.9** — Added component reuse awareness.
+- **0.13.8** — Fixed store HTTP hallucinations and HTTP client import hallucinations.
+- **0.13.6** — Fixed layout hallucinations and route registration reliability.
+- **0.13.5** — Fixed frontend codegen hallucinations and route convention issues.
+- **0.13.4** — Fixed MiMo `max_tokens` truncation.
+- **0.13.3** — Fixed DSL validation false positives.
+- **0.13.2** — Added API key persistence.
+- **0.13.1** — Auto-skipped worktree for frontend generation and fixed related bugs.
+- **0.13.0** — Strengthened context awareness and error-feedback behavior.
+- **0.12.2** — Added PHP / Lumen backend support.
+- **0.12.1** — Restored MiMo v2 Pro support.
+- **0.12.0** — Added constitution consolidation with `ai-spec init --consolidate`.
+- **0.11.0** — Delivered three high-priority additions: incremental update, OpenAPI export, and multi-language codegen prompts.
+- **0.10.0** — Added Mock Server support and expanded multi-language backend support.
+- **0.9.0** — Fixed frontend DSL extraction, decomposition context, and codegen injection precision.
+- **0.8.0** — Enhanced frontend support and added shared global constitutions across projects.
+- **0.7.0** — Introduced Phase 4 multi-repo workspace orchestration.
+- **0.6.0** — Introduced Phase 3 test generation, error feedback, and lesson accumulation.
+- **0.5.0** — Introduced Phase 2 DSL transformation, schema handling, and validation.
+- **0.4.0** — Introduced Phase 1 industrial pipeline infrastructure.
+- **0.3.0** — Added project constitution support, task decomposition, and RTK integration.
+- **0.2.0** — Added multi-provider support and interactive model switching.
+- **0.1.0** — Initial release with Spec generation, Git worktree isolation, code generation, review, and basic project context scanning.
+
+## Evolution Themes
+
+- **Pipeline structure** — The project evolved from prompt-driven generation into a staged, restartable engineering pipeline.
+- **Project grounding** — Context extraction, constitutions, DSL, and behavior contracts reduce repository-specific hallucinations.
+- **Quality loops** — Testing, error feedback, review passes, lesson accumulation, and harness scoring create feedback channels after generation.
+- **Workspace orchestration** — Multi-repo features extend the system from single-repo coding to contract-aware cross-stack delivery.
+- **Harness observability** — `promptHash`, `harnessScore`, `logs`, `trend`, and `dashboard` turn runs into measurable engineering data.
+
+</details>

package/cli/commands/config.ts

@@ -0,0 +1,93 @@
+import { Command } from "commander";
+import * as path from "path";
+import * as fs from "fs-extra";
+import chalk from "chalk";
+import { CodeGenMode } from "../../core/code-generator";
+import { clearAllKeys, clearKey, getSavedKey, KEY_STORE_FILE } from "../../core/key-store";
+import { AiSpecConfig, CONFIG_FILE, loadConfig } from "../utils";
+
+export function registerConfig(program: Command): void {
+  program
+    .command("config")
+    .description(`Set default configuration for this project (saved to ${CONFIG_FILE})`)
+    .option("--provider <name>", "Default AI provider for spec generation")
+    .option("--model <name>", "Default model for spec generation")
+    .option("--codegen <mode>", "Default code generation mode (claude-code|api|plan)")
+    .option("--codegen-provider <name>", "Default provider for code generation")
+    .option("--codegen-model <name>", "Default model for code generation")
+    .option("--min-spec-score <score>", "Minimum overall spec score (1-10) to pass Approval Gate (0 = disabled)")
+    .option("--show", "Print current configuration")
+    .option("--reset", "Reset configuration to empty")
+    .option("--clear-keys", "Delete all saved API keys from ~/.ai-spec-keys.json")
+    .option("--clear-key <provider>", "Delete saved API key for a specific provider")
+    .option("--list-keys", "Show which providers have a saved key")
+    .action(async (opts) => {
+      const currentDir = process.cwd();
+      const configPath = path.join(currentDir, CONFIG_FILE);
+
+      if (opts.clearKeys) {
+        await clearAllKeys();
+        console.log(chalk.green(`✔ All saved API keys cleared.`));
+        return;
+      }
+
+      if (opts.clearKey) {
+        await clearKey(opts.clearKey);
+        console.log(chalk.green(`✔ Saved key for "${opts.clearKey}" removed.`));
+        return;
+      }
+
+      if (opts.listKeys) {
+        const store: Record<string, string> = await fs.readJson(KEY_STORE_FILE).catch(() => ({}));
+        const providers = Object.keys(store);
+        if (providers.length === 0) {
+          console.log(chalk.gray("No saved API keys."));
+        } else {
+          console.log(chalk.bold("Saved API keys:"));
+          for (const p of providers) {
+            const k = store[p];
+            console.log(chalk.gray(`  ${p}: ${k.slice(0, 6)}...${k.slice(-4)}`));
+          }
+          console.log(chalk.gray(`\nFile: ${KEY_STORE_FILE}`));
+        }
+        return;
+      }
+
+      if (opts.reset) {
+        await fs.writeJson(configPath, {}, { spaces: 2 });
+        console.log(chalk.green(`✔ Config reset: ${configPath}`));
+        return;
+      }
+
+      const existing: AiSpecConfig = await loadConfig(currentDir);
+
+      if (opts.show) {
+        if (Object.keys(existing).length === 0) {
+          console.log(chalk.gray("No config file found. Using built-in defaults."));
+        } else {
+          console.log(chalk.bold(`${configPath}:`));
+          console.log(JSON.stringify(existing, null, 2));
+        }
+        return;
+      }
+
+      const updated: AiSpecConfig = { ...existing };
+      if (opts.provider) updated.provider = opts.provider;
+      if (opts.model) updated.model = opts.model;
+      if (opts.codegen) updated.codegen = opts.codegen as CodeGenMode;
+      if (opts.codegenProvider) updated.codegenProvider = opts.codegenProvider;
+      if (opts.codegenModel) updated.codegenModel = opts.codegenModel;
+      if (opts.minSpecScore !== undefined) {
+        const score = parseInt(opts.minSpecScore, 10);
+        if (isNaN(score) || score < 0 || score > 10) {
+          console.error(chalk.red("  --min-spec-score must be a number between 0 and 10"));
+          process.exit(1);
+        }
+        updated.minSpecScore = score;
+      }
+
+      await fs.writeJson(configPath, updated, { spaces: 2 });
+      console.log(chalk.green(`✔ Config saved to ${configPath}`));
+      console.log(JSON.stringify(updated, null, 2));
+    });
+}