zcode-qoder-connect 0.0.0-stage → 1.0.0

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "zcode-qoder-connect",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Bring Qoder CN models (DeepSeek-V4-Pro, Qwen3.8-Max, GLM-5.3 …) into ZCode as an OpenAI-compatible provider, reusing the Qoder desktop sign-in — zero configuration.",
+  "description_i18n": {
+    "en": "Bring Qoder CN models into ZCode as an OpenAI-compatible provider, reusing the Qoder desktop sign-in.",
+    "zh-CN": "把 Qoder 国内版的模型(DeepSeek-V4-Pro、Qwen3.8-Max、GLM-5.3 等)复用桌面登录零配置接入 ZCode 的模型供应商。"
+  },
+  "author": {
+    "name": "xiao-hans",
+    "url": "https://github.com/xiao-hans"
+  },
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xiao-hans/zcode-ai-connect.git",
+    "directory": "zcode-qoder-connect"
+  },
+  "homepage": "https://github.com/xiao-hans/zcode-ai-connect/tree/main/zcode-qoder-connect#readme",
+  "bugs": {
+    "url": "https://github.com/xiao-hans/zcode-ai-connect/issues"
+  },
+  "os": [
+    "win32"
+  ],
+  "engines": {
+    "node": ">=18.17.0"
+  },
+  "bin": {
+    "zcode-qoder-connect": "bin/cli.mjs"
+  },
+  "files": [
+    ".zcode-plugin",
+    "bin",
+    "src",
+    "hooks",
+    "skills",
+    "docs",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {},
+  "keywords": [
+    "qoder",
+    "openai-compatible",
+    "provider",
+    "deepseek",
+    "qwen",
+    "glm"
+  ]
+}

package/skills/qoder-models/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: qoder-models
+description: Operate the Qoder model provider — start/stop the local endpoint, check credential and quota, list or refresh the model roster, run daily check-in, and troubleshoot "model fails to respond" errors. Use when the user asks about Qoder models in ZCode, the provider shows no models, a Qoder model errors out, quota balance, or the check-in credits.
+when_to_use: The user mentions Qoder, the Qoder provider, or a Qoder model (DeepSeek-V4-Pro, DeepSeek-Flash, Qwen3.8-Max, Qwen3.8-Flash, GLM-5.3, Fast, Auto), or reports that a model from this provider fails.
+---
+
+# Qoder models in ZCode
+
+This plugin exposes the models inside the **Qoder CN desktop app** as a ZCode
+model provider. Credentials are reused read-only from the Qoder desktop's own
+sign-in vault (DPAPI + AES-GCM `auth.v1.dat`); a PAT
+(`qoder.cn → 账号设置 → 个人访问令牌`) is an optional fallback. A small local
+service translates between OpenAI chat-completions and Qoder's COSY-signed
+gateway protocol:
+
+```
+ZCode ──(OpenAI chat-completions)──▶ 127.0.0.1:39270 ──▶ gateway.qoder.com.cn
+                                       local endpoint      (COSY + WAF encode)
+```
+
+## Where things are
+
+| Thing | Path |
+|---|---|
+| Service + CLI | `${ZCODE_PLUGIN_ROOT}` |
+| State (PAT, endpoint bearer, logs) | `%USERPROFILE%\.zcode-qoder-connect` |
+| Provider entry (registry the picker reads) | `%USERPROFILE%\.zcode\v2\provider_config.json` |
+| Qoder desktop vault (read-only) | `%APPDATA%\com.qodercn.app.stable\auth.v1.dat` |
+
+All CLI commands are run as `node "${ZCODE_PLUGIN_ROOT}/bin/cli.mjs" <command>`.
+
+## The one thing that usually matters
+
+The provider only works while the local endpoint is running. A `SessionStart`
+hook starts it automatically, but if a session reports "model not responding":
+
+```sh
+node "${ZCODE_PLUGIN_ROOT}/bin/cli.mjs" service-status
+```
+
+- **`endpoint … up`** — the service is fine; look elsewhere (quota, credential).
+- **`endpoint … NOT reachable`** — start it:
+  `node "${ZCODE_PLUGIN_ROOT}/bin/cli.mjs" serve --port 39270`
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `serve [--port N]` | Run the endpoint (default 39270) |
+| `status` | Credential tracks (desktop vault / PAT), quota, model roster |
+| `refresh` | Re-pull the model roster from the gateway |
+| `checkin` | Claim today's Qoder check-in credits when a campaign is live |
+| `login <PAT>` | Validate and save a personal access token |
+| `logout` | Drop the saved PAT (desktop vault untouched) |
+| `service-status` | Is the endpoint reachable |
+
+## Diagnosing a failure
+
+1. **Is the endpoint up?** `service-status`. If not reachable, start it.
+2. **Is the desktop dt- token fresh?** `status`. When it reads `dt- 已过期`,
+   the fix is opening the Qoder CN desktop app ONCE so it refreshes the vault
+   (the plugin re-reads it automatically; no re-login needed on this side).
+3. **Quota left?** `status` prints the credits document
+   (`isQuotaExceeded`, `totalUsagePercentage`).
+4. **Free-tier models queue at peak** — the service retries a queued request
+   (code 10605) for ~24s; a 429-ish failure right after usually means the queue
+   was longer still. Retry, or switch to a paid-tier model.
+5. **Model roster changed?** `refresh` then `status`.

