@lotaber_wang/openclaw-dc-plugin 0.1.2 → 0.1.3

package/README.md

@@ -5,8 +5,11 @@
 ## 插件能力
 
 - 以 OpenClaw 原生插件方式安装
-- 内部启动已发布的 `@mikoto_zero/minigame-open-mcp` 运行时
+- 发布时会把 `@mikoto_zero/minigame-open-mcp` 运行时一起打进插件包，避免宿主侧首次调用时再临时装包
+- 运行时解析顺序为：插件内 bundled runtime -> 本地已安装 runtime -> 本地缓存 runtime
 - 暴露适合 agent / skill 消费的 TapTap DC 原始 JSON 工具
+- 提供高层工具 `taptap_dc_quick_brief`，可直接按游戏名 / app_id 生成 TapTap DC 快速简报
+- 如果当前未授权，`taptap_dc_quick_brief` 会直接返回 `auth_url` / `qrcode_url`，便于用户立即扫码
 - 覆盖授权、选游戏、商店/评价/社区概览、商店快照、论坛内容、评价列表、点赞与官方回复
 - 内置 `taptap-dc-ops-brief`，可把原始数据整理成简洁的运营简报
 
@@ -18,13 +21,28 @@ openclaw plugins install @lotaber_wang/openclaw-dc-plugin
 
 ## 典型使用流程
 
-1. 调用 `taptap_dc_check_environment`
-2. 如果还没授权，调用 `taptap_dc_start_authorization`
-3. 打开 `auth_url` 或扫描 `qrcode_url`
-4. 完成后调用 `taptap_dc_complete_authorization`
-5. 调用 `taptap_dc_list_apps`
-6. 调用 `taptap_dc_select_app`
-7. 再调用概览类工具，并配合内置 skill 生成简报
+优先推荐直接使用：
+
+1. 直接调用 `taptap_dc_quick_brief`
+2. 如果还没授权，工具会直接返回扫码链接
+3. 完成扫码后调用 `taptap_dc_complete_authorization`
+4. 再次调用 `taptap_dc_quick_brief`
+
+示例：
+
+- 查当前已选中游戏：
+  - `taptap_dc_quick_brief`
+- 按游戏名直接查：
+  - `taptap_dc_quick_brief({ "app_name": "TapTap" })`
+- 按 app_id 直接查：
+  - `taptap_dc_quick_brief({ "app_id": 204036 })`
+
+如果需要更底层、更细粒度的操作，再使用原始工具链：
+
+1. `taptap_dc_check_environment`
+2. `taptap_dc_list_apps`
+3. `taptap_dc_select_app`
+4. `taptap_dc_get_store_overview` / `taptap_dc_get_review_overview` / `taptap_dc_get_community_overview`
 
 ## 配置项
 
@@ -38,3 +56,13 @@ openclaw plugins install @lotaber_wang/openclaw-dc-plugin
 - `verbose`
 
 正常情况下，如果内嵌的 TapTap MCP 主包已经带了可用凭据，生产环境不需要额外配置 `client_id` / `client_secret`。
+
+## 安装排障
+
+如果 OpenClaw 能安装插件，但第一次调用工具仍然偏慢，通常是在启动内嵌 TapTap 运行时，而不是在现场重新下载依赖。
+
+如果第一次调用失败，优先检查：
+
+- 当前环境是否能访问 npm registry
+- 本机 Node 版本是否 >= 18.14.1
+- OpenClaw 进程是否有临时目录写权限

package/index.js

@@ -50,6 +50,221 @@ function createSchema(properties = {}, required = []) {
   };
 }
 
