huishi · 事件处理中心（HuishiEvents）

插件化的事件管理平台：文件摄入 → LLM 抽取 → 事件/实体/关系 → 归一 → 关联分析 → 任务/告警/地图展示 的全链路系统。 前端纯静态、后端 FastAPI，可在局域网离线环境下以 Docker 一键部署。

项目现状（2026-08-07，master）：系统已全链路跑通并部署 1.0.5，含 9 个已上线工作台 + 14 个后台引擎 + Docker 离线交付包。本文档描述当前现状；历史骨架/契约交付记录见文末「历史存档」。

---

技术栈

层	选型
后端	Python 3.11 · FastAPI · SQLAlchemy 2.0（asyncmy / pymysql 双驱动）
数据库	MySQL 8.0（111 张表，utf8mb4）
前端	纯静态 HTML/JS（无构建链），插件自动挂载
LLM	OpenAI 兼容端点（内网 Ollama/vLLM），用于抽取/意图解析/语义判定
文档转换	LibreOffice（soffice）txt→PDF，pypdf/img2pdf/rarfile
部署	Docker Compose 双容器（app + worker），镜像离线打包

系统架构

• 单进程 uvicorn main:app（端口 8001）：main.py 自动扫描 plugins/ 注册插件，挂载后端路由 + 前端静态资源，业务代码零改内核。
• worker 进程 run_worker.py --engine all --concurrency 4：14 个后台引擎并行消费队列/定时扫描。
• 生产部署为 app + worker 双容器（docker-entrypoint.sh 按角色 app|worker 启动），共享 MySQL；任一容器退出由 compose 自动拉起。
• 无 Redis 依赖（内存 LRU 兜底），REDIS_ENABLED=false。

后台引擎（14 个，plugins/events/backend/workers/engines/）

引擎	职责
folder_watch	监视 watch_inbox/，新文件自动入抽取队列
extract	三引擎抽取：mysql_fulltext / preset_rule / LLM（出 events / entities / relations）
canonical	实体归一匹配队列（hybrid：字典→映射→名称规则→LLM 兜底）+ 孤儿扫描 + 关系同步
cooccur	实体共现交叉验证，产出候选关系给 LLM 判定
correlate	关联审核（观测点与事件距离关联）
normalizer	归一前置规范化
tagger	自动打标
alerting	告警周期评估（45s，冷却/封顶/动作链/升级）
detect / fusion / inference / attachment_sync / remote_poll / task_reconcile	检测 / 融合 / 推理 / 附件同步 / 外部拉取 / 任务复核

工作台（前端 frontend/tabs/）

已上线（9 个）：

工作台	页面	职责
事件管理台	manage.html	事件 CRUD、标签、多媒体证据、关联实体/文件/任务、时间线
世界地图事件台	mapdisplay.html	世界地图事件可视化、多维筛选、标记聚合
归一复核台	canonical.html	归一匹配队列：合并/拆分/确认 canonical、决策链追溯
关联分析台	assoc.html	实体-实体 / 实体-事件关联分析（无限滚动分页加载）
抽取台账台	ledger.html	文件→事件→实体台账、条件重新抽取
多媒体标注台	media.html	文件上传（年/月日去重）、内容抽取、结果审核导入
任务管理台	watchlist.html	任务草稿五态、监视清单、命中管理
告警配置台	alerting.html	告警规则、日志处置、误报反馈
标签管理台	tags.html	标签 CRUD、AI 生成、自动打标规则、统计

P1 预留（置灰）：融合复核台 / 推理审核台 / 流水线监控台 / 本体配置台。

核心业务数据流

watch_inbox/ 拖入文件
   → folder_watch 入队 → extract（LLM 按 prompt 抽取）
   → events / entity_instances / entity_relations
   → canonical 归一（实体合并到 canonical）
   → 同步 subject_associations（事件↔实体 involves / 实体↔实体 relations）
   → 关联分析台 / 地图台 / 任务 / 告警 消费

目录结构

huishi/
├── main.py                    # 后端入口（自动扫描插件）
├── kernel/                    # 内核（鉴权/配置/文件存储/db 池，业务零改动）
├── plugins/events/            # 事件插件（唯一业务代码）
│   ├── manifest.json          # 插件清单（前缀 /api/events，挂载 /app/events）
│   ├── run_worker.py          # worker 启动器
│   ├── backend/               # routers 10 个 / services 17 个 / workers 14 引擎
│   └── frontend/              # index.html + tabs/（13 个工作台页面）
├── docker/                    # 离线部署：compose / 一键部署脚本 / init-scripts
├── dist/                      # 交付包（build_pipeline 生成，gitignore）
├── build_pipeline.ps1         # ★ 流水线打包脚本（改码后重跑出新交付包）
├── prepare_packages.ps1       # 下载 Linux 离线依赖（wheels+debs）
├── Dockerfile / docker-entrypoint.sh / requirements-docker.txt
├── 种子SQL_当前库/             # 权威初始化 SQL（00 全量 schema+种子）
├── scripts/                   # upgrade_db.py 等运维工具
├── tools/                     # redline_check.py 红线检查
└── 契约包/ 说明/               # 契约与设计文档

启动方式

开发机（Python 3.11 虚拟环境 .venv311/）

# API 进程（端口 8001）
python -X utf8 -m uvicorn main:app --host 0.0.0.0 --port 8001
# worker 引擎
python -X utf8 plugins/events/run_worker.py --engine all --concurrency 4
# 红线检查（CI 门禁）
python tools/redline_check.py plugins/events

Docker 离线部署（目标机，见 README_DEPLOY.md 全文）

开发机跑一次 build_pipeline.ps1 版本号 生成 dist/，拷到目标机（仅需 Docker）：

# 目标机两条命令即可上线
deploy.bat [版本号]      # 或 deploy.sh：加载镜像 → 交互配置(.env) → 启动 → 验证

• 访问入口：http://<本机IP>:8001/（根地址自动进登录门户）
• 默认账号：admin / admin123456
• 升级：改码 → 开发机 build_pipeline.ps1 1.0.6 → 拷新 dist/ → 目标机重跑 deploy → 业务数据卷保留

相关文档索引

文档	内容
README_DEPLOY.md	离线部署/升级完整说明书
已解决Bug清单.md	已修复问题 + 预防踩坑要点（改代码前先看）
插件开发手册.md / plugins/events/事件插件开发手册_v1.1.md	新业务接入规范
契约包/	接口/表/队列/前端契约（历史基线，以代码为准）
说明/软件设计说明2.0.md	设计意图

---

历史存档（v1.2 骨架交付，仅作契约参考）

早期 README 记录的「events 插件骨架与契约包 v1.2」为多团队并行开发时的地基交付（骨架 + 契约包 + 红线检查），P0 五组交付后已逐步演进为上述完整系统。契约类文档与现状有出入的，以代码为准。