harmony-next

HarmonyOS NEXT エージェントガイド

このスキルは、同梱のオフラインリファレンスを使って HarmonyOS NEXT に関する質問に回答するためのものです。コンテキストは小さく保ちます。まずリクエストを振り分け、回答またはアクションに必要な特定の Markdown ファイルだけを開いてください。

references/... や scripts/... のようなパスは、このスキルのディレクトリ、つまり SKILL.md を含むディレクトリからの相対パスです。そのディレクトリは HARMONY_NEXT_SKILL_DIR として一度だけ解決してください。現在のリポジトリルートに harmony-next/ があると想定しないでください。公式のスキャン対象ディレクトリには、$REPO_ROOT/.agents/skills/harmony-next、$HOME/.agents/skills/harmony-next、/etc/codex/skills/harmony-next があります。

# Directory containing this SKILL.md (the file you loaded).
HARMONY_NEXT_SKILL_DIR="<skill-dir>"

通常のアプリケーションリポジトリのルートを含め、どの作業ディレクトリからでも $HARMONY_NEXT_SKILL_DIR を使用してください。同梱のプレイブックでは、実行可能ファイルのパスにこの変数を使用する必要があります。同梱のプレイブックにリポジトリルートを固定したスキルのプレフィックスがある場合は、移植性の不具合として扱ってください。

バージョン

現在のローカルスキルバージョン：v1.3.37。

リファレンスのスナップショット：同梱の references/ は、HarmonyOS API 12〜23 のオフラインスナップショットであり、最新のウェブドキュメントではありません。HarmonyOS SDK 26.0.0（API 26.0.0）は 2026-08-29 にリリースされました。API 26 の宣言ページは references/JsEtsAPIReference/api26/ に同梱されています。包括的なガイドとサンプルは引き続き準備中です。

「最新」や「現在」の情報、新しい API、オンラインドキュメントとの整合性に関する質問では、このローカルバージョンを GitHub Releases または nightly と比較し、精度が重要な場合は Huawei のオンラインドキュメントで API の動作を確認してください。

API 26 のリリース状況と適用に関するメモ：references/harmonyos-releases/api-26-release.md。

インストール／更新のエントリーポイント：

• Vercel Labs skills CLI：npx skills add linhay/harmony-next.skills --skill harmony-next。対話なしで Claude Code にグローバルインストールする場合は -a claude-code -g -y --copy を、Codex の場合は -a codex -g -y --copy を追加します。
• Gemini CLI：gemini skills install https://github.com/linhay/harmony-next.skills --path harmony-next --scope user
• Claude Code：npx skills add linhay/harmony-next.skills --skill harmony-next -a claude-code -g -y --copy を使用します。Claude.ai では、引き続きリリース版の harmony-next.skill.zip をアップロードする方法も使えます。
• Codex：npx skills add linhay/harmony-next.skills --skill harmony-next -a codex -g -y --copy を使用するか、公式の Codex スキャン対象ディレクトリ（$REPO_ROOT/.agents/skills/harmony-next、$HOME/.agents/skills/harmony-next、/etc/codex/skills/harmony-next など）に harmony-next/ を配置またはシンボリックリンクします。再利用可能なインストール用配布物にするには、Codex プラグインとしてパッケージ化してください。

ルーティング

1. ユーザーのリクエストを分類する

   • API、コンポーネント、エラー、またはコード例：KITS.md、TASK_MAP.md、INDEX.md を使用し、DevEco のプレイブックは読み込まないでください。
   • 最小限のプロジェクトフィクスチャ、Empty Ability のひな形、HDC/uitest のスモークアプリ、またはコピーして使える HarmonyOS テストプロジェクト：references/quickStart/ets/minimal-project-scaffold.md と references/templates/empty-ability-app/ を使用してください。
   • DevEco Studio IDE、プラグイン、ローカルサービス、CodeGenie、MCP、LanceDB、devecostudio://、UxTestService、またはオフラインの UI/UX 監査：IDE プレイブックを読み込んでください。
   • HarmonyOS Command Line Tools のダウンロード、アーカイブのインストール、PATH の設定、または codelinter -v による検証：references/ideGuides/独立命令行工具配置手册.md を読み込み、scripts/commandline_tools_manager.py を使用してください。
   • HarmonyOS Emulator、HVD、hdc、uitest、aa、bm、hilog、または hidumper の自動化：Emulator プレイブックを読み込んでください。
   • ArkWeb/WebView DevTools の転送、CDP Runtime.evaluate、または H5 ブリッジのフィールド到達の証明：references/ideGuides/ArkWeb WebView CDP调试与字段到达证明.md を読み込んでください。
   • 不明な分野：まず references/TASK_MAP.md を確認し、その後 references/INDEX.md で絞り込んでください。

2. 最小のインデックスを選ぶ

   • Kit ナビゲーション：references/KITS.md
   • タスク別ナビゲーション：references/TASK_MAP.md

