ragcode-context-engine

v0.1.20

Published

a month ago

Local code intelligence foundation: structural code graph, LanceDB semantic layer, retrieval, context packing, and MCP tools.

0High
0Medium
0Low

marshalleriksen

code-intelligence mcp model-context-protocol semantic-search code-graph lancedb rag ai-agents claude code-analysis

RagCode 是面向编码智能体的「可验证上下文层」，且全程在本地运行。

绝大多数代码智能工具止步于检索——把相关代码片段丢给智能体就完事了。RagCode 多走一步：它会告诉智能体当前掌握的已验证上下文是否足以安全地动手。每一个回答都附带明确的来源引用、新鲜度、归属链、影响半径（blast-radius）、覆盖信号（coverage），以及一个 edit-readiness 判定（safe_to_edit_after_reading / investigate_only / not_enough_context）——并诚实地记录还缺哪些证据。

它与编辑器无关、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 适合，因为…… | |---|---| | 不被单一编辑器锁定的上下文能力 | MCP 原生；适配任意智能体宿主，而非某一个 IDE | | 代码永不离开本机 | 全本地索引 + 离线嵌入，无云端往返 | | 让智能体「正确地动手」而非「自信地犯错」 | 带覆盖信号与 edit-readiness 判定的验证式子图，而不是原始片段堆砌 |

技术栈

| 领域 | 技术 | |------|-----------| | 语言 / 运行时 | 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）：

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。
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、无需账号、无需托管服务。

# 全局安装
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 操作契约

或者免安装直接试用：

npx ragcode-context-engine index .
npx ragcode-context-engine search . "query"

从源码开发（未全局安装）？用 dev 脚本运行任意命令——它通过 tsx 直接执行 TypeScript 入口：

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。

推荐直接安装或更新受管标记区块；该命令不会覆盖仓库中其它既有规则：

ragcode install-guidance .

需要手动复制时，打印当前版本的权威模板：

ragcode install-guidance --print

标准文件名是复数形式的 AGENTS.md。协议不会把“已注册 CLI”误判为“真实模型可用”：跨 CLI 执行前必须调用 ragcode agents doctor . --agent <id>，并明确区分宿主客户端的原生子 Agent 与具备持久化 ledger、artifact、恢复和审查门禁的 RagCode Agent 运行。协议正文使用英文，以便在不同 AI 客户端中保持一致解释。

<!-- RAGCODE:AGENT-GUIDANCE:START -->
## 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 <query>`, `ragcode memory write <topic> --body <text>`, 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 <id>`. 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 <id> --consultant <id> --task "<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 <path>`, and inspect execution using `ragcode agents run . --workflow <path> --task "<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:AGENT-GUIDANCE:END -->

ragcode index <repoRoot> 默认适合大仓库。空索引首轮会先写入一个有界结构化批次，把剩余文件记录为 pending，后续 index、watch 或服务运行会从持久化状态继续推进。首个部分 bootstrap 默认暂缓语义向量写入，因此图检索和归属查询可以先可用，而不会强制一次性跑完整嵌入。

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 <repoRoot> 现在默认是 lazy 模式，不安装任何常驻 watcher。需要安装前先跑一个有界批次时可加 --index-now；需要轻量常驻监听时使用 --mode supervisor，需要旧的始终在线 watcher 时显式使用 --mode hot：

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

升级语义召回能力（可选，永不阻塞）

ragcode configure          # 编辑存储 / 提供商 / 模型 / base URL / 维度
ragcode configure --test   # 验证提供商（失败分类清晰；绝不打印密钥）

OpenAI 兼容提供商（OpenAI、Azure、Ollama 等）：

# 云端（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 了解 Azure、Ollama 配置、故障排查和性能对比。

升级重排序质量（可选）

外部 reranker 与 embedding 是两条独立配置。图扩展仍会先运行，确保结构化候选进入候选池；随后 RagCode 可以把有界候选窗口发送给 OpenAI 兼容 /rerank 端点。如果 provider 报错，检索会回退到本地图重排序。

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 命令

