lucianhanga/personal-ai

# PersonalAI [](https://github.com/lucianhanga/personal-ai/actions/workflows/ci.yml) [](./LICENSE) [](./docs/architecture/adr/0012-langgraph-orchestration.md) [](#principles) [](#principles) [](./SECURITY.md) [](https://www.conventionalcommits.org/) PersonalAI 是**可扩展的**（工具 + MCP）、**结构化输出优先的**（schema 无处不在）、 **开源优先的**（仅限经过验证的来源）以及**安全优先的**（对工具、文件、prompt、模型输出和 MCP server 实行零信任）。 ## 快速开始（本地聊天） ``` make setup make db # local Postgres + pgvector (docker compose) # 终端 1 — backend（local mode = zero-login；multi-tenancy 以 tenant #1 运行） PERSONALAI_DEFAULT_MODEL=qwen3:14b make run-backend # 终端 2 — UI -> http://localhost:5173（local mode 下无需 token） pnpm --filter @personalai/ui dev ``` 需要安装本地的 [Ollama](https://ollama.com) 并拉取一个模型。`app_mode` 默认为 **local** （零登录开发模式）。如需多租户的 **hosted** 模式（真实登录 + cookie + CSRF），请设置 `PERSONALAI_APP_MODE=hosted`。完整指南：[docs/guides/local-chat.md](./docs/guides/local-chat.md)； 所有环境变量均可在 [`.env.example`](./.env.example) 中找到。 ## 原则 | 原则 | 含义 | |---|---| | **本地优先，云端可选** | 所有核心功能均可离线运行；任何出口流量都是可选的、按提供程序划分且可见的。 | | **结构化输出优先** | 所有 agent ↔ backend ↔ tool ↔ UI 消息均经过 schema 验证。 | | **零信任 I/O** | 将文件、prompt、模型输出、工具结果和 MCP server 均视为对抗性输入。 | | **最小权限 + 明确同意** | 工具默认关闭；授权是严格的、限定作用域的且可撤销的。 | | **验证来源** | 每个依赖项都有已知且信誉良好的维护者、许可证、成熟度以及记录在案的理由。 | | **可移植性** | 在稳定的接口背后切换本地 ↔ 远程模型和存储后端。 | | **可审计与可复现** | 仅追加的审计日志、SBOM、签名发行版，以及在可行情况下的可复现构建。 | ## 高层架构 这是一个**单主机模块化单体架构**（六边形架构：端口和适配器 + 注册表），前端连接隔离的运行时环境 —— 本地模型 server 和**沙箱化的**工具/MCP server —— 并将安全、审计和机密管理作为横切层。 ``` Clients (Tauri UI + MV3 extension, loopback) │ API Gateway ── Auth/Settings │ API Gateway ── Auth (IdentityProvider) + per-request tenant context (SecurityContext) │ Conversation ── Agent Orchestration (single-agent loop; opt-in LangGraph multi-agent graph, ADR-0012) ── Structured-Output Validation │ │ File Ingestion Tool/MCP Gateway ── Security Engine ── Sandbox (container/gVisor/WASM) │ │ Retrieval (RAG) Model Abstraction/Router ── Ollama | llama.cpp | vLLM | remote (LiteLLM, opt-in) │ Storage: PostgreSQL + pgvector · object store · secrets vault · append-only audit ``` 完整图表与原由：[架构报告](./docs/architecture/PersonalAI-Architecture-Research.md)。 ## 精选技术栈（计划中，已审查） | 领域 | 选择 | 许可证 | |---|---|---| | Backend | Python + FastAPI (模块化单体架构) | — | | UI | Tauri shell + web SPA (React/Svelte) | MIT/Apache-2.0 | | 本地模型 runtime | Ollama (默认) · llama.cpp · vLLM | MIT / MIT / Apache-2.0 | | 远程提供程序网关 | LiteLLM (可选) | MIT | | Agent 编排 | 单 agent 循环 + 基于现有衔接机制的可选 LangGraph 多 agent 图 (ADR-0012) | MIT | | 认证 / 多租户 | argon2id + server 会话 + Postgres RLS (ADR-0010) | — | | Schema | Pydantic / Zod + JSON Schema | MIT | | 存储 / RAG | PostgreSQL + pgvector | PostgreSQL License | | 文档摄取 | Apache Tika / IBM Docling | Apache-2.0 | | 音频 | faster-whisper (STT) / Piper (TTS) | MIT | **完整且持续维护的**来源登记表（维护者、许可证、成熟度、安全注释、 理由、替代方案）位于 [`docs/supply-chain/SUPPLY-CHAIN.md`](./docs/supply-chain/SUPPLY-CHAIN.md)。 ## 路线图（宏观愿景） `Foundation → Talk → Know → Act → Reason → Sense → Reach → (Connect) → Harden` | 里程碑 | 交付内容 | 状态 | |---|---|---| | **M0** | 骨架 + 契约（定义所有端口，CI/SBOM/签名骨架） | 已完成 | | **M1–M2** | 本地聊天 (Ollama) → 提供程序可移植性 | 已完成 | | **M3** | 文件 + 向量 RAG (pgvector) | 已完成 | | **M4** | 记忆（短期摘要 + 长期、语义记忆） | 已完成 | | **M5** | 工具/MCP 网关 + 沙箱 | 已完成 | | **M6** | 单 agent 循环 + 工具（流式推理 + 回答） | 已完成 | | **M7** | MCP 插入/拔出 + 验证 | 已完成 | | **身份认证 + 多租户** | 常驻认证 + Postgres RLS 租户隔离 (ADR-0010) | 已完成 | | **M8 前置强化** | 审计驱动的修复（run_turn 衔接点，unit-of-work，租户测试，...） | 已完成 | | **M8.1** | 基于 LangGraph 的多 agent 图（规划器 → 研究员 → 评审员）+ 持久化人工拦截 (ADR-0012) | 已完成 | | **M8.2** | 分层验证阶梯 + 有界 schema 修复 + 精度模式 | 下一步 | | **M9** | 多模态（视觉 / STT / TTS） | 计划中 | | **M10** | 浏览器扩展 (MV3) | 计划中 | | **M11** | KAG / 图记忆（M4 的图升级） | 计划中 | | **M12** | 强化、签名、打包、文档 | 计划中 | 详情：[§22 模块化实施路线图](./docs/architecture/PersonalAI-Architecture-Research.md#22-modular-implementation-roadmap)。 ## 文档 | 文档 | 用途 | |---|---| | [架构报告](./docs/architecture/PersonalAI-Architecture-Research.md) | 完整的研究 + 高层架构（共 22 节）。 | | [ADR](./docs/architecture/adr/) | 架构决策记录。 | | [威胁模型](./docs/architecture/THREAT-MODEL.md) | 信任边界与威胁 (v1)。 | | [安全策略](./SECURITY.md) | 报告与安全态势。 | | [依赖项策略](./docs/policies/DEPENDENCY-POLICY.md) | 来源、验证、SBOM、扫描规则。 | | [供应链登记表](./docs/supply-chain/SUPPLY-CHAIN.md) | 包含每个依赖项及其创建者的动态清单。 | | [入职 / 开发指南](./docs/ONBOARDING.md) | 如何在此仓库中工作。 | | [贡献指南](./CONTRIBUTING.md) | GitHub flow、分支管理、提交规范、PR。 | | [更新日志](./CHANGELOG.md) | 版本控制策略（`VERSION` 中的 semver）以及各版本发布历史。 | ## 贡献与工作流 本仓库采用 **GitHub flow**：`main` 分支受保护；所有工作都在短生命周期的 功能分支上进行，并通过 pull request 合并。详见 [CONTRIBUTING.md](./CONTRIBUTING.md)。 ## 许可证 [Apache-2.0](./LICENSE) © 2026 Lucian Hanga.

标签：AI助手, AI风险缓解, 多智能体, 开源大模型, 本地部署, 测试用例, 结构化输出, 逆向工具