企业官网建设流程全解析

很多长期记笔记的人，心里都压着一个不太好意思说出口的尴尬：自己沉淀的东西越来越多，真正能调用的却越来越少。我也经历过这个阶段，从浏览器剪藏、公众号收藏、文档草稿和随手记里攒下了一两千条零散内容，真到要用的时候，要么找不到，要么不敢用，因为完全想不起当初为什么把它存下来。项目“knowledge-work-plugins”就是在这种“存废危机”里诞生的。它不是一个武林大会式的大系统，而是一组互相独立、又能通过统一数据和命令行入口串起来的小插件，专门处理知识工作里最耗精力的采集、清洗、去重、关联、定期回顾这一整条链路。如果你也有“存了等于没学”的困扰，或者在维护自己的第二大脑，这篇项目笔记应该能帮你少踩几个我踩过的坑。

1. 为什么偏偏做成一组插件，而不是一个“知识管理大平台”

1.1 知识工作的真正瓶颈不在“存不下来”，而在“找不回来”

我观察过很多知识密集型岗位的工作流，也复盘过自己的。大部分人并不缺采集工具：笔记软件自带剪藏、浏览器有扩展、云盘里有文档、聊天工具里还躺着几十段语音备忘。真正的问题出在信息进入个人库之后，没有一套稳定、可介入的处理流程。原始信息是“存下来了”，但它和已有内容重复、格式混乱、没有拆解成可复用的单元，也没有和旧笔记建立任何关联。

这就是知识工作和一般信息管理的区别：普通资料管理追求“放入一个文件柜”，知识工作追求“让旧知识不断滋养新场景”。一旦处理流程缺失，库越大，噪声越多，人被淹没在里面找不到要领。“knowledge-work-plugins”想解决的正是这个：把“采集一清理一拆卡一关联一回顾”切成一个个能用命令行跑起来的小插件，每个插件只干一件事，但组合起来，就是一条完整流水线。

1.2 独立插件带来的三种实际收益

一开始我也动过念头，要不要写一个大应用，把所有功能收进同一个界面。后来发现，那样反而会把问题搞复杂。拆分插件的好处，在实践中越用越明显。

• 替换成本低。采集插件如果写得不顺手，我只需要重写一个模块，其他插件完全不受影响。大应用里改一处功能往往要重新回归整条链路，改起来束手束脚。
• 调试路径短。每个插件可以单独跑、单独测试。比如只测去重程序，不需要把采集和导出都搭起来；中途出错的日志也短，一眼能定位到是这个模块自己的问题，还是上游数据的问题。
• 复用能力强。有些插件不绑定我这套业务：去重逻辑拿去处理任何一堆相似文本都成立，卡片工具换个字段定义也能服务于别的场景。插件越“笨”，在不同项目里越通用，这是我在重构中才慢慢体会到的。

1.3 这个项目刻意不去做什么

给一个项目划定“不做什么”，和确定“要做什么”同样重要。在迭代过程中，我给自己定了几条边界：

第一，不做完整的前端界面。我知道界面能降低使用门槛，但初期它的维护成本太高。我优先保证命令行工作流的完整和稳定，等核心链路验证靠谱了再考虑可视化。

第二，不做移动端和实时推送。知识处理的现场绝大多数在电脑端，我宁可把通知做成每天固定时间生成回顾清单，也不去搞一个“点一下弹一条”的即时提醒机制，以避免打断正在做的深度工作。

第三，不做完全自动化的“智能总结”。自动生成摘要看起来很美好，但质量一塌糊涂时反而会污染判断。我的做法是，让程序负责繁重的清洗、去重、聚合，最后一步的“是不是密切相关”“要不要保留”永远保留人工决定权。

边界划清楚之后，维护难度下降了不止一个量级。用户和插件之间的关系也变简单了：插件的可靠性，比它的“聪明”更重要。

2. 插件仓库的结构：核心模块怎么拆的

2.1 一眼看懂项目布局

因为所有插件都在一个仓库里管理，目录结构必须非常规矩。我采用的是一种“按功能分层、按用途分模块”的组织方式：

