feat: 增强 Boss 脚本 HookAction 接入能力

引入 BossHookActionContext 封装战斗上下文，并支持脚本调用 useSkill 和 switchPet 函数控制战斗行为。

docs/boss-script-hookaction-guide-2026-04-05.md

@@ -0,0 +1,173 @@
+# Boss Script（HookAction）接入说明
+
+日期：2026-04-05
+
+## 1. 执行流程
+
+1. 先执行战斗效果链 `HookAction()`
+2. 执行脚本 `hookAction(hookaction)`
+3. 用脚本返回值决定是否继续出手
+4. 脚本可直接调用 Go 绑定函数：`useSkill()`、`switchPet()`
+
+## 2. JS 可调用的 Go 函数
+
+1. `useSkill(skillId: number)`
+   - 作用：指定本回合使用技能
+   - 示例：`useSkill(5001)`
+
+2. `switchPet(catchTime: number)`
+   - 作用：指定本回合切换精灵
+   - 示例：`switchPet(2)`
+
+## 3. `hookaction` 参数字段
+
+1. `hookaction.hookaction: boolean`
+   - effect 链原始判定
+2. `hookaction.round: number`
+   - 当前回合数
+3. `hookaction.is_first: boolean`
+   - 是否先手
+4. `hookaction.our: { pet_id, catch_time, hp, max_hp } | null`
+   - 我方当前精灵
+5. `hookaction.opp: { pet_id, catch_time, hp, max_hp } | null`
+   - 对方当前精灵
+6. `hookaction.skills: Array<{ skill_id, pp, can_use }>`
+   - 我方当前技能快照
+
+返回值：
+
+- `true`：继续行动
+- `false`：阻止行动
+- 不返回：默认回退到 `hookaction.hookaction`
+
+## 4. 脚本示例
+
+### 4.1 第3回合固定放技能
+
+```js
+function hookAction(hookaction) {
+  if (!hookaction.hookaction) return false;
+
+  if (hookaction.round === 3) {
+    useSkill(5001);
+  }
+
+  return true;
+}
+```
+
+### 4.2 低血切宠
+
+```js
+function hookAction(hookaction) {
+  if (!hookaction.hookaction) return false;
+  if (!hookaction.our) return true;
+
+  var hpRate = hookaction.our.max_hp > 0 ? hookaction.our.hp / hookaction.our.max_hp : 1;
+  if (hpRate < 0.3) {
+    switchPet(2);
+  }
+
+  return true;
+}
+```
+
+### 4.3 读取技能可用性后出招
+
+```js
+function hookAction(hookaction) {
+  if (!hookaction.hookaction) return false;
+
+  for (var i = 0; i < hookaction.skills.length; i++) {
+    var s = hookaction.skills[i];
+    if (s.can_use && s.skill_id === 5001) {
+      useSkill(s.skill_id);
+      break;
+    }
+  }
+
+  return true;
+}
+```
+
+## 5. Monaco 类型提示
+
+```ts
+import * as monaco from "monaco-editor";
+
+monaco.languages.typescript.javascriptDefaults.setCompilerOptions({
+  allowNonTsExtensions: true,
+  checkJs: true,
+  target: monaco.languages.typescript.ScriptTarget.ES2020,
+});
+
+monaco.languages.typescript.javascriptDefaults.addExtraLib(
+  `
+interface BossHookPetContext {
+  pet_id: number;
+  catch_time: number;
+  hp: number;
+  max_hp: number;
+}
+
+interface BossHookSkillContext {
+  skill_id: number;
+  pp: number;
+  can_use: boolean;
+}
+
+interface BossHookActionContext {
+  hookaction: boolean;
+  round: number;
+  is_first: boolean;
+  our: BossHookPetContext | null;
+  opp: BossHookPetContext | null;
+  skills: BossHookSkillContext[];
+}
+
+declare function hookAction(hookaction: BossHookActionContext): boolean;
+declare function HookAction(hookaction: BossHookActionContext): boolean;
+declare function hookaction(hookaction: BossHookActionContext): boolean;
+
+declare function useSkill(skillId: number): void;
+declare function switchPet(catchTime: number): void;
+`,
+  "ts:boss-script.d.ts"
+);
+```
+
+## 6. Monaco 补全（可选）
+
+```ts
+monaco.languages.registerCompletionItemProvider("javascript", {
+  provideCompletionItems() {
+    return {
+      suggestions: [
+        {
+          label: "boss hookAction",
+          kind: monaco.languages.CompletionItemKind.Snippet,
+          insertTextRules:
+            monaco.languages.CompletionItemInsertTextRule.InsertAsSnippet,
+          insertText: [
+            "function hookAction(hookaction) {",
+            "  if (!hookaction.hookaction) return false;",
+            "  if (hookaction.round >= 3) useSkill(5001);",
+            "  return true;",
+            "}",
+          ].join("\\n"),
+          documentation: "Boss脚本模板：可读取回合/血量并调用 useSkill/switchPet。",
+        },
+      ],
+    };
+  },
+});
+```
+
+## 7. 后端代码
+
+- 脚本执行器与函数绑定：`modules/config/model/boss_pet.go`
+- AI 出手转发：`logic/service/fight/input/ai.go`
+- BOSS 脚本注入：
+  - `logic/controller/fight_boss野怪和地图怪.go`
+  - `logic/controller/fight_塔.go`
+