dsh-qqbot 1.0.0 → 1.0.1

package/README.md

@@ -7,26 +7,40 @@ QQ 官方机器人插件，作为 DeepSeek Harness 的**树外插件**维护（
 
 ## 安装
 
-构建，然后装进你运行的 profile：
+从 npm 装进你运行的 profile（无需本地构建）：
 
 ```sh
-pnpm install
-pnpm run build
-pnpm dsh plugin --profile <name> add -w link:E:/Project/dsh-plugins/dsh-qqbot
+dsh plugin --profile <name> add -w dsh-qqbot        # 最新版
+dsh plugin --profile <name> add -w dsh-qqbot@1.0.0  # 或固定版本
 ```
 
-或者手动进入 profile 目录执行等价的 pnpm 命令：
+等价的手动方式（进入 profile 目录执行 pnpm）：
 
 ```sh
 cd "$env:DSH_HOME/profiles/<name>"   # DSH_HOME 未设置时是 ~/.dsh/profiles/<name>
-pnpm add -w link:E:/Project/dsh-plugins/dsh-qqbot
+pnpm add -w dsh-qqbot
 ```
 
 注意：
 
 - **必须带 `-w`**：profile 目录自带 `pnpm-workspace.yaml`，不带 `-w` 时 pnpm 报 `ERR_PNPM_ADDING_TO_ROOT` 直接失败。
-- **用 `link:` 而不是裸路径**：裸路径是 `file:` 语义（快照副本），改源码不生效；`link:` 直接指向源码目录，重新 `pnpm run build` 后即时生效，无需重新 add。
 - 本包没有 `dsh.bundle` 声明，不会进入 profile 的 bundles 层，这符合预期——由下面的 patch 行按包名挂载；client 半由 `dsh.client` 扫描同一条挂载行自动进浏览器。
+- 升级到新版本：重新 `add` 一次新版本号，然后重启 dsh。registry 版是安装时的快照（不再指向源码目录），改本地源码不影响它。
+
+### 本地开发（link 到源码）
+
+改插件源码时用 `link:` 直接指向源码目录：
+
+```sh
+cd E:\Project\dsh-plugins\dsh-qqbot
+pnpm install
+pnpm run build
+dsh plugin --profile <name> add -w link:E:/Project/dsh-plugins/dsh-qqbot
+```
+
+- **用 `link:` 而不是裸路径**：裸路径是 `file:` 语义（快照副本），改源码不生效；`link:` 直接指向源码目录，重新 `pnpm run build` 后即时生效，无需重新 add。
+- 改完发布版后切回本地版用同一条 `link:` 命令（`pnpm add` 会把依赖 spec 从 registry 改写成 link）。
+- 反之，切回发布版：`dsh plugin --profile <name> add -w dsh-qqbot@<版本>`。
 
 在 **profile 自己的** `cordis.patch.yml`（`$DSH_HOME/profiles/<name>/cordis.patch.yml`）挂载（凭据在设置界面填写，不再写在这里）：
 
@@ -44,13 +58,14 @@ pnpm add -w link:E:/Project/dsh-plugins/dsh-qqbot
 
 | 字段 | 说明 |
 | --- | --- |
-| AppID | QQ 开放平台机器人应用的 AppID。 |
-| AppSecret | **写穿不回显**：保存后输入框留空表示「保持现有密钥」；页面显示「已配置」，可用「清除密钥」移除。 |
-| 使用沙箱环境 | 勾选后走沙箱网关（`sandbox.api.sgroup.qq.com`），用于开发调试。 |
+| AppID | QQ 开放平台机器人应用的 AppID。**写穿不回显**：页面只显示「已配置/未配置」状态，输入框填写新值以覆盖；「清除 AppID」可移除。 |
+| AppSecret | **写穿不回显**：页面只显示「已配置/未配置」，留空表示保持现有密钥；「清除密钥」可移除。 |
+
+点击「保存」后**立即生效**：host 半按需从 credential 服务读取（`credentials/updated` 提交即触发），已连接的网关会用新身份自动重连，凭据被清空则自动断开。
 
-点击「保存」后**立即生效**：host 半通过 settings 服务热读取（`settings/updated` 提交即触发），已连接的网关会用新身份自动重连，凭据被清空则自动断开。
+存储位置：`$DSH_HOME/.credentials.yaml`（明文，等价于环境变量；由 harness 的 credential 服务管理）。页面写入的引用名是 **`QQBOT_CRED_APP_ID` / `QQBOT_CRED_APP_SECRET`**——故意与 `QQBOT_APP_ID`/`QQBOT_APP_SECRET` 环境变量不同名：credential 服务的环境层会遮蔽同名引用并使其只读，shell 里一旦导出过 `QQBOT_APP_ID`，页面就会永远变灰，因此设置页用自己的引用名，UI 写入永远优先于环境变量。之所以走 credential 服务而不是 settings 命名空间：harness 的 settings wire 面只服务硬编码的命名空间白名单（`agent-loop`、`shell` 等），树外插件注册的命名空间不会被暴露；credential 面接受任意引用名，无需改 harness。
 
-存储位置：`$DSH_HOME/settings.yaml` 的 `qqbot:` 段（明文，等价于环境变量）。配置解析顺序：**settings 用户层 → cordis.yml 行的 config 基础层 → 环境变量 `QQBOT_APP_ID` / `QQBOT_APP_SECRET`**（无头环境可用环境变量兜底）。三处都没有时插件照常挂载，`/qqbot on` 会报错并指向设置页。
+配置解析顺序：**credential 库（设置页写入）→ `settings.yaml` 的 `qqbot:` 段 → cordis.yml 行的 config 基础层 → 环境变量 `QQBOT_APP_ID` / `QQBOT_APP_SECRET`**（无头环境可用环境变量兜底）。**沙箱开关**不在此页：仅在 cordis.yml 的 `config.sandbox: true` 里配置。四处都没有 AppID/AppSecret 时插件照常挂载，`/qqbot on` 会报错并指向设置页。
 
 ## 测试
 
