feat(frontend): 状态栏展示 prompt 用量与上下文占比 / status bar prompt usage vs context cap

cursoragent · noisystreet · noisystreet · commit cddc28f0890c · 2026-05-16T11:57:01.000+08:00
Co-authored-by: Yales Peter &lt;noisystreet@users.noreply.github.com&gt;
diff --git a/README.md b/README.md
@@ -30,7 +30,7 @@
 ## 功能概览
 
 - **对话与工具**：OpenAI 兼容 `chat/completions`；内置文件/工作区、**`run_command`**（白名单；默认含 **`bash`/`sh`**，复合命令用 **`bash -c`/`sh -c`**）、HTTP/搜索、工作区**代码检索**（关键字 + 可选语义/向量）等；完整列表见 [docs/工具说明.md](docs/工具说明.md)。**`run_command`** 等子进程工具输出默认按 **`command_max_output_len`**（嵌入默认 **512KiB**，`CM_COMMAND_MAX_OUTPUT_LEN` 可覆盖）做字节截断，详见 **`config/tools.toml`** 与 [docs/配置说明.md](docs/配置说明.md)。
-- **Web UI**：侧栏会话与工作区；须**显式选择工作区**后工具与 **`@相对路径`** 才生效；浏览器内会话列表按**当前工作区根路径**分桶保存在 `localStorage`，切换工作区会加载该路径下曾保存的会话（未设置工作区前仍使用与旧版相同的默认键）。助手 **Markdown**；支持 **`@` 引用**、图片附件（须视觉模型）、会话导出等。全屏「设置」中 **「会话」** 页可切换本进程是否将服务端会话写入 SQLite（与配置文件中 **`conversation_store_sqlite_path`** 是否可启用一致；**重启 `serve`** 后仍以配置文件为准）。详细路由与行为见 [docs/命令行与路由.md](docs/命令行与路由.md)。
+- **Web UI**：侧栏会话与工作区；须**显式选择工作区**后工具与 **`@相对路径`** 才生效；浏览器内会话列表按**当前工作区根路径**分桶保存在 `localStorage`，切换工作区会加载该路径下曾保存的会话（未设置工作区前仍使用与旧版相同的默认键）。助手 **Markdown**；支持 **`@` 引用**、图片附件（须视觉模型）、会话导出等。与服务器会话同步后，底栏可显示当前消息的 **prompt** tiktoken 粗估用量及相对 **`llm_context_tokens`** 上限的占比（详见 `title` 提示）。全屏「设置」中 **「会话」** 页可切换本进程是否将服务端会话写入 SQLite（与配置文件中 **`conversation_store_sqlite_path`** 是否可启用一致；**重启 `serve`** 后仍以配置文件为准）。详细路由与行为见 [docs/命令行与路由.md](docs/命令行与路由.md)。
 - **终端**：**`repl`**（交互）、**`chat`**（单次）、**`serve`**（HTTP + 静态 UI）、**`tui`**（实验性**全屏**，须真实 TTY，见下文）。流式 **SSE**、工具审批与取消约定见 [docs/SSE协议.md](docs/SSE协议.md)。
 - **会话与导出**：嵌入默认在**当前工作区** **`.crabmate/conversations.db`** 持久化 **Web `serve`**（及配置了同路径的 **`tui`**）对话，**`serve` 重启**后仍可按 **`conversation_id`** 续聊；不需要时在配置里将 **`conversation_store_sqlite_path`** 置空。Web 或 CLI **`save-session`**（别名 **`export-session`**）导出 JSON/Markdown，形状见 [docs/命令行与路由.md](docs/命令行与路由.md)。
 - **进阶（默认不必读）**：分阶段规划时间线、澄清问卷、调试台 **`thinking_trace`**、长期记忆、活文档注入、**MCP**、工作区 **`plugins/*.json`** 等见 [docs/配置说明.md](docs/配置说明.md)、[docs/工具说明.md](docs/工具说明.md)。
