日常工作知识库

Appearance

NoteFlow 双擎架构：GitHub 资产冷备与 Cloudflare 智能知识库 Agent 实施方案 ​

归类：AI 工程化 / 个人知识库与 Agent 基础设施
制定时间：2026-10-13
状态：📝 方案已确立 · 演进实施中

一、背景与核心痛点 ​

随着 NoteFlow（Chrome 扩展 + Cloudflare Pages 在线工作台）从纯备忘录逐步承载个人与团队的重要工作沉淀，随之而来的是更深层次的业务诉求：

  1. 大文件与多媒体图片性能瓶颈：Markdown 内部直接嵌入高清 Base64 图片，会导致单篇笔记暴增至 5MB+，频繁触发 GitHub API 速率限制及浏览器 HTTP/2 协议错误；
  2. 多端数据一致性与孤儿文件覆盖：改动分类目录后，若远端旧路径未清理或缺乏更新时间戳防倒流判定，极易产生“新旧文件互搏覆写”；
  3. 面向未来的 AI 知识库诉求：笔记规模扩张后，用户希望能够指定某个专属目录（如 架构设计/、业务核对规则/）开放为知识库，供外部 AI Agent（如 Claude Code、Cursor、Dify、OpenClaw）或业务后端通过语义搜索高频调用。

二、存储底座深度对比选型 ​

在“纯 GitHub 私有仓”与“Cloudflare 边缘数据生态”之间，两者具有高度互补的特性：

评估维度方案 A：GitHub 私有仓库 (纯 Git Markdown)方案 B：Cloudflare 生态 (D1 + R2 + Vectorize)
数据所有权与防丢⭐️⭐️⭐️⭐️⭐️ 绝对最高。纯文本 Markdown，每个 Commit 均为完整物理快照，一键 git clone 离线保存。⭐️⭐️⭐️ 托管于 Serverless 分布式 SQLite，虽高可用但普通用户不易像本地文件夹直观查看。
外部生态互通⭐️⭐️⭐️⭐️⭐️ 完美。无缝兼容 Obsidian、VS Code、Logseq、Typora 等任何主流 Markdown 编辑器。⭐️⭐️ 依赖 SQL 或自定义 REST API 读写。
高频检索与并发 API⭐️⭐️ 受限。GitHub REST API 存在 5,000次/小时频控，拉取树结构存在网络延迟，不适合高并发 Agent 实时问答。⭐️⭐️⭐️⭐️⭐️ 毫秒级。Cloudflare 全球边缘节点无感就近响应，免费额度充沛，支持高并发并发调用。
图片与多媒体附件⭐️⭐️ 较弱。Git 存 Base64 或大二进制易导致仓库体积无限膨胀。⭐️⭐️⭐️⭐️⭐️ 极佳。接入 Cloudflare R2（兼容 S3，零出口流量费），正文只存轻量 URL。
AI 语义检索 (RAG)⭐️⭐️ 高成本。Agent 每次问答需拉取全量 Markdown 进行内存动态切块与计算，延迟达秒级。⭐️⭐️⭐️⭐️⭐️ 原生集成。内置 Vectorize 向量库 + Workers AI，原生支持按目录划分与语义相似度过滤。

核心决策：双擎驱动架构 (Dual-Engine Architecture) ​

不再做非此即彼的单选题，而是采用“前店后厂、双擎合璧”模式：

  • GitHub 私有仓库：作为终极资产冷备仓与版本归档中心（Source of Truth & Git Backup）。保持纯净 Markdown，支持随时本地克隆和多工具联动；
  • Cloudflare 边缘体系：作为高性能实时读写引擎与 Agent 知识库网关（Hot Engine & AI Gateway）。
    • D1 数据库：毫秒级读写笔记正文与结构化元数据；
    • R2 对象存储：轻量承载图片与多媒体附件，生成 CDN 直链；
    • Vectorize + Workers AI：为指定目录自动生成分块向量索引，对外暴露低延迟 RAG 搜索能力。
 ┌────────────────────────────────────────────────────────┐
 │              NoteFlow 客户端 (插件端 / Web端)            │
 └───────────────────┬────────────────┬───────────────────┘
                     │ 1. 实时读写    │ 2. 异步 Git 归档
                     ▼                ▼
   ┌─────────────────────────────────┐   ┌───────────────────────┐
   │    Cloudflare 边缘中枢服务        │   │    GitHub 私有仓库     │
   │   (Cloudflare Workers / Pages)  │   │ (rowkin/noteflow-data)│
   ├─────────────────────────────────┤   └───────────────────────┘
   │ • D1: 结构化元数据与纯文本正文     │     ▲ 长期版本追溯
   │ • R2: 高清图片与附件对象存储      │     │ 离线防丢/Obsidian互通
   │ • Vectorize: 笔记向量嵌入索引    │     │
   └────────────────┬────────────────┘     │
                    │ (自动同步或定时导出)───┘
                    ▼
┌─────────────────────────────────────────────────────────────────────────────────┐
│                           🤖 外部 Agent / 业务调用接口                             │
├───────────────────────────────────────┬─────────────────────────────────────────┤
│    方式 A: OpenAPI / REST 知识库接口   │       方式 B: Model Context Protocol (MCP)│
│  (支持 Dify, FastGPT, LangChain, 业务) │   (支持 Claude Code, Cursor, Antigravity)│
└───────────────────────────────────────┴─────────────────────────────────────────┘