@@ -58,7 +73,7 @@ pnpm add -w link:E:/Project/dsh-plugins/dsh-qqbot
 pnpm test
 ```
 
-host 的 `protocol` / `gateway` / `qqbot` / `settings-controller` 四套用例可直接跑（57 例，settings-controller 通过 `vi.mock` 替换 runtime 客户端模块以绕过浏览器 bundle）。`tests/*.client.spec.ts(x)` 被 vitest 排除：它们 import `@deepseek-ai/dsh-client-runtime/client`，而 registry 上发布的是浏览器 bundle（`lib/client.js`，import 时执行 `window.__ModuleLoader__.load(...)`），node/jsdom 无法加载。这些用例在 harness 源码树内开发期已验证，客户端开关与设置页的验证走浏览器手动确认（见「使用」）。
+host 的 `protocol` / `gateway` / `qqbot` / `settings-controller` 四套用例可直接跑（59 例，settings-controller 通过 `vi.mock` 替换 runtime 客户端模块以绕过浏览器 bundle）。`tests/*.client.spec.ts(x)` 被 vitest 排除：它们 import `@deepseek-ai/dsh-client-runtime/client`，而 registry 上发布的是浏览器 bundle（`lib/client.js`，import 时执行 `window.__ModuleLoader__.load(...)`），node/jsdom 无法加载。这些用例在 harness 源码树内开发期已验证，客户端开关与设置页的验证走浏览器手动确认（见「使用」）。
 
 ## 使用
 
@@ -70,16 +85,18 @@ host 的 `protocol` / `gateway` / `qqbot` / `settings-controller` 四套用例
 
 ## peer 依赖解析
 
-`link:` 安装的 symlink 目标在 harness 之外，Node 从真实路径（realpath）向上解析依赖，所以 `@deepseek-ai/cordis`、`dsh-*` Service Definition 这些 peer 命中 **dsh-qqbot 项目自己的 `node_modules`**（`pnpm install` 装的最新 registry 版），不是 profile 的 `node_modules` 或 `$DSH_HOME/profiles/node_modules` 回退。这带来两个后果：
+两种安装方式的依赖解析不同：
 
-- 插件与 harness 各持一份 `@deepseek-ai/cordis`（双实例）。当前启动与挂载正常，但若插件代码对 `ctx` 做跨实例判断（`instanceof` 等）会失效。
-- peer 版本按 `^` 取最新（例如 `dsh-session@0.1.0-rc.6`），可能比正在运行的 harness（rc.5）新。运行时服务走 harness 注入的 ctx，一般兼容；harness 升级或插件用到新 API 时需对齐 peer 版本。
+- **registry 版（推荐）**：包从 profile 的 `node_modules` 向上解析 peer（`@deepseek-ai/cordis`、`dsh-*` Service Definition 等），与 harness 及 profile 的 `$DSH_HOME/profiles/node_modules` 回退**共享同一份实例**，没有双实例问题。
+- **`link:` 开发版**：symlink 目标在 harness 之外，Node 从真实路径（realpath）向上解析，peer 命中 **dsh-qqbot 项目自己的 `node_modules`**（`pnpm install` 装的最新 registry 版）。这带来两个后果：
+  - 插件与 harness 各持一份 `@deepseek-ai/cordis`（双实例）。当前启动与挂载正常，但若插件代码对 `ctx` 做跨实例判断（`instanceof` 等）会失效。
+  - peer 版本按 `^` 取最新（例如 `dsh-session@0.1.0-rc.6`），可能比正在运行的 harness（rc.5）新。运行时服务走 harness 注入的 ctx，一般兼容；harness 升级或插件用到新 API 时需对齐 peer 版本。
 
 ## 版本耦合说明
 
 client 半的浏览器 bundle 必须用 harness 的客户端加载协议构建：`tsdown.config.ts` 里硬编码了 `PLATFORM_MODULES`（模块表 external 列表，含 `@deepseek-ai/dsh-client-runtime/client` 的 store 豁免）和 `__ModuleLoader__.load({ id })` 的包名 id。如果 harness 更新了这份平台模块列表或 `__ModuleLoader__` 协议，需要同步更新 `tsdown.config.ts`，否则浏览器端加载会失败。
 
-设置页依赖 harness 的 settings 能力（host 的 `settings` 服务 + `settings.section` 槽位 + `api.settings` wire 面），这些都在 web 基础组合里，无需额外挂载行；如果换成自定义 profile，需保证 `@deepseek-ai/dsh-settings-file` 与 `@deepseek-ai/dsh-client-ui-settings(-general)` 在场。
+设置页依赖 harness 的：credential 能力（host 的 `credentials` 服务 + `api.credentials` wire 面，由 base 组合的 `@deepseek-ai/dsh-credentials-local` 提供）和 settings 面板（`settings.section` 槽位 + settings 服务，用于 `qqbot:` 段的 base 层解析），这些都在 web 基础组合里，无需额外挂载行；如果换成自定义 profile，需保证上述行在场。
 
 ## 发布
 

package/lib/client.js

@@ -8,54 +8,47 @@ window.__ModuleLoader__.load({
 		let react = require("react");
 		let react_jsx_runtime = require("react/jsx-runtime");
 		//#region src/client/settings-controller.ts
-		/** The settings namespace the Host plugin registers its identity under. */
-		const QQBOT_SETTINGS_NAMESPACE = "qqbot";
+		/**
+		* Credential reference holding the robot application id. Deliberately NOT the
+		* environment-variable name: the credential store's env layer shadows a
+		* same-named ref and makes it read-only, which would disable the settings
+		* page wherever `QQBOT_APP_ID` is exported.
+		*/
+		const QQBOT_APP_ID_REF = "QQBOT_CRED_APP_ID";
+		/**
+		* Credential reference holding the robot application secret; distinct from
+		* `QQBOT_APP_SECRET` for the same shadowing reason.
+		*/
+		const QQBOT_APP_SECRET_REF = "QQBOT_CRED_APP_SECRET";
 		/** Human text for a rejected wire call or transport failure. */
 		function messageOf(error) {
 			return error instanceof Error ? error.message : String(error);
 		}
