chore: initialize qiming workspace repository
This commit is contained in:
Codex
@@ -0,0 +1,112 @@
|
||||
# Deepcheck：启动端口与统一 Bash 实现
|
||||
|
||||
## 1. 实现范围
|
||||
|
||||
- **shared/startupPorts.ts**：端口默认值、配置键、`resolvePortsFromSettings(getSetting)`、`getPortsToCheck(ports, includeVite)`
|
||||
- **main/services/startupPorts.ts**：`getConfiguredPorts()`、`getPortList()`、`checkPortsInUse()`、`isPortInUse()`（bash 优先，Windows 回退 cmd+netstat）
|
||||
- **scripts/tools/check-port.sh**：单端口占用检查（netstat/lsof），供 bash 执行
|
||||
- **scripts/tools/check-startup-ports.js**：CLI，读 DB、解析端口、调用 bash+check-port.sh 或回退 Node 内联
|
||||
|
||||
---
|
||||
|
||||
## 2. 正确性
|
||||
|
||||
### 2.1 三处脚本逻辑一致性
|
||||
|
||||
| 位置 | 来源 | 端口参数 | Windows 分支 | Unix 分支 | 输出/exit |
|
||||
|------|------|----------|--------------|-----------|-----------|
|
||||
| **check-port.sh** | 文件 | `$1` | cmd //c "netstat -ano \| findstr \":${port} \"" | lsof -t -i ":${port}" | 占用: exit 0 + echo PID；未占用: exit 1 |
|
||||
| **main CHECK_PORT_SCRIPT** | 内嵌字符串 | `$1` | 同上（\\":$1 \\" 在 JS 中产生 \":$1 \"） | lsof -t -i ":$1" | 同左 |
|
||||
| **脚本** | 读 check-port.sh | spawnSync(..., '_', port) | 由 .sh 决定 | 由 .sh 决定 | 同左 |
|
||||
|
||||
- **结论**：.sh 与内嵌脚本语义一致；端口均通过 `$1` 传入，无注入（端口为数字的 String(port)）。
|
||||
- **已修复**：CLI 原先用 `execSync(bashPath, [args], options)`，Node 的 `execSync` 仅支持 `(command, options)`，第二个参数被当成 options，导致 bash 未按参数执行。已改为 `spawnSync(bashPath, ['-c', scriptContent, '_', String(port)], options)`。
|
||||
|
||||
### 2.2 配置解析（shared + 脚本）
|
||||
|
||||
- **step1_config**：`step1?.agentPort ?? default`、`step1?.fileServerPort ?? default`。若 DB 存的是 `{}` 或缺失，则用默认值；若 `agentPort: 0`，会得到 0（端口 0 在部分系统上表示“任选”，可能不符合预期，见 4.1）。
|
||||
- **mcp_proxy_port**：兼容 number 与 string；`parseInt` 失败或非整数时用默认值。
|
||||
- **脚本 DEFAULTS**：与 shared/constants 数值一致，需人工与 shared 同步（见 4.2）。
|
||||
|
||||
### 2.3 端口占用结果
|
||||
|
||||
- **spawnSync**：`status === 0` 表示脚本 exit 0（端口占用）；stdout 取首行/最后一列解析 PID；空 stdout 时 `inUse: true, pid: undefined`，行为合理。
|
||||
- **回退路径**（Windows 无 bash / 脚本无 .sh）：main 用 `execSync` + cmd；脚本用 `execSync` + shell: true（或 lsof），行为与之前一致。
|
||||
|
||||
---
|
||||
|
||||
## 3. 平台与环境
|
||||
|
||||
### 3.1 Windows
|
||||
|
||||
- **有 prepare-git**：`getBundledGitBashPath()` 返回 `resources/git/bin/bash.exe`（或 usr/bin），main 与 CLI 均用该 bash 执行脚本；脚本内 `OSTYPE=msys*`，走 cmd+netstat+findstr，一致。
|
||||
- **无 prepare-git**：main 回退 cmd+netstat；脚本 `winBashPath` 不存在则回退 Node netstat，逻辑一致。
|
||||
- **路径**：DB 路径 `%USERPROFILE%\.qimingclaw\`；脚本中 sqlite3 路径用正斜杠归一化，避免反斜杠转义问题。
|
||||
|
||||
### 3.2 macOS / Linux
|
||||
|
||||
- main 与脚本均用系统 `bash`；脚本来自文件或内嵌，均包含 `$OSTYPE` 判断，非 msys/cygwin 走 lsof。
|
||||
- **无 bash**（如 Alpine 仅 ash）：`spawnSync('bash', ...)` 会失败，当前实现将 `status !== 0` 视为未占用并返回 `inUse: false`，属保守回退，可接受；若需严格“未知”可再区分 error/status。
|
||||
|
||||
### 3.3 check-port.sh 被读入后的执行
|
||||
|
||||
- 通过 `bash -c "<scriptContent>"` 执行时，首行 `#!/usr/bin/env bash` 被当作注释（`#` 起头），不影响执行，无需 strip。
|
||||
|
||||
---
|
||||
|
||||
## 4. 边界与改进建议
|
||||
|
||||
### 4.1 端口合法性
|
||||
|
||||
- 当前未校验端口范围（1–65535）及 0。若配置了 `agentPort: 0` 或错误大数，会直接传给 `startComputerServer`/lsof/netstat。
|
||||
- **建议**：在 `resolvePortsFromSettings` 或调用方对端口做范围校验，非法时回退默认或报错。
|
||||
|
||||
### 4.2 脚本与 shared 同步
|
||||
|
||||
- **check-startup-ports.js** 的 DEFAULTS/LABELS 与 shared/constants、shared/startupPorts 需人工同步；脚本无法 require 编译后的 shared。
|
||||
- **建议**：在脚本顶部注释中写明“与 shared/startupPorts.ts、constants 保持一致”；或考虑 build 时生成一份 ports-defaults.json 供脚本读取（可选）。
|
||||
|
||||
### 4.3 错误与超时
|
||||
|
||||
- `spawnSync` 未设 timeout；若 bash 或子命令卡住会阻塞。
|
||||
- **建议**：若需在 UI 或敏感路径调用，可加 `timeout` 选项或异步封装。
|
||||
|
||||
### 4.4 安全性
|
||||
|
||||
- 端口来自配置或常量，`String(port)` 后传入 spawn，无用户自由输入，无命令注入风险；脚本内 `$1` 仅用于端口，且由调用方控制。
|
||||
- sqlite3 的 key 做单引号转义，key 来自内部常量，风险可控。
|
||||
|
||||
---
|
||||
|
||||
## 5. 调用链与依赖
|
||||
|
||||
- **startup.ts**：`getConfiguredPorts().agent` → ComputerServer 端口。
|
||||
- **serviceManager.ts**：`getConfiguredPorts().fileServer` → File Server 端口。
|
||||
- **processHandlers.ts**：动态 import `getConfiguredPorts`，取 `fileServer` → 重启时的 File Server 端口。
|
||||
- **dependencies.ts**：导出 `getBundledGitBashPath()`，供 main startupPorts 使用；prepare-git 仅 Windows 下载并解压 Git 到 `resources/git/`。
|
||||
|
||||
---
|
||||
|
||||
## 6. 测试建议
|
||||
|
||||
- **单元**：`resolvePortsFromSettings` 用 mock getSetting 测默认值、step1 部分键、mcp 为 number/string/非法。
|
||||
- **集成**：在 macOS 上运行 `npm run check-ports` 与 `npm run check-ports:dev`，确认有 bash + check-port.sh 时输出与 exit code 正确；关闭应用后再次检查，确认“未占用”与 exit 0。
|
||||
- **Windows**：在装有 prepare-git 与未装两种情况下各跑一次 CLI，确认有 bash 时走脚本、无时走 netstat 回退。
|
||||
|
||||
---
|
||||
|
||||
## 7. 小结
|
||||
|
||||
| 项 | 状态 |
|
||||
|----|------|
|
||||
| 三处脚本逻辑一致（.sh / 内嵌 / CLI 调用方式） | ✅ 一致 |
|
||||
| CLI 使用 spawnSync 传参（原 execSync 误用已修复） | ✅ 已修复 |
|
||||
| 配置解析与默认值 | ✅ 合理，0 与范围未校验见 4.1 |
|
||||
| Windows 有/无 bash 回退 | ✅ 正确 |
|
||||
| Unix 使用 bash，无 bash 时保守回退 | ✅ 可接受 |
|
||||
| 安全与注入 | ✅ 端口与 key 受控 |
|
||||
| 改进点 | 端口范围校验、DEFAULTS 同步方式、可选 timeout |
|
||||
|
||||
---
|
||||
|
||||
*Deepcheck 完成；CLI 中 execSync 误用已改为 spawnSync。*
|
||||
Reference in New Issue
Block a user