koishi-plugin-adapter-debugger 0.1.0

package/lib/index.cjs

@@ -0,0 +1,190 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let koishi = require("koishi");
+//#region src/actions.ts
+/**
+* 当前可调试的 koishi 标准动作预设。
+*
+* 来源：koishi-plugin-adapter-napuketto 的 `NapukettoInternal` 实现的方法
+* （src/actions/internal.ts）。参数为 koishi 标准签名。
+*/
+const ACTION_PRESETS = [
+	{
+		method: "getSelf",
+		description: "获取登录账号自身信息",
+		argNames: [],
+		args: []
+	},
+	{
+		method: "sendMessage",
+		description: "发送消息（content 为字符串或元素数组）",
+		argNames: ["channelId", "content"],
+		args: ["{channelId}", "hello"]
+	},
+	{
+		method: "deleteMessage",
+		description: "撤回消息",
+		argNames: ["channelId", "messageId"],
+		args: ["{channelId}", ""]
+	},
+	{
+		method: "getMessageList",
+		description: "拉取消息历史",
+		argNames: ["channelId", "limit"],
+		args: ["{channelId}", 20]
+	},
+	{
+		method: "markAsRead",
+		description: "标记已读",
+		argNames: ["channelId"],
+		args: ["{channelId}"]
+	},
+	{
+		method: "getGroupList",
+		description: "群列表（数据来自 GroupCache）",
+		argNames: [],
+		args: []
+	},
+	{
+		method: "getFriendList",
+		description: "好友列表",
+		argNames: [],
+		args: []
+	}
+];
+/** 按方法名查找预设，找不到返回 undefined。 */
+function findPreset(method) {
+	return ACTION_PRESETS.find((preset) => preset.method === method);
+}
+/**
+* 执行一次 koishi 标准动作调用：
+* `bot.internal[method](...args)` → 适配器映射 → IPC action → kernel API。
+*
+* 参数组装：预设模板为基底，`rawParams`（命令行的 `key=value` 覆盖表）
+* 按 argNames 一一覆盖；`{channelId}` 占位符替换为当前会话频道。
+*/
+async function runAction(ctx, bot, method, rawParams, channelId) {
+	const preset = findPreset(method);
+	const args = preset ? [...preset.args] : [];
+	preset?.argNames.forEach((name, index) => {
+		if (name in rawParams) args[index] = rawParams[name];
+	});
+	if (channelId) args.forEach((arg, index) => {
+		if (typeof arg === "string") args[index] = arg.replaceAll("{channelId}", channelId);
+	});
+	const internal = bot.internal;
+	const fn = internal?.[method];
+	if (typeof fn !== "function") return {
+		ok: false,
+		method,
+		elapsedMs: 0,
+		error: `适配器未实现 koishi 标准方法 ${method}（bot.internal.${method} 不是函数）`
+	};
+	ctx.logger("tools").debug(`[adbg] 调用 bot.internal.${method}`, args);
+	const startedAt = Date.now();
+	try {
+		const value = await fn.apply(internal, args);
+		return {
+			ok: true,
+			method,
+			elapsedMs: Date.now() - startedAt,
+			value
+		};
+	} catch (error) {
+		ctx.logger("tools").error(`[adbg] bot.internal.${method} 调用失败`, error);
+		return {
+			ok: false,
+			method,
+			elapsedMs: Date.now() - startedAt,
+			error: error instanceof Error ? error.message : String(error)
+		};
+	}
+}
+//#endregion
+//#region src/index.ts
+const name = "adapter-debugger";
+const usage = `
+<div style="border-radius: 10px; border: 1px solid #ddd; padding: 16px; margin-bottom: 20px; box-shadow: 0 2px 5px rgba(0,0,0,0.1);">
+  <h2 style="margin-top: 0; color: #4a6ee0;">🛠️ 适配器协议调试器</h2>
+  <p>🔌 针对 <strong>NapukettoQQ</strong> 适配器（<code>koishi-plugin-adapter-napuketto</code>）的标准动作诊断工具</p>
+  <p>🧪 调用 koishi 标准 <code>bot.internal</code> 方法，逐一验证适配器 → IPC → kernel 链路是否可用</p>
+  <p>⚠️ 仅适用于 <strong>napuketto</strong> 平台，调试工具请谨慎授权</p>
+</div>
+
+<div style="border-radius: 10px; border: 1px solid #ddd; padding: 16px; margin-bottom: 20px; box-shadow: 0 2px 5px rgba(0,0,0,0.1);">
+  <h2 style="margin-top: 0; color: #e0574a;">⚡ 命令</h2>
+  <ul>
+    <li><code>adbg.list</code> — 列出已收录的标准动作及参数模板</li>
+    <li><code>adbg.run &lt;method&gt; [key=value ...]</code> — 调用指定标准方法并展示耗时与结果</li>
+  </ul>
+</div>
+
+<div style="border-radius: 10px; border: 1px solid #ddd; padding: 16px; margin-bottom: 20px; box-shadow: 0 2px 5px rgba(0,0,0,0.1);">
+  <h2 style="margin-top: 0; color: #4a6ee0;">🧩 已收录方法</h2>
+  <ul>
+    <li><code>getSelf</code> — 登录账号自身信息</li>
+    <li><code>sendMessage</code> — 发送消息</li>
+    <li><code>deleteMessage</code> — 撤回消息</li>
+    <li><code>getMessageList</code> — 拉取消息历史</li>
+    <li><code>markAsRead</code> — 标记已读</li>
+    <li><code>getGroupList</code> — 群列表</li>
+    <li><code>getFriendList</code> — 好友列表</li>
+  </ul>
+  <p>📌 方法清单对应 adapter 的 <code>NapukettoInternal</code> 实现，随 adapter 扩充同步更新</p>
+</div>
+`;
+const Config = koishi.Schema.object({
+	minAuthority: koishi.Schema.number().default(3).min(0).max(5).step(1).description("使用调试指令所需的最低用户权限等级（0-5）。默认 3。"),
+	timeout: koishi.Schema.number().default(15e3).min(1e3).step(1e3).description("单次 action 调用超时（毫秒）。默认 15000。"),
+	maxOutputLength: koishi.Schema.number().default(1500).min(200).step(100).description("结果文本最大长度，超出部分省略。默认 1500。")
+});
+/**
+* 获取 napuketto 平台的可调试 bot（koishi 上下文 API：ctx.bots 遍历）。
+* 优先取当前会话所在 bot；否则取第一个 napuketto bot。
+*/
+function getDebugBot(ctx, session) {
+	const bots = ctx.bots;
+	if (!bots) return null;
+	const candidates = [...bots.values()].filter((bot) => bot.platform === "onebot");
+	if (candidates.length === 0) return null;
+	const current = session?.bot;
+	return current?.platform === "onebot" ? current : candidates[0];
+}
+/** 将结果对象渲染为聊天文本（含耗时），并截断超长输出。 */
+function renderResult(result, maxLength) {
+	const text = `${result.ok ? `✅ 调用成功（耗时 ${result.elapsedMs}ms）` : `❌ 调用失败（耗时 ${result.elapsedMs}ms）`}\n${result.ok ? JSON.stringify(result.value, null, 2) : `错误：${result.error}`}`;
+	return text.length > maxLength ? `${text.slice(0, maxLength)}\n…（已截断，完整输出见日志）` : text;
+}
+/** 渲染标准动作预设清单。 */
+function renderPresetList(presets) {
+	return presets.map((preset) => preset.method).join("\n");
+}
+function apply(ctx, config) {
+	ctx.logger("tools").info("adapter-debugger 插件已加载");
+	ctx.command("adbg.list", "列出 NapukettoQQ 适配器的标准动作及参数模板", { authority: config.minAuthority }).action(async ({ session }) => {
+		if (!session) return "无法获取会话信息。";
+		if (session.platform !== "onebot") return "该指令仅支持 napuketto 平台。";
+		return renderPresetList(ACTION_PRESETS);
+	});
+	ctx.command("adbg.run <method:string> [params...]", "调用 NapukettoQQ 适配器的标准动作", { authority: config.minAuthority }).action(async ({ session }, method, ...tokens) => {
+		if (!session) return "无法获取会话信息。";
+		if (session.platform !== "onebot") return "该指令仅支持 napuketto 平台。";
+		const bot = getDebugBot(ctx, session);
+		if (!bot) return "未找到可用的 napuketto bot。";
+		const params = {};
+		for (const token of tokens) {
+			const separator = token.indexOf("=");
+			if (separator === -1) return `无效参数：${token}（应为 key=value 形式）`;
+			const key = token.slice(0, separator);
+			const raw = token.slice(separator + 1);
+			if (/^-?\d+$/.test(raw)) params[key] = Number(raw);
+			else if (raw === "true" || raw === "false") params[key] = raw === "true";
+			else params[key] = raw;
+		}
+		return renderResult(await runAction(ctx, bot, method, params, session.channelId), config.maxOutputLength);
+	});
+}
+//#endregion
+exports.Config = Config;
+exports.apply = apply;
+exports.name = name;
+exports.usage = usage;

