English | 简体中文
一个命令，把任意 Git 仓库的源码和知识链接到当前项目中，让 AI 即时查阅。
添加仓库 — 一条命令将远程或本地 Git 仓库链接到项目中，自动生成代码统计和架构知识
探索知识 — AI 子代理自动阅读源码，将探索结果沉淀为 Markdown 知识文件，一次探索、跨项目复用
知识复用 — 探索结果沉淀为全局知识文件，新项目添加同一仓库后直接命中已有知识，无需重复探索
- 零延迟查阅 — 源码在本地磁盘，AI 直接 Grep/Glob/Read，无网络请求
- 知识可复用 — 探索结果沉淀为 Markdown 知识文件，一次探索，所有项目受益
- 不污染上下文 — 双子代理架构：探索在子代理中完成，主 Agent 只加载知识文件
- 多 AI 助手兼容 — 支持 Claude Code、ZCode、MiMo Code、OpenCode、Codex（自动注入子代理 + Skill），兼容 Cursor、Copilot、Windsurf 等
- 纯本地 — 不依赖任何在线 API 或付费服务，不受网络波动影响
- 本地仓库引用 — 复用你之前在其他项目中实现过的代码
# 从源码构建
git clone https://github.com/cicbyte/reference.git
cd reference
go build -o reference .# 或从 Release 下载预编译二进制（Windows/Linux/macOS）# https://github.com/cicbyte/reference/releases要求 Go 1.24+。
reference # 首次运行：交互式选择编程助手（支持多选） 欢迎使用 reference！
请选择你的编程助手（可多选，用逗号分隔）：
[1] Claude Code
[2] Codex
[3] OpenCode
[4] ZCode
[5] MiMo Code
[6] 无（仅使用仓库引用管理功能）
请输入选项: 1,2
已配置: Claude Code, Codex
已链接 0 个仓库知识。
CI 集成可非交互式初始化：
reference init --agent claude # 单个助手
reference init --agent claude,codex # 多个助手（逗号分隔）# 远程仓库（支持 owner/repo 简写）
reference repo add gin-gonic/gin
reference repo add go-git/go-git
# 本地仓库
reference repo add --local ~/projects/my-lib
# 强制更新已有缓存
reference repo add gin-gonic/gin --update添加后，.reference/ 下通过 Junction 链接动态加载源码和知识：
<project>/
├── .reference/
│ ├── repos/ # 仓库源码（→ 全局缓存）
│ │ ├── gin/
│ │ └── go-git/
│ ├── wiki/ # 知识库 Junction（→ wiki/ 或 localwiki/）
│ │ ├── gin/
│ │ └── go-git/
│ ├── reference.map.jsonl # AI 读取的仓库导航（JSONL 格式）
│ └── reference.settings.json # 项目配置（agents 数组）
不复制、不占空间，全局缓存多项目共享，一处添加，处处可用。
添加仓库后直接对话，AI 自动查阅本地知识。
你：go-git 的 clone 内部流程是怎样的
AI：让我先检查已有知识... 已写入
克隆流程.md主题知识文件，后续可跨项目复用。
解决一个核心矛盾——主 Agent 需要阅读大量源码，但不能让代码污染对话上下文。
flowchart LR
User[你] --> Main[主 Agent<br/>对话 + 编码]
Main -->|查询/参考| Explorer[reference-explorer<br/>探索特定问题]
Main -->|深度分析| Analyzer[reference-analyzer<br/>全面分析架构]
Explorer -->|搜索源码| Source[仓库源码]
Analyzer -->|搜索源码| Source
Explorer -->|写入| Topic["<主题>.md<br/>主题知识文件"]
Analyzer -->|覆盖写入| Ref["reference.md<br/>架构总览"]
Topic -->|轻量读取| Main
Ref -->|轻量读取| Main
Source -->|按需补读关键文件| Main
- reference-explorer — 探索特定问题（"X 是怎么实现的"），输出主题知识文件。先检查已有知识，命中则直接复用，未命中才深入源码，探索结果写入知识目录供后续跨项目复用
- reference-analyzer — 全面分析架构，输出
reference.md（全局只需执行一次）。覆盖分层架构、核心数据结构、关键流程（含 Mermaid 图）、设计决策等 - 主 Agent 先加载知识文件快速理解全貌，仅在需要时按需读取少量关键源码
每个仓库的知识目录下包含以下文件：
<wiki>/<仓库名>/
├── reference.md # 架构总览（analyzer 生成，全局一次）
└── <主题>.md # 主题知识文件（explorer 按需生成）
代码统计通过 reference repo scc <name> 命令实时获取，不生成静态文件。
所有文件为纯 Markdown + Mermaid，一次生成，跨项目复用。
| 平台 | agents 目录 | skills 目录 | agent 格式 |
|---|---|---|---|
| Claude Code | .claude/agents/ | .claude/skills/ | Markdown |
| Codex | .codex/agents/ | .codex/skills/ | TOML |
| OpenCode | .opencode/agents/ | .opencode/skills/ | Markdown |
| ZCode | .zcode/cli/agents/ | .zcode/skills/ | Markdown |
| MiMo Code | .mimocode/agents/ | .mimocode/skills/ | Markdown |
| Cursor / Copilot / Windsurf 等 | — | — | 引导 AI 查看 .reference/ 目录 |
| 无 AI | — | — | 仓库管理、代码统计、知识库管理 |
初始化时按所选助手自动注入 reference-explorer + reference-analyzer 子代理和 reference Skill 到对应目录。支持同时选择多个助手。
reference-vscode-plugin 提供图形化管理界面：
- 侧栏树形视图 — 浏览引用仓库目录结构和知识文件
- 可视化操作 — 添加/更新/移除仓库，无需终端命令
- 状态栏集成 — 实时显示引用仓库数量
安装：
code --install-extension reference-vscode-plugin-0.1.0.vsixgui/ 目录提供完整的 Wails v2 + Vue 3 桌面客户端，支持多项目管理、代码浏览、知识库查看、全局统计、可视化诊断等全部功能，无需终端命令。
cd gui
wails build # 构建桌面应用
wails dev # 开发模式reference repo add <url># 添加远程仓库
reference repo add --local <path># 添加本地仓库
reference repo remove <name># 移除引用
reference repo remove --all # 移除全部引用
reference repo list # 列出所有引用
reference repo update [name] # 更新远程仓库
reference repo scc [name] [-n 15] # 代码统计（语言分布、复杂度、Top 文件）所有输出类命令均支持全局 --format / -f 标志，可使用 -f json 或 -f jsonl 输出结构化数据。
reference wiki # 查看 wiki 状态
reference wiki --local # 查看本地知识库状态
reference wiki commit # 提交知识库更改
reference wiki sync # 同步知识库（pull + commit + push）
reference wiki remote [url] # 查看/设置远程仓库
reference wiki trash # 查看被删除的知识文件
reference wiki restore <path># 从 Git 历史恢复文件远程仓库和本地仓库的知识文件分别存储在独立的 Git 仓库中（wiki/ 和 localwiki/），通过 --local 标志切换操作目标。
reference global list # 列出所有项目及其引用关系
reference global stats # 查看全局统计信息
reference global gc # 清理过期 DB 记录（项目目录已不存在的残留）
reference global gc --cache # 额外清理无引用的缓存目录
reference global gc --dry-run # 预览可清理项，不实际删除reference doctor # 诊断并修复引用健康状态
reference proxy set<url|port># 设置代理
reference proxy info # 查看代理
reference proxy clear # 清除代理详细用法见 docs/ 目录。
配置文件位于 ~/.cicbyte/apps/reference/config/config.yaml：
# 自定义存储路径（可选，修改后自动迁移数据库记录）repos_path: /path/to/reposwiki_path: /path/to/wikinetwork:
proxy: http://127.0.0.1:7890git_proxy: socks5://127.0.0.1:1080