feat: add proxy discovery foundation

.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  go:
+    name: Go
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+
+      - name: Check formatting
+        run: test -z "$(gofmt -l .)"
+
+      - name: Test
+        run: go test ./...
+
+      - name: Build
+        run: go build ./cmd/plugproxy

.gitignore

@@ -0,0 +1,12 @@
+# Binaries
+bin/
+dist/
+*.exe
+
+# Local/editor state
+.idea/
+.vscode/
+
+# Logs
+*.log
+

AGENTS.md

@@ -0,0 +1,58 @@
+# AGENTS.md
+
+## 项目说明
+
+plugproxy 是一个 Go 语言轻量代理采集、检测、代理池管理和接入工具。项目目标是先提供稳定 CLI 和 HTTP API，再演进到轻量前端管理面板。
+
+## 文档规则
+
+- 默认使用中文。
+- `README.md` 保持仓库入口性质，只放项目简介、快速命令和文档索引。
+- 详细文档默认放到 `docs/` 目录。
+- 新增设计文档、路线图、规范和方案时，优先创建或更新 `docs/*.md`。
+
+## Go 规则
+
+- 遵循 Google Go 风格。
+- 提交前运行 `gofmt`。
+- 提交前运行 `go test ./...`。
+- 标准库优先，谨慎增加第三方依赖。
+- 并发代码必须支持 `context.Context` 取消，避免 goroutine 泄漏。
+- 公共模型和 SDK 相关代码放在 `pkg/`，内部实现放在 `internal/`。
+
+## GitHub 规则
+
+- 默认使用 GitHub CLI：`gh`。
+- 创建、查看、推送仓库和 PR 时优先使用 `gh`。
+- 当前仓库使用 GitHub Actions 作为 CI/CD。
+- 所有非临时改动默认先创建 issue，再基于 issue 创建分支和 PR。
+- PR 描述需要关联 issue，例如 `Closes #123`。
+- PR 检查没有问题后启用自动合并。
+- 合并后删除已合并分支。
+- 不要在没有明确要求时改写 Git 历史。
+- 不要回滚用户未明确要求回滚的改动。
+
+## 常用命令
+
+```bash
+go test ./...
+go build -o bin/plugproxy ./cmd/plugproxy
+go run ./cmd/plugproxy version
+go run ./cmd/plugproxy fetch
+go run ./cmd/plugproxy list
+go run ./cmd/plugproxy run -addr 127.0.0.1:8899
+```
+
+## 当前架构
+
+```text
+cmd/plugproxy/       CLI 入口
+internal/app/        应用编排
+internal/checker/    代理检测
+internal/fetcher/    并发代理源采集
+internal/pool/       代理池接口与内存实现
+internal/server/     轻量 HTTP API
+internal/source/     代理源接口与实现
+pkg/model/           公开代理数据模型
+docs/                项目文档
+```

README.md

@@ -1,5 +1,121 @@
 # plugproxy
 
-Lightweight proxy crawling, checking, pooling, and integration toolkit written in Go.
+plugproxy 是一个使用 Go 编写的轻量级代理采集、检测、代理池管理和接入工具。
 
