---
name: ddt-brief-builder
description: 把任意输入（一段文字 / 文件路径 / URL / 已有 PRD / 比赛官网 / 截图 / 会议纪要 / xlsx 功能清单 / 第三方 API 文档 / 多源混合）转成专业 DDT 友好的 project-brief.md，作 DDT 工作流第零步。当用户说"帮我写 project-brief"、"DDT 第零步"、"新项目设置"、"测试项目设置"、"把需求转成 brief"、"我想用 DDT 跑这个项目"、"比赛项目想用 DDT"、"项目简报"、"启动 alv-ops"，或粘贴一段需求/比赛说明/已有 PRD/会议纪要/API 文档目录让你转成 DDT 输入时，立即触发本 skill。覆盖 10 类输入识别、3 个关键决策门、质量自检（含 D26 preset/framework/ai_design 交叉校验）、项目目录一键脚手、与 DDT 后续命令（/prd → /wbs → /design → /design-brief）的丝滑对接。Baseline 信息源（人员/工时/进度表）触发同包的姊妹 skill `ddt-baseline-sync`。claude-design handoff bundle 由 /design-execute 阶段的 `bin/ingest-claude-design.mjs` 摄取，**不在 brief 阶段处理**（避免过早介入；brief 阶段只声明"已有设计"作 §10 参考资料链接）。
origin: DDT
---

# DDT Brief Builder · 工作流第零步

> **使命**：把任意非结构化输入转成 DDT 标准 `project-brief.md`，让 `/prd` 一跑即过、不卡。
> **设计 KPI**（v0.9.4 实战驱动）：从一句话 → 可启动 DDT 全流程 ≤ 90 秒、≤ 5 步互动。
> **范围**：仅产出 `project-brief.md`（可选附带项目目录脚手）。后续工作流由 DDT 各 phase 命令处理。

## 何时触发

| 用户场景 | 处理 |
|---|---|
| 显式要求："帮我写 brief" / "DDT 第零步" / "启动 alv-ops" | 主流程 |
| 粘贴非结构化需求 + 提到 DDT / 比赛 / 测试项目 | 主流程 |
| 给 URL / 文件 + 问"能用 DDT 开始吗" | 主流程 |
| 已有 PRD + "DDT 让我先填 brief" | 反向提炼模式 |
| **人员表 / 工时表 / 项目计划**（独立给出，无 brief 上下文） | **改触发姊妹 skill `ddt-baseline-sync`** |

**不触发**：
- 已有 `project-brief.md` 且只想刷新 → 直接 `/prd --refresh`
- 提到 `/design-brief` → 那是 v0.8 设计阶段，与本 skill 无关

## 输入识别（开场第一步）

| 类型 | 信号 | 处理 |
|---|---|---|
| **A** 自然语言描述 | 对话直接给文本（≥ 50 字） | 直接提取字段 |
| **B** 本地文件路径 | `.md` `.pdf` `.docx` `.txt` | 用 `Read` 读取 |
| **C** URL | `http(s)://` | 用 `WebFetch` 拉取 |
| **D** 已有 PRD | 提到 "PRD" / "需求文档" / 路径含 `prd.md` | **反向提炼**：从详细 PRD 向上抽象 |
| **E** 比赛官网 / 题目 | 含"比赛" / "hackathon" / "评分标准" | 评分项作硬指标 + 历届作品作参考 |
| **F** 项目截图 / 草图 | 上传图片 | `Read` 看图后提 UI 线索作 §核心功能 |
| **G** 多源混合 | 同时多类 | 按 PRD/URL > 文件 > 文字优先级合并 |
| **H** 会议纪要 / 评审记录 | 含"会议" / "纪要" / "※" / "目标上线日" / "客户代表" | **客户驱动模式**：会议确认范围作硬约束；§2 用户分甲方/乙方 |
| **I** xlsx / csv 功能清单 | 文件名含"功能清单" / "feature-list" / "需求" | **自动 dump**：见下方 §"如何调脚本（绝对路径）"，跑 `dump-xlsx.py` |
| **J** 第三方 API 文档（v0.9.8 D25） | 目录名含 `API` / `开放平台` / `SDK` / `OpenAPI` / `swagger` / `集成规约` / `对接文档`；或单 yaml/json 含 `openapi:` 顶层；或单 md 含 `## GET /xxx` 章节 | **自动 dump 进 §11 集成依赖**：跑 `dump-api-docs.mjs`，强制脱敏后注入 brief。详见 `$DDT_PLUGIN_ROOT/skills/ddt-brief-builder/references/integration-detection.md` |

