Use this skill for SDK setup and credential checks only. Keep the user focused on proving that Python can authenticate against Jinkō and read one project item list before moving to model, vpop, protocol, output-set, or trial workflows.
Workflow
- Confirm the user has Python 3.10+.
- Install the SDK and dotenv support when needed:
pip install jinko python-dotenv. - Ask the user to create an API key using
https://doc.jinko.ai/docs/api/if they do not already have one. - Ask the user to set
JINKO_API_KEYandJINKO_PROJECT_IDin their shell or local.envfile. - Point them to
assets/.env.exampleas the safe template. Do not ask them to paste secrets into chat. - Run or adapt
scripts/check_jinko_connection.pyto fail fast on configuration, authentication, authorization, or project-read-access issues. - If the check passes, report that the Jinkō connection is OK.
- When the user wants to browse the project after setup, recommend
client.search(...)as the default read-only exploration call before moving to a workflow-specific skill.
Required Configuration
JINKO_API_KEY: API key created in the Jinkō web interface.JINKO_PROJECT_ID: project identifier used by the SDK forX-jinko-project-id.
The SDK also supports JINKO_BASE_URL, but do not introduce alternate environments unless the user explicitly needs them.
Validation Script
Use the bundled script instead of writing ad hoc checks:
python skills/jk-sdk-setup/scripts/check_jinko_connection.py
The script:
- Loads
.envwhenpython-dotenvis installed. - Redacts sensitive values when showing configuration.
- Requires both
JINKO_API_KEYandJINKO_PROJECT_ID. - Constructs
JinkoClient()from environment variables. - Calls
client.auth_check()to prove authentication and project read access. - Prints minimal output on success.
Use --show-config only when debugging local setup; it prints presence and redacted values, never the full API key.
After Validation
Once the connection check passes, prefer client.search(...) for project exploration because it gives the user an immediate view across project items.
Use a minimal example like:
from jinko import JinkoClient
client = JinkoClient()
client.search(limit=20, table_columns="compact")
Use search() when the user wants to:
- browse what exists in the configured project
- find an item by name or free text
- orient themselves before choosing a model, protocol, vpop, or trial workflow
Keep the setup script focused on authentication and access checks. Use search() only after validation succeeds, not as a replacement for the fail-fast check.
Troubleshooting
- For
ConfigurationError, check that.envor the shell environment contains both required variables. - For missing
JINKO_API_KEY, direct the user tohttps://doc.jinko.ai/docs/api/. - For
AuthenticationError, assume the API key is missing, expired, malformed, or copied incorrectly. - For
AuthorizationError, assume the API key is valid but does not have access to the requested project. - For other SDK request failures, check that
JINKO_PROJECT_IDis copied exactly and that the network can reach Jinkō. - For import errors, reinstall with
pip install jinko python-dotenvin the active Python environment. - If the user uses
direnv, ask them to ensure.envrcloads.env, then rundirenv allow.
Reference Routing
Read references/setup-check.md when you need implementation details for the bundled script or a concise explanation of the fail-fast check.