TEN-framework · dillonliang224 · Aug 20, 2026
@@ -2,6 +2,13 @@
 
 All notable changes to the iFLYTEK ASR Python Extension are documented here.
 
+## 0.2.0 - 2026-08-20
+
+- Standardize vendor and connection settings under `property.params` so TEN
+  graphs can configure iFLYTEK consistently with other ASR extensions.
+- Require all vendor and connection settings under `property.params`; only
+  `dump` and `dump_path` remain extension-level properties.
+
 ## 0.1.0 - 2026-08-04
 
 - Implement iFLYTEK WebSocket request and response mapping.

@@ -59,7 +59,7 @@ flowchart LR
 | Python | `>= 3.10`，当前验证版本为 `3.10.20` |
 | tman / TEN Framework | 当前验证版本为 `0.11.71` |
 | `ten_runtime_python` | `0.11.71` |
-| `ten_ai_base` | `0.6` |
+| `ten_ai_base` | `0.7` |
 | `websockets` | `>=14.0`，当前验证版本为 `14.2` |
 | Pydantic | `>=2.13.4,<3.0`，当前验证版本为 `2.13.4` |
 | pytest | 用于离线测试 |
@@ -94,11 +94,13 @@ python -m pip install \
 tman run test -- -q
 ```
 
-当前离线基线为 `63 passed`。这些测试不访问真实讯飞服务，也不需要业务凭据。
+当前离线基线为 `88 passed`。这些测试不访问真实讯飞服务，也不需要业务凭据。
 
 ## 配置
 
-TEN 从 `property.json` 读取扩展属性。连接信息默认支持通过环境变量注入：
+TEN 从 `property.json` 读取扩展属性。0.2.0 起，供应商及连接参数统一放在
+`params` 对象中，不再接受 0.1.0 的顶层参数。`dump` 和 `dump_path` 保持为
+扩展顶层属性。连接信息默认支持通过环境变量注入：
 
 ```bash
 export IFLYTEK_ASR_URL="wss://asr.example.com/tuling/ast/v3"
@@ -133,32 +135,35 @@ export IFLYTEK_BIZ_ID="business-id"
 | `dump` | 否 | `false` | 是否把成功发送的 PCM 音频写入本地文件 |
 | `dump_path` | 否 | 系统临时目录 | Dump 目录或以 `.pcm` 结尾的文件路径 |
 
