refactor: unify types facade, split into sub-files, fix CI

.github/workflows/ci.yml

@@ -34,13 +34,17 @@ jobs:
           go list -m all | tee modules.txt
           ! grep -E '=>|00010101000000|000000000000' modules.txt
 
-      - name: Run tests
-        run: |
-          go test -timeout 20m ./...
-          if [ -d cmd ]; then
-            go test -timeout 20m ./cmd/...
-            go build ./cmd/...
-          fi
+      - name: Run tests (L1 root module)
+        run: go test -timeout 20m ./...
+
+      - name: Run tests (L2 gogo)
+        run: cd gogo && go test -timeout 20m ./...
+
+      - name: Run tests (L2 spray)
+        run: cd spray && go test -timeout 20m ./...
+
+      - name: Run tests (L2 zombie)
+        run: cd zombie && go test -timeout 20m ./...
 
   consumer-build:
     name: External consumer build
@@ -77,5 +81,8 @@ jobs:
           EOF
           go mod edit -require=github.com/chainreactors/sdk@v0.0.0
           go mod edit -replace=github.com/chainreactors/sdk="$GITHUB_WORKSPACE"
+          go mod edit -replace=github.com/chainreactors/sdk/gogo="$GITHUB_WORKSPACE/gogo"
+          go mod edit -replace=github.com/chainreactors/sdk/spray="$GITHUB_WORKSPACE/spray"
+          go mod edit -replace=github.com/chainreactors/sdk/zombie="$GITHUB_WORKSPACE/zombie"
           go mod tidy
           go build .

CHANGELOG.md

@@ -1,5 +1,93 @@
 # Changelog
 
