内容
# Fluffmind
**蓬松的、开源的第二大脑。**
可自主托管、支持Git的个人知识管理——一个开源的Obsidian替代方案。您的笔记保留为纯Markdown + 维基链接在Git仓库中（无锁定）。Fluffmind添加了现代化的Web界面、服务器端同步和用于AI代理的MCP桥接。
[项目看板](https://github.com/users/chatondearu/projects/3) · [里程碑](https://github.com/chatondearu/fluffmind/milestones) · [发布版本](https://github.com/chatondearu/fluffmind/releases)
---
## 为什么选择Fluffmind
- **您的文件，永远** —— Markdown + frontmatter 在 Git 中是唯一的真实来源。兼容 Foam/Obsidian 保险库；随时可以离开。
- **现代的块编辑器** —— Notion风格的拖放式编辑器，从零开始构建（无第三方编辑器框架）。
- **同步功能** —— Git/GitHub 在服务器端进行协调，因此多设备并不意味着多写入器混乱。
- **工作区** —— 多账户认证（Better Auth + Postgres），权限来自 GitHub 协作者或手动管理。
- **AI就绪** —— MCP 服务器（stdio 或 HTTP），代理可以搜索、读取、写入和遍历您的保险库。
- **100% 网页应用** —— 本地或公共服务器上的相同应用。可移植的独立软件包：解压并运行，无需 Docker/Postgres。
**技术栈：** Nuxt 3 · pnpm + Turborepo · Reka UI · UnoCSS · Material Design 3 · Drizzle · Postgres · Better Auth · MCP
---
## 快速开始
### 便携独立版（无需 Docker，无需 Postgres）
从 [发布版本](https://github.com/chatondearu/fluffmind/releases) 下载适用于您操作系统的版本（`fluffmind-darwin-arm64.tar.gz`、`linux-x64`、`win-x64` 等），解压后执行：
```sh
./bin/fluffmind start # 后台运行 - 自由关闭终端
./bin/fluffmind status
./bin/fluffmind stop
./bin/fluffmind # 前台运行（Ctrl+C停止）
./bin/fluffmind start --vault /path/to/notes
./bin/fluffmind start --vault /path/to/notes --readonly
./bin/fluffmind start --port 3456 --no-open
```
需要 **Git 在 PATH 中**。Node 已嵌入。认证/Postgres 已禁用。
`--readonly`（或 `VAULT_READONLY=true`）拒绝带有 HTTP 403 的笔记/文件夹变更。
后台 PID/日志：`data/fluffmind.pid` / `data/fluffmind.log`.
本地构建软件包：
```sh
pnpm install
pnpm package:portable # 当前操作系统/架构
pnpm package:portable -- --target all # 或 darwin-arm64|linux-x64|…
# 然后从仓库（使用 dist/portable/fluffmind-<os>-<arch>/）：
pnpm portable:start # 后台运行
pnpm portable:status
pnpm portable:stop
pnpm portable:start -- --vault /path/to/notes --port 3456 --readonly
```
产物位于 `dist/portable/`。
### 开发（最快的内循环）
```sh
pnpm install
VAULT_PATH=/absolute/path/to/a/markdown/vault pnpm --filter @fluffmind/web dev
# 浏览时禁止写入：
VAULT_PATH=/absolute/path/to/a/markdown/vault VAULT_READONLY=true pnpm --filter @fluffmind/web dev
```
### Docker
```sh
cp .env.example .env # 将 VAULT_PATH 设置为实际的 Markdown 保险库
./scripts/stack-local.sh
```
或手动：`docker compose up --build`。在容器内打开 http://localhost:3000 与 Postgres + 热重载开发服务器。
### 部署（Coolify）
`docker-compose.coolify.yml` 旨在用作 Coolify 的“Docker Compose”资源。
`DATABASE_URL` 自动连接到 Compose Postgres 服务 — 通常您只需要在 Coolify 的环境 UI 中设置以下变量。
**独立模式（最快）：** 保留 `AUTH_DISABLED=true`（默认），可选设置 `GIT_REMOTE_URL`，然后部署。
**多账户模式（Better Auth）：**
| 变量 | 必需 | 备注 |
| -------- | -------- | ----- |
| `AUTH_DISABLED` | 是 | `false` |
| `BETTER_AUTH_SECRET` | 是 | ≥ 32 随机字节（`openssl rand -base64 32`） |
| `BETTER_AUTH_URL` | 是 | 公共 URL，例如 `https://fluffmind.example.com`（无尾部斜杠） |
| `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` | GitHub 登录 | GitHub **OAuth 应用**（身份） |
| `GITHUB_SYNC_TOKEN_SECRET` | 推荐 | 加密工作区 PAT 链接 |
GitHub OAuth 应用回调 URL： `{BETTER_AUTH_URL}/api/auth/callback/github`。
在空实例上首次注册成为管理员，可以创建第一个工作区。
**GitHub 应用（可选，多仓库组织链接）：** 设置 `GITHUB_APP_ID`、`GITHUB_APP_PRIVATE_KEY`（PEM；使用 `\n` 表示换行符在 Coolify 中）、`GITHUB_APP_SLUG`，并最好设置 `GITHUB_APP_WEBHOOK_SECRET`（默认为 `GITHUB_WEBHOOK_SECRET`）。
应用权限：内容读写，元数据读取，成员/协作者读取。安装流程 + 工作区仓库绑定在设置下实时进行；PAT 链接仍然是备用方案。参见 ADR-009 / PRD-033。
**Webhooks:** 将 GitHub 指向 `POST {BETTER_AUTH_URL}/api/webhooks/github`（推送 + 安装事件，当使用 GitHub 应用时）。
**模式:** 部署后，对 Postgres 运行 Drizzle 迁移，当 `packages/db/drizzle/` 下有新 SQL 时（例如 `0001_*` 表示 GitHub 应用链接列）。
健康检查：`GET /api/health`（用于 Docker 健康检查）。
---
## MCP（AI 代理）
Fluffmind 通过 [模型上下文协议](https://modelcontextprotocol.io) 公开保险库工具：
| 工具 | 描述 |
| ---- | ----------- |
| `search_notes` | 按标题或 ID 搜索 |
| `read_note` | 读取 Markdown + frontmatter |
| `write_note` | 通过 `writeToWorkspace` 创建/更新 |
| `list_backlinks` | 入站维基链接 |
| `get_graph` | 保险库链接图 |
| `create_task` | 追加 `- [ ]` 任务（默认笔记：`inbox/tasks`） |
### 本地（stdio）
适用于同一台机器上的 Claude Code、Cursor 或其他 stdio MCP 客户端：
```sh
VAULT_PATH=/absolute/path/to/your/vault pnpm --filter @fluffmind/web mcp:stdio
```
Cursor 配置示例（`.cursor/mcp.json`）：
```json
{
"mcpServers": {
"fluffmind": {
"command": "pnpm",
"args": ["--filter", "@fluffmind/web", "mcp:stdio"],
"env": {
"VAULT_PATH": "/absolute/path/to/your/vault"
}
}
}
}
```
### 远程（HTTP）
当 Nuxt 应用运行时，代理可以连接到 **`/api/mcp`**（可流式 HTTP）。
如果启用了身份验证（设置了 `DATABASE_URL` 且 `AUTH_DISABLED` 不为 true），客户端必须发送与 Web UI 相同的会话 cookie（或先进行身份验证）。
---
## 发布
GitHub Releases 由 [.github/workflows/release-portable.yml](.github/workflows/release-portable.yml) 生成。
1. 推送版本号标签：`git tag v0.1.0 && git push origin v0.1.0`
2. 工作流在四个运行器上构建便携式存档（`darwin-arm64`、`darwin-x64`、`linux-x64`、`win-x64`），并将它们附加到发布版本中，以及 `SHA256SUMS`。
3. 或手动运行工作流（**Actions → 发布便携式 → 运行工作流**）而无需创建 GitHub Release（仅产物）。标签推送会同时构建 **和** 发布 Release。
每个资产都是一个解压即运行的独立软件包（嵌入 Node 22，无 Postgres）。有关最终用户说明，请参见上面的 [便携独立版](#便携独立版-无需-docker-无需-postgres)。
本地预运行（仅限当前机器）：
```sh
pnpm package:portable -- --target current
# → dist/portable/fluffmind-<os>-<arch>.tar.gz|.zip
```
---
## 状态 & 文档
MVP + 后 MVP UX 已发布，包括分布式工作区锁定（P7a）和便携式独立包装（P8a）。多磁盘扩展和静态发布仍在 [#28](https://github.com/chatondearu/fluffmind/issues/28) 中延期。
| 文档 | 目的 |
| --- | ------- |
| [`DESIGN.md`](./DESIGN.md) | 架构设计原因 |
| [`AGENTS.md`](./AGENTS.md) | 人类和代理的约定和注意事项 |
| [项目看板](https://github.com/users/chatondearu/projects/3) | 当前工作 |
| [里程碑](https://github.com/chatondearu/fluffmind/milestones) | P0 → P7 历史记录 |
