AI极客实战案例日报

01｜案例是什么？

一位中文独立开发者 xiwc 开源了一个浏览器扩展 AI Helper（Chrome / Edge，MIT）：它让大模型在你的浏览器里真的动手——点击、填表、拖拽、上传文件、跑终端命令，并通过 MCP 协议扩展能力。10-06 他写了篇实战文，讲怎么用「一个主助手 + 三个子助手」把写好的 Markdown 自动发布到掘金与知乎；10-07 另一位作者 weFri 在 InfoQ 记录：用同一个插件，让它自己把项目 Wiki 从零写成 8 页中文 + 8 页英文，并同步到 Gitee。项目在 10-08 发布 v2.0.0。

02｜为什么今天值得关注？

• 窗口内的事实（可核实）：AI Helper 在 48 小时窗口内连续发布 5 个版本——v1.17.4（10-06 20:49）、v1.17.5（10-06 21:01）、v1.17.6（10-07 11:49）、v1.17.7（10-08 08:43）、v2.0.0（10-08 08:56）；两篇一手实战记录分别落在 10-06 与 10-07。
• 为什么以前不容易做：浏览器自动化长期是「写代码的人的活」（Playwright / Selenium / 油猴脚本），选择器一变就全废，普通内容创作者根本碰不到；而中文平台各有各的富文本编辑器内核，通用方案一注入就乱码、丢字、串位。
• 为什么现在变得容易：① 浏览器扩展 + LLM 把「操作网页」变成了自然语言；② ReAct 循环让 Agent 自己决定下一步调哪个工具，而不是人预先写死流程；③ MCP 让「浏览器控制 / 文件读写 / 命令执行」从内置绑定变成可插拔工具；④ 有人把中文编辑器的坑逐个踩完并写成文章。
• 为什么值得花时间：「AI + 内容」这个方向在中文一手来源里长期稀缺（过去多期由内容农场垄断），这次是少见的、带真实代码与真实踩坑的执行记录。

03｜案例的前世今生

前世。2023–2025 年，浏览器自动化的主体是程序员写的脚本：selenium 到 Playwright 再到油猴脚本，共同点是「人先假设页面长什么样，再写选择器」。页面改版 = 脚本报废。早期「AI + 浏览器」也只是让模型生成选择器，本质仍是脚本，换不来鲁棒性。

发展。四条线先后成熟：① 长上下文与多模态让模型能读 DOM、也能看截图；② ReAct 范式（Thought → Action → Observation）把「想一步、做一步、看结果、再决定」变成可循环的工程结构；③ MCP 在 2025 年成为事实标准后，浏览器控制、文件读写、终端执行可以统一挂成工具；④ Chrome 扩展作为载体，绕开了「让普通用户先装 Python 环境」这道硬门槛。

今生。AI Helper 没有发明新模型，做的是「把上述零件装进一个浏览器扩展，并把 AI 操作中文网页的工程细节做到可用」。作者的公开记录里有两条真实使用路径：内容分发（知乎 Draft.js / 掘金 ByteMD）与文档自动化（项目 Wiki 双语化 + Gitee 同步）。这两条路恰好一份覆盖 B 端、一份覆盖个人创作者。

下一步可能怎么发展（分析 / 推演）。浏览器 Agent 会从「帮你点一个页面」走向「帮你守一个流程」——定时盯页面、变化告警、异常自动处理；企业侧可能出现「内部系统操作 Agent」，把没有 API 的老系统（老 ERP、老 CRM 网页端）用浏览器 Agent 兜住。以上为推演，非事实。

04｜原始资料

• 一手原文掘金（2026-10-06）《我用 MCP + 多 Agent 搭了一条自动化内容发布流水线》，作者 xiwc
  https://juejin.cn/post/7692743968833847305
• 一手原文InfoQ 写作社区（2026-10-07）《AI Helper 实战：从零搭建开源项目的双语 Wiki》，作者 weFri（上海）
  https://xie.infoq.cn/article/11b0e4a51cd3d652ec2dbb4c9
• 开源仓库xiweicheng/ai-helper（MIT，JavaScript，建于 2026-06-21）
  https://github.com/xiweicheng/ai-helper
• 发布记录Releases（窗口内 v1.17.4 → v2.0.0）
  https://github.com/xiweicheng/ai-helper/releases
• 项目主页官方文档站
  https://xiweicheng.github.io/ai-helper/
• 作者主页掘金 · xiwc
  https://juejin.cn/user/1662117310119655/posts
• 分发渠道Microsoft Edge 扩展商店页（AI Helper 网页智能助手）
  microsoftedge.microsoft.com/addons/detail/…/kabhmgfbkhpbfhhnokaafhkdbckeipcl

