添加说明

.gitignore

@@ -27,3 +27,4 @@ go.work.sum
 
 # default build target
 bloomtool
+test/

.vscode/launch.json

@@ -0,0 +1,15 @@
+{
+    // 使用 IntelliSense 了解相关属性。 
+    // 悬停以查看现有属性的描述。
+    // 欲了解更多信息，请访问: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "debug",
+            "type": "go",
+            "request": "launch",
+            "mode": "auto",
+            "program": "${fileDirname}"
+        }
+    ]
+}

README.md

@@ -1,3 +1,144 @@
-# bloomtool
+# BloomTool - 布隆过滤器工具
 
-布隆过滤器工具
+BloomTool 是一个基于 Go 语言开发的布隆过滤器命令行工具，用于高效地创建、测试和管理布隆过滤器。
+
+## 功能特性
+
+- **高性能**: 使用 RoaringBitmap 库实现高效的位图存储
+- **低误判率**: 支持自定义误判率，默认千万分之一
+- **大容量**: 支持最多 100 亿个元素
+- **简单易用**: 命令行界面，操作简单
+
+## 安装
+
+```bash
+go install git.algo.com.cn/public/bloomtool@latest
+```
+
+## 命令说明
+
+### 1. makebloom - 创建布隆过滤器
+
+从文本文件创建布隆过滤器位图文件。
+
+**语法:**
+```bash
+bloomtool makebloom -d <设备ID文件> -b <位图输出文件> [-e <最大元素数>] [-r <误判率>]
+```
+
+**参数:**
+- `-d`: 设备ID文本文件路径（每行一个ID）
+- `-b`: 布隆过滤器位图输出文件路径
+- `-e`: 最大元素数量（0表示自动计算，最大100亿）
+- `-r`: 误判率（0.01-0.000000001，默认0.00000001）
+
+**示例:**
+```bash
+bloomtool makebloom -d devices.txt -b bloom.blm
+bloomtool makebloom -d devices.txt -b bloom.blm -e 1000000 -r 0.001
+```
+
+### 2. hittest - 命中测试
+
+测试文本文件中的行是否在布隆过滤器中存在。
+
+**语法:**
+```bash
+bloomtool hittest -d <测试文件> -b <位图文件> -s <状态输出文件> [-f]
+```
+
+**参数:**
+- `-d`: 测试文本文件路径（每行一个要测试的ID）
+- `-b`: 布隆过滤器位图文件路径
+- `-s`: 状态输出文件路径
+- `-f`: 仅输出命中的行（过滤模式）
+
+**输出格式:**
+- 默认：每行输出 "<原始文本>\t<命中状态>"（0表示未命中，1表示命中）
+- 使用 `-f` 参数：仅输出命中的原始文本行
+
+**示例:**
+```bash
+bloomtool hittest -d test_ids.txt -b bloom.blm -s result.txt
+bloomtool hittest -d test_ids.txt -b bloom.blm -s hits_only.txt -f
+```
+
+### 3. info - 查看位图信息
+
+显示布隆过滤器位图文件的详细信息。
+
+**语法:**
+```bash
+bloomtool info -b <位图文件>
+```
+
+**参数:**
+- `-b`: 布隆过滤器位图文件路径
+
+**示例:**
+```bash
+bloomtool info -b bloom.blm
+```
+
+### 4. help - 帮助信息
+
+显示命令使用帮助。
+
+**语法:**
+```bash
+bloomtool help
+bloomtool [command] -help
+```
+
+## 使用示例
+
+### 完整工作流程
+
+1. **创建布隆过滤器**
+```bash
+# 从设备ID列表创建布隆过滤器
+bloomtool makebloom -d device_list.txt -b device_bloom.blm
+```
+
+2. **测试设备ID**
+```bash
+# 测试一批设备ID是否在过滤器中
+bloomtool hittest -d test_devices.txt -b device_bloom.blm -s test_results.txt
+```
+
+3. **查看过滤器信息**
+```bash
+# 查看布隆过滤器的统计信息
+bloomtool info -b device_bloom.blm
+```
+
+## 文件格式说明
+
+### 输入文件格式
+- 文本文件，每行一个字符串（如设备ID）
+- 支持任意文本格式，建议使用MD5等哈希值
+
+### 输出文件格式
+- 布隆过滤器位图文件：二进制格式，包含布隆过滤器数据
+- 状态输出文件：文本格式，包含测试结果
+
+## 性能特点
+
+- **内存效率**: 使用压缩位图技术，节省内存空间
+- **查询速度**: 常数时间复杂度的查询操作
+- **误判率可控**: 可根据需求调整误判率
+- **大容量支持**: 支持海量数据处理
+
+## 注意事项
+
+1. 布隆过滤器存在一定的误判率，但不会漏判
+2. 不支持从布隆过滤器中删除元素
+3. 位图文件大小与元素数量和误判率相关
+4. 建议对输入数据进行哈希处理以提高性能
+
+## 依赖项
+
+- Go 1.23+
+- github.com/RoaringBitmap/roaring
+- github.com/klauspost/compress
+- google.golang.org/protobuf

bloomtool.code-workspace

@@ -0,0 +1,7 @@
+{
+	"folders": [
+		{
+			"path": "."
+		}
+	]
+}