语音日记 (voice-diary)

把一天里用户口述、打字或音频转写的零散记录，整理成一份可视化的语音日记。
产出四块内容：① 语音转写总段落 → ② 全天状态时间线表 → ③ 状态强度曲线（颜色由浅到深）→ ④ 休息建议 + 饮食调整。

何时使用

• 用户明确要求「写语音日记 / 记一下今天的语音 / 把语音整理成日记」。
• 用户说「记一段 / 追加记录 / 记录一下刚才」→ 进入分段采集（只存不汇总）。
• 用户说「补录 / 补记 / 补昨天 / 昨日补录 / 把昨天的也记上」+ 一段内容 → 记到昨天（补录模式，见下）。
• 用户说「记个想法 / 记个创业展望 / 这个念头不错（非生活类）」→ 单独存到想法流（collect_idea.py），不在日常日记里，仅用于早间/月度单独高亮（见下）。
• 用户说「汇总今天 / 晚上总结 / 把今天的语音合并」或到点（21:30 自动触发）
  → 合并当天所有片段，产出完整一天总结。
• 用户提供一段口述文字、多条语音转写稿，或一段音频，希望生成结构化日记。
• 用户想回顾某天的节奏、精力与饮食，得到调整建议。

零配置起步（推荐路径）

本技能核心流程完全免密钥、免隧道、免任何额外安装——你只要把「口述/打字文字」给 AI，
剩下的结构化、曲线、建议、归档全自动。下面把哪些功能开箱即用、哪些需要配置说清楚：

> 结论：不配任何密钥也能完整使用语音日记。OPENAI_API_KEY 只是「锦上添花」
> （音频文件转写、服务端全自动），不是 prerequisites。

手机怎么用（零隧道方案，推荐）

手机用麦克风必须 HTTPS，搭隧道较麻烦。最省事的手机用法是完全不走麦克风：

1. 打开手机输入法自带的「语音/麦克风」按钮（Gboard、苹果键盘、讯飞都行），按住说话 → 自动转成文字；
2. 把这段文字直接发到 WorkBuddy 聊天窗口；
3. 说一句「记一段 / 追加记录」→ 存入今天的语音日记（走分段采集）。

晚上 21:30 自动汇总成全天总结。全程不需要麦克风权限、不需要隧道、不需要密钥。
若你确实想在手机浏览器里点麦克风实时说，再走 phone.py 隧道方案（见「在手机上使用」）。

分段采集与夜间汇总（v1.3.0+）

技能支持两种节奏，最终都汇成同一份结构化日记：

1. 白天 · 分段采集：用户一天里可以口述很多次。每次说「记一段 / 追加记录」，
   把当前文字以 {ts, text} 追加进 diary/segments/<date>.json（子目录隔离，
   不污染趋势/分享）。此步只记录、不结构化，不打断用户。
   - 命令行：python scripts/collect.py --append --text "…" [--time HH:MM]
   - 口述页：点「➕ 追加一段记录」；或勾选「说完自动存档」开关（v1.4.1 新增，默认开），
   三种识别方式在「停止说话」时自动把当前转写文字 POST /segment 存为当天一段、并清空输入框，
   无需再手动点「追加一段记录」。关掉开关则恢复手动追加。
   - 断网也不丢记录（v1.4.2 新增）：自动存档若因网络波动/服务器异常失败，该段会暂存进浏览器本地（localStorage），
   状态栏显示「N 段待补传」并出现「🔄 重试补传」按钮；联网后页面加载会自动补传，或手动点按钮补传，
   补传成功才清空本地暂存。极端情况下（隐私模式 localStorage 不可用）文字保留在输入框，提示手动「追加一段记录」。