+除 `dump` 和 `dump_path` 外，表中配置项均位于 `params` 对象内。
 `language` 会在 `engine` 未显式设置时自动写入
 `wrec_param_language_name`。未知配置项会被忽略，以兼容 TEN 图中的共享属性。
 
 ### 配置示例
 
 ```json
 {
-  "url": "${env:IFLYTEK_ASR_URL|wss://asr.example.com/tuling/ast/v3}",
-  "app_id": "${env:IFLYTEK_APP_ID|}",
-  "biz_id": "${env:IFLYTEK_BIZ_ID|}",
-  "trace_id_prefix": "ten",
-  "sample_rate": 16000,
-  "language": "zh|en",
-  "engine": {
-    "wfep_param_nOnlineSpkdia_on": "2"
+  "params": {
+    "url": "${env:IFLYTEK_ASR_URL|wss://asr.example.com/tuling/ast/v3}",
+    "app_id": "${env:IFLYTEK_APP_ID|}",
+    "biz_id": "${env:IFLYTEK_BIZ_ID|}",
+    "trace_id_prefix": "ten",
+    "sample_rate": 16000,
+    "language": "zh|en",
+    "engine": {
+      "wfep_param_nOnlineSpkdia_on": "2"
+    },
+    "res_id_list": [],
+    "hotwords": "zh-科大讯飞;en-Agora",
+    "hotword_weight": 4.0,
+    "voiceprints": {},
+    "connect_timeout": 10.0,
+    "finalize_timeout": 5.0,
+    "reconnect_delay": 0.5,
+    "reconnect_max_delay": 8.0,
+    "reconnect_max_attempts": 5,
+    "buffer_max_bytes": 10485760
   },
-  "res_id_list": [],
-  "hotwords": "zh-科大讯飞;en-Agora",
-  "hotword_weight": 4.0,
-  "voiceprints": {},
-  "connect_timeout": 10.0,
-  "finalize_timeout": 5.0,
-  "reconnect_delay": 0.5,
-  "reconnect_max_delay": 8.0,
-  "reconnect_max_attempts": 5,
-  "buffer_max_bytes": 10485760,
   "dump": false,
   "dump_path": "/tmp"
 }

@@ -27,6 +27,27 @@
 }
 MAX_ERROR_MESSAGE_LENGTH = 2048
 REDACTED_VALUE = "<redacted>"
+PARAM_FIELDS = frozenset(
+    {
+        "url",
+        "app_id",
+        "biz_id",
+        "trace_id_prefix",
+        "sample_rate",
+        "language",
+        "engine",
+        "res_id_list",
+        "hotwords",
+        "hotword_weight",
+        "voiceprints",
+        "connect_timeout",
+        "finalize_timeout",
+        "reconnect_delay",
+        "reconnect_max_delay",
+        "reconnect_max_attempts",
+        "buffer_max_bytes",
+    }
+)
 
 
 class IFlytekAsrConfig(BaseModel):
@@ -52,9 +73,34 @@ class IFlytekAsrConfig(BaseModel):
     reconnect_max_delay: float = Field(default=8.0, ge=0)
     reconnect_max_attempts: int = Field(default=5, ge=1)
     buffer_max_bytes: int = Field(default=10 * 1024 * 1024, gt=0)
+    params: dict[str, Any] = Field(default_factory=dict)
 
     model_config = ConfigDict(extra="ignore")
 
+    @model_validator(mode="before")
+    @classmethod
+    def extract_params(cls, data: Any) -> Any:
+        if isinstance(data, dict):
+            top_level_params = PARAM_FIELDS.intersection(data)
+            if top_level_params:
+                field_names = ", ".join(sorted(top_level_params))
+                raise ValueError(
+                    f"iFLYTEK parameters must be nested under params: "
+                    f"{field_names}"
+                )
+            nested_params = data.get("params")
+            if isinstance(nested_params, dict):
+                merged = dict(data)
+                merged.update(
+                    {
+                        key: value
+                        for key, value in nested_params.items()
+                        if key in PARAM_FIELDS
+                    }
+                )
+                return merged
+        return data
+
     @field_validator("url")
     @classmethod
     def validate_websocket_url(cls, value: str) -> str:

@@ -1,6 +1,6 @@
 # iFLYTEK ASR Production Readiness
 
-This checklist applies to `iflytek_asr_python` version `0.1.0`. It complements
+This checklist applies to `iflytek_asr_python` version `0.2.0`. It complements
 the automated tests; deployment-specific networking, credentials, privacy,
 capacity, and monitoring remain operator responsibilities.
 
@@ -22,6 +22,8 @@ capacity, and monitoring remain operator responsibilities.
   minutes without a maximum-duration error.
 - [x] Black formatting, Python compilation, TMan metadata validation, static
   analysis, dependency audit, and package-content checks are release gates.
+- [x] Before opening or updating a PR, validate its title with
+  `echo "${PR_TITLE}" | npx --yes commitlint --default-config`.
 - [x] Every runnable Guarder case runs across the default and dedicated
   long-duration invocations; skips and deselections are reported and never
   counted as passes.

@@ -14,7 +14,7 @@ This extension connects TEN Framework to the iFLYTEK realtime transcription serv
 
 ## Configuration
 
-`url` and `biz_id` are required for service integration. The default property file reads them from `IFLYTEK_ASR_URL` and `IFLYTEK_BIZ_ID`. Optional fields include `app_id`, `sample_rate`, `language`, `engine`, `res_id_list`, `hotwords`, `hotword_weight`, and `voiceprints`.
+Starting with version 0.2.0, vendor and connection settings must be nested under the `params` property; the 0.1.0 top-level fields are no longer accepted. `dump` and `dump_path` remain top-level properties. `url` and `biz_id` are required for service integration. The default property file reads them from `IFLYTEK_ASR_URL` and `IFLYTEK_BIZ_ID`. Optional fields include `app_id`, `sample_rate`, `language`, `engine`, `res_id_list`, `hotwords`, `hotword_weight`, and `voiceprints`.
 
 Production controls include `finalize_timeout` (default `5` seconds), `reconnect_delay` (`0.5` seconds), `reconnect_max_delay` (`8` seconds), `reconnect_max_attempts` (`5`), and `buffer_max_bytes` (`10485760`). Set `dump` to `true` and `dump_path` to a directory or `.pcm` file to record successfully sent audio. Dump failures are non-fatal. Audio dumps may contain sensitive data and should be enabled only with appropriate retention and access controls.
 

@@ -13,6 +13,8 @@
 
 ## 設定
 
+バージョン 0.2.0 以降、ベンダーおよび接続設定は必ず `params` オブジェクトに格納します。0.1.0 のトップレベル項目は受け付けません。`dump` と `dump_path` はトップレベルのままです。
+
 接続には `url` と `biz_id` が必要です。既定では `IFLYTEK_ASR_URL` と `IFLYTEK_BIZ_ID` 環境変数を使用できます。入力は設定した `sample_rate` のモノラル 16-bit PCM としてください。複数言語は `zh|en` のように `|` で区切ります。
 
 運用向け設定は `finalize_timeout`、`reconnect_delay`、`reconnect_max_delay`、`reconnect_max_attempts`、`buffer_max_bytes`（既定 10 MB）です。`dump=true` の場合、`dump_path` で PCM のディレクトリまたはファイルを指定できます。初回接続と途中の再接続の失敗は NON_FATAL として有限回再試行し、再試行回数を超過すると FATAL として報告されます。

@@ -13,6 +13,8 @@
 
 ## 설정
 
+버전 0.2.0부터 공급자 및 연결 설정은 반드시 `params` 객체 안에 둡니다. 0.1.0의 최상위 필드는 허용하지 않습니다. `dump`와 `dump_path`는 최상위 속성으로 유지됩니다.
+
 서비스 연결에는 `url`과 `biz_id`가 필요합니다. 기본 속성은 `IFLYTEK_ASR_URL` 및 `IFLYTEK_BIZ_ID` 환경 변수를 사용할 수 있습니다. 입력은 설정된 `sample_rate`의 모노 16비트 PCM이어야 합니다. 여러 언어는 `zh|en`처럼 `|`로 구분합니다.
 
 운영 설정에는 `finalize_timeout`, `reconnect_delay`, `reconnect_max_delay`, `reconnect_max_attempts`, `buffer_max_bytes`(기본 10 MB)가 있습니다. `dump=true`로 설정하면 `dump_path`에서 PCM 디렉터리 또는 파일을 지정할 수 있습니다. 최초 연결 및 중간 재연결 실패는 NON_FATAL로 보고하고 제한된 재시도를 계속하며, 재시도를 모두 소진하면 FATAL로 보고합니다.

@@ -16,6 +16,9 @@
 
 ## 配置
 
+从 0.2.0 开始，供应商和连接参数必须统一放在 `params` 对象中，不再接受 0.1.0
+的顶层字段。`dump` 与 `dump_path` 保持为扩展顶层属性。
+
 必填配置：
 
 - `url`：实时转写 WebSocket 地址，格式为 `ws(s)://host:port/tuling/ast/v3`