knowledge-work-plugins/ ├── pyproject.toml ├── cli.py ├── core/ │ ├── __init__.py │ ├── item.py # 统一数据模型 │ └── store.py # 状态存取：文件 + SQLite ├── collectors/ │ ├── clip_cleaner.py # 剪藏内容清洗 │ ├── url_filter.py # 链接参数清理 │ └── import_files.py # 从本地文档导入 ├── processors/ │ ├── dedup.py # 指纹去重 │ ├── cardify.py # 长文拆卡片、抽提炼 │ └── linker.py # 标签与关键词关联 └── exporters/ ├── weekly_digest.py # 周回顾生成 └── markdown_writer.py

一眼看上去有点零碎，其实每块都是顺着知识工作流排的：collectors 负责入口，processors 负责加工，exporters 负责出口。可以把前半段想成“进水口到沉淀池”，后半段则是“用的时候从沉淀池里打水”。

2.2 数据模型先行：所有插件都围绕同一个 Item 结构

插件之间最容易出的问题，就是各说各话——采集插件输出一种字段，去重插件又要求另一种字段，最后要做字段映射，活活把自己累死。我在项目开始时就规定了统一数据模型Item，所有插件都围绕它转，谁也不能自己另搞一套。

# core/item.py from dataclasses import dataclass, field from datetime import datetime @dataclass class Item: item_id: str # 唯一ID，一般用来源URL+内容哈希生成 source_url: str = "" title: str = "" content: str = "" # 清洗后的正文 raw_text: str = "" # 清洗前的原始文本，便于排查 summary: str = "" tags: list[str] = field(default_factory=list) created_at: datetime = field(default_factory=datetime.now) updated_at: datetime = field(default_factory=datetime.now) meta: dict[str, str] = field(default_factory=dict)

这样设计的直接好处是，开发第三个插件的时候，只需要查阅Item定义，不需要翻前面所有插件的内部实现。数据模型像一份所有插件都能读的“合同”，后面每次迭代都在这个合同之上进行，接口争端几乎绝迹。

2.3 一个统一入口带来的指挥便利

虽然模块很多，用户最终只面对一个命令入口。pyproject 里把cli.py注册为控制台命令：

[project.scripts] kw = "cli:main"

于是日常使用变成：

kw clean ./dropped --out ./inbox # 清洗剪藏内容 kw dedup ./inbox # 对收件箱去重 kw cards ./inbox --min-len 300 # 拆分卡片笔记 kw digest --week 2024-W42 # 生成本周回顾

统一入口的意义不在于少敲几个字母，而在于所有插件的行为规则是一致的：同样风格的参数、同样规范的输出目录、同样的日志格式。用起来的时候，不需要为每个小工具重新背一套命令。这也是插件多了之后还能保持清爽的关键。

3. 三个核心插件的实操细节和取舍逻辑

3.1 clip_cleaner：把剪藏代码块变成可用的干净正文

浏览器剪藏下载下来的东西，常常带着大量网页导航、广告、推荐位和追踪参数。我最早是用现成解析库去处理，但发现网页结构一变，解析规则就失效。后来换了一种思路：先用内置的 HTML 转换器提取出正文候选区，再做关键规则清理。

# collectors/clip_cleaner.py (关键片段) import re from html.parser import HTMLParser class TextExtractor(HTMLParser): def __init__(self): super().__init__() self.parts = [] self.skip = False def handle_starttag(self, tag, attrs): if tag in {"script", "style", "noscript", "nav", "footer"}: self.skip = True if tag in {"p", "h1", "h2", "h3", "li", "blockquote", "pre"} or tag == "br": self.parts.append("\n") def handle_endtag(self, tag): if tag in {"script", "style", "noscript", "nav", "footer"}: self.skip = False def handle_data(self, data): if not self.skip and data.strip(): self.parts.append(data.strip()) def clean_html(raw_html: str) -> str: parser = TextExtractor() parser.feed(raw_html) text = "".join(parser.parts) text = re.sub(r"\n{3,}", "\n\n", text) return text.strip()

