@zhin.js/adapter-qq 1.0.84 → 1.1.2

package/agents/qq/skills/qq/tools/channel_info/index.js

@@ -0,0 +1,17 @@
+// 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: '获取 QQ 频道中指定子频道的详细信息',
+    inputSchema: z.object({
+        channel_id: z.string().describe('子频道 ID'),
+    }),
+    adapter: 'qq',
+    tags: ['qq'],
+    permissions: [platformPermission('qq', 'guild_admin')],
+    async execute({ channel_id }, context) {
+        const client = context.$client;
+        return client.getChannelInfo(channel_id);
+    },
+});

package/agents/qq/skills/qq/tools/channel_info/index.ts

@@ -0,0 +1,17 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+
+export default defineAgentTool<{ channel_id: string }>({
+  description: '获取 QQ 频道中指定子频道的详细信息',
+  inputSchema: z.object({
+    channel_id: z.string().describe('子频道 ID'),
+  }),
+  adapter: 'qq',
+  tags: ['qq'],
+  permissions: [platformPermission('qq', 'guild_admin')],
+  async execute({ channel_id  }: { channel_id: string }, context) {
+    const client = context.$client;
+    return client.getChannelInfo(channel_id);
+  },
+});

package/agents/qq/skills/qq/tools/create_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: '创建 QQ 频道角色',
+    inputSchema: z.object({
+        guild_id: z.string().describe('频道 ID'),
+        name: z.string().describe('角色名称'),
+        color: z.number().optional().describe('颜色（RGB 十进制数值）'),
+    }),
+    adapter: 'qq',
+    tags: ['qq'],
+    permissions: [platformPermission('qq', 'guild_owner')],
+    async execute({ guild_id, name, color }, context) {
+        const client = context.$client;
+        const role = await client.createGuildRole(guild_id, name, color);
+        return { success: !!role, role, message: role ? `角色 "${name}" 创建成功` : '创建失败' };
+    },
+});

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

@@ -0,0 +1,20 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+
+export default defineAgentTool<{ guild_id: string; name: string; color?: number }>({
+  description: '创建 QQ 频道角色',
+  inputSchema: z.object({
+    guild_id: z.string().describe('频道 ID'),
+    name: z.string().describe('角色名称'),
+    color: z.number().optional().describe('颜色（RGB 十进制数值）'),
+  }),
+  adapter: 'qq',
+  tags: ['qq'],
+  permissions: [platformPermission('qq', 'guild_owner')],
+  async execute({ guild_id, name, color  }: { guild_id: string; name: string; color?: number }, context) {
+    const client = context.$client;
+    const role = await client.createGuildRole(guild_id, name, color);
+    return { success: !!role, role, message: role ? `角色 "${name}" 创建成功` : '创建失败' };
+  },
+});

package/agents/qq/skills/qq/tools/list_channels/index.js

@@ -0,0 +1,18 @@
+// 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: '获取 QQ 频道下的子频道列表',
+    inputSchema: z.object({
+        guild_id: z.string().describe('频道 ID'),
+    }),
+    adapter: 'qq',
+    tags: ['qq'],
+    permissions: [platformPermission('qq', 'manage_channels')],
+    async execute({ guild_id }, context) {
+        const client = context.$client;
+        const channels = await client.getChannels(guild_id);
+        return { channels, count: channels.length };
+    },
+});

package/agents/qq/skills/qq/tools/list_channels/index.ts

@@ -0,0 +1,18 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+
+export default defineAgentTool<{ guild_id: string }>({
+  description: '获取 QQ 频道下的子频道列表',
+  inputSchema: z.object({
+    guild_id: z.string().describe('频道 ID'),
+  }),
+  adapter: 'qq',
+  tags: ['qq'],
+  permissions: [platformPermission('qq', 'manage_channels')],
+  async execute({ guild_id  }: { guild_id: string }, context) {
+    const client = context.$client;
+    const channels = await client.getChannels(guild_id);
+    return { channels, count: channels.length };
+  },
+});

package/agents/qq/skills/qq/tools/list_guilds/index.js