package/lib/index.d.ts

@@ -0,0 +1,20 @@
+import { Context, Schema } from "koishi";
+//#region src/index.d.ts
+declare const name = "adapter-debugger";
+declare const usage = "\n<div style=\"border-radius: 10px; border: 1px solid #ddd; padding: 16px; margin-bottom: 20px; box-shadow: 0 2px 5px rgba(0,0,0,0.1);\">\n  <h2 style=\"margin-top: 0; color: #4a6ee0;\">🛠️ 适配器协议调试器</h2>\n  <p>🔌 针对 <strong>NapukettoQQ</strong> 适配器（<code>koishi-plugin-adapter-napuketto</code>）的标准动作诊断工具</p>\n  <p>🧪 调用 koishi 标准 <code>bot.internal</code> 方法，逐一验证适配器 → IPC → kernel 链路是否可用</p>\n  <p>⚠️ 仅适用于 <strong>napuketto</strong> 平台，调试工具请谨慎授权</p>\n</div>\n\n<div style=\"border-radius: 10px; border: 1px solid #ddd; padding: 16px; margin-bottom: 20px; box-shadow: 0 2px 5px rgba(0,0,0,0.1);\">\n  <h2 style=\"margin-top: 0; color: #e0574a;\">⚡ 命令</h2>\n  <ul>\n    <li><code>adbg.list</code> — 列出已收录的标准动作及参数模板</li>\n    <li><code>adbg.run &lt;method&gt; [key=value ...]</code> — 调用指定标准方法并展示耗时与结果</li>\n  </ul>\n</div>\n\n<div style=\"border-radius: 10px; border: 1px solid #ddd; padding: 16px; margin-bottom: 20px; box-shadow: 0 2px 5px rgba(0,0,0,0.1);\">\n  <h2 style=\"margin-top: 0; color: #4a6ee0;\">🧩 已收录方法</h2>\n  <ul>\n    <li><code>getSelf</code> — 登录账号自身信息</li>\n    <li><code>sendMessage</code> — 发送消息</li>\n    <li><code>deleteMessage</code> — 撤回消息</li>\n    <li><code>getMessageList</code> — 拉取消息历史</li>\n    <li><code>markAsRead</code> — 标记已读</li>\n    <li><code>getGroupList</code> — 群列表</li>\n    <li><code>getFriendList</code> — 好友列表</li>\n  </ul>\n  <p>📌 方法清单对应 adapter 的 <code>NapukettoInternal</code> 实现，随 adapter 扩充同步更新</p>\n</div>\n";
+interface Config {
+  /**
+   * 使用调试指令所需的最低用户权限等级。
+   * Koishi 默认权限：0 未授权，1 普通用户，2 管理员，3 超管，4+ 自定义。
+   */
+  minAuthority: number;
+  /** 单次 action 调用超时（毫秒）。 */
+  timeout: number;
+  /** 结果文本最大长度（超出截断）。 */
+  maxOutputLength: number;
+}
+declare const Config: Schema<Config>;
+declare function apply(ctx: Context, config: Config): void;
+//#endregion
+export { Config, apply, name, usage };
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;cAsBa;cAEA;UA+BI;;;;;EAKb;;EAEA;;EAEA;;cAGS,QAAQ,OAAO;iBAyDZ,MAAM,KAAK,SAAS,QAAQ"}

