Blink Query

blink查询

LLMs的键入wiki——磁盘上的markdown，库中的resolution。

blinkquery是LLM代理的知识解析库。Markdown文件保存在磁盘上，您可以在那里阅读和编辑它们；该库在笔记旁边的SQLite文件中添加了键入记录、标题加权BM25搜索、确定性路径解析和MCP服务器。没有云，没有嵌入，没有守护进程。

特性

• 5种类型的记录 — SUMMARY, META, SOURCE, ALIAS, COLLECTION --每个都包含代理的消费指令（读取摘要/解析JSON/获取源代码/遵循重定向/浏览子项）
• 命名空间 --斜线分隔的路径按主题对记录进行分组（例如。， wiki/concepts, decisions/auth, people/arpit)；每条记录在以下位置都有稳定的路径 namespace/slug-of-title
• 标题权重BM25超过FTS5 --标题匹配在正文摘要中排名10倍，每种类型的排名偏移有助于推广规范页面
• Hub与叶子默认分类器 --自动升级 index / README / Home 中心目录中的文件 SUMMARY，无需对每个语料库进行调优
• 路径分辨率 --按命名空间/slug进行确定性O（1）查找 NXDOMAIN / STALE / ALIAS_LOOP 状态
• 配备11个工具的MCP服务器 --访问克劳德桌面、克劳德代码、光标、Codex
• 查询DSL --佩吉解析： wiki where type = "SUMMARY" and tags contains "auth" limit 10
• 多源摄入 --markdown目录、PostgreSQL行、GitHub Issues、git repos、web URL
• 区域 --具有默认TTL和所需标记策略的顶级命名空间
• \[\[wikilink\]\]提取 --自动创建 ALIAS 摄入记录

______________________________________________________________________

快速开始

npm install -g blink-query
blink init                 # auto-detect agent (Claude Desktop, Code, Cursor, Codex) and write MCP config
blink wiki init my-wiki    # scaffold + ingest a wiki directory
blink doctor               # verify install

或者将其用作图书馆：

npm install blink-query

import { Blink } from 'blink-query';

const blink = new Blink({ dbPath: './wiki.db' });
await blink.ingestDirectory('./my-wiki');
const results = blink.search('how to configure auth');

逐步演练：

• 在项目中使用blink查询 --安装、摄取、查询、常见模式、自定义衍生工具、故障排除
• 连接到您的代理 --克劳德桌面/代码/光标/每个代理的Codex设置、验证、故障排除

______________________________________________________________________

基准

一个命令。三个公开的降价语料库。一个库配置。

npm run benchmark

在3个语料库中，blink查询比grep快25-91倍，比ripgrep快21-31倍。 速度差距随着语料库的大小而扩大——眨眼比例呈次线性，grep比例呈线性。

在14k文件MDN语料库上， grep每次查询平均返回1212个未排序的文件 （因为“Promise”等常用术语出现在1314个文件中，“DOM”出现在9363个文件中）。blink排名前五。代理读取的文件数减少了约242倍以找到答案。

3个语料库的准确性： P@3=79%平均值（黑曜石为88%，石英为79%，MDN为72%）.中每个查询的可验证正则表达式预言符 benchmark/bench.ts.方法、注意事项和参考号 benchmark/README.md.

bench脚本自动将语料库克隆到 benchmark/corpora/ （gitignored，首次运行约270 MB），在具有相同查询集的同一文件集上运行blink+grep+ripgrep，并打印统一的比较结果。不 --mode 旗帜。无需对每个语料库进行调优。无预设。

______________________________________________________________________

这是什么，不是什么

blink查询是一个库，而不是一个框架。它是在普通markdown之上添加的：

• 你的文件会留在原地。 Markdown在 sources/, entity/, topics/, log//.你可以grep它们，在任何编辑器中打开它们，将它们提交到git，它们的任何部分都是不透明的。
• 该库添加了索引、类型和查询接口。 将blink查询视为相同文件之上的确定性更快路径。
• 没有嵌入。 仅限BM25/FTS5。如果你想进行语义检索，请在旁边运行一个向量存储，并选择对查询更好的答案。
• 没有云。 磁盘上的SQLite文件。MCP服务器通过stdio。完全在您的机器上运行。
• 没有魔法。 摄入是基于规则的推导，你可以忽略。分类基于您控制的文件名+frontmatter。查询DSL是您可以阅读的Peggy语法。

如果你想要原始的markdown+grep，文件仍然可以这样工作。如果你想要带索引的键入记录，请安装库。

______________________________________________________________________

五种记录类型

类型为a *消费指令* -它告诉代理如何使用记录，而不是记录的内容。内容具有领域语义。

摘要 --直接阅读摘要，你就得到了你需要的东西。 用于处理维基页面、实体描述、主题概述。代理人不需要取其他任何东西。

元 --结构化数据（JSON内容字段）。 用于配置、日志条目、会话状态、实体属性。代理解析 content JSON格式。

源 --这里总结一下，如果你需要深度，可以获取源代码。 用于引用外部文档：论文、URL、git文件、API规范。摘要足以决定是否提取。

别名 --按照重定向到目标记录。 用于交联。 [[wikilinks]] 在您的markdown中，摄取时自动提取到ALIAS记录。

收藏 --浏览孩子们，选择相关内容。 用于命名空间索引。解析没有直接记录的命名空间路径时自动生成。

______________________________________________________________________

在您的代理中安装

简单的路径：

npx blink-query init