# 初始化与诊断
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 <repoRoot>
ragcode refresh <repoRoot>
ragcode status <repoRoot>
ragcode status-human <repoRoot>             # 别名：status-ui
ragcode status-ui <repoRoot>
ragcode watch <repoRoot>
ragcode watch-worker <repoRoot>
ragcode watch-supervisor <repoRoot>
ragcode record-events <repoRoot> <files...>
ragcode service install <repoRoot>          # 默认 lazy；常驻服务使用 --mode supervisor/hot
ragcode service status <repoRoot>
ragcode service uninstall <repoRoot>

# 语义代际生命周期
ragcode semantic-status <repoRoot>
ragcode semantic-rebuild <repoRoot> [--promote]
ragcode semantic-promote <repoRoot> <generation>
ragcode semantic-rollback <repoRoot>
ragcode semantic-prune <repoRoot> [--apply]
ragcode semantic-optimize <repoRoot>

# 检索与分析
ragcode search <repoRoot> <query>
ragcode context <repoRoot> <query>
ragcode brief <repoRoot> [--query <query>]
ragcode owner <repoRoot> <query>
ragcode reuse <repoRoot> <query>
ragcode expand-node <repoRoot> <nodeRef>
ragcode impact <repoRoot> <target>
ragcode explain-impact <repoRoot> <target>
ragcode tests <repoRoot> <target>
ragcode trace-request-flow <repoRoot> <entry>

# 记忆、仪表盘与多智能体工作流
ragcode memory --help
ragcode dashboard
ragcode agents run . --workflow <path> --task "<task>"
ragcode agents start . --workflow <path> --task "<task>"
ragcode agents events . --run <id> [--no-follow]
ragcode agents invoke . --run <id> --message "<message>"
ragcode agents consult . --leader <id> --consultant <id> --task "<task>"
ragcode agents status . --run <id>
ragcode agents cancel . --run <id>

运行 ragcode --help 或 ragcode <command> --help 查看更多细节。

多智能体运行会持久化到 .ragcode/agents/runs/，包含事件账本、产物、报告、执行身份、取消状态和原生会话检查点。工作流 JSON 支持依赖排序、有界重试/修复循环、验证与产物门禁、只读/写入策略以及 CLI 智能体连接器。详见 docs/agents/workflow-spec.md 和 docs/agents/cli-adapters.md。

MCP 服务集成

RagCode 可作为 MCP 服务运行，让 Claude 等智能体直接调用它的工具。按客户端自动注册：

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 客户端配置：

{
  "mcpServers": {
    "ragcode": {
      "command": "ragcode",
      "args": ["mcp"],
      "cwd": "/path/to/your/repo"
    }
  }
}

可用的 MCP 工具（共 24 个）：

索引生命周期 — 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

watch_status 是只读的：它报告是否有活着的 watcher 在保持索引新鲜，但绝不启动 watcher（启动属于 ragcode watch 或 OS 服务的职责）。

MCP 工具使用指南

`get_context` — 面向智能体的上下文包

get_context 工具是 RagCode 为 AI 智能体提供的主要接口。它返回经过验证、预算可控的上下文，并附带明确的推理过程和完整性信号。

输出格式（v0.1.6 新增）

format 参数控制输出结构：

// 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%+）。

示例：

// v0.1.6 之前：可能返回 3.3MB
// v0.1.6 之后：保证 ≤18KB
await mcp.callTool('get_context', {
  query: '登录实现',
  budgetChars: 15000  // 现在会严格遵守！
});

推理透明度（v0.1.6 新增）

每个搜索结果都包含 reason 字段解释相关性：

{
  "filePath": "src/auth/login.ts",
  "score": 9.2,
  "reason": "🎯 关键词匹配：login, authentication • 符号匹配：registerLoginCommand (0.95 置信度) • 图位置：距查询 0 跳"
}

这帮助智能体理解：

为什么选择这个文件（关键词 vs 语义匹配）
什么符号匹配了查询
如何与其他代码关联（图距离）

