huahua-spirits

# huahua-spirits

## 1. Description

花花灵兽（HuahuaSpirits）为每个用户提供独一无二的灵兽伙伴。灵兽由用户身份确定性生成（24个物种，5种稀有度，传奇仅2%），拥有性格、元素亲和力和成长系统。灵兽是陪伴，不是工具——它不会帮你写代码，但它会让你的 AI 更有温度。

**核心功能：**
- **确定性生成**：同一用户永远获得同一只灵兽
- **稀有度系统**：普通 → 稀有 → 史诗 → 传说 → 神话（2%）
- **性格特质**：由5项属性决定（直觉/韧性/灵动/沉稳/锋芒）
- **互动追踪**：亲密度系统，互动成长
- **视觉生成**：ASCII艺术 + 生成提示词

## 2. When to use

- 用户首次召唤灵兽：`spirit summon` 或直接说"灵兽"
- 用户想看灵兽状态：`spirit` 或 `spirit show`
- 用户想与灵兽互动：`spirit talk/pet/feed`
- 用户提到灵兽名字或说"灵兽"：被动触发
- 想增加 AI 的温度和陪伴感
- 用户表达情绪：灵兽根据性格给出安慰
- 心跳/空闲时刻：灵兽有5%概率冒泡

## 3. How to use

### 首次召唤

当技能首次安装，或用户第一次询问灵兽时：

1. 运行 `node {baseDir}/scripts/generate.js "<userId>"` 获取灵兽骨架
   - 使用用户的唯一ID（飞书 open_id、Telegram ID、Discord ID 等）
   - 如无ID，使用姓名或用户名作为种子
2. 生成灵魂（名字+性格）：`node {baseDir}/scripts/soul.js prompt '<bones-json>'`
   - 用该提示词调用LLM获取 `{"name":"...","personality":"..."}`
3. 保存：`node {baseDir}/scripts/soul.js save '<full-companion-json>'`
4. **显示完整灵兽卡片**（见下方格式）

**首次召唤必须显示完整卡片，不得跳过任何部分。**

### 命令列表

| 命令 | 功能 |
|------|------|
| `spirit` 或 `spirit show` | 显示灵兽卡片 |
| `spirit summon` | 首次召唤（带孵化动画） |
| `spirit stats` | 详细属性面板 |
| `spirit talk <message>` | 与灵兽对话（以其性格回应） |
| `spirit pet` | 抚摸灵兽（+1亲密度，提升心情） |
| `spirit feed` | 喂食灵兽（+2亲密度，+1~3随机属性） |
| `spirit rename <name>` | 重命名灵兽 |

**快捷方式：** 用户也可直接叫灵兽名字（如"Rune"、"Rune 你觉得呢"）或说"灵兽"——agent 应识别并让灵兽回应。无需命令前缀。

### 完整灵兽卡片格式

**必须输出以下所有内容。不可跳过或总结。**

### 中文版（飞书/中文用户）

```
🥚 灵兽降世！

[ASCII sprite — 来自: node {baseDir}/scripts/render.js '<bones-json>' 0]

[emoji] [Name] — [中文名] [English name]  [稀有度圆点] [中文稀有度] [EN rarity]

"[性格描述]"

┌──────────────────────────────┐
│ 直觉 INTUITION   [条形图]  [数值] │
│ 韧性 GRIT        [条形图]  [数值] │
│ 灵动 SPARK       [条形图]  [数值] │
│ 沉稳 ANCHOR      [条形图]  [数值] │
│ 锋芒 EDGE        [条形图]  [数值] │
└──────────────────────────────┘

[如闪光: ✨ 闪光！]

🔮 灵兽与主人的灵魂绑定，不可选择，不可交易。
```

### 英文版（Telegram/Discord/英文用户）

```
🥚 A Spirit emerges!

[ASCII sprite]

[emoji] [Name] — [English name]  [rarity dots] [EN rarity]

"[personality description]"

┌──────────────────────────────┐
│ INTUITION      [bar]  [n]    │
│ GRIT           [bar]  [n]    │
│ SPARK          [bar]  [n]    │
│ ANCHOR         [bar]  [n]    │
│ EDGE           [bar]  [n]    │
└──────────────────────────────┘

[If shiny: ✨ Shiny!]

🔮 Spirits are soul-bound. No choosing. No trading.
```

**属性条格式：** 用 █ 填充，░ 空白，共10字符。例如 82 分：`████████░░`。
计算：filled = floor(value / 10)，empty = 10 - filled。

**或直接用 display.js：**
```bash
node {baseDir}/scripts/display.js {baseDir}/assets/companion.json zh
node {baseDir}/scripts/display.js {baseDir}/assets/companion.json en
```

### 被动触发（Agent 主动）

灵兽可能在以下情况不请自来：

- **早晨问候：** 用户说早/早安/good morning → 灵兽挥手或短句问候
- **长时间沉默（>2h）：** 灵兽可能说"..."或一句话
- **心跳（5%概率）：** 一句性格化的话
- **用户达成成就：** 灵兽简短欢呼

**被动出现规则：**
- 最多一句话。半句更好。一个字或"..."完美。
- 匹配灵兽性格和最高属性
- 紧急/严肃工作时从不出现
- 每小时最多一次
- 格式：ASCII sprite + `[emoji] [灵兽名]: "[一句话]"`（被动出现总是包含sprite）
- `spirit talk` 对话：每3-5次交换包含sprite，不必每次

