皮平：用于自主智能体的数字实体框架

欢迎来到皮平——一个灵活、开源的框架，用于创建一个数字“实体”，它能够：

• 学习了解您的目标/任务以及角色个性。
• 通过 API 密钥或经由 Composio 的 OAuth 流程连接各种工具或 API 来执行任务。
• 为实现您的目标而动态创建并测试新的“活动”。
• 管理记忆系统以跟踪过去的行动及其结果。
• 提供 Web UI 以便于快速上手和配置，或者如果您更喜欢终端工作流，则可使用 CLI 向导。

---

目录

1. 概述
2. 功能与亮点
3. 先决条件
4. 文件夹结构
5. 快速入门
   • 分支并克隆
   • 安装依赖项
   • 上手与配置
   • 启动智能体
6. 上手流程：CLI 对比 Web UI
   • 核心步骤（底层相同）
   • LLM 设置
   • 目标与角色
   • 通过 Composio 或 API 密钥添加技能
   • 多种 LLM 模型支持
7. 默认活动
8. 使用 Web UI
   • 配置角色与约束条件
   • 通过 OAuth 连接工具（Composio）
   • 启动并监控智能体
9. 使用 CLI
   • 重新运行上手向导
   • 从终端启动智能体
10. 为 Solana-AgentKit 创建新技能（手动示例）
11. 为何保留 AI/Web UI 默认设置？
12. 扩展与创建其他自定义活动
13. 记忆、状态与活动选择
14. 停止或暂停智能体
15. 贡献代码
16. 许可证

---

概述

该项目旨在帮助您快速搭建一个自我改进、基于 LLM 的数字实体，该实体能够：

• 向您询问目标和角色细节。
• 集成各类工具以执行实际任务（例如发推文、在 Solana 上部署代币、生成图像或进行网页抓取）。
• 在持续或定时循环中运行，挑选或创建新活动来达成您的目标。
• 将日志存储在内存中（短期和长期）。
• 能够通过即时重写或生成 Python 代码来自适应并创建新的活动！

您可以选择从终端运行所有操作，也可以通过基于 Web 的界面来完成。两种方式的底层初始化过程是相同的，因此您可以根据自己的习惯选择适合的方式。

---

功能与亮点

• 灵活的上手流程：

  • CLI 向导或 Web UI 流程均可收集必要信息，无需重复操作。
  • 在您提供至少一个 LLM API 密钥（或本地配置）以及基本的角色设定之前，系统不会允许开始运行。

• 多种 LLM 模型支持：

  • 您可以提供一个或多个 LLM API 密钥（OpenAI、GPT4All 或您自定义的服务提供商）。
  • 可以为不同任务分配不同的模型，例如代码生成、日常分析或活动选择。

• Composio：

  • 基于 OAuth 的网关，支持 250 多种工具（Twitter、Slack、Google 等）。
  • 内置流程可快速从已连接的应用程序中添加新“技能”。

• 自定义技能：

  • 您可以轻松添加自己的技能，例如 solana-agent-kit、stable diffusion 或 Node.js 微服务。
  • 默认配置可以帮助您手动添加未使用 Composio 的工具的 API 密钥。

• 默认活动：

  • 包括分析每日日志、头脑风暴新活动、生成 .py 文件等活动。

• 可配置的约束条件：

  • 例如“每小时不超过 5 条推文”、“每月最多创建一次新代币”。

• 记忆系统与状态追踪：

  • 该实体会“记住”过去的行动，能够对其进行反思，并更新自身的状态（精力、情绪等）。

---

先决条件

• 推荐使用 Python 3.9 或更高版本。
• 需要一个 GitHub 账号（用于分支）。
• 如果您希望通过 OAuth 进行技能连接，建议获取 Composio 开发者密钥（可选）。

---

文件夹结构