+## v0.4.0 (2026-07-08)
+
+L1/L2 引擎解耦，types 包统一重构，消除上游类型泄漏。
+
+### Breaking Changes
+
+**types 包重组**
+
+- `types.VulnResult` 重命名为 `types.TemplateResult`，对应方法 `ExecuteResult.VulnResult()` → `ExecuteResult.TemplateResult()`
+- `types.NeutronResult` 已删除。`ExecuteResult.Value()` 现在直接返回 `*types.OperatorResult`，不再需要 `.Result` 二次解引用
+- `ExecuteResult.Result()` 方法已删除，用 `ExecuteResult.Value()` 替代
+- 新增 `ExecuteResult.Events()` 方法获取协议级事件（原先通过 `Result().Events` 访问）
+
+```go
+// 之前
+nr := execResult.Result()           // *NeutronResult
+op := nr.Result                     // *OperatorResult
+events := nr.Events                 // []*ResultEvent
+vr := execResult.VulnResult(target) // *VulnResult
+
+// 现在
+op := execResult.Value()              // *OperatorResult (直接)
+events := execResult.Events()         // []*ResultEvent
+tr := execResult.TemplateResult(target) // *TemplateResult
+```
+
+**Context API 统一为 `WithX`**
+
+- 全部引擎的 Context setter 方法从 `SetX` 统一为 `WithX`（与 fingers 一致）
+- `fingers.Config.SetEnableEngines` → `WithEnableEngines`
+
+```go
+// 之前
+gogo.NewContext().SetThreads(500).SetProxy("socks5://...")
+spray.NewContext().SetTimeout(10).SetMod("path")
+
+// 现在
+gogo.NewContext().WithThreads(500).WithProxy("socks5://...")
+spray.NewContext().WithTimeout(10).WithMod("path")
+```
+
+**ExportFilter 迁移**
+
+- `types.ExportFilter` / `types.NewExportFilter()` → `cyberhub.ExportFilter` / `cyberhub.NewExportFilter()`
+- `types.ReviewStatus*` 常量 → `cyberhub.ReviewStatus*`
+
+**类型清理**
+
+- 移除 `types.ZombieMod*` 常量（与 `zombie.ModeBomb`/`ModePitchFork`/`ModeSniper` 重复）
+- 移除 fingers 内部类型别名：`FingerMapper`、`FingerFavicons`、`FingerContent`、`FingerRegexp`、`FingersMatchEngine`、`FingersLibEngine`
+- 保留扩展点：`FingerSender`、`FingerCallback`
+
+**L2 引擎模块隔离**
+
+- `gogo`、`spray`、`zombie` 各自拥有独立 `go.mod`，通过 `go get github.com/chainreactors/sdk/gogo` 单独引入
+- L2 引擎的 Option 类型从 `types` 包迁移到各自引擎包：
+  - `types.NewDefaultGogoOption()` / `types.CloneGogoOption()` → `gogo.NewDefaultGogoOption()` / `gogo.CloneGogoOption()`
+  - `types.SprayOption` / `types.NewDefaultSprayOption()` / `types.CloneSprayOption()` → `spray` 包内部使用，外部通过 `Context.WithOption()` 配置
+  - `types.NewDefaultZombieOption()` / `types.CloneZombieOption()` → `zombie.NewDefaultOption()` / `zombie.CloneOption()`
+- L2 引擎新增 `init()` 自注册 + `FromClient()` 访问器 + `WithClientConfig()` 配置注入
+
+### New Features
+
+**types 统一暴露**
+
+- `pkg/types` 拆分为语义化子文件：`scan.go`、`finger.go`、`template.go`、`neutron.go`、`proton.go`，核心接口保留在 `types.go`
+- 新增 `types.TemplateEvent` 别名，消除 `VulnResult`（现 `TemplateResult`）对上游 `parsers` 包的直接依赖
+- 新增 `types.ReadRaw` 函数，消费者不再需要直接 import `github.com/chainreactors/utils/httputils`
+
+**Client 注册表**
+
+- 新增 `client.Register()` / `client.Lookup()` 全局引擎工厂注册表
+- L2 引擎通过 `init()` 自注册，`import _ "github.com/chainreactors/sdk/gogo"` 即可使用
+- `client.Engine(name)` 按名称访问扩展引擎，支持延迟初始化
+
+### Bug Fixes
+
+- **CI**: L2 模块（gogo/spray/zombie）测试之前未被 CI 执行，现已补充独立测试步骤
+- **CI**: consumer-build 缺少 L2 模块的 `replace` 指令导致无法构建
+- **go vet**: 修复 gogo/spray 测试中 `context.WithTimeout` 返回的 cancel 函数未调用的警告
+
+### Dependencies
+
+- `fingers` → `3e22b6a528b9`
+- `neutron/operators/full` → `f57d0a560e32`（与 neutron 同步）
+- `proton` → `471f99ea6131`
+- `utils` → `8aa6ca296863`
+
 ## v0.3.3 (2026-06-16)
 
 新增 association 模糊搜索机制，支持对索引内所有实体的子串模糊匹配；修复 CyberHub POC 导出默认状态过滤导致零结果的问题。

README.md

@@ -45,7 +45,7 @@ defer c.Close()
 
 // 获取引擎 — 依赖自动注入
 // GoGo 自动获得 Fingers + Neutron 引擎
-gogoEng, _ := c.Gogo()
+gogoEng, _ := gogo.FromClient(c)
 results, _ := gogoEng.Scan(gogo.NewContext().SetThreads(1000), "192.168.1.0/24", "80,443")
 
 // 关联查询 — 扫描结果直接查关联 POC
