# agent-rag-mcp 中文文档

规范地址：https://npmcn.com/package/agent-rag-mcp/

版本：0\.4\.3
npm 元数据更新时间：2026-11-03T00:27:22.896Z
中文译文更新时间：2026-11-03T03:22:26.741Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/agent-rag-mcp
原文对照：https://npmcn.com/package/agent-rag-mcp/?lang=original
项目主页：https://github.com/Lsarmientov/agent-rag
源码仓库：https://github.com/Lsarmientov/agent-rag

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：271 kB，38 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.13\.0
- 运行依赖：9 个
- 首次发布：2026-11-01T04:04:23.575Z
- 最新版本发布：2026-11-03T00:27:22.728Z
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

使用CLI和MCP服务器进行确定性的、独立于名称空间的文档检索。

## 安装

```sh
npm install agent-rag-mcp
```

也可以使用：`pnpm add agent-rag-mcp`、`yarn add agent-rag-mcp`、`bun add agent-rag-mcp`

## README

# agent-rag

## 它是什么？

Agent-rag是按项目逻辑组织的用户故事、契约、规范和手册等文档的确定性的、每个客户端的事实来源。原始字节存储在内容寻址的对象存储中；SQLite是一个可重建的索引，而不是事实的来源。

## 它不是什么

印迹是记忆点；Agent-rag从文件中检索答案。Agent-rag不是聊天机器人：它提供确定的目录和文档读取操作，而不是自主对话。在v1中，它不是LLM或嵌入索引。

## 安装

全局安装，以便MCP适配器可以解析 `agent-rag-mcp` 从它的 `PATH`：

```sh
npm install --global agent-rag-mcp
```

这个 `rag` 目前可用的命令有：

-   `rag init` —初始化命名空间数据库和对象存储。
-   `rag add <path>` —摄取文件并同时将其字节复制到对象存储，因此OneDrive/Files-On-Demand eviction不会丢失摄取的文档。
-   `rag import <dir>` —从目录中获取文件。
-   `rag ls` —列出所选命名空间中的活动文档。
-   `rag rm <document-id>` —逻辑上退出文档并保留其历史记录。
-   `rag relabel <document-id> --label <text>` -替换一个文档的存储标签。
-   `rag entity rename <from> <to>` -纠正项目中的实体密钥。
-   `rag review list` -列出等待人工决策的版本对。
-   `rag review link <from> <to> --type <conflicts_with|same_entity>` -用注释记录版本之间的人工链接。
-   `rag status` —显示命名空间的计数。
-   `rag doctor` —验证注册对象的完整性，并报告丢失的对象、孤立blob或临时文件。
-   `rag backup --to <dir>` —备份清单和对象存储。
-   `rag restore --from <dir>` —恢复该根目录下的备份。
-   `rag reindex` —根据清单和对象重新构建数据库。
-   `rag rehash` -预览重新计算的哈希存储版本； `rag rehash --apply` 在一个事务中写入更改的哈希事实。先预览，然后备份 `rag backup --to <backup-dir>` 在应用之前。
-   `rag rehash --apply` 写 `manifest.json` 在提交数据库事务之前。在该窗口中的中断可能会使清单先于数据库；重新运行 `rag rehash --apply` 或者跑步 `rag reindex` 收敛到要求的事实。

### CLI输出

交互式终端将文档列表呈现为对齐的列，并将其他支持的结果呈现为简明摘要。当输出是管道输出时，命令保留单行JSON信封。集 `RAG_FORMAT=json` 或者 `RAG_FORMAT=pretty` 覆盖终端检测；无效的值退回到自动检测。 `rag --help` 在终端上默认为原始用法文本，而 `RAG_FORMAT=json` 为解析遗留帮助输出的脚本恢复其JSON信封。集 `NO_COLOR` （任何值，包括empty），在不改变输出布局的情况下禁用ANSI样式。

`rag ls` 包括每个文件的 `documentId`． 复制该值以重新标记相同的文档：

```sh
rag ls
rag relabel <document-id> --label "replacement label"
```

结构化文件可以使用 `.yaml`， `.yml`， `.json`，或者 `.jsonl`;每个结构化文件从其解析的数据树中产生部分。YAML使用YAML 1.2核心模式，所以像 `yes` 和 `on` 保持字符串，未加引号的时间戳保持字符串。

### 内容身份

