@dev-workflow/skill 0.1.0

package/skills/execution/figmaSync/templates/PLAN.md.tpl

@@ -0,0 +1,227 @@
+---
+figmaUrl: <粘贴用户提供的 Figma URL>
+nodeId: <从 URL 提取的 node-id，例如 123:456>
+fileKey: <从 URL 提取的 fileKey>
+targetFile: <计划落地的源码主文件，例如 src/routes/welcome/route.tsx>
+foundationSummaryPath: ./foundation-summary.md
+
+# 失效锚点（apply 阶段校验是否过期）
+figmaMetadataHash: <get_metadata 返回 JSON 的 sha256>
+figmaSnapshotPath: ./figma-snapshot.png
+apexUiVersion: <node_modules/@frontend/apex-ui--react/package.json 的 version>
+themeHash: <theme/dark/primitives.css + theme/dark/aliases.css 的 sha256 摘要>
+cssDraftPath: ./figma-plan.css
+cssDraftHash: <figma-plan.css 的 sha256>
+
+# 报告引用
+planReport: ./session-report-plan.md
+applyReport: null
+
+plannedAt: <ISO 时间戳>
+status: planned # planned | applied | superseded
+---
+
+# PLAN: <页面/特性名>
+
+> 本文档由 `figmaSync plan` 生成。plan 阶段同时生成 `figma-plan.css` 作为审核草案。
+> 该 CSS 草案不在 plan 阶段接入业务代码；apply 阶段需在用户确认后迁移为正式 CSS。
+
+## 1. 视觉结构
+
+![figma-snapshot](./figma-snapshot.png)
+
+```text
+<节点层级树，按 get_metadata 输出整理；保留 nodeId 便于追溯>
+- WelcomePage (1:1)
+  ├── HeroBanner (1:2)
+  ├── FeatureGrid (1:5)
+  └── Footer (1:9)
+```
+
+## 2. 组件映射决策
+
+| Figma 节点  | nodeId | 目标实现                                  | 复用类型         | 样式归属      | 是否需要 CSS | 备注               |
+| ----------- | ------ | ----------------------------------------- | ---------------- | ------------- | ------------ | ------------------ |
+| CTA Button  | 1:3    | `<Button type="primary" size="medium" />` | Apex UI          | Apex UI props | 否           | props 可覆盖视觉   |
+| FilterPanel | 1:4    | `TableFilter`                             | common component | 业务组件 CSS  | 少量         | 只补布局 class     |
+| HeroBanner  | 1:2    | 自定义 section                            | 无               | 页面 CSS      | 是           | 页面私有布局       |
+
+> verify-plan 会校验本表里所有 `<Component prop=...>` 字面量是否存在于 Apex UI llm
+> 文档；引用未注册的组件 / prop 会 fail 或 warning。
+>
+> 样式归属必须先判定再写 CSS。`Apex UI props` 表示颜色、边框、圆角、字号、状态样式由
+> 组件 prop 或内置状态控制，不得写入 `figma-plan.css`；`业务组件 CSS` 和 `页面 CSS`
+> 才允许进入 CSS 草案；`待确认` 必须进入待确认清单。
+
+## 2.5 Icon 资产匹配
+
+> 本章节由 `figmaSync plan` 根据 Figma 节点语义与仓库 icon inventory 生成。若仓库没有
+> `assets/`、`icons/`、`public/`、`src/**/assets/`、`src/**/icons/` 中的可用 icon，
+> 必须在表格中写明，并让用户确认其他 icon 导入方案或确认不关心 icon。
+
+Icon inventory:
+
+```json
+<node .agent/skills/figmaSync/scripts/icon-inventory.mjs --pretty 的输出摘要>
+```
+
+| Figma 节点 | nodeId | 语义     | 匹配仓库 icon              | 匹配依据                | 状态 | 用户确认 |
+| ---------- | ------ | -------- | -------------------------- | ----------------------- | ---- | -------- |
+| SearchIcon | 1:20   | search   | `src/icons/SearchIcon.tsx` | 文件名精确匹配 `search` | 可用 | 已确认   |
+| ExportIcon | 1:21   | download | -                          | 仓库未发现 download icon | 缺失 | 待确认   |
+
+状态取值：
+
+- `可用` — apply 阶段必须使用匹配到的仓库 icon。
+- `缺失` — plan 阶段必须让用户确认处理方式；未确认时 verify-plan 失败。
+- `忽略` — 用户明确表示不关心 icon 或接受无 icon 实现。
+
+## 3. 组件与模块拆分规划
+
+> 根据设计稿复杂度和目标目录的基建情况，制定合理的组件与样式拆分策略。
+
+- **拆分策略**：[基于现有基建组件拆分 / Human 确认的轻量视觉拆分]
+- **基建事实来源**：
+  - route：
+  - components：
+  - service：
+  - types：
+  - constants：
+  - foundation-summary：
+- **figmaSync 允许修改范围**：
+  - 布局。
+  - CSS。
+  - Apex UI 组件选型和 props。
+  - 局部展示结构。
+- **figmaSync 禁止修改范围**：
+  - 路由路径。
+  - service 契约。
+  - API 请求基础封装。
+  - 类型语义。
+  - 页面核心状态模型。
+  - 业务组件边界。
+  - 权限逻辑。
+  - Wujie bridge。
+  - src/routeTree.gen.ts。
+- **拆分明细**：
+  - **模块/组件 A** (对应节点 `nodeId`)
+    - 文件路径：`src/.../xxx.tsx`
+    - CSS 拆分：`src/.../xxx.css` (包含主要的局部 class)
+    - 职责/内容：...
+  - **模块/组件 B** ...
+
+## 4. CSS 变量映射表
+
+| 来源（Figma）                          | 类型   | CSS variable              | /theme 路径                        | 原始值     | 命中方式                  | nodeId | designContextStatus |
+| -------------------------------------- | ------ | ------------------------- | ---------------------------------- | ---------- | ------------------------- | ------ | ------------------- |
+| `var(--fill-neutral-primary, #090A0B)` | color  | `--fill-neutral-primary`  | `foundation.fill.neutral.primary`  | `{grey.14}` | Fast Path 0 (variables)   | 1:2    | OK                  |
+| `var(--spacing-24, 24px)`              | number | `--spacing-24`            | `baseValue.spacing.24`             | `24`       | Fast Path 0 (variables)   | 1:2    | OK                  |
+| `#202226`                              | color  | `--fill-neutral-tertiary` | `foundation.fill.neutral.tertiary` | `{grey.12}` | Slow Path (value-match)   | 1:6    | OK                  |
+| `--xxx-not-mapped`                     | -      | -                         | -                                  | -          | 未命中                    | 1:8    | OK                  |
+
+命中方式取值约定：
+
+- `Fast Path 0 (variables)` — 从 `get_variable_defs` 字典直接命中。
+- `Fast Path 1 (lookup-var)` — `lookup-var.mjs` 命中。
+- `Slow Path (value-match)` — `match-token.mjs` 命中。
+- `未命中` — 写入 CSS 草案 TODO 注释和 §5 待确认清单。
+
+designContextStatus 取值约定：
+
+- `OK` — `get_design_context` 成功返回。
+- `RECURSED` — 因 too-large 递归到子节点拿到的。
+- `TOO_LARGE_SKIPPED` — 递归 2 层仍 too-large，apply 阶段必须补调。
+
+## 5. CSS 草案审核
+
+CSS 草案文件：`./figma-plan.css`
+
+审核重点：
+
+- 是否只使用原生 CSS。
+- 是否优先使用 `/theme` CSS variables。
+- 是否避免覆盖 Apex UI props 已能表达的样式。
+- 是否已剔除 Apex UI 组件自管的状态色、背景、边框、圆角、字号、hover/active/disabled/selected 状态。
+- 是否只包含归属为 `业务组件 CSS` 或 `页面 CSS` 的样式。
+- 未命中变量是否均有 TODO 注释和待确认记录。
+
+```css
+<figma-plan.css 关键片段，保留完整文件在同目录>
+```
+
+## 6. 样式落地清单
+
+### Level 1（组件局部 CSS）
+
+- HeroBanner: `.welcome-page__hero`，使用 `--fill-neutral-primary` 与 `--spacing-24`。
+
+### Level 2（扩展 common component）
+
+- （无）
+
+### Level 3（建议新增 /theme 变量）
+
+- （无）
+
+### 未命中待确认
+
+- `#123456` from node `1:8`：现有 `/theme` 未命中，需要用户确认是否新增变量或接受一次性 CSS 值。
+
+## 7. 实施步骤
+
+| #   | 子任务                                          | 产物                    | 验证标准              | 独立 commit |
+| --- | ----------------------------------------------- | ----------------------- | --------------------- | ----------- |
+| 1   | 新建/更新 `<targetFile>` 骨架                   | route.tsx               | typecheck pass        | ❌          |
+| 2   | 将 `figma-plan.css` 迁移为正式 CSS 文件         | route.css / styles.css  | format:check pass     | ✅          |
+| 3   | 拼装 Apex UI 与 common component                | route.tsx               | dev 视觉 OK           | ✅          |
+| 4   | 拼装自定义区块并绑定 className                  | route.tsx + CSS         | dev 视觉 OK           | ✅          |
+| 5   | 收尾跑 `pnpm figma:report --command=apply ...` | session-report-apply.md | 硬编码待确认项已解释 | —           |
+
+> 「独立 commit = ✅」的行做完后，AI 必须停下等用户测试再进入下一行。
+
+## 8. CSS 草案内容
+
+```css
+/* figma-plan.css */
+.welcome-page {
+  min-height: 100%;
+  background: var(--fill-neutral-primary);
+}
+
+.welcome-page__hero {
+  display: flex;
+  gap: var(--spacing-24);
+}
+```
+
+## 9. 实施偏离记录
+
+> 由 `figmaSync apply` 在执行过程中追加。如无偏离，保留本章节但留空。
+
+- <ISO 时间戳> · <章节> · <原决策> → <新决策> · 原因：<一句话>
+
+## 10. 盲区与待补调
+
+记录 plan 阶段无法解析的节点（多为 too-large），apply 阶段必须补调：
+
+| nodeId | 节点名    | 原因                                       | apply 补调状态 |
+| ------ | --------- | ------------------------------------------ | -------------- |
+| 1:42   | DataTable | get_design_context too-large 递归 2 层失败 | 待补调         |
+
+## 11. 参考链接
+
+- Figma URL: <同 frontmatter>
+- Plan session report: <同 frontmatter.planReport>
+- Apply session report: <apply 阶段写入 frontmatter.applyReport>
+
+## 12. 反向校验
+
+> 由 `pnpm figma:verify-plan` 跑出后，AI 把结果摘要写到这里。warning 项必须
+> 在这里说明意图，否则 review 时无法判断是否可接受。
+
+- CSS variable 校验：✅ N 行已检查
+- CSS 草案校验：✅ figma-plan.css 已检查
+- Apex UI 校验：✅ M 个组件已校验
+- Icon 校验：✅ 可用 N · 缺失 M · 忽略 K
+- warning：
+  - <如有>

