masamune_ai_debugger 3.1.0

AI debug overlay and error reporting adapter for Masamune apps.

Masamune AI Debugger

---

[GitHub] | [YouTube] | [Packages] | [X] | [LinkedIn] | [mathru.net]

---

Plug-in packages that add functionality to the Masamune Framework.

For more information about Masamune Framework, please click here.

https://pub.dev/packages/masamune

Usage

A floating UI will be added to the Debug build of the Masamune app that sends instructions, screenshots, and unhandled errors to SamuraiAI. Neither the UI nor the communication will be active in Release/Profile builds.

final samurai = SamuraiMasamuneAdapter(
  projectId: "Users-mathru-Documents-github-myapp",
  modelLoadTimeout: const Duration(seconds: 5),
  indicatorTimeout: const Duration(seconds: 10),
);

void main() {
  runMasamuneApp(
    (ref) => MasamuneApp(
      masamuneAdapters: [samurai],
      home: const MyHomePage(),
    ),
    masamuneAdapters: [samurai],
  );
}

Do not embed the connection target and API key in the source code; specify them during debug startup.

flutter run \
  --dart-define=MASAMUNE_AI_DEBUGGER_ENDPOINT=https://your-tailnet-host/__samurai \
  --dart-define=MASAMUNE_AI_DEBUGGER_API_KEY=your-key

APIキーは SamuraiAI の Settings で作成します。Debug APK/IPAにも値は含まれるため、配布せず、不要になったキーは無効化してください。スクリーンショットは手動操作時、未処理エラー検出時、性能閾値超過時だけ送信されます。

フローティングアイコンはタップするとそのまま開き、長押しすると現在画面のスクリーンショットを撮影してから開きます。

Custom AI provider

SamuraiAI is the default provider. To connect another AI or backend, pass callbacks for each API operation. Custom callbacks receive semantic values instead of SamuraiAI-specific URLs or JSON payloads, so endpoint and apiKey are not required when all callbacks are supplied.

final customDebugger = AIDebuggerMasamuneAdapter(
  projectId: "my-project",
  registerRun: myRegisterRun,
  heartbeat: myHeartbeat,
  endRun: myEndRun,
  uploadScreenshot: myUploadScreenshot,
  sendRequest: mySendRequest,
  reportIncident: myReportIncident,
  uploadEvents: myUploadEvents,
);

The callback typedefs are AIDebugRegisterRunCallback, AIDebugHeartbeatCallback, AIDebugEndRunCallback, AIDebugUploadScreenshotCallback, AIDebugSendRequestCallback, AIDebugReportIncidentCallback, and AIDebugUploadEventsCallback. The corresponding AIDebuggerMasamuneAdapter.default* static functions expose the default SamuraiAI implementations. The existing post callback remains available for replacing only the low-level HTTP transport used by those defaults.

遅延の自動検出

Debugビルドでは、既存の LoggerAdapter のperformance traceを使って次を自動計測します。

• MasamuneのDocument／Collectionモデルの load・reload・next（既定5秒）
• Future.showIndicator 経由のインジケーター表示（既定10秒）

処理が終わらなくても閾値へ達した時点で、現在画面と直近ログをperformance incidentとして送信し、SamuraiAIにPlan Modeの調査セッションを作成します。同一処理は既存の重複排除と時間当たり上限の対象です。閾値以下で完了した処理は duration_ms の通常ログだけを送ります。

任意に配置した CircularProgressIndicator は画面走査しません。自動計測する場合は showIndicator を利用してください。閾値に Duration.zero を指定すると、そのカテゴリの自動incidentを無効化できます。

GitHub Sponsors

Sponsors are always welcome. Thank you for your support!

https://github.com/sponsors/mathrunet