@dsh-plus/secret-env 0.1.1 → 0.1.2

package/lib/index.d.ts

@@ -3,12 +3,14 @@ import { Context, Service } from "@deepseek-ai/cordis";
 //#region src/config.d.ts
 declare const Config: z<Schemastery.ObjectS<{
   secrets: z<unknown[], any[]>;
+  masked: z<string[], string[]>;
 }>, Schemastery.ObjectT<{
   secrets: z<unknown[], any[]>;
+  masked: z<string[], string[]>;
 }>>;
 type SecretEnvConfig = Schemastery.TypeT<typeof Config>;
 //#endregion
-//#region src/service.d.ts
+//#region src/inventory.d.ts
 /** 列表端点的全局条目（describe 视图，绝无值）。 */
 interface GlobalEntry {
   name: string;
@@ -17,6 +19,8 @@ interface GlobalEntry {
   configured: boolean;
   source?: string;
   writable: boolean;
+  /** 会话视图：该变量在本会话被屏蔽（无 sessionId 的调用恒为 false）。 */
+  masked: boolean;
 }
 /** 列表端点的会话条目。 */
 interface SessionEntry {
@@ -26,14 +30,29 @@ interface SessionEntry {
   once: boolean;
   createdAt: string;
 }
+/**
+ * 列表端点的继承条目：宿主进程环境里已存在的 DSH_VAR_* 变量
+ * （非本插件索引管理；默认纳入注入）。masked = 生效屏蔽态，
+ * globallyMasked = 是否由全局屏蔽导致（会话视图里据此禁用会话级开关）。
+ */
+interface InheritedEntry {
+  name: string;
+  envName: string;
+  masked: boolean;
+  globallyMasked: boolean;
+}
+//#endregion
+//#region src/service.d.ts
 declare class SecretEnvService extends Service {
   static [Context.inject]: string[];
   /** 全局值镜像（seam resolve 为异步，contributor 同步读这里）。 */
   private readonly globalMirror;
   /** 会话桶：sessionId → 后缀 → 条目。 */
   private readonly buckets;
-  /** 变量名 → contributor 注销器（shell-env 要求一键一主）。 */
-  private readonly contributors;
+  /** 会话级屏蔽名单：sessionId → 后缀集合（纯内存，随会话终结清除）。 */
+  private readonly sessionMasks;
+  /** contributor 登记簿（受管/继承两条线，一键一主）。 */
+  private readonly book;
   /** 行级 config（settings 缺席时的索引来源）。 */
   private readonly base;
   /** installSection 给的实时 getter（scope.get 的活视图，读即最新，无时序竞态）。 */
@@ -46,16 +65,22 @@ declare class SecretEnvService extends Service {
   constructor(ctx: Context, config: SecretEnvConfig | undefined);
   /** 当前生效索引（settings 活视图优先，缺席回落行级 config）。 */
   private currentMeta;
+  /** 当前全局屏蔽名单（与索引同源，活读取）。 */
+  private currentMasked;
+  /** 继承变量后缀：宿主进程环境里已存在的 DSH_VAR_* 且不在本插件索引内。 */
+  private inheritedSuffixes;
   /** 索引成员判定（索引是全局名管理面的唯一事实源）。 */
   private isIndexed;
-  /** 索引差量调和：新名建镜像，移出名撤镜像并回收其独占的 contributor。 */
+  /** 索引差量调和：新名建镜像，移出名撤镜像并回落继承登记（若宿主仍有同名）。 */
   private reconcile;
   /** 重新 resolve 一个全局名并同步镜像与 contributor（外部热编辑亦走此路）。 */
   private refreshMirror;
-  /** contributor 登记簿：有任一来源（全局镜像或任一会话桶）则注册，否则注销。 */
+  /** 受管登记簿同步：有任一来源（全局镜像或任一会话桶）则注册，否则注销。 */
   private syncContributor;
-  private registerContributor;
-  /** 注入解析：会话值优先，未命中回落全局镜像；once 命中即焚（注销推迟到微任务，避免 collect 迭代中改注册表）。 */
+  /**
+   * 受管注入解析：会话屏蔽名单优先（任何来源都拦），会话值次之，全局屏蔽再次，
+   * 未命中回落全局镜像；once 命中即焚（注销推迟到微任务，避免 collect 迭代中改登记簿）。
+   */
   private resolveFor;
   /** 会话终结：整桶清除并回收其独占的 contributor。 */
   private dropBucket;
@@ -64,10 +89,17 @@ declare class SecretEnvService extends Service {
   list(sessionId?: string): Promise<{
     global: GlobalEntry[];
     session: SessionEntry[];
+    inherited: InheritedEntry[];
   }>;
+  /**
+   * 屏蔽/恢复一个变量：sessionId 缺席时为全局屏蔽（持久于 settings，
+   * 主要面向继承变量）；否则为会话级屏蔽（纯内存，会话终结即清）。
+   * 两级屏蔽都在 contributor resolve 时现判，下一条命令即生效。
+   */
+  setMask(suffix: string, masked: boolean, sessionId?: string): Promise<void>;
   /** 写入全局值（seam 拒绝继承环境遮蔽与空值，此处先行给出结构化错误）。 */
   setGlobal(suffix: string, value: string, description: string): Promise<void>;
-  /** 删除全局值与元数据。 */
+  /** 删除全局值与元数据；宿主环境仍有同名变量时回落为继承变量继续纳入。 */
   unsetGlobal(suffix: string): Promise<void>;
   /** 写入会话级值（纯内存；host 重启或会话终结即失）。 */
   setSession(sessionId: string, suffix: string, value: string, description: string, once: boolean): void;

package/lib/index.js

@@ -23,7 +23,10 @@ const SecretMetaSchema = z.object({
 	description: z.string().description("用途描述（仅人读，不进提示词）").default(""),
 	createdAt: z.string().description("创建时间 ISO").default("")
 });
-const Config = z.object({ secrets: z.array(SecretMetaSchema).description("全局密钥元数据索引（值存凭据库）").default([]) });
+const Config = z.object({
+	secrets: z.array(SecretMetaSchema).description("全局密钥元数据索引（值存凭据库）").default([]),
+	masked: z.array(z.string()).description("全局屏蔽的变量名后缀（继承变量等；注入时跳过）").default([])
+});
 //#endregion
 //#region src/errors.ts
 /**
@@ -43,12 +46,12 @@ var SecretEnvError = class extends Error {
 /**
 * 变量名语法（纯函数，零依赖；node 半与浏览器半共用）：
 * 用户给出后缀（如 `GITHUB_TOKEN`），插件拼出完整受管变量名
-* `DSH_SECRET_GITHUB_TOKEN`——即模型经 `env | grep ^DSH_` 可见、
-* 在 shell 命令中以 `$DSH_SECRET_*` 引用的那个名字。
+* `DSH_VAR_GITHUB_TOKEN`——即模型经 `env | grep ^DSH_` 可见、
+* 在 shell 命令中以 `$DSH_VAR_*` 引用的那个名字。
 * @module secret-env/names
 */
 /** 受管变量名前缀（属 dsh-shell-env 的 DSH_* 受管命名空间）。 */
-const ENV_PREFIX = "DSH_SECRET_";
+const ENV_PREFIX = "DSH_VAR_";
 /** 后缀语法：POSIX 环境变量名，大写字母开头，总长（含前缀）不超过 79。 */
 const SUFFIX_PATTERN = /^[A-Z][A-Z0-9_]*$/;
 const MAX_SUFFIX_LENGTH = 64;
@@ -69,11 +72,11 @@ function envNameOf(suffix) {
 }
 /** 判断一个完整变量名是否属本插件管理（用于凭据热更事件过滤）。 */
 function isManagedEnvName(envName) {
-	return envName.startsWith("DSH_SECRET_") && envName.length > 11;
+	return envName.startsWith("DSH_VAR_") && envName.length > 8;
 }
 /** 由完整变量名反解后缀；非本插件名返回 undefined。 */
 function suffixOf(envName) {
-	return isManagedEnvName(envName) ? envName.slice(11) : void 0;
+	return isManagedEnvName(envName) ? envName.slice(8) : void 0;
 }
 //#endregion
 //#region src/api.ts
@@ -181,20 +184,93 @@ function registerSecretEnvApi(ctx, service) {
 			}, res);
 		}
 	});
+	ctx.webServer.register({
+		kind: "prefix",
+		path: `${ROUTE}/mask/set`,
+		handler: async (req, res) => {
+			guard("mask/set", async () => {
+				if (req.method !== "POST") throw new SecretEnvError("method", "POST only");
+				const body = JSON.parse(await readBody(req));
+				const sessionId = readString(body.sessionId);
+				await service.setMask(readSuffix(body.name), body.masked === true, sessionId === "" ? void 0 : sessionId);
+				sendJson(res, 200, { ok: true });
+			}, res);
+		}
+	});
 }
 //#endregion
