refstore (Jedim Em O)

refstore

LLM编码代理的参考文档管理员。

管理参考资料的中央存储库——文档、示例代码、配置模板、样式指南——并将相关子集同步到每个项目的 .references/ 目录。然后，代理（或人类）可以读取 .references/ 用于接地的、特定于项目的上下文。

为什么

LLM编码代理可以更好地使用参考资料：API文档、编码约定、示例实现。但是在许多项目中管理这些是乏味的。refstore解决了这个问题：

• 中央商店 --只需添加一次引用（本地文件、目录或git repos），即可在任何地方重用。
• 每个项目清单 --每个项目都声明了它需要哪些引用 refstore.toml.
• 选择性同步 --包含/排除globs以仅提取相关内容。
• 捆绑包 --将相关的引用组合在一起（例如“ruststack”），并在一个步骤中将它们添加到项目中。
• 远程注册表 --通过git在机器和团队之间共享引用。将社区或公司注册作为子模块。
• 注册表编写 --创建并发布自己的注册表供他人使用。
• 版本固定 --pin引用特定的注册表标记或可重复构建的提交。
• MCP服务器 --通过模型上下文协议公开对代理的引用，具有可配置的读/写范围。

快速启动

cargo install --git https://github.com/JedimEmO/refstore
cd my-project
refstore init

init 将主动提出安装MCP服务器(.mcp.json)自动。注册后，Claude Code（和其他MCP客户端）将使用它——您不需要学习完整的CLI。

安装

cargo install --git https://github.com/JedimEmO/refstore

或者从当地收银台：

cargo install --path .

需要Rust 1.85+和git。

用法

# Add a reference to the local store
refstore store add rust-guidelines ~/docs/rust-guidelines --tag rust --description "Team Rust conventions"
refstore store add api-examples https://github.com/org/api-examples.git --ref main --tag api

# Initialize refstore in a project
cd my-project
refstore init

# Add references to the project and sync
refstore add rust-guidelines --sync
refstore add api-examples --include "**/*.rs" --exclude "**/tests/*"
refstore sync

# Discover and search
refstore list
refstore search "authentication"
refstore info rust-guidelines
refstore status

在同步之后， my-project/.references/ 包含：

.references/
  rust-guidelines/
    ...
  api-examples/
    src/
      lib.rs
      ...

CLI参考

发现

refstore list                        # List all references across registries
  --tag                         #   Filter by tag
  --kind    #   Filter by kind

refstore search               # Search content across references
  --ref                        #   Limit to a specific reference

refstore info                  # Show details (works for references and bundles)
refstore versions              # Show version history for a reference

当地书店

refstore store add     # Add a reference (file, dir, or git URL)
  --description "..."                #   Human-readable description
  --tag                         #   Tags for filtering (repeatable)
  --ref 
          #   Git ref to checkout
  --subpath 
                   #   Subdirectory within a git repo

refstore store update [name]         # Re-fetch content from source (all if omitted)
refstore store remove          # Remove a reference
  --force                            #   Skip confirmation prompt

refstore store push            # Copy a reference to another registry
  --to 
                        #   Path to the target registry

捆绑包

将引用分组在一起，以便在项目之间重用：

refstore bundle create  --ref  --ref 
  --description "..."                #   Human-readable description
  --tag                         #   Tags for filtering (repeatable)

refstore bundle list                 # List all bundles
  --tag                         #   Filter by tag

refstore bundle info           # Show bundle details
refstore bundle update         # Modify a bundle
  --add-ref                     #   Add references (repeatable)
  --remove-ref                  #   Remove references (repeatable)
  --description "..."                #   Update description

refstore bundle remove         # Remove a bundle
  --force                            #   Skip confirmation prompt

将捆绑包添加到项目中，其所有引用都会同步：

refstore add --bundle rust-stack
refstore sync

远程注册表

跨机器和团队共享参考。远程注册表是作为子模块添加到本地注册表的git repos：

refstore registry list               # List all registries (local + remote)
refstore registry add     # Add a remote registry
refstore registry update [name]      # Pull latest from remote (all if omitted)
refstore registry remove       # Remove a remote registry
  --force                            #   Skip confirmation prompt

