kimi-code-usage 0.1.4__tar.gz → 0.1.5__tar.gz

{kimi_code_usage-0.1.4 → kimi_code_usage-0.1.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kimi-code-usage
-Version: 0.1.4
+Version: 0.1.5
 Summary: A curated Kimi Coding Plan usage monitor with aesthetic CLI and MCP server.
 Project-URL: Homepage, https://github.com/Golden0Voyager/kimi-code-usage
 Project-URL: Repository, https://github.com/Golden0Voyager/kimi-code-usage

{kimi_code_usage-0.1.4 → kimi_code_usage-0.1.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kimi-code-usage"
-version = "0.1.4"
+version = "0.1.5"
 description = "A curated Kimi Coding Plan usage monitor with aesthetic CLI and MCP server."
 readme = "README.md"
 requires-python = ">=3.10"

{kimi_code_usage-0.1.4 → kimi_code_usage-0.1.5}/src/kimi_code_usage/main.py

@@ -11,7 +11,7 @@ from rich.live import Live
 from rich.panel import Panel
 from rich.text import Text
 
-from kimi_code_usage.config import AppConfig, ConfigResolver, save_theme
+from kimi_code_usage.config import DEFAULT_CONFIG_PATH, AppConfig, ConfigResolver, save_theme
 from kimi_code_usage.providers import DailyUsage, ProviderUsage, dispatch_all
 
 # --- i18n ---
@@ -42,6 +42,41 @@ L_ZH = {
 
 L = L_ZH if IS_ZH else L_EN
 
+_PROVIDER_SETUP_HELP = {
+    "kimi": {
+        "name": "Kimi Code",
+        "key_envs": ("KIMI_API_KEY", "KIMI_CODING_API_KEY"),
+        "base_env": "KIMI_BASE_URL",
+        "default_url": "https://api.kimi.com/coding/v1",
+        "note_en": "Use a Kimi Code / Coding Plan key (sk-kimi-...). Do not use https://api.moonshot.cn/v1.",
+        "note_zh": "使用 Kimi Code / Coding Plan 密钥（sk-kimi-...），不要使用 https://api.moonshot.cn/v1。",
+    },
+    "openai": {
+        "name": "OpenAI",
+        "key_envs": ("OPENAI_API_KEY",),
+        "base_env": "OPENAI_BASE_URL",
+        "default_url": "https://api.openai.com",
+        "note_en": "Use an OpenAI API key with organization usage access.",
+        "note_zh": "使用具备用量接口权限的 OpenAI API Key。",
+    },
+    "anthropic": {
+        "name": "Anthropic",
+        "key_envs": ("ANTHROPIC_API_KEY",),
+        "base_env": "ANTHROPIC_BASE_URL",
+        "default_url": "https://api.anthropic.com",
+        "note_en": "Use an Anthropic key that can access the usage endpoint.",
+        "note_zh": "使用具备用量接口权限的 Anthropic Key。",
+    },
+    "openrouter": {
+        "name": "OpenRouter",
+        "key_envs": ("OPENROUTER_API_KEY", "OPENROUTER_ADMIN_KEY"),
+        "base_env": "OPENROUTER_BASE_URL",
+        "default_url": "https://openrouter.ai/api",
+        "note_en": "Set OPENROUTER_MANAGEMENT_KEY or OPENROUTER_ADMIN_KEY for activity details.",
+        "note_zh": "如需活动明细，设置 OPENROUTER_MANAGEMENT_KEY 或 OPENROUTER_ADMIN_KEY。",
+    },
+}
+
 def _get_visual_width(s: str) -> int:
     import unicodedata
     width = 0
@@ -52,6 +87,14 @@ def _get_visual_width(s: str) -> int:
             width += 1
     return width
 
+
+def _mask_secret(secret: str | None) -> str:
+    if not secret:
+        return "missing"
+    if len(secret) <= 8:
+        return secret[:2] + "..."
+    return f"{secret[:7]}...{secret[-4:]}"
+
 def _get_localized_label(label: str, lang_zh: bool = IS_ZH) -> str:
     _L = L_ZH if lang_zh else L_EN
 
@@ -155,6 +198,117 @@ def _get_localized_text_value(text_val: str, lang_zh: bool) -> str:
 
     return text_val
 
+
+def _render_interactive_help(lang_zh: bool, or_metric: str = "requests", days_window: int = 30) -> Text:
+    text = Text()
+    title = "交互帮助" if lang_zh else "Interactive Help"
+    text.append(f"{title}\n\n", style="bold")
+    if lang_zh:
+        rows = [
+            ("q / Ctrl-C", "退出"),
+            ("r", "刷新用量"),
+            ("h / ?", "显示或隐藏帮助"),
+            ("c", "显示或隐藏配置引导"),
+            ("1-4", "切换服务商面板"),
+            ("l", "切换中英文"),
+            ("←/→ 或 [ / ]", "切换主题"),
+            ("m", f"切换 OpenRouter 指标（当前：{_metric_label(or_metric, True)}）"),
+            ("d", f"切换 OpenRouter 图表窗口（当前：{days_window}d）"),
+            ("Enter", "保存主题、语言、可见面板和 OpenRouter 显示偏好"),
+        ]
+        footer = "再次按 h/? 或 c 可回到用量视图。"
+    else:
+        rows = [
+            ("q / Ctrl-C", "quit"),
+            ("r", "refresh usage"),
+            ("h / ?", "show or hide help"),
+            ("c", "show or hide configuration guide"),
+            ("1-4", "toggle provider panels"),
+            ("l", "toggle language"),
+            ("←/→ or [ / ]", "cycle theme"),
+            ("m", f"cycle OpenRouter metric (current: {_metric_label(or_metric, False)})"),
+            ("d", f"cycle OpenRouter chart window (current: {days_window}d)"),
+            ("Enter", "save theme, language, visible panels, and OpenRouter display preferences"),
+        ]
+        footer = "Press h/? or c again to return to the usage view."
+
+    for key, desc in rows:
+        text.append(f"  {key:<16}", style="bold")
+        text.append(f"{desc}\n", style="grey62")
+    text.append(f"\n{footer}", style="grey62")
+    return text
+
+
+def _render_config_guide(
+    config: AppConfig,
+    lang_zh: bool = IS_ZH,
+    config_path: str | None = None,
+) -> Text:
+    text = Text()
+    title = "配置引导" if lang_zh else "Configuration Guide"
+    path = config_path or str(DEFAULT_CONFIG_PATH)
+    text.append(f"{title}\n\n", style="bold")
+    if lang_zh:
+        text.append(f"配置文件: {path}\n", style="grey62")
+        text.append("读取优先级: config.json > 环境变量 / 当前目录 .env > 默认 base URL\n\n", style="grey62")
+    else:
+        text.append(f"Config file: {path}\n", style="grey62")
+        text.append("Resolution order: config.json > environment variables / current .env > default base URL\n\n", style="grey62")
+
+    provider_order = list(config.provider_order)
+    for provider_name in _PROVIDER_SETUP_HELP:
+        if provider_name not in provider_order:
+            provider_order.append(provider_name)
+
+    for provider_name in provider_order:
+        help_info = _PROVIDER_SETUP_HELP.get(provider_name)
+        if not help_info:
+            continue
+        p_conf = config.providers.get(provider_name)
+        api_key = p_conf.api_key if p_conf else None
+        base_url = p_conf.base_url if p_conf and p_conf.base_url else help_info["default_url"]
+        enabled = p_conf.enabled if p_conf else True
+        status = "enabled" if api_key and enabled else ("disabled" if not enabled else "missing")
+        if lang_zh:
+            status_label = {"enabled": "已启用", "disabled": "已禁用", "missing": "缺少密钥"}[status]
+            text.append(f"{help_info['name']}\n", style="bold")
+            text.append(f"  状态: {status_label}\n", style="grey62")
+            text.append(f"  Key: {_mask_secret(api_key)}  ({' / '.join(help_info['key_envs'])})\n", style="grey62")
+            text.append(f"  Base URL: {base_url}  ({help_info['base_env']})\n", style="grey62")
+            text.append(f"  提示: {help_info['note_zh']}\n", style="grey62")
+        else:
+            text.append(f"{help_info['name']}\n", style="bold")
+            text.append(f"  status: {status}\n", style="grey62")
+            text.append(f"  key: {_mask_secret(api_key)}  ({' / '.join(help_info['key_envs'])})\n", style="grey62")
+            text.append(f"  baseUrl: {base_url}  ({help_info['base_env']})\n", style="grey62")
+            text.append(f"  note: {help_info['note_en']}\n", style="grey62")
+
+        if provider_name == "openrouter":
+            management_key = p_conf.management_key if p_conf else None
+            if lang_zh:
+                text.append(
+                    f"  管理 Key: {_mask_secret(management_key)}  (OPENROUTER_MANAGEMENT_KEY / OPENROUTER_ADMIN_KEY)\n",
+                    style="grey62",
+                )
+            else:
+                text.append(
+                    f"  management key: {_mask_secret(management_key)}  (OPENROUTER_MANAGEMENT_KEY / OPENROUTER_ADMIN_KEY)\n",
+                    style="grey62",
+                )
+        text.append("\n")
+
+    if lang_zh:
+        text.append(
+            "建议把长期配置写入 ~/.kimi-usage/config.json；uvx 每次运行都会读取这个文件。\n",
+            style="grey62",
+        )
+    else:
+        text.append(
+            "For persistent uvx usage, put long-lived settings in ~/.kimi-usage/config.json.\n",
+            style="grey62",
+        )
+    return text
+
 # (typing already imported at top)
 
 THEME_MAP = {
@@ -824,7 +978,7 @@ def _format_aggregated_results(
     return result
 
 
-async def _interactive_mode(config: "AppConfig", initial_theme: str) -> None:
+async def _interactive_mode(config: "AppConfig", initial_theme: str, config_path: str | None = None) -> None:
     """Live Rich TUI with keyboard theme cycling and provider panel toggling.
 
     Keys:
@@ -860,6 +1014,7 @@ async def _interactive_mode(config: "AppConfig", initial_theme: str) -> None:
 
     or_metric: str = _parse_or_metric(config.or_metric)
     days_window: int = _parse_days_window(config.days_window)
+    current_view = "usage"
 
     saved_notice: list = [None]   # holds the saved theme name briefly, then None
 
@@ -871,7 +1026,12 @@ async def _interactive_mode(config: "AppConfig", initial_theme: str) -> None:
     def _build_panel() -> Panel:
         visible_order = [p for p in config.provider_order if p in visible_providers]
         _L = L_ZH if lang_zh else L_EN
-        body = _format_aggregated_results(results, errors, visible_order, themes[idx], lang_zh, enabled_providers=set(config.enabled_providers), or_metric=or_metric, days_window=days_window)
+        if current_view == "help":
+            body = _render_interactive_help(lang_zh, or_metric=or_metric, days_window=days_window)
+        elif current_view == "config":
+            body = _render_config_guide(config, lang_zh=lang_zh, config_path=config_path)
+        else:
+            body = _format_aggregated_results(results, errors, visible_order, themes[idx], lang_zh, enabled_providers=set(config.enabled_providers), or_metric=or_metric, days_window=days_window)
 
         top_bar = Text()
         # Provider toggles
@@ -894,6 +1054,8 @@ async def _interactive_mode(config: "AppConfig", initial_theme: str) -> None:
         bindings = [
             ("[q]", "退出" if lang_zh else "quit"),
             ("[r]", "刷新" if lang_zh else "refresh"),
+            ("[h/?]", "帮助" if lang_zh else "help"),
+            ("[c]", "配置" if lang_zh else "config"),
             ("[←/→]", "主题" if lang_zh else "theme"),
             ("[1-4]", "面板" if lang_zh else "panels"),
             ("[l]", "英" if lang_zh else "ZH"),
@@ -961,6 +1123,14 @@ async def _interactive_mode(config: "AppConfig", initial_theme: str) -> None:
 
                     if saved_notice[0]:     # clear notice on any new keypress
                         saved_notice[0] = None
+                    if ch in ('h', 'H', '?'):
+                        current_view = "usage" if current_view == "help" else "help"
+                        live.update(_build_panel())
+                        continue
+                    if ch in ('c', 'C'):
+                        current_view = "usage" if current_view == "config" else "config"
+                        live.update(_build_panel())
+                        continue
                     if ch in ('\r', '\n'):  # Enter → save settings to config file
                         save_theme(
                             themes[idx],
@@ -1011,7 +1181,7 @@ async def main():
     parser.add_argument("--json", action="store_true")
     parser.add_argument("--plain", action="store_true")
     parser.add_argument("-i", "--interactive", action="store_true",
-                        help="Interactive mode: ←/→ or [/] to cycle themes, r refresh, q quit")
+                        help="Interactive mode: h help, c config, ←/→ or [/] themes, r refresh, q quit")
     parser.add_argument("--provider", help="Comma-separated providers to query (kimi,openai,anthropic,openrouter)")
     parser.add_argument("--config", help="Custom configuration file path")
     parser.add_argument("--theme", help="Specify color theme: blue-dark, blue-light, sky-dark, salmon-dark, turquoise-dark, pink-light, violet-dark, amber-dark, mint-dark, monochrome, blind-deuteranopia, blind-tritanopia")
@@ -1034,7 +1204,7 @@ async def main():
 
     # Interactive mode: hand off to TUI loop (handles its own dispatch)
     if args.interactive:
-        await _interactive_mode(config, theme_name)
+        await _interactive_mode(config, theme_name, config_path=str(resolver.config_path))
         return
 
     results, errors = await dispatch_all(config)

{kimi_code_usage-0.1.4 → kimi_code_usage-0.1.5}/src/kimi_code_usage/providers/kimi.py

@@ -1,9 +1,8 @@
+import os
 from collections.abc import Mapping, Sequence
 from datetime import datetime, timedelta
 from typing import Any, cast
 
-import os
-
 import aiohttp
 
 from . import ProviderUsage
@@ -148,6 +147,12 @@ def _kimi_error_hint(status: int, zh: bool | None = None) -> str:
                 "  ▸ 如需获取正确的 Key，请前往 Kimi Code 控制台创建\n"
                 "  ▸ 环境变量：KIMI_API_KEY 或 KIMI_CODING_API_KEY"
             ),
+            404: (
+                "未找到 Kimi Code API 用量接口（404）。\n"
+                "  ▸ 请确认 KIMI_BASE_URL/baseUrl 是 https://api.kimi.com/coding/v1\n"
+                "  ▸ 请勿使用 Kimi 开放平台地址（https://api.moonshot.cn/v1 或 platform.kimi.com）\n"
+                "  ▸ 请确认 API Key 来自 Kimi Code 平台（Coding Plan），格式为 sk-kimi-xxx"
+            ),
             403: "Kimi Code API 拒绝访问（403），请检查 API Key 是否有权限访问用量接口。",
             429: "Kimi Code API 请求过于频繁（429），请稍后重试。",
         }
@@ -160,6 +165,12 @@ def _kimi_error_hint(status: int, zh: bool | None = None) -> str:
             "  ▸ Get the correct key from Kimi Code Console\n"
             "  ▸ Environment variables: KIMI_API_KEY or KIMI_CODING_API_KEY"
         ),
+        404: (
+            "Kimi Code API usage endpoint was not found (404).\n"
+            "  ▸ Make sure KIMI_BASE_URL/baseUrl is https://api.kimi.com/coding/v1\n"
+            "  ▸ Do NOT use the Kimi Open Platform base URL (https://api.moonshot.cn/v1 or platform.kimi.com)\n"
+            "  ▸ Make sure the API Key is from Kimi Code Platform (Coding Plan), format: sk-kimi-xxx"
+        ),
         403: "Kimi Code API access denied (403). Check if your API Key has permission to access the usage endpoint.",
         429: "Kimi Code API rate limited (429). Please retry later.",
     }
@@ -170,7 +181,9 @@ async def fetch_kimi_usage(api_key: str, base_url: str, management_key: str | No
     headers = _kimi_headers(api_key)
     async with aiohttp.ClientSession() as session:
         async with session.get(url, headers=headers) as resp:
-            if resp.status != 200:
+            if resp.status == 200:
+                payload = await resp.json()
+            elif resp.status == 404:
                 fallback_url = base_url.rstrip("/") + "/usage"
                 async with session.get(fallback_url, headers=headers) as f_resp:
                     if f_resp.status != 200:
@@ -179,7 +192,9 @@ async def fetch_kimi_usage(api_key: str, base_url: str, management_key: str | No
                         raise Exception(f"{hint}\n  Original: API Error {f_resp.status}: {text}")
                     payload = await f_resp.json()
             else:
-                payload = await resp.json()
+                text = await resp.text()
+                hint = _kimi_error_hint(resp.status)
+                raise Exception(f"{hint}\n  Original: API Error {resp.status}: {text}")
 
     summary, limits = _parse_usage_payload(payload)
     rows = ([summary] if summary else []) + limits

{kimi_code_usage-0.1.4 → kimi_code_usage-0.1.5}/tests/test_main.py

@@ -330,6 +330,16 @@ def _cfg_one_provider(m):
     return cfg
 
 
+def _panel_plain(panel):
+    parts = []
+    for item in getattr(panel.renderable, "renderables", []):
+        if hasattr(item, "plain"):
+            parts.append(item.plain)
+        else:
+            parts.append(str(item))
+    return "\n".join(parts)
+
+
 @pytest.mark.parametrize("keys,theme,live_update_min,dispatch_call_count,cfg_maker", [
     (["q"], "blue-dark", 1, 1, None),
     (["r", "q"], "blue-dark", 2, 2, None),
@@ -355,6 +365,62 @@ def test_interactive_mode_initializes_from_config(monkeypatch, language):
     _run_interactive_mode(monkeypatch, ["q"], cfg=cfg, live_update_min=1, dispatch_call_count=1)
 
 
+def test_render_config_guide_includes_supported_provider_setup():
+    from kimi_code_usage.config import AppConfig, ProviderConfig
+    from kimi_code_usage.main import _render_config_guide
+
+    cfg = AppConfig()
+    cfg.providers = {
+        "kimi": ProviderConfig(api_key="sk-kimi-1234567890", base_url="https://api.kimi.com/coding/v1"),
+        "openai": ProviderConfig(api_key="sk-openai-abcdef1234", base_url="https://api.openai.com"),
+        "anthropic": ProviderConfig(api_key=None, base_url="https://api.anthropic.com"),
+        "openrouter": ProviderConfig(api_key="sk-or-v1-abcdef1234", base_url="https://openrouter.ai/api", management_key="or-mgmt-1234"),
+    }
+    cfg.provider_order = ["kimi", "openai", "anthropic", "openrouter"]
+
+    text = _render_config_guide(cfg, lang_zh=False, config_path="/tmp/kimi-usage/config.json")
+    raw = text.plain
+
+    assert "/tmp/kimi-usage/config.json" in raw
+    assert "KIMI_API_KEY" in raw
+    assert "OPENAI_API_KEY" in raw
+    assert "ANTHROPIC_API_KEY" in raw
+    assert "OPENROUTER_API_KEY" in raw
+    assert "OPENROUTER_ADMIN_KEY" in raw
+    assert "OPENROUTER_MANAGEMENT_KEY" in raw
+    assert "https://api.kimi.com/coding/v1" in raw
+    assert "https://openrouter.ai/api" in raw
+    assert "https://api.moonshot.cn/v1" in raw
+    assert "sk-kimi" in raw
+    assert "sk-kimi-1234567890" not in raw
+    assert "or-mgmt-1234" not in raw
+    assert "missing" in raw
+
+
+@pytest.mark.asyncio
+async def test_interactive_mode_help_and_config_keys(monkeypatch):
+    _mock_terminal(monkeypatch)
+    mock_select, mock_read = _make_select_and_read(["h", "c", "q"])
+    import kimi_code_usage.main as main_mod
+    monkeypatch.setattr(main_mod._select_module, "select", mock_select)
+    monkeypatch.setattr(sys.stdin, "read", mock_read)
+
+    cfg = _make_interactive_config(monkeypatch)
+    mock_res = {"kimi": [ProviderUsage(provider="kimi", label="Weekly Usage", used=5, limit=100, remaining=95, percent=5, reset_at=None, unit="%")]}
+
+    with patch("kimi_code_usage.main.dispatch_all", AsyncMock(return_value=(mock_res, {}))):
+        with patch("kimi_code_usage.main.Live") as mock_live_cls:
+            mock_live = mock_live_cls.return_value.__enter__.return_value
+            await _interactive_mode(cfg, "blue-dark")
+
+    rendered = "\n".join(_panel_plain(call.args[0]) for call in mock_live.update.call_args_list)
+    assert "Interactive Help" in rendered
+    assert "Configuration Guide" in rendered
+    assert "OPENAI_API_KEY" in rendered
+    assert "ANTHROPIC_API_KEY" in rendered
+    assert "OPENROUTER_API_KEY" in rendered
+
+
 @pytest.mark.asyncio
 async def test_interactive_mode_lone_escape(monkeypatch):
     """A lone ESC with no follow-up → treated as unknown key (no-op), then q."""

{kimi_code_usage-0.1.4 → kimi_code_usage-0.1.5}/tests/test_provider_kimi.py

@@ -5,6 +5,7 @@ import pytest
 
 from kimi_code_usage.providers.kimi import (
     _get_reset_info,
+    _kimi_error_hint,
     _limit_label,
     _parse_usage_payload,
     _to_int,
@@ -25,6 +26,13 @@ from kimi_code_usage.providers.kimi import (
 def test_to_int(val, expected):
     assert _to_int(val) == expected
 
+def test_kimi_error_hint_404_explains_usage_endpoint_configuration():
+    hint = _kimi_error_hint(404, zh=False)
+    assert "usage endpoint" in hint
+    assert "https://api.kimi.com/coding/v1" in hint
+    assert "api.moonshot.cn" in hint
+    assert "sk-kimi" in hint
+
 # -- _get_reset_info --
 @pytest.mark.parametrize("key", ["resetTime", "reset_at", "reset_time"])
 def test_get_reset_info_iso_string(key):
@@ -188,6 +196,38 @@ async def test_fetch_kimi_usage_fallback():
         assert len(res) == 1
         assert res[0].used == 200.0
 
+@pytest.mark.asyncio
+async def test_fetch_kimi_usage_does_not_fallback_on_auth_error():
+    calls = []
+
+    def make_cm(status, text_data):
+        cm = AsyncMock()
+        cm.__aenter__ = AsyncMock(return_value=cm)
+        cm.__aexit__ = AsyncMock(return_value=None)
+        cm.status = status
+        cm.text = AsyncMock(return_value=text_data)
+        return cm
+
+    def mock_get(url, *a, **kw):
+        calls.append(url)
+        if len(calls) == 1:
+            return make_cm(401, '{"code":"unauthenticated"}')
+        return make_cm(404, '{"error":{"message":"The requested resource was not found","type":"resource_not_found_error"}}')
+
+    mock_session = AsyncMock()
+    mock_session.get = mock_get
+    mock_session.__aenter__ = AsyncMock(return_value=mock_session)
+    mock_session.__aexit__ = AsyncMock(return_value=None)
+
+    with patch('aiohttp.ClientSession', return_value=mock_session):
+        with pytest.raises(Exception) as exc:
+            await fetch_kimi_usage("test-key", "https://api.example.com/v1")
+
+    assert "401" in str(exc.value)
+    assert "unauthenticated" in str(exc.value)
+    assert "resource_not_found_error" not in str(exc.value)
+    assert calls == ["https://api.example.com/v1/usages"]
+
 @pytest.mark.asyncio
 async def test_fetch_kimi_usage_fallback_fails():
     def make_cm(status):

{kimi_code_usage-0.1.4 → kimi_code_usage-0.1.5}/uv.lock

@@ -1049,7 +1049,7 @@ wheels = [
 
 [[package]]
 name = "kimi-code-usage"
-version = "0.1.3"
+version = "0.1.5"
 source = { editable = "." }
 dependencies = [
     { name = "aiohttp" },