AstrBot 网页分析插件

AstrBot网页分析插件，能够自动识别用户发送的网页链接，智能抓取解析内容，集成大语言模型进行深度分析和总结，支持网页截图、缓存机制和多种管理命令。

更新日志

[v1.5.2] - 2026-03-05

🐛 Bug修复

修复路径拼接错误 - 解决 unsupported operand type(s) for /: 'str' and 'str' 错误
- 在所有路径拼接操作前确保使用 Path() 包装字符串
- 修复 core/analyzer.py 中的路径处理逻辑
- 添加类型检查和详细的调试日志
修复浏览器安装判断逻辑 - 解决返回码 250 导致的误判问题
- 智能判断安装成功：检查文件下载成功标记而非仅依赖返回码
- 忽略非关键的 DeprecationWarning（如 Node.js 的 url.parse 警告）
- 验证浏览器可执行文件是否真实存在

[v1.5.1] - 2026-02-23

⚡ 性能优化

浏览器安装流程异步化 - 将浏览器安装流程改为完全异步，避免阻塞框架和其他模块的运行
新增安装进程锁机制 - 实现类级别锁 _browser_install_lock，防止并发安装导致的资源冲突
新增安装状态持久化 - 实现浏览器安装状态的持久化存储，避免重复检查，提升启动速度
优化安装路径管理 - 浏览器安装到安全路径（data/plugin_data/astrbot_plugin_web_analyzer/playwright_browsers/），避免被系统清理

🔧 技术改进

新增异步检查方法 - _check_browser_installed_async() 使用 Playwright 异步 API 检查浏览器
新增异步安装方法 - _install_browser_async() 使用 asyncio.create_subprocess_exec 异步安装浏览器
新增持久化方法 - _load_install_status() 和 _save_install_status() 管理安装状态
新增路径管理方法 - _get_browser_install_path() 获取安全的安装路径
双重检查锁定模式 - 确保多实例场景下只安装一次浏览器
智能等待机制 - 当其他实例正在安装时，当前实例会等待完成而不是重复安装

📁 文件修改

core/analyzer.py - 新增 5 个方法，重构 _ensure_browser_installed() 方法，新增 3 个类属性

📝 说明

此优化大幅提升了插件启动速度，首次检查后持久化安装状态，后续启动无需重复检查
完全异步化确保不阻塞框架运行，提升整体性能
安装锁机制保证了并发安全性

[v1.5.0] - 2026-02-22

🐛 Bug修复

修复所有core模块导入失败问题 - 解决 ModuleNotFoundError: No module named 'core.cache' 及相关错误
统一采用相对导入 - 将 core/ 目录下所有模块的绝对导入改为相对导入（.），避免与 AstrBot 框架自身的 core 目录冲突
修复的文件:
- core/config_loader.py - 修复3处导入
- core/plugin_helpers.py - 修复4处导入
- core/message_handler.py - 修复6处导入
- core/error_handler.py - 修复1处导入
- core/command_handlers.py - 修复1处导入

🔧 技术改进

标准化导入方式 - 所有模块间导入统一使用相对导入（from .module import Class），这是 Python 包内部模块互相导入的标准做法
提高兼容性 - 确保插件在 AstrBot 框架中能够正常加载和运行
优化代码结构 - 移除不必要的 sys.path 设置代码，简化导入逻辑

📝 说明

此修复解决了插件启动时的导入错误
现在插件应该能够正常加载和运行
请重新启动 AstrBot 以应用此修复

[v1.4.9] - 2026-02-09

🐛 Bug修复

修复模块导入失败问题 - 解决 ModuleNotFoundError: No module named 'core.analyzer' 错误
采用相对导入 - 将 main.py 中的绝对导入改为相对导入（.core），避免与 AstrBot 框架自身的 core 目录冲突
移除冗余代码 - 清理不再需要的 sys.path 设置代码，简化导入逻辑

[v1.4.8] - 2026-02-06

⚡ 性能优化

优化screenshot_only模式 - 当启用screenshot_only模式时，跳过网页抓取和LLM分析，直接生成截图，大幅提升响应速度
新增快速路径 - 在process_single_url方法中添加screenshot_only快速通道，避免不必要的操作
独立缓存键 - screenshot_only模式使用独立的缓存键，避免与完整分析模式缓存冲突

🚀 功能改进

