# cyac（赛亚克）快速开始（Windows 安装包用户）

安装 cyac（赛亚克）后，按以下步骤完成首次使用。

---

## 一、前置条件

cyac 需要 AI 后端，**二选一**即可：

### 方式 A：Ollama（本地优先，推荐）

1. 访问 ollama.ai 官网下载并安装
2. 安装后，Ollama 通常会自动启动（可在系统托盘查看）
3. 拉取模型：

```powershell
ollama pull deepseek-coder
```

或 `ollama pull qwen2.5-coder`

### 方式 B：DeepSeek API（无本地环境时）

配置 API Key 即可使用云端模型：

```powershell
cyac config set backends.deepseek_api_key sk-xxx
```

或设置环境变量 `DEEPSEEK_API_KEY`。详见 [AI 后端多源](../features/11-AI后端多源.md)。

---

## 二、首次使用

### 1. 运行 cyac

```powershell
cyac
```

将显示欢迎信息与可用模型列表。

### 2. 设置默认模型（可选）

```powershell
cyac config set model deepseek-coder
```

### 3. 简单测试

```powershell
cyac chat "你好"
```

若返回 AI 回复，说明配置正确。

### 4. 试试 @ 文件引用（可选）

在问题中用 `@path` 引用项目内文件，AI 会自动读取并分析：

```powershell
cyac chat "请解释 @src/main.rs 的核心逻辑"
cyac chat "根据 @README.md 总结项目功能"
```

详见 [@ 文件引用](../features/12-At文件引用.md)。`@` 也可引用图片（如 `@screenshot.png`），chat 还支持 `--image` 传入图片，需 vision 模型，详见 [14-图片支持.md](../features/14-图片支持.md)。

---

## 三、常用命令

### 代码理解

```powershell
# 解释整个文件
cyac explain src/main.rs
cyac explain @src/main.rs              # 支持 @path 语法

# 解释指定行范围
cyac explain src/main.rs:25-40
cyac explain src/main.rs --lines 25-40

# 着重解释某一行（便于编辑器传入光标行）
cyac explain src/main.rs --focus-line 42

# 剪贴板选中即解释（无需保存文件）
Get-Clipboard | cyac explain --stdin   # Windows
Get-Content main.rs | cyac explain --stdin

# 分析复杂度
cyac analyze complexity --path src/core/module.rs

# 分析依赖
cyac analyze dependencies --path src/main.rs
```

### 代码操作

```powershell
# 重命名符号（加 --apply 直接写入）
cyac refactor rename --old old_name --new new_name --path src/lib.rs
cyac refactor rename --old legacy_api --new new_api --path src/ --apply

# 提取函数
cyac refactor extract --lines 25-40 --name helper --path src/main.rs --apply

# 生成函数（加 -o 写入文件）
cyac generate function --name calculate --desc "计算两数之和" --lang rust
cyac gen function --desc "解析配置" --lang python -o src/config.py
```

### 代码搜索

```powershell
cyac search "parse_config"
cyac s "error handling" -p src/
```

### 测试与文档

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

# 生成 API 文档
cyac doc generate --path src/lib.rs --format markdown
```

### 交互模式

```powershell
# 单次提问
cyac chat "如何优化这个算法？"

# REPL 多轮对话
cyac repl

# 项目会话（带上下文，支持 save 写入文件）
cyac session start --project ./
# 会话中: save src/xxx.rs  将上次 AI 回复保存（首次会确认，确认后同目录免确认）
```

### Bug 诊断

```powershell
# 分析错误日志并给出修复建议
cyac diagnose --log build_error.txt --path src/main.rs
cyac diag --log error.log

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

### 配置与初始化

```powershell
# 初始化项目配置（支持别名 i）
cyac init --model deepseek-coder
cyac i --model deepseek-coder

# 查看配置
cyac config show

# 设置默认模型
cyac config set model deepseek-coder

# 开启写入后自动 git commit（需在 git 仓库内）
cyac config set auto_commit true

# 查看可用模型（Ollama 或 DeepSeek）
cyac models list
```

### 项目记忆与 Skill

```powershell
# 记录项目记忆（技术决策、规范等）
cyac memory log "技术决策：使用 Rust"
cyac memory show
cyac memory refine --days 7   # 将近期 Daily 提炼为 Global（需 AI 后端）

# 列出、安装、更新、禁用/恢复 Skill
cyac skills list
cyac skills install https://github.com/user/cyac-skill-xxx
cyac skills upgrade
cyac skills disable <name>   # 临时禁用
cyac skills enable <name>   # 恢复

# 插件
cyac plugins list
cyac <plugin-cmd> [args...]  # 执行插件命令
```

