ChCode：我用 5000 行 Python 写了一个终端 AI 编程助手，开源了！

5000+ 行 Python，13 个内置工具，完整会话持久化，Git 感知工作流，Human-in-the-Loop 审批机制——这是我独立开发的终端 AI 编程代理 ChCode。

前言

自从 AI 编程助手爆火以来，市面上的工具越来越多——Cursor、Copilot、Claude Code……但它们要么绑死在 IDE 里，要么不够透明、不够可控。

我想做一个纯终端、完全透明、用户拥有完全控制权的 AI 编程代理。于是有了 ChCode。

📸 最初的原型——chagent（tkinter + LangChain 的桌面聊天应用）

ChCode 是什么？

ChCode 是一个基于 Python 的终端 AI 编程代理，通过 LangChain + Typer + Rich 构建。它不是 IDE 插件，不是 Web 应用，而是一个在终端中运行的、独立的 AI 编码助手。

简单来说，你在终端里和 AI 对话，它能帮你读文件、写文件、执行命令、搜索代码、管理 Git——完成一整套编码工作流。

核心特性

1. 13 个内置工具，覆盖完整编码流程

工具	功能
read	读取文件内容，支持行号显示和偏移量定位
write	创建或覆盖文件
edit	精确字符串替换，对现有文件进行微创编辑
glob	按文件名模式（通配符）查找文件
grep	正则表达式搜索文件内容
list_dir	浏览目录结构
bash	执行 Shell 命令（Git Bash / PowerShell / bash）
load_skill	动态加载技能指令，通过中间件注入到系统提示
web_fetch	获取 URL 内容并转换为 Markdown
web_search	Web 搜索（基于 Tavily API）
ask_user	用户交互：单选、多选、批量提问
agent	启动子代理（探索型、规划型、通用型），支持并行执行
todo_write	结构化任务跟踪，管理复杂多步骤工作

这 13 个工具的设计参考了 Claude Code、OpenHands 等项目，但做了大量本土化适配和优化。

2. 多模型支持，不绑定任何厂商

ChCode 兼容所有 OpenAI 兼容 API：

• OpenAI（GPT-5.4）
• DeepSeek（DeepSeek-V3.2 / R1）
• 阿里 Qwen（Qwen3.5 / Qwen3.6）
• 智谱 GLM（GLM-5.1 / GLM-5）
• 以及任何 OpenAI 兼容的 API

首次运行时自动扫描环境变量（OPENAI_API_KEY、DEEPSEEK_API_KEY、ZHIPU_API_KEY 等），引导你完成配置。

运行时可以随时切换模型，还能调整 temperature、top_p、top_k、max_tokens、stop_sequences 等超参数。

3. 会话持久化 + 上下文压缩

• 基于 SQLite + LangGraph Checkpoint 实现完整的会话持久化
• 关掉终端、重新打开，会话还在
• 支持会话列表、切换、删除
• 当上下文接近 Token 上限时，自动压缩摘要，不丢失关键信息
• 状态栏实时显示上下文使用量

4. Git 感知工作流

这是 ChCode 最有意思的特性之一：

• 消息编辑回滚：你编辑了一条历史消息，ChCode 会自动把工作目录回滚到那条消息对应的状态
• 消息 Fork：你可以从任意一条历史消息创建新分支，就像 Git 里的 branch
• 通过 /messages 命令编辑、Fork、删除历史消息
• 状态栏显示 Git 检查点计数

这意味着你可以像管理代码一样管理 AI 的对话历史。

5. Human-in-the-Loop 审批机制

ChCode 有两种工作模式：

• Common 模式（默认）：AI 的每一步工具调用都需要你审批，文件编辑会展示 diff 预览
• YOLO 模式：全部自动批准，AI 全速执行

按 Tab 键或输入 /mode 即可切换。

对于关键项目，你可以全程审批；对于实验性任务，一键开启 YOLO 模式让 AI 跑起来。

6. 技能系统（Skill System）

ChCode 没有集成 MCP（Model Context Protocol），而是设计了自己的技能系统：

• 技能本质是结构化的可复用指令模板，通过 LangChain 中间件注入到系统提示
• 支持项目级（.chat/skills/）和全局级（~/.chat/skills/）两个层级的技能
• 通过 /skill 命令安装、删除、管理
• 覆盖 95%+ 的真实编码场景，比 MCP 更简单、更快、更可移植

7. 跨平台 Shell 抽象层

ChCode 实现了完整的 Shell 抽象：

• Windows：默认使用 Git Bash，回退到 PowerShell
• Linux / Mac：原生 bash / zsh
• 持久化 Shell 会话，自动跟踪工作目录

无论你在什么平台上，AI 执行的命令行为都是一致的。

8. 子代理并行执行

通过 agent 工具，ChCode 可以启动三种子代理：

• 探索型（Explore）：快速搜索和分析代码库
• 规划型（Plan）：制定实现计划
• 通用型（General）：执行多步骤任务

子代理支持并行执行，提升复杂任务的效率。

技术架构

chcode/
├── cli.py                  # Typer CLI 入口
├── chat.py                 # REPL 主循环，斜杠命令，HITL
├── agent_setup.py          # Agent 构建，中间件链
├── config.py               # 模型配置，Tavily，环境检测
├── display.py              # Rich 渲染，流式输出，状态栏
├── prompts.py              # 交互式提示（选择/确认/文本）
├── session.py              # 会话管理器（SQLite）
├── skill_manager.py        # 技能安装/删除 UI
├── agents/
│   ├── definitions.py      # 子代理类型定义
│   ├── loader.py           # 从 .chat/agents/ 加载自定义代理
│   └── runner.py           # 子代理执行（含中间件）
└── utils/
    ├── tools.py            # 13 个内置工具
    ├── shell/              # Shell 抽象层（Bash/PowerShell Provider）
    ├── enhanced_chat_openai.py  # 扩展 ChatOpenAI，支持推理模型
    ├── git_manager.py      # Git 检查点管理
    ├── skill_loader.py     # 技能发现与加载
    └── tool_result_pipeline.py  # 输出截断与 Token 预算控制

技术栈

• Python 3.13+
• LangChain — Agent 框架、中间件链、工具系统
• LangGraph — 会话检查点（SQLite 持久化）
• Typer — CLI 框架
• Rich — 终端渲染（Markdown、语法高亮、流式输出、状态栏）
• prompt_toolkit — 多行输入、补全、快捷键
• SQLite — 会话存储
• Tavily — Web 搜索

为什么不用 MCP？

ChCode 故意没有集成 MCP。技能 + CLI 工具 的组合已经覆盖了 95%+ 的真实编码场景。技能提供结构化的、可复用的指令，通过中间件注入——比 MCP Server 更简单、更快、更可移植。

写在最后

这个项目从最初一个 tkinter + LangChain 的聊天原型（chagent），逐步演变成了一个功能完整的终端编程代理。5000+ 行 Python，13 个工具，完整会话管理，Git 集成，Human-in-the-Loop——全部一个人完成。

如果你对终端 AI 编程工具感兴趣，欢迎 Star、Fork、提 Issue：

GitHub：chcode项目地址

安装方式和更多细节请移步 GitHub 仓库 README。如果觉得有用，请给个 Star ⭐，感谢！