ARTICLE · 1330130

AI台账助手——本地知识库技术文档

发布时间：2026-11-08 12:08:12 最近访问：2026-11-08 12:08:13

AI台账助手——本地知识库技术文档

知识库本地应用特色总结（留档）

本文基于本仓库的记忆文件、部署文档（部署文档.md）、使用手册（USAGE.md）、近 60 条 git 提交以及相关代码（services/kb、services/docmeta、services/llm、services/docxtool 等）整理而成，用于记录本系统在"知识库的本地应用"上的核心特色，重点聚焦检索准确性与扩展功能两大方向。

一、本地化与工程形态（底层特色）

本系统是一个单文件、可离线、数据不出机的台账知识库，以单二进制 office_work.exe（Go + PHPWord，HTML/静态资源走 go:embed）形态运行，知识库存于单文件 SQLite（data/kb/cortex.db，底层 cortexdb：FTS5 + HNSW）。几个关键设计取向：

本地大脑优先：默认本机模型 gemma4:e4b（Ollama + 核显/CUDA 加速），含个人信息的帮扶材料默认不出机；云端（DeepSeek）仅作速度选项，且设置页顶部明确标注"全量出域"告警。公众号助手的 AI 成稿/模板生成同样跟随 llm.active，选本机时主题与素材完全不出机，选云端时每次生成都要二次确认。
词法向量而非语义向量：分块向量是 64 维词法哈希（lexicalVector），不是真实 embedding。这一约束决定了检索不能靠语义召回兜底，必须走"词法精修"路线——这正是第二部分全部工作的出发点。
三层链路隔离：裸 POST /api/v1/search 只测召回；/tasks/message 走完整问答链路；accbench 只测模型裸能力。三者不可互相替代，便于精确定位缺陷落在哪一通道。

二、检索准确性（核心特色）

针对"中文姓名/村名 + 大表册 + 同义词 + 错别字 + 多版本"的真实基层台账场景，系统做了一整套词法级确定性修复，而非依赖向量召回。

机制	解决的问题	关键实现
三通道加权 RRF 融合	主通道内部 FTS 臂与 CJK 二元组臂量纲错配（二元组覆盖率 0~1，FTS 的 RRF 分仅 ~0.016），导致入户报告被含"刘志"片段的 Excel 行挤掉	拆成主通道(权重1)/FTS BM25(2)/实体→标题(3)/同义词(1.5) 独立排名后加权融合（`rrfFuse`，`rrfK=60`）
行级 `row_key` 精确补召回	CJK 二元组先按 id 截断候选再打分，单村几千行时村名二元组占满候选位，目标行在打分前被截掉（实测 7015 行表只回 3 行）	入库时把户主/姓名写成 `row_key`，建表达式索引，按精确值 SQL 补召回，不受候选截断影响
标题补召回	空文档/保底分块（证件照、扫描件只有文件名）的 id 排在大表后，纯二元组搜不到	`kb_doc_titles` 字典，正向"查询⊇标题词干" + 反向"标题⊇查询≥4字片段"，提升现有结果而非简单追加
错别字容错（四道闸门）	姓名错一字使二元组完全错开（黄城秀→黄成秀零重叠），命中整体跑偏	①片段 3–5 字 ②结果对该片段二元组零覆盖才可疑 ③字典单字差 + 同音仲裁（go-pinyin） ④字典零候选才走内容 LIKE 兜底；任何不确定都宁可不纠
领域同义词扩展	"监测户/三类人员/监测对象""补贴/补助"词面完全不相交，纯词面检索必断链	`synonymGroups` 把同概念不同写法各跑一路 BM25，轮询交错合并（避免一个变体挤掉其余）
FTS 长查询短语化	纯中文长句被当一条连续 trigram 短语，几乎必空	`ftsMatchPhrases` 拆成"短语" AND：剔停用词（有哪些/多少/的）、≥3字残段加引号、全角标点绝不混进汉字段
实体聚焦过滤	"刘志春的报告"混入只含"刘志"（调查员）的叶志辉报告	查询含真实人名（姓名字典命中）时，整份文档须命中该实体词才保留；为空则整体退回（宁多勿缺）
填表说明降权	xlsx 把"填写说明"存进每列，靠关键词稳压真数据块	`isHeaderBoilerplate` 判据 + 融合分 ×0.25，不删只压
多版本收敛	同一户/同一村情材料多版并存，模型拼着答导致"数字漂移"	`latest_only` 双族：户内按业务时间留最新（`keepLatestPerHousehold`）+ 村情整份材料按"村名｜资料名"留最新（`version_family.go`，跨命名识别《一口清》新旧版）；默认关闭，检索页仍可看全部历史
人名闸门（根源治理）	户主字段抽错会把不同户合并/误分组	`IsLikelyPersonName` 四层架构：百家姓触发 → 地名后缀排除 → 120万人名语料用字统计（含农村俗名补充表）→ 未登录词拒绝；告别逐噪声加黑名单
诊断与性能	大库慢查询难定位、重复全表扫描	慢查询(>1s)按阶段打耗时；`row_key`/`doc_id` 表达式索引强制走索引；`docRowsCache`/`chunkCountsCache`/`likeCache` 缓存 + `Warm` 预热

