# cyac 常见问题

本文档汇总用户常见问题与解答。

---

## 安装与运行

### Q：cyac --help 提示「不是内部或外部命令」

**A**：cyac 未加入 PATH。请重新运行 `install.bat`，或手动将 cyac.exe 所在目录加入系统环境变量 PATH。

### Q：提示「未检测到 Ollama 服务」或「未检测到可用的 AI 后端」

**A**：二选一即可：

**方式 1：安装 Ollama（本地优先）**
1. 访问 https://ollama.ai 下载安装
2. 启动 Ollama（通常安装后自动启动，可在系统托盘查看）
3. 拉取模型：`ollama pull deepseek-coder`

**方式 2：配置 DeepSeek API Key（无本地环境时）**
- `cyac config set backends.deepseek_api_key sk-xxx`
- 或设置环境变量 `DEEPSEEK_API_KEY`

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

### Q：模型拉取很慢

**A**：首次拉取需下载模型文件，体积较大。可尝试使用代理或选择较小的模型（如 `qwen2.5-coder:1.5b`）。

---

## 命令使用

### Q：explain 提示「无代码内容可解释」

**A**：需指定代码来源，任选其一：

- `cyac explain src/main.rs`（指定文件）
- **剪贴板**：编辑器中选中代码复制后，`Get-Clipboard | cyac explain --stdin`（Windows）
- 管道：`Get-Content file.rs | cyac explain --stdin`
- 确保文件路径正确且文件存在

### Q：如何让 AI 着重解释某一行？

**A**：使用 `--focus-line N`，AI 会着重解释第 N 行及其附近逻辑。适合编辑器集成传入光标行：`cyac explain src/main.rs --focus-line 42`

### Q：refactor 的结果如何应用到文件？

**A**：加 `--apply` 可直接写入：`cyac refactor rename --old foo --new bar --path src/lib.rs --apply`。diagnose 同理：`cyac diagnose --log 日志 --path 代码 --apply`。

### Q：save 提示「目标路径不在项目根下」

**A**：`save` 只能写入 `--project` 指定的项目根目录下的文件。路径不能包含 `..`，禁止写入项目外。

### Q：init 和 config set 有什么区别？

**A**：

- `cyac init`：在当前目录创建 `.cyac/config.yaml`，用于**项目级**配置
- `cyac config set`：修改**全局**配置（`~/.config/cyac/config.yaml`）

---

## 功能相关

### Q：--stream 和默认模式有什么区别？

**A**：`--stream` 会边生成边输出，适合长响应；默认模式等待完整响应后一次性输出。

### Q：MCP 工具如何配置？

**A**：在 `~/.config/cyac/config.yaml` 或 `~/.config/cyac/mcp.json` 中配置 `mcp.servers`。详见 [docs/features/02-MCP工具.md](../features/02-MCP工具.md)。本地 MCP 优先，`--no-network` 可禁用联网 MCP。

### Q：如何获取和配置 BRAVE_API_KEY（search_web 联网搜索）？

**A**：`search_web` 使用 Brave Search API。获取步骤：

1. 访问 [Brave Search API 注册](https://api-dashboard.search.brave.com/register) 注册账号
2. 订阅计划后，在 [API Keys](https://api-dashboard.search.brave.com/app/keys) 创建 Key
3. 配置方式（任选其一）：
   - **推荐**：`cyac config set brave_api_key 你的Key`
   - 环境变量：`BRAVE_API_KEY=你的Key`
   - 配置文件：在 `~/.config/cyac/config.yaml` 添加 `tools.brave_api_key: "你的Key"`

完整说明见 [docs/features/07-Brave-Search-API.md](../features/07-Brave-Search-API.md)。

### Q：如何开启写入后自动 git commit？

**A**：`cyac config set auto_commit true`。开启后，refactor/diagnose/explain/generate 的 `--apply` 写入、REPL 中 `save`、`chat --tools` 的 `write_file` 都会自动执行 `git add` + `git commit`。需在 git 仓库内。详见 [08-Git-自动Commit.md](../features/08-Git-自动Commit.md)。

### Q：@ 文件引用怎么用？

**A**：在 chat 或 repl 的问题中用 `@path` 引用项目内文件，AI 会自动读取并注入上下文。例如：`cyac chat "请解释 @src/main.rs 的核心逻辑"`。explain 也支持 `cyac explain @src/main.rs`。详见 [12-At文件引用.md](../features/12-At文件引用.md)。

### Q：run_command 执行前如何确认？

**A**：配置 `cyac config set tools.confirm_before_run_command true` 后，模型调用 run_command 时会在执行前提示用户确认。适用于需要更高安全性的场景。详见 [13-run_command执行确认.md](../features/13-run_command执行确认.md)。

### Q：--tools 是什么？需要什么模型？

**A**：`--tools` 启用 Tool Calling，模型可主动调用 read_file、list_dir、write_file、run_command、search_web 等工具。需使用支持工具调用的模型，如 Qwen3（`ollama pull qwen3`）、Llama 3.1、DeepSeek-V3.1 等。search_web 需额外配置 BRAVE_API_KEY。

### Q：--dry-run 有什么用？

**A**：`--dry-run` 使命令仅预览不写入，防止意外修改。适用于 refactor 和 session 中的 save。

### Q：审计日志在哪里？

**A**：`~/.config/cyac/audit.log`（或 `%APPDATA%\cyac\audit.log`）。记录所有 write 操作，便于追溯。

### Q：如何回滚误保存的文件？

**A**：若启用了 `auto_save_backup`，覆盖前会备份为 `原文件名.cyac.bak`，可手动恢复。

---

## 故障排除

### Q：cargo build 出现「error finalizing incremental compilation session directory ... 拒绝访问。(os error 5)」

**A**：这是 Rust 增量编译在 Windows 下的常见警告，**不影响编译结果**，可忽略。

**原因**：杀毒软件、OneDrive 等可能锁定 `target` 目录，导致编译器无法正确清理增量缓存。

**可选处理方式**：

| 方式 | 说明 |
|------|------|
| 关闭增量编译 | 在项目根目录创建 `.cargo/config.toml`，写入 `[build]` 和 `incremental = false`，可消除警告（编译可能略慢） |
| 排除杀毒扫描 | 在杀毒软件中将 `target` 目录加入排除列表 |
| 避免云盘同步 | 将项目移到非 OneDrive 等云盘同步的目录 |

**示例**（关闭增量编译）：

```toml
# .cargo/config.toml
[build]
incremental = false
```

---

## 其他

### Q：支持哪些编程语言？

**A**：cyac 支持常见语言：Rust、Python、JavaScript/TypeScript、Go、C#、SQL、Shell 等。explain、generate 等命令通过 `--lang` 或文件扩展名识别。

### Q：可以离线使用吗？

**A**：使用 Ollama 时，模型拉取后即可离线使用。使用 DeepSeek API 时需联网。

### Q：企业如何使用？

**A**：请访问官网 cy.ac.cn 的「企业使用」页面，通过表单联系我们。
