dsh-vertex-argon 1.3.0 → 1.5.1

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 ADDED
@@ -0,0 +1,69 @@
1
+ # Changelog
2
+
3
+ All notable changes to `dsh-vertex-argon` are documented in this file.
4
+
5
+ ## [1.5.1] - 2026-10-19
6
+
7
+ ### Changed
8
+ - **Performance Optimization (`client.js`, `diagnostic-store.js`, `interaction-state.js`, `response-store.js`)**:
9
+ - Replaced the remaining 5 ISO 8601 timestamp `String.prototype.localeCompare()` sorts with direct lexicographical relational operators (`<` / `>`) across recovery lists, recent diagnostics, background task eviction, and raw response retention trimming.
10
+ - Reused precomputed `sumParts` when available in `extractTokenMix` (`client.js`) to avoid redundant segment filtering and reduction.
11
+
12
+ ## [1.5.0] - 2026-10-18
13
+
14
+ ### Added
15
+ - **Argon Inspector Dashboard (Right-Sidebar, Conversation Tab & Per-Message Shortcut)**:
16
+ - 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.
17
+ - 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`.
18
+ - 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.
19
+ - **Per-Modality Usage Ledger & Public Cost Estimator (`usage-details.js`, `pricing.js`)**:
20
+ - 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.
21
+ - Added public token price snapshot (`argon-public-2026-10-18`) and USD cost estimation clearly labeled as non-invoice estimates.
22
+ - **Explicit Service Tiers & Vertex PayGo Routing (`service-level.js`)**:
23
+ - 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.
24
+ - **Opt-In Raw Response Store & Cloud Interaction ID Lookup (`response-store.js`, `interaction-query.js`)**:
25
+ - Added `retainRawResponses` setting and bounded `vertex_argon_responses` storage domain with header/secret sanitization and paged character reading.
26
+ - 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.
27
+ - **Deferred Read-Only Agent Tool `argon_inspect` (`inspector-tool.js`)**:
28
+ - Registered `argon_inspect` (`deferLoading: true`) supporting `overview`, `list`, `detail`, `response`, `query`, and `query-response` actions within the current session scope.
29
+ - **Signature-Only `Part` Lossless Replay (`google-signatures.js`)**:
30
+ - Preserved opaque `thoughtSignature` / `thought_signature` fields on empty-content `Part` objects across `GenerateContent` and `Interactions` multi-turn replay and tool-call round-trips.
31
+
32
+ ### Changed & Fixed
33
+ - **In-Band SSE Error Handling (`generate-content.js`)**:
34
+ - 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.
35
+ - **Live Long Decode Verification (Odyssey-VII 365-Day Captain's Log Benchmark)**:
36
+ - 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`.
37
+ - **Pre-Release Codebase & Package Cleanup**:
38
+ - 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.
39
+ - Regenerated `README.md` and `docs/implementation/` directly from the verified 1.5.0 codebase.
40
+
41
+ ## [1.4.3] - 2026-10-18
42
+
43
+ ### Fixed
44
+ - **Interactions Resumable Read Stream (`interactions.js`, `interaction-transport.js`)**:
45
+ - 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.
46
+
47
+ ## [1.4.2] - 2026-10-17
48
+
49
+ ### Fixed
50
+ - **Interactions Pre-Dispatch Intent & Unknown-Create Lock (`interaction-state.js`, `interactions.js`)**:
51
+ - Recorded `phase: "creating"` before sending `interactions.create` and blocked automatic duplicate resubmission after an interrupted create request until explicitly released by the user.
52
+
53
+ ## [1.4.1] - 2026-10-17
54
+
55
+ ### Fixed
56
+ - **Credential Store Fail-Closed Boundary (`adapter.js`)**:
57
+ - Ensured errors thrown by the DSH `credentials` service abort request preparation immediately rather than falling back to ambient environment variables.
58
+
59
+ ## [1.4.0] - 2026-10-16
60
+
61
+ ### Added
62
+ - **Dual-Protocol Architecture (`generate-content` & `interactions`)**:
63
+ - Added full `Interactions` (`v1beta`) SSE & durable background task support alongside `GenerateContent` Long Decode (`v1beta1` / `v1`).
64
+ - Added `vertex_argon_diagnostics` and `vertex_argon_interactions` storage domains and dedicated Settings UI.
65
+
66
+ ## [1.3.0] - 2026-10-15
67
+
68
+ ### Added
69
+ - 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="76" height="76" alt="Vertex Argon Icon" />
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 &amp; Gemini API Dual-Route Gemini 4 Argon Plugin for <a href="https://github.com/deepseek-ai/deepseek-harness">DeepSeek Harness</a> (DSH)</strong></p>
4
+ <p><strong>Google Vertex AI &amp; 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.1.7--rc.2%20%7C%200.2.0--rc.2-4f46e5?style=flat-square" alt="DSH compatibility" /></a>
8
- <a href="https://docs.cloud.google.com/gemini-enterprise-agent-platform/models/gemini/4-argon"><img src="https://img.shields.io/badge/Thinking%20Levels-LOW%20%7C%20MEDIUM%20%7C%20HIGH-0ea5e9?style=flat-square" alt="Thinking Levels" /></a>
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) 提供完整的 **Gemini 4 Argon** 接入支持,自动聚合 **Google Vertex AI**(服务账号 / ADC)与 **Google Gemini Developer API**(AI Studio API Key)双通道,修复内置 `pi-ai` 适配器误传 `thinkingBudget` 导致的 `HTTP 400` 报错,完整打通原生三档思考、思维链(Thought Summaries)、`v1beta1` **Long Decode 跨段长生成自动续传**与带签名的多轮工具调用。
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.3.0](https://github.com/higekibaka/dsh-vertex-argon)** · [npm](https://www.npmjs.com/package/dsh-vertex-argon)
29
+ Current release: **[1.5.1](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` 旧适配器 | `dsh-vertex-argon` 插件通道 |
35
+ | 能力维度 | DSH 内置 `google` / `google-vertex` 默认适配器 | `dsh-vertex-argon` (v1.5.1) |
24
36
  |---|---|---|
25
- | **思考控制参数** | 误判为旧模型并发送 `thinkingBudget: -1`,触发云端 `HTTP 400` | 原生发送 `thinkingLevel: "LOW" \| "MEDIUM" \| "HIGH"`,绝不传 `thinkingBudget` |
26
- | **思维链(思考摘要)** | 手动新增模型默认无 `reasoning` 标记,不请求摘要 | 固定开启 `includeThoughts: true`,流式解析 `thought: true` 实时展示思维链 |
27
- | **多轮工具调用回传** | 路由切换或签名不对齐时易丢失上下文 | 保持 `provider` / `model` 与 `thoughtSignature` 签名全链路一致 |
28
- | **Long Decode 长生成** | Vertex 硬编码 `v1` 且锁死 64K,遇 `CONTINUATION` 直接抛错断流 | 自动切换 `v1beta1` 跨 64K 分段零延迟续传(最高 512K)、断流检查点指数退避恢复,按首跳输入上报水位防误压缩 |
29
- | **采样参数净化** | 可能携带被 Argon 拒绝或忽略的采样字段 | 自动剥离 `temperature`、`topP`、`topK` 等无效采样参数 |
30
- | **通道管理与设置** | 需手改 `cordis.patch.yml` 并反复排查校验报错 | 自动检测双通道 + 内置 **设置 → Vertex Argon** 实时调节与「最近请求诊断摘要」折叠面板 |
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 模型配置扫描"] --> D{"自动检测 gemini-4-argon"}
39
- D -->|"检测到 google-vertex 或默认"| V["Vertex Argon → Gemini 4 Argon (Vertex AI)<br/>复用 GOOGLE_APPLICATION_CREDENTIALS"]
40
- D -->|"检测到 google (Gemini API)"| G["Vertex Argon → Gemini 4 Argon (Gemini API)<br/>复用 GOOGLE_API_KEY"]
41
- V --> P["onPayload 请求级净化与注入"]
42
- G --> P
43
- P --> T["注入 thinkingLevel: LOW / MEDIUM / HIGH 与 includeThoughts: true<br/>剔除 thinkingBudget 与 temperature / topP / topK"]
44
- T --> L["v1beta1 Long Decode 续传引擎<br/>自动处理 CONTINUATION 跨段续接、断流检查点恢复与首跳输入计量"]
45
- L --> S["Google GenAI Stream 响应"]
46
- S --> R1["thought: true → DSH 思维链面板"]
47
- S --> R2["functionCall + thoughtSignature → 原生工具卡片与多轮签名回放"]
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
- 除提供独立的 **Vertex Argon** 分组外,插件在启动时还会为内置 `PiAiAdapter` 注入 `installGemini4PiAiPatch` 运行时兜底——即便用户在模型选择器中误点了原 `Google` 或 `Google Vertex AI` 分组下的 `gemini-4-argon`,也会被自动改写为合法的 `thinkingLevel` 请求。
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,111 +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
- ### 通道 A:Google Vertex AI(服务账号 JSON / ADC)
174
+ 插件严格按照 **DSH 凭据存储(`credentials`) → 启动环境(`launchEnvironment`) → 进程环境变量(`process.env`)** 的顺序解析凭据。若 DSH 凭据存储服务自身抛出异常,插件立即 Fail-Closed 报错终止,绝不静默回退到环境变量中的旧密钥。
78
175
 
79
- 1. 在 [Google Cloud 控制台](https://console.cloud.google.com/) 确认项目已绑定结算账户、已启用 **Vertex AI API**(`aiplatform.googleapis.com`),并为服务账号授予 **Vertex AI User**(`roles/aiplatform.user`)角色,下载 JSON 密钥文件。
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
- 3. **完全退出 DSH(含右下角系统托盘图标)并重新启动**,使进程继承新的环境变量。
89
- 4. 在会话模型选择器中选择 **`Vertex Argon → Gemini 4 Argon (Vertex AI)`**。
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 API(AI Studio API Key)
189
+ ### 通道 B:Google Gemini Developer API(对应模型 `gemini-4-argon-google`)
92
190
 
93
- 1. 打开 DSH **设置 → 模型 → Google**,配置你的 `GOOGLE_API_KEY`。
94
- 2. 在 `Google` 提供商下添加模型 ID:`gemini-4-argon`。
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
- ## ⚙️ 设置页面与配置项(Configuration)
100
-
101
- 打开左下角 **设置 → Vertex Argon**,无需修改 YAML 或重启应用,即可实时调整以下配置(对应 `local-vertex-argon` Profile 条目):
102
-
103
- | 配置字段 | 默认值 | 可选范围 / 预设 | 说明 |
104
- |---|---|---|---|
105
- | `showInModelPicker` | `true` | `true` / `false` | 是否在会话模型选择器中显示 `Vertex Argon` 分组(隐藏不影响已打开会话) |
106
- | `reasoning` | `medium` | `low` / `medium` / `high` | 默认思考档位,分别映射为原生 `LOW` / `MEDIUM` / `HIGH` |
107
- | `longDecode` | `true` | `true` / `false` | 是否启用 `v1beta1` Long Decode 跨段自动续传(含断流检查点恢复与首跳输入防误压缩) |
108
- | `maxTokens` | `65536` | `1` – `524288` | 最大输出预算(默认 `65,536`;开启 `longDecode` 后最高可设为 `524,288` 跨 64K 分段续传) |
109
- | `contextWindow` | `1048576` | `1` – `1048576` | 输入、思考与输出共享的总上下文窗口(官方上限为 `1,048,576`) |
110
-
111
- ### 🩺 结构化请求诊断与「最近请求诊断摘要」面板(v1.3.0+)
112
-
113
- - **有界持久化存储(`vertex_argon_diagnostics`)**:通过宿主 `storageDomain` 自动在 `~/.dsh/storages/vertex_argon_diagnostics/requests/` 下记录最近 **200 条**请求元数据(单请求最多记录 16 跳,异步队列上限 32 条,严格脱敏,绝不保存对话正文、图片、`continuationToken` 明文或密钥)。
114
- - **逐跳与双轨 Token 追踪**:完整记录每次请求的通道(`google-vertex` / `google-generative-ai`)、API 版本(`v1beta1` / `v1`)、思考档位、每一跳的触发原因(`initial` / `continuation` / `checkpoint-reconnect` / `retry-same-checkpoint`)、退避等待耗时(`backoffDelayMs`)、底层传输错误码白名单(如 `ECONNRESET`、`ETIMEDOUT`)以及上报水位(首跳输入)与多跳累计计费 Token 对比。
115
- - **图形化折叠面板**:在 **设置 → Vertex Argon** 页面底部点击展开 **「最近请求诊断摘要」**,即可直接查看最近 20 次请求的耗时、跳数、断流自愈状态与逐跳明细。
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 条脱敏原始响应帧(关闭时立即清空) |
116
215
 
117
216
  ---
118
217
 
119
- ## ⚠️ 与 `billion-context` 配合使用的兼容性说明
120
-
121
- 在 `billion-context`(`0.1.196` / `0.1.197`)下启用 Google 通道代理时,存在两个属于代理侧处理链路的已知兼容性问题(均已向上游提交 Issue 并有对应修复 PR 跟进):
122
-
123
- ### 1. Vertex AI 工具续答 `HTTP 400`(`user.parts` 顺序校验)
124
-
125
- 工具执行完毕后,若 `billion-context` 向最后一条 `user` 消息追加压缩提醒(nudge),会形成 `[functionResponse, text]` 的数组顺序,触发 Vertex AI 报错:
218
+ ## 🗂️ 架构模块图谱与持久化存储域
126
219
 
127
- > `HTTP 400: Requests ending with a model turn are not supported.`
220
+ 项目根目录包含 **27 个正式生产 JS 模块**,职责边界清晰,零冗余依赖:
128
221
 
129
- - **根因说明**:报错文案具有一定误导性——实际请求仍以 `user` 角色结尾且工具结果完好,触发校验的真正原因是同一条 `user` 消息内的 **`parts` 排列顺序**(与 `dsh-vertex-argon` 的 `thinkingLevel` 或思考摘要配置无关)。
130
- - **端点对照**:
131
-
132
- | 最后一条 `user` 消息的 `parts` 顺序 | Google Vertex AI | Google Gemini Developer API |
222
+ | 模块分类 | 核心文件 | 职责说明 |
133
223
  |---|---|---|
134
- | `[functionResponse]`(无追加提醒) | `200 OK`,正常续答 | `200 OK`,正常续答 |
135
- | `[functionResponse, text]`(工具结果后追加提醒) | **`400 Bad Request`** | 未复现该顺序 `400` |
136
- | `[text, functionResponse]`(普通文本置于工具结果前) | `200 OK`,正常续答 | `200 OK`,正常续答 |
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` 恢复游标。
235
+
236
+ ---
137
237
 
138
- - **修复归属**:`dsh-vertex-argon` 的 `onPayload` 钩子运行在 `billion-context` 介入之前,无法在前置阶段调整代理后续注入的提醒顺序;该问题需由 `billion-context` 在 Google 请求转换与提醒注入阶段(`coreToGoogle` / `appendGoogleNudge`)统一处理。
139
- - 上游跟踪:[Issue #3159](https://github.com/ranxianglei/billion-context/issues/3159) · [PR #3167](https://github.com/ranxianglei/billion-context/pull/3167)
238
+ ## 🧪 离线零网络测试套件
140
239
 
141
- ### 2. 流式响应中独立 `thoughtSignature` 片段被过滤
240
+ 仓库内置 **36 个自动化测试文件**(`test/*.test.mjs`),全部在 `test/offline-guard.mjs` 零外网守卫下运行(拦截一切非回环 `fetch` / `http` / `https` / `http2` / `net` / `tls` / `dns` 调用,确保测试零网络、零产生云端费用):
142
241
 
143
- 在完整 `billion-context` 流式处理链路中,Vertex AI 与 Gemini Developer API 返回的思考摘要文本(`thought: true`)均可完整保留,但**不携带文本的独立 `{ thoughtSignature: "..." }` SSE 片段**会被当前的 [Google loop adapter](https://github.com/ranxianglei/billion-context/blob/master/src/loop/adapter-google.ts) 跳过。
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
+ ```
144
249
 
145
- - **实际影响边界**:
146
- - **工具调用签名(必需)**:绑定在 `functionCall` 上的签名若缺失会导致下一轮请求直接报 `400`;该类签名在正常工具调用中可随工具块保留。
147
- - **独立输出签名(非严格校验)**:根据 [Google 官方文档](https://ai.google.dev/gemini-api/docs/generate-content/thought-signatures),非 `functionCall` 的独立签名用于跨轮次延续推理状态,缺失不会触发服务端 `400` 报错,但可能对长链路推理连贯性产生潜在影响。
148
- - 上游跟踪:[Issue #3158](https://github.com/ranxianglei/billion-context/issues/3158) · [PR #3162](https://github.com/ranxianglei/billion-context/pull/3162)
250
+ ---
149
251
 
150
- ### 3. 上游修复合入前的临时规避方式
252
+ ## ⚠️ 与 `billion-context` 配合使用的兼容性说明
151
253
 
152
- 在等待上游合并发版期间,若需在开启 `billion-context` 的环境中稳定使用 Vertex AI,可在生效的 `billion-context` 配置中对目标上游设置路由级透传(仅跳过该路由的代理改写与压缩,不影响其他通道):
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` 配置中对目标上游域名开启透传:
153
255
 
154
256
  ```json
155
257
  {
156
258
  "providers": {
157
- "https://aiplatform.googleapis.com": { "passthrough": true }
259
+ "https://aiplatform.googleapis.com": { "passthrough": true },
260
+ "https://generativelanguage.googleapis.com": { "passthrough": true }
158
261
  }
159
262
  }
160
263
  ```
161
264
 
162
- > **提示**:若使用区域级 Vertex 端点(如 `https://us-central1-aiplatform.googleapis.com`)或 Gemini Developer API(`https://generativelanguage.googleapis.com`),请按实际请求的域名填写。仅关闭 `compress.injectNudge` 无法规避独立签名片段丢失;设置 `passthrough: true` 后该路由将直接透传,不再执行 `billion-context` 上下文压缩。
163
-
164
- ---
165
-
166
- ## ❓ 常见问题
167
-
168
- - **为什么极简问题有时候不显示思维链文本?**
169
- 插件已固定发送 `includeThoughts: true`,但 Google 云端会根据问题复杂度动态决定是否吐出可读摘要:遇到推理或工具调用任务时会返回思考摘要文本,极简问答可能仅返回 `thoughtSignature` 签名而不产出摘要文本,属官方正常机制。
170
- - **Gemini 网页版订阅(Gemini Advanced)包含这里的费用吗?**
171
- 不包含。无论是 Vertex AI 还是 Gemini Developer API,均按对应平台的 API 用量计费。
172
-
173
265
  ---
174
266
 
175
267
  ## 📄 License
176
268
 
177
269
  [MIT](./LICENSE) © [hgk](https://github.com/higekibaka)
270
+
271
+ [![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)