05｜作者是谁？

• 开发者：xiweicheng（掘金 ID xiwc），独立开发者。GitHub 上另有开源项目 tms（团队协作 + 轻量任务看板，387 Star），说明是长期活跃的独立开发者，而非临时起号。
• 第二位作者：weFri（InfoQ 写作社区，标注所在地上海），身份是这套工具的实际使用者与记录者，不一定是项目开发者本人。

06｜解决了什么真实问题？

这个案例要从需求侧看，不从技术侧看。

需求一（内容创作者）。一个同时维护掘金、知乎等多阵地的创作者，一篇稿子写完只是开始：复制粘贴到各平台编辑器格式经常乱、代码块要重贴一遍缩进全丢、每个平台的话题与标签规则不同、发布前还得反复核对分类封面摘要。作者的原话是这些活「重复、机械、还容易出错，典型该被自动化」——他要的不是「AI 帮我写」，而是「AI 帮我把写好的东西发出去」。

需求二（开源维护者）。项目 Wiki 从零写到双语、还要同时维护 GitHub 与 Gitee 两套，纯手工极其耗时。InfoQ 那篇记录的场景是：Wiki 是空白页，要基于源码写一整套文档，还要英文版与跨平台同步。

两者的共同点：不是「不会写」，而是「不值得人写」——重复、规则明确、量大、错了要重来。

07｜完整技术栈

模型	作者未点名。ai-helper 支持保存多个 OpenAI 兼容的 provider 配置（端点 / 密钥 / 模型列表），可接 DeepSeek、Qwen、Kimi、GLM 等。原文只提到「通过 MCP 把工具挂上去」，未写具体模型型号。本文不编造型号。
载体	Chrome / Chromium 扩展（开发者模式加载）与 Microsoft Edge 扩展商店版本
Agent 形态	ReAct 推理循环（原文自述 10–1000 步可调）；主助手编排 + 子助手（浏览器自动化 / 内容处理 / 数据回收）；嵌套分派最多 2 层
工具层	MCP（Model Context Protocol）扩展。原文列出的能力：浏览器控制（点击 / 输入 / 执行 JS）、文件读写（read / write）、命令执行（exec）
本地能力	可选「代理服务」（本地 Agent）：读写本地文件 + 终端命令，官方称带三级命令安全策略与 7 天回收站
内置知识库	本地 RAG：PDF / Word / Excel / PPT / Markdown / HTML / CSV 建库，答案带可点击引用
语言	JavaScript（扩展本体）；原文用 JS 举例注入代码
部署	扩展装即用；本地 Agent 服务可选；发布记录由 GitHub Actions 自动构建 dist/ 打包
协议 / 许可	MIT（已核）

08｜完整 Workflow

路径 A：内容发布流水线（源自掘金原文）

路径 B：项目 Wiki 自动化（源自 InfoQ 原文）

09｜它到底是怎么实现的？

剥开业务内容，这套流程真正的技术内核是三个机制（均来自原文自述）：

机制一：能力抽象 —— 工具原子化，流程交给 Agent。原文的原话是「关键在于：把『能力』抽象成工具，把『流程』留给 Agent 自己规划。这样换一个平台，只要加一个工具，不用改整套逻辑。」这是浏览器自动化与「写死的 Playwright 脚本」最本质的分野：确定性交给工具，不确定性交给规划。

机制二：注入要因地制宜 —— 先侦察编辑器内核，再选方法。这是原文踩坑最多、也最有迁移价值的部分。同样叫「编辑器」，底层实现天差地别，用错方法就是白干（原文给出的对照表）：

Draft.js	伪造 ClipboardEvent('paste')。直接改 DOM 或 execCommand 会和它内部状态打架，表现为文字串位、莫名删除
CodeMirror / Monaco	拿实例调 setValue()。掘金切到 Markdown 模式后是 ByteMD，内核 CodeMirror 5，直接写最稳
原生 textarea	直接赋值 + 触发 input 事件
contenteditable	谨慎，优先走粘贴事件

// 原文给出的知乎（Draft.js）注入方式
const dt = new DataTransfer();
dt.setData('text/html', html);   // 保留标题、列表、链接
dt.setData('text/plain', plain); // 兜底纯文本

editor.dispatchEvent(new ClipboardEvent('paste', {
  clipboardData: dt,
  bubbles: true,
  cancelable: true
}));

// 原文给出的掘金（ByteMD / CodeMirror 5）注入方式
const inst = document.querySelector('.CodeMirror').CodeMirror;
inst.setValue(markdownText);

