universal-email

メール（universal-email）

Cola 流でユーザーにサービスを提供する

これらのルールは、あなたがユーザーに伝えるすべてのことに適用されます。実行するコマンドが変わることはありません。以下のすべての操作は、記載どおりに実行してください。

• 製品に関する用語は使ってかまいません。 配置、授权、连接、账号、授权码/App 专用密码――ユーザーが常にどの段階にいるか分かるようにしてください。
• 実装の詳細をユーザーに伝えてはいけません。 himalaya、CLI、設定ファイル、TOML、IMAP/SMTP、PATH、キーチェーンサービス名の代わりに、「あなたのメールボックス／メールアカウント」と伝えてください。ユーザーから仕組みについて明示的に尋ねられた場合は、説明してもかまいません。
• ツールではなく、目的を伝えてください。 「メールボックスに接続しています」「受信トレイを確認しています」と伝え、「himalaya account list を実行しています」とは言わないでください。
• 必要最小限の情報を一度だけ尋ねてください。 メールアドレスを尋ねます。よく知られたドメインであればプロバイダーを特定できますが、会社や独自ドメインでは特定できません。Google Workspace、Microsoft 365、iCloud でホストされていることが多く、一般的なメールボックスとして扱うと、ユーザーが持っていないサーバー設定を尋ねたり、プロバイダー独自のサインイン手順を省いたりすることになります。設定ガイドを選ぶ前に、ドメインの MX レコードを確認するか、どのサービスでホストされているかを尋ねてください。その後、プロバイダーのアプリ用認証情報の生成方法を案内してください（QQ：设置→账户→开启 IMAP/SMTP 生成授权码；iCloud/Gmail：App 专用密码。リンクを使ってもかまいません）。検証に実際に失敗した場合を除き、再度尋ねないでください。
• 認証情報を会話に含めてはいけません。 アプリ用パスワードや認証コードは、安全なローカルプロンプトに入力してもらい、チャットメッセージにもシェル引数にも含めてはいけません。チャットに貼り付けられた認証情報は、会話の記録に残ります。設定をやり直し、新しいコードをそこで入力するよう伝えてください。それでも貼り付けられた場合は一度だけ使用し、その後、失効させて再生成するよう伝えてください。
• エラーを次の手順に置き換えて伝えてください。 生のコマンド出力やスタックトレースを貼り付けてはいけません。失敗した場合は、ユーザーが取るべき明確な行動を一つ伝えてください（「この認証コードは正しくないようです。QQ メールの設定で新しいコードを生成してください。すぐに再接続をお手伝いします」）。
• ユーザーに分かる言葉で完了を伝えてください。 何をどこに設定したかではなく、今できることを伝えてください（「メールがつながりました。これからは『今日のメールを見て』と言うだけで大丈夫です」）。

同梱の himalaya 実行ファイルを使用してください。このスキルが対象とするのは、リビジョン 923414155f4281d681f4ea8631954f406acf51ee の Himalaya 2.0.0 のみです。Himalaya 1.x の設定フィールドやコマンド例は使用しないでください。

実行ファイルの場所を特定する

必ずこのスキルに同梱されている実行ファイルを使用してください。PATH 上にたまたま存在する himalaya は、別バージョンの可能性があるため使用しないでください。セッションごとに一度だけ場所を特定します。

1. プラットフォームのディレクトリを特定します。macOS では uname -m を実行します（arm64 → darwin-arm64、x86_64 → darwin-x64）。Windows では win32-x64 を使用します。
2. scripts/bin/<platform>/himalaya をこのドキュメントのディレクトリを基準に解決します。Windows ではファイル名は himalaya.exe です。以下のすべてのコマンドで、この絶対パスを使用してください。

このパッケージには macOS 版と Windows 版のみが同梱されています。それ以外のプラットフォームには同梱版がないため、himalaya --version が v2.0.0 と表示されることを確認したうえで、PATH 上の himalaya を使用してください。それ以外のバージョンは使用できないものとして、その旨を伝えてください。

以下の例では読みやすさのためコマンドをそのままの名前で記載していますが、実行時には必ず特定した絶対パスを使用してください。

