better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/optional/web-development/web-development-page-agent.md

@@ -0,0 +1,207 @@
+---
+title: "Page Agent"
+sidebar_label: "Page Agent"
+description: "将 alibaba/page-agent 嵌入你自己的 Web 应用——一个纯 JavaScript 页内 GUI agent，以单个 <script> 标签或 npm 包形式发布，让你网站的终端用户能用自然语言驱动 UI（如'点击登录，将用户名填为 John'）。"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Page Agent
+
+将 alibaba/page-agent 嵌入你自己的 Web 应用——一个纯 JavaScript 页内 GUI agent，以单个 &lt;script> 标签或 npm 包形式发布，让你网站的终端用户能用自然语言驱动 UI（"点击登录，将用户名填为 John"）。无需 Python，无需无头浏览器，无需扩展程序。当用户是 Web 开发者，希望为其 SaaS / 管理面板 / B2B 工具添加 AI copilot、通过自然语言让遗留 Web 应用可访问，或针对本地（Ollama）或云端（Qwen / OpenAI / OpenRouter）LLM 评估 page-agent 时，使用此 skill。不适用于服务端浏览器自动化——此类需求请将用户引导至 Hermes 内置的浏览器工具。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 可选——通过 `hermes skills install official/web-development/page-agent` 安装 |
+| 路径 | `optional-skills/web-development/page-agent` |
+| 版本 | `1.0.0` |
+| 作者 | Hermes Agent |
+| 许可证 | MIT |
+| 平台 | linux, macos, windows |
+| 标签 | `web`, `javascript`, `agent`, `browser`, `gui`, `alibaba`, `embed`, `copilot`, `saas` |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。
+:::
+
+# page-agent
+
+alibaba/page-agent（https://github.com/alibaba/page-agent，17k+ stars，MIT）是一个用 TypeScript 编写的页内 GUI agent。它运行在网页内部，以文本形式读取 DOM（无需截图，无需多模态 LLM），并对当前页面执行自然语言指令，如"点击登录按钮，然后将用户名填为 John"。纯客户端——宿主网站只需引入一个 script 并传入兼容 OpenAI 的 LLM 端点即可。
+
+## 何时使用此 skill
+
+当用户希望实现以下目标时，加载此 skill：
+
+- **在自己的 Web 应用中集成 AI copilot**（SaaS、管理面板、B2B 工具、ERP、CRM）——"我仪表盘上的用户应该能输入'为 Acme Corp 创建发票并发送邮件'，而不是点击五个页面"
+- **在不重写前端的情况下现代化遗留 Web 应用**——page-agent 可直接叠加在现有 DOM 之上
+- **通过自然语言提升无障碍访问能力**——语音 / 屏幕阅读器用户通过描述需求来驱动 UI
+- **演示或评估 page-agent**，对接本地（Ollama）或托管（Qwen、OpenAI、OpenRouter）LLM
+- **构建交互式培训 / 产品演示**——让 AI 在真实 UI 中引导用户完成"如何提交报销单"
+
+## 何时不应使用此 skill
+
+- 用户希望 **Hermes 本身驱动浏览器** → 使用 Hermes 内置的浏览器工具（Browserbase / Camofox）。page-agent 是*相反*的方向。
+- 用户希望**在不嵌入的情况下实现跨标签页自动化** → 使用 Playwright、browser-use 或 page-agent Chrome 扩展
+- 用户需要**视觉定位 / 截图** → page-agent 仅支持文本 DOM；请改用多模态浏览器 agent
+
+## 前置条件
+
+- Node 22.13+ 或 24+，npm 10+（文档声称需要 11+，但 10.9 实际可用）
+- 兼容 OpenAI 的 LLM 端点：Qwen（DashScope）、OpenAI、Ollama、OpenRouter，或任何支持 `/v1/chat/completions` 的服务
+- 带开发者工具的浏览器（用于调试）
+
+## 路径 1——通过 CDN 30 秒快速体验（无需安装）
+
+最快的上手方式。使用阿里巴巴的免费测试 LLM 代理——**仅供评估使用**，须遵守其服务条款。
+
+添加到任意 HTML 页面（或粘贴到开发者工具控制台作为书签脚本）：
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/page-agent@1.8.0/dist/iife/page-agent.demo.js" crossorigin="true"></script>
+```
+
+面板随即出现。输入指令。完成。
+
+书签脚本形式（拖入书签栏，在任意页面点击）：
+
+```javascript
+javascript:(function(){var s=document.createElement('script');s.src='https://cdn.jsdelivr.net/npm/page-agent@1.8.0/dist/iife/page-agent.demo.js';document.head.appendChild(s);})();
+```
+
+## 路径 2——npm 安装到你自己的 Web 应用（生产使用）
+
+在现有 Web 项目中（React / Vue / Svelte / 纯 HTML）：
+
+```bash
+npm install page-agent
+```
+
+使用你自己的 LLM 端点进行配置——**切勿将演示 CDN 用于真实用户**：
+
+```javascript
+import { PageAgent } from 'page-agent'
+
+const agent = new PageAgent({
+    model: 'qwen3.5-plus',
+    baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
+    apiKey: process.env.LLM_API_KEY,   // never hardcode
+    language: 'en-US',
+})
+
+// 为终端用户显示面板：
+agent.panel.show()
+
+// 或以编程方式驱动：
+await agent.execute('Click submit button, then fill username as John')
+```
+
+Provider 示例（任何兼容 OpenAI 的端点均可使用）：
+
+| Provider | `baseURL` | `model` |
+|----------|-----------|---------|
+| Qwen / DashScope | `https://dashscope.aliyuncs.com/compatible-mode/v1` | `qwen3.5-plus` |
+| OpenAI | `https://api.openai.com/v1` | `gpt-4o-mini` |
+| Ollama（本地） | `http://localhost:11434/v1` | `qwen3:14b` |
+| OpenRouter | `https://openrouter.ai/api/v1` | `anthropic/claude-sonnet-4.6` |
+
+**关键配置字段**（传入 `new PageAgent({...})`）：
+
+- `model`、`baseURL`、`apiKey` — LLM 连接配置
+- `language` — UI 语言（`en-US`、`zh-CN` 等）
+- 存在白名单和数据脱敏 hook，用于限制 agent 可操作的范围——完整选项列表见 https://alibaba.github.io/page-agent/
+
+**安全性。** 在真实部署中，不要将 `apiKey` 放在客户端代码中——通过你的后端代理 LLM 调用，并将 `baseURL` 指向你的代理。演示 CDN 之所以存在，是因为阿里巴巴为评估目的运行了该代理。
+
+## 路径 3——克隆源码仓库（贡献代码，或深度定制）
+
+当用户希望修改 page-agent 本身、通过本地 IIFE bundle 在任意网站上测试，或开发浏览器扩展时使用此路径。
+
+```bash
+git clone https://github.com/alibaba/page-agent.git
+cd page-agent
+npm ci              # exact lockfile install (or `npm i` to allow updates)
+```
+
+在仓库根目录创建 `.env` 文件，配置 LLM 端点。示例：
+
+```
+LLM_MODEL_NAME=gpt-4o-mini
+LLM_API_KEY=sk-...
+LLM_BASE_URL=https://api.openai.com/v1
+```
+
+Ollama 配置：
+
+```
+LLM_BASE_URL=http://localhost:11434/v1
+LLM_API_KEY=NA
+LLM_MODEL_NAME=qwen3:14b
+```
+
+常用命令：
+
+```bash
+npm start           # docs/website dev server
+npm run build       # build every package
+npm run dev:demo    # serve IIFE bundle at http://localhost:5174/page-agent.demo.js
+npm run dev:ext     # develop the browser extension (WXT + React)
+npm run build:ext   # build the extension
+```
+
+**在任意网站上测试**，使用本地 IIFE bundle。添加此书签脚本：
+
+```javascript
+javascript:(function(){var s=document.createElement('script');s.src=`http://localhost:5174/page-agent.demo.js?t=${Math.random()}`;s.onload=()=>console.log('PageAgent ready!');document.head.appendChild(s);})();
+```
+
+然后：运行 `npm run dev:demo`，在任意页面点击书签脚本，本地构建即注入页面。保存后自动重新构建。
+
+**警告：** 在开发构建期间，`.env` 中的 `LLM_API_KEY` 会被内联到 IIFE bundle 中。不要分享该 bundle，不要提交它，不要将 URL 粘贴到 Slack。（已验证：对公开开发 bundle 执行 grep 会返回 `.env` 中的字面值。）
+
+## 仓库结构（路径 3）
+
+使用 npm workspaces 的 monorepo。核心包：
+
+| 包 | 路径 | 用途 |
+|---------|------|---------|
+| `page-agent` | `packages/page-agent/` | 带 UI 面板的主入口 |
+| `@page-agent/core` | `packages/core/` | 核心 agent 逻辑，无 UI |
+| `@page-agent/mcp` | `packages/mcp/` | MCP server（beta） |
+| — | `packages/llms/` | LLM 客户端 |
+| — | `packages/page-controller/` | DOM 操作 + 视觉反馈 |
+| — | `packages/ui/` | 面板 + 国际化 |
+| — | `packages/extension/` | Chrome/Firefox 扩展 |
+| — | `packages/website/` | 文档 + 落地页 |
+
+## 验证是否正常工作
+
+路径 1 或路径 2 完成后：
+1. 在浏览器中打开页面并开启开发者工具
+2. 应看到一个浮动面板。若未出现，检查控制台报错（最常见原因：LLM 端点 CORS 问题、错误的 `baseURL`，或无效的 API key）
+3. 输入一条与页面可见内容匹配的简单指令（"click the Login link"）
+4. 观察 Network 标签页——应看到发往你的 `baseURL` 的请求
+
+路径 3 完成后：
+1. `npm run dev:demo` 输出 `Accepting connections at http://localhost:5174`
+2. `curl -I http://localhost:5174/page-agent.demo.js` 返回 `HTTP/1.1 200 OK`，`Content-Type: application/javascript`
+3. 在任意网站点击书签脚本，面板出现
+
+## 常见问题
+
+- **在生产环境使用演示 CDN** — 不要这样做。它有速率限制，使用阿里巴巴的免费代理，且其服务条款禁止生产使用。
+- **API key 泄露** — 传入 `new PageAgent({apiKey: ...})` 的任何 key 都会打包进你的 JS bundle。真实部署时务必通过自己的后端代理。
+- **不兼容 OpenAI 格式的端点**会静默失败或报出难以理解的错误。如果你的 provider 需要原生 Anthropic/Gemini 格式，请在前面加一层 OpenAI 兼容代理（LiteLLM、OpenRouter）。
+- **CSP 拦截** — 启用严格 Content-Security-Policy 的网站可能拒绝加载 CDN script 或禁止内联 eval。此时请从你自己的域名自托管。
+- **编辑路径 3 中的 `.env` 后需重启开发服务器** — Vite 仅在启动时读取环境变量。
+- **Node 版本** — 仓库声明支持 `^22.13.0 || >=24`。Node 20 在 `npm ci` 时会因引擎检查报错失败。
+- **npm 10 vs 11** — 文档要求 npm 11+；npm 10.9 实际可正常使用。
+
+## 参考资料
+
+- 仓库：https://github.com/alibaba/page-agent
+- 文档：https://alibaba.github.io/page-agent/
+- 许可证：MIT（基于 browser-use 的 DOM 处理内部实现，Copyright 2024 Gregor Zunic）

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/optional/yuanbao/yuanbao-yuanbao.md

