个人 AI 知识库系统技术架构设计

1. 架构原则

1. 不魔改 Memos，使用 API、Webhook 和资源接口完成旁路增强。
2. 原始资料与 AI 生成资料分离，避免 AI 覆盖用户原文。
3. 标签树在 Sidecar 中强管控，Memos 中只承载最终标签文本。
4. 后台任务异步化，Webhook 接收与 AI 处理解耦。
5. 默认轻量本地部署，优先 SQLite，预留替换能力。
6. 所有代码完成标准为真实集成测试通过。

2. 总体架构

┌──────────────────────────┐
│          Memos            │
│  UI / API / Webhook       │
│  SQLite / Attachments     │
└─────────────┬────────────┘
              │ Webhook + API
              ▼
┌──────────────────────────┐
│     AI Sidecar Service    │
│ FastAPI + Background Jobs │
└─────────────┬────────────┘
              │
┌─────────────┼─────────────────────────────────────┐
│             │                                     │
▼             ▼                                     ▼
Memos      LLM Gateway                         Local Storage
Client     LiteLLM/OpenAI-compatible           SQLite + sqlite-vec
│          OpenRouter/Qwen/DeepSeek/Custom      Config + Backups
│
▼
Attachment Parsers
txt/md/docx/xlsx/pdf/drawio/mind-elixir-json

3. 部署架构

当前发布版采用 Docker Compose，部署在 NAS 或 Linux，并由 Caddy 网关提供统一入口。

memosima/
  docker-compose.yml
  .env
  config/
    app.yaml
    taxonomy.yaml
    doc-generation.yaml
    models.yaml
  data/
    memos/
    sidecar/
    backups/
  logs/

推荐服务：

默认只暴露 Caddy 网关宿主机端口；开发 Compose 默认为 ${GATEWAY_PORT:-8080}:80，生产 release Compose 默认为 ${GATEWAY_PORT:-8085}:80。用户通过统一网关进入 Memos 与 Sidecar 管理页面，Memos 的 5230 和 Sidecar 容器内部 8080 默认不直接暴露到宿主机。Memos 管理入口 memo 的链接由 PRISM_PUBLIC_BASE_URL（优先）或 app.public_base_url 生成，deploy.sh 会把探测到的公开网关地址写入 .env。

4. 模块设计

4.1 API 模块

职责：

• 接收 Memos webhook。
• 提供标签审核管理接口。
• 提供手动文档生成接口。
• 提供备份与恢复检查接口。
• 提供健康检查。

建议接口：

POST /webhooks/memos
GET  /health
GET  /admin/tag-candidates
POST /admin/tag-candidates/{id}/approve
POST /admin/tag-candidates/{id}/reject
POST /admin/documents/generate
POST /admin/backups
GET  /admin/backups
POST /admin/backups/{id}/verify

4.2 Memos Client

职责：

• 拉取 memo 列表和详情。
• 创建 AI 整理 memo。
• 创建 AI 文档 memo。
• 创建评论用于澄清。
• 建立 memo 关联或在正文中写入来源链接。
• 下载附件资源。

需要用集成测试校验 Memos 当前版本接口，避免依赖过期路径。

4.3 任务系统

Webhook 不直接执行 AI 处理，只创建任务。

任务类型：

process_memo
parse_attachment
review_tag_candidate
generate_document
index_memo
answer_question
backup_create
backup_verify
backup_restore

MVP 可用 SQLite 任务表加轮询 worker。后续可替换为 Redis Queue、Celery 或 Dramatiq。

4.4 LLM 网关

使用 OpenAI-compatible 抽象，支持：

• OpenRouter。
• Qwen。
• DeepSeek。
• 自定义 base_url、api_key、model。

配置示例：

providers:
  openrouter:
    base_url: https://openrouter.ai/api/v1
    api_key_env: OPENROUTER_API_KEY
    default_model: openrouter/auto
  qwen:
    base_url: https://dashscope.aliyuncs.com/compatible-mode/v1
    api_key_env: DASHSCOPE_API_KEY
    default_model: qwen-plus
  deepseek:
    base_url: https://api.deepseek.com
    api_key_env: DEEPSEEK_API_KEY
    default_model: deepseek-chat
  custom:
    base_url: ${CUSTOM_LLM_BASE_URL}
    api_key_env: CUSTOM_LLM_API_KEY
    default_model: ${CUSTOM_LLM_MODEL}

每次 AI 调用必须记录：

• provider。
• model。
• prompt 版本。
• token 用量。
• 耗时。
• 任务 ID。
• 输出校验结果。
• 错误信息。

当前实现状态：

• 已实现 OpenAI-compatible /chat/completions provider。
• 默认 provider 为 DeepSeek，默认模型为 deepseek-v4-flash。
• API key 只从 api_key_env 指定的环境变量读取，不写入配置文件或仓库。
• 模型输出按 JSON 对象校验，字段包含 title、summary、key_points、todos、needs_clarification 和 clarification_question。
• 未配置 API key 时，worker 自动回退到本地模板整理。

4.5 标签树模块

Sidecar 持有正式标签树、候选标签、别名和禁用词。Memos 中的标签只作为展示与检索入口。

核心能力：

• 加载标签树配置。
• 查询相似标签。
• 校验标签格式。
• 创建候选标签。
• 审核通过或拒绝。当前审核通过会写入 business_tags 表并标记为 active，worker 会合并配置标签和数据库 active 标签。
• 导出标签树用于备份。