-//#region src/service.ts
-/**
-* secret-env 服务主体（host 半）：
-* - 全局臂：值经 dsh-credentials seam 持久（$DSH_HOME/.credentials.yaml），
-*   服务内存中维护同步镜像（contributor.resolve 是同步签名，无法现查异步 seam）；
-* - 会话臂：Map<SessionId, Map<后缀, 值>> 纯内存，session/disposed 清除；
-* - 注入臂：每个变量名一个 dsh-shell-env contributor，每次 shell 执行由
-*   注册表 collect 现取——写入/删除下一条命令即生效，不进消息流、不动前缀。
-*
-* 红线：值只流经「端点 → 本服务 → dshEnv」，任何日志/事件/返回值不带值。
-* @module secret-env/service
-*/
+//#region src/contributors.ts
+var ContributorBook = class {
+	managed = /* @__PURE__ */ new Map();
+	inherited = /* @__PURE__ */ new Map();
+	deps;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	/** 受管登记：有任一来源值则注册，否则注销。 */
+	syncManaged(suffix, hasValue) {
+		const envName = envNameOf(suffix);
+		const registered = this.managed.has(envName);
+		if (hasValue && !registered) {
+			this.registerManaged(suffix, envName);
+			return;
+		}
+		if (!hasValue && registered) {
+			this.managed.get(envName)?.();
+			this.managed.delete(envName);
+		}
+	}
+	/** 继承登记：按 shouldForwardInherited 现判注册/注销。 */
+	syncInherited(suffix) {
+		const envName = envNameOf(suffix);
+		const registered = this.inherited.get(envName);
+		if (this.deps.shouldForwardInherited(suffix) && registered === void 0) {
+			const dispose = this.deps.shellEnv.register({
+				name: `secret-env-inherited:${suffix}`,
+				variables: { [envName]: { description: "inherited variable" } },
+				resolve: (execution) => {
+					const value = this.deps.resolveInherited(suffix, execution);
+					return value === void 0 || value === "" ? {} : { [envName]: value };
+				}
+			});
+			this.inherited.set(envName, dispose);
+			return;
+		}
+		if (!this.deps.shouldForwardInherited(suffix) && registered !== void 0) {
+			registered();
+			this.inherited.delete(envName);
+		}
+	}
+	registerManaged(suffix, envName) {
+		const inherited = this.inherited.get(envName);
+		if (inherited !== void 0) {
+			inherited();
+			this.inherited.delete(envName);
+		}
+		try {
+			const dispose = this.deps.shellEnv.register({
+				name: `secret-env:${suffix}`,
+				variables: { [envName]: { description: this.deps.describeManaged(suffix) } },
+				resolve: (execution) => {
+					const value = this.deps.resolveManaged(suffix, execution);
+					return value === void 0 ? {} : { [envName]: value };
+				}
+			});
+			this.managed.set(envName, dispose);
+		} catch (error) {
+			throw new SecretEnvError("conflict", `variable ${envName} conflicts with an existing contributor: ${error instanceof Error ? error.message : String(error)}`);
+		}
+	}
+	dispose() {
+		for (const dispose of this.managed.values()) dispose();
+		this.managed.clear();
+		for (const dispose of this.inherited.values()) dispose();
+		this.inherited.clear();
+	}
+};
+//#endregion
+//#region src/inventory.ts
+/** 从索引数据解析全局密钥元数据列表（宽容过滤非法项）。 */
 function asMeta(value) {
 	if (value === void 0 || value === null || typeof value !== "object") return [];
 	const list = value.secrets;
@@ -205,14 +281,61 @@ function asMeta(value) {
 		createdAt: typeof item.createdAt === "string" ? item.createdAt : ""
 	})).filter((item) => item.name.length > 0);
 }