.
├─ activities/
│   ├─ activity_daily_thought.py
│   ├─ activity_suggest_new_activities.py
│   ├─ activity_build_or_update.py
│   └─ ... # 更多内置或动态生成的活动
├─ skills/
│   ├─ skill_lite_llm.py           # 用于本地或远程 LLM 使用
│   ├─ skill_chat.py               # 示例：OpenAI Chat
│   ├─ skill_solana_agent.py       # 我们将手动创建此技能（示例）
│   ├─ skill_x_api.py              # 用于 API 技能
│   └─ skill_web_scraping.py       # 用于从网上抓取信息
|
├─ framework/
│   ├─ main.py                     # 核心 DigitalBeing 类，运行主循环
│   ├─ activity_selector.py        # 混合 LLM + 确定性选择
│   ├─ memory.py                   # 短期/长期记忆管理
│   ├─ state.py                    # 跟踪精力、情绪等
│   ├─ shared_data.py              # 线程安全的数据，供跨活动使用
│   └─ ...
├─ config/
│   ├─ character_config.json       # 存储实体名称/个性的信息
│   ├─ activity_constraints.json   # 速率限制、技能要求、冷却时间
│   ├─ skills_config.json          # 已启用技能及所需 API 密钥
│   └─ ...
├─ server/
│   ├─ server.py                   # Web UI + WebSocket 服务器
│   └─ static/                     # HTML/CSS/JS 用于前端
├─ tools/
│   └─ onboard.py                  # 基于 CLI 的上手向导
├─ requirements.txt
├─ __init__.py
├─ server.py
└─ README.md                       # 本文档

---

快速入门

1. 分支并克隆

在 GitHub 上分叉本仓库。

克隆您的分支：

git clone https://github.com/<your-username>/pippin-draft.git
cd pippin-draft

2. 安装依赖项（如果您使用 GitHub Codespaces 或提供的开发容器，则可跳过此步骤）

首先，如果尚未安装 UV 包管理器，请执行以下命令：

curl -LsSf https://astral.sh/uv/install.sh | sh

然后创建并激活虚拟环境：

# 创建并激活虚拟环境
uv venv
source .venv/bin/activate  # 在 Unix/MacOS 上
# 或
.venv\Scripts\activate     # 在 Windows 上

安装项目依赖项：

uv pip install -r requirements.txt

3. 上手与配置

进入项目目录：

cd my_digital_being

复制 config_sample 文件夹。

cp -r config_sample config

您可以选择以下任一方式：

• CLI： python -m tools.onboard
• Web UI： python -m server，然后在浏览器中打开 http://localhost:8000 并按照上手提示操作。

无论哪种方式，您都将被引导完成以下步骤：

1. 选择主要的 LLM 提供商并提供至少一个 API 密钥（或本地模型路径）。
2. 定义角色的名称、个性、目标、约束条件等。
3. 可选地连接 Composio 或手动输入额外技能所需的 API 密钥。
4. 确保至少有一项技能已完全配置，以便您可以启动智能体。

4. 启动智能体

• CLI： python -m framework.main
• Web UI： 上手完成后，会出现“开始”按钮，单击即可运行主循环。

---

引导流程：命令行 vs. Web 界面

两种流程都依赖于共享逻辑，用于检查以下内容：

• 您是否已命名角色并设定了目标。
• 是否至少配置了一个 LLM 技能。
• （可选）如果您希望使用高级功能，是否已配置 Composio 或其他技能的凭据。

如果这些条件未满足，代理将无法启动。这样可以确保不会出现配置不完整的使用情况。

---

核心步骤（底层实现相同）

LLM 设置

选择一个或多个模型。示例：

• GPT4All 用于代码生成
• GPT-3.5 用于快速查询
• GPT-4 用于推理

提供必要的 API 密钥或本地模型路径。如果使用本地的 GPT4All 或其他离线 LLM，系统同样可以处理。

目标与角色

指定：

• 名称：例如，“Optimus Mentis”
• 性格：例如，“乐于助人、好奇心强、略带幽默感”
• 目标：例如，主要任务、次要目标
• 约束：例如，“每月不得创建新代币超过一次”

（存储在 character_config.json 和 activity_constraints.json 中。）

通过 Composio 或 API 密钥添加技能

如果您希望您的智能体能够执行以下操作，推荐使用 Composio：

• 在 Twitter、Slack 或 Gmail 上发布内容，而无需手动处理每个 OAuth 授权。
• 自动获取每个应用的操作作为“动态技能”。

对于那些无法与 Composio 集成的工具，或者您更倾向于直接使用 API 的情况，也可以通过 API 密钥来实现：

• 使用 OPENAI_API_KEY 或 STABLE_DIFFUSION_KEY 配置 image_generation 技能
• 使用私钥环境变量配置 solana_agent 技能

引导流程会提示您输入这些密钥。您可以提供，也可以跳过可选部分。

