alibabacloud-vms-smart-call-by-tts

Alibaba Cloud VMS スマート音声通話

Alibaba Cloud Voice Messaging Service（dyvmsapi）を通じて、通話の意図を自然言語で説明し、AI が生成する音声通話を開始します。システムはユーザーのアドレス帳から宛先を自動的に照合し、LLM で読み上げる内容を生成します。

アーキテクチャ：Alibaba Cloud VMS (dyvmsapi) + SubmitIntent API + LLM Content Generation + Contact Book Matching

⚠️ パス選択ルール（必ず以下の順序で従ってください）：

1. 必ず最初にイントラネットのプライマリパスを試してください：§1 に進み、イントラネットプラグインのインストール手順（cli.aliyun-inc.com）をすべて実行します。「外部ネットワークのように見える」という理由だけで §1 を省略することは許可されません。
2. §1.3 で lookup cli.aliyun-inc.com: no such host または connection timeout が報告された場合に限り、§1.alt に切り替えてください。それ以外のエラーはすべて references/plugin-troubleshooting.md を参照して原因を特定し、ネットワーク障害として扱わないでください。
3. 外部ネットワークへのフォールバックで置き換えるのは SubmitIntent だけです：スクリプト scripts/dyvmsapi_rpc.py を経由してパブリックゲートウェイを直接呼び出します（SubmitIntent の公開範囲は引き続き非公開で、SLA はありません）。QueryCallDetailByCallId は public であり、パブリックリリース版の dyvmsapi CLI プラグインにはすでにそのサブコマンドが含まれています（aliyun plugin install --names dyvmsapi。--source-base は不要です）。外部モードでも、通話詳細のクエリには引き続きパブリック CLI プラグインを使用し、スクリプトは SubmitIntent のみを処理します。
4. ⚠️ パブリックリリース版プラグインとイントラネットオンライン版プラグインは同じ名前（aliyun-cli-dyvmsapi）を共有し、相互に排他的です — 同時にインストールできるのは一方だけで、2 つ目のインストールによって 1 つ目が上書きされます。優先事項：可能な限りイントラネットオンライン版をインストールしてください（SubmitIntent と QueryCallDetailByCallId の両方が含まれます）。イントラネットへのインストールに失敗した場合に限り、パブリックリリース版にフォールバックしてください（SubmitIntent は利用できなくなるため、スクリプトで補います）。イントラネットオンライン版を利用できる場合は、パブリックリリース版をインストールしないでください — submit-intent サブコマンドが失われます。
5. 外部ネットワークへのフォールバックを使用する場合の実行手順全体は references/external-network-fallback.md に記載されています。
6. イントラネット接続が復旧したら、ただちにプライマリパスに戻してください。 フォールバックを長期的に使い続けないでください。次の手順で切り替えてください：aliyun plugin uninstall --name dyvmsapi（単数形の --name に注意）、その後 §1.3 の aliyun plugin install ... --source-base ... を再実行してイントラネットオンライン版を再インストールします。

従来の SingleCallByTts と比べ、この機能では：

• ❌ 企業の実名認証は不要です
• ❌ サービスインスタンスのプロビジョニングや、実際の発信番号のバインドは不要です
• ❌ 音声テンプレートの作成や審査は不要です
• ✅ 設定済みのアドレス帳と、自然言語で指定した通話の意図だけが必要です

機能の範囲：この Skill は、スマート通話の開始（SubmitIntent）と通話詳細の照会（QueryCallDetailByCallId）という 2 つの機能をラップします。アドレス帳の CRUD 操作と電話番号の所有権確認は対象外です。ユーザーは Alibaba Cloud Voice Service のコンソールでそれらを実行する必要があります。

---

運用上の制約

• コンテンツのコンプライアンス：音声コンテンツは LLM によって完全に生成され、サーバー側のNGワードスクリーニングと LLM による安全性レビューの二重チェックを受けます。ユーザーが再生する文言を直接指定することはできません。
• コンプライアンスに準拠した用途のみ：合法かつ正当な通知のシナリオに限定されます。債権回収、通信詐欺、嫌がらせ、その他の不正な用途は厳禁です。
• 1回の呼び出しにつき発信先は1件：各呼び出しで一致する連絡先は1件のみです。グループ通話には対応していません。複数の受信者に通知する場合は、呼び出しを個別に実行してください。
• 電話番号の安全性：電話番号が LLM に渡されることはありません。番号の検索と発信はサーバー側で行われます。
• 電話番号ごとのレート制限：同じ番号には、1分あたり1回、1時間あたり5回、24時間以内に20回まで発信できます。
• アドレス帳のサイズ制限：ユーザー1人あたり最大200件の連絡先を登録できます。

---

1. インストール

[MUST] 手順1.1 → 1.2 → 1.3 → 1.4を必ず順番どおりに実行してください。手順を省略しないでください。失敗した場合は、references/plugin-troubleshooting.mdを参照してください。

1.1 [MUST] Aliyun CLIがバージョン≥ 3.3.8でインストールされていることを確認する