-> Status: early design and initialization.
+> 当前状态：早期设计与项目初始化阶段。
+
+## 目标
+
+- 从多种免费代理源采集代理。
+- 并发检测代理，并保留有价值的健康状态与元数据。
+- 通过 CLI、HTTP API 和 Go SDK 让任何项目都能轻松接入代理池。
+- 支持 GitHub、Web、Raw URL 和可选 AI 搜索发现候选代理源。
+- 以 worker pool 支持高并发抓取、验证和检测。
+- 保持轻量：单个 Go 二进制，无强制外部服务依赖。
+
+## 架构
+
+```mermaid
+flowchart LR
+    subgraph Discovery["代理源发现"]
+        GH["GitHub API\nREADME / sources / fetcher"]
+        WEB["Web Search\n可选 AI Provider"]
+        RAW["Raw URL\nTXT / JSON / HTML"]
+        AI["AI Analyst\n搜索规划 / 结果理解 / 规则草案"]
+    end
+
+    subgraph Candidates["候选源层"]
+        CS["CandidateSource\n候选待审"]
+        VR["Validate Workers\n抽样验证 / 去重 / 打分"]
+        SR["SourceRecipe\n解析规则草案"]
+    end
+
+    subgraph Fetch["采集与检测"]
+        SRC["Source Adapter\nRaw / JSON / HTML / API"]
+        FW["Fetch Workers\n高并发采集"]
+        CK["Check Workers\n高并发检测"]
+        POOL["Proxy Pool\n健康评分 / 策略选择"]
+    end
+
+    subgraph Access["接入层"]
+        CLI["CLI"]
+        API["HTTP API"]
+        SDK["Go SDK"]
+        UI["轻量管理面板\n后续"]
+    end
+
+    GH --> CS
+    WEB --> AI --> CS
+    RAW --> CS
+    CS --> VR --> SR
+    SR --> SRC
+    SRC --> FW --> CK --> POOL
+    POOL --> CLI
+    POOL --> API
+    POOL --> SDK
+    POOL --> UI
+```
+
+## 逻辑链
+
+```text
+discover -> candidates -> validate -> review -> source config -> fetch -> check -> pool -> CLI / HTTP API / SDK
+```
+
+plugproxy 的核心原则是“发现候选源”和“使用可用代理”分离。AI、GitHub 搜索和页面分析只进入候选源队列；代理必须经过抽样验证、采集、检测和健康评分后，才会进入代理池。
+
+## 扩展点
+
+- `AIProvider`：适配 OpenAI、Responses-compatible 服务，以及后续 Anthropic、Gemini、OpenRouter、Ollama 等。
+- `Source`：适配 Raw TXT、JSON、HTML 表格、公开 API 和项目源码引用的页面型源。
+- `Checker`：扩展 HTTP、HTTPS、SOCKS4、SOCKS5 和多目标检测。
+- `Pool`：扩展内存池、持久化池、健康评分和选择策略。
+- `Access`：扩展 CLI、HTTP API、Go SDK 和后续嵌入式前端管理面板。
+
+## 当前命令
+
+```bash
+go run ./cmd/plugproxy version
+go run ./cmd/plugproxy fetch
+go run ./cmd/plugproxy list
+go run ./cmd/plugproxy get
+go run ./cmd/plugproxy check -workers 32 -target https://httpbin.org/ip -timeout 8s
+go run ./cmd/plugproxy run -addr 127.0.0.1:8899
+go run ./cmd/plugproxy discover repo jhao104/proxy_pool -workers 32
+go run ./cmd/plugproxy discover url https://raw.githubusercontent.com/gfpcom/free-proxy-list/main/sources/http.txt
+go run ./cmd/plugproxy discover search -query "free proxy list socks5" -limit 10 -workers 32
+go run ./cmd/plugproxy discover validate candidates.json -workers 128
+```
+
+运行后可用的 HTTP API：
+
+```text
+GET /health
+GET /proxies
+GET /proxy
+GET /proxy?protocol=http
+GET /proxy?strategy=fastest
+```
+
+## 项目结构
+
+```text
+cmd/plugproxy/       CLI 入口
+internal/app/        应用编排
+internal/checker/    代理检测
+internal/fetcher/    并发代理源采集
+internal/pool/       代理池接口与内存实现
+internal/server/     轻量 HTTP API
+internal/source/     代理源接口与实现
+internal/discover/   代理源发现、验证和 AI Provider
+pkg/model/           公开代理数据模型
+docs/                项目文档
+```
+
+## 文档
+
+- [项目约定](docs/project-conventions.md)
+- [GitHub Actions CI/CD](docs/ci-cd.md)
+- [代理源清单](docs/proxy-sources.md)
+- [代理源发现爬虫设计](docs/source-discovery.md)
+- [开发路线图](docs/roadmap.md)