# Qiming Agent 启动前检查清单

适用于 **开发模式** 与 **打包运行**，按顺序执行可避免常见端口冲突与 native 模块错误。

**聚合实现**：端口定义与解析集中在 `src/shared/startupPorts.ts` 与 `src/main/services/startupPorts.ts`，启动时 ComputerServer / File Server 等均通过 `getConfiguredPorts()` 取端口；CLI 检查可运行 `npm run check-ports`（开发时加 Vite：`npm run check-ports:dev`）。**端口占用检查**：优先统一走 **bash** 执行 `scripts/tools/check-port.sh`（与 prepare-git 集成一致）：Windows 使用 prepare-git 集成的 Git Bash（`resources/git/bin/bash.exe`），macOS/Linux 使用系统 bash；无 bash 或脚本时回退到 Node 内联 netstat/lsof。

---

## 一、端口与服务的对应关系（以最终配置为准）

检查端口时应使用 **当前配置的端口**，而不是写死的默认值。各服务端口来源如下：

| 服务 | 说明 | 配置来源 | 默认端口 |
|------|------|----------|----------|
| **Agent（ComputerServer）** | /computer/* API，供后端与 lanproxy 隧道访问 | 设置 → step1 配置 → `agentPort`（存 SQLite `step1_config`） | 60001 |
| **File Server** | 本地文件服务、项目上传等 | 设置 → step1 配置 → `fileServerPort`（存 SQLite `step1_config`） | 60000 |
| **MCP Proxy** | MCP 服务统一入口 | 设置 → MCP → 代理端口（存 SQLite `mcp_proxy_port`） | 18099 |
| **Vite 开发服务器** | 仅开发模式，前端热更新 | `vite.config.ts` 的 `server.port` | 60173 |
| **Lanproxy** | 内网穿透客户端；连接远程 `server_port`，隧道落到本机 Agent 或本地代理端口 | 设置 → Lanproxy → 服务端端口（存 `lanproxy_config` / `lanproxy.server_port`，为**远程**端口）；**本地**端口依实现，常见与 Agent 一致或使用 60002（Agent Runner 代理默认） | 远程常 10076；本地 60002 |

- 若未在应用内改过端口，则按上表**默认端口**检查即可。
- 若改过端口，请以**设置页或下面「获取当前配置端口」**得到的值为准。

---

## 二、获取当前配置端口（可选）

**方式一：应用内**  
打开 Qiming Agent → 设置 → 查看「Agent 端口 / 后端端口」「File Server 端口」「MCP 代理端口」「Lanproxy 服务端端口」（远程）及本地代理相关端口（若可见）。开发时 Vite 端口见项目根下 `vite.config.ts`。

**方式二：从 SQLite 读取（应用未运行时）**

```bash
DB="$HOME/.qimingclaw/qimingclaw.db"

# step1_config 内含 agentPort、fileServerPort（JSON）
sqlite3 "$DB" "SELECT value FROM settings WHERE key='step1_config';"

# MCP 代理端口（单独键）
sqlite3 "$DB" "SELECT value FROM settings WHERE key='mcp_proxy_port';"

# Lanproxy 远程服务端端口（lanproxy_config 或 lanproxy.server_port）
sqlite3 "$DB" "SELECT value FROM settings WHERE key='lanproxy_config';"
sqlite3 "$DB" "SELECT value FROM settings WHERE key='lanproxy.server_port';"
```

解析 `step1_config` 的 JSON 可得 `agentPort`、`fileServerPort`；`mcp_proxy_port` 无则表示用默认 18099。Lanproxy 本地检查端口通常用默认 60002（与 Agent Runner 代理端口一致）。

---

## 三、快速检查（按配置端口执行）

确认上述**实际使用的端口**未被占用（无输出表示端口空闲）：

```bash
# 替换为你的实际端口（未改过则用默认）
AGENT_PORT=60001       # Agent / ComputerServer
FILE_SERVER_PORT=60000
MCP_PROXY_PORT=18099
LANPROXY_LOCAL_PORT=60002   # Lanproxy 相关本地端口（如 Agent Runner 代理）
VITE_PORT=60173        # 仅开发模式需要

lsof -i :$AGENT_PORT
lsof -i :$FILE_SERVER_PORT
lsof -i :$MCP_PROXY_PORT
lsof -i :$LANPROXY_LOCAL_PORT
# 开发时追加：
# lsof -i :$VITE_PORT
```

若某端口有输出，说明已被占用，需先结束占用进程或只保留一个 Agent 实例。

**一键检查（推荐，与应用内聚合逻辑一致）：**

```bash
# 从 ~/.qimingclaw/qimingclaw.db 读配置并检查占用（需系统有 sqlite3）
npm run check-ports
# 开发模式含 Vite 端口
npm run check-ports:dev
```

**或手动从 SQLite 读取后检查（需已安装 sqlite3）：**

```bash
DB="$HOME/.qimingclaw/qimingclaw.db"
get_port() { sqlite3 "$DB" "SELECT value FROM settings WHERE key='$1';" 2>/dev/null; }
step1=$(get_port 'step1_config')
agent_port=$(echo "$step1" | sed -n 's/.*"agentPort":\([0-9]*\).*/\1/p'); agent_port=${agent_port:-60001}
file_port=$(echo "$step1" | sed -n 's/.*"fileServerPort":\([0-9]*\).*/\1/p'); file_port=${file_port:-60000}
mcp_port=$(get_port 'mcp_proxy_port'); mcp_port=${mcp_port:-18099}
lanproxy_local_port=60002   # Lanproxy 相关本地端口，默认 60002

