增加「当前在线人数」估计

backend/api/client_activity.py

@@ -1,9 +1,15 @@
 from urllib.parse import unquote
 
+from backend.api.utils import request_has_valid_admin
 from backend.platform.access_log import log_request
+from backend.platform.online_presence import WINDOW_SEC, get_online_now, record_heartbeat
 from backend.platform.visit_stats import normalize_page_key, record_activity_report, record_gen_attr_opt_sec
 
 
+def _activity_response() -> dict:
+    return {"ok": True, "online_now": get_online_now(), "online_window_sec": WINDOW_SEC}
+
+
 def _sparse_page_activity_log_cum(cum: int) -> bool:
     """无服务端状态：累计秒为 2、10、20（前 20s 内与前端档位一致）或 40、80、160…（40·2^k）时打访问日志。"""
     if cum in (2, 10, 20):
@@ -21,13 +27,13 @@ def client_activity_report(activity_body=None):
         cum = int(d.get("total_active_sec"))
         dlt = int(d.get("delta_active_sec"))
         if not p or cum < 1 or dlt < 0:
-            return {"ok": True}
+            return _activity_response()
     except (TypeError, ValueError):
-        return {"ok": True}
+        return _activity_response()
     path_only = p.split("?", 1)[0].split("#", 1)[0].strip()
     page_key = path_only.rstrip("/").split("/")[-1] or path_only
     if not page_key:
-        return {"ok": True}
+        return _activity_response()
     if "?" in p:
         qs = p.split("?", 1)[1].split("#", 1)[0]
         log_path = f"{page_key}?{unquote(qs)}" if qs else page_key
@@ -36,17 +42,19 @@ def client_activity_report(activity_body=None):
 
     page_key = normalize_page_key(page_key)
 
-    raw_os = d.get("client_os")
-    client_os = str(raw_os).strip() if raw_os is not None else None
-
-    record_activity_report(page_key, dlt, cum, client_os)
-    if page_key == "causal_flow.html":
-        raw_opts = d.get("page_opts")
-        if isinstance(raw_opts, dict):
-            record_gen_attr_opt_sec(dlt, {k: bool(v) for k, v in raw_opts.items() if isinstance(k, str)})
-    if _sparse_page_activity_log_cum(cum):
-        log_request(
-            "📄 页面活跃",
-            f"path(sampled)={log_path!r} total_sec={cum} delta_sec={dlt}",
-        )
-    return {"ok": True}
+    if not request_has_valid_admin():
+        raw_os = d.get("client_os")
+        client_os = str(raw_os).strip() if raw_os is not None else None
+
+        record_heartbeat()
+        record_activity_report(page_key, dlt, cum, client_os)
+        if page_key == "causal_flow.html":
+            raw_opts = d.get("page_opts")
+            if isinstance(raw_opts, dict):
+                record_gen_attr_opt_sec(dlt, {k: bool(v) for k, v in raw_opts.items() if isinstance(k, str)})
+        if _sparse_page_activity_log_cum(cum):
+            log_request(
+                "📄 页面活跃",
+                f"path(sampled)={log_path!r} total_sec={cum} delta_sec={dlt}",
+            )
+    return _activity_response()

backend/platform/online_presence.py

@@ -0,0 +1,33 @@
+"""由 /api/client-activity 心跳估算当前在线（滑动窗口，无会话 ID）。"""
+
+import math
+import threading
+import time
+from collections import deque
+
+WINDOW_SEC = 20
+_HEARTBEAT_PERIOD_SEC = 10
+
+_LOCK = threading.Lock()
+_beats: deque[float] = deque()
+
+
+def record_heartbeat() -> None:
+    now = time.monotonic()
+    with _LOCK:
+        _beats.append(now)
+        _prune_locked(now)
+
+
+def get_online_now() -> int:
+    now = time.monotonic()
+    with _LOCK:
+        _prune_locked(now)
+        n = len(_beats)
+    return math.ceil(n * _HEARTBEAT_PERIOD_SEC / WINDOW_SEC)
+
+
+def _prune_locked(now: float) -> None:
+    cutoff = now - WINDOW_SEC
+    while _beats and _beats[0] < cutoff:
+        _beats.popleft()