+function normalizeText(value) {
+  return String(value || '')
+    .trim()
+    .toLowerCase();
+}
+
+function formatNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value.toLocaleString('zh-CN') : '-';
+}
+
+function getNumberField(source, keys = []) {
+  if (!source || typeof source !== 'object') {
+    return undefined;
+  }
+
+  for (const key of keys) {
+    const value = source[key];
+    if (typeof value === 'number' && Number.isFinite(value)) {
+      return value;
+    }
+    if (typeof value === 'string' && value.trim() !== '' && !Number.isNaN(Number(value))) {
+      return Number(value);
+    }
+  }
+
+  return undefined;
+}
+
+function getCurrentAppLabel(payload) {
+  return payload?.app_title || payload?.cache?.app_title || payload?.cache?.appTitle || '当前游戏';
+}
+
+function flattenApps(payload) {
+  const developers = Array.isArray(payload?.list) ? payload.list : [];
+  const flattened = [];
+
+  for (const developer of developers) {
+    const apps = Array.isArray(developer?.apps) ? developer.apps : [];
+    for (const app of apps) {
+      flattened.push({
+        developer_id: developer.developer_id,
+        developer_name: developer.developer_name,
+        app_id: app.app_id,
+        app_title: app.app_title,
+      });
+    }
+  }
+
+  return flattened;
+}
+
+function findAppMatch(payload, appName, appId) {
+  const apps = flattenApps(payload);
+
+  if (appId !== undefined) {
+    const matched = apps.find((app) => app.app_id === appId);
+    return matched ? { matched, candidates: [] } : { matched: null, candidates: [] };
+  }
+
+  const keyword = normalizeText(appName);
+  if (!keyword) {
+    return { matched: null, candidates: [] };
+  }
+
+  const exact = apps.filter((app) => normalizeText(app.app_title) === keyword);
+  if (exact.length === 1) {
+    return { matched: exact[0], candidates: [] };
+  }
+
+  const partial = apps.filter((app) => normalizeText(app.app_title).includes(keyword));
+  if (partial.length === 1) {
+    return { matched: partial[0], candidates: [] };
+  }
+
+  return { matched: null, candidates: exact.length > 0 ? exact.slice(0, 5) : partial.slice(0, 5) };
+}
+
+function buildBriefText(appTitle, sections, meta = {}) {
+  const store = sections.store?.data || {};
+  const review = sections.review?.data || {};
+  const community = sections.community?.data || {};
+  const ratingSummary = review.rating_summary || {};
+
+  const pageViewCount = getNumberField(store, ['page_view_count']);
+  const downloadRequestCount = getNumberField(store, ['download_request_count']);
+  const downloadCount = getNumberField(store, ['download_count']);
+  const reserveCount = getNumberField(store, ['reserve_count']);
+  const ratingScore = getNumberField(ratingSummary, ['score', 'rating_score', 'average_score']);
+  const reviewCount = getNumberField(ratingSummary, ['review_count', 'count', 'total_count']);
+  const positiveCount = getNumberField(review, ['positive_review_count']);
+  const negativeCount = getNumberField(review, ['negative_review_count']);
+  const topicPageViewCount = getNumberField(community, ['topic_page_view_count']);
+  const topicCount = getNumberField(community, ['topic_count']);
+
+  const summary = [];
+  if (pageViewCount !== undefined || downloadRequestCount !== undefined) {
+    summary.push(
+      `商店侧有数据回传，详情页访问量 ${formatNumber(pageViewCount)}，下载请求量 ${formatNumber(downloadRequestCount)}。`
+    );
+  }
+  if (ratingScore !== undefined || reviewCount !== undefined) {
+    summary.push(`评价侧当前均分 ${ratingScore ?? '-'}，累计评价 ${formatNumber(reviewCount)}。`);
+  }
+  if (topicPageViewCount !== undefined || topicCount !== undefined) {
+    summary.push(
+      `社区侧页面浏览量 ${formatNumber(topicPageViewCount)}，帖子量 ${formatNumber(topicCount)}。`
+    );
+  }
+  if (summary.length === 0) {
+    summary.push('已成功拉取数据，但当前字段较少，建议继续查看详细原始结果。');
+  }
+
+  const lines = [
+    `《${appTitle}》TapTap DC 快速简报`,
+    '',
+    `时间范围：${meta.start_date || '默认'} ~ ${meta.end_date || '默认'}`,
+    '',
+    '结论：',
+    ...summary.map((item) => `- ${item}`),
+    '',
+    '关键指标：',
+    `- 详情页访问量（PV）：${formatNumber(pageViewCount)}`,
+    `- 下载请求量：${formatNumber(downloadRequestCount)}`,
+    `- 下载完成量：${formatNumber(downloadCount)}`,
+    `- 预约量：${formatNumber(reserveCount)}`,
+    `- 评价均分：${ratingScore ?? '-'}`,
+    `- 评价总数：${formatNumber(reviewCount)}`,
+    `- 正向评价数：${formatNumber(positiveCount)}`,
+    `- 负向评价数：${formatNumber(negativeCount)}`,
+    `- 社区页面浏览量：${formatNumber(topicPageViewCount)}`,
+    `- 社区帖子量：${formatNumber(topicCount)}`,
+  ];
+
+  return lines.join('\n');
+}
+
+function buildAuthGuideText(authPayload) {
+  const lines = [
+    '当前还没有完成 TapTap 授权，请先扫码授权。',
+    '',
+    `授权链接：${authPayload?.auth_url || '-'}`,
+    `二维码链接：${authPayload?.qrcode_url || '-'}`,
+    '',
+    '完成扫码后，请继续调用 `taptap_dc_complete_authorization`，然后再次调用 `taptap_dc_quick_brief`。',
+  ];
+
+  if (authPayload?.device_code) {
+    lines.push('', `device_code：${authPayload.device_code}`);
+  }
+
+  return lines.join('\n');
+}
+
+async function callJsonTool(bridge, name, args = {}) {
+  const text = await bridge.callTool(name, args);
+  const normalized = normalizeJsonText(text);
+  return JSON.parse(normalized);
+}
+
+async function resolveSelectedApp(bridge, params) {
+  if (params.developer_id && params.app_id) {
+    const selected = await callJsonTool(bridge, 'select_app_raw', {
+      developer_id: params.developer_id,
+      app_id: params.app_id,
+    });
+    return {
+      app: {
+        developer_id: params.developer_id,
+        app_id: params.app_id,
+        app_title: getCurrentAppLabel(selected),
+      },
+      selected,
+    };
+  }
+
+  const current = await callJsonTool(bridge, 'get_current_app_info_raw', {});
+  if (!params.app_name && !params.app_id && current?.selected) {
+    return {
+      app: {
+        developer_id: current?.cache?.developer_id || current?.cache?.developerId,
+        app_id: current?.cache?.app_id || current?.cache?.appId,
+        app_title: getCurrentAppLabel(current),
+      },
+      selected: current,
+    };
+  }
+
+  const appList = await callJsonTool(bridge, 'list_developers_and_apps_raw', {});
+  const { matched, candidates } = findAppMatch(appList, params.app_name, params.app_id);
+
+  if (!matched) {
+    return {
+      error: {
+        ok: false,
+        error: 'APP_NOT_RESOLVED',
+        message:
+          candidates.length > 0
+            ? '找到多个候选游戏，请改用更精确的 app_name 或直接传 app_id / developer_id。'
+            : '没有找到匹配的游戏，请传 app_name、app_id，或先手动选择一次游戏。',
+        candidates,
+      },
+    };
+  }
+
+  const selected = await callJsonTool(bridge, 'select_app_raw', {
+    developer_id: matched.developer_id,
+    app_id: matched.app_id,
+  });
+
+  return {
+    app: matched,
+    selected,
+  };
+}
+
 function registerProxyTool(api, bridge, definition) {
   api.registerTool(
     () => ({
@@ -84,6 +299,92 @@ function registerProxyTool(api, bridge, definition) {
   );
 }
 
+function registerQuickBriefTool(api, bridge) {
+  api.registerTool(
+    () => ({
+      name: 'taptap_dc_quick_brief',
+      label: 'TapTap 快速简报',
+      description:
+        '按当前选中游戏、游戏名或 app_id，直接生成一份 TapTap DC 快速运营简报；如果未授权，会自动返回扫码授权信息。',
+      parameters: createSchema({
+        app_name: {
+          type: 'string',
+          description: '可选，游戏名。传入后会自动在你可访问的游戏里匹配并选中。',
+        },
+        developer_id: {
+          type: 'number',
+          description: '可选，开发者 ID。与 app_id 一起传时会直接选中游戏。',
+        },
+        app_id: {
+          type: 'number',
+          description: '可选，游戏 app_id。可单独传，也可与 developer_id 一起传。',
+        },
+        start_date: {
+          type: 'string',
+          description: '可选，开始日期，格式 YYYY-MM-DD。',
+        },
+        end_date: {
+          type: 'string',
+          description: '可选，结束日期，格式 YYYY-MM-DD。',
+        },
+      }),
+      async execute(_id, params) {
+        try {
+          const env = await callJsonTool(bridge, 'check_environment_raw', {});
+          if (!env?.auth?.has_mac_token) {
+            const authPayload = await callJsonTool(bridge, 'start_oauth_authorization_raw', {});
+            return toolResult(buildAuthGuideText(authPayload), authPayload);
+          }
+
+          const resolved = await resolveSelectedApp(bridge, params || {});
+          if (resolved.error) {
+            return toolResult(JSON.stringify(resolved.error, null, 2), resolved.error);
+          }
+
+          const overviewArgs = {
+            ...(params?.start_date ? { start_date: params.start_date } : {}),
+            ...(params?.end_date ? { end_date: params.end_date } : {}),
+          };
+
+          const [store, review, community] = await Promise.all([
+            callJsonTool(bridge, 'get_current_app_store_overview_raw', overviewArgs),
+            callJsonTool(bridge, 'get_current_app_review_overview_raw', overviewArgs),
+            callJsonTool(bridge, 'get_current_app_community_overview_raw', overviewArgs),
+          ]);
+
+          const appTitle = resolved.app?.app_title || getCurrentAppLabel(store) || '当前游戏';
+          const brief = buildBriefText(
+            appTitle,
+            { store, review, community },
+            {
+              start_date: params?.start_date,
+              end_date: params?.end_date,
+            }
+          );
+
+          return toolResult(brief, {
+            app: resolved.app,
+            sections: { store, review, community },
+          });
+        } catch (error) {
+          return toolResult(
+            JSON.stringify(
+              {
+                ok: false,
+                error: 'QUICK_BRIEF_FAILED',
+                message: error instanceof Error ? error.message : String(error),
+              },
+              null,
+              2
+            )
+          );
+        }
+      },
+    }),
+    { name: 'taptap_dc_quick_brief' }
+  );
+}
+
 const toolDefinitions = [
   {
     name: 'taptap_dc_check_environment',
@@ -361,6 +662,7 @@ const plugin = {
       config: api.pluginConfig || {},
     });
 
+    registerQuickBriefTool(api, bridge);
     for (const definition of toolDefinitions) {
       registerProxyTool(api, bridge, definition);
     }

package/lib/mcp-bridge.js

@@ -1,5 +1,6 @@
 import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
 import { createRequire } from 'node:module';
@@ -7,34 +8,60 @@ import { fileURLToPath } from 'node:url';
 
 const require = createRequire(import.meta.url);
 const HEADER_SEPARATOR = '\r\n\r\n';
+const RUNTIME_PACKAGE_NAME = '@mikoto_zero/minigame-open-mcp';
+
+function readPluginPackageJson() {
+  try {
+    return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function getRuntimePackageSpec() {
+  const packageJson = readPluginPackageJson();
+  const versionRange = packageJson?.dependencies?.[RUNTIME_PACKAGE_NAME];
+  return versionRange ? `${RUNTIME_PACKAGE_NAME}@${versionRange}` : `${RUNTIME_PACKAGE_NAME}@latest`;
+}
 
 function resolveLocalServerPath() {
   const currentDir = path.dirname(fileURLToPath(import.meta.url));
   return path.resolve(currentDir, '../../../dist/server.js');
 }
 
-function resolveEmbeddedServerPath() {
+function resolveInstalledServerPath() {
   try {
-    const packageJsonPath = require.resolve('@mikoto_zero/minigame-open-mcp/package.json');
+    const packageJsonPath = require.resolve(`${RUNTIME_PACKAGE_NAME}/package.json`);
     const packageRoot = path.dirname(packageJsonPath);
     const serverPath = path.join(packageRoot, 'dist', 'server.js');
     if (existsSync(serverPath)) {
       return serverPath;
     }
   } catch {
-    // Fall through to local dev path
+    // Ignore and keep falling back
   }
+  return null;
+}
 
-  const localServerPath = resolveLocalServerPath();
-  if (existsSync(localServerPath)) {
-    return localServerPath;
-  }
+function getManagedRuntimeRoot(config = {}) {
+  const cacheRoot = config.cacheDir || path.join(os.tmpdir(), 'taptap-openclaw-plugin');
+  return path.join(cacheRoot, 'runtime');
+}
 
-  throw new Error(
-    'Unable to resolve the embedded TapTap MCP server. Make sure @mikoto_zero/minigame-open-mcp is installed.'
+function getManagedRuntimeServerPath(config = {}) {
+  return path.join(
+    getManagedRuntimeRoot(config),
+    'node_modules',
+    RUNTIME_PACKAGE_NAME,
+    'dist',
+    'server.js'
   );
 }
 
+function getNpmExecutable() {
+  return process.platform === 'win32' ? 'npm.cmd' : 'npm';
+}
+
 function parseMessageBuffer(buffer, onMessage) {
   let offset = 0;
 
@@ -87,6 +114,7 @@ export class TapTapMcpBridge {
     this.config = options.config || {};
     this.child = null;
     this.readyPromise = null;
+    this.installPromise = null;
     this.pending = new Map();
     this.nextId = 1;
     this.stdoutBuffer = Buffer.alloc(0);
@@ -98,6 +126,10 @@ export class TapTapMcpBridge {
       TAPTAP_MCP_TRANSPORT: 'stdio',
       TAPTAP_MCP_ENV: this.config.environment || 'production',
       TAPTAP_MCP_ENABLE_RAW_TOOLS: 'true',
+      npm_config_loglevel: process.env.npm_config_loglevel || 'error',
+      npm_config_update_notifier: 'false',
+      npm_config_fund: 'false',
+      npm_config_audit: 'false',
     };
 
     if (this.config.workspaceRoot) {
@@ -119,6 +151,126 @@ export class TapTapMcpBridge {
     return env;
   }
 
+  async resolveRuntimeServer() {
+    const installedServerPath = resolveInstalledServerPath();
+    if (installedServerPath) {
+      return {
+        source: 'package dependency',
+        serverPath: installedServerPath,
+      };
+    }
+
+    const localServerPath = resolveLocalServerPath();
+    if (existsSync(localServerPath)) {
+      return {
+        source: 'local workspace build',
+        serverPath: localServerPath,
+      };
+    }
+
+    const managedServerPath = getManagedRuntimeServerPath(this.config);
+    if (existsSync(managedServerPath)) {
+      return {
+        source: 'plugin runtime cache',
+        serverPath: managedServerPath,
+      };
+    }
+
+    const installedManagedServerPath = await this.installRuntimePackage();
+    return {
+      source: 'plugin runtime cache (fresh install)',
+      serverPath: installedManagedServerPath,
+    };
+  }
+
+  async installRuntimePackage() {
+    if (this.installPromise) {
+      return this.installPromise;
+    }
+
+    this.installPromise = this.installRuntimePackageInternal();
+
+    try {
+      return await this.installPromise;
+    } finally {
+      this.installPromise = null;
+    }
+  }
+
+  async installRuntimePackageInternal() {
+    const runtimeRoot = getManagedRuntimeRoot(this.config);
+    const managedServerPath = getManagedRuntimeServerPath(this.config);
+    const packageSpec = getRuntimePackageSpec();
+    const npmCacheDir = path.join(runtimeRoot, '.npm-cache');
+
+    mkdirSync(runtimeRoot, { recursive: true });
+    mkdirSync(npmCacheDir, { recursive: true });
+
+    this.logger?.info?.(
+      `[TapTap DC] Local TapTap MCP runtime not found, installing ${packageSpec} into ${runtimeRoot}`
+    );
+
+    await new Promise((resolve, reject) => {
+      const child = spawn(
+        getNpmExecutable(),
+        [
+          'install',
+          '--no-save',
+          '--no-package-lock',
+          '--omit=dev',
+          '--prefix',
+          runtimeRoot,
+          packageSpec,
+        ],
+        {
+          env: {
+            ...this.buildEnv(),
+            npm_config_cache: npmCacheDir,
+          },
+          stdio: ['ignore', 'pipe', 'pipe'],
+        }
+      );
+
+      let output = '';
+      const appendOutput = (chunk) => {
+        const text = chunk.toString('utf8');
+        output += text;
+        const trimmed = text.trim();
+        if (trimmed) {
+          this.logger?.info?.(`[TapTap DC][npm] ${trimmed}`);
+        }
+      };
+
+      child.stdout.on('data', appendOutput);
+      child.stderr.on('data', appendOutput);
+
+      child.on('error', (error) => {
+        reject(error);
+      });
+
+      child.on('exit', (code) => {
+        if (code === 0) {
+          resolve();
+          return;
+        }
+
+        reject(
+          new Error(
+            `npm install failed with code ${code ?? 'null'}. ${output.trim() || 'No additional output.'}`
+          )
+        );
+      });
+    });
+
+    if (!existsSync(managedServerPath)) {
+      throw new Error(
+        `TapTap MCP runtime install finished but server entry is still missing: ${managedServerPath}`
+      );
+    }
+
+    return managedServerPath;
+  }
+
   async ensureReady() {
     if (this.readyPromise) {
       return this.readyPromise;
@@ -129,8 +281,12 @@ export class TapTapMcpBridge {
   }
 
   async start() {
-    const serverPath = resolveEmbeddedServerPath();
-    this.child = spawn(process.execPath, [serverPath], {
+    const runtime = await this.resolveRuntimeServer();
+    this.logger?.info?.(
+      `[TapTap DC] Starting embedded TapTap MCP runtime from ${runtime.source}: ${runtime.serverPath}`
+    );
+
+    this.child = spawn(process.execPath, [runtime.serverPath], {
       env: this.buildEnv(),
       stdio: ['pipe', 'pipe', 'pipe'],
     });

package/node_modules/@hono/node-server/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 - present, Yusuke Wada and Hono contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.