**识别后必须先告知用户**："识别到 ⟨类型⟩，将走 ⟨路径⟩ 提取字段"——给用户机会纠正。

## 如何调用本 skill 的 scripts/（v0.9.5 D22）

**LLM 跑 Bash 时 cwd 是用户项目根，不是 skill 根**——必须用绝对路径调本 skill 的脚本：

```bash
# 推荐：先解析 plugin root（marker 文件 fallback chain）
PR="${DDT_PLUGIN_ROOT:-$(cat "${HOME}/.claude/delivery-metrics/.ddt-plugin-root" 2>/dev/null)}"
PR="${PR:-${HOME}/.claude/plugins/marketplaces/digital-delivery-team}"

# 然后调本 skill 的脚本（统一前缀 $PR/skills/ddt-brief-builder/scripts/）
python3 "$PR/skills/ddt-brief-builder/scripts/dump-xlsx.py"           <path>
node    "$PR/skills/ddt-brief-builder/scripts/dump-api-docs.mjs"      <path>             # v0.9.8 D25
node    "$PR/skills/ddt-brief-builder/scripts/check-brief-quality.mjs" <brief-path>
node    "$PR/skills/ddt-brief-builder/scripts/scaffold-brief.mjs"      --target <dir> --brief <brief-path>
```

**禁止**：
- ❌ `python3 scripts/dump-xlsx.py ...`（cwd 是项目根，找不到）
- ❌ `python3 .claude/plugins/...`（路径错——`.claude` 在 `~`，不在项目里）
- ❌ 把 skill 内绝对路径硬编码在 brief 产物里（让产物可移植）

## 关键场景特化

| 信号 | 默认行为 |
|---|---|
| **B2B 项目**（"客户" / "运营" / "合同" / "网点" / "车队" / "物流" / "工厂" / "医院" / "政府"） | D1 决策门首选 **java-modern**（B2B 后台稳定性 + 合规） |
| **多模块**（5+ 独立模块） | §4 不强制 3-7 条上限，改用模块化 markdown（每模块 H3 + P0/P1/P2） |
| **外部接口强依赖**（"对接 X 接口" / "取决于 X 能力"） | §5 加"外部接口依赖"子项 + 未确认的接口写**软 blocker**；**已提供文档** → 触发 dump-api-docs.mjs 注入 §11 集成依赖（v0.9.8 D25） |
| **会议纪要 ※ / [必做]** | §4 自动转 P0；其余 P1 / P2 |
| **工期/范围严重不匹配** | 触发软 blocker：`reasonability check 失败：N 模块 × M 子功能 vs T 人天` |
| **客户参与决策**（会议含"客户代表"） | §2 用户分**甲方运营 / 乙方业主**两类 |
| **包含人员/工时/进度表** | 同时触发姊妹 skill `ddt-baseline-sync` 做 baseline 增量 |

## 字段提取与填充（11 字段，v0.9.8 起；v0.9.9 D26 加子字段约束）

详细规则见 `$DDT_PLUGIN_ROOT/skills/ddt-brief-builder/references/field-rules.md`（用 Read 工具读绝对路径），speed cheat：

| # | 字段 | 必填 | 缺失处理 |
|---|---|---|---|
| 1 | 项目背景 | ✅ | AskUserQuestion 问核心痛点 |
| 2 | 目标用户 | ✅ | 缺则标 `<待用户确认>` + 软 blocker |
| 3 | 成功标准 | ✅ | 至少 1 条可量化；比赛项目用评分标准 |
| 4 | 核心功能 | ✅ | 简单项目 3-7 条；多模块用模块化结构 |
| 5 | 关键约束 | ✅ | 截止 / 工期 / 合规 / 外部依赖 / 团队规模 |
| 6 | 技术栈预设 + ui_components 子字段（v0.9.9 D26）| **决策门 D1** | 严格按 preset default 填 frontend.framework；ui_components 按场景（B2B 中后台 → antd-5；SaaS → shadcn-ui） |
| 7 | 前端类型（PR-E 三态）| **决策门 D2** | 同上 |
| 8 | AI-native UI 通道 | **决策门 D3**（仅 spa） | 同上；选 claude-design 时强相关 React |
| 9 | 非目标 | 可选 | 留空 OK，建议 1-2 条防 scope creep |
| 10 | 参考资料 | 可选 | URL / 文件路径；保留原始输入摘要（被动浏览） |
| 11 | 集成依赖（v0.9.8 D25） | 可选 | 第三方 API 契约（主动消费）；输入类型 J 时由 dump-api-docs.mjs 自动产出 |