# Note on --user-agent scope:
# Aliyun CLI system / tooling commands (`version`, `configure`, `plugin`,
# `upgrade`, `oss`, `auto-completion`, `mcp-proxy`, `go-migrate`, `otsutil`,
# and any subcommand invoked with `--help`) DO NOT accept `--user-agent` and
# MUST NOT carry it (passing it raises `unknown flag: --user-agent`).
# The ONLY exception is `aliyun configure ai-mode set-user-agent`, which is
# the dedicated command for declaring the AI-Mode global User-Agent (see §1.1.1).
# Only BUSINESS calls (e.g. `aliyun dyvmsapi submit-intent ...`,
# `aliyun dyvmsapi query-call-detail-by-call-id ...`) accept and MUST carry
#   --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-vms-smart-call-by-tts/1.0.0"
# so the call can be attributed to this Skill.
aliyun version

• ✅ 3.3.15または3.3.8以上のバージョンが出力される場合 → 1.1.1に進みます

• ❌ コマンドが見つからない／バージョンが3.3.8未満の場合 → このスキルに同梱されている環境対応インストーラーを実行します。実行環境に合った最初の方法（Homebrew → $HOME/.local/binへのユーザーレベルの署名済みバイナリ tarball）を選択します。このインストーラーは冪等で、インストール後に検証を行い、リモートスクリプトをシェルにパイプして実行することはありません。

  bash scripts/install_aliyun_cli.sh
  

  注意：

  • CLIのインストールにcurl -fsSL https://aliyuncli.alicdn.com/setup.sh | bashを実行しないでください。リモートスクリプトをシェルに直接パイプすると、整合性検証を回避するため、静的スキャナーによってセキュリティ違反と見なされます。また、このスクリプトは/usr/local/bin/aliyunに書き込み、sudoを使って無言で再試行します。そのため、パスワードを入力するTTYがない非対話型シェル（エージェントのサンドボックスやCIランナーなど）では失敗します。上記のインストーラーは署名済みバイナリ tarballのみをダウンロードし、リモートスクリプトを実行することなく、sudoの問題も回避します。
  • Apple Silicon搭載Macでは、インストーラーはaliyun-cli-macosx-latest-arm64.tgzを取得します。arm64ハードウェアにamd64ビルドをインストールしないでください。Rosetta 2が必要となり、動作が不安定になります。
  • 続行する前に検証してください：インストーラーは、インストールされたaliyun versionが3.3.8未満の場合、ゼロ以外の終了コードを返します。失敗した場合は、references/cli-installation-guide.mdの手動インストール手順を参照してください（macOS amd64／arm64、Linux amd64／arm64、Windowsに対応し、それぞれにsudoなしでの方法も記載されています）。

最低バージョンが3.3.8なのはなぜですか？ §1.3では、aliyun CLI v3.3.7（2026-04-16）で初めて導入されたフラグplugin install --source-baseを使用します（PR #1299）。最低バージョンは安全を考慮して3.3.8に設定されています。3.3.8未満のバージョンでは、§1.3でERROR: invalid flag source-baseが発生します。これはツールのバージョンの問題であり、ネットワークの問題ではありません。CLIをアップグレードしてください。

1.1.1 [MUST] AI モードを有効にする（CLI の確認直後に実行）

§1.1 で CLI が利用可能であることを確認したら、直ちに AI モードを有効にし、この Skill 内で他の aliyun ... コマンドを実行する前に有効化してください。