标签状态：

active
candidate
rejected
disabled
merged

4.6 附件解析模块

解析策略：

安全限制：

• 文件大小上限可配置。
• MIME 与扩展名双重校验。
• 不解析未知格式。
• 解析失败保留原始附件链接和错误原因。

4.7 文档生成模块

文档生成配置：

defaults:
  keep_versions: 5
  output_tag: "#系统/AI文档"
rules:
  - name: project_daily_summary
    scope: "#项目"
    depth: 2
    trigger:
      type: schedule
      cron: "0 2 * * *"
    template: project_summary
  - name: approved_tag_document
    trigger:
      type: tag_approved
    template: tag_document

生成流程：

确定范围
-> 查询 memo 与 AI 整理结果
-> 排除旧版 AI 文档或按策略引用
-> 组织上下文
-> 调用 LLM 生成文档
-> 新建 AI 文档 memo
-> 建立来源关联
-> 清理超过 N 个版本的旧文档
-> 写入索引

4.8 RAG 与问答模块

用户体验上不暴露传统 chunk。内部使用语义单元。

语义单元类型：

• 原始 memo。
• AI 整理 memo。
• 附件段落或表格。
• AI 文档章节。
• Mind Elixir 节点路径。
• drawio 节点与连接说明。

检索策略：

1. 向量相似度检索。
2. 标签同层级和子树召回。
3. 来源 memo 关系扩展。
4. 去重与排序。
5. 生成带来源的回答。

第一版问答入口建议：

用户创建 #系统/问答 memo
-> Sidecar 识别问题
-> 检索
-> 新建 AI 回答 memo
-> 关联问题 memo 与来源 memo

4.9 备份恢复模块

本地备份目录结构：

backups/
  2026-05-18_210000/
    manifest.json
    memos.db
    memos-resources.tar.gz
    sidecar.db
    vector.db
    config.tar.gz
    taxonomy.yaml
    checksums.sha256
    restore.md

manifest.json 记录：

• 备份时间。
• 系统版本。
• Memos 版本。
• Sidecar 版本。
• 数据库文件列表。
• 校验和。
• 备份参数。

恢复策略：

1. 停止服务。
2. 校验备份包。
3. 备份当前数据为恢复前快照。
4. 覆盖数据文件。
5. 启动服务。
6. 执行健康检查与索引校验。

5. 数据库设计

5.1 workspaces

预留多人和多空间。

5.2 memos

记录 Sidecar 已处理的 memo 映射。

5.3 jobs

5.4 tag_nodes

5.5 tag_aliases

5.6 artifacts

5.7 vector_units

向量本体存入 sqlite-vec 虚拟表，通过 vector_units.id 关联。

5.8 document_versions

5.9 llm_calls

6. 配置设计

6.1 app.yaml

app:
  workspace_id: default
  public_base_url: http://localhost:8080
  timezone: Asia/Shanghai
security:
  admin_token_env: SIDECAR_ADMIN_TOKEN
limits:
  max_attachment_mb: 50
  allowed_parse_extensions:
    - .txt
    - .md
    - .docx
    - .xlsx
    - .pdf
    - .drawio
    - .drawio.svg
    - .json

6.2 taxonomy.yaml

system_tags:
  original: "#系统/原始记录"
  ai_summary: "#系统/AI整理"
  ai_document: "#系统/AI文档"
  pending_clarification: "#系统/待澄清"
  tag_candidate: "#系统/标签待审核"
  qa: "#系统/问答"
business_tags:
  - path: "#项目/个人AI知识库"
    status: active
aliases:
  - alias: "#AI知识库"
    target: "#项目/个人AI知识库"
disabled:
  - "#杂项"

6.3 models.yaml

见 LLM 网关配置。

6.4 doc-generation.yaml

见文档生成配置。

7. 测试策略

7.1 单元测试

• 标签路径校验。
• 标签相似度与别名映射。
• 附件解析器。
• Prompt 输出 schema 校验。
• 文档版本清理。
• 备份 manifest 与 checksum。

7.2 集成测试

• 使用真实 Memos 实例。
• 创建 memo 后触发 webhook。
• 新建 AI 整理 memo。
• 创建候选标签并审核通过。
• 解析附件并写入 artifacts。
• 生成文档并保留版本。
• 创建 #系统/问答 memo 并生成回答。
• 执行备份和恢复校验。

7.3 验收测试

所有核心流程必须基于真实服务完成，不以 mock 作为完成标准。

8. 技术风险与处理

9. P0-P1 实现状态（2026-05-19）

当前仓库已完成 P0-P1 技术基座：

• FastAPI Sidecar：GET /health、POST /webhooks/memos、GET /admin/jobs、POST /admin/jobs/{id}/retry。
• SQLite 任务系统：workspaces、memos、jobs 表和幂等任务创建。
• Worker：轮询 process_memo 任务，读取 Memos memo，并记录原始 memo 映射。
• Memos Client：封装读取 memo、创建 memo、创建评论、资源下载。
• 模型配置：默认 provider 为 DeepSeek，默认模型 deepseek-v4-flash，密钥仅从 DEEPSEEK_API_KEY 或本地忽略的 config/.env.local 读取。

当前 Linux 环境缺少 Docker，真实 Memos 容器联调尚未完成，详见 docs/API探针记录.html 与 docs/P0-P1验收记录.html。