zcode-qoder-connect 0.0.0-stage → 1.0.0

package/.zcode-plugin/plugin.json

@@ -0,0 +1,40 @@
+{
+  "name": "zcode-qoder-connect",
+  "version": "1.0.0",
+  "description": "Bring Qoder CN models — domestic (DeepSeek-V4-Pro, Qwen3.8-Max, GLM-5.3, Kimi-K3.1-Pro …) — into ZCode as an OpenAI-compatible provider, with zero configuration.",
+  "description_i18n": {
+    "en": "Bring Qoder CN models into ZCode as OpenAI-compatible providers, with zero configuration.",
+    "zh-CN": "把 Qoder 国内版的模型（DeepSeek-V4-Pro、Qwen3.8-Max、GLM-5.3、Kimi-K3.1-Pro 等）零配置接入 ZCode 的模型供应商。"
+  },
+  "author": {
+    "name": "xiao-hans (a port of masknull/dsh-qoder-connect, MIT)"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/xiao-hans/zcode-ai-connect/tree/main/zcode-qoder-connect#readme",
+  "keywords": [
+    "qoder",
+    "openai-compatible",
+    "provider",
+    "glm",
+    "deepseek",
+    "qwen"
+  ],
+  "skills": "skills",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "process",
+            "command": "node",
+            "args": [
+              "${ZCODE_PLUGIN_ROOT}/hooks/service-ensure.mjs"
+            ],
+            "timeoutMs": 60000,
+            "statusMessage": "Starting the Qoder endpoint"
+          }
+        ]
+      }
+    ]
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hawchou1995
+
+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,72 @@
-# Temporary Holding Version
+# zcode-qoder-connect
 