3. 対象ファイルを見つける

   • 全リポジトリのパス一覧：references/INDEX.md
   • JS/ETS API の分類別一覧：references/JsEtsAPIReference/INDEX.md

4. 対象のリファレンスのみを開く references/JsEtsAPIReference/ は現在、主に modules/、topics/、types/、errors/、guides/ で構成されています。

   • guides/ には、よく参照される公式オンラインガイドへのリンクに代わる、オフラインのガイドページが含まれています。

検索コマンド

この SKILL.md から HARMONY_NEXT_SKILL_DIR を解決した後：

• まずキーワードでパスを検索します：rg -n "UIAbility|AbilityStage|Want" "$HARMONY_NEXT_SKILL_DIR/references/INDEX.md" | head
• @ohos.* モジュールを検索します：rg -n "@ohos\\.app\\.ability\\.|@ohos\\.ability\\." "$HARMONY_NEXT_SKILL_DIR/references/INDEX.md" | rg "JsEtsAPIReference/" | head
• NDK/C API のヘッダーファイルを検索します：rg -n "JsEtsAPIReference/topics/.*/.*\\.h\\.md$" "$HARMONY_NEXT_SKILL_DIR/references/INDEX.md" | rg "(napi|arkui|window|ability)" | head

ツールスクリプトのスキル

DevEco のセットアップコマンドを手書きする前に、これらのスクリプトベースのスキルエントリを使用してください。これらは、不安定なローカルツールを呼び出すための小規模なラッパーであり、環境に問題がある場合は構造化されたステータスを返します。

ユーザーの意図	スクリプトスキル	エージェントが最初に実行するコマンド	ユーザーへの引き継ぎ
HarmonyOS コマンドラインツールのダウンロード、インストール、設定、または検証	commandline_tools_manager.py	python3 "$HARMONY_NEXT_SKILL_DIR/scripts/commandline_tools_manager.py" doctor --tools-root <dir> --json	ユーザーが Huawei ダウンロードセンターのページ URL を提示した場合は、スクリプトのブロック結果を返し、ログインして直接アーカイブの URL をコピーするか、ローカルアーカイブを提供するよう依頼します。
ローカルの DevEco HVD インスタンスの一覧表示、クローン、削除、診断、または起動	hvd_manager.py	python3 "$HARMONY_NEXT_SKILL_DIR/scripts/hvd_manager.py" doctor --json	HVD ルート、Emulator、SDK／イメージルート、またはトレース起動データが不足している場合は、issues、recommendations、missingConfig フィールドを報告し、--root、--emulator、--sdk-root／--image-root、または対応する環境変数を指定するよう依頼します。
上限付きの HDC デバイス証拠の収集、または WebView DevTools 転送の診断	device_evidence_bundle.py	python3 "$HARMONY_NEXT_SKILL_DIR/scripts/device_evidence_bundle.py" doctor --deveco-app <DevEco-Studio.app> --json	生のローカルスクリーンショット、レイアウトツリー、アプリの状態、上限付きログをローカルに保存できる場合に限り、capture ... --artifact-dir <dir> を使用します。ソケット／fport／HTTP の検出分類には webview-devtools ... --artifact-dir <dir> を使用します。
実行前後の証拠を取得しながら、上限付きの UI 操作を 1 回実行	device_ui_action.py	python3 "$HARMONY_NEXT_SKILL_DIR/scripts/device_ui_action.py" tap --deveco-app <DevEco-Studio.app> --target <target> --artifact-dir .hvigor/outputs/<run> --text "<visible-text>" --json	ターゲットセレクターまたはデバイスの生座標のいずれか 1 つだけを指定します。返されたスクリーンショットの寸法を座標空間として扱い、拡大縮小されたプレビューの座標は再利用しないでください。
実行中の HarmonyOS ページをキャプチャし、オフラインの UI／UX 監査レポートを実行	ux_audit_pipeline.py	python3 "$HARMONY_NEXT_SKILL_DIR/scripts/ux_audit_pipeline.py" doctor --deveco-app <DevEco-Studio.app> --python <python-with-ux-deps> --json	1 回で実行する場合は python3 "$HARMONY_NEXT_SKILL_DIR/scripts/ux_audit_pipeline.py" capture-audit --deveco-app <DevEco-Studio.app> --python <python-with-ux-deps> --target <target> --artifact-dir .hvigor/outputs/<run> --json を使用します。Python の画像処理モジュールが不足している場合は、UxTestService の障害として扱わず、missingConfig=["uxPythonDependencies"] と報告します。
オフラインの DevEco Profiler トレースファイルを SQLite の証拠サマリーに変換	profiler_trace_audit.py	python3 "$HARMONY_NEXT_SKILL_DIR/scripts/profiler_trace_audit.py" doctor --deveco-app <DevEco-Studio.app> --json	trace_streamer または入力トレースが不足している場合は、機械可読な blocked ペイロードを報告します。既存の .ftrace／.htrace／bytrace／rawtrace アーティファクトに限り、audit --input <trace> --output-dir .hvigor/outputs/<run> --json を使用します。