package/package.json

@@ -0,0 +1,48 @@
+{
+    "name": "koishi-plugin-adapter-debugger",
+    "version": "0.1.0",
+    "description": "调试 NapukettoQQ 适配器的协议 action（逐一验证是否可用）",
+    "contributors": [
+        "Oppenheymu <oppenheymu@gmail.com>"
+    ],
+    "main": "lib/index.cjs",
+    "types": "lib/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./lib/index.d.ts",
+            "development": "./src/index.ts",
+            "default": "./lib/index.cjs"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "lib"
+    ],
+    "license": "MIT",
+    "publishConfig": {
+        "access": "public"
+    },
+    "keywords": [
+        "chatbot",
+        "koishi",
+        "plugin",
+        "napuketto",
+        "debugger",
+        "adapter"
+    ],
+    "scripts": {
+        "build": "pnpm --dir ../.. exec tsdown -W -F koishi-plugin-adapter-debugger",
+        "typecheck": "tsc --noEmit"
+    },
+    "peerDependencies": {
+        "koishi": "^4.17.4"
+    },
+    "koishi": {
+        "description": {
+            "en": "Debug & test NapukettoQQ adapter protocol actions",
+            "zh": "调试 NapukettoQQ 适配器的协议 action（逐一验证是否可用）"
+        },
+        "service": {}
+    },
+    "type": "module"
+}

package/readme.md

@@ -0,0 +1,33 @@
+# koishi-plugin-adapter-debugger
+
+调试 [koishi-plugin-adapter-napuketto](https://github.com/Oppenheymu/koishi-plugin-adapter-napuketto) 协议 action 的诊断插件。
+
+## 用途
+
+NapukettoQQ 适配器通过 `bot.internal._request(action, params)` 走 IPC 调用 kernel API。
+本插件用于在真实运行环境中逐一验证这些协议 action 是否可用、返回什么数据、报什么错。
+
+## 已收录的 action（IPC 动作表）
+
+来源：`NapukettoQQ/packages/loader/src/host/ipc/ipc-actions.ts`
+
+| action | 说明 |
+| --- | --- |
+| `login.getSelf` | 登录账号自身信息 |
+| `msg.sendMessage` | 发送消息（canonical elements） |
+| `msg.recallMessage` | 撤回消息 |
+| `msg.fetchMessages` | 拉取消息历史 |
+| `msg.markRead` | 标记已读 |
+| `group.getGroupList` | 群列表 |
+| `friend.getFriendList` | 好友列表 |
+
+## 开发
+
+```bash
+pnpm build   # tsc -b 编译
+```
+
+TODO：
+- [ ] `adbg.list` — 列出已知 action 与参数模板
+- [ ] `adbg.run <action> [key=value ...]` — 执行任意 action 并展示耗时/结果/错误
+- [ ] 错误码解析（NOT_FOUND / TIMEOUT / CLOSED / kernel 错误码）