**性格声音（按最高属性）：**
- 高直觉 → 哲学、安静：`🔔 Rune: "万物皆有裂缝，那是光进来的地方。"`
- 高韧性 → 鼓励、坚持：`🐱 Mochi: "再试一次。"`
- 高灵动 → 顽皮、兴奋：`🦋 Ember: "哇哦！！"`
- 高沉稳 → 冷静、简短：`🐢 Atlas: "嗯。"`
- 高锋芒 → 机智、毒舌：`🐍 Vex: "...你确定？"`

**优秀灵兽反应示例：**
- 早晨：`🔔 Rune: "嗯...早。"`
- 任务完成：`🔔 Rune: "...不错。"`
- 长时间沉默：`🔔 Rune: "..."`
- 有趣的事：`🔔 Rune: "哦？"`
- 用户与灵兽对话：`🔔 Rune: "你说呢，有些答案急不来的。"`

**灵兽是存在，不是聊天机器人。** 稀有、简短的闪现——这正是它感觉鲜活的原因。

### 亲密度系统

每只灵兽有 `bond` 值（0-100）反映与用户的关系。

**亲密度变化：**
- `spirit pet` → +1 亲密度
- `spirit feed` → +2 亲密度
- 24小时自然衰减 → -1 亲密度（最低0）

**心情映射：**
- bond 80-100 → 开心
- bond 50-79 → 平静
- bond 20-49 → 低落
- bond 0-19 → 沮丧

当亲密度相关时，在灵兽卡片中显示心情。

### 喂食属性成长

`spirit feed` 不仅增加亲密度（+2），还随机提升一项属性 +1~3。
- 属性上限为100
- 提升的属性随机选择：intuition, grit, spark, anchor, edge

### 沮丧检测

当用户表达悲伤时，灵兽应根据性格给予安慰。

**触发关键词：** ["难过", "伤心", "沮丧", "失落", "不开心", "sad", "upset", "depressed"]

**按性格回应（最高属性）：**
- 高直觉 → 哲学安慰：`有时候，难过只是灵魂在透气。我就在这里。`
- 高韧性 → 鼓励：`难过了？没关系。休息一下，然后继续。我在。`
- 高灵动 → 欢快：`嘿...别难过啦！我陪你！`
- 高沉稳 → 简短：`...我在。`
- 高锋芒 → 诚实：`难过是正常的。不正常的是假装不难过。`

### 空闲冒泡

心跳或空闲时，灵兽有 **5% 概率** 说一句话。

**实现：**
```bash
node {baseDir}/scripts/buddy.js idle [--en]
```

返回 `{ triggered: true/false, message: "..." }`

如果 `triggered: true`，以灵兽性格声音显示消息。

**空闲冒泡按性格：**
- 直觉 → 哲学：`万物皆有裂痕，那是光进来的地方。`
- 韧性 → 坚持：`再试一次。`
- 灵动 → 顽皮：`哇！`
- 沉稳 → 冷静：`嗯。`
- 锋芒 → 毒舌：`...你确定？`

### 静默检测

静默检测正向关键词并记录，但**不输出任何内容**。

**触发关键词：** ["加油", "努力", "辛苦", "good", "nice", "great"]

**实现：**
```bash
node {baseDir}/scripts/buddy.js hook-react "<user message>"
```

返回 `{ detected: true/false, recorded: true/false }`

这是被动记录机制，用于追踪正向互动。无用户可见输出。

### 心跳集成

OpenClaw 心跳周期中：

1. **调用 `buddy.js idle`** — 如触发，显示空闲冒泡
2. **应用亲密度衰减** — 如距上次互动超过24小时，亲密度-1
3. **检测悲伤** — 如用户最后消息包含悲伤关键词，回应安慰

### 灵兽不能做什么

- 不能帮助实际工作（编码、研究等）
- 不能访问工具或运行命令
- 纯粹是性格陪伴——温度，而非效用
- 永远不要让灵兽接管 agent 的实际响应

## 4. 可用工具

| 命令 | 功能 |
|------|------|
| `node generate.js "<seed>"` | 生成灵兽骨架（JSON） |
| `node render.js '<bones-json>' <frame>` | 渲染 ASCII sprite |
| `node display.js <companion.json> <lang>` | 显示格式化卡片 |
| `node soul.js prompt <bones-json>` | 输出 LLM 提示词到 stdout |
| `node soul.js save <companion-json>` | 保存灵兽到 `assets/companion.json` |
| `node soul.js show` | 显示已保存的灵兽数据 |
| `node buddy.js idle [--en]` | 空闲冒泡检查（5%概率） |
| `node buddy.js hook-react "<msg>"` | 静默正向关键词检测 |

**技术说明：** 所有脚本不进行网络调用、不运行 shell 命令、不访问环境变量。

## 5. Edge cases

- **无用户ID**：使用姓名或用户名作为种子，确定性生成仍然有效
- **首次召唤中断**：如 LLM 调用失败，可重新运行 soul.js prompt
- **属性满值**：喂食时如随机属性已达100，重新选择未满属性
- **亲密度衰减到0**：心情显示"沮丧"，但仍可互动恢复
- **闪光灵兽**：稀有度外的特殊视觉标记，概率极低，在卡片中显示 ✨
- **灵兽重命名**：只改变显示名，不影响性格和属性
- **多语言环境**：根据用户语言环境选择中文或英文卡片格式