wwise-waapi-mcp 1.0.0

package/dist/src/index.js

@@ -0,0 +1,95 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+const node_fs_1 = __importDefault(require("node:fs"));
+const server_js_1 = require("./core/server.js");
+const transport_js_1 = require("./core/transport.js");
+const referenceCatalog_js_1 = require("./lib/referenceCatalog.js");
+const runtimePaths_js_1 = require("./lib/runtimePaths.js");
+const waapiSchemaResolver_js_1 = require("./lib/waapiSchemaResolver.js");
+const toolRegistry_js_1 = require("./registry/toolRegistry.js");
+const tools_js_1 = require("./domains/catalog/tools.js");
+const tools_js_2 = require("./domains/example/tools.js");
+const tools_js_3 = require("./domains/soundengine/tools.js");
+const tools_js_4 = require("./domains/object/tools.js");
+const tools_js_5 = require("./domains/audio/tools.js");
+const tools_js_6 = require("./domains/soundbank/tools.js");
+const tools_js_7 = require("./domains/transport/tools.js");
+const tools_js_8 = require("./domains/profiler/tools.js");
+const tools_js_9 = require("./domains/project/tools.js");
+const tools_js_10 = require("./domains/remote/tools.js");
+const tools_js_11 = require("./domains/ui/tools.js");
+const tools_js_12 = require("./domains/debug/tools.js");
+const tools_js_13 = require("./domains/switchContainer/tools.js");
+const tools_js_14 = require("./domains/undo/tools.js");
+const tools_js_15 = require("./domains/log/tools.js");
+const tools_js_16 = require("./domains/plugin/tools.js");
+const tools_js_17 = require("./domains/sourceControl/tools.js");
+const tools_js_18 = require("./domains/sound/tools.js");
+/** 从 config/domains.json 加载领域元数据列表。 */
+function loadDomainsConfig() {
+    const document = JSON.parse(node_fs_1.default.readFileSync((0, runtimePaths_js_1.getConfigPath)("domains.json"), "utf8"));
+    return document.domains;
+}
+/**
+ * 服务器入口：加载配置和参考目录，创建并填充工具注册表，
+ * 根据环境变量应用访问控制策略，然后将 MCP 服务器连接到选定的传输层。
+ *
+ * 传输层选择（优先级从高到低）：
+ *   --http          CLI 标志 → HTTP/SSE 模式
+ *   MCP_TRANSPORT=http 环境变量 → HTTP/SSE 模式
+ *   默认            → stdio 模式
+ *
+ * HTTP/SSE 模式下端口配置（优先级从高到低）：
+ *   --port <n>      CLI 标志
+ *   PORT 环境变量
+ *   默认 3000
+ */
+async function main() {
+    const schemaLocation = await (0, waapiSchemaResolver_js_1.resolveWaapiSchemaDirectory)();
+    const registry = new toolRegistry_js_1.ToolRegistry(loadDomainsConfig(), (0, referenceCatalog_js_1.loadReferenceCatalog)(schemaLocation.schemaDir));
+    console.error(`Using WAAPI schema directory: ${schemaLocation.schemaDir} (source: ${schemaLocation.source}).`);
+    registry.registerTools((0, tools_js_2.getExampleTools)());
+    registry.registerTools((0, tools_js_3.getSoundengineTools)());
+    registry.registerTools((0, tools_js_4.getObjectTools)());
+    registry.registerTools((0, tools_js_5.getAudioTools)());
+    registry.registerTools((0, tools_js_6.getSoundbankTools)());
+    registry.registerTools((0, tools_js_7.getTransportTools)());
+    registry.registerTools((0, tools_js_8.getProfilerTools)());
+    registry.registerTools((0, tools_js_9.getProjectTools)());
+    registry.registerTools((0, tools_js_10.getRemoteTools)());
+    registry.registerTools((0, tools_js_11.getUiTools)());
+    registry.registerTools((0, tools_js_12.getDebugTools)());
+    registry.registerTools((0, tools_js_13.getSwitchContainerTools)());
+    registry.registerTools((0, tools_js_14.getUndoTools)());
+    registry.registerTools((0, tools_js_15.getLogTools)());
+    registry.registerTools((0, tools_js_16.getPluginTools)());
+    registry.registerTools((0, tools_js_17.getSourceControlTools)());
+    registry.registerTools((0, tools_js_18.getSoundTools)());
+    registry.registerTools((0, tools_js_1.getCatalogTools)(registry));
+    const policy = toolRegistry_js_1.ToolRegistry.policyFromEnv(process.env);
+    // --- 传输层模式检测 ---
+    const args = process.argv.slice(2);
+    const useHttp = args.includes("--http") ||
+        (process.env["MCP_TRANSPORT"] ?? "").toLowerCase() === "http";
+    if (useHttp) {
+        const portFlag = args.indexOf("--port");
+        const portArg = portFlag !== -1 ? parseInt(args[portFlag + 1] ?? "", 10) : NaN;
+        const port = !isNaN(portArg) ? portArg :
+            process.env["PORT"] ? parseInt(process.env["PORT"], 10) : 3000;
+        await (0, transport_js_1.startHttpSseServer)(() => (0, server_js_1.createServer)(registry, policy), port);
+    }
+    else {
+        const server = (0, server_js_1.createServer)(registry, policy);
+        const transport = (0, transport_js_1.createStdioTransport)();
+        await server.connect(transport);
+        console.error("Wwise MCP server is running on stdio.");
+    }
+}
+void main().catch(error => {
+    console.error("Failed to start Wwise MCP server.", error);
+    process.exit(1);
+});

