@waterplus-ai/waterbuddy 0.1.21 → 0.1.34

package/lib/client/index.js

@@ -415,9 +415,10 @@ window.__ModuleLoader__.load({
     }
 
     function UserAction({ wide }) {
-      const { useEffect, useState } = require('react')
+      const { useEffect, useRef, useState } = require('react')
       const [open, setOpen] = useState(false)
       const [user, setUser] = useState(null)
+      const [llm, setLlm] = useState(null)
       const [session, setSession] = useState({ qrCode: '', status: '', error: '', loading: false })
 
       useEffect(() => {
@@ -428,6 +429,21 @@ window.__ModuleLoader__.load({
         return () => { cancelled = true }
       }, [])
 
+      // 额度轮询：依赖 user，登录/登出后会立刻重新取值（Host 此时已换过 key）。
+      useEffect(() => {
+        let cancelled = false
+        const load = async () => {
+          try {
+            const response = await fetch('/api/waterbuddy/llm/status')
+            const body = await response.json()
+            if (!cancelled) setLlm(body.llm || null)
+          } catch (_) {}
+        }
+        load()
+        const timer = setInterval(load, 15000)
+        return () => { cancelled = true; clearInterval(timer) }
+      }, [user])
+
       const startLogin = async () => {
         setSession({ qrCode: '', status: '二维码加载中', error: '', loading: true })
         try {
@@ -469,9 +485,39 @@ window.__ModuleLoader__.load({
       }, [open, session.sessionId, user])
 
       const openPanel = () => { setOpen(true); if (!user && !session.sessionId) startLogin() }
+      // 额度耗尽是**主动**提示：模型调用由 Harness 自己发起，插件看不到那次 403
+      // （harness 还会把它归类成「API 密钥无效」，文案完全误导），只能靠额度轮询
+      // 自己发现并把登录面板推给用户。
+      //
+      // 必须走 openPanel 而不是裸 setOpen：裸开会得到一个「二维码暂不可用」的空面板，
+      // 因为扫码会话根本没发起（实测踩过）。
+      const exhaustedNotified = useRef(false)
+      useEffect(() => {
+        if (!llm || llm.managesQuota !== true || user) {
+          exhaustedNotified.current = false
+          return
+        }
+        if (llm.exhausted === true && !exhaustedNotified.current) {
+          exhaustedNotified.current = true
+          openPanel()
+          return
+        }
+        if (llm.exhausted !== true) exhaustedNotified.current = false
+      }, [llm, user])
       const logout = async () => { await fetch('/api/waterbuddy/logout', { method: 'POST' }); setUser(null); setOpen(false); setSession({ qrCode: '', status: '', error: '', loading: false }) }
       const name = userName(user)
       const buttonStyle = { borderRadius: 10, padding: '9px 18px', fontSize: 13, fontWeight: 600, cursor: 'pointer' }
+      // 余额单位是 sub2api 的美元，不是人民币（见 SUB2API-TOKEN-QUOTA-PLAN §2）。
+      const balanceText = `$${Number(llm?.balance || 0).toFixed(2)}`
+      // 用户把默认模型换成别人的提供方时，消耗的不是我们的额度，一律不展示额度。
+      const managesQuota = llm?.managesQuota === true
+      const exhausted = managesQuota && llm?.exhausted === true
+      // 未登录时展示试用额度，登录后展示账号额度；耗尽一律优先提示
+      const subtitle = !managesQuota
+        ? (user ? '水务之窗' : '扫码或账号登录')
+        : exhausted
+          ? '额度已用完'
+          : (user ? `额度 ${balanceText}` : `试用额度 ${balanceText}`)
 
       function userPanel() {
         const account = user?.loginId || (user?.id ? `${String(user.id).slice(0, 8)}…` : '水务之窗账号')
@@ -495,6 +541,10 @@ window.__ModuleLoader__.load({
                 jsx('small', { style: { color: '#8a94a6', fontSize: 11 }, children: '身份' }),
                 jsx('div', { style: { marginTop: 4, color: '#334155', fontSize: 13, fontWeight: 600 }, children: isAdmin ? '管理员' : '内部成员' }),
               ] }),
+              managesQuota ? jsxs('div', { style: { padding: '12px 14px', borderRadius: 12, background: exhausted ? '#fff7ed' : '#f5f8fc' }, children: [
+                jsx('small', { style: { color: '#8a94a6', fontSize: 11 }, children: '剩余额度' }),
+                jsx('div', { style: { marginTop: 4, color: exhausted ? '#b45309' : '#334155', fontSize: 13, fontWeight: 600 }, children: balanceText }),
+              ] }) : null,
             ] }),
             jsx('button', { type: 'button', onClick: logout, style: { ...buttonStyle, width: '100%', marginTop: 18, border: '1px solid #d9e1ec', background: '#fff', color: '#475569' }, children: '退出登录' }),
           ] }),
