Token Switch 文档中心

中文

English

中文

English

Appearance

Aider 配置指南 ​

第一章 - 安装指南 ​

macOS 安装 ​

方式一：使用 Homebrew（推荐） ​

bash
brew install aider-chat

方式二：使用 pip ​

bash
pip install aider-chat

方式三：使用 pipx（推荐） ​

bash
pipx install aider-chat

Windows 安装 ​

方式一：使用 pip ​

powershell
pip install aider-chat

方式二：使用 pipx ​

powershell
pipx install aider-chat

方式三：从源代码安装 ​

powershell
git clone https://github.com/paul-gauthier/aider.git
cd aider
pip install -e .

安装验证 ​

安装完成后，验证 Aider 是否安装成功：

bash
aider --version

第二章 - TokenSwitch 中转 API 配置 ​

环境变量配置 ​

macOS/Linux 配置 ​

编辑 ~/.bash_profile 或 ~/.zshrc 文件：

bash
# 写入配置
echo 'export OPENAI_API_KEY="你的令牌"' >> ~/.zshrc
echo 'export OPENAI_API_BASE={{apiUrl}}' >> ~/.zshrc

# 立即生效
source ~/.zshrc

Windows 配置 ​

在 PowerShell 中执行：

powershell
[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "你的令牌", "User")
[Environment]::SetEnvironmentVariable("OPENAI_API_BASE", "https://neolink.vnet.com/api/v1", "User")

或使用系统环境变量设置。

完整启动参数 ​

基础启动命令 ​

bash
# 使用 Claude Sonnet 4.6（推荐）
aider --model cl-so-4.6

# 使用 Claude Haiku 4.5（轻量级）
aider --model cl-ha-4.5-1001

# 使用其他 Claude 模型
aider --model openai/claude-3-opus-20250514
aider --model cl-ha-4.5-1001

完整参数表 ​

参数说明示例
--model指定模型cl-so-4.6
--api-keyAPI 密钥（可选，默认读取环境变量）sk-xxx
--base-urlAPI 基础 URL
--temperature模型温度（0-2）0.7
--max-tokens最大令牌数4096
--no-auto-commits禁用自动提交无值
--no-dirty禁用脏文件提示无值
--voice启用语音输入无值
--edit启用编辑模式无值

推荐的启动命令 ​

bash
# 基础启动（使用环境变量配置，推荐使用 Claude Sonnet 4.6）
aider --model cl-so-4.6

# 完整配置示例
aider \
  --model cl-so-4.6 \
  --temperature 0.7 \
  --max-tokens 4096 \
  --no-auto-commits

# 指定文件夹启动
aider --model cl-so-4.6 ./src

支持的模型列表 ​

通过 TokenSwitch 可以使用以下模型：

模型 ID描述
cl-ha-4.5-1001Claude Haiku 4.5（轻量级，推荐用于快速任务）
cl-so-4.6Claude Sonnet 4.6（均衡性能和成本，推荐）
openai/claude-3-5-sonnet-20241022Claude 3.5 Sonnet（高性能）
openai/claude-3-opus-20250514Claude 3 Opus（最强模型）
openai/gpt-4-turboGPT-4 Turbo 版本
openai/gpt-4oGPT-4 优化版本
openai/gpt-4GPT-4 基础版本

第三章 - /add 加载文件的路径注意事项 ​

/add 命令基础 ​

/add 命令用于将文件添加到当前对话上下文中：

bash
/add filename.py
/add path/to/file.js
/add src/components/*.vue

路径类型说明 ​

相对路径 ​

相对于当前工作目录：

bash
/add utils.py              # 当前目录下的文件
/add src/main.py           # src 文件夹下的文件
/add ../config/app.yaml    # 上级目录下的文件

绝对路径 ​

完整的文件系统路径：

bash
# macOS/Linux
/add /Users/username/project/src/main.py

# Windows
/add C:\Users\username\project\src\main.py

通配符匹配 ​

支持 glob 模式：

bash
/add src/*.py              # src 目录下所有 Python 文件
/add **/*.js               # 递归匹配所有 JS 文件
/add src/**/*.py           # src 下递归匹配所有 Python 文件
/add tests/test_*.py       # 匹配 test_ 开头的文件

Windows 路径特殊处理 ​

Windows 使用反斜杠 \ 作为路径分隔符：

powershell
# ✅ 正确方式
/add src\models\user.py
/add C:\project\src\main.py

# 也可以使用正斜杠（推荐）
/add src/models/user.py
/add C:/project/src/main.py

路径常见错误及解决方案 ​

错误原因解决方案
File not found路径不正确检查相对路径或使用绝对路径
Permission denied没有读取权限检查文件权限
Path too longWindows 路径超过 260 字符使用相对路径或启用长路径支持
中文路径问题编码问题使用绝对路径或检查系统编码

忽略文件配置 ​

在项目根目录创建 .aiderignore 文件：

node_modules/
__pycache__/
*.pyc
.git/
.env
build/
dist/
*.log