-		/** Read the redacted resolved AppID, defaulting absent values to ''. */
-		function appIdIn(view) {
-			if (typeof view.value !== "object" || view.value === null) return "";
-			const value = view.value["appId"];
-			return typeof value === "string" ? value : "";
-		}
-		/** Read the redacted resolved sandbox flag, defaulting to false. */
-		function sandboxIn(view) {
-			if (typeof view.value !== "object" || view.value === null) return false;
-			return view.value["sandbox"] === true;
-		}
-		/** Whether the redacted view reports a stored AppSecret. */
-		function secretSetIn(view) {
-			return view.secrets.some((secret) => secret.path.length === 1 && secret.path[0] === "appSecret" && secret.set);
-		}
 		/**
-		* Serializes the qqbot namespace's Host reads and writes behind one snapshot
-		* store. Latest load wins; a refused save reloads the namespace so the form
-		* re-renders from the fresh view and the user can re-apply the edit.
+		* Serializes the two credential references' Host reads and writes behind one
+		* snapshot store. Latest load wins; a refused save reloads the views so the
+		* form re-renders from the fresh state and the user can re-apply the edit.
 		*/
 		var QqbotSettingsController = class {
 			api;
 			/** uSES-safe state source the section renders through its hooks compartment. */
 			store = (0, _deepseek_ai_dsh_client_runtime_client.createSnapshotStore)({
 				status: "idle",
-				appId: "",
-				sandbox: false,
+				appIdSet: false,
 				secretSet: false,
 				writable: false,
-				revision: void 0,
 				error: null
 			});
 			generation = 0;
 			/**
-			* @param api - the settings wire face.
+			* @param api - the credentials wire face.
 			*/
 			constructor(api) {
 				this.api = api;
 			}
 			/**
-			* Refresh the snapshot from `settings.describe`; a failure keeps the last
-			* good state and surfaces the error.
+			* Refresh the snapshot from `credentials.describe`; a failure keeps the
+			* last good state and surfaces the error.
 			* @returns settlement after the read.
 			*/
 			async load() {
@@ -65,12 +58,20 @@ window.__ModuleLoader__.load({
 					state.error = null;
 				});
 				try {
-					const response = await this.api.settings.describe({});
+					const response = await this.api.credentials.describe({ refs: [QQBOT_APP_ID_REF, QQBOT_APP_SECRET_REF] });
 					if (!response.result.ok) throw new Error(response.result.error.message);
-					const view = response.result.value.namespaces.find((candidate) => candidate.ns === QQBOT_SETTINGS_NAMESPACE);
-					if (view === void 0) throw new Error(`settings namespace "${QQBOT_SETTINGS_NAMESPACE}" is not registered`);
+					const views = response.result.value.credentials;
+					const appIdView = views[QQBOT_APP_ID_REF];
+					const secretView = views[QQBOT_APP_SECRET_REF];
+					if (appIdView === void 0 || secretView === void 0) throw new Error("credentials domain did not answer the qqbot references");
 					if (generation !== this.generation) return;
-					this.accept(view, response.result.value.writable);
+					this.store.update((state) => {
+						state.status = "ready";
+						state.appIdSet = appIdView.configured;
+						state.secretSet = secretView.configured;
+						state.writable = appIdView.writable && secretView.writable;
+						state.error = null;
+					});
 				} catch (error) {
 					if (generation !== this.generation) return;
 					this.store.update((state) => {
@@ -80,67 +81,41 @@ window.__ModuleLoader__.load({
 				}
 			}
 			/**
-			* Apply one user edit as ordered path ops; a refusal reloads the namespace
-			* and returns its message.
+			* Apply one user edit as ordered credential writes, stopping at the first
+			* refusal; a refusal reloads the views and returns its message.
 			* @param patch - the fields the user changed.
 			* @returns null on success; the Host's failure text otherwise.
 			*/
 			async save(patch) {
-				const ops = [];
-				if (patch.appId !== void 0) ops.push(patch.appId.length === 0 ? {
-					op: "unset",
-					path: ["appId"]
-				} : {
-					op: "set",
-					path: ["appId"],
-					value: patch.appId
-				});
-				if (patch.sandbox !== void 0) ops.push({
-					op: "set",
-					path: ["sandbox"],
-					value: patch.sandbox
-				});
-				if (patch.clearSecret === true) ops.push({
-					op: "unset",
-					path: ["appSecret"]
-				});
-				if (patch.appSecret !== void 0 && patch.appSecret.length > 0) ops.push({
-					op: "set",
-					path: ["appSecret"],
-					value: patch.appSecret
-				});
-				if (ops.length === 0) return null;
-				const revision = this.store.getSnapshot().revision;
-				let response;
+				const writes = [];
+				if (patch.clearAppId === true) writes.push(() => this.api.credentials.unset({ ref: QQBOT_APP_ID_REF }));
+				const appId = patch.appId;
+				if (appId !== void 0 && appId.length > 0) writes.push(() => this.api.credentials.set({
+					ref: QQBOT_APP_ID_REF,
+					value: appId
+				}));
+				if (patch.clearSecret === true) writes.push(() => this.api.credentials.unset({ ref: QQBOT_APP_SECRET_REF }));
+				const appSecret = patch.appSecret;
+				if (appSecret !== void 0 && appSecret.length > 0) writes.push(() => this.api.credentials.set({
+					ref: QQBOT_APP_SECRET_REF,
+					value: appSecret
+				}));
+				if (writes.length === 0) return null;
 				try {
-					response = await this.api.settings.mutate({
-						ns: QQBOT_SETTINGS_NAMESPACE,
-						ops,
-						...revision === void 0 ? {} : { expectedRevision: revision }
-					});
+					for (const write of writes) {
+						const response = await write();
+						if (!response.result.ok) {
+							await this.load();
+							return response.result.error.message;
+						}
+					}
 				} catch (error) {
 					await this.load();
 					return messageOf(error);
 				}
-				if (!response.result.ok) {
-					await this.load();
-					return response.result.error.message;
-				}
-				this.accept(response.result.value, this.store.getSnapshot().writable);
+				await this.load();
 				return null;
 			}
-			/** Fold one redacted wire view into the snapshot. */
-			accept(view, writable) {
-				this.store.update((state) => {
-					state.status = "ready";
-					state.appId = appIdIn(view);
-					state.sandbox = sandboxIn(view);
-					state.secretSet = secretSetIn(view);
-					state.writable = writable;
-					state.revision = view.revision;
-					state.error = null;
-				});
-			}
 		};
 		/**
 		* Refresh only after the section left idle, so an unopened page never fetches
@@ -153,7 +128,7 @@ window.__ModuleLoader__.load({
 		}
 		//#endregion
 		//#region \0dsh-css:E:\Project\dsh-plugins\dsh-qqbot\src\client\QqbotSettingsSection.module.css.mjs
-		const css$1 = ".TV8fAG_section{flex-direction:column;gap:12px;width:100%;padding-bottom:8px;display:flex}.TV8fAG_title{color:var(--dsw-alias-label-primary);margin:0;font-size:16px;font-weight:600;line-height:24px}.TV8fAG_desc{color:var(--dsw-alias-label-secondary);margin:0;font-size:13px;line-height:20px}.TV8fAG_field{flex-direction:column;gap:6px;display:flex}.TV8fAG_fieldLabel{color:var(--dsw-alias-label-primary);font-size:13px;font-weight:500;line-height:20px}.TV8fAG_input{box-sizing:border-box;border:1px solid var(--dsw-alias-border-l2);width:100%;max-width:360px;height:32px;font:inherit;background:var(--dsw-alias-bg-layer-1);color:var(--dsw-alias-label-primary);border-radius:8px;padding:0 10px;font-size:14px;line-height:22px}.TV8fAG_input:focus{border-color:var(--dsw-alias-brand-primary);outline:none}.TV8fAG_input::placeholder{color:var(--dsw-alias-label-dimmed)}.TV8fAG_input:disabled{opacity:.6;cursor:default}.TV8fAG_fieldHint{color:var(--dsw-alias-label-dimmed);margin:0;font-size:12px;line-height:18px}.TV8fAG_secretRow{align-items:center;gap:8px;width:100%;max-width:360px;display:flex}.TV8fAG_secretRow .TV8fAG_input{flex:auto}.TV8fAG_clearButton{border:1px solid var(--dsw-alias-border-l2);height:28px;font:inherit;color:var(--dsw-alias-state-error-primary);cursor:pointer;background:0 0;border-radius:8px;flex:none;padding:0 10px;font-size:13px;line-height:18px}.TV8fAG_clearButton:hover:not(:disabled){background:var(--dsw-alias-interactive-bg-hover-danger)}.TV8fAG_clearButton:disabled{opacity:.6;cursor:default}.TV8fAG_fieldCheck{width:fit-content;color:var(--dsw-alias-label-primary);cursor:pointer;align-items:center;gap:8px;font-size:13px;line-height:20px;display:flex}.TV8fAG_fieldCheck input:disabled{cursor:default}.TV8fAG_actions{align-items:center;gap:12px;display:flex}.TV8fAG_saveButton{height:32px;font:inherit;background:var(--dsw-alias-brand-primary);color:var(--dsw-alias-brand-primary-invert);cursor:pointer;border:none;border-radius:8px;padding:0 16px;font-size:14px;font-weight:500;line-height:20px}.TV8fAG_saveButton:hover:not(:disabled){opacity:.9}.TV8fAG_saveButton:focus-visible{outline:2px solid var(--dsw-alias-brand-primary);outline-offset:2px}.TV8fAG_saveButton:disabled{opacity:.5;cursor:default}.TV8fAG_bound{color:var(--dsw-alias-state-warn-label);font-size:12px;line-height:18px}.TV8fAG_messageOk{color:var(--dsw-alias-label-secondary);margin:0;font-size:12px;line-height:18px}.TV8fAG_messageError{color:var(--dsw-alias-state-error-primary);margin:0;font-size:12px;line-height:18px}";
+		const css$1 = ".TV8fAG_section{flex-direction:column;gap:12px;width:100%;padding-bottom:8px;display:flex}.TV8fAG_title{color:var(--dsw-alias-label-primary);margin:0;font-size:16px;font-weight:600;line-height:24px}.TV8fAG_desc{color:var(--dsw-alias-label-secondary);margin:0;font-size:13px;line-height:20px}.TV8fAG_field{flex-direction:column;gap:6px;display:flex}.TV8fAG_fieldLabel{color:var(--dsw-alias-label-primary);align-items:center;gap:8px;font-size:13px;font-weight:500;line-height:20px;display:flex}.TV8fAG_chipSet{background:var(--dsw-alias-state-warn-tertiary);height:18px;color:var(--dsw-alias-state-warn-label);border-radius:999px;align-items:center;padding:0 6px;font-size:11px;font-weight:500;line-height:18px;display:inline-flex}.TV8fAG_chipUnset{background:var(--dsw-alias-bg-layer-1);height:18px;color:var(--dsw-alias-label-dimmed);border-radius:999px;align-items:center;padding:0 6px;font-size:11px;font-weight:500;line-height:18px;display:inline-flex}.TV8fAG_input{box-sizing:border-box;border:1px solid var(--dsw-alias-border-l2);width:100%;max-width:360px;height:32px;font:inherit;background:var(--dsw-alias-bg-layer-1);color:var(--dsw-alias-label-primary);border-radius:8px;padding:0 10px;font-size:14px;line-height:22px}.TV8fAG_input:focus{border-color:var(--dsw-alias-brand-primary);outline:none}.TV8fAG_input::placeholder{color:var(--dsw-alias-label-dimmed)}.TV8fAG_input:disabled{opacity:.6;cursor:default}.TV8fAG_fieldHint{color:var(--dsw-alias-label-dimmed);margin:0;font-size:12px;line-height:18px}.TV8fAG_secretRow{align-items:center;gap:8px;width:100%;max-width:360px;display:flex}.TV8fAG_secretRow .TV8fAG_input{flex:auto}.TV8fAG_clearButton{border:1px solid var(--dsw-alias-border-l2);height:28px;font:inherit;color:var(--dsw-alias-state-error-primary);cursor:pointer;background:0 0;border-radius:8px;flex:none;padding:0 10px;font-size:13px;line-height:18px}.TV8fAG_clearButton:hover:not(:disabled){background:var(--dsw-alias-interactive-bg-hover-danger)}.TV8fAG_clearButton:disabled{opacity:.6;cursor:default}.TV8fAG_actions{align-items:center;gap:12px;display:flex}.TV8fAG_saveButton{height:32px;font:inherit;background:var(--dsw-alias-button-primary-fill);color:var(--dsw-alias-label-primary-foreground);cursor:pointer;border:none;border-radius:8px;padding:0 16px;font-size:14px;font-weight:500;line-height:20px}.TV8fAG_saveButton:hover:not(:disabled){background:var(--dsw-alias-button-primary-hover)}.TV8fAG_saveButton:focus-visible{outline:2px solid var(--dsw-alias-brand-primary);outline-offset:2px}.TV8fAG_saveButton:disabled{opacity:.5;cursor:default}.TV8fAG_bound{color:var(--dsw-alias-state-warn-label);font-size:12px;line-height:18px}.TV8fAG_messageOk{color:var(--dsw-alias-label-secondary);margin:0;font-size:12px;line-height:18px}.TV8fAG_messageError{color:var(--dsw-alias-state-error-primary);margin:0;font-size:12px;line-height:18px}";
 		const tagId$1 = "dsh-qqbot/QqbotSettingsSection.module.css";
 		if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(tagId$1) + "]") === null) {
 			const tag = document.createElement("style");
@@ -163,67 +138,61 @@ window.__ModuleLoader__.load({
 			document.head.appendChild(tag);
 		}
 		var QqbotSettingsSection_module_css_default = {
-			"actions": "TV8fAG_actions",
-			"fieldLabel": "TV8fAG_fieldLabel",
+			"messageOk": "TV8fAG_messageOk",
 			"bound": "TV8fAG_bound",
-			"title": "TV8fAG_title",
-			"messageError": "TV8fAG_messageError",
-			"input": "TV8fAG_input",
-			"fieldCheck": "TV8fAG_fieldCheck",
-			"secretRow": "TV8fAG_secretRow",
-			"desc": "TV8fAG_desc",
 			"field": "TV8fAG_field",
+			"chipUnset": "TV8fAG_chipUnset",
+			"section": "TV8fAG_section",
+			"desc": "TV8fAG_desc",
+			"messageError": "TV8fAG_messageError",
+			"saveButton": "TV8fAG_saveButton",
 			"fieldHint": "TV8fAG_fieldHint",
 			"clearButton": "TV8fAG_clearButton",
-			"saveButton": "TV8fAG_saveButton",
-			"section": "TV8fAG_section",
-			"messageOk": "TV8fAG_messageOk"
+			"title": "TV8fAG_title",
+			"fieldLabel": "TV8fAG_fieldLabel",
+			"chipSet": "TV8fAG_chipSet",
+			"actions": "TV8fAG_actions",
+			"input": "TV8fAG_input",
+			"secretRow": "TV8fAG_secretRow"
 		};
 		//#endregion
 		//#region src/client/QqbotSettingsSection.tsx
 		/**
-		* The QQ Bot settings page: AppID, AppSecret, and sandbox fields over the
-		* Host's redacted namespace view. The AppSecret is write-only on the wire, so
-		* the field renders blank and "keep unchanged" is the empty-value meaning;
-		* the clear button removes a stored secret. Saving applies every changed
-		* field in one ordered write, and the Host restarts a live gateway in place.
+		* The QQ Bot settings page: AppID and AppSecret over the credential seam's
+		* value-free views. Both values are write-only on the wire — the page shows
+		* configured/not-configured chips and the inputs mean "enter a new value";
+		* an empty field keeps the stored one, and the clear buttons remove it.
+		* Saving applies every changed field in one ordered write, and the Host
+		* restarts a live gateway in place.
 		*/
 		function QqbotSettingsSection({ useQqbotSettings, useQqbotBound, save, t }) {
 			const snapshot = useQqbotSettings((state) => state);
 			const boundSessionId = useQqbotBound((state) => state.sessionId);
 			const [appId, setAppId] = (0, react.useState)("");
 			const [secret, setSecret] = (0, react.useState)("");
-			const [sandbox, setSandbox] = (0, react.useState)(false);
 			const [busy, setBusy] = (0, react.useState)(false);
 			const [message, setMessage] = (0, react.useState)(null);
-			const revision = snapshot.status === "ready" ? snapshot.revision : void 0;
-			(0, react.useEffect)(() => {
-				if (snapshot.status !== "ready") return;
-				setAppId(snapshot.appId);
-				setSecret("");
-				setSandbox(snapshot.sandbox);
-			}, [revision]);
 			const ready = snapshot.status === "ready";
-			const dirty = ready && (appId !== snapshot.appId || secret.length > 0 || sandbox !== snapshot.sandbox);
+			const dirty = ready && (appId.length > 0 || secret.length > 0);
 			const finish = (failure) => {
 				setBusy(false);
-				setMessage(failure === null ? {
-					kind: "ok",
-					text: t("save.ok")
-				} : {
+				if (failure === null) {
+					setAppId("");
+					setSecret("");
+					setMessage({
+						kind: "ok",
+						text: t("save.ok")
+					});
+				} else setMessage({
 					kind: "error",
 					text: failure
 				});
 			};
-			const onClickSave = () => {
-				if (busy || !ready || !snapshot.writable || !dirty) return;
+			const runSave = (patch) => {
+				if (busy || !ready || !snapshot.writable) return;
 				setBusy(true);
 				setMessage(null);
-				save({
-					appId,
-					...secret.length > 0 ? { appSecret: secret } : {},
-					sandbox
-				}).then(finish, (error) => {
+				save(patch).then(finish, (error) => {
 					setBusy(false);
 					setMessage({
 						kind: "error",
@@ -231,20 +200,25 @@ window.__ModuleLoader__.load({
 					});
 				});
 			};
+			const onClickSave = () => {
+				if (!dirty) return;
+				runSave({
+					...appId.length > 0 ? { appId } : {},
+					...secret.length > 0 ? { appSecret: secret } : {}
+				});
+			};
+			const onClickClearAppId = () => {
+				runSave({
+					...appId.length > 0 ? { appId } : {},
+					...secret.length > 0 ? { appSecret: secret } : {},
+					clearAppId: true
+				});
+			};
 			const onClickClearSecret = () => {
-				if (busy || !ready || !snapshot.writable) return;
-				setBusy(true);
-				setMessage(null);
-				save({
-					appId,
-					sandbox,
+				runSave({
+					...appId.length > 0 ? { appId } : {},
+					...secret.length > 0 ? { appSecret: secret } : {},
 					clearSecret: true
-				}).then(finish, (error) => {
-					setBusy(false);
-					setMessage({
-						kind: "error",
-						text: error instanceof Error ? error.message : String(error)
-					});
 				});
 			};
 			let statusLine = null;
@@ -265,20 +239,32 @@ window.__ModuleLoader__.load({
 					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("label", {
 						className: QqbotSettingsSection_module_css_default.field,
 						children: [
-							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+							/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
 								className: QqbotSettingsSection_module_css_default.fieldLabel,
-								children: t("appId.label")
+								children: [t("appId.label"), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+									className: snapshot.appIdSet ? QqbotSettingsSection_module_css_default.chipSet : QqbotSettingsSection_module_css_default.chipUnset,
+									children: snapshot.appIdSet ? t("chip.set") : t("chip.unset")
+								})]
 							}),
-							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
-								className: QqbotSettingsSection_module_css_default.input,
-								value: appId,
-								onChange: (event) => {
-									setAppId(event.target.value);
-								},
-								placeholder: t("appId.placeholder"),
-								autoComplete: "off",
-								spellCheck: false,
-								disabled: !ready || !snapshot.writable
+							/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+								className: QqbotSettingsSection_module_css_default.secretRow,
+								children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
+									className: QqbotSettingsSection_module_css_default.input,
+									value: appId,
+									onChange: (event) => {
+										setAppId(event.target.value);
+									},
+									placeholder: snapshot.appIdSet ? t("appId.placeholder.set") : t("appId.placeholder"),
+									autoComplete: "off",
+									spellCheck: false,
+									disabled: !ready || !snapshot.writable
+								}), snapshot.appIdSet ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+									type: "button",
+									className: QqbotSettingsSection_module_css_default.clearButton,
+									onClick: onClickClearAppId,
+									disabled: busy,
+									children: t("clear.appId")
+								}) : null]
 							}),
 							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
 								className: QqbotSettingsSection_module_css_default.fieldHint,
@@ -289,9 +275,12 @@ window.__ModuleLoader__.load({
 					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("label", {
 						className: QqbotSettingsSection_module_css_default.field,
 						children: [
-							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+							/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
 								className: QqbotSettingsSection_module_css_default.fieldLabel,
-								children: t("appSecret.label")
+								children: [t("appSecret.label"), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+									className: snapshot.secretSet ? QqbotSettingsSection_module_css_default.chipSet : QqbotSettingsSection_module_css_default.chipUnset,
+									children: snapshot.secretSet ? t("chip.set") : t("chip.unset")
+								})]
 							}),
 							/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 								className: QqbotSettingsSection_module_css_default.secretRow,
@@ -310,7 +299,7 @@ window.__ModuleLoader__.load({
 									className: QqbotSettingsSection_module_css_default.clearButton,
 									onClick: onClickClearSecret,
 									disabled: busy,
-									children: t("clear.label")
+									children: t("clear.secret")
 								}) : null]
 							}),
 							/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
@@ -319,21 +308,6 @@ window.__ModuleLoader__.load({
 							})
 						]
 					}),
-					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("label", {
-						className: QqbotSettingsSection_module_css_default.fieldCheck,
-						children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("input", {
-							type: "checkbox",
-							checked: sandbox,
-							onChange: (event) => {
-								setSandbox(event.target.checked);
-							},
-							disabled: !ready || !snapshot.writable
-						}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: t("sandbox.label") })]
-					}),
-					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
-						className: QqbotSettingsSection_module_css_default.fieldHint,
-						children: t("sandbox.hint")
-					}),
 					/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 						className: QqbotSettingsSection_module_css_default.actions,
 						children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
