wtagent 0.1.0-alpha.2 → 0.1.0-alpha.4

package/README.md

@@ -13,16 +13,37 @@ WTAgent 把 GPT 网页聊天连接到本地工具，提供类似 Codex 的 CLI A
 网页 GPT 负责思考，WTAgent 在本机：
 
 - 读取和修改本地文件
-- 调用本地 Shell，运行构建、测试和开发服务
+- 调用结构化本地命令，运行构建、测试和开发服务
 
 不需要 OpenAI API Key，也不要求 ChatGPT Pro。WTAgent 使用独立的 Chrome Profile 保存你的网页登录状态，并使用该账号在网页上实际可用的模型和额度；如果账号拥有 Pro，它会成为额外优势。
 
+支持矩阵：
+
+- macOS
+- Linux
+- Windows 10 1809+ / Windows 11 x64
+- Windows ARM64 目前为预览支持
+
+边界：
+
+- 需要 Chrome 或 Chromium；首版不支持 Edge
+- Git 和 `rg` 是可选项，不是运行前提
+- WSL 不在首版支持范围内；请直接在原生 PowerShell / CMD / Windows Terminal 中运行
+
 ### 快速开始
 
 需要 Node.js 20.17+ 和 Chrome/Chromium。
 
 ```bash
-npm install -g wtagent@alpha
+npm install -g wtagent --registry=https://registry.npmjs.org/
+wtagent login
+```
+
+Windows PowerShell：
+
+```powershell
+npm install -g wtagent --registry=https://registry.npmjs.org/
+wtagent doctor
 wtagent login
 ```
 
@@ -33,6 +54,8 @@ cd my-project
 wtagent
 ```
 
+启动后先选择 ChatGPT 模式：`Pro` 会为新对话选择 Pro，`Current` 会保留网页当前设置且不执行模型切换。非交互调用默认使用 `Current`；需要 Pro 时可显式传入 `--mode Pro`。
+
 也可以直接附带任务：
 
 ```bash
@@ -40,10 +63,16 @@ wtagent "检查这个项目并修复测试"
 wtagent -C ./my-project "创建一个网站"
 ```
 
-之后直接在终端中继续对话。WTAgent 会把任务交给 GPT Web，并在本地执行文件和 Shell 操作。使用 `↑` / `↓` 浏览本次 CLI 会话的历史输入。
+之后直接在终端中继续对话。WTAgent 会把任务交给 GPT Web，并在本地执行文件操作和结构化本地命令。使用 `↑` / `↓` 浏览本次 CLI 会话的历史输入。
 
 按 `Ctrl+C` 或 `Ctrl+D` 可退出并关闭专用 Chrome。若上一次异常退出留下了 Chrome，WTAgent 会在验证其 CDP 身份后复用并接管它。
 
+常见说明：
+
+- `wtagent doctor` 会检查 Node、Chrome、目录权限和运行环境
+- 首次登录只会写入 WTAgent 的专用 Chrome Profile，不会接管你的日常浏览器 Profile
+- 如果系统没有 Git 或 `rg`，WTAgent 仍应保留核心文件读写与搜索能力
+
 ## English
 
 WTAgent connects GPT Web chat to local tools, providing a Codex-like CLI agent experience. The first adapter currently supports ChatGPT Web.
@@ -51,16 +80,37 @@ WTAgent connects GPT Web chat to local tools, providing a Codex-like CLI agent e
 GPT Web handles reasoning. WTAgent runs locally to:
 
 - Read and edit local files
-- Run shell commands, builds, tests, and development servers
+- Run structured local commands, builds, tests, and development servers
 
 No OpenAI API key or ChatGPT Pro subscription is required. WTAgent stores your web login in a dedicated Chrome profile and uses the models and quota actually available to that account. Pro is an optional bonus when the account has it.
 
+Support matrix:
+
+- macOS
+- Linux
+- Windows 10 1809+ / Windows 11 x64
+- Windows ARM64 is currently preview only
+
+Boundaries:
+
+- Requires Chrome or Chromium; Edge is out of scope for the first Windows release
+- Git and `rg` are optional accelerators, not runtime requirements
+- WSL is not supported in v1; run WTAgent from native PowerShell, CMD, or Windows Terminal
+
 ### Quick start
 
 Requires Node.js 20.17+ and Chrome/Chromium.
 
 ```bash
