@haaaiawd/anws 1.0.1 → 1.2.0

package/templates/.agent/skills/spec-writer/references/prd_template.md

@@ -1,174 +1,177 @@
-# Product Requirements Document (PRD) v2.0
+# 产品需求文档 (PRD) v2.0
 
-**Project**: [Project Name]
-**Title**: [Feature/Requirement Name]
-**Status**: Draft | Review | Approved
-**Version**: 1.0
-**Author**: [Author Name or Agent]
-**Date**: [YYYY-MM-DD]
+**项目名称**: [项目名称]
+**功能名称**: [功能/需求名称]
+**文档状态**: 草稿 (Draft) | 评审中 (Review) | 已通过 (Approved)
+**版本号**: 1.0
+**负责人**: [作者名字或 Agent]
+**创建日期**: [YYYY-MM-DD]
 
 ---
 
-## 1. Executive Summary
-<!-- Context Compression: State the "Why" and "What" in < 50 words. -->
-<!-- ⚠️ CRITICAL: This is the "elevator pitch". Must be < 50 words. -->
+## 1. 执行摘要 (Executive Summary)
+<!-- 上下文压缩：在 50 字以内说明"为什么做"和"做了什么"。 -->
+<!-- ⚠️ CRITICAL: 这是"电梯演讲"，必须控制在 50 字以内。 -->
 
-[Briefly describe the problem being solved and the proposed solution. Focus on value.]
+[简明扼要地描述要解决的问题以及所提出的解决方案，请聚焦于核心价值。]
 
 ---
 
-## 2. Background & Context
-<!-- ⭐ 新增: 提供充分背景，帮助后续System Design阶段理解 -->
+## 2. 背景与上下文 (Background & Context)
+<!-- 提供充分的业务和背景知识，帮助后续架构和系统设计阶段更好地理解上下文。 -->
 
-### 2.1 Problem Statement (问题陈述)
-- **Current Pain Point**: [用户面临的具体问题]
-- **Impact Scope**: [受影响的用户群体/业务范围]
-- **Business Impact**: [对业务的影响，如收入、用户满意度、效率]
+### 2.1 问题陈述 (Problem Statement)
+- **当前痛点**: [用户当前面临的具体问题]
+- **影响范围**: [受影响的用户群体/业务范围]
+- **业务影响**: [对业务的实际影响，例如收入损失、用户流失、效率低下等]
 
-### 2.2 Opportunity (机会)
-[如果解决这个问题，能带来什么价值？定量描述]
+### 2.2 核心机会 (Opportunity)
+[如果成功解决这个问题，能带来什么积极价值？请尽量定量描述。]
 
-### 2.3 Reference & Competitors (参考与竞品) - 可选
-<!-- 了解市场已有解决方案，避免重复造轮子 -->
-- **Competitor A**: [特点、优缺点]
-- **Competitor B**: [特点、优缺点]
-- **Our Differentiation**: [我们的独特价值]
+### 2.3 竞品与参考 (Reference & Competitors) — 可选
+<!-- 了解市场已有的解决方案，避免在成熟领域重新发明轮子。 -->
+- **竞品 A**: [特点、优缺点]
+- **竞品 B**: [特点、优缺点]
+- **我们的护城河**: [与竞品的差异化优势/独特价值]
 
 ---
 
-## 3. Goals & Non-Goals
+## 3. 目标与范围 (Goals & Non-Goals)
 
-### 3.1 Goals
-<!-- ⚠️ CRITICAL: 必须使用 SMART 原则 (Specific, Measurable, Achievable, Relevant, Time-bound) -->
+### 3.1 目标 (Goals)
+<!-- ⚠️ CRITICAL: 必须使用 SMART 原则 (明确、可衡量、可实现、相关性强、有时限) -->
 
-- **[G1]**: [可衡量的目标，如: 用户登录成功率 > 95%]
-- **[G2]**: [可衡量的目标，如: 页面加载时间 < 2s]
+- **[G1]**: [可衡量的业务目标，如: 用户登录转化率提升至 95% 以上]
+- **[G2]**: [可衡量的技术目标，如: 列表页 P95 加载时间 < 1.5s]
 