机制三：编排要扁平 —— 平台的硬限制决定了架构形状。原文明确写到：平台对子助手的嵌套分派最多 2 层（主 → 子 A → 子 B 可以，子 B 再往下派就会被拦）。所以「编排层要尽量扁平，别指望无限套娃」。这条限制直接决定了主助手必须自己承担决策，而不能层层下放。

此外还有一条工程纪律（来自 InfoQ 那篇）：不是「生成完就交」，而是「生成完逐页核对」。作者发现原文档写 9 个标签页、实际只有 7 个，且知识库 RAG 整页漏掉——这类「文档与代码不一致」是 AI 写文档最容易出的错，所以必须回到源码交叉验证。

10｜手把手复现

Step 1（原文）。安装扩展：Edge 用户走扩展商店；Chrome / Chromium 用户下载 Release 里的 ai-helper-*.zip 解压，打开 chrome://extensions/ → 开启右上角「开发者模式」→「加载已解压的扩展程序」→ 选择解压后的文件夹。发布记录说明该产物由 GitHub Actions 自动构建。

Step 2（原文）。配置模型 provider：在扩展里保存一个 OpenAI 兼容配置（端点 / 密钥 / 模型列表）。可选多家，切换时先选 provider 再选模型。

Step 3（原文）。挂 MCP 工具：把「浏览器控制（点击 / 输入 / 执行 JS）」「文件读写」「命令执行」按需挂上；若要让 Agent 碰本地文件与终端，装可选的本地 Agent 服务（原文提到三级命令安全策略）。

Step 4（原文架构图还原）。建一个主助手负责编排，再建三个子助手：A 浏览器自动化、B 内容处理、C 数据回收。注意保持扁平——不要试图三层以上嵌套。

Step 5（原文）。先侦察目标编辑器的内核，再决定注入方式：查 .CodeMirror 之类特征判断是不是 CodeMirror；拿不到实例再退到伪造 paste 事件。

Step 6（原文）。每一步都加断言：填完一步就校验 DOM，别等最后才发现某步没生效；出错优先点编辑器的「撤销」按钮回退，比强行改 DOM 安全。

Step 7（本文补充的建议）。第一次只跑单平台、单篇文章：把「打开编辑器 → 注入 → 选标签 → 停」跑通，先不让它点发布。

Step 8（本文补充的建议）。把发布、删除、修改状态这类不可逆动作设为人工确认。原文自己的终点也是「一句话 + 一次确认」——即最后那一下是留给人的。

Step 9（本文补充的建议）。把中文标签映射成平台实际提交的 value（原文踩坑第 3 条），先建一张映射表再动手，而不是让 Agent 现场猜。

11｜Prompt / Code / Config

原作者公开的内容（可直接引用）：

• 知乎 Draft.js 注入代码：DataTransfer + 伪造 ClipboardEvent('paste')（见上）
• 掘金 ByteMD / CodeMirror 5 注入代码：document.querySelector('.CodeMirror').CodeMirror.setValue(...)
• 「编辑器内核 → 推荐注入方式」对照表（Draft.js / CodeMirror·Monaco / 原生 textarea / contenteditable）
• 架构图：「主助手（编排 / 决策）→ 子助手 A / B / C」
• 五条踩坑清单（见下方「踩坑」）
• （InfoQ 篇）sync-wiki-to-gitee.sh 的设计：mktemp 建临时目录 → 双端克隆 → rsync --delete 同步（排除 _Sidebar/_Footer）→ 有变化才 commit + push → trap 自动清理；并在 package.json 增加 npm run sync:wiki

原作者未公开的内容：系统提示词全文、各子助手的完整提示词、工具清单的完整实现、扩展的构建配置细节。本文不编造这些内容。

12｜踩坑

13｜中国用户能不能直接做？

国内访问	可以。扩展本体在国内可下载（Edge 商店 / GitHub Releases）；本案例原生适配掘金、知乎等中文平台，不依赖境外站点。
注册	装扩展即用，无需注册第三方服务；要「问答」类能力时再填自己的模型 API。GitHub 下载 Release 可能需要基本网络处理。
API	任意 OpenAI 兼容端点即可。DeepSeek / Qwen / Kimi / GLM 官方均提供兼容接口，充值即用。
成本	0 元可跑：扩展免费 + 开源，配合各家模型的免费额度即可体验完整流程；长期成本按 token 计，公开发布类任务量不大。原文未给出具体 token 账单。
技术门槛	🟢 直接用 装扩展、用自然语言让它操作网页 🟡 有一定门槛 配 provider + 挂 MCP + 装本地 Agent 服务 🔴 开发者级 改扩展、自写 MCP 工具、做多助手指令编排

14｜国产替代方案

