内容
# Lodestar
**将任何 Markdown 仓库变为可导航、可查询和安全的 AI 代理。**
[](https://github.com/dbareagimeno/lodestar/actions/workflows/ci.yml)
[](rust-toolchain.toml)
[](#licencia)
Lodestar 是一个本地且事务性的引擎，允许代理发现、查询、理解和修改 Markdown 文档网络，而无需将其转换为专有格式。它读取现有的结构，解释你已经使用的 frontmatter，解析链接，并通过验证、并发控制和回滚保护更改。
```bash
cd 我的项目
lodestar-mcp
```
就这样。你不需要初始化仓库，创建特殊索引或适配你的文档。Lodestar 会递归发现 `.md` 文件，尊重 `.gitignore` 和 `.lodestarignore`，并使用当前目录作为工作空间。
> 你的 Markdown 文件仍然是唯一的真相来源：可供人类阅读，可使用你喜欢的工具进行版本控制，无需 Lodestar 即可使用。
## 功能特点
- **为代理提供精确的上下文。** 先搜索再检索，确保只检索必要的文件、章节或字段；不会将整个仓库加载到上下文中。
- **查询你自己的元数据。** 使用类型化运算符、点表示法和图形条件过滤任何 YAML 属性，无需强制规定模式。
- **展现真实的关系。** 解析 Markdown 链接、反向链接、孤立文档、损坏链接、路径和组件，支持任意深度。
- **更改前进行分析。** 在移动或删除文件之前计算影响范围和受影响的引用。
- **可恢复的更改。** 在内存中计划和验证，通过原子事务应用，并保留回执以便恢复。
- **CI 的质量门户。** 审计工作树并生成人类可读、JSON 或 SARIF 格式的输出，附带稳定的退出代码。
- **本地优先和文件优先。** 服务器通过 `stdio` 进行通信；SQLite/FTS5 缓存是派生的，可以从 Markdown 文件中重建。
## 代理如何使用 Lodestar
```text
定位 → 搜索 → 读取 → 检查元数据和关系
→ 分析影响 → 计划 → 应用 → 验证 → 需要时恢复
```
Lodestar 通过 MCP 公开此流程：
| 需求 | 工具 |
|---|---|
| 理解工作空间 | `workspace_status`, `knowledge_search`, `knowledge_get`, `metadata_inspect` |
| 分析知识 | `graph_query`, `impact_analyze`, `knowledge_check` |
| 安全更改 | `change_plan`, `change_apply`, `change_revert` |
`readonly` 配置文件提供七种读取和验证工具。默认使用的 `standard` 配置文件添加了更改计划、应用和恢复功能。
## 快速入门
### 1. 安装二进制文件
Lodestar 需要 Rust 1.80 或更高版本。从仓库副本中：
```bash
cargo install --path crates/lodestar-cli
cargo install --path crates/lodestar-mcp
```
这将安装：
- `lodestar`，用于验证和维护的 CLI；
- `lodestar-mcp`，连接工作空间与代理的本地服务器。
不需要 Node.js、git 或图形库。
### 2. 检查项目
```bash
cd /path/to/my-project
lodestar check
```
Lodestar 将扫描项目中所有可见的 Markdown 文件，而不会修改任何文件。
```bash
lodestar check --json
lodestar check --sarif > lodestar.sarif
```
### 3. 连接你的 MCP 客户端
配置客户端以通过 `stdio` 启动 `lodestar-mcp`。以下是基本值：
```text
command: lodestar-mcp
args: --root /absolute/path/to/my-project --profile readonly
```
在具有 JSON MCP 配置的客户端中，等效定义为：
```json
{
"mcpServers": {
"lodestar": {
"command": "lodestar-mcp",
"args": [
"--root",
"/absolute/path/to/my-project",
"--profile",
"readonly"
]
}
}
}
```
你可以省略 `--root`，如果客户端在项目内启动进程。使用 `readonly` 进行探索或审查；当你想要允许事务更改时，切换到 `standard`。
## 与现有的 Markdown 配合使用
无需必填字段或保留文件名。文档可以是纯 Markdown：
```markdown
# 凭证轮换
参见 [部署手册](../runbooks/deploy.md)。
```
或者可以使用适合您团队的任意 frontmatter YAML：
```markdown
---
status: accepted
priority: 2
owners:
- platform
service:
tier: critical
---
# 凭证轮换
参见 [部署手册](../runbooks/deploy.md)。
```
Lodestar 保留实际的 YAML 类型，并允许查询，如：
```text
status = "accepted" and priority >= 2
owners contains "platform"
service.tier = "critical"
graph.backlinks = 0
```
`metadata_inspect` 允许代理首先发现存在哪些字段、它们的 类型、覆盖率和频繁值。这样，代理可以在不了解项目的情况下理解其约定。
## 图形和影响
每个 Markdown 链接形成图形的一条边。Lodestar 识别内联链接、引用链接、锚点、外部目标和任意深度文档之间的相对路径。
`graph_query` 允许查询：
- 反向链接和出站链接；
- 进入、离开或双向邻居；
- 孤立文档和无目标链接；
- 两个文档之间的路径；
- 图形中的循环和组件。
在 `move` 或 `delete` 之前，`impact_analyze` 在不触摸磁盘的情况下识别直接和传递影响，并计算风险级别。
## 安全和可恢复的更改
`standard` 配置文件故意将思考和编写分开：
1. `change_plan` 规范化操作，在内存中模拟结果，计算语义差异，评估影响，并在更改可应用时进行验证。
2. `change_apply` 检查工作空间自计划以来是否未更改，并通过暂存、锁定、恢复副本、预写日志和原子重命名发布。
3. `knowledge_check` 确认结果状态。
4. `change_revert` 从收据中恢复最近的交易，如果需要，可以撤销它。
可用操作涵盖创建、手术修改 frontmatter、替换正文或文本、编辑章节、移动和删除。还可以使用查询获得的选定项应用兼容的操作。
文档和工作空间的确定性修订提供乐观的并发控制：如果一个人在计划和应用之间更改文件，Lodestar 将拒绝过时的写入。
## CLI
CLI 是用于人员、脚本和 CI 的小型外壳：
| 命令 | 用途 |
|---|---|
| `lodestar check` | 审计工作树 |
| `lodestar reindex` | 从 Markdown 重建 `.lodestar/index.db` |
| `lodestar migrate-from-okf --dry-run` | 在不修改文件的情况下诊断旧 OKF 约定 |
要操作其他目录而不更改 `cwd`：
```bash
lodestar --path /path/to/project check
```
`check` 的退出代码是稳定的：`0` 表示无错误，`1` 表示验证阻止，`2` 表示无效使用，`3` 表示运行时或 I/O 错误。
## 从 OKF 迁移
使用旧格式创建的仓库仍然是有效的 Markdown，可以直接打开。迁移命令仅用于诊断：
```bash
lodestar --path /path/to/project migrate-from-okf --dry-run
```
它报告索引、`okf_version` 和继承的标签索引，但从不修改项目。请参阅 [changelog](CHANGELOG.md) 以了解格式演变和版本间的不兼容性。
## 架构
```text
┌──────────────────────────┐
Markdown 仓库 ───► 发现 + 解析器 │
真实来源 │ 元数据 · 链接 · 查询 ├──► MCP / 代理
│ 图 · 影响 · Diff ├──► CLI / CI
│ 事务 · 恢复 │
└────────────┬─────────────┘
▼
SQLite / FTS5
可重建缓存
```
两个外壳共享域逻辑：
```text
crates/
lodestar-core/ 文档模型、元数据、链接、查询、图形和差异
lodestar-store/ SQLite/FTS5 缓存和观察者
lodestar-workspace/ 发现、I/O 和可恢复发布
lodestar-app/ CLI 和 MCP 共享用例
lodestar-cli/ 面向人员和 CI 的外壳
lodestar-mcp/ 面向代理的 stdio 外壳
lodestar-fixtures/ 共享测试工作空间
```
核心不执行 I/O 操作，外壳不重新实现语义。查询或验证产生的结果与使用者无关。
## 开发
```bash
cargo test --workspace --locked
cargo test -p lodestar-workspace --features test-failpoints --locked
cargo fmt --all --check
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
```
CI 在 Linux、macOS 和 Windows 上运行格式、严格 lint、构建、文档和测试 - 包括崩溃恢复场景。
## 文档
| 文档 | 内容 |
|---|---|
| [架构](ARCHITECTURE.md) | 当前设计和引擎不变性 |
| [MCP 合同](contracts/mcp.yml) | 工具的表面和语义 |
| [实现状态](IMPLEMENTATION_STATUS.md) | 已验证的功能和跟踪 |
| [决策](DECISIONES.md) | 开放或已批准的产品决策 |
| [更新日志](CHANGELOG.md) | 每个版本的更改历史 |
| [发布](RELEASING.md) | 发布过程 |
## 许可证
Lodestar 在 **MIT OR Apache-2.0** 下分发，由您选择。请参阅 [LICENSE-MIT](LICENSE-MIT) 和 [LICENSE-APACHE](LICENSE-APACHE)。
