《小柴寻主记》开发指令手册（新手关怀）
05/1328 浏览开发心得 包含 AI 合成内容
《小柴寻主记》开发指令手册
用途：每次开发前 AI 必读本文件。将开发者的口语化描述转化为规范指令，记录每个阶段的开发决策与操作日志。
AI 读取规则：收到任何开发请求时，先检索本文件对应阶段的"已有决策"，避免重复讨论已有定论的问题。
最后更新：2026-05-13
🤖 AI 会话启动检查单
每次新会话开始时，按顺序确认以下内容：
1. 读取本文件（开发指令手册.md）→ 了解已有决策和语言规范
2. 读取 进度总表.md → 了解当前任务优先级
3. 读取 README.md → 快速决策区确认当前阶段目标
4. 必要时读取对应 scripts/ 文件 → 确认代码现状
🔤 语言标准化对照表
开发者说的话 → AI 应理解为什么 → 标准指令格式
通用语言
开发者说 AI 理解为 标准指令关键词
“帮我加一个XXX” 新增功能开发 新增功能：[名称]，参考现有[类似功能]的实现方式
“这个不对/坏掉了” Bug修复 修复BUG：[现象]，相关文件 [文件名]
“改一下XXX的样子” UI调整 UI调整：[页面名]的[元素名]，目标效果[描述]
“让它动起来” 动画效果 添加动画：[元素]，使用 tween skill 实现[效果类型]
“感觉不对/不好看” 需要辩证分析 架构分析：当前[问题描述]，用辩证法 skill 分析主要矛盾
“生成一个图” 像素美术生成 生成像素图：[对象描述]，尺寸[N×N]，风格：像素卡牌，透明背景
“做个界面” UI设计+实现 创建UI页面：[页面名]，参考 CTM UI设计规范 skill
“存一下/备份” git保存 git保存：[版本描述]
“看看哪里有问题” 全量诊断 全量LSP诊断 + 运行时错误排查，输出问题清单
“先搞XXX” 任务优先级变更 调整优先级：[任务名] 升为 P0，其余不变
“算了不做了” 任务取消 取消任务：[任务名]，原因[描述]，更新进度总表
战斗系统专用语言
开发者说 AI 理解为
“打起来太卡/太慢” BattleSystem 性能或节奏问题
“CT不动了” CT值推进逻辑异常 → 检查 startCTAdvance()
“地图显示不全/溢出” BattleMap 渲染区域计算问题
“技能没反应” SkillSystem → BattlePage 事件链断开
“掉落没出来” LootSystem 或 BattleResultPage 结算逻辑
“加个新职业” PlayerConfig.lua + BattleConfig.lua 双文件联动
“敌人太强/太弱” BattleConfig.lua 敌人属性数值调整
探索系统专用语言
开发者说 AI 理解为
“加个新地点” MapConfig.lua + 背景图资源 + GuidebookConfig.lua 三处联动
“探索没奖励” MapConfig.lua 的 EXPLORE_MAP_DATA 掉落表
“天气没变化” WeatherSystem.lua 逻辑或 HomePage.lua 显示
“体力不够用” Config.lua 中的体力参数
🧰 可用 Skill 工具箱
遇到对应场景时，主动调用对应 skill，不要从零重写。
Skill 1：辩证法游戏开发指南
调用时机：遇到架构决策难题、技术选型犹豫、系统重构方向不明时
触发关键词：架构分析、技术选型、主要矛盾、推倒重来还是改
使用示例（开发者说）：
"战斗系统越来越复杂，感觉要重写了"
"用辩证法 skill 分析当前战斗系统的主要矛盾"
对应 skill：@tianyi_dialectical-game-dev-skill
核心方法：抓主要矛盾 → 避免过早重构，先识别核心阻碍点
本项目已用决策记录：
阶段三：战斗系统采用"渐进式修复"而非"推倒重来"→ 主要矛盾是 CT 推进逻辑，不是整体架构
阶段四：UIAnimations 双版本问题 → 暂缓合并，不是主要矛盾，阶段五再处理
Skill 2：像素美术生成器
调用时机：需要生成角色精灵、道具图标、场景元素、UI组件图片时
触发关键词：生成图片、像素图标、角色精灵、战斗背景
使用示例（开发者说）：
"给大福生成一个战斗用的小图"
"生成像素美术：金毛大福，战斗精灵，32×32，像素卡牌风格，透明背景"
对应 skill：@game_pixel-art-generator
本项目标准规格：
- 道具图标：64×64，透明背景，像素风格
- 角色战斗精灵：64×64 或 128×128，透明背景
- 导航栏图标：48×48，透明背景，像素扁平
- 战斗地图背景：1080×800，无透明背景，大连地点像素场景
本项目已生成资产清单：
角色精灵：小柴/大福/灰灰/团子/跳跳（各战斗状态：idle/attack/hurt/dead/defend/skill）
道具图标：约 15-16 个消耗品（蓝色药水/树叶/蘑菇/肉/鱼/骨头/蜂蜜罐/松果/葡萄/桃子等）
装备图标：红领圈/狗牌（金）/狗粮碗/蓝围巾
技能图标：咬击/治疗舔舔/防御盾/终极嚎叫
战斗地图背景：傅家庄日落/劳动公园樱花/天津街夜/太阳沟雪/星海广场（5张）
导航栏图标：背包/探索/主页/印记/伙伴/商店/休闲（各含激活态）
Skill 3：游戏UI设计规范
调用时机：新建 UI 页面、调整视觉风格、保持界面一致性时
触发关键词：UI页面、界面设计、视觉规范、颜色方案
使用示例（开发者说）：
"做个新的弹窗界面，要和现有风格统一"
"参考 CTM UI设计规范 skill，创建[页面名]，保持暖色系像素卡牌风格"
对应 skill：@CTM_game-ui-design
本项目UI规范（已确定，阶段四定稿）：
- 主色调：暖橙色系（#FF8C42 主色，#FFF3E0 背景，#3E2723 文字）
- 风格：像素卡牌 + 温馨手绘质感
- 字体：MiSans，正文14-16px，标题20-24px
- 屏幕：竖屏 1080×2400
- 圆角：12-16px（卡片），8px（按钮）
- 导航栏：底部 5Tab（主页/探索/背包/伙伴/印记）
本项目已确定页面风格：
StartPage：暖色渐变背景 + 小柴动画（花瓣+呼吸+尾巴摇摆）
HomePage：主城背景图（时段变化）+ 天气系统 + 底部导航
BattlePage：黑色底板（待升级为像素场景背景）+ 六边形格子
ExplorePage：大连地图俯视 + 地点卡片
Skill 4：让动画会呼吸（Tween缓动动画）
调用时机：为 UI 元素添加过渡动效、数值滚动、弹性反馈、呼吸感时
触发关键词：动画、过渡、弹跳、缓动、呼吸感、飞入/飞出
使用示例（开发者说）：
"伤害数字飞出来要有弹跳感"
"使用 tween skill，为伤害浮字添加：弹出（easeOutBack）→ 上升 → 渐隐"
对应 skill：@soyoyo_tween
本项目已用动画方案：
- 开始页花瓣：linear 漂落
- 小柴呼吸：easeInOutSine 循环
- 小柴尾巴：easeInOutQuad 摆动
- 页面切换：easeOutCubic 滑入（UIAnimations.lua）
- 按钮点击：easeOutBack 弹压
待实现动画（阶段五）：
- 战斗浮字：easeOutBack 弹出 → 线性上升 → easeInQuad 渐隐
- CT条更新：easeOutQuart 快速推进
- 胜利结算界面：easeOutBounce 奖励出现
- 伙伴招募：easeOutElastic 弹入
📅 阶段工作日志
按开发阶段记录关键决策、指令翻译和技术要点。AI 读取后能快速理解历史背景。
阶段一：基础搭建（v0.1，✅ 已完成）
核心决策
架构选择：Config（数据）/ System（逻辑）/ Page（UI） 三层分离
存档方案：SaveSystem + Section API，各系统管理自己的存档域
UI方案：全部使用 urhox-libs/UI（Yoga Flexbox），放弃原生 UIElement
关键指令记录
「创建游戏主框架，main.lua 负责页面路由，各页面独立文件，
使用 urhox-libs/UI 组件库构建所有 UI」
「实现存档系统：SaveSystem 负责文件读写，
各系统通过 GetSection/SetSection 接口管理自己的数据域」
遗留问题：UIAnimations 根目录版本（后续合并到 systems/ 版）
阶段二：探索系统（v0.2，✅ 已完成）
核心决策
42个大连真实地点全部定义在 MapConfig.lua
探索采用体力消耗 + 随机事件 + 区域进度设计
天气系统影响探索奖励和战斗
关键指令记录
「实现探索流程：
ExplorePage（选地点）→ ExploreIntroPage（出发确认）
→ ExploreProgressPage（探索中+倒计时）→ 结算弹窗」
「在 MapConfig.lua 添加大连[地区]的所有地点，
每个地点包含：名称/区域/等级/体力消耗/背景图路径/掉落表/剧情触发」
阶段三：战斗系统（v0.3，✅ 已完成）
核心决策
CT速度制战棋（参考梦幻模拟战2），不用回合制
六边形网格地图，5×5 起步，可扩展
战斗系统 = BattleSystem（逻辑）+ BattleMap（地图）+ BattlePage（UI）三文件
关键指令翻译记录
开发者说 翻译为指令 结果
“CT不动了” 检查 startCTAdvance() 是否被调用，根因是 InitBattleFromSquad 无 pcall 保护 ✅ 修复 BUG-CT
“打完没有结算界面” 实现 BattleResultPage，战斗结束后弹出胜利/失败专屏 ✅ 修复 MISS-result
“打完伤害数字不出来” HandleNanoVGRender 中添加浮字渲染逻辑 ✅ 修复 BUG-float
“技能按钮没有” buildActionBar() 添加技能A/B/道具三按钮入口 ✅ 修复 MISS-skill-btn
“进战斗前没提醒血量” doExplore() 添加 HP 检查弹窗（<80%提醒，<30%强警告） ✅ 修复 MISS-hp-check
辩证法应用记录
问题：战斗系统代码越来越长（BattleSystem 已 15KB），是否拆分？
分析（辩证法 skill）：主要矛盾不是文件大小，而是战斗体验的断路缺陷（P0）
决策：先修复 P0 缺陷，文件拆分延后到阶段六性能优化期
阶段四：UI美化（v0.4→v0.6.0，✅ 已完成，2026-05-13）
核心决策
视觉风格：暖橙色系像素卡牌（方案B）
动画系统：小柴呼吸+尾巴+花瓣，使用 tween 缓动
音频：19首BGM分类归档（战斗/探索/叙事/结算/主菜单）
美术资产：像素美术生成器 skill 批量生成
关键指令翻译记录
开发者说 翻译为指令 使用的 Skill 结果
“小柴要动起来/要有生气” 添加 tween 动画：小柴 easeInOutSine 呼吸循环 + easeInOutQuad 尾巴摆动 tween skill ✅
“界面太冷了，要暖一点” UI颜色方案B：主色 #FF8C42 暖橙，替换所有冷蓝色调，参考 CTM UI规范 UI规范 skill ✅
“生成小柴的战斗图” 生成像素美术：柴犬团子，战斗idle姿势，64×64，像素卡牌风，透明背景 像素美术 skill ✅
“背景音乐太少了” 生成BGM：[场景]氛围，风格[描述]，时长60-90秒，循环 音乐制作 skill ✅
“游戏进不去了（启动失败）” 修复 Bootstrap：重新构建 dist/，恢复 342 个缺失文件 — ✅
“序章要有感情，小柴和朋友的相遇” 实现剧情脚本：序章第二节[遇见灰灰] + 第四节[第一场战斗前置]，在 PlayerConfig.STORY_CHAPTERS — ✅
像素美术生成标准（本项目定稿）
角色精灵 prompt 模板：
「[动物种类] [名字]，[动作状态]，64×64像素，卡牌游戏像素风格，
正面/侧面视角，干净透明背景，温馨可爱，大连城市宠物主题」
道具图标 prompt 模板：
「[物品名称]，游戏道具图标，64×64像素，
像素艺术风格，透明背景，暖色调，圆润可爱」
战斗背景 prompt 模板：
「大连[地点名称]，像素艺术场景，1080×800，
横版战棋游戏背景，[时段：白天/黄昏/夜晚]，有景深感，无角色」
阶段五：内容填充（v0.6，⏳ 进行中，启动于 2026-05-13）
阶段目标
22职业完整数据填充
前3个正式关卡实装（剧情+战斗数据）
战斗视觉升级（精灵上屏、背景上屏）
消耗品图标补全（约4-5个）
本阶段决策（持续更新）
日期 决策内容
2026-05-13 战斗视觉P1：使用已有精灵资产替换文字占位，优先级提升至P1
2026-05-13 UIAnimations 合并延后到阶段六，不阻断阶段五
待翻译的开发者语言（本阶段常用）
「加个职业」→
「在 PlayerConfig.lua 的 JOBS 表添加[职业名]：
基础属性{hp, atk, def, spd, mp}，
成长系数{per_level_hp, per_level_atk...}，
职业技能[4个，含id/name/cost/effect]，
转职条件{level, job_id}，
参考已有猫族剑士的数据格式」
「加个关卡」→
「在 BattleConfig.lua 的 LEVELS 表添加第[N]关：
地图: {width=5, height=5, background="[背景图路径]"},
敌人列表: [{id, type, pos, level}],
胜利条件: "defeat_all" 或 "defeat_boss",
前置对话: [{speaker, text}],
后置对话: [{speaker, text}],
奖励: {exp, gold, items}」
「精灵上屏」→
「在 BattleMap.lua 的单位渲染函数中，
将 UI.Label（emoji占位）替换为 UI.Image，
图片路径从 PartnerConfig.battleSprite 读取，
尺寸 64×64，居中对齐格子」
阶段六：测试与平衡（v0.8，⏳ 待开始）
预计指令集（提前准备）
「数值平衡检查」→
「用辩证法 skill 分析当前战斗数值体系的主要矛盾：
输出：[前5关] 平均战斗时长 / 玩家胜率 / 使用频率最高的技能
目标：每关3-5分钟，胜率65-70%」
「新手引导检测」→
「从 StartPage 开始完整走一遍新手流程，
记录每个步骤的用时和困惑点，
输出：可能卡住的3个位置 + 建议引导文本」
「全量Bug扫描」→
「对所有 scripts/*.lua 进行 LSP 全量诊断，
输出：错误列表 + 警告列表 + 按优先级排序的修复建议」
阶段七：发布运营（v1.0，⏳ 待开始）
预计指令集
「生成发布素材」→
「生成游戏图标：小柴犬主角，512×512，像素卡牌风格，
圆角方形构图，暖橙色背景」
「生成宣传图」→
「生成宣传横幅：1920×1080，
《小柴寻主记》主视觉，小柴+大福+灰灰三主角，
大连城市夜景背景，像素卡牌风格，暖色调」
「写游戏简介（TapTap版本）」→
「为《小柴寻主记》写 TapTap 发布简介：
200字以内，突出大连地理特色 + 温馨宠物故事 + SRPG战棋玩法」
🔁 常用操作快速模板
构建验证（每次代码修改后）
构建并验证：帮我构建项目，确认0错误0警告后报告结果
Git 备份
git 备份：帮我提交当前所有更改，提交信息：「[阶段]-[简要描述] [日期]」
资源路径规范（防错）
图片路径规范：
✅ image/UI图标/导航栏/nav_home.png
✅ image/场景背景/大连地点/location_xinghai_square.png
✅ image/道具图标/item_mushroom.png
❌ assets/image/...（不加 assets/ 前缀）
音频路径规范：
✅ audio/bgm/battle/normal/bgm_battle_normal.ogg
✅ audio/sfx/battle/sfx_tile_select.ogg
❌ assets/audio/...（不加 assets/ 前缀）
📎 文档关联索引
本文档章节 关联文档/文件
阶段工作日志 docs/00-索引/进度总表.md（任务状态）
UI规范决策 docs/00-索引/README.md → 代码架构速查
差距分析决策 docs/00-索引/SRPG差距分析报告.md
地点相关指令 scripts/configs/MapConfig.lua
战斗相关指令 scripts/configs/BattleConfig.lua + scripts/systems/BattleSystem.lua
剧情相关指令 scripts/configs/PlayerConfig.lua → STORY_CHAPTERS
像素图资产 assets/image/（各子目录）
音频资产 assets/audio/bgm/ + assets/audio/sfx/