netizen-cli 0.10.0__py3-none-any.whl

netizen_cli/model_settings.py

@@ -0,0 +1,269 @@
+"""Model-catalog projection and native Turn setting validation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from openai_codex.generated.v2_all import ModelUpgradeInfo
+
+
+# App Server uses this protocol-level request value to explicitly select
+# Standard processing instead of inheriting a previous accelerated tier.  It
+# is not a model capability; accelerated/alternative tiers still come only
+# from ``codex.models()``.  Keep this aligned with the exact release source:
+# https://github.com/openai/codex/blob/rust-v0.154.0/codex-rs/protocol/src/config_types.rs
+STANDARD_SERVICE_TIER_ID = "default"
+
+
+class ModelCatalogError(ValueError):
+    pass
+
+
+@dataclass(frozen=True, slots=True)
+class EffortOption:
+    id: str
+    description: str
+    wire_value: object
+
+
+@dataclass(frozen=True, slots=True)
+class ServiceTierOption:
+    id: str
+    name: str
+    description: str
+
+
+@dataclass(frozen=True, slots=True)
+class ModelOption:
+    id: str
+    model: str
+    display_name: str
+    description: str
+    is_default: bool
+    default_effort_id: str
+    default_service_tier_id: str
+    efforts: tuple[EffortOption, ...]
+    service_tiers: tuple[ServiceTierOption, ...]
+    input_modalities: tuple[str, ...] | None = None
+    upgrade: str | None = None
+    upgrade_info: ModelUpgradeInfo | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class TurnModelSettings:
+    """Validated wire values for one native ``turn/start`` override."""
+
+    model_id: str
+    model: str
+    effort_id: str
+    effort: object
+    service_tier_id: str
+    service_tier_name: str
+
+
+@dataclass(frozen=True, slots=True)
+class ModelCatalog:
+    models: tuple[ModelOption, ...]
+
+    @classmethod
+    def from_response(cls, response: object) -> ModelCatalog:
+        if getattr(response, "next_cursor", None) is not None:
+            # The pinned public ``models()`` facade has no cursor parameter.
+            # Treat a paginated response as incomplete instead of silently
+            # presenting only the first page as the full native catalog.
+            raise ModelCatalogError(
+                "Codex 模型目录需要分页，但当前高层 SDK 无法读取后续页面。"
+            )
+        raw_models = getattr(response, "data", None)
+        if not isinstance(raw_models, list) or not raw_models:
+            raise ModelCatalogError("Codex 没有返回可用模型。")
+
+        models = tuple(_model_option(raw) for raw in raw_models)
+        ids = [model.id for model in models]
+        if len(ids) != len(set(ids)):
+            raise ModelCatalogError("Codex 模型目录包含重复 ID。")
+        defaults = [model for model in models if model.is_default]
+        if len(defaults) != 1:
+            raise ModelCatalogError("Codex 模型目录必须包含且仅包含一个默认模型。")
+        return cls(models)
+
+    @property
+    def default_model(self) -> ModelOption:
+        return next(model for model in self.models if model.is_default)
+
+    @property
+    def effort_options(self) -> tuple[EffortOption, ...]:
+        seen: set[str] = set()
+        options: list[EffortOption] = []
+        for model in self.models:
+            for option in model.efforts:
+                if option.id in seen:
+                    continue
+                seen.add(option.id)
+                options.append(option)
+        return tuple(options)
+
+    @property
+    def service_tier_options(self) -> tuple[ServiceTierOption, ...]:
+        options = [
+            ServiceTierOption(
+                STANDARD_SERVICE_TIER_ID,
+                "Standard",
+                "Codex 标准服务层",
+            )
+        ]
+        seen = {STANDARD_SERVICE_TIER_ID}
+        for model in self.models:
+            for option in model.service_tiers:
+                if option.id in seen:
+                    continue
+                seen.add(option.id)
+                options.append(option)
+        return tuple(options)
+
+    def resolve(
+        self,
+        *,
+        model_id: str,
+        effort_id: str,
+        service_tier_id: str,
+    ) -> TurnModelSettings:
+        model = next((item for item in self.models if item.id == model_id), None)
+        if model is None:
+            raise ModelCatalogError("所选 Model 已不可用，请重新打开卡片。")
+        effort = next((item for item in model.efforts if item.id == effort_id), None)
+        if effort is None:
+            raise ModelCatalogError(
+                f"Model {model.display_name} 不支持 Effort {effort_id}，"
+                "请重新选择。"
+            )
+        if service_tier_id == STANDARD_SERVICE_TIER_ID:
+            service_tier_name = "Standard"
+        else:
+            service_tier = next(
+                (
+                    item
+                    for item in model.service_tiers
+                    if item.id == service_tier_id
+                ),
+                None,
+            )
+            if service_tier is None:
+                raise ModelCatalogError(
+                    f"Model {model.display_name} 不支持 Speed {service_tier_id}，"
+                    "请重新选择。"
+                )
+            service_tier_name = service_tier.name
+        return TurnModelSettings(
+            model_id=model.id,
+            model=model.model,
+            effort_id=effort.id,
+            effort=effort.wire_value,
+            service_tier_id=service_tier_id,
+            service_tier_name=service_tier_name,
+        )
+
+
+def _model_option(raw: Any) -> ModelOption:
+    model_id = _nonempty_string(getattr(raw, "id", None), "model.id")
+    model = _nonempty_string(getattr(raw, "model", None), "model.model")
+    display_name = _nonempty_string(
+        getattr(raw, "display_name", None),
+        "model.display_name",
+    )
+    description = str(getattr(raw, "description", "") or "")
+    raw_modalities = getattr(raw, "input_modalities", None)
+    modalities = (
+        tuple(getattr(item, "value", item) for item in raw_modalities)
+        if isinstance(raw_modalities, list) else None
+    )
+
+    efforts = tuple(
+        _effort_option(option)
+        for option in (getattr(raw, "supported_reasoning_efforts", None) or [])
+    )
+    if not efforts:
+        raise ModelCatalogError(f"Model {display_name} 没有可用 Effort。")
+    effort_ids = [option.id for option in efforts]
+    if len(effort_ids) != len(set(effort_ids)):
+        raise ModelCatalogError(f"Model {display_name} 包含重复 Effort。")
+
+    default_effort_id = _enum_value(
+        getattr(raw, "default_reasoning_effort", None),
+        "model.default_reasoning_effort",
+    )
+    if default_effort_id not in set(effort_ids):
+        raise ModelCatalogError(
+            f"Model {display_name} 的默认 Effort 不在支持列表中。"
+        )
+
+    tiers = tuple(
+        _service_tier_option(option)
+        for option in (getattr(raw, "service_tiers", None) or [])
+    )
+    tier_ids = [option.id for option in tiers]
+    if len(tier_ids) != len(set(tier_ids)):
+        raise ModelCatalogError(f"Model {display_name} 包含重复 Service Tier。")
+    default_tier = getattr(raw, "default_service_tier", None)
+    if default_tier is None:
+        default_tier_id = STANDARD_SERVICE_TIER_ID
+    else:
+        default_tier_id = _nonempty_string(
+            default_tier,
+            "model.default_service_tier",
+        )
+        if default_tier_id not in set(tier_ids):
+            raise ModelCatalogError(
+                f"Model {display_name} 的默认 Service Tier 不在支持列表中。"
+            )
+
+    return ModelOption(
+        id=model_id,
+        model=model,
+        display_name=display_name,
+        description=description,
+        is_default=bool(getattr(raw, "is_default", False)),
+        default_effort_id=default_effort_id,
+        default_service_tier_id=default_tier_id,
+        efforts=efforts,
+        service_tiers=tiers,
+        input_modalities=(
+            modalities
+            if modalities is not None and all(isinstance(item, str) for item in modalities)
+            else None
+        ),
+        upgrade=(getattr(raw, "upgrade", None) or None),
+        upgrade_info=(
+            raw.upgrade_info
+            if isinstance(getattr(raw, "upgrade_info", None), ModelUpgradeInfo)
+            else None
+        ),
+    )
+
+
+def _effort_option(raw: Any) -> EffortOption:
+    wire_value = getattr(raw, "reasoning_effort", None)
+    return EffortOption(
+        id=_enum_value(wire_value, "reasoning_effort"),
+        description=str(getattr(raw, "description", "") or ""),
+        wire_value=wire_value,
+    )
+
+
+def _service_tier_option(raw: Any) -> ServiceTierOption:
+    return ServiceTierOption(
+        id=_nonempty_string(getattr(raw, "id", None), "service_tier.id"),
+        name=_nonempty_string(getattr(raw, "name", None), "service_tier.name"),
+        description=str(getattr(raw, "description", "") or ""),
+    )
+
+
+def _enum_value(value: Any, field: str) -> str:
+    return _nonempty_string(getattr(value, "value", value), field)
+
+
+def _nonempty_string(value: Any, field: str) -> str:
+    if not isinstance(value, str) or not value:
+        raise ModelCatalogError(f"Codex 模型目录字段 {field} 无效。")
+    return value

netizen_cli/package_resources.py

@@ -0,0 +1,22 @@
+"""Read files shipped with this exact installation, or an explicit checkout."""
+
+from pathlib import Path
+
+
+def resource_path(relative: str) -> Path:
+    requested = Path(relative)
+    if requested.is_absolute() or ".." in requested.parts:
+        raise ValueError("package resource path must be relative without parent traversal")
+    package = Path(__file__).resolve().parent
+    root = package / "resources"
+    if root.is_symlink():
+        raise ValueError("package resource directory must not be a symlink")
+    if not root.exists():
+        source = package.parent
+        if package.name != "netizen_cli" or not (source / "pyproject.toml").is_file():
+            raise FileNotFoundError("installed Netizen resource directory is missing")
+        root = source
+    resource = root / requested
+    if resource.is_symlink() or not resource.is_file() or not resource.resolve().is_relative_to(root):
+        raise FileNotFoundError(f"Netizen package resource is missing or unsafe: {relative}")
+    return resource

netizen_cli/projects.py

@@ -0,0 +1,327 @@
+"""Persistent Channel aliases for native Codex working directories."""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from .bindings import (
+    PROJECT_DELETE_LIMIT,
+    BindingStore,
+    ProjectConflict as StoredProjectConflict,
+    ProjectDeleteSnapshot,
+    ProjectNotFound as StoredProjectNotFound,
+    ProjectRecord,
+    ProjectRevisionConflict as StoredProjectRevisionConflict,
+)
+
+
+_ALIAS = re.compile(r"^[a-z0-9][a-z0-9_-]{0,63}$")
+
+
+class ProjectError(ValueError):
+    pass
+
+
+class UnknownProject(ProjectError):
+    pass
+
+
+class ProjectDisabled(ProjectError):
+    pass
+
+
+class ProjectAlreadyExists(ProjectError):
+    pass
+
+
+class StaleProject(ProjectError):
+    pass
+
+
+@dataclass(frozen=True, slots=True)
+class Project:
+    alias: str
+    cwd: Path
+    enabled: bool
+    revision: int
+
+
+class ProjectRegistry:
+    def __init__(
+        self,
+        *,
+        store: BindingStore,
+        project_root: Path,
+        projects: dict[str, Path],
+    ) -> None:
+        self._store = store
+        self._project_root = _canonical_directory(project_root, "projectRoot")
+        for alias, configured_path in projects.items():
+            self._bootstrap(alias=alias, configured_path=configured_path)
+
+    @property
+    def project_root(self) -> Path:
+        return self._project_root
+
+    def list(self, *, enabled_only: bool = False) -> tuple[Project, ...]:
+        projects = tuple(_project(record) for record in self._store.list_projects())
+        if not enabled_only:
+            return projects
+        return tuple(project for project in projects if project.enabled)
+
+    def resolve_for_new(
+        self,
+        alias: str,
+        *,
+        expected_revision: int | None = None,
+    ) -> Project:
+        project = self._resolve(alias)
+        if expected_revision is not None and project.revision != expected_revision:
+            raise StaleProject(
+                f"Project {alias} 已被其他操作修改，请刷新卡片后重试。"
+            )
+        if not project.enabled:
+            raise ProjectDisabled(f"Project {alias} 已停用，不能创建新会话。")
+        return _usable_project(project)
+
+    def resolve_for_binding(self, alias: str) -> Project:
+        return _usable_project(self._resolve(alias))
+
+    def resolve(self, alias: str) -> Project:
+        """Compatibility alias for existing bindings; disabled rows still resolve."""
+        return self.resolve_for_binding(alias)
+
+    def aliases(self) -> tuple[str, ...]:
+        return tuple(project.alias for project in self.list())
+
+    def register(
+        self,
+        *,
+        alias: str,
+        path: str | None,
+        create_directory: bool,
+    ) -> Project:
+        alias = alias.strip()
+        _validate_alias(alias)
+        try:
+            self._store.get_project(alias)
+        except StoredProjectNotFound:
+            pass
+        else:
+            raise ProjectAlreadyExists(f"Project {alias} 已存在。")
+
+        created_directory: Path | None = None
+        if create_directory:
+            target = self._creation_target(alias=alias, path=path)
+            if target.exists():
+                raise ProjectError(
+                    f"目录 {target} 已存在；请改用“登记已有目录”。"
+                )
+            try:
+                target.mkdir(mode=0o700)
+            except OSError as error:
+                raise ProjectError(f"无法创建 Project 目录 {target}：{error}") from error
+            created_directory = target
+            try:
+                cwd = _canonical_directory(target, alias)
+            except ProjectError as error:
+                raise ProjectError(
+                    f"{error} 新建目录 {target} 已保留，未自动删除。"
+                ) from error
+        else:
+            if path is None or not path.strip():
+                raise ProjectError("登记已有目录时必须填写绝对路径。")
+            cwd = _canonical_directory(Path(path.strip()).expanduser(), alias)
+
+        try:
+            record = self._store.register_project(alias=alias, cwd=str(cwd))
+        except StoredProjectConflict as error:
+            if created_directory is not None:
+                raise ProjectAlreadyExists(
+                    f"Project {alias} 已被其他操作登记；新建目录 {created_directory} "
+                    "已保留，未自动删除。"
+                ) from error
+            raise ProjectAlreadyExists(f"Project {alias} 已存在。") from error
+        except Exception as error:
+            if created_directory is not None:
+                raise ProjectError(
+                    f"Project {alias} 登记失败；新建目录 {created_directory} "
+                    "已保留，未自动删除。"
+                ) from error
+            raise
+        return _project(record)
+
+    def set_enabled(
+        self,
+        *,
+        alias: str,
+        enabled: bool,
+        expected_revision: int,
+    ) -> Project:
+        try:
+            record = self._store.set_project_enabled(
+                alias=alias,
+                enabled=enabled,
+                expected_revision=expected_revision,
+            )
+        except StoredProjectNotFound as error:
+            raise UnknownProject(alias) from error
+        except StoredProjectRevisionConflict as error:
+            raise StaleProject(
+                f"Project {alias} 已被其他操作修改，请刷新卡片后重试。"
+            ) from error
+        except StoredProjectConflict as error:
+            raise ProjectError(str(error)) from error
+        return _project(record)
+
+    def preview_delete(
+        self,
+        alias: str,
+        *,
+        limit: int = PROJECT_DELETE_LIMIT,
+        extra_side_ids: tuple[str, ...] = (),
+    ) -> ProjectDeleteSnapshot:
+        try:
+            return self._store.preview_project_delete(
+                alias, limit=limit, extra_side_ids=extra_side_ids,
+            )
+        except StoredProjectNotFound as error:
+            raise UnknownProject(alias) from error
+        except StoredProjectConflict as error:
+            raise ProjectError(str(error)) from error
+
+    def begin_delete(
+        self,
+        *,
+        alias: str,
+        expected_revision: int,
+        expected_inventory_fingerprint: str,
+        limit: int = PROJECT_DELETE_LIMIT,
+        extra_side_ids: tuple[str, ...] = (),
+    ) -> ProjectDeleteSnapshot:
+        try:
+            return self._store.begin_project_delete(
+                alias=alias,
+                expected_revision=expected_revision,
+                expected_inventory_fingerprint=expected_inventory_fingerprint,
+                limit=limit,
+                extra_side_ids=extra_side_ids,
+            )
+        except StoredProjectNotFound as error:
+            raise UnknownProject(alias) from error
+        except StoredProjectRevisionConflict as error:
+            raise StaleProject(f"Project {alias} 已改变，请刷新后重新确认。") from error
+        except StoredProjectConflict as error:
+            raise ProjectError(str(error)) from error
+
+    def finish_delete(
+        self,
+        *,
+        alias: str,
+        expected_revision: int,
+        expected_inventory_fingerprint: str,
+    ) -> None:
+        try:
+            self._store.finish_project_delete(
+                alias=alias,
+                expected_revision=expected_revision,
+                expected_inventory_fingerprint=expected_inventory_fingerprint,
+            )
+        except StoredProjectNotFound as error:
+            raise UnknownProject(alias) from error
+        except StoredProjectRevisionConflict as error:
+            raise StaleProject(f"Project {alias} 已改变，请刷新后重新确认。") from error
+        except StoredProjectConflict as error:
+            raise ProjectError(str(error)) from error
+
+    def release_delete(self, *, alias: str, expected_revision: int) -> None:
+        try:
+            self._store.release_project_delete(
+                alias=alias, expected_revision=expected_revision
+            )
+        except StoredProjectRevisionConflict as error:
+            raise StaleProject(f"Project {alias} 已改变，请刷新后重新确认。") from error
+
+    def _resolve(self, alias: str) -> Project:
+        try:
+            return _project(self._store.get_project(alias))
+        except StoredProjectNotFound as error:
+            raise UnknownProject(alias) from error
+
+    def _bootstrap(
+        self,
+        *,
+        alias: str,
+        configured_path: Path,
+    ) -> None:
+        _validate_alias(alias)
+        try:
+            self._store.get_project(alias, include_deleted=True)
+        except StoredProjectNotFound:
+            cwd = _canonical_directory(configured_path, alias)
+            self._store.bootstrap_project(alias=alias, cwd=str(cwd))
+
+    def _creation_target(self, *, alias: str, path: str | None) -> Path:
+        raw = (
+            Path(path.strip()).expanduser()
+            if path is not None and path.strip()
+            else self._project_root / alias
+        )
+        if not raw.is_absolute():
+            raise ProjectError("创建 Project 的路径必须是绝对路径。")
+        target = raw.resolve(strict=False)
+        if target == self._project_root or not target.is_relative_to(
+            self._project_root
+        ):
+            raise ProjectError(
+                f"只能在 projectRoot {self._project_root} 内创建目录。"
+            )
+        try:
+            parent = target.parent.resolve(strict=True)
+        except OSError as error:
+            raise ProjectError(f"Project 父目录不存在：{target.parent}") from error
+        if not parent.is_relative_to(self._project_root):
+            raise ProjectError(
+                f"只能在 projectRoot {self._project_root} 内创建目录。"
+            )
+        if not parent.is_dir() or not os.access(parent, os.R_OK | os.W_OK | os.X_OK):
+            raise ProjectError(f"Project 父目录不可读写：{parent}")
+        return target
+
+
+def _validate_alias(alias: str) -> None:
+    if not _ALIAS.fullmatch(alias):
+        raise ProjectError(f"无效 Project alias：{alias}")
+
+
+def _project(record: ProjectRecord) -> Project:
+    return Project(
+        alias=record.alias,
+        cwd=Path(record.cwd),
+        enabled=record.enabled,
+        revision=record.revision,
+    )
+
+
+def _usable_project(project: Project) -> Project:
+    cwd = _canonical_directory(project.cwd, project.alias)
+    if cwd == project.cwd:
+        return project
+    return Project(project.alias, cwd, project.enabled, project.revision)
+
+
+def _canonical_directory(path: Path, alias: str) -> Path:
+    if not path.is_absolute():
+        raise ProjectError(f"Project {alias} cwd 必须是绝对路径。")
+    try:
+        cwd = path.expanduser().resolve(strict=True)
+    except OSError as error:
+        raise ProjectError(f"Project {alias} cwd 不存在：{path}") from error
+    if not cwd.is_dir():
+        raise ProjectError(f"Project {alias} cwd 不是目录。")
+    if not os.access(cwd, os.R_OK | os.W_OK | os.X_OK):
+        raise ProjectError(f"Project {alias} cwd 必须可读、可写、可进入。")
+    return cwd