package/skills/review/consistency-checker/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: consistency-checker
+description: PM↔UI 一致性检查器。检查 PRD 全文与 Figma UI 稿之间的一致性，输出结构化差异清单，用于 UI 评审会前 12-24 小时前置发现问题。适用于用户提供 PRD 和 Figma 链接并要求检查一致性、评审前查漏、生成一致性 checklist 时。
+---
+
+# 一致性检查器
+
+## 对齐边诊断
+
+| 项 | 值 |
+|---|---|
+| 服务对齐边 | PM↔UI |
+| 现状分级 | 主痛 |
+| AI 形态 | 补契约工具 |
+| 主战场 | UI 评审前 12-24 小时（次战场：自测联调阶段兜底） |
+
+## 这个 skill 解决什么问题
+
+在 UI 评审会前 12-24 小时前置检查 PRD 与 UI 稿之间的一致性，把「评审过快 + 无 PRD 对照」导致的主痛遗漏，前移到会前发现。
+
+## 什么时候用
+
+- 用户显式输入 `$consistency-checker <prd> <figma-url>`
+- 用户话术："帮我检查一下 PRD 和 UI 稿有没有对不上的地方 / UI 评审前查一下 / 生成一致性 checklist"
+- 用户提供 PRD 全文 + Figma URL
+
+## 前置产物
+
+| 产物 | 来源 | 是否必需 |
+|---|---|---|
+| PRD 全文（md / txt / URL） | 人工提供 / lark-read | 必需，**不支持 PDF** |
+| Figma URL | 人工提供 | 必需，**强制走 Figma MCP，不降级到 OCR / 截图** |
+| 历史校准数据 | `skills/artifact/calibration/` | 可选 |
+| 项目业务词表 | `rules/` | 可选 |
+| 历史类似需求 checklist | `rules/` | 可选 |
+
+## 输出产物
+
+| 产物 | 位置 | 下游消费者 |
+|---|---|---|
+| `consistency-report.json` | 项目文档目录 | 人工评审会 / 未闭环清单 |
+
+结构（每条）：
+
+```
+id                 · 唯一标识
+group              · PRD 未见 / UI 越界 / 状态覆盖 / 语义一致
+priority           · P0 / P1 / P2（P0 硬性 ≤ 5 条）
+content            · 问题描述（≥30 字）
+references         · { PRD 章节引用 · Figma 节点引用 }
+suggested_speech   · AI 生成的举手话术
+rule_id            · 触发的规则 ID
+confidence         · high / medium / low
+```
+
+## 下一步
+
+- 输出 P0 项 → UI 评审会当场质询
+- 会中未认领的 P0/P1 项 → 写入 `skills/artifact/open-issues/`（未闭环清单）
+- 自测阶段发现遗漏 → 反查 `consistency-report.json`，归因写入 `skills/artifact/calibration/`（校准清单）
+
+## 明确不做
+
+- **不处理 PRD 隐含约定** —— PM 侧问题，AI 无解
+- **不做 UI 层动画 / 悬浮态细节判断** —— Figma 静态元数据难以覆盖
+- **不越界判断"UI 越界是设计还是遗漏"** —— 标为"待 PM 澄清"，不下结论
+- **不接受 PDF PRD** —— 结构化提取不可靠
+- **不降级到 OCR / 截图** —— Figma URL 必须能被 Figma MCP 访问，不能就报错
+
+---
+
+## 详细规则
+
+### 四类检查
+
+**第一类 · PRD 提到但 UI 未见**
+- 操作类关键词（增/删/改/查 · 导入/导出 · 批量）→ 检查 UI 是否有对应入口
+- 权限描述（角色 X 可 Y）→ 检查 UI 是否有对应角色的入口 / 隐藏
+- 异常态描述（超时 / 失败 / 无权限）→ 检查 UI 是否有对应状态
+
+**第二类 · UI 有但 PRD 未提（可能越界）**
+- UI 稿上的按钮 / 入口 → 反查 PRD 是否有对应功能描述
+- UI 上的字段展示 → 反查 PRD 是否有对应字段定义
+
+**第三类 · 状态覆盖**
+- 列表 / 详情页 → 检查空态 / 加载态 / 错误态是否已画
+- 输入字段 → 检查极限值 / 空值 / 特殊字符
+- 多语言场景 → 检查文案溢出
+
+**第四类 · 语义一致性**
+- PRD 措辞 vs UI 文案 → 检查关键词对应
+- PRD 枚举值 vs UI 展示 → 检查值域一致
+
+### 规则库外置
+
+规则文件放 `rules/*.json`，可直接改文件不改 skill。
+
+### 输出约束
+
+- **P0 硬性 ≤ 5 条**（超过自动降 P1）—— 防止扫读容量过载
+- 无 references 的项自动 discard
+- suggested_speech 用于降低人的发言门槛（配合"降门槛"策略）
+
+### 待补充实现
+
+- [ ] `rules/` 规则库初始 json 骨架
+- [ ] PRD 加载器（考虑抽 `tools/prd-loader/`）
+- [ ] Figma MCP 调用封装（考虑抽 `tools/figma-mcp/`）
+- [ ] 四类检查的 JS 实现
+- [ ] 输出格式化脚本
+
+**当前状态：规范骨架已就绪，实现待启动。**