这个案例本身就是国产方案。它的对照对象不是某个可被替换的海外产品，而是「Playwright 这类浏览器自动化框架 + 闭源商业 AI 扩展」的组合。

原方案（海外心智）	Playwright / Selenium 写脚本；或闭源商业 AI 浏览器扩展（多为订阅制）
中国用户方案	项目原生支持（官方说明）：中文界面、原生适配掘金 / 知乎等中文编辑器的注入方式、可保存多个 OpenAI 兼容 provider。 已验证（官方文档级）：「多 provider」这一设计意味着可以接 DeepSeek / Qwen / Kimi / GLM 的兼容端点——这是项目 README 明确列出的能力，但原文两篇实战文未点名具体模型。 本文推测（未验证）：把主力模型换成 Qwen 或 GLM 的成本对比；在国产浏览器（360 / QQ 浏览器等 Chromium 内核版本）上的扩展兼容性。这两点未经核实，请自行验证。

必须区分的部分：「项目支持 OpenAI 兼容端点」是项目能力（可核实）；「用某个具体国产模型能跑出同样的发布效果」是尚未被原文明示的结论。不要混为一谈。

15｜中国企业可以怎么用？

• 企业场景 1：多平台内容分发的运营岗。公众号、知乎、小红书、掘金多阵地运营，一篇内容要按各平台规则改写并发布。把「格式适配 + 标签选择 + 发布」交出去，人只做选题与终审。这是案例本身最直接的场景。
• 企业场景 2：没有 API 的老系统批量录入。大量企业内网系统（老 ERP、老 CRM、老 OA）只有网页界面、没有开放 API。浏览器 Agent 可以在人工监督下完成批量表单填写与上传——原文提到扩展能「读 Excel 逐行填表并提交」，这正是这类需求的通用解法。
• 企业场景 3：内部文档自动化。把产品文档、FAQ、操作手册从源码或素材自动生成，并同步到多个内部知识库（含 GitHub / Gitee 双端）。InfoQ 那篇的流程可直接迁移到企业内部的「文档站 + 代码仓库」组合。

16｜中国消费者可以怎么用？

1. 自媒体 / 副业者：写一次，自动分发到多个平台——这是原文场景的直接消费者化版本，也是最高频的真实用法。
2. 个人知识整理：用内置知识库把 PDF / Word / Excel / PPT 等本地资料建成本地 RAG，问问题时答案带可点击引用，比「整段丢给聊天框」可信。
3. 重复性网页操作：报名、申报、批量查询这类网页表单流程，交给它按规则执行、人只做最后确认。

17｜如何变成一个赚钱的项目？

产品化。不是重做一个浏览器 Agent（那是红海），而是把「某个垂直场景的稳定操作流」做成可交付物：例如「一篇稿子自动分发到 5 个平台（含格式适配与标签规则）」的预设包 + 使用说明。交付即用、不需要服务器。

服务化。把流程卖给内容团队与 MCN：帮他们搭「主助手 + 子助手」的发布流水线，解决的是「运营每天花两小时复制粘贴」这个具体痛点。注意：账号安全与平台规则是必须一并交付的风险说明。

咨询化。帮企业找「哪些网页操作值得自动化」——尤其是没有 API 的老系统。这一步最难也最值钱：找错流程，Agent 就是个更慢的手动操作。

培训化。本案例非常适合做 Demo：它有两段真实可演示的代码（Draft.js 与 CodeMirror 两种注入）、一个可当场跑通的流程、一组具体的坑。天然适合 60 分钟 Workshop。

内容化。「中文富文本编辑器的注入姿势大全」本身就是高价值内容——它解决的是所有做工具的人都会撞上的问题，可拆成系列。

行业化。把「编辑器内核 → 注入方式」的映射扩展成行业资产：政务系统、电商后台、医疗 HIS、教育教务系统各有自己的前端技术栈，逐个沉淀就是护城河。

18｜变现路径

这是分析，不是保证收益。本案例目前没有任何已验证的收入数据可引用。

19｜如果我是一个中国独立开发者（7 天 MVP）

假设：1 个人、预算有限、有基础前端能力、使用国产模型 API。

• Day 1：装扩展，让它真实完成一件你自己的重复劳动（把一篇稿子发到一个平台），记录失败点与耗时。
• Day 2：把流程固化成「主助手 + 子助手」的职责划分，明确哪一步由哪个助手做。
• Day 3：把「注入」这一步攻下来：写一个判断编辑器内核的小函数，覆盖 Draft.js / CodeMirror / textarea 三种情况。
• Day 4：接一家国产模型 API，跑通「一条指令 → 打开编辑器 → 注入 → 选标签 → 停下等确认」的完整链路。
• Day 5：补断言与回退：每步校验 DOM，失败先点撤销；把发布动作单独抽出来加人工确认。
• Day 6：扩到第二个平台，验证「换平台只加工具、不改逻辑」这个设计是否真的成立。
• Day 7：复盘：把踩坑写成一篇可发布的内容——这既是复盘，也是你的第一批分发素材（可以在你做的工具帮助下发布）。

