# cyac 命令参考

本文档列出 cyac 所有命令、子命令及常用选项的完整说明。

---

## 全局选项

| 选项 | 简写 | 说明 |
|------|------|------|
| `--project <path>` | `-p` | 指定项目路径，用于上下文收集 |
| `--agent <id>` | - | 切换角色，使用对应 agent 的 system_prompt 与记忆 |
| `--dry-run` | - | 仅预览不写入，防止意外修改文件（适用于 refactor、session save） |
| `--json` | - | JSON 输出，便于脚本解析 |
| `--no-color` | - | 禁用彩色输出，管道友好 |
| `--no-network` | - | 禁用联网 MCP 工具（仅使用本地 MCP 与内置工具） |

**示例：**

```powershell
cyac --dry-run refactor rename --old foo --new bar --path src/lib.rs
cyac -p ./myapp chat "如何添加日志？"
```

---

## 命令列表

### init / i — 初始化项目配置

在当前目录创建 `.cyac/config.yaml`，可指定默认模型。

```powershell
cyac init [--model <模型名>]
cyac i --model deepseek-coder
```

| 选项 | 说明 |
|------|------|
| `--model` | 默认使用的模型名 |

---

### explain / exp — 解释代码

解释指定文件或代码段的逻辑。

```powershell
cyac explain [路径] [选项]
cyac exp src/main.rs
cyac explain src/main.rs:25-40 --stream
```

| 参数/选项 | 说明 |
|-----------|------|
| `路径` | 文件路径，支持 `file:start-end` 格式；支持 `@path` 语法（如 `@src/main.rs`） |
| `--lines <范围>` | 行范围，如 `25-40` |
| `--focus-line <N>` | 用户关注的行号，AI 着重解释该行附近（便于编辑器传入光标行） |
| `--stdin` | 从标准输入读取代码（可配合剪贴板：`Get-Clipboard \| cyac explain --stdin`） |
| `--stream` | 流式输出，实时显示生成内容 |
| `--apply` | 将解释结果写入 `*_explained.md` 文件 |
| `--json` | JSON 格式输出 |

**示例：**

```powershell
cyac explain src/lib.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    # 着重解释第 42 行
Get-Clipboard | cyac explain --stdin       # 剪贴板选中代码即解释（Windows）
Get-Content main.rs | cyac explain --stdin
cyac explain src/utils.rs --stream
```

---

### refactor / ref — 代码重构

重命名符号或提取函数。默认输出预览，可用 `--apply` 直接写入文件。

```powershell
cyac refactor rename --old <旧名> --new <新名> [--path <文件或目录>] [--apply]
cyac refactor extract --lines <起始-结束> --name <函数名> [--path <文件>] [--apply]
```

**rename 子命令：**

| 选项 | 说明 |
|------|------|
| `--old` | 原符号名 |
| `--new` | 新符号名 |
| `--path` | 目标文件或目录。为目录时，会搜索包含旧名的所有代码文件并批量修改 |
| `--apply` | 直接写入文件，不仅预览 |

**extract 子命令：**

| 选项 | 说明 |
|------|------|
| `--lines` | 要提取的行范围，如 `25-40` |
| `--name` | 提取后的函数名 |
| `--path` | 目标文件路径 |
| `--apply` | 直接写入文件，不仅预览 |

**示例：**

```powershell
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
cyac --dry-run refactor rename --old foo --new bar --path src/lib.rs
```

---

### generate / gen — 生成代码

根据描述生成函数或代码片段。

```powershell
cyac generate function --desc <描述> [--name <名称>] [--lang <语言>] [--output <路径>]
```

| 选项 | 说明 | 默认值 |
|------|------|--------|
| `--desc` | 功能描述（必填） | - |
| `--name` | 函数/类名 | - |
| `--lang` | 编程语言 | rust |
| `--output` / `-o` | 输出到文件路径，直接写入 | 输出到终端 |

**支持语言**：rust、python、typescript、javascript、go、csharp、sql、shell 等。

**示例：**

```powershell
cyac generate function --name add --desc "计算两数之和" --lang rust
cyac gen function --desc "解析 YAML 配置" --lang python -o src/utils.py
```

---

### chat / c — 交互式对话

单次提问，可结合项目上下文。支持 **@ 文件引用**：在问题中用 `@path` 引用文件，AI 会自动读取并注入上下文。支持 **图片**：`--image` 传入或 `@` 引用图片文件。

