x-request

🎯 スキルの位置付け

このスキルが重点的に解決する課題：さまざまなストリーミングインターフェースの要件に対応するために、XRequest を正しく設定する方法。

目次

• 🚀 クイックスタート - 3 分で使い始める
  • 依存関係の管理
  • 基本設定
• 📦 技術スタックの概要
• 🔧 コア設定の詳細
  • グローバル設定
  • セキュリティ設定
  • ストリーミング設定
• 🛡️ セキュリティガイド
  • 環境のセキュリティ設定
  • 認証方式の比較
• 🔍 デバッグとテスト
  • デバッグ設定
  • 設定の検証
• 📋 利用シナリオ
  • 単独での利用
  • 他のスキルとの統合
• 🚨 開発ルール
• 🔗 参考資料
  • 📚 コア参考ドキュメント
  • 🌐 SDK 公式ドキュメント
  • 💻 サンプルコード

🚀 クイックスタート

依存関係の管理

📋 システム要件

パッケージ	バージョン要件	自動インストール	用途
@ant-design/x-sdk	≥2.2.2	✅	コア SDK。XRequest ツールを含みます

🛠️ ワンクリックインストール

# Recommended to use tnpm
tnpm install @ant-design/x-sdk

# Or use npm
npm add @ant-design/x-sdk

# Check version
npm ls @ant-design/x-sdk

基本設定

最もシンプルな使い方

import { XRequest } from '@ant-design/x-sdk';

// Minimal configuration: only need to provide API URL
const request = XRequest('https://api.example.com/chat');

// For manual control (used in Provider scenarios)
const providerRequest = XRequest('https://api.example.com/chat', {
  manual: true, // Usually only this needs explicit configuration
});

💡 ヒント：XRequest には適切なデフォルト設定が組み込まれています。ほとんどの場合、API URL を指定するだけで利用できます。

📦 技術スタックの概要

🏗️ 技術スタックのアーキテクチャ

graph TD
    A[XRequest] --> B[Network Requests]
    A --> C[Authentication Management]
    A --> D[Error Handling]
    A --> E[Streaming Processing]
    B --> F[fetch Wrapper]
    C --> G[Token Management]
    D --> H[Retry Mechanism]
    E --> I[Server-Sent Events]

🔑 コアコンセプト

コンセプト	役割	主な責務	利用シナリオ
XRequest	🌐 リクエストツール	すべてのネットワーク通信、認証、エラー処理を担います	リクエストの一元管理
グローバル設定	⚙️ 設定センター	一度設定すれば、どこでも利用できます	重複コードの削減
ストリーミング設定	🔄 ストリーミング処理	SSE と JSON のレスポンス形式に対応します	AI との会話シナリオ

🔧 コア設定の詳細

コア機能の参考資料は CORE.md を参照してください。

🛡️ セキュリティガイド

環境のセキュリティ設定

🌍 環境別のセキュリティ対策

実行環境	セキュリティレベル	設定方法	リスクの説明
ブラウザのフロントエンド	🔴 高リスク	❌ キーの設定は禁止	キーがユーザーに直接公開されます
Node.js バックエンド	🟢 安全	✅ 環境変数で設定	キーはサーバー側に保存されます
プロキシサービス	🟢 安全	✅ 同一オリジンのプロキシ転送	キーはプロキシサービスで管理されます

🔐 認証方式の比較

認証方式	対象環境	設定例	セキュリティ
Bearer トークン	Node.js	Bearer ${process.env.API_KEY}	✅ 安全
API キーヘッダー	Node.js	X-API-Key: ${process.env.KEY}	✅ 安全
プロキシ転送	ブラウザ	/api/proxy/service	✅ 安全
直接設定	ブラウザ	Bearer sk-xxx	❌ 危険

🔍 デバッグとテスト

デバッグ設定

🛠️ デバッグ用テンプレート

Node.js のデバッグ設定：

// Safe debug configuration (Node.js environment)
const debugRequest = XRequest('https://your-api.com/chat', {
  headers: {
    Authorization: `Bearer ${process.env.DEBUG_API_KEY}`,
  },
  params: { query: 'test message' },
});

フロントエンドのデバッグ設定：

// Safe debug configuration (frontend environment)
const debugRequest = XRequest('/api/debug/chat', {
  params: { query: 'test message' },
});

設定の検証

✅ セキュリティチェックツール

// Security configuration validation function
const validateSecurity = (config: any) => {
  const isBrowser = typeof window !== 'undefined';
  const hasAuth = config.headers?.Authorization || config.headers?.authorization;

  if (isBrowser && hasAuth) {
    throw new Error(
      '❌ Frontend environment prohibits Authorization configuration, risk of key leakage!',
    );
  }

  console.log('✅ Security configuration check passed');
  return true;
};