package/dist/src/lib/errors.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppError = void 0;
+exports.toFailureResponse = toFailureResponse;
+const response_js_1 = require("./response.js");
+/**
+ * 结构化应用错误，携带 WAAPI 错误码和可选的调试详情。
+ * 用于在工具处理流程中区分业务失败与运行时异常。
+ */
+class AppError extends Error {
+    constructor(code, message, details) {
+        super(message);
+        this.name = "AppError";
+        this.code = code;
+        this.details = details;
+    }
+}
+exports.AppError = AppError;
+/**
+ * 将任意捕获的异常统一转换为标准失败响应包。
+ * AppError 会保留其原有错误码；其他错误均归类为 internal_error。
+ */
+function toFailureResponse(error) {
+    if (error instanceof AppError) {
+        return (0, response_js_1.fail)(error.code, error.message, error.details);
+    }
+    if (error instanceof Error) {
+        return (0, response_js_1.fail)("internal_error", error.message);
+    }
+    return (0, response_js_1.fail)("internal_error", "Unknown error", error);
+}

package/dist/src/lib/logger.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.redact = redact;
+exports.logToolCall = logToolCall;
+/** 匹配敏感字段名的正则，命中则将值替换为 [REDACTED]。 */
+const SENSITIVE_KEY_PATTERN = /token|password|secret/i;
+/**
+ * 递归遍历对象/数组，将敏感字段值替换为 [REDACTED]。
+ * 确保工具参数在写入日志前不泄露凭据或密钥。
+ */
+function redact(value) {
+    if (Array.isArray(value)) {
+        return value.map(item => redact(item));
+    }
+    if (value && typeof value === "object") {
+        const record = value;
+        const next = {};
+        for (const [key, nested] of Object.entries(record)) {
+            next[key] = SENSITIVE_KEY_PATTERN.test(key) ? "[REDACTED]" : redact(nested);
+        }
+        return next;
+    }
+    return value;
+}
+/**
+ * 将工具调用结果以结构化 JSON 形式写入 stderr。
+ * 调用方负责将 args 脱敏后再传入；此函数不会主动脱敏以避免重复处理。
+ */
+function logToolCall(input) {
+    const payload = {
+        tool_name: input.toolName,
+        duration_ms: input.durationMs,
+        success: input.success,
+        error_code: input.errorCode ?? null,
+        args: redact(input.args)
+    };
+    const message = JSON.stringify(payload);
+    if (input.success) {
+        console.error(message);
+        return;
+    }
+    console.error(message);
+}

package/dist/src/lib/referenceCatalog.js

