Sokel Plugin SDK — Python
用 Python 写 Sokel 插件。契约写在 sokel.yaml 里（语言中立），
sokel-gen 把它生成成 pydantic 模型与类型化的注册口；SDK 负责注册、传输、凭证、文件、心跳与重连。
async def issues_list(ctx: Ctx, in_: IssuesListIn) -> IssuesListOut:
issues = await client.list_issues(in_.project, in_.state)
return IssuesListOut(issues=issues, count=len(issues))
on_issues_list(p, issues_list)
in_.project 拼错是 IDE 里的红线，不是线上的一次失败调用——代码里没有任何 dict["key"]。
装
pip install sokel-plugin-sdk
go install github.com/sokel-dev/sokel-plugin-sdk/cmd/sokel-gen@latest # 生成器
sokel-gen 是个单文件二进制（Go 写的），只在生成时用到；跑插件时不需要它。
四步
sokel-gen init -lang python ./my-plugin
cd my-plugin
pip install -r requirements.txt
sokel-gen generate . # sokel.yaml → sokel_gen.py
python main.py
- 声明 ——
sokel.yaml：操作、事件、凭证、认证方式。格式见 docs/manifest.md。 - 生成 ——
sokel-gen generate .产出sokel_gen.py：每个操作一对XxxIn/XxxOut模型 和一个on_xxx(p, fn)；每个事件一个 payload 模型和一个trigger_xxx(ctx, event_id, payload)。 - 实现 —— handler 签名完全具体，可以是
async def也可以是普通函数。 - 连接 ——
asyncio.run(p.run())。插件出站连平台：无入站端口、无公网 IP、无防火墙洞。
能力一览
| 要做的事 | 怎么写 |
|---|---|
| 读凭证 | credential(ctx) → 生成的 Credential 模型 |
| 取入参文件的字节 | await ctx.fetch(in_.file) |
| 产出文件 | await ctx.upload(name, mime, data) → 放进出参 |
| 流式产出 | out.text(...) 逐帧给人看，out.vars(Out(...)) 给下游 |
| 推事件 | await trigger_message(ctx, event_id, MessageEvent(...)) |
| 常驻事件源 | p.register_source(id, label, fn)，循环里判 ctx.stopping.is_set() |
| 平台代收 webhook | p.register_webhook(fn)，返回 ok() / text(401, "...") |
| 协作式认证 | p.register_auth(start=…, poll=…, submit=…) |
| 会话型凭证刷新 | await ctx.update_credential({"session": "…"}) |
| 自报运行态 | ctx.report_status("auth_required", "…") |
配置
SDK 读 SOKEL_ 前缀的环境变量：
| 变量 | 必填 | 含义 |
|---|---|---|
SOKEL_ENDPOINT |
是 | nats://broker:4222，或 https:// 平台地址（经 /connect-info 发现 broker） |
SOKEL_TOKEN |
是 | 接入组 token（skp_…），平台据此认「插件 + 工作空间」 |
SOKEL_NATS_TOKEN |
否 | broker 的传输层鉴权 |
SOKEL_NATS_CA |
否 | tls:// broker 的自定义 CA |
SOKEL_INSTANCE_ID |
否 | 固定副本身份（默认按 token 指纹落盘复用） |
SOKEL_REGION |
否 | 副本的地域标注 |
凭证从不由插件存储：平台随每次调用把解析后的字段下发下来。
例子
examples/kitchen-sink 覆盖了全部形态——每种字段、文件、流式、
事件、webhook、协作式认证各一份，Python 与 Node 实现的是同一份声明。
cd examples/kitchen-sink/python
pip install -r requirements.txt
SOKEL_ENDPOINT=nats://localhost:4222 SOKEL_TOKEN=skp_xxx python main.py
开发本 SDK
uv venv && uv pip install -e '.[dev]'
python -m pytest -q
License
Apache-2.0.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file sokel_plugin_sdk-0.2.1.tar.gz.
File metadata
- Download URL: sokel_plugin_sdk-0.2.1.tar.gz
- Upload date:
- Size: 30.2 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
dccf3160b7b6c0ad068ecf4007336f4206d3bad16b6163ca1089816a148443a5
|
|
| MD5 |
3b373180cf057651e45921e4d82e279a
|
|
| BLAKE2b-256 |
ec6e4c5fa22b81107dcf120f97f7dce26afb94d37e97dced4bbfa165fabb2ce8
|
Provenance
The following attestation bundles were made for sokel_plugin_sdk-0.2.1.tar.gz:
Publisher:
release.yml on sokel-dev/sokel-plugin-sdk
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
sokel_plugin_sdk-0.2.1.tar.gz -
Subject digest:
dccf3160b7b6c0ad068ecf4007336f4206d3bad16b6163ca1089816a148443a5 - Sigstore transparency entry: 2600512717
- Sigstore integration time:
-
Permalink:
sokel-dev/sokel-plugin-sdk@4343105a20c5c7aef8384b1fdf702b6dd0b876f2 -
Branch / Tag:
refs/tags/v0.2.1 - Owner: https://github.com/sokel-dev
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@4343105a20c5c7aef8384b1fdf702b6dd0b876f2 -
Trigger Event:
push
-
Statement type:
File details
Details for the file sokel_plugin_sdk-0.2.1-py3-none-any.whl.
File metadata
- Download URL: sokel_plugin_sdk-0.2.1-py3-none-any.whl
- Upload date:
- Size: 29.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
6c26a8e1102e076f79d1e4febb9481b8e965d1eb461ff906217b5e9b0402468d
|
|
| MD5 |
714dd4ae888bab6dd3b9fd14c39cc236
|
|
| BLAKE2b-256 |
7cc06c7d85d2dc57ba107b4468ec6b43c1c8e51a66a22e9fbf71742e0003afff
|
Provenance
The following attestation bundles were made for sokel_plugin_sdk-0.2.1-py3-none-any.whl:
Publisher:
release.yml on sokel-dev/sokel-plugin-sdk
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
sokel_plugin_sdk-0.2.1-py3-none-any.whl -
Subject digest:
6c26a8e1102e076f79d1e4febb9481b8e965d1eb461ff906217b5e9b0402468d - Sigstore transparency entry: 2600512822
- Sigstore integration time:
-
Permalink:
sokel-dev/sokel-plugin-sdk@4343105a20c5c7aef8384b1fdf702b6dd0b876f2 -
Branch / Tag:
refs/tags/v0.2.1 - Owner: https://github.com/sokel-dev
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@4343105a20c5c7aef8384b1fdf702b6dd0b876f2 -
Trigger Event:
push
-
Statement type:
