repovine

Name: repovine
Author: legann

本地服务

github.com/legann开发工具012 周前更新

代码仓库

关于 repovine

repovine 为当前代码检出构建本地仓库结构与契约图，并通过 MCP 向编码 Agent 提供范围明确的上下文，适用于需要分析依赖、运行流、配置和版本化注释的开发者与 Agent。

主要功能

01检出目录本地仓库图
02跨单元契约与依赖分析
03运行流和配置查询
04带新鲜度检查的版本化注释
05用于图导航的 MCP 工具

适用场景

01追踪请求在服务间的流转
02查找 API 变更影响的使用方
03记录仓库不变量与运维风险

MCP 相关

通过 MCP 工具提供结构化的仓库图与注释查询，包括导航、运行流追踪、依赖分析和维护操作。MCP 服务针对当前检出目录运行。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "legann-repovine": {
      "command": "npx",
      "args": [
        "-y",
        "repovine"
      ]
    }
  }
}

启动命令npx -y repovine

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmrepovine0.1.1stdio

工具

收录的工具列表 · 更新于 2 周前

参数	类型	必填	说明
limit	integer	否	最多返回的条目数。默认值取决于工具，通常为 10-20。
match	enum	否	令牌匹配策略。auto（默认）：先 AND，再有界 OR——OR 命中会将 strategy.relaxedFrom:"and" 设定为 "and"，并省略 emptyDiagnostic；仅弱令牌的 OR 噪声可能会设置 weakTokenOnlySuppressed 和 emptyDiagnostic。and：候选令牌必须包含所有令牌，单独的部分令牌命中会导致 totalResults:0，并出现 emptyDiagnostic strict_and_no_single_node。语义候选会在所有匹配模式下加入，因此启用 semantic_search_embeddings 时，match:"and" 也会返回仅包含部分令牌的节点，且不会在其旁显示 emptyDiagnostic——请查看 topResults[].matchedTokenCount 和 semanticRank。or：合并每个令牌的候选结果，并限制数量（弱令牌如 package/route/handler 可能产生噪声）。默认值为 auto。auto \| and \| or
query	string	是	任务关键词、功能名称、符号、路由、包、配置名称或其他搜索文本。
types	array	否	可选的结果类型筛选条件。
offset	integer	否	分页偏移量。默认值为 0。
include	array	否	已接受但会忽略：无论是否提供，响应都相同。trace_flow 通过自身的 include 枚举选择响应部分。
perTokenLimit	integer	否	最终排序前，每个查询词最多考虑的 OR 候选数。默认值随 limit 增大，最高为 100。
responseFormat	enum	否	响应格式覆盖项：concise = 紧凑输出，debug = 完整封装。concise \| debug
contextSessionId	string	否	来自测试框架的上下文质量会话 ID；每次调用都要传入，以便对返回的上下文评分。

详细介绍

repovine

为编码 Agent 汇集并传递仓库上下文。

仓库知识层

与仓库无关的核心。 repovine 将各种受支持语言、框架和基础设施格式中的仓库结构标准化为一个可查询的模型。

按设计划定契约边界。 图谱通过共享的代码、模板和运行时契约连接仓库单元。这些边界支持仓库级导航、依赖影响分析、运行时流转和配置。

版本化知识，所有权明确。 受版本控制的注释会将意图、不变量、风险和运维知识附加到图谱节点。Agent 和开发者负责撰写；repovine 会根据仓库状态检查其时效性和结构一致性。

这些层共同支持由意图驱动、经上下文编译、由契约验证的开发。任务意图指导 MCP 上下文组装，并根据仓库状态检查可观测声明。

按设计与检出目录关联。 实时图谱和索引根据每个检出目录的工作树构建，并在内存中运行。配置和撰写的知识通过 Git 传递。无需数据库。

基准测试。 在从公共软件仓库中选取的正确性和克制性任务中，90% 的 Repovine 运行通过了针对具体案例的 diff 门槛，而基线运行的通过率为 10.6%。查看结果。

快速开始

在现有仓库中开始：

npx repovine setup claude # or codex, cursor, all

setup 会将所选客户端连接到 repovine，添加 repovine 技能、钩子和指令，并构建仓库图谱。

