@omdp/dsh-key-fallback 1.0.0

package/README.md

@@ -0,0 +1,41 @@
+# @omdp/dsh-key-fallback
+
+A minimal API-key fallback plugin for DeepSeek Harness (DSH). When a provider request fails with a retryable error, it silently retries the same call with the next key in the pool instead of committing a partial message.
+
+## Install
+
+```sh
+dsh plugin --profile web add @omdp/dsh-key-fallback
+```
+
+Restart DSH, then add a config block to `~/.dsh/settings.yaml`:
+
+```yaml
+keyFallback:
+  providers:
+    ninerouter:
+      env: NINEROUTER_API_KEY   # optional; defaults to ${PROVIDER}_API_KEY
+      cooldownMs: 30000          # optional; cooldown after a failure
+      keys:
+        - <your original key>
+        - <alternate key 1>
+        - <alternate key 2>
+```
+
+## How it works
+
+- `agent/request`: picks the next live key (round-robin) and writes it into `process.env[<env>]` before the request goes out.
+- `agent/request-error`: on a retryable error (`RATE_LIMIT`, `AUTH`, `QUOTA_EXCEEDED`, `TIMEOUT`, `TRANSPORT`, any 4xx/5xx, or a message matching rate/limit/quota/timeout/auth/key…), marks the current key as cooling and returns `{ kind: 'retry' }` so the loop retries and picks the next key.
+
+## Boundaries
+
+- The plugin **overrides** `process.env[<env>]` for every provider you list under `keyFallback.providers`. Put your original key in `keys` so it stays in rotation.
+- Providers you don't list are left untouched.
+- With a single key, a retryable error surfaces directly (no pointless retry, no crash).
+- With no configured keys for a provider, the plugin does nothing.
+
+Settings → 插件 shows a read-only card with the key count, cursor, and cooling/healthy keys.
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+- insert:
+    - id: key-fallback
+      name: dsh-key-fallback
+      inject: [llm, settings, webServer]
+      config: {}

package/lib/client.js

@@ -0,0 +1,65 @@
+'use strict'
+// @omdp/dsh-key-fallback — Client half
+// Settings → 插件 里的只读状态卡：显示每个 provider 的 key 数 / 游标 / 冷却。
+function apply(ctx) {
+  const slots = ctx.get('slots')
+  if (slots === undefined) return
+
+  async function fetchJson(url, opts) {
+    const r = await fetch(url, opts)
+    return r.json()
+  }
+
+  function KeyFallbackCard() {
+    const [state, setState] = React.useState({ loading: true, data: null })
+    const refresh = React.useCallback(function () {
+      fetchJson('/dsh-key-fallback/pools')
+        .then(function (data) { setState({ loading: false, data: (data && data.pools) || {} }) })
+        .catch(function () { setState({ loading: false, data: null }) })
+    }, [])
+    React.useEffect(function () {
+      refresh()
+      const t = setInterval(refresh, 2000)
+      return function () { clearInterval(t) }
+    }, [refresh])
+
+    if (state.loading) {
+      return React.createElement('div', { style: { fontSize: '12px', opacity: 0.6 } }, '加载中…')
+    }
+    const data = state.data || {}
+    const providers = Object.keys(data)
+    if (providers.length === 0) {
+      return React.createElement('p', { style: { fontSize: '12px', opacity: 0.6, margin: 0 } },
+        '未在 settings.yaml 配置 keyFallback.providers')
+    }
+    return React.createElement('div', { style: { fontSize: '12px', display: 'flex', flexDirection: 'column', gap: '8px' } },
+      providers.map(function (p) {
+        const pd = data[p]
+        return React.createElement('div', { key: p, style: { padding: '6px 0', borderTop: '1px solid var(--dsw-alias-border-l2, #eee)' } },
+          React.createElement('div', { style: { fontWeight: 600 } }, p + '  (' + pd.env + ')'),
+          React.createElement('div', { style: { opacity: 0.8 } }, 'key 数: ' + pd.keyCount + '，当前游标: ' + pd.currentIndex),
+          pd.cooling.length > 0
+            ? React.createElement('div', { style: { color: '#c62828' } }, '冷却中: ' + pd.cooling.join(', '))
+            : null,
+          pd.healthy.length > 0
+            ? React.createElement('div', { style: { color: '#2e7d32' } }, '健康: ' + pd.healthy.join(', '))
+            : null,
+        )
+      }),
+    )
+  }
+
+  ctx.slots.inject('settings.plugin.item', function* () {
+    yield ctx.slots.register({
+      name: 'settings.plugin.item',
+      key: 'key-fallback',
+      id: 'key-fallback',
+      order: 50,
+      label: () => 'API Key 回退',
+      inject: () => ({}),
+    }, KeyFallbackCard)
+  })
+}
+
+exports.apply = apply
+exports.inject = ['slots']

