shuotype 0.5.2.0__py3-none-any.whl

shuotype/__init__.py

@@ -0,0 +1,3 @@
+"""ShuoType: voice input powered by Alibaba Cloud NLS."""
+
+__version__ = "0.1.0"

shuotype/__main__.py

@@ -0,0 +1,4 @@
+from shuotype_cli.cli import main
+
+if __name__ == "__main__":
+    main()

shuotype/asr.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import time
+
+import requests
+
+from .config import Config
+from .token import TokenManager
+
+ASR_URL = "https://nls-gateway-cn-shanghai.aliyuncs.com/stream/v1/asr"
+
+
+class AsrError(Exception):
+    """语音识别失败。"""
+
+
+class AsrAuthError(AsrError):
+    """NLS Token 被拒绝。"""
+
+
+class AsrTransientError(AsrError):
+    """可重试的识别错误。"""
+
+
+class AsrClient:
+    def __init__(
+        self,
+        config: Config,
+        tokens: TokenManager,
+        session=None,
+        timeout: float = 15,
+        sleep=time.sleep,
+    ):
+        self.config = config
+        self.tokens = tokens
+        self.session = session or requests.Session()
+        self.timeout = timeout
+        self.sleep = sleep
+
+    def recognize(self, pcm: bytes) -> str:
+        auth_retried = transient_retried = False
+        while True:
+            try:
+                return self._post(pcm, self.tokens.get())
+            except AsrAuthError:
+                if auth_retried:
+                    raise
+                auth_retried = True
+                self.tokens.invalidate()
+            except AsrTransientError:
+                if transient_retried:
+                    raise
+                transient_retried = True
+                self.sleep(0.5)
+
+    def _post(self, pcm: bytes, token: str) -> str:
+        params = {
+            "appkey": self.config.app_key,
+            "format": "pcm",
+            "sample_rate": "16000",
+            "enable_punctuation_prediction": "true",
+            "enable_inverse_text_normalization": "true",
+        }
+        try:
+            response = self.session.post(
+                ASR_URL,
+                params=params,
+                data=pcm,
+                headers={
+                    "X-NLS-Token": token,
+                    "Content-Type": "application/octet-stream",
+                },
+                timeout=self.timeout,
+            )
+        except requests.RequestException as exc:
+            raise AsrTransientError(
+                f"识别请求失败: {type(exc).__name__}"
+            ) from None
+        if response.status_code in (408, 429) or response.status_code >= 500:
+            raise AsrTransientError(
+                f"识别服务暂时不可用: HTTP {response.status_code}"
+            )
+        if response.status_code != 200:
+            body = (response.text or "")[:200]
+            detail = f"识别请求失败: HTTP {response.status_code}"
+            if body:
+                detail = f"{detail} {body}"
+            raise AsrError(detail)
+        try:
+            data = response.json()
+        except ValueError as exc:
+            raise AsrError("识别响应不是合法 JSON") from exc
+        if not isinstance(data, dict):
+            raise AsrError("识别响应格式异常")
+        status = data.get("status")
+        if status == 20000000:
+            return data.get("result") or ""
+        if status == 40000001:
+            raise AsrAuthError("NLS Token 无效或已过期")
+        message = data.get("message") or ""
+        detail = f"{status} {message}".strip()
+        if status == 40000005:
+            raise AsrTransientError(f"识别服务限流: {detail}")
+        if status == 50000000:
+            raise AsrTransientError(f"识别服务端错误: {detail}")
+        raise AsrError(f"识别失败: {detail}")

