@dsh-plus/secret-env 0.1.1 → 0.1.2

package/src/client/styles.ts

@@ -30,23 +30,22 @@ const EXTRA = `
 .dse-delBtn:hover{color:var(--dsw-alias-label-error)}
 .dse-empty{color:var(--dsw-alias-label-tertiary);font-size:13px;padding:18px 14px;margin:0;background:var(--dsw-alias-bg-layer-3)}
 .dse-form{border:1px solid var(--dsw-alias-border-l2);border-radius:12px;background:var(--dsw-alias-bg-layer-3);padding:4px 14px 12px;margin-top:10px}
-.dse-formGrid{display:grid;grid-template-columns:1fr 1fr;gap:0 16px}
-/* 会话注入控件（composer 工具行胶囊，对齐官方 chip 语言） */
-.dse-wrap{position:relative;align-items:center;display:inline-flex}
-.dse-chip{background:var(--dsw-alias-bg-module-platform);min-width:34px;color:var(--dsw-alias-label-secondary);cursor:pointer;border:none;border-radius:999px;align-items:center;gap:4px;padding:2px 8px;font-size:13px;font-weight:500;line-height:20px;display:inline-flex}
-.dse-chip:hover:not(:disabled){color:var(--dsw-alias-label-primary)}
-.dse-chip:focus-visible{outline:2px solid var(--dsw-alias-brand-primary);outline-offset:2px}
-.dse-chip:disabled{opacity:.6;cursor:default}
-.dse-count{background:var(--dsw-alias-brand-primary);color:var(--dsw-alias-bg-base);border-radius:999px;min-width:16px;text-align:center;font-size:11px;line-height:16px;padding:0 4px}
-.dse-pop{position:absolute;bottom:calc(100% + 8px);right:0;z-index:60;width:320px;max-width:calc(100vw - 24px);background:var(--dsw-alias-bg-layer-2);border:1px solid var(--dsw-alias-border-l2);border-radius:12px;box-shadow:0 8px 28px rgba(0,0,0,.18);padding:10px 12px 12px}
+.dse-inputError{border-color:var(--dsw-alias-label-error)}
+.dse-hintError{color:var(--dsw-alias-label-error)}
+/* 会话变量面板（/var 命令唤起，overlay 槽浮层）与内嵌共用件 */
+.dse-panelWrap{position:relative}
+.dse-panelCard{position:absolute;bottom:calc(100% + 6px);left:0;right:0;z-index:60;max-height:min(60vh,560px);overflow:auto;background:var(--dsw-alias-bg-layer-2);border:1px solid var(--dsw-alias-border-l2);border-radius:12px;box-shadow:0 8px 28px rgba(0,0,0,.18);padding:10px 12px 12px}
+.dse-maskBtnOn{color:var(--dsw-alias-label-error)}
+.dse-envNameDim{opacity:.55;text-decoration:line-through}
 .dse-popHead{align-items:center;gap:8px;display:flex;padding:2px 0 8px}
 .dse-popTitle{color:var(--dsw-alias-label-primary);font-size:13px;font-weight:600;flex:1;margin:0}
 .dse-popHint{color:var(--dsw-alias-label-tertiary);font-size:12px;line-height:1.5;margin:0 0 8px}
-.dse-popList{flex-direction:column;display:flex;max-height:220px;overflow:auto;margin:0 -4px;padding:0 4px}
+.dse-popList{flex-direction:column;display:flex;margin:0 -4px;padding:0 4px}
 .dse-popList .dse-row{background:0 0;border-radius:8px;padding:8px 8px}
 .dse-popList .dse-row+.dse-row{border-top:1px solid var(--dsw-alias-border-l2)}
 .dse-popForm{border-top:1px solid var(--dsw-alias-border-l2);margin-top:8px;padding-top:4px}
 .dse-foot{justify-content:flex-end;gap:8px;display:flex;padding-top:8px}
+.dse-formGrid{display:grid;grid-template-columns:1fr 1fr;gap:0 16px}
 /* $ 触发补全菜单（仿官方 input-trigger MenuView 的浮层语言） */
 .dse-menuWrap{position:relative}
 .dse-menu{position:absolute;bottom:calc(100% + 6px);left:8px;z-index:60;min-width:280px;max-width:min(420px,calc(100vw - 32px));max-height:320px;overflow:auto;background:var(--dsw-alias-bg-layer-2);border:1px solid var(--dsw-alias-border-l2);border-radius:12px;box-shadow:0 8px 28px rgba(0,0,0,.18);padding:4px}
@@ -67,11 +66,9 @@ const EXTRA = `
 .dse-row{flex-wrap:wrap;padding:12px 12px}
 .dse-rowMain{flex-basis:100%}
 .dse-badges{margin-left:auto}
