dingtalk_channel_connect

DingTalk チャネルの自動接続（画面表示ブラウザー）

このスキルは、画面表示ブラウザーを使用して DingTalk アプリケーションを作成し、QwenPaw チャネルをバインドします。

必須ルール

1. 必ず画面表示モードで起動してください：

{"action": "start", "headed": true}

2. ログイン画面が表示されたら、必ず一時停止してください：

   • ページにログイン画面（ログインの案内、QR コードログイン、電話番号／パスワードログインなど）が表示された場合は、自動操作を直ちに停止してください。
   • まずユーザーに手動でログインするよう明確に案内し、「ログイン完了／続行」と返信するまで待機してください。
   • ユーザーが確認するまで、後続の手順に進まないでください。

3. アプリケーションの設定変更は、新しいバージョンを作成して公開した後にのみ反映されます：

   • ボット関連の情報を設定した後は、必ずボットを公開してください。
   • 新しいアプリケーションを作成する場合も、アプリケーション情報（名前、説明、アイコン、ボット設定など）を変更する場合も、最後に**「新しいバージョンを作成＋公開」**を必ず実行してください。
   • 公開が完了していない場合は、設定が有効になったと伝えないでください。

実行前の確認（最初に必ず行うこと）

自動クリックを始める前に、ユーザーに「設定の確認」を行い、カスタマイズできる項目、画像の仕様、デフォルト値を明確に伝えてください。以下の形式で確認します。

1. ユーザーがカスタマイズできる項目：

   • アプリケーション名
   • アプリケーションの説明
   • ボットアイコン画像の URL またはローカルパス
   • ボットメッセージのプレビュー画像の URL またはローカルパス

2. 画像の仕様を明確に（目立つように）伝えてください：

   • ボットアイコン：JPG／PNG のみ、240*240px 以上、比率 1:1、2MB 未満、角丸加工なし。
   • ボットメッセージのプレビュー画像：形式は png/jpeg/jpg、サイズは 2MB 以下。

3. デフォルト値を明確に伝えてください（ユーザーが指定しない場合は自動的に使用します）：

   • アプリケーション名：QwenPaw
   • アプリケーションの説明：Your personal assistant
   • ボットアイコン：https://img.alicdn.com/imgextra/i4/O1CN01M0iyHF1FVNzM9qjC0_!!6000000000492-2-tps-254-254.png
   • ボットメッセージのプレビュー画像：https://img.alicdn.com/imgextra/i4/O1CN01M0iyHF1FVNzM9qjC0_!!6000000000492-2-tps-254-254.png

4. ユーザーがカスタム値を指定しない場合は、最初に必ず次のように明示して返信してください：

   • 「すべてデフォルト設定（QwenPaw／Your personal assistant／デフォルト画像）を使用します。これより処理を進めます。」

画像アップロードの手順（URL とパスの両方に対応）

1. ユーザーがローカルパスを指定した場合は、そのパスを直接アップロードに使用してください。

2. ユーザーが画像リンクを指定した場合は、まずローカルの一時ファイルにダウンロードしてからアップロードしてください。

3. アップロード操作は、次の順序で行ってください：

   • まずページのアップロード項目をクリックして、ファイル選択ダイアログを表示します。
   • 次に、ローカルパスの配列（paths_json）を指定して file_upload を呼び出します。

4. 画像の仕様（寸法、比率、サイズ、形式）が合わずアップロードに失敗した場合：

   • 自動操作を直ちに一時停止してください。
   • 条件を満たす画像を手動でアップロードするよう、ユーザーにはっきり依頼してください。
   • ユーザーが「アップロード完了／続行」と確認したら、現在の手順から再開してください。

アップロード時の実用的なヒント

1. file_upload の paths_json は「JSON 文字列配列」である必要があります。エスケープに注意してください：

{
  "action": "file_upload",
  "paths_json": "[\"xxx.png\"]",
  "frame_selector": "iframe[src*=\"/fe/app?isHideOuterFrame=true\"]"
}

2. ページが iframe 内にある場合は、frame_selector を含めることを推奨します。含めないと、アップロードコントロールが見つからなかったり、ファイル選択ダイアログが表示されなかったりする可能性があります。

3. file_upload を呼び出す前に、必ずアップロード項目をクリックしてください。直接呼び出すと、次のエラーになります：

   • No chooser. Click upload then file_upload.

4. ボットアイコン領域で要素を特定する際に利用できる一般的な構造上の特徴（DingTalk コンソールでは、中国語の UI ラベルが表示される場合があります）：

   • text: "* 机器人图标"（Bot Icon）
   • button: "使用应用图标"（Use App Icon）
   • button: "avatar"（通常、内部に img "avatar" が含まれています）

5. スナップショットに「使用应用图标」（「Use App Icon」）と「avatar」の両方が表示されている場合は、アップロードを開始するために avatar ボタンをクリックしてから file_upload を呼び出してください。

自動化の流れ

ステップ 1：DingTalk 開発者コンソールを開く

1. ヘッド付きモード（headed: true）でブラウザーを起動します
2. https://open-dev.dingtalk.com/ に移動します
3. snapshot を呼び出して、ログインが必要か確認します

ログインが必要な場合は、次のメッセージを表示して一時停止します。

