操作手册——故事在首页。这里只管：怎么装、怎么配、怎么用、证据包里有什么。
正确姿势是你下指令，agent 敲命令。Witness 本体是 CLI（wit），驱动你系统里的 Edge/Chrome（没有时才回退到自带 Chromium）——不需要云账号、不要 key。
安装 witness：执行 `npm i -g github:wookat/witness`， 用 `wit --version` 验证一下。需要 Node 18+。
wit 命令行——录制器、session 渲染器、转写器、MCP server 四合一。配置持久化到项目的 .witness/config.json；doubao-ime 引擎的凭证缓存在 ~/.witness/doubao-creds.json。证据永远落在当前项目的 .witness/sessions/。skills/witness/SKILL.md——现成的技能文件，放进 CLAUDE.md / .cursor/rules/ / AGENTS.md，之后说"帮我录一段"就能触发整套流程。查看 ↗# 透明起见——你的 agent 在背后敲的是：
npm i -g github:wookat/witness
wit --version wit config asr 持久化到项目的 .witness/config.json；--asr / WIT_ASR 单次覆盖。agent 也能通过 set_asr MCP 工具自己切。auto doubao-web → doubao-ime → sr doubao-web 标点最好（默认首选） doubao-ime 句级时间戳、数字 ITN 更好 sr 浏览器 SpeechRecognition（离线兜底） off 不要实时字幕（只出终稿）
OPENAI_API_KEY whisper-1 词级时间戳
ZHIPU_API_KEY GLM-4 纠错 + 语义证据关联
WIT_ASR 单次录制覆盖引擎
WIT_NO_BODIES=1 不抓响应体（敏感应用）
WIT_CDP=<端口> 开 CDP 口，agent 可接管录制中的
浏览器亲自当测试者你 → "帮我录一段 http://localhost:5173" agent → 执行 `wit start`，托管浏览器弹出 你 → 正常使用产品，看到什么说什么，顺手标记问题 你 → 点工具栏 ■（或对 agent 说"停了"） 你 → "按刚才录的把问题修了" agent → 读 session.md，照证据动手
说话 每句观察 → 带时间戳的 SAY Ctrl+点击 标记元素（selector + 截图 + DOM 快照） M 检视模式：悬停点选 / 拖拽圈选区域 N 切分新问题边界（可选） P 暂停/继续——证据和麦克风一起冻结 ■ / Alt+Shift+R 停止
wit start <url> 开录（由 agent 发起） wit list / open 浏览 session wit transcribe <dir> 重跑转写 wit correct <dir> LLM 润色（原文保留） wit associate <dir> LLM 给每段话挑证据 wit recover <dir> 崩溃重建 wit mcp [dir] MCP 服务拉证据 wit config asr … 引擎：auto|doubao-web|doubao-ime|sr|off
给人：可视化回放。给 agent：能直接修问题的结构化交接。
├─ review.html → 给人看 —— 时间轴回放：语音+截图+事件对齐，点哪跳哪 ├─ SEGMENTS.md → 给 agent —— 语音段索引：原话+嫌疑元素+挂图（先读；段≠问题，归组归 agent） ├─ keyframes/ → rrweb 回放渲染的每段关键帧（wit keyframes） ├─ segments/NN.md → 给 agent —— 每段一包：逐段原话+死点击+报错+截图引用 ├─ PROMPT.md → 给 agent —— 交接文档：教它怎么读这份证据 ├─ session.md → 给 agent —— 全量时间轴档案（深挖时用） ├─ events.jsonl → 原始事件流（真实一次录制 1189 条） ├─ transcript.json → 终稿转写，带句级时间戳 ├─ audio.webm → 录音本体，可 seek ├─ shots/ → 截图——标记元素带红框、圈选是裁切图 ├─ bodies/ → 请求/响应体 ├─ dom/ → 关键时刻的 DOM 快照 ├─ rrweb.jsonl → 全量回放流 └─ session.json → 元数据：url、时长、ASR 引擎、事件数
SAY 块带你的原话 + 那一秒页面发生的一切。list_segments · segment_detail · session_overview · list_says · session_md · events_around · get_errors · get_shot · get_dom_state · get_body · get_asr · set_asr。"我录了一段，证据在 .witness/sessions/<ts>， 读 session.md 把里面的问题修了。"
{ "mcpServers": { "witness": {
"command": "wit", "args": ["mcp"]
} } }agent 按需拉证据，还能自己切 ASR 引擎。反过来让 agent 去录："用 witness 录一下 http://localhost:5173，我会边说边指出问题"。开了 WIT_CDP 之后，agent 甚至可以亲自当测试者在录制中的浏览器里操作。