架构与注意事项
本页是英文页面的简体中文译文。英文为准，译文可能滞后。
一轮交互如何组织
只初始化一次。 仓库映射、文件索引、项目摘要、AGENTS.md 和当前工作目录（cwd）在启动时构建一次，并在整个会话中保持稳定，使推理引擎的提示词前缀缓存能在多轮交互间保留。只有 /cd 会重新执行初始化。
仓库映射。 每个源文件占一行，列出其导出的定义，并按相关性排序，让仓库中其他文件依赖的文件优先纳入 REIKA_REPO_MAP_BUDGET。它按语言使用正则表达式，而不是解析器，覆盖 TypeScript/JavaScript（导出）、Python、Go、Rust、Java/C#、Kotlin、Swift、C/C++/Objective-C、Ruby、PHP、Lua 和 shell。
工具结果随时间缩减。 每个工具结果包含 summary 和 payload。上下文窗口已知时，payload 会一直保留在请求中，直到接近上限，然后最早的结果在一次事件中被集中缩减，因此两次事件之间的请求只追加内容，推理引擎的前缀缓存得以保留。窗口未知时，只有最新且连续的一组结果会发送 payload。预算和保留内容见上下文管理。
一个系统提示词构建器按模式接收参数，避免各模式的提示词彼此偏离。**一个 AbortController**贯穿流式输出、中止、审批和子智能体。所有通信都使用兼容 OpenAI 的 HTTP 接口，因此本地推理引擎和托管 API 走同一条路径。
上下文与索引
- 启动扫描有上限，按广度优先进行：仓库映射最多读取 4,000 个目录中的 3,000 个源文件，文件索引保留 10,000 个路径，嵌套
.gitignore的查找在 2,000 个目录后停止。超过这些上限的目录树，例如用户主目录或 monorepo，会在约一秒内启动，但生成的是优先覆盖浅层的映射，而非完整映射。因此，应从项目根目录运行 Reika，以获得完整覆盖。 - 索引不会自动更新。 文件索引、仓库映射、
list、glob和grep都会跳过被忽略的路径（见工具），但在 Reika 外部修改的文件，在运行/cd .重新建立索引前仍不可见。
审批
审批默认设为 safe：普通编辑和命令会自动执行；匹配危险模式的命令（rm -rf、rm -f、强制推送、git reset --hard / checkout -- / stash drop、任何软件包安装或卸载、npx、curl/wget、pkill/killall 等），以及任何写入项目外部的操作，都必须先确认。这相当于带有约束的 yolo 模式，放行的操作都可通过 git 恢复。/approvals off（或 REIKA_AUTO_APPROVE=off）要求确认每个操作；如要完全关闭提示，REIKA_AUTO_APPROVE=bypass（或 yolo）会直接运行危险命令，不再询问。
子智能体
子智能体提供的是上下文空间，而非速度：它的读取结果以一份报告传回父智能体，而不是 N 份 payload；代价是子智能体返回时，服务器需要重新预填充父智能体的上下文。质量取决于模型，以下三条规则让能力较弱的模型也能提供有用结果：
- 总会返回结果：预算内的最后一轮强制生成报告。
- 报告末尾列出任务中要求、但尚未读取的文件，让父智能体可以把剩余部分交给第二个子智能体，而不是自己读取。
- 每轮交互最多分派 3 轮子智能体，每轮最多 4 个。较早的报告会保留开头部分（记录执行过程），而不是像普通 payload 那样缩减为字节数。
终端
Cmd+←/→ 是否可用取决于终端配置；Ctrl+A/E 始终可用。
图像
Ctrl-v 会通过操作系统的文字识别功能粘贴图像，因此适用于任何模型，包括纯文本模型。它需要 @napi-rs/system-ocr，该依赖仅为 macOS 和 Windows 提供预编译二进制文件；在 Linux 上，粘贴会提示 OCR 不可用，而不是直接失败。它提取的是文字，因此适合堆栈跟踪或错误对话框的截图，不适合 UI 设计稿。
比 OCR 更进一步的两种方式：
REIKA_VISION_MODEL将图像交给视觉模型，先转录文字，再描述画面。描述以相同方式附加，因此主模型仍不会看到像素，但可以处理 UI 设计稿。REIKA_VISION_BASE_URL和REIKA_VISION_API_KEY未设置时回退到主服务器的配置。REIKA_VISION=native对能看图的模型直接跳过识别步骤：粘贴的图像字节以 OpenAI 多模态图像部分发送，仅用于粘贴所在的那轮交互。此项也支持按配置档设置（REIKA_<NAME>_VISION），因此纯文本默认配置可以保持describe，同时用/model <vl>将某个会话切换到视觉模型，再切回。
原生视觉有两点需要注意：图像只发送一次，历史记录中会在原本放置描述的位置保留一条简短的“未转录”说明，因此模型可以要求重新粘贴，但无法在稍后再次查看。@file.png 引用仍会经过识别流程，只有剪贴板路径传递图像字节。图像 token 无法被上下文预算直接统计，因此计算提示词大小时，每张图像都会按固定额度计入。
工具调用
模型使用其原生函数调用聊天模板提供服务时，工具调用最可靠。如果没有原生模板，模型会以文本输出工具调用，Reika 会尽力解析常见格式作为回退：<tool_call>{json}</tool_call>、Hermes <function=…>、Python 风格的 fn(k=v)，以及泄漏到推理通道的调用。这些解析方式用于处理格式错误、循环和泄漏的调用，而原生路径能避免这些问题。如果本地模型的工具使用出现异常，先检查服务器（llama.cpp、Ollama、vLLM、MLX）是否为它加载了支持工具调用的模板。