choice-cards · 选项卡片

一个 HanaAgent 插件：让助手把选项做成可点击的选项卡卡片发给用户，用于做决定、做选择题、调查等场景。用户点击后，选择会自动作为消息回到会话，助手可以据此继续。

支持三种模式：单选（single）、多选（multi）、题目即时反馈（quiz）。

功能特性

• 原生 webview 卡片渲染，选项可点击，点击即回传，无需用户手动输入编号
• 三种交互模式：
  • single：点一个选项即选定
  • multi：勾选多个后点「提交」
  • quiz：点一个选项即时判分，显示对错与解析（绿色标对、红色标错）
• 深色 / 浅色主题自适应
• 选择结果自动注入会话，助手立刻拿到用户的选择继续对话
• 每张卡片有独立记录（JSON 持久化在 plugin data 下），同一会话内可反复出卡
• 兜底路径：卡片不可用时，用户直接回复编号同样生效（文本回退）

安装

把本仓库（或其中的 tools/、routes/、manifest.json）放入 HanaAgent 的插件目录（如 ~/.hanako/plugins/choice-cards），重启后在插件中心启用即可。

要求：HanaAgent ≥ 0.440.0，插件信任级别 full-access。

使用

助手侧直接调用插件工具 offer_choice：

{
  "question": "今晚想怎么安排学习？",
  "options": [
    { "label": "A. 康复评定学刷题", "description": "步态分析 + 平衡协调" },
    { "label": "B. 运动解剖复盘", "description": "四肢肌肉起止点" },
    { "label": "C. 英语单词 + 长难句" }
  ],
  "mode": "single",
  "title": "今晚安排"
}

三种模式

模式	效果	附加参数
single（默认）	点击即选定，回传选择	无
multi	勾选多个，点「提交」后回传全部选择	无
quiz	点击即时判分，显示对错 + 解析	answerIndex（必填，正确答案下标从 0 开始）、explanation（可选）

quiz 示例：

{
  "question": "Brunnstrom 分期中，「联合反应、共同运动开始出现」是哪一期？",
  "options": [
    { "label": "A. I 期（弛缓期）", "description": "无随意运动，腱反射消失" },
    { "label": "B. II 期（痉挛期）", "description": "联合反应、共同运动开始出现" },
    { "label": "C. III 期（共同运动期）", "description": "共同运动达高峰，痉挛加重" }
  ],
  "mode": "quiz",
  "answerIndex": 1,
  "explanation": "II 期（痉挛期）：联合反应与共同运动开始出现；III 期才是共同运动达到高峰。"
}

工作原理

1. 工具层（tools/offer_choice.js）：校验入参，生成一条 choice 记录（JSON）写入 {dataDir}/choices/，返回 details.card（webview 路由 /choice/:id）
2. 路由层（routes/choice.js）：GET /choice/:id 渲染可点击卡片页面；POST /choice/:id/select 接收选择、写入记录，并通过 bus.request("session:send", …) 把选择文本回传会话，助手据此继续
3. 回退层：工具返回值同时包含纯文本选项列表（1. A … 2. B …），卡片渲染失败时用户直接回复编号仍可完成交互

目录结构

choice-cards/
├── manifest.json          # 插件清单（id / name / version / trust）
├── tools/
│   └── offer_choice.js    # 工具：生成卡片 + 纯文本回退
└── routes/
    └── choice.js          # Hono 路由：渲染卡片页 + 接收选择回传会话

协议说明

卡片页面与宿主通过 window.parent.postMessage 通信（协议 hana.plugin.ui）：卡片就绪时发 hana.ready，高度变化发 ui.resize。选择提交走插件自带的 /api/plugins/choice-cards/choice/:id/select 接口，会话上下文通过 X-Hana-Plugin-Surface-Session 请求头或记录中的 sessionId 关联。

License

MIT