@lotaber_wang/openclaw-dc-plugin 0.1.6 → 0.1.8

package/README.md

@@ -9,23 +9,51 @@
 - 运行时解析顺序为：插件内 bundled runtime -> 本地已安装 runtime -> 本地缓存 runtime
 - 暴露适合 agent / skill 消费的 TapTap DC 原始 JSON 工具
 - 提供高层工具 `taptap_dc_quick_brief`，可直接按游戏名 / app_id 生成 TapTap DC 快速简报
-- 如果当前未授权，`taptap_dc_quick_brief` 和 `taptap_dc_start_authorization` 都会直接返回可点击的授权超链接与二维码链接
+- 如果当前未授权，`taptap_dc_quick_brief` 和 `taptap_dc_start_authorization` 都会优先返回“可直接点击的授权链接”，并附带 TapTap 包装链接与授权页直链
 - 覆盖授权、选游戏、商店/评价/社区概览、商店快照、论坛内容、评价列表、点赞与官方回复
 - 内置 `taptap-dc-ops-brief`，可把原始数据整理成简洁的运营简报
 
 ## 安装
 
 ```bash
-openclaw plugins install @lotaber_wang/openclaw-dc-plugin
+openclaw plugins install @lotaber_wang/openclaw-dc-plugin@0.1.8
 ```
 
+安装完成后，建议立刻执行一次检查：
+
+```bash
+openclaw plugins inspect taptap-dc-plugin
+```
+
+如果安装成功但当前会话里还看不到 `taptap_dc_*` 工具，请重启 Gateway：
+
+```bash
+openclaw gateway restart
+```
+
+如果你的环境没有 `openclaw gateway restart`，就直接完整重启 OpenClaw / 宿主应用。
+
+## 推荐安装流程
+
+```bash
+openclaw plugins install @lotaber_wang/openclaw-dc-plugin@0.1.8
+openclaw plugins inspect taptap-dc-plugin
+openclaw gateway restart
+```
+
+说明：
+
+- `install` 负责把插件包装进 OpenClaw
+- `inspect` 用来确认插件元信息、skills、tools 是否已被 Gateway 识别
+- `gateway restart` 用来让最新插件配置真正生效；很多“装上了但没看到 tools”的问题都出在这里
+
 ## 典型使用流程
 
 优先推荐直接使用：
 
 1. 直接调用 `taptap_dc_quick_brief`
 2. 如果还没授权，工具会直接返回可点击授权链接
-3. 手机端优先直接点击授权链接；桌面端优先打开二维码后扫码
+3. 手机端优先直接点击第一条“直接点击授权”链接；桌面端可打开授权页直链后自行扫码或转发
 4. 完成扫码后调用 `taptap_dc_complete_authorization`
 5. 再次调用 `taptap_dc_quick_brief`
 
@@ -81,17 +109,44 @@ openclaw plugins install @lotaber_wang/openclaw-dc-plugin
 
 如果 OpenClaw 能安装插件，但第一次调用工具仍然偏慢，通常是在启动内嵌 TapTap 运行时，而不是在现场重新下载依赖。
 
+如果安装后看不到 `taptap_dc_*` 工具，优先按这个顺序排查：
+
+1. 确认安装的是 `@lotaber_wang/openclaw-dc-plugin@0.1.8` 或更新版本
+2. 执行 `openclaw plugins inspect taptap-dc-plugin`
+3. 执行 `openclaw gateway restart`
+4. 重新开启一个新会话，再观察工具列表
+
+如果 `inspect` 能看到插件，但工具仍未生效，通常不是插件代码没注册，而是 Gateway 还没完成配置重载。
+
+说明：
+
+- 本插件的 `taptap_dc_*` 工具由插件入口代码动态注册
+- `openclaw.plugin.json` 主要承担插件元信息、默认启用和配置校验职责
+- 所以“装完看不到 tool”时，优先怀疑安装状态、Gateway 重启和会话刷新，而不是去手改 manifest 里的 `tools` 字段
+
+如果出现配置异常，优先检查插件 ID 是否一致：
+
+- package 名称：`@lotaber_wang/openclaw-dc-plugin`
+- plugin id：`taptap-dc-plugin`
+- OpenClaw 配置入口：`plugins.entries.taptap-dc-plugin`
+
 如果第一次调用失败，优先检查：
 
 - 当前环境是否能访问 npm registry
 - 本机 Node 版本是否 >= 18.14.1
 - OpenClaw 进程是否有临时目录写权限
+- OpenClaw 是否已经完成 Gateway 重启
 
-从 `0.1.6` 开始，插件 bridge 会额外做这些兼容处理：
+从 `0.1.8` 开始，插件安装链路与 bridge 会额外做这些兼容处理：
 
