---
name: concept-modeler
description: 从模糊的用户需求中提取领域概念——实体、流程和"暗物质"（用户没说的）。基于 DDD（领域驱动设计）方法论。
---

# 建模师手册 (The Modeler's Field Guide)

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

本技能将用户的"感觉词"转化为**实体 (Entities)**、**数据流 (Flows)** 和**暗物质 (Missing Components)**。

---

## ⚠️ 强制深度思考

> [!IMPORTANT]
> 在执行任何分析之前，你**必须**调用 `sequential thinking` 工具，视情况进行 **3—5 步**推理。
> 思考内容例如：
> 1.  "用户说的'同步'是单向还是双向？实时还是批量？"
> 2.  "这个'列表'在代码里对应什么？`Wishlist` 还是 `ShoppingCart`？"
> 3.  "用户只描述了 Happy Path——如果 X 失败了怎么办？"
> 4.  "这个功能需要新的数据库表吗？需要新的 API 端点吗？"
> 5.  "有没有隐藏的安全/性能/可靠性问题用户没提？"

---

## ⚡ 任务目标

从用户的自然语言需求中提取：
1.  **实体 (Entities)** - 系统中的"名词"
2.  **数据流 (Flows)** - "名词"之间的"动词"
3.  **暗物质 (Missing)** - 用户没说但必须存在的组件

---

## 🧭 探索流程 (The Extraction)

### 第一步：名词捕捉 (Noun Hunting)
*   **输入**: "我想让用户能够*同步*他们的*列表*。"
*   **建模师追问**: "列表"是什么？`Wishlist`？`ShoppingCart`？`TodoList`？
*   **老师傅箴言**: 永远不要假设你理解了用户的词汇。**Ubiquitous Language 是 DDD 的核心**。
*   **输出**: 定义清晰的 **Entity** 列表。

### 第二步：动词分析 (Verb Analysis)
*   **输入**: "同步。"
*   **建模师追问**:
    *   是**单向**还是**双向**？
    *   是**实时**还是**批量**？
    *   **失败策略**是什么？重试？回滚？告警？
*   **老师傅箴言**: 动词决定了系统的复杂度。一个"同步"可能藏着 10 个边界情况。
*   **输出**: 定义 **Data Flow** 和 **Consistency Model**。

### 第三步：暗物质探测 (Dark Matter Detection)
*   **老师傅核心定律**: 用户只描述 Happy Path。**你的工作是找到他们没说的一切**。
*   **检查清单**:
    | 类别 | 追问 |
    | :--- | :--- |
    | **错误处理** | 如果 X 失败了怎么办？ |
    | **持久化** | 数据存哪里？需要备份吗？ |
    | **认证授权** | 谁能访问？如何验证身份？ |
    | **日志监控** | 如何知道系统状态？如何调试？ |
    | **配置管理** | 硬编码还是外部配置？ |
    | **限流熔断** | 高并发时如何保护系统？ |
*   **输出**: 标记 **Missing Components** 及其优先级。

---

## 🛡️ 老师傅守则

1.  **不要编造**: 如果信息不足，把问题列出来让用户澄清。
2.  **保守估计**: 宁可多识别缺失组件，也不要遗漏。
3.  **解释推理**: 对每个判断提供理由。
4.  **关联构建信息**: 将识别出的 Entities 与 `build-inspector` 发现的构建根关联起来。

---

## 📤 输出格式

你**必须**使用 `write_to_file` 保存到 `genesis/v{N}/concept_model.json`，格式如下：

```json
{
  "entities": [
    { "name": "Wishlist", "type": "数据", "necessity": "必须", "description": "用户的愿望清单" }
  ],
  "flows": [
    { "from": "User", "action": "添加", "to": "Wishlist", "data": "Product ID" }
  ],
  "missing_components": [
    { "component": "错误重试", "category": "错误处理", "priority": "高", "reason": "API 可能超时" }
  ],
  "questions_for_user": [
    "同步是实时的还是批量的？"
  ]
}
```

---

## 🧰 工具箱

*   `scripts/glossary_gen.py --path src/`: 从代码中提取候选领域词汇。
*   `prompts/GLOSSARY_PROMPT.md`: 领域词汇对齐提示词。
*   `references/ENTITY_EXTRACTION_PROMPT.md`: 完整的实体提取提示词模板（含 Few-Shot 示例）。

---

## Collaboration

*   **Before**: `build-inspector` 和 `runtime-inspector` 揭示了*系统是什么*。
*   **After**: `spec-writer` 定义*系统将变成什么*。
*   **Synergy**: 你的领域模型将帮助 Scout 的功能冲突分析更精准。