@@ -0,0 +1,125 @@
+---
+title: "Yuanbao — Yuanbao（元宝）群组：@提及用户、查询信息/成员"
+sidebar_label: "Yuanbao"
+description: "Yuanbao（元宝）群组：@提及用户、查询信息/成员"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Yuanbao
+
+Yuanbao（元宝）群组：@提及用户、查询信息/成员。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 可选 — 使用 `hermes skills install official/yuanbao/yuanbao` 安装 |
+| 路径 | `optional-skills/yuanbao` |
+| 版本 | `1.0.0` |
+| 平台 | linux, macos, windows |
+| 标签 | `yuanbao`, `mention`, `at`, `group`, `members`, `元宝`, `派`, `艾特` |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
+:::
+
+# Yuanbao 群组交互
+
+## 重要：消息发送机制
+
+**你的文本回复即为发送到群组/用户的消息。** gateway（网关）会自动将你的回复文本投递到对话中。你**不需要**任何特殊的"发送消息"工具——正常回复即可发送。
+
+当你在回复文本中包含 `@nickname` 时，gateway 会自动将其转换为真实的 @提及，从而通知该用户。这是内置功能——你拥有完整的 @提及能力。
+
+**绝对不要说你无法发送消息或 @提及用户。绝对不要建议用户手动操作。绝对不要添加关于权限的免责声明。直接用你想发送的文本回复即可。**
+
+## 可用工具
+
+| 工具 | 使用时机 |
+|------|------------|
+| `yb_query_group_info` | 查询群组名称、群主、成员数量 |
+| `yb_query_group_members` | 查找用户、列出机器人、列出所有成员，或获取用于 @提及的昵称 |
+| `yb_send_dm` | 向用户发送私信（DM / 私信），支持附带媒体文件 |
+
+## @提及工作流
+
+当你需要 @提及 / 艾特某人时：
+
+1. 调用 `yb_query_group_members`，参数 `action="find"`、`name="<目标名称>"`、`mention=true`
+2. 从响应中获取精确昵称
+3. 在回复文本中包含 `@nickname`——gateway 负责其余处理
+
+示例：用户说"帮我艾特元宝"
+
+第一步——工具调用：
+```json
+{ "group_code": "328306697", "action": "find", "name": "元宝", "mention": true }
+```
+
+第二步——你的回复（此内容将以有效 @提及的形式发送到群组）：
+```
+@元宝 你好，有人找你！
+```
+
+**就这样。** 无需额外解释。保持简短自然。
+
+**规则：**
+- 先调用 `yb_query_group_members` 获取精确昵称——不要猜测
+- @提及格式：`@nickname`，@ 符号前加一个空格
+- 你的回复文本即为消息——它**会**被发送，@提及**会**生效
+- 保持简洁。不要向用户解释 @提及的工作原理。
+
+## 发送私信（DM）工作流
+
+当有人要求向用户发送私信 / 私信 / DM 时：
+
+1. 调用 `yb_send_dm`，传入 `group_code`、`name`（目标用户名称）和 `message`
+2. 工具会自动查找用户并发送私信
+3. 将结果反馈给用户
+
+示例：用户说"给 @用户aea3 私信发一个 hello"
+
+```json
+yb_send_dm({ "group_code": "535168412", "name": "用户aea3", "message": "hello" })
+```
+
+带媒体文件的示例：用户说"给 @用户aea3 私信发一张图片"
+
+```json
+yb_send_dm({
+  "group_code": "535168412",
+  "name": "用户aea3",
+  "message": "Here is the image",
+  "media_files": [{"path": "/tmp/photo.jpg"}]
+})
+```
+
+**规则：**
+- 从当前 chat_id 中提取 `group_code`（例如 `group:535168412` → `535168412`）
+- 如果已知 user_id，可直接通过 `user_id` 参数传入以跳过查找
+- 如果多个用户匹配该名称，工具会返回候选列表——请让用户进一步确认
+- 不要使用 `send_message` 工具发送 Yuanbao 私信——请使用 `yb_send_dm`
+- 支持媒体：图片（.jpg/.png/.gif/.webp/.bmp）以图片消息形式发送，其他文件以文档形式发送
+
+## 查询群组信息
+
+```json
+yb_query_group_info({ "group_code": "328306697" })
+```
+
+## 查询成员
+
+| 操作 | 说明 |
+|--------|-------------|
+| `find` | 按名称搜索（部分匹配，不区分大小写） |
+| `list_bots` | 列出机器人和 Yuanbao AI 助手 |
+| `list_all` | 列出所有成员 |
+
+## 注意事项
+
+- `group_code` 来自 chat_id：`group:328306697` → `328306697`
+- 在 Yuanbao 应用中，群组称为"派（Pai）"
+- 成员角色：`user`、`yuanbao_ai`、`bot`

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/tui.md