@@ -48,25 +51,27 @@
 
 ```json
 {
-  "url": "wss://asr.example.com/tuling/ast/v3",
-  "app_id": "app-1",
-  "biz_id": "tenant-1",
-  "sample_rate": 16000,
-  "language": "zh|en",
-  "engine": {
-    "wfep_param_nOnlineSpkdia_on": "2"
-  },
-  "res_id_list": ["tenant-2"],
-  "hotwords": "zh-科大讯飞;en-Agora",
-  "hotword_weight": 4.0,
-  "voiceprints": {
-    "10001": "Base64 encoded voiceprint"
+  "params": {
+    "url": "wss://asr.example.com/tuling/ast/v3",
+    "app_id": "app-1",
+    "biz_id": "tenant-1",
+    "sample_rate": 16000,
+    "language": "zh|en",
+    "engine": {
+      "wfep_param_nOnlineSpkdia_on": "2"
+    },
+    "res_id_list": ["tenant-2"],
+    "hotwords": "zh-科大讯飞;en-Agora",
+    "hotword_weight": 4.0,
+    "voiceprints": {
+      "10001": "Base64 encoded voiceprint"
+    },
+    "finalize_timeout": 5.0,
+    "reconnect_delay": 0.5,
+    "reconnect_max_delay": 8.0,
+    "reconnect_max_attempts": 5,
+    "buffer_max_bytes": 10485760
   },
-  "finalize_timeout": 5.0,
-  "reconnect_delay": 0.5,
-  "reconnect_max_delay": 8.0,
-  "reconnect_max_attempts": 5,
-  "buffer_max_bytes": 10485760,
   "dump": false,
   "dump_path": "/tmp"
 }

@@ -13,6 +13,9 @@
 
 ## 設定
 
+自 0.2.0 起，供應商與連線設定必須統一放在 `params` 物件中，不再接受 0.1.0
+的頂層欄位。`dump` 與 `dump_path` 維持為擴充頂層屬性。
+
 服務串接必須提供 `url` 與 `biz_id`，預設可由 `IFLYTEK_ASR_URL`、`IFLYTEK_BIZ_ID` 環境變數注入。輸入音訊必須是符合 `sample_rate` 的單聲道 16 位元 PCM。多語種以 `|` 分隔，例如 `zh|en`。
 
 生產控制包括 `finalize_timeout`、`reconnect_delay`、`reconnect_max_delay`、`reconnect_max_attempts` 與 `buffer_max_bytes`（預設 10 MB）。設定 `dump=true` 後可用 `dump_path` 指定 PCM 目錄或檔案。初次連線及中間重試失敗會上報 NON_FATAL 並繼續有限次重試；重試耗盡後上報 FATAL。