topcode-cli

TOP Code

---

目录

• 项目简介
• 功能亮点
• 快速开始
• 使用示例
• 配置说明
• 安全机制
• 参与贡献
• 开源协议

项目简介

TOP Code 是一款基于 Python 的轻量级终端 AI 代码代理。它能对接任何兼容 OpenAI 格式的 API -- DeepSeek、通义千问、Claude 等 -- 让你在终端里直接完成代码阅读、编写、调试和修复。

作为 Claude Code、Mimo Code 等工具的开源替代方案，TOP Code 的设计目标是：安装快、用着免费、上手简单。不需要 GUI，不受厂商绑定，只要你的终端加上你选的模型。

功能亮点

7 个内置工具 读文件、写文件、增量编辑、正则搜索、语义搜索、列目录、跑命令。AI 自动选择合适的工具。

语义搜索 用自然语言搜索代码库。首次调用自动建索引，后续增量更新。

增量编辑 edit_file 工具精确替换字符串，不重写整个文件。省 token，防误删。

工具调用确认 危险操作（写文件、跑命令）执行前会询问确认。-y 参数可跳过。

多模型支持 兼容所有 OpenAI 格式的 API。改一行配置即可在 DeepSeek、通义千问、Claude 和本地模型之间切换。

安全优先 目录隔离沙箱、高危命令拦截、文件修改前自动备份、API Key 加密存储。

快速开始

环境要求

• Python 3.10 或更高版本
• 任意兼容 OpenAI 格式的 API Key（DeepSeek、通义千问、OpenAI 等）

安装

一条命令安装（推荐）：

npm install -g topcode-cli

需要 Node.js 16+ 和 Python 3.10+。npm 会自动安装 Python 依赖。

或从源码安装：

git clone https://github.com/NeckJie/TOP-Code.git
cd TOP-Code
pip install .

安装完成后，终端输入 topcode --help 验证安装成功。

首次运行

直接启动 TOP Code：

topcode

首次运行会自动弹出交互式配置引导，只需三步：

1. 选择 API 服务商 — 用方向键选择（DeepSeek / 通义千问 / 智谱 AI / OpenAI / Claude / 自定义）
2. 输入 API Key — 密钥保存在本地 ~/.topcode/config.json，不会上传任何服务器
3. 确认模型 — 回车使用默认模型，或输入其他模型名

配置完成后自动进入交互式对话。

也可以通过环境变量配置（优先级更高）：

export LLM_API_KEY="sk-your-key-here"
export LLM_BASE_URL="https://api.deepseek.com/v1"
export LLM_MODEL="deepseek-chat"

或复制 .env.example 为 .env 并填入你的值。

使用示例

交互模式（默认）

topcode

启动后进入对话界面，直接输入需求即可。支持 /help、/model、/config、/exit 等斜杠命令。

单次执行

topcode "这个项目是做什么的？"
topcode run "为 src/utils/parser.py 编写单元测试"

两种写法等价——执行完任务后自动退出。

继续上次对话

topcode -c

自动加载上次退出时的对话历史，继续聊。

实际场景

# 了解项目
topcode "这个项目是做什么的？"

# 修复 Bug
topcode "登录接口返回 500，找到问题并修复"

# 生成代码
topcode "写一个 Python 脚本，批量重命名当前目录下的 .txt 文件"

# 重构
topcode "把数据库模块重构成连接池模式"

# 读取错误日志并修复
topcode "解释这个错误并修复" < error.log

配置说明

TOP Code 从 ~/.topcode/config.json 读取配置。除 api_key 外所有字段均为可选。

{
  "api_key": "sk-...",
  "base_url": "https://api.deepseek.com/v1",
  "model": "deepseek-chat"
}

支持的服务商

任何提供 OpenAI 兼容 API 的服务均可直接使用：

服务商	Base URL	推荐模型
DeepSeek	https://api.deepseek.com/v1	deepseek-chat
通义千问	https://dashscope.aliyuncs.com/compatible-mode/v1	qwen-plus
OpenAI	https://api.openai.com/v1	gpt-4o
Claude（代理）	你的代理地址	claude-sonnet-4-20250514
本地（Ollama）	http://localhost:11434/v1	任意已加载模型

安全机制

TOP Code 采用纵深防御策略保障安全：

目录沙箱 Agent 只能读写项目目录内的文件。运行时会拦截所有试图访问沙箱外部路径的操作。

命令拦截 Shell 命令在执行前会经过黑名单检查。rm -rf /、磁盘格式化、权限提升等高危操作会被直接拒绝。

自动备份 每次文件修改都会在 ~/.topcode/backups/ 生成带时间戳的备份。可通过以下命令回滚：

topcode --restore <backup-id>

审计日志 所有 Agent 操作记录在 ~/.topcode/audit.log，可随时审查。

参与贡献

欢迎贡献代码。为保持项目可维护性，请遵循以下流程：

1. Fork 本仓库
2. 创建功能分支（git checkout -b feature/your-feature）
3. 编写代码并补充测试
4. 确保所有测试通过（pytest）
5. 提交 Pull Request，附上清晰的说明

重大变更请先开 Issue 讨论设计方案。

完整贡献指南见 CONTRIBUTING.md。

开源协议

基于 MIT 协议开源。详见 LICENSE。

---