dsh-agy-link 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.2.2 (2026-08-19)
+
+- README: dedicated Prerequisites section (DSH, Node >= 24, the agy CLI with Google's official install guide link, first-run login, subscription note), a "how it works" intro paragraph, and an honest "what it cannot do" list in both languages - onboarding now covers first-time users.
+## 0.2.1 (2026-08-19)
+
+- Cross-platform hardening (Linux / macOS / Windows):
+  - binary discovery is platform-aware: agy / agy.exe / .cmd / .bat across
+    PATH, ~/.local/bin, /usr/local/bin, /opt/homebrew/bin,
+    %LOCALAPPDATA%\Programs, and the npm shim dir; a real executable is
+    always preferred over a cmd shim
+  - Windows .cmd/.bat shims spawn through cmd.exe with cross-spawn-style
+    argument quoting (unit-tested)
+  - tree-kill uses taskkill /T /F on Windows (Unix process groups do not
+    exist there); detached sessions are POSIX-only so no console window
+    flashes on Windows
+  - CRLF stdout is normalized (trailing \r stripped per line)
+  - the MCP bridge script path resolves via fileURLToPath (URL.pathname
+    would yield /C:/... on Windows and break the spawn)
+- 5 new cross-platform tests (56 total).
+
 ## 0.2.0 (2026-08-19)
 
 - Multimodal (path-based): DSH image attachments are staged to a local media
@@ -25,4 +45,3 @@
 - README restructured into a single bilingual page: Chinese first, then
   English (README.zh.md removed; package files list updated).
 - Releases now publish to npm automatically (NPM_TOKEN secret configured).
-

package/README.md

@@ -23,6 +23,8 @@
 `agy` CLI 驱动，完整支持对话输出、思考（thinking）、工具活动与 token
 用量，全部走你的 Antigravity 订阅。
 
+**它是怎么工作的**：在 `/model` 选择器里挑一个 Antigravity 模型，之后每一轮对话，插件都会在你的工作区启动一个短生命周期的官方 `agy` 进程（`agy -p --output-format stream-json`），解析它输出的 NDJSON 事件流，把文本、思考、工具活动逐块映射回 DSH。多轮对话通过把 DSH 会话绑定到 agy 原生会话（`--conversation`）实现——agy 自己保存历史，每轮只发最新消息。**插件只启动官方未修改的 agy 二进制**：不逆向它的数据库、不解码 protobuf、不碰你的 OAuth token。
+
 ## ✨ 你能得到什么
 
 | 能力 | 说明 |
@@ -39,18 +41,34 @@
 | 🌉 **MCP 反向桥（v0.2 实验）** | `mcpBridge: true` 开启后 agy 可直接调 DSH 侧工具（回环 + token 守卫端点 + 零依赖 stdio MCP 服务器，`.mcp.json` 合并写入/禁用还原） |
 | 😴 **休眠安全** | 没装 agy？没登录？插件照常加载并告诉你怎么修 |
 
+## 📋 前置要求
+
+装插件**之前**，先把这三样备齐（缺一样插件也能装，但会休眠并提示你补什么）：
+
+| 前置 | 怎么装 / 怎么验证 |
+| --- | --- |
+| **1. DeepSeek Harness（DSH）** | 你正在用的就是；`dsh --version` 可验证 |
+| **2. Node.js ≥ 24** | DSH 本身就要求 Node 24+，通常已满足；`node --version` 验证 |
+| **3. Google Antigravity 的 `agy` CLI** | 按 [Google 官方安装指南](https://antigravity.google/docs/cli/install)装（Linux / macOS / Windows 都有），然后**在终端跑一次 `agy`**，按提示完成 Google 登录。`agy --version` 能出版本号、`agy models` 能列模型就算就绪 |
+
+> **什么是 agy？** Google Antigravity 的官方命令行智能体（类似 Claude Code / Gemini CLI）。本插件不替代它，而是驱动它——所以你需要一份有效的 **Antigravity 订阅**（免费额度也行）。
+>
+> 没登录也能先装：插件自带的 `/agy auth` 会给你授权 URL + 二维码，在 GUI 里完成登录。
+
 ## 🚀 快速开始
 
 ```bash
-# 1. 安装（npm 官方包，预构建产物，无需构建许可）：
+# 0. 确认前置要求满足（见上一节）：agy --version 有输出
+
+# 1. 安装插件（npm 官方包，预构建产物，无需构建许可）：
 dsh plugin --profile web add dsh-agy-link
 #   升级：
 #   dsh plugin --profile web update dsh-agy-link --latest
 
 # 2. 重启 DSH Web GUI，输入框执行：
-#   /agy status     ← 确认 agy 已被检测到
+#   /agy status     ← 应显示 agy 版本号；没装好会告诉你缺什么
 
-# 3. 登录（一次性）：
+# 3. 登录（一次性；终端里已经跑过 agy 登录过的可跳过）：
 #   /agy auth               ← 打开授权 URL，批准并复制授权码
 #   /agy auth-code <授权码>  ← 或直接用侧栏面板的二维码 + 粘贴框
 
@@ -59,6 +77,8 @@ dsh plugin --profile web add dsh-agy-link
 
 > 插件绝不读取/复制/移动 `~/.gemini/antigravity-cli/antigravity-oauth-token`；登录完全通过官方 CLI 自己的流程完成。
 
+> 🖥 **跨平台**：Linux / macOS / Windows 均受支持——bin 探测按平台查找 `agy`/`agy.exe`（PATH、`~/.local/bin`、`/usr/local/bin`、`/opt/homebrew/bin`、`%LOCALAPPDATA%\Programs`，npm `.cmd` shim 自动经 cmd.exe 安全引号包裹启动）；中断/超时杀树在 Windows 走 `taskkill /T /F`；CRLF 输出统一剥离；媒体目录与 MCP 桥路径全部 `fileURLToPath`/`join` 构造。
+
 ## ⚙️ 配置
 
 配置在 `agy-link` 插件条目里（`/plugin` 或 profile patch 层编辑），环境变量优先：
@@ -87,9 +107,14 @@ DSH 侧的工具与权限不受影响——这里只约束 agy 子进程在自
 
 一次 DSH 模型调用 = 一个短生命周期 `agy -p --output-format stream-json` 进程。NDJSON 事件流被解析、归一化并映射为 DSH StreamChunk：思考 → reasoning 块，文本 → text 块，工具活动 → 注记 reasoning 块，结果信封 → usage + finish。会话 id 优先取自流本身，conversations 目录快照对比兜底。**不逆向数据库、不解码 protobuf、不碰 token 文件**——只启动官方未修改的 agy 二进制。
 
-## 📋 已知差距
+## 📋 它做不到什么（诚实清单）
+
+- **图片不是真多模态**——agy 的 print 模式没有图片入参，插件走的是“落盘 + 路径引用”方案（v0.2 起）：图片写进本地媒体目录，prompt 里给绝对路径，agy 用它自己的看图工具查看。能用，但和原生多模态不同。
+- **agy 的文件编辑不经过 DSH 审批**——它直接落盘，DSH 的 inline diff 审查不介入（想要只读就 `/agy mode plan`）。
+- **DSH 工具默认不暴露给 agy**——agy 跑自己的封闭工具循环；v0.2 的 MCP 反向桥（实验性，`mcpBridge: true`）可以打通，但有递归/扇出成本。
+- **结构化输出只在 `agy_ask` 里**——`schema` 参数走 `--json-schema`；DSH 原生工具调用生成还没接（上游没有对应字段）。
 
-见 [docs/KNOWN-GAPS.md](docs/KNOWN-GAPS.md)。要点：图片不转发（agy print 模式纯文本）；DSH 工具不暴露给 agy（MCP 反向桥接是后续工作）。
+完整清单见 [docs/KNOWN-GAPS.md](docs/KNOWN-GAPS.md)。
 
 ## ⚠️ 免责与风险提示
 
@@ -109,6 +134,8 @@ MIT
 
 Bring **Google Antigravity models into DeepSeek Harness (DSH)** — chat, thinking, tool activity, and token usage from your Antigravity subscription, driven by the official `agy` CLI.
 
+**How it works**: pick an Antigravity model in the `/model` picker; for every turn the plugin spawns a short-lived, official `agy` process in your workspace (`agy -p --output-format stream-json`), parses its NDJSON event stream, and maps text, thinking, and tool activity back into DSH chunk by chunk. Multi-turn rides a binding between the DSH session and a native agy conversation (`--conversation`) — agy keeps its own history, so only the latest message is sent each turn. **The plugin only ever spawns the official, unmodified agy binary**: no database reverse-engineering, no protobuf decoding, no touching your OAuth token.
+
 ## ✨ What you get
 
 | Capability | Description |
@@ -125,18 +152,34 @@ Bring **Google Antigravity models into DeepSeek Harness (DSH)** — chat, thinki
 | 📎 **File inlining + structured output (v0.2)** | `agy_ask` gains `readPaths` (inline text files) and `schema` (enforced via `--json-schema`) |
 | 🌉 **MCP reverse bridge (v0.2, experimental)** | with `mcpBridge: true`, agy calls DSH-side tools directly (loopback token-guarded endpoint + zero-dep stdio MCP server merged into `.mcp.json`, restored on disable) |
 
+## 📋 Prerequisites
+
+Before installing, have these three ready (the plugin installs fine without them, but stays dormant and tells you what to fix):
+
+| Requirement | How to install / verify |
+| --- | --- |
+| **1. DeepSeek Harness (DSH)** | You are using it; `dsh --version` verifies |
+| **2. Node.js ≥ 24** | DSH already requires Node 24+; `node --version` verifies |
+| **3. Google Antigravity's `agy` CLI** | Follow [Google's official install guide](https://antigravity.google/docs/cli/install) (Linux / macOS / Windows), then **run `agy` once in a terminal** and complete the Google login. `agy --version` printing a version and `agy models` listing models means you are ready |
+
+> **What is agy?** Google Antigravity's official command-line agent (think Claude Code / Gemini CLI). This plugin does not replace it — it drives it, so you need an active **Antigravity subscription** (the free tier works).
+>
+> Not logged in yet? Install anyway: the built-in `/agy auth` gives you a consent URL + QR code to finish login inside the GUI.
+
 ## 🚀 Quick start
 
 ```bash
+# 0. Confirm the prerequisites (previous section): agy --version prints something
+
 # 1. Install (npm, prebuilt — no build approval needed):
 dsh plugin --profile web add dsh-agy-link
 #   Upgrade:
 #   dsh plugin --profile web update dsh-agy-link --latest
 
 # 2. Restart the DSH Web GUI, then in the composer:
-#   /agy status     <- confirm agy was detected
+#   /agy status     <- should show the agy version; tells you what is missing otherwise
 
-# 3. Login (one time):
+# 3. Login (one time; skip if you already ran agy in a terminal):
 #   /agy auth               <- open the consent URL, approve, copy the code
 #   /agy auth-code <code>   <- or use the sidebar panel (QR + paste box)
 
@@ -145,6 +188,8 @@ dsh plugin --profile web add dsh-agy-link
 
 > The plugin never reads, copies, or moves `~/.gemini/antigravity-cli/antigravity-oauth-token`; login is driven entirely through the official CLI's own flow.
 
+> 🖥 **Cross-platform**: Linux / macOS / Windows — platform-aware binary discovery (`agy` / `agy.exe` across PATH, `~/.local/bin`, `/usr/local/bin`, `/opt/homebrew/bin`, `%LOCALAPPDATA%\Programs`; npm `.cmd` shims spawn through cmd.exe with safe quoting), tree-kill via `taskkill /T /F` on Windows, CRLF output normalized, media and bridge paths built with `fileURLToPath`/`join`.
+
 ## ⚙️ Configuration
 
 Config lives in the `agy-link` plugin entry (edit via `/plugin` or the profile patch layer). Environment variables override the file:
@@ -173,9 +218,14 @@ DSH-side tools and permissions are unaffected — this only governs what the spa
 
 One DSH model call = one short-lived `agy -p --output-format stream-json` process. The NDJSON event stream is parsed, normalized, and mapped to DSH StreamChunks: thinking → reasoning blocks, text → text blocks, tool activity → annotated reasoning blocks, and the result envelope → usage + finish. Conversation ids come from the stream itself, with a conversations-directory snapshot diff as fallback. **No reverse-engineered database scraping, no protobuf decoding, no token-file access** — only the official unmodified agy binary is spawned.
 
-## 📋 Known gaps
+## 📋 What it cannot do (honest list)
+
+- **Images are not true multimodal** — agy print mode has no image input flag; since v0.2 the bridge stages images to a local media directory and references them by absolute path, with agy viewing them via its own tools. Workable, but not native multimodality.
+- **agy's file edits bypass DSH review** — they land directly on disk; DSH's inline diff review does not engage (`/agy mode plan` for read-only).
+- **DSH tools are not exposed to agy by default** — agy runs its own closed tool loop; the v0.2 MCP reverse bridge (experimental, `mcpBridge: true`) can bridge that, at a recursion/fan-out cost.
+- **Structured output only inside `agy_ask`** — the `schema` parameter rides `--json-schema`; DSH-native tool-call generation is not wired (no upstream field to map onto).
 
-See [docs/KNOWN-GAPS.md](docs/KNOWN-GAPS.md). Notably: images are not forwarded (agy print mode is text-only), and DSH tools are not exposed to agy (its MCP reverse bridge is future work).
+Full list in [docs/KNOWN-GAPS.md](docs/KNOWN-GAPS.md).
 
 ## ⚠️ Disclaimer & risk note
 

package/dist/index.js

@@ -7,6 +7,7 @@ import { execFileSync, spawn } from "node:child_process";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 import { createServer } from "node:http";
 import { randomBytes } from "node:crypto";
+import { fileURLToPath } from "node:url";
 //#region src/common/types.ts
 const PROVIDER_ID = "antigravity";
 const PLUGIN_ID = "agy-link";
@@ -1015,20 +1016,51 @@ async function sweepDir(dir, ttlMs, now = Date.now()) {
 function defaultMediaDir(stateDir) {
 	return join(stateDir, "media");
 }
+//#endregion
+//#region src/host/runner.ts
+const IS_WIN = process.platform === "win32";
+/** Executable candidates for one PATH entry, per-platform. Exported for tests. */
+function binCandidates(dir, platform = process.platform) {
+	return (platform === "win32" ? [
+		".exe",
+		".cmd",
+		".bat"
+	] : [""]).map((e) => join(dir, "agy" + e));
+}
+/** True when the resolved bin is a Windows cmd shim (needs shell wrapping). */
+function isCmdShim(bin) {
+	return /\.(cmd|bat)$/i.test(bin);
+}
+/** cmd.exe argument quoting (cross-spawn rules). Exported for tests. */
+function windowsQuote(arg) {
+	if (/[ \t\n\v"]/.test(arg) === false) return arg;
+	let escaped = arg.replace(/(\\+)\"/g, "$1$1\\\"").replace(/(\\+)$/, "$1$1");
+	escaped = "\"" + escaped.replace(/"/g, "\\\"") + "\"";
+	return escaped;
+}
 function resolveAgyBin(cfg) {
 	const candidates = [];
 	if (cfg.agyBin !== "") candidates.push(cfg.agyBin);
 	const pathEnv = process.env.PATH ?? "";
-	for (const dir of pathEnv.split(delimiter)) if (dir !== "") candidates.push(join(dir, "agy"));
-	candidates.push(join(homedir(), ".local", "bin", "agy"));
-	candidates.push("/usr/local/bin/agy");
+	for (const dir of pathEnv.split(delimiter)) if (dir !== "") candidates.push(...binCandidates(dir));
+	if (IS_WIN) {
+		const local = process.env.LOCALAPPDATA ?? "";
+		if (local !== "") candidates.push(join(local, "Programs", "agy", "agy.exe"));
+		candidates.push(join(homedir(), ".local", "bin", "agy.exe"));
+		candidates.push(join(homedir(), "AppData", "Roaming", "npm", "agy.cmd"));
+	} else {
+		candidates.push(join(homedir(), ".local", "bin", "agy"));
+		candidates.push("/usr/local/bin/agy");
+		candidates.push("/opt/homebrew/bin/agy");
+	}
+	const hits = [];
 	for (const c of candidates) try {
-		accessSync(c, constants.X_OK);
-		return c;
+		accessSync(c, constants.F_OK);
+		hits.push(c);
 	} catch {
 		continue;
 	}
-	return null;
+	return hits.find((h) => !isCmdShim(h)) ?? hits[0] ?? null;
 }
 function compareVersions(a, b) {
 	const pa = a.split(/\./).map(Number);
@@ -1045,6 +1077,24 @@ function parseVersion(out) {
 }
 function killTree(child) {
 	if (child.pid === void 0) return;
+	if (IS_WIN) {
+		try {
+			spawn("taskkill", [
+				"/pid",
+				String(child.pid),
+				"/T",
+				"/F"
+			], {
+				stdio: "ignore",
+				windowsHide: true
+			});
+		} catch {
+			try {
+				child.kill();
+			} catch {}
+		}
+		return;
+	}
 	try {
 		process.kill(-child.pid, "SIGTERM");
 	} catch {
@@ -1055,15 +1105,31 @@ function killTree(child) {
 }
 function startAgyProcess(opts) {
 	const started = Date.now();
-	const child = spawn(opts.bin, opts.args, {
+	const child = IS_WIN && isCmdShim(opts.bin) ? spawn(process.env.ComSpec ?? "cmd.exe", [
+		"/d",
+		"/s",
+		"/c",
+		[opts.bin, ...opts.args].map(windowsQuote).join(" ")
+	], {
 		cwd: opts.cwd,
 		env: process.env,
-		detached: true,
 		stdio: [
 			"pipe",
 			"pipe",
 			"pipe"
-		]
+		],
+		windowsVerbatimArguments: true,
+		windowsHide: true
+	}) : spawn(opts.bin, opts.args, {
+		cwd: opts.cwd,
+		env: process.env,
+		detached: !IS_WIN,
+		stdio: [
+			"pipe",
+			"pipe",
+			"pipe"
+		],
+		windowsHide: true
 	});
 	let stdout = "";
 	let stderr = "";
@@ -1088,7 +1154,7 @@ function startAgyProcess(opts) {
 		pending += chunk;
 		let nl;
 		while ((nl = pending.indexOf("\n")) >= 0) {
-			const line = pending.slice(0, nl);
+			const line = pending.slice(0, nl).replace(/\r$/, "");
 			pending = pending.slice(nl + 1);
 			opts.onLine?.(line);
 		}
@@ -2715,7 +2781,7 @@ function apply(ctx, entryConfig = {}) {
 		const want = cfg.mcpBridge && cfg.enabled;
 		if (want && bridgeState.bridge === null) (async () => {
 			try {
-				const script = new URL("./bridge.mjs", import.meta.url).pathname;
+				const script = fileURLToPath(new URL("./bridge.mjs", import.meta.url));
 				const toolsSvc = ctx.get("tools");
 				const bridge = await startMcpBridge({
 					bridgeScript: script,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-agy-link",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Google Antigravity (agy CLI) models for DeepSeek Harness — stream Gemini/Claude/GPT-OSS subscriptions into DSH with thinking, tool activity, token usage and in-GUI Google OAuth login.",
   "type": "module",
   "license": "MIT",