feat(v1.8.1): Windows 兼容性修复 + SKILL.md 铁律区块

Windows 兼容性修复(基于真实使用痛点):

- force_utf8_stdout(): 强制 stdout/stderr 为 UTF-8,修复 Windows GBK 崩溃(print('\\xa0') 不再炸)

- resolve_instances/load_config 新增 %APPDATA%/searxng-cli/ 路径,覆盖 Windows 配置约定

- fetch.py 失败诊断增强:输出 status_code=/cause=/url= 字段,AI Agent 可程序化区分 404/403/DNS 失败

SKILL.md 铁律区块(5 条,置顶):

- stdout=数据/stderr=日志 永不混淆

- 禁用 2>/dev/null(丢弃 stderr = 失败时零诊断)

- 排错去 --quiet 加 --verbose

- 配置查找覆盖 WSL + Windows 双路径

- 实例 URL 必填,公共实例发现已移除

测试: 352 -> 362(新增 10 个:force_utf8_stdout 幂等性/GBK 替换/非 ASCII 打印/APPDATA 路径发现/txt 回退/空 APPDATA)
This commit is contained in:
2026-08-01 20:50:42 +08:00
parent 657af0a221
commit f7cdc81c7f
8 changed files with 325 additions and 12 deletions
+6 -3
View File
@@ -131,7 +131,7 @@ AI Agent 无需每次传入实例 URL 和认证信息,支持通过配置文件
1. **CLI 参数**`-i https://your-instance`(最高优先级)
2. **环境变量**`export SEARXNG_INSTANCE="https://your-instance"`
3. **配置文件**`./searxng.toml` `~/.config/searxng-cli/searxng.toml`
3. **配置文件**`./searxng.toml` `~/.config/searxng-cli/searxng.toml``%APPDATA%/searxng-cli/searxng.toml`Windows
```toml
# searxng.toml
@@ -263,12 +263,15 @@ python scripts/fetch.py -u https://example.com \
**工程**
- 共享 `common.py`(统一重试/字符集/认证/日志)
- 结构化日志(`--verbose` / `--quiet`
- UTF-8 stdout 强制(`force_utf8_stdout()`,修复 Windows GBK 崩溃)
- Windows 配置路径发现(`%APPDATA%/searxng-cli/`
- fetch.py 失败诊断增强(`status_code=` / `cause=` / `url=` 字段)
- 结构化错误码 + `recovery_hint` 恢复建议(`E_NETWORK` / `E_AUTH` / `E_RATE_LIMIT` 等)
- JSON 输出含 `schema_version` 字段,`--dump-schema` 输出 JSON Schema 文档
- JSON Lines 流式输出(`--stream`,含 `error` 事件类型)
- 进度事件(`--progress`,含 `instance_try`/`instance_ok`/`instance_fail`JSON Lines 到 stderr
- batch 模式统一 schema`status` 字段区分成功/失败)
- 352 个单元+集成测试
- 362 个单元+集成测试
## 跨 Agent 兼容性
@@ -296,7 +299,7 @@ pip install pytest
pytest -q
```
352 个测试覆盖:缓存操作、认证解析、域名过滤、Markdown 转换、搜索逻辑、集成流程、日志配置、HTML 回退、自动抓取、健康检查、输出格式化、实例解析、并行搜索、CLI 端到端、错误码分类、流式输出、进度事件、配置文件认证、schema_version、recovery_hint、batch 统一 schema、--dump-schema。
362 个测试覆盖:缓存操作、认证解析、域名过滤、Markdown 转换、搜索逻辑、集成流程、日志配置、HTML 回退、自动抓取、健康检查、输出格式化、实例解析、并行搜索、CLI 端到端、错误码分类、流式输出、进度事件、配置文件认证、schema_version、recovery_hint、batch 统一 schema、--dump-schema、UTF-8 stdout 强制、Windows APPDATA 路径
## 项目结构