-### 3.2 Non-Goals (Out of Scope)
-<!-- Crucial for preventing scope creep -->
+### 3.2 非目标 (Non-Goals)
+<!-- 明确"不做"什么，这是防止需求蔓延（Scope Creep）的关键。 -->
 
-- **[NG1]**: [暂不考虑的功能，如: 第三方OAuth登录]
-- **[NG2]**: [未来版本的考虑，如: 多因素认证]
+- **[NG1]**: [由于范围限制暂不考虑的功能，如: 第三方 OAuth 快捷登录]
+- **[NG2]**: [属于未来版本规划范围的事项，如: 强制多因素认证 (MFA)]
 
 ---
 
-## 4. User Stories (The "What")
-<!-- Format: As a [User], I want to [Action], so that [Benefit] -->
-<!-- ⚠️ CRITICAL: 每个User Story必须有唯一ID [REQ-XXX]，用于追溯链 -->
-
-### US01: [Title] [REQ-001]
-*   **Story**: As a [role], I want to [feature], so that [value].
-*   **Acceptance Criteria (AC)**:
-    *   [ ] **Given** [context], **When** [action], **Then** [outcome].
-    *   [ ] **Error Case**: When [failure condition], show [specific error message].
-*   **Priority**: P0 (Must Have) | P1 (Should Have) | P2 (Nice to Have)
-*   **Estimation**: [Story Points 或 天数] - 可选
-
-### US02: [Title] [REQ-002]
-*   **Story**: ...
-*   **Acceptance Criteria (AC)**:
+## 4. 用户故事与需求清单 (User Stories)
+<!-- 格式要求: 作为一个 [角色]，我想要 [动作]，以便于 [价值/收益]。 -->
+<!-- ⚠️ CRITICAL: 每个 User Story 必须有唯一 ID [REQ-XXX]，这是整个系统防腐和追溯的核心。 -->
+<!-- ⚠️ CRITICAL: 必须按用户价值优先级排序 (P0 核心路径 → P1 重要体验 → P2 锦上添花)。 -->
+<!-- ⚠️ CRITICAL: 每个 User Story 必须具备独立可测性——完成后可以脱离其他 Story 独立演示。 -->
+
+### US-001: [任务标题] [REQ-001] (优先级: P0)
+
+*   **故事描述**: 作为一个 [角色]，我想要 [功能/动作]，以便于 [获得的好处]。
+*   **用户价值**: [一句话说明该 Story 对于最终目标的核心价值]
+*   **独立可测性**: [该任务完成后，测试/产品可以在不依赖其他功能的情况下如何验证？]
+*   **涉及系统**: [列出将会涉及的系统 ID，如: `frontend-system`, `backend-api` — 必须与 `02_ARCHITECTURE` 中的名字对齐]
+*   **验收标准 (Acceptance Criteria)**:
+    *   [ ] **Given** [初始上下文], **When** [触发动作], **Then** [预期结果].
+    *   [ ] **异常处理**: 当 [发生何种异常] 时，系统必须 [具体的回退或提示行为].
+*   **边界与极限情况**:
+    *   [边界条件1 — 如: 超大数据量、断网重连、权限骤变等极端情况如何处理]
+    *   [边界条件2]
+
+### US-002: [任务标题] [REQ-002] (优先级: P1)
+
+*   **故事描述**: ...
+*   **用户价值**: ...
+*   **独立可测性**: ...
+*   **涉及系统**: ...
+*   **验收标准 (Acceptance Criteria)**:
     *   [ ] ...
-*   **Priority**: P0/P1/P2
+*   **边界与极限情况**:
+    *   ...
 
-<!-- 继续添加更多User Stories... -->
+<!-- 根据需求规模继续添加 User Stories... -->
 
 ---
 
