docs: clarify session search scope (#774)

README.md

@@ -33,9 +33,9 @@
 
 ### AI Chat
 
-- Real-time streaming via SSE with async run support
+- Real-time chat streaming over Socket.IO `/chat-run`; API Server runs consume Hermes Gateway streaming responses
 - Multi-session management — create, rename, delete, switch between sessions
-- **Self-built session database** — local SQLite storage with automatic sync from Hermes state.db on first startup
+- **Self-built session database** — local SQLite storage for Web UI sessions; Hermes state.db remains a read-only source for Hermes history APIs
 - Session grouping by source (Telegram, Discord, Slack, etc.) with collapsible accordion
 - Active session indicator — live sessions pin to top with spinner icon
 - Sessions sorted by latest message time
@@ -43,7 +43,7 @@
 - Tool call detail expansion (arguments / result)
 - File upload support
 - File download support — download user-uploaded files and agent-generated files across local, Docker, SSH, and Singularity backends
-- Session search — Ctrl+K global search across all conversations
+- Session search — Ctrl+K search across the Web UI local session database; read-only Hermes history sessions are not included
 - Global model selector — discovers models from `~/.hermes/auth.json` credential pool
 - Per-session model display badge and context token usage
 

README_zh.md

@@ -41,9 +41,9 @@
 
 ### AI 聊天
 
-- 通过 SSE 实时流式输出，支持异步 Run
+- 聊天前端通过 Socket.IO `/chat-run` 实时流式更新；API Server 路径内部消费 Hermes Gateway 流式响应
 - 多会话管理 — 创建、重命名、删除、切换会话
-- **自建会话数据库** — 本地 SQLite 存储，首次启动时自动从 Hermes state.db 同步 api_server 会话
+- **自建会话数据库** — Web UI 会话使用本地 SQLite；Hermes state.db 仅作为只读来源用于 Hermes 历史 API
 - 按来源分组会话（Telegram、Discord、Slack 等），可折叠手风琴面板
 - 活跃会话实时指示器 — 正在进行的会话置顶并显示旋转图标
 - 按最新消息时间排序会话列表
@@ -51,7 +51,7 @@
 - 工具调用详情展开（参数 / 结果）
 - 文件上传支持
 - 文件下载支持 — 支持下载用户上传的文件和 Agent 生成的文件，兼容 local、Docker、SSH、Singularity 等多种 terminal backend
-- 会话搜索 — Ctrl+K 全局搜索所有对话
+- 会话搜索 — Ctrl+K 搜索 Web UI 本地会话库；不包含只读 Hermes 历史会话
 - 全局模型选择器 — 自动从 `~/.hermes/auth.json` 凭证池发现可用模型
 - 每个会话显示模型标签和上下文 Token 用量
 

docs/cli-chat-sessions.md

@@ -25,7 +25,7 @@ Bridge 模式支持：
 - 从 DB resume 会话
 - 与 API Server 路径共用上下文压缩逻辑
 
-当前不再支持旧文档里的独立 `/cli-chat-run` namespace、`CliChatPanel.vue`、`cli-chat.ts` 和 CLI 命令控制层。前端不会再发送 `command` 或 `steer` socket 事件，也不会把 `/new`、`/reset`、`/undo`、`/retry`、`/branch`、`/compress` 等输入当作特殊命令处理。
+当前不再支持旧文档里的独立 `/cli-chat-run` namespace、`CliChatPanel.vue`、`cli-chat.ts` 和独立 `command` / `steer` socket 事件。CLI/Bridge 会话中的 slash command 现在通过统一 `/chat-run` 的 `run` payload 进入后端解析；当前支持 `/usage`、`/status`、`/abort`、`/queue`、`/clear`、`/title`、`/compress`、`/steer`、`/destroy`。
 
 ---
 
@@ -76,7 +76,10 @@ ChatRunSocket (Node.js)
 
 | 文件 | 说明 |
 |------|------|
-| `packages/server/src/services/hermes/chat-run-socket.ts` | `/chat-run` Socket.IO 服务；同时处理 API Server 和 Bridge 运行 |
+| `packages/server/src/services/hermes/run-chat/index.ts` | `/chat-run` Socket.IO 入口；按 `source` 分流 API Server 与 Bridge 运行 |
+| `packages/server/src/services/hermes/run-chat/handle-api-run.ts` | API Server 路径；调用 Hermes Gateway `/v1/responses` 并消费流式响应 |
+| `packages/server/src/services/hermes/run-chat/handle-bridge-run.ts` | Bridge 路径；调用 Agent Bridge 并写入本地会话库 |
+| `packages/server/src/services/hermes/run-chat/session-command.ts` | CLI/Bridge slash command 解析与处理 |
 | `packages/server/src/services/hermes/agent-bridge/client.ts` | Node 端 bridge 客户端；通过 socket 请求 Python bridge |
 | `packages/server/src/services/hermes/agent-bridge/manager.ts` | Python bridge 子进程生命周期管理 |
 | `packages/server/src/services/hermes/agent-bridge/hermes_bridge.py` | Python bridge 服务；创建并复用 `AIAgent` 实例 |
@@ -180,7 +183,7 @@ socket.emit('approval.respond', {
 | `cancel_queued_run` | `{ session_id, queue_id }` | 取消等待队列中的一条 run |
 | `approval.respond` | `{ session_id, approval_id, choice }` | 响应 Bridge 工具审批 |
 
-当前没有 `command`、`steer` 或 slash-command 相关 Socket.IO 事件。
+客户端不再发送独立 `command` 或 `steer` Socket.IO 事件；slash command 作为普通 `run.input` 进入 `/chat-run`，由服务端在 `source=cli` 时解析。
 
 ### 服务端 → 客户端
 
@@ -202,6 +205,7 @@ socket.emit('approval.respond', {
 | `usage.updated` | token 用量更新 |
 | `abort.started` | 中断开始 |
 | `abort.completed` | 中断结束 |
+| `session.command` | slash command 的执行结果或错误反馈 |
 | `run.completed` | 运行完成 |
 | `run.failed` | 运行失败 |
 
@@ -300,9 +304,9 @@ Windows 使用 TCP 是因为部分 Python/Windows 环境没有 Unix domain socke
 | `approval_respond` | 响应工具审批 |
 | `destroy_all` | profile 切换/管理时销毁全部 bridge 内存 session |
 
-bridge 代码里还保留了一些调试/维护 action，例如 `ping`、`get_result`、`get_history`、`destroy`、`list`、`shutdown`、`steer`，但当前 `/chat-run` 前端路径不会暴露这些能力。
+bridge 代码里还保留了一些调试/维护 action，例如 `ping`、`get_result`、`get_history`、`destroy`、`list`、`shutdown`、`steer`。当前 `/chat-run` 前端路径不会直接暴露这些 action；需要的能力由 Node `/chat-run` 层封装，例如 `/steer` slash command 会调用 `steer` action。
 
-旧的 `command` action 已移除，bridge 不再处理 `/new`、`/undo`、`/retry`、`/branch`、`/compress` 等斜杠命令。
+旧的 `command` action 已移除，Python bridge 不再直接解析 `/new`、`/undo`、`/retry`、`/branch` 等旧斜杠命令；当前 CLI/Bridge slash command 支持范围以 Node `/chat-run` 的 `session-command.ts` 为准。
 
 ### 会话和 profile
 
@@ -456,4 +460,4 @@ $env:HERMES_AGENT_BRIDGE_TIMEOUT_MS = "300000"
 - Bridge(beta) 仍依赖 Python bridge 成功启动；启动失败时 Web UI 可用，但 bridge 会话不可用。
 - bridge socket connect 阶段还没有单独 connect timeout。
 - 旧 CLI 独立面板和独立 `/cli-chat-run` namespace 已移除。
-- 旧 bridge 斜杠命令和 `command/steer` socket 控制层已移除；现在输入框内容一律按普通用户消息发送。
+- 旧 bridge `command/steer` socket 控制层已移除；CLI/Bridge slash command 现在通过统一 `/chat-run` 的 `run.input` 解析并以 `session.command` 反馈。

packages/client/src/components/hermes/chat/SessionSearchModal.vue

@@ -231,6 +231,7 @@ onUnmounted(() => {
         <div class="search-title">{{ t('chat.searchSubtitle') }}</div>
         <div class="search-hint">{{ t('chat.searchHint') }}</div>
       </div>
+      <div class="search-scope">{{ t('chat.searchScope') }}</div>
 
       <NInput
         ref="inputRef"
@@ -309,6 +310,12 @@ onUnmounted(() => {
   color: $text-muted;
 }
 
+.search-scope {
+  font-size: 12px;
+  color: $text-muted;
+  line-height: 1.5;
+}
+
 .search-body {
   max-height: min(60vh, 540px);
   overflow: hidden;

packages/client/src/i18n/locales/en.ts

@@ -169,6 +169,7 @@ export default {
     noSessions: 'No sessions',
     searchTitle: 'Search Sessions',
     searchSubtitle: 'Search by title or message content',
+    searchScope: 'Search scope: Web UI local session database only. Read-only Hermes history sessions are not included.',
     searchHint: 'Cmd/Ctrl+K',
     searchPlaceholder: 'Search sessions...',
     searchEmpty: 'Recent sessions',

packages/client/src/i18n/locales/zh-TW.ts

@@ -168,6 +168,7 @@ export default {
     noSessions: '目前無工作階段',
     searchTitle: '搜尋工作階段',
     searchSubtitle: '依標題或訊息內容搜尋',
+    searchScope: '搜尋範圍：僅 Web UI 本地工作階段資料庫；不包含唯讀 Hermes 歷史工作階段。',
     searchHint: 'Cmd/Ctrl+K',
     searchPlaceholder: '搜尋工作階段...',
     searchEmpty: '最近工作階段',

packages/client/src/i18n/locales/zh.ts

@@ -169,6 +169,7 @@ export default {
     noSessions: '暂无会话',
     searchTitle: '搜索会话',
     searchSubtitle: '按标题或消息内容搜索',
+    searchScope: '搜索范围：仅 Web UI 本地会话库；不包含只读 Hermes 历史会话。',
     searchHint: 'Cmd/Ctrl+K',
     searchPlaceholder: '搜索会话...',
     searchEmpty: '最近会话',

packages/website/src/i18n/en.ts

@@ -16,7 +16,7 @@ export default {
     desc: 'A complete AI agent management dashboard with rich features out of the box.',
     streaming: {
       title: 'Streaming Chat',
-      desc: 'Real-time SSE-powered AI conversations with multi-session management, Markdown rendering, and code syntax highlighting.',
+      desc: 'Real-time Socket.IO-powered AI conversations with multi-session management, Markdown rendering, and code syntax highlighting.',
     },
     platforms: {
       title: '8 Platforms',
@@ -156,7 +156,7 @@ export default {
       intro: 'Explore the core features of Hermes Web UI.',
       chat: {
         title: 'AI Chat',
-        content: 'Real-time streaming chat powered by Server-Sent Events. Supports multi-session management, Markdown rendering with syntax highlighting, tool call inspection, file upload/download, and global search across all conversations (Ctrl+K).',
+        content: 'Real-time chat streaming over Socket.IO /chat-run. Supports multi-session management, Markdown rendering with syntax highlighting, tool call inspection, file upload/download, and Ctrl+K search across the Web UI local session database.',
       },
       kanban: {
         title: 'Kanban Board',

packages/website/src/i18n/zh.ts

@@ -16,7 +16,7 @@ export default {
     desc: '开箱即用的完整 AI Agent 管理仪表板。',
     streaming: {
       title: '流式聊天',
-      desc: '基于 SSE 的实时 AI 对话，支持多会话管理、Markdown 渲染和代码语法高亮。',
+      desc: '基于 Socket.IO 的实时 AI 对话，支持多会话管理、Markdown 渲染和代码语法高亮。',
     },
     platforms: {
       title: '8 大平台',
@@ -156,7 +156,7 @@ export default {
       intro: '探索 Hermes Web UI 的核心功能。',
       chat: {
         title: 'AI 聊天',
-        content: '基于 Server-Sent Events 的实时流式聊天。支持多会话管理、Markdown 渲染与语法高亮、工具调用检查、文件上传/下载以及全局搜索 (Ctrl+K)。',
+        content: '通过 Socket.IO /chat-run 实时流式聊天。支持多会话管理、Markdown 渲染与语法高亮、工具调用检查、文件上传/下载，以及 Ctrl+K 搜索 Web UI 本地会话库。',
       },
       kanban: {
         title: '看板管理',