@zhin.js/adapter-kook 5.0.2 → 6.0.0

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # @zhin.js/adapter-kook
 
+## 6.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
+
+## 5.0.3
+
+### 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
+
 ## 5.0.2
 
 ### Patch Changes

package/README.md

@@ -1,16 +1,14 @@
 # @zhin.js/adapter-kook
 
-Zhin.js KOOK（开黑啦）适配器，基于 KOOK 官方 API 开发，支持频道和私聊消息。
+Zhin.js KOOK（开黑啦）适配器（Plugin Runtime），默认通过 **WebSocket Gateway**（`kook-client`）收发消息；可选 **Webhook** 模式经 `httpHostToken` 接收平台 POST 推送。
 
-## 功能特性
+## 功能
 
-- 🗣️ 支持 KOOK 频道和私聊消息处理
-- 📨 消息发送和接收处理
-- 🔄 消息格式转换和适配
-- 📁 自动数据目录管理
-- ⚡ 基于 WebSocket 的实时通信
-- 📝 支持 Markdown 消息格式
-- ⏳ AI 处理中表情回应（Typing Indicator / reaction，频道与私聊）
+- WebSocket Gateway 入站（默认；无需公网 HTTPS / host）
+- Webhook 入站（`connection: webhook` + `httpHostToken` + `verify_token`）
+- 解析频道与私聊文本消息
+- 出站 `send({ target, payload })` → KOOK KMarkdown（`channel:id` / `private:id`）
+- 约定式 `defineAdapter` / `definePlugin`（无需 `usePlugin`）
 
 ## 安装
 
