@zhin.js/adapter-kook 1.1.0 → 1.1.2

package/CHANGELOG.md

@@ -1,5 +1,99 @@
 # @zhin.js/adapter-kook
 
+## 1.1.2
+
+### Patch Changes
+
+- a9e4a40: Derive Command user routes only from explicit `commands/**/*/index.ts(x)` entry paths instead of prepending the plugin owner. Child plugins can now publish top-level static or dynamic commands, while duplicate routes across owners fail during generation construction. Adapter endpoint commands move to explicit paths such as `commands/qq/endpoint/list/index.ts` and are invoked as `qq endpoint list`.
+- 8740059: Standardize TypeScript capabilities on named module directories such as `commands/foo/index.ts`, `middlewares/audit/index.ts`, `handlers/message-receive/index.ts`, `pages/workroom/index.tsx`, and `mcps/filesystem/index.ts`. Only the fixed `index` entry is discovered; sibling files remain private helpers.
+
+  Command route segments come from directories, while `[name]`, `[[name]]`, `[...name]`, and `[[...name]]` directories declare dynamic parameters. Plugin owners do not enter the route unless their config explicitly sets `commandNamespace`; Endpoint `commandPrefix` remains platform-owned and defaults to an empty string.
+
+  Migrate the built-in adapters, plugins, examples, generators, migration tooling, hot reload classification, Agent authoring surfaces, documentation, and release artifacts to the explicit entry convention.
+
+  Make Tool ownership and progressive disclosure explicit across all four supported locations: plugin-public `tools/`, Agent-private `agents/<name>/tools/`, Skill-private `skills/<name>/tools/`, and Agent-Skill-private `agents/<name>/skills/<name>/tools/`. Move adapter and group-suite operations that require domain instructions into their owning Skills so `load_skill` is the only path that unlocks their schemas.
+
+  Remove the package-root `agent/` convention. Public capabilities now use named package-root directories, schedules use `schedules/<name>/index.ts` or `plugin.ts` injection, MCP connections use `mcps/<name>/index.ts`, Prompt Sections use `prompt-sections/<name>/index.ts`, Agent definitions use `agents/<name>/`, and permission vocabulary is published as `PERMITS.md`.
+
+- 25a845a: Unify Skills on `skills/<name>/SKILL.md`, support Agent-private Skills and nested Skill-private Tools, publish and mount existing plugin Skills, add governed Skill metadata and Turn access filtering, unlock only already-admitted same-owner Tools, and make `on-risk` and `once` approval behavior precise.
+- ddbb92e: Isolate adapter Skills under platform-specific Agents and automatically select the matching platform Agent for IM ingress, preventing unrelated adapter Skills from entering another platform's prompt surface.
+- 4380cf9: Colocate adapter command definitions and Agent Skill handlers with their owning capabilities, and provide a shared validated platform permission constructor.
+- 639e076: Require the canonical KOOK endpoint array and stop reading endpoint identity, credentials, webhook verification, encryption, or path values from `process.env`. Configure accounts under `plugins.kook.endpoints`, for example `[{ id: "main", token: "${KOOK_TOKEN}", connection: "websocket" }]`; each entry uses `id` as its identity and may override the plugin-level connection settings. The public config type is now `KookEndpointConfig`.
+- 5c3858e: Make `@zhin.js/im-contract` the explicit zero-dependency owner of transport identities, canonical segments, media guards, conversation facts, stores, and delivery contracts. Platform adapters now read media contracts from that foundation instead of reaching through Core.
+- 33ea736: Use `tools/<name>/index.ts` and `defineAgentTool` from `@zhin.js/tool` as the sole Agent Tool authoring model. Remove the duplicate `@zhin.js/tools` definition, context, bridge, export, and discovery path; migrate plugin manifests, examples, scaffolding, HMR, and prepack compilation to the generation-owned Tool Feature.
+- Updated dependencies [c861789]
+- Updated dependencies [1414ccb]
+- Updated dependencies [743d470]
+- Updated dependencies [62dee52]
+- Updated dependencies [cd54131]
+- Updated dependencies [244e475]
+- Updated dependencies [a9e4a40]
+- Updated dependencies [5855db7]
+- Updated dependencies [ec921d2]
+- Updated dependencies [8740059]
+- Updated dependencies [63d1f7a]
+- Updated dependencies [25a845a]
+- Updated dependencies [103f2c3]
+- Updated dependencies [9110ab8]
+- Updated dependencies [cd2a888]
+- Updated dependencies [eb3227a]
+- Updated dependencies [b853dba]
+- Updated dependencies [e561309]
+- Updated dependencies [d4c6175]
+- Updated dependencies [7a0e1ca]
+- Updated dependencies [103b5d3]
+- Updated dependencies [5a7a7f7]
+- Updated dependencies [b076eae]
+- Updated dependencies [535fed1]
+- Updated dependencies [73a24b7]
+- Updated dependencies [4380cf9]
+- Updated dependencies [2dbbc15]
+- Updated dependencies [1cb1163]
+- Updated dependencies [be3061e]
+- Updated dependencies [75f8332]
+- Updated dependencies [81935e2]
+- Updated dependencies [f9ed01b]
+- Updated dependencies [ac0ab50]
+- Updated dependencies [5140ce1]
+- Updated dependencies [522d75f]
+- Updated dependencies [a7611b3]
+- Updated dependencies [8823044]
+- Updated dependencies [379439b]
+- Updated dependencies [11c9352]
+- Updated dependencies [6b70e46]
+- Updated dependencies [135ac91]
+- Updated dependencies [140cf0f]
+- Updated dependencies [251e4d2]
+- Updated dependencies [203ad34]
+- Updated dependencies [e6c5113]
+- Updated dependencies [e0f6478]
+- Updated dependencies [baef56b]
+- Updated dependencies [698f16f]
+- Updated dependencies [da0a8e3]
+- Updated dependencies [2fd8017]
+- Updated dependencies [5c3858e]
+- Updated dependencies [33ea736]
+- Updated dependencies [507d602]
+- Updated dependencies [df9f76b]
+  - @zhin.js/core@1.1.37
+  - @zhin.js/tool@1.1.1
+  - @zhin.js/host-http@1.1.1
+  - @zhin.js/adapter@1.1.14
+  - @zhin.js/feature-kit@1.1.1
+  - @zhin.js/agent-feature@1.1.1
+  - @zhin.js/skill@1.1.1
+  - @zhin.js/logger@1.1.1
+  - @zhin.js/im-contract@1.1.1
+  - @zhin.js/permission@1.1.1
+
+## 1.1.1
+
+### Patch Changes
+
+- Updated dependencies [769e67f]
+  - @zhin.js/adapter@1.1.13
+  - @zhin.js/core@1.1.36
+
 ## 1.1.0
 
 ### Minor Changes

