feat(v1.7.0): AI 友好度增强 + 测试补全 (155→309)
核心新增(面向 AI Agent 程序化使用): - 结构化错误码体系:E_CONFIG/E_AUTH/E_NETWORK/E_RATE_LIMIT/E_PARSE/E_EMPTY/E_INPUT/E_INTERNAL classify_error() 自动分类异常,JSON 错误输出含 error_code 字段 - JSON Lines 流式输出 (--stream):每条结果独立一行,AI 可增量处理 - 进度事件 (--progress):JSON Lines 事件流到 stderr(start/cache_hit/fetch_ok/done 等) 测试补全(+154 例,覆盖全部高风险盲区): - HTML 回退搜索路径 (19) - --fetch 自动抓取 (21) - --verify 健康检查 (15) - 输出格式化 (15) - 实例解析链 (20) - 并行多实例搜索 (10) - CLI 入口与端到端 (17) - 错误码分类 (27) - 流式输出与进度事件 (10) 源码改进: - search.py: h3 内 a 标签 href 作为 url fallback,提升 SearXNG 主题兼容性 - common.py: 新增 classify_error/emit_progress/set_progress_enabled 文档同步:SKILL.md 新增 AI Agent Integration Guide 章节,README.md 更新参数与错误码表
This commit is contained in:
@@ -55,7 +55,40 @@ AI 调用后,stdout 输出网页正文(text/html/markdown 三种格式),
|
||||
| exit 1 | 失败 | 致命错误(所有实例不可用、参数错误等) |
|
||||
| exit 2 | 空结果 | 搜索成功但无结果 |
|
||||
|
||||
**错误处理**:`--format json` 模式下,错误以 JSON 输出到 stdout(非 stderr),格式为 `{"error": "...", "exit_code": 1}`,AI 可程序化捕获。
|
||||
**错误处理**:`--format json` 模式下,错误以 JSON 输出到 stdout(非 stderr),格式为 `{"error": "...", "error_code": "E_NETWORK", "exit_code": 1, "query": "..."}`,AI 可程序化捕获。
|
||||
|
||||
**错误码体系**(`error_code` 字段):
|
||||
|
||||
| 错误码 | 含义 | AI 恢复策略 |
|
||||
|--------|------|-------------|
|
||||
| `E_CONFIG` | 配置错误(无实例) | 提示用户设置 `-i` / `SEARXNG_INSTANCE` |
|
||||
| `E_AUTH` | 认证失败(401/403) | 检查 token/凭证 |
|
||||
| `E_NETWORK` | 网络错误(连接失败、5xx) | 重试或切换实例/代理 |
|
||||
| `E_RATE_LIMIT` | 限流(429) | 等待后重试 |
|
||||
| `E_PARSE` | 解析错误 | 检查实例 JSON 支持 |
|
||||
| `E_INPUT` | 输入错误(参数/文件) | 修正参数 |
|
||||
| `E_INTERNAL` | 内部错误 | 报告 bug |
|
||||
|
||||
### 流式输出与进度事件(AI 高级用法)
|
||||
|
||||
**`--stream`**:JSON Lines 流式输出,每条结果一行 JSON,AI 可增量处理:
|
||||
```
|
||||
{"type": "result", "result": {"title": "...", "url": "..."}}
|
||||
{"type": "done", "count": 10, "query": "..."}
|
||||
```
|
||||
|
||||
**`--progress`**:进度事件流(JSON Lines 到 stderr),AI 可实时跟踪执行:
|
||||
```
|
||||
{"event": "start", "query": "...", "instances": 2}
|
||||
{"event": "cache_hit", "query": "...", "ttl": 30}
|
||||
{"event": "fetch_ok", "url": "...", "chars": 12345}
|
||||
{"event": "done", "results": 10, "query": "..."}
|
||||
```
|
||||
|
||||
```bash
|
||||
# AI 推荐用法:流式输出 + 进度事件
|
||||
python scripts/search.py -q "research" -i https://your-instance --stream --progress
|
||||
```
|
||||
|
||||
## 部署
|
||||
|
||||
@@ -112,6 +145,8 @@ python scripts/search.py -q "查询词" -i https://your-instance \
|
||||
[--proxy http://corp:8080] \
|
||||
[--auth-bearer-file ~/.token] \
|
||||
[--verify] \
|
||||
[--stream] \
|
||||
[--progress] \
|
||||
[--verbose|-v] [--quiet]
|
||||
```
|
||||
|
||||
@@ -138,6 +173,8 @@ python scripts/search.py -q "查询词" -i https://your-instance \
|
||||
| `--auth-basic-file` | Basic Auth 文件 | — |
|
||||
| `--verify` | 实例健康检查模式 | — |
|
||||
| `--config` | 指定配置文件 | 自动发现 |
|
||||
| `--stream` | JSON Lines 流式输出(每条结果一行) | 关闭 |
|
||||
| `--progress` | 进度事件(JSON Lines 到 stderr) | 关闭 |
|
||||
| `-v / --verbose` | 调试日志 | — |
|
||||
| `--quiet` | 仅输出警告和错误 | — |
|
||||
|
||||
@@ -203,7 +240,10 @@ python scripts/fetch.py -u https://example.com \
|
||||
**工程**
|
||||
- 共享 `common.py`(统一重试/字符集/认证/日志)
|
||||
- 结构化日志(`--verbose` / `--quiet`)
|
||||
- 155 个单元+集成测试
|
||||
- 结构化错误码(`E_NETWORK` / `E_AUTH` / `E_RATE_LIMIT` 等)
|
||||
- JSON Lines 流式输出(`--stream`)
|
||||
- 进度事件(`--progress`,JSON Lines 到 stderr)
|
||||
- 309 个单元+集成测试
|
||||
|
||||
## 跨 Agent 兼容性
|
||||
|
||||
@@ -231,7 +271,7 @@ pip install pytest
|
||||
pytest -q
|
||||
```
|
||||
|
||||
155 个测试覆盖:缓存操作、认证解析、域名过滤、Markdown 转换、搜索逻辑、集成流程、日志配置。
|
||||
309 个测试覆盖:缓存操作、认证解析、域名过滤、Markdown 转换、搜索逻辑、集成流程、日志配置、HTML 回退、自动抓取、健康检查、输出格式化、实例解析、并行搜索、CLI 端到端、错误码分类、流式输出、进度事件。
|
||||
|
||||
## 项目结构
|
||||
|
||||
|
||||
Reference in New Issue
Block a user