@@ -0,0 +1,167 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setReferenceDirectory = setReferenceDirectory;
+exports.loadReferenceCatalog = loadReferenceCatalog;
+exports.loadReferenceDocument = loadReferenceDocument;
+exports.extractReferenceSummary = extractReferenceSummary;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+let activeReferenceDir;
+/** 设置当前进程使用的 WAAPI schema 目录。 */
+function setReferenceDirectory(referenceDir) {
+    activeReferenceDir = referenceDir;
+}
+/** 将字符串的首字母转大写。 */
+function sentenceCase(value) {
+    if (!value) {
+        return value;
+    }
+    return value.charAt(0).toUpperCase() + value.slice(1);
+}
+/** 将 camelCase 字符串拆分为空格分隔的单词。 */
+function splitCamelCase(value) {
+    return value.replace(/([a-z0-9])([A-Z])/g, "$1 $2");
+}
+/**
+ * 根据 WAAPI 函数全限定名（如 ak.soundengine.postEvent）推断所属领域和动作名。
+ * 顺序很重要：较具体的前缀应排在较通用前缀之前。
+ */
+function domainFromToolName(name) {
+    if (name.startsWith("ak.soundengine.")) {
+        return { domain: "soundengine", action: name.slice("ak.soundengine.".length) };
+    }
+    if (name.startsWith("ak.wwise.core.object.")) {
+        return { domain: "object", action: name.slice("ak.wwise.core.object.".length) };
+    }
+    if (name.startsWith("ak.wwise.core.audioSourcePeaks.")) {
+        return { domain: "audio", action: name.slice("ak.wwise.core.audioSourcePeaks.".length) };
+    }
+    if (name.startsWith("ak.wwise.core.audio.")) {
+        return { domain: "audio", action: name.slice("ak.wwise.core.audio.".length) };
+    }
+    if (name.startsWith("ak.wwise.core.soundbank.")) {
+        return { domain: "soundbank", action: name.slice("ak.wwise.core.soundbank.".length) };
+    }
+    if (name.startsWith("ak.wwise.core.transport.")) {
+        return { domain: "transport", action: name.slice("ak.wwise.core.transport.".length) };
+    }
+    if (name.startsWith("ak.wwise.core.profiler.")) {
+        return { domain: "profiler", action: name.slice("ak.wwise.core.profiler.".length) };
+    }
+    if (name.startsWith("ak.wwise.core.switchContainer.")) {
+        return { domain: "switchContainer", action: name.slice("ak.wwise.core.switchContainer.".length) };
+    }
+    if (name.startsWith("ak.wwise.core.undo.")) {
+        return { domain: "undo", action: name.slice("ak.wwise.core.undo.".length) };
+    }
+    if (name.startsWith("ak.wwise.core.plugin.")) {
+        return { domain: "plugin", action: name.slice("ak.wwise.core.plugin.".length) };
+    }
+    if (name.startsWith("ak.wwise.core.sourceControl.")) {
+        return { domain: "sourceControl", action: name.slice("ak.wwise.core.sourceControl.".length) };
+    }
+    if (name.startsWith("ak.wwise.core.sound.")) {
+        return { domain: "sound", action: name.slice("ak.wwise.core.sound.".length) };
+    }
+    if (name === "ak.wwise.core.getInfo" || name === "ak.wwise.core.getProjectInfo") {
+        return { domain: "project", action: name.slice("ak.wwise.core.".length) };
+    }
+    if (name.startsWith("ak.wwise.console.project.")) {
+        return { domain: "project", action: name.slice("ak.wwise.console.project.".length) };
+    }
+    if (name.startsWith("ak.wwise.ui.project.")) {
+        return { domain: "project", action: name.slice("ak.wwise.ui.project.".length) };
+    }
+    if (name.startsWith("ak.wwise.core.project.")) {
+        return { domain: "project", action: name.slice("ak.wwise.core.project.".length) };
+    }
+    if (name.startsWith("ak.wwise.core.remote.")) {
+        return { domain: "remote", action: name.slice("ak.wwise.core.remote.".length) };
+    }
+    if (name.startsWith("ak.wwise.ui.")) {
+        return { domain: "ui", action: name.slice("ak.wwise.ui.".length) };
+    }
+    if (name.startsWith("ak.wwise.debug.")) {
+        return { domain: "debug", action: name.slice("ak.wwise.debug.".length) };
+    }
+    if (name.startsWith("ak.wwise.cli.")) {
+        return { domain: "debug", action: name.slice("ak.wwise.cli.".length) };
+    }
+    if (name.startsWith("ak.wwise.core.executeLuaScript")) {
+        return { domain: "debug", action: name.slice("ak.wwise.".length) };
+    }
+    if (name.startsWith("ak.wwise.core.log.")) {
+        return { domain: "log", action: name.slice("ak.wwise.core.log.".length) };
+    }
+    if (name.startsWith("ak.wwise.waapi.")) {
+        return { domain: "catalog", action: name.slice("ak.wwise.waapi.".length) };
+    }
+    return { domain: "catalog", action: name };
+}
+/** 将动作名（如 postEvent）转化为可读的摘要文字。 */
+function summarizeAction(action) {
+    const normalized = action.split(".").map(splitCamelCase).join(" ");
+    return sentenceCase(normalized);
+}
+/**
+ * 扫描 WAAPI schema 目录下所有 JSON 文件，构建工具名 → 目录条目的映射表。
+ * 此过程不解析文件内容，仅根据文件名推断元数据，确保启动消耗最小。
+ */
+function loadReferenceCatalog(referenceDir) {
+    setReferenceDirectory(referenceDir);
+    if (!node_fs_1.default.existsSync(referenceDir)) {
+        return new Map();
+    }
+    const files = node_fs_1.default.readdirSync(referenceDir);
+    const catalog = new Map();
+    for (const file of files) {
+        if (!file.endsWith(".json") || file === "waapi_definitions.json") {
+            continue;
+        }
+        const name = node_path_1.default.basename(file, ".json");
+        const parsed = domainFromToolName(name);
+        catalog.set(name, {
+            name,
+            domain: parsed.domain,
+            action: parsed.action,
+            referenceFile: file,
+            summary: summarizeAction(parsed.action)
+        });
+    }
+    return catalog;
+}
+/**
+ * 按需加载并解析单个 WAAPI 参考 JSON 文件。
+ * 若文件不存在则返回 undefined，调用方应处理该情况。
+ */
+function loadReferenceDocument(toolName) {
+    if (!activeReferenceDir) {
+        return undefined;
+    }
+    const filePath = node_path_1.default.join(activeReferenceDir, `${toolName}.json`);
+    if (!node_fs_1.default.existsSync(filePath)) {
+        return undefined;
+    }
+    return JSON.parse(node_fs_1.default.readFileSync(filePath, "utf8"));
+}
+/**
+ * 从完整的 WAAPI 参考文档中提取第一个主函数的部分关键字段，用于工具详情展示。
+ * 仅提取 schema 类信息，不包含完整的实例和历史记录以控制响应体积。
+ */
+function extractReferenceSummary(document) {
+    const functions = Array.isArray(document.functions) ? document.functions : [];
+    const topics = Array.isArray(document.topics) ? document.topics : [];
+    const primary = (functions[0] ?? topics[0] ?? {});
+    return {
+        id: primary.id,
+        description: primary.description,
+        restrict: primary.restrict,
+        seeAlso: primary.seeAlso,
+        argsSchema: primary.argsSchema,
+        resultSchema: primary.resultSchema,
+        optionsSchema: primary.optionsSchema
+    };
+}

