# cyac（赛亚克）

**Ollama 生态的 CLI 优先编程入口** —— 用本地模型做 explain、refactor、diagnose、generate，在终端里完成，可脚本、可管道。

> **中文名**：赛亚克（Sài yà kè）—— 音译精准还原 CYAC 发音；「赛」有竞赛、领先之意，「亚克」易联想赛亚人般的强大与进化，「克」有攻克、精准之意；发音响亮，带科幻色彩，易于在技术社群传播。

面向终端开发者，提供本地化、注重隐私的代码理解、生成与重构能力。当你想用 Ollama 做编程时，cyac 是专门为此设计的 CLI 工具。

### 核心特点

- **Ollama 深度集成**：本地模型优先，无 API 成本，隐私安全
- **CLI 优先**：纯终端工作流，可脚本化、管道、CI 集成
- **轻量高性能**：Rust 实现，启动快、低内存占用
- **编程上下文**：项目结构、相关文件、引用关系，比裸 `ollama run` 更懂代码

### 适用场景

新项目上手、代码重构、Bug 排查、测试与文档生成、日常编程问答。

### 技术栈与平台

Rust · Tokio · Clap · Ollama API · reqwest · serde · git2  
支持 Windows、Linux、macOS（x86_64 / ARM64）

---

## 功能特性

- **代码解释**：解释指定代码段的逻辑
- **智能重构**：重命名符号、提取函数
- **代码生成**：根据描述生成函数实现
- **测试生成**：基于现有代码生成单元测试
- **代码分析**：复杂度分析、依赖分析
- **文档生成**：生成 API 文档
- **交互对话**：chat 与 REPL 模式
- **项目会话**：保持上下文的会话模式
- **批量确认写入**：会话中 `save <path>` 将 AI 回复保存到文件，首次确认后同目录免确认
- **项目记忆**：技术决策、规范、历史问题跨会话保持，`cyac memory log/show/set`
- **编程 Skill**：重构、测试、文档等触发词增强 AI 行为，`cyac skills list`，支持 `install`/`upgrade`、`disable`/`enable`
- **多角色配置**：`--agent <id>` 切换角色，在 config 中配置 `agents` 的 `system_prompt`
- **插件扩展**：`~/.config/cyac/plugins/<name>/plugin.yaml` 注册子命令，`cyac plugins list` 列出，`cyac <plugin-cmd>` 执行
- **Tool Calling**：`cyac chat --tools` 启用工具调用，模型可主动 read_file、list_dir、write_file、search_web（需 Qwen3、Llama 3.1 等支持工具调用的模型，search_web 需配置 BRAVE_API_KEY）
- **@ 文件引用**：chat/repl 中用 `@path` 引用文件，如 `cyac chat "解释 @src/main.rs"`
- **管道友好**：`--json`、`--no-color`、`--stdin`、`--apply`
- **Git 集成**：`features.auto_commit` 开启后，写入文件自动 git add + commit
- **Ollama 联动**：`cyac models list` 查看模型，请求失败自动重试

## 环境要求

- Rust 1.75+
- Ollama 0.5+（需单独安装并启动）
- 推荐模型：deepseek-coder:6.7b、qwen2.5-coder:7b

## 安装

```bash
# 从源码编译
cargo install --path .

# 或克隆后
cd cyac && cargo build --release
```

## 首次使用

1. 确保 Ollama 已安装并运行：
  ```bash
   ollama serve
   ollama pull deepseek-coder
  ```
2. 运行 cyac 查看欢迎信息与可用模型：
  ```bash
   cyac
  ```
3. 设置默认模型（可选）：
  ```bash
   cyac config set model deepseek-coder
  ```
4. 启用联网搜索（可选，需 Brave API Key）：
  ```bash
   cyac config set brave_api_key 你的Key
  ```

## 使用案例

面向 zip 用户的完整文档见 **docs/user/**（随 zip 分发，为使用者第一介绍来源）。

## 命令速查

```bash
# 代码理解
cyac explain src/main.rs
cyac explain @src/main.rs              # 支持 @path 语法
cyac explain src/main.rs:25-40
cyac explain src/main.rs --focus-line 42 # 着重解释第 42 行（便于编辑器传入光标行）
Get-Clipboard | cyac explain --stdin    # 剪贴板选中代码即解释（Windows）
cyac explain --stdin < main.rs
cyac explain src/main.rs --json          # JSON 输出，便于脚本解析
cyac explain src/main.rs --apply         # 直接写入解释到文件

# 代码操作
cyac refactor rename --old old_name --new new_name --path src/lib.rs
cyac refactor extract --lines 25-40 --name helper --path src/main.rs
cyac generate function --name calculate --desc "计算两数之和" --lang rust

# 测试与文档
cyac test generate --path src/lib.rs
cyac doc generate --path src/lib.rs --format markdown

# 交互模式
cyac chat "如何优化这个算法？"
cyac chat "请解释 @src/main.rs 的核心逻辑"        # @ 文件引用
cyac chat --tools "列出 src 目录并解释 main.rs"   # 启用 Tool Calling
cyac repl
cyac session start --project ./
# 会话中: save src/xxx.rs 将上次 AI 回复保存（首次会确认，确认后同目录免确认）

# 项目记忆
cyac memory log "技术决策：使用 Rust"
cyac memory show
cyac memory set "项目规范：..."

# 编程 Skill
cyac skills list
cyac skills install https://github.com/user/cyac-skill-xxx
cyac skills upgrade [name]
cyac skills disable <name>    # 临时禁用
cyac skills enable <name>     # 恢复

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

# Ollama 模型
cyac models list
```

## 配置

配置文件位于 `~/.config/cyac/config.yaml`：

```yaml
version: 1
model:
  default: "deepseek-coder:6.7b"
  fallback: "qwen2.5-coder:7b"
context:
  max_tokens: 16000
  include_git_history: true
  ignore_patterns:
    - "**/node_modules"
    - "**/target"
    - "**/.git"