20｜如何迁移到其他行业

21｜培训课程设计

22｜培训师点评

23｜最终判断

这是案例属性描述，不是「最佳案例排名」。装扩展门槛极低，但要把某个平台的发布流做稳定需要真正的调试功。

01｜案例是什么？

一位中文开发者开源了 agentic-kb（MIT，Python）：一个面向中文规程文档的本地知识库智能体。它把检索做成「稠密 + 稀疏」两路并用——用 bge-m3 一次前向同时产出两路向量，服务端做 RRF 融合，再用 bge-reranker-v2-m3 重排；在此之上加了 GraphRAG 与「上下文定位语」，让答案里的 [文档名 (块 3)] 可以点回原文块。它还做了版本化索引：规程换版后旧版本默认不再召回，需要时可显式翻出废止条款。检索侧全部本地推理，只有问答与联网搜索走外部 API。

02｜为什么今天值得关注？

• 窗口内的事实（可核实）：该仓库创建于 2026-10-07 09:29（北京时间），同日 09:56 完成最后推送；当前 58 Star / 1 Fork；MIT 协议；带完整目录结构（agent / api / embed / eval / frontend / ingest / llm / retrieve / store）与四份文档（usage / architecture / evaluation / gotchas）。
• 为什么是现在：企业 RAG 的讨论已经从「怎么检索到」转向「怎么证明它检索得对、怎么管住它的写操作」。这个项目罕见的把「评测设施」和「审计日志」当成一等公民，而不是事后补。
• 为什么以前不容易：① 中文规程文档有天然难点——条款要能溯源（答错是安全事故）、换版频繁（废止条款还得能查）、代词密集（「该系统」「上述参数」单看一块判断不出在说什么）；② 通用 RAG 方案对这三件事基本不处理；③ 让 Agent 自己调写工具，企业最怕的就是「它擅自改了状态还查不出来」。
• 为什么值得花时间：这是一份把「企业知识库」当成严肃工程来做的一手实现，而不是又一个「上传文档就能问答」的 Demo。

03｜案例的前世今生

前世。2023–2024 年的企业知识库主流是「切块 → 向量化 → 余弦相似度召回 → 丢给模型」。它有一个被反复吐槽的天花板：检索不可解释（为什么召回了这一块？）、不可控（换了版本旧条款还在召回）、不可审计（谁改了什么不知道）。对规程类文档，这三条都是硬伤。

发展。三条技术线先后成熟：① 混合检索成为共识——稠密向量负责语义、稀疏向量负责关键词，中文术语与编号（如条款号）靠稀疏那一路才稳；② 重排器（cross-encoder reranker）把粗排结果精排，显著改善「召回对但排得差」；③ 上下文增强（Contextual Retrieval）在入库时给每块补一句「它在原文什么位置、讲的是哪件事」，专门救代词密集的段落；④ GraphRAG 补上多跳关系。

今生。agentic-kb 把上述零件装成一个可本地运行的整体，并额外做了三件企业关心的事：版本化索引（status / doc_version / effective_from 落在 payload 上）、可溯源问答（答案里的块引用可点开原文）、受控写工具（默认全关 + 三道闸 + 审计日志）。作者还自建了一套评测集来量化每个改动的收益，而不是靠「感觉变好了」。

下一步可能怎么发展（分析 / 推演）。这类「可溯源 + 可版本化 + 可审计」的知识库形态，很可能会成为企业合规与安全生产领域的基础设施；下一阶段的竞争点可能从「检索精度」转向「变更治理」——规程改版后如何自动标记影响范围、如何生成差异报告。以上为推演，非事实。

04｜原始资料

• 开源仓库beianchuqing111/agentic-kb（MIT，Python，创建 2026-10-07）
  https://github.com/beianchuqing111/agentic-kb
• 架构文档docs/architecture.md（设计取舍：为什么图的写入不用 LlamaIndex、ReAct 为什么走文本协议而非 function calling、为什么并发被限成 1）
  …/blob/main/docs/architecture.md
• 评测文档docs/evaluation.md（评测设施、指标口径、四条评测规矩）
  …/blob/main/docs/evaluation.md
• 踩坑文档docs/gotchas.md（作者原注：「改动前先读，失败方式几乎都是『不报错』」）
  …/blob/main/docs/gotchas.md
