ChCode

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

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

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

📸 chagent — 最初的 tkinter 原型

14 个内置工具，完整会话持久化，Git 感知工作流。

English

功能特性

模型管理

• 兼容所有支持 OpenAI 接口的模型（OpenAI、DeepSeek、Qwen、GLM、Claude 代理等）
• 内置魔搭快捷配置（积分制，每天 200-250 魔粒，折合约 100-500 次模型调用）
• 原生支持 reasoning/thinking 模型 — 实时显示思考过程
• 运行时创建 / 编辑 / 切换模型
• 每个模型独立调参（temperature、top_p、top_k、max_completion_tokens 等）
• 指数退避自动重试（3/10/30/60s），持续失败时自动切换备用模型

视觉与多模态

• 通过 /vision 命令独立配置视觉模型（与主模型分离）
• 视觉理解，支持自动媒体编码和 base64 嵌入
• 主模型为多模态模型时会禁用 vision 工具，自动嵌入媒体文件；主模型为文本模型时则通过调用 vision 工具理解媒体文件

会话与历史

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

消息管理与影子仓库（Git 感知）

• 影子仓库隔离 - 历史的编辑、分支引发的工作目录回溯均在独立影子仓库中完成，与用户工作仓库完全隔离，不会污染实际代码
• 编辑 - 修改历史消息时，工作目录自动回滚到该消息对应的状态
• 创建分支 - 从任意消息 fork 出新会话分支和新目录分支，然后对工作目录进行和edit效果相同的回溯
• 删除 - 删除不再需要的历史消息，不会影响工作目录
• 以上操作均通过 /messages 命令完成

人在闭环

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

工作环境隔离

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

跨平台

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

Rich 终端 UI

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

可观测性

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

子代理系统

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

技能系统

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

内置工具（14 个）

快速开始

安装

# 稳定版（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

运行

# 启动交互式会话
chcode

# 以 YOLO 模式启动
chcode --yolo

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

首次运行

首次启动时，ChCode 会：

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

命令

快捷键

为什么不用 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 缓存
    ├── 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