@waterplus-ai/waterbuddy 0.1.17 → 0.1.34

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.17",
+  "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: