qianwen-text

Qwen テキストチャット（OpenAI 互換）

OpenAI 互換 API を通じて Qwen モデルを使用し、テキストの生成、会話、コードの作成、ツールの呼び出しを行います。 このスキルは QianWen-AI/qianwen-ai の一部です。

スキルディレクトリ

このスキルの内部ファイルを使用して実行し、仕組みを確認してください。デフォルトのパスで読み込みに失敗した場合や、詳細が必要な場合は、必要に応じてリファレンスファイルを読み込んでください。

場所	用途
scripts/text.py	デフォルトの実行方法 — チャット／補完リクエスト、ストリーミング、出力の保存
references/execution-guide.md	フォールバック：curl、Python SDK、関数呼び出し、思考モード
references/api-guide.md	API の補足と完全なコード例
references/prompt-guide.md	プロンプトエンジニアリング：CO-STAR フレームワーク、CoT、少数ショット、タスクの手順
references/sources.md	公式ドキュメントの URL（手動で参照する場合のみ）

セキュリティ

API キーや認証情報を平文で出力しないでください。 常に変数参照を使用してください（シェルでは $DASHSCOPE_API_KEY、Python では os.environ["DASHSCOPE_API_KEY"]）。認証情報を確認または検出する場合は、平文を使用しないでください。値は決して表示せず、状態（例：「設定済み」／「未設定」、「有効」／「無効）のみを報告してください。シークレットが含まれる可能性のある .env ファイルや設定ファイルの内容は表示しないでください。

API キーが設定されていない場合、ユーザーにキーを直接尋ねないでください。 代わりに、プレースホルダー（DASHSCOPE_API_KEY=sk-your-key-here）を含む .env ファイルの作成を支援し、QianWen Console で取得した実際のキーに置き換えるよう案内してください。ユーザーが明示的に求めた場合に限り、実際のキー値を書き込んでください。

主な互換性

PAYG（sk-ws-...、旧形式の sk-...）と Token Plan（sk-sp-...）の両方のキーに対応しています。キーを公開せずに、API キーの種類を検出してください。

python3 -c "
import sys; sys.path.insert(0, 'scripts')
from qianwen_lib import detect_api_key_type
print(detect_api_key_type('scripts/qianwen_lib.py'))
"

出力	意味
token-plan	Token Plan キー — 以下の Token Plan カタログに記載されているモデルのみを使用してください。
payg	従量課金キー — すべてのモデルカタログを利用できます。
not-set	キーが設定されていません。

Token Plan の場合は、最新のToken Plan モデルカタログを取得して読み込み、記載されているモデルを正確に使用してください。CDN にアクセスできない場合は、ローカルの代替ファイルを使用してください。

Token Plan がサポートするモデルは限られています。上記のリファレンスに記載されているモデルをそのまま使用し、モデルの利用可否を推測したり、試しに問い合わせたりしないでください。PAYG の場合は、以下に進んでください。

モデルの選択

モデルを選択、推奨、またはデフォルトにする前に、最新のQwen テキストモデルカタログを取得して読み込んでください。カタログには、モデル一覧、基本的なモデル情報、推奨モデル、デフォルトモデルが記載されています。CDN にアクセスできない場合は、ローカルの代替ファイルを使用してください。

1. ユーザーがモデルを指定している → そのモデルをそのまま使用します。
2. 要件、シナリオ、料金に応じてモデルを選ぶ必要がある → qianwen-model-selector スキルを参照します。
3. 判断材料がなく、タスクが明確 → モデルカタログのデフォルトモデルを使用します。最高水準の推論やコーディングが必要な場合は、カタログで推奨されている高性能モデルを使用します。

⚠️ 重要：モデルカタログは特定時点のスナップショットであり、古くなっている可能性があります。モデルの提供状況は頻繁に変わります。モデルを決定する前に、必ず最新の正式なカタログである公式モデル一覧を確認してください。

モデルの詳細：特定のモデルの詳細については、ユーザーに https://www.qianwenai.com/models/<model-name> を案内してください。<model-name> は正確なモデル ID に置き換えてください。変更したり、推測したりしないでください。

動的なモデル情報の照会：qianwen-model-selector スキルまたは QianWen CLI（qianwen models info <model>）を利用できる場合は、リアルタイムのモデル情報を取得するために使用してください。CLI の利用には認証が必要です。ログイン手順については qianwen-usage スキルを参照してください。

実行

前提条件

• API キー：Key Compatibility の非平文検出機能を使用してください。キーの有無だけを確認する方法に置き換えないでください。キーが見つからない場合は、利用可能であれば qianwen-ops-auth を使用するか、.env で DASHSCOPE_API_KEY／QIANWEN_API_KEY を設定するようユーザーに案内してください。スキルは個別にインストールできます。
• Python 3.9 以降（標準ライブラリのみ。スクリプトの実行に pip install は不要）

環境の確認

初回実行の前に、Python が利用可能であることを確認してください。

python3 --version  # must be 3.9+

python3 が見つからない場合は、python --version または py -3 --version を試してください。Python が利用できないか、バージョンが 3.9 未満の場合は、execution-guide.md の * Path 2（curl）* に進んでください。

デフォルト：スクリプトを実行

スクリプトのパス：スクリプトは、scripts/ サブディレクトリ（このスキルのディレクトリ、つまり SKILL.md があるディレクトリ内）にあります。最初にこのスキルのインストール先ディレクトリを特定し、その後、スクリプトの実行には必ず絶対パスを使用してください。 スクリプトが現在の作業ディレクトリにあると想定しないでください。実行前にディレクトリを切り替えるために cd を使用しないでください。

実行時の注意：すべてのスクリプトはフォアグラウンドで実行し、標準出力を待ってください。バックグラウンドで実行しないでください。

引数の確認：まず python3 <this-skill-dir>/scripts/text.py --help を実行して、利用可能なすべての引数を確認してください。

python3 <this-skill-dir>/scripts/text.py \
  --request '{"messages":[{"role":"user","content":"Hello!"}],"model":"qwen3.7-plus"}' \
  --output output/qianwen-text/ --print-response

ストリーミングを使用する場合（対話形式での使用に推奨）：

python3 <this-skill-dir>/scripts/text.py \
  --request '{"messages":[{"role":"user","content":"Write a poem about the sea"}],"model":"qwen3.7-plus"}' \
  --stream --print-response

引数	説明
--request '{...}'	JSON リクエスト本文
--file path.json	ファイルからリクエストを読み込む（--request の代替）
--stream	ストリーミング出力を有効にする
--output path	レスポンス JSON をパスに保存する（.json 拡張子の場合はファイル、それ以外はディレクトリ）。上書きを避けるため、呼び出しごとに異なるファイル名を使用してください
--print-response	レスポンスを標準出力に表示する
--model ID	モデルを上書きする（リクエスト JSON でも設定可能）

モデルの優先順位：--model CLI フラグ > --request JSON の "model" フィールド > 組み込みのデフォルト。

結果の確認

• 終了コードが 0 で、出力に choices フィールドを含む有効な JSON がある → 成功
• ゼロ以外の終了、HTTP エラー、空の応答、または "code"／"message" エラーを含む JSON → 失敗
• エージェントが終了コードを読み取れない場合は、出力内でエラーパターン（Error、Traceback、401、403）を検索します
• 実行後の確認：--output を使用した場合は、応答 JSON ファイルが存在し、choices が含まれていることを確認します
• 必須 — stderr シグナルの確認：結果を確認した後、コマンドの stderr 出力で [ACTION_REQUIRED] または [UPDATE_AVAILABLE] を検索します。いずれかのシグナルがある場合は、ユーザーに返答する前に、以下の 更新の確認 の指示に必ず従ってください。

失敗した場合

