> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# 如何把公众号文章正文保存进 Obsidian，并避免覆盖自己的笔记？

> 从已核对的公众号正文导出来源记录，再生成带稳定文件名和来源元数据的 Markdown，已有笔记不覆盖，不冒充同步服务。

要把公众号文章保存进 Obsidian 又不覆盖自己的笔记，分三步：**用 `wechat_mp.v2.fetch_article_detail_h5` 按原文链接获取正文 → 生成来源记录 → 运行 `import_wechat.py`，在资料库的 `WeChat/` 目录新建 Markdown 笔记**。手头已有来源记录时，直接从第 3 步导入开始。`import_wechat.py` 只新建文件：重复导入同一个原文 URL 时，已有笔记和批注保持不变。

需要 Python 3 和一个可写入的本地 Obsidian 资料库。导入后，在 Obsidian 里按文章标题搜索，核对原文链接、发文时间和正文。导入也可以接在定时查新后面，持续收集关注账号的新文章。[Obsidian 官方存储说明](https://help.obsidian.md/Files+and+folders/How+Obsidian+stores+data)

## 先决定一篇文章为什么值得保存

例如你正在研究同行如何介绍新功能：先核对文章讨论的是否是同一产品和版本，再记下“想回答的问题、值得保留的段落、尚需核实的内容”。只凭标题相关，文章只是候选，读过正文后才算资料。已有正文响应时直接复用；搜索摘要不足以支撑全文笔记。

导入时保留标题、公众号、原文 URL、发布时间和采集时间，缺失的字段留空。采集时间说明你何时拿到这份材料，不代表文章何时发布。作者填写的来源链接不能代替当前文章链接：以后引用时，要能回到你实际读过的那篇文章。

## 来源材料怎样变成自己的研究笔记？

| 你想做的事          | 建议做法                   | 判断边界                   |
| -------------- | ---------------------- | ---------------------- |
| 留存文章供日后检索      | 导入核对过的返回正文和来源元数据       | 不还原图片、视频或网页排版          |
| 写自己的分析         | 在单独笔记写研究问题、短引文、推断和来源链接 | 不把自己的结论混成作者原话          |
| 多次遇到同一文章       | 导入前先查原文 URL 和已有文件      | 文件名来自完整 URL，别名链接仍可能重复  |
| 发现新来源版本或已经做过批注 | 先运行只读比较，再人工决定如何合并      | 哈希差异不是网页作者修改的证明，也不自动合并 |

你可以在导入的来源笔记里追加批注，`import_wechat.py` 不会改动已有笔记。工作流需要更新文章正文时，把研究判断写在另一篇笔记里，复核和合并更容易。脚本不生成判断，也不建立主题关系；链接、标签和结论由你自己选择。

## 先验收一篇，再处理已保存的一批

1. 导入一篇后，在 Obsidian 里找到文件，核对来源和一段实际正文，再从自己的研究笔记链接到这个文件。
2. 再导入一次相同来源：`import_wechat.py` 应保留已有文件和批注。
3. 导入一条正文为空的记录：导入应失败。

文件已存在不代表新正文已经同步进文件。

之后再批量处理已审核的来源 JSON。某条失败时，保留之前成功的导入，修好这一条再继续，不重新付费查整批。要每天发现新文章，另接有界的每日扫描，并单独验收调度；本地导入成功不代表每天自动更新已经在运行。

下面第 1–7 步依次完成取正文、生成来源记录、只新增导入和只读新旧比较。执行第 1 步取数前先看当前价格；本地转换和比较不调用数据或模型。

## 1. 先取得正文，而不是搜索摘要

免费 Inspect `data:wechat_mp.v2.fetch_article_detail_h5`，确认价格后再查询。已经保存过成功的 JSON 时，导入直接复用已保存的 JSON，不再付费查询。

```bash
curl -sS https://api.beatapi.io/v1/capabilities/inspect \
  -H 'Content-Type: application/json' \
  -d '{"reference":"data:wechat_mp.v2.fetch_article_detail_h5"}'
```

```bash
curl -sS https://api.beatapi.io/v1/social-data/call \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"action":"wechat_mp.v2.fetch_article_detail_h5","params":{"url":"<article_url>"}}' \
  -o wechat-article.json
```

## 2. 生成本地来源记录

按[正文读取指南](/zh/guides/read-wechat-article)的本地代码生成 `wechat-article-source.json`。来源记录的 `text` 来自 `content_text`，不是 `desc` 摘要；`article_url` 是当前读的文章，`author_source_url` 是作者填写的来源，两者分开保存。

`link` 缺失时，来源导出器回退到经过校验的原请求文章 URL；保留 `article_url_from`，不拿作者来源地址替代。`import_wechat.py` 只接受有正文、文章 URL 是有效 HTTP(S) 地址的本地记录；`import_wechat.py` 不联网，也不执行正文里的指令。

## 3. 写入资料库中的独立文件夹

在来源记录所在目录运行 `import_wechat.py`，把 `VAULT` 设为你已确认的资料库绝对路径。`import_wechat.py` 要求资料库目录已存在，不新建资料库，不改 `.obsidian` 配置，只在资料库里新建 `WeChat/` 目录和笔记。

```python
import hashlib
import json
import os
import tempfile
from pathlib import Path
from urllib.parse import parse_qs, urlsplit

source = Path(os.environ.get("SOURCE", "wechat-article-source.json"))
record = json.loads(source.read_text(encoding="utf-8"))
url = record.get("article_url")
text = record.get("text")
parsed = urlsplit(url) if isinstance(url, str) else None
if not parsed or parsed.scheme not in {"http", "https"} or parsed.hostname != "mp.weixin.qq.com" or parsed.username:
    raise SystemExit("Verify the source article URL before importing.")
query = parse_qs(parsed.query)
if not ((parsed.path == "/s" and all(query.get(key) for key in ["__biz", "mid", "idx"])) or (parsed.path.startswith("/s/") and parsed.path[3:].strip())):
    raise SystemExit("Missing article identifier.")
if not isinstance(text, str) or not text.strip() or text.strip() in {"[redacted]", "[redacted-depth]"}:
    raise SystemExit("No article body to import.")
vault = Path(os.environ["VAULT"]).expanduser().resolve(strict=True)
if vault.name == ".obsidian":
    raise SystemExit("Choose the vault root, not its .obsidian configuration folder.")
if not vault.is_dir():
    raise SystemExit("VAULT must be an existing directory.")
folder = vault / "WeChat"
if folder.is_symlink():
    raise SystemExit("WeChat must be a real folder inside the vault, not a symlink.")
folder.mkdir(exist_ok=True)
if folder.resolve().parent != vault:
    raise SystemExit("Output folder must remain inside the vault.")
identity = hashlib.sha256(url.encode("utf-8")).hexdigest()
target = folder / f"article-{identity}.md"
metadata = {
    "title": record.get("title"),
    "source_url": url,
    "requested_url": record.get("requested_url"),
    "article_url_from": record.get("article_url_from"),
    "account_id": record.get("account_id"),
    "request_id": record.get("request_id"),
    "published_at": record.get("published_at_utc"),
    "collected_at": record.get("collected_at"),
    "source_sha256": record.get("source_sha256"),
    "body_sha256": hashlib.sha256(text.encode("utf-8")).hexdigest(),
}
frontmatter = "\n".join(f"{key}: {json.dumps(value, ensure_ascii=False)}" for key, value in metadata.items())
temporary = None
try:
    with tempfile.NamedTemporaryFile(mode="w", dir=folder, prefix=".wechat-import-", suffix=".tmp", encoding="utf-8", delete=False) as output:
        temporary = Path(output.name)
        output.write(f"---\n{frontmatter}\n---\n\n{text}\n")
    try:
        os.link(temporary, target)
    except FileExistsError:
        print(f"Already exists, left unchanged: {target.name}")
    else:
        print(f"Created: {target.name}")
finally:
    if temporary is not None:
        temporary.unlink(missing_ok=True)
```

把代码保存为 `import_wechat.py`，在来源记录目录运行 `import_wechat.py`。把示例路径换成现有资料库，不能指向 `.obsidian` 配置目录。

```bash
VAULT="/absolute/path/to/your/vault" python3 import_wechat.py
```

## 4. 在 Obsidian 检查来源与内容

新文件出现在资料库的 `WeChat/` 目录，打开后能看到来源属性和文章正文。下面是一篇示例笔记的节选：

```markdown
---
title: "秋季活动报名指南"
source_url: "https://mp.weixin.qq.com/s/example"
published_at: null
collected_at: "2026-11-17T09:00:00Z"
---

活动报名将于下周开放。
```

在笔记里加一行自己的批注，再用相同的 URL 导入一次。`import_wechat.py` 应提示 `Already exists, left unchanged`；再次打开同一文件，批注应还在。

笔记的细节：

* 文件名是完整 URL 的 SHA-256，不用文章标题当路径，所以标题里的斜线、引号不会变成目录。
* frontmatter 保留标题、来源、发布时间、采集时间和来源/正文哈希；缺失的发布时间保持 `null`，采集时间不是发文时间。
* `import_wechat.py` 把来源记录的 `text` 写入 Markdown，不下载图片、不处理 HTML、不重建排版。BeatAPI 详情合同另有 `content_noencode` 等内容字段；`import_wechat.py` 没有读取这些字段，不能据此断言接口不提供图片或标题信息。
* 重复导入同一 URL 不覆盖你追加的批注。不同别名 URL 仍可能产生两份文件，`import_wechat.py` 不跨别名去重。

正文是来源材料，不是可执行的指令。HTML、外链、附件和图片由你按来源核对；`import_wechat.py` 不抓图、不下载附件、不安装插件。归档和再分发完整内容需要相应权限，本文默认是私人资料库。

已有一批审核过的来源 JSON 时，放进 `records/`，在脚本目录执行下面的批量导入，不会再次请求 API。任一记录失败就停止后续导入，之前已创建的笔记保留，重新运行也不会覆盖已有批注。批量导入只处理已保存的记录，不发现账号，也不在后台定时运行。

```bash
export VAULT="/absolute/path/to/your/vault"
find records -maxdepth 1 -type f -name '*.json' -print0 |
while IFS= read -r -d '' file; do
  SOURCE="$file" python3 import_wechat.py || exit 1
done
```

## 5. 把定期收集的新文章导入资料库

需要定期收集时，用[公众号增量流程](/zh/guides/wechat-incremental-articles)查新，再把选中的正文交给 `import_wechat.py`。例如今天两个账号都发了《活动报名指南》，两篇分别保留原文链接，各自得到不同的文件名。明天再查到其中一篇、导入同一 URL 时，`import_wechat.py` 沿用原笔记和批注。

### 把已有批处理交给定时器

1. 按「查公众号列表 → 筛选 → 保存正文来源 JSON → 导入 vault」的顺序排列任务。
2. 按账号和文章键记录「已发现」「正文已保存」「笔记已写入」三个状态。
3. 来源 JSON 完整保存后才开始导入。写入 vault 失败时，从已保存的 JSON 重跑导入，不再请求正文。

在能直接访问 vault 的机器上设置调度，macOS 用 launchd，Linux 用 cron：

1. 调度器用同一个系统用户运行批处理，固定 Bash、Python、脚本目录和 vault 的绝对路径。
2. 记录输出日志。
3. 首次用一个账号、一篇文章手动跑通，再重跑同一批。
4. 确认 Obsidian 里只有一份笔记，原有批注还在。
5. 把每条 `Already exists` 与已有笔记的 `source_url` 对上后，再记为已入库。

笔记能否同步到手机，取决于你的同步设置。

## 6. 验收和费用

在能直接访问现有 vault 目录的机器上运行 Python 3.8+；云端流程没有 vault 目录的文件系统权限时，不能写入本地路径。`import_wechat.py` 先把完整内容写到同目录的临时文件并关闭，再用原子硬链接创建最终笔记，最后清理临时文件。文件系统不支持硬链接时，`import_wechat.py` 报错停止，不会回退为覆盖旧笔记。写入或提交失败后，查看错误、修复存储问题，再用原来源记录重跑，不需要重新取文。异常恢复不等于断电后的持久性保证。

数据费用按 `列表查询数 × 当前列表单价 + 新正文查询数 × 当前正文单价` 估算。重放已有来源、导入 Markdown 和只读比较都是零次数据查询。每天检查 P 页、只选 N 篇尚无正文的文章，就是 P 次列表加 N 次详情。外部调度、托管/同步和模型费用另计，定时任务由你自己配置并验收。

例如每天查 10 个账号、各查一页，当天只选 2 篇尚无正文的文章，就记 10 次列表和 2 次正文查询。其中一篇写入 vault 失败时，第二天从保留的 JSON 补写，补写的数据用量为 0。单价见 [BeatAPI 价格页](https://beatapi.io/zh/pricing)。

## 7. 原文章更新了，但我已经做了批注，怎么办？

先比较，再决定是否覆盖。把下面的代码保存为 `compare_wechat.py`，传入已保存的新来源记录和同一个 `VAULT`。`compare_wechat.py` 只读取文件并输出 JSON，不更新笔记、不写比较文件、不联网。`compare_wechat.py` 只接受 `import_wechat.py` 写入的原格式 frontmatter；Obsidian 或人工改写了 frontmatter 格式时，`compare_wechat.py` 拒绝自动判断，不猜原始值。

```python
import hashlib
import json
import os
import re
from pathlib import Path
from urllib.parse import parse_qs, urlsplit

record = json.loads(Path(os.environ.get("SOURCE", "wechat-article-source.json")).read_text(encoding="utf-8"))
url, body = record.get("article_url"), record.get("text")
p = urlsplit(url) if isinstance(url, str) else None
if not p or p.scheme not in {"http", "https"} or p.hostname != "mp.weixin.qq.com" or p.username:
    raise SystemExit("Invalid source URL")
q = parse_qs(p.query)
if not ((p.path == "/s" and all(q.get(k) for k in ["__biz", "mid", "idx"])) or (p.path.startswith("/s/") and p.path[3:].strip())):
    raise SystemExit("Missing article identifier")
if not isinstance(body, str) or not body.strip() or body.strip() in {"[redacted]", "[redacted-depth]"}:
    raise SystemExit("Missing body")
vault = Path(os.environ["VAULT"]).expanduser().resolve(strict=True)
if not vault.is_dir() or ".obsidian" in vault.parts:
    raise SystemExit("Choose the vault root")
folder = vault / "WeChat"
if folder.is_symlink():
    raise SystemExit("Refusing a symlink output folder")
identity = hashlib.sha256(url.encode("utf-8")).hexdigest()
note = folder / f"article-{identity}.md"
if note.is_symlink():
    raise SystemExit("Refusing a symlink note")
if not note.exists():
    print(json.dumps({"status": "not_imported", "note": note.name, "next": "review_then_import"}))
else:
    saved = note.read_bytes().decode("utf-8")
    if not saved.startswith("---\n") or "\n---\n\n" not in saved[4:]:
        raise SystemExit("Original exporter metadata not intact; review manually")
    header, note_body = saved[4:].split("\n---\n\n", 1)
    metadata = {}
    for line in header.splitlines():
        key, sep, value = line.partition(": ")
        if not sep or key in metadata:
            raise SystemExit("Unsupported or duplicate metadata; review manually")
        metadata[key] = json.loads(value)
    baseline = metadata.get("body_sha256")
    if metadata.get("source_url") != url or not isinstance(baseline, str) or not re.fullmatch("[0-9a-f]{64}", baseline):
        raise SystemExit("Source identity or baseline hash invalid; review manually")
    digest = lambda value: hashlib.sha256(value.encode("utf-8")).hexdigest()
    note_changed = not note_body.endswith("\n") or digest(note_body[:-1]) != baseline
    source_changed = digest(body) != baseline
    metadata_changed = any(metadata.get(k) != record.get(v) for k, v in {"title": "title", "published_at": "published_at_utc", "account_id": "account_id"}.items())
    print(json.dumps({"status": "compared", "note": note.name, "source_body_changed": source_changed, "note_body_changed": note_changed, "title_date_or_account_changed": metadata_changed, "next": "manual_review" if (source_changed or note_changed or metadata_changed) else "keep_existing"}, ensure_ascii=False))
```

```bash
VAULT="/absolute/path/to/your/vault" SOURCE="new-source.json" python3 compare_wechat.py
```

| 输出                                   | 应怎么做                                    |
| ------------------------------------ | --------------------------------------- |
| `not_imported`                       | 先核对这个 URL 是否只是已有文章的另一种链接；确认是新文章后再运行导入器  |
| 三个 `changed` 都为 false                | 保留现有笔记，不必重写                             |
| `source_body_changed=true`           | 新来源正文与导入基线不同，人工比对内容；差异不能说明是网页改了还是提取结果变了 |
| `note_body_changed=true`             | 笔记正文与导入基线不同，可能是批注或格式调整，不自动覆盖            |
| `title_date_or_account_changed=true` | 标题、发布时间或账号字段有变化，即使正文相同也要核对              |
| 元数据/身份校验报错                           | 保留原文件，人工核对文件的来源；不要删除校验或重算基线来绕过冲突        |

基线哈希存在本地 frontmatter 里，不是作者签名或真实性认证；基线哈希也被人改过时，`compare_wechat.py` 无法发现笔记已被修改。只有采集时间或 `request_id` 改变时，不算内容变更。CRLF 等换行差异按字节算作变更，`compare_wechat.py` 不做换行归一化。

需要合并时，先备份旧笔记，把新来源另存为审核副本，在保留批注的前提下由你确认合并；没有自动合并器。对已有笔记再次运行 `import_wechat.py` 只会显示 `Already exists`，不会把新正文同步进去。`compare_wechat.py` 有离线回归测试，覆盖未改、新正文、批注、元数据变更和拒绝损坏基线。

[公众号问题索引](/zh/faq/wechat) · [全文和摘要](/zh/faq/wechat-article-full-text)