comate-cli 0.12.7b1__tar.gz → 0.12.8__tar.gz

{comate_cli-0.12.7b1 → comate_cli-0.12.8}/CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Added
 
+- `update --mirror <tag|url>`：这一次更新改用指定的 PyPI 包索引，查版本和装包都用它，不写入设置。tag 不分大小写：`pypi`、`tuna`、`aliyun`、`tencent`、`huawei`、`ustc`；也可以直接写 `http://` 或 `https://` 开头的 simple 地址（例 `--mirror=https://pypi.corp.example/simple`）。查版本读该索引的 simple 页（PEP 691 JSON 或 PEP 503 HTML），不用 `/pypi/<包名>/json`——阿里云、腾讯云、华为云没有这个接口；yanked 版本和预发布规则与原来一致。装包时 macOS/Linux 重装、Windows 旁装、Windows 手动修复命令都带 `--default-index <地址>`，简中用户的手动命令不再追加清华。输出多一行「使用包索引：<地址>」，四种语言齐全。值缺失、tag 不认识（会列出全部 tag）、`--mirror` 重复时退出码 2，不开始更新。白牌发行版自己管理更新源（如 hico），带 `--mirror` 时退出码 2 并说明原因。不带 `--mirror` 时行为不变：简中 locale 用清华，其他用 pypi.org。只改包索引，Python 下载镜像仍用 `UV_PYTHON_INSTALL_MIRROR` 环境变量。
 - `--disallowed-tools <names>` 启动参数：本次会话不把这些 tool 发给模型，子 agent 也拿不到（进入 SDK 的 `AgentConfig.disallowed_tools`）。名字逗号分隔，参数可重复，结果按出现顺序合并去重；只认精确名字，MCP tool 写 `mcp__<server>__<tool>`。TUI、`resume`、`--rpc-stdio`、`--rpc-ws`、`--rpc-relay` 都生效（RPC 下对整个进程生效）；`-p` 下与它自带的 `SendMessage` 取并集。以下情况都在启动前报错退出：值为空、含 `*`、写了 `Agent` 或 `Skill`（这两个去掉后会话无法创建）、内置名拼错或大小写不对（`mcp__` 开头的名字不检查，MCP 在启动后才连接）。`comate mcp serve` 不支持。
 - 运行中的 Bash 显示 Live Output Tail：模型调用的 Bash 运行时，底部 running-tool 面板每秒读取一次最近输出，在签名行与 Running 状态行之间显示最多 3 个非空行（第一行带 `⎿`），`\r` 覆写的进度条只显示最后一段；`!` 命令活动区从 5 行改为 3 行。两处共用同一套行处理：丢空行、长行按显示宽度截断加 `…` 不折行（中文 / emoji 占 2 列）。命令结束、ctrl+b 转后台或中断后尾部立即消失，不进滚动区；折叠的 Bash 与子 agent 的 Bash 不受影响。
 - Interpreter Migration（macOS/Linux）：CLI 不在 Python 3.12 上、并且没有待更新的新版本时，第一次启动在界面之前显示一行提示，之后的启动显示全屏提示，只有「立即迁移」和「跳过」。「立即迁移」把**当前版本**（`<包名>==<当前版本>`，带发行版的安装参数）用 `--python 3.12` 重装，成功后提示重启，本次启动停止；失败只显示一行原因（uv 输出的最后一行），继续在当前 Python 上进入界面。「跳过」不记住，下次启动再问。已经在 3.12、editable 安装、PATH 里没有 uv、Windows 都不提示；有待更新的新版本时只显示更新提示（接受更新会顺带迁移到 3.12）。文案四种语言齐全。
@@ -75,6 +76,7 @@
 
 ### Changed
 
