FireKB · 消防工程知识库

把教材、规范和课件整理成带文件与页码出处的知识点，再生成复核材料和复习产物。你可以通过桌面端完成主要处理步骤，也可以继续使用命令行。

当前版本：0.2-latest · 开发测试版（内部版本 0.2.0）。本版在 0.1α 命令行流水线的基础上，新增桌面工作区、外观设置、设备检测、本地文本模型部署和云端接口配置。

完整更新记录 · 桌面端说明 · 更新日志

从 0.1α 到 0.2-latest

更新	你可以做什么
桌面工作区	从左侧切换素材输入、处理控制、结果输出和模型配置，查看课程及规范分类
更简洁的外观	使用纯白主背景、更小的字号和轻量玻璃动效；选择雾蓝、苔绿、暖砂、石墨，以及浅色、深色或跟随系统模式
素材与处理	选择文件、文件夹或拖入路径，去重和移除条目；运行解析、OCR、骨架、抽取和核验，查看实际日志
结果浏览与导出	按课程查看知识点、核验状态及来源页码；每页 40 条，Markdown 导出包含全部筛选结果
设备检测与本地部署	查看 CPU、GPU、显存、内存及磁盘余量，选择速度、均衡或质量档，一键配置支持的本地文本模型
云端接口	配置百炼、DeepSeek、OpenRouter 或自定义兼容 API，保存模型与密钥，测试文本和 JSON 返回
手动数据批准	资料默认留在本机；按数据类别、接收方和用途手动批准云端发送，并可撤销批准

文件与页码溯源、逐字引用核验、数字检查和人工复核继续保留。完整更新记录还包含配置、验证和已知边界，方便从旧版升级时逐项核对。

怎样使用

1. 准备素材。 将 PDF、PPTX、EPUB 按课程归档：教材与规范放入 10_原始归档/规范教材/<课程名>/，课件放入 10_原始归档/课件/<课程名>/；在素材页可选择文件或文件夹，查看并整理路径清单。
2. 选择文本模型。 打开「模型配置」，根据设备检测结果选择本地档位，或填写云端 API。使用云端处理资料前，先批准对应的发送范围。
3. 运行处理。 在「处理控制」依次解析、按需 OCR、构建骨架、抽取知识点并核验。OCR 先检查规模；抽取先试跑 3 个块，检查后再确认全量执行。
4. 查看和复核。 在「结果输出」按课程查看知识点与来源，导出 Markdown 或生成复习产物；待确认内容还需进入人工复核流程。

素材页目前只管理路径清单，不会自动复制文件入库。 处理仍读取 10_原始归档/ 下的素材；请先完成归档。当前也未实现粘贴文本解析。

安装与启动

当前提供源码及直接构建启动方式，安装包尚待干净机器验收。以下命令适用于 Windows PowerShell。

1. 准备环境并初始化

• Python 3.12+；按以下克隆方式安装需要 Git。桌面端另需 Node.js 18+ 和 npm。
• 使用云端文本模型不要求独立显卡；本地推理的硬件要求见下文。
• Python 和文档处理依赖需事先安装；使用本地 NVIDIA 推理时还需预先安装对应驱动。一键配置功能只负责支持的本地文本模型环境。

git clone https://github.com/alts1450/FireKB.git FireKB
cd FireKB
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install pypdf pypdfium2 python-pptx
.\.venv\Scripts\python.exe -m firekb init
.\.venv\Scripts\python.exe -m firekb --version
.\.venv\Scripts\python.exe -m firekb doctor

init 创建目录，并从示例模板生成配置，不覆盖已有配置。请按提示编辑 00_配置/courses.json，填写自己的课程信息。

按需依赖	用途
rapidocr-onnxruntime、numpy	扫描版教材的 OCR
faster-whisper、命令行可用的 ffmpeg	本地录音转写
reportlab	生成不含真实教材的合成样例

只需安装准备使用的环节依赖。例如，安装 OCR 和合成样例依赖：

.\.venv\Scripts\python.exe -m pip install rapidocr-onnxruntime numpy reportlab

2. 构建并打开桌面端

在完成初始化的同一 PowerShell 窗口中执行：

