dsh-bundle-antigravity-host 0.0.0-stage → 0.1.22

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-bundle-antigravity-host contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,310 @@
-# Temporary Holding Version
+# dsh-bundle-antigravity-host
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+DeepSeek Harness (DSH) host bundle：把 Google 官方 Antigravity ACP server
+（`agy-acp-server`，Gemini 背后的 agent）作为 LLM provider 接入 DSH。
+
+工作方式：
+
+- 插件通过宿主注入的 `ctx.subprocess` 服务以 stdio 启动官方 ACP server，
+  并以 Agent Client Protocol v1（JSON-RPC over newline-delimited JSON）通信。
+- 本包通过 `src/index.ts` 向 `ctx.llm` 注册 provider `antigravity-acp`
+  的 `LlmAdapter`。
+- 工具执行留在 DSH 侧：进程内私有 `127.0.0.1` loopback MCP 桥把当前
+  DSH 工具 schema 交给官方 agent；`tools/call` 被 park 后以 DSH
+  `tool-call` 结束本轮，下一轮带着 tool result 续同一 ACP prompt。
+- 若官方在 MCP 调用之前要求 ACP 授权，插件可把可解析的当前目录工具请求
+  转为普通 DSH `tool-call`；**官方原始调用仍被拒绝**，工具审批、参数校验和
+  沙箱执行由 DSH 负责。该路径每回合只接管一个请求，回收旧官方进程，收到
+  DSH 结果后按完整历史重建 ACP 回合，不在旧 prompt 上继续执行。
+- 登录态由本包**导入**：读本机官方 CLI 已登录的
+  `~/.gemini/antigravity-cli/antigravity-oauth-token`（只读），换发一颗
+  access token 后落成官方 server 认的 `~/.gemini/antigravity-acp/acp_token.json`，
+  并补写 `settings.json` 的 `auth.type = oauth-personal`。因此**不会拉起浏览器
+  登录页**，也不再发 `authenticate` 请求（该请求在没有交互式浏览器时会一直挂着）。
+  只有导入不到任何登录态时才回退到官方浏览器授权流程。
+
+安全边界（自动下载路径）：
+
+- 仅允许 `https://dl.google.com`，拒绝任何 HTTP 重定向；
+- zip 解压前逐条目校验路径（拒绝绝对路径、`..` 穿越、盘符/反斜杠异常路径）；
+- 官方未提供校验和，因此不伪造任何签名/校验和声明；
+- 下载先落临时文件，成功后原子重命名，失败清理残留。
+
+配置项：`binaryPath`（手动指定，优先级最高）、`autoDownload`（默认开启）、
+`extraArgs`、`acpVersion`、`requestTimeoutMs`、`authTimeoutMs`、
+`promptTimeoutMs`、`bridgeParkSettleMs`、`preferredModel`、`proxyUrl`、
+`proxyBypass`。
+环境变量：`AGY_ACP_BIN`（二进制覆盖）、`AGY_ACP_URL`（下载 URL 覆盖，
+供未验证平台组合使用）、`AGY_ACP_HOME`（可执行文件安装根目录覆盖）。
+
+## 二进制装在哪里（重要）
+
+自动下载的官方 server **不放在 DSH home 下**，默认装到用户级应用数据目录：
+
+- Windows：`%LOCALAPPDATA%\dsh-antigravity-host\<版本>\`
+- macOS / Linux：`$XDG_CACHE_HOME/dsh-antigravity-host/<版本>/`，其次 `~/.cache/...`
+
+原因不是洁癖，而是**功能必需**：DSH 会把 `$DSH_HOME`（默认 `~/.dsh`）整棵树标为
+**Low 强制完整性**（`icacls` 可见 `Mandatory Label\Low Mandatory Level`），而 Windows
+在创建进程时**会采用映像文件的强制完整性标签**。装在 `~/.dsh` 下的 exe 因此只能以
+LOW 运行，受 MIC「禁止向上写」约束，写不进中等完整性的 `~/.gemini/antigravity-acp/`：
+官方 server 保存凭据用的 `tempfile.NamedTemporaryFile` 会在 `PermissionError` 上
+无限重试，`session/new` 永不返回——表现为「Gemini 一直不回话」且没有任何报错。
+
+插件在启动前会**只读**跑一次 `icacls` 探测该标签；一旦命中就直接报
+`AGY_BINARY_LOW_INTEGRITY` 并给出修法，而不是把卡死留给用户（探测本身失败不会阻断
+启动）。手动指定 `binaryPath` 时请同样避开带该标签的目录。
+
+## 出网代理
+
+官方 `agy_acp_server` 自己连 Google（OAuth 与 Cloud Code Assist），而宿主
+`subprocess` 会 scrub 父进程环境，所以代理只能由本包显式注入子进程：
+
+- `proxyUrl`：如 `http://127.0.0.1:7890`；缺 scheme 按 `http` 处理，
+  支持 `http`/`https`/`socks5`/`socks5h`/`socks4`。留空继承宿主代理环境变量，
+  宿主也未配置时才直连；清空此项不等于强制关闭宿主代理。
+- `proxyBypass`：逗号分隔的排除列表，用户条目会与本机地址合并。
+- 注入 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 与对应小写键，
+  Windows 上运行的 Python 栈读大写，小写键覆盖 POSIX 风格读取者。
+- `localhost`、`127.0.0.1`、`::1` 始终排除：私有 MCP 桥与 OAuth 回调都在
+  loopback，走了代理工具回合会直接卡死。
+- 地址非法时在 spawn 之前报 `AGY_INVALID_PROXY`，不会先启动再失败。
+- 代理只在子进程启动时读取，改配置后需完全重启 Desktop（或让官方进程退出）。
+
+## 模型目录
+
+ACP v1 没有「不建会话、不认证」就能读到模型目录的方法：`InitializeResponse`
+只带 `protocolVersion` / `agentCapabilities` / `authMethods` / `agentInfo`，
+`configOptions` 只出现在会话响应与 `config_option_update` 里。因此：
+
+- 不再展示「首次对话登录」占位模型。没有缓存时目录可以为空，通过设置页显式
+  连接 ACP 或「一键拉取模型」获得目录，不必先发送聊天消息。
+- `preferredModel` 可从目录选择或手填自定义 ID，保存后优先列出；目录外 ID 明确
+  标记为用户配置、尚未验证。不会自动替换当前会话的已选模型。
+- 旧会话的 `server-default` 路由仍兼容：映射到 `preferredModel`，留空沿用官方默认，
+  但不再广告为新选择项。
+- 观测到的目录会写入 `$DSH_HOME/cache/antigravity-acp/catalog.json`（只含
+  id/name/description/contextWindow，不含任何凭据），重启后用它兜住选择器；ACP server 版本变化
+  或文件损坏即失效；没有其它来源时目录为空。
+- **家族折叠 + 思考强度路由**（2026-10-16 用户指示）：官方把思考强度编码进
+  模型 id（`claude-opus-5-5-{low,medium,high}`），但模型选择**只出家族一行**
+  （`claude-opus-5-5`「Claude Opus 5.5」），强度由 DSH 的思考强度菜单（低/中/高）
+  决定，路由到对应档位模型（选「高」→ `claude-opus-5-5-high`；未选走默认档位
+  `medium`，与官方默认 `Gemini 3.8 Flash (Medium)` 一致）。家族来源是会话观测
+  目录与官方 CLI 只读 `agy models` 清单（2026-10-16 授权「不 wrap agy CLI」
+  **仅限只读取数用途**，缓存 `cli-models.json`）折叠去重；`gpt-oss-120b` 整族
+  排除（临近下架，用户指示不进选择器）。配置里显式钉住档位 id（如
+  `gemini-3.8-flash-high`）且未选强度时，尊重钉住的档位。
+- **上下文容量**：官方目录不报告 context window，本包不填猜测值；首个回合收到
+  官方 `usage_update.size`（协议定义即 total context window size）后，把实测值
+  写进 `resolveModel().context` 并随目录落盘（目录条目是官方档位 id，落盘时按家族
+  id 对齐，折叠前后都能读回），压缩引擎由此可量化上下文，不再每步报
+  `no context capacity`。首轮回话之前仍是未知。
+
+### 请求项映射
+
+ACP v1 没有采样参数通道，以下请求项的处理是明确的：
+
+| 请求项 | 行为 |
+| --- | --- |
+| `reasoningEffort` | **路由键**（不是不支持项）：低/中/高 → 家族的 `-low`/`-medium`/`-high` 档位模型；家族缺该档位时取最接近档位。 |
+| `maxTokens` | **静默忽略**（输出上限由官方 agent 自己的会话配置决定）。宿主的会话标题等内建流程固定携带它，硬拒绝会让这些功能永久失败。 |
+| `temperature` / `stop` | 抛 `UNSUPPORTED_OPTION`：用户显式要求的效果无法兑现，不假装接受。 |
+
+## 稳定性与诊断
+
+- **ACP 权限与 DSH 审批分层**：插件从不选择 ACP 的 `allow_once` 或 `allow_always`。
+  官方 1.4.0 的 `_meta.mcp` 来自参数信封，并非可靠执行身份；插件只用它解析一个
+  **不可信的 DSH 工具请求**，且必须命中当前会话、当前桥名与当前工具目录，参数包装一致。
+  请求交给 DSH 后，官方原始调用被拒绝，旧桥凭证撤销、进程回收；重复或迟到请求不能
+  重复投递。DSH 工具结果的调用 id 和 `isError` 随完整历史进入新 ACP 会话，DSH 的拒绝
+  不会变成 ACP 自动放行。代价是这类调用每次重建回合，有额外启动开销。
+  无法解析的请求仍拒绝，不按标题或原始参数猜测授权，也不使用全局自动批准模式。
+  权限诊断只记录固定字段存在性、匹配关系与选项种类，不记录标题、调用 id、参数正文、
+  路径值或令牌。`Denied by user`/`pre-tool hook` 单独出现不能证明是 DSH 沙箱拒绝；
+  日志会区分插件拒绝与已转交 DSH。纯文本回复成功不代表真实工具链路已验收。
+- 主对话与后台标题可以并发调用同一个 provider。适配器在首次异步启动前占位、
+  串行调度；工具 park 期间保留主回合所有权，标题等待，不能覆盖当前回合或撤销工具桥。
+  同会话同步压缩则走放弃旧 prompt、按完整历史重建的兜底，避免等待自身工具结果而死锁。
+- 官方返回 `end_turn` 却没有可见文本或工具调用时，返回 `AGY_EMPTY_RESPONSE`，
+  不把空白、仅思考或仅进度通知当成成功回复。回合日志区分 `purpose`、文本/思考字符数与结束原因，
+  不记录回复正文。
+- MCP 调用在入桥时重新核对当前工具目录，未知或已撤销的工具直接返回错误，不进入
+  DSH 工具执行队列；每个新 ACP 回合轮换 token 与授权代次，旧通道不能向新回合投递调用。
+  MCP 会话通道按回合回收：新回合开始时关闭上一回合的全部通道（未完成 initialize 的
+  请求也会被就地收尾），通道数不随回合累积。
+- `finish(tool-calls)` 只封住当前 DSH 输出，不代表官方 prompt 结束。封口后到达的
+  调用与文本暂存到续轮，避免聚合窗口之外的并发调用丢失；等待工具期间仍响应取消。
+- 失败或取消会撤销桥授权，经宿主 `ctx.subprocess` 回收该连接的受管进程。
+  下一回合等待回收完成；无法确认退出时拒绝继续，不把本地 finish 当成后台已停止。
+  这是协议与进程生命周期保护，**不是 OS 文件系统沙箱**，不扩大原生工具权限。
+
+- `ensureAcpRuntime` 是 single-flight：并发首轮只 spawn 一条官方进程、只做一次
+  `authenticate`，不会留下 dispose 杀不到的孤儿进程，也不会重复弹登录。
+- 官方 stderr 含**完整 OAuth 授权 URL**（`state`、`code_challenge` 等）。本包在把
+  stderr 写进 `LlmError` 之前统一脱敏：URL userinfo 与敏感 query 参数一律打码，
+  非凭据上下文保留以便诊断。
+- 认证等待超时时不再回显授权 URL，而是提示「官方进程已打开 Google 登录页，
+  请在浏览器里完成授权」。认证超时使用独立错误码 `AGY_AUTH_TIMEOUT`，与普通
+  请求超时区分。
+- 本 provider **不声明任何可重试失败码**。宿主若消费重试策略会在失败步骤上整步
+  重放 `stream()`：握手失败会重复 spawn，认证超时会重复弹登录，`session/prompt`
+  超时会新建会话并重放全部历史（可能造成重复内容与重复工具调用）。三类都不可
+  安全重放，因此宁可一次不重试。
+
+## 设置卡片
+
+卡片走宿主真实存在的通道：`remote.settings.describe()` 读取、`remote.settings.mutate()`
+写入（改 `preferredModel` / `proxyUrl` / `proxyBypass`），`remote.llm.listProviders()`
+确认路由是否注册。宿主没有 `remote.llm.listModels`，本包通过自有
+`remote.agyQuota.models` 提供目录；强制刷新走官方 `agy models`，失败保留旧目录并显示错误。
+
+- **连接 / 登录 ACP**：需用户确认，复用本机官方登录态，必要时由官方进程打开浏览器
+  授权。只创建空工具会话验证连接，不发送模型 prompt；支持取消，结束后回收独立进程。
+  对话/工具回合进行中拒绝登录，不抢占当前聊天。状态只是最近一次连接验证，不代表
+  CLI 已登录，也不展示任何令牌或账号凭据。
+- **CLI 登录独立**：额度与 CLI 模型目录仍需在官方 `agy` 中完成登录；不假装 ACP
+  登录同时解决两份登录态，不实现未经核实的 CLI 无头登录。
+- **额度手动刷新**：设置页与药丸共用读取器，刷新结果同步；失败、缓存及未知有明确标记。
+- **模型选择**：目录下拉框与手填 ID 共用 `preferredModel`，点击保存生效。不提供模型
+  删除、禁用或账户切换，也不自动开启 AI Credits 付费。
+
+客户端插件的 `inject` 必须逐个声明用到的 remote 命名空间
+（`remote`、`remote.settings`、`remote.llm`）：宿主把每个命名空间做成独立服务，
+漏声明时连读属性都会抛 `cannot get property "remote.<ns>" without inject`，
+击穿 `settings.section` 卡片。卡片对属性读取异常一律降级为卡内可读错误，
+不再让异常穿出组件。
+
+## 额度监控（模型选择器旁用量药丸）
+
+选中 `antigravity-acp` 的模型时，输入区模型选择器**左侧**出现用量药丸
+（`conversation.input.right` 槽，宿主 InputBar 把它渲染在模型选择器之前；
+实现手法参考 dsh-subusage 的同位置药丸）。药丸本身只有当前模型所属额度组的
+迷你条（每个窗口一条），悬浮与无障碍标签提供窗口和百分比，不再显示服务商文字摘要。
+Gemini、Claude/GPT、Gemini 4 Argon 分开匹配，同 provider 切换模型也立即切换额度条。
+未知自定义型号或旧 `server-default` 不借用其它模型的数字，而显示未知符号。
+
+展开面板固定展示三个额度组，缺少的数据标为未提供；展示每窗剩余百分比、重置时间、
+当前模型标记、缓存状态、更新时间和刷新按钮。适配深浅主题，支持 Escape / 外部点击关闭。
+AI Credits 余额通过官方 `agy -p /credits --output-format json` 读取，取
+`command.data.remaining_credits`，可选套餐名为 `plan_name`。只接受成功的 credits
+本地报告与非负安全整数；真实零余额显示 0，缺字段/非法数字不转成零。
+
+余额与套餐额度分别缓存、分别标记失败和更新时间，共用刷新按钮。暂时查询失败可显示
+旧余额并明确标为缓存；官方明确不提供账户信息时撤下旧值。余额失败不影响正常模型
+额度，额度失败也不掩盖有效余额。没有 CLI 时余额标为未提供，不从 HTTP 配额推算。
+不会展示未经核验的升级链接，也不会开启 `useG1Credits` 付费回退。
+
+2026-10-22 已用本机官方 CLI 实测 `/credits`：退出码 0、`status: SUCCESS`、
+`command.name: credits`，金额为 number，`num_turns: 0`、`usage.total_tokens: 0`。
+该无头契约由本机实现与真实回包补充核验，官方 TUI 文档本身不完整覆盖其 JSON 接口；
+不据此保证所有旧版 CLI 都支持，旧版本/无信息/请求失败会显式显示状态。
+
+UI 使用宿主 React 18.3.1，生命周期依照 [React 18 文档](https://18.react.dev/reference/react/useEffect)。
+CLI 登录与余额限制参见官方 [安装与认证](https://antigravity.google/docs/cli/install.md)、
+[无头模式](https://antigravity.google/docs/cli/headless.md) 和 [AI Credits](https://antigravity.google/docs/cli/commands/credits.md)。
+可运行 `node scripts/preview-ui.mjs` 生成离线模拟预览；它不访问宿主页面、不执行登录，不能替代真实 GUI 验收。
+
+取数链路（Host 侧 `remote.agyQuota.read`）：
+
+1. **首选官方 CLI 的只读额度查询**：`agy -p /usage --output-format json`（slash
+   命令由 CLI 本地处理，实测 `num_turns: 0`、`total_tokens: 0`，无模型回合），
+   结果取 `command.data.groups[].buckets[]`（`window`/`remaining_fraction`/
+   `reset_time`）。CLI 路径可用 `AGY_CLI_BIN` 覆盖，缺省按
+   `%LOCALAPPDATA%\agy\bin\agy.exe` 等默认位置探测。
+2. 余额独立执行 `agy -p /credits --output-format json`，与套餐额度并发取数，各有
+   45 秒超时。多视图并发刷新合并为一轮，每个命令各执行一次；有效缓存不重复取数。
+3. 无官方 CLI 时仅套餐额度退回 Cloud Code Assist HTTP 线（读 `antigravity-oauth-token`
+   → 过期时内存内换发 → `loadCodeAssist` → `retrieveUserQuotaSummary`）；余额不猜测回退接口。
+
+取数边界：
+
+- CLI 取数仅使用 `/usage`、`/credits` 和 `models`，不发送聊天或修改付费设置；
+  子进程一律经 DSH 的 `ctx.subprocess`，环境和超时沿用同一套受管通道。
+- HTTP 额度回退对登录态只读，换发出的 access token 仅在内存里用；
+  CLI 通道不由插件直接读写凭据，官方 CLI 自行管理其认证状态；
+- token 材料不进快照、不进错误文本、不进日志（错误统一过 `redactSensitiveText`，
+  含 `Bearer <token>` 打码）；
+- 取数失败折叠成 `status: 'error'` 的可读快照，不把异常抛穿到界面。
+
+实测状态（2026-10-16，本机账户，真实跑通）：官方 CLI 额度查询解析出 3 组额度窗
+（Gemini Models / Claude and GPT models / Gemini 4 Argon，weekly 与 5h 窗、
+剩余百分比与重置时间齐全）。Cloud Code Assist HTTP 线是 **Gemini Code Assist
+（企业授权产品）**：本账户 `retrieveUserQuotaSummary` 403「no valid license of
+this product (#3501)」，仅作备用。原生 gRPC 接口
+`google.gca.aicode.v1main.JetskiRemoteAgentProxyService/GetUserQuotaSummary`
+已定位（宿主 `aicode.googleapis.com:443`）但服务端路由未接通，记录备查。
+
+## 宿主（DSH Core）兼容性声明
+
+宿主在**安装/启用时**会校验插件 manifest 里的 DSH 版本要求，不通过就拒绝安装
+（`ManagementFailure(incompatible-version)`，诊断文本以 `dsh: installation rejected:`
+开头）。规则（读自宿主 `@deepseek-ai/dsh-app-boot` 的 `evaluatePluginCompatibility`）：
+
+- 若声明了 `engines.dsh`，**该范围单独决定**，`peerDependencies` 一律忽略；
+- 否则逐个校验 `peerDependencies` 中名为 `@deepseek-ai/dsh` 或以 `@deepseek-ai/dsh-`
+  开头的项，其余包（含 `@deepseek-ai/cordis`）**不参与**该判定；
+- 比较对象是**运行时版本**，取 `@deepseek-ai/dsh-app-boot` 自身 `package.json` 的
+  `version`（即实际加载的 Core 版本，不是壳版本、也不是任何全局 CLI 版本），
+  且按 `includePrerelease: true` 参与范围匹配。
+
+本包当前声明（0.1.22）：
+
+| peer | 范围 | 说明 |
+|---|---|---|
+| `@deepseek-ai/dsh-llm` | `>=0.2.0-rc.1 <0.2.1-0 \|\| >=0.2.1-0 <0.3.0-0` | 参与宿主校验 |
+| `@deepseek-ai/dsh-subprocess` | 同上 | 参与宿主校验 |
+| `@deepseek-ai/dsh-typert-protocol` | 同上 | 参与宿主校验 |
+| `@deepseek-ai/cordis` | `~4.0.4 \|\| 4.0.5-alpha.1 \|\| 4.0.5-alpha.2` | 宿主不校验，仅供 pnpm peer 解析 |
+
+0.1.10 及更早版本把三个 `dsh-*` peer 写成了逐版本枚举（止于 `0.2.1-alpha.3`），
+在宿主升到 `0.2.1-alpha.4` 后判定为不兼容；0.1.11 换成上面这条宽范围
+（与社区插件 `dsh-subusage` 0.13.4 一致），对 `0.2.1-alpha.x`、`0.2.2` 均为真，
+对 `0.3.0-0` 及以后为假。
+
+若宿主将来越过该范围：可以更新本包的范围，或在插件管理器 / `dsh plugin allow-version`
+里为**精确的 name@version + 精确运行时版本**授予豁免（豁免记录在 profile 的
+`compatibility.json`）。豁免是显式接受风险，不是默认恢复步骤。
+
+契约面（非声明面）的核对状态：以宿主 0.2.1-alpha.4 的实际产物逐项对比过——
+`dsh-subprocess` 与 `cordis` 的类型声明逐字节相同；`dsh-llm` 只有新增可选成员
+（`imageRequestTarget`、`defaultBaseURL` 等，基类提供默认实现）；`dsh-typert-protocol`
+新增 `resources`/`principal` 等可选访问控制面，`register(contribution)` 签名未变，
+本包用的 contribution 形态（`{package, face, schemas, model, invocations}`）与同宿主上
+可用的 `dsh-subusage` 0.13.4 完全一致；客户端依赖的 `conversation.input.right` /
+`conversation.input.model` slot、`__ModuleLoader__`、`listProviders` 在新壳中均存在。
+开发依赖已对齐宿主版本并精确锁定（`dsh-llm` / `dsh-subprocess` / `dsh-typert-protocol`
+= `0.2.1-alpha.4`，`cordis` = `4.0.5-alpha.2`），`npm run check`（320 测试 / 21 文件 +
+类型检查 + 构建）在该版本类型上全绿。**未做**：真机安装 0.1.22 后的 GUI 验收
+（对话与额度药丸）。
+
+## 安装参考
+
+通用 CLI 示例（`web` 只是文档用的 profile 名，不是本机 Desktop）：
+
+```sh
+dsh plugin --profile web add ./dsh-bundle-antigravity-host-0.1.22.tgz
+```
+
+本机 Desktop 壳独占 `desktop` profile，公共 `dsh` 不能对它执行 `plugin add`。
+请在 DSH NEXT 的插件管理器里添加本地包，路径示例：
+
+`D:\dsh-antigravity-acp\.local-install\dsh-bundle-antigravity-host-0.1.22.tgz`
+
+装好后需要完全退出并重开 Desktop。只要本机官方 CLI 已登录过，
+`oauth-personal` 登录态会自动导入，**不会**弹浏览器登录页。模型路由名为
+`antigravity-acp`。
+
+## 排障
+
+| 现象 | 原因 | 处理 |
+|---|---|---|
+| 首次对话后 Gemini 完全不回话、也没有报错 | 二进制落在 Low 强制完整性目录，官方进程被降权后卡在凭据保存 | 插件现在会直接报 `AGY_BINARY_LOW_INTEGRITY`；删掉 DSH home 下的旧 `cache/antigravity-acp/*/extract-*` 即可，新版本默认装到 `%LOCALAPPDATA%` |
+| 启动即失败 `AGY_BINARY_MISSING` | 未配置 `binaryPath`、无缓存且 `autoDownload=false` | 打开 `autoDownload` 或指定 `binaryPath` |
+| 认证环节等到超时 | 导入不到任何本机登录态，退回官方浏览器授权 | 先用官方 CLI 登录一次，或在插件配置里填 `proxyUrl` 后重试 |
+| 官方进程连不上 Google | 宿主 scrub 了父环境，代理需显式注入 | 填 `proxyUrl`（留空时会自动转发宿主自身的 `*_PROXY`） |
+| 磁盘被 `_MEI*` 目录吃掉几十 GB | onefile 解压目录在进程被强杀后不会自清理 | 装载插件时会自动清理超过 1 小时的陈旧目录 |
+| 选某个具体型号后「没有反应」，默认项（首次对话登录）正常 | 该型号去索要原生 `fs`/`terminal` 能力（不同模型对工具的使用风格不同），回合被护栏终止 | 0.1.17 起改为「**拒绝但继续**」：原生请求与权限询问一律照旧**拒绝**（不授予任何本地能力），但不再当场终止回合，模型会改用桥过去的 DSH 工具；只有同一回合反复索要超过 3 次（明确坚持绕开工具桥）才按 fail-closed 终止 |
+| 药丸空着 / 药丸消失 | 贡献型 remote 的客户端挂载与依赖声明 | 插件必须在客户端 `ctx.remote.$mount(...)` 一次（0.1.15 起）；**不要**把 `remote.<ns>` 写进 `inject`（注册回调会永远等待 → 元素消失）|
+
+本 README 仅描述代码与产物现状，不构成已安装或兼容性承诺。

package/cordis.patch.yml

@@ -0,0 +1,6 @@
+# 仅注册本 bundle 的 LLM adapter；不写入任何 agent-default-model row，
+# 用户的默认模型选择不受本插件影响。
+- insert:
+    - id: llm-antigravity-acp
+      name: dsh-bundle-antigravity-host
+      inject: [llm, subprocess]

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

@@ -0,0 +1,157 @@
+/**
+ * Antigravity ACP 的 LlmAdapter 实现。
+ *
+ * 形态：官方 ACP server（Gemini 主模型）走 stdio，工具留在 DSH 侧，经插件
+ * 进程内的私有 loopback MCP 桥暴露给 agent（见 ../bridge/mcp-bridge.ts）。
+ *
+ * 历史权威是 DSH：**本文件不建任何会话存储/数据库/文件**。每次 `stream` 都
+ * 用完整的 `options.messages` + `options.system` 重建一条 ACP prompt
+ * （见 prompt-transcript.ts）；唯一的跨回合内存态是「当前 ACP 回合」与
+ * 「park 中的 MCP tools/call」，它们都随回合结束而释放。
+ *
+ * 不支持项一律抛 `LlmError(..., 'UNSUPPORTED_OPTION')`（dsh-llm 0.2.1 的
+ * error.d.ts 未导出该码的官方常量，因此用字面量并在下方集中定义）。
+ */
+import { LlmAdapter } from '@deepseek-ai/dsh-llm';
+import type { GenerateOptions, LlmModelInfo, LlmProviderInfo, LlmResolvedModelInfo, PreparedAdapterCall, StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { SessionConfigOption } from '@agentclientprotocol/sdk';
+import type { AgentLink, AgentLinkHandlers } from '../protocol/agent-link.js';
+import { McpToolBridge } from '../bridge/mcp-bridge.js';
+/** DSH 侧 provider 标识符；与 cordis.patch.yml 的 id 及文档保持一致。 */
+export declare const AGY_PROVIDER_ID = "antigravity-acp";
+/**
+ * GUI 冷启动占位模型。DSH 模型选择器会丢掉 `options.length === 0` 的 provider
+ * 分组，因此未观测 ACP 会话前必须至少广告一条目录，否则设置页看不到本路由。
+ * 选中该 id 时不调用 session/set_config_option，沿用官方会话默认模型。
+ */
+export declare const AGY_PLACEHOLDER_MODEL_ID = "server-default";
+/**
+ * 不支持项的机器错误码。dsh-llm 0.2.1-alpha.2 的 `error.d.ts` 未导出
+ * `UNSUPPORTED_OPTION` 常量，故使用字面量并集中在此定义。
+ */
+export declare const AGY_UNSUPPORTED_OPTION = "UNSUPPORTED_OPTION";
+/** 本 adapter 的其余原创错误码（AGY_* 体系）。 */
+export declare const AGY_ADAPTER_ERROR: {
+    /** 同一时刻已有活跃回合，且当前请求不是它的续轮。 */
+    readonly BUSY: "AGY_BUSY";
+    /** 回合需要一个模型选择器，但 ACP 会话未声明任何 model 类 configOption。 */
+    readonly NO_MODEL_SELECTOR: "AGY_NO_MODEL_SELECTOR";
+};
+/** MCP 桥与回合的可调参数（由 index.ts 从插件配置注入）。 */
+export interface AntigravityAcpAdapterOptions {
+    /**
+     * 惰性启动工厂：返回完成 initialize + authenticate 的 AgentLink。传入的
+     * handlers 必须在整个 adapter 生命周期内保持**同一对象**——index.ts 会把
+     * 首个 handler 集合固化到被缓存的 AgentLink 上，后续回合只更换其内部状态。
+     */
+    getLink: (handlers: AgentLinkHandlers, signal?: AbortSignal) => Promise<AgentLink>;
+    /** 回收指定连接及其受管子进程；完成前禁止开启下一个回合。 */
+    recycleLink: (link: AgentLink) => Promise<void>;
+    /** 登记桥的关闭钩子（index.ts 把它挂到 ActiveAcpRuntime.bridgeTeardown）。 */
+    registerBridgeTeardown: (teardown: () => Promise<void>) => void;
+    /** session/prompt 等待上限（毫秒）。 */
+    promptTimeoutMs?: number;
+    /** 并发 MCP park 的聚合窗口（毫秒）。 */
+    parkSettleMs?: number;
+    /** session/new 使用的工作目录；缺省为进程 cwd。 */
+    cwd?: string;
+    /** 占位模型 server-default 映射到的官方模型 id；空则沿用会话默认。 */
+    preferredModel?: string;
+    /**
+     * 冷启动目录读取（磁盘缓存）。返回 undefined 表示没有可用缓存；**不得**抛错。
+     * 元数据方法不得触网，因此这里只能读本地文件。
+     */
+    loadCachedCatalog?: () => Promise<CachedModel[] | undefined>;
+    /** 观测到真实目录后的落盘回调；失败由实现方自行吞掉。 */
+    saveCatalog?: (models: readonly CachedModel[]) => Promise<void> | void;
+    /**
+     * 官方 CLI 模型清单（`agy models` 的只读取数，2026-10-16 授权仅限只读取数
+     * 用途）。用于补齐会话观测之外的官方型号；失败由 adapter 吞掉。
+     */
+    loadCliCatalog?: () => Promise<readonly {
+        id: string;
+        name: string;
+    }[]>;
+    /**
+     * 宿主日志（index.ts 接 `ctx.logger`）。仅用于**自诊断**：模型路由决策与
+     * `session/set_config_option` 失败原因。缺省时不产任何日志。
+     */
+    log?: AdapterLog;
+}
+/** 适配器可用的最小日志面（与 cordis 的 `ctx.logger` 结构兼容）。 */
+export interface AdapterLog {
+    info(message: string): void;
+    warn(message: string, error?: unknown): void;
+}
+/** 目录缓存条目（只含模型元数据，不含任何凭据）。 */
+export interface CachedModel {
+    id: string;
+    name: string;
+    description?: string;
+    /** 实测上下文容量（usage_update.size）；官方目录不报告，故可缺省。 */
+    contextWindow?: number;
+}
+export declare class AntigravityAcpAdapter extends LlmAdapter {
+    #private;
+    constructor(options: AntigravityAcpAdapterOptions);
+    /** 设置页连接不能与正在进行的对话/工具回合竞争同一登录态。 */
+    get busy(): boolean;
+    /** 私有 MCP 桥（诊断与测试可见；agent 侧只经 ACP mcpServers 访问它）。 */
+    get bridge(): McpToolBridge;
+    providerInfo(provider: string): LlmProviderInfo;
+    /**
+     * 模型目录：只读**已观测**的 ACP 会话配置，绝不为了列目录而启动运行时。
+     *
+     * 依据已安装 SDK 1.4.0 的 d.ts：`InitializeResponse` 只有 protocolVersion /
+     * agentCapabilities / authMethods / agentInfo，**没有 configOptions**；模型
+     * 选择器出现在 `session/new` 响应、`session/set_config_option` 响应或
+     * `session/update(config_option_update)` 里。也就是说，ACP v1 没有任何
+     * 「无副作用即可读到模型目录」的方法；而启动运行时必然走
+     * `authenticate`（官方进程会自行弹浏览器）。
+     *
+     * 无真实目录时不再广告首次登录占位项；可在设置页显式连接 ACP 或拉取 CLI
+     * 目录。真实目录经 `observeSessionConfigOptions` 观测并缓存。
+     */
+    /**
+     * 本 provider 的模型目录：官方**家族**条目与用户配置的自定义 ID。
+     *
+     * 家族折叠（2026-10-16 用户指示）：官方把思考强度编码进模型 id
+     * （`claude-opus-5-5-{low,medium,high}`），但模型选择只出家族一行，强度由
+     * 思考强度菜单路由（见 #applyModelSelection）。会话观测目录与官方 CLI 清单
+     * 一并折叠，同 id 去重；被排除的家族（gpt-oss-120b 临近下架）不出现。
+     */
+    listModels(_provider: string): Promise<readonly LlmModelInfo[]>;
+    /**
+     * 本 provider **不声明**任何可重试失败码：宿主若整步重放 `stream()`，握手失败会
+     * 重复 spawn、认证超时会重复弹登录、prompt 超时会重放全部历史与工具调用。详见
+     * 文件里「关于失败重试」的说明。
+     *
+     * 注意返回 `undefined` 会让宿主装上自己的默认政策；它对本 provider 不生效的
+     * 前提（我们只抛 `AGY_` 前缀码）由测试锁住，不是靠这里的注释维持。
+     */
+    providerRetryPolicy(_provider: string): undefined;
+    /**
+     * 精确模型解析。按 dsh-llm 的目录语义，目录成员资格是**建议性**的
+     * （catalog membership remains advisory），因此这里不因未登记的 id 报错；
+     * 真正的能力拒绝发生在 ACP 会话侧（模型不存在时 agent 自行报错）。
+     */
+    resolveModel(provider: string, model: string, _signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
+    prepareCall(provider: string, model: string, signal?: AbortSignal): Promise<PreparedAdapterCall>;
+    /**
+     * 一次模型调用的 chunk 流。
+     *
+     * 判定「续轮 vs 新轮」：messages 尾部的连续 tool 结果消息与当前回合 park
+     * 的 MCP 调用**按顺序一一匹配**且该回合的 ACP prompt 尚未应答 → 续轮；
+     * 否则按新轮重建（放弃旧回合、新建 ACP session、重放完整 messages）。
+     * 并发防御：主对话与标题/压缩请求可以同时进入同一个 adapter；从首个 await
+     * 之前串行化 stream。工具 park 保留回合所有权，辅助请求等待而不是抢占主回合。
+     */
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+    /**
+     * 观察一次 ACP 会话配置：刷新模型目录缓存与 model 选择器。
+     * `session/new`、`session/set_config_option` 与 `config_option_update` 共用。
+     */
+    observeSessionConfigOptions(configOptions: readonly SessionConfigOption[] | null | undefined): void;
+    /** 是否已经从真实 ACP 会话观测到过配置（listModels 空目录时的诊断依据）。 */
+    get catalogObserved(): boolean;
+}