chatluna-plugin-onebot-toolbox 0.0.0-stage → 0.0.2

package/lib/index.js

@@ -0,0 +1,809 @@
+import { Schema } from "@chatluna/schema";
+import { fileRefTableOf } from "@chatluna/message";
+// external/onebot-toolbox/src/logger.ts
+function createLogger(ctx, debugLogging) {
+	const logger = ctx.logger;
+	return {
+		debug: (format, ...args) => debugLogging ? logger.info(format, ...args) : logger.debug(format, ...args),
+		info: (format, ...args) => logger.info(format, ...args),
+		warn: (format, ...args) => logger.warn(format, ...args)
+	};
+}
+// external/onebot-toolbox/src/config.ts
+/** 原生工具的名称与描述固定，全部注册；启用范围交给 v2 的工具管理。 */
+const NATIVE_TOOLS = {
+	setSelfProfile: {
+		toolName: "set_self_profile",
+		description: "修改自己的 QQ 资料，可设置昵称、签名和性别。"
+	},
+	setQQAvatar: {
+		toolName: "set_qq_avatar",
+		description: "修改机器人 QQ 头像。imageUrl 填会话里图片的 ref（`<img ref=\"i…\"/>` 的 ref 属性）、HTTP/HTTPS 链接或 OneBot 端可读的本地路径；会话图片与 HTTP/HTTPS 图片会先由插件读取并转为 OneBot base64 文件，避免临时 URL 过期或 OneBot 端无法访问。"
+	},
+	setGroupCard: {
+		toolName: "set_group_card",
+		description: "修改群成员的群昵称。"
+	},
+	searchGroupMember: {
+		toolName: "search_group_member",
+		description: "根据 qqid 精确查询群成员的群昵称与 QQ 昵称，或根据群昵称/QQ 昵称搜索 qqid。默认查询当前群聊，可通过 groupId 查询指定群。"
+	},
+	leaveGroup: {
+		toolName: "set_group_leave",
+		description: "让机器人退出当前群聊。"
+	},
+	handleRequest: {
+		toolName: "handle_request",
+		description: "根据 OneBot 申请 flag 同意或拒绝好友申请、加群申请或群邀请。"
+	},
+	setGroupKick: {
+		toolName: "set_group_kick",
+		description: "将指定成员踢出群聊。"
+	},
+	setGroupSpecialTitle: {
+		toolName: "set_group_special_title",
+		description: "修改或清除群成员的 QQ 群专属头衔。"
+	},
+	deleteMessage: {
+		toolName: "delete_msg",
+		description: "根据消息 ID 撤回指定消息。"
+	}
+};
+const NATIVE_TOOL_KEYS = Object.keys(NATIVE_TOOLS);
+const DEFAULT_MEMBER_INFO_ITEMS = [
+	"nickname",
+	"userId",
+	"role",
+	"level",
+	"title",
+	"gender",
+	"age",
+	"area",
+	"joinTime",
+	"lastSentTime"
+];
+const DEFAULT_GROUP_INFO_ITEMS = [
+	"groupName",
+	"groupId",
+	"memberCount",
+	"ownerList",
+	"adminList"
+];
+/** 变量名须满足 v2 模板的变量命名规则（`@chatluna/prompt` 的 `variable`），留空表示不注册。 */
+const VARIABLE_NAME = /^([a-z_][a-z0-9_]*)?$/i;
+const memberItems = (subject) => Schema.array(Schema.union([
+	Schema.const("userId").description(`${subject} ID`),
+	Schema.const("nickname").description("群昵称"),
+	Schema.const("role").description("群内身份"),
+	Schema.const("level").description("群等级"),
+	Schema.const("title").description("群头衔"),
+	Schema.const("gender").description("性别"),
+	Schema.const("age").description("年龄"),
+	Schema.const("area").description("地区"),
+	Schema.const("joinTime").description("入群时间"),
+	Schema.const("lastSentTime").description("最后发言时间")
+])).role("checkbox").default([...DEFAULT_MEMBER_INFO_ITEMS]);
+const variableName = (name) => Schema.string().default(name).pattern(VARIABLE_NAME).extra("label", "变量名称").description("在预设中以`{变量名称}`引用，留空时不注册");
+const basicFields = {
+	oneBotProtocol: Schema.union([
+		Schema.const("napcat").description("NapCat"),
+		Schema.const("llbot").description("LLBot"),
+		Schema.const("snowluma").description("SnowLuma")
+	]).default("napcat").role("radio").extra("label", "OneBot 协议").description("按所选实现调整请求参数：LLBot 不支持设置性别，群禁言列表的群号类型也不同；SnowLuma 同意好友申请后另行设置备注"),
+	requestNotice: Schema.boolean().default(true).extra("label", "申请通知").description("收到好友申请、加群申请或群邀请时唤醒对应会话，把申请 flag 告诉模型，供`handle_request`工具处理。好友申请与群邀请发往申请人的私聊，加群申请发往所申请的群；该工具在工具管理中禁用时不唤醒")
+};
+const variableFields = {
+	userInfo: Schema.object({
+		variableName: variableName("userInfo"),
+		items: memberItems("用户").extra("label", "信息项").description("选择用户信息变量中显示的详细信息项")
+	}).description("用户信息变量").collapse(),
+	botInfo: Schema.object({
+		variableName: variableName("botInfo"),
+		items: memberItems("机器人").extra("label", "信息项").description("选择机器人信息变量中显示的详细信息项")
+	}).description("机器人信息变量").collapse(),
+	groupInfo: Schema.object({
+		variableName: variableName("groupInfo"),
+		items: Schema.array(Schema.union([
+			Schema.const("groupName").description("群名称"),
+			Schema.const("groupId").description("群号"),
+			Schema.const("memberCount").description("成员数量"),
+			Schema.const("createTime").description("创建时间（仅部分实现支持）"),
+			Schema.const("ownerList").description("群主名单"),
+			Schema.const("adminList").description("管理员名单")
+		])).role("checkbox").default([...DEFAULT_GROUP_INFO_ITEMS]).extra("label", "信息项").description("选择群信息变量中显示的群信息项")
+	}).description("群信息变量").collapse(),
+	groupShutList: Schema.object({ variableName: variableName("groupShutList") }).description("群禁言列表变量").collapse()
+};
+const otherFields = { debugLogging: Schema.boolean().default(false).extra("label", "输出调试日志").description("以 info 级别输出工具调用与变量解析的调试信息") };
+/**
+* 插件配置，直接在 v2 的插件设置页编辑。顶层是分组的 intersect，SchemaForm 把每组的 description 渲染成小节标题；
+* 每个字段都写 `extra('label')`，缺 label 时 SchemaForm 会把配置键当标题显示。
+*/
+const Config = Schema.intersect([
+	Schema.object(basicFields).description("基础设置"),
+	Schema.object(variableFields).description("变量"),
+	Schema.object(otherFields).description("其他设置")
+]);
+// external/onebot-toolbox/src/requests.ts
+/**
+* 申请发往的会话：好友申请与群邀请发往申请人的私聊，加群申请发往所申请的群。
+* 用路由身份而不是事件 Session 唤醒：申请事件不是消息，申请人与机器人之间往往还没有会话，
+* `chat.wake` 会按身份新开一个。
+*/
+function requestTarget(session, kind) {
+	if (!session.userId) return void 0;
+	if (kind === "add") {
+		if (!session.guildId) return void 0;
+		return {
+			platform: session.platform,
+			selfId: session.selfId,
+			isDirect: false,
+			guildId: session.guildId,
+			channelId: session.guildId,
+			userId: session.userId
+		};
+	}
+	return {
+		platform: session.platform,
+		selfId: session.selfId,
+		isDirect: true,
+		channelId: `private:${session.userId}`,
+		userId: session.userId
+	};
+}
+/** 唤醒原因即模型看到的通知，写明 flag 与调用方式，模型据此调用处理申请工具。 */
+function requestReason(session, kind, toolName) {
+	const comment = session.content?.trim() ? `, message: ${JSON.stringify(session.content.trim())}` : "";
+	const flag = `flag: ${JSON.stringify(session.messageId ?? "")}`;
+	if (kind === "friend") return `user ${session.userId} sent you a friend request (${flag}${comment}). Call ${toolName} with requestType "friend" and userId "${session.userId}" to approve or reject it`;
+	if (kind === "add") return `user ${session.userId} requested to join group ${session.guildId} (${flag}${comment}). Call ${toolName} with requestType "group" and subType "add" to approve or reject it`;
+	return `user ${session.userId} invited you to join group ${session.guildId} (${flag}${comment}). Call ${toolName} with requestType "group" and subType "invite" to approve or reject it`;
+}
+/**
+* v2 不把 OneBot 的申请事件交给模型，`handle_request` 拿不到 flag 就无从调用，
+* 所以把申请转成一次唤醒；工具在 v2 工具管理里被禁用时跟着不唤醒。会话所在路由关闭或没选模型时 `wake` 会报错，只记调试日志。
+*/
+function registerRequestNotices(ctx, config, log) {
+	if (!config.requestNotice) return;
+	const toolName = NATIVE_TOOLS.handleRequest.toolName;
+	ctx.inject(["chat"], (inner) => {
+		const notify = (session, kind) => {
+			if (session.platform !== "onebot") return;
+			if (!session.messageId) return log.debug("%s request without flag ignored", kind);
+			if (!inner.tools.list().some((tool) => tool.name === toolName)) return log.debug("%s request ignored: %s is disabled", kind, toolName);
+			const target = requestTarget(session, kind);
+			if (!target) return;
+			inner.chat.wake(target, {
+				reason: requestReason(session, kind, toolName),
+				by: "onebot-toolbox"
+			}).then(() => log.debug("%s request %s delivered", kind, session.messageId)).catch((error) => log.debug("%s request %s not delivered: %s", kind, session.messageId, String(error)));
+		};
+		inner.on("friend-request", (session) => notify(session, "friend"));
+		inner.on("guild-member-request", (session) => notify(session, "add"));
+		inner.on("guild-request", (session) => notify(session, "invite"));
+	});
+}
+// external/onebot-toolbox/src/onebot.ts
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** 会话所在的 OneBot 机器人；不是 OneBot 会话或找不到机器人时为 undefined。 */
+function oneBotOf(ctx, platform, selfId) {
+	if (platform !== "onebot" || selfId === void 0) return void 0;
+	return ctx.satori.bots.find((bot) => bot.platform === "onebot" && bot.selfId === selfId);
+}
+/** 调用 OneBot action 并返回 data，按响应包的 status 与 retcode 判定业务失败。 */
+async function callOneBot(bot, action, params) {
+	const result = await bot.internal._request(action, params);
+	if (!isRecord(result) || typeof result.status !== "string" || typeof result.retcode !== "number") throw new Error("Invalid OneBot response envelope");
+	if (result.status === "ok" && result.retcode === 0) return result.data;
+	const reason = result.wording || result.message || result.status || "OneBot returned failed";
+	throw new Error(`${String(reason)} (retcode: ${result.retcode})`);
+}
+/**
+* 整数形式的 ID 转成数字，其余原样保留；OneBot 实现普遍要求数字形式的群号、QQ 号与消息 ID。
+* SnowLuma 的 message_id 是 int32 哈希，常为负数，所以带负号的整数同样转换。
+*/
+function numericId(value) {
+	return /^-?\d+$/.test(value) ? Number(value) : value;
+}
+/** 取第一个非空值（去掉首尾空白后不为空字符串），保留原始类型。 */
+function pickFirst(...values) {
+	for (const value of values) {
+		if (value === null || value === void 0) continue;
+		if (!String(value).trim()) continue;
+		return typeof value === "number" ? value : String(value);
+	}
+}
+function pickText(...values) {
+	return String(pickFirst(...values) ?? "").trim();
+}
+/** OneBot 使用秒，Satori 使用毫秒，统一成毫秒；空值与 0 视为没有。 */
+function normalizeTimestamp(raw) {
+	if (raw === null || raw === void 0 || raw === "") return void 0;
+	const numeric = Number(raw);
+	if (!Number.isFinite(numeric) || numeric === 0) return void 0;
+	return numeric < 1e11 ? numeric * 1e3 : numeric;
+}
+const pad = (value) => String(value).padStart(2, "0");
+function formatDate(value) {
+	if (value === void 0) return "";
+	const date = new Date(value);
+	if (Number.isNaN(date.valueOf())) return "";
+	return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+}
+function formatDateTime(value) {
+	const day = formatDate(value);
+	if (!day || value === void 0) return day;
+	const date = new Date(value);
+	return `${day} ${pad(date.getHours())}:${pad(date.getMinutes())}`;
+}
+function asMembers(value) {
+	return Array.isArray(value) ? value.filter(isRecord) : [];
+}
+function asRecord(value) {
+	return isRecord(value) ? value : void 0;
+}
+// external/onebot-toolbox/src/tools.ts
+const MISSING_GROUP = "Missing groupId. Provide groupId explicitly or run inside a group session.";
+const MAX_MEMBER_RESULTS = 10;
+const groupIdArg = () => Schema.string().required(false).description("Target group ID. Defaults to current session group.");
+function groupOf(scope, groupId) {
+	const resolved = groupId?.trim() || scope.guildId?.trim();
+	if (!resolved) throw new Error(MISSING_GROUP);
+	return resolved;
+}
+function required(value, name) {
+	const trimmed = value.trim();
+	if (!trimmed) throw new Error(`${name} is required.`);
+	return trimmed;
+}
+const GENDERS = {
+	unknown: "0",
+	male: "1",
+	female: "2"
+};
+const STORAGE_PREFIX = "storage://";
+/** v2 给模型的文件占位符 `<img ref="i…"/>`：`i` 加内容哈希的最短唯一前缀（至少 6 位）。 */
+const FILE_REF = /^i[0-9a-f]{6,}$/;
+const base64File = (buffer) => `base64://${buffer.toString("base64")}`;
+/** HTTP/HTTPS 图片先读成 base64：OneBot 端常访问不到临时 URL，或 URL 在提交前就已过期。 */
+async function remoteFile(url) {
+	try {
+		const response = await fetch(url);
+		if (!response.ok) throw new Error(`HTTP ${response.status}`);
+		return base64File(Buffer.from(await response.arrayBuffer()));
+	} catch (error) {
+		throw new Error(`无法读取头像图片：${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+/** 入站图片由 v2 下载进 `chatluna_storage`，24 小时后过期；没装存储插件时会话里只有 url 或 data 块。 */
+async function storageFile(ctx, reference) {
+	const storage = ctx.get("chatluna_storage");
+	if (!storage) throw new Error(`Cannot read ${reference}: the chatluna_storage service is not loaded.`);
+	const file = await storage.getTempFile(reference.slice(10));
+	if (!file) throw new Error(`${reference} is not in storage (it may have expired).`);
+	return base64File(await file.data);
+}
+function dataFile(data) {
+	if (!data.startsWith("data:")) return `base64://${data}`;
+	const comma = data.indexOf(",");
+	const body = data.slice(comma + 1);
+	return data.slice(0, comma).endsWith(";base64") ? `base64://${body}` : base64File(Buffer.from(decodeURIComponent(body)));
+}
+function messagesOf(agent) {
+	const session = agent && "session" in agent ? agent.session : void 0;
+	if (session === null || typeof session !== "object" || !("messages" in session) || typeof session.messages !== "function") return void 0;
+	return session.messages();
+}
+/**
+* v2 不把聊天图片的地址交给模型，只给 `<img ref="i…"/>`，ref 要在发起调用的 agent 的会话日志里按内容哈希解析
+* （与 v2 自带的 `look` 工具、出站 `<img ref>` 同一张表）。
+*/
+async function sessionImageFile(scope, ref) {
+	const messages = messagesOf(scope.agent);
+	if (!messages) throw new Error(`Image ref ${ref} can only be resolved inside a conversation.`);
+	const block = fileRefTableOf(messages).resolve(ref);
+	if (!block) throw new Error(`Image ref ${ref} is not in this conversation.`);
+	if (!block.mediaType.startsWith("image/")) throw new Error(`ref ${ref} is ${block.mediaType}, not an image.`);
+	const { data } = block;
+	if (data.type === "data") return dataFile(data.data);
+	if (data.type === "url") return remoteFile(data.url);
+	if (data.type === "reference" && data.reference.startsWith(STORAGE_PREFIX)) return storageFile(scope.ctx, data.reference);
+	throw new Error(`Image ref ${ref} cannot be read.`);
+}
+/** 头像来源：会话图片 ref、`storage://`、HTTP/HTTPS 图片都先读成 base64 再提交，其余（OneBot 端可读的本地路径）原样提交。 */
+async function avatarFile(scope, image) {
+	if (FILE_REF.test(image)) return sessionImageFile(scope, image);
+	if (image.startsWith(STORAGE_PREFIX)) return storageFile(scope.ctx, image);
+	if (/^https?:\/\//i.test(image)) return remoteFile(image);
+	return image;
+}
+function formatMember(index, member) {
+	return `${index}. qqid：${pickText(member.user_id) || "未知"}，群昵称：${pickText(member.card) || "无"}，QQ昵称：${pickText(member.nickname) || "无"}`;
+}
+const NATIVE_TOOL_IMPLEMENTATIONS = {
+	setSelfProfile: {
+		args: Schema.args({
+			nickname: Schema.string().min(1).description("The new nickname for the bot."),
+			signature: Schema.string().required(false).description("Optional: the new personal signature."),
+			gender: Schema.union([
+				"unknown",
+				"male",
+				"female"
+			]).required(false).description("Optional: the new gender.")
+		}),
+		effect: "write",
+		async run(scope, args) {
+			await callOneBot(scope.bot, "set_qq_profile", {
+				nickname: args.nickname,
+				...args.signature ? { personal_note: args.signature } : {},
+				...args.gender && scope.protocol !== "llbot" ? { sex: GENDERS[args.gender] } : {}
+			});
+			return "机器人资料已更新。";
+		}
+	},
+	setQQAvatar: {
+		args: Schema.args({ imageUrl: Schema.string().min(1).description("The image: the ref attribute of an `<img ref=\"i…\"/>` in this conversation, an HTTP/HTTPS URL, or a local file path readable by the OneBot side.") }),
+		effect: "write",
+		async run(scope, args) {
+			const file = await avatarFile(scope, required(args.imageUrl, "imageUrl"));
+			await callOneBot(scope.bot, "set_qq_avatar", { file });
+			return "QQ 头像已更新。";
+		}
+	},
+	setGroupCard: {
+		args: Schema.args({
+			groupId: groupIdArg(),
+			userId: Schema.string().min(1).description("Target member user ID."),
+			card: Schema.string().min(1).description("New group card for the member.")
+		}),
+		effect: "write",
+		async run(scope, args) {
+			const groupId = groupOf(scope, args.groupId);
+			const userId = required(args.userId, "userId");
+			const card = required(args.card, "card");
+			await callOneBot(scope.bot, "set_group_card", {
+				group_id: groupId,
+				user_id: userId,
+				card
+			});
+			return `群昵称已更新：${userId} -> ${card}`;
+		}
+	},
+	searchGroupMember: {
+		args: Schema.args({
+			groupId: groupIdArg(),
+			query: Schema.string().min(1).description("qqid, group card, or QQ nickname to search."),
+			mode: Schema.union([
+				"auto",
+				"byName",
+				"byQQ"
+			]).required(false).description("Search mode. Defaults to auto.")
+		}),
+		effect: "read",
+		async run(scope, args) {
+			const query = required(args.query, "query");
+			const mode = args.mode ?? "auto";
+			const groupId = groupOf(scope, args.groupId);
+			const members = asMembers(await callOneBot(scope.bot, "get_group_member_list", { group_id: numericId(groupId) }));
+			const byQQ = mode === "byQQ" || mode === "auto" && /^\d+$/.test(query);
+			const keyword = query.toLowerCase();
+			const matches = members.filter((member) => byQQ ? pickText(member.user_id) === query : [pickText(member.card), pickText(member.nickname)].some((name) => name && name.toLowerCase().includes(keyword)));
+			if (!matches.length) return "未找到匹配的群成员。";
+			return [matches.length > MAX_MEMBER_RESULTS ? `仅显示前 ${MAX_MEMBER_RESULTS} 条，共 ${matches.length} 条匹配：` : `找到 ${matches.length} 个匹配成员：`, ...matches.slice(0, MAX_MEMBER_RESULTS).map((member, index) => formatMember(index + 1, member))].join("\n");
+		}
+	},
+	leaveGroup: {
+		args: Schema.args({ groupId: groupIdArg() }),
+		effect: "write",
+		async run(scope, args) {
+			const groupId = groupOf(scope, args.groupId);
+			await callOneBot(scope.bot, "set_group_leave", { group_id: groupId });
+			return `已退出群 ${groupId}。`;
+		}
+	},
+	handleRequest: {
+		args: Schema.args({
+			requestType: Schema.union(["friend", "group"]).description("Request type: friend or group."),
+			flag: Schema.string().min(1).description("OneBot request flag from the event."),
+			approve: Schema.boolean().description("true to approve the request, false to reject it."),
+			subType: Schema.union(["add", "invite"]).required(false).description("Required for group requests: add or invite."),
+			remark: Schema.string().required(false).description("Optional friend remark when approving a friend request."),
+			userId: Schema.string().required(false).description("Requester user ID of a friend request; needed to apply the remark on SnowLuma."),
+			reason: Schema.string().required(false).description("Optional rejection reason for a group request.")
+		}),
+		effect: "write",
+		async run(scope, args) {
+			const flag = required(args.flag, "request flag");
+			const verb = args.approve ? "同意" : "拒绝";
+			if (args.requestType === "friend") {
+				const remark = args.remark?.trim() ?? "";
+				await callOneBot(scope.bot, "set_friend_add_request", {
+					flag,
+					approve: args.approve,
+					remark
+				});
+				const message = `已${verb}好友申请 ${flag}。`;
+				if (scope.protocol !== "snowluma" || !args.approve || !remark) return message;
+				const userId = args.userId?.trim();
+				if (!userId) return `${message}未提供申请人 userId，备注未设置。`;
+				await callOneBot(scope.bot, "set_friend_remark", {
+					user_id: numericId(userId),
+					remark
+				});
+				return `${message}备注已设置为 ${remark}。`;
+			}
+			if (!args.subType) throw new Error("subType is required for group requests; use add or invite.");
+			await callOneBot(scope.bot, "set_group_add_request", {
+				flag,
+				sub_type: args.subType,
+				approve: args.approve,
+				reason: args.reason?.trim() ?? ""
+			});
+			return `已${verb}${args.subType === "invite" ? "群邀请" : "加群申请"} ${flag}。`;
+		}
+	},
+	setGroupKick: {
+		args: Schema.args({
+			groupId: groupIdArg(),
+			userId: Schema.string().min(1).description("Target member user ID.")
+		}),
+		effect: "write",
+		async run(scope, args) {
+			const groupId = groupOf(scope, args.groupId);
+			const userId = required(args.userId, "userId");
+			await callOneBot(scope.bot, "set_group_kick", {
+				group_id: groupId,
+				user_id: userId
+			});
+			return `已将用户 ${userId} 移出群 ${groupId}。`;
+		}
+	},
+	setGroupSpecialTitle: {
+		args: Schema.args({
+			groupId: groupIdArg(),
+			userId: Schema.string().min(1).description("Target member user ID."),
+			title: Schema.string().description("New special title. Use an empty string to clear it.")
+		}),
+		effect: "write",
+		async run(scope, args) {
+			const groupId = groupOf(scope, args.groupId);
+			const userId = required(args.userId, "userId");
+			const title = args.title.trim();
+			await callOneBot(scope.bot, "set_group_special_title", {
+				group_id: groupId,
+				user_id: userId,
+				special_title: title
+			});
+			return title ? `群专属头衔已更新：${userId} -> ${title}` : `群专属头衔已清除：${userId}`;
+		}
+	},
+	deleteMessage: {
+		args: Schema.args({ message_id: Schema.string().min(1).description("Specific message ID to delete.") }),
+		effect: "write",
+		async run(scope, args) {
+			const messageId = required(args.message_id, "message_id");
+			await callOneBot(scope.bot, "delete_msg", { message_id: numericId(messageId) });
+			return `Message deleted by ID ${messageId}.`;
+		}
+	}
+};
+/** 全部原生工具的定义，名称与描述统一取自 NATIVE_TOOLS。 */
+function nativeToolDefinitions(ctx, config, log) {
+	return NATIVE_TOOL_KEYS.map((key) => {
+		const tool = NATIVE_TOOL_IMPLEMENTATIONS[key];
+		const { toolName: name, description } = NATIVE_TOOLS[key];
+		return {
+			name,
+			description,
+			args: tool.args,
+			traits: { effect: tool.effect },
+			async run(args, call) {
+				const location = call.location;
+				const bot = oneBotOf(ctx, location?.platform, location?.selfId);
+				if (!bot) throw new Error("This tool only supports OneBot platform.");
+				try {
+					const result = await tool.run({
+						ctx,
+						bot,
+						guildId: location?.isDirect ? void 0 : location?.guild,
+						protocol: config.oneBotProtocol,
+						agent: call.agent
+					}, args);
+					log.debug("%s: %s", name, result);
+					return result;
+				} catch (error) {
+					const message = error instanceof Error ? error.message : String(error);
+					log.warn("%s failed: %s", name, message);
+					throw new Error(`${name} failed: ${message}`);
+				}
+			}
+		};
+	});
+}
+/**
+* 注册原生工具。工具对所有会话全局可见（v2 的工具管理页因此能列出并开关它们），
+* 再给不在 OneBot 上的 agent 挂一层排除过滤。
+*/
+function registerNativeTools(ctx, config, log) {
+	const definitions = nativeToolDefinitions(ctx, config, log);
+	for (const definition of definitions) ctx.tools.define(definition);
+	const exclude = definitions.map((definition) => definition.name);
+	log.info("native tools registered: %s", exclude.join(", "));
+	ctx.inject(["agents"], (inner) => {
+		const scope = (agent) => {
+			if (agent.options.location?.platform !== "onebot") inner.tools.filter({ exclude }, agent);
+		};
+		inner.on("chatluna/agent-open", ({ agent }) => scope(agent));
+		for (const agent of inner.agents.list()) scope(agent);
+	});
+}
+// external/onebot-toolbox/src/variables.ts
+const FALLBACK_MEMBER_ITEMS = ["nickname", "userId"];
+const SHUT_LIST_TIMEOUT_MS = 200;
+const SHUT_LIST_CACHE_TTL_MS = 15e3;
+function translateGender(value) {
+	if (value === "male") return "男";
+	if (value === "female") return "女";
+	return "";
+}
+function normalizeRole(value) {
+	if (value === "owner") return "群主";
+	if (value === "admin") return "管理员";
+	return !value || value === "member" ? "群员" : value;
+}
+/** 会话所在的 Satori 机器人，任意平台；预览等没有真实机器人的环境里为 undefined。 */
+function botOf(ctx, env) {
+	return ctx.satori.bots.find((bot) => bot.platform === env.platform && bot.selfId === env.selfId);
+}
+/** 查询群成员信息；私聊、找不到机器人或查询失败时为 undefined，变量照常按已知信息渲染。 */
+async function fetchMember(ctx, env, userId) {
+	const bot = botOf(ctx, env);
+	if (!bot || !env.guildId) return void 0;
+	try {
+		if (bot.platform === "onebot") return asRecord(await callOneBot(bot, "get_group_member_info", {
+			group_id: Number(env.guildId),
+			user_id: Number(userId),
+			no_cache: false
+		}));
+		const member = await bot.getGuildMember(env.guildId, userId);
+		return {
+			user_id: member.user?.id,
+			card: pickText(member.nick, member.name),
+			nickname: member.user?.name,
+			role: member.roles?.[0]?.id,
+			title: member.title,
+			join_time: member.joinedAt
+		};
+	} catch {
+		return;
+	}
+}
+/** 用户信息与机器人信息共用的渲染：按配置的信息项逐条输出，取不到的项省略。 */
+function renderMember(member, items, id, fallbackName) {
+	const values = [];
+	for (const item of items) switch (item) {
+		case "nickname": {
+			const name = pickText(member?.card, member?.nickname, fallbackName, id);
+			if (name) values.push(`name:${name}`);
+			break;
+		}
+		case "userId":
+			if (id) values.push(`id:${id}`);
+			break;
+		case "role":
+			values.push(`群内身份:${normalizeRole(pickText(member?.role))}`);
+			break;
+		case "level": {
+			const level = pickFirst(member?.level);
+			if (level !== void 0) values.push(`群等级:${level}`);
+			break;
+		}
+		case "title": {
+			const title = pickFirst(member?.title);
+			if (title !== void 0) values.push(`头衔:${title}`);
+			break;
+		}
+		case "gender": {
+			const gender = translateGender(member?.sex);
+			if (gender) values.push(`性别:${gender}`);
+			break;
+		}
+		case "age": {
+			const age = Number(member?.age);
+			if (Number.isFinite(age) && age > 0) values.push(`年龄:${age}`);
+			break;
+		}
+		case "area": {
+			const area = pickFirst(member?.area);
+			if (area !== void 0) values.push(`地区:${area}`);
+			break;
+		}
+		case "joinTime": {
+			const joinTime = formatDate(normalizeTimestamp(member?.join_time));
+			if (joinTime) values.push(`入群:${joinTime}`);
+			break;
+		}
+		case "lastSentTime": {
+			const lastSentTime = formatDateTime(normalizeTimestamp(member?.last_sent_time));
+			if (lastSentTime) values.push(`活跃:${lastSentTime}`);
+			break;
+		}
+	}
+	return values;
+}
+const itemsOf = (items) => items.length ? items : FALLBACK_MEMBER_ITEMS;
+function userInfoProvider(ctx, config) {
+	return async ({ env }) => {
+		const userId = (env.userId ?? env.message?.senderId)?.trim();
+		if (!userId) return "未知用户";
+		const values = renderMember(await fetchMember(ctx, env, userId), itemsOf(config.userInfo.items), userId, env.userName ?? env.message?.senderName);
+		return values.length ? values.join(", ") : `id:${userId}`;
+	};
+}
+function botInfoProvider(ctx, config) {
+	return async ({ env }) => {
+		const botId = env.selfId?.trim();
+		if (!botId) return "未知机器人";
+		const values = renderMember(await fetchMember(ctx, env, botId), itemsOf(config.botInfo.items), botId, void 0);
+		return values.length ? values.join(", ") : botId;
+	};
+}
+async function fetchRoles(bot, guildId, log) {
+	try {
+		const members = asMembers(await callOneBot(bot, "get_group_member_list", { group_id: Number(guildId) }));
+		if (!members.length) return void 0;
+		const owners = [];
+		const admins = [];
+		for (const member of members) {
+			const role = member.role;
+			const userId = pickText(member.user_id);
+			const name = pickText(member.card, member.nickname, userId);
+			const label = userId ? `${name}(${userId})` : name;
+			if (role === "owner") owners.push(label);
+			else if (role === "admin") admins.push(label);
+		}
+		return {
+			owners,
+			admins
+		};
+	} catch (error) {
+		log.debug("group roles lookup failed: %s", String(error));
+		return;
+	}
+}
+function renderGroupInfo(group, items, roles) {
+	const id = pickText(group.group_id);
+	const name = pickText(group.group_name);
+	const memberCount = group.member_count;
+	const createTime = formatDate(normalizeTimestamp(group.create_time ?? group.group_create_time));
+	const values = [];
+	for (const item of items) switch (item) {
+		case "groupName":
+			if (name) values.push(`群名：${name}`);
+			break;
+		case "groupId":
+			if (id) values.push(`群号：${id}`);
+			break;
+		case "memberCount":
+			if (memberCount !== void 0 && memberCount !== null) values.push(`成员数量：${String(memberCount)}`);
+			break;
+		case "createTime":
+			if (createTime) values.push(`创建时间：${createTime}`);
+			break;
+		case "ownerList":
+			if (roles) values.push(`群主：${roles.owners.length ? roles.owners.join("、") : "无"}`);
+			break;
+		case "adminList": if (roles) values.push(`管理员：${roles.admins.length ? roles.admins.join("、") : "无"}`);
+	}
+	return values.length ? values.join("\n") : id || name || "未能获取当前群信息。";
+}
+function groupInfoProvider(ctx, config, log) {
+	return async ({ env }) => {
+		if (!env.guildId) return "";
+		if (env.platform !== "onebot") return "当前平台暂不支持查询群信息。";
+		const bot = oneBotOf(ctx, env.platform, env.selfId);
+		if (!bot) return "暂无群信息。";
+		const items = config.groupInfo.items.length ? config.groupInfo.items : DEFAULT_GROUP_INFO_ITEMS;
+		const group = await callOneBot(bot, "get_group_info", {
+			group_id: Number(env.guildId),
+			no_cache: false
+		}).then(asRecord, () => void 0);
+		if (!group) return "未能获取当前群信息。";
+		return renderGroupInfo(group, items, items.includes("ownerList") || items.includes("adminList") ? await fetchRoles(bot, env.guildId, log) : void 0);
+	};
+}
+var ShutListTimeout = class extends Error {};
+function withTimeout(promise, ms) {
+	let timer;
+	return Promise.race([promise, new Promise((_, reject) => {
+		timer = setTimeout(() => reject(new ShutListTimeout("group shut list request timed out")), ms);
+	})]).finally(() => clearTimeout(timer));
+}
+async function fetchShutList(bot, guildId, protocol) {
+	const data = await withTimeout(callOneBot(bot, "get_group_shut_list", { group_id: protocol === "llbot" ? guildId : Number(guildId) }), SHUT_LIST_TIMEOUT_MS);
+	return Array.isArray(data) ? data : [];
+}
+function renderShutItem(item) {
+	const record = asRecord(item);
+	if (!record) return void 0;
+	const userId = pickText(record.uin, record.user_id);
+	if (!userId) return void 0;
+	return `id：${userId}，name：${pickText(record.cardName, record.remark, record.nick, record.nickname, userId)}，禁言截至：${formatDateTime(normalizeTimestamp(pickFirst(record.shutUpTime, record.shut_up_time))) || "未知"}`;
+}
+function groupShutListProvider(ctx, config, log) {
+	const cache = /* @__PURE__ */ new Map();
+	return async ({ env }) => {
+		if (!env.guildId) return "";
+		if (env.platform !== "onebot") return "当前平台暂不支持查询群禁言列表。";
+		const bot = oneBotOf(ctx, env.platform, env.selfId);
+		if (!bot) return "暂无群禁言列表。";
+		const key = `${env.selfId}:${env.guildId}`;
+		const cached = cache.get(key);
+		if (cached && cached.expiresAt > Date.now()) return cached.value;
+		try {
+			const lines = (await fetchShutList(bot, env.guildId, config.oneBotProtocol)).flatMap((item) => renderShutItem(item) ?? []);
+			const value = lines.length ? lines.join("\n") : "当前群暂无禁言成员。";
+			cache.set(key, {
+				value,
+				expiresAt: Date.now() + SHUT_LIST_CACHE_TTL_MS
+			});
+			return value;
+		} catch (error) {
+			log.debug("group shut list failed: %s", String(error));
+			return error instanceof ShutListTimeout ? "当前群暂无禁言成员。" : "获取群禁言列表失败。";
+		}
+	};
+}
+/** 按配置得到要注册的变量；变量名留空的不注册。 */
+function variableDefinitions(ctx, config, log) {
+	return [
+		[
+			config.userInfo.variableName,
+			"Current user info in this group",
+			userInfoProvider(ctx, config)
+		],
+		[
+			config.botInfo.variableName,
+			"Bot info in this group",
+			botInfoProvider(ctx, config)
+		],
+		[
+			config.groupInfo.variableName,
+			"Current group info",
+			groupInfoProvider(ctx, config, log)
+		],
+		[
+			config.groupShutList.variableName,
+			"Muted members of this group",
+			groupShutListProvider(ctx, config, log)
+		]
+	].filter(([name]) => name.trim()).map(([name, description, provider]) => [{
+		name: name.trim(),
+		description,
+		mutable: true
+	}, provider]);
+}
+function registerVariables(ctx, config, log) {
+	for (const [declaration, provider] of variableDefinitions(ctx, config, log)) try {
+		ctx.prompt.variable(declaration, provider);
+	} catch (error) {
+		log.warn("variable %s not registered: %s", declaration.name, error instanceof Error ? error.message : String(error));
+	}
+}
+// external/onebot-toolbox/src/index.ts
+const name = "chatluna-onebot-toolbox";
+/** 过滤工具用的 agents、唤醒用的 chat 与读取会话图片用的 chatluna_storage 是可选服务。 */
+const inject = [
+	"satori",
+	"tools",
+	"prompt"
+];
+function apply(ctx, config) {
+	const log = createLogger(ctx, config.debugLogging);
+	registerVariables(ctx, config, log);
+	registerNativeTools(ctx, config, log);
+	registerRequestNotices(ctx, config, log);
+}
+export { Config, DEFAULT_GROUP_INFO_ITEMS, DEFAULT_MEMBER_INFO_ITEMS, NATIVE_TOOLS, NATIVE_TOOL_KEYS, apply, inject, name };
+
+//# sourceMappingURL=index.js.map