跳过冗余操作 - screenshot_only模式不再执行以下耗时操作：
- ❌ 网页HTML抓取 (fetch_webpage)
- ❌ 内容结构化提取 (extract_content)
- ❌ LLM智能分析 (analyze_with_llm)
- ❌ 特定内容提取 (extract_specific_content)
直接截图 - 只调用capture_screenshot生成网页截图

💾 资源节省

减少网络请求 - 不抓取网页HTML内容
节省内存占用 - 不存储网页内容和分析结果
降低LLM消耗 - 不调用LLM进行分析，节省token消耗
减少计算开销 - 不进行内容提取和处理

[⚠警告] v1.4.5版本重要更新：配置文件结构已发生改变，请在AstrBot管理面板中重新设置所有配置项。

详见更新日志文件。

功能特性

核心功能

功能特性	功能说明
自动识别URL	自动检测消息中的网页链接，支持带协议头和无协议头的URL
智能内容提取	使用BeautifulSoup提取网页主要内容
LLM智能分析	集成AstrBot的LLM接口进行深度内容分析

内容处理

功能特性	功能说明
网页截图	自动捕获网页截图，支持多种格式和自定义尺寸，支持整页截图和区域裁剪
网页翻译	支持将网页内容翻译成指定语言
特定内容提取	支持提取图片、链接、代码块、元信息等特定类型内容
多链接处理	支持同时处理多条链接，合并成一条合并转发消息发送
内容统计	提供详细的内容统计信息

性能优化

功能特性	功能说明
异步并发处理	使用asyncio.gather并发处理多个URL，动态调整并发数
结果缓存	支持分析结果缓存，LRU策略，支持缓存预加载和基于内容哈希的缓存
浏览器池	优化浏览器资源管理，实现高效的浏览器实例复用机制，定期自动清理
优先级调度	基于URL优先级的任务调度，提高重要URL的处理速度
内存监控	内存监控和自动释放机制，延长检查间隔至5分钟

高级特性

功能特性	功能说明
LLM自主决策	允许LLM决定返回分析结果还是截图，支持LLM Tool模式
LLM提示词优化	为娱乐资讯、体育新闻、教育资讯等多种内容类型添加详细分析模板
内容类型检测	智能检测网页内容类型，支持多种内容类型，提高检测准确性
多分析模板	支持多种LLM分析模板，支持智能模板选择

数据管理

功能特性	功能说明
分析结果导出	支持将分析结果导出为Markdown、JSON、TXT等格式，并作为附件发送
缓存管理	支持查看缓存状态和手动清理缓存
URL预处理	自动补全URL协议头，支持URL预处理和规范化，去除反引号、空格等

配置与管理

功能特性	功能说明
高度可配置	支持多种配置选项，满足不同需求，自动验证配置项有效性
域名控制	支持允许和禁止域名列表，域名统一处理（可自定义开关）
多平台支持	兼容各种消息平台
命令系统	支持命令补全、参数提示、命令别名自定义、详细命令帮助
多种结果模板	支持多种结果展示模板，支持结果折叠功能

可靠性

功能特性	功能说明
代理支持	支持HTTP代理配置，可用于绕过访问限制
请求重试机制	自动重试失败的请求，提高抓取成功率
完善的错误处理	实现错误分级和分类，提供详细的错误信息
详细日志记录	新增详细的日志记录，便于调试和监控

文档

详细文档请查看 Wiki：

快速开始 - 安装和基本使用指南
命令参考 - 详细的命令说明
配置指南 - 所有配置项的详细说明
技术实现 - 技术细节和架构
常见问题 - 常见问题和解决方案
开发指南 - 开发相关的信息

安装方法

将插件目录复制到AstrBot的插件目录：

# 目录结构示例
AstrBot/data/plugins/
└── astrbot_plugin_web_analyzer/
    ├── main.py
    ├── requirements.txt
    └── ...

安装依赖：

# 进入插件目录
cd AstrBot/data/plugins/astrbot_plugin_web_analyzer
# 安装依赖
pip install -r requirements.txt

重启AstrBot或在WebUI插件管理中点击重载插件

📂 项目结构

📁 点击展开查看完整的目录结构

