# 网安智能体

**Repository Path**: Free_520/cybersecurity-agent

## Basic Information

- **Project Name**: 网安智能体
- **Description**: 网安渗透专用智能体
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-30
- **Last Updated**: 2026-11-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 时纯 Shichun Security

面向安全分析场景的 LangGraph Agent 工程基座。当前是**第一阶段**：打通
“模型接入 → 多轮对话 → 标准化结构化输出 → 双通道回写”的最小闭环，为后续
工具层、审批门、角色拆分、子代理和 Monitor 机制提供稳定接口。

## 当前能力

- Python 3.11–3.13 + LangGraph 状态图（不是裸写 prompt 循环）
- OpenAI 兼容接口：DeepSeek / 本地 vLLM / 其他兼容端点，`base_url`、模型、超时均可配
- Pydantic v2 `StandardOutput` 强校验，格式失败自动修复重试一次
- 多轮上下文通过 LangGraph checkpoint 保留，`thread_id` 即会话
- 一条输出、两个通道：
  - `answer` 分片展示给用户；
  - 完整 `StandardOutput` JSON 写回 state，供后续节点消费
- 正文 + JSON 同屏显示；`/state` 可检查当前 state
- 真实 token 流诊断命令 `shichun probe`（绕过结构化中间件）
- 内置离线演示 `shichun demo`，没有 API key 也能验证整条链路
- 76 个离线测试（单轮、多轮、重试、超时、schema、state、CLI、真实传输适配器）

## 快速开始

### 方式 A：一键脚本（Windows PowerShell）

```powershell
pwsh -File scripts/bootstrap.ps1
```

脚本会创建 `.venv`、安装依赖、从模板生成 `.env`、运行环境检查和离线 demo。
随后编辑 `.env`：

```dotenv
SHICHUN_LLM__BASE_URL=https://api.deepseek.com/v1
SHICHUN_LLM__API_KEY=sk-your-key
SHICHUN_LLM__MODEL=deepseek-chat
```

### 方式 B：手动安装

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"

Copy-Item .env.example .env
# 编辑 .env，填入 key

python -m shichun config
python -m shichun demo
```

> 本机无法直连 PyPI 时，可加
> `--index-url https://mirrors.aliyun.com/pypi/simple`。
> 不要提交 `.env`；`.gitignore` 已忽略它。

### 运行

```powershell
# 交互式多轮，/exit /quit 退出
python -m shichun

# 单轮：终端同时显示正文与 StandardOutput JSON
python -m shichun ask "解释一下什么是 IDOR，以及如何验证"

# 离线，不访问网络，不需要 key
python -m shichun demo

# 真实 token 流诊断（不经过结构化中间件）
python -m shichun probe "用三句话说明这个项目的第一阶段目标"

# 查看脱敏配置与依赖版本
python -m shichun config
```

也可以直接运行 `python main.py`（PyCharm 绿色运行按钮可用），它会把 `src/`
加入路径；安装后的正式入口是 `shichun`。

## 数据流

```text
用户输入
  |
  v
ChatRuntime.ask()
  |  thread_id = session_id
  v
LangGraph StateGraph (ShichunState, MemorySaver checkpoint)
  |
  v
AgentNode (system prompt + 已持久化的 messages)
  |
  v
OutputMiddleware
  |-- llm.with_structured_output(StandardOutput, include_raw=True)
  |-- Pydantic 校验
  |-- 格式失败：追加修复提示，自动重试 1 次
  |-- 通过：分片展示 answer，返回 MiddlewareResult
  v
build_success_update()
  |-- messages += AIMessage(answer)          -> 用户/上下文
  |-- structured_output = StandardOutput JSON -> 后续节点
  v
LangGraph checkpoint
```

### 关于“流式”的边界

`with_structured_output` 必须先拿到完整对象才能做 Pydantic 校验。因此第一阶段
主链路采用**结构化优先 + 校验后分片展示**，而不是把未校验的 JSON 片段直接当
答案输出。真实 token 流通过 `shichun probe` / `stream_model_text()` 暴露，供
4 号负责人做后续流式接入。这个取舍记录在
[docs/adr/0002-structured-before-streaming.md](docs/adr/0002-structured-before-streaming.md)。

## 目录

