关系维护 Relation Keeper

维护你的社交关系网络：肖像维护、未来提醒、过去归档。

---

一、数据存储

数据存储在 $RELATIONKEEPERDATA 指向的目录；未设置时使用当前 skill 目录下的 data/ 文件夹。

1.1 人物肖像 portraits.json

json
{
people: {
张三: {
name: 张三,
aliases: [老张],
gender: 男,
birthday: 03-15,
birthYear: 1990,
birthDate: 1990-03-15,
address: 北京市朝阳区xx路xx号,
phone: +86 1381234,
notes: 大学同学，做金融,
updatedAt: 2026-02-05T10:00:00Z,
facts: [
{ key: 喜好, value: 喜欢钓鱼, source: 2026-01-20 聊天, at: 2026-01-20 },
{ key: 职位, value: 某银行经理, source: 2026-01-20, at: 2026-01-20 }
]
}
}
}

• - 每次用户提及某人及与其相关的事件、信息时，更新对应 portrait。
• gender：性别（男/女/其他）。
• birthday：MM-DD 格式，用于周年提醒。
• birthYear：出生年（数字），可选。
• birthDate：出生日期，可模糊，如 1990、1990-03、1990-03-15。
• address：家庭地址。
• facts 为键值对列表，可按 key 去重或追加（同一 key 保留最新一条）。

1.2 过去事件 past_events.json

json
{
events: [
{
id: evt-001,
personIds: [张三, 李四],
type: 吃饭,
date: 2026-01-18,
summary: 和张三、李四在海底捞聚餐,
details: 讨论创业想法,
createdAt: 2026-02-05T10:00:00Z
}
]
}

• - type：吃饭、约会、游玩、聚会、会议等。
• 查询某人时，可基于 personIds 过滤并返回相关 past_events。

1.3 未来事件 future_events.json

json
{
events: [
{
id: fevt-001,
personIds: [张三],
type: 生日,
date: 2026-03-15,
time: null,
summary: 张三生日,
reminderRule: birthday,
createdAt: 2026-02-05T10:00:00Z
},
{
id: fevt-002,
personIds: [李四],
type: 约会,
date: 2026-02-10,
time: 18:30,
summary: 和李四晚餐,
reminderRule: appointment,
createdAt: 2026-02-05T10:00:00Z
}
]
}

• - reminderRule：

- birthday：生日/纪念日规则 - appointment：约会规则

---

二、提醒规则：单一扫描任务

不创建一次性提醒，使用一个每 15 分钟运行的 Cron 调用 scan.js 扫描，如有需要提醒的内容则输出。

2.1 提醒规则

事件类型	提醒时机
生日 / 纪念日	7 天前、3 天前、当天（每年按 MM-DD 匹配）
约会

事件前 2 小时、事件当刻 |

2.2 定时任务自动配置

安装本 skill 时，执行 npm install 会自动运行 postinstall 脚本，调用 node scripts/install.js 配置定时任务。用户无需手动执行 openclaw cron add。

若自动配置失败，可手动运行：
bash
cd && npm run install:cron

2.3 scan.js 行为

• - 读取 portraits.json（生日 MM-DD）与 futureevents.json
• 生日/纪念日：按 MM-DD 每年匹配，检查当天、+3 天、+7 天
• 约会：检查当前时间是否落在「事件前 2h」或「事件当刻」窗口内
• 已发送的提醒记录在 reminderssent.json，避免重复

2.4 添加未来事件时

仅需写入 future_events.json，无需创建任何 Cron。扫描任务会自动发现并提醒。

---

三、技能行为指南

3.1 何时触发本 skill

• - 用户提及某人及与其相关的信息、事件。
• 用户说「记一下」「提醒我」「某人生日」「和某人约会」等。
• 用户问「我和张三之前做过什么」「张三喜欢什么」「下周有什么安排」等。

3.2 肖像维护

• - 解析用户输入中的人名、事件、属性（年龄、手机、喜好等）。
• 更新 portraits.json：新建或合并到已有 portrait，追加 facts。
• 若事件属于「过去」，同时写入 past_events.json。

3.3 未来事件与提醒

• - 解析日期、时间（支持自然语言，如「下周五晚上 6 点半」）。
• 确定 reminderRule：生日/纪念日用 birthday，具体时间约会用 appointment。
• 写入 future_events.json 即可，扫描任务每 15 分钟会自动发现并提醒。
• 向用户确认：「已记录，到时会提醒你。」

3.4 过去事件归档

• - 用户描述「上周和谁吃饭」「昨天和谁约会」时，写入 past_events.json。
• 关联 personIds，便于按人查询。

3.5 查询

• - 「张三的信息」→ 读取 portraits.json 中 张三，并可选汇总 pastevents 中与之相关的事件。
• 「我和张三一起做过什么」→ 查询 pastevents 中 personIds 包含张三的事件。
• 「近期有什么社交安排」→ 查询 future_events.json 未来 N 天内事件。

---

四、配置

在 shell 或 ~/.openclaw/.env 中：

bash

数据目录（可选，未设置时使用 skill/data/）

export RELATIONKEEPERDATA=$HOME/.openclaw/relation-keeper

时区（用于计算提醒时间）

export RELATIONKEEPERTZ=Asia/Shanghai

提醒发送渠道（可选）

配置则直接推送到该渠道，如: export RELATIONKEEPERCHANNEL=telegram:YOURCHATID

未配置则推送到当前聊天（main session）

export RELATIONKEEPERCHANNEL=

---

五、自然语言触发示例

用户说	技能动作
张三生日 3 月 15 号，记一下	更新 portrait 生日，创建 future_event + birthday 提醒
下周五晚 6 点半和李四吃饭

创建 appointment，设置 2h 前 + 当刻提醒 | | 上周和张三在海底捞吃过饭 | 写入 past_event，更新 portrait | | 张三喜欢钓鱼 | 更新 portrait.facts | | 张三的电话是 138xxxx1234 | 更新 portrait.phone | | 张三是男的 / 张三性别 | 更新 portrait.gender | | 张三 1990 年出生 | 更新 portrait.birthYear / birthDate | | 张三住朝阳区xx路 | 更新 portrait.address | | 我和张三做过什么 | 查 past_events，汇总输出 | | 张三是谁 / 张三的信息 | 输出 portrait + 相关 past_events 摘要 | | 近期有什么约会 / 生日 | 查 future_events 未来 7–14 天 |

---

六、脚本与工具

从 skill 根目录（relation-keeper/）运行，需 Node.js 16+：

bash

人物肖像

node scripts/portrait.js get 张三
node scripts/portrait.js upsert 张三 --birthday 03-15 --gender 男 --birthYear