Apollo-11：模块化个人知识管理与自动化工作流实战

1. 从代号到工程奇迹：Apollo-11 项目的整体设计逻辑

第一次看到“Apollo-11”这个代号，很多人脑子里蹦出来的可能是那个著名的登月任务。但在我这里，它指的是一套我用了快两年的个人知识管理与自动化工作流系统。名字借用了那个传奇项目的代号，图个吉利，也图个“把复杂目标拆解成可执行步骤”的精神内核。这套系统解决的核心问题很具体：信息碎片化导致的重复劳动、跨设备协作时的版本混乱、以及灵感闪现时找不到合适工具记录的尴尬。它适合那些每天要处理大量文本、代码片段、网页摘录和临时想法的人，不管你是写代码的、做研究的还是搞内容创作的，只要你觉得“东西太多、脑子不够用”，这套思路就能直接抄作业。

为什么叫 Apollo-11 而不是别的？因为整个系统的设计哲学就三条：模块化、可替换、失败隔离。就像当年那艘飞船，指令舱、服务舱、登月舱各司其职，坏了一个不影响其他部分继续工作。我的系统里，采集层、处理层、存储层、输出层完全解耦。采集层负责把网页、PDF、微信读书笔记、随手写的便签统一抓下来；处理层做清洗、打标签、提取关键信息；存储层用纯文本加 Git 做版本控制；输出层按需生成周报、项目文档或直接推送到写作工具里。任何一层出问题，我只需要换掉那一层，其他部分照常运转。

这套思路最大的优势是避免被单一工具绑架。我见过太多人把全部笔记塞进某个闭源软件，结果软件一涨价或者一停服，几年的积累瞬间归零。Apollo-11 的存储层坚持用 Markdown 文件加 Git 仓库，所有数据都是纯文本，任何编辑器都能打开，任何 Git 平台都能托管。处理层我用 Python 脚本加少量 shell 命令，不依赖任何在线服务。采集层稍微复杂点，因为要对接不同来源，但每个采集器都是独立的小脚本，坏了就修那一个，不影响全局。

注意：不要一上来就追求全自动化。我最初试图把所有环节都写成定时任务，结果调试成本极高，一个环节报错整个流水线卡死。后来改成“半自动加手动触发”，反而效率更高。先跑通单点，再串联。

另一个关键设计是失败隔离。每个采集器、每个处理脚本都独立运行，输出到独立的临时目录。只有经过验证的数据才会被合并到主仓库。这样即使某个采集器抓回来一堆乱码，也不会污染已有的干净数据。这个思路借鉴了分布式系统的“舱壁模式”——把系统分成多个独立的隔间，一个隔间进水不会导致整艘船沉没。实际操作中，我给每个采集器配了独立的日志文件和错误重试机制，连续失败三次就自动暂停并给我发通知，而不是无限重试把资源耗光。

2. 核心细节拆解：采集、清洗、存储、输出的关键参数

2.1 采集层：多源输入的标准化处理

采集层要解决的核心问题是格式统一。网页文章、PDF 文档、电子书摘录、语音转文字、手动输入的便签，这五种来源的数据结构完全不同。我的做法是定义一个中间格式，我称之为“原子笔记”。每条原子笔记包含以下字段：

网页采集我用的是 Python 的 readability 库加 requests，先把网页正文提取出来，再转成 Markdown。这里有个坑：很多网站的反爬机制会检测请求头，我试过直接裸 requests 请求，十次有八次被拒。后来加了 User-Agent 轮换和请求间隔随机化，成功率才稳定在九成以上。PDF 采集用 pdfplumber，比 PyPDF2 准确率高不少，尤其是表格和分栏排版。电子书摘录我一般直接从阅读软件导出 Markdown，再用脚本做格式清洗。语音转文字用本地部署的 whisper 模型，虽然速度慢点，但隐私有保障，而且不用联网。

实操心得：采集器一定要加超时和重试。我最初没设超时，某个网站响应慢的时候整个脚本卡死半小时。后来统一设了 15 秒超时，失败后等 5 秒重试，最多重试两次。这个参数组合在我这里跑了半年多，基本没再出现过卡死。