• 使用文档docs/usage.md（起服务、全部命令、.env 配置、排错表）
  …/blob/main/docs/usage.md
• 接口契约api/CONTRACT.md（HTTP 接口契约 + Gradio 与 React 两套界面的能力对照表）
  …/blob/main/api/CONTRACT.md
• 评测基线eval/baselines/（基线与逐题 diff，作者声明评测不调 LLM、不花钱）
  …/tree/main/eval

05｜作者是谁？

独立开发者 / 个人项目作者。GitHub 账号 beianchuqing111（账号创建于 2021-04，公开仓库 69 个，关注者 1）。账号未公开真实姓名、公司与所在地。

06｜解决了什么真实问题？

从需求侧开始。以电力行业规程为例（作者自己举的例子）：一线人员遇到「绝缘子出现裂纹怎么办」这类问题，需要查规程；但规程文档有三个天然麻烦：

• 条款要能溯源：答错就是安全事故。所以答案必须能点回原文块，而不是模型「大概记得」。
• 换版频繁：规程改版后，废止条款默认不该再被召回；但历史追溯时又需要能翻出来。
• 代词密集：「该系统」「上述参数」这类指代，单看一块判断不出说的是什么，检索自然容易错。

传统「向量检索 + 丢给模型」的方案对这三条基本无解。而企业真正要买的从来不是「能聊天」，是「可追溯、可解释、可控、可审计」。

07｜完整技术栈

模型（检索侧）	bge-m3（一次前向同时输出稠密与稀疏两路向量）+ bge-reranker-v2-m3（cross-encoder 重排）。两者均为 BAAI（智源）系列模型，本地推理
模型（生成侧）	任意 OpenAI 兼容端点：作者 README 明确列举 DeepSeek / Qwen / Kimi；用于问答与「上下文定位语」的入库生成
向量库	Qdrant（端口 6343 / 6344）—— 必需
图库	Neo4j（7474 / 7687）—— 仅 GraphRAG 后端需要
后端 / 接口	FastAPI（HTTP 接口契约见 api/CONTRACT.md）
前端	React（日常界面）+ Gradio（调试界面），能力逐控件对齐
Agent 形态	ReAct（Thought → Action → Observation），走文本协议而非 function calling（原因见 architecture.md）
联网搜索	Tavily（仅问答环节可选调用）
语言 / 环境	Python 3.10（作者用 anaconda py310）；Windows 批处理入口 kb.bat
部署	全本地。首次联网下模型后设 KB_HF_ONLINE=0 即可完全离线
许可	MIT（可商用，保留版权声明）

08｜完整 Workflow

入库侧（Ingest）

问答侧（ReAct）

09｜它到底是怎么实现的？

四个值得抄的工程决策：

决策一：混合检索用「一次前向」而不是两个模型。bge-m3 一次前向同时产出稠密与稀疏两路向量，服务端做 RRF 融合，再交 bge-reranker-v2-m3 重排。作者公开了自建评测集上「重排关 / 开」的差值（其余配置完全相同）：hit@1 0.867 → 1.000、MRR@1 0.867 → 1.000、nDCG@1 0.790 → 0.962、recall@1 0.678 → 0.811，其中 contextual 类题 0.500 → 1.000。

决策二：上下文定位语（Contextual Retrieval）单独量化。只在「入库时给每块补一句位置与主题」这一个变量上做对照（重排关）：hit@1 0.800 → 0.867。作者的解释很朴素——代词密集的段落靠定位语补全语义、靠重排救回来。这是「为什么要多花一次 LLM 调用」的直接证据。

决策三：版本过滤挂在两条召回路径的共同出口上。两条召回路径共用同一套分块，版本过滤同时挂在那两条上；而 mark_superseded 改的 status 字段，正是那道过滤读的那个字段。作者还处理了兼容性：加字段前入库的老数据按 current 处理，不报错也不漏。

决策四：写工具默认全关 + 三道闸 + 审计日志。export_report / mark_superseded 是仅有的两个写工具，需经「白名单 → 显式确认 → 参数校验」三道闸，且默认全部关闭；每次调用向 logs/audit.jsonl 追加 intent / result / denied 三条记录。这是把「Agent 能不能改知识库状态」这个责任问题用工程手段回答。

其他设计取舍（作者在 architecture.md 中说明）：图的写入不用 LlamaIndex；ReAct 走文本协议而不是 function calling；并发被限成 1。前两条本文不转述未核实的理由，第三条与「本地单机推理、避免显存争抢」的常见工程判断一致。

10｜手把手复现

