wispr-analytics

Wispr Analytics

从本地 SQLite 数据库中提取并分析 Wispr Flow 听写历史。将定量指标与大模型驱动的定性分析相结合，用于自我反思、识别工作模式和关注心理健康。

数据源

Wispr Flow 将所有听写内容存储在以下 SQLite 数据库中：

~/Library/Application Support/Wispr Flow/flow.sqlite

关键数据表：History，包含字段：formattedText、timestamp、app、numWords、duration、speechDuration、detectedLanguage、isArchived。

用户自 2025 年 2 月以来已有约 8,500 条以上听写记录，使用俄语和英语双语，涉及的应用包括：iTerm2、ChatGPT、Arc 浏览器、Claude Desktop、Windsurf、Telegram、Obsidian、Perplexity。

提取脚本

运行 scripts/extract_wispr.py 从数据库中提取数据：

# Get today's data as JSON with stats + text samples
python3 scripts/extract_wispr.py --period today --mode all --format json

# Get markdown stats for the last week
python3 scripts/extract_wispr.py --period week --format markdown

# Get text samples only for LLM analysis
python3 scripts/extract_wispr.py --period month --mode mental --texts-only

# Save to file
python3 scripts/extract_wispr.py --period week --format markdown --output /path/to/output.md

时段选项

• today —— 当天（默认）
• yesterday —— 前一天
• week —— 过去 7 天
• month —— 过去 30 天
• YYYY-MM-DD —— 指定日期
• YYYY-MM-DD:YYYY-MM-DD —— 日期范围

模式选项

• all —— 完整分析（默认）
• technical —— 筛选编码/AI 工具相关的听写内容
• soft —— 筛选沟通/写作相关的听写内容
• trends —— 重点分析数量/频率模式
• mental —— 分析所有文本，并以促进身心健康反思的方式呈现
• prosody —— 基于音频：从录制的 WAV 中分析音高/强度/语音质量（使用独立脚本 scripts/extract_prosody.py；仅适用于近期听写内容）。请参阅下文的“韵律模式”。

对比与图表

• --compare —— 自动与等长的前一时段进行对比（本周与上周对比，本月与上月对比）
• --graphs PATH —— 生成包含 Chart.js 图表的 HTML 仪表板（隐含启用 --compare）。图表包括：每日词数叠加图、每小时活动、类别细分、使用频率最高的应用、语言分布

# Compare this month vs previous month (markdown)
python3 scripts/extract_wispr.py --period month --compare --format markdown

# Generate visual dashboard for week comparison
python3 scripts/extract_wispr.py --period week --compare --graphs /tmp/wispr-week.html

# Compare and save both markdown + graphs
python3 scripts/extract_wispr.py --period month --compare --format markdown --output report.md --graphs report.html

韵律模式（基于音频）

这是一种独立的分析模式，与 technical/soft/trends/mental 同级，分析听写内容的说话方式，而不仅仅是说了什么。它会读取存储在 History.audio 中的录制 WAV 音频，并通过 Praat（经由 parselmouth）提取韵律特征，作为温和的情绪/精力代理指标，用于自我反思。请使用专用脚本 scripts/extract_prosody.py 运行。

依赖项

pip install praat-parselmouth

librosa/scipy/soundfile 可作为替代方案，但脚本使用 parselmouth（Praat）作为首选标准。

音频保留注意事项（请先阅读）

Wispr 仅保留近期听写内容的录制音频——约为 16,000 多条历史记录中最近的 900 条。较早记录的 audio 数据块会在上传后被清除（而 builtInAudio 始终为空）。因此，韵律分析仅适用于近期听写内容；较早时段的音频已丢失，只能恢复基于时间的指标（语速、停顿）。脚本会如实呈现这一情况：每份报告开头都会显示覆盖情况（此时段的 X 条听写中有 Y 条保留了音频），并在 --limit 限制覆盖范围时记录日志。

测量内容

• 音高（F0）：通过 Praat to_pitch() 获取，忽略无声帧；包括均值、中位数、最小值、最大值、范围、标准差，以及作为单调 <-> 富于表现力代理指标的 CV（标准差/均值）。
• 强度（dB）：均值、范围、标准差——表示响度变化。
• 语音质量：抖动（局部）、闪烁（局部）和 HNR（谐噪比）。通过 try/except 计算——处理失败的短音频/噪声音频会被跳过并计数（feature_failures）。
• 节奏（来自数据库中的计时列，而非音频）：语速 numWords / (speechDuration/60) WPM，以及停顿比例 (duration - speechDuration)/duration（下限设为 >= 0）。
• 按语言拆分（俄语与英语的 F0/语速不同——分开统计，避免双语混合模糊信号），以及多日时段的每日趋势表。

命令

# Prosody report for the last week (text)
python3 scripts/extract_prosody.py --period week