@@ -0,0 +1,14 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+export default defineAgentTool({
+    description: '获取 QQ 频道列表',
+    inputSchema: z.object({}),
+    adapter: 'qq',
+    tags: ['qq'],
+    async execute(_input, context) {
+        const client = context.$client;
+        const guilds = await client.getGuilds();
+        return { guilds, count: guilds.length };
+    },
+});

package/agents/qq/skills/qq/tools/list_guilds/index.ts

@@ -0,0 +1,14 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+
+export default defineAgentTool<Record<string, never>>({
+  description: '获取 QQ 频道列表',
+  inputSchema: z.object({}),
+  adapter: 'qq',
+  tags: ['qq'],
+  async execute(_input, context) {
+    const client = context.$client;
+    const guilds = await client.getGuilds();
+    return { guilds, count: guilds.length };
+  },
+});

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

@@ -0,0 +1,18 @@
+// 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: '获取 QQ 频道角色列表',
+    inputSchema: z.object({
+        guild_id: z.string().describe('频道 ID'),
+    }),
+    adapter: 'qq',
+    tags: ['qq'],
+    permissions: [platformPermission('qq', 'manage_roles')],
+    async execute({ guild_id }, context) {
+        const client = context.$client;
+        const roles = await client.getGuildRoles(guild_id);
+        return { roles, count: roles.length };
+    },
+});

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

@@ -0,0 +1,18 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+
+export default defineAgentTool<{ guild_id: string }>({
+  description: '获取 QQ 频道角色列表',
+  inputSchema: z.object({
+    guild_id: z.string().describe('频道 ID'),
+  }),
+  adapter: 'qq',
+  tags: ['qq'],
+  permissions: [platformPermission('qq', 'manage_roles')],
+  async execute({ guild_id  }: { guild_id: string }, context) {
+    const client = context.$client;
+    const roles = await client.getGuildRoles(guild_id);
+    return { roles, count: roles.length };
+  },
+});

package/agents/qq/skills/qq/tools/member_detail/index.js

@@ -0,0 +1,18 @@
+// 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: '获取 QQ 频道中指定成员的详细信息',
+    inputSchema: z.object({
+        guild_id: z.string().describe('频道 ID'),
+        user_id: z.string().describe('用户 ID'),
+    }),
+    adapter: 'qq',
+    tags: ['qq'],
+    permissions: [platformPermission('qq', 'guild_admin')],
+    async execute({ guild_id, user_id }, context) {
+        const client = context.$client;
+        return client.getGuildMember(guild_id, user_id);
+    },
+});

package/agents/qq/skills/qq/tools/member_detail/index.ts

@@ -0,0 +1,18 @@
+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 }>({
+  description: '获取 QQ 频道中指定成员的详细信息',
+  inputSchema: z.object({
+    guild_id: z.string().describe('频道 ID'),
+    user_id: z.string().describe('用户 ID'),
+  }),
+  adapter: 'qq',
+  tags: ['qq'],
+  permissions: [platformPermission('qq', 'guild_admin')],
+  async execute({ guild_id, user_id  }: { guild_id: string; user_id: string }, context) {
+    const client = context.$client;
+    return client.getGuildMember(guild_id, user_id);
+  },
+});

package/agents/qq/skills/qq/tools/remove_role/index.js

@@ -0,0 +1,21 @@
+// 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: '移除成员的 QQ 频道角色',
+    inputSchema: z.object({
+        guild_id: z.string().describe('频道 ID'),
+        channel_id: z.string().describe('子频道 ID'),
+        user_id: z.string().describe('用户 ID'),
+        role_id: z.string().describe('角色 ID'),
+    }),
+    adapter: 'qq',
+    tags: ['qq'],
+    permissions: [platformPermission('qq', 'manage_roles')],
+    async execute({ guild_id, channel_id, user_id, role_id }, context) {
+        const client = context.$client;
+        const success = await client.removeMemberRole(guild_id, channel_id, user_id, role_id);
+        return { success, message: success ? '已移除成员的角色' : '操作失败' };
+    },
+});

package/agents/qq/skills/qq/tools/remove_role/index.ts