astrbot_plugin_web_analyzer/
├── main.py                    # 插件入口文件
├── metadata.yaml              # 插件元数据
├── _conf_schema.json          # 配置项定义
├── requirements.txt           # Python依赖项
├── CHANGELOG.md               # 更新日志
├── LICENSE                    # MIT开源协议
├── README.md                  # 项目说明文档
├── logo.png                   # 插件Logo
├── .gitignore                 # Git忽略规则
│
├── core/                      # 核心逻辑模块目录
│   ├── __init__.py           # 模块初始化
│   ├── analyzer.py           # 网页解析核心引擎
│   ├── cache.py              # 缓存管理系统
│   ├── command_handlers.py   # 指令处理器集合
│   ├── config_loader.py      # 配置加载与验证
│   ├── constants.py          # 常量定义
│   ├── error_handler.py      # 错误处理机制
│   ├── llm_analyzer.py       # LLM分析集成
│   ├── message_handler.py    # 消息处理逻辑
│   ├── plugin_helpers.py     # 插件辅助函数
│   ├── result_formatter.py   # 结果格式化输出
│   ├── screenshot_temp_manager.py  # 截图临时文件管理
│   └── utils.py              # 通用工具函数
│
├── wiki/                      # 项目文档目录
│   ├── Home.md                    # 文档首页
│   ├── QuickStart.md              # 快速开始指南
│   ├── Commands.md                # 命令参考手册
│   ├── Configuration.md           # 配置选项说明
│   ├── TechnicalImplementation.md # 技术实现细节
│   ├── FAQ.md                     # 常见问题解答
│   └── Development.md             # 开发指南
│
├── docs/                      # 额外文档资源
│   └── command_handlers_guide.md  # 命令处理详细指南
│
└── data/                      # 插件运行时数据存储目录
    └── (运行时自动生成)

使用方法

自动分析

插件会自动检测消息中的URL链接并进行分析：

用户：看看这个新闻 https://example.com/news/article
机器人：检测到网页链接，正在分析: https://example.com/news/article
       [分析结果...]
       [网页截图...]

支持无协议头的URL（需在配置中启用）：

用户：看看这个新闻 www.example.com/news/article
机器人：检测到网页链接，正在分析: https://www.example.com/news/article
       [分析结果...]
       [网页截图...]

支持同时处理多个链接：

用户：看看这些新闻 https://example.com/news/article1 https://example.com/news/article2
机器人：检测到2个网页链接，正在分析...
       [合并转发的分析结果...]
       [网页截图...]

手动分析

使用命令手动分析指定链接：

/网页分析 https://example.com

支持同时分析多个链接：

/网页分析 https://example.com/article1 https://example.com/article2

命令别名

支持多种命令别名，方便用户使用：

/分析 https://example.com
/总结 https://example.com
/web https://example.com
/analyze https://example.com

分析模式

插件支持四种分析模式，可通过配置或管理员命令切换：

模式	说明
auto	检测到链接自动分析，无需命令（默认模式）
manual	必须使用`/网页分析`命令才会分析，不会自动处理链接
hybrid	默认自动分析，但管理员可通过命令临时切换
LLMTOOL	不自动分析链接，让LLM自己决定是否调用analyze_webpage工具

查看当前模式：

/web_mode

切换模式（仅限管理员）：

/web_mode auto      # 切换到自动分析模式
/web_mode manual    # 切换到手动分析模式
/web_mode hybrid    # 切换到混合模式
/web_mode LLMTOOL   # 切换到LLM Tool模式

模式命令别名：

/分析模式
/网页分析模式

命令帮助

查看所有可用命令和帮助信息：

/web_help

命令别名：

/网页分析帮助
/网页分析命令

配置管理

查看当前插件配置：

/web_config

命令别名：

/网页分析配置
/网页分析设置

缓存管理

查看缓存状态：

/web_cache

手动清理缓存：

/web_cache clear

命令别名：

/网页缓存
/清理缓存

分析结果导出

导出指定URL的分析结果：

/web_export https://example.com md

导出所有缓存的分析结果：

/web_export all json

支持的导出格式：

格式	说明
md / markdown	Markdown格式，适合阅读和分享
json	JSON格式，适合程序处理和数据交换
txt	纯文本格式，兼容性好

命令别名：

/导出分析结果 https://example.com
/网页导出 all md

群聊黑名单管理

查看当前群聊黑名单：

/group_blacklist

添加群聊到黑名单：

/group_blacklist add <群号>

从黑名单移除群聊：

/group_blacklist remove <群号>

清空黑名单：

/group_blacklist clear

命令别名：

/群黑名单
/黑名单

配置选项

插件支持多种配置选项，可以在AstrBot管理面板中进行设置。以下是主要配置项的说明：

核心设置

