create-windy 0.3.2 → 0.3.5

package/template/apps/speech-server/src/southwind_speech_server/normalizer.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+
+class NormalizationError(Exception):
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+@dataclass(frozen=True)
+class NormalizedAudio:
+    path: Path
+    duration_ms: int
+
+
+class AudioNormalizer:
+    @property
+    def available(self) -> bool:
+        return bool(shutil.which("ffmpeg") and shutil.which("ffprobe"))
+
+    async def normalize(
+        self,
+        source: Path,
+        target: Path,
+        max_duration_seconds: int,
+        timeout_seconds: int,
+    ) -> NormalizedAudio:
+        if not self.available:
+            raise NormalizationError("CAPABILITY_UNAVAILABLE", "音频归一化工具不可用")
+        duration_ms = await self._duration(source, timeout_seconds)
+        if duration_ms > max_duration_seconds * 1000:
+            raise NormalizationError("BUDGET_EXCEEDED", "音频时长超过 Operation 配额")
+        await run_process(
+            [
+                "ffmpeg",
+                "-nostdin",
+                "-v",
+                "error",
+                "-i",
+                str(source),
+                "-vn",
+                "-ac",
+                "1",
+                "-ar",
+                "16000",
+                "-c:a",
+                "pcm_s16le",
+                "-y",
+                str(target),
+            ],
+            timeout_seconds,
+        )
+        if not await asyncio.to_thread(valid_output, target):
+            raise NormalizationError("INVALID_INPUT", "音频归一化输出无效")
+        return NormalizedAudio(target, duration_ms)
+
+    async def _duration(self, source: Path, timeout_seconds: int) -> int:
+        output = await run_process(
+            [
+                "ffprobe",
+                "-v",
+                "error",
+                "-show_entries",
+                "format=duration",
+                "-of",
+                "json",
+                str(source),
+            ],
+            timeout_seconds,
+        )
+        try:
+            value = json.loads(output)
+            seconds = float(value["format"]["duration"])
+        except (KeyError, TypeError, ValueError, json.JSONDecodeError):
+            raise NormalizationError("INVALID_INPUT", "无法读取音频时长") from None
+        if seconds <= 0:
+            raise NormalizationError("INVALID_INPUT", "音频时长无效")
+        return round(seconds * 1000)
+
+
+async def run_process(arguments: list[str], timeout_seconds: int) -> str:
+    process = await asyncio.create_subprocess_exec(
+        *arguments,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+    try:
+        stdout, _stderr = await asyncio.wait_for(
+            process.communicate(),
+            timeout=max(1, timeout_seconds),
+        )
+    except TimeoutError:
+        process.kill()
+        await process.wait()
+        raise NormalizationError("BUDGET_EXCEEDED", "音频归一化超时") from None
+    if process.returncode != 0:
+        raise NormalizationError("INVALID_INPUT", "音频格式不受支持或内容损坏")
+    return stdout.decode("utf-8", errors="strict")
+
+
+def valid_output(target: Path) -> bool:
+    return target.is_file() and target.stat().st_size > 44

package/template/apps/speech-server/src/southwind_speech_server/output_validation.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+from .contracts import JsonValue
+from .errors import SafeSpeechError
+
+
+def canonicalize_output(
+    value: JsonValue,
+    duration_ms: int,
+    max_units: int,
+) -> JsonValue:
+    if not isinstance(value, dict):
+        raise invalid_output("Speech 输出缺少分段")
+    segments = value.get("segments")
+    if not isinstance(segments, list):
+        raise invalid_output("Speech 输出缺少分段")
+    if len(segments) > max_units:
+        raise invalid_output("Speech 输出分段超过上限")
+    canonical: list[JsonValue] = []
+    previous_end = 0
+    for index, segment in enumerate(segments, 1):
+        if not isinstance(segment, dict):
+            raise invalid_output("Speech 分段结构无效")
+        start = integer(segment.get("startMs"))
+        end = integer(segment.get("endMs"))
+        text = segment.get("text")
+        if (
+            start is None
+            or end is None
+            or start < previous_end
+            or end <= start
+            or end > duration_ms + 1000
+            or not isinstance(text, str)
+            or not text.strip()
+        ):
+            raise invalid_output("Speech 分段时间戳或文本无效")
+        item: dict[str, JsonValue] = {
+            "id": f"segment-{index:06d}",
+            "text": text,
+            "startMs": start,
+            "endMs": end,
+        }
+        confidence = probability(segment.get("confidence"))
+        if confidence is not None:
+            item["confidence"] = confidence
+        language = segment.get("language")
+        if language is not None:
+            if not isinstance(language, str) or not language.strip():
+                raise invalid_output("Speech 分段语言无效")
+            item["language"] = language
+        words = segment.get("words")
+        if words is not None:
+            item["words"] = canonicalize_words(words, start, end)
+        canonical.append(item)
+        previous_end = end
+    metadata = value.get("metadata", {})
+    if not isinstance(metadata, dict) or any(
+        not isinstance(item, str | int | float | bool) for item in metadata.values()
+    ):
+        raise invalid_output("Speech 元数据无效")
+    result: dict[str, JsonValue] = {
+        "durationMs": duration_ms,
+        "segments": canonical,
+        "metadata": {**metadata, "normalizedFormat": "pcm_s16le/16000/mono"},
+    }
+    language = value.get("language")
+    if language is not None:
+        if not isinstance(language, str) or not language.strip():
+            raise invalid_output("Speech 语言无效")
+        result["language"] = language
+    return result
+
+
+def canonicalize_words(
+    value: JsonValue, segment_start: int, segment_end: int
+) -> JsonValue:
+    if not isinstance(value, list):
+        raise invalid_output("Speech 词级时间戳无效")
+    result: list[JsonValue] = []
+    previous_end = segment_start
+    for word in value:
+        if not isinstance(word, dict):
+            raise invalid_output("Speech 词级时间戳无效")
+        start = integer(word.get("startMs"))
+        end = integer(word.get("endMs"))
+        text = word.get("text")
+        if (
+            start is None
+            or end is None
+            or start < previous_end
+            or end <= start
+            or end > segment_end
+            or not isinstance(text, str)
+            or not text
+        ):
+            raise invalid_output("Speech 词级时间戳无效")
+        item: dict[str, JsonValue] = {
+            "text": text,
+            "startMs": start,
+            "endMs": end,
+        }
+        confidence = probability(word.get("confidence"))
+        if confidence is not None:
+            item["confidence"] = confidence
+        result.append(item)
+        previous_end = end
+    return result
+
+
+def integer(value: object) -> int | None:
+    return value if isinstance(value, int) and not isinstance(value, bool) else None
+
+
+def probability(value: object) -> float | int | None:
+    if value is None:
+        return None
+    if (
+        not isinstance(value, int | float)
+        or isinstance(value, bool)
+        or value < 0
+        or value > 1
+    ):
+        raise invalid_output("Speech 置信度无效")
+    return value
+
+
+def invalid_output(message: str) -> SafeSpeechError:
+    return SafeSpeechError("OUTPUT_VALIDATION_FAILED", message, False)

package/template/apps/speech-server/src/southwind_speech_server/service.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import uuid
+
+from .adapter import SpeechAdapter
+from .contracts import ErrorResponse, StartSpeechRunRequest
+from .errors import SafeSpeechError
+from .store import RunRecord, SpeechRunStore
+
+
+class SpeechRunService:
+    def __init__(self, adapter: SpeechAdapter, store: SpeechRunStore) -> None:
+        self.adapter = adapter
+        self.store = store
+        self.tasks: dict[str, asyncio.Task[None]] = {}
+
+    async def start(
+        self, request: StartSpeechRunRequest, idempotency_key: str
+    ) -> RunRecord:
+        validate_options(request)
+        fingerprint = hashlib.sha256(
+            json.dumps(
+                {
+                    "operationKey": request.operation_key,
+                    "sourceSha256": request.source.sha256,
+                    "options": request.options,
+                    "capabilities": sorted(request.required_capabilities),
+                },
+                ensure_ascii=False,
+                separators=(",", ":"),
+                sort_keys=True,
+            ).encode()
+        ).hexdigest()
+        record, created = self.store.create(
+            f"speech_{uuid.uuid4().hex}",
+            request.operation_key,
+            idempotency_key,
+            fingerprint,
+        )
+        if created:
+            task = asyncio.create_task(self._execute(record.run_id, request))
+            self.tasks[record.run_id] = task
+            task.add_done_callback(lambda _task: self.tasks.pop(record.run_id, None))
+        return record
+
+    async def cancel(self, run_id: str) -> RunRecord:
+        record = self.require(run_id)
+        if not record.terminal:
+            self.store.append(run_id, "run.cancelled")
+            task = self.tasks.get(run_id)
+            if task:
+                task.cancel()
+        return self.require(run_id)
+
+    def require(self, run_id: str) -> RunRecord:
+        record = self.store.get(run_id)
+        if not record:
+            raise KeyError(run_id)
+        return record
+
+    async def _execute(self, run_id: str, request: StartSpeechRunRequest) -> None:
+        self.store.append(run_id, "run.started")
+        try:
+            async with asyncio.timeout(request.limits.max_duration_seconds):
+                output = await self.adapter.execute(request)
+                if self.require(run_id).status == "cancelled":
+                    return
+                segments = output.get("segments") if isinstance(output, dict) else None
+                if not isinstance(segments, list):
+                    raise SafeSpeechError(
+                        "OUTPUT_VALIDATION_FAILED",
+                        "Speech 输出缺少稳定分段",
+                        False,
+                    )
+                total = len(segments)
+                for index, segment in enumerate(segments, 1):
+                    if not isinstance(segment, dict):
+                        raise SafeSpeechError(
+                            "OUTPUT_VALIDATION_FAILED",
+                            "Speech 分段无效",
+                            False,
+                        )
+                    end_ms = segment.get("endMs")
+                    if not isinstance(end_ms, int):
+                        raise SafeSpeechError(
+                            "OUTPUT_VALIDATION_FAILED",
+                            "Speech 分段结束时间无效",
+                            False,
+                        )
+                    self.store.append(
+                        run_id,
+                        "speech.segment.completed",
+                        {
+                            "completedSegments": index,
+                            "totalSegments": total,
+                            "endMs": end_ms,
+                        },
+                    )
+                self.store.complete(run_id, output)
+        except TimeoutError:
+            self._fail(run_id, "RUN_TIMEOUT", "Speech 任务超时", True)
+        except SafeSpeechError as error:
+            self._fail(
+                run_id,
+                error.code,
+                error.safe_message,
+                error.retryable,
+            )
+        except Exception:
+            self._fail(run_id, "RUNTIME_UNAVAILABLE", "Speech Runtime 执行失败", True)
+
+    def _fail(self, run_id: str, code: str, message: str, retryable: bool) -> None:
+        self.store.append(
+            run_id,
+            "run.failed",
+            {
+                "error": ErrorResponse(
+                    code=code,
+                    message=message,
+                    request_id=f"speech_{uuid.uuid4().hex}",
+                    retryable=retryable,
+                ).model_dump(by_alias=True)
+            },
+        )
+
+
+def validate_options(request: StartSpeechRunRequest) -> None:
+    options = request.options
+    if not isinstance(options, dict):
+        raise SafeSpeechError("INVALID_INPUT", "Speech options 必须是对象", False)
+    allowed = {"language", "vad", "timestamps"}
+    if any(key not in allowed for key in options):
+        raise SafeSpeechError("INVALID_INPUT", "Speech options 含未知字段", False)
+    language = options.get("language")
+    if language is not None and (
+        not isinstance(language, str) or not language.strip() or len(language) > 35
+    ):
+        raise SafeSpeechError("INVALID_INPUT", "Speech language 无效", False)
+    timestamps = options.get("timestamps")
+    if timestamps is not None and timestamps not in {"segment", "word"}:
+        raise SafeSpeechError("INVALID_INPUT", "Speech timestamps 无效", False)
+    vad = options.get("vad")
+    if vad is None:
+        return
+    if not isinstance(vad, dict) or any(
+        key not in {"enabled", "minSpeechMs", "maxSilenceMs"} for key in vad
+    ):
+        raise SafeSpeechError("INVALID_INPUT", "Speech VAD 配置无效", False)
+    if not isinstance(vad.get("enabled"), bool):
+        raise SafeSpeechError("INVALID_INPUT", "Speech VAD enabled 无效", False)
+    for key in ("minSpeechMs", "maxSilenceMs"):
+        value = vad.get(key)
+        if value is not None and (
+            not isinstance(value, int)
+            or isinstance(value, bool)
+            or value < 0
+            or value > 60_000
+        ):
+            raise SafeSpeechError("INVALID_INPUT", f"Speech VAD {key} 无效", False)

package/template/apps/speech-server/src/southwind_speech_server/store.py

@@ -0,0 +1,209 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import sqlite3
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import cast
+
+from .contracts import JsonValue, RunStatus
+
+
+@dataclass(frozen=True)
+class RunRecord:
+    run_id: str
+    operation_key: str
+    idempotency_key: str
+    fingerprint: str
+    status: RunStatus
+    output: JsonValue = None
+
+    @property
+    def terminal(self) -> bool:
+        return self.status in {"completed", "failed", "cancelled"}
+
+
+@dataclass(frozen=True)
+class ResultArtifact:
+    body: bytes
+    media_type: str
+    byte_size: int
+    sha256: str
+
+
+class RunConflictError(Exception):
+    pass
+
+
+class SpeechRunStore:
+    def __init__(self, path: str) -> None:
+        Path(path).parent.mkdir(parents=True, exist_ok=True)
+        self.database = sqlite3.connect(path, check_same_thread=False)
+        self.database.row_factory = sqlite3.Row
+        self._initialize()
+        self._recover()
+
+    def create(
+        self,
+        run_id: str,
+        operation_key: str,
+        idempotency_key: str,
+        fingerprint: str,
+    ) -> tuple[RunRecord, bool]:
+        existing = self.database.execute(
+            "select run_id from speech_runs where idempotency_key = ?",
+            (idempotency_key,),
+        ).fetchone()
+        if existing:
+            record = self.get(str(existing["run_id"]))
+            if not record or record.fingerprint != fingerprint:
+                raise RunConflictError
+            return record, False
+        now = time.time()
+        self.database.execute(
+            """
+            insert into speech_runs values (?, ?, ?, ?, 'accepted', 'null', ?, ?)
+            """,
+            (run_id, operation_key, idempotency_key, fingerprint, now, now),
+        )
+        self.database.commit()
+        return self.get(run_id) or _missing(), True
+
+    def get(self, run_id: str) -> RunRecord | None:
+        row = self.database.execute(
+            "select * from speech_runs where run_id = ?", (run_id,)
+        ).fetchone()
+        if not row:
+            return None
+        return RunRecord(
+            run_id=str(row["run_id"]),
+            operation_key=str(row["operation_key"]),
+            idempotency_key=str(row["idempotency_key"]),
+            fingerprint=str(row["fingerprint"]),
+            status=cast(RunStatus, str(row["status"])),
+            output=json.loads(str(row["output_json"])),
+        )
+
+    def append(
+        self, run_id: str, event_type: str, fields: dict[str, object] | None = None
+    ) -> None:
+        record = self.get(run_id)
+        if not record or record.terminal:
+            return
+        sequence = (
+            int(
+                self.database.execute(
+                    "select count(*) from speech_events where run_id = ?", (run_id,)
+                ).fetchone()[0]
+            )
+            + 1
+        )
+        event = {
+            "type": event_type,
+            "runId": run_id,
+            "sequence": sequence,
+            **(fields or {}),
+        }
+        status = {
+            "run.started": "running",
+            "run.completed": "completed",
+            "run.failed": "failed",
+            "run.cancelled": "cancelled",
+        }.get(event_type, record.status)
+        self.database.execute(
+            "insert into speech_events values (?, ?, ?)",
+            (run_id, sequence, encode(event)),
+        )
+        self.database.execute(
+            "update speech_runs set status = ?, updated_at = ? where run_id = ?",
+            (status, time.time(), run_id),
+        )
+        self.database.commit()
+
+    def complete(self, run_id: str, output: JsonValue) -> None:
+        self.database.execute(
+            "update speech_runs set output_json = ? where run_id = ?",
+            (encode(output), run_id),
+        )
+        self.database.commit()
+        self.append(run_id, "run.completed")
+
+    def artifact(self, run_id: str) -> ResultArtifact:
+        record = self.get(run_id)
+        if not record or record.status != "completed":
+            raise KeyError(run_id)
+        body = encode(record.output).encode()
+        return ResultArtifact(
+            body=body,
+            media_type="application/json",
+            byte_size=len(body),
+            sha256=hashlib.sha256(body).hexdigest(),
+        )
+
+    def events_after(self, run_id: str, after: int) -> list[dict[str, object]]:
+        return [
+            json.loads(str(row["event_json"]))
+            for row in self.database.execute(
+                """
+                select event_json from speech_events
+                where run_id = ? and sequence > ? order by sequence
+                """,
+                (run_id, after),
+            )
+        ]
+
+    def _initialize(self) -> None:
+        self.database.executescript(
+            """
+            create table if not exists speech_runs (
+              run_id text primary key,
+              operation_key text not null,
+              idempotency_key text not null unique,
+              fingerprint text not null,
+              status text not null,
+              output_json text not null,
+              created_at real not null,
+              updated_at real not null
+            );
+            create table if not exists speech_events (
+              run_id text not null references speech_runs(run_id) on delete cascade,
+              sequence integer not null,
+              event_json text not null,
+              primary key (run_id, sequence)
+            );
+            """
+        )
+        self.database.commit()
+
+    def _recover(self) -> None:
+        rows = self.database.execute(
+            "select run_id from speech_runs where status in ('accepted', 'running')"
+        ).fetchall()
+        for row in rows:
+            self.append(
+                str(row["run_id"]),
+                "run.failed",
+                {
+                    "error": {
+                        "code": "RUNTIME_UNAVAILABLE",
+                        "message": "Speech Runtime 重启中断了任务，请使用新幂等键重试",
+                        "requestId": "speech-recovery",
+                        "retryable": True,
+                    }
+                },
+            )
+
+
+def encode(value: object) -> str:
+    return json.dumps(
+        value,
+        ensure_ascii=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    )
+
+
+def _missing() -> RunRecord:
+    raise RuntimeError("Speech Run 创建后不可读")

package/template/apps/speech-server/tests/__init__.py

@@ -0,0 +1 @@
+"""Speech Runtime tests."""

package/template/apps/speech-server/tests/test_config.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import pytest
+
+from southwind_speech_server.config import SpeechRuntimeConfig
+
+
+def test_internal_endpoints_reject_public_hosts() -> None:
+    with pytest.raises(ValueError, match="禁止使用公网地址"):
+        SpeechRuntimeConfig.from_environment(
+            {
+                "SPEECH_SERVER_INTERNAL_TOKEN": "internal-token",
+                "SPEECH_ADAPTER_URL": "https://8.8.8.8",
+            }
+        )
+
+
+def test_internal_endpoints_reject_public_dns_names() -> None:
+    with pytest.raises(ValueError, match="内部服务名"):
+        SpeechRuntimeConfig.from_environment(
+            {
+                "SPEECH_SERVER_INTERNAL_TOKEN": "internal-token",
+                "SPEECH_ADAPTER_URL": "https://public.example.com",
+            }
+        )
+
+
+def test_unconfigured_adapter_keeps_runtime_bootable() -> None:
+    config = SpeechRuntimeConfig.from_environment(
+        {"SPEECH_SERVER_INTERNAL_TOKEN": "internal-token"}
+    )
+    assert config.adapter_url is None
+    assert config.artifact_url == "http://server:9747/api/internal/ai/artifacts"