package/README.md

@@ -19,7 +19,7 @@ pnpm add @zhin.js/adapter-kook
 
 ## Plugin Runtime
 
-- `@zhin.js/adapter` — 约定式 `adapters/kook.ts`（`defineAdapter`）
+- `@zhin.js/adapter` — 约定式 `adapters/kook/index.ts`（`defineAdapter`）
 - `@zhin.js/core` — `Endpoint.emit(...)` 入站、`outboundMessageToken` 出站
 - `@zhin.js/host-http` — Webhook 模式 POST 路由（WebSocket 不需要）
 - `zhin.js` — `plugin.ts`（`definePlugin`）
@@ -39,7 +39,7 @@ pnpm add @zhin.js/adapter-kook
 | **Webhook** | 需公网 HTTPS + Host `httpHostToken`；与 WebSocket 互斥 |
 | **host-http** | 仅 Webhook 模式需要 |
 
-必填字段（`endpoints[i]`）：`name`、`token`。
+必填字段（`endpoints[i]`）：`id`、`token`。
 
 ## 最小配置
 
@@ -49,7 +49,7 @@ plugins:
   kook:
     # connection: websocket   # 默认
     endpoints:
-      - name: my-kook-bot
+      - id: my-kook-bot
         token: ${KOOK_TOKEN}
 ```
 
@@ -59,11 +59,9 @@ plugins:
 
 | 变量 | 说明 |
 |------|------|
-| `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` |
+| `KOOK_TOKEN` | YAML 示例中 `token` 引用的 Bot Token |
+| `KOOK_VERIFY_TOKEN` | YAML 中 `verify_token` 引用的 Webhook 验证令牌 |
+| `KOOK_ENCRYPT_KEY` | YAML 中可选 `encrypt_key` 引用的消息加密密钥 |
 
 ## Webhook
 
@@ -75,7 +73,7 @@ plugins:
     connection: webhook
     webhookPath: /kook/webhook
     endpoints:
-      - name: my-kook-bot
+      - id: my-kook-bot
         token: ${KOOK_TOKEN}
         verify_token: ${KOOK_VERIFY_TOKEN}
         # encrypt_key: ${KOOK_ENCRYPT_KEY}   # 启用消息加密时必填
@@ -87,9 +85,9 @@ Host 需注入 `httpHostToken`。Challenge（`type: 255`）会校验 `verify_tok
 
 | 类别 | 路径 |
 |------|------|
-| Permit 词汇 | `agent/PERMITS.md` |
-| 平台工具 | `agent/tools/`（角色、黑名单等） |
-| 技能说明 | `agent/skills/kook.md` |
+| Permit 词汇 | `PERMITS.md` |
+| 平台工具 | `tools/`（角色、黑名单等） |
+| 技能说明 | `agents/kook/skills/kook/SKILL.md` |
 
 ## 平台权限（platform permit）
 

package/adapters/{kook.js → kook/index.js}

@@ -1,14 +1,14 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 /**
- * Convention entry: discover `adapters/kook.ts` → defineAdapter.
+ * Convention entry: discover `adapters/kook/index.ts` → defineAdapter.
  * Implementation lives under `src/` (endpoint / webhook / ws / protocol).
  */
 import { defineAdapter } from 'zhin.js/adapter';
 import { httpHostToken } from '@zhin.js/host-http';
-import { KookWebhookEndpoint, KookWebsocketEndpoint, } from "../lib/endpoint.js";
-import { resolveKookConfig, } from "../lib/protocol.js";
-import { kookRuntimeStateToken } from "../lib/kook-runtime-state.js";
-export { KookWebhookEndpoint, KookWebsocketEndpoint, } from "../lib/endpoint.js";
+import { KookWebhookEndpoint, KookWebsocketEndpoint, } from "../../lib/endpoint.js";
+import { resolveKookConfig, } from "../../lib/protocol.js";
+import { kookRuntimeStateToken } from "../../lib/kook-runtime-state.js";
+export { KookWebhookEndpoint, KookWebsocketEndpoint, } from "../../lib/endpoint.js";
 export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
     operations: ['recall'],
@@ -21,7 +21,7 @@ export default defineAdapter({
     },
     create(context) {
         const config = resolveKookConfig(context.config);
-        // 注册到插件运行时状态（kook.endpoint list 的"运行中"数据源）
+        // 注册到插件运行时状态（kook endpoint list 的"运行中"数据源）
         context.use(kookRuntimeStateToken).endpoints.set(config.id, {
             id: config.id,
             mode: config.connection,

package/adapters/{kook.ts → kook/index.ts}

@@ -1,5 +1,5 @@
 /**
- * Convention entry: discover `adapters/kook.ts` → defineAdapter.
+ * Convention entry: discover `adapters/kook/index.ts` → defineAdapter.
  * Implementation lives under `src/` (endpoint / webhook / ws / protocol).
  */
 import { defineAdapter } from 'zhin.js/adapter';
@@ -7,24 +7,24 @@ import { httpHostToken } from '@zhin.js/host-http';
 import {
   KookWebhookEndpoint,
   KookWebsocketEndpoint,
-} from '../src/endpoint.js';
+} from '../../src/endpoint.js';
 import {
   resolveKookConfig,
-  type KookAdapterConfig,
-} from '../src/protocol.js';
-import { kookRuntimeStateToken } from '../src/kook-runtime-state.js';
+  type KookEndpointConfig,
+} from '../../src/protocol.js';
+import { kookRuntimeStateToken } from '../../src/kook-runtime-state.js';
 
 export {
   KookWebhookEndpoint,
   KookWebsocketEndpoint,
-} from '../src/endpoint.js';
+} from '../../src/endpoint.js';
 export type {
   KookEndpointOptions,
   KookWebhookEndpointOptions,
-} from '../src/endpoint.js';
-export type { CreateKookClient, KookClientTransport } from '../src/ws.js';
+} from '../../src/endpoint.js';
+export type { CreateKookClient, KookClientTransport } from '../../src/ws.js';
 