这里有两个细节，我觉得比代码本身更重要。

第一，不要试图“完全恢复”网页正文，那是网页正文抽取研究领域的事，个人工具做到“去掉明显广告和导航后内容完整可读”就够了。追求完美解析，很容易花几天时间处理三个极端样例，投入产出不成比例。

第二，清洗结果一定保留原始文本。Item.raw_text字段就是干这个的。后来我遇到一次“清洗后内容明显少了一段”的问题，靠对比raw_text和content才定位到是网页里某个图片注释块被错误跳过了。如果当初图省事不保留原始内容，排错难度会大很多。

3.2 dedup：用内容指纹和近似相似度拦住重复信息

去重是这个项目里最值得花时间的地方。拿哈希值直接比对“完全相同内容”其实很简单，难的是那类“标题变了、正文基本相同”的重复，以及“被分享过两次，中间被改过两句话”的近似重复。只做精确匹配，库里还是会堆一批味同嚼蜡的冗余。

我采用的方案，是对正文做字符级 n-gram 切分，算 Jaccard 相似度。这个方案不依赖现成的大模型向量库，纯本地跑，速度也快。

# processors/dedup.py (核心逻辑) def shingles(text: str, n: int = 8) -> set[str]: text = "".join(text.split()) if len(text) <= n: return {text} return {text[i:i+n] for i in range(len(text) - n + 1)} def jaccard(a: set[str], b: set[str]) -> float: union = a | b if not union: return 0.0 return len(a & b) / len(union) def find_duplicates(items: list[Item], threshold: float = 0.78) -> list[tuple[str, str, float]]: results = [] for i in range(len(items)): for j in range(i + 1, len(items)): score = jaccard( shingles(items[i].content), shingles(items[j].content), ) if score >= threshold: results.append((items[i].item_id, items[j].item_id, score)) return results

这里我踩过的一个典型坑是阈值设置。最开始我调得很高，0.95，觉得这样最稳妥，结果几乎拦不住任何重复。后来拿一批真实重复样本去试，发现正常重复的相似度普遍集中在 0.76 到 0.92 之间，0.78 到 0.82 是比较合适的档位。

另外，这版逻辑是双重循环，条目上了万之后会很慢。我后来加了个预筛：先按标题关键词首字做粗分组，只有同组内的文章再去算 n-gram，速度直接从“跑不动”到了“秒回”。预处理的思想在知识工具里几乎处处受用。

3.3 cardify：把长文拆成可独立复用的卡片

长文进库之后的下一步，是拆解。爱记笔记的人都有体会，一篇文章 3000 字，存下来是一坨；拆成 6 张带出处的卡片，就是能反复调用的知识积木。cardify 做的事，就是把长文本按语义段落切成卡片，并自动给每张卡片补上“来源引用”。

# processors/cardify.py (关键片段) def split_cards(content: str, min_len: int = 150): blocks = content.split("\n\n") cards, current = [], [] cur_len = 0 for block in blocks: current.append(block) cur_len += len(block) if cur_len >= min_len or block.startswith("## ") or block.startswith("### "): cards.append("\n\n".join(current).strip()) current = [] cur_len = 0 if current: cards.append("\n\n".join(current).strip()) return cards

这版逻辑看着不复杂，但实际调整中有两个认知帮助了我。第一，语义边界不应该只靠长度触发，Markdown 的标题结构是非常好的天然边界；第二，卡片不是越小越好。太碎会让卡片失去上下文，太大会让后续关联变得困难。我自己把 150 字到 500 字作为默认区间，追求“一卡一意”，而不是“一卡一段”。

拆分之后，每张卡片都会带着原始文章 item_id 和标题，做一个引用注脚。这样任何后续的回顾、主题整理都不会丢掉出处，时间再久也能回溯到源头。

3.4 weekly_digest：让沉淀产生可感知的产出

如果知识库只有输入没有输出，很快会变成一个心理负担。weekly_digest 是我重新整理这堆插件时的“出口”插件，它能汇总一周内新增和修改的卡片，按主题聚合成一份 Markdown 周报。里面的核心逻辑很简单：从 SQLite 里查出符合时间范围的记录，按tags里的首要主题分组，再按卡片之间的引用关系把相关条目放一起。