```text
src/shichun/
├── config.py              # 唯一配置入口（.env / 环境变量 / 脱敏）
├── errors.py              # 领域异常
├── messages.py            # 消息/退出命令工具
├── schemas/
│   ├── output.py          # StandardOutput（冻结契约）
│   └── state.py           # ShichunState（LangGraph 全局状态）
├── prompts/phase1.py      # phase-1 system / repair prompt
├── llm/factory.py         # ChatOpenAI 构造、结构化绑定、真实流
├── middleware/
│   ├── output.py          # OutputMiddleware：校验、修复、展示
│   └── parsing.py         # JSON 清洗与安全解析
├── graph/
│   ├── builder.py         # 单节点图编译
│   ├── nodes.py           # AgentNode
│   ├── writeback.py       # 结构化结果 → state
│   └── runtime.py         # 会话、thread、TurnResult
└── cli/
    ├── main.py            # 命令、交互循环、错误码
    ├── render.py          # Rich 输出
    └── demo.py            # 离线假模型（仅 demo/测试）

tests/                     # 单元 + 集成测试，不需要网络
scripts/                   # bootstrap / check
skills/                    # 额外组：环境/事务/工具型渗透 Skill（规格与样例）
docs/                      # 架构、契约、分工、验收、ADR
```

## 配置

所有配置都走 `SHICHUN_<分组>__<字段>`，完整模板见
[.env.example](.env.example)。最常用的几项：

| 变量 | 默认值 | 说明 |
| --- | --- | --- |
| `SHICHUN_LLM__BASE_URL` | `https://api.deepseek.com/v1` | OpenAI 兼容端点 |
| `SHICHUN_LLM__API_KEY` | 空 | 必填；本机回环地址可用 `EMPTY` |
| `SHICHUN_LLM__MODEL` | `deepseek-chat` | 模型名 |
| `SHICHUN_LLM__STRUCTURED_METHOD` | `function_calling` | DeepSeek 用工具调用；vLLM 可试 `json_mode` |
| `SHICHUN_LLM__STRUCTURED_MAX_ATTEMPTS` | `2` | 首次 + 一次格式修复 |
| `SHICHUN_LLM__TIMEOUT_SECONDS` | `60` | 模型超时 |
| `SHICHUN_RUNTIME__MAX_INPUT_CHARS` | `12000` | 单条输入上限 |

优先级：命令行参数 > 进程环境变量 > `.env` > 代码默认值。

## 验收与质量门

```powershell
# 完整质量门（ruff + pytest，可选 mypy）
pwsh -File scripts/check.ps1

# 或者
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m ruff check .
.\.venv\Scripts\python.exe -m ruff format --check .
```

本机离线测试结果：**76 passed**。真实模型验收需要填入 key 后执行
[`docs/phase1-acceptance.md`](docs/phase1-acceptance.md) 中的 Live 检查项。

## 给 1–8 号负责人

**0 基础同学先看**：[docs/team/README.md](docs/team/README.md)，里面是逐号任务卡、
第一周节奏、Git 抄作业流程和汇报模板。

**额外渗透 Skill 组**：看 [docs/team/pentest-skills.md](docs/team/pentest-skills.md)，
了解环境型 / 事务型 / 工具型 Skill 的职责边界，以及
[skills/README.md](skills/README.md) 的目录规范。

再读：

- [docs/architecture.md](docs/architecture.md)：分层、数据流、扩展点
- [docs/contracts.md](docs/contracts.md)：冻结接口与修改规则
- [docs/ownership.md](docs/ownership.md)：1–8 号职责、文件边界、分支与合并顺序
- [docs/phase1-acceptance.md](docs/phase1-acceptance.md)：验收矩阵与真实模型测试步骤
- [docs/onboarding.md](docs/onboarding.md)：Windows/PyCharm/代理/镜像/常见错误

**并行开发约定**：`StandardOutput`、state key、`OutputMiddleware.run()` 返回值和
配置变量名是冻结契约；需要变更时先改文档 + 通知主负责人，不要各自改字段。
各负责人的 feature 分支只动自己文件边界内的代码，跨边界改动走 PR 评审。

## 安全与授权

本项目用于**已获授权的安全测试与防御研究**。第一阶段没有接入 nuclei、nmap
或任何执行类工具；不要在未授权目标上使用后续能力。详见
[SECURITY.md](SECURITY.md)。

## 仓库

Gitee: <https://gitee.com/Free_520/cybersecurity-agent>

一期基座已提交到 `master` 分支；团队分支与合并策略见
[docs/ownership.md](docs/ownership.md)。密钥只放本地 `.env` 或 CI secret，
不进入 Git。