Metadata-Version: 2.4
Name: bugx-agent
Version: 0.10.0
Summary: Host-neutral adversarial white-box and black-box auditing agent
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: tui
Requires-Dist: pexpect==4.9.0; extra == "tui"
Provides-Extra: graph
Requires-Dist: tree-sitter-language-pack==1.14.3; extra == "graph"
Dynamic: license-file

# BugX

> **Version 0.10.0**

BugX 是装进 AI 编程工具里的代码审计 Agent。

它不是另一个需要你学习的 CLI。你只需安装一次，之后直接在 AI 工具里说你想检查什么；
AI 会自己读代码、跑测试、调用 BugX 并给出有证据的结果。

## 快速开始

### 1. 安装

全局安装 BugX CLI：

```bash
npm install -g @bencibro/bugx
```

然后在 IDE 打开的项目终端里运行：

```bash
bugx install
```

BugX 会自动发现本机已安装的 AI 工具。选择“安装到全部已检测 Agent”即可：

- 已有且没变化的入口：跳过；
- 没有的入口：添加；
- 旧版本入口：更新。

这一步只安装 BugX Agent，不会启动 AI，也不会开始审计。

Windows/Codex 若已有宿主管理的 `.agents` 链接，BugX 会保留它；ChatGPT 安装会把 Marketplace
写入链接目标目录，其他插件实体仍写入项目内。请在实际项目目录运行命令，不要把用户目录当作项目根目录。

### 2. 在 AI 工具里启动 BugX

打开刚才的项目，在 AI 工具里选择 BugX：

- OpenCode：输入 `@bugx`；
- Codex：选择 BugX Skill；
- Claude Code：选择 BugX Agent；
- Cline、ZCode、Pi、ChatGPT、DeepSeek Harness：选择对应的 BugX Agent、Skill 或插件。

如果刚打开时看不到 BugX，重启一次 AI 工具。

### 第 4 步：开始你的第一次审计

直接把这句话发给 AI：

```text
请使用 BugX 检查当前项目。
先只读分析，不要修改代码。
发现问题时给出文件位置、复现步骤、证据、影响和严重程度。
```

从这里开始由 AI 主导，不需要你继续敲 BugX 命令。

## 什么时候用 BugX？

### 上线前检查

```text
请使用 BugX 做一次完整项目审计，重点检查业务逻辑、边界条件、安全风险和测试覆盖。
```

### 遇到具体 Bug

```text
请使用 BugX 复现这个问题，找到根因并验证修复：
<粘贴问题描述>
```

### 检查修复或测试

```text
请使用 BugX 验证这个修复是否真的有效，并检查现有测试能否防止问题再次出现。
```

第一次使用时，AI 可能会询问是否只在本地运行、是否允许修改、是否允许提交。
按你的需要选择即可。

## 卸载

在 IDE 的项目终端里运行：

```bash
bugx uninstall
```

想先预览会删除什么：

```bash
bugx uninstall --dry-run
```

<!-- 每次提交代码都必须同步更新受影响文档；默认递增补丁版本；跨版本时使用 --confirm-version-transition。 -->