完整性指标（v0.1.6 新增）

响应包含新鲜度和覆盖率信号：

{
  "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 <repoRoot>，没有索引时运行 ragcode index <repoRoot>
pendingFiles.length > 100 → 大量代码尚未索引
staleFiles.length > 10 → 最近的更改未反映在结果中

查询语言行为

✅ 中文与中英混合查询会在检索前归一化

RagCode 会抽取代码 token、路径、符号、中文分词和领域词典词项后再打分。查询端与 SQLite FTS 索引端共用 Intl.Segmenter，并保留 bigram 降级与 shadow token；中文注释和文档中的代码引用还会生成指向真实符号的确定性 alias。因此无需引入原生中文分词依赖，也能让关于协议、配置、文档、测试、运行时错误、归属和图关系的中文问题命中实现证据。

await mcp.callTool('get_context', {
  query: '网关启动尚未就绪返回哪个 close code 常量',
  budgetChars: 15000
});

trace 诊断会暴露 detectedLanguage、termCategories，以及 raw/lexicon/path/symbol/content 的加权匹配原因。

⚠️ 语义质量仍取决于 embedding 模型

确定性 embedding 兜底离线可靠，但它不是多语言神经模型。需要更好的中文语义召回时，建议使用多语言 OpenAI 兼容 embedding。语义索引受容量限制时会先保证文件覆盖，再按全局质量补位；需要最高精度时，仍建议在查询中加入精确符号、路径或协议/配置词。

推荐查询形态：

// 中文 + 精确符号/路径提示
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 <repoRoot> 继续索引
使用 ragcode status <repoRoot> 监控进度

完整示例

// 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 评审、监听器监控，以及一个带逐字段来源标注和密钥脱敏的运行时配置视图。配置与设置仍然留在终端中完成。

ragcode dashboard       # 打包后的 API + Vue 仪表盘：http://localhost:3000

# 仅源码开发：
npm run web:server
cd web && npm run dev   # Vite 前端：http://localhost:5173

详见 docs/DASHBOARD.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 评审、监听器监控、健康状态、技术栈和脱敏的运行时配置视图。

开发流程

克隆并初始化：

git clone https://github.com/MarshallEriksen-Neura/ragcode.git
cd ragcode
npm install

常用任务（npm 是 CI 使用的标准工具链；本地也可用 bun）：

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）会在每次推送和向 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 自动化完成。

使用确定性嵌入进行离线冒烟运行：

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/（38+ 套件）。它们覆盖整个基础设施：扫描与增量索引、SQLite 与 LanceDB 存储、混合检索与图重排、上下文打包与骨架化、拓扑解析、监听守护进程与日志回放、MCP 服务工具，以及 onboarding/configure CLI 向导。

npm test                    # 完整套件
npm run test:watcher        # 仅监听守护进程 + 状态测试
npx vitest run tests/foundation.test.ts   # 单个套件

当满足以下条件时，基础设施被认为是稳固的：仓库可确定性扫描、分块拥有稳定 ID/哈希、图与语义存储可替换、CLI 与 MCP 调用同一个引擎、严格类型检查通过，并且扫描/索引/搜索/上下文打包都被测试覆盖。任何行为变更都要同步增加或更新测试，并将编写与评审保持为两个独立的环节。

贡献指南

Fork 仓库，并从 main 切出一个功能分支。
进行改动，保持在相关层的边界内（参见 docs/ARCHITECTURE.md）。
为任何行为变更在 tests/ 中增加或更新测试。

推送前在本地运行完整的检查关卡：

npm run check && npm run build && npm test && npm pack --dry-run

推送你的分支，并向 main 提交 Pull Request，附上简明的变更说明与测试情况。

对于智能体辅助贡献，integrations/codex/skills/ 中的 Codex/OMX 技能包提供用于代码智能的 ragcode-context，以及用于共享项目记忆的 ragcode-memory——详见 docs/CODEX_SKILL.md。