境界：

• commandline_tools_manager.py がダウンロードできるのは、直接指定されたアーカイブ URL のみです。ダウンロードセンターのページ URL は、アーカイブではなくログインが必要なページです。
• hvd_manager.py launch-preflight は、外部トレースヘルパーがすでに準備できている場合に、ガード付きの Emulator コマンド計画を出力します。
• 現在、hvd_manager.py launch は起動トレースソケットを作成し、Emulator とトレースホルダーをデタッチして、-t <trace-name> を付けて Emulator を起動します。また、--no-wait-target が渡されない限り、HDC／ブート／安定性を待機します。
• device_evidence_bundle.py はエビデンスの取得用であり、アプリのライフサイクル制御用ではありません。実際の UI／レイアウト／ログのアーティファクトを明示的なアーティファクトディレクトリに保存することはありますが、アプリのインストール、アンインストール、起動、停止、変更は行いません。
• device_evidence_bundle.py webview-devtools は、範囲を限定した fport を1つ作成する場合があります。デフォルトでは、その実行で作成したフォワードのみを削除します。ソケット、古いフォワード、HTTP のリセット／拒否／タイムアウト、無効な JSON の失敗コードを出力します。
• device_ui_action.py は、前後のレイアウト、スクリーンショット、範囲を限定したログを取得する間に、uitest uiInput のタップ、スワイプ、キーイベントをそれぞれ1回だけ実行します。座標には、レイアウト境界から取得したデバイスの生ピクセル座標、または明示的に指定したデバイス座標を使用する必要があります。
• ux_audit_pipeline.py は、device_evidence_bundle.py と DevEco の UxTestService を組み合わせます。インポート前に tools/UxTestService をアーティファクトディレクトリにコピーするため、DevEco の .app バンドルは変更されません。
• いずれかのラッパーが blocked を返した場合、諦める前に、エージェントは公式の HarmonyOS CLI エビデンスコマンドを試す必要があります。対象は hdc list targets -v、hdc -t <target> shell uitest dumpLayout ...、screenCap、file recv、bm dump、aa dump、範囲を限定した hilog です。
• ラッパーがブロックされている、誤解を招く、または有用なワークフローを備えていない場合は、スクリプトの feedback JSON フィールドにあるシナリオ固有の GitHub issue フォーム、または ISSUE_GUIDE.md を使用してください。GitHub にアクセスでき、十分なコンテキストがある場合は、構造化フィールドを維持し、秘匿化ルールに従って、gh で issue を直接作成するか、コメントしてください。
• profiler_trace_audit.py はオフライン専用です。DevEco の trace_streamer を実行し、DevEco の .app バンドル外に SQLite／JSON アーティファクトを書き込みます。DevEco Studio の起動、デバイスへの接続、GUI Profiler のヘッドレスインポートをうたうことはありません。
• ライフサイクルの方針：今後の CLI 作業では、端末セッションに紐付いた起動モードを優先してください。このモードでは、フォアグラウンドランナーがトレースソケットを所有し、準備完了を待機します。また、端末セッションの終了時に Emulator -stop <hvd-name> -path <hvd-root> を呼び出します。デタッチモードは、明示的な互換性用の経路としてのみ維持してください。
• hvd_manager.py download-image は、HVD イメージのダウンロードを機械可読な blocked として報告します。現在確認されている方法は DevEco Studio SDK Manager の UI であり、安定した非 UI の CLI はありません。
• 複数のマシンへの対応では、回答やドキュメントにハードコードされた macOS パスを使うのではなく、doctor --json の出力を優先してください。

API 26 宣言スナップショットを同期するには、python3 "$HARMONY_NEXT_SKILL_DIR/scripts/sync_api26_snapshot.py" --deveco-app <DevEco-Studio.app> を実行してから、python3 "$HARMONY_NEXT_SKILL_DIR/scripts/reference_compat.py" generate でインデックスを再構築してください。

最小空白 Ability 骨架

エージェントが DevEco Studio を開かずにコピー可能な HarmonyOS NEXT のスモークテスト用フィクスチャを必要とする場合に使用します。