package/skills/review/consistency-checker/rules/README.md

@@ -0,0 +1,16 @@
+# 规则库
+
+一致性检查器的规则外置目录。改规则不改 skill 代码。
+
+## 计划文件
+
+- `operation-keywords.json` — 操作类关键词表（增/删/改/查 · 导入/导出 · 批量）
+- `permission-patterns.json` — 权限描述提取正则
+- `exception-patterns.json` — 异常态描述提取正则
+- `state-coverage.json` — 状态覆盖检查项（空态 / 加载 / 错误 / 权限拒绝 / 超时）
+- `boundary-values.json` — 边界值检查项（极限 / 空值 / 特殊字符 / 多语言溢出）
+- `semantic-glossary.json` — 语义词表（同名不同义 / 措辞对应）
+
+## Schema 约定（TBD）
+
+每个规则文件的 JSON schema 在 skill 实现开始时定义。当前仅占位。

package/src/cli/agents.mjs

@@ -0,0 +1,16 @@
+// agent 名 → 目标目录映射
+// 目录路径均以「用户仓库根目录」为基准，且以斜杠结尾便于拼接。
+export const AGENTS = {
+  claude: {
+    id: 'claude',
+    label: 'Claude Code',
+    targetDir: '.claude/'
+  },
+  codex: {
+    id: 'codex',
+    label: 'Codex',
+    targetDir: '.agents/'
+  }
+}
+
+export const AGENT_ORDER = ['claude', 'codex']

