企业官网建设流程全解析

1. 为什么我要给 Obsidian 笔记做自动打标签

用 Obsidian 超过两年的人大概都有同一个感受：笔记越写越多，搜索越来越难。我自己的库现在有四千多篇笔记，早期靠文件夹分类，后来靠双链和 MOC，再后来发现真正卡脖子的不是"找不到"，而是"不知道该找什么"。你脑子里没有那个关键词，搜索框里就敲不出来，笔记就永远沉在库里。

标签系统解决的就是这个问题。它和双链不一样，双链是"我明确知道这两篇有关系"，标签是"这两篇属于同一类语义场"。前者靠人工判断，后者可以靠模型批量生成。所以当我第一次把 Jev 这个模型接进 Obsidian 的标签流程时，整个库的可检索性直接上了一个台阶。

这篇东西写给三类人：一是 Obsidian 用了一段时间、笔记过千但标签体系还是空白的人；二是想用 API 和 CLI 把 AI 能力接进自己知识库、但不知道从哪下手的人；三是已经在用 Jev 或类似模型、想找一个具体落地场景练手的人。全文围绕"Jev + Obsidian + 标签"这一条主线，把 API 调用、CLI 批处理、标签规范、常见坑全部拆开讲。

先说清楚一件事：这不是让你把打标签这件事完全交给模型。模型负责"初筛"，人负责"终审"。我实测下来，纯自动打标签的库，三个月后基本会烂掉，因为标签会无限膨胀。所以下面所有方案里，我都会强调"受控词表"这个概念，这是整个流程能不能长期跑下去的关键。

2. 整体方案设计与技术选型思路

2.1 三种打标签路线的取舍

在动手之前，我把能想到的方案都列了一遍，最后筛出三条可行路线，各自适合不同规模的库。

我最后选的是API 脚本为主、CLI 为辅的混合方案。原因很直接：Obsidian 的笔记本质就是本地 Markdown 文件，用脚本直接读写 frontmatter 是最稳的，不依赖任何插件生态。CLI 则用来做定时任务和增量处理，比如每天睡前跑一次，只处理当天新增或修改过的笔记。

这里要解释一个关键决策：为什么不直接在 Obsidian 里装插件搞定？因为插件的模型调用通常是黑盒，你没法控制提示词、没法控制并发、没法控制失败重试。而打标签这件事对提示词的敏感度极高，同一篇笔记，提示词里加一句"优先复用已有标签"，输出结果能差出一倍。所以必须自己掌控调用层。

2.2 标签体系的设计原则

在写任何代码之前，先把标签规则定下来。这一步偷懒，后面全是返工。

我给自己定的规则是三条：

• 层级不超过两级：比如技术/前端、阅读/心理学，绝不做技术/前端/框架/React/ hooks这种四级标签。层级一深，人记不住，模型也容易乱造。
• 单篇笔记标签数控制在 3-6 个：少于 3 个覆盖不足，多于 6 个等于没打。
• 受控词表 + 自由标签分离：受控词表是我手动维护的、允许模型使用的标签白名单；自由标签是模型可以新造、但需要我事后审核的。两者在 frontmatter 里用不同字段区分。

受控词表我放在库根目录一个叫_tags_whitelist.md的文件里，格式就是一行一个标签，脚本每次运行前先读它。这样我想调整标签体系，改一个文件就行，不用动代码。

2.3 Jev 在这个流程里的角色定位

Jev 在这里干的事情很具体：读一篇笔记的正文，输出一组符合规范的标签。它不负责判断笔记质量，不负责生成摘要，不负责建立双链。职责越单一，提示词越好写，输出越稳定。

我试过让模型一次性输出"标签 + 摘要 + 关联笔记"，结果标签质量明显下降，因为模型的注意力被分散了。后来拆成三个独立任务，每个任务一个提示词，标签准确率肉眼可见地提升。这个经验值得记一下：一个模型调用只做一件事。

3. 核心细节解析与实操要点

3.1 提示词怎么写才不跑偏

提示词是整个流程的灵魂。我前后改了十几版，最后稳定下来的结构是这样的：