// Usage example
validateSecurity({
  headers: {
    // Do not include Authorization
  },
});

📋 利用シナリオ

単独での利用

🎯 リクエストを直接送信する

import { XRequest } from '@ant-design/x-sdk';

// Test interface availability
const testRequest = XRequest('https://httpbin.org/post', {
  params: { test: 'data' },
});

// Send request immediately
const response = await testRequest();
console.log(response);

他のスキルとの統合

🔄 スキル連携ワークフロー

graph TD
    A[x-request] -->|Configure Request| B[x-chat-provider]
    A -->|Configure Request| C[use-x-chat]
    B -->|Provide Provider| C
    A --> D[Direct Request]

使用方法	連携するスキル	目的	例
単独	なし	ネットワークリクエストを直接開始	インターフェースの利用可否をテスト
x-chat-provider と併用	x-chat-provider	カスタム Provider 向けのリクエストを設定	プライベート API を設定
use-x-chat と併用	use-x-chat	組み込み Provider 向けのリクエストを設定	OpenAI API を設定
完全な AI アプリケーション	x-request → x-chat-provider → use-x-chat	システム全体のリクエストを設定	完全な AI 会話アプリケーション

⚠️ useXChat 連携時のセキュリティ警告

重要な警告：useXChat はフロントエンド環境専用です。XRequest の設定に Authorization を含めないでください！

❌ 誤った設定（危険）：

// Extremely dangerous: keys will be directly exposed to browser
const unsafeRequest = XRequest('https://api.openai.com/v1/chat/completions', {
  headers: {
    Authorization: 'Bearer sk-xxxxxxxxxxxxxx', // ❌ Dangerous!
  },
  manual: true,
});

✅ 正しい設定（安全）：

// Frontend security configuration: use proxy service
const safeRequest = XRequest('/api/proxy/openai', {
  params: {
    model: 'gpt-3.5-turbo',
    stream: true,
  },
  manual: true,
});

🚨 開発ルール

テストケースのルール

• ユーザーがテストケースを明示的に必要としていない場合、テストファイルを追加しないでください
• ユーザーが明示的に依頼した場合にのみ、テストケースを作成してください

コード品質のルール

• 完了後は必ず型をチェックしてください：tsc --noEmit を実行し、型エラーがないことを確認してください
• コードをクリーンに保ってください：未使用の変数とインポートをすべて削除してください

✅ 設定チェックリスト

XRequest を使用する前に、以下の設定が正しく行われていることを確認してください：

🔍 設定チェックリスト

チェック項目	状態	説明
API URL	✅ 設定必須	XRequest('https://api.xxx.com')
認証情報	⚠️ 環境による	フロントエンド❌禁止、Node.js✅利用可能
manual 設定	✅ Provider の場合	Provider では true に設定し、それ以外の場合は実際の状況に応じて設定してください
その他の設定	❌ 設定不要	妥当なデフォルト値が組み込まれています
インターフェースの利用可否	✅ テストを推奨	デバッグ設定で確認してください

🛠️ 簡易確認スクリプト

// Check configuration before running
const checkConfig = () => {
  const checks = [
    {
      name: 'Global Configuration',
      test: () => {
        // Check if global configuration has been set
        return true; // Check according to actual situation
      },
    },
    {
      name: 'Security Configuration',
      test: () => validateSecurity(globalConfig),
    },
    {
      name: 'Type Check',
      test: () => {
        // Run tsc --noEmit
        return true;
      },
    },
  ];

  checks.forEach((check) => {
    console.log(`${check.name}: ${check.test() ? '✅' : '❌'}`);
  });
};

🎯 スキル連携

graph LR
    A[x-request] -->|Configure Request| B[x-chat-provider]
    A -->|Configure Request| C[use-x-chat]
    B -->|Provide Provider| C

📊 スキル使用方法の比較表

使用シナリオ	必要なスキル	使用順序	完了時間
インターフェースのテスト	x-request	直接使用	2 分
プライベート API への適応	x-request → x-chat-provider	まずリクエストを設定し、その後 Provider を作成	10 分
標準的な AI アプリケーション	x-request → use-x-chat	まずリクエストを設定し、その後インターフェースを構築	15 分
完全なカスタマイズ	x-request → x-chat-provider → use-x-chat	ワークフロー全体	30 分

🔗 参考資料

📚 主要な参考ドキュメント

• API.md - API の完全なリファレンスドキュメント
• EXAMPLES_SERVICE_PROVIDER.md - 各種サービスプロバイダーの設定例

🌐 SDK 公式ドキュメント

• useXChat 公式ドキュメント
• XRequest 公式ドキュメント
• Chat Provider 公式ドキュメント

💻 サンプルコード

• custom-provider-width-ui.tsx - カスタム Provider の完全なサンプル