dst-test-plan

name	dst-test-plan
description	通过对比当前分支与合适基准引用（PR 分支优先使用 PR base，否则使用用户指定基准或 `master`）、检查差异，并把变更行为整理成最小可行的游戏内检查清单，为这个 Don't Starve Together 模组生成手动测试计划，同时同步写入仓库根目录 `test.md`。当用户要求测试计划、QA 清单、验证步骤、回归清单，或询问如何在没有自动化测试的情况下手动测试 DST 模组改动时使用。

DST 测试计划

使用这个 skill 根据 git 变更生成手动测试计划。

工作流程

1. 选择对比基准：
   • 如果用户指定了基准引用，使用用户指定的基准。
   • 否则先检查当前分支是否是一个 PR 分支：运行 gh pr view --json baseRefName,headRefName,url。如果能取到 PR，使用该 PR 的 baseRefName 作为基准。
   • 如果当前分支不是 PR 分支，回退到 master。
   • 如果基准来自远端分支，先运行 git fetch origin <base>，并优先使用 origin/<base> 对比。
   • 对选定的 <base> 运行：
     • git --no-pager diff --stat <base>...HEAD
     • git --no-pager diff --name-status <base>...HEAD
     • git --no-pager log --oneline <base>..HEAD
2. 只读取理解行为所需的已变更文件。
3. 将 diff 归纳为少量测试主题，而不是逐文件叙述。
4. 为每个变更行为编写能证明它的最短手动测试。
5. 优先使用直接生成/设置命令，而不是漫长的生存流程。
6. 如果变更涉及白天/黄昏/夜晚、天数推进、月相、季节、周期计时器或随时间变化的组件，先使用 dst_reader skill 查原版时间相关代码，再写测试命令。
7. 生成最终测试计划后，先把完整 Markdown 同步写入仓库根目录 test.md，再在最终回复中返回同一份计划。

设置规则

• 控制台命令必须是玩家能直接粘贴到 DST 控制台执行的公开调试指令或事件调用，例如 c_give(...)、c_spawn(...)、c_select(...)、c_countprefabs(...)、TheWorld:PushEvent(...)。
• 不要输出需要在控制台里注入局部变量或临时 Lua 脚本的命令，例如 local i = SpawnPrefab(...)、local x,y,z = ...、for ... do ... end、直接调用 SpawnPrefab(...) 后再改组件字段等。
• 不要用“等待成熟”“继续用游戏内方式催熟”“手动推进到目标状态”这类含糊步骤替代可执行设置；如果目标状态需要成长、腐烂、冷却、计时器、生产周期或其他时间推进，必须给出可直接执行的公开命令或明确的游戏内操作路径。
• 如果某个状态无法只靠公开控制台命令设置，优先改用游戏内可操作路径：给予开发道具、生成目标 prefab、让玩家点击/施法/放入容器/烹饪/收获。
• 如果仍然没有公开入口能设置该状态，不要直接输出最终测试计划。先输出“建议添加的测试辅助调整”清单，说明每项调整的目标、建议入口、影响范围、测试后是否应保留，并询问开发者是否要调整；只有开发者明确同意后，才可以自动编写对应测试代码。开发者拒绝时，再输出使用现有慢路径的测试计划并明确成本。
• 当变更行为发生在物品或消耗品上时，优先使用 c_give("<prefab>")。
• 当变更行为发生在世界物体、生物、植物、建筑或特效上时，优先使用 c_spawn("<prefab>")。
• 如果功能基于配方，提供以下两类命令：
  • 需要时提供制作站的生成命令
  • 提供制作所需材料的给予命令
• 如果不需要通过制作来证明变更，就跳过制作，直接给予/生成最终 prefab。
• 如果行为依赖某种状态，包含所需的最少额外设置命令。
• 如果行为依赖物品内部组件状态，但没有公开控制台入口能直接设置，优先寻找本 mod 已暴露的开发物品或调试行为；找不到时按“建议添加的测试辅助调整”流程先询问开发者。

测试辅助调整流程

当生成测试计划时发现缺少快速、可重复、可直接执行的测试入口，先暂停输出完整测试计划，并按以下格式向开发者确认：

需要先补充测试辅助调整：
- 调整 1：<目标>
  建议入口：<例如 dev_mode 下 reskin_tool 新能力 / 新 debug prefab / 新开发专用 action>
  覆盖测试：<它能让哪些测试变短或可验证>
  影响范围：<仅 dev_mode / 是否影响正式玩法>
  建议：<保留 / 测完移除>

是否要我按以上方案修改代码？

开发者同意后，直接实施调整并再生成测试计划。开发者没有同意前，不要编写测试辅助代码，也不要把不可快速设置的状态写成普通步骤。

时间相关测试

当测试目标和时间有关时，先判断它依赖的是哪一类时间源，再给出最短切换命令。

• 如果依赖白天/黄昏/夜晚，优先使用原版 clock 事件切换阶段：
  • TheWorld:PushEvent("ms_setphase", "day")
  • TheWorld:PushEvent("ms_setphase", "dusk")
  • TheWorld:PushEvent("ms_setphase", "night")
  • TheWorld:PushEvent("ms_nextphase")
