快速开始

按当前 release 仓库真实存在的 server 与 terminal-ui 链路启动 SecBot。

本文档介绍当前 release 分支支持的完整运行方式：SecBot Desktop 桌面客户端、Terminal UI 终端交互、独立后端服务以及自动化基准测试。

0. 桌面版安装（最推荐的用户界面）

对于大多数日常安全测试与交互场景，推荐直接下载安装 SecBot Desktop 桌面版：

前往 GitHub Releases（标签形如 desktop-app-v*）；
根据您的操作系统下载对应安装包：
- macOS Apple Silicon: .dmg
- Windows x64: .exe (NSIS 安装包)
- Ubuntu / Linux x64: .deb 或 .AppImage
安装并启动后，设置面板内可直观切换模型后端、调节主题与查验系统状态。

亦可下载免环境依赖的 TUI 独立自包含压缩包（secbot-tui-<version>-<platform>.tar.gz），解压后直接执行 ./secbot 即可运行。

1. 源码运行环境要求

Node.js >= 24
npm >= 10
真实终端 TTY（运行 Ink TUI 时需要；Windows 推荐 Windows Terminal / PowerShell）
Docker & Docker Compose（运行靶场基准测试时需要）
可选：Ollama（仅在使用本地模型时需要）

2. 配置模型

在仓库根目录创建 .env。当前仓库没有 .env.example，下面是最小示例。

使用 DeepSeek：

LLM_PROVIDER=deepseek
DEEPSEEK_API_KEY=sk-your-api-key
DEEPSEEK_MODEL=deepseek-chat

使用 Ollama：

LLM_PROVIDER=ollama
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llama3.2
OLLAMA_EMBEDDING_MODEL=nomic-embed-text

说明：

TUI 里可以通过 /model 修改 provider、API Key、Base URL 和模型。
通过 TUI 保存的配置会写入 SQLite / config.yaml，后续启动会优先使用已保存配置。

3. 从源码启动完整 TUI

git clone https://github.com/iammm0/secbot.git
cd secbot
npm install
npm run start:stack

npm run start:stack 会先构建后端，再启动 terminal-ui。TUI 默认使用 spawn 模式，也就是在本地自动拉起一个 NestJS 后端子进程，并通过 /api/chat 的 SSE 流展示规划、推理、工具执行和最终报告。

也可以直接运行：

npm start

npm start 只启动已经构建好的后端；如果你想进入 TUI，优先使用 npm run start:stack 或 npm run start:tui。

4. 只启动后端 API

适合 API 调试、自动化脚本或把 TUI 连接到已有服务。

npm run dev

或构建后运行：

npm run build
node server/dist/main.js

默认地址：

Base URL：http://127.0.0.1:8000
健康检查：GET /health
系统信息：GET /api/system/info

当前后端没有注册 Swagger UI，因此不要依赖 /docs 页面。

5. 单独启动 `terminal-ui`

默认 terminal-ui 会自行启动本地后端子进程：

npm run build
npm run start:tui

如果后端已经在运行，并且你只想让 TUI 连接已有服务，请使用 service 模式：

SECBOT_TUI_BACKEND=service SECBOT_API_URL=http://127.0.0.1:8000 npm run start:tui

也可以在 terminal-ui/ 目录中直接运行：

cd terminal-ui
npm install
npm run tui

6. 从 GitHub Releases 安装

从 GitHub Releases 下载 .tgz（当前 v2.0.0-b2）。包内元数据名称为 @opensec/secbot，但不会发布到 npmjs。

npm install -g ./opensec-secbot-2.0.0-b2.tgz
secbot

或一次性运行：

npx ./opensec-secbot-2.0.0-b2.tgz

后端专用入口：

secbot-server

7. 常见命令

npm run build              # 构建 server/dist
npm run build:terminal-ui  # 构建 terminal-ui/dist
npm run typecheck          # TypeScript 类型检查
npm test                   # 运行 vitest 自动化测试
npm run start:stack        # 构建并进入 TUI
npm run start:tui          # 启动 TUI
npm run bench:standard     # 运行 15 项标准权威基准测试 (Pass@1 评测)

8. 常见问题

8.1 TUI 没有进入全屏界面

Ink 需要真实 TTY。请在系统终端中运行，不要在没有 TTY 的 IDE 子进程里直接启动。Windows 下可以使用：

.\scripts\start-cli.ps1

或双击 scripts/start-cli.bat。

8.2 TUI 提示找不到后端构建

默认 spawn 模式需要 server/dist/main.js。先在仓库根目录执行：

npm run build

8.3 service 模式连接失败

确认后端已启动，并检查：

curl http://127.0.0.1:8000/health
curl http://127.0.0.1:8000/api/system/info

如果后端不在本机或端口不是 8000，请同步修改 SECBOT_API_URL。

8.4 Ollama 连接失败

请确认：

Ollama 服务已启动。
OLLAMA_BASE_URL 指向正确地址。
OLLAMA_MODEL 指定的模型已存在，或可由 Ollama 拉取。

更详细说明见 OLLAMA_SETUP.md。