@michaelxwb/code-flow 0.5.1

package/src/adapters/costrict/commands/cf-learn.md

@@ -0,0 +1,291 @@
+# cf-learn
+
+自动扫描项目配置、代码模式和当前工作区变更，提炼有证据支撑的团队规范。输出先作为候选项给用户确认，再写入 `CLAUDE.md` 或 `.code-flow/specs/<domain>/`。
+
+## 输入
+
+- `/project:cf-learn` - 全量扫描
+- `/project:cf-learn <域>` - 仅扫描指定域，如 `scripts`、`cli`，以 `.code-flow/config.yml` 中实际域为准
+- `/project:cf-learn --map` - 生成或更新 Retrieval Map
+- `/project:cf-learn <域> --map` - 仅生成指定域的 Retrieval Map
+- `/project:cf-learn --review` - 基于当前工作区变更提炼可沉淀规范，默认 staged + unstaged + untracked
+- `/project:cf-learn --review --staged` - 仅分析 staged 变更
+
+## 核心原则
+
+- 证据优先：只根据配置文件、CI、测试、代码重复模式、当前 diff，以及 `.session-log.jsonl` 的 `correction` 事件写候选规范，禁止编造不存在的团队规则。
+- 用户确认优先：任何写入前都要展示候选项、目标文件、置信度、来源文件和证据片段。
+- 低置信度不自动写入：单点样例、语义不稳定或只出现在临时代码中的模式，只作为观察项展示。
+- 保持现有结构：优先匹配现有 domain、spec 文件和章节，不新增无必要文件；无法判断目标时询问用户。
+- 贴合优先（learn 的目标）：通用模板只是起点；learn 后要让规范贴近**项目真实做法**——证据印证的留、矛盾的改写、无证据的删减。替换/删除与新增同为候选，统一走确认门并展示 diff，绝不静默改写。
+
+## 执行流程（全量扫描）
+
+1. 建立扫描范围（§1）→ 2. 项目类型识别与域裁剪（§1.5）→ 3. 采集证据：配置 / 代码模式 / 多维度深读 / 纠正信号（§2）→ 4. 生成候选（§3）→ 5. 模板对账 reconcile（§3.5）→ 6. 选择写入目标（§4）→ 7. 用户确认（§5）→ 8. 写入：新增 / 改写 / 删减（§6）→ 9. Map 对账更新（§7）
+
+`--map` 只跑 §7；`--review` 跳过全量，走 R1–R4。
+
+## 1. 建立扫描范围
+
+先读取 `.code-flow/config.yml`，确定 domain、spec 文件、map 文件和 `path_mapping`。如果配置不存在或不完整，只做只读扫描并提示先运行 `cf-init`。
+
+用 `rg --files` 或 `find` 收集配置和源码。进入扫描前必须构建 **统一排除集**：
+- 默认排除：`.git/**`、`.code-flow/**`、`.claude/**`、`.costrict/**`、`.opencode/**`、`.codex/**`、`.agents/**`、`.codex_flow/**`、`node_modules/**`、`dist/**`、`build/**`、`coverage/**`、`.next/**`、`.venv/**`、`venv/**`、`__pycache__/**`
+- 额外排除所有隐藏目录（名称以 `.` 开头），但保留白名单 `.github/workflows/**` 用于 CI 规则提取
+- 从 `.gitignore` 追加排除模式，忽略空行和注释行
+- 所有 `rg --files`、`rg` 和文件读取仅针对“未被排除”的路径执行
+
+## 1.5 项目类型识别与无关域裁剪
+
+全量扫描时（非 `--review`、非 `--map`）先识别项目实际类型，再对 `config.yml` 中已存在却无代码证据的内建域给出裁剪建议。目的：项目演进后（前端被移除、或 init 时误判为 fullstack）保持 specs 与真实技术栈一致，避免无关 spec 持续注入。
+
+### 1.5.1 检测项目类型
+
+复用与 cf-init 一致的信号做只读扫描（应用第 1 步的统一排除集）：
+- 前端框架依赖：`react`、`vue`、`@angular/core`、`svelte`、`next`、`nuxt`（读 package.json dependencies/devDependencies，不只看文件是否存在）
+- 前端目录/文件：`src/components`、`src/pages`、`src/hooks`、`app/`、`pages/`、`components/`、`styles/`，及 `.tsx`/`.jsx`/`.vue`/`.svelte` 源码
+- 后端框架依赖：Node（`express`、`fastify`、`koa`、`@nestjs/*`、`prisma`、`typeorm`）、Python（`pyproject.toml`/`requirements.txt` + `fastapi`/`django`/`flask`/`sqlalchemy`）、Go（`go.mod`、`cmd/`、`internal/`）、Rust/Java（`Cargo.toml`、`pom.xml`、`build.gradle`）
+- 后端目录：`api/`、`services/`、`handlers/`、`controllers/`、`models/`、`migrations/`、`routes/`
+
+判定规则（与 cf-init 步骤 1 保持一致）：
+- 同时命中明确前端与后端信号 → `fullstack`
+- 仅前端信号 → `frontend`
+- 仅后端信号 → `backend`
+- 无明确信号 → `generic`，不产生任何裁剪建议（保守）
+- 用户自定义域（如 `cli`、`scripts`、`infra`、`mobile`）不参与前后端判定，**永不**作为裁剪候选
+
+### 1.5.2 域漂移检测
+
+把 `config.yml` 中的内建域（`frontend`/`backend`）与检测结果对比：
+- 域有 specs 但检测类型不含它（如存在 `frontend/` 但项目判为 `backend`）→ 标记为**裁剪候选**
+- 检测到某类型却缺对应域 specs（如检测到 `frontend` 但无 `frontend/` 目录）→ 标记为**补全建议**，提示运行 `cf-init <type>`；cf-learn 不自行 scaffold
+- **注入覆盖漂移**：检测到的前端源码类型（如 `.vue`/`.svelte`/`.tsx`）若未被 `config.yml` 的 `frontend.patterns` 覆盖 → 标记为**补全建议**，提示在 patterns 追加对应类型（走确认门，不自行改写）；否则编辑这些文件时拿不到注入
+- 检测为 `fullstack` / `generic`：不产生裁剪候选
+
+只有当**整个域无任何代码证据**才建议裁剪；单文件缺失不触发。宁可漏报不可误删。
+
+### 1.5.3 裁剪确认与执行
+
+展示裁剪候选与受影响文件清单，等待用户确认（与第 5 步同一道确认门）：
+
+```text
+项目类型识别：backend（证据：pyproject.toml + fastapi；无任何前端框架/目录信号）
+
+检测到无关域 frontend，建议裁剪：
+  - config.yml: 删除 path_mapping.frontend
+  - validation.yml: 删除 TypeScript 类型检查 / ESLint / 前端单元测试
+  - 删除目录 .code-flow/specs/frontend/（N 个文件）
+
+确认裁剪？（yes 执行 / no 仅保留建议 / 输入编号选择性删除）：
+```
+
+用户确认后执行：
+- 安全编辑 `config.yml`，删除该域的 `path_mapping.<域>` 及相关字段，保留其余结构与用户自定义
+- 删除 `validation.yml` 中该技术栈无关的 validator，保持 YAML 结构与用户修改
+- 删除 `.code-flow/specs/<域>/` 目录及其文件
+
+裁剪是破坏性操作：必须先展示完整文件清单，未确认不得删除；用户输入 `no` 时只在输出摘要保留建议，不改动任何文件。
+
+## 2. 采集证据
+
+读取存在的配置文件并记录证据来源：
+- 前端：`.eslintrc*`、`eslint.config.*`、`tsconfig.json`、`.prettierrc*`、`tailwind.config.*`、`next.config.*`、`nuxt.config.*`、`vite.config.*`、`jest.config.*`、`vitest.config.*`
+- 后端：`pyproject.toml`、`setup.cfg`、`tox.ini`、`.golangci.yml`、`Makefile`、`Dockerfile`、`docker-compose.yml`
+- 通用：`.github/workflows/*.yml`、`.gitlab-ci.yml`、`.editorconfig`、`.gitignore`、`package.json`
+
+用 `rg` 搜索代码模式：
+- 错误处理：`try/except`、`catch`、自定义 Error、显式返回错误
+- 日志：日志库、字段结构、stdout/stderr 使用边界
+- 测试：测试框架、断言风格、fixture、mock、覆盖率入口
+- 导入与模块：alias、相对路径、barrel export、入口文件
+- 命名与组织：文件命名、目录分层、组件/服务/脚本边界
+
+每条候选都必须保留来源文件和证据片段，证据片段只截取能支撑判断的最小内容。
+
+全量扫描还必须消费 `.code-flow/.session-log.jsonl` 的 `correction` 事件（最高价值证据，处理细节见末尾「纠正信号源」）——它直接反映用户纠正过 agent 的真实偏好。
+
+### 2.1 多维度深读（让总结贴合项目）
+
+只靠 rg 命中关键字不足以总结贴切的规范。每个保留域必须多维度抽样**精读代表性源码**，覆盖以下角度后再下判断：
+
+- 入口与分层：入口文件 + 每层（如 api/service/model）各 1–2 个代表文件，核对真实分层是否与模板假设一致
+- 错误处理：真实 try/except、catch、自定义异常/错误码的统一程度
+- 测试：框架、断言风格、覆盖范围、fixture/mock 习惯
+- 命名与组织：文件/目录/符号命名的实际惯例
+- 依赖与配置：真实依赖清单、lint/type/格式化配置的实际严格度
+- 数据流：读通一条真实请求/调用链路
+- 前端专项（检测到前端域时）：组件分层（容器/展示是否分离）、数据获取是否收口在 `services/`、复用是否提取为 hook/composable、样式是否与逻辑/请求分离（CSS Modules/token vs 内联魔法值）
+
+纪律：每个维度至少读 2 个真实文件再下结论，单文件样例只算低置信度；读取量按项目规模自适应（小项目读全、大项目每层抽样），但每条写入/改写/删减候选都必须能指向具体文件证据。
+
+## 3. 生成候选规范
+
+候选项格式：
+
+```text
+[动作: 新增|改写|删减|保留] [置信度: 高|中|低] [来源: <file>] [目标: <target-file>] <规范描述>
+证据: <短片段或 diff 摘要>
+原因: <为什么这会影响 AI 生成代码>
+```
+
+置信度判断：
+- 高：配置、CI 或测试明确要求，或同一模式在多个相关文件中重复出现
+- 中：单个模块内稳定出现，且与目录结构、测试或调用链相互印证
+- 低：只有单点样例、上下文不足或可能只是临时实现；默认不勾选写入
+
+过滤规则：
+- 与 `CLAUDE.md` 和现有 spec 已覆盖的内容去重，已覆盖项只标记 `[已覆盖]`
+- 忽略纯格式化细节，除非 formatter 配置会影响生成代码结构
+- 不把框架默认行为写成团队规范，除非项目配置显式覆盖或代码中反复体现
+
+机检草稿（checks）：可机检的新规则（能用正则 / 简单模式判定，如禁 `print`、禁裸 `except`、禁 `any`）一律附 `checks` 草稿（`id`/`type`/`pattern`/`files`/`message`）写入目标 spec 的 frontmatter；不可机检的只写正文。
+
+前端规则同样生成 checks 草稿（如组件内裸 `fetch`/`axios`、列表 `key={index}`、`: any`）。**精度护栏**：`checks.files` 用 `fnmatch` 匹配相对路径且 `*` 跨 `/`，组件类检查须按路径作用域（`*components*`/`*pages*`）避免误伤允许 fetch 的 `services/` 层；框架语法差异（JSX `key={index}` vs Vue `:key="index"`）用多条 check + 不同 `files` 分别覆盖。
+
+## 3.5 模板条目对账（reconcile）
+
+在保留的域内，把**每条现有 spec 条目**（尤其模板起点的通用 / house-style 规则）与第 2 步的多维度证据对账，分四类处理：
+
+| 分类 | 判定 | 处理 |
+|------|------|------|
+| 证实 | 代码反复印证 | 保留，不动 |
+| 矛盾 | 代码真实做法与规则相反 | 候选**改写**为项目真实做法（附冲突文件证据） |
+| 无证据 | 模板通用条文，项目无任何相关代码 / 配置 | 候选**删减** |
+| 缺失 | 代码稳定存在但 spec 未写 | 候选**新增**（走第 3 步） |
+
+判定纪律：
+- 矛盾 / 删减必须有**多个文件一致证据**，单点样例不触发，防误删 house-style
+- 改写优先于删除：能修正成项目真实写法的就改写，纯属无关的才删
+- 拿不准（可能是规范领先于现状的"应然"要求）时标「待确认」交用户，不直接删——规范允许领先现状
+
+## 4. 选择写入目标
+
+按内容路由到目标文件，目标文件名以实际 `.code-flow/config.yml` 和现有 spec 为准：
+- 全局原则、禁忌、验证命令、跨域规则 -> `CLAUDE.md`
+- 目录、模块边界、入口文件、数据流 -> `directory-structure.md`
+- 前端组件、hook、样式、状态管理 -> `component-specs.md`
+- 类型、lint、测试、错误处理、导入规则 -> `quality-standards.md`
+- 数据库、ORM、migration、schema、query -> `database.md`
+- 日志、观测、审计字段 -> `logging.md`
+- API、部署、配置、版本兼容 -> `platform-rules.md`
+- 性能、缓存、重试、异常、测试策略 -> `code-quality-performance.md`
+
+如果目标 domain 或 spec 文件不存在，不要创建猜测文件；把候选标为“需用户选择目标”。
+
+## 5. 用户确认
+
+按 domain 分组展示候选：
+
+```text
+扫描发现以下未记录的规范候选：
+
+全局（建议写入 CLAUDE.md）：
+  1. [x] [高] [pyproject.toml] 所有测试通过 pytest 运行
+
+cli（建议写入 .code-flow/specs/cli/quality-standards.md）：
+  2. [x] [中] [tests/test_cli_init.py] init 行为必须有回归测试
+  3. [ ] [低] [src/example.js] 单点命名习惯，暂不建议写入
+
+确认要写入的条目（编号、all、none，或修改目标文件）：
+```
+
+对账候选（改写 / 删减）单独成组，每项附**原文 + 拟替换文本**的 diff 预览；删改与新增一同确认。
+
+等待用户确认后再编辑。
+
+## 6. 写入
+
+追加到目标文件的相近章节：
+- 规则类 -> Rules、Core Principles、Constraints 或同义章节
+- 模式类 -> Patterns、Conventions、Implementation Notes 或同义章节
+- 禁忌类 -> Anti-Patterns、Forbidden Patterns 或同义章节
+
+保持原文件风格，不重排无关内容。
+
+对账确认的条目，除追加外还要执行替换 / 删除（破坏性，编辑前展示 diff，未确认不得动）：
+- 改写：替换原条目所在行，保留章节其余内容
+- 删减：删除该条目行及其紧邻的从属证据行
+
+写入后输出文件、新增 / 改写 / 删减条目数量。
+
+## 7. Retrieval Map
+
+当传入 `--map`、检测到 `_map.md` 仍含初始占位符，或全量扫描发现 `_map` 与真实结构漂移（Module Map 缺失已存在目录、或列出的文件/层已不存在）时，生成/更新 map：
+- Purpose：来自 README、package metadata 或入口注释
+- Architecture：来自依赖、配置、目录和入口文件
+- Key Files：只列出实际存在并读取过的核心文件
+- Module Map：基于真实目录结构，不列空目录
+- Data Flow：只写能从调用链、路由或脚本入口推断出的流向
+- Navigation Guide：写“做 X 去哪里”的可执行导航
+
+更新前展示 diff 摘要。已有人工内容要保留，只补充缺失或明显过期的段落。
+
+## --review 模式：基于当前工作区变更提炼规范
+
+传入 `--review` 时跳过全量扫描，专注当前工作区变更。
+
+### R1. 采集变更范围
+
+运行：
+
+```bash
+git diff --name-only
+git diff --cached --name-only
+git ls-files --others --exclude-standard
+```
+
+`--review --staged` 只使用 `git diff --cached --name-only`。合并去重后应用统一排除集，仅保留代码、测试、配置和会影响规范的脚本文件。
+
+### R2. 读取变更证据
+
+对候选文件读取：
+
+```bash
+git diff -- <file>
+git diff --cached -- <file>
+```
+
+untracked 文件读取完整内容。每个候选规范必须附带来源文件和证据片段。
+
+### R3. 提炼与去重
+
+从当前工作区变更中提炼稳定模式：
+- 新增强约束：测试、校验、错误处理、协议输出、兼容性边界
+- 新增推荐模式：目录组织、接口分层、复用 helper、命名习惯
+- 新增禁忌：静默异常、重复解析、非 JSON hook stdout、硬编码路径或 secret
+
+与现有 spec 和 `CLAUDE.md` 对比，已覆盖项不再写入。按置信度排序，低置信度默认不选。
+
+### R4. 确认与写入
+
+展示目标文件、置信度、来源文件、证据片段和建议文本。用户确认后按第 6 步写入。
+
+## 纠正信号源（quality_loop.correction_capture，v0.5）
+
+`.code-flow/.session-log.jsonl` 中的 `correction` 事件是最高价值证据——用户在对话中纠正过 agent 的行为（修正经对话发生，不依赖人工改代码）。全量与 `--review` 模式都应消费此信号源：
+
+### C1. 读取与配对
+
+1. 读取近 30 天 `correction` 事件（JSONL 逐行解析，损坏行跳过）
+2. 对每条 correction，按"同 `sid` 且日志顺序在其后 5 个事件内"的 `edit` 事件配对——配对成功即"纠正原因 + agent 修正改动"证据对
+3. 修正文件用 `git log -p -- <file>` 或当前内容截取相关段，组成 ❌（纠正前问题）/ ✅（修正后写法）对照
+4. 纯讨论无后续 edit 的 correction 仅保留语句信号，不强行配对
+
+### C2. 聚合与候选
+
+- 同类纠正（phrase 相近 + 同 domain）聚合计数；**单次信号不生成候选**（阈值 ≥2，防句式误判噪音）
+- 候选格式：规则文本 + ✅/❌ 对照示例 + 可机检时附 `checks` 草稿（id/type/pattern/message，写入目标 spec 的 frontmatter）+ 纠正原文与次数
+- 置信度：同类 ≥3 次为高、2 次为中；低置信度默认不选
+- 仍需用户确认才落盘（与第 5 步一致）
+
+## 输出摘要
+
+```text
+cf-learn 完成：
+- 扫描文件：N ｜ 纠正信号：K 条（配对成功 J 对）
+- 项目类型：<type>（裁剪域 D / 补全建议 E）
+- 对账：改写 R / 删减 P / 保留 S 条
+- 候选规范：M（高 X / 中 Y / 低 Z）
+- 写入：CLAUDE.md +A，<domain>/<spec>.md +B（含 checks 草稿 C 条）
+- Map 更新：<domain>/_map.md
+```

