@xgjktech/xg_cwork_im 1.0.0 → 1.0.3

package/README.md

@@ -24,6 +24,8 @@ IM 系统  →  WebSocket  →  插件（本项目）  →  OpenClaw AI  →  IM
 
 ## 安装
 
+推荐同事通过 **npm** 安装，无需访问内部 Git；需要改源码时再从内部仓库克隆（方法 B）。
+
 ### 方法 A：通过 npm 包安装（推荐）
 
 一条命令完成安装，依赖由 OpenClaw 自动处理：
@@ -36,10 +38,10 @@ openclaw plugins install @xgjktech/xg_cwork_im
 
 ### 方法 B：通过本地源码安装
 
-如需二次开发或无法使用 npm 安装时，可克隆后以链接模式安装：
+如需二次开发或无法使用 npm 安装时，可从内部 Git 克隆后以链接模式安装：
 
 ```bash
-git clone https://github.com/cwei001/openclaw-channel-xg-cwork-im.git
+git clone http://192.168.3.200/openclaw/openclaw-channel-xg-cwork-im.git
 cd openclaw-channel-xg-cwork-im
 npm install
 openclaw plugins install -l .
@@ -71,6 +73,43 @@ NPM_CONFIG_REGISTRY=https://registry.npmmirror.com npm install
 
 ---
 
+## 更新已安装的插件
+
+当插件发布新版本后，已安装的用户可按以下方式更新。
+
+### 通过 npm 安装的（方法 A）
+
+使用**插件 id**（不是 npm 包名）执行更新：
+
+```bash
+openclaw plugins update xg_cwork_im
+```
+
+更新完成后执行 `openclaw gateway restart` 使新版本生效。
+
+国内网络可临时指定镜像源后再更新：
+
+```bash
+NPM_CONFIG_REGISTRY=https://registry.npmmirror.com openclaw plugins update xg_cwork_im
+```
+
+### 通过本地源码 / 链接安装的（方法 B）
+
+在插件目录拉取最新代码后重启网关：
+
+```bash
+cd openclaw-channel-xg-cwork-im   # 进入当时克隆的目录
+git pull
+npm install
+openclaw gateway restart
+```
+
+### 手动安装的（方法 C）
+
+重新从内部 Git 下载或复制最新代码到 `~/.openclaw/extensions/xg_cwork_im`，在该目录执行 `npm install --omit=dev` 或 `npm run install:prod`，再执行 `openclaw gateway restart`。
+
+---
+
 ## 配置
 
 ### 步骤 1：启用并信任插件
@@ -214,6 +253,7 @@ openclaw-channel-xg-cwork-im/
 │   ├── connection.ts       # WebSocket 连接管理
 │   ├── send-service.ts     # IM 消息发送
 │   ├── group-history-tool.ts      # 拉取群消息历史的 Agent Tool
+│   ├── send-group-message-tool.ts # 发送群消息的 Agent Tool
 │   └── channel.ts          # Channel Plugin 主定义
 ├── package.json
 ├── tsconfig.json
@@ -223,62 +263,82 @@ openclaw-channel-xg-cwork-im/
 
 ---
 
-## 维护者：发布到 npm
+## 代码仓库与发布流程说明
 
-本插件包名为 `@xgjktech/xg_cwork_im`（scoped 包）。按以下步骤发布到 npm 后，同事即可用 `openclaw plugins install @xgjktech/xg_cwork_im` 安装。
+- **代码仓库**：本项目在**内部 Git** 管理，地址：`http://192.168.3.200/openclaw/openclaw-channel-xg-cwork-im`，不推送到 GitHub。
+- **安装方式**：同事安装请优先使用 **npm**（方法 A）；需要改源码时从内部 Git 克隆（方法 B）。
+- **发布流程**：在内部 Git 上开发、提交后，由维护者**发布到 npm**；同事通过 `openclaw plugins install @xgjktech/xg_cwork_im` 安装，无需访问 Git。
 
-### 1. 注册 / 登录 npm
+---
+
+## 维护者：如何发布到 npm（详细步骤）
+
+代码在内部 Git 上维护，发布到 npm 后同事即可一条命令安装。按下列步骤操作。
+
+### 步骤 1：在 npm 注册 / 登录
 