2.2 清洗层：从脏数据到可用笔记

清洗层的任务是把采集来的原始内容变成结构化的原子笔记。核心操作包括：去除广告和导航栏、统一标点符号、拆分超长段落、提取关键信息生成标签。去除广告我用的是基于 CSS 选择器的规则库，针对常见网站写了一套规则，匹配到就直接删掉对应 DOM 节点。标点统一主要是把全角半角混用的情况处理掉，尤其是中英文混排的时候，逗号和句号经常乱。拆分超长段落是为了后续检索方便，我设的阈值是单段不超过 500 字，超过就按句号拆分。

标签生成这块我试过两种方案。一种是基于 TF-IDF 的关键词提取，速度快但准确率一般，经常把“的”“了”这种词也提出来。另一种是用本地部署的小型语言模型做关键词抽取，准确率高不少，但需要额外跑一个模型服务。最后我选了折中方案：先用 TF-IDF 粗筛，再用规则过滤掉停用词和单字词，最后人工确认一遍。虽然多了一步手动操作，但标签质量明显提升，后续检索的时候省心很多。

# 标签生成的核心逻辑示例 import jieba.analyse def generate_tags(text, top_k=5): # 提取关键词 keywords = jieba.analyse.extract_tags(text, topK=top_k*2) # 过滤停用词和单字 stopwords = set(['的', '了', '在', '是', '我', '有', '和', '就']) filtered = [kw for kw in keywords if kw not in stopwords and len(kw) > 1] return filtered[:top_k]

2.3 存储层：Git 仓库加纯文本的组织方式

存储层我用的是一个 Git 仓库加按日期分目录的结构。仓库根目录下按年份建文件夹，年份下按月份建子文件夹，每个月下面再按天建文件夹。每天的文件夹里放当天的所有原子笔记，每条笔记一个 Markdown 文件，文件名就是笔记的 id。这种结构的好处是检索快、备份简单、迁移方便。我想找某天的笔记，直接进对应目录就行。想备份，整个仓库打包或者推到远程仓库都行。想迁移到别的工具，纯文本加 Markdown 格式，几乎没有迁移成本。

Git 的提交策略我也摸索了一段时间。最初是每采集一条就提交一次，结果提交历史乱七八糟，一天几百条提交。后来改成每小时批量提交一次，提交信息自动生成，格式是“采集 YYYY-MM-DD HH:00 共 N 条”。这样提交历史清晰，回溯也方便。分支策略很简单，主分支只存经过清洗的笔记，采集的原始数据放在一个叫 raw 的分支上，清洗完成后再合并到主分支。这样即使清洗脚本出错，原始数据还在，可以重新跑。

注意：Git 仓库不要放太大的二进制文件。我最初把 PDF 原件也塞进仓库，结果仓库体积半年涨到 2GB，克隆一次要等好几分钟。后来改成 PDF 只存提取后的文本，原件放在单独的归档目录，用硬链接引用。仓库体积立刻降到了 200MB 以内。

2.4 输出层：按需生成不同格式的交付物

输出层是这套系统最终产生价值的地方。我常用的输出格式有三种：周报、项目文档、写作素材包。周报是每周日自动生成的，汇总本周新增的笔记，按标签分类，附上统计信息如总条数、各标签占比、来源分布。项目文档是针对特定项目生成的，把该项目相关的所有笔记按时间线排列，加上手动补充的说明。写作素材包是给内容创作准备的，把相关笔记按主题聚类，每条笔记附上原文链接和关键摘录。

输出层的实现用的是 Python 的 Jinja2 模板引擎。我写了几套模板，对应不同的输出格式。生成的时候只需要指定时间范围和标签过滤条件，脚本自动从 Git 仓库里拉取对应笔记，渲染模板，输出 Markdown 或 HTML 文件。整个过程不到十秒，比手动整理快了几个数量级。

3. 实操过程：从零搭建 Apollo-11 的完整步骤

3.1 环境准备与依赖安装

