01 · インストール

あなたが入れるのではなく、エージェントが入れます。

基本の流れ：あなたが指示し、エージェントがコマンドを叩きます。Witness は CLI（wit）で、システムの Edge/Chrome を動かします（無い場合のみ同梱 Chromium にフォールバック）——クラウドアカウント不要、キー不要。

エージェントにこう言う

witness をインストール：`npm i -g github:wookat/witness` を実行、
`wit --version` で確認。Node 18+ が必要です。

マシンに入るもの

wit CLI —— レコーダー、session レンダラー、トランスクライバー、MCP server がひとつ。設定はプロジェクトの .witness/config.json に永続化；doubao-ime エンジンの認証情報は ~/.witness/doubao-creds.json にキャッシュ。エビデンスは常にカレントプロジェクトの .witness/sessions/ に落ちます。

Witness を知らないエージェントに教える

リポジトリには skills/witness/SKILL.md が同梱——そのまま使える skill ファイル。CLAUDE.md / .cursor/rules/ / AGENTS.md に入れれば、「録画して」の一言でワークフロー全体が起動します。見る ↗

エージェントが実際に実行するコマンド

# 透明のために——内部でエージェントが叩くのは：
npm i -g github:wookat/witness
wit --version

02 · 設定

既定はゼロ設定。必要な時だけ切替。

ライブ ASR エンジン

wit config asr はプロジェクトの .witness/config.json に永続化；--asr / WIT_ASR でその場だけ上書き。エージェントは 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 を開き、エージェントが録画中の
                 ブラウザを運転してテスターになれる

03 · 使い方

3文。それがループの全部です。

エージェントとの会話

あなた → "http://localhost:5173 を録画して"
agent → `wit start` を実行、管理ブラウザが開く あなた → 普通にプロダクトを使い、気づいたことを話して問題をマーク あなた → ツールバーの ■（または「止めて」と伝える） あなた → "さっきの録画の問題を直して"
agent → session.md を読み、エビデンスに沿って修正

あなたの役目 —— ブラウザ内

話す + 指す

話す         すべての気づき → タイムスタンプ付き SAY
Ctrl+クリック 要素をマーク（selector + ショット + DOM）
M            inspect モード：ホバー選択 / ドラッグで範囲
N            新しい問題の境界（任意）
P            一時停止/再開——エビデンスもマイクも凍結
■ / Alt+Shift+R   停止

エージェントの役目 —— 実行しうるコマンド

CLI の全面

wit start <url>       録画開始（エージェントが起動）
wit list / open       session を閲覧
wit transcribe <dir>  文字起こしを再実行
wit correct <dir>     LLM 仕上げ（原文は保持）
wit associate <dir>   LLM が各 SAY にエビデンスを選択
wit recover <dir>     クラッシュ後に再構築
wit mcp [dir]         MCP 経由でエビデンスを提供
wit config asr …      エンジン：auto|doubao-web|doubao-ime|sr|off

04 · 得られるもの

ひとつのパケット、ふたつの読者。

あなたへ：ビジュアルなリプレイ。エージェントへ：そのまま直せる構造化された引き継ぎ。

.witness/sessions/<タイムスタンプ>/

├─ review.html → 人間向け —— タイムラインリプレイ：音声+ショット+イベント、クリックでシーク
├─ SEGMENTS.md → エージェント向け —— 発話セグメント索引：逐語+容疑要素+ショット参照（最初に読む。セグメント≠問題、グループ化はエージェント）
├─ keyframes/ → セグメントごとの rrweb レンダリング再生フレーム（wit keyframes）
├─ segments/NN.md → エージェント向け —— セグメント別バンドル：逐語+無反応クリック+エラー+ショット
├─ PROMPT.md → エージェント向け —— 引き継ぎ文書：このエビデンスの読み方
├─ session.md → エージェント向け —— 完全なタイムライン記録（掘り下げ用）
├─ events.jsonl → 生イベントストリーム（実録で 1189 件）
├─ transcript.json → 最終文字起こし、セグメントタイムスタンプ付き
├─ audio.webm → 録音本体、シーク可能
├─ shots/ → スクリーンショット——マークは赤枠、範囲選択は切り抜き
├─ bodies/ → リクエスト/レスポンスのペイロード
├─ dom/ → 重要な瞬間の DOM スナップショット
├─ rrweb.jsonl → 完全なリプレイストリーム
└─ session.json → メタ：url、時間、ASR エンジン、件数

PROMPT.md

エージェントに貼るための文書。フォーマットを教えます：因果インデント、「無反応もエビデンス」、コンポーネントチェーン、SAY なしに意図を推測しない。

session.md

エビデンスのタイムライン本体。各 SAY ブロックにあなたの逐語と、その秒にページで起きた全部が載ります。

wit mcp

セッションを stdio MCP server として提供——12 ツール：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。

05 · エージェントへの伝え方

エビデンスを渡す3つの方法。

いちばん簡単

ディレクトリを指す

"録画しました。エビデンスは
.witness/sessions/<ts> にあります。
session.md を読んで問題を直してください。"

どんなエージェントにも

PROMPT.md を貼る

ファイル自体が読み方のガイド。内容とディレクトリパスを貼れば、Witness を知らないエージェントでも動きます。

常設

MCP を配線

{ "mcpServers": { "witness": {
  "command": "wit", "args": ["mcp"]
} } }

エージェントが必要な時だけエビデンスを取得——ASR エンジンの切替も自分でできます。

エージェントに録画させるには："witness で http://localhost:5173 を録画して。問題は口頭で指摘します"。WIT_CDP を設定すれば、エージェントは録画中のブラウザ内でテスター本人になることもできます。

あなたが話す。エージェントがコマンドを叩く。