package/src/catalog.js

@@ -0,0 +1,58 @@
+/**
+ * Qoder model catalog: the roster the endpoint publishes.
+ *
+ * Content lives in the upstream module (FALLBACK_MODELS plus the live roster
+ * from the Qoder model list); this holder adds the two things the endpoint
+ * needs on top of it — visibility and provenance. Visibility is separate from
+ * content because a signed-out account must expose *no* models: serving the
+ * fallback roster to a signed-out user offers models that can only fail, which
+ * is worse than showing nothing.
+ *
+ * @module zcode-qoder-connect/catalog
+ */
+
+import { FALLBACK_MODELS } from './upstream.js'
+
+/** The roster the endpoint serves before its first successful fetch. */
+function initialRoster() {
+  return [...FALLBACK_MODELS]
+}
+
+export class QoderCatalog {
+  constructor() {
+    this.models = initialRoster()
+    this.visible = false
+    /** Provenance of the roster currently held. */
+    this.source = 'fallback'
+    this.fetchedAtMs = undefined
+  }
+
+  /** Current entries; empty while the catalog has no usable credential. */
+  current() {
+    if (!this.visible) return []
+    return this.models
+  }
+
+  /** Replace the list with a freshly fetched roster. */
+  set(models, { source, fetchedAtMs } = {}) {
+    this.models = [...models]
+    if (source !== undefined) this.source = source
+    this.fetchedAtMs = fetchedAtMs ?? Date.now()
+  }
+
+  isVisible() {
+    return this.visible
+  }
+
+  /** Show or hide the whole catalog. Returns whether the value changed. */
+  setVisible(visible) {
+    if (this.visible === visible) return false
+    this.visible = visible
+    return true
+  }
+
+  /** Models to fall back to when the upstream fetch fails; ignores visibility. */
+  fallback() {
+    return this.models
+  }
+}

package/src/config.js

