jinko-sdk-setup

Jinkō SDK 设置

仅在设置 SDK 和检查凭据时使用此技能。在转向模型、vpop、protocol、output-set 或 trial 工作流之前，先让用户确认 Python 能通过身份验证连接 Jinkō，并读取一个项目条目列表。

请注意：正确的软件包是 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 会兑换一次代码，将 bearer 保存在 JINKO_API_TOKEN 中，并清除 JINKO_SESSION_CODE。新进程看不到该 bearer。请为新进程获取新的代码。
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 是否与所有依赖 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()：

• 浏览配置项目中的现有内容
• 按名称或自由文本查找条目
• 在选择模型、protocol、vpop 或 trial 工作流之前熟悉项目

设置脚本仅在身份验证成功后，通过一次不渲染结果的单条目 search() 检查项目读取权限。只有验证成功后，才使用结果更多、可交互的 search() 进行探索。

阅读 SDK 签名

只从 jinko 导入 JinkoClient 和/或 JinkoOrgClient，并可选择导入异常。SDK 没有 jinko.model 或 jinko.models 模块。其他对象都从客户端获取，然后在需要时使用 help() 查看其签名和文档字符串：

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

使用 org.auth_check() 在不提供项目 ID 的情况下读取密钥声明的范围。 list_projects() 可能会包含该范围之外的项目。在多项目 工作流中，对每个项目客户端调用 client.auth_check()，并捕获 AuthenticationError，以跳过范围外的项目。然后请求项目 资源，以验证实际访问权限。对于不包含密钥元数据的身份验证响应， 只进行凭据检查。

故障排查

重新运行检查，并根据其确定性诊断采取相应措施。不要用临时检查替代它，也不要要求用户分享机密。