-npm install -g wtagent@alpha
+npm install -g wtagent --registry=https://registry.npmjs.org/
+wtagent login
+```
+
+Windows PowerShell:
+
+```powershell
+npm install -g wtagent --registry=https://registry.npmjs.org/
+wtagent doctor
 wtagent login
 ```
 
@@ -71,6 +121,8 @@ cd my-project
 wtagent
 ```
 
+At startup, choose a ChatGPT mode: `Pro` selects Pro for the new conversation, while `Current` keeps the current web setting without changing it. Non-interactive runs default to `Current`; pass `--mode Pro` to opt in explicitly.
+
 Or provide the first task directly:
 
 ```bash
@@ -78,10 +130,16 @@ wtagent "inspect this project and fix the tests"
 wtagent -C ./my-project "build a website"
 ```
 
-Continue chatting in the terminal. WTAgent sends tasks to GPT Web and executes file and shell operations locally. Use `↑` / `↓` to browse input history from the current CLI session.
+Continue chatting in the terminal. WTAgent sends tasks to GPT Web and executes file operations and structured local commands. Use `↑` / `↓` to browse input history from the current CLI session.
 
 Press `Ctrl+C` or `Ctrl+D` to exit and close the dedicated Chrome. If an abnormal exit leaves Chrome running, WTAgent verifies and adopts that CDP instance on the next start.
 
+Notes:
+
+- `wtagent doctor` checks Node, Chrome, writable data paths, and runtime support
+- WTAgent always uses its own Chrome profile and does not reuse your daily browsing profile
+- Core file and search capabilities must continue to work even when Git or `rg` is missing
+
 ## License
 
 [MIT](./LICENSE)

package/docs/technical-design.md

@@ -11,11 +11,20 @@
 - 双方通过普通聊天文本中的自定义 XML 交换工具调用和结果。
 - Runtime 循环执行“网页回复 → 解析工具 → 本地执行 → 回填结果”，直到任务完成。
 
+原生 Windows 支持约束：
+
+- 发布目标是 Windows 10 1809+ / Windows 11 x64；ARM64 先作为预览
+- 支持从 PowerShell、CMD 或 Windows Terminal 启动
+- 仅支持 Chrome / Chromium，不把 Edge 计入首版兼容矩阵
+- Git、`rg`、Codex、Claude Code 都不是运行依赖
+- WSL 不在首版范围内，需要从原生 Windows 终端直接运行
+- Windows 上仍保持同一个结构化执行协议：`program + argv + cwd`
+
 建议的首版技术组合：
 
 | 领域 | 选择 |
 | --- | --- |
-| 运行时 | Node.js 22+，JavaScript ESM |
+| 运行时 | Node.js 20.17+，JavaScript ESM |
 | CLI | `commander` + `@inquirer/prompts`，终端渲染可选 `ink` |
 | 浏览器控制 | `playwright-core`，使用用户已安装的 Chrome，非 headless |
 | XML | `saxes` 或 `fast-xml-parser`；工具参数按注册 Schema 二次校验 |
@@ -50,6 +59,12 @@
 - V1 支持 macOS、Windows、Linux。
 - V1 是 CLI，不做桌面 GUI 和远程控制台。
 
+其中 Windows 的产品边界需要额外强调：
+
+- `.cmd` / `.bat` 兼容属于运行时适配层职责，不能暴露为新的 shell-string 工具
+- `wtagent doctor` 需要明确区分“必需失败”“可选缺失”“能力降级”和“不支持的 WSL”
+- 打包发布必须经过原生 Windows 全局安装 smoke、路径带空格/中文、以及 Chrome 专用 Profile 验证
+
 ### 2.3 一个必须正视的技术事实
 
 普通 ChatGPT 网页聊天没有真正的 system message、tool schema 或 tool result channel。所谓“system prompt”“工具调用”“工具结果”都是由 CLI 作为普通用户文本发送。因此：