@@ -0,0 +1,81 @@
+/**
+ * Runtime paths shared across the Qoder connect service.
+ *
+ * Vendor-agnostic shape copied from zcode-trae-connect; only the env var and
+ * state-directory name are Qoder-specific so the credential copy and the
+ * endpoint bearer live under their own folder, never inside the Qoder desktop
+ * app's own files.
+ *
+ * @module zcode-qoder-connect/config
+ */
+
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+
+/**
+ * Root of everything this service owns on disk.
+ *
+ * Deliberately outside the Qoder app's data dir: the credential copy and the
+ * endpoint bearer are this service's state.
+ */
+export function defaultStateDir() {
+  const fromEnv = process.env['ZCODE_QODER_CONNECT_HOME']
+  if (fromEnv !== undefined && fromEnv.trim() !== '') return fromEnv
+  return join(homedir(), '.zcode-qoder-connect')
+}
+
+const state = {
+  stateDir: defaultStateDir(),
+  /** Fixed loopback port; 0 asks the OS for a free port. */
+  port: 0,
+  /** Bearer the OpenAI-compatible endpoint requires. */
+  token: '',
+}
+
+/** Point the service's state (credential copy, caches) at a directory. */
+export function configureStateDir(dir) {
+  if (typeof dir === 'string' && dir !== '') state.stateDir = dir
+}
+
+export function stateDir() {
+  return state.stateDir
+}
+
+export function configureEndpoint({ port, token } = {}) {
+  if (typeof port === 'number' && Number.isInteger(port) && port >= 0 && port <= 65535) state.port = port
+  if (typeof token === 'string' && token !== '') state.token = token
+}
+
+export function endpointConfig() {
+  return { port: state.port, token: state.token }
+}
+
+/** Path of the plugin-owned Qoder credential copy. */
+export function ownAuthPath() {
+  return join(state.stateDir, '.qoder-credentials.json')
+}
+
+/** Path of the persisted endpoint settings (port and bearer). */
+export function endpointPath() {
+  return join(state.stateDir, 'endpoint.json')
+}
+
+/**
+ * The endpoint's bearer, generated once and persisted.
+ *
+ * It has to be a *stable* value rather than a per-process secret: the client
+ * that points at this endpoint records its bearer in its own configuration
+ * file, so a token rotating on every start would break it on restart.
+ */
+export function loadToken(fallback) {
+  if (state.token !== '') return state.token
+  if (typeof fallback === 'string' && fallback !== '') {
+    state.token = fallback
+    return state.token
+  }
+  return ''
+}
+
+export function setToken(token) {
+  if (typeof token === 'string') state.token = token
+}

package/src/credentials.js