DingTalk 開発者コンソールへのログインが必要です。自動操作を一時停止しました。開いたブラウザーでログインを完了してください。完了したら「continue」と返信してください。現在のページから操作を再開します。

ステップ 2：社内向け企業アプリケーションを作成する

ユーザーがログインを確認した後、操作を続行します。

1. 作成ページに移動します。
   • アプリケーション開発 → 社内向け企業アプリケーション → DingTalk アプリケーション → アプリケーションを作成
2. アプリケーション情報を入力します（ユーザーが指定した値を優先し、指定がない場合はデフォルト値を使用します）。
   • アプリケーション名：デフォルトは QwenPaw
   • アプリケーションの説明：デフォルトは Your personal assistant
3. 保存してアプリケーションを作成します

ページ上のテキストや構成が想定と異なる場合は、snapshot を再実行し、表示されているテキストの意味に基づいて要素を見つけ直します。

ステップ 3：ボット機能を追加して公開する

1. アプリケーション機能 の下にある アプリケーション機能を追加 をクリックし、ボット を見つけて追加します
2. ボット設定 の右側にあるスイッチをオンにします
3. ボット名、ボット概要、ボットの説明 を入力します
4. ボットアイコン をアップロードします（ユーザー指定の画像、またはデフォルト画像）。
   • ボットアイコンのラベルの下にある画像をクリックします
   • デフォルト画像 URL：https://img.alicdn.com/imgextra/i4/O1CN01M0iyHF1FVNzM9qjC0_!!6000000000492-2-tps-254-254.png
   • リンクの場合は、まずローカルにダウンロードしてからアップロードします
   • 画像が仕様を満たさない場合は一時停止し、仕様に合った画像をユーザーが手動でアップロードするよう依頼してから続行します
5. ボットメッセージのプレビュー画像 をアップロードします（ユーザー指定の画像、またはデフォルト画像）。
   • ボットメッセージのプレビュー画像ラベルの下にある画像をクリックします
   • デフォルト画像 URL：https://img.alicdn.com/imgextra/i4/O1CN01M0iyHF1FVNzM9qjC0_!!6000000000492-2-tps-254-254.png
   • リンクの場合は、まずローカルにダウンロードしてからアップロードします
   • 画像が仕様を満たさない場合は一時停止し、仕様に合った画像をユーザーが手動でアップロードするよう依頼してから続行します
6. メッセージの受信モードが Stream Mode に設定されていることを確認します（中国語 UI では Stream 模式 と表示される場合があります）
7. 公開 を選択します。確認ダイアログが表示されるので、公開を選択します。注：次のステップに進む前に、ボットを必ず公開してください

ステップ 4：バージョンを作成して公開する

1. アプリケーションのリリース -> バージョン管理とリリース に移動します
2. 新しいバージョンを作成します（設定を変更するたびに必要です）
3. バージョンの説明を入力し、アプリケーションの公開範囲を全従業員に設定します
4. ページの指示に従って公開を完了します。新しいダイアログが表示されるので、公開を確定します
5. 公開が成功したステータスを確認してから、後続のステップに進むか、「設定が有効になりました」とユーザーに伝えます

ステップ 5：認証情報を取得する

1. 基本情報 -> 認証情報と基本情報 に移動します
2. Client ID（AppKey）と Client Secret（AppSecret）はこのページにあることをユーザーに伝えます。こちらから変更は行わず、ユーザー自身でバインドするよう案内します

QwenPaw のバインド方法

認証情報を取得した後、次のいずれかの方法を選ぶようユーザーに案内します。

1. コンソールのフロントエンドで設定する方法：

   • QwenPaw コンソールで Control -> Channels -> DingTalk に移動します
   • Client ID と Client Secret を入力します

2. 設定ファイルを使用する方法：

"dingtalk": {
  "enabled": true,
  "bot_prefix": "[BOT]",
  "client_id": "Your Client ID",
  "client_secret": "Your Client Secret"
}

パス：~/.qwenpaw/config.json の channels.dingtalk セクションです。

認証情報の受け渡し要件（必須）

1. エージェントの役割は、ユーザーを認証情報ページに案内し、Client ID と実際の Client Secret を取得して表示することに限られます。
2. エージェントは、console の設定や ~/.qwenpaw/config.json を自発的に変更してはいけません。
3. 次のいずれかの方法で、ユーザー自身が認証情報を手動で入力するよう案内する必要があります。
   • コンソールのフロントエンド：Control -> Channels -> DingTalk
   • 設定ファイル：~/.qwenpaw/config.json の channels.dingtalk フィールドを編集

ブラウザツールの使用手順

通常は、次の順序で実行します。

1. headed: true を指定して start
2. open
3. snapshot
4. 必要に応じて click / type / select_option / press_key
5. ページ遷移後はこまめに snapshot
6. 完了したら stop

安定性と復旧の方針

• 最新の snapshot にある ref の使用を優先し、必要な場合にのみ selector を使用します。
• 重要なクリックやナビゲーションの後は、短時間の待機（wait_for）を入れ、直後に snapshot を再実行します。
• セッションが期限切れになった場合や、フローの途中で再ログインが必要になった場合は、いったん停止し、ユーザーがログインするまで待ってから現在の手順を再開します。
• テナント権限や管理者の承認によって自動化がブロックされた場合は、妨げとなっている内容を明確に説明し、再開前にその手順を手動で完了するようユーザーに依頼します。