@zhin.js/adapter-kook 1.1.25 → 1.1.27

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

@@ -1,21 +1,20 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { messages as t } from "../../../../messages.js";
+import { currentGuild } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
-import { platformPermission } from '@zhin.js/permission';
 export default defineAgentTool({
-    description: '在 KOOK 服务器中创建新角色',
+    description: '在当前 KOOK 服务器中创建新角色',
     inputSchema: z.object({
-        guild_id: z.string().describe('服务器 ID'),
         name: z.string().describe('角色名称'),
     }),
     adapter: 'kook',
     scopes: ["channel"],
     tags: ['kook'],
-    permissions: [platformPermission('kook', 'guild_owner')],
-    async execute({ guild_id, name }, context) {
+    permissions: ['platform:owner', 'bot-permission:manage_roles'],
+    async execute({ name }, context) {
         const client = context.$client;
-        const role = await client.pickGuild(guild_id).createRole(name);
+        const role = await client.pickGuild(currentGuild(context)).createRole(name);
         return {
             success: true,
             message: t(context.locale, 'roleCreated', { p0: name }),

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

@@ -1,21 +1,20 @@
 import { messages as t } from "../../../../messages.js";
+import { currentGuild } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
-import { platformPermission } from '@zhin.js/permission';
 
-export default defineAgentTool<{ guild_id: string; name: string }>({
-  description: '在 KOOK 服务器中创建新角色',
+export default defineAgentTool<{ name: string }>({
+  description: '在当前 KOOK 服务器中创建新角色',
   inputSchema: z.object({
-    guild_id: z.string().describe('服务器 ID'),
     name: z.string().describe('角色名称'),
   }),
   adapter: 'kook',
   scopes: ["channel"],
   tags: ['kook'],
-  permissions: [platformPermission('kook', 'guild_owner')],
-  async execute({ guild_id, name  }: { guild_id: string; name: string }, context) {
+  permissions: ['platform:owner', 'bot-permission:manage_roles'],
+  async execute({ name }, context) {
     const client = context.$client;
-    const role = await client.pickGuild(guild_id).createRole(name);
+    const role = await client.pickGuild(currentGuild(context)).createRole(name);
     return {
       success: true,
       message: t(context.locale, 'roleCreated', { p0: name }),

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

@@ -1,21 +1,20 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { messages as t } from "../../../../messages.js";
+import { currentGuild } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
-import { platformPermission } from '@zhin.js/permission';
 export default defineAgentTool({
-    description: '删除 KOOK 服务器中的角色',
+    description: '删除当前 KOOK 服务器中的角色',
     inputSchema: z.object({
-        guild_id: z.string().describe('服务器 ID'),
         role_id: z.string().describe('角色 ID'),
     }),
     adapter: 'kook',
     scopes: ["channel"],
     tags: ['kook'],
-    permissions: [platformPermission('kook', 'guild_owner')],
-    async execute({ guild_id, role_id }, context) {
+    permissions: ['platform:owner', 'bot-permission:manage_roles'],
+    async execute({ role_id }, context) {
         const client = context.$client;
-        const success = await client.pickGuild(guild_id).deleteRole(role_id);
+        const success = await client.pickGuild(currentGuild(context)).deleteRole(role_id);
         return { success, message: success ? t(context.locale, 'roleDeleted', { p0: role_id }) : t(context.locale, 'roleDeleteFailed') };
     },
 });

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

@@ -1,21 +1,20 @@
 import { messages as t } from "../../../../messages.js";
+import { currentGuild } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
-import { platformPermission } from '@zhin.js/permission';
 
-export default defineAgentTool<{ guild_id: string; role_id: string }>({
-  description: '删除 KOOK 服务器中的角色',
+export default defineAgentTool<{ role_id: string }>({
+  description: '删除当前 KOOK 服务器中的角色',
   inputSchema: z.object({
-    guild_id: z.string().describe('服务器 ID'),
     role_id: z.string().describe('角色 ID'),
   }),
   adapter: 'kook',
   scopes: ["channel"],
   tags: ['kook'],
-  permissions: [platformPermission('kook', 'guild_owner')],
-  async execute({ guild_id, role_id  }: { guild_id: string; role_id: string }, context) {
+  permissions: ['platform:owner', 'bot-permission:manage_roles'],
+  async execute({ role_id }, context) {
     const client = context.$client;
-    const success = await client.pickGuild(guild_id).deleteRole(role_id);
+    const success = await client.pickGuild(currentGuild(context)).deleteRole(role_id);
     return { success, message: success ? t(context.locale, 'roleDeleted', { p0: role_id }) : t(context.locale, 'roleDeleteFailed') };
   },
 });

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

@@ -1,22 +1,24 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { messages as t } from "../../../../messages.js";
+import { currentGuild, requireRoleBelowRequester } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
-import { platformPermission } from '@zhin.js/permission';
 export default defineAgentTool({
-    description: '给用户授予 KOOK 服务器角色',
+    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',
     scopes: ["channel"],
     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);
+    permissions: ['platform-permission:manage_roles', 'bot-permission:manage_roles'],
+    async execute({ user_id, role_id }, context) {
+        const guildId = currentGuild(context);
+        const denied = await requireRoleBelowRequester(context, guildId, role_id);
+        if (denied)
+            return { success: false, message: denied };
+        const success = await context.$client.pickGuildMember(guildId, user_id).grant(role_id);
         return { success, message: success ? t(context.locale, 'roleGranted', { p0: user_id, p1: role_id }) : t(context.locale, 'roleGrantFailed') };
     },
 });

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

@@ -1,22 +1,23 @@
 import { messages as t } from "../../../../messages.js";
+import { currentGuild, requireRoleBelowRequester } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
-import { platformPermission } from '@zhin.js/permission';
 
-export default defineAgentTool<{ guild_id: string; user_id: string; role_id: string }>({
-  description: '给用户授予 KOOK 服务器角色',
+export default defineAgentTool<{ user_id: string; role_id: string }>({
+  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',
   scopes: ["channel"],
   tags: ['kook'],
-  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);
+  permissions: ['platform-permission:manage_roles', 'bot-permission:manage_roles'],
+  async execute({ user_id, role_id }, context) {
+    const guildId = currentGuild(context);
+    const denied = await requireRoleBelowRequester(context, guildId, role_id);
+    if (denied) return { success: false, message: denied };
+    const success = await context.$client.pickGuildMember(guildId, user_id).grant(role_id);
     return { success, message: success ? t(context.locale, 'roleGranted', { p0: user_id, p1: role_id }) : t(context.locale, 'roleGrantFailed') };
   },
 });

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

@@ -1,17 +1,15 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { currentGuild } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 export default defineAgentTool({
-    description: '获取 KOOK 服务器的角色列表',
-    inputSchema: z.object({
-        guild_id: z.string().describe('服务器 ID'),
-    }),
+    description: '获取当前 KOOK 服务器的角色列表（position 越小优先级越高）',
+    inputSchema: z.object({}),
     adapter: 'kook',
     scopes: ["channel"],
     tags: ['kook'],
-    async execute({ guild_id }, context) {
-        const client = context.$client;
-        const roles = await client.pickGuild(guild_id).getRoleList();
+    async execute(_args, context) {
+        const roles = await context.$client.pickGuild(currentGuild(context)).getRoleList();
         return {
             roles: roles.map((r) => ({
                 id: String(r.role_id),

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

@@ -1,17 +1,15 @@
+import { currentGuild } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 
-export default defineAgentTool<{ guild_id: string }>({
-  description: '获取 KOOK 服务器的角色列表',
-  inputSchema: z.object({
-    guild_id: z.string().describe('服务器 ID'),
-  }),
+export default defineAgentTool<Record<string, never>>({
+  description: '获取当前 KOOK 服务器的角色列表（position 越小优先级越高）',
+  inputSchema: z.object({}),
   adapter: 'kook',
   scopes: ["channel"],
   tags: ['kook'],
-  async execute({ guild_id  }: { guild_id: string }, context) {
-    const client = context.$client;
-    const roles = await client.pickGuild(guild_id).getRoleList();
+  async execute(_args, context) {
+    const roles = await context.$client.pickGuild(currentGuild(context)).getRoleList();
     return {
       roles: roles.map((r) => ({
         id: String(r.role_id),

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

@@ -1,22 +1,24 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
 import { messages as t } from "../../../../messages.js";
+import { currentGuild, requireRoleBelowRequester } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
-import { platformPermission } from '@zhin.js/permission';
 export default defineAgentTool({
-    description: '撤销用户的 KOOK 服务器角色',
+    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',
     scopes: ["channel"],
     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);
+    permissions: ['platform-permission:manage_roles', 'bot-permission:manage_roles'],
+    async execute({ user_id, role_id }, context) {
+        const guildId = currentGuild(context);
+        const denied = await requireRoleBelowRequester(context, guildId, role_id);
+        if (denied)
+            return { success: false, message: denied };
+        const success = await context.$client.pickGuildMember(guildId, user_id).revoke(role_id);
         return { success, message: success ? t(context.locale, 'roleRevoked', { p0: user_id, p1: role_id }) : t(context.locale, 'roleRevokeFailed') };
     },
 });

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

@@ -1,22 +1,23 @@
 import { messages as t } from "../../../../messages.js";
+import { currentGuild, requireRoleBelowRequester } from "../../../../conversation.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
-import { platformPermission } from '@zhin.js/permission';
 
-export default defineAgentTool<{ guild_id: string; user_id: string; role_id: string }>({
-  description: '撤销用户的 KOOK 服务器角色',
+export default defineAgentTool<{ user_id: string; role_id: string }>({
+  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',
   scopes: ["channel"],
   tags: ['kook'],
-  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);
+  permissions: ['platform-permission:manage_roles', 'bot-permission:manage_roles'],
+  async execute({ user_id, role_id }, context) {
+    const guildId = currentGuild(context);
+    const denied = await requireRoleBelowRequester(context, guildId, role_id);
+    if (denied) return { success: false, message: denied };
+    const success = await context.$client.pickGuildMember(guildId, user_id).revoke(role_id);
     return { success, message: success ? t(context.locale, 'roleRevoked', { p0: user_id, p1: role_id }) : t(context.locale, 'roleRevokeFailed') };
   },
 });

package/lib/console-spec.js

@@ -2,19 +2,154 @@ export const kookConsoleSpec = {
     adapterKey: 'kook',
     adapterDisplayName: 'KOOK',
     fields: [
-        { key: 'token', required: true, env: true, description: 'KOOK bot token' },
-        { key: 'encrypt_key', env: true, description: 'webhook 加密密钥（connection: webhook）', descriptionI18n: { en: 'Webhook encryption secret' } },
-        { key: 'verify_token', env: true, description: 'webhook 验证 token（connection: webhook）', descriptionI18n: { en: 'Webhook verification token' } },
-        { key: 'connection', description: 'websocket or webhook' },
-        { key: 'webhookPath', description: 'Local webhook route' },
-        { key: 'data_dir', description: 'SDK data directory' },
-        { key: 'timeout', type: 'number', description: 'SDK request timeout' },
-        { key: 'max_retry', type: 'number', description: 'SDK configured retry count' },
-        { key: 'ignore', description: 'SDK inbound ignore setting: bot or self' },
-        { key: 'logLevel', description: 'SDK log level' },
-        { key: 'apiProxy.port', type: 'number', description: 'Configured API loopback proxy port' },
-        { key: 'streamProxy.port', type: 'number', description: 'Configured Gateway loopback proxy port' },
-        { key: 'streamProxy.serverName', description: 'Expected Gateway TLS hostname' },
+        {
+            key: 'token',
+            required: true,
+            env: true,
+            label: 'Bot Token (机器人令牌)',
+            labelI18n: { en: 'Bot Token' },
+            group: '基础认证',
+            groupI18n: { en: 'Basic Auth' },
+            placeholder: '1/MTIzNDU=/...',
+            description: 'KOOK 开发者中心获取的 Bot Token',
+            descriptionI18n: { en: 'KOOK bot token' },
+        },
+        {
+            key: 'connection',
+            label: '连接模式',
+            labelI18n: { en: 'Connection Mode' },
+            group: '连接与回调',
+            groupI18n: { en: 'Connection & Webhook' },
+            placeholder: 'websocket',
+            description: 'websocket（默认长连接）或 webhook',
+            descriptionI18n: { en: 'websocket or webhook' },
+            options: [
+                { value: 'websocket', label: 'WebSocket 长连接（推荐）', labelI18n: { en: 'WebSocket (Recommended)' } },
+                { value: 'webhook', label: 'Webhook 回调', labelI18n: { en: 'Webhook' } },
+            ],
+        },
+        {
+            key: 'encrypt_key',
+            env: true,
+            label: 'Webhook Encrypt Key',
+            labelI18n: { en: 'Webhook Encrypt Key' },
+            group: '连接与回调',
+            groupI18n: { en: 'Connection & Webhook' },
+            placeholder: 'Webhook 模式下的 Encrypt Key',
+            placeholderI18n: { en: 'Encrypt key for webhook mode' },
+            description: 'webhook 加密密钥（connection: webhook）',
+            descriptionI18n: { en: 'Webhook encryption secret' },
+        },
+        {
+            key: 'verify_token',
+            env: true,
+            label: 'Webhook Verify Token',
+            labelI18n: { en: 'Webhook Verify Token' },
+            group: '连接与回调',
+            groupI18n: { en: 'Connection & Webhook' },
+            placeholder: 'Webhook 模式下的 Verify Token',
+            placeholderI18n: { en: 'Verify token for webhook mode' },
+            description: 'webhook 验证 token（connection: webhook）',
+            descriptionI18n: { en: 'Webhook verification token' },
+        },
+        {
+            key: 'webhookPath',
+            label: 'Webhook 本地路由',
+            labelI18n: { en: 'Webhook Local Path' },
+            group: '连接与回调',
+            groupI18n: { en: 'Connection & Webhook' },
+            placeholder: '/kook/webhook',
+            description: '本地监听的 Webhook 路径',
+            descriptionI18n: { en: 'Local webhook route' },
+        },
+        {
+            key: 'ignore',
+            label: '消息忽略策略',
+            labelI18n: { en: 'Ignore Policy' },
+            group: '流式体验与代理',
+            groupI18n: { en: 'Streaming & Proxy' },
+            placeholder: 'bot',
+            description: '忽略消息来源：bot（所有机器人）或 self（仅自身）',
+            descriptionI18n: { en: 'SDK inbound ignore setting: bot or self' },
+            options: [
+                { value: 'bot', label: '忽略所有机器人 (bot)', labelI18n: { en: 'Ignore all bots (bot)' } },
+                { value: 'self', label: '仅忽略自身 (self)', labelI18n: { en: 'Ignore self only (self)' } },
+            ],
+        },
+        {
+            key: 'timeout',
+            type: 'number',
+            label: '请求超时 (ms)',
+            labelI18n: { en: 'Request Timeout (ms)' },
+            group: '流式体验与代理',
+            groupI18n: { en: 'Streaming & Proxy' },
+            placeholder: '10000',
+            description: 'API 请求超时时间（毫秒）',
+            descriptionI18n: { en: 'SDK request timeout' },
+        },
+        {
+            key: 'max_retry',
+            type: 'number',
+            label: '最大重试次数',
+            labelI18n: { en: 'Max Retries' },
+            group: '流式体验与代理',
+            groupI18n: { en: 'Streaming & Proxy' },
+            placeholder: '3',
+            description: 'SDK 请求失败最大重试次数',
+            descriptionI18n: { en: 'SDK configured retry count' },
+        },
+        {
+            key: 'data_dir',
+            label: 'SDK 数据目录',
+            labelI18n: { en: 'SDK Data Directory' },
+            group: '流式体验与代理',
+            groupI18n: { en: 'Streaming & Proxy' },
+            placeholder: './data/kook',
+            description: 'KOOK SDK 本地缓存目录（可选）',
+            descriptionI18n: { en: 'SDK data directory' },
+        },
+        {
+            key: 'logLevel',
+            label: 'SDK 日志级别',
+            labelI18n: { en: 'SDK Log Level' },
+            group: '流式体验与代理',
+            groupI18n: { en: 'Streaming & Proxy' },
+            placeholder: 'info',
+            description: 'KOOK SDK 日志级别（info / warn / error / debug）',
+            descriptionI18n: { en: 'SDK log level' },
+        },
+        {
+            key: 'apiProxy.port',
+            type: 'number',
+            label: 'API 代理端口',
+            labelI18n: { en: 'API Proxy Port' },
+            group: '流式体验与代理',
+            groupI18n: { en: 'Streaming & Proxy' },
+            placeholder: '例如 7890',
+            description: '本地回环 API 代理端口（可选）',
+            descriptionI18n: { en: 'Configured API loopback proxy port' },
+        },
+        {
+            key: 'streamProxy.port',
+            type: 'number',
+            label: '网关代理端口',
+            labelI18n: { en: 'Gateway Proxy Port' },
+            group: '流式体验与代理',
+            groupI18n: { en: 'Streaming & Proxy' },
+            placeholder: '例如 7890',
+            description: '本地回环 Gateway 代理端口（可选）',
+            descriptionI18n: { en: 'Configured Gateway loopback proxy port' },
+        },
+        {
+            key: 'streamProxy.serverName',
+            label: '网关 TLS 主机名',
+            labelI18n: { en: 'Gateway TLS Server Name' },
+            group: '流式体验与代理',
+            groupI18n: { en: 'Streaming & Proxy' },
+            placeholder: 'gateway.kookapp.cn',
+            description: '代理校验的 Gateway TLS 主机名（可选）',
+            descriptionI18n: { en: 'Expected Gateway TLS hostname' },
+        },
     ],
     docsUrl: 'https://zhin.js.org/adapters/kook',
     readPermission: 'kook:read',

package/lib/endpoint.d.ts

@@ -7,6 +7,7 @@ import type { HttpHost } from '@zhin.js/host-http';
 import type { CapabilityId } from 'zhin.js';
 import { type KookInboundMessage, type KookWebhookEventData, type ResolvedKookWebhookConfig, type ResolvedKookWebsocketConfig } from './protocol.js';
 import { RuntimeKookClient, type KookClientTransport } from './ws.js';
+import { KookSenderRoleResolver } from './sender-roles.js';
 export interface KookEndpointOptions {
     readonly id: CapabilityId;
     readonly config: ResolvedKookWebsocketConfig;
@@ -45,4 +46,4 @@ export declare class KookWebhookEndpoint extends RuntimeKookClient implements En
  * 数据走 kook-client 的 HTTP API 封装：/api/v3/guild/list、
  * /api/v3/channel/list、/api/v3/guild/user-list（SDK 内部已做分页聚合）。
  */
-export declare function createKookEndpointManagement(requireClient: () => KookClientTransport): EndpointManagement;
+export declare function createKookEndpointManagement(requireClient: () => KookClientTransport, roles?: KookSenderRoleResolver): EndpointManagement;

package/lib/endpoint.js

@@ -11,8 +11,8 @@ import { recallKookMessage, sendKookOutbound } from './outbound.js';
 import { KookSenderRoleResolver } from './sender-roles.js';
 import { receiveKookSideEvent } from './side-event-dispatch.js';
 import { createKookSelfProfile } from './self-profile.js';
-/** 入站 message.receive 载荷：规范角色 owner/admin 进 roles，原始角色 id 进 permissions。 */
-function kookInboundPayload(endpointId, conversation, msg, projection, selfId) {
+/** 入站 message.receive 载荷：发送者平台身份进 `sender.platform`（ADR 0056 §1）。 */
+function kookInboundPayload(endpointId, conversation, msg, platform, selfId) {
     return {
         conversation,
         event: msg.event,
@@ -22,8 +22,7 @@ function kookInboundPayload(endpointId, conversation, msg, projection, selfId) {
         sender: {
             id: msg.authorId,
             name: senderDisplayName(msg) || undefined,
-            ...(projection.role ? { roles: [projection.role] } : {}),
-            ...(projection.permissions.length ? { permissions: [...projection.permissions] } : {}),
+            ...(platform ? { platform } : {}),
         },
         endpointId,
         ...(isKookBotMentioned(msg, selfId) ? { mentioned: true } : {}),
@@ -32,7 +31,6 @@ function kookInboundPayload(endpointId, conversation, msg, projection, selfId) {
             userId: msg.authorId,
             guildId: msg.guildId,
             authorRoleIds: msg.authorRoles,
-            ...(projection.role ? { senderRole: projection.role } : {}),
         }),
     };
 }
@@ -45,7 +43,7 @@ export class KookWebsocketEndpoint extends RuntimeKookClient {
     #open = false;
     #executionSignal;
     #started = false;
-    #management = createKookEndpointManagement(() => this.#requireClient());
+    #management = createKookEndpointManagement(() => this.#requireClient(), this.#roles);
     #control = Object.freeze({
         recall: request => recallKookMessage(this.#requireClient(), request),
     });
@@ -122,9 +120,9 @@ export class KookWebsocketEndpoint extends RuntimeKookClient {
                 return;
             const conversation = kookInboundConversation(String(this.#options.id), msg);
             const selfId = this.self_id != null ? String(this.self_id) : undefined;
-            return this.#roles.resolve(msg).then((projection) => {
+            return this.#roles.resolve(msg).then((platform) => {
                 this.#executionSignal?.throwIfAborted();
-                return this[endpointSpec].events.emit('message.receive', kookInboundPayload(this.#options.config.id, conversation, msg, projection, selfId));
+                return this[endpointSpec].events.emit('message.receive', kookInboundPayload(this.#options.config.id, conversation, msg, platform, selfId));
             }).catch((err) => {
                 this.#logger.warn(formatCompact({
                     op: 'kook_gateway_receive_failed',
@@ -196,7 +194,7 @@ export class KookWebhookEndpoint extends RuntimeKookClient {
     #open = false;
     #executionSignal;
     #started = false;
-    #management = createKookEndpointManagement(() => this.#requireClient());
+    #management = createKookEndpointManagement(() => this.#requireClient(), this.#roles);
     #control = Object.freeze({
         recall: request => recallKookMessage(this.#requireClient(), request),
     });
@@ -306,9 +304,9 @@ export class KookWebhookEndpoint extends RuntimeKookClient {
                 return;
             const conversation = kookInboundConversation(String(this.#options.id), msg);
             const selfId = this.self_id != null ? String(this.self_id) : undefined;
-            return this.#roles.resolve(msg).then((projection) => {
+            return this.#roles.resolve(msg).then((platform) => {
                 this.#executionSignal?.throwIfAborted();
-                return this[endpointSpec].events.emit('message.receive', kookInboundPayload(this.#options.config.id, conversation, msg, projection, selfId));
+                return this[endpointSpec].events.emit('message.receive', kookInboundPayload(this.#options.config.id, conversation, msg, platform, selfId));
             }).catch((err) => {
                 this.#logger.warn(formatCompact({
                     op: 'kook_gateway_receive_failed',
@@ -364,8 +362,25 @@ function isKookTextChannelType(type) {
  * 数据走 kook-client 的 HTTP API 封装：/api/v3/guild/list、
  * /api/v3/channel/list、/api/v3/guild/user-list（SDK 内部已做分页聚合）。
  */
-export function createKookEndpointManagement(requireClient) {
+export function createKookEndpointManagement(requireClient, roles = new KookSenderRoleResolver(requireClient)) {
     return Object.freeze({
+        /**
+         * ADR 0056 §1: the Bot's own standing in the channel's guild (`/v3/user/view` self → its role
+         * ids, then the same guild owner / role-permission resolution as senders).
+         */
+        async inspectSelfStanding({ conversation, signal }) {
+            const guildId = conversation.kind === 'channel' ? conversation.parent?.id : undefined;
+            if (!guildId)
+                return undefined;
+            const operation = createEndpointOperation({ signal });
+            const client = requireClient();
+            const selfId = client.self_id != null ? String(client.self_id) : undefined;
+            if (!selfId)
+                return undefined;
+            const { data } = await operation.run(() => client.request.get('/v3/user/view', { params: { user_id: selfId, guild_id: guildId } }));
+            const held = Array.isArray(data?.roles) ? data.roles.map(Number).filter(Number.isFinite) : [];
+            return roles.resolve({ guildId, authorId: selfId, authorRoles: held });
+        },
         async listGroups(request = {}) {
             const operation = createEndpointOperation(request);
             const guilds = await operation.run(() => requireClient().getGuildList());

package/lib/index.d.ts

@@ -4,4 +4,4 @@ export { registerKookWebhookRoutes, handleKookWebhookRequest, type KookWebhookHa
 export { kookWebsocketClientOptions, kookWebhookClientOptions, normalizeKookMessage, type KookClientTransport, } from './ws.js';
 export { type KookClientEventMap } from './client.js';
 export { KookAdapter } from './adapter.js';
-export { checkKookPlatformPermit, kookGroupPermitResolver, normalizeKookSenderForPermit, platformPermit, type KookSenderInfo, } from './platform-permit.js';
+export { platformPermit } from './platform-permit.js';

package/lib/index.js

@@ -3,4 +3,4 @@ export { KookWebhookEndpoint, KookWebsocketEndpoint, } from './endpoint.js';
 export { registerKookWebhookRoutes, handleKookWebhookRequest, } from './webhook.js';
 export { kookWebsocketClientOptions, kookWebhookClientOptions, normalizeKookMessage, } from './ws.js';
 export { KookAdapter } from './adapter.js';
-export { checkKookPlatformPermit, kookGroupPermitResolver, normalizeKookSenderForPermit, platformPermit, } from './platform-permit.js';
+export { platformPermit } from './platform-permit.js';

package/lib/platform-permit.d.ts

@@ -1,22 +1,7 @@
 /**
- * KOOK platform permit — guild / channel 差异化门禁
+ * KOOK platform permit helper（ADR 0056 §5）。
+ *
+ * 平台身份由适配器上报到 `sender.platform`（见 `sender-roles.ts`），permit 由内置评估器
+ * （`@zhin.js/permission`）判断；适配器不再导出自有的 permit 解析器或检查函数。
  */
-import type { PermissionSubject } from '@zhin.js/permission';
-import { KookPermission } from './protocol.js';
 export declare function platformPermit(perm: string): string;
-export declare function kookGroupPermitResolver(logicalPerm: string): string;
-export interface KookSenderInfo {
-    id: string;
-    name: string;
-    permission?: KookPermission;
-    roles?: number[];
-    isGuildOwner?: boolean;
-    isAdmin?: boolean;
-    role?: string;
-    permissions?: string[];
-}
-export declare function normalizeKookSenderForPermit(info: KookSenderInfo, isChannel: boolean): {
-    role?: string;
-    permissions?: string[];
-};
-export declare function checkKookPlatformPermit(perm: string, subject: PermissionSubject): boolean;