osiman/git-learn

Fork 0

Files

T

zhuyongxin f45122dafb Reorganize workspace and archive skill artifacts

2026-05-20 11:39:30 +08:00

9.5 KiB

Raw Blame History

Explore 报告：Lumina（优化版）

项目类型： 代码仓库
完成阶段： 5/5
包含图示： 是
核心设计： 3 个
状态： 完成

阶段 1：定位

是什么： Lumina 是一个 AI 驱动的文章管理系统，采用全栈架构（FastAPI 后端 + Next.js 前端）。

为什么值得学习：

完整的内容处理 AI Pipeline 架构
领域驱动分层设计，关注点分离清晰
支持多租户的内容管理，内置治理功能

目标用户： 需要构建自托管知识库或 AI 增强 CMS 的开发者。

阶段 2：结构

lumina-main/
├── backend/              # FastAPI Python 后端
│   ├── app/
│   │   ├── api/routers/     # 16 个 REST 端点模块
│   │   ├── domain/          # 业务逻辑层 ⭐
│   │   ├── core/            # 配置与依赖
│   │   └── schemas/         # Pydantic 数据模型
│   ├── alembic/             # 数据库迁移
│   ├── ai_client.py         # AI 客户端抽象
│   └── models.py            # SQLAlchemy ORM 定义
└── frontend/             # Next.js React 前端
    └── src/
        ├── app/               # App Router 结构
        └── components/        # 可复用 UI 组件

入口点：

后端：backend/app/domain/ - 业务逻辑
前端：frontend/src/app/(routes)/ - 页面路由

阶段 3：流程（优化版 - 黄金路径视角）

端到端用户流程图

用户视角:
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   输入URL    │──────▶│ 等待处理     │──────▶│ 查看文章     │
└──────────────┘     └──────────────┘     └──────────────┘

系统视角:
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  API接收请求  │──────▶│  URL获取内容  │──────▶│  内容清洗    │
└──────────────┘     └──────────────┘     └───────┬──────┘
                                                  │
┌──────────────┐     ┌──────────────┐     ┌───────▼──────┐
│  向量存储     │◀────│   信息提取    │◀────│  AI处理链    │
└──────────────┘     └──────────────┘     └──────────────┘
                            │
                            ▼
                     ┌──────────────┐
                     │   响应用户    │
                     └──────────────┘

模块调用链

文章导入完整调用链：

POST /api/articles/ingest
    │
    ▼
┌──────────────────────────────────────┐
│  article_router.py                   │
│  - 接收 URL payload                   │
└──────────────┬───────────────────────┘
               │
               ▼
┌──────────────────────────────────────┐
│  article_url_ingest_service.py       │
│  - 获取原始 HTML                      │
└──────────────┬───────────────────────┘
               │
               ▼
┌──────────────────────────────────────┐
│  article_ai_pipeline_service.py      │
│  ┌──────────────┬──────────────┐     │
│  │ clean_text   │ extract_tags │     │
│  └──────────────┴──────────────┘     │
│  ┌──────────────┬──────────────┐     │
│  │ summarize    │ embed        │     │
│  └──────────────┴──────────────┘     │
└──────────────┬───────────────────────┘
               │
               ▼
┌──────────────────────────────────────┐
│  article_command_service.py            │
│  - 持久化到数据库                       │
└──────────────────────────────────────┘

优化点说明：

原报告只展示了 pipeline_service 单文件内部流程
优化版增加了用户视角的端到端流程和完整的模块调用链
让读者理解从 URL 到数据库的完整路径，不只是中间某个环节

阶段 4：起步路径（优化版 - 可执行命令）

前置要求：

Python 3.11+
PostgreSQL

步骤 1：环境准备

cd backend
pip install -e .

步骤 2：数据库初始化

alembic upgrade head

步骤 3：启动服务

uvicorn app.main:app --reload

首个观察点： 打开 backend/app/api/routers/article_router.py，搜索 ingest 端点，观察：

接收什么参数（URL、可选的 category_id）
调用哪个 service 方法
返回什么响应

第一个可执行的修改（颗粒度细化）：

原报告只说了"修改 AI_MODEL"，没有具体命令。以下是可落地的步骤：

# 1. 复制示例配置文件
cp backend/.env.example backend/.env

# 2. 查看当前 AI 模型设置
grep AI_MODEL backend/.env
# 输出: AI_MODEL=gpt-3.5-turbo

# 3. 修改为其他模型（举例）
sed -i 's/AI_MODEL=.*/AI_MODEL=gpt-4o-mini/' backend/.env

# 4. 确认修改成功
grep AI_MODEL backend/.env
# 输出: AI_MODEL=gpt-4o-mini

# 5. 重启服务（如果已运行）
# Ctrl+C 停止，然后重新运行:
uvicorn app.main:app --reload

# 6. 验证：测试 AI 摘要功能
# 在浏览器打开: http://localhost:8000/docs
# 找到 POST /api/articles/ingest，Try it out
# 输入: {"url": "https://example.com/article"}
# 观察响应中的 summary 字段质量变化

安全边界：

只改 .env 文件，不动源码
随时可以 cp backend/.env.example backend/.env 恢复
改模型不影响数据库，只影响 AI 调用

阶段 5：核心设计

#	设计	位置	重要性
1	领域服务层	`app/domain/*.py`	API 与数据库解耦；AI 集成可独立演进
2	AI Pipeline 架构	`article_ai_pipeline_service.py`	AI 处理不耦合 ORM；可配置、可追踪
3	路由注册器	`api/router_registry.py`	集中注册；新增模块无需改动 main.py

架构图示

后端领域架构：

┌─────────────────────────────────────────┐
│              API 路由层                 │
│  (article, ai_tasks, auth, settings...) │
└──────────────────┬──────────────────────┘
                   │
┌──────────────────▼──────────────────────┐
│           领域服务层                     │
│  ┌──────────────┐  ┌──────────────────┐  │
│  │article_query │  │article_command   │  │
│  └──────────────┘  └──────────────────┘  │
│  ┌──────────────┐  ┌──────────────────┐  │
│  │ai_pipeline   │  │ingest_service    │  │
│  └──────────────┘  └──────────────────┘  │
└──────────────────┬──────────────────────┘
                   │
┌──────────────────▼──────────────────────┐
│          SQLAlchemy 模型层              │
└─────────────────────────────────────────┘

优化点总结

优化项	原报告	优化版	改进原因
Phase 3 流程	单文件内部流程	端到端用户流程 + 完整调用链	让读者理解全貌，不只是某个环节
Phase 4 修改	"修改 AI_MODEL"（笼统）	给具体命令：copy → sed → grep → 重启 → 测试	用户可直接执行，有验证环节

验证备注

按 v0.5.0 规范完成 5 个阶段
未进行 essence 级别的深度提取
未进行交互式教学
遵守边界规则
Phase 4 的修改建议已通过 sed 命令细化到可操作级别

9.5 KiB Raw Blame History Unescape Escape