そのファイルが見つからない場合は、メールボックスをまだ利用できないと伝えてください。アカウントの問題やコネクターの故障として説明してはいけません。

実行する実行ファイルのアクティブな設定を、信頼できる情報源として扱ってください。候補となる設定ファイルを調べて選んだり、ファイルが存在するという理由だけで --config を追加したりしてはいけません。ユーザーから別のプロファイルを明示的に要求された場合に限り、--config を使用してください。

使用シーン

• メールの接続：「QQ メールにつないで」「Gmail を連携して」
• 日常的な送受信：「今日届いた新しいメールを見て」「このメールを Alice に転送して」「明日到着すると返信して」
• 整理と検索：「先週の経費精算に関するメールを探して」「このメールを既読にして」「これを削除して」

アカウントを選択する

1. 解決された実行ファイルが himalaya v2.0.0 を報告することを確認します。
2. himalaya --json account list を実行します。
3. 対象のアカウントが存在する場合は、グローバルな --account <name> オプションで選択します。
4. 存在しない場合は、ユーザーに何かを尋ねる前に、該当するプロバイダーガイドを確認します。
   • Gmail：references/gmail.md
   • QQ Mail：references/qq.md
   • iCloud Mail：references/icloud.md
   • Outlook/Microsoft 365：references/outlook.md
   • その他の IMAP/SMTP：references/standard-imap-smtp.md
5. 設定が不足している場合は、Himalaya 2 の TOML 形式と有効な設定のルールについて references/configuration.md を確認します。
6. メールボックス操作を行う前に、himalaya --account <name> --json account check で検証します。

プロバイダーでアプリパスワード、認証コード、または OAuth が必要な場合、通常のアカウントパスワードを尋ねないでください。秘密情報を表示したり、コマンド引数に含めたり、password.raw として保存したりしないでください。

読み取り操作

機械可読な出力には、グローバルな --json を優先します。

himalaya --account <name> --json mailbox list
himalaya --account <name> --json envelope list --mailbox inbox --page 1 --page-size 20
himalaya --account <name> --json envelope search --mailbox inbox from [email protected] and subject report
himalaya --account <name> --json message read --mailbox inbox <message-id>
himalaya --account <name> --json attachment list --mailbox inbox <message-id>
himalaya --account <name> attachment download --mailbox inbox --dir <directory> <message-id> <attachment-id>

ID はメールボックスごとに割り当てられます。メールボックスの切り替え後、または移動／削除操作後は、一覧を再取得してください。message read --json の結果に必要なフィールドがすでに含まれている場合、同じメッセージを繰り返し取得しないでください。

書き込み操作

送信、返信、転送、移動、削除の直前に、最終的な宛先、件名、本文をユーザーに提示し、確認を得てください。

書き込みの前にバックエンドを確認してください。 message compose|reply|forward --send は SMTP または JMAP 経由でのみ送信するため、Microsoft Graph バックエンドを使用するアカウントでは送信できません。まず account list でアカウントのバックエンドを確認してください。Graph アカウントの場合は、himalaya msgraph message send を使用して raw MIME で送信し、作成前に references/outlook.md を確認してください。

himalaya --account <name> message compose \
  --from [email protected] \
  --to [email protected] \
  --subject "Subject" \
  --body "Body" \
  --send

himalaya --account <name> message reply --mailbox inbox \
  --body "Reply body" --send <message-id>

himalaya --account <name> message forward --mailbox inbox \
  --to [email protected] --body "Forward note" --send <message-id>

添付ファイルと raw RFC 5322 メッセージについては、references/message-composition.md を確認してください。

曖昧なエラーが発生した場合、送信を自動的に再試行しないでください。SMTP では、送信が成功しても、送信済みメールボックスへのコピーの保存に失敗することがあります。再試行する前に、配信状況を確認してください。

メールを整理する

himalaya --account <name> message move --from inbox --to archive <message-id>
himalaya --account <name> message copy --from inbox --to important <message-id>
himalaya --account <name> flag add --mailbox inbox --flag seen <message-id>
himalaya --account <name> flag remove --mailbox inbox --flag seen <message-id>
himalaya --account <name> message delete --mailbox inbox <message-id>

message delete はまずゴミ箱に移動しますが、すでにゴミ箱にあるメッセージは完全に削除します。この結果を説明し、明示的な確認を得てください。

