Files

3.6 KiB
Raw Permalink Blame History

Windows 启动脚本交付审查发现

初始状态

  • 项目根目录存在 start.bat。
  • 根目录已有另一项已完成任务的计划文件,本次改用独立作用域,避免覆盖。
  • 工作区存在一个与本次审查无关的未跟踪 TODO CSV,不触碰。

入口与初步脚本审查

  • start.bat 是 20 行 ASCII DOS batch 文件,已使用 %~dp0 + cd /d,因此支持从其他工作目录启动,也支持项目位于不同盘符。
  • 脚本只检查 node,未独立检查 npm;标准 Node.js 安装通常同时提供 npm,但定制/损坏环境可能例外。
  • 仅在 node_modules 整个目录不存在时执行 npm install;目录存在但依赖缺失或 lockfile 已更新时不会补装。
  • npm install 后没有检查失败状态,即使依赖安装失败仍会继续执行 node server.js。
  • node server.js 退出后无论成功失败都会 pause,但没有明确显示退出码。
  • 仓库同时有 package-lock.json,面向别人交付时更适合 npm ci 做可复现的首次安装(前提是 lockfile 与 package.json 同步)。
  • README 中已把 start.bat 声明为 Windows 启动入口。

运行时与环境兼容性

  • package.json 的运行依赖只有纯 JavaScript 包 ws,没有需要 Windows 本机编译工具链的原生依赖。
  • 服务端已有 process.platform === 'win32' 分支:停止子进程时使用 taskkill,启动 Agent 子进程时禁用 Unix 的 detached 模式,说明核心服务明确考虑了 Windows。
  • 检索到的 /usr/bin/node、bash、ss 等 Unix 命令位于回归测试脚本或 mock 数据,不在 start.bat -> node server.js 的普通启动主链路上。
  • README 要求 Node.js >= 18,但 start.bat 只检查“能否找到 node”,没有检查版本,也没有检查 npm;这是交给非开发者使用时最明显的前置条件缺口。
  • 当前 WSL 环境没有 cmd.exe,不能在本机执行真实 Windows CMD 动态测试;后续只能做静态批处理核验和 Node 主链路验证,并明确标注这一限制。

关键 Windows 批处理问题

  • Windows 的 npm 命令通常由 npm.cmd 提供。
  • 在一个 .bat 中直接执行另一个 .bat/.cmd 而不使用 call,控制流不会可靠返回原脚本。
  • 当前第 15 行是 npm install,因此首次运行进入安装分支后,存在依赖装完却不继续执行第 18~19 行启动服务的确定性批处理兼容风险;常见表现是用户需要再次双击。
  • 交付版至少应改为 call npm ...,并在安装后用 if errorlevel 1 阻断失败路径。
  • 服务对 Claude/Codex 使用直接 spawn(command, args);Windows 全局 npm CLI 常见为 .cmd shim,完整 Agent 功能还应在真实 Windows 上做一次 CLI 拉起验收。这不影响 node server.js 自身启动,但属于交付验收边界。

验证结果

  • node --check server.js:通过。
  • node --check lib/agent-runtime.js:通过。
  • npm ls --depth=0:通过,当前运行依赖为 ws@8.19.0。
  • 使用隔离的配置、会话、日志目录在 18082 端口启动服务并请求首页:HTTP 成功,首页 10143 字节。
  • start.bat 当前为 ASCII + LF;现代 Windows CMD 可解析 LF,且 Windows Git 常会按 core.autocrlf 转换,因此不是主要阻断项。

交付边界

  • 收件人需安装 Node.js >= 18,且 node、npm 在 PATH 中。
  • 需要把完整源码运行目录一起交付,不能只发送 start.bat。
  • 要使用 Agent 功能,还需安装并登录 Claude Code 或 Codex CLI。
  • 不应把发送者自己的 .env、config/auth.json、sessions/、logs/ 一并打包,以免泄露密码和会话数据。