dsh-sub2api 中文文档 Connect your sub2api gateway to DeepSeek Harness as model providers. Sub2API is an AI API gateway that turns subscription quota into OpenAI-compatible endpoints. In its model, each API key is bound to a group, and the group decides the platform (OpenAI / Claude / Grok / Gemini) and the models that key can serve. The four provider routes (sub2api-openai, sub2api-claude, sub2api-grok, sub2api-gemini) are served by the harness's own pi-ai adapter (dsh-llm-pi-ai): this plugin translates its llm-sub2api: settings into llm-pi-ai: provider profiles (all sharing one bare-host base URL, no /v1), and protocol serialization, streaming, and usage accounting all live in pi-ai. The same gateway serves OpenAI, Claude, Grok, and Gemini models side by side, and the harness routes each request to the key whose group owns the requested model. ## Features - One base URL, four provider routes: sub2api-openai, sub2api-claude, sub2api-grok, sub2api-gemini — each configured with its own key, registered as a live LLM provider the moment the key is set. - Streaming chat (backed by pi-ai): SSE streaming, tool calls, reasoning deltas, and token usage are mapped to the harness protocol by dsh-llm-pi-ai, which natively handles wire-format details like top-level function_call items in the Responses API. - Model discovery: one-click "fetch models" calls GET {baseURL}/models with the key, so each route's catalog matches exactly what the sub2api group serves. - Reasoning effort (thinking mode): reasoning_effort is passed straight through to the gateway and adjustable right in the chat model selector; the settings page's per-model "reasoning strength" column fills each model's real levels from models.dev reasoning_options (e.g. gpt-5.6-sol → none/low/medium/high/xhigh/max, deepseek-v4-flash → low/high/max), with editable levels and an explicit opt-out. - Usage lookup: "view usage" calls GET {baseURL}/usage and summarizes quota, balance, rate limits, and subscription windows. - Standards-based config: base URL and model catalogs live in the llm-sub2api: settings section ($DSH_HOME/settings.yaml, written by the web Models page); keys go through the harness credential store. - Global vision / image tools: analyze_image and generate_image stay available even when the current chat model cannot see or create images. They call a dedicated vision or image model configured on the settings page, and return a description or a workspace file path rather than injecting image blocks into a text-only session. - Auto Vision wrapper: image capability for text-only models. Every registered text-only provider route gets a same-name twin (<route>-vision, shown as "… + 自动识图") — our own sub2api-* routes and external providers (official deepseek-official, llm-pi-ai, routes added by other plugins). Twin models carry a -vision id/name suffix (e.g. deepseek-v4-flash-vision) so the picker shows at a glance which models accept images; the suffix is stripped again when the call is delegated back to the base route. The twin's catalog declares inputModalities: ['text', 'image'] so the harness attachment admission passes, and the twin's stream rewrites image blocks into vision-model transcriptions (via the configured tools.analyze model, cached per attachment) before delegating the text-only turn to the original route's adapter. DeepSeek stays the brain; the vision model is only the eyes. Twins follow llm/adapters-updated and skip names already taken by other plugins. Disable with autoVision: false. - Provider icons from lobehub/lobe-icons, embedded as SVG in the settings page. ## Install bash dsh plugin --profile web add @godd6366/dsh-sub2api or, from this repository: bash dsh plugin --profile web add . ## Configure Open Settings → Sub2API 模型 (or edit $DSH_HOME/settings.yaml directly): yaml llm-sub2api: baseURL: http://localhost:8080 providers: openai: apiKeyEnv: SUB2API_OPENAI_API_KEY models: - id: gpt-4o claude: apiKeyEnv: SUB2API_CLAUDE_API_KEY grok: apiKeyEnv: SUB2API_GROK_API_KEY gemini: apiKeyEnv: SUB2API_GEMINI_API_KEY tools: analyze: provider: openai model: gpt-4o generate: provider: openai model: gpt-image-1 Store each key through the credentials service (the web Models page writes it, or export SUB2API_OPENAI_API_KEY=… etc.). A route activates only when its platform has a key; clear the key to drop the route again. ### Wire protocol (automatic per group) The gateway serves each platform group upstream through its NATIVE protocol, and pi-ai picks the endpoint automatically from the key's group — no configuration needed. Configure the bare host (no /v1): OpenAI-style endpoints get /v1 appended automatically, and the Anthropic SDK appends /v1/messages itself: | Group | Protocol used | Endpoint | |---|---|---| | openai | openai-responses | POST {baseURL}/v1/responses | | claude | anthropic-messages | POST {baseURL}/v1/messages | | grok / gemini | openai-completions | POST {baseURL}/v1/chat/completions | Speaking the native protocol means the gateway never has to convert chat/completions — that conversion is what drops/misaligns tool-call names and ids for parallel calls (unknown tool "", missing required property …). To force a different endpoint for a group whose gateway does not serve it natively, declare api on the provider in $DSH_HOME/settings.yaml (advanced; no settings-page control): yaml llm-sub2api: baseURL: http://localhost:8080 providers: openai: apiKeyEnv: SUB2API_OPENAI_API_KEY api: openai-completions # optional: openai-completions / openai-responses / anthropic-messages models: - id: gpt-4o api accepts openai-completions (/v1/chat/completions), openai-responses (/v1/responses), or anthropic-messages (/v1/messages); omitted means the automatic group default above. ### Relationship to dsh-llm-pi-ai This plugin no longer implements the LLM protocol layer itself: the four sub2api-* routes are served by dsh-llm-pi-ai (shipped dormant with dsh-base) through llm-pi-ai: settings profiles. On every llm-sub2api: change (and at boot) the plugin translates the bare-host base URL, per-group models, and key references into hand-declared profiles and writes them to llm-pi-ai:, so routes register/drop live. The settings page, model discovery (GET /v1/models), usage lookup (GET /v1/usage), the vision/image tools, and the Auto Vision twins remain this plugin's own. > Dependency (pi-ai multi-turn crash; attribution: dsh-llm-pi-ai violates pi-ai's contract): pi-ai's AssistantMessage.usage is a required field that its prefix-token estimation dereferences, but the harness's own dsh-llm-pi-ai rebuilds assistant history without usage (the harness Message type records none), so multi-turn conversations throw Cannot read properties of undefined (reading 'totalTokens'). The root fix belongs in dsh-llm-pi-ai (attach a zero Usage); this plugin applies a defensive guard at boot (assistant.usage !== undefined before counting prefix tokens) to @earendil-works/pi-ai/dist/utils/estimate.js inside the dsh install — idempotent, re-applied automatically after a dsh upgrade, so a fresh install works out of the box; on a read-only install run node scripts/patch-pi-ai.mjs manually. > > Auto Vision twins and replay: the twin delegates history to the base route with the base provider id, so pi-ai stamps its replay state with that provider while the harness records the message under the twin route — replaying it would fail pi-ai's provider does not match assistant source check (INVALID_REPLAY_STATE). The twin therefore strips replayState from assistant history before delegating (pi-ai then treats it as foreign); twin conversations intentionally skip provider-native replay. ### Image input & reasoning effort (auto-filled) Attaching an image to the session model requires that model to declare the image input modality — otherwise the harness refuses before sending ("model does not support images"). Both fields are auto-filled from models.dev — no manual selection (the model details panel shows the derived values read-only): - Image input: derived from models.dev attachment / modalities.input when present (e.g. gpt-5.6-luna → text+image, deepseek-v4-flash → text); otherwise guessed from the model id (gpt-*, claude-*, gemini-*, grok-*, glm-*, … default to text+image). Pin a model to text-only with input: [text] in $DSH_HOME/settings.yaml. - Reasoning effort: derived from models.dev reasoning_options when present (e.g. deepseek-v4-flash → high/max); otherwise the default low/medium/high, and models with reasoning: false are marked unsupported. When the model accepts images, the request carries the image in the group's native protocol: openai → Responses input_image, claude → Messages image (base64), grok/gemini → chat-completions image_url. Pick the dedicated vision / image models under Settings → Sub2API 模型 → 全局图像工具. Those two tools stay global: a text-only chat model can still call analyze_image (local file or URL) and generate_image (writes into the session workspace). Generation first tries POST {baseURL}/images/generations, then falls back to chat completions when the gateway has no images endpoint. ## Development bash npm install npm run build # tsdown → lib/ + client wrapper npm run typecheck ## License MIT