建模师手册 (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，格式如下：

{
  "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 的功能冲突分析更精准。