@haaaiawd/anws 1.1.0 → 1.2.1

package/templates/.agent/skills/system-designer/SKILL.md

@@ -91,19 +91,57 @@ description: 为单个系统设计详细的技术文档。负责架构图、接
 
 ---
 
+## 📁 双层文档架构 (Two-Layer Document Structure)
+
+> [!IMPORTANT]
+> **每个系统的设计文档采用 L0 + (可选) L1 双层结构。**
+
+|     层次      | 文件                 | 内容                           |       加载频率       |
+| :-----------: | -------------------- | ------------------------------ | :------------------: |
+| **L0 导航层** | `{system}.md`        | 架构图、操作契约表、设计决策   |    高（每次必载）    |
+| **L1 实现层** | `{system}.detail.md` | 完整伪代码、配置常量、边缘情况 | 低（任务明确引用时） |
+
+### L1 拆分解觠规则 (R1–R5)
+
+**触发任意一条即必须创建 `{system}.detail.md`**:
+
+| 规则 ID | 触发条件                                | 理由                                         |
+| :-----: | --------------------------------------- | -------------------------------------------- |
+| **R1**  | 单个连续代码块 **> 30 行**              | 该长度已是实现细节，非设计意图               |
+| **R2**  | 文档内全部代码块总行数 **> 200 行**     | 代码超过文字意味着文档滞向实现层             |
+| **R3**  | 配置常量字典条目 **> 5 个**             | 配置数据与设计文档是不同阅读目的             |
+| **R4**  | 版本内联注释 (`# vX.X 变更`) **> 5 处** | 版本历史应集中到 §版本历史，不应散落在代码中 |
+| **R5**  | 文档总行数 **> 500 行**                 | 超过 500 行的 `.md` 对 AI 上下文是负担       |
+
+### L0 和 L1 内容边界
+
+| 内容类型                     | L0 导航层 | L1 实现层 |
+| ---------------------------- | :-------: | :-------: |
+| 系统目标、架构图、Trade-offs |     ✅     |     ❌     |
+| 操作契约表格（参见守则 7）   |     ✅     |     ❌     |
+| `@dataclass` 属性字段声明    |     ✅     |     ✅     |
+| Protocol/ABC 接口签名        |     ✅     |     ❌     |
+| Mermaid 决策树、数据流       |     ✅     |     ❌     |
+| 函数体伪代码（> 10 行）      |     ❌     |     ✅     |
+| 配置常量定义表               |     ❌     |     ✅     |
+| 版本变更历史                 |     ❌     |     ✅     |
+| 边缘情况、实现注意事项       |     ❌     |     ✅     |
+
+---
+
 ## 📋 输出格式：系统设计文档结构
 
 使用 `.agent\skills\system-designer\references\system-design-template.md` 模板。
 
 **14个章节**：
 
-### 必需章节 (Must Have)
+### 必需章节 (Must Have) — L0 导航层
 1. **概览 (Overview)** - 系统目的、边界、职责
 2. **目标与非目标 (Goals & Non-Goals)** - 从PRD继承
 3. **背景与上下文 (Background)** - 为什么需要、关联需求
 4. **系统架构 (Architecture)** ⭐ - 架构图 + 组件 + 数据流
-5. **接口设计 (Interface Design)** ⭐ - API/组件/消息格式
-6. **数据模型 (Data Model)** - 数据结构 + Schema
+5. **接口设计 (Interface Design)** ⭐ - 操作契约表格 / 跨系统协议
+6. **数据模型 (Data Model)** - 属性字段声明 + 实体关系图
 7. **技术选型 (Tech Stack)** - 核心技术 + 依赖库
 8. **Trade-offs & Alternatives** ⭐ - 为什么选A不选B
 9. **安全性考虑 (Security)** - 认证、加密、风险缓解