更多 Skill 可从 [uskill.cn](https://www.uskill.cn/) 获取。多角色切换见 [高级用法](高级用法.md)。

---

## 四、常见问题速查

| 需求 | 命令 |
|------|------|
| 看不懂某段代码 | `cyac explain 文件:行号-行号` |
| 想重命名变量 | `cyac refactor rename --old 旧名 --new 新名 --path 文件` |
| 需要提取函数 | `cyac refactor extract --lines 起始-结束 --name 函数名 --path 文件` |
| 写不出函数实现 | `cyac generate function --name 名 --desc 描述 --lang 语言` |
| 缺单元测试 | `cyac test generate --path 源文件` |
| 缺 API 文档 | `cyac doc generate --path 源文件 --format markdown` |
| 问设计/语法问题 | `cyac chat "问题"` |
| 多轮深入讨论 | `cyac repl` 或 `cyac session start` |
| 将 AI 生成代码保存到文件 | `cyac session start --project ./` 后输入 `save src/xxx.rs` |
| Bug 诊断（错误日志+代码） | `cyac diagnose --log 错误日志路径 --path 代码路径` |
| 诊断并自动应用修复 | `cyac diagnose --log 日志 --path 代码 --apply` |
| 代码库搜索 | `cyac search "关键词"` 或 `cyac s "关键词" -p src/` |
| 流式输出（实时显示） | `cyac chat --stream` 或 `cyac explain --stream` |
| 安全预览（不写入） | `cyac --dry-run refactor ...` 或 `cyac --dry-run session start` |
| 记录项目记忆 | `cyac memory log "内容"` |
| 安装社区 Skill | `cyac skills install <git-url>` |
| 临时禁用 Skill | `cyac skills disable <name>` |
| 多角色切换 | `cyac --agent <id> chat/explain/...`（需配置 agents） |
| 让模型读文件 | `cyac chat --tools "列出 src 并解释 main.rs"`（需 Qwen3 等模型） |
| 列出插件 | `cyac plugins list` |
| 查看可用模型 | `cyac models list`（Ollama 或 DeepSeek） |
| 开启自动 git commit | `cyac config set auto_commit true` |

---

## 五、项目内使用

在项目目录下运行 `cyac init` 可创建项目配置及记忆目录结构：

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

会创建 `.cyac/config.yaml` 和 `memory/` 目录（agents/default、daily、global）。之后在该目录下使用 cyac 时会自动加载项目上下文和记忆。

---

## 六、将 AI 回复保存到文件

在 cyac 中写入文件，需要用到**项目会话**和 **save/write** 命令：

**1. 启动项目会话**

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

**2. 向 AI 描述需求**

在 REPL 中输入你的需求，例如：

```
> 请帮我写一个 hello world 函数
```

**3. 使用 save 保存到文件**

AI 返回内容后，输入：

```
> save src/main.rs
```

首次 save 会弹出确认：「允许在 [项目根] 下修改文件？[Y/n]」，输入 Y 后内容即写入文件。之后同目录下的 save 不再询问。

**注意**：save 保存的是**上一次 AI 的回复**；路径相对于 `--project` 指定的项目根；`write` 与 `save` 等价。

---

## 七、配置文件

配置文件位于 `%USERPROFILE%\.config\cyac\config.yaml`（或 `~/.config/cyac/config.yaml`）。

主要配置项：

| 配置项 | 说明 |
|--------|------|
| `model.default` | 默认使用的模型 |
| `model.fallback` | 备用模型（Ollama 时生效） |
| `backends.ollama_priority` | 是否优先 Ollama（默认 true） |
| `backends.deepseek_api_key` | DeepSeek API Key（Ollama 不可用时的 fallback） |
| `context.ignore_patterns` | 上下文收集时忽略的目录 |
| `features.confirm_before_write` | 会话中 save 时是否首次确认（true 时首次确认后同目录免确认） |

---

## 八、提示与技巧

1. **优先指定 path**：涉及文件的命令尽量用 `--path` 指定路径，避免歧义。
2. **善用 --project**：多项目时用 `-p` 或 `--project` 指定项目根目录。
3. **先 explain 再 refactor**：复杂重构前先用 explain 理解逻辑。
4. **REPL 适合探索**：不确定怎么问时，用 `cyac repl` 多轮试错。
5. **save 批量确认**：`session start --project` 或 `repl --project` 后首次 `save` 会确认，确认后同目录下后续保存免确认。
