docs 目录索引

项目全部文档（设计、审计、记录、报告）都在这里。入口是 project-state.md：它的一份文档就能让没有上下文的读者（人或 AI）知道项目是什么、现在能做什么、代码从哪里进、哪些契约不能碰。

约定：叙述用中文，代码标识/路径/测试名保留英文。状态标记：[当前] 与工作树一致；[部分过时] 仍有参考价值但不能照做；[历史] 只用于理解演进；[设计] 是方案，不是现状。冲突时按 代码 > 测试 > CMake/数据 > project-state.md > 旧文档 排序。

一、先读这些

文档	状态	内容
`project-state.md`	`[当前]`	当前状态、功能地图、构建/测试、不变量、修改指南、文档索引
`update.txt`	`[当前-历史]`	中文更新日志（v0.1.7.0–v0.1.9.2，UTF-8 with BOM）。查“最近改了什么”最有用
`developer-guide.md`	`[部分过时]`	0.1.6 时代的架构/玩法指南，大结构与设计意图仍可读；平台/音频/存档细节以 `project-state.md` 为准
`implementation-guide.md`	`[部分过时]`	0.1.6 时代的渲染/rig/玩法实现记录
`android.md`	`[较新]`	Android 构建、EGL/GLES、资源/输入/存储限制，四平台复核

二、平台与引擎

文档	状态	内容
`platform-abstraction-audit.md`	`[设计+落地记录]`	跨平台现状审计与 PAL 下沉方案；开头有“落地状态”对照当前树
`superpowers/specs/2026-11-01-touch-gamepad-adaptive-layout-design.md`	`[设计]`	触摸手柄自适应布局：毫米物理尺寸、屏内/不重叠、紧凑回退

三、战斗

文档	状态	内容
`combat-system-design.md`	`[设计]`	战斗系统设计（动作框架、格挡、技能栏、远程、敌人、词缀）
`combat-e1-weapon-design.md`	`[设计+落地记录]`	战斗扩展 E1 武器系统规格；E1.1–E1.9 已落地，§2.9–§2.17 是落地记录
`combat-e2-watch-design.md`	`[设计]`	战斗扩展 E2 怀表系统规格；未落地（怀表物品/过载/4 种校准/装配面板/v11 存档）
`ai-generic-design.md`	`[设计+落地记录]`	通用 AI 框架：特征表、寻路、感官、行为、交互、能力五个子系统；AI.1–AI.3 已落地，AI.4–AI.5 未开始
`e1-gun-model-solution.md`	`[设计]`	枪械手持表现层持久方案（尺寸口径/武器帧/副把锚点）；未落地

四、建筑

文档	状态	内容
`building-model-optimization-plan.md`	`[当前]`	建筑模型优化总方案（阶段划分 + D-1~D-9 决策表）
`building-audit-baseline.md`	`[基线]`	阶段 1：29 typeId 的尺寸/部件占比/显存/每帧开销/门连通实测
`building-issues.md`	`[当前]`	阶段 2：22 条问题清单（P0×7 / P1×9 / P2×6）
`building-optimization-design.md`	`[设计]`	阶段 3：S1~S17 逐条主选/备选/取舍/影响面/回退
`building-verification-acceptance.md`	`[当前]`	阶段 4：G1~G11 验收判据、验收卡、批次追踪、实机采数模板
`building-proportion-table.md`	`[当前]`	建筑比例表（S10）；与 `tests/BuildingProportions.cpp` 的 `FamilyBand` 成对维护
`building-south-face-offset.md`	`[专题]`	建筑南面偏移的排查与结论

五、碰撞/视觉对齐

文档	状态	内容
`collision-visual-alignment-audit.md`	`[专题]`	碰撞与美术错位的审计
`collision-visual-alignment-fix.md`	`[专题]`	修复方案与实施
`collision-visual-alignment-resolution.md`	`[专题]`	分辨率与探针结论
`collision-visual-alignment-roof-overhang.md`	`[专题]`	屋顶悬挑的例外与判据

六、美术

文档	状态	内容
`deanna-art-upgrade-plan.md`	`[计划]`	Deanna 美术升级计划，不是现状
`female-body-proportions-plan.md`	`[计划]`	女性体型比例计划，不是现状
`src/graphics/CharacterRig.README.md`（在源码旁）	`[当前]`	骨骼、skin、动画、图集、外部美术、构建诊断的权威说明
`resources/assets/eraphanis/textures/world/README.md`（在资源旁）	`[当前]`	世界图集、无缝地面、gutter、细节层
`resources/audio/bgm/README.md`（在资源旁）	`[当前]`	BGM 目录的放置规则

七、记录与报告

文档	状态	内容
`maintenance-2026-11-03.md`	`[记录]`	2026-11-03 整理：清理 18 GB 构建/排查产物、版本升到 0.1.9.0、测试入口与 shader 部署修复、文档更新
`e1-fix-1.md`	`[计划+落地]`	E1 修复规划与落地记录（第 2 期）：快捷栏 armed 换手语义（存档 v11）、存档目录自检与删除/保存失败可行动报错、项目文件清理记录
`e1-report-1.md`	`[记录]`	E1 阶段改动与修复报告（第 1 期，基线 2026-11-05 未提交工作树）

说明：evidence/（仓库根，已 gitignore）存放建筑审计基线等探针产出物，被建筑文档引用，不属于 docs 正文。\n>\n> 早期专题文档里引用的 tmp_frames/… 抓帧属于当时的排查材料，已于 2026-11-03 清理（其中 290 个文件曾是提交内容）；那些引用现在只作历史记录看。

维护 docs

新增/更新文档时：

放到 docs/（除非它必须挨着被说明的资源，例如 CharacterRig.README.md）。
在上面某一节加一行，写清状态标记与一句话定位。
如果它改变了项目现状，同步 project-state.md（它有 §13 更新清单）与 update.txt。