从命令行读取转录文本¶

macOS 发布二进制文件可以在 Hex 运行时读取保留的听写内容和录制的会议。如果 hex 不在你的 PATH 中，请使用 /Applications/Hex.app/Contents/MacOS/hex。

hex history --since 3d --app 'OpenCode Beta' --grep problems --json
hex history --since 2026-10-20 --until 2026-10-21 --raw --oldest-first --limit 500
hex history --since 7d --search 'problems board' --json
hex history stats --since 7d --json   # Labs › Dictation stats
hex meetings list --since 7d --json
hex meetings show latest --md
hex meetings show 1790000500000-1002 --json
hex meetings show 1790000500000-1002 --from 113:03 --to 120:43 --md
hex meetings chapters latest --json
hex meetings show 1790003000000-1005 --chapter 2
hex meetings show latest --srt > call.srt   # Labs › Subtitle export
hex meetings search 'release schedule'

History 过滤器先于 limit 生效¶

history 返回成功的保留结果，包括 Send 和 Voice Action。每个结果都包含时间戳、应用程序、记录的处理模式（如果存在）以及最终文本。--raw 会添加存储的预处理转录文本。较旧的条目可能没有应用或模式；Hex 不会推断缺失的元数据。

• --since 是包含边界，--until 是排他边界。仅提供日期表示当地时间午夜；--until 2026-10-20 包含 10 月 20 日的全部时间。
• 时间支持 3d、36h、90m、2w、today、yesterday、now、日期、本地日期时间、RFC 3339 或 Unix 毫秒（10 位数值为秒）。相对时间从查询时间向前回溯计算。
• --app 匹配完整应用程序名称，忽略大小写。
• --grep 在原始或最终文本中进行不区分大小写的字面子串匹配；当未使用 --raw 时也会匹配原始文本。它不是正则表达式。
• --search QUERY 使用会议搜索对最终文本和原始文本进行词干化、模糊的 BM25 排序，因此 bord 可以找到 board，scheduling 可以找到 schedule。带引号的短语必须是精确的（词干化后）匹配。未匹配的条目会被丢弃。它可与其他过滤器组合使用，但不能与 --oldest-first 一起使用。统计仅覆盖过滤后且未过期的条目，因此分数只在单次响应内可比较，不能跨查询比较。
• 结果按时间戳再按 ID 排序，最新的在前；使用 --search 时，按分数再按最新排序。--oldest-first 反转时间顺序。--limit 默认值为 50，接受 1–10,000。
• 保存的保留时间窗口会在应用下次清理之前就过滤掉过期的条目。缺少设置时默认使用七天。无效设置会直接报错，而不是静默扩大保留窗口。Off 会保留现有条目并阻止新条目，这与 History 面板的行为一致。

History 统计汇总保留的内容¶

history stats（Labs › 听写统计，hex labs on history-stats，默认关闭）打印保留条目的摘要：听写次数、词数（按空白字符切分的插入文本）、每分钟词数（词数除以录制的音频分钟数，仅统计包含音频的条目；没有任何音频时未知）、Output 更改的条目数（插入文本与转录文本不同，忽略周围空白字符）、连续天数（有条目的连续本地天数，截止到今天；如果今天还没有，则截止到昨天）、活跃天数，以及使用最多的五个应用程序。当此开关关闭时，该命令会失败，并在读取 History 之前指出开启该功能的命令。--since 和 --until 使用相同的时间语法来缩小范围；保留窗口始终生效。它只统计 History 仍保留的内容：保留机制移除某条条目后，该条目的任何信息都不会保留；同时也不会跟踪哪些替换已触发。

会议使用与 MCP 相同的查询¶

meetings list 默认为 20 条（最多 200 条）。它接受 --since 和 --until，时间语法与 history 相同。会议的持续时间与范围有重叠时才会被计入；结果按最新优先排序。进行中的录音也会包含并加以标注。不可读的文件夹会被报告，但不会被修复。要补看伴随应用离线期间已结束的会议，可以从保存的光标开始列取，并按 id 去重（streams.md）。

meetings show 接受精确 ID、至少六个字符的无歧义前缀，或 latest（最新的可读会议，包括正在进行中的会议）。默认输出和 --md 返回完整的 Markdown，包含元数据、存储的笔记和说话人轮次。--json 返回带相对毫秒偏移量的转录条目。不会生成笔记或转录文本。

