relation-keeper

# 关系维护 Relation Keeper 维护你的社交关系网络：**肖像维护**、**未来提醒**、**过去归档**。 --- ## 一、数据存储 数据存储在 `$RELATION_KEEPER_DATA` 指向的目录；未设置时使用当前 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 138****1234", "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 <skill 目录> && npm run install:cron ``` ### 2.3 scan.js 行为 - 读取 `portraits.json`（生日 MM-DD）与 `future_events.json` - 生日/纪念日：按 MM-DD 每年匹配，检查当天、+3 天、+7 天 - 约会：检查当前时间是否落在「事件前 2h」或「事件当刻」窗口内 - 已发送的提醒记录在 `reminders_sent.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` 中 `张三`，并可选汇总 `past_events` 中与之相关的事件。 - 「我和张三一起做过什么」→ 查询 `past_events` 中 `personIds` 包含张三的事件。 - 「近期有什么社交安排」→ 查询 `future_events.json` 未来 N 天内事件。 --- ## 四、配置 在 shell 或 `~/.openclaw/.env` 中： ```bash # 数据目录（可选，未设置时使用 skill/data/） export RELATION_KEEPER_DATA="$HOME/.openclaw/relation-keeper" # 时区（用于计算提醒时间） export RELATION_KEEPER_TZ="Asia/Shanghai" # 提醒发送渠道（可选） # 配置则直接推送到该渠道，如: export RELATION_KEEPER_CHANNEL="telegram:YOUR_CHAT_ID" # 未配置则推送到当前聊天（main session） export RELATION_KEEPER_CHANNEL="" ``` --- ## 五、自然语言触发示例 | 用户说 | 技能动作 | |--------|----------| | 张三生日 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 1990 --address "北京市朝阳区xx路" --fact-key 喜好 --fact-value 钓鱼 # 事件 node scripts/events.js future-add --persons 张三 --type 生日 --date 2026-03-15 --summary "张三生日" --rule birthday node scripts/events.js past-add --persons "张三,李四" --type 吃饭 --date 2026-01-18 --summary "海底捞聚餐" # 扫描提醒（通常由 Cron 每 15 分钟调用，也可手动执行测试） node scripts/scan.js # 配置定时任务（安装时自动执行，也可手动运行） npm run install:cron ```