@@ -18,478 +16,88 @@ Zhin.js KOOK（开黑啦）适配器，基于 KOOK 官方 API 开发，支持频
 pnpm add @zhin.js/adapter-kook
 ```
 
+## Plugin Runtime
+
+- `@zhin.js/adapter` — 约定式 `adapters/kook.ts`（`defineAdapter`）
+- `@zhin.js/core` — `messageGatewayToken` 入站/出站
+- `@zhin.js/host-http` — Webhook 模式 POST 路由（WebSocket 不需要）
+- `@zhin.js/plugin-runtime` — `plugin.ts`（`definePlugin`）
+- 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`
+- **WebSocket 路径无需** `@zhin.js/host-http` / `@zhin.js/host-router`
+
+入站：`gateway.receive({ adapter, target: 'channel:…'|'private:…', content, sender, metadata })`  
+出站：`send({ target, payload })` → `sendChannelMsg` / `sendPrivateMsg`
+
 ## 前置条件
 
 | 要求 | 说明 |
 |------|------|
 | **Bot Token** | 在 [KOOK 开发者平台](https://developer.kookapp.cn/) 创建应用并获取 |
 | **邀请入服** | 将机器人邀请到目标服务器，并授予查看频道、发送消息等权限 |
-| **连接方式** | 当前适配器通过 **WebSocket** 连接 KOOK（`kook-client`）；无需公网 URL |
-| **host-router** | 不需要 |
+| **WebSocket（默认）** | `kook-client` 正向连接；无需公网 URL |
+| **Webhook** | 需公网 HTTPS + Host `httpHostToken`；与 WebSocket 互斥 |
+| **host-http** | 仅 Webhook 模式需要 |
 
-必填字段见 `KookEndpointConfig`：`context`、`name`、`token`。
+必填字段（`endpoints[i]`）：`name`、`token`。
 
 ## 最小配置
 
 ```yaml
+# zhin.config.yml（Plugin Runtime）
 plugins:
-  - "@zhin.js/adapter-kook"
-
-endpoints:
-  - context: kook
-    name: my-kook-bot
-    token: "${KOOK_TOKEN}"
-```
-
-## 配置
-
-可选字段（见 `KookEndpointConfig`）：`data_dir`、`timeout`、`max_retry`、`ignore`、`logLevel`、`typingIndicator`。
-
-```yaml
-endpoints:
-  - context: kook
-    name: my-kook-bot
-    token: "${KOOK_TOKEN}"
-    data_dir: ./data/kook
-    # AI 处理中：频道/私聊贴表情回应（不打「正在思考」消息）
-    typingIndicator:
-      enabled: true
-      defaultEmoji: "⏳"
-      autoRemove: true
-      privateConfig:
-        type: reaction
-        emoji: "⏳"
-      groupConfig:
-        type: reaction
-        emoji: "⏳"
-```
-
-`emoji` 可用 Unicode（如 `⏳`）或 KOOK 自定义表情 ID；处理完成后会自动 `delete-reaction` 移除。
-
-TypeScript 等价写法：
-
-```typescript
-import { defineConfig } from 'zhin.js'
-
-export default defineConfig({
-  endpoints: [
-    {
-      context: 'kook',
-      name: 'my-kook-bot',
-      token: process.env.KOOK_TOKEN!,
-      data_dir: './data/kook',
-    },
-  ],
-  plugins: ['@zhin.js/adapter-kook'],
-})
-```
-
-## 获取配置信息
-
-### 1. 创建 KOOK 机器人
-
-1. 访问 [KOOK 开发者平台](https://developer.kookapp.cn/)
-2. 登录并创建应用
-3. 在应用设置中获取 **Bot Token**
-
-### 2. 配置机器人
-
-在应用设置中：
-- 获取 **Bot Token**（必需）
-- 将机器人邀请到需要的服务器并配置频道权限
-
-### 3. 邀请机器人
-
-- 在应用详情页获取邀请链接
-- 将机器人邀请到需要的服务器
-- 确保机器人有相应的权限
-
-## 使用示例
-
-### 基础消息处理
-
-```typescript
-import { usePlugin, MessageCommand } from 'zhin.js'
-
-const { addCommand } = usePlugin()
-
-addCommand(new MessageCommand('hello <name:text>')
-  .action(async (message, result) => {
-    return `你好，${result.params.name}！`
-  })
-)
-```
-
-### 频道消息
-
-```typescript
-import { onMessage } from 'zhin.js'
-
-onMessage(async (message) => {
-  if (message.$channel.type === 'channel') {
-    console.log(`频道消息：${message.$raw}`)
-  }
-})
-```
-
-### 私聊消息
-
-```typescript
-import { onPrivateMessage } from 'zhin.js'
-
-onPrivateMessage(async (message) => {
-  await message.$reply('收到你的私信了！')
-})
-```
-
-### 系统通知（notice）
-
-KOOK 的入群、退群、消息删除、表情回应、频道变更等 **系统消息**（`type: 255`）由适配器在 gateway 层拦截并转为标准 `Notice`，与 ICQQ / NapCat 一样可通过插件生命周期订阅：
-
-```typescript
-import { usePlugin } from 'zhin.js'
-
-const plugin = usePlugin()
-
-// 入群欢迎（与 group-suite 等插件兼容）
-plugin.on('notice.receive', async (notice) => {
-  if (notice.$adapter !== 'kook') return
-  if (notice.$type === 'group_member_increase') {
-    console.log('新成员', notice.$target?.id, '加入服务器', notice.$channel.id)
-  }
-})
-```
-
-常见映射（`extra.type` → `$type`）：
-
-| KOOK `extra.type` | Zhin `$type` |
-|---|---|
-| `joined_guild` | `group_member_increase` |
-| `exited_guild` | `group_member_decrease` |
-| `deleted_message` | `group_recall` |
-| `deleted_private_message` | `friend_recall` |
-| `added_reaction` / `deleted_reaction` | `group_emoji_reaction` |
-| 其它系统事件 | 保留原始类型名（如 `updated_channel`） |
-
-需要原始 gateway 载荷时，可监听适配器上的 `kook.gateway`（含 `post_type` / `notice_type` 增强字段）：
-
-```typescript
-import { usePlugin } from 'zhin.js'
-
-usePlugin().useContext('kook', (kook) => {
-  kook.on('kook.gateway', (raw) => {
-    if (raw.post_type === 'notice') {
-      console.log('KOOK 系统事件', raw.notice_type, raw.extra?.body)
-    }
-  })
-})
-```
-
-### Markdown 消息
-
-```typescript
-addCommand(new MessageCommand('md')
-  .action(async (message) => {
-    return [
-      {
-        type: 'text',
-        data: {
-          text: '**这是粗体** *这是斜体*\n[链接](https://kookapp.cn)'
-        }
-      }
-    ]
-  })
-)
-```
-### Card 消息 (卡片消息)
-
-```typescript
-addCommand(new MessageCommand('card')
-    .action(async (message) => {
-        logger.info(message);
-        if (message.$adapter !== 'kook') {
-            return "暂未适配平台！";
-        } else {
-            const cardMessage = [{
-                type: 'card',
-                theme: "secondary",
-                size: "lg",
-                modules: [
-                    msgMod.section(
-                        element.markdown("(font) 卡片信息(font)[purple](font) Card信息(font)[warning]")
-                    ),
-                    msgMod.container(
-                        [
-                            element.image('https://api.owii.cn/gif/cache/2026-01-03_07-17-15.gif')
-                        ]
-                    )
-                ]
-            }];
-            return cardMessage;
-        }
-        return `当前平台：${message.$adapter}`;
-    })
-)
-```
-
-## 消息类型支持
-
-### 接收消息类型
-
-- ✅ 文本消息
-- ✅ 图片消息
-- ✅ 视频消息
-- ✅ 文件消息
-- ✅ Markdown 消息
-- ✅ KMarkdown 消息
-- ✅ 卡片消息
-
-### 发送消息类型
-
-- ✅ 文本消息
-- ✅ 图片消息
-- ✅ 视频消息
-- ✅ 文件消息
-- ✅ Markdown 消息
-- ✅ 卡片消息
-
-## API 方法
-
-```typescript
-const endpoint = app.adapters.get('kook')?.endpoints.get('my-kook-bot')
-
-// 发送频道消息
-await endpoint.sendChannelMsg(channelId, '消息内容')
-
-// 发送私聊消息
-await endpoint.sendPrivateMsg(userId, '消息内容')
-
-// 统一发送（出站返回带路由的 msg ref，见「消息 ID 与路由」）
-const msgRef = await endpoint.$sendMessage({
-  context: 'kook',
-  bot: 'my-kook-bot',
-  type: 'group', // 或 'private'
-  id: channelOrUserId,
-  content: [{ type: 'text', data: { text: '你好' } }],
-})
-
-// 撤回：支持出站 ref，或入站 plain msg_id + 路由由适配器推断
-await endpoint.$recallMessage(msgRef)
-await endpoint.$recallMessage(message.$id, { route: 'direct' }) // 入站私聊
-
-// Typing Indicator：在用户消息上贴/删表情回应
-const reactionId = await endpoint.$addReaction(message.$id, '⏳', {
-  sceneType: message.$channel.type === 'private' ? 'private' : 'channel',
-})
-await endpoint.$removeReaction(message.$id, reactionId)
-```
-
-## 🔧 频道管理工具（AI 可调用）
-
-
-适配器自动注册了一系列频道管理工具，这些工具可以被 AI 调用，实现智能化的频道管理。
-
-### 权限要求
-
-| 工具 | 所需权限 | 说明 |
-|------|----------|------|
-| `kook_kick_user` | 管理员 | 踢出用户 |
-| `kook_ban_user` | 管理员 | 将用户加入黑名单 |
-| `kook_unban_user` | 管理员 | 解除用户封禁 |
-| `kook_grant_role` | 管理员 | 授予用户角色 |
-| `kook_revoke_role` | 管理员 | 撤销用户角色 |
-| `kook_set_nickname` | 管理员 | 设置用户昵称 |
-| `kook_list_roles` | 普通用户 | 查看角色列表 |
-| `kook_create_role` | 服务器主人 | 创建新角色 |
-| `kook_delete_role` | 服务器主人 | 删除角色 |
-| `kook_list_members` | 普通用户 | 查看成员列表 |
-
-### 使用示例
-
-#### 通过 AI 对话管理频道
-
-```
-用户（服务器主人）：把 @小明 踢出服务器
-AI：已将用户 小明 踢出服务器。
-
-用户（管理员）：把 @捣蛋鬼 禁言，他总是发广告
-AI：已将用户 捣蛋鬼 加入黑名单，原因：发布广告。
-
-用户：查看服务器角色列表
-AI：当前服务器有以下角色：
-1. 管理员 (ID: 123)
-2. 活跃成员 (ID: 456)
-3. 新人 (ID: 789)
-```
-
-#### 编程调用
-
-```typescript
-// 获取 KOOK Endpoint 实例
-const kookAdapter = app.adapters.get('kook')
-const endpoint = kookAdapter?.endpoints.get('my-kook-bot')
-
-// 踢出用户
-await endpoint.kickUser(guildId, userId)
-
-// 加入黑名单（封禁）
-await endpoint.addToBlacklist(guildId, userId, '违规发言', 7) // 删除7天内消息
-
-// 解除封禁
-await endpoint.removeFromBlacklist(guildId, userId)
-
-// 授予角色
-await endpoint.grantRole(guildId, userId, roleId)
-
-// 撤销角色
-await endpoint.revokeRole(guildId, userId, roleId)
-
-// 设置昵称
-await endpoint.setNickname(guildId, userId, '新昵称')
-
-// 获取角色列表
-const roles = await endpoint.getRoleList(guildId)
-
-// 创建角色
-const newRole = await endpoint.createRole(guildId, '新角色')
-
-// 删除角色
-await endpoint.deleteRole(guildId, roleId)
-
-// 获取成员列表
-const members = await endpoint.getGuildMembers(guildId)
-```
-
-### 发送者权限信息
-
-消息中的 `$sender` 现在包含 KOOK 特有的权限信息：
-
-```typescript
-interface KookSenderInfo {
-  id: string;
-  name: string;
-  permission?: KookPermission;  // 1=普通, 2=管理员, 4=服务器主人, 5=频道管理员
-  roles?: number[];             // 用户角色ID列表
-  isGuildOwner?: boolean;       // 是否为服务器主人
-  isAdmin?: boolean;            // 是否为管理员
-}
-```
-
-#### 在插件中检查权限
-
-```typescript
-onMessage(async (message) => {
-  const sender = message.$sender as KookSenderInfo;
-  
-  if (sender.isGuildOwner) {
-    console.log('这是服务器主人的消息');
-  }
-  
-  if (sender.isAdmin) {
-    console.log('这是管理员的消息');
-  }
-})
+  kook:
+    # connection: websocket   # 默认
+    endpoints:
+      - name: my-kook-bot
+        token: ${KOOK_TOKEN}
 ```
 
-## 连接说明
-
-本适配器固定使用 **WebSocket** 与 KOOK 通信（由 `kook-client` 实现），无需配置 Webhook 回调地址。
-
-## 消息 ID 与路由
-
-KOOK 频道与私聊的删除 / 表情 API 路径不同（`/v3/message/*` vs `/v3/direct-message/*`）。适配器在出站返回值与 reaction 句柄里编码路由，避免撤回或删表情时误打另一套 API。
-
-| 场景 | ID 形式 | 说明 |
-|------|---------|------|
-| 入站消息 | plain `msg_id` | `message.$id` 为 KOOK 原始 UUID；`message.$recall()` 会按频道/私聊自动选路由 |
-| 出站 `$sendMessage` 返回值 | `kook:channel:{msgId}` 或 `kook:direct:{msgId}` | 供 `$recallMessage`、Typing Indicator message 模式删除 |
-| 出站 `$addReaction` 返回值 | `reaction:channel:{msgId}:{emoji}` 或 `reaction:direct:...` | 供 `$removeReaction` 精确删表情 |
-
-实现细节见 `plugins/adapters/kook/src/kook-msg-route.ts`。
-
-### @ 提及与 AI 触发
-
-入站 `(met)userId(met)` / `at` 段会规范为带 `user_id` 的 `at` 元素；连接后日志会输出 `platform_user_id`，用于配置 AI 的 `@bot` 触发匹配。
-
-## 注意事项
-
-### 权限配置
-
-确保机器人有以下权限：
-- 查看频道
-- 发送消息
-- 管理消息（如需撤回）
-- 查看服务器成员列表
-
-### 频率限制
-
-KOOK 有消息发送频率限制：
-- 每秒最多 5 条消息
-- 建议添加发送队列管理
+根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-kook`（`instanceKey: kook`）。
 
-## 故障排查
+## 环境变量
 
-### 机器人无法收到消息
-
-1. Token 是否正确
-2. 机器人是否已加入服务器
-3. 机器人是否有查看频道权限
-4. WebSocket 连接是否正常（查看启动日志）
-
-### 发送失败或频率限制
-
-KOOK 有发送频率限制（约每秒 5 条）；建议队列化发送并检查 API 错误码。
+| 变量 | 说明 |
+|------|------|
+| `KOOK_TOKEN` / `KOOK_BOT_TOKEN` | Bot Token |
+| `KOOK_BOT_NAME` | 可选，默认 endpoint 名 |
+| `KOOK_VERIFY_TOKEN` | Webhook 模式 verify token |
+| `KOOK_ENCRYPT_KEY` | 可选，Webhook 消息加密密钥 |
+| `KOOK_WEBHOOK_PATH` | 可选，默认 `/kook/webhook` |
 
-### 如何发送卡片消息
+## Webhook
 
-使用 KOOK 卡片消息格式：
+在 KOOK 开发者后台选择 **WebHook** 连接模式，Callback URL 指向 Host 暴露的公网地址（建议在 URL 加 `?compress=0` 便于调试）。
 
-```typescript
-await endpoint.sendChannelMsg(channelId, [
-  {
-    type: 'card',
-    data: {
-      // 卡片消息内容
-    }
-  }
-])
+```yaml
+plugins:
+  kook:
+    connection: webhook
+    webhookPath: /kook/webhook
+    endpoints:
+      - name: my-kook-bot
+        token: ${KOOK_TOKEN}
+        verify_token: ${KOOK_VERIFY_TOKEN}
+        # encrypt_key: ${KOOK_ENCRYPT_KEY}   # 启用消息加密时必填
 ```
 
-## 文档链接
-
-- [KOOK 适配器文档](https://zhin.js.org/adapters/kook)
-- [适配器概览](https://zhin.js.org/essentials/adapters)
-- [KOOK 开发者平台](https://developer.kookapp.cn/)
-- [KOOK 开发文档](https://developer.kookapp.cn/doc/)
-- [kook-client](https://github.com/zhinjs/kook-client)
-
-## full-bot L4 参考
+Host 需注入 `httpHostToken`。Challenge（`type: 255`）会校验 `verify_token` 并回显 `challenge`；普通事件经 `gateway.receive` 入站，出站仍走 KOOK HTTP API。
 
-[`examples/full-bot`](../../../examples/full-bot/) 默认加载本适配器（`endpoints` 段需填写 `KOOK_TOKEN` 后取消注释）。
+## AI 工具（Skill）
 
-- 入站 → `ZhinAgent` → 出站走 `Adapter.sendMessage` 统一链路
-- 契约测试：`plugins/adapters/kook/tests/l4-contract.test.ts` + `integration.test.ts`
-- CI：`L4_SKIP_PLATFORM=1` 跳过实机；本地验证配置 `KOOK_TOKEN` 后可跑 optional smoke
-
-详见 [full-bot ACCEPTANCE.md](../../../examples/full-bot/ACCEPTANCE.md)。
+| 类别 | 路径 |
+|------|------|
+| Permit 词汇 | `agent/PERMITS.md` |
+| 平台工具 | `agent/tools/`（角色、黑名单等） |
+| 技能说明 | `agent/skills/kook.md` |
 
-## 依赖项
+## 平台权限（platform permit）
 
-- `kook-client` - KOOK 客户端库
-- `zhin.js` - Zhin 核心框架
+platform permit checker 由 `plugin.ts` 的 generation 生命周期注册；CapabilityIngress 与 ToolSystem 统一经 Core `canAccessTool()` 消费工具的 platform permit 声明。
 
-## 开发
+## 迁移后出站能力变化
 
-```bash
-pnpm build  # 构建
-pnpm clean  # 清理构建文件
-```
+迁移到 Plugin Runtime 后，出站统一经 `messageGatewayToken` 渲染为文本后发送（`sendChannelMsg` / `sendPrivateMsg`，KMarkdown 文本）。旧 Adapter 的富媒体出站能力（图片 / 卡片消息 / 附件等多模态 segment 直发）暂未迁移，当前出站等价于纯文本（KMarkdown）。如需发送卡片或附件，可直接使用 endpoint 上的 KOOK OpenAPI 封装（`getRoleList` 等同款 client）作为逃生舱。
 
 ## 许可证
 
 MIT License
-
-## 贡献
-
-欢迎提交 Issue 和 Pull Request！
-

package/adapters/kook.ts

@@ -0,0 +1,46 @@
+/**
+ * Convention entry: discover `adapters/kook.ts` → defineAdapter.
+ * Implementation lives under `src/` (endpoint / webhook / ws / protocol).
+ */
+import { defineAdapter } from '@zhin.js/adapter';
+import { messageGatewayToken } from '@zhin.js/core/runtime';
+import { httpHostToken } from '@zhin.js/host-http';
+import {
+  KookWebhookEndpoint,
+  KookWebsocketEndpoint,
+} from '../src/endpoint.js';
+import {
+  resolveKookConfig,
+  type KookAdapterConfig,
+} from '../src/protocol.js';
+
+export {
+  KookWebhookEndpoint,
+  KookWebsocketEndpoint,
+} from '../src/endpoint.js';
+export type {
+  KookEndpointOptions,
+  KookWebhookEndpointOptions,
+} from '../src/endpoint.js';
+export type { CreateKookClient, KookClientTransport } from '../src/ws.js';
+
+export default defineAdapter<KookAdapterConfig>({
+  capabilities: ['inbound', 'outbound'],
+  create(context) {
+    const config = resolveKookConfig(context.config);
+    const gateway = context.use(messageGatewayToken);
+    if (config.connection === 'webhook') {
+      return new KookWebhookEndpoint({
+        id: context.id,
+        gateway,
+        http: context.use(httpHostToken),
+        config,
+      });
+    }
+    return new KookWebsocketEndpoint({
+      id: context.id,
+      gateway,
+      config,
+    });
+  },
+});

package/agent/tools/blacklist.ts

@@ -1,9 +1,9 @@
-import { defineTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/agent/tools';
 import { z } from 'zod';
 import { platformPermit } from '../../src/platform-permit.js';
 import { getKookAgentDeps } from '../../src/kook-agent-deps.js';
 
-export default defineTool<{ endpoint_id: string; guild_id: string; action: 'add' | 'remove'; user_id: string; remark?: string }>({
+export default defineAgentTool<{ endpoint_id: string; guild_id: string; action: 'add' | 'remove'; user_id: string; remark?: string }>({
   description: 'KOOK 服务器黑名单管理：添加/移除',
   inputSchema: z.object({
     endpoint_id: z.string().describe('Endpoint 名称'),