每天能记多少段？
- 没有硬性上限。每段以 {ts,text} 追加进 diary/segments/<date>.json（一个 JSON 数组）。技术上一整天记几十条也存得下。
- 建议节奏：为让全天状态时间线（成品第 2 块）清晰有层次，每天 5–15 段最合适——大致覆盖「起床/通勤/上午/午休/下午/下班/晚饭/夜班间隙/睡前」等关键节点；段太少（<3）时间线会偏空，段太多（>20）汇总文案会偏碎。
- 段数只影响「时间线密度」，不影响结构化质量；21:30 汇总时会按时间合并全部片段，标注 [片段N HH:MM]。
- 想看已记几段：口述页状态栏「今日分段：N 段」实时显示。

补录昨日（v1.4.3 新增）

有时白天忘了记、或想补上昨天漏掉的片段，可在不破坏今天数据的前提下，把内容记到昨天：

• 口述页：状态栏下方有「记录到：今天 / 昨天（补录）」切换。切到「昨天（补录）」后，
  所有「追加一段 / 说完自动存档 / 今晚汇总」都作用于昨天——状态栏变为「昨日分段：N 段」，
  「今晚汇总」按钮也变成「🌙 汇总昨天」，点它合并昨天的片段出昨天的日记。
  切回「今天」即恢复正常。前端会在切换时向 GET /count?date=… 拉取对应日期的已有段数。
• 聊天窗口：用户说「补录 / 补记 / 补昨天 / 昨日补录 + 内容」，用 CLI 写昨天：
  bash python scripts/collect.py --yesterday --append --text "昨天忘了记：……" [--time HH:MM] # 等价于 --date <昨天日期>
  之后说「汇总昨天」即合并昨天所有片段（含本次补录）出昨天日记，与今天互不影响。
• 隔离性：昨天的数据落在 diary/segments/<昨天>.json，与今天完全独立；21:30 自动汇总默认只汇总今天，
  不会把补录的昨天片段误并进今天。补录后想看昨天成果，说「汇总昨天」或口述页切「昨天」点汇总即可。

> 一句话：补录 = 把 date 指向昨天；其余流程（分段、合并、渲染）与今天完全一致。
2. 晚上 · 汇总成全天：到 21:30（默认自动化）或用户说「汇总今天」，
运行 python scripts/finalize.py --date <date> 把当天所有片段按时间合并
成一份连续素材（标注 [片段N HH:MM]），再按下面第 1~5 步结构化并渲染成
diary/<date>.html。若当天无片段，提示「今天还没有记录」，不生成空日记。
- 口述页：点「🌙 今晚汇总」。无 OPENAI_API_KEY 时返回合并素材，
回聊天窗口粘贴并说「汇总今天的语音日记」即可。

> 一次成型模式（用户一次性给齐全天内容、直接「生成语音日记」）依然可用，
> 与分段模式共享第 1~5 步的整理逻辑，区别仅在素材来源。

每日提醒自动化（建议，v1.3.1+）

为养成记录习惯，建议在 WorkBuddy 里建 3 个每日自动化提醒，到点轻轻提示你「记一段」：

• 自动化只需发一条轻松提醒（如「☀️ 上班后小记录：刚到岗状态咋样？说句『记一段』存进今天日记～」），
  不自动生成日记；用户看到后口述/打字说「记一段」即走分段采集。
• 时刻可按作息调整；倒班/夜班用户请把时刻改成自己的「到岗后 / 半夜收工后 / 傍晚」等对应时段。
• 配合「每晚 21:30 自动汇总」自动化，形成「白天多次记 + 晚上统一总结」的闭环。

工作流程

第 0 步：收集输入

接受三种输入，按优先级处理：
1. 对话框口述/打字文字（主路径）：用户直接给的当日记录文字。
2. 粘贴的语音转写稿：手机/微信语音转文字结果，直接采用。
3. 音频文件路径（扩展路径）：运行
python scripts/transcribe.py <音频路径> 取得文字。
若脚本报「未配置 OPENAI_API_KEY」或转写失败，不要中断——改为请用户
粘贴转写文字，回到路径 1/2。

若用户一天分多条语音，按时间顺序拼接为一份原始素材。

第 1 步：总段落（对应成品第 1 块）

把当天所有语音内容，按时间推进合并成一个连续的总段落。保留原意与关键细节，
淡化「呃/那个/然后然后」等口头禅，但保留能体现情绪的原话。这是成品的「今日全记录」。

