dsh-bundle-antigravity-host 0.1.25 → 0.1.26

package/README.md

@@ -10,7 +10,9 @@
 [![license](https://img.shields.io/badge/license-MIT-64748b)](LICENSE)
 [![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A522.19-64748b)](#兼容性与验证范围)
 
-[快速开始](#快速开始) · [功能亮点](#功能亮点) · [配置参考](docs/configuration.md) · [排障](docs/reference.md#排障) · [更新记录](docs/changelog.md)
+[快速开始](#快速开始) · [功能预览](#功能预览) · [功能亮点](#功能亮点) · [配置参考](docs/configuration.md) · [排障](docs/reference.md#排障) · [更新记录](docs/changelog.md)
+
+<img src="https://raw.githubusercontent.com/KouzakiUmi/dsh-antigravity-acp/main/assets/banner.svg" width="1200" alt="Antigravity ACP for DSH：官方 Antigravity agent 经 ACP 与私有 loopback 桥相连，工具调用交给 DSH 校验、审批与执行，结果回填 agent（示意图）">
 
 </div>
 
@@ -18,6 +20,8 @@
 
 > **0.1.25**：修复冷启动时登录 / 预热握手超时（新增 `handshakeTimeoutMs`，默认 120 秒），默认开启预热并显示启动进度。类型检查、**33 个文件 / 515 项测试**与构建通过；真实 Desktop GUI 与跨平台验收尚未完成。[查看本次更新与限制](docs/changelog.md#0125--2026-10-22)。上一版 0.1.24 的并发池、模型发现与图片输入见[更新记录](docs/changelog.md#0124--2026-10-22)。
 
+> **0.1.26 · 会话复用与生命周期修复**：会话增量一致性、上下文去重、取消排空、统一空闲回收及恢复映射 v2 已补齐；本地类型检查、**36 个文件 / 591 项测试**与构建通过。本地验证不代表本机安装已更新。[查看更新](docs/changelog.md#0126--2026-10-23)
+
 ## 快速开始
 
 ```console
@@ -32,6 +36,15 @@ dsh plugin --profile web add dsh-bundle-antigravity-host
 
 **额度或 AI Credits 没有显示？** ACP 连接与 CLI 登录是两条链路。额度查询优先使用已登录的官方 `agy`，AI Credits 仅从 CLI 读取；ACP 登录成功不代表 CLI 也已登录。[登录态与数据来源](docs/reference.md#登录态与额度来源)
 
+## 功能预览
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/KouzakiUmi/dsh-antigravity-acp/main/assets/readme/features-dark.png">
+  <img src="https://raw.githubusercontent.com/KouzakiUmi/dsh-antigravity-acp/main/assets/readme/features-light.png" width="1200" alt="模型选择器旁的额度药丸与展开的套餐额度弹层，以及「设置 → Antigravity ACP」中的连接状态与模型管理；虚构数据离线预览">
+</picture>
+
+左：模型选择器旁的额度药丸，展开后按额度组显示窗口与剩余百分比。右：设置页的连接状态、分阶段耗时与模型管理。画面来自当前 `src/client.js` 的真实组件，数字与套餐名均为虚构。
+
 ## 功能亮点
 
 ### 多个对话，不再共用一个待审批回合
@@ -73,7 +86,7 @@ flowchart LR
 
 本包是 **Host + Web Client bundle**：Host 注册模型 provider、管理官方进程和工具桥，Client 提供设置页与额度药丸。不修改 DSH Core，也不把官方 CLI 包装成聊天接口；CLI 仅用于只读模型目录、额度与余额查询。
 
-**它不是直接的 Gemini 模型 API。** 普通新用户回合会创建 ACP 会话并重放完整 DSH 历史；工具续轮才复用同一 prompt。角色消息、采样控制、延迟与计费不能视为和原生 API 相同。
+**它不是直接的 Gemini 模型 API。** 默认情况下同一 DSH 对话会复用同一个 ACP 会话，在输入前缀与上一步输出一致时，后续回合只发送新增消息，未变化的上下文去重，变化内容仍发送，历史由官方 agent 自己持有；历史被压缩、回退或编辑，或模型、系统提示、工具目录变化时自动重建会话并全量重放一次（`reuseSessions=false` 可回到每轮重放）。工具续轮仍在同一个 prompt 内完成。角色消息、采样控制、延迟与计费不能视为和原生 API 相同。
 
 ## 使用前，先知道这些边界
 
@@ -82,7 +95,7 @@ flowchart LR
 | 工具与权限 | AGY 内置工具、ACP fs / terminal 关闭；只允许已识别的私有桥请求进入 DSH，`allow_once` 不等于绕过 DSH 审批。协议约束**不是 OS 沙箱**。 |
 | 登录材料 | 插件可能读取 CLI 登录文件，并为官方 ACP 写入 / 更新本机凭据文件；这些文件不是加密凭据库，Windows 访问保护依赖目录 ACL。 |
 | 官方程序 | 按需从 `https://dl.google.com` 下载，拒绝重定向并检查 ZIP 路径；官方未提供校验和，不宣称签名验证通过。默认 server 版本为 **1.4.0**，不跟随 registry 自动升级。 |
-| 模型参数 | `reasoningEffort` 映射官方档位；`maxTokens` 忽略；显式 `temperature` / `stop` 返回 `UNSUPPORTED_OPTION`。 |
+| 模型参数 | `reasoningEffort` 映射官方档位；`maxTokens` 忽略；显式 `temperature` / `stop` 记录警告并忽略，值不生效。 |
 | 数据可信度 | 缓存、失败、缺字段和未知分别标记；额度与余额仅供参考，不是计费依据。 |
 | 版本与测试 | 宽 peer 范围是安装条件，不是全部 Core / 平台版本实机兼容证明；隔离测试不替代真实账号与 GUI 验收。 |
 
@@ -94,7 +107,7 @@ flowchart LR
 | DSH Core peer 范围 | `>=0.2.0-rc.1 <0.2.1-0 \|\| >=0.2.1-0 <0.3.0-0`，适用于所声明的三个 `dsh-*` peer |
 | 开发契约基准 | `dsh-llm` / `dsh-subprocess` / `dsh-typert-protocol` / `dsh-attachment` **0.2.1-alpha.4**，Cordis **4.0.5-alpha.2** |
 | 上游协议 | ACP **v1**；SDK **1.4.0** 与默认 server **1.4.0** 是两个独立版本 |
-| 本次本地验证 | 类型检查、33 个文件 / 515 项隔离测试、构建 |
+| 当前源码本地验证 | 类型检查、36 个文件 / 591 项测试、构建；本机安装另行核验 |
 | 尚未覆盖 | 0.1.24 安装后的 Desktop GUI、真实上游生成与图片识别、非 Windows 实机 |
 
 宿主附件服务是可选依赖，缺少时仍可文本聊天，但不声明图片能力。安装准入、开发类型检查和真实运行兼容性分别看待。[完整声明与验证方法](docs/development.md)

package/dist/adapter/antigravity-adapter.d.ts

@@ -4,13 +4,9 @@
  * 形态：官方 ACP server（Gemini 主模型）走 stdio，工具留在 DSH 侧，经插件
  * 进程内的私有 loopback MCP 桥暴露给 agent（见 ../bridge/mcp-bridge.ts）。
  *
- * 历史权威是 DSH：**本文件不建任何会话存储/数据库/文件**。新轮用
- * 完整的 `options.messages` + `options.system` 建立 ACP prompt，工具结果续轮复用该 prompt
- * （见 prompt-transcript.ts）；唯一的跨回合内存态是「当前 ACP 回合」与
- * 「park 中的 MCP tools/call」，它们都随回合结束而释放。
- *
- * 不支持项一律抛 `LlmError(..., 'UNSUPPORTED_OPTION')`（dsh-llm 0.2.1 的
- * error.d.ts 未导出该码的官方常量，因此用字面量并在下方集中定义）。
+ * DSH 是历史权威：只有输入前缀、上轮实际交付输出与路由一致才复用会话；
+ * 不一致时完整重建。工具结果在同一个 ACP prompt 内经 MCP 回填。
+ * 可选磁盘映射只保存 ID、计数与指纹，不存消息正文。
  */
 import { LlmAdapter } from '@deepseek-ai/dsh-llm';
 import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, PreparedAdapterCall, StreamChunk } from '@deepseek-ai/dsh-llm';
@@ -19,6 +15,8 @@ import type { AgentLink, AgentLinkHandlers } from '../protocol/agent-link.js';
 import { McpToolBridge } from '../bridge/mcp-bridge.js';
 import type { ImageReader } from './image-content.js';
 import type { AcpLifecycle } from '../runtime/lifecycle.js';
+import { SessionMapStore } from '../runtime/session-map.js';
+import type { SessionMapEntry } from '../runtime/session-map.js';
 /** DSH 侧 provider 标识符；与 cordis.patch.yml 的 id 及文档保持一致。 */
 export declare const AGY_PROVIDER_ID = "antigravity-acp";
 /**
@@ -28,8 +26,7 @@ export declare const AGY_PROVIDER_ID = "antigravity-acp";
  */
 export declare const AGY_PLACEHOLDER_MODEL_ID = "server-default";
 /**
- * 不支持项的机器错误码。dsh-llm 0.2.1-alpha.2 的 `error.d.ts` 未导出
- * `UNSUPPORTED_OPTION` 常量，故使用字面量并集中在此定义。
+ * @deprecated 兼容旧导出的错误码；temperature / stop 现在只警告并忽略，不再抛此码。
  */
 export declare const AGY_UNSUPPORTED_OPTION = "UNSUPPORTED_OPTION";
 /** 本 adapter 的其余原创错误码（AGY_* 体系）。 */
@@ -38,6 +35,8 @@ export declare const AGY_ADAPTER_ERROR: {
     readonly BUSY: "AGY_BUSY";
     /** 回合需要一个模型选择器，但 ACP 会话未声明任何 model 类 configOption。 */
     readonly NO_MODEL_SELECTOR: "AGY_NO_MODEL_SELECTOR";
+    /** agent 应答选模却没有确认请求的型号，不能静默使用其他模型。 */
+    readonly MODEL_SELECTION_MISMATCH: "AGY_MODEL_SELECTION_MISMATCH";
 };
 /** MCP 桥与回合的可调参数（由 index.ts 从插件配置注入）。 */
 export interface AntigravityAcpAdapterOptions {
@@ -84,6 +83,32 @@ export interface AntigravityAcpAdapterOptions {
      * `session/set_config_option` 失败原因。缺省时不产任何日志。
      */
     log?: AdapterLog;
+    /**
+     * 复用同一个 ACP 会话（默认 true）：同一 DSH 对话的后续回合只发送新增消息，
+     * 不再每轮 `session/new` 并重放全部历史。历史被压缩/回退、路由或工具目录
+     * 变化时仍会受控重建。关闭后回到旧的「每轮新会话 + 全量重放」。
+     */
+    reuseSessions?: boolean;
+    /**
+     * 跨进程恢复 ACP 会话（默认 false）：重启后若存在会话映射，尝试
+     * `session/load` 恢复而不是从零重建。需要提供 loadSessionMap / saveSessionMap。
+     */
+    resumeSessions?: boolean;
+    /**
+     * 用户取消后是否保留官方进程（默认 false：立即回收，下一轮要冷启动）。
+     * 开启后先等 `cancelGraceMs` 让 agent 确认停止；确认了就只丢弃会话、保留进程。
+     */
+    keepProcessAfterCancel?: boolean;
+    /** 取消后的确认宽限（毫秒）；0 表示不等待、立即回收，绝不复用未确认连接。 */
+    cancelGraceMs?: number;
+    /** 保留进程的最长空闲时间（毫秒），超时回收；0 表示不设上限。 */
+    idleRecycleMs?: number;
+    /** 所有 worker 共享的映射存储（含键所有权与串行提交）。 */
+    sessionStore?: SessionMapStore;
+    /** 独立 adapter 的兼容读取回调；连接池必须改用共享 sessionStore。 */
+    loadSessionMap?: () => Promise<Record<string, SessionMapEntry>>;
+    /** 保存 ACP 会话映射；失败由实现方吞掉。 */
+    saveSessionMap?: (entries: Record<string, SessionMapEntry>) => Promise<void> | void;
 }
 /** 适配器可用的最小日志面（与 cordis 的 `ctx.logger` 结构兼容）。 */
 export interface AdapterLog {