RagCode logo

RagCode 上下文引擎

CI npm version License: MIT Node >= 24

English · 简体中文

让 AI 在改代码前，先证明它真的看懂了。

AI 会写代码，但它不知道自己是否已经看全了你的代码库。 RagCode 是面向编码智能体的**全本地、MCP 原生「可验证上下文层」**。它不止返回几个相似代码片段，而是为回答、调试、修改或评审任务构建一份足够小、证据明确的上下文包。 每一个回答都附带来源引用、新鲜度、归属链、影响范围、覆盖信号，以及一个 `edit-readiness` 判定（`safe_to_edit_after_reading` / `investigate_only` / `not_enough_context`）。证据不足时，RagCode 会明确告诉 Agent 还缺什么，而不是鼓励它自信地猜测。 它**与编辑器无关、MCP 原生**（Claude Code、Codex，或任何 MCP 客户端——不绑定单一编辑器），并**完全在你的机器上运行**（无需账号、无需 API key、代码不出本地）。首次运行用确定性嵌入即可离线工作；只有当你想要更好的召回时，才需要换上 OpenAI 兼容的嵌入provider。 它借鉴了 CodeGraph、Understand-Anything 等项目的思路，并在此基础上加入了 LanceDB 语义层以及更强的上下文引擎契约：`get_context` 返回的是当前已索引的、能够帮助智能体回答、调试、修改或评审代码的**最小任务上下文包**。 RagCode 还内置了**项目级共享记忆系统**，用于持久化决策、反馈、用户偏好和项目事实。记忆通过 MCP 暴露，可在多个 Agent 间同步，但它始终是辅助上下文：代码事实仍必须回到当前索引和源码中验证。 检索层现在具备**语言感知与外部重排序能力**。英文、中文和中英混合查询会先被归一化成带权重的 raw/path/symbol/lexicon 词项，再进入混合检索；因此关于协议、配置、测试、入口、文档和归属的中文问题，也能落到实现证据上。配置 OpenAI 兼容 reranker 后，RagCode 会在图扩展之后调用它；如果提供商失败，会回退到内置图重排序。 新鲜度模型现在默认是 **lazy/on-demand**。CLI 和 MCP 读取路径会先做轻量脏文件/陈旧检查，并在返回答案前按需刷新受影响文件。`ragcode service install` 默认不安装常驻 watcher；只有显式选择 `--mode supervisor` 或 `--mode hot` 时才会启动后台保鲜进程，因此大仓库无需长期驻留索引进程也能使用。 Web 仪表盘现在作为打包后的 Vue SPA 随 `ragcode dashboard` 一起提供，包含项目简报、图节点展开、上下文预算追踪、记忆、影响评审、请求流、diff 评审、运行时健康和配置来源视图。语义代际存储也可以通过 `ragcode semantic-prune` 安全清理：默认只 dry-run，并保护 active/rollback 表。 --- ## 为什么选 RagCode | 如果你需要…… | RagCode 适合，因为…… | |---|---| | 让 Agent 知道证据是否足够 | 验证式子图同时提供来源、覆盖信号、缺失证据和 `edit-readiness` | | 不被单一编辑器锁定的上下文能力 | MCP 原生；适配 Claude Code、Codex 及其他兼容的智能体宿主 | | 代码永不离开本机 | 全本地索引 + 离线嵌入，无需账号、托管服务或云端往返 | | 多个 Agent 不再每次从零开始 | 项目级共享记忆保存决策、反馈、偏好和经过验证的项目事实 | --- ## 技术栈 | 领域 | 技术 | |------|-----------| | 语言 / 运行时 | TypeScript 5.9、Node.js **>= 24**（使用 `node:sqlite`）、ESM 模块 | | 结构化图存储 | `better-sqlite3`（SQLite + FTS），测试场景下使用内存存储 | | 语义 / 向量存储 | `@lancedb/lancedb` + `apache-arrow`，并提供内存存储兜底 | | 共享记忆 | SQLite + FTS 事件存储、可选 LanceDB 向量、frontmatter 适配器、JSONL File-Hub 同步 | | AST / 解析 | TypeScript Compiler API（TS/JS）、`tree-sitter`（Python、Go、Rust、Java） | | MCP 集成 | `@modelcontextprotocol/sdk`（stdio 服务） | | CLI | `commander`、`ink` + `react`（交互式向导） | | Web 仪表盘 | `express` + `ws` 后端，Vue 前端（位于 `web/`） | | 文件监听 | `chokidar` | | 校验 | `zod` | | 工具链 | `tsx`（开发）、`vitest`（测试）、`tsc`（构建 + 类型检查） | --- ## 项目架构 RagCode 采用分层设计，任何具体的存储实现都不会跨越边界泄漏。所有对外的接口层（CLI、MCP、Web）都依赖 `src/core` 中的契约，而不依赖任何特定数据库。 ``` ┌──────────┐ ┌──────────┐ ┌──────────────┐ 接口层 │ CLI │ │ MCP │ │ Web 仪表盘 │ └────┬─────┘ └────┬─────┘ └──────┬───────┘ └──────────────┴────────────────┘ │ ┌───────────▼───────────┐ │ ContextEngine (core) │ 规范契约 └───────────┬───────────┘ ┌──────────────┬────────┼────────┬──────────────┬──────────┐ ▼ ▼ ▼ ▼ ▼ ┌────────┐ ┌─────────┐ ┌──────┐ ┌─────────┐ ┌─────────┐ ┌────────┐ │indexing│ │ graph │ │ sem. │ │retrieval│ │ context │ │ 扫描 │ │ SQLite │ │Lance │ │ 规划器 │ │ 打包器 │ │ memory │ │ 分块 │ │ +FTS │ │ DB │ │ +融合 │ │ +预算 │ │ SQLite │ └────────┘ └─────────┘ └──────┘ └─────────┘ └─────────┘ └────────┘ │ ┌─────▼─────┐ │ watch │ 增量新鲜度 └───────────┘ ``` **各层职责**（详见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)）： - **core** — 规范契约：`RepoIndex`、`CodeFile`、`CodeChunk`、`GraphStore`、`SemanticStore`、`ContextEngine`。这是其他一切所依赖的稳定边界。 - **indexing** — 文件系统扫描、忽略规则、哈希计算、分块以及索引流水线步骤。它不感知 MCP。 - **graph** — 精确的代码结构：文件、符号、边、查找、调用方/被调用方/影响分析。测试用内存实现，生产用 SQLite + FTS。 - **semantic** — 嵌入与向量检索，藏在接口之后，因此可以自由替换提供商（确定性、OpenAI 兼容、本地模型）和存储后端。 - **retrieval** — 查询规划：英文/中文/混合查询上下文、意图识别、精确/图/关键词/语义召回、可选外部重排序、分数融合和结果归一化。 - **context** — 面向智能体的输出：在字符/Token 预算内挑选片段，附带理由、分数、来源引用以及 `missingEvidence`。 - **memory** — 项目级共享 Agent 记忆：MCP 工具、SQLite/FTS 存储、可选向量、MQS 排序、验证、上下文注入和跨 Agent 同步。详见 [docs/MEMORY_SYSTEM.md](docs/MEMORY_SYSTEM.md)。 - **watch** — 长时间运行的监听器、持久化事件日志、脏文件合并，以及后台批量重建索引调度。 - **mcp** — 轻薄的协议适配层：工具命名、输入校验、处理器分发。这里不包含任何检索逻辑。 **上下文包契约**是整个引擎的核心。`get_context` 返回： ``` brief → freshness → ownerChain → topology → 证据片段 → missingEvidence → nextQueries ``` 片段是*证据*，而非结果的主要组织方式。大文件默认以 `skeleton`（骨架）展开级别返回，而非完整源码，并且每个片段都会报告省略了多少行。 --- ## 快速开始 ### 前置条件 - **Node.js >= 24.0.0**（必需——SQLite 图存储使用 `node:sqlite`） - Windows、macOS 或 Linux - 约 100 MB 磁盘空间，用于依赖与索引数据 ### 安装并运行（终端优先、离线优先） 首次运行无需任何嵌入 API key、无需账号、无需托管服务。 ```bash # 全局安装 npm install -g ragcode-context-engine cd my-project ragcode init # 离线优先配置：sqlite + lancedb + 确定性嵌入 ragcode index . # 构建索引；大仓库首轮默认使用有界批处理 ragcode setup-mcp # 为你的智能体客户端注册 MCP 服务 ragcode install-guidance . # 安装可更新的 AGENTS.md RagCode 操作契约 ``` 或者免安装直接试用： ```bash npx ragcode-context-engine index . npx ragcode-context-engine search . "query" ``` 从源码开发（未全局安装）？用 dev 脚本运行任意命令——它通过 `tsx` 直接执行 TypeScript 入口： ```bash npm run dev -- index . npm run dev -- setup-mcp --client codex --print ``` ### 让智能体粘贴即用 RagCode RagCode 提供一份会由 AI 从仓库 `AGENTS.md` 自动加载的启动协议。它会告诉宿主智能体何时优先使用 RagCode 检索、如何恢复缺失或过期索引、何时读取或写入跨 AI 共享记忆，以及何时通过 RagCode 的跨 CLI 控制面调用已注册的 Codex、Claude、Gemini 或 Grok。 推荐直接安装或更新受管标记区块；该命令不会覆盖仓库中其它既有规则： ```bash ragcode install-guidance . ``` 需要手动复制时，打印当前版本的权威模板： ```bash ragcode install-guidance --print ``` 标准文件名是复数形式的 `AGENTS.md`。协议不会把“已注册 CLI”误判为“真实模型可用”：跨 CLI 执行前必须调用 `ragcode agents doctor . --agent `，并明确区分宿主客户端的原生子 Agent 与具备持久化 ledger、artifact、恢复和审查门禁的 RagCode Agent 运行。协议正文使用英文，以便在不同 AI 客户端中保持一致解释。
完整可复制的 AGENTS.md 区块 ```md ## RagCode Operating Contract RagCode is this repository's evidence layer for code intelligence, shared memory, and controlled multi-agent workflows. Use it proactively; do not wait for the user to name it. ### Session Bootstrap - For the first non-trivial repository task in a session, query shared memory for relevant prior decisions, then use `get_context` to build a task-focused context pack before broad grep or manual file traversal. - If RagCode MCP tools are unavailable, use the CLI equivalents from the repository root. Do not block the user's task merely because MCP is absent. - When the index is missing or retrieval reports incomplete/stale evidence, check `index_status`; run `index_repo` for a missing index or `refresh_index` for a stale index, then retry the original query. CLI fallback: `ragcode status .`, `ragcode index .`, `ragcode refresh .`. - Treat the Web dashboard as observability only. Never use it as the setup, configuration, or agent-control path. ### Task Routing - Implementation, debugging, refactor, review, or architecture: start with `get_context` and select `debug`, `feature`, `refactor`, `review`, or `explain` mode to match the task. - Locate the current owner or edit point: use `find_owner`; find an exact symbol with `find_symbol`; inspect one indexed file with `explain_file` or expand a returned node with `expand_node`. - Before adding a helper, component, service, or abstraction: use `find_reuse_candidates` and prefer an existing pattern when the evidence supports reuse. - Understand runtime or request/data flow: use `trace_request_flow`; use `topology_map` when relationships matter more than full snippets. - Before a risky change: use `explain_impact` or `impact_analysis`. Before verification: use `related_tests`. For a completed diff: use `review_diff` before reporting completion. - For frontend work, call `get_project_brief` before coding when framework, design system, styling, theme, or component ownership is not already proven. - Use direct file reads after RagCode identifies the relevant files, to confirm exact implementation details, or when retrieval declares missing evidence. Report retrieval quality gaps explicitly instead of silently presenting guesses as repo truth. ### Evidence and Completion - Base repository claims on current RagCode results plus direct source verification where exact behavior matters. Distinguish indexed evidence, inference, and live runtime proof. - Follow `nextQueries`, `missingEvidence`, freshness diagnostics, and memory hints only while they materially improve the task. Stop retrieving when the owner chain and required evidence are sufficient. - Keep edits scoped. Run the smallest relevant tests first, then broader typecheck/lint/build gates when applicable. Do not claim completion without fresh validation or an explicit validation gap. ## Cross-AI Shared Memory - Before non-trivial work, call `memory_query` for prior decisions, feedback, constraints, and known failure modes. Treat memory as routing context, then verify drift-prone facts against current code or runtime state. - After a durable decision, user correction, non-obvious project fact, verified workaround, or completed architectural change, call `memory_write` with a clear topic, type (`decision`, `feedback`, `project`, `reference`, `user`, or `context`), and concise evidence-backed body. - When a prior memory is outdated, supersede it with `memory_write` (set `supersede` to the old entry ID) rather than deleting — the history is valuable for audit. - When a tool response includes `memoryHints` or `memorySnippets`, follow up with `memory_query` to explore. Heed `memory_write` results: `duplicates` (prefer `supersede` over piling on) and `conflicts` (same-topic disagreements from another agent — reconcile them). - Memory is project-scoped (bound to repo root), not agent-scoped. What you write is visible to Claude, Codex, and other agents working on the same repo. - CLI fallback: `ragcode memory query `, `ragcode memory write --body `, and `ragcode memory list`. ## Agent Selection - Use the host client's native subagents for bounded work inside the current AI session when they are sufficient. - Use RagCode Agents when work requires registered external CLI providers, explicit role-to-provider assignment, durable run artifacts, cross-provider consultation, review gates, background execution, mid-turn steering, or resumable workflows. - Built-in agent IDs are `codex`, `claude`, `gemini`, and `grok`, and repositories may override them in `.ragcode/agents/agents.json`. Registration does not prove installation, authentication, or live-model readiness. - Preserve explicit assignments such as "Claude plans, Grok breaks down tasks, Codex implements, Gemini reviews." Do not replace them with a hard-coded provider pair. - Never claim that an external agent ran unless a real RagCode run, ledger event, provider response, or artifact proves it. A dry run, static probe, or installed executable is not completed model execution. ## Controlled Cross-CLI Agent Workflows - Before using an external provider, run `ragcode agents doctor . --agent `. Add `--live` only when a disposable real-provider turn is needed to prove authenticated readiness. - Run `ragcode agents init .` when `.ragcode/agents/` is absent, then inspect or edit `.ragcode/agents/agents.json` instead of assuming the built-in command fits the local installation. - For one bounded delegation, dry-run `ragcode agents consult . --leader --consultant --task "" --dry-run`, then remove `--dry-run` only when real execution is requested. - For multi-step collaboration, create or compile a workflow JSON, validate it with `ragcode agents validate . --workflow `, and inspect execution using `ragcode agents run . --workflow --task "" --dry-run` before a real run. - Use `ragcode agents start` for detached execution; `ragcode agents status` and `ragcode agents events` for observation; `ragcode agents invoke` only to steer an actually running node; `ragcode agents report` for deterministic completion evidence; `ragcode agents resume` for interrupted runs; `ragcode agents cancel` to stop a run; and gated `ragcode agents integrate` to apply a completed patch artifact. - Mark plan, research, review, and verification nodes `read_only`. Mark implementation nodes `write` and restrict `writePolicy.allowedPaths` to the smallest valid scope. Keep one workspace-writing node at a time and use bounded fail-closed review loops. - MCP workflow tools are read-only (`agent_workflow_validate`, `agent_workflow_status`, `agent_workflow_report`). Starting runs, steering agents, cancellation, and workspace integration remain CLI control-plane operations. - Agent nodes automatically receive bounded, role-aware shared memory unless `memoryPolicy.read.mode` is `off`. Providers cannot write memory directly: `memoryPolicy.write.mode` may record proposals or promote evidence-backed candidates only after required node and final gates pass. ```
### 大仓库与首轮索引 `ragcode index ` 默认适合大仓库。空索引首轮会先写入一个有界结构化批次，把剩余文件记录为 pending，后续 `index`、`watch` 或服务运行会从持久化状态继续推进。首个部分 bootstrap 默认暂缓语义向量写入，因此图检索和归属查询可以先可用，而不会强制一次性跑完整嵌入。 ```bash ragcode index . --max-batch-files 2000 --max-analysis-memory-mb 4096 ragcode index . --semantic-on-bootstrap # 首个部分批次也写入向量 ragcode index . --full # 强制旧的一次性全量索引 ``` 进度会持久化到 `.ragcode/index-state.json` 和 `.ragcode/index-progress.jsonl`。`ragcode status .` 会报告 `graphFresh`、`pendingFileCount`、`indexingFileCount`、`semanticFresh`、`semanticCoverage` 和 `semanticRebuildNeeded`，让智能体能判断检索覆盖的是完整仓库，还是当前已索引的图切片。 默认保鲜模式是 lazy/on-demand。`ragcode search`、`context`、owner、impact、flow 以及 MCP 检索工具会先做轻量新鲜度检查，发现 stale 文件时默认在返回前执行有界刷新；传入 `--stale-ok` / `--no-refresh` 会跳过刷新。文件修改后的第一次查询可能更慢，因为它会承担刷新成本。 设置 `RAGCODE_REFRESH_ON_READ=off`（或 `stale-ok` / `no-refresh`）可以让读取路径保持严格只读；设置为 `always` 则会强制每次读取前都刷新。`ragcode status .` 默认走轻量状态路径；需要 chunk、symbol、edge 和 semantic store 计数时再加 `--full`。 后台保鲜方面，`ragcode service install ` 现在默认是 lazy 模式，不安装任何常驻 watcher。需要安装前先跑一个有界批次时可加 `--index-now`；需要轻量常驻监听时使用 `--mode supervisor`，需要旧的始终在线 watcher 时显式使用 `--mode hot`： ```bash ragcode service install . ragcode service install . --mode supervisor --max-analysis-memory-mb 4096 ragcode service install . --mode hot --index-now --bootstrap-batch-size 2000 --max-analysis-memory-mb 4096 ``` ### 升级语义召回能力（可选，永不阻塞） ```bash ragcode configure # 编辑存储 / 提供商 / 模型 / base URL / 维度 ragcode configure --test # 验证提供商（失败分类清晰；绝不打印密钥） ``` **OpenAI 兼容提供商（OpenAI、Azure、Ollama 等）：** ```bash # 云端（OpenAI） export RAGCODE_EMBEDDING_PROVIDER=openai-compatible export RAGCODE_EMBEDDING_API_KEY=sk-your-key # 本地（Ollama）- 推荐隐私+质量兼顾 ollama pull nomic-embed-text export RAGCODE_EMBEDDING_PROVIDER=openai-compatible export RAGCODE_EMBEDDING_BASE_URL=http://localhost:11434/v1 export RAGCODE_EMBEDDING_MODEL=nomic-embed-text export RAGCODE_EMBEDDING_API_KEY=ollama # 任意非空字符串即可 ``` 详见 [docs/EMBEDDING_PROVIDERS.md](docs/EMBEDDING_PROVIDERS.md) 了解 Azure、Ollama 配置、故障排查和性能对比。 ### 升级重排序质量（可选） 外部 reranker 与 embedding 是两条独立配置。图扩展仍会先运行，确保结构化候选进入候选池；随后 RagCode 可以把有界候选窗口发送给 OpenAI 兼容 `/rerank` 端点。如果 provider 报错，检索会回退到本地图重排序。 ```bash export RAGCODE_RERANK_PROVIDER=openai-compatible export RAGCODE_RERANK_BASE_URL=https://your-router.example/v1 export RAGCODE_RERANK_API_KEY=your-key export RAGCODE_RERANK_MODEL=your-rerank-model export RAGCODE_RERANK_PATH=/rerank export RAGCODE_RERANK_TOP_N=80 ``` 同一组配置也接受 `RAGCODE_RRANK_*` 别名。配置和诊断输出会对密钥脱敏。 ### CLI 命令 ```bash # 初始化与诊断 ragcode init [directory] ragcode configure [repoRoot] ragcode doctor [repoRoot] ragcode update [--check] ragcode setup-mcp [--client codex] ragcode install-guidance [repoRoot] ragcode mcp # 索引与保鲜 ragcode index ragcode refresh ragcode status ragcode status-human # 别名：status-ui ragcode status-ui ragcode watch ragcode watch-worker ragcode watch-supervisor ragcode record-events ragcode service install # 默认 lazy；常驻服务使用 --mode supervisor/hot ragcode service status ragcode service uninstall # 语义代际生命周期 ragcode semantic-status ragcode semantic-rebuild [--promote] ragcode semantic-promote ragcode semantic-rollback ragcode semantic-prune [--apply] ragcode semantic-optimize # 检索与分析 ragcode search ragcode context ragcode brief [--query ] ragcode owner ragcode reuse ragcode expand-node ragcode impact ragcode explain-impact ragcode tests ragcode trace-request-flow # 记忆、仪表盘与多智能体工作流 ragcode memory --help ragcode dashboard ragcode agents run . --workflow --task "" ragcode agents start . --workflow --task "" ragcode agents events . --run [--no-follow] ragcode agents invoke . --run --message "" ragcode agents consult . --leader --consultant --task "" ragcode agents status . --run ragcode agents cancel . --run ``` 运行 `ragcode --help` 或 `ragcode --help` 查看更多细节。 多智能体运行会持久化到 `.ragcode/agents/runs/`，包含事件账本、产物、报告、 执行身份、取消状态和原生会话检查点。工作流 JSON 支持依赖排序、有界重试/修复循环、 验证与产物门禁、只读/写入策略以及 CLI 智能体连接器。详见 [docs/agents/workflow-spec.md](docs/agents/workflow-spec.md) 和 [docs/agents/cli-adapters.md](docs/agents/cli-adapters.md)。 ### MCP 服务集成 RagCode 可作为 MCP 服务运行，让 Claude 等智能体直接调用它的工具。按客户端自动注册： ```bash ragcode setup-mcp # Claude Code (项目 ./.mcp.json，默认) ragcode setup-mcp --client claude # Claude Desktop (~/.../claude_desktop_config.json) ragcode setup-mcp --client codex # Codex CLI (~/.codex/config.toml) ragcode setup-mcp --client codex --print # 仅打印配置，不写文件 ``` 既有配置会被原地合并（保留其它服务和无关字段，并在覆盖前备份原文件）。加 `--force` 可跳过提示直接覆盖已有的 `ragcode` 条目。MCP 默认在仓库根目录启动，并在启动时读取 `.ragcode/config.json`，所以之后修改配置无需重新生成 MCP 条目。只有明确希望把 API 密钥写入 MCP 环境变量时，才使用 `--include-secrets`。 或手动添加到你的 MCP 客户端配置： ```json { "mcpServers": { "ragcode": { "command": "ragcode", "args": ["mcp"], "cwd": "/path/to/your/repo" } } } ``` 用于聚焦代码检索的 CLI 命令包括 `ragcode find-symbol`、`ragcode explain-file` 和 `ragcode topology`。 文档检索使用独立命令组和独立存储命名空间： ```bash ragcode document index --profile default ragcode document search "query" --profile default ragcode document context "query" --profile default --budget 10000 --transport-budget-bytes 18000 ragcode document assets --source-id --profile default ragcode document asset --source-id --block-id --profile default ragcode document status ragcode document benchmark --workspace --report ragcode doctor ``` `--budget` 限制上下文字符数；`--transport-budget-bytes` 是独立的 MCP/JSON 硬字节上限。Figure 资产只从 active generation 中发现，并在每次读取时重新校验；接口不会返回 provider 路径，RagCode 也不会保留 provider 管理的文件。默认会拒绝索引后已修改的文件。只有需要刻意检查过期源证据时才使用 `--allow-stale`，返回的命中会标明该状态。`ragcode doctor ` 会报告文档 SQLite 完整性、generation 状态和已修改/缺失的 active 源。 `ragcode document benchmark` 根据严格 JSON manifest 运行真实的读取、抽取、索引、检索和 evaluator 链路，不注入合成命中，也不自动下载数据集。manifest 会固定 chunk policy，以及不含密钥的 OCR、layout、图像 embedding runtime profile；实际配置不一致时会在索引前失败。默认拒绝复用已有 workspace，只有显式传入 `--reuse-index` 才允许复用，从而保证基线报告能归因到唯一语料和运行配置。在源码 checkout 中也可以使用 `npm run benchmark:document -- ...`。远程 OCR 报告会记录 `requestedAssets`、缓存命中/未命中、并发请求合并、provider 调用/成功/失败、重试次数，以及上传字节和像素总量。如果当前环境会通过 dotenv 启用 Gemini 图像 embedding，可设置 `RAGCODE_DOCUMENT_IMAGE_EMBEDDING_PROVIDER=off`，以固定可复现的 native-only 基线。 生产文档注册表支持本地文本/结构化格式、窄范围原生 DOCX/XLSX/PPTX/PDF profile，以及显式启用的本地或远程 OCR。本地 OCR 继续通过 `RAGCODE_DOCUMENT_OCR_MANIFEST` 提供。远程 OCR 必须同时具备三层授权：`RAGCODE_DOCUMENT_OCR_MODE=remote`、`RAGCODE_DOCUMENT_REMOTE_OCR_PROVIDER=openrouter`、`RAGCODE_DOCUMENT_REMOTE_OCR_SCOPES=image,pdf,office`（只列出你同意上传的格式范围），并配置 `RAGCODE_OPENROUTER_API_KEY` 与固定的 `RAGCODE_OPENROUTER_OCR_MODEL`。仅配置 provider 或 key 绝不会触发文档上传；只有获得 scope 授权的独立图片、符合条件的扫描 PDF 页面/PDF 图片区域或 Office 内嵌图片的规范化 PNG 字节会离开本机。API key 与 HTTP 请求始终留在父进程，不可信 PDF/OOXML parser host 继续保持 `network=false`，既拿不到凭据也没有网络权限。远程 OCR 按规范化图片 SHA-256 和 provider profile 使用持久缓存，并限制并发、总像素、上传字节、PDF 页数、重试、响应大小和墙钟时间。远程坐标只按估计值处理，所有 OCR 引用仍属于 `EXTRACTED` 证据，绝不会伪装成字节精确引用或 `PRIMARY` 原生文本。 Figure 图像向量是独立的显式启用路径。设置 `RAGCODE_DOCUMENT_IMAGE_EMBEDDING_PROVIDER=gemini` 与 `RAGCODE_GEMINI_API_KEY`；可用 `RAGCODE_GEMINI_IMAGE_EMBEDDING_MODEL`、`RAGCODE_GEMINI_IMAGE_EMBEDDING_DIMENSIONS` 和 `RAGCODE_DOCUMENT_IMAGE_VECTOR_STORE_URI` 覆盖固定默认值。图像向量使用 `document-image` 命名空间和独立 LanceDB 存储；OpenRouter OCR key 绝不会自动启用图像向量。 #### 文档自适应检索模式与回滚 产品模式只改预算与可选能力，**不会**关闭 ACL、新鲜度、generation 或 citation 门禁。 | 模式 | 默认行为 | |------|----------| | `fast`（默认） | 单步检索；验证状态 `NOT_RUN`（除非显式开启） | | `deep` | 有界自适应（改写 / 缺 facet / 已注册 structured-graph 动作） | | `audit` | 偏保守的 claim/citation 验证与溯源报告 | 环境默认（生产安全关闭）： | 变量 | 取值 | 默认 | |------|------|------| | `RAGCODE_DOC_RETRIEVAL_MODE` | `fast` | `deep` | `audit` | `fast` | | `RAGCODE_DOC_CLAIM_VERIFY` | `off` | `shadow` | `on` | `off` | | `RAGCODE_DOC_ADAPTIVE` | `off` | `shadow` | `on` | `off` | | `RAGCODE_DOC_ADAPTIVE_MAX_ATTEMPTS` | `1`–`3` | 随模式（fast → 1） | | `RAGCODE_DOC_STRUCTURED_JOIN` | `on` | `off` | 后端就绪后默认 `on` | | `RAGCODE_DOC_GRAPH_EXPAND` | `on` | `off` | 后端就绪后默认 `on` | 可独立关闭 claim 验证、adaptive、STRUCTURED_JOIN、GRAPH_EXPAND，而无需删除 source generation 或 entity/event 行。`shadow` 只记指标/计划动作，不在禁用执行时改变公开 hits。`ragcode doctor` 的 `retrievalFeatures` 会展示这些开关、独立 disable 键与软 SLO。 MCP 附加字段：`mode`、`maxAttempts`、`verifyClaims`、`continuation`。只读工具：`verify_document_answer`、`document_retrieval_metrics`。全局 GraphRAG **未启用**；本地 `GRAPH_EXPAND` 仅 source block 拓扑，`STRUCTURED_JOIN` 为一跳 source-bound 实体/事件。 本地分层基线（无外部下载）： ```bash ragcode document benchmark tests/fixtures/document/benchmark-stratified-v1.json --source-root tests/fixtures/document --workspace /tmp/ragcode-stratified-ws --report /tmp/ragcode-stratified-report.json ``` 报告含候选检索指标，以及可选 `trust`（自动采集）与当前产品模式的软 `slo` 评估。 **可用的 MCP 工具（共 38 个）：** - *索引生命周期* — `index_repo`、`refresh_index`、`index_status`、`record_file_events`、`watch_status` - *搜索与上下文* — `search_code`、`get_context`、`get_project_brief`、`topology_map`、`expand_node` - *符号与文件* — `find_symbol`、`explain_file`、`find_owner`、`find_reuse_candidates` - *影响与流向* — `impact_analysis`、`explain_impact`、`related_tests`、`trace_flow`、`trace_request_flow` - *评审* — `review_diff` - *共享记忆* — `memory_write`、`memory_query`、`memory_list`、`memory_delete` - *智能体工作流* — `agent_workflow_validate`、`agent_workflow_status`、`agent_workflow_report` - *文档检索* — `index_documents`、`refresh_documents`、`document_status`、`search_documents`、`get_document_context`、`list_document_assets`、`get_document_asset`、`delete_document`、`rollback_document`、`verify_document_answer`、`document_retrieval_metrics` `watch_status` 是只读的：它报告是否有活着的 watcher 在保持索引新鲜，但绝不启动 watcher（启动属于 `ragcode watch` 或 OS 服务的职责）。 --- ## MCP 工具使用指南 ### `get_context` — 面向智能体的上下文包 `get_context` 工具是 RagCode 为 AI 智能体提供的主要接口。它返回经过验证、预算可控的上下文，并附带明确的推理过程和完整性信号。 #### 输出格式（v0.1.6 新增） **format 参数**控制输出结构： ```typescript // JSON 格式（默认，向后兼容） { tool: "get_context", input: { query: "认证流程", format: "json", // 返回 ContextPack 结构 budgetChars: 15000 } } // Markdown 格式（AI 友好，推荐） { tool: "get_context", input: { query: "认证流程", format: "markdown", // 返回格式化的 Markdown 字符串 budgetChars: 15000 } } ``` **Markdown 输出**包含： - **主要文件章节**：相关性评分和推理说明 - **代码片段**：按文件分组，带语法高亮 - **调用关系图**：可视化函数关系 - **完整性指标**：索引新鲜度、覆盖率 - **预算使用统计**：已用字符数、包含的片段数 #### 预算强制执行（v0.1.6 修复） `budgetChars` 参数现在**严格执行**： - ✅ 输出大小保证 **≤ budgetChars × 1.2** - ✅ 单个片段限制在 **150 行**或 **8000 字符**以内 - ✅ 智能截断于自然边界（函数、类） - ✅ 截断警告包含在 `missingEvidence` 中 **实际效果：**典型输出从 3.3MB 降至 ≤18KB（压缩 99%+）。 **示例：** ```typescript // v0.1.6 之前：可能返回 3.3MB // v0.1.6 之后：保证 ≤18KB await mcp.callTool('get_context', { query: '登录实现', budgetChars: 15000 // 现在会严格遵守！ }); ``` #### 推理透明度（v0.1.6 新增） 每个搜索结果都包含 **`reason` 字段**解释相关性： ```json { "filePath": "src/auth/login.ts", "score": 9.2, "reason": "🎯 关键词匹配：login, authentication • 符号匹配：registerLoginCommand (0.95 置信度) • 图位置：距查询 0 跳" } ``` 这帮助智能体理解： - **为什么**选择这个文件（关键词 vs 语义匹配） - **什么**符号匹配了查询 - **如何**与其他代码关联（图距离） #### 完整性指标（v0.1.6 新增） 响应包含**新鲜度和覆盖率信号**： ```json { "freshness": { "freshnessScore": 0.95, // 0.0 = 陈旧, 1.0 = 新鲜 "coverageScore": 1.0, // 0.0 = 不完整, 1.0 = 完整 "graphFresh": true, "semanticFresh": true, "pendingFiles": [], // 尚未索引的文件 "staleFiles": [] // 自上次索引后修改的文件 } } ``` **使用这些信号**判断结果是否可能不完整： - `freshnessScore < 0.8` → 已有索引时运行 `ragcode refresh `，没有索引时运行 `ragcode index ` - `pendingFiles.length > 100` → 大量代码尚未索引 - `staleFiles.length > 10` → 最近的更改未反映在结果中 #### 查询语言行为 ✅ **中文与中英混合查询会在检索前归一化** RagCode 会抽取代码 token、路径、符号、中文分词和领域词典词项后再打分。查询端与 SQLite FTS 索引端共用 `Intl.Segmenter`，并保留 bigram 降级与 shadow token；中文注释和文档中的代码引用还会生成指向真实符号的确定性 alias。因此无需引入原生中文分词依赖，也能让关于协议、配置、文档、测试、运行时错误、归属和图关系的中文问题命中实现证据。 ```typescript await mcp.callTool('get_context', { query: '网关启动尚未就绪返回哪个 close code 常量', budgetChars: 15000 }); ``` trace 诊断会暴露 `detectedLanguage`、`termCategories`，以及 raw/lexicon/path/symbol/content 的加权匹配原因。 ⚠️ **语义质量仍取决于 embedding 模型** 确定性 embedding 兜底离线可靠，但它不是多语言神经模型。需要更好的中文语义召回时，建议使用多语言 OpenAI 兼容 embedding。语义索引受容量限制时会先保证文件覆盖，再按全局质量补位；需要最高精度时，仍建议在查询中加入精确符号、路径或协议/配置词。 **推荐查询形态：** ```typescript // 中文 + 精确符号/路径提示 await mcp.callTool('get_context', { query: '登录功能 registerLoginCommand 的实现' }); // 英文查询仍然可用 await mcp.callTool('get_context', { query: 'login implementation' }); // 精确符号名仍然最强 await mcp.callTool('get_context', { query: 'registerLoginCommand' }); ``` ⚠️ **大型仓库索引不完整** 当 `pendingFileCount` 较高时，结果可能无法覆盖整个代码库： - 检查响应中的 `freshness.pendingFiles` 数量 - 运行 `ragcode index ` 继续索引 - 使用 `ragcode status ` 监控进度 #### 完整示例 ```typescript // MCP 客户端调用 get_context const result = await mcp.callTool('get_context', { query: '认证流程', format: 'markdown', budgetChars: 15000, mode: 'debug' // 可选：debug, feature, refactor, review, explain }); // Markdown 格式返回 { content: "## 认证流程 (high confidence)\n\n### 主要文件\n...", metadata: { confidence: "high", totalSnippets: 5, budgetUsed: 14500, freshnessScore: 0.95 } } // JSON 格式返回 ContextPack（与 v0.1.5 相同） { query: "认证流程", brief: "...", confidence: "high", snippets: [...], ownerChain: [...], freshness: {...}, missingEvidence: [...] } ``` --- ### Web 仪表盘（观测与调试） 仪表盘是 RagCode 的可观测面板——项目简报、图可视化与节点展开、搜索调试、上下文包和预算追踪检视、记忆、影响/请求流/diff 评审、监听器监控，以及一个带逐字段来源标注和密钥脱敏的运行时配置视图。配置与设置仍然留在终端中完成。 ```bash ragcode dashboard # 打包后的 API + Vue 仪表盘：http://localhost:3000 # 仅源码开发： npm run web:server cd web && npm run dev # Vite 前端：http://localhost:5173 ``` 详见 [docs/DASHBOARD.md](docs/DASHBOARD.md) 与 [web/README.md](web/README.md)。 --- ## 项目结构 ``` ragcode/ ├── src/ │ ├── core/ # 规范契约与编排门面（稳定边界） │ ├── indexing/ # 扫描、忽略规则、哈希、分块、分析器、流水线 │ ├── graph/ # 结构化代码图：符号、文件、边、查找 │ ├── semantic/ # 嵌入 + 向量存储（LanceDB / 内存） │ ├── retrieval/ # 查询规划与混合（精确/图/关键词/语义）融合 │ ├── context/ # 在 Token/字符预算内构建上下文包 │ ├── memory/ # 共享 Agent 记忆：存储、向量、同步、验证、注入 │ ├── subgraph/ # 经验证的代码子图（影响 / 流程 / 评审 / 调试） │ ├── topology/ # 框架 + 数据流拓扑边 │ ├── reuse/ # 复用 / 重复检测 │ ├── lsp/ # LSP 辅助的符号解析 │ ├── watch/ # 监听守护进程、事件日志、脏文件合并、调度器 │ ├── mcp/ # MCP 工具定义与处理器（轻薄适配层） │ ├── cli/ # 命令入口（commander + ink 向导） │ ├── web/ # 仪表盘后端（express + ws） │ ├── config/ # 运行时配置解析 │ ├── project/ # 项目身份与工作区自动作用域 │ ├── diagnostics/ # Doctor / 冒烟检查 │ ├── types/ # 共享类型声明 │ └── utils/ # 小型共享工具（非领域所有者） ├── tests/ # Vitest 回归测试套件（基础、图、检索、监听……） ├── docs/ # 架构笔记、契约与决策记录 ├── integrations/ # Codex/OMX 智能体技能模板（ragcode-context、ragcode-memory） ├── scripts/ # init-config、setup-mcp、基准测试、评估、审计 ├── web/ # Vue 仪表盘前端 └── benchmarks/ # 基准测试夹具与结果 ``` --- ## 核心特性 - **混合检索** — 融合精确、图、关键词与语义信号，应用语言感知意图加权，保护强文档/协议/测试/跨语言证据，并可把有界候选窗口交给外部 reranker；失败时回退到图重排序。最终分数非正的候选会被过滤掉。 - **模式感知的上下文打包** — 从查询中解析检索模式：`debug`、`feature`、`refactor`、`review` 或 `explain`，每种模式优先关注不同类型的证据。 - **上下文包契约** — `brief`、`freshness`、`ownerChain`、`topology`、证据片段、`missingEvidence` 以及 `nextQueries`，附带来源引用与省略统计。返回不确定性，胜过夸大其词。 - **结构化代码图** — 符号、文件，以及 `contains` / `imports` / `exports` / `calls` 边，由 SQLite + FTS 或内存存储支撑。 - **框架 + 数据流拓扑** — 有界的路由/ORM 证据（Next.js、Express、Fastify、Prisma、Drizzle），以 `calls_api`、`routes_to`、`reads_from`、`writes_to` 以及请求负载 `orm_dataflow` 边的形式产出。 - **多语言分析** — 通过 TS Compiler API 对 TypeScript/JavaScript 提供完整 AST 支持；通过 tree-sitter 对 Python、Go、Rust、Java 进行分析，其他文件类型则回退到按行分块。 - **增量新鲜度** — 默认使用读取时 lazy refresh，也可显式选择 chokidar 驱动的 supervisor/hot watcher 模式。脏文件会经过持久化事件日志、合并和有界重建索引；重启时回放日志，确保脏文件工作不丢失。 - **共享 Agent 记忆** — MCP 记忆工具将决策、反馈、用户偏好、项目事实和引用持久化到项目级 SQLite 存储，并支持可选语义召回、验证、基于 MAB 的上下文注入和跨 Agent 同步。 - **受监管的多智能体工作流** — 支持经过校验的 DAG 工作流、持久化账本与产物、有界验证/修复门禁、执行身份、进程树取消、原生会话恢复，以及 Codex、Claude、Gemini、Grok 和通用 CLI 适配器之间的 leader/consultant 协作。 - **离线优先** — 确定性嵌入无需 API key；任何时候都能换成 OpenAI 兼容的提供商，无需重构架构。 - **MCP 原生** — 24 个智能体工具运行在轻薄的 stdio 服务之上（索引生命周期、搜索/上下文、影响/流向、评审、记忆），外加一个 Codex/OMX 技能模板，引导智能体优先走 MCP、CLI 兜底。 - **Web 可观测性** — 打包发布的仪表盘，包含项目简报、图节点展开、搜索诊断、上下文预算追踪、记忆、影响/请求流/diff 评审、监听器监控、健康状态、技术栈和脱敏的运行时配置视图。 --- ## 开发流程 克隆并初始化： ```bash git clone https://github.com/MarshallEriksen-Neura/ragcode.git cd ragcode npm install ``` 常用任务（npm 是 CI 使用的标准工具链；本地也可用 `bun`）： ```bash npm run dev -- doctor # 通过 tsx 从源码运行 CLI npm run check # TypeScript 严格类型检查（不产出文件） npm test # 运行 Vitest 测试套件 npm run test:watcher # 仅运行监听相关测试 npm run build # 编译 TS 运行时，并把打包仪表盘构建到 web/dist npm --prefix web run build # 仅运行仪表盘 typecheck + Vite 生产构建 npm pack --dry-run # 发布前验证包内容 ``` **分支策略：** `main` 是受保护的默认分支。在功能分支上工作，并向 `main` 提交 Pull Request——切勿直接推送到 `main`。 **CI**（[.github/workflows/ci.yml](.github/workflows/ci.yml)）会在每次推送和向 `main` 提交 PR 时，在 Node 24 上按顺序执行：`npm ci` → `npm run check` → `npm run build` → `npm test` → `npm pack --dry-run`。构建步骤也会根据 `web/package-lock.json` 安装仪表盘依赖并产出用于打包的 `web/dist`。所有步骤必须通过才能合并。发布由 [.github/workflows/publish.yml](.github/workflows/publish.yml) 自动化完成。 使用确定性嵌入进行离线冒烟运行： ```bash export RAGCODE_GRAPH_STORE=sqlite export RAGCODE_SQLITE_PATH=.ragcode/graph.sqlite export RAGCODE_SEMANTIC_STORE=lancedb export RAGCODE_LANCEDB_URI=.ragcode/lancedb export RAGCODE_EMBEDDING_PROVIDER=deterministic npm run dev -- doctor . --query "context engine" npm run dev -- index . npm run dev -- search . "context engine" ``` --- ## 编码规范 - **TypeScript 严格模式。** 任何改动在被视为完成之前，`npm run check`（`tsc --noEmit`）必须零错误通过。 - **全程 ESM。** 包是 `"type": "module"`；使用 ES import/export 以及 `node:` 前缀的内置模块。 - **尊重分层边界。** 依赖 `src/core` 中的契约，而非具体存储。`indexing` 不得感知 MCP；`mcp` 必须保持轻薄、不含检索逻辑；`watch` 只依赖 `ContextEngine` 契约。 - **存储可替换。** 任何触及图或语义存储的代码都要走 `GraphStore` / `SemanticStore` 接口，以便测试和未来的后端能够替换。 - **稳定的 ID 与哈希。** 分块拥有确定性内容哈希与稳定 ID——修改分块或分析器时要保持这一点。 - **在边界处校验输入**，使用 `zod`，尤其是 MCP 工具输入。 - **绝不打印密钥。** 配置视图与提供商测试会对 API key 脱敏；敏感文件（`.env`、密钥、凭据）会从索引中过滤掉。 --- ## 测试 测试使用 **Vitest**，位于 [tests/](tests/)（38+ 套件）。它们覆盖整个基础设施：扫描与增量索引、SQLite 与 LanceDB 存储、混合检索与图重排、上下文打包与骨架化、拓扑解析、监听守护进程与日志回放、MCP 服务工具，以及 onboarding/configure CLI 向导。 ```bash npm test # 完整套件 npm run test:watcher # 仅监听守护进程 + 状态测试 npx vitest run tests/foundation.test.ts # 单个套件 ``` 当满足以下条件时，基础设施被认为是稳固的：仓库可确定性扫描、分块拥有稳定 ID/哈希、图与语义存储可替换、CLI 与 MCP 调用同一个引擎、严格类型检查通过，并且扫描/索引/搜索/上下文打包都被测试覆盖。任何行为变更都要同步增加或更新测试，并将编写与评审保持为两个独立的环节。 --- ## 贡献指南 1. Fork 仓库，并从 `main` 切出一个功能分支。 2. 进行改动，保持在相关层的边界内（参见 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)）。 3. 为任何行为变更在 [tests/](tests/) 中增加或更新测试。 4. 推送前在本地运行完整的检查关卡： ```bash npm run check && npm run build && npm test && npm pack --dry-run ``` 5. 推送你的分支，并向 `main` 提交 Pull Request，附上简明的变更说明与测试情况。 对于智能体辅助贡献，[integrations/codex/skills/](integrations/codex/skills/) 中的 Codex/OMX 技能包提供用于代码智能的 `ragcode-context`，以及用于共享项目记忆的 `ragcode-memory`——详见 [docs/CODEX_SKILL.md](docs/CODEX_SKILL.md)。 ### 更多文档 - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — 分层与职责 - [docs/MEMORY_SYSTEM.md](docs/MEMORY_SYSTEM.md) — 共享记忆架构与运维说明 - [docs/INDEX_SCHEMA.md](docs/INDEX_SCHEMA.md) — 索引 schema - [docs/EMBEDDING_PROVIDERS.md](docs/EMBEDDING_PROVIDERS.md) — embedding、reranker、语义准入与运行时配置 - [docs/DASHBOARD.md](docs/DASHBOARD.md) — Web 仪表盘 - [docs/CODEX_SKILL.md](docs/CODEX_SKILL.md) — Codex/OMX 智能体技能 - [docs/agents/workflow-spec.md](docs/agents/workflow-spec.md) — 多智能体工作流 schema、门禁与执行模型 - [docs/agents/cli-adapters.md](docs/agents/cli-adapters.md) — CLI 连接器分级、能力、恢复、取消与审批语义 认同 `真诚`、`友善`、`团结`、`专业`，欢迎加入 [LinuxDo](https://linux.do/latest)。 --- ## 许可证 基于 [MIT 许可证](./LICENSE) 发布。Copyright (c) 2026 RagCode Team。