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 initinit 将主动提出安装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_scope | read_only, read_write | read_only |
git_depth | 任何正整数 | 1 |
default_branch | 分支机构名称或 none | （未设置） |
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许可证
麻省理工学院