docs: 添加文档导航索引与 features 范围声明

docs/README.md 作为顶层导航,提供阅读路径推荐(新人/策划/工程师/考古)、需求-设计对应表、边界约定、7 大子系统索引、性能目标。features/hammer-deformation-system.md 顶部加导航头,明确本文档为已交付功能说明,完整需求/设计见对应专题文档。 Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-openagent) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
2026-08-11 08:58:58 +08:00
parent ec5e7556ae
commit 68f5f91a08
2 changed files with 97 additions and 1 deletions
@@ -0,0 +1,92 @@
+# BladeSmith 文档索引
+
+BladeSmith 是基于 Unreal Engine 5.6 的真实打铁模拟游戏。本目录存放所有设计文档,按 **需求侧**(玩家/体验视角)与 **设计侧**(技术实现视角)分层组织。
+
+> 项目概述见仓库根目录 [README.md](../README.md)。
+
+---
+
+## 目录结构
+
+```
+docs/
+├── README.md                  (本文件)
+├── requirements/              需求文档(玩家视角,无代码)
+│   ├── 00-锻造系统总体需求.md
+│   └── 01~07 专题需求
+├── design/                    技术设计(算法/代码/性能)
+│   ├── 00-锻造系统总体技术架构.md
+│   └── 01~07 专题设计
+├── features/                  已交付功能说明
+│   └── hammer-deformation-system.md
+├── impl/                      实施记录(Task 清单)
+│   └── 2026-01-23-hammer-deformation-enhancement.md
+├── tests/                     测试文档
+│   └── hammer-deformation-test-results.md
+└── _archive/plans/            原始设计文档归档(2026-01 批次)
+```
+
+## 阅读路径
+
+| 角色 | 推荐阅读顺序 |
+|---|---|
+| **新人了解项目** | [requirements/00](requirements/00-锻造系统总体需求.md) → 各专题需求 → [design/00](design/00-锻造系统总体技术架构.md) |
+| **策划验收功能** | [requirements/00](requirements/00-锻造系统总体需求.md) → 对应专题需求 → [features/](features/) 已交付功能 |
+| **工程师实现** | [design/00](design/00-锻造系统总体技术架构.md) → 对应专题设计 → [impl/](impl/) 实施记录 |
+| **考古(看历史决策)** | [_archive/plans/]( _archive/plans/) 原始文档 |
+
+## 需求/设计对应表
+
+每个主题同时有"需求文档"(玩家可见行为)和"技术设计文档"(算法/代码),一一对应:
+
+| # | 主题 | 需求文档 | 技术设计文档 |
+|---|---|---|---|
+| 00 | 总体 | [requirements/00](requirements/00-锻造系统总体需求.md) | [design/00](design/00-锻造系统总体技术架构.md) |
+| 01 | 锤击形变 / 各向异性流动 | [requirements/01](requirements/01-锤击形变与刀刃形成需求.md) | [design/01](design/01-刀刃形成-各向异性流动设计.md) |
+| 02 | 表面磨损 / 无漂移采样 | [requirements/02](requirements/02-表面磨损与外观需求.md) | [design/02](design/02-表面磨损-顶点属性与无漂移采样设计.md) |
+| 03 | 网格质量 / 增量式优化 | [requirements/03](requirements/03-网格质量与性能需求.md) | [design/03](design/03-网格质量-增量式优化设计.md) |
+| 04 | 加工硬化 / 晶粒演化 | [requirements/04](requirements/04-加工硬化与晶粒演化需求.md) | [design/04](design/04-物理模拟-加工硬化与晶粒演化设计.md) |
+| 05 | 淬火退火相变 | [requirements/05](requirements/05-淬火退火相变需求.md) | [design/05](design/05-淬火退火相变系统设计.md) |
+| 06 | 应力累积 / 开裂 | [requirements/06](requirements/06-应力累积与开裂需求.md) | [design/06](design/06-应力累积系统设计.md) |
+| 07 | 疲劳 / 刀具耐久度 | [requirements/07](requirements/07-疲劳与刀具耐久度需求.md) | [design/07](design/07-疲劳与耐久度系统设计.md) |
+
+## 边界约定
+
+为保证"需求"与"设计"清晰分离:
+
+- **`requirements/` 下严禁**出现代码、UE 宏(UPROPERTY/UFUNCTION)、算法名(Laplacian/Sigmoid/PCA)、变量名、技术概念(Compute Shader/BVH/Ping-Pong)。只用玩家可感知的语言。
+- **`design/` 下聚焦**算法、公式、C++/HLSL 代码、数据结构、性能分析、调试工具。需求部分仅用 1-2 句话引用对应需求文档,不重复。
+- **`features/`** 是已交付能力的功能清单,供策划与 QA 验收。
+- **`impl/`** 是 Step-by-step 实施记录,供工程师追溯历史决策。
+- **`_archive/`** 是 2026-01 批次的原始设计文档(当时需求与设计混杂),保留作为决策考古用途,不再更新。
+
+## 7 大玩家可见子系统
+
+锻造系统要让玩家直观感知以下 7 类冶金学物理现象(详见 [requirements/00 §3](requirements/00-锻造系统总体需求.md)):
+
+1. **锤击形变与刀刃形成** — 材料优先沿最小阻力方向流动,边缘附近形成锐利刀刃
+2. **表面磨损与外观** — 锤击去锈、纹路随形变移动不漂移、大马士革花纹
+3. **网格质量(隐形)** — 连续锻打 50+ 次后刀刃仍平整无锯齿
+4. **加工硬化与晶粒演化** — 越打越硬、加热软化、晶粒影响性能
+5. **淬火退火相变** — 温度区间+冷却速率共同决定硬度/脆性,三阶段可视化
+6. **应力累积与开裂** — 不均匀形变累积应力,超阈值产生裂纹,可弯曲/扭曲/断裂
+7. **疲劳与刀具耐久度** — 反复使用累积疲劳,刀具最终可失效
+
+## 性能目标
+
+| 指标 | 目标 |
+|---|---|
+| 锤击期间帧率 | 稳定 60 FPS |
+| 单次锤击响应 | < 10 ms |
+| 总锤击开销上限 | ≤ 7 ms |
+| 单铁块顶点数 | 20-50 万(刀刃加密到 100 万/cm²) |
+| 单铁块内存 | ~30 MB |
+
+详细预算见 [design/00 §6](design/00-锻造系统总体技术架构.md)。
+
+## 维护
+
+- 新增需求 → 在 `requirements/` 下新增文档,更新本 README 的对应表
+- 新增技术决策 → 在 `design/` 下新增或更新对应专题,在 `design/00` 的子系统映射表中登记
+- 实施完成的 Task → 实施清单存入 `impl/`,功能说明存入 `features/`
+- 文档重组或重大调整 → 原 2026-01 批次文档保留在 `_archive/plans/` 不动
@@ -1,4 +1,8 @@
-# 锤击形变系统
+# 锤击形变系统(已交付功能说明)
+
+> 本文档是锤击形变系统的**功能交付说明**,描述已实现的能力、参数与使用方法。
+> 完整需求见 [requirements/01-锤击形变与刀刃形成需求.md](../requirements/01-锤击形变与刀刃形成需求.md);
+> 完整技术设计见 [design/01-刀刃形成-各向异性流动设计.md](../design/01-刀刃形成-各向异性流动设计.md)。

 ## 概述