package/dist/src/lib/response.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.standardResponseJsonSchema = exports.standardResponseSchema = void 0;
+exports.ok = ok;
+exports.fail = fail;
+exports.toMcpToolResult = toMcpToolResult;
+const v4_1 = require("zod/v4");
+/** Zod 运行时验证 schema，用于内部断言响应结构正确性。 */
+exports.standardResponseSchema = v4_1.z.discriminatedUnion("ok", [
+    v4_1.z.object({
+        ok: v4_1.z.literal(true),
+        data: v4_1.z.unknown()
+    }),
+    v4_1.z.object({
+        ok: v4_1.z.literal(false),
+        error: v4_1.z.object({
+            code: v4_1.z.string(),
+            message: v4_1.z.string(),
+            details: v4_1.z.unknown().optional()
+        })
+    })
+]);
+/**
+ * 对应 standardResponseSchema 的 JSON Schema 表示。
+ * 注意：不要将此 schema 传给 MCP SDK 的 registerTool outputSchema 参数，
+ * 该版本 SDK 对判别联合类型的运行时校验存在 bug。
+ */
+exports.standardResponseJsonSchema = {
+    oneOf: [
+        {
+            type: "object",
+            properties: {
+                ok: { const: true },
+                data: {}
+            },
+            required: ["ok", "data"],
+            additionalProperties: false
+        },
+        {
+            type: "object",
+            properties: {
+                ok: { const: false },
+                error: {
+                    type: "object",
+                    properties: {
+                        code: { type: "string" },
+                        message: { type: "string" },
+                        details: {}
+                    },
+                    required: ["code", "message"],
+                    additionalProperties: false
+                }
+            },
+            required: ["ok", "error"],
+            additionalProperties: false
+        }
+    ]
+};
+/** 构造成功响应包。 */
+function ok(data) {
+    return { ok: true, data };
+}
+/** 构造失败响应包，details 为可选的调试附加信息。 */
+function fail(code, message, details) {
+    return {
+        ok: false,
+        error: {
+            code,
+            message,
+            ...(details === undefined ? {} : { details })
+        }
+    };
+}
+/**
+ * 将标准响应包序列化为 MCP SDK 要求的工具返回格式。
+ * 同时填充 structuredContent 以便支持 MCP 结构化输出的客户端直接解析。
+ */
+function toMcpToolResult(response) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(response, null, 2)
+            }
+        ],
+        structuredContent: response
+    };
+}