--from 和 --to 可将 show 限制为会议的一部分，并适用于两种输出。它们接受会议内的偏移量，格式为 mm:ss（分钟可超过 59，如 113:03）、h:mm:ss 或秒（90、1.14、90s、1.5m），并四舍五入到毫秒；两者均可省略。分钟和小时必须是整数，秒数保持小于 60，h:mm:ss 中的分钟同样小于 60；负数、无限或溢出的偏移量会被拒绝。所有与范围重叠的条目都会完整包含，因此第一条和最后一条可能早于 --from 开始，或晚于 --to 结束。Markdown 会添加 - Range: 行；JSON 会添加 range。如果 --from 等于或晚于 --to（省略 --from 时为 0，因此 --to 0 会失败），或等于或晚于会议结束时间，都会报错。进行中的录音会一直运行到当前时间，因此超出其截至目前的滚动转录文本的范围是空结果而非错误；超出当前时间的范围则会以 “so far” 报错。MCP 的 get_transcript 工具接受相同的范围，可用 start/end，或作为独立 schema 字段的 from/to；为同一个边界同时提供两个名称会报错。

meetings chapters 列出会议通过 live-chapters 实验记录的分章：编号、mm:ss–mm:ss 跨度、模型撰写的名称和一行简介，以及这些边界在 Stop 之后是否被修正。它接受与 show 相同的 ID。没有分章的会议会说明这一点（文本）或返回空的 chapters 列表（JSON）；不会生成任何内容。show --chapter N 只返回第 N 章（从 1 开始计数）的条目，在 Markdown 中使用 ## <name> 章节，在 JSON 中使用 chapter；它不能与 --from/--to 组合使用，如果数字不在列表中则会报错。普通的 show Markdown 在存在分章时会添加 ## Chapters 列表。

show --srt 和 show --vtt（Labs › 字幕导出，hex labs on subtitle-export，默认关闭）改为将带时间轴的字幕输出到 stdout，例如 hex meetings show latest --vtt > call.vtt。当该开关关闭时，它们会在读取任何会议之前失败，并指出用于打开该功能的命令。它们与其他输出接受相同的 ID、--from/--to 和 --chapter，并与 --md、--json 以及彼此互斥。每个转录条目（一次说话人轮次）成为一条提示（cue），其时间由该条目相对于会议开始的时间偏移决定，而不是根据单词时间决定：SRT 对提示进行编号，使用 HH:MM:SS,mmm 时间格式，并在文本前加上 You: 或 Them:；VTT 以 WEBVTT 开头，使用 HH:MM:SS.mmm 时间格式以及 <v You>/<v Them> 声音标签，并转义 &、< 和 >。结束时间早于开始时间时会被钳制为开始时间；没有文本的条目会被跳过；文本中的空行和 --> 会被移除，从而防止一条提示被打断。

meetings search QUERY 对转录文本和存储的笔记使用 MCP 查询中基于词干（stemmed）的模糊 BM25 排名。带引号的短语会限制搜索范围。支持 --since、--until 和 --limit（默认 10，最大 50）；输出为文本。可以先搜索时间戳，再用 show --from/--to 读取其前后的内容。

精确词干明显胜过模糊匹配。与每个未加引号的词项都精确匹配的段落排在前面，无论其得分如何。在同一层级内，一个前缀的权重是精确词干的一半，一个或两个编辑距离为 0.35，Soundex 谐音匹配为 0.2；这些权重也适用于一个段落所覆盖词项的比例。拼写回退（编辑距离和谐音匹配）仅对在少于三个段落中被精确找到的词项尝试，并且绝不会匹配到在被搜索段落中占比超过 0.5% 且至少出现在五段中的词；但若一个词项没有精确匹配，它仍可匹配到与之相距一个编辑距离的常见词（绝不会相距两个编辑距离）。因此，一旦有三个段落写出 blob，blob 就不会再匹配到 blog、Bob 或 believe；media 也不会匹配到像 made 这样常见的词。当一个段落中有多个词可以代表同一个词项时，精确词干优先；然后是得分更高、更可信的匹配，接着是字母顺序排在最前的词，因此结果在不同运行之间永远不会变化。hex history --search 使用相同的排名，将一条条目的原始文本和最终文本计为一个文档（因此同时出现在两者中的词只计一次），并以其中更好的文本作为命中内容。

在启用 vocabulary 实验功能时，两个搜索（以及 MCP search_transcripts）还会从 settings.json 中读取已保存的 词汇表，而不会加载或迁移它。如果查询词是一个单词的词汇条目，那么它还会匹配到该条目的“听起来像”（sounds like）拼写、将该条目拆分为两个相邻单词的形式（0.5，如同前缀），以及听起来像它的词（0.3），除非这些词是常见词。这两者都不会被视为精确匹配。

