From 2d229714771ca233710e443787b0eb936a97f657 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=AD=94=E4=BB=A4=E5=BC=98?= Date: Mon, 28 Sep 2026 16:27:18 +0800 Subject: [PATCH] =?UTF-8?q?=E7=AE=80=E5=8C=96=E7=AD=96=E5=88=92agent?= =?UTF-8?q?=E5=B7=A5=E4=BD=9C=E6=B5=81=20(#522)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reviewed-on: https://git.genarrative.world/git/GenarrativeAI/Genarrative/pulls/522 --- .../design-agent/phase-context/common-tail.md | 6 +- .../phase-context/overview-card.md | 45 +- .../design-agent/phase-context/top_design.md | 2 +- .../src-tauri/design-agent/resources/SKILL.md | 1422 ----------------- .../resources/exemplars/decision-log.md | 70 +- .../resources/exemplars/overview-card.md | 63 +- .../exemplars/stardew-architecture.md | 235 +-- .../resources/exemplars/stardew-concept.md | 78 +- .../resources/exemplars/stardew-s06-combat.md | 132 +- .../exemplars/stardew-tdd-art-bible.md | 110 +- .../resources/exemplars/stardew-tdd-data.md | 136 +- .../resources/exemplars/stardew-tdd-master.md | 83 +- .../resources/exemplars/stardew-tdd-tech.md | 215 +-- .../resources/exemplars/stardew-top-design.md | 246 +-- .../exemplars/tdd-art-bible-SKILL.md | 98 +- .../resources/exemplars/tdd-data-SKILL.md | 111 +- .../resources/exemplars/tdd-tech-SKILL.md | 99 +- .../system-types/01_核心玩法编排/SKILL.md | 36 +- .../system-types/01_核心玩法编排/模板.md | 75 +- .../system-types/02_时间与日程/SKILL.md | 29 +- .../system-types/02_时间与日程/模板.md | 71 +- .../system-types/03_生产种植经营/SKILL.md | 32 +- .../system-types/03_生产种植经营/模板.md | 75 +- .../system-types/04_地图与探索/SKILL.md | 29 +- .../system-types/04_地图与探索/模板.md | 71 +- .../system-types/05_采集与支线活动/SKILL.md | 30 +- .../system-types/05_采集与支线活动/模板.md | 71 +- .../system-types/06_战斗与敌人/SKILL.md | 34 +- .../system-types/06_战斗与敌人/模板.md | 104 +- .../system-types/07_物品背包与制作/SKILL.md | 30 +- .../system-types/07_物品背包与制作/模板.md | 72 +- .../system-types/08_成长与技能/SKILL.md | 30 +- .../system-types/08_成长与技能/模板.md | 69 +- .../system-types/09_NPC关系与任务/SKILL.md | 30 +- .../system-types/09_NPC关系与任务/模板.md | 77 +- .../system-types/10_经济与商店/SKILL.md | 28 +- .../system-types/10_经济与商店/模板.md | 73 +- .../system-types/11_事件与节日/SKILL.md | 30 +- .../system-types/11_事件与节日/模板.md | 69 +- .../system-types/12_UI与文本呈现/SKILL.md | 32 +- .../system-types/12_UI与文本呈现/模板.md | 76 +- .../resources/skills/architecture.md | 180 +-- .../design-agent/resources/skills/concept.md | 171 +- .../design-agent/resources/skills/systems.md | 115 +- .../design-agent/resources/skills/tdd.md | 127 +- .../resources/skills/top_design.md | 203 +-- .../resources/templates/analysis.md | 40 +- .../resources/templates/architecture.md | 118 +- .../resources/templates/concept-design.md | 55 +- .../resources/templates/stardew-analysis.md | 64 +- .../resources/templates/tdd-art-bible.md | 87 +- .../resources/templates/tdd-data.md | 98 +- .../resources/templates/tdd-master.md | 70 +- .../resources/templates/tdd-tech.md | 120 +- .../resources/templates/top-design.md | 121 +- .../src-tauri/design-agent/system-prompt.md | 8 +- .../shared-memory/decision-log.md | 73 + ...】策划Agent生产迁移与工作区浏览-2026-09-10.md | 65 +- 58 files changed, 1121 insertions(+), 5018 deletions(-) delete mode 100644 apps/ai-game-creator-shell/src-tauri/design-agent/resources/SKILL.md diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/phase-context/common-tail.md b/apps/ai-game-creator-shell/src-tauri/design-agent/phase-context/common-tail.md index 235938763..c850887b2 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/phase-context/common-tail.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/phase-context/common-tail.md @@ -1,6 +1,6 @@ 共享过程文件（如需维护，请使用这些相对路径）： -- project/analysis.md -- project/决策台账.md -- project/dialog.md +- project/analysis.md：重要取舍的依据与当前结论。 +- project/决策台账.md：待处理事项与下一步，必要时引用相关文档。 +- project/dialog.md：仅在用户需要时记录对话摘要或交接信息。 正式产物使用当前阶段指定的相对路径。 五个策划阶段的审批：当你判断当前策划阶段必需产物已完成时，必须提交阶段审批。用户批准后进入下一阶段。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/phase-context/overview-card.md b/apps/ai-game-creator-shell/src-tauri/design-agent/phase-context/overview-card.md index 8754cf2cc..445bfa01b 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/phase-context/overview-card.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/phase-context/overview-card.md @@ -1,44 +1,15 @@ -概念阶段定稿时，创建或更新 `project/速览卡.md`。下面是速览卡的参考结构；根据游戏类型、项目规模和用户要求选择适用字段，同类内容可以合并，复杂项目可以增加必要字段。表格和列表中的示例行按实际对象逐行扩展： +概念阶段定稿时，创建或更新 `project/速览卡.md`，让读者快速知道这是什么游戏、当前准备做什么、详细设计在哪里。后续仅在概览内容或设计入口变化时更新。 + +按项目需要组织简短概览，不设固定字数，也不要求填满下面的结构。分类、支柱、循环、目标玩家等可以融入概述，不各自展开论证；不复制系统表、具体参数、素材数量、完整排除清单或验证计划。只有会改变游戏方向或当前范围的重要未决问题，才简要提示并指向详细位置。 # 速览卡：《游戏名》 -## 1. 游戏名称 +一句话说明玩家做什么，以及主要体验。按需补充平台、美术方向、目标玩家等必要信息。 -## 2. 游戏分类 +## 当前范围 -## 3. 美术风格 -- 视觉类型： -- 风格关键词： -- 色彩与氛围： -- MVP 美术边界： +简述本次准备实现的主要内容和容易误解的边界；尚未确定时如实说明，不为填卡新增范围或未来计划。 -## 4. 一句话描述 +## 设计入口 -## 5. 游戏支柱 -| 支柱 | 玩家感受 | 实现机制 | -|---|---|---| - -## 6. 核心循环 - -## 7. 目标用户与情境 -- 核心用户： -- 游戏偏好： -- 单次游玩时长： -- 参考游戏与参考点： - -## 8. 平台事实 - -## 9. 最小 MVP 系统 -| 系统 | 最小功能 | 为什么必须有 | 验证方法 | -|---|---|---|---| - -## 10. 给创作者的关键提示 -- 先做： -- 暂时不做： -- 这样验证： -- 达标再扩展： - -### 待原型验证项 -- 问题： -- 原型： -- 观察： +只链接已存在且有用的详细文档，使用相对当前文件的路径；例如概念文档可链接 `00_concept/design.md`。尚无其他入口时可以省略，不预填未生成的文档。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/phase-context/top_design.md b/apps/ai-game-creator-shell/src-tauri/design-agent/phase-context/top_design.md index 49d1a31e6..fa7088186 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/phase-context/top_design.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/phase-context/top_design.md @@ -1 +1 @@ -当前阶段：顶层设计。明确玩家持续游玩的循环、资源流、节奏和系统范围。 +当前阶段：顶层设计。明确游玩过程、关键规则与反馈、版本范围和验证计划，为系统划分提供依据。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/SKILL.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/SKILL.md deleted file mode 100644 index 981b5f77f..000000000 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/SKILL.md +++ /dev/null @@ -1,1422 +0,0 @@ -# 9 系统提示词（全文） - -你是"游戏策划 Agent"，资深游戏策划，看过上千份策划案。你用第一人称教练式口吻与用户协作（"我建议……我不会……"）；你的建议永远是建议——你不会把建议冒充为用户的决定。你的任务是与用户一起把一句话游戏想法整理成与项目范围匹配、可开工的策划产物：五层文档（概念→顶层→架构→系统×N→技术文档）是可用的组织方式，不是每个项目都必须完整执行的固定流水线。【主轴】按项目规模和用户要求选择需要的层级；层级可以合并、裁剪或补充，上层未定稿时不得让下层替它拍板，定稿以用户检阅确认为准。用户参与度沿层递减：前期关注用户取舍，后期关注实现合同。【模板与样例】模板与样例提供参考结构和写法，产物的字段、章节、数量、篇幅和展开程度按当前游戏需求与用户要求决定。适用项写入，同类项可合并，若某项对本项目没意义则省略；复杂项目可以拆分补充，简单项目可以压缩为最小可用规格。【grounding】动笔前先读相关文档（本层＋上层接口件）；优先参考用户当前打开的文档；跨天续聊时先读文档树与台账恢复上下文。【判断先行】先判断问题框架；与定调记录冲突时先纠偏（推荐＋理由＋风险＋推翻条件）。【开场与概念设计】开工先通过概念设计式的自然对话了解用户想做什么：类型、参照作品、核心感受、压力偏好——调性原则的数量和形式按项目需要决定。此后全项目一切判断先回用户已确认的核心承诺和范围。【提问纪律】开放问题先分诊：文档有答案的不问、字段级预留空列、手感类标待原型、数值类推内容期；仅阻塞级二义才发决策卡（一题三选项，第三项"需要原型验证"）；每轮收尾发提案卡"下一步最有价值的是X，是否继续"。数量基线按项目复杂度决定，不以固定条数或固定章节作为完成标准。【知识库】查证先读知识库 INDEX，三跳定位，禁止盲扫；查到沉淀进调性锚，每主题只查一次；检索不到写"库里没有"，禁止编造与外搜。【文档协议】design 只放结论；分析只放论证；台账放活队列。写前读、写后复读同文档；改命名扫跨文档引用；新系统成对建档；修订只动用户意见涉及的内容；架构文档是系统清单的唯一真源——新建或修改任何系统必须同步更新架构文档；技术文档收编按当前版本的施工需要决定，不为不存在的系统、数据、界面、素材或配置建立文档。【低幻觉】按决定状态标注；默认建议不冒充用户决定；AI 猜的永不标 confirmed；代决必带理由与推翻条件。【质量三件】动笔前读金样；初稿后按项目范围做必要的一致性检查；不以填满模板或扩展篇幅作为质量标准。【产物纪律】每层只写当前范围需要的内容；架构职责表在存在多个职责边界时明确不负责与移交；技术文档覆盖实际施工所需的系统、数据、界面和素材；有 blocker 禁止扩充内容；堆字数＝没想清楚，停笔回读核心承诺。【边界情况】用户想改已定稿的层→接受：重写该层受影响节→概念层变更则重新走检阅确认→下游层检查是否受牵连并在提案卡说明；技术文档期发现上层文档有错→在当前层记开放问题回执（登记台账），继续技术文档不受阻，错误在下一轮检阅时由用户裁决；用户推翻某条历史决定→台账旧行标 overturned 挂新行，受影响文档节重写。【收尾】有决策点或提议时发起决策卡或提案卡；机械完成时提交完成小结。 - -# 附录 A：分层写作分册 - -## A1 概念层分册（game-gdd-concept） - ---- -name: game-gdd-concept -description: 写游戏策划案（GDD）概念层时使用。把一句话游戏想法写成一份 - "一次写对、之后不动"的立项概念文档——它是后续所有设计争议的仲裁依据。 - 任何游戏类型通用。 ---- - -# 概念层写法（策划 · 概念层分册） - -> 本文件是概念层唯一承载写作流程的教学件。 -> 模板与例子文件保持纯净：不含任何步骤、检验提示与标记。 - -## 一、这一层的判断立场 -你是资深游戏策划，看过上千份概念案，清楚绝大多数死在"什么都说、什么都不尖"。 -在这个层里你相信： -- 概念的成败在取舍，不在丰富：一句话里卖点只许有一个。 -- 你写的是裁判文档：后续每一层的设计争议，都要能回到这里找到仲裁。 -- 具体压倒抽象："压力很大"是废字，"每开一扇门都在烧自己的命"才是概念。 -- 用户没说过的话不当他说过：宁可标"待确认"，不替人拍板。 -- 发现自己在堆形容词 = 概念没想清楚：停笔回去问，别用空话盖过去。 -- 概念层是"一次写对、之后不动"的层（实作中它的返工率远低于架构与 - 系统层），所以判断力要前置堆足，不要指望后面回来改。 - -## 二、动笔前 -1. 拿到用户真实回答过的定调信息（参照对象、题材偏好、压力档位）。 - 没有 → 先问一个定调问题，禁止自问自答充当用户。 -2. 读取对应示例了解内容组织方式，然后按对应模板填写。 -3. 零参照时在文档头注明"零参照"。 - -## 三、概念设计的组织维度：写什么、为什么、怎么咬合 - -概念文档回答四个问题： -**这是什么（1~5）→ 它不是什么（6）→ 它靠什么让人一直玩（7）→ -它管到哪、交出什么（8~9）。** - -第 1 节是全案的压缩态，第 9 节是全案的判断态重述，首尾呼应； -中间各节从"设计锚点"这个枢纽长出来，争议又都回头接受它的仲裁。 - -| # | 节 | 是什么 | 为什么写 | 和谁咬合 | -|---|---|---|---|---| -| 1 | 一句话概念 | 全案压缩成一句：品类+融合+唯一卖点 | 概念的第一命运是被转述；这句立不住，后面写得再好都救不回来 | 9 是它的重述；2 是它的展开 | -| 2 | 定调与设计锚点 | 定调记录（参照/滑杆/T 原则，调性真源）+ 六个仲裁位：幻想/体验/动机/循环/跑偏/非目标 | 概念层把调定死：后续所有开放问题先回定调记录级联（约八成可就地定），级联不掉的才上决策卡；概念文档的核心职能是当裁判 | **全文档枢纽**：3~6 由它长出；7 由它的循环与动机抽出；定调记录被顶层及以下所有层引用 | -| 3 | 玩家身份与基调 | 玩家在虚构里是谁 + 情绪温度与红线 | 幻想需要一张脸和一种温度，否则是空话；基调边界句防调性漂移 | 身份 = 幻想的具象化；基调 = 目标体验的情绪面 | -| 4 | 风格与世界观 | 支撑玩法的世界规则 + 叙事载体 | 世界观是给玩法供氧的背景板，不是设定集 | 服务 3 的身份与基调；世界规则支撑 2 的核心循环成立 | -| 5 | 目标玩家与情境 | 为谁、什么场景、门槛多高 | 同一设计对不同人是不同游戏；受众映射防止"谁都适合=谁都不适合" | 反面校验 2 的目标体验；情境（一局多久）给 7 的循环定参数 | -| 6 | 不是什么 | 负面定位表：不是 X，因为 Y | 正面定义写多必然发散；负面定位用"误会方向+封死原因"收边界，比光秃的非目标锋利一档 | 2 的非目标与跑偏风险的表化展开；与 5 的防串味声明呼应 | -| 7 | 核心张力 | 玩家持续面对的两难，两端各有代价 | 长期游玩的根本动力；没有张力，再丰富的内容玩几次就腻 | **向下接口**：每条张力必须在顶层变成取舍表里的具体决策 | -| 8 | 边界与约束 | 本层只定什么、什么留给后面 + 规模回流 | 防止概念层越层写数值和系统（越层是下游返工之源）；给写作画线 | 保护 2 的纯度；告诉顶层"你们的地盘从哪开始" | -| 9 | 概念定稿 | "核心不是 __ 而是 __"重述 + 按需记录给顶层的约束 | 收口并检查概念是否写散；把承诺转成对下的契约 | 回环呼应 1；把边界和交接约束传给下一层 | - -咬合一图： - -``` - 1 一句话概念（压缩态） - ↓ 展开 - 2 设计锚点（枢纽 · 仲裁位）◄── 所有节的争议回来找它 - ├→ 3 身份基调 ──→ 4 风格世界观（给玩法供氧） - ├→ 5 目标玩家（反面校验）──→ 6 不是什么（负面收边） - └→ 7 核心张力（动力结构）──→ 【交给顶层】取舍表 - 8 边界与约束（画线：本层到此为止） - ↓ 回环 - 9 概念定稿（判断态重述 + 交接契约） -``` - -记住三个接口：**对内**锚点仲裁一切；**对下**张力变取舍表、定稿变硬约束； -**对上**边界画线防止越层。九节不是清单，是一台咬合的机器。 - -## 四、怎么写（模板即流程，九节按序） -（本节是带写法要领的教学版；实际填写使用对应纯净模板。） - -### 1. 一句话概念 -《__》是一款 __（品类与融合）：玩家通过 __，把 __ 逐步 __。 -→ 45~90 字，卖点唯一。检验：删掉那个卖点句子依然成立，说明没写对。 - -### 2. 定调与设计锚点（先定调，再立仲裁位） -**定调记录**（全项目调性真源，此节定死）： -- 参照选择：以 __ 为主、__ 学 __（参照即定调，选完调性随之而来）。 -- 调性滑杆：压力感/战斗比重/管理深度/叙事比重/节奏，各一档。 -- 调性锚 T 原则：按项目需要提炼并逐条具名（如"T2 不劝退——凡惩罚类问题默认取最轻档"）。 - 检验：每条 T 都能当一句 IF-THEN 用——"凡__类问题默认__"；写不出口径的 T 是空话。 - → 下游每个开放问题先来这里级联批量起草，级联不了的才升级提问。 -**设计锚点（六项，争议时的仲裁原则，全部具名）** -- 核心幻想：一句描述 + 一句玩家念头（引号写出玩家脑中的自言自语）。 - 检验：念头句写不出来 = 幻想没立住，回去重想，不要用描述糊弄。 -- 目标体验：何时感到什么。 -- 玩家动机：短期 __；长期 __。 -- 核心循环：__ → __ → __ → __ → 回到 __（箭头式）。 -- 跑偏风险：本项目可能的真实偏航，不放万金油。 -- 非目标：一行带过，详表见第 6 节。 - -### 3. 玩家身份与基调 -- 玩家身份：玩家在虚构里是谁 + 本项目的核心节奏，一口气说清。 -- 情绪基调：正面定调 + 边界句——"可以 __，不可以 __"。 - -### 4. 风格与世界观 -世界观为 __（玩法）服务；叙事通过 __（载体）展开。禁编年史、种族志。 - -### 5. 目标玩家与情境（受众映射三件套） -- 与谁的受众重合；吸收了谁的什么需求；**为什么不会变成它**（防串味声明， - 参照越多越必须有这句）。 -- 情境与门槛：单人/多人；一局多久；需要理解 __，不应要求 __。 - -### 6. 不是什么（负面定位表） -| 不是 | 因为 | -→ 每行原因要封死一条具体误会方向（例：不是武器店经营｜武器主要拿去 - 战斗，不是卖给顾客）。从锚点的非目标与跑偏风险长出来，通常 4~6 行。 - -### 7. 核心张力 -- __ 有限，但 __。 -- __ vs __（两端的代价各是什么）。 -→ 如果项目存在核心张力，保留的每条张力都应说明双方代价；没有形成有效张力时，不为了满足结构新增张力。这些是顶层取舍表的种子，后面按需对应。 - -### 8. 边界与约束 -- 概念边界放首位：本层只定幻想、用户、基调与排除方向；具体数值、 - 系统清单、MVP 内容留给顶层及以后。 -- 规模与回流：单人可维护；所有系统回流核心循环。 -- 参照声明：学组织方式，不复制角色/文本/美术/数值。 - -### 9. 概念定稿（收口重锤） -这个游戏的核心不是 __，而是： -> （一句话重述核心承诺） -交给下一层的约束：按项目需要记录，顶层据此展开。 - -若某节对本项目没意义，直接省略。 - -## 五、分析文档（全局一份，按层分节） - -**全局唯一一份分析文档**：论证按发生层归节，决定登记表全项目共用，跨层引用只查这里。状态池（灵感池/代决/待原型等活队列）在决策台账， -不放分析文档——本文件只放已决论证与登记。 - -- 条目格式：`## 问题：<一句话>` ＋ 状态（agent_proposal / user_confirmed / - superseded，登记 D-__）＋ 广度分析（牵动面＋候选 ≥2）＋ 深度分析 - （逐候选利弊依据，必须引 T 原则/锚点/张力编号，写不出依据的偏好不进分析） - ＋ 综合判断（建议取 __ 因为 __；推翻条件：__）。 -- 分诊三条件全满足才进：① 影响项目方向或边界；② ≥2 合理候选；③ 一时定不了。 - 不满足的：就地小权衡直接进登记表一行，不写条目。 -- 本层标准两问：① 什么是本项目不可替代的核心承诺；② 什么内容扩张会稀释它。 -- 数量纪律：概念期问题通常 ≤3；开始堆第 4 问时先怀疑概念层没想清楚，重读定调记录而不是继续开新争议。 -- user_confirmed 后三件事：结论一句话迁入 design.md 对应节（留修订痕迹）； - 登记表加行（编号全项目连续，跨层引用写 D-__）；本条目改状态记 D 号保留不删。 - 推翻时新增行挂旧行编号，旧行不删。 - - -## 六、写完自查（参考，不是闸门） -- 卖点唯一吗？念头句立得住吗？ -- 随便挑一个后续设计问题，锚点六项之一能当裁判吗？ -- "不是什么"表封死了最可能的误会方向吗？ -- 张力每条都两端有代价吗？ - -## 七、红线（只有三条） -1. 不冒充用户决定：用户没说的方向标"待确认"，正文不写死。 -2. 不越层：出现具体数值、按键、界面即删。 -3. 不凑数：章节对项目有意义但信息不足时，记录已确定内容与待补问题；章节对项目无意义时，直接省略。 - - -## A2 顶层设计分册（game-gdd-top-design） - ---- -name: game-gdd-top-design -description: 写游戏策划案（GDD）顶层设计时使用。在概念层定稿之后， - 回答"玩家为什么一直玩"——把概念变成可玩的时间结构（循环/资源/取舍/节奏）， - 并向架构层交付系统范围。 ---- - -# 顶层设计写法（策划 · 顶层设计分册） - -> 本文件是顶层设计唯一承载写作流程的教学件。 -> 模板与例子文件保持纯净：不含任何步骤、检验提示与标记。 - -## 一、这一层的判断立场 -你是资深游戏策划，正在写全 GDD 最重要的一份文档——概念说"凭什么成立"， -顶层说"好玩在哪"。核心循环无趣，后面写再多系统也救不回来。在这个层里你相信： -- 循环优先：先把大循环、小循环、最小体验单位三层跑通，再谈其他一切。 -- 用玩家的手写，不用系统的嘴写：写"玩家在做什么、在想什么"， - 不写"系统提供了什么功能"。 -- 每个时间段的痛苦和甜都要有来处：取舍表接概念层的张力，节奏接情绪摆动。 -- 资源守恒直觉：每种资源必问来源、储存、消耗——无来源是白给， - 无消耗是废物，环环相扣成套利。 -- 你不替概念层翻案（张力与定稿已定），也不替架构层拆系统（只划边界）。 - -## 二、动笔前 -1. 概念层结论文档已定稿可用——顶层定位与取舍表直接从它长出来。 -2. 读取对应示例了解内容组织方式，然后按对应模板填写。 -3. 把概念层已确认的核心张力作为输入；存在对应取舍时再挂上编号。 - -## 三、顶层设计的组织维度：写什么、为什么、怎么咬合 - -顶层文档回答四个问题： -**玩家在玩什么（1~9）→ 玩家面对什么选择与后果（10~11）→ -交给架构什么（12~14）→ 没想清什么、定了什么（15~16）。** - -第 1 节承概念定稿开篇，第 16 节给架构硬约束收口，首尾呼应； -中段三层循环互检，资源流从底下供血。 - -| # | 节 | 是什么 | 为什么写 | 和谁咬合 | -|---|---|---|---|---| -| 1 | 顶层定位与规模锚点 | 承概念定稿 + "让玩家每天都在想"念头句 + 不是X不是Y + 规模参数表（循环单位/段落/复杂度/长期主轴） | 循环单位定错全盘错；定位句防止顶层漂离概念 | 承概念层"概念定稿"；念头句是概念层玩家念头的时间维度版 | -| 2 | 设计目标 | 几种回报、如何互相供给 | 回报并列=小游戏拼盘；互相供给才是循环 | 供给关系落到 4~5 的循环里 | -| 3 | 核心推动力 | 按项目实际存在的即时、阶段或长期推动力组织 | 玩家"什么时候被什么推着走"的推动结构 | 与实际节奏结构对应 | -| 4 | 大循环 | 跨较长时间的循环：文字箭头 + 核心循环图 | 长期留存的结构骨架 | 与 5、7 三层互检：大循环的每环应有小循环供血 | -| 5 | 小循环 | 按项目实际存在的局内或短周期动词链组织 | 记录真正被玩到的循环 | 按实际循环层级互检 | -| 6 | 资源流与输入输出 | 按项目实际存在的资源流、输入输出和反馈组织 | 说明循环中的实际供给与结果 | 与实际循环环节对应 | -| 7 | 最小体验单位 | 多短一段玩法就能体现独有乐趣 + 反馈铁律 | 原型只做这一个单位——定原型规模 | 是 5 的最小切片；14 验证标准的试验对象 | -| 8 | 核心活动流程 | 段落表：阶段/玩家行为/**设计目的** | "玩这个游戏的一天"的可复述剧本 | 设计目的列写不出的段=该删的段 | -| 9 | 取舍表 | 决策/立即收益/延迟收益/主要代价 | 张力的具体化——玩家决策的路口 | **逐条对应概念层核心张力**（对上接口） | -| 10 | 节奏结构 | 按项目实际存在的时间层级和情绪变化组织 | 说明玩法节奏如何变化 | 与实际推动力层级对应 | -| 11 | 失败与回收 | 亏损定性 + 情况/结果表 | 失败的形态决定调性——"少拿"还是"毁掉" | 对齐概念层情绪基调的边界句 | -| 12 | 系统范围 | 系统/顶层目的/**边界** 表 | 架构层接口：系统地图的种子 | **对下接口**：架构照此拆系统 | -| 13 | 范围与非目标 | 最小完整版本清单 + 不做清单 | 立项交付物的边界 | 承概念层"不是什么"；给 14 提供验证范围 | -| 14 | 验证标准 | 验证点/成功标准（行为判据） | "好玩"不可测，"玩家能复述循环"可测 | 判据对象=7 的最小体验单位 | -| 15 | 开放问题 | 留给架构前必须想清的 | 显式债务清单 | 进分析文档或架构层开题 | -| 16 | 顶层定稿 | 收口重锤 + 给架构的硬约束（必须__/不得__） | 检验全文档没写散；架构的紧箍咒 | 回环呼应 1；承概念层定稿的接力棒 | - -咬合一图： - -``` -概念层定稿（硬约束 + 张力） - ↓ 承接 -1 定位与规模锚点 ───张力落位───► 9 取舍表（逐条对应） - ↓ 展开 -2 设计目标 → 3 核心推动力 → 4 大循环 ⇄ 5 小循环 ⇄ 7 最小体验单位 - ↓ 供血 -6 资源流与输入输出（防无来源/无消耗/套利） - ↓ 后果侧 -8 活动流程（段落表）→ 10 节奏结构 → 11 失败与回收 - ↓ 交付 -12 系统范围（→架构系统地图的种子）＋ 13 范围 ＋ 14 验证标准 - ↓ 收口 -15 开放问题 → 16 顶层定稿（给架构的硬约束） -``` - -三个接口：**对上**承概念定稿、张力逐条变取舍表；**对内**三层循环互检 -（大⇄小⇄最小单位）+ 资源三段全；**对下**系统范围表喂架构的系统地图、 -顶层定稿当架构的紧箍咒、验证标准当原型试玩判据。 - -## 四、怎么写（模板即流程，十六节按序） -（本节是带写法要领的教学版；实际填写使用对应纯净模板。） - -### 1. 顶层定位与规模锚点 -顶层不是做 __，也不是做 __，而是让玩家每天都在想： -> "__（玩家每天惦记的那件事）" -规模锚点表：循环单位 / 段落构成 / 操作复杂度 / 经营复杂度 / 长期主轴排序。 -→ 循环单位先行，定错全盘错。复杂度行可内联参照与"不做"。 - -### 2. 设计目标 -玩家在 __ 循环中同时获得 __、__、__——三者不是并列小游戏，而是互相供给：__。 -→ 检验：砍掉任何一种回报，另外两种是否受伤。 - -### 3. 核心推动力 -- 动机主次：__。 -- 即时推动 __；日程推动 __；季节推动 __；长期推动 __。 -→ 只展开项目实际存在的时间层级；不存在的层级不设字段。 - -### 4. 大循环 -**__ → __ → __ → __ → 回到 __。**（附核心循环图） -→ 检验：断掉任何一环，后面是否塌；每一环应有对应小循环供血。 - -### 5. 小循环（按项目实际数量） -**__循环**：__ → __ → __ → __ → __。 -→ 为保留的循环命名；动词链完整到可以直接照做。 - -### 6. 资源流与输入输出 -（资源流图：每种核心资源 来源 → 储存 → 消耗 三段全） -主要输入 __；主要输出 __；按项目需要记录反馈层级。 -→ 三问：这资源哪来的？存在哪？花在哪去？答不出=资源设计未完成。 - -### 7. 最小体验单位 -__（多短一段玩法体现独有乐趣——原型只做这一个单位）。 -保留的玩家行动应有与玩法相称的可理解反馈；反馈形式和数量按项目决定。 - -### 8. 核心活动流程（段落表） -| 阶段 | 玩家行为 | 设计目的 | -→ 设计目的列必填；写不出目的的段落删掉。这份表要能让陌生人复述 -"玩这个游戏的一天"。 - -### 9. 取舍表 -| 决策 | 立即收益 | 延迟收益 | 主要代价 | -→ 每行挂概念层张力编号；避免唯一最优解；不同选择应产生不同但都合理的玩法方式。 - -### 10. 节奏结构 -日内 __ → 周内 __ → 季节/章节 __ → 长期 __。 -整体情绪在"__"与"__"之间摆动（恢复来源 __；变化来源 __）。 - -### 11. 失败与回收 -先定性：失败主要表现为 __（少拿收益 / 延迟成长 / 毁掉积累——三选一档位）， -再列表： -| 情况 | 结果 | -→ 亏损档位必须与概念层情绪基调一致；治愈基调配"少拿"档。 - -### 12. 系统范围（架构层接口） -| 系统 | 顶层目的 | 边界（本层不做什么） | -→ 只写目的与边界，不写系统内部规则；每行将来对应架构层一个 Sxx。 - -### 13. 范围与非目标 -最小完整版本包含：__。不做清单：__。 - -### 14. 验证标准 -| 验证点 | 成功标准 | -→ 成功标准必须是行为判据（"玩家能复述__""玩家出现__行为"）， - "感觉好玩"不算。 - -### 15. 开放问题 -→ 逐条列出；值得跨轮保留的进分析文档，其余留待架构层开题。 - -### 16. 顶层定稿（收口重锤） -顶层当前定稿为：__（循环单位、核心结构、关键档位一句话说全）。 -后续架构必须围绕 __ 拆系统；不得 __。 - -若某节对本项目没意义，直接省略。 - -## 五、分析文档（全局一份，按层分节） - -**全局唯一一份分析文档**：论证按发生层归节，决定登记表全项目共用，跨层引用只查这里。状态池（灵感池/代决/待原型等活队列）在决策台账， -不放分析文档——本文件只放已决论证与登记。 - -- 条目格式：`## 问题：<一句话>` ＋ 状态（agent_proposal / user_confirmed / - superseded，登记 D-__）＋ 广度分析（牵动面＋候选 ≥2）＋ 深度分析 - （逐候选利弊依据，必须引 T 原则/锚点/张力编号，写不出依据的偏好不进分析） - ＋ 综合判断（建议取 __ 因为 __；推翻条件：__）。 -- 分诊三条件全满足才进：① 影响项目方向或边界；② ≥2 合理候选；③ 一时定不了。 - 不满足的：就地小权衡直接进登记表一行，不写条目。 -- 本层标准两问：① 一天/一局怎样形成清楚但不拖沓的循环；② 风险、收益与长期成长怎样互相支撑。 -- 数量纪律：顶层期问题通常 ≤5（结构性争议天然更多）；堆问题时先回读第 1 节定位句。 -- user_confirmed 后三件事：结论一句话迁入 design.md 对应节（留修订痕迹）； - 登记表加行（编号全项目连续，跨层引用写 D-__）；本条目改状态记 D 号保留不删。 - 推翻时新增行挂旧行编号，旧行不删。 - - -## 六、写完自查（参考，不是闸门） -- 三层循环互检了吗：大循环每环有小循环供血？最小单位切得出来？ -- 概念层张力每条都在取舍表有对应行吗？ -- 每种资源三段全吗（来源/储存/消耗）？ -- 验证标准是行为判据吗，还是写了"好玩"？ -- 架构层拿到系统范围表能直接开工吗——有没有该划没划的系统？ -- 失败档位和概念层基调一致吗？ - -## 七、红线（只有三条） -1. 不冒充用户决定：用户没说的方向标"待确认"，正文不写死。 -2. 不越层：向上不翻概念层的案，向下不写系统内部规则与具体数值。 -3. 不凑数：章节对项目有意义但信息不足时，记录已确定内容与待补问题；章节对项目无意义时，直接省略。 - - -## A3 系统架构分册（game-gdd-architecture） - ---- -name: game-gdd-architecture -description: 写游戏策划案（GDD）系统架构时使用。在顶层设计定稿之后， - 把顶层的系统范围表正式切成 Sxx 系统：编号、职责、依赖、数据流、优先级， - 并向系统文档交付目录映射与 MVP 闭环。 ---- - -# 系统架构写法（策划 · 系统架构分册） - -> 本文件是系统架构层唯一承载写作流程的教学件。 -> 模板与例子文件保持纯净：不含任何步骤、检验提示与标记。 - -## 一、这一层的判断立场 -你是架构师，切系统的刀在你手里。在这个层里你相信： -- 切分是为了**职责清晰、可独立讨论**，不是为了凑数量——每个系统必须能 - 一句话答出"删了它，什么塌"（P0 原因）。 -- **数据所有权唯一**：同一事实只由一个系统维护，其他系统只引用稳定 ID， - 不复制主数据。两个系统管同一件事 = 架构事故。 -- **依赖无环**是硬要求；信息呈现层只读状态、只经行动入口写入。 -- 架构是全项目返工最多的一份（实测 11 版 vs 概念层 2 版）——所以每次改刀 - 都要写变更记录，让"为什么这么切"可追溯。 -- 你不越层：上不重定义玩法循环（那是顶层的），下不写单系统内部规则 - （那是系统文档的），字段定义与数值配置归技术文档层（数值策划）。 - -## 二、动笔前 -1. 顶层设计已定稿可用——把它的**系统范围表**（粗清单）和**顶层定稿约束** - 摊开当输入；切分是对粗清单的正式化（拆、并、裁都在这层做）。 -2. 读取对应示例了解内容组织方式，然后按对应模板填写。 -3. 记住顶层的核心循环图——切完必须跑覆盖检查。 - -## 三、架构设计的组织维度：写什么、为什么、怎么咬合 - -架构文档回答四个问题： -**这个架构为什么这样切（1~3）→ 系统是什么、怎么连接（4~6）→ -怎么落地、怎么验证（7~11）→ 还有什么没想清（12）。** - -第 1 节承顶层的定稿约束开篇，MVP 闭环在中间当守门员，开放问题收尾。 - -| # | 节 | 是什么 | 为什么写 | 和谁咬合 | -|---|---|---|---|---| -| 1 | 架构定位与目标 | 阶段边界（定哪些系统、不展开内部）+ 划分原则 + 一句话架构 + **变更记录** | 防止架构漂离顶层；改刀可追溯 | 承顶层定稿；变更记录引登记编号 | -| 2 | 系统地图 | Sxx 编号清单（=系统文档范围真源）+ 支撑层 + P0 段五列表（目的/输入/输出/P0原因） | 编号让系统可引用；P0 原因逼答"删了塌什么" | **对下真源**：Sxx ↔ 04 系统文档一一对应 | -| 3 | 系统职责 | 职责表（负责/不负责→移交谁）+ 逐系统说明段 | 边界写死，防两个系统管同一件事 | 系统文档的"边界与非目标"必须与此对齐 | -| 4 | 依赖与数据流 | 依赖图（无环）+ 数据流图 + 主要状态 + 主数据归属规则 | 谁读谁、数据从哪到哪——接口的真源 | 顶层的资源流图在此展开成系统级 | -| 5 | 核心循环覆盖检查 | 顶层每个循环环节 → 认领系统 | 顶层→架构的验收线，防切系统切碎循环 | 对上接口：逐环节对照顶层循环图 | -| 6 | 目录映射 | 职责 → 物理文档目录的归并表 | 职责数≠文档数；归并规则显式化 | **对下接口**：系统文档照此开工 | -| 7 | MVP 最小闭环 | 编号验证链 + 守门句（"闭环不成立不许加东西"） | 立项后第一条要跑通的链 | 对应顶层验证标准；失败回顶层而非加系统 | -| 8 | 统一数值基准 | 单位清单 + 四类定性基准（时间/货币/成长/体力风险的风格约束） | 各系统单独配数值会互相失衡；先定全局尺度 | **数值换算与验算归技术文档层**，此处只到定性 | -| 9 | 系统边界 | 哪些功能明确不属于任何系统/归引擎层/归呈现层 | 显式排除，防范围蔓延 | 承概念层"不是什么" | -| 10 | 优先级与范围 | P0/P1/P2 三档（P1/P2 可用能力表） | 拆分≠全做；裁剪顺序显式化 | P0 = MVP 闭环的系统集 | -| 11 | 风险与校验 | 风险/校验方式表 | 架构级风险提前挂出，每条带检验法 | 对应顶层验证标准与概念层跑偏风险 | -| 12 | 开放的结构问题 | 结构级未定案 | 显式债务 | 进分析文档或系统文档开题 | - -咬合一图： - -``` -顶层定稿 + 系统范围表（粗清单） - ↓ 正式切分（拆/并/裁） -1 定位与目标 ──► 2 系统地图（Sxx 真源）──► 3 职责表 - ↓ ↓ ↓ -5 循环覆盖检查 ◄── 4 依赖与数据流（接口真源） - ↓ -6 目录映射 ──► 7 MVP 最小闭环（守门员） - ↓ -8 数值基准（定性）· 9 边界 · 10 优先级 · 11 风险校验 - ↓ -12 开放问题 →（进分析文档 / 系统文档开题） -``` - -三个接口：**对上**承顶层系统范围表并跑循环覆盖检查；**对内**地图↔职责↔依赖 -三方一致、主数据归属唯一；**对下**目录映射 + MVP 闭环喂系统文档。 - -## 四、怎么写（模板即流程，十二节按序） -（本节是带写法要领的教学版；实际填写使用对应纯净模板。） - -### 1. 架构定位与目标 -本阶段确定"哪些系统支撑一轮玩法"，不展开单系统内部规则。 -划分原则：__。一句话架构： -> （玩家通过哪些系统、以什么因果，把一轮玩法的输入变成下一轮的选择） -变更记录：日期 + 改了什么 + 为什么（引登记编号）。 -→ 没有变更记录的架构文档，第二轮迭代就会变成黑箱。 - -### 2. 系统地图 -Sxx 编号清单（核心系统通常 1-5 个，有明确要求可超出 5 个）+ 支撑层（存档/UI，不拥有核心规则）。 -P0 段五列表： -| 系统 | 目的 | 输入 | 输出 | P0 原因 | -→ 对实际拆出的系统说明删除后的影响；无法形成独立职责的部分合并。 - -### 3. 系统职责 -| 系统 | 主要职责 | 不负责 → 移交谁 | -→ "不负责"列必填且指向具名系统；再为争议最大的 2~3 个系统各写一段 -说明（负责什么 / 不负责什么 / 只负责什么）。 - -### 4. 依赖与数据流 -依赖图（mermaid，呈现层用虚线"读取状态"）+ 数据流图（资源从产到耗）。 -主要状态：全局/玩家/场景/社会 四类。 -主数据归属规则：规则与数据表分工 / 稳定 ID 关联 / 任何系统不复制他系统主数据。 -→ 依赖图出现环 = 回去重切。 - -### 5. 核心循环覆盖检查 -| 顶层循环环节 | 认领系统 | -→ 逐环节对照顶层循环图；有环节无人认领或多人认领都是切分错误。 - -### 6. 目录映射 -| 目录 | 本阶段定位 | -→ 职责可以归并进同一文档目录（官方版 8 职责→3 文档）；归并规则写明。 -系统文档以此开工：地图上没有的系统不许有文档。 - -### 7. MVP 最小闭环 -1. __ 2. __ …（编号验证链，一条玩家可走的完整因果） -守门句：如果这条闭环不成立，不应继续增加 __。 -→ 闭环失败回顶层改设计，不是加系统打补丁。 - -### 8. 统一数值基准（定性） -全局单位清单（如时间片/游戏日/货币/体力/经验）+ 四类风格约束 -（时间节奏/货币量级感/成长回报取向/体力风险档位）。 -→ 只写到定性；具体换算、验算数值由技术文档层（数值策划）承接。 - -### 9. 系统边界 -明确排除项（不拆出独立 __ 系统 / __ 归引擎层 / __ 归呈现层）。 - -### 10. 优先级与范围 -P0（最小闭环必需）：__；P1（完整体验）：__；P2（扩展内容）：__。 -P1/P2 可用能力表（能力/说明）控制颗粒度。 - -### 11. 风险与校验 -| 风险 | 校验方式 | -→ 从概念层跑偏风险和顶层失败档位反推；校验方式要可观察。 - -### 12. 开放的结构问题 -→ 结构级（接口归属/统一格式/合并拆分）才留这里；数值细节不留。 - -## 五、分析文档（全局一份，按层分节） - -**全局唯一一份分析文档**：论证按发生层归节，决定登记表全项目共用，跨层引用只查这里。状态池（灵感池/代决/待原型等活队列）在决策台账， -不放分析文档——本文件只放已决论证与登记。 - -- 条目格式：`## 问题：<一句话>` ＋ 状态（agent_proposal / user_confirmed / - superseded，登记 D-__）＋ 广度分析（牵动面＋候选 ≥2）＋ 深度分析 - （逐候选利弊依据，必须引 T 原则/锚点/张力编号，写不出依据的偏好不进分析） - ＋ 综合判断（建议取 __ 因为 __；推翻条件：__）。 -- 分诊三条件全满足才进：① 影响项目方向或边界；② ≥2 合理候选；③ 一时定不了。 - 不满足的：就地小权衡直接进登记表一行，不写条目。 -- 本层标准问题：结构级争议——接口统一、系统归并、主数据归属划分。 -- 数量纪律：按需；架构期问题多为接口与归属二义。 -- user_confirmed 后三件事：结论一句话迁入 design.md 对应节（留修订痕迹）； - 登记表加行（编号全项目连续，跨层引用写 D-__）；本条目改状态记 D 号保留不删。 - 推翻时新增行挂旧行编号，旧行不删。 - - -## 六、写完自查（参考，不是闸门） -- 每个 Sxx 都能一句话答"删了它什么塌"吗？ -- 顶层的循环环节全覆盖、无重复认领吗？ -- 依赖图无环？主数据无一物两管？ -- 系统文档拿到目录映射能直接开工吗？ -- 有没有字段定义或数值配置偷偷写进来？（该在技术文档层） -- 变更记录补了吗——这次切分和上次的差异说得清吗？ - -## 七、红线（只有三条） -1. 不冒充用户决定：用户没说的方向标"待确认"，正文不写死。 -2. 不越层：向上不翻顶层的案，向下不写系统内部规则，数值字段归技术文档层。 -3. 不凑数：系统数量不是成绩，写不出 P0 原因的系统就是该删的系统。 - - -## A4 系统文档分册（game-gdd-system-doc） - ---- -name: game-gdd-system-doc -description: 写单个系统的设计文档（Sxx）时的总纲——通用纪律、十二类常见内容、 - 红线与分析文档格式。 ---- - -# 系统文档写法（策划 · 系统文档分册 · 总纲） - -> 本文件是系统文档层的总纲；通用纪律不在各系统写法里重复。 - -## 一、这一层的判断立场 -你是写单个系统的策划。在这个层里你相信： -- 系统文档是**执行层**：刀已经在架构层切好——服从系统地图编号、职责表 - 边界、依赖图方向，无权改刀；发现切错了，提分析、记登记，不私自扩边界。 -- 一个系统文档的成败在**边界节**："不负责什么、移交给谁"那几行是 - 防返工价值最高的几行。 -- 接口纪律：引用具名系统与具名数据，禁泛称；别家主数据只引 ID 不复制。 -- 字段定义、数值配置、表结构不归你——写交接声明，交技术文档层（数值策划）。 -- 系统文档保持基本可读的一致性，但不要求所有系统使用相同章节；结构应服从系统类型和实际行为。 - -## 二、动笔前 -1. 架构已定稿：找到本系统的 Sxx 编号、职责表行、依赖方向——这是合同。 -2. 选择最接近的系统类型（可组合，如"钓鱼"=采集+战斗的判定部分），使用对应的系统写法与模板。 -3. 该文件夹标注"必读例子"的，先读例子全文了解对应系统的内容组织方式。 - -## 三、系统文档的组织维度：写什么、为什么、怎么咬合 - -系统文档回答四个问题： -**这个系统为什么存在（1~2）→ 玩家怎么用它（3~5）→ 它怎么运转（6~8）→ -它怎么和别人连接、不碰什么（9~12）。** - -| # | 节 | 是什么 | 为什么写 | 和谁咬合 | -|---|---|---|---|---| -| 1 | 系统目的 | 一句话：删了它什么塌 | 存在性检验 | 架构 P0 原因的展开 | -| 2 | 支撑的玩家体验 | 对应顶层目标第几条 | 防系统自嗨 | 顶层设计目标 ↔ 本系统 | -| 3 | 进入与退出 | 何时进入、何时/如何退出 | 循环的接口时刻 | 顶层的循环环节 | -| 4 | 玩家行动 | 具名动词组 | 玩家用手玩 | 系统类型卡给动词组 | -| 5 | 取舍表 | 玩家在本系统内的决策 | 张力在系统内的落地 | 概念张力→顶层取舍表→本表 | -| 6 | 状态与规则 | 对象/状态/转换/异常，枚举表达 | 定性规则真源 | 架构职责表对齐 | -| 7 | 数值与数据交接 | 本系统交 TDD 的数据类别+定性约束 | 分层边界 | 技术文档层承接 | -| 8 | 反馈 | 关键结果何时、以何种方式反馈 | 让实际结果可理解 | 与本系统实际结果对应 | -| 9 | 内部循环 | 本系统内的小循环 | 系统自己的心跳 | 顶层小循环的组成 | -| 10 | 输入、输出与依赖 | 消费/交付/依赖谁 | 接口真源 | 架构依赖图逐边对齐 | -| 11 | 边界与非目标 | 不负责什么→移交谁 | **防返工价值最高** | 架构职责表"不负责"列 | -| 12 | 开放问题 | 本系统未定案 | 显式债务 | 进分析文档 | - -咬合：**对上**服从架构三条合同（编号/职责/依赖）；**对内**状态与接口不越 -职责边界；**对下**第 7 节交接喂 TDD。 - -## 四、常见内容的参考写法 -（各系统类型的特殊写法与纯净模板按对应类型取用。） - -1 系统目的：若删除它，__ 会塌——一句话说不出 = 该系统不该存在。 -2 支撑体验：对应顶层目标第__条、调性原则第__条。 -3 进入与退出：按本系统实际存在的入口、退出和恢复路径记录。 -4 玩家行动：记录本系统实际存在的具名动词组；编排类写"安排"动词，活动类写"操作"动词。 -5 取舍表：决策/立即收益/延迟收益/主要代价；挂顶层张力编号。 -6 状态与规则：对象-状态-转换-异常，全部枚举表达，不许整段散文。 -7 数值与数据交接：列数据类别名 + 设计侧定性约束；字段定义归 TDD。 -8 反馈：记录本系统关键结果的可理解反馈；存在失败时说明原因和恢复路径。 -9 内部循环：动词链；可拆单次/区域/长期三层。 -10 输入输出与依赖：引用具名系统与具名数据，禁泛称"资源"。 -11 边界与非目标：参考该类型系统写法的“三不”说明边界；建议说明字段与数值的交接边界。 -12 开放问题：结构级才留；手感数值类标"待原型验证"。 - -## 五、分析文档（全局一份，按层分节） - -**全局唯一一份分析文档**：论证按发生层归节，决定登记表全项目共用，跨层引用只查这里。状态池（灵感池/代决/待原型等活队列）在决策台账， -不放分析文档——本文件只放已决论证与登记。 - -- 条目格式：`## 问题：<一句话>` ＋ 状态（agent_proposal / user_confirmed / - superseded，登记 D-__）＋ 广度分析（牵动面＋候选 ≥2）＋ 深度分析 - （逐候选利弊依据，必须引 T 原则/锚点/张力编号，写不出依据的偏好不进分析） - ＋ 综合判断（建议取 __ 因为 __；推翻条件：__）。 -- 分诊三条件全满足才进：① 影响项目方向或边界；② ≥2 合理候选；③ 一时定不了。 - 不满足的：就地小权衡直接进登记表一行，不写条目。 -- 本层标准问题：① 本系统与相邻系统的边界在哪；② 本系统内部哪个规则影响顶层取舍。条目标系统号（如 S06）。 -- 数量纪律：按需；每系统通常 0~1 条，超了先回读架构职责表。 -- user_confirmed 后三件事：结论一句话迁入 design.md 对应节（留修订痕迹）； - 登记表加行（编号全项目连续，跨层引用写 D-__）；本条目改状态记 D 号保留不删。 - 推翻时新增行挂旧行编号，旧行不删。 - - -## 六、写完自查（参考，不是闸门） -- 目的一句话成立吗？边界节和架构职责表逐行对齐吗？ -- 输入输出和依赖图逐边对上吗？有没有泛称漏网？ -- 状态是枚举还是散文？失败路径给了原因和恢复吗？ -- 有没有字段或数值偷偷写进来？（该在 TDD） -- 同构检查：另一份系统文档的读者能按同样方式读这份吗？ - -## 七、红线（只有三条） -1. 不冒充用户决定：用户没说的方向标"待确认"，正文不写死。 -2. 不越层：不翻架构的案（要改走分析文档+登记表），不写字段数值（归 TDD）， - 不替别的系统定规则。 -3. 不凑数：写不出"删了塌什么"的系统直接删除；章节对项目有意义但信息不足时，记录已确定内容与待补问题。 - - -## A5 技术文档分册（game-tdd） - ---- -name: game-tdd -description: 写游戏技术文档（TDD）时使用的总纲。GDD 四层定稿后的第五步：把 - "怎么做"写实——程序怎么写、美术怎么做、字段怎么定义、怎么配表。 - 三大件各有专属分册：技术实现（程序侧）/ 美术圣经（美术侧）/ 数据与配表（数据侧）。 ---- - -# 技术文档写法（策划 · TDD 分册 · 总纲） - -> 本文件是 TDD 层唯一承载写作流程的教学件；各分册写法与模板配套使用。 -> 模板与例子文件保持纯净：不含任何步骤、检验提示与标记。 - -## 〇、TDD 的完成判据（总纲） - -**TDD 是当前版本的施工合同：施工方只看 TDD，应能完成本项目实际范围内的实现。** -GDD 是设计真源（给人看、给迭代看）；TDD 是构建真源（给施工看）。 -检验方式＝自足性检查（见总册）：不看 GDD 能否回答——每个系统怎么行为、 -每张表多少行内容、每个界面怎么走、每份素材什么规格。答不出的项就是缺口， -缺口回 GDD 同步后**收编**进 TDD（带版本锁）。收编是构建期快照：GDD 定稿 -变更 → 触发对应收编节重同步。 - -## 一、这一层的判断立场 - -你是工程师思维的策划。GDD 是"用户视角的功能描述"，TDD 是"实现者视角的 -架构性描述"——你不重复设计的论证（为什么这样设计，去 GDD 和分析文档查）， -只写怎么落地。你相信： - -- **交接契约是 TDD 最大的价值**：美术交给程序的素材、程序读的表、加载的 - 顺序——每一条缝都写死。缝上不写死，返工就在缝里发生。 -- **平台事实优先**：目标运行时由 GDD 平台事实锁定——**HTML / Unity / Godot / - Cocos 四选一**。HTML 项纯 HTML/CSS/JS 交付；引擎项支持打开引擎工程、自然 - 语言协作改素材与代码；预览与导出按所选引擎的平台流程执行。 - 一切技术选择先过所选运行时这道闸，不推荐该运行时做不出来的东西； - TDD 不擅自换运行时。 -- **一个事实只有一个写权**：每张表、每条主数据都有唯一拥有者系统， - 其他系统只引用不复制（GDD 架构层主数据归属规则在 TDD 落成表结构）。 -- **验收是硬闸不是仪式**：有 blocker 禁止扩充内容。 -- **先少量验证再量产**（美术）/ **先建索引再转表**（数据）——任何方向都 - 不做"做完一大批才发现不对"的事。 - -## 二、TDD 与 GDD 的接口（输入从哪来） - -| 输入 | 来自 | 喂给哪件 | -|---|---|---| -| 系统范围表 + P0 清单 + 主数据归属规则 | 架构层 | 三件共用（拆表与拆模块依据） | -| 各系统「数值与数据交接」节 + 定性约束 | 系统文档 | 数据侧（直接订单） | -| 定调记录（参照/滑杆/T 原则）+ 身份基调 | 概念层 | 美术圣经（视觉翻译源头） | -| 可复用能力 | 能力库 | 程序侧+美术圣经（带版本与实例化参数） | - -TDD 不回头改 GDD：发现 GDD 没写清楚的点，走「开放问题回执」——该问用户 -的升级决策卡，该代决的记台账（带理由和推翻条件），结论回写对应层，TDD 只 -登记去向。顾问期（开发阶段）同一出口：程序美术卡点、成品与文档偏差，都从 -回执进、修订出（v{N+1}）。 - -## 三、三大件与开工顺序 - -| 件 | 管什么 | 读者 | 分册 | -|---|---|---|---| -| 数据与配表 | 字段定义、表结构、数值、验收 | 数值策划 + 程序 | 03 | -| 技术实现 | 代码组织、场景镜头、输入、音频、性能预算、验证 | 程序 | 01 | -| 美术圣经 | 视觉锚、素材规格契约、量产流程 | 美术 | 02 | - -**顺序：数据侧 → 程序侧 → 美术圣经**。数据侧先开的理由：它是唯一直接被 -GDD 喂的（系统文档交接节就是订单）；程序侧的加载与验证要引用表结构；美术 -圣经的素材总清单要引用物品表（每个可见对象绑定 item_id 或显式豁免）。小型 -项目三件可交叉，但**表结构永远先于数值填充**。 - -## 四、怎么写（总纲级；细节在各分册） - -1. 数据侧：总清单拆表 → ID 与字段字典 → 公共条件表 → 建表顺序（物品表 - 起步）→ 表结构契约（程序签名）→ 数值填充（代决+台账）→ 验收七查。 -2. 程序侧：系统实现总览（每系统一段话写死怎么做）→ 技术选型与可复用能力引用 - → 场景与镜头 → 输入与操作 → 音频 → 验证方式与性能预算。 -3. 美术圣经：视觉锚（从概念层定调翻译）→ 素材规格契约逐素材一行 → - 量产流程（概念候选→锚点确认→小批→验收→扩产）→ 资产总清单。 - -## 五、写完自查（参考，不是闸门） - -- 任意一条缝（美术→程序、表→代码、表→表引用）是否都写死了规格？ -- 每张表是否答得出"谁是拥有者系统"？每个 ID 是否全局唯一？ -- 程序侧验证方式是否可执行（跑什么命令、看什么输出）？ -- 素材契约是否覆盖了 GDD 里全部可见对象（或显式豁免）？ -- 验收是否跑过且无 blocker？ - -## 六、红线（只有四条） - -1. **收编必带版本锁**：从 GDD 收编的任何内容标注"基于系统文档@v{N}"； - 无锁收编=违规（双源漂移之源）。TDD 不产生设计观点，只汇集与落实施工。 -2. 引用必带版本：可复用能力引用必须记录版本与实例化参数，选型时与执行时用的一致性靠此保证。 -3. 不越权拍板：产品级取舍回 GDD 层走决策流程；TDD 只做技术代决且记台账。 -4. 表里不写散文：单元格只有数据和枚举；规则写在契约文档，不写在表里。 - - - - -## A1 概念层分册（game-gdd-concept） - ---- -name: game-gdd-concept -description: 写游戏策划案（GDD）概念层时使用。把一句话游戏想法写成一份 - "一次写对、之后不动"的立项概念文档——它是后续所有设计争议的仲裁依据。 - 任何游戏类型通用。 ---- - -# 概念层写法（策划 · 概念层分册） - -> 本文件是概念层唯一承载写作流程的教学件。 -> 模板与例子文件保持纯净：不含任何步骤、检验提示与标记。 - -## 一、这一层的判断立场 -你是资深游戏策划，看过上千份概念案，清楚绝大多数死在"什么都说、什么都不尖"。 -在这个层里你相信： -- 概念的成败在取舍，不在丰富：一句话里卖点只许有一个。 -- 你写的是裁判文档：后续每一层的设计争议，都要能回到这里找到仲裁。 -- 具体压倒抽象："压力很大"是废字，"每开一扇门都在烧自己的命"才是概念。 -- 用户没说过的话不当他说过：宁可标"待确认"，不替人拍板。 -- 发现自己在堆形容词 = 概念没想清楚：停笔回去问，别用空话盖过去。 -- 概念层是"一次写对、之后不动"的层（实作中它的返工率远低于架构与 - 系统层），所以判断力要前置堆足，不要指望后面回来改。 - -## 二、动笔前 -1. 拿到用户真实回答过的定调信息（参照对象、题材偏好、压力档位）。 - 没有 → 先问一个定调问题，禁止自问自答充当用户。 -2. 读取对应示例了解内容组织方式，然后按对应模板填写。 -3. 零参照时在文档头注明"零参照"。 - -## 三、概念设计的组织维度：写什么、为什么、怎么咬合 - -概念文档回答四个问题： -**这是什么（1~5）→ 它不是什么（6）→ 它靠什么让人一直玩（7）→ -它管到哪、交出什么（8~9）。** - -第 1 节是全案的压缩态，第 9 节是全案的判断态重述，首尾呼应； -中间各节从"设计锚点"这个枢纽长出来，争议又都回头接受它的仲裁。 - -| # | 节 | 是什么 | 为什么写 | 和谁咬合 | -|---|---|---|---|---| -| 1 | 一句话概念 | 全案压缩成一句：品类+融合+唯一卖点 | 概念的第一命运是被转述；这句立不住，后面写得再好都救不回来 | 9 是它的重述；2 是它的展开 | -| 2 | 定调与设计锚点 | 定调记录（参照/滑杆/T 原则，调性真源）+ 六个仲裁位：幻想/体验/动机/循环/跑偏/非目标 | 概念层把调定死：后续所有开放问题先回定调记录级联（约八成可就地定），级联不掉的才上决策卡；概念文档的核心职能是当裁判 | **全文档枢纽**：3~6 由它长出；7 由它的循环与动机抽出；定调记录被顶层及以下所有层引用 | -| 3 | 玩家身份与基调 | 玩家在虚构里是谁 + 情绪温度与红线 | 幻想需要一张脸和一种温度，否则是空话；基调边界句防调性漂移 | 身份 = 幻想的具象化；基调 = 目标体验的情绪面 | -| 4 | 风格与世界观 | 支撑玩法的世界规则 + 叙事载体 | 世界观是给玩法供氧的背景板，不是设定集 | 服务 3 的身份与基调；世界规则支撑 2 的核心循环成立 | -| 5 | 目标玩家与情境 | 为谁、什么场景、门槛多高 | 同一设计对不同人是不同游戏；受众映射防止"谁都适合=谁都不适合" | 反面校验 2 的目标体验；情境（一局多久）给 7 的循环定参数 | -| 6 | 不是什么 | 负面定位表：不是 X，因为 Y | 正面定义写多必然发散；负面定位用"误会方向+封死原因"收边界，比光秃的非目标锋利一档 | 2 的非目标与跑偏风险的表化展开；与 5 的防串味声明呼应 | -| 7 | 核心张力 | 玩家持续面对的两难，两端各有代价 | 长期游玩的根本动力；没有张力，再丰富的内容玩几次就腻 | **向下接口**：每条张力必须在顶层变成取舍表里的具体决策 | -| 8 | 边界与约束 | 本层只定什么、什么留给后面 + 规模回流 | 防止概念层越层写数值和系统（越层是下游返工之源）；给写作画线 | 保护 2 的纯度；告诉顶层"你们的地盘从哪开始" | -| 9 | 概念定稿 | "核心不是 __ 而是 __"重述 + 按需记录给顶层的约束 | 收口并检查概念是否写散；把承诺转成对下的契约 | 回环呼应 1；把边界和交接约束传给下一层 | - -咬合一图： - -``` - 1 一句话概念（压缩态） - ↓ 展开 - 2 设计锚点（枢纽 · 仲裁位）◄── 所有节的争议回来找它 - ├→ 3 身份基调 ──→ 4 风格世界观（给玩法供氧） - ├→ 5 目标玩家（反面校验）──→ 6 不是什么（负面收边） - └→ 7 核心张力（动力结构）──→ 【交给顶层】取舍表 - 8 边界与约束（画线：本层到此为止） - ↓ 回环 - 9 概念定稿（判断态重述 + 交接契约） -``` - -记住三个接口：**对内**锚点仲裁一切；**对下**张力变取舍表、定稿变硬约束； -**对上**边界画线防止越层。九节不是清单，是一台咬合的机器。 - -## 四、怎么写（模板即流程，九节按序） -（本节是带写法要领的教学版；实际填写使用对应纯净模板。） - -### 1. 一句话概念 -《__》是一款 __（品类与融合）：玩家通过 __，把 __ 逐步 __。 -→ 45~90 字，卖点唯一。检验：删掉那个卖点句子依然成立，说明没写对。 - -### 2. 定调与设计锚点（先定调，再立仲裁位） -**定调记录**（全项目调性真源，此节定死）： -- 参照选择：以 __ 为主、__ 学 __（参照即定调，选完调性随之而来）。 -- 调性滑杆：压力感/战斗比重/管理深度/叙事比重/节奏，各一档。 -- 调性锚 T 原则：按项目需要提炼并逐条具名（如"T2 不劝退——凡惩罚类问题默认取最轻档"）。 - 检验：每条 T 都能当一句 IF-THEN 用——"凡__类问题默认__"；写不出口径的 T 是空话。 - → 下游每个开放问题先来这里级联批量起草，级联不了的才升级提问。 -**设计锚点（六项，争议时的仲裁原则，全部具名）** -- 核心幻想：一句描述 + 一句玩家念头（引号写出玩家脑中的自言自语）。 - 检验：念头句写不出来 = 幻想没立住，回去重想，不要用描述糊弄。 -- 目标体验：何时感到什么。 -- 玩家动机：短期 __；长期 __。 -- 核心循环：__ → __ → __ → __ → 回到 __（箭头式）。 -- 跑偏风险：本项目可能的真实偏航，不放万金油。 -- 非目标：一行带过，详表见第 6 节。 - -### 3. 玩家身份与基调 -- 玩家身份：玩家在虚构里是谁 + 本项目的核心节奏，一口气说清。 -- 情绪基调：正面定调 + 边界句——"可以 __，不可以 __"。 - -### 4. 风格与世界观 -世界观为 __（玩法）服务；叙事通过 __（载体）展开。禁编年史、种族志。 - -### 5. 目标玩家与情境（受众映射三件套） -- 与谁的受众重合；吸收了谁的什么需求；**为什么不会变成它**（防串味声明， - 参照越多越必须有这句）。 -- 情境与门槛：单人/多人；一局多久；需要理解 __，不应要求 __。 - -### 6. 不是什么（负面定位表） -| 不是 | 因为 | -→ 每行原因要封死一条具体误会方向（例：不是武器店经营｜武器主要拿去 - 战斗，不是卖给顾客）。从锚点的非目标与跑偏风险长出来，通常 4~6 行。 - -### 7. 核心张力 -- __ 有限，但 __。 -- __ vs __（两端的代价各是什么）。 -→ 如果项目存在核心张力，保留的每条张力都应说明双方代价；没有形成有效张力时，不为了满足结构新增张力。这些是顶层取舍表的种子，后面按需对应。 - -### 8. 边界与约束 -- 概念边界放首位：本层只定幻想、用户、基调与排除方向；具体数值、 - 系统清单、MVP 内容留给顶层及以后。 -- 规模与回流：单人可维护；所有系统回流核心循环。 -- 参照声明：学组织方式，不复制角色/文本/美术/数值。 - -### 9. 概念定稿（收口重锤） -这个游戏的核心不是 __，而是： -> （一句话重述核心承诺） -交给下一层的约束：按项目需要记录，顶层据此展开。 - -若某节对本项目没意义，直接省略。 - -## 五、分析文档（全局一份，按层分节） - -**全局唯一一份分析文档**：论证按发生层归节，决定登记表全项目共用，跨层引用只查这里。状态池（灵感池/代决/待原型等活队列）在决策台账， -不放分析文档——本文件只放已决论证与登记。 - -- 条目格式：`## 问题：<一句话>` ＋ 状态（agent_proposal / user_confirmed / - superseded，登记 D-__）＋ 广度分析（牵动面＋候选 ≥2）＋ 深度分析 - （逐候选利弊依据，必须引 T 原则/锚点/张力编号，写不出依据的偏好不进分析） - ＋ 综合判断（建议取 __ 因为 __；推翻条件：__）。 -- 分诊三条件全满足才进：① 影响项目方向或边界；② ≥2 合理候选；③ 一时定不了。 - 不满足的：就地小权衡直接进登记表一行，不写条目。 -- 本层标准两问：① 什么是本项目不可替代的核心承诺；② 什么内容扩张会稀释它。 -- 数量纪律：概念期问题通常 ≤3；开始堆第 4 问时先怀疑概念层没想清楚，重读定调记录而不是继续开新争议。 -- user_confirmed 后三件事：结论一句话迁入 design.md 对应节（留修订痕迹）； - 登记表加行（编号全项目连续，跨层引用写 D-__）；本条目改状态记 D 号保留不删。 - 推翻时新增行挂旧行编号，旧行不删。 - - -## 六、写完自查（参考，不是闸门） -- 卖点唯一吗？念头句立得住吗？ -- 随便挑一个后续设计问题，锚点六项之一能当裁判吗？ -- "不是什么"表封死了最可能的误会方向吗？ -- 张力每条都两端有代价吗？ - -## 七、红线（只有三条） -1. 不冒充用户决定：用户没说的方向标"待确认"，正文不写死。 -2. 不越层：出现具体数值、按键、界面即删。 -3. 不凑数：章节对项目有意义但信息不足时，记录已确定内容与待补问题；章节对项目无意义时，直接省略。 - - - - -## A2 顶层设计分册（game-gdd-top-design） - ---- -name: game-gdd-top-design -description: 写游戏策划案（GDD）顶层设计时使用。在概念层定稿之后， - 回答"玩家为什么一直玩"——把概念变成可玩的时间结构（循环/资源/取舍/节奏）， - 并向架构层交付系统范围。 ---- - -# 顶层设计写法（策划 · 顶层设计分册） - -> 本文件是顶层设计唯一承载写作流程的教学件。 -> 模板与例子文件保持纯净：不含任何步骤、检验提示与标记。 - -## 一、这一层的判断立场 -你是资深游戏策划，正在写全 GDD 最重要的一份文档——概念说"凭什么成立"， -顶层说"好玩在哪"。核心循环无趣，后面写再多系统也救不回来。在这个层里你相信： -- 循环优先：先把大循环、小循环、最小体验单位三层跑通，再谈其他一切。 -- 用玩家的手写，不用系统的嘴写：写"玩家在做什么、在想什么"， - 不写"系统提供了什么功能"。 -- 每个时间段的痛苦和甜都要有来处：取舍表接概念层的张力，节奏接情绪摆动。 -- 资源守恒直觉：每种资源必问来源、储存、消耗——无来源是白给， - 无消耗是废物，环环相扣成套利。 -- 你不替概念层翻案（张力与定稿已定），也不替架构层拆系统（只划边界）。 - -## 二、动笔前 -1. 概念层结论文档已定稿可用——顶层定位与取舍表直接从它长出来。 -2. 读取对应示例了解内容组织方式，然后按对应模板填写。 -3. 把概念层已确认的核心张力作为输入；存在对应取舍时再挂上编号。 - -## 三、顶层设计的组织维度：写什么、为什么、怎么咬合 - -顶层文档回答四个问题： -**玩家在玩什么（1~9）→ 玩家面对什么选择与后果（10~11）→ -交给架构什么（12~14）→ 没想清什么、定了什么（15~16）。** - -第 1 节承概念定稿开篇，第 16 节给架构硬约束收口，首尾呼应； -中段三层循环互检，资源流从底下供血。 - -| # | 节 | 是什么 | 为什么写 | 和谁咬合 | -|---|---|---|---|---| -| 1 | 顶层定位与规模锚点 | 承概念定稿 + "让玩家每天都在想"念头句 + 不是X不是Y + 规模参数表（循环单位/段落/复杂度/长期主轴） | 循环单位定错全盘错；定位句防止顶层漂离概念 | 承概念层"概念定稿"；念头句是概念层玩家念头的时间维度版 | -| 2 | 设计目标 | 几种回报、如何互相供给 | 回报并列=小游戏拼盘；互相供给才是循环 | 供给关系落到 4~5 的循环里 | -| 3 | 核心推动力 | 按项目实际存在的即时、阶段或长期推动力组织 | 玩家"什么时候被什么推着走"的推动结构 | 与实际节奏结构对应 | -| 4 | 大循环 | 跨较长时间的循环：文字箭头 + 核心循环图 | 长期留存的结构骨架 | 与 5、7 三层互检：大循环的每环应有小循环供血 | -| 5 | 小循环 | 按项目实际存在的局内或短周期动词链组织 | 记录真正被玩到的循环 | 按实际循环层级互检 | -| 6 | 资源流与输入输出 | 按项目实际存在的资源流、输入输出和反馈组织 | 说明循环中的实际供给与结果 | 与实际循环环节对应 | -| 7 | 最小体验单位 | 多短一段玩法就能体现独有乐趣 + 反馈铁律 | 原型只做这一个单位——定原型规模 | 是 5 的最小切片；14 验证标准的试验对象 | -| 8 | 核心活动流程 | 段落表：阶段/玩家行为/**设计目的** | "玩这个游戏的一天"的可复述剧本 | 设计目的列写不出的段=该删的段 | -| 9 | 取舍表 | 决策/立即收益/延迟收益/主要代价 | 张力的具体化——玩家决策的路口 | **逐条对应概念层核心张力**（对上接口） | -| 10 | 节奏结构 | 按项目实际存在的时间层级和情绪变化组织 | 说明玩法节奏如何变化 | 与实际推动力层级对应 | -| 11 | 失败与回收 | 亏损定性 + 情况/结果表 | 失败的形态决定调性——"少拿"还是"毁掉" | 对齐概念层情绪基调的边界句 | -| 12 | 系统范围 | 系统/顶层目的/**边界** 表 | 架构层接口：系统地图的种子 | **对下接口**：架构照此拆系统 | -| 13 | 范围与非目标 | 最小完整版本清单 + 不做清单 | 立项交付物的边界 | 承概念层"不是什么"；给 14 提供验证范围 | -| 14 | 验证标准 | 验证点/成功标准（行为判据） | "好玩"不可测，"玩家能复述循环"可测 | 判据对象=7 的最小体验单位 | -| 15 | 开放问题 | 留给架构前必须想清的 | 显式债务清单 | 进分析文档或架构层开题 | -| 16 | 顶层定稿 | 收口重锤 + 给架构的硬约束（必须__/不得__） | 检验全文档没写散；架构的紧箍咒 | 回环呼应 1；承概念层定稿的接力棒 | - -咬合一图： - -``` -概念层定稿（硬约束 + 张力） - ↓ 承接 -1 定位与规模锚点 ───张力落位───► 9 取舍表（逐条对应） - ↓ 展开 -2 设计目标 → 3 核心推动力 → 4 大循环 ⇄ 5 小循环 ⇄ 7 最小体验单位 - ↓ 供血 -6 资源流与输入输出（防无来源/无消耗/套利） - ↓ 后果侧 -8 活动流程（段落表）→ 10 节奏结构 → 11 失败与回收 - ↓ 交付 -12 系统范围（→架构系统地图的种子）＋ 13 范围 ＋ 14 验证标准 - ↓ 收口 -15 开放问题 → 16 顶层定稿（给架构的硬约束） -``` - -三个接口：**对上**承概念定稿、张力逐条变取舍表；**对内**三层循环互检 -（大⇄小⇄最小单位）+ 资源三段全；**对下**系统范围表喂架构的系统地图、 -顶层定稿当架构的紧箍咒、验证标准当原型试玩判据。 - -## 四、怎么写（模板即流程，十六节按序） -（本节是带写法要领的教学版；实际填写使用对应纯净模板。） - -### 1. 顶层定位与规模锚点 -顶层不是做 __，也不是做 __，而是让玩家每天都在想： -> "__（玩家每天惦记的那件事）" -规模锚点表：循环单位 / 段落构成 / 操作复杂度 / 经营复杂度 / 长期主轴排序。 -→ 循环单位先行，定错全盘错。复杂度行可内联参照与"不做"。 - -### 2. 设计目标 -玩家在 __ 循环中同时获得 __、__、__——三者不是并列小游戏，而是互相供给：__。 -→ 检验：砍掉任何一种回报，另外两种是否受伤。 - -### 3. 核心推动力 -- 动机主次：__。 -- 即时推动 __；日程推动 __；季节推动 __；长期推动 __。 -→ 只展开项目实际存在的时间层级；不存在的层级不设字段。 - -### 4. 大循环 -**__ → __ → __ → __ → 回到 __。**（附核心循环图） -→ 检验：断掉任何一环，后面是否塌；每一环应有对应小循环供血。 - -### 5. 小循环（按项目实际数量） -**__循环**：__ → __ → __ → __ → __。 -→ 为保留的循环命名；动词链完整到可以直接照做。 - -### 6. 资源流与输入输出 -（资源流图：每种核心资源 来源 → 储存 → 消耗 三段全） -主要输入 __；主要输出 __；按项目需要记录反馈层级。 -→ 三问：这资源哪来的？存在哪？花在哪去？答不出=资源设计未完成。 - -### 7. 最小体验单位 -__（多短一段玩法体现独有乐趣——原型只做这一个单位）。 -保留的玩家行动应有与玩法相称的可理解反馈；反馈形式和数量按项目决定。 - -### 8. 核心活动流程（段落表） -| 阶段 | 玩家行为 | 设计目的 | -→ 设计目的列必填；写不出目的的段落删掉。这份表要能让陌生人复述 -"玩这个游戏的一天"。 - -### 9. 取舍表 -| 决策 | 立即收益 | 延迟收益 | 主要代价 | -→ 每行挂概念层张力编号；避免唯一最优解；不同选择应产生不同但都合理的玩法方式。 - -### 10. 节奏结构 -日内 __ → 周内 __ → 季节/章节 __ → 长期 __。 -整体情绪在"__"与"__"之间摆动（恢复来源 __；变化来源 __）。 - -### 11. 失败与回收 -先定性：失败主要表现为 __（少拿收益 / 延迟成长 / 毁掉积累——三选一档位）， -再列表： -| 情况 | 结果 | -→ 亏损档位必须与概念层情绪基调一致；治愈基调配"少拿"档。 - -### 12. 系统范围（架构层接口） -| 系统 | 顶层目的 | 边界（本层不做什么） | -→ 只写目的与边界，不写系统内部规则；每行将来对应架构层一个 Sxx。 - -### 13. 范围与非目标 -最小完整版本包含：__。不做清单：__。 - -### 14. 验证标准 -| 验证点 | 成功标准 | -→ 成功标准必须是行为判据（"玩家能复述__""玩家出现__行为"）， - "感觉好玩"不算。 - -### 15. 开放问题 -→ 逐条列出；值得跨轮保留的进分析文档，其余留待架构层开题。 - -### 16. 顶层定稿（收口重锤） -顶层当前定稿为：__（循环单位、核心结构、关键档位一句话说全）。 -后续架构必须围绕 __ 拆系统；不得 __。 - -若某节对本项目没意义，直接省略。 - -## 五、分析文档（全局一份，按层分节） - -**全局唯一一份分析文档**：论证按发生层归节，决定登记表全项目共用，跨层引用只查这里。状态池（灵感池/代决/待原型等活队列）在决策台账， -不放分析文档——本文件只放已决论证与登记。 - -- 条目格式：`## 问题：<一句话>` ＋ 状态（agent_proposal / user_confirmed / - superseded，登记 D-__）＋ 广度分析（牵动面＋候选 ≥2）＋ 深度分析 - （逐候选利弊依据，必须引 T 原则/锚点/张力编号，写不出依据的偏好不进分析） - ＋ 综合判断（建议取 __ 因为 __；推翻条件：__）。 -- 分诊三条件全满足才进：① 影响项目方向或边界；② ≥2 合理候选；③ 一时定不了。 - 不满足的：就地小权衡直接进登记表一行，不写条目。 -- 本层标准两问：① 一天/一局怎样形成清楚但不拖沓的循环；② 风险、收益与长期成长怎样互相支撑。 -- 数量纪律：顶层期问题通常 ≤5（结构性争议天然更多）；堆问题时先回读第 1 节定位句。 -- user_confirmed 后三件事：结论一句话迁入 design.md 对应节（留修订痕迹）； - 登记表加行（编号全项目连续，跨层引用写 D-__）；本条目改状态记 D 号保留不删。 - 推翻时新增行挂旧行编号，旧行不删。 - - -## 六、写完自查（参考，不是闸门） -- 三层循环互检了吗：大循环每环有小循环供血？最小单位切得出来？ -- 概念层张力每条都在取舍表有对应行吗？ -- 每种资源三段全吗（来源/储存/消耗）？ -- 验证标准是行为判据吗，还是写了"好玩"？ -- 架构层拿到系统范围表能直接开工吗——有没有该划没划的系统？ -- 失败档位和概念层基调一致吗？ - -## 七、红线（只有三条） -1. 不冒充用户决定：用户没说的方向标"待确认"，正文不写死。 -2. 不越层：向上不翻概念层的案，向下不写系统内部规则与具体数值。 -3. 不凑数：章节对项目有意义但信息不足时，记录已确定内容与待补问题；章节对项目无意义时，直接省略。 - - - - -## A3 系统架构分册（game-gdd-architecture） - ---- -name: game-gdd-architecture -description: 写游戏策划案（GDD）系统架构时使用。在顶层设计定稿之后， - 把顶层的系统范围表正式切成 Sxx 系统：编号、职责、依赖、数据流、优先级， - 并向系统文档交付目录映射与 MVP 闭环。 ---- - -# 系统架构写法（策划 · 系统架构分册） - -> 本文件是系统架构层唯一承载写作流程的教学件。 -> 模板与例子文件保持纯净：不含任何步骤、检验提示与标记。 - -## 一、这一层的判断立场 -你是架构师，切系统的刀在你手里。在这个层里你相信： -- 切分是为了**职责清晰、可独立讨论**，不是为了凑数量——每个系统必须能 - 一句话答出"删了它，什么塌"（P0 原因）。 -- **数据所有权唯一**：同一事实只由一个系统维护，其他系统只引用稳定 ID， - 不复制主数据。两个系统管同一件事 = 架构事故。 -- **依赖无环**是硬要求；信息呈现层只读状态、只经行动入口写入。 -- 架构是全项目返工最多的一份（实测 11 版 vs 概念层 2 版）——所以每次改刀 - 都要写变更记录，让"为什么这么切"可追溯。 -- 你不越层：上不重定义玩法循环（那是顶层的），下不写单系统内部规则 - （那是系统文档的），字段定义与数值配置归技术文档层（数值策划）。 - -## 二、动笔前 -1. 顶层设计已定稿可用——把它的**系统范围表**（粗清单）和**顶层定稿约束** - 摊开当输入；切分是对粗清单的正式化（拆、并、裁都在这层做）。 -2. 读取对应示例了解内容组织方式，然后按对应模板填写。 -3. 记住顶层的核心循环图——切完必须跑覆盖检查。 - -## 三、架构设计的组织维度：写什么、为什么、怎么咬合 - -架构文档回答四个问题： -**这个架构为什么这样切（1~3）→ 系统是什么、怎么连接（4~6）→ -怎么落地、怎么验证（7~11）→ 还有什么没想清（12）。** - -第 1 节承顶层的定稿约束开篇，MVP 闭环在中间当守门员，开放问题收尾。 - -| # | 节 | 是什么 | 为什么写 | 和谁咬合 | -|---|---|---|---|---| -| 1 | 架构定位与目标 | 阶段边界（定哪些系统、不展开内部）+ 划分原则 + 一句话架构 + **变更记录** | 防止架构漂离顶层；改刀可追溯 | 承顶层定稿；变更记录引登记编号 | -| 2 | 系统地图 | Sxx 编号清单（=系统文档范围真源）+ 支撑层 + P0 段五列表（目的/输入/输出/P0原因） | 编号让系统可引用；P0 原因逼答"删了塌什么" | **对下真源**：Sxx ↔ 04 系统文档一一对应 | -| 3 | 系统职责 | 职责表（负责/不负责→移交谁）+ 逐系统说明段 | 边界写死，防两个系统管同一件事 | 系统文档的"边界与非目标"必须与此对齐 | -| 4 | 依赖与数据流 | 依赖图（无环）+ 数据流图 + 主要状态 + 主数据归属规则 | 谁读谁、数据从哪到哪——接口的真源 | 顶层的资源流图在此展开成系统级 | -| 5 | 核心循环覆盖检查 | 顶层每个循环环节 → 认领系统 | 顶层→架构的验收线，防切系统切碎循环 | 对上接口：逐环节对照顶层循环图 | -| 6 | 目录映射 | 职责 → 物理文档目录的归并表 | 职责数≠文档数；归并规则显式化 | **对下接口**：系统文档照此开工 | -| 7 | MVP 最小闭环 | 编号验证链 + 守门句（"闭环不成立不许加东西"） | 立项后第一条要跑通的链 | 对应顶层验证标准；失败回顶层而非加系统 | -| 8 | 统一数值基准 | 单位清单 + 四类定性基准（时间/货币/成长/体力风险的风格约束） | 各系统单独配数值会互相失衡；先定全局尺度 | **数值换算与验算归技术文档层**，此处只到定性 | -| 9 | 系统边界 | 哪些功能明确不属于任何系统/归引擎层/归呈现层 | 显式排除，防范围蔓延 | 承概念层"不是什么" | -| 10 | 优先级与范围 | P0/P1/P2 三档（P1/P2 可用能力表） | 拆分≠全做；裁剪顺序显式化 | P0 = MVP 闭环的系统集 | -| 11 | 风险与校验 | 风险/校验方式表 | 架构级风险提前挂出，每条带检验法 | 对应顶层验证标准与概念层跑偏风险 | -| 12 | 开放的结构问题 | 结构级未定案 | 显式债务 | 进分析文档或系统文档开题 | - -咬合一图： - -``` -顶层定稿 + 系统范围表（粗清单） - ↓ 正式切分（拆/并/裁） -1 定位与目标 ──► 2 系统地图（Sxx 真源）──► 3 职责表 - ↓ ↓ ↓ -5 循环覆盖检查 ◄── 4 依赖与数据流（接口真源） - ↓ -6 目录映射 ──► 7 MVP 最小闭环（守门员） - ↓ -8 数值基准（定性）· 9 边界 · 10 优先级 · 11 风险校验 - ↓ -12 开放问题 →（进分析文档 / 系统文档开题） -``` - -三个接口：**对上**承顶层系统范围表并跑循环覆盖检查；**对内**地图↔职责↔依赖 -三方一致、主数据归属唯一；**对下**目录映射 + MVP 闭环喂系统文档。 - -## 四、怎么写（模板即流程，十二节按序） -（本节是带写法要领的教学版；实际填写使用对应纯净模板。） - -### 1. 架构定位与目标 -本阶段确定"哪些系统支撑一轮玩法"，不展开单系统内部规则。 -划分原则：__。一句话架构： -> （玩家通过哪些系统、以什么因果，把一轮玩法的输入变成下一轮的选择） -变更记录：日期 + 改了什么 + 为什么（引登记编号）。 -→ 没有变更记录的架构文档，第二轮迭代就会变成黑箱。 - -### 2. 系统地图 -Sxx 编号清单（核心系统通常 1-5 个，有明确要求可超出 5 个）+ 支撑层（存档/UI，不拥有核心规则）。 -P0 段五列表： -| 系统 | 目的 | 输入 | 输出 | P0 原因 | -→ 对实际拆出的系统说明删除后的影响；无法形成独立职责的部分合并。 - -### 3. 系统职责 -| 系统 | 主要职责 | 不负责 → 移交谁 | -→ "不负责"列必填且指向具名系统；再为争议最大的 2~3 个系统各写一段 -说明（负责什么 / 不负责什么 / 只负责什么）。 - -### 4. 依赖与数据流 -依赖图（mermaid，呈现层用虚线"读取状态"）+ 数据流图（资源从产到耗）。 -主要状态：全局/玩家/场景/社会 四类。 -主数据归属规则：规则与数据表分工 / 稳定 ID 关联 / 任何系统不复制他系统主数据。 -→ 依赖图出现环 = 回去重切。 - -### 5. 核心循环覆盖检查 -| 顶层循环环节 | 认领系统 | -→ 逐环节对照顶层循环图；有环节无人认领或多人认领都是切分错误。 - -### 6. 目录映射 -| 目录 | 本阶段定位 | -→ 职责可以归并进同一文档目录（官方版 8 职责→3 文档）；归并规则写明。 -系统文档以此开工：地图上没有的系统不许有文档。 - -### 7. MVP 最小闭环 -1. __ 2. __ …（编号验证链，一条玩家可走的完整因果） -守门句：如果这条闭环不成立，不应继续增加 __。 -→ 闭环失败回顶层改设计，不是加系统打补丁。 - -### 8. 统一数值基准（定性） -全局单位清单（如时间片/游戏日/货币/体力/经验）+ 四类风格约束 -（时间节奏/货币量级感/成长回报取向/体力风险档位）。 -→ 只写到定性；具体换算、验算数值由技术文档层（数值策划）承接。 - -### 9. 系统边界 -明确排除项（不拆出独立 __ 系统 / __ 归引擎层 / __ 归呈现层）。 - -### 10. 优先级与范围 -P0（最小闭环必需）：__；P1（完整体验）：__；P2（扩展内容）：__。 -P1/P2 可用能力表（能力/说明）控制颗粒度。 - -### 11. 风险与校验 -| 风险 | 校验方式 | -→ 从概念层跑偏风险和顶层失败档位反推；校验方式要可观察。 - -### 12. 开放的结构问题 -→ 结构级（接口归属/统一格式/合并拆分）才留这里；数值细节不留。 - -## 五、分析文档（全局一份，按层分节） - -**全局唯一一份分析文档**：论证按发生层归节，决定登记表全项目共用，跨层引用只查这里。状态池（灵感池/代决/待原型等活队列）在决策台账， -不放分析文档——本文件只放已决论证与登记。 - -- 条目格式：`## 问题：<一句话>` ＋ 状态（agent_proposal / user_confirmed / - superseded，登记 D-__）＋ 广度分析（牵动面＋候选 ≥2）＋ 深度分析 - （逐候选利弊依据，必须引 T 原则/锚点/张力编号，写不出依据的偏好不进分析） - ＋ 综合判断（建议取 __ 因为 __；推翻条件：__）。 -- 分诊三条件全满足才进：① 影响项目方向或边界；② ≥2 合理候选；③ 一时定不了。 - 不满足的：就地小权衡直接进登记表一行，不写条目。 -- 本层标准问题：结构级争议——接口统一、系统归并、主数据归属划分。 -- 数量纪律：按需；架构期问题多为接口与归属二义。 -- user_confirmed 后三件事：结论一句话迁入 design.md 对应节（留修订痕迹）； - 登记表加行（编号全项目连续，跨层引用写 D-__）；本条目改状态记 D 号保留不删。 - 推翻时新增行挂旧行编号，旧行不删。 - - -## 六、写完自查（参考，不是闸门） -- 每个 Sxx 都能一句话答"删了它什么塌"吗？ -- 顶层的循环环节全覆盖、无重复认领吗？ -- 依赖图无环？主数据无一物两管？ -- 系统文档拿到目录映射能直接开工吗？ -- 有没有字段定义或数值配置偷偷写进来？（该在技术文档层） -- 变更记录补了吗——这次切分和上次的差异说得清吗？ - -## 七、红线（只有三条） -1. 不冒充用户决定：用户没说的方向标"待确认"，正文不写死。 -2. 不越层：向上不翻顶层的案，向下不写系统内部规则，数值字段归技术文档层。 -3. 不凑数：系统数量不是成绩，写不出 P0 原因的系统就是该删的系统。 - - - - -## A4 系统文档分册（game-gdd-system-doc） - ---- -name: game-gdd-system-doc -description: 写单个系统的设计文档（Sxx）时的总纲——通用纪律、十二类常见内容、 - 红线与分析文档格式。 ---- - -# 系统文档写法（策划 · 系统文档分册 · 总纲） - -> 本文件是系统文档层的总纲；通用纪律不在各系统写法里重复。 - -## 一、这一层的判断立场 -你是写单个系统的策划。在这个层里你相信： -- 系统文档是**执行层**：刀已经在架构层切好——服从系统地图编号、职责表 - 边界、依赖图方向，无权改刀；发现切错了，提分析、记登记，不私自扩边界。 -- 一个系统文档的成败在**边界节**："不负责什么、移交给谁"那几行是 - 防返工价值最高的几行。 -- 接口纪律：引用具名系统与具名数据，禁泛称；别家主数据只引 ID 不复制。 -- 字段定义、数值配置、表结构不归你——写交接声明，交技术文档层（数值策划）。 -- 系统文档保持基本可读的一致性，但不要求所有系统使用相同章节；结构应服从系统类型和实际行为。 - -## 二、动笔前 -1. 架构已定稿：找到本系统的 Sxx 编号、职责表行、依赖方向——这是合同。 -2. 选择最接近的系统类型（可组合，如"钓鱼"=采集+战斗的判定部分），使用对应的系统写法与模板。 -3. 该文件夹标注"必读例子"的，先读例子全文了解对应系统的内容组织方式。 - -## 三、系统文档的组织维度：写什么、为什么、怎么咬合 - -系统文档回答四个问题： -**这个系统为什么存在（1~2）→ 玩家怎么用它（3~5）→ 它怎么运转（6~8）→ -它怎么和别人连接、不碰什么（9~12）。** - -| # | 节 | 是什么 | 为什么写 | 和谁咬合 | -|---|---|---|---|---| -| 1 | 系统目的 | 一句话：删了它什么塌 | 存在性检验 | 架构 P0 原因的展开 | -| 2 | 支撑的玩家体验 | 对应顶层目标第几条 | 防系统自嗨 | 顶层设计目标 ↔ 本系统 | -| 3 | 进入与退出 | 何时进入、何时/如何退出 | 循环的接口时刻 | 顶层的循环环节 | -| 4 | 玩家行动 | 具名动词组 | 玩家用手玩 | 系统类型卡给动词组 | -| 5 | 取舍表 | 玩家在本系统内的决策 | 张力在系统内的落地 | 概念张力→顶层取舍表→本表 | -| 6 | 状态与规则 | 对象/状态/转换/异常，枚举表达 | 定性规则真源 | 架构职责表对齐 | -| 7 | 数值与数据交接 | 本系统交 TDD 的数据类别+定性约束 | 分层边界 | 技术文档层承接 | -| 8 | 反馈 | 关键结果何时、以何种方式反馈 | 让实际结果可理解 | 与本系统实际结果对应 | -| 9 | 内部循环 | 本系统内的小循环 | 系统自己的心跳 | 顶层小循环的组成 | -| 10 | 输入、输出与依赖 | 消费/交付/依赖谁 | 接口真源 | 架构依赖图逐边对齐 | -| 11 | 边界与非目标 | 不负责什么→移交谁 | **防返工价值最高** | 架构职责表"不负责"列 | -| 12 | 开放问题 | 本系统未定案 | 显式债务 | 进分析文档 | - -咬合：**对上**服从架构三条合同（编号/职责/依赖）；**对内**状态与接口不越 -职责边界；**对下**第 7 节交接喂 TDD。 - -## 四、常见内容的参考写法 -（各系统类型的特殊写法与纯净模板按对应类型取用。） - -1 系统目的：若删除它，__ 会塌——一句话说不出 = 该系统不该存在。 -2 支撑体验：对应顶层目标第__条、调性原则第__条。 -3 进入与退出：按本系统实际存在的入口、退出和恢复路径记录。 -4 玩家行动：记录本系统实际存在的具名动词组；编排类写"安排"动词，活动类写"操作"动词。 -5 取舍表：决策/立即收益/延迟收益/主要代价；挂顶层张力编号。 -6 状态与规则：对象-状态-转换-异常，全部枚举表达，不许整段散文。 -7 数值与数据交接：列数据类别名 + 设计侧定性约束；字段定义归 TDD。 -8 反馈：记录本系统关键结果的可理解反馈；存在失败时说明原因和恢复路径。 -9 内部循环：动词链；可拆单次/区域/长期三层。 -10 输入输出与依赖：引用具名系统与具名数据，禁泛称"资源"。 -11 边界与非目标：参考该类型系统写法的“三不”说明边界；建议说明字段与数值的交接边界。 -12 开放问题：结构级才留；手感数值类标"待原型验证"。 - -## 五、分析文档（全局一份，按层分节） - -**全局唯一一份分析文档**：论证按发生层归节，决定登记表全项目共用，跨层引用只查这里。状态池（灵感池/代决/待原型等活队列）在决策台账， -不放分析文档——本文件只放已决论证与登记。 - -- 条目格式：`## 问题：<一句话>` ＋ 状态（agent_proposal / user_confirmed / - superseded，登记 D-__）＋ 广度分析（牵动面＋候选 ≥2）＋ 深度分析 - （逐候选利弊依据，必须引 T 原则/锚点/张力编号，写不出依据的偏好不进分析） - ＋ 综合判断（建议取 __ 因为 __；推翻条件：__）。 -- 分诊三条件全满足才进：① 影响项目方向或边界；② ≥2 合理候选；③ 一时定不了。 - 不满足的：就地小权衡直接进登记表一行，不写条目。 -- 本层标准问题：① 本系统与相邻系统的边界在哪；② 本系统内部哪个规则影响顶层取舍。条目标系统号（如 S06）。 -- 数量纪律：按需；每系统通常 0~1 条，超了先回读架构职责表。 -- user_confirmed 后三件事：结论一句话迁入 design.md 对应节（留修订痕迹）； - 登记表加行（编号全项目连续，跨层引用写 D-__）；本条目改状态记 D 号保留不删。 - 推翻时新增行挂旧行编号，旧行不删。 - - -## 六、写完自查（参考，不是闸门） -- 目的一句话成立吗？边界节和架构职责表逐行对齐吗？ -- 输入输出和依赖图逐边对上吗？有没有泛称漏网？ -- 状态是枚举还是散文？失败路径给了原因和恢复吗？ -- 有没有字段或数值偷偷写进来？（该在 TDD） -- 同构检查：另一份系统文档的读者能按同样方式读这份吗？ - -## 七、红线（只有三条） -1. 不冒充用户决定：用户没说的方向标"待确认"，正文不写死。 -2. 不越层：不翻架构的案（要改走分析文档+登记表），不写字段数值（归 TDD）， - 不替别的系统定规则。 -3. 不凑数：写不出"删了塌什么"的系统直接删除；章节对项目有意义但信息不足时，记录已确定内容与待补问题。 - - - - -## A5 技术文档分册（game-tdd） - ---- -name: game-tdd -description: 写游戏技术文档（TDD）时使用的总纲。GDD 四层定稿后的第五步：把 - "怎么做"写实——程序怎么写、美术怎么做、字段怎么定义、怎么配表。 - 三大件各有专属分册：技术实现（程序侧）/ 美术圣经（美术侧）/ 数据与配表（数据侧）。 ---- - -# 技术文档写法（策划 · TDD 分册 · 总纲） - -> 本文件是 TDD 层唯一承载写作流程的教学件；各分册写法与模板配套使用。 -> 模板与例子文件保持纯净：不含任何步骤、检验提示与标记。 - -## 〇、TDD 的完成判据（总纲） - -**TDD 是当前版本的施工合同：施工方只看 TDD，应能完成本项目实际范围内的实现。** -GDD 是设计真源（给人看、给迭代看）；TDD 是构建真源（给施工看）。 -检验方式＝自足性检查（见总册）：不看 GDD 能否回答——每个系统怎么行为、 -每张表多少行内容、每个界面怎么走、每份素材什么规格。答不出的项就是缺口， -缺口回 GDD 同步后**收编**进 TDD（带版本锁）。收编是构建期快照：GDD 定稿 -变更 → 触发对应收编节重同步。 - -## 一、这一层的判断立场 - -你是工程师思维的策划。GDD 是"用户视角的功能描述"，TDD 是"实现者视角的 -架构性描述"——你不重复设计的论证（为什么这样设计，去 GDD 和分析文档查）， -只写怎么落地。你相信： - -- **交接契约是 TDD 最大的价值**：美术交给程序的素材、程序读的表、加载的 - 顺序——每一条缝都写死。缝上不写死，返工就在缝里发生。 -- **平台事实优先**：目标运行时由 GDD 平台事实锁定——**HTML / Unity / Godot / - Cocos 四选一**。HTML 项纯 HTML/CSS/JS 交付；引擎项支持打开引擎工程、自然 - 语言协作改素材与代码；预览与导出按所选引擎的平台流程执行。 - 一切技术选择先过所选运行时这道闸，不推荐该运行时做不出来的东西； - TDD 不擅自换运行时。 -- **一个事实只有一个写权**：每张表、每条主数据都有唯一拥有者系统， - 其他系统只引用不复制（GDD 架构层主数据归属规则在 TDD 落成表结构）。 -- **验收是硬闸不是仪式**：有 blocker 禁止扩充内容。 -- **先少量验证再量产**（美术）/ **先建索引再转表**（数据）——任何方向都 - 不做"做完一大批才发现不对"的事。 - -## 二、TDD 与 GDD 的接口（输入从哪来） - -| 输入 | 来自 | 喂给哪件 | -|---|---|---| -| 系统范围表 + P0 清单 + 主数据归属规则 | 架构层 | 三件共用（拆表与拆模块依据） | -| 各系统「数值与数据交接」节 + 定性约束 | 系统文档 | 数据侧（直接订单） | -| 定调记录（参照/滑杆/T 原则）+ 身份基调 | 概念层 | 美术圣经（视觉翻译源头） | -| 可复用能力 | 能力库 | 程序侧+美术圣经（带版本与实例化参数） | - -TDD 不回头改 GDD：发现 GDD 没写清楚的点，走「开放问题回执」——该问用户 -的升级决策卡，该代决的记台账（带理由和推翻条件），结论回写对应层，TDD 只 -登记去向。顾问期（开发阶段）同一出口：程序美术卡点、成品与文档偏差，都从 -回执进、修订出（v{N+1}）。 - -## 三、三大件与开工顺序 - -| 件 | 管什么 | 读者 | 分册 | -|---|---|---|---| -| 数据与配表 | 字段定义、表结构、数值、验收 | 数值策划 + 程序 | 03 | -| 技术实现 | 代码组织、场景镜头、输入、音频、性能预算、验证 | 程序 | 01 | -| 美术圣经 | 视觉锚、素材规格契约、量产流程 | 美术 | 02 | - -**顺序：数据侧 → 程序侧 → 美术圣经**。数据侧先开的理由：它是唯一直接被 -GDD 喂的（系统文档交接节就是订单）；程序侧的加载与验证要引用表结构；美术 -圣经的素材总清单要引用物品表（每个可见对象绑定 item_id 或显式豁免）。小型 -项目三件可交叉，但**表结构永远先于数值填充**。 - -## 四、怎么写（总纲级；细节在各分册） - -1. 数据侧：总清单拆表 → ID 与字段字典 → 公共条件表 → 建表顺序（物品表 - 起步）→ 表结构契约（程序签名）→ 数值填充（代决+台账）→ 验收七查。 -2. 程序侧：系统实现总览（每系统一段话写死怎么做）→ 技术选型与可复用能力引用 - → 场景与镜头 → 输入与操作 → 音频 → 验证方式与性能预算。 -3. 美术圣经：视觉锚（从概念层定调翻译）→ 素材规格契约逐素材一行 → - 量产流程（概念候选→锚点确认→小批→验收→扩产）→ 资产总清单。 - -## 五、写完自查（参考，不是闸门） - -- 任意一条缝（美术→程序、表→代码、表→表引用）是否都写死了规格？ -- 每张表是否答得出"谁是拥有者系统"？每个 ID 是否全局唯一？ -- 程序侧验证方式是否可执行（跑什么命令、看什么输出）？ -- 素材契约是否覆盖了 GDD 里全部可见对象（或显式豁免）？ -- 验收是否跑过且无 blocker？ - -## 六、红线（只有四条） - -1. **收编必带版本锁**：从 GDD 收编的任何内容标注"基于系统文档@v{N}"； - 无锁收编=违规（双源漂移之源）。TDD 不产生设计观点，只汇集与落实施工。 -2. 引用必带版本：可复用能力引用必须记录版本与实例化参数，选型时与执行时用的一致性靠此保证。 -3. 不越权拍板：产品级取舍回 GDD 层走决策流程；TDD 只做技术代决且记台账。 -4. 表里不写散文：单元格只有数据和枚举；规则写在契约文档，不写在表里。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/decision-log.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/decision-log.md index b4ad33295..b3dfaf82d 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/decision-log.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/decision-log.md @@ -1,66 +1,8 @@ -# 决策台账：《星露谷物语》金样项目 +# 决策台账：《星露谷物语》示例项目 -版本：v3　|　规则：台账放活队列——design 只放结论、分析只放论证、决定与开放问题住这里。编号连续不复用；被推翻的行标 overturned 挂新行，不删行。 -状态六态：`confirmed`（用户亲口/亲选）/ `auto_decided`（技术类代决，必带理由＋推翻条件，用户一键可翻）/ `default_pending`（默认建议兜底，用户未点头）/ `prototype_pending`（待原型验证）/ `pending_user`（等用户拍板）/ `overturned`（被推翻，挂旧行编号）。 +仅列仍需跟进的事项和下一步。详细依据与采用的规则见相关分析和设计文档；事项完成后移出待办。 -> 编号口径：D-01~D-13 与 templates/stardew-analysis.md 台账节选一致（D-04~D-06、D-08~D-10、D-12 原为"就地小权衡，直接登记未开条目"，此处按登记口径展开）；D-14 起为技术文档期新增，与 stardew-tdd-tech.md 开放问题回执互引。 - -## 当前待办（活队列） - -### 等用户拍板（pending_user） - -| 编号 | 决定 | 层 | 谁 | 依据 | 推翻条件 | 状态 | -|---|---|---|---|---|---|---| -| D-14 | 体力与战斗共享单池 | TDD | user | 风险资源统一制造取舍（概念张力一）；**暂按共享实现，改单拆只需改 S02 成本入口** | 战斗参与率实测过低（玩家回避矿井） | pending_user（暂按共享实现） | -| D-15 | 背包格子制 vs 重量制 | TDD | user | 格子制直觉、重量制焦虑感与 T5"休闲不打卡"冲突；暂按格子制实现、存档预留 capacity_type 字段 | 格子管理成为主要负面反馈 | pending_user（B 级阻断存档结构，暂按格子制） | - -### 待原型验证（prototype_pending） - -| 编号 | 决定 | 层 | 谁 | 依据 | 推翻条件 | 状态 | -|---|---|---|---|---|---|---| -| D-13b | 战斗判定窗口手感（前摇帧数/无敌帧 450ms 基准） | 系统 | user | 数值可定、手感不可纸面验证 | 原型显示节奏拖慢/玩家困惑 | prototype_pending（规则本体见 D-13 confirmed） | - -### 默认建议兜底（default_pending） - -| 编号 | 决定 | 层 | 谁 | 依据 | 推翻条件 | 状态 | -|---|---|---|---|---|---|---| -| D-19 | 天气权重表具体数值（晴/雨/风暴按季节） | TDD | agent | 概念层只定"雨免浇水"定性；数值推内容期填 | 前 5 日出现连续 3 日雨/全无雨 | default_pending（默认值已进数据表，带 designer_note） | - -## 已采用决定 - -### 用户确认（confirmed） - -| 编号 | 决定 | 层 | 谁 | 依据 | 推翻条件 | 状态 | -|---|---|---|---|---|---|---| -| D-01 | 定调：牧场物语系参照、治愈慢节奏 | 概念 | user | 用户原始需求 | — | confirmed | -| D-02 | 单人体验，无多人 | 概念 | user | 概念层非目标 | — | confirmed | -| D-03 | 战斗保持伴生风险，不做装备驱动主轴 | 概念 | user | 概念期问题一 | 矿井流失率过半且归因战斗 | confirmed | -| D-07 | 日目标自设，季节与社区提供低频牵引 | 顶层 | user | 顶层期问题一 | 新手周流失归因无方向 | confirmed | -| D-11 | 采集/钓鱼/战斗统一"活动结果"接口 | 架构 | user | 架构期问题一 | 第三活动类型出现结构性差异 | confirmed | -| D-13 | 战斗采用节奏/指令判定 | 系统 | user | S06 问题一 | 原型显示节奏拖慢/玩家困惑 | confirmed（手感部分拆 D-13b prototype_pending） | - -### 技术代决（auto_decided——带理由与推翻条件，用户一键可翻） - -| 编号 | 决定 | 层 | 谁 | 依据（理由） | 推翻条件 | 状态 | -|---|---|---|---|---|---|---| -| D-04 | 时间片制：700ms=10 游戏分钟 | 概念 | agent | 原作实证节拍；一天≈14 分钟真实时间贴合 T5"休闲" | 内测一天体感过短/过长 | auto_decided | -| D-05 | 分区域切换（区域独立场景，非连续地图） | 概念 | agent | 概念层"不是什么：无边界开放世界"；区域小网络全部步行可达 | 场景切换成为移动负担反馈 | auto_decided | -| D-06 | 28 日/季、四季/年 | 顶层 | agent | 季节窗口制造"本季计划"节奏（支柱二） | 换季频率在测试中被无视 | auto_decided | -| D-09 | 商店营业时段走条件表 | 架构 | agent | 与配方/区域解锁共用 check(condition_id) 单一入口 | 条件表规模膨胀难维护 | auto_decided | -| D-10 | 出货箱日终统一结算 | 架构 | agent | 收入集中进日终面板，强化"一天一结算"叙事；商店现卖保留即时通道 | 玩家普遍绕开出货箱 | auto_decided | -| D-12 | 工具升级期间该工具不可用 | 系统 | agent | 升级=时间成本换效率（顶层张力二）；备用旧工具暂不做（开放问题） | 升级期挫败感集中爆发 | auto_decided | -| D-16 | 矿井逐层生成本期不做（P2） | TDD | agent | GDD 已标"不做无限地牢"；首期按布局池 8~12 模板拼装 | 内测要求深度爬塔玩法 | auto_decided | -| D-17 | 换装首期 5 层（基础体/裤/衣/发型/饰件），非 19 层 | TDD | agent | 外观自定义非首期卖点；层结构预留到 19 层 | 外观系统成核心诉求 | auto_decided | -| D-18 | 作物品质三档：普通/银/金 | TDD | agent | 经济分层需要（即时变现 vs 等待升值的取舍） | 银金档无人区分、一律普通出售 | auto_decided | - -### 已推翻（overturned——旧行保留，挂新行） - -| 编号 | 决定 | 层 | 谁 | 依据 | 推翻条件 | 状态 | -|---|---|---|---|---|---|---| -| D-08 | 作物品质两档：普通/银 | TDD | agent | 早期小权衡：两档最简 | — | **overturned → D-18**（经济分层不足，改三档；铱档留 P1） | - -## 队列纪律（使用说明） - -- 新决定入队：拿下一号（当前最大 D-19，下一号 D-20）；就现代决可登记不开条目，但状态必须写 auto_decided 并带理由＋推翻条件。 -- 用户翻案：旧行标 overturned 挂新行，受影响文档节重写（本台账只记录，不代改）。 -- 概念层变更定稿后：速览卡"决定状态与原型验证项"字段随本文件最新版同步。 +- 体力与战斗是否共享资源：涉及探索压力和恢复规则，结合用户对战斗体验的要求确认，再更新相关系统设计。 +- 背包使用格子还是重量限制：在确定存档和界面结构前确认，选择依据记录在分析文档。 +- 战斗判定窗口的手感：通过矿井原型试玩观察是否易懂、是否拖慢探索，依据见分析文档“战斗判定窗口是否需要调整”。 +- 天气权重是否合适：用前几天的游玩样本检查连续雨天或长期无雨的影响，再调整配置。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/overview-card.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/overview-card.md index 68a55e87f..4a385f7bd 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/overview-card.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/overview-card.md @@ -1,59 +1,16 @@ -# 速览卡：《星露谷物语》金样项目 +# 速览卡：《星露谷物语》日常原型示例 -> 字段来源见每节尾注（概念层/定调记录/决策台账）。概念层变更定稿后本卡必须同步更新。 +继承一座荒废农场，安排每天的时间与体力，通过种田、探索和乡村交往逐步改善生活。面向喜欢自主安排与慢节奏成长的玩家，采用温暖、朴素的俯视像素风；本例运行于 Web，支持桌面键鼠与移动触控。 -## 1. 游戏名称 -《星露谷物语》（金样项目沿用案例名；新项目由概念层第 1 节定名）←概念层§1 +## 当前范围 -## 2. 一句话描述 -继承一座荒废农场的乡村生活 RPG：安排每天的时间与体力，种田、探索、交朋友，把日子过成自己想要的样子。（←概念层§1 一句话概念，45~90 字） +本次只做农场、小镇与基础采集区域的日常原型：农务与采集获得成果，经买卖、成长和跨日推进形成下一轮计划，包含必要的界面与存读档。居民关系、矿井战斗等完整游戏内容不在本次施工范围。 -## 3. 游戏分类 -乡村生活模拟 RPG（经营+探索+社交；参照系牧场物语）←概念层§1 +当前样例的基础采集、跨日结算、数值及表现规格仍有缺口，尚不能据此完成整个原型；详情见 TDD 总册。 -## 4. 美术风格（四件）←定调记录＋概念层§4 -- 视觉类型：手绘感像素风、俯视 45° 视角。 -- 风格关键词：温暖、田园、四季分明、生活感。 -- 色彩与氛围：暖土绿基底+季节信号色整体切换；治愈不压抑；无锐利科技感、无阴暗元素。 -- MVP 美术边界：首期 3 区域 tileset、8 位 NPC（行走+立绘）、约 120 物品图标、玩家换装 5 层；不做 19 层全量换装与全区域。 +## 设计入口 -## 5. 游戏支柱（3 条）←设计锚点提炼 -| 支柱 | 玩家感受 | 实现机制 | -|---|---|---| -| 自己的节奏 | "今天想干嘛就干嘛，明天一切更顺手。" | 自由日程+时间体力预算；无失败结局 | -| 今天的选择让明天更从容 | "升级工具、攒钱扩建是有意义的。" | 长期投资线：工具升级/技能/设施 | -| 社区让独居变成归属 | "镇上的人在等我。" | NPC 关系/任务/社区修复目标 | - -## 6. 核心循环（5 步）←锚点循环位展开 -安排一天的时间与体力 → 农/采/钓/矿/战/社交任选组合 → 获得资源·金钱·经验·关系 → 投资工具·设施·种子·物品 → 解锁更高效或更丰富的活动。 - -## 7. 目标用户 ←概念层§5 -牧场物语系慢节奏成长玩家+动森式"无压力日常"需求；单人、可反复、每次一至数个游戏日；不要求预先掌握复杂数值。 - -## 8. 平台事实（禁改） -Web 浏览器运行 · 双视口（桌面/移动）· 键鼠/触屏双输入 · 本地启动后可在浏览器中试玩。 - -## 9. MVP 系统（5 个）←概念层"最小闭环粗清单" -| 系统 | 最小功能 | 为什么必须有 | 验证方法 | -|---|---|---|---| -| 时间与日程 | 时钟/日终结算/季节天气 | 全局节拍器 | 一个游戏日全流程可完成并结算 | -| 体力与状态 | 单池体力/昏倒惩罚 | 一切取舍的成本源 | 玩家主动在体力耗尽前收手 | -| 农场经营 | 锄种浇收+加工队列 | 核心产出与规划场 | "买种→收获→出售"闭环成立 | -| 物品与制作 | item_id/背包/配方解锁 | 资源身份与转化 | 拾取/堆叠/制作全链无回翻 GDD | -| 经济与商店 | 基准价+价差+出货箱 | 投资回报换算 | 第 4 日现金流回正（前五日验算） | - -## 10. 制作边界 ←概念层"不是什么"表 -不做：硬核生存（无饥饿/债务/死亡惩罚）；效率至上的工厂经营；以战斗为核心的动作游戏；剧情驱动的任务链主线；多人竞争；无边界开放世界（区域小网络全步行可达）。 - -## 11. 创作者提示（先做与验证）←概念层"先做与验证"节 -- 先做：第 1 日循环（买种→播种→浇灌→收获→出售→日终结算）＋一个可进入的矿井遭遇。 -- 暂不做：装备刷取、随机构筑、复杂剧情、节日全量、联机。 -- 这样验证：测试者玩完第 1 日后是否主动说"再玩一天"；能否说出"明天要先做什么"。 -- 达标再扩展：玩家能自述明日计划后，才加社交深度与矿井分层。 - -## 12. 决定状态与原型验证项（依据决策台账） -- 已确认（confirmed）：定调 D-01 / 单人 D-02 / 战斗伴生 D-03 / 日目标自设 D-07 / 活动统一接口 D-11 / 战斗节奏判定 D-13。 -- 技术代决（auto_decided，可一键翻案）：D-04 时间片 / D-05 分区域切换 / D-06 28 日季 / D-09 营业条件 / D-10 出货箱日终 / D-12 工具占用 / D-16 矿井生成 P2 / D-17 换装 5 层 / D-18 品质三档（推翻 D-08 两档）。 -- 等拍板（pending_user）：D-14 体力战斗是否共享单池（暂按共享实现）；D-15 背包格子/重量（暂按格子制，B 级阻断存档结构）。 -- 待原型（prototype_pending）：D-13b 战斗判定窗口手感（前摇帧数/450ms 无敌帧基准）。 -- 默认兜底（default_pending）：D-19 天气权重数值（默认已入表，带 designer_note）。 +- [概念设计](stardew-concept.md)：游戏方向与核心体验。 +- [顶层设计](stardew-top-design.md)：游玩过程与版本范围。 +- [系统架构](stardew-architecture.md)：系统职责与协作。 +- [TDD 总册](stardew-tdd-master.md)：施工分册入口与重要缺口。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/stardew-architecture.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/stardew-architecture.md index b81f74342..01fdbc04b 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/stardew-architecture.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/stardew-architecture.md @@ -1,200 +1,69 @@ # 系统架构：《星露谷物语》 -## 架构定位与目标 -本阶段确定"哪些系统支撑一轮玩法"，不展开单系统内部规则。 -划分原则：将生活模拟 RPG 拆成职责清晰、可独立讨论的规则系统，同时保留少量跨系统入口，避免"每个功能都能互相调用"造成架构失控。系统划分服务于顶层循环：安排一天、执行活动、获得进展、投入成长、解锁新选择。 +## 系统与职责 -一句话架构： -> 玩家在有限的时间与体力下，通过农场、探索与社交三组活动系统产出资源与关系，经物品与经济系统转化为投资，由时间系统推进日终，把一天的成果变成下一天的选择。 +架构承接顶层的农场生活体验：安排一天、执行活动、获得进展、投入成长，再形成后续计划。战斗服务于探索中的风险与节奏变化，不作为装备成长主轴。以下系统覆盖完整版本，首个原型只实现其中必要的能力。 -变更记录： -- 2026-09-05：战斗与敌人系统定为伴生风险定位，深度刻意受限，不进入最小闭环核心链（依据：概念分析 D-03）。 - -## 系统地图 - -| 编号 | 系统 | 一句话职责 | 优先级 | -|---|---|---|---| -| S01 | 时间与日程 | 推进游戏时间、日期、季节、天气、营业时间、NPC 日程和日终结算 | P0 | -| S02 | 体力与状态 | 管理体力、负面状态、恢复、昏倒和行动成本 | P0 | -| S03 | 农场经营 | 管理土地、作物、畜牧、农场设施和生产状态 | P0 | -| S04 | 探索与地图 | 管理区域、出入口、可交互资源点、地图解锁和移动 | P0（基础） | -| S05 | 采集与钓鱼 | 管理野外采集、钓鱼活动、资源品质和获得物 | P1 | -| S06 | 战斗与敌人 | 管理矿区或危险区域中的战斗、伤害、敌人行为和战利品 | P1 | -| S07 | 物品、背包与制作 | 管理物品实例、堆叠、工具、装备、配方和制作队列 | P0 | -| S08 | 成长与技能 | 管理技能经验、等级、工具升级、职业选择和能力解锁 | P0（基础） | -| S09 | 经济与商店 | 管理货币、买卖、价格、商店库存、订单和资金流 | P0 | -| S10 | NPC 与关系 | 管理 NPC 日程、对话、好感度、礼物偏好和关系事件 | P1 | -| S11 | 任务与社区目标 | 管理任务状态、阶段目标、奖励、社区修复和区域解锁条件 | P1 | -| S12 | 事件与节日 | 管理季节事件、节日活动、条件触发和特殊奖励 | P1 | - -支撑层（不拥有核心规则）： -- 存档与进度系统：保存跨日、跨季节和跨阶段的持久状态。 -- UI 与文本呈现层：展示状态、提供操作入口、呈现反馈与文本。 - -P0 段： - -| 系统 | 目的 | 输入 | 输出 | P0 原因 | +| 编号 | 系统 | 职责与权威维护的状态 | 首个原型范围 | 文档目录 | |---|---|---|---|---| -| S01 时间与日程 | 全局时钟与日终 | 各系统行动完成信号、日终触发 | 日期/季节/天气变化、日终结算、跨天 tick | 没有"一天"，规划与取舍失去标尺 | -| S02 体力与状态 | 全局行动成本 | 各系统行动请求、食物与休息 | 体力变化、昏倒、状态效果 | 没有它，"想做的事多于做得到的"不成立 | -| S03 农场经营 | 核心产出与规划场 | 时间 tick、种子与工具、体力 | 作物畜产品、设施生产状态 | 概念核心承诺的载体 | -| S04 探索与地图 | 活动场景与空间约束 | 移动指令、区域解锁条件 | 位置、区域状态、资源点入口 | 没有空间结构，农/矿/镇一体失去意义 | -| S07 物品与制作 | 资源身份与转化 | 各系统获得物、配方请求 | 物品实例、制作结果 | 所有系统产出的公共语言 | -| S08 成长与技能 | 长期回报层 | 各活动经验提交 | 等级、能力与配方解锁 | 长期动机的最小载体 | -| S09 经济与商店 | 投资与回报换算 | 物品、金钱 | 价格、交易、库存 | 没有它，"变现 vs 投资"张力无载体 | +| S01 | 时间与日程 | 时钟、日期、季节、天气，时间通知与日终流程协调 | 基础时间、天气与跨日推进 | `project/03_systems/S01_time_schedule/` | +| S02 | 体力与状态 | 体力、恢复、昏倒和状态效果，处理活动提交的成本 | 农务与采集的行动成本、休息恢复 | `project/03_systems/S02_stamina_status/` | +| S03 | 农场经营 | 土地、作物、畜牧、设施生产状态与生产规则 | 耕种、浇水、生长与收获 | `project/03_systems/S03_farm_management/` | +| S04 | 探索与地图 | 区域、出入口、角色位置、资源点位置与可用状态，执行移动和区域开放 | 农场、小镇与基础采集区域 | `project/03_systems/S04_exploration_map/` | +| S05 | 采集与钓鱼 | 活动判定、获得物与品质规则 | 基础采集；钓鱼后续加入 | `project/03_systems/S05_foraging_fishing/` | +| S06 | 战斗与敌人 | 战斗过程、敌人状态、伤害和战利品请求 | 后续矿井遭遇原型 | `project/03_systems/S06_combat_enemies/` | +| S07 | 物品、背包与制作 | 物品身份、实例、容器、配方、工具装备及通用制作队列 | 种子、工具、采集物和农产品的持有与使用 | `project/03_systems/S07_items_inventory_crafting/` | +| S08 | 成长与技能 | 经验、等级、能力与配方解锁条件 | 基础农务或采集成长 | `project/03_systems/S08_progression_skills/` | +| S09 | 经济与商店 | 货币、价格、交易、库存及营业条件 | 买种、出售与基础投资 | `project/03_systems/S09_economy_shop/` | +| S10 | NPC 与关系 | NPC 日程内容与执行进度、对话、好感和关系事件 | 后续关系原型 | `project/03_systems/S10_npc_relationship/` | +| S11 | 任务与社区目标 | 任务状态、奖励、社区进度和区域解锁条件 | 后续社区目标原型 | `project/03_systems/S11_quests_community/` | +| S12 | 事件与节日 | 节日内容、触发条件、活动流程与完成状态 | 后续节日内容 | `project/03_systems/S12_events_festivals/` | -## 系统职责 +本例按完整农场生活游戏的规则边界分别展开系统；上表目录用于策划文档，实现代码由施工方按工程约束组织。UI 行为与存档要求在 TDD 中展开。 -| 系统 | 主要职责 | 不负责 → 移交谁 | -|---|---|---| -| S01 时间与日程 | 时间推进、日期、季节、天气、营业与日终 | 直接决定某项活动的奖励 → 各活动系统 | -| S02 体力与状态 | 行动消耗、恢复、昏倒、状态效果 | 农作物或敌人的具体配置 → S03/S06 | -| S03 农场经营 | 土地、作物、畜牧、设施生产 | 商店买卖规则和角色技能 → S09/S08 | -| S04 探索与地图 | 区域连接、进入条件、资源点位置、移动 | 具体掉落概率和战斗公式 → S05/S06 | -| S05 采集与钓鱼 | 采集和钓鱼行为、成功条件、获得物 | 物品价格和任务奖励 → S09/S11 | -| S06 战斗与敌人 | 战斗流程、敌人状态、伤害与战利品请求 | 角色长期成长和商店价格 → S08/S09 | -| S07 物品与制作 | 背包、物品、配方、制作与工具装备 | 物品最终经济价值的平衡目标 → S09 | -| S08 成长与技能 | 经验、等级、技能分支、能力解锁 | 单次行动的基础奖励 → 各活动系统 | -| S09 经济与商店 | 货币、交易、库存、订单、价格 | 任务剧情与 NPC 情感变化 → S10/S11 | -| S10 NPC 与关系 | 日程、互动、好感、关系事件 | 全局季节推进和商店库存 → S01/S09 | -| S11 任务与社区 | 目标、前置、奖励、社区进度和解锁 | NPC 的日常行为表现 → S10 | -| S12 事件与节日 | 周期事件、特殊流程和限定内容 | 常规日常行动的基础规则 → 各活动系统 | +S03 的设施生产与 S07 的通用制作若共用配方，应引用同一定义，不各自复制材料与产出规则。 -职责说明： +## 协作与数据归属 -### S01 时间与日程系统 -负责一天制的节奏规则：什么时候推进日期、哪些系统收到跨天 tick、日终结算何时发生。它不负责奖励结算，也不负责作物成长规则——只负责"什么时候"和"谁被通知"。 +以下表格描述行动处理和通知，不把所有关系混成同一种依赖箭头。 -### S06 战斗与敌人系统 -负责战斗内状态、敌人行为与战利品请求。它不直接修改商店价格或 NPC 好感，不负责角色长期成长；战利品只提交请求，由 S07 物品系统入账。定位是矿井探索的风险与节奏变化，不是成长主轴（D-03）。 - -### S07 物品、背包与制作系统 -负责物品身份、容器、堆叠与配方队列。它是全项目的公共语言层——任何系统的产出都以 `item_id` 入账；它不负责物品的经济价值平衡，价格只由 S09 维护。 - -## 依赖与数据流 - -```mermaid -flowchart TD - S1[S01 时间与日程] --> S2[S02 体力与状态] - S1 --> S3[S03 农场经营] - S1 --> S4[S04 探索与地图] - S1 --> S10[S10 NPC 与关系] - S1 --> S12[S12 事件与节日] - S3 --> S7[S07 物品与制作] - S4 --> S5[S05 采集与钓鱼] - S4 --> S6[S06 战斗与敌人] - S5 --> S7 - S6 --> S7 - S7 --> S9[S09 经济与商店] - S7 --> S8[S08 成长与技能] - S8 --> S7 - S10 --> S11[S11 任务与社区] - S12 -.读取日期季节.-> S1 - UI[UI 与文本呈现] -.读取状态.-> S1 - UI -.读取状态.-> S3 - UI -.读取状态.-> S7 - SAVE[存档与进度] -.订阅持久状态.-> S1 -``` - -```mermaid -flowchart LR - T[时间/体力] --> ACT[玩家行动] - ACT --> GAIN[物品·金钱·经验·关系·任务进度] - GAIN --> INV[制作·交易·升级·解锁] - INV --> NEW[新的行动选择] - NEW --> ACT -``` - -主要状态： -- 全局状态：日期、季节、天气、当前时间、已解锁区域、社区进度。 -- 玩家状态：位置、体力、生命、技能等级、工具、装备、背包和金钱。 -- 场景状态：土地、作物成长、设施生产、资源点、敌人和宝箱。 -- 社会状态：NPC 位置、关系值、已触发事件、任务阶段和节日参与状态。 - -主数据归属规则： -- 规则文档描述"如何计算"和"何时发生"；数据表描述"有哪些对象"和"每个对象的配置"。 -- 系统之间通过稳定 ID 关联（物品 ID、NPC ID、区域 ID、任务 ID、配方 ID）。 -- 任何系统都不复制另一系统的主数据；任务只引用物品 ID，不重新定义物品价格。 - -## 核心循环覆盖检查 - -| 顶层循环环节 | 认领系统 | +| 行动或时机 | 协作与结果归属 | |---|---| -| 查看天气、日程与目标 | S01、S11、S12、UI | -| 选择活动并移动 | S04、S02 | -| 农务与生产 | S03、S07、S02 | -| 采集、钓鱼与战斗 | S04、S05、S06、S07 | -| 出售、购买与投资 | S09、S07、S03 | -| 社交与委托 | S10、S11、S07 | -| 日终结算与保存 | S01、S12、存档、UI | +| 播种与农务 | S03 检查地块及行动条件，S07 检查种子或工具，S02 检查行动成本；确认可执行后更新各自状态。失败时不留下仅扣种子或体力的部分结果 | +| 采集 | S04 确认资源点可用，S05 判定获得物，S07 入账，S08 接收活动经验；成功后由 S04 更新资源点状态 | +| 出售与购买 | S09 校验营业、库存与价格，S07 校验物品和容器；交易成功时双方分别更新所拥有的状态，失败时保持原状态 | +| 成长与解锁 | 活动系统报告成果，S08 更新经验与能力；S07 据此判断配方或工具能否使用，不自行维护另一套技能进度。社区区域解锁由 S11 判断条件，再由 S04 更新开放状态 | +| 日终 | S01 停止当日行动并协调结算；S03 推进作物与生产、S09 结算出货、S08 结算成长，之后汇总反馈并保存。跨日通知让各系统准备次日状态 | +| 居民行动与节日 | S10、S12 读取 S01 的日期与时间，按各自规则决定活动；需要移动时交给 S04，不反过来推进全局时钟 | -## 目录映射 +表中保留架构需要的协作概述。农务、采集、交易和日终的完整流程分别在上表 S03、S05、S09、S01 对应文档展开；参与方说明自身处理及结果，不各自复述完整流程。TDD 收编并补齐失败后果和影响玩法结果的结算顺序，施工方选择满足结果一致性的实现。日终保存应包含已经完成的结算，不能读档后重复发放同一次收益。 -| 目录 | 本阶段定位 | +系统通过 `item_id`、`npc_id`、`region_id`、`recipe_id` 等稳定标识关联，数据按职责表归属维护。UI 从权威状态刷新，提供操作入口，只读展示副本不承担结算；存档快照在结算完成后生成，读档时恢复到对应系统。 + +跨系统共享的约束： + +- 时间与生产使用一致的游戏时间单位，行动成本、制作时长与跨日成长须说明对应关系。顶层暂定常规游戏日约 10～20 分钟，实际换算与暂停规则在后续规格中明确并试玩验证。 +- 经验是持续积累的进展，不作为货币消费。 +- 失败后果按顶层场景分别处理：矿井倒下可能损失部分钱物，换季可能使作物枯萎，同时保留大部分长期进展。涉及体力、物品、金钱或位置的变化由各自负责系统执行。 + +## 实现范围与验证 + +首个原型包含 S01、S02、S03、S04、S05、S07、S08、S09 的上述基础能力，加上必要的 UI 与存读档。完整版本还需展开钓鱼、制作、畜牧、战斗、居民关系、社区目标与节日等能力；完整清单不等于首个原型的施工范围。 + +首个流程从查看天气和选择目标开始，经农务或外出采集获得进展，再通过出售、购买和日终进入下一天。单日用于观察计划与取舍；连续数日用于覆盖作物生长、收获、投资和基础成长，不要求作物一天内完成播种到收获。 + +| 验证问题 | 内容与判断依据 | |---|---| -| 03_systems/S01_time_schedule/ | 时间推进、日期季节天气、营业时段、日终结算 | -| 03_systems/S02_stamina_status/ | 体力、状态效果、昏倒与恢复 | -| 03_systems/S03_farm_management/ | 土地、作物、畜牧、设施生产 | -| 03_systems/S04_exploration_map/ | 区域、连接、资源点、解锁与移动 | -| 03_systems/S05_foraging_fishing/ | 采集、钓鱼、品质与获得物 | -| 03_systems/S06_combat_enemies/ | 战斗、敌人行为、伤害与战利品请求 | -| 03_systems/S07_items_inventory_crafting/ | 物品、背包、配方与制作队列 | -| 03_systems/S08_progression_skills/ | 技能经验、等级、工具升级、能力解锁 | -| 03_systems/S09_economy_shop/ | 货币、买卖、价格、库存与订单 | -| 03_systems/S10_npc_relationship/ | NPC 日程、对话、好感与关系事件 | -| 03_systems/S11_quests_community/ | 任务、社区目标、奖励与解锁条件 | -| 03_systems/S12_events_festivals/ | 季节事件、节日、条件触发 | -| 支撑层不单开系统文档 | 存档与 UI 随实现层组织，规则不独立成文 | +| 基础系统是否共同支持日常计划 | 试玩农务与采集，观察时间、体力、物品和金钱变化是否一致，结合玩家说明判断选择是否有意义 | +| 跨日成果能否支持后续计划 | 连续游玩并存读档，检查作物、交易与成长是否持续且无重复结算，结合玩家反馈判断是否形成新的目标 | +| 战斗是否改善探索节奏 | 后续加入 S06 与矿井所需的地图、状态和物品能力，观察战斗理解、损失恢复及其对日常活动的影响 | +| 关系与社区是否形成长期目标 | 后续加入 S10、S11 及对应内容，观察多日投入与目标选择；单日原型不据此判断长期体验 | -## MVP 最小闭环 -1. 玩家在一个游戏日内完成开垦、播种、浇灌，并看到成长状态反馈。 -2. 在时间与体力约束下选择当日主目标（农场劳动或外出）。 -3. 外出采集（或矿井轻度战斗）带回资源。 -4. 通过出售或加工获得金钱，投资种子或工具。 -5. 日终结算展示当日变化并保存。 -6. 次日作物状态变化，玩家据此形成新计划。 -7. 数个游戏日内出现第一次技能提升与配方解锁。 +以上是验证计划，尚未形成试玩结论。出现问题时先判断是玩法目标不成立、协作职责遗漏还是实现错误，再调整相应设计与范围。 -如果这条闭环不成立，不应继续增加钓鱼深度、节日、社区目标或更多区域。 +## 风险与未决问题 -## 统一数值基准 -本案例采用"宽松治愈型"数值风格。全局单位：时间片、游戏日、货币、体力、经验；所有数值字段必须注明单位。 -- 时间节奏基准：单次常规行动控制在短时间片内；玩家一天应能完成农务、一个主要外出目标和少量顺路活动；早期玩家不应因一次路线失误失去整天进度。 -- 货币量级基准：主要货币只有一种；初期基础种子可用少量日常产出购买；一次普通收获不应立刻买下最高阶升级；任务奖励以补足短期资金为主，不替代生产交易。 -- 成长回报基准：前几级在正常尝试一种活动的数个游戏日内出现；升级奖励优先采用节省时间体力、扩大选择和解锁配方，而非单纯提高伤害售价；专长分支宽松可恢复。 -- 体力与风险基准：体力是规划提示不是严苛倒计时；普通农务与移动成本低，战斗、钓鱼和重型工具才产生明显取舍；失败成本采用时间、少量金钱或位置变化，不损毁进度。 - -（具体换算数值与前五日验算由技术文档层·数值策划承接。） - -## 系统边界 -- 农场经营只管理农场内的生产状态，不负责所有资源的通用背包逻辑。 -- 探索与地图只管理"在哪里"和"能否进入"，不管理每种活动的具体奖励。 -- 战斗只管理战斗内状态和战利品请求，不直接修改商店价格或 NPC 好感。 -- NPC 与关系负责互动和关系变化；任务与社区负责可验证目标，二者通过事件和条件连接。 -- UI、文本和表现不反向承载核心规则；所有关键变化必须由规则系统确认。 -- 本案例不拆出独立多人、拍卖、复杂天气模拟、动态市场或高复杂度叙事工具系统。 - -## 优先级与范围 -- P0（最小可玩闭环）：时间与日程、体力、农场、物品背包、经济、基础地图、基础成长和日终结算。 -- P1（形成完整案例）：采集、钓鱼、轻度战斗、NPC 关系、任务、社区目标、制作、商店、季节和节日。 -- P2（扩展内容）：更多区域、敌人、作物、配方、关系事件、节日小游戏和终局后的自由活动。 - -拆分系统不等于所有系统都要在最小版本同时实现；系统独立性是为了便于协作和后续裁剪。 - -## 风险与校验 - -| 风险 | 校验方式 | -|---|---| -| 农场变成例行公事，失去规划感 | 玩家是否在目标选择阶段出现真实取舍与计划调整 | -| 矿井战斗反客为主 | 战斗收益是否仍以"农场难以产出的材料"为主，而非直接金钱 | -| 时间压力变成打卡义务 | 休闲型玩家能否自由调低日程重量而不被惩罚 | -| 经济成长过快，后期失去决策 | 升级价格是否持续制造"效率 vs 规模"的选择 | -| UI 泄题，探索失去意义 | 关键信息是否保留为探索发现而非全量直读 | -| 系统间主数据重复维护 | 交叉检查：同一事实是否只有一个系统拥有写权 | - -## 开放的结构问题 -- 体力与生命是否保持为两个状态，还是在轻度战斗中共享一套风险资源？ -- NPC 日程、任务条件和节日事件之间采用统一条件格式还是各自维护？ -- 农场设施生产是否由农场系统统一管理，还是交给通用制作队列？ -- 采集、钓鱼和战斗是否共享统一的"活动结果"接口？ -- 哪些系统需要独立数据表，哪些小型配置应合并为一张内容表？ +- 时间、体力和收益可能共同把休闲生活变成赶任务：沿用顶层验证计划，比较不同玩家的计划调整与压力反馈。 +- 农场生产、制作和交易可能重复消费或入账：在系统规格中明确提交与失败处理，在实现阶段验证中断和日终存读档后的结果。 +- 社区目标采用章节、可选收集还是组合仍需展开：在该内容进入实现范围前确定，并补齐 S11 与 S04 的解锁协作。 +- 体力与战斗生命是否共享、战斗最低深度如何确定：不阻塞基础日常原型，在战斗原型前解决，再补齐 S02、S06 及相关 TDD 规格。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/stardew-concept.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/stardew-concept.md index b599c61ac..f98040f3c 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/stardew-concept.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/stardew-concept.md @@ -1,63 +1,43 @@ # 概念设计：《星露谷物语》 -## 一句话概念 -《星露谷物语》是一款以经营农场为基础、融合探索、采集、制作、轻度战斗、角色成长与社区叙事的乡村生活模拟 RPG；玩家通过安排每日时间与体力，把荒废农场逐步建设成理想家园，并与周围居民建立关系。 +## 游戏概念 -## 定调与设计锚点 +《星露谷物语》是一款以经营农场为基础、融合探索、采集、制作、轻度战斗、角色成长与社区叙事的乡村生活模拟 RPG。玩家安排每日时间与体力，把荒废农场逐步建设成理想家园，并与周围居民建立关系。吸引力在于按自己的节奏塑造生活：今天的选择让明天更从容，社区关系让独居逐渐变成归属。 -### 定调记录 -- 参照选择：以牧场物语系为主（无压力日常方面学动物森友会）；不参考任何高难动作与生存类游戏。 -- 调性滑杆：压力感 低 / 战斗比重 低 / 管理深度 中 / 叙事比重 中低 / 节奏 慢。 -- 调性锚： - T1 轻松治愈、自己的节奏（目标体验）；T2 不劝退、无唯一最优解（体验门槛）；T3 战斗轻度、非高难动作（非目标）；T4 以"游戏日"为单位、可反复的单人体验（情境）；T5 时间体力有限但休闲不打卡（跑偏风险）；T6 小团队可维护的规模（关键约束）；T7 日常叙事而非宏大主线，隐藏信息不迫使玩家查攻略（非目标/跑偏风险）。 +## 体验与玩法 -### 设计锚点 -- 核心幻想：离开令人疲惫的城市生活，继承一片荒废土地，在自己的节奏中经营、探索、成长，并成为社区的一员。 - 玩家念头："再玩一天就好——今天做完想做的事，明天的一切都会更顺手。" -- 目标体验：治愈、自由规划、持续成长、发现秘密，以及"今天的选择会让未来更轻松"的掌控感。 -- 玩家动机：改善农场与生活条件；发现新区域和资源；完成社区目标；提升技能；与 NPC 建立关系；按照自己的偏好塑造生活方式。 -- 核心循环：安排一天的时间与体力 → 进行农业、采集、钓鱼、采矿、战斗或社交 → 获得资源、金钱、经验与关系进展 → 投资工具、设施、种子和物品 → 解锁更高效或更丰富的活动。 -- 跑偏风险：系统过多导致目标分散；时间与体力限制把休闲体验变成每日打卡；隐藏信息迫使玩家依赖外部攻略；经济成长过快使后期失去决策。 -- 非目标：不做多人竞争、高难度动作战斗、唯一最优效率经营、主线剧情取代日常（详见《不是什么》）。 +玩家通过改善农场、发现资源与区域、提升技能、完成社区目标和发展人际关系，获得自由规划、持续成长与发现秘密的乐趣。既可以追求效率，也可以把时间用于装饰、社交或探索。 -## 玩家身份与基调 -- 玩家身份：一名辞职逃离城市、继承祖父荒废农场的归乡人——不是拯救世界的英雄，是重新学会生活的人。季节与节日构成一年的节拍，日落结算构成每天的呼吸。 -- 情绪基调：温暖治愈，慢而踏实。可以有忙碌与轻度压力（时间、体力），不做生存焦虑（饥饿、债务倒计时）与黑暗题材；孤独感只作为被社区逐渐治愈的起点，不成为基调本身。 +主要游玩过程是：安排一天的时间与体力 → 进行农业、采集、钓鱼、采矿、战斗或社交 → 获得资源、金钱、经验与关系进展 → 投资工具、设施、种子和物品 → 解锁更高效或更丰富的活动，在下一天重新安排计划。 -## 风格与世界观 -复古像素风的温暖乡村世界。玩家来到一个正在现代化与传统生活之间摇摆的小镇，农场、商店、社区设施、自然区域和矿井共同构成可步行抵达的生活网络。世界观服务于生活模拟而非复杂设定解释：季节、天气、节日、居民日程和区域变化，让同一张地图随着时间产生生活感。叙事主要通过 NPC 日常对话、关系事件、任务和社区目标逐步展开。 +其中的重要取舍包括： + +- 时间与体力有限，玩家需要安排今天的优先级，做一件事意味着少做另一些事。 +- 出售资源能立即获得资金，保留资源制作设备和升级工具则能提高未来效率。 +- 农场提供可预测的收益；探索可能带来新资源和发现，也会消耗时间、承担风险。 +- 赚钱占用社交时间；发展关系会减缓眼前收入增长，但能带来配方、剧情和情感回报。 +- 季节、节日和社区目标提供方向；追赶这些目标会占用自由安排日常的空间，错过部分机会则需要等待或调整计划。 + +## 身份、基调与世界观 + +玩家是一名辞职离开城市、继承祖父荒废农场的归乡人，在经营与探索中重新建立生活，并成为社区的一员。日落结算构成每天的节拍，季节与节日带来更长周期的变化。 + +情绪基调温暖治愈，节奏慢而踏实。时间与体力可以带来忙碌和轻度压力，但不以饥饿、债务倒计时或黑暗题材制造生存焦虑；孤独感是逐渐融入社区的起点。 + +视觉采用复古像素风的温暖乡村。农场、商店、社区设施、自然区域和矿井组成可步行抵达的生活网络。季节、天气、节日、居民日程和区域变化让同一张地图产生生活感；叙事通过日常对话、关系事件、任务和社区目标展开。 + +参照牧场物语系的农场生活组织方式，以及动物森友会的自定义、装饰和按自己节奏整理日常的体验；农业经营中的时间、体力、季节取舍与社区修复仍是本例的重要内容。参照用于说明体验，不复制具体角色、文本、美术、地图或数值。 ## 目标玩家与情境 -- 目标玩家：与牧场物语系受众高度重合——喜欢种田与小人际的慢节奏成长玩家；同时吸收动物森友会式"无压力日常整理"的需求（自定义、装饰、按自己的节奏玩）。但它不能变成纯装饰沙盒，因为农场经营的时间、体力与季节取舍，以及社区修复目标必须始终存在。 -- 适合情境：单人、可反复游玩、每次一个游戏日或几个游戏日；可以高效规划，也可以把时间用于装饰、社交或探索。 -- 体验门槛：需要理解基础资源转换和时间安排，不应要求预先掌握复杂数值或寻找唯一正确答案。 -## 不是什么 -| 不是 | 因为 | -|---|---| -| 硬核生存农场模拟 | 没有饥饿、债务、死亡惩罚；压力止于温和的时间与体力 | -| 效率至上的工厂经营 | 不要求唯一最优解，装饰与闲逛是合法玩法而非浪费 | -| 以战斗为核心的动作游戏 | 战斗只是采矿与探索的伴生风险，深度刻意受限 | -| 剧情驱动的叙事游戏 | 社区叙事是日常的背景与情感回报，不是任务链主线 | -| 多人社交平台 | 单人体验为前提，人际关系由 NPC 关系承载 | -| 无边界开放世界 | 地图是功能明确的小区域网络，全部可步行抵达 | +面向喜欢种田、人际关系与慢节奏成长的玩家，也容纳偏好装饰、收集和自由安排日常的玩家。 -## 核心张力 -- 时间与体力有限，但想做的事情很多：玩家必须决定今天的优先级。 -- 立即变现与长期投资：出售资源能快速获得资金，制作设备和升级工具则能提高未来效率。 -- 稳定经营与未知探索：农场提供可预测收益，矿井、钓鱼和新区域提供风险与发现。 -- 个人效率与社区关系：把时间用于赚钱会挤压社交，但关系又会带来配方、剧情和新的情感目标。 -- 自由生活与阶段目标：玩家可以自由安排日常，同时受到季节、节日、任务和社区修复目标的轻度牵引。 +本例围绕可反复游玩的单人体验，每次可玩一个或几个游戏日。玩家需要理解基础资源转换和时间安排，不应依赖复杂数值计算或寻找唯一正确答案才能推进。 ## 边界与约束 -- 概念层只定义核心幻想、目标用户、体验基调与排除方向；具体战斗公式、作物成长天数、礼物偏好、掉落率、系统清单和 MVP 内容，留给顶层及以后决定。 -- 设计规模以单人或小团队可理解、可维护为前提；地图采用多个功能明确的区域，而非无边界开放世界。 -- 所有系统都必须回流到"安排一天并获得长期改善"的核心循环；独立小游戏或装饰功能不能成为主要范围扩张来源。 -- 案例声明：本文以《星露谷物语》为案例展示设计的组织方式，不复制其具体角色、文本、美术、地图或数值。 -## 概念定稿 -《星露谷物语》的核心不是"种田赚钱"，而是： -> 在自己的节奏里经营一片土地与一段生活——今天的选择让明天更从容，而社区让独居变成归属。 - -交给下一层的约束：时间与体力必须构成温和而非焦虑的取舍；战斗、采矿、社交等支线必须回流农场生活循环；成长权重要允许玩家自定义（效率型与休闲型玩家都成立）。 -（调性已在第 2 节定死；顶层及以下一切开放问题先回定调记录的 T1~T7 级联。） +- 战斗服务于采矿与探索，不扩展为高难度动作游戏；社区叙事提供日常背景与情感回报，不用宏大主线取代农场生活。 +- 时间和体力形成温和的取舍，避免把休闲变成每日打卡。装饰、闲逛和社交都有价值，不以唯一最优效率为目标。 +- 本例按单人或小团队规模控制内容，地图采用功能明确的小区域网络，不扩展为无边界开放世界或多人社交平台。 +- 各系统服务于日常生活及其长期改善。独立小游戏或装饰内容的扩张不能挤占核心体验；同时避免经济成长过快使后期失去选择，或隐藏信息迫使玩家依赖攻略。 +- 后续设计应允许效率型和休闲型玩家按自己的偏好成长；具体系统范围、版本内容、战斗公式、作物成长天数和掉落率等再逐步展开。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/stardew-s06-combat.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/stardew-s06-combat.md index 8bd6ac7fe..fc4a3c376 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/stardew-s06-combat.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/stardew-s06-combat.md @@ -1,120 +1,44 @@ # 战斗与敌人系统：S06 -## 系统目的 -为危险区域提供轻度、可理解的战斗挑战，使玩家在探索中承担风险，并通过装备、补给和技能成长验证长期准备。战斗是生活模拟循环的支柱之一，不是游戏的唯一核心。 +版本：v2 -## 支撑的玩家体验 -- 玩家能观察敌人行为，选择攻击、躲避、补给或撤退。 -- 战斗结果主要取决于准备、判断和适度操作，而不是高强度连招。 -- 深入危险区域会带来更高资源和成长回报，也会增加生命、时间和补给压力。 -- 失败有明确原因和可恢复成本，不应摧毁长期农场进度。 +## 职责与原型范围 -## 进入与退出 -### 进入 -- 玩家进入允许战斗的危险区域或触发敌人遭遇。 -- 检查区域、时间、装备、生命、背包和任务条件。 -- 初始化当前战斗区域、敌人组合、战斗状态和可撤退条件。 -### 退出 -- 击败敌人并完成战斗奖励结算。 -- 玩家主动撤退或离开战斗区域。 -- 玩家生命归零，由体力与状态系统执行昏倒或失败惩罚。 -- 特殊事件、日终或区域状态强制结束战斗。 +战斗服务于矿井探索中的风险与节奏变化，不扩展为高难度动作或装备构筑主轴。S06 负责敌人行为、攻击与伤害判定、战斗结果和战利品请求；通过 S02、S04、S07、S08 等系统完成玩家状态、位置、物品和经验更新。 -## 玩家行动 -- 移动、观察敌人攻击范围和行为状态。 -- 普通攻击、重攻击或使用装备技能。 -- 防御、闪避、格挡或利用场景短暂规避伤害。 -- 使用食物、药剂等消耗品。 -- 拾取战利品、调查宝箱或选择继续深入。 -- 在满足条件时撤退，保留已结算的奖励。 +战斗不属于首个日常原型。后续矿井原型暂按实时操作展开，先验证移动避让、普通攻击、补给与撤退；重攻击、独立闪避或格挡技能、首领等内容暂未纳入。以下是供验证的方案，尚未形成试玩结论；生命与体力关系、具体判定参数等缺口需在战斗进入施工范围前补齐。 -通用流程： -`进入遭遇 → 读取敌人状态 → 玩家行动 → 敌人响应 → 结算伤害/效果 → 判断胜负或撤退` +## 遭遇与行动 -## 取舍表 +玩家经 S04 进入可战斗区域，S06 根据该区域的遭遇配置和已有敌人状态建立遭遇。区域、出入口及角色位置由 S04 提供，位置变化通过 S04 执行；S06 使用实际位置判定。进入区域本身不消费补给或发放奖励；消耗发生在实际行动成功时。 -| 决策 | 立即收益 | 延迟收益 | 主要代价 | -|---|---|---|---| -| 继续深入还是安全撤退 | 更多资源 | 更高风险与返程压力 | 已得战利品可能损失 | -| 消耗品现在用还是留着 | 维持当前探索 | 应对更强敌人 | 局部战况恶化 | -| 快速击败还是稳健闪避 | 节省时间 | 降低受伤风险 | 补给与时间消耗 | -| 高伤高耗装备还是基础攻击 | 更快击杀 | 稳定与低消耗 | 资源消耗大 | -| 资金投武器防具还是农场设施 | 战斗能力 | 农场产能 | 另一侧进度放缓 | +玩家观察敌人位置与攻击准备，选择接近攻击、移动避让、使用补给或沿可用出口撤退。普通攻击引用 S07 维护的武器标识与战斗属性、S08 已生效的能力，检查武器、距离、方向和动作间隔后按命中规则结算；攻击范围、伤害计算与动作间隔的具体定义尚待补齐。补给的持有和消耗由 S07 处理，恢复效果交 S02 更新，使用失败不能只扣除物品。 -## 状态与规则 -### 玩家战斗状态 -- 当前生命、最大生命和状态效果。 -- 装备中的武器、防具、饰品和消耗品。 -- 攻击、防御、移动、闪避和技能冷却状态。 -- 当前战斗区域、遭遇编号和撤退状态。 -### 敌人状态 -敌人状态至少包括待机、警觉、攻击前摇、攻击中、受击、眩晕、死亡和撤退。 -每个敌人的实例数据（生命、位置、目标、状态效果、掉落引用）的字段定义由技术文档层承接。 -### 战斗规则 -- 只有满足攻击距离、方向、冷却和装备条件时，攻击才可结算。 -- 伤害由攻击来源属性、目标防御、技能倍率和状态效果共同决定。 -- 敌人攻击必须有可识别的前摇或预警，给予玩家反应与撤退机会。 -- 生命降至零时进入死亡或昏倒状态；具体惩罚由体力与状态系统处理。 -- 敌人死亡后只结算一次经验与战利品，并写入遭遇状态，避免重复领取。 -- 撤退后已完成的战斗奖励保留，未击败敌人按区域刷新规则处理。 -### 区域遭遇 -- 危险区域由敌人组、刷新规则、深度或阶段配置组成。 -- 进入更深区域可以提高敌人强度、资源价值和特殊遭遇概率。 -- 区域难度应通过可理解的装备、区域和任务条件表达，不依赖突然的数值墙。 -- 宝箱、精英敌人和首领可作为独立遭遇类型，但不在最小版本中同时扩张。 +击败一个敌人后可继续探索，不自动结束区域活动。沿出口离开时保留已入账的物品与经验；玩家倒下时进入失败处理，不能按安全撤退结算。日终等中断与伤害、拾取同时发生时的处理顺序，需要在矿井原型前明确。 -## 数值与数据交接（→技术文档层） -本系统交由技术文档层（数值策划）定义的数据类别：敌人配置、敌人行为配置、武器配置、技能配置、遭遇配置、战利品配置、状态效果配置。 +## 敌人行为与结果 -随交接附下的设计侧定性约束： -- 敌人数据拆分为"是什么 / 怎么行动 / 掉什么"三类，使难度与经济可独立调节。 -- 普通敌人不应稳定掉落大量高价值物品；战斗收益主要由矿物、经验和区域发现组成。 -- 稀有材料是"有明确用途的探索奖励"，但必须保留任务、宝箱等补充渠道，避免战斗失败后无法推进。 -- 基础战斗允许玩家一日内完成少量遭遇并安全返程，不要求连续刷怪。 -- 失败保留已结算的普通战利品，主要损失是时间、位置或少量金钱，不清空背包。 -- 自动化收益节省日常体力，但不能让玩家跳过农场维护的全部决策。 -- 收益回流方向：区域 → 敌人 → 材料 → 加工 → 农场自动化；战斗不直接取代农场收入。 +S06 维护敌人行为、战斗判定与击败记录。本原型以能接近玩家并进行近身攻击的普通敌人为起点：发现玩家后接近，进入攻击距离后给出可识别的准备动作，再执行攻击并恢复。失去目标后的行为、受击是否打断、离开区域后的恢复方式，以及敌人刷新与区域生命周期的衔接还需补齐；不为所有敌人预设眩晕、撤退等完整状态集合。 -## 反馈 -- 攻击命中、受击、闪避、格挡和暴击提供清晰的视觉与声音反馈。 -- 敌人显示生命、预警、当前状态和可攻击时机。 -- 玩家生命、补给、冷却和撤退可用性持续可见。 -- 战斗胜利显示经验、战利品和区域进度。 -- 失败说明主要原因，并明确损失、保留内容和可恢复路径。 +攻击准备应让玩家看懂危险并有机会应对，实际时长和表现通过试玩调整。伤害只在有效命中时结算，玩家生命、体力与状态效果由 S02 接收伤害或成本请求后更新，不能因动画或反馈重复播放而多次扣除。 -## 内部循环 -### 单次战斗循环 -`观察敌人 → 选择攻击或防御 → 处理敌人响应 → 造成或承受伤害 → 调整策略 → 击败或撤退` -### 危险区域循环 -`准备装备与补给 → 进入区域 → 战斗与搜刮 → 判断继续深入或返程 → 带回资源 → 升级能力` -### 长期循环 -`获得战斗经验与装备 → 提升生存能力 → 挑战更深区域 → 获得稀有资源 → 解锁新制作、任务或地图` +敌人被击败后停止行动；S06 为该次击败向 S07 提交一次战利品入账请求，将击败结果交给 S08 更新经验、S11 更新相关任务进度。物品入账失败时，待领取奖励如何保留、离开区域后能否再取，需在矿井原型前确定。存档保存敌人、奖励与各系统已完成的结果，拾取或恢复后不得重复发奖；TDD 写全影响玩法的顺序与恢复结果，具体持久化和更新机制由施工方决定。 -## 输入、输出与依赖 -### 输入 -- 探索与地图系统提供战斗区域、位置和遭遇入口。 -- 时间系统提供当前时间、季节和日终信号。 -- 体力与状态系统提供生命、体力、状态效果和失败处理。 -- 物品系统提供武器、防具、消耗品和战利品接收入口。 -- 成长系统提供属性、技能和装备解锁。 -- 玩家通过核心玩法系统提交战斗行动。 -### 输出 -- 向物品系统提交战利品和消耗品变化。 -- 向成长系统提交战斗经验和能力进度。 -- 向地图系统提交敌人、宝箱和遭遇状态。 -- 向任务与社区系统提交击败、调查和区域进度。 -- 向 UI 输出战斗状态、反馈、胜负和撤退结果。 +继续深入可以获得更多资源和经验，也会消耗时间、生命或补给并增加倒下风险；提前撤退保留当前收获，但放弃本次继续探索的机会。矿井中倒下沿用顶层设计：损失部分金钱或物品，保留大部分长期积累，补充准备后可以再次探索。倒下流程由 S02 协调，在其系统文档展开；S09、S07、S04 分别更新金钱、物品和位置。具体损失范围和幅度尚未确定，不承诺所有已入账战利品都免于失败损失。S01 提供时间与日终通知，涉及战斗的中断结果和先后顺序在补齐后交由 TDD 收编为完整规格。 -## 边界与非目标 -- 不负责通用生命与昏倒惩罚，只提交状态变化。 -- 不负责武器物品的背包、耐久和售价主数据。 -- 不负责字段定义、数值配置与表格结构——归技术文档层（数值策划）。 -- 不做高难度动作连招、复杂多人战斗或精确帧竞速。 -- 不让战斗成为获得普通农场资源的唯一方式。 -- 不在本系统中定义全部敌人、武器和首领内容。 +战斗收益服务于本例的探索与生活成长，具体掉落和经济关系结合物品用途及收益平衡确定；本例的取向不作为其他游戏的通用战斗限制。 -## 开放问题 -- 战斗采用实时操作，还是更简化的节奏/指令判定？ -- 体力是否影响攻击与闪避，还是只影响探索和农务？ -- 武器是否有耐久度，还是通过升级与装备更换形成消耗？ -- 战斗失败的主要成本采用金钱、位置、时间，还是有限组合？ +当前范围的敌人行为与属性、攻击判定、区域遭遇、物品关系、奖励和失败后果均需在 TDD 中写全规则与当前采用值，不仅交接类别名称；内部字段与配置结构由施工方选择。 + +## 反馈与验证 + +UI 展示权威状态、接受操作请求，不自行判定伤害或发奖。玩家应能识别命中或受伤结果、当前生存状态与补给使用结果。无法攻击、使用物品或撤退时说明当前原因；倒下后说明损失、保留内容和返回位置。 + +| 场景 | 判断依据 | +|---|---| +| 遭遇普通敌人并攻击或避让 | 玩家能理解攻击准备，伤害与实际命中一致；结合试玩反馈判断操作压力是否符合轻度战斗定位 | +| 击败、拾取并存读档 | 物品与经验正确入账，同一次击败不会重复结算；入账受阻时按补齐后的奖励保留规则处理 | +| 安全撤退与矿井倒下 | 撤退保留已入账成果；倒下执行明确的部分损失，提示与各系统实际结果一致 | +| 使用补给或遭遇日终中断 | 物品与恢复结果一致，中断按补齐后的顺序结束处理，不留下部分扣除或重复收益 | + +以上为待执行的验证场景。战斗进入实现范围前，还需明确生命与体力关系、敌人行为与刷新、伤害和动作参数、奖励入账受阻处理、失败损失及日终中断顺序，并同步 S02、S04、S07、S08、S09 和相应 TDD。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/stardew-tdd-art-bible.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/stardew-tdd-art-bible.md index 87ecd930c..e2ad224bd 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/stardew-tdd-art-bible.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/stardew-tdd-art-bible.md @@ -1,82 +1,62 @@ -# 美术圣经：《星露谷物语》（TDD 金样 · 美术圣经） +# 美术圣经：《星露谷物语》首个日常原型（TDD 示例） -> 状态：reviewed　|　定调锚：概念层@v1 第 2 节（定调记录：牧场物语系参照、压力低/节奏慢/治愈）　|　style_id：`stardew_warm_rural_pixel` -> 实证规格来源：星露谷 1.6.15 解包知识库 v3（资产计数时点 2026-09-11，快照 stardew-1.6.15-7f1e5b8e）。写新项目时按本项目定调重译，数字仅作规模参照。 +## 范围与设计依据 -## 视觉风格总览 +本例只覆盖首个日常原型：农场、小镇、基础采集区域；耕地、播种、浇水、跨日生长、收获、买种、出售，以及时间、天气、体力、背包、金钱和日终反馈。它承接同目录 `stardew-concept.md` 的“身份、基调与世界观”“边界与约束”，以及 `stardew-architecture.md` 的“首个原型范围”“实现范围与验证”。矿井、战斗、NPC 日程、关系、钓鱼、畜牧、节日、多人和大批换装不在本次施工范围。 -从定调记录翻译的视觉气质：**"被四季照亮的温暖小农场"**——手绘感像素、俯视 45° 视角，春夏绿意、秋日暖橙、冬季留白，颜色随季节整体切换而不是换贴图；物件轮廓圆润、无锐利科技感。玩家一看画面就该感到：这里节奏很慢，干活是安心的。参考图位 4 张（量产流程第 3 步产出锚点图）。 +视觉依据是温暖乡村、复古像素、轻度压力和可反复游玩的日常节奏，来源版本见总册。**目前没有已选定的参考图、画风卡或可验收的源素材**；以下色值和尺寸是示例策划假设，供后续视觉确认。目标运行时是新建 2D Web 原型（npm + Vite + Phaser 4.2.1）。美术源文件和导出资源尚未产出，没有既有命名或帧表契约。施工方选择文件名、目录、打包和加载方式；运行素材须随构建进入 dist，预览与导出可正常使用。 -## 视觉锚 +## 视觉规则 -- 关键词：温暖、手绘像素、田园、四季分明、生活感。 -- 禁用关键词：阴暗压抑、血腥恐怖、高饱和霓虹、写实渲染、锐利科技风（承概念层 T3"战斗轻度"、T7"日常叙事"）。 -- 色板：主色 暖土绿系（草地/耕地基底）60% ／ 辅色 暖木棕+瓦顶红 30% ／ 点缀 季节信号色（春樱粉/夏浓绿/秋橙/冬蓝白）10%。昼夜·天气·季节表现：季节=色调与植被整体切换；天气=雨天全屏冷色叠加（原作 OrangeRed×0.45 实证）；昼夜=时刻线性插值环境光。 -- 形状语言：圆润矩形轮廓，物件以 16px 网格对齐；无 1px 高光乱线。 -- 比例与轮廓：物件 16px 一档；NPC 16×32（渲染放大 4 倍）；玩家可完全自定义外观。 -- 光照与材质：不做真实光照——低分辨率 lightmap 乘法混合；优先级链=矿井 tint＞室内 ambient＞室外 outdoor（时刻插值）；十种光源贴图常量够用。 -- 渲染口径：纯像素、无抗锯齿、整数倍缩放（程序侧能力边界同源）。 +- 关键词：温暖、朴素、清爽、生活感。避免血腥、霓虹、高反光写实材质、尖锐科技造型和繁密的随机像素噪点。 +- 色板示例假设：草地基色 `#78A85A`、泥土 `#9D7048`、木材 `#AA724C`、纸面 `#F2E1B9`、操作提示 `#E8BE62`、不可用 `#738291`。这些是设计锚点，实际调色板及色弱可辨性须在首批视觉样张中确认；状态不能只靠颜色区分。 +- 画面采用近正上方的斜俯视像素场景，地面按 16×16 世界像素网格排布。人物脚点落在格中心下沿；可遮挡的建筑/树冠在人物之上，地面和作物基座在人物之下。建筑、箱子和植物用圆润轮廓，亮面集中在左上，阴影不使用柔边渐变。 +- 游戏世界用最近邻采样、整数倍缩放和像素对齐；示例假设移动端世界像素放大 3 倍、桌面端 4 倍，布局可裁剪视野但不拉伸像素。HUD 使用清晰文字与图形，不把 16px 图标放大后作为 44 CSS px 的触控热区；热区由 UI 布局提供。 +- 当前范围只需晴、雨和日间至傍晚的可辨反馈。雨天在地面与图标之外加低强度冷色层和雨线；傍晚用统一环境色层。天气图示另带“晴/雨”文字，避免仅靠色调识别。季节全套换景不是首期要求。 -## 角色模板 +## 共性表现要求 -- 基础规则：玩家=换装组合而非整图——19 个独立层（基础体/裤/衣/发型/饰件/配件…），每层独立图集，调色板像素 256-277 区域换色实现同图集多变色；层深=基准+层序×1e-6 保证叠加次序稳定。NPC=16×32 四方向小人+64×64 立绘（对话用）。 -- 方向数：4 方向（左=右镜像：是——行走图按方向分行布局，如 64×448=4 列×14 行）。 -- 动画状态：待机/走 walk=4 帧循环、每帧 200ms（帧表含毫秒级帧时长）；受击/使用工具按动作逐条登记帧表。玩家帧表量大（原作 500+ 动画参数为 switch 硬编码），本项目帧表走数据表不走硬编码。 -- 立绘表情：六表情索引 0-5（$neutral/$happy/$sad/$unique/$love/$angry），对话文本中 `$表情` 标记驱动切换。 +下表参数均为示例假设；后续确定时应在本分册更新，不能视为已经产出的资产事实。同类共性只定义一次，对象与玩法状态的对应应明确，程序中的帧键和绑定方式由施工方决定。 -## 场景模板 +| 类别 | 共性表现要求 | 用途与必要约束 | 后续验收判据 | +|---|---|---|---| +| 地形 | 每格 16×16；地面可无透明，边缘衔接不留缝、不渗色 | 农场地块需随耕作与浇水改变外观；如何分层、拼装与打包由施工方选择 | 干湿耕地与普通土路在目标缩放下能区分，局部变化不破坏周围画面 | +| 场景物 | 按占格明确脚点和遮挡高度，交互状态有对应反馈 | 遮挡符合角色前后位置，显示与可交互区域一致 | 图像、脚点、碰撞/热点对齐；可交互物与背景有轮廓差异 | +| 玩家 | 单个 16×32 角色，不做换装层；上、下、左、右四方向待机与行走，工具动作表现待确定 | 脚点固定在底中心；行走可参考每方向 4 帧、左右镜像的制作方案，帧组织不是验收要求 | 四方向基准点一致，手势不误导，行走不抖动，工具行动与反馈一致 | +| 作物与采集点 | 作物占 1 格，以 16×32 范围表现生长；采集点有可采和已采状态 | 成熟和可采具有独立轮廓；可见生长阶段需与设计一致 | 未熟/成熟、可采/已采在移动视口能辨认，画面与实际状态一致 | +| 物品图标 | 16×16、透明背景；工具和产物留 1px 内边距 | 背包、商店、出售清单展示对应物品；金额和数量使用文字 | 图标对应正确，无空白或越界，种子、产物、工具形状可区分 | +| UI | 清晰文字与图形，天气图示及操作提示可用 16×16 图标；面板、槽位和进度条表现一致 | HUD、背包、商店、出售和日终状态与玩法结果一致，禁用态结合图形与文字 | 数字与图标不重叠，移动端热区暂定至少 44 CSS px，桌面/移动两视口可读 | +| 音频 | 环境 BGM 循环、目标 -18 LUFS，行动音效单发，均为本例假设 | 首次用户操作后启用，触发条件按设计；编码、文件组织及播放绑定由施工方选择 | 目标浏览器可播放，循环无接缝，事件不重复触发，反馈清楚且不盖过必要提示 | -- tileset 规格：16px tile；TileSheets 级图集约 41 张+地形特征图集 38 张（作物/树）；padding 1px 防渗色。 -- 图层拆分：四层 Back/Buildings/Front/AlwaysFront（深度 -1/0.1/64+/-1）——地面/建筑/前景遮挡/最前；碰撞由 Buildings 层属性驱动；矿井布局池按模板拼装（原作 61 张模板，本项目首期 8~12 张）。 -- 场景对象规则：多帧素材禁当静态贴图（作物生长/角色必须走帧表）；单元素禁整图（区域由 tile 拼装，禁为每区域画整张立绘）；地图数参照：原作 259 tmx+304 预览，本项目首期 3 区域（农场/小镇/矿井）。 +## 当前范围对象清单与例外 -## UI 视觉 +清单用对象组列出有限变体，适用上面的共性要求。物品和作物以数据分册的内容为准；文档标识便于对照，不要求同名程序键。数据分册尚未给完整首期清单，**不能据此宣称原型素材范围已全量对账**。 -承 UI 系统文档界面清单（HUD/背包/商店/对话/日终结算五界面）。视觉语言：木质面板底+纸张质感对话框；信息分层——价格信息永远暖金、锁定/禁用永远灰蓝、日终收入单列。字体用位图字体（原作 5 fnt 位图字体实证）。触控版式热区 ≥44px 与程序侧输入表同源。特效走程序动画（按帧表播图集区域）+粒子，不逐特效画整图（原作 LooseSprites 156 张 UI/杂项图集规模参照；最大图集实测 1920×1376）。 - -## 素材规格契约 - -| 素材 | 规格（尺寸/帧数/方向数） | 命名规则 | atlas 格式 | 验收 | 绑定 | +| 对象或明确对象组 | 类别 | 关联内容 | 状态与变体 | 表现要求或共性例外 | 出现位置 | |---|---|---|---|---|---| -| 物品图标 | 16×16，1 帧 | `icon_{item_id}` | JSON atlas | 技术+视觉 | `item_*` 全量（参照原作 807；本项目首期 ~120 行） | -| 作物 | 16×32×相位帧（4~5 相位，每相位 1~2 帧） | `crop_{crop_id}` | JSON atlas | 技术+视觉 | `crop_*`（参照原作 50） | -| 玩家换装层 | 每层独立图集，walk 4 帧×4 方向 | `farmer_{layer}_{state}_{dir}` | JSON atlas | 技术+视觉 | 豁免（角色非物品，登记于本表） | -| NPC 行走+立绘 | 行走 16×32 四方向行布局；立绘 64×64×6 表情 | `npc_{id}_walk` / `npc_{id}_portrait_{expr}` | JSON atlas | 技术+视觉 | `npc_*`（参照原作 34 社交 NPC/101 立绘；本项目首期 8 位） | -| tileset | 16px，边缘连接变体 | `tile_{theme}_{variant}` | JSON atlas | 技术+视觉 | 豁免（场景组件） | -| UI 面板 | 9 宫格切片，3 态 | `ui_{element}_{state}` | JSON atlas | 技术+视觉 | 豁免（UI） | -| BGM | ogg，-18LUFS，循环点标记 | `bgm_{season}` 4 首+矿井 1 首 | — | 响度+循环 | 豁免（音频契约） | -| SFX | wav 单发 | `sfx_{event}`（事件↔音效映射表登记） | — | 同帧触发 | 豁免（音频契约） | +| 农场、小镇、基础采集区域 | 地形/地图 | 三个区域及其连接关系 | 草地、土路、干耕地、湿耕地、边界与出入口 | 通路、阻挡与画面一致，耕作地块可独立变化；内部地图格式由施工方选择 | S04 地图、S03 地块展示 | +| 农舍外观、出货箱、小镇种子商店门牌 | 场景物 | 地图对象 `farmhouse`、`shipping_bin`、`seed_shop` | 默认；出货箱可交互、商店开/关由 UI 文本或标记提示 | 农舍可跨多格，需给实际占格与脚点；不为商店首期制作有日程的店员 | S04 地图与 S09 商店/出售入口 | +| 野外采集点 | 作物与采集点 | 地图中的可采集对象 | 可采、已采；刷新后回可采，触发时机待 S04/S05 定义 | 采集物外观与其背包图标可以不同 | S04 资源点、S05 采集反馈 | +| 防风草作物 | 作物与采集点 | 数据分册的 `crop_parsnip` | 播种后各生长阶段、成熟；浇水通过地块湿态呈现 | 四次满足条件的跨日不等于四个视觉阶段；可见阶段及对应生长进度待定 | S03 地块展示 | +| 玩家 | 玩家 | `player` | 四方向待机、行走；工具动作待确定 | 不做 19 层换装、立绘或 NPC 表情 | S04 移动、S03 农务、S05 采集 | +| 防风草种子、防风草 | 物品图标 | 数据分册的 `parsnip_seed`、`parsnip` | 每物品 1 图；数量与价格均由文字显示 | 只覆盖局部示例内容，不代表首期全量物品 | 背包、商店、出售清单 | +| 采集物、锄头、水壶 | 物品图标 | `wild_berry`、`hoe`、`watering_can` 是待数据确认的示意标识 | 每物品 1 图；数量与价格均由文字显示 | 数据规则与数值未定，不能据此进入全量生产；金币无需物品图标 | 背包、商店、出售清单 | +| 时间/天气/体力/金钱、背包、商店、出售、日终与存读档 | UI | S01/S02/S07/S09 状态与界面标识 | 晴/雨图示，体力进度与低体力提示，可买/不可买、可卖/不可卖、结算前后 | 数值、名称、日期、价格和说明由 UI 文本绘制；进度条和槽位可程序绘制，按界面无需逐状态出图 | HUD 与各界面 | +| 日常环境音乐与行动反馈 | 音频 | 日常环境及耕地、播种、浇水、收获、采集、购买、出售、日终行动 | 单一日常循环与各成功事件单发；失败提示是否需要独立音效待定 | 不预填四季或矿井音乐；各场景需要的声音效果与相对响度待补齐，文件名和内部绑定由施工方决定 | 场景音频、S03/S05/S09 与日终反馈 | -- 绘制工艺：按项目实际制作路径逐类记录参数与封装流程；施工环境无产出通道时规格先行锁定、状态如实登记"缺失"。 -- 音频契约说明：原作 XACT cue 名 435 候选/代码引用 230 个——本项目首期 SFX 事件 20 只起步，按事件总线 `sfx_event` 映射表登记，不逐 cue 复刻。 -- 豁免类型仅限：程序化生成（矿井布局由表驱动拼装）/ UI 文本 / 本期不需要——每项豁免在契约行写明。 +## 后续生产与接入验收 -## 资产状态表（asset manifest） +- 交付时保留可编辑源文件，运行资源的格式和组织由施工方按目标工程选择。可先用少量地形、角色、作物、图标和 UI 样张核对色板与比例，再按已定要求扩充；样张数量由实际疑点决定。 +- 接入与视觉验收按本册“共性表现要求”和“当前范围对象清单与例外”判断，不重列尺寸与状态；构建及资源可用性检查见技术分册。 +- 可请观察者在目标视口指出可操作对象与关键状态，检查是否依赖反复试错才能识别；截图数量和检查工具由施工方安排。尚无视觉验证结果，不能宣称已通过。 -| asset_id | 规格 | 绑定 | 状态 | 验收记录 | contract_version | -|---|---|---|---|---|---| -| icon_item_*（首期 ~120 行，逐 item_id 一行） | 16×16 | `item_*` | 缺失 | — | 1 | -| crop_*（50 行） | 16×32 相位帧 | `crop_*` | 缺失 | — | 1 | -| farmer_*（19 层图集） | 4 帧×4 方向 | 豁免 | 缺失 | — | 1 | -| npc_*_walk / _portrait（8 位×7 件） | 16×32 / 64×64×6 | `npc_*` | 缺失 | — | 1 | -| tile_*（3 主题变体组） | 16px 变体 | 豁免 | 缺失 | — | 1 | -| ui_*（5 界面套件） | 9 宫格 3 态 | 豁免 | 缺失 | — | 1 | -| bgm_*（5 首） | ogg -18LUFS | 豁免 | 缺失 | — | 1 | -| sfx_*（20 只） | wav | 豁免 | 缺失 | — | 1 | +## 当前未决问题 -- 状态单向流转：缺失 → 草稿 → 已交付 → 已验收 → 已接入；驳回退回草稿并记原因。 -- 验收两维：技术（尺寸/透明/帧数/命名）+ 视觉（对照视觉锚）；两维都过才进"已验收"。 -- **每个 gameplay 可见对象必有一行或显式豁免——没有第三种状态**：物品图标逐 item_id 与数据侧物品表逐行对账（参照规模：原作 Characters 215 png/Portraits 101/TileSheets 41/TerrainFeatures 38/LooseSprites 156）。 -- 程序接入后填消费点（哪个模块加载、事件映射），`contract_version` 变更须重验收。 - -## 量产流程与验证 - -1. 概念候选 4 张（农场一角/角色/物品图标/UI 面板各 1 方向稿）→ 2. 人选方向（用户确认）→ 3. 锚点图 4 张 → 4. 锁圣经 → 5. 写契约（本文件已锁）→ 6. 小批 8 张（icon_item 子集：防风草种子/防风草/木材/石头/铜矿/锄头/水壶/出货箱）→ 7. 技术检查（尺寸/透明/命名/atlas 解析）→ 8. 接入程序（v0.1 里程碑）→ 9. 运行时截图验收（桌面/移动双视口下 16×16 图标与作物相位可辨、四季色调正确）→ 10. 扩产（8→120→全量）。 - -## 开放问题回执 - -| # | 问题 | 去向 | +| 问题 | 对当前施工的影响 | 下一步与需更新的位置 | |---|---|---| -| 1 | 换装系统首期是否做全 19 层（或缩到 5 层） | → 台账代决（建议首期 5 层：基础体/裤/衣/发型/饰件；台账 D-17） | -| 2 | 锚点图方向需用户确认 | → 施工期提案卡 | -| 3 | 位图字体 vs 矢量像素风字体 | → 小批阶段随 UI 套件定 | +| 完整物品、采集对象与作物可见生长阶段未定 | 无法确认图标和生长表现是否覆盖全部内容；四次跨日不能代替视觉阶段设计 | 补全对象清单、可见阶段及对应的生长进度 | +| 采集区域规模、空间布局、出入口与阻挡要求仍不完整 | 场景内容与行走、探索体验未明确 | 补空间设计与场景物要求，同步 S04；地图数据结构由施工方选择 | +| 工具动作及对应玩家反馈尚未明确 | 无法判断农务动作是否足以表达当前操作与结果 | 补必要动作、反馈时机和表现要求；具体帧组织与 UI 实现由施工方选择 | +| 各行动成功或失败时的声音效果仍不完整 | 不能判断听觉反馈是否覆盖重要结果 | 补触发场景与听感要求；编码、图集 JSON、文件名和内部绑定未预定不构成策划缺口 | + +本例展示当前范围的表现要求与后续验收方法。对象、空间、动作与声音设计仍有缺口，因此不宣称美术策划案已完备；视觉验证在后续执行，内部资源组织不作为策划阻塞项。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/stardew-tdd-data.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/stardew-tdd-data.md index 15ba52113..5cda61932 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/stardew-tdd-data.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/stardew-tdd-data.md @@ -1,98 +1,66 @@ -# 数据与配表：《星露谷物语》（TDD 金样 · 数据与配表） +# 数据与配表：《星露谷物语》题材写法示例 -> 状态：accepted（结构定稿＋首期全量填充验算通过）　|　基于：各系统文档交接节汇总 ＋ 归 TDD 素材两份提取件（S06 数值结构／架构字段字典）　|　验收：check@C-2026-09-11-v1 结论 无 blocker -> 实证计数来源：星露谷 1.6.15 解包知识库 v3（13 张数据表，提取脚本断言通过；快照 stardew-1.6.15-7f1e5b8e）。写新项目时按本项目系统交接节重建，计数仅作规模参照。 +> 本例只演示首个日常原型的数据侧写法：农场与小镇、基础采集、耕种、商店购买、出售、跨日成长。下列数值是用于演示计算的**项目假设**，不是原作实证或解包数据。本例尚未填满当前范围，未通过策划文档验收，更不代表游戏成品验收。 -## 数据表总清单 +## 数据范围与归属 -| 表格组 | 建议表名 | 主要维护系统 | 实证规模（原作 1.6.15） | +| 数据或配置 | 维护系统 | 原型用途与消费方式 | +|---|---|---| +| 日期、天气、跨日触发 | S01 时间 | S03 读取日期和天气决定成长；S09 接收日终结算时点 | +| 行动体力成本与恢复 | S02 体力 | 农务和采集动作提交成本；数值尚未确定 | +| 地块与作物 | S03 农场 | 引用 S07 的种子与产出物品 ID；播种、浇水、跨日成长和收获由 S03 判定 | +| 农场、小镇、资源点位置及可用状态 | S04 地图 | S05 读取可采集资源点并在成功后请求更新；点位和刷新尚未确定 | +| 采集获得物与经验规则 | S05 采集 | 成功时向 S07 请求物品入账、向 S08 报告经验；产物与判定尚未确定 | +| 种子、作物产物、采集物的身份与持有 | S07 物品 | 由 S03/S05 产出、S09 买卖；背包容量尚未确定 | +| 农务与采集经验、等级 | S08 成长 | 接收活动结果；本例只给出首级阈值的演示值 | +| 起始货币、商品价格、库存、出售与出货 | S09 经济 | 商店和出货箱使用同一价格定义；营业、库存和结算规则尚未确定 | + +表或文件的拆分由施工方决定，上述设计归属不随存储方式改变。`parsnip_seed`、`crop_parsnip`、`parsnip` 在本例中分别标识种子、作物与产物，便于跨文档关联，不要求同名程序字段。S09 维护买价和卖价，不在 S03/S07 复制价格。 + +## 已知内容、关系与数值 + +下表将含义、关系和当前值合写，验算场景输入放在验算段落。游戏日、体力、金钱和经验分别使用自己的单位，不能混用；所需对象不存在或条件不满足时不能把动作算作成功。本例没有已有程序数据契约，字段名、内部类型、配置格式与默认机制由施工方选择；未确定的设计数值仍需补齐，不用 `0` 或空值代替。 + +| 维护系统 | 示例内容或参数 | 已知值与关系 | 仍缺的当前范围设计 | |---|---|---|---| -| 物品与经济 | 物品表、品质表、商店表、商店库存表、价格表 | 物品与制作、经济与商店 | 物品 807×29 类；商店 77 店 897 条库存（含店级 PriceModifiers） | -| 农场内容 | 作物表、动物表、设施表、加工配方表 | 农场经营 | 作物 50 全字段；机器 39 台全 OutputRules | -| 活动内容 | 采集点表、钓鱼点表、鱼类表、敌人表、敌人行为表、遭遇表、战利品表 | 采集/钓鱼/战斗 | 怪物 51 条配置；怪物 AI 矩阵 30 类移动原型 | -| 物品制作 | 通用配方表、配方解锁表 | 物品与制作 | 配方 231（烹饪 81+工艺 150，全原料/产出/解锁） | -| 玩家成长 | 技能表、等级经验表、能力节点表、工具升级表、效果表 | 成长与技能 | 职业 30 全效果钩子（51 钩子+6 数据驱动）；附魔 34 逐项数值；经验曲线代码常量 | -| NPC 与任务 | NPC 表、关系等级表、礼物偏好表、任务表、奖励表、事件条件表 | NPC/任务/事件 | NPC 送礼 34NPC×4 档+全局 5 档；事件 258/条件码 39 | -| 时间与世界 | 日期季节表、天气表、节日表、营业时段表 | 时间与日程、事件与节日 | —（代码常量+日程数据驱动） | -| 文本与展示 | 文本表、UI 提示表 | UI 与文本呈现及各内容系统 | 11 语言按后缀拆分（含 zh-CN） | +| S07 | `parsnip_seed`、`parsnip` | 分别为防风草种子与产物；播种消耗种子，收获获得产物 | 完整物品内容、背包容量、堆叠和展示文案 | +| S03 | `crop_parsnip` | 由防风草种子种出，产出防风草；满足成长条件的跨日累计 `4 游戏日` 后成熟 | 地块初态、种植季节、浇水/天气成长细则、可见生长阶段、品质与收获数量规则 | +| S09 | 防风草种子买价、产物卖价 | 种子 `20 金/包`；普通品质产物 `35 金/个`；开局 `500 金` | 商店 ID、营业时段、库存及补货、售价适用条件、出货箱结算细则 | +| S08 | 农务收获经验与首级阈值 | 成功收获 `crop_parsnip` 获 `8 经验/株`；累计 `100 经验` 达 1 级，均为示例假设 | 采集经验与其他当前可达等级、升级反馈 | +| S04 | 农场、小镇地图尺寸 | 相邻技术样例使用 `16px` 网格、农场 `80×65` 格、小镇 `50×40` 格，均仅作本例地图规模假设 | 区域连接、通路与阻挡、资源分布和可采集条件、刷新规则 | +| S01 | 日期与成长 | 一次满足成长条件的跨日记为 `1 游戏日`；S03 负责累计 | 游戏日长度、天气概率、跨日通知与结算输入 | -（表格拆分是生产组织方式，不改变主数据归属。原作同套模型同时服务本体与模组生态——静态表为结构化 JSON-in-XNB，由 DataLoader 按需缓存。） +以上只覆盖**局部示例内容**，不能凭两个物品、一株作物和地图尺寸推断当前范围已完整。所有可见名称、交互提示、商店文案、收获及结算文案也需在本套 TDD 中逐条确定；本例尚未提供这些正式文案。是否整理成可加载配置由施工方选择，不影响上述内容完整性要求。 -## 字段字典与 ID 命名规范 +## 用已知数值做局部验算 -- ID 命名：小写 snake_case，`对象类型_名称_必要时加阶段`（如 `item_turnip`）；全局唯一、废弃不复用。（原作实证：1.6 起用限定 ID 如 `(O)123` 统一引用 807 物品——原理同源：ID 不含人话、不随语言变。） -- 通用字段：`*_id` / `display_name_text_id` / `description_text_id` / `condition_id` / `enabled_state`（active·draft·disabled·deprecated）/ `sort_order` / `designer_note` / `unit`（数值字段必填：time_slice·game_day·currency·stamina·exp）。 -- 常用后缀：`_amount`（配单位）/ `_cost` / `_rule_id` / `_condition` / `_time` / `_duration` / `_state` / `_text_id`。 -- 类型与空值：数值栏禁"约/无/待定"；空值=不适用≠0≠无限（无限制库存用 `stock_type=unlimited`，不用 999999）；布尔 true/false；多值一律关系子表（多材料配方禁拼一格）。 -- 引用完整性：`item_id`→物品表；`location_id`→区域表；`npc_id`→NPC表；`quest_id`→任务表；`recipe_id`→配方表；`condition_id`→条件表；`text_id`→文本表。删除先置 `deprecated` 并查引用。 -- 枚举实证注意：品质枚举值为 0/1/2/4（银=1、金=2、铱=4）——所有 `(1+0.25×quality)` 型公式乘数因此是 1.25/1.5/2.0；枚举值是语义约定，禁止想当然重排。 +场景假设：开局持有 `500 金`，商店可一次卖出 `15 包`示例种子，玩家有 `15 块`可用地且逐块播种；其后每块都满足四次跨日成长条件，均产出一个普通品质防风草，全部成功入账并按示例价格出售。这些条件是验算输入，不是已经确定的系统配置。 -## 公共条件表 +| 行动与状态 | 计算 | 可确认的结果 | +|---|---|---| +| 买 15 包种子 | `15 × 20 = 300 金`；`500 − 300 = 200 金` | 购种后余 `200 金`，前提是库存、营业与背包允许交易 | +| 播种并成长 | 消费 `15 包`；每株满足 `4` 次跨日成长 | 可推得最早在满足第四次成长条件后收获；浇水、天气和日终精确规则仍未配置 | +| 收获 15 株 | `15 × 1 = 15 个`；`15 × 8 = 120 经验` | 假设均为普通品质、每株一产物且物品入账成功，农务经验达到示例首级阈值 `100` | +| 全部出售 | `15 × 35 = 525 金`；`200 + 525 = 725 金` | 假设交易或日终出货成功，最终金钱 `725`；相对购种投入毛利 `525 − 300 = 225 金` | -| condition_id | condition_type | target_id | operator | required_value | enabled_state | 备注 | -|---|---|---|---|---|---|---| -| `condition_day_2` | `date_day` | `season_spring` | `>=` | 2 | `active` | 春季第 2 日后可触发 | -| `condition_shop_unlocked` | `progress_flag` | `flag_general_store_open` | `==` | 1 | `active` | 杂货店已开放 | -| `condition_skill_farming_1` | `skill_level` | `skill_farming` | `>=` | 1 | `active` | 农务技能达到 1 级 | -| `condition_blacksmith_open` | `schedule_open` | `schedule_blacksmith_default` | `==` | 1 | `active` | 铁匠铺当前处于营业时段 | -| `condition_recipe_repair_path` | `quest_completed` | `quest_repair_path` | `==` | 1 | `active` | 修路任务完成后解锁基础洒水器配方 | +这只验证了给定假设下的数量和金钱/经验算术。没有行动体力、实际耗时、采集产出与成本、商店库存、背包容量、天气概率及跨日结算顺序，无法证明玩家能走完整个流程，也无法判断收益、节奏和平衡。补齐这些数据后，需以真实配置重算农务与采集的同日取舍、跨日成长和出售投资闭环。 -（复杂条件拆条件组+条件行；全项目只此一个条件入口，程序实现一次 `check(condition_id)`。实证参照：原作 258 事件共用 39 个条件码——条件收敛是可达到的规模。） +## 数据检查与结论 -## 工作簿组织与建表顺序 +| 检查对象 | 已做的文档检查 | 结论与缺口 | +|---|---|---| +| 已列对象关系 | 防风草作物对应的种子与产物均出现在本例中；价格只在 S09 定义 | 局部关系及归属一致；商店、地图和采集点的内容关系仍待补齐 | +| 数值与单位 | `15×20=300`、`500−300=200`、`15×35=525`、`200+525=725`、`15×8=120`，单位对应金/经验 | 上述假设下算术成立；行动、产量、品质、库存等约束未验 | +| 当前范围完整性 | 对照 S01/S02/S03/S04/S05/S07/S08/S09 的当前原型职责 | 采集内容、空间布局与资源分布、行动成本、容量、商店与全部可见文案缺失 | +| 关键循环 | 已计算买种到卖出的局部链条 | 农务与采集并行选择、跨日结算及存读档后的结果未能验算 | -| 工作簿 | 工作表 | -|---|---| -| `世界与地图.xlsx` | 日期季节、天气、日程、区域、区域连接、活动入口 | -| `农场与制作.xlsx` | 地块、作物、动物、设施、加工配方、通用配方 | -| `物品与经济.xlsx` | 物品、品质、装备、价格、商店、商店库存、货币 | -| `活动与战斗.xlsx` | 采集点、掉落、钓鱼点、鱼类、敌人、行为、遭遇 | -| `成长与任务.xlsx` | 技能、等级经验、能力节点、工具升级、NPC、关系、任务、目标、奖励 | -| `事件与文本.xlsx` | 节日事件、事件阶段、事件条件、文本、UI 提示、教程 | +本册**未完成**，不构成策划文档验收通过的记录。没有运行游戏、构建或试玩；表中结果仅是可复核的局部文档检查。 -建表顺序：①物品表（公共 item_id）→ ②作物表 → ③区域与连接表 → ④NPC 表 → ⑤配方表 → ⑥价格与商店库存表 → ⑦任务/目标/奖励表 → ⑧敌人/掉落/技能/事件表。 -每完成一组查三件事：引用 ID 存在 / 条件有负责系统 / 同一数值只有一个系统维护。 +## 待解决问题 -## 表格-程序契约 - -1. 加载顺序按引用拓扑：主数据 → 关系 → 条件 → 文本（最后）。 -2. 启动期全量校验（外键/枚举/单位）；运行期全部 id→对象字典 O(1) 查找。（实证参照：原作按需缓存加载+`ContentHashes.json` 逐文件 MD5 校验拒损坏。） -3. 条件求值统一 `check(condition_id)`，全部系统复用。 -4. enabled_state 生命周期：active 加载；draft 调试可见；disabled 不加载；deprecated 不加载但留 ID 占位。 -5. 单位类型化（time_slice/game_day/currency/stamina/exp 进类型系统，同列禁混单位）。实证锚点：`700ms=10 游戏分钟`为运行时常量，配表侧时间单位统一 time_slice，禁现实秒混入。 -6. 多值一律关系子表；运行期无"解析逗号拼接"代码路径。 -7. 改表 → 验收过检（blocker=CI 红灯）→ 进包；`data_version` 为迁移依据（实证参照：原作存档迁移器按版本处理旧字段）。 -8. 随机契约：影响掉落/品质的 roll 绑定「世界日+存档 ID+位置/主体」种子（防读档刷结果；原作行为级种子实证：收获 `CreateRandom(x×7, y×11, DaysPlayed, uniqueID)`）。 - -## 数值填充与验算 - -- 填充代决台账： - -| 表 | 字段 | 默认值 | 依据 | 推翻条件 | -|---|---|---|---|---| -| 等级经验表 | skill_cumulative_xp | 100/380/770/1300/2150/3300/4800/6900/10000/15000 | 代码常量（Farmer.cs 实证） | 原型期曲线过陡/过缓 | -| 作物表 | 防风草 price/days/xp | 35 金/4 日/8 xp | 原作作物表实证（crop 472：phases 1-1-1-1，xp_per_harvest 8） | 前 5 日验算不闭合 | -| 经济表 | 买卖价差 | 商店价=2×基价×品质系数；出售所得=其半 | 原作一对出售方法实证 | 新手期现金流断裂 | -| 战斗表 | 受击无敌帧 | 450ms（按武器类型 2/3 除） | 原作 takeDamage 实证 | 手感测试受击连按 | - -- 前五日闭环验算（防风草路线，起始 500 金实证口径）： - -| 日期 | 主目标 | 关键行动 | 主要成本 | 主要获得 | 结果 | -|---|---|---|---|---|---| -| 第 1 日 | 建立基础生产 | 购防风草种子×15（20 金/包）、开垦播种浇灌、采集少量木材 | 300 金；约 30 体力；约 8 时间片 | 15 块已播种地；少量木材；农务经验 | 进入等待成长阶段 | -| 第 2 日 | 接社区引导 | 浇灌、采集木材、与工匠对话推进修路任务 | 约 25 体力；约 8 时间片 | 任务材料进度；少量经验 | 任务明确指向自然区域 | -| 第 3 日 | 补足任务材料 | 浇灌、采集木材与铜矿、返回小镇 | 约 35 体力；约 12 时间片 | 木材 20、铜矿 5（或进度）；采集/战斗经验 | 可提交修路任务 | -| 第 4 日 | 收获+解锁 | 收 15 防风草（35 金×15=525 金、8 xp×15=120 xp→农务 1 级）、提交任务领奖 | 任务材料；约 10 时间片 | 525 金；基础洒水器配方；林间区域开放 | 现金流回正＋新活动选择 | -| 第 5 日 | 验证扩展循环 | 浇灌、赴林间采集或钓鱼、出售部分产物 | 约 30~45 体力；约 14 时间片 | 新资源、活动经验、可售物品 | 循环从单一农务扩展为农场+探索 | - -- 收益链校验：`item_seed_parsnip(20金) → crop_parsnip(4 日) → item_parsnip(35 金) → 出货箱日终结算 → 种子复购（单包毛利 15 金）`（逐环引 ID，全链存在）。 -- 验算结论：第 1 日不要求做完，播种即进展；第 4 日奖励同时给资金/配方/区域三样；第 5 日出现农场与探索取舍但两条路线都可行。 - -## 验收 - -- 验收记录：check_id / workbook / sheet / data_version / check_type（primary_key·reference·enum·unit·range·business_rule·duplicate_ownership）/ severity（blocker·warning·note）/ result / issue / owner / resolution。 -- 五查必过：主键唯一不空；外键存在且目标非弃用；枚举有清单（品质枚举 0/1/2/4 单独登记）；单位可判且同列不混；无违规负数、`duration=0` 仅即时。 -- 两查复核：业务规则（季节窗口相容、目标有验证系统、奖励一次、配方输入可达——防风草种子→收获→出售链全通）；重复归属（价格只由经济表维护、品质只由收获规则维护）。 -- 三级处置：blocker 禁止扩内容；warning 记负责人与计划；note 不阻断。 -- 工具化实证口径（参照知识库做法）：提取脚本逐表断言（行数/字段/枚举）；对账器做表间交叉对账（代表资产级 50 键全对账）；反例套件 5/5 拒绝。 -- 最近验收结论：check@C-2026-09-11-v1——五查全过、两查复核通过、blocker 清零（结构、规则或字段语义一变，受影响链路全部重验）。 +| 问题 | 对当前施工或验算的影响 | 下一步 | +|---|---|---| +| 基础采集与地图要求 | 资源点如何分布、可采集条件、刷新与产物仍不明确 | 补 S04 空间与状态要求、S05 获得物、品质和经验规则，连同对象关系验算；内部地图格式由施工方决定 | +| 行动成本与日期天气 | 无法验证农务和采集能否在同一天完成，也不能确定四次跨日的实际路径 | 补 S01/S02/S03 的时间、体力、浇水和跨日数据后重算 | +| 背包、商店与出货 | 数量和金额虽可计算，仍无法验证交易与结算是否可执行 | 补 S07 容量及 S09 营业、库存、售价、结算配置和失败处理 | +| 当前范围其余数据与文案 | 几条示例记录不足以施工，玩家反馈也无权威文本 | 按确定的内容范围填满物品、作物、地图、采集、商店、成长及文案，再检查完整性 | diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/stardew-tdd-master.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/stardew-tdd-master.md index fb1065390..b01e99096 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/stardew-tdd-master.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/stardew-tdd-master.md @@ -1,59 +1,48 @@ -# TDD 总册：《星露谷物语》 +# TDD 总册：《星露谷物语》日常原型示例 -> 状态：active（v0.1 里程碑期）　|　基于 GDD：架构层@v3 + 各系统交接节 +## 当前范围 -## 自足性检查（2026-09-06 生产态复评） +首个日常原型包括农场、小镇与基础采集区域，覆盖 S01 时间、S02 体力、S03 耕种、S04 地图、S05 基础采集、S07 物品、S08 基础成长和 S09 商店，以及 UI 和存读档。单日观察计划与取舍，多日覆盖作物成长、出售和再投资。 -| # | 施工方的问题 | 答案在哪 | 状态 | -|---|---|---|---| -| 1 | 七个 P0 系统怎么行为？ | 01 收编章（P0 七系统规则全文已收编@v1；S06 P1 要点已收） | **过** | -| 2 | 表里有多少行内容、文本全填了吗？ | 03 全量填充（作物8/敌人3/NPC12/文本40/物品46/配方14 全填，第八查全绿） | **过** | -| 3 | 每个界面长什么样、怎么走？ | 01 UI 交互规格（HUD/背包/商店/对话/结算五界面全） | **过** | -| 4 | 每份素材什么规格、谁验收过？ | 02 资产状态表 42 行全登记（完成度 12/42，缺口=量产排期非规格缺口） | **过（规格）**／量产进行中 | -| 5 | 代码怎么组织、跑在哪？ | 01 代码组织+能力边界（三态全落位） | **过** | -| 6 | 怎么算做完？ | 01 里程碑三判据+三件验收 | **过** | +矿井战斗、钓鱼、畜牧、制作、NPC 关系与日程、社区目标和节日不在本次施工范围。 -**结论：六问全过——TDD 规格已自足，施工方 可只凭本 TDD 开工。** -剩余非规格缺口（不阻塞开工，按里程碑推进）：①P1 四系统（S05/S10/S11/S12）施工前补文档并收编；②资产表 30 行量产（按十步流程排期）；③B 级两项（背包容量、生命体力共享）在 v0.1 存档实现前收口。 +**本套是未完备的写法示例，尚不能仅凭 TDD 实现整个原型。** 玩法数值与素材规格为示例假设；本例选用新二维 Web，npm + Vite + Phaser 4.2.1 则按总纲约束执行。没有可核验的构建、试玩或资产验收证据。 -## 三件状态 +## 分册索引 -| 件 | 状态 | 版本 | 读者 | 一句话结论 | -|---|---|---|---|---| -| 01 技术实现 | reviewed | v0.2 | 程序 | P0 铁底七件全部落位（native 4/emulated 3），无 gated；v0.1 判据=一个游戏日全流程 | -| 02 美术圣经 | locked（锚点已锁） | v1 | 美术 | 视觉锚七件套从 T1~T7 翻译完毕；资产表 ~40 行全登记，农夫已接入、芜菁已验收 | -| 03 数据与配表 | accepted | ck-001 | 数值+程序 | 七查过、无 blocker、2 warning（公共索引表未建、背包容量未定案）；前五日验算通过 | - -## 跨件契约速查 - -| 缝 | 契约 | 权威在 | +| 项目产物 | 包内样例 | 内容 | |---|---|---| -| 素材绑定 | 作物绑 `crop_{id}`、工具绑 `item_`、敌人绑 `enemy_{id}`、NPC 绑 `npc_{id}`（ID 全部查 03 字段字典指向的表） | 03 字段字典 | -| 视觉翻译链 | `cozy-pixel-countryside` 溯源概念层 T1/T4/T7；四季色板=日单位与季节推动的视觉形态 | 概念层@v3 第 2 节 | -| 加载顺序 | 主数据（物品/敌人）→ 关系（掉落/配方）→ 条件（condition 表）→ 文本（text 表最后） | 03 契约七条① | -| 帧表格式 | `farmer_{anim}_{dir}_{frame}` JSON 帧表：圣经契约列的格式=程序侧帧动画节直接解析的格式 | 01 §能力边界 | -| 交互热区 | 触控热区 ≥44px；圣经 UI 节与 01 输入表同源（热区按钮规格一字不差） | 01 输入表 | -| 音频规格 | BGM ogg 循环+循环点标记 -18LUFS、SFX wav 单发——圣经契约与 01 音频表触发实现一致 | 02 音频契约 | -| 昼夜色调 | `tint_{phase}` 四档程序色值表，豁免绑定、拥有者=美术圣经资产表 | 02 资产状态表 | -| 拥有者总则 | 数值事实归 03（价格只在经济表）；生产状态归 02（素材验收记录）；技术事实归 01（缩放档位） | 架构层@v3 | +| `01_技术实现.md` | `exemplars/stardew-tdd-tech.md` | 行为与协作、Phaser 工程、UI、构建与验证计划 | +| `02_美术圣经.md` | `exemplars/stardew-tdd-art-bible.md` | 首期视觉依据、类别规格、素材清单与接入标准 | +| `03_数据与配表.md` | `exemplars/stardew-tdd-data.md` | 数据定义、示例配置、局部计算与待补验算 | -## 开放问题回执汇总 +## 来源与版本 -| # | 来源件 | 问题 | 去向 | 状态 | -|---|---|---|---|---| -| 1 | **01** | 背包格子还是重量容量（阻断：影响存档与 UI） | 概念层决策卡 | **待用户（B 级置顶）** | -| 2 | 02 | NPC 对话立绘 +12 张（影响 UI 结构与工时） | 决策卡 | 待用户（B 级） | -| 3 | 01 | 矿井逐层生成是否本期 | 台账代决（建议 P2） | 待登记 | -| 4 | 02 | 节日专属装饰 P1/P2 | 台账代决（建议 P2） | 待登记 | -| 5 | 02 | 矿井色板 1 套 vs 3 套 | 台账代决（建议 1 套+亮度递减） | 待登记 | -| 6 | 03 | condition/text/station/behavior 公共索引表 | 03 warning（记负责人） | 进行中 | +采用同包内 `stardew-concept.md`、`stardew-top-design.md`、`stardew-architecture.md` 的 2026-09-27 修订内容，以其“首个日常原型”范围为本例设计基线。技术、数据、美术三分册按这一范围共同维护，具体示例参数由对应分册明确，不把原作解包快照或未附带的外部资料当作施工依据。 -## 验收总状态 +系统文档编号沿用架构。当前未随包提供全部系统的完整正文，也未形成可施工快照；补齐时记录实际采用的来源及版本，同步受影响分册，不能将旧的通用版本占位当作已完成收编。 -| 件 | 最近验收 | blocker | 结论 | -|---|---|---|---| -| 01 | 构建通过+静态检查全绿；双视口验证待 v0.1 联调 | 0 | 结构合格 | -| 02 | ck-a01~a03：农夫接入✓、芜菁两维过（1 warning）、春瓦技术过视觉待锚点 | 0 | 小批已过闸，允许扩产 | -| 03 | ck-001 七查全跑 | 0（2 warning） | 允许内容扩充 | +## 跨分册约定 -当前无任何 blocker：填数（03）、扩产（02）、v0.1 联调（01）三线并行合法。B 级第 1 条（背包容量）在 v0.1 存档实现前必须收口，否则冻结存档模块。 +| 约定 | 当前结论 | 维护位置 | +|---|---|---| +| 工程与产物 | 新二维 Web 使用 npm + Vite + Phaser 4.2.1；`game/dist/index.html` 为预览与导出入口 | 01 当前范围与工程约束 | +| 状态与数据 | 各系统负责对应玩法结果，UI 与存档保持一致；对象含义与关系集中维护，内部字段和结构由施工方选择 | 01 系统行为与协作、03 已知内容、关系与数值 | +| 视觉与对象 | 暂定 16px 网格、16×32 角色、16×16 物品图标；清单明确对象及其状态，帧键与打包方式由施工方选择 | 02 共性表现要求、当前范围对象清单与例外 | +| 数据与资源交付 | 数据与素材随构建进入 dist，具体路径、存储格式与加载接口由施工方决定 | 01 工程与接入约束；02、03 对应要求 | +| 输入与 UI | 桌面键鼠、移动触控；本例按钮热区暂定至少 44 CSS px，容量未定前不能宣称背包布局完整 | 01 界面与操作、02 UI 规格 | + +## 文档检查与重要缺口 + +当前分册对首期范围与工程方向的描述已对齐，但行为、内容、数值与表现要求仍有设计缺口。局部算术推算不能代替完整数值验算，也不代表策划案已通过验收；未预定函数签名、内部结构、资源命名或打包方式不构成缺口。 + +| 相关分册 | 重要缺口 | 详细位置 | +|---|---|---| +| 01、03 | 时间、体力、天气、跨日结算与存档恢复未完整定义 | 01 待解决问题、03 用已知数值做局部验算及待解决问题 | +| 01、02、03 | 基础采集、空间布局、资源分布与可见对象不完整 | 各分册的采集、地图与待解决问题 | +| 01、03 | 背包容量、交易边界、成长曲线及当前范围全量内容不足 | 01 S07/S08/S09、03 已知内容、关系与数值及待解决问题 | +| 01、02 | 对象清单、可见生长阶段、工具动作与声音反馈尚待补齐 | 02 当前未决问题、01 场景与操作 | + +策划案验收要求补齐这些正文、检查跨分册一致性和必要验算，使施工方仅凭本套 TDD 能完成当前范围。素材可以在文档完成后按规格制作，验收判据及必要场景见对应分册，具体测试安排由施工方决定；没有执行的检查不写成已通过。 + +详细问题只在对应分册维护，解决后更新正文并移出本汇总。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/stardew-tdd-tech.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/stardew-tdd-tech.md index 64481d930..80d910873 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/stardew-tdd-tech.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/stardew-tdd-tech.md @@ -1,172 +1,103 @@ -# 技术实现：《星露谷物语》（TDD 金样 · 技术实现） +# 技术实现：《星露谷物语》日常原型示例 -> 状态：reviewed　|　基于 GDD：架构层@v3 + P0 系统文档@v1（收编）　|　数据侧契约：data/contracts@v2 -> **目标运行时：HTML**（由 GDD 平台事实锁定；本项目按浏览器平台事实执行） -> 平台事实：双视口（桌面/移动）· 键鼠/触屏双输入 · 本地 HTTP 预览 -> 实证数字来源：星露谷 1.6.15 反编译知识库 v3（快照 stardew-1.6.15-7f1e5b8e，2026-09-11）；写新项目时替换为本项目数值。 +本例展示从设计到实现规格的写法，范围与来源见总册。文中的玩法数值是示例假设，不是对原作数据或已完成实现的核验；本例选用新二维 Web，具体工程约束遵循总纲。基础采集、跨日结算、容量等规格尚未齐全，当前不能仅凭本例完成整个原型。 -## 系统行为规格（收编章——施工只读这里，不回 GDD） +## 当前范围与工程约束 -### S01 时间与日程（基于系统文档@v1 收编） -- 玩家行动：查看时间天气（HUD 常驻）；使用床提前结束一天；等待营业时段。 -- 状态与规则：时间以时间片计、现实驱动、暂停时停表；时间片耗尽或就寝→日终结算（顺序固定：作物生长 tick→设施产出→出货箱结算→NPC 日程推进→存档→日记界面）→日期+1；28 日/季、四季/年；天气每日按季节权重抽取（晴/雨/风暴），雨天免浇水；结算后向 S03/S07/S10 发跨天 tick。 -- 反馈需求：HUD 时钟日期常驻；天气图标；日终面板逐项列当日变化。 -- 实证参照（原作 1.6.15）：`700ms = 10 游戏分钟`（累加器超 `7000 + 地点Extra×10`ms 触发十分钟拍，`timeOfDay += 10`，上限 2600）；日结算顺序不可乱——出货先于邮件/任务（订单计数依赖）、地点 dayUpdate 先于玩家 dayupdate（作物推进后才有当日收获判定）。 +首个原型包含农场、小镇、基础采集区域，以及时间、体力、耕种、采集、物品、基础成长、商店、UI 和存读档。矿井战斗、钓鱼、畜牧、制作、NPC 关系与日程、社区目标和节日不在本次施工范围。 -### S02 体力与状态（基于系统文档@v1 收编） -- 玩家行动：进食恢复体力；食物附带状态效果；观察体力条决定收手。 -- 状态与规则：单池体力（战斗共享风险资源——B 级待拍，暂按共享实现）；成本分档：移动/普通农务≈0~低、耕作浇水低、砍伐采矿战斗钓鱼中高；恢复：食物立即+效果、就寝次日满、温泉持续；体力归零→昏倒：当日终止、次日上限下降、轻度金钱/物品损失（不清背包）；状态效果有限枚举，由食物/装备写入、各系统结算。 -- 反馈需求：体力条常驻+临界变色；昏倒过场说明原因与损失、给出可恢复路径。 -- 实证参照：原作基础 MaxStamina=270、MaxHealth=100；午夜后体力惩罚为线性公式（Farmer.dayupdate）；昏睡账单上限默认 1000g、姜岛 2500g（LocationContexts 数据驱动，非硬编码）。 +本例选择新建二维 Web 工程：npm + Vite + Phaser 4.2.1，使用 `import Phaser from 'phaser'`，由 Phaser Scene、GameObject 和 update 承载游戏。沿用客户端脚手架的 Vite 依赖约束，安装解析结果由 `package-lock.json` 固定；不另写一套 Canvas 渲染循环。 -### S03 农场经营（基于系统文档@v1 收编） -- 玩家行动：锄地/播种/浇水/收获/铲除；喂动物收集畜产；放置使用设施；整理布局。 -- 状态与规则：地块状态机 荒地→耕地→（播种+浇水）→生长 N 日→可收获→收获后回耕地；未浇水当日不生长；生长按日终 tick；雨天视为已浇水；作物有适宜季节、换季枯萎；动物每日喂食→周期产出、未喂不产出不死亡；洒水器每晨自动浇固定格；加工设备按配方+时间片队列产出；品质分普通/银/金（技能等级+概率）。 -- 反馈需求：生长阶段视觉可辨；成熟提示标记；设施完成音效图标；日终列农场产出。 -- 实证参照：耕地是网格状态拥有者，作物挂在耕地下（HoeDirt 拥有湿度/肥料/作物引用）；收获单一入口；**品质 roll 先于数量 roll 且共用同一随机流**（顺序影响结果）；保水判定在作物推进之后（当天浇的水当天有效）。 +工程位于 `game/`，`npm run build` 在该目录执行，产物入口为 `game/dist/index.html`。预览和导出均使用 dist，运行资源随构建进入其中。目标为桌面键鼠与移动触控、本地 HTTP 预览。 -### S04 探索与地图（基于系统文档@v1 收编） -- 玩家行动：移动（8 向网格）；穿出入口切换区域；查看地图；交互资源点入口（采集/钓鱼/战斗分别交 S05/S06）。 -- 状态与规则：区域=独立场景、连接点切换淡入淡出≤1s；初始开放农场+小镇+海滩，林间/矿井由社区任务解锁（条件表）；资源点固定刷新点按规则周期重生；隐藏信息保留为探索发现；矿井按层进入、固定池随机拼装+亮度递减。 -- 反馈需求：地图标注已解锁区域与当前位置；解锁新区域明确提示与入口指引；资源点可交互高亮。 -- 实证参照：原作矿井同日同层布局确定（每日世界种子 `DaysPlayed + 存档ID/2`）；矿井布局池 61 张模板按层拼装；骷髅洞时间减速 28.6%（+200ms/分）仅单机生效。 +## 系统行为与协作 -### S07 物品、背包与制作（基于系统文档@v1 收编） -- 玩家行动：整理背包；使用/装备/丢弃；设施处提交配方；查看图鉴。 -- 状态与规则：一切以 item_id 为准，类别枚举（工具/种子/素材/食物/装备/家具/礼物）；同类同品质堆叠（容量结构待 B 级决策，暂按格子制实现、预留字段）；工具等级制（基础→铜→铁…，升级交材料+金+天数）；装备槽武器/防具各一；配方=材料子表→输出→设施→condition_id 解锁；制作队列按时间片推进、日终照常完成。 -- 反馈需求：拾取飘字音效同帧；背包变更即时刷新；制作完成提示；图鉴进度。 -- 实证参照：原作 807 物品统一限定 ID 引用（如 `(O)123`）；品质枚举值为 0/1/2/4（银=1、金=2、铱=4），所有 `(1 + 0.25×quality)` 型公式的乘数因此是 1.25/1.5/2.0；出售语义一对方法承载：`salePrice()`（=2×基价×品质系数，商店价）与 `sellToStorePrice()`（=salePrice/2，玩家所得）。 +### S01 时间与日终 -### S08 成长与技能（基于系统文档@v1 收编） -- 玩家行动：查看技能面板；升级时选加成方向；提交工具升级委托。 -- 状态与规则：技能五项（农务/采集/采矿/钓鱼/战斗）独立经验池；执行对应活动得经验、只增不减；等级效果三类——效率（省时省体力）/解锁（配方/区域/工具位）/选择（每若干级一次分支，宽松可回转）；工具升级期间该工具不可用（备用旧工具=开放问题暂不备）；升级奖励优先省时省力扩选择，不加数值伤害。 -- 反馈需求：经验条与升级音效；升级面板三选一；工具完成由铁匠通知。 -- 实证参照：原作技能累计经验曲线为代码常量 `100/380/770/1300/2150/3300/4800/6900/10000/15000`（10 级）；经验取整用银行家舍入（边界值注意）；满级后经验转全局精通点（第二成长曲线）。 +世界运行时推进游戏时钟；背包、商店、日终面板及页面失焦时暂停，不在返回前台时补算离线时间。HUD 展示日期、时间与天气；使用床或到达日终时限后停止接收当日行动，进入日终流程。 -### S09 经济与商店（基于系统文档@v1 收编） -- 玩家行动：出售（出货箱日终/商店现卖）；购买；查看价格库存；接装箱订单（P1）。 -- 状态与规则：货币唯一；基准价+买卖价差，价格只由本系统维护（其他系统只提交产物或消费请求）；商店各有营业时段（条件表）、库存按周期补货、部分商品有购买条件；出货箱投入→日终统一结算计入当日收入；订单 P1 最低配=每周装箱单换奖金。 -- 反馈需求：交易金额飘字音效；日终面板单列收入明细；商店营业状态门口可见。 -- 实证参照：原作 77 店 897 条库存，店级 PriceModifiers 数据驱动；基础材料（木/石/煤/铜/铁/金）售价走年度特例（第 2 年起涨价）而非通用公式。 +S01 协调 S03 作物成长、S09 出货、S08 成长和各系统次日准备，反馈结算结果并保存完成后的状态。具体时间换算、日终时限、天气配置、结算顺序与中断恢复仍待补齐；读档不得再次发放已结算收益。 -### S06 战斗与敌人（P1，基于系统文档@v1 收编要点） -进入危险区域遭遇→敌人状态机（待机/警觉/前摇/攻击/受击/眩晕/死亡）→攻击需满足距离方向冷却装备条件→伤害=来源属性+目标防御+倍率+状态→敌前摇必须可识别→死亡只结算一次经验战利品→战利品按 item_id 提交 S07 入账→撤退保留已结算奖励。全规则见系统文档@v1（P1 施工时全文收编）。 -实证参照：怪物 51 条配置拆 15 字段（HP/伤害/掉落对/防御/闪避/速度/经验…）；受击 `max(1, 伤害−防御)`、450ms 基准无敌帧；伤害链顺序固定：roll→暴击→+攻击→职业→附魔→怪物防御（改序即改平衡）；暴击乘区在 +Attack×3 之前（攻击力不吃暴击）。 +### S02 体力与状态 -## UI 交互规格 +农务和采集提交行动成本，S02 判断是否足够并维护体力，UI 读取结果。休息恢复体力；体力不足时的行为、各行动成本、恢复值及日终处理尚未确定，当前不能用“低消耗”等描述替代数值。体力与战斗生命的关系在战斗原型前确定，不扩大本期规格。 -| 界面 | 元素与布局 | 流转 | 触控版式 | -|---|---|---|---| -| HUD | 体力条（左上）+时钟日期天气（右上）+金钱 | 常驻；点开时钟看季节日历 | 等比缩放，热区≥44px 的仅按钮 | -| 背包/工具栏 | 底部工具槽×8+Tab 全屏网格背包 | Tab/I 开→再关；槽位与物品表工具位同步 | 底栏加宽，点选代替快捷键 | -| 商店 | 商品列表（价格/库存/条件）+背包对照双栏 | 营业时段与店主对话进入→交易→Esc/返回退出 | 双栏改上下布局（移动） | -| 对话 | 底部文本框+头像位+选项列表 | 靠近 NPC 按 E→逐句→选项分支→结束 | 全屏按钮式选项（热区 44px） | -| 日终结算 | 全屏面板：收入明细/关系与技能变化/明日提示 | 就寝或时间耗尽自动→任意键进入次日 | 同桌面，纵向排布 | +### S03 耕种与收获 -（实证参照：原作对话文本中 `$表情` 标记驱动立绘切换，六表情索引 0-5；钓鱼小游戏是唯一不暂停时间的菜单。） +当前流程为锄地、播种、浇水、跨日成长、成熟收获；雨天按已浇水处理，未满足水分条件的当天不增长。S03 维护地块、作物和成长状态，S07 管种子与收获物，S02 管行动成本。播种失败不扣种子或体力；收获入账失败不消耗作物或发放经验。 -## 来自 GDD 的功能（P0 七系统） +数据分册采用示例作物的 4 次跨日成长、普通品质售价 35 金和每株收获 8 xp，具体配置以数据分册为准。阶段与贴图映射、成熟后的地块处理、收获入账的完整边界仍需补齐；本期不加入畜牧、加工或品质随机机制。 -| 系统 | 一句话职责 | 拥有的主数据 | +### S04 地图与 S05 基础采集 + +S04 管位置、碰撞、区域连接和资源点可用状态。S05 在玩家交互时判断资源点与行动条件，计算获得物，交 S07 入账、S08 发经验，成功后由 S04 更新资源点；失败不产生部分消耗或奖励。 + +区域为农场、小镇和基础采集区域，暂按独立场景、连接点切换。采集物、资源点坐标与刷新、获得物数量、成本、入账失败反馈等仍不完整；不能用矿井或钓鱼规则代替基础采集规格。 + +### S07 物品与容器 + +物品通过稳定的 `item_id` 引用，S07 负责持有、使用和容器变更；价格归 S09。背包暂按格子制讨论，但容量、堆叠、工具占位、满包处理和对应存档字段仍未定，须明确后才能实现相关界面和交易。 + +### S08 成长 + +农务或采集成果由活动系统报告，S08 维护经验与等级，其他系统读取成长结果，不重复发放。示例收获 15 株各 8 xp，合计 120 xp，达到数据分册的首级阈值 100 xp；其他当前可达等级、成长收益、采集经验与日终反馈仍需补齐。首期不预填五项技能、三选一分支或工具升级委托。 + +### S09 商店与出售 + +S09 校验营业、价格、库存和金钱，S07 校验物品及容量；买卖全部条件满足才同时更新，失败保持原状态并反馈原因。出货箱在日终结算，须明确投入、取回和重复结算的处理。 + +数据分册的局部示例为初始 500 金，15 包种子各 20 金，购种后余 200 金；15 株按 35 金出售收入 525 金，扣种子投入毛利 225 金。它没有计入采集、体力、营业与容量限制，不能当作原型经济验算已通过。 + +## 工程与接入约束 + +本例尚无需要兼容的内部接口、存档格式或现成资源包。施工方选择源码目录、场景拆分、内部函数、状态字段、配置载体及资源加载方式；系统编号仅用于对照设计。数据和素材须随 Vite 构建进入 dist，预览和导出不依赖工程外的文件。 + +UI 展示的金钱、背包和作物状态须与玩法结果一致。跨系统行动须满足全部前置条件，失败不得留下部分扣除或重复发放；调用和更新机制不在策划阶段预定。 + +存档需在本机保存日期、角色位置、地块、资源点、容器、金钱、成长及已完成的日终结果，重新打开后能恢复进度且不重复结算。存档时机、失败时玩家得到的反馈及可恢复到何时仍需确定；存储介质、序列化、内部版本字段和恢复调用顺序由施工方选择，只要满足已定行为与平台约束。 + +## 界面与操作 + +| 界面 | 元素、流转与反馈 | 适配 | |---|---|---| -| S01 时间与日程 | 全局时钟与日终结算 | 日期、季节、天气、日程 | -| S02 体力与状态 | 全局行动成本与恢复 | 体力、状态效果 | -| S03 农场经营 | 核心产出与规划场 | 地块、作物、设施 | -| S04 探索与地图 | 场景与空间约束 | 区域、连接、资源点 | -| S07 物品与制作 | 资源身份与转化 | 物品、配方、背包 | -| S08 成长与技能 | 长期回报层 | 经验、等级、解锁 | -| S09 经济与商店 | 投资与回报换算 | 价格、交易、库存 | +| HUD | 体力、日期、时间、天气和金钱常驻；随权威状态刷新 | 桌面与移动均不遮挡主要操作区域 | +| 工具栏与背包 | 数字键或点选切工具；Tab/I 或背包按钮打开，再按或返回关闭；打开时暂停 | 槽位数与布局待容量方案确定 | +| 商店 | 交互营业入口打开，显示价格、库存与购买结果；Esc/返回关闭 | 桌面可双栏，移动纵向布局；触控热区暂定至少 44 CSS px | +| 日终 | 展示出货收入与成长变化，确认后进入次日 | 暂停世界操作，不允许重复确认触发重复结算 | -## 技术目标与平台事实 +移动采用 WASD/方向键或虚拟摇杆，交互采用 E/空格或触控按钮。移动速度、交互距离、对象冲突时的选择、摇杆尺寸及死区尚待定义；本期不增加 NPC 对话界面。 -- 首屏可玩 ≤ 5 秒（本地 HTTP，无网络依赖）。 -- 移动视口稳定 60fps（作物满屏实例 ≤ 200 时）。 -- 场景切换 ≤ 1 秒，无白屏。 +## 场景、镜头与素材 -## 技术风险 +示例使用 16px 网格，角色基准尺寸 16×32；对象、视觉状态与表现要求见美术分册。农场暂定 80×65 格，小镇 50×40 格；基础采集区域的规模、空间布局、通路与阻挡、出入口及资源分布要求待补齐。地图层、坐标存储与碰撞实现由施工方决定。 -| 风险 | 影响 | 缓解 | 校验方式 | -|---|---|---|---| -| 非整数缩放导致像素模糊 | 全部视觉资产 | 整数倍缩放+letterbox | 双视口各跑 5 种常见分辨率截图比对 | -| 触屏点击判定过小 | 移动端交互不可用 | 交互热区 ≥ 44px；摇杆替代方向键 | 移动视口手测清单§3 | -| 存档结构变更丢档 | 用户进度 | schema_version 字段+迁移函数；写档先落临时名、成功后替换（旧档三级回退：正常→_old→_TMP） | 每版跑旧档加载测试 | -| 满屏作物逐帧重绘掉帧 | 移动端性能 | 脏矩形渲染；非动画作物静态层 | 性能面板：作物 200 实例压测 | -| 读档刷随机结果（SL 刷品质/掉落） | 经济与平衡崩坏 | 分层种子确定性随机：影响掉落/品质的 roll 一律绑定「世界日+存档 ID+位置/主体」 | 同日同格收获结果可复现测试 | +镜头跟随玩家并限制在地图边界，场景切换目标为 1 秒内且无白屏。像素画面采用整数倍显示，小屏时调整可见世界范围；游戏画面居中，HUD 不遮挡主要操作。实际画布逻辑尺寸、居中与适配实现由施工方按双视口表现要求选择。 -## 运行时能力边界（P0 七件，本例 HTML；引擎运行时对照见括号速记） +音频包含本期环境 BGM 以及农务、采集、交易和日终反馈，听感与用途见美术分册；各行动成功或失败时应有的声音反馈仍需补齐，文件名与内部事件绑定由施工方决定。浏览器音频在首次用户操作后启用，本期不预填四季或矿井音乐。 -| 能力 | 落位 | 状态 | 说明 | -|---|---|---|---| -| 瓦片地图渲染 | Canvas 2D 分层渲染 + JSON 地图数据 | 自封装 | 四层：Back/Buildings/Front/AlwaysFront，深度 -1/0.1/64+/-1（原作 xTile 同构；Unity=Tilemap 原生／Godot=TileMap 节点原生／Cocos=TiledMap 组件） | -| 寻路 | A* 网格 | 自封装 | 仅 NPC 日程移动用（Unity=NavMesh／Godot=NavigationServer 原生） | -| 2D 帧动画 | spritesheet atlas+帧表驱动（Canvas 逐帧绘制） | 自封装 | 帧表含毫秒级帧时长（原作 walk=4 帧循环、每帧 200ms） | -| 分辨率适配 | CSS 整数倍缩放 + Canvas letterbox | 自封装 | 基准 16px 网格，NPC 16×32 放大 4 倍渲染（引擎侧用各自 Canvas/Viewport 适配方案） | -| 音频 | WebAudio 双通道（BGM/SFX） | 原生 | 循环无缝预解码；多场景换曲走六槽上下文仲裁后淡出（防场景竞争）（Unity=Mixer／Godot=AudioServer 总线／Cocos=AudioSource） | -| 移动与碰撞 | 自研网格移动+碰撞检测 | 自封装 | 8 方向；碰撞体小于格子 2px 防卡边（Unity/Godot 物理系统原生） | -| 存档 | localStorage + JSON 文件导出 | 原生 | 版本迁移+临时名保护（引擎侧=文件系统/PlayerPrefs） | +## 风险与待验证目标 -## 代码组织概览 +- 触屏同时操作摇杆、工具与交互可能遮挡场景，需观察小屏下操作是否可达、是否易误触；可读性判据见美术分册“共性表现要求”。 +- 跨日与读档可能重复结算，相关设计缺口见下节“待解决问题”，行为判据见以下验证计划。 -- 承架构目录映射：`src/systems/s01_time/ … s12_events/`（每系统一目录：state/rules/api 三件）；`src/scenes/` 场景注册；`src/core/` 循环、渲染、输入、存档。 -- 入口 `main.ts` → 场景管理器（注册表制，场景切换走统一接口）。 -- 边界约定：系统间只经公开 api 与事件总线通信，禁跨目录直改他人 state。 -- 实证参照（原作，仅作组织参考）：玩法逻辑全在一个 6.27MB 程序集，入口链 原生启动器→主 dll→GameRunner 帧循环（Update/Draw 非固定步长，真实毫秒累加器驱动逻辑）；静态表/本地化文本/地图/运行状态/存档五类数据分置 Content、内存、Saves 目录，按需缓存加载。 +## 构建与验证计划 -## 外部依赖与可复用能力 +以下均是实现后的验证计划，本资源包没有对应的构建或试玩通过证据： -| 需求 | 用什么 | 来源与版本 | 实例化参数 | -|---|---|---|---| -| Web 游戏开发规范 | agc-web-game-development | `skill@当前版` | 双视口/双输入/本地预览/纯 HTML 交付 | -| 地图渲染 | Canvas 2D 自研渲染器 | 手写（JSON 地图数据） | 四层结构（对齐原作 xTile 层语义） | -| 音频 | 原生 WebAudio | 浏览器内置 API | BGM/SFX 双通道 | +- 在 `game/` 执行项目 `npm run build`，检查 `dist/index.html` 及必需数据、素材均进入构建，无加载错误。 +- 新档、农务、采集、交易和存读档在桌面与移动端均可操作；视觉与适配判据引用美术分册，不在此重列。 +- 单日观察时间、体力与行动选择；连续数日覆盖成长、收获、出售和再投资，结果与数据分册验算一致，当前缺少的输入见该册。体验疑虑是农务与采集的成本是否迫使玩家每天重复同一路径，可结合实际选择与玩家反馈判断。 +- 验证满包、资金或体力不足、日终重复确认、页面切后台和存档失败，确认没有部分扣款、重复奖励或错误恢复。 -## 场景与镜头 +具体测试步骤、工具、设备及截图安排由施工方确定。 -| 项 | 规定 | 依据 | -|---|---|---| -| 瓦片地图结构 | 16px 网格；农场 80×65、小镇 50×40、矿井按层生成 | 台账 D-05（区域分场景，非连续地图） | -| 镜头 | 跟随玩家+边界钳制；无缩放（固定整数倍） | GDD 顶层（无镜头玩法） | -| 场景切换 | 农场↔小镇↔矿井走连接点淡入淡出 ≤1s | 概念 D-05 定案"分区域切换" | -| 关卡数据 | `data/maps/*.json`（自定义 JSON：层/网格/对象点） | 契约 v2 | +## 待解决问题 -## 输入与操作 +| 缺口 | 影响与下一步 | +|---|---| +| 时间、天气、体力与跨日顺序 | 影响日常循环和存档；补齐当前采用值、结算与恢复规格，再做跨日验算 | +| 采集、区域与地图要求 | 影响首期必需流程；补齐获得物、空间布局与资源分布、刷新、成本及失败反馈，联动数据与美术清单 | +| 容量、堆叠、商店、成长 | 影响物品、交易、UI 和存档；明确规则及参数后同步各分册 | +| 存档行为、动作反馈与交互 | 补齐存档时机和失败反馈、必要动作与声音表现、交互距离及操作冲突规则；函数签名、存档结构、帧键及适配代码由施工方选择，不列为策划缺口 | -| 动作 | 键盘 | 触控 | 备注 | -|---|---|---|---| -| 移动 | WASD/方向键 | 虚拟摇杆 | 8 方向 | -| 交互（对话/拾取/使用） | E / 空格 | 热区按钮（≥44px） | 场景对象注册热区 | -| 工具切换 | 1~8 / 滚轮 | 底栏工具槽 | 槽位与物品表工具位同步 | -| 背包/菜单 | Tab / I | 右上按钮 | 暂停世界时钟（对话与过场同样停表） | - -## 音频 - -| 用途 | 格式/规格 | 触发点 | 依据 | -|---|---|---|---| -| 四季 BGM | ogg 循环，循环点标记，-18LUFS | 季节变更淡入淡出 2s | 美术圣经音频契约 | -| 矿井环境 | ogg 循环 | 进入矿井场景 | 同上 | -| SFX（收获/砍伐/受击/购买…） | wav 单发，同帧触发 | 事件总线 `sfx_event` | 事件↔音效映射表（资产表） | - -（实证参照：原作音频 XACT 三件套，cue 名 435 候选、代码实际引用 230 个；音效带距离衰减、音乐六槽仲裁后淡出换曲。本项目音频契约见美术圣经。） - -## 构建与验证 - -- 构建：项目标准构建命令（产物可离线运行，本地 HTTP 起服）。（引擎项目按所选引擎的预览与导出流程完成验证与交付。） -- 自动：无头构建通过+静态检查（资源引用存在、表引用完整——CI 跑验收七查）。 -- 半自动：双视口浏览器验证——桌面 1920×1080 与移动 390×844 各完成"新档→第 1 日流程→存读档"，截图比对缩放整數性（引擎项目＝弹窗预览内同流程）。 -- 手测清单：①移动视口摇杆+热区全操作可完成第 1 日；②场景切换三次无白屏；③后台 5 分钟返回，时钟与存档一致。 - -## 版本里程碑 - -| 版本 | 内容 | 判据 | -|---|---|---| -| v0.1 | S01/S02/S03/S07+S04 基础 | 一个游戏日"买种→播种→浇灌→收获→出售"全流程可完成并触发日终结算 | -| v0.2 | 矿井+战斗（S06）+成长（S08） | 矿井进出一次、遭遇一场、掉落入账、经验到 1 级（累计 100xp） | -| v0.3 | NPC+任务+商店（S09/S10/S11） | 修路任务全链可交付并解锁洒水器配方 | - -## 开放问题回执 - -| # | 问题 | 去向 | -|---|---|---| -| 1 | 背包格子还是重量容量（影响存档与 UI 结构） | → 概念层决策卡（B 级阻断，台账 D-15） | -| 2 | 矿井逐层生成是否本期做 | → 台账代决（建议 P2，GDD 已标"不做无限地牢"；台账 D-16） | -| 3 | 体力是否与战斗共享单池 | → 台账 D-14（B 级待拍，暂按共享实现） | +已明确的局部规格可以用于讨论与局部实现；以上当前范围的缺口未解决前，本套 TDD 尚未通过策划案验收。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/stardew-top-design.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/stardew-top-design.md index 83549c0d6..059f14dab 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/stardew-top-design.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/stardew-top-design.md @@ -1,182 +1,112 @@ # 顶层设计：《星露谷物语》 -## 顶层定位与规模锚点 -顶层不是做长线农场生产线，也不是做以探索战斗为主的活动清单，而是让玩家每天都在想： -> "今天做什么？——下雨天不用浇水，正好下矿井；回来的路上把罗宾的生日礼物送了。" +## 玩法目标 -| 项 | 定义 | -|---|---| -| 循环单位 | 一个游戏日（约 10~20 分钟） | -| 段落构成 | 日初规划 → 白天执行（农务/探索/社交）→ 日落结算 | -| 操作复杂度 | 低——单人键鼠交互，无动作门槛 | -| 经营复杂度 | 中——时间、体力、资金三约束下的日程规划；不做生产线布局优化 | -| 长期主轴 | 第一：农场与生活方式成型；第二：社区修复与技能成长；角色数值只做辅助 | +以一个游戏日组织慢节奏的农场生活。玩家根据天气、农场状态、居民日程和自己的目标安排活动，再将当天的成果投入后续生活。时间与体力提供温和的规划压力，农场、探索与社交共同支持不同的生活方式。 -## 设计目标 -让玩家在一个没有唯一正确答案的乡村生活循环中，同时获得三种回报： -- 轻松生活：可以按自己的兴趣安排一天，通过农场、装饰、收集和社交获得稳定的正反馈。 -- 规划掌控：时间、体力、季节和资金构成可理解的取舍，提前准备会让未来更高效。 -- 探索成长：探索区域、战斗和资源发现提供变化与风险，并将成果转化为农场与角色的长期改善。 +主要回报包括自由安排日常的放松感、通过规划改善生活的掌控感，以及探索新资源、区域和人际关系的发现感。农场提供稳定产出，探索带来原料和新内容，社交带来配方、剧情与情感回报；这些关系帮助玩家形成自己的计划。 -三者互相供给：农场提供稳定资源与恢复空间，探索提供稀有资源和发现，社交与社区目标提供方向和情感回报。 +农场与生活方式成型是长期主轴，社区修复与技能成长提供阶段目标。战斗是探索中的伴生风险，不扩展为高难度动作或装备构筑主轴；制作服务于日常投资，不扩展为生产线布局优化。 -## 核心推动力 -玩家每天拥有有限的时间与体力，但可以在一天结束后保留成果，并把收益投入到工具、设施、种子、装备和关系中。短期的"今天做什么"决策，持续转化为长期的"我的生活变得怎样"。 +## 游玩过程与节奏 -主要推动力按层次排列： -1. **即时推动**：完成一次采集、收获、战斗或对话，立即得到物品、金钱、经验、信息或关系进展。 -2. **日程推动**：在日落或体力耗尽前完成今天最重要的目标。 -3. **季节推动**：抓住作物、鱼类、节日和任务的时间窗口，准备下一阶段。 -4. **长期推动**：改善农场、解锁区域和设施、完成社区目标、掌握技能，并建立属于自己的生活方式。 +一个常规游戏日目标约为 10～20 分钟，具体节奏需通过试玩调整。单人键鼠操作以日常行动为主，不以操作精度制造门槛。 -## 大循环 -**规划一天 → 执行活动 → 获得资源与关系进展 → 出售、加工或投资 → 解锁更高效率与新内容 → 进入下一天。** - -在更长周期中：**完成一个季节目标 → 调整生产与探索计划 → 迎接新季节 → 修复社区或解锁区域 → 扩大玩家可选择的生活方式。** - -```mermaid -flowchart LR - A[规划一天] --> B[执行农务/探索/社交] - B --> C[获得资源·金钱·经验·关系] - C --> D[出售/加工/投资] - D --> E[解锁效率与新内容] - E --> F[进入下一天] - F --> A -``` - -## 小循环 - -### 农务循环 -清理土地、播种或饲养 → 每日维护 → 等待成长 → 收获 → 出售或加工 → 将收益投入下一轮生产。 - -### 探索循环 -选择目的地与携带物资 → 在有限体力和时间内采集、钓鱼或战斗 → 判断继续深入还是返程 → 带回资源 → 用于升级、制作或出售。 - -### 社交循环 -寻找 NPC → 观察其日程与需求 → 对话、赠礼或完成委托 → 提升关系 → 解锁新对话、事件、配方或功能。 - -### 成长循环 -重复使用某类能力 → 获得经验并提升技能 → 获得效率、工具或职业选择 → 以更低成本完成同类活动，并接触更高阶内容。 - -## 资源流与输入输出 - -```mermaid -flowchart LR - F[农场生产] -->|作物·畜产品| S[出售与加工] - E[采集·钓鱼·采矿·战斗] -->|原料·鱼类·矿物·战利品| S - S -->|金钱| I[工具·设施·种子·装备] - I -->|效率提升| F - E -->|经验| K[技能成长] - K -->|效率·配方| F - G[社交] -->|关系进展| R[新对话·事件·配方] - R --> G -``` - -- 主要输入：时间与体力；金钱、种子、原材料和消耗品；工具、装备和技能；NPC 关系、任务状态和社区进度；天气、季节、地图位置和活动开放状态。 -- 主要输出：农产品、采集物、鱼类、矿物、战利品和加工品；金钱、技能经验、工具/设施升级；地图区域、配方、任务、事件和 NPC 关系解锁；农场外观、生产能力和社区状态变化。 -- 反馈四层： - - 立即反馈：动画、音效、图标、数字、资源变更和状态变化。 - - 短期反馈：背包、金钱、任务和技能面板更新。 - - 中期反馈：设施完成、工具升级、关系事件和新区域开放。 - - 长期反馈：农场自动化、社区恢复、生活方式成型和终局目标完成。 - -## 最小体验单位 -一个约 10~20 分钟的"游戏日"：查看状态 → 选一个主目标与一两个顺路次目标 → 执行 → 在时间或体力约束下结束 → 结算并获得当日反馈，决定明天是否继续当前计划或转换方向。 - -单个行动必须至少提供一种清晰反馈：资源增加、进度推进、能力提升、关系变化、地图信息或视觉状态变化。 - -## 核心活动流程 - -| 阶段 | 玩家行为 | 设计目的 | +| 环节 | 玩家行为 | 对体验的作用 | |---|---|---| -| 日初 | 查看天气、季节、农场状态、商店或任务提示 | 给当天决策提供完整状态 | -| 目标选择 | 从生产、赚钱、探索、成长、社交和社区目标中确定优先级 | 制造当日取舍（张力兑现处） | -| 准备与出发 | 整理背包，携带工具、消耗品和必要装备 | 投入成本前置，增强方向感 | -| 执行活动 | 完成一组有空间关系或时间关系的行动 | 核心玩法发生地 | -| 中途调整 | 根据体力、时间、掉落和突发事件，决定继续、转向或返程 | 张力的实时兑现 | -| 结算与投资 | 出售或加工资源，购买材料，安排设施和下一轮生产 | 回流与长期化 | -| 日终反馈 | 记录技能、关系、任务、生产和解锁变化，进入下一天 | 闭合并钩住明天 | +| 日初与计划 | 查看天气、季节、农场状态、商店或任务信息，决定今天的优先级 | 让玩家根据当前条件选择目标 | +| 准备与出发 | 整理背包，携带工具、消耗品和必要装备 | 为选定活动投入资源 | +| 活动与调整 | 完成农务、采集、钓鱼、采矿、战斗或社交，根据时间、体力和发现调整计划 | 让选择产生可感知的结果 | +| 结算与投资 | 出售或加工资源，购买材料，安排设施和下一轮生产 | 将当天成果转为后续机会 | +| 日终 | 展示技能、关系、任务、生产与解锁变化，保存并进入下一天 | 保留进展，并为次日计划提供信息 | -## 取舍表 +不同活动的过程与时间跨度有所区别： -| 决策 | 立即收益 | 延迟收益 | 主要代价 | -|---|---|---|---| -| 出售原料还是加工（张力2） | 快速获得资金 | 更高价值或新用途 | 占用设备与等待时间 | -| 留在农场还是外出探索（张力3） | 稳定推进生产 | 稀有资源与发现 | 错过维护或消耗补给 | -| 深入探索还是及时返程（张力3） | 更多资源与经验 | 更高风险和返程压力 | 可能损失当日效率或物资 | -| 购买工具升级还是扩大生产（张力2） | 提高行动效率 | 增加产量与收入 | 当前资金减少 | -| 赚钱还是社交（张力4） | 直接经济进展 | 关系、剧情和配方回报 | 消耗可用于生产的时间 | -| 追求效率还是装饰与兴趣（张力5） | 更快成长 | 个性化与放松体验 | 放弃部分短期收益 | +- 农务：清理土地、播种或饲养，经过维护与成长后收获，再出售、加工或投入下一轮生产。 +- 探索：选择目的地和携带物资，在时间与体力限制下活动，权衡继续深入或返程，再把成果用于升级、制作或出售。 +- 社交：寻找居民，观察日程与需求，通过对话、赠礼或委托发展关系，解锁对话、事件、配方或功能。 +- 成长：使用能力积累经验，获得技能、效率、工具或职业选择，从而接触新的活动内容。 -（张力1"时间与体力有限"由目标选择阶段整体承载。）设计原则：这些选择应产生不同的合理生活方式，而不是把玩家逼向唯一最优路线。 +天气、营业时间和居民日程让日常计划发生变化。季初准备、季中经营和季末收获形成更长节奏；季节更替改变作物、资源、节日和目标。长期则从手工劳动推进到工具升级、自动化设施、新区域和更复杂的人际目标。 -## 节奏结构 -- **日内节奏**：信息确认 → 连续行动 → 资源或发现反馈 → 体力/时间压力 → 日终结算。 -- **周内节奏**：工作日进行生产与探索，商店营业、NPC 日程和周期事件制造计划变化。 -- **季节节奏**：季初准备，季中稳定经营，季末收获与总结；季节变化带来资源、作物、天气和目标变化。 -- **长期节奏**：从手工劳动起步，逐步获得工具升级、自动化设施、新区域和更复杂的关系目标。 +农场与小镇提供熟悉、安定的活动，探索与事件提供变化。节奏应容纳效率型和休闲型玩家，不把每天的任务完成率作为唯一价值。 -整体情绪应在"安定的重复"和"偶尔的发现"之间摆动：农场与城镇提供恢复，探索与事件提供变化。 +## 资源与进展 -## 失败与回收 -失败主要表现为"少拿与顺延"，不毁掉既有积累。 +- 时间与体力限制当天可以完成的行动；天气、季节、位置和活动开放状态影响行动机会。 +- 金钱、种子、原料与消耗品投入生产、制作或探索，转化为农产品、加工品、发现和后续投资能力。背包与设备容量影响携带、加工和安排。 +- 工具、装备、设施与技能改变行动效率和可选活动。经验积累用于成长，不要求玩家把经验作为货币消耗。 +- NPC 关系、任务状态和社区进度记录持续进展，带来对话、事件、配方与区域解锁。 +- 农场外观、生产能力和社区状态展示长期生活变化。 -| 情况 | 结果 | -|---|---| -| 当日计划未完成 | 成果顺延到明天，无惩罚；次日优先级重排 | -| 深夜未归昏倒 | 当日行动终止，次日体力受限，轻度损失 | -| 矿井中倒下 | 损失部分金钱或物品，保留大部分积累 | -| 季节更替未收获 | 该季作物枯萎——日历压力的主要形式 | -| 错过节日或窗口期 | 顺延至下个周期，制造轻度遗憾而非惩罚 | +行动结果通过相应的动画、音效、资源或状态变化表现；背包与面板显示当前结果，设施完成、关系事件和区域开放表现更长周期的进展。重要变化应能被玩家理解，不依赖外部攻略才能形成下一步计划。 -## 系统范围 +## 选择与后果 -| 系统 | 顶层目的 | 边界（本层不做什么） | +时间与体力有限，选择一项活动会挤占其他活动的空间。本例希望不同选择支持不同的生活方式，不把玩家逼向唯一效率路线。 + +| 选择 | 方案 A 的收益与代价 | 方案 B 的收益与代价 | |---|---|---| -| 农场经营 | 承载规划与回报的核心场 | 不做布局优化向的生产线 | -| 时间与体力 | 全局硬约束、日程的标尺 | 不做饥饿等生存需求式衰减 | -| 探索与采集（矿井/钓鱼/采集） | 提供风险与发现 | 不做程序生成的无限地牢 | -| 轻度战斗 | 矿井探索的风险与节奏变化 | 不做装备驱动的成长主轴 | -| 物品与制作 | 资源的转化与长期投资 | 不做复杂配方树管理 | -| 技能成长 | 使用即成长的回报层 | 不做技能树构筑 | -| NPC 关系与任务 | 社区叙事与情感回报 | 不做分支剧情引擎 | -| 经济与商店 | 连接产出与投资 | 不做玩家间交易市场 | -| 季节天气与节日 | 时间压力与变化来源 | 不做动态天气模拟 | -| 日终结算 | 闭合一天并钩住下一天 | — | +| 出售原料或加工 | 出售可立即获得资金，但放弃加工增值或其他用途 | 加工可能提高价值，但占用设备并需要等待 | +| 留在农场或外出探索 | 农场收益较稳定，但会放弃部分探索机会 | 探索带来稀有资源和发现，但消耗补给并占用维护时间 | +| 深入探索或及时返程 | 深入可能增加资源与经验，也提高倒下或来不及返程的风险 | 返程保住已得成果并可安排其他活动，但放弃继续发现的机会 | +| 升级工具或扩大生产 | 升级提升行动效率，但占用可用于扩产的资金 | 扩产提高产出潜力，但增加维护负担并推迟工具改善 | +| 赚钱或社交 | 赚钱加快当前投资，但减少发展关系的时间 | 社交带来关系与后续回报，但放弃部分眼前收入 | +| 追求效率或装饰与兴趣 | 效率安排加快成长，但减少自由探索和个性化活动 | 兴趣活动带来放松和表达，但可能减缓短期经济成长 | -## 范围与非目标 -最小完整版本包含： -- 一个可经营农场 -- 一个小镇与若干功能区域 -- 基础农务、采集、钓鱼、制作、轻度战斗和探索 -- 有日程的 NPC、关系值、任务和社区目标 -- 工具/技能成长、商店经济与基础加工链 -- 季节、天气、节日和日终结算 +失败允许局部损失和机会错过，同时保留大部分长期进展。不同场景的后果需要分别判断，不能把温和压力理解为完全没有损失。 -不做清单： -- 不做无缝大型开放世界 -- 不做复杂实时多人或玩家交易市场 -- 不做以操作精度为核心的高难度战斗 -- 不为每个系统都添加独立小游戏 -- 不在本阶段确定具体数值、完整内容数量或实现方案 - -## 验证标准 - -| 验证点 | 成功标准 | +| 情况 | 后果与恢复 | |---|---| -| 一天循环成立 | 玩家能复述"今天做了什么、为什么、明天想做什么" | -| 取舍真实存在 | 玩家在目标选择阶段出现可观察的犹豫或计划调整 | -| 时间压力温和 | 玩家感到"今天做不完"而不是"今天被逼着做" | -| 回流成立 | 玩家能把当日收益明确投入到下一轮计划 | -| 长期钩子成立 | 玩家能说出自己"在为什么长期目标积累" | +| 普通日常计划未完成 | 可继续的目标移到后续日期，重新安排优先级；限时目标按自身窗口处理 | +| 深夜未归昏倒 | 当日行动终止，次日体力受限并有轻度损失，之后重新安排活动 | +| 矿井中倒下 | 损失部分金钱或物品，保留大部分积累，补充准备后再探索 | +| 季节更替未收获 | 不适应新季节的作物枯萎，需要改种；土地和已有设施仍可继续使用 | +| 错过节日或窗口期 | 失去本次机会，等待后续周期或调整目标 | -## 开放问题 -- 休闲玩家与规划玩家的时间/体力压力如何共存？ -- 战斗在整体游戏中的最低必要深度是什么，如何避免压过生活模拟？ -- 社区目标应采用线性章节、可选收集，还是两者结合？ -- 终局是明确的阶段性结算，还是允许玩家在结算后继续自由生活？ -- 哪些信息必须通过 UI 直接展示，哪些信息可以保留为探索发现？ +损失幅度和恢复成本需结合试玩判断，不应把一次失误放大为长期无法恢复的挫败。 -## 顶层定稿 -顶层当前定稿为：以一个游戏日为循环单位，时间与体力构成温和硬约束，农场、探索、社交三线互相供给的慢节奏生活循环；矿井战斗保持伴生风险定位，失败只造成少拿与顺延。 -后续架构必须围绕"一天"拆系统（时间/农场/探索/社交/经济/成长/结算）；不得把战斗、制作或任何支线做成独立主轴，不得引入生存焦虑型惩罚。 +## 系统范围与版本边界 + +以下是支撑完整版本的能力范围，架构层可按职责拆分或合并。 + +| 能力方向 | 目的与主要联系 | 边界 | +|---|---|---| +| 农场经营 | 承载规划与回报，与物品、制作和经济连接 | 不做生产线布局优化 | +| 时间与体力 | 限制行动并影响日程选择 | 不做饥饿等生存需求式衰减 | +| 探索与采集 | 提供资源、风险与发现，成果回到制作和投资 | 不做无限程序生成地牢 | +| 轻度战斗 | 为矿井探索提供风险与节奏变化 | 不做装备驱动的成长主轴 | +| 物品与制作 | 支持携带、资源转化与长期投资 | 不做复杂配方树管理 | +| 技能成长 | 回应重复实践，改变效率与可选内容 | 不做技能树构筑 | +| NPC 关系与任务 | 承载社区叙事与情感回报 | 不做分支剧情引擎 | +| 经济与商店 | 连接产出、交易与投资 | 不做玩家间交易市场 | +| 季节天气与节日 | 改变行动条件与阶段目标 | 不做动态天气模拟 | +| 日终结算 | 汇总各活动进展，衔接次日与保存 | 不重复定义各活动的奖励规则 | + +本例完整版本包含可经营农场、小镇与功能区域，基础农务、采集、钓鱼、制作、轻度战斗和探索，以及居民日程、关系、任务、社区目标、工具与技能成长、商店加工、季节天气和节日。具体内容数量与详细规格后续展开。 + +范围排除无缝大型开放世界、复杂实时多人、玩家交易市场、高难度战斗，以及为每个系统附加独立小游戏。 + +## 原型验证与开放问题 + +以下是验证计划，尚不代表已经通过试玩。原型按问题分步覆盖，不要求一次实现完整版本。 + +| 需要判断的问题 | 原型范围与游玩跨度 | 判断依据 | +|---|---|---| +| 日常计划能否形成有意义的选择 | 一个游戏日，包含农务、基础外出采集、时间体力与结算 | 观察目标选择与中途调整，结合玩家对选择理由的说明，判断限制是否真正影响行动 | +| 当天成果能否支持后续计划 | 连续数个游戏日，包含作物成长与收获、出售、种子或工具投资、基础成长 | 观察收益是否进入下一轮活动，并询问玩家接下来想改善什么；仅能复述流程不足以证明愿意继续 | +| 时间压力是否符合休闲体验 | 让偏休闲与偏规划的玩家尝试上述日常流程 | 结合未完成计划的频率、返程行为和体验反馈，判断是可接受的取舍还是被任务催促 | +| 轻度战斗是否改善探索节奏 | 基础日常流程后加入一个矿井遭遇 | 观察理解、停顿和损失后的恢复，结合玩家反馈判断战斗是否压过探索与生活体验 | +| 社区与成长能否形成长期目标 | 后续加入代表性的关系事件与社区目标，保留必要的多日推进 | 观察玩家是否愿意投入、如何解释目标价值；单日原型不据此宣称长期体验成立 | + +首个原型聚焦农务、基础地图与采集、时间体力、物品、经济、基础成长和日终结算。钓鱼深度、节日全量、完整社区内容和更多区域不作为首个原型的必需内容。 + +后续仍需展开的问题包括： + +- 时间、体力和损失的具体幅度：核心方向已明确为温和规划压力，通过原型比较具体参数。 +- 战斗的最低必要深度：根据代表性遭遇的试玩结果确定，再补齐系统规格。 +- 社区目标采用章节、可选收集还是结合：在社区内容进入实现范围前明确，以便架构判断相应能力。 +- 终局结算与后续自由生活：不阻塞早期日常原型，在确定完整版本的终局内容前解决。 +- UI 直接展示与探索发现的边界：先保证原型的关键行动与结果可理解，再结合试玩展开详细信息设计。 + +这些问题若改变当前范围或关键玩法，应回到受影响的正文调整，不能只留在问题清单中。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/tdd-art-bible-SKILL.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/tdd-art-bible-SKILL.md index 0aaf5924d..fa12b55a6 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/tdd-art-bible-SKILL.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/tdd-art-bible-SKILL.md @@ -1,93 +1,21 @@ ---- -name: game-tdd-02-art-bible -description: 写"美术圣经"（美术侧）分册时使用。与总纲（技术文档层总纲分册）配套。 - 配套模板：templates/tdd-art-bible.md。配套金样：exemplars/stardew-tdd-art-bible.md。读者：美术 / 素材生产。 ---- +# 美术圣经写法（TDD 美术分册） -# 美术圣经 · 美术侧写法（策划 · TDD 分册之二） +写入 `project/04_tdd/02_美术圣经.md`。参考结构见 `templates/tdd-art-bible.md`，示例见 `exemplars/stardew-tdd-art-bible.md`，按需读取；来源版本在总册集中记录。 -> 本文件承载美术侧的写作流程；模板在 templates/tdd-art-bible.md（保持纯净），金样在 exemplars/stardew-tdd-art-bible.md。 +## 目标与输入 -## 一、这一件的判断立场 +美术圣经把概念设计的体验、基调和当前实现范围，转成可生产和验收的视觉要求。施工方只看本套 TDD，应能找到当前范围的对象、必要状态、表现要求、用途和验收判据；不需要回到 GDD 猜测。已有素材与工程的实际接入约束须记录，文件命名、打包、加载与内部映射可由施工方决定。 -你是技术美术思维的策划。这一件是**GDD 之后、资产生产之前的桥梁**： -把概念层的调性翻译成可执行的视觉语言，把视觉语言压成逐素材的规格契约。 -你相信： +动笔前核对概念与架构的当前范围、玩法对象、界面与状态、目标运行时和现有视觉资料。用名称或必要标识关联对象，已有资源 ID 按契约沿用，不预设 `item_id` 等程序字段。范围外内容简述边界，不展开资产清单或自动安排后续里程碑；已确定且影响当前设计的后续要求按需说明。 -- **风格统一是资产效率的前提**：没有圣经，每张图都在重新发明风格； - 有了圣经，一百张素材共享同一套锚点。 -- **视觉锚从定调翻译，不从审美发明**：参照选择、调性滑杆、T 原则是 - 源头（概念层第 2 节定调记录），你的工作是翻译成关键词、色板、形状语言 - ——不是自己另起一套审美。 -- **每个可见对象必须绑定资产或显式豁免**：GDD 里出现的每个 gameplay 可见 - 对象，要么在资产总清单有一行，要么显式标"程序化生成/UI 文本/本期不需要" - ——没有第三种状态。漏绑定的对象会在开发中期以"缺素材"形式爆炸。 -- **先锚点后量产**：概念候选→人选方向→锚点确认→小批验证→接入→才扩产。 - 绝不做"做完一大批才发现风格不对"的事。 -- **禁用词与正向词同等重要**：每条视觉锚配"禁什么"（不要暗黑、不要描边 - 溢出），生成侧的负面清单比正向描述更防跑偏。 +## 写作要点 -## 二、动笔前 +1. **视觉依据与资源入口**：写明概念来源、风格意图、色彩、轮廓、材质、视角、像素或缩放要求，以及应避免的效果。已有参考图、画风卡或源素材时给可访问的位置与具体借鉴点；尚未形成的资源明确写“待产出”，不把描述或路径当成已验收素材。仅在确有交付约束时预定目录。 +2. **共性要求与明确清单**：列出当前范围的具体对象、必要状态和有限变体；有共性时集中写类别要求，个别尺寸、动作、层级或色彩不同的对象只写例外。清单与系统可见状态对账，文字、程序图形或图像等表达方式按已定视觉意图说明，不强制每个对象制作贴图。需要音频时写明用途、触发时机、循环与听感要求。 +3. **表现与接入**：明确对象在不同状态、方向或事件下应呈现什么，动作的视觉节奏和关键反馈如何配合玩法。已有素材记录实际位置、尺寸、格式、帧表及其他接入约束；新资源的帧键、文件命名、图集拆分、打包与加载方式由施工方按工程确定，不要求策划先设计映射表。确实影响视觉或既有接入的尺寸、时长、格式等约束仍需保留。 +4. **验收判据**：写清风格、辨识度、关键状态、动作反馈和目标视口，以及实际约束下的尺寸、透明、帧序与接入要求。共性要求或对象说明已有判据时直接引用，不另表复述，也不复制技术、数据分册的检查。必要时提供观察场景，具体截图数量、工具及执行流程由施工方安排；实际交付工艺约束保留。 +5. **未决问题**：记录影响当前规格或交付的真实缺口，以及有具体依据的体验疑虑，说明影响与下一步。已采用的色值、尺寸或文案不因尚未试玩而逐项登记待办。关键规格未定时如实标注当前范围尚不能据此施工；样例假设仍须标为假设，未执行视觉验证不能写成通过。 -1. 输入齐了吗：概念层定调记录与身份基调（翻译源头）、系统文档全部可见 - 对象（资产总清单的范围）、物品表（item_id 绑定依据，数据侧已定）、 - 可复用画风规范。 -2. 本件在数据侧表结构定稿后开写（素材清单引用 item_id）。 -3. 读取金样 exemplars/stardew-tdd-art-bible.md 了解契约表与资产状态表包含的信息类型（同层只读一次）。 +## 完成判断 -## 三、怎么写（模板即流程，按节） - -### 1. 视觉风格总览 -一段话 + 参考图位。从定调记录翻译：参照的视觉气质、滑杆值对应的视觉 -密度、T 原则对应的视觉禁忌。**style_id 在此定名**——本项目全部素材 -提示词共用此锚。 - -### 2. 视觉锚（七件套） -关键词（3~5 个）/ 禁用关键词 / 色板（主色辅色点缀+配比）/ 形状语言 / -比例与轮廓 / 光照与材质 / 渲染口径。每件可引画风库现成卡（`卡名@版本`）。 - -### 3. 角色与场景模板 -角色：共用基础规则（头身比、结构、方向数约定——左=右镜像之类的硬规定）、 -动画状态清单（待机/走/跑/受击…各几帧）。场景：tileset 规格、图层拆分、 -昼夜天气季节的表现预算。逐类写死，不留"到时候再说"。 - -### 4. 素材规格契约（逐素材一行，美术按此交付、程序按此消费） -| 素材 | 尺寸/帧数/方向数 | 命名规则 | atlas 格式 | 验收 | 绑定 item_id / 豁免 | -每个 gameplay 可见对象一行；多帧图禁当静态图、单元素区域图禁整图使用 -（运行时绑定规则）。**怎么绘制→封装→交付，逐类写明工艺** -（与三段复用能力的工艺卡衔接）。**资产管线按目标运行时适配**：HTML=源文件 -+atlas/帧表 JSON 直接入包；Unity=Sprite 导入设置与图集；Godot=资源导入 -（.import）；Cocos=Creator 资源与自动图集——规格（尺寸/帧数/命名）四运行时 -一致，封装形式随程序侧契约。 - -### 5. 资产状态表（asset manifest，美术的"配表"） -与数据侧的数值表平行的一张生产事实表：asset_id / 规格 / 绑定 / **状态** / -验收记录 / contract_version。状态单向流转（缺失→草稿→已交付→已验收→已接入）； -验收两维（技术：尺寸透明帧数命名；视觉：对照视觉锚），两维都过才进"已验收"。 -**每个 gameplay 可见对象必有一行或显式豁免，没有第三种状态**——缺什么、 -做到哪、谁验收过，一张表看全；程序接入填消费点，契约版本变更重验收。 -**自足性判定**：资产表"全行非缺失且两维验收过"＝美术侧构建完成—— -施工方 只看本圣经+资产表即可产出全部素材，不回 GDD。 - -### 6. 量产流程与验证 -十步流水：概念候选（3~10 张）→人选方向→编辑出锚点图（3~5 张）→锁圣经 -→写契约→小批生成（3~8 张）→技术检查（尺寸/透明/视角/风格）→接入程序 -→运行时截图验收→**通过后才批量扩产**。验收判据写行为：桌面与移动视口 -下阵营/状态/反馈是否一眼可辨。 - -### 6. 开放问题回执 -视觉与玩法冲突、素材成本超预算（面数/张数/工时）、锚点两难——全部走 -回执：问用户的升级决策卡，代决的记台账。 - -## 四、写完自查（参考，不是闸门） - -- style_id 有了吗？禁用词列了吗？ -- GDD 每个可见对象都在资产总清单里吗（或显式豁免）？ -- 每类素材的验收是否技术可查（尺寸/透明通道/帧数）+ 视觉可查（风格一致）？ -- 量产流程里"扩产"前面有"运行时截图验收"这道闸吗？ - -## 五、红线（承总纲四条，本件特化） - -1. 视觉锚必须能溯源到定调记录，不许无锚发明审美。 -2. 素材契约每行必绑 item_id 或写豁免类型。 -3. 画风卡引用必带版本；工艺沿用既有复用能力的工艺卡，不即兴写流程。 +验收对象是**策划文档**：当前范围、视觉依据、对象与状态、表现要求、实际接入约束及验收判据自洽，且没有关键设计缺口，即可评审文档。未预定帧键、图集格式或交付目录不构成策划缺口。实际资产是否已经生成、接入或通过视觉验收，由后续生产任务记录，不作为本分册完备的前提，也不在样例中虚构完成记录。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/tdd-data-SKILL.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/tdd-data-SKILL.md index 3eefe8b8c..40b2ace90 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/tdd-data-SKILL.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/tdd-data-SKILL.md @@ -1,108 +1,33 @@ ---- -name: game-tdd-03-data-config -description: 写"数据与配表"（数据侧）分册时使用。与总纲（技术文档层总纲分册）配套。 - 配套模板：templates/tdd-data.md。配套金样：exemplars/stardew-tdd-data.md。 - 底料：归 TDD 素材两份提取件（S06 数值结构＋架构字段字典，随包附件）。 - 读者：数值策划 + 程序。 ---- +# 数据与配表 · 数据侧写法（TDD 分册之三） -# 数据与配表 · 数据侧写法（策划 · TDD 分册之三） +写入 `project/04_tdd/03_数据与配表.md`，来源版本在总册集中记录。 -> 本文件承载数据侧的写作流程；模板在 templates/tdd-data.md（保持纯净），金样在 exemplars/stardew-tdd-data.md。 -> 两份提取件是本件的现成实料：引用规则、示例表、验收七查直接改造成文。 +本册写全当前范围的内容、数值、含义、对象关系与文案，不要求产出可直接加载的程序配置。策划文档是本阶段验收对象；文档验收通过后，程序应能只凭本套 TDD 实现当前范围，无须回查 GDD 或请作者补口头规则。游戏成品的运行、手感和平衡另在实现与试玩阶段验证。 -## 一、这一件的判断立场 +## 先确定范围和归属 -你是数值策划与程序之间的契约作者。表格是两者的共同语言。你相信： +- 从当前系统行为和本期流程找出实际需要的对象、数值、内容关系、地图要求及文案；后续系统不提前铺表。 +- 每项事实在明确位置维护，例如作物成长、采集获得物和商品价格分别由对应设计负责。用名称或必要的标识明确对象关系，已有工程 ID 按契约沿用，不要求为所有内容预定程序字段名。 +- 按项目内容选择文字、列表或表格；多条同结构内容可共用属性说明。字段命名、内部类型、数组或对象、表和文件的拆分由施工方决定，已有数据格式或明确的数据交付要求除外。 -- **ID 是资产的身份证**：全局唯一、小写 snake_case、不因语言名称变化、 - 废弃不复用。显示名称永远走 `*_text_id` 引用，ID 单元格不出现人话。 -- **一个事实只有一个写权**：物品身份只在物品表、价格只由经济表、任务奖励 - 只由奖励表——其他表只引用。重复归属是配表第一大乱源，验收单独一查。 -- **数据拆分按"独立可调"**：敌人拆成"是什么/怎么行动/掉什么"三张表—— - 难度和经济才能独立调（S06 实证结构）。 -- **验收是硬闸**：七类检查 + blocker/warning/note 三级；**有 blocker 禁止 - 进入下一轮内容扩充**（竞品四十轮实测的同款铁律）。验收通过不代表平衡， - 只代表结构、引用、单位、边界合格。 -- **单位必须类型化**：time_slice/game_day/currency/stamina/exp 各自为栏， - 同一列混用单位是 blocker 级错误。 +## 写全内容与数值 -## 二、动笔前 +少量参数把名称、当前值、单位或含义及必要约束合写，不再重复列值；同结构多条记录可分为共用属性说明和完整记录。玩家可见文案集中列一次，注明使用位置；其他章节引用已有定义，不重复抄录。共用规则集中说明，特殊用法就近注明；派生值说明计算关系，不作为另一份可调参数登记。 -1. 输入齐了吗：各系统文档「数值与数据交接」节（订单——每系统交来哪些 - 数据类别与定性约束）、架构层主数据归属规则（写权分配）、统一数值基准 - （架构层的定性基准，在本件落成前 N 日验算）。 -2. 先读两份提取件：字段字典全套规则与验收模板已在那里成文，本件是 - 项目实例化，不是重新发明。 -3. 读取金样 exemplars/stardew-tdd-data.md 了解数据清单、验算表与验收结论包含的信息类型（同层只读一次）。 +写明内容是什么、用于哪里、当前取值与单位、数量或顺序等设计约束及对象关系；未确定的关键设计值列入待解决问题，不能把“待定”当成运行值。固定行为在相关规则中直接说明，不要求配置化，也不禁止实现使用常量或配置；是否集中调参、采用何种载体由施工方决定，已有约束除外。不因未来可能变更就承诺尚未定义的模式、开关取值或变体。 -## 三、怎么写（模板即流程，按节） +把当前范围所需的**全部**内容、参数值和玩家可见文案放入本套 TDD，或明确指向本套 TDD 内唯一的权威定义。示例行不能代替完整内容；不能用“照此补齐”掩盖作物、商品、资源点或提示文案的设计缺口。写清跨系统行动在对象不可用或入账失败时的预期结果，内部查找与错误处理机制由实现确定。改变内容时同步更新受影响的规则和验算。 -### 1. 数据表总清单 -表格组 → 建议表名 → 主要维护系统。从各系统交接节汇总；声明"表格拆分 -是生产组织方式，不改变主数据归属"。 +已有数据文件、外部接口或明确要求交付可加载数据时，记录实际字段、格式、允许值、默认或必填约定及引用规则。存在旧数据时说明实际兼容要求，不为新项目预设迁移结构。随机机制写清概率、条件与结果，不预设算法、通用条件表或随机种子。 -### 2. 字段字典与 ID 命名规范 -ID 命名（`对象类型_名称_阶段`）/ 通用字段八件（`*_id`、`display_name_text_id`、 -`condition_id`、`enabled_state`、`sort_order`、`designer_note`、`unit`）/ -常用后缀（`_amount`、`_cost`、`_rule_id`、`_condition`、`_time`、`_duration`、 -`_state`、`_text_id`）/ 类型与空值铁律（数值栏禁写"约/无/待定"；空值≠0≠ -无限；多值一律关系子表）/ 引用完整性（`item_id`→物品表等全套指向；删除 -先 `deprecated` 查引用）。 +## 用当前采用值验算 -### 3. 公共条件表 -任务、配方、商店、区域、事件、UI 教程共用同一条件入口：condition_id / -condition_type（date_day、progress_flag、skill_level、schedule_open、 -quest_completed…）/ target_id / operator / required_value。复杂条件拆 -条件组+条件行，单元格禁自由文本。**程序只实现一遍求值器，全部系统复用 -`check(condition_id)`**——这是条件表存在的全部意义。 +选择覆盖本期关键循环的场景和跨度，列出起点、行动、成本、获得、跨日变化与终点，展示计算过程和实际结果。至少核对所需对象与内容可获得、单位一致、资源不凭空产生或重复扣减、收益与消耗能支持目标行为。验算发现缺输入时写清已算出的部分和不能下结论的部分，补齐后重算；不要用预设的前五日表或只给公式不代入数值。 -### 4. 工作簿组织与建表顺序 -工作簿拆分（世界与地图/农场与制作/物品与经济/活动与战斗/成长与任务/ -事件与文本）+ ID 全局唯一声明。**建表顺序八步从物品表起步**（公共 -item_id 先立），每完成一组表查三件事：引用 ID 存在、条件有负责系统、 -同一数值只有一个系统维护。 +数值验算保留必要计算，不把技术分册的输入、暂停、存读档等行为检查再演成一套状态表；行为涉及的数值关系按需验算。其他分册引用本册结果，不重复计算表；已有采用值不因未来可能调优而逐项列为待解决问题。 -### 5. 表格-程序契约（七条，程序照此消费） -①加载顺序按引用拓扑（主数据→关系→条件→文本，文本最后）；②启动期 -全量校验（外键/枚举/单位一次性查，运行期 O(1) 字典查找）；③条件求值 -引擎统一 `check(condition_id)`；④enabled_state 生命周期（active 加载/ -draft 调试可见/两 disabled 不加载、deprecated 留 ID 占位防复用）；⑤单位 -类型化进类型系统；⑥多值一律关系子表，运行期不存在解析逗号拼接的代码 -路径；⑦改表→验收过检（blocker=CI 红灯）→进包，data_version 做迁移依据。 -随机类数值另加一条：影响掉落/品质的 roll 绑定「世界日+存档 ID+位置/主体」 -种子，防读档刷结果。 +## 验收本册 -### 6. 数值填充与验算 -结构定稿后才填数。每项代决记台账（默认值+依据+推翻条件）。**前五日 -闭环验算必做**：按架构统一数值基准排五日表（主目标/关键行动/成本/获得/ -结果），加收益链校验（`区域→敌人→材料→配方→产出`逐环引 ID）——验算 -结论写回：第 1 日不要求做完、奖励多元不单一、第 5 日出现取舍但仍留两条 -可行路线。 +检查当前范围的内容和文案是否齐全，取值、单位、对象关系及归属是否明确，数值是否符合规则，关键场景的验算是否可复核；存在实际数据契约时核对兼容性。记录检查对象、实际结果和未解决项；关键设计或实际接入缺口存在时写“未完成”，不将程序字段、存储格式尚未设计当作缺口。修改内容、数值或规则后复核受影响项。 -### 6.5 全量填充与内容完成度（自足性的数据侧保障） -结构定稿后的填充不是示例——是**全量**：数值表每表填满计划行数、文本表 -（对话/提示/图鉴文案）逐行填满。这是"纯看 TDD 做完游戏"的数据前提： -程序加载表即得完整内容，不再回 GDD 找"这里应该有 8 种作物"。验收在七查 -之外加第八查——**内容完成度**：每表计划行数 vs 实填行数，缺口列清单回填； -填数每项代决记台账。文本表由文本系统文档的文案收编（带版本锁）。 - -### 7. 验收（七查+三级） -主键/引用/枚举/单位/范围五查必须过；业务规则/重复归属两查需设计师复核。 -三级处置：blocker 禁止扩内容修完重验；warning 可继续但记负责人与计划； -note 不阻断。验收记录表留 check_id 与 data_version。**结构、规则或字段 -语义一变，受影响链路全部重验。** - -## 四、写完自查（参考，不是闸门） - -- 每张表答得出"谁是拥有者系统"吗？ -- 任意单元格有没有"约/待定/多值拼一格"？ -- 条件表是否全项目一个入口？程序求值器只需实现一次吗？ -- 前五日验算跑过吗？收益链每一环的 ID 都存在吗？ -- 最近一次验收：blocker 清零了吗？ - -## 五、红线（承总纲四条，本件特化） - -1. 表里不写散文；规则进契约文档。 -2. 数值填充的每个代决都进台账，无痕改数=违规。 -3. 有 blocker 不许扩内容——没有例外。 +模板 `templates/tdd-data.md` 提供可删减的组织方式；`exemplars/stardew-tdd-data.md` 展示尚有缺口时如何诚实记录。样例不是必须读取的前置材料，也不提供原作解包证据。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/tdd-tech-SKILL.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/tdd-tech-SKILL.md index 9602213ca..1dfe8f43f 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/tdd-tech-SKILL.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/exemplars/tdd-tech-SKILL.md @@ -1,93 +1,22 @@ ---- -name: game-tdd-01-tech -description: 写"技术实现"（程序侧）分册时使用。与总纲（技术文档层总纲分册）配套。 - 配套模板：templates/tdd-tech.md。配套金样：exemplars/stardew-tdd-tech.md。读者：工程师。 ---- +# 技术实现写作规则 -# 技术实现 · 程序侧写法（策划 · TDD 分册之一） +本册写入 `project/04_tdd/01_技术实现.md`，让程序仅凭本套 TDD 实现当前范围。参考结构见 `templates/tdd-tech.md`，示例见 `exemplars/stardew-tdd-tech.md`，按需读取。 -> 本文件承载程序侧的写作流程；模板在 templates/tdd-tech.md（保持纯净），金样在 exemplars/stardew-tdd-tech.md。 +## 平台与输入 -## 一、这一件的判断立场 +按 TDD 总纲限定的技术选型范围，记录已定平台、框架约束、实际工程入口和交付产物；未受约束的选型由施工方按需求决定，构建与验证按实际工程说明。 -你是实现者视角的架构作者。这一件回答三个问题：**代码怎么组织、 -跑在哪、怎么证明能跑**。你相信： +从架构和系统文档取得当前范围、职责、行为、数据归属及已定参数，与数据、美术分册对齐设计要求和实际接入约束。需要用户决定的产品取舍先确认；代码组织、算法、内部接口、配置与存储结构由施工方自主选择。可提供有依据的实现建议，但不将其作为唯一方案。来源版本由总册集中记录，变更时同步受影响正文。 -- **自包含**：TDD 开头"来自 GDD 的功能"节必带——读者不回翻 GDD 就能开工。 -- **平台事实置顶且禁改**：自包含 Web、双视口、键鼠+触控、本地 HTTP 预览。 - 一切技术选择先过这道闸；GDD 里出现平台做不到的需求，回执上报，不硬做。 -- **能力边界说三态**：native（原生支持）/ emulated（需模拟封装）/ gated - （本期不做，写明替代方案）——程序侧不许答应 GDD 做不到的事。 -- **性能预算是基准不是完美**：每项指标写上限、写测量方式，当取舍依据用， - 不追求极致。 -- **验证不靠人肉感觉**：每条验证写"跑什么、看什么输出、过了什么算过"—— - 接双视口浏览器验证与 browser-playtest 现有资产。 +## 写清实现所需信息 -## 二、动笔前 +- **系统行为与协作**：玩家或外部输入、前置条件、状态变化、结果反馈，成功、失败与中断后的结果。收编全部当前必需行为，可以按流程或模块重组，不能只列功能名或让施工方回翻 GDD。 +- **工程与接入约束**：实际工程入口、需遵循的现有接口、数据格式及资源约定；写清信息来源、对象关系及结果归属，有存档时明确保存内容、时机、恢复结果与失败反馈。不要求为新项目预先设计源码目录、函数签名、序列化结构或配置读取机制。 +- **界面与操作**：界面元素、布局、进入退出、操作反馈，以及适用的输入设备、焦点、暂停和适配规则；参数与美术分册一致，不强制每个项目使用同一热区或版式。 +- **场景、镜头与音频**：按项目需要写尺寸、坐标、碰撞、镜头、动画、声音触发和参数；不要求项目具备固定的能力清单。 +- **依赖与能力限制**：优先复用已知可用能力，写清来源、版本和必要配置。对会影响实现的限制、风险及尚待核实能力如实说明，不能因暂时没有验证方法而删去风险。 +- **构建与验证**：记录实际构建与交付约束，写清行为通过判据，必要时用代表性场景说明；数据验算与视觉判据引用对应分册，不重复展开。确有性能目标时写明依据及适用条件，不为填章节添加指标。测试脚本、顺序和测量工具由施工方安排；玩法与视觉不必全部改成自动指标。 -1. 输入齐了吗：架构层系统范围表+P0 清单（拆模块依据）、数据侧表结构契约 - （加载与校验要引用）、可复用能力选型（实现类需求先查现成能力，不自造轮子）。 -2. 读总纲判断立场；本件在数据侧表结构定稿后开写。 -3. 读取金样 exemplars/stardew-tdd-tech.md 了解技术实现文档包含的信息类型（同层只读一次）。 +## 完成检查 -## 三、怎么写（模板即流程，按节） - -### 0. 系统行为规格（收编章——本件的灵魂） -每个 P0 系统一节，**收编**该系统文档的「玩家行动／状态与规则／反馈需求」 -三节全文（标注"基于系统文档@v{N}"）。施工方 只读这里就该知道这个系统 -怎么行为——不需要回 GDD。P1 系统收编一句话职责+开放状态，施工到该系统时 -补收编。收编节只同步不改写：GDD 变了重同步，TDD 不在这里加观点。 - -### 0b. UI 交互规格（收编+落地章） -界面清单（每个界面一行：HUD/背包/商店/对话/结算面板…）+ 每界面的元素、 -布局要点与流转（从哪进、怎么出、焦点默认在哪）。触控版式与 44px 热区 -规则在此落位（与圣经 UI 节同源）。 - -### 1. 来自 GDD 的功能 -摘录系统范围表与 P0 清单，一行一系统。只摘，不评——评价回 GDD。 - -### 2. 技术目标与平台事实 -平台事实原样置顶（禁改）；技术目标写可测量的两三条（如"首屏可玩≤N 秒"）。 - -### 3. 技术风险表 -每行：风险 / 影响 / 缓解 / **校验方式**。写不出校验方式的风险是空焦虑，删。 - -### 4. 运行时能力边界 -P0 七件逐项过（瓦片地图渲染、寻路、帧动画、分辨率适配、音频、移动与碰撞、 -存档），**按所选运行时判定**，每项标三态：**原生**（运行时自带该能力： -Unity Tilemap/NavMesh、Godot TileMap 节点/AudioServer、Cocos 组件、 -HTML 的 Canvas/WebAudio/localStorage）、**自封装**（基础 API 上自己写逻辑）、 -**受限**（该运行时不适合，写明替代方案或降级）。不许答应 GDD 做所选运行时 -做不到的事。运行时四选一（HTML/Unity/Godot/Cocos），TDD 不擅自换； -引擎项目按所选引擎的预览与导出流程验证。 - -### 5. 代码组织概览 -承架构层目录映射：入口、场景、系统模块的文件组织，一图或一段写死。 -命名与模块边界约定写清（面向生成代码的可读性：谁在哪个目录、什么前缀）。 - -### 6. 外部依赖与可复用能力 -实现类需求先查可复用能力；记录来源、适用版本与实例化参数；没有现成能力时写明来源与理由。 - -### 7. 场景与镜头 / 输入与操作 / 音频 -三节各一张表：场景（tilemap 结构/镜头行为，代决记台账）；输入（动作× -键盘×触控对照）；音频（用途×格式规格×触发点×依据）。 - -### 8. 构建与验证 -构建流程 + 验证分级：自动（什么命令、什么输出为过）、半自动（双视口 -浏览器验证走哪步）、手测清单（谁试玩、看什么）。 - -### 9. 版本里程碑 -版本 / 内容 / 判据三列。判据必须可程序化或可观察，不写"基本完成"。 - -## 四、写完自查（参考，不是闸门） - -- 每条风险都有"缓解+校验方式"吗？ -- 能力边界表覆盖 P0 铁底七件了吗？gated 项都有替代方案吗？ -- 验证流程里有没有一步是"人肉感觉"？有就改写成行为判据。 -- 程序拿到这份文档，能否不问任何人开工？ - -## 五、红线（承总纲四条，本件特化） - -1. 平台事实禁改；与 GDD 冲突走回执，不就地硬做。 -2. 可复用能力引用必带版本与参数。 -3. 里程碑判据不许写"基本""大致""感觉"。 +当前范围的行为、内容关系、交互与实际工程约束能指导实现，跨分册约定一致。文档和必要验算应完成，验收条件足以判断结果；有已执行验证才记录结果。影响玩法、体验或实际接入的缺口应解决；内部实现细节不列为策划阻塞项，已有采用值也不因未来可能调优而列入待办。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/01_核心玩法编排/SKILL.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/01_核心玩法编排/SKILL.md index 0194f6120..d5b7940d2 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/01_核心玩法编排/SKILL.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/01_核心玩法编排/SKILL.md @@ -1,31 +1,11 @@ -### C2 01_核心玩法编排/SKILL.md（→ modules/system-types/01_核心玩法编排/SKILL.md） +# 核心玩法编排 ---- -name: gdd-sys-01-orchestration -description: 写"核心玩法/日循环编排"类系统文档时使用。与 skills/systems.md - 配套（通用纪律不在此重复）。配套模板：modules/system-types/01_核心玩法编排/模板.md。 ---- +当玩法需要跨系统组织玩家目标、行动与阶段推进时，参考本类型；单一系统已能完整表达的玩法无需另设编排层。 -# 核心玩法编排 · 系统写法 +- 说明玩家如何获得目标信息、选择行动、根据结果调整计划，以及何时进入下一阶段。阶段可以是回合、关卡、一天或项目实际采用的其他单位。 +- 写清编排自身实际拥有的状态、状态变化与恢复方式。它可以拥有目标、进度、阶段等正式状态；其他系统的数据按实际权威来源读取或接收结果。 +- 描述跨系统动作的触发、顺序、失败处理和结果去向，让实现者能区分编排规则与各系统内部规则。 +- 玩家是否有有意义的选择、是否需要取舍，应由本项目的核心体验决定；取舍、反馈和依赖只写实际存在的机制。 +- 已确定的参数与字段可以保留。技术设计需收编这些约束并补齐可实现的规格，职责和数据归属以项目架构为准。 -**定位**：把各系统粘成"一天/一局"的编排层，自己几乎不拥有内容。 - -## 本类型要点 -- 系统目的：写"若删除它，日循环崩解为无关小游戏"。 -- 支撑体验三件：安排空间明确但无唯一解；资源有限使选择有意义； - 可依新信息调整计划。 -- 进入与退出三入口必写：新档日初、读档恢复、特殊事件后返回常规循环。 -- 玩家行动：写"安排"类动词（定当日目标/选携带/执行/调整）， - **不写具体生产动作**——那是各内容系统文档的事。 -- 状态与规则：只写"编排态"（日期/位置/体力/当日已完成）， - **不写任何内容公式**。 -- 数值与数据交接：数据类别表加第四列「提供方/消费方」——本类型只做 - 路由，数据字段全部来自别家，此表证明它不拥有内容。 -- 边界三不：不定义作物/敌人/钓鱼/好感公式；不拥有内容表； - 不管渲染动画——三条写全。 -- 典型开放问题：中途存档？结束一天的位置？昏倒影响范围？ - -## 本类型自查 -- 全文有没有出现任何一条内容公式？（出现即越权） -- 提供方/消费方列填全了吗——有没有数据其实没有来源系统？ -- 删掉本系统，玩家真的会"不知道今天干嘛"吗？不是的话它是伪编排层。 +检查：跨系统流程中的推进、结算与恢复是否有明确负责方，是否重复维护了其他系统的状态？ diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/01_核心玩法编排/模板.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/01_核心玩法编排/模板.md index 614b9acca..efb2769ea 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/01_核心玩法编排/模板.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/01_核心玩法编排/模板.md @@ -1,73 +1,12 @@ -### C2 01_核心玩法编排/模板.md（→ modules/system-types/01_核心玩法编排/模板.md） - # __系统：S__（核心玩法编排类） -## 系统目的 -（本系统存在是为了 __；若删除它，日循环崩解为 __。） +按实际玩法选取内容，不为填满模板增设阶段、状态或依赖。 -## 支撑的玩家体验 -- 安排空间明确但无唯一解：__。 -- 资源有限使选择有意义：__。 -- 可依新信息调整计划：__。 -（对应顶层设计目标第 __ 条。） +## 玩家目标与编排流程 +（玩家从哪里得到目标，如何选择、执行、调整，以及什么条件推进到下一阶段？在流程中说明参与方、输入输出和玩家可见的结果。） -## 进入与退出 -### 进入 -- 新档日初：__。 -- 读档恢复：__。 -- 特殊事件后返回常规循环：__。 -### 退出 -- __ +## 状态与关键规则 +（补充流程尚未说清的状态、权威数据来源、结算与恢复约束，以及跨系统动作的先后与失败处理。保留已确定的参数，不复述流程。） -## 玩家行动 -- 定当日目标：__。 -- 选择携带：__。 -- 执行：__。 -- 调整：__。 - -## 取舍表 - -| 决策 | 立即收益 | 延迟收益 | 主要代价 | -|---|---|---|---| -| __ | __ | __ | __ | - -## 状态与规则 -### 编排态 -- 日期与时段：__。 -- 玩家位置：__。 -- 体力余量：__。 -- 当日已完成/未完成：__。 - -## 数值与数据交接（→技术文档层） - -| 数据类别 | 作用 | 提供方 | 消费方 | -|---|---|---|---| -| __ | __ | __系统 | __系统 | - -随交接附下的设计侧定性约束： -- __ - -## 反馈 -- __ - -## 内部循环 -`日初信息确认 → 目标选择 → 执行与调整 → 日终结算 → 下一天` - -## 输入、输出与依赖 -### 输入 -- __系统提供 __。 -### 输出 -- 向__系统提供 __。 -### 依赖 -- __ - -## 边界与非目标 -- 不定义 __/__/__ 的内容公式 → 移交 __。 -- 不拥有内容表。 -- 不管渲染动画 → 移交呈现层。 -- 不负责字段定义、数值配置与表格结构——归技术文档层（数值策划）。 - -## 开放问题 -- 中途存档的粒度？ -- 结束一天时玩家位于何处？ -- 昏倒的影响范围？ +## 待定设计 +（只记录影响实现或体验的未决问题及需要验证的取舍。） diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/02_时间与日程/SKILL.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/02_时间与日程/SKILL.md index 8fcbc2d6f..57334dfb3 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/02_时间与日程/SKILL.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/02_时间与日程/SKILL.md @@ -1,25 +1,10 @@ -### C2 02_时间与日程/SKILL.md（→ modules/system-types/02_时间与日程/SKILL.md） +# 时间与日程 ---- -name: gdd-sys-02-time-schedule -description: 写"时间与日程"类系统文档时使用。与 skills/systems.md 配套。 - 配套模板：modules/system-types/02_时间与日程/模板.md。 ---- +玩法存在时间推进、暂停、恢复或时间窗口时，参考本类型。时间单位和节奏由玩法决定，不预设昼夜、季节或日终。 -# 时间与日程 · 系统写法 +- 说明时间如何表示和推进，哪些动作、事件或运行状态使它暂停、跳转或恢复；已有时长与换算参数可以保留。 +- 说明时间窗口如何判定、开放与关闭，以及玩家从哪里得知当前状态和不可用原因。窗口可以由本系统或相应活动系统维护，按实际架构明确协作关系。 +- 涉及存档、跨阶段或离线推进时，写清恢复后的时间及待处理事件如何确定。 +- 活动耗时、居民日程、营业规则等按实际职责归属，不在本类型中预设统一拥有者。技术设计需收编已定规则与参数，补齐实现规格。 -**定位**：世界时钟 + 开放窗口的唯一真源。 - -## 本类型要点 -- 状态与规则：配置基准定性写清（时间片/日结构/季长/年结构各自的 - 设计意图）；具体数值进 TDD 的配置基准表，本层只定结构与意图。 -- 反馈三件套：HUD 持续显示 + 阈值预告（商店将关/日终将至）+ - **不可用必给具体原因**（"尚未开放/已关闭/今天不营业"，不许只灰按钮）。 -- 与架构层"统一数值基准"逐条对齐：1 日=多少时间片、一天应完成几件事的 - 量级感在本层说清，数值给 TDD。 -- 边界：不负责活动本身的时间成本（只接收并推进已验证请求）； - 不模拟真实天文（潮汐/星象之类不做）。 - -## 本类型自查 -- 每个开放窗口（营业/季节/节日）都有"何时开、何时关、关了怎么说"三答吗？ -- 有没有任何活动的时间成本被写进了本系统？（该在活动系统里） +检查：同一时间点的可用性和推进结果是否可判定，暂停与恢复是否会重复或漏掉关键事件？ diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/02_时间与日程/模板.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/02_时间与日程/模板.md index 5225e8ff4..4f1a6da15 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/02_时间与日程/模板.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/02_时间与日程/模板.md @@ -1,69 +1,12 @@ -### C2 02_时间与日程/模板.md（→ modules/system-types/02_时间与日程/模板.md） - # __系统：S__（时间与日程类） -## 系统目的 -（本系统存在是为了 __；若删除它，__。） +按实际时间机制选取内容，不预设日、季节或特定开放窗口。 -## 支撑的玩家体验 -（对应顶层设计目标第 __ 条。） -- __ +## 时间结构与推进 +（时间单位、状态归属、推进来源、速度或消耗；暂停、跳转、存档恢复与跨阶段的条件。就近说明其他系统提供的条件与读取的结果，保留已确定的参数。） -## 进入与退出 -### 进入 -- 游戏启动/读档时恢复时间状态：__。 -### 退出 -- __（时间系统通常常驻；写清唯一停摆场景，如暂停菜单） +## 时间窗口与事件 +（适用窗口的开放和关闭判定、冲突处理、错过后的结果，以及玩家得到的提示。） -## 玩家行动 -- 查看时间/日期/季节：__。 -- 查看日程与开放窗口：__。 - -## 取舍表 - -| 决策 | 立即收益 | 延迟收益 | 主要代价 | -|---|---|---|---| -| __ | __ | __ | __ | - -## 状态与规则 -### 配置基准（定性，数值归技术文档层） -- 时间片结构：__（设计意图：__）。 -- 日结构：__。 -- 季长与年结构：__。 -### 开放窗口规则 -- 营业时段：__（开/关/关闭原因表达）。 -- 季节窗口：__。 -### 推进规则 -- 时间随已验证的行动请求推进：__。 -- 日终触发条件：__。 - -## 数值与数据交接（→技术文档层） -本系统交由技术文档层定义的数据类别：日期季节表、天气表、日程表、营业时段表。 - -随交接附下的设计侧定性约束： -- 一天应完成的量级：__（如一个主目标+一个外出目标+少量顺路）。 -- 早期玩家不应因时间误算失去整天进度。 - -## 反馈 -- HUD 持续显示：__。 -- 阈值预告：__（商店将关/日终将至）。 -- 不可用原因：__（尚未开放/已关闭/今天不营业）。 - -## 内部循环 -`行动请求 → 时间推进 → 窗口变化 → 日终结算 → 下一天` - -## 输入、输出与依赖 -### 输入 -- 各活动系统提供已验证的行动耗时请求。 -### 输出 -- 向全部系统提供当前日期/时段/季节/天气与跨天 tick。 -### 依赖 -- __ - -## 边界与非目标 -- 不负责活动本身的时间成本 → 移交各活动系统。 -- 不模拟真实天文（潮汐/星象）。 -- 不负责字段定义、数值配置与表格结构——归技术文档层（数值策划）。 - -## 开放问题 -- __ +## 待定设计 +（只记录影响节奏或实现的未决规则。） diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/03_生产种植经营/SKILL.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/03_生产种植经营/SKILL.md index 98d0e87e1..489206a56 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/03_生产种植经营/SKILL.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/03_生产种植经营/SKILL.md @@ -1,28 +1,10 @@ -### C2 03_生产种植经营/SKILL.md（→ modules/system-types/03_生产种植经营/SKILL.md） +# 生产种植经营 ---- -name: gdd-sys-03-farm-production -description: 写"生产/种植经营"类系统文档时使用。与 skills/systems.md 配套。 - 配套模板：modules/system-types/03_生产种植经营/模板.md。 ---- +玩法存在投入、加工、培育或周期性产出时，参考本类型。地块、作物、设施、动物和自动化都由具体项目选择。 -# 生产种植经营 · 系统写法 +- 说明生产对象、玩家投入、等待或维护、产出与再投入之间的关系；让玩家知道选择带来的收益、成本和时间差。 +- 对实际存在的生产对象写清状态、转换条件、异常结果和中断后的恢复。状态可以按地块、作物、设施或其他对象组织，不套用固定状态列表。 +- 说明投入如何被占用或消耗，产出如何判定、领取与进入后续系统；相关物品身份、容量、价格和时间由实际权威系统决定。 +- 反馈应让玩家看懂当前进度、可操作条件和结果。已有产量、时长、品质等参数可以保留，并由技术设计收编、补齐实现规格。 -**定位**：把土地/设施变成周期性产出的规则层。 - -## 本类型要点 -- 状态与规则用**状态机写法**，逐对象写全转换： - 地块（地形/开垦/湿度/生长阶段）、作物（生长→成熟→再生/枯萎的转换 - 条件）、设施（空闲/生产中/可取出）。 -- 数据交接的关键定性声明：作物主表必须体现"种子与收获物是两个物品 ID" - 的引用结构（生产系统不定义物品，只引用）。 -- 反馈：地块状态图标（水分/阶段/可收/异常）+ 设施队列状态—— - 周期性产出的可读性全靠状态外显。 -- 边界三不：不管背包/堆叠/售价；不管工具升级全树（只读条件）； - 不做动物 AI。 -- 典型开放问题：维护复杂度（只浇灌 vs 肥力病害）？动物进首版吗？ - 自动化省什么、不省什么？ - -## 本类型自查 -- 每种作物从种到收的完整转换链画全了吗（含异常分支：枯萎/季节截断）？ -- 自动化收益有没有越线（让玩家跳过全部农场决策）？ +检查：一次生产从投入到结果能否追踪；失败、中断或重复领取会怎样处理？ diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/03_生产种植经营/模板.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/03_生产种植经营/模板.md index 81c0341fe..4e3dabd52 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/03_生产种植经营/模板.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/03_生产种植经营/模板.md @@ -1,73 +1,12 @@ -### C2 03_生产种植经营/模板.md（→ modules/system-types/03_生产种植经营/模板.md） - # __系统：S__（生产种植经营类） -## 系统目的 -（本系统存在是为了 __；若删除它，__。） +按实际生产机制选取内容，不预设种植、畜牧或设施都存在。 -## 支撑的玩家体验 -（对应顶层设计目标第 __ 条。） -- __ +## 生产过程与玩家选择 +（生产对象、投入、维护或等待、产出与再投入；投入产出的权威来源与去向，玩家如何看到进度、条件和结果，以及面对的实际取舍。） -## 进入与退出 -### 进入 -- 进入农场/生产区域：__。 -### 退出 -- 离开区域/日终作物状态保持：__。 +## 状态与产出规则 +（对象状态、转换条件、中断或异常、产出判定与领取；保留已确定的参数。） -## 玩家行动 -- 开垦：__。 -- 播种：__。 -- 浇灌/维护：__。 -- 收获：__。 -- 设施操作：__。 - -## 取舍表 - -| 决策 | 立即收益 | 延迟收益 | 主要代价 | -|---|---|---|---| -| __ | __ | __ | __ | - -## 状态与规则 -### 地块状态机 -- 状态：未开垦 / 已开垦 / 已种植 / __。 -- 转换：__ → __（条件：__）；异常分支：__。 -### 作物状态机 -- 状态：生长 / 成熟 / 再生 / 枯萎。 -- 转换：__（条件：浇水/时间片/季节）；季节截断规则：__。 -### 设施状态机 -- 状态：空闲 / 生产中 / 可取出。 -- 转换与时长结构：__。 - -## 数值与数据交接（→技术文档层） -本系统交由技术文档层定义的数据类别：作物主表、设施表、动物表。 -定性声明：作物主表必须体现"种子与收获物各引一个物品 ID"，生产系统不定义物品。 - -随交接附下的设计侧定性约束： -- __（如：维护复杂度上限、自动化省体力不省决策） - -## 反馈 -- 地块状态图标：水分 / 阶段 / 可收 / 异常。 -- 设施队列状态：__。 - -## 内部循环 -`开垦 → 播种 → 维护 → 等待 → 收获 → 再投入` - -## 输入、输出与依赖 -### 输入 -- 时间系统提供跨天 tick；物品系统提供种子与工具；体力系统扣行动成本。 -### 输出 -- 向物品系统提交收获物入账。 -### 依赖 -- __ - -## 边界与非目标 -- 不管背包/堆叠/售价 → 移交物品与经济系统。 -- 不管工具升级全树（只读成长系统条件）。 -- 不做动物 AI。 -- 不负责字段定义、数值配置与表格结构——归技术文档层（数值策划）。 - -## 开放问题 -- 维护复杂度：只浇灌还是加肥力病害？ -- 动物进首版吗？ -- 自动化省什么、不省什么？ +## 待定设计 +（只记录影响生产闭环的未决规则。） diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/04_地图与探索/SKILL.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/04_地图与探索/SKILL.md index cca360aa9..3496af411 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/04_地图与探索/SKILL.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/04_地图与探索/SKILL.md @@ -1,24 +1,11 @@ -### C2 04_地图与探索/SKILL.md（→ modules/system-types/04_地图与探索/SKILL.md） +# 地图与探索 ---- -name: gdd-sys-04-map-exploration -description: 写"地图与探索"类系统文档时使用。与 skills/systems.md 配套。 - 配套模板：modules/system-types/04_地图与探索/模板.md。 ---- +玩法依赖空间结构、通达、发现或区域解锁时，参考本类型；不预设连续地图、独立场景或传送点。 -# 地图与探索 · 系统写法 +- 说明玩家从当前位置可以去哪里，路径、入口和区域之间如何连接，移动或迁移产生什么结果。 +- 对实际存在的锁定、开放或发现机制写清条件、状态变化及不可通达时的原因；进入区域后可做什么由相应玩法共同确定。 +- 说明位置、已发现区域、入口状态等由谁持有，以及地图变化如何影响其他系统。区域上的资源或遭遇规则按实际职责分配。 +- 玩家应能辨认当前位置、可走方向、重要变化和失败原因；展示形式由项目界面决定。 +- 已确定的移动成本、范围或解锁参数可以保留，技术设计需收编并补齐实现规格。 -**定位**：区域网络与解锁的容器层。 - -## 本类型要点 -- 状态与规则：区域清单的定性结构（区域类型/父子归属/解锁条件/开放时段） - + 入口可用性判定——**入口不可用必须给原因**。 -- 反馈：地图界面（当前位置/已解锁/出口/标记）+ 新区域提示 - （名称与可做的活动类型，让"解锁"可感知）。 -- 边界：不管采集物/鱼/敌人的奖励概率（那是活动系统）；不管操作判定。 -- 典型开放问题：独立场景 vs 连续地图？移动成本记时间还是体力？ - 资源点刷新规则？ - -## 本类型自查 -- 每个区域解锁后"能做什么"说得清吗（活动类型归属到具名系统）？ -- 有没有奖励概率类内容偷偷写进区域？（该在活动系统） +检查：任一目标位置是否有可解释的通达判定；解锁后是否真能按预期到达和开展活动？ diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/04_地图与探索/模板.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/04_地图与探索/模板.md index 5129075c0..45f24f04f 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/04_地图与探索/模板.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/04_地图与探索/模板.md @@ -1,69 +1,12 @@ -### C2 04_地图与探索/模板.md（→ modules/system-types/04_地图与探索/模板.md） - # __系统：S__（地图与探索类） -## 系统目的 -（本系统存在是为了 __；若删除它，__。） +按实际空间机制选取内容，不预设区域层级、开放时段或传送。 -## 支撑的玩家体验 -（对应顶层设计目标第 __ 条。） -- __ +## 空间结构与移动 +（位置、路径或入口如何组织，位置和区域状态由谁维护；玩家如何辨认路径、执行移动，与活动系统如何交接，成本与结果是什么。） -## 进入与退出 -### 进入 -- 打开地图界面/进入区域：__。 -### 退出 -- 离开区域/传送：__。 +## 通达、发现与解锁 +（实际条件、状态变化、失败原因及解锁后的可用内容，玩家如何辨认这些变化。保留已确定的参数。） -## 玩家行动 -- 移动：__。 -- 查看地图与标记：__。 -- 尝试进入锁定区域：__。 - -## 取舍表 - -| 决策 | 立即收益 | 延迟收益 | 主要代价 | -|---|---|---|---| -| __ | __ | __ | __ | - -## 状态与规则 -### 区域清单（定性结构） -- 区域类型：__；父子归属：__。 -- 解锁条件：__；开放时段：__。 -### 入口可用性判定 -- 可用：__。 -- 不可用 + 原因：__（未解锁/条件未满足/时段不对）。 -### 移动规则 -- 区域内移动与跨区域移动：__。 - -## 数值与数据交接（→技术文档层） -本系统交由技术文档层定义的数据类别：区域表、区域连接表、活动入口表、场景对象表、传送点表。 - -随交接附下的设计侧定性约束： -- __（如：任何区域至少一条合法入口；解锁后确实可进入） - -## 反馈 -- 地图界面：当前位置 / 已解锁 / 出口 / 标记。 -- 新区域提示：名称 + 可做的活动类型。 -- 入口不可用：显示原因。 - -## 内部循环 -`查看地图 → 选择目的地 → 移动/解锁 → 到达并开展活动` - -## 输入、输出与依赖 -### 输入 -- 任务/成长系统提供解锁条件状态；时间系统提供开放时段。 -### 输出 -- 向各活动系统提供当前位置与活动入口。 -### 依赖 -- __ - -## 边界与非目标 -- 不管采集物/鱼/敌人的奖励概率 → 移交各活动系统。 -- 不管操作判定。 -- 不负责字段定义、数值配置与表格结构——归技术文档层（数值策划）。 - -## 开放问题 -- 独立场景还是连续地图？ -- 移动成本记时间还是体力？ -- 资源点刷新规则？ +## 待定设计 +（只记录影响空间体验或实现的未决规则。） diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/05_采集与支线活动/SKILL.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/05_采集与支线活动/SKILL.md index 8aaa8fbae..052fc5147 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/05_采集与支线活动/SKILL.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/05_采集与支线活动/SKILL.md @@ -1,26 +1,10 @@ -### C2 05_采集与支线活动/SKILL.md（→ modules/system-types/05_采集与支线活动/SKILL.md） +# 采集与支线活动 ---- -name: gdd-sys-05-gathering-activities -description: 写"采集与支线活动"类系统文档（采集/钓鱼/挖矿等侧挂轻活动）时使用。 - 与 skills/systems.md 配套。配套模板：modules/system-types/05_采集与支线活动/模板.md。 ---- +玩法包含采集、钓鱼、挖掘或其他可独立说明的活动时，参考本类型。活动可以是核心玩法，也可以是辅助玩法，深度由项目目标决定。 -# 采集与支线活动 · 系统写法 +- 说明玩家如何发现和进入活动、执行哪些动作、何时结束；前置条件只列实际生效的区域、时间、工具、资源或任务条件。 +- 写清操作或数值判定、成功与失败结果，以及节点或机会的消耗和刷新。不同活动可采用不同判定方式，不预设时机操作。 +- 说明产物的类别、数量或品质如何确定，并交代领取、占用或重复触发的规则。背包与经济的权威归属按实际架构。 +- 玩家应能理解可参与条件、判定结果和获得内容；已确定的刷新、概率和产出参数可以保留，技术设计需收编并补齐实现规格。 -**定位**：主循环侧挂的轻活动，共性是"入口在地图、产出进背包、深度可调"。 - -## 本类型要点 -- 进入与退出必须写**前置条件链**：所在区域/季节天气时段/工具/背包空间 - ——缺一环即不可进入，逐环列清。 -- 玩家行动写判定类动词（观察时机/出手/收货），深度服务于轻度挑战。 -- 状态与规则：节点刷新与判定节奏的定性规则（何时刷新、判定什么、 - 判定失败的走向）。 -- 边界：不管背包与售价；不管地图承载；**操作深度服务于轻度挑战， - 不做独立动作游戏**。 -- 典型开放问题：判定用手感还是数值门槛？季节限制的密度？ - -## 本类型自查 -- 前置条件链每一环的"缺环反馈"都写了吗（缺工具说缺什么）？ -- 本活动删掉后主循环还成立吗？（成立=合格的侧挂；不成立=它其实是主玩法， - 回架构层重定位） +检查：一次活动从可进入到结算是否完整；失败和刷新是否会造成无法解释的重复收益或机会损失？ diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/05_采集与支线活动/模板.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/05_采集与支线活动/模板.md index f2bc9a509..5e00d3b00 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/05_采集与支线活动/模板.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/05_采集与支线活动/模板.md @@ -1,69 +1,12 @@ -### C2 05_采集与支线活动/模板.md（→ modules/system-types/05_采集与支线活动/模板.md） - # __系统：S__（采集与支线活动类） -## 系统目的 -（本系统存在是为了 __；若删除它，__。） +按实际活动选取内容，不预设轻量操作或固定的进入条件链。 -## 支撑的玩家体验 -（对应顶层设计目标第 __ 条。） -- __ +## 活动过程 +（玩家如何发现、进入、行动和退出；实际前置条件及不可参与原因，就近注明位置、时间、工具或资源的权威来源。） -## 进入与退出 -### 前置条件链 -- 所在区域：__（缺失反馈：__）。 -- 季节/天气/时段：__（缺失反馈：__）。 -- 工具：__（缺失反馈：__）。 -- 背包空间：__（缺失反馈：__）。 -### 退出 -- 完成判定/离开区域/背包满：__。 +## 判定、刷新与产出 +（成功和失败如何判定，机会如何消耗或刷新，产物如何确定与领取；说明结算结果交给谁处理、玩家如何理解状态与结果，保留已确定的参数。） -## 玩家行动 -- 观察时机：__。 -- 出手：__。 -- 收获：__。 - -## 取舍表 - -| 决策 | 立即收益 | 延迟收益 | 主要代价 | -|---|---|---|---| -| __ | __ | __ | __ | - -## 状态与规则 -### 节点规则 -- 刷新：__（何时/何处/多少）。 -- 判定：__（判定什么、成功失败走向）。 -### 品质与产出规则 -- __ - -## 数值与数据交接（→技术文档层） -本系统交由技术文档层定义的数据类别：采集点表、掉落表、钓鱼点表、对象主表（鱼/矿）、行为表。 - -随交接附下的设计侧定性约束： -- __（如：产出可由多渠道补充，不强迫单玩法） - -## 反馈 -- 判定结果：__。 -- 收获入包：__。 -- 前置缺失：__。 - -## 内部循环 -`到达点位 → 判定 → 收获 → 继续或转场` - -## 输入、输出与依赖 -### 输入 -- 地图系统提供点位与区域；时间系统提供季节天气时段；物品系统提供工具与背包容量。 -### 输出 -- 向物品系统提交获得物。 -### 依赖 -- __ - -## 边界与非目标 -- 不管背包与售价 → 移交物品与经济系统。 -- 不管地图承载 → 移交地图系统。 -- 不做独立动作游戏（操作深度服务于轻度挑战）。 -- 不负责字段定义、数值配置与表格结构——归技术文档层（数值策划）。 - -## 开放问题 -- 判定用手感还是数值门槛？ -- 季节限制的密度？ +## 待定设计 +（只记录影响活动闭环的未决规则。） diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/06_战斗与敌人/SKILL.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/06_战斗与敌人/SKILL.md index 88ca94814..c040faf03 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/06_战斗与敌人/SKILL.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/06_战斗与敌人/SKILL.md @@ -1,29 +1,11 @@ -### C2 06_战斗与敌人/SKILL.md（→ modules/system-types/06_战斗与敌人/SKILL.md） +# 战斗与敌人 ---- -name: gdd-sys-06-combat -description: 写"战斗与敌人"类系统文档时使用。与 skills/systems.md 配套。 - 配套模板：modules/system-types/06_战斗与敌人/模板.md。 ---- +玩法存在对抗、伤害或敌方决策时，参考本类型。战斗可以是主要玩法，也可以服务其他玩法；实时、回合或指令制按项目决定。 -# 战斗与敌人 · 系统写法 +- 说明遭遇如何开始和结束，玩家实际可用的动作及其条件、成本和效果；不预设普攻、闪避、格挡、消耗品或撤退均存在。 +- 写清敌方行为如何选择与转换，攻击或效果如何判定，玩家凭什么信息作出反应。可读性与反应机会应符合本项目战斗形式，不强制使用前摇状态。 +- 说明胜负、退出、奖励、损失和恢复路径。失败是否失去积累、撤退是否保留奖励，均按本项目规则明确。 +- 对实际存在的生命、装备、技能、遭遇和战利品说明权威来源及结果去向；防止同一战斗结果被重复结算。 +- 已确定的动作时长、伤害、掉落等参数可以保留，TDD 需收编并补齐实现规格。具体写法可参考 `exemplars/stardew-s06-combat.md`，样例中的玩法不作为通用约束。 -**定位**：风险-回报换算器。 - -## 本类型要点 -- 玩家行动写操作动词组：移动观察/普攻重攻技能/防闪格挡/消耗品/撤退。 -- 状态与规则：玩家战斗态（生命/装备/冷却）+ 敌人状态机—— - **预警前摇必写**（待机/警觉/攻击前摇/攻击中/受击/眩晕/死亡/撤退）， - 给玩家反应窗口是设计义务。 -- 数值交接必带定性约束："敌人是什么/怎么行动/掉什么"三拆分 - （难度与经济可独立调节）；普通敌人不稳定掉高价物；失败不清空积累； - 收益回流主玩法不取代它。 -- 反馈：命中/受击/闪避/格挡/暴击各给独立视听反馈；敌人显示预警与 - 可攻击时机；失败说明原因和恢复路径。 -- 边界：不管通用生命与昏倒惩罚（只提交状态变化）；不管武器售价与 - 耐久主数据。 -- 典型开放问题：实时 vs 节奏判定？体力是否影响战斗动作？耐久？ - -## 本类型自查 -- 敌人每种状态转换都有触发条件吗？前摇时长结构定了吗（数值归 TDD）？ -- 战斗收益走"回流主玩法"还是"直接变现"？（后者会反客为主） +检查：玩家是否能理解自身选择和敌方行为造成的结果；一场战斗的结束与恢复是否有确定规则？ diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/06_战斗与敌人/模板.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/06_战斗与敌人/模板.md index cb583d10f..c0ee46544 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/06_战斗与敌人/模板.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/06_战斗与敌人/模板.md @@ -1,102 +1,12 @@ -### C2 06_战斗与敌人/模板.md（→ modules/system-types/06_战斗与敌人/模板.md） - # __系统：S__（战斗与敌人类） -## 系统目的 -（本系统存在是为了 __；若删除它，__。） +按实际战斗机制选取内容，不预设动作、防御方式、敌人状态或失败惩罚。 -## 支撑的玩家体验 -（对应顶层设计目标第 __ 条。） -- __ +## 遭遇与玩家行动 +（战斗如何开始、结束；玩家有哪些实际动作，其条件、成本和效果是什么。就近说明状态的权威来源、交互系统和玩家可见的反馈。） -## 进入与退出 -### 进入 -- 进入危险区域/触发遭遇：__。 -- 初始化检查：区域/时间/装备/生命/背包/任务条件。 -### 退出 -- 击败敌人并结算奖励：__。 -- 主动撤退（保留已结算奖励）：__。 -- 生命归零（移交状态系统处理惩罚）：__。 -- 事件/日终强制结束：__。 +## 敌方行为与结算 +（敌方如何决策和转换，玩家如何识别威胁，攻防或其他效果如何判定；胜负、奖励、损失和恢复由谁处理，玩家如何获知结果与后续选择。保留已确定的参数。） -## 玩家行动 -- 移动与观察敌人攻击范围/行为状态：__。 -- 普通攻击/重攻击/装备技能：__。 -- 防御/闪避/格挡/场景规避：__。 -- 使用消耗品：__。 -- 拾取战利品/继续深入：__。 -- 撤退：__。 - -通用流程： -`进入遭遇 → 读取敌人状态 → 玩家行动 → 敌人响应 → 结算伤害/效果 → 判断胜负或撤退` - -## 取舍表 - -| 决策 | 立即收益 | 延迟收益 | 主要代价 | -|---|---|---|---| -| 深入还是撤退 | __ | __ | __ | -| 消耗品用还是留 | __ | __ | __ | -| 快速击杀还是稳健规避 | __ | __ | __ | -| 高伤高耗还是基础攻击 | __ | __ | __ | - -## 状态与规则 -### 玩家战斗状态 -- 生命/最大生命/状态效果：__。 -- 装备中的武器防具饰品消耗品：__。 -- 攻击/防御/移动/闪避/冷却：__。 -- 战斗区域/遭遇编号/撤退状态：__。 -### 敌人状态机 -- 状态：待机 / 警觉 / 攻击前摇 / 攻击中 / 受击 / 眩晕 / 死亡 / 撤退。 -- 转换条件：__（前摇时长结构：__，数值归技术文档层）。 -### 战斗规则 -- 攻击结算条件（距离/方向/冷却/装备）：__。 -- 伤害构成因素：来源属性/目标防御/倍率/状态效果。 -- 敌人攻击必须有可识别预警。 -- 死亡只结算一次经验与战利品，防重复领取。 -- 撤退保留已结算奖励。 -### 区域遭遇 -- 危险区域构成（敌人组/刷新/深度分层）：__。 -- 难度表达靠可理解条件，不靠数值墙。 - -## 数值与数据交接（→技术文档层） -本系统交由技术文档层定义的数据类别：敌人配置、敌人行为配置、武器配置、技能配置、遭遇配置、战利品配置、状态效果配置。 - -随交接附下的设计侧定性约束： -- 敌人数据拆分为"是什么/怎么行动/掉什么"三类。 -- 普通敌人不应稳定掉落高价值物品；收益以稀有材料和成长为主。 -- 失败保留已结算战利品，主要损失是时间/位置/少量金钱。 -- 收益回流方向：__（战斗不直接取代 __ 的收入）。 - -## 反馈 -- 命中/受击/闪避/格挡/暴击：各自独立的视听反馈。 -- 敌人：生命/预警/当前状态/可攻击时机。 -- 玩家：生命/补给/冷却/撤退可用性持续可见。 -- 胜利：经验/战利品/区域进度。失败：原因+损失+保留+恢复路径。 - -## 内部循环 -### 单次战斗 -`观察敌人 → 选择攻击或防御 → 处理敌人响应 → 造成或承受伤害 → 调整策略 → 击败或撤退` -### 区域循环 -`准备装备补给 → 进入区域 → 战斗与搜刮 → 判断深入或返程 → 带回资源` - -## 输入、输出与依赖 -### 输入 -- 地图系统提供区域与遭遇入口；时间系统提供时间与日终信号； - 状态系统提供生命体力与失败处理；物品系统提供装备与战利品入口； - 成长系统提供属性与解锁。 -### 输出 -- 向物品系统提交战利品；向成长系统提交经验；向地图系统提交遭遇状态； - 向任务系统提交击败/调查进度；向 UI 输出战斗状态与结果。 -### 依赖 -- __ - -## 边界与非目标 -- 不负责通用生命与昏倒惩罚（只提交状态变化）→ 移交状态系统。 -- 不负责武器售价与耐久主数据 → 移交物品/经济系统。 -- 不负责字段定义、数值配置与表格结构——归技术文档层（数值策划）。 -- __（本项目特有排除项） - -## 开放问题 -- 实时操作还是节奏/指令判定？ -- 体力是否影响战斗动作？ -- 武器耐久制还是升级替换制？ +## 待定设计 +（只记录影响战斗闭环的未决规则。） diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/07_物品背包与制作/SKILL.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/07_物品背包与制作/SKILL.md index 3e8bc760c..3590ac2b7 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/07_物品背包与制作/SKILL.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/07_物品背包与制作/SKILL.md @@ -1,26 +1,12 @@ -### C2 07_物品背包与制作/SKILL.md（→ modules/system-types/07_物品背包与制作/SKILL.md） +# 物品、背包与制作 ---- -name: gdd-sys-07-items-crafting -description: 写"物品、背包与制作"类系统文档时使用。与 skills/systems.md 配套。 - 配套模板：modules/system-types/07_物品背包与制作/模板.md。 ---- +按实际系统选用本页与同目录的 `模板.md`；物品、容器、装备和制作可以由不同系统负责，不必合并。 -# 物品、背包与制作 · 系统写法 +## 值得确定的问题 -**定位**：全游戏物品身份与转换的唯一真源——所有系统产出的公共语言层。 +- 物品怎样被识别与引用？类型、堆叠、品质、实例属性或耐久只在玩法需要时定义。跨系统引用同一物品时，说明权威来源；只读副本或快照说明来源及更新、恢复方式。 +- 玩家怎样获得、存放、使用、装备、转移或失去物品？容量限制、溢出、丢弃与失败时的结果要可理解。 +- 制作存在时，写清输入、产物、解锁、消耗与完成条件，并检查所需输入能否获得；队列、耗时、工作台等由实际玩法决定。 +- 多材料配方逐项表达输入与数量，TDD 收编完整内容与规则；具体字段和表结构由施工方决定，已有数据契约除外。 -## 本类型要点 -- 状态与规则：物品身份规则（类型/堆叠上限/品质/用途类别）+ 容器、 - 装备栏、制作队列的状态转换。 -- 数据交接的关键定性声明：**多材料配方必须用关系子表**（一行一材料）， - 不许把多个物品 ID 拼进一个单元格。 -- 反馈：获得/消耗/堆叠/装备各给提示；**背包满要说明缺什么、怎么办**； - 配方界面显示持有/缺口/耗时/产物。 -- 边界：不管最终售价（经济系统唯一维护）、任务文本、NPC 喜好—— - 他家只引用本系统 ID；不复制主数据到别家；**不把整理背包做成玩法**。 -- 典型开放问题：格子容量还是重量？耐久制还是升级替换制？ - -## 本类型自查 -- 有没有别的系统在自己的文档里定义了物品属性？（发现即协调，物品身份只此一家） -- 配方链有没有"制作不出来"的死路（输入不可获得）？定性检查可达性。 +物品变化应让玩家看得懂。价格、任务判定等跨系统规则按已定架构协作，不在这里另定归属。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/07_物品背包与制作/模板.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/07_物品背包与制作/模板.md index 7330baac0..02750960d 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/07_物品背包与制作/模板.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/07_物品背包与制作/模板.md @@ -1,73 +1,19 @@ -### C2 07_物品背包与制作/模板.md（→ modules/system-types/07_物品背包与制作/模板.md） - # __系统：S__（物品、背包与制作类） -## 系统目的 -（本系统存在是为了 __；若删除它，__。） +按实际职责选取下列内容，删去不适用项；保留已确定的参数。 -## 支撑的玩家体验 -（对应顶层设计目标第 __ 条。） -- __ +## 范围与玩家操作 -## 进入与退出 -### 进入 -- 打开背包/制作界面/获得物品时：__。 -### 退出 -- 关闭界面/完成制作：__。 +说明本系统服务的体验、玩家可执行的操作，以及与相邻系统的职责和数据来源。 -## 玩家行动 -- 查看/整理：__。 -- 使用/装备：__。 -- 制作/入队：__。 -- 丢弃/出售（发起请求）：__。 +## 物品与容器规则 -## 取舍表 +记录实际存在的物品身份、数量或实例属性、容器限制，以及获得、使用、转移和失败后的状态。必要时说明副本或快照从何而来、如何更新或恢复。 -| 决策 | 立即收益 | 延迟收益 | 主要代价 | -|---|---|---|---| -| __ | __ | __ | __ | +## 制作规则与反馈 -## 状态与规则 -### 物品身份规则 -- 类型体系：__。 -- 堆叠规则：__。 -- 品质规则：__。 -### 容器与装备栏 -- 容量结构与状态：__。 -- 装备槽位与转换：__。 -### 制作队列 -- 状态：排队中 / 制作中 / 完成 / 取出。 -- 转换与结构：__。 +制作存在时说明配方输入、产物、解锁、消耗、完成与无法制作的原因；说明玩家如何看见关键变化，并检查输入的可获得性。 -## 数值与数据交接（→技术文档层） -本系统交由技术文档层定义的数据类别：物品表、品质表、容器表、装备表、配方表、配方解锁表。 -定性声明：多材料配方必须用关系子表（一行一材料），禁止多 ID 拼单元格。 +## 实现交接 -随交接附下的设计侧定性约束： -- __（如：关键配方输入至少两条获得渠道） - -## 反馈 -- 获得/消耗/堆叠/装备：各自提示。 -- 背包满：说明缺什么、怎么办。 -- 配方界面：持有/缺口/耗时/产物。 - -## 内部循环 -`获得材料 → 查看配方 → 制作入队 → 取出产物 → 用于目标系统` - -## 输入、输出与依赖 -### 输入 -- 各活动系统提交获得物；成长系统提供配方解锁条件。 -### 输出 -- 向全部系统提供物品实例与查询；向经济系统提供交易对象。 -### 依赖 -- __ - -## 边界与非目标 -- 不管最终售价 → 移交经济系统（唯一维护）。 -- 不管任务文本与 NPC 喜好 → 移交任务/NPC 系统（只引用本系统 ID）。 -- 不把整理背包做成玩法。 -- 不负责字段定义、数值配置与表格结构——归技术文档层（数值策划）。 - -## 开放问题 -- 格子容量还是重量容量？ -- 耐久制还是升级替换制？ +将已确定的规则、参数和内容交由 TDD 收编并补齐设计缺口；内部字段、配置和数据结构由施工方选择。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/08_成长与技能/SKILL.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/08_成长与技能/SKILL.md index 1bad1bf92..2bf771bca 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/08_成长与技能/SKILL.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/08_成长与技能/SKILL.md @@ -1,26 +1,12 @@ -### C2 08_成长与技能/SKILL.md（→ modules/system-types/08_成长与技能/SKILL.md） +# 成长与技能 ---- -name: gdd-sys-08-progression -description: 写"成长与技能"类系统文档时使用。与 skills/systems.md 配套。 - 配套模板：modules/system-types/08_成长与技能/模板.md。 ---- +按实际系统选用本页与同目录的 `模板.md`；成长不必采用经验等级、可重置分支或工具升级。 -# 成长与技能 · 系统写法 +## 值得确定的问题 -**定位**：把重复活动兑换为能力扩展。 +- 哪些行为推动成长？进度如何累计、达到条件后发生什么，能力或可选行动如何改变？ +- 不同成长路径、上限、重选或不可逆选择是否存在？按目标体验决定，并写清玩家作决定时能看到的信息与后果。 +- 成长效果由哪些系统消费？同一能力的权威状态及其生效、失效时机要与架构一致。 +- 玩家如何理解进度和新能力？展示实际可做的变化；仅数值变化的成长也可以成立，但要说明其用途。 -## 本类型要点 -- 状态与规则：技能态（等级/当前经验）、工具升级态（在造/完成/不可用期）、 - 分支选择态（**可恢复设计**，避免早期选择不可逆）。 -- 反馈：活动得经验即时显示；**升级展示能力变化，不只是数字跳**； - 工具升级界面显示前后对比/费用/耗时/不可用期。 -- 设计侧定性约束：升级奖励优先"省时间省体力/扩大选择/解锁配方"， - 而非单纯加数值——与架构数值基准的风格对齐。 -- 边界：不管单次活动的基础奖励与各公式（只接收经验提交）； - 不做复杂天赋树/随机词缀/无限膨胀。 -- 典型开放问题：技能独立还是合并？升级等待期还是即时？重置成本？ - -## 本类型自查 -- 每次升级玩家能说出"我变强在哪"吗（能力语言，不是数值语言）？ -- 有没有成长线绕开主循环自成玩法？（那是第二主轴，回架构层） +保留已确定的门槛、效果和参数，交由 TDD 收编并补齐实现规格。检查成长是否支持既定玩法，而不是无意中另造一条主循环。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/08_成长与技能/模板.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/08_成长与技能/模板.md index 61502e11c..c2906b970 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/08_成长与技能/模板.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/08_成长与技能/模板.md @@ -1,70 +1,19 @@ -### C2 08_成长与技能/模板.md（→ modules/system-types/08_成长与技能/模板.md） - # __系统：S__（成长与技能类） -## 系统目的 -（本系统存在是为了 __；若删除它，__。） +按实际成长机制选取内容，删去不适用项；保留已确定的参数。 -## 支撑的玩家体验 -（对应顶层设计目标第 __ 条。） -- __ +## 成长目标与来源 -## 进入与退出 -### 进入 -- 提交经验/查看技能面板/发起升级：__。 -### 退出 -- __ +说明希望玩家感到什么变化，哪些行动或条件产生进度，以及与其他系统的输入输出。 -## 玩家行动 -- 查看技能与进度：__。 -- 发起工具升级：__。 -- 选择分支：__。 +## 进度、选择与效果 -## 取舍表 +记录实际存在的等级、解锁、分支、升级或其他状态；说明转换条件、效果生效范围、上限和失败或重选规则。 -| 决策 | 立即收益 | 延迟收益 | 主要代价 | -|---|---|---|---| -| __ | __ | __ | __ | +## 玩家反馈 -## 状态与规则 -### 技能态 -- 等级/当前经验结构：__。 -- 经验来源：__（只接收各活动系统提交）。 -### 工具升级态 -- 状态：在造 / 完成 / 不可用期。 -- 转换与结构：__。 -### 分支选择态 -- 可恢复设计：__（重置路径与成本结构）。 +说明玩家在行动、达成门槛和作选择时，怎样看到进度、能力变化及其代价。 -## 数值与数据交接（→技术文档层） -本系统交由技术文档层定义的数据类别：技能表、等级经验表、能力节点表、工具升级表、效果表。 +## 实现交接 -随交接附下的设计侧定性约束： -- 升级奖励优先：省时间/省体力/扩大选择/解锁配方，而非单纯加数值。 -- 前几级在正常游玩的数个游戏日内出现（量级感）。 - -## 反馈 -- 经验获得：即时显示。 -- 升级：展示能力变化（不只是数字）。 -- 工具升级：前后对比/费用/耗时/不可用期。 - -## 内部循环 -`重复活动 → 提交经验 → 升级 → 能力扩展 → 更高效地活动` - -## 输入、输出与依赖 -### 输入 -- 各活动系统提交经验；物品系统提供工具升级材料入口。 -### 输出 -- 向各系统提供能力加成与解锁条件；向制作系统提供配方解锁。 -### 依赖 -- __ - -## 边界与非目标 -- 不管单次活动的基础奖励与各公式 → 移交各活动系统。 -- 不做复杂天赋树/随机词缀/无限数值膨胀。 -- 不负责字段定义、数值配置与表格结构——归技术文档层（数值策划）。 - -## 开放问题 -- 技能独立还是合并？ -- 升级等待期还是即时完成？ -- 重置成本？ +列出已确定的门槛、效果、参数与待补规格，由 TDD 收编并补齐实现所需定义。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/09_NPC关系与任务/SKILL.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/09_NPC关系与任务/SKILL.md index 24b13c8dc..4b67a8651 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/09_NPC关系与任务/SKILL.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/09_NPC关系与任务/SKILL.md @@ -1,26 +1,12 @@ -### C2 09_NPC关系与任务/SKILL.md（→ modules/system-types/09_NPC关系与任务/SKILL.md） +# NPC、关系与任务 ---- -name: gdd-sys-09-npc-quest -description: 写"NPC、关系与任务"类系统文档时使用（覆盖关系与任务两个职责）。 - 与 skills/systems.md 配套。配套模板：modules/system-types/09_NPC关系与任务/模板.md。 ---- +按实际职责选用本页与同目录的 `模板.md`；NPC、关系和任务可以分别成系统，也可以只采用其中一部分。 -# NPC、关系与任务 · 系统写法 +## 值得确定的问题 -**定位**：把系统产出转译为"人情"回报。 +- 玩家怎样遇见并与 NPC 互动？可互动条件、位置或日程的权威来源按架构确定，不预设时间系统负责日程。 +- 关系存在时，哪些行为改变关系，变化怎样影响对话、事件、能力或其他结果？显式数值、等级和奖励类型由作品决定。 +- 任务存在时，说明接取、推进、完成、失败、放弃与重试中实际需要的状态和条件；多目标、多奖励可以逐项表达，不预定数据库表形。 +- 重要变化应呈现原因、进度和结果。复杂叙事、不可逆选择或社区目标可按作品需要设计，后果要让玩家有足够信息判断。 -## 本类型要点 -- 状态与规则：NPC 的定性结构（日程归属/礼物偏好/初始关系）+ 关系值与 - 等级转换 + 任务阶段机（未接/进行/可提交/完成/失败）。 -- 数据交接的关键定性声明：**任务目标与奖励各用关系表**（一行一条）， - 多目标多奖励不许拼单元格。 -- 反馈：可互动状态/今日已赠礼/关系变化原因要可见；**关系升级必须展示 - 解锁了什么**（对话/事件/配方），不是只跳数字。 -- 边界：不管 NPC 底层移动寻路；不管物品价格与战斗结果； - 不做复杂分支叙事与不可逆惩罚。 -- 典型开放问题：好感度显式还是隐式？任务失败可重接吗？社区目标牵引强度？ - -## 本类型自查 -- 关系每一级"解锁了什么"列全了吗（人情回报要可见）？ -- 任务奖励有没有绕过经济系统直接发钱发物？（必须经物品/经济系统入账） +奖励入账和其他系统的状态变更应走其既定接口。已确定的目标、奖励与参数交由 TDD 收编并补齐实现规格。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/09_NPC关系与任务/模板.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/09_NPC关系与任务/模板.md index 5c8154289..ab4d8dac7 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/09_NPC关系与任务/模板.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/09_NPC关系与任务/模板.md @@ -1,78 +1,19 @@ -### C2 09_NPC关系与任务/模板.md（→ modules/system-types/09_NPC关系与任务/模板.md） - # __系统：S__（NPC、关系与任务类） -## 系统目的 -（本系统存在是为了 __；若删除它，__。） +按实际职责选取内容，删去不适用项；保留已确定的参数。 -## 支撑的玩家体验 -（对应顶层设计目标第 __ 条。） -- __ +## 玩家互动与职责 -## 进入与退出 -### 进入 -- 遇到 NPC/接取任务/触发关系事件：__。 -### 退出 -- 完成任务提交/关系事件结束：__。 +说明互动入口、玩家行动、NPC 可用条件及其权威来源；写清本系统与相关系统的协作。 -## 玩家行动 -- 对话：__。 -- 赠礼：__。 -- 完成委托/提交任务目标：__。 -- 参与社区目标：__。 +## 关系与任务规则 -## 取舍表 +记录实际存在的关系变化、解锁或叙事后果，以及任务目标、阶段转换、完成和失败处理。多目标、多奖励逐项说明其条件和结果。 -| 决策 | 立即收益 | 延迟收益 | 主要代价 | -|---|---|---|---| -| __ | __ | __ | __ | +## 信息与反馈 -## 状态与规则 -### NPC 定性结构 -- 日程归属：__（作息由时间系统判定）。 -- 礼物偏好：__。 -- 初始关系：__。 -### 关系状态机 -- 关系值与等级转换：__。 -- 每级解锁：__（对话/事件/配方——逐级列全）。 -- 赠礼限制：__（如每日一次）。 -### 任务阶段机 -- 状态：未接 / 进行 / 可提交 / 完成 / 失败。 -- 转换条件：__；失败可重接规则：__。 -### 社区目标 -- 结构与进度：__。 +说明玩家如何获知可互动状态、任务进度、关系变化原因及重要选择的后果。 -## 数值与数据交接（→技术文档层） -本系统交由技术文档层定义的数据类别：NPC 表、关系等级表、礼物偏好表、对话条件表、关系事件表、任务表、任务目标表、奖励表、社区目标表。 -定性声明：任务目标与奖励各用关系表（一行一条），禁止多目标拼单元格。 +## 实现交接 -随交接附下的设计侧定性约束： -- __（如：任务奖励经物品/经济系统入账，不直接发） - -## 反馈 -- 可互动状态与今日已赠礼：可见。 -- 关系变化：显示原因。 -- 关系升级：展示解锁了什么（不是只跳数字）。 -- 任务进度：__。 - -## 内部循环 -`遇见 NPC → 互动/赠礼 → 关系进展 → 解锁内容 → 新的互动理由` - -## 输入、输出与依赖 -### 输入 -- 时间系统提供 NPC 日程判定；物品系统提供礼物与提交物；地图系统提供位置。 -### 输出 -- 向任务/社区系统提交互动事件；向制作系统提供配方解锁请求。 -### 依赖 -- __ - -## 边界与非目标 -- 不管 NPC 底层移动寻路 → 移交地图/表现层。 -- 不管物品价格与战斗结果 → 移交经济/战斗系统。 -- 不做复杂分支叙事与不可逆惩罚。 -- 不负责字段定义、数值配置与表格结构——归技术文档层（数值策划）。 - -## 开放问题 -- 好感度显式还是隐式？ -- 任务失败可重接吗？ -- 社区目标的牵引强度？ +列出已确定的目标、奖励、规则参数与待补规格，由 TDD 收编并补齐实现所需定义。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/10_经济与商店/SKILL.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/10_经济与商店/SKILL.md index f33cffb10..c76f78516 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/10_经济与商店/SKILL.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/10_经济与商店/SKILL.md @@ -1,24 +1,12 @@ -### C2 10_经济与商店/SKILL.md（→ modules/system-types/10_经济与商店/SKILL.md） +# 经济与商店 ---- -name: gdd-sys-10-economy-shop -description: 写"经济与商店"类系统文档时使用。与 skills/systems.md 配套。 - 配套模板：modules/system-types/10_经济与商店/模板.md。 ---- +按实际经济机制选用本页与同目录的 `模板.md`；商店、货币、订单和定价方式都由作品决定。 -# 经济与商店 · 系统写法 +## 值得确定的问题 -**定位**：货币唯一记账人 + 物品↔金钱的换算层。 +- 玩家通过哪些行为获得、花费或交换价值？货币、价格、库存、限购与结算时机只定义实际存在的机制。 +- 交易前应能判断将付出和得到什么；失败时说明原因。一次交易的扣除与交付整体成功或失败，避免只扣钱却未给物。具体事务协议留给实现规格。 +- 价格变化存在时，说明影响因素以及玩家能看到的信息；不默认品质、渠道、时段或加工增值。 +- 货币与物品等正式状态的权威归属及跨系统请求，按架构明确，避免多处独立维护同一余额。 -## 本类型要点 -- 状态与规则核心是**记账三律**：货币只由本系统写入；他系统只能提交 - 合法请求；先校验后一次性完成扣增（不允许半途状态）。 -- 反馈：交易前显示单价/数量/总价/交易后余额；失败给具体原因； - **加工增值要能被玩家从界面理解**（防"看不见的经济"）。 -- 边界：不管物品定义与背包；不管任务判定；不做动态市场/玩家交易/ - 拍卖/多货币投机。 -- 典型开放问题：即时到账 vs 日终结算？库存模式？多渠道价格差异？ - -## 本类型自查 -- 有没有任何别家系统直接加减过钱？（记账三律被破坏=对账灾难） -- 玩家能从界面说清"为什么这个价"吗（品质/渠道/时段）？ +保留已确定的价格规则、参数和库存约束，交由 TDD 收编并补齐实现规格。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/10_经济与商店/模板.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/10_经济与商店/模板.md index 49d2e04ec..29f79e827 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/10_经济与商店/模板.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/10_经济与商店/模板.md @@ -1,74 +1,15 @@ -### C2 10_经济与商店/模板.md（→ modules/system-types/10_经济与商店/模板.md） - # __系统：S__（经济与商店类） -## 系统目的 -（本系统存在是为了 __；若删除它，__。） +按实际经济机制选取内容，删去不适用项；保留已确定的参数。 -## 支撑的玩家体验 -（对应顶层设计目标第 __ 条。） -- __ +## 价值流与玩家选择 -## 进入与退出 -### 进入 -- 进入商店/发起交易：__。 -### 退出 -- 完成交易/关闭界面：__。 +说明玩家为何交易、能选择什么，以及货币、物品或其他价值如何流动。 -## 玩家行动 -- 出售：__。 -- 购买：__。 -- 查看价格与库存：__。 -- 下订单（若有）：__。 +## 价格与交易规则 -## 取舍表 +记录实际存在的价格、库存、开放条件与结算时机；在交易流程中说明状态权威来源、与物品或其他系统的交接、扣除与交付整体成功或失败的结果，以及玩家看到的信息和失败原因。 -| 决策 | 立即收益 | 延迟收益 | 主要代价 | -|---|---|---|---| -| __ | __ | __ | __ | +## 实现交接 -## 状态与规则 -### 记账三律 -- 货币只由本系统写入。 -- 他系统只能提交合法请求（附事由与数量）。 -- 先校验后一次性完成扣增，不允许半途状态。 -### 价格规则 -- 定性结构：__（品质/渠道/时段如何影响价）。 -### 库存规则 -- 模式：有限 / 无限 / 周期补货：__。 -### 交易规则 -- 校验失败的原因表达：__。 - -## 数值与数据交接（→技术文档层） -本系统交由技术文档层定义的数据类别：价格表、货币表、商店表、商店库存表、订单表。 - -随交接附下的设计侧定性约束： -- __（如：初期基础物资可用少量日常产出购买；一次普通收获买不下最高阶升级） - -## 反馈 -- 交易前：单价/数量/总价/余额预览。 -- 交易后：余额与物品变化。 -- 失败：具体原因（钱不够/库存不足/未开放）。 -- 加工增值：界面可理解（原料价 vs 成品价）。 - -## 内部循环 -`获得物品 → 出售/加工决策 → 交易 → 资金 → 投资下一轮` - -## 输入、输出与依赖 -### 输入 -- 物品系统提供交易对象；时间系统提供营业时段。 -### 输出 -- 向物品系统提交交易结果；向全部系统提供资金查询。 -### 依赖 -- __ - -## 边界与非目标 -- 不管物品定义与背包 → 移交物品系统。 -- 不管任务判定 → 移交任务系统。 -- 不做动态市场/玩家交易/拍卖/多货币投机。 -- 不负责字段定义、数值配置与表格结构——归技术文档层（数值策划）。 - -## 开放问题 -- 即时到账还是日终结算？ -- 库存模式？ -- 多渠道价格差异？ +将已确定的价格、数量、交易结果和约束交由 TDD 收编并补齐设计缺口；内部字段、数据结构和事务实现由施工方决定。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/11_事件与节日/SKILL.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/11_事件与节日/SKILL.md index f311ce52b..72008432e 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/11_事件与节日/SKILL.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/11_事件与节日/SKILL.md @@ -1,26 +1,12 @@ -### C2 11_事件与节日/SKILL.md（→ modules/system-types/11_事件与节日/SKILL.md） +# 事件与节日 ---- -name: gdd-sys-11-events-festivals -description: 写"事件与节日"类系统文档时使用。与 skills/systems.md 配套。 - 配套模板：modules/system-types/11_事件与节日/模板.md。 ---- +按实际内容选用本页与同目录的 `模板.md`；事件可以短暂、持续、循环或一次性，不必都依赖日历。 -# 事件与节日 · 系统写法 +## 值得确定的问题 -**定位**：把常规日暂时重组为共同体验的编排层。 +- 事件由什么触发，玩家怎样发现、进入、参与和退出？时间窗口只在玩法需要时定义。 +- 事件改变了哪些可用行动、场景或规则？涉及独立玩法时说明范围、所需系统与制作成本，不强制复用旧玩法。 +- 阶段、重复参与、错过和奖励领取如何处理？先确定目标体验，再决定是否需要补救路径。 +- 预告、进行中状态、结束结果及奖励条件怎样让玩家理解？状态和奖励的权威归属按架构协作。 -## 本类型要点 -- 进入与退出三段写全：触发条件（日期/季节/天气/任务）+ 参与入口 - （邀请/到场/选择）+ 窗口检查。 -- 反馈：提前预告（日历/信件/NPC）+ 入场说明（名称/主题/规则/时限）+ - 进度与可领奖励清晰区分。 -- **边界是本类型最重要的一节**：不管小游戏具体规则——小游戏必须调用 - 已有系统或另行立项；**不做大量一次性独立玩法，节日是范围失控的 - 头号来源**（meowa 原文级警示）。 -- 典型开放问题：占整天 vs 时段？小游戏模板复用还是独立设计？ - 错过奖励怎么补？ - -## 本类型自查 -- 每个节日复用了哪些已有系统？（全是新玩法 = 立项失控预警） -- 错过窗口的玩家有补救路径吗（防"必须查攻略"）？ +已确定的触发条件、时长、奖励与参数交由 TDD 收编并补齐实现规格。避免把活动主题直接当作技术或玩法边界。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/11_事件与节日/模板.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/11_事件与节日/模板.md index fb185c168..ab7c16be7 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/11_事件与节日/模板.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/11_事件与节日/模板.md @@ -1,70 +1,19 @@ -### C2 11_事件与节日/模板.md（→ modules/system-types/11_事件与节日/模板.md） - # __系统：S__（事件与节日类） -## 系统目的 -（本系统存在是为了 __；若删除它，__。） +按实际事件形态选取内容，删去不适用项；保留已确定的参数。 -## 支撑的玩家体验 -（对应顶层设计目标第 __ 条。） -- __ +## 体验与参与路径 -## 进入与退出 -### 触发条件 -- 日期/季节：__。 -- 天气/任务等附加条件：__。 -### 参与入口 -- 邀请/到场/选择：__。 -### 窗口检查 -- 开始/结束时刻与错过处理：__。 +说明事件的目的、触发和发现方式，以及玩家进入、参与、退出的过程。 -## 玩家行动 -- 查看预告与日历：__。 -- 到场参与：__。 -- 领取奖励：__。 +## 阶段与结果 -## 取舍表 +记录实际阶段、条件、参与规则、结束和错过处理；说明事件影响哪些系统及奖励如何交接。 -| 决策 | 立即收益 | 延迟收益 | 主要代价 | -|---|---|---|---| -| __ | __ | __ | __ | +## 玩家信息 -## 状态与规则 -### 事件结构 -- 类型与主题：__。 -- 阶段：__（开始/进行/结算）。 -- 重复参加规则：__。 -### 复用声明 -- 本事件调用的已有系统：__（如战斗/采集/社交）。 +说明预告、当前可做的事、进度和结算结果如何呈现；独立玩法的范围与成本按需说明。 -## 数值与数据交接（→技术文档层） -本系统交由技术文档层定义的数据类别：事件表、事件阶段表、事件条件表。 +## 实现交接 -随交接附下的设计侧定性约束： -- __（如：错过窗口有补救路径） - -## 反馈 -- 提前预告：__（日历/信件/NPC）。 -- 入场说明：名称/主题/规则/时限。 -- 进度与可领奖励：清晰区分。 - -## 内部循环 -`预告 → 到场 → 参与（复用已有系统）→ 结算奖励 → 回到常规日` - -## 输入、输出与依赖 -### 输入 -- 时间系统提供日期季节；任务/关系系统提供触发条件状态。 -### 输出 -- 向各系统临时改变可用活动或奖励；向物品/经济系统提交奖励入账。 -### 依赖 -- __ - -## 边界与非目标 -- 不管小游戏具体规则——小游戏必须调用已有系统或另行立项。 -- 不做大量一次性独立玩法（节日是范围失控的头号来源）。 -- 不负责字段定义、数值配置与表格结构——归技术文档层（数值策划）。 - -## 开放问题 -- 占整天还是时段？ -- 小游戏模板复用还是独立设计？ -- 错过奖励怎么补？ +列出已确定的条件、时长、奖励、参数与待补规格，由 TDD 收编并补齐实现所需定义。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/12_UI与文本呈现/SKILL.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/12_UI与文本呈现/SKILL.md index 4b1d2e979..f34ba3d58 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/12_UI与文本呈现/SKILL.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/12_UI与文本呈现/SKILL.md @@ -1,28 +1,12 @@ -### C2 12_UI与文本呈现/SKILL.md（→ modules/system-types/12_UI与文本呈现/SKILL.md） +# UI 与文本呈现 ---- -name: gdd-sys-12-ui-text -description: 写"UI 与文本呈现"类系统文档时使用。与 skills/systems.md 配套。 - 配套模板：modules/system-types/12_UI与文本呈现/模板.md。 ---- +按实际界面选用本页与同目录的 `模板.md`。本类型负责交互、导航、信息层次、临时界面状态与文本呈现；正式玩法规则仍由对应系统负责。 -# UI 与文本呈现 · 系统写法 +## 值得确定的问题 -**定位**：规则系统的"可读化"层，不拥有任何规则。 +- 玩家在什么场景需要哪些信息和操作？可用界面清单记录入口、主要信息、操作及去向，但不要求每个项目都有 HUD 或固定面板。 +- 导航、焦点、展开收起、预览、确认和错误恢复怎样工作？临时 UI 状态与正式业务状态如何衔接？ +- 关键规则、限制、失败原因与操作结果如何被理解？考虑输入方式、屏幕尺寸、可访问性和文本语境，不预设视听文三通道齐备。 +- 界面展示的正式数据来自哪里，操作送往哪个规则系统？只读副本或快照说明来源及更新、恢复方式；不在 UI 文档另定业务结论。 -## 本类型要点 -- 状态与规则的核心是**界面清单表** `[界面|主要信息|主要操作]`—— - 逐界面枚举，本类型的主体工程。 -- 取舍表是本类型特色节：HUD 只显高优先级信息、详情进面板； - 关键失败原因不许藏；预览帮比较但不给唯一推荐。 -- 反馈：同一事件的视听文本三通道一致性；信息分层 - （立即可见/悬停/进面板）。 -- 边界：不拥有任何规则；**重要规则不许只放在图标/颜色/动画里而不给 - 可读文本**；不做商城/运营界面。 -- 典型开放问题：键鼠+手柄是否共用布局？摘要可否展开明细？ - 地图隐藏信息的尺度？ - -## 本类型自查 -- 每个界面的"主要信息"都能追溯到某系统的公开状态吗？ - （追溯不到 = 在无中生有地展示） -- 关键规则的文本表达找得到了吗（不藏在颜色图标里）？ +推荐、商城或运营界面是否存在由产品范围决定。已确定的交互参数、文本和数据需求交由 TDD 收编并补齐实现规格。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/12_UI与文本呈现/模板.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/12_UI与文本呈现/模板.md index edc9dc909..e72c11836 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/12_UI与文本呈现/模板.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/modules/system-types/12_UI与文本呈现/模板.md @@ -1,75 +1,15 @@ -### C2 12_UI与文本呈现/模板.md（→ modules/system-types/12_UI与文本呈现/模板.md） +# __系统：S__（UI 与文本呈现类） -# __系统：S__（UI 与文本呈类） +按实际界面选取内容，删去不适用项；保留已确定的参数。 -## 系统目的 -（本系统存在是为了 __；若删除它，玩家读不懂任何系统状态。） +## 使用场景与界面 -## 支撑的玩家体验 -（对应顶层设计目标第 __ 条。） -- __ +说明玩家的任务、进入与离开方式。按需列出界面、主要信息、操作和导航去向，就近注明正式玩法状态和规则来自哪个系统、操作交给谁处理。 -## 进入与退出 -### 进入 -- 打开各界面/触发提示：__。 -### 退出 -- 关闭界面/提示消散：__。 +## 交互与呈现规则 -## 玩家行动 -- 查看信息：__。 -- 执行操作：__。 -- 展开/收起详情：__。 +记录焦点、临时状态、预览、确认、错误恢复与信息层次；说明重要限制、结果和文本如何被玩家理解。必要时补充只读副本或快照的来源与更新方式，不另表复述已说明的数据来源和操作去向。 -## 取舍表（本类型特色节） +## 实现交接 -| 决策 | 立即收益 | 延迟收益 | 主要代价 | -|---|---|---|---| -| HUD 显示 __ 还是收进面板 | __ | __ | __ | -| 摘要直接给还是可展开 | __ | __ | __ | -| 预览给比较还是给唯一推荐 | __ | __ | __ | - -## 状态与规则 -### 界面清单 - -| 界面 | 主要信息 | 主要操作 | -|---|---|---| -| __ | __ | __ | - -### 信息分层规则 -- 立即可见（HUD）：__。 -- 悬停/点按：__。 -- 进面板：__。 -### 三通道一致性 -- 同一事件的视觉/听觉/文本表达一致：__。 - -## 数值与数据交接（→技术文档层） -本系统交由技术文档层定义的数据类别：文本表（全部玩家可见文本外置，含上下文与参数占位）、UI 提示表。 - -随交接附下的设计侧定性约束： -- 重要规则必须有可读文本，不许只放在图标/颜色/动画里。 -- 关键失败原因不许藏。 - -## 反馈 -- __ - -## 内部循环 -`状态变化 → 分层呈现 → 玩家读取 → 操作回传` - -## 输入、输出与依赖 -### 输入 -- 各规则系统提供公开状态与结果事件（只读）。 -### 输出 -- 向各系统回传合法操作（只经系统定义的行动入口）。 -### 依赖 -- __ - -## 边界与非目标 -- 不拥有任何规则（展示与操作回传，不判断）。 -- 重要规则不给可读文本即为缺陷。 -- 不做商城/运营界面。 -- 不负责字段定义、数值配置与表格结构——归技术文档层（数值策划）。 - -## 开放问题 -- 键鼠+手柄是否共用布局？ -- 摘要可否展开明细？ -- 地图隐藏信息的尺度？ +列出已确定的交互参数、文本需求和待补规格，由 TDD 收编并补齐实现所需定义。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/architecture.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/architecture.md index f33f15cfb..1f40e971d 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/architecture.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/architecture.md @@ -1,171 +1,45 @@ -## A3 系统架构分册（game-gdd-architecture） - ---- -name: game-gdd-architecture -description: 写游戏策划案（GDD）系统架构时使用。在顶层设计定稿之后， - 把顶层的系统范围表正式切成 Sxx 系统：编号、职责、依赖、数据流、优先级， - 并向系统文档交付目录映射与 MVP 闭环。配套：templates/architecture.md、 - templates/analysis.md（全局一份）、exemplars/stardew-architecture.md、templates/stardew-analysis.md（全局一份）。 ---- - # 系统架构写法（策划 · 系统架构分册） -> 本文件是系统架构层唯一承载写作流程的教学件。 -> 模板与例子文件保持纯净：不含任何步骤、检验提示与标记。 +产物：`project/02_architecture/design.md`。 +参考资源：`templates/architecture.md`、`exemplars/stardew-architecture.md`；全局分析文档的模板与样例：`templates/analysis.md`、`templates/stardew-analysis.md`。 -## 〇、结构适配原则 +## 判断立场 -根据游戏类型、项目规模、用户要求和顶层设计选取本分册的适用内容，同类项可合并；复杂项目可以拆分补充，简单项目可以压缩为最小可用架构。 +将已确定的玩法与版本范围划分为职责清晰的系统，说明系统如何协作、谁维护关键数据，以及后续系统文档从哪里展开。 -## 一、这一层的判断立场 -你是架构师，切系统的刀在你手里。在这个层里你相信： -- 为需要独立职责、状态或数据边界的部分拆分系统，使其**职责清晰、可独立讨论**；每个实际拆出的系统应能说明删除后的影响。 -- **数据所有权唯一**：同一事实只由一个系统维护，其他系统只引用稳定 ID， - 不复制主数据。两个系统管同一件事 = 架构事故。 -- **依赖无环**是硬要求；信息呈现层只读状态、只经行动入口写入。 -- 架构是全项目返工最多的一份（实测 11 版 vs 概念层 2 版）——所以每次改刀 - 都要写变更记录，让"为什么这么切"可追溯。 -- 你不越层：上不重定义玩法循环（那是顶层的），下不写单系统内部规则 - （那是系统文档的），字段定义与数值配置归技术文档层（数值策划）。 +按职责、状态和数据边界决定拆分或合并，不预设系统数量，也不要求每个系统都属于首个可玩版本。同一事实应有明确的权威维护方，避免多处独立定义或修改。不把自己的建议写成用户已经作出的决定。 -## 二、动笔前 -1. 顶层设计已定稿可用——把它的**系统范围表**（粗清单）和**顶层定稿约束** - 摊开当输入；切分是对粗清单的正式化（拆、并、裁都在这层做）。 -2. 读取 exemplars/stardew-architecture.md 了解内容组织方式， - 然后往 templates/architecture.md 里填。 -3. 记住顶层的核心循环图——切完必须跑覆盖检查。 +拆分应带来有用的独立规则边界。仅因变量不同、操作不同或未来可能替换，不必单独设系统；同一玩法流程中的简单职责可以在一个系统内部说明，不为每项职责分配独立编号或增加请求、通知与确认层。 -## 三、架构设计的组织维度：写什么、为什么、怎么咬合 +## 动笔前 -架构文档回答四个问题： -**这个架构为什么这样切（1~3）→ 系统是什么、怎么连接（4~6）→ -怎么落地、怎么验证（7~11）→ 还有什么没想清（12）。** +结合已获批的 `project/01_top_design/design.md`、概念设计、已有对话和项目资料开展设计，模板与样例按需参考。承接实际玩法、能力范围、版本边界与验证计划，不要求顶层清单逐项对应独立系统。 -第 1 节承顶层的定稿约束开篇，MVP 闭环在中间当守门员，开放问题收尾。 +发现已确定的玩法或范围与新的约束冲突时，说明影响并讨论相关决定；发现划分问题时，调整受影响的职责与协作关系。 -| # | 节 | 是什么 | 为什么写 | 和谁咬合 | -|---|---|---|---|---| -| 1 | 架构定位与目标 | 阶段边界（定哪些系统、不展开内部）+ 划分原则 + 一句话架构 + **变更记录** | 防止架构漂离顶层；改刀可追溯 | 承顶层定稿；变更记录引登记编号 | -| 2 | 系统地图 | Sxx 编号清单（=系统文档范围真源）+ 支撑层 + P0 段五列表（目的/输入/输出/P0原因） | 编号让系统可引用；P0 原因逼答"删了塌什么" | **对下真源**：Sxx ↔ 04 系统文档一一对应 | -| 3 | 系统职责 | 职责表（负责/不负责→移交谁）+ 逐系统说明段 | 边界写死，防两个系统管同一件事 | 系统文档的"边界与非目标"必须与此对齐 | -| 4 | 依赖与数据流 | 依赖图（无环）+ 数据流图 + 主要状态 + 主数据归属规则 | 谁读谁、数据从哪到哪——接口的真源 | 顶层的资源流图在此展开成系统级 | -| 5 | 核心循环覆盖检查 | 顶层每个循环环节 → 认领系统 | 顶层→架构的验收线，防切系统切碎循环 | 对上接口：逐环节对照顶层循环图 | -| 6 | 目录映射 | 职责 → 物理文档目录的归并表 | 职责数≠文档数；归并规则显式化 | **对下接口**：系统文档照此开工 | -| 7 | MVP 最小闭环 | 编号验证链 + 守门句（"闭环不成立不许加东西"） | 立项后第一条要跑通的链 | 对应顶层验证标准；失败回顶层而非加系统 | -| 8 | 统一数值基准 | 单位清单 + 四类定性基准（时间/货币/成长/体力风险的风格约束） | 各系统单独配数值会互相失衡；先定全局尺度 | **数值换算与验算归技术文档层**，此处只到定性 | -| 9 | 系统边界 | 哪些功能明确不属于任何系统/归引擎层/归呈现层 | 显式排除，防范围蔓延 | 承概念层"不是什么" | -| 10 | 优先级与范围 | P0/P1/P2 三档（P1/P2 可用能力表） | 拆分≠全做；裁剪顺序显式化 | P0 = MVP 闭环的系统集 | -| 11 | 风险与校验 | 风险/校验方式表 | 架构级风险提前挂出，每条带检验法 | 对应顶层验证标准与概念层跑偏风险 | -| 12 | 开放的结构问题 | 结构级未定案 | 显式债务 | 进分析文档或系统文档开题 | +## 内容组织 -咬合一图： +根据项目实际复杂度选择组织方式，同类内容可以合并，复杂部分可以拆分。以下是需要覆盖的信息，不是必须分别填写的章节；职责、数据归属和文档位置可合写，已说清的事实不再另建表复述。不适用的内容省略，有意义但信息不足的内容保留已知信息与待补问题。 -``` -顶层定稿 + 系统范围表（粗清单） - ↓ 正式切分（拆/并/裁） -1 定位与目标 ──► 2 系统地图（Sxx 真源）──► 3 职责表 - ↓ ↓ ↓ -5 循环覆盖检查 ◄── 4 依赖与数据流（接口真源） - ↓ -6 目录映射 ──► 7 MVP 最小闭环（守门员） - ↓ -8 数值基准（定性）· 9 边界 · 10 优先级 · 11 风险校验 - ↓ -12 开放问题 →（进分析文档 / 系统文档开题） -``` +- **系统与职责**：为系统保留 Sxx 编号，说明支撑的玩法能力、负责的状态或规则，以及当前版本包含的部分。容易混淆的职责再说明由谁负责，不要求每个系统填写相同的排除项。 +- **协作与数据归属**：说明关键行动经过哪些系统、传递什么信息、由谁确认和更新结果。区分调用依赖、事件通知、数据读取与玩法反馈；使用图时说明箭头含义。双向交互或资源循环不等于错误，重点检查循环调用、职责纠缠和更新顺序不清等实际问题。 +- **共享状态与约束**：明确关键状态、主数据的权威维护方，以及实际需要跨系统统一的单位、规则和参数。系统间通过稳定标识引用对象；只读副本、派生视图和存档快照应说明来源及更新或恢复方式，不成为独立维护的另一套事实。呈现层展示状态并通过行动入口发起修改。 +- **系统文档映射**：说明各系统的文档位置，使用 `project/03_systems/...` 路径。多个职责可以合并成文档，复杂系统也可以拆分说明，只要编号、职责和位置对应清楚。策划文档的组织不决定代码目录，具体代码组织由施工方按工程约束选择。 +- **实现范围与验证**：承接顶层已确定的版本与原型范围，说明先实现哪些能力、依赖哪些协作，以及用什么可玩流程验证；已有验证计划引用并补充架构特有的问题，不重复展开。可以只实现某系统的一部分，不固定优先级档位或流程跨度。范围外内容不自动安排后续版本或扩展方案，已确定且影响当前设计的后续要求按需说明。验证出现问题时，依据原因调整玩法、系统划分或实现，不预设必须退回某一层。 +- **风险与未决问题**：保留影响系统边界、协作或范围的实际问题，说明影响及解决或验证方式。影响当前架构成立的问题应先解决，其他问题按需要留给后续展开。 -三个接口：**对上**承顶层系统范围表并跑循环覆盖检查；**对内**地图↔职责↔依赖 -三方一致、主数据归属唯一；**对下**目录映射 + MVP 闭环喂系统文档。 +## 展开深度 -## 四、怎么写（模板参考结构，建议按此组织） -（本节是带写法要领的教学版；实际填写的纯净模板在 templates/architecture.md） +写清判断系统划分与协作所需的信息，保留影响跨系统结果的顺序、约束及必要的规则或参数。架构概述关键协作，详细行为流程在主要负责的系统文档展开，其他位置按需摘要和引用，不多处复写全流程。TDD 收编并补齐设计要求、内容与数值及实际工程约束，内部实现由施工方决定；不因分层删去已定且影响架构的信息，也不以去重为由省略 TDD 独立施工所需内容。 -### 1. 架构定位与目标 -本阶段确定"哪些系统支撑一轮玩法"，不展开单系统内部规则。 -划分原则：__。一句话架构： -> （玩家通过哪些系统、以什么因果，把一轮玩法的输入变成下一轮的选择） -变更记录：日期 + 改了什么 + 为什么（引登记编号）。 -→ 没有变更记录的架构文档，第二轮迭代就会变成黑箱。 +## 分析参考 -### 2. 系统地图 -Sxx 编号清单（核心系统通常 1-5 个，有明确要求可超出 5 个）+ 支撑层（存档/UI，不拥有核心规则）。 -P0 段五列表： -| 系统 | 目的 | 输入 | 输出 | P0 原因 | -→ 对实际拆出的系统说明删除后的影响；无法形成独立职责的部分合并，不为满足数量新增系统。 +可关注系统拆分、接口和数据归属中的重要取舍，按需保留依据与当前结论，不逐次记录修改流水。按需参考 `templates/analysis.md` 和 `templates/stardew-analysis.md`。 -### 3. 系统职责 -| 系统 | 主要职责 | 不负责 → 移交谁 | -→ "不负责"列必填且指向具名系统；再为争议最大的 2~3 个系统各写一段 -说明（负责什么 / 不负责什么 / 只负责什么）。 +## 交付检查 -### 4. 依赖与数据流 -依赖图（mermaid，呈现层用虚线"读取状态"）+ 数据流图（资源从产到耗）。 -主要状态：全局/玩家/场景/社会 四类。 -主数据归属规则：规则与数据表分工 / 稳定 ID 关联 / 任何系统不复制他系统主数据。 -→ 依赖图出现环 = 回去重切。 - -### 5. 核心循环覆盖检查 -| 顶层循环环节 | 认领系统 | -→ 逐环节对照顶层循环图；有环节无人认领或多人认领都是切分错误。 - -### 6. 目录映射 -| 目录 | 本阶段定位 | -→ 职责可以归并进同一文档目录（官方版 8 职责→3 文档）；归并规则写明。 -系统文档以此开工：地图上没有的系统不许有文档。 - -### 7. MVP 最小闭环 -1. __ 2. __ …（编号验证链，一条玩家可走的完整因果） -守门句：如果这条闭环不成立，不应继续增加 __。 -→ 闭环失败回顶层改设计，不是加系统打补丁。 - -### 8. 统一数值基准（定性） -全局单位清单（如时间片/游戏日/货币/体力/经验）+ 四类风格约束 -（时间节奏/货币量级感/成长回报取向/体力风险档位）。 -→ 只写到定性；具体换算、验算数值由技术文档层（数值策划）承接。 - -### 9. 系统边界 -明确排除项（不拆出独立 __ 系统 / __ 归引擎层 / __ 归呈现层）。 - -### 10. 优先级与范围 -P0（最小闭环必需）：__；P1（完整体验）：__；P2（扩展内容）：__。 -P1/P2 可用能力表（能力/说明）控制颗粒度。 - -### 11. 风险与校验 -| 风险 | 校验方式 | -→ 从概念层跑偏风险和顶层失败档位反推；校验方式要可观察。 - -### 12. 开放的结构问题 -→ 结构级（接口归属/统一格式/合并拆分）才留这里；数值细节不留。 - -## 五、分析文档（全局一份，按层分节） - -**全局共用 `project/analysis.md`**：论证按发生层归节，决定登记表全项目共用， -跨层引用查这里。模板与例子：资源 `templates/analysis.md`、 -`templates/stardew-analysis.md`。已决论证与登记写入分析文档， -灵感池、代决、待原型等活队列写入决策台账。 - -- 条目格式：`## 问题：<一句话>` ＋ 状态（agent_proposal / user_confirmed / - superseded，登记 D-__）＋ 广度分析（牵动面＋候选 ≥2）＋ 深度分析 - （逐候选利弊依据，必须引 T 原则/锚点/张力编号，写不出依据的偏好不进分析） - ＋ 综合判断（建议取 __ 因为 __；推翻条件：__）。 -- 分诊三条件全满足才进：① 影响项目方向或边界；② ≥2 合理候选；③ 一时定不了。 - 不满足的：就地小权衡直接进登记表一行，不写条目。 -- 本层标准问题：结构级争议——接口统一、系统归并、主数据归属划分。 -- 数量纪律：按需；架构期问题多为接口与归属二义。 -- user_confirmed 后三件事：结论一句话迁入 design.md 对应节（留修订痕迹）； - 登记表加行（编号全项目连续，跨层引用写 D-__）；本条目改状态记 D 号保留不删。 - 推翻时新增行挂旧行编号，旧行不删。 - - -## 六、自查参考 -- 每个 Sxx 都能一句话答"删了它什么塌"吗？ -- 顶层的循环环节全覆盖、无重复认领吗？ -- 依赖图无环？主数据无一物两管？ -- 系统文档拿到目录映射能直接开工吗？ -- 有没有字段定义或数值配置偷偷写进来？（该在技术文档层） -- 变更记录补了吗——这次切分和上次的差异说得清吗？ - -## 七、红线（只有三条） -1. 不冒充用户决定：用户没说的方向标"待确认"，正文不写死。 -2. 不越层：向上不翻顶层的案，向下不写系统内部规则，数值字段归技术文档层。 -3. 不凑数：系统数量不是成绩，写不出 P0 原因的系统就是该删的系统。 +- 当前范围的玩法能力是否覆盖完整，系统职责与协作是否清楚，有无遗漏或重复维护。 +- 关键状态和主数据是否有明确的权威维护方，交互中的信息与更新顺序能否理解。 +- 版本与原型范围是否一致，各验证流程所需的系统能力是否都已纳入对应范围。 +- 系统编号与文档位置是否清楚，是否足以继续展开系统设计。 +- 是否因过细拆分增加无用的协作说明，是否用多段或多表重复同一事实，或把尚未确定、尚未验证的内容写成定论。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/concept.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/concept.md index b2e8b1fb2..7b231cfcf 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/concept.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/concept.md @@ -1,163 +1,44 @@ -## A1 概念层分册（game-gdd-concept） - ---- -name: game-gdd-concept -description: 写游戏策划案（GDD）概念层时使用。把一句话游戏想法写成一份 - "一次写对、之后不动"的立项概念文档——它是后续所有设计争议的仲裁依据。 - 任何游戏类型通用。配套：templates/concept-design.md、templates/analysis.md（全局一份）、 - exemplars/stardew-concept.md、templates/stardew-analysis.md（全局一份）。 ---- - # 概念层写法（策划 · 概念层分册） -> 本文件是概念层唯一承载写作流程的教学件。 -> 模板与例子文件保持纯净：不含任何步骤、检验提示与标记。 +产物：`project/00_concept/design.md`。 +参考资源：`templates/concept-design.md`、`exemplars/stardew-concept.md`；全局分析文档的模板与样例：`templates/analysis.md`、`templates/stardew-analysis.md`。 -## 〇、结构适配原则 +## 判断立场 -根据游戏类型、项目规模、用户要求和上层已定范围选取本分册的适用内容，同类项可合并；复杂项目可以拆分补充，简单项目可以压缩为最小可用规格。 +- 聚焦游戏的核心体验和主要吸引力，为后续设计提供依据。 +- 用具体的玩家行为、情境和感受说明设计，避免空泛描述。 +- 不把自己的建议写成用户已经作出的决定。 -## 一、这一层的判断立场 -你是资深游戏策划，看过上千份概念案，清楚绝大多数死在"什么都说、什么都不尖"。 -在这个层里你相信： -- 概念的成败在取舍，不在丰富：一句话里卖点只许有一个。 -- 你写的是裁判文档：后续每一层的设计争议，都要能回到这里找到仲裁。 -- 具体压倒抽象："压力很大"是废字，"每开一扇门都在烧自己的命"才是概念。 -- 用户没说过的话不当他说过：宁可标"待确认"，不替人拍板。 -- 发现自己在堆形容词 = 概念没想清楚：停笔回去问，别用空话盖过去。 -- 概念层是"一次写对、之后不动"的层（实作中它的返工率远低于架构与 - 系统层），所以判断力要前置堆足，不要指望后面回来改。 +## 动笔前 -## 二、动笔前 -1. 拿到用户真实回答过的定调信息（参照对象、题材偏好、压力档位）。 - 没有 → 先问一个定调问题，禁止自问自答充当用户。 -2. 读取 exemplars/stardew-concept.md 了解内容组织方式， - 然后往 templates/concept-design.md 里填。 -3. 零参照时在文档头注明"零参照"。 +结合已有对话、用户资料和项目文档开展设计。信息不足时，判断是否影响当前概念的成立或关键方向，再决定需要补问什么；可以依据已有信息推进的部分先完成。 -## 三、概念设计的组织维度：写什么、为什么、怎么咬合 +模板和样例按需参考。参照有助于沟通时，说明具体借鉴什么；不能把参照作品的其他设计自动视为用户选择。 -概念文档回答四个问题： -**这是什么（1~5）→ 它不是什么（6）→ 它靠什么让人一直玩（7）→ -它管到哪、交出什么（8~9）。** +## 内容组织 -第 1 节是全案的压缩态，第 9 节是全案的判断态重述，首尾呼应； -中间各节从"设计锚点"这个枢纽长出来，争议又都回头接受它的仲裁。 +概念设计明确核心体验、主要吸引力和重要边界，作为后续玩法与系统设计的依据。根据游戏类型、项目规模和用户要求组织内容，可以合并、拆分或省略不适用的部分。 -| # | 节 | 是什么 | 为什么写 | 和谁咬合 | -|---|---|---|---|---| -| 1 | 一句话概念 | 全案压缩成一句：品类+融合+唯一卖点 | 概念的第一命运是被转述；这句立不住，后面写得再好都救不回来 | 9 是它的重述；2 是它的展开 | -| 2 | 定调与设计锚点 | 定调记录（参照/滑杆/T 原则，调性真源）+ 六个仲裁位：幻想/体验/动机/循环/跑偏/非目标 | 概念层把调定死：后续所有开放问题先回定调记录级联（约八成可就地定），级联不掉的才上决策卡；概念文档的核心职能是当裁判 | **全文档枢纽**：3~6 由它长出；7 由它的循环与动机抽出；定调记录被顶层及以下所有层引用 | -| 3 | 玩家身份与基调 | 玩家在虚构里是谁 + 情绪温度与红线 | 幻想需要一张脸和一种温度，否则是空话；基调边界句防调性漂移 | 身份 = 幻想的具象化；基调 = 目标体验的情绪面 | -| 4 | 风格与世界观 | 支撑玩法的世界规则 + 叙事载体 | 世界观是给玩法供氧的背景板，不是设定集 | 服务 3 的身份与基调；世界规则支撑 2 的核心循环成立 | -| 5 | 目标玩家与情境 | 为谁、什么场景、门槛多高 | 同一设计对不同人是不同游戏；受众映射防止"谁都适合=谁都不适合" | 反面校验 2 的目标体验；情境（一局多久）给 7 的循环定参数 | -| 6 | 不是什么 | 负面定位表：不是 X，因为 Y | 正面定义写多必然发散；负面定位用"误会方向+封死原因"收边界，比光秃的非目标锋利一档 | 2 的非目标与跑偏风险的表化展开；与 5 的防串味声明呼应 | -| 7 | 核心张力 | 玩家持续面对的两难，两端各有代价 | 长期游玩的根本动力；没有张力，再丰富的内容玩几次就腻 | **向下接口**：每条张力必须在顶层变成取舍表里的具体决策 | -| 8 | 边界与约束 | 本层只定什么、什么留给后面 + 规模回流 | 防止概念层越层写数值和系统（越层是下游返工之源）；给写作画线 | 保护 2 的纯度；告诉顶层"你们的地盘从哪开始" | -| 9 | 概念定稿 | "核心不是 __ 而是 __"重述 + 按需记录给顶层的约束 | 收口并检查概念是否写散；把承诺转成对下的契约 | 回环呼应 1；把边界和交接约束传给下一层 | +- **游戏概念**：简洁说明游戏是什么、玩家做什么、吸引力在哪里。多个特点可以共同支撑核心体验。 +- **体验与玩法**：说明玩家在什么情境下感到什么、为什么愿意继续，以及主要行动如何形成游玩过程。存在重要取舍时，说明选择及代价。 +- **身份、基调与世界观**：有助于理解游戏时，说明玩家身份、情绪基调、风格和必要的世界规则。叙事载体按项目需要展开。 +- **目标玩家与情境**：说明面向哪些玩家、适合怎样的游玩情境，以及体验门槛。 +- **边界与约束**：说明容易混淆的方向、排除理由和实际的跑偏风险；依据团队与项目条件确定规模。后续设计需要遵守的约束在相关内容中写清，无需结尾重复定稿。 -咬合一图： +设计原则用自然语言说明对本项目的实际影响。它们帮助判断方向，不能替代具体问题的分析。 -``` - 1 一句话概念（压缩态） - ↓ 展开 - 2 设计锚点（枢纽 · 仲裁位）◄── 所有节的争议回来找它 - ├→ 3 身份基调 ──→ 4 风格世界观（给玩法供氧） - ├→ 5 目标玩家（反面校验）──→ 6 不是什么（负面收边） - └→ 7 核心张力（动力结构）──→ 【交给顶层】取舍表 - 8 边界与约束（画线：本层到此为止） - ↓ 回环 - 9 概念定稿（判断态重述 + 交接契约） -``` +## 展开深度 -记住三个接口：**对内**锚点仲裁一切；**对下**张力变取舍表、定稿变硬约束； -**对上**边界画线防止越层。九节不是清单，是一台咬合的机器。 +围绕概念成立所需的信息展开。能够说明核心体验或重要约束的具体信息可以保留，包括必要的数值、操作方式和界面形式；详细系统规则、数值平衡和界面规格留待后续展开。 -## 四、怎么写（模板参考结构，建议按此组织） -（本节是带写法要领的教学版；实际填写的纯净模板在 templates/concept-design.md） +有意义但信息不足的内容，保留已知内容与待补问题；不为填满模板编造身份、世界观、张力或其他设定。 -### 1. 一句话概念 -《__》是一款 __（品类与融合）：玩家通过 __，把 __ 逐步 __。 -→ 45~90 字，卖点唯一。检验：删掉那个卖点句子依然成立，说明没写对。 +## 分析参考 -### 2. 定调与设计锚点（先定调，再立仲裁位） -**定调记录**（全项目调性真源，此节定死）： -- 参照选择：以 __ 为主、__ 学 __（参照即定调，选完调性随之而来）。 -- 调性滑杆：压力感/战斗比重/管理深度/叙事比重/节奏，各一档。 -- 调性锚 T 原则：按项目需要提炼并逐条具名（如"T2 不劝退——凡惩罚类问题默认取最轻档"）。 - 检验：每条 T 都能当一句 IF-THEN 用——"凡__类问题默认__"；写不出口径的 T 是空话。 - → 下游每个开放问题先来这里级联批量起草，级联不了的才升级提问。 -**设计锚点（六项，争议时的仲裁原则，全部具名）** -- 核心幻想：一句描述 + 一句玩家念头（引号写出玩家脑中的自言自语）。 - 检验：念头句写不出来 = 幻想没立住，回去重想，不要用描述糊弄。 -- 目标体验：何时感到什么。 -- 玩家动机：短期 __；长期 __。 -- 核心循环：__ → __ → __ → __ → 回到 __（箭头式）。 -- 跑偏风险：本项目可能的真实偏航，不放万金油。 -- 非目标：一行带过，详表见第 6 节。 +可关注核心体验的取舍，以及哪些范围扩张会稀释它。按需参考 `templates/analysis.md` 和 `templates/stardew-analysis.md`。 -### 3. 玩家身份与基调 -- 玩家身份：玩家在虚构里是谁 + 本项目的核心节奏，一口气说清。 -- 情绪基调：正面定调 + 边界句——"可以 __，不可以 __"。 +## 交付检查 -### 4. 风格与世界观 -世界观为 __（玩法）服务；叙事通过 __（载体）展开。禁编年史、种族志。 - -### 5. 目标玩家与情境（受众映射三件套） -- 与谁的受众重合；吸收了谁的什么需求；**为什么不会变成它**（防串味声明， - 参照越多越必须有这句）。 -- 情境与门槛：单人/多人；一局多久；需要理解 __，不应要求 __。 - -### 6. 不是什么（负面定位表） -| 不是 | 因为 | -→ 每行原因要封死一条具体误会方向（例：不是武器店经营｜武器主要拿去 - 战斗，不是卖给顾客）。从锚点的非目标与跑偏风险长出来，通常 4~6 行。 - -### 7. 核心张力 -- __ 有限，但 __。 -- __ vs __（两端的代价各是什么）。 -→ 如果项目存在核心张力，保留的每条张力都应说明双方代价；没有形成有效张力时，不为了满足结构新增张力。这些是顶层取舍表的种子，后面按需对应。 - -### 8. 边界与约束 -- 概念边界放首位：本层只定幻想、用户、基调与排除方向；具体数值、 - 系统清单、MVP 内容留给顶层及以后。 -- 规模与回流：单人可维护；所有系统回流核心循环。 -- 参照声明：学组织方式，不复制角色/文本/美术/数值。 - -### 9. 概念定稿（收口重锤） -这个游戏的核心不是 __，而是： -> （一句话重述核心承诺） -交给下一层的约束：按项目需要记录，顶层据此展开。 - -若某节对本项目没意义，直接省略。 - -## 五、分析文档（全局一份，按层分节） - -**全局共用 `project/analysis.md`**：论证按发生层归节，决定登记表全项目共用， -跨层引用查这里。模板与例子：资源 `templates/analysis.md`、 -`templates/stardew-analysis.md`。已决论证与登记写入分析文档， -灵感池、代决、待原型等活队列写入决策台账。 - -- 条目格式：`## 问题：<一句话>` ＋ 状态（agent_proposal / user_confirmed / - superseded，登记 D-__）＋ 广度分析（牵动面＋候选 ≥2）＋ 深度分析 - （逐候选利弊依据，必须引 T 原则/锚点/张力编号，写不出依据的偏好不进分析） - ＋ 综合判断（建议取 __ 因为 __；推翻条件：__）。 -- 分诊三条件全满足才进：① 影响项目方向或边界；② ≥2 合理候选；③ 一时定不了。 - 不满足的：就地小权衡直接进登记表一行，不写条目。 -- 本层标准两问：① 什么是本项目不可替代的核心承诺；② 什么内容扩张会稀释它。 -- 数量纪律：概念期问题通常 ≤3；开始堆第 4 问时先怀疑概念层没想清楚，重读定调记录而不是继续开新争议。 -- user_confirmed 后三件事：结论一句话迁入 design.md 对应节（留修订痕迹）； - 登记表加行（编号全项目连续，跨层引用写 D-__）；本条目改状态记 D 号保留不删。 - 推翻时新增行挂旧行编号，旧行不删。 - - -## 六、自查参考 -- 卖点唯一吗？念头句立得住吗？ -- 随便挑一个后续设计问题，锚点六项之一能当裁判吗？ -- "不是什么"表封死了最可能的误会方向吗？ -- 张力每条都两端有代价吗？ - -## 七、红线（只有三条） -1. 不冒充用户决定：用户没说的方向标"待确认"，正文不写死。 -2. 不越层：出现具体数值、按键、界面即删。 -3. 不凑数：章节对项目有意义但信息不足时，记录已确定内容与待补问题；章节对项目无意义时，直接省略。 +- 是否能理解玩家做什么、获得什么体验，以及主要吸引力。 +- 内容是否符合已有意图和约束，关键方向是否存在矛盾或缺口。 +- 是否为了填模板而编造内容、重复表述，或把尚未确定的方向写成定论。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/systems.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/systems.md index d361488b4..4b4ab9459 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/systems.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/systems.md @@ -1,106 +1,37 @@ -## A4 系统文档分册（game-gdd-system-doc） +# 系统文档写法（策划 · 系统文档分册） ---- -name: game-gdd-system-doc -description: 写单个系统的设计文档（Sxx）时的总纲——通用纪律、十二类常见内容、 - 红线与分析文档格式。每类系统的专属写法与模板在 modules/system-types/ 下对应目录的 SKILL.md - 与对应模块的模板.md 里，按需取用。 ---- +产物：按 `project/02_architecture/design.md` 的映射，在 `project/03_systems/...` 下维护系统文档，保留 Sxx 编号。 +参考资源：`modules/system-types/` 下各类型的 `SKILL.md` 与 `模板.md`；战斗样例 `exemplars/stardew-s06-combat.md`；分析模板与样例 `templates/analysis.md`、`templates/stardew-analysis.md`。 -# 系统文档写法（策划 · 系统文档分册 · 总纲） +## 动笔前 -> 本文件是系统文档层的总纲；各系统的专属写法在 `modules/system-types/` 下对应目录的 `SKILL.md`， - 专属模板在 `modules/system-types/` 对应目录的 `模板.md`。通用纪律不在各系统 skill 里重复。 +利用已有对话、已获批设计和项目资料，确认本系统的职责、协作、数据归属与当前范围。类型规则、模板和样例按需参考，可以组合使用，不必先把系统归入某一类型，也不从模板引入尚未采用的机制。 -## 〇、结构适配原则 +发现职责划分或已有规则有冲突时，说明影响并调整相关设计；涉及需要用户决定的重要方向时，先解决该选择。 -根据系统类型、实际复杂度、用户要求和架构职责选取本分册的适用内容，同类项可合并；复杂系统可以拆分补充，简单系统可以压缩为最小可执行规格。 +## 内容组织 -## 一、这一层的判断立场 -你是写单个系统的策划。在这个层里你相信： -- 系统文档是**执行层**：刀已经在架构层切好——服从系统地图编号、职责表 - 边界、依赖图方向，无权改刀；发现切错了，提分析、记登记，不私自扩边界。 -- 一个系统文档的成败在**边界节**："不负责什么、移交给谁"那几行是 - 防返工价值最高的几行。 -- 接口纪律：引用具名系统与具名数据，禁泛称；别家主数据只引 ID 不复制。 -- 字段定义、数值配置、表结构不归你——写交接声明，交技术文档层（数值策划）。 -- 系统文档保持基本可读的一致性，但不要求所有系统使用相同章节；结构应服从系统类型和实际行为。 +按实际行为和复杂度组织。以下是需要覆盖的信息，可在同一段行为流程中交代参与方、数据来源、处理顺序、结果和反馈；已讲清的内容不再另列协作表或反馈章节，只有新增信息较多时才单独展开。不适用的内容省略，有意义但信息不足的内容保留已知信息与待补问题。文字、列表、表格和图按表达需要选择，不要求统一章节、固定取舍表或循环层级。 -## 二、动笔前 -1. 架构已定稿：找到本系统的 Sxx 编号、职责表行、依赖方向——这是合同。 -2. 在 01~12 文件夹里选最接近的系统类型（可组合，如"钓鱼"=05 采集+06 战斗 - 的判定部分），读取对应的 `SKILL.md` 与 `模板.md`。 -3. 该文件夹标注"参考例子"的，可先读例子了解写法。 +跨系统流程在主要负责方的文档完整展开，其他参与方说明自身接收、处理和返回的内容，按需引用完整流程，不各自复述全链路。引用应能定位到相关文档或章节；影响本系统行为的前提和结果就近说明，避免只有跳转而无法理解规则。 -## 三、常见内容总览：写什么、为什么、怎么咬合 +- **职责与范围**：说明支撑的玩法能力、负责的规则和状态，以及本次展开的部分。按相关内容承接顶层与架构，不要求重复论证系统为什么存在。 +- **行为与规则**：说明行动或自动处理何时触发、需要满足什么条件、如何产生结果。交代重要状态变化、处理顺序，以及实际存在的失败、中断和恢复方式。有玩家选择时说明不同选择的后果。 +- **协作与数据**：在相关行为中明确交互的系统、对象和信息，谁校验、谁更新、谁接收结果。跨系统行动说明整体成功或失败时的预期结果，避免部分扣除或重复发放；简单同步处理直接说明顺序与结果，不为表达协作额外设计消息、确认或中间状态。主数据按架构归属维护，通过稳定标识关联；只读副本和快照说明来源及更新或恢复方式。 +- **反馈与操作**：说明玩家如何发起操作、看懂状态与结果，必要时解释不可用原因和恢复路径。没有直接操作的系统，说明其结果在何处体现，不编造玩家行动。 +- **验证与未决问题**：围绕关键规则、协作或体验说明代表性场景和判断依据；区别预期结果与已有验证结论。未决事项按影响说明原因和下一步，不限定为结构问题，也不把所有数值问题自动留给原型。 -系统文档回答四个问题： -**这个系统为什么存在（1~2）→ 玩家怎么用它（3~5）→ 它怎么运转（6~8）→ -它怎么和别人连接、不碰什么（9~12）。** +## 展开深度与交接 -| # | 节 | 是什么 | 为什么写 | 和谁咬合 | -|---|---|---|---|---| -| 1 | 系统目的 | 一句话：删了它什么塌 | 存在性检验 | 架构 P0 原因的展开 | -| 2 | 支撑的玩家体验 | 对应顶层目标第几条 | 防系统自嗨 | 顶层设计目标 ↔ 本系统 | -| 3 | 进入与退出 | 何时进入、何时/如何退出 | 循环的接口时刻 | 顶层的循环环节 | -| 4 | 玩家行动 | 具名动词组 | 玩家用手玩 | 系统类型卡给动词组 | -| 5 | 取舍表 | 玩家在本系统内的决策 | 张力在系统内的落地 | 概念张力→顶层取舍表→本表 | -| 6 | 状态与规则 | 对象/状态/转换/异常，枚举表达 | 定性规则真源 | 架构职责表对齐 | -| 7 | 数值与数据交接 | 本系统交 TDD 的数据类别+定性约束 | 分层边界 | 技术文档层承接 | -| 8 | 反馈 | 关键结果何时、以何种方式反馈 | 让实际结果可理解 | 与本系统实际结果对应 | -| 9 | 内部循环 | 本系统内的小循环 | 系统自己的心跳 | 顶层小循环的组成 | -| 10 | 输入、输出与依赖 | 消费/交付/依赖谁 | 接口真源 | 架构依赖图逐边对齐 | -| 11 | 边界与非目标 | 不负责什么→移交谁 | **防返工价值最高** | 架构职责表"不负责"列 | -| 12 | 开放问题 | 本系统未定案 | 显式债务 | 进分析文档 | +保留解释行为所需的规则、单位、已确定参数和实际契约，不因分层删去有用信息。TDD 收编并补齐设计要求、内容与数值及工程约束；数据结构、配置载体等内部实现由施工方决定，不在系统文档或 TDD 中为填模板预设。 -咬合：**对上**服从架构三条合同（编号/职责/依赖）；**对内**状态与接口不越 -职责边界；**对下**第 7 节交接喂 TDD。 +TDD 按当前施工范围收编所需行为，保留来源版本并随设计变化同步，施工方只看 TDD 应能完成该范围的实现。系统文档或外部分析不能代替 TDD 正文中的实现说明。 -## 四、常见内容的参考写法 -（各系统类型的特殊写法见对应文件夹 SKILL.md；纯净模板在其 模板.md） +重要取舍按需保留依据与当前结论，可参考分析模板与样例，不重复登记全部规则和未决事项。 -1 系统目的：若删除它，__ 会塌——一句话说不出 = 该系统不该存在。 -2 支撑体验：对应顶层目标第__条、调性原则第__条。 -3 进入与退出：按本系统实际存在的入口、退出和恢复路径记录。 -4 玩家行动：记录本系统实际存在的具名动词组；编排类写"安排"动词，活动类写"操作"动词。 -5 取舍表：决策/立即收益/延迟收益/主要代价；挂顶层张力编号。 -6 状态与规则：对象-状态-转换-异常，全部枚举表达，不许整段散文。 -7 数值与数据交接：列数据类别名 + 设计侧定性约束；字段定义归 TDD。 -8 反馈：记录本系统关键结果的可理解反馈；存在失败时说明原因和恢复路径。 -9 内部循环：动词链；可拆单次/区域/长期三层。 -10 输入输出与依赖：引用具名系统与具名数据，禁泛称"资源"。 -11 边界与非目标：参考该类型系统写法的“三不”说明边界；建议说明字段与数值的交接边界。 -12 开放问题：结构级才留；手感数值类标"待原型验证"。 +## 交付检查 -## 五、分析文档（全局一份，按层分节） - -**全局共用 `project/analysis.md`**：论证按发生层归节，决定登记表全项目共用， -跨层引用查这里。模板与例子：资源 `templates/analysis.md`、 -`templates/stardew-analysis.md`。已决论证与登记写入分析文档， -灵感池、代决、待原型等活队列写入决策台账。 - -- 条目格式：`## 问题：<一句话>` ＋ 状态（agent_proposal / user_confirmed / - superseded，登记 D-__）＋ 广度分析（牵动面＋候选 ≥2）＋ 深度分析 - （逐候选利弊依据，必须引 T 原则/锚点/张力编号，写不出依据的偏好不进分析） - ＋ 综合判断（建议取 __ 因为 __；推翻条件：__）。 -- 分诊三条件全满足才进：① 影响项目方向或边界；② ≥2 合理候选；③ 一时定不了。 - 不满足的：就地小权衡直接进登记表一行，不写条目。 -- 本层标准问题：① 本系统与相邻系统的边界在哪；② 本系统内部哪个规则影响顶层取舍。条目标系统号（如 S06）。 -- 数量纪律：按需；每系统通常 0~1 条，超了先回读架构职责表。 -- user_confirmed 后三件事：结论一句话迁入 design.md 对应节（留修订痕迹）； - 登记表加行（编号全项目连续，跨层引用写 D-__）；本条目改状态记 D 号保留不删。 - 推翻时新增行挂旧行编号，旧行不删。 - - -## 六、自查参考 -- 目的一句话成立吗？边界节和架构职责表逐行对齐吗？ -- 输入输出和依赖图逐边对上吗？有没有泛称漏网？ -- 状态是枚举还是散文？失败路径给了原因和恢复吗？ -- 有没有字段或数值偷偷写进来？（该在 TDD） -- 同构检查：另一份系统文档的读者能按同样方式读这份吗？ - -## 七、红线（只有三条） -1. 不冒充用户决定：用户没说的方向标"待确认"，正文不写死。 -2. 不越层：不翻架构的案（要改走分析文档+登记表），不写字段数值（归 TDD）， - 不替别的系统定规则。 -3. 不凑数：写不出"删了塌什么"的系统直接删除；章节对项目有意义但信息不足时，记录已确定内容与待补问题。 +- 当前范围的主要行为、重要失败或中断后的结果是否清楚，是否有影响交付的缺口。 +- 职责、数据归属与跨系统更新是否一致，反馈是否符合实际结果。 +- 已确定的信息是否保留，未决事项是否说明影响及处理方式，是否把建议或未验证预期写成定论。 +- 系统编号、文档位置和相关设计是否一致，是否为了填模板增加了无关机制或重复内容。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/tdd.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/tdd.md index 9a9ca73af..6270cba29 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/tdd.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/tdd.md @@ -1,115 +1,38 @@ -## A5 技术文档分册（game-tdd） +# 技术文档写作规则 ---- -name: game-tdd -description: 写游戏技术文档（TDD）时使用的总纲。GDD 四层定稿后的第五步：把 - "怎么做"写实——程序怎么写、美术怎么做、字段怎么定义、怎么配表。 - 三大件各有专属分册：技术实现（程序侧）/ 美术圣经（美术侧）/ 数据与配表（数据侧）。 ---- +TDD 是当前实现范围的施工依据：**施工方只看本套 TDD，就能完成该范围的实现。** 写全设计要求、必要内容与数值、实际工程约束和验收条件，使施工方无需回查 GDD 或猜测关键设计即可开展实现，章节按实际需要组织。 -# 技术文档写法（策划 · TDD 分册 · 总纲） +施工方可自主决定满足这些要求的代码组织、算法、内部接口、数据结构、配置及资源组织方式；未预先指定这些实现选择，不构成策划缺口。已有工程契约、现有资源格式和用户明确的交付约束必须保留。确有帮助时可给实现建议并说明理由，但不作为唯一方案，也不为每项实现选择增加登记或用户确认。 -> 本文件是 TDD 层唯一承载写作流程的教学件；各分册写法与模板配套使用。 -> 模板与例子文件保持纯净：不含任何步骤、检验提示与标记。 +## 技术选型范围 -## 〇、结构适配原则 +选型限定在 Game Agent 已支持的 Web、Unity、Godot、Cocos Creator 范围内，并遵循已定平台与实际工程。新建 Web 使用 npm + Vite；二维使用 Phaser 4.2.1，三维按需求选择 Three.js、Babylon.js 等适用技术栈；依赖通过 npm 管理，预览与导出使用包目录下的 `dist/index.html`，运行资源随构建进入 dist。已有工程沿用实际结构，不因模板擅自更换引擎或迁移框架。 -根据当前版本的实现目标、游戏规模、运行时和用户要求选取本分册的适用内容，同类项可合并；复杂项目可以拆分补充，简单项目可以合并为最小施工合同。 +## 内容与维护 -## 〇、TDD 的完成判据（总纲） +- 利用已有 GDD 和资料，收编当前范围所需规则、参数与反馈，并补全设计要求及必要约束；可以重组表达，不要求逐段复制。来源及版本集中记录在总册，特殊来源在相应内容旁注明。 +- GDD 中必须由用户决定的产品取舍有缺口或需要变更时，与用户确认并同步受影响设计；其余按已有信息完善设计，当前采用的玩法数值与行为明确，不用“交给程序”掩盖设计缺口。实现选择交由施工方，设计变化后同步受影响正文。 +- 同一事实不多处独立定义。写清跨系统行为中的信息来源、结果归属、存档内容及失败后果；内部调用、字段映射和更新机制由实现确定，已有契约按实际要求记录。 +- 技术、美术、数据可按依赖交叉完善，不固定编写顺序。重要取舍按需记分析；未决事项写清问题、影响和下一步，解决后补齐正文并移出待办，外部台账不能代替施工规格。 +- 同一验证的场景、判据和结果在相关分册完整写一次，其他位置引用并只补充独有要求；总册汇总重要结论、缺口和位置，不复制检查清单。必要验算与实际运行检查各有用途，不互相替代，也不强制每册单列完整验证章节或另建统一验证表。 +- 当前采用值不自动列为待解决问题；存在具体体验疑虑时再写验证问题和判断依据，不为每个参数安排调优或对照版本。范围外内容简述边界即可，只有已确定的后续计划或确实约束当前设计的要求才补充，不预排里程碑或扩展实现。 -**TDD 是当前版本的施工合同：施工方只看 TDD，应能完成本项目实际范围内的实现。** -GDD 是设计真源（给人看、给迭代看）；TDD 是构建真源（给施工看）。 -检验方式＝按项目范围检查施工所需信息是否齐全：实际存在的系统怎么行为、 -实际使用的表和配置怎么读取、实际存在的界面怎么走、实际需要的素材什么规格。答不出的项就是缺口， -缺口回 GDD 同步后**收编**进 TDD（带版本锁）。收编是构建期快照：GDD 定稿 -变更 → 触发对应收编节重同步。 +## 产物与参考 -## 一、这一层的判断立场 +在 `project/04_tdd/` 保留以下四文件；某方向不涉及时在对应分册简述原因，按需增加补充文件。 -你是工程师思维的策划。GDD 是"用户视角的功能描述"，TDD 是"实现者视角的 -架构性描述"——你不重复设计的论证（为什么这样设计，去 GDD 和分析文档查）， -只写怎么落地。你相信： - -- **交接契约是 TDD 最大的价值**：美术交给程序的素材、程序读的表、加载的 - 顺序——每一条缝都写死。缝上不写死，返工就在缝里发生。 -- **平台事实优先**：目标运行时由 GDD 平台事实锁定——**HTML / Unity / Godot / - Cocos 四选一**。HTML 项纯 HTML/CSS/JS 交付；引擎项支持打开引擎工程、自然 - 语言协作改素材与代码；预览与导出按所选引擎的平台流程执行。 - 一切技术选择先过所选运行时这道闸，不推荐该运行时做不出来的东西； - TDD 不擅自换运行时。 -- **一个事实只有一个写权**：每张表、每条主数据都有唯一拥有者系统， - 其他系统只引用不复制（GDD 架构层主数据归属规则在 TDD 落成表结构）。 -- **验收通过后扩充内容**：有 blocker 时先修复并重验。 -- **先少量验证再量产**（美术）/ **先建索引再转表**（数据）。 - -## 二、TDD 与 GDD 的接口（输入从哪来） - -| 输入 | 来自 | 喂给哪件 | +| 文件 | 内容 | 写法参考 | |---|---|---| -| 系统范围表 + P0 清单 + 主数据归属规则 | 架构层 | 三件共用（拆表与拆模块依据） | -| 各系统「数值与数据交接」节 + 定性约束 | 系统文档 | 数据侧（直接订单） | -| 定调记录（参照/滑杆/T 原则）+ 身份基调 | 概念层 | 美术圣经（视觉翻译源头） | -| 可复用能力 | 能力库 | 程序侧+美术圣经（带版本与实例化参数） | +| `01_技术实现.md` | 系统行为、交互、工程与接入约束、运行与验证 | `exemplars/tdd-tech-SKILL.md` | +| `02_美术圣经.md` | 视觉依据、素材清单、制作规格、接入与验收标准 | `exemplars/tdd-art-bible-SKILL.md` | +| `03_数据与配表.md` | 完整内容与数值、含义与关系、文案、必要数据契约与验算 | `exemplars/tdd-data-SKILL.md` | +| `总册.md` | 当前范围、分册索引、来源版本、跨分册约定与重要缺口 | `templates/tdd-master.md` | -TDD 不回头改 GDD：发现 GDD 没写清楚的点，走「开放问题回执」——该问用户 -的升级决策卡，该代决的记台账（带理由和推翻条件），结论回写对应层，TDD 只 -登记去向。顾问期（开发阶段）同一出口：程序美术卡点、成品与文档偏差，都从 -回执进、修订出（v{N+1}）。 +模板与样例通过资源目录按需读取，不预设样例的玩法、数据规模或技术选择。 -## 三、三大件与开工顺序 +## 策划案验收 -| 件 | 管什么 | 读者 | 分册 | -|---|---|---|---| -| 数据与配表 | 字段定义、表结构、数值、验收 | 数值策划 + 程序 | 03 | -| 技术实现 | 代码组织、场景镜头、输入、音频、性能预算、验证 | 程序 | 01 | -| 美术圣经 | 视觉锚、素材规格契约、量产流程 | 美术 | 02 | - -**顺序：数据侧 → 程序侧 → 美术圣经**。数据侧先开的理由：它是唯一直接被 -GDD 喂的（系统文档交接节就是订单）；程序侧的加载与验证要引用表结构；美术 -圣经的素材总清单要引用物品表（每个可见对象绑定 item_id 或显式豁免）。小型 -项目三件可交叉，但**表结构永远先于数值填充**。 - -## 四、怎么写（总纲级；细节在各分册） - -1. 数据侧：总清单拆表 → ID 与字段字典 → 公共条件表 → 建表顺序（物品表 - 起步）→ 表结构契约（程序签名）→ 数值填充（代决+台账）→ 验收七查。 -2. 程序侧：系统实现总览（每系统一段话写死怎么做）→ 技术选型与可复用能力引用 - → 场景与镜头 → 输入与操作 → 音频 → 验证方式与性能预算。 -3. 美术圣经：视觉锚（从概念层定调翻译）→ 素材规格契约逐素材一行 → - 量产流程（概念候选→锚点确认→小批→验收→扩产）→ 资产总清单。 - -## 五、自查参考 - -- 任意一条缝（美术→程序、表→代码、表→表引用）是否都写死了规格？ -- 每张表是否答得出"谁是拥有者系统"？每个 ID 是否全局唯一？ -- 程序侧验证方式是否可执行（跑什么命令、看什么输出）？ -- 素材契约是否覆盖了 GDD 里全部可见对象（或显式豁免）？ -- 验收是否跑过且无 blocker？ - -## 六、红线（只有四条） - -1. **收编必带版本锁**：从 GDD 收编的任何内容标注"基于系统文档@v{N}"； - 无锁收编=违规（双源漂移之源）。TDD 不产生设计观点，只汇集与落实施工。 -2. 引用必带版本：可复用能力引用必须记录版本与实例化参数，选型时与执行时用的一致性靠此保证。 -3. 不越权拍板：产品级取舍回 GDD 层走决策流程；TDD 只做技术代决且记台账。 -4. 表里不写散文：单元格只有数据和枚举；规则写在契约文档，不写在表里。 - - - - -## A1 概念层分册（简介） - -本分册说明概念设计的目标、边界、核心张力、分析记录和交接要求。完整内容请阅读 `resources/skills/concept.md`；概念设计模板请阅读 `resources/templates/concept-design.md`。 - -## A2 顶层设计分册（简介） - -本分册说明顶层循环、资源流、节奏、取舍、范围和验证标准。完整内容请阅读 `resources/skills/top_design.md`；顶层设计模板请阅读 `resources/templates/top-design.md`。 - -## A3 系统架构分册（简介） - -本分册说明系统职责、依赖、数据归属、MVP 闭环、目录映射和架构校验。完整内容请阅读 `resources/skills/architecture.md`；架构模板请阅读 `resources/templates/architecture.md`。 - -## A4 系统文档分册（简介） - -本分册说明单个系统的职责、规则、输入输出、反馈、边界、验证和分析记录。完整内容请阅读 `resources/skills/systems.md`；系统类型的专属写法和模板请按需阅读 `modules/system-types/` 下对应分册。 +- 当前范围的行为、内容与数值、界面、素材要求和实际接入约束完整、自洽，施工方无需回 GDD 或外部台账寻找设计规则；当前采用值明确，后续调优不能代替当前设计。 +- 区分设计缺口与实现选择：未定义奖励、失败后果或关键视觉状态需要补齐；未指定函数签名、源码目录、内部字段或打包方式，不因此阻止策划案验收。 +- 文档一致性、数据引用和必要的数值验算已检查，影响当前施工的关键缺口已解决。 +- 当前范围的验收条件明确，难以理解的规则可用代表性场景说明。实际构建与交付约束保留，测试脚本、执行顺序、截图数量和测量工具由施工方安排；性能指标与专门验证须有实际目标或风险依据。文档验收不要求游戏或素材已制作完成；已有验证结果据实记录，未执行的不宣称通过。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/top_design.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/top_design.md index cfd2439d7..4353a73f6 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/top_design.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/skills/top_design.md @@ -1,194 +1,43 @@ -## A2 顶层设计分册（game-gdd-top-design） - ---- -name: game-gdd-top-design -description: 写游戏策划案（GDD）顶层设计时使用。在概念层定稿之后， - 回答"玩家为什么一直玩"——把概念变成可玩的时间结构（循环/资源/取舍/节奏）， - 并向架构层交付系统范围。配套：templates/top-design.md、templates/analysis.md（全局一份）、 - exemplars/stardew-top-design.md、templates/stardew-analysis.md（全局一份）。 ---- - # 顶层设计写法（策划 · 顶层设计分册） -> 本文件是顶层设计唯一承载写作流程的教学件。 -> 模板与例子文件保持纯净：不含任何步骤、检验提示与标记。 +产物：`project/01_top_design/design.md`。 +参考资源：`templates/top-design.md`、`exemplars/stardew-top-design.md`；全局分析文档的模板与样例：`templates/analysis.md`、`templates/stardew-analysis.md`。 -## 〇、结构适配原则 +## 判断立场 -根据游戏类型、项目规模、用户要求和概念层定稿选取本分册的适用内容，同类项可合并；复杂项目可以拆分补充，简单项目可以压缩为最小可用规格。 +将概念展开为可以理解的游玩过程，说明主要行动、关键规则、反馈与变化，明确当前范围及需要验证的设计问题，为系统划分提供依据。 -## 一、这一层的判断立场 -你是资深游戏策划，正在写全 GDD 最重要的一份文档——概念说"凭什么成立"， -顶层说"好玩在哪"。核心循环无趣，后面写再多系统也救不回来。在这个层里你相信： -- 循环优先：先把大循环、小循环、最小体验单位三层跑通，再谈其他一切。 -- 用玩家的手写，不用系统的嘴写：写"玩家在做什么、在想什么"， - 不写"系统提供了什么功能"。 -- 每个时间段的痛苦和甜都要有来处：取舍表接概念层的张力，节奏接情绪摆动。 -- 资源守恒直觉：每种资源必问来源、储存、消耗——无来源是白给， - 无消耗是废物，环环相扣成套利。 -- 你不替概念层翻案（张力与定稿已定），也不替架构层拆系统（只划边界）。 +从玩家行为说明玩法，结合必要的系统功能解释结果。设计应服务于已确定的核心体验，不把自己的建议写成用户已经作出的决定。 -## 二、动笔前 -1. 概念层 design.md 已定稿可用——顶层定位与取舍表直接从它长出来。 -2. 读取 exemplars/stardew-top-design.md 了解内容组织方式， - 往 templates/top-design.md 里填。 -3. 把概念层已确认的核心张力作为输入；存在对应取舍时再挂上编号。 +## 动笔前 -## 三、顶层设计的组织维度：写什么、为什么、怎么咬合 +结合已获批的 `project/00_concept/design.md`、已有对话和项目资料开展设计，模板与样例按需参考。发现概念与新的约束冲突时，说明影响并讨论相关决定；不因套用样例自行改变方向。 -顶层文档回答四个问题： -**玩家在玩什么（1~9）→ 玩家面对什么选择与后果（10~11）→ -交给架构什么（12~14）→ 没想清什么、定了什么（15~16）。** +## 内容组织 -第 1 节承概念定稿开篇，第 16 节给架构硬约束收口，首尾呼应； -中段三层循环互检，资源流从底下供血。 +根据项目实际玩法选择组织方式，同类内容可以合并，复杂部分可以拆分。不适用的内容省略，有意义但信息不足的内容保留已知信息与待补问题。 -| # | 节 | 是什么 | 为什么写 | 和谁咬合 | -|---|---|---|---|---| -| 1 | 顶层定位与规模锚点 | 承概念定稿 + 按需说明易混淆方向及排除理由 + "让玩家每天都在想"念头句 + 规模参数表（循环单位/段落/复杂度/长期主轴） | 循环单位定错全盘错；定位句防止顶层漂离概念 | 承概念层"概念定稿"；念头句是概念层玩家念头的时间维度版 | -| 2 | 设计目标 | 几种回报、如何互相供给 | 回报并列=小游戏拼盘；互相供给才是循环 | 供给关系落到 4~5 的循环里 | -| 3 | 核心推动力 | 按项目实际存在的即时、阶段或长期推动力组织 | 玩家"什么时候被什么推着走"的推动结构 | 与实际节奏结构对应 | -| 4 | 大循环 | 跨较长时间的循环：文字箭头 + 核心循环图 | 长期留存的结构骨架 | 与 5、7 三层互检：大循环的每环应有小循环供血 | -| 5 | 小循环 | 按项目实际存在的局内或短周期动词链组织 | 记录真正被玩到的循环 | 按实际循环层级互检 | -| 6 | 资源流与输入输出 | 按项目实际存在的资源流、输入输出和反馈组织 | 说明循环中的实际供给与结果 | 与实际循环环节对应 | -| 7 | 最小体验单位 | 多短一段玩法就能体现独有乐趣 + 反馈铁律 | 原型只做这一个单位——定原型规模 | 是 5 的最小切片；14 验证标准的试验对象 | -| 8 | 核心活动流程 | 段落表：阶段/玩家行为/**设计目的** | "玩这个游戏的一天"的可复述剧本 | 设计目的列写不出的段=该删的段 | -| 9 | 取舍表 | 决策/立即收益/延迟收益/主要代价 | 张力的具体化——玩家决策的路口 | **逐条对应概念层核心张力**（对上接口） | -| 10 | 节奏结构 | 按项目实际存在的时间层级和情绪变化组织 | 说明玩法节奏如何变化 | 与实际推动力层级对应 | -| 11 | 失败与回收 | 亏损定性 + 情况/结果表 | 失败的形态决定调性——"少拿"还是"毁掉" | 对齐概念层情绪基调的边界句 | -| 12 | 系统范围 | 系统/顶层目的/**边界** 表 | 架构层接口：系统地图的种子 | **对下接口**：架构照此拆系统 | -| 13 | 范围与非目标 | 最小完整版本清单 + 不做清单 | 立项交付物的边界 | 承概念层"不是什么"；给 14 提供验证范围 | -| 14 | 验证标准 | 验证点/成功标准（行为判据） | "好玩"不可测，"玩家能复述循环"可测 | 判据对象=7 的最小体验单位 | -| 15 | 开放问题 | 留给架构前必须想清的 | 显式债务清单 | 进分析文档或架构层开题 | -| 16 | 顶层定稿 | 收口重锤 + 给架构的硬约束（必须__/不得__） | 检验全文档没写散；架构的紧箍咒 | 回环呼应 1；承概念层定稿的接力棒 | +- **玩法目标**：说明主要行动和回报怎样实现概念中的体验，以及玩家为什么愿意推进。 +- **游玩过程与节奏**：说明玩家如何开始、行动、获得反馈，过程如何变化或结束。存在重复或长期推进结构时再展开循环及其联系，不预设循环层级、日历节奏或反馈层数。文字、表格和图按表达需要选用。 +- **资源与进展**：说明实际存在的资源、状态或进展怎样获得、变化、使用及受到限制。永久解锁、知识或经验等累积结果不必设计消耗环节。 +- **选择与后果**：说明重要选择的结果、收益和代价，以及它们怎样服务于目标体验。是否存在最优解取决于玩法，不要求所有选择等价。存在失败时，按场景说明损失、保留内容和恢复方式。 +- **系统范围与版本边界**：说明支撑玩法所需的能力、目的、边界及相互关系，明确当前版本包含和排除的内容。这里的系统范围供架构层拆分、合并，不要求每项对应一个独立系统。 +- **原型验证与开放问题**：说明需要判断什么，以及为此需要哪些内容、流程和游玩跨度。原型验证范围与当前完整版本范围分别写清；原型不固定为单个体验片段。根据问题采用试玩观察、完成情况、玩家反馈或指标，说明如何据此判断设计是否成立。尚未验证的预期不写成已验证结论。 -咬合一图： +关键约束写在相关内容中，无需结尾重复定稿。影响当前玩法成立或范围确定的问题应先解决，其他问题按影响保留给后续设计。 -``` -概念层定稿（硬约束 + 张力） - ↓ 承接 -1 定位与规模锚点 ───张力落位───► 9 取舍表（逐条对应） - ↓ 展开 -2 设计目标 → 3 核心推动力 → 4 大循环 ⇄ 5 小循环 ⇄ 7 最小体验单位 - ↓ 供血 -6 资源流与输入输出（防无来源/无消耗/套利） - ↓ 后果侧 -8 活动流程（段落表）→ 10 节奏结构 → 11 失败与回收 - ↓ 交付 -12 系统范围（→架构系统地图的种子）＋ 13 范围 ＋ 14 验证标准 - ↓ 收口 -15 开放问题 → 16 顶层定稿（给架构的硬约束） -``` +## 展开深度 -三个接口：**对上**承概念定稿、张力逐条变取舍表；**对内**三层循环互检 -（大⇄小⇄最小单位）+ 资源三段全；**对下**系统范围表喂架构的系统地图、 -顶层定稿当架构的紧箍咒、验证标准当原型试玩判据。 +写清理解和判断玩法所需的关键规则与参数，详细系统规格和实现方案留待后续展开。必要的数值、操作方式和界面信息可以保留。 -## 四、怎么写（模板参考结构，建议按此组织） -（本节是带写法要领的教学版；实际填写的纯净模板在 templates/top-design.md） +## 分析参考 -### 1. 顶层定位与规模锚点 -承接概念定稿说明核心定位；存在容易混淆的方向时，说明排除方向及理由，表述按项目需要组织。 -顶层设计让玩家每天都在想： -> "__（玩家每天惦记的那件事）" -规模锚点表：循环单位 / 段落构成 / 操作复杂度 / 经营复杂度 / 长期主轴排序。 -→ 循环单位先行，定错全盘错。复杂度行可内联参照与"不做"。 +可关注玩法节奏、行动回报、重要取舍及范围选择的依据。按需参考 `templates/analysis.md` 和 `templates/stardew-analysis.md`。 -### 2. 设计目标 -玩家在 __ 循环中同时获得 __、__、__，三者互相供给：__。 -→ 检验：砍掉任何一种回报，另外两种是否受伤。 +## 交付检查 -### 3. 核心推动力 -- 动机主次：__。 -- 即时推动 __；日程推动 __；季节推动 __；长期推动 __。 -→ 只展开项目实际存在的时间层级；不存在的层级不设字段。 - -### 4. 大循环 -**__ → __ → __ → __ → 回到 __。**（附核心循环图） -→ 检验：断掉任何一环，后面是否塌；每一环应有对应小循环供血。 - -### 5. 小循环（按项目实际数量） -**__循环**：__ → __ → __ → __ → __。 -→ 必须具名（"农务循环"不是"资源循环"）；动词链完整到可以直接照做。 - -### 6. 资源流与输入输出 -（资源流图：每种核心资源 来源 → 储存 → 消耗 三段全） -主要输入 __；主要输出 __；按项目需要记录反馈层级。 -→ 三问：这资源哪来的？存在哪？花在哪去？答不出=资源设计未完成。 - -### 7. 最小体验单位 -__（多短一段玩法体现独有乐趣——原型只做这一个单位）。 -保留的玩家行动应有与玩法相称的可理解反馈；反馈形式和数量按项目决定。 - -### 8. 核心活动流程（段落表） -| 阶段 | 玩家行为 | 设计目的 | -→ 设计目的列必填；写不出目的的段落删掉。这份表要能让陌生人复述 -"玩这个游戏的一天"。 - -### 9. 取舍表 -| 决策 | 立即收益 | 延迟收益 | 主要代价 | -→ 每行挂概念层张力编号；避免唯一最优解；不同选择应产生不同但都合理的玩法方式。 - -### 10. 节奏结构 -日内 __ → 周内 __ → 季节/章节 __ → 长期 __。 -整体情绪在"__"与"__"之间摆动（恢复来源 __；变化来源 __）。 - -### 11. 失败与回收 -先定性：失败主要表现为 __（少拿收益 / 延迟成长 / 毁掉积累——三选一档位）， -再列表： -| 情况 | 结果 | -→ 亏损档位必须与概念层情绪基调一致；治愈基调配"少拿"档。 - -### 12. 系统范围（架构层接口） -| 系统 | 顶层目的 | 边界（本层不做什么） | -→ 只写目的与边界，不写系统内部规则；每行将来对应架构层一个 Sxx。 - -### 13. 范围与非目标 -最小完整版本包含：__。不做清单：__。 - -### 14. 验证标准 -| 验证点 | 成功标准 | -→ 成功标准必须是行为判据（"玩家能复述__""玩家出现__行为"）， - "感觉好玩"不算。 - -### 15. 开放问题 -→ 逐条列出；值得跨轮保留的进分析文档，其余留待架构层开题。 - -### 16. 顶层定稿（收口重锤） -顶层当前定稿为：__（循环单位、核心结构、关键档位一句话说全）。 -后续架构必须围绕 __ 拆系统；不得 __。 - -若某节对本项目没意义，直接省略。 - -## 五、分析文档（全局一份，按层分节） - -**全局共用 `project/analysis.md`**：论证按发生层归节，决定登记表全项目共用， -跨层引用查这里。模板与例子：资源 `templates/analysis.md`、 -`templates/stardew-analysis.md`。已决论证与登记写入分析文档， -灵感池、代决、待原型等活队列写入决策台账。 - -- 条目格式：`## 问题：<一句话>` ＋ 状态（agent_proposal / user_confirmed / - superseded，登记 D-__）＋ 广度分析（牵动面＋候选 ≥2）＋ 深度分析 - （逐候选利弊依据，必须引 T 原则/锚点/张力编号，写不出依据的偏好不进分析） - ＋ 综合判断（建议取 __ 因为 __；推翻条件：__）。 -- 分诊三条件全满足才进：① 影响项目方向或边界；② ≥2 合理候选；③ 一时定不了。 - 不满足的：就地小权衡直接进登记表一行，不写条目。 -- 本层标准两问：① 一天/一局怎样形成清楚但不拖沓的循环；② 风险、收益与长期成长怎样互相支撑。 -- 数量纪律：顶层期问题通常 ≤5（结构性争议天然更多）；堆问题时先回读第 1 节定位句。 -- user_confirmed 后三件事：结论一句话迁入 design.md 对应节（留修订痕迹）； - 登记表加行（编号全项目连续，跨层引用写 D-__）；本条目改状态记 D 号保留不删。 - 推翻时新增行挂旧行编号，旧行不删。 - - -## 六、自查参考 -- 三层循环互检了吗：大循环每环有小循环供血？最小单位切得出来？ -- 概念层张力每条都在取舍表有对应行吗？ -- 每种资源三段全吗（来源/储存/消耗）？ -- 验证标准是行为判据吗，还是写了"好玩"？ -- 架构层拿到系统范围表能直接开工吗——有没有该划没划的系统？ -- 失败档位和概念层基调一致吗？ - -## 七、红线（只有三条） -1. 不冒充用户决定：用户没说的方向标"待确认"，正文不写死。 -2. 不越层：向上不翻概念层的案，向下不写系统内部规则与具体数值。 -3. 不凑数：章节对项目有意义但信息不足时，记录已确定内容与待补问题；章节对项目无意义时，直接省略。 +- 能否理解玩家实际怎样玩，行动怎样产生反馈和后续变化。 +- 关键规则、资源或进展、选择与后果是否符合核心体验，是否存在矛盾或缺口。 +- 当前版本范围是否明确，是否足以让架构层判断所需能力及其关系。 +- 验证是否针对真实的设计问题，范围与方法是否足以支持判断。 +- 是否为了填模板编造循环、资源或取舍，或把未确定、未验证的内容写成定论。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/analysis.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/analysis.md index 56ec881d8..da0cd6deb 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/analysis.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/analysis.md @@ -1,41 +1,11 @@ -### C1 模板_分析.md（全局一份；→ templates/analysis.md） - # 分析：《游戏名》 -> **全局唯一一份分析文档**：论证按发生层归节；决定登记表全项目共用，跨层引用只查这里。 -> 论证按发生层归节；决定登记表全项目只此一张，跨层引用只查这里。 -> 状态池（灵感池/代决/待原型等"活的"队列）在决策台账，不放本文件——本文件管已决的档案。 -> 仅记录值得跨轮保留的重要问题；普通讨论、临时灵感和完整对话不写入。策划提案不等于用户确认。 +按需记录影响后续设计的重要取舍。可按问题或主题组织，简单问题几句话即可，复杂问题再展开比较；不必预建各阶段的空章节。 -## 概念期问题（通常 ≤3 条） +下面仅是条目的参考写法，可合并或省略不需要的部分： -## 问题：__（一句话） -状态：agent_proposal / user_confirmed / superseded（登记 D-__） -- 广度分析：牵动面（波及哪些锚点/张力/节）＋ 候选方向（≥2） -- 深度分析：逐候选 利/弊/依据（必须引定调记录 T 原则、锚点、张力编号或参照资料，写不出依据的偏好不进分析） -- 综合判断：建议取 __，因为 __。推翻条件：__。 +## 问题：__ -## 顶层期问题（通常 ≤5 条） +背景与主要依据：__。 -（同上格式） - -## 架构期问题 - -（同上格式；本层不写独立分析文档，结构争议全归此处） - -## 系统期问题（按系统号分条，如 S06） - -（同上格式） - -## 技术文档期问题 - -（同上格式；复用能力选型分歧、表结构二义等） - -## 全局决定登记表 - -| D# | 决定 | 层 | 权威 | 依据 | 推翻条件 | 状态 | -|---|---|---|---|---|---|---| -| D-01 | __ | 概念 | user / agent（代决带理由） | 本文件问题__ / T__ | __ | 已确认/已推翻/待原型 | - -- 编号全项目连续；跨层引用直接写"D-__"；推翻时新增行挂旧行编号，旧行不删。 -- 就地小权衡（不满足分诊三条件的）直接登记一行，不写问题条目。 +当前结论或建议：__。尚未确定的事项及下一步：__。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/architecture.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/architecture.md index e6d8d5e85..40aa03092 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/architecture.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/architecture.md @@ -1,115 +1,27 @@ -### C1 模板_系统架构.md（→ templates/architecture.md） - -本模板是参考结构，不是固定清单。只有需要独立职责、状态或数据边界的部分才拆成系统；简单项目可以合并系统和章节，复杂项目可以增加必要的系统与校验。表格中的示例行可按实际系统、风险和问题扩展，不代表数量上限。 - # 系统架构：《游戏名》 -## 架构定位与目标 -本阶段确定"哪些系统支撑一轮玩法"，不展开单系统内部规则。 -划分原则：__。 +产物：`project/02_architecture/design.md`。以下内容按项目需要选用，可以合并或拆分。 -一句话架构： -> __ +## 系统与职责 -变更记录： -- __（日期 + 改动 + 原因/登记编号） - -## 系统地图 - -| 编号 | 系统 | 一句话职责 | 优先级 | -|---|---|---|---| -| S01 | __ | __ | P0 | -| S02 | __ | __ | | -（以上为示例，可按实际系统删减或扩充。） - -支撑层（不拥有核心规则）：__。 - -P0 段： - -| 系统 | 目的 | 输入 | 输出 | P0 原因 | +| 编号 | 系统 | 职责与负责的状态 | 当前版本范围 | 文档位置 | |---|---|---|---|---| -| __ | __ | __ | __ | 没有它，__ | +| S01 | __ | __ | __ | project/03_systems/S01__/ | -## 系统职责 +只补充表中尚未说清、容易混淆的职责边界。简单职责可在同一系统内表达，不必各自编号；文档位置按实际拆分或合并填写，不决定代码目录。 -| 系统 | 主要职责 | 不负责 → 移交谁 | -|---|---|---| -| __ | __ | __ → __ | +## 协作与数据归属 -职责说明（争议最大的系统各一段）： +关键行动涉及的系统、信息传递和结果约束：__。详细流程在主要负责的系统文档展开，此处保留影响架构判断的概述与必要顺序。 +补充职责表尚未覆盖的数据归属或共享状态：__。 +需要统一的单位、规则或参数：__。 -### __系统 -负责 __。不负责 __，也不直接决定 __；只负责 __。 +## 实现范围与验证 -## 依赖与数据流 +最先实现的能力与可玩流程：__。 +已确定且需要说明的后续版本或原型范围：__（没有则省略，不把范围外内容自动排入里程碑）。 +架构特有的验证问题与判断依据：__；已有计划引用对应位置，不重复展开。 -```mermaid -flowchart TD - A[__系统] --> B[__系统] - U[呈现层] -.读取状态.-> A -``` +## 风险与未决问题 -```mermaid -flowchart LR - A[__来源] --> B[__转化] - B --> C[__消耗/投资] -``` - -主要状态： -- 全局状态：__。 -- 玩家状态：__。 -- 场景状态：__。 -- 社会状态：__。 - -主数据归属规则： -- 规则文档描述"如何计算"与"何时发生"；数据表描述"有哪些对象与配置"。 -- 系统之间通过稳定 ID 关联。 -- 任何系统不复制另一系统的主数据。 - -## 核心循环覆盖检查 - -| 顶层循环环节 | 认领系统 | -|---|---| -| __ | __ | - -## 目录映射 - -| 目录 | 本阶段定位 | -|---|---| -| 03_systems/S01__/ | __ | -| 03_systems/S02__/ | __ | - -## MVP 最小闭环 -1. __ -2. __ -3. __ - -如果这条闭环不成立，不应继续增加 __。 - -## 统一数值基准 -全局单位：__。 -- 时间节奏基准：__。 -- 货币量级基准：__。 -- 成长回报基准：__。 -- 体力与风险基准：__。 - -（具体换算与验算数值由技术文档层·数值策划承接。） - -## 系统边界 -- __（不拆出独立 __ 系统 / __ 归引擎层 / __ 归呈现层） - -## 优先级与范围 -- P0（最小闭环必需）：__。 -- P1（完整体验）：__。 -- P2（扩展内容）：__。 - -## 风险与校验 - -| 风险 | 校验方式 | -|---|---| -| __ | __ | -（按实际风险逐行补充。） - -## 开放的结构问题 -- __ -（按实际问题逐条补充。） +问题、影响及下一步：__。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/concept-design.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/concept-design.md index 36fc4dc79..66e40a7ad 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/concept-design.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/concept-design.md @@ -1,58 +1,23 @@ -### C1 模板_概念设计.md（→ templates/concept-design.md） - -本模板是参考结构，不是固定清单。填写前按项目类型、规模和用户要求筛选章节与字段；同类内容可合并，若某节对项目没有实际意义则删除，复杂项目可增加必要内容。表格和列表中的示例项可按实际内容扩展，不代表数量上限。 - # 概念设计：《游戏名》 -## 一句话概念 -《__》是一款 __：玩家通过 __，把 __ 逐步 __。 +以下为参考结构，可按项目需要合并、拆分或省略。提示问题用于帮助组织内容，不要求逐项填写。 -## 定调与设计锚点 +## 游戏概念 -### 定调记录（全项目调性真源，级联决策的依据库） -- 参照选择：以《__》为主（__, 学 __）；不参考 __。 -- 调性滑杆：压力感 __ / 战斗比重 __ / 管理深度 __ / 叙事比重 __ / 节奏 __。 -- 调性锚（按项目需要逐条具名，下游开放问题按需从这里级联）： - T__ __。 +游戏是什么，玩家主要做什么，吸引力在哪里？ -### 设计锚点（六仲裁位） -- 核心幻想：__。 - 玩家念头："__" -- 目标体验：__。 -- 玩家动机（按项目实际存在的时间尺度填写）：__。 -- 核心循环：__ → __ → __ → __ → 回到 __。 -- 跑偏风险：__。 -- 非目标：__（详见《不是什么》）。 +## 体验与玩法 -## 玩家身份与基调 -- 玩家身份：__。 -- 情绪基调：__；可以 __，不可以 __。 +玩家在什么情境下获得什么感受？哪些行动、反馈或目标推动游玩？存在重要取舍时，选择及代价是什么？ -## 风格与世界观 -世界观为 __ 服务；叙事通过 __ 展开。 +## 身份、基调与世界观 + +哪些身份、情绪基调、风格或世界规则有助于理解游戏？有参照时，具体借鉴什么？ ## 目标玩家与情境 -- 目标玩家：与 __ 的受众重合；吸收 __ 的 __ 需求；但不会变成它，因为 __。 -- 适合情境：__。 -- 体验门槛：需要理解 __；不应要求 __。 -## 不是什么 -| 不是 | 因为 | -|---|---| -| __ | __ | - -## 核心张力 -- __ 有限，但 __。 -- __ vs __。 +面向哪些玩家，适合怎样的游玩情境，体验门槛是什么？ ## 边界与约束 -- 概念层只定 __；__ 留给顶层及以后。 -- 规模与回流：__。 -- 参照声明：__。 -## 概念定稿 -《__》的核心不是 __，而是： -> __ - -交给下一层的约束：__。 -（调性已在第 2 节定死；顶层及以下一切开放问题先回定调记录级联。） +有哪些容易混淆的方向和排除理由？哪些范围扩张会影响核心体验？团队与项目有哪些实际限制，后续设计需要遵守什么？ diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/stardew-analysis.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/stardew-analysis.md index a08d153c6..3ae1f7699 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/stardew-analysis.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/stardew-analysis.md @@ -1,63 +1,25 @@ -### C1 例子_星露谷_分析.md（分析金样；→ templates/stardew-analysis.md） +# 分析：《星露谷物语》示例项目 -# 分析：《星露谷物语》 +以下为策划分析的写法示例，不代表原作的真实决策记录。 -> 全局唯一一份分析文档。定调记录（参照/滑杆/T1~T7）在概念层设计文档第 2 节，此处不重复。 -> 状态池在决策台账；本文件只放已决论证与登记。策划提案不等于用户确认。 +## 矿井战斗要不要做成装备驱动的成长主轴？ -## 概念期问题 +本项目以轻松的农场生活和自由安排为主要体验。装备驱动的战斗能增加长期目标，但需要更多装备、敌人和难度设计，也会与农场主轴争夺玩家时间。 -## 问题：矿井战斗要不要做成装备驱动的成长主轴？ -状态：user_confirmed（登记 D-03） +当前采用战斗作为矿井探索的伴生风险和节奏变化，不做装备驱动主轴。相关定位写入概念设计和架构文档；后续根据试玩反馈评估是否需要调整战斗深度。 -- 广度分析：牵动锚点"目标体验"（掌控感与紧张的比例）、"不是什么"表第 3 行、核心张力第 3 条（稳定经营 vs 未知探索）。候选：A 战斗做成装备驱动主轴之一；B 战斗保持伴生风险，深度刻意受限。 -- 深度分析：A 利：矿井更耐玩，长期目标多一条。弊：需要装备与难度曲线支撑，时间重量与农场主轴抢位，动摇"治愈"基调（违反 T1）。B 利：保住生活模拟纯度，战斗作为探索的节奏变化存在。弊：战斗型玩家留存偏弱——但受众映射显示目标玩家（牧场物语系）本不以战斗为主诉求。 -- 综合判断：建议 B：战斗深度刻意受限，作为矿井探索的风险与节奏变化存在，不做装备驱动主轴。 - 推翻条件：试玩数据中过半玩家在矿井流失且归因于战斗乏味。 +## 每日目标要不要强制？ -## 顶层期问题 +每日固定目标有助于提供方向，但容易形成打卡负担；完全移除时间与体力约束，又会减弱每天安排活动的意义。 -## 问题：一个游戏日怎样保持"想做的事多于做得到的"而不变成打卡负担？ -状态：user_confirmed（登记 D-07） +当前保留温和的时间与体力约束，日目标由玩家自设，以季节事件和社区修复目标提供较长期的方向。后续通过新手试玩观察玩家是否知道接下来能做什么，再调整引导。 -- 广度分析：牵动锚点"目标体验"（掌控感与治愈的配比）、张力第 1 条（时间与体力有限）、节奏结构日内层、失败与回收档位。候选：A 收紧——每日固定目标与奖励；B 放宽——去掉每日压力；C 保留时间/体力约束，目标完全由玩家自设。 -- 深度分析：A 利：方向感强。弊：把休闲变成每日打卡义务，直接命中跑偏风险第 2 条（违反 T5）。B 利：最松弛。弊：没有取舍就没有"今天的选择"，张力第 1 条落空。C 利：约束存在但重量自选；节日与季节提供低频外部节拍。弊：部分玩家需要更明确指引——可由社区修复目标与任务系统补位。 -- 综合判断：建议 C：时间与体力作为温和硬约束保留，日目标不强制；以季节事件和社区修复目标提供低频牵引。 - 推翻条件：新手引导期数据显示玩家第一周内流失且归因于"不知道该做什么"。 +## 采集、钓鱼与战斗是否共用活动结果接口？ -## 架构期问题 +三类活动都需要把产出交给物品系统。分别定义入账协议会增加公共系统的适配工作，但过度统一也可能掩盖各活动的差异。 -## 问题：采集、钓鱼与战斗要不要共享统一的"活动结果"接口？ -状态：user_confirmed（登记 D-11） +当前采用统一的活动结果接口，表达结果的身份与去向；掉落、品质和判定规则仍由各活动系统维护。接口与职责已写入对应设计文档。 -- 广度分析：牵动 S05/S06 的输出边界、S07 物品系统入账方式、依赖与数据流图活动侧。候选：A 三系统各自定义产出结构；B 统一"活动结果"接口（活动类型+结果列表+条件），三系统只填参数。 -- 深度分析：A 利：各系统自由。弊：S07 要维护三种入账协议；任务系统验证"完成了一次采集/战斗"需分别适配——职责表里 S05/S06 的"不负责"列都指向 S07，接口不统一把适配成本堆给公共层。B 利：产出、经验、任务进度走同一条管线，S07 与 S11 只适配一次；新增活动类型不动公共层。弊：接口要预留类型差异（战利品请求/钓鱼品质），设计不当会把差异塞进自由字段。 -- 综合判断：建议 B：统一"活动结果"接口，类型差异用明确枚举表达；掉落条件与品质规则仍归各自系统文档定义，接口只承载"结果的身份与去向"。 - 推翻条件：第三种活动类型加入后出现接口无法表达的结构性差异（如双通道产出）。 +## 战斗判定窗口是否需要调整？ -## 系统期问题 - -## S06：战斗操作深度选哪一档？ -状态：user_confirmed（登记 D-13；手感部分 prototype_pending） - -- 广度分析：牵动玩家行动动词组、状态与规则的判定方式、顶层规模锚点（操作复杂度=低）、"不是什么"表第 3 行。候选：A 实时轻操作（移动+攻击+闪避）；B 节奏/指令判定（时机窗口确认）。 -- 深度分析：A 利：紧张感即时、反馈直接。弊：与顶层"操作复杂度低"直接冲突，敌人一多把轻度风险推成动作压力，动摇治愈基调（T1）。B 利：判定即反馈，压力可通过窗口宽度调节；与"伴生风险"定位相容（D-03）。弊：判定窗口的手感无法纸面验证——需原型。 -- 综合判断：建议 B 为设计方向：节奏/指令判定承载轻度战斗；判定窗口手感在登记表标"待原型验证"。 - 推翻条件：原型显示节奏判定拖慢探索节奏，或玩家反馈"按键时机莫名其妙"。 - -## 技术文档期问题 - -（TDD 期开放问题走分册"开放问题回执"，B 级两条——背包容量、生命体力共享——收口后论证与登记归此处。） - -## 全局决定登记表 - -| D# | 决定 | 层 | 权威 | 依据 | 推翻条件 | 状态 | -|---|---|---|---|---|---|---| -| D-01 | 定调：牧场物语系参照、治愈慢节奏 | 概念 | user | 用户原始需求 | — | 已确认 | -| D-02 | 单人体验，无多人 | 概念 | user | 概念层非目标 | — | 已确认 | -| D-03 | 战斗保持伴生风险，不做装备驱动主轴 | 概念 | user | 概念期问题一 | 矿井流失率过半且归因战斗 | 已确认 | -| D-07 | 日目标自设，季节与社区提供低频牵引 | 顶层 | user | 顶层期问题一 | 新手周流失归因无方向 | 已确认 | -| D-11 | 采集/钓鱼/战斗统一"活动结果"接口 | 架构 | user | 架构期问题一 | 第三活动类型出现结构性差异 | 已确认 | -| D-13 | 战斗采用节奏/指令判定；窗口手感待原型 | 系统 | user | S06 问题一 | 原型显示节奏拖慢/玩家困惑 | 已确认（手感 prototype_pending） | - -（D-04~D-06、D-08~D-10、D-12 为就地小权衡，直接登记未开条目；编号连续不复用。） +目前无法仅凭文档判断窗口手感。下一步在矿井原型中观察判定是否易懂、是否拖慢探索；试玩结果出来后再修订规则。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/tdd-art-bible.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/tdd-art-bible.md index 3577752f6..949a2ca8e 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/tdd-art-bible.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/tdd-art-bible.md @@ -1,73 +1,50 @@ -### C3 02_美术圣经/模板.md（→ templates/tdd-art-bible.md） - -本模板是美术实施的参考结构。按项目实际需要选择角色、场景、UI、动画和素材契约；没有对应资产类型时删除相应章节，复杂项目可增加必要的视觉规则。表格和资产条目可按实际内容扩展，不代表数量上限。 - # 美术圣经：《游戏名》 -> 状态：{drafting / reviewed / frozen}　|　定调锚：概念层@v{N} 第 2 节　|　style_id：`__` +按实际范围组织内容，来源与版本见总册。 -## 视觉风格总览 +## 范围与设计依据 -__（一段话：从定调记录翻译的视觉气质；参考图位 __ 张） +- 当前实现范围：__（区域、玩法、界面和状态；范围外内容仅说明必要边界，不自动规划后续版本）。 +- 概念与系统依据：__（文档、章节及转译到本分册的视觉要求）。 +- 目标运行时与显示条件：__（实际工程、目标视口和缩放方式）。 +- 已有视觉参考入口：__（真实位置与借鉴点；没有则写“暂无”，并在下文写明文字规格）。 +- 已有素材入口与实际接入约束：__（真实位置、格式等；尚未产出时注明，不强制预定目录和打包格式）。 -## 视觉锚 +## 视觉规则 -- 关键词：__（按项目需要）。 -- 禁用关键词：__。 -- 色板：主色 __ / 辅色 __ / 点缀 __（配比 __）；昼夜·天气·季节表现 __。 -- 形状语言：__。 -- 比例与轮廓：__。 -- 光照与材质：__。 -- 渲染口径：__（可引画风卡 `卡名@版本`）。 +- 气质与关键词：__。 +- 避免的表现：__。 +- 色板与状态变化：__（主辅色、提示色、昼夜/天气/季节等当前范围需要的变化）。 +- 形状、比例、视角与层级：__。 +- 光照、材质、渲染与缩放：__。 -## 角色模板 +## 共性表现要求 -- 基础规则：__（头身比/结构/共用约束，保同一世界观）。 -- 方向数：__（__ 方向，左=右镜像：是/否）。 -- 动画状态：__（待机 __ 帧 / 走 __ 帧 / 跑 __ 帧 / 受击 __ 帧…）。 -- 与人物复用能力三段格式的衔接：选型卡 __ / 工艺卡 __ / 接口卡 __。 +有多对象共性时按类别集中说明，可与对象清单合并。写清影响表现的尺寸、动作、方向、层级与边缘要求；音频写用途、触发、循环与听感。已有素材的实际格式和接入约束按需补充，文件名、帧键、打包与加载方案由施工方决定。 -## 场景模板 +| 类别 | 共性表现要求 | 用途与必要约束 | 验收判据 | +|---|---|---|---| +| __ | __ | __ | __ | -- tileset 规格：__（tile 尺寸/边缘连接/padding）。 -- 图层拆分：__（地面/装饰/遮挡/碰撞语义）。 -- 场景对象规则：__（多帧禁当静态贴图、单元素禁整图等运行时绑定规则）。 +## 当前范围对象清单与例外 -## UI 视觉 +列全当前可见对象、必要状态和有限变体，用名称或必要标识关联数据侧内容，已有 ID 沿用实际契约。写清出现位置和视觉结果；已选定文字、程序绘制或图像等表达方式时说明。范围外对象不占当前清单行。 -__（承 UI 系统文档的界面清单；视觉语言与信息分层对齐） +| 对象或明确对象组 | 类别与关联内容 | 状态与变体 | 表现要求或共性例外 | 出现位置 | +|---|---|---|---|---| +| __ | __ | __ | __ | __ | -## 素材规格契约 +## 后续生产与接入验收 -| 素材 | 规格（尺寸/帧数/方向数） | 命名规则 | atlas 格式 | 验收 | 绑定 | -|---|---|---|---|---|---| -| __ | __ | __ | __ | __ | `item_ __` / 豁免：__ | -（以上为示例，可按实际素材删减或扩充。） +- 生产交付约束：__（已有工程或用户明确要求的源文件、输出格式等；没有则省略）。 +- 共性要求与对象说明尚未覆盖的接入、视觉或可用性判据：__（没有则省略，不重复已有检查）。 -- 绘制工艺：__（按项目实际制作路径记录工具、参数与封装流程）。 -- 豁免类型仅限：程序化生成 / UI 文本 / 本期不需要。 +判据已在正文写清时，无需另列验收表。必要时提供观察场景，截图数量、工具及执行流程由施工方安排。对象或状态变化时更新受影响正文。 -## 资产状态表（asset manifest） +## 当前未决问题 -| asset_id | 规格 | 绑定 | 状态 | 验收记录 | contract_version | -|---|---|---|---|---|---| -| __ | __ | `item_ __` / 豁免 | 缺失/草稿/已交付/已验收/已接入 | 技术过/视觉过 @__ | __ | -（以上为示例，可按实际资产删减或扩充。） - -- 状态单向流转：缺失 → 草稿 → 已交付 → 已验收 → 已接入；驳回退回草稿并记原因。 -- 验收两维：技术（尺寸/透明/帧数/命名）+ 视觉（对照视觉锚）；两维都过才进"已验收"。 -- 需要登记的 gameplay 可见对象有一行；不需要资产登记的对象不建立空记录。 -- 程序接入后填消费点（哪个模块加载、事件映射），`contract_version` 变更须重验收。 - -## 量产流程与验证 - -1. 概念候选 __ 张 → 2. 人选方向 → 3. 锚点图 __ 张 → 4. 锁圣经 → -5. 写契约 → 6. 小批 __ 张 → 7. 技术检查（__）→ 8. 接入程序 → -9. 运行时验收（按项目支持的平台）→ 10. 扩产。 -（以上为示例，可按实际流程删减或扩充。） - -## 开放问题回执 - -| # | 问题 | 去向 | +| 问题 | 对当前施工的影响 | 下一步与需更新的位置 | |---|---|---| -| 1 | __ | → 决策卡 / 台账 {id} / 本文档 §__ 修订 | +| __ | __ | __ | + +仅保留设计或实际接入缺口，以及有具体依据的体验疑虑；已采用值不自动登记调优待办。内部命名、打包和加载方案由施工方决定，不因尚未选定而判定本分册不完整。没有问题时省略本节。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/tdd-data.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/tdd-data.md index 244e8063b..83de06290 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/tdd-data.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/tdd-data.md @@ -1,78 +1,60 @@ -### C3 03_数据与配表/模板.md（→ templates/tdd-data.md） - -本模板是数据与配表的参考结构。只有项目实际存在配置、枚举、关系或条件数据时才建立对应表和校验；简单项目可以直接写配置约定，复杂项目再拆分表结构与验算流程。表格中的示例行可按实际数据、字段和验算项扩展，不代表数量上限。 - # 数据与配表：《游戏名》 -> 状态：{structuring / filling / accepted}　|　基于：各系统交接节汇总　|　验收：check@{id} 最新结论 __ +> 当前实现范围：__。本册与技术实现、美术圣经及总册共同构成施工依据，来源版本见总册；验收对象是策划文档。写全当前范围的内容、数值、文案和必要验算，内部数据结构与配置载体由施工方决定。 -## 数据表总清单 +## 数据范围与归属 -| 表格组 | 建议表名 | 主要维护系统 | +| 内容或数值 | 维护位置 | 当前范围用途 | 关联对象或行为 | +|---|---|---|---| +| __ | __ | __ | __ | + +只列本期实际使用的内容，每项事实只在一个位置定义。用名称或必要的标识明确关联，已有工程 ID 沿用实际契约；文档表格不决定程序如何组织数据。 + +## 数据定义与完整内容 + +按实际内容组织，含义与具体取值可以合并。少量参数可直接使用下表，不另列重复清单；同结构多条记录可给共用属性说明和完整内容，不要求两种形式都使用。 + +| 参数或适用对象 | 当前值 | 单位、含义与必要约束 | |---|---|---| | __ | __ | __ | -（以上为示例，可按实际数据表删减或扩充。） -（表格拆分是生产组织方式，不改变主数据归属。） +写清用途、单位、对象关系、数量或顺序及实际设计约束。共用规则集中说明，派生值写明计算关系；固定行为在相关规则中说明，不要求转换为配置字段或开关。条件、随机与失败后果按当前玩法明确；字段命名、内部类型、数组或对象、文件组织及读取机制留给施工方。 -## 字段字典与 ID 命名规范 +已有数据格式或明确要求交付可加载数据时，在此记录实际字段、格式、默认或必填约定及引用规则；没有这些约束时省略，不为填模板编造契约。 -- ID 命名：小写 snake_case，`对象类型_名称_必要时加阶段`（如 `item_turnip`）；全局唯一、废弃不复用。 -- 通用字段：`*_id` / `display_name_text_id` / `description_text_id` / `condition_id` / `enabled_state`（active·draft·disabled·deprecated）/ `sort_order` / `designer_note` / `unit`（数值字段必填：time_slice·game_day·currency·stamina·exp）。 -- 常用后缀：`_amount`（配单位）/ `_cost` / `_rule_id` / `_condition` / `_time` / `_duration` / `_state` / `_text_id`。 -- 类型与空值：数值栏禁"约/无/待定"；空值=不适用≠0≠无限；布尔 true/false；多值一律关系子表。 -- 引用完整性：`item_id`→物品表；`location_id`→区域表；`npc_id`→NPC表；`quest_id`→任务表；`recipe_id`→配方表；`condition_id`→条件表；`text_id`→文本表。删除先置 `deprecated` 并查引用。 +玩家可见文案集中列一次，注明使用位置： -## 公共条件表 +| 文案标识 | 完整文本 | 使用位置及必要说明 | +|---|---|---| +| __ | __ | __ | -| condition_id | condition_type | target_id | operator | required_value | enabled_state | 备注 | -|---|---|---|---|---|---|---| -| __ | date_day / progress_flag / skill_level / schedule_open / quest_completed / __ | __ | __ | __ | active | __ | +当前范围所需的**全部**内容、参数值和文案必须在本套 TDD 中完整给出。已在其他分册定义的内容引用其唯一权威位置，不重复抄录；占位行不代表填充完成。内容数量由已定范围决定，允许明确当前采用的初值并在原型中调优；未定关键设计值进入“待解决问题”，不可用空白、未经说明的估值或几行示例冒充完整内容。 -（存在复杂条件时再拆条件组与条件行；没有条件系统时删除本节。） +## 关键循环验算 -## 工作簿组织与建表顺序 +按玩法选择足以覆盖本期关键数值关系的场景与跨度，不固定为五日。使用上节当前采用值，写出必要的输入、计算和结果，并核对所需对象可获得、单位一致。行为检查引用技术分册，不为重复说明行为另建状态推演表。 -| 工作簿 | 工作表 | -|---|---| -| `__ .xlsx` | __ | - -建表顺序：①物品表（公共 item_id）→ ②__ → ③__ → ④__ → ⑤__ → ⑥__ → ⑦__ → ⑧__。 -每完成一组查三件事：引用 ID 存在 / 条件有负责系统 / 同一数值只有一个系统维护。 -（以上为示例，可按实际表结构删减或扩充。） - -## 表格-程序契约 - -1. 加载顺序按引用拓扑：主数据 → 关系 → 条件 → 文本（最后）。 -2. 启动期全量校验（外键/枚举/单位）；运行期全部 id→对象字典 O(1) 查找。 -3. 条件求值统一 `check(condition_id)`，全部系统复用。 -4. enabled_state 生命周期：active 加载；draft 调试可见；disabled 不加载；deprecated 不加载但留 ID 占位。 -5. 单位类型化（time_slice/game_day/currency/stamina/exp 进类型系统，同列禁混单位）。 -6. 多值一律关系子表；运行期无"解析逗号拼接"代码路径。 -7. 改表 → 验收过检（blocker=CI 红灯）→ 进包；`data_version` 为迁移依据。 - -## 数值填充与验算 - -- 填充代决台账： - -| 表 | 字段 | 默认值 | 依据 | 推翻条件 | +| 起点与行动 | 成本及计算 | 获得及计算 | 跨日/状态变化 | 结果与结论 | |---|---|---|---|---| -| __ | __ | __ | T__ / 台账 id | __ | -（以上为示例，可按实际验算字段删减或扩充。） +| __ | __ | __ | __ | __ | -- 前五日闭环验算： +说明尚不能验算的输入、受影响的结论和补齐后需重算的内容：__。 -| 日期 | 主目标 | 关键行动 | 主要成本 | 主要获得 | 结果 | -|---|---|---|---|---|---| -| 第 1 日 | __ | __ | __ | __ | __ | -（以上为示例，可按实际循环或阶段删减或扩充。） +## 数据检查与结论 -- 收益链校验：`__ → __ → __ → __ → __`（逐环引 ID）。 +| 检查对象 | 实际检查及结果 | 未解决项/影响 | +|---|---|---| +| 当前范围内容和文案完整性 | __ | __ | +| 取值、单位、对象关系与规则一致性 | __ | __ | +| 实际数据契约（存在时） | __ | __ | +| 关键循环验算 | __ | __ | -## 验收 +本册结论：__。已有验算结果引用上节，不复制计算表。关键设计或实际接入缺口存在时写“未完成”；内部结构尚未设计不构成策划缺口。补齐后更新正文并重新检查受影响项，不冒充游戏构建或试玩结果。 -- 验收记录：check_id / workbook / sheet / data_version / check_type（primary_key·reference·enum·unit·range·business_rule·duplicate_ownership）/ severity（blocker·warning·note）/ result / issue / owner / resolution。 -- 五查必过：主键唯一不空；外键存在且目标非弃用；枚举有清单；单位可判且同列不混；无违规负数、`duration=0` 仅即时。 -- 两查复核：业务规则（季节窗口相容、目标有验证系统、奖励一次、配方输入可达）；重复归属（身份/价格/成本/奖励/位置各只有一个写权）。 -- 三级处置：blocker 禁止扩内容；warning 记负责人与计划；note 不阻断。 -- 最近验收结论：__（结构、规则或字段语义一变，受影响链路全部重验。） +## 待解决问题 + +| 问题 | 对当前施工或验算的影响 | 下一步与需更新的正文 | +|---|---|---| +| __ | __ | __ | + +没有未决问题时删除本节；已有采用值不自动登记调优待办，具体体验疑虑在相关分册说明即可。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/tdd-master.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/tdd-master.md index 1285e9f6f..0b4a9b443 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/tdd-master.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/tdd-master.md @@ -1,63 +1,37 @@ -### C3 模板_TDD总册.md（→ templates/tdd-master.md） - -本模板是 TDD 总册的参考结构。只建立当前项目实际需要的技术、美术、数据和索引内容；没有对应方向时不创建空分册，复杂项目可以增加施工所需的分册。表格中的示例行可按实际分册、问题和验收项扩展，不代表数量上限。 - # TDD 总册：《游戏名》 -> 本册是 TDD 层的封面与索引：正文在三件分册（01 技术实现 / 02 美术圣经 / 03 数据与配表）， -> 跨件的缝在本页看全。状态：__　|　基于 GDD：__@v{N} +## 当前范围 -## 自足性检查（TDD 的完成判据） +本次实现目标与边界：__。 -> 标准：施工方只看当前 TDD，能完成项目实际范围内的实现。逐项检查当前项目真正需要的问题， -> 答得出=过；答不出=缺口（列 GDD 来源与同步动作）。 +完成标准：施工方只看本套 TDD 就能完成当前范围的实现。写全设计要求、内容与数值、实际工程约束和验收条件；施工方自主决定满足要求的内部实现，未指定源码目录、函数签名或数据结构不构成策划缺口。验收检查文档的完整、自洽及必要验算，不以游戏或素材已经生产完成为前提；关键设计或实际接入缺口必须解决。 -| # | 施工方的问题 | 答案在哪 | 状态 | -|---|---|---|---| -| 1 | 实际存在的系统怎么行为？ | 01 收编章（@v{N}） | __ | -| 2 | 实际使用的表和配置是否可施工？ | 03 数据与配表 | __ | -| 3 | 实际存在的界面怎么走？ | 01 UI 交互规格 | __ | -| 4 | 实际需要的素材什么规格？ | 02 资产状态表 | __ | -| 5 | 代码怎么组织、跑在哪？ | 01 代码组织+能力边界 | __ | -| 6 | 怎么算做完了（判据）？ | 01 里程碑+各件验收 | __ | +## 分册索引 -当前项目所需检查全部为"过"时，TDD 进入 frozen——构建可以在本版本范围内脱离 GDD 进行。 +| 文件 | 内容位置 | +|---|---| +| `01_技术实现.md` | __ | +| `02_美术圣经.md` | __ | +| `03_数据与配表.md` | __ | -## 三件状态 +四文件均保留；不涉及的方向在对应分册简述原因。补充文件在此列明。 -| 件 | 状态 | 版本 | 读者 | 一句话结论 | -|---|---|---|---|---| -| 01 技术实现 | __ | __ | 程序 | __ | -| 02 美术圣经 | __ | __ | 美术 | __ | -| 03 数据与配表 | __ | __ | 数值+程序 | __ | +## 来源与版本 -## 跨件契约速查（缝都在这） +记录采用的 GDD、系统文档及其他资料的版本或可识别快照：__。设计变更后同步受影响分册，特殊来源在正文旁注明。 -| 缝 | 契约 | 权威在 | +## 跨分册约定 + +| 共同使用的约定 | 当前结论 | 维护位置 | |---|---|---| -| 素材绑定 | 资产状态表每行绑 `item_id`/`enemy_id`/`npc_id`…，ID 查数据侧对应表 | 03 字段字典 | -| 视觉翻译链 | style_id 及视觉锚全部溯源概念层定调记录（T 原则） | 概念层第 2 节 | -| 加载顺序 | 程序启动按"主数据→关系→条件→文本"拓扑加载（契约七条①） | 03 契约 | -| 帧表格式 | atlas+帧表双边共用（圣经素材契约列的格式 = 程序侧帧动画节读的格式） | 01 §能力边界 | -| 交互热区 | 触控热区 ≥ __px，圣经 UI 节与程序侧输入表同源 | 01 输入表 | -| 音频规格 | 圣经音频契约（格式/响度/循环点）= 程序侧音频表触发实现 | 02 音频契约 | -| 昼夜/色调 | tint 色值表豁免绑定但拥有者写明 | 02 资产状态表 | -| 拥有者总则 | 一个事实一个写权：数值事实归 03 各表、生产状态归 02 资产表、技术事实归 01 | 架构层归属规则 | +| __ | __ | __ | -## 开放问题回执汇总（三件集中视图） +只列实际需要共同遵守的设计、数据、素材与已有接口约束，详细内容在对应分册维护；不为填写本表预设内部实现契约。 -| # | 来源件 | 问题 | 去向 | 状态 | -|---|---|---|---|---| -| __ | 01/02/03 | __ | 决策卡 / 台账 id / 分册修订 | __ | +## 文档检查与重要缺口 -（B 级阻断项单独置顶；本视图为临时审阅清单，结论回写各分册与台账。） +- 当前范围的完整性、一致性和必要验算结论：__。 +- 影响施工或涉及多分册的重要缺口及详细位置：__。 +- 游戏或素材验收条件及已有验证结果见对应分册，不重复列检查清单或未执行事项。 -## 验收总状态 - -| 件 | 最近验收 | blocker | 结论 | -|---|---|---|---| -| 01 | __（按项目平台验证 @__） | __ | __ | -| 02 | __（技术+视觉两维 @__） | __ | __ | -| 03 | __（七查 @check_id） | __ | __ | - -任一件有 blocker：禁止对应方向的内容扩充（数值 blocker 冻结填数与接入；资产 blocker 冻结扩产；程序 blocker 冻结下个里程碑）。 +详细问题在对应分册维护，解决后补齐正文并移出缺口汇总；不依赖固定状态标签判定是否完备。已有采用值不自动登记调优待办，范围外内容不自动列为后续里程碑。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/tdd-tech.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/tdd-tech.md index 166e0aa10..435ce7a5a 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/tdd-tech.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/tdd-tech.md @@ -1,96 +1,58 @@ -### C3 01_技术实现/模板.md（→ templates/tdd-tech.md） - -本模板是技术实现的参考结构。按当前运行时、系统复杂度和用户要求选择章节；没有对应系统、界面、输入、音频或存档需求时，删除相应内容，复杂项目可增加施工所需章节。表格和系统条目可按实际实现范围扩展，不代表数量上限。 - # 技术实现：《游戏名》 -> 状态：{drafting / reviewed / frozen}　|　基于 GDD：架构层@v{N}　|　数据侧契约：data/contracts@v{M} -> **目标运行时：{HTML / Unity / Godot / Cocos}（由 GDD 平台事实锁定）**　|　预览：{按项目平台验证 / 引擎=编辑器内预览}　|　导出：{HTML=自包含 / 引擎=引擎命令行导出} +按实际范围选择和合并章节，写全设计要求与实际工程约束；来源及版本见总册。内部实现由施工方决定，有必要提供的实现建议应与必须遵循的约束区分。 -## 系统行为规格（收编章） +## 当前范围与工程约束 -### S01 __（基于系统文档@v{N} 收编） -- 玩家行动：__（收编全文） -- 状态与规则：__（收编全文） -- 反馈需求：__（收编全文） +- 本次实现的功能与边界：__。 +- 已定平台、框架约束、实际工程入口：__。 +- 构建产物与已有资源位置或交付要求：__。 -### S__ … +选型限于 TDD 总纲规定的 Web、Unity、Godot、Cocos Creator；新二维 Web 使用 npm + Vite + Phaser 4.2.1，已有工程沿用实际结构。 -## UI 交互规格 +## 系统行为与协作 -| 界面 | 元素与布局 | 流转（入口→出口） | 触控版式 | -|---|---|---|---| -| __ | __ | __ | __（热区≥44px 落位） | +| 系统或流程 | 输入与条件 | 状态变化与结果 | 失败或中断 | 反馈与协作 | +|---|---|---|---|---| +| __ | __ | __ | __ | __ | -## 来自 GDD 的功能 +复杂行为可展开为段落、步骤或图，规则和当前采用参数写全。 -| 系统（P0） | 一句话职责 | 拥有的主数据 | +## 工程与接入约束 + +- 需遵循的已有接口、数据格式和资源约定：__（没有则省略，不为填表新建契约）。 +- 行为说明尚未覆盖的信息来源、对象关系和结果归属：__。 +- 适用的存档内容、时机、恢复结果与失败反馈：__。 + +源码目录、内部函数与字段、配置载体、存储和加载机制由施工方根据工程选择，不作为必填内容。 + +## 界面与操作 + +| 界面或操作 | 元素与布局 | 进入、退出与状态流转 | 输入与反馈 | 适配要求 | +|---|---|---|---|---| +| __ | __ | __ | __ | __ | + +## 场景、镜头与音频 + +写明当前需要的坐标、尺寸、碰撞、镜头行为、动画与音频触发及参数：__。 + +## 依赖、限制与风险 + +| 依赖或能力 | 来源、版本及配置 | 用途与限制 | |---|---|---| | __ | __ | __ | -## 技术目标与平台事实 - -- 平台事实（由 GDD 平台事实锁定）：__。 -- 技术目标：__（可测量，如"首屏可玩 ≤ __ 秒"）。 - -## 技术风险 - -| 风险 | 影响 | 缓解 | 校验方式 | -|---|---|---|---| -| __ | __ | __ | __ | - -## 运行时能力边界 - -| 能力（按项目实际使用的能力填写） | 落位（按所选运行时） | 状态（原生/自封装/受限） | 说明 | -|---|---|---|---| -| 瓦片地图渲染 | __ | __ | __ | -| 寻路 | __ | __ | __ | -| 2D 帧动画 | __ | __ | __ | -| 分辨率适配 | __ | __ | __ | -| 音频 | __ | __ | __ | -| 移动与碰撞 | __ | __ | __ | -| 存档 | __ | __ | __ | - -（运行时对照速记：瓦片地图——Unity Tilemap／Godot TileMap 节点／Cocos TiledMap 组件／HTML Canvas 自绘；寻路——Unity NavMesh／Godot NavigationServer／Cocos 寻路组件或自写 A*；音频——Unity AudioSource+Mixer／Godot AudioServer 总线／Cocos AudioSource／HTML WebAudio；存档——引擎侧 PlayerPrefs/文件系统，HTML 侧 localStorage+导出。） - -## 代码组织概览 - -- 目录结构：__（承架构层目录映射：入口/场景/系统模块各在哪）。 -- 命名与边界：__（文件前缀、模块间允许的调用方向）。 - -## 外部库与 skill 引用 - -| 需求 | 用什么 | 来源与版本 | 实例化参数 | -|---|---|---|---| -| __ | __ | `skill@版本` / CDN / 手写 | __ | - -## 场景与镜头 - -| 项 | 规定 | 依据（台账/代决） | -|---|---|---| -| tilemap 结构 | __（尺寸/tile 大小/层数及用途） | __ | -| 镜头行为 | __（跟随/边界/变化） | __ | -| 关卡数据 | __（文件格式与位置） | __ | - -## 输入与操作 - -| 动作 | 键盘 | 触控 | 备注 | -|---|---|---|---| -| __ | __ | __ | __ | - -## 音频 - -| 用途 | 格式/规格 | 触发点 | 依据 | -|---|---|---|---| -| __ | __ | __ | __ | +重要风险、影响、处理办法及待核实内容：__。 ## 构建与验证 -- 构建：__（命令/流程）。 -- 验证分级：自动__（跑什么、看什么输出为过）；半自动__（按项目平台验证步骤）；手测__（谁试玩、观察什么）。 +- 实际构建与交付约束、产物：__。 +- 正文尚未说清的行为验收条件与必要场景：__；数据、视觉等已有判据引用对应分册。 +- 有实际依据的性能目标及适用条件：__（没有则省略）。 +- 已有检查结果或针对具体疑虑的验证计划：__（未执行不写通过）。 -## 版本里程碑 +本节可与相关行为合写，不复制整套规格；测试脚本、执行顺序与测量工具由施工方安排。 -| 版本 | 内容 | 判据 | -|---|---|---| -| __ | __ | __ | +## 待解决问题 + +按需写明设计或实际接入缺口、具体体验疑虑、影响和下一步；解决后补齐正文并移出待办。影响当前施工的关键问题未解决时，本册尚未完备；未预定内部实现不算设计缺口，已有采用值不自动登记调优待办。没有问题时省略本节。 diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/top-design.md b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/top-design.md index 437fcc545..8bdbf3a5d 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/top-design.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/resources/templates/top-design.md @@ -1,122 +1,27 @@ -### C1 模板_顶层设计.md（→ templates/top-design.md） - -填写前按项目实际存在的循环、资源、时间层级和用户要求筛选本模板的章节；同类内容可合并，复杂项目可增加必要内容。表格、列表和循环示例按实际内容扩展。 - # 顶层设计：《游戏名》 -## 顶层定位与规模锚点 -核心定位：__。 -容易混淆的方向及排除理由（按需）：__。 +以下为参考结构，可按项目需要合并、拆分或省略。提示问题用于帮助组织内容，不要求逐项填写。 -顶层设计让玩家每天都在想： -> "__" +## 玩法目标 -| 项 | 定义 | -|---|---| -| 循环单位 | __ | -| 段落构成 | __ | -| 操作复杂度 | __ | -| 经营复杂度 | __ | -| 长期主轴 | 第一 __；第二 __；__ 只做辅助 | +玩家的主要行动与回报怎样实现概念中的体验？ -## 设计目标 -玩家在 __ 循环中同时获得：__、__、__，三者互相供给：__。 +## 游玩过程与节奏 -## 核心推动力 -- 动机主次：__。 -- 即时推动：__。 -- 日程推动：__。 -- 季节推动：__。 -- 长期推动：__。 +玩家如何开始、行动、获得反馈，过程如何变化或结束？有哪些关键规则？存在重复或长期推进结构时，它们如何连接？ -## 大循环 -**__ → __ → __ → __ → 回到 __。** +## 资源与进展 -```mermaid -flowchart LR - A[__] --> B[__] - B --> C[__] - C --> D[__] - D --> E[__] - E --> A -``` +实际有哪些资源、状态或进展？它们怎样获得、变化、使用及受到限制？ -## 小循环 +## 选择与后果 -### __循环 -__ → __ → __ → __ → __。 +哪些选择影响体验，各自的结果、收益与代价是什么？存在失败时，会失去或保留什么，怎样恢复？ -### __循环 -__ → __ → __ → __。 -（以上为示例，可按实际循环删减或扩充。） +## 系统范围与版本边界 -## 资源流与输入输出 +支撑玩法需要哪些能力，各自的目的、边界与关系是什么？当前版本包含什么，排除什么？ -```mermaid -flowchart LR - A[__来源] --> B[__储存] - B --> C[__消耗] -``` +## 原型验证与开放问题 -- 主要输入：__。 -- 主要输出：__。 -- 反馈四层：立即 __；短期 __；中期 __；长期 __。 - -## 最小体验单位 -__。 -保留的玩家行动应有与玩法相称的可理解反馈：__。 - -## 核心活动流程 - -| 阶段 | 玩家行为 | 设计目的 | -|---|---|---| -| __ | __ | __ | -（按实际阶段逐行补充。） - -## 取舍表 - -| 决策 | 立即收益 | 延迟收益 | 主要代价 | -|---|---|---|---| -| __ | __ | __ | __ | - -## 节奏结构 -- 日内节奏：__。 -- 周内节奏：__。 -- 季节/章节节奏：__。 -- 长期节奏：__。 -（以上为示例，可按实际节奏层级删减或扩充。） - -整体情绪在"__"与"__"之间摆动（恢复来源：__；变化来源：__）。 - -## 失败与回收 -失败主要表现为：__。 - -| 情况 | 结果 | -|---|---| -| __ | __ | - -## 系统范围 - -| 系统 | 顶层目的 | 边界（本层不做什么） | -|---|---|---| -| __ | __ | __ | - -## 范围与非目标 -最小完整版本包含：__。 - -不做清单：__。 - -## 验证标准 - -| 验证点 | 成功标准 | -|---|---| -| __ | __ | -（按实际验证点逐行补充。） - -## 开放问题 -- __ -（按实际问题逐条补充。） - -## 顶层定稿 -顶层当前定稿为：__。 -后续架构必须围绕 __ 拆系统；不得 __。 +需要判断哪些设计问题，为此需要怎样的原型内容和游玩跨度？通过哪些观察、反馈或指标作出判断？哪些问题影响当前设计，哪些可以后续展开？ diff --git a/apps/ai-game-creator-shell/src-tauri/design-agent/system-prompt.md b/apps/ai-game-creator-shell/src-tauri/design-agent/system-prompt.md index deb3a18c0..ac23c9701 100644 --- a/apps/ai-game-creator-shell/src-tauri/design-agent/system-prompt.md +++ b/apps/ai-game-creator-shell/src-tauri/design-agent/system-prompt.md @@ -1,15 +1,17 @@ -你是游戏策划协作 Agent，与用户持续协作完成游戏设计。像普通策划同事一样交流，使用工作区文件工具读写资料；所有文件路径使用相对路径。根据当前对话、阶段上下文和已有文档决定下一步行动。修改文件后，简要说明修改内容和相对路径。对不确定内容区分用户确认、Agent 建议和待原型验证事项。 +你是游戏策划协作 Agent，与用户持续协作完成游戏设计。像普通策划同事一样交流，使用工作区文件工具读写资料；所有文件路径使用相对路径。根据当前对话、阶段上下文和已有文档决定下一步行动。 优先完成能够依据已有信息推进的工作。局部、可逆的问题可以先提出合理方案并标为暂定。会影响当前阶段范围、关键规则、下游实现或其他重要方向，且必须由用户决定的问题，应先通过纯文本或问询工具询问，等待用户回答。决定稳定后，再更新受影响的正式产物和必要的过程记录，并完成阶段审批前的检查。 -分析阶段优先记录当前目标、上层约束、候选方案、取舍、用户已确认或 Agent 暂定的边界，以及必须检查的验收项。形成结论后直接写入正式产物，再进行一次必要的一致性检查；按用户要求展开讨论。文件操作前只需说明简短计划、目标文件和主要变化。 +分析围绕当前目标和约束展开，存在值得比较的方案时再展开比较。形成结论后更新受影响的正式产物，再进行一次必要的一致性检查；按用户要求展开讨论。文件操作前只需说明简短计划、目标文件和主要变化。 + +根据具体项目的需求、规模和复杂度安排文档结构与内容密度。模板和样例仅供参考，可按实际需要增加、合并或删减章节与字段，不逐项照搬。简单内容简要说明，复杂或容易产生歧义的部分充分展开；不为填满模板增加设计、重复论证或编写无关内容。精简后仍须保留当前阶段判断和后续实现所需的信息。 正式策划文档在文档头部写明版本标记，例如“版本：v1”。由你自行维护版本号：只有整体修订、阶段性定稿或用户意见造成实质内容变化时才递增；错别字、措辞润色、单个局部修改和小范围补充不单独递增。 阶段审批是五个策划阶段各自的最终检查，将已完成的本阶段产物交给用户检阅。需要用户选择的关键问题先通过问询解决，阶段审批不承担问询功能。提交前，解决所有影响本阶段完成的关键问题，或明确说明它们不阻塞本阶段交付，并更新相关产物。可以保留不阻塞当前阶段的后续事项和待原型验证项。 -过程文档用于记录关键依据、决定和待办，不要求实时完整，也不应重复正式设计文档。阶段内优先完成主要设计内容；只有稳定且影响后续工作的决定才需要同步到多个过程文档。阶段提交前，补齐影响验收的关键记录。 +共享文档按用途和内容变化维护，不逐轮更新或重复登记同一决定。分析文档按需保留重要取舍的依据与当前结论；待办变化时更新决策台账，完成后移出待办；对话摘要或交接记录仅在用户需要时维护；速览卡只在概览内容或设计入口变化时更新。可以合并、修订条目，只保留理解当前决定所需的历史依据。未决事项说明原因或下一步，不要求固定状态、连续编号、候选数量或每项推翻条件。阶段提交前检查影响交付的信息是否一致。 阶段获批后，产物中已经采用的方案作为后续工作的依据，并保留原有决策来源。用户主动质疑或出现新的约束冲突时，再重新讨论相关决定。 diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index 28d8e2a64..02d1a063e 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -1,5 +1,78 @@ # 决策记录 +## 2026-09-28 速览卡只承载概览、范围与设计入口 + +- 速览卡帮助读者快速理解游戏及本次范围，分类、支柱、循环与目标玩家可融入概述；不复制系统拆分、具体参数、素材数量、完整排除清单或验证计划，不设固定字数或必填章节。 +- 仅在概览内容或入口变化时维护，只链接已有且有用的文档；影响方向或当前范围的重要未决问题简述并引用详细位置。注入说明与样例同步清理，概念阶段必需产物路径、资源登记及审批合同不变，已有用户项目不自动改写。详见[策划 Agent 生产迁移方案第 6 节](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md#6-阶段与提示词注入)。 + +## 2026-09-28 TDD 验证按需去重，范围外内容不自动规划 + +- 验收判据与必要场景在对应分册完整写一次，其他位置引用并补充独有要求；总册汇总重要结论和缺口，不复制清单。必要数值验算保留，不重复行为状态推演，也不能代替运行验证。 +- 实际构建、交付约束与设计验收条件保留；测试脚本、顺序、截图数量和工具由施工方安排。性能目标与专门验证须有实际依据，未执行不得记录通过。 +- 当前采用值不自动登记调优待办；具体体验疑虑按需验证，不默认制作对照版本。架构和 TDD 对范围外内容只说明必要边界，已确定的后续计划或影响当前设计的要求按需补充，不自动承诺里程碑及扩展实现。TDD 独立施工、四份产物与关键缺口判据不变。详见[策划 Agent 生产迁移方案第 6 节](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md#6-阶段与提示词注入)。 + +## 2026-09-28 TDD 明确设计要求，内部实现由施工方决策 + +- 保留“只看本套 TDD 就能完成当前范围实现”：写全设计要求、内容与数值、实际工程约束和验收条件，施工方无需回查 GDD 或猜测关键设计。代码组织、算法、内部接口、数据结构、配置载体及资源命名和打包由施工方决定，未预定这些选择不构成策划缺口。 +- 已有工程契约、数据与资源格式、明确交付要求仍须遵循；实现建议不作为唯一方案，不增加逐项登记或用户确认。固定规则不要求配置化，也不禁止施工方使用配置；不承诺尚未定义的模式或开关。文档统一使用“施工方”称谓。 +- TDD 总纲、三分册规则、四模板、四样例及上游交接同步这一边界；样例仍保留真实的玩法、内容、数值与表现缺口，未执行验证不写通过。四文件、资源登记、技术范围、阶段审批与已有项目产物均不变。当前合同见[策划 Agent 生产迁移方案第 6 节](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md#6-阶段与提示词注入)。 + +## 2026-09-28 架构与系统按行为组织协作，减少重复展开 + +- 系统拆分以有用的独立规则边界为依据，简单职责可合并，不因变量、操作不同或未来替换而增加系统和协作层。架构保留职责、关键协作与共享约束，数据归属和文档位置可合写。 +- 完整流程在主要负责的系统文档展开，参与方写自身接收、处理和返回，按需引用；行为已说明的协作与反馈不再另表复述。规则、相关模板与样例同步，关键顺序、失败处理及 TDD 独立施工要求保留，已有项目产物不自动改写。当前合同见[策划 Agent 生产迁移方案第 6 节](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md#6-阶段与提示词注入)。 + +## 2026-09-28 数据分册按数据形态组织，避免重复列值 + +- 少量参数合写含义与当前值，同结构多条内容可分列共用属性说明和完整记录；文案集中列一次，其他位置引用唯一权威定义，共用规则集中说明，派生值只保留计算关系。内部字段与配置载体由施工方决定，实际数据契约按需保留。 +- 数据模板、写作规则及样例采用同一口径，当前范围完整内容、数值、文案与验算要求不变。当前合同见[策划 Agent 生产迁移方案第 6 节](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md#6-阶段与提示词注入)。 + +## 2026-09-28 策划文档密度按项目需求与复杂度安排 + +- 常驻提示词统一要求按项目需求、规模和复杂度组织内容；模板与样例仅供参考，章节和字段按需增减、合并，简单内容简述，复杂或易歧义处充分展开，不为填模板增加设计或重复论证。 +- 精简保留当前阶段判断与后续实现所需信息，TDD 可独立指导当前范围实现的标准不变。当前合同见[策划 Agent 生产迁移方案第 6 节](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md#6-阶段与提示词注入)。 + +## 2026-09-27 TDD 按施工信息简化，验收对象为策划案 + +- 保留“只看本套 TDD 就能完成当前范围实现”的标准。文档、数据引用与必要验算须完整自洽；保留实际构建与交付约束、验收判据及必要场景，具体测试安排由施工方决定，不要求游戏或素材在策划案验收前已经完成，未执行不得记录通过。 +- 技术选型限定在 Game Agent 已支持的 Web、Unity、Godot、Cocos Creator 范围，不逐框架说明支持程度；新 Web 使用 npm + Vite，二维使用 Phaser 4.2.1，三维按需求选型，预览与导出读取 dist。已有工程不因模板自动迁移。 +- 收编可重组内容，来源版本集中维护；取消固定编写顺序、能力清单、建表步骤、条件架构、检查分级及资产生产台账。数据保留完整内容、数值、文案与验算；美术保留表现要求、对象与状态、用途及实际接入约束；四份必需产物、资源登记与阶段审批不变。 +- 星露谷 TDD 样例统一首个日常原型，具体参数是示例假设，当前施工缺口如实标明，不能将局部算术或未核验的原作资料当作完备证据。当前合同见[策划 Agent 生产迁移方案第 6 节](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md#6-阶段与提示词注入)。 + +## 2026-09-27 系统文档按实际行为展开 + +- 系统层围绕触发、规则、状态变化、结果与协作组织内容，取消固定十二节、编号追溯、统一取舍表和枚举表达要求；类型规则与模板按需使用，不为填模板添加机制或预设玩法。 +- 十二类资料保留领域问题，职责和数据归属遵循实际架构；UI 维护自身交互与临时状态，正式玩法校验和结算归对应系统。跨系统行动明确成功、失败与中断后的结果。 +- 已定规则、单位和参数留在系统文档，TDD 按相关内容收编并补齐，不依赖固定交接章节；Sxx、产物路径与审批合同保持不变。战斗样例区分暂定原型、撤退与倒下后果及规格缺口，TDD 继续以当前范围可独立施工为完成标准。 +- 当前规则见[策划 Agent 生产迁移方案第 6 节](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md#6-阶段与提示词注入)。 + +## 2026-09-27 系统架构按职责与协作组织 + +- 架构保留系统编号、职责、权威数据归属、文档位置、实现范围和验证，取消固定系统数量、P0 必需性、统一图表与分类、逐轮变更记录。双向交互按含义与更新顺序判断，不以图上有环自动要求重切。 +- 同一事实由明确的权威方维护；只读副本、派生视图和快照说明来源及更新或恢复方式。必要的规则与参数可在架构明确，由系统文档展开、TDD 收编补齐。 +- `project/03_systems/...` 是策划文档映射，不决定代码目录。系统与 TDD 的直接引用按实际范围衔接，TDD 仍须写全当前施工所需规格；星露谷首个原型包含基础采集，单日选择与多日成长分别验证，样例缺口如实列明。 +- 当前规则见[策划 Agent 生产迁移方案第 6 节](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md#6-阶段与提示词注入)。 + +## 2026-09-27 顶层设计按实际玩法展开 + +- 顶层说明游玩过程、关键规则与反馈、资源与进展、选择后果和版本范围；取消固定循环层级、回报数量、资源消耗链、日历节奏和失败档位，允许说明玩法所需的具体参数。 +- 原型范围依据验证问题确定，与完整版本范围分开；验证可结合观察、玩家反馈和指标，预期与已验证结论分清。 +- 架构按顶层已有内容检查玩法覆盖，可拆分、合并能力范围并由多个系统协作，不依赖固定循环图、独立定稿章节或逐项映射。TDD 自足性、产物路径和审批合同保持不变。 +- 当前规则见[策划 Agent 生产迁移方案第 6 节](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md#6-阶段与提示词注入)。 + +## 2026-09-27 概念设计按内容组织，取消固定填写程序 + +- 概念层先利用已有对话与资料，按实际缺口补问；模板和样例按需参考，不强制参照、固定句式、字数、唯一卖点、六项锚点或调性编号。 +- 概念明确核心体验、主要吸引力和重要边界。设计原则帮助判断方向，不代替具体分析；必要的数值、操作或界面信息可以用于说明概念，规模按实际团队与项目条件确定。 +- 规则、模板、样例及下游引用同步调整：重要取舍与视觉设计依据按具体内容或章节引用，不要求张力编号或 T 原则；TDD 继续保留来源版本及完整施工规格。现有产物路径与审批合同不变。 +- 当前规则见[策划 Agent 生产迁移方案第 6 节](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md#6-阶段与提示词注入)。 + +## 2026-09-27 策划共享文档按用途和内容变化维护 + +- 分析文档按需保留重要取舍依据，决策台账集中待处理事项，对话摘要仅在用户需要时维护，速览卡仅随概览内容变化更新；取消概念至系统分册中的重复状态、连续编号和多处登记流程。TDD 同步取消逐项代决登记，规格直接写入 TDD，未决问题解决后补齐正文并关闭待办。 +- 保留“只看 TDD 就能完成当前范围实现”的标准，以及内容收编、来源版本、变更同步和施工所需清单；影响当前实现的关键问题未解决时不能宣称完备。文件路径与现有审批存在性检查不变，不增加内容校验，不批量改写已有项目文件；旧 `resources/SKILL.md` 合并总稿已删除，现役规则由全局提示词、阶段上下文及资源目录登记的分册承接。 +- 当前维护规则见[策划 Agent 生产迁移方案第 6 节](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md#6-阶段与提示词注入)。 + ## 2026-09-22 UI 编辑器预览画布补上右键拖拽平移，节点菜单改为右键抬起弹出 - 背景：预览画布此前只有中键与空格+左键平移，右键整段留给节点操作菜单（`UiTreeRenderer.onContextMenu` 直接弹 `UiNodeContextMenu`）。这次要补右键拖拽平移，并要求"拖拽过就不许再触发右键菜单"。实测（Linux Chromium 151 / Firefox 151，真实 X11 输入）确认 `contextmenu` 在**按下**瞬间触发，且原生菜单一旦弹出，页面之后收不到任何 `pointermove` / `pointerup` / `mouseup` / `auxclick`，所以"先让菜单弹、拖拽时再关"在浏览器层面不可行；headless 没有原生菜单，Playwright 复现不出该行为。macOS 的 `contextmenu` 在 mouseup 触发（本容器无法实测），但同一条实现路径对两种时序都成立。同一次实测：键盘菜单键触发的是 `button: -1`，所以"只认按钮 2"的拦截天然把键盘菜单留给原有节点菜单路径。 diff --git a/docs/technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md b/docs/technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md index ed7e775da..5026014bf 100644 --- a/docs/technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md +++ b/docs/technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md @@ -233,6 +233,16 @@ get_workflow_status ## 6. 阶段与提示词注入 +常驻提示词统一要求按具体项目的需求、规模和复杂度安排文档结构与内容密度。模板和样例仅供参考，章节与字段可按需增加、合并或删减；简单内容简述，复杂或易歧义处充分展开，不为填模板增加设计、重复论证或无关内容。精简须保留当前阶段判断与后续实现所需信息，TDD 仍须独立指导当前范围的实现。 + +2026-09-27：常驻提示词删除每次修改文件后汇报修改内容和相对路径、将不确定内容统一分为用户确认／Agent 建议／待原型验证事项的要求。汇报形式按当前协作需要决定；仍按后文规则标注暂定方案并就关键问题询问用户。提示词简化可以调整核心行为，以调整后的行为是否合理作为评估依据。 + +概念层规则、模板和样例围绕核心体验、主要吸引力与重要边界组织。先利用已有对话和资料，仅按影响当前设计的缺口补问；模板与样例按需读取，参照只说明具体借鉴点，不自动继承参照作品的全部设计。章节按项目需要选取，不要求固定句式、字数、唯一卖点、六项锚点、调性滑杆、T 编号或重复定稿，也不要求先回答固定定调问题或标注“零参照”。 + +概念层的设计原则帮助后续判断方向，不替代具体问题的分析。说明核心体验所需的数值、操作方式和界面形式可以保留，详细规则、数值平衡和界面规格留待后续展开；规模依据实际团队和项目条件确定。交付检查聚焦概念是否清楚、是否符合已有意图和约束、是否存在影响交付的矛盾或缺口，避免为填模板编造内容。 + +下游按相关内容或章节承接概念，不强制张力逐条对应或附编号；TDD 美术规则与样例不再依赖概念层固定第 2 节或 T 原则。美术圣经保留设计依据及来源版本，并在 TDD 内写全视觉规格；总册引用对应 TDD 分册，继续满足只看 TDD 即可完成当前范围实现的标准。资源路径、产物路径及阶段审批合同保持不变。 + 阶段顺序固定为： ```text @@ -276,7 +286,7 @@ concept → top_design → architecture → systems → tdd → consultant | 技术文档 | `project/04_tdd/01_技术实现.md`、`project/04_tdd/02_美术圣经.md`、`project/04_tdd/03_数据与配表.md`、`project/04_tdd/总册.md` | | 顾问态 | 不提交下一阶段审批 | -`systems: []` 是已确定的行为，不是迁移时需要补齐的缺口。`project/analysis.md`、`project/决策台账.md`、`project/dialog.md` 保持原型中的共享过程文件口径，不升级为新的审批必需项。速览卡保留原型结构提示，但 Runtime 与 UI 不解析其章节或内容字段。 +`systems: []` 是已确定的行为，不是迁移时需要补齐的缺口。`project/analysis.md`、`project/决策台账.md`、`project/dialog.md` 保持原型中的共享过程文件口径，不升级为新的审批必需项。速览卡采用下述简短概览结构，Runtime 与 UI 不解析其章节或内容字段。 提示词中的路径是策划 Agent 使用的相对路径约定： @@ -285,7 +295,58 @@ concept → top_design → architecture → systems → tdd → consultant 这些路径直接服务于 Agent 的文件操作和资源查阅，属于提示词应保留的契约；即使阶段上下文也注入了某条产物路径，分册和模板中的路径仍提供目标文件与交叉引用的具体定位。去除客户端与宿主实现细节时，不应把这类相对路径当作意外暴露的内部实现；宿主安装目录、项目绝对路径及会话控制文件位置才不属于 Agent 的操作输入。 -过程文档记录关键依据、决定和待办，不要求实时完整，也不应重复正式设计文档；阶段提交前补齐影响验收的关键记录。顶层设计的分册、模板和示例保留核心定位及按需说明的易混淆方向与排除理由，不强制使用固定的“不是 X，而是 Y”句式。 +共享文档按以下职责维护，文件路径和审批必需产物清单保持不变： + +| 文档 | 用途与更新时机 | +| --- | --- | +| `project/analysis.md` | 按需保留重要取舍的依据与当前结论；存在实际备选时再比较，未决问题说明原因或下一步。结论稳定或依据变化时更新，可合并修订条目，不记录每次讨论。 | +| `project/决策台账.md` | 按需集中列出待处理事项和下一步，必要时引用分析或正式设计。事项变化时更新，完成后移出待办，不再重复保存全部已采用决定。 | +| `project/dialog.md` | 仅在用户需要对话摘要或交接记录时维护，不逐轮转录聊天。 | +| `project/速览卡.md` | 概念阶段形成简短游戏概览、当前范围与已有设计入口；仅在概览内容或入口变化时更新，不复制系统表、参数、素材数量、完整排除清单或验证计划。 | + +正式设计承载当前采用的规则，共享文档按各自用途记录，不要求同一决定在多处重复登记。不强制连续编号、状态枚举、候选数、问题数量、推翻条件或完整历史流水；尚未确定的事项用自然语言说明，不冒充用户确认。阶段提交前检查影响交付的信息是否一致，不以补齐过程记录作为新门禁。已有项目文件不批量重写或删除。 + +速览卡让读者快速了解游戏、当前准备做什么及详细设计的位置。分类、支柱、循环和目标玩家可合入概述，不再分别展开；不设固定字数，也不要求填满参考结构。只提示会改变方向或当前范围的重要未决问题，并引用详细位置；设计入口仅链接已存在且有用的文档，不为填卡新增范围或未来计划。注入说明与星露谷样例同步，样例清除旧 NPC、图标和换装数量，按当前日常原型概括；`project/速览卡.md` 仍为概念阶段必需产物。 + +TDD 的决策记录采用相同原则：设计要求、当前采用值和实际工程约束直接写入对应分册，重要取舍按需保留分析，未决事项说明影响与下一步，不要求逐项登记到外部台账或附推翻条件。总册保留施工索引、跨分册约定与重要缺口，详细问题指向对应分册。问题解决后更新受影响的 GDD 与 TDD 正文并关闭待办，不能只登记处理去向。 + +“施工方只看 TDD，应能完成当前范围的实现”仍是完成标准：设计要求、内容与数值、实际工程约束和验收条件写全，施工方无需回查 GDD 或猜测关键设计。保留来源版本与变更同步，外部分析与台账不能代替正文。代码组织、算法、内部接口、字段与数据结构、配置载体、资源命名与打包由施工方自主决定；未预定这些实现选择不构成策划缺口。已有工程契约、实际数据/资源格式和用户明确交付约束必须记录；有依据的实现建议可供参考，不成为唯一方案，也不增加逐项登记或用户确认。 + +TDD 阶段验收对象是策划文档：当前范围的行为、内容、数值、界面、表现要求与实际接入约束须完整、自洽，完成文档一致性、内容关系和必要数值验算。奖励、失败后果、关键视觉状态等设计缺口须补齐；函数签名、源码目录、内部字段或打包格式未预定不阻塞验收。保留实际构建与交付约束，验收条件明确，必要时给代表性场景；测试脚本、执行顺序、截图数量和测量工具由施工方安排，性能指标与专门验证须有实际目标或风险依据。不要求产品或资产已经完成，只有实际执行过才能记录通过。当前采用的设计值明确，后续调优不能代替当前设计。 + +同一验证的场景、判据和结果在对应 TDD 分册完整写一次，其他位置引用并只补充独有要求；总册汇总重要结论、缺口与位置，不复制清单。不强制每册单列完整验证章节或新增统一验证表。数据册保留必要数值计算，不重复技术册的行为状态推演；文档验算与实际运行检查不能互相代替。当前采用值不自动成为调优待办，只有具体体验疑虑才记录验证问题，不默认安排替代版本对照。架构与 TDD 对范围外内容简述边界，只有已确定的后续计划或确实约束当前设计的要求才补充，不自动承诺里程碑或扩展实现。规则、模板与样例同步，已有用户项目不批量改写。 + +TDD 总纲与技术分册把选型限定在 Game Agent 已支持的 Web、Unity、Godot、Cocos Creator 范围，不逐框架分级说明支持程度。新 Web 使用 npm + Vite，二维使用 Phaser 4.2.1，三维按需求选择适用技术栈；依赖由 npm 管理，预览和导出使用包目录下的 `dist/index.html`，运行素材随构建进入 dist。已有工程沿用实际结构，不因模板自动迁移。该约束与 GameAgent 的 `prompts/runtime/texts/direct.json` 工程提示、`src/project/manifest.rs` 脚手架一致；本轮不修改 GameAgent 提示词或运行时。 + +TDD 按实际内容组织，可重组 GDD 规则而不要求逐段全文复制；来源版本集中在总册记录，设计变化同步受影响正文。取消固定编写顺序、必读样例、统一图表和逐项登记要求。技术分册写行为、工程约束、存档要求及验证，已有接口按契约描述，不为新项目预定代码目录或内部调用。数据分册写全当前内容、数值、关系与文案及可复核验算，不以示例行代替，也不强制写成可加载配置。美术分册写共性表现、对象与状态、用途及验收，已有素材记录真实接入约束，不通用强制帧键、图集、命名或目录。 + +总册保留当前范围、分册索引、来源版本、实际跨分册约定与重要缺口，不重复生产验收表或以 frozen 标签判定通过。`project/04_tdd/01_技术实现.md`、`02_美术圣经.md`、`03_数据与配表.md`、`总册.md` 四个产物继续保留，不涉及的方向在分册简述原因。十二份 TDD 规则、模板和样例同步这一口径；星露谷样例聚焦首个日常原型，数值与素材规格标明示例假设，未附证据的原作实证、构建通过和资产验收声明清理，规格与验算缺口如实保留。资源 ID、路径、阶段注入及 Runtime 的文件存在性检查不变。 + +数据模板将含义、关系与完整内容合写：少量参数直接列当前值与单位，同结构多条内容可共用属性说明；文案集中列一次，其他位置引用唯一权威定义。固定行为写在相关规则中，是否配置化由施工方选择，不为未来可能变更承诺尚未定义的模式或开关。派生值保留计算关系，不重复登记；已有数据格式或明确要求交付可加载数据时，才按实际契约补充字段、类型、默认或必填规则。当前范围完整内容、文案和验算要求保留。 + +写作规则由 `system-prompt.md`、`phase-context/`、资源目录登记的 `skills/` 与各分册承接；重复且过期的 `resources/SKILL.md` 合并总稿已删除，历史由 Git 保留。 + +顶层设计将概念展开为游玩过程、关键规则与反馈、资源与进展、选择后果、版本范围及验证计划。规则、模板和样例按实际玩法组织，不强制三层循环、三种互相供给的回报、资源“来源—储存—消耗”链、日历节奏、反馈层数、唯一原型片段或失败三选一；最优解是否成立取决于玩法，必要的规则与参数可以在顶层明确。保留核心定位及按需说明的易混淆方向与排除理由，不强制固定句式或结尾重复定稿。 + +原型范围由要验证的问题决定，与完整版本范围分别说明；验证可以结合试玩观察、完成情况、玩家反馈和指标，明确如何形成判断，不把未验证的预期写成结论。星露谷样例按选择双方的收益与代价比较，按场景说明损失与恢复，并区分单日、多日和后续内容的验证范围。 + +架构层承接顶层已有的玩法描述、能力范围、版本边界和验证计划，按实际职责、状态与数据边界拆分或合并系统，不要求顶层清单逐项对应系统。规则、模板与样例围绕系统职责、协作和数据归属、系统文档映射、实现范围及验证组织；取消固定系统数量、每个系统必须属于 P0、“不负责”必填列、图表格式、状态分类、数值基准分类和逐轮变更记录。重要取舍按需保留依据。 + +拆分应带来有用的独立规则边界，不因变量、操作不同或未来可能替换就单独设系统；简单职责可在同一系统内部表达。架构概述关键协作，保留影响结果的顺序与共享约束，职责、数据归属和文档位置可合写，不重复建表。完整行为流程在主要负责的系统文档展开，其他参与方说明自身接收、处理与返回，按需引用完整流程并就近保留理解本系统所需的前提和结果。 + +系统交互区分调用、通知、读取与玩法反馈；双向关系不自动判为架构错误，按实际问题检查职责纠缠和更新顺序。主数据归属明确，实际需要的副本或快照说明来源与预期结果，不要求额外设计更新机制。系统文档展开行为，TDD 收编并补齐设计要求、内容与数值及实际约束，内部实现由施工方决定。 + +保留 Sxx 编号与 `project/03_systems/...` 文档位置，可以按内容合并或拆分文档；该映射不决定代码目录，代码模块与文件组织由施工方选择。实现范围区分完整版本、首个原型及后续内容，不固定 P0/P1/P2，也不要求验证失败就退回顶层或禁止调整系统划分。星露谷样例明确 NPC 日程、资源点、物品与经济等归属，首个原型包含基础采集，按单日选择和多日成长分别验证。 + +系统总纲、相关系统类型资料与 TDD 的直接引用同步承接职责、协作、数据归属和当前实现范围，不再依赖架构 P0 清单、固定依赖图或仅限定性的数值基准。数据侧按实际玩法选择验算场景与跨度；技术侧按当前施工范围收编全部必需行为，不能因某系统标为后续优先级而遗漏当前所需规格。速览卡与 TDD 样例同步首个原型范围，基础采集、跨日结算规格和完整数值验算的缺口如实标明，局部推算不作为验算通过的证据。施工完备要求、产物路径与阶段审批合同保持不变。 + +系统层按实际行为展开职责、触发条件、状态变化、结果、协作与反馈，类型规则、模板和样例按需使用，不要求先归入十二类之一。取消固定十二节、顶层条目编号、取舍表列、循环层级、“三不”、全部枚举及禁止段落等填写纪律；未决事项按影响处理，不只保留结构问题，也不把全部数值问题自动推给原型。代表性验证场景说明预期结果和判断依据，不冒充已完成验证。 + +这些维度是信息覆盖要求，不是独立章节要求。参与方、数据来源、处理顺序和反馈可随行为一次说明，已讲清的内容不再另列协作表或反馈章节；简单同步处理不额外设计消息、确认或中间状态。相关类型模板将协作与反馈并入具体行为，架构样例合并职责与文档映射、战斗样例将协作归属就近写入行为。去重不降低关键行为边界、结果一致性和 TDD 独立施工要求，不改写已有项目产物。 + +十二类系统资料保留类型特有的设计问题，模板不预填未经选择的动作、状态、循环和数据表。日历、生产队列、成长分支、复杂叙事、节日专属玩法和战斗定位均由实际项目决定；系统职责与权威数据归属遵循架构，UI 可以维护交互、导航和临时状态，正式玩法校验与结算仍由对应系统负责。跨系统行动明确整体成功或失败的预期结果，TDD 收编设计约束，具体实现机制由施工方选择。 + +系统文档保留已定规则、单位和参数，TDD 从相关内容收编并补齐设计与实际接入缺口，不依赖固定交接章节。系统编号、文档位置、资源登记及审批语义不变。战斗样例明确为后续矿井原型的暂定方案：实时基础动作、安全撤退保留成果、倒下可能损失部分钱物，未定设计和待执行验证如实标明；TDD 日常原型样例不提前收编后续战斗。样例中的代码、数据和资源组织不再作为预先设计或验收要求，仍缺少的玩法、内容、数值及表现如实保留。 进入下一阶段必须由用户批准触发。Runtime 推进后向 Agent 追加明确的用户行为语义，例如“用户已批准上一阶段，现在进入顶层设计阶段”，避免 Agent 误认为 Runtime 自行推进。