@@ -0,0 +1,185 @@
+// credentials.js — Qoder credential handling for zcode-qoder-connect.
+//
+// Two tracks, tried in order:
+//   1. PAT  — a personal access token pasted by the human into
+//             %USERPROFILE%\.zcode-qoder-connect\pat.txt (generated at
+//             qoder.cn → 账号设置 → 个人访问令牌). Exchanged at
+//             POST {openapi}/api/v1/jobToken/exchange {personal_token}.
+//   2. Desktop — Qoder CN's own sign-in vault, reused read-only:
+//             %APPDATA%/com.qodercn.app.stable/Local State
+//               └─ os_crypt.encrypted_key ("DPAPI" prefix + blob)
+//                  → DPAPI Unprotect (powershell System.Security) → AES key
+//             %APPDATA%/com.qodercn.app.stable/auth.v1.dat
+//               └─ "v10" + nonce[12] + AES-256-GCM(ct + tag[16])
+//                  → { token:"dt-…", refreshToken:"drt-…", expiresAt, user }
+//             dt- → POST {openapi}/api/v1/me/jobToken {clientId} → jt-.
+//             When dt- is expired the fix is opening the Qoder desktop app
+//             once (it refreshes the vault); the drt- refresh endpoint is not
+//             public and was not reverse-engineered.
+//
+// Both tracks converge on a job token ("jt-") + userID; COSY-signed gateway
+// calls (models/chat) carry them. Cached for 10 minutes.
+
+import { createDecipheriv } from 'node:crypto'
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+
+/** Qoder CN desktop data directory. */
+export function qoderDataDir() {
+  const fromEnv = process.env['QODER_DATA_DIR']
+  if (fromEnv !== undefined && fromEnv.trim() !== '') return fromEnv
+  return join(process.env['APPDATA'] ?? join(homedir(), 'AppData', 'Roaming'), 'com.qodercn.app.stable')
+}
+
+export const OPENAPI_BASE = 'https://openapi.qoder.com.cn'
+const JOB_TOKEN_CLIENT_ID = '732aef47-9cf2-46a2-95fe-4cebb5d0d1fa'
+const CACHE_TTL_MS = 10 * 60 * 1000
+
+export const SIGN_IN_HINT =
+  '两条路任选:1) 打开 https://qoder.cn/account/integrations 生成个人访问令牌,运行 `node bin/cli.mjs login <PAT>`;2) 打开一次 Qoder CN 桌面程序让它刷新登录态(auth.v1.dat 的 dt- 已过期时必须这样做)'
+
+export function patPath(stateDir) {
+  return join(stateDir, 'pat.txt')
+}
+
+/** DPAPI-unprotect the Chromium master key via PowerShell. */
+function deriveMasterKey(dataDir) {
+  const state = JSON.parse(readFileSync(join(dataDir, 'Local State'), 'utf8'))
+  const blob = Buffer.from(state.os_crypt.encrypted_key, 'base64')
+  if (blob.subarray(0, 5).toString() !== 'DPAPI') throw new Error('Local State encrypted_key 不是 DPAPI 格式')
+  const b64 = blob.subarray(5).toString('base64')
+  const ps = "Add-Type -AssemblyName System.Security;[Convert]::ToBase64String([Security.Cryptography.ProtectedData]::Unprotect([Convert]::FromBase64String('" + b64 + "'),$null,'CurrentUser'))"
+  const out = execFileSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', ps], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true }).trim()
+  const key = Buffer.from(out, 'base64')
+  if (key.length !== 32) throw new Error('DPAPI 解出的主密钥长度异常: ' + key.length)
+  return key
+}
+
+/** AES-256-GCM decrypt of auth.v1.dat (v10 + nonce[12] + ct + tag[16]). */
+export function decryptAuthVault(masterKey, authPath) {
+  const buf = readFileSync(authPath)
+  if (!(buf[0] === 0x76 && buf[1] === 0x31 && buf[2] === 0x30)) {
+    throw new Error(`auth.v1.dat 魔数异常:${buf.subarray(0, 3).toString('hex')}(期望 v10)`)
+  }
+  const decipher = createDecipheriv('aes-256-gcm', masterKey, buf.subarray(3, 15))
+  decipher.setAuthTag(buf.subarray(buf.length - 16))
+  const plaintext = Buffer.concat([decipher.update(buf.subarray(15, buf.length - 16)), decipher.final()])
+  return JSON.parse(plaintext.toString('utf8'))
+}
+
+async function openApiJson(url, { method, token, body } = {}) {
+  const response = await fetch(url, {
+    method: method ?? (body !== undefined ? 'POST' : 'GET'),
+    headers: {
+      accept: 'application/json',
+      'content-type': 'application/json',
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
+    },
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+    signal: AbortSignal.timeout(20000),
+  })
+  const text = await response.text()
+  if (!response.ok) {
+    const err = new Error(`qoder openapi [${response.status}]: ${text.slice(0, 200)}`)
+    err.status = response.status
+    throw err
+  }
+  let payload
+  try { payload = JSON.parse(text) } catch { throw new Error('qoder openapi: 非 JSON 响应') }
+  if (payload && typeof payload === 'object' && 'code' in payload && payload.code !== 0 && payload.code !== '0') {
+    const err = new Error(`qoder openapi code ${payload.code}: ${String(payload.message ?? payload.msg ?? '').slice(0, 160)}`)
+    err.status = 401
+    throw err
+  }
+  return payload && typeof payload === 'object' && 'data' in payload ? payload.data : payload
+}
+
+/** PAT → job token via the documented exchange. */
+export async function exchangePat(pat) {
+  return await openApiJson(`${OPENAPI_BASE}/api/v1/jobToken/exchange`, { body: { personal_token: pat } })
+}
+
+/** dt- → job token via the desktop client id. */
+export async function exchangeJobToken(dtToken) {
+  return await openApiJson(`${OPENAPI_BASE}/api/v1/me/jobToken`, {
+    token: dtToken,
+    body: { clientId: JOB_TOKEN_CLIENT_ID },
+  })
+}
+
+/** jt- → {id, email, name}. */
+async function fetchUserInfo(jobToken) {
+  const info = await openApiJson(`${OPENAPI_BASE}/api/v1/userinfo`, { token: jobToken })
+  if (!info?.id) throw new Error('qoder userinfo 未返回用户 id')
+  return { userID: info.id, email: info.email ?? '', name: info.name ?? info.username ?? 'Qoder User' }
+}
+
+export function readMachineId(dataDir = qoderDataDir()) {
+  try { return readFileSync(join(dataDir, 'auth.machine-id'), 'utf8').trim() } catch { return '' }
+}
+
+/** The vault stores expiresAt as either epoch-ms or an ISO string. */
+function dtExpiresAtMs(auth) {
+  const v = auth?.expiresAt
+  if (typeof v === 'number') return v
+  if (typeof v === 'string') { const p = Date.parse(v); return Number.isNaN(p) ? 0 : p }
+  return 0
+}
+
+export class QoderCredentialStore {
+  constructor({ stateDir, dataDir } = {}) {
+    this.stateDir = stateDir
+    this.dataDir = dataDir ?? qoderDataDir()
+    this.cache = null
+  }
+
+  /** Which tracks are configured, without contacting the network. */
+  status() {
+    const pat = existsSync(patPath(this.stateDir))
+    const vault = existsSync(join(this.dataDir, 'auth.v1.dat'))
+    let dtFresh = false
+    if (vault) {
+      try {
+        const masterKey = deriveMasterKey(this.dataDir)
+        const auth = decryptAuthVault(masterKey, join(this.dataDir, 'auth.v1.dat'))
+        dtFresh = dtExpiresAtMs(auth) > Date.now()
+      } catch {}
+    }
+    return { patConfigured: pat, desktopVault: vault, desktopTokenFresh: dtFresh }
+  }
+
+  async resolve() {
+    if (this.cache && this.cache.expiresAt > Date.now()) return this.cache.credential
+    let jobToken = null
+    let source = ''
+    const patFile = patPath(this.stateDir)
+    if (existsSync(patFile)) {
+      const pat = readFileSync(patFile, 'utf8').trim()
+      if (pat) {
+        const data = await exchangePat(pat)
+        if (data?.token) { jobToken = data.token; source = 'pat' }
+      }
+    }
+    if (!jobToken && existsSync(join(this.dataDir, 'auth.v1.dat'))) {
+      const masterKey = deriveMasterKey(this.dataDir)
+      const auth = decryptAuthVault(masterKey, join(this.dataDir, 'auth.v1.dat'))
+      if (!(dtExpiresAtMs(auth) > Date.now())) throw new Error(`Qoder 桌面 dt- 令牌已过期(${new Date(dtExpiresAtMs(auth)).toISOString()})。${SIGN_IN_HINT}`)
+      const data = await exchangeJobToken(auth.token)
+      if (data?.token) { jobToken = data.token; source = 'desktop' }
+    }
+    if (!jobToken) throw new Error(`没有任何可用的 Qoder 凭据。${SIGN_IN_HINT}`)
+    const info = await fetchUserInfo(jobToken)
+    const credential = {
+      userID: info.userID,
+      authToken: jobToken,
+      name: info.name,
+      email: info.email,
+      machineID: readMachineId(this.dataDir) || '00000000-0000-0000-0000-000000000000',
+      source,
+    }
+    this.cache = { credential, expiresAt: Date.now() + CACHE_TTL_MS }
+    return credential
+  }
+}