cd firekb-desktop
npm ci
npm run build:app
$env:FIREKB_ROOT = (Resolve-Path ..).Path
$env:PYTHON_PATH = (Resolve-Path ../.venv/Scripts/python.exe).Path
npm start

FIREKB_ROOT 指向项目根目录，PYTHON_PATH 指向已安装依赖的 Python。移动项目或换终端后，需要重新设置这两个环境变量。当前尚无可保存这些路径的首次启动向导。

3. 先用合成样例体验

另开终端并进入项目根目录；确认已安装 reportlab，再执行：

.\.venv\Scripts\python.exe -m firekb testdata
.\.venv\Scripts\python.exe -m firekb parse
.\.venv\Scripts\python.exe -m firekb skeleton

样例写入 10_原始归档/课件/_样例验证/。首次在空项目运行时，可体验文件解析和骨架生成，无需 API Key；这里尚未生成知识点。抽取知识点还需配置文本模型，使用云端时需批准相应数据类别。

选择本地模型还是云端

本地文本推理

当前最低参考配置为 Windows x64、i7-13700F、RTX 4060 8GB、16GB RAM。这是本地模型部署门槛；运行桌面界面和使用云端接口不受此显卡门槛限制。

应用会分别检查硬件总容量和当前可用资源。低于门槛、资源不足或型号未确认时，显示云端建议及原因，由你选择接口；不会因此自动发送资料。多个 GPU 的显存不相加，未知等效型号及 Laptop/Mobile GPU 需独立验证。

档位	当前支持的模型	可用显存估算	可用内存估算	项目磁盘余量
速度优先	Qwen3.5 4B · Q4_K_M	4.5GB	6GB	18GB
均衡	Qwen3.5 4B · Q8_0	6.5GB	8GB	20GB
质量优先	Qwen3.5 9B · Q4_K_M	7.5GB	9GB	24GB

以上是资源估算，尚无真实 4060 三档性能成绩；档位名称表示选择取向。质量档在 8GB 显存下余量紧张，限短文本试用。

点击「一键配置本地环境」并确认下载后，应用安装固定版本的 Ollama 便携环境、校验下载文件、拉取模型并检查 GPU 加载，全部成功才切换文本接口；失败保留原配置。运行环境和模型保存在项目 .firekb-runtime/，服务仅监听本机 127.0.0.1:11435。

部署和运行指令可在界面中查看、复制，也可通过命令行使用，详见桌面端说明。本地长文超出上下文预算时会明确拒绝，不静默截断证据，也不自动转到云端。

云端文本推理

在「模型配置」选择平台或自定义兼容 API，填写接口地址、模型和 API Key，保存后测试连接。模型名称、账户权限和区域可用性需要按实际平台核对。

密钥显示为掩码。连接测试仅发送固定合成句，不读取教材或笔记；真实平台可能收取测试费用。保存接口和测试连接均不批准生产资料上传。

本版的一键部署及云端连接配置主要用于文本模型。解析、OCR 和转写保持原有引擎选择；嵌入、重排、云端 OCR/ASR 尚未完成独立适配。

数据由你决定是否进入云端

0.1α 中个性化数据一律不出本机；0.2-latest 改为默认留在本机，手动批准后所选类别才可发送至指定云端。

在「模型配置」选择可发送的类别、填写确认备注，再通过原生对话框确认。批准绑定接口地址、数据类别和知识处理用途，持续有效直到撤销；换接口需要重新批准。旧版个人数据记录不会因升级自动变成有效授权。

点击「撤销全部批准」会拦截之后的新请求；已发送的数据需按接收方规则处理。录音、转写、笔记、错题和复习记录也遵守批准流程。允许某类数据出站不代表相应的云端处理引擎已经实现。

密钥、批准记录、部署状态、运行日志和真实学习数据不随公开仓分发。请自行确认教材、规范和录音的处理权利，手动批准不能替代这些权利。

结果怎样核验

每条知识点保留来源文件与页码。模型引用与原文比对后分为四档，只有 exact 计入引用核验通过：

状态	含义
exact	引用逐字命中原文
partial	引用部分匹配，仍需人工确认
fabricated	仅头部或尾部匹配，按不可靠引用拦截
not_found	未找到匹配引用，进入复核