backend/platform/visit_stats.py

@@ -515,8 +515,12 @@ def _merge_from_sample(s: dict) -> tuple[dict, dict, dict]:
 
 
 def get_stats_snapshot() -> dict:
+    from backend.platform.online_presence import WINDOW_SEC, get_online_now
+
     sample = _sample_locked_counters()
     public, _, _ = _merge_from_sample(sample)
+    public["online_now"] = get_online_now()
+    public["online_window_sec"] = WINDOW_SEC
     public["server_platform"] = _get_server_platform()
     public["startup_base"] = _startup_base
     if _process_start_at is not None:

client/src/analysis.html

@@ -21,9 +21,7 @@
                         <a href="index.html" class="home-link" title="Info Lens" data-i18n="text,title">Info Lens</a>
                         <a href="compare.html?showTextRender=1&demos=/quick-start-1.json,/quick-start-2.json" target="_blank" class="compare-link" style="display: none;" title="Compare analysis results" data-i18n="text,title">Compare results</a>
                         <div class="settings-menu-wrapper">
-                            <button id="settings_btn" class="settings-btn" title="Settings" data-i18n="title">
-                                <span class="settings-icon">⚙️</span>
-                            </button>
+                            <!-- INCLUDE partials/settings-toolbar-controls.html -->
                             <div id="settings_menu" class="settings-menu" style="display: none;">
                                 <!-- INCLUDE partials/settings-menu-analysis.html -->
                                 <!-- INCLUDE partials/settings-menu-common-mid.html -->

client/src/attribution.html

@@ -18,9 +18,7 @@
                     <div class="app-page-toolbar-actions">
                         <a href="index.html" class="home-link" title="Info Lens" data-i18n="text,title">Info Lens</a>
                         <div class="settings-menu-wrapper">
-                            <button id="settings_btn" class="settings-btn" title="Settings" data-i18n="title">
-                                <span class="settings-icon">⚙️</span>
-                            </button>
+                            <!-- INCLUDE partials/settings-toolbar-controls.html -->
                             <div id="settings_menu" class="settings-menu" style="display: none;">
                                 <!-- INCLUDE partials/settings-menu-common-mid.html -->
                                 <!-- INCLUDE partials/settings-menu-trailing-admin.html -->

client/src/causal_flow.html

@@ -18,9 +18,7 @@
                     <div class="app-page-toolbar-actions">
                         <a href="index.html" class="home-link" title="Info Lens" data-i18n="text,title">Info Lens</a>
                         <div class="settings-menu-wrapper">
-                            <button id="settings_btn" class="settings-btn" title="Settings" data-i18n="title">
-                                <span class="settings-icon">⚙️</span>
-                            </button>
+                            <!-- INCLUDE partials/settings-toolbar-controls.html -->
                             <div id="settings_menu" class="settings-menu" style="display: none;">
                                 <!-- INCLUDE partials/settings-menu-common-mid.html -->
                                 <!-- INCLUDE partials/settings-menu-trailing-admin.html -->

client/src/chat.html

@@ -18,9 +18,7 @@
                     <div class="app-page-toolbar-actions">
                         <a href="index.html" class="home-link" title="Info Lens" data-i18n="text,title">Info Lens</a>
                         <div class="settings-menu-wrapper">
-                            <button id="settings_btn" class="settings-btn" title="Settings" data-i18n="title">
-                                <span class="settings-icon">⚙️</span>
-                            </button>
+                            <!-- INCLUDE partials/settings-toolbar-controls.html -->
                             <div id="settings_menu" class="settings-menu" style="display: none;">
                                 <!-- INCLUDE partials/settings-menu-common-mid.html -->
                                 <!-- INCLUDE partials/settings-menu-trailing-admin.html -->

client/src/css/components/_settings-menu.scss

@@ -1,12 +1,37 @@
 // 设置菜单样式（Theme/Language 下拉等共用）
 .settings-menu-wrapper {
   position: relative;
-  display: inline-block;
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
   font-family: var(--font-family-ui);
   font-size: var(--font-size-base);
   line-height: 1.4;
 }
 
