cheso-cli 0.2.0__tar.gz

cheso_cli-0.2.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.3
+Name: cheso-cli
+Version: 0.2.0
+Summary: Use Cheso from your terminal or coding agent: research reports, PPT, web pages, posters, videos, images, document translation and format conversion
+Keywords: cheso,cli,ai-agent,agent-skills,claude-code,codex,ppt,research-report
+Author: cheso
+Author-email: cheso <chesoai2026@gmail.com>
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Utilities
+Requires-Dist: httpx>=0.28.1
+Requires-Python: >=3.10
+Project-URL: Homepage, https://cheso.ai
+Project-URL: Agent Skill, https://github.com/cheso-ai-platform/skills
+Description-Content-Type: text/markdown
+
+# cheso-cli
+
+Use [Cheso](https://cheso.ai) from a terminal or a coding agent (Claude Code, Codex, Cursor ...): research reports
+with citations, PPT decks, web pages, posters, whiteboards, videos, images, document analysis, translation and
+format conversion. Tasks run on Cheso with your own account and credits; result files are downloaded to your
+working directory.
+
+## Install
+
+```bash
+uv tool install cheso-cli        # or: pipx install cheso-cli
+cheso login                      # opens the Cheso sign-in page in your browser; click Allow
+cheso skill install              # teaches Claude Code and Codex how to use Cheso
+```
+
+Requires Python 3.10+. For the China site (zhishi.qq.com) log in with `cheso login --site cn`; later commands use
+the site you logged in to last unless you pass `--site` / `--base-url` or set `CHESO_BASE_URL`.
+
+Then ask your agent, for example: "Use Cheso to turn ./notes.pdf into a 10-slide PPT". Or run it yourself:
+
+```bash
+cheso task create --file ./notes.pdf --prompt "Make a 10-slide investor deck in English" --wait
+```
+
+## Login
+
+`cheso login` uses OAuth 2.1 (authorization code + PKCE) with a loopback redirect: the CLI listens once on
+`http://127.0.0.1:<random port>/callback`, opens the Cheso authorization page, and stores the tokens after you
+approve. `--no-browser` only prints the URL; `--port N` fixes the port (for SSH port forwarding:
+`ssh -L N:127.0.0.1:N host`, then open the URL locally). The browser must reach the loopback port of the machine
+running `cheso`.
+
+Without a browser or a reachable loopback port (SSH sessions, containers, cloud agents), use
+`cheso login --device` (OAuth device authorization grant, RFC 8628): it prints a Cheso page and a short code; open
+the page on any device, sign in to Cheso, enter the code and click Allow. The CLI polls until you approve (every
+5 s, up to `--timeout`, the code itself is valid for 10 minutes). Coding agents split it into two commands that
+return quickly: `cheso login --device --no-wait --json` prints the page and code; `cheso login --wait --json` keeps
+waiting and can be run again (exit 6 while still waiting). Only enter a code that you started yourself: whoever
+approves it lets that CLI act as them.
+
+- Tokens are stored in `$XDG_CONFIG_HOME/cheso/credentials.json` (default `~/.config/cheso/`), one entry per site,
+  readable only by you (file 0600, directory 0700), replaced atomically.
+- Access tokens are refreshed automatically shortly before they expire, and once more if the server rejects one.
+  Refresh tokens rotate and the server revokes the login if an old one is reused, so refreshes are serialized with a
+  lock file (`credentials.json.lock`): parallel `cheso` commands share one refresh.
+- `cheso logout` revokes the authorization on the server and deletes the local tokens. You can also revoke the CLI
+  on the Cheso website under Authorized apps.
+- Token precedence: `--token` > `CHESO_API_TOKEN` > stored login. For CI and scripts, set `CHESO_API_TOKEN` to a
+  personal Cheso API token; nothing is written to disk.
+
+## Commands
+
+Add `--json` to any command for one JSON document on stdout (progress and warnings go to stderr). Global options
+(`--site`, `--base-url`, `--token`, `--json`) may come before or after the command.
+
+| Command | What it does |
+|---|---|
+| `cheso login [--no-browser] [--port N] [--timeout S]` | Sign in with the browser |
+| `cheso login --device [--no-wait] [--timeout S]` | Sign in with a code entered on any device (no browser or loopback needed here) |
+| `cheso login --wait [--timeout S]` | Keep waiting for a sign-in started with `--device --no-wait` |
+| `cheso logout` | Revoke the login and delete stored tokens |
+| `cheso whoami` | Show the account and where the token comes from |
+| `cheso credits` | Show available credits |
+| `cheso task create --prompt TEXT [--file PATH ...] [--file-id ID ...] [--project ID] [--agent-type cheso\|image_edit] [--wait] [--timeout S] [--output-dir DIR]` | Start a task; checks credits first; `--file` uploads local files; `--wait` waits and downloads the results |
+| `cheso task wait ID [--timeout S] [--output-dir DIR] [--no-download]` | Wait for a task (`plan_...`), conversion (`cvt_...`) or translation (`tlj_...`), polling every 3 s and following hand-offs to follow-up tasks; downloads the results |
+| `cheso task get ID` | Show status, answer, files or the pending question (no download) |
+| `cheso task reply ID [--answer "QUESTION=ANSWER" ...] [--skip]` | Answer the question a task is asking (also `N=ANSWER` by number) |
+| `cheso task cancel ID` | Stop a running task |
+| `cheso file upload PATH [--project ID]` | Upload a file; prints its `file_id` |
+| `cheso file list --project ID` | List a project's files |
+| `cheso file download FILE_ID [--version N] [--output-dir DIR]` | Download a file (the latest version by default) |
+| `cheso convert FILE_ID --to TYPE [--wait] [--timeout S] [--output-dir DIR]` | Convert a file (e.g. md to pdf/docx, vppt to pptx/pdf, vmotion to mp4); unsupported targets list the valid ones |
+| `cheso translate FILE_ID --to LANG [--from LANG] [--wait] [--timeout S] [--output-dir DIR]` | Translate a document (zh, zh-Hant, en, ko, ja, es, fr, ar, ru, pt, de, th) |
+| `cheso skill install [--target claude\|codex\|all] [--project] [--force]` | Install the Agent Skill |
+| `cheso skill show` | Print the bundled SKILL.md |
+
+Downloads never overwrite: an existing `report.pdf` makes the new file `report (1).pdf`. The default `--timeout`
+is 1800 s, counted from the start of the command and covering the result downloads too: no request starts after it
+and each one gets at most the time left (uploads and starting the task are not cut short). When it passes the task
+keeps running on Cheso and `cheso task wait ID` picks it up again.
+
+The low-level API commands of the first version (`profile`, `project ...`, `session create`, `plan create|get`)
+are still available and print raw JSON.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | Error |
+| 2 | Usage error (bad flags, unsupported conversion target) |
+| 3 | The task is waiting for your answer: `cheso task reply` |
+| 4 | Login required: `cheso login` or `cheso login --device` (or the token in `CHESO_API_TOKEN` / `--token` was rejected) |
+| 5 | Not enough credits (the JSON error carries `topup_url`) |
+| 6 | Still running when `--timeout` passed: run `cheso task wait ID` again (for `cheso login --device`: `cheso login --wait`) |
+| 7 | Rate limited or project busy; retry later (`retry_after`, `running_task_id` in the JSON error) |
+| 8 | The task succeeded, but some result files were not downloaded (`error.file_ids`); `next` downloads just those. A failed task keeps 1 or 5; its files that did not download carry `error` |
+
+## Agent Skill
+
+`cheso skill install` copies `SKILL.md` (shipped inside the package) to:
+
+| Target | User level (default) | `--project` |
+|---|---|---|
+| Claude Code | `~/.claude/skills/cheso/` | `./.claude/skills/cheso/` |
+| Codex | `~/.agents/skills/cheso/` | `./.agents/skills/cheso/` |
+
+An unchanged older copy is upgraded in place; a copy you edited is left alone unless you pass `--force`.
+
+## Privacy
+
+Files you upload and the tasks you start are stored in your Cheso account, in your projects, and use your credits.
+The CLI sends your token only to the Cheso site you chose; uploads and downloads to presigned storage URLs carry no
+token. Tokens are never printed.
+
+## Environment
+
+| Variable | Use |
+|---|---|
+| `CHESO_API_TOKEN` | Personal API token (CI, scripts); overrides the stored login |
+| `CHESO_BASE_URL` | Override the site URL (e.g. `https://testcheso.ai` for the test environment) |
+| `CHESO_DEV_SET` | **Test environment only.** Adds `X-Dev-Set: <value>` to Cheso requests to route them to a developer container; has no effect in production |
+| `XDG_CONFIG_HOME` | Where `cheso/credentials.json` lives |
+
+Site precedence: `--base-url` > `--site` > `CHESO_BASE_URL` > the site of the last `cheso login` > `https://cheso.ai`.
+Suggested commands (`next`, hints in messages) repeat the `--site` / `--base-url` you passed.
+
+## Development
+
+```bash
+cd clients/cli
+uv sync
+uv run --frozen pytest -q
+uvx ruff check . && uvx ruff format --check .   # uses the repository ruff.toml
+uv build                                          # wheel and sdist in dist/
+```
+
+System tests (case library, pools, runs, reports) live in [`../test-suite`](../test-suite) (`cheso-test`).

cheso_cli-0.2.0/README.md

@@ -0,0 +1,138 @@
+# cheso-cli
+
+Use [Cheso](https://cheso.ai) from a terminal or a coding agent (Claude Code, Codex, Cursor ...): research reports
+with citations, PPT decks, web pages, posters, whiteboards, videos, images, document analysis, translation and
+format conversion. Tasks run on Cheso with your own account and credits; result files are downloaded to your
+working directory.
+
+## Install
+
+```bash
+uv tool install cheso-cli        # or: pipx install cheso-cli
+cheso login                      # opens the Cheso sign-in page in your browser; click Allow
+cheso skill install              # teaches Claude Code and Codex how to use Cheso
+```
+
+Requires Python 3.10+. For the China site (zhishi.qq.com) log in with `cheso login --site cn`; later commands use
+the site you logged in to last unless you pass `--site` / `--base-url` or set `CHESO_BASE_URL`.
+
+Then ask your agent, for example: "Use Cheso to turn ./notes.pdf into a 10-slide PPT". Or run it yourself:
+
+```bash
+cheso task create --file ./notes.pdf --prompt "Make a 10-slide investor deck in English" --wait
+```
+
+## Login
+
+`cheso login` uses OAuth 2.1 (authorization code + PKCE) with a loopback redirect: the CLI listens once on
+`http://127.0.0.1:<random port>/callback`, opens the Cheso authorization page, and stores the tokens after you
+approve. `--no-browser` only prints the URL; `--port N` fixes the port (for SSH port forwarding:
+`ssh -L N:127.0.0.1:N host`, then open the URL locally). The browser must reach the loopback port of the machine
+running `cheso`.
+
+Without a browser or a reachable loopback port (SSH sessions, containers, cloud agents), use
+`cheso login --device` (OAuth device authorization grant, RFC 8628): it prints a Cheso page and a short code; open
+the page on any device, sign in to Cheso, enter the code and click Allow. The CLI polls until you approve (every
+5 s, up to `--timeout`, the code itself is valid for 10 minutes). Coding agents split it into two commands that
+return quickly: `cheso login --device --no-wait --json` prints the page and code; `cheso login --wait --json` keeps
+waiting and can be run again (exit 6 while still waiting). Only enter a code that you started yourself: whoever
+approves it lets that CLI act as them.
+
+- Tokens are stored in `$XDG_CONFIG_HOME/cheso/credentials.json` (default `~/.config/cheso/`), one entry per site,
+  readable only by you (file 0600, directory 0700), replaced atomically.
+- Access tokens are refreshed automatically shortly before they expire, and once more if the server rejects one.
+  Refresh tokens rotate and the server revokes the login if an old one is reused, so refreshes are serialized with a
+  lock file (`credentials.json.lock`): parallel `cheso` commands share one refresh.
+- `cheso logout` revokes the authorization on the server and deletes the local tokens. You can also revoke the CLI
+  on the Cheso website under Authorized apps.
+- Token precedence: `--token` > `CHESO_API_TOKEN` > stored login. For CI and scripts, set `CHESO_API_TOKEN` to a
+  personal Cheso API token; nothing is written to disk.
+
+## Commands
+
+Add `--json` to any command for one JSON document on stdout (progress and warnings go to stderr). Global options
+(`--site`, `--base-url`, `--token`, `--json`) may come before or after the command.
+
+| Command | What it does |
+|---|---|
+| `cheso login [--no-browser] [--port N] [--timeout S]` | Sign in with the browser |
+| `cheso login --device [--no-wait] [--timeout S]` | Sign in with a code entered on any device (no browser or loopback needed here) |
+| `cheso login --wait [--timeout S]` | Keep waiting for a sign-in started with `--device --no-wait` |
+| `cheso logout` | Revoke the login and delete stored tokens |
+| `cheso whoami` | Show the account and where the token comes from |
+| `cheso credits` | Show available credits |
+| `cheso task create --prompt TEXT [--file PATH ...] [--file-id ID ...] [--project ID] [--agent-type cheso\|image_edit] [--wait] [--timeout S] [--output-dir DIR]` | Start a task; checks credits first; `--file` uploads local files; `--wait` waits and downloads the results |
+| `cheso task wait ID [--timeout S] [--output-dir DIR] [--no-download]` | Wait for a task (`plan_...`), conversion (`cvt_...`) or translation (`tlj_...`), polling every 3 s and following hand-offs to follow-up tasks; downloads the results |
+| `cheso task get ID` | Show status, answer, files or the pending question (no download) |
+| `cheso task reply ID [--answer "QUESTION=ANSWER" ...] [--skip]` | Answer the question a task is asking (also `N=ANSWER` by number) |
+| `cheso task cancel ID` | Stop a running task |
+| `cheso file upload PATH [--project ID]` | Upload a file; prints its `file_id` |
+| `cheso file list --project ID` | List a project's files |
+| `cheso file download FILE_ID [--version N] [--output-dir DIR]` | Download a file (the latest version by default) |
+| `cheso convert FILE_ID --to TYPE [--wait] [--timeout S] [--output-dir DIR]` | Convert a file (e.g. md to pdf/docx, vppt to pptx/pdf, vmotion to mp4); unsupported targets list the valid ones |
+| `cheso translate FILE_ID --to LANG [--from LANG] [--wait] [--timeout S] [--output-dir DIR]` | Translate a document (zh, zh-Hant, en, ko, ja, es, fr, ar, ru, pt, de, th) |
+| `cheso skill install [--target claude\|codex\|all] [--project] [--force]` | Install the Agent Skill |
+| `cheso skill show` | Print the bundled SKILL.md |
+
+Downloads never overwrite: an existing `report.pdf` makes the new file `report (1).pdf`. The default `--timeout`
+is 1800 s, counted from the start of the command and covering the result downloads too: no request starts after it
+and each one gets at most the time left (uploads and starting the task are not cut short). When it passes the task
+keeps running on Cheso and `cheso task wait ID` picks it up again.
+
+The low-level API commands of the first version (`profile`, `project ...`, `session create`, `plan create|get`)
+are still available and print raw JSON.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | Error |
+| 2 | Usage error (bad flags, unsupported conversion target) |
+| 3 | The task is waiting for your answer: `cheso task reply` |
+| 4 | Login required: `cheso login` or `cheso login --device` (or the token in `CHESO_API_TOKEN` / `--token` was rejected) |
+| 5 | Not enough credits (the JSON error carries `topup_url`) |
+| 6 | Still running when `--timeout` passed: run `cheso task wait ID` again (for `cheso login --device`: `cheso login --wait`) |
+| 7 | Rate limited or project busy; retry later (`retry_after`, `running_task_id` in the JSON error) |
+| 8 | The task succeeded, but some result files were not downloaded (`error.file_ids`); `next` downloads just those. A failed task keeps 1 or 5; its files that did not download carry `error` |
+
+## Agent Skill
+
+`cheso skill install` copies `SKILL.md` (shipped inside the package) to:
+
+| Target | User level (default) | `--project` |
+|---|---|---|
+| Claude Code | `~/.claude/skills/cheso/` | `./.claude/skills/cheso/` |
+| Codex | `~/.agents/skills/cheso/` | `./.agents/skills/cheso/` |
+
+An unchanged older copy is upgraded in place; a copy you edited is left alone unless you pass `--force`.
+
+## Privacy
+
+Files you upload and the tasks you start are stored in your Cheso account, in your projects, and use your credits.
+The CLI sends your token only to the Cheso site you chose; uploads and downloads to presigned storage URLs carry no
+token. Tokens are never printed.
+
+## Environment
+
+| Variable | Use |
+|---|---|
+| `CHESO_API_TOKEN` | Personal API token (CI, scripts); overrides the stored login |
+| `CHESO_BASE_URL` | Override the site URL (e.g. `https://testcheso.ai` for the test environment) |
+| `CHESO_DEV_SET` | **Test environment only.** Adds `X-Dev-Set: <value>` to Cheso requests to route them to a developer container; has no effect in production |
+| `XDG_CONFIG_HOME` | Where `cheso/credentials.json` lives |
+
+Site precedence: `--base-url` > `--site` > `CHESO_BASE_URL` > the site of the last `cheso login` > `https://cheso.ai`.
+Suggested commands (`next`, hints in messages) repeat the `--site` / `--base-url` you passed.
+
+## Development
+
+```bash
+cd clients/cli
+uv sync
+uv run --frozen pytest -q
+uvx ruff check . && uvx ruff format --check .   # uses the repository ruff.toml
+uv build                                          # wheel and sdist in dist/
+```
+
+System tests (case library, pools, runs, reports) live in [`../test-suite`](../test-suite) (`cheso-test`).

cheso_cli-0.2.0/pyproject.toml

@@ -0,0 +1,55 @@
+[project]
+name = "cheso-cli"
+version = "0.2.0"
+description = "Use Cheso from your terminal or coding agent: research reports, PPT, web pages, posters, videos, images, document translation and format conversion"
+readme = "README.md"
+requires-python = ">=3.10"
+keywords = [
+    "cheso",
+    "cli",
+    "ai-agent",
+    "agent-skills",
+    "claude-code",
+    "codex",
+    "ppt",
+    "research-report",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business",
+    "Topic :: Utilities",
+]
+dependencies = ["httpx>=0.28.1"]
+
+[[project.authors]]
+name = "cheso"
+email = "chesoai2026@gmail.com"
+
+[project.urls]
+Homepage = "https://cheso.ai"
+"Agent Skill" = "https://github.com/cheso-ai-platform/skills"
+
+[project.scripts]
+cheso = "cheso_cli.cli:main"
+cheso-cli = "cheso_cli.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.12.0,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["pytest>=9.1.1"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

cheso_cli-0.2.0/pyproject.toml.orig

@@ -0,0 +1,49 @@
+[project]
+name = "cheso-cli"
+version = "0.2.0"
+description = "Use Cheso from your terminal or coding agent: research reports, PPT, web pages, posters, videos, images, document translation and format conversion"
+readme = "README.md"
+authors = [
+    { name = "cheso", email = "chesoai2026@gmail.com" }
+]
+requires-python = ">=3.10"
+keywords = ["cheso", "cli", "ai-agent", "agent-skills", "claude-code", "codex", "ppt", "research-report"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "httpx>=0.28.1",
+]
+
+[project.urls]
+Homepage = "https://cheso.ai"
+"Agent Skill" = "https://github.com/cheso-ai-platform/skills"
+
+[project.scripts]
+cheso = "cheso_cli.cli:main"
+cheso-cli = "cheso_cli.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.12.0,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.1.1",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

cheso_cli-0.2.0/src/cheso_cli/__init__.py

@@ -0,0 +1,12 @@
+"""Cheso 命令行工具。"""
+
+from cheso_cli.config import VERSION as __version__
+
+__all__ = ["__version__", "main"]
+
+
+def main(argv: list[str] | None = None) -> None:
+    """命令行脚本入口（``cheso`` / ``cheso-cli``）。"""
+    from cheso_cli.cli import main as _main
+
+    _main(argv)

cheso_cli-0.2.0/src/cheso_cli/__main__.py

@@ -0,0 +1,5 @@
+"""模块启动入口：``python -m cheso_cli``。"""
+
+from cheso_cli.cli import main
+
+main()

cheso_cli-0.2.0/src/cheso_cli/auth.py

@@ -0,0 +1,128 @@
+"""决定命令使用哪个令牌，并在需要时刷新已保存的 OAuth 访问令牌。
+
+优先级：``--token`` > ``CHESO_API_TOKEN`` > ``cheso login`` 保存的凭据。
+
+刷新令牌每次使用后都会轮换；服务器再次收到已使用的刷新令牌时，会撤销整个授权。
+Agent 经常同时运行多个 ``cheso`` 命令，因此刷新操作始终持有凭据文件锁，并在拿到锁后重新读取文件。
+如果其他进程已经完成刷新，就使用其新访问令牌，避免用已经失效的刷新令牌再次刷新。
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from collections.abc import Callable, Mapping
+
+import httpx
+
+from cheso_cli.client import StaticToken, TokenSource
+from cheso_cli.config import DEFAULT_SITE, ENV_TOKEN, SITES, Settings
+from cheso_cli.credentials import CredentialStore, SiteCredentials
+from cheso_cli.errors import LoginRequired
+from cheso_cli.oauth import ERROR_INVALID_CLIENT, ERROR_INVALID_GRANT, OAuthClient, OAuthProtocolError
+
+# 访问令牌将在以下秒数内过期时提前刷新。
+REFRESH_SKEW_SECONDS = 60.0
+
+TOKEN_SOURCE_FLAG = "--token"
+TOKEN_SOURCE_ENV = ENV_TOKEN
+TOKEN_SOURCE_LOGIN = "login"
+
+
+def login_hint(settings: Settings) -> str:
+    """当前站点的登录命令，例如 ``cheso login --site cn``。"""
+    for name, url in SITES.items():
+        if settings.base_url == url:
+            return "cheso login" if name == DEFAULT_SITE else f"cheso login --site {name}"
+    return f"cheso login --base-url {settings.base_url}"
+
+
+class OAuthSession(TokenSource):
+    """从凭据文件读取访问令牌，需要时在文件锁内刷新。"""
+
+    def __init__(
+        self,
+        settings: Settings,
+        store: CredentialStore,
+        *,
+        transport: httpx.BaseTransport | None = None,
+        now: Callable[[], float] = time.time,
+    ) -> None:
+        self.settings = settings
+        self.store = store
+        self._transport = transport
+        self._now = now
+        self.refresh_count = 0
+
+    def _fresh(self, creds: SiteCredentials) -> bool:
+        return bool(creds.access_token) and creds.expires_at - self._now() > REFRESH_SKEW_SECONDS
+
+    def token(self) -> str:
+        creds = self.store.get(self.settings.base_url)
+        if not creds.logged_in:
+            raise self._login_required("Not logged in")
+        if self._fresh(creds):
+            return creds.access_token
+        return self._refresh(rejected=None)
+
+    def refresh_after_unauthorized(self, rejected: str) -> str | None:
+        return self._refresh(rejected=rejected)
+
+    def _refresh(self, *, rejected: str | None) -> str:
+        """在锁内刷新。``rejected`` 是服务器刚以 401 拒绝的访问令牌，没有时为空。"""
+        base = self.settings.base_url
+        with self.store.locked():
+            creds = self.store.get(base)
+            if not creds.logged_in:
+                raise self._login_required("Not logged in")
+            # 等待锁期间，其他进程可能已经刷新了令牌。
+            if self._fresh(creds) and creds.access_token != rejected:
+                return creds.access_token
+            if not creds.refresh_token or not creds.client_id:
+                creds.clear_tokens()
+                self.store.put(base, creds)
+                raise self._login_required("The login has expired")
+            with OAuthClient(self.settings, transport=self._transport, now=self._now) as oauth:
+                endpoint = creds.token_endpoint or oauth.metadata().token_endpoint
+                try:
+                    tokens = oauth.refresh(endpoint, client_id=creds.client_id, refresh_token=creds.refresh_token)
+                except OAuthProtocolError as e:
+                    if e.error not in (ERROR_INVALID_GRANT, ERROR_INVALID_CLIENT):
+                        raise
+                    creds.clear_tokens()
+                    if e.error == ERROR_INVALID_CLIENT:
+                        creds.client_id = ""
+                    self.store.put(base, creds)
+                    raise self._login_required("The login has expired or was revoked") from e
+            self.refresh_count += 1
+            creds.access_token = tokens.access_token
+            creds.refresh_token = tokens.refresh_token or creds.refresh_token
+            creds.expires_at = tokens.expires_at
+            creds.token_endpoint = endpoint
+            self.store.put(base, creds)
+            return creds.access_token
+
+    def _login_required(self, what: str) -> LoginRequired:
+        return LoginRequired(f"{what} for {self.settings.base_url}. Run `{login_hint(self.settings)}`.")
+
+
+def resolve_token_source(
+    settings: Settings,
+    store: CredentialStore,
+    *,
+    token_flag: str | None,
+    env: Mapping[str, str] | None = None,
+    transport: httpx.BaseTransport | None = None,
+    now: Callable[[], float] = time.time,
+) -> tuple[TokenSource, str]:
+    """返回令牌来源及其名称（``--token``、``CHESO_API_TOKEN`` 或 ``login``）。"""
+    env = os.environ if env is None else env
+    if token_flag:
+        return StaticToken(token_flag), TOKEN_SOURCE_FLAG
+    env_token = env.get(ENV_TOKEN, "").strip()
+    if env_token:
+        return StaticToken(env_token), TOKEN_SOURCE_ENV
+    creds = store.get(settings.base_url)
+    if not creds.logged_in:
+        raise LoginRequired(f"Not logged in to {settings.base_url}. Run `{login_hint(settings)}` (or set {ENV_TOKEN}).")
+    return OAuthSession(settings, store, transport=transport, now=now), TOKEN_SOURCE_LOGIN