+/** 从同一索引数据解析全局屏蔽名单（与 secrets 共一个 settings 命名空间）。 */
+function asMasked(value) {
+	if (value === void 0 || value === null || typeof value !== "object") return [];
+	const list = value.masked;
+	if (!Array.isArray(list)) return [];
+	return list.filter((item) => typeof item === "string" && item.length > 0);
+}
+/** 继承变量后缀：给定进程环境里的 DSH_VAR_* 且不在索引内（按名排序）。 */
+function inheritedSuffixesOf(env, indexed) {
+	const found = [];
+	for (const key of Object.keys(env)) {
+		const suffix = suffixOf(key);
+		if (suffix !== void 0 && !indexed.has(suffix)) found.push(suffix);
+	}
+	return found.sort();
+}
+/** 拼装继承条目列表（list 端点的 inherited 段）。 */
+function inheritedEntriesOf(suffixes, globalMasked, sessionMask) {
+	return suffixes.map((name) => {
+		const globally = globalMasked.has(name);
+		return {
+			name,
+			envName: envNameOf(name),
+			masked: globally || sessionMask?.has(name) === true,
+			globallyMasked: globally
+		};
+	});
+}
+//#endregion
+//#region src/service.ts
+/**
+* secret-env 服务主体（host 半）：
+* - 全局臂：值经 dsh-credentials seam 持久（$DSH_HOME/.credentials.yaml），
+*   服务内存中维护同步镜像（contributor.resolve 是同步签名，无法现查异步 seam）；
+* - 会话臂：Map<SessionId, Map<后缀, 值>> 纯内存，session/disposed 清除；
+* - 屏蔽臂：全局屏蔽名单持久于 settings（继承变量主要开关），
+*   会话级屏蔽纯内存；两级都在 contributor resolve 时现判；
+* - 注入臂：每个变量名一个 dsh-shell-env contributor（ContributorBook），
+*   每次 shell 执行由注册表 collect 现取——写入/删除/屏蔽下一条命令即生效，
+*   不进消息流、不动前缀。继承变量（宿主环境 DSH_VAR_*）平台默认剥离，
+*   本服务按「默认纳入」逐一转发，可被屏蔽名单拦截。
+*
+* 红线：值只流经「端点 → 本服务 → dshEnv」，任何日志/事件/返回值不带值。
+* @module secret-env/service
+*/
 var SecretEnvService = class extends Service {
 	static [Context.inject] = ["credentials", "shellEnv"];
 	/** 全局值镜像（seam resolve 为异步，contributor 同步读这里）。 */
 	globalMirror = /* @__PURE__ */ new Map();
 	/** 会话桶：sessionId → 后缀 → 条目。 */
 	buckets = /* @__PURE__ */ new Map();
-	/** 变量名 → contributor 注销器（shell-env 要求一键一主）。 */
-	contributors = /* @__PURE__ */ new Map();
+	/** 会话级屏蔽名单：sessionId → 后缀集合（纯内存，随会话终结清除）。 */
+	sessionMasks = /* @__PURE__ */ new Map();
+	/** contributor 登记簿（受管/继承两条线，一键一主）。 */
+	book;
 	/** 行级 config（settings 缺席时的索引来源）。 */
 	base;
 	/** installSection 给的实时 getter（scope.get 的活视图，读即最新，无时序竞态）。 */
@@ -224,7 +347,25 @@ var SecretEnvService = class extends Service {
 	ready;
 	constructor(ctx, config) {
 		super(ctx, "secretEnv");
-		this.base = config ?? { secrets: [] };
+		this.base = config ?? {
+			secrets: [],
+			masked: []
+		};
+		this.book = new ContributorBook({
+			shellEnv: ctx.shellEnv,
+			describeManaged: (suffix) => {
+				const found = this.currentMeta().find((item) => item.name === suffix)?.description;
+				return found !== void 0 && found.trim() !== "" ? found : "secret variable";
+			},
+			resolveManaged: (suffix, execution) => this.resolveFor(suffix, execution),
+			shouldForwardInherited: (suffix) => process.env[envNameOf(suffix)] !== void 0 && !this.isIndexed(suffix),
+			resolveInherited: (suffix, execution) => {
+				if (this.currentMasked().has(suffix)) return void 0;
+				const agentId = execution.agent?.id;
+				if (agentId !== void 0 && this.sessionMasks.get(String(agentId))?.has(suffix) === true) return;
+				return process.env[envNameOf(suffix)];
+			}
+		});
 		ctx.inject(["settings"], (settingsCtx) => {
 			const settings = settingsCtx.settings;
 			settings.installSection(ctx, SETTINGS_NS, Config, this.base, {
@@ -239,6 +380,7 @@ var SecretEnvService = class extends Service {
 			this.reconcile();
 		});
 		ctx.root.on("session/disposed", (session) => {
+			this.sessionMasks.delete(session.id);
 			this.dropBucket(session.id);
 		});
 		ctx.on("credentials/reference-updated", (ref) => {
@@ -248,17 +390,26 @@ var SecretEnvService = class extends Service {
 		ctx.inject(["webServer"], (webCtx) => {
 			registerSecretEnvApi(webCtx, this);
 		});
+		for (const suffix of this.inheritedSuffixes()) this.book.syncInherited(suffix);
 		this.ready = this.reconcile();
 	}
 	/** 当前生效索引（settings 活视图优先，缺席回落行级 config）。 */
 	currentMeta() {
 		return asMeta(this.readIndex !== void 0 ? this.readIndex() : this.base);
 	}
+	/** 当前全局屏蔽名单（与索引同源，活读取）。 */
+	currentMasked() {
+		return new Set(asMasked(this.readIndex !== void 0 ? this.readIndex() : this.base));
+	}
+	/** 继承变量后缀：宿主进程环境里已存在的 DSH_VAR_* 且不在本插件索引内。 */
+	inheritedSuffixes() {
+		return inheritedSuffixesOf(process.env, new Set(this.currentMeta().map((item) => item.name)));
+	}
 	/** 索引成员判定（索引是全局名管理面的唯一事实源）。 */
 	isIndexed(suffix) {
 		return this.currentMeta().some((item) => item.name === suffix);
 	}
-	/** 索引差量调和：新名建镜像，移出名撤镜像并回收其独占的 contributor。 */
+	/** 索引差量调和：新名建镜像，移出名撤镜像并回落继承登记（若宿主仍有同名）。 */
 	async reconcile() {
 		const next = this.currentMeta();
 		const removed = this.lastMeta.filter((item) => !next.some((n) => n.name === item.name));
@@ -267,6 +418,7 @@ var SecretEnvService = class extends Service {
 		for (const item of removed) {
 			this.globalMirror.delete(item.name);
 			this.syncContributor(item.name);
+			this.book.syncInherited(item.name);
 		}
 		for (const item of added) await this.refreshMirror(item.name);
 	}
@@ -277,46 +429,25 @@ var SecretEnvService = class extends Service {
 		else this.globalMirror.set(suffix, resolved.value);
 		this.syncContributor(suffix);
 	}
-	/** contributor 登记簿：有任一来源（全局镜像或任一会话桶）则注册，否则注销。 */
+	/** 受管登记簿同步：有任一来源（全局镜像或任一会话桶）则注册，否则注销。 */
 	syncContributor(suffix) {
-		const envName = envNameOf(suffix);
 		const hasGlobal = this.globalMirror.has(suffix);
 		let hasSession = false;
 		for (const bucket of this.buckets.values()) if (bucket.has(suffix)) {
 			hasSession = true;
 			break;
 		}
-		const registered = this.contributors.has(envName);
-		if ((hasGlobal || hasSession) && !registered) {
-			this.registerContributor(suffix, envName);
-			return;
-		}
-		if (!hasGlobal && !hasSession && registered) {
-			this.contributors.get(envName)?.();
-			this.contributors.delete(envName);
-		}
+		this.book.syncManaged(suffix, hasGlobal || hasSession);
 	}
-	registerContributor(suffix, envName) {
-		const found = this.currentMeta().find((item) => item.name === suffix)?.description;
-		const description = found !== void 0 && found.trim() !== "" ? found : "secret variable";
-		try {
-			const dispose = this.ctx.shellEnv.register({
-				name: `secret-env:${suffix}`,
-				variables: { [envName]: { description } },
-				resolve: (execution) => {
-					const value = this.resolveFor(suffix, execution);
-					return value === void 0 ? {} : { [envName]: value };
-				}
-			});
-			this.contributors.set(envName, dispose);
-		} catch (error) {
-			throw new SecretEnvError("conflict", `variable ${envName} conflicts with an existing contributor: ${error instanceof Error ? error.message : String(error)}`);
-		}
-	}
-	/** 注入解析：会话值优先，未命中回落全局镜像；once 命中即焚（注销推迟到微任务，避免 collect 迭代中改注册表）。 */
+	/**
+	* 受管注入解析：会话屏蔽名单优先（任何来源都拦），会话值次之，全局屏蔽再次，
+	* 未命中回落全局镜像；once 命中即焚（注销推迟到微任务，避免 collect 迭代中改登记簿）。
+	*/
 	resolveFor(suffix, execution) {
 		const sessionId = execution.agent?.id;
-		const bucket = sessionId === void 0 ? void 0 : this.buckets.get(String(sessionId));
+		const sid = sessionId === void 0 ? void 0 : String(sessionId);
+		if (sid !== void 0 && this.sessionMasks.get(sid)?.has(suffix) === true) return void 0;
+		const bucket = sid === void 0 ? void 0 : this.buckets.get(sid);
 		const entry = bucket?.get(suffix);
 		if (entry !== void 0) {
 			if (entry.once && bucket !== void 0) {
@@ -325,6 +456,7 @@ var SecretEnvService = class extends Service {
 			}
 			return entry.value;
 		}
+		if (this.currentMasked().has(suffix)) return void 0;
 		return this.globalMirror.get(suffix);
 	}
 	/** 会话终结：整桶清除并回收其独占的 contributor。 */
@@ -340,6 +472,7 @@ var SecretEnvService = class extends Service {
 	}
 	/** 列表（值永不出现；global 条目来自 credentials.describe 的安全视图）。 */
 	async list(sessionId) {
+		const sessionMask = sessionId === void 0 ? void 0 : this.sessionMasks.get(sessionId);
 		return {
 			global: await Promise.all(this.currentMeta().map(async (item) => {
 				const info = await this.ctx.credentials.describe(credentialRef(envNameOf(item.name)));
@@ -349,7 +482,8 @@ var SecretEnvService = class extends Service {
 					description: item.description,
 					configured: info.configured,
 					source: info.source,
-					writable: info.writable
+					writable: info.writable,
+					masked: sessionMask?.has(item.name) === true
 				};
 			})),
 			session: [...(sessionId === void 0 ? void 0 : this.buckets.get(sessionId))?.entries() ?? []].map(([name, entry]) => ({
@@ -358,9 +492,29 @@ var SecretEnvService = class extends Service {
 				description: entry.description,
 				once: entry.once,
 				createdAt: entry.createdAt
-			}))
+			})),
+			inherited: inheritedEntriesOf(this.inheritedSuffixes(), this.currentMasked(), sessionMask)
 		};
 	}
+	/**
+	* 屏蔽/恢复一个变量：sessionId 缺席时为全局屏蔽（持久于 settings，
+	* 主要面向继承变量）；否则为会话级屏蔽（纯内存，会话终结即清）。
+	* 两级屏蔽都在 contributor resolve 时现判，下一条命令即生效。
+	*/
+	async setMask(suffix, masked, sessionId) {
+		if (sessionId !== void 0) {
+			if (sessionId.length === 0) throw new SecretEnvError("no-session", "sessionId required");
+			const set = this.sessionMasks.get(sessionId) ?? /* @__PURE__ */ new Set();
+			if (masked) set.add(suffix);
+			else set.delete(suffix);
+			if (set.size === 0) this.sessionMasks.delete(sessionId);
+			else this.sessionMasks.set(sessionId, set);
+			return;
+		}
+		const next = asMasked(this.readIndex !== void 0 ? this.readIndex() : this.base).filter((item) => item !== suffix);
+		if (masked) next.push(suffix);
+		if (this.settingsRef !== void 0) await this.settingsRef.update(SETTINGS_NS, { masked: next });
+	}
 	/** 写入全局值（seam 拒绝继承环境遮蔽与空值，此处先行给出结构化错误）。 */
 	async setGlobal(suffix, value, description) {
 		if (value.length === 0) throw new SecretEnvError("empty-value", "value must not be empty");
@@ -382,7 +536,7 @@ var SecretEnvService = class extends Service {
 		this.lastMeta = next;
 		await this.refreshMirror(suffix);
 	}
-	/** 删除全局值与元数据。 */
+	/** 删除全局值与元数据；宿主环境仍有同名变量时回落为继承变量继续纳入。 */
 	async unsetGlobal(suffix) {
 		await this.ctx.credentials.unset(credentialRef(envNameOf(suffix)));
 		const next = this.currentMeta().filter((item) => item.name !== suffix);
@@ -390,6 +544,7 @@ var SecretEnvService = class extends Service {
 		this.lastMeta = next;
 		this.globalMirror.delete(suffix);
 		this.syncContributor(suffix);
+		this.book.syncInherited(suffix);
 	}
 	/** 写入会话级值（纯内存；host 重启或会话终结即失）。 */
 	setSession(sessionId, suffix, value, description, once) {
@@ -413,8 +568,7 @@ var SecretEnvService = class extends Service {
 		this.syncContributor(suffix);
 	}
 	dispose() {
-		for (const disposeContributor of this.contributors.values()) disposeContributor();
-		this.contributors.clear();
+		this.book.dispose();
 	}
 };
 //#endregion

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dsh-plus/secret-env",
-  "version": "0.1.1",
-  "description": "dsh-plus service+ui plugin: 密钥环境变量——以 $DSH_SECRET_* 变量名向 agent 暴露密钥（全局持久/会话级/一次性），执行期经 dsh-shell-env 原生注入，值不进消息流，不影响缓存率",
+  "version": "0.1.2",
+  "description": "dsh-plus service+ui plugin: 密钥环境变量——以 $DSH_VAR_* 变量名向 agent 暴露密钥（全局持久/会话级/一次性），执行期经 dsh-shell-env 原生注入，值不进消息流，不影响缓存率",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -19,7 +19,7 @@
     "src"
   ],
   "dependencies": {
-    "@dsh-plus/shared": "0.1.7"
+    "@dsh-plus/shared": "0.1.8"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
@@ -31,6 +31,7 @@
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "4.0.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "0.1.2-alpha.2",
     "@deepseek-ai/dsh-credentials": "0.1.2-alpha.2",
     "@deepseek-ai/dsh-host-webserver": "0.1.2-alpha.2",
     "@deepseek-ai/dsh-session": "0.1.2-alpha.2",
@@ -52,7 +53,8 @@
         "@deepseek-ai/dsh-client-locale",
         "@deepseek-ai/dsh-api-remotes",
         "@deepseek-ai/dsh-api-session-controller",
-        "@deepseek-ai/dsh-client-ui-conversation"
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-commands"
       ],
       "platform": "web"
     }

package/src/api.ts

@@ -1,5 +1,6 @@
 /**
- * secret-env HTTP 端点：GET list / POST global.set / global.unset / session.set / session.unset。
+ * secret-env HTTP 端点：GET list / POST global.set / global.unset /
+ * session.set / session.unset / mask.set。
  * 与 dsh web 同源（webServer 默认 loopback / 反代信任域），无独立鉴权
  * （与 usage-panel/notify-email 自定义端点同一暴露面约定）。
  * 值只在「浏览器 → 本端点 → 服务」链路出现，响应永不回显值。
@@ -151,4 +152,26 @@ export function registerSecretEnvApi(ctx: Context, service: SecretEnvService): v
       )
     },
   })
+
+  ctx.webServer.register({
+    kind: 'prefix',
+    path: `${ROUTE}/mask/set`,
+    handler: async (req, res) => {
+      guard(
+        'mask/set',
+        async () => {
+          if (req.method !== 'POST') throw new SecretEnvError('method', 'POST only')
+          const body = JSON.parse(await readBody(req)) as Record<string, unknown>
+          const sessionId = readString(body.sessionId)
+          await service.setMask(
+            readSuffix(body.name),
+            body.masked === true,
+            sessionId === '' ? undefined : sessionId,
+          )
+          sendJson(res, 200, { ok: true })
+        },
+        res,
+      )
+    },
+  })
 }

package/src/client/api.ts

@@ -11,6 +11,8 @@ export interface GlobalWireEntry {
   configured: boolean
   source?: string
   writable: boolean
+  /** 会话视图：本会话已屏蔽（无 sessionId 的请求恒 false）。 */
+  masked: boolean
 }
 
 export interface SessionWireEntry {
@@ -21,9 +23,20 @@ export interface SessionWireEntry {
   createdAt: string
 }
 
+/** 继承变量：宿主进程环境中已存在的 DSH_VAR_*（非本插件管理）。 */
+export interface InheritedWireEntry {
+  name: string
+  envName: string
+  /** 生效屏蔽态（全局或本会话）。 */
+  masked: boolean
+  /** 是否由全局屏蔽导致（会话视图据此禁用会话级开关）。 */
+  globallyMasked: boolean
+}
+
 export interface SecretList {
   global: GlobalWireEntry[]
   session: SessionWireEntry[]
+  inherited: InheritedWireEntry[]
 }
 
 interface WriteResult {
@@ -74,3 +87,8 @@ export function setSession(
 export function unsetSession(sessionId: string, name: string): Promise<void> {
   return write('session/unset', { sessionId, name })
 }
+
+/** 屏蔽/恢复：sessionId 缺席为全局屏蔽（设置页），否则为会话级屏蔽。 */
+export function setMask(name: string, masked: boolean, sessionId?: string): Promise<void> {
+  return write('mask/set', { name, masked, sessionId })
+}