@shgroup/dsh-serenity-hooks 1.26.16 → 1.27.0

package/lib/weixin-route-CHCWBvLZ.js

@@ -0,0 +1,473 @@
+import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
+import { s as loadSerenityConfig, t as DEFAULT_SERENITY_CONFIG_PATHS } from "./ccc-CfDrlfA7.js";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { createHash } from "node:crypto";
+//#region src/localstore-ops.ts
+/**
+* localstore-ops.ts — localstore 纯逻辑层（零 DSH 依赖，可独立单测）
+*
+* S134 重设计（v1.16.7）：存储从 ~/.serenity/ 迁到 **CCC 根根目录 localstore.json**
+* （JSON 格式——方便 MSM 直接 read + JSON.parse 读取，零解析依赖）。
+*
+* git 提交策略（可靠机制 × 用户自由）：
+*   - 配置：.opencode/serenity.json `localstore.gitTrack`: "allow"（可提交）| "deny"（禁提交）
+*   - **缺省 deny（没配就是不提交）**；且 deny 的保证**不依赖 dsh 运行**——
+*     写入时自动确保 .gitignore 含 localstore.json（物理保证：即使 dsh 不在、
+*     用户手动 git commit 也不会误提交），cc_git 检查为第二道防线（拒绝 + 提示）
+*   - allow：放行（文件可提交，用户自行管理 .gitignore）
+*
+* 存储结构（JSON 顶层分节）：
+*   { "credentials": { "HOME_GITLAB_TOKEN": "xxx" }, "<config节>": { "<key>": "v" } }
+*   credentials 为保留节（credential 命名空间，key 大写蛇形）；其余节归 config 命名空间
+*   （path = section.key，如 handyman.models）。
+*/
+const LOCALSTORE_SCOPES = ["credential", "config"];
+/** 存储文件名（CCC 根根目录） */
+const LOCALSTORE_FILENAME = "localstore.json";
+/** 凭据保留节名（JSON 顶层） */
+const CREDENTIALS_SECTION = "credentials";
+/** 凭据 key 规范：大写蛇形，如 HOME_GITLAB_TOKEN */
+const CREDENTIAL_KEY_RE = /^[A-Z][A-Z0-9_]*$/;
+/** 配置节名规范：小写字母数字连字符 */
+const CONFIG_SECTION_RE = /^[a-z][a-z0-9-]*$/;
+/** 配置 key 规范（节内）：小驼峰，如 defaultModel */
+const CONFIG_KEY_RE = /^[a-z][a-zA-Z0-9_]*$/;
+/** 存储文件绝对路径（CCC 根根目录） */
+function localstorePath(root) {
+	return join(root, LOCALSTORE_FILENAME);
+}
+/** git 策略：serenity.json localstore.gitTrack，缺省 deny（不提交） */
+function readGitTrack(root, paths = DEFAULT_SERENITY_CONFIG_PATHS) {
+	return loadSerenityConfig(root, paths).localstore?.gitTrack === "allow" ? "allow" : "deny";
+}
+/** .gitignore 是否已覆盖 localstore 文件（非空非注释行含文件名即算） */
+function isLocalstoreGitignored(root) {
+	const gi = join(root, ".gitignore");
+	if (!existsSync(gi)) return false;
+	return readFileSync(gi, "utf-8").split("\n").some((l) => {
+		const t = l.trim();
+		return t !== "" && !t.startsWith("#") && t.includes("localstore.json");
+	});
+}
+/**
+* 确保 .gitignore 含 localstore 文件（deny 时的物理保证，不依赖 dsh 运行）：
+* 写入 localstore 时调用——deny（含缺省）且 .gitignore 未覆盖 → 自动追加一行。
+* allow → 不写入（放行，文件可提交）。
+*/
+function ensureLocalstoreGitignored(root) {
+	if (readGitTrack(root) === "allow") return { status: "allow" };
+	if (isLocalstoreGitignored(root)) return { status: "ignored" };
+	const gi = join(root, ".gitignore");
+	const existing = existsSync(gi) ? readFileSync(gi, "utf-8") : "";
+	const line = `${LOCALSTORE_FILENAME}  # ACC localstore (localstore.gitTrack defaults to deny — do not commit)`;
+	writeFileSync(gi, (existing.endsWith("\n") || existing === "" ? existing : existing + "\n") + line + "\n", "utf-8");
+	return { status: "appended" };
+}
+/**
+* cc_git 联动检查（第二道防线）：文件存在 && deny && .gitignore 未覆盖 → 不通过。
+* 调用方（cc_git commit）据此拒绝提交；status 可输出 warning。
+*/
+function checkLocalstoreGitCompliance(root) {
+	if (!existsSync(localstorePath(root))) return { ok: true };
+	if (readGitTrack(root) === "allow") return { ok: true };
+	if (isLocalstoreGitignored(root)) return { ok: true };
+	return {
+		ok: false,
+		reason: `localstore.json must not be committed (localstore.gitTrack=deny default) but .gitignore does not cover it — add ${LOCALSTORE_FILENAME} to .gitignore (or set localstore.gitTrack=allow to explicitly permit)`
+	};
+}
+/** 读取全文件（顶层分节）；文件不存在/坏 JSON 返回空 */
+function readAll(root) {
+	const p = localstorePath(root);
+	if (!existsSync(p)) return {};
+	try {
+		const v = JSON.parse(readFileSync(p, "utf-8").replace(/^\uFEFF/, ""));
+		if (v && typeof v === "object" && !Array.isArray(v)) return v;
+		return {};
+	} catch {
+		return {};
+	}
+}
+/** 写回全文件（2 空格缩进 + 尾换行，方便 MSM 直接读取） */
+function writeAll(root, data) {
+	writeFileSync(localstorePath(root), JSON.stringify(data, null, 2) + "\n", "utf-8");
+}
+/** 读取命名空间全部条目：credential → 扁平；config → 分节（剔除 credentials 保留节） */
+function readStore(root, scope) {
+	const all = readAll(root);
+	if (scope === "credential") return all["credentials"] ?? {};
+	const { [CREDENTIALS_SECTION]: _cred, ...rest } = all;
+	return rest;
+}
+/** 校验凭据 key 合法（大写蛇形）；不合法抛错 */
+function assertCredentialKey(key) {
+	if (!CREDENTIAL_KEY_RE.test(key)) throw new Error(`credential key "${key}" must match UPPER_SNAKE ^[A-Z][A-Z0-9_]*$ (e.g. HOME_GITLAB_TOKEN)`);
+}
+/** 校验 config 路径（节.key）；不合法抛错 */
+function assertConfigPath(path) {
+	const idx = path.indexOf(".");
+	if (idx <= 0 || idx === path.length - 1) throw new Error(`config path "${path}" must be section.key (e.g. handyman.models)`);
+	const section = path.slice(0, idx);
+	const key = path.slice(idx + 1);
+	if (!CONFIG_SECTION_RE.test(section)) throw new Error(`config section "${section}" must match ^[a-z][a-z0-9-]*$`);
+	if (!CONFIG_KEY_RE.test(key)) throw new Error(`config key "${key}" must match lowerCamel ^[a-z][a-zA-Z0-9_]*$ (e.g. defaultModel)`);
+	return {
+		section,
+		key
+	};
+}
+/** 写入单个条目（自动建文件；deny 默认时同步确保 .gitignore 物理保证） */
+function writeEntry(root, scope, name, value) {
+	const all = readAll(root);
+	if (scope === "credential") {
+		assertCredentialKey(name);
+		all[CREDENTIALS_SECTION] ??= {};
+		all[CREDENTIALS_SECTION][name] = value;
+	} else {
+		const { section, key } = assertConfigPath(name);
+		all[section] ??= {};
+		all[section][key] = value;
+	}
+	writeAll(root, all);
+	ensureLocalstoreGitignored(root);
+}
+/** 删除单个条目（不存在返回 false）；空节自动移除 */
+function unsetEntry(root, scope, name) {
+	const all = readAll(root);
+	if (scope === "credential") {
+		assertCredentialKey(name);
+		const sec = all[CREDENTIALS_SECTION];
+		if (!sec || !(name in sec)) return false;
+		delete sec[name];
+		if (Object.keys(sec).length === 0) delete all[CREDENTIALS_SECTION];
+	} else {
+		const { section, key } = assertConfigPath(name);
+		const sec = all[section];
+		if (!sec || !(key in sec)) return false;
+		delete sec[key];
+		if (Object.keys(sec).length === 0) delete all[section];
+	}
+	writeAll(root, all);
+	return true;
+}
+/** 读取单个条目值；不存在返回 null */
+function getEntry(root, scope, name) {
+	const all = readAll(root);
+	if (scope === "credential") {
+		assertCredentialKey(name);
+		return all["credentials"]?.[name] ?? null;
+	}
+	const { section, key } = assertConfigPath(name);
+	return all[section]?.[key] ?? null;
+}
+/** 列出 key（凭据只返回 key 名，不返回值） */
+function listKeys(root, scope) {
+	const data = readStore(root, scope);
+	if (scope === "credential") return Object.keys(data);
+	return Object.entries(data).flatMap(([section, entries]) => Object.keys(entries).map((key) => `${section}.${key}`));
+}
+/**
+* doc 说明文本：输出存储位置/格式/key 规范/git 策略/读写方法。
+* agent 据此可直接用 fs 工具（read/write）自己读写凭据/配置。
+*/
+function docText(root) {
+	const path = localstorePath(root);
+	return [
+		"# localstore — ACC local credential/config storage (standard, S134 redesign)",
+		"",
+		"One tool manages two namespaces: credential (credentials) + config (preferences).",
+		`Stored at the CCC root in ${path} (JSON format; MSMs can read + JSON.parse directly).`,
+		"",
+		"## Git commit policy",
+		"- Config: .opencode/serenity.json `localstore.gitTrack`: `\"allow\"` (may commit) | `\"deny\"` (must not commit; .dsh fallback)",
+		"- **Default deny (unset = not committed)**; when deny, writes automatically ensure .gitignore contains localstore.json",
+		"  (physical guarantee, independent of dsh runtime); cc_git commit checks and refuses",
+		"- To commit: set `\"localstore\": { \"gitTrack\": \"allow\" }` and remove localstore.json from .gitignore",
+		"",
+		"## Format (JSON top-level sections)",
+		"```json",
+		"{",
+		"  \"credentials\": {",
+		"    \"HOME_GITLAB_TOKEN\": \"xxx\"",
+		"  },",
+		"  \"handyman\": {",
+		"    \"models\": [\"minimax-cn-coding-plan/MiniMax-M3\"]",
+		"  }",
+		"}",
+		"```",
+		"- credentials is a reserved section (credentials, UPPER_SNAKE keys); other sections = config (path = section.key)",
+		"",
+		"## Key conventions",
+		"- credential key: ^[A-Z][A-Z0-9_]*$ (e.g. HOME_GITLAB_TOKEN)",
+		"- config path: section.key (section ^[a-z][a-z0-9-]*$, key lowerCamel ^[a-z][a-zA-Z0-9_]*$, e.g. handyman.models)",
+		"",
+		"## Reading (agents may use fs tools directly)",
+		`- Read ${path} with the read tool → JSON.parse`,
+		"- Or use localstore get <name> [--scope credential|config]",
+		"",
+		"## Writing",
+		"- Recommended: localstore set <name> <value> [--scope ...] (auto-creates file / preserves other entries / syncs .gitignore)",
+		"- Or modify the file directly with write/edit, keeping the JSON valid",
+		"",
+		"## Security boundary",
+		"- list/show return only key names for credentials, never values",
+		"- Credential values should be used internally by the agent; never write them into conversation or logs",
+		"- Default deny: the file is not committed to git (.gitignore physical guarantee + cc_git check fallback)",
+		""
+	].join("\n");
+}
+/** 运行 localstore 操作（纯逻辑；返回 JSON 值供工具 render） */
+function runLocalStore(root, args) {
+	const scope = args.scope === "config" ? "config" : "credential";
+	switch (args.action) {
+		case "list": return {
+			scope,
+			keys: listKeys(root, scope)
+		};
+		case "get": {
+			if (!args.name) throw new Error("get requires name");
+			const value = getEntry(root, scope, args.name);
+			if (value === null) throw new Error(`not found: ${args.name} (scope=${scope})`);
+			return {
+				scope,
+				name: args.name,
+				value,
+				source: scope
+			};
+		}
+		case "set": {
+			if (!args.name) throw new Error("set requires name");
+			if (args.value === void 0) throw new Error("set requires value");
+			writeEntry(root, scope, args.name, args.value);
+			const git = checkLocalstoreGitCompliance(root);
+			return {
+				scope,
+				name: args.name,
+				set: true,
+				path: localstorePath(root),
+				gitTrack: readGitTrack(root),
+				gitOk: git.ok,
+				git: git.reason ? { warning: git.reason } : null
+			};
+		}
+		case "unset": {
+			if (!args.name) throw new Error("unset requires name");
+			const removed = unsetEntry(root, scope, args.name);
+			return {
+				scope,
+				name: args.name,
+				removed
+			};
+		}
+		case "show": {
+			if (!args.name) throw new Error("show requires name");
+			const exists = getEntry(root, scope, args.name) !== null;
+			return {
+				scope,
+				name: args.name,
+				exists,
+				path: localstorePath(root)
+			};
+		}
+		case "doc": return { doc: docText(root) };
+		default: throw new Error(`Unknown subcommand: ${args.action} (available: list/get/set/unset/show/doc)`);
+	}
+}
+//#endregion
+//#region src/weixin-route.ts
+/**
+* weixin-route.ts — 微信桥 CCC 配置层纯逻辑（F4c-3，v1.27.0 实验性）
+*
+* 职责（零 DSH 依赖，可独立单测）：
+* - 读取 CCC 的 weixin 配置（.opencode/serenity.json weixin 段——结构/路由/开关）
+* - 读取/写入 CCC localstore 的账号凭据（weixin.accounts.<accountId>.token/.baseUrl/.userId）
+* - 微信用户 → skiff 会话 id 映射（固定可重建：skiff-weixin-<sha256(userid)>.slice(16)）
+* - 路由匹配（exact user → 通配 * 兜底）
+*
+* 配置归属（S142 用户拍板）：**CCC 级**——serenity.json 结构 + localstore 凭据分离；
+* 不绑定具体 role（用户自选路由目标）。
+*/
+var weixin_route_exports = /* @__PURE__ */ __exportAll({
+	WEIXIN_SESSION_PREFIX: () => WEIXIN_SESSION_PREFIX,
+	clearWeixinCredential: () => clearWeixinCredential,
+	extractWeixinText: () => extractWeixinText,
+	matchWeixinRoute: () => matchWeixinRoute,
+	readWeixinCredential: () => readWeixinCredential,
+	readWeixinSettings: () => readWeixinSettings,
+	removeWeixinAccount: () => removeWeixinAccount,
+	saveWeixinRoutes: () => saveWeixinRoutes,
+	setWeixinEnabled: () => setWeixinEnabled,
+	upsertWeixinAccount: () => upsertWeixinAccount,
+	weixinSessionIdFor: () => weixinSessionIdFor,
+	writeWeixinCredential: () => writeWeixinCredential
+});
+/** localstore 凭据键前缀（**credential scope**——token 是凭据，走 UPPER_SNAKE 键；
+*  格式 WEIXIN_<ACCOUNT_ID>_TOKEN / _BASEURL / _USERID（accountId 归一为大写蛇形）） */
+const LS_PREFIX = "WEIXIN_";
+/** accountId → UPPER_SNAKE 片段（wechat-1 → WECHAT_1） */
+function accountKeyPart(accountId) {
+	return accountId.toUpperCase().replace(/[^A-Z0-9]+/g, "_");
+}
+/** 微信桥 skiff 会话 id 前缀（seams 旁路判定；对外面纯净——守卫识别外部面） */
+const WEIXIN_SESSION_PREFIX = "skiff-weixin-";
+/** 微信用户 → 固定会话 id（同用户长期同一会话，记忆延续；多用户天然隔离） */
+function weixinSessionIdFor(fromUserId) {
+	const digest = createHash("sha256").update(fromUserId).digest("hex").slice(0, 16);
+	return `${WEIXIN_SESSION_PREFIX}${digest}`;
+}
+/**
+* 读取 CCC 微信桥配置（未配置/未启用 → 归一默认）。
+* @returns 归一化 WeixinSettings（accounts/routes 数组清洗；空段 → 空数组）
+*/
+function readWeixinSettings(root, paths = DEFAULT_SERENITY_CONFIG_PATHS) {
+	try {
+		const w = loadSerenityConfig(root, paths).weixin;
+		if (!w || typeof w !== "object") return {
+			enabled: false,
+			accounts: [],
+			routes: []
+		};
+		return {
+			enabled: w.enabled === true,
+			botType: typeof w.botType === "string" && w.botType !== "" ? w.botType : void 0,
+			accounts: Array.isArray(w.accounts) ? w.accounts.filter((a) => typeof a === "object" && a !== null && typeof a.accountId === "string" && a.accountId !== "").map((a) => ({
+				accountId: a.accountId,
+				name: typeof a.name === "string" ? a.name : void 0,
+				enabled: a.enabled !== false
+			})) : [],
+			routes: Array.isArray(w.routes) ? w.routes.filter((r) => typeof r === "object" && r !== null && typeof r.user === "string" && r.user !== "" && typeof r.role === "string" && r.role !== "") : []
+		};
+	} catch {
+		return {
+			enabled: false,
+			accounts: [],
+			routes: []
+		};
+	}
+}
+/** localstore 凭据键（credential scope: WEIXIN_<ACCOUNT_ID>_<FIELD>） */
+function lsKey(accountId, field) {
+	return `${LS_PREFIX}${accountKeyPart(accountId)}_${field}`;
+}
+/** 读取账号凭据（token 缺失 → null——账号未绑定） */
+function readWeixinCredential(root, accountId) {
+	const token = getEntry(root, "credential", lsKey(accountId, "TOKEN"));
+	if (!token) return null;
+	const baseUrl = getEntry(root, "credential", lsKey(accountId, "BASEURL"));
+	const userId = getEntry(root, "credential", lsKey(accountId, "USERID"));
+	return {
+		token,
+		baseUrl: baseUrl ?? "",
+		userId: userId ?? void 0
+	};
+}
+/** 写入账号凭据（扫码 confirmed 后；token 必写，baseUrl/userId 可选） */
+function writeWeixinCredential(root, accountId, cred) {
+	writeEntry(root, "credential", lsKey(accountId, "TOKEN"), cred.token);
+	if (cred.baseUrl) writeEntry(root, "credential", lsKey(accountId, "BASEURL"), cred.baseUrl);
+	if (cred.userId) writeEntry(root, "credential", lsKey(accountId, "USERID"), cred.userId);
+}
+/** 清除账号凭据（移除账号时） */
+function clearWeixinCredential(root, accountId) {
+	unsetEntry(root, "credential", lsKey(accountId, "TOKEN"));
+	unsetEntry(root, "credential", lsKey(accountId, "BASEURL"));
+	unsetEntry(root, "credential", lsKey(accountId, "USERID"));
+}
+/**
+* 路由匹配：exact user 优先，通配 `*` 兜底。
+* @returns 命中的 role 名；未命中 → null（无路由 → 消息不回复/忽略）
+*/
+function matchWeixinRoute(routes, fromUserId) {
+	if (!Array.isArray(routes) || routes.length === 0) return null;
+	for (const r of routes) if (r.user === fromUserId) return r.role;
+	for (const r of routes) if (r.user === "*") return r.role;
+	return null;
+}
+/**
+* 提取消息文本（item_list 首条 text_item；非文本消息 → null——P1 只处理文本）。
+* @returns 纯文本；无文本 → null
+*/
+function extractWeixinText(msg) {
+	const items = msg.item_list;
+	if (!Array.isArray(items) || items.length === 0) return null;
+	for (const item of items) if (item.type === 1 && typeof item.text_item?.text === "string") {
+		const text = item.text_item.text.trim();
+		return text === "" ? null : text;
+	}
+	return null;
+}
+/**
+* 读取 serenity.json 文件（原始；不存在 → 空对象）。
+* 注意：loadSerenityConfig 返回解析对象但无法写回——此处直接文件读写。
+*/
+function readRawConfig(root, paths = DEFAULT_SERENITY_CONFIG_PATHS) {
+	for (const candidate of paths) {
+		const p = resolve(root, candidate);
+		if (existsSync(p)) try {
+			const v = JSON.parse(readFileSync(p, "utf-8").replace(/^\uFEFF/, ""));
+			if (v && typeof v === "object" && !Array.isArray(v)) return v;
+		} catch {
+			return {};
+		}
+	}
+	return {};
+}
+/** 写入 serenity.json（保留既有字段；weixin 段整体替换） */
+function writeWeixinSection(root, weixin, paths = DEFAULT_SERENITY_CONFIG_PATHS) {
+	const target = resolve(root, paths[0] ?? ".opencode/serenity.json");
+	const raw = readRawConfig(root, paths);
+	raw.weixin = weixin;
+	const dir = resolve(target, "..");
+	if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+	writeFileSync(target, JSON.stringify(raw, null, 2) + "\n", "utf-8");
+}
+/** 添加/更新账号（serenity.json 结构部分；凭据单独写 localstore） */
+function upsertWeixinAccount(root, account) {
+	const settings = readWeixinSettings(root);
+	const accounts = settings.accounts ?? [];
+	const idx = accounts.findIndex((a) => a.accountId === account.accountId);
+	if (idx >= 0) accounts[idx] = {
+		...accounts[idx],
+		...account
+	};
+	else accounts.push(account);
+	const next = {
+		...settings,
+		accounts
+	};
+	writeWeixinSection(root, next);
+	return next;
+}
+/** 移除账号（serenity.json 结构 + localstore 凭据；同时停桥由调用方 syncCccBridge） */
+function removeWeixinAccount(root, accountId) {
+	const settings = readWeixinSettings(root);
+	const accounts = (settings.accounts ?? []).filter((a) => a.accountId !== accountId);
+	const next = {
+		...settings,
+		accounts
+	};
+	writeWeixinSection(root, next);
+	clearWeixinCredential(root, accountId);
+	return next;
+}
+/** 保存路由表（整体替换） */
+function saveWeixinRoutes(root, routes) {
+	const next = {
+		...readWeixinSettings(root),
+		routes
+	};
+	writeWeixinSection(root, next);
+	return next;
+}
+/** 切换总开关 */
+function setWeixinEnabled(root, enabled) {
+	const next = {
+		...readWeixinSettings(root),
+		enabled
+	};
+	writeWeixinSection(root, next);
+	return next;
+}
+//#endregion
+export { weixinSessionIdFor as a, checkLocalstoreGitCompliance as c, runLocalStore as d, readWeixinSettings as i, localstorePath as l, matchWeixinRoute as n, weixin_route_exports as o, readWeixinCredential as r, LOCALSTORE_SCOPES as s, extractWeixinText as t, readGitTrack as u };

