内容
# NavFlow
一款可自主托管的AI智能体数据流平台。NavFlow 从您的系统中摄取事件——日志、指标、部署、Postgres、Vercel、GitHub、OpenTelemetry——并将其无损地存储在嵌入式 DuckDB 中，为智能体提供 **一次关联的、按时间顺序的读取** 任意实体的能力，基于 MCP 协议。它还 **监控**：在条件触发时，推送关联的时间线到订阅的智能体。
它运行为两个进程——`navflowd`（守护进程）和 `navflow-mcp`（MCP 代理）——写入单个 DuckDB 文件。无需外部数据库或代理。
**文档：** [docs.navflow.ai](https://docs.navflow.ai) —— 快速入门、概念、连接器、MCP、部署和指南。
## 安装和运行
```bash
uv tool install navflow # 或：pipx install navflow
navflow up # 守护进程 + 控制台，访问 http://127.0.0.1:8787
```
Docker 镜像和服务器部署（TLS、身份验证）请参阅 [部署](https://docs.navflow.ai/deployment)。
## 体验
最快的体验方式是使用捆绑的 [`demo/`](demo/) —— 一个小型栈（API 服务器、Prometheus、流量）供 NavFlow 摄取，并具有故障注入：
```bash
cd demo && docker compose up -d && cd - # 启动栈以供摄取
```
停止上一步的守护进程（Ctrl-C），然后重新启动它，并使用演示目录——三个源、一个关联视图和两个触发器：
```bash
NAVFLOW_CATALOG=demo/catalog.demo.yaml navflow up
```
（目录仅在您的目录仍为空时导入。已经添加了一个源？请在新的数据目录中重新启动：`NAVFLOW_CATALOG=demo/catalog.demo.yaml navflow up --data-dir ~/navflow-demo`。）
打开 **探索** 并选择 `api-server`：请求日志、延迟和错误率指标，以及警报——三个源合并为一个按时间顺序的时间线。 该时间线正是智能体所获取的，因此请连接一个智能体并故意中断演示。
跳过演示？添加您自己的源：**源 → 添加源** 在控制台中（[连接器](https://docs.navflow.ai/connectors)）。
## 连接智能体
NavFlow 通过 [MCP](https://docs.navflow.ai/agents) 提供其读取/监控界面。运行 MCP 端点，并将客户端（Claude Code、Cursor、Claude Desktop 等）指向它：
```bash
# 1）MCP 端点——第二个进程（或使用_stdio传输并跳过此步骤）
navflow mcp --transport streamable-http --port 8788 --navflowd http://localhost:8787
# 2）连接 Claude Code
claude mcp add --transport http navflow http://localhost:8788/mcp
```
运行演示？现在导致事件发生——5xx 风暴——并给它大约 30 秒的时间来摄取：
```bash
./demo/inject.sh error_spike
```
然后询问您的智能体：
> 使用 navflow：过去 15 分钟内，api-server 发生了什么？
智能体调用 `read` 并获取关联的事件：5xx 请求日志、错误率峰值和警报在一个按时间顺序的响应中——无需在系统之间进行拼接。（`error_spike` 触发器也会触发——**智能体 → 触发器调度**；`./demo/inject.sh clear` 将故障恢复。）其他客户端、stdio 和身份验证请参阅 [连接智能体](https://docs.navflow.ai/agents)。
## 您获得的功能
- **连接器** —— Prometheus、Docker 日志、GitHub、Postgres、Vercel、OpenTelemetry（OTLP）、通用 webhook、智能体内存和 Claude Code 会话。在运行时添加和配置源；**发现** 步骤为可以自省的连接器提出配置。 → [连接器](https://docs.navflow.ai/connectors)
- **读取** —— `read(selector, window)` 返回任何实体的关联时间线，跨越所有源，无需视图；`query(view, …)` 通过保存的、缩小的视图读取；智能体 **订阅** 以在触发器触发时推送时间线。 → [概念](https://docs.navflow.ai/concepts)
- **控制台** —— 源（健康状况 + 设置）、**探索**（选择实体，读取其时间线，人类或智能体视图）、视图和触发器、智能体（连接客户端并监视其读取和调度），以及 **询问**（控制台内的数据助手，可使用 ⌘K 调用）。
- **MCP 工具** —— `read`、`query`、`subscribe`、`catalog_list` / `catalog_describe`、`derive`（智能体创建自己的视图）、`remember`（写回观察结果），以及源设置工具。 → [MCP](https://docs.navflow.ai/agents)
## 架构
两个进程共享一个 DuckDB 文件。`navflowd` 拥有存储并持续运行摄取和触发器评估；`navflow-mcp` 是一个薄_stdio_代理，智能体启动后通过 HTTP 访问守护进程。
```
上游 ──轮询/推送──▶ navflowd ──▶ DuckDB ──▶ 触发器评估 ──触发──▶ webhook ──▶ 订阅的智能体
▲
读取 / 查询 / 订阅（HTTP）
│
navflow-mcp（MCP 代理） ◀── 智能体
```
DuckDB 是单写入器，这就是为什么守护进程拥有数据库并且所有其他操作都通过其 HTTP API 进行。更多信息请参见 [概念](https://docs.navflow.ai/concepts)。
## 反馈
通过 [GitHub 问题](https://github.com/glassflow/navflow/issues) 或 `ashish@glassflow.dev` 欢迎提出错误报告和想法。
**无遥测** —— NavFlow 收集和发送零使用数据。
## 许可证
[MIT](LICENSE)。