第 2 步：全天状态时间线表（对应成品第 2 块）

依据 references/schema.md 的准则，把一天切成若干时间段（最少 3 条，建议 5–10 条）。
每条记录以下字段：

• time：大致时间点 HH:MM（升序）。
• activity：在做的事，动词开头、简练。
• emotion：从语调 + 措辞 + 自我描述推测的情绪/状态标签（如「轻松」「偏焦虑」）。
• state：一句话个人状态（如「精力饱满」「电量低下」）。
• level：状态强度 1–10（综合能量高低 + 情绪张力），驱动曲线高度与颜色。

level 判定、情绪推测线索、颜色语义（浅=轻松低能量，深=紧绷高能量）一律参照
references/schema.md，保持各天口径一致，便于长期对比。

第 3 步：状态强度曲线（对应成品第 3 块）

曲线由渲染脚本自动生成，此处只需保证 records 的 level 真实反映当天起伏。
渲染器会把 level 映射为：低=浅青、高=深靛，并在图上附「浅·轻松 → 深·紧绷」色条，
让用户一眼看出当天最紧绷/最高能量的时段。

第 4 步：综合建议（对应成品第 4 块）

基于 records 整体形态写两段建议，具体可落地（准则见 references/schema.md）：

• advice.rest：看 level 峰值时段、全天均值、是否有长时间高位占用；
  给出可执行的休息/睡眠动作，点出最需放松的时段。
• advice.diet：从语音里抓饮食信号（吃了什么、喝水多少、咖啡/奶茶、跳餐、宵夜）；
  给出针对性调整。

第 5 步：组装 JSON 并渲染

把以上结果聚合成严格符合 references/schema.md 的 JSON，例如：

{
  "date": "2026-10-12",
  "weekday": "周一",
  "paragraph": "……（第1步总段落）",
  "records": [ { "time":"07:10","activity":"…","emotion":"…","state":"…","level":6 } ],
  "advice": { "rest":"……", "diet":"……" }
}

然后调用渲染脚本（脚本仅用标准库，无需额外依赖）：

python scripts/build_diary.py --json diary.json --out diary/2026-10-12.html

• 默认 --out 为当前工作区下的 diary/<date>.html；目录不存在时会自动创建。
• 也可省略 --out 让脚本输出到 stdout，再写入文件以便预览。

第 6 步：交付

用 present_files 打开生成的 diary/YYYY-MM-DD.html，并简要说明：
当天峰值时段、平均状态、以及最关键的 1–2 条建议。文件已按日期归档，方便日后回看。

直接口述（浏览器语音入口，增强路径）

若想「对着窗口说话就立刻成日记」，用本技能自带的无密钥语音口述器：

1. 启动本地服务：
   bash python scripts/serve_recorder.py # 默认 http://127.0.0.1:5019/ python scripts/serve_recorder.py --port 8080
2. 浏览器（Chrome / Edge）打开该地址，点麦克风开始说中文，实时转写。
3. 点「生成语音日记」：
   - 已配置 OPENAI_API_KEY → 服务端自动结构化并渲染 HTML，返回日记链接（全自动）。
   - 未配置 Key → 返回提示，点「复制文字」回 WorkBuddy 聊天窗口粘贴并说
   “生成语音日记”，由本技能（即对话中的 AI）完成结构化与建议。
4. 生成的日记同样存入 diary/YYYY-MM-DD.html。

> 语音识别走浏览器本地 Web Speech API，无需任何密钥；结构化整理才用到 AI。

在手机上使用

> 首选「零隧道方案」：手机键盘听写 → 聊天窗口说「记一段」（见上节），零配置、最省事。
> 本节的隧道方案仅在你想在手机浏览器里点麦克风实时说时才需要。

手机用麦克风必须 HTTPS（安全上下文），且 http://127.0.0.1 或同 Wi-Fi 的 http 在手机上都不可用。
用一行命令把本地服务通过 Cloudflare 临时隧道暴露成 HTTPS 地址，手机打开即可：

