# cyac 使用示例

本文档介绍 cyac 在日常开发中的典型使用场景与完整案例。

---

## 1. 新接手项目：快速理解代码

**场景**：刚加入团队或接手遗留项目，需要快速理解核心逻辑。

### 解释整个文件

```powershell
cyac explain src/lib.rs
```

### 解释指定行范围

```powershell
# 解释第 25-40 行
cyac explain src/main.rs:25-40

# 或使用 --lines 参数
cyac explain src/main.rs --lines 25-40
```

### 管道模式（配合编辑器选中）

在编辑器中选中代码，通过管道传入：

```powershell
Get-Content src/utils.rs | cyac explain --stdin
```

### 分析代码复杂度

```powershell
cyac analyze complexity --path src/core/module.rs
```

### 分析依赖关系

```powershell
cyac analyze dependencies --path src/main.rs
```

---

## 2. 代码重构

**场景**：需要安全地重命名变量、提取函数，或优化代码结构。

### 重命名符号

```powershell
cyac refactor rename --old old_name --new new_name --path src/lib.rs
```

默认输出预览。加 `--apply` 可直接写入文件：

```powershell
cyac refactor rename --old old_name --new new_name --path src/lib.rs --apply
```

### 跨文件批量重命名

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

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

### 提取函数

```powershell
# 将第 25-40 行提取为名为 helper 的函数
cyac refactor extract --lines 25-40 --name helper --path src/main.rs

# 直接写入文件
cyac refactor extract --lines 25-40 --name helper --path src/main.rs --apply
```

### 重构流程建议

复杂重构前可先理解再动手：

```powershell
# 1. 先理解目标代码
cyac explain src/module.rs:20-50

# 2. 再执行重构
cyac refactor extract --lines 20-50 --name process_data --path src/module.rs
```

---

## 3. 代码生成

**场景**：根据需求描述快速生成函数、工具函数或样板代码。

### 生成函数（多语言）

```powershell
# Rust
cyac generate function --name add --desc "计算两个 i32 的和" --lang rust

# Python
cyac generate function --name parse_config --desc "从 YAML 字符串解析配置" --lang python

# TypeScript
cyac generate function --name User --desc "用户类型定义，包含 id、name、email" --lang typescript

# Go
cyac generate function --name validate --desc "验证邮箱格式是否合法" --lang go

# C#
cyac generate function --name GetUserById --desc "根据 ID 查询用户，返回 User 对象" --lang csharp

# JavaScript
cyac generate function --name fetchData --desc "异步获取 API 数据，支持重试 3 次" --lang javascript

# SQL
cyac generate function --name create_user_table --desc "创建用户表，含 id、username、created_at" --lang sql

# Shell
cyac generate function --name backup_dir --desc "将指定目录打包为 tar.gz 备份" --lang shell
```

### 生成并写入文件

使用 `--output` 或 `-o` 将生成结果直接写入指定文件：

```powershell
cyac generate function --name parse_config --desc "解析 YAML 配置" --lang python -o src/config.py
cyac gen function --desc "用户类型定义" --lang typescript --output src/types.ts
```

### 生成测试

```powershell
# 为 src/lib.rs 生成单元测试
cyac test generate --path src/lib.rs

# 指定目标模块
cyac test generate --target utils --path src/lib.rs
```

---

## 4. 文档与维护

**场景**：为代码库补充文档、生成 API 说明。

### 生成 API 文档

```powershell
cyac doc generate --path src/lib.rs --format markdown
```

### 分析依赖关系

```powershell
cyac analyze dependencies --path src/main.rs
```

---

## 5. 交互式开发

**场景**：边写代码边提问，或需要多轮对话理解设计。

### 单次提问

```powershell
cyac chat "Rust 中 Option 和 Result 的区别是什么？"
cyac chat "如何用 tokio 实现一个简单的 HTTP 服务器？"
cyac chat "Python 中 __init__ 和 __new__ 的区别？"
```

