@sdd330dev/jy-skill 0.3.1 → 0.7.0

package/references/agent-handbook.md

@@ -32,8 +32,16 @@ moveTo 若返回 encounter → 必须 startBattle 并打完或玩家死亡
 战斗后 isDead(state) ? → 死亡结算 + restartGame()
   ↓
 getStatus(state) 生成状态栏，附在回复末尾
+  ↓
+buildChoicePrompt(state) → Host 渲染点选 UI（MCP Elicitation / AskQuestion / 飞书卡片）
+  ↓
+玩家点选 → resolveOption(state, optionId)
 ```
 
+**标准契约**：优先 `buildChoicePrompt` + Host UI；详见 [host-adapters.md](host-adapters.md)。
+
+**数字 fallback**：无 UI 能力时，Agent 可展示编号列表；玩家输入 `1`–`9` → `resolveOption(state, getOptions(state)[n-1].id)`。
+
 **复合指令**：按逻辑顺序逐步调用。例：「去平安镇买铁剑并装备」→ `moveTo` → 若 `encounter` 先战斗 → `buyItem` → `equipItem`。
 
 **续玩 vs 新游戏**：
@@ -104,11 +112,29 @@ getStatus(state) 生成状态栏，附在回复末尾
 ### 3.7 商店与对话
 
 - **`buyItem`**：物品须在**当前地点** `shops` 列表中，且银两 ≥ 价格。
-- **`talkTo`**：NPC 名须与当前地点 `npcs` **完全一致**。
+- **`talkTo`**：NPC 名须与当前地点 `npcs` **完全一致**；返回 `npc` 角色卡、`choices?`、`context?`、`events?`。
 - **`talkTo(state, 'random')`**：随机与在场 NPC 对话。
-- 有配置对话的 NPC 返回「说话者：「台词」」格式。
+- **`chooseDialog(state, dialogId, choiceIndex)`**：推进对话分支，执行 choice actions（setFlag/addItem/battle/heal）。
+- 有配置对话的 NPC 返回「说话者：「台词」」格式；Agent 基于 `npc.persona` 扩写，数值以引擎为准。
+
+### 3.8 事件与任务（flags）
+
+- `game-config.json` 中 `events` 已由 `event-engine.ts` 接入。
+- **`auto` 事件**：`moveTo` 抵达、`createNewGame` 首次落点触发（如小村 `village_start`）。
+- **`interact` 事件**：通过 `getOptions` 生成探索选项，`resolveOption` 触发（如山洞 `cave_treasure`）。
+- **`talk` 事件**：`talkTo` 时按 NPC 名与条件触发（如 `cave_master_quest`）。
+- `state.flags` 持久化；条件 `flag` / `level` / `item` 由引擎判定。
+
+### 3.9 行动选项与 PlayerChoicePrompt
+
+- **`buildChoicePrompt(state)`**：生成 Host 无关的 `PlayerChoicePrompt`（`choices[].value` = `ActionOption.id`）。
+- **`toMcpElicitationParams(prompt)`** / **`fromElicitationResponse(content)`**：MCP Elicitation 映射。
+- **`toFeishuInteractiveCard(prompt)`**：飞书交互卡片 JSON。
+- **`getOptions(state)`**：内部行动列表；与 `buildChoicePrompt().choices[].value` 一一对应。
+- **`resolveOption(state, optionId)`**：按 id 前缀分发到 talk/move/buy/interact/rest/status/explore/paginate/dialog。
+- 每轮回复末尾 MUST 输出 `buildChoicePrompt`；Host 有 UI 时禁止让玩家打字选行动。
 
-### 3.8 武功
+### 3.10 武功
 
 - 新角色默认：**基本拳法**（不耗内力）。
 - **`learnSkill`**：武功须存在于 `assets/skills.json`；已学会则失败。
@@ -167,12 +193,14 @@ while (尚有敌人 hp > 0 && !isDead(state)) {
 
 | 函数 | 返回 | 说明 |
 |------|------|------|
-| `loadOrCreateGame(createNewGame, name?)` | `{ state, isNewGame }` | 有档续玩，无档新建落盘 |
-| `loadGameState()` | `GameState \| null` | 仅读取，不创建 |
+| `loadOrCreateGame(createNewGame, name?)` | `{ state, isNewGame }` | 单用户默认档 |
+| `loadOrCreateGameForUser(userId, createNewGame, name?)` | `{ state, isNewGame }` | 多用户 `save/users/{userId}.json` |
+| `setSaveUserId(userId \| null)` | void | 切换当前会话存档目标 |
+| `loadGameState(userId?)` | `GameState \| null` | 仅读取，不创建 |
 | `saveGameState(state)` | void | 幂等手动存档 |
 | `deleteSave()` | void | 仅删档；重开请用 `restartGame` |
 | `restartGame(name?)` | `GameState` | 删档 + 新建 + 落盘 |
-| `createNewGame(name)` | `GameState` | 仅内存，不自动存档 |
+| `createNewGame(name)` | `GameState` | 新建并触发 auto 事件、落盘 |
 
 ### 查询
 
@@ -181,14 +209,24 @@ while (尚有敌人 hp > 0 && !isDead(state)) {
 | `getStatus(state)` | 状态栏文本（含经验、中毒/受伤行） |
 | `getInventory(state)` | 银两 + 物品列表 |
 | `getSkills(state)` | 已学武功 |
-| `getLocationInfo(state)` | 当前地点：可前往、NPC、商店、险地提示 |
+| `getLocationInfo(state)` | 当前地点文本（含描述、险地提示） |
+| `getLocationDetail(state)` | 结构化地点：description、atmosphere、dangerLevel、npcs |
+| `getOptions(state)` | 当前可选行动列表（与 buildChoicePrompt 一致） |
+| `buildChoicePrompt(state, ctx?)` | `PlayerChoicePrompt` 标准契约 |
+| `buildChoicePromptFromTalk(talkResult, state)` | 对话分支选项契约 |
+| `toMcpElicitationParams(prompt)` | MCP elicitation/create 参数 |
+| `fromElicitationResponse(content)` | Elicitation 回传 → optionId |
+| `toFeishuInteractiveCard(prompt)` | 飞书交互卡片 JSON |
+| `getNpcContext(state, npc)` | LLM-NPC 约束包：card、constraints、availableActions |
 
 ### 探索与交互
 
 | 函数 | 返回 | 失败常见原因 |
 |------|------|--------------|
-| `moveTo(state, dest)` | `{ success, message, encounter? }` | 不相连、无处可去 |
-| `talkTo(state, npc)` | `{ success, message }` | NPC 不在场 |
+| `moveTo(state, dest)` | `{ success, message, encounter?, events?, locationDetail? }` | 不相连、无处可去 |
+| `talkTo(state, npc)` | `TalkResult`（含 `npc?`, `choices?`, `context?`, `events?`） | NPC 不在场 |
+| `chooseDialog(state, dialogId, index)` | `TalkResult` | 无效选项 |
+| `resolveOption(state, optionId)` | `{ action, result }` | 未知 optionId |
 | `rest(state)` | `{ success, message }` | 一般总成功 |
 | `buyItem(state, item)` | `{ success, message }` | 非本店、无货、银两不足 |
 | `useItem(state, item)` | `{ success, message }` | 无物品、非消耗品、无收益 |

package/references/host-adapters.md

@@ -0,0 +1,182 @@
+# Host 选项适配指南
+
+jy 引擎输出统一的 **PlayerChoicePrompt** 标准契约，各 Host 按自身能力渲染 UI，回传 `choices[].value` 后调用 `resolveOption(state, optionId)`。
+
+## 标准契约
+
+```typescript
+interface PlayerChoicePrompt {
+  type: 'player_choice';
+  message: string;
+  choices: Array<{
+    value: string;      // 回传用，如 talk_村长、move_平安镇
+    label: string;
+    description?: string;
+    category?: string;
+  }>;
+  dialogChoices?: DialogChoice[];
+  dialogId?: string;
+  page?: number;
+  hasMore?: boolean;
+}
+```
+
+引擎 API：
+
+| 函数 | 用途 |
+|------|------|
+| `buildChoicePrompt(state, ctx?)` | 从当前状态生成契约 |
+| `buildChoicePromptFromTalk(state, talkResult)` | 对话含分支时生成契约 |
+| `toMcpElicitationParams(prompt)` | 转为 MCP Elicitation schema |
+| `fromElicitationResponse(content)` | 解析用户选择 → optionId |
+| `toFeishuInteractiveCard(prompt)` | 转为飞书交互卡片 JSON |
+| `resolveOption(state, optionId)` | 执行选中行动 |
+
+---
+
+## Host 适配矩阵
+
+| Host | 渲染机制 | 集成方式 |
+|------|----------|----------|
+| **MCP 客户端** | [MCP Elicitation](https://modelcontextprotocol.io/specification/2025-11-25/client/elicitation) `oneOf` 单选 | 运行 `scripts/mcp-server.ts`；工具返回 `mcpElicitation` |
+| **Cursor Agent** | `AskQuestion`（语义同 Elicitation） | Skill 规则：每轮 `buildChoicePrompt` → AskQuestion 映射 value/label |
+| **OpenClaw + 飞书** | 交互卡片按钮 | `build-feishu-card.ts` 或 `toFeishuInteractiveCard`；按钮 value 含 `optionId` |
+| **纯文本 Agent** | 数字/文字 fallback | 仅当 Host 无 UI 能力时使用 1/2/3 |
+
+**原则**：有 UI 能力则 **禁止** 让玩家打字选行动；无 UI 时才 fallback。
+
+---
+
+## MCP 客户端
+
+### 启动 Server
+
+```bash
+npx tsx scripts/mcp-server.ts
+```
+
+Claude Desktop / Cursor MCP 配置示例：
+
+```json
+{
+  "mcpServers": {
+    "jy-skill": {
+      "command": "npx",
+      "args": ["tsx", "/path/to/jy/scripts/mcp-server.ts"],
+      "cwd": "/path/to/jy"
+    }
+  }
+}
+```
+
+### 工具
+
+| 工具 | 说明 |
+|------|------|
+| `jy_load_game` | `playerId` 加载/新建（多用户存档） |
+| `jy_resolve_action` | 执行 `optionId` |
+| `jy_get_status` | 状态 + 最新 `playerChoice` |
+| `jy_from_elicitation` | 解析 Elicitation 响应并执行 |
+
+工具返回 JSON 含 `playerChoice` 与 `mcpElicitation`。Host 支持 Elicitation 时，用 `mcpElicitation` 渲染单选 UI；用户提交后调 `jy_from_elicitation` 或 `jy_resolve_action`。
+
+### Elicitation 示例
+
+```json
+{
+  "mode": "form",
+  "message": "江湖路远，接下来做什么？",
+  "requestedSchema": {
+    "type": "object",
+    "properties": {
+      "action": {
+        "type": "string",
+        "title": "选择行动",
+        "oneOf": [
+          { "const": "talk_村长", "title": "和村长交谈" },
+          { "const": "move_平安镇", "title": "前往平安镇" }
+        ]
+      }
+    },
+    "required": ["action"]
+  }
+}
+```
+
+用户选择后回传 `{ "action": "talk_村长" }` → `resolveOption(state, "talk_村长")`。
+
+---
+
+## Cursor Agent
+
+Cursor 的 `AskQuestion` 与 MCP Elicitation 语义相同。Agent 工作流：
+
+1. `buildChoicePrompt(state)` 获取选项
+2. 调用 AskQuestion：`options[].id` = `choices[].value`，`label` = `choices[].label`
+3. 用户点选 → `resolveOption(state, selectedValue)`
+4. 武侠叙述 + 状态栏 + 新一轮 AskQuestion
+
+`talkTo` 返回 `choices` 时，用 `buildChoicePromptFromTalk` 或 AskQuestion 展示对话分支；选中后 `chooseDialog` 或 `resolveOption`（`dialog:dialogId:index` 格式）。
+
+**Fallback**：AskQuestion 不可用时，可输出编号列表（1/2/3），但应优先尝试 AskQuestion。
+
+---
+
+## OpenClaw + 飞书
+
+### 前置
+
+- 安装 [OpenClaw 飞书插件](https://docs.openclaw.ai/channels/feishu)（WebSocket 模式，免公网 Webhook）
+- jy Skill 绑定到 Agent
+- 多用户使用 `loadOrCreateGameForUser(open_id)` / MCP `playerId`
+
+### 发卡片
+
+```bash
+# 演示：从小村状态生成卡片
+npx tsx scripts/build-feishu-card.ts --demo
+
+# 从 PlayerChoicePrompt JSON 生成
+echo '{"type":"player_choice",...}' | npx tsx scripts/build-feishu-card.ts
+```
+
+输出 `msg_type: interactive` 与 `content` JSON，通过飞书 IM API 或 OpenClaw 发送。
+
+### 按钮回调
+
+按钮 `value` 为 `{ "optionId": "talk_村长" }`。收到 `card.action.trigger` 后：
+
+1. 解析 `optionId`
+2. `resolveOption(state, optionId)`
+3. 叙述结果 + 发送新卡片（`buildChoicePrompt` → `toFeishuInteractiveCard`）
+
+也可安装社区 Skill `feishu-interactive-cards`，由 Agent 将 `PlayerChoicePrompt` 转为 confirmation/choice 卡片。
+
+---
+
+## 多用户存档
+
+| 场景 | API |
+|------|-----|
+| 单用户（Cursor 默认） | `loadOrCreateGame` → `save/game-state.json` |
+| 飞书/OpenClaw 多用户 | `loadOrCreateGameForUser(userId)` → `save/users/{userId}.json` |
+| MCP Server | 工具参数 `playerId` 自动隔离 |
+
+`setSaveUserId(userId)` 可切换当前会话存档目标。
+
+---
+
+## 分页
+
+选项超过 8 条时，`buildChoicePrompt` 自动分页，含「上一页」「查看更多…」导航项（`__page_N`）。  
+`resolveOption(state, "__page_1")` 返回 `{ action: 'paginate', result: PlayerChoicePrompt }`，Host 重新渲染即可，不修改游戏状态。
+
+---
+
+## 对话分支 value 格式
+
+| 类型 | value 格式 | 处理 |
+|------|------------|------|
+| 地图行动 | `talk_村长`、`move_平安镇`、`buy_铁剑` | `resolveOption` |
+| 对话分支 | `dialog:village_elder:0` | `resolveOption` → `chooseDialog` |
+| 分页 | `__page_0` | `resolveOption` → 新 prompt |

package/scripts/build-feishu-card.ts

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * 将 PlayerChoicePrompt 转为飞书交互卡片 JSON
+ *
+ * 用法:
+ *   echo '{"type":"player_choice","message":"...","choices":[...]}' | npx tsx scripts/build-feishu-card.ts
+ *   npx tsx scripts/build-feishu-card.ts --demo
+ */
+
+import { readFileSync } from 'node:fs';
+import { createNewGame, buildChoicePrompt } from './game-engine.js';
+import { toFeishuInteractiveCard, feishuCardToMessageContent } from './choice-prompt.js';
+import type { PlayerChoicePrompt } from './game-types.js';
+
+function readStdin(): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    process.stdin.on('data', (c: Buffer) => chunks.push(c));
+    process.stdin.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+    process.stdin.on('error', reject);
+  });
+}
+
+async function main(): Promise<void> {
+  let prompt: PlayerChoicePrompt;
+
+  if (process.argv.includes('--demo')) {
+    const state = createNewGame('主角');
+    prompt = buildChoicePrompt(state);
+  } else if (process.argv[2] && !process.argv[2].startsWith('-')) {
+    prompt = JSON.parse(readFileSync(process.argv[2], 'utf-8')) as PlayerChoicePrompt;
+  } else {
+    const input = await readStdin();
+    if (!input.trim()) {
+      console.error('Usage: build-feishu-card.ts [prompt.json] | --demo | stdin JSON');
+      process.exit(1);
+    }
+    prompt = JSON.parse(input) as PlayerChoicePrompt;
+  }
+
+  const card = toFeishuInteractiveCard(prompt);
+  const output = {
+    msg_type: 'interactive',
+    content: feishuCardToMessageContent(card),
+    card,
+  };
+  console.log(JSON.stringify(output, null, 2));
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/scripts/choice-prompt.ts

@@ -0,0 +1,179 @@
+/**
+ * 玩家选项标准契约 — Host 无关的选项导出与格式适配
+ */
+
+import type {
+  ActionOption,
+  DialogChoice,
+  PlayerChoiceItem,
+  PlayerChoicePrompt,
+  McpElicitationParams,
+  FeishuInteractiveCard,
+} from './game-types';
+
+export const CHOICES_PER_PAGE = 8;
+
+export interface BuildChoicePromptContext {
+  message?: string;
+  dialogChoices?: DialogChoice[];
+  dialogId?: string;
+  page?: number;
+  options?: ActionOption[];
+}
+
+export function optionsToChoiceItems(options: ActionOption[]): PlayerChoiceItem[] {
+  return options.map((o) => ({
+    value: o.id,
+    label: o.label,
+    description: o.hint,
+    category: o.category,
+  }));
+}
+
+export function paginateChoiceItems(
+  items: PlayerChoiceItem[],
+  page = 0,
+  perPage = CHOICES_PER_PAGE,
+): Pick<PlayerChoicePrompt, 'choices' | 'page' | 'hasMore' | 'totalPages'> {
+  const totalPages = Math.max(1, Math.ceil(items.length / perPage));
+  const safePage = Math.max(0, Math.min(page, totalPages - 1));
+  const start = safePage * perPage;
+  const slice = items.slice(start, start + perPage);
+  const hasMore = start + perPage < items.length;
+
+  const choices: PlayerChoiceItem[] = [...slice];
+  if (safePage > 0) {
+    choices.unshift({
+      value: `__page_${safePage - 1}`,
+      label: '上一页',
+      category: 'nav',
+    });
+  }
+  if (hasMore) {
+    choices.push({
+      value: `__page_${safePage + 1}`,
+      label: '查看更多…',
+      category: 'nav',
+    });
+  }
+
+  return { choices, page: safePage, hasMore, totalPages };
+}
+
+export function buildChoicePrompt(
+  options: ActionOption[],
+  ctx: BuildChoicePromptContext = {},
+): PlayerChoicePrompt {
+  if (ctx.dialogChoices?.length) {
+    return {
+      type: 'player_choice',
+      message: ctx.message ?? '请做出选择：',
+      choices: ctx.dialogChoices.map((c) => ({
+        value: dialogChoiceValue(ctx.dialogId ?? 'unknown', c.index),
+        label: c.text,
+        category: 'talk' as const,
+      })),
+      dialogChoices: ctx.dialogChoices,
+      dialogId: ctx.dialogId,
+    };
+  }
+
+  const allItems = optionsToChoiceItems(ctx.options ?? options);
+  const { choices, page, hasMore, totalPages } = paginateChoiceItems(allItems, ctx.page ?? 0);
+
+  return {
+    type: 'player_choice',
+    message: ctx.message ?? '江湖路远，接下来做什么？',
+    choices,
+    page,
+    hasMore,
+    totalPages,
+  };
+}
+
+export function dialogChoiceValue(dialogId: string, choiceIndex: number): string {
+  return `dialog:${dialogId}:${choiceIndex}`;
+}
+
+export function parseDialogChoiceValue(value: string): { dialogId: string; index: number } | null {
+  if (!value.startsWith('dialog:')) return null;
+  const parts = value.split(':');
+  if (parts.length !== 3) return null;
+  const index = Number.parseInt(parts[2]!, 10);
+  if (Number.isNaN(index)) return null;
+  return { dialogId: parts[1]!, index };
+}
+
+export function isPaginationValue(value: string): boolean {
+  return value.startsWith('__page_');
+}
+
+export function parsePaginationValue(value: string): number | null {
+  if (!isPaginationValue(value)) return null;
+  const page = Number.parseInt(value.slice('__page_'.length), 10);
+  return Number.isNaN(page) ? null : page;
+}
+
+export function toMcpElicitationParams(prompt: PlayerChoicePrompt): McpElicitationParams {
+  const selectable = prompt.choices.filter((c) => c.category !== 'nav');
+  return {
+    mode: 'form',
+    message: prompt.message,
+    requestedSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          title: '选择行动',
+          description: prompt.dialogId ? '对话分支' : undefined,
+          oneOf: selectable.map((c) => ({
+            const: c.value,
+            title: c.description ? `${c.label} ${c.description}` : c.label,
+          })),
+        },
+      },
+      required: ['action'],
+    },
+  };
+}
+
+export function fromElicitationResponse(content: Record<string, unknown>): string | null {
+  const action = content.action;
+  if (typeof action === 'string' && action.length > 0) return action;
+  return null;
+}
+
+export function toFeishuInteractiveCard(prompt: PlayerChoicePrompt): FeishuInteractiveCard {
+  const actionButtons = prompt.choices.map((choice) => ({
+    tag: 'button',
+    text: { tag: 'plain_text', content: choice.label },
+    type: choice.category === 'nav' ? 'default' : 'primary',
+    value: { optionId: choice.value },
+  }));
+
+  const rows: Array<Record<string, unknown>> = [];
+  for (let i = 0; i < actionButtons.length; i += 3) {
+    rows.push({
+      tag: 'action',
+      actions: actionButtons.slice(i, i + 3),
+    });
+  }
+
+  return {
+    config: { wide_screen_mode: true },
+    header: {
+      title: { tag: 'plain_text', content: prompt.message },
+    },
+    elements: rows,
+  };
+}
+
+export function feishuCardToMessageContent(card: FeishuInteractiveCard): string {
+  return JSON.stringify(card);
+}
+
+export function parseFeishuButtonValue(payload: unknown): string | null {
+  if (!payload || typeof payload !== 'object') return null;
+  const optionId = (payload as { optionId?: unknown }).optionId;
+  return typeof optionId === 'string' ? optionId : null;
+}