# 先在本机启动服务（保持运行）
python scripts/serve_recorder.py
# 另开一个终端，把本地 5019 暴露成公网 HTTPS（cloudflared 需先下载，免费、免登录）
cloudflared tunnel --url http://localhost:5019
# 终端会输出 https://xxxx.trycloudflare.com ，手机浏览器打开它

• Android（Chrome）：页面自动进入「实时听写模式」，点麦克风说中文即实时转写，无需任何 Key。
• iPhone（Safari）：iOS 不支持网页实时听写，页面默认进入「本地识别（免 Key）」模式——
  在浏览器内用 Whisper 模型直接识别（首次需联网下载约几十 MB 模型，之后离线可用），
  点麦克风即说即转，无需任何 API Key。若想更快，可切到「服务端(需Key)」用 Whisper API 上传识别。
• 口述页顶部有三个识别方式按钮可切换：浏览器听写（Android/Chrome 实时免 Key）/
  本地识别(免Key)（iPhone 推荐）/ 服务端(需Key)（录音上传 Whisper）。
• 想全自动出日记（两端都行）：在环境变量设置 OPENAI_API_KEY 后启动服务。
• 零部署替代：手机用自带键盘听写（Gboard / 苹果键盘 / 讯飞）把话说成文字，直接发到
  WorkBuddy 聊天窗口并说「生成语音日记」，由技能完成整理（同样无需 Key）。

想法 / 创业展望单独记录（v1.5.0）

日常日记记的是生活（带娃、家务、上班、睡眠……）。但用户常冒出非生活类的念头——
奇怪的想法、创业/副业展望、对某个项目的灵感。这些不想混进时间分配统计，又怕忘，所以单独成流：

• 命令：python scripts/collect_idea.py --append --text "…" --tag "创业展望"（tag 可选：奇怪想法 / 创业展望 / 其它(非生活)）。
• 聊天触发：用户说「记个想法 / 创业展望 + 内容」→ 走 collect_idea.py 存到 diary/ideas/<date>.json（按天列表）。
• 为什么单列：日常日记的时间分配柱状图只统计生活行为；想法流不会被归类进「睡眠/工作/带娃」等，避免污染行为数据。
• 早间/月度会自动把近期想法单独高亮出来（见下两节），提醒你别让好点子溜走。
• 查看：collect_idea.py --recent 7（最近 7 天）、--list --date YYYY-MM-DD。

时间分配柱状图与横向对比（v1.5.0）

scripts/build_bars.py 从 diary/<date>.json 的 records 推算每段时长（按相邻起始时间差；末段若带 HH:MM-HH:MM 范围则用范围末值），按关键词归类
（睡眠休息 / 工作通勤 / 带娃家庭 / 家务 / 吃饭饮食 / 娱乐游戏 / 出行采买 / 其它），渲染自包含 HTML：

• 单日柱状图：python scripts/build_bars.py --dates 2026-10-15 --out bars.html → 当日各活动时长柱 + 分类时长小计。
• 横向对比（昨日 vs 今日）：python scripts/build_bars.py --yesterday --out cmp.html →
  两张单日柱 + 一张「分类并排对比柱」（昨日蓝 / 今日橙）+ 差异文案（如「睡眠：昨 4h43m → 今 0m（-4h43m）」）。
• 月度聚合：python scripts/build_bars.py --month 2026-10 --out month.html → 当月各分类累计时长柱 + 有记录天数。
• 命令结束会往 stdout 打印 ===SUMMARY=== 文字摘要（差异行 + 各天时长），供自动化推送直接取用。
• 归类是关键词启发式，仅供自我观察；时长按事件间隔推算，非精确计时。

每日早间推送 & 月度总结（v1.5.0 自动化）

为把上面的数据「用起来」，技能配套两条自动化（已内置，可在 WorkBuddy 自动化里查看/关闭）：