调试构建保留了 meeting record、watch、probe、transcribe 等开发者命令。它们的 meeting list/show 命令也使用只读查询路径。复数形式的 meetings 命令在发布构建中可用。

JSON 版本 1¶

每个 JSON 响应都包含整数 version: 1。调用方应忽略未知字段；不兼容的字段变更需要新的版本号。所有 *_ms 字段都是整数毫秒。绝对时间戳使用 Unix 时间。可空字段以 null 形式出现，但以下字段除外：raw_text 在未使用 --raw 时省略；score 和 snippet 在未使用 --search 时省略；range 在未使用 --from 或 --to 时省略；chapters 在会议没有章节时省略；chapter 在未使用 --chapter 时省略。JSON 输出到 stdout；错误输出到 stderr，并以非零退出状态结束。空结果也是成功响应。truncated 报告的是查询的输出限制，而不是已经过期或已从存储中逐出的数据。

type History = {
  version: 1
  retention: "off" | "day" | "week" | "month" | "forever"
  truncated: boolean
  entries: {
    id: number
    timestamp_ms: number
    application: string | null
    mode: string | null
    kind: "dictation" | "send" | "voice_action" | "printed" | "raw"
    final_text: string
    raw_text?: string // present only with --raw
    score?: number // present only with --search; higher is more relevant
    snippet?: string // present only with --search; matches wrapped in **
  }[]
}

type HistoryStats = { // hex history stats --json
  version: 1
  retention: "off" | "day" | "week" | "month" | "forever"
  dictations: number
  words: number
  audio_ms: number
  words_per_minute: number | null // null without recorded audio
  changed_by_output: number
  streak_days: number
  active_days: number
  top_apps: { application: string; dictations: number }[] // at most 5, most first
}

type Meeting = {
  id: string
  title: string
  timestamp_ms: number
  duration_ms: number
  application: string | null
  status: "starting" | "recording" | "transcribing" | "complete" | "interrupted" | "failed"
  in_progress: boolean
  transcript_source: "final" | "rolling" | "missing" // older builds also reported "draft"
  warnings: string[]
}
type MeetingList = {
  version: 1
  meetings: Meeting[]
  skipped: { id: string; reason: string }[]
  truncated: boolean
}
type MeetingShow = {
  version: 1
  meeting: Meeting
  notes: { title: string; summary: string; generated_at_ms: number } | null
  range?: { from_ms: number; to_ms: number | null } // only with --from or --to
  chapters?: Chapter[] // only when the meeting has chapters
  chapter?: Chapter // only with --chapter
  entries: { // with a range or chapter, only the entries in it
    source: "microphone" | "system" // You / Them; remote speakers aren't separated
    start_ms: number // relative to the meeting start
    end_ms: number
    text: string
  }[]
}
type Chapter = {
  number: number // counting from 1
  title: string // model-written
  summary: string // one line; may be empty
  start_ms: number // relative to the meeting start
  end_ms: number // the next chapter's start, or the meeting's end (now while recording)
}
type MeetingChapters = {
  version: 1
  meeting: Meeting
  chapters: Chapter[] // empty when none are stored
  refined: boolean // boundaries corrected over the whole transcript after Stop
}

读取操作从不启动或更改应用¶

这些命令在日志记录、实例锁定、本地 API 启动、权限、GUI 和 Hex Microphone 之前分派。它们不会打开麦克风、加载模型、发出网络请求，也不会创建任何文件或目录。历史记录读取一个文件描述符，因此原子替换会产生完整的旧快照或新快照。格式错误的历史记录会产生错误，而不会进行恢复性写入。

数据来自 ~/Library/Application Support/hex。HEX_APPLICATION_SUPPORT_DIR 会覆盖根目录，用于测试夹具或镜像副本（Windows 上为 %APPDATA%\hex，Linux 上为 ~/.local/share/hex 或 $XDG_DATA_HOME/hex）。这些命令在所有 OS 上均可用。

保留策略仍限制在单一存储中¶

历史记录上限现在为 10,000 条，或原始文本加最终文本共 16 MiB，以先达到者为准，此前的上限为 2,000 条 / 4 MiB。每条目限制、仅所有者可读的文件、原子替换、过期、显式删除以及“全部清除”仍与历史记录窗格共享。已被驱逐的较旧条目无法通过此更改恢复。

保持单一存储可避免另一套过期和删除规则。月度归档需要原子轮换、ID 去重、空闲时过期以及跨每个文件的删除。更大的上限是使用现有存储进行的有界增量；它仍会在每次成功结果时重写 JSON 文件。该上限并不保证在选定时间窗口内保留每个结果，而且“永久”选项也有硬性上限。不会创建单独的归档。