Metadata-Version: 2.4
Name: chcode
Version: 0.1.3
Summary: Terminal-based AI coding agent with typer+rich
Project-URL: Homepage, https://github.com/ScarletMercy/chcode
Project-URL: Repository, https://github.com/ScarletMercy/chcode
Project-URL: Issues, https://github.com/ScarletMercy/chcode/issues
Author-email: Flymo Han <minimizeball@foxmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,cli,coding-agent,langchain,rich,typer
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.13
Requires-Dist: aiofiles>=25.1.0
Requires-Dist: aiosqlite>=0.22.1
Requires-Dist: bs4>=0.0.2
Requires-Dist: charset-normalizer>=3.4.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: langchain-openai>=1.1.10
Requires-Dist: langchain>=1.2.10
Requires-Dist: langgraph-checkpoint-sqlite>=3.0.3
Requires-Dist: markdownify>=0.14.0
Requires-Dist: pillow>=12.2.0
Requires-Dist: prompt-toolkit>=3.0.0
Requires-Dist: psutil>=6.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: questionary>=2.1.0
Requires-Dist: rich>=13.9.0
Requires-Dist: tavily>=1.1.0
Requires-Dist: typer>=0.15.0
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.25.0; extra == 'test'
Requires-Dist: pytest-cov>=6.0.0; extra == 'test'
Requires-Dist: pytest-mock>=3.14.0; extra == 'test'
Requires-Dist: pytest-timeout>=2.3.0; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Description-Content-Type: text/markdown

# ChCode

```
 ███████╗  ██╗   ██╗   ███████╗   ██████╗   █████╗     ████████╗
██╔═════╝  ██║   ██║  ██╔═════╝  ██╔═══██╗  ██╔══██╗   ██╔═════╝
██║        ████████║  ██║        ██║   ██║  ██║   ██╗  ████████╗
██║        ██╔═══██║  ██║        ██║   ██║  ██║  ██╔╝  ██╔═════╝
████████╗  ██║   ██║  ████████╗  ╚██████╔╝  █████╔═╝   ████████╗
 ╚══════╝  ╚═╝   ╚═╝   ╚══════╝   ╚═════╝   ╚════╝      ╚══════╝
```

基于终端的 AI 编程代理，使用 LangChain + Typer + Rich 构建。

> **为什么叫 "ChCode"？** 最初的原型是一个 tkinter + LangChain 应用，名为 **chat-agent**（chagent）。当它演变为 CLI 工具后，名字变成了 **ChCode** — chat-agent 遇上 code。

<details>
<summary>📸 chagent — 最初的 tkinter 原型</summary>
<img src="https://raw.githubusercontent.com/ScarletMercy/chcode/main/assets/chagent.png" alt="chagent prototype" width="600"/>
</details>

> 7000+ 行 Python 代码，14 个内置工具，完整会话持久化，Git 感知工作流。