echo "检查端口: Agent=$agent_port FileServer=$file_port MCP=$mcp_port Lanproxy本地=$lanproxy_local_port (Vite=60173 仅开发)"
for p in $agent_port $file_port $mcp_port $lanproxy_local_port; do
  lsof -i :$p 2>/dev/null && echo "  -> 端口 $p 已被占用"
done
```

---

## 四、端口被占用时的处理步骤

### 1. 查看占用进程

```bash
# 替换 <PORT> 为实际端口号（以「一」中配置为准），例如 60001
lsof -i :<PORT>
```

示例输出：
```
COMMAND   PID  USER   FD   TYPE  DEVICE  SIZE/OFF  NODE  NAME
Electron  123  apple  23u  IPv4  xxx     0t0      TCP  *:60001 (LISTEN)
```

记下 **PID**（第二列）。

### 2. 结束占用进程

```bash
# 替换 123 为上面看到的 PID
kill 123
```

若进程无法结束，可强制结束：
```bash
kill -9 123
```

### 3. 一次性释放 Agent / File Server / MCP / Vite 端口（谨慎使用）

以下会结束占用**当前配置端口**的进程。若你未改过端口，可直接运行；若改过，请先把 `agent_port`、`file_port`、`mcp_port`、`lanproxy_local_port`、`vite_port` 改成你在设置里配置的值，并确认没有其他重要服务使用这些端口：

```bash
# 使用默认端口示例；若已修改，请改为你配置的端口
agent_port=60001
file_port=60000
mcp_port=18099
lanproxy_local_port=60002   # Lanproxy 相关本地端口
vite_port=60173            # 仅开发模式需要

for port in $agent_port $file_port $mcp_port $lanproxy_local_port $vite_port; do
  pid=$(lsof -t -i :$port 2>/dev/null)
  [ -n "$pid" ] && echo "Killing PID $pid (port $port)" && kill $pid
done
```

---

## 五、开发模式启动流程

在项目根目录或 `crates/agent-electron-client` 下执行：

```bash
cd /Users/apple/workspace/qiming-agent/crates/agent-electron-client

# 1. 安装依赖（首次或 package.json 变更后）
npm install

# 2. 若曾出现 better-sqlite3 与 Electron Node 版本不匹配，先重建 native 模块
npx @electron/rebuild

# 3. 启动开发环境（Vite + Electron）
npm run dev
```

**开发模式注意：**

- 若 Vite 报错 `Port 60173 is already in use`，说明上次 dev 未完全退出。先执行「四、端口被占用时的处理步骤」释放 Vite 配置端口（默认 60173），或执行「四」中的「一次性释放」脚本后再 `npm run dev`。
- 确保只运行一个 `npm run dev`，避免多开导致 Agent / File Server / MCP 端口冲突。

---

## 六、打包后运行（正式/测试包）

1. **完全退出已有实例**  
   从菜单退出并确认托盘图标已消失，避免 Agent / File Server / MCP 等配置端口被旧进程占用。

2. **首次运行或更换 Electron/Node 后**  
   若出现「Database initialization failed」且与 better-sqlite3 相关，在**开发目录**执行一次：
   ```bash
   cd crates/agent-electron-client && npx @electron/rebuild
   ```
   然后重新打包再运行。

3. **启动应用**  
   直接打开打包好的应用即可；无需再执行 npm。

---

## 七、API 连接失败（UND_ERR_SOCKET）时

日志中出现 `Unable to connect to API (UND_ERR_SOCKET)` 时，表示引擎无法连上配置的模型 API，请依次检查：

| 检查项 | 说明 |
|--------|------|
| 网络 | 本机能否访问外网或企业代理（如用代理，确认代理可用）。 |
| Base URL | 设置中的 API Base URL 是否正确（含协议与端口）。 |
| 防火墙/安全软件 | 是否拦截了 Electron 或 Node 的出站连接。 |
| 本地验证 | 在终端用 `curl -I <你的 Base URL>` 或浏览器访问，确认可达。 |

---

## 八、检查清单小结（可打印或保存）

- [ ] 以**当前配置端口**检查：Agent（ComputerServer）、File Server、MCP Proxy、Lanproxy 相关本地端口（默认 60002）及开发时 Vite 无冲突或已释放（参见「一」「三」）
- [ ] 只保留一个 Qiming Agent 进程（含托盘）
- [ ] 开发模式：已执行 `npm install`，必要时执行 `npx @electron/rebuild`
- [ ] 设置中已配置默认模型和 API Key（避免依赖内置默认）
- [ ] 启动后语言初始化正常：`navigator.language`（如 `en-US` / `zh-TW`）能命中期望语言；`zh-TW` / `zh-HK` 的 antd 组件文案为繁体；主进程托盘文案与页面语言一致
- [ ] 若需内网穿透：Lanproxy 服务端与网络正常，且本地 Lanproxy/Agent Runner 所用端口（如 60002）无冲突；否则可忽略 Lanproxy 相关告警
- [ ] 出现 API 连接错误时，已按「七」检查网络与 Base URL

---

*文档依据 `~/.qimingclaw/logs/latest.log` 常见错误整理，最后更新：2026-04-08*