@kinski/opencode-web-gateway 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 opencode-web-gateway contributors
+
+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,168 @@
-# Temporary Holding Version
+# opencode-web-gateway
 
-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.
+浏览器出网桥：让 opencode 的原生 **DeepSeek provider** 只访问本机，真正请求 DeepSeek 的 `fetch` 由网页完成。
+
+插件在本机 `127.0.0.1:8787` 启动端点；页面主动通过 WebSocket 连接插件，转发原始请求体和响应字节（包括 SSE），不解析、不改写。
+
+- **不捆绑 opencode**：使用你已安装的 opencode；本包包含全局 CLI、插件和网页
+- **只影响 DeepSeek 通路**：保留 opencode 原生 `deepseek` provider、原生模型目录和 `/connect`，只覆盖它的 `baseURL`
+- **参数透传**：`temperature`、`top_p`、`tools`、reasoning 等由 opencode 原生 provider 构造，插件按字节转发
+- **Key 原样透传**：只使用 `/connect` 或 `DEEPSEEK_API_KEY` 的凭据；插件不保存、不注入、不覆盖
+- 插件内嵌完整网页，不需要额外前端资源
+- 同一份插件支持 opencode v1（`server()`）和 v2（`setup()`）
+- 默认只监听回环地址；跨源页面需要显式加入 `allowedOrigins`
+
+## 安装（推荐：全局 CLI）
+
+```bash
+npm install -g @kinski/opencode-web-gateway
+opencode-web-gateway
+```
+
+`npm install -g` 会把 `opencode-web-gateway` 写到 PATH。之后在任何目录运行：
+
+```bash
+opencode-web-gateway
+# 不自动打开浏览器
+opencode-web-gateway --no-open
+
+# 直接跑一次
+opencode-web-gateway run -m deepseek/deepseek-flash "hello"
+```
+
+它做三件事：
+
+1. 调用你系统已安装的 `opencode`，不捆绑 opencode；
+2. 通过额外的 opencode config source 加载本包插件，并只覆盖原生 `deepseek` 的 `baseURL`；
+3. 等本地桥接页就绪后自动打开页面。
+
+不会改写你的项目 `opencode.json`、全局 opencode 配置、`/connect` 或 auth 存储。除 Node.js 外不需要 bash、PowerShell 或额外的项目文件。
+
+要求：Node.js 20+，并且 `opencode` 已在 PATH（也可用 `OPENCODE_BIN` 指定）。
+
+## 可选：项目内手动配置
+
+如果不想用全局 CLI，也可以把本包作为普通 opencode 插件加载，并在项目配置里覆盖 DeepSeek `baseURL`：
+
+opencode v2 的 `opencode.jsonc`：
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-web-gateway"]
+}
+```
+
+opencode v1 的 `opencode.json`：
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-web-gateway"]
+}
+```
+
+## 只覆盖原生 DeepSeek 的 baseURL
+
+不要创建自定义 provider。把原生 `deepseek` 的端点改到本地即可：
+
+opencode v1：
+
+```json
+{
+  "provider": {
+    "deepseek": {
+      "options": {
+        "baseURL": "http://127.0.0.1:8787/v1"
+      }
+    }
+  }
+}
+```
+
+opencode v2：
+
+```jsonc
+{
+  "providers": {
+    "deepseek": {
+      "settings": {
+        "baseURL": "http://127.0.0.1:8787/v1"
+      }
+    }
+  }
+}
+```
+
+完整示例见 [`examples/opencode.v1.json`](examples/opencode.v1.json) 和 [`examples/opencode.v2.jsonc`](examples/opencode.v2.jsonc)。
+
+原生模型目录会保留（当前为 `deepseek/deepseek-flash`、`deepseek/deepseek-v4-pro`），provider ID 仍是 `deepseek`，所以 `/connect`、模型 capability、工具调用和参数映射都不变。
+
+## 连接与 Key
+
+推荐直接使用 opencode 原生流程：
+
+```text
+/connect  ->  DeepSeek  ->  粘贴 API Key
+```
+
+或在启动前设置 `DEEPSEEK_API_KEY`。插件将 opencode 发来的 `Authorization` 原样转发给页面，不保存、不注入、不覆盖。
+
+`web-gateway.config.json` 只用于上游、端口、跨源页面等传输配置：
+
+```json
+{
+  "upstream": "https://api.deepseek.com",
+  "host": "127.0.0.1",
+  "port": 8787,
+  "allowedOrigins": [],
+  "waitForBridgeMs": 15000
+}
+```
+
+## 使用
+
+1. 启动 opencode，`/connect` 连接 DeepSeek（或设置 `DEEPSEEK_API_KEY`）。
+2. 打开 <http://127.0.0.1:8787/>，保持标签页打开。
+3. 页面显示“已连接”后，在 opencode 中执行 `/models`，选择原生 DeepSeek 模型（如 `deepseek/deepseek-flash`）。
+4. 如果请求时页面还没打开，请求会等待 `waitForBridgeMs`（默认 15 秒），然后返回 503。
+
+## 托管页面（pages.dev）
+
+页面也可以部署到 Cloudflare Pages 等静态托管。页面会默认连接 `ws://127.0.0.1:8787/bridge`。
+
+跨源页面默认会被插件拒绝。部署后，在本机 `web-gateway.config.json` 加入页面来源：
+
+```json
+{
+  "allowedOrigins": ["https://kinski-opencode-web-gateway.pages.dev"]
+}
+```
+
+然后刷新 opencode/插件，再打开托管页面。HTTPS 页面连接本机回环 `ws://127.0.0.1` 已在 Chrome 验证；如果浏览器拦截混合内容，直接使用插件自带的 <http://127.0.0.1:8787/> 即可。
+
+## 配置项
+
+| 字段 | 默认 | 说明 |
+| --- | --- | --- |
+| `upstream` | `https://api.deepseek.com` | 浏览器实际 fetch 的上游 |
+| `host` | `127.0.0.1` | 监听地址；`0.0.0.0` 可供局域网页面连接 |
+| `port` | `8787` | 本地端口，修改后同步修改 provider 的 `baseURL` |
+| `allowedOrigins` | `[]` | 允许跨源 WebSocket 的页面来源列表（精确 origin） |
+| `token` | `""` | 可选的页面访问令牌 |
+| `waitForBridgeMs` | `15000` | 没有页面时请求等待时间 |
+
+## 安全
+
+- 使用 `/connect` 时，Key 在 opencode 的 auth 存储中；插件不改写它，只在转发瞬间把 `Authorization` 交给页面。
+- 页面 HTML、bootstrap、localStorage、日志都不保存 Key。
+- 默认监听 `127.0.0.1`；跨源页面必须显式加入 `allowedOrigins`。
+- 可使用 `token` 增加一道页面访问校验。
+- 页面只转发，不解析 SSE；上游必须允许浏览器 CORS（DeepSeek 已支持）。
+
+## 兼容性
+
+- 已测试：opencode **1.19.5**（v1 API）与 **2.2.0**（v2 API），包含原生 `/connect` 凭据透传。
+- 1.18.x 的 Bun 运行时对 `node:http` upgrade socket 写入不刷新，不适用于本 WebSocket 桥。
+
+MIT License

