dsh-lightvela

把 LightVela（OpenAI 兼容网关）接入 DeepSeek Harness 的模型 provider —— Magpie 式接入。

一个自包含的 DSH 插件：注册 provider、自动发现模型、把 SSE 流转成 DSH StreamChunk、多 API key 失败自动切换。

特性

• 多 key 账号池：某个 key 额度满（402 / quota）、限流（429）、失效（401/403）时自动换下一个，全部不可用才报错。
• 模型发现：GET {baseURL}/models 自动拉目录，支持白名单过滤与兜底，失败沿用上一次有效目录。
• 流式转发：POST {baseURL}/chat/completions → StreamChunk，含 reasoning_content、tool_calls、usage。
• 积分感知：maxTokens 同时约束单次请求的 max_tokens 与模型默认输出上限。
• 零内核耦合：不 import 任何 @deepseek-ai/*，ctx.llm.registerAdapter 走结构化契约，内核换版不会解析失败。
• 用量工具：注册 lightvela_usage，按账号汇报已用额度与可用状态。

安装

# 方式一：直接从本仓库
dsh plugin --profile <你的profile> add github:bob868335-rgb/dsh-lightvela

# 方式二：下载 Release 里的 tarball
#   https://github.com/bob868335-rgb/dsh-lightvela/releases
dsh plugin --profile <你的profile> add file:/绝对路径/dsh-lightvela-0.2.0.tgz

# 方式三：本地目录
dsh plugin --profile <你的profile> add link:/绝对路径/dsh-lightvela

装完重载一次（或重启 dsh），模型选择器里会出现 LightVela 分组。

配置

配置写在 cordis.patch.yml 的 config 块里，也可用 dsh 的配置编辑器改。

单账号

config:
  baseURL: https://token.lightvela.com/v1
  apiKeyRef: LIGHTVELA_API_KEY   # 或直接 apiKey: 'sk-...'
  maxTokens: 8192
  models: [auto]

多账号自动切换

config:
  baseURL: https://token.lightvela.com/v1
  accounts:
    - label: 主账号
      apiKey: 'sk-aaaa'
    - label: 备用账号
      apiKey: 'sk-bbbb'
    - label: 环境变量里的号
      apiKeyRef: LIGHTVELA_BACKUP_KEY
  strategy: failover          # failover（默认）| round-robin
  rateLimitCooldownMs: 60000  # 429 冷却（上游给 retry-after 则以它为准）
  quotaCooldownMs: 1800000    # 额度耗尽冷却

配了 accounts 就忽略顶层 apiKey / apiKeyRef。

字段

字段	默认	说明
baseURL	https://token.lightvela.com/v1	OpenAI 兼容 api 地址
apiKey	—	明文 key（不推荐）
apiKeyRef	LIGHTVELA_API_KEY	凭据引用名
accounts	—	账号池，非空时忽略 apiKey / apiKeyRef
strategy	failover	failover 固定优先用第一个可用；round-robin 每次轮转起点
rateLimitCooldownMs	60000	429 冷却
quotaCooldownMs	1800000	额度耗尽冷却
transientCooldownMs	5000	网络 / 5xx 冷却
displayName	LightVela	选择器显示名
maxTokens	8192	单次输出上限 / 积分控制
contextWindow	131072	上下文窗口
streamIdleTimeoutMs	300000	流空闲上限
models	—	只暴露这些 id；留空自动发现
fallbackModels	—	/models 发现失败时的兜底 id
reasoningEfforts	—	推理模型才需要，如 [low, medium, high]
defaultReasoningEffort	—	默认推理档位

key 的三条来源（优先级从高到低）

1. config.apiKey（或 accounts[].apiKey）明文
2. credentials 服务里 apiKeyRef 指向的凭据
3. 启动环境变量 apiKeyRef（如 export LIGHTVELA_API_KEY=sk-...）

切换规则

只在响应码阶段换号（此时还未输出任何 chunk），所以不会出现半截输出重复。

上游响应	处理
402 / quota / insufficient / 余额 / 积分 / 额度	额度耗尽 → 该号冷却 → 换下一个
429	限流 → 按 retry-after 或 rateLimitCooldownMs 冷却 → 换下一个
401 / 403	失效 → 该号熔断 → 换下一个
网络错误 / 5xx	短暂冷却 → 换下一个
400 等请求本身的错	不换号，直接报错

顺序：健康号按配置顺序在前，冷却中的按「最早恢复」排后；全部不可用返回最后一个失败原因（NO_ACCOUNT）。

用量查询

插件注册工具 lightvela_usage，读上游 OpenAI 兼容 billing 路由：

• GET {baseURL}/dashboard/billing/usage → total_usage（已用）
• GET {baseURL}/dashboard/billing/subscription → 支付方式状态

上游只提供「已用」，没有「剩余额度」接口，剩余积分需到 LightVela 控制台「套餐与费用」查看。

模型选择

/v1/models 通常列出 auto、deepseek-v4-pro-202606 等。auto 是路由器，实际落到哪家由网关决定，没有触发模型级 60 RPM 限制；deepseek-v4-pro-202606 有模型级 60 RPM 上限，密集调用会 429。

注意

• provider 名固定是 lightvela，在模型选择器里是独立一组，不会混进 Magpie 组。
• 子代理要使用它，需在 profile 的 subagent-model-selection-settings.allowedModels 里补 - provider: lightvela / model: auto。
• 本仓库不含任何 API key；cordis.patch.yml 里只有占位引用。

License

MIT