@lotaber_wang/openclaw-dc-plugin 0.1.11 → 0.1.13

package/README.md

@@ -2,6 +2,25 @@
 
 这是一个面向 OpenClaw 的 TapTap DC 插件，内置原始数据工具与运营简报 skill。
 
+## 先看这个
+
+这是 **OpenClaw 插件包**，不是普通 npm CLI 包。
+
+请这样安装：
+
+```bash
+openclaw plugins install @lotaber_wang/openclaw-dc-plugin@0.1.13
+```
+
+不要这样安装：
+
+```bash
+npm install @lotaber_wang/openclaw-dc-plugin
+npm install -g @lotaber_wang/openclaw-dc-plugin
+```
+
+如果误用了 `npm install`，包内的 `postinstall` 会主动输出警告，提醒改用 `openclaw plugins install`。
+
 ## 插件能力
 
 - 以 OpenClaw 原生插件方式安装
@@ -15,10 +34,6 @@
 
 ## 安装
 
-```bash
-openclaw plugins install @lotaber_wang/openclaw-dc-plugin@0.1.11
-```
-
 安装完成后，建议立刻执行一次检查：
 
 ```bash
@@ -27,19 +42,19 @@ openclaw plugins inspect openclaw-dc-plugin
 
 ## 给 OpenClaw 的安装执行指令
 
-如果安装流程判断需要重启 Gateway，先通知用户，再执行重启。
+如果安装流程判断需要重启 Gateway，先通过飞书或其他通信插件通知用户，再执行重启。
 
 推荐通知文案：
 
-`TapTap DC 插件已安装完成。OpenClaw 接下来如需重启 Gateway，应先提示用户；重启完成后即可使用 taptap_dc_* 工具。`
+`TapTap DC 插件已安装完成。OpenClaw 接下来如需重启 Gateway，应先通过飞书或其他通信插件通知用户；重启完成后即可使用 taptap_dc_* 工具。`
 
 执行顺序要求：
 
-1. 先向用户发送上面的安装完成/即将重启提示
+1. 先通过飞书或其他通信插件向用户发送上面的安装完成/即将重启提示
 2. 再执行 `openclaw gateway restart` 或等效的宿主重启动作
 3. 重启完成后，再开始使用 `taptap_dc_*` 工具
 
-不管是手动重启还是宿主自动触发的重启，都应先提示用户，不要静默重启。
+不管是手动重启还是宿主自动触发的重启，都应先通过飞书或其他通信插件通知用户，不要静默重启。
 
 如果安装成功后仍然看不到 `taptap_dc_*` 工具，再按下面命令手动重启 Gateway：
 
@@ -52,9 +67,9 @@ openclaw gateway restart
 ## 推荐安装流程
 
 ```bash
-openclaw plugins install @lotaber_wang/openclaw-dc-plugin@0.1.11
+openclaw plugins install @lotaber_wang/openclaw-dc-plugin@0.1.13
 openclaw plugins inspect openclaw-dc-plugin
