@napuketto/adapter 0.0.1 → 0.0.3

package/dist/satori/index.mjs

@@ -0,0 +1,1891 @@
+import { a as ActionRegistry, n as BaseProtocolAdapter } from "../core-Bj5L8WeZ.mjs";
+import { i as createWsServerSchema, n as collectGrayTipUids, r as createHttpServerSchema, t as forEachRawMessage } from "../raw-message-Du7tvR1D.mjs";
+import { ChatType, GrayTipSubType, NTGroupRequestOperateTypes, TipGroupElementType, isKernelError, kernelError, toCanonicalElements } from "@napuketto/kernel";
+import { z } from "zod";
+import { join } from "node:path";
+import { HttpServer, WsServer } from "@napuketto/network";
+import { mkdir, open, writeFile } from "node:fs/promises";
+import { encodePcmToSilk } from "@napuketto/media";
+//#region src/satori/helper/config.ts
+/**
+* Satori 协议配置（zod schema，归属本包，ADR-012）
+* 协议配置 schema 在各自协议包，kernel 只提供 ConfigBase 基类。
+*/
+/** HTTP RPC 服务器默认端口（satori.chat 惯例 5500 区间，取 5500）。 */
+const DEFAULT_HTTP_PORT = 5500;
+/** WS 事件服务默认端口（satori.chat 惯例 5500 区间，取 5501）。 */
+const DEFAULT_WS_PORT = 5501;
+/** HTTP RPC 服务器实例（POST /v1/{resource}.{method}）。 */
+const httpServerSchema = createHttpServerSchema(DEFAULT_HTTP_PORT);
+/** WS 事件服务实例（/v1/events 信令，第三方 SDK 连入）。 */
+const wsServerSchema = createWsServerSchema(DEFAULT_WS_PORT);
+/** Satori 配置 schema。 */
+const satoriConfigSchema = z.object({
+	/** 鉴权 token（全局默认，实例未指定时继承）。 */
+	token: z.string().optional(),
+	/** 媒体资源（img/audio/video/file）下载缓存目录。 */
+	cacheDir: z.string().optional(),
+	/** HTTP RPC 服务器列表。 */
+	httpServers: z.array(httpServerSchema).default([]),
+	/** WS 事件服务列表。 */
+	wsServers: z.array(wsServerSchema).default([])
+});
+//#endregion
+//#region src/satori/helper/error.ts
+/** KernelErrorCode → HTTP 状态码映射表。 */
+const satoriHttpStatusMap = {
+	SEND_FAILED: 500,
+	PERMISSION_DENIED: 403,
+	NOT_FOUND: 404,
+	TIMEOUT: 500,
+	NOT_LOGIN: 403,
+	INVALID_PARAM: 400,
+	INVALID_STATE: 500,
+	UNKNOWN: 500
+};
+/** HTTP 状态码常量。 */
+const HTTP_STATUS = {
+	ok: 200,
+	badRequest: 400,
+	unauthorized: 401,
+	forbidden: 403,
+	notFound: 404,
+	notImplemented: 501,
+	serverError: 500
+};
+/** 适配器名（固定 napuketto）。 */
+const ADAPTER = "napuketto";
+/** 平台特性（API 可用性判断；群聊频道与群组重合 → guild.plain）。 */
+const FEATURES = ["guild.plain", "message.list.from"];
+/** 构造用户（uin）。 */
+function toUser(id, name, nick) {
+	const user = { id };
+	if (name !== void 0 && name !== "") user.name = name;
+	if (nick !== void 0 && nick !== "") user.nick = nick;
+	return user;
+}
+/** 构造群聊频道（id = 群号）。 */
+function toGroupChannel(groupCode, name) {
+	const channel = {
+		id: String(groupCode),
+		type: 0
+	};
+	if (name !== void 0 && name !== "") channel.name = name;
+	return channel;
+}
+/** 构造私聊频道（id = 对端 uin）。 */
+function toDirectChannel(uin, name) {
+	const channel = {
+		id: String(uin),
+		type: 1
+	};
+	if (name !== void 0 && name !== "") channel.name = name;
+	return channel;
+}
+/** 构造群组（id = 群号）。 */
+function toGuild(groupCode, name, avatar) {
+	const guild = { id: String(groupCode) };
+	if (name !== void 0 && name !== "") guild.name = name;
+	if (avatar !== void 0 && avatar !== "") guild.avatar = avatar;
+	return guild;
+}
+/** 构造登录信息（login.get / READY logins）。 */
+function toLogin(self, sn, online) {
+	return {
+		sn,
+		platform: "qq",
+		user: toUser(self.uin, self.nickname),
+		status: online ? 1 : 0,
+		adapter: ADAPTER,
+		features: [...FEATURES]
+	};
+}
+/** 构造非登录事件的最小 login（只带 sn/user/platform，规范）。 */
+function toMinimalLogin(sn, selfUin) {
+	return {
+		sn,
+		platform: "qq",
+		user: toUser(selfUin),
+		status: 1,
+		adapter: ADAPTER
+	};
+}
+//#endregion
+//#region src/satori/helper/element/canonical.ts
+/** 收集 at uid → 批量 uidToUin（失败不阻塞，at 原样 uid）。 */
+async function resolveAtUids(elements, uidToUin) {
+	const atUids = [];
+	for (const el of elements) if (el.type === "at" && el.target !== "all") atUids.push(el.target);
+	if (atUids.length === 0 || uidToUin === void 0) return /* @__PURE__ */ new Map();
+	try {
+		return await uidToUin([...new Set(atUids)]);
+	} catch {
+		return /* @__PURE__ */ new Map();
+	}
+}
+/** canonical at → Satori at（uid → uin，name = display）。 */
+function atToSatori(el, uinMap) {
+	if (el.target === "all") return {
+		type: "at",
+		attrs: { id: "all" }
+	};
+	const attrs = { id: uinMap.get(el.target) ?? el.target };
+	if (el.display !== void 0 && el.display !== "") attrs["name"] = el.display;
+	return {
+		type: "at",
+		attrs
+	};
+}
+/** canonical file → Satori file（title = name）。 */
+function fileToSatori(el) {
+	const attrs = { src: el.path };
+	if (el.name !== void 0 && el.name !== "") attrs["title"] = el.name;
+	return {
+		type: "file",
+		attrs
+	};
+}
+/** canonical forward → Satori message（取首个消息 id）。 */
+function forwardToSatori(el) {
+	const first = el.messageIds[0];
+	if (first === void 0 || first === "") return null;
+	return {
+		type: "message",
+		attrs: {
+			forward: "",
+			id: first
+		}
+	};
+}
+/** 单个 canonical → Satori（null = 宽容忽略，如 json/xml/unknown）。 */
+function canonicalToSatori(el, uinMap) {
+	switch (el.type) {
+		case "text": return el.text === "" ? null : {
+			type: "text",
+			text: el.text
+		};
+		case "at": return atToSatori(el, uinMap);
+		case "image": return {
+			type: "img",
+			attrs: { src: el.url ?? el.path }
+		};
+		case "face": return {
+			type: "emoji",
+			attrs: { id: el.id }
+		};
+		case "voice": return {
+			type: "audio",
+			attrs: { src: el.path }
+		};
+		case "video": return {
+			type: "video",
+			attrs: { src: el.url ?? el.path }
+		};
+		case "file": return fileToSatori(el);
+		case "reply": return {
+			type: "quote",
+			attrs: { id: el.messageId }
+		};
+		case "forward": return forwardToSatori(el);
+		case "json":
+		case "xml":
+		case "unknown": return null;
+	}
+}
+/**
+* 收方向：kernel canonical 元素 → Satori 元素树（纯函数映射，宽容忽略 unknown）。
+* at 目标为 uid 时经 uidToUin 转换（异步）；无转换器时原样。
+*/
+async function canonicalToSatoriElements(elements, deps = {}) {
+	const uinMap = await resolveAtUids(elements, deps.uidToUin);
+	const out = [];
+	for (const el of elements) {
+		const converted = canonicalToSatori(el, uinMap);
+		if (converted !== null) out.push(converted);
+	}
+	return out;
+}
+//#endregion
+//#region src/satori/helper/element/parse-tag.ts
+/**
+* Satori 标签读取（元素名 / 属性解析，从 element.ts 拆分，2026-08-08 FTA 优化）
+*
+* - decodeEntity/decodeEntities：命名/十进制/十六进制实体解码（属性值用）
+* - readTagName：读取元素名（小写字母/数字/连字符，以字母开头）
+* - readTagAttrs / readAttr / skipSpaces：标签属性区解析（无值属性 / 引号值 / 无引号值）
+* - readTag：完整标签（名 + 属性 + 自闭合指示）
+*/
+/** 命名实体（规范规定的四个 + apos 宽容）。 */
+const NAMED_ENTITIES = {
+	quot: "\"",
+	amp: "&",
+	lt: "<",
+	gt: ">",
+	apos: "'"
+};
+/** 解码单个实体（命名/十进制/十六进制）。 */
+function decodeEntity(body) {
+	const named = NAMED_ENTITIES[body];
+	if (named !== void 0) return named;
+	if (body.startsWith("#x") || body.startsWith("#X")) {
+		const code = Number.parseInt(body.slice(2), 16);
+		if (Number.isInteger(code)) return String.fromCodePoint(code);
+	}
+	if (body.startsWith("#")) {
+		const code = Number.parseInt(body.slice(1), 10);
+		if (Number.isInteger(code)) return String.fromCodePoint(code);
+	}
+	return `&${body};`;
+}
+/** 解码字符串中的全部实体。 */
+function decodeEntities(input) {
+	return input.replace(/&([^;]+);/g, (_full, body) => decodeEntity(body));
+}
+/** 元素名：小写字母/数字/连字符，以字母开头（规范）。 */
+const NAME_RE = /^[a-z][a-z0-9-]*/i;
+/** 读取元素名（pos 起）；未匹配返回空名。 */
+function readTagName(source, pos) {
+	const rest = source.slice(pos);
+	const m = NAME_RE.exec(rest);
+	if (m === null) return {
+		name: "",
+		end: pos
+	};
+	return {
+		name: m[0],
+		end: pos + m[0].length
+	};
+}
+/** 跳过空白；返回下一个非空白位置。 */
+function skipSpaces(source, start) {
+	let i = start;
+	while (i < source.length && /\s/.test(source.charAt(i))) i += 1;
+	return i;
+}
+/** 读取单个属性（名 / = / 值 / 无值属性），更新 attrs，返回下一个位置。 */
+function readAttr(source, start, attrs) {
+	const keyMatch = /^[a-zA-Z0-9:_-]+/.exec(source.slice(start));
+	if (keyMatch === null) return start + 1;
+	const key = keyMatch[0];
+	let i = skipSpaces(source, start + key.length);
+	if (source.charAt(i) !== "=") {
+		attrs[key] = "";
+		return i;
+	}
+	i = skipSpaces(source, i + 1);
+	const quote = source.charAt(i);
+	if (quote === "\"" || quote === "'") {
+		i += 1;
+		const valueStart = i;
+		while (i < source.length && source.charAt(i) !== quote) i += 1;
+		attrs[key] = decodeEntities(source.slice(valueStart, i));
+		if (i < source.length) i += 1;
+	} else {
+		const valueStart = i;
+		while (i < source.length && !/[\s>]/.test(source.charAt(i))) i += 1;
+		attrs[key] = decodeEntities(source.slice(valueStart, i));
+	}
+	return i;
+}
+/** 读取标签属性区（到 > 或 /> 为止），返回属性表与闭合指示、结束位置。 */
+function readTagAttrs(source, start) {
+	const attrs = {};
+	let i = start;
+	let selfClosing = false;
+	while (i < source.length) {
+		const ch = source.charAt(i);
+		if (ch === ">") {
+			i += 1;
+			break;
+		}
+		if (ch === "/") {
+			if (source.charAt(i + 1) === ">") {
+				selfClosing = true;
+				i += 2;
+				break;
+			}
+			i += 1;
+			continue;
+		}
+		if (/\s/.test(ch)) {
+			i += 1;
+			continue;
+		}
+		i = readAttr(source, i, attrs);
+	}
+	return {
+		attrs,
+		selfClosing,
+		end: i
+	};
+}
+/** 读取完整标签（元素名 + 属性 + 闭合指示），返回属性表与结束位置。 */
+function readTag(source, pos) {
+	const { name, end } = readTagName(source, pos);
+	if (name === "") return {
+		name: "",
+		attrs: {},
+		selfClosing: false,
+		end: pos
+	};
+	const { attrs, selfClosing, end: attrEnd } = readTagAttrs(source, end);
+	return {
+		name,
+		attrs,
+		selfClosing,
+		end: attrEnd
+	};
+}
+//#endregion
+//#region src/satori/helper/element/element.ts
+/**
+* Satori 消息元素解析/渲染（协议 v1，自研实现，规范参考 satori.chat/zh-CN/protocol/message.html）
+*
+* - parseElements：XML 风格字符串 → 元素树（注释/转义/无值属性/未配对标签容错）
+* - renderElements：元素树 → 字符串（消息 content 序列化）
+*
+* canonical ↔ Satori 双向转换不在本文件：收方向（canonical → Satori）在
+* canonical.ts，发方向（Satori → canonical）在 element-convert.ts，调用方直引。
+*
+* 语法要点（对齐规范）：
+* - 转义：&quot; &amp; &lt; &gt; &#39; &#x27; 与十进制/十六进制数字实体
+* - 注释 <!-- --> 不渲染
+* - 无值属性（key）与 key="value" / key='value' 均合法
+* - 未配对的标签视为文本内容的一部分
+* - 文本内容前后包含换行符的连续空白会被忽略
+*/
+/** 文本转义（& < >）。 */
+function encodeText(input) {
+	return input.replace(/[&<>]/g, (ch) => {
+		if (ch === "&") return "&amp;";
+		if (ch === "<") return "&lt;";
+		return "&gt;";
+	});
+}
+/** 属性值转义（& " < >）。 */
+function encodeAttr(input) {
+	return input.replace(/[&"<>]/g, (ch) => {
+		if (ch === "&") return "&amp;";
+		if (ch === "\"") return "&quot;";
+		if (ch === "<") return "&lt;";
+		return "&gt;";
+	});
+}
+/**
+* 文本规范化：开头/结尾的「包含换行符的连续空白」被忽略（规范），
+* 中间的空白与不含换行的首尾空白保留。
+*/
+function normalizeText(raw) {
+	const leading = /^\s+/.exec(raw);
+	const trailing = /\s+$/.exec(raw);
+	let out = raw;
+	if (leading !== null && /[\r\n]/.test(leading[0])) out = out.slice(leading[0].length);
+	if (trailing !== null && /[\r\n]/.test(trailing[0])) out = out.slice(0, -trailing[0].length);
+	return out;
+}
+/** Satori 消息解析器状态（挂载点 / 文本缓冲 / 栈管理，拆分主循环复杂度）。 */
+var ElementParser = class {
+	root = [];
+	stack = [];
+	text = "";
+	/** 当前挂载数组（栈顶元素 children 或根数组）。 */
+	mountPoint() {
+		const top = this.stack[this.stack.length - 1];
+		if (top === void 0) return this.root;
+		top.children ??= [];
+		return top.children;
+	}
+	/** 归一化文本落位到当前挂载点。 */
+	pushText() {
+		const normalized = normalizeText(this.text);
+		this.text = "";
+		if (normalized !== "") this.mountPoint().push({
+			type: "text",
+			text: normalized
+		});
+	}
+	/** 解析完成的元素树。 */
+	get elements() {
+		return this.root;
+	}
+	/** 追加原始文本（解析间隙累积）。 */
+	appendRaw(raw) {
+		this.text += raw;
+	}
+	/** 起始/自闭合标签落位（压栈或仅挂载）。 */
+	openTag(name, attrs, selfClosing) {
+		const el = {
+			type: name,
+			attrs
+		};
+		this.mountPoint().push(el);
+		if (!selfClosing) this.stack.push(el);
+	}
+	/** 收尾：剩余文本落位（栈剩余未闭合元素：文本落在栈顶元素内，宽容）。 */
+	flush() {
+		this.pushText();
+	}
+	/** 注释：返回跳过后的位置；-1 = 未闭合终止解析（注释不渲染）。 */
+	skipComment(source, pos) {
+		const end = source.indexOf("-->", pos);
+		return end === -1 ? -1 : end + 3;
+	}
+	/**
+	* 结束标签：匹配栈顶则闭合，否则按文本保留。
+	* @returns 下一个解析位置；-1 = 终止解析。
+	*/
+	closeTag(source, lt, slashPos) {
+		const { name, end } = readTagName(source, slashPos + 1);
+		if (name === "") {
+			this.text += "<";
+			return lt + 1;
+		}
+		const gt = source.indexOf(">", end);
+		if (gt === -1) {
+			this.text += source.slice(lt);
+			return -1;
+		}
+		const top = this.stack[this.stack.length - 1];
+		if (top !== void 0 && top.type === name) {
+			this.pushText();
+			this.stack.pop();
+		} else this.text += source.slice(lt, gt + 1);
+		return gt + 1;
+	}
+};
+/**
+* 解析 Satori 消息字符串 → 元素树。
+* 容错：未配对标签/非法标签按文本保留；解析不抛错（消息内容宽容）。
+*/
+function parseElements(source) {
+	const parser = new ElementParser();
+	let i = 0;
+	while (i < source.length) {
+		const lt = source.indexOf("<", i);
+		if (lt === -1) {
+			parser.appendRaw(source.slice(i));
+			break;
+		}
+		parser.appendRaw(source.slice(i, lt));
+		i = lt + 1;
+		if (source.startsWith("!--", i)) {
+			const next = parser.skipComment(source, i);
+			if (next === -1) break;
+			i = next;
+			continue;
+		}
+		if (source.startsWith("/", i)) {
+			const next = parser.closeTag(source, lt, i);
+			if (next === -1) break;
+			i = next;
+			continue;
+		}
+		const tag = readTag(source, i);
+		if (tag.name === "") {
+			parser.appendRaw("<");
+			continue;
+		}
+		parser.pushText();
+		parser.openTag(tag.name, tag.attrs, tag.selfClosing);
+		i = tag.end;
+	}
+	parser.flush();
+	return parser.elements;
+}
+/** 元素树 → Satori 消息字符串。 */
+function renderElements(elements) {
+	let out = "";
+	for (const el of elements) {
+		if (el.type === "text") {
+			out += encodeText(el.text ?? "");
+			continue;
+		}
+		out += renderElement(el);
+	}
+	return out;
+}
+/** 渲染单个元素（含子元素递归）。 */
+function renderElement(el) {
+	let attrs = "";
+	for (const [key, value] of Object.entries(el.attrs ?? {})) if (value === "") attrs += ` ${key}`;
+	else attrs += ` ${key}="${encodeAttr(value)}"`;
+	const children = el.children ?? [];
+	if (children.length === 0) return `<${el.type}${attrs}/>`;
+	const inner = renderElements(children);
+	return `<${el.type}${attrs}>${inner}</${el.type}>`;
+}
+//#endregion
+//#region src/satori/helper/element/asset.ts
+/**
+* Satori 发方向资源处理（从 element-convert.ts 拆分，2026-08-08 FTA 优化）
+*
+* - resolveAsset：internal: 路径 / http(s) 下载 / 本地路径原样
+* - ensureSilk：非 silk 语音（wav/pcm）转 silk（QQ 语音格式，失败原样返回）
+*/
+/** internal:{platform}/{user.id}/{path} → 本地路径（取 _tmp 之后的路径，回落 cacheDir）。 */
+function resolveInternalPath(src) {
+	const pathPart = src.slice(9);
+	const slash1 = pathPart.indexOf("/");
+	const slash2 = slash1 === -1 ? -1 : pathPart.indexOf("/", slash1 + 1);
+	if (slash2 === -1) return pathPart;
+	const rest = pathPart.slice(slash2 + 1);
+	const tmpIdx = rest.indexOf("_tmp/");
+	return tmpIdx === -1 ? rest : rest.slice(tmpIdx + 5);
+}
+/**
+* 解析资源 src：
+* - internal:{platform}/{user.id}/{path} → 本地路径（第一版仅支持 _tmp 保留路径）
+* - http(s):// → 下载到 cacheDir
+* - 其他 → 视为本地路径原样返回
+*/
+async function resolveAsset(src, cacheDir) {
+	if (src.startsWith("internal:")) return resolveInternalPath(src);
+	if (/^https?:\/\//i.test(src)) return downloadAsset(src, cacheDir);
+	return src;
+}
+/** 下载 URL 资源到缓存目录（返回本地路径）。 */
+async function downloadAsset(url, cacheDir) {
+	await mkdir(cacheDir, { recursive: true });
+	const res = await fetch(url);
+	if (!res.ok) throw kernelError(`下载资源失败: ${url}`, "SEND_FAILED");
+	const buf = Buffer.from(await res.arrayBuffer());
+	const safeName = (url.split("/").pop() ?? `asset-${Date.now()}`).replace(/[^a-zA-Z0-9._-]/g, "_") || `asset-${Date.now()}`;
+	const filePath = join(cacheDir, safeName);
+	await writeFile(filePath, buf);
+	return filePath;
+}
+/** 语音转码：非 silk 输入（wav/pcm）转 silk（QQ 语音格式）。 */
+async function ensureSilk(path) {
+	try {
+		if ((await readFileHead(path)).startsWith("#!SILK")) return path;
+		return await encodePcmToSilk(path);
+	} catch {
+		return path;
+	}
+}
+/** 读文件头 8 字节（判断格式）。 */
+async function readFileHead(path) {
+	const handle = await open(path, "r");
+	try {
+		const buf = Buffer.alloc(8);
+		await handle.read(buf, 0, 8, 0);
+		return buf.toString("utf8");
+	} finally {
+		await handle.close();
+	}
+}
+//#endregion
+//#region src/satori/helper/element/media-convert.ts
+/** 解析元素媒体 src（空 → null 忽略），返回本地路径。 */
+async function resolveMediaSrc(el, deps) {
+	const src = el.attrs?.["src"] ?? "";
+	if (src === "") return null;
+	return resolveAsset(src, deps.cacheDir);
+}
+/** Satori img → canonical image。 */
+async function imgToCanonical(el, deps) {
+	const path = await resolveMediaSrc(el, deps);
+	return path === null ? [] : [{
+		type: "image",
+		path
+	}];
+}
+/** Satori audio → canonical voice（非 silk 转码）。 */
+async function audioToCanonical(el, deps) {
+	const path = await resolveMediaSrc(el, deps);
+	return path === null ? [] : [{
+		type: "voice",
+		path: await ensureSilk(path)
+	}];
+}
+/** Satori video → canonical video。 */
+async function videoToCanonical(el, deps) {
+	const path = await resolveMediaSrc(el, deps);
+	return path === null ? [] : [{
+		type: "video",
+		path
+	}];
+}
+/** Satori file → canonical file（title → name）。 */
+async function fileToCanonical(el, deps) {
+	const path = await resolveMediaSrc(el, deps);
+	if (path === null) return [];
+	const title = el.attrs?.["title"];
+	const base = {
+		type: "file",
+		path
+	};
+	if (title !== void 0 && title !== "") return [{
+		...base,
+		name: title
+	}];
+	return [base];
+}
+/** 媒体元素转换器子表（并入 element-convert 主表）。 */
+const MEDIA_CONVERTERS = {
+	img: imgToCanonical,
+	audio: audioToCanonical,
+	video: videoToCanonical,
+	file: fileToCanonical
+};
+//#endregion
+//#region src/satori/helper/element/element-convert.ts
+/** 发方向：Satori 元素树 → kernel canonical（at uin→uid + 资源下载/转码）。 */
+async function satoriToCanonicalElements(elements, deps) {
+	const atUins = [];
+	const collectAt = (list) => {
+		for (const el of list) {
+			const id = el.attrs?.["id"];
+			if (el.type === "at" && id !== void 0 && id !== "all") atUins.push(id);
+			if (el.children !== void 0) collectAt(el.children);
+		}
+	};
+	collectAt(elements);
+	let uinToUidMap = /* @__PURE__ */ new Map();
+	if (atUins.length > 0) try {
+		uinToUidMap = await deps.uinToUid([...new Set(atUins)]);
+	} catch {}
+	const out = [];
+	for (const el of elements) out.push(...await elementToCanonical(el, deps, uinToUidMap));
+	return out;
+}
+/** Satori at → canonical at（uin → uid，name → display）。 */
+function atToCanonical(el, uinToUidMap) {
+	const id = el.attrs?.["id"] ?? "";
+	if (id === "all") return [{
+		type: "at",
+		target: "all"
+	}];
+	if (id === "") return [];
+	const target = uinToUidMap.get(id) ?? id;
+	const display = el.attrs?.["name"];
+	const base = {
+		type: "at",
+		target
+	};
+	if (display !== void 0 && display !== "") return [{
+		...base,
+		display
+	}];
+	return [base];
+}
+/** Satori message：forward 属性 → canonical forward；否则展开子元素。 */
+async function messageToCanonical(el, deps, uinToUidMap) {
+	if (el.attrs?.["forward"] !== void 0) {
+		const id = el.attrs?.["id"] ?? "";
+		return id === "" ? [] : [{
+			type: "forward",
+			messageIds: [id]
+		}];
+	}
+	return flattenChildren(el.children, deps, uinToUidMap);
+}
+/** 元素 type → 转换器（未知/修饰/排版类型走 fallback，不在此表）。 */
+const ELEMENT_CONVERTERS = {
+	text: async (el) => {
+		const text = el.text ?? "";
+		return text === "" ? [] : [{
+			type: "text",
+			text
+		}];
+	},
+	at: async (el, _deps, uinToUidMap) => atToCanonical(el, uinToUidMap),
+	emoji: async (el) => {
+		const id = el.attrs?.["id"] ?? "";
+		return id === "" ? [] : [{
+			type: "face",
+			id
+		}];
+	},
+	quote: async (el) => {
+		const id = el.attrs?.["id"] ?? "";
+		return id === "" ? [] : [{
+			type: "reply",
+			messageId: id
+		}];
+	},
+	message: async (el, deps, uinToUidMap) => messageToCanonical(el, deps, uinToUidMap),
+	br: async () => [{
+		type: "text",
+		text: "\n"
+	}],
+	author: async () => [],
+	sharp: async () => [],
+	a: async () => [],
+	button: async () => [],
+	...MEDIA_CONVERTERS
+};
+/** 单个元素 → canonical（修饰/排版元素展开子元素）。 */
+async function elementToCanonical(el, deps, uinToUidMap) {
+	const converter = ELEMENT_CONVERTERS[el.type];
+	if (converter !== void 0) return converter(el, deps, uinToUidMap);
+	return flattenChildren(el.children, deps, uinToUidMap);
+}
+/** 展开子元素为 canonical（递归）。 */
+async function flattenChildren(children, deps, uinToUidMap) {
+	const out = [];
+	for (const child of children ?? []) out.push(...await elementToCanonical(child, deps, uinToUidMap));
+	return out;
+}
+/** 解析消息 content 字符串 → canonical（message.create 用）。 */
+async function parseContentToCanonical(content, deps) {
+	return satoriToCanonicalElements(parseElements(content), deps);
+}
+//#endregion
+//#region src/satori/helper/translate.ts
+/**
+* Satori 资源翻译（RawMessage → Satori Message / 频道 / 群组，纯函数 + 注入转换）
+*
+* 收方向 ID 空间：canonical at.target 是 uid，Satori 规范是 uin——经
+* uidToUin 批量转换（依赖注入，与 OB11 的 ReceiveTranslateContext 同思路）。
+*/
+/** RawMessage → Satori Message（资源提升：message 不嵌套 user/member/channel）。 */
+async function toSatoriMessage(raw, deps) {
+	const elementDeps = {};
+	if (deps.uidToUin !== void 0) elementDeps.uidToUin = deps.uidToUin;
+	const content = renderElements(await canonicalToSatoriElements(toCanonicalElements(raw), elementDeps));
+	const isGroup = raw.chatType === ChatType.GROUP;
+	const peerUin = String(raw.peerUin ?? "");
+	const senderUin = String(raw.senderUin ?? "");
+	const nickname = raw.sendNickName ?? "";
+	const memberName = raw.sendMemberName ?? "";
+	const message = { id: raw.msgId };
+	if (content !== "") message.content = content;
+	if (isGroup) {
+		message.guild = toGuild(peerUin, raw.peerName);
+		message.channel = toGroupChannel(peerUin, raw.peerName);
+		message.user = toUser(senderUin, nickname);
+		message.member = { user: message.user };
+		if (memberName !== "" && memberName !== nickname) message.member.nick = memberName;
+	} else {
+		const peerId = senderUin !== "" ? senderUin : peerUin;
+		message.channel = toDirectChannel(peerId, nickname);
+		message.user = toUser(peerId, nickname);
+	}
+	const created = Number(raw.msgTime);
+	if (Number.isFinite(created) && created > 0) message.created_at = created;
+	return message;
+}
+/** 按频道 id 构造频道（isGroup 由调用方从事件/缓存得知）。 */
+function toChannelById(channelId, isGroup, name) {
+	if (isGroup) return toGroupChannel(channelId, name);
+	return toDirectChannel(channelId, name);
+}
+//#endregion
+//#region src/satori/action/base-action.ts
+/**
+* Satori 动作基类（响应形态与 OB11 不同：直接返回资源对象，错误用 HTTP 状态码）
+*
+* - `run(payload)`：zod 校验失败 → SatoriActionError(400)；_handle 抛的
+*   KernelError → satoriHttpStatusMap 映射 HTTP 状态码（ADR-017）
+* - `SatoriActionError`：带 HTTP 状态码的动作错误（transport 层直接透传状态码）
+*/
+/** 动作错误（带 HTTP 状态码；由 transport 层透传）。 */
+var SatoriActionError = class extends Error {
+	status;
+	constructor(status, message) {
+		super(message);
+		this.status = status;
+	}
+};
+/** 校验失败默认状态码。 */
+const INVALID_PARAM_STATUS = 400;
+/** 兜底错误状态码。 */
+const UNKNOWN_STATUS = 500;
+/**
+* Satori 动作基类：校验 + 执行 + 错误映射。
+* 成功返回资源对象（或数组/分页列表），失败抛 SatoriActionError。
+*/
+var BaseSatoriAction = class {
+	/** 校验并执行（HTTP/WS 共用）。 */
+	async run(payload) {
+		const parsed = this.schema.safeParse(payload);
+		if (!parsed.success) throw new SatoriActionError(INVALID_PARAM_STATUS, "参数校验失败");
+		try {
+			return await this._handle(parsed.data);
+		} catch (err) {
+			if (err instanceof SatoriActionError) throw err;
+			if (isKernelError(err)) throw new SatoriActionError(satoriHttpStatusMap[err.code] ?? UNKNOWN_STATUS, err.message);
+			throw new SatoriActionError(UNKNOWN_STATUS, err instanceof Error ? err.message : "未知错误");
+		}
+	}
+};
+//#endregion
+//#region src/satori/action/channel.ts
+/**
+* Satori 频道动作：channel.get / channel.list
+* （channel.create / update / delete / mute：QQ 不支持 → 501，见 registry）
+*/
+/** channel.get 参数。 */
+const channelGetSchema = z.object({ channel_id: z.string() });
+/** 获取频道（群聊 = 群号频道；私聊 = uin 频道）。 */
+var ChannelGetAction = class extends BaseSatoriAction {
+	name = "channel.get";
+	schema = channelGetSchema;
+	deps;
+	constructor(deps) {
+		super();
+		this.deps = deps;
+	}
+	async _handle(payload) {
+		const { channel_id: channelId } = payload;
+		const isGroup = (await this.deps.resolvePeer(channelId)).chatType === 2;
+		this.deps.setChannelType(channelId, isGroup);
+		if (isGroup) return toChannelById(channelId, true, (await this.deps.groupCache?.getGroupDetail(channelId))?.groupName);
+		return toChannelById(channelId, false);
+	}
+};
+/** channel.list 参数。 */
+const channelListSchema = z.object({
+	guild_id: z.string(),
+	next: z.string().optional()
+});
+/** 获取群组频道列表（QQ：群组与群聊频道重合 → 单元素列表）。 */
+var ChannelListAction = class extends BaseSatoriAction {
+	name = "channel.list";
+	schema = channelListSchema;
+	deps;
+	constructor(deps) {
+		super();
+		this.deps = deps;
+	}
+	async _handle(payload) {
+		const { guild_id: guildId } = payload;
+		const name = (await this.deps.groupCache?.getGroupDetail(guildId))?.groupName;
+		return { data: [toChannelById(guildId, true, name)] };
+	}
+};
+//#endregion
+//#region src/satori/action/friend.ts
+/** friend.list 参数。 */
+const friendListSchema = z.object({ next: z.string().optional() });
+/** 获取好友列表。 */
+var FriendListAction = class extends BaseSatoriAction {
+	name = "friend.list";
+	schema = friendListSchema;
+	deps;
+	constructor(deps) {
+		super();
+		this.deps = deps;
+	}
+	async _handle(_payload) {
+		return { data: (await this.deps.friendApi.getFriendList()).map((f) => {
+			const out = { user: toUser(f.uin, f.nickname) };
+			if (f.remark !== "" && f.remark !== f.nickname) out.nick = f.remark;
+			return out;
+		}) };
+	}
+};
+/** friend.delete 参数。 */
+const friendDeleteSchema = z.object({ user_id: z.string() });
+/** 删除好友。 */
+var FriendDeleteAction = class extends BaseSatoriAction {
+	name = "friend.delete";
+	schema = friendDeleteSchema;
+	deps;
+	constructor(deps) {
+		super();
+		this.deps = deps;
+	}
+	async _handle(payload) {
+		const { user_id: userId } = payload;
+		const uid = (await this.deps.uinToUid([userId])).get(userId) ?? userId;
+		await this.deps.friendApi.deleteFriend(uid);
+	}
+};
+/** friend.approve 参数（处理好友申请）。 */
+const friendApproveSchema = z.object({
+	message_id: z.string(),
+	approve: z.boolean(),
+	comment: z.string().optional()
+});
+/** 处理好友申请（message_id = 申请方 uin）。 */
+var FriendApproveAction = class extends BaseSatoriAction {
+	name = "friend.approve";
+	schema = friendApproveSchema;
+	deps;
+	constructor(deps) {
+		super();
+		this.deps = deps;
+	}
+	async _handle(payload) {
+		const { message_id: messageId, approve } = payload;
+		const notify = await findBuddyReq(this.deps, messageId);
+		await this.deps.friendApi.handleFriendRequest(notify, approve);
+	}
+};
+/** 按 message_id（申请方 uin）查找好友申请。 */
+async function findBuddyReq(deps, messageId) {
+	const reqs = await deps.friendApi.getBuddyReqList();
+	if (reqs.length === 0) throw new Error("好友申请不存在");
+	const uids = reqs.map((r) => r.friendUid);
+	const uinMap = await deps.uidToUin(uids);
+	const found = reqs.find((r) => uinMap.get(r.friendUid) === messageId);
+	if (found === void 0) throw new Error("好友申请不存在");
+	return found;
+}
+//#endregion
+//#region src/satori/action/guild.ts
+/** 成员列表默认条数。 */
+const DEFAULT_MEMBER_LIMIT = 100;
+/** guild.get 参数。 */
+const guildGetSchema = z.object({ guild_id: z.string() });
+/** 获取群组。 */
+var GuildGetAction = class extends BaseSatoriAction {
+	name = "guild.get";
+	schema = guildGetSchema;
+	deps;
+	constructor(deps) {
+		super();
+		this.deps = deps;
+	}
+	async _handle(payload) {
+		const { guild_id: guildId } = payload;
+		const detail = await this.deps.groupApi.getGroupInfo(guildId);
+		return toGuild(detail.groupCode, detail.groupName);
+	}
+};
+/** guild.list 参数。 */
+const guildListSchema = z.object({ next: z.string().optional() });
+/** 获取群组列表。 */
+var GuildListAction = class extends BaseSatoriAction {
+	name = "guild.list";
+	schema = guildListSchema;
+	deps;
+	constructor(deps) {
+		super();
+		this.deps = deps;
+	}
+	async _handle(_payload) {
+		return { data: (await this.deps.groupApi.getGroupList(true)).map((g) => toGuild(g.groupCode, g.groupName)) };
+	}
+};
+/** guild.approve 参数（处理入群邀请）。 */
+const guildApproveSchema = z.object({
+	message_id: z.string(),
+	approve: z.boolean(),
+	comment: z.string().optional()
+});
+/** 群请求 approve 基类（guild.approve / guild.member.approve 共用实现）。 */
+var GroupRequestApproveBase = class extends BaseSatoriAction {
+	schema = guildApproveSchema;
+	deps;
+	constructor(deps) {
+		super();
+		this.deps = deps;
+	}
+	async _handle(payload) {
+		const { message_id: messageId, approve, comment } = payload;
+		const notify = await findGroupNotify(this.deps, messageId);
+		const operateType = approve ? NTGroupRequestOperateTypes.KAGREE : NTGroupRequestOperateTypes.KREFUSE;
+		await this.deps.groupNotifyApi.handleGroupRequest(false, notify, operateType, comment ?? "");
+	}
+};
+/** 处理群邀请（message_id = 群通知 seq）。 */
+var GuildApproveAction = class extends GroupRequestApproveBase {
+	name = "guild.approve";
+};
+/** guild.member.get 参数。 */
+const guildMemberGetSchema = z.object({
+	guild_id: z.string(),
+	user_id: z.string()
+});
+/** 获取群成员。 */
+var GuildMemberGetAction = class extends BaseSatoriAction {
+	name = "guild.member.get";
+	schema = guildMemberGetSchema;
+	deps;
+	constructor(deps) {
+		super();
+		this.deps = deps;
+	}
+	async _handle(payload) {
+		const { guild_id: guildId, user_id: userId } = payload;
+		const uid = (await this.deps.uinToUid([userId])).get(userId) ?? userId;
+		const member = await this.deps.groupCache?.getMember(guildId, uid);
+		if (member !== void 0) return toGuildMember(member, userId);
+		const found = (await this.deps.groupApi.getGroupMemberInfo(guildId, [uid])).find((m) => m.uid === uid);
+		if (found === void 0) throw new Error("群成员不存在");
+		return toGuildMember(found, userId);
+	}
+};
+/** guild.member.list 参数。 */
+const guildMemberListSchema = z.object({
+	guild_id: z.string(),
+	next: z.string().optional()
+});
+/** 获取群成员列表。 */
+var GuildMemberListAction = class extends BaseSatoriAction {
+	name = "guild.member.list";
+	schema = guildMemberListSchema;
+	deps;
+	constructor(deps) {
+		super();
+		this.deps = deps;
+	}
+	async _handle(payload) {
+		const { guild_id: guildId } = payload;
+		let members;
+		const cached = await this.deps.groupCache?.getMembers(guildId);
+		if (cached !== void 0 && cached.length > 0) members = cached;
+		else members = await this.deps.groupApi.getGroupMemberList(guildId, true);
+		const limited = members.slice(0, DEFAULT_MEMBER_LIMIT);
+		const uids = limited.map((m) => m.uid);
+		const uinMap = await this.deps.uidToUin(uids);
+		const out = { data: limited.map((m) => toGuildMember(m, uinMap.get(m.uid) ?? m.uin)) };
+		if (members.length > DEFAULT_MEMBER_LIMIT) out.next = String(DEFAULT_MEMBER_LIMIT);
+		return out;
+	}
+};
+/** guild.member.kick 参数。 */
+const guildMemberKickSchema = z.object({
+	guild_id: z.string(),
+	user_id: z.string(),
+	/** 是否永久踢出（无法再次加入）。 */
+	permanent: z.boolean().optional()
+});
+/** 踢出群成员。 */
+var GuildMemberKickAction = class extends BaseSatoriAction {
+	name = "guild.member.kick";
+	schema = guildMemberKickSchema;
+	deps;
+	constructor(deps) {
+		super();
+		this.deps = deps;
+	}
+	async _handle(payload) {
+		const { guild_id: guildId, user_id: userId, permanent } = payload;
+		const uid = (await this.deps.uinToUid([userId])).get(userId) ?? userId;
+		await this.deps.groupApi.kickMember(guildId, [uid], permanent === true);
+	}
+};
+/** guild.member.approve 参数（处理加群申请）。 */
+const guildMemberApproveSchema = z.object({
+	message_id: z.string(),
+	approve: z.boolean(),
+	comment: z.string().optional()
+});
+/** 处理加群申请（message_id = 群通知 seq）。 */
+var GuildMemberApproveAction = class extends GroupRequestApproveBase {
+	name = "guild.member.approve";
+	schema = guildMemberApproveSchema;
+};
+/** 按 message_id（通知 seq）查找群通知。 */
+async function findGroupNotify(deps, messageId) {
+	const found = (await deps.groupNotifyApi.getSingleScreenNotifies(false, 50)).find((n) => n.seq === messageId);
+	if (found === void 0) throw new Error("群通知不存在");
+	return found;
+}
+/** GroupMember → Satori GuildMember（user.id = uin；nick = 群名片优先）。 */
+function toGuildMember(member, uin) {
+	const nick = member.cardName !== "" ? member.cardName : member.nick;
+	const out = { user: toUser(uin, member.nick) };
+	if (nick !== "" && nick !== member.nick) out.nick = nick;
+	return out;
+}
+//#endregion
+//#region src/satori/action/login.ts
+/**
+* Satori 登录动作：login.get
+*/
+/** login.get 参数（无）。 */
+const loginGetSchema = z.object({});
+/** 获取登录信息。 */
+var LoginGetAction = class extends BaseSatoriAction {
+	name = "login.get";
+	schema = loginGetSchema;
+	deps;
+	constructor(deps) {
+		super();
+		this.deps = deps;
+	}
+	async _handle(_payload) {
+		return toLogin(this.deps.self, 0, true);
+	}
+};
+//#endregion
+//#region src/satori/action/message.ts
+/**
+* Satori 消息动作：message.create / get / list / delete
+* （message.update：QQ 不支持编辑 → 501，见 registry）
+*/
+/** 消息列表默认条数（规范推荐 50）。 */
+const DEFAULT_LIST_LIMIT = 50;
+/** message.create 参数。 */
+const messageCreateSchema = z.object({
+	channel_id: z.string(),
+	content: z.string(),
+	/** 被动请求来源（第一版透传忽略，QQ 不区分主动/被动）。 */
+	referrer: z.unknown().optional()
+});
+/** 发送消息：返回 Message 数组（规范）。 */
+var MessageCreateAction = class extends BaseSatoriAction {
+	name = "message.create";
+	schema = messageCreateSchema;
+	deps;
+	constructor(deps) {
+		super();
+		this.deps = deps;
+	}
+	async _handle(payload) {
+		const { channel_id: channelId, content } = payload;
+		const peer = await this.deps.resolvePeer(channelId);
+		this.deps.setChannelType(channelId, peer.chatType === 2);
+		const elements = await parseContentToCanonical(content, this.deps.toCanonicalDeps());
+		const { msgId } = await this.deps.msgApi.sendMessage(peer, elements);
+		const message = {
+			id: msgId,
+			channel: toChannelById(channelId, peer.chatType === 2)
+		};
+		message.content = content;
+		return [message];
+	}
+};
+/** message.get 参数。 */
+const messageGetSchema = z.object({
+	channel_id: z.string(),
+	message_id: z.string()
+});
+/** 获取单条消息。 */
+var MessageGetAction = class extends BaseSatoriAction {
+	name = "message.get";
+	schema = messageGetSchema;
+	deps;
+	constructor(deps) {
+		super();
+		this.deps = deps;
+	}
+	async _handle(payload) {
+		const { channel_id: channelId, message_id: messageId } = payload;
+		const peer = await this.deps.resolvePeer(channelId);
+		const first = (await this.deps.msgApi.fetchMsgsByMsgId(peer, [messageId]))[0];
+		if (first === void 0) throw new Error("消息不存在");
+		this.deps.setChannelType(channelId, peer.chatType === 2);
+		return toSatoriMessage(first, {
+			selfUin: this.deps.selfUin,
+			uidToUin: (uids) => this.deps.uidToUin(uids)
+		});
+	}
+};
+/** message.list 参数。 */
+const messageListSchema = z.object({
+	channel_id: z.string(),
+	/** 分页令牌（缺省从最新开始）。 */
+	next: z.string().optional(),
+	/** 查询方向（缺省 before）。 */
+	direction: z.enum([
+		"before",
+		"after",
+		"around"
+	]).optional(),
+	/** 消息数量限制（缺省平台默认，推荐 50）。 */
+	limit: z.number().int().optional(),
+	/** 排序（缺省 asc）。 */
+	order: z.enum(["asc", "desc"]).optional()
+});
+/** 获取消息列表（双向分页；第一版仅支持 before 方向）。 */
+var MessageListAction = class extends BaseSatoriAction {
+	name = "message.list";
+	schema = messageListSchema;
+	deps;
+	constructor(deps) {
+		super();
+		this.deps = deps;
+	}
+	async _handle(payload) {
+		const { channel_id: channelId, next, direction, limit, order } = payload;
+		if (direction === "around") throw new Error("暂不支持 around 方向");
+		const peer = await this.deps.resolvePeer(channelId);
+		const count = limit ?? DEFAULT_LIST_LIMIT;
+		const raw = await this.deps.msgApi.fetchMessages(peer, {
+			count,
+			msgId: next ?? ""
+		});
+		this.deps.setChannelType(channelId, peer.chatType === 2);
+		const ordered = order !== "desc" ? [...raw].reverse() : raw;
+		const messages = [];
+		for (const msg of ordered) messages.push(await toSatoriMessage(msg, {
+			selfUin: this.deps.selfUin,
+			uidToUin: (uids) => this.deps.uidToUin(uids)
+		}));
+		const last = messages[messages.length - 1];
+		const out = { data: messages };
+		if (last !== void 0 && raw.length >= count) out.next = last.id;
+		return out;
+	}
+};
+/** message.delete 参数。 */
+const messageDeleteSchema = z.object({
+	channel_id: z.string(),
+	message_id: z.string()
+});
+/** 撤回消息。 */
+var MessageDeleteAction = class extends BaseSatoriAction {
+	name = "message.delete";
+	schema = messageDeleteSchema;
+	deps;
+	constructor(deps) {
+		super();
+		this.deps = deps;
+	}
+	async _handle(payload) {
+		const { channel_id: channelId, message_id: messageId } = payload;
+		const peer = await this.deps.resolvePeer(channelId);
+		await this.deps.msgApi.recallMessage(peer, [messageId]);
+	}
+};
+//#endregion
+//#region src/satori/action/not-implemented.ts
+/**
+* 未实现动作（501）：平台支持但适配器未实现（规范：501 而非 404）。
+*/
+/** 未实现动作：schema 接受任意对象，执行抛 501。 */
+var NotImplementedAction = class extends BaseSatoriAction {
+	name;
+	schema = z.object({}).passthrough();
+	constructor(name) {
+		super();
+		this.name = name;
+	}
+	async _handle(_payload) {
+		throw new SatoriActionError(501, `平台不支持该操作: ${this.name}`);
+	}
+};
+//#endregion
+//#region src/satori/action/reaction.ts
+/**
+* Satori 表态动作：reaction.create / reaction.delete
+* （reaction.clear / reaction.list：501，见 registry）
+*/
+/** 表情 ID 默认类型（QQ 表情 id 为 qq 表情索引）。 */
+const EMOJI_TYPE = "1";
+/** reaction.create 参数。 */
+const reactionCreateSchema = z.object({
+	channel_id: z.string(),
+	message_id: z.string(),
+	emoji_id: z.string()
+});
+/** 添加表态（QQ 表情表态，message_id = NT msgId）。 */
+var ReactionCreateAction = class extends BaseSatoriAction {
+	name = "reaction.create";
+	schema = reactionCreateSchema;
+	deps;
+	constructor(deps) {
+		super();
+		this.deps = deps;
+	}
+	async _handle(payload) {
+		const { channel_id: channelId, message_id: messageId, emoji_id: emojiId } = payload;
+		const peer = await this.deps.resolvePeer(channelId);
+		await this.deps.msgApi.setMsgEmojiLike(peer, {
+			msgSeq: messageId,
+			emojiId,
+			emojiType: EMOJI_TYPE,
+			like: true
+		});
+	}
+};
+/** reaction.delete 参数。 */
+const reactionDeleteSchema = z.object({
+	channel_id: z.string(),
+	message_id: z.string(),
+	emoji_id: z.string(),
+	/** 删除指定用户的表态（缺省删除自己的）。 */
+	user_id: z.string().optional()
+});
+/** 删除表态（第一版仅支持删除自己的，与 QQ 表情表态能力对齐）。 */
+var ReactionDeleteAction = class extends BaseSatoriAction {
+	name = "reaction.delete";
+	schema = reactionDeleteSchema;
+	deps;
+	constructor(deps) {
+		super();
+		this.deps = deps;
+	}
+	async _handle(payload) {
+		const { channel_id: channelId, message_id: messageId, emoji_id: emojiId, user_id: userId } = payload;
+		if (userId !== void 0) throw new Error("暂不支持删除他人表态");
+		const peer = await this.deps.resolvePeer(channelId);
+		await this.deps.msgApi.setMsgEmojiLike(peer, {
+			msgSeq: messageId,
+			emojiId,
+			emojiType: EMOJI_TYPE,
+			like: false
+		});
+	}
+};
+//#endregion
+//#region src/satori/action/user.ts
+/**
+* Satori 用户动作：user.get / user.channel.create
+*/
+/** user.get 参数。 */
+const userGetSchema = z.object({ user_id: z.string() });
+/** 获取用户信息（QQ 平台 user.id = uin）。 */
+var UserGetAction = class extends BaseSatoriAction {
+	name = "user.get";
+	schema = userGetSchema;
+	deps;
+	constructor(deps) {
+		super();
+		this.deps = deps;
+	}
+	async _handle(payload) {
+		const { user_id: userId } = payload;
+		let nickname;
+		try {
+			const info = await this.deps.profileApi.getStrangerInfo(userId);
+			nickname = info.nickname ?? info.long_nick ?? void 0;
+		} catch {}
+		return toUser(userId, nickname);
+	}
+};
+/** user.channel.create 参数。 */
+const userChannelCreateSchema = z.object({
+	user_id: z.string(),
+	guild_id: z.string().optional()
+});
+/** 创建私聊频道（QQ：私聊频道 id = 对端 uin，无需实际创建）。 */
+var UserChannelCreateAction = class extends BaseSatoriAction {
+	name = "user.channel.create";
+	schema = userChannelCreateSchema;
+	async _handle(payload) {
+		const { user_id: userId } = payload;
+		return toChannelById(userId, false);
+	}
+};
+//#endregion
+//#region src/satori/action/index.ts
+/**
+* Satori 动作注册表（ADR-013 延伸）：动作依赖收敛为 { api: SatoriApi } 单聚合对象。
+*
+* 501 动作：规范「平台支持但适配器未实现 → 501」——QQ 平台不支持的
+* 能力（消息编辑/频道管理/角色管理等）统一注册 NotImplementedAction。
+*/
+/** QQ 平台不支持的 Satori 标准动作（501）。 */
+const NOT_IMPLEMENTED = [
+	"message.update",
+	"channel.create",
+	"channel.update",
+	"channel.delete",
+	"channel.mute",
+	"guild.member.mute",
+	"guild.member.role.set",
+	"guild.member.role.unset",
+	"guild.role.list",
+	"guild.role.create",
+	"guild.role.update",
+	"guild.role.delete",
+	"reaction.clear",
+	"reaction.list"
+];
+/** 创建 Satori 动作注册表。 */
+function createSatoriActionRegistry(deps) {
+	const registry = new ActionRegistry();
+	const { api } = deps;
+	const messageDeps = api;
+	registry.register(new MessageCreateAction(messageDeps));
+	registry.register(new MessageGetAction(messageDeps));
+	registry.register(new MessageListAction(messageDeps));
+	registry.register(new MessageDeleteAction(messageDeps));
+	const channelDeps = api;
+	registry.register(new ChannelGetAction(channelDeps));
+	registry.register(new ChannelListAction(channelDeps));
+	const userDeps = api;
+	registry.register(new UserGetAction(userDeps));
+	registry.register(new UserChannelCreateAction());
+	const guildDeps = api;
+	registry.register(new GuildGetAction(guildDeps));
+	registry.register(new GuildListAction(guildDeps));
+	registry.register(new GuildApproveAction(guildDeps));
+	registry.register(new GuildMemberGetAction(guildDeps));
+	registry.register(new GuildMemberListAction(guildDeps));
+	registry.register(new GuildMemberKickAction(guildDeps));
+	registry.register(new GuildMemberApproveAction(guildDeps));
+	const friendDeps = api;
+	registry.register(new FriendListAction(friendDeps));
+	registry.register(new FriendDeleteAction(friendDeps));
+	registry.register(new FriendApproveAction(friendDeps));
+	const loginDeps = api;
+	registry.register(new LoginGetAction(loginDeps));
+	const reactionDeps = api;
+	registry.register(new ReactionCreateAction(reactionDeps));
+	registry.register(new ReactionDeleteAction(reactionDeps));
+	for (const name of NOT_IMPLEMENTED) registry.register(new NotImplementedAction(name));
+	return registry;
+}
+//#endregion
+//#region src/satori/api/satori-api.ts
+/** Satori 动作统一依赖聚合。 */
+var SatoriApi = class {
+	msgApi;
+	groupApi;
+	groupNotifyApi;
+	friendApi;
+	profileApi;
+	self;
+	selfUin;
+	cacheDir;
+	groupCache;
+	/**
+	* 频道类型缓存：channel_id → isGroup（群聊频道 id 与私聊 uin 无法从数字
+	* 规则区分，需从事件/查询回填——QQ 平台群号与用户 uin 同为数字）。
+	*/
+	channelTypeCache = /* @__PURE__ */ new Map();
+	constructor(opts) {
+		this.msgApi = opts.msgApi;
+		this.groupApi = opts.groupApi;
+		this.groupNotifyApi = opts.groupNotifyApi;
+		this.friendApi = opts.friendApi;
+		this.profileApi = opts.profileApi;
+		this.self = opts.self;
+		this.selfUin = opts.self.uin;
+		this.cacheDir = opts.cacheDir;
+		this.groupCache = opts.groupCache;
+	}
+	/** 记录频道类型（消息事件翻译时回填：chatType GROUP → true）。 */
+	setChannelType(channelId, isGroup) {
+		this.channelTypeCache.set(channelId, isGroup);
+	}
+	/**
+	* 解析 channel_id → Peer（消息动作共用）。
+	* 缓存命中直接取类型；未命中先试群号（getGroupInfo 成功 = 群聊），
+	* 失败按私聊（uin → uid）。
+	*/
+	async resolvePeer(channelId) {
+		const cached = this.channelTypeCache.get(channelId);
+		if (cached === true) return {
+			chatType: ChatType.GROUP,
+			peerUid: channelId
+		};
+		if (cached === false) return this.toC2cPeer(channelId);
+		const isGroup = await this.groupApi.getGroupInfo(channelId).then(() => true).catch(() => false);
+		this.channelTypeCache.set(channelId, isGroup);
+		if (isGroup) return {
+			chatType: ChatType.GROUP,
+			peerUid: channelId
+		};
+		return this.toC2cPeer(channelId);
+	}
+	/** uin → 私聊 Peer（uin→uid 转换；转换失败原样 uin 兜底）。 */
+	async toC2cPeer(uin) {
+		const uid = (await this.groupApi.uinToUid([uin])).get(uin) ?? uin;
+		return {
+			chatType: ChatType.C2C,
+			peerUid: uid
+		};
+	}
+	/** uin → uid（委托 groupApi；私聊发送 / at 目标用）。 */
+	uinToUid(uins) {
+		return this.groupApi.uinToUid(uins);
+	}
+	/** uid → uin（委托 groupApi；收方向 at / 用户 ID 用）。 */
+	uidToUin(uids) {
+		return this.groupApi.uidToUin(uids);
+	}
+	/** 发方向元素转换依赖（at uin→uid + 资源下载目录）。 */
+	toCanonicalDeps() {
+		return {
+			uinToUid: (uins) => this.groupApi.uinToUid(uins),
+			cacheDir: this.cacheDir
+		};
+	}
+};
+//#endregion
+//#region src/satori/event/translate.ts
+/**
+* Satori 事件翻译（kernel RawMessage → Satori Event 内容，纯函数 + 注入转换）
+*
+* 第一版支持：
+*  - message-created：普通消息（Msg/onRecvMsg）
+*  - message-deleted：grayTip REVOKE（撤回）
+*  - guild-member-added / guild-member-removed：grayTip GROUP（TipGroupElement）
+* （friend-request / guild-request 事件留待后续：grayTip 的 jsonGrayTipElement
+*  结构待运行时探测，OB11 走主动查询 get_group_system_msg 不广播。）
+*
+* 收方向 ID 空间：uid → uin 批量转换（deps.uidToUin，与消息翻译同依赖）。
+*/
+/** 普通消息 → message-created 事件。 */
+async function toSatoriMessageEvent(raw, deps) {
+	const message = await toSatoriMessage(raw, deps);
+	const content = {
+		type: "message-created",
+		timestamp: Number(raw.msgTime)
+	};
+	if (message.channel !== void 0) content.channel = message.channel;
+	if (message.guild !== void 0) content.guild = message.guild;
+	if (message.user !== void 0) content.user = message.user;
+	if (message.member !== void 0) content.member = message.member;
+	content.message = message;
+	return content;
+}
+/** 检查消息是否含可翻译的 grayTip（撤回 / 群成员变动）。 */
+function hasSatoriGrayTip(raw) {
+	for (const el of raw.elements) {
+		const g = el.grayTipElement;
+		if (g === void 0) continue;
+		if (g.subElementType === GrayTipSubType.REVOKE || g.subElementType === GrayTipSubType.GROUP) return true;
+	}
+	return false;
+}
+/** 收集 grayTip 涉及的 uid（批量 uidToUin 用，core 共享实现）。 */
+const collectSatoriGrayTipUids = collectGrayTipUids;
+/** 判断消息是否为群聊 grayTip（peerUid 是群号）。 */
+function isGroupMessage(raw) {
+	return raw.chatType === ChatType.GROUP;
+}
+/** grayTip → 事件（撤回 / 群成员变动；无匹配返回 null）。 */
+async function toSatoriGrayTipEvent(raw, uidToUinMap) {
+	for (const el of raw.elements) {
+		const g = el.grayTipElement;
+		if (g === void 0) continue;
+		if (g.subElementType === GrayTipSubType.REVOKE) {
+			const revoked = toRevokeEvent(raw, uidToUinMap);
+			if (revoked !== null) return revoked;
+		}
+		if (g.subElementType === GrayTipSubType.GROUP && isGroupMessage(raw)) {
+			const member = toMemberChangeEvent(raw, uidToUinMap);
+			if (member !== null) return member;
+		}
+	}
+	return null;
+}
+/** uid → uin（映射缺省退化为 uid）。 */
+function toUin(uid, uidToUinMap) {
+	return uidToUinMap.get(uid) ?? uid;
+}
+/** 撤回 → message-deleted 事件。 */
+function toRevokeEvent(raw, uidToUinMap) {
+	for (const el of raw.elements) {
+		const revoke = el.grayTipElement?.revokeElement;
+		if (revoke === void 0) continue;
+		const operatorUin = toUin(revoke.operatorUid, uidToUinMap);
+		const peerUin = String(raw.peerUin ?? "");
+		const content = {
+			type: "message-deleted",
+			timestamp: Number(raw.msgTime)
+		};
+		content.channel = {
+			id: peerUin,
+			type: isGroupMessage(raw) ? 0 : 1
+		};
+		if (isGroupMessage(raw)) content.guild = {
+			id: peerUin,
+			name: raw.peerName
+		};
+		content.message = { id: raw.msgSeq };
+		content.operator = toUser(operatorUin, revoke.operatorNick);
+		return content;
+	}
+	return null;
+}
+/** 群成员变动 → guild-member-added / guild-member-removed 事件。 */
+function toMemberChangeEvent(raw, uidToUinMap) {
+	for (const el of raw.elements) {
+		const grp = el.grayTipElement?.groupElement;
+		if (grp === void 0 || grp.type === void 0) continue;
+		const type = memberChangeType(grp.type);
+		if (type === null) return null;
+		const memberUid = grp.memberUid ?? "";
+		const adminUid = grp.adminUid ?? "";
+		const peerUin = String(raw.peerUin ?? "");
+		const content = {
+			type,
+			timestamp: Number(raw.msgTime),
+			guild: toGroupGuild(peerUin, raw.peerName),
+			channel: {
+				id: peerUin,
+				type: 0
+			},
+			member: toMember(memberUid, grp.memberNick, grp.memberRemark, uidToUinMap),
+			user: toUser(toUin(memberUid, uidToUinMap), grp.memberNick)
+		};
+		if (adminUid !== "" && adminUid !== memberUid) content.operator = toUser(toUin(adminUid, uidToUinMap), grp.adminNick);
+		return content;
+	}
+	return null;
+}
+/** 成员变动类型（MEMBER_ADD=added / QUIT=removed；其余 null）。 */
+function memberChangeType(type) {
+	if (type === TipGroupElementType.MEMBER_ADD) return "guild-member-added";
+	if (type === TipGroupElementType.QUIT) return "guild-member-removed";
+	return null;
+}
+/** 构造群组（带可选群名）。 */
+function toGroupGuild(id, name) {
+	const guild = { id };
+	if (name !== void 0 && name !== "") guild.name = name;
+	return guild;
+}
+/** 构造群成员（user + 可选备注 nick）。 */
+function toMember(uid, nick, remark, uidToUinMap) {
+	const member = { user: toUser(toUin(uid, uidToUinMap), nick) };
+	if (remark !== void 0 && remark !== "" && remark !== nick) member.nick = remark;
+	return member;
+}
+//#endregion
+//#region src/satori/types/event.ts
+/** 信令类型。 */
+const Opcode = {
+	EVENT: 0,
+	PING: 1,
+	PONG: 2,
+	IDENTIFY: 3,
+	READY: 4,
+	META: 5
+};
+//#endregion
+//#region src/satori/transport.ts
+/** WS 事件服务路径（规范固定）。 */
+const WS_EVENTS_PATH = "/v1/events";
+/** HTTP RPC 版本前缀。 */
+const V1_PREFIX = "/v1/";
+/** Authorization 头前缀。 */
+const BEARER_PREFIX = "Bearer ";
+/** 按配置装配 Satori 传输。 */
+function assembleSatoriTransports(opts) {
+	const { config, broadcaster, registry, login } = opts;
+	const adapters = [];
+	for (const item of config.httpServers) {
+		if (!item.enabled) continue;
+		const token = item.token ?? config.token;
+		const server = new HttpServer({
+			host: item.host,
+			port: item.port,
+			...token !== void 0 && token !== "" ? { authorize: makeBearerAuthorize(token) } : {}
+		});
+		server.onPathRequest = (ctx, req, respond) => {
+			handleHttpRequest(ctx, req, respond, registry, login);
+		};
+		adapters.push(server);
+	}
+	for (const item of config.wsServers) {
+		if (!item.enabled) continue;
+		const token = item.token ?? config.token;
+		const server = new WsServer({
+			host: item.host,
+			port: item.port,
+			path: WS_EVENTS_PATH
+		});
+		server.onRequest = (req, respond) => {
+			handleWsSignal(req, respond, token, login);
+		};
+		adapters.push(server);
+	}
+	for (const adapter of adapters) broadcaster.register(adapter);
+	return {
+		adapters,
+		close: async () => {
+			await Promise.all(adapters.map((a) => a.close()));
+			for (const adapter of adapters) broadcaster.unregister(adapter);
+		}
+	};
+}
+/** Bearer token 鉴权钩子。 */
+function makeBearerAuthorize(token) {
+	return (ctx) => {
+		const auth = ctx.headers["authorization"] ?? ctx.headers["Authorization"];
+		if (auth?.startsWith(BEARER_PREFIX)) return auth.slice(7) === token;
+		return false;
+	};
+}
+/** 解析路径：/v1/{resource}.{method} → 动作名；不匹配返回 null。 */
+function parseActionPath(path) {
+	if (!path.startsWith(V1_PREFIX)) return null;
+	const rest = path.slice(4);
+	if (/^([a-z][a-z0-9-]*)(?:\.[a-z][a-z0-9-]*)+$/i.exec(rest) === null) return null;
+	return rest;
+}
+/** HTTP RPC 分发。 */
+function handleHttpRequest(ctx, req, respond, registry, login) {
+	if (ctx.method !== "POST") {
+		respond({ error: "method not allowed" }, 405);
+		return;
+	}
+	const action = parseActionPath(ctx.path);
+	if (action === null) {
+		respond({ error: "api not found" }, HTTP_STATUS.notFound);
+		return;
+	}
+	if (action === "meta") {
+		respond({
+			logins: [login()],
+			proxy_urls: []
+		}, HTTP_STATUS.ok);
+		return;
+	}
+	const act = registry.get(action);
+	if (act === void 0) {
+		respond({ error: "api not found" }, HTTP_STATUS.notFound);
+		return;
+	}
+	act.run(req).then((data) => {
+		respond(data ?? {}, HTTP_STATUS.ok);
+	}).catch((err) => {
+		if (err instanceof SatoriActionError) {
+			respond({ error: err.message }, err.status);
+			return;
+		}
+		respond({ error: err instanceof Error ? err.message : "internal error" }, HTTP_STATUS.serverError);
+	});
+}
+/** WS 信令处理（IDENTIFY → READY；PING → PONG）。 */
+function handleWsSignal(signal, respond, token, login) {
+	const parsed = signal ?? {};
+	const op = parsed.op;
+	if (op === Opcode.IDENTIFY) {
+		const body = parsed.body ?? {};
+		if (token !== void 0 && token !== "" && body.token !== token) return;
+		respond({
+			op: Opcode.READY,
+			body: {
+				logins: [login()],
+				proxy_urls: []
+			}
+		});
+		return;
+	}
+	if (op === Opcode.PING) respond({
+		op: Opcode.PONG,
+		body: null
+	});
+}
+/** 事件信令（adapter 广播用）。 */
+function toEventSignal(event) {
+	return {
+		op: Opcode.EVENT,
+		body: event
+	};
+}
+//#endregion
+//#region src/satori/adapter.ts
+/** Satori 协议适配器。 */
+var NapukettoSatoriAdapter = class extends BaseProtocolAdapter {
+	protocol = "satori";
+	configSchema = satoriConfigSchema;
+	msgChannel;
+	api;
+	registry;
+	transports = null;
+	unsubscribe = null;
+	eventSn = 0;
+	constructor(opts) {
+		super({
+			config: opts.config,
+			broadcaster: opts.broadcaster,
+			hooks: {
+				onStart: (config) => this.startTransports(config),
+				onStop: () => this.stopAll(),
+				onReload: () => {
+					return Promise.resolve();
+				}
+			}
+		});
+		this.msgChannel = opts.msgChannel;
+		this.api = new SatoriApi(opts);
+		this.registry = createSatoriActionRegistry({ api: this.api });
+	}
+	/** 启动传输：装配（HTTP RPC + WS 事件服务）+ 打开 server + 订阅消息事件。 */
+	async startTransports(config) {
+		const broadcaster = this.getBroadcaster();
+		if (broadcaster !== void 0) {
+			this.transports = assembleSatoriTransports({
+				config,
+				broadcaster,
+				registry: this.registry,
+				login: () => this.currentLogin()
+			});
+			await Promise.all(this.transports.adapters.map((t) => t.open()));
+		}
+		this.subscribe();
+		this.broadcastLoginUpdated(true);
+	}
+	/** 当前登录信息（READY logins / meta / login.get 用）。 */
+	currentLogin() {
+		return toLogin(this.api.self, 0, true);
+	}
+	/** 广播 login-updated 事件（适配器启停时）。 */
+	broadcastLoginUpdated(online) {
+		const login = toLogin(this.api.self, 0, online);
+		this.broadcastEvent(toEventSignal({
+			sn: this.nextSn(),
+			type: "login-updated",
+			timestamp: Date.now(),
+			login
+		}));
+	}
+	/** 停止：退订 + 关闭传输 + 广播 login-updated（离线）。 */
+	async stopAll() {
+		this.unsubscribeAll();
+		if (this.transports !== null) {
+			await this.transports.close();
+			this.transports = null;
+		}
+		this.broadcastLoginUpdated(false);
+	}
+	/** 订阅 kernel 消息事件（幂等）。 */
+	subscribe() {
+		if (this.unsubscribe !== null) return;
+		this.unsubscribe = this.msgChannel.on("Msg/onRecvMsg", (msgs) => {
+			forEachRawMessage(msgs, (msg) => {
+				if (hasSatoriGrayTip(msg)) {
+					this.broadcastGrayTip(msg).catch(() => {});
+					return;
+				}
+				this.broadcastMessageCreated(msg);
+			});
+		});
+	}
+	/** 广播消息事件（message-created）。 */
+	async broadcastMessageCreated(msg) {
+		const content = await toSatoriMessageEvent(msg, {
+			selfUin: this.api.selfUin,
+			uidToUin: (uids) => this.api.uidToUin(uids)
+		});
+		this.api.setChannelType(String(msg.peerUin ?? ""), msg.chatType === 2);
+		this.broadcastContent(content);
+	}
+	/** 广播 grayTip 事件（message-deleted / guild-member-added / removed）。 */
+	async broadcastGrayTip(msg) {
+		const uids = collectSatoriGrayTipUids(msg);
+		let uidToUin = /* @__PURE__ */ new Map();
+		if (uids.length > 0) uidToUin = await this.api.uidToUin(uids);
+		const content = await toSatoriGrayTipEvent(msg, uidToUin);
+		if (content !== null) this.broadcastContent(content);
+	}
+	/** 广播事件内容（sn 递增 + 最小 login 包装 + EVENT 信令）。 */
+	broadcastContent(content) {
+		this.broadcastEvent(toEventSignal({
+			sn: this.nextSn(),
+			type: content.type,
+			timestamp: content.timestamp,
+			login: toMinimalLogin(this.eventSn, this.api.selfUin),
+			...pickEventResources(content)
+		}));
+	}
+	/** 事件 sn（递增，从 1 起）。 */
+	nextSn() {
+		this.eventSn += 1;
+		return this.eventSn;
+	}
+	/** 退订（幂等）。 */
+	unsubscribeAll() {
+		this.unsubscribe?.();
+		this.unsubscribe = null;
+	}
+};
+/** 从事件内容提取可选资源字段（channel/guild/message/user/member/operator）。 */
+function pickEventResources(content) {
+	const out = {};
+	if (content.channel !== void 0) out.channel = content.channel;
+	if (content.guild !== void 0) out.guild = content.guild;
+	if (content.message !== void 0) out.message = content.message;
+	if (content.user !== void 0) out.user = content.user;
+	if (content.member !== void 0) out.member = content.member;
+	if (content.operator !== void 0) out.operator = content.operator;
+	return out;
+}
+//#endregion
+export { HTTP_STATUS, NapukettoSatoriAdapter, SatoriActionError, SatoriApi, assembleSatoriTransports, canonicalToSatoriElements, createSatoriActionRegistry, parseContentToCanonical, parseElements, renderElements, satoriConfigSchema, satoriHttpStatusMap, satoriToCanonicalElements, toEventSignal };
+
+//# sourceMappingURL=index.mjs.map