配置项	说明	默认值
analysis_mode	分析模式，支持auto(自动)、manual(手动)、hybrid(混合)、LLMTOOL(LLM智能决定)	auto
enable_no_protocol_url	识别无协议头URL（如www.example.com）	false
default_protocol	默认协议	https
max_content_length	最大网页内容长度	10000
request_timeout	请求超时时间(秒)	30
retry_count	请求重试次数	3
retry_delay	请求重试间隔(秒)	2
llm_enabled	启用LLM智能分析	true
user_agent	自定义User-Agent	-
proxy	HTTP代理配置，格式为http://username:password@host:port，留空表示不使用代理	-
enable_unified_domain	是否启用域名统一处理（如google.com和www.google.com视为同一域名）	true

域名管理

配置项	说明	默认值
allowed_domains	允许的域名列表（留空表示允许所有域名）	-
blocked_domains	禁止的域名列表	-

分析结果配置

配置项	说明	默认值
enable_emoji	启用emoji图标	true
enable_statistics	显示内容统计	true
max_summary_length	最大摘要长度	2000
result_template	结果展示模板，支持：default, detailed, compact, markdown, simple	default
enable_collapsible	启用结果折叠功能	false
collapse_threshold	结果折叠阈值	1500
enable_llm_decision	启用LLM自主决策功能	false

网页截图配置

配置项	说明	默认值
enable_screenshot	启用网页截图	true
screenshot_quality	截图质量（0-100）	80
screenshot_width	截图宽度像素	1280
screenshot_height	截图高度像素	720
screenshot_format	截图格式（支持jpeg和png）	jpeg
screenshot_full_page	截取整页	false
screenshot_wait_time	截图前等待页面加载的时间（毫秒）	2000
enable_crop	启用截图裁剪功能	false
crop_area	裁剪区域，格式为 [left, top, right, bottom]	[0, 0, screenshot_width, screenshot_height]

LLM配置

配置项	说明	默认值
llm_provider	LLM提供商（使用会话默认或指定提供商）	-
custom_prompt	自定义分析提示词	-

消息管理

配置项	说明	默认值
group_blacklist	群聊黑名单，在这些群聊中禁用自动分析功能	-
merge_forward_enabled.group	群聊启用合并转发功能	false
merge_forward_enabled.private	私聊启用合并转发功能	false

翻译配置

配置项	说明	默认值
enable_translation	启用网页翻译	false
target_language	目标语言	zh
translation_provider	翻译提供商	llm
custom_translation_prompt	自定义翻译提示词	-

缓存配置

配置项	说明	默认值
enable_cache	启用结果缓存	true
cache_expire_time	缓存过期时间（分钟）	1440
max_cache_size	最大缓存数量	100
cache_preload_enabled	启用缓存预加载功能	false
cache_preload_count	预加载的缓存数量	20

内容提取配置

配置项	说明	默认值
enable_specific_extraction	启用特定内容提取	false
extract_types	提取内容类型，每行一个，支持：title, content, images, links, tables, lists, code, meta	title\ncontent

技术实现

核心技术栈

功能模块	技术实现
异步HTTP请求	`httpx`
HTML解析	`BeautifulSoup` + `lxml`
网页截图	`playwright` 无头浏览器
异步并发	`asyncio.gather`
缓存机制	内存缓存 + 文件缓存
LLM集成	AstrBot LLM接口

关键实现细节

网页内容提取

智能选择主要内容区域（使用article、main等语义化标签）
自动移除脚本和样式标签，只保留纯文本内容
支持代理配置，可用于绕过访问限制
实现请求重试机制，提高抓取成功率

异步并发处理

使用asyncio.gather并发处理多个URL
优化异步上下文管理器的使用
提高多链接处理效率

网页截图

支持自定义截图质量、宽度、高度和等待时间
支持JPEG和PNG多种格式
自动安装浏览器，无需手动配置
支持整页截图和自定义区域裁剪

缓存系统

双重缓存机制：内存缓存 + 文件缓存
支持缓存统计、过期清理和大小限制
提供缓存管理命令
基于内容哈希的缓存策略，提高缓存命中率

LLM分析

集成AstrBot的LLM接口
提供结构化的分析提示词
支持多种分析维度：核心摘要、关键要点、内容类型、价值评估、适用人群
支持LLM自主决策模式

配置与错误处理

配置验证逻辑，确保配置项有效性
详细的配置错误提示
网络请求失败时的友好提示
LLM不可用时的基础分析模式
完善的日志记录
浏览器自动安装和错误恢复
资源的正确释放和清理

