dsh-my-opencode-session-header 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-09-10
+
+### Added
+
+- 修复 OpenCode Go 网关 `400 MissingSessionID`：为走 `opencode` / `opencode-go` 路由的推理请求注入
+  `x-opencode-session`（该会话的稳定 id）
+- 拦截链：同步 `llm/stream` waterfall handler 包装流 + `AsyncLocalStorage` 会话上下文（每次
+  `next()`/`return()` 均在上下文中执行，适配 pi-ai 惰性发请求）+ 单层 `globalThis.fetch` 补丁
+- 路由判定（AND）：provider 白名单（默认 `opencode` / `opencode-go`）× 主机命中（默认 `opencode.ai` 及子域），
+  任一不满足即原样调用原 fetch（零副作用）
+- 会话头值确定性：同会话跨轮次 / 压缩 / 重试 / 重启稳定，不同会话不同值；`valueMode` 支持 `uuid`（提取裸 UUID，
+  无则回退原串）与 `raw`
+- 幂等与优先级：已有同名头（`Headers` / 数组 / 普通对象三形态，大小写不敏感）默认不覆盖，`override: true` 才覆盖
+- 退化安全：无会话上下文或会话 id 为空时不注入（首次 warn 一次）；插件内部异常一律吞掉并降级为原行为
+- 卸载还原：disposer 仅当当前 `globalThis.fetch` 仍是本插件安装的那个时才还原，不误还原他人 patch
+- 配置项（含校验与明确报错）：`enabled` / `providers` / `hosts` / `headerName` / `valueMode` / `override`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bsfeng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# dsh-my-opencode-session-header
+
+[![插件生态](https://img.shields.io/badge/插件生态-topic%20dsh-4d6bfe)](https://github.com/topics/dsh)
+
+> **无 UI 说明**：纯 server 插件（无 client / 无面板 / 无设置页），不产生界面截图——README 效果图门禁按 `package.json` 的 `dsh.ui=false` + `dsh.uiReason` 显式豁免。
+
+**DSH OpenCode 会话头注入插件**：让走 `opencode` / `opencode-go` 路由的推理请求自动携带 `x-opencode-session`（该会话的稳定 id），修复 OpenCode Go 网关对缺失该头的请求返回 **400 MissingSessionID** 的问题。上游讨论：<https://github.com/deepseek-ai/deepseek-harness/discussions/5495>。
+
+## 功能与边界
+
+- 包装 `llm/stream` 事件 + 单层补丁 `globalThis.fetch`，命中配置的 provider 与目标 host 时注入会话头，零运行时依赖。
+- **确定性**：同一会话在跨轮次 / 压缩摘要 / 重试 / 重启后得到同一个值，不同会话不同值；辅助 LLM 调用（标题、摘要）同样带上同一会话的头。
+- **幂等**：请求里已存在同名头（`Headers` / 数组 / 普通对象三种形态，大小写不敏感）时默认不覆盖，`override: true` 才覆盖。
+- **退化安全**：无会话上下文 / 会话 id 为空 / 插件内部异常 → 不注入，原样放行，绝不影响推理请求。
+- **卸载干净**：disposer 仅在「当前 `globalThis.fetch` 仍是自己装的那层」时还原，不误还原他人的 patch。
+
+## 配置项
+
+| 配置项       | 默认值                        | 说明                                                                |
+| ------------ | ----------------------------- | ------------------------------------------------------------------- |
+| `enabled`    | `true`                        | 总开关（`false` 不注册监听、不装 fetch 补丁）                       |
+| `providers`  | `["opencode", "opencode-go"]` | provider 路由白名单（空数组 / 非法值启动即报错）                    |
+| `hosts`      | `["opencode.ai"]`             | 目标主机白名单，自动含子域（`zen.opencode.ai` 命中 `opencode.ai`）  |
+| `headerName` | `"x-opencode-session"`        | 注入的请求头名                                                      |
+| `valueMode`  | `"uuid"`                      | `uuid` = 取会话 id 中的裸 UUID（无则回退原串）；`raw` = 原始会话 id |
+| `override`   | `false`                       | 已有同名头时是否覆盖                                                |
+
+```yaml
+- id: opencode-session-header
+  config:
+    enabled: true
+    providers: ['opencode', 'opencode-go']
+    hosts: ['opencode.ai']
+    valueMode: uuid
+    # override: true   # 仅当确有需要覆盖已有同名头时才开启
+```
+
+## 安装
+
+```bash
+# 方式一：npm 安装
+dsh plugin --profile web add dsh-my-opencode-session-header
+
+# 方式二：本地 link 安装（开发中）
+git clone https://github.com/baosfeng/my-dsh-plugins.git
+dsh plugin --profile web add link:<仓库路径>/plugins/dsh-my-opencode-session-header
+```
+
+安装后必须**完全重启 `dsh`（Web 服务）**才生效：插件在启动时注册 `llm/stream` 监听并安装 fetch 补丁，只刷新浏览器不生效。
+
+> **与静态 header 互斥（重要）**：若 `settings.yaml` 里给 opencode-go 配了写死的 `x-opencode-session`，请先删除该项——本插件默认 `override: false` 不覆盖已有头，静态值会让插件形同未启用，且该固定值会被网关当成同一个会话。确需保留静态头又要插件接管时，改用 `override: true`。
+
+## 验证是否生效
+
+1. 完全重启 `dsh`，启动日志应出现 `[opencode-session-header] active for providers […] with valueMode uuid`；没有则插件未挂载（查 `dsh plugin list` / `cordis.patch.yml`）或配置校验失败。
+2. 新开一个走 opencode-go 路由的会话发消息：正常回复、不再出现 400 即为生效；再开第二个会话同样正常，说明两个会话各带自己的 id（互相串上下文说明仍在用静态头）。
+3. 需要看实际发出的头值时，可临时把 `settings.yaml` 的 `llm-pi-ai.providers.opencode-go.baseURL` 指向本机一个打印请求头的 HTTP 服务（HTTPS 下 `tcpdump` 看不到明文），验证完改回原地址并重启。
+
+## 卸载
+
+```bash
+dsh plugin --profile web remove dsh-my-opencode-session-header
+```
+
+卸载后完全重启 `dsh`，`globalThis.fetch` 由 disposer 还原为安装前的实现（仅还原自己装的那层）。
+
+## 已知限界
+
+- 只拦截 `globalThis.fetch` 且只在 `llm/stream` 上下文内注入：走 websocket / 绕过 fetch 的原生客户端、其它非推理 fetch 调用都不加头（opencode-go 走 HTTPS fetch，不受影响）。
+- 与静态 `headers` 配置互斥（见上）：静态值优先，除非 `override: true`。
+- `valueMode: uuid` 在会话 id 不含 UUID 时回退为原始会话 id 字符串（仍确定性、会话间唯一）。
+
+## 相关文档
+
+→ [OpenCode 会话头模块文档](../../docs/OpenCode会话头/概述.md) · [CHANGELOG](CHANGELOG.md)

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+# dsh-my-opencode-session-header bundle patch: inserts the plugin row into the
+# profile roster. The row mounts the server half (llm/stream wrapper +
+# globalThis.fetch patch injecting the x-opencode-session header). Install with:
+#
+#   git clone https://github.com/baosfeng/my-dsh-plugins.git
+#   dsh plugin --profile web add link:<仓库路径>/plugins/dsh-my-opencode-session-header
+- insert:
+    - id: opencode-session-header
+      name: 'dsh-my-opencode-session-header'

package/lib/config.js

@@ -0,0 +1,76 @@
+/**
+ * dsh-my-opencode-session-header — 配置解析与校验。
+ *
+ * cordis 插件 config 的运行时校验：空数组 / 非法值一律抛出明确错误
+ * （loader 启动即失败，不静默降级成"插件没生效但又没提示"）。
+ */
+const DEFAULT_PROVIDERS = ['opencode', 'opencode-go'];
+const DEFAULT_HOSTS = ['opencode.ai'];
+const DEFAULT_HEADER_NAME = 'x-opencode-session';
+/** 主机名形态（裸主机名，无 scheme / 端口 / 路径）。 */
+const HOST_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/i;
+/** HTTP 头名 token 形态（RFC 7230）。 */
+const HEADER_NAME_PATTERN = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+/** 构造带插件前缀的配置错误（仅本模块内部使用）。 */
+function configError(message) {
+    return new Error(`[opencode-session-header] ${message}`);
+}
+/** 解析并校验插件配置（非法值抛错）。 */
+export function resolveConfig(config) {
+    const source = (config ?? {});
+    return {
+        enabled: booleanOf(source.enabled, 'enabled', true),
+        providers: stringListOf(source.providers, 'providers', DEFAULT_PROVIDERS),
+        hosts: hostListOf(source.hosts),
+        headerName: headerNameOf(source.headerName),
+        valueMode: valueModeOf(source.valueMode),
+        override: booleanOf(source.override, 'override', false),
+    };
+}
+/** 布尔字段校验（缺省用 fallback）。 */
+function booleanOf(value, field, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== 'boolean')
+        throw configError(`config.${field} must be a boolean`);
+    return value;
+}
+/** 非空字符串数组字段校验（缺省用 fallback）。 */
+function stringListOf(value, field, fallback) {
+    if (value === undefined)
+        return [...fallback];
+    if (!Array.isArray(value) || value.length === 0) {
+        throw configError(`config.${field} must be a non-empty array of strings`);
+    }
+    for (const item of value) {
+        if (typeof item !== 'string' || item === '')
+            throw configError(`config.${field} entries must be non-empty strings`);
+    }
+    return value;
+}
+/** hosts 字段：非空数组 + 每项必须是裸主机名。 */
+function hostListOf(value) {
+    const hosts = stringListOf(value, 'hosts', DEFAULT_HOSTS);
+    for (const host of hosts) {
+        if (!HOST_PATTERN.test(host))
+            throw configError(`config.hosts entries must be bare host names (got "${host}")`);
+    }
+    return hosts;
+}
+/** headerName 字段：合法 HTTP 头名。 */
+function headerNameOf(value) {
+    if (value === undefined)
+        return DEFAULT_HEADER_NAME;
+    if (typeof value !== 'string' || !HEADER_NAME_PATTERN.test(value)) {
+        throw configError('config.headerName must be a valid HTTP header name');
+    }
+    return value;
+}
+/** valueMode 字段：uuid | raw。 */
+function valueModeOf(value) {
+    if (value === undefined)
+        return 'uuid';
+    if (value !== 'uuid' && value !== 'raw')
+        throw configError('config.valueMode must be "uuid" or "raw"');
+    return value;
+}

package/lib/context.js

@@ -0,0 +1,62 @@
+/**
+ * dsh-my-opencode-session-header — 会话上下文（AsyncLocalStorage）与流包装。
+ *
+ * pi-ai 的 Models.streamSimple() 是惰性的：真正发 HTTP 发生在消费（迭代）
+ * 流时。因此包装 generator 的**每次** next()/return() 都必须在
+ * `sessionContext.run(store, ...)` 内执行，否则 fetch 侧读不到会话上下文。
+ *
+ * 注意：handler 本身必须是同步函数（返回流对象），async handler 会把
+ * waterfall 返回值变成 Promise，破坏下游 `yield*` 委托（见踩坑
+ * docs/踩坑/README.md）。
+ */
+import { AsyncLocalStorage } from 'node:async_hooks';
+/** 请求期会话上下文存储（模块级单例：插件实例共用无害）。 */
+export const sessionContext = new AsyncLocalStorage();
+/**
+ * 用会话上下文包装推理流；非异步可迭代对象原样返回（绝不破坏调用方）。
+ */
+export function wrapStreamWithContext(store, stream) {
+    const iterator = iteratorOf(stream);
+    if (iterator === undefined)
+        return stream;
+    return iterateWithContext(store, iterator);
+}
+/** 取异步迭代器（失败返回 undefined，由调用方原样透传）。 */
+function iteratorOf(stream) {
+    if (stream === null || typeof stream !== 'object')
+        return undefined;
+    const factory = stream[Symbol.asyncIterator];
+    if (typeof factory !== 'function')
+        return undefined;
+    try {
+        return factory.call(stream);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 逐 chunk 透传；每次 next()/return() 都在会话上下文内执行。 */
+async function* iterateWithContext(store, iterator) {
+    try {
+        for (;;) {
+            const result = await sessionContext.run(store, () => iterator.next());
+            if (result.done === true)
+                return result.value;
+            yield result.value;
+        }
+    }
+    finally {
+        // 消费方 early break（return()）或异常时，关闭内层流，避免流泄漏。
+        await closeInner(store, iterator);
+    }
+}
+/** 关闭内层迭代器（失败静默：关闭错误不得影响消费方）。 */
+async function closeInner(store, iterator) {
+    try {
+        if (typeof iterator.return === 'function')
+            await sessionContext.run(store, () => iterator.return?.(undefined));
+    }
+    catch {
+        /* 内层流已终止或拒绝关闭：忽略 */
+    }
+}

package/lib/fetch-patch.js

@@ -0,0 +1,149 @@
+/**
+ * dsh-my-opencode-session-header — globalThis.fetch 单层补丁。
+ *
+ * 安装时保存原 fetch 并替换；卸载时**仅当当前 fetch 仍是我们装的那个**
+ * 才还原（避免误还原他人的 patch）。包装函数同步判定路由（provider 白名单
+ * AND 主机命中），命中且当前有会话上下文时注入会话头；任一不满足或任何
+ * 内部异常 → 原样调用原 fetch，零副作用。
+ *
+ * 安全性：openai SDK 与 anthropic SDK 都在每次请求时解析 globalThis.fetch，
+ * 且 DSH 自身没有任何 globalThis.fetch 补丁，故请求前安装即被采用。
+ */
+import { sessionContext } from './context.js';
+import { hasHeader, withHeader } from './headers.js';
+/** 补丁层标记属性（不可枚举；用于识别"这一层也是我们装的"）。 */
+const LAYER_KEY = 'dshOpencodeSessionHeaderLayer';
+/** 安装 fetch 补丁，返回卸载函数（仅还原/摘除自己的补丁层）。 */
+export function installFetchPatch(options) {
+    const target = globalThis;
+    const { patched, layer } = createPatchedFetch(target.fetch, options);
+    target.fetch = patched;
+    return () => {
+        const inner = layer.current();
+        if (target.fetch === patched) {
+            target.fetch = inner;
+            return;
+        }
+        // 本层被同类补丁压在下面（重复 apply / 乱序卸载）：从链上摘除自己，
+        // 不触碰他人的 fetch 实现。
+        patchLayerOf(target.fetch)?.rewire(inner);
+    };
+}
+/** 取补丁层（非本插件安装的 fetch 返回 undefined）。 */
+function patchLayerOf(value) {
+    if (typeof value !== 'function')
+        return undefined;
+    const layer = value[LAYER_KEY];
+    if (layer === null || typeof layer !== 'object')
+        return undefined;
+    const candidate = layer;
+    return typeof candidate.rewire === 'function' && typeof candidate.current === 'function'
+        ? candidate
+        : undefined;
+}
+/** 包装原 fetch：命中则注入，否则/异常时原样调用。 */
+function createPatchedFetch(initial, options) {
+    let inner = initial;
+    const patched = (input, init) => {
+        try {
+            const plan = planInjection(input, init, options);
+            return plan === undefined ? inner(input, init) : inner(plan[0], plan[1]);
+        }
+        catch {
+            // 插件内部任何异常都必须降级为原行为，绝不阻断推理请求。
+            return inner(input, init);
+        }
+    };
+    const layer = {
+        rewire: (next) => {
+            inner = next;
+        },
+        current: () => inner,
+    };
+    Object.defineProperty(patched, LAYER_KEY, { value: layer });
+    return { patched, layer };
+}
+/** 判定是否注入；命中返回 [input, init]，否则 undefined。 */
+function planInjection(input, init, options) {
+    const url = urlOf(input);
+    if (url === undefined || !hostMatches(url, options.hosts))
+        return undefined;
+    const store = storeForRequest(options);
+    if (store === undefined || !options.providers.includes(store.provider))
+        return undefined;
+    if (!options.override && hasHeader(headersOf(input, init), options.headerName))
+        return undefined;
+    return applyHeader(input, init, options.headerName, store.value);
+}
+/** 取当前会话上下文；缺失时按"退化"告警一次并放弃注入。 */
+function storeForRequest(options) {
+    const store = sessionContext.getStore();
+    if (store !== undefined && store.value !== '')
+        return store;
+    options.warnOnce(`[opencode-session-header] host matched but no llm session context; ${options.headerName} not injected`);
+    return undefined;
+}
+/** 注入头：优先 init.headers（Headers/数组/对象三种形态），其次 Request 实例。 */
+function applyHeader(input, init, name, value) {
+    const initHeaders = propertyOf(init, 'headers');
+    if (initHeaders !== undefined)
+        return [input, { ...init, headers: withHeader(initHeaders, name, value) }];
+    if (isRequestInstance(input))
+        return [withRequestHeader(input, name, value), init];
+    return [input, { ...init, headers: { [name]: value } }];
+}
+/** init / Request 上现有的请求头（用于幂等判定）。 */
+function headersOf(input, init) {
+    const initHeaders = propertyOf(init, 'headers');
+    if (initHeaders !== undefined)
+        return initHeaders;
+    return isRequestInstance(input) ? propertyOf(input, 'headers') : undefined;
+}
+/** 请求目标 URL（string / URL / Request 三种形态）。 */
+function urlOf(input) {
+    if (typeof input === 'string')
+        return input;
+    if (input instanceof URL)
+        return input.href;
+    const url = propertyOf(input, 'url');
+    return typeof url === 'string' ? url : undefined;
+}
+/** 主机命中判定：精确匹配或子域（`zen.opencode.ai` 命中 `opencode.ai`）。 */
+export function hostMatches(url, hosts) {
+    const hostname = hostnameOf(url);
+    if (hostname === undefined)
+        return false;
+    return hosts.some((host) => {
+        const wanted = host.toLowerCase();
+        return hostname === wanted || hostname.endsWith(`.${wanted}`);
+    });
+}
+/** URL → 主机名（不可解析返回 undefined）。 */
+function hostnameOf(url) {
+    try {
+        return new URL(url).hostname.toLowerCase();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 属性读取（非对象或不可读时返回 undefined）。 */
+function propertyOf(target, key) {
+    if (target === null || typeof target !== 'object')
+        return undefined;
+    return target[key];
+}
+/** 是否为 Request 实例（仅在构造器可用时判定）。 */
+function isRequestInstance(value) {
+    const ctor = globalThis.Request;
+    if (typeof ctor !== 'function')
+        return false;
+    return value instanceof ctor;
+}
+/** 复制 Request 并合入会话头（不改动原 Request）。 */
+function withRequestHeader(request, name, value) {
+    const ctor = globalThis.Request;
+    if (ctor === undefined)
+        return request;
+    return new ctor(request, { headers: withHeader(propertyOf(request, 'headers'), name, value) });
+}

package/lib/headers.js

@@ -0,0 +1,56 @@
+/**
+ * dsh-my-opencode-session-header — 请求头形态归一化。
+ *
+ * fetch init.headers / Request.headers 有三种形态（Headers 实例、数组、
+ * 普通对象），大小写不敏感：判定"是否已有该头"与"写入该头"都必须覆盖
+ * 三种形态，且不可就地修改调用方的对象（避免污染共享 headers）。
+ */
+/** 取运行时 Headers 构造器（Node 18+ 全局可用；缺失时降级为其它形态处理）。 */
+function headersConstructor() {
+    const ctor = globalThis.Headers;
+    return typeof ctor === 'function' ? ctor : undefined;
+}
+function isHeadersInstance(value) {
+    const ctor = headersConstructor();
+    return ctor !== undefined && value instanceof ctor;
+}
+/** 条目 → 头名（数组形态的第 0 项）。 */
+function entryName(entry) {
+    return Array.isArray(entry) ? String(entry[0]).toLowerCase() : '';
+}
+/** 是否已存在同名头（大小写不敏感）。 */
+export function hasHeader(headers, name) {
+    const wanted = name.toLowerCase();
+    if (isHeadersInstance(headers))
+        return headers.has(name);
+    if (Array.isArray(headers))
+        return headers.some((entry) => entryName(entry) === wanted);
+    if (headers !== null && typeof headers === 'object') {
+        return Object.keys(headers).some((key) => key.toLowerCase() === wanted);
+    }
+    return false;
+}
+/** 返回写入该头后的新 headers 值（不改动入参；形态与入参一致）。 */
+export function withHeader(headers, name, value) {
+    if (isHeadersInstance(headers))
+        return clonedWithHeader(headers, name, value);
+    if (Array.isArray(headers))
+        return [...headers.filter((entry) => entryName(entry) !== name.toLowerCase()), [name, value]];
+    const base = headers !== null && typeof headers === 'object' ? { ...headers } : {};
+    for (const key of Object.keys(base)) {
+        if (key.toLowerCase() === name.toLowerCase())
+            delete base[key];
+    }
+    base[name] = value;
+    return base;
+}
+/** 复制 Headers 实例并写入（避免改动调用方共享的实例）。 */
+function clonedWithHeader(headers, name, value) {
+    const ctor = headersConstructor();
+    if (ctor === undefined)
+        return headers;
+    const copy = new ctor();
+    headers.forEach((headerValue, key) => copy.set(key, headerValue));
+    copy.set(name, value);
+    return copy;
+}

package/lib/index.js

@@ -0,0 +1,72 @@
+/**
+ * dsh-my-opencode-session-header — OpenCode Go 网关会话头注入（server 端）。
+ *
+ * 问题：opencode.ai（OpenCode Go 网关）要求每个推理请求携带
+ * `x-opencode-session`，否则返回 400 MissingSessionID；DSH 的 pi-ai 适配器
+ * 从不发这个头，且 DSH 的 `headers` 配置是静态字符串字典（无插值）、
+ * session 头名写死——纯配置不可行。
+ *
+ * 方案（唯一可用拦截点）：
+ *  1. `ctx.on('llm/stream', ...)`（waterfall）同步包装流，用 AsyncLocalStorage
+ *     携带 { provider, 会话头值 }（options 同时带 provider 与 sessionId）；
+ *  2. 安装单层 `globalThis.fetch` 补丁：请求的 provider 命中白名单且目标
+ *     主机命中配置时，注入会话头（已有同名头默认不覆盖）。
+ *
+ * 会话头值确定性：同会话跨轮次 / 压缩 / 重试 / 重启得到同一个值。
+ * 任何内部异常都吞掉并降级为原行为，绝不影响推理请求。
+ */
+import { resolveConfig } from './config.js';
+import { wrapStreamWithContext } from './context.js';
+import { installFetchPatch } from './fetch-patch.js';
+import { sessionValueOf } from './session-value.js';
+export const name = 'dsh-my-opencode-session-header';
+export function apply(ctx, config) {
+    const cfg = resolveConfig(config);
+    if (!cfg.enabled)
+        return;
+    const warnOnce = createWarnOnce(ctx);
+    ctx.on('llm/stream', (options, next) => handleStream(options, next, cfg.valueMode));
+    ctx.effect(() => installFetchPatch({
+        providers: cfg.providers,
+        hosts: cfg.hosts,
+        headerName: cfg.headerName,
+        override: cfg.override,
+        warnOnce,
+    }), 'dsh-my-opencode-session-header: fetch patch');
+    ctx.logger?.info?.(`[opencode-session-header] active for providers [${cfg.providers.join(', ')}] with valueMode ${cfg.valueMode}`);
+}
+/**
+ * llm/stream waterfall handler：**必须是同步函数**（async 会让 waterfall
+ * 返回 Promise，破坏下游 `yield*` 委托），先取流再决定是否包装。
+ */
+function handleStream(options, next, valueMode) {
+    const stream = next();
+    const sessionId = stringOf(propertyOf(options, 'sessionId'));
+    if (sessionId === '')
+        return stream;
+    const store = {
+        provider: stringOf(propertyOf(options, 'provider')),
+        value: sessionValueOf(sessionId, valueMode),
+    };
+    return wrapStreamWithContext(store, stream);
+}
+/** 退化告警（首次出现时 warn 一次，之后静默）。 */
+function createWarnOnce(ctx) {
+    let warned = false;
+    return (message) => {
+        if (warned)
+            return;
+        warned = true;
+        ctx.logger?.warn?.(message);
+    };
+}
+/** 属性读取（非对象或不可读时返回 undefined）。 */
+function propertyOf(target, key) {
+    if (target === null || typeof target !== 'object')
+        return undefined;
+    return target[key];
+}
+/** 字符串读取（非字符串返回空串）。 */
+function stringOf(value) {
+    return typeof value === 'string' ? value : '';
+}

package/lib/session-value.js

@@ -0,0 +1,13 @@
+/** 裸 UUID（大小写不敏感）。 */
+const UUID_PATTERN = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/i;
+/**
+ * 计算会话头取值。
+ * @param sessionId - llm/stream options.sessionId（会话稳定 id）。
+ * @param mode - uuid（提取裸 UUID，无则回退原串）或 raw（原始会话 id）。
+ */
+export function sessionValueOf(sessionId, mode) {
+    if (mode === 'raw')
+        return sessionId;
+    const match = UUID_PATTERN.exec(sessionId);
+    return match === null ? sessionId : match[0];
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "dsh-my-opencode-session-header",
+  "version": "0.1.0",
+  "description": "DSH opencode 会话头注入插件：包装 llm/stream 建立 AsyncLocalStorage 会话上下文 + 单层 globalThis.fetch 补丁，为 opencode.ai（含子域）的推理请求注入 x-opencode-session 头，修复 OpenCode Go 网关 400 MissingSessionID。DSH web plugin: injects the x-opencode-session header for opencode-go model routes.",
+  "type": "module",
+  "main": "lib/index.js",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/baosfeng/my-dsh-plugins"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "npx tsc -p tsconfig.json",
+    "typecheck": "npx tsc --noEmit -p tsconfig.json",
+    "test": "npx vitest run --coverage && cucumber-js test/features --import \"test/features/steps/*.mjs\""
+  },
+  "exports": {
+    ".": {
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "ui": false,
+    "uiReason": "纯 server 插件：只在出站推理请求上注入 x-opencode-session 头，DSH Web UI 无任何可见产物（无 client / 无面板 / 无设置页）"
+  },
+  "peerDependencies": {
+    "cordis": "^4.0.0-rc.10"
+  },
+  "peerDependenciesMeta": {
+    "cordis": {
+      "optional": true
+    }
+  },
+  "license": "MIT"
+}