前言¶
DeepSeek Harness（DSH）采用插件化架构，通过组合配置与 UI 注入扩展功能。在智能体开发中，直接对接火山方舟（Volcengine Ark）的 Agent Plan 与 Coding Plan 套餐需要额外的路由配置与额度管理。该插件通过在 llm-pi-ai 适配器中声明 Provider，并提供会话标题栏的额度 Pill 与模型管理页面，解决了原生 DSH 对 Ark 套餐支持不足的问题。
核心功能¶
该插件主要解决以下问题：
* 模型接入：在 DeepSeek Harness 的模型选择器中增加“火山方舟 Agent Plan”与“Coding Plan”两个 Provider。
* 额度追踪：在会话标题栏显示每条车道的额度用量与刷新时间，避免跑满后才发现。
* 精细控制：在设置页逐条启用或停用模型，隐藏不需要的模型。
安装与启用¶
安装插件后，需要重启对应的 profile（Web 端不能同时起两个实例）。
dsh plugin --profile web add github:HaydenSmith1121/dsh-ark-plans
重启后，依次完成以下步骤：
1. 打开 设置 → 模型，你会看到新增的两个 Provider 行。
2. 点击对应行的 API Key 输入框，粘贴套餐的 API Key。
3. 回到对话页，在模型选择器中选择方舟模型即可使用。
注意：API Key 会存储在 $DSH_HOME/.credentials.yaml 的顶层 refs: 下，键名为配置中声明的引用名（如 ARK_AGENT_PLAN_API_KEY）。如果启动 harness 的环境变量中存在同名变量，它会覆盖页面填写的值（页面会显示只读）。
额度显示机制¶
会话标题栏右侧会出现一个 Pill，每条车道一格，显示进度条与已用百分比。
数据来源：
额度数据不在 OpenAI 兼容接口的 /usage 或 /quota 路径中（实测返回 404）。真正的额度由控制面提供，插件通过 arkcli 在本地建立的身份（STS 或 AK-SK 签名）调用控制面接口获取。
状态处理：
插件不会编造数字，当无法获取额度时会显示具体原因：
* expired：arkcli 的 SSO 凭证已过期，需运行 arkcli auth login volc-sso。
* no-identity：未找到 arkcli 身份。
* not-subscribed：该账号下车道没有生效订阅。
* error：控制面签名被拒绝。
在未登录 arkcli 时，插件仍可正常调用模型，只是额度 Pill 显示“不可用”并说明原因。
模型管理（启用/停用）¶
插件 0.3.0 版本新增了设置页面的模型管理功能。通过 设置 → 模型管理，可以勾选或取消勾选模型。
工作原理：
* 取消勾选会将模型 ID 从 dsh-ark-plans.enabledModelIds 中移除。
* 插件会在 llm-pi-ai.providers 的配置中动态调整模型清单，从而在模型选择器中隐藏这些模型。
* 保存按钮只在有改动时可点；写入失败会原地显示原因，不会回滚勾选状态。
边界情况：
* 空清单代表“全开”（恢复默认），而非“全关”。
* 恢复全选必须列出完整的模型清单，因为 pi-ai 的 models 字段是整表替换，不允许为空。
模型清单与自定义¶
Agent Plan 车道：
该车道不支持模型发现接口，插件内置了 12 个已验证模型 ID。这些 ID 是通过真实请求探测确认的，包括：
ark-code-latest, doubao-seed-evolving, doubao-seed-2-1-turbo, doubao-seed-2-0-lite, doubao-seed-2-0-mini, glm-5.3, glm-5-3-flash, kimi-k3, kimi-k2.7-code, minimax-m3, deepseek-v4-pro, deepseek-v4-flash。
Coding Plan 车道：
插件仅内置了官方文档中的智能路由模型 ark-code-latest。如果需要添加其他模型，可以使用 arkcli plans model-list --plan coding-plan 获取权威清单，并在 设置 → 模型 中手动编辑该 Provider 的 models 列表。
自定义模型：
你可以在 settings.yaml 中手动追加模型清单，这会整表替换该 Provider 的配置。注意，手动修改后若再点击“保存”，会以页面勾选状态为准。
已知限制¶
- 不支持图片输入：所有模型条目未声明
input: [text, image]，输入图片会被 provider 拒绝。 - 不提供思考强度调节：虽然模型返回
reasoning_content，但插件未声明reasoningEfforts，因此选择器中无法调整思考强度，模型按默认强度运行。 - Provider 删除限制：由于 pi-ai 的设计，组合层声明的 Provider（如
ark-agent-plan）用户无法通过设置页删除，只能通过卸载插件移除。 - 与 arkcli 冲突：
arkcli helper configure deepseek-harness与本插件会各自写入配置，路由名不同（如arkcli-agent-planvsark-agent-plan），需注意不要混淆。
总结¶
该插件为 DeepSeek Harness 提供了火山方舟 Agent Plan 与 Coding Plan 的完整接入方案。它利用官方 llm-pi-ai 适配器支持流式、工具调用与重试策略，并通过 arkcli 实现了准确的额度监控。对于需要使用火山方舟模型进行智能体开发的用户，这是一个必要的配置补充。
