Files
abot/docs/工程优化与Feature清单.md

798 lines
21 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# ABOT 工程优化与 Feature 清单
## 1. 文档目标
本文档用于沉淀当前 ABOT 项目的工程化分析结论,并整理一份可直接进入迭代排期的优化清单。
适用场景:
- 作为后续软件工程优化的总入口
- 作为版本规划与任务拆解的基础文档
- 作为功能优化、性能治理、可维护性建设的统一 backlog
本文重点不放在“再增加多少新功能”,而放在“如何让现有系统更稳、更快、更安全、更好维护、更好用”。
## 1.1 最近已完成的治理项
- 已剥离未实际使用的事件系统实现,减少主链路无效抽象
- 已将插件调用统计改为主链路直接埋点,降低维护复杂度
- 已在消息主链路接入 `trace_id`,用于串联消息处理、插件统计与异常日志
- 已在后台首页补充“系统健康快照”,可集中查看机器人连接、插件运行、近 24 小时异常与 md2img 运行状态
- 已补充 MySQL / Redis 连接探测与统一 LLM 最近调用快照,基础设施与 AI 运行态可直接在首页查看
- 已将 `trace_id` 通过异步上下文继续贯穿到统一 LLM 调用与微信发送动作,链路追踪粒度进一步提升
- 已补充后台登录失败限流、会话超时、默认弱口令强提醒与密码复杂度校验,后台安全基线进一步收紧
- 已引入全局配置环境变量注入、启动期完整性校验与 `config.example.yaml`,默认配置不再直接携带仓库内明文密钥
## 2. 项目现状判断
从当前仓库结构、主链路代码、插件体系、后台管理端、存储层与 AI 能力来看ABOT 已经属于一个具备完整产品雏形的机器人系统,而不是简单的脚本集合。
当前已经具备的核心能力包括:
- 微信消息接入与机器人主循环
- 插件化消息处理框架
- 管理后台与部分运营配置能力
- MySQL 与 Redis 双存储体系
- 定时任务与系统任务加载机制
- AI 自动回复、消息总结、群画像、内容生成等能力
- 群管理、积分、媒体处理、排行榜、消息归档等业务功能
整体评价如下:
- 功能广度:较强
- 产品雏形完整度:较高
- 工程化成熟度:中等偏上,但仍有明显提升空间
- 可运维性:初步具备,但距离稳定线上系统还有差距
- 可扩展性:架构方向正确,但治理能力不足
## 3. 当前主要问题
### 3.1 安全性问题
当前最优先的问题不是新功能不足,而是安全基线偏弱。
主要体现在:
- 配置文件中直接保存数据库、Redis、邮箱、LLM 等敏感凭据
- 后台存在默认账号回退逻辑,部署时容易留下弱口令入口
- Flask `secret_key` 仍是固定值,不适合正式环境
- 缺少系统级的鉴权审计、登录失败限流、会话超时等安全能力
影响:
- 一旦仓库泄露或服务器暴露,风险较大
- 配置难以安全迁移到多环境部署
- 后台权限控制不足时,容易产生误操作与未授权访问问题
### 3.2 人工验证体系不足
当前项目已经很大,但还没有形成稳定、固定、可重复执行的人工验证流程。
主要体现在:
- 缺少统一的改动后检查清单
- 缺少核心链路的固定回归步骤
- 缺少后台功能、消息链路、插件链路的验收模板
- 功能越多,人工测试越容易遗漏
影响:
- 每次改动都更依赖临场经验
- 插件之间联动问题不容易在第一时间发现
- 后续优化越多,回归成本越高
### 3.3 可观测性不足
当前项目已经有日志,但还没有形成真正的观测体系。
主要体现在:
- 日志有了,但缺少统一指标
- 缺少消息链路追踪
- 缺少插件耗时、错误率、队列积压等核心监控
- 缺少可直接定位性能瓶颈的后台页面
影响:
- 系统一旦变慢,很难快速定位是哪一层出问题
- 很难为扩容、限流、降级提供数据支撑
- 排障过程较依赖人工经验
### 3.4 性能与吞吐风险
消息处理主链路已经做了部分异步和并发控制,但仍有几个潜在热点:
- 插件处理仍以串行判定为主,插件数量增加后会放大延迟
- 统计、观测、异常记录等横切逻辑过去分散在多处抽象中,主链路需要继续收口
- 消息归档、媒体处理、AI 调用都可能形成局部阻塞
- Redis 和数据库部分写法在高消息量场景下会出现额外开销
影响:
- 高峰期可能出现处理延迟上升
- 群聊现场感会受到影响,尤其是 AI 即时回复场景
- 单个插件异常时,可能拖慢整体系统
### 3.5 插件治理能力不足
当前插件架构已经是项目的核心优势,但治理层能力还不够强。
主要体现在:
- 插件有加载、启停、热更新,但缺少健康评分与故障隔离
- 缺少插件依赖声明
- 缺少插件资源配额机制
- 缺少插件级性能统计与错误统计
- 缺少插件升级兼容性约束
影响:
- 插件数量越多,系统复杂度越高
- 新插件接入成本逐步上升
- 问题出现时难以快速判断是哪个插件导致
### 3.6 数据层职责逐渐变重
随着功能增长,消息表、统计逻辑、媒体处理、成员画像、群画像等数据能力不断叠加,数据访问层已经有膨胀趋势。
主要体现在:
- 某些数据访问文件职责过多
- 存储结构逐步同时承担在线查询、统计分析、排障追踪等多类用途
- 部分统计逻辑仍偏“业务脚本式”,而不是标准的数据汇总链路
影响:
- 后续维护成本会继续升高
- 查询性能优化难度会越来越大
- 数据模型的边界容易变模糊
### 3.7 后台可运维能力还不够
当前后台已经能完成很多管理动作,但更像是“功能页面集合”,还不完全是“系统运维控制台”。
主要体现在:
- 缺少系统健康总览
- 缺少任务运行历史与失败重试中心
- 缺少插件运行态可视化
- 缺少关键配置变更审计
- 缺少管理员行为日志
影响:
- 后期维护仍要依赖日志和人工排查
- 运维动作不够可追踪
- 一旦项目规模变大,后台会逐渐不够用
### 3.8 用户体验仍有提升空间
项目已经具备很多能力,但从普通用户和群管理员角度看,仍有一些典型改进点。
主要体现在:
- 命令发现成本较高
- 功能启用状态不够透明
- 群级个性化配置入口不统一
- AI 能力较强,但可控性和可解释性还可以继续提升
影响:
- 新用户上手门槛仍偏高
- 管理员配置成本较高
- 功能多,但不一定都能被真正使用起来
## 4. 优化原则
建议后续优化遵循以下原则:
### 4.1 先补工程底座,再扩业务上限
优先处理安全、人工验证、监控、性能、插件治理,再继续叠加复杂功能。
### 4.2 优先做“能降低长期维护成本”的能力
例如:
- 人工验证清单
- 配置治理
- 指标与追踪
- 插件治理
- 运维后台
这些能力虽然短期不一定最显眼,但对项目长期价值最高。
### 4.3 优先做“能支撑更多功能继续增长”的通用平台能力
例如:
- 任务中心
- 插件元数据中心
- 群级配置中心
- AI 成本与策略中心
这些能力做好后,后面新增业务插件的成本会明显下降。
## 5. Feature Backlog
以下 backlog 按优先级拆分为 P0、P1、P2。
说明:
- P0建议立即进入迭代
- P1建议在 P0 后连续推进
- P2可作为增强项逐步建设
---
## 6. P0 优先级清单
### 6.1 配置与密钥治理中心
目标:
- 把敏感配置从仓库中剥离
- 支持多环境部署
- 减少误配置导致的线上事故
建议内容:
- 引入 `.env` 或环境变量注入机制
- 提供 `config.example.yaml`
- 启动时增加配置完整性检查
- 后台展示配置时自动脱敏
- 区分开发、测试、生产环境配置
当前进展:
- 第一阶段已完成:`configuration.py` 已支持 `${ENV_NAME}` / `${ENV_NAME:默认值}` 形式的环境变量注入
- 第一阶段已完成:启动时已增加 MySQL、Redis、LLM、邮件等关键配置完整性检查致命缺项会直接阻止启动
- 第一阶段已完成:已补充 `config.example.yaml`,并将仓库内默认 `config.yaml` 改为安全占位模板
- 后续可继续补充后台配置查看脱敏、分环境配置切换与插件级配置治理
预期收益:
- 大幅降低密钥泄露风险
- 降低部署与迁移成本
- 提高配置管理规范性
涉及模块:
- `configuration.py`
- `config.yaml`
- `admin/dashboard`
- 各插件 `config.toml`
### 6.2 后台安全增强
目标:
- 提高后台管理面的安全基线
当前进展:
- 第一阶段已完成:已补充登录失败限流、会话超时、安全 Cookie 与动态 secret_key 兜底
- 第二阶段已完成:已补充默认弱口令识别、登录后强制改密提示与密码复杂度校验
- 后续可继续补充关键操作审计日志与更细粒度的管理员行为追踪
建议内容:
- 首次部署强制修改默认管理员密码
- 登录失败次数限制
- 会话过期机制
- 安全 Cookie 配置
- 关键操作审计日志
- 后台密码复杂度校验
预期收益:
- 降低后台被暴力尝试和弱口令利用的风险
- 提高运维操作可追踪性
涉及模块:
- `admin/dashboard/server.py`
- `admin/dashboard/blueprints/auth.py`
- `db/admin_account_db.py`
### 6.3 人工验证与回归清单
目标:
- 让每次改动后都有固定、可重复执行的验证步骤
当前排期说明:
- 按当前优化策略,该项暂时后置处理,放在本轮工程治理工作的最后再集中补齐
建议内容:
- 建立“日常改动验证清单”
- 建立“消息主链路回归清单”
- 建立“后台页面回归清单”
- 建立“插件启停与配置修改回归清单”
- 建立“上线前人工检查清单”
- 为高风险功能补最基础的手工验收步骤说明
预期收益:
- 降低人工测试遗漏概率
- 让后续优化更有章法
涉及模块:
- `docs/`
- `admin/dashboard/`
- `robot.py`
- `plugins/`
### 6.4 系统健康与观测面板
目标:
- 让系统运行状态可视化、可量化
当前进展:
- 第一阶段已完成:首页已增加系统健康快照,可快速查看核心运行状态
- 第二阶段已完成:已补充基础设施连通性与 AI 最近调用耗时/成功率快照
- 后续可继续补充更细粒度的吞吐、延迟、存储连接与 AI 调用链指标
建议内容:
- 增加系统吞吐量指标
- 增加插件成功率与错误率统计
- 增加 AI 调用耗时统计
- 增加消息处理延迟监控
- 增加 Redis/MySQL 连接状态展示
- 增加最近错误摘要面板
预期收益:
- 快速发现故障
- 为性能优化提供真实数据
涉及模块:
- `admin/dashboard/`
- `robot.py`
- `main.py`
- `utils/ai/`
### 6.5 消息链路 Trace 能力
目标:
- 对单条消息实现“从接收到发送”的全链路追踪
当前进展:
- 第一阶段已完成:主消息链路、插件统计与异常日志已接入 `trace_id`
- 第二阶段已完成:统一 LLM 调用与微信发送日志已可自动继承同一 `trace_id`
- 后续可继续补充后台按 `trace_id` 检索错误、消息与 AI 调用详情的入口
建议内容:
- 为每条消息生成统一 trace_id
- 日志中贯穿 trace_id
- 插件处理结果绑定 trace_id
- AI 请求与消息发送动作绑定 trace_id
预期收益:
- 排障效率大幅提升
- 更容易定位慢点与错误点
涉及模块:
- `robot.py`
- `base/plugin_common/`
- `utils/ai/`
- `utils/wechat/`
---
## 7. P1 优先级清单
### 7.1 插件治理中心
目标:
- 把插件系统从“可加载”升级为“可治理”
当前进展:
- 第一阶段已完成:`PluginManager` 已输出统一插件治理快照,后台不再只展示“加载成功的插件”
- 第一阶段已完成后台插件管理页已补充治理健康、能力类型、Feature Key、依赖与配置概览信息
- 第一阶段已完成:插件配置保存前已增加格式校验,避免坏配置直接写回线上文件
- 第二阶段已完成:插件管理页已补充执行表现摘要、最近错误信息与高风险/慢插件排行,便于快速定位运行异常插件
- 第二阶段已完成:插件快照已补充依赖拓扑摘要,后台可直接查看核心依赖插件、缺失依赖风险与上下游关系
- 后续可继续补充插件错误历史、性能排名、依赖图与熔断/隔离控制
建议内容:
- 插件元信息页面
- 插件依赖声明
- 插件配置校验
- 插件运行状态监控
- 最近错误记录
- 插件性能排名
预期收益:
- 提高插件系统可维护性
- 降低多插件并行增长的复杂度
涉及模块:
- `base/plugin_common/plugin_manager.py`
- `base/plugin_common/plugin_registry.py`
- `admin/dashboard/`
### 7.2 插件超时、熔断与隔离
目标:
- 防止单插件问题拖垮整体系统
当前进展:
- 第一阶段已完成:消息插件执行已增加统一超时保护,避免单插件长时间卡住主链路
- 第一阶段已完成:已补充连续失败熔断、冷却后半开探测与自动恢复逻辑
- 第一阶段已完成:插件治理快照与后台详情已可查看执行保护状态、连续失败与恢复剩余时间
- 后续可继续补充插件级并发配额、失败原因聚合、后台手动解除熔断与更细粒度的隔离策略
建议内容:
- 插件处理超时控制
- 连续失败自动熔断
- 熔断后定时恢复探测
- 插件错误隔离与状态降级
预期收益:
- 提高整体稳定性
- 降低故障扩散风险
涉及模块:
- `robot.py`
- `base/plugin_common/`
### 7.3 后台任务中心
目标:
- 让定时任务真正可管理、可追踪
当前进展:
- 第一阶段已完成:系统任务页与插件调度页已补充历史执行摘要,可直接查看最近成功时间、最近失败原因与累计成功/失败次数
- 第一阶段已完成:任务列表接口已合并内存运行态与数据库日志态,服务重启后后台仍可回看最近执行结果
- 第一阶段已完成:插件调度页已补充快捷启停入口,减少仅为切换启用状态而进入编辑弹窗的操作成本
- 后续可继续补充任务执行审计人、失败重试策略模板、筛选搜索与跨任务汇总看板
建议内容:
- 展示任务执行历史
- 展示上次成功时间和上次失败原因
- 支持手动触发任务
- 支持失败重试
- 支持任务启停与审计
预期收益:
- 大幅提升后台运维能力
- 降低定时任务异常后的排查成本
涉及模块:
- `utils/system_jobs.py`
- `utils/plugin_schedule_manager.py`
- `db/system_job_db.py`
- `db/plugin_schedule_db.py`
- `admin/dashboard/`
### 7.4 数据层性能优化
目标:
- 提高高消息量场景下的吞吐与查询效率
当前进展:
- 第一阶段已完成:数据库公共层已增加慢 SQL 记录能力,可按 `db_config.slow_query_threshold_ms` 阈值输出慢查询日志
- 第一阶段已完成:消息存储层启动时会自动补齐关键查询索引,优先覆盖群消息范围查询、成员消息回溯与待处理媒体扫描场景
- 第一阶段已完成:多处按日期查询已改为时间范围查询,避免 `DATE(timestamp)` 直接作用在索引列上导致索引失效
- 第一阶段已完成:已修正消息存储层重复定义的日期范围方法,避免按天汇总查询误走错误实现
- 后续可继续补充统计报表快照表、Redis key 扫描替换方案、后台慢 SQL 看板与更多统计表索引治理
建议内容:
- 梳理消息表与统计表索引
- 优化高频查询 SQL
- 逐步替换高成本 Redis key 扫描模式
- 对报表类查询做汇总表或快照表
- 增加慢 SQL 记录
预期收益:
- 提升整体处理效率
- 为数据规模增长留出空间
涉及模块:
- `db/`
- `utils/wechat/message_to_db.py`
- `admin/dashboard/`
### 7.5 消息归档与统计分层
目标:
- 降低单一数据层承担过多职责的问题
建议内容:
- 区分原始消息、结构化消息、统计快照、媒体资产
- 梳理消息归档与统计写入边界
- 为画像、总结、排行等场景设计更清晰的数据来源
预期收益:
- 降低维护复杂度
- 提升查询可解释性
涉及模块:
- `db/message_storage.py`
- `utils/wechat/message_to_db.py`
- `db/scripts/migrations/`
### 7.6 AI 成本与策略中心
目标:
- 让 AI 能力更可控、更可衡量
建议内容:
- 统计各插件 token 消耗
- 统计模型成功率与平均耗时
- 支持模型降级策略
- 支持预算阈值告警
- 支持按场景切换模型策略
预期收益:
- 降低 AI 成本不可控风险
- 提高不同场景下的模型使用效率
涉及模块:
- `utils/ai/`
- `plugins/ai_auto_response/`
- `plugins/message_summary/`
- `plugins/member_context/`
### 7.7 命令帮助与功能发现优化
目标:
- 降低普通用户与管理员的使用门槛
当前进展:
- 第一阶段已完成:`菜单 指令清单 / 功能清单 / 命令清单 / 帮助` 已改为基于运行中插件快照自动生成
- 第一阶段已完成:指令清单已按当前群真实可用状态过滤,管理员可额外看到未启用命令与管理命令
- 第二阶段已完成:后台已新增“命令索引”页面,可按群查看真实可用命令、未启用命令、自动能力与管理员触发示例
- 后续可继续补充插件触发示例模板、命令分类标签与更细粒度的使用说明
建议内容:
- 自动生成按插件分类的帮助菜单
- 按群启用状态展示实际可用命令
- 按管理员/普通用户显示不同帮助内容
- 后台提供命令索引与触发示例
预期收益:
- 提高功能使用率
- 降低学习成本
涉及模块:
- `plugins/robot_menu/`
- `utils/robot_cmd/`
- `admin/dashboard/`
---
## 8. P2 优先级清单
### 8.1 群级个性化配置中心
目标:
- 让不同群拥有不同的机器人行为策略
建议内容:
- 群级人格配置
- 群级回复频率配置
- 群级白名单和黑名单
- 群级敏感词与休眠时段配置
- 群级 AI 场景开关
预期收益:
- 提高多群场景适配能力
- 提高管理员可控性
### 8.2 用户反馈闭环
目标:
- 为 AI 与功能优化提供真实用户反馈数据
建议内容:
- 对 AI 回复增加“有用/没用”反馈
- 管理后台查看低质量回复样本
- 针对高频差评问题做规则与提示词优化
预期收益:
- 让优化方向更基于数据
- 提高 AI 回复质量
### 8.3 数据导出与备份恢复
目标:
- 提升系统的数据可迁移性与安全性
建议内容:
- 导出群消息统计报表
- 导出积分/签到/排行数据
- 数据备份任务
- 恢复演练机制
预期收益:
- 提高运维安全性
- 提高系统迁移与容灾能力
### 8.4 多模态交互能力增强
目标:
- 扩展项目的智能交互上限
建议内容:
- 语音识别
- 图片理解
- 图文混合回复
- 后台统一管理多模态能力开关
预期收益:
- 提高交互丰富度
- 增强内容类插件能力
### 8.5 插件模板与插件市场化能力
目标:
- 降低后续新增插件的开发与接入成本
建议内容:
- 标准插件模板
- 插件脚手架命令
- 插件元数据规范
- 插件安装与升级指引
预期收益:
- 提高插件生态扩展效率
- 降低维护者心智负担
### 8.6 运营与数据分析能力增强
目标:
- 让后台不只是管理系统,也能辅助群运营
建议内容:
- 群活跃时段分析
- 沉默成员识别
- 热点话题趋势分析
- 群行为周报/月报
预期收益:
- 提高项目在群运营场景下的价值
- 为功能优化提供更多行为数据
---
## 9. 推荐迭代路线
建议不要同时推进过多方向,而是按“三阶段”推进。
### 第一阶段:补基础工程能力
建议先完成:
- 配置与密钥治理
- 后台安全增强
- 人工验证与回归清单
- 系统健康与观测面板
- 消息链路 Trace
阶段目标:
- 先把系统变成“敢持续改”的状态
### 第二阶段:补平台治理能力
建议推进:
- 插件治理中心
- 插件超时/熔断/隔离
- 后台任务中心
- 数据层性能优化
- 消息归档与统计分层
- AI 成本与策略中心
阶段目标:
- 让系统变成“能稳定扩展”的状态
### 第三阶段:补产品增强能力
建议推进:
- 群级个性化配置中心
- 用户反馈闭环
- 数据导出与备份恢复
- 多模态交互
- 插件模板化
- 运营分析能力
阶段目标:
- 让系统变成“更好用、更智能、更可运营”的状态
## 10. 建议优先落地的 10 个任务
如果需要进一步压缩为最小可执行版本,建议优先做以下 10 项:
1. 配置脱敏与环境变量化
2. 后台管理员安全增强
3. 人工回归清单模板建立
4. 插件处理耗时统计
5. 消息 trace_id 全链路打通
6. 任务执行历史页面
7. 插件错误与健康状态页
8. 消息表与统计查询索引优化
9. 命令帮助系统自动生成
10. 关键配置变更审计
## 11. 结论
ABOT 当前最大的优势是“功能已经足够丰富,且架构已经有平台化雏形”;最大的风险则是“功能增长速度可能快于工程治理速度”。
因此,后续优化不建议继续以“堆新功能”为主,而建议转为以下主线:
- 先提升安全性
- 再补人工验证与观测
- 再做插件治理与任务治理
- 最后继续扩展产品能力
如果这条路线执行得当ABOT 后续会更像一个稳定的机器人平台,而不是一个持续膨胀的功能集合。