docs: 更新提示词

docs/dev/template.md

@@ -0,0 +1,72 @@
+> 本示例文档以物体移动为例，代码参考 `packages-user/data-common/src/common/mover.ts`。文档较为简略，实际编写的时候可以更丰富一些。
+
+# 需求综述
+
+为提供更便捷的物体移动接口，故进行本设计。本设计提供统一的移动接口 `IObjectMover`，并完成其抽象实现 `abstract class ObjectMover`，以方便具体拓展。
+
+# 接口设计分析
+
+默认场景下，移动主要发生在两种物体上：地图动态图块及玩家操控的勇士。二者的主要差别在于后者由玩家操控，需要进行移动判定，例如需要进行通行性判定，事件触发判定等，而前者通常由系统代码控制，且常用于演出，并不需要进行判定。
+
+## IObjectMover
+
+### 设计意图
+
+对于玩家操控，判定往往发生在移动前，因此为统一接口，设计出 `onStepStart` 与 `onStepEnd` 两个接口，前者进行判定，后者根据判定结果进行相应的操作。为了让后者知道判定结果，将 `onStepStart` 的返回值设计为 `Promise<number>`，`onStepEnd` 接收之并执行操作。
+
+在实际情况中，常见的使用场景是先规划好线路，然后让物体移动，因此接口需要设计成计划式，计划完成后通过 `start` 接口开始移动，故需要两个接口 `onMoveStart` 和 `onMoveEnd` 分别在移动开始前和结束后执行某些操作。
+
+为了能够在开始移动后对移动进行干预及监听，`start` 应返回 `IMoveController` 作为返回值，其中应包含临时在当前步后插入一步、在当前移动队列后插入一步、下一步结束后立刻停止移动、当移动结束后兑现的 `Promise` 等内容。
+
+接下来考虑移动计划，最通用的移动方法是指定移动方向与物体的面朝朝向，然后物体面朝指定朝向，向移动方向移动一格，故需要 `stepFace` 接口。在绝大多数情况下，移动方向与朝向是一致的，故提供 `step` 接口。除了这种情况，还会包含前进一格的需求，故提供 `forward` 接口；与之对应，还提供 `backward` 后退接口，而且在多数情况下，后退往往代表面朝前向后走，这里也使用这一语义。在后退时，移动动画的播放进度应该相反，故提供 `animDir` 接口。在移动时，移动速度是一个重要参数，故提供 `speed` 接口。在某些情况下，物体可能会需要瞬移，故提供 `tp` 接口。除了这些，还需要提供转向接口 `face`，调整面朝朝向；以及一个相对比较常见的 `jump` 接口。
+
+对于移动对象，仅需要 `x` `y` `setPos` `getCurrentFaceDirection` 接口即可完成所有上述行为，故将这几个接口包装为 `IObjectMovable`，同时 `interface IObjectMover<T extends IObjectMovable>` 允许自定义拓展。
+
+### 接口分析
+
+> 此处仅列出部分。
+
+- `IObjectMover.forward()`：预期频率**高频**。向前移动一格是地图行走、动画演出等场景的核心需求，在逻辑与演出中都会频繁出现，故为高频。典型使用场景：演出中玩家或 NPC 沿某方向连续移动。
+- `IObjectMover.speed()`：预期频率**中频**。移动中修改移速有一定使用场景，但远不及 `forward`、`step` 等移动接口的频率，通常只在特殊演出或逻辑中出现，故为中频。典型使用场景：NPC 逃离怪物时先定在原地，随后逐渐加速逃跑。
+- `IObjectMover.stepFace()`：预期频率**低频**。移动方向与朝向不同的常见场景（后退）已由 `backward` 覆盖，只有极特殊情况才需要此接口（如角色朝向固定但沿垂直方向平移），相当罕见，故为低频。
+
+### 预期体量
+
+本节应当写出预期的代码体量，并分析原因。示例如下：
+
+预期代码体量为 200-300 行。分析如下：
+
+- `IObjectMover` 首先需要完成计划存储与计划的定义，这些接口基本大致就是向数组中添加元素，每个方法内容都不多，整体预计在 100 行左右。
+- `IObjectMover` 还需要完成移动流程的编写工作，需要根据每个移动步按照流程执行不同的行为，这一过程较为复杂，预计需要 100-200 行。
+
+## IMoveController
+
+...
+
+# 实现思路
+
+## 移动流程控制
+
+核心难点在于如何进行移动控制，以下为核心思路。
+
+1. 为实现移动流程，首先需要写一个大循环来处理每一个移动步。
+2. 对于每一个移动步，首先调用 `onStepStart` 接口，获取移动 `code`，然后触发钩子，然后进行 `onStepEnd` 的执行，其返回值作为移动后的目标位置，最后触发钩子。
+
+# 涉及文件
+
+## 需要引用的文件
+
+- `lodash-es`: 引用 `lodash` 工具库，使用某些工具函数。
+- `@motajs/common`: 引用系统基本库，使用钩子相关接口。
+- `types.ts`: 引用当前子模块的类型标注文件，使用相应的接口声明。
+
+## 需要修改的文件
+
+### `@user/data-common/src/common/mover.ts`
+
+- [ ] 编写 `IObjectMover` 接口：按照本文描述完成设计
+- [ ] 编写 `IObjectMovable` 接口：按照本文描述完成设计
+- [ ] 编写 `IMoveController` 接口：按照本文描述完成设计
+- [ ] 完成每个移动步的接口设计：每个移动步都需要一个接口对象，本文未明确提及，需包含每种移动计划
+- [ ] 完成移动枚举的编写：每种移动计划都需要一个枚举类型来标注
+- [ ] 编写 `ObjectMover` 抽象类：实现 `IObjectMover` 接口，作为移动基类

