@zhin.js/adapter-milky 3.0.2 → 5.0.0

package/CHANGELOG.md

@@ -0,0 +1,464 @@
+# @zhin.js/adapter-milky
+
+## 5.0.0
+
+### Patch Changes
+
+- 7db69c1: 命令前缀改为适配器配置项：`MessageDispatcher` 不再硬编码 `/`，默认按消息所属适配器实例 config 的 `commandPrefix` 解析（默认 `''` 无前缀，任意文本按命令匹配），`endpoints[i].commandPrefix` 逐项覆盖；`ImRuntime({ commandPrefix })` 仍可设全局静态前缀。全部 20 个平台适配器 schema 新增 `commandPrefix` 属性。
+
+  BREAKING（行为变化）：未配置时命令不再需要 `/` 前缀——原 `/zt` 写法不再命中，直接发 `zt` 即可；需要斜杠风格的适配器请在配置里显式设 `commandPrefix: '/'`。
+
+- 713445c: 适配器配置格式定稿（不兼容旧格式）：`plugins.<adapter>` 顶层仅共享字段 + `commandPrefix`，`endpoints[i]` 携带 endpoint 级字段（`name` + 凭据，各 schema 已类型化），`endpoints` 为必填（icqq 另需顶层 `master`）；icqq 新增 `trusted` 列表（顶层/逐项均可）。scaffold-wizard 全部字段式与自定义 configure() 产出改为新格式，examples（full-bot / qq-games-bot）与 20 个适配器 README 同步迁移。
+- Updated dependencies [7db69c1]
+- Updated dependencies [e5c84ed]
+- Updated dependencies [3ea84a0]
+- Updated dependencies [1ddcd70]
+- Updated dependencies [ac9da66]
+  - @zhin.js/core@1.4.0
+  - @zhin.js/adapter@1.1.0
+  - @zhin.js/plugin-runtime@1.1.0
+  - @zhin.js/agent@1.0.5
+  - @zhin.js/host-http@1.0.2
+  - zhin.js@5.0.0
+
+## 4.0.1
+
+### Patch Changes
+
+- cc5c94d: 约定式插件运行时迁移（breaking）：插件与适配器由 `usePlugin()` / `extends Adapter` 迁移为 `definePlugin` / `defineAdapter` + `plugin.ts` + 约定目录（`adapters/`、`commands/`、`components/`、`tools/` 等）。
+
+  - 新增约定式运行时包：`@zhin.js/plugin-runtime`、`@zhin.js/adapter`、`@zhin.js/runtime`、`@zhin.js/host-http`（首版 1.0.0 走 init-publish，不在本 changeset 内 bump）。
+  - 全部 20 个平台适配器改为约定式 `defineAdapter`，旧 `usePlugin` / `extends Adapter` / `segment-mapper` 生产入口已删除；onebot11 反向 WSS、onebot12 webhook/wss、milky sse/webhook/wss、satori webhook、kook webhook、qq webhook/middleware 等 slice 1 推迟的连接模式已补齐。
+  - 游戏 / 工具 / 服务插件同步迁移到约定目录结构。
+  - CLI 增加 plugin-runtime host installer（http/database/outbound/schedule/console 等）。
+
+  后续加固（同批）：
+
+  - CLI：`zhin runtime start --daemon`（pidfile/崩溃拉起/风暴保护），orphan watchdog 防僵尸进程；legacy `zhin dev` / `zhin start` 已移除（含 `zhin restart`），`zhin stop` 兼容新 daemon。
+  - 安全：builtin 工具统一走 `security/policy-facade.ts` 的 `runToolPolicies`（声明式策略表，deny 优先）；审计日志 close flush + 背压队列；`splitCompoundCommand` 引号感知、`extractCommandName` 去引号堵绕过。
+  - 日志：Logger 双堆栈修复、本地时区、`getLogger` 挂树（`setLevel` 递归生效）、第三方库（log4js/discord）桥接、启动人读总结。
+  - 结构：`plugins/games/shared` 迁为 `packages/game-kit`（`@zhin.js/game-kit`）；死目录 `plugins/adapters/common` 删除。
+  - 脚手架：`create-zhin-app` / `zhin new` / scaffold-wizard 生成物改为 Plugin Runtime 形态（minimal-bot 同构，新配置格式）。
+  - Console：endpoint.list 真实名称与 phase、schema:get-all 按 instanceKey 映射、db:\* 接 DatabaseHost。
+
+  注：按仓库发布惯例（见 1bb345dd2），本次 breaking 迁移统一使用 patch，避免 zhin.js 5.0 级联。
+
+- 447f3e2: 迁移缺口修复（legacy 功能对齐）：
+
+  - html 段出站规范化：经 `@zhin.js/html-renderer` 渲染为 image 段（sandbox 豁免、无渲染器时降级文本），修复真实平台 `[object Object]`。
+  - 群聊 @ 触发 AI：适配器入站标注 `metadata.mentioned`（icqq/qq/slack/onebot11/onebot12/napcat/milky/discord/telegram/kook/dingtalk/satori），`matchAiTrigger` 补齐 ignorePrefixes/respondToAt/respondToPrivate/keywords（默认值与 legacy 对齐）。
+  - im_transcripts 全量流水恢复写入（chat_history 工具可用）；群聊旁听上下文回迁。
+  - `ai.trigger.timeout/thinkingMessage/errorTemplate` 生效；masters/trusted 角色解析对齐 legacy。
+  - `Message.sender` 统一为用户 ID（onebot11/12、napcat、milky 原误传显示名）；quote_id 经 metadata 接入 AI 引用上下文。
+
+- Updated dependencies [16ec4e8]
+- Updated dependencies [cc5c94d]
+- Updated dependencies [447f3e2]
+  - @zhin.js/core@1.3.5
+  - @zhin.js/agent@1.0.4
+  - @zhin.js/host-http@1.0.1
+  - zhin.js@4.1.3
+  - @zhin.js/logger@1.0.75
+  - @zhin.js/plugin-runtime@1.0.1
+  - @zhin.js/adapter@1.0.1
+
+## 3.0.2
+
+### Patch Changes
+
+- 872c583: fix: 代码格式优化
+- Updated dependencies [872c583]
+- Updated dependencies [872c583]
+  - @zhin.js/agent@1.0.3
+  - @zhin.js/host-router@2.0.3
+  - zhin.js@4.1.2
+
+## 3.0.1
+
+### Patch Changes
+
+- 5cc9c03: fix: ai 优化
+- b9b3881: fix: 增加游戏引擎以及部分游戏
+- Updated dependencies [5cc9c03]
+- Updated dependencies [7700903]
+  - @zhin.js/host-router@2.0.2
+  - zhin.js@4.1.1
+
+## 3.0.0
+
+### Patch Changes
+
+- c4575c9: fix: 输入输出优化,文档优化
+- Updated dependencies [c4575c9]
+- Updated dependencies [c4575c9]
+  - @zhin.js/host-router@2.0.1
+  - zhin.js@4.1.0
+
+## 2.0.1
+
+### Patch Changes
+
+- Updated dependencies [ae5239c]
+  - zhin.js@4.0.1
+  - @zhin.js/host-router@2.0.0
+
+## 2.0.0
+
+### Patch Changes
+
+- zhin.js@3.0.0
+- @zhin.js/host-router@2.0.0
+
+## 1.0.1
+
+### Patch Changes
+
+- d8def69: fix: 性能优化
+- 2ef4896: fix: 更新概念 Bot=>Endpoint,已适配后续更多的业务场景;统一角色权限
+- Updated dependencies [d8def69]
+- Updated dependencies [2ef4896]
+  - @zhin.js/host-router@1.0.1
+  - zhin.js@2.0.1
+
+## 1.0.0
+
+### Patch Changes
+
+- zhin.js@2.0.0
+- @zhin.js/host-router@1.0.0
+
+## 0.0.42
+
+### Patch Changes
+
+- Updated dependencies [d8547d2]
+  - zhin.js@1.0.92
+  - @zhin.js/host-router@0.0.3
+
+## 0.0.41
+
+### Patch Changes
+
+- Updated dependencies [3735e96]
+  - zhin.js@1.0.91
+  - @zhin.js/host-router@0.0.3
+
+## 0.0.40
+
+### Patch Changes
+
+- c8f8207: fix: 修复内存泄露问题
+- Updated dependencies [c8f8207]
+  - @zhin.js/host-router@0.0.3
+  - zhin.js@1.0.90
+
+## 0.0.39
+
+### Patch Changes
+
+- Updated dependencies [c78d2cd]
+  - @zhin.js/host-router@0.0.2
+  - zhin.js@1.0.89
+
+## 0.0.38
+
+### Patch Changes
+
+- Updated dependencies [ccb6e24]
+  - zhin.js@1.0.88
+
+## 0.0.37
+
+### Patch Changes
+
+- 90d9efd: fix: 处理包名
+  - zhin.js@1.0.87
+  - @zhin.js/host-router@0.0.1
+
+## 0.0.36
+
+### Patch Changes
+
+- 7e14f8d: fix: 统一发个版,优化一些列安全问题
+- Updated dependencies [7e14f8d]
+  - zhin.js@1.0.86
+  - @zhin.js/host-router@1.0.79
+
+## 0.0.35
+
+### Patch Changes
+
+- zhin.js@1.0.85
+- @zhin.js/host-router@1.0.78
+
+## 0.0.34
+
+### Patch Changes
+
+- 0db9fed: fix: deno deploy
+- f19d2e0: fix: remove multiple runtime support
+- Updated dependencies [0db9fed]
+- Updated dependencies [f19d2e0]
+  - zhin.js@1.0.84
+  - @zhin.js/host-router@1.0.77
+
+## 0.0.33
+
+### Patch Changes
+
+- 775427e: fix: edge 支持
+- Updated dependencies [775427e]
+  - @zhin.js/host-router@1.0.76
+  - zhin.js@1.0.83
+
+## 0.0.32
+
+### Patch Changes
+
+- 32049f5: fix: init publish
+- Updated dependencies [32049f5]
+  - @zhin.js/host-router@1.0.75
+  - zhin.js@1.0.82
+
+## 0.0.31
+
+### Patch Changes
+
+- Updated dependencies [8086ccb]
+  - zhin.js@1.0.81
+  - @zhin.js/host-router@1.0.74
+
+## 0.0.30
+
+### Patch Changes
+
+- zhin.js@1.0.80
+- @zhin.js/host-router@1.0.73
+
+## 0.0.29
+
+### Patch Changes
+
+- zhin.js@1.0.79
+- @zhin.js/host-router@1.0.72
+
+## 0.0.28
+
+### Patch Changes
+
+- zhin.js@1.0.78
+- @zhin.js/host-router@1.0.71
+
+## 0.0.27
+
+### Patch Changes
+
+- zhin.js@1.0.77
+- @zhin.js/host-router@1.0.70
+
+## 0.0.26
+
+### Patch Changes
+
+- Updated dependencies [cb9fbf1]
+  - zhin.js@1.0.76
+  - @zhin.js/host-router@1.0.69
+
+## 0.0.25
+
+### Patch Changes
+
+- zhin.js@1.0.75
+- @zhin.js/host-router@1.0.68
+
+## 0.0.24
+
+### Patch Changes
+
+- Updated dependencies [c9dec38]
+  - zhin.js@1.0.74
+  - @zhin.js/host-router@1.0.67
+
+## 0.0.23
+
+### Patch Changes
+
+- f1e9a76: fix: 提高 skill 质量
+  - zhin.js@1.0.73
+  - @zhin.js/host-router@1.0.66
+
+## 0.0.22
+
+### Patch Changes
+
+- abc75a4: fix: 优化,客户端构建优化
+
+## 0.0.21
+
+### Patch Changes
+
+- e28fd7c: fix: 重新发版
+- Updated dependencies [e28fd7c]
+  - zhin.js@1.0.72
+  - @zhin.js/host-router@1.0.65
+
+## 0.0.20
+
+### Patch Changes
+
+- 4304825: fix: 重新发版
+- Updated dependencies [4304825]
+  - zhin.js@1.0.71
+  - @zhin.js/host-router@1.0.64
+
+## 0.0.19
+
+### Patch Changes
+
+- zhin.js@1.0.68
+- @zhin.js/host-router@1.0.63
+
+## 0.0.18
+
+### Patch Changes
+
+- Updated dependencies [0eba6d6]
+  - @zhin.js/host-router@1.0.62
+  - zhin.js@1.0.67
+
+## 0.0.17
+
+### Patch Changes
+
+- zhin.js@1.0.66
+- @zhin.js/host-router@1.0.61
+
+## 0.0.16
+
+### Patch Changes
+
+- zhin.js@1.0.65
+- @zhin.js/host-router@1.0.60
+
+## 0.0.15
+
+### Patch Changes
+
+- 9577eba: fix: tool 收集 bug,升级 ts 到 6.0.2
+- Updated dependencies [9577eba]
+  - zhin.js@1.0.64
+  - @zhin.js/host-router@1.0.59
+
+## 0.0.14
+
+### Patch Changes
+
+- Updated dependencies [ba30934]
+  - @zhin.js/host-router@1.0.58
+  - zhin.js@1.0.63
+
+## 0.0.13
+
+### Patch Changes
+
+- zhin.js@1.0.62
+- @zhin.js/host-router@1.0.57
+
+## 0.0.12
+
+### Patch Changes
+
+- zhin.js@1.0.61
+- @zhin.js/host-router@1.0.56
+
+## 0.0.11
+
+### Patch Changes
+
+- 5073d4c: chore: chore: update TypeScript version to ^5.9.3 across all plugins and packages
+  feat: enhance ai-text-as-image output registration with off handler for cleanup
+  fix: remove unnecessary logging in ensureBuiltinFontsCached function
+  refactor: simplify action handlers in html-renderer tools
+  chore: add README files for queue-sandbox-poc and event-delivery packages
+  chore: adjust pnpm workspace configuration to exclude games directory
+  chore: update tsconfig to include plugins directory for TypeScript compilation
+- Updated dependencies [5073d4c]
+  - zhin.js@1.0.60
+  - @zhin.js/host-router@1.0.55
+
+## 0.0.10
+
+### Patch Changes
+
+- c212bf7: fix: 适配器优化
+- Updated dependencies [c212bf7]
+  - zhin.js@1.0.59
+  - @zhin.js/host-router@1.0.54
+
+## 0.0.9
+
+### Patch Changes
+
+- zhin.js@1.0.58
+- @zhin.js/host-router@1.0.53
+
+## 0.0.8
+
+### Patch Changes
+
+- zhin.js@1.0.57
+- @zhin.js/host-router@1.0.52
+
+## 0.0.7
+
+### Patch Changes
+
+- zhin.js@1.0.56
+- @zhin.js/host-router@1.0.51
+
+## 0.0.6
+
+### Patch Changes
+
+- zhin.js@1.0.55
+- @zhin.js/host-router@1.0.50
+
+## 0.0.5
+
+### Patch Changes
+
+- 16c8f92: fix: 统一发一次版
+- Updated dependencies [16c8f92]
+  - zhin.js@1.0.54
+  - @zhin.js/host-router@1.0.49
+
+## 0.0.4
+
+### Patch Changes
+
+- zhin.js@1.0.53
+- @zhin.js/host-router@1.0.48
+
+## 0.0.3
+
+### Patch Changes
+
+- a3511a0: 各包内 Agent 技能说明已固定为随包发布的 `skills/*/SKILL.md`（替代已移除的运行时 `declareSkill`）。本批为 registry / 分发侧对齐的 **patch** 版本递增。
+- Updated dependencies [a3511a0]
+  - @zhin.js/host-router@1.0.47
+
+## 0.0.2
+
+### Patch Changes
+
+- Updated dependencies [bb6bfa8]
+- Updated dependencies [bb6bfa8]
+  - zhin.js@1.0.52
+  - @zhin.js/host-router@1.0.46
+
+## 0.0.1
+
+### Patch Changes
+
+- zhin.js@1.0.51
+- @zhin.js/host-router@1.0.45

