dsh-agy-acp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 higekibaka
+
+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,96 @@
-# Temporary Holding Version
+<div align="center">
 
-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.
+# Antigravity ACP Worker (`dsh-agy-acp`)
+
+**将本机 Antigravity CLI（`agy`）作为可续聊、可后台自动唤醒、可排队并发的 ACP Worker 挂载到 DeepSeek Harness。**
+
+[![npm](https://img.shields.io/npm/v/dsh-agy-acp?color=3b82f6&label=npm)](https://www.npmjs.com/package/dsh-agy-acp)
+[![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/development.md) · [更新记录](docs/changelog.md)
+
+</div>
+
+---
+
+它直连 `agy` 原生 ACP 通道（JSON-RPC 2.0 over NDJSON，每行一条结构化消息），而不是屏幕抓取或 PTY 猜字，因此流式回复、工具调用轨迹、权限请求与取消清理都是可观测的结构化事件。
+
+## 核心场景
+
+| 场景 | `dsh-agy-acp` 的表现 |
+| --- | --- |
+| 复用本机 `agy` 订阅模型干活 | `action:"start"` 起一个 Worker，默认 `wait:false` 挂进宿主 `ctx.jobs` 后台执行，完成后自动唤醒父会话 |
+| 多轮追问保留上下文 | 同名 `action:"followup"` 通过 `session/load` 恢复同一 `agySessionId`，支持延续上一轮模型、档位与模式 |
+| 并发派发多份任务 | 多个 `start` 立刻拿到各自 `jobId`，底层通过全局信号量（默认并发 1）排队串行，避免争抢 `agy` SQLite 锁 |
+| 本地精准单步 Token 账单 | 只读打开本机 `agy` SQLite 会话库——**无 WAL 侧车时**用 `?immutable=1`（不生成 `-wal`/`-shm`）；**活跃 WAL 存在时**退回普通只读，避免读到未 checkpoint 的半截快照，并与 ACP `usage_update` 做容差对账 |
+| 传递图片附件或本地截图 | 支持传入授权本地路径、`data:image/*;base64,...` 或宿主附件引用；远端**明确声明** `promptCapabilities.image=false` 时降级为纯文本并告警，未声明（`unknown`）则先按支持尝试发送 |
+| 按需查看剩余额度 | 监控面板点击「刷新额度」才按需运行只读命令 `agy -p /usage --output-format json`（可选 `/credits`），打开面板不自动起进程 |
+
+## 快速开始
+
+### 环境要求
+
+- DeepSeek Harness `>= 0.2.2-rc.1`
+- Node.js `^22.19.0 || >= 24.0.0`
+- 本机已安装并登录 **Antigravity CLI（`agy`）**
+
+### 安装与启用
+
+通过 DSH CLI 或 Web 端 **Plugins** 页面安装 `dsh-agy-acp`：
+
+```console
+dsh plugin --profile desktop add dsh-agy-acp
+```
+
+安装后按宿主提示重载或重启使 Host 与 Web Client 同时生效。未在设置页填写 `executable` 时，插件会按以下顺序自动探测本机 `agy`：
+
+`config.executable` → `AGY_ACP_BIN` / `AGY_BIN` → `ctx.subprocess.resolveExecutable('agy')` → 各平台默认安装目录。
+
+## 架构概览
+
+```text
+DSH 会话（父 Agent）
+   │  agy_acp({ action, name, prompt, images, wait, ... })
+   ▼
+index.js ── Config (schemastery) / 沙盒策略翻译 / 工具与 Typert 注册
+   ▼
+AgyWorkerService (src/worker-service.js)
+   ├─ WorkerRegistry     ~/.dsh/agy-acp/workers.json（原子写）
+   ├─ Semaphore          全局 maxConcurrent (1..4)
+   ├─ TurnUsageTracker   SQLite 只读单步账单 + ACP usage_update 对账
+   ├─ getQuota()         5 分钟缓存 + single-flight + 45s 硬超时 + stale 保留
+   └─ AcpClient          NDJSON 分帧 / 握手独立超时 / 四级审批 / 图片能力协商
+         ▼
+   ctx.subprocess.spawn (agy acp --stdio)
+```
+
+## 使用前，先知道这些边界
+
+| 边界项 | 当前实际行为（不夸大承诺） |
+| --- | --- |
+| **进程管理 ≠ OS 文件沙盒** | `ctx.subprocess` 负责整棵进程树生命周期回收，**不拦截** `agy` 原生读写磁盘。若需强隔离，请配合操作系统受限账户、容器或虚拟机。 |
+| **ACP 审批是尽力拦截** | 插件对收到的 `session/request_permission` 按四级规则严格裁决（含 `call_mcp_tool` + `_meta.mcp` 防欺诈检验），但依赖上游是否发起权限请求。 |
+| **后台 `wait:false` 拒绝非白名单操作** | 父会话处于轮次间 idle 时，不在 `bridgeAllowlist` 内的权限请求一律 `fail-closed` 拒绝；仅 `wait:true` 前台模式弹窗询问宿主审批。 |
+| **Windows Low Integrity 保护** | 若 `agy` 落在 `AppData\\LocalLow` 或 ACL 含 `Low Mandatory Level`（`S-1-16-4096`），插件会直接拒绝启动并报错（`AGY_LOW_INTEGRITY_EXECUTABLE`），防止子进程挂死。 |
+| **额度与账单可信度** | 本地 SQLite 账单与 `/usage`/`/credits` 均零联网修改且严禁把 `unknown` 伪装成 `0`，仅作本地监控参考，不作为正式计费依据。 |
+
+## 常见排障
+
+- **找不到 `agy`**：在设置页「Antigravity ACP Worker」填入完整路径，或设置环境变量 `AGY_ACP_BIN` / `AGY_BIN`。
+- **报 `AGY_LOW_INTEGRITY_EXECUTABLE`**：将 `agy` 移至常规用户目录（如 Windows 下的 `%LOCALAPPDATA%\\agy\\bin`）并确认非 Low 完整性目录。
+- **冷启动握手频繁超时**：适当调高设置页中的 `handshakeTimeoutMs`（默认 `120000` ms）。
+- **监控面板显示「已过期快照」**：最近一次手动刷新额度失败，面板保留了上一次成功快照并在横幅中展示脱敏后的失败原因。
+
+## 文档索引
+
+| 主题 | 文档 |
+| --- | --- |
+| 全量配置项、环境变量与 `bridgeAllowlist` | [配置参考](docs/configuration.md) |
+| `agy_acp` 工具入参、模型矩阵、图片与额度协议 | [接口与协议参考](docs/reference.md) |
+| 离线测试、源码结构与 GitHub/npm 发布指南 | [开发与发布](docs/development.md) |
+| 版本变更记录 | [更新记录](docs/changelog.md) |
+
+## 许可协议
+
+[MIT License](LICENSE)