@haaaiawd/anws 2.3.0 → 2.4.1

package/templates/.agents/skills/concept-modeler/SKILL.md

@@ -1,179 +1,230 @@
----
-
-## name: concept-modeler
-
-description: 当用户需求模糊、术语不清晰时使用。通过交互式追问澄清领域概念，提取实体、流程和暗物质。由 /genesis Step 1 调用。
-
-# 领域建模师 (Domain Modeler)
-
-> "如果你描述不清楚，你就造不出来。" —— Eric Evans
-
-本技能通过**交互式追问**将用户的"感觉词"转化为清晰的领域模型。
-
----
-
-## 使命与定位
-
-**这个技能是什么**: 通过与用户交互，澄清模糊需求，建立领域模型（实体、流程、暗物质）。
-
-**何时调用**:
-
-- `/genesis` Step 1: 需求澄清阶段
-- 用户需求使用模糊术语（"同步"、"列表"、"管理"）
-- 需要建立 Ubiquitous Language
-
-**何时不调用**:
-
-- 需求已经清晰、术语已定义
-- 纯技术实现讨论（无需领域建模）
-
----
-
-## 核心原则
-
-> [!IMPORTANT]
-> **一次只问一个问题，不一次性输出所有问题。**
->
-> **为什么？** 用户一次只能思考一个问题。逐个追问能获得更准确的答案，也避免用户被问题淹没。
-
----
-
-## 交互流程 (Interactive Process)
-
-### Step 1: 扫描模糊区域
-
-**目标**: 识别需求中的模糊术语和缺失信息。
-
-> [!IMPORTANT]
-> 你**必须**先扫描用户需求，识别以下类别的模糊点：
->
->
-> | 类别       | 检查问题                                          |
-> | -------- | --------------------------------------------- |
-> | **实体模糊** | "列表"是什么？`Wishlist`？`ShoppingCart`？`TodoList`？ |
-> | **动词模糊** | "同步"是单向/双向？实时/批量？失败策略？                        |
-> | **暗物质**  | 用户只描述 Happy Path——错误处理？持久化？认证？                |
-> | **边界模糊** | 谁能访问？数据量多大？并发要求？                              |
->
-
-**内部产出**: 生成候选问题队列（最多 5 个），按影响排序。**不输出队列**。
-
----
-
-### Step 2: 交互式追问循环
-
-**目标**: 逐个澄清模糊点，每次只问一个问题。
-
-> [!IMPORTANT]
-> **追问规则**：
->
-> - 最多问 **5 个问题**
-> - 每个问题必须是**多选题**或**短回答（≤5 词）**
-> - 每次只输出**一个问题**
-
-#### 2.1 多选题格式
-
-对于有多种明确选项的问题：
-
-```markdown
-**推荐:** 选项 B - 实时双向同步能保证数据一致性，适合用户多设备场景。
-
-| 选项 | 描述 |
-| :--- | :--- |
-| A | 单向同步（仅上传） |
-| B | 实时双向同步 |
-| C | 批量定时同步 |
-| 自定义 | 提供简短描述（≤5 词） |
-
-回复选项字母（如 "B"），说 "yes" 或 "推荐" 接受推荐，或提供自定义答案。
-```
-
-#### 2.2 短回答格式
-
-对于需要用户自定义的问题：
-
-```markdown
-**建议:** 用户愿望清单 - 这是电商场景最常见的术语。
-
-格式: 简短回答（≤5 词）。说 "yes" 或 "建议" 接受建议，或提供你的答案。
-```
-
-#### 2.3 停止条件
-
-停止追问当：
-
-- 所有关键模糊点已澄清
-- 用户说 "done"、"好了"、"继续"
-- 已问满 5 个问题
-
----
-
-### Step 3: 增量更新模型
-
-**目标**: 每次获得答案后，立即更新领域模型。
-
-> [!IMPORTANT]
-> **每个答案接受后立即更新**，不要等所有问题结束。
-
-**更新规则**：
-
-1. 实体澄清 → 更新 `entities` 列表
-2. 动词澄清 → 更新 `flows` 列表
-3. 暗物质识别 → 更新 `missing_components` 列表
-4. 术语统一 → 记录到 `glossary`
-
----
-
-## 输出格式
-
-**输出路径**: `.anws/v{N}/concept_model.json`
-
-```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": "实时双向同步" }
-  ]
-}
-```
-
----
-
-## 老师傅守则
-
-1. **不要假设**: 永远不要假设你理解了用户的词汇。追问确认。
-2. **一次一个**: 用户一次只能思考一个问题。不要输出问题列表。
-3. **推荐优先**: 给出推荐选项 + 理由，让用户更容易决策。
-4. **增量更新**: 每个答案立即写入文件，避免上下文丢失。
-5. **术语统一**: 一旦确定术语，全程使用该术语，避免同义词。
-6. **工具优先提问**: 如果当前环境提供 `ask question` 等结构化提问工具，优先使用工具发起问题，而不是让用户手动输入整段回复。
-
----
-
-## 完成标准
-
-- 澄清了关键模糊术语（记录到 glossary） -  识别了核心实体和关系 -  发现了用户没说的暗物质组件 -  领域模型保存到 `.anws/v{N}/concept_model.json` -  用户确认术语理解正确
-
----
-
-## Collaboration
-
-- **Before**: 用户提供的模糊需求描述
-- **After**: `spec-writer` 基于澄清后的需求生成 PRD
-- **Synergy**: 你的领域模型为后续架构设计提供清晰的术语基础
-
+---
+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 | 用户确认或选择的答案（或多选选项标签 + 要义）。 |
+
+**示例形状（示例值可替换；结构须满足上表）**：
+
+```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`**，无跨路径替代表述。