### v0.9.9 D26 反模式（实战触发，v0.9.10 D27 收敛）

brief 阶段保持**宽松**——给后续 /design-brief 减少摩擦，不在 brief 阶段武断锁死前端栈：

- ❌ **java-modern + Vue + Element Plus**：preset default 是 React + Vite + Tailwind + shadcn-ui，写 Vue 是凭训练偏置（国内 Java 项目偏置）。如确需 Vue，应改 preset=interactive
- ⚠️ **claude-design 通道 + 非 React 框架**：bundle 一般是 .jsx，但 README 明说 "recreate in whatever fits"，不强制；只在 brief §6/§7 写 Vue/Svelte 时软警告，由 /design-brief 阶段细化
- ❌ **brief §6 留空 ui_components**：让 LLM 在下游 /prd /design 阶段自由发挥 → 训练偏置污染产出
- ✅ **check-brief-quality 自动交叉校验**：上述反模式触发软警告（不阻塞 pass，但提醒）

> 设计哲学：brief 不该过早介入设计层细节。framework / UI 库的精细化决策属于 /design-brief 范围；brief 只在明显违反 preset default 时给软警告。

## 3 个关键决策门（**必须用 AskUserQuestion**）

DDT 后续命令对这 3 个决策强依赖。详细模板见 `$DDT_PLUGIN_ROOT/skills/ddt-brief-builder/references/decision-gates.md`，**speed cheat**：

```
D1 技术栈预设  → java-modern (B2B/Recommended) | node-modern | go-modern | python-fastapi | interactive
D2 前端类型    → spa (Recommended for SaaS/后台) | server-side | none
D3 AI 设计通道 → claude-design (Recommended) | figma | v0
```

**默认推断**（按输入信号给 `(Recommended)` 标记）：
- B2B 信号 → java-modern；SaaS 信号 → node-modern；AI 信号 → python-fastapi；高并发 → go-modern；其他 → node-modern
- 含 UI 词 → spa；模板渲染 → server-side；纯 API → none
- 用户没明确说 → claude-design（零外部账号成本）

**集中提问原则**：D1+D2+D3 一次性 3 个 AskUserQuestion 问完——避免多轮打断用户心流。

## 质量自检（产出前必跑）

调用脚本（**绝对路径**，详见 §"如何调用本 skill 的 scripts/"）：

```bash
node "$PR/skills/ddt-brief-builder/scripts/check-brief-quality.mjs" <draft-brief-path> --json
```

返回 JSON：`{ fill_rate_pct, filled_total, blockers, warnings, field_details }`

**门槛**：
- `pass: true`（填充率 ≥ 70% 且必填字段全填）→ 直接产出
- `pass: false` 且必填缺 → 不产出，回头问用户补
- `pass: true` 但 warnings 非空 → 产出 + 在 brief 末尾列软 blocker

## 产物落盘 + 项目脚手（一键）

**两种落盘模式**：

### 模式 A：仅写 brief 到当前目录

适用于：用户已经在项目目录里，只要 brief 文件。

```bash
# LLM 用 Write 工具写到 cwd/project-brief.md
# 已存在则 AskUserQuestion 选：覆盖 / 写 draft 旁路 / 取消
```

### 模式 B：一键脚手新项目目录（**演示首选 / 丝滑模式**）

适用于：用户给项目名 + brief 内容，期望立即 cd 进去跑 `/prd`。

```bash
# 先把 brief 写到临时位置（如 /tmp/brief.md），再调脚本（**绝对路径**）：
node "$PR/skills/ddt-brief-builder/scripts/scaffold-brief.mjs" --target <project-dir> --brief <brief-path>
```

脚本会一次完成：mkdir → cp brief → cp .gitignore → git init → initial commit → 输出"下一步"引导。

**适用场景判断**：
- 用户说 "启动 alv-ops" / "新建项目目录" / "为 X 项目脚手" → 走模式 B
- 用户在已有项目目录里 → 走模式 A

## 产出后立即输出"下一步指南"

```
✅ project-brief.md 已生成（填充率 X%，关键决策已确认）

填充摘要：
- 项目：<名称>
- 技术栈：<preset> | 前端：<spa|server-side|none> | AI 通道：<channel|N/A>
- 成功标准：<n> 条（其中 <m> 条可量化）
- 软 blocker：<n> 条（不阻塞，留 /prd 阶段细化）

下一步链路：
1. /digital-delivery-team:prd            # product-agent 出 PRD
2. /digital-delivery-team:wbs            # 拆任务（baseline 已校准则估算更准）
3. /digital-delivery-team:design         # 出架构 + OpenAPI 契约
4. (spa) /digital-delivery-team:design-brief → design-execute --channel claude-design
5. /digital-delivery-team:impl → :verify → :ship

完整流程图：docs/architecture/flowchart.md（v0.9 A1 自动生成）
如有人员/工时表 → 对 Claude 说"导入 baseline 工时数据"触发 ddt-baseline-sync
```

