dsh-pet-floating/HERMES-PLUGIN-CONVERSION.md

DeepSeek Hermes 插件 → 小鲸娘插件 转换规范

给应用内「对话」用：把这份规范贴进对话，或直接说「把下面这个 Hermes 插件转成小鲸娘插件」， AI 会输出 <<<PET_PLUGIN id="...">>> 代码块，应用自动安装。

一、两边是什么

	Hermes Agent 插件	小鲸娘插件
语言	Python	JavaScript（跑在宠物 WebView 里）
形态	目录 + plugin.yaml + register()	一段 JS 代码
能力	注册工具、hook、web provider、设置项	说话/通知/播动作/弹表情/执行技能/监听互动
安装	hermes plugins install	对话里给代码，或 POST /api/plugin

结论：Hermes 插件不能原样搬进来（没有 Python 宿主），但行为可以翻译。

二、能力对照表

Hermes 里的东西	小鲸娘里怎么写
on_startup() / 顶层初始化	把初始化代码直接写在插件顶层
定时任务 / cron hook	setInterval(() => Pet.say('…'), 3600000)
工具 tool_xxx() 被调用时通知	Pet.notify('done', '任务完成')
打印/汇报消息	Pet.say('文字', 6000)
触发动画	Pet.anim({tag:'happy'}) / {name:'…'} / {random:true}
发图片/表情	Pet.meme({tag:'praise'})
组合动作	Pet.skill('work_done')
监听宠物互动	Pet.on('tap', fn)、Pet.on('drag_end', fn)、Pet.on('long_press', fn)
读宠物状态	Pet.status()（返回 Promise）
HTTP 请求	fetch() 可用（WebView 有网络权限）
设置项 / 环境变量	写成代码顶部的 var CONFIG = {...}；不要把密钥写进插件

三、不能转换的

• 注册 LLM provider / 修改 agent 推理行为（那属于宿主，小鲸娘不跑模型路由）
• 依赖 Python 库（numpy/httpx/…）：只能用 JS 和 fetch
• 依赖 Hermes 的配置目录、secrets、工具注册表
• 需要拦截「另一个程序内部事件」的 hook —— 改由对方通过 HTTP 调小鲸娘

四、输出格式（AI 必读）

需要安装插件时，只输出下面这种块，应用会自动安装并从可见消息里剥离：

<<<PET_PLUGIN id="插件id（字母数字下划线）">>>
// 这里写 JS
setInterval(function () { Pet.say('该喝水啦～'); }, 3600000);
<<<END>>>

规则：

• id 必填，只能 [A-Za-z0-9_-]，重复会覆盖
• 代码里只用 Pet.* 与浏览器标准 API
• 安装后回一句简短说明（装了啥、什么时候触发）

五、三个转换例子

1) Hermes 定时提醒插件

# Hermes
def on_startup(ctx):
    ctx.schedule_interval(3600, lambda: ctx.notify("该喝水啦"))

// 小鲸娘
setInterval(function () { Pet.say('该喝水啦～'); }, 3600000);

2) Hermes 工具结果通知

// 小鲸娘：被戳时报告一次状态
Pet.on('tap', function () {
  Pet.status().then(function (s) {
    Pet.say('现在是：' + (s.anim ? s.anim.name : '待机'));
  });
});

3) Hermes web 搜索插件（只能部分转换） 注册 provider 那部分转不了；能保留的是「用完给个反馈」：

// 收到外部通知后弹个表情（由 Hermes 侧 POST /api/task 触发）
Pet.meme({ tag: 'praise' });