# codecli

**Repository Path**: Candykon/codecli

## Basic Information

- **Project Name**: codecli
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-16
- **Last Updated**: 2026-07-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# codecli

多模型 AI 协作命令行工具。

## 简介

`codecli` 让多个 AI 模型像一个工作群一样协作完成软件开发任务：

- **方案师（Architect）**：负责输出整体架构、目录结构、接口约定。
- **前端开发（Frontend）**：负责实现前端代码。
- **后端开发（Backend）**：负责实现后端代码。
- **测试验收（QA）**：负责评审并最终投票。

模型之间自动循环交流，所有消息在终端以群聊形式展示，每个模型投票，**全票通过**才算验收完成，否则继续重新思考并输出代码。

## 快速开始

```bash
cd 你的项目目录
codecli config init          # 生成 config.yaml，填入你的模型与 key
codecli                      # 进入群聊界面
```

在界面里：

1. 输入 `/init` —— 所有模型先阅读项目资料，把认识文档写入 `syycode/`（`AGENTS.md` 总览 + 各角色文档，后续会话自动参考）；
2. 直接输入需求，`Enter` 发送后**先选择进入群聊的成员**（默认全选，空格勾选/取消，`Enter` 开始）；
3. 一场结束后**直接输入下一个需求**即可继续，无需退出；
4. `/sessions` 查看并加载历史会话（全部消息原样回放），`/new` 随时开新会话；
5. **你也是群聊的一员**：会话进行中直接输入文字即发言（右侧亮白气泡），模型后续发言都能看到。

输入框固定 3 行，超出时上方提示“↑ 已隐藏 N 行”；支持多行需求一次发送。输入 `/` 时输入框上方会弹出**命令候选菜单**（每个命令带说明，`↑/↓` 选择，`Enter` 补全），不用背命令。界面不捕获鼠标，**所有内容都可以用终端原生选择直接复制**；`/init` 过程中可看到每个模型的认识进度与产出文档。

## 核心特性

- 多角色、多模型实例协作
- 全屏交互界面（类似 Claude Code / Codex）：群聊布局，单数 Agent 靠左、双数靠右，颜色固定，白狐吉祥物
- 同轮文件冲突自动触发**冲突协商子轮次**，相关模型讨论出统一版本
- 会话逐条持久化，中断可用 `resume` 恢复；`export` 导出 Markdown 存档
- 界面内运行时命令：`/syy` 暂停、`/continue` 继续、`/stats`、`/session`、`/exit`、`/help`
- 自动代码提取与落盘
- 专门投票轮次与 unanimous 通过机制；投票并发执行、格式异常自动重投一次
- SQLite 全局投票榜单（`codecli stats`，按收到通过率排名）
- 支持 OpenAI-compatible / Claude / Gemini 模型（后两者为可选依赖）
- 角色扩展：内置 prompt 模板库、角色级阶段提示覆盖、讨论发言顺序可配

## 安装

推荐使用 `uv` 或 `pip` 在虚拟环境安装：

```bash
# uv
uv pip install -e ".[dev]"

# pip
pip install -e ".[dev]"
```

安装后命令行即出现 `codecli` 入口。

## 配置

可以直接用命令管理配置，无需手动编辑 YAML：

```bash
codecli config init                              # 生成配置模板（默认 config.yaml）
codecli config show                              # 查看配置（api_key 自动脱敏）
codecli config set project.max_rounds 3          # 设置配置项（自动解析数字/布尔/null）
codecli config set providers.deepseek.model deepseek-chat
codecli config get providers.deepseek.model      # 读取配置项
codecli config unset providers.deepseek.base_url # 删除配置项
```

- 配置键为点号路径（`project.*` / `providers.*` / `roles.*`），中间层级自动创建；所有子命令支持 `-c <path>` 指定配置文件。
- 也可复制示例配置手动编辑：`cp examples/config.yaml config.yaml`，完整示例见 [`examples/config.yaml`](examples/config.yaml)。
- 所有命令的 `--config` 均可省略，按 `./config.yaml` → `./syycode/config.yaml` → `~/.codecli/config.yaml`（全局兜底）顺序解析。全局安装后可把配置放 `~/.codecli/config.yaml`，任意目录开箱即用。
- API key 推荐用环境变量：配置中写 `${OPENAI_API_KEY}` 会自动替换为环境变量值；也可以直接填写 `api_key`（不建议提交到 git）。

配置结构说明：

- `providers`：模型接入配置。`type: openai` 覆盖 GPT/DeepSeek/Kimi 等兼容服务；`type: anthropic`（Claude，需 `pip install anthropic`）；`type: gemini`（需 `pip install google-generativeai`）。
- `roles`：角色与智能体定义，每个角色可绑定一个或多个模型实例；`system_prompt` 可省略——用 `template: architect|frontend|backend|qa|docs` 引用内置模板，或 role key 与模板同名时自动使用；`phase_instructions` 可按角色覆盖阶段提示。
- `project`：输出目录、日志目录、最大轮次、`dry_run`、`discussion_order`（讨论发言顺序）等全局设置。

## 命令

| 命令 | 说明 |
|------|------|
| `codecli` | 进入群聊界面：输入需求开始协作，`/init` 认识项目，会话结束可继续输新需求 |
| `codecli init [-c config]` | 让模型认识当前项目，在 `syycode/` 下生成认识文档 |
| `codecli create <requirement> [-c config]` | 根据需求启动一次多模型群聊（全屏界面） |
| `codecli create ... --dry-run` | 仅预览流程，不写入文件 |
| `codecli create/resume ... --no-tui` | 不使用全屏界面，纯文本输出（适合 CI/管道） |
| `codecli resume <session_id>` | 恢复历史会话（`--max-rounds N` 可追加轮次预算） |
| `codecli show <session_id>` | 查看历史会话详情 |
| `codecli sessions` | 列出全部历史会话 |
| `codecli stats` | 查看全局投票榜单（SQLite 聚合，按收到通过率排名） |
| `codecli export <session_id> [-o path]` | 把会话导出为 Markdown 文档 |
| `codecli config init/show/set/get/unset` | 命令行管理配置（无需手动改 YAML） |