数字检查区分 1.5 与 15 等差异；页码支持 PDF 物理页与印刷页校准。录音转写仅提供课堂线索，不作为教材或规范引用来源。引用核验通过表示找到了原文，不等于结论已获得专业审定。

命令行仍可使用

在项目根目录执行；以下为处理顺序，OCR 仅在需要时运行。教材和规范放入 10_原始归档/规范教材/<课程名>/，课件放入 10_原始归档/课件/<课程名>/，并核对课程配置。

.\.venv\Scripts\python.exe -m firekb parse
.\.venv\Scripts\python.exe -m firekb ocr
.\.venv\Scripts\python.exe -m firekb skeleton
.\.venv\Scripts\python.exe -m firekb extract --limit 3
# 检查试跑质量后，再执行全量抽取
.\.venv\Scripts\python.exe -m firekb extract
.\.venv\Scripts\python.exe -m firekb verify
.\.venv\Scripts\python.exe -m firekb review

抽取前需完成本地或云端文本配置；云端请求需有效批准。review 生成背诵卡、数字对照表和 Anki 导入等复习产物，人工复核工作表可通过 queue 生成。更多命令可用 .\.venv\Scripts\python.exe -m firekb --list 查看。

环境和结果检查：

.\.venv\Scripts\python.exe -m firekb doctor
.\.venv\Scripts\python.exe -m firekb selftest
.\.venv\Scripts\python.exe -m firekb consistency
.\.venv\Scripts\python.exe -m firekb schema

doctor 返回 7 表示尚未初始化，6 表示仅可选引擎未就绪，5 表示硬门槛失败；0 为全部通过。处理环节返回 4 表示运行完成但有失败项，应查看失败清单。

从 0.1α 升级

1. 备份 00_配置/.env、引擎和课程配置，以及原始素材、文本库、知识点库和复习产物，再更新源码。保留旧 commit 或 v0.1.0-alpha 标签便于回退。
2. 在项目根使用 .\.venv\Scripts\python.exe -m firekb --version 查看版本，再将 --version 换为 doctor 和 selftest 分别检查环境与运行自检。
3. 进入桌面目录执行 npm ci 和 npm run build:app，按启动步骤设置项目根与解释器。
4. 核对文本接口和手动批准范围。示例模板更新不会覆盖已有 .env；低配推荐和平台选择不会自动放行资料。

本版保留知识点、证据和页码产物契约，但仍不承诺后续版本向后兼容。latest 表示当前开发版本，不表示生产验收完成或已有自动升级通道。

当前验证与限制

本版已通过 198 项统一单元检查、桌面类型检查与构建、隔离桌面流程验收和公开副本的 7 步基础上手检查。真实 4060 模型安装与性能、付费云端全流程和干净机器安装包仍待实测，现有验证不代表这些场景全部通过。

• 扫描版资料需先 OCR；复杂表格、公式和英文教材的抽取效果需人工检查，页码偏移需按文件校准。
• 素材自动归档、粘贴文本解析、保存路径向导、完整任务取消和桌面原页同屏复核仍待完善；人工复核可先使用 CLI 工作表。
• 当前分页减少界面渲染数量，后台仍读取整份知识点文件；超大知识库的查询与索引需进一步优化。
• 研究文档中的其他模型、语音及嵌入方案尚未全部集成。当前可一键配置的文本模型仅为上表三档。

仓库内容与许可

仓库包含代码、配置模板和文档。教材、课件、录音、派生知识库、API Key 和模型权重均不随仓库提供；请准备自己的合法素材。

firekb.py          命令行入口
firekb-desktop/    桌面端源码与使用说明
tools/            解析、抽取、核验、复习及设备配置工具
00_配置/           配置与示例模板
10_原始归档/       用户素材（初始化后创建，不入版本库）
20_文本库/         页级文本与转写
30_知识点/         知识点、证据与核验数据
40_复习产物/       导出和复习材料
90_日志/           运行记录

项目代码采用 MIT 许可。第三方依赖与可选引擎另按各自许可使用，详见第三方说明。数据目录和机器状态不进入公开版本库。