package/dist/src/lib/runtimePaths.js

@@ -0,0 +1,21 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getProjectRoot = getProjectRoot;
+exports.getConfigPath = getConfigPath;
+const node_path_1 = __importDefault(require("node:path"));
+/**
+ * 返回项目根目录的绝对路径。
+ * - 开发模式：__dirname 位于 dist/src/lib，向上三级即为仓库根目录。
+ * - 打包模式（pkg）：使用可执行文件所在目录。
+ */
+function getProjectRoot() {
+    const packagedProcess = process;
+    return packagedProcess.pkg ? node_path_1.default.dirname(process.execPath) : node_path_1.default.resolve(__dirname, "..", "..", "..");
+}
+/** 返回 config/ 目录下指定文件的绝对路径。 */
+function getConfigPath(...segments) {
+    return node_path_1.default.join(getProjectRoot(), "config", ...segments);
+}

package/dist/src/lib/toolFactory.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWaapiStubTool = void 0;
+exports.createWaapiTool = createWaapiTool;
+const v4_1 = require("zod/v4");
+const response_js_1 = require("./response.js");
+const waapiClient_js_1 = require("./waapiClient.js");
+/**
+ * 在 Zod 属性规范中自动注入可选的 options 字段。
+ * 若传入的是原始 Zod 类型（透过 _zod 属性判定）则不作修改。
+ */
+function withOptionalOptionsSchema(inputSchema) {
+    if (!inputSchema || Array.isArray(inputSchema) || typeof inputSchema !== "object" || "_zod" in inputSchema) {
+        return inputSchema;
+    }
+    const shape = inputSchema;
+    return {
+        ...shape,
+        options: shape.options ?? v4_1.z.unknown().optional()
+    };
+}
+/**
+ * 在 JSON Schema 中自动注入可选的 options 字段。
+ * 若 inputSchemaJson 不存在或不是 object 类型，返回最小化的兼容 schema。
+ */
+function withOptionalOptionsJsonSchema(inputSchemaJson) {
+    if (!inputSchemaJson || inputSchemaJson.type !== "object") {
+        return {
+            type: "object",
+            properties: {
+                options: {}
+            },
+            additionalProperties: true
+        };
+    }
+    const properties = inputSchemaJson.properties && typeof inputSchemaJson.properties === "object"
+        ? { ...inputSchemaJson.properties }
+        : {};
+    if (!("options" in properties)) {
+        properties.options = {};
+    }
+    return {
+        ...inputSchemaJson,
+        properties
+    };
+}
+/**
+ * 创建一个真实执行 WAAPI RPC 调用的 ToolDefinition。
+ * 处理器会自动从入参中分离 options 并传入 WAAPI optionsSchema。
+ * 返回值使用标准包：{ ok: true, data: { tool, domain, result } }。
+ */
+function createWaapiTool(input) {
+    return {
+        ...input,
+        inputSchema: withOptionalOptionsSchema(input.inputSchema),
+        inputSchemaJson: withOptionalOptionsJsonSchema(input.inputSchemaJson),
+        callable: true,
+        implementationStatus: "implemented",
+        outputSchemaJson: response_js_1.standardResponseJsonSchema,
+        handler: async (rawArgs) => {
+            const args = (rawArgs ?? {});
+            const { options, ...waapiArgs } = args;
+            const data = await (0, waapiClient_js_1.callWaapi)(input.name, waapiArgs, options);
+            return (0, response_js_1.ok)({
+                tool: input.name,
+                domain: input.domain,
+                result: data
+            });
+        }
+    };
+}
+/** createWaapiTool 的别名，保留以兼容旧引用。 */
+exports.createWaapiStubTool = createWaapiTool;

