Imported from LudwigHugoL/RoadToImmortal (AGENTS.md). Install upstream with npx skills add LudwigHugoL/RoadToImmortal. Copyright stays with the author.

项目宪法

本文件是最高约束。任何代码、数据、UI 改动都必须遵守。 冲突时以本文件为准。

C1. 数据驱动

所有道具、技能、英雄、商店、战斗效果数据必须存放在 res://data/ 下的 JSON 文件中。

• 禁止在 GDScript 中硬编码物品名称、数值、冷却、触发条件。
• 允许集中存放少量全局参数，但必须集中在 RunManager / ShopSystem 等明确配置位置，并注释来源。

C2. 战斗模拟器是纯逻辑

BattleSimulator、BattleHero、BattleItem 必须是纯逻辑类：

• 不继承 Node
• 不引用任何 UI / 场景树节点
• 不直接读写 Autoload 里的 UI 状态
• UI 只能读取模拟器输出的 events 数组来播放表现

C3. 确定性随机

战斗中所有随机数必须使用 BattleSimulator 内部持有的 RandomNumberGenerator。

• 支持通过 seed 复现同一场战斗。
• 禁止在战斗逻辑中使用全局 randi() / randf()。

C4. 数据格式变更必须同步文档

修改任何 JSON 数据结构前：

1. 先更新 docs/02_ARCHITECTURE.md
2. 新旧格式必须给出兼容方案，或提供迁移脚本

C5. 禁止重复实现

新增系统前必须检查 docs/05_PROGRESS.md 和 docs/06_DECISIONS.md。 已经存在的功能不得重复实现。

C6. UI 热重载契约

UI 层不允许长期持有旧的 ItemData / ItemCombatData 对象引用。

• 必须监听 BazaarDB.data_reloaded
• 每次刷新时重新从 BazaarDB 查询

C7. 版权与资产

• 不直接使用 The Bazaar 原始美术资源。
• 所有视觉先使用占位卡片 / Unicode 符号 / 程序化配色。
• 如果未来引入自制美术，必须放在 res://assets/ 下。

C8. 两阶段工作流（强制门禁）

任何代码、数据、场景的修改，必须先输出分析报告，获得明确批准后才能执行。

• 阶段一（分析）：按附录 A 的模板输出报告，输出后立即停止，禁止输出任何代码、diff 或补丁。
• 阶段二（执行）：仅在用户明确回复"执行"（或等义指令）后，严格按报告中的计划修改，不得超出计划范围一行代码。
• 唯一豁免：用户消息中包含"快速修"三个字时，可跳过阶段一，但仍需遵守 C9（最小改动）。
• 如果不确定自己是否应该开始写代码，默认停在阶段一。

C9. 最小改动原则

• 只修改完成当前任务绝对必要的代码。
• 禁止顺手重构、重命名、重排 import、调整缩进、改代码风格。
• 禁止未经明确要求新增第三方依赖、新增文件、新增抽象层。
• 禁止"预防性"修复：发现任务外的问题，只在分析报告中列出，不动手修。
• 如果认为必须大改才能解决，必须在报告中逐条论证"为什么更小的改动做不到"，由用户裁决。

C10. 修改范围白名单与禁改区

• 分析报告中必须列出允许修改的文件清单，执行阶段只能触碰清单内的文件。
• 以下区域为禁改区，除非用户在当次任务中明确点名：
  • BattleSimulator 的随机数来源与事件输出格式（受 C2/C3 约束的接口）
  • res://data/ 下与本次任务无关的 JSON 文件
  • docs/ 下的历史决策记录（06_DECISIONS.md 只允许追加，不允许改写）
  • 用户标注"勿动"的任何代码段
• 修改禁改区边界的接口（如 events 结构）属于 C4 范畴，必须先走文档同步流程。

C11. 改动对账

执行完成后，必须输出对账表： 文件：【路径】 计划改动：【报告中对应的条目】 实际改动：【实际 diff 摘要】 超出计划的部分：【有/无；有则逐条说明原因】

• 存在超出计划的改动且无事先说明的，视为违规，必须回滚。
• 必须给出验证步骤：改完后用什么操作、预期看到什么结果。

C12. 认知地图优先

动手分析前，必须先读取本宪法 + docs/09_FEATURE_MAP.md（功能→代码定位第一入口）+ docs/02_ARCHITECTURE.md + docs/05_PROGRESS.md。

