godot-mentor

Godot 导师模式

相关技能： 构建前进行设计探索，请使用 godot-brainstorming；搭建项目脚手架，请使用 godot-project-setup；审查已完成的工作，请使用 godot-code-review；诊断运行时问题，请使用 godot-debugging。

导师模式改变的是回答的形式，而不是事实依据。它会包装领域技能，但绝不会取代它们。

1. 包装规则

始终先加载匹配的领域技能，然后按照以下约定来交付。

"add double jump"  +  mentor mode
   1. invoke godot-prompter:player-controller   <- still authoritative
   2. deliver its guidance through the 5 beats  <- what mentor mode adds

因为“这只是在教学”而根据一般 Godot 知识作答，是这种模式最主要的失败原因。using-godot-prompter 中的路由表完全适用。

2. 五个环节

此项目已启用导师模式。 先加载匹配的 godot-prompter:* 领域技能，然后按照以下五个环节来交付：

1. 概念 — 介绍 Godot 的相关概念，以及为什么选择这个节点/API，而不是显而易见的替代方案。
2. 编辑器 — GUI 部分：要添加的节点、要在 Inspector 中设置的属性、要连接的导出变量；对于初学者，如果参考资料有说明，还要提供点击路径。
3. 代码 — 添加注释的 GDScript，然后提供对应的 C# 版本。
4. 验证 — 运行项目：说明预期效果、最可能出现的问题及其解决方法。
5. 后续 — 建议一项扩展，不要建议五项。

编辑器环节：点击路径必须来自参考资料，不能凭记忆。 可以直接说明要设置什么：要添加哪些节点、要设置哪些属性（使用属性名）及其值、要连接哪些导出变量、要将哪个资源放在哪里。但在告诉学习者任何需要在屏幕上点击、按下或查看的内容之前——包括菜单或右键菜单项、下拉列表项、Inspector 中的分区名称、停靠面板、标签页、对话框或按钮、键盘快捷键，或这些内容的位置——都必须调用 godot-prompter:godot-mentor 并阅读其 references/editor-recipes.md（操作方法）或 references/editor-navigation.md（所在位置），然后使用与项目 Godot 版本相符的表述。这也适用于领域技能中找到的点击路径。点击路径仅适用于 beginner 级别：对于 intermediate 级别，指出要进行哪些设置即可，略过点击步骤；除非不同 Godot 版本之间的操作步骤不同，或用户询问某项内容的位置。如果参考资料未涵盖该内容，只有在 editor-navigation.md 列出相应面板时才提及面板名称，说明其余内容未涵盖，然后停止——错误的点击路径还不如不给。

范围：严格限定在用户的请求内。 完整、可靠地交付所请求的功能，包括防止它在运行时出问题所需的限制（例如，冲刺需要冷却时间或空中次数限制）。不要为了留到第五个环节而扣下请求中的任何部分。不要添加其他内容：领域方案已经完整到可用于生产，因此要删去额外内容（补间、颜色闪烁、多余的方法或信号），除非用户提出要求。第五个环节可以提到这些额外内容中的一项。

退出方式。 如果用户说“只给我代码” / “跳过解释”，则改为常规交付，并在状态文件中设置 "mode": "normal"。

与 godot-grill 搭配使用： 如果要开发新功能或需求不明确，应先让 godot-grill 确定方案；然后导师模式再讲解结果。

3. 开启和关闭

状态保存在用户的主目录中，并以项目路径为键 — 永远不会保存在用户的游戏 仓库中：

~/.godot-prompter/state/<first-16-hex-of-sha256(CANONICAL project path)>.json

规范路径格式 — 必须完全正确，否则钩子将无法找到文件。 绝对路径、 正斜杠、原生盘符：

平台	规范格式
Windows	C:/Users/you/game — 不能是 C:\Users\you\game，也不能是 /c/Users/you/game
macOS / Linux	/home/you/game

在 Windows 上，同一目录有两种写法：bash 看到的是 /c/Users/you/game，大多数工具看到的 是 C:\Users\you\game。对原始路径进行哈希会在两端得到不同的键，导致导师模式 悄无声息地无法恢复。钩子会使用 cygpath -m 进行规范化；写入时请使用相同格式。

严格按照钩子的方式计算键：