```powershell
cyac chat [问题] [--stream] [--image <路径>]...
cyac c "如何优化这个算法？"
```

| 选项 | 说明 |
|------|------|
| `--stream` | 流式输出，实时显示回复 |
| `--image <path>` | 传入图片路径，可多次使用；需 vision 模型（如 llama3.2-vision） |
| `--tools` | 启用 Tool Calling，模型可主动读取/写入项目文件（read_file、list_dir、write_file、run_command），支持 MCP 工具 |
| `--no-network` | 与 `--tools` 配合，禁用联网 MCP 工具 |

**@ 文件引用**：问题中写 `@path` 可引用项目内文件，如 `cyac chat "解释 @src/main.rs"`。若 `@path` 指向图片（png/jpg/gif/webp/bmp），会作为图片传入。详见 [12-At文件引用.md](../features/12-At文件引用.md)、[14-图片支持.md](../features/14-图片支持.md)。

**示例：**

```powershell
cyac chat "你好"
cyac chat "请解释 @src/main.rs 的核心逻辑"     # @ 引用
cyac chat --image screenshot.png "描述这张图"  # 图片
cyac chat "@diagram.png 解释这个架构图"        # @ 引用图片
cyac chat "Rust 中 Option 和 Result 的区别？"
cyac chat --stream "写一个快速排序"
cyac chat --tools "列出 src 目录下的文件并解释 main.rs 的逻辑"
```

---

### test / t — 测试相关

生成单元测试。

```powershell
cyac test generate [--path <文件>] [--target <模块>] [--coverage <百分比>]
```

| 选项 | 说明 |
|------|------|
| `--path` | 源文件路径 |
| `--target` | 目标模块（与 --path 二选一） |
| `--coverage` | 目标覆盖率（占位，后续集成） |

**示例：**

```powershell
cyac test generate --path src/lib.rs
cyac t generate --target utils --path src/lib.rs
```

---

### analyze / ana — 代码分析

复杂度分析或依赖分析。

```powershell
cyac analyze complexity [--path <文件>] [--threshold <级别>]
cyac analyze dependencies [--path <文件>]
```

**示例：**

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

---

### config / cfg — 配置管理

查看或设置配置。

```powershell
cyac config show
cyac config set <key> <value>
```

| 配置项 | 说明 |
|--------|------|
| `model` | 默认模型 |
| `fallback` | 备用模型（Ollama 时生效） |
| `brave_api_key` | Brave Search API Key（search_web 用） |
| `backends.deepseek_api_key` | DeepSeek API Key（Ollama 不可用时的 fallback） |
| `auto_commit` | 写入后自动 git commit（true/false） |
| `tools.confirm_before_run_command` | run_command 执行前是否需用户确认（true/false），详见 [13-run_command执行确认.md](../features/13-run_command执行确认.md) |

**示例：**

```powershell
cyac config show
cyac config set model deepseek-coder
cyac config set auto_commit true
```

---

### doc / d — 文档生成

为代码生成 API 文档。

```powershell
cyac doc generate --path <文件> [--format <格式>]
```

| 选项 | 说明 | 默认值 |
|------|------|--------|
| `--path` | 源文件路径（必填） | - |
| `--format` | 输出格式 | markdown |

**示例：**

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

---

### diagnose / diag — Bug 诊断

分析错误日志并给出修复建议。

```powershell
cyac diagnose --log <错误日志路径> [--path <代码路径>] [--apply]
cyac diag --log error.txt --path src/main.rs --apply
```

| 选项 | 说明 |
|------|------|
| `--log` | 错误日志文件路径（必填） |
| `--path` | 相关代码文件路径（可选，不指定则使用项目上下文） |
| `--apply` | 将 AI 给出的修复代码直接写入 `--path` 指定文件 |

**示例：**

```powershell
# 编译错误日志 + 相关代码
cyac diagnose --log build_error.txt --path src/main.rs

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

# 仅错误日志，使用项目上下文
cyac diagnose --log runtime_error.log
```

---

### repl — 交互式 REPL

多轮对话模式，支持 `save`/`write` 将 AI 回复保存到文件。输入中支持 **@ 文件引用**（含图片），如 `> 解释 @src/main.rs`、`> @screenshot.png 这是什么界面？`。

```powershell
cyac repl [-p <项目路径>]
```

**REPL 内命令：**

| 命令 | 说明 |
|------|------|
| `save <路径>` | 将上次 AI 回复保存到文件 |
| `write <路径>` | 与 save 等价 |
| `exit` / `quit` | 退出 REPL |