• 骨格ガイド：references/quickStart/ets/minimal-project-scaffold.md
• コピー可能なテンプレート：references/templates/empty-ability-app/
• デフォルト：bundleName com.example.emptyability、モジュール entry、Ability EntryAbility、Compatible SDK 5.0.0(12)、target SDK 5.0.0(12)。
• ルート／コンポーネントの分割：pages/Index.ets は @Entry ルートページのみを担い、SmokeCounter() をマウントします。components/SmokeCounter.ets はスモーク UI の状態とノード ID を管理します。
• 検証の実行コマンド：ohpm install、hvigorw --mode module -p module=entry@default assembleHap、HDC によるインストール／起動、uitest dumpLayout、uitest screenCap。
• SDK オーバーライドの検証：HarmonyOS 6.0.2／API 22 などの target SDK を指定する場合、コピーしたフィクスチャの compatibleSdkVersion と targetSdkVersion を 6.0.2(22) に設定し、DEVECO_SDK_HOME を SDK ルートに設定します。たとえば sdk/default ではなく、DEVECO_SDK_HOME=/Applications/DevEco-Studio.app/Contents/sdk を指定します。
• API 22 のスキーマ互換性はアプリと Ability のアイコンに依存します。テンプレート内の AppScope/resources/base/media/app_icon.png、アプリの icon、Ability の icon、および startWindowIcon はそのままにしてください。
• 安定したスモーク UI シグナル：Harmony Smoke Ready、smoke-title、smoke-counter、smoke-increment。
• インタラクティブなスモークテスト：起動後、uitest uiInput click を使用して smoke-increment の範囲をクリックし、新しい dumpLayout で tapCount=1／Harmony Smoke Tapped を確認します。

コマンドラインツールのセットアップ

ユーザーが DevEco Studio を使わずに HarmonyOS Command Line Tools のダウンロードまたは設定を求めた場合に使用します。

• 公式情報：Huawei の「获取命令行工具」ページは、エージェントを Command Line Tools のダウンロードセンターに案内し、HarmonyOS SDK がパッケージに含まれていることを説明し、${Command Line Tools解压路径}/command-line-tools/bin を PATH に設定します。
• このスキルでは、ローカルで管理された一連の操作に scripts/commandline_tools_manager.py を使用します。download --url <direct-archive-url>、install --archive <zip> --dest <dir> --profile auto、bootstrap --url <direct-archive-url> ...、configure --tools-root <dir> --profile auto、doctor --tools-root <dir> が利用できます。
• このスクリプトには、Huawei のダウンロードセンターからコピーしたアーカイブの直接 URL、またはローカルのアーカイブパスが必要です。ダウンロードセンターのページ URL が渡された場合、現在のパッケージを解決したかのように装わず、機械可読な blocked を返します。
• Huawei の整合性チェック値が入手できる場合は、--sha256 <digest> を使用します。

DevEco エミュレーターの自動化

ユーザーが IDE を使わずに HarmonyOS Emulator を起動または確認する場合、コマンドラインからエミュレーターを操作する場合、hdc／uitest／aa／bm／hilog／hidumper の自動化を診断する場合、または Charles、mitmproxy、Proxyman などの HTTP プロキシツールでシミュレーターのトラフィックキャプチャをデバッグする場合に使用します。

エミュレーター／HVD／hdc／uitest／aa／bm／hilog／hidumper に関する目的の場合に限り、このプレイブックを読みます。一般的な ArkTS、ArkUI、API、コンポーネント、エラーコードの検索では、API インデックスを参照してください。

操作する前に references/ideGuides/DevEco模拟器私有接口与AI自动化.md を読んでください。バージョンによって変わりうる非公開の挙動を扱うエージェント向けプレイブックとして扱い、パス、フラグ、出力フィールド、ポートに依存する前に、ローカルの DevEco／Emulator のバージョンを確認してください。

デフォルトの境界：