-- 无账号：打开 [https://www.npmjs.com/signup](https://www.npmjs.com/signup) 注册。
-- 已有账号：在项目根目录执行：
+1. 无 npm 账号：打开 [https://www.npmjs.com/signup](https://www.npmjs.com/signup) 注册。
+2. 在项目根目录执行：
 
 ```bash
 npm login
 ```
 
-按提示输入 Username、Password、Email 及一次性验证码（若开启 2FA）。
+3. 按提示输入 **Username**、**Password**、**Email**。
+4. 若账号开启了**双因素认证（2FA）**，发布时必须使用：
+   - 在 npm 网站 **Access Tokens** 里创建 **Granular Access Token**，勾选 **Publish packages**，并勾选 **Bypass 2FA**；或  
+   - 在命令行登录时使用 **OTP**（一次性密码）。  
+   否则会报错：`Two-factor authentication or granular access token with bypass 2fa enabled is required to publish packages`。
 
-### 2. 确认 scope 权限
+### 步骤 2：确认 scope 与权限
 
-包名是 `@xgjktech/xg_cwork_im`，表示属于 **scope** `@xgjktech`。两种方式二选一：
+- 包名为 `@xgjktech/xg_cwork_im`，属于 **scope** `@xgjktech`。
+- 在 [npm 官网](https://www.npmjs.com/) 登录 → **Organizations** → **Create**，创建组织名为 **xgjktech**，确保你的账号有该组织的发布权限。
+- 若改用个人 scope（如 `@你的用户名/xg_cwork_im`），需修改 `package.json` 的 `"name"` 并同步改 README 中的安装命令。
 
-- **使用 npm 组织**：在 [npm 官网](https://www.npmjs.com/) 登录 → Organizations → Create → 创建名为 `xgjktech` 的组织，并把你的账号加入。
-- **使用个人 scope**：若你希望包名是个人 scope（如 `@你的用户名/xg_cwork_im`），需把 `package.json` 里的 `"name"` 改成 `@你的用户名/xg_cwork_im`，并同步修改 README 中的安装命令。
+### 步骤 3：发布前检查
 
-### 3. 发布前检查
-
-在仓库根目录执行：
+在项目根目录执行：
 
 ```bash
-# 查看将要随包发布的文件（与 package.json 的 "files" 一致）
 npm pack --dry-run
 ```
 
-确认没有敏感文件（如 `.env`、密钥）。`package.json` 里已通过 `"files"` 指定只发布必要文件。
+确认列出的文件无敏感内容（如 `.env`、密钥）。发布内容由 `package.json` 的 `"files"` 控制。
 
-### 4. 执行发布
+### 步骤 4：执行发布
 
-**scoped 包首次发布必须加 `--access public`**，否则会变成付费的私有包：
+**scoped 包必须加 `--access public`**，否则会按私有包计费并可能报 402：
 
 ```bash
 npm publish --access public
 ```
 
-发布成功后可在 [https://www.npmjs.com/package/@xgjktech/xg_cwork_im](https://www.npmjs.com/package/@xgjktech/xg_cwork_im) 查看。
+成功后可在此查看：  
+[https://www.npmjs.com/package/@xgjktech/xg_cwork_im](https://www.npmjs.com/package/@xgjktech/xg_cwork_im)
+
+### 步骤 5：后续更新（重新推送到 npm）
 
-### 5. 后续更新
+每次发新版本都按下面做一遍即可：
 
-修改代码后，先在 `package.json` 里把 `version` 提高（如 `1.0.0` → `1.0.1`），再执行：
+1. 在内部 Git 上改代码、提交、推送。
+2. 在 **package.json** 里把 **version** 升高（如 `1.0.0` → `1.0.1`），保存。
+3. 在项目根目录执行：
 
 ```bash
 npm publish --access public
 ```
 
-（若该 scope 下此前已发布过公开包，可只执行 `npm publish`。）
+4. 通知同事执行 **更新已安装的插件**（见上文「更新已安装的插件」），例如：  
+   `openclaw plugins update xg_cwork_im` → `openclaw gateway restart`。
+
+（若该 scope 已发过公开包，有时可只执行 `npm publish`，建议仍带 `--access public` 避免误发成私有。）
 
 ### 常见问题
 
-- **403 Forbidden**：当前账号无 `@xgjktech` 的发布权限，需在 npm 上创建/加入组织，或将包名改为你的个人 scope。
-- **402 Payment Required**：未加 `--access public`，scoped 包被当成私有包，需改为 `npm publish --access public`。
-- **国内网络**：可临时使用镜像登录与发布（不推荐长期用镜像发布）：  
-  `npm login --registry=https://registry.npmjs.org/`，发布时仍用默认 registry 或 `--registry=https://registry.npmjs.org/`。
+| 报错或现象 | 原因 | 处理 |
+|-----------|------|------|
+| **403 Forbidden**，且提示需 2FA 或 token | 账号开启 2FA 后，普通登录无法发布 | 使用 **Granular Access Token**（勾选 Publish + Bypass 2FA），或在发布时提供 OTP |
+| **403 Forbidden**，无 2FA 提示 | 当前账号无 `@xgjktech` 发布权限 | 在 npm 创建/加入组织 `xgjktech`，或将包名改为个人 scope |
+| **402 Payment Required** | 未加 `--access public`，scoped 包被视为私有 | 执行 `npm publish --access public` |
+| 国内网络登录/发布慢或超时 | 默认 registry 在国外 | 登录：`npm login --registry=https://registry.npmjs.org/`；发布时也可加 `--registry=https://registry.npmjs.org/`，不推荐长期用第三方镜像发布 |

package/index.ts

@@ -22,8 +22,9 @@ const plugin: XgCworkImPluginModule = {
         // 注册 AI 工具（静态工具对象，确保 toolNames 正确注册）
         const cworkConfig = extractXgCworkImConfig(api.config);
         if (cworkConfig) {
-            api.registerTool(buildGroupHistoryTool(cworkConfig));
-            api.registerTool(buildSendGroupMessageTool(cworkConfig));
+            // 工具涉及网络请求 / 副作用，按文档要求标记为 optional，由用户在 Agent 的 tools.allow 中显式启用
+            api.registerTool(buildGroupHistoryTool(cworkConfig), { optional: true });
+            api.registerTool(buildSendGroupMessageTool(cworkConfig), { optional: true });
         } else {
             console.warn("[xg_cwork_im] channel config not found, skipping tool registration");
         }

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@xgjktech/xg_cwork_im",
-  "version": "1.0.0",
+  "version": "1.0.3",
   "description": "XG CWork IM channel plugin for OpenClaw",
   "keywords": [
     "bot",
     "channel",
     "openclaw",
-    "xgim",
+    "xg_cwork_im",
     "im"
   ],
   "license": "MIT",
@@ -51,7 +51,6 @@
       "blurb": "小橙工作台 IM 机器人 Channel 插件，通过 WebSocket 长连接接收消息。",
       "aliases": [
         "xg_cwork_im",
-        "xgim",
         "im"
       ]
     },