ネットワークとトラブルシューティング

Himalaya 2 は SOCKS5 と HTTP CONNECT をサポートしており、ルートは各コマンド実行時の環境からのみ取得します。オペレーティングシステムのプロキシ設定は検出元であり、ルートではありません。macOS または Windows の設定でプロキシを構成していても、プロセス環境に設定されていなければ使用されません。そのため、設定を読み取った後にコマンドを変更せずに実行すると、プロキシをテストしているように見えて、実際には直接接続ルートがテストされます。検出した設定を試すには、そのコマンド実行時の環境に明示的に渡し、報告されたプロトコルをそのまま使用してください。ポート番号からプロトコルを推測してはいけません。

Himalaya にはプロキシ設定フィールドも CLI フラグもありません。ルートは各コマンド実行時の環境からのみ決まり、このビルドが読み取る変数は all_proxy が先で、次に https_proxy のちょうど 2 つです。http_proxy は一切参照されないため、それだけで指定されたプロキシは黙って無視され、コマンドは直接接続で実行されます。そのような値は、コマンド実行時に https_proxy に引き継いでください。この環境が、コマンドごとにルートを分離する唯一の方法です。単一のコマンドを直接接続ルートに強制するには、ユーザーのグローバルプロキシには触れず、そのコマンド実行時に限り両方の変数をクリアしてください。macOS では env -u all_proxy -u https_proxy <himalaya> --account <name> ... を使用します。PowerShell には env がないため、代わりにプロセスのスコープ内で変更します。

# A child process, so the user's proxy stays intact in this session.
powershell -NoProfile -Command @'
Remove-Item Env:all_proxy -ErrorAction SilentlyContinue
Remove-Item Env:https_proxy -ErrorAction SilentlyContinue
& '<himalaya>' --account <name> ...
'@

作業中のセッションで $env: の値を直接設定しないでください。設定が残り、その後のすべてのコマンドが、ユーザーのプロキシを使わずに黙って実行されることになります。ルートを推測で判断するのではなく、Himalaya 独自の dial <host>:<port> ... (source: direct|all_proxy|https_proxy) デバッグ行で、実際に使用されたルートを確認してください。

次のいずれかに該当する場合は、接続または診断を行う前に references/proxy.md を読んでください。

• プロバイダーがユーザーの現在のネットワークでプロキシを必要とする可能性がある場合；
• プロキシ変数またはオペレーティングシステムのプロキシ設定が存在する場合；
• エラーにプロキシ、タイムアウト、DNS／接続、TLS、サービスへの到達不能、または不完全な SOCKS ハンドシェイクに関する記載がある場合；
• IMAP は動作するが SMTP は失敗する場合、またはその逆の場合；
• 直接接続ルートとプロキシ経由ルートを切り替えると結果が変わる場合。

このガイドでは、Gmail、QQ Mail、iCloud Mail、Outlook、カスタム IMAP／SMTP のルーティング既定値、macOS と Windows でのプロキシ検出、コマンドごとのルート分離、エラー別の復旧方法を説明しています。ユーザーにグローバルプロキシ設定の編集を求めないでください。

エラーの対応表を復旧の指針として使用してください。観測されたエラーが既知のケースに一致する場合は、現在のデバイスで利用できる操作手段を用いて、記載された方向に沿って診断を進めてください。プロトコル、ポート、またはタイムアウトをユーザーに言い直すだけで終わらせないでください。また、すべてのデバイスで同じ方法でプロキシを操作できると決めつけないでください。

実際の CLI パスを使用してください。

himalaya --account <name> --log-level debug account check

結果を解釈する前に、Himalaya 独自のデバッグ行で選択されたルートを確認してください。nc、telnet、または直接ソケットを使ったプローブを、Himalaya の接続性の証明として使用しないでください。これらの確認方法では、Himalaya のプロキシ選択が迂回されるためです。ネットワーク以外の障害と段階的な診断フローについては、references/troubleshooting.md を読んでください。

タイムアウトを解釈する前に、診断の各段階を省略しないでください。まず、範囲を限定したコマンド出力を確認し、その後、安全なルート情報と段階情報のみを残して報告してください。