@@ -416,25 +390,27 @@ window.__ModuleLoader__.load({
 			"toggle.off.label": "连接 QQ",
 			"settings.nav": "QQ Bot",
 			"settings.title": "QQ 官方机器人",
-			"settings.desc": "填写 QQ 开放平台机器人应用的 AppID 与 AppSecret 后，在会话中使用 /qqbot on 或输入框的「连接 QQ」开关接入。配置保存后立即生效。",
+			"settings.desc": "填写 QQ 开放平台机器人应用的 AppID 与 AppSecret 后，在会话中使用 /qqbot on 或输入框的「连接 QQ」开关接入。两者保存后都不回显，页面仅显示配置状态；保存立即生效。",
+			"chip.set": "已配置",
+			"chip.unset": "未配置",
 			"appId.label": "AppID",
-			"appId.placeholder": "机器人的 AppID",
-			"appId.hint": "QQ 开放平台机器人应用的 AppID。",
+			"appId.placeholder": "输入新的 AppID",
+			"appId.placeholder.set": "已配置（不回显），输入以覆盖",
+			"appId.hint": "QQ 开放平台机器人应用的 AppID；留空表示保持现有值。",
+			"clear.appId": "清除 AppID",
 			"appSecret.label": "AppSecret",
 			"appSecret.placeholder": "输入新的 AppSecret",
-			"appSecret.placeholder.set": "已保存（不回显），输入以覆盖",
+			"appSecret.placeholder.set": "已配置（不回显），输入以覆盖",
 			"appSecret.hint": "保存后不回显；留空表示保持现有密钥。",
 			"appSecret.hint.set": "已配置 AppSecret；留空保存将保持不变，点击「清除密钥」可移除。",
-			"clear.label": "清除密钥",
-			"sandbox.label": "使用沙箱环境",
-			"sandbox.hint": "启用后连接沙箱网关（sandbox.api.sgroup.qq.com），用于开发调试。",
+			"clear.secret": "清除密钥",
 			"save.label": "保存",
 			"save.busy": "保存中…",
 			"save.ok": "已保存，立即生效。",
 			"bound.prefix": "已绑定会话：",
 			"status.loading": "正在读取配置…",
 			"status.error": "读取配置失败：",
-			"status.readonly": "设置存储为只读，无法修改。"
+			"status.readonly": "凭据被只读来源（如环境变量）遮蔽，无法在界面修改。"
 		};
 		/** English dictionary, checked complete against the zh key set. */
 		const en = {
@@ -446,25 +422,27 @@ window.__ModuleLoader__.load({
 			"toggle.off.label": "Connect QQ",
 			"settings.nav": "QQ Bot",
 			"settings.title": "QQ Official Bot",
-			"settings.desc": "Enter the AppID and AppSecret of your QQ open-platform bot application, then use /qqbot on or the \"Connect QQ\" toggle in a session. Saved changes apply immediately.",
+			"settings.desc": "Enter the AppID and AppSecret of your QQ open-platform bot application, then use /qqbot on or the \"Connect QQ\" toggle in a session. Both are write-only: the page shows only configured status. Saved changes apply immediately.",
+			"chip.set": "Configured",
+			"chip.unset": "Not configured",
 			"appId.label": "AppID",
-			"appId.placeholder": "Bot AppID",
-			"appId.hint": "The AppID of the bot application on the QQ open platform.",
+			"appId.placeholder": "Enter a new AppID",
+			"appId.placeholder.set": "Configured (not shown back), enter to replace",
+			"appId.hint": "The AppID of the bot application on the QQ open platform; leave empty to keep the stored value.",
+			"clear.appId": "Clear AppID",
 			"appSecret.label": "AppSecret",
 			"appSecret.placeholder": "Enter a new AppSecret",
-			"appSecret.placeholder.set": "Saved (not shown back), enter to replace",
+			"appSecret.placeholder.set": "Configured (not shown back), enter to replace",
 			"appSecret.hint": "Never shown back after saving; leave empty to keep the stored value.",
 			"appSecret.hint.set": "An AppSecret is configured; saving with an empty field keeps it. Use \"Clear secret\" to remove it.",
-			"clear.label": "Clear secret",
-			"sandbox.label": "Use the sandbox environment",
-			"sandbox.hint": "Route token, gateway, and sends through the sandbox host (sandbox.api.sgroup.qq.com) for development.",
+			"clear.secret": "Clear secret",
 			"save.label": "Save",
 			"save.busy": "Saving…",
 			"save.ok": "Saved, applied immediately.",
 			"bound.prefix": "Bound session: ",
 			"status.loading": "Loading configuration…",
 			"status.error": "Failed to load configuration: ",
-			"status.readonly": "Settings storage is read-only."
+			"status.readonly": "The credentials are shadowed by a read-only source (such as environment variables) and cannot be changed here."
 		};
 		//#endregion
 		//#region src/client/index.ts
@@ -520,8 +498,8 @@ window.__ModuleLoader__.load({
 			}, QqbotToggle));
 			const settings = new QqbotSettingsController(ctx.get("connection").api);
 			ctx.effect(() => {
-				const disposers = [ctx.remote.$on("settings/document-updated", (ns) => {
-					if (ns === "qqbot") refreshIfLoaded(settings);
+				const disposers = [ctx.remote.$on("credentials/updated", (ref) => {
+					if (ref === "QQBOT_CRED_APP_ID" || ref === "QQBOT_CRED_APP_SECRET") refreshIfLoaded(settings);
 				}), ctx.on("connection/reset", () => {
 					refreshIfLoaded(settings);
 				})];

package/lib/index.js

@@ -1,4 +1,5 @@
 import Schema from "@deepseek-ai/schemastery";
+import { credentialRef } from "@deepseek-ai/dsh-credentials";
 import { createUserMessage } from "@deepseek-ai/dsh-llm";
 import { installSettingsSection, settingsNamespace } from "@deepseek-ai/dsh-settings";
 //#region lib/types/protocol.js
@@ -435,10 +436,12 @@ var QqGatewayClient = class {
 * QQ gateway; `/qqbot off` disconnects. Nothing connects until a session opts
 * in, and QQ messages then arrive as ordinary user messages on that agent.
 *
-* The robot identity (AppID/AppSecret) lives in the `qqbot` settings section —
-* the Settings → QQ Bot page of the web GUI — with the composition entry as
-* the base layer and `QQBOT_APP_ID`/`QQBOT_APP_SECRET` as an environment
-* fallback. Committed settings changes restart a live gateway in place.
+* The robot identity (AppID/AppSecret) resolves in order: the credential
+* references `QQBOT_APP_ID`/`QQBOT_APP_SECRET` (written by the Settings → QQ
+* Bot page into the harness credential store), then the `qqbot` settings
+* section (whose base layer is the composition entry), then the same-named
+* environment variables. Committed credential or settings changes restart a
+* live gateway in place.
 *
 * The bridge is also an approval answerer for its bound agent: a tool call that
 * asks for confirmation is forwarded to the originating QQ chat as a prompt,
@@ -459,7 +462,11 @@ const Config = Schema.object({
 const QQBOT_APP_ID_ENV = "QQBOT_APP_ID";
 /** Environment variable fallback for the robot application secret. */
 const QQBOT_APP_SECRET_ENV = "QQBOT_APP_SECRET";
-/** Settings namespace carrying the robot identity (Settings → QQ Bot). */
+/** Credential reference for the robot application id (written by Settings → QQ Bot). */
+const QQBOT_APP_ID_REF = credentialRef("QQBOT_CRED_APP_ID");
+/** Credential reference for the robot application secret (written by Settings → QQ Bot). */
+const QQBOT_APP_SECRET_REF = credentialRef("QQBOT_CRED_APP_SECRET");
+/** Settings namespace carrying the identity base layer (the cordis.yml config). */
 const QQBOT_SETTINGS_NAMESPACE = settingsNamespace("qqbot");
 /** Prompt section name registered on the bound agent's scope. */
 const QQBOT_CHANNEL_SECTION = "qqbot:channel";
@@ -531,28 +538,13 @@ function parseAnswer(text) {
 	if (REJECT_ANSWERS.has(first)) return "rejected";
 }
 /**
-* Resolve robot credentials from a config section, then environment, then
-* fail loud.
-* @param config - the validated section (settings-resolved or composition entry).
-* @returns the concrete credentials.
-*/
-function resolveCredentials(config) {
-	const appId = config.appId ?? process.env["QQBOT_APP_ID"];
-	const appSecret = config.appSecret ?? process.env["QQBOT_APP_SECRET"];
-	if (appId === void 0 || appId.length === 0 || appSecret === void 0 || appSecret.length === 0) throw new Error(`qqbot: appId and appSecret are required; set them in Settings → QQ Bot, or export ${QQBOT_APP_ID_ENV}/${QQBOT_APP_SECRET_ENV}`);
-	return {
-		appId,
-		appSecret
-	};
-}
-/**
 * Mount the QQ bot bridge. It registers the `/qqbot` command and connects the
 * gateway only when a session runs `/qqbot on`; the bound agent's own scope,
 * history, and cwd are reused unchanged. While bound, it also answers that
 * agent's approval requests through the originating QQ chat.
 * @param ctx - Cordis context carrying the agent registry, commands, and session events.
-* @param config - composition entry; the user layer of the `qqbot` settings
-*   namespace resolves over it once a settings provider is mounted.
+* @param config - composition entry; the `qqbot` settings section resolves its
+*   user layer over it once a settings provider is mounted.
 */
 function apply(ctx, config) {
 	const logger = ctx.logger;
@@ -561,14 +553,36 @@ function apply(ctx, config) {
 	let boundSectionDispose;
 	let gateway;
 	let gatewaySettings;
+	let rejudgeGeneration = 0;
 	const originByMessage = /* @__PURE__ */ new Map();
 	const originByTurn = /* @__PURE__ */ new Map();
 	const replyText = /* @__PURE__ */ new Map();
 	let currentOrigin;
 	let pendingApproval;
-	/** Resolve the identity the bridge uses right now, or throw for the caller. */
-	function resolveCurrentCredentials() {
-		return resolveCredentials(readSection());
+	/**
+	* Resolve the identity the bridge uses right now, or throw for the caller.
+	* Layer ladder: the credential store (written by Settings → QQ Bot), then
+	* the settings section (settings.yaml over the cordis.yml base), then the
+	* same-named environment variables.
+	* @returns the concrete credentials.
+	*/
+	async function resolveCurrentCredentials() {
+		const section = readSection();
+		const credentials = ctx.get("credentials");
+		let appId = section.appId;
+		let appSecret = section.appSecret;
+		if (credentials !== void 0) {
+			const [appIdCredential, appSecretCredential] = await Promise.all([credentials.resolve(QQBOT_APP_ID_REF), credentials.resolve(QQBOT_APP_SECRET_REF)]);
+			if (appIdCredential !== void 0) appId = appIdCredential.value;
+			if (appSecretCredential !== void 0) appSecret = appSecretCredential.value;
+		}
+		appId = appId ?? process.env["QQBOT_APP_ID"];
+		appSecret = appSecret ?? process.env["QQBOT_APP_SECRET"];
+		if (appId === void 0 || appId.length === 0 || appSecret === void 0 || appSecret.length === 0) throw new Error(`qqbot: appId and appSecret are required; set them in Settings → QQ Bot, or export ${QQBOT_APP_ID_ENV}/${QQBOT_APP_SECRET_ENV}`);
+		return {
+			appId,
+			appSecret
+		};
 	}
 	/** Resolve the reply path for one inbound message. */
 	function replyPathOf(message) {
@@ -611,9 +625,10 @@ function apply(ctx, config) {
 		agent.followup(userMessage);
 	}
 	/** Connect the gateway for the first bound session, or reuse the live one. */
-	function ensureGateway() {
+	async function ensureGateway() {
 		if (gateway === void 0) {
-			const creds = resolveCurrentCredentials();
+			const creds = await resolveCurrentCredentials();
+			rejudgeGeneration += 1;
 			gatewaySettings = {
 				appId: creds.appId,
 				appSecret: creds.appSecret,
@@ -634,48 +649,53 @@ function apply(ctx, config) {
 		return gateway;
 	}
 	/** Bind a session: register its channel section, then connect the gateway. */
-	function bind(agent) {
+	async function bind(agent) {
+		let live;
 		try {
-			resolveCurrentCredentials();
+			live = await ensureGateway();
 		} catch (_missingCredentials) {
 			return `QQ bot credentials are not configured. Set AppID/AppSecret in Settings → QQ Bot, or export ${QQBOT_APP_ID_ENV}/${QQBOT_APP_SECRET_ENV}.`;
 		}
 		boundAgent = agent;
 		boundSectionDispose = agent.ctx.systemPrompt.section(channelSection);
-		ensureGateway().start().catch((error) => {
+		live.start().catch((error) => {
 			const detail = error instanceof Error ? error.message : String(error);
 			logger.warn(`qqbot: gateway start failed: ${detail}`);
 		});
 		return null;
 	}
 	/**
-	* Re-evaluate the settings section against the live gateway: removed
+	* Re-evaluate the credential layers against the live gateway: removed
 	* credentials close it; a changed identity or sandbox flag restarts it with
-	* the new values, keeping the binding.
+	* the new values, keeping the binding. Asynchronous by nature (credential
+	* resolution is a per-call read), so a generation counter and a
+	* gateway-identity check discard stale evaluations.
 	*/
-	function rejudgeSettings() {
+	function rejudgeIdentity() {
 		const active = gateway;
 		if (active === void 0) return;
-		let creds;
-		try {
-			creds = resolveCurrentCredentials();
-		} catch (_missingCredentials) {
+		const generation = ++rejudgeGeneration;
+		resolveCurrentCredentials().then((creds) => {
+			if (generation !== rejudgeGeneration || gateway !== active) return;
+			const sandbox = readSection().sandbox === true;
+			const current = gatewaySettings;
+			if (current !== void 0 && current.appId === creds.appId && current.appSecret === creds.appSecret && current.sandbox === sandbox) return;
+			active.close();
+			gateway = void 0;
+			gatewaySettings = void 0;
+			if (boundAgent === void 0) return;
+			ensureGateway().then((live) => {
+				live.start();
+			}, (error) => {
+				const detail = error instanceof Error ? error.message : String(error);
+				logger.warn(`qqbot: gateway restart failed: ${detail}`);
+			});
+		}, () => {
+			if (generation !== rejudgeGeneration || gateway !== active) return;
 			logger.warn("qqbot: credentials removed while connected; gateway closed");
 			active.close();
 			gateway = void 0;
 			gatewaySettings = void 0;
-			return;
-		}
-		const sandbox = readSection().sandbox === true;
-		const current = gatewaySettings;
-		if (current !== void 0 && current.appId === creds.appId && current.appSecret === creds.appSecret && current.sandbox === sandbox) return;
-		active.close();
-		gateway = void 0;
-		gatewaySettings = void 0;
-		if (boundAgent === void 0) return;
-		ensureGateway().start().catch((error) => {
-			const detail = error instanceof Error ? error.message : String(error);
-			logger.warn(`qqbot: gateway restart failed: ${detail}`);
 		});
 	}
 	/** Disconnect and drop the binding, unwinding the scoped section. */
@@ -769,10 +789,10 @@ function apply(ctx, config) {
 	ctx.commands.register({
 		name: "qqbot",
 		description: "Connect or disconnect the QQ official bot for this session (/qqbot on | off)",
-		handler: (invocation) => {
+		handler: async (invocation) => {
 			const input = invocation.rawInput.trim();
 			if (input === "on") {
-				const failure = bind(invocation.agent);
+				const failure = await bind(invocation.agent);
 				if (failure !== null) return {
 					kind: "error",
 					text: failure
@@ -795,12 +815,15 @@ function apply(ctx, config) {
 			};
 		}
 	});
+	ctx.on("credentials/updated", (ref) => {
+		if (ref === QQBOT_APP_ID_REF || ref === QQBOT_APP_SECRET_REF) rejudgeIdentity();
+	});
 	installSettingsSection(ctx, QQBOT_SETTINGS_NAMESPACE, Config, config, {
 		setSource: (current) => {
 			readSection = current;
 		},
 		onChange: () => {
-			rejudgeSettings();
+			rejudgeIdentity();
 		}
 	});
 	ctx.effect(() => () => {
@@ -808,4 +831,4 @@ function apply(ctx, config) {
 	}, "qqbot");
 }
 //#endregion
-export { Config, QQBOT_APP_ID_ENV, QQBOT_APP_SECRET_ENV, QQBOT_CHANNEL_ORDER, QQBOT_CHANNEL_PROMPT, QQBOT_CHANNEL_SECTION, QQBOT_SETTINGS_NAMESPACE, apply, inject, name, parseAnswer };
+export { Config, QQBOT_APP_ID_ENV, QQBOT_APP_ID_REF, QQBOT_APP_SECRET_ENV, QQBOT_APP_SECRET_REF, QQBOT_CHANNEL_ORDER, QQBOT_CHANNEL_PROMPT, QQBOT_CHANNEL_SECTION, QQBOT_SETTINGS_NAMESPACE, apply, inject, name, parseAnswer };

package/lib/types/client/QqbotSettingsSection.d.ts

@@ -3,10 +3,11 @@ import type { QqbotSettingsInjected } from './index.ts';
 /** Full settings.section component props: runtime share + injected share + the locale seat. */
 export type QqbotSettingsSectionProps = PropsRuntime<'settings.section'> & InjectFace<QqbotSettingsInjected> & PropsLocale<'qqbot'>;
 /**
- * The QQ Bot settings page: AppID, AppSecret, and sandbox fields over the
- * Host's redacted namespace view. The AppSecret is write-only on the wire, so
- * the field renders blank and "keep unchanged" is the empty-value meaning;
- * the clear button removes a stored secret. Saving applies every changed
- * field in one ordered write, and the Host restarts a live gateway in place.
+ * The QQ Bot settings page: AppID and AppSecret over the credential seam's
+ * value-free views. Both values are write-only on the wire — the page shows
+ * configured/not-configured chips and the inputs mean "enter a new value";
+ * an empty field keeps the stored one, and the clear buttons remove it.
+ * Saving applies every changed field in one ordered write, and the Host
+ * restarts a live gateway in place.
  */
 export declare function QqbotSettingsSection({ useQqbotSettings, useQqbotBound, save, t }: QqbotSettingsSectionProps): import("react").JSX.Element;

package/lib/types/client/locales.d.ts

@@ -10,17 +10,19 @@ export declare const zh: {
     'settings.nav': string;
     'settings.title': string;
     'settings.desc': string;
+    'chip.set': string;
+    'chip.unset': string;
     'appId.label': string;
     'appId.placeholder': string;
+    'appId.placeholder.set': string;
     'appId.hint': string;
+    'clear.appId': string;
     'appSecret.label': string;
     'appSecret.placeholder': string;
     'appSecret.placeholder.set': string;
     'appSecret.hint': string;
     'appSecret.hint.set': string;
-    'clear.label': string;
-    'sandbox.label': string;
-    'sandbox.hint': string;
+    'clear.secret': string;
     'save.label': string;
     'save.busy': string;
     'save.ok': string;
@@ -42,17 +44,19 @@ export declare const en: {
     'settings.nav': string;
     'settings.title': string;
     'settings.desc': string;
+    'chip.set': string;
+    'chip.unset': string;
     'appId.label': string;
     'appId.placeholder': string;
+    'appId.placeholder.set': string;
     'appId.hint': string;
+    'clear.appId': string;
     'appSecret.label': string;
     'appSecret.placeholder': string;
     'appSecret.placeholder.set': string;
     'appSecret.hint': string;
     'appSecret.hint.set': string;
-    'clear.label': string;
-    'sandbox.label': string;
-    'sandbox.hint': string;
+    'clear.secret': string;
     'save.label': string;
     'save.busy': string;
     'save.ok': string;

package/lib/types/client/settings-controller.d.ts

@@ -1,46 +1,54 @@
 /**
- * Settings-page transport for the qqbot namespace: reads the Host's redacted
- * settings view and writes user edits as path ops, mirroring the result in a
- * snapshot store the section renders through. The Host is the single fact
- * source — every mutation writes through the wire and the page re-renders
- * from the response view (or a reload after a refusal).
+ * Settings-page transport for the QQ bot identity: reads the credential seam's
+ * value-free views (`configured`/`source`/`writable`, never values) and writes
+ * user edits through `credentials.set`/`credentials.unset`, mirroring the
+ * result in a snapshot store the section renders through. The credentials
+ * domain is used because the settings wire face serves only a hardcoded
+ * namespace allowlist the harness owns; credentials take arbitrary reference
+ * names, so an out-of-tree plugin needs no harness patch.
  */
 import type { IApiClient } from '@deepseek-ai/dsh-api-remotes/client';
 import type { SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client';
-/** The settings namespace the Host plugin registers its identity under. */
-export declare const QQBOT_SETTINGS_NAMESPACE = "qqbot";
+/**
+ * Credential reference holding the robot application id. Deliberately NOT the
+ * environment-variable name: the credential store's env layer shadows a
+ * same-named ref and makes it read-only, which would disable the settings
+ * page wherever `QQBOT_APP_ID` is exported.
+ */
+export declare const QQBOT_APP_ID_REF = "QQBOT_CRED_APP_ID";
+/**
+ * Credential reference holding the robot application secret; distinct from
+ * `QQBOT_APP_SECRET` for the same shadowing reason.
+ */
+export declare const QQBOT_APP_SECRET_REF = "QQBOT_CRED_APP_SECRET";
 /** One user edit the section sends: absent fields stay untouched. */
 export interface QqbotSettingsPatch {
-    /** New AppID; an empty string clears the field (re-inherits the base layer). */
+    /** New AppID; omitted or empty keeps the stored value. */
     appId?: string;
     /** New AppSecret; omitted or empty keeps the stored value. */
     appSecret?: string;
-    /** New sandbox flag. */
-    sandbox?: boolean;
+    /** Remove the stored AppID. */
+    clearAppId?: boolean;
     /** Remove the stored AppSecret. */
     clearSecret?: boolean;
 }
-/** Snapshot state mirrored from the Host's redacted namespace view. */
+/** Snapshot state mirrored from the credential seam's views. */
 export interface QqbotSettingsState {
-    /** `loading` until the first accepted view; `error` after a failed load. */
+    /** `loading` until the first accepted views; `error` after a failed load. */
     status: 'idle' | 'loading' | 'ready' | 'error';
-    /** Resolved AppID (base layer overridden by the user section); '' when unset. */
-    appId: string;
-    /** Resolved sandbox flag. */
-    sandbox: boolean;
-    /** Whether the user section stores an AppSecret (the value never rides the wire). */
+    /** Whether an AppID is currently stored (the value never rides the wire). */
+    appIdSet: boolean;
+    /** Whether an AppSecret is currently stored (the value never rides the wire). */
     secretSet: boolean;
-    /** Whether the Host settings document accepts writes. */
+    /** Whether the credential store accepts writes for both references. */
     writable: boolean;
-    /** Namespace revision the next write fences against. */
-    revision: number | undefined;
     /** Human failure text of the latest load or save; null while healthy. */
     error: string | null;
 }
 /**
- * Serializes the qqbot namespace's Host reads and writes behind one snapshot
- * store. Latest load wins; a refused save reloads the namespace so the form
- * re-renders from the fresh view and the user can re-apply the edit.
+ * Serializes the two credential references' Host reads and writes behind one
+ * snapshot store. Latest load wins; a refused save reloads the views so the
+ * form re-renders from the fresh state and the user can re-apply the edit.
  */
 export declare class QqbotSettingsController {
     private readonly api;
@@ -48,24 +56,22 @@ export declare class QqbotSettingsController {
     readonly store: SnapshotStore<QqbotSettingsState>;
     private generation;
     /**
-     * @param api - the settings wire face.
+     * @param api - the credentials wire face.
      */
-    constructor(api: Pick<IApiClient, 'settings'>);
+    constructor(api: Pick<IApiClient, 'credentials'>);
     /**
-     * Refresh the snapshot from `settings.describe`; a failure keeps the last
-     * good state and surfaces the error.
+     * Refresh the snapshot from `credentials.describe`; a failure keeps the
+     * last good state and surfaces the error.
      * @returns settlement after the read.
      */
     load(): Promise<void>;
     /**
-     * Apply one user edit as ordered path ops; a refusal reloads the namespace
-     * and returns its message.
+     * Apply one user edit as ordered credential writes, stopping at the first
+     * refusal; a refusal reloads the views and returns its message.
      * @param patch - the fields the user changed.
      * @returns null on success; the Host's failure text otherwise.
      */
     save(patch: QqbotSettingsPatch): Promise<string | null>;
-    /** Fold one redacted wire view into the snapshot. */
-    private accept;
 }
 /**
  * Refresh only after the section left idle, so an unopened page never fetches

package/lib/types/index.d.ts

@@ -7,10 +7,12 @@
  * QQ gateway; `/qqbot off` disconnects. Nothing connects until a session opts
  * in, and QQ messages then arrive as ordinary user messages on that agent.
  *
- * The robot identity (AppID/AppSecret) lives in the `qqbot` settings section —
- * the Settings → QQ Bot page of the web GUI — with the composition entry as
- * the base layer and `QQBOT_APP_ID`/`QQBOT_APP_SECRET` as an environment
- * fallback. Committed settings changes restart a live gateway in place.
+ * The robot identity (AppID/AppSecret) resolves in order: the credential
+ * references `QQBOT_APP_ID`/`QQBOT_APP_SECRET` (written by the Settings → QQ
+ * Bot page into the harness credential store), then the `qqbot` settings
+ * section (whose base layer is the composition entry), then the same-named
+ * environment variables. Committed credential or settings changes restart a
+ * live gateway in place.
  *
  * The bridge is also an approval answerer for its bound agent: a tool call that
  * asks for confirmation is forwarded to the originating QQ chat as a prompt,
@@ -20,6 +22,7 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import Schema from '@deepseek-ai/schemastery';
+import { type CredentialRef } from '@deepseek-ai/dsh-credentials';
 import type { ApprovalOutcome } from '@deepseek-ai/dsh-user-approval';
 import type { QqbotConfig } from './types.ts';
 export type { QqbotConfig } from './types.ts';
@@ -32,7 +35,11 @@ export declare const Config: Schema<QqbotConfig>;
 export declare const QQBOT_APP_ID_ENV = "QQBOT_APP_ID";
 /** Environment variable fallback for the robot application secret. */
 export declare const QQBOT_APP_SECRET_ENV = "QQBOT_APP_SECRET";
-/** Settings namespace carrying the robot identity (Settings → QQ Bot). */
+/** Credential reference for the robot application id (written by Settings → QQ Bot). */
+export declare const QQBOT_APP_ID_REF: CredentialRef;
+/** Credential reference for the robot application secret (written by Settings → QQ Bot). */
+export declare const QQBOT_APP_SECRET_REF: CredentialRef;
+/** Settings namespace carrying the identity base layer (the cordis.yml config). */
 export declare const QQBOT_SETTINGS_NAMESPACE: import("@deepseek-ai/dsh-settings").SettingsNamespace;
 /** Prompt section name registered on the bound agent's scope. */
 export declare const QQBOT_CHANNEL_SECTION = "qqbot:channel";
@@ -58,7 +65,7 @@ export declare function parseAnswer(text: string): ApprovalOutcome | undefined;
  * history, and cwd are reused unchanged. While bound, it also answers that
  * agent's approval requests through the originating QQ chat.
  * @param ctx - Cordis context carrying the agent registry, commands, and session events.
- * @param config - composition entry; the user layer of the `qqbot` settings
- *   namespace resolves over it once a settings provider is mounted.
+ * @param config - composition entry; the `qqbot` settings section resolves its
+ *   user layer over it once a settings provider is mounted.
  */
 export declare function apply(ctx: Context, config: QqbotConfig): void;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-qqbot",
   "description": "QQ official bot bridge for DeepSeek Harness: /qqbot command, bound-session routing, QQ-side approvals, the composer connection toggle, and the QQ Bot settings page",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
@@ -46,6 +46,7 @@
     "test": "vitest run"
   },
   "dependencies": {
+    "@deepseek-ai/dsh-credentials": "^0.1.0-rc.5",
     "@deepseek-ai/dsh-settings": "^0.1.0-rc.5",
     "@deepseek-ai/schemastery": "^3.18.1"
   },
@@ -79,6 +80,7 @@
     "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.5",
     "@deepseek-ai/dsh-client-web-react": "^0.1.0-rc.5",
     "@deepseek-ai/dsh-commands": "^0.1.0-rc.5",
+    "@deepseek-ai/dsh-credentials": "^0.1.0-rc.5",
     "@deepseek-ai/dsh-invariants": "^0.1.0-rc.5",
     "@deepseek-ai/dsh-llm": "^0.1.0-rc.5",
     "@deepseek-ai/dsh-session": "^0.1.0-rc.5",