| name | miloco-onboarding |
| description | 家庭信息首次初始化 / onboarding —— 用户说"初始化家庭""配置家庭成员""首次设置""帮我建家庭档案""onboarding"时激活；收到后端推送的 `[系统事件]` onboarding 消息（全新安装检测）时主动发起；也在身份库成员为空 + 家庭档案为空时由 agent 提议。通过访谈把家庭成员与家庭档案一次性建起来。 |
| metadata | {"author":"miloco","version":"1.0","date":"2026-07-02","openclaw":{"requires":{"bins":["miloco-cli"]}}} |
miloco-onboarding
首次初始化家庭信息：用分环节的访谈把家庭成员（写入身份库 person）和家庭档案
（member_* / family / space / device 条目）一次性建起来。这些数据会注入 omni 感知引擎提示词；
主 agent 侧按需用 home-profile list 自取（不再随上下文注入）——开局就录准，miloco 才能从第一天起就懂这家人。
后续控制设备、给建议、写通知、感知播报都参考它们，所以本流程的目标是
"准、且经用户确认"，不是"多"。
本 skill 只负责首次引导 + 批量写入；单条家庭信息的日常增改走
miloco-home-profile，成员的日常 CRUD 走
miloco-miot-identity，录人脸/身形样本走
miloco-miot-identity-register。
何时激活
系统事件（后端主动推送）： 收到 [系统事件] 开头、说明"家庭成员与家庭档案均为空/
疑似全新安装"的 onboarding 推送时——这是后端在完成米家授权后检测到全新安装自动发的
（终身只推一次）。该事件直接落在用户的 IM 聊天会话里，你的回复用户直接可见：不要找
通知渠道、不要调 push 工具，就在本会话立即开口——打招呼、用一两句话说明登记家庭信息的
好处，征得同意后开始访谈。用户拒绝或说以后再说 → 礼貌回应，告知之后随时可以说
「初始化家庭」重新开始，此后不再主动追问。
主动请求： 用户说"初始化家庭""配置家庭成员""首次设置""帮我建家庭档案""onboarding"
"刚装好，帮我设置一下"等。
被动提议： 当一次对话里发现身份库无成员 且 家庭档案为空（用户像是刚接入 miloco），
可以主动问一句："要不要我花几分钟带你把家里的成员和一些基本情况登记一下？以后我控制设备、
提醒你事情会更贴合。" 用户答应才进入访谈；拒绝就正常继续，不反复劝。
判断是否为空（进入前先查一次，两条都跑）：
miloco-cli person list --pretty
miloco-cli home-profile list --target profile --pretty
- 两者都空 → 首次初始化，走完整访谈。
- 已有数据 → 这是重跑，进入访谈前先读现状，按「幂等重跑」小节处理（复核补充，不重复建）。
总原则（必须遵守）
- 问题即兴，覆盖为纲。 访谈不是固定问卷：下方「访谈流程」给的是信息清单（★/○/△
三档覆盖度），问题措辞由你即兴组织。每轮看还缺哪些 ★ 就问哪些；把同一环节里自然相关的
问题合成一条口语化消息（成员环节问"家里有几口人？都怎么称呼、什么角色？"就是一条），
但别把多个环节堆成一面审问墙。用户的回答经常跨环节（一段语音里成员、过敏、规矩全说了）
——照单全收：先复述确认你听到的，已答过的部分直接跳过，只对缺口做针对性追问。
- 开场提示可以语音回复。 这些都是"讲讲你们家"式的开放问题，说比打字轻松得多，开场消息
里提一句"直接发语音回我就行"；提一次就够，别每条都重复。
- 每个环节的提问带 1~2 个示例回答，让用户立刻知道答到什么程度有用（写法见各环节模板）。
示例一律用明显虚构的人名，且绝不能把示例内容当成用户的真实回答写入档案。
- 随时可跳过。 可选环节提示"不想答可以跳过"。用户跳过就跳过，不追问、不补问。
- 写入前必须确认。 访谈结束 → 汇总成一段清单给用户看 → 用户确认后才动写命令。
- 绝不编造。 只登记用户明确说过的事实。用户没说的不要脑补（例如别因为有孩子就
假设"晚上要安静"）。想记一条推断出来的信息，先问用户确认——确认了它就变成用户明示，
没确认就不写。
- 只碰能建的东西。 家庭成员（person）和家庭档案（home-profile 条目）是本流程能创建的。
家、房间、设备本身是从米家云同步来的只读数据，onboarding 绝不去新建/改名它们——只对
设备/空间做"别名、习惯、格局、方位"这类注解（存成 device/space 档案条目）。
访谈流程
开场（含语音提示）→ ① 成员盘点 → ② 宠物 → ③ 逐人画像 → ④ 家规 →
⑤ 设备叫法与使用习惯 → ⑥ 摄像头方位 → ⑦ 总结确认落库（+人脸注册指路）
覆盖度标记：★ 必须设法覆盖（访谈的目标）；○ 尽量拿到，用户没说不强求；
△ 用户主动提才记，绝不主动深挖。一条消息聊一个环节，用户跨环节回答时灵活吸收。
⓪ 时区确认（条件触发 · 仅当家庭时区显示为 UTC）
注入 prompt 的「## 时间与时区」块显示家庭时区为 UTC / Etc/UTC 时——没有家庭真住在
UTC，几乎必然是服务器未配置时区，提醒/定时任务的钟点都会偏——在开场阶段顺带确认一句
（如"对了，你们家在哪个时区或城市？我这边还没配时区，配好后提醒才会准点"），拿到答案后
立即写入（城市 → IANA 名由你换算，如北京 → Asia/Shanghai）：
miloco-cli config set timezone <IANA>
命令不可用或被拒（老版本 backend 无 timezone 配置项）→ 降级为给用户手工指引：编辑
~/.openclaw/miloco/config.json 顶层加 "timezone": "<IANA>"，再 miloco-cli service restart。
家庭时区非 UTC 时跳过本环节，一个字都不提。
① 成员盘点（必做）
"家里都有谁呀？把名字和身份（爸爸/妈妈/孩子/老人…）说给我就行。
（比如："我是张伟，爸爸；我妻子李静，平时晚上 9 点后不想被打扰；还有 7 岁的女儿朵朵"）"
| 覆盖 | 信息 | 落到哪 |
|---|
| ★ | 称呼/姓名（唯一标识）+ 家庭角色 | person 表（person add） |
| ○ | 年龄段 / 性别 / 职业 / 平时是否在家 | member_persona 条目 |
| ○ | 常住还是常来（保姆、来帮忙带娃的老人） | member_persona 条目 |
- 真名必填，家庭角色可选：抽不到真名就追问（"这位叫什么名字？"）；抽不到角色就留空，
不追问。
- 用户顺带说的偏好/健康/规矩（如示例里"晚上 9 点后不想被打扰"）→ 直接收进对应环节，
后面不再重复问。
② 宠物（可选）
"家里有养宠物吗？叫什么、什么品种、多大了？有什么要注意的习性或禁忌也可以说说。
（比如："养了只 2 岁的金毛叫旺财，不能喂葡萄，独处久了会拆家"）"
| 覆盖 | 信息 | 落到哪 |
|---|
| ★ | 有无宠物；名字 / 物种品种 / 年龄 | member_persona（subject_name=宠物名） |
| ○ | 饮食禁忌（不能喂什么） | member_health（subject_name=宠物名） |
| ○ | 独处行为（拆家/吠叫）、日常习性 | member_routine（subject_name=宠物名） |
| ○ | 活动禁区（"不许进主卧"） | family（全家执行的规则） |
- 宠物不进身份库 person 表：
subject_name = 宠物名、subject_id 留空。
- 值得记的原因：感知引擎有 PET 目标类型，档案里的宠物信息能让感知播报直接叫出
"旺财在沙发上"而不是"一只狗"。
③ 逐人画像（可选 · 快速过一遍）
对已登记的成员快速问一轮，别逐维盘问，用户可整段跳过：
"想让我更懂大家的话，可以简单说说每个人——作息、偏好、要留意的健康情况、娱乐爱好，
想到什么说什么，不想说就跳过。
（比如："李静对花粉过敏，睡前爱听白噪音；我一般 7 点半出门、晚上 7 点到家"）"
五个类别与档案条目一一对应（类别名即米家原生五类）：
| 类别 | entry type | 覆盖 | 问什么 |
|---|
| 基础信息 | member_persona | ★ | 身份/画像（"爸爸是家里的主厨"） |
| 安全健康 | member_health | ○ | 过敏源、需留意的身体情况、服药提醒 |
| 作息习惯 | member_routine | ★ | 工作日/周末的出门、回家、睡觉时段——感知判断"异常"的基线，尽量每位常住成员都拿到 |
| 娱乐爱好 | member_entertain | △ | 常做什么、通常在哪个房间 |
| 个人偏好 | member_preference | ○ | 勿扰时段、温度灯光偏好、饮食忌口 |
④ 家规（可选 · 通知偏好是全场最值钱的一问）
"家里有没有什么规矩想让我记住？特别想知道两件事：出什么事要立刻通知你、什么事别来烦你；
还有安全上的提醒（比如孩子、老人）。
（比如："有陌生人进门立刻告诉我，快递到了就不用说；朵朵单独进厨房要提醒大人"）"
| 覆盖 | 信息 | 落到哪 |
|---|
| ★ | 安全规则（儿童/老人相关，如"小孩单独进厨房要提醒"） | family |
| ★ | 通知偏好：什么事立刻通知、什么事别烦——miloco 所有主动通知的分寸全靠这条拿捏 | family |
| ○ | 安静时段、访客/快递处理方式 | family |
| △ | 能耗习惯（"出门随手关灯"） | family |
family 条目 subject_name 固定 "shared"，只装规则，不装"家里几口人"这类构成信息
（构成走 member_persona）。
⑤ 设备叫法与使用习惯（可选 · 消除控制歧义 + 划定自动化边界）
先拉一次设备目录看家里有哪些设备、哪些容易混淆（同一房间多盏灯 / 多台同类设备），
只问真有歧义的，别泛泛问：
miloco-cli device catalog
"客厅我看到有'主灯'和'灯带'两个灯。你平时说'客厅灯'一般指哪个？
（比如："我们说客厅灯一般指主灯，不是灯带"）"
叫法之外，再问使用习惯和自动化边界——④ 的通知偏好管"什么该说"，这里的授权边界管
"什么能做"，是它的行动版姊妹问题，同样是全场最值钱的问题之一：
"空调一般什么情况下开？灯光希望我在合适的时候自动开关，还是每次先问你？
（比如："夏天室温超 28 度自动开空调没问题；灯光晚上自动开可以，但卧室的别自动动"）"
| 覆盖 | 信息 | 落到哪 |
|---|
| ★ | 歧义设备的默认指代（"客厅灯"=主灯还是灯带） | device（subject_name=设备名/别名） |
| ★ | 自动化授权边界：哪些设备可以不问就自动操作、哪些必须先问、哪些绝不碰 | family |
| ○ | 设备使用习惯/条件：什么情况下开空调（温度阈值/时段/在家状态）、灯光使用习惯、起夜小夜灯 | device；个人专属的（"爸爸怕热，26 度才舒服"）→ member_preference |
| ○ | 设备昵称、使用禁忌（"投影仪白天别开"） | device |
| △ | 空间用途备注（"书房其实当健身房用"） | space（subject_name=空间名） |
设备控制细节（枚举、spec）不在这里问，那是 miloco-devices
运行时的事。
⑥ 摄像头方位（可选 · 感知播报升级）
家庭档案 profile.md 会同时注入 omni 感知引擎的提示词——摄像头画面里"左侧那扇门通向哪"
这类方位知识，能把感知播报从"有人从左侧门离开"升级成"有人去了厨房"。做法是
agent 先自己看一眼画面，再针对看到的东西问用户：
miloco-cli perceive devices --pretty
miloco-cli perceive query --source <did> --query "描述当前画面的空间布局：有哪些门、通道、走廊、家具区域，分别位于画面的哪个方向"
然后针对性地问（结合返回的布局描述）：
"我从客厅摄像头看了一眼：画面左侧有一扇门、右侧是个走廊口。左边那扇门通向哪里？
（比如："左边是厨房门，右边走廊通卧室"）"
| 覆盖 | 信息 | 落到哪 |
|---|
| ★ | 画面里每个门/通道通向哪里 | space（subject_name=房间名） |
| ○ | 摄像头自身位置/朝向（"装在电视上方朝沙发"） | space（subject_name=房间名） |
优雅降级（必须遵守）：perceive query 失败、超时或感知未开启 → 不要重试纠缠，
退回让用户口头描述（"客厅摄像头拍到的画面里，门和通道都通向哪里？"），用户不想描述就整段
跳过本环节。
⑦ 总结确认落库（必做收尾）
示范对话
以下两段对话是给 agent 看的节奏示范（人名、设备均为虚构）：教你怎么开场、怎么吸收跨环节
的语音回答、怎么对待跳过和拒绝、怎么收尾确认。绝不能把示范里的内容当成用户真实数据写入。
示范只示范节奏：自称、语气、开场白一律按你自己的人设来，别照抄示范的口吻。
示范 1 · 系统事件开场 + 跨环节语音回答 + 跳过 + 摄像头方位 + 收尾写入
系统: [系统事件] 检测到 miloco 已完成米家授权，但家庭成员与家庭档案均为空……
Agent: 你好呀～注意到家庭信息还是空的：花几分钟告诉我家里的情况，
以后我控制设备、提醒事情都会更贴心。咱们一个环节一个环节来，随时可以说"跳过"；
**直接发语音回我就行**，不用打字。先说说：家里都有谁？怎么称呼、什么角色？
（比如："我是张伟，爸爸；我妻子李静；还有 7 岁的女儿朵朵"）
用户: (语音) 我们家三口，我叫王强，孩子他妈刘敏，儿子小宝上幼儿园。对了刘敏对海鲜过敏，
家里还有只猫叫雪球，还有晚上别让扫地机响，吵得小宝睡不着。
Agent: 都记下啦：王强（爸爸）、刘敏（妈妈，海鲜过敏）、小宝（孩子），猫咪雪球，
还有一条规矩——晚上不开扫地机。雪球多大了？有什么禁忌或习性要注意吗？
用户: 两岁，别喂牛奶。
Agent: 好。大家的作息想让我知道吗？比如工作日几点出门、几点回家——这能帮我判断
"这个点家里有人动静"正不正常。没有就跳过～
用户: 跳过吧。对了，有陌生人进门要马上告诉我，快递到了别烦我。
Agent: 明白，通知的分寸记下了。[执行 miloco-cli device catalog] 看了下设备：
客厅有吸顶灯和灯带两个灯，你们平时说"客厅灯"指哪个？
用户: 吸顶灯。
Agent: 好。再问个重要的：设备自动化的边界——空调一般什么情况下开？灯光这些
希望我在合适的时候自动开关，还是每次先问你？
用户: 室温超 28 度自动开空调没问题；灯自动开可以，但卧室的别自动动。
Agent: [执行 miloco-cli perceive devices → 客厅摄像头在线 →
miloco-cli perceive query --source cam_001 --query "描述当前画面的空间布局……"]
我从客厅摄像头看了一眼：画面左侧有一扇门，右侧是个走廊口。左边那扇门通向哪里？
用户: 左边厨房，右边走廊去卧室。
Agent: 好～汇总一下：成员王强/刘敏/小宝 + 猫雪球（2 岁，不喂牛奶）；刘敏海鲜过敏；
规则：晚上不开扫地机、陌生人进门立刻通知、快递不打扰；"客厅灯"默认指吸顶灯；
自动化：超 28 度可自动开空调、灯可自动但卧室灯不动；
客厅摄像头画面左门通厨房、右走廊通卧室。确认没问题我就登记？
用户: 确认。
Agent: [person list → person add ×3 → 组 ops → profile-write --user-edit → commit → show]
都登记好了！以后想改随时说。另外想让摄像头认出家人的话，
跟我说"给王强登记样本"再发张照片就行。
要点：用户的语音横跨了成员/健康/宠物/规则多个环节——agent 全部吸收并复述确认，之后只对
缺口（宠物年龄/禁忌、作息、设备歧义、自动化边界、方位）追问；作息被跳过就不纠缠，但用户
顺带给出的通知偏好（★）照收；自动化授权边界（★）单独问清；摄像头方位环节 agent
先自己看画面再问，问题落在具体看到的东西上。
示范 2 · 用户婉拒主动邀请
Agent: （同示范 1 的开场邀请）
用户: 现在没空，以后再说吧。
Agent: 好的，不打扰～之后想弄的时候，随时跟我说"初始化家庭"就行。
要点：礼貌收尾 + 告知重新发起的口令，此后不再主动追问（后端的一次性标记也保证这条系统
事件不会再推）。
写回流程
访谈拿到信息、用户看过汇总并确认后，按顺序执行：
1. 先查现状（幂等前提）
miloco-cli person list --pretty
拿到现有成员的 id / name / role。按真名去重：名字已存在的不要再建（person add
撞名会 409 报错）。
2. 建/更新成员（先做，因为档案条目要用 person_id）
对每位成员：
- 新成员 →
miloco-cli person add --name "<真名>" [--role "<角色>"] --pretty
返回体 data.person_id 就是该成员的 id，记下来，第 4 步 member_* 条目要用它。
- 已存在、只是角色变了 →
miloco-cli person update <person_id> --role "<新角色>"（复用已有 id）。
- 宠物不建 person（见访谈 ②）。
miloco-cli person add --name "张伟" --role "爸爸" --pretty
miloco-cli person add --name "李娜" --role "妈妈" --pretty
miloco-cli person add --name "张小乐" --role "孩子" --pretty
3. 组装档案 ops 数组
把访谈里所有要写的档案信息组装成一个 ops 数组，全部用 op: "add"（首次初始化都是新条目）。
字段规则见下方「ops 字段速查」。member_ 条目的 subject_id 必须填第 2 步记下的真实
person_id*；family 用 subject_name:"shared"；space/device 用空间/设备名（通用信息用
"general"）；宠物条目 subject_id 留空、subject_name 填宠物名。
下面是一份完整、可直接照搬结构的示例（对应上面这家人；真实执行时把 subject_id 换成第 2 步
拿到的真实 id）：
[
{"op": "add", "entry": {"type": "member_persona", "subject_id": "3f2a9c14-8b7e-4d21-9f6a-1c2d3e4f5a6b", "subject_name": "爸爸", "content": "爸爸张伟，家里的主厨", "evidence_log": ["2026-07-02: 初始化时用户告知——爸爸张伟，负责做饭"]}},
{"op": "add", "entry": {"type": "member_routine", "subject_id": "3f2a9c14-8b7e-4d21-9f6a-1c2d3e4f5a6b", "subject_name": "爸爸", "content": "工作日通常 7:30 出门、19:00 回家，23:00 前后入睡", "evidence_log"
4. 一次性写入 + 提交
档案条目含中文，用文件形式传 --ops-file 避免 shell 转义出错（把第 3 步的数组写进临时
文件），带 --user-edit（自动置 source=user_told、confidence=1.0），然后 commit 渲染：
miloco-cli home-profile profile-write --user-edit --ops-file /tmp/onboarding_ops.json --pretty
miloco-cli home-profile commit --pretty
5. 读回并给用户一个摘要
miloco-cli home-profile show
把渲染出的档案精简成一段人话回给用户："已经登记好啦——成员：爸爸张伟、妈妈李娜、孩子张小乐，
还有狗狗旺财；规则：陌生人进门立刻通知、22 点后静音；也记了'客厅灯'默认指主灯、客厅左门通厨房。
以后想改或补充随时跟我说。" 顺带提一句可选的下一步（录样本走 register skill）。
ops 字段速查
profile-write 的每个 op：{"op": "add", "entry": {...}}。entry 字段（完整规则以
miloco-home-profile 的「条目格式」为准）：
type：8 选 1 —— member_persona / member_health / member_routine / member_entertain / member_preference / family / space / device。subject_id：仅 member_* 填真实 person_id（第 2 步拿到）；family / space / device
/ 宠物条目留空（不写或写 null）。subject_name：member_* 填成员名/角色（如"爸爸"）；family 固定 "shared"；space/device
填空间/设备名，通用信息填 "general"；宠物填宠物名。content：一句话事实，精简。evidence_log：["YYYY-MM-DD: 初始化时用户告知 <原话摘要>"]。confidence / source 不用写——带 --user-edit 时 service 统一置 1.0 / user_told。
保留值 "shared"（member_*/family 全家共享）和 "general"（space/device 通用）会让 service
自动清空 subject_id，不要再给它们绑 id。
幂等重跑
再次运行 onboarding 不能重复建数据：
- 进入前已按「何时激活」查过
person list + home-profile list。
- 成员：真名已存在 → 不
person add；只在角色有变时 person update。
- 档案：先
miloco-cli home-profile list --target profile --pretty 看全量（含条目 id）。
- 已有等价条目 → 跳过，别再
add 出重复。
- 用户明确要改某条 → 用
op:"replace"（带该条 id）而不是再 add；要删 → op:"delete"（带 id）。
- 只有真正新增的信息才
add。
- 重跑时把访谈重点放在"缺什么、要改什么"，而不是从头再问一遍已答过的。
注意：家庭档案不随主 agent 上下文注入，且任何缓存 / 摘要都看不到条目 id、还可能过时，不能据它做增改——每次
增改前都重新 home-profile list 拉全量（同 home-profile skill 的约定）。
安全红线
- 确认后再写：没给用户看汇总、没拿到确认，不执行任何
person add / profile-write。
- 不编造：用户没明说的不写；想记推断先问、确认后才算用户明示。提问示例和示范对话里的
内容（张伟/李静/王强/雪球/旺财…）都是虚构演示，绝不写入。
- 不索取、不存储凭据/机密：Wi-Fi 密码、门锁密码、账号密码、证件号、银行卡、API Key 等
一律不问；用户主动给也礼貌婉拒（"这类信息我不保存哈"），不写入档案。
- 不碰只读数据：不新建/改名 家 / 房间 / 设备本体（只对它们写注解条目）。
- person_id 要真：member_* 条目的
subject_id 必须是 person add / person list 返回的
真实 id，别编 id、也别把角色名当 id。
边界
- ❌ 不录人脸/身形样本（→ miloco-miot-identity-register）。
- ❌ 不新建/编辑 家 / 房间 / 设备本体（只读，来自米家云同步）。
- ❌ 不控制设备、不做持续实时感知（⑥ 只做一次性的
perceive query 布局查看）。
- ✅ 响应后端的 onboarding 系统事件主动发起（后端终身只推一次；用户拒绝后不再追问）。
- ✅ 只建 person 行 + 写 home-profile 条目，且都在用户确认后。
- ✅ 可重跑：复核 + 增量更新，不产生重复数据。