-.dse-pop{position:fixed;left:8px;right:8px;bottom:8px;top:auto;width:auto;max-width:none;max-height:70vh;overflow:auto}
-.dse-chip{min-height:32px}
+.dse-panelCard{position:fixed;left:8px;right:8px;bottom:8px;top:auto;max-height:70vh}
 }
 @media (pointer:coarse){
-.dse-chip{min-height:32px}
 .dse-iconBtn{min-width:44px;min-height:44px;align-items:center;justify-content:center}
 }
 `

package/src/config.ts

@@ -22,6 +22,10 @@ const SecretMetaSchema: any = z.object({
 
 export const Config = z.object({
   secrets: z.array(SecretMetaSchema).description('全局密钥元数据索引（值存凭据库）').default([]),
+  masked: z
+    .array(z.string())
+    .description('全局屏蔽的变量名后缀（继承变量等；注入时跳过）')
+    .default([]),
 })
 
 export type SecretEnvConfig = Schemastery.TypeT<typeof Config>

package/src/contributors.ts

@@ -0,0 +1,115 @@
+/**
+ * shell-env contributor 登记簿（从 service 拆出，规约模块规模）：
+ * 受管与继承两条线共用一张表，注册表要求一键一主——受管注册前
+ * 同名继承 contributor 先让位；继承只在「宿主环境有该名且未被索引」时存在。
+ * 所有屏蔽判定都下沉到 resolve 回调（由 service 注入），登记簿只管生命周期。
+ * @module secret-env/contributors
+ */
+import type { ToolExecution } from '@deepseek-ai/dsh-tools'
+
+import { SecretEnvError } from './errors.ts'
+import { envNameOf } from './names.ts'
+
+/** 受管键（结构等价 dsh-shell 的 DshEnvironmentKey，避免仅为类型多挂一个依赖）。 */
+type ManagedKey = `DSH_${string}`
+
+/** dsh-shell-env 注册面的结构子集。 */
+export interface ShellEnvLike {
+  register(spec: {
+    name: string
+    variables: Readonly<Record<string, { description: string }>>
+    resolve(execution: ToolExecution): Readonly<Record<string, string>>
+  }): () => void
+}
+
+export interface ContributorBookDeps {
+  readonly shellEnv: ShellEnvLike
+  /** 受管变量描述（注册表拒绝空描述，调用方已做回落）。 */
+  describeManaged(suffix: string): string
+  /** 受管值解析：undefined = 本次执行不设置。 */
+  resolveManaged(suffix: string, execution: ToolExecution): string | undefined
+  /** 继承 contributor 是否应存在（宿主环境有该名且未被索引）。 */
+  shouldForwardInherited(suffix: string): boolean
+  /** 继承值解析（屏蔽名单在此生效）：undefined/空串 = 不设置。 */
+  resolveInherited(suffix: string, execution: ToolExecution): string | undefined
+}
+
+export class ContributorBook {
+  private readonly managed = new Map<string, () => void>()
+  private readonly inherited = new Map<string, () => void>()
+  private readonly deps: ContributorBookDeps
+
+  constructor(deps: ContributorBookDeps) {
+    this.deps = deps
+  }
+
+  /** 受管登记：有任一来源值则注册，否则注销。 */
+  syncManaged(suffix: string, hasValue: boolean): void {
+    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: string): void {
+    const envName = envNameOf(suffix)
+    const registered = this.inherited.get(envName)
+    if (this.deps.shouldForwardInherited(suffix) && registered === undefined) {
+      const dispose = this.deps.shellEnv.register({
+        name: `secret-env-inherited:${suffix}`,
+        variables: { [envName as ManagedKey]: { description: 'inherited variable' } },
+        resolve: (execution: ToolExecution) => {
+          const value = this.deps.resolveInherited(suffix, execution)
+          return value === undefined || value === '' ? {} : { [envName as ManagedKey]: value }
+        },
+      })
+      this.inherited.set(envName, dispose)
+      return
+    }
+    if (!this.deps.shouldForwardInherited(suffix) && registered !== undefined) {
+      registered()
+      this.inherited.delete(envName)
+    }
+  }
+
+  private registerManaged(suffix: string, envName: string): void {
+    // 同名继承 contributor 先让位（一键一主），受管接管该变量。
+    const inherited = this.inherited.get(envName)
+    if (inherited !== undefined) {
+      inherited()
+      this.inherited.delete(envName)
+    }
+    try {
+      const dispose = this.deps.shellEnv.register({
+        name: `secret-env:${suffix}`,
+        variables: { [envName as ManagedKey]: { description: this.deps.describeManaged(suffix) } },
+        resolve: (execution: ToolExecution) => {
+          const value = this.deps.resolveManaged(suffix, execution)
+          return value === undefined ? {} : { [envName as ManagedKey]: 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(): void {
+    for (const dispose of this.managed.values()) dispose()
+    this.managed.clear()
+    for (const dispose of this.inherited.values()) dispose()
+    this.inherited.clear()
+  }
+}

package/src/index.ts

@@ -2,7 +2,7 @@
  * dsh-plus secret-env 插件（node 半）。浏览器半见 src/client/client.ts，
  * 经 ./client 导出 + tsdown 构建，由 dsh-client-modules 扫描进 __DSH_BOOT__。
  *
- * 挂载即得：密钥以 $DSH_SECRET_* 变量名向 agent 暴露（dsh-shell-env 执行期
+ * 挂载即得：密钥以 $DSH_VAR_* 变量名向 agent 暴露（dsh-shell-env 执行期
  * 注入，与内建变量同一通道）；值经 dsh-credentials seam 或会话内存持有，
  * 不进消息流、不动 prompt 前缀（缓存率零影响）。不新增工具与提示词——
  * 模型经 bash 原生能力（env | grep ^DSH_）发现变量名。

package/src/inventory.ts

@@ -0,0 +1,101 @@
+/**
+ * 索引解析与端点线型（从 service 拆出，规约模块规模；纯函数+DTO，零依赖）。
+ * @module secret-env/inventory
+ */
+
+import type { SecretMeta } from './config.ts'
+import { envNameOf, suffixOf } from './names.ts'
+
+/** 一条会话级密钥（内存态；once = 首次注入后自毁）。 */
+export interface SessionSecret {
+  value: string
+  description: string
+  once: boolean
+  createdAt: string
+}
+
+/** 列表端点的全局条目（describe 视图，绝无值）。 */
+export interface GlobalEntry {
+  name: string
+  envName: string
+  description: string
+  configured: boolean
+  source?: string
+  writable: boolean
+  /** 会话视图：该变量在本会话被屏蔽（无 sessionId 的调用恒为 false）。 */
+  masked: boolean
+}
+
+/** 列表端点的会话条目。 */
+export interface SessionEntry {
+  name: string
+  envName: string
+  description: string
+  once: boolean
+  createdAt: string
+}
+
+/**
+ * 列表端点的继承条目：宿主进程环境里已存在的 DSH_VAR_* 变量
+ * （非本插件索引管理；默认纳入注入）。masked = 生效屏蔽态，
+ * globallyMasked = 是否由全局屏蔽导致（会话视图里据此禁用会话级开关）。
+ */
+export interface InheritedEntry {
+  name: string
+  envName: string
+  masked: boolean
+  globallyMasked: boolean
+}
+
+/** 从索引数据解析全局密钥元数据列表（宽容过滤非法项）。 */
+export function asMeta(value: unknown): SecretMeta[] {
+  if (value === undefined || value === null || typeof value !== 'object') return []
+  const list = (value as { secrets?: unknown }).secrets
+  if (!Array.isArray(list)) return []
+  return list
+    .filter((item): item is Record<string, unknown> => typeof item === 'object' && item !== null)
+    .map((item) => ({
+      name: typeof item.name === 'string' ? item.name : '',
+      description: typeof item.description === 'string' ? item.description : '',
+      createdAt: typeof item.createdAt === 'string' ? item.createdAt : '',
+    }))
+    .filter((item) => item.name.length > 0)
+}
+
+/** 从同一索引数据解析全局屏蔽名单（与 secrets 共一个 settings 命名空间）。 */
+export function asMasked(value: unknown): string[] {
+  if (value === undefined || value === null || typeof value !== 'object') return []
+  const list = (value as { masked?: unknown }).masked
+  if (!Array.isArray(list)) return []
+  return list.filter((item): item is string => typeof item === 'string' && item.length > 0)
+}
+
+/** 继承变量后缀：给定进程环境里的 DSH_VAR_* 且不在索引内（按名排序）。 */
+export function inheritedSuffixesOf(
+  env: Record<string, string | undefined>,
+  indexed: ReadonlySet<string>,
+): string[] {
+  const found: string[] = []
+  for (const key of Object.keys(env)) {
+    const suffix = suffixOf(key)
+    if (suffix !== undefined && !indexed.has(suffix)) found.push(suffix)
+  }
+  return found.sort()
+}
+
+/** 拼装继承条目列表（list 端点的 inherited 段）。 */
+export function inheritedEntriesOf(
+  suffixes: readonly string[],
+  globalMasked: ReadonlySet<string>,
+  sessionMask: ReadonlySet<string> | undefined,
+): InheritedEntry[] {
+  return suffixes.map((name) => {
+    const globally = globalMasked.has(name)
+    return {
+      name,
+      envName: envNameOf(name),
+      masked: globally || sessionMask?.has(name) === true,
+      globallyMasked: globally,
+    }
+  })
+}

package/src/names.ts

@@ -1,13 +1,13 @@
 /**
  * 变量名语法（纯函数，零依赖；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_* 受管命名空间）。 */
-export const ENV_PREFIX = 'DSH_SECRET_'
+export const ENV_PREFIX = 'DSH_VAR_'
 
 /** 后缀语法：POSIX 环境变量名，大写字母开头，总长（含前缀）不超过 79。 */
 const SUFFIX_PATTERN = /^[A-Z][A-Z0-9_]*$/

package/src/service.ts

@@ -3,8 +3,12 @@
  * - 全局臂：值经 dsh-credentials seam 持久（$DSH_HOME/.credentials.yaml），
  *   服务内存中维护同步镜像（contributor.resolve 是同步签名，无法现查异步 seam）；
  * - 会话臂：Map<SessionId, Map<后缀, 值>> 纯内存，session/disposed 清除；
- * - 注入臂：每个变量名一个 dsh-shell-env contributor，每次 shell 执行由
- *   注册表 collect 现取——写入/删除下一条命令即生效，不进消息流、不动前缀。
+ * - 屏蔽臂：全局屏蔽名单持久于 settings（继承变量主要开关），
+ *   会话级屏蔽纯内存；两级都在 contributor resolve 时现判；
+ * - 注入臂：每个变量名一个 dsh-shell-env contributor（ContributorBook），
+ *   每次 shell 执行由注册表 collect 现取——写入/删除/屏蔽下一条命令即生效，
+ *   不进消息流、不动前缀。继承变量（宿主环境 DSH_VAR_*）平台默认剥离，
+ *   本服务按「默认纳入」逐一转发，可被屏蔽名单拦截。
  *
  * 红线：值只流经「端点 → 本服务 → dshEnv」，任何日志/事件/返回值不带值。
  * @module secret-env/service
@@ -18,40 +22,21 @@ import type { ToolExecution } from '@deepseek-ai/dsh-tools'
 
 import { registerSecretEnvApi } from './api.ts'
 import { Config, type SecretEnvConfig, type SecretMeta } from './config.ts'
+import { ContributorBook } from './contributors.ts'
 import { SecretEnvError } from './errors.ts'
+import {
+  asMasked,
+  asMeta,
+  type GlobalEntry,
+  type InheritedEntry,
+  inheritedEntriesOf,
+  inheritedSuffixesOf,
+  type SessionEntry,
+  type SessionSecret,
+} from './inventory.ts'
 import { envNameOf, suffixOf } from './names.ts'
 import { SETTINGS_NS } from './ns.ts'
 
-/** 受管键（结构等价 dsh-shell 的 DshEnvironmentKey，避免仅为类型多挂一个依赖）。 */
-type ManagedKey = `DSH_${string}`
-
-/** 一条会话级密钥（内存态；once = 首次注入后自毁）。 */
-export interface SessionSecret {
-  value: string
-  description: string
-  once: boolean
-  createdAt: string
-}
-
-/** 列表端点的全局条目（describe 视图，绝无值）。 */
-export interface GlobalEntry {
-  name: string
-  envName: string
-  description: string
-  configured: boolean
-  source?: string
-  writable: boolean
-}
-
-/** 列表端点的会话条目。 */
-export interface SessionEntry {
-  name: string
-  envName: string
-  description: string
-  once: boolean
-  createdAt: string
-}
-
 interface SettingsLike {
   get(ns: string): unknown
   update(ns: string, patch: Record<string, unknown>): Promise<void>
@@ -64,20 +49,6 @@ interface SettingsLike {
   ): void
 }
 
-function asMeta(value: unknown): SecretMeta[] {
-  if (value === undefined || value === null || typeof value !== 'object') return []
-  const list = (value as { secrets?: unknown }).secrets
-  if (!Array.isArray(list)) return []
-  return list
-    .filter((item): item is Record<string, unknown> => typeof item === 'object' && item !== null)
-    .map((item) => ({
-      name: typeof item.name === 'string' ? item.name : '',
-      description: typeof item.description === 'string' ? item.description : '',
-      createdAt: typeof item.createdAt === 'string' ? item.createdAt : '',
-    }))
-    .filter((item) => item.name.length > 0)
-}
-
 export class SecretEnvService extends Service {
   static [Context.inject] = ['credentials', 'shellEnv']
 
@@ -85,8 +56,10 @@ export class SecretEnvService extends Service {
   private readonly globalMirror = new Map<string, string>()
   /** 会话桶：sessionId → 后缀 → 条目。 */
   private readonly buckets = new Map<string, Map<string, SessionSecret>>()
-  /** 变量名 → contributor 注销器（shell-env 要求一键一主）。 */
-  private readonly contributors = new Map<string, () => void>()
+  /** 会话级屏蔽名单：sessionId → 后缀集合（纯内存，随会话终结清除）。 */
+  private readonly sessionMasks = new Map<string, Set<string>>()
+  /** contributor 登记簿（受管/继承两条线，一键一主）。 */
+  private readonly book: ContributorBook
   /** 行级 config（settings 缺席时的索引来源）。 */
   private readonly base: SecretEnvConfig
   /** installSection 给的实时 getter（scope.get 的活视图，读即最新，无时序竞态）。 */
@@ -99,7 +72,26 @@ export class SecretEnvService extends Service {
 
   constructor(ctx: Context, config: SecretEnvConfig | undefined) {
     super(ctx, 'secretEnv')
-    this.base = config ?? { secrets: [] }
+    this.base = config ?? { secrets: [], masked: [] }
+    this.book = new ContributorBook({
+      shellEnv: ctx.shellEnv,
+      describeManaged: (suffix) => {
+        // 注册表拒绝空描述（"must describe"）；空白描述回落为通用文案。
+        const found = this.currentMeta().find((item) => item.name === suffix)?.description
+        return found !== undefined && found.trim() !== '' ? found : 'secret variable'
+      },
+      resolveManaged: (suffix, execution) => this.resolveFor(suffix, execution),
+      shouldForwardInherited: (suffix) =>
+        process.env[envNameOf(suffix)] !== undefined && !this.isIndexed(suffix),
+      resolveInherited: (suffix, execution) => {
+        if (this.currentMasked().has(suffix)) return undefined
+        const agentId = execution.agent?.id
+        if (agentId !== undefined && this.sessionMasks.get(String(agentId))?.has(suffix) === true) {
+          return undefined
+        }
+        return process.env[envNameOf(suffix)]
+      },
+    })
     // 官方 installSection 范式（同 usage-panel）：setSource 收到的是
     // () => scope.get() 活视图——索引读取永远走 currentMeta() 现取，
     // onChange 仅触发差量调和，因此用户层加载早晚都不会被写覆盖。
@@ -117,6 +109,7 @@ export class SecretEnvService extends Service {
       void this.reconcile()
     })
     ctx.root.on('session/disposed', (session: { id: string }) => {
+      this.sessionMasks.delete(session.id)
       this.dropBucket(session.id)
     })
     ctx.on('credentials/reference-updated', (ref) => {
@@ -127,6 +120,10 @@ export class SecretEnvService extends Service {
     ctx.inject(['webServer'], (webCtx) => {
       registerSecretEnvApi(webCtx as Context, this)
     })
+    // 继承变量启动登记（平台默认剥离宿主 DSH_*，本插件显式 opt-in 转发）。
+    for (const suffix of this.inheritedSuffixes()) {
+      this.book.syncInherited(suffix)
+    }
     this.ready = this.reconcile()
   }
 
@@ -135,12 +132,22 @@ export class SecretEnvService extends Service {
     return asMeta(this.readIndex !== undefined ? this.readIndex() : this.base)
   }
 
+  /** 当前全局屏蔽名单（与索引同源，活读取）。 */
+  private currentMasked(): Set<string> {
+    return new Set(asMasked(this.readIndex !== undefined ? this.readIndex() : this.base))
+  }
+
+  /** 继承变量后缀：宿主进程环境里已存在的 DSH_VAR_* 且不在本插件索引内。 */
+  private inheritedSuffixes(): string[] {
+    return inheritedSuffixesOf(process.env, new Set(this.currentMeta().map((item) => item.name)))
+  }
+
   /** 索引成员判定（索引是全局名管理面的唯一事实源）。 */
   private isIndexed(suffix: string): boolean {
     return this.currentMeta().some((item) => item.name === suffix)
   }
 
-  /** 索引差量调和：新名建镜像，移出名撤镜像并回收其独占的 contributor。 */
+  /** 索引差量调和：新名建镜像，移出名撤镜像并回落继承登记（若宿主仍有同名）。 */
   private async reconcile(): Promise<void> {
     const next = this.currentMeta()
     const removed = this.lastMeta.filter((item) => !next.some((n) => n.name === item.name))
@@ -149,6 +156,7 @@ export class SecretEnvService 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)
@@ -166,9 +174,8 @@ export class SecretEnvService extends Service {
     this.syncContributor(suffix)
   }
 
-  /** contributor 登记簿：有任一来源（全局镜像或任一会话桶）则注册，否则注销。 */
+  /** 受管登记簿同步：有任一来源（全局镜像或任一会话桶）则注册，否则注销。 */
   private syncContributor(suffix: string): void {
-    const envName = envNameOf(suffix)
     const hasGlobal = this.globalMirror.has(suffix)
     let hasSession = false
     for (const bucket of this.buckets.values()) {
@@ -177,45 +184,18 @@ export class SecretEnvService extends Service {
         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)
-    }
-  }
-
-  private registerContributor(suffix: string, envName: string): void {
-    // 注册表拒绝空描述（"must describe"）；空白描述回落为通用文案。
-    const found = this.currentMeta().find((item) => item.name === suffix)?.description
-    const description = found !== undefined && found.trim() !== '' ? found : 'secret variable'
-    try {
-      const dispose = this.ctx.shellEnv.register({
-        name: `secret-env:${suffix}`,
-        variables: { [envName as ManagedKey]: { description } },
-        resolve: (execution: ToolExecution) => {
-          const value = this.resolveFor(suffix, execution)
-          return value === undefined ? {} : { [envName as ManagedKey]: 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)
-        }`,
-      )
-    }
+    this.book.syncManaged(suffix, hasGlobal || hasSession)
   }
 
