jinko-sdk-setup

Jinkō SDK のセットアップ

このスキルは、SDK のセットアップと認証情報の確認にのみ使用してください。モデル、vpop、プロトコル、出力セット、トライアルのワークフローに進む前に、Python で Jinkō に認証し、1 つのプロジェクト項目リストを読み取れることの確認に専念してください。

注意：正しいパッケージは jinko-sdk で、jinko モジュールをエクスポートします。jinko は Jinko SDK とは無関係の別パッケージです。

認証情報

接続を確認する前に、これを行ってください。Jinko MCP サーバーに接続している場合、.env がないのは想定内です。作成するために作業を止めないでください。

JinkoClient() は環境変数から認証情報を読み取ります。SDK の各コマンドを実行するたびに、次の両方を設定してください。

1. JINKO_PROJECT_ID — ユーザーが作業しているプロジェクトの ID です。必ず設定してください。推測して設定しないでください。
2. いずれかの認証情報。Jinko MCP ツール get_session_code が利用可能な場合は、JINKO_SESSION_CODE を優先してください。このツールが利用できない場合にのみ、JINKO_API_KEY を使用してください。両方が設定されている場合は、JINKO_SESSION_CODE が使用されます。

セッションコード

セッションコードは一度しか交換できません。接続確認を含む各 SDK プロセスの直前に、毎回 get_session_code を呼び出してください。プロセスに渡したコードは再利用しないでください。

1. 引数なしで get_session_code を呼び出します。
2. ツールは code と expiresAt を含む JSON を返します。そのプロセスでのみ、code を JINKO_SESSION_CODE として設定します。
3. コードを .env、チャット、ログ、バージョン管理に含めないでください。
4. プロセス内で SDK はコードを一度だけ交換し、ベアラーを JINKO_API_TOKEN に保持して、JINKO_SESSION_CODE を削除します。新しいプロセスからは、そのベアラーを参照できません。新しいプロセスごとに新しいコードを取得してください。
5. expiresAt を過ぎた後、または SDK が認証エラーを報告した場合も、get_session_code を再度呼び出してください。

get_session_code が失敗し、JINKO_API_KEY がすでに設定されている場合は、API キーを使って続行し、セッションコードを利用できなかったことを伝えてください。

API キー

Jinko MCP の get_session_code ツールが利用できない場合にのみ、環境変数またはローカルの .env にある JINKO_API_KEY を使用してください。ユーザーにチャットへキーを貼り付けるよう求めないでください。

ワークフロー

SDK バージョンの前提条件： 以下のチェックを実行してください。これは SDK に同梱されており、API にアクセスする前に、インストール済みの SDK と依存するすべての隣接スキルとの互換性を検証します。

決定的なチェックを実行し、成功またはエラーのメッセージに従ってください。

python -m jinko.cli.check_jinko_connection

スクリプトは次の処理を行います。

• python-dotenv がインストールされている場合は、.env を読み込みます。
• 設定を表示する際に、機密情報をマスキングします。
• JINKO_API_KEY（プロジェクトキーまたは組織キー）または JINKO_SESSION_CODE を必須とします。両方の認証情報変数が設定されている場合は、JINKO_SESSION_CODE が使用されます。
• JINKO_PROJECT_ID が設定されていない場合は、JinkoOrgClient().list_projects() を使って、キーから参照できるプロジェクトを一覧表示します。この一覧にはキーのスコープが表示されないため、スクリプトはキーの種類を報告しません。
• JINKO_PROJECT_ID が設定されている場合は、JinkoClient() を構築し、client.auth_check() を呼び出した後、client.search(limit=1, show_table=False, show_table_hint=False) を実行して、プロジェクト項目への最小限の読み取り専用アクセスを確認します。
• 成功時は、JINKO_PROJECT_ID が設定されている場合のキーの種類など、必要最小限の出力を表示します。

--show-config はローカルのセットアップをデバッグするときにのみ使用してください。設定の有無とマスキングされた値が表示され、API キーやセッションコード全体は表示されません。

検証後

接続確認に合格したら、プロジェクト項目全体をすぐに確認できるため、プロジェクトの探索には client.search(...) を優先してください。

次のような最小限の例を使用します。

from jinko import JinkoClient

client = JinkoClient()
client.search(limit=20, columns="compact")

ユーザーが次のことを希望する場合は、search() を使用してください。

• 設定済みのプロジェクトに何があるかを確認する
• 名前またはフリーテキストで項目を検索する
• モデル、プロトコル、vpop、トライアルのワークフローを選ぶ前に、プロジェクトの概要を把握する

セットアップスクリプトでは、認証後のプロジェクト読み取り確認として、項目数を 1 件に限定し、レンダリングしない search() のみを使用します。検証に合格した後の探索に限り、より大規模な対話型の search() を使用してください。

SDK のシグネチャを確認する

JinkoClient および／または JinkoOrgClient のみをインポートし、必要に応じて jinko から例外をインポートしてください。SDK に jinko.model または jinko.models モジュールはありません。それ以外のオブジェクトはすべてクライアントから取得し、必要に応じて help() でシグネチャと docstring を確認してください。

model = client.get_model("cm-...")
help(client.get_model)
help(type(model))  # every method of the returned object
help(model.simple_solve)

型注釈で名前を指定する場合に限り、jinko.domain からクラスをインポートしてください。たとえば、from jinko.domain import Model のようにします。シグネチャを調べるために、インストール済みパッケージのソースを検索するのは避けてください。

クライアントの選択

どちらのクライアントもプロジェクトキーと組織キーを受け取るため、タスクに応じて選択してください。JINKO_PROJECT_ID が示すプロジェクトで作業する場合は、JinkoClient() を使用してください。JINKO_PROJECT_ID が未設定の場合や、タスクが複数のプロジェクトにまたがる場合は、JinkoOrgClient を使用してください。JinkoOrgClient が読み取るのは JINKO_API_KEY と JINKO_BASE_URL のみです。

from jinko import JinkoOrgClient

org = JinkoOrgClient()
for project in org.list_projects():
    print(project.id, project.name)

client = org.project(project.id)  # a JinkoClient for that project

プロジェクト ID を指定せずにキーの宣言済みスコープを確認するには、org.auth_check() を使用してください。 list_projects() には、そのスコープ外のプロジェクトが含まれる場合があります。複数プロジェクトにまたがるワークフローでは、各プロジェクトクライアントで client.auth_check() を呼び出し、AuthenticationError を捕捉してスコープ外のプロジェクトをスキップしてください。その後、プロジェクトのリソースをリクエストして、実際にアクセスできることを確認してください。キーのメタデータを含まない認証レスポンスでは、認証情報の確認のみが行われます。

トラブルシューティング

チェックを再実行し、その確定的な診断結果に基づいて対処してください。独自のチェックに置き換えたり、ユーザーに秘密情報の共有を求めたりしないでください。