package/lib/weixin-route.d.ts

@@ -0,0 +1,61 @@
+/**
+ * weixin-route.ts — 微信桥 CCC 配置层纯逻辑（F4c-3，v1.27.0 实验性）
+ *
+ * 职责（零 DSH 依赖，可独立单测）：
+ * - 读取 CCC 的 weixin 配置（.opencode/serenity.json weixin 段——结构/路由/开关）
+ * - 读取/写入 CCC localstore 的账号凭据（weixin.accounts.<accountId>.token/.baseUrl/.userId）
+ * - 微信用户 → skiff 会话 id 映射（固定可重建：skiff-weixin-<sha256(userid)>.slice(16)）
+ * - 路由匹配（exact user → 通配 * 兜底）
+ *
+ * 配置归属（S142 用户拍板）：**CCC 级**——serenity.json 结构 + localstore 凭据分离；
+ * 不绑定具体 role（用户自选路由目标）。
+ */
+import { type WeixinSettings, type WeixinRouteConfig, type WeixinAccountConfig } from './ccc.js';
+/** 微信桥 skiff 会话 id 前缀（seams 旁路判定；对外面纯净——守卫识别外部面） */
+export declare const WEIXIN_SESSION_PREFIX = "skiff-weixin-";
+/** 判定 sessionId 是否为微信桥会话（外部面——输出守卫/轨迹隐藏生效） */
+export declare function isWeixinSessionId(sessionId: string | undefined): boolean;
+/** 微信用户 → 固定会话 id（同用户长期同一会话，记忆延续；多用户天然隔离） */
+export declare function weixinSessionIdFor(fromUserId: string): string;
+/**
+ * 读取 CCC 微信桥配置（未配置/未启用 → 归一默认）。
+ * @returns 归一化 WeixinSettings（accounts/routes 数组清洗；空段 → 空数组）
+ */
+export declare function readWeixinSettings(root: string, paths?: string[]): WeixinSettings;
+/** 账号凭据（localstore credential scope；baseUrl 缺省 = 官方默认） */
+export interface WeixinAccountCredential {
+    token: string;
+    baseUrl: string;
+    userId?: string;
+}
+/** 读取账号凭据（token 缺失 → null——账号未绑定） */
+export declare function readWeixinCredential(root: string, accountId: string): WeixinAccountCredential | null;
+/** 写入账号凭据（扫码 confirmed 后；token 必写，baseUrl/userId 可选） */
+export declare function writeWeixinCredential(root: string, accountId: string, cred: WeixinAccountCredential): void;
+/** 清除账号凭据（移除账号时） */
+export declare function clearWeixinCredential(root: string, accountId: string): void;
+/**
+ * 路由匹配：exact user 优先，通配 `*` 兜底。
+ * @returns 命中的 role 名；未命中 → null（无路由 → 消息不回复/忽略）
+ */
+export declare function matchWeixinRoute(routes: WeixinRouteConfig[], fromUserId: string): string | null;
+/**
+ * 提取消息文本（item_list 首条 text_item；非文本消息 → null——P1 只处理文本）。
+ * @returns 纯文本；无文本 → null
+ */
+export declare function extractWeixinText(msg: {
+    item_list?: Array<{
+        type?: number;
+        text_item?: {
+            text?: string;
+        };
+    }>;
+}): string | null;
+/** 添加/更新账号（serenity.json 结构部分；凭据单独写 localstore） */
+export declare function upsertWeixinAccount(root: string, account: WeixinAccountConfig): WeixinSettings;
+/** 移除账号（serenity.json 结构 + localstore 凭据；同时停桥由调用方 syncCccBridge） */
+export declare function removeWeixinAccount(root: string, accountId: string): WeixinSettings;
+/** 保存路由表（整体替换） */
+export declare function saveWeixinRoutes(root: string, routes: WeixinRouteConfig[]): WeixinSettings;
+/** 切换总开关 */
+export declare function setWeixinEnabled(root: string, enabled: boolean): WeixinSettings;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shgroup/dsh-serenity-hooks",
-  "version": "1.26.16",
+  "version": "1.27.0",
   "description": "宁静号 ACC harness — Native Cordis 插件（DeepSeek Harness 运行时）。真实 DSH 工具注册（cc_fs/session/acc_msm 等 9 工具）+ 拦截缝机械约束（safe-mode/路径守卫/会话落盘）+ 系统提示词注入（ACC/CCE/Constraints/SKILL/Session 五块）。适配 DSH 公开版（deepseek-ai/deepseek-harness 0.1.0-rc）。",
   "license": "MIT",
   "repository": {