@coclaw/openclaw-coclaw 0.1.6 → 0.1.7

package/README.md

@@ -5,51 +5,60 @@ CoClaw 的 OpenClaw 插件（npm: `@coclaw/openclaw-coclaw`，plugin id: `opencl
 - **transport bridge** — CoClaw server 与 OpenClaw gateway 之间的实时消息桥接
 - **session-manager** — 会话列表/读取能力（`nativeui.sessions.listAll` / `nativeui.sessions.get`）
 
-## 安装
+## 安装与模式切换
 
-### 从 npm 安装（生产推荐）
+插件支持两种安装模式，可随时切换（脚本会自动处理卸载→重装）：
+
+### 本地开发（link 模式，日常开发推荐）
 
 ```bash
-pnpm run plugin:npm:install
-# 或手动：
-openclaw plugins install @coclaw/openclaw-coclaw
-openclaw gateway restart
+pnpm run link
 ```
 
-### 本地开发安装（--link）
+link 后代码更新只需 `openclaw gateway restart`，无需重新安装。
+
+### 从 npm 安装
 
 ```bash
-pnpm run plugin:dev:link
-# 或手动：
-openclaw plugins install --link /path/to/plugins/openclaw
-openclaw gateway restart
+pnpm run install:npm
 ```
 
-安装后确认：
+### 卸载
 
 ```bash
-openclaw plugins doctor
-openclaw gateway status
+pnpm run unlink          # 卸载 link 模式
+pnpm run uninstall:npm   # 卸载 npm 模式
 ```
 
-## 卸载
+卸载仅移除插件元数据和代码，不清理绑定信息（`bindings.json` 独立保留）。
+
+## 预发布验证与发布
+
+### 预发布验证
 
-### npm 安装的卸载
+发布前验证 tarball 能正确安装到 OpenClaw 中：
 
 ```bash
-pnpm run plugin:npm:uninstall
+pnpm run prerelease              # 全新安装验证（交互式，含手动功能验证）
+pnpm run prerelease -- --upgrade # 升级验证（先装 npm 旧版，再用本地包覆盖）
 ```
 
-### 本地开发安装的卸载
+### 发布到 npm
 
 ```bash
-pnpm run plugin:dev:unlink
+pnpm run release
 ```
 
-卸载脚本会自动清理：
-- `plugins.entries` / `plugins.installs` 等插件元数据
-- `~/.openclaw/coclaw/bindings.json`（绑定信息）
-- `openclaw.json` 中可能残留的 `channels.coclaw` 节点（旧版兼容）
+发布流程：预发布验证（自动） → npm 凭据检查 → dry-run → 发布 → 轮询确认生效。
+
+### 检查发布状态
+
+```bash
+pnpm run release:check                     # 显示各 registry 最新版本
+pnpm run release:check -- 0.1.7            # 对比指定版本
+WAIT=1 pnpm run release:check -- 0.1.7     # 轮询直到版本生效
+pnpm run release:versions                  # 显示所有已发布版本
+```
 
 ## 绑定 / 解绑
 
@@ -102,7 +111,6 @@ node ~/.openclaw/extensions/coclaw/src/cli.js unbind --server <url>
 说明：
 - 这一设计是为了避免卸载插件后 `channels.coclaw` 节点残留导致 OpenClaw gateway schema 验证失败。
 - `config.js` 是读写绑定信息的唯一入口。
-- 首次读取时会自动从旧位置（`openclaw.json` 的 `channels.coclaw` / `.coclaw-tunnel.json`）迁移。
 - 绑定时不提交 bot `name`；server 通过 gateway WebSocket 获取 OpenClaw 实例名。若未设置实例名，前端回退显示 `OpenClaw`。
 
 ## 运行与排障日志
@@ -150,4 +158,4 @@ pnpm coverage     # 覆盖率检查
 pnpm verify       # 完整验证（check → test:standalone → test:plugin → test → coverage）
 ```
 
-覆盖率阈值：100%（lines/functions/branches/statements），未通过禁止接入 gateway。
+覆盖率阈值：lines/statements/functions 100%，branches ≥ 95%。未通过禁止接入 gateway。

package/index.js

@@ -1,7 +1,7 @@
 import { bindBot, unbindBot } from './src/common/bot-binding.js';
 import { registerCoclawCli } from './src/cli-registrar.js';
 import { resolveErrorMessage } from './src/common/errors.js';