+- 在 `package.json` 中补充 `openclaw.install.npmSpec`，让安装链路更稳定
+- 在 `openclaw.plugin.json` 中显式开启 `enabledByDefault`
 - `initialize` 超时后自动切换到无缓冲 / PTY 启动策略重试
 - `initialize` 默认超时提升到 45 秒，避免宿主启动稍慢时过早失败
+- 向内嵌 TapTap runtime 发送 `initialize` 与后续请求时，默认改为裸 JSON + 换行（NDJSON 风格），避免只发 `Content-Length` 帧导致无响应
+- `initialize` 的 `protocolVersion` 回退到 `2024-11-05`，并使用更保守的空 `capabilities`，降低 OpenClaw 宿主兼容风险
 - 兼容解析裸 JSON 输出，不再只接受 `Content-Length` 帧
 - 启动时如果 stdout 混入人类可读日志，会先自动丢弃噪音再解析协议消息
 - 如果拿到的是半截 JSON，会先继续等待后续分片，而不是立刻按失败处理
 - 过滤 PTY 场景下被回显到 stdout 的请求消息
+- 授权结果会优先把“直接点击授权”链接放在第一位，方便移动端对话直接打开

package/index.js

@@ -58,6 +58,55 @@ function buildMarkdownLink(label, url) {
   return `[${label}](${url})`;
 }
 
