opencode 会话标识 gausszhou/dsh-opencode-session-id

dsh-opencode-session-id

给 opencode 用的 dsh 会话 ID，零配置。

一个 DeepSeek Harness（dsh）插件：当你使用 opencode 模型（opencode / opencode-go 这类服务商，指向 opencode.ai 网关）时，它让实际发出的 HTTP 请求带上会话 ID —— 和 opencode 客户端自己的做法一样。

用法

把插件加到 dsh 配置档里（发布到 npm 后按包名安装）：

dsh plugin --profile web add "@gausszhou/dsh-opencode-session-id"

安装后重启 dsh web（systemctl --user restart dsh-web），bundle 才会生效。默认配置开箱即用：发往 opencode.ai 的请求会自动带上 x-opencode-session（opencode 网关使用的会话请求头），外加 x-session-affinity / x-client-request-id / x-session-id。请求头的值默认是从会话 ID 的 uuid 部分算出的纯字母数字 nanoid(8)（例如 0RpJJnxJ —— session- 前缀不参与哈希；token 由 uuid 经 SHA-256 确定性推导）。开启 verbose: true 后，journal 会记录原始 ID 与线上 token 的对应关系：

journalctl --user -u dsh-web -f | grep opencode-session-id

工作原理

opencode 网关分支用 x-opencode-session 携带会话 ID；本插件监听 llm/stream 作用域，包装 fetch，在传输层加上这个请求头。默认情况下，它把 session-<uuid> 的 uuid 部分（不含 session- 前缀）哈希成字母数字的 nanoid(8)，再发到线上。只动请求头 —— 请求体、URL、方法以及其他一切原样透传。完整设计思路见 docs/design.md。

配置

默认零配置（上面那条安装命令就够了）。想通过补丁层开启注入日志：

- id: opencode-session-id
config:
verbose: true

全部选项（均可选，默认值如下）：

| 键 | 默认值 | 说明 |
| providers | [opencode, opencode-go] | 需要标记 sessionId 的 llm-pi-ai 路由名 |
| hosts | [opencode.ai] | 会带上会话请求头的 URL 主机后缀（含子域名） |
| baseURLs | [] | 额外匹配的精确 URL 前缀（自定义网关） |
| headers | [x-opencode-session, x-session-affinity, x-client-request-id, x-session-id] | 要注入的请求头名称 |
| extraHeaders | {} | 可选的静态额外请求头（例如 opencode 指纹系列 x-opencode-client: native / x-opencode-request: dsh） |
| userAgent | 空 | 覆盖 User-Agent（opencode 自己发送 opencode/<version>；默认不改动） |
| sessionIdEnv | 空 | 会话 id 回退时读取的环境变量名 |
| verbose | false | 记录每次注入（包括原始 id → 线上 token 的映射） |
| seedSessionId | false | 为 opencode 路由预置 options.sessionId |
| nanoidSessionId | true | 发送前把 session-<uuid> 哈希成 nanoid(8)；设为 false 则发送原始 id |
| nanoidLength | 8 | token 长度（4–32） |
| nanoidAlphabet | alphanumeric | alphanumeric（纯 A-Za-z0-9，不含 _/-）或 urlsafe（经典 64 字符集） |
| disableFetchInjection | false | 设为 true 时，只保留 waterfall 的会话作用域 |

验证

node test/verify.mjs # 10 checks: unit tests + real pi-ai wire request + concurrent isolation + headers-only guarantee
node test/smoke-apply.mjs # apply() wiring: listener registration, scoped fetch, mount/dispose lifecycle

verify.mjs 会通过 dsh CLI 自带的 pi-ai 发出真实 opencode-go 请求，断言线上请求头确实携带会话 id；它还会验证并发会话隔离，以及非 opencode 端点不受影响。

说明与限制

- 会话 id 来自 options.sessionId（agent-loop 会按会话填入）；没有会话上下文时，回退顺序是 sessionIdEnv > DSH_SESSION_ID（web 部署中进程的启动会话）> 进程内随机 id。
- 覆盖走 fetch 的协议，例如 openai-completions / openai-responses / anthropic-messages；transport: websocket 不走 fetch，不在范围内。
- 全局 fetch 包装只在匹配到 opencode 端点时追加请求头，其他什么都不改。线上 token 是 session-<uuid> 中 uuid 部分的单向 SHA-256 哈希（不含 session- 前缀，例如 0RpJJnxJ），所以后端无法反推出原始 id；改动 nanoidAlphabet / nanoidLength 会让每个 token 都变，与旧记录的关联随之失效。