+- Self-Update 不再把用户换到 Python 3.12：`comate update`、启动时的「立即更新」、Windows 旁装，以及 Windows 手动修复命令，uv 命令里的 `--python` 改为当前解释器的 `主版本.次版本`（例如在 3.13 上运行就带 `--python 3.13`），更新后留在原来的 Python 上。命令仍然带 `--python`，否则 `--force` 重装会漂到 uv 默认找到的解释器上。不在 `requires-python` 范围内的解释器（例如 3.14）也照样保持。白牌发行版在 `install_args` 里自己指定了 `--python` 时仍以白牌为准，可以用它固定版本（例如 `"--python", "3.13.12"`）。决策见 ADR 0064。
 - 状态栏的 Job Indicator 只统计正在运行的后台 job：后台 subagent 跑完一轮进入待命（idle）后，不再显示 `x agent`；1 个运行中、2 个待命时显示 `1 agent`。待命的 agent 仍可在 `/ps` 里查看和停止，退出确认仍会提示它们（ADR 0050 补充）。
 - Self-Update 固定到 Python 3.12：`comate update`、启动时的「立即更新」、Windows 旁装，以及 Windows 自动路径不可用时显示的手动修复命令，都让新版本装在 Python 3.12 上（uv 命令带 `--python 3.12`；机器上没有 3.12 时 uv 会自动下载）。原因：uv 在读包之前就选好解释器，并且忽略 `requires-python` 的上限，所以以前用户会跑在 3.11 / 3.13 / 3.14 等不同版本上，而且不带 `--python` 的重装会把已经在 3.12 上的环境换成别的版本。白牌发行版在 `install_args` 里自己指定了 `--python` 时，以白牌的为准。`requires-python` 不变，3.11–3.13 继续支持。决策见 ADR 0055。
 - 简中用户更新时，uv 需要下载的 Python 改走国内镜像（npmmirror 的 python-build-standalone），不再依赖 GitHub；进程内重装和 Windows 旁装都生效。你自己设置了 `UV_PYTHON_INSTALL_MIRROR` 时以你的为准；其他语言环境不变。

{comate_cli-0.12.7b1 → comate_cli-0.12.8}/CONTEXT.md

@@ -212,6 +212,10 @@ _Avoid_: update check, update detection (plugin term), has-update probe
 Where a Version Check reads the newest version from: the public package index for the default distribution, or the whitelabel distribution's own index. It is derived from the distribution profile, never hard-coded.
 _Avoid_: registry, mirror (a mirror is one way to reach the same source)
 
+**Update Mirror**:
+A PyPI package index the user names for one `update` run (`--mirror <tag|url>`). It replaces the default Release Source for both the Version Check (read from the index's simple page) and the install of that run, and is never saved. Distributions with their own Release Source refuse it.
+_Avoid_: Python download mirror (that is `UV_PYTHON_INSTALL_MIRROR`), update source setting
+
 **Side-Install**:
 Installing a new CLI version into its own version-isolated location without touching the currently running installation. Used where the running installation cannot be rebuilt in place.
 _Avoid_: in-place upgrade, reinstall, versioned install
@@ -389,7 +393,7 @@ _Avoid_: lag log, profiler output (the profiler records phase durations, not a s
 - **Self-Update** and **Plugin Auto Update** are separate concepts with separate vocabularies: a **Version Check** orders versions, plugin **Update Detection** only compares for equality. Neither triggers the other.
 - A **Side-Install** followed by an **Entrypoint Flip** is one Self-Update strategy; an in-process reinstall of the current installation is another. Which one applies is a property of the platform, not of the user's choice.
 - **Restart-to-Apply** holds for every Self-Update strategy and mirrors the plugin **Update Effectiveness Boundary**: on-disk state changes, the running process does not.
-- **Self-Update** is the only way an installation reaches the target Python (3.12, ADR 0055). A CLI that runs on another interpreter stays there until its next Self-Update.
+- **Self-Update** keeps the installation on the interpreter it runs on: every uv install command requests the running `major.minor` (ADR 0064), unless the distribution profile's `install_args` already pins `--python`. There is no target Python; a CLI moves to another interpreter only when a whitelabel pin asks for it.
 
 - A **Session Title** is a fact of the session, not of the **Session Report**: it exists whether or not a report backend is configured, and the report only mirrors it. **Durable Title Completion** is therefore judged from the session's own metadata.
 - A **Session Title** is generated from the session's earliest **Committed Title Input**, never from the latest one. A resumed session without a title is titled from its original first input, so the title does not change to whatever was typed after resume.

{comate_cli-0.12.7b1 → comate_cli-0.12.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: comate-cli
-Version: 0.12.7b1
+Version: 0.12.8
 Summary: Comate terminal CLI built on comate-agent-sdk
 Project-URL: Homepage, https://github.com/AndyLee1024/agent-sdk
 Project-URL: Repository, https://github.com/AndyLee1024/agent-sdk

{comate_cli-0.12.7b1 → comate_cli-0.12.8}/comate_cli/main.py

@@ -317,6 +317,9 @@ class _ShutdownNoiseGuard:
 
 
 def _usage_text(command_name: str = "comate") -> str:
+    # 懒导入：usage 只在 --help 与参数错误时生成，不让启动路径多 import 更新模块。
+    from comate_cli.update_cli import UPDATE_MIRROR_TAGS
+
     return (
         "Usage:\n"
         f"  {command_name} [--rpc-stdio] [--add-dir <path>]...\n"
@@ -326,7 +329,7 @@ def _usage_text(command_name: str = "comate") -> str:
         f"  {command_name} -p [--output-format text|json] <prompt>\n"
         f"  {command_name} resume [<session_id>]\n"
         f"  {command_name} mcp <subcommand> [options]\n"
-        f"  {command_name} update [--pre]\n"
+        f"  {command_name} update [--pre] [--mirror <tag|url>]\n"
         "\n"
         f'MCP subcommands (run "{command_name} mcp <subcommand> --help" for details):\n'
         f"  add        Add an MCP server to {command_name}\n"
@@ -366,7 +369,10 @@ def _usage_text(command_name: str = "comate") -> str:
         "                     bypassPermissions; refused by default\n"
         "  --yolo             Start in bypassPermissions (YOLO) mode\n"
         "  --version, -V      Print version and exit\n"
-        "  --pre              (update) Also consider pre-release versions"
+        "  --pre              (update) Also consider pre-release versions\n"
+        "  --mirror <tag|url> (update) PyPI package index for this update only (not the Python\n"
+        "                     download mirror): an http(s):// URL or one of\n"
+        f"                     {', '.join(UPDATE_MIRROR_TAGS)}"
     )
 
 
@@ -881,19 +887,18 @@ def main(argv: list[str] | None = None, *, profile=None) -> None:
         return
 
     if run_argv and run_argv[0] == "update":
-        update_args = run_argv[1:]
-        include_prereleases = "--pre" in update_args
-        unknown = [arg for arg in update_args if arg != "--pre"]
-        if unknown:
-            sys.stderr.write(
-                f"update: unknown arguments: {' '.join(unknown)}\n"
-                f"{_usage_text(command_name=command_name)}\n"
-            )
-            raise SystemExit(2)
-        from comate_cli.update_cli import run_update_cli
+        from comate_cli.update_cli import UpdateArgumentError, parse_update_args, run_update_cli
+
+        try:
+            include_prereleases, index_url = parse_update_args(run_argv[1:])
+        except UpdateArgumentError as exc:
+            sys.stderr.write(f"update: {exc}\n{_usage_text(command_name=command_name)}\n")
+            raise SystemExit(2) from None
 
         raise SystemExit(
-            run_update_cli(profile=profile, include_prereleases=include_prereleases)
+            run_update_cli(
+                profile=profile, include_prereleases=include_prereleases, index_url=index_url
+            )
         )
 
     if run_argv and run_argv[0] == "mcp":

{comate_cli-0.12.7b1 → comate_cli-0.12.8}/comate_cli/terminal_agent/side_install.py

@@ -398,6 +398,7 @@ async def stage_update(
         _notify(progress, StagePhase.STAGING)
         # 延迟导入理由同 _staging_env：顶层互导会成环。
         from comate_cli.terminal_agent.update_check import (
+            default_index_args,
             index_strategy_fallback_args,
             python_request_args,
         )
@@ -414,6 +415,7 @@ async def stage_update(
             "--refresh",
             *python_request_args(target.install_args),
             *index_strategy_fallback_args(target.install_args),
+            *default_index_args(target.index_url),
             *target.install_args,
         )
         code, output = await run(

{comate_cli-0.12.7b1 → comate_cli-0.12.8}/comate_cli/terminal_agent/update_check.py

@@ -190,6 +190,9 @@ class UpdateTarget:
     install_args: tuple[str, ...] = ()
     command_name: str = "comate"
     python_install_mirror: str | None = None
+    # `<command> update --mirror` 指定的包索引（simple 地址）；只在这一次运行里有效。
+    # 设置后 Version Check 读它的 simple 页，三条安装路径都带 --default-index。
+    index_url: str | None = None
 
     def update_command(self, *, pin_version: str | None = None) -> tuple[str, ...]:
         """进程内重装命令（macOS/Linux 路径）。"""
@@ -205,6 +208,7 @@ class UpdateTarget:
             "--refresh",
             *python_request_args(self.install_args),
             *index_strategy_fallback_args(self.install_args),
+            *default_index_args(self.index_url),
             *self.install_args,
         )
 
@@ -274,6 +278,17 @@ def _pins_default_index(install_args: tuple[str, ...]) -> bool:
     return any(arg in _DEFAULT_INDEX_FLAGS for arg in install_args)
 
 
+def has_own_update_source(target: UpdateTarget) -> bool:
+    """白牌自己管理更新源（profile 查询源或 install_args 已设默认索引）：此时拒绝 --mirror。
+    uv 对重复的 --default-index 直接报错（实测 2026-11-06）。"""
+    return target.fetch_latest is not None or _pins_default_index(target.install_args)
+
+
+def default_index_args(index_url: str | None) -> tuple[str, ...]:
+    # 命令行的 --default-index 盖过子进程环境里注入的清华 UV_DEFAULT_INDEX（实测 2026-11-06）。
+    return ("--default-index", index_url) if index_url else ()
+
+
 def _install_spec(package: str, pin_version: str | None) -> str:
     """正式版沿用 `@latest`；目标是预发布版时精确 pin `==<version>`：`@latest`
     会解析到最新正式版，把 beta 用户降级（Q9 预发布规则的另一半）。
@@ -296,10 +311,15 @@ def index_strategy_fallback_args(install_args: tuple[str, ...]) -> tuple[str, ..
     return () if "--index-strategy" in install_args else _INDEX_STRATEGY_FALLBACK
 
 
-# CLI 的目标运行时（ADR 0055）。uv 在读包之前就选好 tool 环境的解释器，且忽略
-# requires-python 上限，所以只有命令里的 --python 能定运行时；实测 2026-11-02：
-# 不带它的 `--force` 重装把 3.12 环境重建到了 uv 默认找到的 3.13 上。
-TARGET_PYTHON = "3.12"
+def _running_python() -> str:
+    """当前进程解释器的 `主版本.次版本`：Self-Update 后保持在这个版本上（ADR 0064）。
+
+    uv 在读包之前就选好 tool 环境的解释器，且忽略 requires-python 上限，所以只有命令里的
+    --python 能定运行时；实测 2026-11-02：不带它的 `--force` 重装把 3.12 环境重建到了
+    uv 默认找到的 3.13 上。不带补丁号：当前解释器已在机器上，uv 不用下载。
+    """
+    major, minor = sys.version_info[:2]
+    return f"{major}.{minor}"
 
 
 def _pins_python(install_args: tuple[str, ...]) -> bool:
@@ -313,7 +333,7 @@ def _pins_python(install_args: tuple[str, ...]) -> bool:
 
 
 def python_request_args(install_args: tuple[str, ...]) -> tuple[str, ...]:
-    return () if _pins_python(install_args) else ("--python", TARGET_PYTHON)
+    return () if _pins_python(install_args) else ("--python", _running_python())
 
 
 def windows_update_command(
@@ -336,9 +356,15 @@ def windows_update_command(
         target.package,
         *python_request_args(target.install_args),
         *index_strategy_fallback_args(target.install_args),
+        *default_index_args(target.index_url),
         *target.install_args,
     ]
-    if _is_chinese_locale() and not _pins_default_index(target.install_args):
+    # 用户用 --mirror 指定了索引时不追加清华：uv 对重复的 --default-index 直接报错。
+    if (
+        _is_chinese_locale()
+        and target.index_url is None
+        and not _pins_default_index(target.install_args)
+    ):
         command += ["--default-index", TUNA_PYPI_INDEX]
     return tuple(command)
 
@@ -414,8 +440,9 @@ def _is_chinese_locale() -> bool:
 def uv_default_index_env(*, python_install_mirror: str | None = None) -> dict[str, str]:
     """uv 安装子进程的镜像环境变量。
 
-    简中 locale：包索引（清华）与 Python 下载镜像（npmmirror）。安装命令带 --python 3.12，
-    机器上没有 3.12 时 uv 默认从 GitHub 下载，国内可能慢或失败（ADR 0055 取舍四）。
+    简中 locale：包索引（清华）与 Python 下载镜像（npmmirror）。安装命令请求的 Python
+    （白牌在 install_args 里指定的版本）机器上没有时，uv 默认从 GitHub 下载，国内可能慢或
+    失败（ADR 0055 取舍四）。
     白牌镜像 `python_install_mirror` 不看 locale，并且盖过 npmmirror（ADR 0056）。
     调用方以 setdefault 语义合并，用户已显式设置的同名变量不覆盖。
     """
@@ -462,6 +489,125 @@ def pypi_json_source(
     return fetch
 
 
+# PEP 691 JSON 优先，退回 PEP 503 HTML。实测 2026-11-06：pypi.org / 清华 / 中科大回 JSON，
+# 阿里云 / 腾讯云 / 华为云只回 HTML；后三家的 `/pypi/<pkg>/json` 都是 404，所以 --mirror 不用 JSON API。
+_SIMPLE_INDEX_ACCEPT = "application/vnd.pypi.simple.v1+json, text/html;q=0.1"
+
+
+def simple_index_source(
+    package: str,
+    index_url: str,
+    *,
+    include_prereleases: bool = False,
+) -> LatestVersionFetcher:
+    """`--mirror` 的 Version Check：读 `<index_url>/<package>/`，从文件名取版本。"""
+
+    async def fetch() -> LatestRelease | None:
+        from packaging.utils import canonicalize_name
+
+        url = f"{index_url}/{canonicalize_name(package)}/"
+        files = await _fetch_simple_index_files(url, trust_env=_update_check_trust_env())
+        payload = _simple_index_payload(files, package)
+        latest = _select_latest_version(
+            payload,
+            current=installed_version(package),
+            include_prereleases=include_prereleases,
+        )
+        return LatestRelease(version=latest)
+
+    return fetch
+
+
+async def _fetch_simple_index_files(url: str, *, trust_env: bool) -> list[tuple[str, bool]]:
+    """返回 (文件名, 是否 yanked) 列表。网络/解析失败直接抛，由 `<command> update` 报「连不上」。"""
+    import httpx
+
+    client_kwargs: dict[str, Any] = {"timeout": 3.0, "trust_env": trust_env}
+    if not trust_env:
+        ssl_context = await _get_update_check_ssl_context_off_loop()
+        if ssl_context is None:
+            raise _UpdateCheckTransportUnavailable("update check SSL context is unavailable")
+        client_kwargs["verify"] = ssl_context
+    async with httpx.AsyncClient(**client_kwargs) as client:
+        resp = await client.get(
+            url, headers={"Accept": _SIMPLE_INDEX_ACCEPT}, follow_redirects=True
+        )
+        resp.raise_for_status()
+        if "application/vnd.pypi.simple.v1+json" in resp.headers.get("content-type", ""):
+            return [
+                (str(item["filename"]), bool(item.get("yanked")))
+                for item in resp.json()["files"]
+            ]
+        return _parse_simple_index_html(resp.text)
+
+
+def _parse_simple_index_html(text: str) -> list[tuple[str, bool]]:
+    """PEP 503：每个 `<a>` 的文本是文件名；有 `data-yanked` 属性即 yanked（PEP 592）。"""
+    from html.parser import HTMLParser
+
+    class _Links(HTMLParser):
+        def __init__(self) -> None:
+            super().__init__()
+            self.files: list[tuple[str, bool]] = []
+            self._open: tuple[bool, list[str]] | None = None
+
+        def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+            if tag == "a":
+                self._open = (any(name == "data-yanked" for name, _ in attrs), [])
+
+        def handle_data(self, data: str) -> None:
+            if self._open is not None:
+                self._open[1].append(data)
+
+        def handle_endtag(self, tag: str) -> None:
+            if tag == "a" and self._open is not None:
+                yanked, parts = self._open
+                self.files.append(("".join(parts).strip(), yanked))
+                self._open = None
+
+    parser = _Links()
+    parser.feed(text)
+    parser.close()
+    return parser.files
+
+
+def _simple_index_payload(files: list[tuple[str, bool]], package: str) -> dict[str, Any]:
+    """把文件列表整理成 PyPI JSON 的形状，交给 _select_latest_version 套用同一套预发布规则。
+
+    `info.version` 取最大的未 yanked 正式版（没有正式版时取最大的未 yanked 版本）；
+    一个版本的文件全部 yanked 才算 yanked，与 _select_latest_version 一致。
+    """
+    from packaging.utils import canonicalize_name, parse_sdist_filename, parse_wheel_filename
+    from packaging.version import Version
+
+    wanted = canonicalize_name(package)
+    releases: dict[str, list[dict[str, bool]]] = {}
+    for filename, yanked in files:
+        try:
+            if filename.endswith(".whl"):
+                name, version, _build, _tags = parse_wheel_filename(filename)
+            elif filename.endswith((".tar.gz", ".zip")):
+                name, version = parse_sdist_filename(filename)
+            else:
+                continue
+        except ValueError:
+            logger.debug("skipping unparsable index file name: %s", filename)
+            continue
+        if name != wanted:
+            continue
+        releases.setdefault(str(version), []).append({"yanked": yanked})
+
+    available = [
+        Version(raw)
+        for raw, entries in releases.items()
+        if not all(entry["yanked"] for entry in entries)
+    ]
+    if not available:
+        raise ValueError(f"no installable {package} versions on the index")
+    stable = [version for version in available if not version.is_prerelease]
+    return {"info": {"version": str(max(stable or available))}, "releases": releases}
+
+
 def _select_latest_version(
     payload: dict[str, Any],
     *,
@@ -595,6 +741,10 @@ async def fetch_latest_release(
     启动期 best-effort 语义。include_prereleases 只对 PyPI 源有意义：白牌
     profile 源只回一个版本号，没有预发布的概念。
     """
+    if target.index_url is not None:
+        return await simple_index_source(
+            target.package, target.index_url, include_prereleases=include_prereleases
+        )()
     profile_fetch_latest = target.fetch_latest
     if profile_fetch_latest is not None:
         return await _fetch_profile_latest_with_timeout(profile_fetch_latest)
@@ -673,6 +823,7 @@ def _target_for_info(info: UpdateInfo, target: UpdateTarget | None = None) -> Up
             install_args=target.install_args,
             command_name=target.command_name,
             python_install_mirror=target.python_install_mirror,
+            index_url=target.index_url,
         )
     return UpdateTarget(
         package=info.package,
@@ -1044,7 +1195,7 @@ async def run_update_command(
 def _write_plain_after_reinstall(console: Console, text: str) -> None:
     """成功重装之后写终端：不经过 Rich。
 
-    换解释器的重装（Self-Update 带 --python 3.12）会删掉旧的
+    换解释器的重装（例如白牌 install_args 指定了别的 --python）会删掉旧的
     lib/python3.X/site-packages，之后任何懒 import 都会 ModuleNotFoundError。Rich 渲染
     非 ASCII 字符时懒加载 rich._unicode_data：真机实测 2026-11-02，
     `comate update`（3.13 → 3.12）在打印成功文案时崩溃。

{comate_cli-0.12.7b1 → comate_cli-0.12.8}/comate_cli/terminal_agent/update_messages.py

@@ -44,6 +44,9 @@ class UpdateMessages:
     update_cli_unreachable: str
     update_cli_editable: str
     update_cli_uv_missing: str
+    # `<command> update --mirror`：这次运行用的包索引；白牌自管更新源时拒绝
+    update_cli_using_mirror: str
+    update_cli_mirror_unsupported: str
 
 
 _MESSAGES: dict[str, UpdateMessages] = {
@@ -107,6 +110,8 @@ _MESSAGES: dict[str, UpdateMessages] = {
             "uv was not found on PATH, so {product} cannot update itself. "
             "Install uv (https://docs.astral.sh/uv/) and run `{command}`."
         ),
+        update_cli_using_mirror="Using package index: {url}",
+        update_cli_mirror_unsupported="{product} uses its own update source, so --mirror is not supported.",
     ),
     "zh_cn": UpdateMessages(
         hint=(
@@ -163,6 +168,8 @@ _MESSAGES: dict[str, UpdateMessages] = {
             "PATH 上找不到 uv，{product} 无法自更新。"
             "请先安装 uv（https://docs.astral.sh/uv/），再运行 `{command}`。"
         ),
+        update_cli_using_mirror="使用包索引：{url}",
+        update_cli_mirror_unsupported="{product} 使用自己的更新源，不支持 --mirror。",
     ),
     "zh_tw": UpdateMessages(
         hint=(
@@ -219,6 +226,8 @@ _MESSAGES: dict[str, UpdateMessages] = {
             "PATH 上找不到 uv，{product} 無法自我更新。"
             "請先安裝 uv（https://docs.astral.sh/uv/），再執行 `{command}`。"
         ),
+        update_cli_using_mirror="使用套件索引：{url}",
+        update_cli_mirror_unsupported="{product} 使用自己的更新來源，不支援 --mirror。",
     ),
     "ja": UpdateMessages(
         hint=(
@@ -279,6 +288,8 @@ _MESSAGES: dict[str, UpdateMessages] = {
             "PATH に uv が見つからないため、{product} は自己更新できません。"
             "uv（https://docs.astral.sh/uv/）をインストールしてから `{command}` を実行してください。"
         ),
+        update_cli_using_mirror="使用するパッケージインデックス：{url}",
+        update_cli_mirror_unsupported="{product} は独自の更新元を使うため、--mirror は使えません。",
     ),
 }
 

{comate_cli-0.12.7b1 → comate_cli-0.12.8}/comate_cli/update_cli.py

@@ -2,13 +2,14 @@
 
 流程：安装方式探测 → Version Check → 打印结果 → 交给 update_check 的平台
 升级路径（macOS/Linux 进程内 uv 重装；Windows Side-Install + Entrypoint Flip）。
-退出码：0=成功或已最新，1=失败/无法检查/不支持，130=中断。
+退出码：0=成功或已最新，1=失败/无法检查/不支持，2=白牌不支持 --mirror，130=中断。
 所有用户可见文案来自 update_messages（四 locale），命令名/包名来自发行配置。
 """
 
 from __future__ import annotations
 
 import asyncio
+import dataclasses
 import logging
 from typing import TYPE_CHECKING
 
@@ -16,10 +17,12 @@ from rich.console import Console
 
 from comate_cli.terminal_agent import theme
 from comate_cli.terminal_agent.update_check import (
+    TUNA_PYPI_INDEX,
     InstallKind,
     UpdateInfo,
     detect_install_kind,
     fetch_latest_release,
+    has_own_update_source,
     installed_version,
     run_update_command,
     update_target_from_profile,
@@ -32,12 +35,82 @@ logger = logging.getLogger(__name__)
 
 # InstallKind / detect_install_kind 已搬到 update_check（启动期提示也要用），这里保留导入。
 
+# `--mirror <tag>` 可用的 PyPI 包索引（simple 地址）。2026-11-06 逐个实测都能返回 simple 页。
+UPDATE_MIRROR_TAGS: dict[str, str] = {
+    "pypi": "https://pypi.org/simple",
+    "tuna": TUNA_PYPI_INDEX,
+    "aliyun": "https://mirrors.aliyun.com/pypi/simple",
+    "tencent": "https://mirrors.cloud.tencent.com/pypi/simple",
+    "huawei": "https://repo.huaweicloud.com/repository/pypi/simple",
+    "ustc": "https://mirrors.ustc.edu.cn/pypi/simple",
+}
+
+
+class UpdateArgumentError(ValueError):
+    """`<command> update` 的参数不合法；main 打印原因与 usage 后以退出码 2 结束。"""
+
+
+def parse_update_args(args: list[str]) -> tuple[bool, str | None]:
+    """解析 `update [--pre] [--mirror <tag|url>]`，返回 (include_prereleases, index_url)。"""
+    include_prereleases = False
+    mirror_values: list[str] = []
+    unknown: list[str] = []
+    index = 0
+    while index < len(args):
+        arg = args[index]
+        if arg == "--pre":
+            include_prereleases = True
+        elif arg == "--mirror":
+            # 下一个参数缺失或是另一个 flag（例：`--mirror --pre`）都算没给值。
+            if index + 1 >= len(args) or args[index + 1].startswith("-"):
+                raise UpdateArgumentError("--mirror requires a value")
+            index += 1
+            mirror_values.append(args[index])
+        elif arg.startswith("--mirror="):
+            value = arg.split("=", 1)[1]
+            if not value.strip():
+                raise UpdateArgumentError("--mirror requires a value")
+            mirror_values.append(value)
+        else:
+            unknown.append(arg)
+        index += 1
+    if unknown:
+        raise UpdateArgumentError(f"unknown arguments: {' '.join(unknown)}")
+    if len(mirror_values) > 1:
+        raise UpdateArgumentError("--mirror can only be given once")
+    index_url = resolve_update_mirror(mirror_values[0]) if mirror_values else None
+    return include_prereleases, index_url
+
+
+def resolve_update_mirror(value: str) -> str:
+    """`http://` / `https://` 开头按 URL（去掉结尾 /），否则按 tag 查表（不分大小写）。"""
+    raw = value.strip()
+    if raw.lower().startswith(("http://", "https://")):
+        return raw.rstrip("/")
+    url = UPDATE_MIRROR_TAGS.get(raw.lower())
+    if url is None:
+        raise UpdateArgumentError(
+            f"unknown mirror {value!r}; use an http(s):// URL or one of: "
+            + ", ".join(UPDATE_MIRROR_TAGS)
+        )
+    return url
+
 
-def run_update_cli(*, profile: "DistributionProfile", include_prereleases: bool = False) -> int:
+def run_update_cli(
+    *,
+    profile: "DistributionProfile",
+    include_prereleases: bool = False,
+    index_url: str | None = None,
+) -> int:
     console = Console()
     try:
         return asyncio.run(
-            _run_update(profile=profile, console=console, include_prereleases=include_prereleases)
+            _run_update(
+                profile=profile,
+                console=console,
+                include_prereleases=include_prereleases,
+                index_url=index_url,
+            )
         )
     except KeyboardInterrupt:
         return 130
@@ -48,6 +121,7 @@ async def _run_update(
     profile: "DistributionProfile",
     console: Console,
     include_prereleases: bool = False,
+    index_url: str | None = None,
 ) -> int:
     from comate_cli.terminal_agent.update_messages import get_update_messages
     from packaging.version import InvalidVersion, Version
@@ -55,6 +129,16 @@ async def _run_update(
     target = update_target_from_profile(profile)
     messages = get_update_messages()
 
+    if index_url is not None:
+        if has_own_update_source(target):
+            console.print(
+                messages.update_cli_mirror_unsupported.format(product=target.product_label),
+                style=theme.ERROR,
+                markup=False,
+            )
+            return 2
+        target = dataclasses.replace(target, index_url=index_url)
+
     kind = detect_install_kind(target.package)
     if kind is InstallKind.EDITABLE:
         console.print(
@@ -74,6 +158,8 @@ async def _run_update(
         )
         return 1
 
+    if target.index_url is not None:
+        console.print(messages.update_cli_using_mirror.format(url=target.index_url), markup=False)
     console.print(messages.update_cli_checking, markup=False)
     current = installed_version(target.package)
     try:

{comate_cli-0.12.7b1 → comate_cli-0.12.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "comate-cli"
-version = "0.12.7b1"
+version = "0.12.8"
 description = "Comate terminal CLI built on comate-agent-sdk"
 readme = "README.md"
 requires-python = ">=3.11,<3.14"

{comate_cli-0.12.7b1 → comate_cli-0.12.8}/tests/test_side_install.py

@@ -12,6 +12,7 @@ Windows 独有的 OS 文件锁行为不进单测，归 tools/verify_windows_self
 from __future__ import annotations
 
 import os
+import sys
 import time
 import unittest
 from pathlib import Path
@@ -21,6 +22,9 @@ from unittest.mock import patch
 from comate_cli.terminal_agent import side_install as vi
 from comate_cli.terminal_agent.update_check import UpdateInfo, UpdateTarget
 
+# 旁装命令请求当前解释器的 主版本.次版本（ADR 0064）。
+_RUNNING_PYTHON = f"{sys.version_info.major}.{sys.version_info.minor}"
+
 
 def _target(**overrides) -> UpdateTarget:
     base = dict(
@@ -255,19 +259,36 @@ class _FakeUv:
 
 
 class TestStageUpdate(unittest.IsolatedAsyncioTestCase):
-    async def test_side_install_requests_target_python(self) -> None:
-        """Windows 的 Self-Update 也必须把新版本装到 3.12（ADR 0055）：旁装是全新的
-        tool 环境，不带 --python 时 uv 用它默认找到的解释器，Windows 用户就永远落不到 3.12。"""
-        with TemporaryDirectory() as tmp:
+    async def test_side_install_requests_running_python(self) -> None:
+        """Windows 的 Self-Update 也要把新版本装在当前解释器的 主版本.次版本上（ADR 0064）：
+        旁装是全新的 tool 环境，不带 --python 时 uv 用它默认找到的解释器，更新后就换了 Python。
+        伪造成 3.14（不在 requires-python 范围内）：改回固定版本或加范围判断，这里会失败。"""
+        with TemporaryDirectory() as tmp, patch(
+            "comate_cli.terminal_agent.update_check.sys.version_info", (3, 14, 2, "final", 0)
+        ):
             base = Path(tmp)
             fake = _FakeUv(base)
             await vi.stage_update(_info(), _target(), layout=_layout_for(base), run_command=fake)
             install_cmd, _ = fake.calls[0]
             self.assertIn("--python", install_cmd)
-            self.assertEqual(install_cmd[install_cmd.index("--python") + 1], "3.12")
+            self.assertEqual(install_cmd[install_cmd.index("--python") + 1], "3.14")
+
+    async def test_side_install_installs_from_update_mirror(self) -> None:
+        """`update --mirror`：Windows 旁装也要从查版本的那个索引装包，否则精确 pin 的版本
+        在 uv 的默认索引上可能还不存在（镜像落后时正是用户换镜像的原因）。"""
+        mirror = "https://mirrors.example/pypi/simple"
+        with TemporaryDirectory() as tmp:
+            base = Path(tmp)
+            fake = _FakeUv(base)
+            await vi.stage_update(
+                _info(), _target(install_args=(), index_url=mirror), layout=_layout_for(base), run_command=fake
+            )
+            install_cmd, _ = fake.calls[0]
+            defaults = [install_cmd[i + 1] for i, arg in enumerate(install_cmd) if arg == "--default-index"]
+            self.assertEqual(defaults, [mirror])
 
     async def test_zh_cn_side_install_downloads_python_through_mirror(self) -> None:
-        """旁装要求 3.12，机器上没有时 uv 从 GitHub 下载，国内可能失败（ADR 0055 取舍四）；
+        """旁装请求的 Python 机器上没有时 uv 从 GitHub 下载，国内可能失败（ADR 0055 取舍四）；
         用户自己设置的镜像必须保留。"""
         mirror = "https://registry.npmmirror.com/-/binary/python-build-standalone"
         own = "https://mirror.corp.example/python-build-standalone"
@@ -329,7 +350,7 @@ class TestStageUpdate(unittest.IsolatedAsyncioTestCase):
                     "uv", "tool", "install", "acme-cli==1.1.0",
                     "--refresh",
                     "--python",
-                    "3.12",
+                    _RUNNING_PYTHON,
                     "--index-strategy", "unsafe-first-match",
                     "--default-index", "https://pypi.example.com/simple",
                 ),