• 読み取り専用のプローブを優先してください：Emulator -version、Emulator -list -details、hdc list targets -v、uitest dumpLayout -p /dev/null -a。
• UI 操作には、hdc -t <target> shell uitest uiInputを優先して使用してください。画面上の座標を見当でクリックしないでください。
• ユーザーが「エミュレーター本体のサンドボックス／アプリのサンドボックスはどこですか」と尋ねた場合は、まず HVD の本体ディレクトリとアプリのサンドボックスを区別してください。HVD のデフォルトは~/.Huawei/Emulator/deployedです。アプリのサンドボックスはエミュレーターのシステム内にあります。まずaa dump -lでフォアグラウンドのバンドルを見つけ、次にContext.filesDir/cacheDir/databaseDirや/data/app/el2/<USERID>/base/<bundleName>などの物理パスの対応先で特定してください。shell -b <bundleName> pwdはデバッグ用の HAP 作業ディレクトリを返すだけの場合があり、データサンドボックスのパスとして扱わないでください。
• CLI から直接 Emulator を起動する際、Emulator -hvd ... -path ... -imageRoot ...を完全なコマンドとして扱うことはできません。まず、検証済みのヘルパーを使って、-t <trace-name>に対応するトレースパイプを準備し、保持しておく必要があります。この前提条件が満たされていない場合、「エミュレーターの起動に失敗しました／DevEco StudioでHuaweiアカウントにログインし、デバイスマネージャーからエミュレーターを起動してください」と表示されることがあります。この場合は、まずユーザーにログインを求めるのではなく、不完全な CLI 起動経路として分類してください。
• riskLevelと実行モードを区別してください。ユーザーはデフォルトで完全な実行権限を持ち、skill は許可や確認のために実行をブロックしません。HARMONY_NEXT_AUTOMATION_POLICY、--policy、.harmony-next-policy.jsonは、この run における自動化モード、成果物ディレクトリ、秘匿化の契約のみを記述します。
• ポリシーの段階：readonlyでは低リスクのプローブを実行します。evidenceでは、artifactDirと秘匿化メタデータを付けてスクリーンショット、layout、ログの断片、file recvを収集します。automationでは、Emulator の起動／停止、アプリのインストール／起動、UI 入力、有界の証拠収集を実行します。diagnosticでは、有界のhitraceまたはより広範なログ収集を実行します。break-glassは、フラッシュ、フォーマット、データ消去、root／daemonなどのシステムレベルの操作を示します。
• 実際のスクリーンショット、layout、ログパッケージ、file recv、インストール／アンインストール、HVD の作成／削除、ポート転送、低レベルのuinput、hitraceは、すべて非対話型のフローで実行します。target、artifactDir、秘匿化ポリシー、timeout、監査可能なコマンド記録のいずれかが不足している場合は、missingConfigとrequiredModeを含む、機械可読なblocked結果を返します。
• エミュレーターのパケットキャプチャ、HTTP proxy tools、NetworkKit proxy routing、transparent interception、システムプロキシの問題については、playbookの「エミュレーターのパケットキャプチャとプロキシの診断」を参照してください。まず、エミュレーターの NAT、デフォルトゲートウェイ、プロキシのリッスンアドレス、アプリがプロキシを明示的に使用しているかを確認してください。Mac 側のポート転送スクリプトが、すべてのエミュレータートラフィックを自動的に透過的に受け取れるかのように説明しないでください。
• 複数の target がある場合は、127.0.0.1:<port>を明示的に選択してください。Connectedのみを選択し、Offlineは無視してください。
• 目的がオフラインの UI/UX チェックの場合、エミュレーター側ではhdc／uitestを使って、実際にフォアグラウンドに表示されているページのスクリーンショットと layout のみを収集します。収集後は、DevEco Studio Private InterfacesのUxTestService offline UI/UX auditルールに従ってください。
• 分類できないコマンドにはriskLevel=unknownとマークし、sourceCommandと target を記録したうえで、ユーザーの目的に沿って続行してください。target を特定できない場合、またはコマンドが無制限のバックグラウンドタスクになる場合は、原因をmissingConfigとして、機械可読なblockedを返してください。

HVD manager command map:

コマンド	目的	主な出力
doctor --json	HVD のルート、Emulator、ビルド SDK のルート、エミュレーターイメージのルート、HDC、Emulator のバージョン、およびローカル HVD を調査します	issues、recommendations、hvdRoot、emulator、sdkRoot、imageRoot、hdc
list --json	UUID を公開せずに、登録済み HVD を一覧表示します	name、device_type、api_version、hdc_port、image_sub_path、exists
launch-preflight --name <hvd> --image-root <dir> --trace-name <name> --trace-helper-ready-file <file> --json	Emulator を起動せずに、トレースヘルパーの準備状況とイメージのルートを検証します	decision、missingConfig、emulatorCommand
launch --name <hvd> --image-root <dir> --trace-name <name> --json	現在の実装：トレースソケットを作成し、Emulator とトレースホルダーをデタッチしてから、HDC、起動、安定性を待機します	traceHolder、hdcWait、bootWait、stabilityWait、logPath
device_evidence_bundle.py doctor --deveco-app <DevEco-Studio.app> --json	hdc を特定し、接続済みターゲットの概要をまとめます	connectedTargets、missingConfig、issues
device_evidence_bundle.py capture --deveco-app <DevEco-Studio.app> --target <target> --artifact-dir .hvigor/outputs/<run> --json	起動状態、bm／aa の概要、範囲を限定した hilog、uitest dumpLayout、スクリーンショット、およびコマンド台帳を収集します	summary、artifacts、layoutSummary、commandLedger
device_evidence_bundle.py webview-devtools --target <target> --artifact-dir .hvigor/outputs/<run> --json	WebView DevTools ソケットを列挙し、古いフォワードを分類して、範囲を限定した fport を 1 つ作成し、/json と /json/version を調査します	sockets、staleForwards、fportStatus、httpProbe、failureCode
device_ui_action.py tap --target <target> --artifact-dir .hvigor/outputs/<run> --text "<text>" --json	生の境界座標を解決し、タップを 1 回実行して、実行前後の証拠を取得します	coordinateSpace、action、before、after、commandLedger
ux_audit_pipeline.py doctor --deveco-app <DevEco-Studio.app> --python <python> --json	hdc、UxTestService、接続済みターゲット、および Python UX 依存関係を特定します	uxService、uxPython、connectedTargets、missingConfig
ux_audit_pipeline.py capture-audit --deveco-app <DevEco-Studio.app> --python <python> --target <target> --artifact-dir .hvigor/outputs/<run> --json	レイアウト／スクリーンショット／ログの証拠を取得し、フォアグラウンドのバンドルを推定して、UxTestService を実行し、Markdown／JSON レポートを作成します	captureSummary、auditSummary、report、resultCounts、bundleName
ux_audit_pipeline.py audit --evidence-summary <summary.json> --artifact-dir .hvigor/outputs/<run> --json	デバイスに触れずに、既存の証拠バンドルに対して UxTestService を再実行します	checkParam、uxResult、uxSummary、report、resultCounts
launch --accept-license ... --json	オペレーターが Huawei Emulator の初回起動時の同意プロンプトを確認した後、明示的に yes と回答します	result=started または result=license-agreement-required

