# cyac 故障诊断

本文档介绍如何使用 cyac 的 **diagnose** 命令进行 Bug 诊断，以及常见问题的排查方法。

---

## 一、diagnose 命令

`cyac diagnose` 用于分析错误日志与相关代码，由 AI 给出：

1. 错误原因
2. 问题定位
3. 修复方案
4. 修复后的代码

### 基本用法

```powershell
cyac diagnose --log <错误日志路径> [--path <代码路径>] [--apply]
```

**参数说明：**

| 参数 | 必填 | 说明 |
|------|------|------|
| `--log` | 是 | 错误日志文件路径 |
| `--path` | 否 | 相关代码文件路径。不指定时使用项目上下文 |
| `--apply` | 否 | 将 AI 给出的修复代码直接写入 `--path` 指定文件 |

### 使用示例

#### 1. 编译错误 + 指定代码文件

```powershell
# 将编译输出保存到文件
cargo build 2>&1 | Out-File -FilePath build_error.txt

# 诊断
cyac diagnose --log build_error.txt --path src/main.rs
```

#### 2. 运行时错误

```powershell
# 运行程序并将错误输出保存
.\myapp.exe 2>&1 | Out-File -FilePath runtime_error.log

# 诊断（指定出错模块）
cyac diagnose --log runtime_error.log --path src/module.rs
```

#### 3. 仅错误日志（使用项目上下文）

在项目目录下运行，cyac 会收集项目结构作为上下文：

```powershell
cd my_project
cyac diagnose --log error.txt
```

#### 4. 测试失败日志

```powershell
cargo test 2>&1 | Out-File -FilePath test_fail.txt
cyac diagnose --log test_fail.txt --path tests/integration_test.rs
```

#### 5. 自动应用修复（--apply）

诊断后若需直接写入修复代码，加 `--apply`：

```powershell
cyac diagnose --log build_error.txt --path src/main.rs --apply
```

AI 会从回复中提取最后一个代码块并写入 `--path` 指定文件。建议先用不带 `--apply` 的方式预览，确认无误后再使用。

---

## 二、诊断流程建议

1. **保存完整错误信息**：包含堆栈、行号、上下文
2. **指定相关代码**：用 `--path` 指向出错文件，提高准确度
3. **在项目目录运行**：若未指定 `--path`，会使用项目上下文

---

## 三、常见问题排查

### AI 后端不可用

**现象**：`❌ 未检测到 Ollama 服务` 或 `❌ 未检测到可用的 AI 后端`

**解决**：二选一

1. **Ollama**：安装 https://ollama.ai，启动 `ollama serve`，拉取 `ollama pull deepseek-coder`
2. **DeepSeek**：`cyac config set backends.deepseek_api_key sk-xxx` 或设置环境变量 `DEEPSEEK_API_KEY`

详见 [AI 后端多源](../features/11-AI后端多源.md)。

### 模型未拉取

**现象**：`model not found` 或类似错误

**解决**：

```powershell
ollama pull deepseek-coder
# 或
ollama pull qwen2.5-coder
```

### 无代码内容

**现象**：`无代码内容可解释，请指定文件或使用 --stdin`

**解决**：为 explain 或相关命令指定 `--path` 或使用 `--stdin` 传入内容。

### 路径不存在

**现象**：`No such file or directory`

**解决**：检查 `--path`、`--log` 指定的路径是否正确，可使用相对路径或绝对路径。

### save 权限

**现象**：`目标路径不在项目根下，禁止写入`

**解决**：`save` 命令只能写入 `--project` 指定的项目根目录下的文件，路径不能包含 `..`。

---

## 四、结合其他命令诊断

### 先解释再诊断

```powershell
# 1. 理解出错代码段
cyac explain src/main.rs:45-60

# 2. 诊断错误
cyac diagnose --log error.txt --path src/main.rs
```

### 用 chat 追问

```powershell
cyac chat "这段代码报错 'borrow of moved value'，如何修复？"
```

### 带项目上下文

```powershell
cyac chat --project ./myapp "运行时报 'connection refused'，可能是什么原因？"
```
