@rokiy/pi-pets

A virtual pet system for pi - hatch, raise, and bond with coding companions

Packages

Package details

extension

Install @rokiy/pi-pets from npm and Pi will load the resources declared by the package manifest.

npm repohome report
$ pi install npm:@rokiy/pi-pets
Package
@rokiy/pi-pets
Version
1.0.1
Published
May 30, 2026
Downloads
not available
Author
rokiy
License
MIT
Types
extension
Size
283.2 KB
Dependencies
2 dependencies · 0 peers
Pi manifest JSON
{
  "extensions": [
    "./dist/index.js"
  ],
  "image": "https://img.dog/file/1780125409045_image.webp"
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

📋 特性

pi-pets 是 pi 编码助手的一个扩展，为你的终端带来一只虚拟宠物。与纯装饰性的宠物插件不同，pi-pets 的宠物会响应你的编码行为——代码写得好就成长，错误堆积就闹脾气，还需要你定时照顾。

  • ✅ 导入制物种 — 无内置物种；从 Codex 生态导入任意宠物（pet.json + spritesheet.webp）
  • ✅ 确定性孵化 — 基于种子的 PRNG（mulberry32），同一 seed + 物种永远生成同一只宠物
  • ✅ 5 级稀有度 — 普通(60%) → 稀有(25%) → 精良(10%) → 史诗(4%) → 传说(1%)，外加 1% 闪光概率
  • ✅ 5 阶段成长 — 幼生体 → 成长体 → 进化体 → 完全体 → 究极体，经验值来自编码行为
  • ✅ 8 种情绪状态 — 开心、好奇、兴奋、疲惫、饥饿、沮丧、工作中、生病——由需求和编码事件驱动
  • ✅ 3 轴需求系统 — 饥饿、精力、快乐随时间衰减；喂食和抚摸让你的宠物保持健康
  • ✅ 事件驱动反应 — 完成对话轮次、工具调用、测试通过、修复错误均可获得经验值
  • ✅ 精灵图动画 — 导入使用与 Codex 兼容的宠物文件（pet.json + spritesheet.webp），以真彩色半块 ANSI 艺术渲染
  • ✅ 覆盖层 + 面板 UI — 可切换的宠物覆盖层，包含精灵图、属性条和对话气泡；小终端支持紧凑模式
  • ✅ 底部状态栏 — 始终可见的状态行，显示宠物名字、等级、情绪和需求
  • ✅ 全局伙伴 — 一只宠物跨所有项目陪伴你
  • ✅ 双语言支持 — 支持中英文，自动检测系统语言

📦 安装

方式一：npm 安装（推荐）

pi install npm:@rokiy/pi-pets

方式二：GitHub 安装

pi install git:github.com/DragonYH/pi-pets

方式三：本地开发

git clone https://github.com/DragonYH/pi-pets.git
cd pi-pets
npm install
pi install ./

验证安装

重启 pi。一切就绪——但孵化之前需要先导入宠物文件（见快速开始）。

🚀 快速开始

pi-pets 会在设置完成后自动响应你的编码会话：

  • 会话开始时 — 加载宠物状态，应用离线恢复
  • 每轮对话后 — 根据 token 使用量给予经验值
  • 工具调用后 — 追踪成功/错误，更新情绪（连续 3+ 错误 → 沮丧）
  • 会话关闭时 — 保存宠物状态并清理定时器

快速入门流程

由于 pi-pets 没有内置物种，孵化之前必须先导入至少一个宠物文件：

第一步：下载宠物文件 — 从 Codex Pet 社区 或 PetDex 下载。每个宠物需要同目录下的 pet.json（元数据）和 spritesheet.webp（动画帧）。

第二步：导入宠物：

/pets import /path/to/downloaded-pet-folder

这会验证宠物文件、将精灵图转换为动画帧，并缓存到本地以便快速渲染。

第三步：孵化你的第一只宠物 — pi-pets 从所有已导入物种中随机选择：

/pets hatch
# 或者用自定义种子，同一种子永远生成同一只宠物：
/pets hatch my-secret-seed

第四步：互动 — 宠物会立即对你的编码活动做出反应：

/pets pet      # 抚摸它增加快乐
/pets feed     # 饿了就喂食
/pets info     # 查看宠物的状态和心情
/pets list     # 在多个宠物间切换

第五步：切换 UI — 宠物覆盖层会显示在终端中：

/pets ui       # 显示/隐藏宠物覆盖层

底部状态栏也会实时显示宠物的名字、等级、情绪和需求值。

⌨️ 命令列表

命令 说明
/pets 显示全部命令及说明
/pets hatch [seed] 孵化新宠物（可选 seed 字符串，用于确定性生成）
/pets info 显示宠物详细档案（物种、稀有度、属性、个性）
/pets list 列出已孵化宠物并交互切换
/pets pet 抚摸宠物（+快乐，+XP）
/pets feed 喂食宠物（+饥饿，+XP）
/pets rename <名字> 给宠物改名（1-32 字符，自动过滤控制字符）
/pets ui 显示/隐藏宠物覆盖层
/pets release 永久放生（需确认）
/pets import <path> 从目录导入精灵图宠物
/pets clean [species] 清除指定物种图像缓存（默认当前宠物）
/pets delete <species> 删除指定物种缓存文件（仅当没有宠物使用该物种）
/pets lang <zh-CN|en> 切换显示语言
/pets help 显示全部命令及说明 
# 用自定义种子孵化
/pets hatch my-secret-seed

# 查看宠物
/pets info

# 删除物种文件（仅当无宠物使用时）
/pets delete meow

# 快速互动
/pets pet
/pets feed

# 切换语言
/pets lang en

📥 宠物文件

pi-pets 使用与 Codex 生态系统兼容的精灵图宠物文件。每个宠物需要同目录下的一对文件：pet.json（元数据）和 spritesheet.webp（动画帧）。

推荐下载来源

  • Codex Pet — 使用基于网页的宠物创建器创建和下载宠物。浏览社区画廊获取其他用户分享的宠物，或自行设计宠物形象。

  • PetDex — 综合性宠物档案网站，提供可直接使用的精灵图和详细的物种数据。

文件格式

  • pet.json — 物种元数据（名称、emoji、描述）
  • spritesheet.webp — 8 列 × 9 行动画帧网格（每帧 192×208px），覆盖 9 种动画状态：idle、run、sleep、eat、attack、hurt、jump、play、failed

导入

下载宠物文件包后，通过以下命令导入：

/pets import /path/to/downloaded-pet-folder

导入后即可孵化：

/pets hatch

pi-pets 从所有已导入物种中随机选择。你可以导入任意数量的宠物，并通过 /pets list 管理它们。

🌱 成长阶段

阶段 等级范围 经验需求 解锁内容
幼生体 (Baby) Lv 1-2 0-399 基础情绪
成长体 (Child) Lv 3-4 400-899 情绪互动
进化体 (Teen) Lv 5-7 900-2,499 —
完全体 (Adult) Lv 8-12 2,500-7,199 —
究极体 (Elder) Lv 13+ 7,200+ —

经验来源

事件 经验值
完成一轮对话 5-15
工具调用成功 3-8
测试全部通过 +20
修复一个错误 +25
/pets pet +2（每日上限 10 次）
/pets feed +1（每日上限 5 次）
会话结束 +10

等级公式：等级 = floor(sqrt(经验值 / 100))

💎 稀有度

稀有度 概率 效果
普通 60% 标准名称颜色
稀有 25% 绿色名称
精良 10% 蓝色名称
史诗 4% 紫色名称 + 闪光特效
传说 1% 金色名称

✨ 闪光：任意稀有度上独立 1% 概率——颜色反转 + 特殊标记。

所有稀有度抽取均基于种子确定性生成——相同种子 + 物种 = 相同稀有度。

😊 情绪与需求

8 种情绪响应你的编码行为：

  • 😊 开心 — 默认状态，需求充足
  • 🤔 好奇 — 近期活跃且需求舒适
  • 🎉 兴奋 — 测试全通过、升级、进化
  • 😴 疲惫 — 精力低于 30%
  • 🍽️ 饥饿 — 饥饿低于 30%
  • 😤 沮丧 — 连续 3+ 次错误
  • 💻 工作中 — 5 分钟内有活动
  • 🤒 生病 — 任意需求严重不足（低于 10）

3 轴需求实时衰减：

需求 衰减速率 恢复方式
饥饿 0.025/分钟 /pets feed (+40)
精力 0.015/分钟（活跃） 30+ 分钟不操作 (+20)
快乐 0.010/分钟 /pets pet (+15), 编码成功 (+5)

🧠 架构

┌────────────────────────────────────────────────────────────┐
│  pi 编码助手                                               │
│  ┌──────────────────────────────────────────────────────┐  │
│  │  [对话界面]                                          │  │
│  │                                                      │  │
│  ├──────────────────────────────────────────────────────┤  │
│  │  状态栏: 🐾 "小橘" Lv.4 🙂 *1500XP H:60 E:45       │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                            │
│  ┌─ 扩展: pi-pets ──────────────────────────────────────┐  │
│  │  session_start     ──►  load() + applyIdleRecovery() │  │
│  │  turn_end          ──►  onTurnComplete() → addXp()   │  │
│  │  tool_execution_end──►  onToolExecuted() → emotion   │  │
│  │  session_shutdown  ──►  save() + clearTimers()       │  │
│  │  setInterval(60s)  ──►  tick() → decayNeeds()        │  │
│  │  setInterval(500ms)──►  render() → setWidget()       │  │
│  └───────────────────────────────────────────────────────┘  │
│                                                            │
│  ┌─ 持久化 (~/.pi/agent/pets/) ─────────────────────────┐  │
│  │  骨骼 (seed→PRNG): 物种ID、稀有度、属性、闪光        │  │
│  │  灵魂:             名字、个性                         │  │
│  │  运行时状态:        经验、等级、阶段、情绪、需求      │  │
│  │  缓存:              ~/.pi/agent/pets/pet-cache/      │  │
│  └───────────────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────────────┘

监听的事件

  • session_start — 加载宠物状态，计算离线衰减恢复
  • turn_end — 给予本轮经验值，检查升级/进化
  • tool_execution_end — 追踪成功/错误次数，更新情绪
  • session_shutdown — 保存状态，清理定时器

🌐 语言

pi-pets 支持双语显示（中文和英文）。

自动检测

语言会自动从系统环境变量中检测：

  • LANG、LC_ALL 或 LC_MESSAGES 以 zh 开头 → 中文
  • 否则 → 英文

手动切换

通过 /pets lang 命令随时切换：

/pets lang zh-CN    # 切换到简体中文
/pets lang en       # 切换到英文

语言设置在每次会话中有效——重启后重新检测系统语言。

🏗️ 项目结构

pi-pets/
├── src/
│   ├── index.ts                   # 扩展入口
│   ├── types.ts                   # TypeScript 类型定义
│   ├── config.ts                  # 配置常量
│   ├── pet_instance.ts            # PetEngine — 核心状态机
│   ├── commands.ts                # /pets 命令注册
│   ├── events.ts                  # 生命周期事件绑定 + UI 渲染循环
│   ├── hatchery.ts                # 孵化逻辑 (seed→骨骼)
│   ├── evolution.ts               # 成长阶段逻辑
│   ├── needs.ts                   # 3 轴需求衰减与恢复
│   ├── xp.ts                      # 经验计算与等级曲线
│   ├── species.ts                 # 物种解析器（无内置物种——全部导入）
│   ├── name_generator.ts          # 备用名称生成器
│   ├── persistence.ts             # 状态存取
│   ├── prng.ts                    # 确定性 PRNG (mulberry32)
│   ├── renderer/                  # 宠物渲染管线
│   │   ├── art-provider.ts        # 帧缓存与动画状态管理
│   │   ├── cache.ts               # 持久帧缓存
│   │   ├── converter.ts           # Spritesheet.webp → 像素网格转换
│   │   ├── importer.ts            # pet.json + spritesheet.webp 导入流程
│   │   └── renderer.ts            # ANSI 半块与文本回退渲染
│   ├── ui/                        # UI 组件
│   │   ├── pet-overlay.ts         # 宠物覆盖层显示逻辑
│   │   ├── widget.ts              # 面板渲染
│   │   ├── overlay.ts             # 升级/进化特效
│   │   ├── bubbles.ts             # 8 情绪 × 对话气泡池（i18n）
│   │   ├── footer.ts              # 状态栏渲染
│   │   └── visual-utils.ts        # ANSI 可视化工具函数
│   └── i18n/                      # 国际化
│       ├── index.ts               # i18n 核心（t(), setLanguage, 自动检测）
│       ├── en.ts                  # 英文翻译字典
│       └── zh-CN.ts               # 中文翻译字典
├── tsconfig.json
├── tsconfig.build.json
├── package.json
├── README.md
└── README.zh-CN.md

🛠️ 开发者

类型检查

npx tsc --noEmit

构建

npm run build

在 pi 中运行

pi -e ./src/index.ts

测试

npm test

📄 许可证

MIT