账号池插件 AITabby/dockyard-dsh

Dockyard DSH

DeepSeek Harness（dsh）的原生账号池与服务商插件。

中文 · English

Current status / 当前状态: 开发者预览 · macOS DMG 已提供 · Windows EXE 已构建完成，正在上传。

Dockyard DSH 是什么

Dockyard DSH 把多个官方 OAuth / 官方客户端会话接入 DeepSeek Harness，提供统一的账号池、模型目录、额度状态和服务商原生请求入口。它是 DSH 的原生 bundle/plugin，不需要另起一个代理网关，也不把服务商逻辑塞进 DSH 核心。

当前包含的服务商模块：

- Codex — 官方浏览器 OAuth、CLI fallback 和原生 Responses 请求链路。
- Antigravity — Google 官方浏览器 OAuth、官方本机会话、实时模型目录、额度/credits 和原生 Gemini SSE 请求链路。
- Grok — xAI 官方浏览器 OAuth、CLI fallback、实时模型目录、官方 Build credits 周期和服务商原生 streaming 请求。额度读取使用官方 /billing?format=credits（转发 GetGrokCreditsConfig）；若上游只返回周期，剩余值保持未知。
- Claude — Claude 官方浏览器 OAuth（支持带 state 的手动回调地址/授权码）、CLI fallback 与原生请求适配。
- Cursor — Cursor 官方浏览器登录轮询、CLI fallback 与原生请求适配。

如果对应的官方客户端、CLI 或 OAuth 源没有安装、没有登录，Dockyard 会返回明确的 unavailable/degraded 状态；不会用硬编码的账号、模型、版本、套餐或额度伪造可用结果。

主要功能

- 在 DSH 内使用 /dockyard 命令管理账号和服务商。
- 点击「登录添加账号」直接打开服务商官方浏览器授权页，选择账号并安全导入账号池；服务商不可用时保留 CLI fallback。
- 扫描本机已有的官方登录态；扫描和新增账号是两个独立操作，已有账号不会被「新增」静默重复导入。
- 支持手动选择、sticky session、round-robin 和 failover 账号池策略。
- 读取服务商返回的实时模型目录、推理档位、套餐和额度窗口。
- 所有命令、模型选择和 LLM 生成都读取同一个 Dockyard runtime，不维护第二套账号池或额度缓存。

平台支持：macOS 已发布，Windows 构建完成

当前 0.1.2 版本正在整理；macOS DMG 已提供，Windows EXE 已完成构建，待上传到 v0.1.2 Release。

macOS 完整功能依赖以下原生能力：

- 凭据存储使用 macOS Keychain 和 Swift helper。
- 浏览器 OAuth 由 DSH GUI 打开服务商官方授权页面，并使用 PKCE、state 校验和 loopback/manual-code 回调；CLI fallback 才使用官方 CLI。
- 扫描模式仍可读取 Cursor、Antigravity 等服务商的 macOS 官方桌面端或本机 CLI 会话状态。

Windows 版本已完成 EXE 构建，待上传到 v0.1.2 Release；上传完成后再进行发布页下载验证。

macOS 独立应用与 DMG

如果不想手动安装 Node.js、pnpm 或 DSH，可以直接下载自带完整运行时的 macOS 通用 DMG：

下载最新 Dockyard DSH DMG

也可以在 Mac 上自行构建：

./apps/macos/build-dmg.sh

DMG 内置 Node.js、DSH CLI、完整 web 配置档和 Dockyard 插件；双击 App 即可运行，不需要另外安装 Node.js、pnpm 或 DSH。它会在原生 WebKit 窗口中显示内置的 DSH Web 配置档；OAuth 授权页会交给系统默认浏览器打开。当前构建包含 Apple Silicon 和 Intel 两个架构。详细说明见 apps/macos/README.md。

仍需注意：这是 macOS 专用、当前为本地 ad-hoc 签名的开发预览；某些服务商的官方 CLI 扫描/兼容性 fallback 仍可能需要对应 CLI，Antigravity 浏览器授权仍需要配置官方 OAuth client 信息。

一条命令安装 Dockyard plugin

如果已经有 Node.js，直接把下面这一行交给终端或智能体执行即可：

npx -y @dockyard-dsh/install@latest

它会自动检查 DSH 和 pnpm，并把预构建的 Dockyard host/client bundle 安装到默认 web 配置档。安装完成后重启 DSH Web。

从源码安装 Dockyard plugin / Web profile