diff --git a/frontend/src/app/app_signals/mod.rs b/frontend/src/app/app_signals/mod.rs
@@ -91,6 +91,7 @@ impl AppSignals {
             stream_last_sse_event_seq: RwSignal::new(0),
             reasoning_preserved: RwSignal::new(HashMap::new()),
             stream_text_overlay: RwSignal::new(None),
+            conversation_prompt_tokens: RwSignal::new(None),
         };
 
         Self {
diff --git a/frontend/src/app/chat/session_hydrate.rs b/frontend/src/app/chat/session_hydrate.rs
@@ -24,20 +24,11 @@ fn messages_contain_loading(messages: &[StoredMessage]) -> bool {
         .any(|m| m.state.as_ref().is_some_and(|s| s.is_loading()))
 }
 
-fn trimmed_server_conversation_id(session: &ChatSession) -> Option<&str> {
-    session
-        .server_conversation_id
-        .as_deref()
-        .map(str::trim)
-        .filter(|x| !x.is_empty())
-}
-
-/// 当前会话是否允许发起「拉取服务端消息」水合：已绑定 `conversation_id` 且无 `Loading` 占位。
 fn conversation_server_id_if_hydratable_for_wire(s: &ChatSession) -> Option<String> {
     if messages_contain_loading(&s.messages) {
         return None;
     }
-    trimmed_server_conversation_id(s).map(str::to_string)
+    s.trimmed_server_conversation_id().map(str::to_string)
 }
 
 /// 服务端快照中不存在的本地消息：工具卡与 TimelineLog，须保留并与快照合并。
@@ -112,7 +103,7 @@ fn try_hydration_merge_precheck(
     if messages_contain_loading(&session.messages) {
         return Err(SessionHydrationMergeOutcome::SkippedLoadingPlaceholders);
     }
-    let still = trimmed_server_conversation_id(session);
+    let still = session.trimmed_server_conversation_id();
     if still != Some(cid) {
         return Err(SessionHydrationMergeOutcome::SkippedConversationIdMismatch);
     }
@@ -260,7 +251,7 @@ pub(crate) mod conversation_hydration_cycle {
     use leptos::prelude::*;
 
     use crate::api::fetch_conversation_messages;
-    use crate::chat_session_state::ChatSessionSignals;
+    use crate::chat_session_state::{ChatSessionSignals, ConversationPromptTokenHydrate};
     use crate::conversation_hydrate::stored_messages_from_conversation_api;
 
     use super::{
@@ -322,6 +313,12 @@ pub(crate) mod conversation_hydration_cycle {
             return;
         }
 
+        chat.conversation_prompt_tokens
+            .set(Some(ConversationPromptTokenHydrate {
+                conversation_id: cid.clone(),
+                tiktoken: resp.tiktoken_prompt_tokens.clone(),
+            }));
+
         restore_reasoning_after_hydration(&chat, &aid, nonce_at_start);
         apply_saved_revision_if_same_conversation(&chat, cid.as_str(), resp.revision);
     }
@@ -336,6 +333,27 @@ async fn run_conversation_hydration_cycle(
     conversation_hydration_cycle::run(snap, chat, selected_agent_role).await;
 }
 
+fn clear_conversation_prompt_tokens_if_no_server_conversation(chat: ChatSessionSignals) {
+    let aid = chat.active_id.get_untracked();
+    if aid.is_empty() {
+        chat.conversation_prompt_tokens.set(None);
+        return;
+    }
+    let Some(sess) = chat
+        .sessions
+        .with_untracked(|list| list.iter().find(|s| s.id == aid).cloned())
+    else {
+        chat.conversation_prompt_tokens.set(None);
+        return;
+    };
+    if messages_contain_loading(&sess.messages) {
+        return;
+    }
+    if sess.trimmed_server_conversation_id().is_none() {
+        chat.conversation_prompt_tokens.set(None);
+    }
+}
+
 /// 订阅 `chat.session_hydrate_nonce`：流结束后由 composer 递增，拉取服务端快照并写回当前会话。
 ///
 /// 门闸与 [`crate::app::app_bootstrap_phase::AppBootstrapPhase::hydration_effects_enabled`] 一致（`initialized` + `web_ui_config_loaded`）。
@@ -358,6 +376,7 @@ pub fn wire_session_hydration(
             }
             let loc = locale_sig.get_untracked();
             let Some(snap) = try_hydration_wire_snapshot(chat, loc) else {
+                clear_conversation_prompt_tokens_if_no_server_conversation(chat);
                 return;
             };
             spawn_local(run_conversation_hydration_cycle(
diff --git a/frontend/src/app/status_bar.rs b/frontend/src/app/status_bar.rs
@@ -6,8 +6,11 @@ use leptos::prelude::*;
 use leptos_dom::helpers::event_target_value;
 
 use crate::api::load_client_llm_text_fields_from_storage;
-use crate::app_prefs::{status_bar_effective_api_base, status_bar_effective_model};
-use crate::chat_session_state::ChatStreamBusyMemos;
+use crate::app_prefs::{
+    status_bar_effective_api_base, status_bar_effective_llm_context_tokens,
+    status_bar_effective_model,
+};
+use crate::chat_session_state::{ChatSessionSignals, ChatStreamBusyMemos};
 
 use super::app_shell_ctx::StatusBarFooterSignals;
 use super::shell_runtime_context::expect_chat_shell_ctx;
@@ -50,6 +53,115 @@ struct StatusBarChipsSignals {
     locale: RwSignal<Locale>,
 }
 
+fn status_bar_context_chip_visible(chat: ChatSessionSignals) -> bool {
+    let Some(snap) = chat.conversation_prompt_tokens.get() else {
+        return false;
+    };
+    let aid = chat.active_id.get();
+    chat.sessions.with(|list| {
+        list.iter().find(|s| s.id == aid).is_some_and(|s| {
+            s.trimmed_server_conversation_id()
+                .is_some_and(|c| c == snap.conversation_id.as_str())
+        })
+    })
+}
+
+fn status_bar_context_cap_and_used(
+    chat: ChatSessionSignals,
+    st: StatusTasksSignals,
+    client_llm_storage_tick: RwSignal<u64>,
+) -> (u32, Option<u32>) {
+    let _tick = client_llm_storage_tick.get();
+    let sd = st.status_data.get();
+    let (_, _, _, stored_ctx, _) = load_client_llm_text_fields_from_storage();
+    let cap = status_bar_effective_llm_context_tokens(sd.as_ref(), stored_ctx.as_str());
+    let used = chat
+        .conversation_prompt_tokens
+        .get()
+        .and_then(|s| s.tiktoken.as_ref().map(|t| t.prompt_tokens));
+    (cap, used)
+}
+
+fn status_bar_context_value_text(cap: u32, used: Option<u32>) -> String {
+    match (used, cap > 0) {
+        (Some(u), true) => {
+            let pct = (u as f64 / cap as f64) * 100.0;
+            format!("{u} / {cap} ({:.1}%)", pct.min(999.9))
+        }
+        (Some(u), false) => format!("{u}"),
+        (None, true) => format!("— / {cap}"),
+        (None, false) => "—".to_string(),
+    }
+}
+
+#[component]
+fn StatusBarContextChip(
+    st: StatusTasksSignals,
+    chat: ChatSessionSignals,
+    client_llm_storage_tick: RwSignal<u64>,
+    locale: RwSignal<Locale>,
+) -> impl IntoView {
+    view! {
+        <Show when=move || status_bar_context_chip_visible(chat)>
+            <span
+                class="status-chip status-chip-context"
+                prop:title=move || i18n::status_chip_context_tooltip(locale.get())
+            >
+                <span class="status-chip-context-row">
+                    <span class="status-chip-label">
+                        {move || i18n::status_chip_context(locale.get())}
+                    </span>
+                    <span class="status-chip-value">{move || {
+                        let (cap, used) = status_bar_context_cap_and_used(
+                            chat,
+                            st,
+                            client_llm_storage_tick,
+                        );
+                        status_bar_context_value_text(cap, used)
+                    }}</span>
+                </span>
+                <Show when=move || {
+                    let (cap, used) = status_bar_context_cap_and_used(
+                        chat,
+                        st,
+                        client_llm_storage_tick,
+                    );
+                    cap > 0 && used.is_some()
+                }>
+                    <div
+                        class="status-context-meter"
+                        style=move || {
+                            let (cap, used) = status_bar_context_cap_and_used(
+                                chat,
+                                st,
+                                client_llm_storage_tick,
+                            );
+                            let u = used.unwrap_or(0);
+                            let pct = ((u as f64 / cap as f64) * 100.0).min(100.0);
+                            format!("--status-context-pct: {pct:.2}%")
+                        }
+                    >
+                        <div class=move || {
+                            let (cap, used) = status_bar_context_cap_and_used(
+                                chat,
+                                st,
+                                client_llm_storage_tick,
+                            );
+                            let u = used.unwrap_or(0);
+                            let pct = (u as f64 / cap as f64) * 100.0;
+                            if pct >= 90.0 {
+                                "status-context-meter-fill status-context-meter-fill--warn"
+                            } else {
+                                "status-context-meter-fill"
+                            }
+                        }></div>
+                    </div>
+                </Show>
+            </span>
+        </Show>
+    }
+}
+
 #[component]
 fn StatusBarChipsSkeleton(locale: RwSignal<Locale>) -> impl IntoView {
     view! {
@@ -162,6 +274,12 @@ fn StatusBarChipsLoaded(
                     }}
                 </select>
             </label>
+            <StatusBarContextChip
+                st=st
+                chat=chat
+                client_llm_storage_tick=client_llm_storage_tick
+                locale=locale
+            />
         </>
     }
 }
diff --git a/frontend/src/app_prefs.rs b/frontend/src/app_prefs.rs
@@ -120,6 +120,23 @@ pub fn status_bar_effective_api_base(server: Option<&StatusData>, stored_api_bas
     }
 }
 
+/// 状态栏「上下文窗口 token 上限」：本机 `client_llm.llm_context_tokens` 非空且可解析为正数时优先，否则用 `/status`。
+#[must_use]
+pub fn status_bar_effective_llm_context_tokens(
+    server: Option<&StatusData>,
+    stored_llm_context_tokens: &str,
+) -> u32 {
+    let t = stored_llm_context_tokens.trim();
+    if !t.is_empty() {
+        if let Ok(n) = t.parse::<u32>() {
+            if n > 0 {
+                return n;
+            }
+        }
+    }
+    server.map(|d| d.llm_context_tokens).unwrap_or(0)
+}
+
 pub fn clamp_side_width_for_viewport(w: f64) -> f64 {
     let win = web_sys::window()
         .and_then(|win| win.inner_width().ok())
diff --git a/frontend/src/chat_session_state.rs b/frontend/src/chat_session_state.rs
@@ -6,7 +6,7 @@
 //! - **`stream_transport`**：[`ChatStreamTransport`] 单 **`RwSignal`** 收敛 **attach 代际** + **Idle / 已绑定会话**（内含 **`job_id`**）；[`ChatSessionSignals::clear_stream_resume_handles`] 将车道置回 Idle 并重置 [`Self::stream_last_sse_event_seq`]；[`ChatSessionSignals::bind_stream_to_session`] 在 bump 后写入 Bound。SSE `id:` 序号单独为 **`stream_last_sse_event_seq`**，避免热路径上整包传输状态无效化。与 **`stream_text_overlay`** 的联合象限见 [`StreamLaneOverlayPhase`] / [`ChatSessionSignals::stream_lane_overlay_phase_untracked`]。
 //! - **代际门闩**：每次发起新 `/chat/stream` attach 时递增 [`ChatStreamTransport::attach_generation`]；[`crate::app::chat::composer_stream::context::ChatStreamCallbackCtx`] 捕获该值，回调内若与当前不一致则视为陈旧。
 //! - **`session_sync`**：服务端 `conversation_id` / revision，与 `POST /chat/branch` 等对齐。
-//! - **`session_hydrate_nonce` / `reasoning_preserved`**：拉取会话正文与水合时的补偿字段。
+//! - **`session_hydrate_nonce` / `reasoning_preserved` / `conversation_prompt_tokens`**：拉取会话正文与水合时的补偿字段；后者供底栏展示 prompt token 粗估。
 //! - **`stream_text_overlay`**：尾条 `loading` 助手消息的流式正文/思维链旁路缓冲（字段见 [`ChatSessionSignals`]）。
 //!
 //! # `sessions` 向量的写入通道（命名封装）
@@ -26,10 +26,18 @@ use std::sync::Arc;
 
 use leptos::prelude::*;
 
+use crate::conversation_hydrate::TiktokenPromptTokensSnapshot;
 use crate::session_sync::SessionSyncState;
 use crate::storage::ChatSession;
 use crate::stream_text_overlay::StreamTextOverlay;
 
+/// 水合成功后与会话绑定的 tiktoken prompt 粗估（见 `GET /conversation/messages`）。
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ConversationPromptTokenHydrate {
+    pub conversation_id: String,
+    pub tiktoken: Option<TiktokenPromptTokensSnapshot>,
+}
+
 /// `/chat/stream` 传输层：单调 **`attach_generation`** 与 **`lane`**（Idle | 已绑定会话及重连句柄）。
 #[derive(Clone, Debug, PartialEq, Eq, Default)]
 pub struct ChatStreamTransport {
@@ -239,6 +247,8 @@ pub struct ChatSessionSignals {
     pub reasoning_preserved: RwSignal<HashMap<String, String>>,
     /// 当前尾条 `loading` 助手消息的流式正文/思维链增量；**不**写入 [`Self::sessions`]，减少历史行重算。
     pub stream_text_overlay: RwSignal<Option<StreamTextOverlay>>,
+    /// 最近一次成功水合的 tiktoken prompt 计数（与 [`ConversationPromptTokenHydrate::conversation_id`] 对齐，防串会话）。
+    pub conversation_prompt_tokens: RwSignal<Option<ConversationPromptTokenHydrate>>,
 }
 
 impl ChatSessionSignals {
diff --git a/frontend/src/conversation_hydrate.rs b/frontend/src/conversation_hydrate.rs
@@ -20,18 +20,14 @@ pub struct ConversationMessagesResponse {
     pub revision: u64,
     #[serde(default)]
     pub active_agent_role: Option<String>,
-    /// 服务端可选返回；水合路径当前未消费，保留供 UI/调试读取。
     #[serde(default)]
-    #[allow(dead_code)]
     pub tiktoken_prompt_tokens: Option<TiktokenPromptTokensSnapshot>,
     pub messages: Vec<Value>,
 }
 
-#[derive(Debug, Clone, Deserialize)]
+#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
 pub struct TiktokenPromptTokensSnapshot {
-    #[allow(dead_code)]
     pub prompt_tokens: u32,
-    #[allow(dead_code)]
     pub tiktoken_model: String,
 }
 
diff --git a/frontend/src/i18n/status.rs b/frontend/src/i18n/status.rs
@@ -34,6 +34,25 @@ pub fn status_chip_base_url(_l: Locale) -> &'static str {
     "base_url"
 }
 
+pub fn status_chip_context(l: Locale) -> &'static str {
+    match l {
+        Locale::ZhHans => "上下文",
+        Locale::En => "Context",
+    }
+}
+
+/// 状态栏「上下文」芯片 `title`：说明 tiktoken 粗估与上限含义。
+pub fn status_chip_context_tooltip(l: Locale) -> &'static str {
+    match l {
+        Locale::ZhHans => {
+            "当前会话消息体的 prompt tokens（tiktoken 粗估，与出站消息一致）相对 llm_context_tokens 上限；不含工具 JSON，与网关真实计费可能有偏差。"
+        }
+        Locale::En => {
+            "Prompt tokens for stored message bodies (tiktoken estimate, aligned with outbound messages) vs llm_context_tokens cap; excludes tool JSON and may differ from provider billing."
+        }
+    }
+}
+
 pub fn status_role_label(l: Locale) -> &'static str {
     match l {
         Locale::ZhHans => "角色",
diff --git a/frontend/src/storage.rs b/frontend/src/storage.rs
@@ -180,6 +180,17 @@ pub struct ChatSession {
     pub workspace_root: Option<String>,
 }
 
+impl ChatSession {
+    /// 非空且 trim 后的 `server_conversation_id`；与 `GET /conversation/messages` 路径参数对齐。
+    #[must_use]
+    pub fn trimmed_server_conversation_id(&self) -> Option<&str> {
+        self.server_conversation_id
+            .as_deref()
+            .map(str::trim)
+            .filter(|x| !x.is_empty())
+    }
+}
+
 /// 进程重启后不再有挂起的 SSE；本地持久化的助手 `loading` 占位若不清理会永久显示「生成中」。
 /// 在从 `localStorage` 恢复会话列表时调用（见 `wire_initial_sessions_from_storage`）。
 pub fn clear_stale_assistant_loading_states(messages: &mut [StoredMessage]) {
diff --git a/frontend/styles/status.css b/frontend/styles/status.css