-echo 'TapTap DC 插件已安装完成。OpenClaw 接下来如需重启 Gateway，应先提示用户；重启完成后即可使用 taptap_dc_* 工具。'
+echo 'TapTap DC 插件已安装完成。OpenClaw 接下来如需重启 Gateway，应先通过飞书或其他通信插件通知用户；重启完成后即可使用 taptap_dc_* 工具。'
 openclaw gateway restart
 ```
 
@@ -62,7 +77,8 @@ openclaw gateway restart
 
 - `install` 负责把插件包装进 OpenClaw
 - `inspect` 用来确认插件元信息、skills、tools 是否已被 Gateway 识别
-- 如果宿主判断需要重启 Gateway，必须先通知用户，再重启
+- 如果有人误用 `npm install` 或 `npm install -g`，插件包会在 `postinstall` 阶段打印醒目的纠正提示
+- 如果宿主判断需要重启 Gateway，必须先通过飞书或其他通信插件通知用户，再重启
 - 如果 10-30 秒后还没生效，再手动执行 `gateway restart`
 - 如果宿主存在“stock 安装失败后再 fallback npm”的行为，优先使用明确版本号安装，必要时改用本地 `.tgz` 安装，避免双安装链路互相打架
 
@@ -130,9 +146,9 @@ openclaw gateway restart
 
 如果安装后看不到 `taptap_dc_*` 工具，优先按这个顺序排查：
 
-1. 确认安装的是 `@lotaber_wang/openclaw-dc-plugin@0.1.11` 或更新版本
+1. 确认安装的是 `@lotaber_wang/openclaw-dc-plugin@0.1.13` 或更新版本
 2. 执行 `openclaw plugins inspect openclaw-dc-plugin`
-3. 如果宿主要求重启 Gateway，先向用户发送安装完成提示
+3. 如果宿主要求重启 Gateway，先通过飞书或其他通信插件向用户发送安装完成提示
 4. 再执行 `openclaw gateway restart`
 5. 重新开启一个新会话，再观察工具列表
 
@@ -158,7 +174,7 @@ openclaw gateway restart
 - OpenClaw 进程是否有临时目录写权限
 - OpenClaw 是否已经完成 Gateway 重启
 
-从 `0.1.11` 开始，插件安装链路与 bridge 会额外做这些兼容处理：
+从 `0.1.13` 开始，插件安装链路与 bridge 会额外做这些兼容处理：
 
 - 在 `package.json` 中补充 `openclaw.install.npmSpec`，让安装链路更稳定
 - 在 `package.json` 的 `openclaw.install` 中补充 `postInstallMessage` / `instructions` / `restartCommand`

package/index.js

@@ -3,12 +3,18 @@ import process from 'node:process';
 import { TapTapMcpBridge } from './lib/mcp-bridge.js';
 
 const RESTART_NOTICE =
-  'TapTap DC 插件已安装完成。OpenClaw 接下来如需重启 Gateway，应先提示用户；重启完成后即可使用 taptap_dc_* 工具。';
+  'TapTap DC 插件已安装完成。OpenClaw 接下来如需重启 Gateway，应先通过飞书或其他通信插件通知用户；重启完成后即可使用 taptap_dc_* 工具。';
+const PREFERRED_INSTALL_COMMAND =
+  'openclaw plugins install @lotaber_wang/openclaw-dc-plugin@0.1.13';
+const WRONG_INSTALL_HINT =
+  '这是 OpenClaw 插件包，不是普通 npm CLI 包。请不要直接用 npm install，改用 openclaw plugins install。';
 
 const INSTALLATION_GUIDANCE = [
-  '如果安装流程判断需要重启 Gateway，先通知用户，再执行重启。',
+  '如果安装流程判断需要重启 Gateway，先通过飞书或其他通信插件通知用户，再执行重启。',
+  `正确安装命令：${PREFERRED_INSTALL_COMMAND}`,
+  `错误安装提醒：${WRONG_INSTALL_HINT}`,
   `推荐提示文案：${RESTART_NOTICE}`,
-  '执行顺序：先提示用户 -> 再执行 gateway restart -> 重启完成后再开始使用 taptap_dc_* 工具。',
+  '执行顺序：先通过飞书或其他通信插件把安装完成与即将重启的消息发给用户 -> 再执行 gateway restart -> 重启完成后再开始使用 taptap_dc_* 工具。',
 ];
 
 function toolResult(text, details = {}) {
@@ -822,14 +828,19 @@ const plugin = {
   id: 'openclaw-dc-plugin',
   name: 'TapTap DC',
   description:
-    '面向 OpenClaw 的 TapTap DC 插件，内置原始数据工具与运营简报 skill；如需重启 Gateway，应先提示用户。',
+    '面向 OpenClaw 的 TapTap DC 插件。请使用 openclaw plugins install 安装，不要直接 npm install；如需重启 Gateway，应先通过飞书或其他通信插件通知用户。',
   installation: {
+    preferredCommand: PREFERRED_INSTALL_COMMAND,
+    doNotUseNpmInstall: true,
+    wrongInstallHint: WRONG_INSTALL_HINT,
     restartRequired: true,
     restartCommand: 'openclaw gateway restart',
     postInstallMessage: RESTART_NOTICE,
     instructions: INSTALLATION_GUIDANCE,
   },
   installHints: {
+    preferredCommand: PREFERRED_INSTALL_COMMAND,
+    wrongInstallHint: WRONG_INSTALL_HINT,
     beforeRestartMessage: RESTART_NOTICE,
     instructions: INSTALLATION_GUIDANCE,
   },

package/openclaw.plugin.json

@@ -1,8 +1,8 @@
 {
   "id": "openclaw-dc-plugin",
   "name": "TapTap DC",
-  "description": "面向 OpenClaw 的 TapTap DC 插件，内置原始数据工具与运营简报 skill；如需重启 Gateway，应先提示用户。",
-  "version": "0.1.11",
+  "description": "面向 OpenClaw 的 TapTap DC 插件。请使用 openclaw plugins install 安装，不要直接 npm install；如需重启 Gateway，应先通过飞书或其他通信插件通知用户。",
+  "version": "0.1.13",
   "enabledByDefault": true,
   "skills": ["./skills"],
   "configSchema": {

package/package.json

@@ -1,22 +1,31 @@
 {
   "name": "@lotaber_wang/openclaw-dc-plugin",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "type": "module",
-  "description": "TapTap DC 的 OpenClaw 插件，内置原始数据工具与运营简报 skill；如需重启 Gateway，应先提示用户。",
+  "description": "TapTap DC 的 OpenClaw 插件。请使用 openclaw plugins install 安装，不要直接 npm install；如需重启 Gateway，应先通过飞书或其他通信插件通知用户。",
   "main": "index.js",
+  "scripts": {
+    "postinstall": "node ./scripts/postinstall.js"
+  },
   "openclaw": {
     "extensions": [
       "./index.js"
     ],
     "install": {
       "npmSpec": "@lotaber_wang/openclaw-dc-plugin",
-      "postInstallMessage": "TapTap DC 插件已安装完成。OpenClaw 接下来如需重启 Gateway，应先提示用户；重启完成后即可使用 taptap_dc_* 工具。",
+      "preferredCommand": "openclaw plugins install @lotaber_wang/openclaw-dc-plugin@0.1.13",
+      "doNotUseCommands": [
+        "npm install @lotaber_wang/openclaw-dc-plugin",
+        "npm install -g @lotaber_wang/openclaw-dc-plugin"
+      ],
+      "wrongInstallHint": "这是 OpenClaw 插件包，不是普通 npm CLI 包。请改用 openclaw plugins install @lotaber_wang/openclaw-dc-plugin@0.1.13。",
+      "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_* 工具。"
+        "如果安装流程判断需要重启 Gateway，先通过飞书或其他通信插件通知用户，再执行重启。",
+        "推荐提示文案：TapTap DC 插件已安装完成。OpenClaw 接下来如需重启 Gateway，应先通过飞书或其他通信插件通知用户；重启完成后即可使用 taptap_dc_* 工具。",
+        "执行顺序：先通过飞书或其他通信插件把安装完成与即将重启的消息发给用户 -> 再执行 gateway restart -> 重启完成后再开始使用 taptap_dc_* 工具。"
       ]
     }
   },
@@ -34,6 +43,7 @@
     "index.js",
     "lib/",
     "openclaw.plugin.json",
+    "scripts/",
     "skills/",
     "README.md"
   ],

package/scripts/postinstall.js

@@ -0,0 +1,52 @@
+import process from 'node:process';
+
+const PACKAGE_NAME = '@lotaber_wang/openclaw-dc-plugin';
+const PACKAGE_VERSION = '0.1.13';
+const PREFERRED_COMMAND = `openclaw plugins install ${PACKAGE_NAME}@${PACKAGE_VERSION}`;
+const DISCOURAGED_COMMANDS = [
+  `npm install ${PACKAGE_NAME}`,
+  `npm install -g ${PACKAGE_NAME}`,
+];
+
+function looksLikeOpenClawInstall(value) {
+  return /openclaw/i.test(String(value || ''));
+}
+
+function looksLikePluginPath(value) {
+  return /(?:^|[/\\])(extensions|plugins|openclaw)(?:[/\\]|$)/i.test(String(value || ''));
+}
+
+function emit(lines, writer = console.error) {
+  writer('');
+  writer('============================================================');
+  for (const line of lines) {
+    writer(line);
+  }
+  writer('============================================================');
+  writer('');
+}
+
+const installPath = process.cwd();
+const initCwd = process.env.INIT_CWD || '';
+const npmExecPath = process.env.npm_execpath || '';
+const userAgent = process.env.npm_config_user_agent || '';
+const isGlobalInstall = process.env.npm_config_global === 'true';
+const isLikelyOpenClawInstall =
+  looksLikeOpenClawInstall(userAgent) ||
+  looksLikeOpenClawInstall(npmExecPath) ||
+  looksLikePluginPath(installPath) ||
+  looksLikePluginPath(initCwd);
+
+if (isGlobalInstall || !isLikelyOpenClawInstall) {
+  emit([
+    `[TapTap DC] 检测到当前安装方式更像是直接通过 npm 安装 ${PACKAGE_NAME}。`,
+    '[TapTap DC] 这会把它当成普通 npm 包，而不是 OpenClaw 插件，后续通常不会自动注册 tools。',
+    `[TapTap DC] 正确安装方式：${PREFERRED_COMMAND}`,
+    `[TapTap DC] 不推荐：${DISCOURAGED_COMMANDS.join(' / ')}`,
+  ]);
+} else {
+  emit([
+    `[TapTap DC] 已安装插件包 ${PACKAGE_NAME}@${PACKAGE_VERSION}。`,
+    `[TapTap DC] 推荐后续检查命令：openclaw plugins inspect openclaw-dc-plugin`,
+  ], console.log);
+}