你是一个知识库标签助手。请为下面的笔记内容生成 3-6 个标签。 规则： 1. 优先从以下白名单中选择标签：{whitelist} 2. 如果白名单中没有合适的标签，可以新造，但必须遵循"一级/二级"格式 3. 标签使用中文，不要用英文，除非是专有名词 4. 只输出标签，用英文逗号分隔，不要输出任何解释 5. 不要生成"笔记""记录""想法"这类无意义标签 笔记标题：{title} 笔记内容：{content}

几个细节值得展开说。

第一，白名单要动态注入。每次调用前把当前白名单拼进提示词，模型就会优先复用。我实测下来，加了白名单之后，新造标签的比例从 40% 降到了 8% 左右。

第二，明确禁止无意义标签。模型特别喜欢输出"笔记""记录""思考"这种词，因为它们在任何笔记里都"正确"。必须在提示词里点名禁止，否则你的库里会堆满这种废标签。

第三，要求只输出标签。一旦允许模型输出解释，解析就麻烦了。宁可让它只吐一行逗号分隔的字符串，脚本用split(',')就能处理。

第四，内容要截断。长笔记直接全文塞进去，token 消耗大且没必要。我的做法是取标题 + 前 800 字 + 各级小标题。小标题往往最能反映笔记主题，比正文还准。

3.2 frontmatter 的读写规范

Obsidian 的标签有两种存法：正文里的#标签，和 frontmatter 里的tags:字段。我强烈建议用frontmatter，原因有三：

• 正文标签会污染阅读体验，尤其是标签多的时候
• frontmatter 标签能被 Dataview 等插件直接查询
• 脚本读写 frontmatter 比正则匹配正文标签稳得多

frontmatter 的结构我这样设计：

--- title: 笔记标题 tags: - 技术/前端 - 工具/Obsidian auto_tags: - AI生成 - 知识管理 ---

tags是我确认过的正式标签，auto_tags是模型生成、待审核的。这样我可以在 Obsidian 里用一个 Dataview 查询把所有auto_tags非空的笔记列出来，逐条审核，确认的移到tags，不合适的删掉。这个"待审区"的设计是整个流程能长期维护的关键。

注意：frontmatter 的 YAML 对缩进和特殊字符敏感。标签里如果出现冒号、井号，必须用引号包起来，否则解析会出错。我踩过这个坑，一批笔记的 frontmatter 直接损坏，靠 Git 才恢复回来。

3.3 并发与限流的平衡

批量处理四千篇笔记，如果串行调用 API，按每篇 2 秒算，要两个多小时。所以必须并发。但并发太高会被限流，还会因为网络抖动导致大量失败。

我的参数是这样定的：

• 并发数 5：实测这个值在大多数 API 服务上不会触发限流，再高就容易 429
• 单次超时 30 秒：模型生成标签通常 3-5 秒返回，30 秒足够覆盖网络波动
• 失败重试 3 次，指数退避：第一次失败等 2 秒，第二次等 4 秒，第三次等 8 秒
• 每处理 50 篇落一次盘：防止跑到一半崩溃，前面的结果全丢

这些参数不是拍脑袋定的，是我用不同并发数跑了五轮对比出来的。并发 10 的时候失败率飙到 15%，并发 5 的时候稳定在 1% 以下。稳定性比速度重要，因为失败重试的时间成本远高于降低并发损失的时间。

4. 实操过程与核心环节实现

4.1 环境准备与依赖安装

先把环境搭起来。我用的是 Python，因为处理 Markdown 和 YAML 的库最成熟。

python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate pip install requests pyyaml python-frontmatter tqdm

四个库各司其职：requests发 HTTP 请求，pyyaml解析 frontmatter，python-frontmatter专门处理 Markdown 的元数据块，tqdm显示进度条。别小看进度条，处理几千篇笔记的时候，没有进度条你会怀疑程序是不是卡死了。

API Key 不要硬编码在脚本里。我用环境变量：

export JEV_API_KEY="你的key"

脚本里用os.environ.get("JEV_API_KEY")读取。这样脚本可以放心提交到 Git，不会泄露密钥。

4.2 核心脚本的完整实现

下面是主脚本，我把它拆成几个函数，每个函数只干一件事。