# Last month as JSON
python3 scripts/extract_prosody.py --period month --format json

# Specific day, raise the clip cap so coverage isn't truncated
python3 scripts/extract_prosody.py --period 2026-06-11 --limit 600

# Save to a file
python3 scripts/extract_prosody.py --period week --output /tmp/prosody-week.md

参数：--period（与 extract_wispr.py 语义相同：today/yesterday/week/month/YYYY-MM-DD/YYYY-MM-DD:YYYY-MM-DD）、--format text|json、--limit N（限制处理的片段数量，默认值为 300，以限制运行时间；截断时会向 stderr 写入日志）、--output PATH。数据库将严格以只读模式打开（mode=ro&immutable=1）。

性能：对 300 个片段进行音频分析约需 15–20 秒（比 SQL 慢）。默认的 --limit 300 可让单次运行保持快速；繁忙时段需要完整覆盖时，可提高此值。

合理性预期

Gleb 为男性，因此平均 F0 预计约为 95–150 Hz（观察到的值约为 120 Hz）。按语言拆分时，俄语通常表现出略高于英语的 F0 和 CV。F0 CV 通常为 0.2–0.3。

与心理模式的关联

韵律分析通过声学情感／能量指标补充基于文本的 mental 模式，并采用相同的呈现方式——邀请用户进行自我反思，而非给出诊断：

• F0 CV（音高变化度）可作为投入度／表达力指标：较平缓可能表示疲倦／偏事务性，变化较丰富则可能表示更有活力。
• 语速和停顿比例可作为能量／认知负荷指标。
• HNR 降低可能反映声音疲劳或紧张。

声学特征也会受到麦克风、房间、感冒和语言的影响——因此务必说明这种不确定性，并进行同类比较（相同语言，与用户近期的基线比较）。完整的解读提示词请参阅 references/analysis-prompts.md 中的 Prosody Mode 模板。

工作流

步骤 1：提取数据

使用请求的时段和模式运行提取脚本。需要完整数据时使用 --format json；侧重 LLM 分析时使用 --texts-only。

步骤 2：呈现定量统计数据

首先显示定量摘要：

• 听写总数、字数、语音时长
• 类别细分（coding、ai_tools、communication、writing、other）
• 语言分布
• 每小时活动模式
• 每日趋势（针对多日时段）
• 常用应用

步骤 3：进行定性分析

读取 references/analysis-prompts.md，加载适用于请求模式的分析模板。然后使用该模板分析文本样本。

针对每种模式：

Technical：关注处理的工作、技术决策、上下文切换模式和生产力评估。

Soft：关注沟通风格变化、语言切换模式、受众适配和人际互动。

Trends：关注数量变化、时段变化、应用迁移和行为变化假设。

Mental：关注能量指标、情绪信号、反刍检测和活动模式变化。所有观察都应表达为自我反思的邀请，绝不可作为诊断。使用“你可能会注意到……”或“这种模式可能表明……”之类的措辞。

All：结合全部四个视角，形成统一的反思。

步骤 4：输出

默认输出位置：知识库中的 meta/wispr-analytics/YYYYMMDD-period-mode.md。

文件格式：

---
created_date: '[[YYYYMMDD]]'
type: wispr-analytics
period: [period description]
mode: [mode]
---

# Wispr Flow Analytics: [period]

## Quantitative Summary
[stats from Step 2]

## Analysis
[qualitative analysis from Step 3]

## Reflection Prompts
[3-5 questions based on observations]

如果用户要求仅输出到控制台，则跳过文件创建并直接显示。

应用类别映射

提取脚本会对应用进行分类：

• coding：iTerm2、cmuxterm、VS Code、Windsurf、Zed、Cursor、Terminal
• ai_tools：ChatGPT、Claude Desktop、Perplexity、OpenAI Atlas、Codex
• communication：Telegram、Messages、Slack、Zoom
• writing：Obsidian、Notes、Chrome、Arc browser

词典管理

管理 Wispr Flow 的词典，以提高识别准确率。词典 JSON 在 ~/ai_projects/claude-skills/wispr-analytics/data/dictionary.json 中进行版本控制。

词典脚本

运行 scripts/wispr_dictionary.py 执行所有词典操作：

# Check database health and dictionary stats
python3 scripts/wispr_dictionary.py check

# List all entries (safe while Wispr is running)
python3 scripts/wispr_dictionary.py list
python3 scripts/wispr_dictionary.py list --filter "claude"

# Export dictionary to JSON (safe while running)
python3 scripts/wispr_dictionary.py export

# Suggest new entries by analyzing ASR vs formatted text differences
python3 scripts/wispr_dictionary.py suggest --days 30 --min-freq 3

# Propose snippets + replacement rules + vocab from dictation logs (safe while running)
python3 scripts/wispr_dictionary.py propose --days 30 --min-freq 3
python3 scripts/wispr_dictionary.py propose --days 90 --min-freq 2 --format json

