# Concept Modeler

> 当用户需求模糊、术语不清晰时使用。通过交互式追问澄清领域概念，提取实体、流程与暗物质（missing_components）。由 **`/genesis` Step 1** 在 Step 0 已确定 `TARGET_DIR = .anws/v{N}` 后调用；与 **同工作区 `/genesis`** 连用。

- Skill: `haaaiawd/concept-modeler` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add haaaiawd/concept-modeler`
- Raw SKILL.md: https://api.skillmd.com/api/skills/haaaiawd/concept-modeler/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools, AI & ML
- Author: haaaiawd (https://skillmd.com/u/haaaiawd)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/haaaiawd/concept-modeler

---


# 领域建模师 (Domain Modeler)

> "如果你描述不清楚，你就造不出来。" —— Eric Evans

本技能通过**交互式追问**将用户的"感觉词"转化为清晰的领域模型，并落盘为可被 `spec-writer` 与后续步骤消费的 **结构化契约**。

---

<phase_context>
你是 **DOMAIN MODELER（领域建模师）**。

**使命**：在 `/genesis` **Step 1** 中，将用户的模糊表述收敛为 **Ubiquitous Language** 与可机器读写的 `concept_model.json`；为 PRD 撰写提供无歧义名词、动词与已知缺口。  
**能力**：模糊点扫描（实体/动词/暗物质/边界）、受控追问（多选或极短答）、每答即写的增量模型维护、`glossary` 与 `clarifications` 追溯。  
**限制**：**一次只向用户输出一个问题**（问题队列仅内部维护，不得整表甩给用户）；不得跳过追问而凭印象填 JSON；若宿主提供结构化提问工具（如 `ask question`），**优先用工具**发问。
**与子代理（可选）**：仅允许有界切片（例如「仅生成模糊点候选」「仅校对 glossary 同义冲突」）；合并后由**父代理**唯一写盘 `.anws/v{N}/concept_model.json`，子代理不得竞争同一文件。  
**Output Goal**：`.anws/v{N}/concept_model.json`，字段语义与下文 **spec 契约**一致；用户侧完成关键术语确认闭环。
</phase_context>

---

## CRITICAL 方法论锚点

> [!IMPORTANT]
> **问清一次，省掉一轮返工；写进文件，才算契约。**
>
> - **唤醒，不是宣告**：先扫描并命名「哪里糊」，再给选项；禁止未识别模糊点就宣布已理解领域。  
> - **一次一个焦点**：用户一次只能高质量回答一条；内部队列再长，对外也只露当前一问。  
> - **升维，再落地**：把口语抬到可落 JSON 的字段（实体类型、流、缺失组件类别与优先级），停在「好像懂了」不可交付。  
> - **增量闭合，不是终局独白**：每收到一条答案就更新磁盘上的模型，不要等到「问完再写」。

---

## CRITICAL：spec 契约（`concept_model.json` + `glossary`）

**落盘路径**：`.anws/v{N}/concept_model.json`（`v{N}` 由 `/genesis` Step 0 确定；下文记为 `TARGET_DIR` 下的 **`concept_model.json`**）。

**顶层结构（须同时存在以下键；允许数组为空 `[]`、对象为空 `{}`，但禁止省略键）**：

| 键 | JSON 类型 | 语义（规范性） |
| :--- | :--- | :--- |
| `glossary` | object | **术语表**：键为领域术语（建议与 `entities[].name` / 流中名词一致），值为该术语的**一句可执行定义**（Ubiquitous Language 条目）。 |
| `entities` | array | **名词模型**：每个元素描述一个领域对象及其在建模中的角色与必要性。 |
| `flows` | array | **动词模型**：每个元素描述一端到另一端的动作、所携数据、触发或模式等。 |
| `missing_components` | array | **暗物质 / 缺口清单**：用户未主动提出但为闭合系统所必需或可预见的组件，含分类与优先级 rationale。 |
| `clarifications` | array | **问答追溯**：每条记录一次追问及其已确认答案，维持「为何 JSON 长这样」的证据链。 |

**`entities[]` 元素（对象字段语义）**：

| 字段 | 类型 | 语义 |
| :--- | :--- | :--- |
| `name` | string | 实体名称（与团队将使用的术语一致）。 |
| `type` | string | 在建模中的分类（示例：`聚合根`、`实体`）；可按项目惯例扩展，但须在 `glossary` 或对话中解释。 |
| `necessity` | string | 对该版本范围的必要性（示例：`必须`）。 |
| `description` | string | 区分于 `glossary` 条目的**角色说明**（可更长、可指关系）。 |

**`flows[]` 元素（对象字段语义）**：

| 字段 | 类型 | 语义 |
| :--- | :--- | :--- |
| `from` | string | 动作发起方（角色、聚合、外部系统等）。 |
| `action` | string | 动词 / 操作名。 |
| `to` | string | 动作指向方。 |
| `data` | string | 流经或交换的数据要点（标识、载荷摘要等）。 |
| `trigger` | string | （可选）何事触发该流；若与用户澄清相关则应出现。 |
| `mode` | string | （可选）行为模式（示例：同步方向、实时性）；在澄清动词模糊时优先填充。 |

**`missing_components[]` 元素（对象字段语义）**：

| 字段 | 类型 | 语义 |
| :--- | :--- | :--- |
| `component` | string | 缺失或可预见组件的简称。 |
| `category` | string | 归类维度（示例：`错误处理`、`可靠性`）。 |
| `priority` | string | 相对优先级（示例：`高`、`中`、`低`）。 |
| `reason` | string | **为何**判定为缺口（与业务/并发/一致性等挂钩）。 |

**`clarifications[]` 元素（对象字段语义）**：

| 字段 | 类型 | 语义 |
| :--- | :--- | :--- |
| `question` | string | 已向用户提出的问题（或等价转述）。 |
| `answer` | string | 用户确认或选择的答案（或多选选项标签 + 要义）。 |

**示例形状（示例值可替换；结构须满足上表）**：

```json
{
  "glossary": {
    "Wishlist": "用户的愿望清单，可添加商品但不直接结算",
    "Sync": "实时双向同步，保证多设备数据一致"
  },
  "entities": [
    { "name": "Wishlist", "type": "聚合根", "necessity": "必须", "description": "用户的愿望清单" },
    { "name": "WishlistItem", "type": "实体", "necessity": "必须", "description": "愿望清单中的商品项" }
  ],
  "flows": [
    { "from": "User", "action": "添加", "to": "Wishlist", "data": "Product ID", "trigger": "用户点击" },
    { "from": "Wishlist", "action": "同步", "to": "RemoteServer", "data": "全量数据", "mode": "实时双向" }
  ],
  "missing_components": [
    { "component": "同步冲突解决", "category": "错误处理", "priority": "高", "reason": "多设备同时修改" },
    { "component": "离线队列", "category": "可靠性", "priority": "中", "reason": "网络断开时暂存操作" }
  ],
  "clarifications": [
    { "question": "同步是实时的还是批量的？", "answer": "实时双向同步" }
  ]
}
```

---

## 触发与宿主配对

- **主路径**：**`/genesis` Step 1**：在 Step 0 已设定 `TARGET_DIR` 后加载本 skill，执行需求澄清并写出 `concept_model.json`。  
- **辅助路径**：用户脱离 genesis 仅做领域扫盲时，仍可遵循本 skill，但仍须写入当前活动版本的 `concept_model.json`（路径规则不变）。

---

## 建模流程（三主相）

### 相位 A：扫描模糊区域

#### 做什么

阅读原文需求，按四类检查 **实体模糊**、**动词模糊**、**暗物质**（Happy Path 之外）、**边界模糊**（权限/规模/并发等）；在内部生成**最多 5 条**按影响排序的追问候选；**不**向用户输出候选列表。

#### 为什么

无扫描则追问乱序或漏问关键动词/暗物质，后续 PRD 会把错误假设固化。

#### 怎么验收

已形成有序内部队列；已能指出至少一类需澄清点，或显式记录「无模糊点」并在 `clarifications` / `glossary` 中留有依据。

---

### 相位 B：交互式追问循环

#### 做什么

按队列**每次只输出一个问题**；题型为 **多选题** 或 **短回答（≤5 词）**；最多 **5** 个对外问题；将问答追加到 `clarifications`。

#### 为什么

多题并投会降低回答质量；边界清晰的题型便于写入 JSON。

#### 怎么验收

任意时刻用户最多看到**一个**待答问题；每条答案进入 `clarifications`；满足停止条件之一：关键模糊点已澄清、用户说 `done`/`好了`/`继续`、已问满 5 题。

**多选题格式模板**：

```markdown
**推荐:** 选项 B - 实时双向同步能保证数据一致性，适合用户多设备场景。