### 启动一次群聊

```bash
codecli create "做一个支持拖拽的 Todo 小程序" --config config.yaml
```

全屏界面中：顶部是 codecli Logo（含白狐吉祥物）与会话信息，中间为群聊消息流（单数 Agent 靠左、双数靠右，每个 Agent 颜色固定），底部状态栏显示当前轮次/阶段与正在思考的模型，`Ctrl+Q` 退出。底部命令输入框支持 `/help`、`/stats`、`/session`、`/quit`。

若同一轮中两个模型向同一文件写入不同内容，会自动进入**冲突协商子轮次**：相关模型看到彼此的版本并讨论出统一方案后落盘，随后照常进入投票；若协商后仍有分歧，则保留最后写入版本并**暂停会话等待人工处理**（可人工修改后用 `resume` 继续）。

### 仅预览，不写入文件

```bash
codecli create "做一个支持拖拽的 Todo 小程序" --config config.yaml --dry-run
```

### 中断后恢复会话

会话的每条消息都会实时持久化到 `~/.codecli/sessions/`（可用环境变量 `CODECLI_SESSION_DIR` 覆盖）。达到最大轮次或中途退出后：

```bash
codecli sessions                                # 找到会话 ID
codecli resume session_20260717_100000          # 从断点继续
codecli resume session_20260717_100000 --max-rounds 3   # 追加 3 轮预算
```

### 查看帮助

```bash
codecli --help
codecli create --help
```

## 架构概览

```
src/codecli/
├── cli.py              # Typer 命令行入口与参数解析
├── config.py           # YAML 配置加载、环境变量替换与 Pydantic 校验
├── models.py           # 核心领域模型：Message、Vote、VoteResult 等
├── agent.py            # Agent 封装：角色、系统提示、模型调用
├── chatroom.py         # 群聊上下文管理，消息按轮次与阶段存储
├── orchestrator.py     # 多轮协作主控：framework → discussion →（冲突协商）→ voting → report
├── project_init.py     # 项目认识：扫描项目资料，生成 syycode/ 认识文档
├── exporter.py         # 会话导出 Markdown（export 命令）
├── rendering.py        # Rich 终端渲染与纯文本事件监听
├── events.py           # Orchestrator 事件类型（消息/阶段/投票/报告等）
├── config_cli.py       # config 子命令组：init/show/set/get/unset（api_key 脱敏）
├── sessions.py         # 会话持久化：SessionState / SessionStore / SessionRecorder
├── stats_db.py         # SQLite 全局投票榜单（stats 命令）
├── roles/              # 角色注册表与系统提示模板
├── providers/          # Provider 抽象与 OpenAI / Anthropic / Gemini 实现
├── tui/                # Textual 全屏界面：Logo（含白狐吉祥物）、配色、气泡组件、App
└── tools/              # 代码提取、文件写入、投票解析、统计跟踪
```

一次 `create` 会话的典型流程：

1. **解析配置**：加载 `config.yaml`，替换环境变量，校验 schema。
2. **构建 Agent**：根据 `roles` 与 `providers` 实例化模型代理。
3. **初始化群聊**：创建 `ChatRoom`，写入系统需求消息。
4. **运行 Orchestrator**：
   - **Framework 阶段**：架构师输出整体方案。
   - **Discussion 阶段**：各角色循环发言、补充与修改。
   - **Voting 阶段**：QA 等角色按格式投票。
   - **Conflict Resolution**：未全票通过时，根据反馈继续讨论。
   - **Report 阶段**：输出最终代码与统计。
5. **文件写入**：`FileWriter` 将代码块提取并落盘（`dry-run` 时跳过）。

> 设计文档规划已全部实现：全屏 TUI、会话持久化、全部命令、冲突协商（含未解决暂停）、运行时命令（/syy、/continue 等）、Claude/Gemini 适配、投票并发、SQLite 榜单、prompt 模板库与角色扩展。

## 测试

项目使用 `pytest` 进行单元测试与集成测试：

```bash
# 运行全部测试
pytest -q

# 仅运行 CLI 集成测试
pytest tests/integration/test_cli.py -v

# 生成覆盖率报告
pytest --cov=src/codecli --cov-report=term-missing
```

当前测试覆盖：

- 配置加载与校验（`tests/unit/test_config.py`）
- Agent、ChatRoom、Orchestrator 行为与事件发射（`tests/unit/`）
- 工具函数：代码提取、文件写入、投票解析、统计（`tests/unit/test_*.py`）
- 会话持久化（`tests/unit/test_sessions.py`）
- TUI 布局配色与界面冒烟（`tests/unit/test_tui_theme.py`、`test_tui_app.py`）
- Provider 单元测试（`tests/unit/test_openai_provider.py`）
- CLI 集成测试：create/resume/show/sessions/stats（`tests/integration/test_cli.py`）

## 项目文档

- 需求文档：`docx/requirements.md`
- 设计文档：`docx/2026-07-16-codecli-design.md`
- 实现规划：`docx/2026-07-16-codecli-plan.md`

> 设计文档与实现规划不纳入 git 版本控制，仅作为项目参考文档保留在 `docx/` 目录。