kw digest --week 2024-W42 --to ./reviews/2024-W42.md

生成的文件长这样：

# 2024-W42 知识回顾 ## 主题：插件开发模式 - [卡片A] 小插件比大应用更适合个人工具链迭代（来源: 20241015-001.md） - [卡片B] 数据模型统一能显著降低插件间摩擦（来源: 20241016-014.md） ## 主题：去重算法 - [卡片C] Jaccard 阈值在 0.78-0.82 之间最合适（来源: 20241017-008.md）

我把自己对这个插件的定位跟其他人讲过：它不产出“精彩文章”，它只负责“让回顾这件事变得可能”。知识的复利体现在一次次回顾时的重新组合，而不是收藏那一瞬间的快感。

4. 插件怎么串成一条端到端的知识工作流水线

4.1 流水线的三个相：采集、加工、出口

单看某个插件，都只是“好用的命令行工具”；真正有价值的是把它们串起来跑。我的实践是把它拆成三个相。

第一个相是“采集”。从浏览器剪藏、本地文档导入、RSS 订阅转存等入口，把内容统一放进一个叫inbox的目录。这个目录相当于物理世界的收件箱，只容纳原始材料，不承担“可读好读”的责任。

第二个相是“加工”。kw dedup先清理重复，再kw cards拆卡片，接着kw link根据已有标签和文件名做关联绑定。加工完的内容会进入notes目录，并同步写入 SQLite 供检索。

第三个相是“出口”。到了固定时间，kw digest从笔记目录拉取本周变更，生成回顾；碰到具体写作任务，也可以直接按标签导出相关卡片，组成初稿素材。

三个相的顺序几乎是固定的。把顺序颠倒过来，比如先拆卡片再去重，会白白算出一大堆重复卡片的指纹，浪费时间和存储。知识流水线和工厂流水线一个道理：顺序、缓冲、质检都得提前想清楚。

4.2 用一条命令跑完整个流程的调度设计

为了不让自己每天要敲十几遍命令，我在入口脚本里加了一个流式命令：

kw flow --from inbox --to notes --week 2024-W42

内部做的事情，其实只是把前面几个插件按顺序调用，并维护一个简单状态机：

clean -> filter -> dedup -> cardify -> link -> digest

