@lotaber_wang/openclaw-dc-plugin 0.1.9 → 0.1.11

package/README.md

@@ -16,7 +16,7 @@
 ## 安装
 
 ```bash
-openclaw plugins install @lotaber_wang/openclaw-dc-plugin@0.1.9
+openclaw plugins install @lotaber_wang/openclaw-dc-plugin@0.1.11
 ```
 
 安装完成后，建议立刻执行一次检查：
@@ -31,7 +31,7 @@ openclaw plugins inspect openclaw-dc-plugin
 
 推荐通知文案：
 
-`TapTap DC 插件已安装完成。OpenClaw 接下来会重启 Gateway；重启完成后即可使用 taptap_dc_* 工具。`
+`TapTap DC 插件已安装完成。OpenClaw 接下来如需重启 Gateway，应先提示用户；重启完成后即可使用 taptap_dc_* 工具。`
 
 执行顺序要求：
 
@@ -52,9 +52,9 @@ openclaw gateway restart
 ## 推荐安装流程
 
 ```bash
-openclaw plugins install @lotaber_wang/openclaw-dc-plugin@0.1.9
+openclaw plugins install @lotaber_wang/openclaw-dc-plugin@0.1.11
 openclaw plugins inspect openclaw-dc-plugin
-echo 'TapTap DC 插件已安装完成。OpenClaw 接下来会重启 Gateway；重启完成后即可使用 taptap_dc_* 工具。'
+echo 'TapTap DC 插件已安装完成。OpenClaw 接下来如需重启 Gateway，应先提示用户；重启完成后即可使用 taptap_dc_* 工具。'
 openclaw gateway restart
 ```
 
@@ -64,6 +64,7 @@ openclaw gateway restart
 - `inspect` 用来确认插件元信息、skills、tools 是否已被 Gateway 识别
 - 如果宿主判断需要重启 Gateway，必须先通知用户，再重启
 - 如果 10-30 秒后还没生效，再手动执行 `gateway restart`
+- 如果宿主存在“stock 安装失败后再 fallback npm”的行为，优先使用明确版本号安装，必要时改用本地 `.tgz` 安装，避免双安装链路互相打架
 
 ## 典型使用流程
 
@@ -129,7 +130,7 @@ openclaw gateway restart
 
 如果安装后看不到 `taptap_dc_*` 工具，优先按这个顺序排查：
 
-1. 确认安装的是 `@lotaber_wang/openclaw-dc-plugin@0.1.9` 或更新版本
+1. 确认安装的是 `@lotaber_wang/openclaw-dc-plugin@0.1.11` 或更新版本
 2. 执行 `openclaw plugins inspect openclaw-dc-plugin`
 3. 如果宿主要求重启 Gateway，先向用户发送安装完成提示
 4. 再执行 `openclaw gateway restart`
@@ -157,11 +158,14 @@ openclaw gateway restart
 - OpenClaw 进程是否有临时目录写权限
 - OpenClaw 是否已经完成 Gateway 重启
 
-从 `0.1.9` 开始，插件安装链路与 bridge 会额外做这些兼容处理：
+从 `0.1.11` 开始，插件安装链路与 bridge 会额外做这些兼容处理：
 
 - 在 `package.json` 中补充 `openclaw.install.npmSpec`，让安装链路更稳定
+- 在 `package.json` 的 `openclaw.install` 中补充 `postInstallMessage` / `instructions` / `restartCommand`
+- 插件导出对象会同步暴露 `installation` / `installHints`，给宿主额外一层安装提示兜底
 - 在 `openclaw.plugin.json` 中显式开启 `enabledByDefault`
 - 统一插件 id 为 `openclaw-dc-plugin`，避免 manifest id 与 entry hint 不一致
+- 默认仅保留错误级别注册/bridge 日志；详细日志改为 `verbose=true` 时才输出，减少安装后自动重载时的噪音
 - `initialize` 超时后自动切换到无缓冲 / PTY 启动策略重试
 - `initialize` 默认超时提升到 45 秒，避免宿主启动稍慢时过早失败
 - 向内嵌 TapTap runtime 发送 `initialize` 与后续请求时，默认改为裸 JSON + 换行（NDJSON 风格），避免只发 `Content-Length` 帧导致无响应
@@ -170,4 +174,4 @@ openclaw gateway restart
 - 启动时如果 stdout 混入人类可读日志，会先自动丢弃噪音再解析协议消息
 - 如果拿到的是半截 JSON，会先继续等待后续分片，而不是立刻按失败处理
 - 过滤 PTY 场景下被回显到 stdout 的请求消息