1. 📅 每日早间推送（每天 08:30）：自动跑 build_bars.py --yesterday --ideas，
   给你一段昨日 vs 今日行为差异简报 + 时间分配柱状图 + 横向对比图；若期间有想法/创业展望会单独 ⚠️ 标出提示。
   （今日往往还没记录，推送会说明「今日尚未记录，预计差异待补」；夜班日晚起可忽略或改时刻。）
2. 🗓️ 每月 1 号月度总结（每月 1 号 21:00）：自动跑 build_bars.py --month <上月> --ideas，
   汇总整月时间分配、有记录天数、当月想法/展望，出月度柱状图。

> 时刻可按作息调整（尤其倒班/夜班用户）；自动化只做「推送与汇总」，不自动改写你的日记。

如果失败了怎么办（v1.4.2 排查指南）

技能已尽量做「失败不丢数据、可自愈」，下面按场景给处理办法：

1. 自动存档网络中断 / 服务器没回应

• 现象：点完麦克风/识别停止后，提示「⚠️ 网络中断，自动存档未送达」或「服务器未确认」。
• 已兜底：该段自动存入浏览器本地（localStorage），状态栏显示「N 段待补传」并出现「🔄 重试补传」按钮。
• 怎么办：
  1. 恢复网络后，刷新页面会自动补传；或点「重试补传」按钮立即补传；
  2. 补传成功提示「待补传已全部送达」，本地暂存清空。
• 极端情况（隐私模式等 localStorage 不可用）：文字保留在输入框，提示「请点『追加一段记录』手动存」——手动点一下即可。

2. 语音识别没出字 / 识别报错

• 浏览器听写（Android/Chrome）无结果或中断：Web Speech 依赖网络与 Google 服务，弱网/后台切换会断。换「本地识别(免Key)」或在安静环境重试；急用可关掉「说完自动存档」，用手机键盘听写→聊天窗口说「记一段」。
• iPhone 本地识别报错：首次需联网下载 Whisper 模型；若下载失败，提示「本地识别不可用」，可切「服务端(需Key)」或走键盘听写方案。
• 服务端(需Key)识别失败：检查 OPENAI_API_KEY 是否有效、额度/网络；或换前两种免 Key 方式。

3. 点「今晚汇总」没反应 / 报错

• 今天还没有记录：返回「今天还没有记录」，不会生成空日记——先去记几段。
• 未配置 OPENAI_API_KEY：不报错，而是返回合并好的当天素材，提示「复制后去聊天窗口粘贴并说『汇总今天的语音日记』」，由对话里的 AI 完成结构化（见上）。
• 本地暂存还有未补传的段：汇总前先按场景 1 把「待补传」补完，否则汇总的只是已送达的部分。

4. HTTPS 隧道连不上 / 手机打不开页面

• 首选「零隧道方案」：手机键盘听写→聊天窗口说「记一段」，零配置最稳（见「手机怎么用」）。
• 确需手机浏览器点麦克风：用 phone.py 拉 cloudflared 隧道；若 cloudflared 下载失败或连不上，脚本会自动回退打印免隧道键盘听写方案，不影响使用。

5. 麦克风权限被拒 / 找不到麦克风

• 浏览器地址须是 HTTPS（或 http://127.0.0.1 本机）；手机用同 Wi-Fi 的 http 不可用。
• 去浏览器地址栏左侧「权限」里允许麦克风；或回归键盘听写方案（不碰麦克风权限）。

6. 改完技能后想验证

• 跑 python scripts/selftest.py：collect→finalize→渲染→服务接口+语调代理全过则退出 0，作为回归基线。

> 口诀：记不下→本地暂存+重试补传；识别挂→换免Key方式或键盘听写；汇总缺Key→复制去聊天窗口；手机麻烦→走零隧道键盘听写。

增强能力（v1.1.0+）

除核心四块日记外，脚本集还提供：