-import { alreadyBound, notBound, bindOk, unbindOk } from './src/common/messages.js';
+import { notBound, bindOk, unbindOk } from './src/common/messages.js';
 import { coclawChannelPlugin } from './src/channel-plugin.js';
 import { refreshRealtimeBridge, startRealtimeBridge, stopRealtimeBridge } from './src/realtime-bridge.js';
 import { setRuntime } from './src/runtime.js';
@@ -118,6 +118,8 @@ const plugin = {
 
 				try {
 					if (action === 'bind') {
+						// 先断开 bridge，避免 unbindWithServer 触发的 bot.unbound 竞态
+						await stopRealtimeBridge();
 						const serverUrl = options.server ?? api.pluginConfig?.serverUrl;
 						const result = await bindBot({
 							code: positionals[0],
@@ -136,9 +138,6 @@ const plugin = {
 					return { text: buildHelpText() };
 				}
 				catch (err) {
-					if (err.code === 'ALREADY_BOUND') {
-						return { text: alreadyBound(err) };
-					}
 					if (err.code === 'NOT_BOUND') {
 						return { text: notBound() };
 					}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coclaw/openclaw-coclaw",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "type": "module",
   "license": "Apache-2.0",
   "description": "OpenClaw CoClaw channel plugin for remote chat",
@@ -45,23 +45,23 @@
   },
   "scripts": {
     "dev": "node src/cli.js --help",
-    "build": "echo \"TODO: build coclaw openclaw plugin\"",
+    "build": "echo 'No build step needed (pure ES modules)'",
     "lint": "eslint \"**/*.{js,mjs,cjs}\" --no-error-on-unmatched-pattern",
     "typecheck": "echo \"No typecheck configured yet (coclaw openclaw plugin)\"",
     "check": "pnpm lint && pnpm typecheck",
     "test:standalone": "node --test src/standalone-mode.test.js",
     "test:plugin": "node --test src/plugin-mode.test.js",
     "test": "node --test",
-    "coverage": "c8 --check-coverage --lines 100 --functions 100 --branches 100 --statements 100 --reporter=text --reporter=lcov node --test",
+    "coverage": "c8 --check-coverage --lines 100 --functions 100 --branches 95 --statements 100 --reporter=text --reporter=lcov node --test",
     "verify": "pnpm check && pnpm test:standalone && pnpm test:plugin && pnpm test && pnpm coverage",
-    "pub:verify": "pnpm verify",
-    "pub:check": "npm whoami --registry=https://registry.npmjs.org/ && npm ping --registry=https://registry.npmjs.org/ && npm publish --dry-run --access public --registry=https://registry.npmjs.org/",
-    "pub:versions": "npm view @coclaw/openclaw-coclaw versions --json --registry=https://registry.npmjs.org/ && npm view @coclaw/openclaw-coclaw versions --json",
-    "pub:release": "bash ./scripts/publish-npm.sh",
-    "plugin:dev:link": "bash ./scripts/dev-link-install.sh",
-    "plugin:dev:unlink": "bash ./scripts/dev-link-uninstall.sh",
-    "plugin:npm:install": "bash ./scripts/npm-install.sh",
-    "plugin:npm:uninstall": "bash ./scripts/npm-uninstall.sh"
+    "link": "bash ./scripts/link.sh",
+    "unlink": "bash ./scripts/unlink.sh",
+    "install:npm": "bash ./scripts/install-npm.sh",
+    "uninstall:npm": "bash ./scripts/uninstall-npm.sh",
+    "prerelease": "bash ./scripts/prerelease.sh",
+    "release": "bash ./scripts/release.sh",
+    "release:check": "bash ./scripts/release-check.sh",
+    "release:versions": "npm view @coclaw/openclaw-coclaw versions --json --registry=https://registry.npmjs.org/ && npm view @coclaw/openclaw-coclaw versions --json"
   },
   "devDependencies": {
     "c8": "^10.1.3",

package/src/api.js

@@ -1,10 +1,14 @@
-async function requestJson(baseUrl, path, { method = 'GET', headers, body } = {}) {
+async function requestJson(baseUrl, path, { method = 'GET', headers, body, timeout } = {}) {
 	const url = new URL(path, baseUrl).toString();
-	const res = await fetch(url, {
+	const fetchOpts = {
 		method,
 		headers,
 		body: body == null ? undefined : JSON.stringify(body),
-	});
+	};
+	if (timeout) {
+		fetchOpts.signal = AbortSignal.timeout(timeout);
+	}
+	const res = await fetch(url, fetchOpts);
 	let data = null;
 	try {
 		data = await res.json();
@@ -21,37 +25,25 @@ async function requestJson(baseUrl, path, { method = 'GET', headers, body } = {}
 	return data;
 }
 
+const BIND_TIMEOUT = 30_000;
+const UNBIND_TIMEOUT = 15_000;
+
 export async function bindWithServer({ baseUrl, code, name }) {
 	return requestJson(baseUrl, '/api/v1/bots/bind', {
 		method: 'POST',
 		headers: { 'content-type': 'application/json' },
 		body: { code, name },
+		timeout: BIND_TIMEOUT,
 	});
 }
 
-export async function unbindWithServer({ baseUrl, token }) {
+export async function unbindWithServer({ baseUrl, token, timeout = UNBIND_TIMEOUT }) {
 	return requestJson(baseUrl, '/api/v1/bots/unbind', {
 		method: 'POST',
 		headers: {
 			Authorization: `Bearer ${token}`,
 		},
+		timeout,
 	});
 }
 
-export async function listBotsWithServer({ baseUrl, cookie }) {
-	return requestJson(baseUrl, '/api/v1/bots', {
-		headers: cookie
-			? {
-				Cookie: cookie,
-			}
-			: undefined,
-	});
-}
-
-export async function getBotSelfWithServer({ baseUrl, token }) {
-	return requestJson(baseUrl, '/api/v1/bots/self', {
-		headers: {
-			Authorization: `Bearer ${token}`,
-		},
-	});
-}

package/src/channel-plugin.js

@@ -1,5 +1,4 @@
 import { DEFAULT_ACCOUNT_ID } from './config.js';
-import { createTransportAdapter } from './transport-adapter.js';
 
 function resolveAccount(_cfg, accountId) {
 	const resolvedAccountId = accountId ?? DEFAULT_ACCOUNT_ID;
@@ -11,8 +10,6 @@ function resolveAccount(_cfg, accountId) {
 	};
 }
 
-const transport = createTransportAdapter();
-
 export const coclawChannelPlugin = {
 	id: 'coclaw',
 	meta: {
@@ -44,21 +41,15 @@ export const coclawChannelPlugin = {
 	},
 	outbound: {
 		deliveryMode: 'direct',
-		sendText: async ({ to, text }) => {
-			const result = await transport.safeDispatchOutbound({
-				channel: 'coclaw',
-				to,
-				text,
-			});
-			return {
-				channel: 'coclaw',
-				messageId: result.messageId ?? `coclaw-local-${Date.now()}`,
-				to,
-				text,
-				accepted: Boolean(result.accepted),
-			};
-		},
+		// placeholder: CoClaw 消息实际通过 realtime-bridge WebSocket 桥接发送，
+		// 此 sendText 仅满足 OpenClaw channel 注册要求。
+		sendText: async ({ to }) => ({
+			channel: 'coclaw',
+			messageId: `coclaw-${Date.now()}`,
+			to,
+		}),
 	},
+	// TODO: status.defaultRuntime.running 应反映 realtime-bridge 实际连接状态
 	status: {
 		defaultRuntime: {
 			accountId: DEFAULT_ACCOUNT_ID,

package/src/cli-registrar.js

@@ -2,7 +2,7 @@ import { bindBot, unbindBot } from './common/bot-binding.js';
 import { resolveErrorMessage } from './common/errors.js';
 import { callGatewayMethod } from './common/gateway-notify.js';
 import {
-	alreadyBound, notBound, bindOk, unbindOk,
+	notBound, bindOk, unbindOk,
 	gatewayNotified, gatewayNotifyFailed,
 } from './common/messages.js';
 
@@ -47,17 +47,14 @@ export function registerCoclawCli({ program, config, logger }, deps = {}) {
 		.option('--server <url>', 'CoClaw server URL')
 		.action(async (code, opts) => {
 			try {
+				// 先断开 bridge，避免 unbindWithServer 触发的 bot.unbound 竞态
+				await notifyGateway('coclaw.stopBridge');
 				const serverUrl = resolveServerUrl(opts, config);
 				const result = await bindBot({ code, serverUrl });
 				/* c8 ignore next */
 				console.log(bindOk(result));
 				await notifyGateway('coclaw.refreshBridge');
 			} catch (err) {
-				if (err.code === 'ALREADY_BOUND') {
-					console.error(alreadyBound(err));
-					process.exitCode = 1;
-					return;
-				}
 				console.error(`Error: ${resolveErrorMessage(err)}`);
 				process.exitCode = 1;
 			}

package/src/cli.js

@@ -7,7 +7,7 @@ import { bindBot, unbindBot } from './common/bot-binding.js';
 import { resolveErrorMessage } from './common/errors.js';
 import { callGatewayMethod } from './common/gateway-notify.js';
 import {
-	alreadyBound, notBound, bindOk, unbindOk,
+	notBound, bindOk, unbindOk,
 	gatewayNotified, gatewayNotifyFailed,
 } from './common/messages.js';
 
@@ -66,22 +66,16 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
 	}
 
 	if (command === 'bind') {
-		try {
-			const result = await bindBot({
-				code: positionals[0],
-				serverUrl: options.server,
-			});
-			/* c8 ignore next */
-			console.log(bindOk(result));
-			await notifyGateway('coclaw.refreshBridge', deps);
-			return 0;
-		} catch (err) {
-			if (err.code === 'ALREADY_BOUND') {
-				console.error(alreadyBound(err));
-				return 1;
-			}
-			throw err;
-		}
+		// 先断开 bridge，避免 unbindWithServer 触发的 bot.unbound 竞态
+		await notifyGateway('coclaw.stopBridge', deps);
+		const result = await bindBot({
+			code: positionals[0],
+			serverUrl: options.server,
+		});
+		/* c8 ignore next */
+		console.log(bindOk(result));
+		await notifyGateway('coclaw.refreshBridge', deps);
+		return 0;
 	}
 
 	if (command === 'unbind') {

package/src/common/bot-binding.js

@@ -9,11 +9,20 @@ export async function bindBot({ code, serverUrl }) {
 	}
 
 	const config = await readConfig();
+
+	// 已绑定时自动解绑再重绑（解绑尽力而为，不阻塞新绑定）
+	let previousBotId;
 	if (config?.token) {
-		const err = new Error('already bound, please unbind first');
-		err.code = 'ALREADY_BOUND';
-		err.botId = config.botId;
-		throw err;
+		previousBotId = config.botId || 'unknown';
+		const oldBaseUrl = config.serverUrl;
+		if (oldBaseUrl) {
+			try {
+				await unbindWithServer({ baseUrl: oldBaseUrl, token: config.token });
+			} catch {
+				// 尽力而为，忽略解绑错误
+			}
+		}
+		await clearConfig();
 	}
 
 	/* c8 ignore next */
@@ -27,18 +36,17 @@ export async function bindBot({ code, serverUrl }) {
 		throw new Error('invalid bind response');
 	}
 
-	const next = {
-		...config,
+	await writeConfig({
 		serverUrl: baseUrl,
 		botId: data.botId,
 		token: data.token,
 		boundAt: new Date().toISOString(),
-	};
-	await writeConfig(next);
+	});
 
 	return {
 		botId: data.botId,
 		rebound: Boolean(data.rebound),
+		previousBotId,
 	};
 }
 

package/src/common/messages.js

@@ -1,8 +1,11 @@
 // bind/unbind CLI 及 command 的用户提示文案（统一出口）
 
-export function bindOk({ botId, rebound }) {
+export function bindOk({ botId, rebound, previousBotId }) {
 	const action = rebound ? 're-bound' : 'bound';
-	return `OK. Bot (${botId}) ${action} to CoClaw.`;
+	const prev = previousBotId
+		? ` (previous binding to bot ${previousBotId} was auto-removed)`
+		: '';
+	return `OK. Bot (${botId}) ${action} to CoClaw.${prev}`;
 }
 
 export function unbindOk({ botId, serverError }) {
@@ -13,11 +16,6 @@ export function unbindOk({ botId, serverError }) {
 	return `OK. Bot (${id}) unbound from CoClaw.${tag}`;
 }
 
-export function alreadyBound({ botId }) {
-	const id = botId ?? 'unknown';
-	return `Already bound to CoClaw as bot (${id}).\nRun \`openclaw coclaw unbind\` to unbind first.`;
-}
-
 export function notBound() {
 	return 'Not bound. Nothing to unbind.';
 }

package/src/config.js

@@ -48,112 +48,12 @@ async function writeJson(filePath, value) {
 	await fs.writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
 }
 
-// --- 旧位置迁移 ---
-
-function getOpenclawConfigPath() {
-	return process.env.OPENCLAW_CONFIG_PATH
-		? nodePath.resolve(process.env.OPENCLAW_CONFIG_PATH)
-		: nodePath.join(os.homedir(), '.openclaw', 'openclaw.json');
-}
-
-function pickFromOldConfig(rootCfg) {
-	const channels = toRecord(rootCfg.channels);
-	const coclaw = toRecord(channels.coclaw);
-	const accounts = toRecord(coclaw.accounts);
-	const account = toRecord(accounts.default);
-	return {
-		serverUrl: account.serverUrl ?? coclaw.serverUrl,
-		botId: account.botId ?? coclaw.botId,
-		token: account.token ?? coclaw.token,
-		boundAt: account.boundAt ?? coclaw.boundAt,
-	};
-}
-
-async function tryMigrateFromOldLocations() {
-	// 1. 尝试从 openclaw.json channels.coclaw 迁移
-	const rt = getRuntime();
-	let oldData;
-	if (rt?.config?.loadConfig) {
-		oldData = pickFromOldConfig(rt.config.loadConfig());
-	} else {
-		const rootCfg = await readJson(getOpenclawConfigPath());
-		oldData = pickFromOldConfig(rootCfg);
-	}
-	if (oldData.token) {
-		return oldData;
-	}
-
-	// 2. 尝试从 legacy 文件迁移
-	const legacyPaths = [
-		nodePath.resolve(process.cwd(), '.coclaw-tunnel.json'),
-		nodePath.join(os.homedir(), '.coclaw-tunnel.json'),
-	];
-	for (const p of legacyPaths) {
-		const legacy = await readJson(p);
-		if (legacy?.token) {
-			return legacy;
-		}
-	}
-
-	return null;
-}
-
-async function cleanOldLocations() {
-	// 清理 openclaw.json 中的 channels.coclaw
-	const rt = getRuntime();
-	if (rt?.config?.loadConfig && rt?.config?.writeConfigFile) {
-		const rootCfg = structuredClone(rt.config.loadConfig());
-		const channels = toRecord(rootCfg.channels);
-		if (channels.coclaw) {
-			delete channels.coclaw;
-			rootCfg.channels = channels;
-			await rt.config.writeConfigFile(rootCfg);
-		}
-	} else {
-		const filePath = getOpenclawConfigPath();
-		const rootCfg = toRecord(await readJson(filePath));
-		const channels = toRecord(rootCfg.channels);
-		if (channels.coclaw) {
-			delete channels.coclaw;
-			rootCfg.channels = channels;
-			await writeJson(filePath, rootCfg);
-		}
-	}
-
-	// 清理 legacy 文件
-	const legacyPaths = [
-		nodePath.resolve(process.cwd(), '.coclaw-tunnel.json'),
-		nodePath.join(os.homedir(), '.coclaw-tunnel.json'),
-	];
-	for (const p of legacyPaths) {
-		const legacy = await readJson(p);
-		if (legacy?.token) {
-			await writeJson(p, {});
-		}
-	}
-}
-
 // --- 公共 API ---
 
 export async function readConfig(accountId = DEFAULT_ACCOUNT_ID) {
 	const bindingsPath = getBindingsPath();
 	const bindings = await readJson(bindingsPath);
-	const entry = toRecord(bindings[accountId]);
-
-	if (entry.token) {
-		return entry;
-	}
-
-	// 首次运行：尝试从旧位置迁移
-	const migrated = await tryMigrateFromOldLocations();
-	if (migrated?.token) {
-		const newBindings = { ...bindings, [accountId]: migrated };
-		await writeJson(bindingsPath, newBindings);
-		await cleanOldLocations();
-		return migrated;
-	}
-
-	return entry;
+	return toRecord(bindings[accountId]);
 }
 
 export async function writeConfig(nextConfig, accountId = DEFAULT_ACCOUNT_ID) {
@@ -188,7 +88,4 @@ export async function clearConfig(accountId = DEFAULT_ACCOUNT_ID) {
 	} else {
 		await writeJson(bindingsPath, bindings);
 	}
-
-	// 确保清理旧位置残留
-	await cleanOldLocations();
 }

package/src/message-model.js

@@ -1,3 +1,5 @@
+// placeholder: 当前仅被 transport-adapter 使用，预留用于未来 channel outbound 消息规范化。
+
 function isNonEmptyString(value) {
 	return typeof value === 'string' && value.trim() !== '';
 }