shuotype/assets/shuotype-icon-orange.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 160 160" width="512" height="512" role="img" aria-label="ShuoType app icon" xmlns:c2pa="http://c2pa.org/manifest">
+<rect width="160" height="160" rx="36" fill="#D97757"/>
+<rect x="29" y="68" width="10" height="24" rx="5" fill="#141413"/>
+<rect x="49" y="55" width="10" height="50" rx="5" fill="#141413"/>
+<rect x="101" y="55" width="10" height="50" rx="5" fill="#141413"/>
+<rect x="121" y="68" width="10" height="24" rx="5" fill="#141413"/>
+<rect x="76" y="40" width="8" height="80" rx="4" fill="#FAF9F5"/>
+<rect x="66" y="38" width="28" height="7" rx="3.5" fill="#FAF9F5"/>
+<rect x="66" y="115" width="28" height="7" rx="3.5" fill="#FAF9F5"/>
+<metadata><c2pa:manifest>AAAWgmp1bWIAAAAeanVtZGMycGEAEQAQgAAAqgA4m3EDYzJwYQAAABZcanVtYgAAAEdqdW1kYzJtYQARABCAAACqADibcQN1cm46YzJwYTo5N2VjOWExNi1lZmI1LTQwNmYtOWM0MS03NDJkM2U1Zjg0YzUAAAADl2p1bWIAAAApanVtZGMyYXMAEQAQgAAAqgA4m3EDYzJwYS5hc3NlcnRpb25zAAAAALxqdW1iAAAARGp1bWRjYm9yABEAEIAAAKoAOJtxE2MycGEuaW5ncmVkaWVudC52MwAAAAAYYzJzaHTRW7reDLLvuRNoYQQ2NakAAABwY2JvcqNpZGM6Zm9ybWF0bWltYWdlL3N2Zyt4bWxqaW5zdGFuY2VJRHgseG1wOmlpZDoyMjRlYzQxMy0wMmZjLTQyMDgtYjY4Mi03YzA4YjliZjA1MWNscmVsYXRpb25zaGlwaHBhcmVudE9mAAAB4mp1bWIAAABBanVtZGNib3IAEQAQgAAAqgA4m3ETYzJwYS5hY3Rpb25zLnYyAAAAABhjMnNouM3+FeIlml5wezVnY/RKPgAAAZljYm9yomdhY3Rpb25zgqJmYWN0aW9ua2MycGEub3BlbmVkanBhcmFtZXRlcnOha2luZ3JlZGllbnRzgaJjdXJseC1zZWxmI2p1bWJmPWMycGEuYXNzZXJ0aW9ucy9jMnBhLmluZ3JlZGllbnQudjNkaGFzaFggsf1dzntgxtLgtM6aKtUzpy0wE+XtrWgDMwiDiR5vC42kZmFjdGlvbngdY29tLmFudGhyb3BpYy5jbGF1ZGUucHJvdmlkZWRqcGFyYW1ldGVyc6F4H2NvbS5hbnRocm9waWMub3JpZ2luLWNvbmZpZGVuY2VndW5rbm93bmtkZXNjcmlwdGlvbnhmQ2xhdWRlIHByb3ZpZGVkIHRoaXMgZmlsZSBhdCB0aGUgcmVxdWVzdCBvZiBhIHVzZXIgYW5kIG1heSBoYXZlIGNyZWF0ZWQgb3IgbW9kaWZpZWQgdGhlIGZpbGUgY29udGVudHMubXNvZnR3YXJlQWdlbnShZG5hbWVmQ2xhdWRlcmFsbEFjdGlvbnNJbmNsdWRlZPUAAADIanVtYgAAAEBqdW1kY2JvcgARABCAAACqADibcRNjMnBhLmhhc2guZGF0YQAAAAAYYzJzaBH+BWR6yx13LAb1WXajqw8AAACAY2JvcqVjYWxnZnNoYTI1NmNwYWRMAAAAAAAAAAAAAAAAZGhhc2hYIAaDziOUWz+7p2KAj0VupM7kEr9817osQVDanCTT/hyaZG5hbWVuanVtYmYgbWFuaWZlc3RqZXhjbHVzaW9uc4GiZXN0YXJ0GQLSZmxlbmd0aBkeBAAAAj5qdW1iAAAAJ2p1bWRjMmNsABEAEIAAAKoAOJtxA2MycGEuY2xhaW0udjIAAAACD2Nib3KlY2FsZ2ZzaGEyNTZpc2lnbmF0dXJleE1zZWxmI2p1bWJmPS9jMnBhL3VybjpjMnBhOjk3ZWM5YTE2LWVmYjUtNDA2Zi05YzQxLTc0MmQzZTVmODRjNS9jMnBhLnNpZ25hdHVyZWppbnN0YW5jZUlEeCx4bXA6aWlkOjAyZDYzMmM0LTk0MjYtNDljMC04YjY5LWRkMTJkZDRiN2NjYnJjcmVhdGVkX2Fzc2VydGlvbnODomN1cmx4LXNlbGYjanVtYmY9YzJwYS5hc3NlcnRpb25zL2MycGEuaW5ncmVkaWVudC52M2RoYXNoWCCx/V3Oe2DG0uC0zpoq1TOnLTAT5e2taAMzCIOJHm8LjaJjdXJseCpzZWxmI2p1bWJmPWMycGEuYXNzZXJ0aW9ucy9jMnBhLmFjdGlvbnMudjJkaGFzaFggmyEy8ypEkSXVYEVOtjnnH1JO/pMsc8yi+upBA2LcUo2iY3VybHgpc2VsZiNqdW1iZj1jMnBhLmFzc2VydGlvbnMvYzJwYS5oYXNoLmRhdGFkaGFzaFggi2Ymn1Gy6qapuntAUFd/izebB/OEsflskyafPC1LwD10Y2xhaW1fZ2VuZXJhdG9yX2luZm+jZG5hbWVvQW50aHJvcGljIEZpbGVzZ3ZlcnNpb25lMS4wLjBrc3BlY1ZlcnNpb25lMi40LjAAABA4anVtYgAAAChqdW1kYzJjcwARABCAAACqADibcQNjMnBhLnNpZ25hdHVyZQAAABAIY2JvctKEWQISogEmGCFZAgowggIGMIIBjaADAgECAhRA5aAK7sI50L64g/oGQgU9Z1UTADAKBggqhkjOPQQDAzBJMRcwFQYDVQQKEw5BbnRocm9waWMsIFBCQzEuMCwGA1UEAxMlQW50aHJvcGljIENvbnRlbnQgQ3JlZGVudGlhbHMgUm9vdCBDQTAeFw0yNjA4MDcxODQzNTZaFw0yODA4MDYxOTQzNTZaMEQxFzAVBgNVBAoTDkFudGhyb3BpYywgUEJDMSkwJwYDVQQDEyBBbnRocm9waWMgQ2xhdWRlIENvbnRlbnQgU2lnbmluZzBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABJh6CmvLUBgFFNU0vUKlOVtE6djd17L5SuwX0LemFisBM3dkd/3cyjxFA3Qo5S46fX0/ihY0VZ7mfb9KF703t5OjWDBWMA4GA1UdDwEB/wQEAwIHgDAVBgNVHSUEDjAMBgorBgEEAYPoXgIBMAwGA1UdEwEB/wQCMAAwHwYDVR0jBBgwFoAUzlHiBIFOZFsj+OPEz5o+nMHXXMIwCgYIKoZIzj0EAwMDZwAwZAIwMXMdFJ4BetLLVY7ORuE9noqbbAZOZn/aArXyTwFAZfKrPzxF2vPoJNf1+UCdg1XGAjBwX1zd9WGqYkqmL5SFqw1QySjr1zJfpJM9+1rdDwSPLMOPOjKuiXjoU/pUUeG9RwmhY3BhZFkNngAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAPZYQMCF4t79NseMlNyqts16cQzOB+Czs6ZTGd3+FwNct093gwh0W5CDAHOQ34N+Ijbtn2JRegT9z7L/CIz4P4244aE=</c2pa:manifest></metadata></svg>

