前言¶

DeepSeek Harness (DSH) 默认使用一个全局凭证引用（通常为 DEEPSEEK_API_KEY），这导致所有会话和所有工作区共享同一个 API Key，难以将 API 调用成本与特定的开发或测试任务对应起来。dsh-workspace-api-key 插件通过在层级结构中为不同范围分配独立的密钥，解决了这一成本归属与密钥管理问题。

插件简介¶

这是一个由 COH2357 维护的 DeepSeek Harness 插件，用于绑定单独的 DeepSeek API Key 到每个工作区或单个会话。它通过拦截凭证解析流程，实现从“系统默认”到“工作区”再到“会话”的层级密钥覆盖，确保每一层没有自定义密钥时会自动继承上一层的配置。

核心功能¶

层级密钥管理
插件支持三层密钥配置：会话级、工作区级和系统默认级。配置逻辑遵循 session key → workspace key → system default 的优先级。
侧边栏界面
在 DSH 侧边栏中新增 API Key 分配 行，直接位于主机插件行下方。该行展开后显示所有工作区及其会话，每个层级都有独立的密钥输入框。
系统默认卡片
显示当前生效的全局默认引用（DEEPSEEK_API_KEY）、其来源（文件、环境变量等）以及掩码后的值。
连接测试
针对绑定的密钥发起真实的 POST <baseURL>/messages 请求（设置 max_tokens: 1），返回 ok、invalid、quota、rate-limit 或 unreachable 状态，成功测试可清除过期标记。
过期与不匹配警告
当绑定的密钥返回 401/403 时标记为 invalid，402 标记为 quota，429 标记为 rate-limit。若密钥与当前使用的 Provider 不匹配，也会在进入会话时通过遮罩层警告，但不会自动切换密钥。
安全与控制
插件不会静默替换密钥，决策权始终在用户手中。响应中绝不会包含明文密钥，仅显示掩码。API 访问仅限 Loopback 调用（127.0.0.1, ::1 等）。
一键还原
清除会话或工作区的密钥配置，即可回退到上一级配置（会话回退到工作区，工作区回退到系统默认）。

安装与启用¶

安装方式为通过包管理器直接添加 GitHub 仓库。请在 DSH 的配置目录（例如 ~/.dsh/profiles/desktop）中执行以下命令：

pnpm add "dsh-workspace-api-key@github:COH2357/dsh-workspace-api

安装完成后，插件会自动注册到 credentials.resolve 流程中，并在侧边栏生成对应的入口。

工作原理¶

插件通过两个部分协作实现功能：Host 端（lib/index.js）处理凭证解析，Browser 端（lib/client.js）处理 UI 渲染与交互。

Host 端通过 ctx.effect 包装 credentials.resolve，在每次凭证解析时读取当前会话的目录和 ID。它将目录与 workspaceRegistry.list() 进行匹配（规范化路径大小写和后缀），为匹配的工作区生成唯一的引用名：
- 工作区引用：DEEPSEEK_API_KEY_WS_<first 16 hex chars of sha1(normalized path), upper-cased>
- 会话引用：DEEPSEEK_API_KEY_SS_<first 16 hex chars of sha1(session id), upper-cased>

插件仅重写 Provider 实际读取的引用（默认引用、适配器的 apiKeyEnv 配置及生成的引用），其他引用保持原样。它会记录无效标记、Provider 不匹配等信息到本地存储文件 $DSH_HOME/storages/dsh-workspace-api-key.json。

Browser 端通过 React 注册到 sidebar.panellist 和 shell.overlay 等插槽，渲染密钥分配面板。它会从 sessionController 或 sessions 服务获取会话列表，并过滤掉子代理会话和空白会话，确保面板显示的内容与侧边栏一致。

HTTP API¶

插件提供一组 REST API 接口，仅允许 Loopback 调用，且响应不包含明文密钥。

方法	路径	说明
GET	`/wsk-api/state`	获取默认引用状态、工作区及会话列表、无效标记、插件版本及会话探针信息
GET	`/wsk-api/resolve`	查询当前会话正在解析的层级和引用
GET	`/wsk-api/check`	查询指定会话的只读状态（有效层级、密钥、过期标记、不匹配情况）
POST	`/wsk-api/set`	绑定密钥（`{scope: 'workspace' \\| 'session', path \\| sessionId, key, provider?}`），或使用 `{useDefault: true}` 清除
POST	`/wsk-api/test`	使用指定密钥进行真实连接测试并返回结果
POST	`/wsk-api/clear-flag`	清除指定引用的无效或配额标记

注意事项¶

插件以当前 DSH 进程的权限运行，安装前建议检查源码。
仅接受 Loopback 调用，且响应不包含明文密钥。
插件不执行静默替换，不会因为警告而自动切换密钥，这符合“将花费归属给特定会话”的设计初衷。
部分功能依赖于 workspaceRegistry 和 sessionController 服务，如果这些服务不可用或报错，面板可能无法正常显示会话列表。

总结¶

dsh-workspace-api-key 提供了一种精细化的 DeepSeek API Key 管理方案，通过层级覆盖机制和明确的警告反馈，帮助开发者在不改变 DSH 核心逻辑的前提下，实现按工作区或按会话的独立计费与密钥管理。

dsh-workspace-api-key

前言¶