三、指定目录作为知识库的系统设计 ​

1. 目录级知识库标记与元数据模型 ​

在笔记元数据中引入知识库目录绑定标识：

sql
CREATE TABLE notes (
  id TEXT PRIMARY KEY,
  title TEXT NOT NULL,
  content TEXT NOT NULL,          -- 纯文本 Markdown
  category TEXT NOT NULL,         -- 目录分类，如 '工作知识库/架构设计'
  tags TEXT,                      -- JSON Array: ["架构", "DDD"]
  is_kb_enabled INTEGER DEFAULT 0,-- 是否将该目录开放为 Agent 知识库 (0/1)
  images TEXT,                    -- JSON Array: ["https://r2.note.rowkin.xyz/xxx.png"]
  updated_at INTEGER NOT NULL,
  created_at INTEGER NOT NULL
);

CREATE INDEX idx_category ON notes(category);
CREATE INDEX idx_kb ON notes(is_kb_enabled);

2. 目录向量切片与语义索引机制 ​

当用户勾选或更新某个知识库目录（如 架构沉淀/）的笔记时，触发 Cloudflare Workers 自动分块切片并调用 Workers AI 嵌入：

ts
export async function updateNoteVector(note: Note, env: Env) {
  // 1. Markdown 语义分块 (Chunking)
  const chunks = splitMarkdownIntoChunks(note.content, { maxChars: 500, overlap: 50 });

  // 2. 调用 Cloudflare 免费内置 Workers AI 生成 1024 维向量
  const embeddings = await env.AI.run('@cf/baai/bge-base-en-v1.5', {
    text: chunks.map(c => c.text)
  });

  // 3. 写入 Cloudflare Vectorize 向量库，元数据附带 category 属性
  const vectors = chunks.map((chunk, i) => ({
    id: `${note.id}#chunk_${i}`,
    values: embeddings.data[i],
    metadata: {
      noteId: note.id,
      title: note.title,
      category: note.category, // ⚡ 关键：支持按目录严格过滤！
      text: chunk.text,
    }
  }));

  await env.VECTORIZE.upsert(vectors);
}

四、外部 Agent 与业务系统的双协议接入 ​

1. REST / OpenAPI 知识库检索接口（适配 Dify / FastGPT / 业务后端） ​

  • Endpoint：POST /api/v1/kb/search
  • Request Body：
json
{
  "query": "我们的结算核对规则和兜底策略是什么？",
  "directory": "财务业务/核对规则",   // ⚡ 指定知识库目录范围 (支持多级前缀匹配)
  "topK": 5,
  "scoreThreshold": 0.75
}
  • 核心查询逻辑：
ts
// 查询用户问题向量
const { data } = await env.AI.run('@cf/baai/bge-base-en-v1.5', { text: [query] });
const queryVector = data[0];

// 严格按指定目录过滤向量索引
const results = await env.VECTORIZE.query(queryVector, {
  topK: topK || 5,
  filter: { category: { $startsWith: directory } }, // 仅命中目标目录内部的笔记
  returnMetadata: 'all'
});

return Response.json({
  hits: results.matches.map(m => ({
    title: m.metadata.title,
    category: m.metadata.category,
    score: m.score,
    snippet: m.metadata.text
  }))
});

2. 原生 MCP Server 协议（适配 Claude Code / Cursor / Antigravity） ​

在 Cloudflare Worker 中暴露标准 Model Context Protocol (MCP) 端点：

  • Tool 1: noteflow_list_directories：列出当前标记为知识库的可用目录列表；
  • Tool 2: noteflow_query_knowledge：传入 directory 与 question，返回该目录下的结构化上下文片段，Agent 可在代码编写与排障过程中实现自动引用。

五、演进实施路线图 (Step-by-Step) ​

[阶段 1: 基础底座巩固] ──► [阶段 2: R2 图床与目录标识] ──► [阶段 3: D1 结构化与 Vectorize RAG] ──► [阶段 4: MCP 开放服务]
  • GitHub 数据结构对齐       • 图片直传 R2 告别 Base64       • 目录切块与向量嵌入               • Claude Code / Cursor
  • 404 预检防护              • 目录知识库开关 (UI)           • /api/v1/kb/search API            • 业务系统低延迟接入
  • RAW 传输防溢出            • 缩略图与正文严格解耦          • D1 实时双向检索
  1. 阶段 1（当前已完成）：彻底解决 GitHub 私有仓数据模型对齐、图片 Base64 提纯解耦、404 预检防护及 Blobs RAW 模式防 HTTP/2 协议错误；
  2. 阶段 2（近期演进）：在 NoteFlow 设置中提供 Cloudflare R2 / Worker 直传端点配置，将图片彻底从 Markdown 提纯为 URL，并在 UI 上支持为分类目录设置“设为知识库”标识；
  3. 阶段 3（生产落地）：在 Cloudflare Pages Functions 中建立 D1 表结构与 Vectorize 索引绑定，实现按目录前缀过滤的 /api/v1/kb/search 检索接口；
  4. 阶段 4（生态开放）：集成标准 MCP Server 协议，让 NoteFlow 真正成为全栈 AI Agent 的随身外部记忆体。