企业官网建设流程全解析

aider 的/help交互式支持：终端内基于文档检索的 AI 问答与排障

【免费下载链接】aideraider is AI pair programming in your terminal项目地址: https://gitcode.com/GitHub_Trending/ai/aider

在 aider 的日常使用中，你几乎不需要离开终端去查文档：只要输入/help <question>，aider 会基于全量官方文档建立检索增强生成（RAG）问答，结合你当前会话上下文直接给出针对性解答。本指南以 support.md 为核心，讲解/help的用法、典型问答场景，并深入其背后的文档索引、向量检索与源码实现原理，帮助你在配置.env、接入本地大模型、排查异常等场景中最大化利用这个内置支持台。

/help是什么：终端里的“文档问答机器人”

在 aider 会话中输入：

/help <question>

aider 就会以当前提问为检索条件，找到最相关的官方文档片段并与大模型共享，从而返回有用的解答。你可以用它询问几乎所有话题：

• aider 的基本用法；
• 如何自定义配置（例如.env、模型别名、编辑格式）；
• 各类故障排查；
• 如何接入不同的 LLM 提供商。

这一定位与仓库中的命令表一致：commands.md 将/help列为“Ask questions about aider”，而在多种聊天模式（code / architect / ask / help）的介绍页 modes.md 中，/help也被当作切换讨论方式的一个入口。

每个会话启动时，aider 都会打印类似下面的一行提示（commands.py 中的basic_help也会在列出全部斜杠命令后追加同一句话）：

Use /help <question> to ask for help, run with --help to see cmd line args

注意区分两者：/help <question>是在正在进行的会话内做“语义问答”，而--help是命令行参数列表。

不带问题输入/help时

如果直接输入/help（不带问题），会打印所有内置斜杠命令及其说明。在 commands.py 的cmd_help实现中可以看到这一分支：args.strip()为空时调用basic_help()后直接返回。

两个典型问答实录

原文档通过两段真实聊天记录展示了/help的问答形态，下面完整复现其核心内容，帮助理解回答风格与信息组织方式。

实录一：.env文件是全局生效还是仅针对某个 git 仓库？

输入/help is the .env file global or for a git repo?，aider 会基于检索到的文档给出如下回答：

.env文件既可以是全局的，也可以只针对某个 git 仓库。Aider 会在多个位置查找.env文件，加载优先级顺序为：

1. 你的主目录（全局）；
2. git 仓库的根目录（仓库级）；
3. 当前目录；
4. 通过--env-file <filename>参数指定的文件。

如果这些位置存在多个.env，会按上述顺序依次加载，后加载的文件优先级更高。因此你可以在主目录放一个全局.env存放通用设置，再在具体 git 仓库的根目录放一个仓库级.env做覆盖或补充，从而实现“全局默认 + 按项目覆盖”的灵活配置。

这段回答在仓库文档 dotenv.md 中有完全对应的描述，且其正文进一步说明：.env不仅能存放各家模型的 API Key，还可以写入几乎所有 aider 选项（通过AIDER_*前缀的环境变量形式）。仓库内置了一份可直接参考的示例文件 sample.env，其头部注释即建议“放在 git 仓库根目录，或用aider --env <fname>指定”，其中包含类似这样的条目：

# Place at the root of your git repo. # Or use `aider --env <fname>` to specify. ## OpenAI #OPENAI_API_KEY= ## Main model: #AIDER_MODEL= ## Specify the api base url #AIDER_OPENAI_API_BASE=

此外，config.md 提供了配置的总体索引，AIDER_ENV_FILE（默认.env，位于 git 根目录）与命令行参数--env-file对应。

实录二：能否使用本地大模型（local LLMs）？

输入/help can i use local LLMs?，回答会给出如下要点：

可以。Aider 支持多种本地模型接入方式：

1. Ollama：通过 Ollama 使用本地模型；
2. 兼容 OpenAI 的 API：aider 可访问提供 OpenAI 兼容接口的本地模型服务；
3. 其他本地模型：aider 借助 LiteLLM 包连接各类 LLM 提供商，其中也包括本地运行的选项。

但需要注意：aider 在“能够正确返回代码编辑（code edits）”这一能力上对模型要求较高，能力较弱的模型可能无法可靠返回编辑结果，导致 aider 无法修改文件或完成提交。

仓库中 ollama.md 给出了具体操作：先设置OLLAMA_API_BASE（默认通常是http://127.0.0.1:11434），再用aider --model ollama_chat/<model>启动，且文档明确推荐ollama_chat/前缀而不是ollama/。Ollama 默认 2k 上下文窗口对 aider 偏小且会“静默丢弃”超出内容，因此 aider 默认会为每次请求把窗口设置得足够大（请求大小 + 8k 回复空间）；你也可以通过.aider.model.settings.yml的num_ctx固定窗口大小。若 Ollama 需要鉴权，可设置OLLAMA_API_KEY。更完整的模型接入总览见 llms.md 与 openai-compat.md。

背后原理：文档索引与检索增强生成（RAG）

从源码看，/help并不是把问题原样丢给模型，而是先执行一次本地化的文档检索，再把“相关文档 + 会话上下文”拼装成大模型输入。

索引的构建与缓存

核心实现在 help.py。aider 在打包安装时会把整个aider.website目录的 Markdown 文档作为包资源带上，get_package_files() 递归枚举其中的全部.md文件；get_index() 使用llama_index的MarkdownNodeParser把每篇文档切成节点，再构建VectorStoreIndex向量索引。