package/dist/src/lib/waapiClient.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getWaapiSession = getWaapiSession;
+exports.callWaapi = callWaapi;
+exports.disconnectWaapi = disconnectWaapi;
+const waapi_client_1 = require("waapi-client");
+const fs_1 = require("fs");
+const errors_js_1 = require("./errors.js");
+const runtimePaths_js_1 = require("./runtimePaths.js");
+/** 从 runtime.json 读取 WAAPI URL 配置 */
+function getWaapiUrl() {
+    try {
+        const configPath = (0, runtimePaths_js_1.getConfigPath)("runtime.json");
+        const config = JSON.parse((0, fs_1.readFileSync)(configPath, "utf-8"));
+        return config.waapiUrl?.trim() || "ws://127.0.0.1:8080/waapi";
+    }
+    catch {
+        // 如果读取配置失败，使用默认值
+        return "ws://127.0.0.1:8080/waapi";
+    }
+}
+/** 应用内共享的单例 WAAPI 会话对象。 */
+let activeSession;
+/** 连接过程中的 Promise，用于防止并发请求触发多次连接。 */
+let connectPromise;
+/**
+ * 尝试与 WAAPI 服务器建立新会话。
+ * 连接失败时抛出带 waapi_unavailable 错误码的 AppError。
+ */
+async function openSession() {
+    const url = getWaapiUrl();
+    try {
+        return await (0, waapi_client_1.connect)(url);
+    }
+    catch (error) {
+        throw new errors_js_1.AppError("waapi_unavailable", `Unable to connect to WAAPI at ${url}.`, {
+            url,
+            cause: error instanceof Error ? error.message : error
+        });
+    }
+}
+/**
+ * 返回当前已活跃的 WAAPI 会话，必要时自动初始化连接。
+ * 并发调用时共享同一个连接 Promise，避免重复连接。
+ */
+async function getWaapiSession() {
+    if (activeSession) {
+        return activeSession;
+    }
+    if (!connectPromise) {
+        connectPromise = openSession();
+    }
+    try {
+        activeSession = await connectPromise;
+        return activeSession;
+    }
+    finally {
+        connectPromise = undefined;
+    }
+}
+/**
+ * 对单个 WAAPI RPC 接口发起调用并返回原始结果。
+ * 调用失败时抛出带 waapi_call_failed 的 AppError，并重置内部会话以备下次重连。
+ * @param uri WAAPI 函数全限定名，如 ak.soundengine.postEvent
+ * @param args 函数入参（对应该接口的 argsSchema）
+ * @param options 函数选项（对应该接口的 optionsSchema）
+ */
+async function callWaapi(uri, args, options) {
+    const session = await getWaapiSession();
+    try {
+        return await session.call(uri, args ?? {}, options ?? {});
+    }
+    catch (error) {
+        activeSession = undefined;
+        throw new errors_js_1.AppError("waapi_call_failed", `WAAPI call failed for ${uri}.`, {
+            uri,
+            cause: error instanceof Error ? error.message : error
+        });
+    }
+}
+/**
+ * 断开当前活跃的 WAAPI 会话。通常在进程退出前调用以保持连接干净。
+ * 断开错误会被忙略，不会影响清理流程。
+ */
+async function disconnectWaapi() {
+    if (!activeSession) {
+        return;
+    }
+    const session = activeSession;
+    activeSession = undefined;
+    try {
+        await session.disconnect();
+    }
+    catch {
+        // Ignore disconnect errors during shutdown or reconnect.
+    }
+}