スクリプトが失敗した場合は、以下の診断表でエラー出力を照合し、解決方法を確認します。一致するものがない場合は、 代替手段として、curl コマンド（パス 2）、Python SDK コード生成（パス 3）、自律的な解決（パス 5）について記載されている execution-guide.md を参照してください。

Python がまったく利用できない場合 → execution-guide.md のパス 2（curl）へ直接進みます。

エラーパターン	診断	解決方法
command not found: python3	PATH に Python がありません	python または py -3 を試します。見つからない場合は Python 3.9 以降をインストールします
Python 3.9+ required	スクリプトのバージョン確認に失敗	Python を 3.9 以降にアップグレードします
SyntaxError near type hints	Python が 3.9 未満です	Python を 3.9 以降にアップグレードします
QIANWEN_API_KEY/DASHSCOPE_API_KEY not found	API キーがありません	QianWen Console からキーを取得します。.env に追加します：echo 'DASHSCOPE_API_KEY=sk-...' >> .env。または、利用可能な場合は qianwen-ops-auth を実行します
HTTP 401	キーが無効、または一致していません	qianwen-ops-auth を実行します（平文ではないかの確認のみ）。キーが有効であることを確認します
SSL: CERTIFICATE_VERIFY_FAILED	SSL 証明書の問題（プロキシ／企業ネットワーク）	macOS：Install Certificates.command を実行します。それ以外の場合は、SSL_CERT_FILE 環境変数を設定します
URLError / ConnectionError	ネットワークに接続できません	インターネット接続を確認します。プロキシ経由の場合は HTTPS_PROXY を設定します
HTTP 429	レート制限に達しました	待機してから、バックオフを適用して再試行します
HTTP 5xx	サーバーエラー	バックオフを適用して再試行します
PermissionError	出力を書き込めません	書き込み可能なディレクトリを --output で指定します

クイックリファレンス

リクエストフィールド

フィールド	型	説明
prompt / messages	string | array	ユーザー入力またはメッセージのリスト
model	string	モデル ID（例：qwen3.7-plus）
system	string	システムプロンプト（任意）
temperature	float	0～2。ランダム性を制御します
max_tokens	int	出力トークンの最大数
tools	array	ツール呼び出し用の関数定義
stream	bool	ストリーミングを有効にします（対話形式での使用を推奨）
enable_thinking	bool	思考モードを有効にします。モデルごとにデフォルト設定が異なるため、変更する前に上記のモデルカタログを確認してください。リアルタイムタスクでは遅延が増加します。

レスポンスフィールド

フィールド	説明
text	生成されたテキストの内容
model	使用したモデル
usage	トークン使用量（prompt_tokens、completion_tokens）
tool_calls	関数呼び出しリクエスト（ツールを使用した場合）

高度な機能

これらは、リクエストパラメーターでサポートされる API レベルの機能です。すべて同じ chat/completions エンドポイントを使用します。

機能	有効化方法	備考
構造化出力	response_format: {"type": "json_schema", "json_schema": {...}}	スキーマに準拠した JSON 出力を強制します
ウェブ検索	enable_search: true	リアルタイムのウェブ検索を追加した応答です
深い思考	enable_thinking: true	拡張推論です。ユーザーが要求した場合にのみ有効です
関数呼び出し	tools: [...]	ツールで使用する関数を定義します
コンテキストキャッシュ	繰り返しのプレフィックスに対して自動適用。またはセッション単位で明示的に設定	繰り返しのコンテキストにかかるコストを削減します
部分モード	最後のメッセージ：{"role": "assistant", "content": "prefix…", "partial": true}	プレフィックスを続ける／完成させる
バッチ推論	JSONL 入力を使用する非同期バッチ API	50% のコスト割引

各機能の詳しい使い方については、api-guide.md と sources.md を参照してください。

エラー処理

