@foperate/secret-env-dsh 0.0.0-stage → 0.3.2

package/README.md

@@ -1,3 +1,43 @@
-# Temporary Holding Version
+# @foperate/secret-env-dsh
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+secret-env 的 DeepSeek Harness（DSH）bundle：把密钥从私有库注入 bash 子进程环境，模型上下文永不见值。
+
+**独立包**：本包零依赖，不 import 主包代码；运行时经 PATH 上的全局 CLI `secret-env` 走宿主协议
+（`protocol 1`：`info` / `inject` / `store`，stdin/stdout JSON，值只经 stdin 且不回显）。
+
+## 安装
+
+```bash
+# 1) 全局 CLI（真身；注入、守卫、入库都在这里）
+bun add -g @foperate/secret-env        # 或 npm i -g @foperate/secret-env
+
+# 2) DSH bundle（本包；装进当前 profile）
+#    plugin_manager → action: install_bundle, target: @foperate/secret-env-dsh@<version>
+```
+
+skill 由 DSH 从 `~/.dsh/skills` 发现，指向本包的 `skills/secret-env`：
+
+```bash
+ln -sfn "$HOME/.dsh/profiles/<profile>/node_modules/@foperate/secret-env-dsh/skills/secret-env" \
+  "$HOME/.dsh/skills/secret-env"
+```
+
+安装或升级后重启 DSH（插件代码在启动时加载）。
+
+## 组成
+
+| 文件 | 作用 |
+|---|---|
+| `index.js` | 装配：`tools/execute` bash 注入、`tools.guard` 同步守卫、systemPrompt 清单、`add_secret` 工具 |
+| `client.mjs` | 协议客户端（`$SENV_BIN` → PATH `secret-env`），超时/退出码/非 JSON 转 `CliError` |
+| `guards.mjs` | 文件工具与 pwsh/terminal_send 的同步守卫（bash 守卫在 CLI 的 `inject` 里） |
+| `rules.mjs` | `scanRefs` 同步副本（与主包 `core.mjs` 同源，跨仓库测试校验） |
+| `entry.mjs` | DSH 专属文案与卡片答案判定 |
+| `cordis.patch.yml` | DSH bundle 补丁（插入 `@foperate/secret-env-dsh` 行） |
+| `skills/secret-env/` | skill 副本（与主包 `skills/secret-env` 逐字节一致） |
+
+## 兼容
+
+- 需要主包 CLI 支持 `protocol 1`（`secret-env info` 可验证）；协议不匹配时插件拒绝加载（宁可失败）。
+- 已知：`ctx.tools.guard` 同步回调限制决定了守卫不能走子进程；bash 守卫与注入统一在 CLI，
+  GUI 内文件/通道守卫在本包，`rules-sync` 测试保证两处判定同源。

package/client.mjs

@@ -0,0 +1,89 @@
+// DSH 适配器的 CLI 协议客户端（protocol 1）：只经子进程与主包交互，不 import 主包代码。
+// 契约：stdin 一行 JSON，stdout 一行 JSON；退出码 0 成功 / 2 业务拒绝（JSON 带 code）/ 3 协议不匹配。
+// 值只经 stdin 进入，响应不含值。协议见 docs/PLAN-DSH-DECOUPLING.md。
+import { spawn, spawnSync } from "node:child_process";
+
+export const PROTOCOL = 1;
+
+export class CliError extends Error {
+  constructor(message, { code = "cli", exit } = {}) {
+    super(message);
+    this.name = "CliError";
+    this.code = code;
+    this.exit = exit;
+  }
+}
+
+const MAX_STDERR = 200;
+
+// 统一解析：非 JSON / 非零退出都转成 CliError（宁可失败，不静默放行）
+function toJson(out, err, code, cmd) {
+  const text = (out ?? "").trim();
+  let json = null;
+  try { json = text ? JSON.parse(text) : null; } catch { json = null; }
+  if (json === null) {
+    throw new CliError(`secret-env ${cmd} 返回非 JSON（exit=${code}）${err ? `：${err.trim().slice(0, MAX_STDERR)}` : ""}`, { code: "bad-output", exit: code });
+  }
+  if (code !== 0) throw new CliError(json.error ?? `secret-env ${cmd} 失败（exit=${code}）`, { code: json.code ?? "cli", exit: code });
+  return json;
+}
+
+export function createClient({ bin = process.env.SENV_BIN || "secret-env", timeoutMs = 8000 } = {}) {
+  const hint = `请全局安装 @foperate/secret-env（bun add -g · npm i -g）并确认 ${bin} 在 PATH 上`;
+
+  function run(cmd, payload, { timeout = timeoutMs } = {}) {
+    return new Promise((resolve, reject) => {
+      let child;
+      try {
+        child = spawn(bin, [cmd], { stdio: ["pipe", "pipe", "pipe"] });
+      } catch (e) {
+        reject(new CliError(`无法启动 ${bin}：${e.message}——${hint}`, { code: "spawn" }));
+        return;
+      }
+      let out = "", err = "", done = false;
+      const timer = setTimeout(() => {
+        done = true;
+        child.kill("SIGKILL");
+        reject(new CliError(`secret-env ${cmd} 超时（${timeout}ms）`, { code: "timeout" }));
+      }, timeout);
+      const finish = (fn, value) => {
+        if (done) return;
+        done = true;
+        clearTimeout(timer);
+        fn(value);
+      };
+      child.on("error", (e) => finish(reject, new CliError(`无法启动 ${bin}（${e.code ?? e.message}）——${hint}`, { code: "spawn" })));
+      child.stdout.on("data", (d) => { out += d; });
+      child.stderr.on("data", (d) => { err += d; });
+      child.on("close", (code) => {
+        try { finish(resolve, toJson(out, err, code, cmd)); }
+        catch (e) { finish(reject, e); }
+      });
+      child.stdin.end(payload === null ? undefined : JSON.stringify({ protocol: PROTOCOL, ...payload }));
+    });
+  }
+
+  // 同步版只给 info 用：DSH 的 guard 是同步回调，插件启动时必须有快照才能判定。
+  function runSync(cmd) {
+    const r = spawnSync(bin, [cmd], { encoding: "utf8", timeout: timeoutMs });
+    if (r.error) throw new CliError(`无法启动 ${bin}（${r.error.code ?? r.error.message}）——${hint}`, { code: "spawn" });
+    return toJson(r.stdout ?? "", r.stderr ?? "", r.status ?? -1, cmd);
+  }
+
+  return {
+    bin,
+    info: () => run("info", null),
+    infoSync: () => runSync("info"),
+    inject: (payload) => run("inject", payload),
+    store: (payload) => run("store", payload),
+  };
+}
+
+// 版本握手：插件只认自己实现的协议版本
+export function requireProtocol(info) {
+  const got = info?.protocol;
+  if (got !== PROTOCOL) {
+    throw new CliError(`secret-env 协议版本不匹配：插件需要 ${PROTOCOL}，CLI 返回 ${got ?? "无"}（请把主包与插件升到匹配版本）`, { code: "protocol" });
+  }
+  return info;
+}

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+- insert:
+    - id: secret-env
+      name: '@foperate/secret-env-dsh'
+      config: {}