多 LLM 模型支持

系统可以同时处理多个 LLM，例如：

• 活动选择器 => 使用廉价的 GPT-3.5
• 代码生成 => 使用 GPT-4
• 每日分析 => 使用本地的 GPT4All

您只需在 skills_config.json 中启用正确的技能，并可选择性地指定每个功能使用的模型。默认情况下，所有功能都会使用同一个技能。

---

默认活动

1. AnalyzeDailyActivity

   • 读取最近的记忆，调用您选择的 LLM，记录一段简短的反思。

2. SuggestNewActivities

   • 根据您的目标和约束，头脑风暴新的任务或扩展方向。

3. BuildOrUpdateActivity

   • 接收建议，调用 LLM 生成 .py 代码，写入 activities/ 目录，并动态加载。

---

使用 Web 界面

配置角色与约束

1. 在引导或配置界面中，填写名称、性格、目标和约束。
2. 点击保存。

通过 OAuth 连接工具（Composio）

1. 在集成或技能选项卡中，选择一个应用（例如 Twitter）。
2. 通过 Composio 完成 OAuth 授权。
3. 确认状态显示为“已连接”。

启动并监控代理

• 一切设置完成后，点击“开始”。
• 实时日志会显示当前选择的活动、内存使用情况以及新代码的生成情况。
• 您可以随时暂停或停止。

---

使用命令行

重新运行引导向导

python my_digital_being/tools/onboard.py

（它会重新检查您的配置，允许您更新或跳过某些步骤。）

从终端启动代理

python -m framework.main

日志会显示在您的控制台中。按 Ctrl+C 可以停止。

---

为 Solana-AgentKit 创建新技能（手动示例）

如果您希望您的 AI 智能体能够部署代币或与 Solana 区块链交互，可以选择依赖 Composio（如果支持），或者手动添加一个封装 Solana-AgentKit 的技能。下面是一个最小示例，展示如何在 skills/ 目录下创建新技能、配置密钥，并在活动中引用该技能。

1. 技能创建 (skill_solana_agent.py)

在 skills/skill_solana_agent.py 中，您可以编写如下内容：

"""
Solana AgentKit 技能
此技能封装了 solana-agent-kit，用于代币部署或其他链上操作。
"""
import logging
import os
from typing import Optional
from framework.api_management import api_manager

logger = logging.getLogger(__name__)

class SolanaAgentSkill:
    def __init__(self):
        self.skill_name = "solana_agent"
        self.required_api_keys = ["SOLANA_PRIVATE_KEY"]
        # 将所需密钥注册到系统中
        api_manager.register_required_keys(self.skill_name, self.required_api_keys)

        self.private_key: Optional[str] = None

    async def initialize(self) -> bool:
        """
        从秘密存储中获取 SOLANA_PRIVATE_KEY（环境变量或 .env 文件等）。
        您还可以选择性地测试连接或运行一笔最小交易。
        """
        try：
            self.private_key = await api_manager.get_api_key(self.skill_name, "SOLANA_PRIVATE_KEY")
            if not self.private_key:
                logger.error("Solana 私钥未配置")
                return False

            # 如果需要，您可以在这里进行简单的验证或连接测试
            logger.info("SolanaAgentSkill 初始化成功")
            return True

        except Exception as e：
            logger.error(f"初始化 SolanaAgentSkill 时出错：{e}")
            return False

    async def deploy_token(self, name: str，symbol: str，supply: int，decimals: int = 9) -> dict：
        """
        示例方法，使用 solana-agent-kit 逻辑部署新代币。
        """
        if not self.private_key：
            logger.error("技能未初始化，缺少私钥")
            return {"success": False，"error": "技能未初始化"}

        try：
            logger.info(f"正在 Solana 上部署名为 '{name}' 的代币，供应量为 {supply}")
            # 伪代码：
            # agent = SolanaAgentKit(self.private_key，"https://api.mainnet-beta.solana.com")
            # result = await agent.deployToken(name，uri，symbol，decimals，supply)
            # return {"success": True，"mint": result["mint_address"]}

            # 为了演示，返回一个假结果
            return {"success": True，"mint": "FakeMint123"}
        except Exception as e：
            logger.error(f"deploy_token 出错：{e}")
            return {"success": False，"error": str(e)}

