内容
# 达菲尔
达菲尔是为个人和LLM代理提供的本地网络Markdown工作区。
它将笔记存储为普通的Markdown文件，通过小型Web UI提供服务，
使用`qmd`索引，并公开MCP服务器，以便编码代理可以搜索、
读取、写入和追加日记条目，而无需自定义粘合脚本。
## 截图
### 带有相关内容的笔记
### 日记历史
### MCP连接器设置
## 适用人群
在以下情况下使用达菲尔：
- 需要一个由您可以正常检查和版本控制的文件支持的本地笔记工作区。
- 需要一个浏览器UI，用于阅读、编辑、存档和搜索Markdown笔记。
- 需要一个MCP端点，让LLM工具可以使用与持久项目内存相同的笔记。
- 需要一个简单的Go + TypeScript应用程序，可以在笔记本电脑、家庭服务器或私有网络上运行。
## 请求LLM设置
将此提示粘贴到您的编码助手从干净的机器或服务器：
```text
从 https://github.com/jibs/duffel 设置达菲尔。
要求：
- 使用pnpm，而不是npm。
- 不要安装全局qmd二进制文件；达菲尔使用来自pnpm依赖项的固定@tobilu/qmd包。
- 首先启动本地开发运行。
- 如果这只是一个私有本地演示，请使用DUFFEL_AUTH_ENABLED=false运行。
- 如果这是实际的共享/私有网络部署，请启用身份验证并在首次设置之前设置DUFFEL_SETUP_TOKEN。
步骤：
1. 克隆仓库并进入其中。
2. 运行make setup。
3. 在./data目录为空时，创建几个示例Markdown文件。
4. 启动应用程序，开发环境使用make dev，系统部署请遵循ops/deploy/DEPLOY.md。
5. 打开 http://localhost:4386。
6. 对于LLM集成，打开 http://localhost:4386/#/_mcp并配置其中显示的MCP客户端。
7. 在提出任何代码更改之前运行make ci。
```
## 快速入门：本地演示
要求：
- Go `1.26+`
- Node.js和pnpm
- `make`
- `curl`
```bash
git clone https://github.com/jibs/duffel.git
cd duffel
make setup
mkdir -p data/projects data/research data/journal
cat > data/index.md <<'MD'
---
type: note
---
# 欢迎使用达菲尔
这是一个文件系统支持的Markdown工作区。
尝试：
- 在侧边栏浏览文件
- 编辑此笔记
- 搜索`MCP`
- 打开MCP连接器页面
MD
cat > data/projects/demo.md <<'MD'
---
type: note
---
# 演示项目
达菲尔将项目笔记保存在Markdown中，并通过MCP将其公开给LLM代理。
## 任务
- 捕获设置决策
- 存储有用的研究
- 在更改后追加日记更新
MD
cat > data/research/mcp.md <<'MD'
---
type: research
---
# MCP笔记
使用 `#/_mcp` 处的MCP连接器配置兼容的代理。
代理应首先搜索，读取仅相关的文件，并追加简洁的日记条目以进行持久更改。
MD
cat > data/journal/worklog.md <<'MD'
---
type: journal
---
## 2026-01-01 09:00
演示：创建了一个示例达菲尔工作区。
MD
DUFFEL_AUTH_ENABLED=false make dev
```
打开 `http://localhost:4386`。
对于本地演示，身份验证在上面的命令中被禁用。对于其他人或机器可访问的任何内容，请启用身份验证并遵循下面的身份验证设置。
## 生产/私有网络设置
达菲尔默认启用身份验证。
在第一个所有者设置之前，设置一次性设置令牌：
```bash
export DUFFEL_SETUP_TOKEN="$(openssl rand -base64 32)"
make dev
```
打开 `http://localhost:4386/oauth/setup`，创建所有者帐户，将返回的引导令牌存储在您的秘密管理器中（如果您需要CLI/MCP引导访问），然后从运行时环境中删除 `DUFFEL_SETUP_TOKEN`。
对于systemd部署，请使用 [ops/deploy/DEPLOY.md](ops/deploy/DEPLOY.md)。
该指南使用通用主机名和路径；请用您自己的服务器值替换它们。
## LLM和MCP设置
达菲尔在 `/mcp` 处公开了一个可流式传输的HTTP MCP端点。
在浏览器UI中：
1. 打开 `http://localhost:4386/#/_mcp`。
2. 如果启用了身份验证，请创建或粘贴一个承载令牌。
3. 复制为您的代理生成的客户端配置。
通用MCP配置形状:
```json
{
"mcpServers": {
"duffel": {
"type": "streamable-http",
"url": "http://localhost:4386/mcp",
"headers": {
"Authorization": "Bearer ${DUFFEL_MCP_TOKEN}"
}
}
}
}
```
如果您使用 `DUFFEL_AUTH_ENABLED=false` 启动达菲尔，请省略 `headers` 块。
推荐的代理行为：
- 在读取广泛的文件夹之前搜索。
- 首先使用小结果限制。
- 只读取任务所需的文档。
- 使用日记文件进行简洁的更改历史记录。
- 将研究文物保存在名为 `research/` 的清晰文件夹下。
- 不要提交机密、本地笔记数据、`.env`、生成的令牌或运行时日志。
## 配置
环境变量：
| 变量 | 默认值 | 用途 |
| --- | --- | --- |
| `DUFFEL_HOST` | 空 | 绑定地址。空表示所有接口。 |
| `DUFFEL_PORT` | `4386` | HTTP端口。 |
| `DUFFEL_DATA_DIR` | `./data` | Markdown工作区根目录。 |
| `DUFFEL_FRONTEND_DIR` | `./src/frontend` | 静态前端目录。 |
| `DUFFEL_AUTH_ENABLED` | `true` | 为API和MCP启用OAuth/Bearer身份验证。 |
| `DUFFEL_SETUP_TOKEN` | 空 | 启用身份验证时，首次所有者设置所需。 |
`qmd` 由固定的npm依赖项 `@tobilu/qmd@2.1.0` 提供；请勿安装或依赖全局 `qmd` 二进制文件。
## API概述
所有数据API都在 `/api` 下。OAuth和MCP发现路由位于根目录。
响应为JSON，除了代理助手脚本/代码段/版本路由和OAuth HTML表单。
主要路由：
- `GET|PUT|POST|DELETE /api/fs/*` 用于文件系统支持的笔记和目录。
- `POST /api/archive/*` 和 `POST /api/unarchive/*` 用于存档移动。
- `POST /api/journal/*` 和 `POST /api/journal/*/append` 用于日记文件。
- `GET /api/search?q=<query>` 用于工作区搜索。
- `GET|POST|DELETE /api/mcp/tokens` 用于MCP承载令牌管理。
- `GET|POST /mcp` 用于MCP服务器。
- `GET|POST /oauth/setup`、`/oauth/authorize`、`/oauth/token` 和 `/oauth/register` 用于身份验证。
## 达菲尔库
达菲尔的低级知识工作区功能作为Go包提供，位于 `pkg/duffellib` 下。
当另一个项目需要与达菲尔相同的安全磁盘支持的文档行为时，请使用 `duffellib.Open`:
- 根限制路径解析，带符号链接逃逸检查
- 验证文本写入，验证读写后，允许列出的二进制图像写入
- 日记创建和锁定日记追加
- 存档/取消存档操作
- 通过 `Workspace.Search` 进行一流的工作区搜索
搜索是库API的一部分。具体的搜索后端是达菲尔实现细节；调用者应使用 `duffellib.Workspace` 和 `duffellib/search.SearchOptions`，而不是调用索引工具。
## 开发
常用命令：
```bash
make setup # 安装依赖项
make dev # 构建前端JS并运行Go服务器
make build # 构建后端二进制文件
make test # 运行单元测试、集成测试和端到端测试
make lint # 运行Go和TypeScript lint
make fmt # 格式化Go和TypeScript
make release-audit # 扫描跟踪的文件以检查隐私/安全风险
make ci # 完整的本地检查套件
```
在发布更改之前，请运行：
```bash
make ci
```
CI目标包括格式化检查、lint、Go vet、TypeScript检查、前端构建、后端测试、端到端测试和发布审计。
## 安全模型
- 默认启用身份验证。
- 首次所有者设置需要 `DUFFEL_SETUP_TOKEN`。
- 当启用身份验证时，API数据路由和 `/mcp` 需要Bearer身份验证。
- OAuth发现/设置路由和代理助手路由保持公开以进行引导。
- 存储规范化路径并在配置的数据根目录下保留操作。
- 默认启用同源CORS和变异跨源保护。
对于公共或面向互联网的部署，请将达菲尔置于HTTPS/TLS和正常网络控制之下。达菲尔主要设计用于受信任的本地或私有网络使用。
## 仓库卫生
受跟踪的源代码不应包括个人笔记数据、生成的令牌、`.env`、运行时日志或本地机器路径。
在发布前运行：
```bash
make release-audit
trufflehog filesystem --no-update --only-verified .
```
## 更多文档
- [CONTRIBUTING.md](CONTRIBUTING.md)
- [SECURITY.md](SECURITY.md)
- [AGENTS.md](AGENTS.md)
- [ops/deploy/DEPLOY.md](ops/deploy/DEPLOY.md)
- [ops/docs/public-release-checklist.md](ops/docs/public-release-checklist.md)
