diff --git a/AGENTS.md b/AGENTS.md index f8d4f34d..84dfeef5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,41 +12,41 @@ ## Engine Version Reference -@design/dev/engine-reference/godot/VERSION.md +@design/engineering/engine-reference/godot/VERSION.md ## 运行与验证（工作目录 = 含 project.godot 的切片目录） - **交付前验收 = 跑 `tools/run_all_gates.sh`，按本批改动域选档（`--code` 只跑代码域／`--docs` 只跑文档域／不带参数＝两域全量），所选域全绿才合回 master**——它是全部验证闸的唯一入口与唯一清单，**域划分也只写在它这一个地方**，闸件增减与分域调整都只改它，文档禁另列清单。一次改动同批混触 `game/` 与文档面时跑全量档。跑完写回执 `game/tests/.gates/receipt.json`（含 `domain` 字段），合回时由 worktree-guard 按 diff 路径推出该验哪个域再校验回执（缺回执／quick 模式／回执 commit ≠ HEAD／域不覆盖本次改动／含新增红，五况一律拦截） - 单件直跑（调试期最窄确认用，**不构成验收**）：系统级断言面 `python tools/run_smoke.py`（名带 smoke 但不止存活检查，术语见 `game/tests/README.md`）· 场景探针 `…console.exe --headless --path . res://smoke/ui_probe.tscn` · 单元 `… --script res://tests/run_all.gd` - 调参批量：`--script res://smoke/adventure_monte_carlo.gd`（全冒险期望）· `res://smoke/reward_expectation.gd`（奖励期望）；通关率/难度类测量一律走全冒险 -- 数值验证：`python tools/balance_verifier.py`（采集端 `res://smoke/verifier_batch.gd`，报告落 `design/qa/`） +- 数值验证：`python tools/balance_verifier.py`（采集端 `res://smoke/verifier_batch.gd`，报告与原始数据落 `sim-data/`） - 熵增闸（新类别 = 同批修订 Project Layout + 白名单）：`python tools/repo_structure_audit.py` ## Project Layout - `design/gdd/` — 现行设计文档树（根索引 `02-系统清单.md`，文档增删必须同步；`gdd/ux/` 战斗画面与交互规格） -- `design/art/` — 美术纯文档（圣经/清单/提示词卡 + references/）；评估调研归 `design/research/`；不放图片 -- `design/dev/` — 工程规范（五份规约 + architecture + engine-reference） -- `design/qa/` — 验证报告 + QA 呈现产物图；`design/research/` — 调研/提案/评估/历史验收 +- `design/art/` — 美术文档（圣经/角色设计/两份清单/路径图/提示词库与生图操作单）；只放 .md 与 `references/` 参考图，审计报告与调研归 `design/research/` +- `design/engineering/` — 工程规范（五份规约 + architecture + engine-reference） +- `design/research/` — 调研/提案/评估/历史验收（中间文档暂存地，入内文件到期即死；**需求卡片不在此，落 `reports/`**）；`design/qa/` 已退役，验证截图不进 `design/`（判据见 doc-conventions §11） - `artwork/` — 在途图像素材唯一工作区（文档归文档/在途图归一处/终稿归游戏）；整目录不入 git（.gitignore 强制），收口归档 `archive/` - `game/assets/art/` — 已验收终稿（入包被游戏加载）；`game/` — 游戏工程本体（代码 + smoke/ 冒烟 + tests/ 单元集成） - `sim-data/` — 机器读数据产物；数据件不入 git（入库例外 = README+analyze.py+growth_model.py）；MC 锚与读数常驻留盘，无数值调整禁重跑 - `tools/` — python 工具脚本；`archive/` — 收口归档 zip（gitignored） -- `reports/` — 迭代批产出物（实现报告/代拍板追认单/GDD 反哺点清单）；**实现批唯一可写目录**，只放 .md，不是事实源（细则见 `reports/README.md`） -- 根目录：`roadmap.md`（里程碑＋迭代总表六列＋顶部「当前位」节＝现在做什么）、`stage.txt`/`review-mode.txt`（运行开关）；仓库根禁止再设会话状态文件（2026-10-18 用户裁，细则见 doc-conventions 第 10 节） +- `reports/` — 过程件容器：**需求卡片**（写卡段产出，实现批的输入合同）＋迭代批产出物（实现报告/代拍板追认单/GDD 反哺点清单）；**实现批唯一可写目录**，只放 .md，不是事实源（细则见 `reports/README.md`） +- 根目录：`README.md`（纯指路牌：设计/流程/当前位/待办四个链接，零规则重述）、`roadmap.md`（里程碑＋迭代总表六列＋顶部「当前位」节＝现在做什么）、`stage.txt`/`review-mode.txt`（运行开关）；仓库根禁止再设会话状态文件（2026-10-18 用户裁，细则见 doc-conventions 第 10 节） ## 规范导航（动手前先查表） | 时机 | 权威文档 | |---|---| -| 批次开工 / 流程纪律 | `design/dev/process-conventions.md`——worktree 铁律、五段流水线、批次清单、测试两入口与 MC/闸机细则、像素纪律 | -| 流水线段入口 | 技能对照——doc-design=文档设计／asset-ingest=美术录入／req-card=写卡／iter-plan=迭代编排／iter=实现（五者均装于项目 `.zcode/skills/`）；登记不立技能；格式与状态机权威=`design/dev/doc-conventions.md` §12 | -| 写代码 / 改代码前 | `design/dev/code-conventions.md`——结构/契约/语言/数值/流程五类硬纪律（反例库 = 同目录 code-conventions-cases.md） | -| 写测试 / 改测试前 | `design/dev/test-conventions.md`——探针标配 / 回归断言 / 全量验证 / 验收清单落码 / 变异验证 | -| 写文档 / 改文档前 | `design/dev/doc-conventions.md`——白话写作 / 载体分工 / 用语 / 结构骨架 / 会话记录与生命周期 | -| 概念切分与互链 | `design/dev/concept-conventions.md`——概念封装 / 跨文档引用 / 归档与事实源 | +| 批次开工 / 流程纪律 | `design/engineering/process-conventions.md`——worktree 铁律、五段流水线、批次清单、测试两入口与 MC/闸机细则、像素纪律 | +| 流水线段入口 | 技能对照——doc-design=文档设计（兼任反哺点落文）／asset-ingest=美术录入／req-card=写卡／iter-plan=迭代编排／iter=实现（五者均装于项目 `.zcode/skills/`）；登记不立技能；批后收尾与中间文档退役=batch-closure（同一目录）；格式与状态机权威=`design/engineering/doc-conventions.md` §12 | +| 写代码 / 改代码前 | `design/engineering/code-conventions.md`——结构/契约/语言/数值/流程五类硬纪律（反例库 = 同目录 code-conventions-cases.md） | +| 写测试 / 改测试前 | `design/engineering/test-conventions.md`——探针标配 / 回归断言 / 全量验证 / 验收清单落码 / 变异验证 | +| 写文档 / 改文档前 | `design/engineering/doc-conventions.md`——白话写作 / 载体分工 / 用语 / 结构骨架 / 会话记录与生命周期 | +| 概念切分与互链 | `design/engineering/concept-conventions.md`——概念封装 / 跨文档引用 / 归档与事实源 | | 系统设计 / 增删文档 | `design/gdd/02-系统清单.md`——根索引 + 中文规范名↔英文代号对照 | -| 架构（唯一事实源） | `design/dev/architecture/architecture.md`——历史决策沿革查 git commit log，不另设决策文档 | +| 架构（唯一事实源） | `design/engineering/architecture/architecture.md`——历史决策沿革查 git commit log，不另设决策文档 | | 术语与已锁数值 | 规范名与定义 = `design/gdd/术语表.md`（全库唯一对照表，仅 owner 文档可修订）；现行数值 = `game/data/tables/*.tres`；规则与取值域 = 各系统 owner 文档。冲突须显式提出，禁默默改值 | | 现在做什么 / 待办与待裁 | 根 `roadmap.md` 顶部「当前位」节＋迭代总表六列 · 待办唯一登记处 `design/gdd/06-待办清单.md` · 批次过程与结论查 git 提交信息与 `reports/` | @@ -69,7 +69,7 @@ - 文件头 = `##` 文档注释，介绍本模块，≤8 行两类白名单（①职责摘要 ②使用约束；禁一切文档反向链接；code-conventions §1.4.1，规范权威 = Google pyguide §3.8 + PEP 257；机器闸 tools/audit_file_headers.py） - 数值单一事实源——玩法数值只存 `data/tables/`（.tres）经 ConfigDB 单点读取；禁数值字面量与自建 `load()` 表路径 - RNG 单点——禁 `randomize()`/自建 RandomNumberGenerator，随机只经 `RngService` 统一流 -- 架构事实唯一源——架构事实只认 `design/dev/architecture/architecture.md`；禁立第二架构文档或决策文档体系，历史决策记录只进 git commit log +- 架构事实唯一源——架构事实只认 `design/engineering/architecture/architecture.md`；禁立第二架构文档或决策文档体系，历史决策记录只进 git commit log - Core 层零 UI 依赖——完整战斗必须可 `--headless --script` 跑通；fail-fast——数据校验错误一律致命中止，无软回退 - spec-AC 一致性——规约与验收标准不得在同一输入上给出不同答案；评审隔离——`/design-review` 必须独立会话跑（与 `/design-system` 隔离） - 像素结构件——先抄后造、验收写成像素级判据、±1px 坐标推导（process-conventions 第 7 节） diff --git a/README.md b/README.md new file mode 100644 index 00000000..c9ee03ea --- /dev/null +++ b/README.md @@ -0,0 +1,12 @@ +# Dungeon Sweeper（扫雷 × 自动战斗 闯关 Roguelike） + +扫雷推理层＋自动战斗结算的两段式回合 Roguelike。个人开发，Godot 4.7 · GDScript。 + +本 README 只是路牌——不重述任何规则，想知道什么去唯一权威处： + +| 想知道 | 去看 | +|---|---| +| 这个游戏设计成什么样 | [design/gdd/02-系统清单.md](design/gdd/02-系统清单.md)（GDD 根索引） | +| 开发流程怎么走（五段流水线/批次纪律/验收闸） | [design/engineering/process-conventions.md](design/engineering/process-conventions.md)＋[AGENTS.md](AGENTS.md) 规范导航表（每段一个技能入口） | +| 现在做什么 | [roadmap.md](roadmap.md) 顶部「当前位」节 | +| 待办与待裁 | [design/gdd/06-待办清单.md](design/gdd/06-待办清单.md) | diff --git a/design/art/art-assets-checklist.md b/design/art/art-assets-checklist.md index a1cad699..fb18c2f6 100644 --- a/design/art/art-assets-checklist.md +++ b/design/art/art-assets-checklist.md @@ -11,7 +11,7 @@ | 渠道 | 出什么 | 先例 | |---|---|---| | ♻ **素材站复用（轻改）** | UI 九宫格面板与按钮、字体、通用粒子与光效、通用图标、无缝纹理底噪 | 无（2026-09-23 本批立渠道）；来源偏好 CC0（如 Kenney 全站、OpenGameArt 标 CC0 件、itch.io 免费包） | -| ✦ **ComfyUI（用户自跑）** | 角色、插画级素材；每个敌种/主角建议出 **2–3 版候选**供裁决，不直接出终稿 | 主角站姿样张（2026-09-16 脚本管线产物，源文件已清理）；提示词规格卡 comfyui-prompts.md **v2.0 已重生成**（2026-09-22，美术圣经 §5 落地后正序重生；v1.0 移除决策归状态记录 125） | +| ✦ **ComfyUI（用户自跑）** | 角色、插画级素材；每个敌种/主角建议出 **2–3 版候选**供裁决，不直接出终稿 | 主角站姿样张（2026-09-16 脚本管线产物，源文件已清理）；提示词规格卡 art-prompts.md **v2.0 已重生成**（2026-09-22，美术圣经 §5 落地后正序重生；v1.0 移除决策归状态记录 125） | | ⚙ **脚本管线（代理出）** | 图标、格面、样张类精度资产 | 格面占位渲染与程序化徽标（现行） | **通用规格纪律**： @@ -59,7 +59,7 @@ ## 2. P1 —— 角色级（样张通过后开工，ComfyUI） -> 提示词规格卡 comfyui-prompts.md 已于 2026-09-22 按「圣经 §5 落地后重生成」拍板重写为 **v2.0**（主角三态+八敌种，逐资产自包含完整提示词，整段可直贴）；v1.0 移除决策归状态记录 125 完成登记（production/session-state/active.md）。 +> 提示词规格卡 art-prompts.md 已于 2026-09-22 按「圣经 §5 落地后重生成」拍板重写为 **v2.0**（主角三态+八敌种，逐资产自包含完整提示词，整段可直贴）；v1.0 移除决策归状态记录 125 完成登记（production/session-state/active.md）。 ### 2.1 主角战斗小人 diff --git a/design/art/art-bible.md b/design/art/art-bible.md index 6b195792..c402355c 100644 --- a/design/art/art-bible.md +++ b/design/art/art-bible.md @@ -485,7 +485,7 @@ - **显示档登记例外(2026-10-06 UI 设计对齐批 P6 甲——64 源 0.5×,待素材批消除)**:柜台四枚 `icon_forge/workshop/atlas/keystone`(64×64 源)显示档统一 **32px = 0.5×**;状态九枚(32×32 源)mini(站桩)档 **16px = 0.5×**。两处均系「显示尺寸侧唯一可调、素材一字节禁改」红线下的人工检整数半倍档,登记为**待消除例外**——素材批出 32px 源后回归 1×。常规档显示一律 1×(状态九枚 32px、手绘十枚 20px/40px 双档、BCard 图标槽 40px=2×)。 - **乙类·角色与单位精灵**(有机形体、非文字):允许运行时非整数倍缩放(NEAREST 过滤不变),容忍轻度像素宽窄不均;判据 = 实机目检,可感不适即回整数档。乙类今后免逐案豁免(豁免蔓延断根)。 - **站桩立绘槽位=高定宽随(2026-10-04 原型审计教训落规)**:立绘/精灵槽位只定「高度的整数倍档」,宽度随源图宽高比自适应——**禁止把全部立绘塞进统一方框强拉**(纵横倍率必须恒等)。实例=UI 原型 88×92 方框把 23×48 地精源横拉 3.83×/纵拉 1.92×、26×48 熊地精 3.38×/1.92× 压扁发花,46×48 主角近方恰等比故独活——方框是按主角比例定的,窄条生物(细长本体裁掉透明边)进主角的框必变形。乙类的非整数豁免只覆盖**等比**缩放,不含纵横异倍变形。 - - **1920×1080 档策略(2026-09-30 三裁决案甲落定——三案呈报见 design/qa/m3-iter9-t8-rulings-2026-09-30.md)**:全局等比(stretch=canvas_items+aspect **keep**)——16:10 设计在 16:9 窗口=等比 1.35×+左右黑边各 ~96px,构图与 1280×800 基准档完全一致(逻辑布局 1920/1280 逐键一致实测);甲类 1.35 非整数缩放例外注记:轻度宽窄不均系本档位接受代价(像素游戏 shipped 常态),实机目检可感不适→回乙案(1920 独立 2× 基准)重议;乙类同前款。 + - **1920×1080 档策略(2026-09-30 三裁决案甲落定——三案呈报原件已随中间文档退役，删除批见 commit 8e02dcf0)**:全局等比(stretch=canvas_items+aspect **keep**)——16:10 设计在 16:9 窗口=等比 1.35×+左右黑边各 ~96px,构图与 1280×800 基准档完全一致(逻辑布局 1920/1280 逐键一致实测);甲类 1.35 非整数缩放例外注记:轻度宽窄不均系本档位接受代价(像素游戏 shipped 常态),实机目检可感不适→回乙案(1920 独立 2× 基准)重议;乙类同前款。 - **画布基准(2026-09-23 用户暂定值)**: - **主角人设原图 = 48×72**(1× 基准,暂定;与站姿降采样可读性验证一致); - **主角战斗状态图(含 B 区站桩侧向)= 48×72**(同上暂定;v1.9 待决注记「主角立绘档空缺」由此完成); @@ -498,7 +498,7 @@ - **归档纪律(2026-10-06 P0-1 用户口径写入文档)**:图片素材**不入 git 版本管理**——仓库只保留运行时引用资产(game/assets);生成链路原始产物(AI 原图/中间产物/候选版本)归档至 `archive/` 并择机上对象存储备份;主文档(圣经/GDD/清单)**禁引用 artwork/ 散文件路径**——定稿成图以 game/assets 为唯一事实源,过程稿引用一律用归档包路径或描述性出处。 - **入包与对账检查器(2026-10-06 P2 固化挂点——本批只立挂点,实现随 PRD 工具批)**:①**色板检查器**——扫描新素材色板,报新增色/近色告警/超 §4.1 上限(48)拦截,挂素材流入包步(asset-path-map §2 第 3 步);②**路径核对器**——扫描 asset-path-map 声明的全部路径,悬空/退役未清即报,随大批与审计例行跑(2026-10-06 三处悬空即此类失守);③**standee_asset_check 硬闸升级规格**(审计 §07-2/3)——按 §8.2 逐键定档校验体量与档高(现「宽 1–75」虚设区间退役)、像素域色数 ≤32、无非整数倍缩放痕迹、描边亮度达标(亮描边明度档,§8.2 描边层级);把 v3.6「高定宽随」教训变成代码闸而非文字。 - **交付格式**:PNG 透明底;动画 = 序列帧或引擎精灵表(SpriteFrames),帧尺寸恒定、横向等宽排列(候选)。 -- **命名规范(候选草案)**:`<域>_<对象键>_<状态|变体>[_<序号>].png`,全小写 snake_case;**对象键 = 数据表主键**(effect_id/reward_id/cell_type/enemy_id——图标键契约 §4.6 的文件侧延伸:资产文件名键 = 图标键,全局恒定禁运行时换图);图类型变体后缀 = board_type 键(`_dungeon`/`_underdark`/`_deep_underdark`);候选评审件与终稿分目录(`candidates/` 承载评审件)。 +- **命名规范(候选草案)**:`<域>_<对象键>_<状态|变体>[_<序号>].png`,全小写 snake_case;**对象键 = 数据表主键**(effect_id/reward_id/cell_type/enemy_id——图标键契约 §4.6 的文件侧延伸:资产文件名键 = 图标键,全局恒定禁运行时换图);图类型变体后缀 = board_type 键(`_dungeon`/`_underdark`/`_deep_underdark`);候选评审件与终稿分目录(`artwork/candidates/` 承载评审件)。 ### 8.4 帧数规格(样张 v2 冻结 2026-09-28) diff --git a/design/art/comfyui-prompts.md b/design/art/art-prompts.md similarity index 99% rename from design/art/comfyui-prompts.md rename to design/art/art-prompts.md index da3e51f0..b51a9470 100644 --- a/design/art/comfyui-prompts.md +++ b/design/art/art-prompts.md @@ -9,10 +9,10 @@ ## 0. 使用流程(五步) 1. **出图**:按下面卡片把正向/负向提示词粘进生图渠道的提示词栏(**渠道 = 远程对话式生图为主,本地 ComfyUI 为备选**——2026-10-06 拍板;对话操作纪律见 [remote-gen-prompts](remote-gen-prompts.md)),每个资产出 **2–3 版候选**(建议固定 3 个 seed 连拍,便于横评)。 -2. **入库**:候选原图(带底)放 `design/art/candidates/<资产名>/`,文件名 `v1.png / v2.png / v3.png`。这个目录只存候选,不进引擎。 +2. **入库**:候选原图(带底)放 `artwork/candidates/<资产名>/`,文件名 `v1.png / v2.png / v3.png`。这个目录只存候选,不进引擎。 3. **裁决**:你按 §4 验收速查预筛,挑出每一资产的入围候选拍板。 4. **后处理**:喊我一声,脚本管线代跑——去底转透明、最近邻降采样到目标尺寸、色板量化、四联底测试条(掩尘底/裸土底/暗底/灰度)。 -5. **转正**:终稿从 candidates 转入切片资产目录,随表现层升级批接线;清单状态列改「已交付」。 +5. **转正**:终稿从 `artwork/candidates/` 转入切片资产目录,随表现层升级批接线;清单状态列改「已交付」。 **出图通道(2026-09-23 定稿)**:线上 API,用户自跑——本地 ComfyUI 生图路线已经用户拍板**彻底关闭**(母版工作流/像素 LoRA/Z-Image 模型已清退,不留复活预案,本卡不依赖任何本地管线)。 diff --git a/design/art/art-status-checklist.md b/design/art/art-status-checklist.md index 40c8196a..e85c4f33 100644 --- a/design/art/art-status-checklist.md +++ b/design/art/art-status-checklist.md @@ -17,8 +17,8 @@ | 素材 | 状态 | 需求文档 | |---|---|---| -| 主角战斗小人（待机/攻击/受击三态） | ✅ B区站桩三态全接（2026-09-29 迭代 6 T3：normal/attack/hit 48px 档入包+挂事件切换+结算回 idle，短驻自回；棋盘 1.5×/脚锚25%/椭圆影在役不变；hit 态源=new-hit.pxo 已程序导出） | [character-design](character-design.md) + [comfyui-prompts](comfyui-prompts.md) §2 | -| 八敌种形象（L2 熊地精=bugbear 复用，不单列） | ✅ B区站桩八敌真图服役（2026-09-29 迭代 6 T1/T2：pixel-1 源→48px 档统一比例/底中锚/众数投票降采样，character_enemy_<键>.png 按常量入位，字形回退退役为缺位兜底；素材不入 git 本地在盘）。**2026-10-06 v3.7 定档批注记**：八敌源档已定（36–94，art-bible §8.2），旧统一 48 档在役过渡，新档重产落位归 PRD（tools/pixelize_candidates.py `STANDEE_TIER_H` 已改，产出与定档总图一致） | [art-bible](art-bible.md) §5 + [comfyui-prompts](comfyui-prompts.md) §3 | +| 主角战斗小人（待机/攻击/受击三态） | ✅ B区站桩三态全接（2026-09-29 迭代 6 T3：normal/attack/hit 48px 档入包+挂事件切换+结算回 idle，短驻自回；棋盘 1.5×/脚锚25%/椭圆影在役不变；hit 态源=new-hit.pxo 已程序导出） | [character-design](character-design.md) + [art-prompts](art-prompts.md) §2 | +| 八敌种形象（L2 熊地精=bugbear 复用，不单列） | ✅ B区站桩八敌真图服役（2026-09-29 迭代 6 T1/T2：pixel-1 源→48px 档统一比例/底中锚/众数投票降采样，character_enemy_<键>.png 按常量入位，字形回退退役为缺位兜底；素材不入 git 本地在盘）。**2026-10-06 v3.7 定档批注记**：八敌源档已定（36–94，art-bible §8.2），旧统一 48 档在役过渡，新档重产落位归 PRD（tools/pixelize_candidates.py `STANDEE_TIER_H` 已改，产出与定档总图一致） | [art-bible](art-bible.md) §5 + [art-prompts](art-prompts.md) §3 | | 意图准备动画三档 | ◐ | [art-bible](art-bible.md) §4.6.4 | ## P2 图标与格面（可与样张并行） diff --git a/design/art/asset-path-map.md b/design/art/asset-path-map.md index 037fa939..42262455 100644 --- a/design/art/asset-path-map.md +++ b/design/art/asset-path-map.md @@ -7,19 +7,19 @@ | 路径 | 角色 | 入 git | 游戏运行时引用 | |---|---|---|---| -| `design/art/candidates/**` | 设计侧源档（母版 PNG/.pxo/GIF/对比图/验收留底）——**素材的原产地与档案库，游戏禁直接引用**。**目录按需创建**（首批候选入库时建，2026-10-06 对账注：当前两 worktree 均未建立，非路径作废） | 否（`.gitignore` 三行规则；`*.md` 指引例外） | **禁**（res:// 路径禁指 candidates） | -| `game/assets/art/**` | **游戏运行时素材唯一落地处**（res://assets/art/...）——定稿素材从 candidates 拷贝入此，改名按圣经 §8.3 | 否（untracked，勿 git add；worktree 间需脚本拷贝同步） | **唯一合法引用源** | +| `artwork/candidates/**` | 候选原图与母版源档（PNG/.pxo/GIF/对比图/验收留底）——**素材的原产地，游戏禁直接引用**；随 `artwork/` 整目录不入 git（`design/art/candidates/` 已作废，路径列入熵增闸退役名单） | 否（`.gitignore` 三行规则；`*.md` 指引例外） | **禁**（res:// 路径禁指 candidates） | +| `game/assets/art/**` | **游戏运行时素材唯一落地处**（res://assets/art/...）——定稿素材从 `artwork/candidates/` 拷贝入此，改名按圣经 §8.3 | 否（untracked，勿 git add；worktree 间需脚本拷贝同步） | **唯一合法引用源** | | `game/assets/ui/icons/**` | UI 图标（状态图标批特例——唯一已提交入 git 的素材目录） | **是**（2026-09-24 批特例） | 是 | | `artwork/mockups/**` | 混合样张/版式对比图（设计评审产物，非游戏素材；样张 v3、关卡地图样张等实存于此）——2026-10-06 对账更正：原写的 `production/mockups/**` 系废路径 | 否 | 禁 | ## 2. 素材流（新素材批标准路径） -1. **产出/候选**：candidates 对应子目录（如 `hero-idle/`） +1. **产出/候选**：`artwork/candidates/` 对应子目录（如 `hero-idle/`） 2. **验收定稿**：用户拍板（候选目录留档不动） 3. **入包**：拷贝 → `game/assets/art/<语义子目录>/`，改名 `§8.3` 域键式（如 `character_hero_portrait.png`） 4. **接线**：代码 `res://assets/art/...` 引用（路径常量单点归 `UiKit.TEX_*`）；装载一律 `UiKit.load_tex`（exists 守卫——素材不入 git，缺位树回退），**禁 preload** 5. **提交**：只提交代码/文档；PNG 与 `.import`（全局忽略）均不入 git -6. **整理（2026-10-06 P2-1 固化段——脚本链第四段：生成→验证→整理→入包）**：定稿入包后当批清 candidates 子目录——保留**定稿源 + 最相邻候选 2 版**（默认策略，可按资产调整），其余打包归 `archive/`；非素材残留（.url/.ogg/.ai/.swf 等）剔出；批量执行一律 **dry-run 清单先行**，经用户确认再动文件（2026-10-06 用户惯例） +6. **整理（2026-10-06 P2-1 固化段——脚本链第四段：生成→验证→整理→入包）**：定稿入包后当批清 `artwork/candidates/` 子目录——保留**定稿源 + 最相邻候选 2 版**（默认策略，可按资产调整），其余打包归 `archive/`；非素材残留（.url/.ogg/.ai/.swf 等）剔出；批量执行一律 **dry-run 清单先行**，经用户确认再动文件（2026-10-06 用户惯例） ## 3. game/assets/art 语义子目录 @@ -31,6 +31,6 @@ ## 4. 坐标/朝向等工程侧约定备查 -- 素材基准朝向：角色/铲帧一律朝**左**入库，右向=运行时 `flip_h`（镜像帧不入包，right 变体留 candidates） +- 素材基准朝向：角色/铲帧一律朝**左**入库，右向=运行时 `flip_h`（镜像帧不入包，right 变体留 `artwork/candidates/`） - 挥铲握把锚：画布 (18,12)（三帧同位——以手为圆心旋转的预烤相位） - 缩放纪律：圣经 §8.2 整数缩放为一般规则；棋盘小人 1.5× 系 2026-09-26 用户明示裁决（豁免注记归 art-bible 批另落） diff --git a/design/art/character-design.md b/design/art/character-design.md index 18244696..dfd73c33 100644 --- a/design/art/character-design.md +++ b/design/art/character-design.md @@ -1,7 +1,7 @@ # 人物设计文档(Character Design)— Dungeon Sweeper > **性质**:美术圣经 §5(角色设计)的独立承载文档——2026-09-23 抽离批自 art-bible v1.6 §5 迁出成文,动机是**人设高频改动、独立成档免动圣经**;圣经 §5 自此为引用存根指向本文件,**小节号 §5.1–§5.6 沿用不变**(跨文档引用经圣经 §5 存根仍可达,新引用直指本文件)。 -> **边界**:本文件只定角色呈现;角色承载的机制语义(护甲克制矩阵、技能与状态)以 GDD 为准(敌人系统/增益状态/战斗结算)。色彩系统、形状语言总纲引用美术圣经 [art-bible](art-bible.md) §4/§3,冲突以圣经为准。提示词执行侧(可直贴串)归 [comfyui-prompts](comfyui-prompts.md),本文件是它的规格上游。 +> **边界**:本文件只定角色呈现;角色承载的机制语义(护甲克制矩阵、技能与状态)以 GDD 为准(敌人系统/增益状态/战斗结算)。色彩系统、形状语言总纲引用美术圣经 [art-bible](art-bible.md) §4/§3,冲突以圣经为准。提示词执行侧(可直贴串)归 [art-prompts](art-prompts.md),本文件是它的规格上游。 --- diff --git a/design/art/remote-gen-prompts.md b/design/art/remote-gen-prompts.md index c34a438a..2612a874 100644 --- a/design/art/remote-gen-prompts.md +++ b/design/art/remote-gen-prompts.md @@ -1,14 +1,14 @@ # 远程生图提示词单(对话式生图操作单) -> **渠道定位(2026-10-06 拍板)**:生图渠道 = **远程对话式生图为主,本地 ComfyUI 为备选**(v2.7「彻底关闭」系当时口径,现行更正为备选);本文件是**对话操作单**(怎么开对话/贴什么参考图/怎么续写),提示词正文词库归 [comfyui-prompts](comfyui-prompts.md)——分工:词库改词库、操作单改流程,同一段正文不双处维护。 -> **出图登记义务(2026-10-06 P1-1 复现性)**:每张产出登记 **模型名 + 分辨率 + seed(可取则取)+ 对话/日期**,随候选原图同存 `design/art/candidates/<资产名>/`;缺登记的候选不入正稿遴选。 -> 开新对话出图:同一角色 2–3 版候选各开新对话(同对话续写=修图);同角色换姿势在同对话续写。分辨率开大档;候选原图存 `design/art/candidates/<资产名>/`。 +> **渠道定位(2026-10-06 拍板)**:生图渠道 = **远程对话式生图为主,本地 ComfyUI 为备选**(v2.7「彻底关闭」系当时口径,现行更正为备选);本文件是**对话操作单**(怎么开对话/贴什么参考图/怎么续写),提示词正文词库归 [art-prompts](art-prompts.md)——分工:词库改词库、操作单改流程,同一段正文不双处维护。 +> **出图登记义务(2026-10-06 P1-1 复现性)**:每张产出登记 **模型名 + 分辨率 + seed(可取则取)+ 对话/日期**,随候选原图同存 `artwork/candidates/<资产名>/`;缺登记的候选不入正稿遴选。 +> 开新对话出图:同一角色 2–3 版候选各开新对话(同对话续写=修图);同角色换姿势在同对话续写。分辨率开大档;候选原图存 `artwork/candidates/<资产名>/`。 ## 1. 主角战斗立绘 先贴基准图再发对应整段:重出攻击态=把 normal+hit 两张定稿成图都贴上当底稿(段尾 Reference fidelity 句按底稿锁死体型与形态,一或两张通吃);新候选开新对话,同对话续写=修图。 -> 旗面注意(2026-09-28 拍板脱钩):棋盘格上的封印旗=封印黑 `#000000`(旗朱→封印紫→封印黑沿革仅作用于棋盘);**人设背包旗=旗朱红矩形旗 `#C63D22`**(2026-09-28 拍板与棋盘封印色脱钩,形为矩形非三角)——参考图 normal/hit 的红旗即正确基准,段内措辞以本注记为准。 +> 旗面基准：参考图 normal/hit 的红旗即正确基准，段内措辞以 [character-design](character-design.md) §5.4 背包旗条为准（棋盘封印色与人设旗色的脱钩裁决也在那里），本单不复述色值与沿革。 ### 攻击态 diff --git a/design/dev/architecture/architecture.md b/design/engineering/architecture/architecture.md similarity index 98% rename from design/dev/architecture/architecture.md rename to design/engineering/architecture/architecture.md index df929af7..bf279d9c 100644 --- a/design/dev/architecture/architecture.md +++ b/design/engineering/architecture/architecture.md @@ -16,9 +16,9 @@ ## 引擎知识缺口摘要 -- **风险等级：MEDIUM**（2026-09-12 `/setup-engine refresh` 后由 HIGH 降级）。4.5→4.7 官方迁移指南已逐条核实并入 `design/dev/engine-reference/godot/breaking-changes.md` 与 `deprecated-apis.md`；**结论：无一条破坏 GDD 已锁架构契约**（autoload 体系 / .tres 单一事实源 / Callable 信号 / int64 二补数 / headless SceneTree 协议均不受影响）。 +- **风险等级：MEDIUM**（2026-09-12 `/setup-engine refresh` 后由 HIGH 降级）。4.5→4.7 官方迁移指南已逐条核实并入 `design/engineering/engine-reference/godot/breaking-changes.md` 与 `deprecated-apis.md`；**结论：无一条破坏 GDD 已锁架构契约**（autoload 体系 / .tres 单一事实源 / Callable 信号 / int64 二补数 / headless SceneTree 协议均不受影响）。 - 写码纪律不变：不确定的 API 一律查 `docs.godotengine.org/en/4.7/` 核实后再用；4.8（dev 阶段）稳定版发布后跑 `/setup-engine refresh`。 -- 三类必须入编码纪律的引擎事实（详见 `design/dev/engine-reference/godot/current-best-practices.md`）： +- 三类必须入编码纪律的引擎事实（详见 `design/engineering/engine-reference/godot/current-best-practices.md`）： 1. **GDScript 4.7 两条语义变化**：打包数组元素赋值不再触发属性 setter；类型化返回的方法覆盖必须显式 `return`。 2. **新项目默认值已变**：stretch mode `canvas_items` / aspect `expand`（4.7）；Windows 渲染驱动 D3D12（4.6，仅 Forward+ 线）——创建 project.godot 后逐项核对。 3. `Resource.duplicate(true)` 深复制不再覆盖外部子资源——D2 表资源复制语义注意。 @@ -84,7 +84,7 @@ ## 模块归属 -> 命名遵循 `design/dev/code-conventions.md`：领域命名、禁 ID 前缀（文件头注不写文档链接——「实现 GDD：xxx」一类已废止，代码↔设计追溯由 GDD 文档承担）。切片已按此规范完成领域命名批。 +> 命名遵循 `design/engineering/code-conventions.md`：领域命名、禁 ID 前缀（文件头注不写文档链接——「实现 GDD：xxx」一类已废止，代码↔设计追溯由 GDD 文档承担）。切片已按此规范完成领域命名批。 ### 基础层 diff --git a/design/dev/architecture/code-architecture.html b/design/engineering/architecture/code-architecture.html similarity index 100% rename from design/dev/architecture/code-architecture.html rename to design/engineering/architecture/code-architecture.html diff --git a/design/dev/architecture/code-architecture.json b/design/engineering/architecture/code-architecture.json similarity index 100% rename from design/dev/architecture/code-architecture.json rename to design/engineering/architecture/code-architecture.json diff --git a/design/dev/architecture/gdd-architecture.html b/design/engineering/architecture/gdd-architecture.html similarity index 100% rename from design/dev/architecture/gdd-architecture.html rename to design/engineering/architecture/gdd-architecture.html diff --git a/design/dev/architecture/gdd-architecture.json b/design/engineering/architecture/gdd-architecture.json similarity index 98% rename from design/dev/architecture/gdd-architecture.json rename to design/engineering/architecture/gdd-architecture.json index cc6af465..dabec8f7 100644 --- a/design/dev/architecture/gdd-architecture.json +++ b/design/engineering/architecture/gdd-architecture.json @@ -3,7 +3,7 @@ "diagram_type": "architecture", "meta": { "title": "Dungeon Sweeper 系统架构总图", - "output": "design/dev/architecture/gdd-architecture.html", + "output": "design/engineering/architecture/gdd-architecture.html", "quality_profile": "showcase", "locale": "zh-CN" }, diff --git a/design/dev/code-conventions-cases.md b/design/engineering/code-conventions-cases.md similarity index 100% rename from design/dev/code-conventions-cases.md rename to design/engineering/code-conventions-cases.md diff --git a/design/dev/code-conventions.md b/design/engineering/code-conventions.md similarity index 96% rename from design/dev/code-conventions.md rename to design/engineering/code-conventions.md index 738a0df5..fdee417a 100644 --- a/design/dev/code-conventions.md +++ b/design/engineering/code-conventions.md @@ -1,7 +1,7 @@ # 代码规范（Dungeon Sweeper） > 约束范围：`game/` 代码同尺度；与 AGENTS.md「硬性红线」节硬约束（数值表单点 / RNG 封闭流 / Core 零 UI / fail-fast / spec-AC 一致性）并行生效，冲突以用户裁决为准。 -> 分工：本文管结构 / 契约 / 语言 / 数值 / 流程五类；测试的编写与验收见 `design/dev/test-conventions.md`；真实反例库见同目录 `code-conventions-cases.md`（不常驻加载，对规则适用有疑义时查）。 +> 分工：本文管结构 / 契约 / 语言 / 数值 / 流程五类；测试的编写与验收见 `design/engineering/test-conventions.md`；真实反例库见同目录 `code-conventions-cases.md`（不常驻加载，对规则适用有疑义时查）。 **写任何代码前必须通读本文件。** @@ -56,7 +56,7 @@ ## 3. 测试纪律 -已独立成文：`design/dev/test-conventions.md`（探针标配 / 回归断言 / 提交前全量验证 / 验收清单落码规范 / 变异验证）。 +已独立成文：`design/engineering/test-conventions.md`（探针标配 / 回归断言 / 提交前全量验证 / 验收清单落码规范 / 变异验证）。 --- diff --git a/design/dev/concept-conventions.md b/design/engineering/concept-conventions.md similarity index 98% rename from design/dev/concept-conventions.md rename to design/engineering/concept-conventions.md index 31730389..0cceadac 100644 --- a/design/dev/concept-conventions.md +++ b/design/engineering/concept-conventions.md @@ -1,6 +1,6 @@ # 概念与引用规范（Dungeon Sweeper） -> 约束范围：设计文档的概念建模与跨文档引用。写作层（句子、结构、骨架）归 `design/dev/doc-conventions.md`；本文管概念怎么切、文档怎么互链。 +> 约束范围：设计文档的概念建模与跨文档引用。写作层（句子、结构、骨架）归 `design/engineering/doc-conventions.md`；本文管概念怎么切、文档怎么互链。 > 概念只在 owner 文档里定义一次；跨系统术语的规范名、定义与互斥关系登记在 `design/gdd/术语表.md`。某概念被谁引用，靠全仓搜索它的规范名得出，不设第二处登记表。 **写设计文档前必须通读本文。** diff --git a/design/dev/doc-conventions.md b/design/engineering/doc-conventions.md similarity index 84% rename from design/dev/doc-conventions.md rename to design/engineering/doc-conventions.md index 3e7778cd..c6321303 100644 --- a/design/dev/doc-conventions.md +++ b/design/engineering/doc-conventions.md @@ -1,7 +1,7 @@ # 文档写作规范（写文档前必读） -> **地位**：本文是文档写作的规范权威，与 `design/dev/code-conventions.md`（代码规范）对等；AGENTS.md 只留导航指针，细则以本文为准。 -> **适用范围**：`design/` 下一切现行文档与根目录 `roadmap.md`；概念建模与跨文档引用见 `design/dev/concept-conventions.md`。 +> **地位**：本文是文档写作的规范权威，与 `design/engineering/code-conventions.md`（代码规范）对等；AGENTS.md 只留导航指针，细则以本文为准。 +> **适用范围**：`design/` 下一切现行文档与根目录 `roadmap.md`；概念建模与跨文档引用见 `design/engineering/concept-conventions.md`。 ## 0. 总纲 @@ -61,12 +61,12 @@ | 规则 | 内容 | |---|---| | 树形文档体系 | 全部设计文档构成一棵树；文档增删必须同步根索引 `design/gdd/02-系统清单.md` | -| 架构事实唯一源 | `design/dev/architecture/architecture.md` 是架构事实的唯一权威（分层/模块归属/数据流/API 边界/测试与质量域）；禁建第二份架构文档；历史决策记录只进 git commit log | +| 架构事实唯一源 | `design/engineering/architecture/architecture.md` 是架构事实的唯一权威（分层/模块归属/数据流/API 边界/测试与质量域）；禁建第二份架构文档；历史决策记录只进 git commit log | | 一页纸节点 | 一节、一条规则 ≤一页纸（约 ≤80 行）；装不下就拆节 | | 一系统一文档 | 不建 analysis 推演件；两三句能说清的"为什么"直接写进设计目的或规则正文 | | 正文只写现行规则 | 禁删除线、"（作废）"、"（日期+拍板）"式注记；审计信息入对应文档附录 | -| 禁写变更记录 | 文档与代码文件内一律禁设「版本历史／修订记录／变更记录／修改记录／更新记录／更新日志」节或表格，禁逐版本叙述「改了哪些条款」；沿革与改动明细只进 git commit log。版本号可作为文档现行身份标记出现在文首状态行与正文引用中，但不得再挂变更表 | -| 后置 ≠ 删除 | P1/P2 后置内容逐条列出；复活后置项 = 修订文档，禁静默加回 | +| 正文单点维护 | 一条规则句只写在定义它的那份文档（owner 文档）；其他文档要引用时写指针或语义概括，禁复制色值、尺寸、路径等可核对的具体值——上一句管不住数值之外的双写，本句补上。豁免面 = 执行侧文件必须带字面值才能工作时（生图提示词里的十六进制色、脚本参数），转写不算双写，但该文件头部必须写明"冲突时以 owner 文档为准" | +| 禁写变更记录 | 文档与代码文件内一律禁设「版本历史／修订记录／变更记录／修改记录／更新记录／更新日志」节或表格，禁逐版本叙述「改了哪些条款」；沿革与改动明细只进 git commit log。版本号可作为文档现行身份标记出现在文首状态行与正文引用中，但不得再挂变更表 || 后置 ≠ 删除 | P1/P2 后置内容逐条列出；复活后置项 = 修订文档，禁静默加回 | **数值纪律**：正文定规则、取值域、单位；平衡值进 `data/tables/`，provisional 必须标注；已锁数值事实源 = `game/data/tables/*.tres`（现行值）与 owner 文档正文（规则、取值域、单位）。 @@ -97,7 +97,7 @@ **命名**：中文、见名知意；禁 a1_/b1_ 编号前缀；不留纯空目录。正文指代子系统一律用中文规范名；英文代号对照表见 `02-系统清单.md`，旧代号（a1–d6）仅限解读归档。 -## 7–9. 概念封装 / 引用纪律 / 归档与事实源——已独立成文 `design/dev/concept-conventions.md` +## 7–9. 概念封装 / 引用纪律 / 归档与事实源——已独立成文 `design/engineering/concept-conventions.md` ## 10. 会话状态——仓库根不设状态文件 @@ -107,7 +107,7 @@ ## 11. 文档生命周期：吸收即死 -**活文档**=唯一事实源长期维护：GDD 树、art-bible 等定稿规范、术语表、架构文档（`design/dev/architecture/architecture.md`）、本规范、06-待办清单、roadmap。**中间文档**=脚手架，寿命=迭代寿命：批需求卡片、机检/验收过程报告、调研/审计报告、模拟读数、迭代计划书、目检清单。为什么：了解游戏看 GDD，了解变更看 git；增量中间文档让版本管理失去意义，原始数据 dump 是化石不是证据。 +**活文档**=唯一事实源长期维护：GDD 树、art-bible 等定稿规范、术语表、架构文档（`design/engineering/architecture/architecture.md`）、本规范、06-待办清单、roadmap。**中间文档**=脚手架，寿命=迭代寿命：批需求卡片、机检/验收过程报告、调研/审计报告、模拟读数、迭代计划书、目检清单。为什么：了解游戏看 GDD，了解变更看 git；增量中间文档让版本管理失去意义，原始数据 dump 是化石不是证据。 | 规则 | 内容 | |---|---| @@ -118,15 +118,16 @@ | 删除不留死链 | 中间文档删除后，任何现行文档禁止再留指向它的文件路径；改指结论或提交号 | | sim-data 白名单 | 只留 README、日志、分析工具 .py、现行 MC 对拍锚、设计文档 md；可再生原始数据不入库 | | 出口清理项 | 每迭代出口检查单必含：本迭代中间产物逐份核对（结论已吸收、未决已迁移）后删除 | -| 暂存地非档案库 | `design/research/` 与 `design/qa/` 是中间文档暂存地，入内文件默认到期即死 | +| 暂存地非档案库 | 中间文档有两处暂存地，入内文件默认到期即死：`reports/`（需求卡片＋迭代产出物）、`design/research/`（调研/提案/评估/历史验收）。`design/` 各子目录不留验证截图——截图属一次性凭据，结论写进 06 或需求卡片后图像即弃（在途图放 `artwork/`，整目录不入 git）；只有需要机器逐像素比对的基线图长期入库，落 `game/tests/golden/` | +| 落档必写接收方 | 新报告落档时头部必须写明接收方——`06-待办清单.md` 第几条，或哪张需求卡片。写不出接收方的不落文件，内容在会话里交付即可 | | 迭代实现报告 | 实现批收口的迭代级报告（各卡状态/代拍板追认单/GDD 反哺点清单），属中间文档，**落 `reports/` 不落 `design/`**（2026-10-17 用户裁：实现批禁写 `design/`，`reports/` 是其唯一可写目录）：反哺点裁决落文吸收后按「证据只留最新」退役 | | 证据只留最新 | 测试证据只保留最新一次迭代或最新一轮同类审计版本；新证据落位后同批删上一份；待人清单过人闸后同规退役 | -**删除方式**：按 `design/dev/concept-conventions.md` 第 2 节删除概念 SOP 口径——先查引用面（grep 文件名于阻塞域），改写或删除指路句，再删文件，收尾跑死链检查全绿。 +**删除方式**：按 `design/engineering/concept-conventions.md` 第 2 节删除概念 SOP 口径——先查引用面（grep 文件名于阻塞域），改写或删除指路句，再删文件，收尾跑死链检查全绿。执行入口=项目技能 batch-closure（批后收尾与中间文档退役）。 ## 12. 流程文档格式 -五段流水线（登记 → 文档设计／美术设计 → 写卡 → 迭代编排 → 实现，流程纪律见 `design/dev/process-conventions.md` §2）靠流程文档运转：06-待办清单登记要做的事，roadmap 记录迭代编排结果，artwork 目录承载美术在途素材。本节是这些流程文档的格式与状态机权威，也是流水线闸（`tools/pipeline_gate.py`，自动检查 06 与 roadmap 两文件格式及互相引用的机检闸）的判据依据。 +五段流水线（登记 → 文档设计／美术设计 → 写卡 → 迭代编排 → 实现，流程纪律见 `design/engineering/process-conventions.md` §2）靠流程文档运转：06-待办清单登记要做的事，roadmap 记录迭代编排结果，artwork 目录承载美术在途素材。本节是这些流程文档的格式与状态机权威，也是流水线闸（`tools/pipeline_gate.py`，自动检查 06 与 roadmap 两文件格式及互相引用的机检闸）的判据依据。 ### 12.1 06-待办清单条目格式与状态机 @@ -157,8 +158,8 @@ 例：美术设计已闭合（样张过审、art-bible v3.x）） 双轨条目设计阶段示例：文档设计已闭合（design/gdd/systems/xxx.md v0.6）＋美术设计中 进入下游段（待写卡及之后）的前置条件——双轨：两个设计轨段都在场且都已闭合（带凭据）；单轨：本轨闭合段（带凭据）在场 -下游共用序列：待写卡 → 已写卡（design/research/ 下的卡片路径）→ 已编迭代 N → 完成即整条删除 -单轨累积示例（已编迭代）：文档设计已闭合（design/gdd/systems/xxx.md v1.2）＋已写卡（design/research/xxx.md）＋已编迭代 2 +下游共用序列：待写卡 → 已写卡（reports/ 下的需求卡片路径）→ 已编迭代 N → 完成即整条删除 +单轨累积示例（已编迭代）：文档设计已闭合（design/gdd/systems/xxx.md v1.2）＋已写卡（reports/需求卡片-xxx.md）＋已编迭代 2 ``` 凭据括号内禁用＋号——＋只作状态段连接符，凭据内需要并列多项时用顿号（如上例「样张过审、art-bible v3.x」），用＋会被流水线闸误判为状态段。已编迭代 N 段的交叉核依据=同状态行内「已写卡」段括号里的卡片路径。 diff --git a/design/dev/engine-reference/godot/VERSION.md b/design/engineering/engine-reference/godot/VERSION.md similarity index 100% rename from design/dev/engine-reference/godot/VERSION.md rename to design/engineering/engine-reference/godot/VERSION.md diff --git a/design/dev/engine-reference/godot/breaking-changes.md b/design/engineering/engine-reference/godot/breaking-changes.md similarity index 100% rename from design/dev/engine-reference/godot/breaking-changes.md rename to design/engineering/engine-reference/godot/breaking-changes.md diff --git a/design/dev/engine-reference/godot/current-best-practices.md b/design/engineering/engine-reference/godot/current-best-practices.md similarity index 100% rename from design/dev/engine-reference/godot/current-best-practices.md rename to design/engineering/engine-reference/godot/current-best-practices.md diff --git a/design/dev/engine-reference/godot/deprecated-apis.md b/design/engineering/engine-reference/godot/deprecated-apis.md similarity index 100% rename from design/dev/engine-reference/godot/deprecated-apis.md rename to design/engineering/engine-reference/godot/deprecated-apis.md diff --git a/design/dev/process-conventions.md b/design/engineering/process-conventions.md similarity index 94% rename from design/dev/process-conventions.md rename to design/engineering/process-conventions.md index 5646a2d1..c8659157 100644 --- a/design/dev/process-conventions.md +++ b/design/engineering/process-conventions.md @@ -52,8 +52,8 @@ **完成** 10. **批末按域验收才合并**——在任务 worktree 内跑 `tools/run_all_gates.sh`，**按本批改动域选档**：本批改动触及 `game/`（游戏工程代码、测试、探针、场景）→ `--code`；不触及 `game/` 的一切改动（`design/`、根规则文件、`tools/` 工具脚本、`.zcode/` 配置等）→ `--docs`；同批混触 `game/` 与文档面 → 全量档不带参数。所选域全绿才合回 master。该脚本是全部验证闸的**唯一入口、唯一清单与唯一域划分**，闸件增减、分域调整都只改它；**本文与其他文档禁另列闸件清单**（清单散落多处正是 iter27 漏跑 `probe_gate --full` 的成因）。跑完写回执 `game/tests/.gates/receipt.json`（含 `domain` 字段），合回时由 worktree-guard 按 diff 路径推域强制校验。闸件（`tools/` 下机检脚本与闸壳）自身的改动不占合回全量——其质量义务＝落批时的变异验证（test-conventions §6），闸真崩溃时合回闸 fail-closed（跑不出回执即拦），不以合回全量为兜底 11. **合并后主区按域复跑**——合并可能引入冲突或环境差异，落回 master 后按本批改动域复跑：触及 `game/` 的批＝全量复跑（维持）；纯文档域批＝复跑文档域档（秒级），不再全量 -12. **批次完成后的登记义务**——合回 master 后按 doc-conventions §12.1 推进 06 条目状态（做完整条删除），涉及迭代编排的在 roadmap 迭代总表与顶部「当前位」节换代，跨会话教训写记忆库。批次过程与结论由 git 提交信息承载，禁止再写会话状态文件（2026-10-18 用户裁，见 doc-conventions 第 10 节）。`design/` 与根规则文件（`AGENTS.md`/`roadmap.md`）实现批禁写，见 §13 -13. **文档同步闸（2026-10-17 改口径：实现批禁写文档）**——实现批**禁写 `design/` 整个目录与根规则文件**，要往外交代的东西一律落 `reports/`：实现报告 `reports/iter-实现报告-<日期>.md`（各卡状态+实机目检总清单+遗留读数义务）、代拍板追认单 `reports/iter-代拍板-<日期>.md`、GDD 反哺点清单 `reports/iter-反哺点-<日期>.md`（每条写清哪个文件哪一节、改成什么、依据是什么）。设计权威文档（GDD/art-bible）**任何批都不直改**：用户在会话中逐点裁决后，由非迭代批（工具/规则/文档批）写入 `design/`，并把反哺条目从 `reports/` 清掉（吸收即死）。机械面文档（roadmap 行/术语表/README 工具注）同样归非迭代批在合并前更新。反哺点未落地期间相关 GDD 节视为待反哺，读前先查 `reports/` 与 06；需求卡片必列「关联文档同步面」按两层标注 +12. **批次完成后的登记义务**——合回 master 后按 doc-conventions §12.1 推进 06 条目状态（做完整条删除），涉及迭代编排的在 roadmap 迭代总表与顶部「当前位」节换代——执行入口=项目技能 batch-closure（批后收尾与中间文档退役），跨会话教训写记忆库。批次过程与结论由 git 提交信息承载，禁止再写会话状态文件（2026-10-18 用户裁，见 doc-conventions 第 10 节）。`design/` 与根规则文件（`AGENTS.md`/`roadmap.md`）实现批禁写，见 §13 +13. **文档同步闸（2026-10-17 改口径：实现批禁写文档）**——实现批**禁写 `design/` 整个目录与根规则文件**，要往外交代的东西一律落 `reports/`：实现报告 `reports/iter-实现报告-<日期>.md`（各卡状态+实机目检总清单+遗留读数义务）、代拍板追认单 `reports/iter-代拍板-<日期>.md`、GDD 反哺点清单 `reports/iter-反哺点-<日期>.md`（每条写清哪个文件哪一节、改成什么、依据是什么）。设计权威文档（GDD/art-bible）**任何批都不直改**：用户在会话中逐点裁决后，由非迭代批（工具/规则/文档批）写入 `design/`（执行入口=doc-design 技能），并把反哺条目从 `reports/` 清掉（吸收即死；退役执行=batch-closure 技能）。机械面文档（roadmap 行/术语表/README 工具注）同样归非迭代批在合并前更新。反哺点未落地期间相关 GDD 节视为待反哺，读前先查 `reports/` 与 06；需求卡片必列「关联文档同步面」按两层标注 14. **实机目检归用户，只登记不阻塞**——真人检测项登记进实现报告目检总清单与 07-体验验证清单即完成批内义务；禁把等目检当停工理由或完成前置 15. **中间产物吸收即死**——细则见 AGENTS.md 硬性红线与 doc-conventions 第 11 节 diff --git a/design/dev/test-conventions.md b/design/engineering/test-conventions.md similarity index 100% rename from design/dev/test-conventions.md rename to design/engineering/test-conventions.md diff --git a/design/gdd/06-待办清单.md b/design/gdd/06-待办清单.md index c45e60cd..de5f2bc8 100644 --- a/design/gdd/06-待办清单.md +++ b/design/gdd/06-待办清单.md @@ -1,6 +1,6 @@ # 06-待办清单 -本清单是流水线的唯一登记处：要做的事先在此登记一条，随流水线段推进改状态，做完整条删除；各系统文档的「待办」节只留一行指路存根，不再自建条目。条目格式（标题＝登记元数据，正文＝现状/缺口/归属/状态四属性）与状态机以 [doc-conventions §12.1](../dev/doc-conventions.md) 为权威。 +本清单是流水线的唯一登记处：要做的事先在此登记一条，随流水线段推进改状态，做完整条删除；各系统文档的「待办」节只留一行指路存根，不再自建条目。条目格式（标题＝登记元数据，正文＝现状/缺口/归属/状态四属性）与状态机以 [doc-conventions §12.1](../engineering/doc-conventions.md) 为权威。 #### UI 贴图重构批——营地与元进度件仍是程序化占位（2026-10-13 登记，来源=审计发现，设计面=美术轨） @@ -24,7 +24,7 @@ #### 战斗一屏样张 P0 未开工——界面成品是否过审的那把尺子还没建（2026-10-13 登记，来源=审计发现，设计面=美术轨） -**现状**：[美术圣经](../art/art-bible.md) §7.1 明文写着"程序化占位＝临时态，任何屏的终稿闸＝§1.4 整屏样张过闸；占位态禁止跨里程碑"。而 [美术素材状态清单](../art/art-status-checklist.md) 把「战斗一屏样张」这件最高优先级的素材标的是**未开始**——也就是说，**判定界面美术算不算过关的那把尺子到现在还没造出来**。2026-10-16 曾编入迭代 30 卡②（UI 呈现三卡批序位②），2026-10-17 用户裁定不满足「迭代＝代码实现批」的开发条件、剔除回待设计（理由＝样张交付物本身就是设计规格，正式字体与素材均未定稿；同日样张批开工已被用户终止）。v1.4 旧卡留 design/research/需求卡片-战斗一屏样张批-2026-10-16.md 作素材，非已写卡状态，重启不得直接开工。 +**现状**：[美术圣经](../art/art-bible.md) §7.1 明文写着"程序化占位＝临时态，任何屏的终稿闸＝§1.4 整屏样张过闸；占位态禁止跨里程碑"。而 [美术素材状态清单](../art/art-status-checklist.md) 把「战斗一屏样张」这件最高优先级的素材标的是**未开始**——也就是说，**判定界面美术算不算过关的那把尺子到现在还没造出来**。2026-10-16 曾编入迭代 30 卡②（UI 呈现三卡批序位②），2026-10-17 用户裁定不满足「迭代＝代码实现批」的开发条件、剔除回待设计（理由＝样张交付物本身就是设计规格，正式字体与素材均未定稿；同日样张批开工已被用户终止）。v1.4 旧卡留 reports/需求卡片-战斗一屏样张批-2026-10-16.md 作素材，非已写卡状态，重启不得直接开工。 **缺口**：还差「设计讨论→需求澄清→美术定稿」一轮设计（样张即设计目标图，产出尺寸档/色板/明度档清单反向给素材批），定稿后重新立卡方可开发。 @@ -211,7 +211,7 @@ **归属**：[地图战斗资源](systems/战斗循环/地图战斗资源.md)修订批（基础配比的权重覆盖语义 + GDD 修订）与[元进度](systems/跨局循环/元进度.md)（解锁容量与注入生产者）共裁；呈现面归[HUD 框架](systems/表现与支撑/HUD框架.md)与[教学引导](systems/表现与支撑/教学引导.md)顺带。 -**状态**：文档设计已闭合（八裁全落零拍板点，机制依赖面=元进度.md v1.0「冒险开始参数面与覆盖值通道」）＋已写卡（design/research/需求卡片-冒险前资源配比预设批-2026-10-04.md）（备选） +**状态**：文档设计已闭合（八裁全落零拍板点，机制依赖面=元进度.md v1.0「冒险开始参数面与覆盖值通道」）＋已写卡（reports/需求卡片-冒险前资源配比预设批-2026-10-04.md）（备选） #### GP 经济换算失衡——GP 袋面值与商店价格的换算关系复查（2026-10-07 登记，来源=审计发现，设计面=文档轨） @@ -313,7 +313,7 @@ #### 第二 / 三关棋盘观感——亮度与对比度（2026-10-13 登记，来源=playnote，设计面=双轨） -**现状**：来源＝playnote 用户试玩记录「UI 优化，第二第三关的棋盘看着太累了；不知道是因为亮度还是对比度的原因，看着非常费劲，非常不舒服」。2026-10-13 用户裁定：**这是需要做的**，且本就属版本标准的覆盖范围——[08-Alpha版本标准](08-Alpha版本标准.md)「五 · 表现」已新增「棋盘观感（第二 / 三关亮度与对比度）」行，标待做。**开工前须先定性（沿用既有裁决）**：是**素材轴**问题（棋盘瓦片与格面图标本身的明度与色相），还是 **UI 轴**问题（舞台底色与叠加层的对比关系）——两轴修法完全不同，定性错了等于白改一轮；该定性要求（原备忘 (e) 项）是本条的开工前置。2026-10-16 曾编入迭代 30 卡③（UI 呈现三卡批序位③），2026-10-17 用户裁定剔除回待设计（自身挂「素材轴/UI 轴」定性人闸＋甲/乙〔recolor/远程生图重产〕素材裁点；若裁乙，其瓦片规格依赖战斗一屏样张批的目标规格清单产出）。v1.4 旧卡留 design/research/需求卡片-二三关棋盘观感批-2026-10-16.md 作素材，非已写卡状态。与已完成注销的「呈现层残余 <4.5:1 文字位」分工：本条管**棋盘区域整体的观感**（亮度/对比度/费劲感，体感问题），彼条管**具体文字位的对比度读数**（机检可判硬指标），两条不同面不互相替代。 +**现状**：来源＝playnote 用户试玩记录「UI 优化，第二第三关的棋盘看着太累了；不知道是因为亮度还是对比度的原因，看着非常费劲，非常不舒服」。2026-10-13 用户裁定：**这是需要做的**，且本就属版本标准的覆盖范围——[08-Alpha版本标准](08-Alpha版本标准.md)「五 · 表现」已新增「棋盘观感（第二 / 三关亮度与对比度）」行，标待做。**开工前须先定性（沿用既有裁决）**：是**素材轴**问题（棋盘瓦片与格面图标本身的明度与色相），还是 **UI 轴**问题（舞台底色与叠加层的对比关系）——两轴修法完全不同，定性错了等于白改一轮；该定性要求（原备忘 (e) 项）是本条的开工前置。2026-10-16 曾编入迭代 30 卡③（UI 呈现三卡批序位③），2026-10-17 用户裁定剔除回待设计（自身挂「素材轴/UI 轴」定性人闸＋甲/乙〔recolor/远程生图重产〕素材裁点；若裁乙，其瓦片规格依赖战斗一屏样张批的目标规格清单产出）。v1.4 旧卡留 reports/需求卡片-二三关棋盘观感批-2026-10-16.md 作素材，非已写卡状态。与已完成注销的「呈现层残余 <4.5:1 文字位」分工：本条管**棋盘区域整体的观感**（亮度/对比度/费劲感，体感问题），彼条管**具体文字位的对比度读数**（机检可判硬指标），两条不同面不互相替代。 **缺口**：还差「素材轴 / UI 轴」定性设计讨论与甲/乙素材裁点裁决；素材轴若走重产，还依赖战斗一屏样张批的目标规格清单产出。 @@ -343,7 +343,7 @@ #### 立绘清晰度回退评估——是否改用高清图（2026-10-13 登记，来源=playnote，设计面=美术轨） -**现状**：来源＝playnote 用户试玩记录「现在的立绘太丑了，像素化的粒度太低了，导致根本看不清立绘；看是否可以改回用较为高清的图片？还有一个问题是大小的问题……现在地精的图片看起来比熊地精还要大，这并不合理」。2026-10-13 用户裁定：与「第二 / 三关棋盘观感」同属**美术线更新**。**两个子问题现状不同**：子问题一＝怪物大小比例不合理——**已兑现**（体量语义改生物体型〔character-design §5.2，弃强度线性映射〕＋八敌逐键定档〔art-bible §8.2〕），剩余面＝用户是否复核验收；子问题二＝像素粒度过低/是否改回高清图——**方向已裁（2026-10-14 用户裁）**：「还是像素风格立绘，但是不需要像现在太过于像素」，定性为**精细手绘像素**（不是插画、不是 HD-2D、不回退高清图；裁决录＝[美术审计-cursor会话存档](../art/美术审计-cursor会话存档-2026-10-14.md) §2.2；权威面 art-bible/character-design 口径节反哺另批），粒度问题已改派生管线（八敌源档 36–94 全过可读门槛：24 糊/32 可读/48 清楚）。[08-Alpha版本标准](08-Alpha版本标准.md) 未决项已随裁删除（2026-10-16 状态刷新批）。 +**现状**：来源＝playnote 用户试玩记录「现在的立绘太丑了，像素化的粒度太低了，导致根本看不清立绘；看是否可以改回用较为高清的图片？还有一个问题是大小的问题……现在地精的图片看起来比熊地精还要大，这并不合理」。2026-10-13 用户裁定：与「第二 / 三关棋盘观感」同属**美术线更新**。**两个子问题现状不同**：子问题一＝怪物大小比例不合理——**已兑现**（体量语义改生物体型〔character-design §5.2，弃强度线性映射〕＋八敌逐键定档〔art-bible §8.2〕），剩余面＝用户是否复核验收；子问题二＝像素粒度过低/是否改回高清图——**方向已裁（2026-10-14 用户裁）**：「还是像素风格立绘，但是不需要像现在太过于像素」，定性为**精细手绘像素**（不是插画、不是 HD-2D、不回退高清图；裁决录＝[美术审计-cursor会话存档](../research/美术审计-cursor会话存档-2026-10-14.md) §2.2；权威面 art-bible/character-design 口径节反哺另批），粒度问题已改派生管线（八敌源档 36–94 全过可读门槛：24 糊/32 可读/48 清楚）。[08-Alpha版本标准](08-Alpha版本标准.md) 未决项已随裁删除（2026-10-16 状态刷新批）。 **缺口**：还差立绘按「精细手绘像素」新口径重产的设计——整屏方向稿与地面/立绘密度同批锁（与战斗一屏样张批联动）后才可出重产工单。 @@ -479,6 +479,12 @@ ### 文档与结构 +#### game/tests/README 分级表证据落点行仍指 design/qa/（2026-10-20 登记，来源=批次移交，设计面=工程直入） + +**现状**：qa/ 目录退役批（分支 `qa-retire-20261020`，提交 897a0742）已把 13 处活指针改判到 `design/research/`、`reports/`、`sim-data/`，唯 `game/tests/README.md:81` 测试分级表 Config/Data 行的证据落点仍写 `design/qa/`（该目录本批已退役），正解＝`sim-data/`——该行是机器读数出口，与 `tools/balance_verifier.py` 的报告落点改动属同一口径。本批未顺手改：改动路径一旦落在 `game/` 前缀内，合回闸即按路径推定本批需代码域验收，而本批零代码改动（见 `.zcode/hooks/worktree-guard.sh` 推域段）；死链闸也判不出——`tools/doc_link_audit.py` 只扫 `design/gdd/`。故列为已知欠账，等下一批真改 `game/` 时一并纠正。 +**归属**：`game/tests/README.md` 测试分级表 +**状态**：待写卡（备选） + #### qa/ 实现报告收尾·孤儿遗留七项（2026-10-14 登记，来源=批次移交，设计面=工程直入） **现状**：qa 收尾批核查 iter19 系列出口报告遗留移交项时发现**不在 06 在册**的七项（acceptance-package §三.2/card0 §5.3/followup §七.3/uibackfill §6.2-4/verify §6.1/3/7）。已结案的（tree_rules 受理闭环、X/Y 双源、S1 七项违例修复、提灯目检项、tests.yml 休眠等）已在各报告标注结案证据，不入本条。七项均为挂号备查/顺路件，无排期承诺： @@ -497,7 +503,7 @@ #### 美术资产链路审计两项 P0 — 待用户裁决（2026-10-09 登记，来源=审计发现，设计面=双轨） -**现状**：**P0①（文档面）**：`design/art/art-bible.md` 第 68/527 行与 art-status-checklist 第 13 行至今仍引用已丢失的冻结样张 sample-batch-v3-final-2026-09-30.png（磁盘实测零命中），死指涉待修复。**P0②（美术面）**：主角棋盘小人未走像素管线（插值糊图），重产事项未在任何登记处在册。审计报告唯一留档＝design/art/美术资产链路审计报告-2026-10-06.html（无人指路）。裁＝修复死指涉+登记重产，或判过期随旧管线退役。2026-10-13 用户令随「UI 美化三层诊断」登记：本条属第三层「观感提升」，Alpha 阶段需完成。 +**现状**：**P0①（文档面）**：`design/art/art-bible.md` 第 68/527 行与 art-status-checklist 第 13 行至今仍引用已丢失的冻结样张 sample-batch-v3-final-2026-09-30.png（磁盘实测零命中），死指涉待修复。**P0②（美术面）**：主角棋盘小人未走像素管线（插值糊图），重产事项未在任何登记处在册。审计报告 HTML 件从未进版本库、现已删除，两项 P0 的现状以本条正文为准。裁＝修复死指涉+登记重产，或判过期随旧管线退役。2026-10-13 用户令随「UI 美化三层诊断」登记：本条属第三层「观感提升」，Alpha 阶段需完成。 **缺口**：还差用户的路线裁决（修复死指涉＋登记重产，还是判过期随旧管线退役）——裁决后文档面修复与美术重产登记各按轨推进。 @@ -539,15 +545,15 @@ **归属**：营地交互重做（数据层＋呈现层＋美术线；五卡路径见状态行，批次归属与波次由用户按工作量另裁） -**状态**：文档设计已闭合（design/research/需求澄清-营地交互重做-2026-10-18.md v1.0）＋待美术设计＋已写卡（design/research/需求卡片-存档制数据层改造批-2026-10-18.md）＋已写卡（design/research/需求卡片-主菜单三入口化批-2026-10-18.md）＋已写卡（design/research/需求卡片-选档界面新建批-2026-10-18.md）＋已写卡（design/research/需求卡片-营地场景图新建批-2026-10-18.md）＋已写卡（design/research/需求卡片-ESC浮窗与营地顶栏批-2026-10-18.md） +**状态**：文档设计已闭合（design/research/需求澄清-营地交互重做-2026-10-18.md v1.0）＋待美术设计＋已写卡（reports/需求卡片-存档制数据层改造批-2026-10-18.md）＋已写卡（reports/需求卡片-主菜单三入口化批-2026-10-18.md）＋已写卡（reports/需求卡片-选档界面新建批-2026-10-18.md）＋已写卡（reports/需求卡片-营地场景图新建批-2026-10-18.md）＋已写卡（reports/需求卡片-ESC浮窗与营地顶栏批-2026-10-18.md） #### 代码术语刷新批——禁用词全库清扫＋flag→seal 标识符重命名（2026-10-18 登记，来源=会话提及，设计面=工程直入） -**现状**：2026-10-18 用户裁定三组术语刷新（记忆 `project-terminology-rulings-20261018.md`）：①GP 是唯一正式命名，「金币」系 AI 噪音全库禁用；②「插旗」全库禁用，正式动作名=封印，「旗」概念不存在；③代码英文标识符 flag_* 全换 seal_*。另「雷格」「惩罚格」2026-10-11 已裁退役→危险格，代码域尚未执行。审计报告（`design/qa/代码术语审计报告-2026-10-18.md`）实查：game/ 代码域实测读数（2026-10-18 需求卡片 v1.4 复核；口径＝区分大小写逐处计数，命令见卡片 §2）：含 `flag` 的文件 57 个（.gd 53 ＋ .tres 4）共 617 处，剔除 `size_flags_*` 70 处（19 个文件）与 `_fatal_flag` 4 处后**净待改 543 处/42 个文件**；中文禁用词 金币 39 处、插旗 62 处、雷格 75 处、惩罚格 1 处、「旗」含复合词共 376 处。涉及核心逻辑（minesweeper_rules.gd 净 59、battle_orchestrator.gd 33、grant_segment.gd 38）、数据表（feats.tres 15、settlement.tres、action_economy.tres、reward.tres、treasure_items.tres）、呈现层（board_view.gd 23、battle_end_overlay.gd 11、shop_overlay_view.gd、legend_overlay.gd）与冒烟测试（smoke_all.gd 单文件净 156 处＝全集 29%）。订正说明：审计报告原记「game/ 约 757 处（flag_ 314 处/29 个 .gd；金币 116／插旗 210／雷格 109）」在现行代码上两种口径都复现不出：中文三词的读数属全库面（全库实测 金币 381／插旗 600／雷格 394 处），与本条的 game/ 范围混记；flag 侧则低估约一倍。逐文件读数以需求卡片 §2 为准。文档面（design/）由另批处理，本条只覆盖 game/ 代码域。 +**现状**：2026-10-18 用户裁定三组术语刷新（记忆 `project-terminology-rulings-20261018.md`）：①GP 是唯一正式命名，「金币」系 AI 噪音全库禁用；②「插旗」全库禁用，正式动作名=封印，「旗」概念不存在；③代码英文标识符 flag_* 全换 seal_*。另「雷格」「惩罚格」2026-10-11 已裁退役→危险格，代码域尚未执行。审计报告（`design/research/代码术语审计报告-2026-10-18.md`）实查：game/ 代码域实测读数（2026-10-18 需求卡片 v1.4 复核；口径＝区分大小写逐处计数，命令见卡片 §2）：含 `flag` 的文件 57 个（.gd 53 ＋ .tres 4）共 617 处，剔除 `size_flags_*` 70 处（19 个文件）与 `_fatal_flag` 4 处后**净待改 543 处/42 个文件**；中文禁用词 金币 39 处、插旗 62 处、雷格 75 处、惩罚格 1 处、「旗」含复合词共 376 处。涉及核心逻辑（minesweeper_rules.gd 净 59、battle_orchestrator.gd 33、grant_segment.gd 38）、数据表（feats.tres 15、settlement.tres、action_economy.tres、reward.tres、treasure_items.tres）、呈现层（board_view.gd 23、battle_end_overlay.gd 11、shop_overlay_view.gd、legend_overlay.gd）与冒烟测试（smoke_all.gd 单文件净 156 处＝全集 29%）。订正说明：审计报告原记「game/ 约 757 处（flag_ 314 处/29 个 .gd；金币 116／插旗 210／雷格 109）」在现行代码上两种口径都复现不出：中文三词的读数属全库面（全库实测 金币 381／插旗 600／雷格 394 处），与本条的 game/ 范围混记；flag 侧则低估约一倍。逐文件读数以需求卡片 §2 为准。文档面（design/）由另批处理，本条只覆盖 game/ 代码域。 **归属**：全工程（排雷循环/战斗循环/冒险循环/呈现层/数据表/冒烟测试均触及；主责=术语表裁定执行） -**状态**：已写卡（design/research/需求卡片-代码术语刷新批-2026-10-18.md）＋已编迭代 31 +**状态**：已写卡（reports/需求卡片-代码术语刷新批-2026-10-18.md）＋已编迭代 31 --- @@ -556,7 +562,7 @@ **现状**：2026-10-16 迭代 29 编入批（提交 `21c83f5`）认定「需求卡片写进了 roadmap 却没在 06 登记」属流程漏洞，需要补一条卡片入库纪律。该条至今在 06 清单内查无（2026-10-17 与 2026-10-18 两次全文检索零命中）。唯一记过它的地方是根目录状态文件未决面第 31 行，该文件已于 2026-10-18 用户裁废除，故改记本条防遗忘。 -**归属**：design/dev/process-conventions.md 五段流水线的登记段 +**归属**：design/engineering/process-conventions.md 五段流水线的登记段 **状态**：待裁决（这条纪律要不要立；立则写进 process-conventions） @@ -640,7 +646,7 @@ **归属**：game/ 代码与数据表（走独立 worktree 批） -**状态**：文档设计已闭合（design/gdd/systems/冒险循环/奇物.md v3.18）＋已写卡（design/research/需求卡片-凭证件裁削批-2026-10-18.md）＋已编迭代 31 +**状态**：文档设计已闭合（design/gdd/systems/冒险循环/奇物.md v3.18）＋已写卡（reports/需求卡片-凭证件裁削批-2026-10-18.md）＋已编迭代 31 --- diff --git a/design/gdd/08-Alpha版本标准.md b/design/gdd/08-Alpha版本标准.md index 152b0203..167186cc 100644 --- a/design/gdd/08-Alpha版本标准.md +++ b/design/gdd/08-Alpha版本标准.md @@ -144,7 +144,7 @@ | 棋盘瓦片与格面资源图标 | [美术圣经](../art/art-bible.md) | 在役 | | 未开格类型微光（五组色相＋明度档） | [HUD框架](systems/表现与支撑/HUD框架.md) | 在役（明度档 provisional 值登记见 art-bible 的 git 提交史，复核转正归战斗一屏样张） | | 棋盘观感（第二 / 三关亮度与对比度） | [06-待办清单](06-待办清单.md) | 待做（2026-10-16 用户令编入迭代 30，序位③） | -| 立绘清晰度回退评估（是否改用高清图） | [角色设计](../art/character-design.md) | 待做（评估已结——2026-10-14 用户裁维持像素风、升级精细手绘像素、不回退高清图，裁决录=[美术审计-cursor会话存档](../art/美术审计-cursor会话存档-2026-10-14.md) §2.2；余=立绘按新口径重产＋大小比例子题用户复核） | +| 立绘清晰度回退评估（是否改用高清图） | [角色设计](../art/character-design.md) | 待做（评估已结——2026-10-14 用户裁维持像素风、升级精细手绘像素、不回退高清图，裁决录=[美术审计-cursor会话存档](../research/美术审计-cursor会话存档-2026-10-14.md) §2.2；余=立绘按新口径重产＋大小比例子题用户复核） | | 敌人立绘（全敌种） | [角色设计](../art/character-design.md) | 在役 | | 主角立绘三态 | [角色设计](../art/character-design.md) | 在役 | | 状态图标 | [美术圣经](../art/art-bible.md) | 在役 | diff --git a/design/gdd/systems/跨局循环/生涯.md b/design/gdd/systems/跨局循环/生涯.md index 14263aab..c8ba53cc 100644 --- a/design/gdd/systems/跨局循环/生涯.md +++ b/design/gdd/systems/跨局循环/生涯.md @@ -78,7 +78,7 @@ | 期 | 内容 | 前置 | 建议窗口（候选） | |---|---|---|---| -| 期一 | 跨局汇总页 + 主菜单生涯入口落位。总局数/通关局数两个终身计数域随该批做存档 schema 迁移——**✅ 已实装（2026-10-07 迭代 18 卡④）**：汇总段六类九项+营地与系统组生涯钮+存档 v6 两终身计数域〔v5 升 v6 幂等迁移〕；闸读数与代拍板追认单见 design/qa/iter18-career-exit-report-2026-10-07.md | 提纲评审通过。实装批前置义务 = 对齐迭代 16 UI 批后的现行基线：`FS_*` 六档字号 / `TG_*` 语义色 / `BUTTON_MIN_H=40`（`ui_kit.gd:437`）/ 色板单源 / `page_shell` 模态栈纪律（`ui_kit.gd:394`）——与卡③需求卡片同款红线，本文只登记、不展开 | Alpha 后最近一个 UI 窗口 | +| 期一 | 跨局汇总页 + 主菜单生涯入口落位。总局数/通关局数两个终身计数域随该批做存档 schema 迁移——**✅ 已实装（2026-10-07 迭代 18 卡④）**：汇总段六类九项+营地与系统组生涯钮+存档 v6 两终身计数域〔v5 升 v6 幂等迁移〕；闸读数与代拍板追认单原记于该批出口报告，该件已按「吸收即死」在提交 8e02dcf0 删除，读数以本行与该批提交信息为准 | 提纲评审通过。实装批前置义务 = 对齐迭代 16 UI 批后的现行基线：`FS_*` 六档字号 / `TG_*` 语义色 / `BUTTON_MIN_H=40`（`ui_kit.gd:437`）/ 色板单源 / `page_shell` 模态栈纪律（`ui_kit.gd:394`）——与卡③需求卡片同款红线，本文只登记、不展开 | Alpha 后最近一个 UI 窗口 | | 期二 | 历史冒险回看整段：N 扩容 + 用时埋点 + 旧档摘要迁移 + 逐局列表 + 单局明细（`settlement_review_overlay.gd` 复活承接）+ 营地条带处置（P6 裁案落地） | 期一。实装批开工前须向用户呈报两件：N 终值读数（20 / 50 / 维持 10 三选一）与「用时」埋点口径（计时起点、暂停是否计入——字段级细节本文不做） | 期一落地后独立批 | | 期三 | 图鉴承接（敌人优先，范围与顺序随 P3 甲）；「见过」记账面 schema 义务随该批执行 | 期二或独立评估 | Beta 窗口候选（与教学引导同段评估——图鉴的「认得」轴与教学相关；06 教学引导节各条 2026-10-04 起已整体标 Beta 阶段） | diff --git a/design/gdd/术语表.md b/design/gdd/术语表.md index 349fb844..7e816b21 100644 --- a/design/gdd/术语表.md +++ b/design/gdd/术语表.md @@ -85,7 +85,7 @@ | 术语 | 定义 | |---|---| -| 逐需求点验收清单 | 需求卡片验证闸的必备清单：每个需求点列明测什么（具体断言或行为）/怎么测（测试落点与注入方式）/谁验（自动闸或用户目检）；查不出验收条目的需求点=卡片不成立（规矩见 req-card 技能，测试落码写法见 [code-conventions](../dev/code-conventions.md) §3.5） | +| 逐需求点验收清单 | 需求卡片验证闸的必备清单：每个需求点列明测什么（具体断言或行为）/怎么测（测试落点与注入方式）/谁验（自动闸或用户目检）；查不出验收条目的需求点=卡片不成立（规矩见 req-card 技能，测试落码写法见 [code-conventions](../engineering/code-conventions.md) §3.5） | | 测试方式两分法 | 能力验证与体验验证分开走（2026-10-11 用户定）：能力验证=通过调试接口直接修改游戏数据（改钥石/槽位/解锁状态等，不走正常资源积累流程）；体验验证=用户目检完整流程，登记 07-体验验证清单观测项 | ## 用语规范（2026-10-15 用户令立） diff --git a/design/qa/ui-audit-2026-10-06/demo/_map_bottom.png b/design/qa/ui-audit-2026-10-06/demo/_map_bottom.png deleted file mode 100644 index 277f904f..00000000 Binary files a/design/qa/ui-audit-2026-10-06/demo/_map_bottom.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/demo/demo_1_start.png b/design/qa/ui-audit-2026-10-06/demo/demo_1_start.png deleted file mode 100644 index cf4df806..00000000 Binary files a/design/qa/ui-audit-2026-10-06/demo/demo_1_start.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/demo/demo_2_camp.png b/design/qa/ui-audit-2026-10-06/demo/demo_2_camp.png deleted file mode 100644 index 96f25437..00000000 Binary files a/design/qa/ui-audit-2026-10-06/demo/demo_2_camp.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/demo/demo_3_settings.png b/design/qa/ui-audit-2026-10-06/demo/demo_3_settings.png deleted file mode 100644 index f4181b92..00000000 Binary files a/design/qa/ui-audit-2026-10-06/demo/demo_3_settings.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/demo/demo_4_map.png b/design/qa/ui-audit-2026-10-06/demo/demo_4_map.png deleted file mode 100644 index 52876d3d..00000000 Binary files a/design/qa/ui-audit-2026-10-06/demo/demo_4_map.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/demo/demo_5_battle.png b/design/qa/ui-audit-2026-10-06/demo/demo_5_battle.png deleted file mode 100644 index eadff07d..00000000 Binary files a/design/qa/ui-audit-2026-10-06/demo/demo_5_battle.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/demo/demo_6_bonus.png b/design/qa/ui-audit-2026-10-06/demo/demo_6_bonus.png deleted file mode 100644 index 4a486c8c..00000000 Binary files a/design/qa/ui-audit-2026-10-06/demo/demo_6_bonus.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/demo/demo_7_shop.png b/design/qa/ui-audit-2026-10-06/demo/demo_7_shop.png deleted file mode 100644 index 2e6b8bb4..00000000 Binary files a/design/qa/ui-audit-2026-10-06/demo/demo_7_shop.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/demo/demo_8_end_defeat.png b/design/qa/ui-audit-2026-10-06/demo/demo_8_end_defeat.png deleted file mode 100644 index 5c8f3596..00000000 Binary files a/design/qa/ui-audit-2026-10-06/demo/demo_8_end_defeat.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/demo/demo_8_end_victory.png b/design/qa/ui-audit-2026-10-06/demo/demo_8_end_victory.png deleted file mode 100644 index 5dd47934..00000000 Binary files a/design/qa/ui-audit-2026-10-06/demo/demo_8_end_victory.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/demo/raw/raw_1_start.png b/design/qa/ui-audit-2026-10-06/demo/raw/raw_1_start.png deleted file mode 100644 index 144f7b52..00000000 Binary files a/design/qa/ui-audit-2026-10-06/demo/raw/raw_1_start.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/demo/raw/raw_2_camp.png b/design/qa/ui-audit-2026-10-06/demo/raw/raw_2_camp.png deleted file mode 100644 index fae045a4..00000000 Binary files a/design/qa/ui-audit-2026-10-06/demo/raw/raw_2_camp.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/demo/raw/raw_3_settings.png b/design/qa/ui-audit-2026-10-06/demo/raw/raw_3_settings.png deleted file mode 100644 index 4b28d36e..00000000 Binary files a/design/qa/ui-audit-2026-10-06/demo/raw/raw_3_settings.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/demo/raw/raw_4_map.png b/design/qa/ui-audit-2026-10-06/demo/raw/raw_4_map.png deleted file mode 100644 index edecee5a..00000000 Binary files a/design/qa/ui-audit-2026-10-06/demo/raw/raw_4_map.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/demo/raw/raw_5_battle.png b/design/qa/ui-audit-2026-10-06/demo/raw/raw_5_battle.png deleted file mode 100644 index 301b601b..00000000 Binary files a/design/qa/ui-audit-2026-10-06/demo/raw/raw_5_battle.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/demo/raw/raw_6_bonus.png b/design/qa/ui-audit-2026-10-06/demo/raw/raw_6_bonus.png deleted file mode 100644 index 5b34ea50..00000000 Binary files a/design/qa/ui-audit-2026-10-06/demo/raw/raw_6_bonus.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/demo/raw/raw_7_shop.png b/design/qa/ui-audit-2026-10-06/demo/raw/raw_7_shop.png deleted file mode 100644 index 3e04bac9..00000000 Binary files a/design/qa/ui-audit-2026-10-06/demo/raw/raw_7_shop.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/demo/raw/raw_8_end_defeat.png b/design/qa/ui-audit-2026-10-06/demo/raw/raw_8_end_defeat.png deleted file mode 100644 index 5cd97a1c..00000000 Binary files a/design/qa/ui-audit-2026-10-06/demo/raw/raw_8_end_defeat.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/demo/raw/raw_8_end_victory.png b/design/qa/ui-audit-2026-10-06/demo/raw/raw_8_end_victory.png deleted file mode 100644 index fee6cc91..00000000 Binary files a/design/qa/ui-audit-2026-10-06/demo/raw/raw_8_end_victory.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/pairs/pair_1_start.png b/design/qa/ui-audit-2026-10-06/pairs/pair_1_start.png deleted file mode 100644 index 644a5931..00000000 Binary files a/design/qa/ui-audit-2026-10-06/pairs/pair_1_start.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/pairs/pair_2_camp.png b/design/qa/ui-audit-2026-10-06/pairs/pair_2_camp.png deleted file mode 100644 index 7a029376..00000000 Binary files a/design/qa/ui-audit-2026-10-06/pairs/pair_2_camp.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/pairs/pair_3_settings.png b/design/qa/ui-audit-2026-10-06/pairs/pair_3_settings.png deleted file mode 100644 index 5ae31141..00000000 Binary files a/design/qa/ui-audit-2026-10-06/pairs/pair_3_settings.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/pairs/pair_4_map.png b/design/qa/ui-audit-2026-10-06/pairs/pair_4_map.png deleted file mode 100644 index 450f4f09..00000000 Binary files a/design/qa/ui-audit-2026-10-06/pairs/pair_4_map.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/pairs/pair_5_battle.png b/design/qa/ui-audit-2026-10-06/pairs/pair_5_battle.png deleted file mode 100644 index 81081c12..00000000 Binary files a/design/qa/ui-audit-2026-10-06/pairs/pair_5_battle.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/pairs/pair_6_bonus.png b/design/qa/ui-audit-2026-10-06/pairs/pair_6_bonus.png deleted file mode 100644 index a573ca41..00000000 Binary files a/design/qa/ui-audit-2026-10-06/pairs/pair_6_bonus.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/pairs/pair_7_shop.png b/design/qa/ui-audit-2026-10-06/pairs/pair_7_shop.png deleted file mode 100644 index b552e685..00000000 Binary files a/design/qa/ui-audit-2026-10-06/pairs/pair_7_shop.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/pairs/pair_8_end_defeat.png b/design/qa/ui-audit-2026-10-06/pairs/pair_8_end_defeat.png deleted file mode 100644 index 42a3a5e9..00000000 Binary files a/design/qa/ui-audit-2026-10-06/pairs/pair_8_end_defeat.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/pairs/pair_8_end_victory.png b/design/qa/ui-audit-2026-10-06/pairs/pair_8_end_victory.png deleted file mode 100644 index ef47c706..00000000 Binary files a/design/qa/ui-audit-2026-10-06/pairs/pair_8_end_victory.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/real/real_10_legend.png b/design/qa/ui-audit-2026-10-06/real/real_10_legend.png deleted file mode 100644 index 240ed8c5..00000000 Binary files a/design/qa/ui-audit-2026-10-06/real/real_10_legend.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/real/real_11_confirm.png b/design/qa/ui-audit-2026-10-06/real/real_11_confirm.png deleted file mode 100644 index 86a59405..00000000 Binary files a/design/qa/ui-audit-2026-10-06/real/real_11_confirm.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/real/real_1_start.png b/design/qa/ui-audit-2026-10-06/real/real_1_start.png deleted file mode 100644 index 804cee6d..00000000 Binary files a/design/qa/ui-audit-2026-10-06/real/real_1_start.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/real/real_2_camp.png b/design/qa/ui-audit-2026-10-06/real/real_2_camp.png deleted file mode 100644 index cf44b227..00000000 Binary files a/design/qa/ui-audit-2026-10-06/real/real_2_camp.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/real/real_3_settings.png b/design/qa/ui-audit-2026-10-06/real/real_3_settings.png deleted file mode 100644 index 342f9a99..00000000 Binary files a/design/qa/ui-audit-2026-10-06/real/real_3_settings.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/real/real_4_map.png b/design/qa/ui-audit-2026-10-06/real/real_4_map.png deleted file mode 100644 index 9cfcec0c..00000000 Binary files a/design/qa/ui-audit-2026-10-06/real/real_4_map.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/real/real_5_battle.png b/design/qa/ui-audit-2026-10-06/real/real_5_battle.png deleted file mode 100644 index a5bb45da..00000000 Binary files a/design/qa/ui-audit-2026-10-06/real/real_5_battle.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/real/real_6_bonus.png b/design/qa/ui-audit-2026-10-06/real/real_6_bonus.png deleted file mode 100644 index a8c4f335..00000000 Binary files a/design/qa/ui-audit-2026-10-06/real/real_6_bonus.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/real/real_7_shop.png b/design/qa/ui-audit-2026-10-06/real/real_7_shop.png deleted file mode 100644 index 55c702d1..00000000 Binary files a/design/qa/ui-audit-2026-10-06/real/real_7_shop.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/real/real_8_end_defeat.png b/design/qa/ui-audit-2026-10-06/real/real_8_end_defeat.png deleted file mode 100644 index a085f343..00000000 Binary files a/design/qa/ui-audit-2026-10-06/real/real_8_end_defeat.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/real/real_8_end_victory.png b/design/qa/ui-audit-2026-10-06/real/real_8_end_victory.png deleted file mode 100644 index e8349b3b..00000000 Binary files a/design/qa/ui-audit-2026-10-06/real/real_8_end_victory.png and /dev/null differ diff --git a/design/qa/ui-audit-2026-10-06/real/real_9_debug.png b/design/qa/ui-audit-2026-10-06/real/real_9_debug.png deleted file mode 100644 index 183fd6fa..00000000 Binary files a/design/qa/ui-audit-2026-10-06/real/real_9_debug.png and /dev/null differ diff --git a/design/qa/ui-audit-vs-demo-2026-10-06.md b/design/qa/ui-audit-vs-demo-2026-10-06.md deleted file mode 100644 index 90d41538..00000000 --- a/design/qa/ui-audit-vs-demo-2026-10-06.md +++ /dev/null @@ -1,96 +0,0 @@ -# 全屏 UI 审计：实机 vs demo v2.1（2026-10-06 用户令返工） - -> 方法：实机十二屏窗口化程序截图（`game/smoke/ui_audit_probe.gd`，真实信号路径+拟真数据，1280×800 归一）× demo 原型 v2.1 浏览器现截九屏（纯净模式，与 HTML md5 `78ebbee0…` 同代现渲染）。逐屏并排图=`pairs/pair_*.png`（左实机右 demo），原图在 `real/` 与 `demo/`。 -> 输入：用户截图的红砖「放弃」按钮（第二层地图屏，特性持有态）+「底栏重设计是根本解、不是限制按钮」裁决。 - -## 逐屏差距（demo 八映射屏） - -### ① 关卡地图（pair_4_map）——用户点名核心屏，差距最大 - -| # | 差距 | demo | 实机 | -|---|---|---|---| -| 1 | **底栏** | 单条 **~85px** 紧凑亮条：头像+生命轨 \| 属性(含攻击加成副行) \| 本关加成(含持有行) \| 道具槽×2 \| **放弃=小号危险钮 ~90×38** | 亮条 + **放弃=216×50+ 危险钮**；特性持有行无限宽换行把栏爆到 130px+（用户截图实证），全栏跟着涨 | -| 2 | 底栏内容 | 五段齐装（含道具槽与持有行） | 少道具槽、少持有行展示态（特性行爆栏）；空态大片留白由放弃钮填充 | -| 3 | 底栏淡墨 | 加成副行用 wood-deep 深棕（亮板上可读） | 特性组用 WARM/WARM_SOFT 暖白系（亮板上 ≈1:1，**不可读——§7.2 违例**） | -| 4 | 背景 | 暖棕渐变聚焦、无纹理平铺 | 全屏石纹平铺（/busy，视觉焦点弱） | -| 5 | 顶栏 | 关卡头与 GP 徽章均有框板（plate 感） | 裸文本浮在纹理上 | -| 6 | 节点图 | 分支树多行多列+连线，分支结构一目了然 | 第一层为单行线性排布（深层有分支但连线视觉弱） | - -**底栏重设计草案（待用户裁决后实施，本批未动代码）**：对齐 demo——①底栏定高 88px 单条，五个信息段一行排齐；②放弃改小号危险钮（~90×38，右端）；③特性持有行限宽（固定栏宽内 1-2 行省略+tooltip 全文），杜绝爆栏；④特性组墨色换深墨系（INK_HINT/INK_TITLE）修 §7.2 违例；⑤道具槽段位预留（道具读数出口=台账 352 在册项）。 - -### ② 商店（pair_7_shop） - -demo=**全屏页**（顶部标题+刷新徽+GP 框+池源/涨价规则行）+**竖卡三张**（色带/图标/名/效/价/类型脚注）；实机=**战斗屏上的小模态**（dim 0.6）+三横行（名+现价+已购档+购买钮），标题与 HUD 行叠压。→ 即 06 在册 D1（卡片 232×352）/D2（商店全屏化）结构级差异，本次截图实证差距量级。实机独有「已购 N 档」档位语义 demo 无。 - -### ③ 三选一（pair_6_bonus） - -demo=全屏页：标题+**GP 汇总行**+三张竖卡（色带/图标/名/效/类型脚注/**选中✓**）+确认选择钮+免费选择注记。实机=战斗内浮层：标题+三行引导文字（关卡奖励点/从提升池抽…/选择一件带走）+窄条卡（~140×220，无脚注无选中✓）+无确认钮（点卡即选）。 -**新证据（E5 追认）**：demo 的「工兵爆破」卡=**紫带（magic 族）**，实机按 T4a 归 TG_AOE=粉带——demo 自身的 blast 归属与 T4a 判定相反，建议回滚 E5（blast 归回 TG_MAGIC），随用户裁决。 - -### ④ 战斗结算·胜利（pair_8_end_victory；失败态同族） - -demo=全屏 dim（仪式感）+石皮框板卡：标题+三行**两列对齐账目**（战利品/钥石/本关加成）+紧凑主钮「下一节点」；实机=**无 dim**（战斗屏裸露）+素面板+居中堆叠文本行+全宽黄钮「返回」。仪式感与排版差距大。 - -### ⑤ 战斗（pair_5_battle） - -结构对齐度高（舞台/上轮摘要行/AP·RAP 行/左栏/提示条均在位）。差距：①demo 棋盘融进深棕场景、实机=亮米大平板+四周大片空白（观感最大点）；②demo 左栏三段齐装（探险者+魔法道具槽有货+本关强化+流派件），实机左栏=探险者+秘宝空槽（强化/流派件编排不同源）；③demo 站桩带名牌与头顶 HP 轨更紧凑。 - -### ⑥ 标题屏（pair_1_start） - -1. **主操作语义反转**：demo=「继续上局」黄色主钮（有存档时继续是首动作）、「开始冒险」石钮；实机=「开始冒险」主黄钮、「继续上局」石钮。 -2. 主标题：demo 粗像素体大字+烛光副题装饰线；实机细体。 -3. 背景：demo 暗棕渐变+聚光；实机全铺石纹。 -4. demo 有「玩法速览」牌——**实机已按用户令删除，不回补**。 -5. 立绘/敌人群比例 demo 更大更聚中。 - -### ⑦ 营地（pair_2_camp） - -面板明度关系相反（demo 暗石皮面板浮于暖渐变；实机亮米大板浮于石纹）；demo 行带图标/Lv 徽章/价格按钮一格齐，实机行松、工坊行为纯文字行；关闭钮 demo 底部居中、实机左下；实机独有累计通关解锁进度列（功能差异非缺陷）。 - -### ⑧ 设置（pair_3_settings） - -demo 石皮框板+两列对齐行（label 列/控制列）+减动效行；实机素面板+行内流式布局无列对齐+**减动效行缺失**（实机仅 主音量/全屏/结算演出动画 三行——减动效语义由结算行承担与否待核）；返回钮 demo 紧凑、实机 216 宽。 - -### demo 无映射的实机屏（三屏，无对比基线） - -调试浮窗（real_9_debug）· 图例（real_10_legend）· 确认框（real_11_confirm）——demo 八屏不含，维持现状，仅存档截图。 - -## 总体结论（差距量级排序） - -1. **关卡地图底栏**（用户点名）——放弃钮尺寸语义错+特性行爆栏+淡墨违例；根本解=按 demo 88px 单条重设计（草案见上）。 -2. **商店/三选一形态级差距**（D1/D2 在册）：全屏化+竖卡 232×352——06 已登记待立项，本轮截图把量级坐实。 -3. **结算仪式感**（dim+石皮框板+两列账目）——呈现批量级。 -4. **背景处理全局差距**：demo 暖渐变聚焦、石纹只作局部质感；实机全屏铺石纹——跨屏共通改。 -5. **标题屏主操作语义**（继续上局应为主钮）。 -6. 战斗屏结构对齐度最高，仅棋盘底色处理与左栏编排差距。 -7. E5 证据更新：demo 爆破卡紫带 → 建议 blast 归回 TG_MAGIC（推翻 T4a 的 blast→TG_AOE），随用户裁决。 - -## 批末判定（2026-10-06 /goal UI 对齐批收口——逐项复判全记） - -/goal 令（「将游戏的 UI 对齐 demo 的 UI；完成后自验：ui_audit_probe 逐屏实机截图×demo 浏览器截图，重建并排对比图逐项判定；全部差距闭环或列明不可对齐原因」）执行完毕。判官=documents:visual-judge 两轮独立目检（初判 7 pass/2 partial/1 fail → 修复后复判 4 张全部转 pass），九组并排图已按合后态重摄重建（real/ 与 pairs/ 现内容=最终态）。 - -### 逐屏判定终态 - -| 屏 | 判定 | 闭环内容 | 留档差异（非本轮差距） | -|---|---|---|---| -| ①标题 | **pass** | 主操作语义反转（有档=继续上局主黄钮）；背景=暖棕底+石纹 0.14+斜光带+暗角 | demo 玩法速览牌已按用户令删除，不回补 | -| ②营地 | **pass**（用户实机复检后二次修复） | 背景氛围层（可见处石纹微弱+暗角）；**用户实机两缺陷修（2026-10-06）**：①底改不透明暖亮档（原 0.45 半透 dim 在石纹降 0.14 后底下对局画面透出——demo #v-camp=bg-bright 实底同款）②三柜 EXPAND_FILL 等宽分屏+行标签截断兜底（原行标签按文字全宽算 min，进度/状态长文案随档变长把三柜总宽撑爆 1248=右柜裁出屏）+状态列 tooltip 兜底 | 面板明度/行密度/关闭钮位=camp ⑦ 遗留（06 留档） | -| ③设置 | **pass** | 两列对齐（label 定宽 140）+返回钮紧凑 90+主音量滑轨实高修（HSlider 槽按 stylebox min 高绘制缺陷） | 减动效行不拆=reduced_motion 单设置同驱 motion_scale+结算演播（语义命名批裁决，demo 两行=同一设置） | -| ④地图 | **pass** | 底栏 85px 定高单条+放弃 90 小钮+特性行限宽截断+深墨；顶栏关卡名框板+GP 烛光胶囊+两极排布；背景暖棕渐变 | 道具槽段位=台账 352 功能欠账（非呈现层） | -| ⑤战斗 | **pass** | 背景氛围层成立；轮次条/上轮摘要结构一致 | 棋盘底板融景、左栏编排、站桩紧凑度=battle ⑤ 遗留（06 留档） | -| ⑥三选一 | **pass** | 全屏页（page_shell 根底档）+D1 竖卡 232×352+类型脚注行+底注 | 稀有度词缺=数据面无投喂（词表随数据批补） | -| ⑦商店 | **pass** | 全屏页（D2）+56px 通栏顶条+爬价规则行（实数投喂 shop_bp_visit_buys×shop_price_a）+D1 竖卡+底注池源 | 「已购 N 档」=实机独有档位语义（功能差异非缺陷） | -| ⑧结算·胜/败 | **pass** | DIM_NIGHT 0.62/0.6 全屏压暗（判官实测亮度 218→97）+两列对齐账行+紧凑主钮 | 账行文案词序差异=Narrator 文案域 | -| 无映射三屏 | 存档 | 调试浮窗/图例/确认框维持现状（demo 无基线） | — | - -### 不可对齐/留档原因清单 - -1. **营地面板明度与行密度、关闭钮位**：camp 布局属 M 批落码形制，重排=独立呈现批量级，本批只落背景氛围层；06 留档。 -2. **战斗棋盘底板**：棋盘视觉=样张 v2 机检冻结域（golden 断言），动底板需过样张闸；06 留档。 -3. **地图道具槽**：道具读数无关卡画面=成文出口（台账 352），功能件非呈现层。 -4. **稀有度脚注词**：候选数据面无稀有度字段投喂，随数据批补。 -5. **减动效独立行**：与结算演出动画=同一设置（语义命名批 T17 裁决合并），拆行=一设置双行重复，不拆。 - -### 闸门记录 - -开工基线冒烟 782/0（4336fd2 净态）→ 每轮轻闸冒烟 782/0+probe_gate --click 全绿 → 批末 run_all 16 套全绿+全探针绿+doc 三闸零新增（2 处 06 陈旧断链系基线随 merge 自愈，非本批引入）→ 合 master 2ca6288 主区复跑（冒烟 782/0+click 全绿+run_all 17 套全绿〔含并行批新落 curio_refresh_paid_test〕）→ 判官修复轮复验全绿。 diff --git a/design/qa/迭代18-实机目检总清单-2026-10-07.md b/design/qa/迭代18-实机目检总清单-2026-10-07.md deleted file mode 100644 index 96559586..00000000 --- a/design/qa/迭代18-实机目检总清单-2026-10-07.md +++ /dev/null @@ -1,52 +0,0 @@ -# 迭代 18 四卡实机目检总清单（2026-10-07 交付） - -迭代 18 四卡已全部已合并进 master：卡③ 提案批（merge de067ae）/卡⑤ 混编投放批（merge 0dbe3c3）/卡⑦ 种子随机化批（merge b91b973）/卡④ 生涯界面批（本批）。目检归用户逐项过；每节标注详细判据所在的出口报告。目检不阻塞后续开发，但发现的问题按正常缺陷修复流程登记。 - -> **✅ 核销状态（2026-10-14 qa 收尾批）**：用户实机目检回报全部完成，未呈报问题——卡⑤ 四项、卡⑦ 八项、卡④ 六项共 18 项同批核销（卡③ 纯文档批无实机目检项；卡⑤ 难度带 MC 取证读数挂账条随 M4 数值批履行，不属人闸）。 - -## 一、卡③ 武器锻造系统设计提案（纯文档批——无实机目检） - -人闸=**提案盘问裁决**（异步，不阻塞其余卡）： - -- 提案正文：`design/research/提案-武器锻造系统-2026-10-07.md`（八节框架）。 -- 17 个设计裁点的全备选案一览表：`design/qa/iter18-forge-exit-report-2026-10-07.md` §四（推荐主线=丙案「当前武器单选+每件武器独立等级与特效」等，逐点呈裁）。 - -## 二、卡⑤ 混编遭遇首批投放批 - -目检四项（详细判据：`design/qa/iter18-mixenc-exit-report-2026-10-07.md` §7）： - -1. 第 2 关深度 5 的普通节点触发战斗：同场出现两种敌人——熊地精重击手 + 巨蜘蛛巢群（巨蜘蛛 2-3 只）。 -2. 同场敌人出场顺序与表序一致：重击手在前、巨蜘蛛巢群在后。 -3. 同场敌人实例总数不超过 4。 -4. 首遇教学位回归不变：巨蜘蛛首遇位（第 2 关节点 4）固定 2 只不加骰；钩爪恐魔（第 3 关节点 0/1）固定数量。 - -## 三、卡⑦ 种子随机化与调试浮窗升级批 - -前置：以 `DS_DEBUG=1` 启动游戏（详细判据：`design/qa/iter18-seed-exit-report-2026-10-07.md` A-I 九节）： - -1. 应用启动后调试浮窗默认打开（手动可关、角标可再开）。 -2. 主菜单连续开多次新冒险（非首局、种子框留空）：各局种子互不相同（当局数据区块可查本局种子）；首次冒险（新档第一局）固定种子 42。 -3. 调试种子框输入合法整数时全场景按输入值生效（含首局）。 -4. 对局中可从战斗屏 HUD 角标与关卡地图屏角标开合浮窗；其他层打开时浮窗暂隐、关闭后自动恢复。 -5. 当局数据区块六项（种子/关卡/节点/HP/GP/钥石）与实际局况逐项一致。 -6. 从浮窗发起调试对局正常；对局进行中批量模拟与调试对局两按钮禁用。 -7. 浮窗开着时棋盘输入不被锁死、暂停角标不置灰；开新冒险/续玩路径正常（浮窗自动收起）。 -8. 断点续玩逐位正常（存档种子回填）。 -- 随附：代拍板追认单六项（区块标题/占位提示词/角标落点等）见出口报告追认单节。 - -## 四、卡④ 生涯界面实装批·期一 - -目检六项（详细判据：`design/qa/iter18-career-exit-report-2026-10-07.md` A-H 八节）： - -1. 主菜单「营地与系统」组出现「生涯」钮（营地钮之后），点击开生涯全屏页、关闭返回主菜单。 -2. 汇总页六类九项数值与存档实况逐项一致：总局数/通关局数/各关通关次数/Boss 首杀/Boss 总击杀/钥石余额/属性锻造合计/道具工坊解锁计数/天赋树已购聚合。 -3. 旧档（v5 格式）载入后生涯页正常显示（终身计数缺省补零），无损坏。 -4. 生涯页开着=游戏输入锁定（与其他层同语义）；与设置/确认弹窗等他层开合关系正常。 -5. 页内零「前往他处」跳转入口（只有返回）；零动效。 -6. 局内（战斗屏/地图屏）无生涯入口；存档往返（退出重进）后计数不漂移。 -- 随附：代拍板追认单十一项（字段命名/文案/行序排版/分组标题等）见出口报告追认单节。 - -## 挂账提醒（非目检项） - -- 卡⑤ 难度带 MC 取证读数：顺延 Alpha 收官 M4 数值批统一执行，届时另行报批（07-⑱ 在册）。 -- 卡⑦ 三裁决（首次固定/显式指定/种子不进玩家 UI）2026-10-07 已裁，本批即其执行。 diff --git a/design/qa/代码术语审计报告-2026-10-18.md b/design/research/代码术语审计报告-2026-10-18.md similarity index 96% rename from design/qa/代码术语审计报告-2026-10-18.md rename to design/research/代码术语审计报告-2026-10-18.md index 7f793b32..5f59a0ec 100644 --- a/design/qa/代码术语审计报告-2026-10-18.md +++ b/design/research/代码术语审计报告-2026-10-18.md @@ -34,7 +34,7 @@ 注：「封印」现有 170 处命中（46 文件），其中大部分是正确用法（封印=正式术语），但部分语境把它当「比喻」或「对外表达」描述，需修正措辞。 -**读数订正（2026-10-18 需求卡片 v1.4 实测，本表数字保留作历史读数不作施工依据）**：上表的 game/ 侧数字用现行代码复现不出。同一命令口径实测（`game/` 内、区分大小写逐处计数）：含 `flag` 的 .gd 53 个文件 595 处 ＋ .tres 4 个文件 22 处，剔除 `size_flags_*`（70 处／19 文件）与 `_fatal_flag`（4 处）后**净 543 处／42 个文件**；「金币」39 处、「插旗」62 处、「雷格」75 处、「惩罚格」1 处、「旗」含复合词 376 处。两处口径错误：①中文三词用的是**全库**读数（全库实测 金币 381／插旗 600／雷格 394 处），被记进了 game/ 范围行；②flag 侧低估约一倍（原记 270＋22＋22＝314）。施工判据以 [需求卡片-代码术语刷新批](../research/需求卡片-代码术语刷新批-2026-10-18.md) §2 的复现命令为准。 +**读数订正（2026-10-18 需求卡片 v1.4 实测，本表数字保留作历史读数不作施工依据）**：上表的 game/ 侧数字用现行代码复现不出。同一命令口径实测（`game/` 内、区分大小写逐处计数）：含 `flag` 的 .gd 53 个文件 595 处 ＋ .tres 4 个文件 22 处，剔除 `size_flags_*`（70 处／19 文件）与 `_fatal_flag`（4 处）后**净 543 处／42 个文件**；「金币」39 处、「插旗」62 处、「雷格」75 处、「惩罚格」1 处、「旗」含复合词 376 处。两处口径错误：①中文三词用的是**全库**读数（全库实测 金币 381／插旗 600／雷格 394 处），被记进了 game/ 范围行；②flag 侧低估约一倍（原记 270＋22＋22＝314）。施工判据以 [需求卡片-代码术语刷新批](../reports/需求卡片-代码术语刷新批-2026-10-18.md) §2 的复现命令为准。 --- @@ -119,4 +119,4 @@ design/research/（提案、需求卡片）、design/qa/（审查报告）、des ## 6. 建议拆批 -见同目录需求卡片：`design/research/需求卡片-代码术语刷新批-2026-10-18.md` +见同目录需求卡片：`reports/需求卡片-代码术语刷新批-2026-10-18.md` diff --git a/design/research/会话提示-营地场景图美术设计-2026-10-18.md b/design/research/会话提示-营地场景图美术设计-2026-10-18.md index 122c5dfc..4e29d614 100644 --- a/design/research/会话提示-营地场景图美术设计-2026-10-18.md +++ b/design/research/会话提示-营地场景图美术设计-2026-10-18.md @@ -16,7 +16,7 @@ ### 2. 开工前必读（按序，读完再动手） 1. `design/research/需求澄清-营地交互重做-2026-10-18.md` —— **唯一事实源**：①目标体验原话 ②参照与反参照 ③非目标 6 条 ④目标结构树＋纵深稿（远景天空／中景围栏+大门／近景篝火居中／左锻炉铁砧／右床铺宝箱）⑤10 条交互裁决 ⑥验收口径 ⑦切批原则 -2. `design/research/需求卡片-营地场景图新建批-2026-10-18.md`（v2.2）—— 卡④现状与已裁事项（Q4/Q5/Q6/Q8 均裁定甲）、五项前置销号清单 **P1–P5**、归属纪律段 +2. `reports/需求卡片-营地场景图新建批-2026-10-18.md`（v2.2）—— 卡④现状与已裁事项（Q4/Q5/Q6/Q8 均裁定甲）、五项前置销号清单 **P1–P5**、归属纪律段 3. `design/gdd/ux/camp.md`（v1.5）—— 营地现有功能面（四柜台、钥石、商店） 4. `design/art/art-bible.md`（v3.15）—— §4.2／§4.6.3 色板权威面、§6.2／§7.5 场景与物件条款 5. `design/gdd/06-待办清单.md` 末尾「营地交互重做·五张需求卡片」条目 —— 状态机与销号出口在哪改 diff --git a/design/research/提案-冒险前资源配比预设-2026-10-04.md b/design/research/提案-冒险前资源配比预设-2026-10-04.md index 3beb8a1b..d5091be6 100644 --- a/design/research/提案-冒险前资源配比预设-2026-10-04.md +++ b/design/research/提案-冒险前资源配比预设-2026-10-04.md @@ -2,7 +2,7 @@ > 日期：2026-10-04 > 性质：立项提案（纯调研，零代码，零 git 操作）——五个开放问题逐项列全备选案（含淘汰案与淘汰依据），各给一条推荐；全部拍板归用户（见 §八）〔2026-10-04 已全裁，裁决记录见 §九〕。 -> **⚠ 已退役存档（2026-10-18 用户令入库）**：八裁与盘问四裁全落后，本提案已由[需求卡片-冒险前资源配比预设批-2026-10-04](需求卡片-冒险前资源配比预设批-2026-10-04.md)吸收（吸收即死）——裁决结论唯一事实源=06-待办清单「冒险前资源配比预设（构筑提案）」条＋该卡片；本文件只作推导过程与淘汰依据的历史档，重启该批勿以本文为现行口径。 +> **⚠ 已退役存档（2026-10-18 用户令入库）**：八裁与盘问四裁全落后，本提案已由[需求卡片-冒险前资源配比预设批-2026-10-04](../reports/需求卡片-冒险前资源配比预设批-2026-10-04.md)吸收（吸收即死）——裁决结论唯一事实源=06-待办清单「冒险前资源配比预设（构筑提案）」条＋该卡片；本文件只作推导过程与淘汰依据的历史档，重启该批勿以本文为现行口径。 > 事实源：[06-待办清单](../gdd/06-待办清单.md)「冒险前资源配比预设（构筑提案）」条（2026-10-04 现行态）· [元进度](../gdd/systems/跨局循环/元进度.md) v1.6 · [地图战斗资源](../gdd/systems/战斗循环/地图战斗资源.md) v0.16 · [难度曲线与Boss](../gdd/systems/冒险循环/难度曲线与Boss.md)（带换代节）· [关卡节点地图](../gdd/systems/冒险循环/关卡节点地图.md) v1.5 · [棋盘生成](../gdd/systems/排雷循环/棋盘生成.md) v0.4 · `game/data/tables/reward.tres`（现行权重逐行核证）· 姊妹研究 方案-挖掘风险不等式修订-2026-10-04（已退役，git 历史可考） · 外部先例出处随文注（§二与附录）。 --- diff --git a/design/qa/测试审计-单测与验收门禁标准-2026-10-15.md b/design/research/测试审计-单测与验收门禁标准-2026-10-15.md similarity index 100% rename from design/qa/测试审计-单测与验收门禁标准-2026-10-15.md rename to design/research/测试审计-单测与验收门禁标准-2026-10-15.md diff --git a/design/art/美术审计-canvas转HTML-2026-10-14.html b/design/research/美术审计-canvas转HTML-2026-10-14.html similarity index 98% rename from design/art/美术审计-canvas转HTML-2026-10-14.html rename to design/research/美术审计-canvas转HTML-2026-10-14.html index 118a5fd1..a1b9efaf 100644 --- a/design/art/美术审计-canvas转HTML-2026-10-14.html +++ b/design/research/美术审计-canvas转HTML-2026-10-14.html @@ -4,6 +4,7 @@ 视觉与美术审计 - 2026-10-14 +