+.online-count {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 1px;
+  color: var(--text-muted, var(--text-color));
+  opacity: 0.85;
+  font-size: 11px;
+  line-height: 1.15;
+  user-select: none;
+}
+
+.online-count-label,
+.online-count-value {
+  white-space: nowrap;
+}
+
+.online-count-value {
+  font-variant-numeric: tabular-nums;
+  min-width: 1.5ch;
+  text-align: center;
+}
+
 .settings-btn {
   display: inline-flex;
   align-items: center;

client/src/index.html

@@ -13,9 +13,7 @@
 <body class="nav-landing-page">
 
     <div class="nav-landing-settings settings-menu-wrapper">
-        <button id="settings_btn" class="settings-btn" title="Settings" data-i18n="title">
-            <span class="settings-icon">⚙️</span>
-        </button>
+        <!-- INCLUDE partials/settings-toolbar-controls.html -->
         <div id="settings_menu" class="settings-menu" style="display: none;">
             <!-- INCLUDE partials/settings-menu-common-mid.html -->
             <!-- INCLUDE partials/settings-menu-trailing-admin.html -->

client/src/pages/analysis/index.ts

@@ -32,6 +32,7 @@ import {PANEL_SPLIT_STORAGE_KEY_START} from '../../shared/cross/panelSplitStorag
 import {handleServerDemoSave} from '../../shared/controllers/serverDemoController';
 // 公共初始化模块
 import {initializeCommonApp} from '../../shared/bootstrap';
+import { registerPageBusy } from '../../shared/core/activitySession';
 // 工具函数
 import {ensureJsonExtension} from '../../shared/cross/localFileUtils';
 import {extractErrorMessage} from '../../shared/core/errorUtils';
@@ -193,6 +194,10 @@ window.onload = () => {
         getSemanticSearchQuery: () => (document.getElementById('semantic_search_input') as HTMLInputElement | null)?.value ?? '',
         tr
     });
+    registerPageBusy(() => {
+        const s = appStateManager.getState();
+        return appStateManager.getIsAnalyzing() || s.isSemanticSearching;
+    });
 
     // 创建GLTR文本可视化实例
     const lmf = new GLTR_Text_Box(d3.select("#results"), eventHandler);

client/src/pages/attribution/index.ts

@@ -11,6 +11,7 @@ import { initChatPanelLayout } from '../../shared/ui/chat_panel_layout';
 import { PANEL_SPLIT_STORAGE_KEY_ATTRIBUTION } from '../../shared/cross/panelSplitStorage';
 import { TextInputController } from '../../shared/controllers/textInputController';
 import { initializeCommonApp } from '../../shared/bootstrap';
+import { registerPageBusy } from '../../shared/core/activitySession';
 import { showAlertDialog } from '../../shared/ui/dialog';
 import URLHandler from '../../shared/core/URLHandler';
 import { initCachedHistoryQueryDropdown, type CachedHistorySelectContext } from '../../shared/cross/cachedHistoryUi';
@@ -165,6 +166,8 @@ function setAnalyzeLoading(loading: boolean): void {
     syncAnalyzeButtonState();
 }
 
