matelab-python-sdk 0.2.0a3__tar.gz → 0.2.0a5__tar.gz

{matelab_python_sdk-0.2.0a3 → matelab_python_sdk-0.2.0a5}/.github/workflows/release.yml

@@ -84,7 +84,7 @@ jobs:
           uv pip install \
             --python "${RUNNER_TEMP}/matelab-consumer/bin/python" \
             dist/release/*.whl \
-            "basedpyright<2,>=1.40.1" \
+            "basedpyright>=1.40.1" \
             "nodejs-wheel-binaries==22.20.0"
           "${RUNNER_TEMP}/matelab-consumer/bin/python" scripts/check_installed_package.py
           "${RUNNER_TEMP}/matelab-consumer/bin/basedpyright" \

{matelab_python_sdk-0.2.0a3 → matelab_python_sdk-0.2.0a5}/AGENTS.md

@@ -4,14 +4,16 @@
 
 ## 维护顺序
 
-1. **定界**：先读 `git status` 和适用权威；完成标准是任务范围、用户现有改动和所需外部权限均已识别。
+1. **定界**：先读 `git status` 和适用权威，确定任务范围、用户现有改动和所需权限。
 2. **查证**：涉及 SDK 行为或 Contract 时，沿 public intent → wire operation → Provider evidence 核对受影响
    operation 的 request、response、security、examples、成功码及 PVD/PCG，明确报告 Contract 缺口。文档、排版和
    工具配置修改只核对相关权威。
 3. **收敛**：只修改任务必需的层，检查 public、adapter、generated、tests、coverage 和 docs 中受影响的内容。
-4. **验证**：按变更类型选择 [delivery gate](docs/agent-workflows.md#delivery-gate)，先运行相关检查；代码变更先跑
-   聚焦测试，再跑完整门槛。完成标准是必需命令全部退出为零，skip 和 deselected 分别说明。
-5. **交付**：复核最终 diff、状态和验证证据；完成标准是结果、限制和未执行项都可由用户独立核对。
+4. **验证**：按变更类型执行 [delivery gate](docs/agent-workflows.md#delivery-gate)，复用仍覆盖当前变更的有效结果。
+5. **交付**：复核最终 diff 和状态，报告结果、验证证据、限制及未执行项。
+
+本地仅为打包配置、构建元数据、发布脚本变化或制品故障按需构建。正式可复现构建、制品审计和安装后消费由
+发布 CI 执行，本地无需重复构建或保留历史 `dist/` 产物。
 
 ## 分支指针
 
@@ -23,8 +25,6 @@
   [`docs/agent-workflows.md#contract-adoption`](docs/agent-workflows.md#contract-adoption)。
 - **Configuration and dependencies**：修改 `pyproject.toml`、依赖范围、lock 或对应 CI 配置时读
   [`docs/agent-workflows.md#configuration-and-dependencies`](docs/agent-workflows.md#configuration-and-dependencies)。
-- **Delivery gate**：交付前按变更类型执行
-  [`docs/agent-workflows.md#delivery-gate`](docs/agent-workflows.md#delivery-gate)。
 - **Provider validation**：任何实时 Provider smoke、读取或 mutation 前执行
   [`docs/agent-workflows.md#provider-validation`](docs/agent-workflows.md#provider-validation)。
 - **Release**：准备版本或发布制品时执行；普通 commit/push 只应用其中的授权与 diff 审查要求
@@ -34,16 +34,16 @@
 
 | 权威 | 负责内容 |
 | --- | --- |
-| `README.md` | 当前 public interface、集成语义、示例及人类流程 |
+| `README.md` | 项目介绍、安装及快速入门 |
+| `docs/api.md` | 当前 public interface、集成语义、完整示例和 Provider 限制 |
+| `docs/development.md` | 开发、验证、版本与构建流程 |
 | `CONTEXT.md` | public 类型和命名采用的领域词汇 |
-| `CHANGELOG.md` | SDK 版本变化与迁移影响；不定义当前接口 |
 | `docs/operation-coverage.yaml` | operation 状态、公开入口、稳定性和已知问题 |
 | `pyproject.toml` | SDK 版本、依赖范围、构建与工具配置；`uv.lock` 只锁定本仓库环境 |
 | Contract lock 与 snapshot | Contract pin 与 wire schema |
 | `src/matelab/__init__.py::__all__` | 公开导入边界 |
 
-机器权威变化时，同一变更同步受影响的当前态文档；历史只追加到 `CHANGELOG.md`。测试提供行为证据，不替代
-接口、coverage 或 Contract 权威。
+机器权威变化时，同一变更同步受影响的当前态文档。测试提供行为证据，不替代接口、coverage 或 Contract 权威。
 
 ## 范围与授权
 

{matelab_python_sdk-0.2.0a3 → matelab_python_sdk-0.2.0a5}/CONTEXT.md

@@ -63,9 +63,14 @@ _Avoid_: Record locator, public record ref, deleted record ref
 
 **Record locator**:
 A record ref paired with the owned or shared notebook in which it was observed. It is the complete source identity
-used by record reads and record-scoped operations.
+used by owned/shared record reads and record-scoped operations.
 _Avoid_: Record ref, notebook ID
 
+**Public record ref**:
+A public association's row ID, paired source notebook and record IDs, and nullable association UID metadata.
+The source ID pair locates its current body; it does not grant notebook-wide access.
+_Avoid_: Record locator, public notebook ID, association ID as record ID
+
 **Record version ref**:
 A historical version ID bound to its record locator. It identifies observed historical content, not a separate active
 record.

matelab_python_sdk-0.2.0a5/PKG-INFO

@@ -0,0 +1,69 @@
+Metadata-Version: 2.5
+Name: matelab-python-sdk
+Version: 0.2.0a5
+Summary: Reusable async Python client for the Matelab Integration Contract
+Author: CMPDC, Institute of Physics, Chinese Academy of Sciences
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: asyncio,electronic-lab-notebook,eln,matelab,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx2>=2.13.1
+Requires-Dist: jsonschema>=4.26.0
+Requires-Dist: pydantic>=2.13.5
+Requires-Dist: typing-extensions>=4.16.0
+Description-Content-Type: text/markdown
+
+# matelab-python-sdk
+
+Async Python client for the Matelab Integration Contract, with typed interfaces for authentication,
+notebooks, records, attachments, cloud files, templates, and literature. Requires Python 3.11 or newer.
+
+## Installation
+
+```bash
+uv add matelab-python-sdk
+```
+
+Or use `python -m pip install matelab-python-sdk`.
+
+## Quick start
+
+Replace the example credentials with your own:
+
+```python
+import asyncio
+
+from matelab import AsyncMatelab
+
+
+async def main() -> None:
+    async with AsyncMatelab() as client:
+        await client.authenticate("user@example.org", "password")
+        notebooks = await client.notebooks.list()
+        for notebook in notebooks.owned:
+            print(notebook.ref)
+
+
+asyncio.run(main())
+```
+
+`AsyncMatelab()` uses `https://matelab.iphy.ac.cn/api` by default. Pass another API root as its first argument.
+
+## Documentation
+
+- [API reference](https://github.com/tiannianzhu/matelab-python-sdk/blob/main/docs/api.md): Session persistence, errors, examples, and Provider limits.
+- [Operation coverage](https://github.com/tiannianzhu/matelab-python-sdk/blob/main/docs/operation-coverage.yaml): supported operations.
+- [Development and releases](https://github.com/tiannianzhu/matelab-python-sdk/blob/main/docs/development.md): checks, Provider smoke, versioning, and builds.

matelab_python_sdk-0.2.0a5/README.md

@@ -0,0 +1,41 @@
+# matelab-python-sdk
+
+Async Python client for the Matelab Integration Contract, with typed interfaces for authentication,
+notebooks, records, attachments, cloud files, templates, and literature. Requires Python 3.11 or newer.
+
+## Installation
+
+```bash
+uv add matelab-python-sdk
+```
+
+Or use `python -m pip install matelab-python-sdk`.
+
+## Quick start
+
+Replace the example credentials with your own:
+
+```python
+import asyncio
+
+from matelab import AsyncMatelab
+
+
+async def main() -> None:
+    async with AsyncMatelab() as client:
+        await client.authenticate("user@example.org", "password")
+        notebooks = await client.notebooks.list()
+        for notebook in notebooks.owned:
+            print(notebook.ref)
+
+
+asyncio.run(main())
+```
+
+`AsyncMatelab()` uses `https://matelab.iphy.ac.cn/api` by default. Pass another API root as its first argument.
+
+## Documentation
+
+- [API reference](https://github.com/tiannianzhu/matelab-python-sdk/blob/main/docs/api.md): Session persistence, errors, examples, and Provider limits.
+- [Operation coverage](https://github.com/tiannianzhu/matelab-python-sdk/blob/main/docs/operation-coverage.yaml): supported operations.
+- [Development and releases](https://github.com/tiannianzhu/matelab-python-sdk/blob/main/docs/development.md): checks, Provider smoke, versioning, and builds.

{matelab_python_sdk-0.2.0a3 → matelab_python_sdk-0.2.0a5}/contracts/matelab-integration-v1.lock.json

@@ -2,12 +2,12 @@
   "schema_version": 1,
   "contract_line": "integration-v1",
   "release": {
-    "tag": "v2026.10.1",
-    "commit": "9941e2d623a1c2633adb459b823d78d4e62d3802"
+    "tag": "v2026.10.2",
+    "commit": "1183d6833d88a6904598357321ef2d30cf944339"
   },
   "openapi": {
     "source_path": "openapi/matelab-integration-v1.openapi.yaml",
     "snapshot": "matelab-integration-v1.openapi.yaml",
-    "sha256": "a07997128c1df17a03724c5af8e11b45a34166f9d6e15558e66e0a301f2e0813"
+    "sha256": "4806fc2e4b4cb4cf94464be6f1b5f574f5a44745bf7cbc03d8644a13e57f8ec9"
   }
 }

{matelab_python_sdk-0.2.0a3 → matelab_python_sdk-0.2.0a5}/contracts/matelab-integration-v1.openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: Matelab Integration Contract
-  version: "2026.10.1"
+  version: "2026.10.2"
   description: |
     Current PHP wire contract for generating SDKs against the selected
     `matelab-server` Provider version.
@@ -26,6 +26,7 @@ info:
       - controller/Eln.php
       - controller/Eln_api.php
       - controller/Eln_items.php
+      - controller/Eln_public.php
       - controller/Eln_template.php
       - controller/Eln_url.php
       - controller/Files.php
@@ -36,6 +37,7 @@ info:
       - model/FileQuoteModel.php
       - model/FilesModel.php
       - traits/ElnTrait.php
+      - traits/ElnPublicTrait.php
       - traits/RecommendTrait.php
       - service/ElnApiImport.php
       - service/ElnApiUpdate.php
@@ -53,7 +55,7 @@ info:
       - sql/recommend.sql
   x-provider-audit:
     currentCommit: 3f39d47b7ad43bed618b029a7d9cc51fab852eb6
-    previousReleaseEvidenceCommit: acb0e12f2d62a8959ab9e9bddf38e34a67c19b48
+    previousReleaseEvidenceCommit: 3f39d47b7ad43bed618b029a7d9cc51fab852eb6
     lastProviderVerifiedCommit: 3f39d47b7ad43bed618b029a7d9cc51fab852eb6
     contractStatus: current-provider-aligned
     # Summary of changes adopted by current Supported Routes since the last
@@ -62,36 +64,8 @@ info:
     # updates against that fixed release baseline; use [] if no relevant changes.
     # Entries are not per-change verification results or a cumulative history.
     incorporatedChanges:
-      - {operationId: readApplicationBootstrap, change: array-valued-query-token-rejected-as-missing-authentication}
-      - {operationId: updateRecordData, change: collaboration-source-restricted-to-same-notebook-record-web-peer}
-      - {operationId: readRecord, change: encrypted-modules-and-unresolved-user-fields-modeled}
-      - {operationId: listRecordComments, change: unresolved-author-descriptors-modeled}
-      - {operationId: listRecordRelations, change: unresolved-comment-author-descriptors-modeled}
-      - {operationId: updateRecordData, change: staged-files-folder-append-wired-into-request-and-base64-excluded}
-      - {operationId: importRecordDataset, change: unreachable-base64-file-input-excluded}
-      - {operationId: searchRecordData, change: fixed-result-field-aliases-reserved-and-extraction-path-constrained}
-      - {operationId: saveNotebookMetadata, change: decoded-list-display-requests-reject-null-uid-and-invalid-path}
-      - {operationId: updateRecordData, change: quote-extraction-path-constrained-and-collaboration-code-0-documented}
-      - {operationId: listNotebooks, change: stored-types-return-non-null-decoded-json}
-      - {operationId: extractLiteratureMetadata, change: nested-errors-and-opaque-array-results-modeled}
-      - {operationId: listCloudDriveFiles, change: unreachable-null-timestamp-success-removed}
-      - {operationId: downloadRecordAttachment, change: zero-start-open-range-4097-byte-cap-documented}
-      - {operationId: downloadRecordCommentAttachment, change: zero-start-open-range-4097-byte-cap-documented}
-      - {operationId: downloadLiteraturePdf, change: zero-start-open-range-4097-byte-cap-documented}
-      - {operationId: downloadCloudDriveFile, change: zero-start-open-range-4097-byte-cap-documented}
-      - {operationId: listCurrentUserElnGroups, change: dangling-group-id-null-and-first-group-error-modeled}
-      - {operationId: downloadRecordCommentAttachment, change: zero-byte-attachment-download-supported}
-      - {operationId: listNotebookRecords, change: local-data-server-success-code-zero-internal-forwarding-code-excluded}
-      - {operationId: exportRecords, change: local-data-server-success-code-zero-internal-forwarding-code-excluded}
-      - {operationId: searchRecordData, change: local-data-server-success-code-zero-internal-forwarding-code-excluded}
-      - {operationId: listDeletedRecordPage, change: local-data-server-success-code-zero-internal-forwarding-code-excluded}
-      - {operationId: copyRecord, change: local-data-server-success-code-zero-internal-forwarding-code-excluded}
-      - {operationId: addRecordRelation, change: local-data-server-success-code-zero-internal-forwarding-code-excluded}
-      - {operationId: deleteRecordRelation, change: local-data-server-success-code-zero-internal-forwarding-code-excluded}
-      - {operationId: saveRecordComment, change: local-data-server-success-code-zero-internal-forwarding-code-excluded}
-      - {operationId: deleteRecordComment, change: local-data-server-success-code-zero-internal-forwarding-code-excluded}
-      - {operationId: downloadRecordAttachment, change: remote-data-server-download-excluded-pending-proxy-verification}
-      - {operationId: downloadRecordCommentAttachment, change: remote-data-server-download-excluded-pending-proxy-verification}
+      - {operationId: readRecord, change: public-only-body-access-and-source-record-identity-documented}
+      - {operationId: listPublicNotebookRecords, change: source-record-identifiers-distinguished-from-public-association-id}
   x-consumer-evidence:
     - repository: /home/tnzhu/projects/matelab-mcp
       commit: 94a129b2df0ef0fbcf179c10550fb7c9a5dd2e6f
@@ -2054,6 +2028,17 @@ paths:
       operationId: listPublicNotebookRecords
       tags: [Records]
       summary: List records in a visible public notebook
+      description: |
+        Authentication is required even for a globally visible public directory.
+        `eln` is the public directory's name. Visibility comes from a global
+        directory (`eln_public.userid=0`) or the caller's directory membership;
+        owning or sharing the source notebook is not required.
+        To read an item's current body, call `readRecord` with query
+        `eln=items[n].eln_id&id=items[n].item_id&version=0`. The directory's own
+        id and each returned association `id` are different identities and must
+        not be substituted. `uid` is nullable association metadata, not a body
+        selector. An association can survive a missing source notebook or record;
+        listing it does not guarantee that its body can still be read.
       security: [{bearerAuth: []}]
       requestBody:
         required: true
@@ -2092,6 +2077,8 @@ paths:
                       - {id: 52, item_id: 9002, eln_id: 12, uid: null, title: null, comm: null, locked: false, eln_name: null, userid: null, username: null, email: null, owner: false}
                 error:
                   value: {code: 2, msg: Public notebook not found, errcode: 2, errmsg: Public notebook not found}
+                authenticationError:
+                  value: {code: 1, msg: Authentication required, errcode: 1, errmsg: Authentication required}
   /eln_items/items:
     get:
       operationId: listNotebookRecordPage
@@ -2676,19 +2663,37 @@ paths:
         operation uses query parameters. Reading records writes an audit-log entry;
         that incidental access logging does not turn the resource read into a
         mutation operation.
+        Public-record bodies use this same operation and `ItemViewResponse`.
+        After `listPublicNotebookRecords`, pass that item's `eln_id` as `eln` and
+        `item_id` as `id`; keep them paired and use `version=0` for current content.
+        Do not substitute the public directory id, the public association's `id`,
+        or its nullable `uid`.
+        Authentication is still required. For a caller with no source-notebook
+        owner/share grant, an exact `(eln_id, item_id)` association in a global
+        public directory or one they belong to grants record-level read access.
+        This does not grant ownership or access to other records in that notebook.
+        Global public access is read-only; a member directory can separately
+        grant editing through the association's `editable` setting.
+        `modules` contains the canonical body or the existing encrypted descriptor;
+        this endpoint does not decrypt it. The required `uid` field can be null
+        for historical content and is not needed to construct the body request.
+        Missing/invalid authentication returns business code 1; denied access or
+        an invalid current-record identity returns code 2, both over HTTP 200.
+        Historical reads must use a version from this record's own `modify_log`;
+        the Provider does not enforce historical-version ownership (PVD-005).
       security:
         - bearerAuth: []
       parameters:
         - name: eln
           in: query
           required: true
-          description: Notebook database identifier.
+          description: Source notebook database identifier; use PublicRecordItem.eln_id for a public record, not the public directory id.
           schema: {type: integer, minimum: 1}
           example: 12
         - name: id
           in: query
           required: true
-          description: Record database identifier.
+          description: Source record database identifier; use PublicRecordItem.item_id for a public record, not its association id or UID.
           schema: {type: integer, minimum: 1}
           example: 9001
         - name: version
@@ -2766,6 +2771,38 @@ paths:
                     template_show: ""
                     template_text: Calibration Template
                     template_intro: ""
+                public:
+                  summary: Current body for a public-only reader without source-notebook sharing
+                  value:
+                    code: 0
+                    msg: ""
+                    errcode: 0
+                    errmsg: ""
+                    title: Calibration Run
+                    keywords: [calibration]
+                    modules:
+                      - {type: richtext, name: Notes, uid: module-example, data: Sanitized content}
+                    template_id: 8
+                    datetime_modify: 1767946200000
+                    username: Example User
+                    modify_log: []
+                    uid: REC-EXAMPLE-001
+                    current_version: 0
+                    item_id: 9001
+                    datetime_locked: 0
+                    locked: false
+                    signs: []
+                    signed: false
+                    owner: false
+                    eln_text: Example Notebook
+                    eln_server: localhost
+                    eln_id: 12
+                    editable: false
+                    keyword_eln: [calibration]
+                    pdf_enable: true
+                    template_show: ""
+                    template_text: Calibration Template
+                    template_intro: ""
                 nullable:
                   summary: Historical record with nullable UID, user, template, and keywords
                   value:
@@ -2902,6 +2939,11 @@ paths:
                     msg: No operation permission
                     errcode: 2
                     errmsg: No operation permission
+                authenticationError:
+                  value: {code: 1, msg: Authentication required, errcode: 1, errmsg: Authentication required}
+                identityError:
+                  summary: Source notebook and record identifiers do not identify the same current record
+                  value: {code: 2, msg: Illegal operation, errcode: 2, errmsg: Illegal operation}
   /eln_url/eln:
     get:
       operationId: downloadRecordAttachment
@@ -5677,7 +5719,10 @@ components:
       type: object
       required: [eln]
       properties:
-        eln: {type: string, minLength: 1}
+        eln:
+          type: string
+          minLength: 1
+          description: Public directory name, not the source notebook name or numeric id.
       additionalProperties: false
     CreateRecordRequest:
       type: object
@@ -6214,10 +6259,21 @@ components:
       type: object
       required: [id, item_id, eln_id, uid, title, comm, locked, eln_name, userid, username, email, owner]
       properties:
-        id: {type: integer, minimum: 1}
-        item_id: {type: integer, minimum: 1}
-        eln_id: {type: integer, minimum: 1}
-        uid: {type: [string, "null"]}
+        id:
+          type: integer
+          minimum: 1
+          description: Public association row identifier; not the record id accepted by readRecord.
+        item_id:
+          type: integer
+          minimum: 1
+          description: Source record identifier; pass as readRecord query id together with this row's eln_id.
+        eln_id:
+          type: integer
+          minimum: 1
+          description: Source notebook identifier; pass as readRecord query eln, not the public directory id.
+        uid:
+          type: [string, "null"]
+          description: Nullable UID copied into the association; not required for the numeric readRecord selector.
         title: {type: [string, "null"]}
         comm: {type: [string, "null"]}
         locked: {type: boolean}

matelab_python_sdk-0.2.0a5/docs/agent-workflows.md

@@ -0,0 +1,100 @@
+# Agent Maintenance Workflows
+
+本文件只在对应分支触发时加载。机器值始终从仓库读取；这里记录顺序、授权边界和完成标准。
+
+## Contract adoption
+
+1. 读取 Contract lock 和远端 release refs。只选择新的 annotated tag；移动分支和改写后的旧
+   snapshot 不能成为 SDK pin。记录 tag object、peeled commit、OpenAPI path 与 SHA-256。完成标准：四者固定且
+   互相一致。
+2. 比较当前 snapshot 与 release commit。逐项核对 operation request、response、security、examples、成功码、
+   Provider evidence 及 PVD/PCG。完成标准：每个 schema/operation 差异都分类为 generated-only、adapter、public
+   interface、test、coverage 或 docs 影响。
+3. request/response 均由生成 wire model 校验，adapter 只映射 public Python 名称与 wire 字段。required nullable
+   使用无默认值的 `T | None`；request 拒绝未知字段，response 接受新增字段。若专用 schema、顶层 request 或
+   Provider evidence 相互矛盾，保留当前安全边界并报告缺口。
+4. 从 release commit 复制 OpenAPI snapshot；同一变更更新 lock 的 tag、commit、snapshot path 和 SHA-256，运行
+   生成脚本并审查完整 generated diff。`_generated` 只由生成脚本修改；projection 只补偿生成器表达能力并保留
+   inherited required、`if/then`、`oneOf`、`anyOf` 和 `not`。完成标准：snapshot hash 与 lock 相等，生成差异
+   全部可由 OpenAPI 差异解释，`--check` 确定、非写入且能发现 stale output。
+5. 同步 runtime、测试、operation coverage、README、`docs/api.md`、`docs/development.md`、`pyproject.toml` 与 `uv.lock`
+   中受影响的当前态。
+   完成标准：每个 Contract 差异都有实现或明确 containment，当前文档与采用后的 Contract 一致。
+6. 执行 [delivery gate](#delivery-gate)。
+
+## Configuration and dependencies
+
+配置值以 `pyproject.toml` 为准，`uv.lock` 固定本仓库的解析环境，不反向定义发布依赖范围。
+
+- `[project]` 字段依次为 `name`、`version`、`description`、`requires-python`、`keywords`、`authors`、
+  `dependencies`，其他字段放在其后。
+- `[tool.basedpyright]` 字段依次为 `pythonVersion`、`typeCheckingMode`、`include`、`exclude`、
+  `reportUnannotatedClassAttribute`、`reportIncompatibleUnannotatedOverride`，其他设置放在其后。沿用 SDK 的目标
+  Python 版本与检查路径，不照搬其他项目的值。
+- runtime、build 和 dev 依赖仅声明已验证的 `>=` 下限；`nodejs-wheel-binaries` 保留系统所需的精确版本。
+  更新声明时同步 lock 和安装后消费检查使用的 CI requirement。
+- 构建后端依赖和 wheel package 显式配置；metadata 与制品检查从这些声明推导预期值。
+
+完成标准：配置可解析、声明与 lock 一致、受影响 CI 使用同一约束；字段重排不改变配置含义。
+
+## Delivery gate
+
+按本次变更选择验证范围：
+
+- 纯文档修改检查相关事实、本地路径和 Markdown 引用；示例或接口说明变化要对照当前 public interface。
+- 字段重排或显式写出既有默认值，检查语法与有效配置一致性。工具配置的有效设置变化运行对应工具。
+- SDK 代码、测试行为、Contract、依赖范围或影响制品的构建元数据变化，先跑聚焦测试，再完成下列完整门槛。
+
+### SDK test scope
+
+SDK 测试覆盖 public interface 到 wire adapter 的映射、认证与 Session、错误与重试、stream/上传生命周期及
+分发制品；Provider 的逐路由原始 HTTP conformance 由 `matelab-spec` 负责。
+
+新增或修改 operation 覆盖 method/path/encoding、认证、成功映射及适用的空结果、
+required nullable 和 additive response fields；operation coverage 与 pinned OpenAPI exact match，implemented
+operation 同时具备 public interface、wire adapter 和测试。删除或收紧 public interface 时同步移除过时测试，
+不保留无承诺的墓碑 alias。生成测试覆盖 metadata/checksum、schema、required/nullable、extra policy、确定性和
+stale detection。
+
+优先使用 pinned sanitized examples 或小型受控 fixture 验证稳定行为。operation 数量从 pinned Contract 推导，
+不固定当前数量；当前服务地址和依赖版本值不作为回归断言，除非它们本身就是明确的稳定契约。
+配置值变化只验证语法、约束及相关行为，不另加冻结新值或重复实现逻辑的测试。
+
+Ruff/Basedpyright 诊断通过修复代码或精确 ignore 解决，不缩小检查范围；Basedpyright 目标为 0 errors / 0 warnings。
+
+### Full gate
+
+完整命令见 [开发文档](development.md#development)。离线验证不配置 Provider 连接变量；实时 smoke 按
+[Provider validation](#provider-validation) 执行。
+
+检查因权限失败或无进展时，先查看输出和自己启动的进程，区分普通失败与文件、socket、网络或子进程限制。
+有沙箱阻塞证据后停止自己启动的停滞测试，通过工具审批机制申请最小范围重试；保留配置，不改权限、凭证或测试
+行为来绕过限制。超时本身不是沙箱拒绝的证据；无法升级或被拒绝时报告阻塞。
+
+完成标准：必需检查退出为零，`git diff --check` 无错误；skip 报告测试名称和原因，deselected 说明筛选范围。
+
+## Provider validation
+
+1. 实时验证仅在任务需要且会话授权覆盖目标及副作用时执行；连接设置和 smoke 命令见
+   [开发文档](development.md#opt-in-provider-consumer-smoke)。
+2. 执行前确认目标是隔离服务、`.env.test` 处于 Git ignore、命令显式加载该文件，并列出 authentication、refresh、
+   mutation 或带写痕迹读取的副作用。
+3. mutation 场景在写前记录 fixture，在写后回读，并尽力清理。完成标准：目标、Provider commit、命令、通过数、
+   skip/failure 和清理结果均可追溯；凭证及敏感 payload 未进入输出或提交。
+
+## Release
+
+普通 commit/push 只处理已授权的 diff，不自动改版本、建 tag 或发布。发布准备完成但缺少外部操作授权时，
+先交付可审查结果，再请求执行授权。以下步骤适用于实际发布：
+
+1. 按 [版本规则](development.md#versioning) 选择 SDK 版本，读取 `[project].version`，确认待发布版本未发布
+   且 Contract pin 完整。公开接口删除、重命名、类型收紧或不兼容行为变化按 breaking change 处理。
+   完成标准：版本、当前文档和 tag 名 `v{version}` 一致。
+2. 提交前同步受影响的当前文档，完成 [delivery gate](#delivery-gate)。构建元数据或发布流程变化时，核对
+   metadata 版本与固定的 PyPI 发布 Action 是否兼容；需要本地制品证据时使用
+   [手工构建命令](development.md#reproducible-release-build)。创建已审查、已授权的 release commit。
+3. 创建指向 release commit 的 annotated `v{version}` tag。先推送 `origin` 的 main/tag，再推送 GitHub mirror 的
+   main/tag；只有与项目版本完全匹配的 tag 触发 Trusted Publishing workflow，第三方 Action 固定 immutable
+   commit SHA。
+4. 跟踪 [发布 CI](../.github/workflows/release.yml) 的测试、可复现构建、制品审计、安装后消费和 PyPI publish。
+   完成标准：两个远端 main/tag 对应 release commit，CI 全部通过，PyPI 对应版本可读取。