import os import time import frontmatter import requests from pathlib import Path from concurrent.futures import ThreadPoolExecutor, as_completed from tqdm import tqdm API_KEY = os.environ.get("JEV_API_KEY") API_URL = "https://api.example.com/v1/chat/completions" # 替换为实际端点 VAULT_PATH = Path("/path/to/your/vault") WHITELIST_FILE = VAULT_PATH / "_tags_whitelist.md" def load_whitelist(): if not WHITELIST_FILE.exists(): return [] lines = WHITELIST_FILE.read_text(encoding="utf-8").splitlines() return [l.strip() for l in lines if l.strip() and not l.startswith("#")] def extract_content(post, max_chars=800): title = post.get("title", "") body = post.content # 提取小标题 headings = [l for l in body.splitlines() if l.startswith("#")] body_snippet = body[:max_chars] return f"标题：{title}\n小标题：{' | '.join(headings[:10])}\n正文：{body_snippet}" def call_jev(title, content, whitelist, retries=3): prompt = build_prompt(title, content, whitelist) for attempt in range(retries): try: resp = requests.post( API_URL, headers={"Authorization": f"Bearer {API_KEY}"}, json={ "model": "jev", "messages": [{"role": "user", "content": prompt}], "temperature": 0.3, }, timeout=30, ) resp.raise_for_status() text = resp.json()["choices"][0]["message"]["content"] return [t.strip() for t in text.split(",") if t.strip()] except Exception as e: if attempt == retries - 1: print(f"失败：{title} - {e}") return [] time.sleep(2 ** attempt) return [] def build_prompt(title, content, whitelist): wl = "、".join(whitelist) return f"""你是一个知识库标签助手。请为下面的笔记生成 3-6 个标签。 规则： 1. 优先从白名单选择：{wl} 2. 白名单无合适项时可新造，格式为"一级/二级" 3. 中文标签，专有名词除外 4. 只输出标签，英文逗号分隔，不要解释 5. 禁止"笔记""记录""想法"等无意义标签 {content} """ def process_file(md_path, whitelist): post = frontmatter.load(md_path) if post.get("tags") and not post.get("auto_tags"): return None # 已人工确认，跳过 content = extract_content(post) tags = call_jev(post.get("title", md_path.stem), content, whitelist) if not tags: return None post["auto_tags"] = tags md_path.write_text(frontmatter.dumps(post), encoding="utf-8") return md_path.name def main(): whitelist = load_whitelist() files = list(VAULT_PATH.rglob("*.md")) files = [f for f in files if not f.name.startswith("_")] print(f"共 {len(files)} 篇待处理") with ThreadPoolExecutor(max_workers=5) as executor: futures = {executor.submit(process_file, f, whitelist): f for f in files} for future in tqdm(as_completed(futures), total=len(futures)): future.result() if __name__ == "__main__": main()

这段代码有几个地方是我反复调过的。

temperature设成 0.3。标签任务需要稳定，不需要创意。温度太高，同一篇笔记跑两次结果不一样，没法审核。0.3 是我试出来的平衡点，再低模型会变得死板，只会从白名单里挑，失去发现新标签的能力。

跳过已有tags的笔记。这个判断很重要，否则每次跑都会覆盖你人工确认过的标签。逻辑是：如果tags有值且auto_tags为空，说明这篇已经审核过了，跳过。

文件名以下划线开头的跳过。Obsidian 里我习惯用_前缀标记模板、白名单这类非笔记文件，脚本要排除它们。

4.3 CLI 增量处理方案

全量跑一次之后，日常只需要处理新增和修改的笔记。这时候用 CLI 更合适。

#!/bin/bash # daily_tag.sh - 每天处理最近修改的笔记 VAULT="/path/to/your/vault" SINCE_FILE="$VAULT/.last_tag_run" if [ -f "$SINCE_FILE" ]; then SINCE=$(cat "$SINCE_FILE") else SINCE="1970-01-01" fi find "$VAULT" -name "*.md" -newermt "$SINCE" -not -name "_*" > /tmp/changed_files.txt python tag_script.py --files /tmp/changed_files.txt date +"%Y-%m-%d %H:%M:%S" > "$SINCE_FILE"

这个脚本用find -newermt找出上次运行之后修改过的文件，只处理这些。配合系统的定时任务，每天跑一次，增量处理通常几十秒就完事。

提示：.last_tag_run这个文件要加到.gitignore里，它是本地状态，不该同步。我一开始忘了加，结果多设备同步的时候时间戳互相覆盖，导致重复处理。

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