此自动检测克劳德桌面、克劳德代码、光标和Codex。它处理macOS/Linux上的nvm+绝对节点路径gotcha，包装 npx 在 cmd /c 在Windows上，它会合并到现有的MCP配置中——它永远不会覆盖其他服务器（如果JSON无法解析它，它会备份到 .bak 并发出警告）。

跑 blink doctor 之后进行验证。

手动配置

克劳德桌面版 — ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json （Windows）：

{
  "mcpServers": {
    "blink": {
      "command": "npx",
      "args": ["-y", "blink-query", "mcp"],
      "env": { "BLINK_DB_PATH": "~/.blink/blink.db" }
    }
  }
}

克劳德代码:

claude mcp add-json blink --scope user '{"type":"stdio","command":"npx","args":["-y","blink-query","mcp"]}'

光标 — ~/.cursor/mcp.json （与克劳德桌面形状相同，按键 mcpServers).

法典 — ~/.codex/config.toml:

[mcp_servers.blink]
command = "npx"
args = ["-y", "blink-query", "mcp"]

[mcp_servers.blink.env]
BLINK_DB_PATH = "~/.blink/blink.db"

nvm用户：如果你的经纪人找不到 npx，跑 blink init --absolute-node 将节点二进制文件的绝对路径写入。避免了“代理不提供shell rc”的问题。

运行时功能

一旦连接，代理就可以解析、搜索、， 保存新记录移动或删除现有的， 创建新区域 具有所需的标签策略，以及 摄入新鲜的降价 --所有这些都是在运行时通过MCP工具调用完成的。无需重新启动、重新部署、重新摄取。知识库在代理自己的手中增长。

MCP服务器公开了11个工具，按其功能分组：

阅读

写

区域

掉落 BLINK_WIKI.md 将其粘贴到项目根目录中（或粘贴到代理的系统提示符中），以便代理知道如何使用wiki模式。

______________________________________________________________________

命令行界面

# Wiki workflows
blink wiki init my-wiki          # scaffold + ingest
blink wiki ingest ./my-wiki      # re-ingest after changes
blink wiki lint                  # find STALE, NXDOMAIN, broken aliases

# Core operations
blink resolve wiki/mcp-protocol  # deterministic O(1) lookup
blink search "tool call protocol"
blink query 'wiki where type = "SUMMARY" limit 10'
blink list wiki --limit 20

# Agent setup
blink init                       # write MCP config for detected agent
blink doctor                     # post-install diagnostic

# Data management
blink ingest ./docs --prefix wiki
blink move wiki/old wiki/new
blink delete wiki/outdated
blink zones

所有命令支持 --json 用于机器可读输出和 --db 用于自定义数据库路径。

______________________________________________________________________

库API

import { Blink, extractiveSummarize } from 'blink-query';

const blink = new Blink({ dbPath: './wiki.db' });

// Ingest a directory of markdown files
await blink.ingestDirectory('./my-wiki', {
  summarize: extractiveSummarize(500),
  namespacePrefix: 'wiki',
});

// Resolve — deterministic O(1) path lookup
const response = blink.resolve('wiki/mcp-protocol');
if (response.status === 'OK') console.log(response.record.summary);

// Search — title-weighted BM25 over typed records
const results = blink.search('tool call protocol');

// Query DSL
const summaries = blink.query(
  'wiki where type = "SUMMARY" order by hit_count desc limit 10',
);

// Save a new record (idempotent on path — upserts by namespace + slug-of-title)
blink.save({
  namespace: 'wiki/concepts',
  title: 'OAuth Flow',
  type: 'SUMMARY',
  summary: 'OAuth 2.1 flow for first-party apps — PKCE, refresh tokens, session scoping.',
  tags: ['auth'],
});

// Create a zone with a required-tag policy
blink.createZone({
  namespace: 'decisions',
  description: 'Architecture decision records',
  defaultTtl: 31536000,    // 1 year, inherited by saves into this zone
  requiredTags: ['adr'],   // save() throws if missing
});

blink.close();

所有CRUD操作都是同步的(resolve, get, save, delete, move, search, list, query, createZone, zones).只有摄入是异步的。

______________________________________________________________________

您的代理的架构文档

BLINK_WIKI.md 是LLM代理阅读以了解如何将blink查询用作wiki的文档。它涵盖了名称空间约定、所有五种记录类型及其示例、摄取/查询/日志/lint工作流和四个工作示例会话。

将其放入项目根目录或粘贴到代理的系统提示符中。

______________________________________________________________________

示例

examples/llm-wiki/ 是一个完整的端到端示例：一个30文件的MCP生态系统语料库被摄取、查询并与grep进行基准测试。

______________________________________________________________________

范围

blink查询句柄：

• Markdown和纯文本（主要）
• PostgreSQL表（通过 loadFromPostgres)
• Web URL（通过 loadFromURL)
• Git仓库（通过 loadFromGit)
• GitHub问题（通过 loadFromGitHubIssues)

确实如此 *不* 做：

• 矢量嵌入 --仅限BM25/FTS5。如果你需要语义相似性，可以在上面叠加一个RAG系统。
• 同步或复制 --单个SQLite文件，本地。通过git同步markdown源代码并重新摄取。
• 托管存储 --没有云，就没有账户。您的数据存在于 .db 您拥有的文件。
• 代理编排 --blink查询解析知识。它不计划任务或协调代理。

______________________________________________________________________

发展

npm install
npm run build       # builds parser + library + CLI
npm test            # 524 tests
npm run benchmark   # universal benchmark on 3 public corpora

______________________________________________________________________

状态

v2.0.0版本 --在npm上发布为 blink-query.MIT许可证。

npm install blink-query        # library
npm install -g blink-query     # CLI + blink init

欢迎发布问题和PR。