Witness：为AI编程代理打造的语音锚定证据记录工具

面向 AI 编程代理的语音锚定因果证据记录器。 你一边体验产品一边说话——“这个按钮点了没反应。” Witness 把每一个词都焊接到那一秒的因果证据上：点击、请求、控制台报错、DOM 变更、截图、完整的 rrweb 回放——然后交给你的 AI 编程代理一个结构化的证据包。 AI 代理看不到你看到的东西。描述一个视觉 bug 要花十分钟截图和打磨提示词——而且仍然会丢掉“为什么”。语音是最廉价的标注通道；只是一直没有记录器。

wit start 打开受管浏览器的那一刻，三路数据流并行运行： npm i -g witness-recorder # 需要 Node 18+ 以及系统 Edge/Chrome wit start http://localhost:5173 # 受管浏览器打开——说话并点击 rec 是 wit 的别名——同一个二进制，打起来更短。 无需下载，无需 API key。优先使用系统 Edge/Chrome；捆绑的 Chromium 作为回退。

手势 效果 浏览 + 说话 全程录音；点击/滚动/输入/导航自动记录；工具栏下方实时转写预览 Ctrl+点击 标记一个元素——选择器、outerHTML、组件链、红框截图 M 检查模式：悬停高亮，点击标记；拖拽裁剪区域 N 显式边界标记——⏺ ISSUE #n 分隔线；给代理的强分组提示 P 暂停/继续——所有事件和音频冻结（隐私） Esc 退出检查模式 ■ / Alt+Shift+R 停止并生成最终证据包 events.jsonl 边进行边写入磁盘——杀掉进程最多只丢失最后几百毫秒。wit recover 可以重建一切。

每个语音片段都以 SAY 块的形式落在时间线上，携带那一刻的因果爆发——无效点击、变更、报错——并附上关联截图和 DOM 快照。

wit start <url> [--lang en-US] [--duration 60] [--no-rr] [--associate] [--shot-format jpeg|webp] [--dsf 1|2] [--keyframes] wit list # 列出会话，含 url/时长/say 数量 wit open latest # 打开 review.html wit transcribe <dir> # 重新跑云端 ASR wit correct <dir> # 重新跑 LLM 文本润色 wit associate <dir> # LLM 为每个 SAY 挑选相关证据（ZHIPU_API_KEY） wit recover <dir> # 崩溃后重建产物 wit segments <dir> # 重新生成 speech-anchor 索引和 bundle wit keyframes <dir> # 渲染 rrweb → 每段关键帧 jpg wit mcp [dir] # 基于证据的 stdio MCP 服务器 wit config asr <engine> # 实时 ASR：auto|doubao-web|doubao-ime|sr|off

证据包——.witness/sessions/<ts>_<host>/ 面向代理的产物（PROMPT.md / SEGMENTS.md / session.md）始终用英文生成——对 LLM 来说最可靠的语料；你的原话保持逐字，绝不翻译。 SEGMENTS.md # 语音锚点：逐字文本 + 疑似问题 + 截图/dom 引用（代理优先读） segments/.md # 每段 bundle：逐字片段、无效点击、报错、关联截图 keyframes/.jpg # 每段 rrweb 渲染的回放帧（wit keyframes） KEYFRAMES.md # 关键帧索引 segments.json # 机器可读的分段索引（MCP 提供的内容） session.md # 时间线归档：每个 SAY 块携带其因果爆发 PROMPT.md # 可直接粘贴的交接说明 + 页面词汇表 review.html # 人类视图：语音卡片 + 音频定位 + 胶片条 + 内嵌 rrweb 回放 events.jsonl # 完整原始流，崩溃安全 rrweb.jsonl # 完整 DOM 事件流（--no-rr 可禁用） dom/.html # 导航/标记/每 30 秒的 DOM 快照 assoc.json # 可选的 LLM 证据关联建议 shots/.jpg # 点击/标记裁剪 + 周期性 + 语音段帧（--shot-format webp 可小约 35%） bodies/* # 响应体 ≤64KB（JSON 存为 .json，其余为 .txt） session.json # 元信息：url、时长、asr 引擎、计数 audio.webm / transcript.json

MCP——把证据当作 API wit mcp 通过 stdio 提供会话。把任何支持 MCP 的代理（Claude Code、Cursor、Devin）指向它，它就能精确拉取所需内容： list_segments · segment_detail(n) · session_overview · list_says · session_md · events_around(t_ms, radius, kinds) · get_errors · get_shot · get_body · get_dom_state(t) · get_asr · set_asr