Knowerage

Knowerage — AI 分析覆盖率管理

链接： GitHub · Glama MCP 列表 · npm @mtimma/knowerage

快速开始

要求： Node.js 18 或更高版本 — npx 必须位于你的 PATH 中（它随 npm 一同提供，而 npm 已包含在 Node 中）。

MCP 服务配置

在 MCP 主机要求的位置注册 Knowerage 服务定义（例如，某些客户端使用 .cursor/mcp.json 或 .vscode/mcp.json；其他客户端使用环境变量或 UI——请遵循主机的文档）。使用相同的服务条目格式：

{
  "mcpServers": {
    "knowerage": {
      "command": "npx",
      "args": ["@mtimma/knowerage"],
      "env": {
        "KNOWERAGE_WORKSPACE_ROOT": "${workspaceFolder}",
        "KNOWERAGE_AUTO_FULL_RECONCILE": "true"
      }
    }
  }
}

如果主机不会展开该变量，请将 ${workspaceFolder} 替换为项目根目录。

KNOWERAGE_AUTO_FULL_RECONCILE 是可选的：当其未设置、为空或不是有效值时，文件监视器默认关闭。将其设置为 1、true、yes 或 on（会先去除首尾空格，且不区分大小写）即可启用。启用后，服务会监视 knowerage/，并在短暂的防抖等待后，于文件系统发生变化时运行 knowerage_reconcile_all。这不等同于每次调用 MCP 工具后都运行完整协调——它只会响应 knowerage/ 下的文件变化。监视器会忽略对 registry.json 的写入，以避免保存操作导致循环。

如何使用 Knowerage

配置好 MCP 服务后，你可以用日常语言与助手交谈。无需记住工具名称。

分析或记录代码

指出你关心的文件、类或行为。例如：

• 使用 Knowerage 分析 main.java 中的逻辑算法工作流。
• 分析 ETL 服务中的数据实体协调和版本控制逻辑。

助手会在 knowerage/analysis/ 下创建或更新 Markdown，并在 knowerage/registry.json 中记录覆盖情况（参见下文的工作原理）。

覆盖情况与缺口（同一项目、后续聊天或其他 Agent）

如果目录树中已经有分析内容，你可以询问：

• 我们的分析覆盖了多少比例的代码？
• 这个代码库中哪些部分尚未分析？

Knowerage 会根据注册表和覆盖率辅助工具（例如总览、逐文件状态和过期列表）回答，而不是含糊地浏览整个代码库。

其他方式

通过 npm 安装

npx @mtimma/knowerage

或从源代码构建

cargo build --release
./target/release/knowerage-mcp

工作原理

1. AI Agent 创建分析 .md 文件，并使用 YAML frontmatter 声明源文件和覆盖的行范围
2. 注册表（knowerage/registry.json）使用 SHA-256 哈希跟踪分析记录的新鲜度
3. MCP 工具提供创建、协调、查询和导出操作
4. Agent 说“分析 X” → 自动运行完整工作流（创建 → 协调 → 记录）

注册表文件格式（knowerage/registry.json）

磁盘上的格式是一个 JSON 对象，其键为分析路径（字符串）。每个值都是一条记录（参见 contracts/contracts.md）。examples/registry.sample.json 中提供了包含两条记录的完整示例。

flowchart TB
  subgraph file["knowerage/registry.json"]
    O["Top-level JSON object"]
    O --> K["Each key: analysis markdown path, e.g. knowerage/analysis/.../topic.md"]
    K --> V["Value: one RegistryRecord"]
  end

  subgraph rec["RegistryRecord fields"]
    ap["analysis_path · source_path"]
    cr["covered_ranges: [[start,end], ...]"]
    h["analysis_hash · source_hash (sha256:… )"]
    t["record_created_at · record_updated_at (ISO 8601)"]
    st["status: fresh | stale_doc | stale_src | missing_src | dangling_doc"]
  end

  V --> rec

分析 .md 文件的 frontmatter 在 contracts 文档中单独说明（元数据架构），不包含在 registry.json 中。

MCP 工具

工具	用途
knowerage_create_or_update_doc	创建/更新分析文档
knowerage_parse_doc_metadata	解析并验证 frontmatter
knowerage_reconcile_record	对一条分析记录进行校准
knowerage_reconcile_all	完整重新扫描/重建
knowerage_get_file_status	已分析与缺失的范围
knowerage_list_stale	列出过时/有问题的记录
knowerage_list_registry	完整的注册表快照（与 registry.json 格式相同，键已排序）
knowerage_get_tree	树形/分组覆盖情况
registry_export_report	导出快照（JSON/YAML/TXT/HTML）
knowerage_generate_bundle	分块导出所选分析（toc*.md、combined*.md、manifest.json）

项目结构

knowerage/                  # Created per-project
├── analysis/              # Analysis markdown files
│   └── **/*.md
└── registry.json          # Coverage registry

src/                       # Rust MCP server
├── main.rs
├── lib.rs
├── types.rs
├── parser.rs
├── registry.rs
├── mcp.rs
├── security.rs
└── export.rs

文档

• 用户入门指南 — 设置、配置、典型用法
• INSTRUCTIONS.md — MCP Agent 指令
• Rust 实践
• JS 实践
• 契约 — 架构与 API 契约（注册表 + frontmatter）
• 注册表示例 JSON — registry.json 内容示例

安全

• 所有路径均针对工作区根目录进行验证
• 拒绝路径遍历（..）
• 注册表采用原子写入（崩溃安全）
• 分析文件或报告中不包含机密信息
• 基于 SHA-256 哈希值判断新鲜度（git pull 后仍有效）

许可证

MIT — 版权所有 Martins Timma。

本项目的部分内容由生成式 AI 编码助手编写或改进。设计、安全敏感行为和发布均经过人工审核。