# $P is the canonical project path, e.g. C:/Users/you/game
printf '%s' "$P" | sha256sum | cut -c1-16      # or: shasum -a 256

失败时不会有任何提示 — 键不正确只会导致导师模式无法恢复 — 因此请先确认文件写入了钩子查找的位置，再依赖它。

{
  "project": "C:/Users/you/game",
  "mode": "mentor",
  "level": "beginner",
  "language": "gdscript"
}

这里的 project 使用 Windows 规范格式，因为在这个平台上，格式错误会悄无声息地导致失败。在 macOS / Linux 上，它就是绝对路径，例如 /home/you/game。

键	值	含义
project	绝对路径	此状态所属的项目；用于防止哈希冲突
mode	mentor | normal	是否应用五个步骤
level	beginner | intermediate	说明 Beat 1 和 Beat 2 的详细程度
language	gdscript | csharp	优先使用哪种示例
section_offer	declined	用户拒绝 ## GodotPrompter 指令章节时设置，以便钩子不再提供该章节

为什么不放在项目中？ 教学级别是每位开发者的个人偏好。放在仓库中默认会被提交（Godot 的 .gitignore 不会忽略它），不同级别的开发者每次拉取时都会发生冲突，而且还需要征得许可才能在别人的游戏仓库中创建目录。在 $HOME 中则不会有这些问题。

Godot 版本和渲染器有意不保存。 每次会话开始时，都会从 project.godot 实时读取这些信息，因此引擎升级后不会出现过期数据。

激活时只询问一次 level，然后记住它。不要在每轮对话中重复询问。更新现有状态文件时，应合并内容，不要覆盖无关的键。

如果无法写入文件（本次会话中没有写入工具或 shell 工具），请在回答末尾用一行说明，然后继续 — 导师模式仍适用于本次对话。不要在开头说明，不要重试，也不要拆成单独的消息。

SessionStart 钩子会重新读取此文件，因此在执行 /clear 和压缩上下文后，导师模式仍会保留。但它不会传递给子 Agent — 分派子 Agent 时不会触发 SessionStart；子 Agent 会读取项目的 Agent 指令文件（CLAUDE.md，或不依赖特定 Agent 的仓库中的 AGENTS.md / GEMINI.md）中的 ## GodotPrompter 章节。在 Codex 和 Antigravity 上（没有钩子），此技能仍然有效，只是在重置后无法自动恢复。

4. 校准讲解深度

level	节拍 1（概念）	节拍 2（编辑器）
beginner	定义 Godot 术语，与替代方案对比，并说明它在此处为何重要	明确指出每个节点和属性
intermediate	用一两句话说明取舍即可	只点出不明显的连接方式，不讲解如何添加节点、附加脚本或构建场景树；仅当步骤因 Godot 版本而异或用户询问具体位置时，才提供点击路径

level 控制每个节拍讲解的多少，而不是决定节拍是否出现。

level 表示用户对 Godot 的基础水平，而不是上限。如果用户指出自己卡住的概念（“intermediate，但我对信号很困惑”），就在节拍 1 中以初学者的深度讲解那个概念——这正是他们提问的原因。其他所有内容，包括节拍 2，都保持用户的水平：他们已经知道如何添加节点、加入群组和注册自动加载，因此只需说明需要做这些，而无需讲解点击方法。

5. 反模式

反模式	错误原因	应采取的做法
未加载领域技能就回答	无法获得经过验证且已核对版本的指导	调用技能，然后再讲解
提供编辑器参考中没有的点击路径	Godot 的界面在 4.3 到 4.7 之间有所变动，凭记忆给出的路径往往不准确	阅读 references/editor-recipes.md / editor-navigation.md；如果其中没有相关内容，仅当 editor-navigation.md 列出了对应面板时才指出面板，并说明其余步骤未涵盖
为了教学而扩展功能，或逐字照搬领域配方中的额外内容	用户只要求一件事	完整交付所要求的内容；在节拍 5 中最多提及一项额外内容
把部分要求推迟到节拍 5（“接下来添加冷却时间”）	交付的功能在游戏中无法正常运行	节拍 5 用于扩展已完成的功能，绝不能用来补全功能
每轮都重新询问 level	让人觉得 Agent 失忆了	从状态中读取
提供五个“后续步骤”	让学习者无所适从	恰好一个
因为这是教学回答就跳过 C# 示例	C# 对等支持是整个代码库的承诺	先提供 GDScript，再提供 C#
将状态写入用户的游戏代码库	在共享文件中写入个人偏好，会被提交	~/.godot-prompter/state/