Dockyard DSH 作为源码 plugin 安装到已有 DSH Web 配置档时，才需要先安装 DSH CLI，并确认 dsh 命令可用。

当前上游 DSH CLI 的 npm 安装方式：

DSH 当前是 developer preview；请使用上游要求的 Node.js 版本。
当前上游 package.json 要求 Node 22.19+ 的 22.x，或 Node 24+。
npm install --global @deepseek-ai/dsh
npm install --global pnpm

dsh --version
pnpm --version
上游安装和兼容性变化以 DeepSeek Harness 官方仓库 为准。当前 bundle 已按 @deepseek-ai/dsh@0.1.5-rc.2 验证。DSH 仍处于 developer preview，升级已有 DSH_HOME 前请先备份数据，并先用独立的 DSH_HOME 验证。

通过 DSH 插件市场（发现页）图形化安装

DSH（v0.2.1+）支持通过插件市场索引（Marketplace Index）在 Web 界面中一键安装：

1. 打开 DSH Web 侧边栏 -> 设置 (Settings) -> 插件 (Plugins) -> 发现 (Discover)。
2. 点击 管理索引源… (Index sources)，添加 Dockyard 官方市场索引源： https://raw.githubusercontent.com/AITabby/dockyard-dsh/main/market/index.json

3. 在列表中找到 Dockyard DSH，点击 安装 (Install) 即可完成安装。

最简便的方式：直接安装到 DSH Web profile

web 是 DSH 自带的完整 Web profile；不要新建只包含 Dockyard bundle 的空 profile，否则不会启动 Web GUI。

dsh plugin --profile web add github:AITabby/dockyard-dsh
dsh web

默认访问 http://127.0.0.1:3080。首次启动可先检查组合配置：

dsh web --dump-config

如需固定版本，建议 pin 到已验证的 commit：

dsh plugin --profile web add github:AITabby/dockyard-dsh#<commit-sha>

当前发布 commit 已提交可运行的 host/client bundle，安装时不执行 prepare，因此 GitHub 直装不需要额外的 allowBuilds 配置。若你 pin 到旧 commit，或 pnpm 明确报告了其他构建脚本，请只在检查源码后按终端提示配置对应 profile 的 pnpm-workspace.yaml。

需要本地修改时：克隆后安装

git clone https://github.com/AITabby/dockyard-dsh.git
cd dockyard-dsh
npm install
npm test # 可选：验证环境
npm run build # 修改 source 或 bundle 过期时需要

dsh plugin --profile web add .
dsh web

要隔离测试、不影响默认 DSH home：

DSH_HOME=/tmp/dockyard-dsh-home dsh plugin --profile web add .
DSH_HOME=/tmp/dockyard-dsh-home dsh web --dump-config
DSH_HOME=/tmp/dockyard-dsh-home dsh web

仓库已提交 packages/dsh-plugin/dist/index.mjs 和 packages/dsh-plugin/lib/client.js；普通用户不需要先运行测试或构建即可使用已发布 commit。

DSH 内的命令

在运行中的 DSH profile 中：

/dockyard status
/dockyard scan [provider]
/dockyard add [provider] [candidateId]
/dockyard login <provider>
/dockyard refresh [provider]
/dockyard models <provider>
/dockyard policy <provider> <manual|sticky_session|round_robin|failover> [accountId]
/dockyard use <provider> <accountId>
/dockyard remove <provider> <accountId>

新增账号流程是 /dockyard login <provider>（直接打开官方浏览器 OAuth）；如果要导入已有本机登录态，则使用 /dockyard scan <provider> 后再 /dockyard add <provider>，最后用 /dockyard status 和 /dockyard models <provider> 检查实时状态。

官方浏览器 OAuth / active session 边界

- Codex、Antigravity、Grok、Claude、Cursor 的「登录添加账号」默认由 DSH 直接打开官方浏览器授权页，不要求本机先安装 CLI；CLI 仅作为兼容性 fallback。
- Codex 使用 loopback PKCE；Antigravity 使用 Google loopback OAuth；Grok 使用 xAI loopback OAuth；Cursor 使用官方 loginDeepControl + /auth/poll；Claude 使用官方网页回调，手动输入时要求粘贴带 state 的完整回调地址或 code#state。
- Antigravity 的 Google OAuth client ID/secret 必须通过 DOCKYARD_ANTIGRAVITY_CLIENT_ID 和 DOCKYARD_ANTIGRAVITY_CLIENT_SECRET 提供，仓库不内置凭据；需要浏览器 OAuth 时，先在启动 DSH 的 shell 中设置这两个环境变量（或写入 ~/.zshrc），不要提交到仓库。
- 扫描仍可读取本机已有的官方客户端/CLI 会话；扫描和浏览器新增账号不会互相替代。
- provider 的 OAuth endpoint、token response 或授权范围变化时，Dockyard 会显示 unavailable/degraded，不猜测未验证的字段。

