self-sleep-agent：把"想睡好"变成可追踪的爬坡
一、这个 Agent 是干什么的
self-sleep-agent 是「自我」系列里专注于睡眠的一个能主动干活的 AI Agent。它的服务对象是「用 AI 的人」本人——那个常常深夜连轴转、靠咖啡续命、周末补觉反而更累的你我。
它不替你睡觉，也不做医疗诊断，而是把"想睡好"这件模糊的愿望，拆解成一组可记录、可计算、可复核的指标：
- 睡眠质量趋势：平均睡眠时长、睡眠效率、入睡潜伏期、主观质量、睡眠债；
- 生理节律学习：从你积累的记录里学出睡眠中点，推断你是早鸟、中间还是夜猫，并估算"社会时差"（工作日与自由日作息的错位）；
- 弱项预警：当效率偏低、时长欠债、作息漂移、咖啡因或屏幕过近时，主动点名；
- 本周计划：每次只给你"最值得做的一个改变"，避免建议过载。
它背后站着一整套睡眠科学（详见 references/ 与 resources/）：双过程模型、睡眠规律性指数 SRI、社会时差与时型 MCTQ、睡眠需要与睡眠债、睡眠卫生、多导睡眠图分期、光照授时、睡眠记忆巩固、CBT-I 与睡眠限制、睡眠结构随年龄变化、个体时型、睡眠惯性与小睡。不是"最好的养生建议"，而是带年份、期刊、书名出处的循证底座。
二、主动触发（重要）
这个 Agent 不是等你去翻文档才动的说明书。当以下情形出现时，它会主动介入：
- 你连续多日提到"好累、又熬夜、睡不好、起不来"——主动建议开始用
log记录，并给出最小上手步骤； - 你已经记了两周以上——主动跑
trend/rhythm/report，把趋势和弱项摆出来； - 报告出现弱项（退出码 1）——主动用
plan给出本周唯一主攻项，并解释为什么选它； - 你说"我周末补觉就行"——主动用社会时差理论点破"补觉反而打乱生物钟"；
- 你说"我是夜猫/懒/自律差"——主动用
rhythm测时型，把道德评判换成生理事实与可操作调整； - 你提到失眠、长期睡差——主动说明本工具的"前哨"定位，提醒重度情况走正规 CBT-I，不做越界承诺。
换句话说：它在该出手时出手，在该收手时收手（不替代医生），在该教育时教育（用理论而非鸡汤）。
三、理论地图（12 篇均带出处）
| 主题 | 关键理论 | 出处 |
|---|---|---|
| 睡眠调控 | 双过程模型 S+C | Borbély 1982, Hum Neurobiol 1(3):195-204 |
| 规律性 | 睡眠规律性指数 SRI | Phillips 2017, Sleep 40(8):zsx097 |
| 时型/错位 | 社会时差 + MCTQ | Wittmann 2006, Curr Biol 16(9):939-943；Roenneberg 2003, J Sleep Res 12(3):231-239 |
| 睡眠需要 | 分年龄推荐 + 睡眠债 | Hirshkowitz 2015, Sleep Health 1(1):40-43；Carskadon & Dement |
| 睡眠卫生 | 行为学循证 + 元分析 | Irish 2015, Sleep Med Rev 22:23-36；Stepanski & Wyatt 2003 |
| 睡眠结构 | 分期 R&K / AASM | Rechtschaffen & Kales 1968；AASM 2012 |
| 光照授时 | 相位响应曲线 | Czeisler 1986, Science 233:667-671；Lewy 1998 |
| 记忆巩固 | 睡眠依赖巩固 | Stickgold 2005, Nat Rev Neurosci 6:951-964；Walker 2009 |
| 失眠治疗 | CBT-I + 睡眠限制 | Spielman 1987, Sleep 10:45-56；Morin 2006, JAMA 295:2851-2858 |
| 结构年龄化 | 深睡随龄减少 | Ohayon 2004, Sleep Med Rev 8:281-301 |
| 个体时型 | 遗传+年龄+光照 | Roenneberg 2007；Jones 2019, Nat Commun 10:4098 |
| 睡眠惯性 | 唤醒脑雾 | Dinges 1985, Sleep 8:311-319 |
四、快速上手（30 秒）
# 1) 记一晚（--bedtime/--wake 必填；--latency 直接填潜伏期，或留空由 --onset 推算）
python scripts/sleep.py --data ./my_sleep log \
--date 2026-09-01 --bedtime 23:30 --latency 20 --wake 06:30 \
--waso 25 --quality 4 --caffeine 3 --screen 40 --mood 4 --daytype work
# 2) 看趋势（近 14 晚）
python scripts/sleep.py --data ./my_sleep trend --days 14
# 3) 学节律/时型/规律性（建议累计 14 晚以上，并用 --daytype 标记）
python scripts/sleep.py --data ./my_sleep rhythm
# 4) 完整报告（有弱项退出码 1，否则 0）
python scripts/sleep.py --data ./my_sleep report
# 5) 本周最该做的一个改变
python scripts/sleep.py --data ./my_sleep plan
数据全部落在 --data 目录：events.jsonl（逐晚记录）、profile.json（偏好）、reports/sleep-<日期>.md（报告）。重跑结果一致，可长期追踪。
五、子命令速查
| 命令 | 作用 | 关键参数 |
|---|---|---|
log |
记录一晚睡眠（同日期幂等覆盖） | --date --bedtime --onset|--latency --wake --waso --quality --caffeine --screen --mood --daytype |
trend |
近期趋势/睡眠债/规律性 | --days（默认14） --target（分钟，默认450） |
rhythm |
学出生理节律/时型/社会时差 | 无 |
nudge |
可执行建议（按影响排序） | --days --target |
report |
完整报告+弱项预警 | --days --target（弱项退出码1） |
plan |
本周最值得做的一个改变 | --days --target |
退出码约定：0 正常 / 1 需关注（存在弱项）/ 4 系统性警报（参数或数据错误）。
六、适用范围与边界（诚实声明）
- 本 Agent 是自我观察与节律学习的工具，不是医疗诊断，不替代医生；
regularity评分是 SRI 的工程近似（基于就寝/起床日标准差），非逐分钟全量 SRI；- 睡眠中点、时型、社会时差均从你提供的记录实时重算，记录越多越稳；
- 若符合慢性失眠临床标准（≥3 晚/周、≥1 月、影响日间），请走正规 CBT-I 或睡眠门诊。