图谱模型

repovine 根据仓库状态确定性地推导出跨单元契约图谱。源代码和基础设施插件会将特定技术栈的结构转换为相同的词汇体系，包括包、模块、导出符号、模板、运行时资源及其关系，因此在所有受支持的技术栈中，导航、依赖影响分析、运行时流转和配置都能保持一致。了解设计原理。

工作原理

引擎和 MCP 提供基础工作流。交互式客户端会直接使用它。对于显式的协议运行，Delivery Protocol 会围绕同一工作流添加结构化的分配 → 结果 → 合规契约。

客户端

在 Claude Code、Codex 或 Cursor 等客户端中，Agent 会直接使用 repovine MCP，同时开发者保持在流程中。

graph LR
  SRC["sources"] --> S1["Stage 1: gather facts"]
  S1 --> S2["Stage 2: build graph"]
  S2 --> ANN["versioned annotations on graph nodes"]
  A["agents and developers"] --> ANN
  S2 --> S3["Stage 3: build search index"]
  ANN --> S3
  S3 --> MCP["MCP tools"]
  ANN --> MCP
  MCP -->|"bounded context"| C["Cursor, Claude Code, or Codex"]

阶段	输入	输出
阶段 1：收集事实	源	导出项、导入项、环境变量名称、路由、基础设施
阶段 2：构建图谱	事实	包 → 模块 → 符号；基础设施／模板／领域边
注释	图谱 + Agent／开发者撰写内容	版本化的意图、不变量、风险、副作用和运维约束
阶段 3：构建搜索索引	图谱 + 注释	词元索引；可选的嵌入向量，用于辅助模糊搜索
MCP	图谱 + 注释 + 索引	范围受限的图谱和注释查询结果

交付协议

交付协议定义了 assignment → 结构化结果 → 合规报告这一契约。Core 负责维护架构、投影和验证器，以便将协议落实到可观测的仓库状态中。

Agent 在工作过程中使用 MCP 获取仓库上下文。repovine CLI 会验证 assignment 和结果，并生成合规报告。

graph LR
  IN["assignment"] --> AV["assignment validation"]
  AV --> A["agent"]
  A <-->|"repository context during the run"| MCP["repovine MCP"]
  A --> R["structured result"]
  AV -->|"validated assignment"| V["repovine compliance validation"]
  R --> V
  S["observable repository state + recorded context"] --> V
  V --> OUT["compliance report"]

repovine 会验证架构一致性、assignment 关联，以及可根据图、注释、已记录的 MCP 上下文和可选的修订差异重新计算的声明。合规报告涵盖协议一致性和仓库依据；行为正确性和是否已准备好合并不属于协议范围。

可运行的 LangGraph harness 演示将该协议应用于端到端的 Agent 工作流。其编排拓扑、沙箱、重试、工作树隔离和提供方行为，均为演示特有的实现选择。请参阅交付协议集成指南。

MCP 工具

每个工具都会返回范围明确的结构化响应。

查询工具，以及适用于大型仓库的典型问题：

分组	示例问题	工具
导航	身份验证在哪里？计费包中包含什么？	`search_context`、`map_context`、`inspect_node`
运行时	入口点有哪些？订单如何流经各项服务？	`get_entrypoints`、`trace_flow`
契约与配置	API 变更会影响哪些使用方？工作进程会读取哪些环境变量？	`analyze_dependencies`、`get_config_surface`
架构	是否存在边界违规或巨型模块？	`analyze_architecture`

维护工具用于维护图和注释：

分组	用途	工具
记忆	哪些节点已添加注释或已过时？	`get_annotation_status`、`write_annotation`、`merge_annotations`、`validate_annotations`、`get_annotation_merge_status`
同步	重建并检查图	`refresh_context`、`get_build_status`、`get_context_session_quality`
领域	调整领域配置	`suggest_domains_config`
忽略项	忽略已审查的建议项	`decline_advisory`（kind：`domains-config` \| `carrier-link-gaps`）

设置与 CLI

setup 会将以下 repovine 集成添加到工作区，同时保留现有配置和项目专属专家：