package/README.md

@@ -1,163 +1,78 @@
 # @zhin.js/adapter-milky
 
-Zhin.js [Milky](https://milky.ntqqrev.org/) 协议适配器，**一个适配器**支持 WebSocket 正向/反向、SSE、Webhook 四种连接方式，由配置项 `connection` 区分；支持 HTTP API 调用与 `access_token` 鉴权。
+Zhin.js [Milky](https://milky.ntqqrev.org/) 协议适配器（Plugin Runtime）。默认 **正向 WebSocket 客户端**（`connection: ws`）；亦支持 **Webhook**、**反向 WS**（经 `httpHostToken`）与 **SSE**（HTTP GET `/event`，fetch 解析 `text/event-stream`）。
 
 ## 功能特性
 
-- 🔌 Milky 协议兼容（[通信说明](https://milky.ntqqrev.org/guide/communication)）
-- 📦 **单一适配器**：`context: milky`，通过 `connection` 选择连接方式
-- 🌐 **WebSocket 正向**（`connection: ws`）：应用连协议端 `ws(s)://baseUrl/event`
-- 📡 **SSE**（`connection: sse`）：应用 GET 协议端 `/event`
-- 📮 **Webhook**（`connection: webhook`）：应用提供 POST 端点收事件
-- 🔄 **WebSocket 反向**（`connection: wss`）：应用开 WS 服务端，协议端来连
-- 🔐 `access_token` 鉴权（Header 或 query）
-- 📨 群聊 / 私聊消息收发与消息段映射
-- 🛠️ HTTP API 封装，供发消息、撤回、群管等复用
+- [Milky 协议](https://milky.ntqqrev.org/guide/communication) 兼容（事件 + HTTP API）
+- 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
+- **正向 WebSocket**（`connection: ws`）：应用连协议端 `ws(s)://baseUrl/event`
+- `access_token` 鉴权（Bearer + query）
+- 入站经 `messageGatewayToken`；出站 `send({ target, payload })` → HTTP `send_*_message`
 
 ## 安装
 
 ```bash
-pnpm add @zhin.js/adapter-milky ws eventsource
+pnpm add @zhin.js/adapter-milky
 ```
 
-适配器依赖 `@zhin.js/host-router` 提供的 `router` 才能注册（Webhook/反向 WS 需挂路由），请同时启用 HTTP 服务：
+## Plugin Runtime
 
-```bash
-pnpm add @zhin.js/host-router
-```
-
-## 配置
+- `@zhin.js/adapter` — 约定式 `adapters/milky.ts`（`defineAdapter`）
+- `@zhin.js/core` — `messageGatewayToken` 入站/出站
+- `@zhin.js/plugin-runtime` — `plugin.ts`（`definePlugin`）
+- 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
 
-所有 Endpoint 使用 **同一 context：`milky`**，通过 **`connection`** 区分连接方式。
+入站：`gateway.receive({ adapter, target: "private:uid"|"group:gid", content, sender, metadata })`  
+出站：`send({ target, payload })` → HTTP `send_private_message` / `send_group_message`（payload 已由 gateway/core 渲染；无 segment-mapper）
 
-### WebSocket 正向
+## 最小配置
 
 ```yaml
+# zhin.config.yml（Plugin Runtime）
 plugins:
-  - "@zhin.js/host-router"
-  - "@zhin.js/adapter-milky"
-
-endpoints:
-  - context: milky
+  milky:
     connection: ws
-    name: milky-bot
-    baseUrl: "http://127.0.0.1:8080"
-    access_token: "${MILKY_ACCESS_TOKEN}"
     reconnect_interval: 5000
     heartbeat_interval: 30000
+    endpoints:
+      - name: milky-bot
+        baseUrl: "http://127.0.0.1:8080"
+        access_token: "${MILKY_ACCESS_TOKEN}"
 ```
 
-### SSE
+根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-milky`（`instanceKey: milky`）。
 
-```yaml
-endpoints:
-  - context: milky
-    connection: sse
-    name: milky-sse-bot
-    baseUrl: "http://127.0.0.1:8080"
-    access_token: "${MILKY_ACCESS_TOKEN}"
-```
-
-### Webhook
+## 连接方式
 
-```yaml
-endpoints:
-  - context: milky
-    connection: webhook
-    name: milky-webhook-bot
-    baseUrl: "http://协议端地址"
-    path: "/milky/webhook"               # 应用接收事件的 POST 路径
-    access_token: "${MILKY_ACCESS_TOKEN}"
-```
-
-### WebSocket 反向
-
-```yaml
-endpoints:
-  - context: milky
-    connection: wss
-    name: milky-wss-bot
-    baseUrl: "http://协议端地址"
-    path: "/milky/event"                 # 应用 WS 服务端路径
-    access_token: "${MILKY_ACCESS_TOKEN}"
-    heartbeat_interval: 30000
-```
+| connection | 状态 |
+|------------|------|
+| `ws` | 已实现（推荐） |
+| `sse` | HTTP GET `/event`（`Accept: text/event-stream`） || `webhook` | 已实现：POST 入站 + baseUrl HTTP API 出站 |
+| `wss` | 已实现：反向 WS（httpHostToken） |
 
 ## 鉴权
 
-所有连接方式统一支持：
-
-- **Header**：`Authorization: Bearer {access_token}`
-- **Query**：`access_token=xxx`
-
-建议配置 `access_token`，并与协议端一致。
-
-## 连接方式对比
+- **Bearer**：`Authorization: Bearer <access_token>`
+- 正向 WS 在 Upgrade 时附带请求头，并在 URL query 写入 `access_token`
+- HTTP API 同样使用 Header / query 鉴权
 
-| connection | 说明                           |
-|------------|--------------------------------|
-| `ws`       | 应用主动连协议端 `/event`      |
-| `sse`      | 应用 GET `/event` 拉取事件流   |
-| `webhook`  | 协议端 POST 到应用配置的 path  |
-| `wss`      | 协议端连应用提供的 WS path     |
+## 消息 ID
 
-## 使用示例
-
-### 消息处理
-
-```typescript
-import { addCommand, MessageCommand } from 'zhin.js'
-
-addCommand(new MessageCommand('hello <name:text>')
-  .action(async (message, result) => {
-    return `你好，${result.params.name}！`
-  })
-)
-```
-
-### 发送消息段
-
-```typescript
-addCommand(new MessageCommand('pic')
-  .action(async () => {
-    return [
-      { type: 'text', data: { text: '图片：' } },
-      { type: 'image', data: { url: 'https://example.com/img.png' } }
-    ]
-  })
-)
-```
-
-发消息、撤回、群管等通过适配器封装的 HTTP API 完成。群管能力通过 `ISceneManagement` 自动注册为工具，详见 [工具与技能](/advanced/tools-skills)。
+`{message_scene}:{peer_id}:{message_seq}`（如 `group:123456:10001`）。
 
 ## AI 工具
 
-Permit 词汇见 `agent/PERMITS.md`（维护者参考）。技能说明见 `agent/skills/milky.md`。群管标准工具由 `createSceneManagementTools()` 注册。
-
+| 类别 | 路径 |
+|------|------|
+| Permit 词汇 | `agent/PERMITS.md` |
+| 技能说明 | `agent/skills/milky.md` |
 
-## 消息 ID 格式
-
-`{message_scene}:{peer_id}:{message_seq}`（如 `group:123456:10001`）。撤回时使用该 ID。
-
-## 协议与 API 参考
+## 文档链接
 
 - [Milky 快速开始](https://milky.ntqqrev.org/)
 - [Milky 通信](https://milky.ntqqrev.org/guide/communication)
-- [事件结构](https://milky.ntqqrev.org/struct/Event)、[接收消息](https://milky.ntqqrev.org/struct/IncomingMessage)、[消息 API](https://milky.ntqqrev.org/api/message)、[群聊 API](https://milky.ntqqrev.org/api/group)
-
-## 依赖项
-
-- `ws` - WebSocket 客户端/服务端
-- `eventsource` - SSE 客户端
-- `zhin.js` - Zhin 核心
-- `@zhin.js/host-router` - 提供 router，适配器注册依赖
-
-## 开发
-
-```bash
-pnpm build   # 构建
-pnpm clean   # 清理
-```
+- [适配器概览](https://zhin.js.org/essentials/adapters)
 
 ## 许可证