@@ -0,0 +1,21 @@
+import { defineAgentTool } from '@zhin.js/tool';
+import { z } from 'zod';
+import { platformPermission } from '@zhin.js/permission';
+
+export default defineAgentTool<{ guild_id: string; channel_id: string; user_id: string; role_id: string }>({
+  description: '移除成员的 QQ 频道角色',
+  inputSchema: z.object({
+    guild_id: z.string().describe('频道 ID'),
+    channel_id: z.string().describe('子频道 ID'),
+    user_id: z.string().describe('用户 ID'),
+    role_id: z.string().describe('角色 ID'),
+  }),
+  adapter: 'qq',
+  tags: ['qq'],
+  permissions: [platformPermission('qq', 'manage_roles')],
+  async execute({ guild_id, channel_id, user_id, role_id  }: { guild_id: string; channel_id: string; user_id: string; role_id: string }, context) {
+    const client = context.$client;
+    const success = await client.removeMemberRole(guild_id, channel_id, user_id, role_id);
+    return { success, message: success ? '已移除成员的角色' : '操作失败' };
+  },
+});

package/agents/qq/system.md

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

package/commands/qq/endpoint/add/[[id]]/index.js

@@ -0,0 +1,3 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { qqEndpointCommands } from '../../definition.js';
+export default qqEndpointCommands.add;

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

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

package/commands/qq/endpoint/cancel/index.js

@@ -0,0 +1,11 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { defineCommand } from 'zhin.js/command';
+import { isQqEndpointOperator, QQ_ENDPOINT_FORBIDDEN, qqRuntimeStateToken, runQqEndpointCancel, } from '../definition.js';
+export default defineCommand({
+    description: '取消进行中的 QQ 扫码绑定或公域/私域选择',
+    execute({ config, input, use }) {
+        if (!isQqEndpointOperator(config, input))
+            return QQ_ENDPOINT_FORBIDDEN;
+        return runQqEndpointCancel(use(qqRuntimeStateToken));
+    },
+});

package/commands/qq/endpoint/cancel/index.ts

@@ -0,0 +1,15 @@
+import { defineCommand } from 'zhin.js/command';
+import {
+  isQqEndpointOperator,
+  QQ_ENDPOINT_FORBIDDEN,
+  qqRuntimeStateToken,
+  runQqEndpointCancel,
+} from '../definition.js';
+
+export default defineCommand({
+  description: '取消进行中的 QQ 扫码绑定或公域/私域选择',
+  execute({ config, input, use }) {
+    if (!isQqEndpointOperator(config, input)) return QQ_ENDPOINT_FORBIDDEN;
+    return runQqEndpointCancel(use(qqRuntimeStateToken));
+  },
+});

package/commands/qq/endpoint/definition.js