package/src/loopback.js

@@ -0,0 +1,40 @@
+/**
+ * Loopback checks for the local OpenAI-compatible endpoint.
+ *
+ * Binding to 127.0.0.1 is not by itself a trust boundary: any local process,
+ * and a DNS-rebinding page in a browser, can reach a loopback port. Every
+ * request must therefore also name a loopback Host, and browser-sent Origins
+ * must be loopback too, so a rebinding page is rejected on both counts.
+ *
+ * @module zcode-trae-connect/loopback
+ */
+
+/** Hostname of a Host header value, with the port and IPv6 brackets removed. */
+export function hostnameOfHost(host) {
+  if (typeof host !== 'string' || host === '') return ''
+  const trimmed = host.trim()
+  // IPv6 literal: [::1]:1234 or [::1]
+  const v6 = /^\[([^\]]+)\](?::\d+)?$/u.exec(trimmed)
+  if (v6 !== null) return (v6[1] ?? '').toLowerCase()
+  const colon = trimmed.lastIndexOf(':')
+  return (colon === -1 ? trimmed : trimmed.slice(0, colon)).toLowerCase()
+}
+
+/** Whether a hostname names the loopback interface. */
+export function hostIsLoopback(host) {
+  const name = hostnameOfHost(host)
+  return name === '127.0.0.1' || name === 'localhost' || name === '::1' || name === '[::1]'
+}
+
+/** Whether an Origin header (absent counts as fine) is a loopback origin. */
+export function originIsLoopback(origin) {
+  if (origin === undefined || origin === null || origin === '') return true
+  if (typeof origin !== 'string') return false
+  let parsed
+  try {
+    parsed = new URL(origin)
+  } catch {
+    return false
+  }
+  return hostIsLoopback(parsed.host)
+}