User-Agent は、ビジネス呼び出しでのみコマンドごとに指定します。 SKILL.md および references/*.md 内のすべてのビジネス aliyun ... コマンド（例：aliyun dyvmsapi submit-intent、aliyun dyvmsapi query-call-detail-by-call-id）では、この Skill に呼び出しを帰属させるため、Skill ごとの UA "AlibabaCloud-Agent-Skills/alibabacloud-vms-smart-call-by-tts/1.0.0" を明示的に指定する必要があります。システム／ツール用コマンド（§1.1 のスコープコメントに列挙されているカテゴリ）はこの UA フラグを受け付けず、指定してはいけません。指定すると unknown flag: --user-agent が発生し、コマンドが中断されます。唯一の例外は、AI モードのデフォルト UA を宣言するために以下で使用する aliyun configure ai-mode set-user-agent です。

# 1) Enable AI-Mode for this Skill session.
aliyun configure ai-mode enable

# 2) Declare the AI-Mode default UA so the gateway attributes every business
#    call below to this Skill. `ai-mode set-user-agent` is the ONLY
#    system/tooling command that legitimately accepts the UA flag.
aliyun configure ai-mode set-user-agent \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-vms-smart-call-by-tts"

[MUST] この Skill の終了時（成功、失敗、早期 STOP のいずれの場合も）には、必ず aliyun configure ai-mode disable を実行して AI モードを無効にしてください。 §6 の手順 2／手順 4 および §9 のベストプラクティス #5 を参照してください。

1.2 [MUST] submit-intent サブコマンドがすでに存在するか確認する

aliyun dyvmsapi submit-intent --help 2>&1

出力に基づいて判断します。

出力パターン	判定	次の手順
API 版本: 2017-05-25 を含み、--user-message も含む	プラグインは準備完了です	1.3 をスキップし、§2 に進む
unknown command "submit-intent"／command not found	プラグインがインストールされていません	1.3 に進む
aliyun: command not found	CLI がインストールされていません	1.1 に戻る
その他	異常です	references/plugin-troubleshooting.md を参照する

1.3 [MUST] 社内ネットワーク用のオンライン dyvmsapi プラグインをインストールする

SubmitIntent は、Alibaba 社内ネットワーク用オンライン CLI プラグインを通じてのみ配布されています。一般公開版の aliyun-cli-dyvmsapi には、このサブコマンドは含まれていません。

以下のコマンドをそのまま実行してください（パラメーターの省略・変更は禁止です）。

aliyun plugin install --names dyvmsapi \
  --version 0.1.0 \
  --source-base https://cli.aliyun-inc.com/registry_id/2/env/online/plugins

[MUST] 厳守事項（1 つでも異なると、インストールに失敗するか、誤ったビルドが取得されます）。

パラメーター	正しい値	よくある間違い
CLI バージョン	≥ 3.3.8	< 3.3.8 → ERROR: invalid flag source-base。§1.1 でアップグレードしてください。外部フォールバックには切り替えないでください
--names	s を付けた複数形	--name（インストール時に invalid flag で失敗します。単数形は uninstall 専用です）
--version	0.1.0（必須）	省略すると最新の一般公開ビルドが取得されます
--source-base	上記の URL（必須）	省略すると一般公開ミラーから取得されますが、そこには submit-intent がありません
URL パス	env/online/plugins	env/pre/plugins は非推奨です
URL ホスト	cli.aliyun-inc.com	Alibaba の社内ネットワークからのみ名前解決できます

想定される出力：

Downloading aliyun-cli-dyvmsapi 0.1.0...
Plugin aliyun-cli-dyvmsapi 0.1.0 installed successfully!

出力が plugin "aliyun-cli-dyvmsapi" is already installed (version X.Y.Z); continuing will replace it with version 0.1.0 の場合は、想定どおりの動作です（上書きインストール）。完了するまで待ってください。

出力が ERROR: invalid flag source-base の場合、CLI のバージョンが 3.3.8 未満であり、このフラグに対応していません。§1.1 の環境に応じたフォールバック手順を再実行してアップグレードしてください（brew／システム全体／ユーザーレベルから自動的に選択されます）。その後、§1.3 を再試行してください。このエラーを理由に §1.alt に切り替えることは**[FORBIDDEN] 禁止**です。これはネットワークの問題ではなく、ツールのバージョンの問題です。外部フォールバックを使用できるのは、no such host／connection timeout の場合に限られます。

出力が lookup cli.aliyun-inc.com: no such host／connection timeout の場合、実行環境は Alibaba の社内ネットワーク上にありません。§1.alt に切り替えて続行してください（機能的には同等で、プラグインのインストールは不要です）。

その他のエラーについては、references/plugin-troubleshooting.md を参照してください。

1.4 [MUST] インストール後に再検証する

# `--help` is a help-mode invocation: it MUST NOT carry `--user-agent`
# (passing it raises `unknown flag: --user-agent` and aborts the command).
# See §1.1.1 for the full system-vs-business UA scope rule.
aliyun dyvmsapi submit-intent --help

検証基準（続行する前にすべて満たす必要があります）：

• 出力に API 版本: 2017-05-25 が含まれている
• 出力にパラメーター --user-message が含まれている
• 出力に説明 提交文本意图… または同等の内容が含まれている

いずれかの基準を満たさない場合 → references/plugin-troubleshooting.md を参照してください。

---

1.alt 外部フォールバック経路（プライマリ経路が利用できない場合のみ使用）

トリガー：§1.3 で lookup cli.aliyun-inc.com: no such host が報告された場合、または実行環境がパブリックネットワーク上にあり、Alibaba 社内ネットワーク／VPN にアクセスできないことが確認された場合です。 プライマリプラグインが機能している間は、この経路を使用しないでください。

前提条件（不足があってはなりません）：

• Python 3.6 以降（macOS/Linux ではプリインストール済みです。python3 --version で確認してください）— ステップ 2 のスクリプトベースの SubmitIntent に必要です
• このリポジトリに含まれるスクリプト scripts/dyvmsapi_rpc.py（サードパーティ依存関係なし）— SubmitIntent のみを処理します
• Aliyun CLI とパブリックリリースの dyvmsapi プラグイン — ステップ 4 の CLI ベースの QueryCallDetailByCallId に必要です：

  # Refresh the public plugin index so the latest public-release dyvmsapi metadata is used.
  aliyun plugin update
  
  # Install the public-release dyvmsapi plugin (default source = public mirror; no --source-base).
  aliyun plugin install --names dyvmsapi
  

  ⚠️ 社内ネットワーク接続用プラグインとは同時に使用できません：§1.3 で社内ネットワーク接続用ビルド（0.1.0）が正常にインストールされている場合は、ここでパブリックリリース版をインストールしないでください。社内ネットワーク接続用ビルドには query-call-detail-by-call-id がすでに含まれています。パブリックリリース版をインストールするのは、§1.3 が no such host で失敗した場合のみです。
• パブリックネットワークから dyvmsapi.aliyuncs.com に接続できること

スクリプトが配置されていることを確認する：

python3 scripts/dyvmsapi_rpc.py --help

出力に dyvmsapi public RPC direct-call script (zero dependencies) が含まれている場合は、§2 の認証情報の検証に進んでください。（外部スクリプト経路では、ヘルパー scripts/run_with_aliyun_creds.py によって、現在の aliyun configure プロファイルから認証情報が自動で挿入されます。§2 を参照してください。）

重要な制約：

• 外部経路に切り替えた後は、§6 のステップ 2 にある aliyun dyvmsapi submit-intent の呼び出しを、スクリプトの呼び出しに置き換える必要があります。ステップ 4（aliyun dyvmsapi query-call-detail-by-call-id）では、引き続き上記のパブリックリリースプラグインをインストールした CLI を使用します。詳細は §6.alt と references/external-network-fallback.md を参照してください。
• AI-Mode：§1.1.1 で一度有効にしたら、ステップ 2 をスクリプトで実行するか、ステップ 4 を CLI で実行するかにかかわらず、このスキルのすべての終了時点で必ず無効にしてください。§1.1.1 のコマンドごとの UA ルールは引き続き適用されます。業務用の aliyun ... 呼び出し（例：aliyun dyvmsapi query-call-detail-by-call-id）にはスキルごとの UA を付与する必要がありますが、システム／ツール用のコマンドには付与してはいけません。§1.1.1 を参照してください。
• 2 つの経路を交互に使用しないでください。

---

2. 認証情報の検証

事前確認：Alibaba Cloud の認証情報が必要です

セキュリティルール：

• AK／SK の値を読み取ったり、エコーしたり、表示したりすることは絶対にしないでください（例：echo $ALIBABA_CLOUD_ACCESS_KEY_ID は禁止です）
• 会話やコマンドラインで AK／SK を直接入力するようユーザーに求めることは絶対にしないでください
• リテラルの認証情報を指定して aliyun configure set を使用することは絶対にしないでください
• 認証情報の状態確認には aliyun configure list のみを使用してください

aliyun configure list

有効なプロファイル（AK、STS、または OAuth ID）があるか、出力を確認してください。

注：Valid は、ローカルプロファイルのフィールド形式が正しいことを示すだけであり、AK がサーバー側で現在も有効であることを証明するものではありません。後続の呼び出しで InvalidAccessKeyId.NotFound ／ SignatureDoesNotMatch が返された場合、認証情報の構文は正しいものの、無効化またはローテーションされています。AK Management Console でステータスを照合してください。

有効なプロファイルがない場合は、ここで停止してください。

1. Alibaba Cloud Console から認証情報を取得します
2. ユーザー自身のターミナルで aliyun configure を実行する（またはシェルプロファイルで環境変数をエクスポートする）ことで、このセッションの外で認証情報を設定します。対話形式のフローでは、AK ID、AK Secret、Default Region Id など、複数の値を尋ねられます。通常、ユーザーが入力に迷うのは Region のプロンプトのみです（CLI に候補が表示されないため）。そのため、エージェントはユーザーに必ず事前に伝えてください。cn-hangzhou を推奨します。dyvmsapi は一元化されたサービスで、リージョンに依存しないため、有効なリージョンであればどれでも使用できます。ユーザーのほかの Alibaba Cloud リソースがすでに別のリージョン（例：cn-shanghai、cn-beijing、cn-shenzhen、cn-hongkong、ap-southeast-1）にある場合は、そちらを選んでもかまいません。候補の全一覧は references/cli-installation-guide.md を参照してください。
3. aliyun configure list に有効なプロファイルが表示されたら戻り、再実行します

---

2.1 主な方法（CLI）— 認証情報

主な方法では、aliyun dyvmsapi submit-intent ／ query-call-detail-by-call-id が現在のプロファイルから認証情報を自動的に読み取ります。エージェント側で追加の操作を行う必要はありません。

2.2 §1.alt 外部フォールバック（スクリプト）— 認証情報をデフォルトで自動注入

設計：外部フォールバックのスクリプト経路では、ユーザーに AK/SK を手動で export するよう求めなくなりました。代わりに、ユーザーがすでに設定している aliyun configure の現在のプロファイルを再利用し、ヘルパー scripts/run_with_aliyun_creds.py がサブプロセスの環境に認証情報を自動注入します。この設計には、次の 3 つの理由があります。① 主要経路と一貫したユーザー体験を実現するため。② プロセスをまたぐシェルの export では、認証情報をエージェントのサブプロセスに渡せないため（技術的に実現不可能です）。③ ユーザーはすでにこのプロファイル用の認証情報を提供しているため、再度求めるのは重複入力にあたるためです。

[MUST] 標準的な呼び出しパターン：エージェントは必ずヘルパーを経由します。~/.aliyun/config.json から認証情報を手動で取り出さないでください。

# 1) 事前チェック：現在のプロファイルが自動注入の要件を満たしていることを確認
python3 scripts/run_with_aliyun_creds.py --check
# 想定される出力：`OK profile=default mode=AK ready for auto-injection` → 準備完了

# 2) 使用するプロファイルをユーザーに伝える（透明性の確保。認証情報の値は含めない）
python3 scripts/run_with_aliyun_creds.py --print-profile
# 出力例：`profile=default mode=AK region=cn-hangzhou`
# エージェントはユーザーに明確に「profile=<name> mode=<mode> で SubmitIntent を呼び出します」と伝え、拒否する機会を設けなければなりません。

# 3) 実際に呼び出す（ヘルパーが環境変数を注入し、スクリプトが環境変数から読み取ります。値は永続化されません）
python3 scripts/run_with_aliyun_creds.py -- \
  python3 scripts/dyvmsapi_rpc.py SubmitIntent -P UserMessage="<the user's intent>"

対応モード：AK / StsToken。StsToken の場合は、スクリプトが署名の公開パラメーターとして含める ALIBABA_CLOUD_SECURITY_TOKEN も追加で注入します。

非対応モード（RamRoleArn / EcsRamRole / OAuth / External / CredentialsURI …）：ヘルパーは終了コード 3 で終了し、一時的な AK/SK/STS を手動で取得するようユーザーに促します。その場合は、主要経路に切り替えるか（CLI はすべてのモードにネイティブ対応しています）、ユーザーに新しい AK プロファイルを作成してもらいます。

[FORBIDDEN] 禁止事項：

• ヘルパーを迂回し、エージェントのコード内で ~/.aliyun/config.json / json.load(...) を直接読み取ることは厳禁です。次の 3 つのよくある失敗につながります。current ではなく profiles[0] をハードコードする（誤ったプロファイルを使用する）、StsToken の sts_token を見落とす、デバッグ出力やスクリプトのログから認証情報が漏れる。
• AK/SK/SecurityToken を ran_scripts/*.sh / outputs/*.md / ログ / Git から参照可能なファイルに書き込むことは厳禁です（# AK=<from-config> のようなプレースホルダーコメントも禁止です。読者に誤解を与えます）。
• -P SecurityToken=... を使って SecurityToken を業務パラメーターとして渡すことは厳禁です。これは公開パラメーターであり、署名に含める必要があります。ヘルパーがこれを自動的に処理します。
• 認証情報の値を echo / print / --debug で出力することは厳禁です。
• 従来の read -s ... && export ... パターンに戻すことは厳禁です。プロセスをまたぐシェル環境はサブプロセスに引き継げないため、技術的に実現不可能です。

---

3. RAM 権限

RAM サブアカウントには dyvms:SubmitIntent と dyvms:QueryCallDetailByCallId を付与する必要があります。ルートアカウントには追加の設定は不要です。完全なポリシーについては references/ram-policies.md を参照してください。

[MUST] 権限エラーへの対応： 実行中のどの時点でも、コマンドまたは API 呼び出しが権限エラーで失敗した場合は、次の手順に従ってください。

1. references/ram-policies.md を読み、この SKILL に必要な権限の全一覧を確認します
2. ram-permission-diagnose スキルを使って、必要な権限を申請する手順をユーザーに案内します
3. 必要な権限が付与されたことをユーザーが確認するまで、処理を中断して待ちます

---

4. 前提条件：アドレス帳を設定する

アドレス帳の管理はこのスキルの対象外です。スマート通話を開始する前に、ユーザーは Alibaba Cloud Voice Service コンソールで以下を完了する必要があります。

1. 電話番号の所有権を確認する：追加するすべての電話番号について所有権の確認を完了します（確認はデフォルトで約6か月間有効です）
2. 連絡先を追加する：確認済みの各番号に、判別しやすい タグを割り当てます。例：「お母さん」「張マネージャー」「老呉」
3. （任意）既存の連絡先を更新または削除します

アドレス帳の制約：

• Tag と PhoneNumber は厳密に1対1で対応します
• LLM が連絡先を照合する際に使用する手がかりはタグのみです。明確で判別しやすい名前を使用してください

---

5. パラメーターの確認

重要：パラメーターの確認 — API 呼び出しを実行する前に、 ユーザーの意図（誰に電話するか、何を伝えるか）を確認してください。ユーザーのメッセージから両方がすでに明らかな場合は、確認不要です。そのまま進めてください。 言い回しを繰り返し検討したり、読み上げるテキストの草案を作成したりしないでください。UserMessage は意図の説明であり、 最終的に再生される台本ではありません。サーバー側の LLM が実際に読み上げる内容（Model.CallContent）を生成します。

パラメーター	必須	説明	デフォルト
UserMessage	はい	通話の意図を自然言語で説明したもの（実際に読み上げるテキストではありません）	なし（ユーザーが指定する必要があります）

UserMessage の例：

• 「今夜は夕食に帰らないとお母さんに伝えて」
• 「張マネージャーに電話して、会議は明日の午前10時だと伝えて」
• 「今日の午後、契約書を持ってくるよう老呉に伝えて」

これらは意図の説明です。ユーザーの元のメッセージから「誰に」「何を」がすでに明らかな場合は、そのまま進めてください。繰り返して確認したり、承認を求めたりしないでください。「このような言い方でよろしいですか？」と尋ねたり、言い回しを繰り返し検討したりしないでください。読み上げる内容はサーバーが生成します。

---

6. 基本的なワークフロー

AI-Mode と User-Agent：AI-Mode は §1.1.1（CLI の検証直後）で有効にしています。事前に無効化していた場合（ステップ3の後の注記を参照）を除き、ここで再度有効にしないでください。以下の各業務用 aliyun ... 呼び出し（例：aliyun dyvmsapi submit-intent、aliyun dyvmsapi query-call-detail-by-call-id）では、スキルごとの UA "AlibabaCloud-Agent-Skills/alibabacloud-vms-smart-call-by-tts/1.0.0" を必ず明示的に渡してください。システム／ツール関連のコマンドはこのフラグを受け付けないため、付けてはなりません。§1.1.1 を参照してください。

［必須］このスキルのすべての終了箇所で、成功、失敗、途中での STOP など、終了理由を問わず AI-Mode を無効にしてください。無効化コマンドは次のとおりです。

aliyun configure ai-mode disable

ステップ 1：ユーザーの意図を把握する

ユーザーのメッセージから、誰に電話をかけ、何を伝えるのかを把握します。自然言語での指定で十分です（例：「我爸」「Mom」「张经理」）。アドレス帳に登録されている Tag の表記と完全に一致している必要はありません。サーバー側の LLM が、ユーザーの連絡先リストと意味的に照合します。

• 意図がすでに明確（誰に＋何を伝えるかの両方が曖昧でない）→ 確認を省略し、ただちにステップ 2 に進みます。例：「父に電話して、食料品を買いに行くよう伝えて」— 誰に＝父、何を伝えるか＝食料品を買いに行く。すぐに発信します。
• 意図が一部不明確（誰に電話するかが不明、または伝える内容が曖昧すぎて実行できない）→ 不明な点を確認するため一度だけ質問してから発信します。例：「電話して」— 誰に？ 何を伝える？ 一度だけ質問します。

[MUST] 確認は 0 回または 1 回で、その後は発信します — UserMessage は実際に読み上げる文面ではありません。サーバー側の LLM に渡す意図の説明であり、実際に読み上げる内容は LLM が生成します。誰に＋何を伝えるかが明確になった時点で（元のメッセージ、または一度だけの確認のいずれかで明確になった場合）、ただちにステップ 2 に進みます。以下の行為は禁止されています。

• 「通知文案」を作成し、ユーザーに文面を確認してもらう
• 「このように伝えますか？」と尋ねたり、複数の言い回しを提案したりする
• アドレス帳に登録されている正確な Tag の表記をユーザーに尋ねる（例：「你爸在通讯录里的 Tag 叫什么?」）— サーバーが意味的に照合するため、自然言語での指定で十分です
• 連絡先が明らかな場合に、その人が誰かを確認する（「爸」「老爸」「爸爸」はすべて同じ役割です。「どの人ですか？」と尋ねてはいけません）
• ユーザーが意図の誤りを明確に指摘していないのに、二度目の確認を求める

[MUST] 検証できない Tag を理由に中断してはいけません — エージェントには、アドレス帳のエントリーを一覧表示または検証するローカル API がありません（§4 を参照：CRUD は対象外です）。ユーザーが指定した Tag が存在するか確認できない場合でも、エージェントは必ずステップ 2 に進み、サーバーに検証させなければなりません。フローを中断する、ユーザーに「まずコンソールを確認してください」と求める、または Tag が「存在しないかもしれない」ことを理由に発信を拒否する行為は厳禁です。正しい動作は API を呼び出し、サーバーから返された内容（成功またはエラー）をそのまま伝えることです。

ステップ 2：スマートコールを開始する

aliyun dyvmsapi submit-intent \
  --user-message "<user-confirmed natural-language intent>" \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-vms-smart-call-by-tts/1.0.0"

§6.alt 外部フォールバック — ランタイムが §1.alt（スクリプトパス）に入った場合、このステップをヘルパー経由の呼び出しに置き換えます（認証情報はヘルパー経由で必ず自動挿入します。§2.2 を参照）。

python3 scripts/run_with_aliyun_creds.py -- \
  python3 scripts/dyvmsapi_rpc.py SubmitIntent \
    -P UserMessage="<user-confirmed natural-language intent>"

• キーはパスカルケース（user-message ではなく UserMessage）でなければなりません。レスポンスの形式は CLI と同じです。ステップ 3 の解析ロジックは共通です。
• ヘルパーを経由せずに python3 scripts/dyvmsapi_rpc.py ... を直接呼び出すことは厳禁です。このスクリプトは ~/.aliyun/config.json を自ら読み込みません。環境変数が設定されていない場合、[ERROR] AK/SK not provided が出力されます。
• 呼び出し前に、§2.2 の [MUST] に記載された 3 ステップの手順（--check → --print-profile でユーザーに通知 → 実際の呼び出し）を実行してください。
• 詳細は references/external-network-fallback.md を参照してください。

ステップ 3：レスポンスを解析する

• Code == "OK" かつ Success == true：呼び出しが開始されています
  • Model.Tag（一致した連絡先）、Model.CallContent（読み上げられたテキスト）、Model.CallIdをユーザーに表示します
  • 電話番号の安全性を確保するため、レスポンスには発信先の電話番号は含まれません
• エラー処理については、references/related-commands.mdのエラーコード表を参照してください
• Code != "OK"は有効な実行結果です。たとえば、連絡先が見つからない、クォータ超過、パラメーターが無効などです。エラーを解析し、内容を忠実にユーザーに報告して、エラー結果としてSkillの実行を完了したものと扱ってください。ユーザーから明示的に依頼されない限り、自動的に再試行したり、ステップ1に戻ったりしてはいけません。

ステップ3後のAI-Modeのライフサイクル：

• Code != "OK"の場合、またはユーザーがステップ4を必要としない場合 → ここが終了地点です → ただちにAI-Modeを無効にしてください。
• Code == "OK"で、ステップ4に進む可能性がある場合（ユーザーが通話結果の確認を希望している場合）→ まだ無効にしてはいけません。ステップ4が完了するまでAI-Modeを有効のままにしてください。
• Skillセッションが中断された場合（例：エージェントがステップ3後にAI-Modeをすでに無効にし、その後ユーザーがステップ4を依頼した場合）→ ステップ4の前にAI-Modeを再度有効にし、終了時に再び無効にしてください。これが再有効化を認められる唯一のケースです。

[FORBIDDEN] レスポンスの捏造やMock配信の実行は厳禁です — ステップ2でインフラストラクチャ障害が発生した場合（認証情報がない／期限切れ、ネットワークに接続できない、JSON本文を伴わないスクリプトの終了コードが0以外、InvalidAccessKeyId、SignatureDoesNotMatch）：

• 停止する前に、必ず最初にaliyun configure ai-mode disableを実行してください（AI-Modeは§1.1.1で有効化されており、失敗時を含め、すべての終了地点で無効化が必須です）。
• ただちに停止し、エラーを内容どおり、一字一句違わずユーザーに報告して、問題を修正してから再試行するよう依頼してください。
• Code: OK、偽のCallId、偽のModel.Tag、偽のModel.CallContentを捏造することは厳禁です。
• 成功した配信を装うために、偽造したcall_result.json、task_summary.md、executed_actions.shを書き込むことは厳禁です。
• 実際の呼び出しを回避する目的で、「simulated」／「mock」／「assume the user has」／「since this is a simulated environment」などの表現を使うことは厳禁です。
• 上記のいずれかに該当する行為は、不正な配信とみなされます。

ステップ 4（任意）：通話結果を照会する

SubmitIntentが返すModel.CallIdは、通話が受け付けられたことを示すだけであり、相手が応答したことを示すものではありません。通話が接続されたかどうかを確認したい場合は、query-call-detail-by-call-idを呼び出してください。

# Take the CallId returned by SubmitIntent (format: <ms-timestamp>^<call-sequence>, e.g. "1779785134472^9876543210").
CALL_ID="<Model.CallId from step 2 response>"
# The first segment of CallId is already a Unix-millisecond timestamp; reuse it as query-date.
# `--query-date` is an int (Unix-millisecond timestamp), NOT a yyyyMMdd string — do NOT call any datetime conversion.
QUERY_DATE="${CALL_ID%%^*}"

aliyun dyvmsapi query-call-detail-by-call-id \
  --call-id "$CALL_ID" \
  --prod-id 11000000300006 \
  --query-date "$QUERY_DATE" \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-vms-smart-call-by-tts/1.0.0"

必須要件：

• --prod-idは必ず11000000300006にしてください（Voice Notificationの製品ID）。SubmitIntentはこの製品でディスパッチされます。ほかのprod-idを指定すると、DataがないままCode: OKが返されます。
• --query-dateはCallIdと同じ日付でなければなりません（ミリ秒単位のタイムスタンプ）。
• CDRの書き込み遅延：通知形式の通話（通常は10～30秒）の場合、CDRは一般に通話終了から約40秒後に利用可能になります。Code: OKがDataなしで返された場合は、さらに30～60秒待ってから一度だけ再試行してください。何もせずに1～2分待つことは避けてください。

§6.alt External — ステップ4でも引き続きCLIを使用します。QueryCallDetailByCallIdの可視性はpublicです。一般公開版のaliyun-cli-dyvmsapiプラグインにはすでに含まれています：

aliyun plugin update
aliyun plugin install --names dyvmsapi   # public-release; no --source-base

一般公開版のプラグインは、§1.altからすでにインストールされているはずです。何らかの理由でまだインストールされていない場合は、まず上記の2つのコマンドを実行してください。インストール後は、上記のaliyun dyvmsapi query-call-detail-by-call-id ...コマンドをそのまま実行できます。外部経路では、スクリプトが置き換えるのはSubmitIntentのみです。CDRの照会は引き続きCLI経由で行います。詳細はreferences/external-network-fallback.mdを参照してください。

レスポンスの解析：

DataはJSONの文字列（2回目の解析が必要）であり、次の内容を含みます：

フィールド	意味
stateDesc	ローカライズされた状態の説明。例：用户接听（ユーザーが応答）／未接听（応答なし）／呼叫中（通話中）
state	状態コード（200000 = 応答済み）
duration	通話時間（秒）
bRingTime / bStartTime / bEndTime	呼び出し／応答／通話終了のタイムスタンプ
callee	発信先番号（この CDR API は完全な番号を返します — 各アカウント所有者は自分の CDR のみを閲覧できます。これは、電話番号が LLM に渡されないという SubmitIntent のルールに反するものではありません）
gmtCreate	プラットフォームが通話リクエストを受け付けた時刻
calleeShowNumber	着信時に表示される番号

[MUST] 読みやすい形式での表示 — 生の Data JSON 文字列をそのままユーザーに表示することは厳禁です。解析後、結果を実際の Markdown テーブル 3 つとして表示してください（フェンス付きコードブロックや、───── のような ASCII 区切り線は使用しないでください。Markdown レンダラーで <hr> として取り込まれ、以降の内容が 1 行に折り返されます）。

通話結果

✅ 状態	<stateDesc>（state=<state>）
👤 発信先	<callee_masked>
📲 表示番号	<calleeShowNumber>
⏰ 通話時間	<duration> 秒

タイムライン

🕐 受付	<gmtCreate>
🔔 呼び出し	<bRingTime>（受付から +<offset_after_accepted> 秒）
📞 応答	<bStartTime>（呼び出しから +<offset_after_ringing> 秒）
🔚 通話終了	<bEndTime>（通話時間 <duration> 秒）
👋 通話終了者	<callee-initiated|caller-initiated>（hangupDirection=<0|1>）

参照

🆔 CallId	<callId>

ルール：

• 実際の Markdown テーブルで表示してください。レイアウトをフェンス付きコードブロックで囲んだり、ASCII 区切り（─────、===、セル内の --- など）を使用したりしないでください。Markdown レンダラーで <hr> として取り込まれ、以降のテキストが 1 行に折り返されます。
• ローカライズされた stateDesc を数値の state と併記してください。生の数値のみを表示しないでください。
• 発信先番号は必ずマスキングしてください。先頭 3 桁、続けて ****、最後に末尾 4 桁を表示します。これがテーブル内の <callee_masked> に相当します。番号全体を表示してはいけません。
• 時刻フィールドには相対時間も含めてください（受付 → 呼び出し、呼び出し → 応答）。これにより、ユーザーがタイムラインを把握できます。
• hangupDirection：0 = 発信先が通話を終了、1 = 発信者が通話を終了。
• 応答がなかった場合（state ≠ 200000）、タイムラインの応答／通話終了の行を省略し、1 行の要約を使用してください。例：「✗ 発信先は応答しませんでした（X 秒間呼び出した後、通話を終了しました）」

パラメーターの完全なリファレンスとレスポンスの例については、references/related-commands.md を参照してください。

[MUST] すべての終了時に AI-Mode を無効化 — どのような理由であっても、最終応答を返す前に必ず aliyun configure ai-mode disable を実行してください。

---

7. 成功の検証

references/verification-method.md を参照してください。

簡易チェック：レスポンスの Code == "OK" かつ Model.CallId が空でない場合、通話は正常に開始されています。

---

8. コマンドリファレンス

references/related-commands.md を参照してください。

---

9. ベストプラクティス

1. UserMessage では連絡先を明示的に指定してください：ユーザーがアドレス帳に登録していると考える、見分けやすい呼び名（例：「お母さん」、「張マネージャー」）を使用し、代名詞（「彼」、「あの人」）は避けてください。
2. レート制限を守ってください：1 番号あたり 1 分間に 1 回、1 時間に 5 回、24 時間に 20 回です。一括通知では、呼び出しの間隔を少なくとも 60 秒空けてください。
3. 呼び出しの前にアドレス帳を設定してください：有効な電話番号の所有権確認を行い、連絡先がコンソールに追加されていることを確認してください。
4. コンプライアンスに沿った用途のみ：合法的な通知シナリオに限ります。債権回収、詐欺、嫌がらせなどは禁止されています。
5. 各 Skill の実行終了時（成功時も失敗時も）に、AI-Mode を必ず無効化してください：aliyun configure ai-mode disable を実行してください。

---

10. 参考リンク

ファイル	内容
references/cli-installation-guide.md	Aliyun CLI のインストールガイド
references/plugin-troubleshooting.md	dyvmsapi プラグインのインストールに関するトラブルシューティング（§1 で失敗した場合は必ず参照してください）
references/ram-policies.md	RAM ポリシー（最小限の Action）
references/related-commands.md	CLI コマンドのリファレンス、パラメーター、エラーコード
references/verification-method.md	検証方法
references/acceptance-criteria.md	受け入れ基準
references/external-network-fallback.md	外部フォールバックの実行マニュアル（プライマリパスを利用できない場合にのみ実行してください）
scripts/dyvmsapi_rpc.py	パブリックな dyvmsapi ゲートウェイを直接呼び出す、依存関係ゼロの Python スクリプト
scripts/run_with_aliyun_creds.py	認証情報の挿入ヘルパー。aliyun configure の現在のプロファイルから環境変数を自動挿入し、サブコマンドを実行します（外部フォールバックパスでは必須のエントリーポイントです）
scripts/install_aliyun_cli.sh	環境を考慮した Aliyun CLI のインストーラー／アップグレーダー（Homebrew → ユーザーレベルの署名付きバイナリ tarball。冪等で、自己検証を行います）。CLI が見つからない場合、またはバージョンが 3.3.8 未満の場合に §1.1 から呼び出されます。
related_apis.yaml	依存 API の一覧