-  /** 注入解析：会话值优先，未命中回落全局镜像；once 命中即焚（注销推迟到微任务，避免 collect 迭代中改注册表）。 */
+  /**
+   * 受管注入解析：会话屏蔽名单优先（任何来源都拦），会话值次之，全局屏蔽再次，
+   * 未命中回落全局镜像；once 命中即焚（注销推迟到微任务，避免 collect 迭代中改登记簿）。
+   */
   private resolveFor(suffix: string, execution: ToolExecution): string | undefined {
     const sessionId = execution.agent?.id
-    const bucket = sessionId === undefined ? undefined : this.buckets.get(String(sessionId))
+    const sid = sessionId === undefined ? undefined : String(sessionId)
+    if (sid !== undefined && this.sessionMasks.get(sid)?.has(suffix) === true) return undefined
+    const bucket = sid === undefined ? undefined : this.buckets.get(sid)
     const entry = bucket?.get(suffix)
     if (entry !== undefined) {
       if (entry.once && bucket !== undefined) {
@@ -224,6 +204,7 @@ export class SecretEnvService extends Service {
       }
       return entry.value
     }
+    if (this.currentMasked().has(suffix)) return undefined
     return this.globalMirror.get(suffix)
   }
 
@@ -243,7 +224,12 @@ export class SecretEnvService extends Service {
   }
 
   /** 列表（值永不出现；global 条目来自 credentials.describe 的安全视图）。 */
-  async list(sessionId?: string): Promise<{ global: GlobalEntry[]; session: SessionEntry[] }> {
+  async list(sessionId?: string): Promise<{
+    global: GlobalEntry[]
+    session: SessionEntry[]
+    inherited: InheritedEntry[]
+  }> {
+    const sessionMask = sessionId === undefined ? undefined : this.sessionMasks.get(sessionId)
     const global = await Promise.all(
       this.currentMeta().map(async (item) => {
         const info: CredentialInfo = await this.ctx.credentials.describe(
@@ -256,6 +242,7 @@ export class SecretEnvService extends Service {
           configured: info.configured,
           source: info.source,
           writable: info.writable,
+          masked: sessionMask?.has(item.name) === true,
         }
       }),
     )
@@ -267,7 +254,35 @@ export class SecretEnvService extends Service {
       once: entry.once,
       createdAt: entry.createdAt,
     }))
-    return { global, session }
+    return {
+      global,
+      session,
+      inherited: inheritedEntriesOf(this.inheritedSuffixes(), this.currentMasked(), sessionMask),
+    }
+  }
+
+  /**
+   * 屏蔽/恢复一个变量：sessionId 缺席时为全局屏蔽（持久于 settings，
+   * 主要面向继承变量）；否则为会话级屏蔽（纯内存，会话终结即清）。
+   * 两级屏蔽都在 contributor resolve 时现判，下一条命令即生效。
+   */
+  async setMask(suffix: string, masked: boolean, sessionId?: string): Promise<void> {
+    if (sessionId !== undefined) {
+      if (sessionId.length === 0) throw new SecretEnvError('no-session', 'sessionId required')
+      const set = this.sessionMasks.get(sessionId) ?? new Set<string>()
+      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 !== undefined ? this.readIndex() : this.base).filter(
+      (item) => item !== suffix,
+    )
+    if (masked) next.push(suffix)
+    if (this.settingsRef !== undefined) {
+      await this.settingsRef.update(SETTINGS_NS, { masked: next })
+    }
   }
 
   /** 写入全局值（seam 拒绝继承环境遮蔽与空值，此处先行给出结构化错误）。 */
@@ -289,7 +304,7 @@ export class SecretEnvService extends Service {
     await this.refreshMirror(suffix)
   }
 
-  /** 删除全局值与元数据。 */
+  /** 删除全局值与元数据；宿主环境仍有同名变量时回落为继承变量继续纳入。 */
   async unsetGlobal(suffix: string): Promise<void> {
     await this.ctx.credentials.unset(credentialRef(envNameOf(suffix)))
     const next = this.currentMeta().filter((item) => item.name !== suffix)
@@ -297,6 +312,7 @@ export class SecretEnvService extends Service {
     this.lastMeta = next
     this.globalMirror.delete(suffix)
     this.syncContributor(suffix)
+    this.book.syncInherited(suffix)
   }
 
   /** 写入会话级值（纯内存；host 重启或会话终结即失）。 */
@@ -324,9 +340,6 @@ export class SecretEnvService extends Service {
   }
 
   dispose(): void {
-    for (const disposeContributor of this.contributors.values()) {
-      disposeContributor()
-    }
-    this.contributors.clear()
+    this.book.dispose()
   }
 }