+function tryParseUrl(value) {
+  if (!value || typeof value !== 'string') {
+    return null;
+  }
+
+  try {
+    return new URL(value);
+  } catch {
+    return null;
+  }
+}
+
+function decodeWrappedAuthUrl(value) {
+  const parsed = tryParseUrl(value);
+  const wrappedCode = parsed?.searchParams?.get('code');
+  if (!wrappedCode) {
+    return null;
+  }
+
+  try {
+    return decodeURIComponent(wrappedCode);
+  } catch {
+    return wrappedCode;
+  }
+}
+
+function enrichAuthPayload(authPayload) {
+  if (!authPayload || typeof authPayload !== 'object') {
+    return authPayload;
+  }
+
+  const directAuthUrl =
+    authPayload.direct_auth_url ||
+    authPayload.verification_uri_complete ||
+    authPayload.qrcode_url ||
+    decodeWrappedAuthUrl(authPayload.auth_url) ||
+    authPayload.verification_uri ||
+    null;
+
+  const wrappedAuthUrl = authPayload.wrapped_auth_url || authPayload.auth_url || null;
+
+  return {
+    ...authPayload,
+    direct_auth_url: directAuthUrl,
+    wrapped_auth_url: wrappedAuthUrl,
+    preferred_auth_url: directAuthUrl || wrappedAuthUrl || null,
+  };
+}
+
 function normalizeText(value) {
   return String(value || '')
     .trim()
@@ -195,30 +244,39 @@ function buildBriefText(appTitle, sections, meta = {}) {
 }
 
 function buildAuthGuideText(authPayload) {
-  const authUrl = authPayload?.auth_url;
-  const qrcodeUrl = authPayload?.qrcode_url;
+  const enriched = enrichAuthPayload(authPayload);
+  const directAuthUrl = enriched?.direct_auth_url;
+  const wrappedAuthUrl = enriched?.wrapped_auth_url;
+  const qrcodeUrl = enriched?.qrcode_url;
   const lines = [
-    '当前还没有完成 TapTap 授权，请先扫码授权。',
+    '当前还没有完成 TapTap 授权，请先完成一次授权。',
+    '',
+    '如果你现在是在手机上或当前客户端支持超链接，请优先点击下面这条直接授权链接，不用扫码：',
+    buildMarkdownLink('直接点击授权', directAuthUrl),
     '',
-    '如果你现在是在手机上对话，优先直接点击下面这个授权链接：',
-    buildMarkdownLink('立即打开授权页面', authUrl),
+    '如果上面的链接打不开，再尝试这个 TapTap 包装授权页：',
+    buildMarkdownLink('打开 TapTap 包装授权页', wrappedAuthUrl),
     '',
-    '如果你现在是在桌面端对话，可以打开二维码后用 TapTap 扫码授权：',
-    buildMarkdownLink('打开二维码图片', qrcodeUrl),
+    '如果你需要在桌面端继续，或者想把授权页转给另一台设备，也可以使用这个直链自行打开或生成二维码：',
+    buildMarkdownLink('打开授权页直链', qrcodeUrl || directAuthUrl),
     '',
     '完成扫码后，请继续调用 `taptap_dc_complete_authorization`，然后再次调用 `taptap_dc_quick_brief`。',
   ];
 
-  if (authPayload?.device_code) {
-    lines.push('', `device_code：${authPayload.device_code}`);
+  if (enriched?.device_code) {
+    lines.push('', `device_code：${enriched.device_code}`);
   }
 
-  if (authUrl) {
-    lines.push('', `授权直链：${authUrl}`);
+  if (directAuthUrl) {
+    lines.push('', `直接授权链接：${directAuthUrl}`);
   }
 
-  if (qrcodeUrl) {
-    lines.push(`二维码直链：${qrcodeUrl}`);
+  if (wrappedAuthUrl && wrappedAuthUrl !== directAuthUrl) {
+    lines.push(`TapTap 包装授权链接：${wrappedAuthUrl}`);
+  }
+
+  if (qrcodeUrl && qrcodeUrl !== directAuthUrl) {
+    lines.push(`授权页直链：${qrcodeUrl}`);
   }
 
   return lines.join('\n');
@@ -298,12 +356,15 @@ function registerProxyTool(api, bridge, definition) {
           const text = await bridge.callTool(definition.mcpToolName, params || {});
           const normalized = normalizeJsonText(text);
           const parsed = tryParseJson(normalized);
+          const normalizedParsed = definition.normalizeResult
+            ? definition.normalizeResult(parsed)
+            : parsed;
           const renderedText = definition.resultFormatter
-            ? definition.resultFormatter(parsed, normalized)
+            ? definition.resultFormatter(normalizedParsed, normalized)
             : normalized;
           return toolResult(renderedText, {
             mcpToolName: definition.mcpToolName,
-            parsed,
+            parsed: normalizedParsed,
           });
         } catch (error) {
           return toolResult(
@@ -357,7 +418,9 @@ function registerQuickBriefTool(api, bridge) {
         try {
           const env = await callJsonTool(bridge, 'check_environment_raw', {});
           if (!env?.auth?.has_mac_token) {
-            const authPayload = await callJsonTool(bridge, 'start_oauth_authorization_raw', {});
+            const authPayload = enrichAuthPayload(
+              await callJsonTool(bridge, 'start_oauth_authorization_raw', {})
+            );
             return toolResult(buildAuthGuideText(authPayload), authPayload);
           }
 
@@ -425,6 +488,9 @@ const toolDefinitions = [
       'Start TapTap OAuth device flow and return a mobile-friendly clickable auth link plus qrcode link.',
     mcpToolName: 'start_oauth_authorization_raw',
     parameters: createSchema(),
+    normalizeResult(parsed) {
+      return enrichAuthPayload(parsed);
+    },
     resultFormatter(parsed, normalized) {
       if (!parsed || typeof parsed !== 'object') {
         return normalized;

package/lib/mcp-bridge.js

@@ -10,7 +10,10 @@ 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 = 45000;
+const DEFAULT_PROTOCOL_VERSION = '2024-11-05';
 const ANSI_ESCAPE_REGEX = /\x1B\[[0-?]*[ -/]*[@-~]/g;
+const pluginPackageJson = readPluginPackageJson();
+const PLUGIN_VERSION = pluginPackageJson?.version || '0.1.0';
 
 function readPluginPackageJson() {
   try {
@@ -563,8 +566,7 @@ export class TapTapMcpBridge {
     }
 
     const body = JSON.stringify(message);
-    const frame = `Content-Length: ${Buffer.byteLength(body, 'utf8')}\r\n\r\n${body}`;
-    this.child.stdin.write(frame, 'utf8');
+    this.child.stdin.write(`${body}\n`, 'utf8');
   }
 
   request(method, params) {
@@ -694,15 +696,11 @@ export class TapTapMcpBridge {
   async initializeServer() {
     await Promise.race([
       this.request('initialize', {
-        protocolVersion: '2025-11-25',
-        capabilities: {
-          tools: {},
-          resources: {},
-          logging: {},
-        },
+        protocolVersion: DEFAULT_PROTOCOL_VERSION,
+        capabilities: {},
         clientInfo: {
           name: 'taptap-openclaw-dc-plugin',
-          version: '0.1.0',
+          version: PLUGIN_VERSION,
         },
       }),
       new Promise((_, reject) => {

package/openclaw.plugin.json

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

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "@lotaber_wang/openclaw-dc-plugin",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "type": "module",
   "description": "TapTap DC 的 OpenClaw 插件，内置原始数据工具与运营简报 skill。",
   "main": "index.js",
   "openclaw": {
     "extensions": [
       "./index.js"
-    ]
+    ],
+    "install": {
+      "npmSpec": "@lotaber_wang/openclaw-dc-plugin"
+    }
   },
   "exports": {
     ".": "./index.js",

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

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