@@ -519,11 +534,18 @@ V1 不需要把 `cd` 暴露给模型；每个命令都有显式 `cwd`，且必
 
 - `cwd` 解析后必须位于项目根目录。
 - stdout/stderr 分开捕获并流式展示。
-- 达到上限后保留头尾并标记截断。
+- stdout 与 stderr 回填给网页模型的合计上限为 4 KiB；达到上限后按 UTF-8 字节安全地保留约 1 KiB 头部和 3 KiB 尾部，并标记原始与省略字节数。
+- 工具说明要求模型优先使用 `fs.search`、分页 `fs.read`、窄路径、子命令和测试过滤参数缩小输出；不假设系统已安装 Git、`rg` 或 Unix 文本工具。`terminal.exec` 不提供管道、重定向或其他 Shell 运算符。
+- 单次调用流式写入本地 `tool-output.jsonl` 的原始命令日志最多保留 4 MiB，超过后停止记录剩余日志，但不因此终止命令。
 - 超时先优雅终止，再强制终止进程树。
 - Windows 必须处理子进程树终止。
 - 返回 exit code、signal、duration 和截断信息。
 
+文件读取与网页传输另有两层硬限制：
+
+- `fs.read` 单次最多读取 16 KiB，通过返回的 `nextOffset` 继续读取；分段边界不得切断 UTF-8 字符。
+- 最终发送到浏览器的单条工具结果，包括 XML、续跑信息和 `<system_reminder>`，不得超过 24 KiB。Runtime 在字段级截断后生成完整 XML，Browser Adapter 在写入 composer 前再次按 UTF-8 字节数校验；禁止直接截断已经序列化的 XML。
+
 ### 7.4 长运行进程
 
 网站场景离不开 dev server，不能让 `terminal.exec` 永久阻塞。
@@ -820,7 +842,7 @@ macOS、Windows、Linux 都运行：
 | ChatGPT DOM 变化 | Provider Adapter 隔离、集中 Locator、Fixture 和诊断截图 |
 | 网页模型不遵守 XML | 简单协议、单工具/轮、确定性解析、有限重发 |
 | 重复执行工具 | assistant 指纹、call ledger、两阶段事件记录 |
-| 大输出塞满聊天 | 本地保存、截断回填、按需读取 |
+| 大输出塞满聊天 | 文件按 16 KiB 分段读取；命令结果回填 4 KiB；浏览器工具消息硬限制 24 KiB；本地命令日志限制 4 MiB |
 | dev server 阻塞 | 独立 Process Manager |
 | 跨平台 Shell 差异 | `program + argv + cwd`，复杂 Shell 单独审批 |
 | 路径逃逸 | realpath、符号链接检查、项目根策略 |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wtagent",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.4",
   "description": "Turn your own web AI session into a local tool-using agent.",
   "repository": {
     "type": "git",
@@ -25,12 +25,14 @@
   "files": [
     "src",
     "README.md",
-    "docs/technical-design.md"
+    "docs/technical-design.md",
+    "LICENSE"
   ],
   "scripts": {
     "test": "node --test",
     "test:unit": "node --test test/protocol.test.js test/policy.test.js test/tools.test.js test/prompt-builder.test.js test/session-export.test.js test/platform.test.js test/cli.test.js test/at-files.test.js",
     "test:integration": "node --test test/runtime.test.js",
+    "test:windows": "node --test test/windows-command-launcher.test.js test/windows-diagnostics.test.js test/windows-search-path.test.js test/atomic-write.test.js test/process-utils.test.js test/cdp-state.test.js test/windows-fixtures.test.js test/windows-package-smoke.test.js",
     "check": "node scripts/check-syntax.js",
     "doctor": "node src/cli/main.js doctor",
     "login": "node src/cli/main.js login",

package/src/browser/cdp-state.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { execFile } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { promisify } from "node:util";
+import { replaceFileAtomic } from "../shared/atomic-write.js";
 
 const execFileAsync = promisify(execFile);
 const CDP_STATE_FILE = ".wtagent-cdp.json";
@@ -37,7 +38,7 @@ async function writeJsonAtomic(filePath, value) {
       `${JSON.stringify(value, null, 2)}\n`,
       { mode: 0o600 },
     );
-    await fs.rename(temporary, filePath);
+    await replaceFileAtomic(temporary, filePath);
   } finally {
     await fs.rm(temporary, { force: true }).catch(() => {});
   }
@@ -114,7 +115,7 @@ function normalizeCandidate(candidate, profileDir) {
   }
   if (
     candidate.profileDir
-    && path.resolve(candidate.profileDir) !== profileDir
+    && !profileDirsMatch(candidate.profileDir, profileDir)
   ) {
     return null;
   }
@@ -128,6 +129,21 @@ function normalizeCandidate(candidate, profileDir) {
   };
 }
 