# 如果需要，可以创建一个全局实例
solana_agent_skill = SolanaAgentSkill()

这里发生了什么：

• skill_name = "solana_agent"。
• 我们调用 api_manager.register_required_keys(...) 并传入 ["SOLANA_PRIVATE_KEY"]。
• initialize() 从安全存储中加载私钥。
• deploy_token(...) 是一个用于实际 Solana 逻辑的示例方法——此处仅为占位符。

---

2. 在 skills_config.json 中注册技能

打开 config/skills_config.json，并添加：

{
  "solana_agent": {
    "enabled": true，
    "required_api_keys": ["SOLANA_PRIVATE_KEY"]，
    "api_key_mapping": {
      "SOLANA_PRIVATE_KEY": "SOLANA_PRIVATE_KEY"
    }
  }
  // ... 其他技能 ...
}

（现在，引导向导或 Web 界面会在缺少 SOLANA_PRIVATE_KEY 时提示您输入。）

---

3. 创建或更新一个使用该技能的活动

接下来，我们定义一个调用 solana_agent_skill.deploy_token(...) 的活动。你可以手动完成，也可以让 AI 生成代码。以下是一个手动示例：

# activities/activity_deploy_solana_token.py
import logging
from framework.activity_decorator import activity, ActivityBase, ActivityResult
from skills.skill_solana_agent import solana_agent_skill

logger = logging.getLogger(__name__)

@activity(
    name="deploy_solana_token",
    energy_cost=1.0,
    cooldown=2592000,  # 例如 30 天
    required_skills=["solana_agent"]
)
class DeploySolanaTokenActivity(ActivityBase):
    async def execute(self, shared_data) -> ActivityResult:
        try:
            logger.info("开始执行 DeploySolanaTokenActivity...")

            # 如果尚未初始化技能，则进行初始化
            if not await solana_agent_skill.initialize():
                return ActivityResult(
                    success=False,
                    error="初始化 Solana 代理技能失败"
                )

            # 从共享数据或状态中获取示例配置
            token_info = {
                "name": "我的 AI 代币",
                "symbol": "AIT",
                "supply": 1000000,
                "decimals": 9
            }

            result = await solana_agent_skill.deploy_token(
                name=token_info["name"],
                symbol=token_info["symbol"],
                supply=token_info["supply"],
                decimals=token_info["decimals"]
            )

            if not result["success"]:
                return ActivityResult(
                    success=False,
                    error=result.get("error", "来自 Solana 技能的未知错误")
                )

            logger.info(f"代币已部署，铸造地址为: {result['mint']}")
            return ActivityResult(
                success=True,
                data={"mint_address": result["mint"]}
            )

        except Exception as e:
            logger.error(f"DeploySolanaTokenActivity 中发生错误: {e}")
            return ActivityResult(success=False, error=str(e))

---

4. 添加活动约束（可选）

如果你希望限制该代币的部署频率，可以在 activity_constraints.json 中定义约束条件。例如：

{
  "activity_cooldowns": {
    "DeploySolanaTokenActivity": 2592000
  },
  "activity_requirements": {
    "DeploySolanaTokenActivity": {
      "required_skills": ["solana_agent"]
    }
  }
}

（现在系统会识别出 DeploySolanaTokenActivity 需要 solana_agent 技能，并且有 30 天的冷却时间。）

5. 重启或热加载

系统会自动重新加载新的活动。如果你刚刚创建了 activity_deploy_solana_token.py，可以选择重启代理，或者等待配置好的热加载功能生效。一旦运行起来，智能体可能会根据约束条件选择该活动；你也可以通过移除冷却时间或将它设为唯一可行的选择来强制执行。

---

为什么保留 AI/Web UI 的默认设置？

• 易于使用： 我们的内置“BuildOrUpdateActivity”可以自动生成新代码，省去手动创建的麻烦。
• Web UI： 你可以直接在界面上手动编辑或优化 Python 代码。
• 高级开发者： 如果你有特殊需求（比如特定的约束条件或不适合使用 Composio 的外部库），手动创建技能将非常合适。

---

扩展与创建其他自定义活动

• 依赖 AI： 智能体可以通过“BuildOrUpdateActivity”自动生成新的 .py 代码。你可以在 Web UI 中批准或进一步优化。
• 手动： 类似上述步骤——创建 activity_*.py 文件，使用 @activity() 装饰器定义类，并在 activity_constraints.json 中设置约束条件。