凭据和安全边界

- 原始 OAuth/token 不写入 Git、账号池快照或页面状态；运行时只传递 opaque credential reference。
- 浏览器 OAuth 的 refresh token 持久化在安全凭据存储中；支持 refresh 的服务商会在重启后自动刷新短期 access token，只有服务商撤销 refresh token 或改变协议时才需要重新授权。
- macOS 默认使用 Keychain；非 macOS 默认 credential store 会 fail closed，不会静默退回不安全的内存存储。
- 额度、模型、套餐、账号身份和过期时间都来自服务商的实时结果；服务商不返回时保持 unknown/null。
- 发布和提 issue 前请阅读 SECURITY.md，不要提交 token、OAuth 文件、Keychain 值或包含敏感信息的日志。

开发与验证

npm install
npm test
npm run build
npm run build:plugin
npm pack --dry-run

发布包的关键内容是：

packages/dsh-plugin/dist/index.mjs # Node/host bundle
packages/dsh-plugin/lib/client.js # browser client bundle
packages/dsh-plugin/cordis.patch.yml # DSH bundle layer

npm pack --dry-run 应只显示发布入口、client bundle、patch、必要的 package metadata 和安全说明。修改 provider source 后，重新执行 npm run build，再提交更新后的构建产物。

项目结构

packages/core/ 模块生命周期、契约、事件和 DSH route packages/account-pool/ 账号发现、选择、健康状态和 credential reference packages/runtime/ 一个共享的 Dockyard runtime packages/dsh-plugin/ DSH bundle、LLM adapter、命令和 client UI packages/vault/ macOS Keychain backend modules/provider-/ 各 provider 自己的 OAuth、目录、额度和 native transport tests/ 安全、生命周期、provider 和 runtime 测试

核心原则是：provider-specific 逻辑留在 provider module，账号选择留在 runtime，host 只消费稳定契约。不要在 host 中新增 provider 特判，也不要把动态 provider 数据写成常量。

已知限制

- DSH 本身仍处于 developer preview，上游可能发生 breaking changes。
- 服务商的官方 CLI、客户端路径、OAuth 返回字段和额度接口都可能变化；Dockyard 对缺失字段保持未知。
- 浏览器 OAuth 多账号依赖服务商官方授权页和 token response；如果服务商暂停或改变该流程，必须重新验证 endpoint，而不是猜测协议。
- Windows EXE 已完成构建但仍在上传和验证中；在发布页出现并完成验证前，请勿用于 Windows 生产环境。

What it is

Dockyard DSH 是原生 DeepSeek Harness bundle/plugin，把官方 OAuth 和官方客户端会话接到同一个共享账号池、模型目录、额度视图和服务商原生请求路径。它不需要第二层代理网关，也不会把服务商专属分支塞进 DSH 核心。

当前的服务商模块：

- Codex — 官方浏览器 OAuth、CLI fallback 和原生 Responses transport。
- Antigravity — Google 浏览器 OAuth、官方本地会话、实时模型目录、额度/credits 和原生 Gemini SSE transport。
- Grok — xAI 浏览器 OAuth、CLI fallback、实时模型目录、官方 Build credits 周期和服务商原生流式传输。额度走官方 /billing?format=credits 接口（转发 GetGrokCreditsConfig）；如果上游只返回周期，剩余额度保持未知。
- Claude — 官方浏览器 OAuth（包括绑定 state 的手动 callback/code 输入）、CLI fallback 和原生请求适配器。
- Cursor — 官方浏览器登录轮询、CLI fallback 和原生请求适配器。
官方客户端、命令行或 OAuth 来源缺失、未登录时，Dockyard 会明确报告不可用/降级状态。它不会凭空编造账号、模型、版本、套餐或配额数值。

功能

- 在 DSH 的 /dockyard 命令界面里管理服务商和账号。
- 从「登录/添加账号」打开各服务商的官方浏览器授权页，安全导入已完成的会话；同时保留命令行回退方案以兼容旧方式。
- 扫描已有官方登录状态与添加新账号分开进行；已有账号绝不会被「添加」操作悄悄重新导入。
- 手动选择账号，或使用粘性会话、轮询、故障转移策略。
- 读取服务商实时模型目录、推理档位、套餐和配额窗口。
- 让命令、模型选择和生成共用同一套 Dockyard 运行时与唯一数据源。