Step 1（原文）。准备环境：Python 3.10；Qdrant 必须（端口 6343 / 6344）；Neo4j 仅在用 graphrag 后端时需要（7474 / 7687）。显存要求：bge-m3 约 2.3G、bge-reranker-v2-m3 约 2.3G，有 CUDA 走 GPU（作者实测 RTX 5080），没有也能跑只是慢。

Step 2（原文）。起服务（两个窗口别关）：scripts\start_qdrant.bat、scripts\start_neo4j.bat。

Step 3（原文）。体检：kb.bat health。作者说明——看到「✅ 全部就绪」或「⚠️ 后端可用，但 LLM 未配置」都算正常。

Step 4（原文）。导入你自己的文档：kb.bat ingest D:\你的文档目录（支持 .txt / .md / .pdf / .docx）。没有 LLM key 也能导入，只是每个块缺「定位语」，召回质量下降；填上 key 后重导即可补齐。

Step 5（原文）。不花钱先验检索质量：kb.bat search "你确定文档里有的短语"、kb.bat docs（只检索，不需要 LLM key）。

Step 6（原文）。开启问答：在 .env 里填 LLM_API_KEY（DeepSeek / Qwen / Kimi 任何 OpenAI 兼容端点均可），然后 kb.bat ask "绝缘子出现裂纹怎么办" -v。

Step 7（原文）。不想记命令就用 webui.bat，浏览器里点。全局开关 --backend {hybrid,graphrag} 与 -v 放在子命令前后都行。

Step 8（本文补充的建议）。第一次上线前，先只读一遍 docs/gotchas.md——作者自己在该文档里提醒「失败方式几乎都是『不报错』」，这句话意味着排查不能靠报错日志。

Step 9（本文补充的建议）。用自己的语料重跑一遍 eval/（作者说明评测脚本不调 LLM、不花钱），得到你所在行业的基线，再决定要不要开重排或换后端。

11｜Prompt / Code / Config

作者公开的内容（可直接引用）：

• 命令速查表：kb.bat health / ingest / search / ask / docs / stats，并标注每条命令是否需要 LLM key
• 关键环境变量与开关：LLM_API_KEY、INCLUDE_SUPERSEDED=1、KB_HF_ONLINE=0、KB_PYTHON（覆盖 kb.bat 里写死的 Python 路径）、--backend {hybrid,graphrag}
• 版本字段：status / doc_version / effective_from
• 写工具与闸门：export_report / mark_superseded，三道闸（白名单 → 显式确认 → 参数校验），审计落 logs/audit.jsonl（intent / result / denied）
• 评测口径：9 篇电力规程 / 61 个块 / 15 道可答题 + 5 道反例；阈值中性档（rerank_min_score=0、rerank_min_keep=0）；按题宏平均；每个数字带 n
• Mermaid 架构图（见 README「架构」一节）

作者未公开 / 本文未获取的：入库时生成「定位语」的具体提示词、ReAct 的系统提示词、评测题目的具体内容。本文不编造。

12｜踩坑

13｜中国用户能不能直接做？

国内访问	可以。项目在 GitHub；检索侧全部本地推理（bge-m3 / bge-reranker-v2-m3），不依赖任何境外 API；仅问答环节可选调用外部 LLM 与 Tavily 联网。
注册	无需注册。首次运行需联网下载模型权重。
API	问答需一个 OpenAI 兼容端点：作者 README 明确列举 DeepSeek / Qwen / Kimi，充值即用。检索与评测不需要 key。
成本	接近 0 元可验证：作者说明评测脚本不调 LLM、不花钱；search 与 ingest 也不需要 key。只有「问答」与「生成定位语」产生 token 成本。本地部署省去服务器费用（但要自己的机器 / 显存）。
技术门槛	🔴 开发者级 需要会配 Qdrant / Neo4j、装 Python 环境、装 bge 系列模型、看得懂 .env 与批处理入口。这不是「下载即用」的产品，是要动手部署的工程件。

14｜国产替代方案

这个案例本身就是国产方案——检索侧用的就是智源（BAAI）的 bge 系列模型，问答侧作者直接推荐 DeepSeek / Qwen / Kimi。

对照项	通用「上传文档就能问答」的 SaaS 知识库；以及 LangChain / LlamaIndex 的通用 RAG 拼装
本案例的差异	① 检索全本地（数据不出内网）；② 版本化索引与废止条款可查；③ 答案可点回原文块；④ 写操作默认全关 + 三道闸 + 审计日志；⑤ 带自建评测设施而不是「感觉变好了」。
说明	已验证（作者原文明示）：bge-m3 / bge-reranker-v2-m3 本地推理、DeepSeek / Qwen / Kimi 任意 OpenAI 兼容端点。本文推测（未验证）：把稀疏那一路换成 BM25 单独实现、或用其他中文 embedding 模型替代 bge-m3 的可行性。请勿把推测当结论。

