@haaaiawd/anws 1.2.0 → 1.2.2

package/README.md

@@ -1,96 +1,265 @@
-# anws
+<div align="center">
 
-**Antigravity Workflow System** — 一条命令，将 AI 协作工作流体系注入任意项目。
+<img src="assets/logo.png" width="200" alt="Antigravity Workflow System">
 
-```
-npm install -g @haaaiawd/anws
-anws init
-```
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Target: Antigravity](https://img.shields.io/badge/Environment-Antigravity-blueviolet)](https://github.com/google-deepmind/antigravity)
+[![Vibe Coding](https://img.shields.io/badge/Vibe%20Coding-Enabled-ff69b4)](https://github.com/karpathy/vibe-coding)
+
+[English](./README.md) | [中文](./README_CN.md)
+
+</div>
 
 ---
 
-## 安装
+## ⚡ What is this?
 
-```bash
-npm install -g @haaaiawd/anws
-```
+A **structured workflow framework** for Agentic AI assistants, designed to solve the core pain points of the Vibe Coding era.
 
-需要 **Node.js ≥ 18**。
+> 💡 **TL;DR**: Stop letting AI write spaghetti code. Force it to think like an architect first.
 
----
+### 🎯 Problems We Solve
 
-## 命令
+| Pain Point             | The Problem                                                 | Our Solution                                                   |
+| ---------------------- | ----------------------------------------------------------- | -------------------------------------------------------------- |
+| **Architecture Drift** | AI generates inconsistent patterns across the same codebase | `/genesis` forces PRD & architecture design first              |
+| **Spaghetti Code**     | AI lacks project context, writes code that doesn't fit      | Tasks include constraints & acceptance criteria                |
+| **Context Amnesia**    | New session = AI forgets all previous decisions             | `.agent/rules/agents.md` + versioned docs as persistent memory |
+| **Lack of Planning**   | Vibe Coding skips design, creates tech debt                 | Mandatory design-first workflow                                |
 
-### `anws init`
+---
+
+## 🚀 Quick Start
 
-将 `.agent/` 工作流体系复制到当前项目目录。
+### Option A — npm CLI (Recommended)
 
 ```bash
-cd my-project
+npm install -g @haaaiawd/anws
+cd your-project
 anws init
 ```
 
-- **首次初始化**：直接写入所有文件，不覆盖任何已有文件。
-- **检测到冲突**：显示已存在的托管文件数量，询问是否覆盖（默认 **N**）。  
-  确认后只会覆盖 `anws` 管理的文件，你的自定义文件不受影响。
-- **非 TTY 环境（如 CI）**：检测到冲突时自动跳过，不挂起进程。
+> Requires Node.js ≥ 18.
 
-### `anws update`
+### Option B — GitHub Release
 
-将当前项目的 `.agent/` 托管文件更新到最新版本。
+Download the latest `.zip` from [Releases](https://github.com/Haaaiawd/Antigravity-Workflow-System/releases), then copy `.agent/` to your project root.
+
+### 📦 Update Existing Installation
 
 ```bash
+cd your-project
 anws update
 ```
 
-- 仅覆盖 `anws` 管理的文件，用户自定义文件完全保留。
-- 交互式确认（默认 **N**），防止误操作。
+> `anws update` overwrites all managed workflow/skill files to the latest version while **preserving** your `agents.md`.
+> If the `agents.md` template has new content, an `agents.md.new` file will be generated for you to merge manually.
 
-### 选项
+### Your First Project 🐣
 
-| 选项 | 说明 |
-|------|------|
-| `-v`, `--version` | 打印版本号 |
-| `-h`, `--help` | 显示帮助信息 |
+> **The easiest way to start**: Just run the `/quickstart` command! The AI will automatically analyze your project state and guide you step-by-step through the entire lifecycle (from `/genesis` to `/forge`).
 
----
+**Looking for inspiration? Alternative prompt**: "I want to build a web-based macOS simulator, including Dock, top bar, and several system apps. Please start this new project from scratch according to the development process."
 
-## 无 npm 安装方式
+### 🔁 Built with Itself (Dogfooding)
 
-如果你不想全局安装，也可以直接克隆仓库手动获取模板：
+Fun fact: **This very CLI tool (`anws`) was built using its own workflows!**
+We used the `/genesis` workflow to design the CLI's architecture, and the `/forge` workflow to implement the code. This project serves as a live demonstration of what Antigravity Workflow System can achieve.
 
-```bash
-# 克隆仓库
-git clone https://github.com/Haaaiawd/Antigravity-Workflow-System.git
+**Deep Thinking & Architecture Design**: The AI will automatically execute the `/genesis` workflow, thinking deeply about project requirements and producing the PRD and architecture design.
+<img src="assets/genesis工作流演示.jpg" width="800" alt="Genesis Workflow">
+
+**Interactive Requirement Alignment**: The AI will ask follow-up questions for ambiguous requirements to ensure the design matches your intuition.
+<img src="assets/与人类交互确认细节.jpg" width="800" alt="Human Interaction">
+
+**Autonomous Task Breakdown & Execution**: The AI will autonomously call necessary Skills (e.g., `spec-writer`, `task-planner`, etc.) to complete documentation and task decomposition.
+<img src="assets/自主调用skills.jpg" width="800" alt="Skills Execution">
+
+---
 
-# 将 templates/.agent/ 复制到你的项目
-cp -r Antigravity-Workflow-System/src/anws/templates/.agent/ my-project/
+## 🗺️ Decision Flowchart
+
+```
+                    ┌─────────────────┐
+                    │  Where are you? │
+                    └────────┬────────┘
+           ┌─────────────────┼─────────────────┐
+           ▼                 ▼                 ▼
+    ┌──────────┐      ┌──────────┐      ┌──────────┐
+    │   New    │      │  Legacy  │      │ Existing │
+    │ Project  │      │ Takeover │      │  Change  │
+    └────┬─────┘      └────┬─────┘      └────┬─────┘
+         │                 │                 │
+         ▼                 ▼                 ▼
+    /genesis          /scout        Tweak existing task?
+         │                 │              /         \
+         │                 │             /           \
+         └────────┬────────┘     /change       /genesis
+                  │            (modify only)  (new tasks)
+                  ▼                │            │
+           /design-system <--------+------------+
+          (optional, recommended)
+                  |
+                  v
+            /challenge
+         (design review)
+                  |
+                  v
+             /blueprint
+                  |
+                  v
+            /challenge
+          (task review)
+                  |
+                  v
+               /forge
+          (code delivery)
 ```
 
 ---
 
-## 完成初始化后
+## 🔑 Core Principles
+
+### 1. Versioned Architecture
+> Don't "fix" architecture docs. **Evolve** them.
+
+- `genesis/v1` → `genesis/v2` on major changes
+- Full traceability of decisions
+- No "it was always like this" mystery
+
+### 2. Deep Thinking First
+> AI must think before it writes.
+
+- Workflows force multi-step reasoning via `sequentialthinking`
+- `[!IMPORTANT]` blocks as guardrails
+- No shallow, scan-and-output responses
+
+### 3. Filesystem as Memory
+> Chat is ephemeral. Files are eternal.
+
+- `AGENTS.md` = AI's anchor
+- Architecture docs = persistent decisions
+- New session recovery in 30 seconds
+
+---
+
+## 📋 Workflows
+
+| Command           | Purpose                                                 | Input             | Output                                     |
+| ----------------- | ------------------------------------------------------- | ----------------- | ------------------------------------------ |
+| **`/quickstart`** | **One-command entry: orchestrates the whole lifecycle** | Auto-detected     | Full pipeline orchestration                |
+| `/genesis`        | Start from zero, create PRD & architecture              | Vague idea        | PRD, Architecture, ADRs                    |
+| `/scout`          | Analyze legacy codebase risks                           | Existing code     | Risk report, Gap analysis                  |
+| `/design-system`  | Detailed design for a system                            | Architecture      | System Design doc                          |
+| `/challenge`      | Review Design & Tasks (intelligent detection)           | Full Docs / TASKS | Challenge Report (Graded)                  |
+| `/blueprint`      | Break architecture into tasks                           | PRD + Arch        | TASKS.md (WBS)                             |
+| `/forge`          | Execute tasks — architecture to code                    | TASKS.md          | Working code, verified                     |
+| `/change`         | Tweak existing tasks (no new tasks)                     | Minor tweak       | Updated TASKS + Design files (modify only) |
+| `/explore`        | Deep research & brainstorm                              | Topic/Question    | Exploration report                         |
+| `/craft`          | Create workflows/skills/prompts                         | Creation request  | Workflow / Skill / Prompt docs             |
+
+---
+
+## 🛠️ Compatibility & Prerequisites
+
+> ⚠️ **Important**: This framework requires **Antigravity** environment with `.agent/workflows/` support.
+
+| Environment     |            Status            | Notes                          |
+| --------------- | :--------------------------: | ------------------------------ |
+| **Antigravity** |         ✅ Supported          | Full workflow + skills support |
+| Claude Code     | ❌ No native workflow support |                                |
+| Cursor          |    ❌ No workflow support     |                                |
+| GitHub Copilot  |    ❌ No workflow support     |                                |
+
+**What is Antigravity?**
+
+Antigravity is an Agentic AI coding environment that natively recognizes `.agent/workflows/` directory and can execute slash commands like `/genesis`, `/blueprint`, etc.
+
+### 🔌 Required: Sequential Thinking MCP Server
+
+This framework uses `sequentialthinking` for deep reasoning. Install it via MCP Store:
+
+1. Open **Antigravity Editor**
+2. Click **"..."** (three dots) in the sidebar → **Additional Options**
+3. Select **MCP Servers**
+4. Open **MCP Store** and search for `sequential-thinking`
+5. Click **Add** to install
+
+> 💡 Without this, workflows still work, but deep thinking features will be limited.
+
+---
+
+## ⚡ Invoke Workflows
+
+Antigravity will automatically recognize the intent and trigger the appropriate workflow. You can use it in two ways:
 
-1. 阅读 `.agent/rules/agents.md` — 了解系统的核心法则
-2. 在你的 AI 助手中执行 `/genesis` — 启动新项目的架构设计流程
+#### ⚡ Method A: Slash Protocol (Explicit)
+Directly type the command in the chat or editor to trigger the workflow.
+- `/genesis` - Start project creation
+- `/scout` - Analyze existing codebase
+- `/blueprint` - Break down architecture into tasks
+
+#### 🧠 Method B: Intent Protocol (Implicit)
+Just speak naturally. Antigravity will automatically select and run the right workflow.
+- *"I want to start a new project for a todo app"* → Triggers `/genesis`
+- *"Help me understand this legacy code and its risks"* → Triggers `/scout`
+- *"I think there are gaps in this design, challenge it"* → Triggers `/challenge`
+- *"The architecture is ready, let's plan the tasks"* → Triggers `/blueprint`
+- *"Change the error message on the login page"* → Triggers `/change` (tweak existing task)
+- *"I need to add a back-to-top button"* → Triggers `/genesis` (requires new task)
 
 ---
 
-## 冲突处理机制
+## 📁 Project Structure
+
+```
+your-project/
+├── .agent/
+│   ├── rules/
+│   │   └── agents.md          # 🧠 AI's anchor point
+│   ├── workflows/             # Workflow definitions
+│   │   ├── genesis.md
+│   │   ├── scout.md
+│   │   ├── design-system.md
+│   │   ├── challenge.md
+│   │   ├── blueprint.md
+│   │   ├── forge.md
+│   │   ├── change.md
+│   │   ├── explore.md
+│   │   └── craft.md
+│   │
+│   └── skills/            # Reusable skills
+│       ├── concept-modeler/
+│       ├── spec-writer/
+│       ├── task-planner/
+│       └── ...
+│
+└── genesis/               # Versioned architecture docs
+    ├── v1/
+    │   ├── 01_PRD.md
+    │   ├── 02_ARCHITECTURE.md
+    │   ├── 03_ADR/
+    │   ├── 05_TASKS.md
+    │   └── 07_CHALLENGE_REPORT.md
+    └── v2/                # New version on major changes
+```
 
-`anws` 维护一份静态的**托管文件清单**（34 个文件），只有清单内的文件才会被覆盖，清单外的文件永远不会被修改。
+## 🙌 Contributing
 
-这意味着你可以安全地在 `.agent/` 目录中添加自定义工作流或技能，`anws update` 不会碰它们。
+Contributions are welcome! Please read our contributing guidelines before submitting PRs.
 
 ---
 
-## 系统要求
+## 📜 License
 
-- Node.js **≥ 18.0.0**
-- 无运行时依赖
+[MIT](LICENSE) © 2026
 
 ---
 
-## License
+<div align="center">
+
+**Made for architects who code, and AIs who think.**
+
+🧠 *"Good architecture isn't written. It's designed."*
 
-MIT
+</div>

package/lib/init.js

@@ -161,7 +161,7 @@ function printNextSteps() {
   blank();
   info('Next steps:');
   info('  1. Read .agent/rules/agents.md to understand the system');
-  info('  2. Run /genesis in your AI assistant to start a new project');
+  info('  2. Run /quickstart in your AI assistant to analyze and start the workflow');
 }
 
 /**

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "@haaaiawd/anws",
-  "version": "1.2.0",
-  "description": "Antigravity Workflow System CLI — one command to install AI collaboration workflows into your project",
+  "version": "1.2.2",
+  "description": "A spec-driven workflow framework for AI-assisted development. Empowers prompt engineers to build production-ready software through structured PRD → Architecture → Task decomposition. Designed for Antigravity to enforce design-first principles and prevent architectural drift in vibe coding.",
   "keywords": [
-    "ai",
-    "workflow",
-    "agent",
-    "cli",
-    "developer-tools"
+    "antigravity",
+    "agentic-ai",
+    "workflow-orchestration",
+    "spec-driven",
+    "system-architecture",
+    "vibe-coding",
+    "prompt-engineering",
+    "devops-for-ai",
+    "skills-framework"
   ],
   "homepage": "https://github.com/Haaaiawd/Antigravity-Workflow-System",
   "repository": {
@@ -30,6 +34,8 @@
   ],
   "main": "./lib/index.js",
   "scripts": {
+    "sync": "node scripts/sync-assets.js",
+    "prepublishOnly": "npm run sync",
     "test": "node --test test/**/*.test.js"
   },
   "dependencies": {}

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

@@ -1,15 +1,14 @@
-# {System Name} — 实现细节 (detail)
+# {System Name} — 实现细节 (L1)
 
-> **文件性质**: L1 实现层  
-> **对应 L0**: [`{system}.md`](./{system}.md)  
-> 本文件仅在 `/forge` 任务的 `**输入**` 字段明确引用时加载。  
-> 日常阅读、系统概览、任务规划请优先阅读 L0 层文件。
+> **文件性质**: L1 实现层 · **对应 L0**: [`{system-id}.md`](./{system-id}.md)
+> 本文件仅在 `/forge` 任务明确引用时加载。日常阅读和任务规划请优先看 L0。
+> **⚠️ 孤岛检查**: 本文件各节均须在 L0 有对应超链接入口，禁止孤岛内容。
 
 ---
 
 ## 版本历史
 
-> 所有版本变更记录集中于此，不再散落在代码注释中。
+> 所有变更记录集中于此，不再散落在代码注释里。
 
 | 版本 | 日期         | Changelog |
 | ---- | ------------ | --------- |
@@ -17,28 +16,38 @@
 
 ---
 
+## 本文件章节索引
+
+|   §   | 章节                                                                 |   对应 L0 入口   |
+| :---: | -------------------------------------------------------------------- | :--------------: |
+|  §1   | [配置常量](#1-配置常量-config-constants)                             |  L0 §6 数据模型  |
+|  §2   | [完整数据结构](#2-核心数据结构完整定义-full-data-structures)         |  L0 §6 数据模型  |
+|  §3   | [核心算法伪代码](#3-核心算法伪代码-non-trivial-algorithm-pseudocode) | L0 §5 操作契约表 |
+|  §4   | [决策树详细逻辑](#4-决策树详细逻辑-decision-tree-details)            |   L0 §4 架构图   |
+|  §5   | [边缘情况与注意事项](#5-边缘情况与注意事项-edge-cases--gotchas)      |    L0 §5 / §9    |
+|  §6   | [测试辅助](#6-测试辅助-test-helpers) *(可选)*                        | L0 §11 测试策略  |
+
+---
+
 ## §1 配置常量 (Config Constants)
 
 > 所有硬编码配置、枚举映射、查找表集中放在此处。
+> **L0 对应入口**: L0 §6 末尾锚点 → *配置常量字典详见 [L1 §1]*
 
 ```python
 # ── 示例: 单位配置表 ──
-# 每行格式: UnitType: {atk, def, hp, mov, range, cost, tech, behavior, move_type}
 UNIT_CONFIG = {
-    # UnitType.WARRIOR: {...},
-    # ...
+    # UnitType.WARRIOR: {atk, def, hp, mov, range, cost, tech, behavior, move_type}
 }
 
 # ── 示例: 地形配置表 ──
 TERRAIN_CONFIG = {
     # TerrainType.PLAIN: {move_cost: 1, passable: "land", buildings: [...]}
-    # ...
 }
 
 # ── 示例: 建筑配置表 ──
 BUILDING_CONFIG = {
     # BuildingType.FARM: {cost: 5, tech: "farming", rp_bonus: 1}
-    # ...
 }
 ```
 
@@ -46,11 +55,10 @@ BUILDING_CONFIG = {
 
 ## §2 核心数据结构完整定义 (Full Data Structures)
 
-> 包含方法实现的完整类定义（L0 层只放无方法的属性声明）。
+> 含方法体的完整类定义。L0 层只放属性声明和方法签名（`def foo(): ...`）。
+> **L0 对应入口**: L0 §6.1 末尾锚点 → *完整方法实现详见 [L1 §2]*
 
 ```python
-# ── 示例: 完整类定义（含方法） ──
-
 @dataclass
 class ExampleEntity:
     id: str
@@ -58,7 +66,7 @@ class ExampleEntity:
 
     def some_method(self) -> bool:
         """方法说明"""
-        # 完整逻辑...
+        # 完整实现逻辑
         pass
 ```
 
@@ -67,42 +75,30 @@ class ExampleEntity:
 ## §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
-> ```
+> | 函数体估计 **> 15 行** | 短函数从 L0 操作契约表已可理解 |
+> | 含**不明显的业务规则** | 伤害公式、状态机分支、复杂校验 |
+> | 含**多步骤副作用链** | A→检查→B→更新C→触发D，顺序不可颠倒 |
+> | **同事看签名猜不出实现** | 函数名+参数已能清楚表达意图则不需要 |
 
-每个小节对应 L0 操作契约表格中的一行，提供完整函数体。
+每个小节对应 L0 §5 操作契约表的一行，提供完整函数体。
 
 ### §3.1 {操作名称}
 
-**对应契约**: L0 §{章节} 操作契约表 — `{function_name}()`  
-**准入理由**: {为什么这个函数需要伪代码，满足了哪条准入条件}
+**对应契约**: L0 §5.1 — `{function_name}()`
+**准入理由**: {满足了哪条准入条件}
 
 ```python
-def function_name(param1: Type, param2: Type, ...) -> ReturnType:
+def function_name(param1: Type, param2: Type) -> ReturnType:
     """
     函数说明。
-    
+
     前置条件:
     1. ...
-    
+
     副作用:
     - ...
     """
@@ -110,37 +106,23 @@ def function_name(param1: Type, param2: Type, ...) -> ReturnType:
     pass
 ```
 
-**关键设计注意事项**:
-- 注意点1 (如: 深拷贝、竞争条件、顺序依赖等)
-
----
-
-### §3.2 {操作名称}
-
-```python
-# ...
-```
+> **注意事项**: {深拷贝 / 竞争条件 / 顺序依赖等关键陷阱}
 
 ---
 
 ## §4 决策树详细逻辑 (Decision Tree Details)
 
-> 对应 L0 层 Mermaid 决策树的文字展开 + 完整伪代码。
+> 对应 L0 Mermaid 决策图的文字展开 + 完整伪代码。
+> **L0 对应入口**: L0 §4 架构图注释 → *完整决策逻辑见 [L1 §4]*
 
 ### §4.1 {决策场景名称}
 
-**对应 L0 Mermaid**: `{system}.md §{章节}`
+**对应 L0 Mermaid**: `{system-id}.md §{章节}`
 
 ```python
 def plan_or_decide(...):
-    """
-    决策逻辑完整实现。
-    """
     # Step 1: 检查高优先级条件
-    # ...
-    
     # Step 2: 分支逻辑
-    # ...
     pass
 ```
 
@@ -148,17 +130,18 @@ def plan_or_decide(...):
 
 ## §5 边缘情况与注意事项 (Edge Cases & Gotchas)
 
-> 实现时必须处理的非显而易见的情况。
+> 实现时必须处理的非显而易见情况。
+> **L0 对应入口**: L0 §5 或 §9 安全性章节的锚点
 
 | 场景           | 风险       | 处理方式       |
 | -------------- | ---------- | -------------- |
 | {边缘情况描述} | {潜在 Bug} | {正确处理方式} |
 
-### §5.1 {具体边缘情况}
+### §5.1 {具体情况}
 
 ```python
-# ❌ 错误做法 (会导致什么问题)
-# cloned_unit.embarked_unit = unit.embarked_unit  # 浅拷贝导致状态污染!
+# ❌ 错误做法
+# cloned_unit.embarked_unit = unit.embarked_unit  # 浅拷贝 → 状态污染!
 
 # ✅ 正确做法
 # cloned_unit.embarked_unit = deepcopy(unit.embarked_unit) if unit.embarked_unit else None
@@ -168,31 +151,37 @@ def plan_or_decide(...):
 
 ## §6 测试辅助 (Test Helpers)
 
-> 单元测试中复用的工厂函数、fixtures 或测试场景说明。
+> 可选。单元测试中复用的工厂函数或 fixtures。
+> **L0 对应入口**: L0 §11 测试策略锚点
 
 ```python
-# 示例: 测试用工厂函数
-def make_test_unit(type=UnitType.WARRIOR, hp=10, pos=(0,0)) -> Unit:
-    """创建测试用 Unit 对象"""
+def make_test_unit(type=UnitType.WARRIOR, hp=10, pos=(0, 0)) -> Unit:
+    """创建测试用 Unit"""
     pass
 
 def make_test_world(size=8) -> World:
-    """创建测试用 World 对象"""
+    """创建测试用 World"""
     pass
 ```
 
 ---
 
-<!-- ⚠️ 使用指南
-**何时填写本文件**:
-- 触发了 R1-R5 任意一条提取规则时
-- L0 的操作契约表对应的实现需要 > 30 行伪代码时
-
-**§ 编号约定**:
-- §1 配置常量: 始终是第一节
-- §2 数据结构: 含方法的完整类
-- §3 算法伪代码: 按照函数顺序编号 (§3.1, §3.2...)
-- §4 决策树展开: 对应 L0 Mermaid 图的文字版
-- §5 边缘情况: 从文档注释中提取的 "# ⚠️ 注意" 类内容
-- §6 测试辅助: 可选
+<!-- ⚠️ AGENT 使用指南
+
+何时创建本文件: 触发 L0 拆分规则 R1-R5 任意一条时。
+  R1 单个代码块 > 30 行
+  R2 代码块总行数 > 200 行
+  R3 配置常量字典条目 > 5 个
+  R4 版本内联注释 > 5 处
+  R5 文档总行数 > 500 行
+
+孤岛检查: 本文件每新增一节，必须同步在 L0 对应位置添加超链接锚点。
+
+§ 编号约定:
+  §1 配置常量  — 始终第一节
+  §2 数据结构  — 含方法体的完整类
+  §3 算法伪代码 — 按函数顺序编号 (§3.1, §3.2 ...)
+  §4 决策树    — 对应 L0 Mermaid 图的展开
+  §5 边缘情况  — 从代码注释中提取的 "# ⚠️ 注意" 类内容
+  §6 测试辅助  — 可选
 -->