Secbot UI 设计与交互

当前仓库只保留一个前端实现：terminal-ui。

terminal-ui 是基于 Ink + React 的终端 TUI，通过 HTTP 和 SSE 连接 NestJS 后端。仓库当前没有 app/ 移动端或 desktop/ 桌面端目录，因此本文档不再描述 Expo、React Native、Tauri 或浏览器 UI。

1. 技术栈

TUI 支持两类后端连接模式：

模式	行为	使用场景
`spawn`	TUI 自动启动本地 `server/dist/main.js` 子进程	本地完整产品体验，默认
`service` / `remote`	TUI 只连接已有后端	后端单独部署或调试

配置方式：

# 默认：自动拉起本地后端
npm run start:tui

# 连接已有后端
SECBOT_TUI_BACKEND=service SECBOT_API_URL=http://127.0.0.1:8000 npm run start:tui

spawn 模式会把后端子进程日志写入 logs/backend-runtime.log，避免污染终端 UI。

文件	职责
`terminal-ui/src/cli.tsx`	解析 CLI 参数和后端模式，启动 Ink 渲染
`terminal-ui/src/backendSpawn.ts`	分配端口、启动本地后端、等待 `/api/system/info` 可用
`terminal-ui/src/App.tsx`	TUI 根组件、全局布局和退出逻辑
`terminal-ui/src/MainContent.tsx`	主内容区渲染
`terminal-ui/src/useChat.ts`	聊天状态、SSE 事件处理、会话消息流
`terminal-ui/src/sse.ts`	SSE 请求和事件解析
`terminal-ui/src/api.ts`	REST API 调用
`terminal-ui/src/slash.ts`	斜杠命令解析与补全

TUI 的主界面围绕三块区域组织：

主内容区会把后端 SSE 事件转换为统一的内容块，再交给 ContentBlock / blocks/* 渲染。这样可以把报告、代码、表格、工具结果、错误等结构化内容拆开维护。

POST /api/chat 返回 SSE。TUI 主要处理这些事件：

事件	UI 行为
`connected`	标记连接已建立
`planning`	展示计划或 Todo
`thought_start` / `thought_chunk` / `thought`	展示推理过程
`action_start` / `action_result`	展示工具执行过程与结果
`content`	渲染结构化内容块
`report`	渲染最终或阶段性报告
`phase`	更新当前阶段
`root_required`	打开 root 权限确认对话框
`error`	展示错误块
`response`	展示最终回复
`done`	标记本轮完成

事件解析集中在 useChat.ts，渲染细节集中在 components/blocks/，避免把网络状态和 UI 表现耦合在一起。

输入 / 会触发命令补全。常用命令包括：

命令实现位于 terminal-ui/src/slash.ts，部分命令会打开对话框，部分命令会调用 REST API。

主要对话框位于 terminal-ui/src/components/：

对话框状态通过 contexts/DialogContext.tsx 管理，Toast 通过 contexts/ToastContext.tsx 管理。

当前 TUI 的全局状态拆在 terminal-ui/src/contexts/：

入口处由 AllProviders 统一包裹应用，新增全局能力时优先放到独立 Context，而不是继续扩大 App.tsx。

terminal-ui/src/components/blocks/ 保存结构化块渲染器，例如：

如果新增后端 content 类型，推荐流程是：

Ink 依赖 TTY raw mode。若在 IDE 集成终端、CI 或无 TTY 子进程中启动，TUI 可能无法进入交互状态。Windows 下仓库提供：

.\scripts\start-cli.ps1

也可以双击 scripts/start-cli.bat，它会打开新的系统终端窗口。