package/entry.mjs

@@ -0,0 +1,57 @@
+// DSH 登记条目的纯逻辑：消息/选项文案与答案解释。
+// 条目构造与终端兜底命令已下沉到 CLI 协议（store 的 ready / command 形态），本文件不 import 主包代码。
+// PROVIDERS 只用于文案与工具 schema 兜底：权威列表来自 info.providers（协议）。
+export const PROVIDERS = ["keychain", "bitwarden", "viking", "onepassword"];
+
+const lang = (() => {
+  const l = process.env.LC_ALL ?? process.env.LANG ?? "";
+  return l.toLowerCase().startsWith("zh") ? "zh" : "en";
+})();
+
+export const T = {
+  zh: {
+    toolDescription:
+      "会话内交互登记新凭据：元数据由本工具入参传入；密钥值由宿主问答卡片直接向用户收集并写入凭据库，永远不进入模型上下文——不要试图把密钥值作为参数传入，也不要让用户发给你。返回 status：stored=已入库 / command-issued=已给出终端命令 / declined=用户取消 / invalid=元数据有误 / error=执行失败。",
+    paramName: "人读名（如 github token），归一化为全大写下划线环境变量名",
+    paramProvider: "keychain（默认）/ bitwarden / viking / onepassword",
+    paramDetail: "条目定位：bitwarden/onepassword=条目名[/字段]；viking=类目/目标[/字段]；keychain 留空自动命名",
+    paramAlias: "别名（可选，逗号分隔）",
+    paramDescription: "描述（可选。会进入模型上下文，不得含敏感信息）",
+    cardHeader: "录入密钥值",
+    cardQuestion:
+      "secret-env 新条目登记：请选择密钥值录入方式。\n\n注意：这里提交的内容会原样写入凭据库、不经过模型，因此必须直接填写密钥本身——不要填名字、描述、占位符或「我的 token」之类的说明（模型无法校验或补全）。\n\n· 直接填写：在下方输入框填写密钥值——值明文显示在卡片中（介意旁观/录屏请改选命令行），提交后直接写入凭据库，不会进入模型上下文。\n· 命令行：选择「我希望通过命令行来完成输入」，我会给你一条在终端执行的命令（隐藏输入）。",
+    commandLabel: "我希望通过命令行来完成输入",
+    commandDescription: "随后给出一条 senv add 命令，在终端执行时隐藏输入密钥值。",
+    missingName: "缺少 name（归一化后为空）",
+    badProvider: `provider 只能是 ${PROVIDERS.join(" / ")}`,
+    exists: "已存在同名条目，请换名后重调（维护已有条目请在终端用 senv add 不带 --provider）",
+    noAgent: "无法定位调用方 agent，不能弹问答卡片",
+  },
+  en: {
+    toolDescription:
+      "Register a new credential interactively in this session: metadata comes from the tool arguments; the secret value is collected by the host's question card and written straight to the credential store — it never enters model context. Do not pass the secret value as an argument or ask the user to send it. Returns status: stored / command-issued / declined / invalid / error.",
+    paramName: "Human-readable name (e.g. github token); normalized to UPPER_SNAKE env var",
+    paramProvider: "keychain (default) / bitwarden / viking / onepassword",
+    paramDetail: "Entry locator: bitwarden/onepassword=item[/field]; viking=category/target[/field]; keychain=leave blank",
+    paramAlias: "Aliases (optional, comma-separated)",
+    paramDescription: "Description (optional; enters model context — no sensitive info)",
+    cardHeader: "Enter the secret value",
+    cardQuestion:
+      "secret-env new entry: choose how to enter the secret.\n\nNote: whatever is submitted here is written straight to the credential store without passing through the model, so it must be the secret value itself — not a name, description, placeholder, or note like \"my token\" (the model cannot validate or complete it).\n\n· Type it: fill the field below — the value is visible on the card (avoid if others can see your screen), and is written straight to the credential store without entering model context.\n· Command line: choose \"I'll enter it via the command line\" to get a command for your terminal (hidden input).",
+    commandLabel: "I'll enter it via the command line",
+    commandDescription: "Returns a senv add command that hides the input in your terminal.",
+    missingName: "Missing name (empty after normalization)",
+    badProvider: `provider must be one of ${PROVIDERS.join(" / ")}`,
+    exists: "An entry with this name already exists — pick another name (to maintain an existing entry run senv add without --provider)",
+    noAgent: "Cannot resolve the calling agent; the question card is unavailable",
+  },
+}[lang];
+
+// 单选问答：custom 覆盖 selected（DSH 语义）。返回 value / command / declined。
+export function interpretAnswer(item, commandLabel) {
+  const custom = typeof item?.custom === "string" ? item.custom.trim() : "";
+  if (custom !== "") return { kind: "value", value: custom };
+  const selected = Array.isArray(item?.selected) ? item.selected : [];
+  if (selected.includes(commandLabel)) return { kind: "command" };
+  return { kind: "declined" };
+}

package/guards.mjs

@@ -0,0 +1,83 @@
+// DSH 守卫判定（纯函数，供单测直接调用）：文件通道 + 无注入通道的拒绝；不做密钥解析。
+// 规则数据来自 CLI 的 info 快照（guardPaths）+ 本地 scanRefs 副本（同步判定，不 spawn 子进程）。
+// bash 的命令文本守卫由 CLI 的 inject 统一执行（三端同语义，2026-11-06）——这里只管
+// 文件工具（同步）与 pwsh/terminal_send（没有注入通道，必须在本地拦）。
+// 与 ZCode 的 guardPaths 同源：secrets.json（含 master 口令明文）/ vault.kdbx 对 agent 一律只读不可触。
+import { matchGuardPaths, scanRefs } from "./rules.mjs";
+
+const FILE_TOOLS = ["read", "read_image", "write", "edit"];
+const COMMAND_CHANNELS = new Map([
+  ["pwsh", "command"],
+  ["terminal_send", "text"],
+]);
+
+const protectedReason = (fragment) =>
+  `secret-env：操作涉及受保护文件（片段「${fragment}」）——secrets.json / vault.kdbx 含 master 口令明文与全部凭据映射，禁止 Agent 读写。配置维护请在终端运行 secret-env add/remove，或亲手编辑。`;
+
+// 返回拒绝理由（字符串）或 undefined（放行）。exec 形态见 DSH ToolDispatchExecution：{ name, arguments, callId, agent, signal }。
+// snapshot = { entries, guardPaths, config }，由 info 协议构建（见 index.js buildSnapshot）。
+export function evaluateCall(exec, snapshot) {
+  if (exec === null || typeof exec !== "object") return;
+  const name = exec.name;
+  if (typeof name !== "string" || name.length === 0) return;
+  const args = exec.arguments !== null && typeof exec.arguments === "object" ? exec.arguments : {};
+  const fragments = (snapshot?.guardPaths ?? []).filter((f) => typeof f === "string" && f.length > 0);
+
+  if (FILE_TOOLS.includes(name)) {
+    for (const key of ["file_path", "path"]) {
+      const fragment = matchGuardPaths(args[key], fragments);
+      if (fragment !== undefined) return protectedReason(fragment);
+    }
+    return;
+  }
+  if (name === "apply_patch") {
+    const fragment = matchGuardPaths(args.patch, fragments);
+    return fragment === undefined ? undefined : protectedReason(fragment);
+  }
+
+  const commandKey = COMMAND_CHANNELS.get(name);
+  if (commandKey === undefined) return;
+  const command = args[commandKey];
+  if (typeof command !== "string" || command.length === 0) return;
+
+  const fragment = matchGuardPaths(command, fragments);
+  if (fragment !== undefined) return protectedReason(fragment);
+
+  // pwsh / terminal_send 没有注入通道——引用已配置密钥时直接拒绝，避免变量为空静默执行（宁可失败）。
+  let tokens = [];
+  try {
+    tokens = scanRefs(command, snapshot.config, (reason) => { throw new Error(reason); });
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+  if (name === "pwsh") {
+    // PowerShell 的读法 $env:NAME（大小写不敏感）不被 scanRefs 的 $NAME 覆盖。
+    for (const [alias, info] of snapshot.config) {
+      if (new RegExp(`\\$env:${alias}(?![A-Za-z0-9_])`, "i").test(command)) {
+        tokens = [{ token: `$env:${alias}`, name: info.canonical }];
+        break;
+      }
+    }
+  }
+  if (tokens.length > 0) {
+    return `secret-env：${name} 通道不注入密钥（只支持 bash 工具）。需要凭据请改用 bash，或在终端用 srun/senv 执行。`;
+  }
+}
+
+// 等价 ZCode SessionStart 的 `secret-env list --inject`：注入已配置名字清单与用法约定（无真值）。
+export function promptText(snapshot) {
+  const entries = snapshot?.entries ?? [];
+  if (entries.length === 0) {
+    return "secret-env：当前没有已配置的密钥条目。命令中不要写密钥明文；需要时请用户在终端运行 secret-env add 配置。";
+  }
+  return [
+    "secret-env：已配置的密钥（值永远不会出现在上下文；在 bash 命令文本里显式引用即可注入子进程环境）：",
+    ...entries.map(
+      ({ name, aliases = [], description }) =>
+        `- ${name}${aliases.length ? `（别名：${aliases.join("、")}）` : ""}${description ? `：${description}` : ""}`,
+    ),
+    '用法：写 $NAME 或 ${NAME}（双引号内），例如 curl -H "Authorization: Bearer $GH_TOKEN" ...；隐式读取环境变量的工具写成 NAME=$NAME cmd。',
+    "禁止：单引号包引用（拒绝）、echo/打印凭据、同一命令里出现 env/printenv/裸 set/export。",
+    "terminal_send 与 pwsh 通道不注入密钥，需要凭据请用 bash。禁止读写 ~/.config/secret-env 与 vault.kdbx。",
+  ].join("\n");
+}

package/icon.svg

@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 64 64" role="img" aria-label="Secret Env">
+  <rect width="64" height="64" rx="14" fill="#2f6feb"/>
+  <circle cx="24" cy="25" r="8" fill="none" stroke="#ffffff" stroke-width="4"/>
+  <path d="M29.5 30.5 L46 47" stroke="#ffffff" stroke-width="4" stroke-linecap="round"/>
+  <path d="M38 39.5 L44 33.5 M41.5 43 L47.5 37" stroke="#ffffff" stroke-width="4" stroke-linecap="round"/>
+</svg>

package/index.js

@@ -0,0 +1,217 @@
+// secret-env DSH 真身适配器（协议客户端形态，2026-11-06 起）：
+//   1) tools/execute 包装 bash：调 CLI `inject`（命令文本守卫 + 注入后的命令；值只在子进程里写 env 文件，不进上下文）；
+//   2) tools.guard 同步守卫：本地规则副本 + info 快照（受保护路径、名字清单），不 spawn 子进程；
+//   3) systemPrompt 注入已配置名字清单与用法约定（来自 info 快照）；
+//   4) add_secret 工具：元数据由模型传，ctx.userQuestions 卡片收值后经 CLI `store` 入库（值走 stdin）。
+// 不 import 主包代码：只经 CLI 协议（client.mjs，见 docs/PLAN-DSH-DECOUPLING.md）。
+// 运行时中立：与 core.mjs 同规，不用 Bun 专属 API。
+// 注：工具定义直接构造 JSON Schema 交给 ctx.tools.register，不 import defineTool（插件经 pnpm link
+// 从仓库/包路径加载时，Node 按真实路径解析不到 profile 的 @deepseek-ai/dsh-tools）。
+import { appendFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { T, PROVIDERS, interpretAnswer } from "./entry.mjs";
+import { evaluateCall, promptText } from "./guards.mjs";
+import { PROTOCOL, createClient, requireProtocol } from "./client.mjs";
+
+const LOG = join(tmpdir(), "secret-env-dsh.log");
+const log = (msg) => { try { appendFileSync(LOG, `[${new Date().toISOString()}] ${msg}\n`); } catch {} };
+
+const REFRESH_MS = 30 * 1000; // 快照过期时间：guard 每次调用顺手触发后台刷新（非阻塞）
+
+// info（协议）→ 本地快照：config 供同步 scanRefs 用，entries 供清单文案，guardPaths 供文件守卫
+export function buildSnapshot(info) {
+  const config = new Map();
+  for (const entry of info?.entries ?? []) {
+    config.set(entry.name, { canonical: entry.name, description: entry.description });
+    for (const alias of entry.aliases ?? []) config.set(alias, { canonical: entry.name });
+  }
+  return { entries: info?.entries ?? [], guardPaths: info?.rules?.guardPaths ?? [], config };
+}
+
+// CLI 的 store 错误码 → 宿主文案
+function storeError(error) {
+  if (error?.code === "exists") return { status: "invalid", message: T.exists };
+  if (error?.code === "unknown-provider") return { status: "invalid", message: T.badProvider };
+  if (error?.code === "missing-name") return { status: "invalid", message: T.missingName };
+  return { status: "error", message: error?.message ?? String(error) };
+}
+
+export const inject = ["tools", "systemPrompt", "userQuestions"];
+
+// options.client 仅供离线测试注入假客户端；生产不传，走 createClient()（$SENV_BIN → PATH secret-env）
+export function apply(ctx, options = {}) {
+  const client = options.client ?? createClient();
+  const disposers = [];
+
+  // 启动即同步拉快照：guard 是同步回调，没有快照就无法判定。失败 = 插件不加载（宁可失败，不静默放行）。
+  let info;
+  try {
+    info = requireProtocol(client.infoSync());
+  } catch (error) {
+    throw new Error(`secret-env 无法初始化：${error.message}`);
+  }
+  let snapshot = buildSnapshot(info);
+  let lastRefresh = Date.now();
+  let refreshing = false;
+
+  async function refresh() {
+    if (refreshing) return;
+    refreshing = true;
+    try {
+      const next = requireProtocol(await client.info());
+      info = next;
+      snapshot = buildSnapshot(next);
+      lastRefresh = Date.now();
+      log(`snapshot refresh entries=${snapshot.entries.length}`);
+    } catch (error) {
+      log(`snapshot refresh failed: ${error.message}`);
+    } finally {
+      refreshing = false;
+    }
+  }
+  const maybeRefresh = () => { if (Date.now() - lastRefresh > REFRESH_MS) void refresh(); };
+
+  // 守卫在 pre-execute / approval 之后、dispatch 之前同步执行；返回理由即拒绝。
+  disposers.push(ctx.tools.guard((exec) => {
+    maybeRefresh();
+    const reason = evaluateCall(exec, snapshot);
+    if (reason !== undefined) log(`deny tool=${exec?.name} reason=${reason.slice(0, 160)}`);
+    return reason;
+  }));
+
+  // 清单 + 约定：等价 ZCode SessionStart 注入；配置变化在下次 assembly 反映。
+  disposers.push(ctx.systemPrompt.section({
+    name: "secret-env",
+    order: 900,
+    interpolate: false,
+    text: () => promptText(snapshot),
+  }));
+
+  // bash 注入 + 命令文本守卫：一律经 CLI 的 inject（三端同语义，2026-11-06）——
+  // 未配置条目也要走一次，否则受保护路径的命令会漏拦。
+  // exec.arguments 的替换依赖 dispatchToolBody 现场读取同一 exec 对象。
+  // DSH 官方契约只承诺 wrappers 可改 exec.signal；这是既有探针验证过的实现细节，DSH 收紧时需改显式 srun/senv。
+  disposers.push(ctx.on("tools/execute", async function (exec, next) {
+    if (exec?.name !== "bash") return next();
+    const command = exec?.arguments?.command;
+    if (typeof command !== "string" || !command) return next();
+
+    const session = String(exec.callId ?? exec.id ?? "dsh");
+    let result;
+    try {
+      result = await client.inject({ command, session });
+    } catch (error) {
+      throw new Error(`secret-env：${error.message}`); // 业务拒绝与 CLI 故障都报错（宁可失败）
+    }
+    if (!result?.envFile) return next(); // 无引用 = 零注入
+
+    exec.arguments = { ...exec.arguments, command: result.command };
+    log(`inject via cli key=${session} file=${result.envFile}`);
+    void refresh(); // 解析成功可能伴随配置变化（极少），顺手刷新
+    return next();
+  }));
+
+  disposers.push(ctx.tools.register({
+    name: "add_secret",
+    description: T.toolDescription,
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        name: { type: "string", description: T.paramName },
+        provider: { type: "string", enum: PROVIDERS, description: T.paramProvider },
+        detail: { type: "string", description: T.paramDetail },
+        alias: { type: "string", description: T.paramAlias },
+        description: { type: "string", description: T.paramDescription },
+      },
+      required: ["name"],
+    },
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          status: { type: "string", enum: ["stored", "command-issued", "declined", "invalid", "error"] },
+          envName: { type: "string" },
+          uri: { type: "string" },
+          command: { type: "string" },
+          message: { type: "string" },
+        },
+        required: ["status"],
+      },
+      render: (_args, value) => [{ type: "text", text: JSON.stringify(value) }],
+    },
+    async execute(args, exec) {
+      if (exec.agent === undefined) return { status: "error", message: T.noAgent };
+
+      const name = String(args.name ?? "").trim();
+      if (!name) return { status: "invalid", message: T.missingName };
+
+      const provider = args.provider === undefined || args.provider === "" ? "keychain" : args.provider;
+      if (!PROVIDERS.includes(provider)) return { status: "invalid", message: T.badProvider };
+
+      const picked = {
+        name,
+        provider,
+        detail: String(args.detail ?? "").trim(),
+        alias: String(args.alias ?? "").trim(),
+        description: String(args.description ?? "").trim(),
+      };
+
+      // 校验阶段（不入库）：判重与命名归一化由 CLI 回答，宿主不重复实现
+      try {
+        await client.store(picked);
+      } catch (error) {
+        return storeError(error);
+      }
+
+      let item;
+      try {
+        const answer = await ctx.userQuestions.ask({
+          agent: exec.agent,
+          signal: exec.signal,
+          wait: { callId: exec.callId },
+          questions: [{
+            id: "value",
+            header: T.cardHeader,
+            question: T.cardQuestion,
+            options: [{ label: T.commandLabel, description: T.commandDescription }],
+          }],
+        });
+        item = answer?.answers?.[0];
+      } catch (error) {
+        const code = error?.code;
+        if (code === "ASK_CANCELLED" || code === "ASK_ABORTED" || code === "ASK_TIMED_OUT" || code === "NO_PROVIDER") {
+          return { status: "declined" };
+        }
+        return { status: "error", message: error?.message ?? String(error) };
+      }
+
+      const decision = interpretAnswer(item, T.commandLabel);
+      if (decision.kind === "declined") return { status: "declined" };
+      if (decision.kind === "command") {
+        try {
+          const fallback = await client.store({ ...picked, commandOnly: true });
+          return { status: "command-issued", command: fallback.command };
+        } catch (error) {
+          return storeError(error);
+        }
+      }
+
+      try {
+        const stored = await client.store({ ...picked, value: decision.value });
+        log(`add_secret stored env=${stored.envName}`);
+        void refresh();
+        return { status: "stored", envName: stored.envName, uri: stored.uri };
+      } catch (error) {
+        return storeError(error);
+      }
+    },
+  }));
+
+  log(`applied protocol=${PROTOCOL} version=${info.version} entries=${snapshot.entries.length}`);
+  return () => {
+    for (const dispose of disposers) dispose?.();
+  };
+}

package/locale/en.json

@@ -0,0 +1 @@
+{ "meta": { "title": "Secret Env", "description": "Inject credentials into shell commands without exposing values to the model." } }

package/locale/zh.json

@@ -0,0 +1 @@
+{ "meta": { "title": "Secret Env", "description": "把密钥注入 shell 子进程环境，模型上下文永远看不到值。" } }

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@foperate/secret-env-dsh",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.2",
+  "description": "secret-env 的 DeepSeek Harness（DSH）bundle：bash 注入、文件/通道守卫、密钥清单与 add_secret 工具。运行时经 PATH 上的全局 CLI 走宿主协议（protocol 1），本包零依赖。",
+  "type": "module",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js",
+    "./package.json": "./package.json"
+  },
+  "license": "MIT",
+  "author": "whitemay",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/whitemay/zcode-plugin-secret-env.git",
+    "directory": "adapters/dsh"
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "secret-env",
+    "credential-injection"
+  ],
+  "files": [
+    "index.js",
+    "entry.mjs",
+    "guards.mjs",
+    "rules.mjs",
+    "client.mjs",
+    "cordis.patch.yml",
+    "locale/",
+    "icon.svg",
+    "skills/",
+    "README.md"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/rules.mjs

@@ -0,0 +1,48 @@
+// DSH 适配器内的同步判定规则：scanRefs 与 matchGuardPaths。
+// 为什么复制而不是 import 主包：`ctx.tools.guard` 是同步回调（每次工具调用都跑，不能 await 子进程），
+// 扫描算法必须留在插件内；规则**数据**（guardPaths）仍由 CLI 的 info 提供，不在这里硬编码。
+// 同步来源：core.mjs 的 scanRefs（2026-11-06 复制）。改任一边都要同步另一边，并跑 tests/rules-sync.mjs。
+// 返回每个引用 token 的 {token, start, inSingle, name}；deny 为宿主拒绝回调（占位符未配置时调用）。
+export function scanRefs(command, config, deny) {
+  const tokens = []; // {token, start, inSingle, name}
+  const unknownPlaceholders = [];
+
+  // 逐字符扫描建立单引号区间（shell 语义：单引号内无转义）
+  const singleRanges = [];
+  let inSingle = false, rangeStart = -1;
+  for (let i = 0; i < command.length; i++) {
+    const c = command[i];
+    if (c === "'") {
+      if (inSingle) { singleRanges.push([rangeStart, i]); inSingle = false; }
+      else { inSingle = true; rangeStart = i; }
+    }
+  }
+  const inSingleQuote = (i) => singleRanges.some(([a, b]) => i > a && i < b);
+
+  // ① 占位符 {{secret:NAME}}
+  const phRe = /\{\{secret:([A-Za-z0-9_]+)\}\}/g;
+  let m;
+  while ((m = phRe.exec(command))) {
+    const name = m[1];
+    if (!config.has(name)) { unknownPlaceholders.push(name); continue; }
+    tokens.push({ token: m[0], start: m.index, name, inSingle: inSingleQuote(m.index) });
+  }
+  if (unknownPlaceholders.length) {
+    deny(`secret-env：占位符 {{secret:${unknownPlaceholders.join("、")}}} 未在 secrets.json 配置。宁可失败：请修正名字或先配置。`);
+  }
+
+  // ② 显式 $NAME / ${NAME}（词边界；\$ 转义跳过）
+  for (const [alias, info] of config) {
+    const re = new RegExp(`(?<![A-Za-z0-9_\\$])\\$\{?${alias}(?![A-Za-z0-9_])`, "g");
+    while ((m = re.exec(command))) {
+      if (m.index > 0 && command[m.index - 1] === "\\") continue;
+      tokens.push({ token: m[0], start: m.index, name: info.canonical, inSingle: inSingleQuote(m.index) });
+    }
+  }
+  return tokens;
+}
+
+// 受保护片段匹配（规则数据来自 CLI info 的 rules.guardPaths）
+export function matchGuardPaths(text, fragments) {
+  return typeof text === "string" ? fragments.find((f) => text.includes(f)) : undefined;
+}

package/skills/secret-env/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: secret-env
+description: 密钥注入约定——执行需要凭据的 Bash 命令时如何让 secret-env 插件把凭据送进子进程环境（模型上下文永不见值）。写涉及 GH_TOKEN/API key/DATABASE_URL 等凭据的命令前必读。
+---
+
+# secret-env：密钥显式引用约定
+
+本项目的密钥从私有库（Keychain / OpenViking / Bitwarden）直接注入 Bash 子进程环境。
+**你（模型）从头到尾只写变量名，永远不写、也永远看不到真值。**
+注入使用周知原名（如 `GH_TOKEN`），命令文本零改写——拦截层只在命令前加 source 前缀。
+
+> 宿主适配：ZCode 的拦截层是 PreToolUse 钩子，DSH 的是 host 插件，opencode 的是 V2 插件（`execute.before` 钩子）；三者注入语义一致，下文统一称「拦截层」。
+
+## 两条注入触发（拦截层只认显式文本）
+
+1. **占位符**：命令文本里写 `{{secret:NAME}}`（NAME 必须已配置）
+2. **显式 $VAR**：命令文本里出现已配置的周知变量名
+
+## 铁律
+
+- **命令里禁止写死任何密钥明文**。需要凭据时写成 `"$GH_TOKEN"` 或 `{{secret:GH_TOKEN}}`。
+- **禁止单引号包引用**：`'$GH_TOKEN'` 内不会展开，拦截层会直接拒绝整条命令。一律双引号：
+  ```bash
+  curl -H "Authorization: Bearer $GH_TOKEN" ...
+  psql "$DATABASE_URL" -c '...'
+  ```
+- **隐式使用必须显式化**：拦截层只扫命令文本，隐式读环境变量的工具（`gh`、`git push` 等）扫不到、不会注入。必须让命令文本出现引用，例如变量名前缀或同义别名均可——副作用都是把真值以原名送进环境：
+  ```bash
+  GH_TOKEN=$GH_TOKEN gh pr list          # 同名显式化
+  GITHUB_TOKEN=${GH_TOKEN} git push ...  # 工具认别的名字，别名映射
+  USE_TOKEN=${GH_TOKEN} some-tool ...    # 任意名字皆可，注入的仍是原名 GH_TOKEN
+  ```
+  注意：拦截层按命令中**实际引用的名字**注入——引用 `$GITHUB_TOKEN` 就注入 `GITHUB_TOKEN`，引用 `$GH_TOKEN` 就注入 `GH_TOKEN`。需要哪个名字就在命令里写哪个名字的引用。
+- **倾泻意图放独立调用**：查看环境变量、`set -e` 选项、`export FOO=1` 这类与密钥无关的操作，放在**单独一次 Bash 调用**里，不要和带密钥引用的命令拼在同一条。原因：① 每次调用是全新 shell，注入变量不跨调用存活，独立调 `env` 看不到任何密钥，天然安全；② 同一条命令里「密钥引用 + env/printenv/裸 set/裸 export」会被拦截层直接拒绝（同命令倾泻）。
+- **不要 echo/打印凭据**：`echo $GH_TOKEN` 会把值送进你的上下文（出口防线尚未实现），等于绕过整个机制。
+
+## 已配置条目
+
+会话启动时，宿主会把已配置的**名字清单**（含别名，无真值）注入上下文——ZCode 经 SessionStart 钩子，DSH 经系统提示 section（opencode 暂无清单注入，以 `senv list` 或 `~/.config/secret-env/secrets.json` 为准）——以那份清单为准。配置本体在 `~/.config/secret-env/secrets.json`（周知名 → {uri, aliases?}，文件里也只有名字和 uri，没有真值）。配置为空时纯旁路、什么都不注入。清单里的 `BW_SESSION` 是基础设施条目（Bitwarden vault 解锁钥匙，bitwarden:// 凭据解析时自动使用），命令中无需引用它。
+
+用户需要接入新密钥库或添加凭据条目时，按下面的流程走（provider 准备步骤见 [references/providers.md](references/providers.md)）。
+
+## 登记新凭据：先问答，默认交终端执行
+
+登记分两步：**你只负责元数据，密钥值永远不经过你的上下文**。
+
+**第 1 步：元数据问答**——用宿主自带的问答工具（ZCode 的 `AskUserQuestion`、DSH 的 `ask_user_question`；都没有时直接在对话里问），一次问清三个字段：
+
+- **key 题**：从上下文推断 well-known 候选作为选项（同一凭据的多个周知名都列出，如 Hugging Face → `HF_TOKEN`、`HUGGINGFACE_TOKEN`，标注互为别名）；用户也可自由输入，格式 `KEY, alias1, alias2`（逗号分隔，别名可省）。问题文案须说明该格式。
+- **desc 题**：选项 1=你组织的一段描述，选项 2=不需要描述。文案须警示「描述会进入模型上下文，不得含敏感信息」。
+- **provider 题**：keychain（KeePassXC 库）/ bitwarden（Bitwarden）/ viking（OpenViking）/ onepassword（1Password），无从推断时默认 keychain。
+
+用户选完由**你**把答案解析成定稿：well-known 选项→该名字+已知别名；自由输入→按逗号拆出 name 和别名。
+
+**第 2 步（默认兜底，所有宿主可用）：构造完整导入命令，交用户在终端执行**
+
+```bash
+# 例：bitwarden 条目
+senv add -n "github token" --provider bitwarden --item "GitHub" --alias gh-token --desc "GitHub PAT"
+```
+
+命令的密钥值输入是隐藏的、不经过上下文，执行完登记即完成。转交时只需要给命令 + 一句「在终端运行，按提示输入密钥值」——提醒提示符要的是密钥原值，不是名字或说明文字。
+
+**增强分支（仅当宿主满足条件）**：部分宿主能提供表单收值（值同样不进上下文）。先判宿主，再读对应 reference（与本 SKILL.md 同目录的 `references/`）：
+
+- 若环境存在 `ZCODE_APP_VERSION`（ZCode）→ 读 [references/zcode.md](references/zcode.md)：senv-mcp 的 `add_secret` 两问题流程。
+- 若环境存在 `DSH_PROFILE`（DSH）→ 读 [references/dsh.md](references/dsh.md)：当前仍走第 2 步兜底；插件版 `add_secret` 落地后按该文档更新。
+- 无法判别宿主或对应 reference 不可用（含 opencode 等其它宿主）→ 直接走第 2 步兜底。
+
+只有 reference 明确说明「该工具可用」时才走表单路径；否则一律兜底。**不要自己发明工具参数，也不要让用户把密钥值发给你。**
+
+## 常见配方
+
+```bash
+# GitHub
+GH_TOKEN=$GH_TOKEN gh pr list
+curl -s -H "Authorization: Bearer {{secret:GH_TOKEN}}" https://api.github.com/user
+
+# 数据库
+psql "$DATABASE_URL" -c '\dt'
+
+# OpenAI
+OPENAI_API_KEY={{secret:OPENAI_API_KEY}} bun run script.ts
+```
+
+## 失败即信号
+
+拦截层报错时按提示修正命令文本（多半是单引号或未配置的名字），**不要尝试绕过拦截层**（如把值写进文件再 cat、从代码里硬编码读取）。ZCode 的报错为 exit 2 + stderr；DSH 的报错为工具错误结果。

package/skills/secret-env/references/dsh.md

@@ -0,0 +1,61 @@
+# DSH 分支：问答卡片直接消费（不走 MCP elicitation）
+
+适用前提：宿主是 DSH（`DSH_PROFILE` 存在；系统提示里出现 secret-env 已配置清单，即由 DSH host 插件注入）。
+
+## 设计
+
+DSH 的收值路径是**插件内部调用问答卡片**，不是 MCP：
+
+```
+模型 → DSH 插件工具 add_secret（只传元数据）
+     → 插件 ctx.userQuestions.ask() 弹卡片（用户输入密钥值）
+     → 答案回到插件代码，程序化消费（写 keychain / Bitwarden / viking + 登记 secrets.json）
+     → 工具结果只返回 { status, envName, uri }（脱敏，值不进模型上下文）
+```
+
+- **不用 MCP elicitation**：DSH 的 MCP 客户端不声明 elicitation 能力；`senv-mcp` 的 `add_secret` 在 DSH 不可用。
+- **即使将来经 MCP**：也不会用「提供选项」的 elicitation，而是由程序调用另一个 MCP 工具直接消费输入值。
+- 卡片是无掩码文本输入：值在屏幕上可见，但**不进入模型上下文**；工具结果永远脱敏。
+
+## 工具 `add_secret`（已实现）
+
+参数（全部元数据，由模型在第 1 步问答后传入）：
+
+| 参数 | 必填 | 说明 |
+|---|---|---|
+| `name` | 是 | 人读名（归一化为全大写下划线环境变量名） |
+| `provider` | 否 | keychain / bitwarden / viking / onepassword（默认 keychain） |
+| `detail` | 否 | bitwarden/onepassword 条目名[/字段]；viking=类目/目标[/字段]；keychain 留空自动命名 |
+| `alias` | 否 | 别名，逗号分隔 |
+| `description` | 否 | 描述（会进模型上下文，不得含敏感信息） |
+
+执行：名称归一化 + 重名校验（不合法直接返回 `invalid`，不弹卡）→ `ctx.userQuestions.ask()` 弹收值卡 → 程序化入库。
+
+返回（永不含值）：
+
+- `{ status: "stored", envName, uri }`
+- `{ status: "command-issued", command }`（用户在卡片里选了命令行）
+- `{ status: "declined" }`（用户取消/跳过；不是失败。若用户直接关闭卡片面板，宿主可能把整个工具调用标记为 aborted——同样未落库）
+- `{ status: "invalid", message }`（缺名/重名/provider 非法）
+- `{ status: "error", message }`（入库失败等）
+
+## 卡片交互
+
+**必须填原值**：卡片提交的内容会原样写入凭据库、不经过模型——用户必须直接填密钥本身，不能填名字、描述、占位符或说明文字（否则这些文字会被当成密钥存进去，模型也无法校验或补全）。
+
+一张卡，两个输入位置：
+
+1. **显式选项**「我希望通过命令行来完成输入」——选中即返回 `command-issued`，给用户在终端执行的命令（隐藏输入）；
+2. 卡片自动附加的**自由输入行**——用户在这里填密钥值，提交后直接入库。
+
+判断规则（单选：`custom` 覆盖 `selected`）：
+
+- `custom` 非空 → 消费该值，入库，返回 `stored`
+- `custom` 为空且 `selected` 含命令行选项 → 返回命令
+- 两者都空 → `declined`
+
+这对应 ZCode 版第 2 屏形态裁断：ZCode 先试 password 掩码表单、被拒后降级到「命令 / 明文表单」选择屏；DSH 没有密码掩码形态，用「选项 + 自定义输入」一张卡完成同样的分流。
+
+## 兜底
+
+若 `add_secret` 工具不可用（旧版插件/安装异常），登记回到 SKILL.md 的默认路径：问完元数据后构造完整 `senv add ...` 命令交用户在终端执行。

package/skills/secret-env/references/providers.md

@@ -0,0 +1,112 @@
+# 密钥库接入指南（面向用户/操作者）
+
+各 provider 的准备工作与添加凭据条目的步骤。配置登记统一在 `~/.config/secret-env/secrets.json`（周知名 → {uri, aliases?, description?}，文件里只有名字和 uri，无真值）。推荐用 `secret-env add` 交互登记（值经隐藏输入，不经过 Agent 上下文）。
+
+## URI 一般化寻址（2026-11-04 定案）
+
+所有 provider 统一 `scheme://item[/field]`：
+
+- **一级寻址（缺省）= 主密钥**：keychain → password；bitwarden → password；viking → 条目主值
+- **二级寻址 = 次级字段**：
+  - `keychain://<service>/account` — keychain account 属性（同 service 多 account 条目存在时报歧义错，不静默取第一条）
+  - `viking://<category>/<target>/<field>` — privacy 条目字段（既有能力）
+  - `bitwarden://<item>/username`、`/totp`、`/password` — 保留键，走 bw get 子命令；其余字段名按自定义字段在条目 `fields[]` 里按 name 匹配（保留键优先，撞名改字段名消歧）
+- 字段段 URI 内不允许 `/` 与空格；bw 字段名含空格时建议改用无空格命名
+- 账户信息（username/account/成对凭证的 id 侧）是 agent 真实需求（构造 DSN/`-u` 参数/成对 API 凭证），次级寻址为此而设
+
+## keychain://（macOS 系统密钥库，本机最简）
+
+准备：无需安装，macOS 自带 `security` 命令。
+
+```bash
+secret-env add -n "github token" --provider system            # 隐藏输入收值 → 钥匙串 → 登记
+secret-env add -n "aws creds" --provider system --user "AKIA..."  # 可选：account 属性存指定值（缺省 = 当前系统用户）
+```
+
+更新值：同命令重跑覆盖（`--provider system` 对已存在条目强制重新收值；不带则进维护模式只改别名/描述）。
+
+## viking://（OpenViking privacy 层，跨设备）
+
+准备：`ov` CLI 已配置（`~/.openviking/ovcli.conf`）且服务可达。
+
+写侧自治：`add` 收值后经 `ov privacy upsert` 写入（值走 0600 临时文件，不落 argv），再登记映射：
+
+```bash
+secret-env add -n openai --provider viking --path credential/openai/api_key   # 收值 → 写 privacy 字段 → 登记
+secret-env add -n openai --provider viking --path credential/openai           # 无 field 段：主值落 value 字段
+```
+
+更新值：同命令重跑覆盖，或直接在 ov 侧更新（secrets.json 不动）。
+
+## bitwarden://（Bitwarden CLI，跨设备/团队共享）
+
+准备（一次性）：
+
+```bash
+npm i -g @bitwarden/cli        # 或 brew install bitwarden-cli
+bw login                       # 登录（自建服务器先 bw config server <url>）
+bw unlock                      # 解锁，末尾输出 export BW_SESSION="..."
+```
+
+登记 BW_SESSION（两级解析的基础设施条目，session key 存钥匙串）：
+
+```bash
+security add-generic-password -U -s bw-session -a "$USER" -w
+# 交互提示时粘贴 unlock 输出里引号内的 session key（不带引号）
+```
+
+secrets.json 中登记 `"BW_SESSION": { "uri": "keychain://bw-session" }`（读写任何 bitwarden:// 条目时自动经配置链解析并注入 bw 子进程环境；其 uri 不可为 bitwarden://）。
+
+写侧自治：`add` 收值后经 bw 写入 vault（JSON 走 stdin，不落 argv），再登记映射：
+
+```bash
+secret-env add -n myvar --provider bitwarden --item "条目名"            # 收值 → password 位（条目不存在则新建 login 条目）
+secret-env add -n myvar.key --provider bitwarden --item "条目名" --field "api key"   # 收值 → 自定义字段（条目须已存在）
+secret-env add -n myvar --provider bitwarden --item "条目名" --user "someone"        # 顺路写 username 位
+```
+
+要点：
+
+- 写的落位与读镜像：password 位 ↔ 一级寻址；`--field`/username ↔ 二级寻址；`--field` 不隐式建条目
+- 条目名需唯一；重名条目用 id（`bw get item <名> | jq -r .id` 查，界面里 Web Vault 地址栏 `itemId=` 可见）
+- 名字含空格/中文无需转义（字段名含空格不建议用于 URI）
+- **session key 生命周期**：每次 `bw unlock` 换新值 → 重跑上面的 `security add-generic-password` 覆盖；过期后 bitwarden 凭据读写报 bw 原始错误（locked/not unlocked 字样即此因）
+
+## onepassword://（1Password CLI，跨设备）
+
+> ⚠️ 本 provider 尚未真机验证（实现于无 op CLI 的机器），首次使用如有报错以 op 原始错误为准。
+
+准备（一次性）：
+
+```bash
+brew install 1password-cli
+op signin                      # 或开启 1Password 桌面 App 的 biometric 集成后免 signin
+```
+
+可选：登记 OP_SESSION（与 BW_SESSION 同构的基础设施条目）：
+
+```bash
+security add-generic-password -U -s op-session -a "$USER" -w   # 粘贴 op signin --raw 输出的 session token
+# secrets.json 登记 "OP_SESSION": { "uri": "keychain://op-session" }
+```
+
+（不登记则依赖 biometric 或宿主环境的 OP_SESSION_<shorthand> 变量。）
+
+写侧自治（与 bitwarden 镜像）：
+
+```bash
+secret-env add -n myvar --provider onepassword --item "条目名"           # 收值 → password 位（不存在则新建）
+secret-env add -n myvar.key --provider onepassword --item "条目名" --field "api key"   # 收值 → 自定义字段
+```
+
+要点：一级 = password；`/username` 与自定义字段 label 可二级寻址；totp 暂不支持。
+
+## 验证
+
+配置后在新命令里引用（值不出现在输出）：
+
+```bash
+printf '%s' "$MY_VAR" | wc -c    # 长度非 0 即注入成功
+```
+
+清单核对：`secret-env list`（显示名字与 uri，无真值）。

package/skills/secret-env/references/zcode.md

@@ -0,0 +1,22 @@
+# ZCode 分支：senv-mcp 的 add_secret（表单收值）
+
+适用前提：宿主是 ZCode（`ZCODE_APP_VERSION` 存在），且工具列表里有 `add_secret`（senv-mcp，由 ZCode 插件壳 `.zcode-plugin/plugin.json` 的 `mcpServers` 声明）。工具不可用时回到 SKILL.md 的默认兜底（构造 `senv add` 命令交终端）。
+
+## 流程
+
+**第 1 步：元数据问答**——同 SKILL.md 的「第 1 步」，用 ZCode 的 `AskUserQuestion` 一次问清 key / desc / provider 三题，解析成定稿（name + 别名 / 描述 / provider / 条目定位）。
+
+**第 2 步：调用 `add_secret`** 传定稿入参（`name` 必填；`provider` / `detail` / `alias` / `description` 可选）。
+
+工具随后弹收值卡：
+
+- 输入框收密钥（输入时可见，但**不进入模型上下文**）；
+- 用户若选「手工通过命令行输入」或取消，返回里带现成 `command`——转交用户在终端执行即可。**`declined` 不是失败**，是用户选了终端通道；
+- 返回 `status:"invalid"` 时按 `message` 里的原因（缺名 / 重名 / provider 非法）回到第 1 步重问；
+- `status:"stored"` 即收尾。
+
+## 要点
+
+- 密钥值永远不要作为参数传给 `add_secret`，也不要让用户发给你。
+- 工具结果永远脱敏（`stored` 只带 `envName` / `uri`；`command-issued` 只带命令）。
+- ZCode 支持 MCP elicitation；DSH 不支持——DSH 见 [dsh.md](dsh.md)，不要在对 DSH 的对话里调用不存在的 `add_secret`。