CC Code Python

Code Author: GPT-5.4 & GLM-5 & Doubao-Seed-Code-2.0

WARNING: 本项目绝大部分为AI生成代码

1. 此项目仅用于个人探究 CC Code 基本工具调用原理、系统提示词、工具提示词设计，仅用于个人学习，不保证更新和维护。
2. 此项目的部分前端组件(例如代码diff view)来源于 toad，也是一个Python AI TUI。

cc-py 是根据 CC Code 提示词构建的 Python AI 编程终端，当前聚焦核心 agent 能力：Agent核心循环、OpenAI 兼容 /v1/chat/completions、基础文件与 shell 工具，以及与上游保持一致的提示词和交互语义，其他高级特性（例如skills系统或其他高级特性）暂不考虑。

欢迎界面	Code Diff渲染
Sessions 管理	Markdown 渲染

Features

核心功能

• TUI交互界面：基于 Textual 的现代化终端用户界面
• 流式响应：支持流式响应、工具调用、工具结果回填
• OpenAI 兼容：使用官方 OpenAI Python SDK，支持所有 OpenAI 兼容的 API
• 工具集：Read、Write、Edit、Glob、Grep、Bash
• 系统提示词对齐：与 TypeScript 版本保持一致的系统提示词和工具描述
• HTTP 前后端统一：cc-api 同时提供 API 和浏览器界面，cc-py 通过 HTTP 连接

TUI 特性

• 支持各种终端主题：内置多种终端主题，可在配置中切换
• 推理/思考内容支持：显示模型的推理过程
• 上下文使用提示：TUI 输入框下方实时显示上下文占用情况（已用/总量/百分比）
• 高性能 Markdown 渲染：TUI 使用虚拟化 Markdown 组件，针对长输出和流式追加做了性能优化，同时保留文本选择、复制和目录跳转能力
• 内联 Diff 展示：Edit 和 Write 工具结果以 diff 格式呈现
• 多行输入支持：Enter 提交，Shift+Enter 换行
• 输入历史导航：上下键导航历史输入，持久化到 ~/.cc-py/input_history.json
• 文件引用扩展：支持 @file_path 语法在消息中引用文件内容，自动展开并显示
• @web 搜索：支持 @web 语法触发 Web 搜索能力（需配置 tavily skills，详见下方说明）

浏览器界面特性 (实验)

• 现代化浏览器界面：由 cc-api 提供的 Vue + FastAPI 响应式界面
• Markdown 渲染：支持完整的 Markdown 语法渲染，代码高亮显示
• 流式响应：实时显示 AI 响应流，支持流式输出
• 会话管理：创建、切换、恢复历史会话，会话持久化存储
• 工具调用可视化：清晰展示工具调用过程和结果
• Diff 内容渲染：Edit 和 Write 工具结果以 diff 格式呈现，直观显示文件变更

TUI Session 管理

• Session 持久化：每次 TUI 对话自动分配唯一 session ID，持久化到 ~/.cc-py/sessions/
• Session 恢复：通过 --resume <session_id> 或 --sessions 选择恢复历史会话
• Session 切换：TUI 内使用 /sessions 命令切换到其他保存的会话
• 新建 Session：TUI 内使用 /clear 命令开始新会话，无需重启应用

安装

要求：

• MacOS / Linux / Windows(仅支持WSL启动)
• ripgrep (rg) - Grep 工具依赖

WSL下需要 export COLORTERM=truecolor，否则配色不正常

安装 ripgrep

Grep 工具依赖系统安装的 ripgrep 命令行工具。请根据你的操作系统安装：

# macos
brew install ripgrep
# ubuntu
sudo apt-get install ripgrep

用户安装（推荐）

通过 npm 安装稳定版本：

npm install -g @thundervvv/cc-py

开发安装

从源码安装（需要 Python 3.12+）：

git clone https://github.com/ThunderVVV/claude-code-python.git
cd claude-code-python
pip install -e .

运行

安装方式	命令
npm 安装	cc-py
pip 开发安装	cc-py-dev

TUI 模式

默认启动 TUI（自动启动 API 服务器）：

cc-py          # npm 安装
cc-py-dev      # pip 开发安装

浏览器界面模式（实验特性）

启动 API 服务器，访问 http://localhost:8000/：

cc-py api      # npm 安装
cc-py-dev api  # pip 开发安装

TUI 命令

• /model：显示当前模型和可用模型 ID（从服务器获取）
• /model <model_id>：实时切换当前 session 的模型，并同步更新 settings.json
• /debug：弹出调试窗口，查看当前 QueryEngine 成员变量状态

调试模式

cc-py --debug          # npm 安装
cc-py-dev --debug      # pip 开发安装

日志自动写入当前目录下的 .logs。

配置

配置统一保存在 ~/.cc-py/settings.json。

示例：

{
  "current_model": "gpt-4-1",
  "theme": "atom-one-dark",
  "models": {
    "gpt-4-1": {
      "api_key": "your-api-key",
      "api_url": "https://api.openai.com/v1",
      "model_name": "gpt-4.1",
      "context": 128000
    }
  }
}

说明：

• current_model：当前默认模型配置 ID
• theme：cc-py 的 TUI 主题，默认 atom-one-dark, 可选 tokyo-night等其他textual支持主题
• models.<id>：每个模型固定包含 api_key、api_url、model_name、context

可选 Skills（@web 搜索功能）

项目支持 @web 语法触发 Web 搜索能力。此功能通过解析 .claude/skills/ 目录下的 skill 文件实现，将搜索提示附加到输入消息中。

如需使用 @web Web 搜索功能，需准备以下 skills：

1. tavily-search - Web 搜索能力
2. tavily-extract - Web 内容提取能力

安装方式：在项目根目录创建 .claude/skills/ 目录，并将 skill 文件放入其中：

.claude/
└── skills/
    ├── tavily-search/
    │   └── SKILL.md
    └── tavily-extract/
        └── SKILL.md

注：

• skills 需要自行获取或编写，本项目不包含这些文件
• 本项目不支持完整的 skills 系统，仅通过解析固定路径的 SKILL.md 文件实现 @web 功能

架构说明

本项目有两条独立的运行路径：

TUI 路径
REPLScreen -> CCCodeHttpClient --HTTP--> cc-api -> QueryEngine -> OpenAIClient

Web 路径
Browser(Vue) -> cc-api(FastAPI) -> QueryEngine -> OpenAIClient

• cc-py（npm 安装）和 cc-py-dev（pip 安装）提供所有功能：默认启动 TUI（自动启动 API 服务器），api 子命令只启动 API 服务器
• TUI 客户端通过 CCCodeHttpClient 连接 API 服务器
• 两条路径共享核心提示词、消息模型、工具实现和 OpenAI-compatible 配置

许可证

MIT License