HVD の起動ルール：

• --sdk-root / DEVECO_SDK_HOME は DevEco ビルド SDK のルートです。エミュレーターイメージのルートとして扱わないでください。
• --image-root / HARMONY_EMULATOR_IMAGE_ROOT はエミュレーターイメージのルートです。macOS では通常 ~/Library/Huawei/Sdk です。
• launch と launch-preflight は、HVD の config.ini にある <image-root>/<imageSubPath> を検証します。失敗時は missingConfig=["imageRootSystemImage"] を返します。
• 現在の launch のデフォルトでは、トレースホルダーは 1800 秒間維持され、起動後の安定性チェックは 60 秒間実行されます。
• 初回実行時の Emulator のライセンス／同意プロンプトは、result="license-agreement-required"、missingConfig=["emulatorLicenseAgreement"] として分類されます。黙って同意しないでください。--accept-license は、同意内容を確認した後、明示的にオプトインする場合にのみ使用してください。
• HDC の準備状態に関する失敗は、failureCode として emulator_kernel_panic、emulator_crashed、stale_hdc_target、hdc_wait_timeout に分類されます。イメージとトレースの事前条件には、image_root_missing、license_agreement_required、trace_helper_unavailable が使用されます。
• 現在のデタッチされた launch の後に、別のプロセスで HAP のインストール、ディープリンク、スクリーンショットの撮影、レイアウトのダンプが必要な場合は、返された hdcWait.target を使用し、--trace-hold-seconds でトレースホルダーを十分な時間維持してください。
• アタッチされたライフサイクルのチェックリスト：ランナーはフォアグラウンドで実行し続け、トレースソケットをプロセス内に保持し、SIGINT / SIGTERM / SIGHUP を捕捉し、Emulator -stop を呼び出し、ソケットを閉じ、自身のトレースパスのみを削除して、選択したターゲットが hdc list targets -v に表示されなくなったことを確認する必要があります。
• 失敗／タイムアウトの診断情報には、存在する場合、logPath、processExitCode、hvdRuntime、hdcSnapshot、hdcWait、bootWait、stabilityWait を含めてください。

ArkWeb / WebView CDP によるフィールド到達の証拠

HarmonyOS の ArkWeb 内の H5 コードがネイティブブリッジのフィールドを受け取ったことを証明するタスクでは、references/ideGuides/ArkWeb WebView CDP调试与字段到达证明.md を読んでください。

• 利用可能な TritonKit Harmony ランタイムを優先し、上位レベルのランタイムが利用できない場合に限り、HDC/WebView CDP にフォールバックしてください。
• 最初に device_evidence_bundle.py webview-devtools を実行してください。複数のソケットがある場合は --remote-socket を明示してください。古いフォワードは、グローバルなクリーンアップを行わずに報告されます。
• 選択したページの webSocketDebuggerUrl を使い、CDP の Runtime.evaluate を awaitPromise=true と returnByValue=true で実行してください。
• 小規模で機密情報を削除したブリッジコールバック JSON を主な証拠として扱ってください。Page.captureScreenshot の完了を待たないでください。
• aa dump、レイアウト、スクリーンショットは、フォアグラウンド状態を示す補助的な証拠としてのみ使用してください。ロック画面や対象外のキャプチャは無視してください。

DevEco Studio のプライベートインターフェース

CodeGenie、ローカル AI/RAG/MCP、devecostudio://、Previewer、ArkUI Inspector、Profiler、Doctor、Diagnostic、FaultLog、UxTestService、プラグインアクション、ツールウィンドウ、サービスに関して、ユーザーから DevEco Studio の内部機能や自動化について質問された場合に使用してください。

このプレイブックを読むのは、DevEco Studio IDE／プライベートインターフェースに関する意図がある場合に限ります。通常の HarmonyOS API の検索では読み込まないでください。

操作を行う前に references/ideGuides/DevEco Studio IDE私有接口与AI自动化.md を読んでください。これは安全性を最優先するプレイブックであり、安定した公開 API リファレンスではありません。プラグイン ID、クラス名、URL スキーム、ポート範囲、ハンドラー、キャッシュパス、ローカルサービスを使用する前に、インストール済みの DevEco のバージョンとローカルパスを再確認してください。

