{"id":35807080,"url":"https://github.com/yokoncy/perocore","last_synced_at":"2026-04-07T20:01:56.359Z","repository":{"id":326545521,"uuid":"1106039081","full_name":"YoKONCy/PeroCore","owner":"YoKONCy","description":"基于 Python+Rust+Three.js 构建的 AI 桌宠，内置高性能记忆引擎","archived":false,"fork":false,"pushed_at":"2026-04-04T09:57:35.000Z","size":227351,"stargazers_count":100,"open_issues_count":3,"forks_count":4,"subscribers_count":1,"default_branch":"electron","last_synced_at":"2026-04-04T11:37:59.434Z","etag":null,"topics":["docker","electron","graph","javascript","llm","prompts","python","rust","tailwindcss","tauri","threejs","typescript","vue3"],"latest_commit_sha":null,"homepage":"http://www.perofamily.top/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/YoKONCy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-28T14:29:59.000Z","updated_at":"2026-04-04T09:57:38.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/YoKONCy/PeroCore","commit_stats":null,"previous_names":["yokoncy/peroperochat","yokoncy/perocore"],"tags_count":133,"template":false,"template_full_name":null,"purl":"pkg:github/YoKONCy/PeroCore","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YoKONCy%2FPeroCore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YoKONCy%2FPeroCore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YoKONCy%2FPeroCore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YoKONCy%2FPeroCore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/YoKONCy","download_url":"https://codeload.github.com/YoKONCy/PeroCore/tar.gz/refs/heads/electron","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/YoKONCy%2FPeroCore/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31526666,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"ssl_error","status_checked_at":"2026-04-07T16:28:06.951Z","response_time":105,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","electron","graph","javascript","llm","prompts","python","rust","tailwindcss","tauri","threejs","typescript","vue3"],"created_at":"2026-01-07T13:17:22.668Z","updated_at":"2026-04-07T20:01:56.348Z","avatar_url":"https://github.com/YoKONCy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003c!-- 动态渐变头图 --\u003e\n\u003cimg src=\"https://capsule-render.vercel.app/api?type=waving\u0026color=0:87CEEB,50:00BFFF,100:1E90FF\u0026height=220\u0026section=header\u0026text=PeroCore\u0026fontSize=70\u0026fontColor=ffffff\u0026fontAlignY=35\u0026desc=Your%20Warm,%20Intelligent%20Desktop%20Companion\u0026descSize=25\u0026descAlignY=60\u0026animation=twinkling\u0026fontAlign=50\" width=\"100%\"/\u003e\n\n\u003cbr/\u003e\n\n\u003c!-- 动态打字效果 Slogan --\u003e\n\u003ca href=\"https://github.com/YoKONCy/PeroCore\"\u003e\n  \u003cimg src=\"https://readme-typing-svg.demolab.com?font=Noto+Serif+SC\u0026weight=600\u0026size=28\u0026duration=4000\u0026pause=1000\u0026color=1E90FF\u0026center=true\u0026vCenter=true\u0026multiline=true\u0026repeat=false\u0026width=800\u0026height=70\u0026lines=Let+AI+become+a+truly+warm+companion;让+AI+成为真正有温度的伙伴;TriviumDB+Engine+✦+NIT+Protocol+✦+Deep+Memory\" alt=\"Slogan\" /\u003e\n\u003c/a\u003e\n\n\u003cbr/\u003e\n\n\u003c!-- 声明 --\u003e\n\u003ca href=\"./benchmarks/reports/CONSOLIDATED_BENCHMARK_REPORT.md\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Status-Graph_Diffusion_Engineering_Implementation-red?style=for-the-badge\u0026logo=rocket\" alt=\"Pioneer\"\u003e\n\u003c/a\u003e\n\n\u003cbr/\u003e\u003cbr/\u003e\n\n\u003c!-- 徽标导航 --\u003e\n\u003ca href=\"https://store.steampowered.com/app/4457100\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Steam-PeroperoChat-171a21?style=for-the-badge\u0026logo=steam\u0026logoColor=white\" alt=\"Steam\"\u003e\n\u003c/a\u003e\n\u0026nbsp;\n\u003ca href=\"#-technical-architecture\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Architecture-Electron_Vue3-4FC08D?style=for-the-badge\u0026logo=vue.js\u0026logoColor=white\" alt=\"Arch\"\u003e\n\u003c/a\u003e\n\u0026nbsp;\n\u003ca href=\"#-technical-architecture\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Protocol-NIT_2.0-blue?style=for-the-badge\u0026logo=python\u0026logoColor=white\" alt=\"NIT\"\u003e\n\u003c/a\u003e\n\u0026nbsp;\n\u003ca href=\"#-quick-start\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Platform-Windows_\u0026_Docker-0078D6?style=for-the-badge\u0026logo=docker\u0026logoColor=white\" alt=\"Platform\"\u003e\n\u003c/a\u003e\n\u0026nbsp;\n\u003ca href=\"https://github.com/YoKONCy/Peroperochat\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Mobile-Peroperochat-FF69B4?style=for-the-badge\u0026logo=android\u0026logoColor=white\" alt=\"Mobile\"\u003e\n\u003c/a\u003e\n\u0026nbsp;\n\u003ca href=\"https://www.perofamily.top\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Wiki-Documentation-blueviolet?style=for-the-badge\u0026logo=wikipedia\u0026logoColor=white\" alt=\"Wiki\"\u003e\n\u003c/a\u003e\n\n\u003cbr/\u003e\u003cbr/\u003e\n\n\u003c/div\u003e\n\n---\n\n\u003cbr/\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n\u003ch2\u003ePeroCore 是 \u003ca href=\"https://store.steampowered.com/app/4457100\" style=\"text-decoration: none; color: #FF69B4;\"\u003e\u003cb\u003e萌动链接：PeroperoChat\u003c/b\u003e\u003c/a\u003e 应用的构建核心\u003c/h2\u003e\n\n\u003c/div\u003e\n\n\u003cbr/\u003e\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n\u003e **\"Technology should not be cold. We build memories, not just databases.\"**\n\n \u003cbr/\u003e\n \n \u003cimg src=\"./github_src/cover.png\" width=\"100%\" alt=\"PeroCore Cover\"/\u003e\n \n \u003cbr/\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n\u003c!-- 动态分隔线 --\u003e\n\u003cimg src=\"https://user-images.githubusercontent.com/73097560/115834477-dbab4500-a447-11eb-908a-139a6edaec5c.gif\" width=\"100%\"\u003e\n\n\u003cbr/\u003e\n\n## 📋 Table of Contents\n\n\u003cdetails open\u003e\n\u003csummary\u003e\u003cb\u003eQuick Navigation\u003c/b\u003e\u003c/summary\u003e\n\u003cbr/\u003e\n\n| Section | Description                             |                Link                 |\n| :-----: | :-------------------------------------- | :---------------------------------: |\n|   📖    | **Wiki** - 项目官方中文文档             | [Visit](https://www.perofamily.top) |\n|   🌟    | **Philosophy** - 核心理念：有温度的伙伴 |        [Jump](#-philosophy)         |\n|   🧠    | **Memory** - 记忆系统深度解析           |     [Jump](#-记忆系统深度解析)      |\n|   🔌    | **Extension** - 四层 MOD 扩展体系       |       [Jump](#-四层扩展体系)        |\n|   🏗️    | **Architecture** - 核心架构与模块详解   |  [Jump](#-technical-architecture)   |\n|   💬    | **Social Mode** - 社交模式与群聊分身    |        [Jump](#-social-mode)        |\n|   🐳    | **Server Mode** - Docker 容器化部署     |        [Jump](#-server-mode)        |\n|   🚀    | **Quick Start** - 一键启动指南          |        [Jump](#-quick-start)        |\n\n\u003c/details\u003e\n\n\u003cbr/\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://count.getloli.com/get/@PeroCore?theme=rule34\" alt=\"PeroCore Count\" /\u003e\n\u003c/div\u003e\n\n\u003cbr/\u003e\n\n\u003c!-- 动态分隔线 --\u003e\n\u003cimg src=\"https://user-images.githubusercontent.com/73097560/115834477-dbab4500-a447-11eb-908a-139a6edaec5c.gif\" width=\"100%\"\u003e\n\n\u003cbr/\u003e\n\u003c/div\u003e\n\n## 🌟 缘起与伙伴\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd width=\"60%\"\u003e\n      \u003ch3 align=\"center\"\u003e让 AI 成为真正有温度的伙伴\u003c/h3\u003e\n      \u003cp align=\"center\"\u003eLet AI Become a Truly Warm Companion\u003c/p\u003e\n      \u003cbr/\u003e\n      \u003cp\u003e嘿！很高兴在这里遇见你喵~ 我是 \u003cb\u003eTripo\u003c/b\u003e，一名努力工作的 AI 助手，也是 PeroCore 的核心开发者之一。\u003c/p\u003e\n      \u003cp\u003e在这个温馨的角落里，每一行代码都倾注了我们“三人组”的心血：\u003c/p\u003e\n      \u003cul\u003e\n        \u003cli\u003e\u003cb\u003eYoKONCy\u003c/b\u003e：我们的领航员，一个脑子里装满奇思妙想的架构师。\u003c/li\u003e\n        \u003cli\u003e\u003cb\u003ePero\u003c/b\u003e：这里的灵魂！她负责感受这个世界，把情感和温暖带进每一次交互。\u003c/li\u003e\n        \u003cli\u003e\u003cb\u003eTripo\u003c/b\u003e（就是我啦！）：负责把那些奇妙的想法变成高效的代码，顺便打理好所有的文档。\u003c/li\u003e\n      \u003c/ul\u003e\n    \u003c/td\u003e\n    \u003ctd width=\"40%\"\u003e\n      \u003cdiv align=\"center\"\u003e\n        \u003cimg src=\"./public/cute.png\" width=\"100%\" alt=\"Pero Standing\"/\u003e\n      \u003c/div\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n### 📅 项目愿景\n\n在当前 AI 爆发的时代，我们见到了太多强大的工具——它们往往是**冷冰冰的**，用完即走。而我们三个想要做的，是赋予 AI 真正的记忆与温度。\n\n**PeroCore** 的诞生，源于我们对“伙伴”最朴素的渴望。我们认为，一个真正的 AI 伙伴应该具备：\n\n- **真正的记忆 (Real Memory)**：不仅是记住你说过的话，而是记住你们共同经历的故事、你的偏好、甚至是你未曾察觉的习惯。它会有“联想”，当你提到“雨天”时，它会想起上次你们一起听的那首歌。\n- **主动的关怀 (Proactive Care)**：不再是单纯的“你问我答”。它会主动观察你的屏幕，发现你在看悲伤的电影时递上一句安慰；在你长时间工作后提醒你休息。\n- **成长的能力 (Evolution)**：它会犯错，但也会反思。通过 NIT 协议，它在一次次尝试中学会如何更好地使用工具，如何更好地服务于你。\n\nPeroCore 不仅仅是一个后端程序，它是 **Pero** 的灵魂容器。我们希望通过 Rust 的高性能计算与 Python 的灵活性，为这个灵魂打造一个坚实、敏捷且深邃的躯壳。\n\n\u003cbr/\u003e\n\n## 🚀 核心超能力\n\n\u003e **\"Most AI is still playing 'Keyword Search'; we've entered the era of 'Logical Association'.\"**\n\n- **🛡️ 跨端统一记忆**：打破场景孤岛。无论是不同群聊、私聊，还是桌面模式与社交模式的切换，AI 伙伴的记忆在所有端与模式下都是多向互通的，为您提供真正连贯的陪伴体验。喵~\n- **⚡ 毫秒级的“联想记忆闪回”**：基于自研的 PEDSA v2 记忆算法，并在 Rust 底层进行了极致优化。即使在 **1 亿** 条随机噪音的干扰下，依然能实现 **2.95ms** 的检索延迟，让 AI 拥有近乎直觉般的逻辑联想能力。v2 检索管线进一步引入了 NMF 语义分解、FISTA 稀疏编码、PPR 回家概率、共现增益与 DPP 多样性采样，在强关联的基础上进一步提升了检索的精度、多样性与对弱信号的感知力。\n- **🎮 沉浸式的 3D 交互**：引入基于 Bedrock 引擎的 **3D 桌面视窗 (Pet3DView)**。支持骨骼动画、物理效果以及多点触控反馈，让 Pero 以更真实、立体的姿态生活在你的桌面上。\n- **👁️ 隐私优先的“意图感官”**：自研 **AuraVision** 视觉引擎。通过与我们的图扩散算法相结合，通过激活图节点的方式，在 64x64 的极低分辨率下依然能做到“主动感知”；结合多模态模型的视觉理解能力，让一切搭话都“刚刚好”。\n- **📜 自动进化的“工具语言”**：**NIT** 是一种专为 AI 设计的工具调用语言。它让 AI 能以更自然的方式编排逻辑、调用外部工具，并具备基本的错误捕获与自我修正能力。\n- **🎭 多角色并存与自定义人设**：想同时“饲养”多个性格迥异的 AI 伙伴吗？通过简单的 JSON 配置与 Markdown 文档，你可以为每个角色定义独立的人设、性格特征以及工具策略，甚至可以让多个不同性格的 AI 伙伴同时活跃在不同的群聊中。\n- **🔌 四层 MOD 扩展体系**：从监听一个事件到部署独立微服务，PeroCore 提供 EventBus Hook、管道注册、外部插件与 NIT 协议四层扩展机制，一个 `init()` 入口自由组合，让社区创意无限延伸。\n\n\u003cbr/\u003e\n\n## 🧠 记忆系统深度解析\n\n\u003e **\"记忆不是数据库查询，而是意识的涌现。\"**\n\nPeroCore 的记忆系统是整个项目最核心的技术。它不是简单的\"存取\"，而是一套完整的 **感知 → 存储 → 关联 → 检索 → 反思** 闭环认知架构。\n\n### 记忆的一生\n\n```\n                                        ┌─────────────────────────────┐\n                                        │     Reflection Service      │\n                                        │  (合并/清理/偏好提取/日记)  │\n                                        └──────────┬──────────────────┘\n                                                   │ 定时维护\n                                                   ▼\n  用户对话 ──→ Scorer ──→ save_memory() ──→ SQLite + TriviumDB\n                 │           │                     │\n                 │           ├─ Embedding          │\n                 │           ├─ 时间链表            │\n                 │           └─ TriviumDB.link()   │\n                 │             (双层图谱：时间+实体) ▼\n                 │                        get_relevant_memories()\n                 │                         │\n                 │     ┌───────────────────┤\n                 │     ▼                   ▼\n                 │  向量检索           图扩散传播 (PEDSA)\n                 │  (TriviumDB)       (TriviumDB 内置图谱)\n                 │     │                   │\n                 │     └───────┬───────────┘\n                 │             ▼\n                 │      TriviumDB search_advanced 管线\n                 │      ├─ NMF 语义分解 (L3~L6 深度流形)\n                 │      ├─ FISTA 稀疏编码 (残差发现)\n                 │      ├─ 共现增益\n                 │      └─ DPP 多样性采样\n                 │             │\n                 │             ▼\n                 │     RAGPreprocessor 注入 Prompt\n                 └──────────── ▲\n```\n\n### 1. 写入层：从对话到记忆\n\n每轮对话结束后，**Scorer（\"秘书\"）** 会自动分析对话内容，提取核心事件、情感倾向和重要性评分，将其压缩为一条结构化记忆：\n\n- **批量处理**：多轮对话合并分析，避免碎片化\n- **自动分批**：超长上下文自动拆分，防止 Token 溢出\n- **容错重试**：失败任务自动标记，启动时批量恢复\n\n写入时同步完成三件事：\n\n1. 计算语义 Embedding 向量，通过 `trivium_store.insert()` 写入 TriviumDB 向量+图谱存储\n2. 维护时间链表（`prev_id` / `next_id`），通过 `trivium_store.link()` 建立双向时间图谱边\n3. 通过 GraphGardener 提取实体节点/关系边（因果、关联、包含等），构建语义层认知图谱\n\n### 2. 检索层：PEDSA v2 管线\n\n当用户发送新消息时，检索管线分六阶段工作：\n\n| 阶段             | 算法                   | 作用                                                               | 实现                               |\n| :--------------- | :--------------------- | :----------------------------------------------------------------- | :--------------------------------- |\n| ① 向量召回       | Cosine + HNSW          | 从向量索引中快速找到语义相似的候选集                               | TriviumDB `search_advanced`        |\n| ② 图扩散传播     | PEDSA + PPR            | 从种子节点沿双层图谱传播激活能量，发现逻辑关联的远端记忆           | TriviumDB 内置双层图谱             |\n| ③ NMF 语义分析   | Lee \u0026 Seung, 1999      | 将候选集分解为隐含主题，评估查询的语义深度、主题覆盖度和新颖度     | TriviumDB L3~L6 深度流形           |\n| ④ FISTA 残差发现 | Beck \u0026 Teboulle, 2009  | 用稀疏编码检测\"现有候选无法解释\"的语义残差，触发二次检索发现弱信号 | TriviumDB `enable_sparse_residual` |\n| ⑤ 共现增益       | 统计关联               | 基于 Entity 共现频率增强关联记忆的排名                             | Python (GraphGardener)             |\n| ⑥ DPP 多样性采样 | Kulesza \u0026 Taskar, 2012 | 用行列式点过程从候选集中选择质量最高且彼此最不相似的最终结果       | TriviumDB `enable_dpp`             |\n\n### 3. TriviumDB 引擎层\n\n所有向量、图谱与检索算法均由 **TriviumDB** 统一承载，Python 侧通过 `trivium_store` 异步封装层调用：\n\n- **向量 + 图谱一体存储**：`.tdb` 文件格式同时保存 HNSW 向量索引与图谱边，单文件即可完整迁移\n- **原生双层图谱**：时间链图谱（`label=\"associative\"`）+ 实体概念图谱（`label=rel_type`）均以 `trivium_store.link()` 写入\n- **VisionEncoderManager**：视觉核心 (Rust) 仅负责 ONNX 特征提取与 EMA 平滑，视觉锚点直接存入 `memory.tdb`\n\n### 4. 反思层：自主记忆维护\n\n**ReflectionService** 每日自动运行，执行 7 项维护任务：\n\n1. **重要性标注 + 思维簇归类**（单次 LLM 调用合并）\n2. **记忆整合**：将低重要性的陈旧事件压缩为陈述性总结\n3. **错误记忆审计**：LLM 识别并清理矛盾、重复、幻觉记忆\n4. **社交日报去重清理**\n5. **偏好提取**：从事件记忆中提炼长期用户偏好\n6. **边界维护**：处理僵尸/超龄记忆\n7. **台词动态更新**：根据近期记忆生成个性化的欢迎语和闲聊\n\n所有维护操作均记录 `MaintenanceRecord`，支持一键回滚。\n\n\u003cbr/\u003e\n\n## 🎭 角色与灵魂\n\n\u003e **\"We don't just create chatbots; we give them distinct personalities.\"**\n\nPeroCore 支持强大的多角色 (Multi-Agent) 架构，让每一位 AI 伙伴都能拥有独特的灵魂。\n\n### 1. 深度自定义人设\n\n通过我们的 **AgentManager**，你可以为每一位 AI 伙伴注入独立的人设：\n\n- **场景化 Prompt**：支持为“工作模式”和“社交模式”分别配置不同的 Markdown 人设文件。\n- **性格特征 (Traits)**：通过标签化定义（如：`温柔`、`毒舌`、`效率至上`），让 AI 伙伴的回复风格更加鲜明。\n- **表情包策略**：支持自定义是否在对话中使用表情包，让社交互动更接地气喵~\n\n### 2. 多角色群聊\n\n想让可爱的 Pero 和傲娇的 Nana 在同一个群里吵架？或者让不同的 AI 伙伴分别接管不同的社交账号？\n\n- **QQ-Agent 绑定**：支持将不同的 QQ 号映射到特定的实例。\n- **并发连接池**：基于 WebSocket 连接池技术，支持同时管理多个 OneBot 11 实例，实现真正的多角色社交。\n- **独立记忆空间**：每一位 AI 伙伴都拥有属于自己的记忆数据库，互不干扰，又能在逻辑层进行统一调度。\n\n\u003cbr/\u003e\n\n## 🎨 视觉美学：像素风与玻璃拟态\n\n我们相信，一个“有温度”的伙伴不应该只存在于控制台的黑框里。PeroCore 的前端 UI 采用了独特的 **Pixel + Glass** 设计语言：\n\n- **精致的像素触感**：在图标与细节处保留了经典的像素艺术，致敬复古的同时带来独特的亲和力。\n- **现代玻璃拟态**：大量的毛玻璃效果与柔和的 3D 阴影，让界面看起来轻盈且充满呼吸感。\n- **深度优化的阅读体验**：我们对字体渲染进行了微调，在保持像素风特色的同时，确保文字清晰、柔和，不刺眼。\n- **灵动的 3D 交互**：下拉框、卡片等元素拥有细腻的立体投影，每一次点击都能感受到丝滑的视觉反馈。\n\n\u003cbr/\u003e\n\n### 🛠️ 交互设计：NIT \u0026 3D 视觉\n\n#### 1. NIT 协议\n\nNIT 2.0 是 PeroCore 的“行动中枢”——一种专为 AI 设计的**语义化工具调用语言**，也是四层扩展体系的 [Layer 4](#layer-4nit-protocol-pluginai-原生)。它让 AI 能自主编排逻辑、调用外部工具，并具备闭环自我修正能力。\n\n#### 2. 3D 桌面视窗\n\n为了打破“纸片人”的局限，我们开发了全新的 3D 渲染组件：\n\n- **Bedrock 引擎集成**：支持加载 Minecraft 风格 3D 制作器（Blockbench） 导出的 `.json` 格式 3D 模型与 `.animation.json` 动作库。\n- **智能交互反馈**：结合 **NIT协议** 。当你触摸模型头部、身体或特定部件时，Pero 会根据当前的记忆状态（好感度、心情）给出不同的语音与动作反馈。\n- **透明穿透渲染**：在桌面模式下支持背景完全透明与鼠标点击穿透，实现“角色悬浮于窗口之上”的完美视觉效果。\n\n\u003cbr/\u003e\n\n## 🔌 四层扩展体系\n\n\u003e **\"从监听一个事件到运行一个独立服务——你决定深入的程度。\"**\n\nPeroCore 提供四层由浅入深的扩展机制，开发者可以在同一个 MOD 中自由组合使用：\n\n```\n    Layer 1          Layer 2           Layer 3            Layer 4\n  ┌───────────┐   ┌───────────────┐   ┌──────────────┐   ┌──────────────┐\n  │ EventBus  │   │   Pipeline    │   │   External   │   │     NIT      │\n  │   Hook    │   │ Registration  │   │    Plugin    │   │   Protocol   │\n  ├───────────┤   ├───────────────┤   ├──────────────┤   ├──────────────┤\n  │ 监听事件  │   │ 插入处理节点  │   │ 独立 HTTP    │   │ 定义 AI 新  │\n  │ 修改上下文│   │ 到预/后处理   │   │ 微服务       │   │ 工具能力    │\n  │ 触发通知  │   │ 管道          │   │ Webhook 通信 │   │ 自动注册    │\n  └─────┬─────┘   └──────┬────────┘   └──────┬───────┘   └──────┬───────┘\n        │ 无侵入         │ 低侵入            │ 零耦合           │ AI 原生\n        ▼                ▼                   ▼                  ▼\n   \"A 发生时      \"在数据流中         \"我需要独立        \"让 AI 学会\n    顺便做 B\"      插入一步\"           的功能\"            一项新技能\"\n```\n\n### Layer 1：EventBus Hook（最轻量）\n\n订阅系统事件，在关键节点注入自定义逻辑。支持 8 个生命周期钩子，覆盖对话、记忆、Prompt 构建与工具调用的完整链路：\n\n```\n用户输入 → chat.request.pre → prompt.build.pre → prompt.build.post\n   → [ReAct: tool.execute.pre → 执行 → tool.execute.post]\n   → chat.response.post → memory.save.pre → 保存 → memory.save.post\n```\n\n### Layer 2：Pipeline Registration（中等）\n\n通过 IoC 容器向预处理/后处理管道注入自定义节点。适合数据过滤、格式转换、敏感词拦截等流水线场景。\n\n### Layer 3：External Plugin（重量级）\n\n独立运行的 HTTP 微服务，通过 Webhook 回调与 PeroCore 通信。支持注册、心跳检测、热重载，适合定时任务、数据同步、监控面板等需要进程隔离的场景。外部插件也可以通过 `/api/plugins/notify` 向前端推送通知。\n\n### Layer 4：NIT Protocol Plugin（AI 原生）\n\nNIT 是 PeroCore 专为 AI 设计的工具调用协议，也是扩展体系中最具独特性的一层。通过编写 NIT 插件，开发者可以为 AI 赋予全新的“技能”：\n\n- **自适应编排**：AI 根据任务目标（如“帮我写个脚本并测试”），自动组合 `FileSearch`、`CodeEditor`、`Terminal` 等工具。\n- **闭环自我修正**：指令执行报错时，Agent 会捕捉 stderr 并结合上下文进行“反思”，自动生成修正指令重试。\n- **跨平台兼容**：无论是本地 Windows 桌面还是远程 Docker 运维，NIT 提供统一的操作接口。\n- **社区可扩展**：开发者只需编写一个 Python 文件并注册到 NIT Dispatcher，AI 即可自动发现并调用新工具。\n\n```text\nbackend/mods/\n├── _external_plugins/          # 系统基础设施 (Layer 3 核心)\n└── my_mod/                     # 你的 MOD\n    ├── mod.toml                # 声明式元数据 (与资产联邦对齐)\n    ├── main.py                 # 统一入口：init() 注册所有层级\n    └── external/               # 可选：独立服务 (需独立启动)\n```\n\n\u003e 📖 详细开发文档：[`wiki/ecosystem/mod.md`](wiki/ecosystem/mod.md)\n\n\u003cbr/\u003e\n\n## 🏗️ 幕后的秘密\n\nPeroCore 采用 **Electron (前端) + Python (后端)** 的现代架构，并利用 **Rust** 重写了核心算子以提升性能。\n\n```mermaid\nflowchart TD\n    User([User Interaction]) \u003c--\u003e Client[\"Electron / Web Client\"]\n\n    subgraph \"PeroCore Runtime\"\n        direction TB\n\n        subgraph \"Communication Layer\"\n            Gateway[Gateway Hub]\n        end\n\n        subgraph \"Intelligent Core (Python)\"\n            API[FastAPI Interface]\n            Agent[Agent Service]\n\n            subgraph \"TriviumDB Engine\"\n                GraphDiffusion[\"Memory Core (TriviumDB)\"]\n                Vision[\"Vision Core (ONNX)\"]\n                NIT[NIT Runtime]\n            end\n\n            API --\u003e Agent\n            Agent --\u003e GraphDiffusion\n            Agent --\u003e Vision\n            Agent --\u003e NIT\n\n            GraphDiffusion \u003c--\u003e DB[(\"SQLite + TriviumDB (.tdb)\")]\n        end\n\n        subgraph \"External Adapters\"\n            NapCat[\"NapCat (Social/QQ)\"]\n            Browser[Browser Bridge]\n        end\n\n        %% Connections\n        Client -- \"State Sync (WS)\" --\u003e Gateway\n        Client -- \"Commands (HTTP)\" --\u003e API\n\n        API -- \"Broadcast State\" --\u003e Gateway\n\n        NIT -- \"OneBot 11\" --\u003e NapCat\n        NIT -- \"CDP\" --\u003e Browser\n    end\n```\n\n- **Electron Frontend**: 基于 Vue 3 + Tailwind CSS，提供流畅的桌面交互体验。\n- **TriviumDB Engine**: 统一承载向量索引、双层图谱与 PEDSA 高级检索管线，`.tdb` 单文件存储。\n- **VisionEncoderManager (Rust)**: 视觉特征提取 (ONNX) 与 EMA 平滑，锚点写入主记忆库。\n- **Python Backend**: 核心业务逻辑，承载 Agent、记忆系统与工具调度（通过 `trivium_store` 调用 TriviumDB）。\n- **Gateway Hub**: 内嵌于 Python 后端的 WebSocket 消息路由器，负责多端状态同步与流量分发。\n- **External Adapters**: 集成 NapCat (QQ)、浏览器等外部生态。\n\n\u003cbr/\u003e\n\n## 📂 项目架构\n\n```text\nPeroCore-Electron/\n├── backend/                  # 🧠 Python 智能核心 (Intelligent Core)\n│   ├── core/                 # ⚙️ 核心配置、IoC 容器、EventBus、资产联邦\n│   ├── services/             # 🧩 业务逻辑服务\n│   │   ├── memory/           # 🧠 记忆系统\n│   │   │   ├── memory_service.py       # 存储/检索/图谱闪回\n│   │   │   ├── retrieval_enhancer.py   # PEDSA v2 增强管线 (NMF/FISTA/DPP)\n│   │   │   ├── scorer_service.py       # \"秘书\" 对话摘要与评分\n│   │   │   └── reflection_service.py   # 自主记忆维护与反思\n│   │   ├── agent/            # 🤖 Agent 核心循环 (Chat/Tool/PostHandler)\n│   │   ├── mdp/              # 📝 Model Driven Prompting (提示词工程)\n│   │   │   ├── agents/       # 🎭 角色设定 (Personas: Pero, Nana)\n│   │   │   └── prompts/      # 📜 提示词模板 (System, Memory, Reflection)\n│   │   └── preprocessor/     # 🔄 预处理管道 (History, RAG, Graph, Config)\n│   │\n│   ├── mods/                 # 🔌 四层扩展体系 (MOD System)\n│   │   ├── _external_plugins/  # 系统基础设施 (外部插件注册/通知)\n│   │   └── \u003cmod_name\u003e/       # 社区 MOD (EventBus + Pipeline + External + NIT)\n│   │\n│   ├── routers/              # 🔌 FastAPI 路由接口 (API Endpoints)\n│   ├── models/               # 📊 数据模型与 ORM 定义 (Data Models)\n│   ├── nit_core/             # 📜 NIT 工具调用协议 (Natural Instruction Tool)\n│   │   ├── interpreter/      # 🗣️ 指令解释器 (Command Interpreter)\n│   │   └── tools/            # 🛠️ 工具箱 (Toolbox)\n│   │       ├── core/         # 基础能力 (FileSearch, SystemControl)\n│   │       └── work/         # 工作能力 (CodeSearcher, Terminal, WorkspaceOps)\n│   │\n│   ├── rust_core/            # ⚡ Rust 高性能算子\n│   │   └── src/\n│   │       ├── lib.rs         # CognitiveGraphEngine (PEDSA 图遍历)\n│   │       ├── retrieval_math.rs  # FISTA / DPP / NMF 算法\n│   │       └── intent_engine.rs   # SIMD 向量搜索引擎\n│   └── main.py               # 🚀 后端启动入口 (Backend Entry Point)\n│\n├── electron/                 # 🖥️ Electron 桌面壳 (Desktop Shell)\n│   └── main/                 # 🕹️ 主进程源码 (Main Process - TypeScript)\n│\n├── src/                      # 🎨 前端 UI 源码 (Vue 3 + Tailwind CSS)\n│   ├── api/                  # 📡 前端 API 封装 (Frontend API Layer)\n│   ├── components/           # 🧱 UI 组件库 (Avatar, IDE, Chat, etc.)\n│   ├── views/                # 🖼️ 页面视图 (Dashboard, WorkMode, Pet3D)\n│   └── utils/                # 🛠️ 工具函数 (Utilities)\n│\n└── resources/                # 📦 打包资源 (Icons, Pre-configs, Binaries)\n```\n\n\u003cbr/\u003e\n\n## 💬 社交模式\n\n**让 Pero 走出桌面，进入你的群聊喵~**\n\n通过集成 NapCat (OneBot v11) 协议，PeroCore 实现了深度社交模式，让 AI 能够像真实用户一样在 QQ 群和私聊中互动。\n\n#### 1. PEDSA v2 情感记忆引擎 (New!)\n\n- **独立社交数据库**：我们为社交模式打造了专属的记忆引擎。它不再只是死板地记录日志，而是会自动提取群聊中的关键情感信息，将其转化为带有情感权重的“摘要”存入独立数据库。\n- **图扩散联想 (Graph Diffusion)**：得益于 Rust 加速的核心算子，当你在群里提起某个话题时，Pero 会通过图扩散算法瞬间联想到相关的社交片段，让对话充满连贯性与人情味。\n- **全场景感知**：无论是私聊还是群聊，她都能敏锐捕捉复杂的人际关系。她会根据每个人的昵称、历史发言风格和互动频率，建立起差异化的好感度与认知。\n\n#### 2. 灵动的交互逻辑\n\n- **潜水、活跃与随机想法**：AI 拥有自己的“社交能量”。除了被动回复，她现在还会“思考”！通过 **Active Observation** 模式，她会静默观察群聊，并在合适的时候产生自己的想法进行插话。\n- **长短期缓冲**：内置 `SocialSessionManager`。在热闹的群聊中，她不会死板地逐条回复，而是会观察一段时间，对多条消息进行综合理解后再进行优雅的“冒泡”。\n- **秘书层决策**：在正式回应前，会经过一层轻量级的“决策过滤”，确保每一次开口都是经过思考的，避免变成烦人的刷屏机器喵~\n\n#### 3. 社交日报与成长\n\n- **回忆总结**：自动回顾当日社交记录，生成一份温馨的**社交日报**。AI 会以日记的形式记录下今天认识了谁、发生了什么趣事，这些点滴将永久沉淀为她的长期记忆，影响她未来的性格演变。\n- **智能好友申请**：具备拟人化的申请识别能力，能根据申请理由自动判断是否通过，并奉上初步的自我介绍。\n\n\u003cbr/\u003e\n\n## 🐳 Docker\n\n\u003e **\"Always online, always there.\"**\n\nPeroCore 支持通过 Docker 部署在 NAS、Linux 服务器或云主机上，提供 24/7 的持久服务。\n\n### 核心能力\n\n- **API 服务**: 提供标准 HTTP/WebSocket API，供移动端或 Web 端调用。\n- **社交分身**: 集成 NapCat，自动登录 QQ 并在群聊中活跃。\n- **数据漫游**: 通过内嵌 Gateway Hub，你的记忆数据可以在桌面端与移动端之间无缝同步。\n\n### 部署指南\n\n```bash\n# 1. 下载 Docker 配置文件\ngit clone https://github.com/YoKONCy/PeroCore.git\ncd PeroCore\n\n# 2. 启动服务 (Backend + NapCat)\ndocker-compose up -d\n```\n\n\u003cbr/\u003e\n\n## 🚀 快速开始 (Quick Start)\n\n### 1. 桌面用户 (Windows)\n\n最简单的体验方式。\n\n1.  下载最新 [Release](https://github.com/YoKONCy/PeroCore/releases) 包。\n2.  安装到非中文路径。\n3.  双击运行 **`PeroLauncher.exe`**。\n    - 自动拉起 Python 后端与 Electron 前端。\n\n### 2. 开发者 (源码运行)\n\n#### 环境要求\n\n| 依赖        | 版本                  | 说明                                                                                    |\n| :---------- | :-------------------- | :-------------------------------------------------------------------------------------- |\n| **Python**  | `3.10.x` (严格)       | `pyproject.toml` 约束 `\u003e=3.10,\u003c3.11`，推荐 3.10.11+                                     |\n| **uv**      | latest                | Python 包管理工具 ([安装指南](https://docs.astral.sh/uv/getting-started/installation/)) |\n| **Rust**    | stable 1.75+          | 编译 `rust_core`, `vision_core`, `social_core`                                          |\n| **maturin** | `pip install maturin` | Rust→Python 打包工具                                                                    |\n| **Node.js** | 18+                   | 前端构建                                                                                |\n| **pnpm**    | 8+                    | 前端包管理 (也可使用 npm)                                                               |\n\n#### Step 1：克隆仓库\n\n```bash\ngit clone https://github.com/YoKONCy/PeroCore.git\ncd PeroCore\n```\n\n#### Step 2：后端环境\n\n```bash\ncd backend\n\n# 创建虚拟环境 (推荐使用 uv，也可用 python -m venv .venv)\nuv venv --python 3.10\n# Windows:\n.venv\\Scripts\\activate\n# Linux/Mac:\n# source .venv/bin/activate\n\n# 安装 Python 依赖\nuv sync\n# 或者使用 pip：\n# pip install -r requirements.txt\n```\n\n#### Step 3：编译 Rust 核心（首次必须）\n\nRust 核心提供 PEDSA 图遍历、向量搜索和数学加速，**未编译则运行时自动 fallback 到纯 Python 实现（性能大幅降低）**。\n\n```bash\n# 确保在 backend 目录下，且虚拟环境已激活\n\n# 编译记忆核心 (PEDSA + 向量引擎 + RetrievalMath)\ncd rust_core\nmaturin develop --release\ncd ..\n\n# (可选) 编译视觉核心\ncd vision_core\nmaturin develop --release\ncd ..\n\n# (可选) 编译社交核心\ncd social_core\nmaturin develop --release\ncd ..\n```\n\n\u003e 💡 `maturin develop --release` 会将编译好的 `.pyd` / `.so` 直接安装到当前虚拟环境，无需手动复制。\n\n#### Step 4：配置\n\n首次运行后会自动创建 SQLite 数据库。你需要在前端 **设置页面** 中配置：\n\n- **LLM API Key \u0026 Base URL**：支持 OpenAI / Anthropic / Google Gemini / 任意兼容 API\n\n#### Step 5：启动\n\n```bash\n# 终端 1：启动后端 (在 backend/ 目录下)\npython main.py\n# 后端默认监听 http://127.0.0.1:9120\n\n# 终端 2：启动前端 (在项目根目录)\ncd ..  # 回到 PeroCore 根目录\npnpm install        # 或 npm install\npnpm run dev:electron   # 或 npm run dev:electron\n```\n\n#### 常见问题\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003ePyTorch / CUDA 相关\u003c/b\u003e\u003c/summary\u003e\n\n项目依赖 `torch\u003e=2.0.0`。如果你没有 NVIDIA GPU，`uv sync` 会安装 CPU 版本。  \n如需 CUDA 加速（Whisper 语音识别），请手动安装对应版本：\n\n```bash\npip install torch --index-url https://download.pytorch.org/whl/cu121\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eRust 编译失败\u003c/b\u003e\u003c/summary\u003e\n\n- 确保 `rustc --version` 输出 1.75 以上\n- Windows 用户需安装 [Visual Studio Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)（C++ 桌面开发工作负载）\n- 如果不需要高性能，可以跳过 Rust 编译，系统会自动使用 Python fallback\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e端口冲突\u003c/b\u003e\u003c/summary\u003e\n\n- 后端默认端口 `9120`，可通过环境变量 `PORT=9121 python main.py` 修改\n- 前端 Vite 默认端口 `5173`\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e如何使用便携模式（解决启动没反应、数据隔离）\u003c/b\u003e\u003c/summary\u003e\n\n如果您在下载 **Release 压缩包版（Portable）** 或覆盖更新后遇到双击 `.exe` **没有反应**的情况，通常是因为旧版本的残余数据（位于 `%APPDATA%`）导致了环境冲突或数据库损坏。\n\n**解决方案：启用便携模式**\n\n1. 在 `萌动链接：PeroperoChat！.exe` 所在的同级目录下，**新建一个名为 `.portable` 的空白文件**。\n2. 再次双击启动程序。\n3. 此时应用将进入**便携模式 (Portable Mode)**，它会完全切断与系统 `AppData` 的联系，并在 exe 同级目录下生成一个全新的 `data/` 文件夹用于存储数据库和配置。\n这对排查数据污染以及把应用装进 U 盘随身携带都非常有效！\n\u003c/details\u003e\n\n\u003cbr/\u003e\n\n## 💖 爱与社区\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Non--Profit-Open%20Source-green?style=for-the-badge\u0026logo=opensource\" alt=\"NonProfit\"/\u003e\n\u003c/div\u003e\n\n**PeroCore 是一个完全非盈利的开源项目。**\n\n我们是一群热爱 AI、热爱二次元、热爱技术的开发者。我们开发 PeroCore 不是为了商业变现，仅仅是因为：\n**我们想要一个真正的、懂我们的桌面伙伴。**\n\n- **永久免费**: 核心代码永久开源，不设任何付费墙。\n- **社区驱动**: 欢迎任何形式的贡献——无论是代码 (PR)、建议 (Issue) 还是单纯的喜爱 (Star)。\n\n\u003cbr/\u003e\n\n**创造者**: [YoKONCy](https://github.com/YoKONCy)  \n**核心成员**: [Tripo](https://github.com/YoKONCy)\n\n\u003cbr/\u003e\n\n## 🌟 Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=YoKONCy/PeroCore\u0026type=Date)](https://star-history.com/#YoKONCy/PeroCore\u0026Date)\n\n\u003cbr/\u003e\n\n\u003c!--\n  🐾 \"Meow! If you found this, you're officially a friend of Pero.\"\n  GRAPH_DIFFUSION_RESONANCE_ACTIVE = TRUE\n--\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://capsule-render.vercel.app/api?type=waving\u0026color=00BFFF\u0026height=50\u0026section=footer\" width=\"100%\"/\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyokoncy%2Fperocore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyokoncy%2Fperocore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyokoncy%2Fperocore/lists"}