473 lines
16 KiB
Markdown
Executable File
473 lines
16 KiB
Markdown
Executable File
# 嘉陵江-code (Jialing Code)
|
||
|
||
<p align="center">
|
||
<strong>🖥️ 终端 AI 编程助手 — 支持 22+ 大模型厂商，默认本地 Ollama 零配置启动</strong>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<a href="#快速开始">快速开始</a> •
|
||
<a href="#支持的模型厂商">模型厂商</a> •
|
||
<a href="#功能特性">功能特性</a> •
|
||
<a href="#项目架构">架构</a> •
|
||
<a href="#配置指南">配置</a> •
|
||
<a href="#常见问题">FAQ</a>
|
||
</p>
|
||
|
||
---
|
||
|
||
## 简介
|
||
|
||
**嘉陵江-code** 是一个基于终端的 AI 编程助手 CLI 工具，fork 自 Anthropic Claude Code 并进行了深度改造，核心目标是：
|
||
|
||
- **多模型支持**：不再绑定 Anthropic 单一厂商，通过 OpenAI 兼容接口统一接入 22+ 大模型厂商
|
||
- **本地优先**：默认使用本地 Ollama，无需 API Key、无需联网、零配置即可启动
|
||
- **保留核心能力**：完整的 REPL 交互、工具系统、权限管理、MCP 协议支持
|
||
- **国内厂商友好**：深度适配 DeepSeek、通义千问、智谱、月之暗面、豆包等国内主流大模型
|
||
|
||
```
|
||
$ jialing-code
|
||
╭──────────────────────────────────────╮
|
||
│ 嘉陵江-code v1.3.14 │
|
||
│ Provider: Ollama (qwen3.5:35b) │
|
||
│ Type /help for commands │
|
||
╰──────────────────────────────────────╯
|
||
>
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- [Bun](https://bun.sh/) >= 1.3.11（**必须最新版本**，旧版有兼容性问题，请先 `bun upgrade`）
|
||
- （可选）[Ollama](https://ollama.com/) — 本地模型运行时
|
||
- （可选）任意云端大模型的 API Key
|
||
|
||
### 安装与运行
|
||
|
||
```bash
|
||
# 1. 克隆仓库
|
||
git clone https://github.com/claude-code-best/claude-code.git
|
||
cd claude-code
|
||
|
||
# 2. 安装依赖
|
||
bun install
|
||
|
||
# 3. 开发模式运行（看到版本号 888 说明启动成功）
|
||
bun run dev
|
||
|
||
# 4. 构建
|
||
bun run build
|
||
|
||
# 5. 构建后运行（Bun 或 Node.js 均可）
|
||
bun dist/cli.js
|
||
node dist/cli.js
|
||
```
|
||
|
||
### 全局安装（可选）
|
||
|
||
构建后可以发布到私有 npm 源，或直接全局链接：
|
||
|
||
```bash
|
||
bun run build
|
||
bun link # 全局可用 jialing-code / jl 命令
|
||
```
|
||
|
||
### 首次运行
|
||
|
||
首次运行会进入 **交互式配置向导**，引导你选择模型厂商、填写 API Key、选择模型。也可以通过环境变量预先配置：
|
||
|
||
```bash
|
||
# 方式一：使用本地 Ollama（默认，无需任何配置）
|
||
jialing-code
|
||
|
||
# 方式二：通过环境变量指定厂商
|
||
export PROVIDER=deepseek
|
||
export DEEPSEEK_API_KEY=sk-xxx
|
||
jialing-code
|
||
|
||
# 方式三：使用 --setup 重新配置
|
||
jialing-code --setup
|
||
```
|
||
|
||
## 支持的模型厂商
|
||
|
||
嘉陵江-code 通过统一的 OpenAI 兼容适配器接入所有厂商，无需关心各家 API 差异。
|
||
|
||
### 国际厂商
|
||
|
||
| 厂商 | 环境变量 | 默认模型 | 代表模型 |
|
||
|------|---------|---------|---------|
|
||
| **Anthropic** | `ANTHROPIC_API_KEY` | claude-sonnet-4-20250514 | Claude Opus/Sonnet/Haiku |
|
||
| **OpenAI** | `OPENAI_API_KEY` | gpt-4o | GPT-4o, GPT-4.1, o3, o4-mini |
|
||
| **Google Gemini** | `GOOGLE_API_KEY` | gemini-2.5-flash | Gemini 2.5 Pro/Flash |
|
||
| **Mistral AI** | `MISTRAL_API_KEY` | mistral-large-latest | Mistral Large, Codestral |
|
||
| **Groq** | `GROQ_API_KEY` | llama-3.3-70b-versatile | Llama 3.3, Mixtral |
|
||
| **xAI** | `XAI_API_KEY` | grok-3 | Grok 3, Grok 3 Mini |
|
||
| **Together AI** | `TOGETHER_API_KEY` | meta-llama/Llama-3.3-70B | Llama, Qwen, DeepSeek |
|
||
| **Cohere** | `COHERE_API_KEY` | command-a-03-2025 | Command A/R+ |
|
||
| **Perplexity** | `PERPLEXITY_API_KEY` | sonar-pro | Sonar Pro/Reasoning |
|
||
|
||
### 国内厂商
|
||
|
||
| 厂商 | 环境变量 | 默认模型 | 代表模型 |
|
||
|------|---------|---------|---------|
|
||
| **DeepSeek** | `DEEPSEEK_API_KEY` | deepseek-chat | DeepSeek V3, R1 |
|
||
| **通义千问 (Qwen)** | `QWEN_API_KEY` | qwen-max | Qwen Max/Plus/Turbo, QwQ |
|
||
| **智谱 (GLM)** | `ZHIPU_API_KEY` | glm-4-plus | GLM-4 Plus/Flash/Long |
|
||
| **月之暗面 (Kimi)** | `MOONSHOT_API_KEY` | moonshot-v1-auto | Kimi 全系列 |
|
||
| **豆包 (Doubao)** | `DOUBAO_API_KEY` | doubao-1.5-pro-256k | 豆包 Pro/Lite |
|
||
| **百度文心 (Ernie)** | `BAIDU_API_KEY` | ernie-4.5-8k | ERNIE 4.5/4.0/Speed |
|
||
| **零一万物 (Yi)** | `YI_API_KEY` | yi-lightning | Yi Lightning/Large |
|
||
| **阶跃星辰 (Step)** | `STEPFUN_API_KEY` | step-2-16k | Step 2/1 全系列 |
|
||
| **百川 (Baichuan)** | `BAICHUAN_API_KEY` | Baichuan4 | Baichuan 4/3 |
|
||
| **MiniMax** | `MINIMAX_API_KEY` | MiniMax-Text-01 | MiniMax Text/Abab |
|
||
| **讯飞星火 (Spark)** | `SPARK_API_KEY` | general-v3.5 | Spark Max/Ultra/Pro |
|
||
| **腾讯混元** | `HUNYUAN_API_KEY` | hunyuan-turbo | 混元 Turbo/Pro/Lite |
|
||
|
||
### 聚合平台 & 本地
|
||
|
||
| 平台 | 环境变量 | 说明 |
|
||
|------|---------|------|
|
||
| **Ollama** | 无需 Key | 本地运行，默认 `qwen3.5:35b`，零配置 |
|
||
| **SiliconFlow** | `SILICONFLOW_API_KEY` | 国内聚合平台，支持多家模型 |
|
||
| **OpenRouter** | `OPENROUTER_API_KEY` | 国际聚合平台，统一接入 |
|
||
|
||
### 企业级部署
|
||
|
||
| 平台 | 环境变量 | 说明 |
|
||
|------|---------|------|
|
||
| **AWS Bedrock** | `CLAUDE_CODE_USE_BEDROCK=1` | 需配置 AWS 凭证 |
|
||
| **Google Vertex** | `CLAUDE_CODE_USE_VERTEX=1` | 需配置 GCP 凭证 |
|
||
| **Azure Foundry** | `CLAUDE_CODE_USE_FOUNDRY=1` | 需配置 Azure AD |
|
||
|
||
## 功能特性
|
||
|
||
### 核心能力
|
||
|
||
| 能力 | 状态 | 说明 |
|
||
|------|------|------|
|
||
| REPL 交互界面 | ✅ | 基于 Ink 的终端 UI，完整交互体验 |
|
||
| 流式对话与工具调用 | ✅ | 流式输出 + 自动工具调用循环 |
|
||
| 会话引擎 | ✅ | 管理对话状态、上下文压缩、归因追踪 |
|
||
| 权限系统 | ✅ | plan/auto/manual 三种模式，细粒度控制 |
|
||
| Hook 系统 | ✅ | pre/post tool use 钩子，通过 settings.json 配置 |
|
||
| 会话恢复 | ✅ | `/resume` 恢复历史会话 |
|
||
| 自动压缩 | ✅ | 超长对话自动 compact，节省 token |
|
||
| MCP 协议 | ✅ | 支持 Model Context Protocol 扩展 |
|
||
| 多厂商适配 | ✅ | 22+ 厂商统一 OpenAI 兼容接口 |
|
||
| 思考链支持 | ✅ | 适配 DeepSeek R1、Qwen thinking 等推理模型 |
|
||
|
||
### 内置工具
|
||
|
||
| 工具 | 功能 |
|
||
|------|------|
|
||
| **BashTool** | Shell 命令执行，支持沙箱模式 |
|
||
| **FileReadTool** | 文件 / PDF / 图片 / Notebook 读取 |
|
||
| **FileEditTool** | 精确字符串替换编辑 + diff 追踪 |
|
||
| **FileWriteTool** | 文件创建与覆写 |
|
||
| **GlobTool** | 文件模式搜索 |
|
||
| **GrepTool** | 内容正则搜索 |
|
||
| **AgentTool** | 子代理（fork / async / background） |
|
||
| **WebFetchTool** | URL 抓取 → Markdown 转换 |
|
||
| **WebSearchTool** | 网页搜索 + 域名过滤 |
|
||
| **NotebookEditTool** | Jupyter Notebook 编辑 |
|
||
|
||
### 斜杠命令 (90+)
|
||
|
||
常用命令：
|
||
|
||
| 命令 | 功能 |
|
||
|------|------|
|
||
| `/help` | 显示帮助信息 |
|
||
| `/model` | 切换模型 |
|
||
| `/config` | 查看/修改配置 |
|
||
| `/compact` | 手动压缩上下文 |
|
||
| `/diff` | 查看文件变更 |
|
||
| `/doctor` | 环境诊断 |
|
||
| `/resume` | 恢复历史会话 |
|
||
| `/memory` | 管理持久记忆 |
|
||
| `/mcp` | 管理 MCP 服务器 |
|
||
| `/plan` | 进入规划模式 |
|
||
| `/permissions` | 权限管理 |
|
||
| `/theme` | 切换主题 |
|
||
| `/export` | 导出对话 |
|
||
| `/vim` | Vim 模式 |
|
||
|
||
## 配置指南
|
||
|
||
### 配置文件位置
|
||
|
||
```
|
||
~/.jialing-code/
|
||
├── config.json # 主配置（厂商、模型、API Key）
|
||
├── settings.json # 行为设置（hooks、权限规则）
|
||
├── memory/ # 持久记忆存储
|
||
└── sessions/ # 会话历史
|
||
```
|
||
|
||
### 环境变量配置
|
||
|
||
```bash
|
||
# ── 厂商选择（二选一） ──
|
||
|
||
# 方式一：指定厂商名
|
||
export PROVIDER=deepseek # 厂商名（小写）
|
||
export DEEPSEEK_API_KEY=sk-xxx # 对应 API Key
|
||
|
||
# 方式二：自动检测（根据已设置的 API Key 自动识别）
|
||
export OPENAI_API_KEY=sk-xxx # 设了哪个就用哪个
|
||
|
||
# ── Anthropic 原生模式 ──
|
||
export ANTHROPIC_API_KEY=sk-ant-xxx # Anthropic 直连
|
||
export ANTHROPIC_MODEL=claude-sonnet-4-20250514 # 可选，指定模型
|
||
|
||
# ── 自定义 API 端点 ──
|
||
export OPENAI_BASE_URL=https://your-proxy.com/v1 # 自定义兼容端点
|
||
export OPENAI_API_KEY=your-key
|
||
|
||
# ── 其他 ──
|
||
export CLAUDE_CODE_SIMPLE=1 # 简洁模式（去掉装饰）
|
||
```
|
||
|
||
### 交互式配置
|
||
|
||
```bash
|
||
# 首次启动自动进入，或手动触发
|
||
jialing-code --setup
|
||
```
|
||
|
||
配置向导会：
|
||
1. 列出所有支持的厂商
|
||
2. 验证 API Key 连通性
|
||
3. 拉取可用模型列表供选择
|
||
4. 保存到 `~/.jialing-code/config.json`
|
||
|
||
## 项目架构
|
||
|
||
```
|
||
jialing-code/
|
||
├── src/
|
||
│ ├── entrypoints/
|
||
│ │ ├── cli.tsx # 入口：polyfill + 快速路径分发
|
||
│ │ └── sdk/ # SDK 导出
|
||
│ ├── main.tsx # Commander.js CLI 定义
|
||
│ ├── query.ts # API 查询核心（流式 + 工具循环）
|
||
│ ├── QueryEngine.ts # 会话引擎（状态管理 + 压缩）
|
||
│ ├── services/
|
||
│ │ └── api/
|
||
│ │ ├── claude.ts # Anthropic 原生 API 客户端
|
||
│ │ ├── openaiAdapter.ts # OpenAI 兼容适配器（核心）
|
||
│ │ ├── providerRegistry.ts # 22+ 厂商注册表
|
||
│ │ ├── client.ts # 客户端工厂
|
||
│ │ └── setupWizard.ts # 交互式配置向导
|
||
│ ├── tools/ # 工具目录（每个工具独立文件夹）
|
||
│ │ ├── BashTool/
|
||
│ │ ├── FileEditTool/
|
||
│ │ ├── FileReadTool/
|
||
│ │ ├── GrepTool/
|
||
│ │ ├── AgentTool/
|
||
│ │ └── ... # 30+ 工具
|
||
│ ├── screens/
|
||
│ │ └── REPL.tsx # REPL 主界面（5000+ 行）
|
||
│ ├── components/ # Ink 终端 UI 组件
|
||
│ ├── commands/ # 斜杠命令实现
|
||
│ ├── state/ # 状态管理（Zustand）
|
||
│ ├── context.ts # 系统提示词构建
|
||
│ └── utils/
|
||
│ └── model/
|
||
│ └── providers.ts # 厂商检测与路由
|
||
├── packages/ # Monorepo workspace 包
|
||
│ ├── @ant/ # Computer Use stub 包
|
||
│ ├── color-diff-napi/ # 颜色 diff（完整实现）
|
||
│ └── *-napi/ # 其他 NAPI stub 包
|
||
├── build.ts # 构建脚本（code splitting）
|
||
├── package.json # Bun workspaces monorepo
|
||
├── tsconfig.json # TypeScript 配置
|
||
└── CLAUDE.md # Claude Code 项目指导
|
||
```
|
||
|
||
### 关键设计
|
||
|
||
#### 多厂商适配层
|
||
|
||
```
|
||
用户请求 → 厂商检测 → OpenAI 兼容适配器 → 各厂商 API
|
||
↓ ↓
|
||
Anthropic 直连 统一消息格式转换
|
||
Bedrock/Vertex 工具调用翻译
|
||
Azure Foundry 思考链处理
|
||
```
|
||
|
||
- **`providerRegistry.ts`**：22+ 厂商的 baseURL、模型列表、API Key 映射
|
||
- **`openaiAdapter.ts`**：将 OpenAI 格式的流式响应实时转换为 Anthropic 内部格式
|
||
- **`providers.ts`**：厂商检测优先级链（显式 > 环境变量 > 自动检测 > Ollama 兜底）
|
||
|
||
#### 工具分层
|
||
|
||
针对非 Anthropic 模型，工具按能力分层：
|
||
|
||
- **Tier 1**（始终可用）：Bash、Read、Write、Edit、Glob、Grep
|
||
- **Tier 2**（中等模型）：WebFetch、WebSearch、NotebookEdit、Agent
|
||
- **跳过**：Anthropic 专属工具（EnterWorktree、TodoWrite 等）
|
||
- **MCP 工具**：始终透传
|
||
|
||
#### 构建流程
|
||
|
||
```bash
|
||
bun run build
|
||
```
|
||
|
||
1. 清理 `dist/` 目录
|
||
2. Bun bundler + code splitting → 入口 `dist/cli.js` + ~450 chunk 文件
|
||
3. 后处理：`import.meta.require` 替换（Node.js 兼容）
|
||
4. Shebang 修正：`#!/usr/bin/env node`
|
||
5. 注入 `globalThis.Bun` polyfill
|
||
|
||
构建产物 **Bun 和 Node.js 均可运行**。
|
||
|
||
## 与原版 Claude Code 的区别
|
||
|
||
| 方面 | 原版 Claude Code | 嘉陵江-code |
|
||
|------|-----------------|-------------|
|
||
| 模型支持 | 仅 Anthropic Claude | 22+ 厂商 + 本地 Ollama |
|
||
| 默认配置 | 需要 API Key | 本地 Ollama 零配置启动 |
|
||
| 国内厂商 | 不支持 | 深度适配 12 家国内厂商 |
|
||
| 思考链 | Claude 原生 | 适配 DeepSeek R1、Qwen thinking 等 |
|
||
| 功能裁剪 | 全功能 | 移除 Computer Use、Voice、Magic Docs 等 |
|
||
| Feature Flags | 内部功能开关 | 全部 `false`（禁用未实现分支） |
|
||
| 运行时 | Bun | Bun 开发 / Bun+Node 运行 |
|
||
| 配置体验 | 需手动配置 | 交互式向导 + 自动检测 |
|
||
|
||
### 已移除/Stub 的模块
|
||
|
||
| 模块 | 状态 | 说明 |
|
||
|------|------|------|
|
||
| Computer Use (`@ant/*`) | Stub | 保留包结构，无实际功能 |
|
||
| NAPI 包 (audio/image/url/modifiers) | Stub | 除 `color-diff-napi` 外均为空实现 |
|
||
| Analytics / GrowthBook / Sentry | 空实现 | 移除遥测 |
|
||
| Magic Docs / Voice Mode / LSP Server | 移除 | 不影响核心功能 |
|
||
| Plugins / Marketplace | 移除 | 不影响核心功能 |
|
||
|
||
## 开发指南
|
||
|
||
### 项目特殊说明
|
||
|
||
- **~1341 个 tsc 错误**：来自反编译，类型多为 `unknown`/`never`/`{}`，**不影响 Bun 运行时**，请勿尝试修复
|
||
- **`feature()` 始终返回 `false`**：所有 feature flag 后的代码是死代码
|
||
- **React Compiler 产物**：组件中大量 `const $ = _c(N)` 是编译器输出的记忆化模板，属正常现象
|
||
- **`bun:bundle` 导入**：构建时 API，开发时由 `cli.tsx` 顶部 polyfill 提供
|
||
|
||
### 常用命令
|
||
|
||
```bash
|
||
# 开发运行
|
||
bun run dev
|
||
|
||
# 构建
|
||
bun run build
|
||
|
||
# Lint（需先安装 biome）
|
||
bun run lint
|
||
bun run lint:fix
|
||
|
||
# 格式化
|
||
bun run format
|
||
|
||
# 依赖检查
|
||
bun run check:unused
|
||
|
||
# 健康检查
|
||
bun run health
|
||
```
|
||
|
||
### 添加新厂商
|
||
|
||
在 `src/services/api/providerRegistry.ts` 中添加条目即可：
|
||
|
||
```typescript
|
||
export const PROVIDER_REGISTRY = {
|
||
// ...
|
||
your_provider: {
|
||
name: 'Your Provider',
|
||
baseURL: 'https://api.your-provider.com/v1',
|
||
defaultModel: 'your-default-model',
|
||
apiKeyEnvVars: ['YOUR_PROVIDER_API_KEY'],
|
||
models: [
|
||
{ id: 'model-1', name: 'Model 1', description: '描述' },
|
||
],
|
||
},
|
||
}
|
||
```
|
||
|
||
只要厂商支持 OpenAI 兼容接口，即可无缝接入。
|
||
|
||
## 常见问题
|
||
|
||
### Q: 安装依赖失败？
|
||
|
||
确保 Bun 为最新版本：
|
||
```bash
|
||
bun upgrade
|
||
bun install
|
||
```
|
||
|
||
### Q: 如何切换模型？
|
||
|
||
运行中使用 `/model` 命令，或设置环境变量：
|
||
```bash
|
||
export PROVIDER=openai
|
||
export OPENAI_API_KEY=sk-xxx
|
||
export ANTHROPIC_MODEL=gpt-4o # 指定具体模型
|
||
```
|
||
|
||
### Q: 本地 Ollama 如何使用？
|
||
|
||
1. 安装 [Ollama](https://ollama.com/)
|
||
2. 拉取模型：`ollama pull qwen3.5:35b`
|
||
3. 启动嘉陵江-code，默认自动连接本地 Ollama
|
||
|
||
### Q: 能否用 Node.js 运行？
|
||
|
||
可以。`bun run build` 后，`node dist/cli.js` 即可运行（构建时已注入 Node.js 兼容 shim）。
|
||
|
||
### Q: tsc 报大量错误？
|
||
|
||
正常现象，来自反编译。不影响运行，请忽略。
|
||
|
||
### Q: 工具调用不工作？
|
||
|
||
部分本地模型（尤其小参数量模型）不支持 function calling。建议使用 7B+ 参数的模型，推荐 `qwen3.5:35b` 或 `deepseek-r1:32b`。
|
||
|
||
## 贡献指南
|
||
|
||
欢迎贡献！请遵循以下流程：
|
||
|
||
1. Fork 本仓库
|
||
2. 创建特性分支：`git checkout -b feature/your-feature`
|
||
3. 提交变更：`git commit -m 'Add your feature'`
|
||
4. 推送分支：`git push origin feature/your-feature`
|
||
5. 创建 Pull Request
|
||
|
||
### 贡献方向
|
||
|
||
- 新增模型厂商适配
|
||
- Bug 修复
|
||
- 文档改进
|
||
- 工具增强
|
||
- 国际化 (i18n)
|
||
|
||
## 许可证
|
||
|
||
本项目采用 [MIT 许可证](LICENSE)。
|
||
|
||
## 致谢
|
||
|
||
- 本项目基于 [Anthropic Claude Code](https://claude.ai/code) 反编译与改造
|
||
- 感谢所有大模型厂商提供的 OpenAI 兼容接口
|
||
- 感谢 [Ollama](https://ollama.com/) 提供的本地模型运行时
|
||
- 感谢 [Bun](https://bun.sh/) 提供的高性能 JavaScript 运行时
|
||
|
||
---
|
||
|
||
**Star ⭐ 这个项目如果对你有帮助！**
|