这里最重要的一个细节是“边界可中断”。我不会让 flow 命令在某个中间环节死了就直接终止，而是让每个插件输出自己的中间产物到work/目录。比如clean的结果存成work/01-cleaned/*.md，dedup的结果存成work/02-deduped/*.md。这样即使第 4 步挂了，前 3 步的结果还在，不用从头再来。

这种设计多花了一点磁盘，换来的是排错和重跑时的大量时间节省。个人知识工具不需要事务性强的数据库事务，但可以用“流水线断点续传”的思路换取可靠性。

4.3 定时任务与人工检视：自动化到什么程度才算合适

很多人一听“自动化”就恨不得全自动。我试过把整条流水线挂在每天凌晨自动跑一遍，后来发现会有两个问题：一是剪藏内容里总有些需要人工判断的无效信息，全自动会把垃圾内容也拆成卡片；二是自动生成的回顾如果没人看，一周后就成了新的“沉默文档”，反而增加干扰。

现在的节奏是：采集全自动，每天定时把新内容拉进收件箱；加工半自动，我每天只跑一次kw flow，过程中遇到相似度不高不低的内容弹出提示，我来决定归并还是分开；回顾定时化，每周一上午固定生成上周 digest，之后花 15 分钟快速扫一遍。

“人工检视”不是偷懒，恰恰是知识工作最不能被替代的部分。计算机负责把 1000 条信息压成 20 个候选判断，人负责在 20 个候选里选哪几个留下。这样一来自动化程度适中，又不需要忍受全自动带来的垃圾输出。

5. 维护这类知识工具时，我踩过的高频坑和排查链路

5.1 剪藏内容的“标签污染”和正文识别失真

第一个常见坑，是网页里的正文被正文之外的内容污染。比如有些文章页面会在结尾堆一大片“相关推荐”，我的正文提取器很容易把这部分当作正常段落。刚开始我没意识到问题，等到发现卡片库里混了好几篇“文不对题”的卡片，才回去翻原始文本。

排查链路是：先打开raw_text看原文，确认来源页面确实包含这些推荐位内容；然后看TextExtractor的跳过程序，发现它只跳过了nav、footer这类有固定语义的标签，对“推荐内容”这种无规范标签的区块根本没有规则。

最后的修法是在clip_cleaner里加一个基于位置的黑名单逻辑：正文候选区之后出现的、与标题相关性低于某个阈值的段落，一律丢弃。某种程度上，靠位置信息比靠标签更可靠，因为网页结构再怎么变化，“正文在前、推荐在后”的大体顺序通常不变。

5.2 插件间的接口对象被重复解析，导致状态漂移

第二个坑更隐蔽，也更值得记录。某天我发现流水线重复跑了一遍之后，有些卡片的updated_at一直在跳动，每次生成 digest 都会把它们算成“本周修改”。

定位时我先查看状态存储，发现同一批item_id出现在了两条处理记录里。后来才知道，是cardify插件在每次运行时，不管内容有没有变化，都会重新生成一个新的卡片文件，而link插件又来者不拒，把新旧同名文件都识别为“新增”。

这个问题的本质是幂等性不足。管线上游重复输出，下游又没有能力识别“这些内容我原来已经见过”。修法分两步：第一步，给每个卡片文件生成内容哈希，文件名里带上哈希前缀，内容没变时文件不重写；第二步，在link插件里加上“同一来源+相同内容指纹的卡片只建立一次关联”的校验。

个人工具的稳定性，其实就体现在这些幂等细节上。一次处理做成“可重入”的，后面省心非常多。

5.3 升级一个依赖，结果整条链路一起崩

还有一次，我把一个解析库从旧版本升到新版本，想着反正都是解析 HTML，升级一下不会有问题。结果第二天跑流水线，clip_cleaner报错，cardify也因为拿到了异常的空正文而连续报错，整个 flow 在我没看日志的情况下静默攒了两天故障。

排查日志时发现，根本不是解析库本身坏了，而是新版本改变了某个默认参数。解析出来的文本里多了一些我不期望保留的标签内容，导致后面去重和拆卡片的输入和以前完全不一样。

从那以后，我立了三条规矩：第一，插件仓库和外部依赖的版本锁都要固定，必须记录在 pyproject 的依赖里；第二，升级依赖后，先只跑kw clean --fixture ./testdata单独冒烟测试，不要直接对整个流水线做升级；第三，每个插件的__main__里都带一套自测样例，确保未来任何环境变化都能靠这些样例快速回归。

5.4 别指望一步到位：工具链是长出来的

最后一条，是我在这个项目里体会最深的经验。我最初试图把所有功能设计得“完美”，结果一个月都没交付能用的版本。后来改成“先让采集、去重、卡片这三件事能跑，其他功能长出来再说”，反而很快进入了正向循环。

插件工具链的演进方式和做菜很像：不可能第一次就做出一桌宴席，先把一道拿手菜做到稳定，再试着添第二道、第三道。每加一个插件，都想想它和旧插件之间有没有真正补上缺口；如果只是“多一个功能”，宁可先不做。

我在实际使用中还发现一个挺有用的习惯：每次给某个插件加新功能时，都顺手在文档头部写下“这个功能为什么存在”。过了几个月再回来看，有些功能你已经不确定为什么加了，这种场景出现时，往往就是它该被删除的时候。keeping文档和代码同步更新，比写一大堆设计说明更实用。

如果你也准备维护一套知识工作插件，我的建议很简单：想清楚你要处理的最痛的那一个环节，用最小代码量做出来，跑顺手之后再考虑扩成流水线。一上来就搭大框架的人，大部分时间都花在了装饰大厅上，而厨房还是空的。工具链是慢慢长出来的，让这组插件陪你一起进化，远比一步到位更可靠。