dsh-volcengine

简体中文 | English

Volcengine Ark Agent Plan & Coding Plan provider routes + a real-time quota monitor for DeepSeek Harness (DSH), in a single plugin bundle.

• Two LLM provider routes — volcengine-plan/<model> and volcengine-coding/<model> for Volcengine Ark Agent Plan / Coding Plan plans.
• Quota monitor — a draggable floating ball + window showing real-time Coding Plan / Agent Plan quota usage with donut charts, per-window progress bars, and reset countdowns.
• One config surface — all credentials (LLM API keys and quota AK/SK) are configured through DSH's own settings page (设置 → 插件) and stored in the DSH credential store (~/.dsh/.credentials.yaml) via ctx.credentials. There is no separate configuration file to maintain.

Features

• Two LLM provider routes with verified thinking-effort compatibility:
  • volcengine-plan/<model> — Volcengine Ark Agent Plan (https://ark.cn-beijing.volces.com/api/plan/v3, OpenAI Responses)
  • volcengine-coding/<model> — Volcengine Ark Coding Plan (https://ark.cn-beijing.volces.com/api/coding/v3, OpenAI Completions)
• Quota monitor — floating ball (collapsed) → draggable window (expanded) with donut charts, per-window progress bars, and reset countdowns, auto-refreshed every 60s.
• One config surface — settings → plugins shows a single 火山方舟配置 card with:
  • 额度查询凭据 — quota AK/SK + plan type.
  • LLM 路由 API Key — Agent Plan / Coding Plan API keys (written to the DSH credential store, so the LLM routes pick them up with no separate config).
  • Configured fields echo back masked (e.g. AKLT••••1234) and keep what you typed after saving — no more blank fields.
• Floating quota monitor with LLM plan detection — the draggable ball (polished with a live status dot + brand gradient) opens a panel that also shows which LLM plan is active (Agent Plan / Coding Plan / both) based on the configured API keys, and auto-detects the model list per plan on page load, on credential change, and every 60s.
• Injects only the plan you chose — the plugin registers just the provider route(s) whose API key is configured (Agent Plan and/or Coding Plan). DSH never shows a Volcengine Ark Agent Plan + Volcengine Ark Coding Plan pair at once unless you configured both; saving/clearing keys in the config card re-injects immediately via atomic route replacement (no restart).

Install

The bundle isn't published to npm yet — install it from the GitHub source.

From the root of a DSH profile (e.g. ~/.dsh/profiles/web):

dsh plugin --profile web add github:RONG-LU/dsh-volcengine

Or paste this prompt into a DSH chat window and let DSH install it for you:

请帮我安装 DSH 插件：https://github.com/RONG-LU/dsh-volcengine

Then restart DSH (or reload the profile). The model picker will show volcengine-plan/* and volcengine-coding/*, and the quota floating ball appears in the bottom-right corner.

Security note: installing a plugin runs third-party source on your machine with the same permissions as your user, and a GitHub source may also run build scripts. Only install from sources you trust, and prefer pinning a commit:

dsh plugin --profile web add github:RONG-LU/dsh-volcengine#<commit-sha>

Credentials — all through DSH's own config

The plugin resolves every credential through the DSH credential service (ctx.credentials), the same mechanism DSH itself uses for API keys: environment variables first, ~/.dsh/.credentials.yaml as the persisted fallback. The settings → plugins cards write the credential store, so there is nothing to configure separately.

What	Credential refs (tried in order)	Set from
Agent Plan API key	ARK_AGENT_PLAN_API_KEY → VOLCENGINE_ARK_PLAN_API_KEY → ARK_CODE_API_KEY	设置 → 插件 → 火山方舟配置, or env
Coding Plan API key	ARK_CODING_PLAN_API_KEY → VOLCENGINE_CODING_API_KEY → HUOSHAN_API_KEY	设置 → 插件 → 火山方舟 LLM, or env
Quota AK	VOLC_ARK_ACCESS_KEY_ID (legacy: VOLC_ACCESS_KEY_ID / VOLC_ACCESS_KEY / ARK_ACCESS_KEY_ID)	设置 → 插件 → 火山方舟配置, or env
Quota SK	VOLC_ARK_ACCESS_KEY_SECRET (legacy: VOLC_ACCESS_KEY_SECRET / VOLC_SECRET_KEY / ARK_ACCESS_KEY_SECRET)	设置 → 插件 → 火山方舟额度, or env

Credential resolution priority: request-body override (advanced) > credential store / env > legacy aliases.

LLM provider routes

volcengine-plan — Volcengine Ark Agent Plan

• Endpoint: https://ark.cn-beijing.volces.com/api/plan/v3
• Protocol: openai-responses for most models; openai-completions for Kimi K2.6 / K2.7 Code (mixed-api provider)
• reasoning.effort maps to the selected thinking level

Model ID	Context	Max tokens	Input	Thinking tiers
deepseek-v4-pro	1.0M	384000	text	low·medium·high·xhigh·max
deepseek-v4-flash	1.0M	384000	text	low·medium·high·xhigh·max
glm-5.2	1.0M	128000	text	low·medium·high·xhigh·max
glm-5.3	1.0M	128000	text	low·medium·high·xhigh·max
kimi-k3	1.0M	128000	text, image	low·high·max
minimax-m2.7	200k	128000	text	low·medium·high·xhigh·max
minimax-m3	512k	128000	text, image	low·medium·high·xhigh·max
doubao-seed-2.0-mini	256k	128000	text, image	low·medium·high·xhigh·max
doubao-seed-2.0-lite	256k	128000	text, image	low·medium·high·xhigh·max
doubao-seed-2.0-code	256k	128000	text, image	low·medium·high·xhigh·max
doubao-seed-2.0-pro	256k	128000	text, image	low·medium·high·xhigh·max
kimi-k2.6	256k	32000	text, image	off·high
kimi-k2.7-code	256k	32000	text, image	high

volcengine-coding — Volcengine Ark Coding Plan

• Endpoint: https://ark.cn-beijing.volces.com/api/coding/v3
• Protocol: openai-completions with supportsDeveloperRole: false, supportsStore: false, supportsStrictMode: false, maxTokensField: "max_tokens"
• DeepSeek/GLM accept reasoning_effort; Kimi uses the qwen enable_thinking toggle; MiniMax/Doubao-seed-code expose no thinking control (reasoning is auto-captured)

Model ID	Context	Max tokens	Input	Thinking tiers
deepseek-v4-pro	1.0M	384000	text	low·medium·high·xhigh·max
deepseek-v4-flash	1.0M	384000	text	low·medium·high·xhigh·max
glm-5.2	1.0M	128000	text	low·medium·high·xhigh·max
glm-5.3	1.0M	128000	text	low·medium·high·xhigh·max
kimi-k2.6	256k	32000	text, image	off·high
kimi-k2.7-code	256k	32000	text, image	high
minimax-m2.7	200k	128000	text	—
minimax-m3	512k	128000	text, image	—
doubao-seed-code	256k	32000	text, image	—
doubao-seed-2.0-code	256k	65536	text, image	low·medium·high·xhigh·max
doubao-seed-2.0-pro	256k	128000	text, image	low·medium·high·xhigh·max
doubao-seed-2.0-lite	256k	128000	text, image	low·medium·high·xhigh·max

Bundle config (optional)

Override defaults through the bundle config in cordis.patch.yml:

- id: dsh-volcengine
  name: dsh-volcengine
  config:
    agentPlanApiKeyEnv: ARK_AGENT_PLAN_API_KEY
    codingPlanApiKeyEnv: ARK_CODING_PLAN_API_KEY
    defaultReasoning: high     # off | minimal | low | medium | high | xhigh | max
    planType: auto             # auto | coding | agent

Host API

• GET /dsh-volcengine/quota/config — quota credential status (configured/source/writable/masked); masked shows only the first/last chars for echo-back, never the full value
• POST /dsh-volcengine/quota/config — body {ak, sk}, writes the credential store (empty string clears)
• POST /dsh-volcengine/quota/clear — clear quota AK/SK
• POST /dsh-volcengine/quota/snapshot (body {planType} optional) — quota snapshot
• GET /dsh-volcengine/llm/config — LLM API key status (configured/source/writable/masked); masked shows only the first/last chars for echo-back, never the full value
• GET /dsh-volcengine/llm/status — LLM plan status: { effective: agent|coding|both|none, plans: [{name, configured, active, masked, models[]}] }; the floating panel uses it to detect the active plan and the available model types.
• POST /dsh-volcengine/llm/config — body {agentPlanApiKey, codingPlanApiKey}, writes the credential store (empty string clears)
• POST /dsh-volcengine/llm/clear — clear LLM API keys

How it works

The bundle inserts a single plugin row (id: dsh-volcengine). On apply it:

1. Builds two pi-ai Provider objects directly with createProvider, passing the full compat block on each Model — bypassing the dsh-llm-pi-ai settings compat schema.
2. Wraps them in the exported PiAiAdapter, registers the adapter for both routes with ctx.llm.registerAdapter.
3. Serves the quota snapshot/config web routes through webServer, and the LLM API-key config routes that write the DSH credential store.
4. The client registers the floating quota monitor and the single settings → plugins 「火山方舟配置」 card (quota + LLM credentials with masked echo-back).

Acknowledgements

Model catalogs, max output tokens, and compatibility switches are sourced from the community-verified Volcengine Ark provider extensions for pi:

• pi-provider-volcengine-agent-plan — the Agent Plan Responses path, tier gating, and Kimi routing decisions.
• pi-provider-volcengine-codingplan — the Coding Plan compat switches and model caps.
• pi-provider-volcengine-ark — per-model thinking formats for the coding endpoint.

The quota monitor UI references the MIT-licensed community plugins listed in THIRD_PARTY_NOTICES.md.

License

MIT (see LICENSE)