# cyac 高级用法

本文档介绍 cyac 的高级功能：@ 文件引用、流式输出、--dry-run、自动应用修改、跨文件引用、操作审计等。

---

## 一、@ 文件引用

在 `chat`、`repl` 和 `explain` 中，可使用 `@path` 语法引用项目内文件，AI 会自动读取并注入到上下文。若 `@path` 指向图片（png/jpg/gif/webp/bmp），会作为图片传入（仅 chat、repl；需 vision 模型）。chat 还支持 `--image <path>` 显式传入图片。

```powershell
cyac chat "请解释 @src/main.rs 的核心逻辑"
cyac chat "根据 @config.toml 和 @Cargo.toml 总结项目配置"
cyac chat --image screenshot.png "描述这张图"
cyac chat "@diagram.png 解释这个架构图"
cyac explain @src/lib.rs
```

详见 [12-At文件引用.md](../features/12-At文件引用.md)、[14-图片支持.md](../features/14-图片支持.md)。

---

## 二、自动应用修改（--apply / --output）

refactor、diagnose、generate 支持将 AI 输出**直接写入文件**，无需手动复制。

### refactor --apply

```powershell
cyac refactor rename --old foo --new bar --path src/lib.rs --apply
cyac refactor extract --lines 25-40 --name helper --path src/main.rs --apply
```

### 多文件批量修改

`--path` 为目录时，会搜索包含旧名的所有代码文件并逐个重构：

```powershell
cyac refactor rename --old legacy_api --new new_api --path src/ --apply
```

### diagnose --apply

将 AI 给出的修复代码直接写入 `--path` 指定文件：

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

### generate --output

将生成的代码直接写入指定文件：

```powershell
cyac generate function --desc "解析 YAML" --lang python -o src/config.py
```

---

## 三、跨文件引用

指定 `--project` 且操作文件时，cyac 会解析 import/use/mod 等语句，自动收集相关文件内容作为上下文。

**支持语言**：Rust（use、mod）、Python（from、import）、JavaScript/TypeScript（import、require）

**效果**：AI 能同时看到当前文件及其依赖的定义，提高解释、重构、诊断的准确度。

---

## 四、流式输出

对于 `chat` 和 `explain`，长时间等待时可通过 `--stream` 实时查看生成内容。

### 使用场景

- 模型响应较慢时，避免长时间等待
- 需要边生成边阅读的场景
- 调试或验证 prompt 效果

### 用法

```powershell
cyac chat --stream "写一个快速排序算法"
cyac explain src/main.rs --stream
```

### 与非流式对比

| 模式 | 行为 |
|------|------|
| 默认 | 等待完整响应后一次性输出 |
| `--stream` | 边生成边输出，实时显示 |

---

## 五、--dry-run 安全模式

`--dry-run` 为全局选项，使命令**仅预览不写入**，防止意外修改文件。

### 适用命令

| 命令 | 效果 |
|------|------|
| `refactor` | 输出重构结果，标注 `[--dry-run]`，不实际修改 |
| `session start` | REPL 中 `save` 仅预览，不写入 |
| `diagnose --apply` | 不写入修复代码 |

### 用法

```powershell
cyac --dry-run refactor rename --old foo --new bar --path src/lib.rs
cyac --dry-run session start --project ./
# 会话中 save 时：仅显示 [--dry-run] 将保存到 xxx (未实际写入)
```

### 使用建议

- 首次尝试重构时，先加 `--dry-run` 查看结果
- 在重要项目上谨慎使用 save 时，可先 `--dry-run` 验证

---

## 六、操作审计

cyac 会记录 AI 的**写入操作**，便于追溯与回滚。

### 审计日志位置

- Windows：`%APPDATA%\cyac\audit.log`
- 或：`%USERPROFILE%\.config\cyac\audit.log`
- 或：`~/.config/cyac/audit.log`

### 日志格式

```
时间戳 | 操作 | 文件路径 | 备份路径
```

- **操作**：如 `write`
- **备份路径**：若启用 `auto_save_backup` 且文件已存在，会先备份为 `.cyac.bak`

### 自动备份

配置 `features.auto_save_backup: true`（默认开启）时，会话中 `save` 覆盖已有文件前会先备份：

- 备份文件：`原文件名.cyac.bak`
- 示例：`main.rs` → `main.rs.cyac.bak`

### 回滚

若需回滚，可手动将 `.cyac.bak` 文件恢复为原文件名。

---

## 七、search 代码库搜索

按关键词在代码库中查找相关代码：

```powershell
cyac search "parse_config"
cyac s "error handling" -p src/ -c 3
cyac search "async" --lang rs
```

| 选项 | 说明 |
|------|------|
| `--path` / `-p` | 限定搜索路径 |
| `--lang` | 限定扩展名（rs、py、ts 等） |
| `-c` / `--context` | 匹配行上下文行数 |

---

## 八、项目记忆与 Skill

### 项目记忆

