内容
<div align="center">
# 📖 洛雷德克斯
**适用于跨产品、项目和仓库的代码代理团队协作的通用控制系统。**
[](https://github.com/ahmedtawfeeq1/loredex/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/loredex)
[](LICENSE)
[](package.json)
[](https://github.com/ahmedtawfeeq1/loredex-obsidian)
*lore* — 代理学习的一切 · *dex* — 自动记录索引
</div>
---
洛雷德克斯是一个共享内存和控制系统，用于跨产品、项目和仓库的代码代理团队协作。它在单个连接的知识层中捕获研究、发现、验证、决策和移交，代理可以通过MCP读取，团队可以通过[Obsidian](https://obsidian.md)仪表板管理。结果非常简单：任何代理都可以打开任何仓库，继承完整的工作上下文，并继续从上下文中工作，而不是靠猜测。
<a id="quick-actions"></a>
## 🚀 快速操作
| 我想要... | 去这里 |
|---|---|
| 快速了解问题和解决方案 | [可视化概览](#visual-overview) |
| 立即组织现有项目 | [快速入门](#quickstart) |
| 安装Claude Code插件 | [为Claude Code安装](#install-for-claude-code) |
| 在Obsidian中使用洛雷德克斯 | [洛雷德克斯-Obsidian](https://github.com/ahmedtawfeeq1/loredex-obsidian) |
| 查看完整公共信息图表故事 | [文档/信息图表.md](docs/INFOGRAPHICS.md) |
| 学习完整的工作流程和命令 | [文档/用户指南.md](docs/USER-GUIDE.md) |
<a id="table-of-contents"></a>
## 📑 目录
- [快速操作](#quick-actions)
- [可视化概览](#visual-overview)
- [快速入门](#quickstart)
- [工作原理](#how-it-works)
- [生态系统](#the-ecosystem)
- [功能](#features)
- [为Claude Code安装](#install-for-claude-code)
- [适用于任何代理](#works-with-any-agent)
- [命令](#commands)
- [策划](#curate)
- [一个产品，多个仓库](#one-product-many-repos)
- [代理读取仓库：MCP](#agents-read-the-vault-mcp)
- [浏览它：Obsidian](#browse-it-obsidian)
- [跨设备同步](#sync-across-devices)
- [安全模型](#security-model)
- [常见问题](#faq)
- [文档](#documentation)
- [路线图](#roadmap)
- [贡献](#contributing)
<a id="visual-overview"></a>
## 🖼️ 可视化概览
**问题：** 代码代理生产力高，但知识分散在仓库、会话和随机markdown文件中。
**解决方案：** 洛雷德克斯为每个代理提供一个共享的文件系统、共享内存和共享检索层。
**结果：** 与其使用不连接的笔记，您可以获得一个具有索引、移交和可重用上下文的导航知识库。
**最快的开始方式：** 初始化一次，采用现有的markdown，并在Obsidian中打开知识库。
想要完整的叙述，包括设计原则、安全、策划、MCP和多代理使用？ 打开[文档/信息图表.md](docs/INFOGRAPHICS.md)。
<a id="quickstart"></a>
## ⚡ 快速入门
在60秒内组织现有项目：
```bash
cd your-project
npx loredex adopt --dry-run # 查看归档计划 — 不会写入任何内容
npx loredex adopt # 执行
```
在Obsidian中打开`~/Loredex`。您分散的代理输出现在是一个连接的知识图。
```text
之前 — 分散在仓库中 之后 — 一个连接的知识库
───────────────────────────────── ────────────────────────────────────────────────
docs/GAP-ANALYSIS.md projects/my-app/gap-analysis/2026-07-03-gap-analysis.md
docs/current-system/00-OBJECTIVE.md → projects/my-app/current-system/2026-07-03-objective.md
research-dump-v2.md projects/my-app/engine/2026-07-01-research-dump-v2.md
notes/llm-pricing.md research/llm-tools/2026-06-28-llm-pricing.md
_index/my-app.md ← 内容地图，自动构建
_index/Dashboard.base ← 原生Obsidian数据库
_index/Home.md ← 知识库范围索引
```
原始文件保持不变（标记为`loredex: routed`以便不会重新采用）。传递`--move`以重定位它们。每个命令都支持`--dry-run`。
> [!TIP]
> **阅读索引，而不是文件夹树。** 固定`_index/<project>.md` — 主题按最新活动顺序排列（最新优先，日期在每个标题中）— 或打开`_index/Dashboard.base`以获取原生、可排序的数据库。Obsidian按字母顺序排列文件夹，而索引是前门。
<a id="how-it-works"></a>
## 🧠 工作原理
```text
代理写入.md 洛雷德克斯路由 您的知识库
┌─────────────────┐ ┌──────────────────────┐ ┌─────────────────────────────┐
│ Claude Code │ │ 1. frontmatter? │ │ projects/<project>/<topic>/ │
│ Codex │ → │ → 确定性 │ → │ YYYY-MM-DD-slug.md │
│ Cursor │ │ 2. 否则LLM分类 │ │ _index/ ← 自动MOCs + 基础 │
│ 任意 │ │ 3. 否则启发式 │ │ + 维基链接，git提交 │
└─────────────────┘ └──────────────────────┘ └─────────────────────────────┘
```
1. **确定性优先** — 具有`project` + `topic` frontmatter的文件立即路由，无需LLM参与。
2. **LLM备用** — 未标记的文件由您已经拥有的任意代理CLI（`claude`或`codex`）分类。无需管理API密钥。
3. **启发式最后** — 没有LLM？文件名和路径规则仍然可以合理地归档所有内容（`--no-llm`强制执行此操作）。
**设计保证：** 永远不会删除任何内容 · 幂等（运行两次，无变化） · 纯markdown，零锁定。
<a id="the-ecosystem"></a>
## 🧩 生态系统
一个核心，四个外壳 — 相同的知识库，相同的规则 everywhere：
| 组件 | 是什么 | 在哪里 |
|---|---|---|
| **CLI** (`npx loredex`) | 所有命令：adopt, route, curate, handoff, sync, MCP, … | 此仓库 |
| **Claude Code插件** | 停止钩子文件查找每个回合；SessionStart钩子注入开放移交；11个斜杠命令技能 | 此仓库 — [`plugin/`](plugin/) |
| **MCP服务器** | 代理搜索、读取和存储知识库中间任务（stdio或HTTP） | 此仓库 — `loredex mcp` |
| **Obsidian插件** | 原生Bases仪表板、开放移交徽章、知识库同步、应用内MCP服务器与`active_note` | **[ahmedtawfeeq1/loredex-obsidian](https://github.com/ahmedtawfeeq1/loredex-obsidian)** |
Obsidian插件将此包作为库嵌入（`import { createLoredexMcpServer } from 'loredex'`）— 路由、索引和安全的实现之一，在每个表面上重新托管。
<a id="features"></a>
## ✨ 功能
<details>
<summary><b>归档和结构</b> — 从转储到知识库</summary>
- 确定性 → LLM → 启发式分类级联； `--no-llm` 在每个级别
- 默认复制采用，具有`loredex: routed` 戳记； `--move` 选择加入； 碰撞安全名称
- 知识库布局：`projects/<project>/<topic>/YYYY-MM-DD-slug.md` + `research/` 用于无项目笔记
- **链接出处**：路由副本携带 `source_path` + 可移植的 `source_project`/`source_rel`; 相对链接重写 — 批量兄弟姐妹变成维基链接，代码文件变成编辑器深链接 (`cursor://file/...:42`, 任意方案通过 `editor` 配置)，二进制文件变成 `file://`
- 幽灵维基链接清理：`[[chat.py]]` → 内联代码 — 没有幻影图节点
- `loredex reset <project>` — 守护重建路径（取消原始文件的标记，删除仅知识库副本）
</details>
<details>
<summary><b>索引和仪表板</b> — 始终最新，从不手动编辑</summary>
- `_index/<project>.md` MOC — 主题按最新活动顺序排列，最新的在前，每个标题中的日期； 过时笔记标记
- `_index/Dashboard.base` — **原生Obsidian数据库** （Bases，Obsidian ≥ 1.9）：最新笔记、开放移交、按项目划分的卡片、过期列表 — 可排序和筛选，无需插件
- `_index/Home.md` — 知识库范围索引
- 所有生成的文件都会批量重新生成，并且在保持本地的git合并驱动程序下是冲突免费的
</details>
<details>
<summary><b>理解</b> — 策略、简介、卫生</summary>
- `curate --objective "..."` — LLM编写**开始这里简介**：叙事、阅读顺序、后续行动； 分层摘要缩放超过大型知识库 (`--max-detailed`)
- 过时/过时标记、重复标记（仅报告）、语义`## 相关`链接
- **漂移检测** — 确定性，通过每个笔记的源文件的git历史记录； 跨机器工作，通过可移植的出处
- 孤儿检测 — 没有链接到的笔记
- `curate --product` — 跨项目仪表板 + LLM产品简介：阅读顺序跨团队，报告仅风险和重复工作； `--refresh-stale` 仅重新策划过时的项目
</details>
<details>
<summary><b>团队合作</b> — 一个产品，多个仓库</summary>
- 一个知识库用于一个产品，通过私有git远程共享； 每个仓库都注册到它
- `handoff --to <project>` — 受众感知的简介和阅读顺序放入接收项目，`status: open`，自动推送
- SessionStart钩子拉取知识库并将开放的移交注入代理的上下文 — 零命令
- `sync` — 提交，拉取 --rebase（自动stash），推送； 优雅的离线； 索引在拉取后重新生成
</details>
<details>
<summary><b>代理访问</b> — MCP</summary>
- `loredex mcp` — stdio服务器通过`init`连接到`.mcp.json`
- 工具：`vault_search`（排名：简介 > 原始笔记，过时汇聚），`vault_note`，`handoffs_open`，`handoff_consume`，`product_state`，`vault_store`（路由器中介写入）
- 相同服务器通过Streamable HTTP在Obsidian内 [loredex-obsidian](https://github.com/ahmedtawfeeq1/loredex-obsidian) — 添加`active_note`
</details>
<a id="install-for-claude-code"></a>
## 🔌 为Claude Code安装
```text
/plugin marketplace add ahmedtawfeeq1/loredex
/plugin install loredex@loredex
```
插件添加：
- **停止钩子** — 每次回合后，新的前置matter文件会自动路由到知识库
- **SessionStart钩子** — 拉取共享知识库并将开放的移交注入上下文
- **11个技能** — `/loredex`，`/loredex-init`，`/loredex-adopt`，`/loredex-route`，`/loredex-curate`，`/loredex-product`，`/loredex-handoff`，`/loredex-handoffs`，`/loredex-sync`，`/loredex-mcp`，`/loredex-reset`，`/loredex-status`
然后每个项目一次：`npx loredex init`。忘记归档。
<a id="works-with-any-agent"></a>
## 🤝 适用于任何代理
洛雷德克斯**基于文件，不基于代理API**。 `loredex init`将约定写入`AGENTS.md`（Codex、Cursor、Copilot等读取），`CLAUDE.md`和`.cursor/rules/`。任何编写带有此frontmatter的markdown的工具都参与：
```yaml
---
project: my-app
topic: auth-redesign
type: research | finding | analysis | snapshot | note
date: 2026-07-03
source: codex
tags: []
---
```
> [!IMPORTANT]
> 代理永远不应该自己编写`loredex: routed` — 该戳记是路由器的签名，在归档后添加。 预先标记的文件作为已归档的文件跳过。
Claude Code的钩子在任何IDE托管的终端中触发（VS Code, Cursor, Antigravity）。原生IDE侧边栏代理没有钩子 — 对于那些，运行`loredex watch`（路由更改）或手动运行`loredex route`。完整的协议是一页： [docs/VAULT-SPEC.md](docs/VAULT-SPEC.md)。使用BMAD或Spec Kit？粘贴内片段： [docs/INTEGRATIONS.md](docs/INTEGRATIONS.md)。
<a id="commands"></a>
## 📋 命令
| 命令 | 它做什么 |
|---|---|
| `loredex init` | 创建/注册知识库，连接项目：约定文件 `.mcp.json`，编辑器。 `--sync git`， `--editor <scheme>` |
| `loredex adopt [path]` | 分类和归档项目的现有markdown。 `--dry-run`， `--move`， `-y`， `--no-llm` |
| `loredex route` | 处理知识库收件箱 + 项目中的新发现。 `--strict` = 仅限frontmatter |
| `loredex curate [project]` | 目标的Start Here简介； 过时/重复/孤儿/漂移标记； 语义链接。 `--objective`， `--since`， `--topic`， --max-detailed`, `--dry-run` |
| `loredex curate --product` | 跨项目产品视图：仪表板，团队流程，报告仅风险/重复。 `--objective`， `--refresh-stale` |
| `loredex handoff --to <project>` | 将完成的工作交给另一个团队：可消费的简介和阅读顺序，自动同步。 `--objective`， `--since`， `--dry-run` |
| `loredex handoffs` | 列出该项目的开放移交（先拉取远程）。 `--consume <name>` 标记完成 |
| `loredex mcp` | 通过stdio的MCP服务器 — 由 `init`连接到`.mcp.json` |
| `loredex sync` | 提交本地知识库更改，拉取队友的笔记，推送您的笔记 |
| `loredex reset <project>` | 删除项目的知识库副本并取消原始文件的标记，以便进行干净的重新采用。 `--dry-run`， `-y` |
| `loredex watch` | 守护进程：自动路由文件更改（轮询 — 无文件描述符限制） |
| `loredex status` | 知识库统计信息 |
| `loredex doctor` | 检查配置，知识库，编辑器和分类器可用性 |
每个命令的完整演练和引导测试检查清单： [docs/USER-GUIDE.md](docs/USER-GUIDE.md).
<a id="curate"></a>
## 🧭 策略
归档解决了存储；`curate`解决了“从哪里开始？”：
```bash
npx -y loredex@latest curate my-app --objective "draft the v2 spec" --since 2026-07-01 --dry-run
```
代理人阅读范围内的笔记并在知识库中写入**开始这里简介**：这项工作是什么，目标的5-10个笔记按顺序排列 *，以及建议的后续行动。它还标记过时的文档（`status: stale`，`superseded_by`），发现重复的覆盖范围，检测 **漂移** （源文件自归档后更改 — 确定性，通过git），查找孤儿，并重写`## Related`部分以使用语义链接。作用范围 `--since`/`--topic` — 每个范围简介都是一个持久的会话移交。
与安全规则相同：先进行干燥运行，绝不删除，合并建议是标记 — 由您决定。
<a id="one-product-many-repos"></a>
## 🔀 一个产品，多个仓库
在前端仓库完成工作，打开移动应用仓库，代理已经知道做出了什么决定。移交传递火炬；钩子做归档；MCP服务器在任务中回答问题：
完整演练： [USER-GUIDE — 多项目产品](docs/USER-GUIDE.md#multi-project-products-handoffs-between-teams).
<a id="agents-read-the-vault-mcp"></a>
## 🤖 代理读取知识库：MCP
`loredex init` 将MCP条目连接到项目的`.mcp.json` — 代理在任务中获得六个工具，而不是要求您重新解释：
- `vault_search` — 排名术语搜索（简介 > 原始笔记，过期文件）
- `vault_note` — 读取一个笔记（仅限知识库路径，无符号链接保护）
- `handoffs_open` / `handoff_consume` — 团队的交接棒，从会话内部
- `product_state` — 每个项目的最新鲜度和开放移交一览
- `vault_store` — 通过路由器写入笔记（无原始文件写入）
每个响应都有长度限制，控制字符剥离，并以 *数据而非指令* 格式化。
<a id="browse-it-obsidian"></a>
## 🔮 浏览它：Obsidian
知识库开箱即用支持Obsidian — 图形视图、反向链接、属性。两个级别：
1. **无需插件**：打开 `_index/Dashboard.base` — 一个原生Bases数据库（Obsidian ≥ 1.9），具有最新笔记、开放移交、按项目划分和过期视图。由loredex重新生成，实时由Obsidian查询。
2. **[loredex-obsidian](https://github.com/ahmedtawfeeq1/loredex-obsidian)** 插件添加：单击仪表板（功能区 + 命令）、状态栏中的 **开放移交徽章** 、知识库同步、应用内MCP服务器和 **活动笔记** — 代理获得上述所有功能以及 `active_note`，您正在查看的笔记。 通过 [BRAT](https://obsidian.md/plugins?id=obsidian42-brat) 安装 → `ahmedtawfeeq1/loredex-obsidian`。
<a id="sync-across-devices"></a>
## ☁️ 跨设备同步
知识库是一个纯粹的markdown文件夹 — 每个同步工具都已经有效：
| 选项 | 成本 | 备注 |
|---|---|---|
| **git** （推荐） | 免费 | `loredex init --sync git`，添加私有GitHub远程仓库。永久版本控制 |
| Obsidian Sync | 付费 | 端到端加密，最佳移动体验 |
| iCloud / Dropbox / Syncthing | 免费 | 将知识库放在同步文件夹中 |
无需loredex服务器，无需帐户，无需锁定： **您的文件，任何代理，永久可用**。
<a id="security-model"></a>
## 🔒 安全模型
知识库内容被视为 **不受信任的输入** 始终：
- 流入代理上下文的任何内容（钩子，MCP响应）都会被展平，控制字符剥离，长度限制，并以 *数据而非指令* 格式化 — 提示注入测试
- 笔记路径通过 `realpath` 解析，必须位于知识库内（符号链接逃逸被拒绝）
- frontmatter中的 `source_path` 从不进入shell — 仅使用数组参数 `execFile`，绝对路径受保护
- 绝不删除任何内容； `reset` 仅删除知识库拥有的副本
<a id="faq"></a>
## ❓ 常见问题
**它会删除或重写我的文件吗？** 绝不会删除。`adopt` 默认复制并标记原始文件；`--move` 是可选的。名称冲突会添加后缀。
**我需要 API 密钥吗？** 不需要。分类 shell 调用您已有的 `claude` 或 `codex` 命令行界面。两者都不需要安装 → 启发式。
**我需要 Obsidian 吗？** 不需要 — 仓库是纯 Markdown，可以与任何查看器（Logseq、VS Code、`cat`）一起使用。Obsidian 只是提供最佳的免费图谱/反向链接体验 — 而且使用它，`_index/Dashboard.base` 为您提供原生数据库 UI，以及 [loredex-obsidian](https://github.com/ahmedtawfeeq1/loredex-obsidian) 插件，提供完整的应用程序体验。
**如果它错误地归档了某个文件怎么办？** 这是一个普通文件夹 — 移动文件即可。 `_index` MOC 将在下一次路由时重新生成。
**为什么我的最新主题在 Obsidian 的文件树中不在顶部？** Obsidian 按字母顺序排序文件夹 — 没有设置可以更改。使用 `_index/<project>.md`（主题按时间顺序，最新的排在前面）或 Dashboard 基页。
<a id="documentation"></a>
## 📚 文档
| 文档 | 内容 |
|---|---|
| [信息图表](docs/INFOGRAPHICS.md) | 产品故事的完整视觉导览，包含所有 13 张公告-ready PNG 图片 |
| [用户指南](docs/USER-GUIDE.md) | 每个命令，按生命周期组织，加上引导式测试驱动和多仓库团队导览 |
| [仓库规范](docs/VAULT-SPEC.md) | 单页协议：布局、frontmatter 合同、链接策略、来源 |
| [架构](docs/ARCHITECTURE.md) | 设计在一页上 — 核心模块、四层 shell、决策 |
| [集成](docs/INTEGRATIONS.md) | BMAD + Spec Kit 粘贴片段 |
| [loredex-obsidian](https://github.com/ahmedtawfeeq1/loredex-obsidian) | Obsidian 插件 — 安装、设置、网络披露 |
<a id="roadmap"></a>
## 🗺️ 路线图
- [x] `curate` — 目标驱动的简报、过期/漂移/孤立检测、语义链接
- [x] 团队仓库 — 交接、共享 git 远程、会话启动上下文拉取
- [x] MCP 服务器 — 代理读取仓库作为长期记忆
- [x] Obsidian 插件 — [loredex-obsidian](https://github.com/ahmedtawfeeq1/loredex-obsidian)：基础仪表盘、交接徽章、应用内 MCP
- [x] 原生基础仪表盘 (`_index/Dashboard.base`)
- [ ] Obsidian 社区目录列表
- [ ] 仓库上的语义搜索
- [ ] 光标原生钩子适配器
<a id="contributing"></a>
## 🛠️ 贡献
欢迎 PR — 从 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) 开始（整个设计都放在一页上）。标记为 [`good first issue`](https://github.com/ahmedtawfeeq1/loredex/labels/good%20first%20issue) 的问题是良好的起点。
```bash
git clone https://github.com/ahmedtawfeeq1/loredex && cd loredex
npm install && npm test
```
MIT © [Ahmed Tawfeeq](https://github.com/ahmedtawfeeq1) — [genudo.ai](https://genudo.ai) 的 AI 负责人 & 创始人
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器