package/lib/index.js

@@ -0,0 +1,178 @@
+'use strict'
+// @omdp/dsh-key-fallback — Host half
+// 极简 API Key 回退：请求报错 → 静默换下一个 key 重试同一请求。
+const { readFileSync, existsSync } = require('node:fs')
+const { homedir } = require('node:os')
+const { join } = require('node:path')
+const { load: loadYaml } = (() => {
+  try { return require('js-yaml') }
+  catch { return { load: (s) => { try { return JSON.parse(s) } catch { return {} } } } }
+})()
+
+const name = 'key-fallback'
+const inject = ['llm', 'settings', 'webServer']
+const API_BASE = '/dsh-key-fallback'
+const SETTINGS_FILE = join(homedir(), '.dsh', 'settings.yaml')
+
+function mask(key) {
+  if (!key) return ''
+  if (key.length <= 8) return key.slice(0, 2) + '****'
+  return key.slice(0, 6) + '****' + key.slice(-4)
+}
+function sendJson(res, code, data) {
+  const payload = JSON.stringify(data)
+  res.writeHead(code, {
+    'Content-Type': 'application/json; charset=utf-8',
+    'Content-Length': Buffer.byteLength(payload),
+    'Cache-Control': 'no-store',
+  })
+  res.end(payload)
+}
+
+// 从 settings.yaml 读配置块（keyFallback 或 key-fallback 均可）
+function readConfig() {
+  try {
+    if (!existsSync(SETTINGS_FILE)) return {}
+    const raw = readFileSync(SETTINGS_FILE, 'utf8')
+    const doc = (loadYaml && typeof loadYaml === 'function') ? loadYaml(raw) : {}
+    const blk = (doc && (doc['keyFallback'] || doc['key-fallback'])) || {}
+    return blk
+  } catch (e) { return {} }
+}
+
+function apply(ctx) {
+  // 占位命名空间：让只读状态卡出现在 Settings → 插件（keyed slot 要求 key ∈ served）
+  ctx.inject(['settings'], (sctx) => {
+    try {
+      if (typeof zs !== 'undefined') sctx.settings.register('key-fallback', zs.object({}), { base: {} })
+    } catch (e) { /* 命名空间注册失败不影响核心轮换逻辑 */ }
+  })
+
+  const pools = new Map()
+  const attempts = new Map() // `${turn}:${step}` -> 已尝试次数（防止死循环）
+  const lifetime = new AbortController()
+
+  function buildPools() {
+    const cfg = readConfig()
+    const providers = (cfg && cfg.providers) || {}
+    for (const [provider, pcfg] of Object.entries(providers)) {
+      const env = (pcfg && pcfg.env) || `${provider.toUpperCase()}_API_KEY`
+      const keys = Array.isArray(pcfg && pcfg.keys) ? pcfg.keys.filter(Boolean) : []
+      const cooldown = (pcfg && pcfg.cooldownMs) || 30000
+      if (!pools.has(provider)) {
+        pools.set(provider, {
+          env, keys, cooldown, idx: 0,
+          states: new Map(keys.map((k) => [k, { failCount: 0, cooldownUntil: 0 }])),
+        })
+      } else {
+        const p = pools.get(provider)
+        const added = keys.filter((k) => !p.keys.includes(k))
+        for (const k of added) p.states.set(k, { failCount: 0, cooldownUntil: 0 })
+        p.keys = keys
+        p.env = env
+        p.cooldown = cooldown
+      }
+    }
+  }
+  buildPools()
+
+  function pickKey(provider) {
+    const pool = pools.get(provider)
+    if (!pool || pool.keys.length === 0) return undefined
+    const now = Date.now()
+    const live = pool.keys.filter((k) => ((pool.states.get(k) && pool.states.get(k).cooldownUntil) || 0) <= now)
+    if (live.length === 0) return pool.keys[pool.idx % pool.keys.length]
+    for (let i = 0; i < live.length; i++) {
+      const key = live[(pool.idx + i) % live.length]
+      const realIdx = pool.keys.indexOf(key)
+      if (realIdx >= 0) { pool.idx = (realIdx + 1) % pool.keys.length; return key }
+    }
+    return pool.keys[0]
+  }
+
+  function markFailed(provider, key) {
+    const pool = pools.get(provider)
+    if (!pool || !key) return
+    const st = pool.states.get(key)
+    if (!st) return
+    st.failCount += 1
+    st.cooldownUntil = Date.now() + pool.cooldown * Math.min(st.failCount, 5)
+  }
+
+  // ── agent/request：先拿 provider，再选 key 注入 env ──
+  ctx.on('agent/request', async (payload, next) => {
+    const config = await next()
+    const provider = config && config.provider
+    if (!provider) return config
+    buildPools()
+    const pool = pools.get(provider)
+    if (!pool || pool.keys.length === 0) return config
+    const key = pickKey(provider)
+    if (!key) return config
+    process.env[pool.env] = key
+    return config
+  })
+
+  // 是否还有「别的、未冷却」的 key 可用（单 key / 全冷却 / 未配置时返回 false）
+  function hasOtherLiveKey(provider, excludeKey) {
+    const pool = pools.get(provider)
+    if (!pool) return false
+    const now = Date.now()
+    return pool.keys.some((k) => k !== excludeKey && ((pool.states.get(k) && pool.states.get(k).cooldownUntil) || 0) <= now)
+  }
+
+  // ── agent/request-error：命中可重试错误 → 标当前 key 失效 + 重试 ──
+  ctx.on('agent/request-error', async (payload, next) => {
+    const code = String((payload && ((payload.failure && payload.failure.code) || payload.code)) || '')
+    const rawMsg = String((payload && ((payload.failure && payload.failure.message) || payload.message)) || '')
+    const provider = (payload && payload.provider) || ''
+    const RETRYABLE = ['RATE_LIMIT', 'AUTH', 'QUOTA_EXCEEDED', 'TIMEOUT', 'TRANSPORT']
+    const isRetryable = RETRYABLE.includes(code) ||
+      /^[45]\d\d$/.test(code) ||
+      /rate|limit|quota|exhaust|throttl|429|timeout|timed?out|auth|credential|denied|forbidden|unavailable|busy|key/i.test(rawMsg)
+    if (provider && isRetryable) {
+      const pool = pools.get(provider)
+      if (!pool || pool.keys.length === 0) return next() // 未配置：不接管，原样委托
+      const cur = process.env[pool.env]
+      if (cur && pool.keys.includes(cur)) markFailed(provider, cur)
+      // 只有还有别的未冷却 key 才重试；单 key 或全冷却时直接放弃（不无意义重试，也不崩溃）
+      if (hasOtherLiveKey(provider, cur)) {
+        // 安全上限：同一 step 内每个 key 至多试一次，全试完仍失败则放弃（终态）
+        const ak = `${payload.turn}:${payload.step}`
+        const n = (attempts.get(ak) || 0) + 1
+        attempts.set(ak, n)
+        if (n <= pool.keys.length) return { kind: 'retry' }
+        attempts.delete(ak)
+      }
+    }
+    return next()
+  })
+
+  // ── 只读状态接口（给卡片用）──
+  const webServer = ctx.get('webServer')
+  if (webServer) {
+    ctx.effect(() => webServer.register({
+      kind: 'exact',
+      path: `${API_BASE}/pools`,
+      handler: (req, res) => {
+        if (req.method !== 'GET') { sendJson(res, 405, { error: 'method not allowed' }); return }
+        const now = Date.now()
+        const out = {}
+        for (const [provider, p] of pools) {
+          out[provider] = {
+            env: p.env,
+            keyCount: p.keys.length,
+            currentIndex: p.idx,
+            cooling: p.keys.filter((k) => ((p.states.get(k) && p.states.get(k).cooldownUntil) || 0) > now).map(mask),
+            healthy: p.keys.filter((k) => ((p.states.get(k) && p.states.get(k).cooldownUntil) || 0) <= now).map(mask),
+          }
+        }
+        sendJson(res, 200, { pools: out })
+      },
+    }), 'key-fallback: pools route')
+  }
+
+  ctx.effect(() => () => { lifetime.abort() })
+}
+
+module.exports = { name, inject, apply }

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@omdp/dsh-key-fallback",
+  "description": "Minimal API key fallback for DeepSeek Harness: on a retryable request error, silently retry the same call with the next key in the pool.",
+  "version": "1.0.0",
+  "type": "commonjs",
+  "main": "lib/index.js",
+  "exports": {
+    ".": { "default": "./lib/index.js" },
+    "./client": { "default": "./lib/client.js" },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/XJungit/omdp.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dsh": {
+    "bundle": { "patch": "./cordis.patch.yml" },
+    "client": {
+      "platform": "web",
+      "inject": ["@deepseek-ai/dsh-client-ui-settings"]
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  }
+}