features:
  auto_save_backup: true
  confirm_before_write: true   # 写入前批量确认：首次 save 确认后，本次会话内同目录免确认
  auto_commit: false          # 写入后自动 git commit（需在 git 仓库内）
  enable_telemetry: false
# 多角色（可选）
agents:
  - id: doc
    system_prompt: "你是文档专家，专注于生成清晰的技术文档..."
  - id: code
    system_prompt: "你是代码专家，擅长重构与优化..."
```

**主要配置项**：

| 配置项                             | 说明                                  |
| ------------------------------- | ----------------------------------- |
| `model.default`                 | 默认模型                                |
| `agents`                        | 多角色列表，含 `id`、`system_prompt`，配合 `--agent <id>` 使用 |
| `features.confirm_before_write` | 会话中 save 时是否首次确认（true 时首次确认后同目录免确认） |
| `features.auto_commit`         | 写入文件后自动 git add + commit（默认 false，需在 git 仓库内） |
| `context.ignore_patterns`       | 上下文收集时忽略的目录                         |
| `mcp.servers`                   | MCP 服务器列表，支持 `type: local`/`remote`，配合 `--tools` 使用 |
| `mcp.remote_enabled`            | 是否启用联网 MCP 工具（`--no-network` 或 `false` 时禁用） |
| `tools.brave_api_key`           | Brave Search API Key（也可用环境变量 `BRAVE_API_KEY`），用于 search_web，[获取指南](docs/features/07-Brave-Search-API.md) |
| `tools.confirm_before_run_command` | run_command 执行前是否需用户确认（默认 false） |


## 项目配置

在项目目录运行 `cyac init` 可创建 `.cyac/config.yaml` 项目级配置，以及 `memory/` 目录结构。

### 项目记忆

记忆存储在 `memory/` 下，供 explain、chat、REPL 等命令注入到 prompt：

- `memory/agents/default/memory.md` - 项目记忆（技术决策、规范）
- `memory/daily/YYYY-MM-DD.md` - 每日工作轨迹
- `memory/global/MEMORY.md` - 长期记忆（可选）

### 编程 Skill

在 `.cyac/skills/<name>/SKILL.md` 或 `~/.config/cyac/skills/<name>/SKILL.md` 创建 Skill，支持 YAML frontmatter 与 triggers。当用户输入匹配触发词时，Skill 内容会注入到 prompt。explain、chat、refactor、diagnose、test、doc 等命令均支持 Skill 注入。

**社区 Skill**：可从 [uskill.cn](https://www.uskill.cn/) 获取更多 Skill，使用 `cyac skills install <git-url>` 安装。

### 功能文档

各功能详细使用说明见 [docs/features/](docs/features/)：

| 文档 | 功能 |
|------|------|
| [01-Tool-Calling.md](docs/features/01-Tool-Calling.md) | Tool Calling |
| [02-MCP工具.md](docs/features/02-MCP工具.md) | MCP 工具配置 |
| [03-插件.md](docs/features/03-插件.md) | 插件扩展 |
| [04-项目记忆.md](docs/features/04-项目记忆.md) | 项目记忆 |
| [05-编程Skill.md](docs/features/05-编程Skill.md) | 编程 Skill |
| [06-多角色.md](docs/features/06-多角色.md) | 多角色 |
| [07-Brave-Search-API.md](docs/features/07-Brave-Search-API.md) | Brave Search API Key 获取与配置 |
| [08-Git-自动Commit.md](docs/features/08-Git-自动Commit.md) | Git 自动 Commit |
| [09-管道与脚本友好.md](docs/features/09-管道与脚本友好.md) | 管道与脚本友好 |
| [12-At文件引用.md](docs/features/12-At文件引用.md) | @ 文件引用 |
| [13-run_command执行确认.md](docs/features/13-run_command执行确认.md) | run_command 执行前确认 |
| [10-Ollama-模型管理.md](docs/features/10-Ollama-模型管理.md) | Ollama 模型管理 |

## 品牌与命名

中文名 **赛亚克**（Sài yà kè），寓意：音译精准、寓意积极、记忆点强。详见 [docs/品牌与命名.md](docs/品牌与命名.md)。

---

## 打包分发

将 cyac 打包给其他用户使用，请参阅 [docs/DISTRIBUTION.md](docs/DISTRIBUTION.md)。

**Windows** 快速打包：

```powershell
.\scripts\windows\build-release.ps1
```

生成 `dist/cyac-v0.1.0-windows-x64.zip`。用户解压后**双击 install.bat** 即可安装，完整使用说明见 zip 内 **docs/user/** 目录。

**Linux / macOS** 打包：

```bash
./scripts/linux/build-release.sh
```

生成 `dist/cyac-v0.1.0-{os}-{arch}.tar.gz`。用户解压后执行 `./install.sh` 即可安装。

## 开发

```bash
cargo build
cargo test
cargo run -- --help
cargo clippy
```

## 许可证

MIT