AI-native knowledge base & Evernote/Obsidian alternative with instant sync & native MCP. Free on Cloudflare or self-hosted via Docker.
HTML ai-agentcloudflarecloudflare-d1cloudflare-r2cloudflare-workersdockerelectronevernoteevernote-alternativeknowledge-basemcpnote-takingobsidian-alternativeoffline-firstpersonal-knowledge-basepwaself-hostedsqlitetiptapweb-clipper
docs: simplify public readme
tianma1c21010326a0
diff --git a/README.md b/README.mdindex 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 installbun run db:migrate:local```-同时启动 Worker API 和 Vite 前端:+启动本地开发:```shbun 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 搜索、摘要和索引使用+```