@@ -266,24 +304,77 @@ interface User {
 
 ---
 
-## 🧰 工具箱
+### 守则 7：操作契约表格（Agent/游戏系统尓必）
+**规则**: 对于 Agent、游戏核心、消息系统，**必须用操作契约表格代替函数伪代码**，完整伪代码移入 `.detail.md`。
+
+**为什么？** 一行表格 = 30 行伪代码的信息量，且对 AI 上下文更友好。
+
+**表格格式**:
+
+```markdown
+### 操作契约：{XXX 类操作}
+
+| 操作                   | [REQ-XXX] | 前置条件               | 消耗/输入 | 产出/副作用                        |      实现细节       |
+| ---------------------- | :-------: | ---------------------- | --------- | ---------------------------------- | :-----------------: |
+| `embark(unit, port)`   | [REQ-012] | 陆地单位;有港口;未行动 | 3★        | 生成 Boat，承载 unit；原 unit 消失 | [§3.1](./detail.md) |
+| `disembark(boat, pos)` | [REQ-012] | boat 有承载;目标是陆地 | 0★        | 释放单位至 pos；boat 解体          | [§3.2](./detail.md) |
+```
+
+**填写要领**:
+- 操作名: `func_name(key_params)` 风格，参数只写关键入参，不写类型注解
+- 前置条件: 以「;」分隔，不超过 3 个
+- 实现细节: 链接到 `.detail.md` 对应章节（如尚未创建，填「待补充」）
+
+---
+
+### 守则 8：Mermaid 优先于伪代码
+**规则**: 对于决策树、状态机类逻辑，**优先使用 Mermaid flowchart**，完整伪代码移入 `.detail.md`。
 
-### 工具1: 系统设计模板
+**为什么？** Mermaid 图在 L0 层对 AI 输入 Token 消耗更低，且可视化程度更高。
+
+**示例**:
+
+````markdown
+### 决策树：陆地单位任务规划
+
+```mermaid
+flowchart TD
+    A[单位在中立村落上?] -->|是| B[→ capture 任务, 优先级 100]
+    A -->|否| C[HP < 撤退阀值?]
+    C -->|是| D[→ move_to 最近己方城市, 优先级 90]
+    C -->|否| E{军事策略}
+    E -->|aggressive| F[→ 攻击/趋近目标]
+    E -->|defensive| G[→ 守卫无防御城市]
+    E -->|neutral| H[→ 探索/扩张焦点]
+```
+
+> 完整实现见 [`executor.detail.md §4.1`](./executor.detail.md)
+````
+
+---
+
+### 工具1: 系统设计 L0 模板（导航层）
 - **路径**: `.agent/skills/system-designer/references/system-design-template.md`
-- **用途**: 14章节的标准模板，确保文档完整性
+- **用途**: L0 导航层模板，14章节结构，操作契约表格格式
 - **使用**: `view_file .agent/skills/system-designer/references/system-design-template.md`
 
-### 工具2: 调研报告存储
+### 工具2: 系统设计 L1 模板（实现层）
+- **路径**: `.agent/skills/system-designer/references/system-design-detail-template.md`
+- **用途**: L1 实现层模板，触发 R1-R5 任意一条时创建 `{system}.detail.md`
+- **使用**: `view_file .agent/skills/system-designer/references/system-design-detail-template.md`
+
+### 工具3: 调研报告存储
 - **路径**: `genesis/v{N}/04_SYSTEM_DESIGN/_research/{system-id}-research.md`
 - **用途**: 保存 /explore 的调研结果
 - **格式**: Exploration Report (由 /explore 生成)
 
-### 工具3: 架构图工具
+### 工具4: 架构图工具
 - **工具**: Mermaid
-- **语法**: 
+- **语法**:
   - `graph TD` - 架构图
+  - `flowchart TD` - 决策树（优先用此替代伪代码，见守则8）
   - `sequenceDiagram` - 数据流图
-  - `classDiagram` - 类图（可选）
+  - `classDiagram` - 实体关系图
 - **参考**: [Mermaid Documentation](https://mermaid.js.org/)
 
 ---
@@ -300,20 +391,23 @@ interface User {
 
 ### 内容质量
 - [ ] 系统边界定义清晰（输入/输出/依赖）
-- [ ] 接口设计完整（API/组件/消息格式）
-- [ ] 数据模型明确（实体/Schema）
-- [ ] 技术选型有理由（Trade-offs讨论）
+- [ ] **§5 接口设计使用操作契约表格**，而非函数伪代码（守则7）
+- [ ] **§6 数据模型只有属性字段 + Protocol 签名**，无方法体（守则8）
+- [ ] Trade-offs 章节至少讨论 2 个重要决策
+- [ ] 决策树/流程图使用 Mermaid，而非伪代码（守则8）
 
 ### 约束遵守
-- [ ] PRD的性能约束已继承
-- [ ] PRD的安全约束已继承
-- [ ] ADR的技术决策已遵守
-- [ ] 追溯链完整（[REQ-XXX]引用）
+- [ ] PRD 的性能约束已继承
+- [ ] PRD 的安全约束已继承
+- [ ] ADR 的技术决策已遵守
+- [ ] 追溯链完整（[REQ-XXX] 引用）
+- [ ] **L0 文件无方法体伪代码**（如有，立即移入 `.detail.md §3`）
+- [ ] **触发 R1-R5 时已创建 `.detail.md`**（否则标记「待补充」）
 
 ### 可实施性
-- [ ] 接口签名足够详细（可以直接实现）
-- [ ] 数据库Schema完整（可以直接执行）
+- [ ] 操作契约表格完整（每个核心操作都有对应行）
 - [ ] 测试策略明确（单元/集成/E2E）
+- [ ] 如已创建 `.detail.md`，§3 每个小节都填写了「准入理由」
 - [ ] 部署流程清晰（如需要）
 
 ---

package/templates/.agent/skills/system-designer/references/system-design-detail-template.md

@@ -0,0 +1,198 @@
+# {System Name} — 实现细节 (detail)
+
+> **文件性质**: L1 实现层  
+> **对应 L0**: [`{system}.md`](./{system}.md)  
+> 本文件仅在 `/forge` 任务的 `**输入**` 字段明确引用时加载。  
+> 日常阅读、系统概览、任务规划请优先阅读 L0 层文件。
+
+---
+
+## 版本历史
+
+> 所有版本变更记录集中于此，不再散落在代码注释中。
+
+| 版本 | 日期         | Changelog |
+| ---- | ------------ | --------- |
+| v1.0 | {YYYY-MM-DD} | 初始版本  |
+
+---
+
+## §1 配置常量 (Config Constants)
+
+> 所有硬编码配置、枚举映射、查找表集中放在此处。
+
+```python
+# ── 示例: 单位配置表 ──
+# 每行格式: UnitType: {atk, def, hp, mov, range, cost, tech, behavior, move_type}
+UNIT_CONFIG = {
+    # UnitType.WARRIOR: {...},
+    # ...
+}
+
+# ── 示例: 地形配置表 ──
+TERRAIN_CONFIG = {
+    # TerrainType.PLAIN: {move_cost: 1, passable: "land", buildings: [...]}
+    # ...
+}
+
+# ── 示例: 建筑配置表 ──
+BUILDING_CONFIG = {
+    # BuildingType.FARM: {cost: 5, tech: "farming", rp_bonus: 1}
+    # ...
+}
+```
+
+---
+
+## §2 核心数据结构完整定义 (Full Data Structures)
+
+> 包含方法实现的完整类定义（L0 层只放无方法的属性声明）。
+
+```python
+# ── 示例: 完整类定义（含方法） ──
+
+@dataclass
+class ExampleEntity:
+    id: str
+    # ... 字段
+
+    def some_method(self) -> bool:
+        """方法说明"""
+        # 完整逻辑...
+        pass
+```
+
+---
+
+## §3 核心算法伪代码 (Non-Trivial Algorithm Pseudocode)
+
+> [!IMPORTANT]
+> **严格准入门槛 — 不满足任意一条，禁止写入本节**:
+>
+> | 准入条件 | 说明 |
+> |---------|------|
+> | 函数体估计 **> 15 行** | 短函数的意图从 L0 操作契约表格已可理解，不需要伪代码 |
+> | 含**不明显的业务规则** | 如战斗伤害公式、路径寻找、状态机分支、复杂校验逻辑 |
+> | 含**多步骤副作用链** | 如"A→检查→B→更新C→触发D"且顺序不能颠倒 |
+> | **同事看签名猜不出实现** | 若函数名+参数名已能清楚表达意图，则不需要伪代码 |
+>
+> **反例（禁止写入 §3）**:
+> ```python
+> # ❌ 太简单，不需要伪代码
+> def get_nation_stars(nation: Nation) -> int:
+>     return nation.stars
+>
+> # ❌ 5行setter，从签名已可理解
+> def set_military_target(self, target: str) -> None:
+>     self.military_target = target
+>     self.last_updated_turn = world.turn
+> ```
+
+每个小节对应 L0 操作契约表格中的一行，提供完整函数体。
+
+### §3.1 {操作名称}
+
+**对应契约**: L0 §{章节} 操作契约表 — `{function_name}()`  
+**准入理由**: {为什么这个函数需要伪代码，满足了哪条准入条件}
+
+```python
+def function_name(param1: Type, param2: Type, ...) -> ReturnType:
+    """
+    函数说明。
+    
+    前置条件:
+    1. ...
+    
+    副作用:
+    - ...
+    """
+    # 完整实现逻辑
+    pass
+```
+
+**关键设计注意事项**:
+- 注意点1 (如: 深拷贝、竞争条件、顺序依赖等)
+
+---
+
+### §3.2 {操作名称}
+
+```python
+# ...
+```
+
+---
+
+## §4 决策树详细逻辑 (Decision Tree Details)
+
+> 对应 L0 层 Mermaid 决策树的文字展开 + 完整伪代码。
+
+### §4.1 {决策场景名称}
+
+**对应 L0 Mermaid**: `{system}.md §{章节}`
+
+```python
+def plan_or_decide(...):
+    """
+    决策逻辑完整实现。
+    """
+    # Step 1: 检查高优先级条件
+    # ...
+    
+    # Step 2: 分支逻辑
+    # ...
+    pass
+```
+
+---
+
+## §5 边缘情况与注意事项 (Edge Cases & Gotchas)
+
+> 实现时必须处理的非显而易见的情况。
+
+| 场景           | 风险       | 处理方式       |
+| -------------- | ---------- | -------------- |
+| {边缘情况描述} | {潜在 Bug} | {正确处理方式} |
+
+### §5.1 {具体边缘情况}
+
+```python
+# ❌ 错误做法 (会导致什么问题)
+# cloned_unit.embarked_unit = unit.embarked_unit  # 浅拷贝导致状态污染!
+
+# ✅ 正确做法
+# cloned_unit.embarked_unit = deepcopy(unit.embarked_unit) if unit.embarked_unit else None
+```
+
+---
+
+## §6 测试辅助 (Test Helpers)
+
+> 单元测试中复用的工厂函数、fixtures 或测试场景说明。
+
+```python
+# 示例: 测试用工厂函数
+def make_test_unit(type=UnitType.WARRIOR, hp=10, pos=(0,0)) -> Unit:
+    """创建测试用 Unit 对象"""
+    pass
+
+def make_test_world(size=8) -> World:
+    """创建测试用 World 对象"""
+    pass
+```
+
+---
+
+<!-- ⚠️ 使用指南
+**何时填写本文件**:
+- 触发了 R1-R5 任意一条提取规则时
+- L0 的操作契约表对应的实现需要 > 30 行伪代码时
+
+**§ 编号约定**:
+- §1 配置常量: 始终是第一节
+- §2 数据结构: 含方法的完整类
+- §3 算法伪代码: 按照函数顺序编号 (§3.1, §3.2...)
+- §4 决策树展开: 对应 L0 Mermaid 图的文字版
+- §5 边缘情况: 从文档注释中提取的 "# ⚠️ 注意" 类内容
+- §6 测试辅助: 可选
+-->