-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.
+把 **Qoder(国内版)桌面 App** 里的模型零配置接入 ZCode / pi 等 OpenAI 兼容客户端。
+
+```
+客户端 ──(OpenAI chat-completions)──▶ 127.0.0.1:39270 ──▶ gateway.qoder.com.cn
+                                        本地端点             (COSY 签名 + WAF 编码)
+```
+
+## 特性
+
+- **双轨凭据,零 PAT 依赖**:优先复用 Qoder CN 桌面 App 的登录保险库(Windows DPAPI + AES-GCM 的 `auth.v1.dat`,只读),`dt-` 换 `jt-` 作业令牌;也可用个人访问令牌(`qoder.cn → 账号设置 → 个人访问令牌`,`cli.mjs login <PAT>`)。桌面令牌约 16 天过期,打开一次 Qoder 桌面即自动刷新。
+- **完整协议**:COSY 请求签名(AES-CBC + RSA + MD5)、WAF 请求体编码、双层 SSE 响应解析,推理内容(`reasoning_content`)与 `tool_calls` 均以 OpenAI 形状透传给调用方。
+- **可读模型 id**:`deepseek-v4-pro`、`qwen3.8-max`、`glm-5.3`、`kimi-k3.1-pro` 等(`MODEL_ALIASES` 映射内部 key,内部 key 直连仍然有效)。
+- **排队自愈**:免费档高峰的 10605 排队信号(HTTP 403 或 SSE 首帧 403 信封)自动换请求 id 重试。
+- **每日签到**:`cli.mjs checkin` 领取当日积分(campaigns 端点,有活动时生效)。
+- **ZCode 插件化**:SessionStart hook 自动拉起端点,skills 提供排障指南。
+
+## 已知边界(如实说明)
+
+Qoder 网关会**包夹**调用方的 system 消息:前缀注入"You are Qoder…"身份与默认英文偏好,后缀注入"被问底层模型时拒答"。调用方的 system 原文完整保留在中间,指令遵从、工具调用、多轮上下文全部正常;仅模型的自我称谓与底层模型自述被锁定。这是端点固有行为,上游无裸 completions 通道(实测 7 个候选路径均 404)。
+
+## 流生命周期(为什么回合不会「突然不动」)
+
+长回合会把每一处代理缺陷暴露成同一种症状:模型忽然没声了、界面一直转、又没有任何报错。端点按下面五条收尾:
+
+| 情况 | 端点行为 |
+|---|---|
+| 已开流后上游 180 秒零字节 | 写 `error` 帧(`type: "upstream_stalled"`)+ `finish_reason: "network_error"` + `[DONE]`,并中止上游请求。下游重试,不会挂在我们自己的心跳后面。 |
+| 上游没给 finish 帧就断流 | 以 `finish_reason: "length"` 收尾——被截断就说截断,绝不改写成 `stop`(那正是「被切断的回答」被当成「模型自己讲完了」的原因)。 |
+| 有 `tool_calls` 却标了 `stop` | 纠正为 `finish_reason: "tool_calls"`;下游的 agent 循环依赖这个值决定是否继续。 |
+| 整回合没有任何产出(只有思考) | 发 `error` 帧(`type: "empty_answer"`),让下游重试,而不是接受一条空的 assistant 消息。 |
+| 客户端中途断开 | 中止上游请求,取消的回合立即停止生成,也不占用账号并发额度。 |
+
+看门狗间隔可调:`ZC_STREAM_IDLE_TIMEOUT_MS`(默认 `180000`)。10 秒一次的心跳(`: heartbeat`)只保活**下游**读超时,刻意不重置看门狗——它只认真实的上游字节。
+
+回归测试:`tests/test-stream-guard-qoder.mjs`。
+
+## 安装
+
+### ZCode
+
+```jsonc
+// %USERPROFILE%\.zcode\cli\config.json
+{ "plugins": { "dirs": ["D:/path/to/zcode-qoder-connect"] } }
+```
+
+重启 ZCode(托盘退出重开)后,模型选择器出现 `Qoder` 分组。端点由 SessionStart hook 自动启动。
+
+### 其他 OpenAI 客户端(pi 等)
+
+```sh
+node bin/cli.mjs serve --port 39270   # 前台运行;healthz 鉴权用 state 目录 endpoint.json 里的 bearer
+```
+
+以 pi 为例,在 `~/.pi/agent/models.json` 添加 provider:`baseUrl http://127.0.0.1:39270/v1`、`api openai-completions`、`apiKey = endpoint.json 的 token`。
+
+## 命令
+
+| 命令 | 作用 |
+|---|---|
+| `serve [--port N]` | 启动端点(默认 39270) |
+| `status` | 凭据双轨状态、积分、模型名册 |
+| `refresh` | 重拉模型名册 |
+| `checkin` | 领取当日签到积分 |
+| `login <PAT>` | 校验并保存个人访问令牌 |
+| `logout` | 删除已保存 PAT(桌面登录不受影响) |
+| `service-status` | 端点是否在运行 |
+
+## 致谢与许可
+
+协议实现源自 [dsh-qoder-connect](https://github.com/masknull/dsh-qoder-connect)(MIT,作者 corrinehu)。MIT,见 [LICENSE](LICENSE)。

package/bin/cli.mjs

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+// cli.mjs — zcode-qoder-connect command line.
+//
+//   serve            run the loopback OpenAI-compatible endpoint (default)
+//   status           credential tracks, credits, model roster
+//   refresh          re-pull the model roster
+//   checkin          claim today's Qoder check-in credits (+100/day)
+//   login <PAT>      save a personal access token (qoder.cn → 账号设置)
+//   logout           drop the saved PAT (desktop vault untouched)
+//   service-status   is the endpoint up
+//   doctor           credential + upstream diagnostics
+
+import { randomBytes } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs'
+import { join } from 'node:path'
+
+const { defaultStateDir, configureStateDir, configureEndpoint, stateDir, endpointPath } = await import(new URL('../src/config.js', import.meta.url).href)
+const { QoderCredentialStore, patPath, SIGN_IN_HINT } = await import(new URL('../src/credentials.js', import.meta.url).href)
+const { QoderUpstreamClient } = await import(new URL('../src/upstream.js', import.meta.url).href)
+const { QoderCatalog } = await import(new URL('../src/catalog.js', import.meta.url).href)
+const { createQoderServer } = await import(new URL('../src/server.js', import.meta.url).href)
+
+const HELP = `zcode-qoder-connect — Qoder CN 模型接入本地 OpenAI 端点
+
+用法: node bin/cli.mjs <command> [options]
+
+commands:
+  serve [--port N]    启动本地 OpenAI 兼容端点(默认 39270)
+  status              凭据双轨状态、积分、模型名册
+  refresh             重新拉取模型名册
+  checkin             领取今日签到积分(+100/天)
+  login <PAT>         保存个人访问令牌(qoder.cn → 账号设置 → 个人访问令牌)
+  logout              删除已保存的 PAT(不影响 Qoder 桌面)
+  service-status      端点是否在运行
+  doctor              诊断
+
+凭据双轨:
+  1. PAT(pat.txt)— 生成: https://qoder.cn/account/integrations
+  2. Qoder CN 桌面登录(auth.v1.dat,只读;dt- 过期时需打开一次 Qoder)`
+
+const args = process.argv.slice(2)
+const command = args.find(a => !a.startsWith('--')) ?? 'serve'
+const portArg = args.includes('--port') ? Number(args[args.indexOf('--port') + 1]) : 39270
+
+configureStateDir(defaultStateDir())
+mkdirSync(stateDir(), { recursive: true })
+
+// --- endpoint token (stable across restarts) --------------------------------
+function ensureToken() {
+  const p = endpointPath()
+  if (existsSync(p)) {
+    try {
+      const j = JSON.parse(readFileSync(p, 'utf8'))
+      if (j.token && j.port) {
+        configureEndpoint({ port: j.port, token: j.token })
+        return j.token
+      }
+    } catch {}
+  }
+  const token = randomBytes(24).toString('base64url')
+  writeFileSync(p, JSON.stringify({ token, port: portArg, createdAt: new Date().toISOString() }, null, 2), 'utf8')
+  configureEndpoint({ port: portArg, token })
+  return token
+}
+
+function buildStore() {
+  return new QoderCredentialStore({ stateDir: stateDir() })
+}
+function buildClient() {
+  return new QoderUpstreamClient({})
+}
+
+async function main() {
+  if (command === 'help' || args.includes('--help')) { console.log(HELP); return }
+
+  if (command === 'login') {
+    const pat = args.find((a, i) => i > 0 && !a.startsWith('--') && args[i - 1] !== '--port' && a !== 'login')
+    if (!pat) { console.error('用法: node bin/cli.mjs login <PAT>'); process.exitCode = 2; return }
+    // live-validate before saving
+    const { exchangePat } = await import(new URL('../src/credentials.js', import.meta.url).href)
+    try {
+      const data = await exchangePat(pat)
+      if (!data?.token) throw new Error('兑换未返回 job token')
+      writeFileSync(patPath(stateDir()), pat, 'utf8')
+      console.log('PAT 有效并已保存(有效期至 ' + (data.expires_at ?? data.expires_in + 's') + ')')
+    } catch (e) {
+      console.error('PAT 校验失败,未保存:', String(e.message ?? e).slice(0, 200)); process.exitCode = 2
+    }
+    return
+  }
+
+  if (command === 'logout') {
+    if (existsSync(patPath(stateDir()))) { unlinkSync(patPath(stateDir())); console.log('PAT 已删除(桌面登录不受影响)') }
+    else console.log('没有已保存的 PAT')
+    return
+  }
+
+  if (command === 'service-status') {
+    const token = ensureToken()
+    try {
+      const r = await fetch(`http://127.0.0.1:${portArg}/healthz`, { headers: { Authorization: `Bearer ${token}` } })
+      console.log(r.ok ? `endpoint http://127.0.0.1:${portArg}/v1 — up` : `endpoint responded HTTP ${r.status}`)
+    } catch {
+      console.log(`endpoint http://127.0.0.1:${portArg}/v1 — NOT reachable`)
+      console.log('  启动: node bin/cli.mjs serve')
+    }
+    return
+  }
+
+  if (command === 'checkin') {
+    const store = buildStore()
+    const client = buildClient()
+    try {
+      const credential = await store.resolve()
+      console.log(`凭据来源: ${credential.source}`)
+      const result = await client.checkin(credential)
+      if (result.status === 'claimed') console.log(`签到成功: +${result.amount} credits`)
+      else if (result.status === 'already-claimed') console.log(`今日已签到(+${result.amount})`)
+      else console.log(`签到未完成: ${result.status} ${result.message ?? ''}`)
+    } catch (e) {
+      console.log('签到失败 —', String(e.message ?? e).slice(0, 220))
+    }
+    return
+  }
+
+  if (command === 'status' || command === 'doctor' || command === 'refresh') {
+    const store = buildStore()
+    const st = store.status()
+    console.log(`PAT:       ${st.patConfigured ? '已配置' : '未配置'}`)
+    console.log(`桌面 vault: ${st.desktopVault ? '存在' : '不存在'}${st.desktopVault ? (st.desktopTokenFresh ? '(dt- 有效)' : '(dt- 已过期 → 打开一次 Qoder CN 桌面即可刷新)') : ''}`)
+    if (command !== 'refresh') {
+      try {
+        const client = buildClient()
+        const credential = await store.resolve()
+        console.log(`凭据:      ${credential.source} (user ${credential.userID})`)
+        try {
+          const credits = await client.fetchCredits(credential)
+          console.log('积分:', JSON.stringify(credits).slice(0, 200))
+        } catch (e) { console.log('积分: 查询失败 —', String(e.message ?? e).slice(0, 120)) }
+        const models = await client.fetchModels(credential)
+        console.log(`Models (${models.length}):`)
+        for (const m of models) {
+          console.log(`  ${m.id.padEnd(30)} ${m.name.padEnd(24)} ${m.contextWindow} ctx${m.supportsImages ? '  img' : ''}${m.reasoning?.supportedEfforts?.length ? '  efforts ' + m.reasoning.supportedEfforts.join('/') : ''}${m.priceFactor !== undefined ? '  x' + m.priceFactor : ''}`)
+        }
+      } catch (e) {
+        console.log('凭据不可用 —', String(e.message ?? e).slice(0, 240))
+      }
+      return
+    }
+    // refresh falls through to serve-side catalog refresh below when live
+    try {
+      const client = buildClient()
+      const credential = await store.resolve()
+      const models = await client.fetchModels(credential)
+      console.log(`refreshed ${models.length} models`)
+    } catch (e) {
+      console.log('refresh 失败 —', String(e.message ?? e).slice(0, 200)); process.exitCode = 1
+    }
+    return
+  }
+
+  if (command === 'serve') {
+    const token = ensureToken()
+    const store = buildStore()
+    const client = buildClient()
+    const catalog = new QoderCatalog()
+    const server = createQoderServer({
+      token,
+      port: portArg,
+      client,
+      variants: [{ id: 'qoder', path: '', prefix: '', store, catalog }],
+    })
+    await server.start()
+    console.log(`[zcode-qoder-connect] listening on http://127.0.0.1:${server.port()}`)
+    console.log(`[zcode-qoder-connect] OpenAI base: http://127.0.0.1:${server.port()}/v1`)
+    console.log(`[zcode-qoder-connect] bearer: ${token}`)
+    // initial catalog load (best-effort)
+    try {
+      const credential = await store.resolve()
+      const models = await client.fetchModels(credential)
+      catalog.set(models, { source: 'qoder-directory', fetchedAtMs: Date.now() })
+      catalog.setVisible(true)
+      console.log(`[zcode-qoder-connect] catalog: ${models.length} models`)
+    } catch (e) {
+      console.log(`[zcode-qoder-connect] catalog 未加载 — ${String(e.message ?? e).slice(0, 160)}`)
+    }
+    const shutdown = signal => {
+      console.log(`\n[zcode-qoder-connect] ${signal} — shutting down`)
+      server.close().then(() => process.exit(0))
+    }
+    process.on('SIGINT', () => shutdown('SIGINT'))
+    process.on('SIGTERM', () => shutdown('SIGTERM'))
+    return
+  }
+
+  console.error(`未知命令: ${command}\n`)
+  console.log(HELP)
+  process.exitCode = 2
+}
+
+main().catch(error => {
+  console.error('fatal:', error)
+  process.exit(1)
+})

package/docs/validate-provider-config.mjs

@@ -0,0 +1,203 @@
+/**
+ * Strict validator for ZCode's `provider_config.json`.
+ *
+ * ZCode parses this document with zod schemas compiled into its Electron
+ * bundle, and those schemas are `.strict()`: a single unrecognised key fails
+ * the WHOLE document, and the app's failure mode is to discard the entire
+ * personal provider set and start from an empty one — silently breaking every
+ * other provider the user had configured, with no error surfaced anywhere.
+ *
+ * That failure mode is why `setup` writes into a temp file and this validator
+ * runs before the write lands. It mirrors the shapes read out of
+ * `ZCode\resources\app.asar` -> `out/host/index.js`:
+ *
+ *   manualProviderModelRules[].config  (the `extractManualModelConfig` shape)
+ *     enabled?
+ *     properties   pick: contextWindow, supportsJsonSchemaOutput,
+ *                        supportsNativeWebSearch, supportsMidConversationSystem
+ *                  + inputFormat pick: supportsImage, supportsVideo, supportsPdf
+ *     optionSpecs  pick: reasoningLevel
+ *                  + maxOutputTokens pick: max   (map is NOT accepted here)
+ *
+ *   providerModelRules[].config  (the full base shape, sparse)
+ *     properties: requiresMfjsToolSchema, contextWindow,
+ *                 inputFormat{5 flags}, outputFormat,
+ *                 supportsToolCall, supportsJsonSchemaOutput,
+ *                 supportsNativeWebSearch, supportsMidConversationSystem
+ *     optionSpecs: reasoningLevel{values,map}, maxOutputTokens{max,map}
+ *
+ * Usage:  node docs/validate-provider-config.mjs [path]
+ * Exit 0 = valid, 1 = invalid (with the offending path printed).
+ */
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { homedir } from 'node:os'
+
+const path = process.argv[2] ?? join(homedir(), '.zcode', 'v2', 'provider_config.json')
+
+/** Keys accepted inside `providerModelRules[].config.properties`. */
+const PROPERTY_KEYS = new Set([
+  'requiresMfjsToolSchema', 'contextWindow',
+  'inputFormat', 'outputFormat',
+  'supportsToolCall', 'supportsJsonSchemaOutput',
+  'supportsNativeWebSearch', 'supportsMidConversationSystem',
+])
+const INPUT_FORMAT_KEYS = new Set(['supportsText', 'supportsImage', 'supportsVideo', 'supportsAudio', 'supportsPdf'])
+const OUTPUT_FORMAT_KEYS = new Set(['supportsText'])
+const OPTION_SPEC_KEYS = new Set(['reasoningLevel', 'maxOutputTokens'])
+const MAX_OUTPUT_TOKEN_KEYS = new Set(['max', 'map'])
+const REASONING_LEVEL_KEYS = new Set(['values', 'map'])
+
+/** The manual variant accepts only a subset of each shape. */
+const CONFIG_KEYS = new Set(['enabled', 'properties', 'optionSpecs'])
+const MANUAL_PROPERTY_KEYS = new Set([
+  'contextWindow', 'supportsJsonSchemaOutput',
+  'supportsNativeWebSearch', 'supportsMidConversationSystem', 'inputFormat',
+])
+const MANUAL_INPUT_FORMAT_KEYS = new Set(['supportsImage', 'supportsVideo', 'supportsPdf'])
+const MANUAL_OPTION_SPEC_KEYS = new Set(['reasoningLevel', 'maxOutputTokens'])
+const MANUAL_MAX_OUTPUT_TOKEN_KEYS = new Set(['max'])
+
+const RULE_KEYS = new Set(['modelId', 'providerId', 'config'])
+const PROVIDER_RULE_KEYS = new Set(['providerId', 'templateId', 'providerName', 'enabled', 'config'])
+const PROVIDER_CONFIG_KEYS = new Set([
+  'group', 'logo', 'access', 'api', 'builtinModelIds', 'personalModelIds', 'modelOrder', 'visibility',
+])
+const API_TYPES = new Set(['anthropic-messages', 'openai-chat-completions', 'openai-responses'])
+const MODEL_RULE_SETS = new Set([
+  'providerModelRules', 'manualProviderModelRules', 'modelRules', 'modelApiRules',
+  'providerSiteRules', 'templateModelRules', 'builtinProviderModelRules',
+])
+
+const problems = []
+const isObj = value => typeof value === 'object' && value !== null && !Array.isArray(value)
+
+function unknownKeys(obj, allowed, where) {
+  if (!isObj(obj)) return
+  for (const key of Object.keys(obj)) {
+    if (!allowed.has(key)) problems.push(`${where}: unrecognised key "${key}" (strict schema rejects the whole document)`)
+  }
+}
+
+function checkPositiveInt(value, where) {
+  if (value === undefined) return
+  if (!Number.isInteger(value) || value <= 0) {
+    problems.push(`${where}: must be a positive integer, got ${JSON.stringify(value)}`)
+  }
+}
+
+function walkConfig(config, where, { manual }) {
+  if (!isObj(config)) {
+    problems.push(`${where}: must be an object`)
+    return
+  }
+  unknownKeys(config, CONFIG_KEYS, where)
+  if (config['enabled'] !== undefined && typeof config['enabled'] !== 'boolean') {
+    problems.push(`${where}.enabled: must be boolean`)
+  }
+
+  const properties = config['properties']
+  if (properties !== undefined) {
+    unknownKeys(properties, manual ? MANUAL_PROPERTY_KEYS : PROPERTY_KEYS, `${where}.properties`)
+    checkPositiveInt(properties['contextWindow'], `${where}.properties.contextWindow`)
+    if (properties['inputFormat'] !== undefined) {
+      unknownKeys(properties['inputFormat'], manual ? MANUAL_INPUT_FORMAT_KEYS : INPUT_FORMAT_KEYS, `${where}.properties.inputFormat`)
+    }
+    if (properties['outputFormat'] !== undefined) {
+      unknownKeys(properties['outputFormat'], OUTPUT_FORMAT_KEYS, `${where}.properties.outputFormat`)
+    }
+  }
+
+  const specs = config['optionSpecs']
+  if (specs === undefined) return
+  unknownKeys(specs, manual ? MANUAL_OPTION_SPEC_KEYS : OPTION_SPEC_KEYS, `${where}.optionSpecs`)
+  const maxOutput = specs['maxOutputTokens']
+  if (maxOutput !== undefined) {
+    unknownKeys(maxOutput, manual ? MANUAL_MAX_OUTPUT_TOKEN_KEYS : MAX_OUTPUT_TOKEN_KEYS, `${where}.optionSpecs.maxOutputTokens`)
+    checkPositiveInt(maxOutput['max'], `${where}.optionSpecs.maxOutputTokens.max`)
+  }
+  const reasoning = specs['reasoningLevel']
+  if (reasoning !== undefined) {
+    unknownKeys(reasoning, REASONING_LEVEL_KEYS, `${where}.optionSpecs.reasoningLevel`)
+  }
+}
+
+let document
+try {
+  document = JSON.parse(readFileSync(path, 'utf8'))
+} catch (error) {
+  console.error(`INVALID — ${path}`)
+  console.error(`  - not readable as JSON: ${String(error)}`)
+  process.exit(1)
+}
+
+if (document['schemaVersion'] !== 1) {
+  problems.push(`schemaVersion: must be 1, got ${JSON.stringify(document['schemaVersion'])}`)
+}
+const config = document['config']
+if (!isObj(config)) {
+  console.error(`INVALID — ${path}`)
+  console.error('  - missing config object')
+  process.exit(1)
+}
+unknownKeys(config, new Set(['providerOrder', 'providerConfigRules', 'modelConfigRules', 'defaultModelSelection']), 'config')
+
+const modelConfigRules = config['modelConfigRules']
+if (modelConfigRules !== undefined) {
+  unknownKeys(modelConfigRules, MODEL_RULE_SETS, 'config.modelConfigRules')
+  for (const setName of ['providerModelRules', 'manualProviderModelRules']) {
+    const rules = modelConfigRules[setName]
+    if (rules === undefined) continue
+    if (!Array.isArray(rules)) {
+      problems.push(`config.modelConfigRules.${setName}: must be an array`)
+      continue
+    }
+    rules.forEach((rule, index) => {
+      const where = `config.modelConfigRules.${setName}[${index}]`
+      unknownKeys(rule, RULE_KEYS, where)
+      if (typeof rule?.['providerId'] !== 'string') problems.push(`${where}.providerId: required string`)
+      if (typeof rule?.['modelId'] !== 'string') problems.push(`${where}.modelId: required string`)
+      if (rule?.['config'] !== undefined) {
+        walkConfig(rule['config'], `${where}.config`, { manual: setName === 'manualProviderModelRules' })
+      }
+    })
+  }
+}
+
+const providerRules = config['providerConfigRules']?.['providerRules']
+if (providerRules !== undefined) {
+  if (!Array.isArray(providerRules)) {
+    problems.push('config.providerConfigRules.providerRules: must be an array')
+  } else {
+    providerRules.forEach((rule, index) => {
+      const where = `config.providerConfigRules.providerRules[${index}]`
+      unknownKeys(rule, PROVIDER_RULE_KEYS, where)
+      const ruleConfig = rule?.['config']
+      if (ruleConfig === undefined) return
+      unknownKeys(ruleConfig, PROVIDER_CONFIG_KEYS, `${where}.config`)
+      const ids = ruleConfig['personalModelIds']
+      if (ids !== undefined && ids !== null && !Array.isArray(ids)) {
+        problems.push(`${where}.config.personalModelIds: must be an array or null`)
+      }
+      const modelOrder = ruleConfig['modelOrder']
+      if (modelOrder !== undefined && modelOrder !== null && !Array.isArray(modelOrder)) {
+        problems.push(`${where}.config.modelOrder: must be an array or null`)
+      }
+      const api = ruleConfig['api']
+      if (isObj(api) && typeof api['type'] === 'string' && !API_TYPES.has(api['type'])) {
+        problems.push(`${where}.config.api.type: unsupported "${api['type']}"`)
+      }
+    })
+  }
+}
+
+if (problems.length === 0) {
+  const ruleCount = (modelConfigRules?.['providerModelRules']?.length ?? 0)
+    + (modelConfigRules?.['manualProviderModelRules']?.length ?? 0)
+  console.log(`VALID — ${path}`)
+  console.log(`  providers: ${Array.isArray(providerRules) ? providerRules.length : 0}, model rules: ${ruleCount}`)
+  process.exit(0)
+}
+console.error(`INVALID — ${path}`)
+for (const problem of problems) console.error(`  - ${problem}`)
+process.exit(1)

package/hooks/service-ensure.mjs

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+/**
+ * SessionStart hook: make sure the local Qoder endpoint is running.
+ *
+ * Same contract as zcode-trae-connect's hook: the provider entry in ZCode's
+ * provider_config.json points at a fixed loopback port (39270), so something
+ * has to be listening there before the first message. Self-verifying — the
+ * spawn call alone never counts as success — and never fails the session.
+ *
+ * @module zcode-qoder-connect/hooks/service-ensure
+ */
+
+import { spawn } from 'node:child_process'
+import { readFile, appendFile, mkdir } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const pluginRoot = dirname(dirname(fileURLToPath(import.meta.url)))
+const cliPath = join(pluginRoot, 'bin', 'cli.mjs')
+const stateDir = process.env['ZCODE_QODER_CONNECT_HOME'] ?? join(process.env['USERPROFILE'] ?? '.', '.zcode-qoder-connect')
+const endpointPath = join(stateDir, 'endpoint.json')
+const logPath = join(stateDir, 'service.log')
+const DEFAULT_PORT = 39270
+
+async function log(line) {
+  try {
+    await mkdir(stateDir, { recursive: true })
+    await appendFile(logPath, `${new Date().toISOString()} ${line}\n`)
+  } catch {}
+}
+
+async function readEndpoint() {
+  try {
+    const document = JSON.parse(await readFile(endpointPath, 'utf8'))
+    const token = typeof document['token'] === 'string' ? document['token'] : ''
+    const port = typeof document['port'] === 'number' && document['port'] > 0 ? document['port'] : DEFAULT_PORT
+    return { token, port }
+  } catch {
+    return { token: '', port: DEFAULT_PORT }
+  }
+}
+
+async function healthy(port, token, timeoutMs = 2500) {
+  try {
+    const response = await fetch(`http://127.0.0.1:${port}/healthz`, {
+      headers: token === '' ? {} : { Authorization: `Bearer ${token}` },
+      signal: AbortSignal.timeout(timeoutMs),
+    })
+    if (!response.ok) return false
+    const body = await response.json()
+    return body?.['ok'] === true
+  } catch {
+    return false
+  }
+}
+
+async function waitForHealth(port, token, attempts = 20) {
+  for (let i = 0; i < attempts; i += 1) {
+    if (await healthy(port, token)) return true
+    await new Promise(resolve => setTimeout(resolve, 500))
+  }
+  return false
+}
+
+function spawnDetached(port) {
+  const child = spawn(process.execPath, [cliPath, 'serve', '--port', String(port)], {
+    detached: true,
+    stdio: 'ignore',
+    windowsHide: true,
+    cwd: pluginRoot,
+  })
+  child.unref()
+  return child.pid
+}
+
+async function main() {
+  if (!existsSync(cliPath)) {
+    await log(`cli not found at ${cliPath}; skipping`)
+    return
+  }
+  const { token, port } = await readEndpoint()
+
+  if (await healthy(port, token)) {
+    await log(`endpoint already healthy on :${port}`)
+    return
+  }
+
+  let pid
+  try {
+    pid = spawnDetached(port)
+    await log(`spawned detached pid ${pid} on :${port}`)
+  } catch (error) {
+    await log(`spawn refused: ${String(error)}`)
+  }
+
+  if (await waitForHealth(port, token)) {
+    await log(`endpoint healthy on :${port}${pid === undefined ? '' : ` (pid ${pid})`}`)
+    return
+  }
+
+  await log(`endpoint NOT healthy on :${port} after spawn attempt`)
+  console.log(
+    `[zcode-qoder-connect] The local endpoint is not running on port ${port}.`
+    + ' Its models will fail until it is started. Start it in a terminal with:\n'
+    + `  node "${cliPath}" serve --port ${port}\n`
+    + '凭据提示: Qoder 桌面 dt- 过期时,打开一次 Qoder CN 桌面即可刷新。',
+  )
+}
+
+main().catch(async error => {
+  await log(`hook error: ${String(error)}`)
+}).finally(() => {
+  process.exit(0)
+})