3.6 KiB
3.6 KiB
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 常见为.cmdshim,完整 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/一并打包,以免泄露密码和会话数据。