# 故障排查

## 找不到模型

现象：

```text
Warning: No models available.
```

处理：

```text
/login
/model
```

或设置供应商 API Key：

```powershell
$env:OPENAI_API_KEY="sk-..."
kcode start
```

## 产品一直是未确认

查看状态：

```text
/kd status
```

确认产品：

```text
/kd product cangqiong --version V6.0
/kd check
```

产品无法判断时，查看 [产品画像确认](PRODUCT_PROFILE.md)。

## ship 阶段门禁阻塞

常见原因：

- 产品画像未确认。
- 风险等级或风险原因未知。
- 缺少 `SHIP.md` 必需章节。
- 缺少 evidence 文件。
- evidence 文件未登记到 `evidence/index.json`。
- KSQL/SQL 交付缺少元数据或 lint 证据。

常用命令：

```text
/kd status
/kd check
/kd risk low 已完成验证，无残余交付风险
```

## 仍然加载旧版本 KCode

检查当前版本：

```powershell
kcode version
```

检查项目配置：

```powershell
type .pi\settings.json
```

`packages` 中存在多条 `kcode-pi` 路径时，`kcode` 启动时会自动清理旧路径。

使用 nvm 时，Windows 上每个 Node 版本都有独立全局 npm 安装目录。切换 Node 后重新安装：

```powershell
npm install -g kcode-pi@latest
```

安装后直接运行 `kcode` 即可自动初始化。

## npm install 没有更新

确认 registry 上的版本：

```powershell
npm view kcode-pi version
npm view kcode-pi versions --json
```

必要时重装：

```powershell
npm uninstall -g kcode-pi
npm install -g kcode-pi@latest
kcode version
```

出现 `EEXIST: file already exists ... kcode.cmd` 时，确认旧 shim：

```powershell
npm root -g
where kcode
```

删除旧 `kcode.cmd`、`kcode.ps1` 后重装。

## Windows 下出现 /mnt/d 路径

现象：

```text
read /mnt/d/projects/xxx/src/main/java/Foo.java
ENOENT: no such file or directory, access 'D:\mnt\d\projects\xxx\src\main\java\Foo.java'
```

原因是当前运行环境是 Windows，但路径被写成了 WSL/MSYS 风格。

正确做法：

- 默认使用项目相对路径。
- 必须用绝对路径时，使用 `D:\projects\xxx\...`。
- 禁止使用 `/mnt/d/...` 或 `/d/...`。

刷新项目上下文：

```powershell
kcode ctx --refresh
```

## Windows 下 bash 工具一直搜索 Git Bash

现象：

```text
Searched Git Bash in:
  C:\Program Files\Git\bin\bash.exe
  C:\Program Files (x86)\Git\bin\bash.exe
```

原因是 Pi 内置 `bash` 工具在 Windows 上要求 Git Bash、Cygwin 或 MSYS2。KCode 在 Windows 下会覆盖该工具为 PowerShell，并提供 `kd_find_file`、`kd_list_dir` 用于文件查找和目录探索。

处理：

```powershell
kcode repair
kcode check --deep
kcode start
```

在 KCode 会话中查找文件时使用：

```text
kd_find_file name=MesApiClient.cs root=C:\Users\Administrator\Desktop\lf-project
kd_list_dir path=C:\Users\Administrator\Desktop\lf-project
```

如果需要 Pi 原生 bash 行为，安装 Git for Windows 后重新运行：

```powershell
kcode check --deep
```