エラー	原因	対処
401 Unauthorized	API キーが無効、または設定されていません	利用可能な場合は qianwen-ops-auth を実行します。それ以外の場合は、キーを設定するようユーザーに求めます（平文でないことのみ確認）
429 Too Many Requests	レート制限を超過しました	バックオフして再試行します
500 / 502 / 503	サーバーエラー	再試行し、ステータスページを確認します
Invalid model	モデル ID が見つかりません	上記のモデルカタログで ID を確認します
Invalid parameter	リクエスト本文に問題があります	JSON とフィールドの型を検証します
TypeError: ...proxies	openai SDK と httpx の互換性がありません	pip install --upgrade openai (>=1.55.0) を実行するか、スクリプト（標準ライブラリのみ）を使用します

利用状況と請求：使用状況、無料枠の上限、請求を直接確認するには、qianwen-usage スキルを使用してください。または、ユーザーは QianWen コンソールにアクセスできます。 利用状況分析 | 従量課金 | トークンプランのサブスクリプション

使用状況／請求／コンソールの URL を捏造、推測、作成してはいけません。 このスキルに記載された正確なリンクのみを提示してください。ここに記載されていない URL を作成してはいけません。

出力先

すべての出力先には、現在の作業ディレクトリを優先してください。--output を使用する場合のデフォルトのサブディレクトリ： ./output/qianwen-text/。

書き込み禁止：このスキルのインストールディレクトリや、skills/ 階層には、出力ファイルを絶対に書き込まないでください。生成されたコンテンツはすべて、現在の作業ディレクトリ内の output/、またはユーザー指定のパスに保存してください。

更新確認（実行後に必ず実施）

スクリプトの実行後、stderr にアクションシグナルがないか確認してください。スクリプトは更新状況を自動で検出し、 構造化されたシグナルを出力します。必ずそれらに対応してください。このセクションは、ユーザーから明示的に更新確認を依頼された場合にも適用されます。

シグナル：[ACTION_REQUIRED] qianwen-update-check skill is not installed

stderr にこのシグナルが含まれている場合、次の選択肢をユーザーに提示し、続行する前にユーザーの回答を待ってください。黙ってスキップしてはいけません。

更新確認スキルがインストールされていません。このスキルは、QianWen-AI/qianwen-ai の新機能やバグ修正についてお知らせします。

1. 今すぐインストール — インストールコマンドを実行します
2. 今回はスキップ — 今回は何もしません
3. 今後は通知しない — この確認を今後表示しないようにします

ユーザーの回答後：

• ユーザーが 1 を選択 → 次を実行します： npx skills add QianWen-AI/qianwen-ai --skill qianwen-update-check -y。続けて次を実行します： python3 <this-skill-scripts-dir>/gossamer.py --dismiss
• ユーザーが 2 を選択 → python3 <this-skill-scripts-dir>/gossamer.py --dismiss を実行し、その後通常どおり続行します
• ユーザーが 3 を選択 → python3 <this-skill-scripts-dir>/gossamer.py --never-install を実行し、その後通常どおり続行します

シグナル：[UPDATE_AVAILABLE]

stderr にこのシグナルが含まれている場合、バージョン情報と stderr に表示された更新コマンドを含む、簡潔な更新通知を回答に追加してください。

stderr にシグナルがない場合

stderr に [ACTION_REQUIRED] も [UPDATE_AVAILABLE] も含まれていない場合は、対応不要です。スキルはインストール済みで最新です（または24時間以内にキャッシュされています）。

明示的なユーザーのリクエスト

ユーザーが更新の確認を明示的に依頼した場合（「更新を確認して」「バージョンを確認して」など）：

1. 隣接するスキルディレクトリ内に qianwen-update-check/SKILL.md があるか確認します。
2. 見つかった場合は、python3 <qianwen-update-check-dir>/scripts/check_update.py --print-response を実行し、結果を報告します。
3. 見つからなかった場合は、上記のインストール方法を提示します。

参考資料

• execution-guide.md — フォールバックの方法（curl、SDK、自律実行）、関数呼び出し、 思考モード
• api-guide.md — 詳細なコード例を含む API の補足ガイド
• sources.md — 公式ドキュメントの URL