---

### session — 项目会话

在项目上下文中启动 REPL，支持 save 写入项目文件。

```powershell
cyac session start [--project <路径>]
```

首次 `save` 会确认，确认后同目录下后续保存免确认。

---

### search / s — 代码库搜索

按关键词或描述在代码库中查找相关代码。

```powershell
cyac search [关键词] [--path <路径>] [--lang <扩展名>] [-c <行数>]
cyac s "parse_config" --path src/
```

| 选项 | 说明 | 默认值 |
|------|------|--------|
| `query` | 搜索关键词或描述（位置参数） | - |
| `--path` / `-p` | 限定搜索路径（文件或目录） | 当前目录 |
| `--lang` | 限定语言/扩展名（如 rs、py、ts） | 所有代码文件 |
| `-c` / `--context` | 匹配行上下文的行数 | 2 |

**示例：**

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

---

### memory — 项目记忆

管理项目记忆（技术决策、规范、历史问题），供 explain、chat、REPL 等命令注入到 prompt。

```powershell
cyac memory log "记忆内容" [--agent <id>]
cyac memory show [--agent <id>]
cyac memory set "记忆内容" [--agent <id>]
cyac memory refine [--days <N>]
```

| 子命令 | 说明 |
|--------|------|
| `log` | 追加到 Daily 记忆（`memory/daily/YYYY-MM-DD.md`） |
| `show` | 显示项目记忆、Daily、Global |
| `set` | 设置项目记忆（覆盖 `memory/agents/default/memory.md`） |
| `refine` | 将近期 Daily 用 LLM 提炼后追加到 Global，`--days` 默认 7（需 Ollama） |

---

### skills — 编程 Skill

列出、安装、更新、禁用/恢复 Skill。Skill 通过触发词增强 AI 行为（explain、chat、refactor、diagnose、test、doc 等命令均支持）。

```powershell
cyac skills list
cyac skills install <git-url> [--name <目录名>]
cyac skills upgrade [<skill名>]
cyac skills disable <name>
cyac skills enable <name>
```

| 子命令 | 说明 |
|--------|------|
| `list` | 列出已发现的 Skill（项目 + 用户 + 内置），并显示已禁用列表 |
| `install` | 从 Git URL 克隆 Skill 到 `~/.config/cyac/skills/` |
| `upgrade` | 更新已安装的 Skill（git pull），不指定名称则更新全部 |
| `disable` | 临时禁用某 Skill（写入 `~/.config/cyac/skills-disabled`） |
| `enable` | 恢复已禁用的 Skill |

**Skill 来源**：可从 [uskill.cn](https://www.uskill.cn/) 获取更多 Skill。

---

### plugins — 插件管理

列出已安装的插件。插件可注册自定义子命令，通过 `cyac <plugin-cmd>` 执行。

```powershell
cyac plugins list
cyac <plugin-cmd> [args...]
```

| 子命令/用法 | 说明 |
|-------------|------|
| `list` | 列出 `~/.config/cyac/plugins/` 下的插件及其命令 |
| `cyac <plugin-cmd>` | 执行插件注册的命令（未知子命令时尝试作为插件执行） |

**插件安装**：在 `~/.config/cyac/plugins/<name>/` 创建 `plugin.yaml`，格式见开发计划文档。

---

### models — 模型列表

列出可用模型。Ollama 可用时显示本地模型；DeepSeek fallback 时显示 deepseek-chat、deepseek-reasoner。

```powershell
cyac models list
```

显示模型名称、大小，并标注当前默认模型。设置默认模型使用 `cyac config set model <name>`。

---

### MCP 工具（--tools 时生效）

配置 MCP 服务器后可扩展更多工具。详见 [docs/features/02-MCP工具.md](../features/02-MCP工具.md)。

- **配置**：`~/.config/cyac/mcp.json` 或 config 中 `mcp.servers`
- **优先级**：L1 内置 → L2 本地 MCP → L3 联网 MCP
- **禁用联网**：`--no-network` 或 `mcp.remote_enabled: false`

---

## 命令别名速查

| 完整命令 | 别名 |
|----------|------|
| init | i |
| explain | exp |
| refactor | ref |
| generate | gen |
| chat | c |
| test | t |
| analyze | ana |
| config | cfg |
| doc | d |
| diagnose | diag |
| search | s |
| memory | - |
| skills | - |
| plugins | - |
| models | - |
