dsh-endpoint 0.0.0-stage → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## [1.0.1] - 2026-11-02
+
+- `/healthz` and the settings page report the running version.
+- `limits.maxTextFileBytes` (default 1 MiB) controls how much of one inline text
+  file is inlined; the request body cap remains the hard ceiling.
+
+## [1.0.0] - 2026-11-02
+
+First public release.
+
+- OpenAI-compatible `POST /v1/chat/completions` (streaming and non-streaming) and
+  `GET /v1/models`, every call forwarded through `ctx.llm.stream()`.
+- Tool calls pass through both ways; inline images and text files are supported.
+- Stable conversation identity and read-only session mirroring into DSH.
+- Settings page (Chinese/English) with in-place listener rebind.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wangzhongyang
+
+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

@@ -1,3 +1,263 @@
-# Temporary Holding Version
+# dsh-endpoint
 
-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.
+[![npm](https://img.shields.io/npm/v/dsh-endpoint)](https://www.npmjs.com/package/dsh-endpoint)
+[![license](https://img.shields.io/npm/l/dsh-endpoint)](LICENSE)
+[![ci](https://github.com/wangzhongyang/dsh-endpoint/actions/workflows/ci.yml/badge.svg)](https://github.com/wangzhongyang/dsh-endpoint/actions/workflows/ci.yml)
+
+Expose the model providers and models already configured in DeepSeek Harness as an
+OpenAI-compatible HTTP endpoint.
+
+The endpoint only forwards. It holds no provider credentials and never talks to a
+provider directly: every model call goes through `ctx.llm.stream()`, so DSH's provider
+adapters (credentials, protocol differences, retries, image handling, token usage) keep
+owning the real request.
+
+[中文](README.zh.md)
+
+## Architecture
+
+```
+OpenAI-compatible client
+   │  POST /v1/chat/completions
+   ▼
+┌────────────────────── DSH host process ───────────────────────┐
+│  dsh-endpoint (Cordis plugin)                                 │
+│   HTTP listener → OpenAI mapping → SessionMirror → ctx.llm     │
+│                                          │                     │
+│                        dsh-llm-pi-ai / dsh-llm-deepseek-*      │
+└──────────────────────────────────────────┼─────────────────────┘
+                                           ▼
+                                   provider API
+```
+
+- **Plugin only.** No second process, no second credential store.
+- **Sessions are real.** Each conversation is mirrored into a DSH session, so it shows
+  up in the sidebar and can be inspected.
+- **Read-only mirrors.** The mirrored session holds the persistence write handle, so the
+  GUI refuses to resume it (`already owned by an active write handle`).
+
+## Install
+
+Requires DeepSeek Harness Desktop (web profile) 0.2.1-rc.x.
+
+From npm:
+
+```sh
+dsh plugin --profile web add dsh-endpoint
+```
+
+From a checkout (useful while developing):
+
+```sh
+dsh plugin --profile web add /absolute/path/to/dsh-endpoint
+```
+
+In the Desktop app you can also use **Settings → Plugins** and install it from the
+market once the package is listed.
+
+> **No authentication, no rate limiting.** The endpoint spends your configured
+> model quota for anyone who can reach it. Keep it on `127.0.0.1` unless you put
+> it behind a proxy you control, and disable the plugin to switch it off.
+
+Restart the app after installing: host plugins are ESM modules, and reinstalling does
+not replace the module already loaded in the running process.
+
+## Settings page
+
+**Settings → Model Endpoint** (a custom section, same level as plugin pages).
+
+![dsh-endpoint settings page](docs/settings.png)
+
+| Field | Meaning |
+|---|---|
+| Listen address | `127.0.0.1` (local only) or `0.0.0.0` (all interfaces) |
+| Port | default `43130`; the GUI owns `43129` |
+| Default model | used when a request omits `model` |
+| Model aliases | JSON map, e.g. `{"gpt-4o": "opencode-go/deepseek-v4.1-flash"}` |
+| Session mirror | write each API conversation into a DSH session |
+| Mapping retention | days an external conversation id keeps its session after last use |
+| Workspace directory | workspace that groups mirrored sessions |
+
+Saving applies immediately: **changing the listen address or port rebinds the listener
+in place** (the old listener closes, the new one binds, and a failed bind rolls back to
+the previous address). Switching `127.0.0.1 ↔ 0.0.0.0` takes the same path. Toggling the
+mirror or changing the workspace directory still needs a plugin reload, because those are
+built at startup.
+
+In-flight streaming responses are dropped when the listener moves.
+
+The page reads and writes two loopback-only routes: `GET /dsh-endpoint/state` and
+`GET|PUT /dsh-endpoint/config`. Saves go to the user layer
+`$DSH_HOME/dsh-endpoint/config.json`, which is merged over the plugin config at startup.
+
+## HTTP API
+
+| Method | Path | Notes |
+|---|---|---|
+| `GET` | `/healthz` | liveness + registered providers |
+| `GET` | `/v1/models` | `provider/model` ids plus aliases |
+| `GET` | `/v1/models/{id}` | one model |
+| `POST` | `/v1/chat/completions` | streaming and non-streaming |
+
+Model ids are `provider/model`, e.g. `opencode-go/deepseek-v4.1-flash`.
+
+**Supported:** `messages` (system/user/assistant/tool), `tools` and `tool_calls`
+pass-through, `temperature`, `max_tokens` / `max_completion_tokens`, `stream`,
+`stream_options.include_usage`, `stop` (truncated endpoint-side because not every
+adapter accepts it).
+
+**Rejected explicitly:** `n > 1`, `tool_choice` other than `"auto"`, remote (`http(s)`) media
+URLs, `file_id` references, and binary documents (PDF/DOCX).
+
+## Attachments
+
+Inline base64 only — the endpoint never fetches remote URLs on a client's behalf.
+
+| Input | Handling |
+|---|---|
+| `image_url` with `data:image/{png,jpeg,webp,gif};base64,…` | decoded → `ctx.attachments.saveImages` → `ImageBlock`; the adapter resizes per route |
+| `image_url` with `http(s)://…` | 400: send a data URL instead |
+| `file` part with `file_data` of `text/*`, JSON, YAML, XML, JS, SQL | inlined as a `text` block (512 KiB cap, filename preserved) |
+| `file` part with a binary document (PDF, DOCX, …) | 400: text extraction is not implemented |
+| `file` part with `file_id` | 400: the Files API is not implemented |
+
+Attachments live in DSH's attachment store, so the mirrored session keeps a compact reference
+instead of megabytes of base64.
+
+### Limits
+
+| Limit | Value | Source |
+|---|---|---|
+| Request body | 8 MiB | `limits.maxBodyBytes`, a plugin default |
+| One inline text file | 1 MiB, truncated with a marker | `limits.maxTextFileBytes`, a plugin default |
+| One image | 20 MiB | DSH attachment service (not this plugin) |
+| Images per message | 20 | DSH attachment service |
+| Total image bytes per message | 200 MiB | DSH attachment service |
+| Image pixels / longest side | 64 MP / 8192 px | DSH attachment service |
+
+The text-file cap is a prompt-size guard, not a protocol limit: the body is already
+bounded by `maxBodyBytes`, and a file near the cap is far past most models' context
+windows. Truncation is announced in the inlined text, so the model knows it is partial.
+
+**Ignored on purpose:** every other unknown field (`top_p`, `seed`, `service_tier`,
+`metadata`, …). Real clients send fields this build does not model; rejecting them would
+break more than it protects, so they are logged and dropped rather than silently applied.
+
+## Session identity
+
+Resolution order, first hit wins:
+
+1. `x-dsh-session-id` (this plugin's own header)
+2. known agent headers: `x-session-id`, `x-conversation-id`, `x-chat-id`, `x-thread-id`,
+   `x-agent-session-id`, `x-claude-code-session-id`, `x-codex-session-id`
+3. body fields: `session_id`, `conversation_id`, `chat_id`, `thread_id`,
+   `metadata.session_id`, `metadata.conversation_id`, `user`
+4. content fingerprint: `sha256(model + first user message)` — deterministic across
+   requests and restarts
+5. only when there is no user message at all, a fresh id is minted
+
+`x-request-id`, `x-correlation-id` and `x-trace-id` are never treated as session ids.
+
+Every response echoes `x-dsh-session-id`. Clients may send it back to pin the
+conversation; clients that send nothing still get a stable id from step 4.
+
+Only new user/tool messages are appended to the mirrored session (assistant messages are
+always the ones this endpoint produced), so logs grow per turn instead of quadratically.
+If the client's user history diverges from what was recorded, a new DSH session is
+started and the divergence is logged.
+
+## Supported clients
+
+Any client that can point an OpenAI-compatible provider at a custom base URL:
+
+```bash
+export OPENAI_BASE_URL=http://127.0.0.1:43130/v1
+export OPENAI_API_KEY=anything          # there is no auth; any placeholder works
+```
+
+| Client | How to configure | Status |
+|---|---|---|
+| `curl` / any HTTP client | POST the body directly | verified |
+| OpenAI Python SDK | `OpenAI(base_url="http://127.0.0.1:43130/v1", api_key="any")` | request shape verified |
+| OpenAI Node SDK | `new OpenAI({ baseURL: "http://127.0.0.1:43130/v1", apiKey: "any" })` | request shape verified |
+| Cline (VS Code) | Provider: OpenAI Compatible → Base URL + any key | expected; not yet end-to-end tested |
+| Roo Code (VS Code) | Provider: OpenAI Compatible | expected; not yet end-to-end tested |
+| Continue (VS Code / JetBrains) | `provider: openai`, `apiBase: http://127.0.0.1:43130/v1` | expected; not yet end-to-end tested |
+| OpenCode (CLI) | custom provider in `opencode.json`, see below | **verified**, tool loop included |
+| Cherry Studio | Add provider → OpenAI → API Host | expected |
+| Chatbox | Model provider → OpenAI API → API Host | expected |
+| LobeChat | OpenAI provider → proxy/base URL | expected |
+| Open WebUI | Connections → OpenAI → Base URL | expected |
+
+### OpenCode
+
+Model ids contain a slash, which breaks `provider/model` parsing on the client, so add a
+slash-free alias first (Settings → Model Endpoint → Model aliases), e.g.
+`{"flash": "opencode-go/deepseek-v4.1-flash"}`. Then point a project `opencode.json` at the
+endpoint:
+
+```json
+{
+  "provider": {
+    "dsh": {
+      "name": "DSH Endpoint",
+      "npm": "@ai-sdk/openai-compatible",
+      "options": { "baseURL": "http://127.0.0.1:43130/v1", "apiKey": "anything" },
+      "models": { "flash": { "name": "DeepSeek via DSH" } }
+    }
+  }
+}
+```
+
+```sh
+opencode run -m dsh/flash "list the files here and tell me which is largest"
+```
+
+A ready-to-copy file lives at [`examples/opencode.json`](examples/opencode.json).
+
+OpenCode sends `x-session-id`, which the endpoint already treats as the conversation key,
+so a whole multi-step tool loop lands in one mirrored session.
+
+Tool calls are forwarded both ways (`tools` in, `tool_calls` out); OpenCode's shell/read
+tool loop has been verified end to end.
+
+## Limitations
+
+- No authentication and no rate limiting. The stop switch is disabling the plugin. Keep
+  it on `127.0.0.1`; binding `0.0.0.0` lets anyone who can reach the port spend your quota.
+- Inline images and text files only; remote media URLs and binary documents are refused.
+- `n > 1`, `tool_choice` other than `auto`, `logprobs`, `top_p`, `seed` are not applied.
+- Mirrored sessions cannot be continued in the GUI by design.
+- Pinned to DSH internal packages (`0.2.1-rc.x`); API changes there can break this plugin.
+
+## Development
+
+```sh
+pnpm install
+node --test                              # 47 cases, no DSH required
+node spike/mock-provider.mjs 44001       # local fake provider
+```
+
+`spike/` also contains the P0 harness that creates a session in a throwaway `DSH_HOME`,
+persists it, restores it, and checks that GUI takeover is refused (`spike/run.sh`).
+
+## Verified / not verified
+
+Verified on a real Desktop install:
+
+- `/v1/models` (31 models across `opencode-go`, `deepseek-official`, `deepseek-account`)
+- non-streaming and streaming chat with usage
+- the same conversation twice → the same `x-dsh-session-id`
+- mirrored session persists with `turn/start → step/start → user → assistant → step/end →
+  turn/end`, second turn appends only the new user message
+- mirrored sessions appear in the sidebar workspace
+- `agentLoop.resume` refused while the write handle is held
+- settings page: section registered, config read/write round-trip
+- live listener rebind (`43130 → 43131 → 43130`) without restarting the app
+- inline image input (a 1152×883 screenshot was described correctly)
+- OpenCode driving a full tool loop (two shell calls in one turn, mirrored with tool results)
+
+Not verified yet:
+
+- other IDE agents (Cline, Roo Code, Continue)
+- multiple concurrent conversations against one provider quota

package/README.zh.md

@@ -0,0 +1,244 @@
+# dsh-endpoint
+
+[![npm](https://img.shields.io/npm/v/dsh-endpoint)](https://www.npmjs.com/package/dsh-endpoint)
+[![license](https://img.shields.io/npm/l/dsh-endpoint)](LICENSE)
+[![ci](https://github.com/wangzhongyang/dsh-endpoint/actions/workflows/ci.yml/badge.svg)](https://github.com/wangzhongyang/dsh-endpoint/actions/workflows/ci.yml)
+
+把 DeepSeek Harness 里已经配置好的模型供应商和模型，暴露成一个 OpenAI 兼容的 HTTP 端点。
+
+端点只负责转发：它不持有任何 provider 凭据，也不直接访问三方 API。每一次模型调用都走
+`ctx.llm.stream()`，凭据、协议差异、重试、图片处理、用量统计仍然由 DSH 的 provider 适配器负责。
+
+[English](README.md)
+
+## 架构
+
+```
+OpenAI 兼容客户端
+   │  POST /v1/chat/completions
+   ▼
+┌────────────────────── DSH Host 进程 ──────────────────────────┐
+│  dsh-endpoint（Cordis 插件）                                   │
+│   HTTP listener → OpenAI 映射 → SessionMirror → ctx.llm        │
+│                                          │                     │
+│                        dsh-llm-pi-ai / dsh-llm-deepseek-*      │
+└──────────────────────────────────────────┼─────────────────────┘
+                                           ▼
+                                      三方模型 API
+```
+
+- **只做插件**：没有第二个进程，也没有第二套凭据。
+- **会话是真的**：每段对话镜像成一条 DSH 会话，侧栏可见、可查看。
+- **镜像只读**：镜像会话持有持久化写句柄，GUI 里点「继续」会被拒
+  （`already owned by an active write handle`）。
+
+## 安装
+
+需要 DeepSeek Harness Desktop（web profile）0.2.1-rc.x。
+
+从 npm 安装：
+
+```sh
+dsh plugin --profile web add dsh-endpoint
+```
+
+从源码目录安装（开发时用）：
+
+```sh
+dsh plugin --profile web add /absolute/path/to/dsh-endpoint
+```
+
+在 Desktop 里也可以走 **设置 → 插件**，等包进入市场后直接搜 `dsh-endpoint`。
+
+> **没有鉴权、没有限流。** 谁能连上这个端口，就能花你配置的模型额度。除非前面有你自己
+> 控制的反向代理，否则请保持在 `127.0.0.1`；停用插件就是关闭它。
+
+安装后要重启应用：宿主插件是 ESM 模块，重装只换磁盘快照，不换已经加载进进程的模块。
+
+## 设置页
+
+**设置 → 模型端点**（自定义分区，和插件页同级）。
+
+![dsh-endpoint 设置页](docs/settings.png)
+
+| 字段 | 含义 |
+|---|---|
+| 监听地址 | `127.0.0.1`（仅本机）或 `0.0.0.0`（所有网卡） |
+| 端口 | 默认 `43130`；GUI 占用 `43129` |
+| 默认模型 | 请求不带 `model` 时使用 |
+| 模型别名 | JSON 映射，例如 `{"gpt-4o": "opencode-go/deepseek-v4.1-flash"}` |
+| 会话镜像 | 把每段 API 对话写成一条 DSH 会话 |
+| 映射保留 | 外部会话 ID 超过多少天没再用就解绑 |
+| 工作区目录 | 镜像会话归属的 workspace |
+
+保存即时生效：**改监听地址或端口会就地重绑 listener**（先关旧的、再绑新的，绑定失败回滚到
+原地址）。`127.0.0.1 ↔ 0.0.0.0` 走同一条路径。切换镜像开关、改工作区目录仍然需要重载插件，
+因为它们在启动时构建。
+
+重绑时正在进行的流式响应会断开。
+
+页面通过两条 loopback 路由读写：`GET /dsh-endpoint/state`、`GET|PUT /dsh-endpoint/config`。
+保存写入用户层 `$DSH_HOME/dsh-endpoint/config.json`，启动时叠加在插件 config 之上。
+
+## HTTP 接口
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| `GET` | `/healthz` | 存活 + 已注册 provider |
+| `GET` | `/v1/models` | `provider/model` 列表 + 别名 |
+| `GET` | `/v1/models/{id}` | 单个模型 |
+| `POST` | `/v1/chat/completions` | 流式与非流式 |
+
+模型名为 `provider/model`，例如 `opencode-go/deepseek-v4.1-flash`。
+
+**支持**：`messages`（system/user/assistant/tool）、`tools` 与 `tool_calls` 透传、
+`temperature`、`max_tokens` / `max_completion_tokens`、`stream`、
+`stream_options.include_usage`、`stop`（端侧截断，因为不是所有适配器都接受它）。
+
+**明确拒绝**：`n > 1`、`tool_choice` 非 `"auto"`、远程（`http(s)`）媒体 URL、`file_id`
+引用、二进制文档（PDF/DOCX）。
+
+## 附件
+
+只接受内联 base64——端点不会代替客户端去下载远程地址。
+
+| 输入 | 处理 |
+|---|---|
+| `image_url` + `data:image/{png,jpeg,webp,gif};base64,…` | 解码 → `ctx.attachments.saveImages` → `ImageBlock`，由适配器按路由缩放 |
+| `image_url` + `http(s)://…` | 400，要求改用 data URL |
+| `file` 部件的 `file_data` 为 `text/*`、JSON、YAML、XML、JS、SQL | 直接内联成 `text` 块（上限 512 KiB，保留文件名） |
+| `file` 部件为二进制文档（PDF、DOCX 等） | 400，未实现文本抽取 |
+| `file` 部件用 `file_id` | 400，未实现 Files API |
+
+附件存放在 DSH 的附件库里，所以镜像会话只保留一个紧凑引用，而不是几 MB 的 base64。
+
+### 限制
+
+| 限制 | 值 | 来源 |
+|---|---|---|
+| 请求体 | 8 MiB | 插件默认值 `limits.maxBodyBytes` |
+| 单个内联文本文件 | 1 MiB，超出会截断并标注 | 插件默认值 `limits.maxTextFileBytes` |
+| 单张图片 | 20 MiB | DSH 附件服务（不是本插件） |
+| 每条消息图片数 | 20 | DSH 附件服务 |
+| 每条消息图片总字节 | 200 MiB | DSH 附件服务 |
+| 图片像素 / 最长边 | 64 MP / 8192 px | DSH 附件服务 |
+
+文本文件这个上限是**提示词体积保护**，不是协议限制：整个请求体已经被 `maxBodyBytes` 卡住，
+而接近这个上限的文件早就超出多数模型的上下文窗口了。截断会在内联文本里明确写出来，模型知道
+自己拿到的是片段。
+
+**故意忽略**：其余未知字段（`top_p`、`seed`、`service_tier`、`metadata` …）。真实客户端
+会发一堆本版本没有建模的字段，严格拒绝会破坏更多东西，所以记录日志后丢弃，而不是假装生效。
+
+## 会话身份
+
+解析顺序，先命中先用：
+
+1. `x-dsh-session-id`（本插件自己的头）
+2. 已知 agent 会话头：`x-session-id`、`x-conversation-id`、`x-chat-id`、`x-thread-id`、
+   `x-agent-session-id`、`x-claude-code-session-id`、`x-codex-session-id`
+3. body 字段：`session_id`、`conversation_id`、`chat_id`、`thread_id`、
+   `metadata.session_id`、`metadata.conversation_id`、`user`
+4. 内容指纹：`sha256(model + 首条 user 消息)`——跨请求、跨重启都是确定值
+5. 只有在完全没有 user 消息时，才新生成
+
+`x-request-id`、`x-correlation-id`、`x-trace-id` 永远不会被当成会话 ID。
+
+每个响应都回写 `x-dsh-session-id`。客户端回传即可锁定这段对话；什么都不发的客户端也能靠
+第 4 条拿到稳定 ID。
+
+镜像只追加新的 user / tool 消息（assistant 消息永远由本端点自己的流产生），所以日志按轮次
+线性增长，不会二次膨胀。如果客户端的 user 历史与记录的前缀不一致，会新开一条 DSH 会话并记日志。
+
+## 支持的客户端
+
+任何能把 OpenAI 兼容 provider 指向自定义 base URL 的客户端：
+
+```bash
+export OPENAI_BASE_URL=http://127.0.0.1:43130/v1
+export OPENAI_API_KEY=anything          # 没有鉴权，随便填占位符
+```
+
+| 客户端 | 配置方式 | 状态 |
+|---|---|---|
+| `curl` / 任意 HTTP 客户端 | 直接 POST | 已验证 |
+| OpenAI Python SDK | `OpenAI(base_url=..., api_key="any")` | 请求形态已验证 |
+| OpenAI Node SDK | `new OpenAI({ baseURL: ..., apiKey: "any" })` | 请求形态已验证 |
+| Cline（VS Code） | Provider: OpenAI Compatible → Base URL + 任意 key | 理论上可用，未端到端验证 |
+| Roo Code（VS Code） | Provider: OpenAI Compatible | 理论上可用，未端到端验证 |
+| Continue（VS Code / JetBrains） | `provider: openai`、`apiBase: http://127.0.0.1:43130/v1` | 理论上可用，未端到端验证 |
+| OpenCode（CLI） | 在 `opencode.json` 里加自定义 provider，见下 | **已验证**，含工具循环 |
+| Cherry Studio | 添加供应商 → OpenAI → API Host | 理论上可用 |
+| Chatbox | 模型供应商 → OpenAI API → API Host | 理论上可用 |
+| LobeChat | OpenAI provider → 代理/base URL | 理论上可用 |
+| Open WebUI | 连接 → OpenAI → Base URL | 理论上可用 |
+
+### OpenCode
+
+模型 id 里带斜杠，会破坏客户端的 `provider/model` 解析，所以先在设置页加一个无斜杠别名
+（模型别名），例如 `{"flash": "opencode-go/deepseek-v4.1-flash"}`，再在项目里放一个
+`opencode.json`：
+
+```json
+{
+  "provider": {
+    "dsh": {
+      "name": "DSH Endpoint",
+      "npm": "@ai-sdk/openai-compatible",
+      "options": { "baseURL": "http://127.0.0.1:43130/v1", "apiKey": "anything" },
+      "models": { "flash": { "name": "DeepSeek via DSH" } }
+    }
+  }
+}
+```
+
+```sh
+opencode run -m dsh/flash "列出当前目录的文件，告诉我哪个最大"
+```
+
+可直接复制的文件在 [`examples/opencode.json`](examples/opencode.json)。
+
+OpenCode 会发 `x-session-id`，端点本来就把它当会话键，所以整个多步工具循环会落进同一条镜像会话。
+
+工具调用双向透传（进来 `tools`，出去 `tool_calls`）；OpenCode 的 shell/read 工具循环已端到端验证。
+
+## 限制
+
+- 没有鉴权、没有限流。停止开关就是停用插件。请保持在 `127.0.0.1`；绑 `0.0.0.0`
+  意味着同网段任何人都能花你的额度。
+- 只支持内联图片与文本文件；远程媒体 URL 和二进制文档会被拒绝。
+- `n > 1`、`tool_choice` 非 `auto`、`logprobs`、`top_p`、`seed` 都不会生效。
+- 镜像会话按设计不能在 GUI 里继续对话。
+- 绑定 DSH 内部包（`0.2.1-rc.x`），那边接口变化可能导致本插件失效。
+
+## 开发
+
+```sh
+pnpm install
+node --test                              # 47 个用例，不需要 DSH
+node spike/mock-provider.mjs 44001       # 本地假 provider
+```
+
+`spike/` 里还有 P0 验证脚本：在临时 `DSH_HOME` 里创建会话、落盘、恢复，并验证 GUI 接管被拒
+（`spike/run.sh`）。
+
+## 已验证 / 未验证
+
+在真实 Desktop 安装上验证过：
+
+- `/v1/models`（`opencode-go`、`deepseek-official`、`deepseek-account` 共 31 个模型）
+- 非流式与流式对话，含 usage
+- 同一对话两次请求 → 同一个 `x-dsh-session-id`
+- 镜像会话落盘为 `turn/start → step/start → user → assistant → step/end → turn/end`，
+  第二轮只追加新的 user 消息
+- 镜像会话出现在侧栏 workspace
+- 持有写句柄时 `agentLoop.resume` 被拒
+- 设置页：分区已注册、配置读写往返
+- 在线重绑监听地址（`43130 → 43131 → 43130`），不用重启应用
+- 内联图片（1152×883 截图被正确描述）
+- OpenCode 的完整工具循环（一轮两个 shell 调用，连工具结果一起镜像）
+
+尚未验证：
+
+- 其它 IDE agent（Cline、Roo Code、Continue）
+- 同一 provider 额度下的多会话并发

package/SECURITY.md

@@ -0,0 +1,35 @@
+# Security
+
+## Reporting a vulnerability
+
+Please do not open a public issue for security problems. Use GitHub's
+[private vulnerability reporting](https://github.com/wangzhongyang/dsh-endpoint/security/advisories/new)
+on this repository. Include the version, your platform, and reproduction steps;
+you will get an acknowledgement within a few days.
+
+## Threat model
+
+`dsh-endpoint` is a **local development tool**. Its security posture is deliberate
+and documented rather than accidental:
+
+- **No authentication, no rate limiting.** Anyone who can reach the listening port
+  can spend the model quota configured in your harness. This is why the default
+  bind address is `127.0.0.1` and why the plugin logs a warning when you switch to
+  `0.0.0.0`.
+- **No provider credentials.** The plugin never reads or stores API keys. Every
+  call goes through `ctx.llm`, so credentials stay in DSH's credential store and
+  are resolved per request by the provider adapter.
+- **Loopback-only management routes.** The settings page talks to
+  `/dsh-endpoint/state` and `/dsh-endpoint/config` on the GUI server, and both
+  routes reject non-loopback peers.
+- **Remote media URLs are refused.** Only inline `data:` URLs are accepted, so the
+  endpoint cannot be used to make the host fetch arbitrary internal addresses
+  (SSRF).
+
+If you need to expose the endpoint beyond your machine, put it behind a reverse
+proxy that terminates TLS and enforces authentication, and keep the plugin's own
+listener bound to `127.0.0.1`.
+
+## Supported versions
+
+Only the latest released version receives fixes.

package/cordis.patch.yml

@@ -0,0 +1,9 @@
+# Bundle layer for dsh-endpoint.
+#
+# This package is a *bundle*: list it in a profile's `dsh.profile.bundles` and
+# this patch contributes the host plugin that serves the OpenAI-compatible
+# endpoint. Every model call is executed by `ctx.llm`, so provider routing and
+# credentials stay owned by whichever profile mounted the adapters.
+- insert:
+    - id: dsh-endpoint
+      name: dsh-endpoint

package/examples/opencode.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "provider": {
+    "dsh": {
+      "name": "DSH Endpoint",
+      "npm": "@ai-sdk/openai-compatible",
+      "options": {
+        "baseURL": "http://127.0.0.1:43130/v1",
+        "apiKey": "anything"
+      },
+      "models": {
+        "flash": {
+          "name": "DeepSeek V4.1 Flash (via DSH)"
+        }
+      }
+    }
+  }
+}

package/icon.svg

@@ -0,0 +1,13 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128" width="128" height="128" role="img" aria-label="dsh-endpoint">
+  <defs>
+    <linearGradient id="g" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#5b9dff"/>
+      <stop offset="1" stop-color="#2f6fe4"/>
+    </linearGradient>
+  </defs>
+  <rect width="128" height="128" rx="28" fill="url(#g)"/>
+  <path d="M40 52h26a10 10 0 0 1 10 10v14" fill="none" stroke="#fff" stroke-width="8" stroke-linecap="round"/>
+  <path d="M88 76H62a10 10 0 0 1-10-10V52" fill="none" stroke="#fff" stroke-width="8" stroke-linecap="round" opacity=".55"/>
+  <circle cx="88" cy="76" r="7" fill="#fff"/>
+  <circle cx="40" cy="52" r="7" fill="#fff"/>
+</svg>