dsh-remote-bridge 2.5.2 → 2.6.0

package/lib/index.js

@@ -2926,7 +2926,7 @@ function createDsh02ApiProxy(host, options = {}) {
 }
 //#endregion
 //#region src/shared/version.ts
-const PLUGIN_VERSION = "2.5.2";
+const PLUGIN_VERSION = "2.6.0";
 //#endregion
 //#region src/host/capabilities.ts
 /**
@@ -3978,7 +3978,7 @@ function normalizeDshEvent(frame, fallback, time = Date.now()) {
 			}
 		};
 	}
-	if (payloadType === "session/event" && typeof payload.sessionId === "string" && isRecord$1(payload.event)) {
+	if (payloadType === "session/event" && typeof payload.sessionId === "string" && isRecord$2(payload.event)) {
 		const event = payload.event;
 		const eventType = typeof event.type === "string" ? event.type : "unknown";
 		const seq = typeof event.seq === "number" ? event.seq : void 0;
@@ -3988,9 +3988,9 @@ function normalizeDshEvent(frame, fallback, time = Date.now()) {
 			...seq === void 0 ? {} : { seq }
 		};
 		const assistantData = event.data;
-		if (eventType === "assistant/chunk" && isRecord$1(assistantData)) {
+		if (eventType === "assistant/chunk" && isRecord$2(assistantData)) {
 			const rawChunk = assistantData.chunk;
-			if (isRecord$1(rawChunk)) {
+			if (isRecord$2(rawChunk)) {
 				const kind = rawChunk.type === "text-delta" ? "text" : rawChunk.type === "reasoning-delta" ? "reasoning" : void 0;
 				if (kind !== void 0 && typeof rawChunk.text === "string" && typeof rawChunk.index === "number") return {
 					id: frame.rpcId,
@@ -4008,7 +4008,7 @@ function normalizeDshEvent(frame, fallback, time = Date.now()) {
 			}
 		}
 		if (eventType === "user/message" || eventType === "assistant/message") {
-			const eventData = isRecord$1(event.data) ? event.data : {};
+			const eventData = isRecord$2(event.data) ? event.data : {};
 			return {
 				id: frame.rpcId,
 				type: "chat.message.committed",
@@ -4022,8 +4022,8 @@ function normalizeDshEvent(frame, fallback, time = Date.now()) {
 			};
 		}
 		if (eventType === "deliverables/presented") {
-			const data = isRecord$1(payload.event) ? payload.event.data : void 0;
-			const files = isRecord$1(data) && Array.isArray(data.files) ? data.files : [];
+			const data = isRecord$2(payload.event) ? payload.event.data : void 0;
+			const files = isRecord$2(data) && Array.isArray(data.files) ? data.files : [];
 			return {
 				id: `${payload.sessionId}:deliverables:${seq ?? files.length}`,
 				type: "chat.deliverables.presented",
@@ -4051,7 +4051,7 @@ function normalizeDshEvent(frame, fallback, time = Date.now()) {
 					};
 				}
 			}
-			const turnReason = eventType === "turn/end" && isRecord$1(event.data) ? event.data.reason : void 0;
+			const turnReason = eventType === "turn/end" && isRecord$2(event.data) ? event.data.reason : void 0;
 			return {
 				id: frame.rpcId,
 				type: eventType === "turn/start" ? "chat.turn.start" : "chat.turn.end",
@@ -4111,12 +4111,12 @@ function normalizeDshEvent(frame, fallback, time = Date.now()) {
 * 用本地化文案「API 密钥无效」顶上。这里保持原样转发，不替客户端猜。
 */
 function turnFailureOf(event) {
-	const reason = isRecord$1(event.data) ? event.data.reason : void 0;
-	if (!isRecord$1(reason)) return void 0;
+	const reason = isRecord$2(event.data) ? event.data.reason : void 0;
+	if (!isRecord$2(reason)) return void 0;
 	const kind = reason.kind;
 	if (kind === "error") {
 		const error = reason.error;
-		if (!isRecord$1(error)) return { message: String(error ?? "本轮运行失败") };
+		if (!isRecord$2(error)) return { message: String(error ?? "本轮运行失败") };
 		const code = typeof error.code === "string" ? error.code : void 0;
 		const message = typeof error.message === "string" ? error.message : JSON.stringify(error);
 		return code === void 0 ? { message } : {
@@ -4124,13 +4124,13 @@ function turnFailureOf(event) {
 			code
 		};
 	}
-	if (kind === "aborted" && isRecord$1(reason.reason) && reason.reason.kind === "hook" && reason.reason.reason === "deepseek-account/signed-out") return {
+	if (kind === "aborted" && isRecord$2(reason.reason) && reason.reason.kind === "hook" && reason.reason.reason === "deepseek-account/signed-out") return {
 		message: "Stopped because you signed out of DeepSeek.",
 		code: "ACCOUNT_SIGNED_OUT",
 		stopped: true
 	};
 }
-function isRecord$1(value) {
+function isRecord$2(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function matchRoot(roots, cwd) {
@@ -4216,13 +4216,13 @@ function findToolCallDetail(events, callId) {
 	if (callId === void 0) return void 0;
 	for (let index = events.length - 1; index >= 0; index -= 1) {
 		const candidate = events[index];
-		if (!isRecord$1(candidate)) continue;
-		const event = isRecord$1(candidate.event) ? candidate.event : candidate;
-		if (event.type !== "tool/call" || !isRecord$1(event.data)) continue;
+		if (!isRecord$2(candidate)) continue;
+		const event = isRecord$2(candidate.event) ? candidate.event : candidate;
+		if (event.type !== "tool/call" || !isRecord$2(event.data)) continue;
 		const data = event.data;
 		if ((typeof data.callId === "string" ? data.callId : typeof data.id === "string" ? data.id : void 0) !== callId) continue;
 		const args = decodeToolArguments(data.arguments);
-		if (isRecord$1(args) && typeof args.command === "string") return args.command;
+		if (isRecord$2(args) && typeof args.command === "string") return args.command;
 		if (typeof args === "string") return args;
 		if (args !== void 0) return JSON.stringify(args, null, 2);
 	}
@@ -4616,9 +4616,62 @@ var WorkspaceDatabase = class {
 	* 干净的办法制造这种行，而它不该走生产代码路径 —— 所以显式开一个测试专用入口，
 	* 并起一个自见其明的名字，免得有人把它当成正常 API。
 	*/
+	/**
+	* 仅供测试：把某台设备的「最后使用时间/创建时间」拨到过去。
+	*
+	* 生产路径没法造出「30 天没动过」的设备（认证一次就刷新 `last_seen_at`），而
+	* `pruneInactiveDevices` 的核心语义恰恰只在这种时间跨度上才看得见。与
+	* `markRevokedForTest` 同样的理由：显式开一个自见其明的测试入口，别让人误当 API。
+	*/
+	backdateDeviceForTest(id, options) {
+		if (options.lastSeenAt !== void 0) this.db.prepare("UPDATE devices SET last_seen_at = ? WHERE id = ?").run(options.lastSeenAt, id);
+		if (options.createdAt !== void 0) this.db.prepare("UPDATE devices SET created_at = ? WHERE id = ?").run(options.createdAt, id);
+	}
 	markRevokedForTest(id) {
 		this.db.prepare("UPDATE devices SET revoked_at = ? WHERE id = ?").run(Date.now(), id);
 	}
+	/**
+	* 按「最后使用时间」批量清掉长期没动过的设备。
+	*
+	* 「最后使用」取 `last_seen_at`（每次令牌认证成功都会刷新），从没认证过的设备退回
+	* `created_at` —— 否则一条配好就再没开过的设备会永远躲过清理，而那恰恰是用户最想
+	* 一键清掉的那类（换手机、临时配对、旧测试探针）。
+	*
+	* 与 `purgeRevokedDevices` 的区别：后者清的是历史遗留的「标记式撤销」脏行，这里清的是
+	* **仍然有效、但已经不用了**的设备 —— 用户的原话是「一键清理多少天未使用设备」。
+	*
+	* 语义边界（故意这么定）：
+	* - 只删设备行 + 级联的 `device_roots`，不碰审计（审计的 `actor_id` 不是外键）；
+	* - **不删本机正在用的那台**（`keepDeviceId`）：调用方就是它，删掉自己会让当前
+	*   客户端立刻 401，看起来像「点一下清理把手机踢下线了」；
+	* - 天数被夹在 1..3650，避免 `0` 或负数变成「清空所有设备」；
+	* - 返回真正删掉的条数，0 也是一次合法结果。
+	*/
+	pruneInactiveDevices(olderThanDays, options = {}) {
+		const days = Math.min(3650, Math.max(1, Math.trunc(olderThanDays)));
+		const cutoff = Date.now() - days * 24 * 60 * 60 * 1e3;
+		const rows = this.db.prepare("SELECT id, name FROM devices WHERE COALESCE(last_seen_at, created_at) < ? AND id IS NOT ?").all(cutoff, options.keepDeviceId ?? null);
+		if (rows.length === 0) {
+			this.devicesRevisionCounter += 1;
+			return 0;
+		}
+		this.db.exec("BEGIN IMMEDIATE");
+		try {
+			const statement = this.db.prepare("DELETE FROM devices WHERE id = ?");
+			for (const row of rows) statement.run(row.id);
+			this.audit("admin", "loopback-admin", "device.prune", void 0, void 0, {
+				olderThanDays: days,
+				pruned: rows.length,
+				names: rows.map((row) => row.name)
+			}, options.requestId);
+			this.db.exec("COMMIT");
+		} catch (error) {
+			this.db.exec("ROLLBACK");
+			throw error;
+		}
+		this.devicesRevisionCounter += 1;
+		return rows.length;
+	}
 	purgeRevokedDevices() {
 		if (this.db.prepare("SELECT id FROM devices WHERE revoked_at IS NOT NULL").all().length === 0) {
 			this.devicesRevisionCounter += 1;
@@ -5448,6 +5501,176 @@ function probeHostServices(host, pluginVersion) {
 	};
 }
 //#endregion
+//#region src/host/im-command.ts
+/**
+* `/tunnel` —— 从即时通讯（微信 / 飞书 / 钉钉 / 企业微信 …）里远程开隧道并取回配置文本。
+*
+* ## 为什么需要它
+*
+* 用户常见的困境是「人已经出门，才发现电脑上的 Cloudflare 隧道没开，配置文本也没发给自己」。
+* 此时公网入口不存在，WebUI 与 App 都够不着这台机器 —— 唯一的反向通道是 IM 机器人的
+* **长连接**（手机/IM 云 → 本机主动连出去，不需要任何入站端口）。
+*
+* 本模块只做一件事：注册一条 `/tunnel` 命令，把「开隧道 + 生成 DSH1 配置文本」的结果
+* 直接作为聊天消息回给发送者。**不做停止、不做改配置、不读任何文件** —— 攻击面刻意压到
+* 「最多被人开一次隧道」，而隧道本身不授予任何数据面权限（数据面仍要设备令牌）。
+*
+* ## 门禁在哪里（重要）
+*
+* 本命令**自己不做身份校验**，它依赖 IM 插件在派发命令之前执行的访问策略：
+* `@xmanrui/dsh-im` 的每个机器人都有 `canExecuteCommands` / `defaultCanExecuteCommands`，
+* 非白名单发送者的 `/xxx` 根本到不了这里（`lib/index.js` 的 access policy 判定）。因此
+* 部署侧的必要条件是：**机器人保持 allowlist 模式，且只把自己加进白名单**。
+* 这条约束写在 README「远程开隧道」一节与 SECURITY.md 里，别只在代码注释里说。
+*
+* ## 为什么直接调宿主 API 而不是走 HTTP 自调用
+*
+* 「已开隧道」这一状态下，`/manage` 管理面被判据 0 整体关门（`auth.ts` 的
+* `TUNNEL_MODE_ADMIN_DISABLED`），`/manage/config/text` 必然 403 —— 走 HTTP 就取不到
+* 配置文本。命令在插件进程内执行，与路由共用同一个隧道管理器与同一套建配置逻辑，
+* 天然绕开这个自锁，且不需要为它额外豁免任何端点。
+*
+* @module dsh-remote-bridge/im-command
+*/
+/** 命令名（不带斜杠）。 */
+const TUNNEL_COMMAND_NAME = "tunnel";
+/** 命令描述：会出现在 IM 的 `/help` 里。 */
+const TUNNEL_COMMAND_DESCRIPTION = "开启 Cloudflare 隧道并返回一行配置文本（DSH1:…）";
+/** 把结果拼成聊天消息。 */
+function formatTunnelReply(result) {
+	return [
+		"云隧道已开启。",
+		`地址：${result.url}`,
+		`设备名：${result.deviceName}`,
+		"配置文本（一行，复制后粘贴到 App 的「导入配置」）：",
+		result.text
+	].join("\n");
+}
+/**
+* 创建 `/tunnel` 的命令定义（不注册，纯数据，便于单测）。
+*
+* 参数只接受空串：本命令刻意**不接受**任何开关，避免出现「`/tunnel stop`」这种需要
+* 额外鉴权语义的入口。带参数一律回用法说明。
+*/
+function createTunnelCommand(deps) {
+	/** 同一时刻只允许一次开隧道（IM 侧重发、双端同时发都可能撞上）。 */
+	let inFlight = false;
+	return {
+		name: TUNNEL_COMMAND_NAME,
+		description: TUNNEL_COMMAND_DESCRIPTION,
+		input: { hint: "（无需参数）" },
+		async handler(invocation) {
+			if (invocation.rawInput.trim().length > 0) return {
+				kind: "error",
+				text: "用法：/tunnel（不需要参数）"
+			};
+			if (inFlight) return {
+				kind: "error",
+				text: "上一次开隧道还没结束，请稍等几秒再发一次。"
+			};
+			inFlight = true;
+			try {
+				const result = await deps.openTunnel();
+				deps.logger?.info(`[dsh-remote-bridge] /tunnel 已开启隧道 ${result.url}`);
+				return {
+					kind: "success",
+					text: formatTunnelReply(result)
+				};
+			} catch (cause) {
+				const message = cause instanceof Error ? cause.message : String(cause);
+				deps.logger?.warn(cause instanceof Error ? cause : new Error(message));
+				return {
+					kind: "error",
+					text: `开隧道失败：${message}`
+				};
+			} finally {
+				inFlight = false;
+			}
+		}
+	};
+}
+/**
+* 注册 `/tunnel` 并返回注销函数。
+*
+* 注册是**全局层**（不是 agent 子层），所以任何 IM 会话、任何工作区里都能用 ——
+* 这正是本命令的用途：开机时人不在电脑边。是否允许某个人执行，由 IM 插件的
+* 访问策略决定（见模块头注释）。
+*/
+function registerTunnelCommand(registry, deps) {
+	return registry.register(createTunnelCommand(deps));
+}
+/**
+* ## 为什么除命令之外还要一个工具
+*
+* `@xmanrui/dsh-im` 5.4.0 的斜杠命令表是**封闭的**：内置 31 条，另外只把
+* `/compact` `/clear` `/permission` 三条委派给宿主（`lib/index.js` 里
+* `executeCommand("/compact")` 等固定字面量），**没有**「未知命令转交宿主命令表」的通用派发，
+* 也从不调用 `commands.list`。所以在 IM 里发 `/tunnel` 到不了上面那个命令处理函数 ——
+* 它会当成一句普通消息交给智能体。
+*
+* 于是 IM 侧真正可用的入口是**工具**：用户用自然语言说一句（「帮我开隧道，把配置发我」），
+* 智能体调用本工具，结果直接回到聊天里。命令与工具共用同一个 `openTunnel()`，
+* 语义完全一致；两者的差别只是「谁来触发」。
+*/
+/** 工具名（模型可见）。 */
+const TUNNEL_TOOL_NAME = "open_tunnel_config";
+/**
+* 模型可见描述。
+*
+* 写英文是惯例（工具描述面向模型，与仓内其他描述同语言），并显式写清
+* 「用户说开隧道/取配置文本时调用」，否则模型倾向于自己用 bash 拼一条 curl。
+*/
+const TUNNEL_TOOL_DESCRIPTION = "Open the Cloudflare quick tunnel for this DSH host and return a one-line DSH1: config text that a phone app can paste to connect. Use it whenever the user asks to start the tunnel, to get the config text, or says they are away from the computer and need remote access. It never stops the tunnel and never touches files.";
+/** 创建工具定义（不注册，便于单测）。 */
+function createTunnelTool(deps) {
+	return {
+		name: TUNNEL_TOOL_NAME,
+		description: TUNNEL_TOOL_DESCRIPTION,
+		parameters: {},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					url: {
+						type: "string",
+						required: true
+					},
+					text: {
+						type: "string",
+						required: true
+					},
+					deviceName: {
+						type: "string",
+						required: true
+					}
+				},
+				required: true
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: `Tunnel is up at ${value.url}`
+			}, {
+				type: "text",
+				text: value.text
+			}]
+		},
+		async execute() {
+			const result = await deps.openTunnel();
+			deps.logger?.info(`[dsh-remote-bridge] ${TUNNEL_TOOL_NAME} 已开启隧道 ${result.url}`);
+			return {
+				url: result.url,
+				text: result.text,
+				deviceName: result.deviceName
+			};
+		}
+	};
+}
+/** 注册工具并返回注销函数。注册是全局层：任何会话（含 IM 会话）都能调用。 */
+function registerTunnelTool(registry, deps) {
+	return registry.register(createTunnelTool(deps));
+}
+//#endregion
 //#region src/host/retention.ts
 /**
 * 数据保留（retention）调度器：把**会无限增长的两张表**按时间清掉。
@@ -6308,6 +6531,129 @@ async function inspectResolvedPath(root, wirePath) {
 	};
 }
 //#endregion
+//#region src/host/settings-namespace.ts
+/**
+* 通用设置命名空间的纯逻辑：写允许策略、密钥脱敏、ops 校验与响应投影。
+*
+* 为什么单独成文件（2.6.0）：这一层不碰任何内核 RPC，全部可以纯单测；
+* 而 `settings-adapter.ts` 已贴着 `AGENTS.md` §3.2 的 600 行单文件预算。
+* 拆出来之后两边都不再挤，adapter 只保留「调内核 + 映射错误」的那几行。
+*
+* 契约见 `docs/api/openapi.yaml` 的 SettingsNamespace* 与 `docs/project/API.md`
+* 的「通用设置命名空间」一节；安全判据的理由见 `docs/project/SECURITY.md`。
+*/
+const MAX_OPS = 32;
+/**
+* 键名兜底脱敏正则。
+*
+* **不是主要机制**：内核 `settings.describe()` 已经用 `redactSecrets: true` 读过一遍，
+* role('secret') 的字段不会随响应出网（见 dsh-api-settings-controller 的
+* `namespaceView`/`describe`）。这里是第二道保险 —— 万一某个自定义 schema 漏标了
+* role('secret')，或者凭据被写进了普通字段，桥也不会把它端给手机。
+*
+* `apiKeyEnv` 是环境变量**名**不是密钥值，一并遮蔽是刻意的：名字本身能暴露
+* 「这台机器用哪家 key」，而 App 读设置根本不需要这个名字。
+*/
+const SECRET_KEY = /^(apiKey|secret|token|password|credential|apiKeyEnv)$/i;
+/**
+* 写允许策略：`ui-*`（界面类插件设置）与 `*locale`（语言/区域）默认可写。
+*
+* 其余一律默认只读，尤其是能改「模型、权限、子代理」的命名空间 —— 手机一旦
+* 丢了或被恶意 App 拿到令牌，改模型等于把请求引到攻击者的端点，改权限等于
+* 把审批闸门拆掉。需要放行时由部署者显式配 `settingsWriteNamespaces`。
+*/
+function isSettingsNamespaceWriteAllowed(ns, extra = []) {
+	if (ns.startsWith("ui-") || ns.endsWith("locale")) return true;
+	return extra.some((pattern) => pattern.endsWith("*") ? ns.startsWith(pattern.slice(0, -1)) : ns === pattern);
+}
+/**
+* 单个命名空间不可写的原因。
+*
+* 宿主设置文档整体只读优先报 `HOST_READONLY`：那与 ns 策略无关，修策略也没用。
+*/
+function settingsNamespaceReason(hostWritable, ns, extra = []) {
+	if (!hostWritable) return "HOST_READONLY";
+	if (!isSettingsNamespaceWriteAllowed(ns, extra)) return "HIGH_RISK_NAMESPACE";
+}
+/**
+* 递归遮蔽密钥：键名命中 {@link SECRET_KEY}，或路径整体命中内核给出的
+* `secrets[].path`（前者是兜底，后者才是权威）。
+*
+* 路径按 `\u0000` 拼接比较，避免 `['a.b']` 与 `['a','b']` 混淆；
+* 数组下标也进路径，密钥恰好是数组元素时同样能命中。
+*/
+function redactSettingsSecrets(value, secretPaths = []) {
+	const exact = new Set(secretPaths.map((path) => path.join("\0")));
+	return walk(value, []);
+	function walk(current, path) {
+		if (path.length > 0 && exact.has(path.join("\0"))) return "***";
+		if (typeof current === "string") {
+			const key = path.at(-1);
+			return key !== void 0 && SECRET_KEY.test(key) ? "***" : current;
+		}
+		if (Array.isArray(current)) return current.map((item, index) => walk(item, [...path, String(index)]));
+		if (isRecord$1(current)) return Object.fromEntries(Object.entries(current).map(([key, item]) => [key, walk(item, [...path, key])]));
+		return current;
+	}
+}
+/** 校验并规范化请求里的 `ops`；结构不合法一律 400 `SETTINGS_OPS_INVALID`。 */
+function parseSettingsNamespaceOps(input) {
+	if (!Array.isArray(input) || input.length === 0 || input.length > MAX_OPS) throw new ApiError(400, "SETTINGS_OPS_INVALID", `ops must be an array of 1 to ${MAX_OPS} operations.`);
+	return input.map((raw, index) => {
+		const where = `ops[${index}]`;
+		if (!isRecord$1(raw)) throw invalid(`${where} must be an object.`);
+		if (raw.op !== "set" && raw.op !== "unset") throw invalid(`${where}.op must be "set" or "unset".`);
+		if (!Array.isArray(raw.path) || raw.path.some((segment) => typeof segment !== "string")) throw invalid(`${where}.path must be an array of strings.`);
+		const path = [...raw.path];
+		if (raw.op === "unset") return {
+			op: "unset",
+			path
+		};
+		if (!Object.hasOwn(raw, "value")) throw invalid(`${where}.value is required for "set".`);
+		return {
+			op: "set",
+			path,
+			value: raw.value
+		};
+	});
+}
+/** 审计用字段清单：只记路径，**绝不记值**。根路径（空数组）不产生字段名。 */
+function settingsNamespaceOpFields(ops) {
+	return [...new Set(ops.map((op) => op.path.join(".")).filter((field) => field !== ""))];
+}
+/** 本次写入是否碰到了密钥位（审计 `credentialChanged`）；只看路径，不看值。 */
+function settingsNamespaceCredentialChanged(ops, secrets) {
+	if (secrets === void 0 || secrets.length === 0) return false;
+	const exact = new Set(secrets.map((secret) => secret.path.join("\0")));
+	return ops.some((op) => exact.has(op.path.join("\0")));
+}
+/** 内核视图 → 对外视图：叠加写策略并脱敏。 */
+function projectSettingsNamespace(view, hostWritable, extra = []) {
+	const writable = hostWritable && isSettingsNamespaceWriteAllowed(view.ns, extra);
+	const secretPaths = (view.secrets ?? []).map((secret) => secret.path);
+	const project = (value) => redactSettingsSecrets(value, secretPaths);
+	const reason = settingsNamespaceReason(hostWritable, view.ns, extra);
+	return {
+		ns: view.ns,
+		revision: view.revision,
+		...view.schema === void 0 ? {} : { schema: view.schema },
+		value: project(view.value),
+		...view.base === void 0 ? {} : { base: project(view.base) },
+		...view.user === void 0 ? {} : { user: project(view.user) },
+		...view.autoGenerate === void 0 ? {} : { autoGenerate: view.autoGenerate },
+		...view.applies === void 0 ? {} : { applies: view.applies },
+		...view.secrets === void 0 ? {} : { secrets: view.secrets },
+		writable,
+		...reason === void 0 ? {} : { reason }
+	};
+}
+function invalid(message) {
+	return new ApiError(400, "SETTINGS_OPS_INVALID", message);
+}
+function isRecord$1(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
 //#region src/host/wire-json.ts
 /**
 * 出网 JSON 的安全序列化：把**孤立 UTF-16 代理项**换成 U+FFFD。
@@ -6667,6 +7013,27 @@ var ApiRouter = class {
 			sendJson(res, 200, await this.options.settings.catalog());
 			return;
 		}
+		if (method === "GET" && pathname === "/api/v1/settings/namespaces") {
+			this.options.auth.requireScope(principal, "settings.read");
+			sendJson(res, 200, await this.options.settings.describeNamespaces());
+			return;
+		}
+		const settingsNamespaceRoute = pathname.match(/^\/api\/v1\/settings\/namespaces\/([^/]+)$/);
+		if (settingsNamespaceRoute !== null && method === "PATCH") {
+			this.options.auth.requireScope(principal, "settings.write");
+			const ns = decodePathSegment(settingsNamespaceRoute[1]);
+			const body = await readJson(req, 256e3);
+			const record = typeof body === "object" && body !== null ? body : {};
+			const ops = parseSettingsNamespaceOps(record.ops);
+			const entry = await this.options.settings.mutateNamespace(ns, ops, settingsExpectedRevision(record.expectedRevision));
+			this.audit(principal, "settings.namespace.mutate", void 0, void 0, requestId, {
+				ns,
+				fields: settingsNamespaceOpFields(ops),
+				credentialChanged: settingsNamespaceCredentialChanged(ops, entry.secrets)
+			});
+			sendJson(res, 200, entry);
+			return;
+		}
 		if (method === "GET" && pathname === "/api/v1/settings/plugins") {
 			this.options.auth.requireScope(principal, "settings.read");
 			const inventory = await readPluginInventory();
@@ -7049,6 +7416,12 @@ var ApiRouter = class {
 			sendJson(res, 200, { items: this.options.database.listDevices() });
 			return;
 		}
+		if (method === "POST" && pathname === "/manage/devices/prune") {
+			const raw = (await readJson(req, 64e3)).olderThanDays;
+			if (typeof raw !== "number" || !Number.isFinite(raw) || !Number.isInteger(raw) || raw < 1 || raw > 3650) throw new ApiError(400, "INVALID_OLDER_THAN_DAYS", "olderThanDays must be an integer between 1 and 3650.");
+			sendJson(res, 200, { pruned: this.options.database.pruneInactiveDevices(raw, { requestId }) });
+			return;
+		}
 		const deviceRoute = pathname.match(/^\/manage\/devices\/([^/]+)$/);
 		if (deviceRoute !== null && method === "PATCH") {
 			const body = await readJson(req, 64e3);
@@ -7130,44 +7503,9 @@ var ApiRouter = class {
 		}
 		if (this.options.tunnels !== void 0 && method === "POST" && pathname === "/manage/cloudflare/create") {
 			const createBody = await readJson(req, 64e3).catch(() => ({}));
-			const wantConfig = createBody.configText === true;
-			const binDir = this.options.cloudflaredBinDir;
-			let exe;
-			try {
-				exe = await ensureCloudflared(binDir ?? this.options.database.dataDir, (a) => {
-					this.options.tunnels.reportActivity(a);
-				});
-			} catch (cause) {
-				this.options.tunnels.clearActivity();
-				throw new ApiError(502, "TUNNEL_DOWNLOAD_FAILED", "Failed to download or unpack cloudflared. Check the network and retry, or set CLOUDFLARED_MIRROR.", {
-					errorKey: "tunnelErrorDownload",
-					...cause instanceof Error ? { reason: sanitizeDownloadError(cause.message) } : {}
-				});
-			}
-			const port = this.options.remote.status().configuredPort ?? 3090;
-			const state = await this.options.tunnels.startQuick(exe, port);
-			let configText;
-			let resolvedUrl = state.url;
-			if (wantConfig) {
-				const tunnelUrl = state.url ?? await this.options.tunnels.waitForUrl();
-				resolvedUrl = tunnelUrl;
-				if (tunnelUrl !== null) configText = this.buildConfigText({
-					endpoints: [{
-						label: readOptionalText(createBody.endpointLabel) ?? "云隧道",
-						baseUrl: tunnelUrl
-					}],
-					...createBody.rootIds === void 0 ? {} : { rootIds: createBody.rootIds },
-					...createBody.deviceName === void 0 ? {} : { deviceName: createBody.deviceName }
-				}, requestId);
-			}
-			this.options.tunnels.clearActivity();
-			this.options.database.audit("admin", "loopback-admin", "cloudflare.create", void 0, void 0, {}, requestId);
-			const responseState = resolvedUrl === state.url ? state : {
+			const { state, configText } = await this.createTunnel(createBody, requestId, "loopback-admin");
+			sendJson(res, 201, configText === void 0 ? state : {
 				...state,
-				url: resolvedUrl
-			};
-			sendJson(res, 201, configText === void 0 ? responseState : {
-				...responseState,
 				configText
 			});
 			return;
@@ -7181,6 +7519,99 @@ var ApiRouter = class {
 		throw new ApiError(404, "ROUTE_NOT_FOUND", "The requested management route does not exist.");
 	}
 	/**
+	* 打开隧道并（可选）顺带产出配置文本 —— HTTP `POST /manage/cloudflare/create` 与
+	* IM `/tunnel` 命令**共用**这一条实现。
+	*
+	* 抽出来的原因：两条入口的前半段完全一致（确保 cloudflared → startQuick → 等随机域名 →
+	* 建配置文本），差别只在「谁在调用」——HTTP 侧要先把请求体读干净（流会随时间关闭），
+	* 命令侧没有请求体。复制一份会让「一键出令牌」在两条路径上慢慢漂移。
+	*
+	* @param createBody - 已解析的请求体（HTTP 侧）或 `{ configText: true }`（命令侧）。
+	* @param requestId - 审计与配对记录共用的请求 ID。
+	* @param actorLabel - 审计里的操作者标签：`loopback-admin`（本机管理面）或 `im-command`。
+	* @returns 合并了「等到地址」的 state，以及（wantConfig 且拿到地址时）配置文本。
+	*/
+	async createTunnel(createBody, requestId, actorLabel) {
+		const wantConfig = createBody.configText === true;
+		const binDir = this.options.cloudflaredBinDir;
+		let exe;
+		try {
+			exe = await ensureCloudflared(binDir ?? this.options.database.dataDir, (a) => {
+				this.options.tunnels.reportActivity(a);
+			});
+		} catch (cause) {
+			this.options.tunnels.clearActivity();
+			throw new ApiError(502, "TUNNEL_DOWNLOAD_FAILED", "Failed to download or unpack cloudflared. Check the network and retry, or set CLOUDFLARED_MIRROR.", {
+				errorKey: "tunnelErrorDownload",
+				...cause instanceof Error ? { reason: sanitizeDownloadError(cause.message) } : {}
+			});
+		}
+		const port = this.options.remote.status().configuredPort ?? 3090;
+		const state = await this.options.tunnels.startQuick(exe, port);
+		let configText;
+		let resolvedUrl = state.url;
+		if (wantConfig) {
+			const tunnelUrl = state.url ?? await this.options.tunnels.waitForUrl();
+			resolvedUrl = tunnelUrl;
+			if (tunnelUrl !== null) configText = this.buildConfigText({
+				endpoints: [{
+					label: readOptionalText(createBody.endpointLabel) ?? "云隧道",
+					baseUrl: tunnelUrl
+				}],
+				...createBody.rootIds === void 0 ? {} : { rootIds: createBody.rootIds },
+				...createBody.deviceName === void 0 ? {} : { deviceName: createBody.deviceName }
+			}, requestId);
+		}
+		this.options.tunnels.clearActivity();
+		this.options.database.audit("admin", actorLabel, "cloudflare.create", void 0, void 0, {}, requestId);
+		return {
+			state: resolvedUrl === state.url ? state : {
+				...state,
+				url: resolvedUrl
+			},
+			...configText === void 0 ? {} : { configText }
+		};
+	}
+	/**
+	* IM `/tunnel` 命令的宿主侧入口：开隧道并返回一行可粘贴的配置文本。
+	*
+	* 与 HTTP 路径的两点差别：
+	*
+	* 1. **隧道已在运行时直接复用当前地址**，不重复 spawn（第二次 `startQuick` 会撞
+	*    `TUNNEL_ALREADY_RUNNING`，而用户在 IM 里连发两条是很常见的）。
+	* 2. 配置文本的 endpoint 只用隧道地址，设备名缺省由 `buildConfigText` 决定 —— 命令
+	*    不接受参数，所以没有 `endpointLabel` / `rootIds` 的透传面。
+	*
+	* @throws 当 12 秒内没拿到公网地址，或 cloudflared 下载失败时。
+	*/
+	async openTunnelForCommand() {
+		const tunnels = this.options.tunnels;
+		if (tunnels === void 0) throw new Error("隧道功能未启用。");
+		const requestId = randomUUID();
+		const current = tunnels.publicState;
+		if (current.running === true && current.url !== null) {
+			const reused = this.buildConfigText({ endpoints: [{
+				label: "云隧道",
+				baseUrl: current.url
+			}] }, requestId);
+			this.options.database.audit("admin", "im-command", "cloudflare.create", void 0, void 0, { reused: true }, requestId);
+			return {
+				url: current.url,
+				text: reused.text,
+				deviceName: reused.deviceName
+			};
+		}
+		const { state, configText } = await this.createTunnel({ configText: true }, requestId, "im-command");
+		if (configText === void 0 || state.url === null) throw new Error("隧道已启动，但 12 秒内没拿到公网地址。稍等片刻再发一次 /tunnel 可复用当前地址。");
+		const text = typeof configText.text === "string" ? configText.text : "";
+		const deviceName = typeof configText.deviceName === "string" ? configText.deviceName : "Android 设备";
+		return {
+			url: state.url,
+			text,
+			deviceName
+		};
+	}
+	/**
 	* 隧道状态视图。
 	*
 	* **这里不做脱敏，因为用不上**：判据 1 已经把 Cloudflare 边缘头（`Cf-Connecting-IP` /
@@ -7572,6 +8003,17 @@ function optionalInteger(value) {
 	if (!Number.isSafeInteger(parsed) || parsed < 0) throw new ApiError(400, "NUMBER_INVALID", "A query parameter must be a non-negative integer.");
 	return parsed;
 }
+/**
+* 请求体里的 `expectedRevision`。
+*
+* 不复用 `optionalInteger()`：它读的是查询串（字符串）且错误码是 `NUMBER_INVALID`；
+* 这里是 JSON 数字，非法时属于「ops 请求体不合法」，契约要求 `SETTINGS_OPS_INVALID`。
+*/
+function settingsExpectedRevision(value) {
+	if (value === void 0) return void 0;
+	if (!Number.isSafeInteger(value) || value < 0) throw new ApiError(400, "SETTINGS_OPS_INVALID", "expectedRevision must be a non-negative integer.");
+	return value;
+}
 function commandName(line) {
 	return /^\/([a-z][a-z0-9_-]*)/u.exec(line)?.[1] ?? "unknown";
 }
@@ -8407,8 +8849,71 @@ const PROVIDER_CONTEXT_TTL_MS = 1e3;
 const PROVIDER_CONTEXT_CACHE_LIMIT = 128;
 var DshSettingsAdapter = class {
 	api;
-	constructor(api) {
+	options;
+	/**
+	* @param options.writeNamespaces 额外允许手机端写入的设置命名空间（精确 ns 或
+	*   `前缀*`），与内置策略（`ui-*` / 以 `locale` 结尾）叠加；默认为空。
+	*/
+	constructor(api, options = {}) {
 		this.api = api;
+		this.options = options;
+	}
+	/**
+	* 列出全部设置命名空间（通用设置面的读侧）。
+	*
+	* 与 `listProviders()` 的区别：它不理解任何 provider 语义，原样透出内核按插件
+	* 划分的命名空间，由手机端按 `schema` 自己长表单 —— 新装插件不必等 App 发版。
+	*/
+	async describeNamespaces() {
+		const described = unwrapDsh(await this.settingsService().describe({
+			rpcId: randomUUID(),
+			payload: {}
+		}));
+		return {
+			writable: described.writable,
+			namespaces: described.namespaces.map((view) => projectSettingsNamespace(view, described.writable, this.writeNamespaces))
+		};
+	}
+	/**
+	* 按路径改一个命名空间（通用设置面的写侧）。
+	*
+	* 校验顺序是刻意的：ns 策略 → ops 结构 → 内核 describe（host 可写性）→ mutate。
+	* 先验策略既省一次内核往返，也保证「高危命名空间」无论 ops 怎么错都先得到 403。
+	*/
+	async mutateNamespace(ns, ops, expectedRevision) {
+		if (!isSettingsNamespaceWriteAllowed(ns, this.writeNamespaces)) throw new ApiError(403, "SETTINGS_NAMESPACE_READONLY", `The settings namespace "${ns}" is not writable from this bridge.`, {
+			ns,
+			reason: "HIGH_RISK_NAMESPACE"
+		});
+		const normalized = parseSettingsNamespaceOps(ops);
+		const described = unwrapDsh(await this.settingsService().describe({
+			rpcId: randomUUID(),
+			payload: {}
+		}));
+		if (!described.writable) throw new ApiError(409, "SETTINGS_READ_ONLY", "DSH settings are read-only.");
+		let mutated;
+		try {
+			mutated = unwrapDsh(await this.settingsService().mutate({
+				rpcId: randomUUID(),
+				payload: {
+					ns,
+					ops: normalized,
+					...expectedRevision === void 0 ? {} : { expectedRevision }
+				}
+			}));
+		} catch (error) {
+			throw mapSettingsMutationError(error);
+		}
+		return projectSettingsNamespace(mutated, described.writable, this.writeNamespaces);
+	}
+	get writeNamespaces() {
+		return this.options.writeNamespaces ?? [];
+	}
+	/** 内核 settings 服务缺失时给 503（而不是把 `TypeError` 漏成 500）。 */
+	settingsService() {
+		const settings = this.api.settings;
+		if (settings === void 0) throw new ApiError(503, "SETTINGS_UNAVAILABLE", "The DSH settings service is not available.");
+		return settings;
 	}
 	async listProviders() {
 		const [directoryResponse, settingsResponse, catalogResponse] = await Promise.all([
@@ -8699,6 +9204,20 @@ var DshSettingsAdapter = class {
 		};
 	}
 };
+/**
+* 把内核 `settings.mutate` 的错误翻成契约错误码。
+*
+* `unwrapDsh()` 的通用映射只认 `busy` / `locked` 为 409，所以内核的
+* `settings/conflict` 会落到 400 `DSH_SETTINGS_CONFLICT` —— 这里按契约改回
+* 409 `SETTINGS_CONFLICT`（客户端据此提示「刷新后重试」而不是「参数不对」）。
+* `settings/rejected` 是 ops 在 schema 上不合法，落回 400 `SETTINGS_OPS_INVALID`。
+*/
+function mapSettingsMutationError(error) {
+	if (!(error instanceof ApiError)) return error;
+	if (error.code.includes("SETTINGS") && error.code.includes("CONFLICT")) return new ApiError(409, "SETTINGS_CONFLICT", "Settings changed since they were read; refresh and retry.", error.details);
+	if (error.code.includes("SETTINGS") && error.code.includes("REJECTED")) return new ApiError(400, "SETTINGS_OPS_INVALID", error.message, error.details);
+	return error;
+}
 function projectConfig(profile, inheritedModels) {
 	const baseURL = text(profile?.baseURL);
 	const api = text(profile?.api);
@@ -8857,7 +9376,7 @@ async function apply(ctx, config = {}) {
 		agents: ctx.agents,
 		commands: ctx.commands
 	});
-	const settings = new DshSettingsAdapter(apiProxy);
+	const settings = new DshSettingsAdapter(apiProxy, { writeNamespaces: config.settingsWriteNamespaces ?? [] });
 	let hostServiceReport;
 	try {
 		hostServiceReport = probeHostServices(ctx, PLUGIN_VERSION);
@@ -8908,6 +9427,34 @@ async function apply(ctx, config = {}) {
 		path: IMAGE_ROUTE,
 		handler: imageRoute
 	}]);
+	try {
+		ctx.effect(() => registerTunnelCommand(ctx.commands, {
+			openTunnel: () => router.openTunnelForCommand(),
+			logger: {
+				info: (message) => ctx.logger.info(message),
+				warn: (error) => ctx.logger.warn(error)
+			}
+		}), "dsh-remote-bridge /tunnel command");
+	} catch (error) {
+		ctx.logger.warn(/* @__PURE__ */ new Error(`dsh-remote-bridge: /tunnel command registration failed (ignored): ${String(error)}`));
+	}
+	let toolsService;
+	try {
+		toolsService = reflect?.get?.("tools", false);
+	} catch {
+		toolsService = void 0;
+	}
+	if (toolsService !== void 0) try {
+		ctx.effect(() => registerTunnelTool(toolsService, {
+			openTunnel: () => router.openTunnelForCommand(),
+			logger: {
+				info: (message) => ctx.logger.info(message),
+				warn: (error) => ctx.logger.warn(error)
+			}
+		}), "dsh-remote-bridge open_tunnel_config tool");
+	} catch (error) {
+		ctx.logger.warn(/* @__PURE__ */ new Error(`dsh-remote-bridge: open_tunnel_config registration failed (ignored): ${String(error)}`));
+	}
 	ctx.effect(() => async () => {
 		disposeEmbedded();
 		await remote.stop();