Skip to content

AI-native knowledge base & Evernote/Obsidian alternative with instant sync & native MCP. Free on Cloudflare or self-hosted via Docker.

docs: simplify public readme

tianma1c21010326a0
diff --git a/README.md b/README.md
index 009f0a29..9f09d962 100644
--- a/README.md
+++ b/README.md
@@ -4,266 +4,42 @@
>
> **EdgeEver:基于 Cloudflare 全家桶自托管的开源『印象笔记』。**
+EdgeEver 是一个开源、自托管、Cloudflare-native 的现代笔记工作区。它保留经典印象笔记的三栏体验,同时提供清晰的数据模型、REST API,并为未来 MCP/CLI 接入预留接口。
+
<p align="center">
<a href="https://deploy.workers.cloudflare.com/?url=https://github.com/msh01/edgeever">
<img src="https://deploy.workers.cloudflare.com/button" alt="Deploy to Cloudflare" />
</a>
</p>
-<p align="center">
- 点击上方按钮进入 Cloudflare 部署向导;Cloudflare 会根据 wrangler 配置创建并绑定 D1/R2 资源,执行构建、D1 migration 和 Worker 部署。
-</p>
-
## 在线演示
- Demo 地址:[https://demo.edgeever.org](https://demo.edgeever.org)
- 演示账号:`ee-demo`
- 演示密码:`demo#dZ6Q29Zjfor%`
-这是公开演示环境,请不要在其中保存私密内容;演示数据可能随版本测试或维护被清理。
-
-EdgeEver 是一个完全开源、支持自部署、面向人类和 AI Agent 的现代笔记工作区。
-
-它致敬经典印象笔记的大屏三栏交互:笔记本目录、笔记列表、主编辑区。但 EdgeEver 不想复刻臃肿的旧时代套件,而是用 Cloudflare 的边缘网络、轻量前端、开放 API、MCP 和 CLI,把笔记系统重新做成一个可自托管、可编程、可被 AI 读写的个人知识库底座。
-
-## 产品定位
-
-EdgeEver 是一个现代个人知识库,面向三类一等用户:
-
-- **人类用户**:在专注的三栏界面中捕获、整理、编辑、搜索、合并笔记。
-- **AI Agent**:通过 REST API、MCP 或 CLI 读取、搜索、新建、追加、合并和整理笔记,而不是模拟点击 UI。
-- **自部署用户**:把完整系统部署到自己的 Cloudflare 账号下,用很低的运维成本拥有自己的笔记后端。
-
-EdgeEver 的目标不是再做一个大而全的效率套件,而是做一个锋利、轻快、开放的笔记核心:本地优先的体验,全球同步的部署,面向 AI 的明确接口。
-
-## 项目背景
-
-经典印象笔记有一个至今仍然优秀的设计:大屏三栏工作流。
-
-```text
-笔记本目录 -> 笔记列表 -> 编辑器
-```
+公开演示环境可能会被重置,请不要保存私密内容。
-这个布局依旧是浏览个人资料库、整理长期知识、快速切换上下文的高效方式。但现代笔记系统需要一个新的技术底座:
+## 功能
-- 笔记内容应该可读、可导出、可迁移。
-- 前端应该是轻量 SPA/PWA,而不是不必要的重型服务端应用。
-- 图片和附件应该进入对象存储,而不是塞进不透明的数据块。
-- 搜索应该建立在清晰的数据模型之上。
-- AI Agent 应该拥有显式、受权限控制的接口,而不是伪装成人类用户。
-- 自托管应该对个人开发者足够现实。
-
-EdgeEver 要做的就是这个版本:经典的信息架构,现代的边缘基础设施,从第一天起就为 Agent 读写做好准备。
-
-## 核心体验
-
-- **桌面三栏布局**:笔记本树、笔记卡片流、富文本编辑器。
-- **无限级嵌套笔记本**:通过 `parent_id` 支持多级目录树。
-- **Markdown 友好的富文本编辑**:TipTap/ProseMirror JSON 作为权威编辑器格式,Markdown 作为 Agent、CLI 和导出格式。
-- **PWA 响应式布局**:桌面端三栏,移动端自动折叠为单栏。
-- **单用户账号密码登录**:自部署实例可通过 PBKDF2-SHA256 密码 hash 启用网页登录,session 存入 D1。
-- **多选合并笔记**:选中多条笔记后创建一条合并后的新笔记,用 Markdown 分割线连接内容,原笔记软删除,资源引用重新指向新笔记。
-- **Headless 能力**:REST、MCP 和 CLI 共享同一套核心服务。
-- **资源模型**:图片和附件存入 R2,D1 保存资源元数据和笔记关联关系。
-
-## 架构规划
-
-```text
-edgeever/
-├── apps/
-│ ├── web/ # Vite + React PWA
-│ └── api/ # Cloudflare Worker + Hono
-├── packages/
-│ └── shared/ # 共享类型、Zod schema、内容格式转换
-├── migrations/ # Cloudflare D1 SQL 迁移
-├── docs/
-├── tailwind.config.ts
-└── wrangler.toml # Worker、Assets、D1、R2 绑定配置
-```
-
-目标运行形态是一个 Cloudflare Worker:
-
-- `/api/v1/*` 提供 REST API。
-- `/mcp` 提供远程 MCP Streamable HTTP 入口。
-- Workers Assets 从 `apps/web/dist` 托管构建后的 SPA。
-- D1 存储笔记本、笔记元数据、正文记录、搜索索引、用户、Session、Token、修订记录和审计事件。
-- R2 存储图片和附件。
+- 三栏布局:笔记本树、笔记列表、主编辑区。
+- 无限级嵌套笔记本。
+- TipTap 富文本编辑,服务端保存结构化 JSON、Markdown 和纯文本。
+- 图片粘贴上传到 R2,D1 保存资源元数据。
+- 图片自动压缩,GIF 会尝试转 animated WebP。
+- 附件入口,可查看资源列表和总存储占用。
+- 多选合并笔记,原笔记软删除,资源关联迁移到新笔记。
+- 单用户登录,密码使用 PBKDF2-SHA256 hash。
+- REST API-first,后续可接 MCP 和 CLI。
## 技术栈
-### 工程工具链
-
-- **Bun**:包管理器、脚本运行入口和 monorepo workspace 工具。
-
-### 前端
-
-- **Vite**:轻量 SPA 构建工具。
-- **React**:应用 UI 层。
-- **Tailwind CSS**:原子化样式系统。
-- **shadcn/ui**:可组合、可访问的 UI 组件基础。
-- **TipTap**:基于 ProseMirror 的富文本编辑器核心。
-- **TanStack Query**:API 缓存、乐观更新、重试和服务端状态管理。
-- **Dexie**:基于 IndexedDB 的离线缓存和本地草稿队列。
-- **Zod**:前后端共享数据校验。
-
-### 后端
-
-- **Cloudflare Workers**:边缘运行时。
-- **Hono**:轻量、快速的 HTTP 路由框架。
-- **Cloudflare D1**:SQLite 语义的关系型数据库。
-- **Cloudflare R2**:图片和附件对象存储。
-- **D1 FTS5**:全文搜索能力。
-- **Wrangler**:本地开发、迁移和部署工具。
-
-### Agent 与开发者接口
-
-- **REST API**:供 Web、CLI 和第三方集成调用。
-- **MCP Streamable HTTP**:通过 `/mcp` 暴露给支持远程 MCP 的客户端。
-- **本地 stdio MCP Server**:通过 EdgeEver CLI 启动,供桌面 AI 工具接入。
-- **CLI**:用于脚本化、导入导出和终端工作流。
-
-## 内容存储策略
-
-EdgeEver 不应该只把 Markdown 当作唯一真实格式。
-
-```text
-content_json TipTap/ProseMirror 文档,权威编辑器格式
-content_markdown Agent、CLI、导入导出、diff 使用的格式
-content_text 全文搜索、摘要、embedding 使用的纯文本
-```
-
-浏览器编辑器写入 TipTap JSON,并派生 Markdown 和纯文本。MCP 与 CLI 可以接受 Markdown 输入,但服务端需要把 Markdown 转换并校验为权威的 TipTap JSON 后再入库。
-
-## Cloudflare 初始化
-
-公开仓库可以直接通过上方 **Deploy to Cloudflare** 按钮进入部署向导。Cloudflare 会读取 `wrangler.toml`,为 D1/R2 等绑定创建或配置所需资源,并使用 `package.json` 中的 `deploy` 脚本执行 D1 migration 与 Worker 部署。你仍需要登录 Cloudflare、授权 GitHub/GitLab 连接,并确认仓库名、Worker 名和资源名;如果你的账号里已经存在同名 Worker 或仓库,把项目名改成一个唯一名称即可。
-
-`.env.example` 在 Deploy Button 语义下是 Worker Secret 模板。EdgeEver 的登录密码使用 PBKDF2-SHA256 hash,不要把明文密码放进仓库或 wrangler 配置。
-
-如果你更喜欢 CLI 部署,先创建本机环境文件:
-
-```sh
-cp .env.local.example .env.local
-```
-
-`.env.local` 已被 `.gitignore` 忽略,用来保存本机 Cloudflare 账号、资源名称、API Token 等部署参数。不要把它提交到公开仓库。
-
-创建 D1 数据库和 R2 存储桶:
-
-```sh
-bunx wrangler d1 create edgeever
-bunx wrangler r2 bucket create edgeever-resources
-```
-
-把 D1 创建命令返回的 `database_id` 填入本机 `.env.local` 的 `EDGE_EVER_D1_DATABASE_ID`。部署脚本会在运行时生成临时 `.wrangler.generated.toml`,不需要把个人 D1 ID 提交到公开仓库。
-
-生成登录密码 hash,并填入 `.env.local` 或部署环境的 secret:
-
-```sh
-bun run auth:hash -- <你的密码>
-```
-
-```text
-EDGE_EVER_AUTH_USERNAME=admin
-EDGE_EVER_AUTH_PASSWORD_HASH=<上一步生成的 hash>
-EDGE_EVER_SESSION_TTL_DAYS=30
-```
-
-线上部署时,`EDGE_EVER_AUTH_PASSWORD_HASH` 应作为 Cloudflare Worker Secret 或 GitHub Actions Secret 配置。未配置 `EDGE_EVER_AUTH_PASSWORD_HASH` 且 D1 中没有用户时,EdgeEver 会保持无登录保护,避免一键部署后因为缺少密码变量而锁死实例。一旦配置密码 hash,首次成功登录会在 D1 中创建用户,之后浏览器通过 HttpOnly cookie session 访问 REST API。
-
-## 多实例部署
-
-EdgeEver 推荐用多个 Worker + 多套 D1/R2 来做实例隔离。比如私人实例和公开演示实例:
-
-```text
-tianma.edgeever.org -> edgeever-tianma -> edgeever-tianma D1 + edgeever-tianma-resources R2
-demo.edgeever.org -> edgeever-demo -> edgeever-demo D1 + edgeever-demo-resources R2
-```
-
-本地 `.env.local` 可以按 `.env.local.example` 填入实例专属变量:
-
-```text
-EDGE_EVER_TIANMA_WORKER_NAME=edgeever-tianma
-EDGE_EVER_TIANMA_CUSTOM_DOMAIN=tianma.edgeever.org
-EDGE_EVER_TIANMA_D1_DATABASE_ID=<tianma D1 database_id>
-EDGE_EVER_TIANMA_R2_BUCKET_NAME=edgeever-tianma-resources
-EDGE_EVER_TIANMA_AUTH_USERNAME=<tianma 登录账号>
-
-EDGE_EVER_DEMO_WORKER_NAME=edgeever-demo
-EDGE_EVER_DEMO_ROUTE_PATTERN=demo.edgeever.org/*
-EDGE_EVER_DEMO_D1_DATABASE_ID=<demo D1 database_id>
-EDGE_EVER_DEMO_R2_BUCKET_NAME=edgeever-demo-resources
-EDGE_EVER_DEMO_AUTH_USERNAME=<demo 登录账号>
-```
+- 前端:Vite、React、Tailwind CSS、TipTap、TanStack Query、Dexie。
+- 后端:Cloudflare Workers、Hono。
+- 存储:Cloudflare D1、Cloudflare R2。
+- 工具链:Bun、Wrangler、TypeScript。
-`EDGE_EVER_CUSTOM_DOMAIN` 会通过 Workers Custom Domain 绑定域名;`EDGE_EVER_ROUTE_PATTERN` 会生成 Worker Route,适合配合 DNS CNAME 使用。当前推荐 `tianma` 用 Custom Domain,`demo` 用 Route Pattern,两个实例彼此独立。
-
-部署单个实例:
-
-```sh
-bun run deploy:tianma
-bun run deploy:demo
-```
-
-同时部署两个实例:
-
-```sh
-bun run deploy:all
-```
-
-## GitHub Actions 自动部署
-
-仓库内置 `.github/workflows/deploy.yml`。Push 到 `main` 后会自动:
-
-1. 安装 Bun 依赖。
-2. 执行 `bun run typecheck`。
-3. 部署 `tianma` 实例。
-4. 同步 `tianma` 的 Worker Secret。
-5. 部署 `demo` 实例。
-6. 同步 `demo` 的 Worker Secret。
-
-需要在 GitHub 仓库 Secrets 中配置:
-
-```text
-CLOUDFLARE_ACCOUNT_ID
-CLOUDFLARE_API_TOKEN
-
-EDGE_EVER_TIANMA_WORKER_NAME
-EDGE_EVER_TIANMA_CUSTOM_DOMAIN
-EDGE_EVER_TIANMA_D1_DATABASE_NAME
-EDGE_EVER_TIANMA_D1_DATABASE_ID
-EDGE_EVER_TIANMA_R2_BUCKET_NAME
-EDGE_EVER_TIANMA_R2_PREVIEW_BUCKET_NAME
-EDGE_EVER_TIANMA_AUTH_USERNAME
-EDGE_EVER_TIANMA_AUTH_PASSWORD_HASH
-EDGE_EVER_TIANMA_SESSION_TTL_DAYS
-
-EDGE_EVER_DEMO_WORKER_NAME
-EDGE_EVER_DEMO_ROUTE_PATTERN
-EDGE_EVER_DEMO_D1_DATABASE_NAME
-EDGE_EVER_DEMO_D1_DATABASE_ID
-EDGE_EVER_DEMO_R2_BUCKET_NAME
-EDGE_EVER_DEMO_R2_PREVIEW_BUCKET_NAME
-EDGE_EVER_DEMO_AUTH_USERNAME
-EDGE_EVER_DEMO_AUTH_PASSWORD_HASH
-EDGE_EVER_DEMO_SESSION_TTL_DAYS
-```
-
-Cloudflare 原生 Workers Builds 也可以做 Git 集成;如果账号已启用 Workers Previews/Builds,可以把同样的 deploy command 配成 `bun run deploy:tianma` 和 `bun run deploy:demo`。当前仓库默认使用 GitHub Actions,因为它对普通公开仓库更直接。
-
-应用本地迁移:
-
-```sh
-bunx wrangler d1 migrations apply DB --local
-```
-
-应用远程迁移:
-
-```sh
-bunx wrangler d1 migrations apply DB --remote
-```
-
-## 本地开发
+## 快速开始
安装依赖:
@@ -277,43 +53,53 @@ bun install
bun run db:migrate:local
```
-同时启动 Worker API 和 Vite 前端:
+启动本地开发:
```sh
bun run dev
```
-也可以分开启动:
+常用检查:
```sh
-bun run dev:api
-bun run dev:web
+bun run typecheck
+bun run build
```
-常用校验:
+## 部署
+
+最简单的方式是点击上方 **Deploy to Cloudflare** 按钮,根据 Cloudflare 向导完成授权和部署。
+
+如果使用 CLI 部署:
```sh
-bun run typecheck
-bun run build
+cp .env.local.example .env.local
+bunx wrangler d1 create edgeever
+bunx wrangler r2 bucket create edgeever-resources
+bun run auth:hash -- <你的密码>
+bun run deploy
```
-## 当前阶段
+把 D1 创建命令返回的 `database_id` 和密码 hash 填入本机 `.env.local`。`.env.local` 已被 `.gitignore` 忽略,不要提交。
-当前已经具备第一条可运行纵向切片:
+GitHub Actions 不是自部署必须项。本仓库的 workflow 用于维护者自动发布演示实例;普通 fork 用户只需要配置自己的 Cloudflare 账号、D1、R2 和登录密码即可。
-- Bun monorepo 基础工程。
-- D1 schema:支持嵌套笔记本、用户、Session、笔记正文拆表、FTS5 搜索、资源、修订、审计、软删除和合并字段。
-- Hono REST API:账号密码登录、cookie session 鉴权、笔记本列表/创建/更新/删除,笔记列表/创建/读取/更新/删除,搜索,多选合并。
-- Vite React PWA:登录页、桌面三栏布局,移动端单栏切换,递归笔记本树,笔记卡片流,TipTap 编辑器,标签和本地草稿备份。
-- 基础 `wrangler.toml`:配置 Workers Assets、D1、R2 和 `/api/*`、`/mcp` Worker-first 路由。
+## 目录结构
-后续阶段会继续补完整 MCP Server、CLI、资源上传、认证 Token、导入导出和更完整的 Markdown 双向转换。
+```text
+apps/web Vite + React 前端
+apps/api Cloudflare Worker + Hono API
+packages/shared 共享类型、schema 和内容转换
+migrations D1 数据库迁移
+wrangler.toml Cloudflare Workers 配置
+```
-## 项目原则
+## 内容格式
-- **默认开放**:数据应该可读、可导出、可脚本化。
-- **为 Agent 准备,但不牺牲人类体验**:人类使用最好的 UI,Agent 使用明确的 API。
-- **边缘原生,而不是边缘噱头**:只在 Cloudflare 真正降低部署和运维复杂度的地方使用它。
-- **内容可迁移**:Markdown 很重要,但结构化编辑器 JSON 才能保护富文本保真度。
-- **软删除和可审计**:破坏性操作必须可追踪、可恢复。
-- **小模块,清边界**:UI、REST、MCP、CLI 共享核心行为,而不是重复实现。
+EdgeEver 同时保存三种内容形态:
+
+```text
+content_json TipTap/ProseMirror 文档,编辑器权威格式
+content_markdown API、Agent、导入导出使用
+content_text 搜索、摘要和索引使用
+```