matelab-python-sdk 0.3.0a1__tar.gz → 0.3.0a2__tar.gz

{matelab_python_sdk-0.3.0a1 → matelab_python_sdk-0.3.0a2}/.agents/skills/matelab-sdk-release/SKILL.md

@@ -34,7 +34,8 @@ coverage 和当前态文档。公开接口和生命周期沿 public intent → w
 ## 2. 验证与审查
 
 执行 `docs/agent-workflows.md#delivery-gate`，具体命令取 `docs/development.md#development`。
-代码、契约、依赖或构建行为变化先聚焦再完整测试；聚焦用例不能代替完整 `pytest`。修复需补充的用例来自契约、
+代码、契约、依赖或构建行为变化先聚焦再完整测试；聚焦用例不能代替完整 `pytest`。发布前的支持版本测试、静态
+检查和安装后消费验证在本地完成，发布 CI 不重复执行。修复需补充的用例来自契约、
 独立示例或可验证属性，不复刻实现，不增加 Provider 逐路由 conformance。
 
 真实 smoke 按 `docs/agent-workflows.md#provider-validation` 确认目标、ignore 和授权。授权覆盖隔离服务的登录、
@@ -58,17 +59,21 @@ SDK 版本与 spec 日历版本独立，不跳过未占用的预发布序号。`
 本项目版本。仅改版本时保持其余 lock 内容，使用发布 workflow 固定的 uv 检查兼容性。
 
 按需读配置/依赖章节；不因发布顺手升级依赖、Node、uv 或流水线插件。文档在提交前完成，仅维护受影响的当前态，不新建
-CHANGELOG。正常发布由 CI 完成可复现构建、制品审计和安装后消费；只有打包故障或打包配置变化需要时才本地构建，
-使用临时目录，不积累 `dist/`。
+CHANGELOG。本地为发布前消费验证、打包故障或打包配置变化按需构建，使用临时目录，不积累 `dist/`。
 
 复核最终 diff、版本、Contract pin 和有效验证证据，将本次尚未提交的实现、测试、文档及版本号放入同一个
 release commit。已有提交的历史仅在另有授权时改写。
 
-## 4. 推送、发布并核验
+## 4. 推送与自动发布
 
-执行 `docs/agent-workflows.md#release`：创建指向 release commit 的 annotated `v{version}` tag，推送
-`origin` 的 main/tag，并验证远端 refs；tag 推送自动触发发布 CI。跟踪该 commit/tag 的 CI，确认测试、
-可复现构建、制品审计、安装后消费和 PyPI 上传成功；tag 推送成功不等于发布完成。
+本地验证通过后，按 `docs/agent-workflows.md#release` 完成：
+
+1. 创建指向本次 release commit 的新 annotated `v{version}` tag，版本与 `pyproject.toml` 一致。
+2. 推送 `origin` 的 main 和本次新 tag，核对远端 refs 均对应本次 release commit。
+3. 跟踪新 tag 自动触发的 Gitee 流水线，由其完成可复现构建、制品审计和 PyPI 上传；CI 不重复本地验证。
+
+已发布版本不可覆盖，对应 tag 不再移动。main 可以继续前进，无需与历史 tag 指向同一提交；
+后续发版使用新版本、新 tag。
 
 从本次 CI 构建审计输出或下载的制品取得 wheel/sdist 的 SHA-256，不能仅用 PyPI 自报哈希证明 CI/PyPI 一致。
 在 SDK 锁定开发环境中运行本技能的只读核验器：
@@ -85,5 +90,5 @@ uv run --frozen --no-sync python -B .agents/skills/matelab-sdk-release/scripts/v
 历史制品。PyPI 暂未可读时允许短暂重试，等待期间保持进度更新。
 
 失败时定位具体阶段，优先重试失败环节；不通过删测试、跳检查或自动另选版本制造成功。改变已推送历史或处理失败
-候选前核对现有授权，已发布版本不可覆盖。最后报告版本/链接、单次提交、`origin` 的 main/tag refs、CI/PyPI 核验和工作区状态；
+候选前核对现有授权。最后报告版本/链接、发布提交、main 与新 tag 的远端 refs、Gitee/PyPI 核验和工作区状态；
 明确剩余失败或未验证项。

