SWF

作为软件架构师，我面临着构建一个能够解释复杂视觉信息系统（具体为 Dakila 技术语境中的几何象征与波频率）并将其与高度专业化的知识库进行交叉比对的挑战。根本问题在于处理非结构化视觉伪影并将其精确地与庞大的文档记录关联起来的难度，同时降低语言模型产生幻觉的风险。

为了解决这个问题，我设计了一个渐进式 Web 平台 (PWA)，它充当计算机视觉与结构化信息检索 (RAG) 之间的桥梁。该系统不是一个简单的聊天机器人；它是一个推理引擎，编排多模态模型来提取图像特征（几何模式、线条、曲线、颜色），并将这些属性用作针对专业矢量数据库的搜索向量。

主要业务工作流

从业务角度来看，系统按照三个主要阶段执行确定性序列：

1. 分析导入： 用户提供图像以及可选的文本上下文。系统使用 Vercel Blob 处理并临时保存视觉文件，为多模态分析做准备。
2. 提取与矢量搜索 (RAG)： 人工智能 Agent（由 Mastra 和基础模型驱动）执行初始视觉分析以提取图像元数据。紧接着，系统将这些发现矢量化并查询内部知识库。这一步确保了后续的任何声明都严格锚定在官方文献中。
3. 综合与状态返回： 引擎将视觉发现与检索到的记录合并，生成结构化响应。对话通过专门的内存系统在整个会话中保持状态，允许针对同一视觉伪影进行后续迭代。

---

架构解剖

为了构建这个系统，我选择了解耦的模块化架构，优先考虑性能以及呈现层与认知编排之间的清晰职责分离。

整体架构

项目在基于 Astro 的生态系统中遵循 服务导向的解耦架构 模式。这一决定背后的技术原因是将人工智能 Agent 的计算复杂性与用户界面的渲染相隔离，确保可扩展性和可维护性。

• 呈现层 (Frontend)： 使用 Astro 和 React 构建。我选择 Astro 是因为它的“群岛”哲学，这允许仅在需要时才水化复杂的交互（如 3D 可视化器或聊天界面）。界面由将渲染委托给特定子组件的高层组件编排。
• 编排与 API 层： 通过充当中间件的安全 API 路由暴露。这里管理文件上传、实时分布式配置验证以及将流请求委托给底层认知引擎。
• 认知引擎 (Agentic Layer)： 构成了领域核心。我配置了一个配备矢量查询工具和多模态能力的自主 Agent，完全封装了推理逻辑和 RAG 交互。

graph TD
    %% Architecture Diagram
    User([用户]) --> |上传图像 / 消息| UI[UI 呈现层\nReact / Astro]
    UI --> |FormData| API[API 中间件\n/api/analyze.ts]

    subgraph Edge Infrastructure
        API --> |Upload| BlobStore[(Vercel Blob)]
        API --> |状态验证| EdgeConfig[(Edge Config)]
    end

    API --> |Stream Request\n上下文 + 图像 URL| Agent[认知引擎\nMastra Agent]

    subgraph Cognitive Layer
        Agent --> |实体提取| LLM[Google Gemini Multimodal]
        Agent --> |矢量查询| VectorTool[RAG 搜索工具]
        VectorTool --> |Embeddings Text-004| VectorDB[(LibSQL Vector Store)]
        Agent --> |上下文管理| Memory[(LibSQL Store\nMastra Memory)]
    end

    LLM --> |合成响应| Agent
    Agent --> |Server-Sent Events| API
    API --> |Stream| UI

数据建模与状态管理

应用要求对对话状态和处理后的伪影进行严格控制。为此，我实现了一个基于执行线程的持久化模型。

• 前端状态管理： 在 React 中通过 hooks 和 context 容器集中管理，保持向渲染组件（聊天、交互可视化器、视觉反馈）的严格单向数据流。
• 后端状态管理： 代理框架利用事务内存模块自主地在嵌入式数据库中持久化消息历史，通过唯一标识符将其链接起来。

erDiagram
    %% Data Model
    THREAD {
        string threadId PK
        datetime createdAt
    }
    MESSAGE {
        string messageId PK
        string role "user | assistant"
        text content
        string threadId FK
    }
    RESOURCE {
        string resourceId PK
        string publicUrl "Blob Storage Access URL"
    }
    KNOWLEDGE_CHUNK {
        string chunkId PK
        vector embedding "Dimension: 768"
        text content
        string source
    }

    THREAD ||--o{ MESSAGE : contains
    THREAD ||--o| RESOURCE : contextualizes

技术栈

本项目的工具选择在创新、开发速度与执行效率之间取得平衡。

层级 / 领域	技术	技术考量与角色
基础框架	Astro + React 19	Astro 提供高效路由和优化的渲染模型。React 管理交互群岛中的响应式状态。
样式与界面	Tailwind CSS v4, shadcn/ui, Framer Motion	实用程序设计系统、无耦合的无障碍组件以及高性能声明式动画。
3D 渲染	react-three-fiber, @react-three/postprocessing	WebGL 的声明式抽象，用于渲染与分析特征链接的复杂 3D 场景和视觉效果。
认知引擎	Mastra Framework (@mastra/core)	AI Agent 和工作流编排器。定义工具 Schema、内存管理和基础分析指令。
AI 模型	Google Gemini (2.0 Flash / 3.0 Pro)	负责视觉分析、高维嵌入生成和自然语言合成的基础引擎。
推理与 RAG	Mistral AI (OCR)	通过高级光学字符识别进行文档导入处理，以便在矢量化之前对 PDF 进行结构化。
数据持久化	LibSQL / Vercel Edge Config / Vercel Blob	LibSQL 以双重形式充当事务与矢量引擎。Edge Config 和 Blob 管理分布式配置与静态二进制文件。

架构影响

该设计的实现巩固了一个凝聚的生态系统，在这个生态系统中，多模态分析以集成的方式运行，并借助检索增强生成 (RAG) 架构提升了响应的保真度。通过将推理逻辑转移到自主 Agent 环境并将存储抽象到原生 Edge 嵌入式数据库，我将呈现层与生成式 AI 系统中常见的计算瓶颈隔离开来。结果是一个能够以可预测的方式扩展、并在各数据流中保持架构一致性的系统。