argo-search 1.0.1 → 2.9.8

package/scripts/browser_auth.py

@@ -0,0 +1,323 @@
+#!/usr/bin/env python3
+"""browser_auth.py — argo 自持浏览器登录态（持久 profile，A2 车道）
+
+落地方案：docs-local/连接器能力接入_方案调研_2026-09-26.md §4 方案 A 的 A2。
+
+模型（与既有凭据纪律对齐）：
+  - profile 是 argo 自持的独立 Chromium profile（不是用户主 Chrome），
+    落在状态根 browser-profiles/<site>/。
+  - cookie 只存在于 Chrome 自己的存储里（macOS Keychain / Windows DPAPI
+    加密），argo 全程不读取、不导出 cookie 值——比导出 state 文件再加密
+    （agent-browser --session 的做法）少一类落盘凭据。
+  - 抓取走 chrome_cdp 的「页面内带凭证 fetch」（fetch_json）：cookie 由
+    浏览器附加，argo 只收响应体。
+  - 登录态结果标 login_state_used=True / cache_eligible=False，
+    cache.assert_cacheable 据此拒绝进公共缓存。
+
+CLI（bin/argo 的 auth 子命令）：
+  argo auth login <url>     开可见窗口登录/扫码一次（Ctrl-C 放弃）
+  argo auth status          列出已登录站点
+  argo auth logout <site>   删除该站点 profile
+
+开关：ARGO_FETCH_AUTH=0 关闭抓取侧登录态车道；auth login/status/logout
+不受它管（用户显式管理自己的 profile 永远可用）。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shutil
+import sys
+import time
+from pathlib import Path
+
+ENV_AUTH_FETCH = "ARGO_AUTH_FETCH"
+
+# 备名：与抓取降级链分级开关家族（ARGO_FETCH_*）保持同族命名
+ENV_AUTH_FETCH_ALIAS = "ARGO_FETCH_AUTH"
+
+_HOST_RE = re.compile(r"[^a-z0-9.-]")
+
+
+def auth_fetch_enabled() -> bool:
+    """抓取侧登录态车道开关：ARGO_AUTH_FETCH / ARGO_FETCH_AUTH=0 关闭，默认开启。"""
+    for name in (ENV_AUTH_FETCH, ENV_AUTH_FETCH_ALIAS):
+        try:
+            from engine_env import get_env
+            val = get_env(name)
+        except ImportError:
+            val = os.environ.get(name, "")
+        if str(val).strip().lower() in ("0", "false", "no", "off"):
+            return False
+        if str(val).strip():
+            return True
+    return True
+
+
+def profile_root() -> Path:
+    """持久 profile 根目录：状态根/browser-profiles（ARGO_STATE_DIR 可整体隔离）。"""
+    from argo_paths import state_root
+    return state_root() / "browser-profiles"
+
+
+def site_host(url_or_host: str) -> str:
+    """URL 或主机名 → 站点身份（去 scheme/port/path，去 www.，小写）。
+
+    返回值直接用作 profile 目录名，所以顺带做文件名安全审查：
+    出现 [^a-z0-9.-]（路径穿越、空格、怪字符）或没有点（排除裸词）
+    一律拒绝。localhost 显式放行（本地开发站登录是真实场景）。
+    """
+    s = (url_or_host or "").strip()
+    if "://" in s:
+        s = s.split("://", 1)[1]
+    s = s.split("/", 1)[0].split("?", 1)[0].split("#", 1)[0]
+    if s.endswith(":80") or s.endswith(":443"):
+        s = s.rsplit(":", 1)[0]
+    if ":" in s:  # 带端口（或 IPv6 字面量）→ 取端口前段；IPv6 不支持，报错更诚实
+        head = s.split(":", 1)[0]
+        if not head:
+            raise ValueError(f"unsupported site: {url_or_host!r}")
+        s = head
+    s = s.lower()
+    if s.startswith("www."):
+        s = s[4:]
+    if not s or _HOST_RE.search(s):
+        raise ValueError(f"invalid site: {url_or_host!r}")
+    if s.startswith("."):  # "." / ".." / ".com"：点号打头做目录名就是穿越
+        raise ValueError(f"invalid site: {url_or_host!r}")
+    if "." not in s and s != "localhost":
+        raise ValueError(f"invalid site (no dot): {url_or_host!r}")
+    return s
+
+
+def _profile_dir(host: str) -> Path:
+    return profile_root() / host
+
+
+def _read_meta(d: Path) -> dict:
+    try:
+        return json.loads((d / "meta.json").read_text(encoding="utf-8"))
+    except Exception:
+        return {}
+
+
+def _write_meta(d: Path, host: str, created: str | None = None) -> None:
+    """原子写 meta.json：profile 的 argo 登记标记（Chrome 不认识也不在乎它）。"""
+    prev = _read_meta(d)
+    meta = {
+        "site": host,
+        "created": created or prev.get("created") or time.strftime("%Y-%m-%dT%H:%M:%S"),
+        "last_used": time.strftime("%Y-%m-%dT%H:%M:%S"),
+        "argo": "browser-profiles/v1",
+    }
+    tmp = d / f"meta.json.tmp.{os.getpid()}"
+    tmp.write_text(json.dumps(meta, ensure_ascii=False), encoding="utf-8")
+    os.replace(tmp, d / "meta.json")
+
+
+def profile_for(url_or_host: str) -> str | None:
+    """该站点的持久 profile 路径；没登录过（或站点名不合法）返回 None。
+
+    以 meta.json 存在为准：裸目录可能是上次登录失败的残骸，不能当登录态。
+    """
+    try:
+        host = site_host(url_or_host)
+    except ValueError:
+        return None
+    d = _profile_dir(host)
+    if d.is_dir() and (d / "meta.json").is_file():
+        return str(d)
+    return None
+
+
+def auth_profile_for_fetch(url_or_host: str,
+                           allow_browser_lane: bool = True) -> str | None:
+    """抓取侧入口：车道让路（开关关 / 调用方禁浏览器 / 未登录）→ None。
+
+    allow_browser_lane=False 对应 use_browser_fallback=False 的调用方
+    （批量爬取、evidence 核验等刻意无浏览器的路径）——登录态车道同样让路，
+    未认证不破默认路径的另一半。
+    """
+    if not allow_browser_lane or not auth_fetch_enabled():
+        return None
+    return profile_for(url_or_host)
+
+
+def login(url_or_host: str, chrome_path: str | None = None,
+          confirm=None) -> dict:
+    """开可见 Chrome 窗口让用户登录一次，profile 持久保存。
+
+    confirm：等待登录完成的钩子（None → 终端 input()）。可注入以便测试。
+    """
+    host = site_host(url_or_host)
+    d = _profile_dir(host)
+    fresh = not d.is_dir()
+    d.mkdir(parents=True, exist_ok=True)
+
+    target = url_or_host.strip()
+    if "://" not in target:
+        target = "https://" + target
+
+    from chrome_cdp import _ChromeProcess
+    proc = _ChromeProcess(chrome_path=chrome_path, headless=False,
+                          user_data_dir=str(d), start_url=target)
+    try:
+        proc.start()
+    except Exception as e:
+        # 新建 profile 时启动即败（占位 SingletonLock / 磁盘满等）→ 别留裸目录
+        if fresh:
+            shutil.rmtree(d, ignore_errors=True)
+        msg = str(e)
+        if "CDP failed to start" in msg or "Singleton" in msg:
+            msg += "（该 profile 可能已有 Chrome 在跑：关掉它或先 argo auth logout）"
+        return {"ok": False, "site": host, "error": msg[:200]}
+
+    try:
+        if confirm is None:
+            print(f"\n[{host}] 已在打开的 Chrome 窗口中登录/扫码。", file=sys.stderr)
+            print("完成后回到终端按 Enter 保存登录态（Ctrl-C 放弃）：", file=sys.stderr)
+            try:
+                input()
+            except EOFError:
+                return {"ok": False, "site": host,
+                        "error": "非交互终端无法确认登录完成（需要 tty）"}
+        else:
+            confirm()
+        _write_meta(d, host)
+        return {"ok": True, "site": host, "profile": str(d)}
+    finally:
+        try:
+            proc.stop()
+        except Exception:
+            pass
+
+
+def status() -> list[dict]:
+    """已登录站点清单（只读 meta，绝不触碰 profile 内的浏览器存储）。"""
+    root = profile_root()
+    if not root.is_dir():
+        return []
+    out = []
+    for d in sorted(root.iterdir()):
+        if not (d.is_dir() and (d / "meta.json").is_file()):
+            continue
+        m = _read_meta(d)
+        out.append({
+            "site": m.get("site") or d.name,
+            "created": m.get("created"),
+            "last_used": m.get("last_used"),
+            "path": str(d),
+        })
+    return out
+
+
+def logout(url_or_host: str) -> dict:
+    """删除站点 profile。Chrome 还开着该 profile 时拒绝（SingletonLock 探活）。"""
+    host = site_host(url_or_host)
+    d = _profile_dir(host)
+    if not d.is_dir():
+        return {"ok": False, "site": host, "error": f"no profile for {host}"}
+    lock = d / "SingletonLock"
+    if lock.is_symlink():
+        # Chrome 的 SingletonLock 是 hostname-PID 软链；PID 活着 → 别删活人脚下的地毯
+        pid = os.readlink(lock).rsplit("-", 1)[-1]
+        if pid.isdigit():
+            try:
+                os.kill(int(pid), 0)
+            except OSError:
+                pass  # 进程已死：锁是残骸，放行删除
+            else:
+                return {"ok": False, "site": host,
+                        "error": f"Chrome(pid {pid}) 正在使用该 profile，先关闭再 logout"}
+    shutil.rmtree(d)
+    return {"ok": True, "site": host}
+
+
+def touch(url_or_host: str) -> None:
+    """抓取命中登录态车道时更新 last_used（失败静默——只是观测字段）。"""
+    try:
+        host = site_host(url_or_host)
+        d = _profile_dir(host)
+        if d.is_dir() and (d / "meta.json").is_file():
+            _write_meta(d, host)
+    except Exception:
+        pass
+
+
+# ─── CLI（bin/argo 的 auth 子命令入口）──────────────────────────────────────
+
+def main(argv: list[str] | None = None) -> None:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    use_json = "--json" in argv
+    argv = [a for a in argv if a != "--json"]
+
+    if not argv or argv[0] in ("-h", "--help"):
+        print(__doc__.strip() or "argo auth — 浏览器登录态")
+        sys.exit(0 if argv else 1)
+
+    cmd, rest = argv[0], argv[1:]
+
+    def _emit_json(payload: dict) -> None:
+        # stdout 一律紧凑 JSON（context-budget 门禁：禁缩进 JSON / dumps_pretty）
+        try:
+            from cli_io import dumps
+            print(dumps(payload))
+        except ImportError:
+            print(json.dumps(payload, ensure_ascii=False))
+
+    if cmd == "login":
+        if not rest:
+            print("用法：argo auth login <url>（如 argo auth login https://example.com）",
+                  file=sys.stderr)
+            sys.exit(1)
+        chrome_path = None
+        if "--chrome-path" in rest:
+            i = rest.index("--chrome-path")
+            if i + 1 < len(rest):
+                chrome_path = rest[i + 1]
+                del rest[i:i + 2]
+        out = login(rest[0], chrome_path=chrome_path)
+        if use_json:
+            _emit_json(out)
+        elif out.get("ok"):
+            print(f"已保存 {out['site']} 的登录态（{out['profile']}）\n"
+                  f"之后 argo fetch 该站点自动带会话；argo auth status 可查看。")
+        else:
+            print(f"登录失败：{out.get('error')}", file=sys.stderr)
+        sys.exit(0 if out.get("ok") else 1)
+
+    if cmd == "status":
+        profiles = status()
+        if use_json:
+            _emit_json({"profiles": profiles})
+        elif not profiles:
+            print("（尚无已登录站点——argo auth login <url> 添加）")
+        else:
+            for p in profiles:
+                print(f"{p['site']}  建于 {p.get('created') or '?'}  "
+                      f"最近使用 {p.get('last_used') or '?'}")
+        sys.exit(0)
+
+    if cmd == "logout":
+        if not rest:
+            print("用法：argo auth logout <site>（站点见 argo auth status）",
+                  file=sys.stderr)
+            sys.exit(1)
+        out = logout(rest[0])
+        if use_json:
+            _emit_json(out)
+        elif out.get("ok"):
+            print(f"已删除 {out['site']} 的登录态 profile。")
+        else:
+            print(f"删除失败：{out.get('error')}", file=sys.stderr)
+        sys.exit(0 if out.get("ok") else 1)
+
+    print(f"Unknown auth subcommand: {cmd}（可用：login / status / logout）",
+          file=sys.stderr)
+    sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/scripts/budget.py

@@ -0,0 +1,247 @@
+#!/usr/bin/env python3
+"""budget.py — 按引擎的月度预算（原生币种）。
+
+为什么需要（2026-10-21）：`quota.py` 的额度是**次数**（limit/used），而付费引擎
+（DeepSeek、Tavily 等）的真实约束是**钱**。按次数换算会在单价变化时失真，也会
+把「失败调用」算成花费（DeepSeek 只对成功请求计费）。本模块只做三件事：
+
+1. 读取预算（默认 → 共享文件 → env 覆盖），不碰配额状态；
+2. 把预算挂到 `quota.py` 的 profile 上（budget_amount / budget_currency / period）；
+3. 提供 `argo budget set|list|unset` 的存储原语。
+
+存储位置：`~/.config/argo/budgets.json`（POSIX）或 `%APPDATA%\\argo\\budgets.json`
+（Windows），与 `~/.config/argo/env` 同根；`ARGO_BUDGET_FILE` 可覆盖（测试/多环境）。
+格式：
+
+    {"deepseek_search": {"amount": 5.0, "currency": "CNY", "period": "month"}}
+
+env 覆盖（优先级高于文件，便于插件/临时实验）：
+  - `ARGO_BUDGETS_JSON`：整份 JSON（最高）
+  - `ARGO_BUDGET_<ENGINE>`：单引擎金额（币种按引擎 cost_unit，缺省 CNY；周期 month）
+
+默认只给 DeepSeek 一个月度体验额度（¥5 ≈ 1000 次成功调用）；其他引擎默认不设，
+沿用各自 quota_profiles.json 里的既有额度，符合「其他默认不改」。
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+__all__ = [
+    "DEFAULT_BUDGETS",
+    "budget_file",
+    "budget_signature",
+    "load_budgets",
+    "budget_for",
+    "apply_to_profiles",
+    "set_budget",
+    "unset_budget",
+]
+
+# 默认预算：只覆盖 DeepSeek。金额按人民币；折算依据是官方 5 元/千次成功请求。
+DEFAULT_BUDGETS: dict[str, dict[str, Any]] = {
+    "deepseek_search": {"amount": 5.0, "currency": "CNY", "period": "month"},
+}
+
+_ENV_JSON = "ARGO_BUDGETS_JSON"
+_ENV_FILE = "ARGO_BUDGET_FILE"
+_ENV_PREFIX = "ARGO_" + "BUDGET_"
+
+# 单引擎 env 覆盖的默认币种（金额单位必须与引擎 cost_unit 对齐，否则预算
+# 与 cost_used 是两个币种在比大小）。未列出的引擎按 CNY，与历史行为一致。
+_ENV_CURRENCY = {
+    "deepseek_search": "CNY",
+    "exa": "USD",
+    "tavily": "USD",
+}
+
+
+def budget_file() -> Path:
+    """预算文件路径（不保证存在）。"""
+    override = (os.environ.get(_ENV_FILE) or "").strip()
+    if override:
+        return Path(os.path.expanduser(override))
+    if os.name == "nt":
+        base = (os.environ.get("APPDATA") or "").strip() or os.path.expanduser("~")
+    else:
+        base = (os.environ.get("XDG_CONFIG_HOME") or "").strip() or os.path.expanduser("~/.config")
+    return Path(base) / "argo" / "budgets.json"
+
+
+def _valid(entry: Any) -> dict[str, Any] | None:
+    """校验并归一一条预算；坏条目返回 None（不阻断其他引擎）。"""
+    if not isinstance(entry, dict):
+        return None
+    try:
+        amount = float(entry.get("amount"))
+    except (TypeError, ValueError):
+        return None
+    if amount < 0:
+        return None
+    currency = str(entry.get("currency") or "CNY").strip().upper() or "CNY"
+    period = str(entry.get("period") or "month").strip().lower()
+    if period not in ("day", "month"):
+        period = "month"
+    return {"amount": amount, "currency": currency, "period": period}
+
+
+def _read_file() -> dict[str, dict[str, Any]]:
+    try:
+        raw = json.loads(budget_file().read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return {}
+    if not isinstance(raw, dict):
+        return {}
+    out: dict[str, dict[str, Any]] = {}
+    for engine, entry in raw.items():
+        if str(engine).startswith("_"):
+            continue
+        norm = _valid(entry)
+        if norm is not None:
+            out[str(engine)] = norm
+    return out
+
+
+def _read_env() -> dict[str, dict[str, Any]]:
+    out: dict[str, dict[str, Any]] = {}
+    raw = (os.environ.get(_ENV_JSON) or "").strip()
+    if raw:
+        try:
+            parsed = json.loads(raw)
+        except ValueError:
+            parsed = None
+        if isinstance(parsed, dict):
+            for engine, entry in parsed.items():
+                norm = _valid(entry)
+                if norm is not None:
+                    out[str(engine)] = norm
+    # 单引擎便捷覆盖："ARGO_BUDGET_DEEPSEEK_SEARCH"=5 → deepseek_search 5 CNY/月。
+    # 同族命名 ARGO_BUDGET_<ENGINE> 由下面按前缀解析；字面量保留给插件门禁对拍。
+    # 只认「大写化后能在默认/文件里找到的引擎」太窄；这里按环境变量名反推引擎名，
+    # 由调用方（quota）决定是否真的存在该引擎，避免拼错静默生效。
+    for key, value in os.environ.items():
+        if not key.startswith(_ENV_PREFIX) or key in (_ENV_JSON, _ENV_FILE):
+            continue
+        engine = key[len(_ENV_PREFIX):].strip().lower()
+        if not engine:
+            continue
+        try:
+            amount = float(str(value).strip())
+        except (TypeError, ValueError):
+            continue
+        if amount < 0:
+            continue
+        currency = (out.get(engine) or {}).get("currency") \
+            or _ENV_CURRENCY.get(engine, "CNY")
+        entry = {"amount": amount, "currency": currency, "period": "month"}
+        out[engine] = entry
+    return out
+
+
+def budget_signature() -> tuple[Any, ...]:
+    """预算配置源的轻量签名（文件 mtime/size + 环境变量覆盖），供热读与路由缓存换键。"""
+    p = budget_file()
+    try:
+        st = p.stat()
+        f_sig: tuple[Any, ...] = (st.st_mtime_ns, st.st_size)
+    except OSError:
+        f_sig = (0, 0)
+    return (
+        f_sig,
+        os.environ.get(_ENV_JSON, ""),
+        os.environ.get("ARGO_BUDGET_DEEPSEEK_SEARCH", ""),
+        os.environ.get("ARGO_BUDGET_EXA", ""),
+    )
+
+
+def load_budgets() -> dict[str, dict[str, Any]]:
+    """默认 → 文件 → env，逐层覆盖。"""
+    merged: dict[str, dict[str, Any]] = {k: dict(v) for k, v in DEFAULT_BUDGETS.items()}
+    merged.update(_read_file())
+    merged.update(_read_env())
+    return merged
+
+
+def budget_for(engine: str) -> dict[str, Any] | None:
+    return load_budgets().get(str(engine))
+
+
+def apply_to_profiles(profiles: dict[str, dict[str, Any]]) -> None:
+    """把预算挂到 quota profile（就地）。只覆盖存在的引擎，拼错不生效。"""
+    active = load_budgets()
+    for engine, spec in profiles.items():
+        if not isinstance(spec, dict) or str(engine).startswith("_"):
+            continue
+        entry = active.get(engine)
+        if entry is not None:
+            spec["budget_amount"] = entry["amount"]
+            spec["budget_currency"] = entry["currency"]
+            # 预算周期即重置周期；与 limit 共用同一条 `period`，避免两套时钟。
+            spec["period"] = entry["period"]
+        else:
+            spec.pop("budget_amount", None)
+            spec.pop("budget_currency", None)
+
+
+def _write(data: dict[str, Any]) -> None:
+    path = budget_file()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(json.dumps(data, ensure_ascii=False, indent=2, sort_keys=True) + "\n",
+                   encoding="utf-8")
+    os.replace(tmp, path)
+
+
+def over_budget_error(engine: str) -> str | None:
+    """预算耗尽时返回可行动错误文本；未耗尽/未配预算/读失败返回 None。
+
+    放在 budget.py 而不是 dispatch：engine_dispatch 有行数门禁，预算检查是
+    「读状态 + 拼一句话」的纯策略，搬出来也让显式/自动路径共用同一文案。
+    """
+    try:
+        from engine_env import env_flag
+        if env_flag("ARGO_PAID_BUDGET_BYPASS", default=False):
+            return None
+    except Exception:
+        if (os.environ.get("ARGO_PAID_BUDGET_BYPASS", "").strip().lower()
+                in ("1", "true", "yes", "on")):
+            return None
+    try:
+        from quota import get_quota_manager
+        qm = get_quota_manager()
+        # 只认真正的 True：测试常把 quota manager 打成 MagicMock，属性调用
+        # 会返回真值 mock——不能把「mock 存在」当成预算耗尽。
+        if qm.is_over_budget(engine) is not True:
+            return None
+        st = (qm.budget_status(engine) if hasattr(qm, "budget_status")
+              else (qm.get_stats().get(engine) or {}))
+        return (f"本月预算已用完（{st.get('cost_used', 0)}/{st.get('budget')} "
+                f"{st.get('budget_currency') or ''}）；"
+                f"可用 ARGO_PAID_BUDGET_BYPASS=1 单次放行")
+    except Exception:
+        return None
+
+
+def set_budget(engine: str, amount: float, *, currency: str = "CNY",
+               period: str = "month") -> dict[str, Any]:
+    """写入一条预算（保留文件里其他引擎）。返回归一后的条目。"""
+    norm = _valid({"amount": amount, "currency": currency, "period": period})
+    if norm is None:
+        raise ValueError("预算金额必须是非负数")
+    data = _read_file()
+    data[str(engine)] = norm
+    _write(data)
+    return norm
+
+
+def unset_budget(engine: str) -> bool:
+    """删除一条预算；返回是否真的删了。"""
+    data = _read_file()
+    if engine not in data:
+        return False
+    data.pop(engine, None)
+    _write(data)
+    return True

package/scripts/budget_cli.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""budget_cli.py — `argo budget`：按引擎的月度预算读写口。
+
+用法：
+  argo budget list [--json]
+  argo budget set <engine> <amount> [--currency CNY|USD] [--period month|day]
+  argo budget unset <engine>
+
+预算存在 ~/.config/argo/budgets.json（`ARGO_BUDGET_FILE` 可覆盖）；`quota.py`
+启动时读取，按引擎原生币种与调用成本比较。默认只有 DeepSeek ¥5/月。
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+import budget
+from cli_io import dumps
+
+
+def _cmd_list(args: argparse.Namespace) -> int:
+    items = budget.load_budgets()
+    try:
+        from quota import get_quota_manager
+        stats = get_quota_manager().get_stats()
+    except Exception:
+        stats = {}
+    rows = []
+    for engine, entry in sorted(items.items()):
+        st = stats.get(engine) or {}
+        rows.append({
+            "engine": engine,
+            "amount": entry["amount"],
+            "currency": entry["currency"],
+            "period": entry["period"],
+            "cost_used": st.get("cost_used"),
+            "cost_per_call": st.get("cost_per_call"),
+            "available": st.get("available"),
+        })
+    if args.json:
+        print(dumps({"file": str(budget.budget_file()), "budgets": rows}))
+    else:
+        print(f"预算文件：{budget.budget_file()}")
+        if not rows:
+            print("（无预算；引擎沿用 quota_profiles.json 的次数额度）")
+        for r in rows:
+            print(f"  {r['engine']:<20} {r['amount']:>8.2f} {r['currency']}/"
+                  f"{r['period']}  已用 {r['cost_used']}  可用={r['available']}")
+    return 0
+
+
+def _cmd_set(args: argparse.Namespace) -> int:
+    try:
+        entry = budget.set_budget(args.engine, args.amount,
+                                  currency=args.currency,
+                                  period=args.period)
+    except ValueError as exc:
+        print(f"设置失败：{exc}", file=sys.stderr)
+        return 2
+    print(f"已设置 {args.engine}: {entry['amount']} {entry['currency']}/{entry['period']}"
+          f"（{budget.budget_file()}）")
+    return 0
+
+
+def _cmd_unset(args: argparse.Namespace) -> int:
+    ok = budget.unset_budget(args.engine)
+    print(("已删除 " if ok else "未找到 ") + args.engine)
+    return 0 if ok else 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="argo budget",
+                                 description="按引擎的月度预算（原生币种）")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+    p_list = sub.add_parser("list", help="列出预算与本月已用")
+    p_list.add_argument("--json", action="store_true")
+    p_list.set_defaults(func=_cmd_list)
+    p_set = sub.add_parser("set", help="设置某引擎预算")
+    p_set.add_argument("engine")
+    p_set.add_argument("amount", type=float)
+    p_set.add_argument("--currency", default="CNY")
+    p_set.add_argument("--period", default="month", choices=["day", "month"])
+    p_set.set_defaults(func=_cmd_set)
+    p_unset = sub.add_parser("unset", help="删除某引擎预算")
+    p_unset.add_argument("engine")
+    p_unset.set_defaults(func=_cmd_unset)
+    args = ap.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())