一句话概括：系统把"中文姓名/村名检索"这种语义向量帮不上忙、却最容易出错的场景，用纯 SQL + 字典 + 同音 + RRF + 多版本治理的确定性工程手段，做到了可解释、可回归、不会因为猜错而静默答错。

三、扩展功能的特点

围绕"把材料用起来"而非"只存起来"的目标，扩展功能呈现几个鲜明特点：

多入口协同：管理后台 /admin、手机任务页 /tasks、免登录"查询页" /q/<令牌>（令牌即凭证，用完即删）、公众号写作助手「发文章」/admin/mp（知识库的内容出口，详见第五节）。其中微信机器人是日常最高频入口，能力最完整，详见下文「四、微信机器人（最高频入口）」。资料全库共用，并自动带"最近上传/最近入库"两份上下文清单。
直接改原 docx + 转 PDF：不走模板重填，而是 Word COM（docx_tool.py 内嵌进 exe）在原件上改字、套 A4（超版心宽图等比缩入，防裁切）、加图注（逐图说明、同页居中）、导出 PDF；串行互斥 + 超时 tree-kill 孤儿进程 + WPS 回退，绝不误关用户自己开的 Word。
指标中心 / 迎检材料（特色闭环）：AI 读《考核清单》→ 材料类型打标（13 类闭集）→ 缺件/过期盘点 → 按户缺件下发 → 补录闭环标记 → 一键打包（Word 汇报 + Excel 缺件 + 每户产物）。强调只读溯源：每日只读 lint 体检、按户时间线（只认正文业务时间，绝不用 mtime）、kb_changelog 审计、答案引用校验——原文只读、元信息只增不改。
去重与冲突治理：上传即 FindSame 冲突检测（精确指纹/同户同名/资料族跨命名三依据），FindDuplicates 三种分组（exact/household/title）保守提示，默认"都保留"防误删。
快路径 + 云端脱敏：kb_query 高置信查询跳过 agent 工具环，直接检索 top_k + 单轮生成（实测 284s → 12.4s）；脱敏通道把身份证/手机号/银行卡（Luhn 校验位防误报）替换为占位符出域，本地还原并校验残留，云端不通熔断回落本机——问答快路径的脱敏不构成全局保护（设置页明确提示）。公众号助手另有一条独立的硬兜底：成稿/模板的所有输入与输出都过 redact，且通道跟随 llm.active + 云端二次确认。
MCP 工具与自动化：内置 file/excel/doc/web/zip 五组本机工具，主 exe 自身充当 MCP 服务端（无需额外 exe），后台热加载；配合定时提醒/催办、异步任务、自动备份（VACUUM INTO 一致性快照，默认凌晨 3 点留 7 份）。
离线地图：离线百度 GL 引擎 + annotations.db，不依赖 9091 后台；标注按几何中心画彩色点、房框只读保留；写接口刻意独立路径 + 登录白名单按路径精确匹配（防 POST/DELETE 被免登录公开）。

四、微信机器人（最高频入口）

微信助手是基层日常使用最频繁的入口：管理后台「系统设置 → 机器人接入」逐个扫码绑定（iLink Web 登录，二维码以 base64 直接回前端展示），每个机器人对应一个 iLink 账号、一套独立凭证与交互日志。