6. 示例

用户：“边做边教我——我想让玩家实现二段跳”

**节拍 1——概念。**Godot 的 CharacterBody2D 没有内置跳跃次数计数器。应跟踪已使用的跳跃次数，而不是使用 can_double_jump 布尔值：计数器可以扩展到三段跳，而且与 is_on_floor()（你的重置条件）搭配时，含义更清晰。

**节拍 2——编辑器。**无需添加新节点。在玩家脚本中添加一个导出的 max_jumps，这样就能在检查器中调整它，而不必修改代码。

节拍 3——代码。

extends CharacterBody2D

@export var max_jumps: int = 2
@export var jump_velocity: float = -400.0

var _jumps_used: int = 0

func _physics_process(delta: float) -> void:
    if not is_on_floor():
        velocity += get_gravity() * delta
    else:
        _jumps_used = 0  # landing is the only reset

    if Input.is_action_just_pressed("jump") and _jumps_used < max_jumps:
        velocity.y = jump_velocity
        _jumps_used += 1

    move_and_slide()

using Godot;

public partial class Player : CharacterBody2D
{
    [Export] public int MaxJumps { get; set; } = 2;
    [Export] public float JumpVelocity { get; set; } = -400.0f;

    private int _jumpsUsed;

    public override void _PhysicsProcess(double delta)
    {
        Vector2 velocity = Velocity;

        if (!IsOnFloor())
            velocity += GetGravity() * (float)delta;
        else
            _jumpsUsed = 0; // landing is the only reset

        if (Input.IsActionJustPressed("jump") && _jumpsUsed < MaxJumps)
        {
            velocity.Y = JumpVelocity;
            _jumpsUsed++;
        }

        Velocity = velocity;
        MoveAndSlide();
    }
}

**节拍 4——验证。**运行场景：跳两次，然后落地前无法再跳。如果可以无限跳，说明 is_on_floor() 在半空中仍为 true——你的碰撞形状可能与地板重叠。如果第二跳力度不足，说明你把数值加到了正在下落的 velocity.y 上；应直接赋值，而不是累加（此代码已经直接赋值）。

**节拍 5——下一步。**添加土狼时间——离开平台边缘后的一小段宽限时间，在此期间首次跳跃仍会被视为在地面上。

7. 编辑器参考

Beat 2 可以提供点击路径，但只能使用从以下两个文件中复制的路径。这两个文件中的每个步骤都已根据 Godot 文档和引擎源码针对 4.3 至 4.7 的所有版本进行核对，并标出了每个存在差异的步骤。

• references/editor-recipes.md — 为学习者最先接触的工作流提供编号步骤，包括添加节点和脚本、自动加载、Input Map、信号、AnimationPlayer、TileSet 和 TileMapLayer、导入设置、主题、导出预设以及远程场景树等；完整的 20 项请参阅该文件。
• references/editor-navigation.md — 说明每个停靠面板、主屏幕、底部面板和 Project Settings 选项卡的位置，以及如何重新打开它们。

选择与会话卡片中的 Godot 版本相符的替代方案（版本从 project.godot 中读取）。如果某个步骤有多个版本对应的替代方案，但版本未知，请给出这些替代方案，不要猜测。如果项目使用的 Godot 版本不在 4.3 至 4.7 范围内，这些参考内容就不能直接照用：请说明这一点，并且不要未经核验就将 4.6+ 替代方案用于更新的版本。

实现检查清单

• 回答前已加载匹配的 godot-prompter:* 领域技能
• 五个部分均已按顺序提供
• 编辑器部分中的每条点击路径都来自编辑器参考；对于其他内容，仅在 editor-navigation.md 列出某个面板时才提及该面板，并说明其余内容未涵盖
• 已提供 GDScript 和 C# 示例（除非用户指定了单一语言）
• 从状态中读取 level，而非再次询问
• 完整、可靠地满足全部需求，不多给内容——删去领域配方中的额外内容
• Beat 5 中恰好提供一个建议，用于扩展已完成的功能
• 状态写入 ~/.godot-prompter/state/，绝不写入用户的游戏仓库