{matelab_python_sdk-0.3.0a1 → matelab_python_sdk-0.3.0a2}/.workflow/release.yml

@@ -10,26 +10,26 @@ triggers:
         - v
 stages:
   - name: release
-    displayName: Test, build and publish
+    displayName: Build and publish
     strategy: naturally
     trigger: auto
     steps:
       - step: build@python
         name: build-and-publish
-        displayName: Validate and publish release
+        displayName: Build and publish release
         # Gitee's Python bootstraps uv; the SDK runs on uv-managed Python 3.15.
         pythonVersion: "3.14"
         commands: |
           set +x
           set -eu
-          # Gitee injects its pytest tooling into Python's import path.
+          # Keep Gitee's Python tooling out of the build environment.
           unset PYTHONPATH PYTHONHOME
           python -m pip install --user --index-url https://pypi.org/simple "uv==0.13.7"
           export PATH="$(python -m site --user-base)/bin:$PATH"
           uv --version
           release_tag="v$(uv version --short)"
           build_ref="${GITEE_BRANCH:?Gitee build ref is required}"
-          if [ "$build_ref" != main ] && [ "$build_ref" != "$release_tag" ]; then
+          if [ "$build_ref" != "$release_tag" ]; then
             echo "Release ref must be $release_tag; received $build_ref" >&2
             exit 1
           fi
@@ -37,20 +37,10 @@ stages:
             echo "Checkout does not match the Gitee build commit" >&2
             exit 1
           fi
+          : "${UV_PUBLISH_TOKEN:?Configure UV_PUBLISH_TOKEN as a protected pipeline secret}"
           export SOURCE_DATE_EPOCH="$(git show -s --format=%ct HEAD)"
-          unset MATELAB_PROVIDER_BASE_URL MATELAB_PROVIDER_USERNAME MATELAB_PROVIDER_PASSWORD
-
-          test_status=0
-          for python_version in 3.12 3.13 3.14 3.15; do
-            uv run --frozen --exact --python "$python_version" pytest -rs || test_status=1
-          done
-          test "$test_status" -eq 0
-
           export UV_PYTHON="$(cat .python-version)"
-          uv run --frozen python scripts/generate_models.py --check
-          uv run --frozen ruff check .
-          uv run --frozen ruff format --check .
-          uv run --frozen basedpyright
+          uv sync --frozen
 
           mkdir -p dist/release dist/reproducible
           uv build --no-build-isolation --out-dir dist/release
@@ -61,24 +51,6 @@ stages:
           (cd dist/release && sha256sum *.whl *.tar.gz > SHA256SUMS)
           cat dist/release/SHA256SUMS
 