登录后发给机器人的任何消息都进入 AI 任务系统——不再是"发关键词直接查资料"的固定路由，而是模型理解意图后，可能查库、读刚发的文件、查采集数据，也可能执行授权内的操作（生成 Word、导出台账、订阅报告）。

多人怎么共用：iLink 协议只处理一对一的用户消息，代码里没有群聊/群消息分支（handleMessage 只认 messageTypeUser），所以不能拉群；工作队成员把任一机器人加为好友私聊即可，各自发消息各自答。会话与任务按发送者 FromUserID 分开，但这是会话隔离，不是数据隔离——知识库、上传目录、最近上传全库共享，同一份资料不会重复入库。多机器人只是「多绑几个微信号」，不改变共享口径；加任意一个都能查到同一批资料。

隔离边界与生命周期：列表存 data/wechat/bots.json；仅凭证与日志按机器人隔离（credentials-.json、logs-.jsonl、raw_items-.jsonl），data/uploads/wechat// 按用户分目录但不按 bot 分。异步推送靠「用户→机器人」映射落盘 data/wechat/user_bots.json（0600），重启后第一次就能找对号，不必等用户再发一条消息。

停用/删除实例会取消该实例专属的可取消 ctx 并等待消息循环真正退出（30 秒退避也能打断）；删除时把凭证/日志/raw 归档到 data/wechat/archived/-<时间戳>/（不真删、同名重建不会继承旧登录态）。

服务关停统一取消并等待三个定时扫描器（备份/提醒/报告）收尾，避免与关库抢写锁。

下面 1–4 是能力主线（单机器人与多机器人下完全一致）；公众号写作助手是另一条内容出口，见第五节。

1. 两种问答形态

任务化 agent 模式（主路径）：消息进入 agent 工具环（MaxRounds=6），多轮查库 / 读文件 / 生成文档，可完成"查资料 → 起草填报规则 → 生成 Word 模板"这类复合任务。
单轮 RAG（降级路径）：agent 不可用或 LLM 未配置时，退回 kb_search + 大模型综合 的单轮检索回复；模型仍未配置则再退回"原文片段罗列"。机器人永远有回应；长回复由 sendChunks 分批发送（每条 ≤1950 字、最多 5 条、相邻间隔 350ms 防限流），不再把一条长回复截断成半截消息。

2. agent 工具环能力集（挂接即启用）

工具	能力	备注
`kb_search`	在资料库检索片段，带 `file` 参数可定向到某份文件查，避免全库混入其他文档内容	用户说"这个文件/文件里的XX"时强制带 file
`kb_stats`	资料库概况（文档数 / 文本块数 / 向量维度）	—
`list_word_configs` / `gen_word`	从资料库批量生成 Word（研判报告 / 月报等），返回公网可下载链接，微信里直接发	微信无文件发送 API，靠外网链接下发
`list_task_data`	查任务采集数据：谁交了表、每户填了哪些字段	只读
`create/list/delete_report_schedule`	订阅"每月 X 号自动出报告并推送下载链接"	删除类工具有确认闸门
`map_find_household`	上户查户位置并发回定位截图（"刘观喜家在哪"）	仅当离线地图资源就绪时挂上
外部 MCP 工具	`mcp.json` 配置即白名单，无配置则 no-op	可在微信里说"帮我接一个 XX 的 MCP server"

门控式意图理解：消息含 ≥2 个问题或超长时，先用 1 次云端 LLM 把乱输入拆成"逐题 + 短语关键词"的结构化检索计划注入 agent 首轮，agent 照计划逐题单独 kb_search、按序编号作答、每题标注来源、查不到不编造；轮数随问题数放大并封顶 40 防失控。简单输入完全不走这一步，快路径零开销。

3. 附件自动入库（高频刚需）

聊天里发来的文件/图片自动解析入库，并按扩展名分流：

文档（Word/Excel/PDF，含老版 .xls/.doc 走 docling 纯 Go 解析）；
图片走本地 OCR（RapidOCR）：先判"普通照片"跳过（防把风景照脑补成乱码入库），再做质量门禁（乱码率过高且内容过短则拒收），避免脏数据污染检索库；
压缩包.zip/.tar.gz/.tgz/.rar/.7z 自动解压逐篇入库（rar/7z 走纯 Go 库无 cgo；含 GBK 文件名还原、子目录建父目录、包内同名冲突直接覆盖旧版）。