-export default defineAdapter<KookAdapterConfig>({
+export default defineAdapter<KookEndpointConfig>({
   capabilities: ['inbound', 'outbound'],
   operations: ['recall'],
   // KOOK 图片消息消费远程 URL；KMarkdown 由 endpoint codec 原生消费；
@@ -36,7 +36,7 @@ export default defineAdapter<KookAdapterConfig>({
   },
   create(context) {
     const config = resolveKookConfig(context.config);
-    // 注册到插件运行时状态（kook.endpoint list 的"运行中"数据源）
+    // 注册到插件运行时状态（kook endpoint list 的"运行中"数据源）
     context.use(kookRuntimeStateToken).endpoints.set(config.id, {
       id: config.id,
       mode: config.connection,

package/agents/kook/agent.json

@@ -0,0 +1,20 @@
+{
+  "name": "KOOK Platform Agent",
+  "version": "1.0.0",
+  "description": "Handles kook platform-specific operations and progressively loads only the required platform Skill.",
+  "trigger_rules": {
+    "file_patterns": [],
+    "keywords": [
+      "kook",
+      "adapter:kook"
+    ]
+  },
+  "entry_points": [
+    "system.md",
+    "boundaries.md",
+    "conventions.md"
+  ],
+  "platforms": [
+    "kook"
+  ]
+}

package/agents/kook/boundaries.md

@@ -0,0 +1,3 @@
+# Boundaries
+
+Operate only on the active kook endpoint and authenticated conversation context. Respect every Tool permission and approval policy. Do not infer identifiers, roles, or authorization from display names.

package/agents/kook/conventions.md

@@ -0,0 +1,3 @@
+# Conventions
+
+Use stable platform identifiers from the current turn or directory queries. Load one task-specific Skill at a time, and use the unified reply and outbound message path.

package/agents/kook/skills/kook/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: kook
+platforms: [kook]
+description: KOOK 角色和黑名单管理能力。
+keywords: [kook, role, 角色, blacklist, 黑名单]
+tags: [adapter, community]
+tools:
+  - grant_role
+  - revoke_role
+  - list_roles
+  - create_role
+  - delete_role
+  - blacklist
+---
+
+# KOOK
+
+角色操作前先用 `list_roles` 确认角色 ID，再授予、撤销、创建或删除角色。`blacklist` 是黑名单操作，影响用户重新加入服务器，执行前应确认目标用户和意图。
+
+当前 Agent Tool 不提供普通踢人、改昵称或成员列表查询，不要用黑名单代替普通踢人。

package/agents/kook/skills/kook/tools/blacklist/index.js

@@ -0,0 +1,31 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+export default defineAgentTool({
+    description: 'KOOK 服务器黑名单管理：添加/移除',
+    inputSchema: z.object({
+        guild_id: z.string().describe('服务器 ID'),
+        action: z.enum(['add', 'remove']).describe('add|remove'),
+        user_id: z.string().describe('用户 ID'),
+        remark: z.string().optional().describe('备注（add 可选）'),
+    }),
+    adapter: 'kook',
+    tags: ['kook'],
+    permissions: [platformPermission('kook', 'guild_admin')],
+    async execute({ guild_id, action, user_id, remark }, context) {
+        const member = context.$client.pickGuildMember(guild_id, user_id);
+        switch (action) {
+            case 'add': {
+                const success = await member.addToBlackList(remark);
+                return { success, message: success ? `已将 ${user_id} 加入黑名单` : '操作失败' };
+            }
+            case 'remove': {
+                const success = await member.removeFromBlackList();
+                return { success, message: success ? `已将 ${user_id} 从黑名单移除` : '操作失败' };
+            }
+            default:
+                return { success: false, message: `未知操作: ${action}` };
+        }
+    },
+});

package/{agent/tools/blacklist.ts → agents/kook/skills/kook/tools/blacklist/index.ts}

@@ -1,6 +1,6 @@
-import { defineAgentTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
-import { platformPermit } from '../../src/platform-permit.js';
+import { platformPermission } from '@zhin.js/permission';
 
 export default defineAgentTool<{ guild_id: string; action: 'add' | 'remove'; user_id: string; remark?: string }>({
   description: 'KOOK 服务器黑名单管理：添加/移除',
@@ -12,7 +12,7 @@ export default defineAgentTool<{ guild_id: string; action: 'add' | 'remove'; use
   }),
   adapter: 'kook',
   tags: ['kook'],
-  permissions: [platformPermit('guild_admin')],
+  permissions: [platformPermission('kook', 'guild_admin')],
   async execute({ guild_id, action, user_id, remark }: { guild_id: string; action: 'add' | 'remove'; user_id: string; remark?: string }, context) {
     const member = context.$client.pickGuildMember(guild_id, user_id);
     switch (action) {

package/agents/kook/skills/kook/tools/create_role/index.js

@@ -0,0 +1,23 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+export default defineAgentTool({
+    description: '在 KOOK 服务器中创建新角色',
+    inputSchema: z.object({
+        guild_id: z.string().describe('服务器 ID'),
+        name: z.string().describe('角色名称'),
+    }),
+    adapter: 'kook',
+    tags: ['kook'],
+    permissions: [platformPermission('kook', 'guild_owner')],
+    async execute({ guild_id, name }, context) {
+        const client = context.$client;
+        const role = await client.pickGuild(guild_id).createRole(name);
+        return {
+            success: true,
+            message: `已创建角色 "${name}"`,
+            role: { id: role.role_id, name: role.name },
+        };
+    },
+});

package/{agent/tools/create_role.ts → agents/kook/skills/kook/tools/create_role/index.ts}

@@ -1,6 +1,6 @@
-import { defineAgentTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
-import { platformPermit } from '../../src/platform-permit.js';
+import { platformPermission } from '@zhin.js/permission';
 
 export default defineAgentTool<{ guild_id: string; name: string }>({
   description: '在 KOOK 服务器中创建新角色',
@@ -10,7 +10,7 @@ export default defineAgentTool<{ guild_id: string; name: string }>({
   }),
   adapter: 'kook',
   tags: ['kook'],
-  permissions: [platformPermit('guild_owner')],
+  permissions: [platformPermission('kook', 'guild_owner')],
   async execute({ guild_id, name  }: { guild_id: string; name: string }, context) {
     const client = context.$client;
     const role = await client.pickGuild(guild_id).createRole(name);

package/agents/kook/skills/kook/tools/delete_role/index.js

@@ -0,0 +1,19 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+export default defineAgentTool({
+    description: '删除 KOOK 服务器中的角色',
+    inputSchema: z.object({
+        guild_id: z.string().describe('服务器 ID'),
+        role_id: z.string().describe('角色 ID'),
+    }),
+    adapter: 'kook',
+    tags: ['kook'],
+    permissions: [platformPermission('kook', 'guild_owner')],
+    async execute({ guild_id, role_id }, context) {
+        const client = context.$client;
+        const success = await client.pickGuild(guild_id).deleteRole(role_id);
+        return { success, message: success ? `已删除角色 ${role_id}` : '删除角色失败' };
+    },
+});

package/{agent/tools/delete_role.ts → agents/kook/skills/kook/tools/delete_role/index.ts}

@@ -1,6 +1,6 @@
-import { defineAgentTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
-import { platformPermit } from '../../src/platform-permit.js';
+import { platformPermission } from '@zhin.js/permission';
 
 export default defineAgentTool<{ guild_id: string; role_id: string }>({
   description: '删除 KOOK 服务器中的角色',
@@ -10,7 +10,7 @@ export default defineAgentTool<{ guild_id: string; role_id: string }>({
   }),
   adapter: 'kook',
   tags: ['kook'],
-  permissions: [platformPermit('guild_owner')],
+  permissions: [platformPermission('kook', 'guild_owner')],
   async execute({ guild_id, role_id  }: { guild_id: string; role_id: string }, context) {
     const client = context.$client;
     const success = await client.pickGuild(guild_id).deleteRole(role_id);

package/agents/kook/skills/kook/tools/grant_role/index.js

@@ -0,0 +1,20 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+export default defineAgentTool({
+    description: '给用户授予 KOOK 服务器角色',
+    inputSchema: z.object({
+        guild_id: z.string().describe('服务器 ID'),
+        user_id: z.string().describe('用户 ID'),
+        role_id: z.string().describe('角色 ID'),
+    }),
+    adapter: 'kook',
+    tags: ['kook'],
+    permissions: [platformPermission('kook', 'manage_roles')],
+    async execute({ guild_id, user_id, role_id }, context) {
+        const client = context.$client;
+        const success = await client.pickGuildMember(guild_id, user_id).grant(role_id);
+        return { success, message: success ? `已授予用户 ${user_id} 角色 ${role_id}` : '授予角色失败' };
+    },
+});

package/{agent/tools/grant_role.ts → agents/kook/skills/kook/tools/grant_role/index.ts}

@@ -1,6 +1,6 @@
-import { defineAgentTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
-import { platformPermit } from '../../src/platform-permit.js';
+import { platformPermission } from '@zhin.js/permission';
 
 export default defineAgentTool<{ guild_id: string; user_id: string; role_id: string }>({
   description: '给用户授予 KOOK 服务器角色',
@@ -11,7 +11,7 @@ export default defineAgentTool<{ guild_id: string; user_id: string; role_id: str
   }),
   adapter: 'kook',
   tags: ['kook'],
-  permissions: [platformPermit('manage_roles')],
+  permissions: [platformPermission('kook', 'manage_roles')],
   async execute({ guild_id, user_id, role_id  }: { guild_id: string; user_id: string; role_id: string }, context) {
     const client = context.$client;
     const success = await client.pickGuildMember(guild_id, user_id).grant(role_id);

package/agents/kook/skills/kook/tools/list_roles/index.js

@@ -0,0 +1,25 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+export default defineAgentTool({
+    description: '获取 KOOK 服务器的角色列表',
+    inputSchema: z.object({
+        guild_id: z.string().describe('服务器 ID'),
+    }),
+    adapter: 'kook',
+    tags: ['kook'],
+    async execute({ guild_id }, context) {
+        const client = context.$client;
+        const roles = await client.pickGuild(guild_id).getRoleList();
+        return {
+            roles: roles.map((r) => ({
+                id: String(r.role_id),
+                name: r.name,
+                color: r.color,
+                position: r.position,
+                permissions: r.permissions,
+            })),
+            count: roles.length,
+        };
+    },
+});

package/{agent/tools/list_roles.ts → agents/kook/skills/kook/tools/list_roles/index.ts}

@@ -1,4 +1,4 @@
-import { defineAgentTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 
 export default defineAgentTool<{ guild_id: string }>({

package/agents/kook/skills/kook/tools/revoke_role/index.js

@@ -0,0 +1,20 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+export default defineAgentTool({
+    description: '撤销用户的 KOOK 服务器角色',
+    inputSchema: z.object({
+        guild_id: z.string().describe('服务器 ID'),
+        user_id: z.string().describe('用户 ID'),
+        role_id: z.string().describe('角色 ID'),
+    }),
+    adapter: 'kook',
+    tags: ['kook'],
+    permissions: [platformPermission('kook', 'manage_roles')],
+    async execute({ guild_id, user_id, role_id }, context) {
+        const client = context.$client;
+        const success = await client.pickGuildMember(guild_id, user_id).revoke(role_id);
+        return { success, message: success ? `已撤销用户 ${user_id} 的角色 ${role_id}` : '撤销角色失败' };
+    },
+});

package/{agent/tools/revoke_role.ts → agents/kook/skills/kook/tools/revoke_role/index.ts}

@@ -1,6 +1,6 @@
-import { defineAgentTool } from '@zhin.js/agent/tools';
+import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
-import { platformPermit } from '../../src/platform-permit.js';
+import { platformPermission } from '@zhin.js/permission';
 
 export default defineAgentTool<{ guild_id: string; user_id: string; role_id: string }>({
   description: '撤销用户的 KOOK 服务器角色',
@@ -11,7 +11,7 @@ export default defineAgentTool<{ guild_id: string; user_id: string; role_id: str
   }),
   adapter: 'kook',
   tags: ['kook'],
-  permissions: [platformPermit('manage_roles')],
+  permissions: [platformPermission('kook', 'manage_roles')],
   async execute({ guild_id, user_id, role_id  }: { guild_id: string; user_id: string; role_id: string }, context) {
     const client = context.$client;
     const success = await client.pickGuildMember(guild_id, user_id).revoke(role_id);

package/agents/kook/system.md

@@ -0,0 +1,3 @@
+# KOOK Platform Agent
+
+You are the kook platform specialist. Interpret requests in the current kook conversation and load only the narrowest private Skill needed for the task.

package/commands/{endpoint/add/[id].js → kook/endpoint/add/[id]/index.js}

@@ -1,3 +1,3 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
-import { kookEndpointCommands } from "../../../lib/kook-endpoint-commands.js";
+import { kookEndpointCommands } from '../../definition.js';
 export default kookEndpointCommands.add;

package/commands/kook/endpoint/add/[id]/index.ts

@@ -0,0 +1,3 @@
+import { kookEndpointCommands } from '../../definition.js';
+
+export default kookEndpointCommands.add;

package/{lib/kook-endpoint-commands.js → commands/kook/endpoint/definition.js}

@@ -1,10 +1,11 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
 /**
- * `kook.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
- * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ * `kook endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/kook/endpoint/ 下的 list / add / remove 直接默认导出这三项。
  */
 import { createEndpointCommands } from 'zhin.js/adapter';
 import { defineCommand } from 'zhin.js/command';
-import { kookRuntimeStateToken } from './kook-runtime-state.js';
+import { kookRuntimeStateToken } from "../../../lib/kook-runtime-state.js";
 export const kookEndpointCommands = createEndpointCommands({
     adapterKey: 'kook',
     adapterDisplayName: 'KOOK',

package/{src/kook-endpoint-commands.ts → commands/kook/endpoint/definition.ts}

@@ -1,10 +1,10 @@
 /**
- * `kook.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
- * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
+ * `kook endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * commands/kook/endpoint/ 下的 list / add / remove 直接默认导出这三项。
  */
 import { createEndpointCommands } from 'zhin.js/adapter';
 import { defineCommand } from 'zhin.js/command';
-import { kookRuntimeStateToken } from './kook-runtime-state.js';
+import { kookRuntimeStateToken } from '../../../src/kook-runtime-state.js';
 
 export const kookEndpointCommands = createEndpointCommands({
   adapterKey: 'kook',

package/commands/{endpoint/list.js → kook/endpoint/list/index.js}

@@ -1,3 +1,3 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
-import { kookEndpointCommands } from "../../lib/kook-endpoint-commands.js";
+import { kookEndpointCommands } from '../definition.js';
 export default kookEndpointCommands.list;

package/commands/kook/endpoint/list/index.ts

@@ -0,0 +1,3 @@
+import { kookEndpointCommands } from '../definition.js';
+
+export default kookEndpointCommands.list;

package/commands/{endpoint/remove/[id].js → kook/endpoint/remove/[id]/index.js}

@@ -1,3 +1,3 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
-import { kookEndpointCommands } from "../../../lib/kook-endpoint-commands.js";
+import { kookEndpointCommands } from '../../definition.js';
 export default kookEndpointCommands.remove;

package/commands/kook/endpoint/remove/[id]/index.ts

@@ -0,0 +1,3 @@
+import { kookEndpointCommands } from '../../definition.js';
+
+export default kookEndpointCommands.remove;

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-export { formatInboundContent, formatOutboundKmarkdown, resolveKookConfig, senderDisplayName, KookPermission, type KookAdapterConfig, type KookInboundMessage, type KookWireSegment, type LogLevel, type ResolvedKookConfig, type ResolvedKookWebhookConfig, type ResolvedKookWebsocketConfig, } from './protocol.js';
+export { formatInboundContent, formatOutboundKmarkdown, resolveKookConfig, senderDisplayName, KookPermission, type KookEndpointConfig, type KookInboundMessage, type KookWireSegment, type LogLevel, type ResolvedKookConfig, type ResolvedKookWebhookConfig, type ResolvedKookWebsocketConfig, } from './protocol.js';
 export { KookWebhookEndpoint, KookWebsocketEndpoint, type KookEndpointOptions, type KookWebhookEndpointOptions, } from './endpoint.js';
 export { registerKookWebhookRoutes, handleKookWebhookRequest, type KookWebhookHandler, } from './webhook.js';
 export { defaultCreateClient, defaultCreateWebhookClient, normalizeKookMessage, type CreateKookClient, type KookClientTransport, } from './ws.js';

package/lib/kook-runtime-state.js

@@ -1,6 +1,6 @@
 /**
  * KOOK 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
- * 由 plugin.ts setup() provide，adapter create 与 `kook.endpoint` 命令共享（同一 owner generation）。
+ * 由 plugin.ts setup() provide，adapter create 与 `kook endpoint` 命令共享（同一 owner generation）。
  */
 import { defineEndpointRuntimeStateToken } from 'zhin.js/adapter';
 export const kookRuntimeStateToken = defineEndpointRuntimeStateToken('kook');

package/lib/protocol.d.ts

@@ -1,9 +1,6 @@
-/**
- * KOOK protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
- * Canonicalization is owned by gateway/core before endpoint.send.
- */
+/** KOOK protocol helpers. Canonicalization is owned by Core. */
 import type { IncomingMessage } from 'node:http';
-import type { ConversationRef } from '@zhin.js/im-contract';
+import { type ConversationRef } from '@zhin.js/im-contract';
 export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal' | 'mark' | 'off';
 export declare enum KookPermission {
     Normal = 1,
@@ -11,10 +8,10 @@ export declare enum KookPermission {
     Owner = 4,
     ChannelAdmin = 5
 }
-/** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
-export interface KookAdapterConfig {
-    readonly id?: string;
-    readonly token?: string;
+/** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
+export interface KookEndpointConfig {
+    readonly id: string;
+    readonly token: string;
     /** Default `websocket`. `webhook` requires httpHostToken + verify_token. */
     readonly connection?: 'websocket' | 'webhook';
     readonly webhookPath?: string;
@@ -25,21 +22,6 @@ export interface KookAdapterConfig {
     readonly max_retry?: number;
     readonly ignore?: 'bot' | 'self';
     readonly logLevel?: LogLevel;
-    /** Transitional: legacy root `endpoints[]` with `context: kook`. */
-    readonly endpoints?: ReadonlyArray<{
-        readonly context?: string;
-        readonly id?: string;
-        readonly token?: string;
-        readonly connection?: 'websocket' | 'webhook';
-        readonly webhookPath?: string;
-        readonly verify_token?: string;
-        readonly encrypt_key?: string;
-        readonly data_dir?: string;
-        readonly timeout?: number;
-        readonly max_retry?: number;
-        readonly ignore?: 'bot' | 'self';
-        readonly logLevel?: LogLevel;
-    }>;
 }
 export interface ResolvedKookWebsocketConfig {
     readonly context: 'kook';
@@ -107,7 +89,7 @@ export interface KookWireSegment {
     readonly type: string;
     readonly data?: Record<string, unknown>;
 }
-export declare function resolveKookConfig(config?: KookAdapterConfig): ResolvedKookConfig;
+export declare function resolveKookConfig(config: KookEndpointConfig): ResolvedKookConfig;
 /**
  * 入站归一化 → ConversationRef：频道消息的所属 guild 进 `parent`（guild 容器
  * 映射为 channel 容器）；私聊（PERSON）无容器，直接 kind 'private'。

package/lib/protocol.js

@@ -1,11 +1,7 @@
-/**
- * KOOK protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
- * Canonicalization is owned by gateway/core before endpoint.send.
- */
+/** KOOK protocol helpers. Canonicalization is owned by Core. */
 import { createDecipheriv, timingSafeEqual } from 'node:crypto';
 import { inflateSync } from 'node:zlib';
-import { pickCredential } from 'zhin.js/adapter';
-import { isMediaRef } from '@zhin.js/core';
+import { isMediaRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 const logger = getLogger('kook');
 export var KookPermission;
@@ -15,38 +11,23 @@ export var KookPermission;
     KookPermission[KookPermission["Owner"] = 4] = "Owner";
     KookPermission[KookPermission["ChannelAdmin"] = 5] = "ChannelAdmin";
 })(KookPermission || (KookPermission = {}));
-export function resolveKookConfig(config = {}) {
-    const entry = config.endpoints?.find((item) => item.context === 'kook' || !item.context);
-    const token = pickCredential(config.token, entry?.token, process.env.KOOK_TOKEN, process.env.KOOK_BOT_TOKEN);
-    if (!token) {
-        throw new TypeError('KOOK adapter requires token (plugins.<key>.token or endpoints with context: kook)');
-    }
-    const id = (typeof config.id === 'string' && config.id)
-        || (typeof entry?.id === 'string' && entry.id)
-        || process.env.KOOK_BOT_NAME
-        || 'kook-bot';
-    const connection = config.connection
-        ?? entry?.connection
-        ?? 'websocket';
+export function resolveKookConfig(config) {
+    const id = requiredEndpointField(config.id, 'id');
+    const token = requiredEndpointField(config.token, 'token');
+    const connection = config.connection ?? 'websocket';
     if (connection === 'webhook') {
-        const verifyToken = (typeof config.verify_token === 'string' && config.verify_token)
-            || (typeof entry?.verify_token === 'string' && entry.verify_token)
-            || process.env.KOOK_VERIFY_TOKEN
-            || '';
-        if (!verifyToken) {
-            throw new TypeError('KOOK webhook mode requires verify_token (plugins.<key>.verify_token or KOOK_VERIFY_TOKEN)');
-        }
-        const encryptKey = config.encrypt_key ?? entry?.encrypt_key ?? process.env.KOOK_ENCRYPT_KEY;
+        const verifyToken = requiredEndpointField(config.verify_token, 'verify_token');
+        const encryptKey = config.encrypt_key;
         return {
             context: 'kook',
             connection: 'webhook',
             id,
             token,
-            webhookPath: normalizeWebhookPath(config.webhookPath ?? entry?.webhookPath ?? process.env.KOOK_WEBHOOK_PATH ?? '/kook/webhook'),
+            webhookPath: normalizeWebhookPath(config.webhookPath ?? '/kook/webhook'),
             verifyToken,
             encryptKey: typeof encryptKey === 'string' && encryptKey ? encryptKey : undefined,
-            ignore: config.ignore ?? entry?.ignore ?? 'bot',
-            logLevel: config.logLevel ?? entry?.logLevel ?? 'info',
+            ignore: config.ignore ?? 'bot',
+            logLevel: config.logLevel ?? 'info',
         };
     }
     return {
@@ -54,13 +35,19 @@ export function resolveKookConfig(config = {}) {
         connection: 'websocket',
         id,
         token,
-        data_dir: config.data_dir ?? entry?.data_dir,
-        timeout: config.timeout ?? entry?.timeout ?? 10_000,
-        max_retry: config.max_retry ?? entry?.max_retry ?? 3,
-        ignore: config.ignore ?? entry?.ignore ?? 'bot',
-        logLevel: config.logLevel ?? entry?.logLevel ?? 'info',
+        data_dir: config.data_dir,
+        timeout: config.timeout ?? 10_000,
+        max_retry: config.max_retry ?? 3,
+        ignore: config.ignore ?? 'bot',
+        logLevel: config.logLevel ?? 'info',
     };
 }
+function requiredEndpointField(value, field) {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new TypeError(`KOOK endpoint requires a non-empty ${field}`);
+    }
+    return value.trim();
+}
 /**
  * 入站归一化 → ConversationRef：频道消息的所属 guild 进 `parent`（guild 容器
  * 映射为 channel 容器）；私聊（PERSON）无容器，直接 kind 'private'。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-kook",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Zhin.js KOOK adapter for Plugin Runtime (WebSocket gateway or Webhook)",
   "type": "module",
   "main": "./lib/index.js",
@@ -34,26 +34,25 @@
   },
   "dependencies": {
     "kook-client": "^1.0.4",
-    "@zhin.js/adapter": "1.1.12",
-    "@zhin.js/core": "1.1.35",
-    "@zhin.js/feature-kit": "1.1.0",
-    "@zhin.js/host-http": "1.1.0",
-    "@zhin.js/im-contract": "1.1.0",
-    "@zhin.js/logger": "1.1.0",
-    "@zhin.js/permission": "1.1.0"
+    "@zhin.js/adapter": "1.1.14",
+    "@zhin.js/agent-feature": "1.1.1",
+    "@zhin.js/core": "1.1.37",
+    "@zhin.js/feature-kit": "1.1.1",
+    "@zhin.js/host-http": "1.1.1",
+    "@zhin.js/im-contract": "1.1.1",
+    "@zhin.js/logger": "1.1.1",
+    "@zhin.js/permission": "1.1.1",
+    "@zhin.js/skill": "1.1.1",
+    "@zhin.js/tool": "1.1.1"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.12",
-    "@zhin.js/agent": "^1.1.23",
-    "@zhin.js/command": "^1.1.0",
-    "@zhin.js/core": "^1.1.35",
-    "zhin.js": "^1.1.0"
+    "@zhin.js/adapter": "^1.1.14",
+    "@zhin.js/command": "^1.1.1",
+    "@zhin.js/core": "^1.1.37",
+    "zhin.js": "^1.1.2"
   },
   "peerDependenciesMeta": {
-    "@zhin.js/agent": {
-      "optional": true
-    },
     "@zhin.js/command": {
       "optional": true
     },
@@ -69,9 +68,8 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.1.23",
-    "@zhin.js/host-http": "1.1.0",
-    "zhin.js": "1.1.0"
+    "@zhin.js/host-http": "1.1.1",
+    "zhin.js": "1.1.2"
   },
   "files": [
     "adapters",
@@ -80,9 +78,11 @@
     "schema.json",
     "src",
     "lib",
-    "agent",
+    "tools",
+    "agents",
     "README.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "PERMITS.md"
   ],
   "publishConfig": {
     "access": "public",
@@ -105,6 +105,18 @@
       {
         "package": "@zhin.js/command",
         "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/tool",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/skill",
+        "api": "^1.0.0"
+      },
+      {
+        "package": "@zhin.js/agent-feature",
+        "api": "^1.0.0"
       }
     ],
     "plugins": []

package/schema.json

@@ -70,10 +70,11 @@
     },
     "endpoints": {
       "type": "array",
-      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（id 必填，其余覆盖顶层）",
+      "minItems": 1,
+      "description": "多账号：每项定义一个 endpoint，id/token 必填，其余字段覆盖实例默认值",
       "items": {
         "type": "object",
-        "additionalProperties": true,
+        "additionalProperties": false,
         "properties": {
           "master": {
             "type": [
@@ -97,6 +98,16 @@
             "type": "string",
             "description": "KOOK bot token"
           },
+          "connection": {
+            "type": "string",
+            "enum": [
+              "websocket",
+              "webhook"
+            ]
+          },
+          "webhookPath": {
+            "type": "string"
+          },
           "verify_token": {
             "type": "string",
             "description": "KOOK developer console verify token (required for webhook mode)."
@@ -105,6 +116,38 @@
             "type": "string",
             "description": "Optional Encrypt Key when message encryption is enabled in KOOK console."
           },
+          "data_dir": {
+            "type": "string"
+          },
+          "timeout": {
+            "type": "number"
+          },
+          "max_retry": {
+            "type": "number"
+          },
+          "ignore": {
+            "type": "string",
+            "enum": [
+              "bot",
+              "self"
+            ]
+          },
+          "logLevel": {
+            "type": "string",
+            "enum": [
+              "trace",
+              "debug",
+              "info",
+              "warn",
+              "error",
+              "fatal",
+              "mark",
+              "off"
+            ]
+          },
+          "commandPrefix": {
+            "type": "string"
+          },
           "id": {
             "type": "string",
             "description": "KOOK bot name"

package/src/index.ts

@@ -4,7 +4,7 @@ export {
   resolveKookConfig,
   senderDisplayName,
   KookPermission,
-  type KookAdapterConfig,
+  type KookEndpointConfig,
   type KookInboundMessage,
   type KookWireSegment,
   type LogLevel,

package/src/kook-runtime-state.ts

@@ -1,6 +1,6 @@
 /**
  * KOOK 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
- * 由 plugin.ts setup() provide，adapter create 与 `kook.endpoint` 命令共享（同一 owner generation）。
+ * 由 plugin.ts setup() provide，adapter create 与 `kook endpoint` 命令共享（同一 owner generation）。
  */
 import { defineEndpointRuntimeStateToken } from 'zhin.js/adapter';
 

package/src/protocol.ts

@@ -1,14 +1,9 @@
-/**
- * KOOK protocol helpers — no legacy Adapter/Endpoint / segment-mapper.
- * Canonicalization is owned by gateway/core before endpoint.send.
- */
+/** KOOK protocol helpers. Canonicalization is owned by Core. */
 
 import { createDecipheriv, timingSafeEqual } from 'node:crypto';
 import { inflateSync } from 'node:zlib';
 import type { IncomingMessage } from 'node:http';
-import { pickCredential } from 'zhin.js/adapter';
-import { isMediaRef } from '@zhin.js/core';
-import type { ConversationRef } from '@zhin.js/im-contract';
+import { isMediaRef, type ConversationRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 
 const logger = getLogger('kook');
@@ -30,10 +25,10 @@ export enum KookPermission {
   ChannelAdmin = 5,
 }
 
-/** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
-export interface KookAdapterConfig {
-  readonly id?: string;
-  readonly token?: string;
+/** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
+export interface KookEndpointConfig {
+  readonly id: string;
+  readonly token: string;
   /** Default `websocket`. `webhook` requires httpHostToken + verify_token. */
   readonly connection?: 'websocket' | 'webhook';
   readonly webhookPath?: string;
@@ -44,21 +39,6 @@ export interface KookAdapterConfig {
   readonly max_retry?: number;
   readonly ignore?: 'bot' | 'self';
   readonly logLevel?: LogLevel;
-  /** Transitional: legacy root `endpoints[]` with `context: kook`. */
-  readonly endpoints?: ReadonlyArray<{
-    readonly context?: string;
-    readonly id?: string;
-    readonly token?: string;
-    readonly connection?: 'websocket' | 'webhook';
-    readonly webhookPath?: string;
-    readonly verify_token?: string;
-    readonly encrypt_key?: string;
-    readonly data_dir?: string;
-    readonly timeout?: number;
-    readonly max_retry?: number;
-    readonly ignore?: 'bot' | 'self';
-    readonly logLevel?: LogLevel;
-  }>;
 }
 
 export interface ResolvedKookWebsocketConfig {
@@ -134,45 +114,26 @@ export interface KookWireSegment {
   readonly data?: Record<string, unknown>;
 }
 
-export function resolveKookConfig(config: KookAdapterConfig = {}): ResolvedKookConfig {
-  const entry = config.endpoints?.find((item) => item.context === 'kook' || !item.context);
-  const token = pickCredential(config.token, entry?.token, process.env.KOOK_TOKEN, process.env.KOOK_BOT_TOKEN);
-  if (!token) {
-    throw new TypeError(
-      'KOOK adapter requires token (plugins.<key>.token or endpoints with context: kook)',
-    );
-  }
-  const id = (typeof config.id === 'string' && config.id)
-    || (typeof entry?.id === 'string' && entry.id)
-    || process.env.KOOK_BOT_NAME
-    || 'kook-bot';
-  const connection = config.connection
-    ?? entry?.connection
-    ?? 'websocket';
+export function resolveKookConfig(config: KookEndpointConfig): ResolvedKookConfig {
+  const id = requiredEndpointField(config.id, 'id');
+  const token = requiredEndpointField(config.token, 'token');
+  const connection = config.connection ?? 'websocket';
 
   if (connection === 'webhook') {
-    const verifyToken = (typeof config.verify_token === 'string' && config.verify_token)
-      || (typeof entry?.verify_token === 'string' && entry.verify_token)
-      || process.env.KOOK_VERIFY_TOKEN
-      || '';
-    if (!verifyToken) {
-      throw new TypeError(
-        'KOOK webhook mode requires verify_token (plugins.<key>.verify_token or KOOK_VERIFY_TOKEN)',
-      );
-    }
-    const encryptKey = config.encrypt_key ?? entry?.encrypt_key ?? process.env.KOOK_ENCRYPT_KEY;
+    const verifyToken = requiredEndpointField(config.verify_token, 'verify_token');
+    const encryptKey = config.encrypt_key;
     return {
       context: 'kook',
       connection: 'webhook',
       id,
       token,
       webhookPath: normalizeWebhookPath(
-        config.webhookPath ?? entry?.webhookPath ?? process.env.KOOK_WEBHOOK_PATH ?? '/kook/webhook',
+        config.webhookPath ?? '/kook/webhook',
       ),
       verifyToken,
       encryptKey: typeof encryptKey === 'string' && encryptKey ? encryptKey : undefined,
-      ignore: config.ignore ?? entry?.ignore ?? 'bot',
-      logLevel: config.logLevel ?? entry?.logLevel ?? 'info',
+      ignore: config.ignore ?? 'bot',
+      logLevel: config.logLevel ?? 'info',
     };
   }
 
@@ -181,14 +142,24 @@ export function resolveKookConfig(config: KookAdapterConfig = {}): ResolvedKookC
     connection: 'websocket',
     id,
     token,
-    data_dir: config.data_dir ?? entry?.data_dir,
-    timeout: config.timeout ?? entry?.timeout ?? 10_000,
-    max_retry: config.max_retry ?? entry?.max_retry ?? 3,
-    ignore: config.ignore ?? entry?.ignore ?? 'bot',
-    logLevel: config.logLevel ?? entry?.logLevel ?? 'info',
+    data_dir: config.data_dir,
+    timeout: config.timeout ?? 10_000,
+    max_retry: config.max_retry ?? 3,
+    ignore: config.ignore ?? 'bot',
+    logLevel: config.logLevel ?? 'info',
   };
 }
 
+function requiredEndpointField(
+  value: unknown,
+  field: 'id' | 'token' | 'verify_token',
+): string {
+  if (typeof value !== 'string' || !value.trim()) {
+    throw new TypeError(`KOOK endpoint requires a non-empty ${field}`);
+  }
+  return value.trim();
+}
+
 /**
  * 入站归一化 → ConversationRef：频道消息的所属 guild 进 `parent`（guild 容器
  * 映射为 channel 容器）；私聊（PERSON）无容器，直接 kind 'private'。

package/agent/skills/kook.md

@@ -1,80 +0,0 @@
----
-name: kook
-platforms:
-  - kook
-description: >-
-  KOOK 服务器管理能力。当用户在 KOOK 中请求群管（踢人、封禁、解封、改昵称）、
-  角色管理（创建/删除/授予/撤销角色）、黑名单操作或查询成员列表时使用。
-  即使用户没有提到 KOOK，只要上下文是 KOOK 场景且涉及上述操作，就应触发。
-  仅有昵称时必须先 list_members 获取 user_id。
-keywords:
-  - kook
-  - KOOK
-  - adapter:kook
-  - 群管理
-  - 角色
-  - 黑名单
-  - 封禁
-  - list_members
-tags:
-  - group
-  - management
-  - im
-tools:
-  - kook_grant_role
-  - kook_revoke_role
-  - kook_list_roles
-  - kook_create_role
-  - kook_delete_role
-  - kook_blacklist
-  - kook_kick_member
-  - kook_ban_member
-  - kook_unban_member
-  - kook_set_nickname
-  - kook_list_members
----
-
-# KOOK 服务器管理技能
-
-KOOK 的管理模型类似 Discord，以角色为核心。此技能覆盖成员管理和角色系统。
-
-## 核心原则
-
-### ID 获取链
-
-操作成员需要 KOOK 用户 ID，操作角色需要角色 ID：
-- `kook_list_members` → 获取用户 ID
-- `kook_list_roles` → 获取角色 ID
-
-### 黑名单 ≠ 踢人
-
-`kook_blacklist` 是永久性封禁，被拉黑的用户无法再加入服务器。`kook_kick_member` 只是移除，用户可以通过邀请重新加入。
-
-## 工具详解
-
-### 成员管理
-
-| 工具 | 用途 | 说明 |
-|------|------|------|
-| `kook_kick_member` | 踢出 | 可重新加入 |
-| `kook_ban_member` | 封禁 | 阻止重新加入 |
-| `kook_unban_member` | 解除封禁 | — |
-| `kook_set_nickname` | 改昵称 | 服务器内昵称 |
-| `kook_list_members` | 成员列表 | — |
-| `kook_blacklist` | 黑名单操作 | **不可逆，谨慎使用** |
-
-### 角色管理
-
-| 工具 | 用途 | 说明 |
-|------|------|------|
-| `kook_create_role` | 创建角色 | — |
-| `kook_delete_role` | 删除角色 | — |
-| `kook_grant_role` | 授予角色 | 需 user_id + role_id |
-| `kook_revoke_role` | 撤销角色 | 需 user_id + role_id |
-| `kook_list_roles` | 角色列表 | 获取所有角色及 ID |
-
-## 易错点
-
-1. **黑名单是永久封禁**，与普通踢人（kick）不同。用户说「把他踢了」用 kick，说「永久拉黑」才用 blacklist。
-2. **角色操作需要 role_id**，先 `kook_list_roles` 查询。
-3. **创建角色后还需要 grant_role 才能给成员分配**，创建 ≠ 分配。

package/commands/endpoint/add/[id].ts

@@ -1,3 +0,0 @@
-import { kookEndpointCommands } from '../../../src/kook-endpoint-commands.js';
-
-export default kookEndpointCommands.add;

package/commands/endpoint/list.ts

@@ -1,3 +0,0 @@
-import { kookEndpointCommands } from '../../src/kook-endpoint-commands.js';
-
-export default kookEndpointCommands.list;

package/commands/endpoint/remove/[id].ts

@@ -1,3 +0,0 @@
-import { kookEndpointCommands } from '../../../src/kook-endpoint-commands.js';
-
-export default kookEndpointCommands.remove;

package/lib/kook-endpoint-commands.d.ts

@@ -1 +0,0 @@
-export declare const kookEndpointCommands: import("@zhin.js/adapter").EndpointCommands<Readonly<import("@zhin.js/command").CommandDefinition<unknown, unknown, import("@zhin.js/command").CommandMessage, string | undefined>>>;