索引默认缓存在主目录下的~/.aider/caches/help.<version>（help.py），缓存目录按 aider 版本号区分，损坏时会自动清理重建。构造Help实例时，help.py 指定嵌入模型为 HuggingFace 的BAAI/bge-small-en-v1.5，检索器则固定取相似度最高的前 20 个文档节点（similarity_top_k=20）。

并不是所有文档都会进入索引：help_pats.py 中的exclude_website_pats会排除examples/、_posts/、HISTORY.md、benchmarks/ctags/unified-diffs 等页面以及纯站点资产，保证检索空间聚焦于面向用户的帮助文档。

检索结果如何变成模型上下文

当用户输入问题时，Help.ask() 执行检索，把命中的文档节点包装成带来源的<doc from_url="...">...</doc>片段（from_url由 fname_to_url() 把仓库内的 Markdown 路径映射为官方文档 URL 生成），并在最前面拼上# Question: ...与# Relevant docs:标题。

随后 commands.py 的cmd_help会把这段检索上下文与本次 aider 会话启动时打印的 announcement 行拼接在一起作为用户消息，这样大模型既能检索到全局文档知识，也能感知到“你正在使用哪个版本、哪个模型、哪个 git 仓库”等现场信息。

回答风格由专门的提示词约束

处理/help时，aider 会创建一个编辑格式为help的专用 Coder——HelpCoder 继承自Coder，其edit_format = "help"，并且get_edits()返回空、apply_edits()为空实现，也就是说 help 模式只回答、绝不改文件。

回答风格由 help_prompts.py 中的HelpPrompts.main_system定义，要点包括：

• 角色设定为“aider 的专家”，仅在与用户问题相关时使用提供的文档；
• 需要输出一个裸 URL 列表（不带 Markdown 链接语法），方便用户点开原文；
• 如果不知道答案，要明说，并推荐相关文档 URL；
• 如果用户要求的是 aider 不支持的方案，要明确说明，不做超出能力的承诺；
• 除非问题另有说明，默认用户是在以 CLI 方式使用 aider；
• 系统会注入当前用户平台信息（{platform}）供模型参考。

完整的调用链与首次使用安装提示

汇总整个链路：

1. 用户输入/help <question>，命中 Commands.cmd_help()；
2. 若未安装交互帮助依赖，先调用install_help_extra()（help.py）提示安装aider-chat[help]可选依赖——该依赖包含llama-index-embeddings-huggingface以及受版本约束的torch、numpy、scikit-learn（见 requirements-help.in）；
3. 首次加载会构建/缓存向量索引；
4. 创建 help 格式的 Coder，喂入“检索文档 + 当前会话 announcement”组成的消息并运行；
5. 回答结束后通过SwitchCoder（commands.py）切换回用户原本的编辑格式与模型设置，会话无缝继续，同时保证成本统计仍归属原会话。

上述行为在测试中也有覆盖：test_help.py 验证了cmd_help会触发SwitchCoder且HelpCoder.run被调用一次、Help检索器初始化成功、ask()能返回包含 5 个以上<doc>片段的上下文，以及fname_to_url()对 Unix/Windows 路径的映射规则。

使用建议与注意点

• 把/help当作“带文档依据的 FAQ”：由于检索结果保留了from_url来源，模型倾向于给出可回溯的结论；如果你需要深挖，可以顺着回答让模型继续展开，也可以直接阅读仓库对应文档页面。
• 结合当前会话提问：正因为模型能看到你正在进行的 aider 会话上下文，你可以基于眼前的具体报错、具体配置来提问，得到的建议往往比泛泛搜索更贴近现场。
• 对模型能力保持预期：如果/help返回的只是概念性介绍而无法指导实操，可以追问更具体的参数或步骤；同时请记住 aider 的编辑功能依赖模型返回规范化的代码编辑结构，能力不足的模型即使能“聊天”也可能无法完成可靠的文件修改（见上面“本地模型”实录的提醒）。
• help 模式不会改代码：从HelpCoder的空实现可以看出，/help阶段所有输出都只是建议；若想基于回答真正动手改文件，需要切回 code / architect 等模式。

问题仍未解决时：更多求助渠道与信息准备

如果/help的答案仍无法定位问题，仓库的帮助文档 help.md 建议到项目维护的 Issues 讨论区检索是否已有相同问题，必要时提交新 issue，或加入官方社区群组直接交流。

为了让维护者能快速定位，报告问题时最好提供以下信息：

• aider 版本；
• 正在使用的 LLM 模型；
• aider 启动时打印的 announcement 行。

把启动横幅贴出来是提供这些信息最省事的方式。它通常长这样：

Aider v0.37.1-dev Models: gpt-4o with diff edit format, weak model gpt-3.5-turbo Git repo: .git with 243 files Repo-map: using 1024 tokens

（版本号、模型与仓库统计随实际环境不同而变。）

在此之前，你也可以先翻一翻本仓库 troubleshooting 目录下的其他专题页，例如常见的模型与密钥问题 models-and-keys.md、编辑格式报错 edit-errors.md、Token 超限处理 token-limits.md 等；而无论遇到什么问题，随时都可以回到会话里敲一句：

/help 我遇到了……（描述你的问题）

【免费下载链接】aideraider is AI pair programming in your terminal项目地址: https://gitcode.com/GitHub_Trending/ai/aider