平台支持：macOS 已发布，Windows 构建完成

0.1.2 版本正在准备发布。macOS DMG 已可用；Windows EXE 已构建完成，等待上传到 v0.1.2 发布页。

macOS 集成依赖系统原生行为：

- 凭据存放在 macOS Keychain，由一个 Swift 辅助程序读写。
- 浏览器 OAuth 由 DSH GUI 打开，使用 PKCE、state 校验、回环回调或手动输入授权码；官方命令行仅作回退。
- 扫描模式仍会读取 macOS 桌面端或本地命令行的会话状态，前提是服务商提供这类状态。

Windows EXE 构建已完成，等待上传到 v0.1.2 发布页；上传完成后会进行下载验证。

独立 macOS 应用与 DMG

不想手动安装 Node.js、pnpm 或 DSH，可以下载自带全部依赖的通用 DMG：

下载最新 Dockyard DSH DMG

或在 macOS 上自行构建：

./apps/macos/build-dmg.sh

DMG 内嵌 Node.js、DSH 命令行、完整的 web 配置档和 Dockyard 插件。启动应用即可，无需另外安装 Node.js、pnpm 或 DSH。OAuth 授权页在系统默认浏览器中打开。详情见 apps/macos/README.md。当前构建包含 Apple Silicon 和 Intel 两种架构切片。这是仅面向 macOS 的开发者预览版，使用本地 ad-hoc 签名；部分服务商的命令行扫描/兼容回退仍需对应服务商的命令行，Antigravity 的浏览器 OAuth 仍需官方 OAuth 客户端配置。

一条命令安装 Dockyard 插件

如果已有 Node.js，把下面这条命令交给终端或智能体：

npx -y @dockyard-dsh/install@latest

它会检查 DSH 和 pnpm，然后把预构建的 Dockyard 宿主/客户端包安装到默认 web 配置档。安装完成后重启 DSH Web。

把源码插件安装到现有 DSH Web 配置档

Dockyard DSH 是 DSH 插件，不是独立智能体。把源码插件装进已有 DSH 配置档时，需要先满足这个前提：先安装 DSH 命令行，确认 dsh 命令可用：

DSH is currently a developer preview. Use the Node.js version required by DSH.
The current upstream package declares Node 22.19+ on the 22.x line, or Node 24+.
npm install --global @deepseek-ai/dsh
npm install --global pnpm

dsh --version
pnpm --version

上游安装方式与兼容性变更，请关注 DeepSeek Harness 官方仓库。当前 bundle 已在 @deepseek-ai/dsh@0.1.5-rc.2 上验证。DSH 仍处于开发者预览阶段；升级前请备份已有的 DSH_HOME，并用隔离的 DSH_HOME 验证。

通过 DSH 插件市场安装（Discover 标签页）

DSH（v0.2.1+）支持通过市场索引可视化安装插件：

1. 打开 DSH Web -> Settings -> Plugins -> Discover 标签页。
2. 点击 Manage index sources...，添加 Dockyard DSH 市场索引 URL： https://raw.githubusercontent.com/AITabby/dockyard-dsh/main/market/index.json

3. 在列表中找到 Dockyard DSH，点击 Install。

最短路径：直接装进 DSH Web 配置档

web 是 DSH 内置的完整 Web 配置档。想要图形界面，就不要新建空的自定义配置档。

dsh plugin --profile web add github:AITabby/dockyard-dsh
dsh web

默认 URL 是 http://127.0.0.1:3080。想先查看合成后的配置：

dsh web --dump-config

需要可复现的安装时，固定到已验证的 commit：

dsh plugin --profile web add github:AITabby/dockyard-dsh#<commit-sha>

当前发布 commit 已包含可直接运行的 host/client bundle，安装时不执行 prepare，所以直接从 GitHub 安装不需要额外设置 allowBuilds。如果固定到较旧的 commit，或 pnpm 明确报告了其他构建钩子，请先检查源码，再按命令打印出的配置档配置原样操作。

需要本地改动时：克隆后安装

git clone https://github.com/AITabby/dockyard-dsh.git
cd dockyard-dsh
npm install
npm test # optional environment check
npm run build # needed after source or bundle changes

dsh plugin --profile web add .
dsh web

做隔离测试、不影响默认 DSH home：

