style(03-19): normalize touched replay JSDoc to multiline

- Convert replay command, helper, and registry JSDoc into multiline form
- Add declaration-aware script/check-touched-jsdoc.ts scanner that
  inventories constructors as explicit exemptions and fails any other
  touched top-level function or class method without multiline JSDoc

packages-user/data-state/src/replay/commands.ts

@@ -13,22 +13,37 @@ import {
     REPLAY_COMMAND_ORDER
 } from './types';
 
+/**
+ * 判断未知值是否为有限数值
+ */
 function isNumber(value: unknown): value is number {
     return typeof value === 'number' && Number.isFinite(value);
 }
 
+/**
+ * 判断未知值是否为可用的道具编号或道具 id
+ */
 function isItem(value: unknown): value is number | string {
     return isNumber(value) || typeof value === 'string';
 }
 
+/**
+ * 判断未知值是否为布尔值
+ */
 function isBoolean(value: unknown): value is boolean {
     return typeof value === 'boolean';
 }
 
+/**
+ * 判断未知值是否为可用的装备槽位编号或槽位 id
+ */
 function isSlot(value: unknown): value is number | string {
     return isNumber(value) || typeof value === 'string';
 }
 
+/**
+ * 将槽位编号或槽位 id 解析为装备槽位索引
+ */
 function resolveSlot(
     state: IReplayCommandState,
     slot: number | string
@@ -46,6 +61,9 @@ class ReplayDirectionCommand implements IReplayCommand {
         private readonly direction: FaceDirection
     ) {}
 
+    /**
+     * 按构造方向启动一次勇士移动并等待移动结束
+     */
     private async moveHero(): Promise<boolean> {
         try {
             const mover = this.state.hero.location.mover;
@@ -60,6 +78,9 @@ class ReplayDirectionCommand implements IReplayCommand {
         }
     }
 
+    /**
+     * 校验录像步参数并执行一次方向移动
+     */
     execute(step: IReplayStepHandler): Promise<boolean> {
         if (step.params.length !== 0) return Promise.resolve(false);
         return this.moveHero();
@@ -69,6 +90,9 @@ class ReplayDirectionCommand implements IReplayCommand {
 class ReplayAutoPathfindCommand implements IReplayCommand {
     constructor(private readonly state: IReplayCommandState) {}
 
+    /**
+     * 自动寻路到目标坐标并等待寻路结束
+     */
     private async moveToPoint(x: number, y: number): Promise<boolean> {
         try {
             const result = this.state.pathfinding.moveTo({ x, y });
@@ -80,6 +104,9 @@ class ReplayAutoPathfindCommand implements IReplayCommand {
         }
     }
 
+    /**
+     * 校验录像步参数并执行一次自动寻路
+     */
     execute(step: IReplayStepHandler): Promise<boolean> {
         if (step.params.length !== 2) return Promise.resolve(false);
         const x = step.params[0];
@@ -92,10 +119,16 @@ class ReplayAutoPathfindCommand implements IReplayCommand {
 class ReplayUseItemCommand implements IReplayCommand {
     constructor(private readonly state: IReplayCommandState) {}
 
+    /**
+     * 使用指定道具并返回现有状态接口的结果
+     */
     private useItem(item: number | string): boolean {
         return this.state.hero.items.useItem(item);
     }
 
+    /**
+     * 校验录像步参数并执行一次道具使用
+     */
     execute(step: IReplayStepHandler): Promise<boolean> {
         if (step.params.length !== 1) return Promise.resolve(false);
         const item = step.params[0];
@@ -107,6 +140,9 @@ class ReplayUseItemCommand implements IReplayCommand {
 class ReplayEquipCommand implements IReplayCommand {
     constructor(private readonly state: IReplayCommandState) {}
 
+    /**
+     * 将指定装备穿到目标槽位并返回是否穿装成功
+     */
     private equip(
         uid: number,
         slot: number | string,
@@ -123,6 +159,9 @@ class ReplayEquipCommand implements IReplayCommand {
         return equipment.getEquipped(slotIndex) === uid;
     }
 
+    /**
+     * 校验录像步参数并执行一次装备穿装
+     */
     execute(step: IReplayStepHandler): Promise<boolean> {
         if (step.params.length < 2 || step.params.length > 3) {
             return Promise.resolve(false);
@@ -145,6 +184,9 @@ class ReplayEquipCommand implements IReplayCommand {
 class ReplayUnequipCommand implements IReplayCommand {
     constructor(private readonly state: IReplayCommandState) {}
 
+    /**
+     * 卸下指定槽位的装备并返回是否卸下成功
+     */
     private unequip(slot: number): boolean {
         const equipment = this.state.hero.equip;
         if (equipment.getEquipped(slot) === undefined) return false;
@@ -152,6 +194,9 @@ class ReplayUnequipCommand implements IReplayCommand {
         return equipment.getEquipped(slot) === undefined;
     }
 
+    /**
+     * 校验录像步参数并执行一次装备卸下
+     */
     execute(step: IReplayStepHandler): Promise<boolean> {
         if (step.params.length !== 1) return Promise.resolve(false);
         const slot = step.params[0];
@@ -162,7 +207,9 @@ class ReplayUnequipCommand implements IReplayCommand {
     }
 }
 
-/** 创建按稳定 enum 顺序排列的默认 replay command items */
+/**
+ * 创建按稳定 enum 顺序排列的默认 replay command items
+ */
 export function createReplayCommandItems(
     state: IReplayCommandState
 ): ReadonlyArray<IReplayCommandItem> {
@@ -202,7 +249,9 @@ export function createReplayCommandItems(
     ];
 }
 
-/** 按 top-level stable code 注册 command，并在注册前拒绝重复项 */
+/**
+ * 按 top-level stable code 注册 command，并在注册前拒绝重复项
+ */
 export function registerReplayCommandItems(
     replay: IReplaySystem | IReplayCommandRegistry,
     items: ReadonlyArray<IReplayCommandItem>