知识工作插件knowledge-work-plugins这个项目是我在连续做了大半年调研型写作之后被逼出来的。每天要开几十个网页摘录十几段文字等真正坐到键盘前准备动笔却发现笔记散落在各种收藏夹、截图目录和聊天记录里标题不统一、出处缺失、内容被截断。那种感觉就像在一个没有标签的仓库里找一枚螺丝钉翻得越久越焦虑。这篇文章想把整套插件的设计思路和落地过程讲清楚。它不是一个单纯的小工具而是一套围绕采集—存储—处理—检索四个环节串起来的知识工作流水线。适合经常做资料整理、技术调研、内容创作或者正在搭建个人知识库但总觉得差一点顺手的人。无论你是想直接复用里面的思路还是打算照着代码自己改一套都能找到可以参考的东西。1. 先捋清楚知识工作插件到底解决什么问题1.1 知识工作者的真实困境先说说我自己的原始痛点。日常知识工作看似简单实际拆开就是四个高频动作看到一篇有价值的文章摘录一段关键观点给这个材料打上标签过几天能重新找到它。这四个动作听起来都不复杂可一旦叠加上海量的输入频率系统就会崩溃。我以前的做法非常朴素浏览器书签存网址截图工具存图片聊天软件里发给自己做稍后读文档软件里再粘一段文字。结果就是同一个主题的材料被拆成四五种格式、分布在五六个地方。等到写长文的时候为了找一句出处可能要把所有软件翻一遍时间成本高到吓人。这个问题的本质不是工具不够多而是采集动作和整理动作被人为切开了。采集的时候图快什么都不管整理的时候又嫌信息太碎干脆放弃。所以需要的不是又一个收藏工具而是一个能把采集成本压到最低、把整理流程自动化的插件体系。1.2 设计目标一秒钟采集零成本整理我给自己定了三条硬指标所有开发决策都围绕它们展开。第一条采集动作必须控制在一次点击以内。选中文字、点鼠标右键、完成整个过程超过三秒我就觉得它会变成负担。因此浏览器扩展的右键菜单是核心入口不做弹窗、不做二次确认。第二条存储格式必须对人友好。所有保存内容都落到本地的 Markdown 文件里不搞私有数据库。即使哪一天插件全部失效这些文件依然能用普通编辑器直接打开阅读数据永不绑架。第三条整理过程尽量自动化但保留人工确认的位置。自动生成摘要和标签再把结果放进待确认状态我只花晚上十分钟扫一遍。整理全自动会出错全手动会放弃折中才是可持续的。1.3 为什么选择轻量插件而不是重型软件有人会问市面上的笔记软件不都有收藏功能吗确实有但我个人踩过的坑是通用软件为了适配所有人群往往把流程固化死了。有的存下来是私有格式导出麻烦有的必须联网离线环境用不了还有的采集插件和知识库绑定太紧换工具等于换全家桶。插件化的好处在于它长在你现有的习惯上。浏览器还是那个浏览器文件夹还是那个文件夹只是在中间加了一层顺手的管道。想改保存位置就改配置想加字段就改脚本整个体系像一个可以自由拼装的工作台而不是一个封闭的箱子。这也是我最后决定自己写一套而不是掏钱买会员的原因。2. 系统架构与模块划分2.1 采集端一次右键搞定保存整个系统的起点是浏览器扩展。我用的是基于 Manifest V3 的扩展方案只申请contextMenus、activeTab、scripting三个权限尽量不触碰用户隐私。交互逻辑很简单在网页上选中一段文字点右键菜单里出现保存到知识库点击后扩展读取当前页面的标题、URL 和选中文本打包成 JSON 发给本地服务。页面没有选中文字的时候也可以直接保存整个页面但我更推荐选中文字再保存。强迫自己摘录最核心的一段比把整篇文章搬运回来更有价值。整篇搬运的后果通常是存完再也不看而摘录会迫使你至少在保存的一瞬间做了这个材料为什么值得留的判断。2.2 存储端Markdown 文件仓库本地服务收到数据后按照预设的目录结构写入 Markdown 文件。我的目录设计基本稳定成四块inbox/临时捕获区所有新保存的内容先到这里notes/完成整理的永久笔记references/外部参考资料的原始摘录assets/图片、附件等二进制文件选择文件做存储最直接的收益是可读、可迁移、可版本管理。我配合使用 Git 做快照备份每一次采集和修改都会产生一次提交相当于给知识库提供了时间旅行功能。之前用笔记软件时最怕删错内容现在完全不用担心回滚一个 commit 就恢复原状。每个文件头部都带一段 YAML 格式的元数据记录标题、来源链接、保存时间、标签、状态字段。这个设计非常关键后面做检索和处理都是靠在元数据上做文章。2.3 处理端从临时区到永久笔记的清洗流保存到inbox只是第一步真正产生价值的是后续处理环节。我写了一套批处理脚本定期扫描inbox下的文件做三件事。第一清理正文里的 HTML 残留标签和多余空行把摘录规整成干净的 Markdown第二调用本地部署的模型为每篇材料生成三到五句话的摘要再提取几个候选标签第三把处理结果写回文件的元数据并把文件移动到notes/目录状态改成 finished。这套流程不是完全无人值守的。脚本会把标注为 pending 的文件集中列出来我每天晚上花几分钟核对一遍。机器生成的摘要偶尔会跑偏但绝大多数时候能帮我省掉从头读一遍的时间。人机配合的好处是既不会被低质量自动整理淹没也不会因为懒得整理而积压一堆原文。2.4 检索端让沉淀的内容能被再次找到知识库的终极价值只有一个你需要的时候能把它找出来。为了做到这一点我在本地建了一个 SQLite 数据库用 FTS5 全文索引对标题、正文、标签做检索。之所以要单独做一层索引而不是直接靠文本编辑器里的搜索是因为数据量上来之后跨目录、跨标签、按状态筛选这些查询会变得非常频繁。FTS5 支持中文分词还差一点意思所以我的做法是保存时同时把原始正文和一个分词后的字段都写进索引搜索时两边一起匹配召回率高很多。搜索入口我做了两个。一是在命令行里敲一个kb search 关键词的快捷命令二是在编辑器的搜索面板里配置指向索引文件的连接。日常使用中绝大多数查询都是秒回比在文件夹里挨个翻快得多。3. 实操从零搭建这套插件系统3.1 环境选型与准备整套系统分三块浏览器扩展用 JavaScript 写本地服务用 Python 写检索层用 SQLite 承载。这个选型不追求技术上的极致而是图一个省心。Python 生态里处理文本、调用本地模型都太方便了一个脚本就能搞定清洗和摘要。浏览器扩展在 MV3 体系下只能用 JavaScript这是平台决定的。SQLite 不需要额外起服务单文件即可非常适合个人知识库这种小规模数据。开发之前先装好环境。我的建议是给本地服务单独建一个虚拟环境避免依赖污染系统 Python。目录结构我习惯这样放knowledge-work-plugins/ ├── extension/ # 浏览器扩展代码 │ ├── manifest.json │ └── background.js ├── server/ # 本地服务 │ ├── main.py │ └── requirements.txt ├── scripts/ # 批处理脚本 │ ├── clean_inbox.py │ └── build_index.py ├── knowledge/ # 知识库根目录 │ ├── inbox/ │ ├── notes/ │ ├── references/ │ └── assets/ └── knowledge.db # 检索索引3.2 浏览器端插件核心逻辑扩展部分代码量并不大核心就两个文件。manifest.json声明权限和后台服务background.js实现右键菜单和请求发送。{ manifest_version: 3, name: Knowledge Work Saver, version: 1.0.0, permissions: [contextMenus, activeTab, scripting], background: { service_worker: background.js } }background.js里我做了两件事安装扩展时创建右键菜单点击菜单时组装数据并发送到本地接口。chrome.runtime.onInstalled.addListener(() { chrome.contextMenus.create({ id: save-to-kb, title: 保存选中内容到知识库, contexts: [selection, page] }); }); chrome.contextMenus.onClicked.addListener(async (info, tab) { const payload { title: tab.title, url: tab.url, excerpt: info.selectionText || , savedAt: new Date().toISOString() }; await fetch(http://127.0.0.1:8765/save, { method: POST, headers: { Content-Type: application/json }, body: JSON.stringify(payload) }); });有个细节值得说发送请求前不需要弹窗提示成功或失败因为频繁的弹窗只会打断工作流。我在扩展的角标上短暂显示一下状态颜色绿色表示成功红色表示失败几秒后自动消失。这样既不影响节奏出了问题也能及时发现。3.3 本地服务接收数据并写入文件本地服务我用 FastAPI 起了一个极简接口只有POST /save一个路由。监听地址固定为127.0.0.1:8765不对外网开放保证只有本机浏览器能访问。from fastapi import FastAPI, Request from pathlib import Path import re from datetime import datetime app FastAPI() BASE_DIR Path.home() / knowledge INBOX BASE_DIR / inbox INBOX.mkdir(parentsTrue, exist_okTrue) app.post(/save) async def save(request: Request): data await request.json() title data.get(title, 未命名).strip() url data.get(url, ) excerpt data.get(excerpt, ) ts datetime.now().strftime(%Y%m%d%H%M%S) safe_title re.sub(r[\\/:*?\|], _, title)[:50] filename f{ts}-{safe_title}.md content ( ---\n ftitle: {title}\n fsource: {url}\n fsaved_at: {datetime.now().isoformat()}\n status: inbox\n tags: []\n ---\n\n f{excerpt}\n ) (INBOX / filename).write_text(content, encodingutf-8) return {ok: True, file: filename}文件命名用时间戳加标题前缀比如20250607123045-知识工作插件设计原则.md。这样做的好处是排序天然按时间重名概率低就算标题是中文也是可读的。写入文件后同一时刻用 Git 做一次自动提交这样每次采集都会留下一个可回溯的快照。3.4 处理与索引清洗、摘要、搜索一条线inbox里的文章积累到一定数量后运行scripts/clean_inbox.py做批量清洗。脚本的主要工作包括去掉正文里的 HTML 标签、合并连续空行、修正常见中文排版问题全角半角混用、多余空格然后调用本地模型生成摘要和候选标签。针对中文场景我会在标签生成前先做一轮分词再把高频实义词放到候选标签前列。比如一篇讲分布式事务的文章分词后常见词有事务、一致性、隔离级别、补偿这些就会被优先选为标签候选。人工确认的时候基本只需要勾选或者删减很少需要从零输入。清洗完成后的文件进入notes/目录同时触发索引更新。索引脚本是一个独立的小进程扫描所有 Markdown 文件把标题、正文、标签写入 SQLite 的 FTS5 表。为了中文搜索更友好写入时额外存一个分词版本检索时两边一起查匹配结果合并且去重。sqlite3 knowledge.db CREATE VIRTUAL TABLE notes_fts USING fts5(title, content, tags, tokenizeunicode61);插一句FTS5 默认分词对中文支持一般按字切分会导致很多无效匹配。我的临时方案是保存分词后的字段再建一个附加索引实测下来英文和中文混合检索的准确率都在可接受范围内。如果你有精力也可以换成专门的中文分词插件的 SQLite 编译版但个人场景下我这个方案够用。4. 常见问题与排查技巧实录4.1 本地服务收不到请求先查三件事插件保存不上最常见的原因有三个。第一本地服务进程挂了或者终端窗口被关了此时访问http://127.0.0.1:8765没有任何响应第二浏览器扩展没有重新加载改了background.js之后忘记在扩展管理页点刷新第三CORS 问题浏览器阻止页面脚本跨源请求本地地址。排查顺序我建议固定下来先看本地服务日志能不能打印请求再开浏览器开发者工具的 Console 看有没有报错最后确认扩展图标是不是灰色状态。80% 的问题出在前两步只是很多人一上来就怀疑代码逻辑写错了反而绕远路。另外如果系统启用了代理或者防火墙也可能拦掉对127.0.0.1的后台请求。遇到这类情况把本地地址加入白名单就好。这个问题不太常见但我确实踩过一次排查了半小时才发现是代理配置拦截了 localhost。4.2 中文标题乱码的根源用时间戳加标题做文件名后偶尔会遇到保存出来的文件标题乱码比如æç¥è¯鏂囩珷鏍囬。根源基本都是编码传递链路出了问题最常见的是 URL 编码被重复转义或者本地服务读取时没有按 UTF-8 解码。排查时从扩展侧开始在发请求前打印一下tab.title确认中文字符是否正常再在服务端把收到的title原样打印看到底是哪一步变了样。通常找到一次重复encodeURIComponent就能定位。我的经验是两个环节都显式声明 UTF-8比依赖默认编码要稳得多。4.3 同一篇文章被保存了多份知识工作做到一定量后重复采集是最容易忽视的坑。同一篇技术文档可能今天存了一段引言明天又存了后面的操作步骤文件名不同正文却高度重叠检索时一条关键信息出来三四个结果。我处理这件事分两层。第一层是采集时的去重提示本地服务根据 URL 的哈希值检查是否已经存在同源记录如果存在就把新文件命名加上-dup后缀并在返回结果里提醒。第二层是每周一次的相似度扫描用编辑距离算法对比标题近似的内容列出可疑重复项由我手动合并。自动合并太危险容易删错文件宁可多花一分钟也不要不可恢复的损失。4.4 保存后全文搜索不到刚写入的内容有时候明明保存成功了命令搜索却找不到刚存入的文章。第一次遇到这问题我很困惑后来发现是处理管线的时序问题新保存的内容落在inbox而索引脚本默认只扫描notes目录结果当然是搜不到。解决方式很简单索引构建时把inbox也纳入不过要给inbox里的文件标注外部的未处理状态让它能搜到但不参与正式统计。另一个隐蔽原因是 SQLite 的 FTS 表没有及时重建文章被移动或改名后索引还停留在旧路径定期做一次全量rebuild就能解决。5. 后续可以扩展的方向用了近一年后这套插件的形态基本稳定了但我一直记着几个待办方向。第一个是移动端入口比如在手机上看到一篇好文章直接分享到知识库的接口现在还需要通过转发到电脑再手动保存体验还是差一截。第二个是多端同步目前知识库只放本机打算后续把存储目录换到同步网盘上配合 Git 冲突处理脚本实现多设备无缝流转。第三个是团队协作把当前的单人模式扩展成多人订阅模式每个人都能往里投递材料再按主题分拣。这些方向没有一个是为了堆功能都是顺着更高频、更省事、更可靠这三个目标延展出来的。工具的价值不在多而在顺手。只要继续保持采集一步到位、整理自动辅助、检索秒级反馈这套知识工作插件就能长期为我服务下去。最后再分享一个我坚持了很久的体会不要为了整套方案完整而把一开始不需要的模块都写上。我最早写的版本里塞了一个复杂的数据看板结果半年过去了我一次都没打开过类似页面。真正留下来的是那几个最朴素的能力——右键保存、自动摘要、快速检索。知识管理的产品化很容易做重难的是做轻。先把采集整理检索这条主干跑通再慢慢生长分支这个顺序不要搞反。