concept-modeler

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

领域建模师 (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	用户确认或选择的答案（或多选选项标签 + 要义）。

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

{
  "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 题。

多选题格式模板：

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

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

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

短回答格式模板：

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

格式: 简短回答（≤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，无跨路径替代表述。