DSH_HOME=/tmp/dockyard-dsh-home dsh plugin --profile web add .
DSH_HOME=/tmp/dockyard-dsh-home dsh web --dump-config
DSH_HOME=/tmp/dockyard-dsh-home dsh web

仓库已提交 packages/dsh-plugin/dist/index.mjs 和 packages/dsh-plugin/lib/client.js，普通用户使用发布 commit 时无需先跑测试或构建。

DSH 命令

/dockyard status
/dockyard scan [provider]
/dockyard add [provider] [candidateId]
/dockyard login <provider>
/dockyard refresh [provider]
/dockyard models <provider>
/dockyard policy <provider> <manual|sticky_session|round_robin|failover> [accountId]
/dockyard use <provider> <accountId>
/dockyard remove <provider> <accountId>

新账号用 /dockyard login <provider> 打开官方浏览器 OAuth。要导入已有的本地会话，先 /dockyard scan <provider>，再 /dockyard add <provider>，然后用 /dockyard status 和 /dockyard models <provider> 查看。

官方浏览器 OAuth 与活动会话的边界

- 点 Login/Add 时，Codex、Antigravity、Grok、Claude、Cursor 直接打开服务商的官方浏览器授权页，不需要本地命令行。命令行仍作为兼容回退。
- Codex 用 loopback PKCE；Antigravity 用 Google loopback OAuth；Grok 用 xAI loopback OAuth；Cursor 用官方 loginDeepControl + /auth/poll 流程；Claude 用官方托管回调，手动输入时回调 URL 必须带 state（或 code#state）。
- Antigravity 浏览器 OAuth 需要 DOCKYARD_ANTIGRAVITY_CLIENT_ID 和 DOCKYARD_ANTIGRAVITY_CLIENT_SECRET；仓库不内置 OAuth 凭据。在启动 DSH 的 shell 里设置（或写进 ~/.zshrc），绝不提交。没有这两个变量时，改用 Scan 或命令行回退读取已有的本地/命令行会话。
- Scan 仍能读取已有的官方桌面/命令行会话。Scan 和浏览器添加账号是两件独立的事。
- 服务商改了 OAuth 端点、token 响应或 scope 时，Dockyard 会报告不可用/降级，不去猜未公开的字段。

凭据与安全

- 原始 OAuth/token 值不写进 Git、账号池快照或页面状态；运行时只用不透明的凭据引用。
- 浏览器 OAuth 的 refresh token 存在安全凭据存储里；支持刷新的服务商在重启后自动续短时 access token，但服务商撤销授权或协议变更时仍需重新授权。
- macOS 默认用 Keychain。非 macOS 默认失败关闭，不会悄悄退回不安全的 in-memory 存储。
- 服务商模型、套餐、配额、身份和过期时间都取自服务商的实时响应；缺失的值保持 unknown/null。
- 提 issue 前先读 SECURITY.md。绝不提交 token、OAuth 文件、Keychain 值或敏感日志。

开发与验证

npm install
npm test
npm run build
npm run build:plugin
npm pack --dry-run

可分发入口：

packages/dsh-plugin/dist/index.mjs # Node/host bundle
packages/dsh-plugin/lib/client.js # browser client bundle
packages/dsh-plugin/cordis.patch.yml # DSH bundle layer

改完服务商源码后，跑 npm run build，把刷新后的产物和源码改动一起提交。

项目结构

packages/core/ lifecycle, contracts, events, and DSH routes
packages/account-pool/ 账号发现、选择、健康检查与引用 packages/runtime/ 共享的 Dockyard 运行时 packages/dsh-plugin/ DSH 打包、LLM 适配器、命令与客户端 UI packages/vault/ macOS Keychain 后端 modules/provider-/ 服务商 OAuth、目录、配额与原生传输 tests/ 安全、生命周期、服务商与运行时测试

核心规则很简单：服务商专属逻辑留在服务商模块里，账号选择留在运行时里，宿主只消费稳定契约。不要给宿主加服务商专属分支，也不要硬编码动态的服务商数据。

已知限制

- DeepSeek Harness 仍是开发者预览版，可能引入破坏性变更。
- 官方服务商命令行、桌面端路径、OAuth 字段和配额 API 都可能变化；缺失的字段保持未知。
- 浏览器账号池的行为取决于各服务商官方 OAuth 页面和 token 响应；端点变化后需要重新验证，不要猜测协议字段。
- Windows EXE 已构建，但仍在上传和验证中；在发布资产可用并验证通过之前，不要用于生产环境。