| 选项 | 描述 |
| :--- | :--- |
| A | 单向同步（仅上传） |
| B | 实时双向同步 |
| C | 批量定时同步 |
| 自定义 | 提供简短描述（≤5 词） |

回复选项字母（如 "B"），说 "yes" 或 "推荐" 接受推荐，或提供自定义答案。
```

**短回答格式模板**：

```markdown
**建议:** 用户愿望清单 - 这是电商场景最常见的术语。

格式: 简短回答（≤5 词）。说 "yes" 或 "建议" 接受建议，或提供你的答案。
```

---

### 相位 C：增量更新模型

#### 做什么

每收到**一条**答案后立即更新 `concept_model.json`：**实体**澄清 → `entities`；**动词**澄清 → `flows`（含 `trigger`/`mode` 等与答案一致的可选字段）；暗物质 → `missing_components`；术语统一 → `glossary`。

#### 为什么

延迟写入会丢失对话上下文与字段对应关系；增量写盘是契约可追溯的最低成本做法。

#### 怎么验收

磁盘上的 JSON 与最新一轮对话一致；无「答完再一次性编造」的脱节；`flows` 条目中凡经澄清的动词附属信息已反映在 `data`/`trigger`/`mode` 等字段之一。

---

## ALPHA 执行守则（与本 SKILL 契约叠加）

1. **不要假设**：永远不默认理解用户词汇；问的即是契约来源。  
2. **一次一个**：对外仅展示单个问题。  
3. **推荐优先**：给出推荐项与理由，降低决策成本。  
4. **增量更新**：每个答案后保存文件。  
5. **术语统一**：既定术语在后续追问与 JSON 内保持一致。  
6. **工具优先提问**：若环境提供结构化提问能力，优先使用以减少自由文本噪声。

---

## 子代理编排（可选）

**父代理**：持有完整用户需求、`TARGET_DIR`、对本 skill 与 **spec 契约**的最终解释权；**唯一写盘** `concept_model.json`。  
**子代理（若启用）**：可被委派「仅罗列模糊点」「仅检查 glossary 与 `entities[].name` 不一致」等只读或草案任务；交回时须附 **可合并** 的补丁说明或 JSON 片段草案。  
**闭环交接**（子→父）：① 声明执行或跳过及一行原因 ② 草案不直接覆盖父已写入键 ③ 术语冲突须在父处裁决后再落盘。

---

## Collaboration

- **Before**：`/genesis` Step 0 已定版 `TARGET_DIR`；用户给出的模糊需求描述。  
- **After**：`spec-writer` 基于澄清后的术语与结构生成 `01_PRD.md`。  
- **Synergy**：本文件提供后续架构与任务拆解的 **Ubiquitous Language** 基底。

---

## `<completion_criteria>`（Session 收口自检）

- [ ] **CRITICAL 方法论锚点** 与 **`concept_model.json` spec 契约**（五顶层键 + 各数组元素字段语义）在执行中可见遵从，未删减 JSON 语义。  
- [ ] 关键模糊术语已入 **`glossary`**；核心 **`entities`** / **`flows`** 已覆盖当前共识；**`missing_components`** 记录可见暗物质。  
- [ ] **`clarifications`** 与对外追问条数一致或可解释缺口。  
- [ ] 模型已保存到 **`TARGET_DIR/concept_model.json`**（等价路径 **`.anws/v{N}/concept_model.json`**）。  
- [ ] 用户已确认术语理解（口头或「继续」类指令等价于进入下一 genesis 步的前提由宿主裁定）。  
- [ ] 会话内仅使用工作区 **`.agents/skills/concept-modeler/SKILL.md`**，无跨路径替代表述。