@coclaw/openclaw-coclaw 0.3.2 → 0.4.0

package/index.js

@@ -1,14 +1,35 @@
+import fs from 'node:fs/promises';
+import nodePath from 'node:path';
+
 import { bindBot, unbindBot } from './src/common/bot-binding.js';
 import { registerCoclawCli } from './src/cli-registrar.js';
 import { resolveErrorMessage } from './src/common/errors.js';
 import { notBound, bindOk, unbindOk } from './src/common/messages.js';
 import { coclawChannelPlugin } from './src/channel-plugin.js';
-import { ensureAgentSession, restartRealtimeBridge, stopRealtimeBridge } from './src/realtime-bridge.js';
+import { ensureAgentSession, gatewayAgentRpc, restartRealtimeBridge, stopRealtimeBridge } from './src/realtime-bridge.js';
 import { setRuntime } from './src/runtime.js';
 import { createSessionManager } from './src/session-manager/manager.js';
+import { TopicManager } from './src/topic-manager/manager.js';
+import { generateTitle } from './src/topic-manager/title-gen.js';
 import { AutoUpgradeScheduler } from './src/auto-upgrade/updater.js';
 import { getPackageInfo } from './src/auto-upgrade/updater-check.js';
 
+// 延迟读取 + 缓存：避免模块加载时 package.json 损坏导致插件整体无法注册
+let __pluginVersion = null;
+export async function getPluginVersion() {
+	if (__pluginVersion) return __pluginVersion;
+	try {
+		const pkgPath = nodePath.resolve(import.meta.dirname, 'package.json');
+		const raw = await fs.readFile(pkgPath, 'utf8');
+		__pluginVersion = JSON.parse(raw).version ?? 'unknown';
+	} catch {
+		return 'unknown';
+	}
+	return __pluginVersion;
+}
+// 测试用：重置缓存
+export function __resetPluginVersion() { __pluginVersion = null; }
+
 
 function parseCommandArgs(args) {
 	/* c8 ignore next */
@@ -56,6 +77,12 @@ const plugin = {
 		setRuntime(api.runtime);
 		const logger = api?.logger ?? console;
 		const manager = createSessionManager({ logger });
+		const topicManager = new TopicManager({ logger });
+
+		// 懒加载 topic 数据（best-effort，不阻断注册）
+		topicManager.load('main').catch((err) => {
+			logger.warn?.(`[coclaw] topic manager load failed: ${String(err?.message ?? err)}`);
+		});
 
 		api.registerChannel({ plugin: coclawChannelPlugin });
 		api.registerService({
@@ -110,6 +137,109 @@ const plugin = {
 			}
 		});
 
+		api.registerGatewayMethod('coclaw.info', async ({ respond }) => {
+			try {
+				const version = await getPluginVersion();
+				respond(true, { version, capabilities: ['topics'] });
+			}
+			catch (err) {
+				respondError(respond, err);
+			}
+		});
+
+		api.registerGatewayMethod('coclaw.topics.create', async ({ params, respond }) => {
+			try {
+				const agentId = params?.agentId?.trim?.() || 'main';
+				// 确保该 agent 的 topics 已加载
+				if (!topicManager.__cache.has(agentId)) {
+					await topicManager.load(agentId);
+				}
+				const result = await topicManager.create({ agentId });
+				respond(true, result);
+			}
+			catch (err) {
+				respondError(respond, err);
+			}
+		});
+
+		api.registerGatewayMethod('coclaw.topics.list', async ({ params, respond }) => {
+			try {
+				const agentId = params?.agentId?.trim?.() || 'main';
+				if (!topicManager.__cache.has(agentId)) {
+					await topicManager.load(agentId);
+				}
+				respond(true, topicManager.list({ agentId }));
+			}
+			catch (err) {
+				respondError(respond, err);
+			}
+		});
+
+		api.registerGatewayMethod('coclaw.topics.get', ({ params, respond }) => {
+			try {
+				const topicId = params?.topicId?.trim?.();
+				if (!topicId) {
+					respond(false, { error: 'topicId required' });
+					return;
+				}
+				respond(true, topicManager.get({ topicId }));
+			}
+			catch (err) {
+				respondError(respond, err);
+			}
+		});
+
+		api.registerGatewayMethod('coclaw.topics.getHistory', ({ params, respond }) => {
+			try {
+				const topicId = params?.topicId?.trim?.();
+				if (!topicId) {
+					respond(false, { error: 'topicId required' });
+					return;
+				}
+				const agentId = params?.agentId?.trim?.() || 'main';
+				// 直接复用 session-manager 的 get()，topicId 即 sessionId
+				respond(true, manager.get({ agentId, sessionId: topicId }));
+			}
+			catch (err) {
+				respondError(respond, err);
+			}
+		});
+
+		api.registerGatewayMethod('coclaw.topics.generateTitle', async ({ params, respond }) => {
+			try {
+				const topicId = params?.topicId?.trim?.();
+				if (!topicId) {
+					respond(false, { error: 'topicId required' });
+					return;
+				}
+				const result = await generateTitle({
+					topicId,
+					topicManager,
+					agentRpc: gatewayAgentRpc,
+					logger,
+				});
+				respond(true, result);
+			}
+			catch (err) {
+				respondError(respond, err);
+			}
+		});
+
+		api.registerGatewayMethod('coclaw.topics.delete', async ({ params, respond }) => {
+			try {
+				const topicId = params?.topicId?.trim?.();
+				if (!topicId) {
+					respond(false, { error: 'topicId required' });
+					return;
+				}
+				const result = await topicManager.delete({ topicId });
+				respond(true, result);
+			}
+			catch (err) {
+				respondError(respond, err);
+			}
+		});
+
 		api.registerGatewayMethod('coclaw.upgradeHealth', async ({ respond }) => {
 			try {
 				const { version } = await getPackageInfo();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coclaw/openclaw-coclaw",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "type": "module",
   "license": "Apache-2.0",
   "description": "OpenClaw CoClaw channel plugin for remote chat",

package/src/realtime-bridge.js

@@ -246,6 +246,79 @@ export class RealtimeBridge {
 		});
 	}
 
+	/**
+	 * 两阶段 agent RPC：发送请求后等待 accepted 再等待最终响应。
+	 * agent() RPC 返回两次响应（同一 id）：
+	 *   1. { status: "accepted", runId }
+	 *   2. { status: "ok", result: { payloads: [{ text }] } }
+	 *
+	 * @param {string} method - RPC 方法名（通常为 'agent'）
+	 * @param {object} params - RPC 参数
+	 * @param {object} [options]
+	 * @param {number} [options.timeoutMs=60000] - 总超时（含两阶段）
+	 * @param {number} [options.acceptTimeoutMs=10000] - 等待 accepted 的超时
+	 * @returns {Promise<{ok: boolean, response?: object, error?: string}>}
+	 */
+	async __gatewayAgentRpc(method, params = {}, options = {}) {
+		const totalTimeoutMs = Number.isFinite(options.timeoutMs) ? options.timeoutMs : 60_000;
+		const acceptTimeoutMs = Number.isFinite(options.acceptTimeoutMs) ? options.acceptTimeoutMs : 10_000;
+		const ready = await this.__waitGatewayReady(acceptTimeoutMs);
+		/* c8 ignore next 3 -- waitGatewayReady 返回 false 后的防御检查 */
+		if (!ready || !this.gatewayWs || this.gatewayWs.readyState !== 1 || !this.gatewayReady) {
+			return { ok: false, error: 'gateway_not_ready' };
+		}
+		const ws = this.gatewayWs;
+		const id = this.__nextGatewayReqId('coclaw-agent');
+		return await new Promise((resolve) => {
+			let settled = false;
+			let accepted = false;
+			let totalTimer = null;
+			let acceptTimer = null;
+			const finish = (result) => {
+				if (settled) return;
+				settled = true;
+				if (totalTimer) clearTimeout(totalTimer);
+				if (acceptTimer) clearTimeout(acceptTimer);
+				this.gatewayPendingRequests.delete(id);
+				resolve(result);
+			};
+			// 两阶段 settle：第一次 accepted 不 resolve，第二次才 resolve
+			const settle = (result) => {
+				if (settled) return;
+				// 错误响应：直接结束
+				if (!result.ok) {
+					finish(result);
+					return;
+				}
+				const status = result.response?.payload?.status;
+				if (!accepted && status === 'accepted') {
+					// 第一阶段：已接受，切换到总超时
+					accepted = true;
+					if (acceptTimer) clearTimeout(acceptTimer);
+					return;
+				}
+				// 第二阶段或非 accepted 响应：最终结果
+				finish(result);
+			};
+			this.gatewayPendingRequests.set(id, settle);
+			// 总超时
+			totalTimer = setTimeout(() => finish({ ok: false, error: 'timeout' }), totalTimeoutMs);
+			totalTimer.unref?.();
+			// accepted 超时（仅等第一阶段）
+			acceptTimer = setTimeout(() => {
+				if (!accepted) finish({ ok: false, error: 'accept_timeout' });
+			}, acceptTimeoutMs);
+			acceptTimer.unref?.();
+			try {
+				ws.send(JSON.stringify({ type: 'req', id, method, params }));
+			}
+			/* c8 ignore next 3 -- ws.send 极少抛出 */
+			catch {
+				finish({ ok: false, error: 'send_failed' });
+			}
+		});
+	}
+
 	/**
 	 * 确保指定 agent 的主 session 存在（sessions.resolve + 条件 sessions.reset）
 	 * @param {string} [agentId] - agent ID，默认 'main'
@@ -747,3 +820,17 @@ export async function ensureAgentSession(agentId) {
 	}
 	return singleton.ensureAgentSession(agentId);
 }
+
+/**
+ * 通过 gateway WS 发起两阶段 agent RPC（供标题生成等场景使用）
+ * @param {string} method
+ * @param {object} params
+ * @param {object} [options]
+ * @returns {Promise<{ok: boolean, response?: object, error?: string}>}
+ */
+export async function gatewayAgentRpc(method, params, options) {
+	if (!singleton) {
+		return { ok: false, error: 'bridge_not_started' };
+	}
+	return singleton.__gatewayAgentRpc(method, params, options);
+}

package/src/topic-manager/manager.js

@@ -0,0 +1,237 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import nodePath from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+import { atomicWriteJsonFile } from '../utils/atomic-write.js';
+import { createMutex } from '../utils/mutex.js';
+
+const TOPICS_FILE = 'coclaw-topics.json';
+
+function emptyStore() {
+	return { version: 1, topics: [] };
+}
+
+/**
+ * Topic 管理器：内存模型 + CRUD + 磁盘持久化。
+ *
+ * 每个 agentId 对应一份 coclaw-topics.json，按需懒加载到内存。
+ * 写操作通过 mutex + atomicWriteJsonFile 保证一致性。
+ */
+export class TopicManager {
+	/**
+	 * @param {object} [opts]
+	 * @param {string} [opts.rootDir] - agents 根目录，默认 ~/.openclaw/agents
+	 * @param {object} [opts.logger]
+	 * @param {Function} [opts.readFile] - 测试注入
+	 * @param {Function} [opts.writeJsonFile] - 测试注入
+	 * @param {Function} [opts.unlinkFile] - 测试注入
+	 * @param {Function} [opts.copyFile] - 测试注入
+	 */
+	constructor(opts = {}) {
+		this.__rootDir = opts.rootDir ?? nodePath.join(os.homedir(), '.openclaw', 'agents');
+		this.__logger = opts.logger ?? console;
+		this.__readFile = opts.readFile ?? fs.readFile;
+		this.__writeJsonFile = opts.writeJsonFile ?? atomicWriteJsonFile;
+		this.__unlinkFile = opts.unlinkFile ?? fs.unlink;
+		this.__copyFile = opts.copyFile ?? fs.copyFile;
+		// 内存缓存：agentId -> { version, topics[] }
+		this.__cache = new Map();
+		// 每个 agentId 一把锁
+		this.__mutexes = new Map();
+		// 进行中的 load Promise（防止并发 load 竞态）
+		this.__loadingPromises = new Map();
+	}
+
+	__sessionsDir(agentId) {
+		return nodePath.join(this.__rootDir, agentId, 'sessions');
+	}
+
+	__topicsFilePath(agentId) {
+		return nodePath.join(this.__sessionsDir(agentId), TOPICS_FILE);
+	}
+
+	__mutex(agentId) {
+		if (!this.__mutexes.has(agentId)) {
+			this.__mutexes.set(agentId, createMutex());
+		}
+		return this.__mutexes.get(agentId);
+	}
+
+	/**
+	 * 从磁盘加载指定 agent 的 topics 到内存（文件不存在时初始化空数据）。
+	 * 若同一 agentId 的 load 已在进行中，复用同一 Promise，防止并发竞态。
+	 * @param {string} agentId
+	 */
+	async load(agentId) {
+		// 已加载 → 跳过
+		if (this.__cache.has(agentId)) return;
+		// 正在加载 → 复用
+		const pending = this.__loadingPromises.get(agentId);
+		if (pending) return pending;
+
+		const p = this.__doLoad(agentId).finally(() => {
+			this.__loadingPromises.delete(agentId);
+		});
+		this.__loadingPromises.set(agentId, p);
+		return p;
+	}
+
+	async __doLoad(agentId) {
+		const filePath = this.__topicsFilePath(agentId);
+		try {
+			const raw = await this.__readFile(filePath, 'utf8');
+			const data = JSON.parse(raw);
+			if (data && typeof data === 'object' && Array.isArray(data.topics)) {
+				this.__cache.set(agentId, data);
+				return;
+			}
+		} catch {
+			// 文件不存在或解析失败，初始化空数据
+		}
+		this.__cache.set(agentId, emptyStore());
+	}
+
+	__ensureLoaded(agentId) {
+		if (!this.__cache.has(agentId)) {
+			throw new Error(`TopicManager: agent "${agentId}" not loaded, call load() first`);
+		}
+	}
+
+	__getStore(agentId) {
+		this.__ensureLoaded(agentId);
+		return this.__cache.get(agentId);
+	}
+
+	async __persist(agentId) {
+		const store = this.__getStore(agentId);
+		await this.__writeJsonFile(this.__topicsFilePath(agentId), store);
+	}
+
+	/**
+	 * 创建新 Topic
+	 * @param {{ agentId: string }} params
+	 * @returns {Promise<{ topicId: string }>}
+	 */
+	async create({ agentId }) {
+		const topicId = randomUUID();
+		const record = {
+			topicId,
+			agentId,
+			title: null,
+			createdAt: Date.now(),
+		};
+		await this.__mutex(agentId).withLock(async () => {
+			const store = this.__getStore(agentId);
+			store.topics.unshift(record);
+			await this.__persist(agentId);
+		});
+		return { topicId };
+	}
+
+	/**
+	 * 获取指定 agent 的 Topic 列表（已按 createdAt 倒序）
+	 * @param {{ agentId: string }} params
+	 * @returns {{ topics: object[] }}
+	 */
+	list({ agentId }) {
+		const store = this.__getStore(agentId);
+		return { topics: store.topics };
+	}
+
+	/**
+	 * 获取单个 Topic 元信息
+	 * @param {{ topicId: string }} params
+	 * @returns {{ topic: object | null }}
+	 */
+	get({ topicId }) {
+		for (const [, store] of this.__cache) {
+			const found = store.topics.find((t) => t.topicId === topicId);
+			if (found) return { topic: found };
+		}
+		return { topic: null };
+	}
+
+	/**
+	 * 更新 Topic 标题
+	 * @param {{ topicId: string, title: string }} params
+	 */
+	async updateTitle({ topicId, title }) {
+		// 查找 topic 所属 agentId
+		let targetAgentId = null;
+		for (const [agentId, store] of this.__cache) {
+			if (store.topics.some((t) => t.topicId === topicId)) {
+				targetAgentId = agentId;
+				break;
+			}
+		}
+		if (!targetAgentId) {
+			throw new Error(`Topic not found: ${topicId}`);
+		}
+		await this.__mutex(targetAgentId).withLock(async () => {
+			const store = this.__getStore(targetAgentId);
+			const topic = store.topics.find((t) => t.topicId === topicId);
+			if (!topic) throw new Error(`Topic not found: ${topicId}`);
+			topic.title = title;
+			await this.__persist(targetAgentId);
+		});
+	}
+
+	/**
+	 * 删除 Topic 及其 .jsonl 文件
+	 * @param {{ topicId: string }} params
+	 * @returns {Promise<{ ok: boolean }>}
+	 */
+	async delete({ topicId }) {
+		let targetAgentId = null;
+		for (const [agentId, store] of this.__cache) {
+			if (store.topics.some((t) => t.topicId === topicId)) {
+				targetAgentId = agentId;
+				break;
+			}
+		}
+		if (!targetAgentId) {
+			return { ok: false };
+		}
+		await this.__mutex(targetAgentId).withLock(async () => {
+			const store = this.__getStore(targetAgentId);
+			const idx = store.topics.findIndex((t) => t.topicId === topicId);
+			if (idx === -1) return;
+			store.topics.splice(idx, 1);
+			await this.__persist(targetAgentId);
+		});
+		// 删除 .jsonl（忽略不存在）
+		const jsonlPath = nodePath.join(this.__sessionsDir(targetAgentId), `${topicId}.jsonl`);
+		try {
+			await this.__unlinkFile(jsonlPath);
+		} catch (err) {
+			if (err?.code !== 'ENOENT') throw err;
+		}
+		return { ok: true };
+	}
+
+	/**
+	 * 复制 topic 的 .jsonl 为临时文件（用于标题生成）
+	 * @param {{ agentId: string, topicId: string }} params
+	 * @returns {Promise<{ tempId: string, tempPath: string }>}
+	 */
+	async copyTranscript({ agentId, topicId }) {
+		const srcPath = nodePath.join(this.__sessionsDir(agentId), `${topicId}.jsonl`);
+		const tempId = randomUUID();
+		const tempPath = nodePath.join(this.__sessionsDir(agentId), `${tempId}.jsonl`);
+		await this.__copyFile(srcPath, tempPath);
+		return { tempId, tempPath };
+	}
+
+	/**
+	 * 删除临时 .jsonl 文件
+	 * @param {string} filePath
+	 */
+	async cleanupTempFile(filePath) {
+		try {
+			await this.__unlinkFile(filePath);
+		} catch (err) {
+			if (err?.code !== 'ENOENT') throw err;
+		}
+	}
+}

package/src/topic-manager/title-gen.js

@@ -0,0 +1,147 @@
+import { randomUUID } from 'node:crypto';
+
+const TITLE_SYSTEM_PROMPT = [
+	'You are a title generator. Your ONLY job is to output a short title.',
+	'',
+	'STRICT RULES:',
+	'- Output ONLY the title itself. Nothing else.',
+	'- Do NOT add any prefix like "Title:", "标题:", "Here is the title:", "好的" etc.',
+	'- Do NOT add quotes around the title.',
+	'- Do NOT add any explanation, greeting, or preamble.',
+	'- Do NOT call any tools or functions.',
+	'- Keep it concise: max 15 words.',
+	'- Use the same language as the conversation.',
+	'',
+	'GOOD examples of valid output:',
+	'  量子计算基础概念',
+	'  How to deploy a Node.js app',
+	'',
+	'BAD examples (DO NOT do this):',
+	'  好的，标题是：量子计算基础概念',
+	'  "量子计算基础概念"',
+	'  Title: How to deploy a Node.js app',
+].join('\n');
+
+const TITLE_MAX_LEN = 128;
+
+// 清洗 LLM 返回的标题文本
+const QUOTE_PAIRS = [
+	['"', '"'],
+	["'", "'"],
+	['\u300C', '\u300D'], // 「」
+	['\u201C', '\u201D'], // ""
+	['\u2018', '\u2019'], // ''
+];
+
+// 弱模型常见的前缀模式（贪婪匹配到冒号/换行后的实际标题）
+const PREFIX_PATTERNS = [
+	// 中文前缀：好的，标题是：xxx / 以下是标题：xxx / 标题：xxx
+	/^(?:好的[，,]?\s*)?(?:以下是|这是|生成的)?(?:对话)?标题(?:是|为)?[：:]\s*/,
+	// 英文前缀：Title: xxx / Here is the title: xxx / Sure, the title is: xxx
+	/^(?:sure[,.]?\s*)?(?:here\s+is\s+)?(?:the\s+)?title(?:\s+is)?[:\s]+/i,
+	// 通用客气开头：好的，让我... / 好的，xxx
+	/^好的[，,]\s*(?:让我[^：:]*[：:]|我[^：:]*[：:])\s*/,
+];
+
+function cleanTitle(raw) {
+	if (!raw || typeof raw !== 'string') return '';
+	let s = raw.trim();
+	// 多行响应时只取第一行（LLM 可能附加解释）
+	const firstLine = s.split(/\r?\n/)[0].trim();
+	if (firstLine) s = firstLine;
+	// 去除常见前缀
+	for (const re of PREFIX_PATTERNS) {
+		s = s.replace(re, '');
+	}
+	s = s.trim();
+	// 去除首尾成对引号
+	for (const [open, close] of QUOTE_PAIRS) {
+		if (s.startsWith(open) && s.endsWith(close) && s.length >= 2) {
+			s = s.slice(open.length, -close.length).trim();
+		}
+	}
+	// 截断
+	if (s.length > TITLE_MAX_LEN) {
+		s = s.slice(0, TITLE_MAX_LEN);
+	}
+	return s;
+}
+
+/**
+ * 从 agent 两阶段响应中提取 assistant 文本
+ * @param {object} response - gateway 响应
+ * @returns {string | null}
+ */
+function extractAssistantText(response) {
+	const payloads = response?.payload?.result?.payloads;
+	if (!Array.isArray(payloads)) return null;
+	for (const p of payloads) {
+		if (typeof p?.text === 'string' && p.text.trim()) {
+			return p.text.trim();
+		}
+	}
+	return null;
+}
+
+/**
+ * 为 Topic 生成 AI 标题
+ *
+ * @param {object} opts
+ * @param {string} opts.topicId
+ * @param {object} opts.topicManager - TopicManager 实例
+ * @param {Function} opts.agentRpc - gatewayAgentRpc 函数
+ * @param {object} [opts.logger]
+ * @returns {Promise<{ title: string }>}
+ */
+export async function generateTitle({ topicId, topicManager, agentRpc, logger }) {
+	const log = logger ?? console;
+
+	// 验证 topic 存在
+	const { topic } = topicManager.get({ topicId });
+	if (!topic) {
+		throw new Error(`Topic not found: ${topicId}`);
+	}
+	const { agentId } = topic;
+
+	// 复制 .jsonl → 临时文件
+	const { tempId, tempPath } = await topicManager.copyTranscript({ agentId, topicId });
+
+	try {
+		// 通过 gateway WS 发起 agent 两阶段请求
+		const result = await agentRpc('agent', {
+			sessionId: tempId,
+			extraSystemPrompt: TITLE_SYSTEM_PROMPT,
+			message: '请为这段对话生成标题',
+			idempotencyKey: randomUUID(),
+		}, {
+			timeoutMs: 60_000,
+			acceptTimeoutMs: 10_000,
+		});
+
+		if (!result.ok) {
+			throw new Error(`Agent RPC failed: ${result.error ?? 'unknown'}`);
+		}
+
+		const rawTitle = extractAssistantText(result.response);
+		if (!rawTitle) {
+			throw new Error('No assistant text in agent response');
+		}
+
+		const title = cleanTitle(rawTitle);
+		if (!title) {
+			throw new Error('Title is empty after cleaning');
+		}
+
+		// 更新 topic title
+		await topicManager.updateTitle({ topicId, title });
+		return { title };
+	} catch (err) {
+		log.warn?.(`[coclaw] generateTitle failed for topic ${topicId}: ${String(err?.message ?? err)}`);
+		throw err;
+	} finally {
+		// 清理临时文件
+		await topicManager.cleanupTempFile(tempPath).catch(() => {});
+	}
+}
+
+export { cleanTitle, extractAssistantText, TITLE_SYSTEM_PROMPT };

package/src/utils/atomic-write.js

@@ -0,0 +1,61 @@
+/**
+ * 原子文件写入工具。
+ * 通过 write-to-tmp + rename 模式确保写入过程中崩溃不会损坏目标文件。
+ *
+ * 参照 OpenClaw writeTextAtomic / writeJsonAtomic 实现。
+ */
+
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs/promises';
+import nodePath from 'node:path';
+
+/**
+ * 原子写入任意文件。
+ * 先写入同目录临时文件，再 rename 覆盖目标（POSIX 原子操作）。
+ *
+ * @param {string} filePath - 目标文件路径
+ * @param {string | Buffer} content - 文件内容
+ * @param {object} [opts]
+ * @param {number} [opts.mode=0o600] - 文件权限
+ * @param {number} [opts.dirMode] - 父目录权限（自动创建时使用）
+ * @param {string} [opts.encoding='utf8'] - 写入编码
+ */
+async function atomicWriteFile(filePath, content, opts) {
+	const mode = opts?.mode ?? 0o600;
+	const encoding = opts?.encoding ?? 'utf8';
+	const mkdirOpts = { recursive: true };
+	if (opts?.dirMode != null) {
+		mkdirOpts.mode = opts.dirMode;
+	}
+
+	await fs.mkdir(nodePath.dirname(filePath), mkdirOpts);
+
+	const tmp = `${filePath}.${randomUUID()}.tmp`;
+	try {
+		await fs.writeFile(tmp, content, { encoding, mode });
+		// best-effort chmod（部分平台 writeFile 的 mode 可能不生效）
+		try { await fs.chmod(tmp, mode); } catch { /* ignore */ }
+		await fs.rename(tmp, filePath);
+		try { await fs.chmod(filePath, mode); } catch { /* ignore */ }
+	} finally {
+		// 确保临时文件不残留
+		await fs.rm(tmp, { force: true }).catch(() => {});
+	}
+}
+
+/**
+ * 原子写入 JSON 文件。
+ * 使用 2 空格缩进 + 尾部换行，与 OpenClaw 配置文件风格一致。
+ *
+ * @param {string} filePath - 目标文件路径
+ * @param {*} value - 要序列化的值
+ * @param {object} [opts]
+ * @param {number} [opts.mode=0o600] - 文件权限
+ * @param {number} [opts.dirMode] - 父目录权限
+ */
+async function atomicWriteJsonFile(filePath, value, opts) {
+	const text = JSON.stringify(value, null, 2) + '\n';
+	await atomicWriteFile(filePath, text, opts);
+}
+
+export { atomicWriteFile, atomicWriteJsonFile };

package/src/utils/mutex.js

@@ -0,0 +1,50 @@
+/**
+ * 进程内异步互斥锁。
+ * 用于保护 read-modify-write 等需要串行化的异步操作序列。
+ *
+ * 参照 OpenClaw createAsyncLock() 实现，基于 Promise 链的 FIFO 队列。
+ */
+
+/**
+ * 创建一把互斥锁，返回 `{ withLock }` 对象。
+ *
+ * 用法：
+ * ```js
+ * const mutex = createMutex();
+ * const result = await mutex.withLock(async () => {
+ *   const data = await readFile(path);
+ *   data.count += 1;
+ *   await writeFile(path, data);
+ *   return data;
+ * });
+ * ```
+ *
+ * @returns {{ withLock: <T>(fn: () => Promise<T>) => Promise<T> }}
+ */
+function createMutex() {
+	let lock = Promise.resolve();
+
+	/**
+	 * 排队执行 fn，同一时刻只有一个 fn 在运行。
+	 * fn 的返回值原样返回，fn 的异常原样抛出。
+	 * @param {() => Promise<*>} fn
+	 * @returns {Promise<*>}
+	 */
+	async function withLock(fn) {
+		const prev = lock;
+		let release;
+		lock = new Promise((resolve) => {
+			release = resolve;
+		});
+		await prev;
+		try {
+			return await fn();
+		} finally {
+			release?.();
+		}
+	}
+
+	return { withLock };
+}
+
+export { createMutex };