搭建这套系统的第一步是准备环境。我用的是一台常年开机的迷你主机，装了 Ubuntu 系统，主要考虑是功耗低、噪音小、可以一直跑后台任务。如果你没有独立主机，用树莓派或者旧笔记本也行，甚至可以在主力电脑上跑，只是需要的时候才启动。系统装好后，先装基础依赖：

# 更新系统包 sudo apt update && sudo apt upgrade -y # 安装 Python 和 pip sudo apt install python3 python3-pip git -y # 安装核心 Python 库 pip3 install requests readability-lxml pdfplumber jieba jinja2 markdown

这里有个细节：Python 版本建议用 3.9 以上，因为有些库在新版本上性能更好。我试过在 3.6 上跑，jieba 分词速度明显慢一截。另外，如果要用 whisper 做语音转文字，还需要装 ffmpeg 和 torch，这两个包比较大，装的时候耐心点。

3.2 目录结构初始化与 Git 仓库配置

环境准备好之后，建目录结构和初始化 Git 仓库。我习惯把整个系统放在~/apollo11目录下，里面再分几个子目录：

mkdir -p ~/apollo11/{collectors,processors,storage,outputs,logs} cd ~/apollo11/storage git init git config user.name "Apollo11" git config user.email "apollo11@local"

collectors放采集脚本，processors放清洗脚本，storage是 Git 仓库，outputs放生成的周报和文档，logs放日志文件。这个结构我用了很久，清晰且不容易乱。Git 仓库初始化后，先建一个.gitignore文件，把临时文件和日志排除掉：

*.log *.tmp __pycache__/ .DS_Store

实操心得：Git 仓库的默认分支名建议改成 main，跟主流平台保持一致。另外，如果笔记数量大，建议开启 Git 的压缩功能，在.git/config里加上core.compression = 9，能省不少磁盘空间。

3.3 第一个采集器：网页文章抓取与清洗

从最简单的网页采集器开始。我写了一个web_collector.py，输入是一个 URL 列表文件，输出是原子笔记的 Markdown 文件。核心逻辑分三步：请求网页、提取正文、生成笔记文件。

