Argus 用户操作手册

本手册涵盖有效使用 Argus 所需的全部内容——从配置和 Web 控制台到 Prompt 扩展、报告解读和故障排查。

配置

大模型配置

Argus 需要兼容 OpenAI Chat Completions 的大模型 API。通过交互式命令配置：

argus config llm

配置保存在数据库（API Key 加密存储）。后续可通过 Web 控制台管理多个模型配置。

验证连通性：

argus llm check

环境文件格式

LLM_API_KEY=sk-your-key
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL=gpt-4o

高级参数

argus config llm --advanced

额外设置：最大输出 Token 数（默认 4096）、温度（默认 0）、最大重试次数（默认 3）。

服务器配置

服务器配置位于 config/server.yaml：

CORS 域名 — 允许的前端域名
限流 — 按路由限流
SSRF 防护 — 允许的私网 LLM 主机
可观测性 — 请求日志、审计、LLM 追踪开关
调度并发 — 最大并发任务数（默认 4）
WebSocket 限制 — 每事件总线最大订阅数

修改文件后重启 argus serve 生效。

模型配置（通过 Web 控制台）

可将多个 LLM 提供商配置存储在 SQLite 中，API Key 加密存储：

在 Web 控制台中导航到模型配置
点击添加模型，输入 API 地址、模型名称和 API Key
点击测试连接验证
创建任务时选择此模型配置

API Key 使用 Fernet 密钥加密存储，密钥位于 config/.fernet_key。首次启动 argus serve 时自动生成。

Web 控制台

Web 控制台是 Vue 3 SPA，运行 argus serve 后访问 http://localhost:8000/。

构建前端

前端源码位于 frontend/。首次启动前需要构建：

cd frontend
pnpm install
pnpm build
cd ..
argus serve

初始构建后：

仅改 Python → 直接重启 argus serve，无需重新构建
改前端代码 → 再次运行 pnpm build，然后重启 argus serve

页面

仪表盘

显示项目和最近任务的概览及状态。

项目管理

管理测试项目。每个项目可以有：

名称和描述
自定义 Prompt 扩展（参见 Prompt 扩展系统）
关联的任务

任务管理

任务管理中心。功能：

创建任务 — 设置目标、URL、关联项目、模型配置和 Prompt 扩展
任务列表 — 按状态、项目筛选，按目标搜索；白盒任务以类型 whitebox 标识
任务详情 — 页签布局取决于任务类型：

黑盒任务 — 三个页签：

报告页签 — 内联展示 HTML 报告，步骤和截图可折叠，问题清单清晰可见。

执行时间线页签 — 查看完整生命周期：任务创建 → 入队 → 启动 → 每个 Planner/Executor/Evaluator 循环 → 完成。事件通过 WebSocket 实时推送，持久化存储在 SQLite 的 task_events 表。

LLM 调试页签 — 检查任务期间的每次 LLM 调用：
- 阶段、事件类型、模型、主机、耗时、Token 用量
- System Prompt
- 输入 Payload（完整 API 请求）
- 原始响应（完整 API 响应）
- 解析结果（JSON 提取后的结构化输出）
- 错误和解析失败
白盒任务 — 「分析报告」页签展示分析结果（概览指标、端点列表、交互式调用图查看器、发现项、执行流、功能聚类），并带有完整度横幅和分析器诊断面板；「分析日志」页签显示构建/分析进度。白盒任务不调用 LLM，因此没有 LLM 调试页签。

当任务存在关联的黑白盒关联运行时，会显示「关联证据」页签，包含端点证据、发现证据和未匹配 HTTP 请求（见黑白盒关联）。

模型配置

管理 LLM 提供商配置。

Prompt 扩展系统

Argus 将内置 Prompt 与用户自定义业务规则分离。

架构

拼接顺序：内置模板 → 项目扩展 → 任务扩展

内置模板（argus_py/llm/prompts/）— 包含输入字段、输出 JSON Schema 和安全边界的硬契约，不可覆盖
项目扩展 — 存储在项目 parameters.prompt_extensions.{planner,evaluator} 中的自定义规则
任务扩展 — 存储在任务 parameters.prompt_extensions.{planner,evaluator} 中的自定义规则，拼接在项目扩展之后

内置模板末尾的 ## 业务扩展 / ## Business Extensions 标记段即为扩展插入点。

通过 CLI 使用

argus run --goal "..." --url "..." \
  --planner-extension ./my-rules/planner.md \
  --evaluator-extension ./my-rules/evaluator.md

通过 Web 控制台使用

在项目或任务的创建/编辑对话框中，展开 Prompt 业务扩展 折叠面板：

两个 Tab：Planner 和 Evaluator
左侧 Markdown 编辑，右侧实时渲染
底部的预览完整 Prompt按钮调用 POST /argus/api/prompts/preview（600ms 防抖），展示内置 + 项目 + 任务三段拼接后的最终 Prompt

扩展示例

Planner 扩展（针对特定应用）：

## 项目特定规则
- 危险按钮关键词：作废、出库、开账
- 登录页固定为 /auth/signin
- 不要点击 class 为 "disabled" 的元素

Evaluator 扩展：

## 评估规则
- "成功"通知必须包含绿色勾选图标
- 登录后页面标题必须包含"仪表盘"

浏览器登录态管理

需要测试登录后页面时，可以一次保存登录态，跨任务复用。

保存登录态

