netizen-cli 0.10.2__tar.gz → 0.11.1__tar.gz

{netizen_cli-0.10.2/netizen_cli.egg-info → netizen_cli-0.11.1}/PKG-INFO

@@ -1,16 +1,17 @@
 Metadata-Version: 2.4
 Name: netizen-cli
-Version: 0.10.2
+Version: 0.11.1
 Summary: Use native Codex threads through a Feishu Channel.
 Requires-Python: <3.15,>=3.11
 Requires-Dist: h11==0.16.0
+Requires-Dist: httpx==0.28.1
 Requires-Dist: lark-channel-sdk==1.4.0
 Requires-Dist: lark-oapi==1.7.2
 Requires-Dist: markdown-it-py==4.0.0
 Requires-Dist: mdformat==1.0.0
 Requires-Dist: mdformat-gfm==1.0.0
 Requires-Dist: mcp==2.2.0
-Requires-Dist: openai-codex==0.159.2
+Requires-Dist: openai-codex==0.162.1
 Requires-Dist: pydantic==2.13.4
 Requires-Dist: PyYAML==6.0.3
 Requires-Dist: qrcode==8.2

{netizen_cli-0.10.2 → netizen_cli-0.11.1}/README.md

@@ -41,6 +41,9 @@
   [群聊上下文](skills/netizen-user-guide/references/user-guide.md#发送消息引用与图片)。
 - **取回本轮文件。** 完成后从回复卡片中按需发送有原生执行记录的文件；发送的是点击时
   的当前内容，详见[文件说明](skills/netizen-user-guide/references/user-guide.md#查看和发送本轮文件)。
+- **保留上下文，另开一条讨论。** 用
+  [持久分支](skills/netizen-user-guide/references/user-guide.md#fork-持久分支)在当前聊天或其他群
+  创建普通话题，之后独立继续。
 - **展开临时讨论，推进持续目标。** 用
   [Side](skills/netizen-user-guide/references/user-guide.md#side-临时话题)另开临时话题，或用
   [Goal](skills/netizen-user-guide/references/user-guide.md#goal)让 Codex 围绕目标持续推进。
@@ -80,16 +83,20 @@ netizen start
 netizen status
 ```
 
-setup 准备配置、飞书授权和实例数据并注册服务，不默认启动。首次缺凭据会输出浏览器
-验证链接；Agent 可运行 `netizen setup </dev/null`，转交链接并保留同一进程，确认后自动
-保存凭据。不要把 App Secret 发到聊天里。start 等待服务真正就绪，每次实际启动均检查
-数据格式并按需迁移。
+setup 准备配置、飞书应用、首位管理员和实例数据并注册服务，不默认启动。缺应用凭据或
+管理员时会输出浏览器验证链接；Agent 可运行 `netizen setup </dev/null`，逐次转交链接并
+保留同一进程，确认后自动保存。已有应用也可用 `netizen setup --admin-open-id ou_...`
+指定该应用下的首位管理员；已有名单不会被覆盖。不要把 App Secret 发到聊天里。
+start 等待服务真正就绪，每次实际启动均检查管理员配置、数据格式并按需迁移；后台启动
+缺配置会明确失败，不等待扫码。
 
 默认实例数据集中在 `~/.netizen`；程序位于选定 Python 环境。用 `--root` 或 NETIZEN_ROOT
 选择其他实例，例如 `netizen setup --root "$HOME/work/.netizen" --admin-port 8890`。
 各实例共享原生 Codex 状态；服务固定注册时的 Python，终端换 venv 不改变已有绑定。
 
 日常维护用 `netizen update` 更新当前环境并恢复原来运行的实例；它不接受 --root。
+Agent／脚本使用 `netizen update --json`：stdout 只输出最终 JSON，进度和包管理器输出
+写入 stderr。以 JSON 和退出码判断结果，包验证成功与实例恢复 ready 分别报告。
 `netizen remove --root ...` 默认保留数据，--purge 才清理精确范围，-y 只省略确认。
 完整流程、失败边界、跨环境切换和卸载见 [CLI 安装与维护](docs/cli.md)。
 
@@ -122,8 +129,10 @@ setup 准备配置、飞书授权和实例数据并注册服务，不默认启
 | 新建会话，选择项目 | `/new` |
 | 查看、保存或删除当前聊天的会话默认配置 | `/defaults` |
 | 查看并切换已有会话 | `/sessions` |
+| 从当前空闲会话另建持久分支话题 | `/fork` |
 | 调整模型、思考强度和过程卡 | `/config`，当前会话空闲时使用 |
 | 查看当前任务和上下文用量 | `/status` |
+| 查看共享 Codex 账号额度和重置时间 | `/usage` |
 | 中断当前任务 | `/stop`；不保证前台工具进程退出，见[停止说明](skills/netizen-user-guide/references/user-guide.md#stop) |
 | 查找当前机器人的管理入口 | `/admin`；返回实际管理 URL 和实例根目录，不返回登录凭据 |
 | 管理定时任务 | `/cron`，也可以直接用自然语言描述计划 |
@@ -157,10 +166,13 @@ Side 会在同一聊天中新建话题，可继续多轮讨论。它与原会话
 ## 管理与维护
 
 实例管理员可以通过 **Admin Web** 集中管理项目、会话、Side 话题、会话默认配置和定时任务，
-并在“系统维护”中检查正式更新或重启服务。发送 `/admin` 可获取当前实例的管理 URL
+并在“系统维护”中查看安装信息或重启服务。发送 `/admin` 可获取当前实例的管理 URL
 和根目录，无需创建会话。未指定端口时首次从 `8787` 起分配并保存，各实例独立监听；
-管理页仍使用安装器生成的独立管理员凭据，命令不会返回凭据或免登录链接。
-[访问方式](docs/deployment.md#配置与管理页访问)见部署文档。
+管理页使用飞书登录，并核对当前应用的管理员名单，命令不会返回凭据或免登录链接。
+Admin 是实例必备能力；管理员可在“系统管理 → 权限管理 → 管理员”中维护名单。
+服务重启后需要重新登录。
+[访问方式](docs/deployment.md#配置与管理页访问)见部署文档。飞书登录与管理员维护描述
+当前源码行为，真人和平台验收尚未完成，见[验收状态](docs/deployment.md#admin-飞书登录与管理员维护验收)。
 
 升级与重启都会影响正在执行的任务，重启后不会自动续跑。
 [正式升级、启停与卸载](docs/deployment.md#升级启停和卸载) ·
@@ -169,13 +181,13 @@ Side 会在同一聊天中新建话题，可继续多轮讨论。它与原会话
 ## 使用前了解
 
 - **共享环境。** 飞书应用的可用范围和群成员关系控制谁能访问；同一实例复用服务账号，
-  不提供按用户或项目隔离的权限体系。Admin Web 面向受信内网的单管理员。
+  不提供按用户或项目隔离的权限体系。Admin Web 面向受信内网，名单中的管理员权限相同。
 - **输入与输出。** 支持文本、普通图片和富文本图片，也可提供飞书 2.0 卡片、合并转发与转发话题作为
   [背景材料](skills/netizen-user-guide/references/user-guide.md#卡片合并转发与转发话题)。材料内部的媒体只提供未读附件描述；直接文件和音视频仍不支持。
   飞书 1.0 卡片明确不支持。
   输出文件按本轮原生记录发现，不扫描工作区补齐，也不自动上传。
 - **Codex 能力有宿主差异。** 飞书复用原生会话和工具，但并非每个 App/CLI 控件都可用；
-  新会话采用 `auto_review`，不能完整继承 App 的 Ask/Custom。
+  全新会话采用 `auto_review`，持久分支沿用原生继承权限；不提供 App 的 Ask/Custom 选择器。
   [完整差异与当前限制](skills/netizen-user-guide/references/user-guide.md#与-codex-appcli-的差异)
 
 <a id="用户指南-skill"></a>

{netizen_cli-0.10.2 → netizen_cli-0.11.1}/config.example.yaml

@@ -15,10 +15,9 @@ projects:
 channel:
   securityMode: audit
 
-# Single-administrator management UI. It is enabled by default and listens on
-# all interfaces for direct access inside the trusted private network.
+# Required management UI, using this app's Feishu administrator identities.
+# It listens on all interfaces for direct access inside the trusted private network.
 adminWeb:
-  enabled: true
   host: 0.0.0.0
   # Omit port for first-start allocation from 8787 through 8886. Once bound,
   # the selected port is written here and stays fixed on subsequent starts.
@@ -31,5 +30,7 @@ adminWeb:
 # The installer prepares this file; see docs/deployment.md for its JSON format.
 # An explicit override must be an absolute path. Lark CLI is optional.
 # NETIZEN_LARK_APP_CONFIG=/home/your-user/.netizen/lark-app/config.json
-# Admin Web supports only a canonical 32-byte base64url credential file.
-# NETIZEN_ADMIN_SECRET_FILE=/home/your-user/.netizen/credentials/admin-web-secret
+# Setup binds the first administrator through Feishu login or --admin-open-id.
+# Administrator membership: <NETIZEN_ROOT>/state/admin-users.json
+# Private user credentials: <NETIZEN_ROOT>/credentials/admin-user-tokens.json
+# Admin browser sessions stay in memory and require login after service restart.

{netizen_cli-0.10.2 → netizen_cli-0.11.1}/netizen_cli/__init__.py

@@ -1,3 +1,3 @@
 """Netizen: a thin Feishu Channel for native Codex Threads."""
 
-__version__ = "0.10.2"
+__version__ = "0.11.1"

netizen_cli-0.11.1/netizen_cli/account_rate_limits.py

@@ -0,0 +1,340 @@
+"""One read-only, removable bridge for native account quota snapshots."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import re
+from dataclasses import dataclass
+from decimal import Decimal, InvalidOperation, ROUND_HALF_UP
+from typing import Any, Protocol
+
+from openai_codex import AsyncCodex
+from pydantic import ValidationError, field_validator
+
+from .sdk_gap_adapter import (
+    SdkFacadeMigrationRequired,
+    SdkGapCapabilityUnavailable,
+    _generated_type,
+    _initialized_client,
+    _require_model_fields,
+)
+
+
+_CAPABILITY = "account-rate-limits"
+_READ_METHOD = "account/rateLimits/read"
+_READ_TIMEOUT_SECONDS = 10.0
+_MAX_BUCKETS = 64
+_MAX_LABEL_LENGTH = 256
+
+
+class AccountRateLimitsUnavailable(RuntimeError):
+    """The response cannot supply a trustworthy quota projection."""
+
+
+@dataclass(frozen=True, slots=True)
+class AccountRateLimitWindow:
+    used_percent: int
+    window_duration_mins: int | None
+    resets_at: int | None
+
+
+@dataclass(frozen=True, slots=True)
+class AccountCredits:
+    has_credits: bool
+    unlimited: bool
+    balance: int | None
+
+
+@dataclass(frozen=True, slots=True)
+class AccountMonthlyCreditLimit:
+    limit: int
+    used: int
+    remaining_percent: int
+    resets_at: int
+
+
+@dataclass(frozen=True, slots=True)
+class AccountRateLimitBucket:
+    limit_id: str | None
+    limit_name: str | None
+    primary: AccountRateLimitWindow | None
+    secondary: AccountRateLimitWindow | None
+    credits: AccountCredits | None = None
+    monthly_limit: AccountMonthlyCreditLimit | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class AccountRateLimitsSnapshot:
+    buckets: tuple[AccountRateLimitBucket, ...]
+
+
+class AccountRateLimits(Protocol):
+    async def read(self) -> AccountRateLimitsSnapshot: ...
+
+
+def facade_migration_requirements() -> tuple[str, ...]:
+    """Require review when a candidate public account-quota facade appears."""
+
+    candidates = (
+        "rate_limits",
+        "rate_limits_read",
+        "account_rate_limits",
+        "account_rate_limits_read",
+        "get_account_rate_limits",
+        "read_account_rate_limits",
+    )
+    names = tuple(
+        f"AsyncCodex.{name}" for name in candidates if hasattr(AsyncCodex, name)
+    )
+    return (
+        (f"migration-required:{_CAPABILITY}:{','.join(names)}",) if names else ()
+    )
+
+
+class AppServerAccountRateLimits:
+    """Read once through the same initialized SDK-owned client.
+
+    Timeout/cancellation stops waiting, not the SDK's underlying sync request.
+    This bridge never retries, resets quota, consumes notifications, or closes
+    the shared client. Late results remain owned by the SDK transport.
+    """
+
+    __slots__ = ("_client", "_params_model", "_response_model", "_bucket_model")
+
+    def __init__(self, codex: AsyncCodex) -> None:
+        if requirements := facade_migration_requirements():
+            raise SdkFacadeMigrationRequired("; ".join(requirements))
+        self._client = _initialized_client(codex, capability=_CAPABILITY)
+        self._params_model = _model(
+            "GetAccountRateLimitsParams",
+            {
+                "exclude_reset_credit_details": "excludeResetCreditDetails",
+                "supports_luna_reserve": "supportsLunaReserve",
+            },
+        )
+        self._response_model = _model(
+            "GetAccountRateLimitsResponse",
+            {
+                "account_id": "accountId",
+                "ordinary_usage_allowed": "ordinaryUsageAllowed",
+                "rate_limit_reset_credits": "rateLimitResetCredits",
+                "rate_limit_upsell": "rateLimitUpsell",
+                "rate_limits": "rateLimits",
+                "rate_limits_by_limit_id": "rateLimitsByLimitId",
+            },
+        )
+        self._bucket_model = _model(
+            "RateLimitSnapshot",
+            {
+                "credits": "credits",
+                "individual_limit": "individualLimit",
+                "limit_id": "limitId",
+                "limit_name": "limitName",
+                "normal_model_slug": "normalModelSlug",
+                "plan_type": "planType",
+                "primary": "primary",
+                "rate_limit_reached_type": "rateLimitReachedType",
+                "secondary": "secondary",
+                "spend_control_reached": "spendControlReached",
+            },
+        )
+        _model(
+            "RateLimitWindow",
+            {
+                "resets_at": "resetsAt",
+                "used_percent": "usedPercent",
+                "window_duration_mins": "windowDurationMins",
+            },
+        )
+        _model(
+            "CreditsSnapshot",
+            {
+                "balance": "balance",
+                "has_credits": "hasCredits",
+                "unlimited": "unlimited",
+            },
+        )
+        _model(
+            "SpendControlLimitSnapshot",
+            {
+                "limit": "limit",
+                "used": "used",
+                "remaining_percent": "remainingPercent",
+                "resets_at": "resetsAt",
+            },
+        )
+        self._response_model = _strict_response_model(
+            self._response_model, self._bucket_model
+        )
+
+    async def read(self) -> AccountRateLimitsSnapshot:
+        params = self._params_model(
+            excludeResetCreditDetails=True, supportsLunaReserve=False
+        )
+        try:
+            async with asyncio.timeout(_READ_TIMEOUT_SECONDS):
+                response = await self._client.request(
+                    _READ_METHOD,
+                    params.model_dump(by_alias=True),
+                    response_model=self._response_model,
+                )
+        except ValidationError as error:
+            raise AccountRateLimitsUnavailable("Codex 额度响应格式无效。") from error
+        if not isinstance(response, self._response_model):
+            raise AccountRateLimitsUnavailable("Codex 额度响应类型无效。")
+        multiple = response.rate_limits_by_limit_id
+        if multiple is None:
+            buckets = (self._project_bucket(response.rate_limits),)
+        else:
+            if not isinstance(multiple, dict) or not 0 < len(multiple) <= _MAX_BUCKETS:
+                raise AccountRateLimitsUnavailable("Codex 额度分组为空或超出读取范围。")
+            projected = []
+            for key, raw in multiple.items():
+                limit_id = _label(key, required=True)
+                if not isinstance(raw, dict):
+                    raise AccountRateLimitsUnavailable("Codex 额度分组格式无效。")
+                try:
+                    # JSON strict validation preserves valid string enums while
+                    # rejecting coercion of window strings/bools into numbers.
+                    bucket = self._bucket_model.model_validate_json(
+                        json.dumps(raw, allow_nan=False), strict=True
+                    )
+                except (ValidationError, TypeError, ValueError) as error:
+                    raise AccountRateLimitsUnavailable(
+                        "Codex 额度分组格式无效。"
+                    ) from error
+                projected.append(self._project_bucket(bucket, limit_id=limit_id))
+            buckets = tuple(projected)
+        if not any(
+            bucket.primary is not None or bucket.secondary is not None
+            or bucket.credits is not None or bucket.monthly_limit is not None
+            for bucket in buckets
+        ):
+            raise AccountRateLimitsUnavailable("Codex 尚未提供可用的额度数据。")
+        return AccountRateLimitsSnapshot(buckets)
+
+    def _project_bucket(
+        self, bucket: Any, *, limit_id: str | None = None
+    ) -> AccountRateLimitBucket:
+        if not isinstance(bucket, self._bucket_model):
+            raise AccountRateLimitsUnavailable("Codex 额度分组格式无效。")
+        supplied_id = _label(bucket.limit_id)
+        if limit_id is not None and supplied_id is not None and limit_id != supplied_id:
+            raise AccountRateLimitsUnavailable("Codex 额度分组标识不一致。")
+        return AccountRateLimitBucket(
+            limit_id=limit_id if limit_id is not None else supplied_id,
+            limit_name=_label(bucket.limit_name),
+            primary=_window(bucket.primary),
+            secondary=_window(bucket.secondary),
+            credits=_credits(bucket.credits),
+            monthly_limit=_monthly_limit(bucket.individual_limit),
+        )
+
+
+def _model(name: str, aliases: dict[str, str]) -> type[Any]:
+    model = _generated_type(name, capability=_CAPABILITY)
+    _require_model_fields(model, capability=_CAPABILITY, aliases=aliases)
+    if not callable(getattr(model, "model_validate_json", None)):
+        raise SdkGapCapabilityUnavailable(f"{_CAPABILITY} model validation changed")
+    return model
+
+
+def _strict_response_model(
+    response_model: type[Any], bucket_model: type[Any]
+) -> type[Any]:
+    # Inherit every field from the installed SDK. Its request decoder calls
+    # model_validate on the raw response, so validate legacy windows before
+    # Pydantic can coerce false, "0", or 0.0 into a known zero percent.
+    class StrictAccountRateLimitsResponse(response_model):
+        @field_validator("rate_limits", mode="before")
+        @classmethod
+        def _strict_legacy_bucket(cls, value: Any) -> Any:
+            if not isinstance(value, dict):
+                raise ValueError("expected a quota bucket object")
+            try:
+                return bucket_model.model_validate_json(
+                    json.dumps(value, allow_nan=False), strict=True
+                )
+            except TypeError as error:
+                raise ValueError("invalid quota bucket object") from error
+
+    return StrictAccountRateLimitsResponse
+
+
+def _label(value: Any, *, required: bool = False) -> str | None:
+    if value is None and not required:
+        return None
+    if (
+        not isinstance(value, str)
+        or not value
+        or value.strip() != value
+        or len(value) > _MAX_LABEL_LENGTH
+        or any(ord(char) < 32 or ord(char) == 127 for char in value)
+    ):
+        raise AccountRateLimitsUnavailable("Codex 额度分组名称或标识无效。")
+    return value
+
+
+def _window(value: Any) -> AccountRateLimitWindow | None:
+    if value is None:
+        return None
+    used = _nonnegative_int(value.used_percent)
+    duration = (
+        None if value.window_duration_mins is None
+        else _nonnegative_int(value.window_duration_mins)
+    )
+    resets = None if value.resets_at is None else _nonnegative_int(value.resets_at)
+    if duration == 0:
+        raise AccountRateLimitsUnavailable("Codex 额度窗口时长无效。")
+    # Native i32 percentages can exceed 100; do not invent a capped usage value.
+    return AccountRateLimitWindow(used, duration, resets)
+
+
+def _credits(value: Any) -> AccountCredits | None:
+    if value is None or not (value.unlimited or value.has_credits):
+        return None
+    # The native display treats a hidden or invalid balance as Available; it
+    # never exposes the raw string or infers requests from credit balances.
+    balance = _credit_amount(value.balance, positive=True)
+    return AccountCredits(value.has_credits, value.unlimited, balance)
+
+
+def _monthly_limit(value: Any) -> AccountMonthlyCreditLimit | None:
+    if value is None:
+        return None
+    limit, used = _credit_amount(value.limit), _credit_amount(value.used)
+    if limit is None or used is None:
+        return None
+    # Native remainingPercent can fall outside the display range; clamp only
+    # while rendering, independently of the reported used/limit amounts.
+    remaining = value.remaining_percent
+    if isinstance(remaining, bool) or not isinstance(remaining, int):
+        raise AccountRateLimitsUnavailable("Codex 月度额度数值无效。")
+    return AccountMonthlyCreditLimit(
+        limit, used, remaining, _nonnegative_int(value.resets_at)
+    )
+
+
+def _credit_amount(value: str | None, *, positive: bool = False) -> int | None:
+    if value is None:
+        return None
+    raw = value.strip()
+    if re.fullmatch(r"[+-]?(?:[0-9]+(?:\.[0-9]*)?|\.[0-9]+)(?:[eE][+-]?[0-9]+)?", raw) is None:
+        return None
+    try:
+        amount = Decimal(raw)
+    except InvalidOperation:
+        return None
+    if (
+        not amount.is_finite() or amount < 0 or (positive and amount == 0)
+        or amount > 2**63 - 1
+    ):
+        return None
+    return int(amount.to_integral_value(rounding=ROUND_HALF_UP))
+
+
+def _nonnegative_int(value: Any) -> int:
+    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+        raise AccountRateLimitsUnavailable("Codex 额度窗口数值无效。")
+    return value