package/src/cli/copy.mjs

@@ -0,0 +1,95 @@
+// 递归复制目录：镜像仓库层级，逐文件冲突处理。
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+export const CONFLICT = {
+  SKIP: 'skip',
+  OVERWRITE: 'overwrite',
+  PROMPT: 'prompt'
+}
+
+// 单文件冲突时的处理结果码（供 onConflict 回调返回）
+export const CONFLICT_DECISION = {
+  SKIP_ONE: 'skip_one',
+  OVERWRITE_ONE: 'overwrite_one',
+  SKIP_REST: 'skip_rest',
+  OVERWRITE_REST: 'overwrite_rest'
+}
+
+async function pathExists(p) {
+  try {
+    await fs.access(p)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function walkFiles(srcRoot) {
+  const out = []
+  async function walk(dir) {
+    const entries = await fs.readdir(dir, { withFileTypes: true })
+    for (const entry of entries) {
+      const full = path.join(dir, entry.name)
+      if (entry.isDirectory()) {
+        await walk(full)
+      } else if (entry.isFile()) {
+        out.push(path.relative(srcRoot, full))
+      }
+    }
+  }
+  await walk(srcRoot)
+  return out
+}
+
+async function writeFile(from, to) {
+  await fs.mkdir(path.dirname(to), { recursive: true })
+  await fs.copyFile(from, to)
+}
+
+// 复制单个源目录到目标目录，返回统计。
+// state 让「本次全部这样」的决定跨目录延续；调用方在整个安装流程内共享一个 state 对象。
+export async function copyDir(srcAbs, destAbs, { conflict = CONFLICT.SKIP, onConflict, state = {} } = {}) {
+  const stats = { copied: 0, skipped: 0, overwritten: 0 }
+  if (!(await pathExists(srcAbs))) {
+    throw new Error(`源目录不存在：${srcAbs}`)
+  }
+  const files = await walkFiles(srcAbs)
+  for (const rel of files) {
+    const from = path.join(srcAbs, rel)
+    const to = path.join(destAbs, rel)
+    const exists = await pathExists(to)
+    if (!exists) {
+      await writeFile(from, to)
+      stats.copied++
+      continue
+    }
+    // 冲突分派
+    let mode = conflict
+    if (mode === CONFLICT.PROMPT) {
+      if (state.restOverride) {
+        mode = state.restOverride
+      } else {
+        const decision = await onConflict(to)
+        if (decision === CONFLICT_DECISION.SKIP_REST) {
+          state.restOverride = CONFLICT.SKIP
+          mode = CONFLICT.SKIP
+        } else if (decision === CONFLICT_DECISION.OVERWRITE_REST) {
+          state.restOverride = CONFLICT.OVERWRITE
+          mode = CONFLICT.OVERWRITE
+        } else if (decision === CONFLICT_DECISION.OVERWRITE_ONE) {
+          mode = CONFLICT.OVERWRITE
+        } else {
+          mode = CONFLICT.SKIP
+        }
+      }
+    }
+    if (mode === CONFLICT.OVERWRITE) {
+      await writeFile(from, to)
+      stats.overwritten++
+    } else {
+      stats.skipped++
+    }
+  }
+  return stats
+}

package/src/cli/install.mjs

@@ -0,0 +1,131 @@
+// 主流程：选 agent → 选冲突策略 → 展示计划 → 确认 → 复制 → 后置检查。
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { AGENTS, AGENT_ORDER } from './agents.mjs'
+import { copyDir, CONFLICT, CONFLICT_DECISION } from './copy.mjs'
+import { select, confirm, closePrompts } from './prompts.mjs'
+
+const COPY_PLAN = [
+  { srcRel: 'skills/execution/devFlow', destRel: 'skills/execution/devFlow' },
+  { srcRel: 'skills/execution/figmaSync', destRel: 'skills/execution/figmaSync' },
+  { srcRel: 'skills/review/consistency-checker', destRel: 'skills/review/consistency-checker' },
+  { srcRel: 'skills/artifact', destRel: 'skills/artifact' },
+  { srcRel: 'tools/lark', destRel: 'tools/lark' }
+]
+
+// 提示消费者：SKILL.md 里引用了根目录 HUMAN_AGENT_WORKFLOW.md，用户仓库根缺这个文件时打印警告。
+const HAW_FILENAME = 'HUMAN_AGENT_WORKFLOW.md'
+
+function packageRoot() {
+  const here = path.dirname(fileURLToPath(import.meta.url))
+  return path.resolve(here, '..', '..')
+}
+
+async function pathExists(p) {
+  try {
+    await fs.access(p)
+    return true
+  } catch {
+    return false
+  }
+}
+
+export async function run() {
+  try {
+    await runInner()
+  } finally {
+    closePrompts()
+  }
+}
+
+async function runInner() {
+  console.log('')
+  console.log('📦 @dev-workflow/skill installer')
+
+  const agentId = await select(
+    '? 目标 agent：',
+    AGENT_ORDER.map(id => ({
+      value: id,
+      label: AGENTS[id].label,
+      hint: `→ ${AGENTS[id].targetDir}`
+    })),
+    { defaultIndex: 0 }
+  )
+  const agent = AGENTS[agentId]
+  const cwd = process.cwd()
+  const targetAbs = path.resolve(cwd, agent.targetDir)
+
+  const conflictMode = await select(
+    '? 冲突策略（目标文件已存在时）：',
+    [
+      { value: CONFLICT.SKIP, label: '跳过已存在文件', hint: '（保留目标仓库现有版本）' },
+      { value: CONFLICT.OVERWRITE, label: '全部覆盖', hint: '（用包内版本覆盖）' },
+      { value: CONFLICT.PROMPT, label: '逐个决定', hint: '（首次冲突时问，可选择本次剩余全部）' }
+    ],
+    { defaultIndex: 0 }
+  )
+
+  console.log('')
+  console.log(`📂 将复制以下内容到 ${agent.targetDir}：`)
+  for (const item of COPY_PLAN) {
+    console.log(`  ${item.srcRel}/  →  ${agent.targetDir}${item.destRel}/`)
+  }
+
+  const ok = await confirm('? 确认开始？', { defaultYes: false })
+  if (!ok) {
+    console.log('\n已取消，未做任何改动。')
+    return
+  }
+
+  const pkgRoot = packageRoot()
+  const total = { copied: 0, skipped: 0, overwritten: 0 }
+  const state = {}
+  for (const item of COPY_PLAN) {
+    const src = path.join(pkgRoot, item.srcRel)
+    const dest = path.join(targetAbs, item.destRel)
+    process.stdout.write(`  ↳ ${item.destRel} ... `)
+    const stats = await copyDir(src, dest, {
+      conflict: conflictMode,
+      state,
+      onConflict: filePath => askConflict(filePath)
+    })
+    total.copied += stats.copied
+    total.skipped += stats.skipped
+    total.overwritten += stats.overwritten
+    console.log(`copied=${stats.copied}, skipped=${stats.skipped}, overwritten=${stats.overwritten}`)
+  }
+
+  console.log('')
+  console.log(`✅ 已安装到 ${agent.targetDir}`)
+  console.log(`   合计：新增 ${total.copied}，跳过 ${total.skipped}，覆盖 ${total.overwritten}`)
+
+  // 后置检查：目标仓库根是否有 HUMAN_AGENT_WORKFLOW.md
+  const hawPath = path.resolve(cwd, HAW_FILENAME)
+  const hasHaw = await pathExists(hawPath)
+  if (!hasHaw) {
+    console.log('')
+    console.log(`⚠️  未在仓库根目录发现 ${HAW_FILENAME}`)
+    console.log(`   devFlow / prd-review 等子命令依赖它判断 L0/L1/L2/L3 分档`)
+    console.log(`   请从 dev-workflow-skill 源仓库获取并放到项目根目录`)
+    console.log(`   https://github.com/Wenyari/dev-workflow-skill/blob/main/${HAW_FILENAME}`)
+  }
+
+  console.log('')
+  console.log(`建议：git add ${agent.targetDir} && git commit -m "chore: install @dev-workflow/skill"`)
+}
+
+async function askConflict(filePath) {
+  console.log('')
+  console.log(`⚠️  冲突：${filePath} 已存在`)
+  return select(
+    '? 处理方式：',
+    [
+      { value: CONFLICT_DECISION.SKIP_ONE, label: '跳过本文件' },
+      { value: CONFLICT_DECISION.OVERWRITE_ONE, label: '覆盖本文件' },
+      { value: CONFLICT_DECISION.SKIP_REST, label: '此后剩余冲突全部跳过' },
+      { value: CONFLICT_DECISION.OVERWRITE_REST, label: '此后剩余冲突全部覆盖' }
+    ],
+    { defaultIndex: 2 }
+  )
+}

package/src/cli/prompts.mjs

@@ -0,0 +1,66 @@
+// 纯 Node readline 交互，不引入第三方依赖。
+// 用 module-level 单例 rl，避免多次 close/open 关闭 stdin 后无法再读。
+// 测试模式：设 DWF_TEST_ANSWERS="1|y" 时按顺序消费答案，绕过 readline。
+import readline from 'node:readline'
+
+let rlInstance = null
+let testAnswers = null
+
+function loadTestAnswers() {
+  if (testAnswers !== null) return testAnswers
+  const raw = process.env.DWF_TEST_ANSWERS
+  testAnswers = raw ? raw.split('|') : []
+  return testAnswers
+}
+
+function getRl() {
+  if (!rlInstance) {
+    rlInstance = readline.createInterface({ input: process.stdin, output: process.stdout })
+  }
+  return rlInstance
+}
+
+function ask(question) {
+  const answers = loadTestAnswers()
+  if (answers.length > 0) {
+    const next = answers.shift()
+    process.stdout.write(`${question}${next}\n`)
+    return Promise.resolve(next)
+  }
+  return new Promise(resolve => getRl().question(question, answer => resolve(answer)))
+}
+
+// 显式关闭：主流程结束时调用一次。
+export function closePrompts() {
+  if (rlInstance) {
+    rlInstance.close()
+    rlInstance = null
+  }
+}
+
+// 单选，返回被选中项的 value。
+// options: [{ value, label, hint? }]
+export async function select(message, options, { defaultIndex = 0 } = {}) {
+  console.log('')
+  console.log(message)
+  options.forEach((opt, i) => {
+    const marker = i === defaultIndex ? '❯' : ' '
+    const hint = opt.hint ? `  ${opt.hint}` : ''
+    console.log(`  ${marker} ${i + 1}) ${opt.label}${hint}`)
+  })
+  while (true) {
+    const raw = (await ask(`\n请输入编号 [1-${options.length}] (默认 ${defaultIndex + 1})：`)).trim()
+    if (raw === '') return options[defaultIndex].value
+    const n = Number(raw)
+    if (Number.isInteger(n) && n >= 1 && n <= options.length) return options[n - 1].value
+    console.log(`  ⚠️  请输入 1 - ${options.length} 之间的整数`)
+  }
+}
+
+// y/N 确认，默认 no。
+export async function confirm(message, { defaultYes = false } = {}) {
+  const suffix = defaultYes ? '(Y/n)' : '(y/N)'
+  const raw = (await ask(`\n${message} ${suffix}：`)).trim().toLowerCase()
+  if (raw === '') return defaultYes
+  return raw === 'y' || raw === 'yes'
+}