import requests from readability import Document from datetime import datetime import hashlib import os def collect_web(url): headers = { 'User-Agent': 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36' } try: resp = requests.get(url, headers=headers, timeout=15) resp.raise_for_status() except Exception as e: print(f"请求失败: {url}, 错误: {e}") return None doc = Document(resp.text) title = doc.title() content = doc.summary() # 生成笔记 ID note_id = datetime.now().strftime('%Y%m%d%H%M%S') + '_' + hashlib.md5(url.encode()).hexdigest()[:6] # 构建 Markdown 内容 md_content = f"""--- id: {note_id} source: web url: {url} title: {title} created_at: {datetime.now().isoformat()} --- # {title} {content} """ # 保存文件 date_path = datetime.now().strftime('%Y/%m/%d') save_dir = os.path.expanduser(f'~/apollo11/storage/{date_path}') os.makedirs(save_dir, exist_ok=True) filepath = os.path.join(save_dir, f'{note_id}.md') with open(filepath, 'w', encoding='utf-8') as f: f.write(md_content) return filepath

这个脚本跑通之后，我每天定时跑一次，把收藏的网页批量抓下来。实测下来，readability 对新闻类和技术博客的提取效果最好，对论坛帖子和社交媒体页面效果一般，经常把评论区也抓进来。后来我加了一个后处理步骤，用正则把常见的评论区标记删掉，准确率提升了不少。

3.4 清洗流水线的搭建与定时任务配置

采集器跑通后，接下来搭清洗流水线。清洗脚本clean_pipeline.py做三件事：读取原始笔记、清洗内容、生成标签并写回。清洗内容包括去除多余空行、统一标点、截断超长段落。标签生成用前面说的 TF-IDF 加规则过滤方案。

import re import jieba.analyse from pathlib import Path def clean_content(text): # 去除多余空行 text = re.sub(r'\n{3,}', '\n\n', text) # 统一标点 text = text.replace('，', '，').replace('。', '。') # 截断超长段落 paragraphs = text.split('\n\n') cleaned = [] for p in paragraphs: if len(p) > 500: # 按句号拆分 sentences = re.split(r'(?<=[。！？])', p) current = '' for s in sentences: if len(current) + len(s) > 500: cleaned.append(current) current = s else: current += s if current: cleaned.append(current) else: cleaned.append(p) return '\n\n'.join(cleaned) def generate_tags(text, top_k=5): keywords = jieba.analyse.extract_tags(text, topK=top_k*2) stopwords = set(['的', '了', '在', '是', '我', '有', '和', '就', '不', '也']) filtered = [kw for kw in keywords if kw not in stopwords and len(kw) > 1] return filtered[:top_k]

定时任务用系统的 cron 来配。我设了三个任务：每天早上六点跑采集器，七点跑清洗流水线，每周日晚上八点生成周报。cron 表达式分别是0 6 * * *、0 7 * * *、0 20 * * 0。配置的时候注意要用绝对路径，cron 的环境变量和登录 shell 不一样，相对路径经常找不到文件。

注意：cron 任务一定要加日志重定向。我最初没加，脚本报错了都不知道。后来改成>> ~/apollo11/logs/collector.log 2>&1，所有输出都进日志文件，排查问题方便多了。

3.5 输出层模板定制与周报自动生成

输出层的核心是 Jinja2 模板。我写了一个周报模板weekly_report.md.j2，结构包括：本周概览、按标签分类的笔记列表、来源统计、下周计划。生成脚本从 Git 仓库拉取本周新增的笔记，渲染模板，输出到outputs目录。

from jinja2 import Template from datetime import datetime, timedelta import subprocess def generate_weekly_report(): # 计算本周时间范围 today = datetime.now() start = today - timedelta(days=today.weekday()) end = start + timedelta(days=6) # 从 Git 仓库获取本周提交的笔记 result = subprocess.run( ['git', 'log', '--since', start.isoformat(), '--name-only', '--pretty=format:'], cwd=os.path.expanduser('~/apollo11/storage'), capture_output=True, text=True ) files = [f for f in result.stdout.split('\n') if f.endswith('.md')] # 读取笔记内容 notes = [] for f in files: filepath = os.path.join(os.path.expanduser('~/apollo11/storage'), f) with open(filepath, 'r', encoding='utf-8') as fp: content = fp.read() notes.append(parse_note(content)) # 渲染模板 with open('templates/weekly_report.md.j2', 'r') as fp: template = Template(fp.read()) output = template.render( start_date=start.strftime('%Y-%m-%d'), end_date=end.strftime('%Y-%m-%d'), notes=notes, total=len(notes) ) # 保存输出 output_path = os.path.expanduser(f'~/apollo11/outputs/weekly_{start.strftime("%Y%m%d")}.md') with open(output_path, 'w', encoding='utf-8') as fp: fp.write(output) return output_path

模板里我用了一些 Jinja2 的过滤器和循环，把笔记按标签分组，每组下面列出笔记标题和摘要。摘要取正文前 100 字，去掉 Markdown 标记。整个周报生成过程不到五秒，比手动整理快太多了。

4. 常见问题与排查技巧实录

4.1 采集器被目标网站拒绝的排查思路

采集器跑了一段时间后，最常遇到的问题就是请求被拒。表现是返回 403 或者 429 状态码，或者返回一个验证页面而不是正文。排查思路分三步：先看状态码，403 一般是请求头被识别，429 是请求频率太高。然后检查 User-Agent 是否被屏蔽，换个常见的浏览器 UA 试试。最后看是否需要加 Referer 头，有些网站会检查来源页面。

我整理了一个常见状态码的排查表：

实操心得：请求间隔我设的是 3 到 8 秒随机，这个范围实测下来既能保证速度，又不容易触发频率限制。如果目标网站特别严格，可以加到 10 到 20 秒，但采集速度会明显变慢。权衡一下，我一般优先保证成功率。

4.2 清洗后标签质量差的优化方法

标签质量差是另一个高频问题。表现是标签里出现大量无意义的词，或者标签跟内容完全不相关。原因通常是分词不准确或者停用词表不完整。优化方法有三个：扩充停用词表、调整 TF-IDF 参数、引入人工确认环节。停用词表我维护了一个stopwords.txt，除了常见虚词，还加了一些领域相关的无意义词，比如“转载”“点击”“查看”这类网页常见词。

TF-IDF 的参数主要是topK和withWeight。topK控制返回的关键词数量，我一般设成目标标签数的两倍，留出过滤空间。withWeight设成 True 可以拿到权重，方便按权重排序。人工确认环节我放在清洗流水线的最后一步，生成一个待确认列表，我每天花五分钟过一遍，把不合适的标签删掉，把漏掉的关键词补上。这个习惯坚持了两个月后，标签质量明显提升，后续检索效率高了很多。

4.3 Git 仓库体积膨胀的清理方案

Git 仓库用久了体积会膨胀，尤其是频繁提交的情况下。我遇到过仓库从 200MB 涨到 1.5GB 的情况，原因是历史提交里存了很多后来删掉的大文件。清理方案是用git filter-branch或者bfg工具重写历史，把大文件从所有提交里删掉。操作前一定要备份仓库，重写历史是不可逆的。

# 备份仓库 cp -r ~/apollo11/storage ~/apollo11/storage_backup # 用 bfg 清理大文件 java -jar bfg.jar --strip-blobs-bigger-than 1M ~/apollo11/storage # 清理引用和垃圾回收 cd ~/apollo11/storage git reflog expire --expire=now --all git gc --prune=now --aggressive

清理完之后，仓库体积降到了 150MB 左右。为了防止再次膨胀，我加了一个 pre-commit 钩子，检查提交的文件大小，超过 1MB 就拒绝提交并提示。这个钩子用 shell 脚本写的，放在.git/hooks/pre-commit里，记得加执行权限。

4.4 定时任务不执行的常见原因

cron 任务不执行是新手最容易踩的坑。原因通常有三个：路径问题、权限问题、环境变量问题。路径问题是指 cron 里的命令用了相对路径，但 cron 的工作目录跟登录 shell 不一样。解决方法是一律用绝对路径。权限问题是指脚本没有执行权限，或者 cron 服务没启动。检查方法是systemctl status cron看服务状态，chmod +x给脚本加执行权限。环境变量问题是指脚本依赖的环境变量在 cron 里没有，解决方法是在脚本开头手动设置，或者在 crontab 里定义。

我习惯在 crontab 开头加一行PATH=/usr/local/bin:/usr/bin:/bin，把常用路径都包含进去。另外，脚本里用到的 Python 解释器也写绝对路径，比如/usr/bin/python3，避免 cron 找不到。

5. 系统扩展与长期维护的个人体会

这套系统跑了一年多，中间经历过几次大的调整。最初只有网页采集，后来慢慢加了 PDF、电子书、语音。每次加新来源，都是先写一个独立的采集器，跑通后再接入清洗流水线。这种增量式扩展的方式让我每次只需要关注一个新点，不会因为改动太大导致整个系统崩溃。我个人的体会是，不要试图一次性设计一个完美的系统，先跑通最小可用版本，然后在用的过程中逐步优化。很多需求是用了之后才发现的，提前设计反而容易过度工程。

另一个体会是定期回顾和清理。我每个月会花半小时过一遍这个月的笔记，把重复的合并，把过时的删掉，把重要的加上星标。这个习惯让仓库保持整洁，检索效率不会随时间下降。星标笔记我会单独同步到一个highlights目录，方便快速访问。

最后分享一个小技巧：给采集器加一个“手动触发”的快捷方式。我在手机和电脑上都设了一个快捷指令，遇到好文章一键发送到采集器。这个快捷方式就是一个 HTTP 请求，打到本地的一个小服务上，服务收到请求后调用采集器脚本。整个过程不到两秒，比复制粘贴到笔记软件快多了。这个功能上线后，我的采集量翻了一倍，因为采集的摩擦成本几乎降到了零。