![Python 3.13+](https://img.shields.io/badge/python-3.13%2B-blue)
![License](https://img.shields.io/badge/license-MIT-green)

[English](README_en.md)

<img src="https://raw.githubusercontent.com/ScarletMercy/chcode/main/assets/chcode.png" alt="ChCode 主界面" width="800"/>

## 功能特性

### 模型管理

- 兼容**所有 OpenAI 兼容 API**（OpenAI、DeepSeek、Qwen、GLM、Claude 代理等）
- 内置 **ModelScope** 等主流平台快捷配置
- **ModelScope**：每天 2000 次免费模型调用
- 首次运行向导，**自动检测环境变量**（扫描 `OPENAI_API_KEY`、`DEEPSEEK_API_KEY`、`ZHIPU_API_KEY`、`ModelScopeToken` 等）
- 原生支持 **reasoning/thinking 模型** — 实时显示思考过程
- 运行时创建 / 编辑 / 切换模型
- 每个模型独立调参（temperature、top_p、top_k、max_completion_tokens、stop_sequences 等）
- **指数退避自动重试**（3/10/30/60s），持续失败时自动切换备用模型

### 视觉与多模态

- 通过 `/vision` 命令独立配置视觉模型（与主模型分离）
- 图片分析，支持**自动媒体编码**和 base64 嵌入
- **视频支持** — 直接将视频发送给视觉模型进行分析（MP4、MOV、AVI、MKV、WebM）
- 大尺寸图片自动缩放
- 支持的图片格式：PNG、JPG、JPEG、GIF、BMP、WebP、TIFF

### 会话与历史

- **持久化会话**，基于 SQLite 的检查点存储（LangGraph）
- 会话列表、切换、重命名、删除
- **上下文压缩** — 接近 token 上限时自动摘要
- 状态栏实时显示**上下文使用量**

### Git 集成

- 编辑消息时工作目录**自动回滚**
- 从任意消息**创建分支**（fork）
- 通过 `/messages` 编辑 / fork / 删除历史消息
- 状态栏显示检查点计数

### 人工审核

- **Common 模式** — 每次工具调用需要确认，编辑操作显示 diff 预览。仅可使用 Explore 和 Plan 子代理
- **YOLO 模式** — 自动批准所有操作。所有子代理可用，包括 General-purpose
- 通过 `Tab` 键或 `/mode` 命令切换
- 切换模式时自动更新可用子代理列表

### 工作环境隔离

- 每个项目独立的 `.chat/` 目录存放会话、技能、代理
- 全局 `~/.chat/` 存放共享技能和设置
- `/workdir` 切换项目根目录

### 跨平台

- **Windows** — 默认使用 Git Bash，回退到 PowerShell
- **Linux / Mac** — 原生 bash/zsh
- 持久化 Shell 会话，**自动追踪 CWD**

### 终端 UI

- 实时**状态栏** — 上下文使用率、Git 检查点数、ModelScope API 配额
- **流式输出**，逐 token 渲染
- 斜杠命令自动补全
- 彩色工具审核界面，文件编辑显示**行内 diff 预览**

### 可观测性

- **LangSmith 追踪** — 通过 `/langsmith` 命令开关
- 遇到 429 限流时自动禁用追踪并通知用户

### 子代理系统

- 三种内置代理类型：**Explore**（代码库搜索，只读）、**Plan**（架构设计，只读）、**General-purpose**（全能力编程）
- **模式感知可用性** — 普通模式：仅 Explore + Plan；YOLO 模式：全部三种 + 自定义代理
- **并行执行** — 同时启动多个代理处理独立任务，带实时旋转进度显示
- 子代理运行在**隔离上下文**中，保护主对话不被上下文污染
- 只读代理（Explore、Plan）具有 **bash 命令限制**，防止误修改
- **自定义代理** — 在 `.chat/agents/` 中定义自己的代理类型，配备专属工具和指令

### 技能系统

- 通过 `/skill` 安装 / 删除 / 管理技能
- 技能通过 LangChain 中间件注入系统提示
- 支持项目级和全局技能目录

### ModelScope 限额监控

- 状态栏实时显示 **API 配额**（每日剩余额度、每模型剩余额度）
- 使用 ModelScope 模型时自动启用

## 内置工具（14 个）

| 工具 | 说明 |
|------|------|
| `read` | 读取文件内容，支持行号和偏移量 |
| `write` | 创建或覆盖文件 |
| `edit` | 精准字符串替换编辑现有文件 |
| `glob` | 按文件名模式查找文件 |
| `grep` | 用正则搜索文件内容 |
| `list_dir` | 浏览目录结构 |
| `bash` | 执行 Shell 命令（Git Bash / PowerShell / bash） |
| `load_skill` | 通过中间件动态加载技能指令 |
| `web_fetch` | 抓取 URL 内容并转换为 Markdown |
| `web_search` | 通过 [Tavily](https://tavily.com) 进行网络搜索 |
| `ask_user` | 单选、多选、批量问题与用户交互 |
| `agent` | 启动子代理（Explore、Plan、YOLO 模式下含 General-purpose、custom），支持并行执行 |
| `todo_write` | 结构化任务追踪，适用于复杂多步骤工作 |
| `vision` | 通过视觉模型分析图片和视频 |

## 快速开始

### 安装

```bash
# 稳定版（PyPI）— 三选一
pip install chcode        # pip
uv tool install chcode    # uv（推荐）
pipx install chcode       # pipx

# 最新版（GitHub）— 二选一
uv tool install git+https://github.com/ScarletMercy/chcode.git    # uv（推荐）
pipx install git+https://github.com/ScarletMercy/chcode.git       # pipx

# 开发测试（从源码）
git clone https://github.com/ScarletMercy/chcode.git
cd chcode
pip install -e .       # 或: uv sync && uv run chcode
```

### 运行

```bash
# 启动交互式会话
chcode

# 以 YOLO 模式启动
chcode --yolo

# 模型管理
chcode config new    # 添加新模型
chcode config edit   # 编辑当前模型
chcode config switch # 切换模型
```

### 首次运行

首次启动时，ChCode 会：

1. 扫描环境变量中的已知 API Key
2. 引导你完成模型配置
3. 可选配置 Tavily 用于网络搜索

## 命令

| 命令 | 说明 |
|------|------|
| `/new` | 新建会话 |
| `/history` | 浏览和切换会话 |
| `/model` | 模型管理（新建 / 编辑 / 切换） |
| `/vision` | 视觉模型配置 |
| `/messages` | 编辑 / fork / 删除历史消息 |
| `/compress` | 压缩当前会话 |
| `/skill` | 管理技能 |
| `/search` | 配置 Tavily API Key |
| `/workdir` | 切换工作目录 |
| `/mode` | 切换 Common / YOLO 模式 |
| `/git` | 显示 Git 状态 |
| `/langsmith` | 开关 LangSmith 追踪 |
| `/tools` | 列出内置工具 |
| `/quit` | 退出 |

## 快捷键

| 按键 | 操作 |
|------|------|
| `Enter` | 发送消息 |
| `Ctrl+Enter` | 换行 |
| `Tab` | 切换 Common/YOLO 模式（输入为空时） |
| `Ctrl+C` | 中断生成 |

## 为什么不用 MCP？

ChCode 故意不集成 MCP（Model Context Protocol）。**技能 + CLI 工具**的组合覆盖了 95%+ 的真实编程代理场景。技能通过中间件注入结构化、可复用的指令 — 比 MCP 服务器更简单、更快、更轻量。

## 架构

```
chcode/
├── cli.py                  # Typer CLI 入口
├── chat.py                 # REPL 主循环、斜杠命令、人工审核
├── agent_setup.py          # 代理构建、中间件、模型重试与回退
├── config.py               # 模型配置、Tavily、环境变量检测
├── display.py              # Rich 渲染、流式输出、状态栏
├── prompts.py              # 交互式提示（选择/确认/文本）
├── vision_config.py        # 视觉模型配置管理
├── agents/
│   ├── definitions.py      # 代理类型（explore、plan、general）
│   ├── loader.py           # 从 .chat/agents/ 加载自定义代理
│   └── runner.py           # 子代理执行（含中间件）
└── utils/
    ├── tools.py            # 内置工具
    ├── enhanced_chat_openai.py  # 扩展 ChatOpenAI，支持 reasoning
    ├── frontmatter.py      # YAML Frontmatter 解析
    ├── git_checker.py      # Git 可用性检查
    ├── git_manager.py      # Git 检查点管理
    ├── json_utils.py       # JSON 原子读写 + mtime 缓存
    ├── modelscope_ratelimit.py  # ModelScope API 限额监控
    ├── multimodal.py       # 多模态模型检测与媒体编码
    ├── session.py          # 会话管理器（SQLite）
    ├── skill_loader.py     # 技能发现与加载
    ├── skill_manager.py    # 技能安装/删除 UI
    ├── text_utils.py       # 消息内容文本提取
    ├── tool_result_pipeline.py  # 输出截断与预算控制
    └── shell/
        ├── provider.py     # Shell 提供者抽象（Bash/PowerShell）
        ├── session.py      # 交互式 Shell 会话
        ├── output.py       # 输出捕获与临时文件
        ├── result.py       # 执行结果数据类
        └── semantics.py    # 输出语义分析（错误检测等）
```

## 许可证

MIT