### 结合项目上下文提问

在项目目录下，会带上项目结构作为上下文：

```powershell
cyac chat "这个项目的入口在哪里？"
cyac chat --project ./myapp "如何添加新的 API 路由？"
cyac chat --project ./frontend "这个组件的 props 有哪些？"
```

### Tool Calling：让模型主动读文件

加 `--tools` 后，模型可主动调用 read_file、list_dir、write_file（及 MCP 工具），适合「让 AI 自己看代码再回答」：

```powershell
cyac chat --tools "列出 src 目录下的文件"
cyac chat --tools "读取 src/main.rs 并解释入口函数的逻辑"
cyac chat --tools "在 src 下创建 hello.txt 并写入 Hello World"
cyac chat --tools --no-network "读取 README.md"   # 仅本地工具，禁用联网 MCP
```

详见 [docs/features/01-Tool-Calling.md](../features/01-Tool-Calling.md)、[02-MCP工具.md](../features/02-MCP工具.md)。

需使用支持工具调用的模型（如 Qwen3、Llama 3.1）。

### REPL 多轮对话

```powershell
cyac repl
# 或指定项目：cyac repl --project ./myapp
```

```
> 解释当前目录的 main 函数
[AI 响应...]
> 为它生成测试
[AI 生成测试...]
> exit
```

若要将 AI 回复保存到文件，需用 `cyac session start --project <路径>` 或 `cyac repl --project <路径>` 启动。

---

## 6. 项目会话与保存到文件

**场景**：在项目上下文中多轮对话，并将 AI 生成的内容保存到项目文件。

**首次 save 会弹出确认**，确认后本次会话内同目录下所有 save/write 自动执行。

```powershell
cyac session start --project ./myapp
```

```
cyac REPL - 输入问题或命令，输入 exit 退出
支持: save <path> 将上次 AI 回复保存到文件
当前项目: Some("./myapp")

> 写一个 hello world 函数
[AI 返回代码...]

> save src/main.rs
允许在 ./myapp 下修改文件？[Y/n] Y
已保存: ./myapp/src/main.rs

> 再写一个工具函数
[AI 返回代码...]

> save src/utils.rs
已保存: ./myapp/src/utils.rs   # 不再询问，直接保存
```

**步骤**：① `session start --project <路径>` 启动 ② 对话生成代码 ③ `save <相对路径>` 或 `write <相对路径>` ④ 首次确认后，同目录后续保存免确认

---

## 7. 多语言项目

**场景**：项目包含 Rust、Python、JavaScript 等多种语言。

```powershell
# 解释 Python 代码
cyac explain scripts/data_processor.py

# 解释 JavaScript/TypeScript
cyac explain src/components/Button.tsx

# 分析 Go 模块依赖
cyac analyze dependencies --path pkg/handler/handler.go

# 为 C# 代码生成文档
cyac doc generate --path Services/UserService.cs --format markdown
```

---

## 8. 不同项目类型示例

### Web 后端 API

```powershell
cyac explain src/routes/user.rs
cyac generate function --name create_user --desc "创建用户 API，接收 JSON 返回 201" --lang rust
cyac test generate --path src/routes/user.rs
```

### 前端组件

```powershell
cyac explain src/components/Form.tsx
cyac generate function --name useForm --desc "React Hook，管理表单状态和校验" --lang typescript
```

### 脚本与工具

```powershell
cyac explain scripts/deploy.sh
cyac generate function --name check_env --desc "检查环境变量是否齐全，缺失则退出" --lang shell
```

### 数据处理

```powershell
cyac explain src/etl/pipeline.py
cyac generate function --name transform --desc "将 DataFrame 按列名映射转换" --lang python
```

---

## 9. 代码库搜索

**场景**：在项目中查找包含某关键词或模式的代码。

```powershell
# 按关键词搜索
cyac search "parse_config"
cyac s "error handling" -p src/

# 指定上下文行数
cyac search "async" -c 3 --path src/

# 限定语言
cyac search "use crate" --lang rs
```