argus auth save --url "https://example.com/login"

该命令显示浏览器窗口。手动登录后回到终端按 Enter，状态（cookies、localStorage、sessionStorage）保存到 config/browser-states/<name>.json。

列出已保存的登录态

argus auth list

复用登录态

argus run --auth-state example.com \
  --goal "检查个人中心页面是否正常展示" \
  --url "https://example.com/profile"

--auth-state 参数接受状态名称（在 config/browser-states/ 中查找）或 JSON 文件路径。

登录态包含会话凭据。已通过 .gitignore 排除，但仍应按敏感文件对待——不要分享包含登录态的调试包。

报告与执行流程

执行流程

Planner（LLM） 接收测试目标和页面快照，决定下一步浏览器动作
Executor 通过 Playwright 执行动作，采集截图和 DOM 快照
Evaluator（LLM） 评估目标是否达成
若未达成，携带更新后的上下文回到步骤 1
动作失败时，恢复机制重新观察页面并重新规划（最多 2 次重试）
完成后（成功或用尽所有尝试）生成 HTML + JSON 报告

报告输出

outputs/reports/<task_id>/
├── index.html      # 面向人工阅读的 HTML 报告
└── report.json     # 结构化 JSON 报告

HTML 报告特性：

任务摘要、执行步骤、步骤参数、截图、问题清单和错误信息
失败步骤高亮显示
步骤参数和截图可折叠
截图可点击放大
截图尽量使用相对路径引用

JSON 报告包含相同数据的结构化版本，适合下游工具或 API 读取。

报告 API

GET /argus/api/tasks/{task_id}/report    → HTML（默认）或 JSON（?format=json）

截图

默认每个执行步骤都会截图。存储在：

outputs/screenshots/<task_id>/

通过 --no-screenshot 关闭。关闭后，即使规划器输出 screenshot 动作，也只会记录"截图已按任务配置跳过"，不会保存图片。

白盒代码分析

除浏览器测试外，Argus 还可以对 Java 代码库执行静态分析。Python 控制面对源码做快照（Git clone 或本地复制），把解析工作交给 Java Analyzer 服务（Spring Boot + JavaParser + Maven classpath 解析），并将结果渲染为报告。

前置条件

Java Analyzer 服务可达 — 默认 http://localhost:8081，通过环境变量 ARGUS_JAVA_ANALYZER_URL 覆盖。Docker Compose 部署时使用 --profile java 启动。
源码路径必须对分析进程可见且位于允许的源码根目录内（容器部署共享源码卷，见部署指南）。
Maven classpath 解析可以提升分析精度；没有 Maven 时分析自动降级为仅源码模式。

执行分析

# 完整分析 Git 仓库
argus analyze --repo https://github.com/user/project.git

# 本地目录，仅抽取端点
argus analyze --source-path /path/to/project --scope endpoints

分析范围：all（默认，完整分析）、changed（增量变更）、modules（指定 Maven 模块）、endpoints、callgraph、flows、clusters。全部选项见 CLI 参考。

理解分析结果

结果	说明
端点	REST 映射：路径、HTTP 方法、Controller 类/方法、参数
调用图	以 `className#methodName` 为键的方法级调用图
发现项	基于规则、带严重级别的发现
执行流	代码中的 traced 执行路径
功能聚类	相关类的功能聚类
诊断	解析失败和逐 pass 失败/降级记录

可选 pass（flows、clusters）失败时显式降级而不是使任务失败——降级记录在诊断中，并以完整度告警的形式呈现在报告中。

黑白盒关联

黑盒执行期间，Argus 会为浏览器发出的每个请求捕获 HTTP 请求证据（方法、规范化路径、状态码、耗时）。关联运行将这些证据与白盒分析抽取的 REST 端点进行匹配，把 UI 行为链接到服务端代码路径。

工作方式

为黑盒运行创建关联运行，并固定期望的源码快照和分析配置
绑定白盒分析后，捕获的 HTTP 请求与抽取的端点进行匹配
匹配结果保存为端点证据和发现证据，未匹配的请求也会显式列出

查看关联结果

Web 控制台 — 存在关联运行的任务会显示「关联证据」页签，包含端点证据、发现证据和未匹配请求表格
REST API — GET /argus/api/correlation-runs/{id}（另有 summary、attempts 及证据端点）；通过 bind-analysis、retry、recalculate 绑定或重新匹配

关联结果的新鲜度取决于绑定的源码快照。如果被分析的源码与黑盒运行时实际 exercised 的代码不一致，对齐状态会标记 mismatch，而不是静默返回过期结果。

任务可观测性

Argus 为任务执行提供丰富的可观测能力。

执行时间线

每个任务生命周期事件都记录在 SQLite 的 task_events 表中：

任务创建、入队、启动、完成
每个 Planner/Executor/Evaluator 循环
浏览器动作及其结果
报告生成

通过 API 获取：

GET /argus/api/tasks/{task_id}/events

或在 Web 控制台的执行时间线页签中查看（通过 WebSocket 实时更新）。

LLM 调用追踪

每次 LLM 调用（Planner 和 Evaluator）都记录完整上下文：

阶段、事件类型、模型、主机、耗时、Token 用量
完整 System Prompt
输入 Payload（API 请求体）
原始响应（API 响应体）
解析结果（JSON 提取后）
错误和解析失败

存储为 JSONL：

outputs/traces/<task_id>.jsonl