结构化JSON、JSONL和YAML都是从紧凑的规范化JSON中散列出来的，用于它们解析的数据树，没有格式前缀。他们的 `doc_version` 行用 `content_kind='structured'` 和 `hash_version=2`;因此，等价树可以跨格式和键顺序共享内容散列。其他格式保留现有的规范化提取文本散列并使用 `content_kind=NULL` 与 `hash_version=1`． 现有的版本行保持在版本1，并具有空内容类型，直到使用 `rag rehash`;修复不会重写存储的对象字节，也不会跳过不能进行常规散列的结构化文档。

默认的知识库根为 `%USERPROFILE%\.rag\`． 每个客户端都有自己的 `rag.db` 下 `.rag\clients\<client>\`;项目在客户端中是合乎逻辑的，并由 `project_id`． 命名空间就是pair `(client, project)`． 默认情况下, `failClosed` 是 `true`;如果没有名称空间，则允许读取 `failClosed` 设为 `false`，写入到保留的 `default/default` 名称空间。Tier 3人工审核队列可通过 `rag review list`.

`rag add` 是幂等的吗 `sha256`：再次添加相同的字节将返回 `{namespace, result}` 信封 `result.status` 设置为 `"unchanged"` 也不会产生新的版本。不同的散列创建新的散列 `doc_version` 不删除前一个。删除是一个逻辑墓碑；版本历史被保存。 `label` 是重新摄取所匹配的，因此重新标记将文档从相同源路径的未来导入中分离出来，然后该路径将作为新文档出现。

## MCP

在适配器配置中注册两个独立的服务器进程（本例使用公共的） `mcpServers` 格式)。取代 `/path/to/rag-data` 带绝对存储路径：

```json
{
  "mcpServers": {
    "agent-rag-orchestrator": {
      "command": "agent-rag-mcp",
      "args": [],
      "env": {
        "RAG_ROOT": "/path/to/rag-data",
        "RAG_CAPABILITIES": "find"
      }
    },
    "agent-rag-explorer": {
      "command": "agent-rag-mcp",
      "args": [],
      "env": {
        "RAG_ROOT": "/path/to/rag-data",
        "RAG_CAPABILITIES": "find,read"
      }
    }
  }
}
```

编排器只接收 `rag_find`，它返回引文和有界摘录。资源管理器也接收到 `rag_read`，它从引文中读取有界文本。将它们分开使用最小特权。服务器读取 `RAG_ROOT` 定位知识库和 `RAG_CAPABILITIES` 决定宣布哪些工具。

扩展增加了 `rag` 部分向代理系统提示符描述命名空间和委托规则；该部分不包含客户端、项目或路径值。集 `RAG_PROMPT=off` （正是这个值）来抑制它；任何其他值，包括unset，都会保留它。

命名空间在每个 `rag_find` 或者 `rag_read` 调用;它不是来自环境。例如，包括 `"namespace": {"client":"acme","project":"research"}` 在每个工具调用的参数中。不要配置 `RAG_CLIENT` 或者 `RAG_PROJECT` 作为每个调用名称空间的替代品。

## 要求

-   Node.js >= 22.13。
-   这个 `.mts` 运行的源文件 `--experimental-strip-types --experimental-sqlite`.
-   `npm run build` 使用esbuild（每个文件）构建每个源文件。
-   `npm test` 运行Node的测试 `node:test`.
-   `npm run typecheck` 运行TypeScript类型检查而不输出文件。

## 已知的限制

版本0.1.0没有嵌入或Tier 2；扫描的pdf通过OCR。文档解析在具有512 MB V8堆帽的子进程中运行。

## 设计文档

-   [体系结构](https://github.com/Lsarmientov/agent-rag/blob/main/docs/design/0001-arquitectura.md)
-   [数据模型](https://github.com/Lsarmientov/agent-rag/blob/main/docs/design/0002-modelo-de-datos.md)
-   [身份和副本](https://github.com/Lsarmientov/agent-rag/blob/main/docs/design/0003-identidad-duplicados.md)

## 许可证

麻省理工学院。

## 常见问题

### agent-rag-mcp 是什么？

使用CLI和MCP服务器进行确定性的、独立于名称空间的文档检索。

### 如何安装 agent-rag-mcp？

在项目目录运行 npm install agent-rag-mcp，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 rag、agent-rag-mcp，可以用 npx rag 直接运行。

### agent-rag-mcp 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/agent-rag-mcp 是否存在。

### agent-rag-mcp 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### agent-rag-mcp 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.13\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### agent-rag-mcp 可以商用吗？

agent-rag-mcp 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### agent-rag-mcp 还在维护吗？

最新版本 0\.4\.3 发布于 2026/11/03（今天）；至今共发布 8 个版本，其中过去 12 个月发布了 8 个；首次发布于 2026/11/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。