package/src/adapters/costrict/commands/cf-stats.md

@@ -0,0 +1,86 @@
+# cf-stats
+
+统计规范体系的 token 使用情况（各文件分布、预算利用率、压缩与 quality_loop 健康度）；`--audit` 附带规范质量审计。
+
+> 原 `cf-scan` 已并入本命令：质量审计（冗长/冗余/过时/缺描述 + 待复审清单）改用 `/project:cf-stats --audit`。
+
+## 输入
+
+- `/project:cf-stats` — 完整统计
+- `/project:cf-stats --human` — 人类可读格式
+- `/project:cf-stats --domain=frontend` — 仅统计指定领域
+- `/project:cf-stats --audit` — 附带规范质量审计（冗长/冗余/过时/缺描述）与待复审清单
+
+## 执行步骤
+
+### 1. 调用 Python 脚本
+
+用 Bash 执行：
+
+```bash
+python3 .code-flow/scripts/cf_stats.py [--human] [--domain=frontend] [--audit]
+```
+
+将用户传入的参数原样透传。
+
+### 2. 解析输出
+
+解析 stdout 的 JSON 输出，格式如下：
+
+```json
+{
+  "l0": {"file": "CLAUDE.md", "tokens": 650, "budget": 800},
+  "l1": {
+    "frontend": [
+      {"path": "frontend/directory-structure.md", "tokens": 180, "tokens_raw": 200, "tokens_compressed": 180, "saved_pct": 10.0}
+    ],
+    "backend": [
+      {"path": "backend/database.md", "tokens": 200, "tokens_raw": 230, "tokens_compressed": 200, "saved_pct": 13.0}
+    ]
+  },
+  "total_tokens": 1580,
+  "total_budget": 2500,
+  "utilization": "63%",
+  "compression_summary": {"total_raw": 1820, "total_compressed": 1580, "total_saved_pct": 13.2}
+}
+```
+
+每个 spec 的 `tokens` 为压缩后 token（参与预算计算）；`tokens_raw` 为压缩前、`saved_pct` 为节约率。`compression_summary` 为全域聚合。
+
+### 3. 格式化输出
+
+将 JSON 格式化为人类可读的统计信息：
+
+```
+L0 (CLAUDE.md): ~650 / 800 tokens
+
+L1 Frontend:
+  - directory-structure.md: ~180 tokens (raw=200→compressed=180, -10.0%)
+
+L1 Backend:
+  - database.md: ~200 tokens (raw=230→compressed=200, -13.0%)
+
+Total: ~1580 / 2500 tokens (63%)
+COMPRESSION: 1820 → 1580 (-13.2%)
+```
+
+### 4. 质量审计（仅 `--audit`）
+
+传入 `--audit` 时，JSON 额外含 `audit` 字段，human 模式额外输出 `AUDIT` 段：
+
+```json
+"audit": {
+  "files": [{"path": "specs/backend/database.md", "issues": ["冗长: 620 tokens", "冗余: '...' 出现于 3 个文件"]}],
+  "review": [{"item": "specs/frontend/x.md", "reason": "30 天未命中注入/未触发检查"}]
+}
+```
+
+- `audit.files`：仅列出有质量问题的 spec（冗长 >500 token / 跨文件冗余 / 死链过时 / 缺 frontmatter description / checks 标注错误）
+- `audit.review`：待复审清单（长期未命中注入 / 已自动停用 / 反复误报的规则）
+
+格式化为表格，无问题时输出"无规范质量问题"。不传 `--audit` 时提示用户可加 `--audit` 查看。
+
+## 异常处理
+
+- `.code-flow/` 不存在 → 提示运行 `/project:cf-init`
+- Python 脚本执行失败 → 输出错误信息，建议检查 Python 环境