packages-user/data-base/src/hero/mover.ts

@@ -100,7 +100,7 @@ export class HeroMover<T extends IHeroLocation>
     }
 
     /**
-     * 创建通行性检查信息对象
+     * 创建撞击行为信息对象
      * @param curr 勇士所在位置
      * @param dir 勇士移动方向
      * @param floorId 当前楼层 id

prompt.md

@@ -46,15 +46,17 @@
 1. 阅读当前代码，分析需求，将需求整理为一个 markdown 文档，放在 `docs/dev` 目录下，注意有可能在其子文件夹下，例如 `docs/dev/hero`，自行判断应该放到哪。文档中需明确标注需求细节，以及代码实现的大体思路。此阶段需考虑全面，遇到任何问题应向我提问并确认，不得自行假设。
 2. 我会对文档进行全面阅读，确认实现细节与思路无误后，方允许开始实现。我可能会对文档进行细微调整，请在实现前重新仔细阅读最终版本。实现过程中如有任何问题，应向我提问，而不是自行决定。
 
-## 示例文档
+## 文档结构
 
-对于新增接口/彻底性地重构接口，按照以下格式编写，其余需求自行组织。
+一般情况下按照以下格式编写，其余需求自行组织。
 
 - 如有需要可单独开设标题章节详述。
 - 我会使用 `>` 引用块在文档中批注，因此**不要在文档中使用引用块**。
 - 文档控制在 100-250 行，简洁但包含所有必要信息，不擅自修改示例文档格式。
 - 一般不需要流程图；若必须画，使用 `mermaid`。
 
+以下为文档结构，示例文档参考 `docs/dev/template.md`
+
 ```md
 # 需求综述
 
@@ -62,48 +64,31 @@
 
 # 接口设计分析
 
-这是相当重要的一章。按接口逐一分析成员与方法的预期使用频率（高/中/低，指**用户编写此调用的频率**而非运行时频率），中高频成员需列出至少一个典型使用场景。
-
-**命名长度原则**：高频 -> 一个单词；中频 -> 不超过三个单词；低频 -> 可稍长但不宜过长。
-
 我可能不会给完整接口设计，你需要自行分析需求补充设计，并在对话中明确指出哪些接口是你补充的。
 
-示例如下：
-
 ## IObjectMover
 
-### 接口综述
+### 设计意图
 
-这里讲解接口的设计，注意不要直接写成 ts 代码，也不要简单地一个个列出，而是需要分析需求，然后经过推理自然地得出接口设计。
+分析需求，然后在这里编写接口的设计意图。
 
 ### 接口分析
 
-- `IObjectMover.forward()`：预期频率**高频**。向前移动一格是地图行走、动画演出等场景的核心需求，在逻辑与演出中都会频繁出现，故为高频。典型使用场景：演出中玩家或 NPC 沿某方向连续移动。
-- `IObjectMover.speed()`：预期频率**中频**。移动中修改移速有一定使用场景，但远不及 `forward`、`step` 等移动接口的频率，通常只在特殊演出或逻辑中出现，故为中频。典型使用场景：NPC 逃离怪物时先定在原地，随后逐渐加速逃跑。
-- `IObjectMover.stepFace()`：预期频率**低频**。移动方向与朝向不同的常见场景（后退）已由 `backward` 覆盖，只有极特殊情况才需要此接口（如角色朝向固定但沿垂直方向平移），相当罕见，故为低频。
+按接口逐一分析成员与方法的预期使用频率（高/中/低，指**用户编写此调用的频率**而非运行时频率），中高频成员需列出至少一个典型使用场景。接口使用频率越高，其名称长度最好越短。
 
 ### 预期体量
 
-本节应当写出预期的代码体量，并分析原因。示例如下：
-
-预期代码体量为 200-300 行。分析如下：
-
-- `IObjectMover` 首先需要完成计划存储与计划的定义，这些接口基本大致就是向数组中添加元素，每个方法内容都不多，整体预计在 100 行左右。
-- `IObjectMover` 还需要完成移动流程的编写工作，需要根据每个移动步按照流程执行不同的行为，这一过程较为复杂，预计需要 100-200 行。
-
-### 可能风险
-
-若需修改已有接口（即本次新增之外的接口），在此写明修改风险（如类型污染、其他接口出错等）。只写修改已有接口的风险，不写实现风险（实现风险放到问题节）。无风险则跳过此章节。
+本节应当写出预期的代码体量，并分析原因。
 
 # 实现思路
 
-按照下面的格式分条描述实现思路。
+对于复杂逻辑，按照下面的格式分条描述实现思路。
 
-## 1. 完成 xxx
+## 复杂需求 1
 
 ...
 
-## 2. 完成 xxx
+## 复杂需求 2
 
 ...
 
@@ -111,11 +96,7 @@
 
 ## 需要引用的文件
 
-按照第三方库 → 其他包 → 当前包的其他文件的顺序写。
-
-- `xxx 库`: 引用第三方库，说明引用目的，以及需要的接口
-- `@user/xxx`: 引用的目的，需要这个文件的哪些接口
-- `xxx.ts`: 引用此文件的目的，需要这个文件的哪些接口
+按照第三方库 -> @motajs 包 → @user 包 → 当前包的其他文件的顺序写。不要写成接口列举，而是要写成需要什么类型的接口，示例如下。
 
 ## 需要修改的文件