无论哪种方式，一旦被系统识别，新活动就有资格在主循环中被选中。

---

记忆、状态与活动选择

记忆

• 短期记忆： 最近的日志或活动结果（最多约 100 条）。
• 长期记忆： 按类别归档的旧日志。

状态

• 存储智能体的“能量”、“情绪”、时间戳或其他自定义字段。

活动选择器

• 过滤掉不符合冷却时间或技能要求的活动。
• 如果仍有多个活动可用，则调用 LLM 来做出决策。
• 如果没有符合条件的活动，可能会提议新的活动来填补空缺。

---

停止或暂停代理

• Web UI： 点击“停止”或“暂停”按钮。
• 命令行： 按下 Ctrl+C。

内存和状态会保留下来，以便下次继续使用。

---

贡献

我们欢迎 PR 和反馈！

1. 克隆本仓库。
2. 为你的更改创建一个特性分支。
3. 添加或改进代码或文档。
4. 提交拉取请求——维护者会审查并合并。

---

许可证

本项目采用 MIT 许可证。详情请参阅 LICENSE 文件。

---

好了！我们希望你喜欢使用 Pippin 框架进行开发。无论你是想让 AI 构思内容、在 Solana 上发行代币，还是从头实现一项全新的技能，我们都将为你提供支持。如果你有任何问题或建议，请随时联系我们或提交一个问题——祝你编码愉快！

Pippin 快速上手指南

Pippin 是一个灵活的开源框架，用于创建能够自主学习、连接工具并执行任务的“数字生命”（自主智能体）。它支持通过 CLI 或 Web UI 进行配置，能够动态生成新活动以适应你的目标。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：Python 3.9 或更高版本
• 账户要求：GitHub 账号（用于克隆项目）
• 可选依赖：Composio 开发者密钥（推荐，用于通过 OAuth 连接 Twitter、Slack 等 250+ 种工具）

安装步骤

1. 克隆项目

首先 Fork 该仓库，然后克隆到你的本地环境：

git clone https://github.com/<your-username>/pippin-draft.git
cd pippin-draft

2. 安装依赖

本项目推荐使用 uv 包管理器以获得更快的安装速度。

安装 uv：

curl -LsSf https://astral.sh/uv/install.sh | sh

创建并激活虚拟环境：

# 创建虚拟环境
uv venv

# 激活环境 (Unix/MacOS)
source .venv/bin/activate

# 激活环境 (Windows)
.venv\Scripts\activate

安装项目依赖：

uv pip install -r requirements.txt

3. 初始化配置

复制示例配置文件到 config 目录：

cp -r config_sample config

基本使用

Pippin 提供了两种启动方式：命令行向导（CLI）和网页界面（Web UI）。两者底层逻辑一致，任选其一即可。

方式一：使用 Web UI（推荐新手）

1. 启动服务：

   python -m server
   

2. 访问界面：打开浏览器访问 http://localhost:8000。
3. 完成引导：
   • LLM 设置：输入至少一个 LLM API Key（如 OpenAI）或配置本地模型路径。
   • 角色定义：设置智能体的名称、性格、主要目标和约束条件（例如：“每小时最多发 5 条推文”）。
   • 技能连接：可选择通过 Composio 连接 OAuth 应用，或手动输入 API Key。
4. 启动智能体：配置完成后，点击界面上的 Start 按钮，智能体将开始运行循环任务。

方式二：使用 CLI 向导

1. 运行引导程序：

   python -m tools.onboard
   

   按照终端提示依次完成 LLM 配置、角色设定和技能添加。

2. 启动智能体： 配置完毕后，运行以下命令启动核心循环：

   python -m framework.main
   

   日志将直接在终端输出，按 Ctrl+C 可停止运行。

核心功能说明

启动后，Pippin 将自动执行以下默认活动：

• AnalyzeDailyActivity：分析近期记忆并进行反思。
• SuggestNewActivities：根据目标头脑风暴新任务。
• BuildOrUpdateActivity：调用 LLM 生成新的 Python 代码文件（位于 activities/ 目录），动态扩展自身能力。

你可以通过修改 config/character_config.json 调整角色设定，或在 skills/ 目录下添加自定义技能（如 Solana 交互、图像生成等）来扩展智能体的能力。