-- 授权结果会优先把“直接点击授权”链接放在第一位，方便移动端对话直接打开
+- 授权结果会把裸授权直链放在最前面，并在 `details.preferred_auth_url` / `details.auth_links` 中重复返回，降低宿主偶发吞链路时的影响

package/index.js

@@ -1,6 +1,16 @@
 import { readFileSync } from 'node:fs';
+import process from 'node:process';
 import { TapTapMcpBridge } from './lib/mcp-bridge.js';
 
+const RESTART_NOTICE =
+  'TapTap DC 插件已安装完成。OpenClaw 接下来如需重启 Gateway，应先提示用户；重启完成后即可使用 taptap_dc_* 工具。';
+
+const INSTALLATION_GUIDANCE = [
+  '如果安装流程判断需要重启 Gateway，先通知用户，再执行重启。',
+  `推荐提示文案：${RESTART_NOTICE}`,
+  '执行顺序：先提示用户 -> 再执行 gateway restart -> 重启完成后再开始使用 taptap_dc_* 工具。',
+];
+
 function toolResult(text, details = {}) {
   return {
     content: [{ type: 'text', text }],
@@ -98,15 +108,60 @@ function enrichAuthPayload(authPayload) {
     null;
 
   const wrappedAuthUrl = authPayload.wrapped_auth_url || authPayload.auth_url || null;
+  const preferredAuthUrl = directAuthUrl || wrappedAuthUrl || null;
+  const authLinks = [
+    preferredAuthUrl
+      ? {
+          kind: 'preferred',
+          label: '直接点击授权',
+          url: preferredAuthUrl,
+        }
+      : null,
+    directAuthUrl && directAuthUrl !== preferredAuthUrl
+      ? {
+          kind: 'direct',
+          label: '授权直链',
+          url: directAuthUrl,
+        }
+      : null,
+    wrappedAuthUrl && wrappedAuthUrl !== preferredAuthUrl
+      ? {
+          kind: 'wrapped',
+          label: 'TapTap 包装授权页',
+          url: wrappedAuthUrl,
+        }
+      : null,
+    authPayload.qrcode_url && authPayload.qrcode_url !== preferredAuthUrl
+      ? {
+          kind: 'qrcode',
+          label: '授权页直链',
+          url: authPayload.qrcode_url,
+        }
+      : null,
+  ].filter(Boolean);
 
   return {
     ...authPayload,
     direct_auth_url: directAuthUrl,
     wrapped_auth_url: wrappedAuthUrl,
-    preferred_auth_url: directAuthUrl || wrappedAuthUrl || null,
+    preferred_auth_url: preferredAuthUrl,
+    authorization_url: preferredAuthUrl,
+    mobile_auth_url: preferredAuthUrl,
+    auth_links: authLinks,
+    next_action:
+      '优先打开 preferred_auth_url 完成授权；完成后调用 taptap_dc_complete_authorization。',
   };
 }
 
+function isVerboseLoggingEnabled(config = {}) {
+  return (
+    config?.verbose === true ||
+    String(process.env.TAPTAP_MCP_VERBOSE || '')
+      .trim()
+      .toLowerCase() === 'true'
+  );
+}
+
 function normalizeText(value) {
   return String(value || '')
     .trim()
@@ -245,37 +300,61 @@ function buildBriefText(appTitle, sections, meta = {}) {
 
 function buildAuthGuideText(authPayload) {
   const enriched = enrichAuthPayload(authPayload);
+  if (enriched?.authorized || enriched?.already_authorized) {
+    return [
+      'TapTap 授权已完成，无需再次扫码或打开授权链接。',
+      '如果你刚完成授权，接下来可直接调用 `taptap_dc_quick_brief` 或其他 `taptap_dc_*` 工具。',
+    ].join('\n');
+  }
+
+  const preferredAuthUrl = enriched?.preferred_auth_url;
   const directAuthUrl = enriched?.direct_auth_url;
   const wrappedAuthUrl = enriched?.wrapped_auth_url;
   const qrcodeUrl = enriched?.qrcode_url;
-  const lines = [
-    '当前还没有完成 TapTap 授权，请先完成一次授权。',
-    '',
-    '如果你现在是在手机上或当前客户端支持超链接，请优先点击下面这条直接授权链接，不用扫码：',
-    buildMarkdownLink('直接点击授权', directAuthUrl),
-    '',
-    '如果上面的链接打不开，再尝试这个 TapTap 包装授权页：',
-    buildMarkdownLink('打开 TapTap 包装授权页', wrappedAuthUrl),
-    '',
-    '如果你需要在桌面端继续，或者想把授权页转给另一台设备，也可以使用这个直链自行打开或生成二维码：',
-    buildMarkdownLink('打开授权页直链', qrcodeUrl || directAuthUrl),
+  const lines = ['当前还没有完成 TapTap 授权，请先完成一次授权。'];
+
+  if (preferredAuthUrl) {
+    lines.push(
+      '',
+      '优先打开下面这条授权直链。这一行会同时保留裸链接，方便手机端直接点击，或在宿主吞掉超链接时复制打开：',
+      preferredAuthUrl,
+      `<${preferredAuthUrl}>`
+    );
+  }
+
+  if (preferredAuthUrl || directAuthUrl || wrappedAuthUrl || qrcodeUrl) {
+    lines.push(
+      '',
+      '可点击版本：',
+      `- ${buildMarkdownLink('直接点击授权', preferredAuthUrl || directAuthUrl)}`,
+      `- ${buildMarkdownLink('打开 TapTap 包装授权页', wrappedAuthUrl)}`,
+      `- ${buildMarkdownLink('打开授权页直链', qrcodeUrl || directAuthUrl || preferredAuthUrl)}`
+    );
+  }
+
+  lines.push(
     '',
-    '完成扫码后，请继续调用 `taptap_dc_complete_authorization`，然后再次调用 `taptap_dc_quick_brief`。',
-  ];
+    '如果你在手机上对话，优先直接点上面的第一条裸链接；如果超链接显示异常，优先使用 details.preferred_auth_url。',
+    '完成授权后，请继续调用 `taptap_dc_complete_authorization`，然后再次调用 `taptap_dc_quick_brief`。'
+  );
 
   if (enriched?.device_code) {
     lines.push('', `device_code：${enriched.device_code}`);
   }
 
-  if (directAuthUrl) {
+  if (preferredAuthUrl) {
+    lines.push('', `preferred_auth_url：${preferredAuthUrl}`);
+  }
+
+  if (directAuthUrl && directAuthUrl !== preferredAuthUrl) {
     lines.push('', `直接授权链接：${directAuthUrl}`);
   }
 
-  if (wrappedAuthUrl && wrappedAuthUrl !== directAuthUrl) {
+  if (wrappedAuthUrl && wrappedAuthUrl !== preferredAuthUrl) {
     lines.push(`TapTap 包装授权链接：${wrappedAuthUrl}`);
   }
 
-  if (qrcodeUrl && qrcodeUrl !== directAuthUrl) {
+  if (qrcodeUrl && qrcodeUrl !== preferredAuthUrl) {
     lines.push(`授权页直链：${qrcodeUrl}`);
   }
 
@@ -385,6 +464,23 @@ function registerProxyTool(api, bridge, definition) {
   );
 }
 
+function safeRegisterTool(api, logger, verbose, registerFn, toolName) {
+  try {
+    registerFn();
+    if (verbose) {
+      logger?.info?.(`[TapTap DC] Registered OpenClaw tool: ${toolName}`);
+    }
+    return true;
+  } catch (error) {
+    logger?.error?.(
+      `[TapTap DC] Failed to register OpenClaw tool ${toolName}: ${
+        error instanceof Error ? error.stack || error.message : String(error)
+      }`
+    );
+    return false;
+  }
+}
+
 function registerQuickBriefTool(api, bridge) {
   api.registerTool(
     () => ({
@@ -725,7 +821,18 @@ try {
 const plugin = {
   id: 'openclaw-dc-plugin',
   name: 'TapTap DC',
-  description: '面向 OpenClaw 的 TapTap DC 插件，内置原始数据工具与运营简报 skill。',
+  description:
+    '面向 OpenClaw 的 TapTap DC 插件，内置原始数据工具与运营简报 skill；如需重启 Gateway，应先提示用户。',
+  installation: {
+    restartRequired: true,
+    restartCommand: 'openclaw gateway restart',
+    postInstallMessage: RESTART_NOTICE,
+    instructions: INSTALLATION_GUIDANCE,
+  },
+  installHints: {
+    beforeRestartMessage: RESTART_NOTICE,
+    instructions: INSTALLATION_GUIDANCE,
+  },
   configSchema: {
     type: 'object',
     properties: {
@@ -754,14 +861,70 @@ const plugin = {
     additionalProperties: false,
   },
   register(api) {
-    const bridge = new TapTapMcpBridge({
-      logger: api.logger,
-      config: api.pluginConfig || {},
-    });
+    const logger = api.logger;
+    const verbose = isVerboseLoggingEnabled(api.pluginConfig || {});
+    if (verbose) {
+      logger?.info?.('[TapTap DC] Starting OpenClaw plugin registration');
+    }
+
+    let bridge;
+    try {
+      bridge = new TapTapMcpBridge({
+        logger,
+        config: api.pluginConfig || {},
+      });
+    } catch (error) {
+      logger?.error?.(
+        `[TapTap DC] Failed to create TapTapMcpBridge during registration: ${
+          error instanceof Error ? error.stack || error.message : String(error)
+        }`
+      );
+      throw error;
+    }
+
+    let successCount = 0;
+
+    if (
+      safeRegisterTool(
+        api,
+        logger,
+        verbose,
+        () => registerQuickBriefTool(api, bridge),
+        'taptap_dc_quick_brief'
+      )
+    ) {
+      successCount += 1;
+    }
 
-    registerQuickBriefTool(api, bridge);
     for (const definition of toolDefinitions) {
-      registerProxyTool(api, bridge, definition);
+      if (
+        safeRegisterTool(
+          api,
+          logger,
+          verbose,
+          () => registerProxyTool(api, bridge, definition),
+          definition.name
+        )
+      ) {
+        successCount += 1;
+      }
+    }
+
+    if (successCount !== toolDefinitions.length + 1) {
+      logger?.error?.(
+        `[TapTap DC] OpenClaw plugin registration incomplete: ${successCount}/${
+          toolDefinitions.length + 1
+        } tools registered`
+      );
+      return;
+    }
+
+    if (verbose) {
+      logger?.info?.(
+        `[TapTap DC] OpenClaw plugin registration completed: ${successCount}/${
+          toolDefinitions.length + 1
+        } tools registered`
+      );
     }
   },
 };

package/lib/mcp-bridge.js

@@ -333,6 +333,11 @@ export class TapTapMcpBridge {
   constructor(options = {}) {
     this.logger = options.logger;
     this.config = options.config || {};
+    this.verbose =
+      this.config.verbose === true ||
+      String(process.env.TAPTAP_MCP_VERBOSE || '')
+        .trim()
+        .toLowerCase() === 'true';
     this.child = null;
     this.readyPromise = null;
     this.installPromise = null;
@@ -342,6 +347,12 @@ export class TapTapMcpBridge {
     this.stdoutBuffer = Buffer.alloc(0);
   }
 
+  logInfo(message) {
+    if (this.verbose) {
+      this.logger?.info?.(message);
+    }
+  }
+
   buildEnv() {
     const env = {
       ...process.env,
@@ -428,7 +439,7 @@ export class TapTapMcpBridge {
     mkdirSync(runtimeRoot, { recursive: true });
     mkdirSync(npmCacheDir, { recursive: true });
 
-    this.logger?.info?.(
+    this.logInfo(
       `[TapTap DC] Local TapTap MCP runtime not found, installing ${packageSpec} into ${runtimeRoot}`
     );
 
@@ -459,7 +470,7 @@ export class TapTapMcpBridge {
         output += text;
         const trimmed = text.trim();
         if (trimmed) {
-          this.logger?.info?.(`[TapTap DC][npm] ${trimmed}`);
+          this.logInfo(`[TapTap DC][npm] ${trimmed}`);
         }
       };
 
@@ -508,7 +519,7 @@ export class TapTapMcpBridge {
     const errors = [];
 
     for (const attempt of launchAttempts) {
-      this.logger?.info?.(
+      this.logInfo(
         `[TapTap DC] Starting embedded TapTap MCP runtime from ${runtime.source} using ${attempt.label}: ${runtime.serverPath}`
       );
 
@@ -520,7 +531,7 @@ export class TapTapMcpBridge {
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         errors.push(`${attempt.label}: ${message}`);
-        this.logger?.info?.(
+        this.logInfo(
           `[TapTap DC] Runtime start attempt failed via ${attempt.label}, retrying if possible: ${message}`
         );
         await this.close();
@@ -657,11 +668,11 @@ export class TapTapMcpBridge {
     this.child.stdout.on('data', (chunk) => {
       try {
         this.stdoutBuffer = Buffer.concat([this.stdoutBuffer, chunk]);
-        this.stdoutBuffer = trimNonProtocolNoise(this.stdoutBuffer, this.logger);
+        this.stdoutBuffer = trimNonProtocolNoise(this.stdoutBuffer, this.verbose ? this.logger : null);
         this.stdoutBuffer = parseMessageBuffer(
           this.stdoutBuffer,
           (message) => this.handleMessage(message),
-          this.logger
+          this.verbose ? this.logger : null
         );
       } catch (error) {
         this.logger?.error?.(
@@ -669,14 +680,14 @@ export class TapTapMcpBridge {
             error instanceof Error ? error.message : String(error)
           }`
         );
-        this.stdoutBuffer = trimNonProtocolNoise(this.stdoutBuffer, this.logger);
+        this.stdoutBuffer = trimNonProtocolNoise(this.stdoutBuffer, this.verbose ? this.logger : null);
       }
     });
 
     this.child.stderr.on('data', (chunk) => {
       const text = chunk.toString('utf8').trim();
       if (text) {
-        this.logger?.info?.(`[TapTap MCP] ${text}`);
+        this.logInfo(`[TapTap MCP] ${text}`);
       }
     });
 

package/openclaw.plugin.json

@@ -1,8 +1,8 @@
 {
   "id": "openclaw-dc-plugin",
   "name": "TapTap DC",
-  "description": "面向 OpenClaw 的 TapTap DC 插件，内置原始数据工具与运营简报 skill。",
-  "version": "0.1.9",
+  "description": "面向 OpenClaw 的 TapTap DC 插件，内置原始数据工具与运营简报 skill；如需重启 Gateway，应先提示用户。",
+  "version": "0.1.11",
   "enabledByDefault": true,
   "skills": ["./skills"],
   "configSchema": {

package/package.json

@@ -1,15 +1,23 @@
 {
   "name": "@lotaber_wang/openclaw-dc-plugin",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "type": "module",
-  "description": "TapTap DC 的 OpenClaw 插件，内置原始数据工具与运营简报 skill。",
+  "description": "TapTap DC 的 OpenClaw 插件，内置原始数据工具与运营简报 skill；如需重启 Gateway，应先提示用户。",
   "main": "index.js",
   "openclaw": {
     "extensions": [
       "./index.js"
     ],
     "install": {
-      "npmSpec": "@lotaber_wang/openclaw-dc-plugin"
+      "npmSpec": "@lotaber_wang/openclaw-dc-plugin",
+      "postInstallMessage": "TapTap DC 插件已安装完成。OpenClaw 接下来如需重启 Gateway，应先提示用户；重启完成后即可使用 taptap_dc_* 工具。",
+      "restartRequired": true,
+      "restartCommand": "openclaw gateway restart",
+      "instructions": [
+        "如果安装流程判断需要重启 Gateway，先通知用户，再执行重启。",
+        "推荐提示文案：TapTap DC 插件已安装完成。OpenClaw 接下来如需重启 Gateway，应先提示用户；重启完成后即可使用 taptap_dc_* 工具。",
+        "执行顺序：先提示用户 -> 再执行 gateway restart -> 重启完成后再开始使用 taptap_dc_* 工具。"
+      ]
     }
   },
   "exports": {

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

@@ -19,8 +19,8 @@ description: 生成 TapTap 当前游戏 DC 运营简报与结论解读（商店/
    - 如果用户给了游戏名，直接把 `app_name` 传进去
    - 如果用户给了 `app_id`，直接把 `app_id` 传进去
 2. 如果未授权
-   - `taptap_dc_quick_brief` 会直接返回 markdown 授权链接，其中第一条通常就是可直接点击完成授权的链接
-   - 如果用户当前在手机上对话，优先引导用户直接点击第一条“直接点击授权”链接，不要先强调扫码
+   - `taptap_dc_quick_brief` 会直接返回授权信息，其中最前面的裸链接和 `details.preferred_auth_url` 都应视为首选授权入口
+   - 如果用户当前在手机上对话，优先引导用户直接点击第一条裸链接，不要先强调扫码
    - 如果用户当前在桌面端对话，再引导用户打开授权页直链并扫码或转发到手机
    - 用户确认后调用 `taptap_dc_complete_authorization`
    - 然后再次调用 `taptap_dc_quick_brief`
@@ -45,7 +45,7 @@ description: 生成 TapTap 当前游戏 DC 运营简报与结论解读（商店/
 ## 关键规则
 
 - 这些 plugin tools 返回的是 **raw JSON**，你要自己完成解读，不要把 JSON 原样长篇贴回给用户
-- 当授权工具已经返回可点击 markdown 链接时，优先直接复用第一条直链，不要再把它改写成“去扫二维码”
+- 当授权工具已经返回授权链接时，优先直接复用第一条裸直链；如果文本里链接缺失，就从 `details.preferred_auth_url` 取值，不要直接退化成“去扫二维码”
 - `page_view_count` 应写成“详情页访问量（PV）”，不要偷换成别的口径
 - `taptap_dc_like_review` / `taptap_dc_reply_review` 只能在用户明确确认后调用
 - 如果回复结果里出现 `need_confirmation=true`，必须先把草稿给用户确认，再决定是否带 `confirm_high_risk=true` 重试