mn288/dsh-vertex-gemini

dsh-vertex-gemini

在 DeepSeek Harness（dsh）中，通过 Google Cloud Vertex AI 使用 Gemini，并使用你自己的 Google 账号登录。不会创建或存储任何 API 密钥：该插件使用你机器上已有的 Google 登录（应用默认凭据），并向你指定的 Google Cloud 项目计费。

它可与官方 npx @deepseek-ai/dsh 配合使用——无需 fork，也无需构建。

你需要准备

- Node.js 22.19+ 或 24+。
- gcloud CLI。
- PATH 中有 pnpm（npm install -g pnpm）：dsh plugin 命令会在 profile 内运行它。
- 对此仓库的读取权限，以及已登录的 GitHub CLI（gh auth login），用于下载 release。
- 一个已启用 Vertex AI API 的 Google Cloud 项目，以及调用它的权限（roles/aiplatform.user）。

设置（约两分钟）

1. 登录一次。这会存储一个 Google 登录，插件会自行刷新它：

gcloud auth application-default login

2. 将最新 release 下载到一个你会保留的文件夹中，然后将其安装到 Web profile。profile 会记录 tarball 的绝对路径，因此从 Downloads 中删除文件会导致下次安装 profile 失败；~/.dsh/plugins 是存放它的安全位置：

mkdir -p ~/.dsh/plugins
gh release download --repo mn288/dsh-vertex-gemini --pattern '*.tgz' --dir ~/.dsh/plugins
npx @deepseek-ai/dsh plugin --profile web add ~/.dsh/plugins/dsh-vertex-gemini-0.1.0.tgz

pnpm 最后会输出一段 missing peer @deepseek-ai/... 警告。这是预期情况：这些包位于 profile 树中上一级目录，Node 在运行时会找到它们。要查找的行是 dependencies 下的 + dsh-vertex-gemini。

如果还想从终端使用该插件，请使用 --profile headless 重复执行 add 命令。以后要更新时，将更新的 release 下载到同一文件夹，并使用新文件运行相同的 add 命令。

3. 指定你的 Google Cloud 项目。可以在启动 dsh 的 shell 中导出它：

export GOOGLE_CLOUD_PROJECT=my-gcp-project

或将其保存在 $DSH_HOME/settings.yaml 中（默认是 ~/.dsh/settings.yaml）：

llm-vertex:
project: my-gcp-project

4. 启动 Web UI 并选择模型：

npx @deepseek-ai/dsh web

如果 dsh web 已在运行，请停止它并重新启动：插件在启动时加载。然后打开模型选择器，选择 Google Vertex AI → Gemini 3.8 Flash。该选择将成为新会话的默认值。

选择器提供 Low、Medium 和 High 推理级别。如果 settings.yaml 中因其他提供商而残留 xhigh 或 max 的默认值，会导致每个请求都失败并报 UNSUPPORTED_REASONING_EFFORT；请在选择器中选择一个级别，或在 agent-default-model 下设置 reasoningEffort: high。
在设置项目之前，提供程序会列在 Settings → Models 下，但选择器中不会出现任何模型。这是预期行为：在知道要调用哪个项目之前，该路由保持关闭。

要移除插件：npx @deepseek-ai/dsh plugin --profile web remove dsh-vertex-gemini。

设置

每个字段都是可选的，位于 settings.yaml 中的 llm-vertex: 下。更改会在下一次请求时生效；无需重启。

| 字段 | 默认值 | 含义 |
|---|---|---|
| project | $GOOGLE_CLOUD_PROJECT，然后是 $GCLOUD_PROJECT | 被调用并计费的 Google Cloud 项目 |
| location | global | Vertex AI 位置；诸如 europe-west1 之类的区域会使用该区域的端点 |
| reasoningEffort | high | 默认思考级别：low、medium 或 high |
| models | Gemini 3.8 Flash | 选择器中显示的模型；每个条目接受 id，以及可选的 name、description、contextWindow、maxTokens |
| maxTokens | 65536 | 未指定该值的模型的输出上限 |
| defaultContextWindow | 1048576 | 未指定该值的模型的上下文大小 |
| publisher | google | 在传输时添加到裸模型 id 的前缀（gemini-3.8-flash 会作为 google/gemini-3.8-flash 发送） |
| baseURL | 根据项目和位置计算 | 完整的 OpenAI 兼容端点根，用于公司网关 |
| auth | adc | adc 使用 Google 登录；access-token 读取你提供的 bearer |
| accessTokenEnv | GOOGLE_OAUTH_ACCESS_TOKEN | 当 auth: access-token 时 bearer 的来源（用于自行生成令牌的 CI 任务） |
| streamIdleTimeoutMs | 300000 | 响应中一段静默时间可以持续多久，超过后请求失败 |
| retryPolicy | 五次重试 | 失败的模型请求的重试行为 |

添加第二个模型：

llm-vertex:
project: my-gcp-project
models:
- id: gemini-3.8-flash
name: Gemini 3.8 Flash
- id: another-gemini-model-id   # any model id your project can call
name: Shown in the picker

你的项目可以调用的任何 Gemini 模型 id 都可以使用，即使它未被列出；该列表仅用于填充选择器。

当某些东西失败时

| 消息 | 原因和修复 |
|---|---|
| MISSING_CREDENTIAL … run "gcloud auth application-default login" | 此机器上没有 Google 登录，或登录已过期。运行该命令并重试；无需重启。 |
| AUTH | 登录存在，但 Google 拒绝了它（已撤销，或账户缺少访问权限）。重新登录，并检查该账户在项目上具有 roles/aiplatform.user。 |
| NOT_FOUND | 项目无法使用该模型，或模型 id 或位置错误。检查 id，尝试 location: global，并确认 Vertex AI API 已启用。 |
| QUOTA / RATE_LIMIT | 项目的 Gemini 配额已耗尽或受到限制。测试框架会自行重试；如果问题持续存在，请在 Cloud 控制台中提高配额。 |
| 选择器中没有 Vertex 模型 | 未配置项目。参见步骤 3。 |
| UNSUPPORTED_CONTENT | 你附加了图像。此插件仅发送文本。 |
验证状态

已于 2026-09-21 针对真实的 Vertex AI API（项目 common-ai-tooling-prd，位置 global，Gemini 3.8 Flash）完成验证：下面的真实 API 测试（先是一个文本回答，然后是一次带签名回放的工具调用往返）通过，并且从发布 tarball 安装的无头 dsh 会话通过工具读取了一个文件并正确作答。单元测试、Loader 启动测试，以及针对本地 mock 的安装并运行冒烟测试也均通过。

每当适配器或 harness 版本发生变化时，请使用有效的 Google 登录重新运行真实 API 测试：

DSH_VERTEX_E2E=1 DSH_VERTEX_PROJECT=my-gcp-project pnpm exec vitest run tests/adapter.e2e.ts

Gemini 3.8 Flash 会将思考 token 计入输出上限：maxTokens 设置得非常小的请求可能会以 max-tokens 结束且没有文本。请将上限保留为默认值（65536），或至少设为数千。

限制

- 仅支持文本。 图像输入会被拒绝，而不是被静默丢弃。
- 没有设置表单。 Models 页面会列出该提供方，但没有为其提供专门的卡片；请通过环境变量或如上所示的 settings.yaml 进行配置。
- 已针对 @deepseek-ai/dsh 0.1.5-rc.2 测试。 harness API 尚处于预稳定阶段，因此后续版本可能需要更新插件。

工作原理

该插件注册一个提供方路由 vertex-ai，并通过流式方式与 Vertex AI 的 OpenAI 兼容 chat-completions 端点通信。有两个细节对 agent 工作很重要：

- 思考签名。 Gemini 3 会为工具调用附加一个不透明签名，如果后续请求未将其发回，则会拒绝该请求。该插件会将每个签名存储在会话日志中工具调用的旁边，并在后续请求中回传，因此多步骤工具使用在重启和恢复会话后仍能继续。由其他模型或提供方生成的历史记录则会使用 Google 文档中所述的跳过标记发送。
- 凭据。 google-auth-library 会按 Google 的标准顺序查找登录信息（GOOGLE_APPLICATION_CREDENTIALS、gcloud 用户登录，然后是元数据服务器），缓存每小时令牌并刷新它。该库仅在首次请求时加载，因此当你使用其他提供方时，该插件在启动时不会产生任何开销。

开发

pnpm install
pnpm test          # unit tests, no network or Google login needed
pnpm run typecheck
pnpm run smoke     # packs the plugin, installs it with the published dsh CLI, and runs one prompt against a local mock endpoint

tests/adapter.e2e.ts 会调用真实 API。请使用有效的 Google 登录运行它：

DSH_VERTEX_E2E=1 DSH_VERTEX_PROJECT=my-gcp-project pnpm exec vitest run tests/adapter.e2e.ts

分享它

该仓库是私有的，并且 package.json 中带有 "private": true，因此意外的 npm publish 会被拒绝。同事需要先获得读取权限：在仓库的 Settings → Collaborators 下添加他们。要将插件交给他们：
- 作为发布版本（当前设置）： 提升 version，运行 npm pack，并使用 gh release create v dsh-vertex-gemini-.tgz 将 .tgz 附加到新版本发布中。拥有仓库读取权限的同事可按设置步骤中所示进行安装。
- 通过内部注册表： 移除 "private": true，将 publishConfig.registry 指向该注册表，然后发布到那里；同事随后可按名称安装。

许可证

MIT。该适配器遵循 DeepSeek Harness LLM 适配器的结构，后者由 DeepSeek 以 MIT 许可证授权；请参阅 LICENSE。