dsh-model-headers 0.2.0

package/README.md

@@ -0,0 +1,46 @@
+# dsh-model-headers
+
+[dsh](https://www.npmjs.com/package/@deepseek-ai/dsh) 插件：按模型名给 LLM 请求注入自定义请求头。
+
+典型场景 —— Grok 中转的会话级缓存路由：让同一会话的所有请求携带恒定的 `X-Grok-Conv-Id` 头，与 body 里的 `prompt_cache_key` 恒等，从而命中中转的会话亲和缓存。
+
+```json
+{
+  "rules": [
+    {
+      "id": "r-grok",
+      "enabled": true,
+      "model": "grok-*",
+      "headers": { "X-Grok-Conv-Id": "${sessionId}" }
+    }
+  ]
+}
+```
+
+## 工作原理
+
+- **注入点**：包装 `globalThis.fetch`（幂等，插件卸载时恢复）。规则引擎在模块导入时即安装 —— 不依赖插件 `apply` 时机，headless 首批请求也不会漏拦截。
+- **模型匹配**：通配符 `*`（大小写不敏感），匹配请求 body 的 `model` 字段。命中的启用规则按数组顺序应用，同名头后者覆盖。
+- **值变量**：`${sessionId}` 运行时解析为当前 dsh 会话 ID（取 `x-client-request-id` → `session_id` 头 → body `prompt_cache_key`，兜底空串）。
+
+## 管理 UI
+
+dsh 设置页 →「模型请求头」：
+
+- 规则的添加 / 编辑 / 删除 / 启停，改动实时生效（`fs.watch` 热加载）
+- 模型下拉按供应商分组展示 settings.yaml 里已配置的模型，并自动推导通配符项（`*`、`grok-*`、`gpt-5.6-*` …），支持手输任意通配符与输入过滤
+- 头值一键插入 `${sessionId}`
+
+规则持久化在 `~/.dsh/model-headers.json`。
+
+## 附带能力：settings.yaml 自愈
+
+启动及 settings.yaml 变动时，自动给 `llm-pi-ai.providers` 下缺 `cacheRetention` 的 provider 补写 `cacheRetention: long`（已有值一律尊重）。缺省时 dsh 退回 short 保留策略、不发 `prompt_cache_retention`，中转缓存容易未命中 —— 本插件确保 24h 保留策略就位。
+
+## 核验
+
+每次实际注入追加一行到 `~/.dsh/model-headers.log`（超 5MB 截断；主目录不可写自动落临时目录）。设 `DSH_MH_DEBUG=1` 可额外记录每个请求的 cacheKey / retention。
+
+## License
+
+BSD-3-Clause

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# dsh-model-headers bundle layer.
+# 双面包：宿主半装进 host loader；dsh.client 声明把浏览器模块加进 Web roster。
+- insert:
+    - id: dsh-model-headers
+      name: 'dsh-model-headers'

package/lib/client.js

@@ -0,0 +1,577 @@
+/**
+ * dsh-model-headers client half (v0.1.2).
+ *
+ * 设置页 section「模型请求头」：
+ *   - 规则卡片列表（双列）：启停开关 / 模型通配符 / 头摘要 / 编辑 / 删除（二次确认）
+ *   - 添加·编辑弹框：模型下拉（combobox：点选 settings.yaml 现有模型 / 推导通配符 / 手输任意）+ 头键值行（值可插入 ${sessionId} 变量）
+ *   - 通信：connection RPC 通道 '/model-headers'，信封 {ok, value | error{message}}
+ * - 挂载点：settings.section 槽位（order 100，排在「技能与MCP」之后）。
+ */
+window.__ModuleLoader__.load({
+  id: "dsh-model-headers",
+  factory: (require) => {
+    const React = require("react");
+    // 不用 jsx-runtime：某些 shell 构建里 require("react/jsx-runtime") 的命名导出
+    // 不可靠（jsx 为 undefined → "jsx is not a function"），createElement 最稳。
+    const jsx = (type, props) => React.createElement(type, props);
+
+    const INJECT = ["slots", "connection"];
+
+    /** connection RPC 通道（与 host 半一致）。 */
+    const RPC_CHANNEL = "/model-headers";
+
+    let hostCtx = null;
+
+    async function callApi(endpoint, body = {}) {
+      const result = await hostCtx.connection.rpc.call(RPC_CHANNEL, endpoint, body);
+      if (result.ok) return result.value;
+      throw new Error(result.error?.message || `rpc ${endpoint} failed`);
+    }
+
+    // ------------------------------------------------------------------
+    // Styles（沿用 dsh-ccs/dpc 设计语言，类前缀 dsh-mh-）
+    // ------------------------------------------------------------------
+
+    const css = `
+      .dsh-mh-page { display: flex; flex-direction: column; gap: 12px; width: 100%;
+        max-width: 760px; color: var(--dsw-alias-label-primary, #222);
+        flex: 1 0 auto; min-height: calc(100vh - 180px); }
+      .dsh-mh-title { margin: 0; font-size: 16px; line-height: 24px; font-weight: 600; }
+      .dsh-mh-desc { margin: 0; display: flex; align-items: flex-start; gap: 8px;
+        border: 1px solid var(--dsw-alias-border-l2, rgba(127,127,127,0.3)); border-radius: 8px;
+        padding: 9px 12px; background: var(--dsw-alias-bg-layer-3, rgba(127,127,127,0.06));
+        font-size: 12px; line-height: 18px; white-space: pre-wrap;
+        color: var(--dsw-alias-label-secondary, #555); }
+      .dsh-mh-toolbar { display: flex; gap: 8px; align-items: center; flex-wrap: wrap; flex-shrink: 0; }
+      .dsh-mh-listhead { display: flex; align-items: baseline; gap: 7px; padding: 0 2px; }
+      .dsh-mh-listhead-title { margin: 0; font-size: 13px; line-height: 20px; font-weight: 600; }
+      .dsh-mh-listhead-count { font-size: 12px; line-height: 18px;
+        color: var(--dsw-alias-label-tertiary, #8a8a8a); font-variant-numeric: tabular-nums; }
+      .dsh-mh-cards { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr));
+        align-items: stretch; gap: 10px; }
+      @media (max-width: 680px) { .dsh-mh-cards { grid-template-columns: minmax(0, 1fr); } }
+      .dsh-mh-card { display: flex; flex-direction: column; gap: 6px; min-width: 0;
+        border: 1px solid var(--dsw-alias-border-l2, rgba(127,127,127,0.3)); border-radius: 10px;
+        background: var(--dsw-alias-bg-layer-3, rgba(127,127,127,0.06)); padding: 10px 12px;
+        transition: background 0.15s; }
+      .dsh-mh-card:hover { background: var(--dsw-alias-interactive-bg-hover, rgba(127,127,127,0.1)); }
+      .dsh-mh-card-off { opacity: 0.6; }
+      .dsh-mh-card-top { display: flex; align-items: center; gap: 8px; }
+      .dsh-mh-card-name { flex: 0 1 auto; min-width: 0; overflow: hidden; text-overflow: ellipsis;
+        white-space: nowrap; font-size: 14px; line-height: 20px; font-weight: 600;
+        font-family: var(--ds-font-family-code, ui-monospace, Consolas, monospace); }
+      .dsh-mh-card-spacer { flex: 1; }
+      .dsh-mh-card-headers { display: flex; flex-direction: column; gap: 2px; min-width: 0; }
+      .dsh-mh-card-header-line { font-size: 12px; line-height: 18px;
+        color: var(--dsw-alias-label-secondary, #555);
+        font-family: var(--ds-font-family-code, ui-monospace, Consolas, monospace);
+        white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+      .dsh-mh-card-header-line .dsh-mh-var { color: var(--dsw-alias-state-business-primary, #4b7bec); }
+      .dsh-mh-tag { display: inline-flex; align-items: center; min-height: 18px; flex: none;
+        border-radius: 5px; padding: 1px 6px; background: var(--dsw-alias-bg-layer-1, rgba(127,127,127,0.14));
+        color: var(--dsw-alias-label-secondary, #555); font-size: 11px; line-height: 16px; white-space: nowrap; }
+      .dsh-mh-tag[data-kind='off'] { background: color-mix(in srgb, var(--dsw-alias-state-warning-primary, #b7791f) 12%, transparent);
+        color: var(--dsw-alias-label-secondary, #555); }
+      .dsh-mh-switch { appearance: none; width: 34px; height: 18px; border-radius: 9px; cursor: pointer;
+        background: var(--dsw-alias-state-inactive-label, #9e9e9e); position: relative;
+        transition: background 0.15s; flex-shrink: 0; outline: none; }
+      .dsh-mh-switch:checked { background: var(--dsw-alias-state-success-label, #2e7d32); }
+      .dsh-mh-switch::after { content: ''; position: absolute; top: 2px; left: 2px; width: 14px; height: 14px;
+        border-radius: 50%; background: #fff; transition: transform 0.15s; }
+      .dsh-mh-switch:checked::after { transform: translateX(16px); }
+      .dsh-mh-btn { appearance: none; display: inline-flex; align-items: center; justify-content: center;
+        padding: 6px 14px; border-radius: 8px; cursor: pointer;
+        font-size: 12px; line-height: 18px;
+        background: var(--dsw-alias-bg-layer-1, rgba(127,127,127,0.12));
+        color: var(--dsw-alias-label-primary, #222);
+        border: 1px solid var(--dsw-alias-border-l2, rgba(127,127,127,0.3)); }
+      .dsh-mh-btn:hover:not(:disabled) { background: var(--dsw-alias-interactive-bg-hover, rgba(127,127,127,0.16)); }
+      .dsh-mh-btn:disabled { opacity: 0.5; cursor: not-allowed; }
+      .dsh-mh-btn-primary { background: color-mix(in srgb, var(--dsw-alias-state-business-primary, #4b7bec) 14%, transparent);
+        border-color: color-mix(in srgb, var(--dsw-alias-state-business-primary, #4b7bec) 40%, transparent);
+        color: var(--dsw-alias-state-business-primary, #4b7bec); font-weight: 600; }
+      .dsh-mh-btn-primary:hover:not(:disabled) { background: color-mix(in srgb, var(--dsw-alias-state-business-primary, #4b7bec) 22%, transparent); }
+      .dsh-mh-icon-btn { appearance: none; background: none; border: none; cursor: pointer;
+        font-size: 12px; line-height: 18px; color: var(--dsw-alias-label-tertiary, #8a8a8a);
+        padding: 3px 8px; border-radius: 6px; }
+      .dsh-mh-icon-btn:hover:not(:disabled) { background: var(--dsw-alias-interactive-bg-hover, rgba(127,127,127,0.12));
+        color: var(--dsw-alias-label-primary, #222); }
+      .dsh-mh-icon-btn-danger:hover:not(:disabled) { background: color-mix(in srgb, var(--dsw-alias-state-error-primary, #e5484d) 12%, transparent);
+        color: var(--dsw-alias-state-error-primary, #e5484d); }
+      .dsh-mh-input { border: 1px solid var(--dsw-alias-border-l2, rgba(127,127,127,0.35)); border-radius: 8px;
+        background: var(--dsw-alias-bg-layer-1, rgba(127,127,127,0.08));
+        color: var(--dsw-alias-label-primary, #222); outline: none;
+        padding: 6px 11px; font-size: 13px; line-height: 18px; min-width: 0; }
+      .dsh-mh-input:focus-visible { border-color: var(--dsw-alias-state-business-primary, #4b7bec);
+        box-shadow: 0 0 0 2px color-mix(in srgb, var(--dsw-alias-state-business-primary, #4b7bec) 18%, transparent); }
+      .dsh-mh-mono { font-family: var(--ds-font-family-code, ui-monospace, Consolas, monospace); }
+      .dsh-mh-msg { margin: 0; display: flex; align-items: flex-start; gap: 8px;
+        border: 1px solid var(--dsw-alias-border-l2, rgba(127,127,127,0.3)); border-radius: 8px;
+        padding: 9px 12px; background: var(--dsw-alias-bg-layer-3, rgba(127,127,127,0.06));
+        font-size: 12px; line-height: 18px; white-space: pre-wrap; word-break: break-all;
+        color: var(--dsw-alias-label-primary, #222); }
+      .dsh-mh-msg-ok { border-color: color-mix(in srgb, var(--dsw-alias-state-success-primary, #2e7d32) 35%, transparent);
+        background: color-mix(in srgb, var(--dsw-alias-state-success-primary, #2e7d32) 8%, transparent); }
+      .dsh-mh-msg-err { border-color: color-mix(in srgb, var(--dsw-alias-state-error-primary, #e5484d) 35%, transparent);
+        background: color-mix(in srgb, var(--dsw-alias-state-error-primary, #e5484d) 8%, transparent);
+        color: var(--dsw-alias-state-error-primary, #e5484d); }
+      .dsh-mh-empty { margin: 0; padding: 14px 2px; font-size: 13px; line-height: 20px;
+        color: var(--dsw-alias-label-tertiary, #8a8a8a); white-space: pre-wrap; }
+      /* 弹框 */
+      .dsh-mh-modal-mask { position: fixed; inset: 0; z-index: 1100; display: flex;
+        align-items: center; justify-content: center; padding: 24px;
+        background: var(--dsw-alias-bg-mask-1, rgba(0,0,0,0.45)); backdrop-filter: blur(2px); }
+      .dsh-mh-modal { display: flex; flex-direction: column; min-width: 0; box-sizing: border-box;
+        width: min(520px, 100%); max-height: min(80vh, 680px); overflow: auto; padding: 20px;
+        border: 1px solid var(--dsw-alias-border-l2, rgba(127,127,127,0.3)); border-radius: 14px;
+        background: var(--dsw-alias-bg-base, #fff); box-shadow: 0 16px 48px rgba(0,0,0,0.24); }
+      .dsh-mh-modal-title { margin: 0; font-size: 15px; line-height: 22px; font-weight: 600;
+        color: var(--dsw-alias-label-primary, #222); }
+      .dsh-mh-modal-desc { margin: 4px 0 0; font-size: 12px; line-height: 18px;
+        color: var(--dsw-alias-label-tertiary, #8a8a8a); }
+      .dsh-mh-field { margin-top: 16px; }
+      .dsh-mh-field-label { display: block; margin: 0 0 6px; font-size: 11px; line-height: 16px;
+        font-weight: 500; color: var(--dsw-alias-label-secondary, #555); }
+      .dsh-mh-hv-row { display: flex; gap: 8px; align-items: center; }
+      .dsh-mh-hv-row + .dsh-mh-hv-row { margin-top: 8px; }
+      .dsh-mh-hv-name { flex: 2 1 0; min-width: 0; }
+      .dsh-mh-hv-value { flex: 3 1 0; min-width: 0; }
+      .dsh-mh-hv-var { flex: none; height: 32px; padding: 0 10px; font-size: 11px; }
+      .dsh-mh-hv-del { flex: none; width: 32px; height: 32px; padding: 0; display: inline-flex;
+        align-items: center; justify-content: center; border-radius: 8px; }
+      .dsh-mh-btn-dashed { width: 100%; justify-content: center; margin-top: 8px; height: 30px;
+        border-style: dashed; background: transparent; color: var(--dsw-alias-label-secondary, #555); }
+      .dsh-mh-btn-dashed:hover:not(:disabled) { color: var(--dsw-alias-state-business-primary, #4b7bec);
+        border-color: var(--dsw-alias-state-business-primary, #4b7bec); background: transparent; }
+      .dsh-mh-modal-actions { display: flex; gap: 8px; justify-content: flex-end; margin-top: 20px;
+        padding-top: 14px; border-top: 1px solid var(--dsw-alias-border-l3, rgba(127,127,127,0.18)); }
+      /* 模型下拉（combobox：可手输通配符，也可点选；fixed 定位避免撑出弹框滚动条） */
+      @keyframes dsh-mh-pop { from { opacity: 0; transform: translateY(-2px); } to { opacity: 1; transform: none; } }
+      .dsh-mh-combo { position: relative; flex: 1; min-width: 0; }
+      .dsh-mh-combo-input { width: 100%; box-sizing: border-box; }
+      .dsh-mh-combo-menu { position: fixed; z-index: 1200; box-sizing: border-box;
+        overflow: auto; padding: 5px;
+        border: 1px solid var(--dsw-alias-border-l2, rgba(127,127,127,0.3)); border-radius: 10px;
+        background: var(--dsw-alias-bg-base, #fff); box-shadow: 0 10px 32px rgba(0,0,0,0.16);
+        animation: dsh-mh-pop 0.14s ease; }
+      .dsh-mh-combo-group { margin: 4px 8px 2px; font-size: 10px; line-height: 14px; font-weight: 600;
+        letter-spacing: 0.03em; color: var(--dsw-alias-label-tertiary, #8a8a8a); user-select: none; }
+      .dsh-mh-combo-opt { display: flex; align-items: center; gap: 4px; width: 100%; box-sizing: border-box;
+        appearance: none; border: none; background: none; cursor: pointer; text-align: left;
+        border-radius: 7px; padding: 4px 10px; transition: background 0.15s; }
+      .dsh-mh-combo-opt:hover { background: var(--dsw-alias-interactive-bg-hover, rgba(127,127,127,0.12)); }
+      .dsh-mh-combo-opt.is-active { background: color-mix(in srgb, var(--dsw-alias-state-business-primary, #4b7bec) 10%, transparent); }
+      .dsh-mh-combo-opt-check { flex: none; width: 14px; text-align: center; font-size: 11px; line-height: 18px;
+        color: var(--dsw-alias-state-business-primary, #4b7bec); }
+      .dsh-mh-combo-opt-name { flex: 1 1 auto; min-width: 0; overflow: hidden; text-overflow: ellipsis;
+        white-space: nowrap; font-size: 12px; line-height: 18px;
+        font-family: var(--ds-font-family-code, ui-monospace, Consolas, monospace);
+        color: var(--dsw-alias-label-primary, #222); }
+      .dsh-mh-combo-opt.is-wild .dsh-mh-combo-opt-name {
+        color: var(--dsw-alias-state-business-primary, #4b7bec); font-weight: 600; }
+      .dsh-mh-combo-empty { padding: 8px 10px; font-size: 12px; line-height: 18px;
+        color: var(--dsw-alias-label-tertiary, #8a8a8a); white-space: pre-wrap; }
+    `;
+
+    function ensureStyles() {
+      if (document.getElementById('dsh-mh-style')) return;
+      const el = document.createElement('style');
+      el.id = 'dsh-mh-style';
+      el.textContent = css;
+      document.head.appendChild(el);
+    }
+
+    // ------------------------------------------------------------------
+    // UI 组件
+    // ------------------------------------------------------------------
+
+    const Switch = ({ checked, onChange, disabled, title }) =>
+      jsx('input', {
+        type: 'checkbox', className: 'dsh-mh-switch', checked,
+        onChange: (e) => onChange(e.target.checked), disabled, title,
+      });
+
+    /** 头值里的 ${sessionId} 变量着色展示。 */
+    function renderHeaderValue(value) {
+      const parts = String(value).split('${sessionId}');
+      if (parts.length === 1) return value;
+      const children = [];
+      for (let i = 0; i < parts.length; i++) {
+        if (parts[i] !== '') children.push(parts[i]);
+        if (i < parts.length - 1) {
+          children.push(jsx('span', { key: `v${i}`, className: 'dsh-mh-var', children: '${sessionId}' }));
+        }
+      }
+      return children;
+    }
+
+    /**
+     * 模型下拉（combobox）：可手输任意通配符，也可点选。
+     * 选项按 provider（供应商）分组展示，末组为推导通配符（*、grok-*、gpt-5.6-* …）。
+     * fixed 定位依输入框实时测量（打开帧 + 渲染帧 + models 就绪时重测），避免首开尺寸错位。
+     */
+    function ModelCombo({ value, models, onChange }) {
+      const [open, setOpen] = React.useState(false);
+      const [query, setQuery] = React.useState(''); // 本次打开后手动输入的过滤词（打开时重置，避免只剩已选值）
+      const [menuStyle, setMenuStyle] = React.useState(null);
+      const ref = React.useRef(null);
+      const inputRef = React.useRef(null);
+
+      // 供应商 → 模型 id 分组（保持配置出现顺序）
+      const groups = React.useMemo(() => {
+        const map = new Map();
+        for (const m of models || []) {
+          let ids = map.get(m.provider);
+          if (!ids) map.set(m.provider, (ids = []));
+          if (!ids.includes(m.id)) ids.push(m.id);
+        }
+        return [...map.entries()].map(([provider, ids]) => ({ provider, ids }));
+      }, [models]);
+
+      // 通配符推导：* + 去掉最后一个 - 段的前缀
+      const wildcards = React.useMemo(() => {
+        const set = new Set(['*']);
+        for (const m of models || []) {
+          const parts = m.id.split('-');
+          if (parts.length >= 2) set.add(`${parts.slice(0, -1).join('-')}-*`);
+        }
+        return [...set];
+      }, [models]);
+
+      /** 依输入框位置计算下拉的 fixed 定位与高度；下方空间不足时上翻。 */
+      const placeMenu = React.useCallback(() => {
+        const r = inputRef.current?.getBoundingClientRect();
+        if (!r) return;
+        const ITEM = 26, HEADER = 18, PAD = 12, GAP = 4;
+        const rowCount = groups.reduce((n, g) => n + g.ids.length, 0) + wildcards.length;
+        const headerCount = groups.length + (wildcards.length > 0 ? 1 : 0);
+        const natural = Math.min(rowCount * ITEM + headerCount * HEADER + PAD, 440);
+        const below = window.innerHeight - r.bottom - 12;
+        const above = r.top - 12;
+        const openUp = below < Math.min(natural, 160) && above > below;
+        const maxH = Math.max(120, Math.min(natural, openUp ? above : below));
+        setMenuStyle({
+          left: r.left,
+          width: r.width,
+          maxHeight: maxH,
+          ...(openUp ? { bottom: window.innerHeight - r.top + GAP } : { top: r.bottom + GAP }),
+        });
+      }, [groups, wildcards]);
+
+      const openMenu = React.useCallback(() => {
+        setQuery('');
+        placeMenu();
+        setOpen(true);
+        // autoFocus 可能早于最终布局，下一帧再测一次保证首开位置/宽度正确
+        requestAnimationFrame(placeMenu);
+      }, [placeMenu]);
+
+      React.useEffect(() => {
+        if (!open) return;
+        const onDoc = (e) => { if (ref.current && !ref.current.contains(e.target)) setOpen(false); };
+        const onKey = (e) => { if (e.key === 'Escape') setOpen(false); };
+        const onReposition = () => { placeMenu(); };
+        document.addEventListener('mousedown', onDoc);
+        document.addEventListener('keydown', onKey);
+        // 弹框/页面滚动与窗口缩放时跟随重定位
+        window.addEventListener('resize', onReposition);
+        window.addEventListener('scroll', onReposition, true);
+        return () => {
+          document.removeEventListener('mousedown', onDoc);
+          document.removeEventListener('keydown', onKey);
+          window.removeEventListener('resize', onReposition);
+          window.removeEventListener('scroll', onReposition, true);
+        };
+      }, [open, placeMenu]);
+
+      // models 异步就绪后重测一次，修正首开时的加载态尺寸
+      React.useEffect(() => {
+        if (open) placeMenu();
+      }, [open, groups, wildcards, placeMenu]);
+
+      // 打开/过滤后把已选中项滚动进可视区
+      React.useEffect(() => {
+        if (!open) return;
+        const el = ref.current?.querySelector('.dsh-mh-combo-opt.is-active');
+        el?.scrollIntoView?.({ block: 'nearest' });
+      }, [open, query]);
+
+      const q = query.trim().toLowerCase();
+      const match = (s) => q === '' || q === '*' || s.toLowerCase().includes(q);
+      const visibleGroups = groups
+        .map((g) => ({ ...g, ids: g.ids.filter(match) }))
+        .filter((g) => g.ids.length > 0);
+      const visibleWildcards = wildcards.filter(match);
+      const current = String(value);
+
+      const optButton = (val, wild, key) => jsx('button', {
+        key, type: 'button',
+        className: `dsh-mh-combo-opt${wild ? ' is-wild' : ''}${val === current ? ' is-active' : ''}`,
+        onClick: () => { onChange(val); setOpen(false); },
+        children: [
+          jsx('span', { key: 'c', className: 'dsh-mh-combo-opt-check',
+            children: val === current ? '✓' : '' }),
+          jsx('span', { key: 'n', className: 'dsh-mh-combo-opt-name', children: val }),
+        ],
+      });
+
+      const items = [];
+      for (const g of visibleGroups) {
+        items.push(jsx('div', { key: `g:${g.provider}`, className: 'dsh-mh-combo-group',
+          children: g.provider }));
+        for (const id of g.ids) items.push(optButton(id, false, `m:${g.provider}:${id}`));
+      }
+      if (visibleWildcards.length > 0) {
+        items.push(jsx('div', { key: 'g:wild', className: 'dsh-mh-combo-group', children: '通配符' }));
+        for (const w of visibleWildcards) items.push(optButton(w, true, `w:${w}`));
+      }
+
+      return jsx('div', {
+        ref, className: 'dsh-mh-combo',
+        children: [
+          jsx('input', {
+            key: 'i', ref: inputRef, className: 'dsh-mh-input dsh-mh-mono dsh-mh-combo-input',
+            placeholder: 'grok-*（可手输通配符，或点选下拉项）', value,
+            onChange: (e) => { onChange(e.target.value); setQuery(e.target.value); showMenu(); },
+            onFocus: openMenu,
+          }),
+          open && jsx('div', { key: 'menu', className: 'dsh-mh-combo-menu', style: menuStyle, children:
+            models === null
+              ? jsx('div', { className: 'dsh-mh-combo-empty', children: '读取模型列表…' })
+              : items.length === 0
+                ? jsx('div', { className: 'dsh-mh-combo-empty', children: '无匹配项，可直接使用通配符（如 grok-*）' })
+                : items,
+          }),
+        ],
+      });
+    }
+
+    /** 编辑弹框：模型通配符（下拉可点选 / 可手输）+ 头键值行。 */
+    function RuleEditor({ initial, onClose, onSaved }) {
+      const [model, setModel] = React.useState(initial?.model || '');
+      const [models, setModels] = React.useState(null); // [{ provider, id }] | null 加载中
+      const [pairs, setPairs] = React.useState(() => {
+        const entries = Object.entries(initial?.headers || {});
+        return entries.length > 0 ? entries.map(([name, value]) => ({ name, value })) : [{ name: '', value: '' }];
+      });
+      const [busy, setBusy] = React.useState(false);
+      const [error, setError] = React.useState(null);
+
+      React.useEffect(() => {
+        let alive = true;
+        callApi('models/list')
+          .then((d) => { if (alive) setModels(d.models || []); })
+          .catch(() => { if (alive) setModels([]); });
+        return () => { alive = false; };
+      }, []);
+
+      const setPair = (i, patch) => {
+        setPairs((prev) => prev.map((p, j) => (j === i ? { ...p, ...patch } : p)));
+      };
+      const removePair = (i) => {
+        setPairs((prev) => (prev.length > 1 ? prev.filter((_, j) => j !== i) : prev));
+      };
+
+      const save = async () => {
+        setError(null);
+        const headers = {};
+        for (const p of pairs) {
+          if (p.name.trim() !== '') headers[p.name.trim()] = p.value;
+        }
+        if (model.trim() === '') { setError('模型通配符不能为空'); return; }
+        if (Object.keys(headers).length === 0) {
+          setError('至少需要一条请求头（头名称不能为空）');
+          return;
+        }
+        setBusy(true);
+        try {
+          const saved = await callApi('headers/save', {
+            rule: { id: initial?.id, enabled: initial?.enabled !== false, model, headers },
+          });
+          onSaved(saved.rule);
+        } catch (e) {
+          setError(e.message);
+          setBusy(false);
+        }
+      };
+
+      return jsx('div', {
+        className: 'dsh-mh-modal-mask',
+        onClick: (e) => { if (e.target === e.currentTarget && !busy) onClose(); },
+        children: jsx('div', {
+          className: 'dsh-mh-modal',
+          children: [
+            jsx('h3', { key: 't', className: 'dsh-mh-modal-title',
+              children: initial?.id ? '编辑规则' : '添加规则' }),
+            jsx('p', { key: 'd', className: 'dsh-mh-modal-desc',
+              children: '匹配模型通配符的 LLM 请求将在发出前注入下列自定义请求头' }),
+            jsx('div', { key: 'f1', className: 'dsh-mh-field', children: [
+              jsx('label', { key: 'l', className: 'dsh-mh-field-label',
+                children: '模型匹配（支持 * 通配符，不区分大小写）' }),
+              jsx(ModelCombo, { key: 'c', value: model, models, onChange: setModel }),
+            ] }),
+            jsx('div', { key: 'f2', className: 'dsh-mh-field', children: [
+              jsx('label', { key: 'l', className: 'dsh-mh-field-label',
+                children: '注入头（值支持 ${sessionId} 变量）' }),
+              ...pairs.map((p, i) => jsx('div', { key: i, className: 'dsh-mh-hv-row', children: [
+                jsx('input', {
+                  key: 'n', className: 'dsh-mh-input dsh-mh-mono dsh-mh-hv-name',
+                  placeholder: '头名称，如 X-Grok-Conv-Id', value: p.name,
+                  onChange: (e) => setPair(i, { name: e.target.value }),
+                }),
+                jsx('input', {
+                  key: 'v', className: 'dsh-mh-input dsh-mh-mono dsh-mh-hv-value',
+                  placeholder: '固定值 或 ${sessionId}', value: p.value,
+                  onChange: (e) => setPair(i, { value: e.target.value }),
+                }),
+                jsx('button', {
+                  key: 'sv', type: 'button', className: 'dsh-mh-btn dsh-mh-hv-var',
+                  title: '插入 ${sessionId} 变量',
+                  onClick: () => setPair(i, { value: `${p.value}\${sessionId}` }),
+                  children: '+会话ID',
+                }),
+                jsx('button', {
+                  key: 'x', type: 'button', className: 'dsh-mh-icon-btn dsh-mh-icon-btn-danger dsh-mh-hv-del',
+                  title: '移除该头', disabled: pairs.length === 1,
+                  onClick: () => removePair(i), children: '✕',
+                }),
+              ] })),
+              jsx('button', {
+                key: 'add', type: 'button', className: 'dsh-mh-btn dsh-mh-btn-dashed',
+                onClick: () => setPairs((prev) => [...prev, { name: '', value: '' }]),
+                children: '+ 添加头',
+              }),
+            ] }),
+            error && jsx('div', { key: 'e', className: 'dsh-mh-msg dsh-mh-msg-err', style: { marginTop: '12px' }, children: error }),
+            jsx('div', { key: 'a', className: 'dsh-mh-modal-actions', children: [
+              jsx('button', { key: 'c', type: 'button', className: 'dsh-mh-btn', disabled: busy, onClick: onClose, children: '取消' }),
+              jsx('button', { key: 's', type: 'button', className: 'dsh-mh-btn dsh-mh-btn-primary', disabled: busy, onClick: () => void save(), children: busy ? '保存中…' : '保存' }),
+            ] }),
+          ],
+        }),
+      });
+    }
+
+    function HeadersPanel() {
+      const [rules, setRules] = React.useState(null);
+      const [configFile, setConfigFile] = React.useState('');
+      const [message, setMessage] = React.useState(null); // { kind: 'ok'|'err', text }
+      const [editing, setEditing] = React.useState(null); // rule 对象（{} = 新增）
+      const [busyId, setBusyId] = React.useState(null);
+
+      const reload = React.useCallback(async () => {
+        try {
+          const data = await callApi('headers/list');
+          setRules(data.rules || []);
+          setConfigFile(data.configFile || '');
+        } catch (e) {
+          setMessage({ kind: 'err', text: `加载失败：${e.message}` });
+        }
+      }, []);
+
+      React.useEffect(() => { void reload(); }, [reload]);
+
+      const run = async (endpoint, body, okText) => {
+        const id = body?.id || 'new';
+        setBusyId(id);
+        try {
+          await callApi(endpoint, body);
+          setMessage(okText ? { kind: 'ok', text: okText } : null);
+          await reload();
+        } catch (e) {
+          setMessage({ kind: 'err', text: `${endpoint} 失败：${e.message}` });
+        } finally {
+          setBusyId(null);
+        }
+      };
+
+      const remove = (rule) => {
+        if (!confirm(`确定删除规则 '${rule.model}'？\n该规则的所有自定义请求头将停止注入。`)) return;
+        void run('headers/remove', { id: rule.id }, `已删除规则 '${rule.model}'。`);
+      };
+
+      const toggle = (rule, enabled) => {
+        void run('headers/toggle', { id: rule.id, enabled }, enabled ? `已启用 '${rule.model}'。` : `已停用 '${rule.model}'。`);
+      };
+
+      const enabledCount = (rules || []).filter((r) => r.enabled).length;
+
+      return jsx('div', { className: 'dsh-mh-page', children: [
+        jsx('h2', { key: 't', className: 'dsh-mh-title', children: '模型请求头' }),
+        jsx('div', { key: 'd', className: 'dsh-mh-desc',
+          children: '按模型名匹配 LLM 请求并注入自定义请求头。\n值支持固定字符串和 ${sessionId}（运行时替换为当前会话 ID，适合中转的会话粘性/缓存路由）。' }),
+        jsx('div', { key: 'tb', className: 'dsh-mh-toolbar', children: [
+          jsx('button', { key: 'add', type: 'button', className: 'dsh-mh-btn dsh-mh-btn-primary',
+            onClick: () => setEditing({}), children: '添加规则' }),
+        ] }),
+        jsx('div', { key: 'lh', className: 'dsh-mh-listhead', children: [
+          jsx('span', { key: 'lt', className: 'dsh-mh-listhead-title', children: '规则' }),
+          rules && jsx('span', { key: 'lc', className: 'dsh-mh-listhead-count',
+            children: `${rules.length} 条 · 启用 ${enabledCount}` }),
+        ] }),
+        message && jsx('div', { key: 'msg',
+          className: `dsh-mh-msg ${message.kind === 'ok' ? 'dsh-mh-msg-ok' : 'dsh-mh-msg-err'}`,
+          children: message.text }),
+        rules === null
+          ? jsx('div', { key: 'loading', className: 'dsh-mh-empty', children: '加载中…' })
+          : rules.length === 0
+            ? jsx('div', { key: 'empty', className: 'dsh-mh-empty',
+              children: '还没有规则。点击「添加规则」，例如：\n模型 grok-* → 头 X-Grok-Conv-Id: ${sessionId}' })
+            : jsx('div', { key: 'cards', className: 'dsh-mh-cards', children:
+              rules.map((rule) => jsx('div', {
+                key: rule.id,
+                className: `dsh-mh-card${rule.enabled ? '' : ' dsh-mh-card-off'}`,
+                children: [
+                  jsx('div', { key: 'top', className: 'dsh-mh-card-top', children: [
+                    jsx(Switch, { key: 'sw', checked: rule.enabled, disabled: busyId === rule.id,
+                      title: rule.enabled ? '停用' : '启用', onChange: (v) => toggle(rule, v) }),
+                    jsx('span', { key: 'n', className: 'dsh-mh-card-name', title: rule.model, children: rule.model }),
+                    !rule.enabled && jsx('span', { key: 'off', className: 'dsh-mh-tag', 'data-kind': 'off', children: '已停用' }),
+                    jsx('span', { key: 'sp', className: 'dsh-mh-card-spacer' }),
+                    jsx('button', { key: 'e', type: 'button', className: 'dsh-mh-icon-btn', title: '编辑',
+                      disabled: busyId === rule.id, onClick: () => setEditing(rule), children: '编辑' }),
+                    jsx('button', { key: 'del', type: 'button', className: 'dsh-mh-icon-btn dsh-mh-icon-btn-danger', title: '删除',
+                      disabled: busyId === rule.id, onClick: () => remove(rule), children: '删除' }),
+                  ] }),
+                  jsx('div', { key: 'hs', className: 'dsh-mh-card-headers', children:
+                    Object.entries(rule.headers || {}).map(([name, value]) =>
+                      jsx('div', { key: name, className: 'dsh-mh-card-header-line',
+                        children: [`${name}: `, renderHeaderValue(value)] })) }),
+                ],
+              })) }),
+        configFile && jsx('div', { key: 'cfg', className: 'dsh-mh-empty', style: { fontSize: '11px' },
+          children: `配置文件：${configFile}（外部编辑自动热加载）` }),
+        editing && jsx(RuleEditor, {
+          key: editing.id || 'new',
+          initial: editing,
+          onClose: () => setEditing(null),
+          onSaved: (rule) => {
+            setEditing(null);
+            setMessage({ kind: 'ok', text: `已保存规则 '${rule.model}'，即刻生效。` });
+            void reload();
+          },
+        }),
+      ] });
+    }
+
+    // ------------------------------------------------------------------
+    // apply
+    // ------------------------------------------------------------------
+
+    const apply = (ctx) => {
+      hostCtx = ctx;
+      ensureStyles();
+      ctx.effect(() => () => { hostCtx = null; });
+
+      // 设置页：模型请求头（settings.section 槽位，排在「技能与MCP」之后）
+      ctx.slots.inject('settings.section', () => ctx.slots.register({
+        name: 'settings.section',
+        id: 'dsh-model-headers',
+        order: 100,
+        label: () => '模型请求头',
+      }, (props) => jsx(HeadersPanel, props)));
+    };
+
+    return { apply, inject: INJECT };
+  },
+});

package/lib/index.js

@@ -0,0 +1,455 @@
+/**
+ * dsh-model-headers host half (v0.1.2).
+ *
+ * 按模型名给 LLM 请求注入自定义请求头：
+ *   - 规则存 ~/.dsh/model-headers.json：{ rules: [{ id, enabled, model, headers }] }
+ *   - model 为通配符（仅 '*'，大小写不敏感），匹配请求 body 里的 model 字段
+ *   - 值支持固定字符串与 ${sessionId} 变量（运行时取 dsh 会话 ID）
+ *   - 匹配的启用规则按数组顺序应用，同名头后者覆盖
+ *
+ * 附带自愈：settings.yaml 的 llm-pi-ai.providers 若缺 cacheRetention，启动和
+ * 文件变动时补写 `cacheRetention: long`（缺省时 pi-ai 退回 short，不发
+ * prompt_cache_retention，缓存保留退化易未命中）。
+ *
+ * 注入点：globalThis.fetch 包装（幂等，dispose 恢复）。钩子在**模块导入时**
+ * 立即安装（而非 apply 时），避免 headless 启动竞态导致首批请求漏拦截。
+ * dsh 原生请求头（x-client-request-id / session_id）在此之前已就位，作为
+ * sessionId 取值来源。
+ *
+ * 管理：connection RPC 通道 '/model-headers'（loopback），配置文件 fs.watch
+ * 热加载。每次实际注入追加一行到 ~/.dsh/model-headers.log 供核验（>5MB 截断）。
+ */
+
+import { watch as fsWatch } from 'node:fs'
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises'
+import { homedir, tmpdir } from 'node:os'
+import path from 'node:path'
+import { randomUUID } from 'node:crypto'
+
+export const name = 'dsh-model-headers'
+export const inject = []
+export { ensureCacheRetention, listConfiguredModels }
+
+const DSH_HOME = () => process.env.DSH_HOME || path.join(homedir(), '.dsh')
+const CONFIG_FILE = () => path.join(DSH_HOME(), 'model-headers.json')
+const LOG_FILE = () => path.join(DSH_HOME(), 'model-headers.log')
+const SETTINGS_FILE = () => path.join(DSH_HOME(), 'settings.yaml')
+const LOG_MAX_BYTES = 5 * 1024 * 1024
+const RPC_CHANNEL = '/model-headers'
+const GUARD = Symbol.for('dsh.model-headers.installed')
+
+const e2str = (e) => String(e?.message || e).slice(0, 160)
+
+// ==================== 模块级注入引擎（apply 之外也能工作） ====================
+
+let rules = [] // apply/loadRules 填充；钩子实时读取
+
+/** 规则通配符 → 正则（仅 '*' 语义，其余字符转义；大小写不敏感）。 */
+function modelPatternToRegExp(pattern) {
+  const escaped = String(pattern)
+    .split('*')
+    .map((seg) => seg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+    .join('.*')
+  return new RegExp(`^${escaped}$`, 'i')
+}
+
+async function loadRules() {
+  try {
+    const raw = await readFile(CONFIG_FILE(), 'utf8')
+    const parsed = JSON.parse(raw)
+    rules = Array.isArray(parsed?.rules) ? parsed.rules : []
+  } catch (e) {
+    if (e?.code !== 'ENOENT') console.warn(`[dsh-model-headers] 配置读取失败：${e2str(e)}`)
+    rules = []
+  }
+}
+
+async function saveRules() {
+  const file = CONFIG_FILE()
+  await mkdir(path.dirname(file), { recursive: true })
+  const data = `${JSON.stringify({ rules }, null, 2)}\n`
+  const tmp = `${file}.${process.pid}.tmp`
+  try {
+    await writeFile(tmp, data, 'utf8')
+    // rename 覆盖已存在目标：先清掉旧的（Windows rename 不覆盖）
+    await rm(file, { force: true })
+    await rename(tmp, file)
+  } catch {
+    // 原子写不可用（受限环境/文件占用）时退化为直接覆盖
+    await rm(tmp, { force: true }).catch(() => {})
+    await writeFile(file, data, 'utf8')
+  }
+}
+
+/**
+ * 自愈 settings.yaml：给 llm-pi-ai.providers 下缺 cacheRetention 的 provider
+ * 补写 `cacheRetention: long`。缺省时 pi-ai 退回 short → 不发
+ * prompt_cache_retention，缓存保留退化易未命中。纯行级插入：只补缺失键，
+ * 不动已有值（用户显式配的 none/short 一律尊重）与文件其它内容。
+ */
+async function ensureCacheRetention() {
+  const file = SETTINGS_FILE()
+  let raw
+  try {
+    raw = await readFile(file, 'utf8')
+  } catch (e) {
+    if (e?.code !== 'ENOENT') console.warn(`[dsh-model-headers] settings.yaml 读取失败：${e2str(e)}`)
+    return
+  }
+  const lines = raw.split(/\r?\n/)
+  const start = lines.findIndex((l) => /^llm-pi-ai:\s*(?:#.*)?$/.test(l))
+  if (start < 0) return
+  let providersAt = -1
+  for (let k = start + 1; k < lines.length; k++) {
+    if (/^\S/.test(lines[k])) break // 顶层下一个键，llm-pi-ai 块结束
+    if (/^ {2}providers:\s*(?:#.*)?$/.test(lines[k])) { providersAt = k; break }
+  }
+  if (providersAt < 0) return
+  // 遍历 provider 块（4 空格缩进键），检查块内（6 空格缩进）是否已有 cacheRetention
+  const insertAt = []
+  for (let k = providersAt + 1; k < lines.length; k++) {
+    const line = lines[k]
+    if (/^\S/.test(line)) break
+    if (!/^ {4}[^ #\s][^:]*:\s*(?:#.*)?$/.test(line)) continue
+    let has = false
+    for (let q = k + 1; q < lines.length; q++) {
+      const inner = lines[q]
+      if (/^\S/.test(inner) || /^ {4}[^ ]/.test(inner)) break // 下一个 provider / 顶层
+      if (/^ {6}cacheRetention:/.test(inner)) { has = true; break }
+    }
+    if (!has) insertAt.push(k + 1)
+  }
+  if (insertAt.length === 0) return
+  for (const at of insertAt.reverse()) lines.splice(at, 0, '      cacheRetention: long')
+  const eol = raw.includes('\r\n') ? '\r\n' : '\n'
+  const tmp = `${file}.${process.pid}.tmp`
+  try {
+    await writeFile(tmp, lines.join(eol), 'utf8')
+    await rm(file, { force: true })
+    await rename(tmp, file)
+    console.log(`[dsh-model-headers] settings.yaml 补写 cacheRetention: long × ${insertAt.length}`)
+  } catch (e) {
+    console.warn(`[dsh-model-headers] settings.yaml 补写失败（不影响请求头注入）：${e2str(e)}`)
+    await rm(tmp, { force: true }).catch(() => {})
+  }
+}
+
+/**
+ * 行级扫描 settings.yaml，取 llm-pi-ai.providers 下配置的模型清单
+ * （[{ provider, id }]），供管理 UI 选择指定模型。零 YAML 依赖。
+ */
+async function listConfiguredModels() {
+  let raw = ''
+  try {
+    raw = await readFile(SETTINGS_FILE(), 'utf8')
+  } catch {
+    return []
+  }
+  const lines = raw.split(/\r?\n/)
+  const start = lines.findIndex((l) => /^llm-pi-ai:\s*(?:#.*)?$/.test(l))
+  if (start < 0) return []
+  const out = []
+  let provider = null
+  let inModels = false
+  for (let k = start + 1; k < lines.length; k++) {
+    const line = lines[k]
+    if (/^\S/.test(line)) break // 顶层下一键，llm-pi-ai 块结束
+    let m = line.match(/^ {4}([^ #\s][^:]*):\s*(?:#.*)?$/)
+    if (m) {
+      provider = m[1].trim()
+      inModels = false
+      continue
+    }
+    if (provider === null) continue
+    m = line.match(/^ {6}([^ #\s][^:]*):\s*(?:#.*)?$/)
+    if (m) {
+      inModels = m[1].trim() === 'models'
+      continue
+    }
+    if (!inModels) continue
+    m = line.match(/^ {8}- id:\s*(.+?)\s*(?:#.*)?$/)
+    if (m) {
+      const id = m[1].replace(/^['"]|['"]$/g, '')
+      if (id !== '') out.push({ provider, id })
+    }
+  }
+  return out
+}
+
+// ---- 核验日志（追加一行；超限截断重建；主位置写失败自动落到临时目录） ----
+let logFile = null
+let logWarned = false
+async function writeLogLine(file, line) {
+  let size = 0
+  try { size = (await readFile(file)).length } catch {}
+  if (size > LOG_MAX_BYTES) await rm(file, { force: true })
+  await writeFile(file, line, { flag: 'a' })
+}
+async function appendLog(entry) {
+  const line = `${JSON.stringify(entry)}\n`
+  try {
+    const file = logFile ?? LOG_FILE()
+    await writeLogLine(file, line)
+    logFile = file
+  } catch (e) {
+    if (logFile === null) {
+      // 主位置（~/.dsh）不可写（受限环境/权限），退回临时目录
+      try {
+        const fallback = path.join(tmpdir(), 'dsh-model-headers.log')
+        await writeLogLine(fallback, line)
+        logFile = fallback
+        console.warn(`[dsh-model-headers] 主日志位置不可写，改用 ${fallback}：${e2str(e)}`)
+        return
+      } catch {}
+    }
+    if (!logWarned) {
+      logWarned = true
+      console.warn(`[dsh-model-headers] 核验日志写入失败（注入本身不受影响）：${e2str(e)}`)
+    }
+  }
+}
+
+// ---- 头注入核心 ----
+/** sessionId 来源优先级：原生头 x-client-request-id → session_id → body prompt_cache_key。 */
+function resolveSessionId(lowerHeaders, cacheKey) {
+  return (
+    lowerHeaders['x-client-request-id'] ??
+    lowerHeaders['session_id'] ??
+    cacheKey ??
+    null
+  )
+}
+
+function computeHeaders(lowerHeaders, bodyFields) {
+  if (rules.length === 0) return null
+  const model = bodyFields.model
+  if (!model) return null
+  const sessionId = resolveSessionId(lowerHeaders, bodyFields.prompt_cache_key)
+  const merged = {}
+  let touched = false
+  for (const rule of rules) {
+    if (!rule?.enabled) continue
+    const headers = rule.headers
+    if (!headers || typeof headers !== 'object') continue
+    let pattern
+    try { pattern = modelPatternToRegExp(rule.model) } catch { continue }
+    if (!pattern.test(model)) continue
+    for (const [hName, rawValue] of Object.entries(headers)) {
+      if (typeof hName !== 'string' || hName === '' || typeof rawValue !== 'string') continue
+      let value = rawValue
+      if (value.includes('${sessionId}')) {
+        if (sessionId === null) continue // 取不到会话 ID：丢弃该头，不发字面量
+        value = value.split('${sessionId}').join(sessionId)
+      }
+      merged[hName] = value
+      touched = true
+    }
+  }
+  return touched ? merged : null
+}
+
+function toPlainHeaders(headers) {
+  const out = {}
+  if (!headers) return out
+  try {
+    if (typeof headers.forEach === 'function') {
+      headers.forEach((v, k) => { out[String(k).toLowerCase()] = v })
+    } else if (Array.isArray(headers)) {
+      for (const [k, v] of headers) out[String(k).toLowerCase()] = v
+    } else {
+      for (const [k, v] of Object.entries(headers)) out[k.toLowerCase()] = v
+    }
+  } catch {}
+  return out
+}
+
+function parseBody(body) {
+  try {
+    if (typeof body !== 'string') return null
+    const json = JSON.parse(body)
+    if (!json || typeof json !== 'object') return null
+    return {
+      model: typeof json.model === 'string' && json.model !== '' ? json.model : null,
+      prompt_cache_key: typeof json.prompt_cache_key === 'string' ? json.prompt_cache_key : null,
+      prompt_cache_retention: typeof json.prompt_cache_retention === 'string' ? json.prompt_cache_retention : null,
+    }
+  } catch { return null }
+}
+
+function setHeader(init, name, value) {
+  const headers = init.headers
+  if (headers && typeof headers.set === 'function') {
+    headers.set(name, value)
+    return
+  }
+  if (Array.isArray(headers)) {
+    const i = headers.findIndex(([k]) => String(k).toLowerCase() === name.toLowerCase())
+    if (i >= 0) headers[i][1] = value
+    else headers.push([name, value])
+    return
+  }
+  init.headers = headers || {}
+  init.headers[name] = value
+}
+
+function installFetchHook() {
+  if (globalThis[GUARD]) return
+  const debug = process.env.DSH_MH_DEBUG === '1'
+  const origFetch = globalThis.fetch
+  globalThis[GUARD] = origFetch
+  globalThis.fetch = async function modelHeadersFetch(input, init) {
+    try {
+      const url = typeof input === 'string' ? input : input?.url
+      const body = init?.body
+      const bodyFields = parseBody(body)
+      if (debug) {
+        void appendLog({ t: new Date().toISOString(), debug: 'fetch', url: String(url).slice(0, 120), bodyType: typeof body, model: bodyFields?.model ?? null, cacheKey: bodyFields?.prompt_cache_key ?? null, retention: bodyFields?.prompt_cache_retention ?? null, hasClientReqId: Boolean(toPlainHeaders(init?.headers)['x-client-request-id']) })
+      }
+      if (bodyFields) {
+        const lower = toPlainHeaders(init?.headers)
+        const extra = computeHeaders(lower, bodyFields)
+        if (extra) {
+          for (const [hName, value] of Object.entries(extra)) setHeader(init, hName, value)
+          void appendLog({
+            t: new Date().toISOString(),
+            model: bodyFields.model,
+            headers: extra,
+          })
+        }
+      }
+    } catch {}
+    return origFetch.call(this, input, init)
+  }
+}
+
+function uninstallFetchHook() {
+  const orig = globalThis[GUARD]
+  if (orig === undefined) return
+  if (globalThis.fetch.name === 'modelHeadersFetch') globalThis.fetch = orig
+  delete globalThis[GUARD]
+}
+
+// 钩子在模块导入时立即安装：任何 LLM 请求（含插件 apply 之前的）都能被拦截。
+installFetchHook()
+
+// ==================== 插件装配 ====================
+
+export function apply(ctx) {
+  let watcher = null
+  let watchTimer = null
+
+  async function watchConfig() {
+    if (watcher) return
+    try {
+      watcher = fsWatch(path.dirname(CONFIG_FILE()), (event, filename) => {
+        const name = filename == null ? '' : String(filename)
+        const isRules = name === 'model-headers.json'
+        const isSettings = name === 'settings.yaml'
+        if (!isRules && !isSettings) return
+        clearTimeout(watchTimer)
+        watchTimer = setTimeout(() => {
+          if (isRules) void loadRules()
+          if (isSettings) void ensureCacheRetention()
+        }, 300)
+      })
+    } catch (e) {
+      console.warn(`[dsh-model-headers] 配置监听失败（外部编辑需手动刷新）：${e2str(e)}`)
+    }
+  }
+
+// ---- RPC ----
+  const rpcOk = (value) => ({ ok: true, value })
+  // 镜像 dsh-skill-mcp 的 RpcResult 形状；协议要求 error.code 走 discriminated union，
+  // 且 internal 分支 details 必须为 {}（bad-request 会要求 details.issues，不适用）
+  const rpcFail = (message) => ({ ok: false, error: { code: 'internal', message: String(message).slice(0, 300), details: {} } })
+
+  const endpoints = {
+    'headers/list': { run: async () => ({ rules, configFile: CONFIG_FILE() }) },
+    'models/list': { run: async () => ({ models: await listConfiguredModels() }) },
+    'headers/save': {
+      run: async (p = {}) => {
+        const rule = p?.rule
+        if (!rule || typeof rule !== 'object') throw new Error('缺少 rule')
+        if (typeof rule.model !== 'string' || rule.model.trim() === '') throw new Error('模型通配符不能为空')
+        if (!rule.headers || typeof rule.headers !== 'object' || Object.keys(rule.headers).length === 0) {
+          throw new Error('至少需要一条请求头')
+        }
+        const clean = {
+          id: typeof rule.id === 'string' && rule.id !== '' ? rule.id : `r-${randomUUID()}`,
+          enabled: rule.enabled !== false,
+          model: rule.model.trim(),
+          headers: {},
+        }
+        for (const [k, v] of Object.entries(rule.headers)) {
+          if (typeof k === 'string' && k.trim() !== '' && typeof v === 'string') clean.headers[k.trim()] = v
+        }
+        const i = rules.findIndex((r) => r.id === clean.id)
+        if (i >= 0) rules[i] = clean
+        else rules.push(clean)
+        await saveRules()
+        return { rule: clean }
+      },
+    },
+    'headers/remove': {
+      run: async (p = {}) => {
+        const before = rules.length
+        rules = rules.filter((r) => r.id !== p?.id)
+        if (rules.length === before) throw new Error(`未知规则 '${p?.id}'`)
+        await saveRules()
+        return { removed: p?.id }
+      },
+    },
+    'headers/toggle': {
+      run: async (p = {}) => {
+        const rule = rules.find((r) => r.id === p?.id)
+        if (!rule) throw new Error(`未知规则 '${p?.id}'`)
+        rule.enabled = p?.enabled !== false
+        await saveRules()
+        return { rule }
+      },
+    },
+  }
+
+  // ---- 装配（apply 保持同步：加载/监听异步初始化，RPC 稍后即就绪） ----
+  void (async () => {
+    await loadRules()
+    await ensureCacheRetention()
+    await watchConfig()
+    console.log(`[dsh-model-headers] host ready: ${rules.length} rule(s), rpc '${RPC_CHANNEL}'`)
+  })()
+
+  // connection 是 web profile 的服务，headless 没有 → 可选获取，取不到就跳过 RPC
+  //（fetch 钩子与配置文件热加载不依赖它）。ctx.get 绕过 inject 要求直读服务店。
+  const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+  void (async () => {
+    let connection
+    for (let attempt = 0; attempt < 10; attempt++) {
+      connection = ctx.get?.('connection')
+      if (connection?.rpc?.handle) break
+      connection = undefined
+      await sleep(1000)
+    }
+    if (!connection?.rpc?.handle) {
+      console.log('[dsh-model-headers] 无 connection 服务（headless）：RPC 关闭，注入钩子照常工作')
+      return
+    }
+    connection.rpc.handle(RPC_CHANNEL, async (endpoint, payload) => {
+      try {
+        const action = endpoints[endpoint]
+        if (action === undefined) return rpcFail(`unknown endpoint "${endpoint}"`)
+        return rpcOk(await action.run(payload ?? {}))
+      } catch (e) {
+        return rpcFail(e2str(e))
+      }
+    }, { authority: 'loopback' })
+    console.log(`[dsh-model-headers] rpc '${RPC_CHANNEL}' ready`)
+  })()
+
+  // 文件监听随插件卸载关闭；fetch 钩子恢复原状（配合热重载）。
+  ctx.effect(() => () => {
+    clearTimeout(watchTimer)
+    watcher?.close()
+    watcher = null
+    uninstallFetchHook()
+  })
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "dsh-model-headers",
+  "version": "0.2.0",
+  "description": "Per-model custom request headers: inject headers into LLM requests matched by model-name wildcard; values support fixed strings and the ${sessionId} variable. Managed from a settings-page UI.",
+  "license": "BSD-3-Clause",
+  "homepage": "https://github.com/LvanLa/deepseek-harness-ex/tree/master/plugins/dsh-model-headers",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LvanLa/deepseek-harness-ex.git",
+    "directory": "plugins/dsh-model-headers"
+  },
+  "bugs": {
+    "url": "https://github.com/LvanLa/deepseek-harness-ex/issues"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "headers",
+    "prompt-cache"
+  ],
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-slots"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-connection": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-locale": "^0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.1-rc.2"
+  }
+}