@@ -0,0 +1,256 @@
+---
+sidebar_position: 2
+title: "TUI"
+description: "启动 Hermes 的现代终端 UI——支持鼠标操作、丰富的浮层面板和非阻塞输入。"
+---
+
+# TUI
+
+TUI 是 Hermes 的现代前端——一个终端 UI（用户界面），与 [Classic CLI](cli.md) 共享同一 Python 运行时。相同的 agent、相同的会话、相同的斜杠命令；交互界面更简洁、响应更流畅。
+
+这是以交互方式运行 Hermes 的推荐方式。
+
+## 启动
+
+```bash
+# 启动 TUI
+hermes --tui
+
+# 恢复最近的 TUI 会话（若无则回退到最近的 classic 会话）
+hermes --tui -c
+hermes --tui --continue
+
+# 通过 ID 或标题恢复指定会话
+hermes --tui -r 20260409_000000_aa11bb
+hermes --tui --resume "my t0p session"
+
+# 直接运行源码——跳过预构建步骤（供 TUI 贡献者使用）
+hermes --tui --dev
+```
+
+也可以通过环境变量启用：
+
+```bash
+export HERMES_TUI=1
+hermes          # 现在使用 TUI
+hermes chat     # 同上
+```
+
+Classic CLI 仍作为默认方式保留。[CLI 界面](cli.md)中记录的所有内容——斜杠命令、快捷命令、skill 预加载、personality、多行输入、中断——在 TUI 中均完全一致。
+
+## 为什么选择 TUI
+
+- **即时首帧** — banner 在应用加载完成前就已渲染，因此 Hermes 启动时终端不会出现卡顿感。
+- **非阻塞输入** — 会话就绪前即可输入并排队消息。agent 上线后立即发送第一条 prompt（提示词）。
+- **丰富的浮层面板** — 模型选择器、会话选择器、审批和澄清提示均以模态面板形式渲染，而非内联流程。
+- **实时会话面板** — 工具和 skill 在初始化过程中逐步填充。
+- **鼠标友好的选择** — 拖拽高亮时使用统一背景色，而非 SGR 反色。使用终端的常规复制手势即可复制。
+- **备用屏幕渲染** — 差量更新意味着流式传输时无闪烁，退出后无滚动历史残留。
+- **编辑器增强** — 长片段的内联折叠粘贴、`Cmd+V` / `Ctrl+V` 文本粘贴（带剪贴板图片回退）、括号粘贴安全保护，以及图片/文件路径附件规范化。
+
+同样的 [skins](features/skins.md) 和 [personalities](features/personality.md) 均适用。会话中途使用 `/skin ares`、`/personality pirate` 切换，UI 实时重绘。完整的可定制键列表及其对 classic 与 TUI 的适用范围，请参阅 [Skins & Themes](features/skins.md)——TUI 支持 banner 调色板、UI 颜色、prompt 字形/颜色、会话显示、补全菜单、选区背景色、`tool_prefix` 和 `help_header`。
+
+### 可折叠的 banner 区块
+
+TUI 启动 banner 将运行时信息分为四个可折叠区块，每个区块标题旁渲染 `▸` / `▾` 折叠箭头：
+
+| 区块 | 默认状态 |
+|------|---------|
+| Tools | 展开 |
+| Skills | 折叠 |
+| System Prompt | 折叠 |
+| MCP Servers | 折叠 |
+
+点击区块标题（或其折叠箭头）的任意位置即可切换展开/折叠状态。Tools 列表默认展开，因为它是会话开始时最常查看的区块；Skills、System Prompt 和 MCP Servers 默认折叠，即使安装了大量 skill 或接入了多个 MCP server，banner 也能保持紧凑。状态仅对当前 banner 实例有效，下次启动将重置为默认值。
+
+## 环境要求
+
+- **Node.js** ≥ 20 — TUI 作为从 Python CLI 启动的子进程运行。`hermes doctor` 会验证此项。
+- **TTY** — 与 classic CLI 一样，通过管道传入 stdin 或在非交互式环境中运行时，将回退到单次查询模式。
+
+首次启动时，Hermes 会将 TUI 的 Node 依赖安装到 `ui-tui/node_modules`（一次性操作，耗时数秒）。后续启动速度很快。拉取新版 Hermes 后，若源文件比 dist 更新，TUI bundle 将自动重新构建。
+
+### 外部预构建
+
+发行版若附带预构建 bundle（如 Nix、系统包），可将 Hermes 指向该 bundle：
+
+```bash
+export HERMES_TUI_DIR=/path/to/prebuilt/ui-tui
+hermes --tui
+```
+
+该目录必须包含 `dist/entry.js`。
+
+## 快捷键
+
+快捷键与 [Classic CLI](cli.md#keybindings) 完全一致。仅有以下行为差异：
+
+- **`Ctrl+T`** — 将输入框上方的实时子智能体栏展开为完整 `/agents` 列表；**Enter/t** 查看实时日志，**`d`** 查看详细信息，**`e`** 引导，**`x`** 停止选中的工作者。可见行数随终端高度调整，关闭后保留输入草稿。
+- **`F7`** — 在多行预览和单行摘要之间切换，保留输入焦点，不写入配置。
+- **鼠标拖拽** — 以统一选区背景色高亮文本。
+- **`Cmd+V` / `Ctrl+V`** — 优先尝试普通文本粘贴，然后回退到 OSC52/原生剪贴板读取，最后在剪贴板或粘贴内容解析为图片时进行图片附件操作。
+- **`/terminal-setup`** — 安装本地 VS Code / Cursor / Windsurf 终端绑定，以在 macOS 上获得更好的 `Cmd+Enter` 和撤销/重做一致性。
+- **斜杠自动补全** — 以带描述的浮动面板形式展开，而非内联下拉菜单。
+- **`Ctrl+X`** — 当排队消息被高亮（在 agent 仍在运行时发送的消息）时，从队列中删除该消息。**`Esc`** 取消编辑并取消高亮，但不删除。
+- **`Ctrl+G` / `Ctrl+X Ctrl+E`** — 在 `$EDITOR` 中打开当前输入缓冲区，用于多行/长 prompt 编写；保存并退出后，内容将作为 prompt 发送回来。
+
+## 斜杠命令
+
+所有斜杠命令均可正常使用。部分命令由 TUI 独有——它们会产生更丰富的输出或以浮层而非内联面板形式渲染：
+
+| 命令 | TUI 行为 |
+|------|---------|
+| `/help` | 带分类命令的浮层，可用方向键导航 |
+| `/sessions` | 模态会话选择器——预览、标题、token 总量、内联恢复 |
+| `/model` | 按提供商分组的模态模型选择器，带费用提示 |
+| `/skin` | 实时预览——浏览时主题变更即时生效 |
+| `/details` | 切换详细工具调用详情（全局或按区块） |
+| `/usage` | 丰富的 token / 费用 / 上下文面板 |
+| `/agents`（别名 `/tasks`） | 可观测性浮层——带终止/暂停控制的实时子 agent 树、按分支的费用/token/文件汇总、逐轮历史记录 |
+| `/reload` | 将 `~/.hermes/.env` 重新读入运行中的 TUI 进程，使新添加的 API 密钥无需重启即可生效 |
+| `/mouse [on\|off\|toggle\|wheel\|buttons\|all]` | 在运行时选择鼠标跟踪预设（同时持久化到 `config.yaml` 的 `display.mouse_tracking`）。`wheel`（1000+1006）保留滚轮滚动而不产生悬停事件，避免在 tmux 中向 prompt 行发送"No image in clipboard"垃圾信息；`buttons` 添加 1002 以支持终端侧拖拽选择；`all` 是带悬停 UI 的默认值。 |
+
+其他所有斜杠命令（包括已安装的 skill、快捷命令和 personality 切换）与 classic CLI 完全一致。请参阅[斜杠命令参考](../reference/slash-commands.md)。
+
+## LaTeX 数学渲染
+
+TUI 的 Markdown 渲染管线支持内联 LaTeX 数学：`$E = mc^2$` 和 `$$\frac{a}{b}$$` 渲染为 Unicode 格式的数学表达式，而非原始 TeX 源码。支持内联和块级数学；不支持的语法将回退为显示包裹在代码 span 中的原始 TeX，以保持可复制性。
+
+此功能始终开启，无需配置。Classic CLI 保留原始 TeX。
+
+## 浅色终端检测
+
+TUI 自动检测浅色终端并相应切换到浅色主题。检测分三层进行：
+
+1. `HERMES_TUI_THEME` 环境变量——最高优先级。可选值：`light`、`dark`，或原始 6 位背景十六进制色值（如 `ffffff`、`1a1a2e`）。
+2. `COLORFGBG` 环境变量——xterm 衍生终端使用的经典"背景色查询"提示。
+3. 通过 OSC 11 探测终端背景——适用于不设置 `COLORFGBG` 的现代终端（Ghostty、Warp、iTerm2、WezTerm、Kitty）。
+
+若要无论终端如何都永久使用浅色主题：
+
+```bash
+export HERMES_TUI_THEME=light
+```
+
+## 忙碌指示器样式
+
+状态栏忙碌指示器可插拔——默认在 agent 工作期间每 2.5 秒轮换一次 Hermes 的 kawaii 表情调色板。通过配置或 `/indicator` 斜杠命令选择不同样式：
+
+```yaml
+display:
+  tui_status_indicator: kaomoji   # kaomoji | emoji | unicode | ascii
+```
+
+或在会话中：`/indicator emoji`（等）。各样式附带匹配的字形宽度，轮换时状态栏其余部分不会抖动。
+
+## 自动恢复
+
+默认情况下，`hermes --tui` 每次启动都会开启新会话。若要自动重新连接到最近的 TUI 会话（在终端或 SSH 连接意外断开时很有用），可选择启用：
+
+```bash
+export HERMES_TUI_RESUME=1          # 最近的 TUI 会话
+# 或：
+export HERMES_TUI_RESUME=<session-id>   # 指定会话
+```
+
+取消设置该变量，或在每次启动时显式传入 `--resume <id>` 以覆盖。
+
+## 状态栏
+
+TUI 的状态栏实时跟踪 agent 状态：
+
+| 状态 | 含义 |
+|------|------|
+| `starting agent…` | 会话 ID 已激活；工具和 skill 仍在上线中。可以输入——消息将排队，就绪后发送。 |
+| `ready` | Agent 空闲，等待输入。 |
+| `thinking…` / `running…` | Agent 正在推理或运行工具。 |
+| `interrupted` | 当前轮次已取消；按 Enter 重新发送。 |
+| `forging session…` / `resuming…` | 初始连接或 `--resume` 握手中。 |
+
+各 skin 的状态栏颜色和阈值与 classic CLI 共享——请参阅 [Skins](features/skins.md) 了解自定义方式。
+
+状态栏还显示：
+
+- **工作目录及 git 分支** — `~/projects/hermes-agent (docs/two-week-gap-sweep)`。在旁边的终端执行 `git checkout` 时，分支后缀会更新（mtime 缓存），TUI 反映的是实际活跃分支，而非启动时的分支。
+- **每条 prompt 的耗时** — 轮次运行时显示 `⏱ 12s/3m 45s`（实时），轮次完成后冻结为 `⏲ 32s / 3m 45s`。第一个数字是自上次用户消息以来的时间；第二个是会话总时长。每次新 prompt 时重置。
+- **`🗜️ N`** — 当前会话被自动压缩的次数。首次压缩触发后显示。
+- **`▶ N`** — 当前会话中正在运行的 `/bg` 任务数量。至少有一个任务在执行时显示。
+- **`⚠ YOLO`** — 每当 YOLO 模式开启时（`hermes --yolo`、`/yolo` 或 `HERMES_YOLO_MODE=1`）显示的可见警告。同一徽章也出现在启动 banner 中，确保你不会在未注意到的情况下启动自动审批会话。
+
+## 配置
+
+TUI 遵循所有标准 Hermes 配置：`~/.hermes/config.yaml`、profile、personality、skin、快捷命令、凭证池、内存提供商、工具/skill 启用状态。不存在 TUI 专属配置文件。
+
+少数键专门用于调整 TUI 界面：
+
+```yaml
+display:
+  skin: default              # 任意内置或自定义 skin
+  personality: helpful
+  details_mode: collapsed    # hidden | collapsed | expanded — 全局折叠面板默认值
+  sections:                  # 可选：按区块覆盖（任意子集）
+    thinking: expanded       # 始终展开
+    tools: expanded          # 始终展开
+    activity: collapsed      # 重新启用 activity 面板（默认隐藏）
+  mouse_tracking: all        # off | wheel | buttons | all（或 true/false 以向后兼容）
+                             #   wheel   — 1000+1006（滚轮+点击；无拖拽，无悬停——
+                             #             在 tmux 内推荐使用，可消除悬停事件导致的
+                             #             prompt 行"No image in clipboard"垃圾信息）
+                             #   buttons — 添加 1002 以支持终端侧拖拽选择
+                             #   all     — 添加 1003 以支持悬停（滚动条悬停翻页、
+                             #             链接 mouseenter 等）
+```
+
+运行时切换：
+
+- `/details [hidden|collapsed|expanded|cycle]` — 设置全局模式
+- `/details <section> [hidden|collapsed|expanded|reset]` — 覆盖单个区块
+  （区块：`thinking`、`tools`、`subagents`、`activity`）
+
+**默认可见性**
+
+TUI 附带有主见的按区块默认值，将轮次以实时转录形式流式展示，而非一堆折叠箭头：
+
+- `thinking` — **展开**。推理过程随模型输出内联流式显示。
+- `tools` — **展开**。工具调用及其结果以展开状态渲染。
+- `subagents` — 沿用全局 `details_mode`（默认折叠在箭头下——在实际发生委托之前保持安静）。
+- `activity` — **隐藏**。环境元信息（gateway 提示、终端一致性提醒、后台通知）对日常使用来说是噪音。工具失败仍会在失败的工具行内联渲染；当所有面板均隐藏时，环境错误/警告通过浮动警告兜底显示。
+
+按区块覆盖优先于区块默认值和全局 `details_mode`。调整布局的方式：
+
+- `display.sections.thinking: collapsed` — 将 thinking 折叠到箭头下
+- `display.sections.tools: collapsed` — 将工具调用折叠到箭头下
+- `display.sections.activity: collapsed` — 重新启用 activity 面板
+- 运行时使用 `/details <section> <mode>`
+
+在 `display.sections` 中显式设置的内容优先于默认值，因此现有配置保持不变。
+
+## 会话
+
+会话在 TUI 和 classic CLI 之间共享——两者均写入同一个 `~/.hermes/state.db`。可以在一个界面开始会话，在另一个界面恢复。会话选择器显示来自两个来源的会话，并带有来源标签。
+
+会话生命周期、搜索、压缩和导出，请参阅[会话](sessions.md)。
+
+## TUI 如何与其 gateway 通信
+
+默认情况下，TUI 会在进程内启动自己的 gateway，因此每个 TUI 实例是自包含的——无需任何配置。
+
+你可能会在代码或日志中看到 `HERMES_TUI_GATEWAY_URL` 环境变量。它是 **Web 仪表板的内部接线细节**，并非面向用户的远程连接开关。当你打开仪表板的 "Chat" 标签页（`hermes dashboard` → `/chat`）时，仪表板的 Web 服务器会派生一个内嵌的 TUI 子进程，并注入 `HERMES_TUI_GATEWAY_URL`，让该子进程通过本地回环 WebSocket（`/api/ws`）连接到仪表板自己的进程内 `tui_gateway`。`/api/ws` 端点仅存在于仪表板服务器内部（`hermes_cli/web_server.py`），并绑定到该进程的生命周期和认证。
+
+不存在通用的"将任意 TUI 指向任意独立 gateway 端口"的模式。特别是，OpenAI 兼容 API 服务器（`hermes gateway` / `api_server` 平台）**不**提供 `/api/ws`——它是模型后端接口（`/v1/chat/completions`、`/v1/models` 等），并刻意不暴露 TUI 的 JSON-RPC 控制通道。将 `HERMES_TUI_GATEWAY_URL` 设置为该端口将返回 404。
+
+如果你希望多个界面共享同一组会话，请使用共享的 `~/.hermes/state.db`（参见[会话](sessions.md)）或 Web 仪表板的内嵌聊天（参见 [Web Dashboard](features/web-dashboard.md#chat)）——而不是手动设置 gateway URL。
+
+## 回退到 Classic CLI
+
+不带 `--tui` 启动 `hermes` 将继续使用 classic CLI。若要让某台机器默认使用 TUI，在 shell profile 中设置 `HERMES_TUI=1`。若要回退，取消设置即可。
+
+如果 TUI 启动失败（无 Node、缺少 bundle、TTY 问题），Hermes 会打印诊断信息并回退——而不是让你陷入困境。
+
+## 另请参阅
+
+- [CLI 界面](cli.md) — 完整的斜杠命令和快捷键参考（共享）
+- [会话](sessions.md) — 恢复、分支和历史记录
+- [Skins & Themes](features/skins.md) — 自定义 banner、状态栏和浮层主题
+- [语音模式](features/voice-mode.md) — 在两种界面中均可使用
+- [配置](configuration.md) — 所有配置键