-## 5. User Experience & Design (用户体验) - 可选
-<!-- ⭐ 新增: 描述关键的UX流程，帮助前端系统设计 -->
+## 5. 用户体验与设计 (User Experience) — 可选
+<!-- 提供关键的用户交互设计指引，为前端/客户端的设计系统建立边界。 -->
 
-### 5.1 Key User Flows (关键用户流程)
-<!-- 使用Mermaid流程图描述关键用户旅程 -->
+### 5.1 关键用户旅程 (Key User Flows)
+<!-- 【推荐】使用 Mermaid 流程图直观表达主体业务流程。 -->
 
 ```mermaid
-graph LR
-    A[用户访问登录页] --> B[输入邮箱密码]
-    B --> C{认证}
-    C -->|成功| D[跳转Dashboard]
-    C -->|失败| E[显示错误提示]
+flowchart TD
+    A[用户访问登录页] --> B[输入邮箱与密码]
+    B --> C{后端服务认证}
+    C -->|校验成功| D[跳转 Dashboard 首页]
+    C -->|校验失败| E[输入框下方抛出错误指引]
     E --> B
 ```
 
-### 5.2 Design Guidelines (设计规范)
-- **UI Style**: [现代化、简洁、专业等]
-- **Color Palette**: [主色调、辅助色]
-- **Interactions**: [动画、反馈机制]
+### 5.2 交互规范 (Design Guidelines)
+- **视觉风格**: [现代化、极简、严肃专业等]
+- **响应模式**: [对页面加载骨架屏、按钮 Loading 状态等的要求]
+- **平台兼容**: [仅限 Web 端，是否需要兼顾移动/平板自适应？]
 
 ---
 
-## 6. Constraint Analysis
-<!-- Derived from /scout report or /challenge -->
-<!-- ⭐ 增强: 分类更详细，便于后续System Design继承约束 -->
+## 6. 约束与限制 (Constraint Analysis)
+<!-- 约束决定了技术选型的天花板。来自于 /scout 报告或立项时的不可抗力。 -->
 
-### 6.1 Technical Constraints (技术约束)
-*   **Legacy Systems**: [e.g., Must work with existing Auth system]
-*   **Performance**: [e.g., API response time < 200ms (p95)]
-*   **Scalability**: [e.g., Support 100k concurrent users]
+### 6.1 技术约束 (Technical Constraints)
+*   **遗留系统**: [例如: 必须兼容老版本的 MySQL 5.7 表结构]
+*   **性能底线**: [例如: API 响应时间 P95 < 200ms]
+*   **扩展性预期**: [例如: 设计上需要支撑 10 万并发在线]
 
-### 6.2 Security & Compliance (安全与合规)
-*   **Security**: [e.g., No PII in logs, HTTPS only]
-*   **Privacy**: [e.g., GDPR compliance]
-*   **Compliance**: [e.g., SOC 2 Type II]
+### 6.2 安全与合规 (Security & Compliance)
+*   **数据安全**: [例如: 日志中绝对不可包含明文 PII 信息]
+*   **网络要求**: [例如: 强制全站 HTTPS / API 仅内网可访]
+*   **合规审核**: [例如: 满足当地数据出境要求 / 通过特定等保审核]
 
-### 6.3 Time & Budget (时间与预算)
-*   **Deadline**: [交付时间，如: 2026-03-01]
-*   **Budget**: [预算限制] - 可选
-*   **Team**: [团队规模和技能] - 可选
+### 6.3 时间与资源 (Time & Resources)
+*   **交付死线**: [硬性 Deadline，如: 2026-03-01 必须全量上线]
+*   **其他限制**: [如依赖外部供应商接口的对接进度等]
 
 ---
 
-## 7. Success Metrics (成功指标)
-<!-- ⭐ 新增: 如何衡量成功，便于后续验证 -->
+## 7. 成功指标 (Success Metrics) — 可选
+<!-- 如何在功能上线后衡量我们的成功？ -->
 