来自远程注册表的引用出现在 refstore list 并且可以像本地引用一样添加到项目中。当名称冲突时，本地引用优先。

注册表编写

创建并发布自己的注册表供他人使用：

# Create a new registry
refstore registry init /path/to/my-registry

# Push references from your local store into it
refstore store push rust-guidelines --to /path/to/my-registry
refstore store push api-examples --to /path/to/my-registry

# Or add content directly using --data-dir
refstore --data-dir /path/to/my-registry store add react-docs ./react-docs/

# Create bundles in it
refstore --data-dir /path/to/my-registry bundle create frontend-stack --ref react-docs

# Publish: push the registry to a git remote
cd /path/to/my-registry
git remote add origin git@github.com:team/registry.git
git push -u origin main

其他人可以使用注册表：

refstore registry add team git@github.com:team/registry.git
refstore list                        # team's references are now visible
refstore add react-docs --sync       # sync from the team registry

版本控制

本地注册表是一个git repo。每 store add, store update，以及 store remove 创建一个commit。您可以标记状态并将项目固定到特定版本：

refstore store tag             # Tag the current registry state
  -m "..."                           #   Optional tag message (annotated tag)

refstore store tags                  # List all tags

refstore versions              # Show version history for a reference

在将引用添加到项目时，将其固定到特定版本：

refstore add api-examples --pin v1.0
refstore sync                        # Syncs content from the v1.0 tag, not HEAD

项目工作流程

refstore init                        # Initialize refstore.toml in current directory
  --path                        #   Target directory
  --commit-references                #   Don't gitignore .references/
  --install-mcp                      #   Install MCP server without prompting
  --no-mcp                           #   Skip MCP server installation

refstore add                   # Add a reference to the project manifest
  --bundle                           #   Add a bundle instead of a single reference
  --include                    #   Only sync matching files (repeatable)
  --exclude                    #   Skip matching files (repeatable)
  --pin                         #   Pin to a registry tag or commit
  --path                   #   Custom path within .references/
  --sync                             #   Sync content immediately after adding

refstore remove                # Remove from manifest
  --bundle                           #   Remove a bundle
  --purge                            #   Also delete synced content

refstore sync [name]                 # Sync .references/ from manifest
  --force                            #   Re-sync even if up to date

refstore status                      # Show sync status of all references

配置

refstore config show                 # Show all settings
refstore config get             # Get a value
refstore config set      # Set a value

MCP服务器

refstore install-mcp                 # Register in .mcp.json (auto-detects binary path)
  --name                       #   Override server name (default: refstore)
  --path                        #   Target directory (default: cwd)

refstore mcp                         # Start MCP server (stdio transport)

要在项目中设置MCP服务器，只需运行 refstore install-mcp --它创建或更新 .mcp.json 使用正确的二进制路径和参数。适用于Claude Code、Cursor和其他MCP客户端。

显示工具： list_references, get_reference, read_reference_file, list_reference_files, search_references, list_bundles, get_bundle，以及 add_to_project （要求 read_write 范围）。

项目清单

refstore.toml 在项目根目录中：

version = 1
gitignore_references = true

[references.rust-guidelines]

[references.api-examples]
include = ["**/*.rs"]
exclude = ["**/tests/*"]
version = "v1.0"

bundles = ["rust-stack"]

数据布局

中央存储库位于 ~/.local/share/refstore/ （或 $XDG_DATA_HOME/refstore/，可与 --data-dir).这是一个git repo——所有突变都是自动提交的：

~/.local/share/refstore/          # git repo
  .git/
  .gitmodules                     # tracks remote registries
  .gitignore                      # excludes config.toml
  index.toml                      # reference & bundle definitions
  config.toml                     # local settings (gitignored)
  content/                        # cached reference content
    rust-guidelines/
    api-examples/
  registries/                     # remote registries (git submodules)
    community/                    # submodule → https://github.com/.../refs.git
      index.toml
      content/
        some-ref/

发展

cargo build
cargo test          # 88 integration tests

许可证

麻省理工学院