file-system-like-github

# fsbrain — 一个 AI 原生的 Markdown 知识库（MCP 服务器 + 第二大脑） > **一个本地优先的 Markdown 知识库，您可以交给 AI 代理 — 它会随着您的使用而变得更好。** 浏览它就像 **GitHub 文件树**，编辑它就像 **Notion**，并将其插入 Claude、Cursor 或任何 **MCP** 主机作为 **24 种代理工具** — 语义和混合搜索、RAG 上下文和引用答案。知识库 **自我改进**：它从您的草稿→最终编辑中学习您的写作风格，并自我整理损坏的链接、孤立的笔记和重复项 — 每次更改都进入 **人工审核队列**，代理提出建议，您来决定。普通的 `.md` 文件，离线运行，无需 API 密钥。 [](#) [](#) [](#) [](#) 如果您曾经希望您的 Markdown 内容能够： - **易于导航**，像代码仓库一样， - **易于编辑**，像现代文档工具一样， - **存储为真实文件**（不锁定在数据库中）， 那么这个项目就是为您准备的。 --- ## 为什么创建这个项目 大多数笔记/文档工具都迫使您做出取舍： - 优秀的用户体验，但专有存储。 - 优秀的存储（普通文件），但笨拙的用户体验。 这个代码仓库弥合了两者： - ✅ 熟悉的基于树的导航 - ✅ 以 Markdown 为优先的编辑和预览 - ✅ 安全的基于文件系统的 API - ✅ 适合轻松扩展的单体结构 --- ## 您可以用它做什么 - 在类似 GitHub 的文件树中浏览 Markdown 内容 - 打开文件并在 **预览** 和 **编辑** 选项卡之间切换 - 创建、重命名/移动和删除文件和文件夹 - 保存时带有乐观并发元数据（`etag` / `lastModified`） - 将您的内容保存在可配置的 `CONTENT_ROOT`（“知识库”）下 - 跨笔记搜索 — **全文**、**语义** 和 **混合**（Ctrl/Cmd-K） - 使用 `[[wikilinks]]` 链接笔记，浏览 **反向链接**，并探索交互式 **知识图谱** - 通过内置的 **MCP 服务器** 将知识库交给 AI 代理（读取/搜索/修补/提议），每次代理写入都记录在审计日志中，以便人类查看更改 --- ## 🤖 AI 和代理功能 这不仅仅是一个文件浏览器 — 知识库被设计为 **AI 代理的大脑**，人类始终在控制之下。下面所有功能都 **默认本地和离线运行**（无需 API 密钥），代理对您的笔记的任何更改都通过 **您批准的审核队列**。 - **🔎 智能搜索。** 按 **含义** 而不是精确词语查找笔记 — `语义` 搜索按相关性排名，`混合` 搜索融合关键词和语义结果。非常适合 _“我知道我把这写在某个地方……”_。 - **💬 询问您的笔记（`think`）。** 提出问题并获得 **引用答案**，从您自己的笔记中组装 — 加上诚实的 **空白** 列表，当知识库无法完全回答时，您知道缺少什么。 - **🔌 插入任何 AI 代理（MCP）。** 内置的 [MCP](https://modelcontextprotocol.io) 服务器将整个知识库交给像 Claude、Cursor 或 OpenClaw 这样的代理，作为 **24 种工具**（读取、搜索、修补、提议……）。**每次代理写入都记录** 在审计轨迹中，编辑作为 **您批准的提议** 落地 — 代理建议，只有您提交。 - **🧹 自我整理的知识库（维护）。** “梦周期”扫描查找 **损坏的链接、孤立的笔记和近似重复项**，并将每个修复作为提议归档。重新运行是安全的 — 它不会垃圾邮件发送到您的审核队列。 - **🪄 新增 — 从您的编辑中学习（反馈循环）。** 当代理起草外联 — **X 文章、LinkedIn 消息或电子邮件** — 而您在发送之前重写它时，该编辑是宝贵的信号。扫描比较 **草稿 vs. 您的最终版本**，提炼出您更改的内容（以及原因）到可重用的 **剧本课程**，并将其归档为 **提议**，供您审核。随着时间的推移，知识库以 **您的风格** 编写。**永远不会自动发布或发送** — 它只为您的审核提议笔记。 > **主线：代理提议，您决定。** 有风险或面向外部的更改永远不会自动应用 — 它们成为可审核的提议，归因于命名代理（例如 `agent:maintenance`，`agent:feedback-loop`），因此您始终看到谁建议了什么。 **30 秒了解反馈循环：** 1. 代理在 `social/x/drafts/launch.md` 处起草帖子。 2. 您编辑它并保存您实际发送到 `social/x/old-posts/launch.md` 的内容。 3. 您添加一个微小的“配对”笔记，链接两者（frontmatter: `type: feedback`, `channel: x`, `draftPath`, `finalPath`, 和可选的 `reviewReason`）。 4. 运行 `run_feedback` 代理工具（或 `POST /api/feedback/scan`）。它比较两者，将经验教训提炼成频道的 **剧本**，并将其归档为 **提议**，您在“审核”选项卡中批准。 --- ## 为现实世界的使用场景而构建 - 个人知识管理（PKM） - 团队文档门户 - 内部剧本/剧本 - 产品/项目文档 - 轻量级 Markdown CMS 基础 --- ## 架构概览 ```txt apps/web (React + Vite) ├─ 文件树 + 编辑器 / 预览 / 图表 / 活动 UI └─ 通过 HTTP/JSON 调用 API（实时更新通过 SSE） apps/api (Node HTTP 服务器) ├─ 验证和解析逻辑路径（沙盒到 CONTENT_ROOT） ├─ Markdown 焦点文件 CRUD + 乐观并发 └─ 搜索（文本/语义/混合），反向链接，图表，思考，审计，提议 apps/mcp (MCP stdio 服务器) ├─ 将知识库暴露给 AI 代理，作为 24 种工具 └─ 在进程中嵌入 API — 一个自包含的 MCP 主机命令 packages/shared └─ 共享 TypeScript 合同 + 纯助手（markdown，搜索，图表，…） ``` 代码仓库结构： ```txt apps/ api/ # 后端 HTTP 服务器 + 文件系统存储（CONTENT_ROOT） web/ # 前端 UI（React + Vite） mcp/ # MCP stdio 服务器 — 知识库作为代理工具（嵌入 API） packages/ shared/ # 共享类型/合同 + 纯助手 docs/ implementation.md # 项目状态的真实来源 CONNECT.md # 连接 MCP 主机（OpenClaw / Claude / Cursor） integration-test-plan.md # 手动集成检查 AGENTS.md # 如果您是此代码仓库中的 AI 代理，请从这里开始 ``` --- ## 快速开始（5 分钟内） ### 1) 准备工作 - Node.js **22.x** - npm **10.x** ### 2) 安装 ```bash npm install ``` ### 3) 运行 API + Web（两个终端） 终端 A： ```bash npm run dev:api ``` 终端 B： ```bash npm run dev:web ``` ### 4) 打开应用 - Web UI：`http://localhost:5173` - API 健康检查：`http://localhost:3001/health` --- ## 用作代理的大脑（克隆和运行） 跳过 Web UI，将知识库交给具有 MCP 功能的代理（OpenClaw，Claude Desktop，Claude Code，Cursor，...）： ```bash git clone https://github.com/andylow92/file-system-like-github.git cd file-system-like-github npm install npm run build # 生成 apps/mcp/dist/server.js npm run start:agent # 在 stdio 上启动自包含的 fsbrain-mcp ``` `fsbrain-mcp` 在进程中嵌入存储 API，并自动在 `~/.fsbrain/vault` 处创建知识库（通过 `CONTENT_ROOT=...` 重写）。它公开了 24 种知识库工具（`list_notes`, `read_note`, `create_note`, `patch_note`, `semantic_search`, `hybrid_search`, `think`, `get_graph`, `propose_edit`, `run_maintenance`, `list_skills`, `run_feedback`, ...），并将每个代理写入记录到 `<vault>/.fsbrain/audit.jsonl`，以便您可以查看代理的操作。 **复制粘贴配置代码片段**，适用于 OpenClaw / Claude Desktop / Claude Code / Cursor，参见 **[`docs/CONNECT.md`](docs/CONNECT.md)**。 > **旧克隆的提示信息。** 默认 `CONTENT_ROOT` 现为 `~/.fsbrain/vault`（之前为 `<cwd>/content`）。现有的 `./content` 笔记不会被删除，但 `npm run dev:api` / `npm run dev:web` / `npm run start:agent` 在未设置 `CONTENT_ROOT` 时将读取新路径。设置 `CONTENT_ROOT=./content`（在 `apps/api/.env` 或您的 shell 中），以保留旧位置。 --- ## 环境变量 对于 `apps/api`: - `CONTENT_ROOT` - Markdown 文件/目录的基准目录（“知识库”）。 - 如果未设置，则默认为 `~/.fsbrain/vault`（在首次运行时自动创建）。 - 设置 `CONTENT_ROOT=./content` 以保留旧克隆的位置。 - `PORT` - API 服务器端口（默认：`3001`）。 示例： ```bash CONTENT_ROOT=/absolute/path/to/vault PORT=3001 npm run dev:api ``` --- ## API 快照 **文件和树** - `GET /health` - `GET /api/tree?path=...` - `GET /api/file?path=...` （或 `?id=...`） - `POST /api/file` · `PUT /api/file` · `PATCH /api/file` （粒度操作） - `POST /api/dir` - `PATCH /api/path` （移动/重命名） · `DELETE /api/path?path=...&recursive=true|false` **链接、图表和块** - `GET /api/backlinks` · `GET /api/graph` - `GET /api/block` · `GET /api/block-anchors` **搜索和检索** - `GET /api/search` · `GET /api/semantic-search` · `GET /api/hybrid-search` - `GET /api/context` （RAG 包） · `GET /api/think` （引用答案套件） **来源、审核和维护** - `GET /api/audit` - `GET /api/proposals` · `POST /api/proposals` · `POST /api/proposals/resolve` （仅限人类） - `GET /api/maintenance` · `POST /api/maintenance/scan` - `GET /api/feedback` · `POST /api/feedback/scan` **实时** - `GET /api/events` （服务器发送事件） 有关端点详细信息和请求/响应示例，请参见 [`apps/api/README.md`](apps/api/README.md)。代理通常通过 MCP 工具访问这些端点 — 请参见 [`apps/mcp/README.md`](apps/mcp/README.md)。 --- ## 本地质量检查 ```bash npm test npm run lint npm run format ``` --- ## 安全模型（重要） - API 路径处理拒绝遍历和绝对路径。 - 文件操作以 Markdown 为重点（`.md`）。 - 存储解析确保请求保持在 `CONTENT_ROOT` 内。 这有助于保护主机文件系统，同时仍然启用基于文件的 工作流。 --- ## 部署说明 对于生产中的持久内容，请挂载主机卷并将 `CONTENT_ROOT` 指向它。 在 README 历史记录和后端文档中查看完整的部署示例。 --- ## 路线图想法 - ✅ 跨 Markdown 文件搜索（全文，语义和 **混合** RRF） - ✅ 交互式知识图谱 + 反向链接 - ✅ 内置 MCP 服务器 — 将知识库用作代理的大脑 - ✅ 引用答案 + 离线间隙分析（`think`）和梦周期维护 - ✅ 自我改进的 outreach **反馈循环** — 从草稿→最终编辑中学习您的声音 - Mermaid 图表 + 真实向量嵌入（缓存索引是缝隙） - Git 同步工作流 - 多用户身份验证 + 权限 - 实时协作编辑 - 可插拔存储适配器 --- ## 贡献 欢迎 PR。如果您想贡献： 1. 打开一个包含用例/问题陈述的 issue。 2. 提交带有测试的聚焦 PR。 3. 保持 Markdown/文件安全保证完整。 --- ## 额外文档 - **AI 代理从这里开始：** [`AGENTS.md`](AGENTS.md) — 代码仓库入口 + 工具/端点快速参考 - 项目状态/路线图（真实来源）：[`docs/implementation.md`](docs/implementation.md) - 后端 API 详细信息：[`apps/api/README.md`](apps/api/README.md) - 代理工具（MCP）+ 写入归因：[`apps/mcp/README.md`](apps/mcp/README.md) - 连接 MCP 主机（OpenClaw / Claude / Cursor）：[`docs/CONNECT.md`](docs/CONNECT.md) - 手动集成验证：[`docs/integration-test-plan.md`](docs/integration-test-plan.md) --- ## 关键词（用于可发现性） **AI 原生：** MCP 服务器，模型上下文协议，AI 代理工具，代理内存，自我改进的知识库，从编辑中学习反馈循环，自我修复维护，代理 RAG，检索增强生成，语义搜索，混合搜索（RRF），矢量就绪知识库，Claude / Cursor / OpenClaw 集成，LLM 的第二大脑，人工在环，代理提议和审计日志，引用答案。 **Markdown 工作区：** 类似 GitHub 的文件树，Notion 风格的 Markdown 编辑器，本地优先的 Markdown 知识库，文件系统 CMS，Markdown 知识库，维基链接和反向链接，知识图谱，React Markdown 编辑器，Node 文件系统 API，PKM。