# 嘉陵江-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 ⭐ 这个项目如果对你有帮助！**