文件加载最佳实践 ​

  1. 一次加载的文件数量：建议 5-10 个文件以内
  2. 文件大小限制：单个文件建议不超过 100KB
  3. 优先级顺序：先加载核心文件，再加载依赖文件
  4. 增量加载：根据需要逐步添加文件，而不是一次性加载整个项目

第四章 - 常用内置指令说明 ​

文件管理指令 ​

指令说明示例
/add添加文件到上下文/add src/main.py
/drop从上下文移除文件/drop src/main.py
/list列出当前上下文中的文件/list
/ls/list 的简写/ls
/files显示文件列表和大小/files

编辑与提交指令 ​

指令说明示例
/undo撤销最后一次编辑/undo
/diff查看当前所有未提交的更改/diff
/commit提交当前更改到 Git/commit -m "message"
/reset重置所有更改/reset

会话管理指令 ​

指令说明示例
/clear清空对话历史/clear
/exit退出 Aider/exit
/help显示帮助信息/help
/history查看命令历史/history

高级指令 ​

指令说明示例
/architect切换到架构模式/architect
/auto自动修复所有文件/auto
/lint运行代码 linter/lint
/test运行测试/test
/git执行 Git 命令/git status

特殊命令 ​

bash
# 获取帮助
/help              # 显示所有可用指令
/?                 # 同 /help

# 查询信息
/stats             # 显示令牌使用统计
/version           # 显示 Aider 版本

# 切换模式
/architect         # 架构模式（更详细的规划）
/code              # 代码模式（默认）

第五章 - 完整工作流示例 ​

示例 1：创建新模块 ​

bash
# 1. 启动 Aider
aider --model cl-so-4.6 src/

# 2. 添加相关文件
/add src/models/__init__.py
/add src/models/base.py

# 3. 与 AI 交流
创建一个新的 User 模型，包含 id、name、email 字段

# 4. 查看更改
/diff

# 5. 提交更改
/commit -m "feat: add User model"

示例 2：重构代码 ​

bash
# 1. 添加要重构的文件
/add src/utils/helpers.py
/add src/utils/validators.py

# 2. 请求重构
请将这两个文件中的重复代码提取为公共工具函数

# 3. 查看建议的更改
/diff

# 4. 接受并提交
/commit -m "refactor: extract common utility functions"

示例 3：修复 Bug ​

bash
# 1. 添加相关文件
/add src/services/auth.py
/add tests/test_auth.py

# 2. 描述问题
用户登录失败，错误信息是 "Invalid token"，请检查并修复

# 3. 运行测试验证
/test

# 4. 提交修复
/commit -m "fix: resolve token validation issue in auth service"

第六章 - 故障排查 ​

常见问题解决方案 ​

Q1：无法连接到 API ​

错误信息：Connection refused / Cannot connect to API

解决方案：

  1. 检查网络连接
  2. 验证 OPENAI_API_BASE 是否正确配置
  3. 确认 API 密钥有效
bash
# 验证环境变量
echo $OPENAI_API_KEY
echo $OPENAI_API_BASE

Q2：找不到文件 ​

错误信息：File not found: xxx

解决方案：

  1. 检查相对路径是否正确
  2. 使用绝对路径测试
  3. 确认当前工作目录
bash
# 查看当前目录
pwd

# 列出文件
ls -la src/

Q3：权限被拒绝 ​

错误信息：Permission denied

解决方案：

bash
# 检查文件权限
ls -l filename

# 修改权限
chmod 644 filename

Q4：Windows 路径问题 ​

解决方案：

使用正斜杠而不是反斜杠，或使用完整的 UNC 路径：

powershell
# ✅ 推荐
/add src/models/user.py

# 也可以
/add src\models\user.py

第七章 - 最佳实践 ​

工作流建议 ​

  1. 始终使用 Git：确保所有更改都在 Git 仓库中
  2. 增量加载文件：不要一次性加载整个项目
  3. 明确的需求描述：提供详细的操作说明而不是模糊的指令
  4. 验证更改：在提交前检查 /diff 输出
  5. 定期提交：使用有意义的提交信息

性能优化 ​

  • 一次性加载 5-10 个相关文件效果最佳
  • 对于大型项目，按功能模块分次对话
  • 避免加载二进制文件或生成的文件

最大化效果 ​

  • 提供足够的上下文：添加相关的测试文件和配置文件
  • 使用清晰的中文描述需求
  • 利用 /architect 模式进行复杂重构
  • 在 Git 提交前运行 /diff 检查所有更改

第八章 - 相关资源 ​

官方链接 ​

快速参考 ​

启动命令速查

bash
# macOS/Linux - 推荐使用 Claude Sonnet 4.6
aider --model cl-so-4.6

# Windows PowerShell
aider --model cl-so-4.6

# 指定工作目录
aider --model cl-so-4.6 /path/to/project

常用指令速查

/add file.py          # 添加文件
/drop file.py         # 移除文件
/list                 # 列出文件
/diff                 # 查看更改
/commit -m "msg"      # 提交更改
/undo                 # 撤销操作
/help                 # 显示帮助