CounterCall は何をしますか？
Pak Yantoは午前中に休暇をとり、四十分かけてSamsat窓口に行きましたが、コピーがA4ではなくフォリオだったために追い返されました。彼は一日分の収入を失い、翌日に何が不足しているのかもわからないままでした。
公共サービス窓口は、不完全だったり、古かったり、窓口で暗黙に矛盾している要求リストを公開しています。唯一信頼できる情報源は役所の電話回線ですが、その回線は混んでいて、IVR（自動音声案内）の壁があり、ようやく繋がるのは四回目です。だから人々は電話しません。彼らは移動し、列に並び、一つの書類が原因で追い返されます。
このスキルは代わりに電話をかけ、ユーザーがスクリーンショットを撮って持参できるチェックリストを返します。
CALL-Eの設計に適しています：低頻度で、個人的で、リスクの高い電話業務であり、人間が朝中ずっとリダイヤルしなければならない番号にかけるものです。
始める前に
このスキルは実際の公共機関に実際の電話をかけます。 ユーザーと以下の点を確認してください。
- どの手続きについて尋ねているのか（役所の表現で）
- どの役所か、そしてその電話番号（E.164形式で、役所の公式公開ページから取得したもの）
- 今すぐ電話をかけてもよいか
電話番号を推測しないでください。 ディレクトリからでも、類似の役所からでも、国コードを推測してもいけません。番号がフローに入るのは、人間が役所自身の公開ページから読み取った場合のみです。間違った番号にかけると、自動発信者が他人に届くことになり、このスキルで最悪の事態です。
安全上の境界
このスキルは窓口の必要条件のみを収集します。
- 申請の提出、予約、手数料の支払い、またはユーザーを何かに拘束することはしません。質問して報告するだけです。
- 法的または移民に関するアドバイスは提供しません。職員が代替案を提案した場合は、そのまま報告し、決して推奨として提示しません。
- 職員の口頭回答は情報提供であり、法的拘束力はありません。すべての結果にその旨が記載されます。要件は変わり、個々の窓口は裁量を適用します。
- 通話開始時に、自動アシスタントであることと、なぜ電話しているのかを明確に述べます。相手が答えることを拒否した場合は、感謝して通話を終了します。粘ったり、再度質問したり、同じ日に再発信したりしません。
- 1日1回、1つの役所につき1つの手続きにつき1回の通話。 これらは、前に行列ができている人間が対応する公共サービス回線です。冪等性キーがこれを強制します。削除しないでください。
- 職員が不明な場合、結果は不明と表示します。典型的な情報で穴を埋めることは決してなく、曖昧な表現を事実として提示することもありません。人はこの回答を頼りに街を横断して移動するかもしれません。
- 公開された営業時間内にのみ役所に電話をかけます。22時に公共回線が鳴るのはデータポイントではなく、迷惑です。
このスキルを新しい機関に適応させる前に、references/safety.md をお読みください。一部の相手先は、自動発信の対象として適切ではありません。
トランスクリプトとの違い
ほとんどの通話スキルは散文を返し、読者に解釈させます。これは固定され、検証されたオブジェクトを返し、それ以外は拒否します。
Goalのresult_schemaはadditionalProperties: falseを設定し、4つのフィールドを列挙型に制約しています — payment_method、appointment_required、originals_or_copies、clerk_certainty。それぞれに「職員が知らなかった」場合の値が含まれています。通話が異なる形で返ってきた場合、結果はレンダリングされるのではなく隔離されます。半分しか解析されていないチェックリストは、ユーザーがそれに基づいて行動するため、チェックリストがないより悪いです。
完全な契約はreferences/result-contract.mdにあります。
ワークフロー
1. リクエストを収集する
必須項目：手続き名、役所名、役所の電話番号（E.164形式）、番号の出典URL。
他の何よりも先に番号を検証してください。 E.164はプラス記号、ゼロ以外の国コード数字、その後7～14桁の数字です：^\+[1-9]\d{7,14}$。それ以外は拒否し、ユーザーに尋ねてください。国コードを決して推測しないでください。ローカル形式の番号がダイヤラーに到達すると、間違った人に電話がかかります。
scripts/preflight.mjsを実行して、ダイヤルせずに番号と契約を確認してください。
2. 公開された契約がずれていないか確認する
毎回の実行前に、ライブのGoalインターフェースを読み、このスキルが書かれた時点の契約と比較してください。
import { diffContract, publishedRunSpec } from './scripts/_lib.mjs';
const goal = await client.goals.get(GOAL_ID);
const drift = diffContract(PINNED_CONTRACT, publishedRunSpec(goal));
if (drift.length) throw new ContractDrift(drift); // ダイヤルを拒否
publishedRunSpec(goal)ヘルパーを使用し、直接goal.published_run_specは使わないでください。 ワイヤーフォーマットとドキュメントはpublished_run_spec.result_schemaと綴りますが、TypeScript SDKはキャメルケースでpublishedRunSpec.resultSchemaと解釈します。ドキュメント通りの名前だけをTSクライアントに対して読むと、undefinedが返り、例外はスローされません。するとガードは「公開されたスペックがない」と結論づけ、動作しているように見えながらすべてのダイヤルを拒否します。ヘルパーは両方の綴りを読みます。これで一日を費やしました。リポジトリルートのFEEDBACK.mdに記録されています。
CALL-Eのドキュメントは、変数の変更をデプロイする前にこの比較を行うことを推奨しています。毎回の実行でこれを行うと、1回のAPI呼び出しがかかり、静かな失敗が明示的な拒否に変わります。古いスキーマで実際の人に電話をかけると、結果は問題なく見えて、静かに間違っています。
3. 1回の通話をかける
goals.runにIdempotency-Keyを指定し、役所、手続き、日付でスコープします。これにより、リトライが公共回線に二重発信されることはありません。
countercall:{office}:{procedure}:{yyyy-mm-dd}:v1
4. 結果かエラーまでポーリングする
goals.waitForResultの完了ルールは一つ：resultまたはerrorが非nullになった時点で停止します。完了した通話は、CALL-Eが構造化結果を解析している間、一時的に両方ともnullを返すことがあります。そのため、そのウィンドウを失敗として扱わないでください。
5. レンダリングするか、正直に失敗する
公開されている8つのGoalRunErrorコードはすべて、個別の結果にルーティングされます。以下のセットはscripts/render.mjsが実装しているものです。CALL-Eがコードを追加した場合、これらと同期を保ってください。
| 結果 | ユーザーに表示される内容 |
|---|---|
| 有効な結果 | チェックリスト、職員の正確な発言、およびソースURL |
no_answer | 「回線が応答しませんでした」。チェックリストなし |
declined | 「役所が自動発信者への応答を拒否しました」。チェックリストなし |
result_invalid | 通話は完了したが、回答が契約と一致しませんでした。隔離済み |
result_unavailable | 通話は完了したが、構造化された回答が生成されませんでした。チェックリストなし |
result_failed | 回答をチェックリストに処理できませんでした。チェックリストなし |
timed_out | 期限までに「使用可能な回答なし」。チェックリストなし |
call_failed | 通話を完了できませんでした。チェックリストなし |
canceled | 回答が生成される前にキャンセルされました。チェックリストなし |
どの分岐も部分的なチェックリストをレンダリングしません。 各ケースの動作例はreferences/examples.mdにあります。
実行方法
scripts/call.mjsはデフォルトでドライランです。送信する正確なリクエストを表示し、通話は行いません。ダイヤルには明示的な--liveが必要です。
# ドライラン — 送信するリクエストを表示し、ダイヤルは行わず、認証情報は不要
node scripts/call.mjs --office <id> --procedure "<procedure>"
# 実際に電話をかける
node scripts/call.mjs --office <id> --procedure "<procedure>" --live
デフォルトでダイヤルするスキルは、事故でダイヤルするスキルです。
data/offices.jsonには電話番号がマスクされています（+62XXXXXXXXXX）。そのため、シードされたエントリはダイヤルできず、それに対するすべてのコマンドは3で終了しREFUSING TO DIALを表示します。これは意図的です：人間が役所自身の公開ページから番号を読み取り、source_urlとsource_checkedを記録した場合にのみ、番号がファイルに入ります。何かを実行する前に、独自のエントリを追加してください。
ドライランの出力をすぐに確認するには、テストフィクスチャに有効な架空の番号が含まれています：
node scripts/call.mjs --offices ../../test/fixtures/offices.test.json \
--office fixture-sourced --procedure "perpanjangan paspor"
これを使用すべきでない場合
- 緊急時。 これは数分のレイテンシがある要件確認です。緊急に誰かに連絡する方法ではありません。
- 公開された、信頼でき、最新の要件ページがある役所。 ウェブサイトが正しければ、ウェブサイトを読んでください。公表された回答が不完全であるとわかっている場合にのみ、電話は正当化されます。
- 自動システムからの電話を拒否するよう要求した機関、 または現地法が自動発信を制限している場合。役所を追加する前に確認してください。
- 高頻度の問い合わせ。 1日1つの手続きにつき1つの役所が設計上の上限です。大量のデータが必要なら、電話ではなくデータ共有契約が必要です。
- 間違いが安価な場合。 ここでの価値は、無駄な移動のコストに由来します。ユーザーが単に出向いて確認できるなら、そうさせてください。
正直な限界
- カバレッジはシードファイル内の役所に限定され、それぞれに公開ソースURLがあります。
- 公共サービス回線の応答率は役所や時間帯によって異なり、かなりの割合の通話は応答されません。その信頼性の低さがこのスキルが存在する理由であり、隠すのではなく報告されます。
- 結果はある日の一人の職員の回答です。証拠であって、保証ではありません。