-          sdk_consumer_dir="$(mktemp -d)"
-          trap 'rm -rf -- "$sdk_consumer_dir"' EXIT
-          uv venv "$sdk_consumer_dir/venv"
-          uv pip install \
-            --python "$sdk_consumer_dir/venv/bin/python" \
-            dist/release/*.whl \
-            "basedpyright>=1.40.2" \
-            "nodejs-wheel-binaries==22.20.0"
-          "$sdk_consumer_dir/venv/bin/python" scripts/check_installed_package.py
-          "$sdk_consumer_dir/venv/bin/basedpyright" \
-            --pythonpath "$sdk_consumer_dir/venv/bin/python" \
-            --project tests/typing/pyproject.toml
-
-          if [ "$build_ref" = main ]; then
-            echo "Validation passed on main; publishing requires tag $release_tag"
-            exit 0
-          fi
-          : "${UV_PUBLISH_TOKEN:?Configure UV_PUBLISH_TOKEN as a protected pipeline secret}"
           uv publish --trusted-publishing never \
             --publish-url https://upload.pypi.org/legacy/ \
             dist/release/*.whl dist/release/*.tar.gz

{matelab_python_sdk-0.3.0a1 → matelab_python_sdk-0.3.0a2}/AGENTS.md

@@ -12,8 +12,8 @@
 4. **验证**：按变更类型执行 [delivery gate](docs/agent-workflows.md#delivery-gate)，复用仍覆盖当前变更的有效结果。
 5. **交付**：复核最终 diff 和状态，报告结果、验证证据、限制及未执行项。
 
-本地仅为打包配置、构建元数据、发布脚本变化或制品故障按需构建。正式可复现构建、制品审计和安装后消费由
-发布 CI 执行，本地无需重复构建或保留历史 `dist/` 产物。
+发布前在本地完成测试、静态检查和安装后消费验证；发布 CI 只负责可复现构建、制品审计和 PyPI 上传。
+本地为发布前消费验证、打包配置或制品故障按需构建，使用临时目录，不保留历史 `dist/` 产物。
 
 ## 分支指针
 

{matelab_python_sdk-0.3.0a1 → matelab_python_sdk-0.3.0a2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: matelab-python-sdk
-Version: 0.3.0a1
+Version: 0.3.0a2
 Summary: Reusable async Python client for the Matelab Integration Contract
 Author: CMPDC, Institute of Physics, Chinese Academy of Sciences
 License-Expression: Apache-2.0

{matelab_python_sdk-0.3.0a1 → matelab_python_sdk-0.3.0a2}/contracts/matelab-integration-v1.lock.json

@@ -2,12 +2,12 @@
   "schema_version": 1,
   "contract_line": "integration-v1",
   "release": {
-    "tag": "v2026.11.2",
-    "commit": "a986f73b0edc6bb67f2993a9ee1291aba31df5e5"
+    "tag": "v2026.11.4",
+    "commit": "199f1ae307e0561bd7c4ec8ce5af22d05486e7e9"
   },
   "openapi": {
     "source_path": "openapi/matelab-integration-v1.openapi.yaml",
     "snapshot": "matelab-integration-v1.openapi.yaml",
-    "sha256": "4a485f0ab2b589136cdcccad77407d8b5768e6e8cbb8e3a7636d8b9a07649991"
+    "sha256": "769629096ccdd9d4198aefd738e522afa268ec77a146cf4548fc3b1715985b49"
   }
 }

{matelab_python_sdk-0.3.0a1 → matelab_python_sdk-0.3.0a2}/contracts/matelab-integration-v1.openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: Matelab Integration Contract
-  version: "2026.11.2"
+  version: "2026.11.4"
   description: |
     Current PHP wire contract for generating SDKs against the selected
     `matelab-server` Provider version.
@@ -18,7 +18,7 @@ info:
   x-contract-line: integration-v1
   x-provider-evidence:
     repository: /home/tnzhu/projects/matelab-server
-    commit: f5a714e17cd76076efe7579db279936ac29b50a6
+    commit: fa4172020c6a9f2955ed02a763bfce909ef63aa3
     verificationRuntime:
       baseUrl: https://matelab.iphy.ac.cn/eln-test/api
       container: matelab-test-server-1
@@ -53,6 +53,7 @@ info:
       - lib/Route.php
       - lib/HttpServer.php
       - lib/WsServer.php
+      - lib/Taskscheduler.php
       - start.php
       - lib/MultiException.php
       - config/Db.php
@@ -62,17 +63,16 @@ info:
       - sql/matelab.sql
       - sql/recommend.sql
   x-provider-audit:
-    currentCommit: f5a714e17cd76076efe7579db279936ac29b50a6
-    previousReleaseEvidenceCommit: 00f17b6ce0906bb78b0a3e9bb8c50abee90ca3d0
-    lastProviderVerifiedCommit: f5a714e17cd76076efe7579db279936ac29b50a6
+    currentCommit: fa4172020c6a9f2955ed02a763bfce909ef63aa3
+    previousReleaseEvidenceCommit: f5a714e17cd76076efe7579db279936ac29b50a6
+    lastProviderVerifiedCommit: fa4172020c6a9f2955ed02a763bfce909ef63aa3
     contractStatus: current-provider-aligned
     # Summary of changes adopted by current Supported Routes since the last
     # released contract, including contract corrections. The Provider diff is
     # previousReleaseEvidenceCommit -> currentCommit. Accumulate unreleased
     # updates against that fixed release baseline; use [] if no relevant changes.
     # Entries are not per-change verification results or a cumulative history.
-    incorporatedChanges:
-      - {operationId: stageTemporaryFile, change: filename-independent-continuation-with-final-fragment-name-and-extensionless-abort}
+    incorporatedChanges: []
   x-consumer-evidence:
     - repository: /home/tnzhu/projects/matelab-mcp
       commit: 94a129b2df0ef0fbcf179c10550fb7c9a5dd2e6f

{matelab_python_sdk-0.3.0a1 → matelab_python_sdk-0.3.0a2}/docs/agent-workflows.md

@@ -32,7 +32,7 @@
   `reportUnannotatedClassAttribute`、`reportIncompatibleUnannotatedOverride`，其他设置放在其后。沿用 SDK 的目标
   Python 版本与检查路径，不照搬其他项目的值。
 - 升级 runtime、build 或 dev 依赖时，必须将验证通过的新版本同步为 `pyproject.toml` 中对应依赖的 `>=` 下限，
-  同时更新对应 CI 约束（包括安装后消费检查）。`uv.lock` 必须通过 `uv lock` 等 uv 命令自动更新，不手工编辑。
+  同时更新对应 CI 和本地安装后消费校验中的约束。`uv.lock` 必须通过 `uv lock` 等 uv 命令自动更新，不手工编辑。
   例外：`nodejs-wheel-binaries` 保留系统所需的精确版本，并同步 lock 和对应 CI 约束。
 - 构建后端依赖和 wheel package 显式配置；metadata 与制品检查从这些声明推导预期值。
 
@@ -91,10 +91,12 @@ Ruff/Basedpyright 诊断通过修复代码或精确 ignore 解决，不缩小检
 1. 按 [版本规则](development.md#versioning) 选择 SDK 版本，读取 `[project].version`，确认待发布版本未发布
    且 Contract pin 完整。公开接口删除、重命名、类型收紧或不兼容行为变化按 breaking change 处理。
    完成标准：版本、当前文档和 tag 名 `v{version}` 一致。
-2. 提交前同步受影响的当前文档，完成 [delivery gate](#delivery-gate)。构建元数据或发布流程变化时，核对
+2. 提交前同步受影响的当前文档，在本地完成 [delivery gate](#delivery-gate)、支持版本测试与安装后消费校验。
+   构建元数据或发布流程变化时，核对
    metadata 与流水线固定版本的 uv 是否兼容；需要本地制品证据时使用
    [手工构建命令](development.md#reproducible-release-build)。创建已审查、已授权的 release commit。
-3. 创建指向 release commit 的 annotated `v{version}` tag，推送 `origin` 的 main/tag；tag 推送自动触发
-   [发布 CI](../.workflow/release.yml)。
-4. 跟踪发布 CI 的测试、可复现构建、制品审计、安装后消费和 PyPI publish。
-   完成标准：`origin` 的 main/tag 对应 release commit，CI 全部通过，PyPI 对应版本与 CI 制品哈希一致。
+3. 本地验证通过后，创建指向 release commit 的新 annotated `v{version}` tag，推送 `origin` 的 main 和新 tag；
+   tag 推送自动触发 Gitee [发布 CI](../.workflow/release.yml)。已发布版本不可覆盖，对应 tag 不再移动；main 可继续
+   前进，无需与旧 tag 指向同一提交，后续发版使用新版本、新 tag。
+4. 跟踪新 tag 的 Gitee 可复现构建、制品审计和 PyPI 上传；CI 不重复本地测试、静态检查或消费校验。
+   完成标准：本地验证通过，本次推送的 main/新 tag 对应 release commit，Gitee 发布成功，PyPI 与 CI 制品哈希一致。

{matelab_python_sdk-0.3.0a1 → matelab_python_sdk-0.3.0a2}/docs/api.md

@@ -5,13 +5,13 @@ See the [README](../README.md) for installation and quick start and [CONTEXT.md]
 
 ## Contract
 
-The SDK is pinned to the immutable `matelab-spec v2026.11.2` Contract Release. The sole pin,
+The SDK is pinned to the immutable `matelab-spec v2026.11.4` Contract Release. The sole pin,
 [contracts/matelab-integration-v1.lock.json](../contracts/matelab-integration-v1.lock.json), records peeled commit
-`a986f73b0edc6bb67f2993a9ee1291aba31df5e5`, source `openapi/matelab-integration-v1.openapi.yaml`, the local snapshot path,
-and SHA-256 `4a485f0ab2b589136cdcccad77407d8b5768e6e8cbb8e3a7636d8b9a07649991`. The annotated tag object is
-`dc7a09dccf4187100cd05241757fc3f500107bdd`.
+`199f1ae307e0561bd7c4ec8ce5af22d05486e7e9`, source `openapi/matelab-integration-v1.openapi.yaml`, the local snapshot path,
+and SHA-256 `769629096ccdd9d4198aefd738e522afa268ec77a146cf4548fc3b1715985b49`. The annotated tag object is
+`b1748d96763669461cfa9467d6a4cd1273f53b41`.
 
-The Contract uses Provider source evidence from `f5a714e17cd76076efe7579db279936ac29b50a6`; v2026.11.2 validation ran
+The Contract uses Provider source evidence from `fa4172020c6a9f2955ed02a763bfce909ef63aa3`; v2026.11.4 validation ran
 against an isolated test instance and does not establish production behavior. The Front Consumer evidence
 `f7a7b952d7981f169d5c2585aea5c94b418086a3` informs cross-Consumer capability review but does not define the SDK interface.
 

{matelab_python_sdk-0.3.0a1 → matelab_python_sdk-0.3.0a2}/docs/development.md

@@ -17,8 +17,8 @@ according to its public impact.
 
 Use Python 3.15 for development; `.python-version` selects it for `uv sync` and `uv run`.
 The SDK supports Python 3.12 and newer. Source syntax, type checking, and generated models target Python 3.12.
-Release CI tests Python 3.12, 3.13, 3.14, and 3.15. Generated-model, lint, formatting, and type checks run only on
-Python 3.15, which also builds the distributions and checks the installed-wheel consumer.
+Run tests and static checks locally before release. Generated-model, lint, formatting, and type checks use Python 3.15.
+Release CI uses Python 3.15 for reproducible builds, artifact audits, and PyPI upload; it does not rerun tests.
 
 ```bash
 uv sync --frozen
@@ -35,6 +35,16 @@ Contract or generator changes regenerate private models with `uv run python scri
 `pyproject.toml` declares dependency minimums; `uv.lock` fixes the development and release environment.
 The exact Node.js wheel pin preserves compatibility with glibc 2.17 on the development host.
 
+Before release, also test all supported Python versions locally, with Provider connection variables unset:
+
+```bash
+test_status=0
+for python_version in 3.12 3.13 3.14 3.15; do
+    uv run --frozen --exact --python "$python_version" pytest -rs || test_status=1
+done
+test "$test_status" -eq 0
+```
+
 ## Opt-in Provider consumer smoke
 
 The smoke checks authentication, complete Session persistence and restoration, refresh with identity preservation,
@@ -57,19 +67,25 @@ for target authorization and keep credentials out of Git.
 
 ## Reproducible release build
 
-Pushing a `v{version}` release tag to `origin` automatically triggers [CI](../.workflow/release.yml): checks, reproducible
-builds, artifact audits, installed-wheel validation, and PyPI publishing. Preparation follows the
+After local validation, pushing a `v{version}` release tag to `origin` automatically triggers
+[CI](../.workflow/release.yml): reproducible builds, artifact audits, and PyPI publishing.
+The workflow accepts only the tag matching the declared version. Preparation follows the
 [release workflow](agent-workflows.md#release).
-A manual run of `main` performs validation without publishing.
 
-Local builds are only needed for packaging changes or artifact diagnostics. To reproduce CI artifacts, use the release
-tag's checkout and committer timestamp, the locked environment, and a temporary output directory:
+For local installed-wheel validation or packaging diagnostics, use the intended release checkout and committer
+timestamp, the locked environment, and a temporary output directory:
 
 ```bash
 export SOURCE_DATE_EPOCH="$(git show -s --format=%ct HEAD)"
 sdk_release_build_dir="$(mktemp -d)"
+trap 'rm -rf -- "$sdk_release_build_dir"' EXIT
 uv sync --frozen
-uv build --no-build-isolation --out-dir "$sdk_release_build_dir"
-uv run python scripts/check_release.py "$sdk_release_build_dir"/*.whl "$sdk_release_build_dir"/*.tar.gz
-(cd "$sdk_release_build_dir" && sha256sum *.whl *.tar.gz > SHA256SUMS)
+uv build --no-build-isolation --out-dir "$sdk_release_build_dir/dist"
+uv run python scripts/check_release.py "$sdk_release_build_dir"/dist/*.whl "$sdk_release_build_dir"/dist/*.tar.gz
+uv venv --python 3.15 "$sdk_release_build_dir/consumer"
+uv pip install --python "$sdk_release_build_dir/consumer/bin/python" \
+    "$sdk_release_build_dir"/dist/*.whl "basedpyright>=1.40.2" "nodejs-wheel-binaries==22.20.0"
+"$sdk_release_build_dir/consumer/bin/python" scripts/check_installed_package.py
+"$sdk_release_build_dir/consumer/bin/basedpyright" \
+    --pythonpath "$sdk_release_build_dir/consumer/bin/python" --project tests/typing/pyproject.toml
 ```

{matelab_python_sdk-0.3.0a1 → matelab_python_sdk-0.3.0a2}/docs/operation-coverage.yaml

@@ -3,7 +3,7 @@
 schema_version: 1
 contract:
   line: integration-v1
-  release: v2026.11.2
+  release: v2026.11.4
   operation_count: 71
 
 operations:

{matelab_python_sdk-0.3.0a1 → matelab_python_sdk-0.3.0a2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "matelab-python-sdk"
-version = "0.3.0a1"
+version = "0.3.0a2"
 description = "Reusable async Python client for the Matelab Integration Contract"
 requires-python = ">=3.12"
 keywords = ["matelab", "electronic-lab-notebook", "eln", "asyncio", "sdk"]

{matelab_python_sdk-0.3.0a1 → matelab_python_sdk-0.3.0a2}/src/matelab/_generated/models.py

@@ -11,7 +11,7 @@ from pydantic import ConfigDict, Field, RootModel, SecretStr, StrictBool, Strict
 
 from matelab._wire_validation import WireModel
 
-OPENAPI_INFO_VERSION = "2026.11.2"
+OPENAPI_INFO_VERSION = "2026.11.4"
 
 
 class ResponseEnvelope(WireModel):

{matelab_python_sdk-0.3.0a1 → matelab_python_sdk-0.3.0a2}/tests/test_release.py

@@ -129,9 +129,9 @@ def test_release_dependencies_publish_minimum_versions() -> None:
     assert build == [dev["hatchling"]]
     assert project["license"] == "Apache-2.0"
     assert project["license-files"] == ["LICENSE", "NOTICE"]
-    workflow = (_ROOT / ".workflow" / "release.yml").read_text()
-    assert str(dev["basedpyright"]) in workflow
-    assert str(dev["nodejs-wheel-binaries"]) in workflow
+    development = (_ROOT / "docs" / "development.md").read_text()
+    assert str(dev["basedpyright"]) in development
+    assert str(dev["nodejs-wheel-binaries"]) in development
 
 
 def test_built_metadata_contains_public_dependency_and_python_contract(built_wheel: Path) -> None:

{matelab_python_sdk-0.3.0a1 → matelab_python_sdk-0.3.0a2}/uv.lock

@@ -412,7 +412,7 @@ wheels = [
 
 [[package]]
 name = "matelab-python-sdk"
-version = "0.3.0a1"
+version = "0.3.0a2"
 source = { editable = "." }
 dependencies = [
     { name = "httpx2" },