package/src/adapters/costrict/commands/cf-task/align.md

@@ -0,0 +1,283 @@
+# cf-task:align
+
+从需求出发，通过结构化对话产出设计简报（`.design.md`），为 `cf-task:plan` 提供足够丰富的输入。支持三种输入：纯文本需求、`.prd.md` 产品需求文档、`.design.md` 草稿。
+
+## 输入
+
+- `/cf-task:align "需求描述"` — 从需求描述新建设计简报
+- `/cf-task:align <.prd.md 路径>` — 基于已有 PRD 派生设计简报（推荐路径）
+- `/cf-task:align <.design.md 路径>` — 恢复已有草稿继续讨论
+- `/cf-task:align` — 交互式，先问用户要做什么
+
+## 执行步骤
+
+### 1. 确定模式
+
+按参数类型识别（顺序判断，优先匹配更具体的后缀）：
+
+| 参数形态 | 模式 | 行为 |
+|---------|------|------|
+| 已存在的 `.design.md` 文件 | **恢复模式** | Read 读取，展示当前内容，询问调整点，进入 Step 3 |
+| 已存在的 `.prd.md` 文件 | **PRD 派生模式** | Read PRD，执行 Step 2.6 预填充维度，Step 3 只补技术维度 |
+| 已存在的其他 `.md` 文件 | **新建模式（带上下文）** | Read 作为参考材料，进入 Step 2 |
+| 纯文本字符串 | **新建模式** | 以文本作为初始需求，进入 Step 2 |
+| 无参数 | **交互模式** | 询问"要实现什么功能？"，进入 Step 2 |
+
+### 2. 代码库上下文扫描
+
+快速了解项目现状，为后续建议提供依据：
+
+1. 用 Glob 检查 `.code-flow/specs/*/_map.md` 是否存在，若有则 Read 读取（了解项目结构）
+2. 检测技术栈：Read `package.json` / `requirements.txt` / `go.mod` / `pyproject.toml` 等（取存在的）
+3. 用 Glob 扫描与需求相关的现有代码目录，了解已有模式
+
+目的：**让后续建议基于实际代码库**，而非泛泛的通用建议。
+
+### 2.5. 识别需求类型，选择维度
+
+根据需求描述和代码库上下文，判断本次工作的性质，选择适用的讨论维度。
+
+**模板选择规则**：
+- **design-lite.md** — 后端/通用，简单：功能开发(简单) | CLI/脚本 | Bug修复 | 小型重构
+- **design-full.md** — 后端/通用，复杂：跨系统集成 | 性能优化 | 架构演进 | 中大型功能开发
+- **design-frontend.md** — 前端：页面/组件/交互/UI 功能开发
+
+**域识别（依 Step 2 代码库扫描自动判断，不需用户指定）**：
+- 涉前端（检测到 frontend 域 / `.tsx`·`.jsx`·`.vue`·`.svelte` 源码 / UI·组件·页面·样式类需求）→ 用 design-frontend.md 产出前端设计
+- 涉后端/通用 → 按复杂度用 design-lite / design-full（默认 lite，复杂或用户要求时 full）
+- **全栈需求** → 前后端各产出一份（见 Step 5 按域后缀命名）
+
+**模板路径**：
+- Lite: `.code-flow/specs/shared/design/design-lite.md`
+- Full: `.code-flow/specs/shared/design/design-full.md`
+- Frontend: `.code-flow/specs/shared/design/design-frontend.md`
+
+先读取对应模板文件作为生成基准。
+
+**核心维度（所有类型必选）**：
+- 目标与边界
+- 技术方案
+- 约束条件
+- 验收标准
+
+**扩展维度（按需选择，不适用则跳过）**：
+- 数据模型 — 涉及数据库/存储变更时
+- 接口设计 — 涉及 API / CLI / 函数入口变更时
+- 性能与容量 — 命中性能敏感信号时（写路径 / 高频调用 / 大数据量或列表查询 / 循环内 IO / 外部依赖 / 并发）
+
+常见需求类型与维度匹配：
+
+| 需求类型 | 数据模型 | 接口设计 | 技术方案侧重 |
+|----------|---------|---------|-------------|
+| 功能开发（含 API） | ✓ | ✓ API | 组件设计、第三方库选型 |
+| 功能开发（纯后台） | 视情况 | 视情况 | 模块结构、算法/流程、数据流 |
+| CLI 命令/脚本 | — | ✓ CLI | 命令结构、参数、输出格式 |
+| 重构 | — | — | 变更范围、迁移路径、兼容性 |
+| 性能优化 | — | — | 瓶颈分析、优化策略、度量指标 |
+| 定时任务/队列 | 视情况 | — | 调度策略、失败处理、幂等性 |
+| 日志/监控 | — | — | 采集点、指标定义、告警规则 |
+| 构建/CI | — | — | 流水线设计、触发条件、产物 |
+| 缺陷修复 | 视情况 | 视情况 | 根因分析、修复方案、回归范围 |
+
+> 上表仅供参考，AI 应根据实际需求灵活判断，不机械套用。
+
+### 2.6. PRD 派生处理（仅 PRD 派生模式）
+
+从 PRD 各章节提取结构化信息，映射到设计维度作为 Step 3 的预填充上下文：
+
+| PRD 章节 | 映射到设计维度 | 处理方式 |
+|---------|--------------|---------|
+| §2 背景与目标 | 目标与边界（问题/目标） | 直接继承 |
+| §3 用户与场景（含 US-XX） | 目标与边界（用户） | 继承用户画像；US 列表用于 FEAT 追溯 |
+| §4 功能需求（FEAT-XX） | 功能方案（FEAT 清单） | 继承 FEAT 清单与优先级；保留 US→FEAT 来源映射 |
+| §5 非功能需求 | 约束条件（性能/安全/兼容） | 直接继承 |
+| §6 范围与边界 | 目标与边界（In/Out Scope） | 直接继承 |
+| §7 依赖与风险 | 风险与依赖 | 直接继承 |
+
+**需向用户呈现的摘要**：
+```
+已从 PRD 解析：
+  - 功能 N 个（P0: X, P1: Y）
+  - 用户故事 M 个
+  - 非功能约束 K 条
+  - 范围内/外清单已继承
+
+本轮将聚焦技术维度：数据模型 / 接口设计 / 技术方案
+PRD 已覆盖的维度如无需调整，将直接使用。
+```
+
+**关键约束**：
+- Step 3 中已从 PRD 获得充分信息的维度**不重复提问**，除非用户主动修改
+- design 中 FEAT 的"来源"列必须引用 PRD 中对应的 US-XX
+
+### 3. 交互式细化
+
+围绕选中的维度逐步推进，**每轮提 2-3 个问题**（不要一次性抛 10 个问题）：
+
+**目标与边界**（必选；PRD 派生模式下已覆盖，只需用户确认）
+- 解决什么问题？为谁？
+- 做什么？（核心功能列表）
+- 不做什么？（明确排除项）
+
+**数据模型**（涉及数据库/存储变更时）
+- 需要哪些表/集合？
+- 字段、类型、约束、索引？
+- 与现有模型的关系？（外键、关联）
+- 性能敏感时：高频查询的索引、分页/游标、避免全表扫描、读写热点
+
+**接口设计**（涉及 API / CLI / 函数入口时）
+
+API 场景：
+- 哪些 endpoint？请求/响应格式？错误码？
+
+CLI 场景：
+- 命令名称和子命令？参数和 flag？输出格式？
+
+内部函数入口场景：
+- 公开接口签名？输入输出类型？错误处理约定？
+
+性能敏感时：批量接口优先于循环单调、分页/游标、避免 over-fetch、可缓存性
+
+**技术方案**（必选，内容随需求类型变化）
+- 性能敏感路径：正确性满足后按最优性能取向选型——算法/数据结构复杂度、IO/查询次数（杜绝 N+1）、能否批量/缓存/异步、同步阻塞点；记录所选方案的性能依据与放弃的较慢方案
+- 功能开发：关键组件、模块结构、第三方库选型、与现有架构集成方式
+- 重构：变更范围、分步迁移路径、向后兼容策略
+- 性能优化：瓶颈定位、优化策略、性能度量方式
+- 定时任务：调度策略、失败重试、幂等性保证
+- 日志/监控：采集点、指标定义、告警阈值
+- 构建/CI：流水线阶段、触发条件、产物和部署
+- 缺陷修复：根因分析、修复方案、回归测试范围
+
+**性能与容量**（命中性能敏感信号时；否则一句"无性能敏感点，跳过"）
+- 负载量级？（QPS / 数据规模 / 并发；有实测用数据，无则给量级估计，禁止编造）
+- 延迟 / 吞吐目标？热点路径在哪？
+- 潜在瓶颈与应对策略？（索引 / 分页 / 缓存 / 批量 / 异步 / 连接池 / 算法复杂度）
+- 选定方案为什么最优？放弃了哪个更慢的方案？
+
+**约束条件**（必选；PRD 派生模式下已从 NFR 继承）
+- 技术栈、性能要求、兼容性、时间线等
+
+**验收标准**（必选）
+- 怎么判断做完了？正常 / 异常场景各列至少一条
+- 可验证、可转为自动化测试断言的条件（明确输入与可观测输出）；场景 ID（S-/E-/B-）即测试用例来源
+
+**妥协与技术债**（按需）
+- 本次有意接受的取舍或欠债？后续偿还设想？
+
+**交互原则**：
+- 基于 Step 2 扫描到的代码库上下文**提出具体默认建议**，而非空泛提问
+- **性能敏感路径上方案按最优性能设计**：择优于更低复杂度、更少 IO/查询、可批量/缓存/异步的方案，并记录"为什么更快、放弃了哪个更慢方案"；非敏感路径不过早优化
+- **初始需求、PRD 或参考材料中已明确的维度不重复提问**，只就缺失或模糊处发问
+- 每轮回答后更新理解，追问细节或推进到下一个维度
+- 涉及数据库和接口的维度**必须具体到表结构和请求/响应 schema**
+- 不涉及数据库和接口时，**不要强制展开这些维度**
+- PRD 派生模式下，已从 PRD 覆盖的维度不再提问；用户主动要求调整除外
+- 用户说"你定"或"随意"时，根据代码库上下文选择最合理的默认方案，明确告知用户采用了什么
+- 输出语言默认与用户需求语言保持一致；若用户未明确指定语言，默认使用中文生成完整设计简报（标题、正文、表头均为中文）
+- 仅当用户明确要求英文或项目已有强约定要求英文文档时，才输出英文；避免中英混杂
+
+**中断恢复**：在进入 Step 3 之前**提前确定文件路径**（Step 5 的命名与目录逻辑）。当任意两个维度已有实质内容时，立即写入草稿文件。后续每轮对话更新同一文件。这样即使会话中断，进度不会丢失。
+
+### 4. 基于模板生成设计简报
+
+选中的维度都有实质内容后，基于 Step 2.5 选择的模板文件生成设计简报。
+
+**操作步骤**：
+1. 用 Read 读取选定的模板文件（design-lite.md 或 design-full.md）
+2. 按照模板章节结构，将 Step 3 中收集的内容填入对应位置
+3. **只包含适用的章节**，模板中有但需求不涉及的章节跳过
+4. 用 `{}` 占位符替换为实际内容
+5. PRD 派生模式：功能清单的"来源"列填 PRD 中对应的 US-XX
+6. 展示生成的设计简报
+
+**章节映射**（Lite 模板，对应 `design-lite.md` 实际章节）：
+
+| 模板章节 | 内容来源 |
+|---------|---------|
+| 1. 文档控制 | 自动生成（修订历史 v0.1） |
+| 2.1 需求概述 | Step 3 的"目标与边界"（PRD 派生时继承自 PRD §2） |
+| 2.2 功能方案 | Step 3 的功能清单 + 字段约束（FEAT 继承自 PRD §4，"来源"列填 US-XX） |
+| 2.3 范围与边界 | Step 3 的 In/Out Scope（PRD 派生时继承自 PRD §6） |
+| 2.4 验收条件 | Step 3 的"验收标准"（正常/异常场景 + 非功能指标） |
+| 3.1 技术选型 | Step 3 的"技术方案"（语言/框架/数据库选型） |
+| 3.2 架构设计 | Step 3 的"技术方案"（分层与组件，按需） |
+| 3.3 接口设计 | Step 3 的"接口设计"（API/CLI/函数签名，按需） |
+| 3.4 性能与容量考量 | Step 3 的"性能与容量"（热点/瓶颈/策略/目标，按需） |
+| 4. 风险与依赖 | Step 3 的依赖与风险（PRD 派生时继承自 PRD §7） |
+
+**章节映射**（Full 模板，对应 `design-full.md` 实际章节）：
+
+| 模板章节 | 内容来源 |
+|---------|---------|
+| 1. 文档控制 | 自动生成 |
+| 2.1 需求概述 | PRD §2 模块/背景/核心目标 |
+| 2.2 痛点与价值 | PRD §2 + §3（目标用户、当前问题、业务影响、预期价值、US 清单） |
+| 2.3 功能方案 | Step 3 的功能清单 + 字段约束（FEAT 继承自 PRD §4，"来源"列填 US-XX） |
+| 2.4 范围与边界 | Step 3 的范围（继承自 PRD §6） |
+| 2.5 验收条件 | Step 3 的"验收标准"（业务规则 RULE + 场景 S/E/B + NFR） |
+| 3.1 方案选型 | Step 3 的"技术方案"（备选对比含性能预期权重 + 技术栈 + ADR 记录性能依据/被否决项） |
+| 3.2 架构设计 | Step 3 的"技术方案"（架构图 + 分层 + 外部依赖） |
+| 3.3 数据设计 | Step 3 的"数据模型"（表 + 索引 + ER + 容量） |
+| 3.4 接口设计 | Step 3 的"接口设计" |
+| 3.5 质量实现方案 | Step 3 的"约束条件 + 性能与容量"（性能设计含热点路径 + 可靠性/安全/可观测性落地） |
+| 4. 部署与运维 | 按需（发布回滚、监控告警、数据迁移） |
+| 5. 风险与依赖 | Step 3 的依赖与风险（继承自 PRD §7） |
+| 6. 需求追溯矩阵 | 自动生成（US→FEAT→API→TC 关联） |
+
+**章节映射（Frontend 模板，对应 `design-frontend.md` 实际章节）**：
+
+| 模板章节 | 内容来源 |
+|---------|---------|
+| 2.1–2.4 需求概述/功能方案/范围/验收 | Step 3 的目标/功能/范围 + 交互验收场景（S/E/B） |
+| 3.1 技术选型 | 框架 / 状态库 / 路由 / 样式方案 / 数据请求选型 |
+| 3.2 页面与路由结构 | 页面清单与路由层级 |
+| 3.3 组件设计 | 组件树 + 容器/展示分离 + 复用 |
+| 3.4 组件接口契约 | Props / Events |
+| 3.5 状态与数据流 | 状态划分 + 数据流 + services 数据获取层 |
+| 3.6 UI 状态 | loading / empty / error / success |
+| 3.7 样式方案 | 设计 token / 响应式 / 样式与逻辑分离 |
+
+**追溯硬约束（plan 拆解与质量门的基础）**：
+- 功能清单每个 FEAT 保留"来源"列（PRD 派生填 US-XX；无 PRD 填需求描述）
+- 接口（API/CLI/函数）与验收场景标注其实现 / 覆盖的 FEAT-XX
+- Full 模板 §6 需求追溯矩阵必须闭合：US → FEAT → API → TC 不留断点，TC 引用 §2.5.2 场景 ID
+- 任一缺口（FEAT 无来源 / FEAT 无验收 / 矩阵断点）在展示时显式列出并提示补全
+
+展示后询问用户：**确认写入？可以调整任何部分。**
+
+### 5. 写入文件
+
+用户确认后：
+
+1. **确定需求名**：
+   - **PRD 派生模式**：继承 PRD 需求名（去 `.prd` 后缀）。例：`user-login-flow.prd.md` → `user-login-flow`
+   - **恢复模式**：保持原需求名
+   - **新建/交互模式**：从目标推导 kebab-case，如 `user-auth`
+2. **确定需求目录**：
+   - **PRD 派生模式**：使用 PRD 所在的需求目录 `.code-flow/tasks/<日期>/<需求>/`（PRD 与 design 同目录，便于 `cf-task:archive` 整目录归档）
+   - **恢复模式**：保持原目录
+   - **新建/交互模式**：按当前日期创建需求目录 `.code-flow/tasks/<YYYY-MM-DD>/<需求>/`；目录已存在且非本次草稿时目录名追加序号 `<需求>-2`…
+3. **按域后缀命名**（同一需求目录内）：
+   - 前端设计（design-frontend）→ `<需求>.frontend.design.md`
+   - 后端/通用设计（design-lite/full）→ 全栈时 `<需求>.backend.design.md`；纯后端/通用单域时 `<需求>.design.md`
+   - **全栈需求**：前后端各写一份到同一需求目录
+4. 用 Write 写入最终路径
+
+### 6. 输出摘要
+
+```
+已生成设计简报: <完整路径>
+模板类型: Lite / Full
+来源: <PRD 派生 / 新建 / 恢复>
+
+内容:
+  - <按实际包含的章节列出>
+  - 验收标准: N 项
+  - 追溯自检: 每个 FEAT 有来源(US/需求)✓、有验收场景✓；Full 模板 §6 矩阵 US→FEAT→API→TC 闭合，缺口显式列出
+  - 性能自检: 标记性能敏感则方案须体现最优性能设计依据（§3.1/§3.5 或 lite §3.4），否则提示补全或显式声明"无性能敏感点"
+
+下一步:
+  - 审阅/编辑: 直接打开设计简报文件
+  - 标注问题: 在文件中添加 #NOTES，然后 /cf-task:note <name>.design
+  - 生成任务: /cf-task:plan <完整路径>
+```