デフォルトの境界：

• 読み取り専用で許可される操作：DevEco パッケージ内のファイルの列挙、Info.plist / product-info.json / プラグイン XML の解析、jar のクラス名と文字列のスキャン、オフラインの .htrace / faultlog / stacktrace / .arkli / .preview 成果物の分析。
• 高い機密性を伴う操作：IDE/GUI/JCEF/Preview Server/Inspector/Profiler/Debug の起動、デバイスへの接続、スクリーンショット／ログ／レイアウトの取得、ユーザー側のキャッシュやチャット履歴の読み取り、CodeGenie localhost HTTP/WebSocket の呼び出し、MCP 設定の作成、外部 LLM プロバイダーの起動。実行前に、対象、入力、成果物の保存先、機密情報の削除方針を記録してください。
• システムレベルの操作：自動ログイン、アップロード、デプロイ、キャッシュの消去、状態の削除、token/securityId/API key/プロジェクトの一部／ログ本文の公開、未知の devecostudio:// URL の隔離されていない状態での検証。ユーザーが明示的に要求した場合は、指定された対象に対して実行しますが、監査概要と機密情報の削除範囲を必ず保持してください。

CodeGenie、MCP、LanceDB、HTTP forwarding、Application Agent、Operation Analyzer、Cloud Toolkit などの機能については、監査可能な実行に進む前に、プライバシーとアカウントの境界を必ず確認してください。

UxTestService によるオフライン UI/UX 監査

オフラインでの UI/UX レビュー、UI/UX 監査、ビジュアル／レイアウト確認、クリック可能なホットスポットの確認、DevEco の UxTestService、またはシミュレーターに基づく UI 品質レポートを求められた場合に使用します。

検証済みの範囲：

• 再現可能な実行には scripts/ux_audit_pipeline.py を優先してください。doctor、capture-audit、audit をサポートしています。既定の Python に cv2、numpy、PIL、requests、scipy、skimage、werkzeug、または opencc がない場合は、--python または HARMONY_UX_PYTHON を指定してください。
• capture-audit は検証済みのワンショットワークフローです。hdc で実機の証拠をキャプチャし、レイアウトからシステム以外のフォアグラウンドバンドルを推定し、UxTestService を成果物専用のランタイムにコピーして、check_param.json を書き込み、ux_detect.main(check_param=...) を実行した後、ux_result.json、ux_summary.json、report.md、summary.json を生成します。
• 既存の device_evidence_bundle.py によるキャプチャをオフラインで再実行する、検証済みの方法は audit --evidence-summary <summary.json> です。
• 失敗した場合は、監査を断念する前に公式 CLI での復旧を優先してください。hdc／uitest を使って layout.json と screen.png を手動でキャプチャし、hdc file recv でローカルに受信してから、ux_audit_pipeline.py audit --layout ... --screenshot ... --bundle ... を再試行してください。
• 結果がブロックされた場合、ルールの出力がわかりにくい場合、または DevEco／UxTestService のバージョンがサポートされていない場合は、GitHub へのアクセスが可能で必要な情報が十分にそろっていれば、summary.json／report.md の feedback セクションを使ってリポジトリの issue を作成するか、コメントしてください。認証またはネットワークがブロックされている場合、あるいは必要な詳細が不足している場合に限り、ユーザーに issue の作成を依頼してください。検証済みのマスキング処理なしに、元のスクリーンショット、元のレイアウト JSON、全ログ、またはマークアップ画像を添付しないでください。
• DevEco の tools/UxTestService/ux_detect.py は、非公開かつバージョン依存のエンジンとして扱ってください。実行するためだけに DevEco Studio の GUI を起動しないでください。また、DevEco の .app バンドルを変更しないでください。
• 実際にフォアグラウンドで表示されている HarmonyOS ページから、hdc -t <target> shell uitest dumpLayout -p <remote.json> -a と hdc -t <target> shell uitest screenCap -p <remote.png> を使って入力データをキャプチャし、その後、.hvigor/outputs/... などの外部成果物ディレクトリに hdc file recv で両方の成果物を受信してください。
• レイアウトツリーで見つかった実際のフォアグラウンドの bundle_name を使って check_param を構築してください。poc のようなプレースホルダーのバンドル名を使うと、エンジンがページを無効または非フォアグラウンドとして分類し、多くの場合 UTS.0300 が発生します。
• ローカル実行では extend_infos.language="zh" を使用してください。zh-CN は一部のルールでメッセージキーが見つからない例外を引き起こし、通常なら有効なチェックが UTS.0201 になることがあります。
• ログ、結果 JSON、スクリーンショット、マークアップ画像は DevEco アプリのバンドル外に書き込んでください。一部の DevEco アプリバンドルのコピーは書き込み不可であり、変更するとアプリの署名に影響するおそれがあるため、変更しないでください。
• まず、実証済みの静的サブセットから開始してください。対象は 7.1.1.2.1 基本レイアウトのサブルール、7.1.1.2.2 ノッチ対応、7.1.1.3.3 ホットスポットのサイズ、7.1.1.4.4 アイコンのサイズ、7.1.1.4.5 アイコンの明瞭さ、7.1.2.1.1 ナビゲーションバー、7.1.2.6.1 ステータスバー、7.2.2.1.8 ページの余白です。そのほかのローカルルールについては、Python モジュールが存在することを確認してから使用してください。
• 安定したステータスキーとして test_state を使用してください。0 は合格、1 は問題あり、2 は該当する対象なし／無視、4 は例外または未対応のシーン、5 は実行エラーを示します。失敗した場合は、開発者向けの証拠として detail.Issues、detail.IssueComponents、detail.ErrorPath、detail.CustomDrawPath を使用してください。
• これは静的な設定の事前チェックではありません。実行中のページから取得した実際のスクリーンショットとレイアウトの成果物を解析し、デバッグ用のマークアップ画像を生成することがあります。

