@dsh-plus/secret-env 0.1.0

package/src/client/i18n.ts

@@ -0,0 +1,112 @@
+/**
+ * 浏览器半文案（zh/en）。公共键来自 shared common，本文件只维护业务键。
+ * @module secret-env/client/i18n
+ */
+import { commonEn, commonZh, mergeDict } from '@dsh-plus/shared/client'
+
+export const NS = 'dsh-plus-secret-env'
+
+const ownZh = {
+  nav: '密钥变量',
+  title: '密钥变量',
+  description:
+    '以 $DSH_SECRET_* 变量名向 agent 暴露密钥：值在每次 shell 调用时由宿主注入，不进入对话记录与提示词，不影响上下文缓存。',
+  // 设置页（全局）
+  globalList: '全局密钥',
+  colName: '变量名（模型可见）',
+  colDescription: '描述',
+  colState: '状态',
+  colActions: '操作',
+  configured: '已配置',
+  unconfigured: '未配置',
+  readonly: '只读来源',
+  addGlobal: '添加全局密钥',
+  nameLabel: '变量名后缀',
+  nameHint: '大写字母/数字/下划线，如 GITHUB_TOKEN；模型实际使用 $DSH_SECRET_ 前缀拼接后的完整名。',
+  valueLabel: '值',
+  valueHint: '写入后不可回读；保存于宿主凭据库，不进入对话。',
+  descLabel: '描述（可选）',
+  descHint: '仅人读备注，不进提示词。',
+  save: '保存',
+  saving: '保存中…',
+  delete: '删除',
+  deleteConfirm: '确认删除 {name}？该变量将立即对后续命令失效。',
+  copy: '复制变量名',
+  copied: '已复制',
+  emptyGlobal: '暂无全局密钥。添加后 agent 即可通过变量名引用。',
+  loadFailed: '加载失败，请稍后重试。',
+  retry: '重试',
+  // 会话注入控件
+  sessionSecrets: '会话密钥',
+  sessionEmpty: '本会话暂无有默认值的密钥。',
+  sessionHint: '仅当前会话的 shell 命令可用；会话结束或一次性使用即失效。',
+  addSession: '添加会话密钥',
+  onceLabel: '一次性（首次使用后销毁）',
+  close: '关闭',
+  refresh: '刷新',
+  scopeGlobal: '全局',
+  scopeSession: '会话',
+  scopeOnce: '一次性',
+  // 错误码
+  'error.invalid-name': '变量名不合法：大写字母开头，仅字母/数字/下划线，≤64 字符。',
+  'error.empty-value': '值不能为空。',
+  'error.shadowed': '进程环境中已存在同名变量且优先级更高，写入无效；请先取消该环境变量。',
+  'error.conflict': '变量名与其他插件注册的受管变量冲突。',
+  'error.no-session': '缺少会话标识，请刷新后重试。',
+  'error.method': '请求方法不允许。',
+  'error.internal': '服务内部错误，请查看宿主日志。',
+}
+
+const ownEn = {
+  nav: 'Secret Variables',
+  title: 'Secret Variables',
+  description:
+    'Expose secrets to the agent as $DSH_SECRET_* variables: values are injected by the host into each shell call, never enter the transcript or prompt, and do not affect context caching.',
+  globalList: 'Global secrets',
+  colName: 'Variable (model-visible)',
+  colDescription: 'Description',
+  colState: 'State',
+  colActions: 'Actions',
+  configured: 'Configured',
+  unconfigured: 'Not configured',
+  readonly: 'Read-only source',
+  addGlobal: 'Add global secret',
+  nameLabel: 'Name suffix',
+  nameHint:
+    'Uppercase letters/digits/underscore, e.g. GITHUB_TOKEN; the model uses the full name with the $DSH_SECRET_ prefix.',
+  valueLabel: 'Value',
+  valueHint: 'Write-only after saving; stored in the host credential store, never in chat.',
+  descLabel: 'Description (optional)',
+  descHint: 'Human-readable note only; never enters prompts.',
+  save: 'Save',
+  saving: 'Saving…',
+  delete: 'Delete',
+  deleteConfirm: 'Delete {name}? The variable stops working for subsequent commands immediately.',
+  copy: 'Copy variable name',
+  copied: 'Copied',
+  emptyGlobal: 'No global secrets yet. Once added, the agent can reference them by name.',
+  loadFailed: 'Failed to load. Try again later.',
+  retry: 'Retry',
+  sessionSecrets: 'Session secrets',
+  sessionEmpty: 'No session secrets yet.',
+  sessionHint:
+    'Available to shell commands of this session only; expires when the session ends or after one use.',
+  addSession: 'Add session secret',
+  onceLabel: 'One-time (destroyed after first use)',
+  close: 'Close',
+  refresh: 'Refresh',
+  scopeGlobal: 'global',
+  scopeSession: 'session',
+  scopeOnce: 'once',
+  'error.invalid-name':
+    'Invalid name: start with an uppercase letter; letters/digits/underscore only, ≤64 chars.',
+  'error.empty-value': 'Value must not be empty.',
+  'error.shadowed': 'A same-named process environment variable shadows this write; unset it first.',
+  'error.conflict': 'The variable conflicts with a managed variable registered by another plugin.',
+  'error.no-session': 'Missing session id; refresh and retry.',
+  'error.method': 'Method not allowed.',
+  'error.internal': 'Internal error; check the host log.',
+}
+
+export const zh: Record<string, string> = mergeDict(commonZh, ownZh)
+export const en: Record<string, string> = mergeDict(commonEn, ownEn)