shuotype/config.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Mapping
+
+from .hotkey import HotkeyError, parse_hotkey
+
+
+class ConfigError(Exception):
+    """配置缺失或格式错误。"""
+
+
+def _xdg_dir(name: str, fallback: Path) -> Path:
+    value = os.environ.get(name, "")
+    if value:
+        candidate = Path(value)
+        if candidate.is_absolute():
+            return candidate
+    return fallback
+
+
+def config_dir() -> Path:
+    return _xdg_dir("XDG_CONFIG_HOME", Path.home() / ".config") / "shuotype"
+
+
+def config_path() -> Path:
+    return config_dir() / "config.json"
+
+
+def cache_dir() -> Path:
+    return _xdg_dir("XDG_CACHE_HOME", Path.home() / ".cache") / "shuotype"
+
+
+def runtime_dir() -> Path:
+    value = os.environ.get("XDG_RUNTIME_DIR", "")
+    if value and Path(value).is_absolute():
+        return Path(value) / "shuotype"
+    return Path(tempfile.gettempdir()) / f"shuotype-{os.getuid()}"
+
+
+POLISH_MODES = {"off", "fillers", "polish"}
+PASTE_KEYS = {"ctrl+shift+v", "ctrl+v", "shift+insert"}
+ASR_MODES = {"oneshot", "streaming"}
+
+
+@dataclass
+class Config:
+    access_key_id: str = ""
+    access_key_secret: str = field(default="", repr=False)
+    app_key: str = ""
+    region: str = "cn-shanghai"
+    deepseek_api_key: str = field(default="", repr=False)
+    deepseek_base_url: str = "https://api.deepseek.com"
+    deepseek_model: str = "deepseek-chat"
+    polish_mode: str = "off"
+    asr_mode: str = "oneshot"
+    hotkey: str = "右Ctrl"
+    paste_keys: str = "ctrl+shift+v"
+    audio_device: str | int = "pulse"
+    max_seconds: int = 60
+    notifications: bool = True
+
+    @classmethod
+    def load(
+        cls,
+        path: Path | None = None,
+        environ: Mapping[str, str] | None = None,
+    ) -> "Config":
+        path = path or config_path()
+        env = dict(os.environ if environ is None else environ)
+        data: dict = {}
+        if path.exists():
+            try:
+                data = json.loads(path.read_text(encoding="utf-8"))
+            except json.JSONDecodeError as exc:
+                raise ConfigError(f"配置文件格式错误: {path}: {exc}") from exc
+            except (OSError, UnicodeDecodeError) as exc:
+                raise ConfigError(f"无法读取配置文件: {path}: {exc}") from exc
+            if not isinstance(data, dict):
+                raise ConfigError(f"配置文件根节点必须是 JSON 对象: {path}")
+        if data.get("hotkey") == "<Control><Alt>v":
+            # 旧版本默认值；GNOME 快捷键已移除，迁移为新的默认热键。
+            data["hotkey"] = cls.__dataclass_fields__["hotkey"].default
+        known = set(cls.__dataclass_fields__)
+        cfg = cls(**{key: value for key, value in data.items() if key in known})
+        cfg.access_key_id = env.get("SHUOTYPE_AK_ID") or cfg.access_key_id
+        cfg.access_key_secret = env.get("SHUOTYPE_AK_SECRET") or cfg.access_key_secret
+        cfg.app_key = env.get("SHUOTYPE_APPKEY") or cfg.app_key
+        cfg.deepseek_api_key = env.get("DEEPSEEK_API_KEY") or cfg.deepseek_api_key
+        cfg.validate()
+        return cfg
+
+    def validate(self) -> None:
+        for name in (
+            "access_key_id",
+            "access_key_secret",
+            "app_key",
+            "deepseek_api_key",
+            "deepseek_base_url",
+            "deepseek_model",
+            "polish_mode",
+            "asr_mode",
+            "hotkey",
+            "paste_keys",
+            "region",
+        ):
+            if not isinstance(getattr(self, name), str):
+                raise ConfigError(f"{name} 必须是字符串")
+        if not isinstance(self.notifications, bool):
+            raise ConfigError("notifications 必须是布尔值")
+        if isinstance(self.audio_device, bool) or not isinstance(
+            self.audio_device, (str, int)
+        ):
+            raise ConfigError("audio_device 必须是字符串或整数")
+        if self.region != "cn-shanghai":
+            raise ConfigError("目前仅支持 cn-shanghai")
+        if self.polish_mode not in POLISH_MODES:
+            raise ConfigError(f"polish_mode 必须是 {sorted(POLISH_MODES)} 之一")
+        if self.asr_mode not in ASR_MODES:
+            raise ConfigError(f"asr_mode 必须是 {sorted(ASR_MODES)} 之一")
+        if (
+            isinstance(self.max_seconds, bool)
+            or not isinstance(self.max_seconds, int)
+            or self.max_seconds <= 0
+        ):
+            raise ConfigError("max_seconds 必须是正整数")
+        if self.max_seconds > 60:
+            raise ConfigError("max_seconds 不能超过 60（一句话识别上限）")
+        if self.paste_keys not in PASTE_KEYS:
+            raise ConfigError("paste_keys 只支持 ctrl+shift+v / ctrl+v / shift+insert")
+        try:
+            parse_hotkey(self.hotkey)
+        except HotkeyError as exc:
+            raise ConfigError(f"hotkey 配置无效: {exc}") from exc
+
+    def require_asr(self) -> None:
+        missing = [
+            name
+            for name in ("access_key_id", "access_key_secret", "app_key")
+            if not getattr(self, name)
+        ]
+        if missing:
+            raise ConfigError(f"缺少配置: {', '.join(missing)}（运行 shuotype init）")
+
+    def require_deepseek(self) -> None:
+        if not self.deepseek_api_key:
+            raise ConfigError("polish_mode 已开启，但缺少 deepseek_api_key")
+
+    def save(self, path: Path | None = None) -> Path:
+        self.validate()
+        path = path or config_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        payload = asdict(self)
+        content = json.dumps(payload, ensure_ascii=False, indent=2) + "\n"
+        fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write(content)
+        os.chmod(path, 0o600)
+        return path