---

## 10. Bug 排查与错误分析

**场景**：遇到报错或异常行为，需要定位原因。

### 使用 diagnose 命令（推荐）

将错误日志保存到文件，由 AI 分析并给出修复方案：

```powershell
# 编译错误
cargo build 2>&1 | Out-File -FilePath build_error.txt
cyac diagnose --log build_error.txt --path src/main.rs

# 诊断并自动应用修复
cyac diagnose --log build_error.txt --path src/main.rs --apply

# 运行时错误
.\myapp.exe 2>&1 | Out-File -FilePath runtime_error.log
cyac diagnose --log runtime_error.log --path src/module.rs

# 测试失败
cargo test 2>&1 | Out-File -FilePath test_fail.txt
cyac diagnose --log test_fail.txt --path tests/integration_test.rs
```

### 结合错误信息提问

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

### 先解释再排查

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

# 2. 再结合错误信息提问
cyac chat "第 52 行附近，为什么会出现 'expected struct, found ()'？"
```

### 带项目上下文

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

---

## 11. 完整开发流程示例

从理解到重构、测试、文档的串联：

```powershell
# 1. 理解目标模块
cyac explain src/auth/module.rs

# 2. 生成新函数
cyac generate function --name hash_password --desc "使用 bcrypt 哈希密码" --lang rust

# 3. 将生成结果写入文件（需 session）
cyac session start --project ./
# > 写一个 hash_password 函数...
# > save src/auth/module.rs

# 4. 生成测试
cyac test generate --path src/auth/module.rs

# 5. 生成文档
cyac doc generate --path src/auth/module.rs --format markdown
```

---

## 12. 工作流集成

### 初始化项目配置

在项目根目录：

```powershell
cyac init --model deepseek-coder
```

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

### 切换模型

```powershell
cyac config set model deepseek-coder
cyac config set model qwen2.5-coder
```

### 配合 Git 使用

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

---

## 13. 实用技巧

### 提问更精准

- **具体化**：`cyac chat "如何用 tokio 实现超时 5 秒的 HTTP 请求？"` 比 `cyac chat "HTTP 超时"` 更易获得有用回复
- **带上下文**：在项目目录下运行，或使用 `--project` 指定路径，AI 会结合项目结构回答

### 善用 --project 与跨文件引用

多项目时明确指定项目根。指定 `--project` 时，cyac 会解析当前文件的 import/use/mod，自动收集相关文件内容作为上下文，提高 AI 理解准确度：

```powershell
cyac chat --project ./backend "如何添加日志中间件？"
cyac explain --project ./frontend src/App.tsx
cyac diagnose --log error.txt --path src/main.rs -p ./
```

### 管道与编辑器

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

```powershell
Get-Clipboard | cyac explain --stdin   # Windows
pbpaste | cyac explain --stdin         # macOS
xclip -o | cyac explain --stdin        # Linux
```

无需保存文件，选中即解释。若已知光标行号，可配合 `--focus-line` 让 AI 着重解释该行：

```powershell
cyac explain src/main.rs --focus-line 42
```

或保存到临时文件后：

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

### 先 explain 再 refactor

复杂重构前先用 explain 理解逻辑，减少出错：

```powershell
cyac explain src/legacy.rs:100-150
cyac refactor extract --lines 100-150 --name clean_legacy --path src/legacy.rs
```

### 流式输出（长响应时）

```powershell
cyac chat --stream "写一个完整的 REST API 实现"
cyac explain src/large_module.rs --stream
```

### --dry-run 安全预览

```powershell
# 重构前先预览，不实际修改
cyac --dry-run refactor rename --old old_name --new new_name --path src/lib.rs

# 会话中 save 仅预览
cyac --dry-run session start --project ./
# > 写一个函数...
# > save src/main.rs   # 仅显示 [--dry-run] 将保存到...，未实际写入
```