## 与 DDT 体系的对齐契约（违反就是 BUG）

1. `/prd` Phase 1 检查 `project-brief.md` 存在 → 路径 `cwd/project-brief.md`
2. `/design` Phase 2b 读"技术栈预设"字段 → 值在 `java-modern | java-traditional | node-modern | go-modern | python-fastapi | interactive | custom` 7 个枚举内
3. `/design` Phase 2b 检查 `interactive` / `custom` → 本 skill D1 必须 AskUserQuestion 让用户选
4. `/design-brief` 引用 brief 的"目标用户"、"核心功能" → 必填非空
5. `/design-execute` 读 `.ddt/tech-stack.json::ai_design.type` → D3 决策门必须给清晰值

## 边界（**做 / 不做**）

✅ **做**：
- D1+D2+D3 集中一次 AskUserQuestion 问完（避免多轮打断）
- 缺字段标 `<待用户确认>` + 写软 blocker，不编假数据
- 已有 brief 默认旁路 `project-brief.draft.md`，不直接覆盖
- 在 §10 参考资料保留原始输入摘要让 product-agent 后续能 cross-reference
- 比赛项目把评分标准作 §3 硬指标
- 多源输入按 PRD/URL > 文件 > 文字优先级合并

❌ **不做**：
- 替用户决定技术栈（哪怕输入暗示 Java，也必须 D1 显式确认）
- 越界写 PRD（用户故事 / Given-When-Then AC 是 /prd 阶段的事）
- 覆盖已有 brief 而不问
- 跳过质量自检（填充率 < 70% 仍产出但不警告）
- 把人员/工时表内容塞 brief 字段（应触发 ddt-baseline-sync）

## 资源索引

```
ddt-brief-builder/
├── SKILL.md                                ← 本文件（识别 + 决策 + 自检 + 输出）
├── scripts/
│   ├── dump-xlsx.py                        ← xlsx 全文 dump（自动 pip install openpyxl）
│   ├── dump-api-docs.mjs                   ← 第三方 API 文档摘要（v0.9.8 D25，零依赖 yaml + 脱敏）
│   ├── check-brief-quality.mjs             ← brief 字段填充率自检（11 字段 + D26 交叉校验）
│   └── scaffold-brief.mjs                  ← 项目目录一键脚手（mkdir+cp+git init+commit）
├── references/
│   ├── field-rules.md                      ← 11 字段决策准则（含 §6 §7 D26 反模式）
│   ├── integration-detection.md            ← 类型 J 第三方 API 文档识别信号（v0.9.8 D25）
│   ├── ui-library-by-scenario.md           ← UI 库场景化推荐（v0.9.9 D26 / v0.9.10 D27）
│   ├── tech-stack-quick-pick.md            ← D1 速查（输入暗示 → preset 推荐）
│   ├── ai-design-quick-pick.md             ← D3 速查（3 通道差异 + 框架推荐宽松）
│   └── decision-gates.md                   ← D1/D2/D3 完整 AskUserQuestion 模板
└── examples/
    ├── from-paragraph.md                   ← 用户粘贴一段文字 → brief
    ├── from-existing-prd.md                ← 已有 PRD 反向提炼 brief
    ├── from-competition-url.md             ← 比赛项目特化（评分项作硬指标）
    ├── from-meeting-minutes.md             ← B2B 多模块实战（会议纪要 + xlsx 多源）
    └── from-api-docs-folder.md             ← 第三方 API 文档目录 + OpenAPI yaml 双例（v0.9.8 D25）
```

> ℹ️ **claude-design handoff 不在 brief 阶段处理**（v0.9.10 D27 收敛）：handoff bundle 由 `/design-execute` 阶段的 `bin/ingest-claude-design.mjs` 摄取到 `.ddt/design/`。brief 阶段如有"已有设计"信号，仅在 §10 参考资料列 URL 链接，不解析内容；framework / UI 库决策留给 /design-brief 阶段精细化。

**姊妹 skill**：
- `skills/ddt-baseline-sync/`：人员/工时/进度表 → `baseline/historical-projects.csv` 增量同步