@@ -0,0 +1,188 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+/**
+ * `qq endpoint` 命令的业务逻辑（与命令定义文件分离，便于测试）。
+ * 通用部分（权限 / list / remove / 配置写回 / .env 持久化）已迁移到
+ * @zhin.js/adapter 的 createEndpointCommands 套件；本文件保留 QQ 特化的
+ * 扫码绑定 add 流程（经套件 bindFlow 钩子接入）与 cancel，并导出
+ * qqEndpointCommands 供 commands/qq/endpoint/ 下的命令文件默认导出。
+ */
+import { buildEndpointEnvKey, createEndpointCommands, endpointCommandForbidden, endpointConfigurationStoreToken, extractEndpointCommandReply, formatEndpointList, isEndpointOperator, removeEndpointById, } from 'zhin.js/adapter';
+import { defineCommand } from 'zhin.js/command';
+import { QQ_BOT_KIND_PROMPT, qqCommandSessionKey } from "../../../lib/qq-bot-kind-prompt.js";
+import { startQqBindFlow } from "../../../lib/qq-bind-flow.js";
+import { defaultQqEndpointIntentFields } from "../../../lib/qq-intents.js";
+import { qqRuntimeStateToken, } from "../../../lib/qq-runtime-state.js";
+export { qqRuntimeStateToken };
+/**
+ * endpoint 管理命令的操作者校验：实例配置声明了 master（顶层或任一端点项）时
+ * 仅 master 可执行 add/cancel/remove；未配置则放行（首个扫码绑定者即为 owner，
+ * legacy applyBindOwnership 会把 operator 写为新端点的 master）。
+ */
+export function isQqEndpointOperator(config, input) {
+    return isEndpointOperator(config, input);
+}
+export const QQ_ENDPOINT_FORBIDDEN = endpointCommandForbidden('QQ');
+/**
+ * 从命令 input（Runtime Message）提取 $reply；非消息来源（如 Host API 调用）降级为 no-op。
+ */
+export function extractQqCommandReply(input) {
+    return extractEndpointCommandReply(input);
+}
+function busyFooter(state) {
+    if (state.bindFlow)
+        return '⚠️ 有进行中的扫码绑定，可用 qq endpoint cancel 取消';
+    if (state.pendingBotKind) {
+        return `⚠️ endpoint「${state.pendingBotKind.endpointId}」等待公域/私域选择，回复 public/private 或 qq endpoint cancel`;
+    }
+    return undefined;
+}
+/** `qq endpoint list`：运行中的 endpoints（本 generation adapter create 注册）+ 配置里的 endpoints */
+export async function runQqEndpointList(state, store) {
+    return formatEndpointList(qqEndpointListSpec, {
+        running: state.endpoints.values(),
+        configured: await store.list('qq'),
+        footer: busyFooter(state),
+    });
+}
+const qqEndpointListSpec = {
+    adapterKey: 'qq',
+    adapterDisplayName: 'QQ',
+    describeEntry: (entry) => `appid: ${String(entry.appid)}`,
+};
+async function writeEndpointWithBotKind(pending, botKind, store) {
+    const appidKey = buildEndpointEnvKey('qq', pending.endpointId, 'appid');
+    const secretKey = buildEndpointEnvKey('qq', pending.endpointId, 'secret');
+    const intentFields = defaultQqEndpointIntentFields(botKind);
+    const { filePath } = await store.add({
+        adapterKey: 'qq',
+        entry: {
+            id: pending.endpointId,
+            appid: `\${${appidKey}}`,
+            secret: `\${${secretKey}}`,
+            botKind: intentFields.botKind,
+            intents: [...intentFields.intents],
+        },
+        environment: {
+            [appidKey]: pending.appId,
+            [secretKey]: pending.appSecret,
+        },
+    });
+    return (`✅ 已按 botKind=${intentFields.botKind} 将 endpoint「${pending.endpointId}」写入 .env 与 ${filePath}。\n` +
+        `intents: ${intentFields.intents.join(', ')}。\n` +
+        '⚠️ 需重启 zhin 后新 endpoint 才会生效。');
+}
+/**
+ * 完成 pending 的公域/私域选择：一次性写 .env + yaml。
+ * @returns 成功文案；调用方负责清 pending。
+ */
+export async function completeQqPendingBotKind(pending, botKind, store) {
+    return await writeEndpointWithBotKind(pending, botKind, store);
+}
+/**
+ * `qq endpoint add [id]`：启动扫码绑定流程。
+ * 返回的 Promise 在二维码链接就绪（或前置失败）时 resolve 为首条回复；
+ * 后续状态（已扫码 / 成功 / 失败 / 过期刷新）通过 reply 推回当前会话。
+ * 扫码成功后凭据暂存内存并询问公域/私域；确认后一次性写 .env + yaml。
+ */
+export function runQqEndpointAdd(state, id, reply, store, input) {
+    if (state.bindFlow || state.pendingBotKind) {
+        return Promise.resolve('已有进行中的 QQ 机器人绑定或待确认的公域/私域选择，请先发送 qq endpoint cancel 取消后再试');
+    }
+    const endpointId = id?.trim() || undefined;
+    const sessionKey = qqCommandSessionKey(input);
+    return new Promise((resolve) => {
+        let firstReplied = false;
+        const settle = (text) => {
+            if (!firstReplied) {
+                firstReplied = true;
+                resolve(text);
+                return;
+            }
+            // Follow-ups outlive the inbound Message reply scope; durable reply
+            // (OutboundHost) is provided by createEndpointCommands.bindFlow. Never
+            // let a late notify crash the process.
+            void Promise.resolve(reply(text)).catch(() => undefined);
+        };
+        const stop = startQqBindFlow({
+            onQrDisplayed: (url) => {
+                // QQ 出站当前仅支持纯文本（富媒体未迁移），二维码只能发链接文本
+                settle(`请用手机 QQ 打开以下链接完成扫码绑定（二维码图片出站暂未支持，故发送链接）：\n${url}`);
+            },
+            onQrExpired: async () => {
+                try {
+                    await reply('二维码已过期，正在刷新，请扫描新链接…');
+                }
+                catch {
+                    // same as settle follow-up: best-effort after command scope ends
+                }
+            },
+            onSuccess: async (credentials) => {
+                state.bindFlow = null;
+                try {
+                    const [{ appId, appSecret }] = credentials;
+                    const finalName = endpointId ?? appId;
+                    // 无会话上下文（Host 等）时无法追问，直接按公域一次性写入
+                    if (!sessionKey) {
+                        settle(await writeEndpointWithBotKind({
+                            endpointId: finalName,
+                            appId,
+                            appSecret,
+                            sessionKey: '',
+                        }, 'public', store) +
+                            '\n（当前会话无法交互选择公/私域；私域请手动改配置。）');
+                        return;
+                    }
+                    state.pendingBotKind = {
+                        endpointId: finalName,
+                        appId,
+                        appSecret,
+                        sessionKey,
+                    };
+                    settle(`✅ 扫码成功！endpoint「${finalName}」。\n` +
+                        QQ_BOT_KIND_PROMPT);
+                }
+                catch (error) {
+                    settle(`绑定成功但写入配置失败：${error instanceof Error ? error.message : String(error)}`);
+                }
+            },
+            onFailure: (error) => {
+                state.bindFlow = null;
+                settle(`❌ QQ 绑定失败：${error.message}`);
+            },
+        }, { source: 'zhin' });
+        state.bindFlow = { id: endpointId, stop };
+    });
+}
+/** `qq endpoint cancel`：中止进行中的绑定或待选 botKind */
+export function runQqEndpointCancel(state) {
+    if (state.bindFlow) {
+        state.bindFlow.stop();
+        state.bindFlow = null;
+        return '已取消进行中的 QQ 绑定流程';
+    }
+    if (state.pendingBotKind) {
+        const name = state.pendingBotKind.endpointId;
+        state.pendingBotKind = null;
+        return `已取消 endpoint「${name}」的绑定（尚未写入任何文件）`;
+    }
+    return '当前没有进行中的 QQ 绑定流程';
+}
+/** `qq endpoint remove <id>`：从 zhin.config.yml 移除对应 endpoints 项 */
+export async function runQqEndpointRemove(_state, id, store) {
+    return await removeEndpointById(qqEndpointListSpec, id, store);
+}
+/**
+ * 通用套件生成的 QQ endpoint 命令（add 经 bindFlow 钩子走扫码绑定）。
+ * commands/qq/endpoint/ 下的 list / add / remove 直接默认导出这三项；cancel 为 QQ 特化，单独定义。
+ */
+export const qqEndpointCommands = createEndpointCommands({
+    ...qqEndpointListSpec,
+    fields: [
+        { key: 'appid', required: true, env: true, description: 'QQ 机器人 appid' },
+        { key: 'secret', required: true, env: true, description: 'QQ 机器人 secret' },
+    ],
+    running: (use) => use(qqRuntimeStateToken).endpoints.values(),
+    listFooter: (use) => busyFooter(use(qqRuntimeStateToken)),
+    addDescription: '手机 QQ 扫码绑定机器人：确认公域/私域后一次性写入 .env 与 zhin.config.yml（重启生效）',
+    bindFlow: ({ id, reply, input, use }) => runQqEndpointAdd(use(qqRuntimeStateToken), id, reply, use(endpointConfigurationStoreToken), input),
+}, defineCommand);