Skip to content

Commit c5b8e4b

Browse files
iammm0iammm0
committed
docs: 优化 npm 平台 README 展示与使用说明
1 parent c984ed6 commit c5b8e4b

1 file changed

Lines changed: 81 additions & 215 deletions

File tree

‎README.md‎

Lines changed: 81 additions & 215 deletions
Original file line numberDiff line numberDiff line change
@@ -1,264 +1,130 @@
1-
<div align="center">
2-
3-
<h1 style="font-size: 3em; font-weight: bold; margin-bottom: 10px;">
4-
Secbot
5-
</h1>
6-
7-
<p style="font-size: 1.2em; color: #666; margin-bottom: 20px;">
8-
<strong>AI 驱动的自动化安全测试工作台</strong>
9-
</p>
10-
11-
<p>
12-
<a href="https://nodejs.org/">
13-
<img src="https://img.shields.io/badge/Node.js-18%2B-339933.svg" alt="Node.js">
14-
</a>
15-
<a href="https://www.typescriptlang.org/">
16-
<img src="https://img.shields.io/badge/TypeScript-5.x-3178C6.svg" alt="TypeScript">
17-
</a>
18-
<a href="package.json">
19-
<img src="https://img.shields.io/badge/version-2.0.3-brightgreen.svg" alt="Version">
20-
</a>
21-
<a href="LICENSE">
22-
<img src="https://img.shields.io/badge/license-Custom-orange.svg" alt="License">
23-
</a>
24-
<a href="https://github.com/iammm0/secbot/releases">
25-
<img src="https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey.svg" alt="Platform">
26-
</a>
27-
</p>
28-
29-
<p>
30-
<a href="https://nestjs.com/">
31-
<img src="https://img.shields.io/badge/NestJS-11-E0234E.svg" alt="NestJS">
32-
</a>
33-
<a href="https://www.sqlite.org/">
34-
<img src="https://img.shields.io/badge/SQLite-3.x-003B57.svg" alt="SQLite">
35-
</a>
36-
<a href="https://github.com/vadimdemedes/ink">
37-
<img src="https://img.shields.io/badge/Ink-4.4%2B-FF69B4.svg" alt="Ink">
38-
</a>
39-
</p>
40-
41-
<p>
42-
<a href="README_EN.md">English</a> | 中文
43-
</p>
44-
45-
</div>
46-
47-
---
48-
49-
> **安全警告**：本工具仅用于**获得明确授权**的安全测试、研究与教学。未经授权的网络攻击、渗透、爆破或控制行为可能违法。详见 [docs/SECURITY_WARNING.md](docs/SECURITY_WARNING.md)。
50-
51-
---
52-
53-
## 功能概览
54-
55-
- **统一后端**：基于 NestJS 暴露 REST + SSE 接口，CLI/TUI 共用同一套编排与事件流。
56-
- **多智能体执行**：支持 `secbot-cli` 自动模式与 `superhackbot` 专家模式，结合规划、执行、总结链路完成安全任务。
57-
- **安全测试能力**：覆盖内网发现、端口与服务识别、Web 安全、OSINT、系统控制、防御扫描与报告生成，共 54 个工具。
58-
- **多推理后端**：内置 Ollama、DeepSeek、OpenAI 及多家 OpenAI 兼容厂商支持。
59-
- **终端 TUI**：基于 Ink + React 的全屏终端交互界面。
60-
- **SQLite 持久化**：对话历史、提示词链、用户偏好和 API Key 配置可持久化到 SQLite。
61-
- **记忆与知识**：短期/长期/情景记忆子系统，向量存储与语义检索。
62-
- **漏洞数据库**：统一漏洞 schema，适配 CVE/NVD/Exploit-DB/MITRE ATT&CK。
63-
64-
## 架构概览
65-
66-
```mermaid
67-
flowchart LR
68-
tui["terminal-ui (Ink)"]
69-
tui --> api["NestJS /api/*"]
70-
71-
api --> chat["ChatModule"]
72-
chat --> agents["AgentsModule"]
73-
agents --> tools["ToolsModule (54 工具)"]
74-
tools --> db["DatabaseModule (SQLite)"]
75-
agents --> memory["MemoryModule"]
76-
agents --> summary["SummaryAgent"]
77-
summary --> sse["SSE 事件流"]
78-
sse --> tui
79-
```
1+
# @opensec/secbot (TypeScript)
2+
3+
[![npm version](https://img.shields.io/npm/v/@opensec/secbot.svg)](https://www.npmjs.com/package/@opensec/secbot)
4+
[![npm downloads](https://img.shields.io/npm/dm/@opensec/secbot.svg)](https://www.npmjs.com/package/@opensec/secbot)
5+
[![Node.js](https://img.shields.io/badge/node-%3E%3D20-339933.svg)](https://nodejs.org/)
6+
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
7+
8+
Secbot is an AI-powered TypeScript security automation workspace with a NestJS backend and an Ink-based terminal UI.
9+
10+
> Security notice: this package is for authorized security testing, research, and education only. Do not run scans or exploitation tasks against targets without explicit permission.
11+
12+
![Secbot main UI](https://raw.githubusercontent.com/iammm0/secbot/main-ts-version/assets/secbot-main.png)
8013

81-
更细的 UI 与事件流说明见 [docs/UI-DESIGN-AND-INTERACTION.md](docs/UI-DESIGN-AND-INTERACTION.md)，API 细节见 [docs/API.md](docs/API.md)。
14+
## Why This Package
8215

83-
## 环境要求
16+
- End-to-end TypeScript architecture (`NestJS + Ink + SQLite`).
17+
- `secbot` binary that starts backend + terminal UI as one product workflow.
18+
- `secbot-server` binary for backend-only API scenarios.
19+
- Multi-agent orchestration with planning, tool execution, and summarization.
20+
- Built-in security tool modules for web, network, OSINT, defense, and reporting workflows.
8421

85-
- **Node.js** `18+`（后端与所有前端均需要）
86-
- **npm**（随 Node.js 附带）
87-
- **Ollama**（可选，本地模型时需要）
22+
## Requirements
8823

89-
## 安装与启动
24+
- Node.js `>= 20`
25+
- npm `>= 10` (recommended)
26+
- Optional: Ollama for local model serving
9027

91-
### 方式一：从 npm 安装
28+
## Install
29+
30+
### Global install (recommended)
9231

9332
```bash
9433
npm install -g @opensec/secbot
95-
secbot
9634
```
9735

98-
### 方式二：从源码运行（推荐开发使用）
36+
### One-off run with npx
9937

10038
```bash
101-
git clone https://github.com/iammm0/secbot.git
102-
cd secbot
103-
npm install
39+
npx @opensec/secbot
10440
```
10541

106-
创建 `.env`，至少填写一组可用推理后端配置：
42+
## Quick Start
43+
44+
### 1. Configure environment variables
45+
46+
Create a `.env` file in your working directory:
10747

10848
```env
109-
# 云端推理（默认推荐）
49+
# Cloud model backend (recommended)
11050
LLM_PROVIDER=deepseek
11151
DEEPSEEK_API_KEY=sk-your-api-key
11252
DEEPSEEK_MODEL=deepseek-reasoner
11353
114-
# 或改用本地 Ollama
54+
# Optional local backend (Ollama)
11555
# LLM_PROVIDER=ollama
11656
# OLLAMA_BASE_URL=http://localhost:11434
11757
# OLLAMA_MODEL=gemma3:1b
11858
```
11959

120-
启动完整终端体验：
60+
### 2. Start full product mode (backend + TUI)
12161

12262
```bash
123-
# 一键启动后端 + TUI
124-
npm run start:stack
125-
126-
# 或分步启动
127-
npm run dev # 启动后端（开发模式，热重载）
128-
npm run start:tui # 在另一终端启动 TUI
63+
secbot
12964
```
13065

131-
### 方式三：下载 GitHub Release
132-
133-
从 [Releases](https://github.com/iammm0/secbot/releases) 下载 npm 打包产物（`.tgz`），解压后运行。
134-
135-
更详细的发布包说明见 [docs/RELEASE.md](docs/RELEASE.md)。
136-
137-
## 快速开始
138-
139-
### 1. 常见开发入口
66+
### 3. Start backend only (optional)
14067

14168
```bash
142-
# 开发模式（后端热重载）
143-
npm run dev
144-
145-
# 生产构建
146-
npm run build
147-
npm start
148-
149-
# 终端 TUI
150-
npm run start:tui
69+
secbot-server
15170
```
15271

153-
### 2. 常用环境变量
154-
155-
| 变量 | 用途 | 默认值 |
156-
|------|------|--------|
157-
| `LLM_PROVIDER` | 当前推理后端 | `deepseek` |
158-
| `DEEPSEEK_API_KEY` | DeepSeek API Key | 无 |
159-
| `DEEPSEEK_MODEL` | DeepSeek 默认模型 | `deepseek-reasoner` |
160-
| `OLLAMA_BASE_URL` | Ollama 服务地址 | `http://localhost:11434` |
161-
| `OLLAMA_MODEL` | Ollama 默认模型 | `gemma3:1b` |
162-
| `PORT` | 后端监听端口 | `8000` |
163-
164-
### 3. 常见斜杠命令（TUI 内使用）
165-
166-
| 命令 | 说明 |
167-
|------|------|
168-
| `/model` | 选择推理后端、模型、API Key、Base URL |
169-
| `/agent` | 切换 `secbot-cli` / `superhackbot` |
170-
| `/list-agents` | 查看当前可用智能体 |
171-
| `/system-info` | 查看系统信息 |
172-
| `/db-stats` | 查看 SQLite 统计 |
173-
174-
## 目录结构
175-
176-
```text
177-
secbot/
178-
├── server/ # NestJS 后端
179-
│ └── src/
180-
│ ├── main.ts # 应用入口
181-
│ ├── app.module.ts # 根模块
182-
│ ├── common/ # 公共基础设施（LLM 抽象、过滤器、拦截器）
183-
│ └── modules/ # 业务模块
184-
│ ├── agents/ # 多智能体（Planner/Hackbot/Coordinator/Summary）
185-
│ ├── chat/ # SSE 聊天接口
186-
│ ├── tools/ # 54 个安全工具（10 大类）
187-
│ ├── database/ # SQLite 持久化
188-
│ ├── memory/ # 记忆子系统
189-
│ ├── vuln-db/ # 漏洞数据库
190-
│ ├── network/ # 网络发现与远程控制
191-
│ ├── defense/ # 防御扫描
192-
│ ├── sessions/ # 会话管理
193-
│ ├── system/ # 系统信息与配置
194-
│ ├── crawler/ # 爬虫调度
195-
│ └── health/ # 健康检查
196-
├── npm-bin/ # npm CLI 入口包装
197-
│ ├── secbot.js
198-
│ └── secbot-server.js
199-
├── terminal-ui/ # Ink 终端前端
200-
├── scripts/ # 启动与构建脚本
201-
├── tools/ # 工具能力说明文档
202-
└── docs/ # 项目文档
203-
```
204-
205-
## 开发
72+
### 4. Attach to an existing backend (optional)
20673

20774
```bash
208-
# 类型检查
209-
npm run typecheck
210-
211-
# 代码检查
212-
npm run lint
213-
214-
# 代码格式化
215-
npm run format
216-
217-
# 运行测试
218-
npm test
219-
220-
# 构建
221-
npm run build
75+
SECBOT_API_URL=http://127.0.0.1:8000 secbot
22276
```
22377

224-
## 文档索引
78+
## Package Binaries
79+
80+
| Binary | Description |
81+
| --- | --- |
82+
| `secbot` | Start backend and open terminal UI |
83+
| `secbot-server` | Start NestJS backend only |
22584

226-
| 文档 | 说明 |
227-
|------|------|
228-
| [docs/QUICKSTART.md](docs/QUICKSTART.md) | 快速启动指南 |
229-
| [docs/API.md](docs/API.md) | REST + SSE 接口说明 |
230-
| [docs/LLM_PROVIDERS.md](docs/LLM_PROVIDERS.md) | 多厂商模型后端与配置 |
231-
| [docs/OLLAMA_SETUP.md](docs/OLLAMA_SETUP.md) | 本地 Ollama 配置 |
232-
| [docs/UI-DESIGN-AND-INTERACTION.md](docs/UI-DESIGN-AND-INTERACTION.md) | TUI 交互设计 |
233-
| [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) | 后端部署指南 |
234-
| [docs/RELEASE.md](docs/RELEASE.md) | 发布与打包说明 |
235-
| [docs/DATABASE_GUIDE.md](docs/DATABASE_GUIDE.md) | SQLite 结构与操作 |
236-
| [docs/TOOL_EXTENSION.md](docs/TOOL_EXTENSION.md) | 工具扩展开发指南 |
85+
## Source Development
23786

238-
## 贡献
87+
```bash
88+
git clone https://github.com/iammm0/secbot.git
89+
cd secbot
90+
npm ci
23991

240-
欢迎提交 Issue 和 Pull Request。
92+
# Backend dev (watch mode)
93+
npm run dev
24194

242-
1. Fork 本仓库
243-
2. 创建分支：`git checkout -b feat/your-change`
244-
3. 提交修改：`git commit -m "feat: 新增某功能"`
245-
4. 推送分支并发起 PR
95+
# TUI (in another terminal)
96+
npm run start:tui
97+
```
24698

247-
提交信息遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范。
99+
### Common npm scripts
248100

249-
## 许可证
101+
| Script | Description |
102+
| --- | --- |
103+
| `npm run build` | Build backend and package artifacts |
104+
| `npm run typecheck` | Type-check server code |
105+
| `npm run lint` | Run ESLint |
106+
| `npm run format:check` | Check Prettier formatting |
107+
| `npm test` | Run tests |
108+
| `npm run release:pack` | Build and create npm package tarball |
250109

251-
本项目使用 [LICENSE](LICENSE) 中定义的 **Secbot Open Source License**：
110+
## Documentation
252111

253-
- 允许个人学习、学术研究、教学与非营利技术交流
254-
- 修改与分发时需保留版权与协议声明
255-
- 商业用途需事先获得书面授权
112+
- [Quickstart](https://github.com/iammm0/secbot/blob/main-ts-version/docs/QUICKSTART.md)
113+
- [API Reference](https://github.com/iammm0/secbot/blob/main-ts-version/docs/API.md)
114+
- [LLM Providers](https://github.com/iammm0/secbot/blob/main-ts-version/docs/LLM_PROVIDERS.md)
115+
- [Ollama Setup](https://github.com/iammm0/secbot/blob/main-ts-version/docs/OLLAMA_SETUP.md)
116+
- [UI Interaction Design](https://github.com/iammm0/secbot/blob/main-ts-version/docs/UI-DESIGN-AND-INTERACTION.md)
117+
- [Tool Extension](https://github.com/iammm0/secbot/blob/main-ts-version/docs/TOOL_EXTENSION.md)
118+
- [Release Guide](https://github.com/iammm0/secbot/blob/main-ts-version/docs/RELEASE.md)
119+
- [Security Warning](https://github.com/iammm0/secbot/blob/main-ts-version/docs/SECURITY_WARNING.md)
256120

257-
商用授权联系：[wisewater5419@gmail.com](mailto:wisewater5419@gmail.com)
121+
## Registry Links
258122

259-
## 作者
123+
- npm: [https://www.npmjs.com/package/@opensec/secbot](https://www.npmjs.com/package/@opensec/secbot)
124+
- GitHub Packages: [https://github.com/iammm0/secbot/packages](https://github.com/iammm0/secbot/packages)
125+
- Repository: [https://github.com/iammm0/secbot](https://github.com/iammm0/secbot)
126+
- Issues: [https://github.com/iammm0/secbot/issues](https://github.com/iammm0/secbot/issues)
260127

261-
赵明俊（Zhao Mingjun）
128+
## License
262129

263-
- GitHub: [@iammm0](https://github.com/iammm0)
264-
- Email: [wisewater5419@gmail.com](mailto:wisewater5419@gmail.com)
130+
This project is licensed under MIT. See [LICENSE](LICENSE) for details.

0 commit comments

Comments
 (0)