5.1 标签质量问题的排查

跑完第一轮之后，我抽查了 100 篇笔记，发现几类典型问题，整理成速查表。

其中"同一概念多种写法"是最头疼的。比如"知识管理""知识库""笔记方法"其实是一回事，模型会随机选。解决办法是在白名单里只保留一个标准写法，其他作为同义词在提示词里说明"遇到知识库、笔记方法，统一用知识管理"。

5.2 API 调用的典型故障

故障一：429 限流。表现是大量请求返回 429。排查思路是先降并发，从 5 降到 3 再试。如果还不行，说明服务端限流阈值很低，需要在请求之间加固定延迟。我遇到过一次，最后是并发 2 + 每次请求间隔 0.5 秒才稳定。

故障二：返回内容解析失败。模型偶尔会输出"标签：xxx, yyy"这种带前缀的格式，split(',')之后第一个标签会带上"标签："。解决方法是解析前先做一次清洗，用正则去掉^[^:]*：这样的前缀。

故障三：frontmatter 损坏。表现是 Obsidian 打不开某些笔记。原因是标签里含特殊字符，YAML 解析失败。预防方法是在写入前对每个标签做校验，只允许中文、英文、数字、斜杠、连字符，其他字符一律过滤掉。

import re def sanitize_tag(tag): tag = re.sub(r"[^\w\u4e00-\u9fff/\-]", "", tag) return tag.strip("/")

这个正则保留了中文、字母数字、斜杠和连字符，其他全部剔除。加在写入 frontmatter 之前，能挡掉 99% 的损坏问题。

5.3 我踩过的三个坑

坑一：没做备份就全量跑。第一次跑的时候，脚本有个 bug 把tags字段覆盖了，四千篇笔记的人工标签全没了。幸好库在 Git 里，git checkout .恢复了。从那以后，我跑任何批量脚本之前都先git commit一次。这个习惯救了我至少三次。

坑二：白名单文件被脚本自己处理了。白名单文件放在库根目录，脚本扫描时把它也当成笔记处理，往里写auto_tags，结果白名单被污染。后来加了_前缀过滤才解决。所以命名规范不是洁癖，是实打实的功能需求。

坑三：并发写入同一文件。早期版本没做文件锁，两个线程同时处理一篇笔记（因为软链接导致重复扫描），frontmatter 写坏了。解决方法是扫描时用resolve()去重，确保每个真实路径只处理一次。

files = list({f.resolve() for f in VAULT_PATH.rglob("*.md")})

这一行去重，比任何锁机制都简单有效。

5.4 标签体系的长期维护

跑通流程只是开始，真正难的是让标签体系不腐烂。我的做法是每月做一次"标签体检"：

• 用 Dataview 查出所有auto_tags非空的笔记，逐条审核
• 统计每个标签的使用频次，低于 3 次的考虑合并或删除
• 检查是否有新出现的、值得纳入白名单的标签
• 把审核通过的标签从auto_tags移到tags

这个体检一次大概花半小时，但能让整个库的标签保持干净。我见过太多人一开始热情满满，三个月后标签库变成一团乱麻，最后干脆放弃标签系统。维护成本必须控制在可承受范围内，否则再好的方案也跑不长。

6. 关于这套流程我个人的几点体会

这套东西我从最初的想法到稳定运行，前后折腾了大概三周。最大的感受是：AI 打标签的价值不在于"自动"，而在于"初筛"。它帮你把四千篇笔记过一遍，给出一个 80 分的基础，你只需要在这个基础上做 20 分的修正。如果指望它直接给你 100 分的结果，那一定会失望。

另一个体会是，受控词表的重要性怎么强调都不过分。我一开始觉得让模型自由发挥挺好，结果标签数量两周内从 50 个膨胀到 300 个，全是同义词和近义词。后来痛下决心做白名单，把标签数量压回 80 个以内，整个库的可检索性反而提升了。标签不是越多越好，是越准越好。

最后分享一个小技巧：如果你也在用 Obsidian，可以在库根目录建一个_tag_dashboard.md，用 Dataview 写几个查询，一个显示待审核的auto_tags，一个显示标签使用频次排行，一个显示最近新增的标签。每次打开这个文件，标签体系的健康状况一目了然。这个面板我每天都会扫一眼，比任何自动化都管用。