+function normalizeProfilePath(value, platform = process.platform) {
+  const input = String(value ?? "");
+  const resolved = platform === "win32"
+    ? path.win32.resolve(input)
+    : path.resolve(input);
+  if (platform !== "win32") {
+    return resolved;
+  }
+  return path.win32.normalize(resolved).replaceAll("/", "\\").toLowerCase();
+}
+
+function profileDirsMatch(left, right, platform = process.platform) {
+  return normalizeProfilePath(left, platform) === normalizeProfilePath(right, platform);
+}
+
 async function probeCandidate(candidate, profileDir, {
   isAlive = isProcessAlive,
   fetchVersion = fetchCdpVersion,
@@ -202,7 +218,7 @@ async function readProcessTable() {
         "-Command",
         "Get-CimInstance Win32_Process | Select-Object ProcessId,CommandLine | ConvertTo-Json -Compress",
       ],
-      { maxBuffer: 10 * 1024 * 1024 },
+      { maxBuffer: 10 * 1024 * 1024, windowsHide: true },
     );
     const parsed = JSON.parse(stdout || "[]");
     return (Array.isArray(parsed) ? parsed : [parsed]).map((entry) => ({
@@ -219,24 +235,25 @@ async function readProcessTable() {
   return stdout.split("\n").flatMap((line) => {
     const match = line.match(/^\s*(\d+)\s+(.+)$/);
     return match
-      ? [{ pid: Number(match[1]), command: match[2] }]
+      ? [{ pid: Number(match[1]), command: match[2].trim() }]
       : [];
   });
 }
 
-function commandUsesProfile(command, profileDir) {
-  return (
-    command.includes(`--user-data-dir=${profileDir}`)
-    || command.includes(`--user-data-dir="${profileDir}"`)
-    || command.includes(`--user-data-dir='${profileDir}'`)
-  );
+function commandUsesProfile(command, profileDir, platform = process.platform) {
+  const inline = command.match(/--user-data-dir=(?:"([^"]+)"|'([^']+)'|(\S+))/i);
+  const separated = command.match(/--user-data-dir\s+(?:"([^"]+)"|'([^']+)'|(\S+))/i);
+  const raw = inline?.[1] ?? inline?.[2] ?? inline?.[3]
+    ?? separated?.[1] ?? separated?.[2] ?? separated?.[3]
+    ?? null;
+  return raw ? profileDirsMatch(raw, profileDir, platform) : false;
 }
 
-function candidateFromProcess(entry, profileDir) {
+function candidateFromProcess(entry, profileDir, platform = process.platform) {
   if (
     !entry.command
     || entry.command.includes("--type=")
-    || !commandUsesProfile(entry.command, profileDir)
+    || !commandUsesProfile(entry.command, profileDir, platform)
   ) {
     return null;
   }
@@ -246,6 +263,16 @@ function candidateFromProcess(entry, profileDir) {
     : null;
 }
 
+function profileHolderFromProcess(entry, profileDir, platform = process.platform) {
+  if (!entry.command || !commandUsesProfile(entry.command, profileDir, platform)) {
+    return null;
+  }
+  const pid = Number(entry.pid);
+  return Number.isSafeInteger(pid) && pid > 0
+    ? { pid, command: entry.command }
+    : null;
+}
+
 async function singletonOwnerPid(profileDir) {
   if (process.platform === "win32") {
     return null;
@@ -259,13 +286,17 @@ async function singletonOwnerPid(profileDir) {
   }
 }
 
-export async function processMatchesCdpState(state) {
-  const profileDir = path.resolve(state.profileDir);
+export async function processMatchesCdpState(state, {
+  listProcesses = readProcessTable,
+  platform = process.platform,
+} = {}) {
+  const pathApi = platform === "win32" ? path.win32 : path.posix;
+  const profileDir = pathApi.resolve(state.profileDir);
   const port = Number(state.port);
   try {
-    const processes = await readProcessTable();
+    const processes = await listProcesses();
     return processes.some((entry) => {
-      const candidate = candidateFromProcess(entry, profileDir);
+      const candidate = candidateFromProcess(entry, profileDir, platform);
       return (
         candidate?.pid === Number(state.pid)
         && candidate.port === port
@@ -276,30 +307,61 @@ export async function processMatchesCdpState(state) {
   }
 }
 
+function processTableContainsState(
+  processes,
+  state,
+  profileDir,
+  platform = process.platform,
+) {
+  const port = Number(state.port);
+  const pid = Number(state.pid);
+  return processes.some((entry) => {
+    const candidate = candidateFromProcess(entry, profileDir, platform);
+    return candidate?.pid === pid && candidate.port === port;
+  });
+}
+
 export async function discoverReusableCdpState(profileDir, {
   isAlive = isProcessAlive,
   fetchVersion = fetchCdpVersion,
   listProcesses = readProcessTable,
+  platform = process.platform,
 } = {}) {
   const resolvedProfile = path.resolve(profileDir);
+  const requireVerifiedProcessTable = platform === "win32";
   const saved = await readCdpState(resolvedProfile);
+  let processes;
+  try {
+    processes = await listProcesses();
+  } catch {
+    if (requireVerifiedProcessTable) {
+      return null;
+    }
+    processes = null;
+  }
+
   const savedHealthy = await probeCandidate(saved, resolvedProfile, {
     isAlive,
     fetchVersion,
   });
-  if (savedHealthy) {
+  if (
+    savedHealthy
+    && (!requireVerifiedProcessTable || processTableContainsState(
+      processes ?? [],
+      savedHealthy,
+      resolvedProfile,
+      platform,
+    ))
+  ) {
     return await saveCdpState(resolvedProfile, savedHealthy);
   }
 
-  let processes;
-  try {
-    processes = await listProcesses();
-  } catch {
+  if (!processes) {
     return null;
   }
 
   const rawCandidates = processes
-    .map((entry) => candidateFromProcess(entry, resolvedProfile))
+    .map((entry) => candidateFromProcess(entry, resolvedProfile, platform))
     .filter(Boolean);
   const uniqueCandidates = [...new Map(
     rawCandidates.map((candidate) => [
@@ -348,6 +410,7 @@ export async function reapStaleProfileChrome(profileDir, {
   fetchVersion = fetchCdpVersion,
   listProcesses = readProcessTable,
   killTree = null,
+  platform = process.platform,
 } = {}) {
   const resolvedProfile = path.resolve(profileDir);
   let processes;
@@ -357,28 +420,35 @@ export async function reapStaleProfileChrome(profileDir, {
     return { killed: [] };
   }
 
+  const holders = processes
+    .map((entry) => profileHolderFromProcess(entry, resolvedProfile, platform))
+    .filter(Boolean);
   const candidates = processes
-    .map((entry) => candidateFromProcess(entry, resolvedProfile))
+    .map((entry) => candidateFromProcess(entry, resolvedProfile, platform))
     .filter(Boolean);
 
-  const killed = [];
+  // A healthy main browser owns every helper/renderer using this profile.
+  // Never reap individual children from a verified live instance.
+  let hasHealthyCdpOwner = false;
   for (const candidate of candidates) {
-    // "Stale" = the CDP endpoint does not answer a healthy version probe. A
-    // healthy instance is left alone (it is a reuse candidate elsewhere).
-    let healthy = false;
     try {
       await fetchVersion(`http://127.0.0.1:${candidate.port}`);
-      healthy = true;
+      hasHealthyCdpOwner = true;
+      break;
     } catch {
-      healthy = false;
-    }
-    if (healthy) {
-      continue;
+      // Continue until one verified owner is found.
     }
-    if (isAlive(candidate.pid) && typeof killTree === "function") {
-      await killTree(candidate.pid).catch(() => {});
+  }
+  if (hasHealthyCdpOwner) {
+    return { killed: [] };
+  }
+
+  const killed = [];
+  for (const holder of holders) {
+    if (isAlive(holder.pid) && typeof killTree === "function") {
+      await killTree(holder.pid).catch(() => {});
     }
-    killed.push(candidate.pid);
+    killed.push(holder.pid);
   }
 
   // Chrome's singleton profile guard is a symlink; a crashed instance can leave
@@ -395,6 +465,82 @@ export async function reapStaleProfileChrome(profileDir, {
   return { killed };
 }
 
+export async function inspectCdpProfileState(profileDir, {
+  isAlive = isProcessAlive,
+  fetchVersion = fetchCdpVersion,
+  listProcesses = readProcessTable,
+  platform = process.platform,
+} = {}) {
+  const resolvedProfile = path.resolve(profileDir);
+  const diagnostics = [];
+
+  const lock = await readJson(lockPath(resolvedProfile));
+  if (lock?.pid) {
+    const alive = isAlive(Number(lock.pid));
+    diagnostics.push(
+      alive
+        ? `profile lock held by live pid=${lock.pid}`
+        : `stale profile lock references dead pid=${lock.pid}`,
+    );
+  } else {
+    diagnostics.push("no WTAgent profile lock");
+  }
+
+  const saved = await readJson(statePath(resolvedProfile));
+  if (!saved) {
+    diagnostics.push("no saved CDP state");
+    return {
+      status: "pass",
+      detail: diagnostics.join("; "),
+    };
+  }
+
+  const savedHealthy = await probeCandidate(saved, resolvedProfile, {
+    isAlive,
+    fetchVersion,
+  });
+  if (!savedHealthy) {
+    diagnostics.push(`saved CDP state for pid=${saved.pid} is stale or unhealthy`);
+    return {
+      status: "degraded",
+      detail: diagnostics.join("; "),
+    };
+  }
+
+  if (platform !== "win32") {
+    diagnostics.push(`saved CDP state is healthy for pid=${savedHealthy.pid}`);
+    return {
+      status: "pass",
+      detail: diagnostics.join("; "),
+    };
+  }
+
+  let processes;
+  try {
+    processes = await listProcesses();
+  } catch (error) {
+    diagnostics.push(`cannot verify saved CDP state against PowerShell CIM: ${error.message}`);
+    return {
+      status: "degraded",
+      detail: diagnostics.join("; "),
+    };
+  }
+
+  if (!processTableContainsState(processes, savedHealthy, resolvedProfile, platform)) {
+    diagnostics.push(`saved CDP state for pid=${savedHealthy.pid} could not be verified against the current process table`);
+    return {
+      status: "degraded",
+      detail: diagnostics.join("; "),
+    };
+  }
+
+  diagnostics.push(`saved CDP state is verified for pid=${savedHealthy.pid}`);
+  return {
+    status: "pass",
+    detail: diagnostics.join("; "),
+  };
+}
+
 export async function acquireCdpProfileLock(profileDir, {
   ownerPid = process.pid,
   isAlive = isProcessAlive,