From 68fbd568b70594c6509686c4f031550997912371 Mon Sep 17 00:00:00 2001
From: Zhicheng Han <43314240+hanzckernel@users.noreply.github.com>
Date: Sat, 16 May 2026 02:29:51 +0200
Subject: [PATCH] docs: clarify session search scope (#774)
---
README.md | 6 +++---
README_zh.md | 6 +++---
docs/cli-chat-sessions.md | 16 ++++++++++------
.../hermes/chat/SessionSearchModal.vue | 7 +++++++
packages/client/src/i18n/locales/en.ts | 1 +
packages/client/src/i18n/locales/zh-TW.ts | 1 +
packages/client/src/i18n/locales/zh.ts | 1 +
packages/website/src/i18n/en.ts | 4 ++--
packages/website/src/i18n/zh.ts | 4 ++--
9 files changed, 30 insertions(+), 16 deletions(-)
diff --git a/README.md b/README.md
index b8128a3..2a40275 100644
--- a/README.md
+++ b/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
diff --git a/README_zh.md b/README_zh.md
index 3ef7fb9..dfd974c 100644
--- a/README_zh.md
+++ b/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 用量
diff --git a/docs/cli-chat-sessions.md b/docs/cli-chat-sessions.md
index bbe274b..b7932cf 100644
--- a/docs/cli-chat-sessions.md
+++ b/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` 反馈。
diff --git a/packages/client/src/components/hermes/chat/SessionSearchModal.vue b/packages/client/src/components/hermes/chat/SessionSearchModal.vue
index 49d4561..d4f0684 100644
--- a/packages/client/src/components/hermes/chat/SessionSearchModal.vue
+++ b/packages/client/src/components/hermes/chat/SessionSearchModal.vue
@@ -231,6 +231,7 @@ onUnmounted(() => {
{{ t('chat.searchSubtitle') }}
{{ t('chat.searchHint') }}
+ {{ t('chat.searchScope') }}
{
color: $text-muted;
}
+.search-scope {
+ font-size: 12px;
+ color: $text-muted;
+ line-height: 1.5;
+}
+
.search-body {
max-height: min(60vh, 540px);
overflow: hidden;
diff --git a/packages/client/src/i18n/locales/en.ts b/packages/client/src/i18n/locales/en.ts
index 603e6e2..af32025 100644
--- a/packages/client/src/i18n/locales/en.ts
+++ b/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',
diff --git a/packages/client/src/i18n/locales/zh-TW.ts b/packages/client/src/i18n/locales/zh-TW.ts
index c326f2e..0e2d77e 100644
--- a/packages/client/src/i18n/locales/zh-TW.ts
+++ b/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: '最近工作階段',
diff --git a/packages/client/src/i18n/locales/zh.ts b/packages/client/src/i18n/locales/zh.ts
index dee355a..57c3de0 100644
--- a/packages/client/src/i18n/locales/zh.ts
+++ b/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: '最近会话',
diff --git a/packages/website/src/i18n/en.ts b/packages/website/src/i18n/en.ts
index 50c2736..38497a2 100644
--- a/packages/website/src/i18n/en.ts
+++ b/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',
diff --git a/packages/website/src/i18n/zh.ts b/packages/website/src/i18n/zh.ts
index c47ef52..3227370 100644
--- a/packages/website/src/i18n/zh.ts
+++ b/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: '看板管理',