dsh-decision-engine 0.0.0-stage → 0.5.0

package/lib/config-file.js

@@ -0,0 +1,136 @@
+/**
+ * `config.yml` 的极简读写。
+ *
+ * 为什么自己写：本插件的配置全是「标量 + 字符串数组」，为它引入一个 YAML
+ * 依赖不值得（插件目标之一是零运行时依赖）。但这套读写必须**可测**——
+ * 「保存后再打开没回显」「切换 provider 把别的配置冲掉」这类问题都出在这里，
+ * 而它们无法靠读代码确认，只能靠往返测试。
+ *
+ * 因此把它从 `index.js` 拆出来：本模块零依赖、无 I/O，只做纯文本变换，
+ * 可以被 `test/config-file.test.js` 直接调用。
+ *
+ * 支持的语法（够用即止）：
+ *
+ *   key: value           标量（含引号、行尾注释）
+ *   key:                 显式空值（保留为 ""，语义是「用户要求留空」）
+ *   key: [a, b]          字符串数组
+ *   # 注释 / 空行        忽略
+ *
+ * @module dsh-decision-engine/config-file
+ */
+
+/**
+ * 解析配置文件文本。
+ *
+ * @param text - 文件全文。
+ * @returns 键值对；无法识别的行被忽略。
+ */
+export function parseConfigText(text) {
+  const out = {};
+  for (const line of String(text ?? "").split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0 || trimmed.startsWith("#")) continue;
+    const sep = trimmed.indexOf(":");
+    if (sep <= 0) continue;
+    const key = trimmed.slice(0, sep).trim();
+    let value = trimmed.slice(sep + 1).trim();
+    // 去掉行尾注释（只处理 ` #` 之后的，避免把 URL 里的 # 当注释）
+    const hashAt = value.indexOf(" #");
+    if (hashAt >= 0) value = value.slice(0, hashAt).trim();
+    // 显式空值（`model:` 后面什么都不写）必须被保留为 ""。
+    // 若在这里丢弃，键会缺失并回落到内置默认模型名，「自动」就永远无法生效。
+    if (value.length === 0) {
+      out[key] = "";
+      continue;
+    }
+    if (isSingleQuoted(value)) {
+      out[key] = value.slice(1, -1);
+      continue;
+    }
+    if (isDoubleQuoted(value)) {
+      // 双引号内允许 `\"`：面板保存带引号的值（如 JSON 形态的请求头）时
+      // 会转义，读回必须还原，否则每次保存都多一层反斜杠。
+      out[key] = value.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, "\\");
+      continue;
+    }
+    // 标量类型推断
+    if (value === "true") out[key] = true;
+    else if (value === "false") out[key] = false;
+    else if (/^-?\d+$/.test(value)) out[key] = Number(value);
+    else if (value.startsWith("[") && value.endsWith("]")) {
+      out[key] = value
+        .slice(1, -1)
+        .split(",")
+        .map((part) => part.trim().replace(/^["']|["']$/g, ""))
+        .filter((part) => part.length > 0);
+    } else out[key] = value;
+  }
+  return out;
+}
+
+/** 值是否为成对单引号包裹（未闭合不算）。 */
+function isSingleQuoted(value) {
+  return value.length >= 2 && value.startsWith("'") && value.endsWith("'");
+}
+
+/** 值是否为成对双引号包裹（未闭合不算）。 */
+function isDoubleQuoted(value) {
+  return value.length >= 2 && value.startsWith('"') && value.endsWith('"');
+}
+
+/**
+ * 把值渲染成 yml 右侧的文本。
+ *
+ * 需要引号的情况：含 `: # [ ] { } ,` 或首尾空白。优先用单引号，
+ * 因为值里带 `"` 时单引号不需要转义；只有同时含单引号与特殊字符时才退回
+ * 双引号并转义。
+ *
+ * @param value - 任意标量。
+ * @returns 渲染结果（不含 `key: ` 前缀）。
+ */
+export function renderConfigValue(value) {
+  if (typeof value === "boolean") return String(value);
+  if (typeof value === "number") return String(value);
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => String(item ?? "").trim()).filter((item) => item.length > 0).join(", ")}]`;
+  }
+  const text = String(value ?? "");
+  if (text.length === 0) return "";
+  const needsQuote = /[:#\[\]{},]/.test(text) || text !== text.trim() || text.includes("\n");
+  if (!needsQuote) return text;
+  if (!text.includes("'") && !text.includes("\n")) return `'${text}'`;
+  return `"${text.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+
+/**
+ * 把若干键值写回配置文本的行数组。
+ *
+ * 保留原有注释与顺序，只替换/追加目标键——用户的注释是说明书，
+ * 整文件重写一次就全丢，而这份文件是用户唯一能看懂配置的地方。
+ *
+ * @param lines - 现有行（会被修改副本，不原地改动入参）。
+ * @param updates - 要写入的键值；`undefined` 视为「不修改」。
+ * @returns 新行数组。
+ */
+export function applyConfigUpdates(lines, updates) {
+  const out = [...lines];
+  for (const [key, value] of Object.entries(updates ?? {})) {
+    if (value === undefined) continue;
+    const rendered = `${key}: ${renderConfigValue(value)}`.trimEnd();
+    let replaced = false;
+    for (let index = 0; index < out.length; index += 1) {
+      const trimmed = out[index].trim();
+      if (trimmed.startsWith("#")) continue;
+      const sep = trimmed.indexOf(":");
+      if (sep <= 0) continue;
+      if (trimmed.slice(0, sep).trim() !== key) continue;
+      // 保留原有的缩进，避免把用户手动缩进的块写歪。
+      const indent = out[index].slice(0, out[index].length - out[index].trimStart().length);
+      out[index] = indent + rendered;
+      replaced = true;
+      break;
+    }
+    if (!replaced) out.push(rendered);
+  }
+  return out;
+}

package/lib/credentials.js

@@ -0,0 +1,187 @@
+/**
+ * `~/.dsh/.credentials.yaml` 的 `refs:` 段读写。
+ *
+ * 为什么单独一层：密钥存哪里是本插件的一个显式选项（`keyStorage`），
+ * 「写进 refs 段」这件事必须**可测**——写坏一个共享凭据文件，代价是
+ * 用户所有服务（DeepSeek / ModelScope / 智谱 …）的 key 一起失效。
+ *
+ * 因此这里只做纯文本变换：给定原文与键值，返回新文本。
+ * 文件 I/O 留给调用方，本模块零依赖、可被单测直接驱动。
+ *
+ * 只碰 `refs:` 段，`records:` 段（DSH 的授权记录，带嵌套结构）一个字节都不改。
+ *
+ * @module dsh-decision-engine/credentials
+ */
+
+/**
+ * 在 `refs:` 段里查找某个键的值。
+ *
+ * @param raw - 文件全文。
+ * @param name - 键名。
+ * @returns 值（已去引号）；未找到返回 undefined。
+ */
+export function pickRefValue(raw, name) {
+  const refs = parseRefsBlock(raw);
+  if (refs === undefined) return undefined;
+  for (const entry of refs.entries) {
+    if (entry.name === name) return entry.value;
+  }
+  return undefined;
+}
+
+/**
+ * 列出 `refs:` 段里的所有键名（不含值）。
+ *
+ * 配置页用它显示「哪些 key 已经配好」，而不必把明文读进内存。
+ *
+ * @param raw - 文件全文。
+ * @returns 键名数组；没有 refs 段时为空数组。
+ */
+export function listRefNames(raw) {
+  const refs = parseRefsBlock(raw);
+  if (refs === undefined) return [];
+  return refs.entries.map((entry) => entry.name);
+}
+
+/**
+ * 定位 `refs:` 段：起始行、结束行与段内条目。
+ *
+ * @param raw - 文件全文。
+ * @returns `{ start, end, indent, entries }`；没有 refs 段时返回 undefined。
+ */
+function parseRefsBlock(raw) {
+  const lines = String(raw ?? "").split(/\r?\n/);
+  let start = -1;
+  let refsIndent = -1;
+  /** @type {Array<{line: number, name: string, value: string}>} */
+  const entries = [];
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    const trimmed = line.trim();
+    if (trimmed.length === 0 || trimmed.startsWith("#")) continue;
+    const indent = line.length - line.trimStart().length;
+
+    if (trimmed === "refs:") {
+      start = index;
+      refsIndent = indent;
+      continue;
+    }
+    if (start < 0) continue;
+    // 缩进不深于 refs 的顶层键 = refs 段结束。
+    if (indent <= refsIndent) {
+      return { start, end: index, indent: refsIndent, entries };
+    }
+    const sep = trimmed.indexOf(":");
+    if (sep <= 0) continue;
+    const name = trimmed.slice(0, sep).trim();
+    const value = trimmed
+      .slice(sep + 1)
+      .trim()
+      .replace(/^["']|["']$/g, "");
+    entries.push({ line: index, name, value });
+  }
+  if (start < 0) return undefined;
+  return { start, end: lines.length, indent: refsIndent, entries };
+}
+
+/**
+ * 把一组键值写入 `refs:` 段。
+ *
+ * 行为约定：
+ *
+ *   - 已存在的键：原地替换值，保留该行位置；
+ *   - 不存在的键：追加到 refs 段末尾（段内缩进对齐已有条目）；
+ *   - 值为空字符串：**删除该键**（用户清空即撤销，不留空壳行）；
+ *   - 没有 refs 段：在文件末尾新建一个；
+ *   - `records:` 段与注释：一律不动。
+ *
+ * @param raw - 文件全文。
+ * @param updates - 键名 → 值。值传 "" 表示删除。
+ * @returns 新文本。
+ */
+export function applyRefUpdates(raw, updates) {
+  const source = String(raw ?? "");
+  const lines = source.split(/\r?\n/);
+  const block = parseRefsBlock(source);
+
+  // 没有 refs 段：追加一个。先保证末尾有换行，避免与最后一行粘连。
+  if (block === undefined) {
+    const body = lines.filter((line) => line.length > 0 || lines.indexOf(line) > 0);
+    // 去掉尾部空行后补回一个换行
+    while (body.length > 0 && body[body.length - 1].trim().length === 0) body.pop();
+    const additions = [];
+    additions.push("refs:");
+    for (const [name, value] of Object.entries(updates ?? {})) {
+      if (typeof value !== "string" || value.length === 0) continue;
+      additions.push(`  ${name}: ${renderValue(value)}`);
+    }
+    return [...body, ...additions, ""].join("\n");
+  }
+
+  // 条目缩进：沿用段内第一个子条目，没有就比 refs 多两格。
+  const childIndent =
+    block.entries.length > 0
+      ? " ".repeat(block.entries[0].line >= 0 ? countIndent(lines[block.entries[0].line]) : block.indent + 2)
+      : " ".repeat(block.indent + 2);
+
+  /** 待删除的行号（值为空时）。 */
+  const removals = new Set();
+  /** 新增的条目行。 */
+  const additions = [];
+
+  for (const [name, value] of Object.entries(updates ?? {})) {
+    const existing = block.entries.find((entry) => entry.name === name);
+    if (typeof value !== "string" || value.length === 0) {
+      if (existing !== undefined) removals.add(existing.line);
+      continue;
+    }
+    const rendered = `${childIndent}${name}: ${renderValue(value)}`;
+    if (existing !== undefined) {
+      lines[existing.line] = rendered;
+    } else {
+      additions.push(rendered);
+    }
+  }
+
+  // 追加位置：refs 段最后一个条目之后；段内没有条目则紧跟 `refs:` 行。
+  let insertAt;
+  if (block.entries.length > 0) {
+    insertAt = block.entries[block.entries.length - 1].line + 1;
+  } else {
+    insertAt = block.start + 1;
+  }
+
+  const result = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    if (removals.has(index)) continue;
+    result.push(lines[index]);
+    if (index === insertAt - 1) result.push(...additions);
+  }
+  // insertAt 落在文件末尾之外（refs 是最后一行且没有条目）
+  if (insertAt >= lines.length) result.push(...additions);
+  return result.join("\n");
+}
+
+/** 行首空格数。 */
+function countIndent(line) {
+  return line.length - line.trimStart().length;
+}
+
+/**
+ * 渲染 YAML 标量。
+ *
+ * key 都是 `sk-…` 这类无特殊字符的串，但仍要处理少数含 `:#` 或引号的值，
+ * 否则写进去之后读不回来（值是 key，读错就等于 key 丢了）。
+ *
+ * @param value - 原始值。
+ * @returns 可安全写入的文本。
+ */
+function renderValue(value) {
+  const text = String(value);
+  if (text.length === 0) return "";
+  const needsQuote = /[:#\[\]{},]/.test(text) || text !== text.trim();
+  if (!needsQuote) return text;
+  if (!text.includes("'")) return `'${text}'`;
+  return `"${text.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}

package/lib/decision-cache.js

@@ -0,0 +1,182 @@
+/**
+ * 决策结果缓存。
+ *
+ * 为什么需要两种键：
+ *
+ * 旧实现只用「完整 state 的 sha256」当键。完整 state 里含 `args_preview`
+ * （本次工具调用的实际参数），所以每次调用参数一变键就变——实测 309 次
+ * 调用命中 0 次，等于缓存完全没工作，每次都真发请求。
+ *
+ * 现在分两层：
+ *
+ *   exact  与旧实现相同，键来自完整 state。命中即复用，绝对安全。
+ *   soft   键来自「归一化签名」：工具名 + 命令族 + 风险标记集合。
+ *          只有**低风险放行**的裁决才写进这一层，且必须风险标记完全一致
+ *          才复用——这样 `node -e '...'` 这类重复调试能命中，而
+ *          `rm -rf /` 与 `rm -rf /tmp/x` 因为风险标记一致、但都属于高风险
+ *          被排除在缓存之外，永不误用。
+ */
+
+import { createHash } from "node:crypto";
+
+/**
+ * 危险动作标记。命中越多，越不可能进 soft 层。
+ * 这些词是「会改变外部世界」的动作，而不是普通读写。
+ */
+const RISK_PATTERNS = [
+  ["rm", /\brm\b/],
+  ["rmdir", /\brmdir\b/],
+  ["mv", /\bmv\b/],
+  ["dd", /\bdd\b/],
+  ["mkfs", /\bmkfs/],
+  ["chmod", /\bchmod\b/],
+  ["chown", /\bchown\b/],
+  ["sudo", /\bsudo\b/],
+  ["kill", /\b(kill|pkill|killall)\b/],
+  ["reboot", /\b(reboot|shutdown|halt)\b/],
+  ["git-push", /\bgit\s+push\b/],
+  ["git-reset", /\bgit\s+(reset|clean)\b/],
+  ["publish", /\b(npm|pnpm|yarn)\s+publish\b/],
+  ["curl", /\b(curl|wget)\b/],
+  ["ssh", /\b(ssh|scp|rsync)\b/],
+  ["redirect", /(^|[^>])>{1,2}[^>]/],
+  ["pipe", /\|/],
+  ["chain", /(&&|;)/],
+  ["subshell", /\$\(|`/],
+  ["eval", /\b(eval|exec)\b/],
+  ["truncate", /\b(truncate|unlink)\b/],
+  ["drop", /\b(drop|delete|truncate)\s+(table|database)\b/i],
+  ["launchctl", /\b(launchctl|crontab|systemctl)\b/],
+  ["defaults", /\bdefaults\s+write\b/],
+  ["security", /\bsecurity\s+(delete|add)/],
+];
+
+/**
+ * 从一段命令文本里抽取风险标记。
+ * @param text - 命令或参数预览。
+ * @returns 排序后的标记名数组。
+ */
+export function riskFlags(text) {
+  const source = typeof text === "string" ? text : "";
+  if (source.length === 0) return [];
+  const hits = [];
+  for (const [name, pattern] of RISK_PATTERNS) {
+    if (pattern.test(source)) hits.push(name);
+  }
+  return hits;
+}
+
+/**
+ * 归一化命令族：取第一个「看起来像命令」的词。
+ *
+ * 目的是让同一类重复操作落到同一个键上，例如反复跑的
+ * `node -e ...` / `python3 - <<PY` / `ls -la`。
+ *
+ * @param text - 命令或参数预览。
+ * @returns 命令族名（小写），取不到时返回空串。
+ */
+export function commandFamily(text) {
+  const source = (typeof text === "string" ? text : "").trim();
+  if (source.length === 0) return "";
+  // 去掉前导环境变量赋值，如 `FOO=1 bar`
+  const withoutEnv = source.replace(/^(?:[A-Za-z_][A-Za-z0-9_]*=\S*\s+)+/, "");
+  const first = withoutEnv.split(/[\s;|&]+/)[0] ?? "";
+  // 只保留命令名的基名，去掉路径
+  const base = first.split("/").pop() ?? "";
+  return base.toLowerCase().slice(0, 32);
+}
+
+/**
+ * 双层决策缓存。
+ *
+ * @param limit - 最多保留多少条（<=0 表示禁用缓存）。
+ * @param ttlMs - 条目存活时间；策略或配置改了之后旧裁决不该继续被复用。
+ */
+export class DecisionCache {
+  /**
+   * @param getLimit - 返回当前容量的取值函数；<=0 表示禁用缓存。
+   * @param getTtlMs - 返回当前存活时间的取值函数。
+   *   两者都接收函数而非定值：配置页改了缓存参数应当立刻生效，
+   *   不该要求重启（与预算、端点、密钥的处理方式一致）。
+   */
+  constructor(getLimit, getTtlMs) {
+    this.getLimit = getLimit;
+    this.getTtlMs = getTtlMs;
+    this.map = new Map();
+    this.stats = { exactHits: 0, softHits: 0, stores: 0, softStores: 0 };
+  }
+
+  /** 当前容量。 */
+  get limit() {
+    const value = Number(typeof this.getLimit === "function" ? this.getLimit() : this.getLimit);
+    return Number.isFinite(value) ? value : 0;
+  }
+
+  /** 当前存活时间。 */
+  get ttlMs() {
+    const value = Number(typeof this.getTtlMs === "function" ? this.getTtlMs() : this.getTtlMs);
+    return Number.isFinite(value) && value > 0 ? value : 600000;
+  }
+
+  /** 完整 state 的精确键。 */
+  static exactKey(parts) {
+    return "e:" + createHash("sha256").update(JSON.stringify(parts)).digest("hex");
+  }
+
+  /**
+   * 归一化软键：工具名 + 命令族 + 风险标记。
+   * 三者全同才认为是同一类操作。
+   */
+  static softKey(toolName, text) {
+    const flags = riskFlags(text).join(",");
+    const family = commandFamily(text);
+    return `s:${toolName}|${family}|${flags}`;
+  }
+
+  get(key) {
+    const entry = this.map.get(key);
+    if (entry === undefined) return undefined;
+    if (Date.now() - entry.at > this.ttlMs) {
+      this.map.delete(key);
+      return undefined;
+    }
+    // LRU：命中后移到队尾
+    this.map.delete(key);
+    this.map.set(key, entry);
+    if (key.startsWith("s:")) this.stats.softHits += 1;
+    else this.stats.exactHits += 1;
+    return entry.value;
+  }
+
+  /**
+   * 写入。exact 键总是可写；soft 键只接受「低风险放行」的裁决。
+   * @param key - 键。
+   * @param value - 裁决。
+   * @param soft - 是否为软键。
+   */
+  set(key, value, soft = false) {
+    if (this.limit <= 0) return;
+    if (soft) this.stats.softStores += 1;
+    this.stats.stores += 1;
+    if (this.map.has(key)) this.map.delete(key);
+    this.map.set(key, { value, at: Date.now() });
+    while (this.map.size > this.limit) {
+      const oldest = this.map.keys().next();
+      if (oldest.done) break;
+      this.map.delete(oldest.value);
+    }
+  }
+
+  /** 命中率（含软硬两层），用于配置页展示。 */
+  get report() {
+    const hits = this.stats.exactHits + this.stats.softHits;
+    const total = hits + this.stats.stores;
+    return {
+      size: this.map.size,
+      exactHits: this.stats.exactHits,
+      softHits: this.stats.softHits,
+      stores: this.stats.stores,
+      hitRate: total === 0 ? 0 : Math.round((hits / total) * 1000) / 1000,
+    };
+  }
+}