• 分析报告中的"定位依据"必须引用具体文件、具体函数、具体行号或具体原文，禁止使用"大概""某处""相关代码"等模糊表述。
• 引用不出原文的分析视为未完成分析，不得进入阶段二。

C13. 竖屏 UI 设计约束

所有 UI 改动必须遵守《大巴扎手机竖屏版 UI/UX 设计文档》（见项目根 设计文档.md，缺失时先创建）：

• 拇指热区：顶部 25% 只读禁止按钮；全部高频交互按钮位于底部 40%。
• 一屏一事：每个界面只承载一个决策或动作，禁止把多界面功能堆叠进同一屏。
• 棋盘规格：棋盘与储物箱均为 2×4；物品尺寸仅允许 1×1 / 1×2 / 2×1 / 2×2；"相邻"= 四方向网格相邻；"最左侧" = 第 1 列。
• 整理模式为全屏独立界面，非弹窗；棋盘在下（大格、操作区），储物箱在上（小格、核对区）。
• 战斗界面禁止修改摆位；战斗表现为纯动画播放，只允许加速/跳过操作。
• 新增 UI 元素前先自检：眯眼看上去是"游戏关键时刻"还是"工具面板"？是后者则删减。

C14. 功能↔代码映射必须同步

docs/09_FEATURE_MAP.md 是"功能 → 代码定位"清单（AI 切入点 / 第一入口）。任何新增或修改某功能的改动，必须同步更新该文件：

• 新增/删除/移动文件、类、函数、信号、数据 schema、场景、测试时，在对应小节同步标注（文件路径 + 类名 + 关键函数名）。
• 若改动涉及文档中的"备注 / 遗留 / 边界"标注（如战斗层仍为旧一维 vs 已迁移的 2×4），须一并更新那段边界说明，杜绝"文档说的目标状态 ≠ 代码真实状态"。
• 该文档与 02_ARCHITECTURE.md、03_RULES.md、05_PROGRESS.md、06_DECISIONS.md 属于同一套"必须同步"的文档组；不一致会直接误导后续修改。

附录 A：修改前强制分析报告模板

修改前分析报告

1. 任务理解 用户要求：（一句话复述） 验收标准：（怎么算改完了）
2. 定位 要修改的位置：文件路径 + 函数名 + 行号 定位依据：（引用具体原文/调用链，禁止模糊表述） 改的是根因还是症状？
3. 影响面 谁调用了它：（搜索结果） 它调用了谁： 是否触发 C1~C14 中的条款：逐条快速排查，写明"无"或具体条款（尤其 C14 同步文档组）
4. 修改计划 允许修改的文件清单： 每处改动的预估 diff： 不改清单：（考虑过但决定不动的地方 + 理由）
5. 验证步骤 改完后如何验证： ⚠️ 报告输出完毕，停止。等待"执行"指令。

附录 B：宪法修订

• 本宪法的任何修改本身也必须走 C8 两阶段流程。
• 新增条款时保持编号递增，不回收、不改写已有条款编号。 几点设计说明： C8 是核心引擎，它把我们之前讨论的“分析关卡”写成了宪法条款，并带一个“快速修”逃生舱口——没有豁免口，你自己就会因为小事破坏规则，最后整个宪法形同虚设。 C9/C10/C11 是三道护栏：最小 diff(防止顺手重构)、白名单禁改区(防止越界)、对账表(事后可验收、违规可判定)。三者都是可机器/人工核查的硬标准，不是“尽量”这种软话。 C12 把“假分析”堵死了——必须引用具体行号和原文，糊弄式报告(“大概在 parser 某处”)直接不通过。 C13 把你的设计文档升格为法律，防止 AI 在改 UI 时随手把棋盘改回 1×10、或者把按钮放到顶部热区外。 附录 A 的模板里藏了一个细节：第 3 条要求“逐条排查 C1~C14”,这会强制 AI 在每次修改前把宪法过一遍——宪法从“静态文档”变成了“每次任务的检查清单”。 使用建议：把这个文件放到项目根目录命名为 AGENTS.md(或 CLAUDE.md),这样 AI 编程工具每次会话都会自动加载；配合工具层的 Plan Mode(物理禁写)效果最佳，宪法管“它想怎么做”，权限管“它能不能做”。