package/bin/opencode-web-gateway.js

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+// Global CLI: run the system opencode with this package loaded as a plugin.
+// No shell scripts and no changes to the opencode config on disk.
+
+import { spawn, spawnSync } from "node:child_process"
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+const packageRoot = path.resolve(here, "..")
+const packageJson = JSON.parse(readFileSync(path.join(packageRoot, "package.json"), "utf8"))
+
+const help = `Usage: opencode-web-gateway [--no-open] [opencode args...]
+
+Runs the system opencode with the opencode-web-gateway plugin loaded and
+DeepSeek's baseURL pointed at the local bridge. Project opencode config is
+preserved; the gateway is added through an extra config source.
+
+Options:
+  --no-open        Do not open the bridge page in a browser
+  -h, --help       Show this help
+  -v, --version    Print the CLI version
+
+Everything after the options is passed to opencode, for example:
+  opencode-web-gateway run -m deepseek/deepseek-flash "hello"
+`
+
+let args = process.argv.slice(2)
+let noOpen = false
+
+if (args[0] === "--help" || args[0] === "-h") {
+  process.stdout.write(help)
+  process.exit(0)
+}
+if (args[0] === "--version" || args[0] === "-v") {
+  console.log(packageJson.version)
+  process.exit(0)
+}
+while (args[0] === "--no-open") {
+  noOpen = true
+  args = args.slice(1)
+}
+
+const DEFAULT_CONFIG = {
+  upstream: "https://api.deepseek.com",
+  host: "127.0.0.1",
+  port: 8787,
+  allowedOrigins: [],
+  waitForBridgeMs: 15000,
+}
+
+function fail(message) {
+  console.error(message)
+  process.exitCode = 1
+}
+
+function readConfig() {
+  const candidates = [
+    process.env.OPENCODE_WEB_GATEWAY_CONFIG,
+    path.join(process.cwd(), "web-gateway.config.json"),
+    path.join(process.cwd(), ".opencode", "web-gateway.config.json"),
+  ].filter(Boolean)
+
+  for (const candidate of candidates) {
+    if (!existsSync(candidate)) continue
+    try {
+      const value = JSON.parse(readFileSync(candidate, "utf8"))
+      if (!value || typeof value !== "object" || Array.isArray(value)) continue
+      return { path: path.resolve(candidate), value }
+    } catch {
+      console.warn(`warning: ignoring invalid config ${candidate}`)
+    }
+  }
+  return null
+}
+
+function displayHost(host) {
+  if (host === "0.0.0.0") return "127.0.0.1"
+  if (host === "::" || host === "0:0:0:0:0:0:0:0") return "[::1]"
+  if (host.includes(":") && !host.startsWith("[")) return `[${host}]`
+  return host
+}
+
+function openBrowser(url) {
+  try {
+    if (process.platform === "win32") {
+      spawn(process.env.ComSpec || "cmd.exe", ["/d", "/s", "/c", `start "" "${url}"`], {
+        stdio: "ignore",
+        windowsHide: true,
+      }).unref()
+    } else if (process.platform === "darwin") {
+      spawn("open", [url], { stdio: "ignore", detached: true }).unref()
+    } else {
+      spawn("xdg-open", [url], { stdio: "ignore", detached: true }).unref()
+    }
+  } catch {
+    // The URL is printed above; opening a browser is best-effort.
+  }
+}
+
+async function openWhenReady(url, child) {
+  const deadline = Date.now() + 10_000
+  while (Date.now() < deadline) {
+    if (child.exitCode !== null) return
+    try {
+      const response = await fetch(`${url}healthz`, { signal: AbortSignal.timeout(500) })
+      if (response.ok) {
+        openBrowser(url)
+        return
+      }
+    } catch {
+      // server not up yet
+    }
+    await new Promise((resolve) => setTimeout(resolve, 250))
+  }
+  openBrowser(url)
+}
+
+const opencode = process.env.OPENCODE_BIN || (process.platform === "win32" ? "opencode.exe" : "opencode")
+const probe = spawnSync(opencode, ["--version"], {
+  encoding: "utf8",
+  windowsHide: true,
+})
+if (probe.error || probe.status !== 0) {
+  fail(
+    `opencode was not found (${opencode}).\n` +
+      "Install opencode with its normal installer, or set OPENCODE_BIN to the executable.",
+  )
+  process.exit()
+}
+
+const opencodeVersionText = `${probe.stdout || ""}\n${probe.stderr || ""}`
+const opencodeVersion = (opencodeVersionText.match(/\d+\.\d+\.\d+/) || ["unknown"])[0]
+const opencodeMajor = Number(opencodeVersion.split(".")[0]) || 0
+
+const found = readConfig()
+const config = { ...DEFAULT_CONFIG, ...(found ? found.value : {}) }
+const port = Number(config.port) || DEFAULT_CONFIG.port
+const host = String(config.host || DEFAULT_CONFIG.host)
+const pageUrl = `http://${displayHost(host)}:${port}/`
+
+const temp = mkdtempSync(path.join(tmpdir(), "opencode-web-gateway-"))
+const cleanup = () => {
+  try {
+    rmSync(temp, { recursive: true, force: true })
+  } catch {
+    // best effort
+  }
+}
+process.on("exit", cleanup)
+
+let configPath = found ? found.path : ""
+if (!configPath) {
+  configPath = path.join(temp, "web-gateway.config.json")
+  writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8")
+}
+
+const baseURL = `http://${displayHost(host)}:${port}/v1`
+const pluginPath = packageRoot.replace(/\\/g, "/")
+const overlay = {
+  plugin: [pluginPath],
+  provider: {
+    deepseek: {
+      options: { baseURL },
+    },
+  },
+  providers: {
+    deepseek: {
+      settings: { baseURL },
+    },
+  },
+}
+const overlayPath = path.join(temp, "opencode.json")
+writeFileSync(overlayPath, `${JSON.stringify(overlay, null, 2)}\n`, "utf8")
+
+const env = {
+  ...process.env,
+  OPENCODE_WEB_GATEWAY_CONFIG: configPath,
+}
+
+if (!process.env.OPENCODE_CONFIG) {
+  env.OPENCODE_CONFIG = overlayPath
+} else if (!process.env.OPENCODE_CONFIG_CONTENT) {
+  // Keep the caller's OPENCODE_CONFIG and add the bridge overlay as a document.
+  env.OPENCODE_CONFIG_CONTENT = JSON.stringify(overlay)
+} else {
+  fail(
+    "Both OPENCODE_CONFIG and OPENCODE_CONFIG_CONTENT are set in this environment.\n" +
+      "opencode-web-gateway needs one config slot for its overlay; unset one of them.",
+  )
+  process.exit()
+}
+
+const finalArgs = [...args]
+const has = (flag) => finalArgs.includes(flag)
+if (opencodeMajor >= 2 && !has("--standalone") && !has("--server") && !has("--version") && !has("-v") && !has("--help") && !has("-h")) {
+  finalArgs.unshift("--standalone")
+}
+
+const firstCommand = args.find((arg) => !arg.startsWith("-"))
+const wantsPage = !noOpen && (!firstCommand || firstCommand === "run" || firstCommand === "serve")
+
+console.log(`opencode-web-gateway ${packageJson.version}`)
+console.log(`  opencode ${opencodeVersion}`)
+console.log(`  page     ${pageUrl}`)
+console.log(`  config   ${configPath}`)
+if (noOpen) console.log("  browser  disabled (--no-open)")
+
+let child
+try {
+  child = spawn(opencode, finalArgs, {
+    cwd: process.cwd(),
+    env,
+    stdio: "inherit",
+    windowsHide: false,
+  })
+} catch (error) {
+  fail(`could not start opencode: ${error instanceof Error ? error.message : String(error)}`)
+  process.exit()
+}
+
+child.on("error", (error) => {
+  fail(`could not start opencode: ${error.message}`)
+  cleanup()
+})
+child.on("exit", (code, signal) => {
+  cleanup()
+  process.exitCode = code ?? (signal ? 1 : 0)
+})
+
+if (wantsPage) {
+  void openWhenReady(pageUrl, child)
+}