LIA-Assistant

<p align="center"> <img src="docs/assets/logo.png" alt="LIA — 你的生活. 你的AI. 你的规则." width="600" /> </p> <h1 align="center">LIA</h1> <p align="center"> <strong>具有 LangGraph 协调、人工参与、 企业级可观察性和完整国际化支持（6种语言）的智能多代理对话式助手</strong> </p> <p align="center"> <a href="https://lia.jeyswork.com/"><img src="https://img.shields.io/badge/🚀_试用_LIA-lia.jeyswork.com-0EA5E9?style=for-the-badge" alt="试用 LIA"></a> &nbsp;&nbsp; <a href="https://github.com/jgouviergmail/LIA-Assistant/stargazers"><img src="https://img.shields.io/github/stars/jgouviergmail/LIA-Assistant?style=for-the-badge&logo=github&label=星标&color=gold" alt="GitHub 星标"></a> </p> <p align="center"> <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.12%2B-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.12+"></a> <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-22%20LTS-5FA04E?style=flat-square&logo=nodedotjs&logoColor=white" alt="Node.js 22 LTS"></a> <a href="https://fastapi.tiangolo.com/"><img src="https://img.shields.io/badge/FastAPI-0.135.1-009688?style=flat-square&logo=fastapi&logoColor=white" alt="FastAPI"></a> <a href="https://nextjs.org/"><img src="https://img.shields.io/badge/Next.js-16-000000?style=flat-square&logo=nextdotjs&logoColor=white" alt="Next.js 16"></a> <a href="https://langchain-ai.github.io/langgraph/"><img src="https://img.shields.io/badge/LangGraph-1.1.2-FF6F00?style=flat-square" alt="LangGraph"></a> <a href="https://python.langchain.com/"><img src="https://img.shields.io/badge/LangChain-1.2.12-4B8BBE?style=flat-square" alt="LangChain"></a> <a href="#国际化-i18n--6种语言"><img src="https://img.shields.io/badge/i18n-6%20语言-E040FB?style=flat-square" alt="6种语言"></a> <a href="#许可证"><img src="https://img.shields.io/badge/许可证-AGPL--3.0-blue?style=flat-square" alt="许可证"></a> <a href="https://deepwiki.com/jgouviergmail/LIA-Assistant"><img src="https://deepwiki.com/badge.svg" alt="询问 DeepWiki"></a> </p> <p align="center"> <a href="#功能">功能</a> • <a href="#管理--监控">管理与监控</a> • <a href="#快速入门">快速入门</a> • <a href="#架构">架构</a> • <a href="#文档">文档</a> • <a href="#贡献">贡献</a> </p> <p align="center"> <strong>版本 1.14.4</strong> — 工具嵌入缓存、提供者无关的结构化输出、主动保护 — 2026年4月 </p> --- ## 目录 - [为什么选择LIA？](#为什么选择LIA？) - [在线试用LIA](#在线试用LIA) - [截图](#截图) - [功能](#功能) - [管理与监控](#管理--监控) - [快速入门](#快速入门) - [架构](#架构) - [技术](#技术) - [文档](#文档) - [测试](#测试) - [CI/CD](#cicd) - [性能](#性能) - [安全](#安全) - [贡献](#贡献) - [支持](#支持) - [许可证](#许可证) - [致谢](#致谢) --- ## 为什么选择LIA？ **LIA** 解决了当前AI助手的基本问题： | 问题 | LIA 解决方案 | |---------|---------------------| | **不可预测的LLM成本** | 实时代币跟踪、预算警报、93%优化 | | **不受控制的幻觉** | 人工参与（HITL）具有6个审批级别 | | **碎片化集成** | 统一的多领域编排（18个代理 + MCP + 子代理） | | **有限的可观察性** | 500+ Prometheus 指标、18个Grafana仪表盘、GeoIP分析 | | **不一致的性能** | Gemini嵌入-001具有不对称任务类型、混合评分的语义路由 | ### 主要用例 ``` 📅 "查找我明天的会议并向所有参与者发送提醒" 📧 "总结这周带有附件的未读邮件" 👥 "更新在初创公司工作的联系人的公司" 🔔 "提醒我在明天上午9点给Marie打电话，祝她生日快乐" ``` --- ## 在线试用LIA <p align="center"> <a href="https://lia.jeyswork.com/"><img src="https://img.shields.io/badge/🚀_试用_LIA-lia.jeyswork.com-0EA5E9?style=for-the-badge" alt="试用 LIA"></a> </p> LIA 作为托管服务在 **https://lia.jeyswork.com/** 上提供 — 无需安装。 > **封闭测试**: 目前仅限于有限数量的用户，由管理员酌情决定。要请求邀请，请联系 **liamyassistant@gmail.com**。 --- ## 截图 <p align="center"> <img src="docs/assets/screenshot-homepage.png" alt="仪表盘 — 首页，包含使用统计信息" width="800" /> <br /><em>仪表盘 — 首页，快速访问、使用统计信息和个性化问候</em> </p> <p align="center"> <img src="docs/assets/screenshot-chat.png" alt="聊天 — 多代理对话，带有调试面板" width="800" /> <br /><em>聊天 — 多代理对话，实时调试面板（右侧边栏）</em> </p> <details> <summary><strong>更多截图</strong></summary> <p align="center"> <img src="docs/assets/screenshot-settings-preferences.png" alt="设置 — 首选项（连接器、MCP、主题）" width="800" /> <br /><em>设置 — 首选项：连接器、MCP服务器、语言、时区和主题</em> </p> <p align="center"> <img src="docs/assets/screenshot-settings-features.png" alt="设置 — 功能（内存、兴趣、通知）" width="800" /> <br /><em>设置 — 功能：LIA样式、长期记忆、兴趣、主动通知、计划操作、子代理、通道</em> </p> <p align="center"> <img src="docs/assets/screenshot-settings-administration.png" alt="设置 — 管理面板" width="800" /> <br /><em>设置 — 管理：LLM配置、RAG空间、用户、连接器、定价、技能、语音、广播、调试</em> </p> <p align="center"> <img src="docs/assets/screenshot-settings-administration-oneclick.png" alt="设置 — 一键管理" width="800" /> <br /><em>管理 — 一键操作：每个管理操作都可以通过一次点击访问，无需技术技能</em> </p> <p align="center"> <img src="docs/assets/screenshot-settings-administration-llm.png" alt="设置 — LLM配置，支持多提供者" width="800" /> <br /><em>管理 — LLM配置：7个提供者（OpenAI、Anthropic、DeepSeek、Qwen、Perplexity、Ollama、Gemini），每个节点模型选择</em> </p> <p align="center"> <img src="docs/assets/screenshot-faq.png" alt="常见问题 — 可搜索的帮助中心" width="800" /> <br /><em>常见问题 — 可搜索的帮助中心，分类的问答部分</em> </p> </details> --- ## 功能 ### 多代理智能（LangGraph 1.x） - **19+ 专用代理**: 联系人、电子邮件、日历、驱动器、任务、提醒、地点、路线、天气、维基百科、Perplexity、Brave、网络搜索、网络获取、浏览器控制（带有渐进式截图流媒体）、智能家居（Philips Hue）、上下文、查询 + 动态MCP代理 - **MCP（模型上下文协议）**: 每用户外部工具服务器，支持OAuth 2.1、SSRF保护、结构化项目解析、MCP应用（交互式iframe小部件）、**迭代模式（ReAct）** 用于复杂服务器 — 专用代理读取文档然后正确调用工具 - **代理主动阶段**: 执行后跨域丰富 — 助手主动验证相关信息（例如，天气显示降雨 → 检查日历中的户外活动）。提示驱动， 只读，完全可配置 - **技能（agentskills.io）**: 专家指令的开放标准（SKILL.md），模型驱动的激活，渐进式披露（L1/L2/L3），沙盒脚本，市场导入，自动翻译的多语言描述，ZIP下载，管理员管理。**计划者技能保护**: 多领域确定性技能通过领域重叠检测（`_has_potential_skill_match`）保护免受错误积极早期澄清请求。**内置技能生成器**: 使用自然语言创建自定义技能 — 助手指导您完成需求分析、原型选择，并生成带有自动验证的准备导入的SKILL.md - **AI图像生成与编辑**: 根据文本提示生成图像（gpt-image-1），使用自然语言指令编辑现有图像。多提供者工厂架构，每用户质量/大小偏好，成本跟踪与DB缓存定价，基于附件的存储与级联清理 - **文件附件（图像、PDF）**: 客户端压缩上传，可配置的LLM视觉分析，PDF文本提取，严格的每用户隔离 - **语义路由**: 具有置信度评分的二进制分类（高> 0.85，中等> 0.65） - **多步骤规划**: 具有依赖和条件的ExecutionPlan DSL - **并行执行**: 异步汇总用于独立领域 - **智能上下文压缩**: 当代币计数超过动态阈值时，基于LLM的对话历史摘要（响应模型上下文窗口的比率）。保留标识符（UUID、URL、电子邮件）。`/resume` 命令用于手动触发。4个HITL安全条件在活动审批流程期间防止压缩 ### Psyche引擎 — 动态情感智能 - **5层心理状态**: 大五人格特质（永久）→ PAD情绪空间，14种情绪（小时）→ 16种离散情绪，带有交叉抑制（分钟）→ 4阶段关系进展（周）→ 好奇/参与驱动（每会话） - **展示，不要讲述**: 情绪和情绪微妙地影响词语选择、句子节奏、能量水平和关系基调 — 助手从不声明“我感觉快乐” - **情感头像**: 消息中带有彩色环的情绪响应表情符号。每个消息的历史头像都保留下来，以确保加载的一致性 - **进化意识**: 助手知道自上次消息以来其情绪如何变化，提供叙事连续性 - **4图表仪表盘**: 交互式重绘图，显示时间范围内的情绪（PAD）、情绪、关系和驱动（24小时至90天） - **教育指南**: 7节交互式文档，解释每个层级，并附有14种情绪和16种情感的描述表格 - **可定制的气质**: 表达性（斯多葛 → 高表达性）和稳定性（易变 → 非常稳定）滑块。软重置（仅情绪）和完整重置（所有内容），并具有明确的作用域描述 - **全局注入**: 行为指令被注入到所有面向用户的文本生成中（响应、通知、提醒、电子邮件、语音、子代理） - **自我报告**: 通过隐藏的`<psyche_eval/>`标签进行零成本情绪跟踪 — 无需额外的LLM调用 ### 语音：输入和输出 **语音输入（STT）** - **按住说话**: 按住麦克风按钮说话，松开按钮转录。针对移动设备优化（防长按CSS，触摸手势处理） - **唤醒词**: 说“OK Guy”激活免提录音。Sherpa-onnx WASM（Whisper Tiny.en）在浏览器中运行 — 唤醒词检测时不会将音频发送到外部 - **每用户语言**: STT转录使用用户的首选语言设置（Whisper Small，99+语言，完全离线） - **延迟优化**: 麦克风流重用，WebSocket预热，并行设置，缓存AudioWorklet（~50-100ms唤醒到录音） **语音输出（TTS）** | 模式 | 提供者 | 成本 | 质量 | |------|----------|------|---------| | **标准** | Edge TTS（Microsoft Neural） | 免费 | 高 | | **高清** | OpenAI TTS | $15-30/1M 字符 | 高级 | | **高清** | Gemini TTS | 可变 | 高级 | - **工厂模式**: 可互换的实现 - **管理员控制**: 通过系统设置控制模式 - **优雅降级**: 自动从高清降级到标准 ### FOR_EACH 迭代模式 ```python # DSL 语法 ExecutionStep( tool_name="send_email", for_each="$steps.get_contacts.contacts", for_each_max=10 ) ``` - **HITL 阈值**: ≥ 1 次突变触发强制审批 - **批量操作**: 发送电子邮件、更新联系人、批量删除 ### 智能服务（代币节省 89%） | 服务 | 角色 | 优化 | |---------|------|--------------| | QueryAnalyzerService | 路由决策 | LRU 缓存 | | SmartPlannerService | ExecutionPlan 生成 | 模式学习 | | SmartCatalogueService | 工具过滤 | 96% 代币减少 | | PlanPatternLearner | 贝叶斯学习 | 绕过 >90% 置信度 | ### Google 集成（OAuth 2.1 + PKCE） - **Gmail**: 搜索、读取、发送、回复、删除 - **联系人**: 模糊搜索、列表、详情（14+ 模式） - **日历**: 搜索、创建、更新事件 - **驱动器**: 搜索、文件/文件夹列表 - **任务**: 具有完成的完全CRUD ### Apple iCloud 集成 - **Apple Mail**: 搜索、读取、发送、回复、转发、删除（IMAP/SMTP） - **Apple 日历**: 搜索、创建、更新、删除事件（CalDAV） - **Apple 联系人**: 搜索、列表、创建、更新、删除（CardDAV） ### Microsoft 365 集成（OAuth 2.0 + PKCE） - **Outlook**: 搜索、读取、发送、回复、转发、删除（Graph API） - **日历**: 搜索、创建、更新、删除事件（calendarView） - **联系人**: 搜索、列表、创建、更新、删除 - **待办事项**: 具有完成的完全CRUD（任务列表 + 任务） - **多租户**: 个人账户（outlook.com）和商业账户（Azure AD）通过`tenant=common` ### 三向互斥 - 每个功能类别的提供者只能有一个 - 3个支持的提供者：Google、Apple、Microsoft - 激活新提供者会自动停用活动竞争者 ### 智能家居 — Philips Hue - **语音控制照明**: 通过自然语言打开/关闭灯光、调整亮度和颜色 - **房间和场景管理**: 控制整个房间或激活预定义场景（“调暗客厅”，“激活电影模式”） - **本地或云连接**: 通过本地网桥IP或Philips Hue云API连接 - **功能标志**: `PHILIPS_HUE_ENABLED=true`启用 ### 人工参与（HITL） | 类型 | 触发器 | 严重程度 | |------|---------|----------| | 计划审批 | 破坏性操作 | 关键 | | 澄清 | 检测到模糊性 | 警告 | | 草稿批评 | 电子邮件/事件审查 | 信息 | | 破坏确认 | 删除 ≥ 3 个项目 | 关键 | | FOR_EACH 确认 | 批量突变 | 警告 | | 修饰审查 | 审查和批准 AI 建议的对草稿内容的修改 | 信息 | ### 企业可观察性 - **Prometheus**: 500+ 自定义指标（代理、LLM、基础设施） - **Grafana**: 18个生产就绪的仪表盘 - **Langfuse**: 具有提示版本的LLM特定跟踪 - **Loki**: 结构化JSON日志，包含PII过滤 - **Tempo**: 分布式跨服务跟踪 ### 成本跟踪与计费 | 类型 | 跟踪 | 导出 | |------|----------|--------| | **LLM 代币** | 每节点、每提供者 | 详细CSV | | **Google API** | 每端点、每用户 | 详细CSV | | **聚合** | 每用户、每期间 | CSV摘要 | - **Google Maps Platform**: 地点、路线、地理编码、静态地图 - **动态定价**: 管理员UI进行定价CRUD - **上下文变量模式**: 无需显式参数传递的隐式跟踪 - **管理员CSV导出**: 代币使用情况、Google API使用情况、消费摘要（所有用户或按用户筛选） - **用户CSV导出**（v1.9.1）：设置 > 功能中的个人消费导出 — 用户仅导出他们自己的数据（服务端强制`user_id`，IDOR安全） ### 安全与合规 - **OAuth 2.1**: PKCE（S256），一次性状态令牌 - **BFF模式**: HTTP-only cookies，Redis会话，24小时TTL - **加密**: Fernet（凭证），bcrypt（密码） - **GDPR**: 自动PII过滤，假名化，个人数据导出（文章20数据可移植性） - **每用户使用限制**: 代币、消息和成本配额（期间/全局），具有5层深度防御强制执行，管理员杀死开关，带有WebSocket仪表的实时仪表盘。功能标志：`USAGE_LIMITS_ENABLED=true` ### MCP（模型上下文协议） - **每用户外部服务器**: 每个用户连接自己的MCP服务器（第三方工具） - **灵活认证**: 无、API密钥、Bearer令牌、OAuth 2.1（DCR + PKCE S256） - **增强安全**: HTTPS-only，SSRF防护（DNS解析 + IP封禁列表），加密凭证（Fernet） - **结构化项目解析**: 自动JSON数组检测为个别项目，带有McpResultCard HTML - **自动生成描述**: 发现的工具的LLM分析，生成智能路由优化的领域描述 - **每服务器速率限制**: Redis滑动窗口，每个服务器/工具 - **功能标志**: `MCP_USER_ENABLED=true`启用每用户 ### 多通道消息传递（Telegram） - **双向Telegram**: 通过Telegram与LIA的完整聊天（文本、语音、HITL） - **OTP链接**: 通过6位OTP码的安全账户到Telegram的链接（单次使用，5分钟TTL，防暴力保护） - **HITL内联键盘**: 6种语言直接在Telegram中批准/拒绝按钮 - **语音转文本**: Telegram语音消息到STT（Sherpa Whisper）到文本处理 - **主动通知**: 提醒和兴趣警报也通过Telegram发送 - **可扩展架构**: `BaseChannelSender`/`BaseChannelWebhookHandler`抽象，用于未来通道（Discord、WhatsApp） - **可观察性**: 12个专用Prometheus RED指标（延迟、错误、数量） - **功能标志**: `CHANNELS_ENABLED=true`启用 ... (rest of the translation remains the same) ### 自主心跳 — 主动通知 - **LLM驱动的主动性**: LIA主动告知您相关信息（天气、日历、兴趣） - **多源聚合**: 日历、天气（带有变化检测）、任务、兴趣、记忆、活动 — 并行获取 - **2阶段LLM决策**: 阶段1（结构化输出，成本效益模型）决定是否通知，阶段2重写用户个性和语言 - **智能防冗余**: 决策提示中的最近历史记录 + 跨类型去重（心跳 vs. 兴趣） - **用户控制**: 推送通知（FCM/Telegram）独立可切换，可配置每日最大次数（1-8），专用时间窗口（独立于兴趣） - **天气变化检测**: 雨开始/结束，温度下降，风警报 — 真正可行的通知 - **功能标志**: `HEARTBEAT_ENABLED=true`启用 ### 预定操作 - **重复操作**: 预定重复操作自动执行（发送电子邮件、检查、提醒） - **时区感知**: 正确处理每个用户的时区 - **重试逻辑**: 失败时自动重试并退避 - **自动禁用**: N次连续失败后自动停用 - **多通道集成**: 通过FCM、SSE和Telegram通知结果 - **功能标志**: `SCHEDULED_ACTIONS_ENABLED=true`启用 ### 子代理（F6） - **持久化专用代理**: 创建具有自定义指令、技能和LLM配置的子代理 - **只读V1**: 子代理执行研究、分析和综合 — 无写操作 - **基于模板的创建**: 预定义模板（研究助理、写作助理、数据分析师） - **对用户不可见**: 主助理协调子代理并自然呈现结果 - **令牌防护**: 每执行一次预算，每日预算，连续失败后自动禁用 - **功能标志**: `SUB_AGENTS_ENABLED=true`启用（默认:false） ### RAG 知识空间 - **个人知识库**: 创建空间，上传15+格式文档（PDF、DOCX、PPTX、XLSX、CSV、RTF、HTML、EPUB等），自动分段和嵌入 - **Google Drive 文件夹同步**: 将Google Drive文件夹链接到空间，实现文件向量化自动同步（新增、修改、删除）。功能标志：`RAG_SPACES_DRIVE_SYNC_ENABLED` - **混合搜索**: 语义相似性（pgvector cosine）+ BM25关键词匹配，支持可配置的alpha融合 - **响应增强**: 启用空间时，RAG上下文自动注入到助理响应中 - **完全成本透明**: 嵌入成本按文档和查询跟踪，在聊天气泡和仪表盘中可见 - **系统知识空间**: 内置FAQ知识库（119+问题，涵盖17个章节），从Markdown文件索引（`docs/knowledge/`）。`is_app_help_query`通过QueryAnalyzer检测，路由决策规则0覆盖，应用身份提示注入，延迟加载（对正常查询零开销）。启动时自动索引，基于SHA-256哈希的陈旧检测。管理员UI用于重新索引和陈旧监控。[ADR-058](./docs/architecture/ADR-058-System-RAG-Spaces.md) - **管理员重新索引**: 嵌入模型更改时进行完整重新索引，Redis互斥锁和自动维度ALTER。系统空间通过管理员API独立重新索引 - **可观察性**: 17个Prometheus指标（14个用户 + 3个系统），专用Grafana仪表盘 - **功能标志**: `RAG_SPACES_ENABLED=true`（用户空间），`RAG_SPACES_SYSTEM_ENABLED=true`（系统FAQ空间） ### 个人日记（Carnets de Bord） - **内省笔记本**: 助理维护主题日记（自我反思，用户观察，想法&分析，学习成果），以第一人称书写，颜色由其活跃个性决定 - **双触发器**: 会话后提取（fire-and-forget）+ 周期性整合（APScheduler）。助理自由决定写入内容 - **语义上下文注入**: 日记条目通过Gemini embedding-001相似性搜索注入到响应和计划器提示中，支持可配置的最低分数预过滤（`JOURNAL_CONTEXT_MIN_SCORE`）。结果包括分数 — LLM自主决定相关性 - **提示驱动生命周期**: 助理管理其自身日记 — 无硬编码自动存档。大小约束通过提示工程引导清理 - **心跳集成**: 日记条目通过动态二次查询丰富主动通知，查询基于聚合上下文（日历、天气、电子邮件）。心跳设置中可切换的源徽章 - **完全用户控制**: 启用/禁用（保留数据），整合切换，会话历史分析（带成本警告），4个可配置的数字设置，设置中完整的CRUD操作 - **反幻觉防护**: 三层防御LLM UUID幻觉 — 提示指导带有ID引用表，`field_validator`检查条目ID，提取和整合服务中的已知ID过滤 - **调试面板**: 专用“个人日记”部分显示注入指标（每个条目的分数和视觉条形，预算指示器）和后台提取结果（解析/应用的操作，创建/更新/删除徽章，主题，情绪）。通过补充`debug_metrics_update` SSE事件在后台任务完成后到达提取数据 - **成本透明**: 通过TrackingContext跟踪实际令牌成本，在设置和仪表盘中可见 - **功能标志**: `JOURNALS_ENABLED=false`（系统），用户级别在设置 > 功能中切换。[ADR-057](./docs/architecture/ADR-057-Personal-Journals.md) ### MCP 应用 — 交互式小部件 - **沙盒化iframe**: MCP应用程序在安全iframe中渲染（CSP + COEP `credentialless`） - **JSON-RPC桥**: iframe应用程序与聊天之间通过PostMessage JSON-RPC 2.0进行双向通信 - **Excalidraw迭代构建器**: 通过专用LLM调用（形状 + 箭头）进行意图驱动的图表生成，注入快捷键以确保格式准确性 - **`read_me`约定**: 暴露`read_me`工具的MCP服务器自动将其内容注入计划器提示中 - **自动生成描述**: 对发现的工具进行LLM分析，以优化路由的领域描述 - **应用专属工具**: 仅限iframe的`visibility: ["app"]`工具从LLM目录中过滤 ### 国际化（i18n）— 6种语言 LIA完全翻译为**6种语言**: 英语、法语、德语、西班牙语、意大利语和中文。 - **完整UI覆盖**: 所有界面、对话框、通知、错误消息、FAQ和登陆页面 - **HITL本地化**: 人机交互审批提示按语言适配 - **主动通知**: 心跳和提醒按用户语言发送 - **Telegram**: 内联键盘和消息本地化 - **技能**: 所有6种语言的自动翻译描述 - **react-i18next**: 基于命名空间的翻译，`locales/{lang}/translation.json` ### 登陆页面 - **展示页面**: 具有动画组件的响应式登陆页面（Hero、Features、Architecture、Security、Stats、Use Cases、How It Works、CTA） - **SEO & OpenGraph**: 动态生成的OG图像，用于社交媒体预览 - **认证重定向**: 如果已登录，则自动重定向到仪表盘 --- ## 管理与监控 LIA包含一个**功能齐全的管理界面** — 为操作员提供对系统的完全控制权和实时可见性，无需触及配置文件或数据库。 ### 管理仪表盘 一个涵盖系统各个运营方面的网页管理面板: | 章节 | 功能 | |---------|-------------| | **LLM配置** | 节点模型选择、提供商参数、温度/令牌限制、提示版本 | | **RAG知识空间** | 管理文档空间、嵌入配置、用户重新索引操作、系统知识空间（FAQ陈旧性、重新索引） | | **个性** | 创建和管理助理个性（语气、语言、行为规则） | | **用户管理** | 用户账户、角色、权限、连接器状态概览 | | **连接器管理** | Google/Apple/Microsoft OAuth状态、令牌健康状况、用户提供商激活 | | **技能管理** | 启用/禁用技能、编辑描述、在6种语言中翻译、删除 | | **MCP服务器** | 管理级MCP服务器配置、工具发现、领域描述 | | **LLM定价** | 每模型定价的CRUD（输入/输出/缓存令牌），用于成本跟踪 | | **Google API定价** | Google Maps Platform服务的每个端点定价配置 | | **语音设置** | TTS模式选择（标准/HD）、提供商配置 | | **广播** | 向所有用户或目标群组发送系统范围的通知 | | **调试设置** | 切换调试面板可见性、配置诊断详细程度（每个用户） | | **使用限制** | 每用户令牌/消息/成本配额（期间 + 全局），实时仪表盘，手动阻止/取消阻止，WebSocket实时更新 | | **消费导出** | 令牌使用、Google API使用和按用户/期间聚合的消费CSV导出 | ### 实时调试面板 一个多部分调试面板嵌入在聊天界面中，提供对对话过程的实时洞察: | 类别 | 部分 | |----------|----------| | **意图分析** | 意图分类、领域检测、路由决策（带有置信度分数） | | **执行管道** | 计划器输出、执行波、工具调用（输入/输出）、ForEach分析 | | **LLM内部** | LLM管道（所有LLM + 嵌入调用的按时间顺序协调）、LLM调用详细信息（模型、令牌、延迟）、令牌预算跟踪、Google API调用 | | **上下文和内存** | 上下文解析、内存注入、知识增强、RAG注入（分数）、兴趣配置文件 | | **智能机制** | 智能机制（缓存命中、模式学习、语义扩展） | | **生命周期** | 完整的请求生命周期，带有每个阶段的时间分解 | > 调试面板专为**开发者和操作员**设计，用于诊断问题、优化提示，并在实时情况下了解代理的决策过程 — 无需外部工具或日志访问。 --- ## 快速开始 ### 先决条件 | 软件 | 版本 | 必要 | |----------|---------|----------| | Python | 3.12+ | 是 | | Node.js | 22 LTS | 是 | | Docker | 24+ | 是 | | pnpm | 10+ | 是 | | [Task](https://taskfile.dev/) | 3+ | 是（构建工具） | 所有命令均在`Taskfile.yml`中定义。快速开始：`task setup`然后`task dev`. ### 快速设置（5分钟） ```bash # 1. 克隆仓库 git clone https://github.com/jgouviergmail/LIA-Assistant.git cd LIA-Assistant # 2. 配置环境 cp .env.example .env # 使用您的API密钥编辑 # 3. 完整设置（后端 + 前端 + git钩子） task setup # 4. 启动所有服务（API + Web + PostgreSQL + Redis + 可观察性） task dev ``` <details> <summary><strong>手动设置（无Task）</strong></summary> ```bash # 1. 启动基础设施 docker compose up -d postgres redis prometheus grafana # 2. 后端设置 cd apps/api python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -r requirements.txt cp ../../.env.example .env # 配置您的API密钥 # 3. 数据库迁移 alembic upgrade head # 4. 前端设置 cd ../web pnpm install # 5. 启动服务 # 终端1 - 后端： cd apps/api && uvicorn src.main:app --reload --port 8000 # 终端2 - 前端： cd apps/web && pnpm dev ``` </details> ### 开发URL | 服务 | URL | 凭证 | |---------|-----|-------------| | 前端 | http://localhost:3000 | — | | API文档 | http://localhost:8000/docs | — | | Grafana | http://localhost:3001 | admin/admin | | Prometheus | http://localhost:9090 | — | ### 最小配置（.env） ```bash # 数据库 DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/lia REDIS_URL=redis://localhost:6379/0 # 安全（必需 - 生产环境中更改） SECRET_KEY=change-me-in-production-use-openssl-rand-base64-32 FERNET_KEY=your-fernet-key-here # LLM提供商API密钥通过管理员界面配置 # （设置 > 管理 > LLM配置） # 至少需要一个提供商（通常是OpenAI）。 # Google OAuth（可选） GOOGLE_CLIENT_ID=... GOOGLE_CLIENT_SECRET=... # 功能标志（可选，默认禁用） MCP_ENABLED=false # 管理MCP服务器 MCP_USER_ENABLED=false # 用户MCP（需要MCP_ENABLED） CHANNELS_ENABLED=false # 多通道消息（Telegram） HEARTBEAT_ENABLED=false # 自主主动通知 SCHEDULED_ACTIONS_ENABLED=false # 定期预定操作 SUB_AGENTS_ENABLED=false # 持久化专用子代理 SKILLS_ENABLED=false # 技能系统（agentskills.io标准） RAG_SPACES_ENABLED=true # RAG知识空间（文档上传和检索） FCM_NOTIFICATIONS_ENABLED=false # Firebase推送通知 ``` --- ## 架构 ### 概述 生产环境目标包括通过多架构Docker构建（`linux/amd64,linux/arm64`）支持树莓派（ARM64）。 ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ 前端（Next.js 16 + React 19） │ │ 聊天界面 • 设置 • i18n（6种语言）• SSE流媒体 • 语音模式 │ └─────────────────────────────┬───────────────────────────────────────────┘ │ HTTP-only cookies （session_id, 24h TTL） ┌─────────────────────────────┴───────────────────────────────────────────┐ │ 后端（FastAPI + LangGraph 1.x） │ │ │ │ ┌────────────────────────────────────────────────────────────────────┐ │ │ │ LangGraph 多代理编排 │ │ │ │ │ │ │ │ 路由器 → 查询分析器 → 计划器 → 审批门 → 协调器 │ │ │ │ ↓ ↓ │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ │ │ 联系人 │ 电子邮件 │ 日历 │ Google Drive │ 任务 │ 提醒 │ │ │ │ │ │ 地点 │ 路线 │ 天气 │ 维基百科 │ Perplexity │ │ │ │ │ │ Brave │ 网络搜索 │ 网络获取 │ 浏览器 │ 上下文 │ 查询│ │ │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ ↓ │ │ │ │ MCP工具（每用户外部服务器） │ │ │ │ ↓ │ │ │ │ 响应节点（合成） │ │ │ └────────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────────────────┐│ │ │ 领域服务：身份验证、用户、连接器、RAG、语音、技能... ││ │ └─────────────────────────────────────────────────────────────────────┘│ │ │ │ ┌─────────────────────────────────────────────────────────────────────┐│ │ │ 基础设施：Redis（缓存）• PostgreSQL（检查点）• ││ │ │ MCP客户端池 • Prometheus（指标）• Langfuse（跟踪） ││ │ └─────────────────────────────────────────────────────────────────────┘│ └──────────────────────────────────────────────────────────────────────────┘ ``` ### 对话流程 ```mermaid graph TD A[用户消息] --> B[路由节点] B -->|对话| C[响应节点] B -->|可操作| D[计划器节点] D --> E[语义验证器] E --> F{审批门} F -->|批准| G[任务编排器] F -->|拒绝子代理| D F -->|拒绝| C G --> H[领域代理 + 工具] G --> L[子代理委托] H --> I[外部API] L --> M[子代理管道] M --> G I --> G G --> C C --> J[SSE流] ``` 代码结构（DDD） ``` apps/api/src/ ├── core/ # 模块化配置（9个模块） │ ├── config/ # 每个领域的设置 │ ├── constants.py # 全局常量 │ └── bootstrap.py # 初始化函数 ├── domains/ # 有限上下文（DDD） │ ├── agents/ # LangGraph节点、服务、工具 │ ├── nodes/ # 7个节点（路由器、规划器...） │ │/ #服务，HITL │ │ ├── tools/ # 领域特定工具 │ │ration/ # 执行计划，并行执行器 │ ├── auth # JWT，会话，OAuth │ ├── connectors/ # Google + Apple + Microsoft客户端，提供程序解析│ ├── conversations/ # 会话CRUD记录 │ ├── google_api/ #定价和用量跟踪 ├── rag_spaces/ RAG知识上传，嵌入，系统FAQ） │ ├── user_mcp/ # 每个用户的MCP服务器（CRUD，OAuth，域名路由） │ ├── voice/ # TTS工厂，STT，唤醒词 │ ├── skills/ # 技能系统（agentskills.io标准） │ ├── sub_agents/ # 持久化专用子代理（F6） │ ├── interests/ # 兴趣学习系统 ├── heartbeat/ # 自主心跳（主动通知） │ ├── channels/ # 多传递（Telegram） │ ├── reminders/ # 提醒和通知调度 │ ├── scheduled_actions/ # 循环调度操作 │ ├── journals/ # 个人日记（内省笔记本） │ └── users/ # 用户管理 └── infrastructure/ # 跨领域关注点 ├── cache/ # Redis会话，LLM缓存 ├── llm/ # 工厂，提供程序，嵌入 ├── mcp/ # MCP，身份验证，安全，工具适配器 ├── browser/ # Playwright会话池，CD访问性 _limiting/ # 分布式速率限制 └── observability # 指标，跟踪 ``` ### 主要设计模式 **工具系统层架构）**工具分为五个可组合的层构建：`[ClientType]`基础，具有OAuth自动`@connector_tool`（指标+速率限制+上下文保存的元装饰格式化器（领域特定的结果归一化），Manifest` +构建器（具有语义关键字的声明式声明），以及器（动态自省）。每个工具的样从~150行减少到~8行（％）。基于类别的速率限制：读取（20/分钟），写入（5/分钟），昂贵（2/5分钟）。 **领域分类法** — 每个领域都是一个声明性的`DomainConfig`（代理，`result_key`，`related_domains`，优先级，可路由性）。`DOMAIN_REGISTRY`是被智能目录（过滤），语义扩展（相邻领域）和主动阶段（结构预过滤）所消耗的单一真实来源。 **数据注册表** — 一个`InMemoryStore`将工具结果与消息历史记录解耦。通过`@auto_save_context`，结果在每个节点的消息窗口（5/10/20回合）中存活，跨步骤引用（`$steps.X.field`）针对注册表解析 — 这使得在不丢失工具输出上下文的情况下激进窗口化是可行的。 **语义验证器** — 在HITL批准之前，专用LLM（与规划器不同）会针对四类14种问题类型检查计划：关键（幻觉能力，幽灵依赖），语义（基数不匹配，范围溢出），安全（危险的模糊性）和FOR_EACH特定验证。 **自适应重新规划器** — 在执行失败时，基于规则的分析器分类失败模式并选择恢复策略。在**恐慌模式**下，智能目录扩展到所有工具进行重试，解决领域过滤过于激进的情况。 **连接器抽象** — Python协议实现在Google，Apple和Microsoft提供程序之间透明切换。规范化器将提供程序特定的响应转换为统一的领域模型。`ProviderResolver`保证每个功能类别只有一个提供程序（电子邮件，日历，联系人，任务）。 **错误架构** — 所有工具返回具有`ToolErrorCode`枚举（18+类型）和``标志的`ToolResponse`/`ToolErrorModel`。API侧集中异常引发器替换原始HTTPException。 **功能标志** — 每个可选子系统都受`{FEATURE}_ENABLED`标志控制，在启动，路由连接和节点输入时检查（即时短路）。 > 完整技术细节：[LIA工作原理？](https://lia.jeysw/how) — 25节架构指南 --- ## 技术 ### 后端 | 技术 | 版本 | | --- | --- | --- | | Python | 3.12+ | 主要运行时 | | FastAPI | 0.135.1 | REST API + SSE框架 | | LangGraph | 1.1.2 | 多代理编排 | | LangChain | 1.2.12 | LLM抽象+工具 | | SQLAlchemy | 2.0.48异步ORM | | Alembic | 最新 | 数据库迁移 | | PostgreSQL | 16 + pgvector | 数据库+向量搜索 | | Redis | 7.3.0 | 缓存，会话，速率限制 | | Pydantic | 2.12.5 | 验证+序列化 | | structlog | 最新 | 结构化JSON日志记录 | | openai | 1.0+ | LLM提供程序 | | Edge TTS | 6.1+ | 语音合成（免费） | | mcp | 1.9+模型上下文协议SDK（可流式HTTP） | | Docker | 24+ | 容器化（多架构amd64/arm64） | ### 前端 | 技术 | 版本 | 角色 | | --- | --- | --- | | Node.js | 22 LTS | JavaScript运行时 | | Next.js | 16.1.7 | React框架 | | React | 19.2.4 | UI库 | | TypeScript | 5.9.3 | 类型安全性 | | TailwindCSS | 4.2.1 | 样式 | | TanStack Query | 5.90.16 | 服务器状态管理 | | react-i18next | 16.5.1 | i18n（6种语言） | | Radix UI | 最新 | 可访问的UI基元 | **响应式设计**：针对桌面，平板电脑和智能手机进行了全面优化。自适应布局，触摸友好型交互和移动优先的组件可在任何设备上提供无缝体验。 ### 支持的LLM提供程序 | 提供程序 | 模型 | 用例 | | --- | --- | --- | | OpenAI | GPT-5.4，GPT-5.4-mini，GPT-5.2-5.1，GPT-5，GPT-5-mini/nano，GPT-4.1，GPT-4.1-mini/nano，GPT-4o，o1，o3-mini | 主要（提示缓存，推理） | | Anthropic | Claude Opus 4.6/4.5/4，Claude Sonnet 4.6/4.5/4，Claude Haiku 4.5 | 替代（扩展思维） | | Google | Gemini 3.1/3/2.5 Pro，Gemini 3/2.5/2.0 Flash | 多模态 | | DeepSeek | deepseek-chat（V3），deepseek-reasoner（R1） | 成本效益推理 | | Perplexity | sonar-small/large-128k-online | Web增强响应 | | Qwen | qwen3-max，qwen3.5-plus，qwen3.5-flash |+工具+视觉（阿里云） | | Ollama | 任意本地模型（动态发现） | 零API成本，自我托管 | ### 可 | 技术 | 角色 | | --- | --- | | Prometheus |+指标 | | Grafana | 18个仪表盘 | | Loki | 聚合日志 | | Tempo | 分布 | | Langfuse | LLM可观察性 | | structlog | 结构化JSON日志 | --- ## 文档 ### 主要文档 | 文档 | 描述 | | --- | --- | | [GETTING_STARTED.md](./docs/GETTING_STARTED.md) | 详细的安装指南 | | [ARCHIT](./docs/ARCHITECTURE.md) | 完整系统架构 | | [INDEX.md](./docs/INDEX.md) | 完整文档地图（190+文档） | ### 技术文档 | 领域 || --- | --- | | **代理和LLM** | [GRAPH_AND_AGENTS_ARCHITECTURE/technical/GRAPH_AND_AGENTS_ARCHITECTURE.md) • [](./docs/technical/PLANNER.md)SEMANTICER](./docs/SEMANTICER.md) | HITL**HITL/technical/HIT) • [PLANL_STREAMING](./docs/PLAN_HITL_VALIDATION.md) | | **语音**VOICE](./docs/VOICE • [VOICEdocs/technicalICE_MODE.md) | | **内存**LONG_TERM_MEMORY/technical/LERM_MEMORY.md)MEMORY_RESdocs/technical/M_RESOLUTION.md| **MCP [MCP_INTEGRATION](./docs/technical/MCP_INTEGRATION.md) • [GUIDE_MCP_INTEGRATION](./docs/guides/GUIDE_MCP_INTEGRATION.md) | | **心跳** | [HEARTBEAT_AUTONOME](./docs/technical/HEARTBEAT_AUTONOME.md) • [_HEARTBEdocs/guides/GUIDE_HEARTBEAT_PROACTIVE_NOTIFICATIONS.md) **通道**CHANNELS_INTEGRdocs/technical/CHANNELS_INTEGRATION.md) • [GUIDE_TELEGRAM](./docsUIDE_TELEGRAM_INTEGRATION.md| **计划 | [SCHEDULECTIONS](./docs/technical/SCHEDULED_ACTIONS.md) •E_SCHEDULED_ACTIONS](./docs/guidesE_SCHEDULED.md) | | **技能** | [SKILLS_INTEGRATION](./docs/technical/SKTEGRATION.md) | | **子 | [SUB_AGdocs/technical/SENTS.md) **RAG | [GUIDE_SPACES](.//GUIDE_RAG_SPACES.md) • [ADR-055](./docs/architecture/ADR-RAG-Spaces.md) •-058](./docs/architecture/ADR-058-System-RAG-Spaces | | **浏览器控制** | [_CONTROL](./docs/technical/BROWSER_CONTROL.md [ADR-059/architecture/ADR-Browser) | | **记** | [JOURNALS](./docs/technical/JOUR.md) • [057](./docs/architecture/ADR-057-Pournals.md) | | **LLM提供程序** | [LLM_PROVIDERS](./docs/technical/LLM_PROVIDERS.md) | | **CI | [CI_CD](./docs/technical/CI_CD.md) | 安全** | [](./docs/technical/SECURITY.md) •UTH](./docs/technical/OAUTH.md [RATE_LIMITING](./docs/technical/RATE_LIMITING.md) | | **可观察性** | [OBSERVABILITY_AGENTS](./docs/technical/OBSERVABILITY_AGENTS.md) • [METRICS_REFERENCE](./docs/technical/METRICS_REFERENCE | | **成本跟踪** | [LLM_PRICING_MANAGEMENT](./docs/technicalM_PRICING_MANAGEMENT.md) •OGLE_API_TRACKING](./docs/technicalOGLE_API_TRACKING | ### | 指南 | 描述 | | --- | --- | | [_DEVELOPPEMENT/guides/GUIDVELOPPEMENT | 完整开发 | | [_AGENT_CREATION](./docsUIDEATION.md) | 如何创建新代理 | GUIDE_TOOL](./docs/guides/GUIDE_TOOL_CRE) | 如何工具 | |E_TESTING](./docs/guides/GUIDE.md) |（2,300+测试） | | [GUIDE_DEBUdocs/guides/GUIDE_DEBUGGING.md) | LangGraph和 | ### 架构（ADR）个ADR记录主要架构决策： --007：节点复杂性的服务层docs/architecture/007-Service-Layer-Pattern-For-Complexity.md) - [ADR-048：工具路由器](./itecture/ADR-emantic-Router.md) ADR-051：提醒和通知系统](./itecture/ADR-Reminder-.md) - [查看所有ADR](./docs/ADR_INDEX.md) --- ## 测试 ```cd apps/api # 单元测试（快速，~30秒 tests/unit -# 集成PostgreSQL） pytest tests -v Graph代理测试 /agents -# 完整 pytest --cov=src --cov-report=html -v # 报告：htmlcov/index.html ``` ### 统计 | 指标 | 值 | | --- | --- | | 总测试数 | 2,300+ | | 可重用夹具 | 170| 目标 | | | CI工作流 | CI，安全， | --- ## LIA使用两层质量门控：一个**本地预**（限暂存一个**Git CI管道**（全面，在每次推送/PRmain`时### 管道``` 预提交（ GitHub ===================== .bak文件 后端 lintuff + BlackPy） 机 前端 lintLint + TypeRuff + MyPy 单元测试 +率（43％单元测试 （i18lembic，.env.example，模式模式检测 烟雾测试18n密钥同步 机密扫描（Gitleaks） A迁移冲突 ───── 完整性 流（每周） + TypeScript检查 CodeQL（ JS） 依赖审计（pip-audit + pnpm audit Trivy文件 SBOM``` ###实践 | 实现 | | --- | | **SHA固定操作** | 所有GitHub操作都通过提交SHA固定（安全） | 最小特权 `permissions: read`在流上 | |保护** |（外部贡献7个状态禁止强制推送 **Dependabot**周更新pip，npm，Docker，次要/分组 | |提交/CI** | CI涵盖预提交的所有内容（和更多） | | **覆盖率阈值** | 强制在CI中执行43％的最低覆盖率 | ### 工作流 | 工作流 | 触发 | 作业 | | --- | --- | --- **CI** (`ci.yml`) |到`mainPR | 作业：lint，代码卫生构建，机 | | **安全security.yml`)，每周计划 | CodeQL，，TrSBOM | 发布** (`release | 标签`` | Docker多架构构建+推送cr.io）， | > 完整详细信息：[CI/CD文档](./docs/technical/CI_CD.md## 性能 关键指标95） | | 值 | SLO | | --- | --- | --- API延迟 | | < 500| TTFT（首个代币时间） | | < 500| 路由延迟800毫秒 | <秒 | | 规划 2.5 < 5秒 OpenAI嵌入 |-200毫秒 | <毫秒 | | 代（窗口化）93％ | >％ | | 上下文压缩节省 | ~60压缩 | — | 实施的优化 消息窗口化**节点的5/10回合 - **上下文：LLM总结（动态阈响应模型上下文窗口，可COMPACTION_*`设置配置） - ****：OpenAIthropic（90扣） - **嵌入**：gemini-001，具有不对类型（多语言 **并行执行asyncio.gather领域 - **（1）**操作（而非O（N）SCAN） -池**：htt连接 --- ##### 合规性 标准 | 状态 | | --- | | GDPR | PII过滤，数据最小化 | | OWASP十大漏洞 | XSS，SQL注入，CSRF保护 | | 提示注入 | 外部内容包装（`<external_content>`安全标记） | | OAuth 2.1 | 强制PKCE | ### 报告漏洞 **请勿为安全漏洞创建GitHub问题。** 发送电子 **liamyassistant**，内容包括： 漏洞描述 -步骤 - 潜在影响 我们会在48回复。 --- ## 我们欢迎所有请参阅我们的指南](./CONTRIBUT) 开始。 ###者快速入门 # 1.并克隆 https://github.com-USERNAME/LIA.git cd LAssistant # 分支 gitb feature/my-feature 3. （后端 + 前 git钩子） task# 4.测试 task test:unit:fast 5. 提交提交） git commit "feat(agents weather forecast agent" 6. 推送并 git push/my-feature ``` 贡献类型 - 错误修复 - 新功能 - 文档 - 测试 i18n翻译（支持的语言） -优化 ###- **Python** + Ruff + My严格） - ****：ESLintttier - **： [约定提交://www.conventional.org/) - ****：>= 在CI中强制- **预提交**：通过``安装 — 在文件上运行lint 测试 - **：所有PR必须个状态检查才能参见 [CI/CDd)） 支持 ### 获取| 频道 | | | --- | [GitHubhttps://github.comouviergmail/LAssistant/issues) |功能请求 | |Hub讨论](https://github.com/jgouv/LIA-Assistant) | 问题，| liamyassistant | 一般查询 | - [完整文档](./docs/INDEX.md) - [实用指南](./docs/guides/) - [操作手册](./docs/runbooks/) --- ## 许可证 该项目根据 **GNU Affero通用公共许可证v3.0（AGPL-3.0）** 许可。 [LICENSE](./ 获取详细信息。 为无法遵守AGPL-0条款的组织许可证。请联系li@gmail.com获取详细信息。 --- ## 致谢 源技术 本项目建立在优秀的开源技术之上： **后端与基础设施** - Python - 主要运行时 - FastAPI - 现代异步Web框架 - LangGraph - 多智能体编排 - LangChain - LLM抽象与工具 - SQLAlchemy - 异步对象关系映射 - Pydantic - 数据验证与设置 - Alembic - 数据库迁移 - PostgreSQL + pgvector - 数据库与向量搜索 - Redis - 缓存、会话、速率限制 - Google Gemini Embeddings - 用于多语言语义搜索的gemini-embedding-001 - Edge TTS - 免费的神经语音合成 - structlog结构化JSON日志记录 - Docker - 容器化与多架构构建 **前端** - Node.js - JavaScript运行时 - Next.js - React框架 - React - 用户界面库 - TypeScript - 类型安全 - TailwindCSS - 实用优先的样式设计 - Radix UI - 可访问的用户界面基元 - TanStack Query - 服务器状态管理 - react-i18next - 国际化（6种语言） **可观测性** - Prometheus - 指标与警报 - Grafana -盘与可视化 - Loki - 日志聚合 - Tempo - 分布式追踪 - Langfuse - LLM可观测性与提示管理 ### 灵感来源 - OpenAI Assistants API - Anthropic Claude - 模型上下文协议 --- <p align="center"> <strong>LIA</strong> — 新一代智能对话助手 </p> <p align="center"> 使用Python、Node.js、FastAPI、LangGraph和Next.js构建 </p> <p align="center"> <="#lia">返回顶部</a> </p>