# Add a single term (requires Wispr Flow to be QUIT)
python3 scripts/wispr_dictionary.py add "Gastown"
python3 scripts/wispr_dictionary.py add "cloud code" "Claude Code"

# Remove an entry (requires Wispr Flow to be QUIT)
python3 scripts/wispr_dictionary.py remove "old term"

# Import from JSON (requires Wispr Flow to be QUIT)
python3 scripts/wispr_dictionary.py import --dry-run
python3 scripts/wispr_dictionary.py import

词典安全规则

重要：执行任何写入操作（添加、移除、导入）前，必须退出 Wispr Flow。脚本会自动执行此检查。读取操作（导出、列出、建议、检查）可在 Wispr 运行时安全执行。

Wispr Flow 打开数据库时向 SQLite 数据库写入内容会导致索引损坏。请务必：

1. 检查 Wispr 是否正在运行：pgrep -f "Wispr Flow"
2. 如果正在运行，请先让用户退出（Cmd+Q）
3. 写入后，运行 check 验证完整性
4. 重启 Wispr Flow

词典条目类型

• 识别词条（仅短语）：教 Wispr 正确识别这个词（例如，“Gastown”、“LLM”、“subagent”）
• 替换规则（短语 → 替换内容）：自动纠正识别错误（例如，“cloud code” → “Claude Code”，“клод дизайн” → “Claude Design”）
• 文本片段（isSnippet=true）：文本扩展快捷方式（例如，“my email” → “[email protected]”）

提议替换规则和文本片段

suggest 只能捕捉 ASR 识别错误。propose 则进行范围更广、更贴近人工审阅的检查： 它会读取近期听写日志，并按三种 类别提议添加词典条目，同时跳过词典中已有的内容。它是只读的， 可在 Wispr Flow 运行时安全使用——绝不会写入数据库。

# Default: last 30 days, terms seen >= 3 times
python3 scripts/wispr_dictionary.py propose

# Wider net, machine-readable
python3 scripts/wispr_dictionary.py propose --days 90 --min-freq 2 --format json

标志：--days（历史记录时间范围）、--min-freq（最少出现次数）、--format （默认为 text，也可用 json）。

三种类别：

1. 文本片段候选项（收益最高、利用最少）：反复出现的网址、 邮箱和电话号码，以及重复使用的固定句子／开场白／结束语 （至少 8 个词，按规范化的逐字频率计数）。每项提议都包含一个 简短的 My X 触发短语，以及完整的扩展内容。
2. 替换规则候选项：反复出现的 ASR 识别错误（通过 find_mishears helper 与 suggest 共用代码）。
3. 词汇候选项：频繁听写的首字母大写／技术术语 （例如 HTML、LinkedIn、SDK），这些词可能会被错误识别——教 Wispr 正确拼写。

每项提议都会显示出现频次，并提供可直接运行的 add 命令行。

文本片段是收益最高、利用最少的词典功能。 每月有 1,600 多次听写的用户，往往只有少数几个文本片段。添加一个 My GitHub → 网址文本片段，就能省去数十次听写（和错误听写）网址的麻烦。 务必优先展示文本片段候选项。

建议的工作流

1. 运行分析（extract_wispr.py），了解听写量以及文本片段能发挥作用的地方。
2. 运行 propose（Wispr 运行时也可安全使用）。
3. 向用户展示分组后的提议——先展示文本片段，再展示替换规则， 最后展示词汇。强调文本片段带来的显著收益。
4. 用户批准后，退出 Wispr Flow（Cmd+Q），运行已批准的 add 命令（文本片段需使用 add "My X" "expansion"）。
5. 运行 python3 scripts/wispr_dictionary.py check 验证完整性。
6. 重启 Wispr Flow。

主动改进词典的工作流

运行分析时，也要检查是否有改进词典的机会：

1. 运行 propose，一次性找出文本片段、替换规则和词汇 （或者运行 suggest，仅查找识别错误）
2. 对比 asrText 与 formattedText，查找规律
3. 留意俄语／英语切换时的识别错误
4. 检查用户是否开始使用新的技术术语
5. 导出更新后的词典并提交到 git

备注

• 分析时：数据库为只读；分析过程绝不会修改 Wispr 数据
• 词典操作：写入前必须先退出 Wispr Flow
• 每次提取最多保留 100 条文本样本，以控制上下文窗口
• 分析多日时段时，按日趋势表有助于直观展示变化
• 双语听写很常见；分析时应兼顾俄语和英语
• asrText 字段包含格式化前的原始语音识别结果——可用于检测语音模式与格式化输出之间的差异
• 词典 JSON 存储在 ~/ai_projects/claude-skills/wispr-analytics/data/dictionary.json，用于版本控制