@lotaber_wang/openclaw-dc-plugin 0.1.3 → 0.1.5

package/README.md

@@ -9,7 +9,7 @@
 - 运行时解析顺序为：插件内 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_quick_brief` 和 `taptap_dc_start_authorization` 都会直接返回可点击的授权超链接与二维码链接
 - 覆盖授权、选游戏、商店/评价/社区概览、商店快照、论坛内容、评价列表、点赞与官方回复
 - 内置 `taptap-dc-ops-brief`，可把原始数据整理成简洁的运营简报
 
@@ -24,9 +24,10 @@ openclaw plugins install @lotaber_wang/openclaw-dc-plugin
 优先推荐直接使用：
 
 1. 直接调用 `taptap_dc_quick_brief`
-2. 如果还没授权，工具会直接返回扫码链接
-3. 完成扫码后调用 `taptap_dc_complete_authorization`
-4. 再次调用 `taptap_dc_quick_brief`
+2. 如果还没授权，工具会直接返回可点击授权链接
+3. 手机端优先直接点击授权链接；桌面端优先打开二维码后扫码
+4. 完成扫码后调用 `taptap_dc_complete_authorization`
+5. 再次调用 `taptap_dc_quick_brief`
 
 示例：
 
@@ -57,6 +58,25 @@ openclaw plugins install @lotaber_wang/openclaw-dc-plugin
 
 正常情况下，如果内嵌的 TapTap MCP 主包已经带了可用凭据，生产环境不需要额外配置 `client_id` / `client_secret`。
 
+## 运行时环境变量
+
+插件内部会继续向 bundled TapTap MCP runtime 透传或设置这些环境变量：
+
+- `TAPTAP_MCP_TRANSPORT=stdio`
+- `TAPTAP_MCP_ENV`
+- `TAPTAP_MCP_ENABLE_RAW_TOOLS=true`
+- `TAPTAP_MCP_WORKSPACE_ROOT`
+- `TAPTAP_MCP_CACHE_DIR`
+- `TAPTAP_MCP_TEMP_DIR`
+- `TAPTAP_MCP_LOG_ROOT`
+- `TAPTAP_MCP_VERBOSE`
+
+如果你是在 OpenClaw / 容器环境中排查启动问题，优先关注：
+
+- `TAPTAP_MCP_ENV`
+- `TAPTAP_MCP_VERBOSE`
+- `TAPTAP_MCP_LOG_ROOT`
+
 ## 安装排障
 
 如果 OpenClaw 能安装插件，但第一次调用工具仍然偏慢，通常是在启动内嵌 TapTap 运行时，而不是在现场重新下载依赖。
@@ -66,3 +86,11 @@ openclaw plugins install @lotaber_wang/openclaw-dc-plugin
 - 当前环境是否能访问 npm registry
 - 本机 Node 版本是否 >= 18.14.1
 - OpenClaw 进程是否有临时目录写权限
+
+从 `0.1.5` 开始，插件 bridge 会额外做这些兼容处理：
+
+- `initialize` 超时后自动切换到无缓冲 / PTY 启动策略重试
+- `initialize` 默认超时提升到 20 秒，避免宿主启动稍慢时过早失败
+- 兼容解析裸 JSON 输出，不再只接受 `Content-Length` 帧
+- 启动时如果 stdout 混入人类可读日志，会先自动丢弃噪音再解析协议消息
+- 过滤 PTY 场景下被回显到 stdout 的请求消息

package/index.js

@@ -50,6 +50,14 @@ function createSchema(properties = {}, required = []) {
   };
 }
 
+function buildMarkdownLink(label, url) {
+  if (!url) {
+    return '-';
+  }
+
+  return `[${label}](${url})`;
+}
+
 function normalizeText(value) {
   return String(value || '')
     .trim()
@@ -187,11 +195,16 @@ function buildBriefText(appTitle, sections, meta = {}) {
 }
 
 function buildAuthGuideText(authPayload) {
+  const authUrl = authPayload?.auth_url;
+  const qrcodeUrl = authPayload?.qrcode_url;
   const lines = [
     '当前还没有完成 TapTap 授权，请先扫码授权。',
     '',
-    `授权链接：${authPayload?.auth_url || '-'}`,
-    `二维码链接：${authPayload?.qrcode_url || '-'}`,
+    '如果你现在是在手机上对话，优先直接点击下面这个授权链接：',
+    buildMarkdownLink('立即打开授权页面', authUrl),
+    '',
+    '如果你现在是在桌面端对话，可以打开二维码后用 TapTap 扫码授权：',
+    buildMarkdownLink('打开二维码图片', qrcodeUrl),
     '',
     '完成扫码后，请继续调用 `taptap_dc_complete_authorization`，然后再次调用 `taptap_dc_quick_brief`。',
   ];
@@ -200,6 +213,14 @@ function buildAuthGuideText(authPayload) {
     lines.push('', `device_code：${authPayload.device_code}`);
   }
 
+  if (authUrl) {
+    lines.push('', `授权直链：${authUrl}`);
+  }
+
+  if (qrcodeUrl) {
+    lines.push(`二维码直链：${qrcodeUrl}`);
+  }
+
   return lines.join('\n');
 }
 
@@ -276,9 +297,13 @@ function registerProxyTool(api, bridge, definition) {
         try {
           const text = await bridge.callTool(definition.mcpToolName, params || {});
           const normalized = normalizeJsonText(text);
-          return toolResult(normalized, {
+          const parsed = tryParseJson(normalized);
+          const renderedText = definition.resultFormatter
+            ? definition.resultFormatter(parsed, normalized)
+            : normalized;
+          return toolResult(renderedText, {
             mcpToolName: definition.mcpToolName,
-            parsed: tryParseJson(normalized),
+            parsed,
           });
         } catch (error) {
           return toolResult(
@@ -397,9 +422,15 @@ const toolDefinitions = [
     name: 'taptap_dc_start_authorization',
     label: 'TapTap Auth Start',
     description:
-      'Start TapTap OAuth device flow and return auth_url/qrcode_url/device_code as raw JSON.',
+      'Start TapTap OAuth device flow and return a mobile-friendly clickable auth link plus qrcode link.',
     mcpToolName: 'start_oauth_authorization_raw',
     parameters: createSchema(),
+    resultFormatter(parsed, normalized) {
+      if (!parsed || typeof parsed !== 'object') {
+        return normalized;
+      }
+      return buildAuthGuideText(parsed);
+    },
   },
   {
     name: 'taptap_dc_complete_authorization',

package/lib/mcp-bridge.js

@@ -1,4 +1,4 @@
-import { spawn } from 'node:child_process';
+import { spawn, spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -9,6 +9,8 @@ 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';
+const DEFAULT_INIT_TIMEOUT_MS = 20000;
+const ANSI_ESCAPE_REGEX = /\x1B\[[0-?]*[ -/]*[@-~]/g;
 
 function readPluginPackageJson() {
   try {
@@ -62,31 +64,185 @@ function getNpmExecutable() {
   return process.platform === 'win32' ? 'npm.cmd' : 'npm';
 }
 
+function hasCommand(command) {
+  const lookupCommand = process.platform === 'win32' ? 'where' : 'which';
+  const result = spawnSync(lookupCommand, [command], {
+    stdio: 'ignore',
+  });
+  return result.status === 0;
+}
+
+function shellEscape(value) {
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+function stripAnsi(text) {
+  return text.replace(ANSI_ESCAPE_REGEX, '');
+}
+
+function findLikelyFrameStart(buffer) {
+  return buffer.indexOf('Content-Length:', 0, 'utf8');
+}
+
+function findLikelyJsonStart(buffer) {
+  const text = buffer.toString('utf8');
+  const candidates = ['{"jsonrpc"', '{"result"', '{"method"', '{"error"', '[{"jsonrpc"'];
+  let bestIndex = -1;
+
+  for (const candidate of candidates) {
+    const index = text.indexOf(candidate);
+    if (index !== -1 && (bestIndex === -1 || index < bestIndex)) {
+      bestIndex = index;
+    }
+  }
+
+  return bestIndex;
+}
+
+function trimNonProtocolNoise(buffer, logger) {
+  const frameStart = findLikelyFrameStart(buffer);
+  const jsonStart = findLikelyJsonStart(buffer);
+
+  let start = -1;
+  if (frameStart !== -1 && jsonStart !== -1) {
+    start = Math.min(frameStart, jsonStart);
+  } else {
+    start = frameStart !== -1 ? frameStart : jsonStart;
+  }
+
+  if (start > 0) {
+    const dropped = stripAnsi(buffer.subarray(0, start).toString('utf8')).trim();
+    if (dropped) {
+      logger?.info?.(`[TapTap DC] Ignoring non-protocol stdout noise: ${dropped.slice(0, 300)}`);
+    }
+    return buffer.subarray(start);
+  }
+
+  return buffer;
+}
+
+function parseBareJsonMessage(buffer) {
+  const text = buffer.toString('utf8');
+  let start = 0;
+
+  while (start < text.length && /\s/.test(text[start])) {
+    start += 1;
+  }
+
+  const firstChar = text[start];
+  if (firstChar !== '{' && firstChar !== '[') {
+    return null;
+  }
+
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+
+  for (let index = start; index < text.length; index += 1) {
+    const char = text[index];
+
+    if (inString) {
+      if (escaped) {
+        escaped = false;
+        continue;
+      }
+      if (char === '\\') {
+        escaped = true;
+        continue;
+      }
+      if (char === '"') {
+        inString = false;
+      }
+      continue;
+    }
+
+    if (char === '"') {
+      inString = true;
+      continue;
+    }
+
+    if (char === '{' || char === '[') {
+      depth += 1;
+      continue;
+    }
+
+    if (char === '}' || char === ']') {
+      depth -= 1;
+      if (depth === 0) {
+        const raw = text.slice(start, index + 1);
+        return {
+          raw,
+          consumedBytes: Buffer.byteLength(text.slice(0, index + 1), 'utf8'),
+        };
+      }
+    }
+  }
+
+  return undefined;
+}
+
+function findNextMessageOffset(buffer) {
+  const framedIndex = buffer.indexOf('Content-Length:', 0, 'utf8');
+  const jsonIndex = findLikelyJsonStart(buffer);
+
+  if (framedIndex === -1) {
+    return jsonIndex;
+  }
+
+  if (jsonIndex === -1) {
+    return framedIndex;
+  }
+
+  return Math.min(framedIndex, jsonIndex);
+}
+
 function parseMessageBuffer(buffer, onMessage) {
   let offset = 0;
 
   while (offset < buffer.length) {
-    const headerEnd = buffer.indexOf(HEADER_SEPARATOR, offset, 'utf8');
-    if (headerEnd === -1) {
+    while (offset < buffer.length && /\s/.test(String.fromCharCode(buffer[offset]))) {
+      offset += 1;
+    }
+
+    if (offset >= buffer.length) {
       break;
     }
 
-    const headerText = buffer.subarray(offset, headerEnd).toString('utf8');
-    const contentLengthMatch = headerText.match(/content-length:\s*(\d+)/i);
-    if (!contentLengthMatch) {
-      throw new Error(`Missing Content-Length header in MCP frame: ${headerText}`);
+    const headerEnd = buffer.indexOf(HEADER_SEPARATOR, offset, 'utf8');
+    if (headerEnd !== -1) {
+      const headerText = buffer.subarray(offset, headerEnd).toString('utf8');
+      const contentLengthMatch = headerText.match(/content-length:\s*(\d+)/i);
+      if (contentLengthMatch) {
+        const contentLength = Number(contentLengthMatch[1]);
+        const bodyStart = headerEnd + HEADER_SEPARATOR.length;
+        const bodyEnd = bodyStart + contentLength;
+        if (buffer.length < bodyEnd) {
+          break;
+        }
+
+        const bodyText = buffer.subarray(bodyStart, bodyEnd).toString('utf8');
+        onMessage(JSON.parse(bodyText));
+        offset = bodyEnd;
+        continue;
+      }
+    }
+
+    const bareJson = parseBareJsonMessage(buffer.subarray(offset));
+    if (bareJson) {
+      onMessage(JSON.parse(bareJson.raw));
+      offset += bareJson.consumedBytes;
+      continue;
     }
 
-    const contentLength = Number(contentLengthMatch[1]);
-    const bodyStart = headerEnd + HEADER_SEPARATOR.length;
-    const bodyEnd = bodyStart + contentLength;
-    if (buffer.length < bodyEnd) {
+    if (bareJson === undefined) {
       break;
     }
 
-    const bodyText = buffer.subarray(bodyStart, bodyEnd).toString('utf8');
-    onMessage(JSON.parse(bodyText));
-    offset = bodyEnd;
+    const nextOffset = findNextMessageOffset(buffer.subarray(offset + 1));
+    if (nextOffset === -1) {
+      break;
+    }
+    offset += nextOffset + 1;
   }
 
   return buffer.subarray(offset);
@@ -116,6 +272,7 @@ export class TapTapMcpBridge {
     this.readyPromise = null;
     this.installPromise = null;
     this.pending = new Map();
+    this.outboundMessages = [];
     this.nextId = 1;
     this.stdoutBuffer = Buffer.alloc(0);
   }
@@ -282,66 +439,39 @@ export class TapTapMcpBridge {
 
   async start() {
     const runtime = await this.resolveRuntimeServer();
-    this.logger?.info?.(
-      `[TapTap DC] Starting embedded TapTap MCP runtime from ${runtime.source}: ${runtime.serverPath}`
-    );
+    const launchAttempts = this.getLaunchAttempts(runtime.serverPath);
+    const errors = [];
 
-    this.child = spawn(process.execPath, [runtime.serverPath], {
-      env: this.buildEnv(),
-      stdio: ['pipe', 'pipe', 'pipe'],
-    });
+    for (const attempt of launchAttempts) {
+      this.logger?.info?.(
+        `[TapTap DC] Starting embedded TapTap MCP runtime from ${runtime.source} using ${attempt.label}: ${runtime.serverPath}`
+      );
+
+      this.spawnChild(attempt.command, attempt.args);
 
-    this.child.stdout.on('data', (chunk) => {
       try {
-        this.stdoutBuffer = Buffer.concat([this.stdoutBuffer, chunk]);
-        this.stdoutBuffer = parseMessageBuffer(this.stdoutBuffer, (message) =>
-          this.handleMessage(message)
-        );
+        await this.initializeServer();
+        return;
       } catch (error) {
-        this.logger?.error?.(
-          `[TapTap DC] Failed to parse MCP stdout: ${
-            error instanceof Error ? error.message : String(error)
-          }`
+        const message = error instanceof Error ? error.message : String(error);
+        errors.push(`${attempt.label}: ${message}`);
+        this.logger?.info?.(
+          `[TapTap DC] Runtime start attempt failed via ${attempt.label}, retrying if possible: ${message}`
         );
+        await this.close();
       }
-    });
-
-    this.child.stderr.on('data', (chunk) => {
-      const text = chunk.toString('utf8').trim();
-      if (text) {
-        this.logger?.info?.(`[TapTap MCP] ${text}`);
-      }
-    });
-
-    this.child.on('exit', (code, signal) => {
-      const error = new Error(
-        `Embedded TapTap MCP server exited unexpectedly (code=${code ?? 'null'}, signal=${signal ?? 'null'}).`
-      );
-      for (const pending of this.pending.values()) {
-        pending.reject(error);
-      }
-      this.pending.clear();
-      this.child = null;
-      this.readyPromise = null;
-    });
-
-    await this.request('initialize', {
-      protocolVersion: '2025-11-25',
-      capabilities: {
-        tools: {},
-        resources: {},
-        logging: {},
-      },
-      clientInfo: {
-        name: 'taptap-openclaw-dc-plugin',
-        version: '0.1.0',
-      },
-    });
+    }
 
-    this.notify('notifications/initialized', {});
+    throw new Error(
+      `Failed to start embedded TapTap MCP runtime. Attempts: ${errors.join(' | ')}`
+    );
   }
 
   handleMessage(message) {
+    if (this.isEchoedOutboundMessage(message)) {
+      return;
+    }
+
     if (message.id !== undefined && this.pending.has(message.id)) {
       const pending = this.pending.get(message.id);
       this.pending.delete(message.id);
@@ -361,6 +491,15 @@ export class TapTapMcpBridge {
       throw new Error('Embedded TapTap MCP server is not running.');
     }
 
+    this.outboundMessages.push({
+      id: message.id,
+      method: message.method,
+      payload: JSON.stringify(message),
+    });
+    if (this.outboundMessages.length > 20) {
+      this.outboundMessages.shift();
+    }
+
     const body = JSON.stringify(message);
     const frame = `Content-Length: ${Buffer.byteLength(body, 'utf8')}\r\n\r\n${body}`;
     this.child.stdin.write(frame, 'utf8');
@@ -403,5 +542,129 @@ export class TapTapMcpBridge {
       this.child = null;
       this.readyPromise = null;
     }
+    this.pending.clear();
+    this.outboundMessages = [];
+  }
+
+  getLaunchAttempts(serverPath) {
+    const attempts = [
+      {
+        label: 'direct stdio',
+        command: process.execPath,
+        args: [serverPath],
+      },
+    ];
+
+    if (hasCommand('stdbuf')) {
+      attempts.push({
+        label: 'stdbuf unbuffered stdio',
+        command: 'stdbuf',
+        args: ['-i0', '-o0', '-e0', process.execPath, serverPath],
+      });
+    }
+
+    if (process.platform === 'darwin' && hasCommand('script')) {
+      attempts.push({
+        label: 'script pty wrapper',
+        command: 'script',
+        args: ['-q', '/dev/null', process.execPath, serverPath],
+      });
+    }
+
+    if (process.platform === 'linux' && hasCommand('script')) {
+      attempts.push({
+        label: 'script pty wrapper',
+        command: 'script',
+        args: ['-q', '-e', '-c', `${shellEscape(process.execPath)} ${shellEscape(serverPath)}`, '/dev/null'],
+      });
+    }
+
+    return attempts;
+  }
+
+  spawnChild(command, args) {
+    this.child = spawn(command, args, {
+      env: this.buildEnv(),
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+
+    this.stdoutBuffer = Buffer.alloc(0);
+
+    this.child.stdout.on('data', (chunk) => {
+      try {
+        this.stdoutBuffer = Buffer.concat([this.stdoutBuffer, chunk]);
+        this.stdoutBuffer = trimNonProtocolNoise(this.stdoutBuffer, this.logger);
+        this.stdoutBuffer = parseMessageBuffer(this.stdoutBuffer, (message) =>
+          this.handleMessage(message)
+        );
+      } catch (error) {
+        this.logger?.error?.(
+          `[TapTap DC] Failed to parse MCP stdout: ${
+            error instanceof Error ? error.message : String(error)
+          }`
+        );
+        this.stdoutBuffer = trimNonProtocolNoise(this.stdoutBuffer, this.logger);
+      }
+    });
+
+    this.child.stderr.on('data', (chunk) => {
+      const text = chunk.toString('utf8').trim();
+      if (text) {
+        this.logger?.info?.(`[TapTap MCP] ${text}`);
+      }
+    });
+
+    this.child.on('exit', (code, signal) => {
+      const error = new Error(
+        `Embedded TapTap MCP server exited unexpectedly (code=${code ?? 'null'}, signal=${signal ?? 'null'}).`
+      );
+      for (const pending of this.pending.values()) {
+        pending.reject(error);
+      }
+      this.pending.clear();
+      this.child = null;
+      this.readyPromise = null;
+    });
+  }
+
+  async initializeServer() {
+    await Promise.race([
+      this.request('initialize', {
+        protocolVersion: '2025-11-25',
+        capabilities: {
+          tools: {},
+          resources: {},
+          logging: {},
+        },
+        clientInfo: {
+          name: 'taptap-openclaw-dc-plugin',
+          version: '0.1.0',
+        },
+      }),
+      new Promise((_, reject) => {
+        setTimeout(() => {
+          reject(
+            new Error(
+              `Initialize handshake timed out after ${DEFAULT_INIT_TIMEOUT_MS}ms`
+            )
+          );
+        }, DEFAULT_INIT_TIMEOUT_MS);
+      }),
+    ]);
+
+    this.notify('notifications/initialized', {});
+  }
+
+  isEchoedOutboundMessage(message) {
+    if (!message || typeof message !== 'object' || !message.method) {
+      return false;
+    }
+
+    const payload = JSON.stringify(message);
+    return this.outboundMessages.some(
+      (entry) =>
+        entry.payload === payload ||
+        (entry.id !== undefined && entry.id === message.id && entry.method === message.method)
+    );
   }
 }

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "taptap-dc-plugin",
   "name": "TapTap DC",
   "description": "面向 OpenClaw 的 TapTap DC 插件，内置原始数据工具与运营简报 skill。",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "skills": ["./skills"],
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotaber_wang/openclaw-dc-plugin",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "description": "TapTap DC 的 OpenClaw 插件，内置原始数据工具与运营简报 skill。",
   "main": "index.js",

package/skills/taptap-dc-ops-brief/SKILL.md

@@ -19,8 +19,9 @@ description: 生成 TapTap 当前游戏 DC 运营简报与结论解读（商店/
    - 如果用户给了游戏名，直接把 `app_name` 传进去
    - 如果用户给了 `app_id`，直接把 `app_id` 传进去
 2. 如果未授权
-   - `taptap_dc_quick_brief` 会直接返回 `auth_url` / `qrcode_url`
-   - 让用户打开 `auth_url` 或扫描 `qrcode_url`
+   - `taptap_dc_quick_brief` 会直接返回 markdown 授权链接和二维码链接
+   - 如果用户当前在手机上对话，优先引导用户直接点击授权链接
+   - 如果用户当前在桌面端对话，再引导用户打开二维码并扫码
    - 用户确认后调用 `taptap_dc_complete_authorization`
    - 然后再次调用 `taptap_dc_quick_brief`
 3. 只有在用户明确要求更细的内容时，才退回到底层工具链
@@ -44,6 +45,7 @@ description: 生成 TapTap 当前游戏 DC 运营简报与结论解读（商店/
 ## 关键规则
 
 - 这些 plugin tools 返回的是 **raw JSON**，你要自己完成解读，不要把 JSON 原样长篇贴回给用户
+- 当授权工具已经返回可点击 markdown 链接时，优先直接复用它，不要再把链接改写成纯文本说明
 - `page_view_count` 应写成“详情页访问量（PV）”，不要偷换成别的口径
 - `taptap_dc_like_review` / `taptap_dc_reply_review` 只能在用户明确确认后调用
 - 如果回复结果里出现 `need_confirmation=true`，必须先把草稿给用户确认，再决定是否带 `confirm_high_risk=true` 重试