内容
<p align="center">
<h1 align="center">洛勒姆</h1>
<p align="center">人工智能编码代理的工程知识基础设施。</p>
<p align="center">
<a href="./LICENSE"><img alt="许可证" src="https://img.shields.io/badge/license-Apache--2.0-blue"></a>
<a href="https://github.com/lorelum/lorelum"><img alt="状态" src="https://img.shields.io/badge/status-早期开发-orange"></a>
<a href="./CONTRIBUTING.md"><img alt="贡献" src="https://img.shields.io/badge/contributions-欢迎-brightgreen"></a>
</p>
<p align="center">
<a href="./README.md">English</a> ·
<a href="./README.zh-CN.md">简体中文</a>
</p>
</p>
---
> ⚠️ **洛勒姆处于早期开发阶段。** 目前还没有 `npm install` —— 我们正在开放构建中。您可以先关注仓库以跟踪进展，或者跳转到 [CONTRIBUTING.md](./CONTRIBUTING.md) / [讨论](https://github.com/lorelum/lorelum/discussions) 参与贡献。
## 问题
您可能遇到过以下情况：
- 您的团队编写了一个 `.cursorrules` / `AGENTS.md` / Skills 文件。它在会话的前 10 分钟内有效，但到了第 20 条消息时，代理已经忘记了第一条消息中的规则。
- 每个开发者的 AI 助手输出的架构、命名、错误处理、API 分层都不同，尽管“标准”已经写在某个地方。
- 入门新的 AI 工具感觉像是从头开始：重写约定、重新解释堆栈、重新说明反模式。
您并不孤单。这就是 AI 编码中的 **知识层差距**。
## 为什么会发生这种情况
```
┌─────────────────────────────────┐
│ 一开始就转储完整的规则集 │
│ (10k 个令牌的约定) │
└──────────────┬──────────────────┘
▼
消息 1 ── 消息 5 ── 消息 10 ── 消息 20 ── 消息 30
[规则回忆] [部分回忆] [注意力衰退] [遗忘]
```
传统方法（“将所有规则粘贴到上下文中”）与两个 **物理限制** 作斗争：长会话中的注意力衰退和上下文窗口容量。即使是 1M 令牌窗口，在长会话后也不能可靠地回忆早期指令。简单地增加上下文并不能解决问题。
## 洛勒姆如何解决这个问题
洛勒姆将团队的工程经验转化为 **离散的、可检索的、基于触发条件的单元，称为实践** —— 并在需要时将它们注入 AI 上下文，而不是一次性注入。
```
┌─────────────┐ 查询 ┌────────────────────┐ 精确 ┌──────────────┐
│ AI 代理 │ ─────────▶ │ 洛勒姆 │ ──────────▶ │ 3 个相关 │
│ （Cursor / │ │ 检索引擎 │ │ 实践 │
│ Claude / │ ◀───────── │ （嵌入 + 元数据 │ ◀────────── │ + 反模式 │
│ Codex） │ 注入 │ + 图谱） │ └──────────────┘
```
**按需获取，而不是一次性获取所有信息。** 当代理开始实现身份验证时，洛勒姆会为其提供身份验证实践 —— 而不是路由、测试和部署实践。
### 实践的示例
```markdown
---
id: react.api.layered-design
stage: api-layer
tech_stack: [react, typescript]
applies_when: 在 React SPA 中构建 API 层
---
# 分层 API 设计
[具体指导：HTTP 客户端、基础 API、模块、DTO 边界。]
## 避免的反模式
- api.direct-axios-in-component （在组件中调用 axios）
- api.local-storage-in-api-class （在 API 类中持久化令牌）
- api.dto-used-as-ui-model （重用 DTO 作为 UI 状态）
```
一个 **知识包** 捆绑了许多实践 + 决策图（`decisions.yaml`）+ 模板 + 反模式，适用于特定的技术栈或团队标准。
## 5 分钟导览
*(CLI 处于前期 alpha 阶段 —— 以下命令展示了预期的 UX。)*
```bash
# 安装社区包（本地模式，离线工作）
lore install react-fullstack
# 查询：“哪些实践适用于我的当前任务？”
lore query "带有权限守护、表单和测试的设置页面"
# 根据项目上下文获取决策建议
lore decide "React SPA、中型客户端状态、RBAC 路由、组件测试"
# 检查代码是否违反任何实践
lore check src/features/auth/LoginPage.tsx
# 将成功的修复转化为团队的可重用实践
lore learn "HTTP 客户端中的单次刷新令牌"
```
或者，通过 MCP 将其与您的 AI 工具连接起来 —— 洛勒姆提供了一个 MCP 服务器，任何与 MCP 兼容的代理（Cursor、Claude Code、Codex、Windsurf 等）都可以调用。
## 它与现有方案的区别
| | `.cursorrules` / `AGENTS.md` | 技能 / 斜杠命令 | **洛勒姆** |
|---|---|---|---|
| **交付** | 静态，一次性 | 手动触发 | **按需检索** |
| **随会话衰退** | 是 | 否（一次性） | 否（每次查询都是新鲜的） |
| **扩展到数百条规则** | ❌ | 麻烦 | ✅ 构建用于此目的 |
| **捕获团队决策** | 否 | 否 | ✅ `decisions.yaml` |
| **工具无关** | 工具特定 | 工具特定 | ✅ MCP / CLI / 技能 |
| **反模式检查** | 否 | 否 | ✅ `lore check` |
洛勒姆并不是一个更好的 `.cursorrules`。它是 **检索 + 决策层**，位于您使用的任何 AI 工具之后。
## 架构（简要介绍）
```
┌──────────────────────────────────────────────────────────┐
│ AI 工具层 （Cursor / Claude Code / Codex / Windsurf） │
└────────────┬─────────────────────────────────┬───────────┘
│ CLI │ MCP
▼ ▼
┌──────────────────────────────────────────────────────────┐
│ 洛勒姆引擎 │
│ 检索（嵌入 + 元数据 + 图谱）· decisions.yaml │
└────────────┬─────────────────────────────────────────────┘
│
┌─────────┴─────────┐
▼ ▼
本地包 端点（团队 / SaaS / 自托管）
（离线） （实时，多用户）
```
两种模式共享相同的命令：
- **本地模式（默认）：** `lore install` 一个公共包，离线查询。无需运维。类似 npm。
- **端点模式：** 将 CLI 指向团队/SaaS/自托管端点，实现实时、多用户知识。
## 路线图
我们正在开放构建，分为几个里程碑：
- **P0–P2** — 核心引擎：实践格式、检索（嵌入 + 元数据）、`lore query` / `get` / `decide` / `check`。仅限本地模式。
- **P3–P4** — 第一个公共包（`react-fullstack`）、MCP 服务器、`lore install` / `search`、公共注册表 MVP。
- **P5** — 端点内核（AGPL，可自托管）、团队包、决策图评估器。
- **P6** — 企业治理（SSO、审计、敏感信息扫描）。
在 [讨论](https://github.com/lorelum/lorelum/discussions) 中查看当前正在进行的工作。
## 项目状态
🟡 **早期开发中。** 没有稳定的发布版本，也没有发布的 CLI。设计正在最终确定。这是塑造方向的最佳时机 —— 欢迎加入 [讨论](https://github.com/lorelum/lorelum/discussions)。
## 贡献
我们欢迎贡献者。洛勒姆是 **开放核心**（参见 [许可证架构](#license)）—— 核心引擎、格式和社区包永远开源。
- 📖 阅读 [**CONTRIBUTING.md**](./CONTRIBUTING.md) 了解开发工作流（规范驱动 + 问题驱动）
- 🤖 如果您正在使用 AI 编码助手，请阅读 [**AGENTS.md**](./AGENTS.md）
- 💬 来 [讨论](https://github.com/lorelum/lorelum/discussions) 打个招呼或提出想法
- 🐛 发现了错误？[打开一个问题](https://github.com/lorelum/lorelum/issues/new/choose)
## 许可证
洛勒姆是 **开放核心**：
| 组件 | 许可证 |
|---|---|
| 核心引擎（CLI、本地检索、MCP、格式规范） | **Apache 2.0** |
| 社区知识包 | **CC-BY-4.0** |
| 端点服务器内核（可自托管） | **AGPL-3.0** *(独立仓库，后续发布)* |
| SaaS 平台和企业治理 | **专有** *(独立仓库，后续发布)* |
边界：**如果它允许开发人员在个人笔记本电脑上运行完整的离线工作流，那么它就是开源的。** 付费层购买的是托管运维、协作和合规性 —— 而不是功能限制。
参见 [LICENSE](./LICENSE) 了解适用于此仓库的 Apache 2.0 条款。
## 致谢
洛勒姆建立在更广泛的 AI 编码和开发者工具社区的肩膀上。名称结合了 **Lore** （通过实践传承的知识）和 **Lum** （光，如 lumen）—— 将团队的工程经验转化为 AI 代理可以工作的光。
MCP 市场