集成	内容
MCP 服务	repovine MCP 工具
技能	`repovine-workflow`、`repovine-annotations`、`repovine-refresh`、`repovine-review`、`repovine-status`
子 Agent	`repovine-repo-explorer`、`repovine-annotation-writer`、`repovine-architecture-auditor`、`repovine-code-reviewer`
钩子	编辑前边界提醒、编辑后图过时提醒、会话启动时的“MCP 优先”提醒
说明文件	`AGENTS.md`（Cursor 使用 `.cursor/rules`）

命令	目标
`npx repovine`	在 IDE/CLI 客户端之外运行 stdio MCP 服务
`npx repovine setup cursor`（或 `claude`/`codex`/`all`）	添加上述集成，然后构建图
`npx repovine build`	构建图
`npx repovine status`	图 / 配置 / 注释状态
`npx repovine doctor`	诊断工作区集成
`npx repovine clear`	删除由 repovine 管理的工作区文件
`npx repovine --version` · `--help`	版本 / 帮助
`npx repovine delivery --help`	harness/CI 交付协议命令：描述符、清单、运行概要、验证和合规
`npx repovine agents --help`	harness/CI 实用工具：用于仓库角色、确定性方向引导和上下文会话质量

v1 仅支持 STDIO 这一种 MCP 传输方式。对于远程、devcontainer、WSL、VM 或 devbox 场景，请在相应环境中启动 repovine 子进程，使其在正在分析的检出目录中运行。

支持的技术栈

领域	支持情况
语言	一等支持： TypeScript（通过 TS 工具链支持 JS/JSX，需要 `tsconfig.json`）；部分支持 Python（后端路由 + 服务端渲染模板）
框架	React、Next.js、Nuxt、SvelteKit、Angular、NestJS、无服务器单体仓库；Vue/Svelte 单文件组件（仅脚本块）
IaC	部分支持，覆盖范围持续扩展： SAM/CloudFormation、Terraform、Kubernetes、Helm、Dockerfile、docker-compose、Vercel

IaC 解析器会将基础设施文件转换为运行时资源节点，并建立指向其背后代码和镜像的链接。它们涵盖部分资源和关系，而非完整的格式架构。覆盖范围仍在积极开发中，扩展现有提取器也是贡献方向之一。设计详情：DESIGN.md。

需要 Node.js 22+，并且至少有一个可索引的根目录：tsconfig.json、pyproject.toml/setup.py（需要 python3），或 IaC 文件。包含受支持 IaC 文件的仓库可在没有源代码项目的情况下建立索引；图中会包含基础设施模块和运行时资源，但不包含代码模块。

仓库文件

文件 / 目录	Git	作用
`repovine.config.json`	提交	主配置：图构建和 MCP 输出
`repovine.domains.json`	提交	仓库图的逻辑组织
`repovine.annots.json`	提交	语义标注记忆
`.repovine/`	忽略	本地引擎缓存和工作区状态

默认配置适用于大多数 TypeScript 仓库。配置参考：docs/workspace-files.md。

状态

预览版（0.1.0），目前即可使用，欢迎贡献。图架构和 @repovine/plugin-sdk 仍在变化。

贡献

repovine 的插件架构通过 @repovine/plugin-sdk 提供两个用于扩展语言和基础设施覆盖范围的公共生产者接口：

插件	新增内容
语言源代码生产者	一种语言：源文件 → 模块、导入、导出、语义提示
IaC 解析器	一种基础设施格式：文件 → 运行时资源节点和链接

内置和第三方生产者共用同一套公共插件契约；核心会验证其输出，并负责图标识和本体。请参阅插件指南以及可运行的 Go 源代码插件、IaC 插件和其他示例。

了解更多

DESIGN.md：系统边界、图契约、信任模型和限制
CONTRIBUTING.md：开发环境设置、质量门禁
文档：指南、参考资料和 TODO 应用演练
平台支持：各界面的操作系统支持级别、前置条件和晋级规则
examples：可运行的插件和 Delivery Protocol 测试框架演示

许可证

MIT。请参阅 LICENSE。

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

repovine

关于 repovine

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

repovine

仓库知识层

快速开始

图谱模型

工作原理

客户端

交付协议

MCP 工具

设置与 CLI

支持的技术栈

仓库文件

状态

贡献

了解更多

许可证

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？