dev-log

dev-log

実行時ログを HTTP リクエスト経由でローカルサービスにリアルタイムで収集し、AI が自ら読み取って分析します。スクリーンショットも、コンソール出力のコピーも不要です。AI がログを仕込み、ユーザーが操作し、AI がログを読み取ります。

使用するタイミング

以下の場面では積極的に使用します。

1. 生成したフロントエンドコードのデバッグや検証が必要と思われる場合。
2. ユーザーが「見てもらえますか」「問題があります」「なぜか確認してください」と言った場合。
3. 非同期処理のフロー（fetch、Promise、async/await）を追跡する必要がある場合。
4. 変数の実行時の値（特にユーザー入力や動的に計算された値）を確認する必要がある場合。

使用しないケース：純粋な静的コンテンツ、簡単な一度きりの確認、または純粋なバックエンド（Node サーバー側）コードの場合。後者は stdout を直接確認できます。

コマンド

すべての操作は 1 つの CLI で行い、npx @dev-log/cli を使用します。

ヒント： 初めて npx を実行すると、インストール確認（Ok to proceed?）が表示され、エージェントが自動実行する場合はそこで止まってしまいます。-y を付けてスキップすることをおすすめします：npx -y @dev-log/cli <command>。以下の例では簡潔にするため -y を省略しています。

npx @dev-log/cli start                            # 启动日志服务（端口 7331，后台 daemon）
npx @dev-log/cli gen --lang <lang> [options]      # 生成可直接粘贴的日志语句
npx @dev-log/cli logs [--session <id>]            # 读取已收集的日志
npx @dev-log/cli clear [--session <id>]           # 清除日志（不传 --session 清全部）
npx @dev-log/cli status                           # 查看服务状态
npx @dev-log/cli tunnel                           # 可选：启动 HTTPS 隧道（HTTPS 页面 / 远程访问）
npx @dev-log/cli stop                             # 停止服务
npx @dev-log/cli --help                           # 查看所有命令和选项

gen のオプション

オプション	説明
--lang <lang>	対象言語：js ts python go swift kotlin dart cpp rust java csharp php ruby
--type <type>	ログの種類 — state（デフォルト）、error、validation、click、request など
--data <expr>	データペイロード。対象言語のリテラル／式を指定します（例：{count:1}）
--ready	業務ログではなく、__ready__ 接続確認用プローブを生成します
--session <id>	sessionId を再利用します（デフォルト：新しい sess_xxxxxxxx を生成）
--url <url>	エンドポイント URL（デフォルト：http://localhost:7331）

gen はコードのみを stdout に出力します。出力を取得して、ユーザーのソースコードに挿入してください。sessionId、タイムスタンプ式、および（--ready を使用した場合は）__ready__ プローブを自動的に挿入します。

ワークフロー

1. サービスを起動する

npx @dev-log/cli start

start はバックグラウンドデーモンを fork してすぐに戻ります。nohup や & は不要で、フォアグラウンドをブロックしません。デーモンはエージェント／子プロセスとは独立して動作します。起動したことを確認します。

sleep 2 && npx @dev-log/cli status

2. session id を選択してログを仕込む

重要： デバッグ対象ごとに sess_xxxxxxxx を1 つ選択し、毎回の gen 呼び出しで同じ値を渡してください。--session を渡さずに gen を 2 回続けて呼び出すと、異なるランダム ID が生成され、ログが別々のセッションに分割されてしまい、意味がなくなります。必ず --session <同じ id> を指定してください。

まず接続確認用プローブを生成し、次に業務ログを生成します。

# 连通性探测（始终第一个）
npx @dev-log/cli gen --lang js --ready --session sess_a1b2c3d4

# 业务日志
npx @dev-log/cli gen --lang js --type state --data '{count: count}' --session sess_a1b2c3d4
npx @dev-log/cli gen --lang js --type error --data '{msg: err.message}' --session sess_a1b2c3d4

各出力コードを、ユーザーのソースコード内の該当する位置に挿入します。

モバイル／HTTPS ページ： デフォルトの http://localhost:7331 はローカル HTTP ページでのみ使用できます。HTTPS ページ、モバイル端末、リモートマシンでは、トンネルを起動して --url を渡してください。

npx @dev-log/cli tunnel          # https://xxxx.loca.lt を出力
npx @dev-log/cli gen --lang js --ready --session sess_a1b2c3d4 --url https://xxxx.loca.lt

3. ユーザーに操作を依頼する

ユーザーに「重要な箇所にログを追加しました。操作してください」と伝えます。

4. ログを読み取って分析する

ユーザーが「完了しました」と言ったら、ログを読み取ります（他のセッションのデータを読み込まないよう、必ず自分の session id でフィルタリングしてください）。

npx @dev-log/cli logs --session sess_a1b2c3d4

__ready__ プローブを基に診断します。

__ready__ の有無	診断
✅ 存在し、業務ログもある	業務ログを分析します。完了です。
✅ 存在するが、業務ログがない	プローブはサービスに到達していますが、ログを仕込んだコードが実行されていません。イベントバインド／トリガー条件／ユーザーが実際に操作したかを確認してください。
❌ プローブがまったくない	ネットワークの問題です。ページからサービスに接続できていません。HTTPS ページから HTTP エンドポイントにリクエストしている可能性があります（MIXED_CONTENT）。トンネル URL に変更してください。

セッションのクリーンアップ

サービスはセッション間で共有されています。 会話が終了したという理由だけで、サービスを kill したり clear（--session なし）を実行したりしないでください。

デバッグ対象の作業が完了したら：

npx @dev-log/cli clear --session sess_a1b2c3d4     # 只清除本会话的日志
npx @dev-log/cli status                            # 是否还有其他活跃会话？

status でアクティブなセッションがゼロと表示される場合にのみ、サービスを停止します。

npx @dev-log/cli stop

セキュリティ

• 機密情報は絶対に記録しないでください。 データに認証情報が含まれる場合は、記録する前に機密フィールドをフィルタリングしてください。
• 機密フィールド名（大文字・小文字を区別しません）：password、pwd、token、secret、apikey、key、credit、cvv、ssn、auth。

// 记录前剥离敏感字段
const safe = (o) => {
  const k = ['password','pwd','token','secret','key','credit','cvv','ssn','auth'];
  return Object.fromEntries(Object.entries(o).map(([n,v]) =>
    [n, k.some(s => n.toLowerCase().includes(s)) ? '***' : v]));
};

備考

1. サービスはログと PID を $TMPDIR/dev-log/（システムの一時ディレクトリ）に書き込みます。インストール済みパッケージのディレクトリはクリーンな状態に保たれます。
2. ポートは 7331 に固定されています。ランダムポートは使用せず、ポートファイルを読み取る必要もありません。
3. start はバックグラウンドデーモンとして実行されます。nohup／& は不要です。npx @dev-log/cli stop で停止します。
4. リリース前に、デバッグ用に仕込んだコードを必ずすべて削除してください。
5. ローカル開発専用です。パブリックインターネットに公開しないでください。