• 如果依赖新的一天或跨天刷新，使用：
  • TheWorld:PushEvent("ms_nextcycle")
• 如果需要固定昼夜长度，使用：
  • TheWorld:PushEvent("ms_setclocksegs", {day = 16, dusk = 0, night = 0})
  • TheWorld:PushEvent("ms_setclocksegs", {day = 0, dusk = 0, night = 16})
• 如果依赖月相，使用：
  • TheWorld:PushEvent("ms_setmoonphase", {moonphase = "full", iswaxing = true})
  • TheWorld:PushEvent("ms_setmoonphase", {moonphase = "new", iswaxing = true})
• 如果依赖季节，使用：
  • TheWorld:PushEvent("ms_setseason", "autumn")
  • TheWorld:PushEvent("ms_setseason", "winter")
  • TheWorld:PushEvent("ms_setseason", "spring")
  • TheWorld:PushEvent("ms_setseason", "summer")
  • TheWorld:PushEvent("ms_advanceseason")
• 如果依赖组件自己的定时器、冷却、腐烂、燃烧、生产或周期任务，先用 dst_reader 检查对应原版组件的时间字段和更新函数，再决定是切换世界时间、调用 LongUpdate，还是等待最短秒数。
• 在输出测试计划时，写明要观察的时间点。例如“切到夜晚后立刻检查一次，再推进一天后检查一次”。
• 如果控制台命令来自原版事件，说明已根据 dst_reader 检查过 components/clock.lua 或 components/seasons.lua。

需要读取的内容

• modmain.lua：确认功能已经接入。
• scripts/hooks/：检查行为补丁和注入逻辑。
• scripts/prefabs/：检查物品、建筑、食物和生物行为。
• scripts/recpiesHooker.lua：查找配方材料、制作过滤器和制作建筑。
• scripts/prefabsHooker.lua：查找添加到原版 prefab 上的行为。
• 时间相关变更：使用 dst_reader 读取原版 components/clock.lua、components/seasons.lua，以及实际被 hook 或调用的原版组件。
• 使用 rg 查找 prefab 名称、配方，以及适合控制台设置的切入点。

有用的搜索命令：

rg -n "Prefab\\(\" scripts
rg -n "rec\\(|AddRecipe|AddRecipe2|Ingredient\\(" scripts
rg -n "c_give|c_spawn|ThePlayer|GetSkillInfo|DoDelta" scripts
rg -n "ms_setphase|ms_nextcycle|ms_setmoonphase|ms_setseason|LongUpdate|DoTaskInTime|DoPeriodicTask" scripts

测试计划风格

保持计划简洁、实用。

文档截图模式

当用户为语雀/wiki 文档请求“截图测试代码”“截图需要的测试计划”或“配套截图指令”时，把任务理解为生成最小截图准备指令，而不是完整回归测试，也不是修改 Lua 代码。

• 只覆盖当前要拍的条目或画面，不扩展到整轮功能。
• 输出“目标、控制台指令、手动步骤、截图占位”即可。
• 控制台指令越少越好，优先使用 c_give(...)、c_spawn(...)、原版世界事件，以及本 mod 已存在的 dev 辅助命令。
• 保持本 skill 的控制台安全规则：不输出 local 变量、循环、临时函数或直接改组件字段的片段。
• 如果画面状态必须通过游戏内动作完成，例如播种、放入容器、烹饪、挖掘、采摘，就写成最短手动步骤。
• 如果没有现成命令或游戏内动作能快速摆出画面，先说明缺口并询问是否要新增 dev-only 辅助入口。

每个测试用例包含：

1. 目标
2. 设置
3. 步骤
4. 预期结果

优先输出类似格式：

## 1. 种子品质增益
目标：确认品质会改变可食用物品的恢复数值。

设置：
- `c_give("carrot_seeds", 5)`
- `c_give("reskin_tool")`

步骤：
1. 使用调试物品提高种子品质。
2. 吃掉一颗种子。

预期：
- 饥饿/生命/理智变化符合新的品质倍率。

规划启发

• 优先使用一个端到端证明新行为的测试，而不是多个细碎重复的测试。
• 只有当 diff 暗示可能出现破坏时，才添加第二个回归测试。
• 如果功能同时影响生食和熟食，只有当 diff 触及两条路径时才同时测试两者。
• 如果 hook 改变了合并/拆分/保存/加载行为，只有在证明该行为确实需要时，才加入堆叠、丢弃、重进游戏或重新烹饪步骤。
• 当命令名或 prefab 名称是根据代码推断出来的，要明确说明假设。

输出期望

使用这个 skill 回答时：

• 在最终回复前，将测试计划完整写入仓库根目录 test.md，覆盖旧内容；test.md 是本地测试产物，应保持在 .gitignore 中。
• 先用一段话概述从 diff 得出的测试范围。
• 然后列出手动测试用例。
• 只包含可直接粘贴到游戏控制台运行的公开命令；不要包含 local 变量、循环、临时函数或直接改组件字段的 Lua 片段。
• 对无法用公开控制台命令快速设置的前置状态，明确写出需要的游戏内操作或需要补充的临时调试入口。
• 优先选择开发者能在本地调试世界中最快执行的路径。