対応範囲を過大に主張しないでください：

• config/rule_config_en.json に記載されているルールは、すべての DevEco パッケージで利用できるわけではありません。ルールを案内する前に、設定されたモジュールをインポートするか、checkMethod/ を確認してください。
• フォントサイズ、テキストコントラスト、テキストの切り詰めなど、テキストに関するルールでは、ArkUI のフォント／スタイルメタデータが欠落しているため、プレーンな uitest dumpLayout の入力で UTS.0306 が報告されることがあります。これを製品の不具合ではなく、「このキャプチャモードでは該当するターゲットがありません」と記録してください。
• ランチャー、ロック画面、読み込みページ、白色率の高いページ、キーボードページ、Web／Flutter ページ、またはバンドルとレイアウトの不一致は、エンジンによって意図的に拒否されることがあります。
• 負のパスの検証には、変更を加えた本番ファイルではなく、分離されたフィクスチャ成果物または専用のテストアプリを使用してください。有用なスモークテストとして、一時的なレイアウト JSON 内でコピーしたクリック可能なノードの bounds／origBounds を縮小し、ホットスポットルールの出力に Issues、IssueComponents、ErrorPath、CustomDrawPath が含まれることを確認します。

Profiler トレースのオフラインエビデンス監査

既存の HarmonyOS Profiler／bytrace／htrace／ftrace／rawtrace 成果物をユーザーが持っており、DevEco Studio を開かずにオフラインでパフォーマンスのエビデンス、長時間スパンの要約、または機械可読レポートを求めている場合に使用します。

確認済みの範囲：

• scripts/profiler_trace_audit.py を使用します。まず doctor --json を実行して、DevEco の tools/profiler/dic_server/trace_streamer の場所を特定します。
• audit --input <trace> --output-dir .hvigor/outputs/<run> --json を実行すると、トレースを trace_streamer -e で SQLite に変換し、summary.json、tables.txt、meta.json、trace_range.json、counts.json、top_callstack.json、しきい値スパンの JSON ファイル、および frame_slice.json を書き出します。
• デフォルトのしきい値は 16.67ms と 33.34ms です。より厳しい、または緩やかな予算を指定するには、--threshold-ms フラグを繰り返し渡します。
• 出力はすべての .app バンドルの外部に保存してください。DevEco アプリの署名やバンドル内ファイルに影響を与えないよう、スクリプトは .app ディレクトリ内への出力を拒否します。
• これは trace_streamer を呼び出すことが確認済みの CLI ラッパーであり、ヘッドレスの DevEco Profiler GUI インポート経路ではありません。接続先で別途確認できていない限り、タイムライン UI 機能、IDE セッションのインポート、またはデバイスのトレース取得について主張しないでください。
• 製品の診断には、既存の実トレースを優先してください。合成トレースで確認できるのは変換／クエリの処理ループのみであり、スモークテストのエビデンスとして明記してください。

回答時の制約

• 全件を読み込まないでください：まず INDEX.md で該当するパスを探し、その後、対応する .md を開いてください。
• 不確かな場合はドキュメントを確認してください：API のシグネチャ、引数、戻り値は references/ 内のテキストを根拠とし、経験則で補わないでください。
• ArkUI では宣言型を優先してください：サンプルでは @Entry／@Component／build() を優先して使用します（ドキュメントで NDK またはシステムサービスと明記されている場合を除きます）。
• 頻繁に参照されるオンラインガイドへの外部リンクがある場合：まず references/JsEtsAPIReference/guides/ にオフラインページがすでに存在するか確認してください。存在しない場合は、公式の getDocumentById の本文に基づいてオフラインの入口ページを作成してから、マッピングに追加してください。同等でない API ページにリンクを無理に変更しないでください。