+registerPageBusy(() => analyzeInFlight);
+
 // input 事件同步按钮状态
 [contextField, targetField].forEach((field) => {
     (field.node() as HTMLTextAreaElement | null)?.addEventListener('input', syncAnalyzeButtonState);

client/src/pages/causal_flow/index.ts

@@ -11,6 +11,7 @@ import { initChatPanelLayout } from '../../shared/ui/chat_panel_layout';
 import { PANEL_SPLIT_STORAGE_KEY_GEN_ATTRIBUTE } from '../../shared/cross/panelSplitStorage';
 import { TextInputController } from '../../shared/controllers/textInputController';
 import { initializeCommonApp } from '../../shared/bootstrap';
+import { registerPageBusy } from '../../shared/core/activitySession';
 import { setPageOptsGetter } from '../../shared/core/clientActivityPing';
 import { showAlertDialog } from '../../shared/ui/dialog';
 import URLHandler from '../../shared/core/URLHandler';
@@ -1658,6 +1659,8 @@ function setGenLoading(loading: boolean): void {
     syncSubmitButtonState();
 }
 
+registerPageBusy(() => inFlight);
+
 /** 当前输入是否满足可以发起一次生成（不含 inFlight 判断）。 */
 function isInputReadyForRun(): boolean {
     const prompt = getActivePromptValue();

client/src/pages/chat/index.ts

@@ -12,6 +12,7 @@ import { initChatPanelLayout } from '../../shared/ui/chat_panel_layout';
 import { PANEL_SPLIT_STORAGE_KEY_CHAT } from '../../shared/cross/panelSplitStorage';
 import { TextInputController } from '../../shared/controllers/textInputController';
 import { initializeCommonApp } from '../../shared/bootstrap';
+import { registerPageBusy } from '../../shared/core/activitySession';
 import { showAlertDialog } from '../../shared/ui/dialog';
 import URLHandler from '../../shared/core/URLHandler';
 import { ToolTip } from '../../shared/vis/ToolTip';
@@ -489,6 +490,8 @@ const setAskLoading = (loading: boolean): void => {
     syncAskButtonState();
 };
 
+registerPageBusy(() => askInFlight);
+
 const runAsk = async (options?: { forceRefresh?: boolean }): Promise<void> => {
     const prompt = getActivePromptValue();
     if (askInFlight || prompt.length === 0) return;

client/src/partials/settings-toolbar-controls.html

@@ -0,0 +1,7 @@
+<span class="online-count" aria-label="Online users">
+    <span class="online-count-label">Online:</span>
+    <span id="online_count_value" class="online-count-value" aria-live="polite">—</span>
+</span>
+<button id="settings_btn" class="settings-btn" title="Settings" data-i18n="title">
+    <span class="settings-icon">⚙️</span>
+</button>

client/src/shared/api/GLTR_API.ts

@@ -235,9 +235,6 @@ export class TextAnalysisAPI {
         });
     }
 
-    /**
-     * 获取访问统计（管理员）
-     */
     public getVisitStats(): Promise<{
         success: boolean,
         totals: { page_loads: number, active_visits: number },
@@ -264,6 +261,8 @@ export class TextAnalysisAPI {
             gen_attr_opt_sec?: Record<string, number>,
         },
         reset_at?: string | null,
+        online_now?: number,
+        online_window_sec?: number,
     }> {
         return d3.json(this.baseURL + '/api/visit_stats', {
             headers: this.getHeaders()

client/src/shared/bootstrap.ts

@@ -9,6 +9,7 @@ import { TextAnalysisAPI } from './api/GLTR_API';
 import { initForceNarrowFromStorage } from './core/responsive';
 import { getTokenSurprisalColor, getByteSurprisalColor, HISTOGRAM_MIN_ALPHA } from './cross/SurprisalColorConfig';
 import { initClientActivityPing } from './core/clientActivityPing';
+import { initOnlineCountDisplay } from './cross/onlineCountDisplay';
 
 /**
  * 公共初始化返回对象
@@ -29,15 +30,18 @@ export interface CommonAppContext {
  */
 export function initializeCommonApp(apiPrefix: string = '', element?: Element): CommonAppContext {
     initForceNarrowFromStorage();
+    initOnlineCountDisplay();
     initClientActivityPing(apiPrefix);
 
+    const api = new TextAnalysisAPI(apiPrefix);
+
     // 使用传入的元素或默认 body 元素
     const targetElement = element || document.body;
     
     const format = d3.format('.2f');
     return {
         eventHandler: new SimpleEventHandler(targetElement),
-        api: new TextAnalysisAPI(apiPrefix),
+        api,
         tokenSurprisalColorScale: (v) => getTokenSurprisalColor(v, HISTOGRAM_MIN_ALPHA),
         byteSurprisalColorScale: (v) => getByteSurprisalColor(v, 1, HISTOGRAM_MIN_ALPHA),
         totalSurprisalFormat: (n: number | null) => n !== null && Number.isFinite(n) ? format(n) : String(n)

client/src/shared/core/activitySession.ts

@@ -0,0 +1,16 @@
+/**
+ * 各页入口注册 isBusy；心跳 tick 用 isSessionActive() = 可见 || getter()。
+ */
+
+let pageBusyGetter: (() => boolean) | undefined;
+
+export function registerPageBusy(getter: () => boolean): void {
+    pageBusyGetter = getter;
+}
+
+export function isSessionActive(): boolean {
+    if (typeof document !== 'undefined' && document.visibilityState === 'visible') {
+        return true;
+    }
+    return pageBusyGetter?.() ?? false;
+}

client/src/shared/core/clientActivityPing.ts

@@ -1,7 +1,13 @@
 import URLHandler from './URLHandler';
 import { AdminManager } from '../cross/adminManager';
+import { applyOnlineCount } from '../cross/onlineCountDisplay';
+import { isSessionActive } from './activitySession';
 
-const S = 10, FIRST = 2;
+/** 活跃秒采样间隔 */
+const TICK_MS = 1000;
+/** 上报档位：累计活跃秒达到这些值时 POST */
+const FIRST_REPORT_SEC = 2;
+const REPORT_INTERVAL_SEC = 10;
 
 let _pageOptsGetter: (() => Record<string, boolean>) | undefined;
 /** gen_attribute.html 等页面注册当前选项状态，供心跳上报时附带。 */
@@ -11,7 +17,7 @@ export function setPageOptsGetter(fn: () => Record<string, boolean>): void {
 
 export type ReportedClientOs = 'ios' | 'android' | 'windows' | 'macos' | 'linux' | 'unknown';
 
-/** UA 粗略归类；仅在首轮心跳（cum === FIRST）顺带上报一次。 */
+/** UA 粗略归类；仅在首轮心跳顺带上报一次。 */
 function detectInitialClientOs(): ReportedClientOs {
     const ua = typeof navigator !== 'undefined' ? navigator.userAgent || '' : '';
     if (/iPad|iPhone|iPod/i.test(ua)) return 'ios';
@@ -27,37 +33,64 @@ function detectInitialClientOs(): ReportedClientOs {
     return 'unknown';
 }
 
+function applyOnlineFromActivityResponse(r: Response): void {
+    const ct = r.headers.get('content-type') || '';
+    if (!ct.includes('application/json')) return;
+    void r
+        .clone()
+        .json()
+        .then((data: { online_now?: unknown }) => {
+            if (data && 'online_now' in data) applyOnlineCount(data.online_now);
+        })
+        .catch(() => {});
+}
+
+/** 累计活跃秒为 2、10、20… 时上报 */
+function shouldReportAtSec(totalActiveSec: number): boolean {
+    return totalActiveSec === FIRST_REPORT_SEC || totalActiveSec % REPORT_INTERVAL_SEC === 0;
+}
+
 export function initClientActivityPing(apiPrefix: string | null | undefined): void {
     if (typeof window === 'undefined') return;
-    if (AdminManager.getInstance().isInAdminMode()) return;
-    const u = `${apiPrefix || URLHandler.basicURL()}/api/client-activity`;
-    let n = 0, reportedTotal = 0, id: number | undefined;
-    const vis = () => document.visibilityState === 'visible';
-    const tick = () => {
-        if (!vis()) return;
-        n += 1;
-        if (n !== FIRST && n % S !== 0) return;
-        const cum = n;
-        const delta_active_sec = Math.max(cum - reportedTotal, 0);
+    const admin = AdminManager.getInstance();
+    const endpoint = `${apiPrefix || URLHandler.basicURL()}/api/client-activity`;
+    let totalActiveSec = 0;
+    let lastReportedSec = 0;
+
+    const postActivity = (includeClientOs: boolean) => {
+        const deltaActiveSec = Math.max(totalActiveSec - lastReportedSec, 0);
         const payload: Record<string, unknown> = {
             page_path: location.pathname + location.search,
-            total_active_sec: cum,
-            delta_active_sec,
+            total_active_sec: totalActiveSec,
+            delta_active_sec: deltaActiveSec,
         };
-        if (cum === FIRST) payload.client_os = detectInitialClientOs();
+        if (includeClientOs) payload.client_os = detectInitialClientOs();
         if (_pageOptsGetter) {
             const active = Object.fromEntries(Object.entries(_pageOptsGetter()).filter(([, v]) => v));
             if (Object.keys(active).length > 0) payload.page_opts = active;
         }
-        const body = JSON.stringify(payload);
-        void fetch(u, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body, keepalive: true })
-            .then((r) => { if (r.ok) reportedTotal = cum; })
+        const headers: Record<string, string> = { 'Content-Type': 'application/json' };
+        const adminToken = admin.isInAdminMode() ? admin.getAdminToken() : null;
+        if (adminToken) headers['X-Admin-Token'] = adminToken;
+        void fetch(endpoint, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(payload),
+            keepalive: true,
+        })
+            .then((r) => {
+                applyOnlineFromActivityResponse(r);
+                if (r.ok) lastReportedSec = totalActiveSec;
+            })
             .catch(() => {});
     };
-    const sync = () => {
-        if (id !== undefined) { clearInterval(id); id = undefined; }
-        if (vis()) id = window.setInterval(tick, 1000);
+
+    const tick = () => {
+        if (!isSessionActive()) return;
+        totalActiveSec += 1;
+        if (!shouldReportAtSec(totalActiveSec)) return;
+        postActivity(totalActiveSec === FIRST_REPORT_SEC);
     };
-    document.addEventListener('visibilitychange', sync);
-    sync();
+
+    window.setInterval(tick, TICK_MS);
 }

client/src/shared/cross/onlineCountDisplay.ts

@@ -0,0 +1,17 @@
+/**
+ * 页头在线人数（由 client-activity 响应更新 #online_count_value）
+ */
+
+const VALUE_ID = 'online_count_value';
+
+export function initOnlineCountDisplay(): void {
+    const el = document.getElementById(VALUE_ID);
+    if (el && !el.textContent?.trim()) el.textContent = '—';
+}
+
+export function applyOnlineCount(n: unknown): void {
+    const el = document.getElementById(VALUE_ID);
+    if (!el) return;
+    el.textContent =
+        typeof n === 'number' && Number.isFinite(n) ? String(n) : '—';
+}

client/src/shared/cross/visitStatsDialog.ts

@@ -130,6 +130,7 @@ function visitStatsHtml(data: VisitStatsRow): string {
         `[All-time (${g('+ delta since reset')})]`,
         `Page loads: ${fmtTotal(t.page_loads)}${deltaSuffix(t.page_loads - (sb.page_loads ?? 0))}`,
         `Active visits: ${fmtTotal(t.active_visits)}${deltaSuffix(t.active_visits - (sb.active_visits ?? 0))}`,
+        `Online: ${data.online_now ?? 'unknown'}`,
         '',
         '[OS]',
         ...linesJoined(orderedKeysGt0(OS_ORDER, os), os, sb.os ?? {}),

server.yaml

@@ -397,14 +397,20 @@ paths:
               client_os:
                 type: string
                 description: 首轮心跳附带；ios / android / windows / macos / linux / unknown
+            description: |
+              有效心跳计入访问统计与在线估计。请求头带有效 X-Admin-Token 时仅返回 online_now，不计入统计。
       responses:
         200:
-          description: acknowledged
+          description: acknowledged; includes estimated online_now after valid heartbeat
           schema:
             type: object
             properties:
               ok:
                 type: boolean
+              online_now:
+                type: integer
+              online_window_sec:
+                type: integer
 
   /check_admin:
     post:
@@ -863,6 +869,13 @@ paths:
                 type: string
                 description: |
                   最近一次手动 reset 的 UTC 时间；从未 reset 时为 null。
+              online_now:
+                type: integer
+                description: |
+                  最近 online_window_sec 内 client-activity 心跳数按每 10s 一次折算的当前在线估计（ceil）；进程内存，重启清零。
+              online_window_sec:
+                type: integer
+                description: 在线估计滑动窗口秒数（当前为 20）。
 
   /visit_stats/reset:
     post: