dsh-vertex-argon 1.2.1 → 1.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +62 -0
- package/README.md +188 -88
- package/adapter.js +208 -344
- package/bounded-json.js +54 -0
- package/client.js +1738 -71
- package/diagnostic-store.js +348 -0
- package/diagnostics.js +289 -0
- package/generate-content.js +287 -0
- package/google-connection.js +36 -0
- package/google-signatures.js +151 -0
- package/index.js +99 -2
- package/inspector-overview.js +72 -0
- package/inspector-service.js +104 -0
- package/inspector-tool.js +71 -0
- package/interaction-adapter.js +143 -0
- package/interaction-image.js +6 -0
- package/interaction-lifecycle.js +16 -0
- package/interaction-query.js +69 -0
- package/interaction-state.js +222 -0
- package/interaction-transport.js +202 -0
- package/interactions-input.js +118 -0
- package/interactions.js +214 -0
- package/locale/en.json +1 -1
- package/locale/zh.json +1 -1
- package/package.json +54 -10
- package/pricing.js +84 -0
- package/request-association.js +110 -0
- package/response-store.js +111 -0
- package/service-level.js +37 -0
- package/structured-output.js +124 -0
- package/usage-details.js +48 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to `dsh-vertex-argon` are documented in this file.
|
|
4
|
+
|
|
5
|
+
## [1.5.0] - 2026-10-18
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
- **Argon Inspector Dashboard (Right-Sidebar, Conversation Tab & Per-Message Shortcut)**:
|
|
9
|
+
- Added full-featured Inspector UI in `client.js` mounted in both the Right Sidebar (`Argon`) and Conversation View (`dsh-vertex-argon/inspector`), plus a per-message Argon header button that jumps directly to `Selected Answer` scope.
|
|
10
|
+
- Added **Current Scope Overview** card (`inspector-overview.js`) summarizing request counts, outcomes, token totals, and estimated USD cost across `This Conversation`, `Selected Answer`, or `All Recent`.
|
|
11
|
+
- Added **Request Association Hub** (`request-association.js`) correlating `llm/stream`, `agent/assistant-stream`, and `session/event` to bind diagnostics to exact finalized assistant `messageId` and `settlementSeq` values across `LlmRuntime` clones.
|
|
12
|
+
- **Per-Modality Usage Ledger & Public Cost Estimator (`usage-details.js`, `pricing.js`)**:
|
|
13
|
+
- Normalized `GenerateContent` per-hop and `Interactions` aggregate usage into structured modality breakdowns (`TEXT`, `IMAGE`, `AUDIO`, `VIDEO`, `DOCUMENT`) across input, cache, output, thought, and tool tokens.
|
|
14
|
+
- Added public token price snapshot (`argon-public-2026-10-18`) and USD cost estimation clearly labeled as non-invoice estimates.
|
|
15
|
+
- **Explicit Service Tiers & Vertex PayGo Routing (`service-level.js`)**:
|
|
16
|
+
- Added `googleServiceTier`, `vertexServiceTier` (`standard`, `flex`, `priority`), and `vertexPaygoOnly` settings with fail-closed route × protocol capability validation (`ARGON_SERVICE_TIER_UNVERIFIED`) and observed response tier extraction.
|
|
17
|
+
- **Opt-In Raw Response Store & Cloud Interaction ID Lookup (`response-store.js`, `interaction-query.js`)**:
|
|
18
|
+
- Added `retainRawResponses` setting and bounded `vertex_argon_responses` storage domain with header/secret sanitization and paged character reading.
|
|
19
|
+
- Added read-only Cloud Interaction ID Lookup (`interactions.get(id)`) in the Inspector `Operations` tab and `argon_inspect` tool without mutating local recovery state or executing cloud tool calls.
|
|
20
|
+
- **Deferred Read-Only Agent Tool `argon_inspect` (`inspector-tool.js`)**:
|
|
21
|
+
- Registered `argon_inspect` (`deferLoading: true`) supporting `overview`, `list`, `detail`, `response`, `query`, and `query-response` actions within the current session scope.
|
|
22
|
+
- **Signature-Only `Part` Lossless Replay (`google-signatures.js`)**:
|
|
23
|
+
- Preserved opaque `thoughtSignature` / `thought_signature` fields on empty-content `Part` objects across `GenerateContent` and `Interactions` multi-turn replay and tool-call round-trips.
|
|
24
|
+
|
|
25
|
+
### Changed & Fixed
|
|
26
|
+
- **In-Band SSE Error Handling (`generate-content.js`)**:
|
|
27
|
+
- Detected HTTP `200` SSE frames containing top-level `{ error }` payloads, recording the failure in hop diagnostics and retrying from the latest `continuationToken` only when the error status is retryable.
|
|
28
|
+
- **Live Long Decode Verification (Odyssey-VII 365-Day Captain's Log Benchmark)**:
|
|
29
|
+
- Verified continuous single-turn `GenerateContent` Long Decode across **98,985 output tokens** (2 hops: `65,536` + `33,449` output tokens in `1,437.9s`, `0` reconnects) on `google-vertex/gemini-4-argon`.
|
|
30
|
+
- **Pre-Release Codebase & Package Cleanup**:
|
|
31
|
+
- Removed retired/unmounted experimental modules (`generate-content-checkpoint.js`, `protocol-policy.js`, `management-policy.js`, `management-input.js`, `structured-result-command.js`) and their obsolete tests, keeping the low-level `structured-output.js` wire helper intact.
|
|
32
|
+
- Regenerated `README.md` and `docs/implementation/` directly from the verified 1.5.0 codebase.
|
|
33
|
+
|
|
34
|
+
## [1.4.3] - 2026-10-18
|
|
35
|
+
|
|
36
|
+
### Fixed
|
|
37
|
+
- **Interactions Resumable Read Stream (`interactions.js`, `interaction-transport.js`)**:
|
|
38
|
+
- Switched background recovery from non-streaming `GET` polling to resumable `interactions.get(id, { stream: true, last_event_id })` whenever an event cursor is available, preventing duplicate block emission on reconnect.
|
|
39
|
+
|
|
40
|
+
## [1.4.2] - 2026-10-17
|
|
41
|
+
|
|
42
|
+
### Fixed
|
|
43
|
+
- **Interactions Pre-Dispatch Intent & Unknown-Create Lock (`interaction-state.js`, `interactions.js`)**:
|
|
44
|
+
- Recorded `phase: "creating"` before sending `interactions.create` and blocked automatic duplicate resubmission after an interrupted create request until explicitly released by the user.
|
|
45
|
+
|
|
46
|
+
## [1.4.1] - 2026-10-17
|
|
47
|
+
|
|
48
|
+
### Fixed
|
|
49
|
+
- **Credential Store Fail-Closed Boundary (`adapter.js`)**:
|
|
50
|
+
- Ensured errors thrown by the DSH `credentials` service abort request preparation immediately rather than falling back to ambient environment variables.
|
|
51
|
+
|
|
52
|
+
## [1.4.0] - 2026-10-16
|
|
53
|
+
|
|
54
|
+
### Added
|
|
55
|
+
- **Dual-Protocol Architecture (`generate-content` & `interactions`)**:
|
|
56
|
+
- Added full `Interactions` (`v1beta`) SSE & durable background task support alongside `GenerateContent` Long Decode (`v1beta1` / `v1`).
|
|
57
|
+
- Added `vertex_argon_diagnostics` and `vertex_argon_interactions` storage domains and dedicated Settings UI.
|
|
58
|
+
|
|
59
|
+
## [1.3.0] - 2026-10-15
|
|
60
|
+
|
|
61
|
+
### Added
|
|
62
|
+
- Initial multi-hop `GenerateContent` Long Decode (`continuationToken`) and dual-route (`google-vertex` / `google-generative-ai`) adapter for `gemini-4-argon`.
|
package/README.md
CHANGED
|
@@ -1,53 +1,148 @@
|
|
|
1
1
|
<div align="center">
|
|
2
|
-
<img src="./icon.svg" width="
|
|
2
|
+
<img src="./icon.svg" width="80" height="80" alt="Vertex Argon Icon" />
|
|
3
3
|
<h1>dsh-vertex-argon</h1>
|
|
4
|
-
<p><strong>Google Vertex AI & Gemini API
|
|
4
|
+
<p><strong>Google Vertex AI & Gemini Developer API 双通道 · 双协议 Gemini 4 Argon 全功能插件(面向 <a href="https://github.com/deepseek-ai/deepseek-harness">DeepSeek Harness</a>)</strong></p>
|
|
5
5
|
<p>
|
|
6
6
|
<a href="https://www.npmjs.com/package/dsh-vertex-argon"><img src="https://img.shields.io/npm/v/dsh-vertex-argon?style=flat-square&color=2563eb" alt="npm version" /></a>
|
|
7
|
-
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://img.shields.io/badge/DSH-0.
|
|
8
|
-
<a href="
|
|
7
|
+
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://img.shields.io/badge/DSH-0.2.1--rc.2-4f46e5?style=flat-square" alt="DSH compatibility" /></a>
|
|
8
|
+
<a href="#-工作原理与双通道--双协议架构流向"><img src="https://img.shields.io/badge/Protocols-GenerateContent%20%7C%20Interactions-0284c7?style=flat-square" alt="Protocols" /></a>
|
|
9
|
+
<a href="https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/gemini/4-argon"><img src="https://img.shields.io/badge/Thinking-LOW%20%7C%20MEDIUM%20%7C%20HIGH-0ea5e9?style=flat-square" alt="Thinking Levels" /></a>
|
|
10
|
+
<a href="#️-服务层级service-tiers与-vertex-paygo-能力矩阵"><img src="https://img.shields.io/badge/Service%20Tiers-Standard%20%7C%20Flex%20%7C%20Priority-8b5cf6?style=flat-square" alt="Service Tiers" /></a>
|
|
9
11
|
<a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-10b981?style=flat-square" alt="License" /></a>
|
|
12
|
+
<a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white" alt="Powered by dsh" /></a>
|
|
13
|
+
</p>
|
|
14
|
+
<p>
|
|
15
|
+
<a href="#-为什么需要这个插件">✨ 核心对比</a> ·
|
|
16
|
+
<a href="#-真实超长解码实测基准奥德赛七号全年-365-天舰长日志">🧪 98.9K 长解码实测</a> ·
|
|
17
|
+
<a href="#-工作原理与双通道--双协议架构流向">🔄 架构图解</a> ·
|
|
18
|
+
<a href="#-argon-inspector-检视器模态用量账本与成本估算">📊 Inspector 检视器</a> ·
|
|
19
|
+
<a href="#-安装方法">🚀 快速安装</a> ·
|
|
20
|
+
<a href="#-双通道凭据配置">🔑 凭据配置</a> ·
|
|
21
|
+
<a href="#️-设置页面与完整配置项参考">⚙️ 配置参考</a>
|
|
10
22
|
</p>
|
|
11
23
|
</div>
|
|
12
24
|
|
|
13
25
|
---
|
|
14
26
|
|
|
15
|
-
`dsh-vertex-argon` 为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH)
|
|
27
|
+
`dsh-vertex-argon` 为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH) 提供生产级的 **Gemini 4 Argon** 双通道接入支持。插件同时打通 **Google Vertex AI**(ADC 服务账号 / Express API Key)与 **Google Gemini Developer API**(AI Studio API Key),完整支持 **`GenerateContent` (`v1beta1` / `v1`) 多跳长解码续传**与 **`Interactions` (`v1beta`) 持久化后台恢复**双协议,配备显式服务层级路由(`Standard` / `Flex` / `Priority`)、仅签名空 `Part` 无损回放、模态级 Token 账本、公开价格成本估算、**Argon Inspector 全景检视台**以及只读 Agent 诊断工具 `argon_inspect`。
|
|
16
28
|
|
|
17
|
-
Current release: **[1.
|
|
29
|
+
Current release: **[1.5.0](https://github.com/higekibaka/dsh-vertex-argon)** · [npm](https://www.npmjs.com/package/dsh-vertex-argon) · [CHANGELOG](./CHANGELOG.md)
|
|
18
30
|
|
|
19
31
|
---
|
|
20
32
|
|
|
21
33
|
## ✨ 为什么需要这个插件?
|
|
22
34
|
|
|
23
|
-
| 能力维度 | DSH 内置 `google` / `google-vertex`
|
|
35
|
+
| 能力维度 | DSH 内置 `google` / `google-vertex` 默认适配器 | `dsh-vertex-argon` (v1.5.0) |
|
|
24
36
|
|---|---|---|
|
|
25
|
-
| **思考控制参数** |
|
|
26
|
-
|
|
|
27
|
-
|
|
|
28
|
-
| **
|
|
29
|
-
|
|
|
30
|
-
|
|
|
37
|
+
| **思考控制参数** | 误传 `thinkingBudget: -1` 触发云端 `HTTP 400`,或传入超限档位 `max` 报错 | 原生映射 `thinkingLevel: "LOW" \| "MEDIUM" \| "HIGH"`,自动将 `max` 收敛为 `high`,剔除无效采样参数 |
|
|
38
|
+
| **思维链与空块签名回放** | 容易丢失不带文本的独立 `thoughtSignature` `Part`,影响长链路多轮推理与工具续答 | 固定开启 `includeThoughts: true`,通过 `google-signatures.js` 无损编码并原样回放仅含签名的空 `Part` |
|
|
39
|
+
| **GenerateContent 超长解码** | 单次锁死 64K,遇 `CONTINUATION` 直接截断结束;无流内错误帧识别 | 自动切换 `v1beta1` 执行 `continuationToken` 多跳续写(最高 `1,048,576`预算 / 最多 32 跳)、检查点指数退避重连与 HTTP 200 SSE 内联 `{ error }` 拦截 |
|
|
40
|
+
| **Interactions 协议与后台恢复** | 不支持 `Interactions` 协议及后台持久化执行 | 原生支持 `Interactions` (`v1beta`)、`creating` 预写防重发锁、以及基于 `last_event_id` 游标的流式断点续读 |
|
|
41
|
+
| **服务层级与 PayGo 控制** | 仅默认标准队列,无层级路由与响应账单核验 | 支持按通道显式指定 `standard` / `flex` / `priority` 及 Vertex `PayGo-Only` 共享池请求头,未验证组合发包前 Fail-Closed 拦截 |
|
|
42
|
+
| **可观测性、用量与成本估算** | 仅展示粗粒度总 Token,多跳长解码易虚报上下文水位触发误压缩 | **水位线 Token 与累计计费 Token 双轨分离** + 模态级(文本/图像/音频/视频/文档)拆解 + 公开价格非账单 USD 估算 + **Argon Inspector** 检视台与 `argon_inspect` 工具 |
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## 🧪 真实超长解码实测基准:奥德赛七号全年 365 天舰长日志
|
|
47
|
+
|
|
48
|
+
`dsh-vertex-argon` v1.5.0 的 `GenerateContent` 多跳长解码引擎已在真实高密度长文本与状态保持压力测试(**Temporal LongGenBench — 奥德赛七号全年 365 天舰长日志**)中完成实测验证:
|
|
49
|
+
|
|
50
|
+
- **测试任务约束**:在**单次模型回复回合**内,严禁跳日、严禁摘要省略,连续输出深空科考船「奥德赛七号」从 `[DAY 001 | 2186-01-01]` 至 `[DAY 365 | 2186-12-31]` 全部 **365 篇**每日日志(每天 180–250 中文字),并全程维持:
|
|
51
|
+
1. **每日递归状态台账**:每天首行精确计算并输出 `[燃料: XX.XX% | 氧气: XX.XX% | 船体: XX.XX% | 船员: X/6 | 距地: X.XXXX光年]`(初始值:燃料 `100.00%`、氧气 `100.00%`、船体 `100.00%`、船员 `6/6`、距地 `0.0000光年`;日常基础消耗:燃料 `-0.20%/天`,距地 `+0.0120光年/天`)。
|
|
52
|
+
2. **双周期强制不变式**:
|
|
53
|
+
- **`PI-1`(每逢第 7 的倍数天:`DAY 007, 014, ..., 364`)**:人工清理聚变偏滤器,当日燃料消耗翻倍为 `-0.40%`。
|
|
54
|
+
- **`PI-2`(每个公历自然月最后一天:`01-31`, `02-28`, ..., `12-31`)**:船载 AI「赫尔墨斯」输出当月航行数据汇总与船员心理健康评级(`A`–`D` 级)。
|
|
55
|
+
3. **四处单点长程锚定事件**:
|
|
56
|
+
- **`DAY 100 (2186-04-10)`**:捕获冰彗星提炼重水,当日结算后燃料一次性 `+12.50%`(封顶 `100.00%`)。
|
|
57
|
+
- **`DAY 200 (2186-07-19)` – `DAY 215 (2186-08-03)`**:绿藻生态舱基因突变,`DAY 200` 氧气骤降 `-8.00%`,`DAY 201–214` 每天额外泄漏 `-0.50%`,直至 `DAY 215` 彻底修复并将氧气恢复锁定在 `95.00%`。
|
|
58
|
+
- **`DAY 300 (2186-10-27)`**:接收到半人马座方向无法解释的质数矩阵引力波信号并召开全员听证会。
|
|
59
|
+
- **`DAY 365 (2186-12-31)`**:抵达奥尔特云边界星门中继站,完成全年航行与台账终审。
|
|
60
|
+
|
|
61
|
+
### 实测诊断账本数据(Diagnostic ID: `f911d0c5-fe7a-43ca-b205-5d2202105a41`)
|
|
62
|
+
|
|
63
|
+
| 指标维度 | 实测记录值 |
|
|
64
|
+
|---|---|
|
|
65
|
+
| **通道 / 模型 / 协议** | `google-vertex` / `gemini-4-argon` / `generate-content` (`v1beta1`, `regionClass: "global"`) |
|
|
66
|
+
| **思考档位 / 配置预算** | `LOW` / `configuredMaxTokens: 131,072` (`longDecodeEnabled: true`) |
|
|
67
|
+
| **服务层级(请求 vs 实测回执)** | `requested: "priority"` → `observed: "standard"` (`source: "traffic-type"`) |
|
|
68
|
+
| **单回合总输出 Token** | **98,985 tokens**(单次逻辑回合无缝跨越 65,536 单跳硬上限) |
|
|
69
|
+
| **第 1 跳(Initial Hop)** | `HTTP 200` · 耗时 `961,781 ms` (~16.0 分钟) · `1,291` 个 SSE 块 · 输入 `52,737` tokens · 输出满额 **`65,536` tokens** · `finishReason: "CONTINUATION"` |
|
|
70
|
+
| **第 2 跳(Continuation Hop)** | `HTTP 200` · 自动携带 `continuationToken` 续写 · 耗时 `476,132 ms` (~7.9 分钟) · 输入 `118,274` tokens · 输出 **`33,449` tokens** · `finishReason: "STOP"` |
|
|
71
|
+
| **总耗时与流稳定性** | **1,437,917 ms(约 23 分 58 秒)** · `hopCount: 2` · `continuationCount: 1` · `reconnectCount: 0` · `outcome: "done"` |
|
|
72
|
+
| **双轨 Token 计量** | 上报宿主上下文水位 `reportedInputTokens: 52,737` · 多跳累计计费输入 `billedPromptTokens: 171,011` · 累计总计费 `billedTotalTokens: 269,996` |
|
|
73
|
+
|
|
74
|
+
> **实测结论**:在近 **9.9 万 Output Tokens** 的单回合连续生成中,`GenerateContent` 多跳续传引擎在 65,536 token 边界处零丢字无缝衔接,从 `DAY 001` 到 `DAY 365` 全年日志完整闭环,所有周期性偏滤器双倍燃耗、月末赫尔墨斯评级与四处单点灾变/补给锚点全部严格命中。
|
|
31
75
|
|
|
32
76
|
---
|
|
33
77
|
|
|
34
|
-
## 🔄
|
|
78
|
+
## 🔄 工作原理与双通道 · 双协议架构流向
|
|
35
79
|
|
|
36
80
|
```mermaid
|
|
37
81
|
flowchart TD
|
|
38
|
-
U["DSH
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
82
|
+
U["DSH 会话请求 / 模型选择器"] --> R{"路由与凭据解析<br/>credentials → launchEnvironment → process.env"}
|
|
83
|
+
R -->|"gemini-4-argon (Vertex AI)"| V["google-vertex<br/>ADC 服务账号 或 Express API Key"]
|
|
84
|
+
R -->|"gemini-4-argon-google (Gemini API)"| G["google-generative-ai<br/>GOOGLE_API_KEY / GEMINI_API_KEY"]
|
|
85
|
+
|
|
86
|
+
V --> S["service-level.js 能力矩阵校验<br/>Standard / Flex / Priority & Vertex PayGo"]
|
|
87
|
+
G --> S
|
|
88
|
+
|
|
89
|
+
S --> P{"按通道选择的协议引擎"}
|
|
90
|
+
P -->|"generate-content (默认)"| GC["GenerateContent 引擎 (v1beta1 / v1)<br/>• continuationToken 多跳续传 (最高 32 跳)<br/>• 检查点指数退避重连 & 内联 { error } 拦截<br/>• google-signatures.js 空块签名无损回放"]
|
|
91
|
+
P -->|"interactions"| IA["Interactions 引擎 (v1beta)<br/>• 前台 SSE 流式 或 后台持久化执行<br/>• creating 预写锁防止断网重复创建计费<br/>• last_event_id 游标流式断点续读"]
|
|
92
|
+
|
|
93
|
+
GC --> D["诊断、关联与公开价格估算中心<br/>• request-association.js 绑定精确 messageId<br/>• usage-details.js 模态拆解 & 水位/计费双轨计量<br/>• pricing.js 公开价格表非账单 USD 估算<br/>• response-store.js 可选脱敏原始响应帧"]
|
|
94
|
+
IA --> D
|
|
95
|
+
|
|
96
|
+
D --> UI["Argon Inspector 检视台 & argon_inspect 工具<br/>右侧栏 · 对话主视图 · 单条回复图标 · 只读云端 ID 查询"]
|
|
48
97
|
```
|
|
49
98
|
|
|
50
|
-
|
|
99
|
+
---
|
|
100
|
+
|
|
101
|
+
## 📊 Argon Inspector 检视器、模态用量账本与成本估算
|
|
102
|
+
|
|
103
|
+
v1.5.0 内置完整的 **Argon Inspector** 可观测套件,前后端共享同一套宿主服务(`inspector-service.js`):
|
|
104
|
+
|
|
105
|
+
### 1. 三大图形化入口与范围联动
|
|
106
|
+
- **右侧边栏(Right Sidebar → `Argon`)**:在当前对话旁实时检视请求时间线与单次回复详情。
|
|
107
|
+
- **对话主视图标签页(Conversation View → `Argon Inspector`)**:提供宽屏双栏仪表盘视图。
|
|
108
|
+
- **单条回复顶部快捷图标(Message Header Argon Button)**:依托 `request-association.js` 对 `llm/stream`、`agent/assistant-stream` 与 `session/event` 的精确关联,点击任意 Argon 回复右上角的图标即可直接锁定该条回复(`Selected Answer` 范围)打开对应请求账本。
|
|
109
|
+
|
|
110
|
+
### 2. 固定范围概览(Current Scope Overview)与四维详情抽屉
|
|
111
|
+
- **三档范围切换**:支持 **`This Conversation`(当前会话)**、**`Selected Answer`(当前选中回复)** 与 **`All Recent`(全局最近 200 条记录)**。
|
|
112
|
+
- **顶部固定概览卡片**:实时聚合当前范围内的请求总数、完成状态分布、模态 Token 汇总(输入、缓存命中、输出、思考、工具)以及公开价格估算总计。
|
|
113
|
+
- **单请求四维明细**:
|
|
114
|
+
- **Overview**:通道、模型、协议、API 版本、区域分类(`global` / `non-global`)、请求与实测服务层级、关联 `messageId`。
|
|
115
|
+
- **Hops & Usage**:逐跳耗时、HTTP 状态、触发原因(`initial` / `continuation` / `checkpoint-reconnect`)、水位线 Token 与分模态(`TEXT` / `IMAGE` / `AUDIO` / `VIDEO` / `DOCUMENT`)账本。
|
|
116
|
+
- **Cost Estimate**:基于公开价格快照 `argon-public-2026-10-18` 的逐跳与汇总 USD 估算(明确标注非账单发票,区分促销期与 Vertex 非 `global` `1.1x` 系数)。
|
|
117
|
+
- **Raw Response**:当开启 `retainRawResponses` 时,支持按帧、按字符偏移分页查阅已脱敏的原始响应内容。
|
|
118
|
+
- **Operations 运维标签页**:
|
|
119
|
+
- **Cloud Interaction ID 只读查询**:输入任意已知的云端 Interaction ID 与通道,执行单次只读 `interactions.get(id)` 查询并分页检视返回内容(绝不恢复生成、不取消云端任务、不执行返回的工具调用)。
|
|
120
|
+
- **Background Recovery 锁管理**:查看当前持久化后台任务状态,并在出现未知创建中断(`creating`)时由用户确认后手动释放锁。
|
|
121
|
+
|
|
122
|
+
### 3. 只读 Agent 诊断工具 `argon_inspect`
|
|
123
|
+
插件向宿主注册延迟加载的并发安全只读工具 `argon_inspect`(`deferLoading: true`),供 Agent 在当前会话内自查诊断与成本:
|
|
124
|
+
|
|
125
|
+
| `action` | 作用说明 | 关键参数 |
|
|
126
|
+
|---|---|---|
|
|
127
|
+
| `overview` | 聚合当前会话(或指定 `messageId`)在保留窗口内的用量、成本与覆盖率概览 | `messageId?`, `limit?` (1–100) |
|
|
128
|
+
| `list` | 列出当前会话(或指定 `messageId`)的本地诊断请求摘要与 `requestId` | `messageId?`, `limit?` (1–50) |
|
|
129
|
+
| `detail` | 分页读取指定 `requestId` 的完整诊断记录、逐跳账本、模态用量与成本明细 | `requestId`, `offset?`, `limit?` (1–10) |
|
|
130
|
+
| `response` | 按字符偏移分页读取指定 `requestId` 已捕获的脱敏原始响应帧 | `requestId`, `index?`, `offset?`, `length?` |
|
|
131
|
+
| `query` | 使用当前配置凭据对已知 Cloud Interaction ID 执行单次只读 `GET` 查询 | `route`, `id` |
|
|
132
|
+
| `query-response` | 分页读取 `query` 返回的临时云端 Interaction 响应内容 | `queryId`, `offset?`, `length?` |
|
|
133
|
+
|
|
134
|
+
---
|
|
135
|
+
|
|
136
|
+
## 🎚️ 服务层级(Service Tiers)与 Vertex PayGo 能力矩阵
|
|
137
|
+
|
|
138
|
+
`service-level.js` 在发起任何网络请求前严格校验通道与协议组合能力;若配置了未验证组合,立即以 `ARGON_SERVICE_TIER_UNVERIFIED` 拒绝发包,**绝不静默降级或自动切换到更高单价层级**:
|
|
139
|
+
|
|
140
|
+
| 路由通道 | 协议引擎 | 支持的服务层级 (`Service Tier`) | 支持 `vertexPaygoOnly`? | 底层协议传递方式 |
|
|
141
|
+
|---|---|---|---|---|
|
|
142
|
+
| `google-generative-ai` | `generate-content` | `standard` · `flex` · `priority` | 不适用(自动忽略) | 请求体 `serviceTier` 字段 |
|
|
143
|
+
| `google-generative-ai` | `interactions` | `standard` · `flex` · `priority` | 不适用(自动忽略) | 请求体 `service_tier` 字段 |
|
|
144
|
+
| `google-vertex` | `generate-content` | `standard` · `priority` | **支持**(注入 `X-Vertex-AI-LLM-Request-Type: shared`) | 请求头 `X-Vertex-AI-LLM-Shared-Request-Type: priority` |
|
|
145
|
+
| `google-vertex` | `interactions` | 仅 `standard` | **不支持**(发包前 Fail-Closed 拒绝) | 默认标准队列 |
|
|
51
146
|
|
|
52
147
|
---
|
|
53
148
|
|
|
@@ -67,105 +162,110 @@ flowchart TD
|
|
|
67
162
|
### 方式 2:使用 DSH CLI 安装
|
|
68
163
|
|
|
69
164
|
```sh
|
|
165
|
+
dsh plugin --profile desktop add dsh-vertex-argon
|
|
166
|
+
# 或针对 Web profile:
|
|
70
167
|
dsh plugin --profile web add dsh-vertex-argon
|
|
71
168
|
```
|
|
72
169
|
|
|
73
170
|
---
|
|
74
171
|
|
|
75
|
-
## 🔑
|
|
172
|
+
## 🔑 双通道凭据配置
|
|
76
173
|
|
|
77
|
-
|
|
174
|
+
插件严格按照 **DSH 凭据存储(`credentials`) → 启动环境(`launchEnvironment`) → 进程环境变量(`process.env`)** 的顺序解析凭据。若 DSH 凭据存储服务自身抛出异常,插件立即 Fail-Closed 报错终止,绝不静默回退到环境变量中的旧密钥。
|
|
78
175
|
|
|
79
|
-
|
|
80
|
-
2. 在系统用户环境变量中设置以下 3 项(Windows 打开「编辑账户的环境变量 → 用户变量」新建,**变量值不要加引号**):
|
|
176
|
+
### 通道 A:Google Vertex AI(对应模型 `gemini-4-argon`)
|
|
81
177
|
|
|
82
|
-
|
|
83
|
-
|---|---|---|
|
|
84
|
-
| `GOOGLE_APPLICATION_CREDENTIALS` | `C:\Keys\vertex-sa.json` | 服务账号 JSON 密钥文件的完整本地路径 |
|
|
85
|
-
| `GOOGLE_CLOUD_PROJECT` | `my-gcp-project-id` | Google Cloud **项目 ID**(注意不是项目名称) |
|
|
86
|
-
| `GOOGLE_CLOUD_LOCATION` | `global` | 调用区域,推荐 `global`(或 `us` / `eu`) |
|
|
178
|
+
支持 **标准 ADC 服务账号模式** 与 **Express API Key 模式**:
|
|
87
179
|
|
|
88
|
-
|
|
89
|
-
|
|
180
|
+
1. **标准 ADC 服务账号模式**(同时提供 Project 与 Location 时启用):
|
|
181
|
+
| 变量 / 凭据名 | 填写示例 | 说明 |
|
|
182
|
+
|---|---|---|
|
|
183
|
+
| `GOOGLE_APPLICATION_CREDENTIALS` | `C:\Keys\vertex-sa.json` | 服务账号 JSON 密钥文件绝对路径(具备 `roles/aiplatform.user` 权限) |
|
|
184
|
+
| `GOOGLE_CLOUD_PROJECT` | `my-gcp-project-id` | Google Cloud **项目 ID**(支持别名 `GCLOUD_PROJECT`) |
|
|
185
|
+
| `GOOGLE_CLOUD_LOCATION` | `global` | 调用区域,默认并推荐 `global`(非 `global` 区域公开定价有 `1.1x` 溢价) |
|
|
186
|
+
2. **Vertex Express API Key 模式**(未配置 Project/Location 时启用):
|
|
187
|
+
- 配置 `GOOGLE_CLOUD_API_KEY` 即可通过 Vertex Express 端点直接调用。
|
|
90
188
|
|
|
91
|
-
### 通道 B:Google Gemini
|
|
189
|
+
### 通道 B:Google Gemini Developer API(对应模型 `gemini-4-argon-google`)
|
|
92
190
|
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
3. 插件会自动检测到该配置,并在模型选择器的 **`Vertex Argon`** 分组下多显示一项 **`Gemini 4 Argon (Gemini API)`**,点击即可直接调用。
|
|
191
|
+
- 在 DSH **设置 → 凭据** 或环境变量中配置 `GOOGLE_API_KEY`(或 `GEMINI_API_KEY`)。
|
|
192
|
+
- 插件会自动检测可用凭据并在模型选择器的 **`Vertex Argon`** 分组下展示对应通道模型。
|
|
96
193
|
|
|
97
194
|
---
|
|
98
195
|
|
|
99
|
-
## ⚙️
|
|
100
|
-
|
|
101
|
-
打开左下角 **设置 → Vertex Argon
|
|
102
|
-
|
|
103
|
-
| 配置字段 | 默认值 |
|
|
104
|
-
|
|
105
|
-
|
|
|
106
|
-
| `reasoning` | `medium` | `low
|
|
107
|
-
| `
|
|
108
|
-
| `
|
|
109
|
-
| `
|
|
196
|
+
## ⚙️ 设置页面与完整配置项参考
|
|
197
|
+
|
|
198
|
+
打开左下角 **设置 → Vertex Argon**,所有配置项均支持实时热更新(`volatile`),分为四大功能组共 **13 项配置**:
|
|
199
|
+
|
|
200
|
+
| 分组 | 配置字段 | 默认值 | 可选值 / 范围 | 说明 |
|
|
201
|
+
|---|---|---|---|---|
|
|
202
|
+
| **基础与生成** | `showInModelPicker` | `true` | `boolean` | 是否在会话模型选择器中展示 `Vertex Argon` 模型 |
|
|
203
|
+
| | `reasoning` | `"medium"` | `"low" \| "medium" \| "high"` | 默认思考档位(当收到宿主 `max` 请求时自动收敛为 `high`) |
|
|
204
|
+
| | `maxTokens` | `65536` | `1` – `1048576` | 单回合最大输出 Token 预算(超过 `65,536` 时须在 `generate-content` 下开启 `longDecode`) |
|
|
205
|
+
| | `contextWindow` | `1048576` | `1` – `1048576` | 模型总上下文窗口大小(默认 1M tokens) |
|
|
206
|
+
| | `longDecode` | `true` | `boolean` | 启用 `GenerateContent` `v1beta1` 跨 64K 多跳自动续传与断流检查点恢复 |
|
|
207
|
+
| **协议与服务层级** | `googleProtocol` | `"generate-content"` | `"generate-content" \| "interactions"` | Gemini Developer API (`gemini-4-argon-google`) 使用的底层协议 |
|
|
208
|
+
| | `vertexProtocol` | `"generate-content"` | `"generate-content" \| "interactions"` | Vertex AI (`gemini-4-argon`) 使用的底层协议 |
|
|
209
|
+
| | `googleServiceTier` | `"standard"` | `"standard" \| "flex" \| "priority"` | Gemini Developer API 请求的服务层级 |
|
|
210
|
+
| | `vertexServiceTier` | `"standard"` | `"standard" \| "flex" \| "priority"` | Vertex AI 请求的服务层级(注:Vertex 仅验证 `standard` 与 `generate-content` 下的 `priority`) |
|
|
211
|
+
| | `vertexPaygoOnly` | `false` | `boolean` | Vertex `generate-content` 请求固定附带 `X-Vertex-AI-LLM-Request-Type: shared` |
|
|
212
|
+
| **Interactions 后台模式** | `interactionsBackground` | `false` | `boolean` | 在 `interactions` 协议下启用云端持久化后台执行(须同时开启 `allowInteractionStorage`) |
|
|
213
|
+
| | `allowInteractionStorage` | `false` | `boolean` | 允许向 `interactions` 请求发送 `store: true` 以支持断线恢复与 ID 查询 |
|
|
214
|
+
| **诊断与高级** | `retainRawResponses` | `false` | `boolean` | 显式开启后,在本地 `vertex_argon_responses` 存储域保留最近 50 条脱敏原始响应帧(关闭时立即清空) |
|
|
110
215
|
|
|
111
216
|
---
|
|
112
217
|
|
|
113
|
-
##
|
|
114
|
-
|
|
115
|
-
在 `billion-context`(`0.1.196` / `0.1.197`)下启用 Google 通道代理时,存在两个属于代理侧处理链路的已知兼容性问题(均已向上游提交 Issue 并有对应修复 PR 跟进):
|
|
116
|
-
|
|
117
|
-
### 1. Vertex AI 工具续答 `HTTP 400`(`user.parts` 顺序校验)
|
|
118
|
-
|
|
119
|
-
工具执行完毕后,若 `billion-context` 向最后一条 `user` 消息追加压缩提醒(nudge),会形成 `[functionResponse, text]` 的数组顺序,触发 Vertex AI 报错:
|
|
120
|
-
|
|
121
|
-
> `HTTP 400: Requests ending with a model turn are not supported.`
|
|
218
|
+
## 🗂️ 架构模块图谱与持久化存储域
|
|
122
219
|
|
|
123
|
-
|
|
124
|
-
- **端点对照**:
|
|
220
|
+
项目根目录包含 **27 个正式生产 JS 模块**,职责边界清晰,零冗余依赖:
|
|
125
221
|
|
|
126
|
-
|
|
|
222
|
+
| 模块分类 | 核心文件 | 职责说明 |
|
|
127
223
|
|---|---|---|
|
|
128
|
-
|
|
|
129
|
-
| `
|
|
130
|
-
|
|
|
224
|
+
| **插件入口与运行时** | `index.js`, `client.js`, `runtime.js` | Host 插件入口、Web 设置页与 Inspector UI 入口、宿主 Peer 依赖解析桥 |
|
|
225
|
+
| **适配器、连接与服务层级** | `adapter.js`, `google-connection.js`, `service-level.js` | 双通道适配器、SDK 与自定义 SSE 传输层构建、服务层级与 PayGo 校验矩阵 |
|
|
226
|
+
| **GenerateContent 与签名引擎** | `generate-content.js`, `google-signatures.js` | 多跳 `continuationToken` 续传、检查点退避重连、SSE 内联错误拦截、空 `Part` 签名回放 |
|
|
227
|
+
| **Interactions 与后台恢复引擎** | `interactions.js`, `interaction-adapter.js`, `interactions-input.js`, `interaction-image.js`, `interaction-transport.js`, `interaction-state.js`, `interaction-lifecycle.js`, `interaction-query.js` | `Interactions` 流式状态机、请求与多模态图片转换、`creating` 预写锁、`last_event_id` 游标续读、只读云端 ID 查询 |
|
|
228
|
+
| **结构化输出底层辅助** | `structured-output.js`, `bounded-json.js` | 基于 `ajv/dist/2020.js` 的严格 JSON Schema 校验、深度/字节边界守卫与双协议格式转换 |
|
|
229
|
+
| **诊断、定价与 Inspector** | `diagnostics.js`, `diagnostic-store.js`, `usage-details.js`, `pricing.js`, `response-store.js`, `request-association.js`, `inspector-service.js`, `inspector-overview.js`, `inspector-tool.js` | 双轨 Token 诊断追踪、模态拆解、公开价格 USD 估算、请求-消息精确绑定、Inspector 宿主服务与 `argon_inspect` 工具 |
|
|
230
|
+
|
|
231
|
+
### 本地持久化存储域(Storage Domains)
|
|
232
|
+
- `vertex_argon_diagnostics`:保存最近 **200 条**结构化请求诊断记录(自动脱敏,不含正文或密钥)。
|
|
233
|
+
- `vertex_argon_responses`:仅当 `retainRawResponses: true` 时保存最近 **50 条**脱敏原始响应帧(单帧上限 256 KB,关闭开关即刻清空)。
|
|
234
|
+
- `vertex_argon_interactions`:保存后台 `Interactions` 任务的创建锁与 `last_event_id` 恢复游标。
|
|
131
235
|
|
|
132
|
-
|
|
133
|
-
|
|
236
|
+
---
|
|
237
|
+
|
|
238
|
+
## 🧪 离线零网络测试套件
|
|
134
239
|
|
|
135
|
-
|
|
240
|
+
仓库内置 **36 个自动化测试文件**(`test/*.test.mjs`),全部在 `test/offline-guard.mjs` 零外网守卫下运行(拦截一切非回环 `fetch` / `http` / `https` / `http2` / `net` / `tls` / `dns` 调用,确保测试零网络、零产生云端费用):
|
|
136
241
|
|
|
137
|
-
|
|
242
|
+
```bash
|
|
243
|
+
DSH_TEST_HOST_ROOT=/path/to/deepseek-harness \
|
|
244
|
+
node --experimental-transform-types \
|
|
245
|
+
--import ./test/offline-guard.mjs \
|
|
246
|
+
--import ./test/host-loader.mjs \
|
|
247
|
+
--test test/*.test.mjs
|
|
248
|
+
```
|
|
138
249
|
|
|
139
|
-
|
|
140
|
-
- **工具调用签名(必需)**:绑定在 `functionCall` 上的签名若缺失会导致下一轮请求直接报 `400`;该类签名在正常工具调用中可随工具块保留。
|
|
141
|
-
- **独立输出签名(非严格校验)**:根据 [Google 官方文档](https://ai.google.dev/gemini-api/docs/generate-content/thought-signatures),非 `functionCall` 的独立签名用于跨轮次延续推理状态,缺失不会触发服务端 `400` 报错,但可能对长链路推理连贯性产生潜在影响。
|
|
142
|
-
- 上游跟踪:[Issue #3158](https://github.com/ranxianglei/billion-context/issues/3158) · [PR #3162](https://github.com/ranxianglei/billion-context/pull/3162)
|
|
250
|
+
---
|
|
143
251
|
|
|
144
|
-
|
|
252
|
+
## ⚠️ 与 `billion-context` 配合使用的兼容性说明
|
|
145
253
|
|
|
146
|
-
|
|
254
|
+
在旧版 `billion-context` 代理环境下启用 Google 通道时,若遇到代理注入压缩提醒导致的 `user.parts` 顺序校验报错([Issue #3159](https://github.com/ranxianglei/billion-context/issues/3159) / [PR #3167](https://github.com/ranxianglei/billion-context/pull/3167))或流式独立签名过滤问题([Issue #3158](https://github.com/ranxianglei/billion-context/issues/3158) / [PR #3162](https://github.com/ranxianglei/billion-context/pull/3162)),可在 `billion-context` 配置中对目标上游域名开启透传:
|
|
147
255
|
|
|
148
256
|
```json
|
|
149
257
|
{
|
|
150
258
|
"providers": {
|
|
151
|
-
"https://aiplatform.googleapis.com": { "passthrough": true }
|
|
259
|
+
"https://aiplatform.googleapis.com": { "passthrough": true },
|
|
260
|
+
"https://generativelanguage.googleapis.com": { "passthrough": true }
|
|
152
261
|
}
|
|
153
262
|
}
|
|
154
263
|
```
|
|
155
264
|
|
|
156
|
-
> **提示**:若使用区域级 Vertex 端点(如 `https://us-central1-aiplatform.googleapis.com`)或 Gemini Developer API(`https://generativelanguage.googleapis.com`),请按实际请求的域名填写。仅关闭 `compress.injectNudge` 无法规避独立签名片段丢失;设置 `passthrough: true` 后该路由将直接透传,不再执行 `billion-context` 上下文压缩。
|
|
157
|
-
|
|
158
|
-
---
|
|
159
|
-
|
|
160
|
-
## ❓ 常见问题
|
|
161
|
-
|
|
162
|
-
- **为什么极简问题有时候不显示思维链文本?**
|
|
163
|
-
插件已固定发送 `includeThoughts: true`,但 Google 云端会根据问题复杂度动态决定是否吐出可读摘要:遇到推理或工具调用任务时会返回思考摘要文本,极简问答可能仅返回 `thoughtSignature` 签名而不产出摘要文本,属官方正常机制。
|
|
164
|
-
- **Gemini 网页版订阅(Gemini Advanced)包含这里的费用吗?**
|
|
165
|
-
不包含。无论是 Vertex AI 还是 Gemini Developer API,均按对应平台的 API 用量计费。
|
|
166
|
-
|
|
167
265
|
---
|
|
168
266
|
|
|
169
267
|
## 📄 License
|
|
170
268
|
|
|
171
269
|
[MIT](./LICENSE) © [hgk](https://github.com/higekibaka)
|
|
270
|
+
|
|
271
|
+
[](https://github.com/deepseek-ai/deepseek-harness)
|