内容
# Ragmir
[](https://github.com/jcode-works/jcode-ragmir/actions/workflows/ci.yml)
[](https://github.com/jcode-works/jcode-ragmir/actions/workflows/codeql.yml)
[](https://www.npmjs.com/package/@jcode.labs/ragmir)
[](https://www.npmjs.com/package/@jcode.labs/ragmir)
[](https://github.com/jcode-works/jcode-ragmir/blob/main/LICENSE)
开源本地RAG库、命令行工具和MCP服务器。Ragmir在本地索引您的规格、文档和代码，并为您的AI代理提供有用的引用段落， 通过MCP，无需在整个存储库上消耗令牌。
根据您的需求构建，将所有内容保留在您的机器上，并让Claude、Codex、Kimi、OpenCode、Cline或任何MCP客户端从您的真实来源回答。Ragmir安装到任何Node.js存储库中，本地使用LanceDB存储向量，默认情况下完全离线运行，内置本地哈希检索或可选的Transformers.js语义嵌入。
Ragmir Core返回引用的检索上下文。答案合成属于您选择的AI代理、LLM或本地模型运行时，因此每个答案都基于您的真实证据。
由Jean-Baptiste Thery创建，并发布在JCode Labs的npm范围内。
## 开发者用例
Ragmir设计用于在有用上下文本地、私有并分布在存储库、规格、导出和同步文件夹时进行代理辅助开发。
| 用例 | 它启用 |
| --- | --- |
| 索引存储库的文档 | 向Claude Code、Codex、Kimi Code CLI、OpenCode、Cline或另一个代理询问如何从本地README文件、架构笔记、API合约、ADR和运行手册中实现功能。 |
| 从规格或`cahier des charges`编写代码 | 将本地PRD、招标响应、客户简介或工程规格转化为实现计划、验收检查清单和引用变更指南。 |
| 从下载的Google Drive文件夹工作 | 将Ragmir指向通过Google Drive桌面版本地同步的文件，然后让代理在不将语料库上传到托管的RAG服务的情况下检索上下文。 |
| 入职到遗留代码库 | 询问流程在哪里实现，哪些模块拥有责任，哪些文档解释了行为，以及在更改高风险代码之前需要阅读什么。 |
| 将密集文档转换为可听的迷你学习 | 使用`ragmir audio`从引用段落生成短的口语摘要（MP3/WAV），以便免提审查规格、架构文档或研究通过手。 |
| 在同一证据上保留多个代理 | 为Claude Code、Codex、Kimi Code CLI、OpenCode和Cline安装相同的项目技能和MCP服务器，以便每个工具从相同的本地索引中检索。 |
| 实现前研究 | 在询问代理规划功能、迁移或审查之前，在规格、文档和代码引用上运行审计支持的多查询传递。 |
| 准备实施和审查工作 | 从团队使用的相同本地源生成引用的任务分解、迁移说明、发布检查清单、QA计划和代码审查上下文。 |
| 审计本地知识覆盖 | 检查哪些支持的文件被索引，哪些格式被跳过，是否可能存在机密，以及黄金查询是否仍然检索预期的证据。 |
工作流程保持简单：保留磁盘上的文件，运行`ragmir ingest`，通过MCP或便携式技能连接您的编码代理，然后询问它从引用的本地段落中工作。
## 概览
Ragmir是AI代理的本地证据层：将文档放入存储库中，在本地索引它们，然后让您的CLI、MCP兼容代理或捆绑的技能在不将语料库上传到托管的RAG服务的情况下检索引用的段落。
```mermaid
flowchart TD
subgraph Workspace["您的存储库"]
Docs["本地文件<br/>文档、规格、代码、PDF"]
Config[".ragmir/config.json<br/>.ragmir/raw/"]
Index[".ragmir/storage<br/>本地LanceDB索引"]
end
subgraph Ragmir["Ragmir Core"]
Ingest["ragmir ingest<br/>解析、编辑、切分"]
Retrieve["ragmir search / ask / research<br/>排名引用证据"]
Audit["doctor, audit,<br/>安全审计、评估"]
end
subgraph Agents["开发者工具"]
CLI["终端"]
MCP["MCP服务器"]
Skills["便携式代理技能"]
LLM["Claude、Codex、<br/>或您的受信任模型"]
end
Docs --> Ingest
Config --> Ingest
Ingest --> Index
Index --> Retrieve
Index --> Audit
Retrieve --> CLI
Retrieve --> MCP
Skills --> MCP
MCP --> LLM
```
最快的实用路径是在存储库中安装Ragmir，将其连接到您已经使用的编码代理，然后询问该代理基于本地文件的问题：
```bash
npm install --save-dev @jcode.labs/ragmir
npx ragmir setup
# 可选：下载Transformers.js嵌入模型一次并启用更高质量的语义检索。
npx ragmir setup --semantic
npx ragmir install-agent --agents claude,codex,kimi,opencode,cline
npx ragmir doctor --fix
npx ragmir research "发布准备和风险" --compact
# Claude Code
claude mcp add-json --scope local ragmir "$(cat .ragmir/claude-mcp-server.json)"
# Codex
cat .ragmir/codex-mcp.toml
# Kimi Code CLI
kimi --mcp-config-file .ragmir/kimi-mcp.json
# OpenCode
cat .ragmir/opencode.jsonc
# Cline
cat .ragmir/cline-mcp.json
```
在需要基于私有规格、代码库、法律档案、招标、课程材料、项目存档或会议笔记的 grounded上下文时使用它，但文件应保留在您的机器上。
## 包
此README是公共npm包的规范文档。
| 包 | 角色 |
| --- | --- |
| `@jcode.labs/ragmir` | Ragmir Core：CLI、库、MCP服务器、捆绑的代理技能和合成示例。 |
| `@jcode.labs/ragmir-tts` | Ragmir插件，用于Edge质量的MP3和离线Transformers.js WAV渲染，通过`ragmir audio`。 |
| `@jcode.labs/ragmir-ui` | 未发布的Ragmir表面工作区UI包，适用于WorkoutGen设计基础。 |
| `@jcode.labs/ragmir-landing` | 未发布的Astro静态登陆包。产品面向的标题保留为`Ragmir`。 |
| `@jcode.labs/ragmir-app` | 未发布的Tauri桌面/移动壳包。原生构建是明确的应用程序命令。核心集成使用围绕`ragmir` CLI的限定原生命令，带有打包的边车分发。 |
| `@jcode.labs/ragmir-license-webhook` | 未发布、未部署的MIT许可Cloudflare Worker处理程序，用于未来的Lemon Squeezy webhook和本地`RAGMIR1`许可发布。 |
软件包README文件故意简短，因为npm分别显示每个软件包的README。它们指向npm读者回到此GitHub文档。
产品名称对用户可见的是 **Ragmir**。技术核心包是 **Ragmir Core**，现在位于 `packages/ragmir-core`；公共npm包名称保留为 `@jcode.labs/ragmir`。
公共源和商业分发边界在 [`docs/source-boundary.md`](./docs/source-boundary.md) 和 [`docs/commercial-distribution.md`](./docs/commercial-distribution.md) 中跟踪。没有检出URL、生产下载URL、客户数据或许可机密被提交到此存储库中。
## 文档
使用此README作为入口，然后在需要命令表、代理连接、API形状、安全详细信息或应用打包规则时跳转到聚焦的文档：
| 文档 | 用它来 |
| --- | --- |
| [`docs/cli-reference.md`](./docs/cli-reference.md) | 完整的`ragmir`和`ragmir-tts`命令参考。 |
| [`docs/api-reference.md`](./docs/api-reference.md) | 公共TypeScript API、设置选项、语义模型预加载和MCP工具输入。 |
| [`docs/agent-integration.md`](./docs/agent-integration.md) | Claude Code、Codex、Kimi Code CLI、OpenCode和Cline设置。 |
| [`docs/troubleshooting.md`](./docs/troubleshooting.md) | 空索引、弱搜索、严格的安全审计警告和音频预加载修复。 |
| [`SECURITY-HARDENING.md`](./SECURITY-HARDENING.md) | 威胁模型、离线操作、发布验证和更高保证的部署说明。 |
| [`docs/offline-tts-preload.md`](./docs/offline-tts-preload.md) | 预加载和验证离线Transformers.js TTS缓存。 |
| [`docs/fr-eu-sovereign-positioning.md`](./docs/fr-eu-sovereign-positioning.md) | 有限的FR/EU主权、GDPR、AI法案和法律垂直定位。 |
| [`docs/source-boundary.md`](./docs/source-boundary.md) | 公共MIT存储库中包含的内容和必须留在Git外部的内容。 |
| [`docs/commercial-distribution.md`](./docs/commercial-distribution.md) | 签名构建、许可证和支持的公共安全商业分发规则。 |
| [`docs/app-sidecar-architecture.md`](./docs/app-sidecar-architecture.md) | 桌面应用边车和原生桥约束。 |
| [`docs/app-distribution.md`](./docs/app-distribution.md) | 直接下载的原生应用打包和发布预检。 |
| [`docs/payment-webhook-architecture.md`](./docs/payment-webhook-architecture.md) | 未来的结账、webhook和本地许可架构。 |
| [`llms.txt`](./llms.txt) | 面向Context7等工具的LLM文档索引。 |
## 开源
Ragmir是一个在MIT许可下的公共开源项目。它设计为可检查、可分叉和在无需JCode Labs帐户的情况下可用。
此存储库中的每个跟踪包都是可见源。商业Ragmir应用分发可以控制官方签名构建、支持、更新和托管的许可交付，但它不会使跟踪的Tauri应用或webhook源专有。
通过拉取请求欢迎贡献。从 [`CONTRIBUTING.md`](./CONTRIBUTING.md) 开始。安全报告应保持私密并遵循 [`SECURITY.md`](./SECURITY.md)。
## 赞助商
Ragmir保持MIT开源。赞助有助于维护、问题排查、文档和实用代理工作流改进。
通过 [GitHub Sponsors](https://github.com/sponsors/jb-thery) 赞助该项目。
建议的GitHub Sponsors层级：
- EUR 5/月：支持该项目。
- EUR 15/月：活跃的赞助商。
- EUR 49/月：问题和问题的优先权。
- EUR 199/月：公司赞助商和轻度咨询支持。
## 状态
早期公共包。在 `1.0.0` 之前，API可能会演变。
## 桌面客户端预览
Ragmir Core是您今天可以通过CLI、库、MCP服务器和便携式代理技能使用的开源产品。
一个跨平台的Ragmir桌面/移动客户端正在`packages/ragmir-app`中开发。它的目标是为非CLI工作流程提供更便捷的本地保密工作空间：注册本地档案，运行设置和摄取，询问问题并引用本地段落，检查隐私姿态，并显式预加载嵌入模型。Google Drive支持作为一个可选的本地同步文件夹流实现，适用于已经存在于磁盘上的文件，而不是作为默认的云API集成。
原生客户端尚未发布、签名或商业分发。没有结账、等待列表或此存储库中托管的帐户流程。当发布时，计划直接下载和侧载安装程序，而不是App Store或Play Store分发。
规范的登陆和未来直接下载发布网址是 [`ragmir.jcode.works`](https://ragmir.jcode.works)。它准备作为Cloudflare Workers静态资产站点，但公共部署仍然是一个单独的发布操作。
## Ragmir的用途
- 在任何存储库中构建本地RAG知识库。
- 在保持原始文件和生成索引本地的情况下分析机密数据集。
- 为Claude、Codex、Kimi、OpenCode、Cline、内部助手或其他MCP兼容工具提供相同的私有检索层。
- 通过CLI、库调用、MCP工具或捆绑的代理技能检索基于证据的本地证据。
- 可选地，使用捆绑的技能创建可听的MP3/WAV摘要或引用的Markdown报告。
- 使用可选的捆绑的法律技能准备法律档案摘要、时间表、条款审查和专业审查交接。
Ragmir不是托管的SaaS，不是远程向量数据库，也不是认证的高保证系统。对于受监管或国家级环境，请将其与加密磁盘、受控机器、发布验证和外部安全审查配对。
## 要求
- Node.js 20或更新版本。
- pnpm、npm、yarn或bun。
- 一个存储库，其中生成的本地文件夹可以被Git忽略。
- 默认`embeddingProvider: "local-hash"`模式不需要模型运行时。
- 可选的语义嵌入使用Transformers.js，带有本地模型文件在`.ragmir/models`下。 当远程模型下载可接受时，使用`ragmir models pull`，然后保持`transformersAllowRemoteModels`为false以进行机密索引。
- 生成的答案故意在Ragmir核心之外。 使用Claude、Codex、OpenAI、本地模型MCP服务器或另一个受信任的模型运行时来从Ragmir的引用上下文中合成。
## 安装
该软件包是公开的。用户无需JCode Labs帐户或npm令牌即可安装它。
使用npm：
```bash
npm install --save-dev @jcode.labs/ragmir
```
使用pnpm：
```bash
pnpm add -D @jcode.labs/ragmir
```
仅当您直接使用时，安装独立的TTS软件包：
```bash
npm install --save-dev @jcode.labs/ragmir-tts
```
维护者令牌仅在发布新版本时需要。
## 快速入门
初始化存储库，安装便携式代理工具包，运行就绪检查，并在支持的文件已经存在时摄取文档：
```bash
# 快速启动：无需模型下载，全局词汇/哈希检索。
npx ragmir setup
# 更高质量的自然语言检索：一次性Transformers.js模型下载，
# 然后远程模型加载保持禁用以进行正常的机密索引。
npx ragmir setup --semantic
```
全新设置在单个被忽略的`.ragmir/`文件夹下保留本地状态：
```plain text
.ragmir/config.json # 本地配置
.ragmir/sources.txt # 可选的额外源路径
.ragmir/raw/ # 要摄取的原始文档
.ragmir/storage/ # 摄取后生成的LanceDB索引
.ragmir/access.log # 使用后仅包含元数据的访问日志
.ragmir/skills/ragmir/SKILL.md # 便携式代理技能
.ragmir/skills/ragmir-audio-summary/SKILL.md
.ragmir/skills/ragmir-markdown-report/SKILL.md
.ragmir/skills/ragmir-legal-dossier/SKILL.md
.ragmir/mcp.json # 泛型MCP服务器配置片段
.ragmir/claude-mcp-server.json # Claude Code add-json有效载荷
.ragmir/codex-mcp.toml # Codex config.toml片段，包含MCP和skills.config
.ragmir/kimi-mcp.json # Kimi Code CLI MCP配置
.ragmir/opencode.jsonc # OpenCode配置片段
.ragmir/cline-mcp.json # Cline MCP配置
.ragmir/agent-setup.md # 代理特定设置指南
.gitignore # 忽略.ragmir/
```
它检测存储库包管理器并使用正确的命令写入MCP帮助文件：`npx ragmir serve-mcp`，`pnpm exec ragmir serve-mcp`，`yarn exec ragmir serve-mcp`或`bunx ragmir serve-mcp`。当存储库需要包装脚本或仅代理帮助程序的子集时，请在设置期间明确说明：
```bash
npx ragmir setup --agents claude,codex --mcp-name project-docs --mcp-command ./scripts/serve-mcp.sh
```
对于通常的先有代理工作流，请向存储库中使用的编码助手公开Ragmir：
```bash
npx ragmir install-agent --agents claude,codex,kimi,opencode,cline
```
然后连接您使用的代理。Claude Code、Codex和Cline遵循其公共文档的标准MCP形状；Kimi和OpenCode使用Ragmir在`.ragmir/`下编写的生成器帮助文件。
```bash
# Claude Code：在此存储库的本地MCP服务器。
claude mcp add-json --scope local ragmir "$(cat .ragmir/claude-mcp-server.json)"
# Codex：审查和合并生成的MCP和技能配置。
cat .ragmir/codex-mcp.toml
# Kimi Code CLI：使用生成的Ragmir MCP配置启动Kimi。
kimi --mcp-config-file .ragmir/kimi-mcp.json
# OpenCode：审查和合并生成的OpenCode JSONC片段。
cat .ragmir/opencode.jsonc
```
# Cline：将在 Cline 的 mcpServers 配置下添加生成的 JSON。
cat .ragmir/cline-mcp.json
```
从代理中，自然地询问，例如：“使用 Ragmir 查找此存储库关于部署的内容。” 代理调用 MCP 工具，并使用捆绑的技能来处理引用的本地上下文。
在任何时候检查准备情况：
```bash
npx ragmir doctor
```
如果索引中缺少文件、文件已过时或设置不完整，请运行：
```bash
npx ragmir doctor --fix
```
`doctor --fix` 执行安全修复：缺少的脚手架、Git 忽略条目、代理工具安装和索引重建，当支持的文件存在且隐私立场没有警告时。
仍然可以手动初始化：
```plain text
.ragmir/config.json # 本地配置（在"sources"数组中添加额外路径）
.ragmir/raw/ # 要摄入的原始文档
.gitignore # 忽略 .ragmir/
```
将支持的文件放在 `.ragmir/raw/` 下：
```plain text
.ragmir/raw/
policy.md
meeting-notes.pdf
requirements.docx
```
对于 monorepos 或下载的本地文件夹，请在 `.ragmir/config.json` 中添加额外的路径或 glob 模式到 `sources` 数组。相对条目从 Ragmir 项目根目录解析，`!` 排除匹配的文件：
```json
{
"sources": [
"../apps/*/README.md",
"../apps/*/docs/**/*.{md,mdx}",
"../packages/*/architecture/**/*.md",
"!../apps/**/node_modules/**"
]
}
```
遗留的 `.ragmir/sources.txt` 文件（每行一个条目）仍然被读取，当存在时，可以从 CLI 管理：
```bash
npx ragmir sources add "../apps/*/README.md" "../apps/*/docs/**/*.{md,mdx}"
npx ragmir sources list
```
### 使用共享私有语料库的团队工作流
对于一个由 10 名开发人员组成的团队，将 Git 保留为可复制的设置层，并将语料库保留在批准的私有源中。每个开发人员在本地实现相同的语料库，然后构建自己的本地 Ragmir 索引。
```plain text
Git repository
README.md
ragmir.config.example.json
ragmir-sources.example.txt
scripts/sync-corpus.sh
Ignored local state on each developer machine
.ragmir/config.json
.ragmir/sources.txt
.ragmir/raw/ or data/private-corpus/
.ragmir/storage/
.ragmir/access.log
.ragmir/models/
```
如果您的团队使用 Google Drive、Dropbox、SharePoint、S3、rsync、加密 ZIP 或其他私有源，请编写一个小型项目脚本，将其同步到一个被忽略的本地文件夹，然后摄入：
```bash
#!/usr/bin/env bash
set -euo pipefail
mkdir -p .ragmir/raw
# 示例仅供参考：请用您批准的私有同步命令替换此命令。
# rclone copy "team-drive:Project Knowledge" .ragmir/raw --drive-export-formats docx,xlsx,pptx,pdf
npx ragmir ingest
npx ragmir doctor
```
提交脚本和说明，而不是同步的文件。相同的模式在没有 Google Drive 的情况下也适用：每个开发人员下载相同的批准存档或镜像到同一个被忽略的路径，然后运行 `npx ragmir ingest`。Ragmir 比较校验和并重用未更改的行，因此刷新保持增量。
构建本地索引：
```bash
npx ragmir ingest
npx ragmir doctor
```
当索引准备就绪时，`ragmir doctor` 会打印 `ready=true`。`ragmir ingest` 和 `ragmir audit` 还会报告因类型不支持、文件太大或文件名看起来像秘密/私钥而被发现但未编制索引的文件。
显式列出跳过的路径：
```bash
npx ragmir audit --unsupported
```
在不暴露原始查询或本地路径的情况下，总结最近的仅限元数据的使用情况：
```bash
npx ragmir usage-report --days 7
```
检索确切的段落：
```bash
npx ragmir search "approval for offline operation"
```
为代理或模型返回引用的检索上下文：
```bash
npx ragmir ask "What evidence supports offline operation?"
```
在进行广泛的综合或实施任务之前，运行审计支持的多查询研究通道：
```bash
npx ragmir research "release readiness and risks" --compact
```
在黄金查询文件上衡量召回率：
```bash
npx ragmir evaluate --golden golden-queries.json
```
对于私有测试，将真实的语料库和黄金查询文件保留在 Git 之外或被忽略的本地路径下，然后使用与评估阶段相匹配的阈值：
```bash
npx ragmir --project-root /path/to/workspace ingest
npx ragmir --project-root /path/to/workspace evaluate --golden .ragmir/evaluations/golden-queries.json --fail-under 0.8 --json
```
JSON 报告包括活动的 `embeddingProvider` 和 `embeddingModel`，因此您可以将默认的本地哈希召回率与私有 Transformers 语义运行进行比较，而无需将报告存储在 Git 中。
Ragmir 不会合成 LLM 答案。它返回引用的本地段落；您选择的代理或模型会围绕这些段落编写内容。
使用 pnpm 时，在安装软件包后使用 `pnpm exec`：
```bash
pnpm exec ragmir setup
pnpm exec ragmir doctor
pnpm exec ragmir search "approval for offline operation"
```
## 选择检索模式
Ragmir 有两种嵌入模式。
### 默认本地哈希检索
在您想要完全本地、无模型烟雾测试或依赖关系轻量级设置时使用此模式。检索基于词典/哈希，而不是语义。
`.ragmir/config.json`:
```json
{
"embeddingProvider": "local-hash"
}
```
命令：
```bash
npx ragmir ingest
npx ragmir search "offline retrieval approval"
npx ragmir ask "What evidence supports offline operation?"
```
`ragmir ask` 始终返回引用的检索段落，而不是生成的综合。您可以将这些段落传递给您信任的任何 LLM 或代理。
### 可选的语义嵌入与 Transformers.js
在您想要更好的语义检索同时保持 Ragmir 核心免受 LLM 服务器影响时使用此模式。
`.ragmir/config.json`:
```json
{
"embeddingProvider": "transformers",
"embeddingModel": "mixedbread-ai/mxbai-embed-xsmall-v1",
"embeddingModelPath": ".ragmir/models",
"transformersAllowRemoteModels": false
}
```
命令：
```bash
npx ragmir setup --semantic
# 或稍后：
npx ragmir models pull --enable
npx ragmir ingest
npx ragmir ask "Which passages support offline operation?"
```
`ragmir setup --semantic` 是一个首跑快捷方式。它故意允许一次性从 Hugging Face 下载到 `embeddingModelPath`，将 `.ragmir/config.json` 切换到 `embeddingProvider: "transformers"`，并将 `transformersAllowRemoteModels` 设置为 false 以进行正常的机密索引。使用 `ragmir models pull --enable` 时，您想在以后做出相同的选择。更改嵌入提供程序或模型后，请重新运行 `ragmir ingest --rebuild` 以使存储的向量与活动配置匹配。
## 代理技能和 MCP
Ragmir 配备了可移植的代理技能和标准 MCP 服务器。
使用 `ragmir setup` 进行正常路径，或仅在以后安装代理层：
```bash
npx ragmir install-skill
npx ragmir install-skill --agents claude,codex --mcp-command ./scripts/serve-mcp.sh
npx ragmir install-agent --agents claude,codex,kimi,opencode,cline
```
主要代理示例：
```bash
# Claude Code
claude mcp add-json --scope local ragmir "$(cat .ragmir/claude-mcp-server.json)"
# Codex
cat .ragmir/codex-mcp.toml
# Kimi Code CLI
kimi --mcp-config-file .ragmir/kimi-mcp.json
# OpenCode
cat .ragmir/opencode.jsonc
# Cline
cat .ragmir/cline-mcp.json
```
在兼容的代理需要工具访问时，从存储库根目录启动 MCP 服务器：
```bash
npx ragmir serve-mcp
```
MCP 服务器公开 `ragmir_status`、`ragmir_search`、`ragmir_ask`、`ragmir_research`、`ragmir_audit`、`ragmir_evaluate`、`ragmir_usage_report` 和 `ragmir_security_audit`。LLM 不需要了解 LanceDB 或原始文件布局；它询问 Ragmir 获取排名的段落、引用的上下文、审计支持的研究、本地召回门控或仅限元数据的使用摘要，并使用返回的引用。
每个代理的设置详细信息位于 [`docs/agent-integration.md`](./docs/agent-integration.md)。
## 音频摘要
Ragmir 包括一个即插即用的文本转语音路径，用于可听见的摘要。
对于与全局 Voice Forge 技能相同的质量路径，请安装 `edge-tts` 并渲染 MP3：
```bash
npx ragmir audio --doctor
pipx install edge-tts
npx ragmir audio /tmp/RAGMIR-SUMMARY-project.txt \
--engine edge \
--out .ragmir/audio/project-summary.mp3
```
Edge 路径使用在线 Microsoft Edge TTS 服务通过 `edge-tts` CLI。使用它仅当将叙述文本发送到该服务是可以接受的时。MP3 输出需要明确的 `--engine edge` 原因。
默认情况下，`ragmir audio` 使用 Transformers.js WAV 路径。对于机密或隔离工作，请预加载 Transformers.js 兼容的模型文件，并离线渲染 WAV：
```bash
npx ragmir audio /tmp/RAGMIR-SUMMARY-project.txt \
--engine transformers \
--offline \
--lang fr \
--model-path .ragmir/models/tts \
--out .ragmir/audio/project-summary.wav
```
直接使用独立软件包：
```bash
npx ragmir-tts doctor --json
npx ragmir-tts render /tmp/RAGMIR-SUMMARY-project.txt \
--engine edge \
--out .ragmir/audio/project-summary.mp3
```
默认的独立引擎是 `transformers`，默认语言是 `fr`。传递 `--lang en|es|fr` （或 `RAGMIR_TTS_LANG`）以切换语言：它选择匹配的自包含离线模型（`Xenova/mms-tts-eng`、`Xenova/mms-tts-spa` 或 `Xenova/mms-tts-fra`）并在 Edge 路径上使用原生神经语音。直接使用 `--model` 或 `RAGMIR_TTS_MODEL` 覆盖模型。
参见 [`docs/offline-tts-preload.md`](./docs/offline-tts-preload.md) 以获取确切的预加载和离线检查工作流程。
## 数据边界
软件包代码位于 `node_modules` 或此存储库中。项目数据保留在您运行 CLI 的存储库中：
```plain text
your-project/
.ragmir/config.json # 本地配置
.ragmir/sources.txt # 可选的额外源路径
.ragmir/raw/ # 要摄入的原始文档
.ragmir/storage/ # 生成的 LanceDB 索引
.ragmir/access.log # 仅限元数据的访问日志
```
软件包从不发送项目文档。`ragmir setup` 添加了一个 `.ragmir/` gitignore 条目，以便生成的索引、代理文件、原始文档、报告、模型、音频和访问日志保持在目标存储库的本地。
已经有 `.kb/config.json` 的旧项目仍然有效。在这种模式下，Ragmir 保留旧默认值（`private/`、`.kb/storage`、`.kb/sources.txt`、`.kb/access.log`）并接受现有的 `KB_*` 环境变量。新设置和文档使用 `.ragmir/` 和 `RAGMIR_*`。
## 机密性默认值
Ragmir 设计用于私有存储库和敏感的本地证据。
- 零遥测：没有分析或文档内容被发送到 JCode Labs。
- 核心中没有 LLM 生成：Ragmir 返回引用的上下文，供您选择的代理/运行时使用。
- 默认本地哈希：默认检索路径不需要模型运行时。
- Transformers.js 远程模型加载默认禁用。
- 可选的 Transformers.js 模型下载需要显式的预加载命令或 `--allow-remote-models`；机密运行应使用已经缓存的本地模型文件。
- 索引前删除：常见秘密和标识符在嵌入和存储切片之前被删除。
- 仅限元数据的访问日志：查询哈希和操作元数据被记录，而不是原始查询。
- 仅限元数据的使用报告：`ragmir usage-report --days 7` 在不暴露查询文本或本地路径的情况下总结最近的本地活动。
- MCP 以读取为中心，并受 `mcpMaxTopK` 限制。
- 生成的本地状态被 Git 忽略。
运行：
```bash
npx ragmir security-audit --strict
```
删除生成的向量索引：
```bash
npx ragmir destroy-index --yes
```
`destroy-index` 不会对 SSD 或 copy-on-write 存储提供安全的擦除保证。对于强删除保证，请使用加密存储并销毁加密密钥。
有关离空操作、发布验证、安全删除限制和威胁模型详细信息，请阅读 [`SECURITY-HARDENING.md`](./SECURITY-HARDENING.md)。
## 支持的文件
Ragmir 默认支持常见的文本、文档、数据、配置、日志和源代码文件：
- Markdown：`.md`、`.mdx`
- 文本：`.txt`、`.text`
- JSON：`.json`
- YAML：`.yaml`、`.yml`
- CSV/TSV：`.csv`、`.tsv`
- HTML：`.html`、`.htm`
- EPUB：`.epub`
- PDF：`.pdf`
- Office/OpenDocument：`.docx`、`.pptx`、`.xlsx`、`.odt`、`.ods`、`.odp`
- 旧版 Excel：转换 `.xls` 工作簿为 `.xlsx`、CSV、PDF、HTML 或文本，然后摄入
- 旧版 Word：`.doc` 仅在配置了显式的本地 `legacyWordCommand` 时
- 富文本：`.rtf`
- 笔记本：`.ipynb`
- 字幕/日历/邮件：`.vtt`、`.srt`、`.ics`、`.eml`
- 行数据和日志：`.jsonl`、`.ndjson`、`.log`
- XML 源文档：`.xml`、`.rss`、`.atom`、`.svg`
- 配置和数据文件：`.toml`、`.ini`、`.conf`、`.cfg`、`.properties`、`.sql`、`.example`、`.exemple`
- 常见项目元数据：`.gitignore`、`.dockerignore`、`.npmignore`、`.gitlab-ci.yml`、`.vscode/settings.json`、Maven 包装器 `.properties`
- 源代码：`.ts`、`.tsx`、`.mts`、`.cts`、`.js`、`.jsx`、`.mjs`、`.cjs`、`.py`、`.go`、`.rs`、`.java`、`.rb`、`.php`、`.cs`、`.c`、`.cpp`、`.h`、`.hpp`、`.css`、`.scss`、`.vue`、`.svelte`、`.astro`、`.sh`、`.bash`、`.bat`、`.cmd`、`.ps1`
- 常见的无扩展文本包装器：`mvnw`、`gradlew`、`Dockerfile`、`Makefile`、`Procfile`、`Gemfile`、`Rakefile`
- 文档/代码审查文本：`.rst`、`.adoc`、`.tex`、`.diff`、`.patch`、`.markdown`、`.mdown`、`.mmd`
自定义 UTF-8 文本扩展名可以在不更改代码的情况下启用：
```json
{
"includeExtensions": [".transcript", ".evidence"]
}
```
或通过：
```bash
RAGMIR_INCLUDE_EXTENSIONS=".transcript,.evidence" npx ragmir ingest
```
音频/视频文件和未列出的格式对 Ragmir 来说不是很有用。它们仍然可以是有价值的源证据，但它们应该在摄入之前转录、转换或导出为文本/PDF/HTML。`ragmir audit --unsupported` 打印每个文件的建议格式。对于扫描的 PDF，可以使用显式的 `pdfOcrCommand` 包装器，当您接受运行本地 OCR 工具时。静态图像文件如 `.png`、`.jpg`、`.heic` 和 `.tiff` 默认情况下不受支持，但可以通过显式的本地 `imageOcrCommand` 包装器进行索引。旧版 `.doc` Word 二进制文件默认情况下不受支持，但可以通过显式的本地 `legacyWordCommand` 包装器进行索引。如果支持的文件解析为空文本，则 `ragmir ingest --json` 会在 `emptyTextFiles` 下报告。Ragmir 有意避免假装可以安全索引每个二进制格式而不进行提取逻辑。
默认跳过 `.env`、`.npmrc`、私钥和证书等类似秘密的文件。转换安全示例为正常文本格式后再摄入。
点文件被发现，以便有用的项目元数据不会被静默忽略。包含 `.pem`、`.key`、`.p12`、`.pfx`、`.jks`、`.gpg` 和常见秘密文件名（如 `.env`、`.npmrc`、`.netrc` 和 `.pgpass`）的文件默认跳过，即使它们位于源目录下。
配置参考
大多数用户应该从 `ragmir setup` 开始，让 `ragmir doctor` 解释缺少的内容。只有在需要更改源路径、检索模式、块大小、隐私限制或本地提取器时，才编辑 `.ragmir/config.json`。
全新项目的默认 `.ragmir/config.json` 配置文件：
```json
{
"rawDir": ".ragmir/raw",
"storageDir": ".ragmir/storage",
"sourcesFile": ".ragmir/sources.txt",
"sources": [],
"accessLogPath": ".ragmir/access.log",
"embeddingModelPath": ".ragmir/models",
"tableName": "chunks",
"embeddingProvider": "local-hash",
"embeddingModel": "mixedbread-ai/mxbai-embed-xsmall-v1",
"transformersAllowRemoteModels": false,
"redaction": {
"enabled": true,
"builtIn": true,
"patterns": []
},
"accessLog": true,
"mcpMaxTopK": 10,
"topK": 8,
"chunkSize": 1200,
"chunkOverlap": 200,
"maxFileBytes": 50000000,
"ingestConcurrency": 4,
"embeddingBatchSize": 32,
"includeExtensions": [],
"pdfOcrCommand": [],
"pdfOcrTimeoutMs": 120000,
"imageOcrCommand": [],
"imageOcrTimeoutMs": 120000,
"legacyWordCommand": [],
WordTimeoutMs":
}
```
每个字段、默认值及其控制内容：
| 字段 | 默认值 | 用途 |
| --- | --- | --- |
| `rawDir` | `.ragmir/raw` | 本地语料库文件夹，递归索引。主要的文档放置位置。 |
| `sources` | `[]` | 额外的文件、目录和 glob 路径（以及 `!` 排除项）进行索引，从目录解析。参见下| `sources | `.ragmir/sources.txt 旧式单行文件；仍然读取并与 `sources` 合并（如果存在）。 |
| `storageDir` | `.ragmir/storage` | LanceDB 矢量存储位置。 |
| `accessLogPath` | `.ragmir/access.log` | 查询访问日志（仅存储哈希值/元数据）。 |
| `embeddingModelPath` | `.ragmir/models` | Transformers.js 嵌入模型的本地缓存。 |
| `tableName` | `chunks` | LanceDB 表名。 |
| `embeddingProvider` | `local-hash` | `local-hash`（离线词典，不语义）或 `transformers`（语义）。切换需要 `ragmir ingest --rebuild`。 |
| `embeddingModel` | `mixedbread-ai/mxbai-embed-xsmall-v1` | 当 `embeddingProvider` 为 `transformers` 时使用的模型。 |
| `transformersAllowRemoteModels` | `false` | 允许在运行时下载嵌入模型。 |
| `redaction.enabled` | `true` | 在嵌入任何内容之前剥离机密/PII。 |
| `redaction.builtIn` | `true` | 应用内置的机密/PII 模式。 |
| `redaction.patterns` | `[]` | 额外的 `{ name, pattern, flags?, replacement? }` 删减规则。 |
| `accessLog` | `true` | 将查询元数据记录到 `accessLogPath`。 |
| `mcpMaxTopK` | `10` | 任何 MCP 工具可能返回的结果的硬上限。 |
| `topK` | `8` | `search`/`ask` 返回的默认段落数量。 |
| `chunkSize` | `1200` | 每个块的字符数。 |
| `chunkOverlap` | `200` | 块之间的重叠字符（必须小于 `chunkSize`）。 |
| `maxFileBytes` | `50000000` | 跳过大于此的文件。 |
| `ingestConcurrency` | `4` | 摄入期间并行处理的文件。 |
| `embeddingBatchSize` | `32` | 每批次嵌入的块。 `includeExtensions` | ` | 额外视为可索引文本的文件扩展名| `pdfOcr `imageOcrCommand`, `legacyWordCommand`[]` | 选择加入外部提取器（参见下文）。 |
| `pdfOcrTimeoutMs`, `imageOcrTimeoutMs`, `legacyMs` | `120000` | 外部提取器的超时。 |
### 额外源路径（`sources`）
Ragmir 始终索引 `rawDir` 下的所有内容（`.ragmir/raw/`）。要引入位于其他位置的文件 — 比如单体仓库中的 sibling 包、共享文档文件夹、下载的目录 — 直接将它们添加到 `.ragmir/config 中的 `sources` 数组需要单独的文件：json
{
": [
"../packages.md",
"../ "./NOTES.md "!../packages/**/node"
]
}
```
目可以是：
- **文件** 或 **目录** 路径 — 相对路径从项目根目录解析；目录递归索引；
- **glob** 模式 — 任何包含 `*`、`?`、`[` 或 `{` 的条目；
- **排除项** — 以 `!` 开头，过滤 glob 匹配项。
```mermaid
flowchart LR
Raw["rawDir<br/>.ragmir/raw/"] --> Merge["源合并"]
Cfg["sources[]<br/>in config.json"] --> Merge
Legacy["legacy sources.txt<br/>(只读，可选)"] -.-> Merge
Merge --> Discover["文件发现"]
Discover --> Index["LanceDB 索引"]
```
> **旧式 `sources.txt`.** `ragmir sources add` 和 `ragmir sources list` 读取并写入 `.ragmir/config.json` 中的 `sources` 数组 — 这是规范位置。预先存在的 `.ragmir/sources.txt` 仍然被读取（只读）并与配置数组合并，因此现有项目保持不变；不再向其中写入任何内容。新项目从不获取 `sources.txt`。
环境变量覆盖：
- `RAGMIR_RAW_DIR`
- `RAGMIR_STORAGE_DIR`
- `RAGMIR_SOURCES_FILE`
- `RAGMIR_ACCESS_LOG_PATH`
- `RAGMIR_EMBEDDING_PROVIDER`
- `RAGMIR_EMBEDDING_MODEL`
- `RAGMIR_EMBEDDING_MODEL_PATH`
- `RAGMIR_TRANSFORMERS_ALLOW_REMOTE_MODELS`
- `RAGMIR_REDACTION_ENABLED`
- `RAGMIR_RE_BUILT_IN`
- `RAGMIR_ACCESS- `RAGMIR_MCP_MAX_TOP- `RAGM_K`
- `MIR_CHUNK- `RAGM_OVERLAP`
- `RAGMIR_MAX`
- `RIR_INGEST_CON`
- `RAGMIR_EMBEDD_SIZE`
- `RAGMIR_INCLUDE_EXTENSIONS `RAGMIR_PDF_OCR_COMMAND` 数组，例如 `["-pdf-ocr","{input}"]`
- `RAGMIR_PDF_OCR_TIMEOUT_MS`
- `RAGMIR_IMAGE_OCR 作为 JSON 数组，例如 `["ragmir-image-{input}"]`
- `RAGMIROCR_TIMEOUT_MS`
- `RAGMIR_LEGACY_WORD_COMMAND` 作为 JSON 数组，例如 `["rag","{input}"]`
- `RAGMIR_LEGACY_WORD_TIMEOUT_MS`
旧式 `KB_*` 别名仍被接受用于现有的自动化。
### 外部提取器
`pdfOcrCommand` 是选择加入的，仅在正常 PDF 文本提取返回无文本时运行。`imageOcrCommand` 也是选择加入的；只有配置了它，图像文件才被视为受支持。`legacyWordCommand` 是选择加入的；只有配置了它，`.doc` 文件才被视为受支持。外部文本命令从目标项目根目录执行，无需 shell，接收 `RAGMIR_PDF_PATH`、`RAGMIR_IMAGE_PATH` 或 `RAGMIR_LEGACY_WORD_PATH`，用源路径替换 `{input}` 占位符，并且必须将 UTF-8 文本打印到 stdout。
## 命令和 API 参考
Ragmir 提供了两个 CLI：
- `ragmir`：主要的本地 RAG、MCP、技能、安全和音频命令。`kb` 仍然是兼容性的旧别名。
- `ragmir-tts`：`ragmir audio` 使用的独立文本转语音渲染器。
大多数用户从 `ragmir setup`、`ragmir doctor`、`ragmir ingest`、`ragmir search`、`ragmir ask`、`ragmir research` 和 `ragmir security-audit` 开始。
在初始设置期间使用 `ragmir setup --semantic`，或者在稍后使用 `ragmir models pull --enable`，当一次性 Transformers.js 模型下载可接受并且您想要更高质量的语义检索时。切换嵌入提供程序或模型后，运行 `ragmir ingest --rebuild`。
完整命令表：[`docs/cli-reference.md`](./docs/cli-reference.md)。
TypeScript API 镜像用于应用程序和边车的 CLI：
```ts
import { ask, ingest, search } from "@jcode.labs/ragmir"
await ingest({ rebuild: true })
const results = await search("供应商发票状态")
const answer = await ask("哪些文档支持项目时间线？")
```
完整 API 参考：[`docs/api-reference.md`](./docs/api-reference.md)。
## 故障排除和验证
首先使用 `ragmir doctor`。它是通往下一个有用操作的捷径：
```bash
npx ragmir doctor
```
当您希望 Ragmir 自动修复安全设置问题时，请使用 `doctor --fix`：
```bash
npx ragmir doctor --fix
```
空索引、弱搜索、严格安全审计失败和 TTS 设置的常见修复方法位于 [`docs/troubleshooting.md`](./docs/troubleshooting.md)。
对于此存储库中的发布或集成工作，`pnpm validate` 是完整的本地关卡。它涵盖了 Biome、依赖项安全审计、TypeScript、Vitest、构建输出、生产 CLI/MCP 烟雾测试、npm 包元数据、semantic-release 连线和发布工件。
## 依赖项占用
Ragmir 可以在没有模型运行时的情况下运行检索。一些运行时依赖项仍然存在，因为它们拥有核心功能：
| 依赖项 | 它保留的原因 |
| --- | --- |
| `@h/transformers` | 可选的本地语义嵌入和离线 TTS；除非显式启用远程模型加载，否则禁用远程模型加载。 |
| LanceDB | 本地向量存储和最近邻检索。 |
| MCP SDK | 适用于兼容代理的 MCP 服务器。 |
| fast-glob | 安全的文件发现。 |
|, mammoth, read-excel-file, html-to-text, yaml, fflate | PDF、Office、HTML、YAML、OpenDocument 和 EPUB 文件的文档解析。 |
| commander, zod, picocolors | CLI、配置验证和可读的终端输出。 |
直接运行时依赖项扫描不显示分析 SDK 或产品遥测调用。 暂存包使用一个包装器，设置 `ASTRO_TELEMETRY_DISABLED=1` 以禁用开发、检查、预览和构建命令。
删除更多依赖项的可能性仅在于删除功能或用较小的内部实现替换它们。对于选择 `local-hash` 的用户，当前低摩擦路径在运行时是依赖项轻量的，而对于保留更丰富的解析、MCP 支持和可选语义嵌入，则是依赖项丰富的。
## 示例测试工作区
此存储库附带两个综合示例，位于 [`packages/ragmir-core/examples`](./packages/ragmir-core/examples)。两者都使用默认的本地哈希检索模式，因此它们在不下载嵌入或聊天模型的情况下运行，并且都不使用私有文档。
> 测试本地更改：使用存储库自己的构建，而不是 `npx`。在存储库内部，`npx ragmir` 解析为已发布的 npm 包，而不是您的工作副本 — 因此它不会执行您的本地编辑。先使用 `pnpm build` 构建，然后针对本地 `dist/` 构建运行示例。（`dist/` 是 gitignored 构建输出，因此干净的克隆在运行 `pnpm build` 之前没有。）
### CLI 工作区（`sovereign-rag-demo`）
[`sovereign-rag-demo`](./packages/ragmir-core/examples/sovereign-rag-demo) 驱动 **CLI** 以测试摄入、检索、`security-audit` 和自定义文本扩展。
```bash
pnpm build
cd packages/ragmir-core/examples/sovereign-rag-demo
node ../../dist/cli.js security-audit
node ../../dist/cli.js ingest
node ../../dist/cli.js search "离线检索审批"
node ../../dist/cli.js evaluate --golden golden-queries.json
node ../../dist/cli.js evaluate --golden golden-queries.json --fail-under 1
node ../../dist/cli.js audit
```
### 库 API 演示（`library-api-demo`）
[`library-api-demo`](./packages/ragmir-core/examples/library-api-demo) 演练 **库** API 的方式与外部消费者使用 `import` 类似，但 Node 自引用解析 `@jcode.labs/ragmir` 到本地构建，而非 npm。它是开发 Ragmir Core 本身时的快速内部循环：
```bash
pnpm example
```
该命令会构建 Ragmir Core，然后通过公共 APIest -> search -> ask -> audit` 以重用综合语料库。
## 开发和发布
安装并验证 monorepo：
```bash
pnpm install
pnpm validate
```
有用的过滤命令：
```bash
pnpm --filter @jcode.labs/ragmir test
pnpm --filter @jcode.labs/ragmir mcp:pnpm --filter @jcode.labsmir-tts test
pnpm --filtercode.labs/ragmir-app build
pnfilter @jcode.labs/ragmir-landing build
pnpm --filter @jcode.labs/ragmir build
pnpm --filter @jcode.labs/ragmir-tts build
```
所有 `packages/*/dist/` 目录（`ragmir-core`-tts`、`ragmir-app`mir-landing`）都是 gitignored 构建输出 — 它们不被提交到 Git。在发布包之前，先在 TypeScript 源代码更改后构建并在本地验证：
```bash
pnpm build
pnpm validate
```
CI 在烟雾测试之前重新构建 `dist/`，发布管道在 `pnpm pack`/`publish` 之前再次重新构建，因此发布的 tarball 始终带有新鲜的输出。干净的克隆在 `pnpm build` 运行之前没有 `dist/`。
根包是私有的，仅用于协调工作区任务。npm 发布由受保护的 `Release GitHub Actions 工作流在 `main` 上处理。semantic-release 从 Conventional Commits 中派生准备两个包 tarball，先发布 `@jabs/ragmir-tts`，然后发布code.labs/ragmir`。
从源代码构建：
```git clone git@:jcode-works/jcode-ragmir jcode-ragmir
pnpm install
pnpm build
```
在另一个存储库中使用本地副本```bash
pnpm add -D file:../jcode-ragmir/packages/ragmir-core
```
创建本地 npm tarball：
```bash
pnpm build
pnpm --dir packages/ragmir-core pack
```
## 许可证
MIT Jean-Baptiste Thery.
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器