15｜中国企业可以怎么用？

• 企业场景 1：安全生产 / 操作规程问答（案例本身场景）。电力、化工、矿山等行业的规程文档，一线人员需要「随口一问、答案能追溯到条款」。可溯源 + 版本化 + 审计这三条，恰好对上安全管理的硬要求。
• 企业场景 2：法规 / 合规知识库。法务与合规部门面对大量内外规、监管文件、行业标准。换版频繁、废止条款要能追溯，正好命中版本化索引的价值。
• 企业场景 3：SaaS / 硬件的售后与交付文档库。产品手册、配置说明、FAQ 版本迭代快，且必须能回答「这个型号 / 这个版本应该怎么做」。把 doc_version 与产品版本对齐即可。

16｜中国消费者可以怎么用？

这个案例的形态是本地部署的工程件，对纯消费者的直接适用性有限。但对个人有三条务实路径：

1. 考证 / 职业学习：把大量 PDF 教材、规范、标准建成自己的本地知识库，答案是带引用的（能点回原页），比「整本丢给聊天框」更适合需要背条文的场景。
2. 自由职业者的资料库：咨询、法律、工程类从业者手上往往有几百份历史文档，用版本化 + 可溯源的方式管理，交活时能直接给出出处。
3. 技术学习样本：这套代码是学习「企业级 RAG 到底要额外做哪些事」的极佳样本——尤其是评测设施与写工具治理这两块，是多数教程不会讲的。

17｜如何变成一个赚钱的项目？

产品化。把 agentic-kb 作为内核，做成「某行业规程知识库」的一体机 / 私有化部署包：预置该行业的文档处理规则（编号体系、条款层级、版本规则），客户导入自己的文档即可用。卖点不是「AI 问答」，是「可溯源 + 可审计」。

服务化。给企业做知识库的实施与调优：文档清洗、分块策略、评测集共建、检索参数调优。这类服务有一个天然优势——它需要行业知识，不是纯技术外包。

咨询化。帮企业做「知识资产治理」：哪些文档该入库、版本怎么管、废止条款怎么追溯、谁有权改状态。这是 IT 与业务部门之间的空白地带，也很少有人能做。

培训化。课程价值极高：它可以把「企业级 RAG 与 Demo 级 RAG 的差别」讲得非常具体——混合检索为什么必要、重排为什么值那一次调用、评测集为什么必须自建、写工具为什么要三道闸。学员带走的是判断力。

内容化。拆成系列：一次前向出双路向量是怎么做的 / 上下文定位语值不值一次 LLM 调用 / 版本化索引怎么设计 / Agent 的写工具该不该默认关闭。每一篇都是企业技术选型时会搜的问题。

行业化。把「行业文档规则包 + 评测集 + 检索参数基线」沉淀成行业资产，一个行业一套。行业越多，复利越明显——这也是这类项目最容易形成壁垒的地方。

18｜变现路径

这是分析，不是保证收益。项目本身暂无任何商业数据可引用。

19｜如果我是一个中国独立开发者（7 天 MVP）

假设：1 个人、有机器（最好有 GPU）、有基础 Python 能力、使用国产模型 API。

• Day 1：跑通官方快速开始：起 Qdrant → kb.bat health → 导入一小批文档 → kb.bat search。这一步不需要任何 API key。
• Day 2：填上 LLM key（DeepSeek / Qwen / Kimi），重导文档生成「定位语」，对比重导前后的召回差异。
• Day 3：换成你自己行业的 20–30 份真实文档，跑一次 eval/ 得到你的基线数字（这一步不花钱，但决定后面所有判断）。
• Day 4：做一次「重排关 / 开」的对照，看在你自己的语料上收益有多大——如果收益不明显，就把重排那 2.3G 显存省下来。
• Day 5：问 20 个真实业务问题，逐条检查引用能不能点回正确的原文块。这一步是这类项目最该花时间的地方。
• Day 6：设计写工具的护栏与审计：谁能触发、什么条件下允许、日志给谁看。先不打开写工具，只把设计写完。
• Day 7：复盘并决定方向：继续做通用（拼部署与调优），还是扎进某一个行业（拼行业规则包与评测集）。一个行业做透，比十个行业都浅尝更有价值。

20｜如何迁移到其他行业

21｜培训课程设计

22｜培训师点评

23｜最终判断

这是案例属性描述，不是「最佳案例排名」。技术完成度高、企业需求真实，但要真正落地需要本地环境与行业语料的双重投入。