package/src/client/section.tsx

@@ -0,0 +1,258 @@
+/**
+ * 密钥变量设置页（settings.section 官方插槽）：全局密钥的列表与增删。
+ * 只展示元数据与模型可见的完整变量名——值写入后不可回读（端点不出值）。
+ * 响应式：≤767px 行转堆叠卡、表单转单列。
+ * @module secret-env/client/section
+ */
+import { type ReactElement, useEffect, useRef, useState } from 'react'
+
+import { ApiError, fetchSecrets, type SecretList, setGlobal, unsetGlobal } from './api.ts'
+import { copyText, errorText } from './common.ts'
+
+export interface SectionProps {
+  t(key: string): string
+}
+
+interface FormState {
+  name: string
+  value: string
+  description: string
+}
+
+const EMPTY_FORM: FormState = { name: '', value: '', description: '' }
+
+/** 单行：完整变量名（复制）+ 描述 + 状态徽标 + 两步删除。 */
+function GlobalRow(props: {
+  t: SectionProps['t']
+  entry: SecretList['global'][number]
+  onDeleted(): void
+  onError(text: string): void
+}): ReactElement {
+  const { t, entry } = props
+  const [confirming, setConfirming] = useState(false)
+  const [copied, setCopied] = useState(false)
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null)
+
+  useEffect(
+    () => () => {
+      if (timer.current !== null) clearTimeout(timer.current)
+    },
+    [],
+  )
+
+  const onCopy = (): void => {
+    void copyText(`$${entry.envName}`).then((ok) => {
+      if (!ok) return
+      setCopied(true)
+      if (timer.current !== null) clearTimeout(timer.current)
+      timer.current = setTimeout(() => setCopied(false), 1500)
+    })
+  }
+
+  const onDelete = (): void => {
+    unsetGlobal(entry.name)
+      .then(() => props.onDeleted())
+      .catch((error: unknown) => props.onError(errorText(t, error)))
+  }
+
+  return (
+    <div className="dse-row">
+      <div className="dse-rowMain">
+        <div className="dse-env">
+          <span className="dse-envName">${entry.envName}</span>
+          <button
+            type="button"
+            className="dse-iconBtn"
+            title={t('copy')}
+            aria-label={t('copy')}
+            onClick={onCopy}
+          >
+            {copied ? '✓' : '⧉'}
+          </button>
+        </div>
+        {entry.description !== '' ? <span className="dse-note">{entry.description}</span> : null}
+      </div>
+      <div className="dse-badges">
+        <span className={`dse-badge${entry.configured ? '' : ' dse-badgeDim'}`}>
+          {entry.configured ? t('configured') : t('unconfigured')}
+        </span>
+        {entry.writable ? null : (
+          <span className="dse-badge dse-badgeDim" title={entry.source ?? ''}>
+            {t('readonly')}
+          </span>
+        )}
+        {confirming ? (
+          <>
+            <button type="button" className="dse-btn dse-btnPrimary" onClick={onDelete}>
+              {t('delete')}
+            </button>
+            <button
+              type="button"
+              className="dse-btn dse-btnGhost"
+              onClick={() => setConfirming(false)}
+            >
+              {t('close')}
+            </button>
+          </>
+        ) : (
+          <button
+            type="button"
+            className="dse-iconBtn dse-delBtn"
+            title={t('delete')}
+            aria-label={t('delete')}
+            onClick={() => setConfirming(true)}
+          >
+            ✕
+          </button>
+        )}
+      </div>
+    </div>
+  )
+}
+
+export function SecretsSection(props: SectionProps): ReactElement {
+  const { t } = props
+  const [data, setData] = useState<SecretList | null>(null)
+  const [failed, setFailed] = useState(false)
+  const [form, setForm] = useState<FormState>(EMPTY_FORM)
+  const [saving, setSaving] = useState(false)
+  const [status, setStatus] = useState<{ kind: 'ok' | 'err'; text: string } | null>(null)
+
+  const load = (): void => {
+    fetchSecrets()
+      .then((list) => {
+        setData(list)
+        setFailed(false)
+      })
+      .catch(() => setFailed(true))
+  }
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: load 为闭包稳定函数（读端点后 setState），仅需首载一次
+  useEffect(() => {
+    load()
+  }, [])
+
+  const onSave = (): void => {
+    setSaving(true)
+    setStatus(null)
+    setGlobal(form.name, form.value, form.description)
+      .then(() => {
+        setForm(EMPTY_FORM)
+        setStatus({ kind: 'ok', text: t('configured') })
+        load()
+      })
+      .catch((error: unknown) => {
+        setStatus({
+          kind: 'err',
+          text: errorText(t, error instanceof ApiError ? error : new ApiError('internal')),
+        })
+      })
+      .finally(() => setSaving(false))
+  }
+
+  if (data === null) {
+    return (
+      <div className="dse-section">
+        <p className="dse-empty">{failed ? t('loadFailed') : '…'}</p>
+        {failed ? (
+          <button type="button" className="dse-btn dse-btnGhost" onClick={load}>
+            {t('retry')}
+          </button>
+        ) : null}
+      </div>
+    )
+  }
+
+  const canSave = form.name.trim() !== '' && form.value !== '' && !saving
+  return (
+    <div className="dse-section">
+      <header className="dse-head">
+        <h2 className="dse-title">{t('title')}</h2>
+        <p className="dse-desc">{t('description')}</p>
+      </header>
+
+      <h3 className="dse-groupLabel">{t('globalList')}</h3>
+      <div className="dse-rows">
+        {data.global.length === 0 ? (
+          <p className="dse-empty">{t('emptyGlobal')}</p>
+        ) : (
+          data.global.map((entry) => (
+            <GlobalRow
+              key={entry.name}
+              t={t}
+              entry={entry}
+              onDeleted={load}
+              onError={(text) => setStatus({ kind: 'err', text })}
+            />
+          ))
+        )}
+      </div>
+
+      <h3 className="dse-groupLabel">{t('addGlobal')}</h3>
+      <div className="dse-form">
+        <div className="dse-formGrid">
+          <div className="dse-field">
+            <div className="dse-head">
+              <label className="dse-label" htmlFor="dse-name">
+                {t('nameLabel')}
+              </label>
+            </div>
+            <input
+              id="dse-name"
+              className="dse-input"
+              value={form.name}
+              placeholder="GITHUB_TOKEN"
+              onChange={(event) => setForm({ ...form, name: event.target.value })}
+            />
+            <p className="dse-hint">{t('nameHint')}</p>
+          </div>
+          <div className="dse-field">
+            <div className="dse-head">
+              <label className="dse-label" htmlFor="dse-value">
+                {t('valueLabel')}
+              </label>
+            </div>
+            <input
+              id="dse-value"
+              className="dse-input"
+              type="password"
+              autoComplete="off"
+              value={form.value}
+              onChange={(event) => setForm({ ...form, value: event.target.value })}
+            />
+            <p className="dse-hint">{t('valueHint')}</p>
+          </div>
+        </div>
+        <div className="dse-field">
+          <div className="dse-head">
+            <label className="dse-label" htmlFor="dse-desc">
+              {t('descLabel')}
+            </label>
+          </div>
+          <input
+            id="dse-desc"
+            className="dse-input"
+            value={form.description}
+            onChange={(event) => setForm({ ...form, description: event.target.value })}
+          />
+          <p className="dse-hint">{t('descHint')}</p>
+        </div>
+        <div className="dse-foot">
+          {status !== null ? (
+            <p className={`dse-status${status.kind === 'err' ? ' dse-statusError' : ''}`}>
+              {status.text}
+            </p>
+          ) : null}
+          <button
+            type="button"
+            className="dse-btn dse-btnPrimary"
+            disabled={!canSave}
+            onClick={onSave}
+          >
+            {saving ? t('saving') : t('save')}
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/client/styles.ts

@@ -0,0 +1,68 @@
+/**
+ * 样式注入：shared cardCss('dse') 提供官方卡片/字段/按钮基件，
+ * extra 部分为本插件特有规则——设置页变量表（桌面网格、≤767px 堆叠）
+ * 与会话注入控件（官方 chip 胶囊 + popover，窄屏转底部抽屉）。
+ * @module secret-env/client/styles
+ */
+import { cardCss, injectCardStyle } from '@dsh-plus/shared/client'
+
+const EXTRA = `
+/* 设置页布局 */
+.dse-section{padding:0 0 24px}
+.dse-head{flex-direction:column;gap:6px;padding:16px 0 12px;display:flex}
+.dse-title{color:var(--dsw-alias-label-primary);font-size:18px;font-weight:600;margin:0;line-height:1.4}
+.dse-desc{color:var(--dsw-alias-label-tertiary);font-size:13px;margin:0;line-height:1.6}
+.dse-groupLabel{color:var(--dsw-alias-label-secondary);font-size:12px;font-weight:600;padding:14px 0 8px;margin:0}
+.dse-rows{flex-direction:column;display:flex;border:1px solid var(--dsw-alias-border-l2);border-radius:12px;overflow:hidden}
+.dse-row{align-items:center;gap:12px;padding:10px 14px;display:flex;background:var(--dsw-alias-bg-layer-3)}
+.dse-row+.dse-row{border-top:1px solid var(--dsw-alias-border-l2)}
+.dse-rowMain{flex-direction:column;gap:3px;flex:1;min-width:0;display:flex}
+.dse-env{align-items:center;gap:6px;display:flex;min-width:0}
+.dse-envName{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;color:var(--dsw-alias-label-primary);font-size:13px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.dse-note{color:var(--dsw-alias-label-tertiary);font-size:12px;line-height:1.5;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.dse-badges{align-items:center;gap:6px;flex:none;display:flex}
+.dse-badge{white-space:nowrap;border-radius:999px;padding:1px 8px;font-size:11px;font-weight:500;line-height:17px;background:var(--dsw-alias-bg-module-platform);color:var(--dsw-alias-label-secondary)}
+.dse-badgeDim{background:0 0;color:var(--dsw-alias-label-tertiary)}
+.dse-iconBtn{appearance:none;border:none;background:0 0;cursor:pointer;color:var(--dsw-alias-label-tertiary);border-radius:6px;padding:4px;display:inline-flex}
+.dse-iconBtn:hover{color:var(--dsw-alias-label-primary);background:var(--dsw-alias-interactive-bg-hover)}
+.dse-iconBtn:focus-visible{outline:2px solid var(--dsw-alias-brand-primary);outline-offset:1px}
+.dse-delBtn{color:var(--dsw-alias-label-tertiary)}
+.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-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 .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}
+/* 响应式：窄屏表格转堆叠，popover 转底部抽屉 */
+@media (max-width:767px){
+.dse-formGrid{grid-template-columns:1fr}
+.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}
+}
+@media (pointer:coarse){
+.dse-chip{min-height:32px}
+.dse-iconBtn{min-width:44px;min-height:44px;align-items:center;justify-content:center}
+}
+`
+
+/** 幂等注入本插件样式；返回新标签（卸载用），已存在或无 document 返回 null。 */
+export function injectSecretEnvStyle(pluginId: string): HTMLStyleElement | null {
+  return injectCardStyle(pluginId, cardCss('dse', EXTRA))
+}

package/src/config.ts

@@ -0,0 +1,34 @@
+/**
+ * 配置单一事实源：cordis 行级 Config（组合默认值）与 settings namespace
+ * （用户层，$DSH_HOME/settings.yaml 热生效）共用同一 schemastery schema。
+ * `secrets` 只是全局密钥的**元数据索引**（后缀/描述/创建时间），
+ * 值永远走 dsh-credentials seam（$DSH_HOME/.credentials.yaml），不进本文件。
+ * @module secret-env/config
+ */
+import z from '@deepseek-ai/schemastery'
+
+import { SETTINGS_NS as NS_LITERAL } from './ns.ts'
+
+/** settings 命名空间（字面量即合法命名空间，0.1.2-alpha.2 起编译期校验）。 */
+export const SETTINGS_NS = NS_LITERAL
+
+/** 一条全局密钥的元数据（值不在此处）。 */
+// biome-ignore lint/suspicious/noExplicitAny: dts 可移植性——嵌套 schema 的精确类型经 TypeT 消费，显式断掉 cosmokit 推断链
+const SecretMetaSchema: any = z.object({
+  name: z.string().min(1).description('变量名后缀（如 GITHUB_TOKEN）').default(''),
+  description: z.string().description('用途描述（仅人读，不进提示词）').default(''),
+  createdAt: z.string().description('创建时间 ISO').default(''),
+})
+
+export const Config = z.object({
+  secrets: z.array(SecretMetaSchema).description('全局密钥元数据索引（值存凭据库）').default([]),
+})
+
+export type SecretEnvConfig = Schemastery.TypeT<typeof Config>
+
+/** 一条元数据的运行时形态。 */
+export interface SecretMeta {
+  name: string
+  description: string
+  createdAt: string
+}

package/src/errors.ts

@@ -0,0 +1,12 @@
+/**
+ * 结构化错误（独立模块，避免 service ↔ api 循环依赖）。
+ * 端点映射为 HTTP 状态码 + 错误码，UI 按码给文案。
+ * @module secret-env/errors
+ */
+export class SecretEnvError extends Error {
+  readonly code: string
+  constructor(code: string, message: string) {
+    super(message)
+    this.code = code
+  }
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+/**
+ * dsh-plus secret-env 插件（node 半）。浏览器半见 src/client/client.ts，
+ * 经 ./client 导出 + tsdown 构建，由 dsh-client-modules 扫描进 __DSH_BOOT__。
+ *
+ * 挂载即得：密钥以 $DSH_SECRET_* 变量名向 agent 暴露（dsh-shell-env 执行期
+ * 注入，与内建变量同一通道）；值经 dsh-credentials seam 或会话内存持有，
+ * 不进消息流、不动 prompt 前缀（缓存率零影响）。不新增工具与提示词——
+ * 模型经 bash 原生能力（env | grep ^DSH_）发现变量名。
+ * @module @dsh-plus/secret-env
+ */
+import type { Context } from '@deepseek-ai/cordis'
+
+import { Config, type SecretEnvConfig } from './config.ts'
+import { SecretEnvService } from './service.ts'
+
+export const name = 'dsh-plus-secret-env'
+export const inject = ['credentials', 'shellEnv'] as const
+
+export { Config }
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    secretEnv: SecretEnvService
+  }
+}
+
+export function apply(ctx: Context, config?: SecretEnvConfig): void {
+  // config 由加载器按行级 Config schema 补默认后传入；服务内部完成端点挂载。
+  ctx.plugin(SecretEnvService, config)
+}
+
+export { SecretEnvError } from './errors.ts'
+export { SecretEnvService } from './service.ts'

package/src/names.ts

@@ -0,0 +1,45 @@
+/**
+ * 变量名语法（纯函数，零依赖；node 半与浏览器半共用）：
+ * 用户给出后缀（如 `GITHUB_TOKEN`），插件拼出完整受管变量名
+ * `DSH_SECRET_GITHUB_TOKEN`——即模型经 `env | grep ^DSH_` 可见、
+ * 在 shell 命令中以 `$DSH_SECRET_*` 引用的那个名字。
+ * @module secret-env/names
+ */
+
+/** 受管变量名前缀（属 dsh-shell-env 的 DSH_* 受管命名空间）。 */
+export const ENV_PREFIX = 'DSH_SECRET_'
+
+/** 后缀语法：POSIX 环境变量名，大写字母开头，总长（含前缀）不超过 79。 */
+const SUFFIX_PATTERN = /^[A-Z][A-Z0-9_]*$/
+const MAX_SUFFIX_LENGTH = 64
+
+/** 名称校验失败码（端点与 UI 共用的结构化错误）。 */
+export type NameError = 'empty' | 'bad-charset' | 'too-long'
+
+/** 规范化用户输入：去空白并转大写。 */
+export function normalizeSuffix(raw: string): string {
+  return raw.trim().toUpperCase()
+}
+
+/** 校验规范化后的后缀；合法返回 null，非法返回失败码。 */
+export function validateSuffix(suffix: string): NameError | null {
+  if (suffix.length === 0) return 'empty'
+  if (suffix.length > MAX_SUFFIX_LENGTH) return 'too-long'
+  if (!SUFFIX_PATTERN.test(suffix)) return 'bad-charset'
+  return null
+}
+
+/** 由后缀拼出完整受管变量名（调用方保证后缀已通过校验）。 */
+export function envNameOf(suffix: string): string {
+  return `${ENV_PREFIX}${suffix}`
+}
+
+/** 判断一个完整变量名是否属本插件管理（用于凭据热更事件过滤）。 */
+export function isManagedEnvName(envName: string): boolean {
+  return envName.startsWith(ENV_PREFIX) && envName.length > ENV_PREFIX.length
+}
+
+/** 由完整变量名反解后缀；非本插件名返回 undefined。 */
+export function suffixOf(envName: string): string | undefined {
+  return isManagedEnvName(envName) ? envName.slice(ENV_PREFIX.length) : undefined
+}

package/src/ns.ts

@@ -0,0 +1,6 @@
+/**
+ * settings 命名空间字面量（纯常量，零依赖，浏览器半可安全引入）。
+ * 服务端以字面量注册元数据索引，浏览器半作为 settings.section 页标识。
+ * @module secret-env/ns
+ */
+export const SETTINGS_NS = 'dsh-plus-secret-env'