记忆存储在 `memory/` 下，供 explain、chat、REPL 等命令自动注入到 prompt，解决跨会话失忆。

```powershell
cyac memory log "技术决策：使用 Rust 实现"
cyac memory show
cyac memory set "项目规范：函数命名采用 snake_case"
cyac memory refine --days 7   # 将近期 Daily 提炼为 Global（需 AI 后端）
```

| 层级 | 路径 | 用途 |
|------|------|------|
| 项目记忆 | `memory/agents/default/memory.md` | 技术决策、规范、已知问题 |
| Daily | `memory/daily/YYYY-MM-DD.md` | 每日工作轨迹 |
| Global | `memory/global/MEMORY.md` | 长期知识库（可选） |

### 编程 Skill

Skill 通过触发词增强 AI 行为，explain、chat、refactor、diagnose、test、doc 等命令均支持。

```powershell
cyac skills list
cyac skills install https://github.com/user/cyac-skill-xxx
cyac skills upgrade
cyac skills disable <name>   # 临时禁用冲突或实验性 Skill
cyac skills enable <name>    # 恢复
```

- **自研**：在 `.cyac/skills/<name>/SKILL.md` 或 `~/.config/cyac/skills/<name>/SKILL.md` 创建
- **社区**：从 [uskill.cn](https://www.uskill.cn/) 获取，`cyac skills install <url>` 安装

---

## 九、多角色配置（--agent）

通过 `--agent <id>` 切换角色，不同角色有独立的 system_prompt 与记忆路径。

### 配置

在 `~/.config/cyac/config.yaml` 或 `.cyac/config.yaml` 中添加：

```yaml
agents:
  - id: doc
    system_prompt: "你是文档专家，专注于生成清晰的技术文档..."
  - id: code
    system_prompt: "你是代码专家，擅长重构与优化..."
```

### 使用

```powershell
cyac --agent doc explain src/main.rs
cyac --agent doc chat "如何写 API 文档？"
cyac --agent code refactor rename --old foo --new bar --path src/lib.rs
```

chat、explain、repl、refactor、test、doc、diagnose 等命令均支持 `--agent`。记忆从 `memory/agents/<id>/memory.md` 加载。

---

## 十、Tool Calling（--tools）

启用 `--tools` 后，模型可主动调用工具读取/写入项目文件，适合「让 AI 自己看代码再回答」的场景。

### 工具优先级（L1 → L2 → L3）

| 层级 | 说明 | 示例 |
|------|------|------|
| L1 内置 | cyac 直接实现 | read_file、list_dir、write_file |
| L2 本地 MCP | 连接本地 MCP 服务器 | filesystem、sqlite、git |
| L3 联网 MCP | 连接需网络的 MCP（HTTP） | brave-search、自定义 API |

### 内置工具

| 工具 | 说明 |
|------|------|
| read_file | 读取项目内指定路径的文件内容 |
| list_dir | 列出项目内目录下的文件和子目录 |
| write_file | 将内容写入项目内指定路径的文件 |
| run_command | 在项目目录执行白名单命令（cargo、npm、git 等） |
| search_web | 联网搜索（需配置 BRAVE_API_KEY，[获取与配置指南](../features/07-Brave-Search-API.md)） |

### 使用

```powershell
cyac chat --tools "列出 src 目录下的文件"
cyac chat --tools "读取 src/main.rs 并解释入口函数的逻辑"
cyac -p ./myapp chat --tools "在 src 下创建 config.rs 并写入基础配置"
cyac chat --tools --no-network "读取 README.md"   # 仅本地工具，禁用 search_web 与联网 MCP
cyac chat --tools "搜索 Rust 2024 新特性"         # 需配置 BRAVE_API_KEY
cyac chat --tools "运行 cargo build 并检查结果"   # run_command
```

### MCP 配置

在 `~/.config/cyac/config.yaml` 或 `mcp.json` 中配置 MCP 服务器。详见 [docs/features/02-MCP工具.md](../features/02-MCP工具.md)。

**run_command 执行前确认**：配置 `tools.confirm_before_run_command: true` 后，每次执行 run_command 前会提示用户确认，适用于需要更高安全性的场景。

**注意**：需使用支持工具调用的模型，如 Qwen3、Llama 3.1、DeepSeek-V3.1 等。路径限制在项目目录内，禁止 `..` 穿越。

---

## 十一、Git 自动 Commit

当 `features.auto_commit` 开启时，cyac 在写入文件后会自动执行 `git add` + `git commit`，便于追踪 AI 修改历史。

### 启用

```powershell
cyac config set auto_commit true
```

或编辑 `~/.config/cyac/config.yaml`：

```yaml
features:
  auto_commit: true
```

### 生效场景

| 命令/场景 | 说明 |
|----------|------|
| `refactor --apply` | 重构写入后 |
| `diagnose --apply` | 诊断修复写入后 |
| `explain --apply` | 解释写入文件后 |
| `generate --output` | 生成代码写入后 |
| REPL 中 `save <path>` | 保存到文件后 |
| `chat --tools` 中 `write_file` | 模型写入文件后 |

详见 [08-Git-自动Commit.md](../features/08-Git-自动Commit.md)。

---

## 十二、插件扩展

插件可注册自定义子命令，通过 `cyac <plugin-cmd>` 执行外部脚本或二进制。

### 安装

在 `~/.config/cyac/plugins/<name>/` 创建目录和 `plugin.yaml`：

```yaml
name: my-plugin
version: 1.0.0
description: 插件描述
commands:
  - name: my-cmd
    exec: bin/my-cmd
    help: 执行自定义命令
```

可执行文件放在 `bin/` 下或按 `exec` 路径配置。

### 使用

```powershell
cyac plugins list          # 列出已安装插件
cyac my-cmd arg1 arg2      # 执行插件命令
```

---

## 十三、项目配置

### 初始化项目配置

```powershell
cd 你的项目目录
cyac init --model deepseek-coder
```

会创建 `.cyac/config.yaml` 和 `memory/` 目录结构，后续命令会优先使用项目配置。

### 配置文件位置

- **全局**：`~/.config/cyac/config.yaml`（或 `%APPDATA%\cyac\config.yaml`）
- **项目**：`<项目根>/.cyac/config.yaml`

### 主要配置项

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `model.default` | 默认使用的模型 | deepseek-coder:6.7b |
| `model.fallback` | 备用模型 | qwen2.5-coder:7b |
| `context.ignore_patterns` | 上下文收集时忽略的目录 | node_modules, target, .git |
| `context.max_tokens` | 上下文最大 Token 数 | 16000 |
| `features.auto_save_backup` | save 前是否自动备份 | true |
| `features.confirm_before_write` | 首次 save 是否确认 | true |
| `features.auto_commit` | 写入后自动 git commit（需在 git 仓库内） | false |
| `tools.brave_api_key` | Brave Search API Key（search_web 用），可用 `cyac config set brave_api_key <key>` 或 env BRAVE_API_KEY，[获取指南](../features/07-Brave-Search-API.md) | - |

---

## 十四、--project 指定项目

多项目或非当前目录时，用 `-p` 或 `--project` 指定项目根：

```powershell
cyac chat -p ./backend "如何添加日志中间件？"
cyac explain -p ./frontend src/App.tsx
cyac session start --project ./myapp
```

---

## 十五、管道与编辑器集成

### 从编辑器选中代码解释（推荐）

在 VS Code、Cursor 等编辑器中**选中代码 → 复制**，然后：

```powershell
# Windows PowerShell：剪贴板直接管道
Get-Clipboard | cyac explain --stdin

# Linux/macOS：xclip 或 pbcopy 配合
xclip -o | cyac explain --stdin    # Linux
pbpaste | cyac explain --stdin     # macOS
```

**无需保存文件**，选中即解释，适合快速理解片段逻辑。

### 指定关注行（--focus-line）

解释文件时，若已知用户关注某一行（如编辑器光标行），可用 `--focus-line` 让 AI 着重解释该行附近：

```powershell
cyac explain src/main.rs --focus-line 42
cyac explain src/lib.rs:30-50 --focus-line 35   # 配合行范围
```

便于脚本或编辑器扩展传入光标行号。

### 其他管道用法

```powershell
Get-Content temp.rs | cyac explain --stdin
cat file.py | cyac explain --stdin
```

### 配合 Git 使用

```powershell
cyac explain src/feature/new_module.rs
cyac test generate --path src/feature/new_module.rs
```

---

## 十六、init 别名

`init` 支持别名 `i`，便于快速初始化：

```powershell
cyac i --model deepseek-coder
```

---

## 十七、实用技巧

1. **剪贴板即解释**：编辑器中选中代码复制，`Get-Clipboard | cyac explain --stdin`，无需保存文件
2. **focus-line 聚焦**：`cyac explain src/main.rs --focus-line 42` 让 AI 着重解释光标所在行
3. **流式 + 长问题**：复杂问题用 `--stream` 可边生成边看
4. **dry-run 先试**：重构前用 `--dry-run` 查看结果
5. **--apply 一键应用**：refactor、diagnose、generate 支持直接写入，省去复制粘贴
6. **search 快速定位**：用 `cyac search "关键词"` 在代码库中查找
7. **审计追溯**：`audit.log` 可查所有写入操作
8. **备份恢复**：误覆盖时用 `.cyac.bak` 恢复
9. **记忆跨会话**：用 `cyac memory log` 记录技术决策，explain/chat 会自动注入
10. **Skill 增强**：从 uskill.cn 安装 Skill，触发词匹配时自动注入到 prompt
11. **多角色切换**：配置 `agents` 后，用 `--agent doc` 等切换文档/代码等角色
12. **插件扩展**：在 `~/.config/cyac/plugins/` 创建 plugin.yaml，注册自定义子命令
13. **Tool Calling**：`cyac chat --tools` 让模型主动读文件、列目录、写文件，适合「让 AI 自己看代码再回答」