-| Metric | Target | Measurement Method |
-|--------|--------|-------------------|
-| 用户登录成功率 | > 95% | Google Analytics |
-| 页面加载时间 (p95) | < 2s | Lighthouse/监控 |
-| 用户满意度 (NPS) | > 4.5/5 | 用户调研 |
+| 核心指标 (Metric) | 目标值 (Target) | 测量方式 (Measurement Method) |
+| ----------------- | --------------- | ----------------------------- |
+| 业务: 注册转化率  | > 45%           | 数据看板/漏斗分析             |
+| 性能: 接口成功率  | > 99.9%         | APM 监控告警                  |
 
 ---
 
-## 8. Definition of Done (完成标准)
+## 8. 完成标准 (Definition of Done)
+<!-- 所有任务合并到主分支发布前，必须 100% 勾选的检查清单。 -->
 
-*   [ ] All Acceptance Criteria (AC) passed.
-*   [ ] Unit tests written and passing (coverage > 80%).
-*   [ ] Integration tests passing.
-*   [ ] No new lint errors.
-*   [ ] Documentation updated (API docs, user manual).
-*   [ ] Performance benchmarks met (if applicable).
-*   [ ] Security audit passed (if applicable).
-*   [ ] User acceptance testing (UAT) completed.
+*   [ ] 所有的验收标准 (AC) 全部测试通过。
+*   [ ] 包含足够的自动化单元测试 (行覆盖率 > 80%) 并且 CI 绿灯。
+*   [ ] 集成测试/E2E 关键路径全部顺畅。
+*   [ ] 代码 Lint 及格式化审查均无警告。
+*   [ ] 已更新相关技术文档 (如 OpenAPI 接口文档、Wiki 知识库)。
+*   [ ] 性能与安全隐患已经过 Review (若有前述相关的约束要求)。
+*   [ ] 产品验收环节 (UAT) 已通过。
 
 ---
 
-## 9. Appendix (附录) - 可选
+## 9. 附录 (Appendix) — 可选
 
-### 9.1 Glossary (术语表)
-- **[Term 1]**: [Definition]
-- **[Term 2]**: [Definition]
+### 9.1 术语表 (Glossary)
+- **[首字母缩写/术语 1]**: [明确定义，避免跨团队沟通歧义]
+- **[术语 2]**: [定义]
 
-### 9.2 References (参考资料)
-- [Link 1]
-- [Link 2]
-
-### 9.3 Change Log (变更日志)
-| Version | Date | Changes | Author |
-|---------|------|---------|--------|
-| 1.0 | 2026-01-08 | Initial version | XXX |
+### 9.2 参考资料 (References)
+- [URL 1]
+- [URL 2]
 
 ---
 
 <!-- ⚠️ CRITICAL 使用指南 -->
 <!-- 
-**PRD撰写原则 (Amazon 6-pager风格)**:
-1. **精炼至上**: 总长度最多6页（约3000-4000字）
-2. **Executive Summary < 50字**: 电梯演讲
-3. **每个User Story < 100字**: 简洁清晰
-4. **数据驱动**: 所有目标和指标必须可衡量
-5. **追溯链**: 每个User Story有唯一ID [REQ-XXX]
+**PRD 撰写原则 (精益规格要求)**:
+1. **去冗存精**: 抵制长篇大论，整个文档建议控制在阅读时间 10 分钟以内。
+2. **执行摘要 < 50字**: 用最少的话讲明白核心价值。
+3. **独立性**: User Story 粒度必须控制在"可单独交付验证"的级别。
+4. **追溯链 (Traceability)**: [REQ-XXX] 编号是神圣不可侵犯的，将贯穿架构、任务和代码。
 
 **章节使用指南**:
 - **必需章节**: 1, 2.1, 3, 4, 6, 8
 - **可选章节**: 2.3 (竞品分析), 5 (UX设计), 7 (成功指标), 9 (附录)
-- **小项目**: 可省略 2.3, 5, 9，但结构保持一致
+- **小型功能/迭代**: 可大胆删除 2.3, 5, 7, 9，保留骨架即可。
 -->

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 测试辅助: 可选
+-->