依赖说明

依赖包	版本要求	用途
`httpx`	`>=0.24.0`	异步HTTP客户端
`beautifulsoup4`	`>=4.12.0`	HTML解析库
`lxml`	`>=4.9.0`	快速XML/HTML解析器
`playwright`	`>=1.40.0`	浏览器自动化库，用于网页截图

常见问题

截图功能异常

问题现象：截图功能不工作或生成的截图异常

可能原因及解决方法：

浏览器未正确安装：插件会自动尝试安装浏览器，若安装失败可手动执行 playwright install
网络问题：请检查网络连接，确保能正常访问目标网站
权限问题：确保插件有足够的权限创建临时文件
截图格式设置错误：请确保使用支持的格式（JPEG或PNG）
页面加载问题：适当增加 screenshot_wait_time 配置值

分析结果不准确

问题现象：网页分析结果与预期不符

优化建议：

调整 max_content_length 配置，增加抓取的内容长度
调整 screenshot_wait_time 配置，增加页面加载等待时间
使用 custom_prompt 配置自定义提示词，优化分析结果
检查代理配置是否正确（如果使用了代理）
确保目标网页内容能正常访问

插件响应缓慢

问题现象：插件处理请求时间过长

优化建议：

减少 max_content_length 配置，减少抓取的内容长度
关闭 screenshot_full_page 选项，只截取可见部分
调整 request_timeout 配置，合理设置超时时间
减少 retry_count 配置，减少重试次数
根据实际需求考虑关闭 enable_screenshot 选项

代理配置问题

问题现象：配置代理后无法正常使用

检查要点：

代理格式是否正确：格式应为 http://username:password@host:port
代理服务器是否可用：确保代理服务器能正常访问
代理服务器是否支持HTTPS请求：多数网站使用HTTPS
代理认证信息是否正确：检查用户名和密码

缓存功能异常

问题现象：缓存不生效或出现异常

解决方法：

检查 enable_cache 配置是否为 true
检查 cache_expire_time 配置是否合理（单位：分钟）
尝试使用 /web_cache clear 命令手动清理缓存后重新测试
检查缓存目录是否有写入权限
查看日志文件，排查具体错误信息

多链接处理问题

问题现象：同时发送多个链接时处理异常

解决方法：

检查 merge_forward_enabled 配置，确保合并转发功能正常
减少单次发送的链接数量
确保服务器资源充足，能支持并发处理

开发说明

插件遵循AstrBot插件开发规范：

使用中文注释
完善的错误处理
异步编程模式
符合PEP8代码风格

开发者联系方式

GitHub: https://github.com/Sakura520222
Email: sakura520222@outlook.com

贡献者

Ciallo～(∠・ω< )⌒★

许可证

本项目采用 MIT License 开源协议。

Name		Name	Last commit message	Last commit date
Latest commit History 152 Commits
.github		.github
core		core
docs		docs
wiki		wiki
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
_conf_schema.json		_conf_schema.json
logo.png		logo.png
main.py		main.py
main_backup.py		main_backup.py
metadata.yaml		metadata.yaml
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

AstrBot 网页分析插件

更新日志

[v1.5.2] - 2026-03-05

🐛 Bug修复

[v1.5.1] - 2026-02-23

⚡ 性能优化

🔧 技术改进

📁 文件修改

📝 说明

[v1.5.0] - 2026-02-22

🐛 Bug修复

🔧 技术改进

📝 说明

[v1.4.9] - 2026-02-09

🐛 Bug修复

[v1.4.8] - 2026-02-06

⚡ 性能优化

🚀 功能改进

💾 资源节省

功能特性

核心功能

内容处理

性能优化

高级特性

数据管理

配置与管理

可靠性

文档

安装方法

📂 项目结构

使用方法

自动分析

手动分析

命令别名

分析模式

命令帮助

配置管理

缓存管理

分析结果导出

群聊黑名单管理

配置选项

核心设置

域名管理

分析结果配置

网页截图配置

LLM配置

消息管理

翻译配置

缓存配置

内容提取配置

技术实现

核心技术栈

关键实现细节

网页内容提取

异步并发处理

网页截图

缓存系统

LLM分析

配置与错误处理

依赖说明

常见问题

截图功能异常

分析结果不准确

插件响应缓慢

代理配置问题

缓存功能异常

多链接处理问题

开发说明

开发者联系方式

贡献者

许可证

Star

About

Resources

License

Uh oh!

Packages