Skip to content

README.md

Latest commit

 

History

History
206 lines (154 loc) · 6.05 KB

README.md

File metadata and controls

206 lines (154 loc) · 6.05 KB
Raw

🤖 Agentic-Desktop-Pet

Agentic-Desktop-Pet

English | 简体中文

👋 介绍

🚀 🚀 🚀 下一代 Agentic 桌宠 = LLM + 记忆 + 情感 + RPG + Claude Code

Caution

development is still in progress, there are many bugs, please be patient

🔀 当前架构方向

当前仓库正在往 安全网关 + OpenClaw Agent 方向收敛：

  • 本项目负责公网入口和平台接入
  • 先做 Webhook 验签、幂等去重、moderation、routing、rate limit、事件清洗
  • 直接写入 OpenClaw workspace 中的共享 soul / memory 文件
  • 再把结构化后的安全事件转发给 OpenClaw
  • OpenClaw 负责 soul、memory、tool 调用和角色决策

这意味着现在更推荐把本项目理解为 Instagram / 社交入口网关，而不是最终的 Agent Runtime。

✨ 特性

  • 🧠 记忆系统：使用 Cognee
    • 知识图谱记忆: 将对话组织成语义图谱
    • 长期记忆: 跨会话持久存储
    • 语义搜索: 向量和图谱搜索进行记忆检索
    • 记忆丰富化: 自动提取实体和关系
  • 🛠️ 个人助手能力：实现类似 Claude Code 的功能,参考 learn-agent
    • 文件操作: 读取、创建、编辑本地文件
    • 代码执行: 运行代码和脚本
    • 任务管理: 创建和管理待办事项
    • 系统集成: 执行系统命令和自动化任务
  • mod 系统：轻松添加和切换不同桌宠主题
  • 💕 动态情感系统
    • 情感状态: 开心、悲伤、兴奋、无聊等基础情感
    • 时间衰减: 情感随时间自然衰减
    • 互动增强: 与用户交互增强情感连接
    • 行为影响: 情感状态影响 Agent 的回复风格和行为
  • ⚔️ RPG 属性系统
    • 基础属性: 智力、魅力、敏捷、体力等
    • 经验等级: 通过对话和任务获得经验升级
    • 技能系统: 解锁和升级各种能力
    • 好感度: 与用户的情感纽带等级

🏗️ 架构

Agentic-Desktop-Pet/
├── backend/                    # Python FastAPI 后端
│   ├── learn_agent/           # Agent 核心模块
│   │   ├── agent/             # Agent 实现
│   │   │   ├── agent.py       # 主 Agent 类
│   │   │   └── memory.py      # 记忆管理
│   │   ├── memory/            # 记忆系统 (Cognee)
│   │   │   └── cognee_manager.py
│   │   ├── emotion/           # 情感系统
│   │   │   └── emotion_engine.py
│   │   ├── rpg/               # RPG 属性系统
│   │   │   └── character.py
│   │   ├── llm/               # LLM 接口
│   │   └── tool/              # 工具集
│   │       ├── file_tool.py
│   │       ├── code_tool.py
│   │       └── todo_tool.py
│   ├── main.py                # FastAPI 服务入口
│   └── pyproject.toml
│
├── godot/                     # Godot 4.x 前端
│   ├── scenes/               # 场景文件
│   ├── scripts/              # GDScript 脚本
│   ├── themes/               # 桌宠主题
│   └── project.godot
│
├── docs/                     # 文档
└── CLAUDE.md                # Claude Code 指导

🚀 快速开始

前置要求

  • Python 3.13+
  • Godot 4.3+
  • LLM API (OpenAI / DeepSeek / Claude 等)

安装后端

cd backend
uv sync
# 配置环境变量
cp .env.example .env
# 编辑 .env 添加 API Key

启动服务

# 启动后端服务
uv run main.py
# 服务运行在 http://localhost:8000

运行前端

  1. 打开 Godot 4.3+
  2. 导入 godot/ 文件夹
  3. 点击运行按钮（或按 F5）

Caution

将主题文件.pck都需要放在和.exe的同级目录的themes/*.pck下面

📖 使用指南

⌨️ 快捷键

鼠标右键 角色区域弹出对话框 当焦点在角色窗口上，按 ESC 关闭软件

文件操作

"帮我读取 main.py 文件"
"创建一个新文件 hello.txt"
"帮我编辑 config.json"

任务管理

"创建一个待办：买牛奶"
"列出我的待办事项"
"标记第一个待办为完成"

查看状态

"你现在感觉怎么样？"
"你有多少经验值？"
"显示你的属性"

Instagram Gateway

当前后端已内置 Instagram 网关入口：

  • GET /webhook/instagram：Meta webhook 验证
  • POST /webhook/instagram：接收评论事件
  • GET /gateway/health：网关健康检查

网关会先执行：

  • 签名校验
  • 简单关键词审核
  • 单用户限流
  • 重复事件去重
  • 标准化事件封装

随后才会把安全事件转发给 OpenClaw 的 /v1/chat/completions。

🛣️ 开发路线图

详见 TODO.md

🐶 开发自己的桌宠

Wiki 教程

🤝 贡献

项目目前处于开发阶段（我有时间就会更新），还存在许多 Bug，我正着手修复。 欢迎任何贡献，即使细微。 添加角色素材等等

©️ 许可证

你可以使用项目中的任何代码片段，但不能直接将完整项目打包用于商业项目。 同时，需要注意项目中使用到的一些资产的版权信息。

🙏 致谢