49 lines
3.6 KiB
Markdown
49 lines
3.6 KiB
Markdown
# 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/` 一并打包，以免泄露密码和会话数据。
|