• 多日趋势：本地累积 diary/*.json 后，运行 python scripts/build_trend.py
  生成 diary/trend.html（平均状态强度随日期的浅→深曲线 + 每日指标表）；
  口述服务也提供 GET /trend 一键生成。
• 分享长图：python scripts/build_share.py diary/<date>.json 生成竖版 SVG 分享卡
  diary/<date>_share.svg 与 Markdown diary/<date>.md（后者便于粘贴进腾讯文档）；
  服务提供 GET /share?date=YYYY-MM-DD。
• 语调代理：音频经 Whisper 转写且带分段时间戳时，
  python scripts/analyze_tone.py --json segs.json 输出 level_bias(−2…+2)，
  用于校准状态强度（详见 references/schema.md 第六节）。
• 腾讯文档归档：连接腾讯文档连接器后，把 diary/<date>.md 用 tencent-docs 技能建文档，
  形成云端日记本（见 references/tencent_docs.md）。
• 手机一键隧道：python scripts/phone.py 自动启动服务并拉起 cloudflared HTTPS 隧道，
  打印手机可打开的地址（首次会下载 cloudflared）。

资源

• scripts/build_diary.py：核心渲染器。读 JSON → 输出自包含 HTML（含 SVG 曲线）。
  用法：python build_diary.py --json <f> --out <html>，或省略 --out 输出到 stdout。
• scripts/collect.py：分段采集。把白天每次口述/文字以 {ts,text} 追加到
  diary/segments/<date>.json；支持 --append / --list / --count。
• scripts/finalize.py：夜间汇总。合并当天 diary/segments/<date>.json 所有片段为一份素材
  （标注 [片段N HH:MM]），写出 diary/<date>_transcript.txt 并打印，供 AI 结构化。
• scripts/transcribe.py：可选音频转写。调用 OpenAI Whisper API（需 OPENAI_API_KEY），
  未配置时友好提示并退出，主流程改走粘贴文字路径。
• scripts/serve_recorder.py：语音口述本地服务。托管浏览器口述页（assets/recorder.html），
  接收实时转写，有 Key 时全自动出 HTML、无 Key 时回退聊天窗口；并提供 /trend、/share、/diary 接口。仅用标准库。
• scripts/build_trend.py：多日趋势聚合，读 diary/*.json 渲染 trend.html。
• scripts/build_share.py：分享卡（SVG）+ 腾讯文档用 Markdown 导出。
• scripts/analyze_tone.py：基于 Whisper 分段时间戳的语调张力近似（无依赖）；v1.4.0+ 支持 --text 纯文本免 Key 模式。
• scripts/build_bars.py：时间分配柱状图 + 横向对比 + 月度聚合（v1.5.0）。--dates a,b / --yesterday / --month YYYY-MM，可加 --ideas 附带想法；输出自包含 HTML 并往 stdout 打 ===SUMMARY=== 文字摘要。
• scripts/collect_idea.py：单独记录非生活类想法/创业展望（v1.5.0），存 diary/ideas/<date>.json；支持 --append/--list/--recent N。
• scripts/selftest.py：端到端自测（无需密钥/网络）。python scripts/selftest.py 跑一遍
  collect→finalize→渲染→服务接口+语调代理，全部通过退出 0；改完技能后做回归验证用。
• scripts/phone.py：一键启动服务 + cloudflared HTTPS 隧道，手机即可访问。
• assets/recorder.html：浏览器语音口述前端，用免费 Web Speech API 做中文实时识别（Android 实时听写 / iPhone 录音上传双模式）；含「说完自动存档」开关，说停即自动存为当天一段记录；断网/服务器异常时自动暂存本地并支持一键补传，不丢记录；状态栏可选「记录到 今天 / 昨天（补录）」，补录昨日与今天数据隔离。
• references/schema.md：JSON 结构、字段说明、level 判定准则、情绪推测线索、建议生成准则、语调代理用法。
• references/tencent_docs.md：归档到腾讯文档的步骤与扩展点。
  整理前必读，保证各天口径一致。

备注

• 当前主路径以文字为主；真实「语音语调」分析需音频 + 韵律模型，留作后续扩展
  （transcribe.py 已预留接口）。文字路径下从情绪词、自我描述、事件性质推断。
• level 为 AI 推测值，仅供自我观察参考，不用于医疗/诊断。