@@ -508,7 +558,7 @@ window.__ModuleLoader__.load({
             onClick: openPanel,
             title: user ? name : '登录 WaterBuddy',
             style: { display: 'flex', alignItems: 'center', gap: 8, width: wide ? 'auto' : 40, maxWidth: wide ? 150 : 40, minHeight: 38, padding: wide ? '5px 9px 5px 6px' : 3, border: user ? '1px solid #e1eafa' : '1px solid transparent', borderRadius: 12, background: user ? '#f5f8ff' : 'transparent', color: 'var(--dsw-text-secondary, #586174)', cursor: 'pointer', textAlign: 'left', transition: 'background .15s ease, border-color .15s ease' },
-            children: [user ? jsx(UserAvatar, { user, size: 28 }) : jsx('img', { src: SSO.image, alt: SSO.title, style: { width: 28, height: 28, borderRadius: 8, objectFit: 'contain', padding: 2, boxSizing: 'border-box', flex: '0 0 auto', background: '#fff', border: '1px solid #dce9fb' } }), wide ? jsxs('span', { style: { minWidth: 0, display: 'grid', gap: 1 }, children: [jsx('strong', { style: { overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap', fontSize: 12.5, lineHeight: '16px', color: 'var(--dsw-text-primary, #1f2937)' }, children: user ? name : SSO.title }), jsx('small', { style: { color: '#8a94a6', fontSize: 10.5, lineHeight: '14px' }, children: user ? '水务之窗' : '扫码或账号登录' })] }) : null],
+            children: [user ? jsx(UserAvatar, { user, size: 28 }) : jsx('img', { src: SSO.image, alt: SSO.title, style: { width: 28, height: 28, borderRadius: 8, objectFit: 'contain', padding: 2, boxSizing: 'border-box', flex: '0 0 auto', background: '#fff', border: '1px solid #dce9fb' } }), wide ? jsxs('span', { style: { minWidth: 0, display: 'grid', gap: 1 }, children: [jsx('strong', { style: { overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap', fontSize: 12.5, lineHeight: '16px', color: 'var(--dsw-text-primary, #1f2937)' }, children: user ? name : SSO.title }), jsx('small', { style: { color: exhausted ? '#b45309' : '#8a94a6', fontSize: 10.5, lineHeight: '14px' }, children: subtitle })] }) : null],
           }),
           open ? jsx('div', { style: { position: 'fixed', inset: 0, zIndex: 1000, background: 'rgba(15, 23, 42, .42)', backdropFilter: 'blur(5px)', display: 'flex', alignItems: 'center', justifyContent: 'center', padding: 16 }, onClick: event => { if (event.target === event.currentTarget) setOpen(false) }, children: jsx('div', { style: { width: 420, maxWidth: 'calc(100vw - 32px)', borderRadius: 22, background: '#fff', overflow: 'hidden', boxShadow: '0 24px 80px rgba(15,23,42,.28)' }, children: user ? userPanel() : jsxs('div', { children: [
             jsxs('div', { style: { position: 'relative', padding: '22px 26px 0', textAlign: 'center' }, children: [
@@ -516,6 +566,7 @@ window.__ModuleLoader__.load({
               jsx('img', { src: SSO.image, alt: SSO.title, style: { display: 'block', width: 52, height: 52, objectFit: 'contain', margin: '0 auto' } }),
               jsx('h3', { style: { margin: '10px 0 4px', color: '#162033', fontSize: 21 }, children: 'WaterBuddy' }),
               jsx('p', { style: { margin: 0, color: '#7b8799', fontSize: 12.5 }, children: '登录后同步水务之窗账号与知识库权限' }),
+              exhausted ? jsx('div', { style: { margin: '14px 26px 0', padding: '10px 12px', borderRadius: 10, background: '#fff7ed', border: '1px solid #fed7aa', color: '#b45309', fontSize: 12.5, lineHeight: 1.5 }, children: '试用额度已用完，登录后即可继续使用（额度升为账号档）' }) : null,
             ] }),
             jsx(LoginPanel, { session, onLogin: nextUser => setUser(nextUser || null), onRestart: startLogin, onClose: () => setOpen(false) }),
           ] }) }) }) : null,

package/lib/host/index.js

@@ -3,6 +3,7 @@ import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import { WATERPLUS_PERSONA } from '../shared/persona.js'
+import { bindLlmCredential, describeLlmCredential, ensureLlmCredential, isGatewayActive, readActiveProvider, refreshLlmQuota, restoreDeviceLlmCredential, switchDefaultProviderWithRetry } from './llm-gateway.js'
 
 const WATERPLUS_ICON = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII=', 'base64')
 const CLIENT_ID = '2CC7F925-07AE-4AB9-9F17-75B7378D5890'
@@ -14,6 +15,9 @@ const sessions = new Map()
 let persistedAuth
 let currentUser
 let upstreamTransport
+let llmStatus
+let llmLoginHook
+let llmLogoutHook
 
 /**
  * Test seam only. Production always uses `https.request`; regression tests install a
@@ -23,6 +27,24 @@ function setUpstreamTransport(transport) {
   upstreamTransport = transport
 }
 
+/**
+ * 给「登录后换 key」这类收尾动作加一个上限。
+ *
+ * 它不该让登录失败，但也不该无限拖住登录响应——客户端拿到登录成功的那一刻
+ * 就该显示账号档余额，所以这里等一小段而不是纯后台跑。
+ */
+function withTimeout(promise, ms, label) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(`${label}-timeout`)), ms)
+    promise.then(
+      value => { clearTimeout(timer); resolve(value) },
+      error => { clearTimeout(timer); reject(error) },
+    )
+  })
+}
+
+const LLM_SWAP_TIMEOUT_MS = 5000
+
 function dshHome() {
   return process.env.DSH_HOME || path.join(os.homedir(), '.dsh')
 }
@@ -159,6 +181,16 @@ async function finalizeLogin(token) {
   currentUser = user
   persistedAuth = { token, user }
   savePersistedAuth(persistedAuth)
+  // 登录即换账号档 key（额度升档）。**等它完成再返回**：客户端拿到登录成功就会
+  // 立刻查余额，若此时 key 还没换，读到的还是设备档（实测会显示 $0.00 且误判耗尽）。
+  // best-effort 不变——失败或超时只告警，绝不让登录失败。
+  if (llmLoginHook) {
+    try {
+      await withTimeout(Promise.resolve().then(() => llmLoginHook(token)), LLM_SWAP_TIMEOUT_MS, 'llm-bind')
+    } catch (error) {
+      console.warn('[WaterBuddy] llm bind after login failed:', error.message)
+    }
+  }
   return { token, user }
 }
 
@@ -306,10 +338,31 @@ async function proxyAvatar(req, res) {
   res.end()
 }
 
-export const inject = ['webServer', 'systemPrompt']
+/**
+ * 领取设备凭证并写入 harness 凭据存储，再把默认提供方指向 waterplus-ai。
+ *
+ * 全流程尽力而为：网关不可达时插件其余功能照常，只是模型不可用。
+ */
+export async function bootstrapLlmCredential(ctx, config) {
+  try {
+    const { deviceId, credential } = await ensureLlmCredential(ctx, { config })
+    llmStatus = describeLlmCredential(credential, deviceId)
+    try {
+      await switchDefaultProviderWithRetry(ctx)
+    } catch (error) {
+      console.warn('[WaterBuddy] default provider not switched:', error.message)
+    }
+  } catch (error) {
+    console.warn('[WaterBuddy] LLM credential bootstrap failed:', error.message)
+    llmStatus = { ...(llmStatus || {}), error: error.message }
+  }
+  return llmStatus || null
+}
+
+export const inject = ['webServer', 'systemPrompt', 'credentials', 'settings']
 export { normalizeAvatar, setUpstreamTransport }
 
-export function apply(ctx) {
+export function apply(ctx, config) {
   readPersistedAuth()
   ctx.effect(() => {
     const routes = [
@@ -324,12 +377,38 @@ export function apply(ctx) {
       { kind: 'exact', path: '/api/waterbuddy/auth/password/change', handler: (req, res) => handleAuthAction(req, res, changePassword) },
       { kind: 'exact', path: '/api/waterbuddy/user', handler: (_req, res) => json(res, 200, { user: currentUser || null }) },
       { kind: 'exact', path: '/api/waterbuddy/avatar', handler: async (req, res) => { try { await proxyAvatar(req, res) } catch (error) { json(res, 502, { error: error.message }) } } },
-      { kind: 'exact', path: '/api/waterbuddy/logout', handler: (_req, res) => { currentUser = undefined; for (const session of sessions.values()) delete session.token; clearPersistedAuth(); json(res, 200, { ok: true }) } },
+      { kind: 'exact', path: '/api/waterbuddy/llm/status', handler: async (_req, res) => {
+        try {
+          const token = persistedAuth?.token
+          const { quota } = await refreshLlmQuota({ config, token })
+          if (quota) {
+            // 余额是权威读数，每次刷新都覆盖；subjectType 跟随当前是否登录。
+            llmStatus = { ...(llmStatus || {}), ...quota, subjectType: token ? 'user' : 'device', isAnonymous: !token }
+          }
+        } catch (error) {
+          // 额度查询失败沿用上次读数，不打扰用户
+        }
+        // 用别人的模型时额度不归我们管，客户端据此隐藏额度展示。
+        const activeProvider = readActiveProvider(ctx)
+        json(res, 200, {
+          llm: llmStatus
+            ? { ...llmStatus, activeProvider, managesQuota: isGatewayActive(ctx) }
+            : { activeProvider, managesQuota: isGatewayActive(ctx) },
+        })
+      } },
+      { kind: 'exact', path: '/api/waterbuddy/llm/refresh', handler: async (req, res) => { if (req.method !== 'POST') return json(res, 405, { error: 'method-not-allowed' }); try { json(res, 200, { llm: await bootstrapLlmCredential(ctx, config) }) } catch (error) { json(res, 502, { error: error.message }) } } },
+      { kind: 'exact', path: '/api/waterbuddy/logout', handler: async (_req, res) => { currentUser = undefined; for (const session of sessions.values()) delete session.token; clearPersistedAuth(); if (llmLogoutHook) { try { await withTimeout(Promise.resolve().then(() => llmLogoutHook()), LLM_SWAP_TIMEOUT_MS, 'llm-unbind') } catch (error) { console.warn('[WaterBuddy] llm restore after logout failed:', error.message) } } json(res, 200, { ok: true }) } },
       { kind: 'prefix', path: '/api/waterbuddy/mcp', handler: async (req, res) => { try { await proxyMcp(req, res) } catch (error) { json(res, 502, { error: error.message }) } } },
     ]
     const disposers = routes.map(route => ctx.webServer.register(route))
     const disposeTitle = ctx.webServer.tapIndex(html => html.replace(/<title>[^<]*<\/title>/i, '<title>WaterBuddy</title>').replace(/<link[^>]+rel=["']icon["'][^>]*>/i, '<link rel="icon" type="image/png" href="/waterplus-mark.png" />'))
     const disposePersona = ctx.systemPrompt.section({ name: 'waterplus:persona', order: 100, text: WATERPLUS_PERSONA })
+    // 尽力而为：宿主没有 credentials 服务（例如测试替身）时直接跳过，不发网络请求。
+    if (ctx.credentials?.set) {
+      llmLoginHook = token => bindLlmCredential(ctx, token, { config })
+      llmLogoutHook = () => restoreDeviceLlmCredential(ctx, { config })
+      void bootstrapLlmCredential(ctx, config)
+    }
     return () => { for (const dispose of disposers) dispose(); disposeTitle(); disposePersona(); sessions.clear(); currentUser = undefined; persistedAuth = undefined }
   }, 'waterbuddy: identity and auth')
 }

package/lib/host/llm-gateway.js

@@ -0,0 +1,424 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import http from 'node:http'
+import https from 'node:https'
+import { randomUUID } from 'node:crypto'
+
+/**
+ * LLM 网关客户端：把「本机设备」换成一把受额度约束的网关 key。
+ *
+ * 边界：官方 DeepSeek key 只存在于 sub2api 服务端；本模块拿到的是网关 key，
+ * 写进 harness 凭据存储后由 `llm-pi-ai` 的 `apiKeyEnv` 引用按请求解析，
+ * 因此换 key 无需重启（凭据文件是热重载的）。
+ */
+
+/** 与 patches/cordis.patch.yml 中 waterplus-ai 路由的 apiKeyEnv 保持一致。 */
+export const LLM_GATEWAY_CREDENTIAL_REF = 'WATERPLUS_AI_LLM_KEY'
+/** 提供方路由名，同时也是设置里的默认提供方值。 */
+export const LLM_GATEWAY_PROVIDER = 'waterplus-ai'
+/** 网关默认走平台域名；部署不同可用插件 config 或环境变量覆盖。 */
+export const DEFAULT_LLM_GATEWAY_BASE_URL = 'https://ai.shuiwujia.com'
+/** 首次安装时指向的默认模型。 */
+export const DEFAULT_LLM_GATEWAY_MODEL = 'deepseek-flash'
+/** 未登录设备的额度用尽后由客户端引导登录（见 P3）。 */
+export const LOW_BALANCE_HINT = 0
+
+const DEVICE_ID_PATTERN = /^[A-Za-z0-9._:-]{8,128}$/
+
+let llmGatewayTransport
+
+/**
+ * Test seam only, mirroring `setUpstreamTransport` in `lib/host/index.js`.
+ * Production always uses the protocol-matched node request; regression tests
+ * install a scripted transport so the gateway contract is asserted offline.
+ */
+export function setLlmGatewayTransport(transport) {
+  llmGatewayTransport = transport
+}
+
+export function dshHome() {
+  return process.env.DSH_HOME || path.join(os.homedir(), '.dsh')
+}
+
+export function deviceStateFile() {
+  return path.join(dshHome(), 'waterbuddy-device.json')
+}
+
+export function resolveGatewayBaseUrl(config) {
+  const raw = config?.llmGatewayBaseUrl || process.env.WATERBUDDY_LLM_GATEWAY_URL || DEFAULT_LLM_GATEWAY_BASE_URL
+  return String(raw).trim().replace(/\/+$/, '')
+}
+
+function readDeviceState() {
+  try {
+    const value = JSON.parse(fs.readFileSync(deviceStateFile(), 'utf8'))
+    return value && typeof value === 'object' ? value : {}
+  } catch {
+    return {}
+  }
+}
+
+function writeDeviceState(state) {
+  try {
+    const file = deviceStateFile()
+    fs.mkdirSync(path.dirname(file), { recursive: true })
+    fs.writeFileSync(file, JSON.stringify(state), { mode: 0o600 })
+    try { fs.chmodSync(file, 0o600) } catch {}
+  } catch (error) {
+    console.warn('[WaterBuddy] failed to persist device state:', error.message)
+  }
+}
+
+/**
+ * 读取本机 deviceId，没有则生成并持久化。
+ *
+ * 未登录时的额度按 deviceId 一人一份，所以它必须稳定：重装插件不能让用户
+ * 白拿一份新试用额度。
+ */
+export function readOrCreateDeviceId() {
+  const state = readDeviceState()
+  const existing = typeof state.deviceId === 'string' ? state.deviceId.trim() : ''
+  if (DEVICE_ID_PATTERN.test(existing)) {
+    return { deviceId: existing, state, created: false }
+  }
+  const deviceId = randomUUID()
+  const next = { ...state, deviceId, createdAt: state.createdAt || new Date().toISOString() }
+  writeDeviceState(next)
+  return { deviceId, state: next, created: true }
+}
+
+export function markDefaultProviderApplied() {
+  writeDeviceState({ ...readDeviceState(), defaultProviderApplied: true, defaultProviderAppliedAt: new Date().toISOString() })
+}
+
+/**
+ * 拆掉 swj-kb-api 的全局响应信封。
+ *
+ * 后端注册了 `TransformInterceptor`，所有非 SSE 响应都被包成
+ * `{ success, message, code, result, timestamp }`；这里同时兼容未包裹的扁平
+ * 结构，便于直连调试或将来去掉拦截器。
+ */
+export function unwrapGatewayPayload(raw) {
+  if (raw && typeof raw === 'object' && raw.result && typeof raw.result === 'object') {
+    return raw.result
+  }
+  return raw
+}
+
+/** 校验后端响应，缺失 apiKey 视为失败而不是写入空凭据。 */
+export function normalizeCredentialPayload(raw) {
+  const payload = unwrapGatewayPayload(raw)
+  const apiKey = typeof payload?.apiKey === 'string' ? payload.apiKey.trim() : ''
+  if (!apiKey) {
+    throw new Error('llm-credential-missing-api-key')
+  }
+  const baseURL = typeof payload?.baseURL === 'string' ? payload.baseURL.trim() : ''
+  return {
+    apiKey,
+    baseURL,
+    provider: typeof payload?.provider === 'string' && payload.provider.trim() ? payload.provider.trim() : LLM_GATEWAY_PROVIDER,
+    balance: Number.isFinite(Number(payload?.balance)) ? Number(payload.balance) : 0,
+    subjectType: payload?.subjectType === 'user' ? 'user' : 'device',
+    isAnonymous: payload?.isAnonymous !== false,
+  }
+}
+
+/**
+ * 按协议选择请求实现。
+ *
+ * 生产网关走 https，但本机联调/私有部署会用 http（例如 10.x 网段的 sub2api），
+ * 硬编码 `https.request` 会直接抛 ERR_INVALID_PROTOCOL。
+ */
+export function selectTransport(url) {
+  return new URL(url).protocol === 'http:' ? http.request : https.request
+}
+
+function defaultTransport(url, options, callback) {
+  // 必须把 callback 透传下去：漏掉它就永远收不到响应，只能等到超时。
+  return selectTransport(url)(url, { method: options.method, headers: options.headers, insecureHTTPParser: true }, callback)
+}
+
+/**
+ * 调一次 swj-kb-api 的 llm 端点，返回拆掉信封后的业务对象。
+ *
+ * 注意这里**不是**平台的 `{code, message}` 信封：swj-kb-api 是 NestJS，
+ * 响应经 `TransformInterceptor` 包成 `{success, code, result}`（见 unwrapGatewayPayload），
+ * 非 2xx 即失败并把上游 message 带出来。
+ */
+export async function callLlmGateway(options) {
+  const { baseUrl, path: requestPath, method = 'POST', token, body, transport, timeoutMs = 15000 } = options
+  const url = new URL(`${baseUrl}${requestPath}`)
+  const payloadText = body === undefined ? undefined : JSON.stringify(body)
+  const send = transport || llmGatewayTransport || defaultTransport
+
+  return await new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error('llm-gateway-timeout')), timeoutMs)
+    const fail = error => { clearTimeout(timer); reject(error) }
+    const headers = {}
+    if (payloadText !== undefined) {
+      headers['content-type'] = 'application/json'
+      headers['content-length'] = Buffer.byteLength(payloadText)
+    }
+    if (token) headers.Authorization = `Bearer ${token}`
+
+    let request
+    try {
+      request = send(url, { method, headers }, response => {
+        const chunks = []
+        response.on('data', chunk => chunks.push(chunk))
+        response.on('end', () => {
+          clearTimeout(timer)
+          const text = Buffer.concat(chunks).toString('utf8')
+          let payload
+          try { payload = text ? JSON.parse(text) : {} } catch { payload = { message: text } }
+          const status = response.statusCode || 500
+          if (status >= 400) {
+            return reject(new Error(payload?.message || `llm-gateway-failed:${status}`))
+          }
+          resolve(unwrapGatewayPayload(payload))
+        })
+      })
+    } catch (error) {
+      return fail(error)
+    }
+    request.on('error', fail)
+    if (payloadText !== undefined) request.write(payloadText)
+    request.end()
+  })
+}
+
+/** 领取设备档凭证（幂等：同一 deviceId 返回同一把 key）。 */
+export async function requestDeviceCredential(options) {
+  const { baseUrl, deviceId, transport, timeoutMs = 15000 } = options
+  const payload = await callLlmGateway({
+    baseUrl,
+    path: '/swj-kb-api/client/llm/credentials',
+    method: 'POST',
+    body: { deviceId },
+    transport,
+    timeoutMs,
+  })
+  return normalizeCredentialPayload(payload)
+}
+
+/** 用登录态换账号档凭证：额度升档，并把设备试用额度并入账号。 */
+export async function requestUserCredential(options) {
+  const { baseUrl, token, deviceId, mergeDeviceQuota = true, transport, timeoutMs = 15000 } = options
+  if (!token) throw new Error('llm-bind-missing-token')
+  const payload = await callLlmGateway({
+    baseUrl,
+    path: '/swj-kb-api/client/llm/bind',
+    method: 'POST',
+    token,
+    body: { deviceId, mergeDeviceQuota },
+    transport,
+    timeoutMs,
+  })
+  return normalizeCredentialPayload(payload)
+}
+
+/**
+ * 查当前额度。
+ *
+ * 带 token 查账号档，否则按 deviceId 查设备档——与后端 `GET /client/llm/quota`
+ * 的两种鉴权方式一致（JWT 或 `?deviceId=`）。
+ */
+export async function fetchLlmQuota(options) {
+  const { baseUrl, token, deviceId, transport, timeoutMs = 8000 } = options
+  const query = !token && deviceId ? `?deviceId=${encodeURIComponent(deviceId)}` : ''
+  const payload = await callLlmGateway({
+    baseUrl,
+    path: `/swj-kb-api/client/llm/quota${query}`,
+    method: 'GET',
+    token,
+    transport,
+    timeoutMs,
+  })
+  return {
+    balance: Number.isFinite(Number(payload?.balance)) ? Number(payload.balance) : 0,
+    totalRecharged: Number.isFinite(Number(payload?.totalRecharged)) ? Number(payload.totalRecharged) : 0,
+    isAnonymous: payload?.isAnonymous !== false,
+    exhausted: payload?.exhausted === true,
+    lowBalance: payload?.lowBalance === true,
+    lowBalanceThreshold: Number(payload?.lowBalanceThreshold) || 0,
+  }
+}
+
+/**
+ * 领取（或复用）设备凭证并写入 harness 凭据存储。
+ *
+ * 幂等：后端按 deviceId 返回同一把 key；凭据写入是热生效的，不需要重启。
+ */
+export async function ensureLlmCredential(ctx, options = {}) {
+  // 先确认凭据存储可用再发请求：没有 credentials 服务的宿主不该产生任何网络流量。
+  if (!ctx?.credentials?.set) {
+    throw new Error('llm-credential-store-unavailable')
+  }
+
+  const baseUrl = resolveGatewayBaseUrl(options.config)
+  const { deviceId, state } = readOrCreateDeviceId()
+  const credential = await requestDeviceCredential({ baseUrl, deviceId, transport: options.transport })
+  await ctx.credentials.set(LLM_GATEWAY_CREDENTIAL_REF, credential.apiKey)
+
+  return { deviceId, credential, state, baseUrl }
+}
+
+/**
+ * 首次安装把默认提供方指向 waterplus-ai。
+ *
+ * 只做一次并留标记：用户之后在 Models 设置页改回自有提供方时，插件不再抢回。
+ */
+export async function applyDefaultProviderOnce(ctx) {
+  const state = readDeviceState()
+  if (state.defaultProviderApplied === true) {
+    return { applied: false, reason: 'already-applied' }
+  }
+  if (!ctx?.settings?.update) {
+    return { applied: false, reason: 'settings-unavailable' }
+  }
+  await ctx.settings.update('agent-default-model', {
+    provider: LLM_GATEWAY_PROVIDER,
+    model: DEFAULT_LLM_GATEWAY_MODEL,
+  })
+
+  // 回读确认后再置标记。插件 `apply()` 跑在宿主启动早期，此时 settings 命名空间
+  // 可能尚未就绪，`update` 会静默不落盘（实测过）；若无条件置标记，用户就永远
+  // 停在默认提供方上。回读不到就当作未生效，留给下一次启动 / refresh 重试。
+  const persisted = ctx.settings.get?.('agent-default-model')
+  if (persisted && typeof persisted === 'object' && persisted.provider && persisted.provider !== LLM_GATEWAY_PROVIDER) {
+    return { applied: false, reason: 'not-persisted' }
+  }
+
+  markDefaultProviderApplied()
+  return { applied: true }
+}
+
+/**
+ * 启动早期切换默认提供方可能因命名空间未就绪而失败，这里带退避重试。
+ *
+ * 只在「确实没落盘」时重试：用户自己改过提供方（already-applied）或宿主没有
+ * settings 服务（settings-unavailable）都直接结束。
+ */
+export async function switchDefaultProviderWithRetry(ctx, options = {}) {
+  const attempts = options.attempts ?? 4
+  const delayMs = options.delayMs ?? 3000
+  let last = { applied: false, reason: 'not-attempted' }
+
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    last = await applyDefaultProviderOnce(ctx)
+    if (last.applied || last.reason !== 'not-persisted') {
+      return { ...last, attempts: attempt }
+    }
+    if (attempt < attempts) {
+      await new Promise(resolve => setTimeout(resolve, delayMs))
+    }
+  }
+  return { ...last, attempts }
+}
+
+/** 额度查询失败不该让状态接口失败，降级为 null 由调用方沿用上次读数。 */
+async function safeQuota(options) {
+  try {
+    return await fetchLlmQuota(options)
+  } catch {
+    return null
+  }
+}
+
+/** 登录后把 key 换成账号档（热生效），并带回最新额度。 */
+export async function bindLlmCredential(ctx, token, options = {}) {
+  if (!ctx?.credentials?.set) throw new Error('llm-credential-store-unavailable')
+  const baseUrl = resolveGatewayBaseUrl(options.config)
+  const { deviceId } = readOrCreateDeviceId()
+  const credential = await requestUserCredential({
+    baseUrl,
+    token,
+    deviceId,
+    mergeDeviceQuota: options.mergeDeviceQuota !== false,
+    transport: options.transport,
+  })
+  await ctx.credentials.set(LLM_GATEWAY_CREDENTIAL_REF, credential.apiKey)
+  const quota = await safeQuota({ baseUrl, token, deviceId, transport: options.transport })
+  return { deviceId, credential, quota }
+}
+
+/** 登出后回落到设备档 key（设备档是幂等的，直接重领即可）。 */
+export async function restoreDeviceLlmCredential(ctx, options = {}) {
+  if (!ctx?.credentials?.set) throw new Error('llm-credential-store-unavailable')
+  const baseUrl = resolveGatewayBaseUrl(options.config)
+  const { deviceId } = readOrCreateDeviceId()
+  const credential = await requestDeviceCredential({ baseUrl, deviceId, transport: options.transport })
+  await ctx.credentials.set(LLM_GATEWAY_CREDENTIAL_REF, credential.apiKey)
+  const quota = await safeQuota({ baseUrl, deviceId, transport: options.transport })
+  return { deviceId, credential, quota }
+}
+
+/** 只刷额度不换 key，供状态接口按需更新余额。 */
+export async function refreshLlmQuota(options = {}) {
+  const baseUrl = resolveGatewayBaseUrl(options.config)
+  const { deviceId } = readOrCreateDeviceId()
+  const quota = await safeQuota({
+    baseUrl,
+    token: options.token,
+    deviceId,
+    transport: options.transport,
+    timeoutMs: options.timeoutMs ?? 3000,
+  })
+  return { deviceId, quota }
+}
+
+/**
+ * 读当前选中的默认提供方。
+ *
+ * 用户可以在模型页换成自己的提供方（我们**不锁定**），此时插件不应再展示额度：
+ * 消耗的不是我们的额度，显示出来只会误导。
+ */
+export function readActiveProvider(ctx) {
+  try {
+    const section = ctx?.settings?.get?.('agent-default-model')
+    return typeof section?.provider === 'string' ? section.provider.trim() : ''
+  } catch {
+    return ''
+  }
+}
+
+/** 额度是否由我们的网关管辖（即当前默认提供方就是 waterplus-ai）。 */
+export function isGatewayActive(ctx) {
+  return readActiveProvider(ctx) === LLM_GATEWAY_PROVIDER
+}
+
+/** 合并凭据与额度，得到下发给客户端的完整状态。 */
+export function describeLlmState(credential, quota, deviceId, extra = {}) {
+  const balance = quota?.balance ?? credential?.balance ?? 0
+  return {
+    provider: LLM_GATEWAY_PROVIDER,
+    subjectType: credential?.subjectType ?? 'device',
+    isAnonymous: credential?.isAnonymous !== false,
+    balance,
+    totalRecharged: quota?.totalRecharged ?? 0,
+    // 额度耗尽是登录引导的唯一触发条件（见 SUB2API-TOKEN-QUOTA-PLAN §7.2）
+    exhausted: quota?.exhausted ?? balance <= LOW_BALANCE_HINT,
+    lowBalance: quota?.lowBalance === true,
+    baseURL: credential?.baseURL ?? '',
+    deviceId,
+    ...extra,
+  }
+}
+
+/** 供本地路由返回的状态快照。 */
+export function describeLlmCredential(credential, deviceId) {
+  return {
+    provider: LLM_GATEWAY_PROVIDER,
+    subjectType: credential.subjectType,
+    isAnonymous: credential.isAnonymous,
+    balance: credential.balance,
+    exhausted: credential.balance <= LOW_BALANCE_HINT,
+    baseURL: credential.baseURL,
+    deviceId,
+  }
+}
+
+export function readDeviceStateSnapshot() {
+  return readDeviceState()
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waterplus-ai/waterbuddy",
-  "version": "0.1.21",
+  "version": "0.1.34",
   "description": "WaterBuddy branding and Web profile bundle for DeepSeek Harness",
   "license": "UNLICENSED",
   "type": "module",
@@ -13,6 +13,7 @@
   },
   "files": [
     "lib/host/index.js",
+    "lib/host/llm-gateway.js",
     "lib/client/index.js",
     "lib/shared/persona.js",
     "patches/cordis.patch.yml",

package/patches/cordis.patch.yml

@@ -4,9 +4,76 @@
 - id: ui-brand-official
   disabled: true
 
+# WaterPlus LLM gateway route.
+#
+# pi-ai ships no catalog entry for our gateway, so this route declares its
+# protocol, endpoint, credential reference, model list, and wire-compat switch
+# outright — a route the catalog does not describe must name all of them.
+#
+# No secret lives here: `apiKeyEnv` is a reference the harness resolves per
+# request from its credential store, and `lib/host` writes the gateway key into
+# that store on startup. Because the store is hot-reloaded, rotating the key
+# (for example after the user signs in) never needs a restart.
+#
+# `baseURL` must equal the backend's `SUB2API_PUBLIC_BASE_URL` plus `/v1`; the
+# host reports the address the backend actually returned under
+# `GET /api/waterbuddy/llm/status`, so drift is visible rather than silent.
+#
+# 本机联调：把 baseURL 改成 http://<你的局域网IP>:8080/v1，并把 llmGatewayBaseUrl
+# 改成 http://<你的局域网IP>:3099（或设 WATERBUDDY_LLM_GATEWAY_URL），改的是
+# profile 里安装后的那份 patch，不要改这里——这里是发布值。
+- id: llm-pi-ai
+  config:
+    providers:
+      waterplus-ai:
+        displayName: WaterPlus AI
+        api: openai-completions
+        baseURL: https://token.shuiwujia.com/v1
+        apiKeyEnv: WATERPLUS_AI_LLM_KEY
+        compat:
+          thinkingFormat: deepseek
+          # DeepSeek 官方适配器对每个等级发 `thinking:{type:enabled}` + `reasoning_effort:<等级>`，
+          # 因此这里要打开，否则 pi-ai 只发 thinking 开关、等级不生效。
+          supportsReasoningEffort: true
+          # 必须关掉：pi-ai 在 `model.reasoning && supportsDeveloperRole` 时把系统提示词
+          # 的角色发成 `developer`，而 DeepSeek 只认 system/user/assistant/tool，
+          # 会直接 400 invalid_request_error。启用 reasoning 之前不发 developer，
+          # 所以这个坑是「声明 reasoningEfforts」之后才暴露的（实测踩过）。
+          supportsDeveloperRole: false
+        defaultContextWindow: 1000000
+        defaultMaxTokens: 256000
+        models:
+          - id: deepseek-flash
+            name: DeepSeek-V4-Flash
+            contextWindow: 1000000
+            maxTokens: 256000
+            input: [text, image]
+            # 必须声明：模型级省略 reasoningEfforts 会被解析成 reasoning:false，
+            # harness 里任何已保存的等级都会以 UNSUPPORTED_REASONING_EFFORT 直接跑挂。
+            # 取值与官方 DeepSeek 适配器契约一致：只接受 low / high / max。
+            reasoningEfforts:
+              low: low
+              high: high
+              max: max
+          - id: deepseek-v4-pro
+            name: DeepSeek-V4-Pro
+            contextWindow: 1000000
+            maxTokens: 256000
+            input: [text]
+            # 必须声明：模型级省略 reasoningEfforts 会被解析成 reasoning:false，
+            # harness 里任何已保存的等级都会以 UNSUPPORTED_REASONING_EFFORT 直接跑挂。
+            # 取值与官方 DeepSeek 适配器契约一致：只接受 low / high / max。
+            reasoningEfforts:
+              low: low
+              high: high
+              max: max
+
 - insert:
     - id: ui-brand-waterplus
       name: '@waterplus-ai/waterbuddy'
+      # 设备领 key 的平台地址；换部署只改这里，无需改代码。
+      config:
+        llmGatewayBaseUrl: https://ai.shuiwujia.com
     - id: mcp-xiaojia
       name: '@deepseek-ai/dsh-mcp-client'
       config: