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

{kimi_code_usage-0.1.4 → kimi_code_usage-0.1.6}/.gitignore

@@ -44,3 +44,10 @@ vscode-extension/coverage/
 .vscode-test/
 **/*.js.map
 tokscale-export-*.json
+
+# Toolchain caches
+.ruff_cache/
+.mypy_cache/
+
+# Coverage
+htmlcov/

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kimi-code-usage
-Version: 0.1.4
+Version: 0.1.6
 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.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kimi-code-usage"
-version = "0.1.4"
+version = "0.1.6"
 description = "A curated Kimi Coding Plan usage monitor with aesthetic CLI and MCP server."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -59,6 +59,7 @@ ignore = ["E501", "SIM108", "SIM117", "UP035", "N806"]
 
 [tool.mypy]
 ignore_missing_imports = true
+files = ["src/kimi_code_usage/"]
 
 [tool.coverage.run]
 source = ["kimi_code_usage"]

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

@@ -11,8 +11,9 @@ 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.providers import DailyUsage, ProviderUsage, dispatch_all
+from kimi_code_usage.config import DEFAULT_CONFIG_PATH, AppConfig, ConfigResolver, save_theme
+from kimi_code_usage.providers import DailyUsage, ModelUsage, ProviderUsage, dispatch_all
+from kimi_code_usage.server import run_server
 
 # --- i18n ---
 LANG = os.getenv("LANG", "en")
@@ -42,6 +43,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 +88,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 +199,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 = {
@@ -403,7 +558,7 @@ def _render_activity_totals(totals, lang_zh: bool, theme: dict) -> Text:
     return text
 
 
-def _render_daily_chart(daily_activity, lang_zh: bool, theme: dict, metric: str = OR_METRIC_REQUESTS, days_window: int = 30) -> Text:
+def _render_daily_chart(daily_activity, lang_zh: bool, theme: dict, metric: str = OR_METRIC_REQUESTS, days_window: int = 30, color_map: dict[str, str] | None = None) -> Text:
     if not daily_activity:
         return Text()
     metric = _parse_or_metric(metric)
@@ -457,7 +612,16 @@ def _render_daily_chart(daily_activity, lang_zh: bool, theme: dict, metric: str
             model_totals_all[model.model] = model_totals_all.get(model.model, 0.0) + _metric_value_model(model, metric)
     top_models = _top_n_models(model_totals_all, top_models_limit)
     top_model_set = set(top_models)
-    others_color_idx = len(top_models) % len(_model_colors(theme))
+    # Build a color palette aligned to `top_models`, plus a trailing neutral color
+    # for the "others" bucket. When a shared color_map is supplied, colors are
+    # keyed by model name so this chart agrees with the Top Models chart.
+    _colors = _model_colors(theme)
+    if color_map is not None:
+        palette = [color_map.get(name, _colors[i % len(_colors)]) for i, name in enumerate(top_models)]
+    else:
+        palette = [_colors[i % len(_colors)] for i in range(len(top_models))]
+    palette.append(theme.get("meta", "grey62"))  # "others" bucket → neutral
+    others_color_idx = len(top_models)  # index of the "others" color in `palette`
 
     # Pre-compute each column as color indices (bottom -> top)
     columns: list[list[int | None]] = []
@@ -517,8 +681,6 @@ def _render_daily_chart(daily_activity, lang_zh: bool, theme: dict, metric: str
     filled_glyph = "▐" + "█" * (col_width - 1)
     empty_glyph = " " * col_width
 
-    colors = _model_colors(theme)
-
     # Render rows top -> bottom
     for row in range(height - 1, -1, -1):
         text.append(chart_indent, style=theme.get("meta", "grey62"))
@@ -535,7 +697,7 @@ def _render_daily_chart(daily_activity, lang_zh: bool, theme: dict, metric: str
         for col in columns:
             cidx = col[row]
             if cidx is not None:
-                color = colors[cidx % len(colors)]
+                color = palette[cidx]
                 text.append(filled_glyph, style=color)
             else:
                 text.append(empty_glyph)
@@ -586,7 +748,7 @@ def _render_daily_chart(daily_activity, lang_zh: bool, theme: dict, metric: str
         text.append("     ", style=theme.get("meta", "grey62"))
         for i, model in enumerate(top_models[:8]):
             name = truncate(_model_short_name(model), 14)
-            color = colors[i % len(colors)]
+            color = palette[i]
             text.append("█", style=color)
             text.append(f" {name}  ", style=theme.get("meta", "grey62"))
         text.append("\n")
@@ -609,6 +771,44 @@ def _model_colors(theme: dict) -> list[str]:
     ]
 
 
+def _build_model_color_map(model_names: list[str], theme: dict) -> dict[str, str]:
+    """Map each model name to a stable color so every panel colors it the same.
+
+    ``model_names`` is expected in canonical (metric-descending) order, so the
+    top-ranked model gets the first color. Colors cycle when there are more
+    models than palette entries.
+    """
+    colors = _model_colors(theme)
+    return {name: colors[i % len(colors)] for i, name in enumerate(model_names)}
+
+
+def _build_openrouter_color_map(rows, metric: str, theme: dict) -> dict[str, str] | None:
+    """Build one shared model→color map for an OpenRouter provider's rows.
+
+    The daily chart and the Top Models chart live in separate ``ProviderUsage``
+    rows but must agree on colors. We rank models by the currently displayed
+    metric (preferring the aggregate ``top_models`` row, else ``daily_activity``)
+    so the same model gets the same color in both. Returns ``None`` when the
+    rows carry no model breakdown (e.g. non-OpenRouter providers).
+    """
+    metric = _parse_or_metric(metric)
+    totals: dict[str, float] = {}
+    top_row = next((r for r in rows if r.top_models), None)
+    if top_row and top_row.top_models:
+        for m in top_row.top_models:
+            totals[m.model] = totals.get(m.model, 0.0) + _metric_value_model(m, metric)
+    else:
+        for row in rows:
+            if row.daily_activity:
+                for day in row.daily_activity:
+                    for m in day.models:
+                        totals[m.model] = totals.get(m.model, 0.0) + _metric_value_model(m, metric)
+    if not totals:
+        return None
+    ordered = [name for name, _ in sorted(totals.items(), key=lambda kv: (-kv[1], kv[0]))]
+    return _build_model_color_map(ordered, theme)
+
+
 def _top_n_models(model_totals: dict[str, float], n: int) -> list[str]:
     items = sorted(model_totals.items(), key=lambda x: (-x[1], x[0]))
     return [m for m, _ in items[:n]]
@@ -627,7 +827,54 @@ def truncate(s: str, max_len: int) -> str:
 
 
 
-def _render_top_models(top_models, lang_zh: bool, theme: dict, metric: str = OR_METRIC_REQUESTS, chart_width: int = 20) -> Text:
+def _window_top_models(daily_activity, days_window: int, metric: str) -> list[ModelUsage]:
+    """Rank models within the current [d] window, so Top Models tracks the Daily chart.
+
+    Mirrors the daily chart's window (a contiguous range of ``days_window`` days
+    ending at the latest activity date), aggregates each model's usage across those
+    days, and returns them ranked by ``metric`` descending. Returns an empty list
+    when there is no dated activity to window over.
+    """
+    if not daily_activity:
+        return []
+    from datetime import datetime, timedelta
+
+    metric = _parse_or_metric(metric)
+    days_window = _parse_days_window(days_window)
+    sorted_days = sorted(daily_activity, key=lambda d: d.date)
+    latest_date = datetime.strptime(sorted_days[-1].date[:10], "%Y-%m-%d")
+    start_date = latest_date - timedelta(days=days_window - 1)
+
+    agg: dict[str, ModelUsage] = {}
+    for day in sorted_days:
+        key = day.date[:10] if len(day.date) >= 10 else day.date
+        try:
+            day_date = datetime.strptime(key, "%Y-%m-%d")
+        except ValueError:
+            continue
+        if day_date < start_date or day_date > latest_date:
+            continue
+        for m in day.models:
+            existing = agg.get(m.model)
+            if existing is None:
+                agg[m.model] = ModelUsage(
+                    model=m.model,
+                    spend=m.spend,
+                    requests=m.requests,
+                    prompt_tokens=m.prompt_tokens,
+                    completion_tokens=m.completion_tokens,
+                    reasoning_tokens=m.reasoning_tokens,
+                )
+            else:
+                existing.spend += m.spend
+                existing.requests += m.requests
+                existing.prompt_tokens += m.prompt_tokens
+                existing.completion_tokens += m.completion_tokens
+                existing.reasoning_tokens += m.reasoning_tokens
+    return sorted(agg.values(), key=lambda m: (-_metric_value_model(m, metric), m.model))
+
+
+def _render_top_models(top_models, lang_zh: bool, theme: dict, metric: str = OR_METRIC_REQUESTS, chart_width: int = 20, color_map: dict[str, str] | None = None) -> Text:
     if not top_models:
         return Text()
     metric = _parse_or_metric(metric)
@@ -650,7 +897,7 @@ def _render_top_models(top_models, lang_zh: bool, theme: dict, metric: str = OR_
         name = _model_short_name(m.model)
         if len(name) > 22:
             name = name[:19] + "..."
-        color = colors[i % len(colors)]
+        color = color_map.get(m.model, colors[i % len(colors)]) if color_map else colors[i % len(colors)]
         text.append(f"    {name:22} ", style=theme.get("meta", "grey62"))
         text.append(f"{_format_metric_value(val, metric):>8}  ", style=theme.get("meta", "grey62"))
         text.append("█" * bar_len, style=color)
@@ -702,6 +949,11 @@ def _format_aggregated_results(
         bar_width = 20
 
         body_text = Text()
+        # Shared model→color map so the daily chart and Top Models agree on colors.
+        model_color_map = _build_openrouter_color_map(p_items, or_metric, theme)
+        # Top Models tracks the [d] window: recompute the ranking from the dated
+        # daily activity so switching the window updates it (consistent with the chart).
+        _daily_row = next((r for r in p_items if r.daily_activity), None)
         for i, row in enumerate(p_items):
             if i > 0:
                 body_text.append("\n")
@@ -717,11 +969,12 @@ def _format_aggregated_results(
                 if row.daily_activity:
                     if i > 0 or row.activity_totals:
                         body_text.append("\n")
-                    body_text.append(_render_daily_chart(row.daily_activity, lang_zh, theme, metric=or_metric, days_window=days_window))
+                    body_text.append(_render_daily_chart(row.daily_activity, lang_zh, theme, metric=or_metric, days_window=days_window, color_map=model_color_map))
                 if row.top_models:
                     if i > 0 or row.activity_totals or row.daily_activity:
                         body_text.append("\n")
-                    body_text.append(_render_top_models(row.top_models, lang_zh, theme, metric=or_metric, chart_width=20))
+                    _windowed = _window_top_models(_daily_row.daily_activity, days_window, or_metric) if _daily_row else []
+                    body_text.append(_render_top_models(_windowed or row.top_models, lang_zh, theme, metric=or_metric, chart_width=20, color_map=model_color_map))
                 continue
 
             loc_label = _get_localized_label(row.label, lang_zh)
@@ -824,7 +1077,36 @@ def _format_aggregated_results(
     return result
 
 
-async def _interactive_mode(config: "AppConfig", initial_theme: str) -> None:
+def _fit_scroll_body(body: Text, budget: int, scroll_offset: int, lang_zh: bool) -> tuple[Text, int]:
+    """Clamp a body ``Text`` to ``budget`` lines with an in-panel scroll offset.
+
+    Keeps the interactive panel within the terminal height so the control hint
+    bar is never cropped and Rich never has to scroll the screen (which would
+    duplicate the header). When the body overflows, returns the visible slice
+    plus a scroll-indicator line; otherwise returns the body unchanged. The
+    second return value is the clamped offset the caller should store back.
+    """
+    if budget < 1:
+        budget = 1
+    lines = body.split("\n")
+    total = len(lines)
+    if total <= budget:
+        return body, 0
+    view_rows = max(1, budget - 1)  # reserve one line for the scroll indicator
+    max_off = max(0, total - view_rows)
+    off = max(0, min(scroll_offset, max_off))
+    visible = list(lines[off:off + view_rows])
+    up = "▲" if off > 0 else "·"
+    down = "▼" if off + view_rows < total else "·"
+    label = "滚动" if lang_zh else "scroll"
+    indicator = Text(
+        f"  {up} {off + 1}–{min(off + view_rows, total)}/{total} {down}  [↑/↓ PgUp/PgDn {label}]",
+        style="dim",
+    )
+    return Text("\n").join([*visible, indicator]), off
+
+
+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,8 +1142,10 @@ 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
+    scroll: list = [0]            # in-panel vertical scroll offset (lines from top)
 
     _SHORT = {
         "anthropic": "Anthropic", "openai": "Openai",
@@ -871,7 +1155,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,8 +1183,11 @@ 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"),
+            ("[↑↓]", "滚动" if lang_zh else "scroll"),
             ("[l]", "英" if lang_zh else "ZH"),
             ("[m]", _metric_label(or_metric, lang_zh)),
             ("[d]", f"{days_window}d"),
@@ -910,6 +1202,19 @@ async def _interactive_mode(config: "AppConfig", initial_theme: str) -> None:
             hint.append(f"  ✓ {'已保存' if lang_zh else 'Saved'}: {saved_notice[0]}", style="bold green")
         hint.justify = "center"
 
+        # Keep top_bar and hint to a single line each so the fit math below is exact.
+        top_bar.no_wrap = True
+        top_bar.overflow = "ellipsis"
+        hint.no_wrap = True
+        hint.overflow = "ellipsis"
+
+        # Fit the body to the terminal so the hint bar is never cropped and Rich
+        # never scrolls the screen (which duplicates the header). Overhead:
+        # border(2) + padding(2) + top_bar(1) + gap(1) + hint(1) = 7 lines.
+        body_budget = max(3, console.size.height - 7)
+        if isinstance(body, Text):
+            body, scroll[0] = _fit_scroll_body(body, body_budget, scroll[0], lang_zh)
+
         panel_content = Group(
             top_bar,
             Text(""),
@@ -940,7 +1245,7 @@ async def _interactive_mode(config: "AppConfig", initial_theme: str) -> None:
         tty.setcbreak(fd)
         results, errors = await dispatch_all(config)
         console = Console()
-        with Live(_build_panel(), console=console, refresh_per_second=4) as live:
+        with Live(_build_panel(), console=console, auto_refresh=False, vertical_overflow="crop") as live:
             running = True
             while running:
                 rlist, _, _ = _select_module.select([sys.stdin], [], [], 0.15)
@@ -957,10 +1262,26 @@ async def _interactive_mode(config: "AppConfig", initial_theme: str) -> None:
                                 r3, _, _ = _select_module.select([sys.stdin], [], [], 0.05)
                                 if r3:
                                     ch3 = _read_char()
-                                    ch = f'\x1b[{ch3}'
+                                    if ch3.isdigit():
+                                        # CSI sequences like PgUp (\x1b[5~) / PgDn (\x1b[6~)
+                                        r4, _, _ = _select_module.select([sys.stdin], [], [], 0.05)
+                                        tilde = _read_char() if r4 else ""
+                                        ch = f'\x1b[{ch3}{tilde}'
+                                    else:
+                                        ch = f'\x1b[{ch3}'
 
                     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"
+                        scroll[0] = 0
+                        live.update(_build_panel(), refresh=True)
+                        continue
+                    if ch in ('c', 'C'):
+                        current_view = "usage" if current_view == "config" else "config"
+                        scroll[0] = 0
+                        live.update(_build_panel(), refresh=True)
+                        continue
                     if ch in ('\r', '\n'):  # Enter → save settings to config file
                         save_theme(
                             themes[idx],
@@ -970,7 +1291,7 @@ async def _interactive_mode(config: "AppConfig", initial_theme: str) -> None:
                             days_window=days_window
                         )
                         saved_notice[0] = themes[idx]
-                        live.update(_build_panel())
+                        live.update(_build_panel(), refresh=True)
                         # Flush any consecutive \r or \n (like \r\n from terminal)
                         while True:
                             r_extra, _, _ = _select_module.select([sys.stdin], [], [], 0.0)
@@ -980,11 +1301,25 @@ async def _interactive_mode(config: "AppConfig", initial_theme: str) -> None:
                                     continue
                             break
                         continue
+                    if ch == '\x1b[A':          # ↑ → scroll up
+                        scroll[0] = max(0, scroll[0] - 3)
+                        live.update(_build_panel(), refresh=True)
+                        continue
+                    if ch == '\x1b[B':          # ↓ → scroll down
+                        scroll[0] += 3
+                        live.update(_build_panel(), refresh=True)
+                        continue
+                    if ch in ('\x1b[5~', '\x1b[6~'):  # PgUp / PgDn → page scroll
+                        page = max(1, console.size.height - 8)
+                        scroll[0] = max(0, scroll[0] + (page if ch == '\x1b[6~' else -page))
+                        live.update(_build_panel(), refresh=True)
+                        continue
                     idx, quit_flag, refresh_flag, toggle_num, lang_toggle, metric_toggle, days_toggle = _handle_key(ch, idx, len(themes))
                     if quit_flag:
                         running = False
                     elif refresh_flag:
                         results, errors = await dispatch_all(config)
+                        scroll[0] = 0
                     elif toggle_num is not None:
                         providers = list(config.provider_order)
                         if toggle_num < len(providers):
@@ -999,7 +1334,7 @@ async def _interactive_mode(config: "AppConfig", initial_theme: str) -> None:
                         or_metric = _next_or_metric(or_metric)
                     elif days_toggle:
                         days_window = _next_days_window(days_window)
-                    live.update(_build_panel())
+                    live.update(_build_panel(), refresh=True)
                 await asyncio.sleep(0)
     finally:
         termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
@@ -1011,15 +1346,22 @@ 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")
+    parser.add_argument("--serve", action="store_true", help="Start web server instead of CLI output")
+    parser.add_argument("--port", type=int, default=8765, help="Web server port (default: 8765)")
     args = parser.parse_args()
 
     resolver = ConfigResolver(config_path=args.config)
     config = resolver.resolve()
 
+    # Serve mode: start web server
+    if args.serve:
+        await run_server(port=args.port, lang_zh=IS_ZH)
+        return
+
     # Determine theme
     theme_name = args.theme if args.theme else config.theme
 
@@ -1034,7 +1376,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)