入库三道关卡（保守防误删）：

①内容指纹去重——同一份原样重发直接跳过，若库里旧标题是 GBK 乱码则按本次正确文件名修正；

②冲突检测——同户/同名但内容不同（改版重传）登记"待决事项"并问用户：1️⃣替换旧版（旧原件移入归档夹、不删除）→2️⃣两版都留→3️⃣只存档不入库（默认）；

③正常入库。原件永远先存档再入库（以后重解析/换分块策略靠 source_path 反查），并把"最近上传"备忘落库（每用户最多 3 份、重启不丢），支撑"这个文件"的指代定向。

4. 一句话做成公开查询页（微信口令快车道）

发一份 Excel + 说"做成查询页"，机器人把这张表变成只读、可筛选分页的公开网页（/q/<32位令牌> 免登录白名单，令牌即凭证、用完删），微信原生发图推送二维码；支持改名口令、删除口令（连数据表一起 DROP）。双指令快车道（改名/筛选/删除）+ LLM 人话兜底，让手机上不发后台也能自助出公开表。

安全与隐私治理

后台开关 allow_upload 控制是否允许聊天上传；写操作（生成、删除、订阅取消）经确认闸门，明确"确认/取消"语义，其他内容一律不视为同意。
微信上传件对网页端可见是有意为之：知识库是全局单库，同一份资料微信入库后网页任务照样能检索、读全文，不要求再发一遍。
工具环里"知识库资料严禁用 mcp_pdf_* / mcp_file_read_file 读源文件"（不在本机磁盘），从提示词纪律层堵住读盘误调用。
内容出口的出域闸门：公众号助手的 AI 成稿/模板生成按 llm.active 选端点，云端模式必须带 allow_cloud（页面每次生成前弹窗确认）才放行，绕过页面直调接口一律 400；所有输入与 AI 输出过 redact 硬兜底，prompt 里的隐私红线只是软约束，推送草稿前仍需人工复查。

五、公众号写作助手（知识库的内容出口）

顶栏「发文章」（/admin/mp，排在「问 AI」之后、不属于「出 Word」组）把知识库材料变成可直接进公众号草稿箱的文章：

5 套出厂模板 + 自建模板：guide-steps / magazine / notice / tech-dark / report 五套内置 HTML 模板，源码以 text/plain 只读回传、预览走 sandbox iframe；可用 AI 按一句要求生成新模板，预览确认后另存，出厂模板禁覆盖禁删。模板正文不写填写说明，避免残留进成品。
AI 成稿 + 人工修订闭环：选模板 → 填主题/素材/附加要求 → 产出标题、摘要、正文 HTML；成稿可在可视化预览（contenteditable）与源码间双向切换修改，确认无误后才推草稿箱。系统只调微信草稿 API（素材上传、draft/add、batchget、delete），没有发布/群发能力。
按需取材并脱敏：勾选「用知识库取材」后按主题检索（latest_only 防串版本）；检索结果与用户手粘的素材、主题、模板 HTML 在发送前统一过 redact（身份证/手机/银行卡号 → 占位符），AI 输出的标题/摘要/正文再脱敏一次。prompt 另写隐私红线：人名一律 xx、地名泛化为 xx村/xx乡、完整格式号码绝不出现。
通道跟随 llm.active：成稿与 AI 生成模板都走 Complete()（按当前启用的端点选路），不再固定 CompleteOn("cloud")。本机 = 输入不出机；云端 = 页面二次确认 + 服务端 requireCloudConfirm 强校验 allow_cloud。本机小模型写长 HTML 较慢/质量略低，这是「数据不出机」的代价，页面已明示。
凭据单一入口：AppID/AppSecret 存 config.yaml 的 mp 段（gitignore + 0600），唯一写入口是「系统设置」的公众号凭据卡；/admin/mp 只显示只读状态并跳转。AppID 默认只读展示（防浏览器把网站账号自动填进 AppID 框），前后端双重格式校验（wx+16 位十六进制 / 32 位十六进制），AppSecret 永不回显明文、只回带首尾片段的掩码。