@@ -113,17 +113,17 @@ for _, t := range engine.Get() {
 // GoGo - 端口扫描（Provider 自动加载 Fingers 和 Neutron）
 gogoConfig := gogo.NewConfig().
     WithProvider(cyberhub.NewProvider("http://127.0.0.1:8080", "your_key"))
-gogoEngine := gogo.NewEngine(gogoConfig)
+gogoEngine, _ := gogo.NewEngine(gogoConfig)
 results, _ := gogoEngine.Scan(gogo.NewContext(), "192.168.1.0/24", "80,443")
 
 // Spray - HTTP 检测
-sprayEngine := spray.NewEngine(nil)
+sprayEngine, _ := spray.NewEngine(nil)
 results, _ := sprayEngine.Check(spray.NewContext(), []string{"http://example.com"})
 
 // Zombie - 弱口令检测
-zombieEngine := zombie.NewEngine(nil)
-task := zombie.NewWeakpassTask([]zombie.Target{{IP: "192.168.1.1", Port: "22", Service: "ssh"}})
-results, _ := zombieEngine.Weakpass(zombie.NewContext(), task)
+zombieEngine, _ := zombie.NewEngine(nil)
+targets := []zombie.Target{{IP: "192.168.1.1", Port: "22", Service: "ssh"}}
+results, _ := zombieEngine.Brute(zombie.NewContext(), targets, []string{"root"}, []string{"123456"})
 ```
 
 ## 架构设计
@@ -157,6 +157,7 @@ SDK 采用四组件架构，定义在 `pkg/types/types.go`：
 
 - 引擎懒加载，首次访问时创建
 - 依赖自动注入（GoGo ← Fingers + Neutron，Spray ← Fingers）
+- 扩展引擎通过 `client.Register` 反向注册，Client 不直接导入 L2 引擎包
 - Index 是可选的关联查询层，通过 `WithIndex` 开启
 
 ### 数据源
@@ -176,19 +177,20 @@ client.WithResourceProvider(rp)         // 共享资源加载器
 client.WithIndex(opts)                  // 开启关联索引（可选）
 client.WithFingersConfig(cfg)           // 覆盖 Fingers 配置
 client.WithNeutronConfig(cfg)           // 覆盖 Neutron 配置
-client.WithGogoConfig(cfg)              // 覆盖 GoGo 配置
-client.WithSprayConfig(cfg)             // 覆盖 Spray 配置
-client.WithZombieConfig(cfg)            // 覆盖 Zombie 配置
+gogo.WithClientConfig(cfg)              // 覆盖 GoGo 配置
+spray.WithClientConfig(cfg)             // 覆盖 Spray 配置
+zombie.WithClientConfig(cfg)            // 覆盖 Zombie 配置
 ```
 
 ### 引擎访问
 
 ```go
 c.Fingers()  // *fingers.Engine
 c.Neutron()  // *neutron.Engine
-c.Gogo()     // *gogo.GogoEngine
-c.Spray()    // *spray.SprayEngine
-c.Zombie()   // *zombie.Engine
+gogo.FromClient(c)     // *gogo.Engine
+spray.FromClient(c)    // *spray.Engine
+zombie.FromClient(c)   // *zombie.Engine
+c.Engine("name")       // types.Engine，用于自定义注册引擎
 ```
 
 ### 关联查询
@@ -300,9 +302,9 @@ go build -o bin/association ./association
 - `client/` — 统一客户端（依赖注入、关联查询）
 - `fingers/` — 指纹识别引擎
 - `neutron/` — POC 扫描引擎
-- `gogo/` — 端口扫描引擎
-- `spray/` — HTTP 检测引擎
-- `zombie/` — 弱口令检测引擎
+- `gogo/` — 端口扫描引擎（独立 Go module，反向注册到 Client）
+- `spray/` — HTTP 检测引擎（独立 Go module，反向注册到 Client）
+- `zombie/` — 弱口令检测引擎（独立 Go module，反向注册到 Client）
 - `pkg/types/` — 核心接口（Engine / Provider / Context / Task / Result）
 - `pkg/cyberhub/` — CyberHub 远程数据源
 - `pkg/provider/` — 内置数据源（EmbedProvider / FileProvider / URLProvider）
@@ -330,8 +332,8 @@ go test ./...
 ### 添加新引擎
 
 1. 实现 `pkg/types` 中的 Engine / Context / Task / Result 接口
-2. 创建引擎包（engine.go / types.go / init.go）
-3. 在 `client/client.go` 中添加 ensure 方法和访问器
+2. 在引擎包中调用 `client.Register(name, factory)` 反向注册
+3. 提供 `WithClientConfig` / `FromClient` 这类类型安全的薄封装
 4. 在 `examples/` 中添加示例
 
 ## License