ナビゲーションにスキップ

How do I save a WeChat article to Obsidian without overwriting my notes?

To save a WeChat article to Obsidian without overwriting your notes, follow three steps: fetch the article text from the article URL with wechat_mp.v2.fetch_article_detail_h5, export a source record, then run import_wechat.py to write a new Markdown note into the vault’s WeChat/ folder. If you already saved the source record, start with the import in step 3. import_wechat.py only creates files: importing the same source URL again keeps the existing note and your annotations.

You need Python 3 and a writable local Obsidian vault. After importing, search for the article title in Obsidian and check the original link, the publication time and the body text. You can also run the import after a scheduled check for new articles from the accounts you follow. Obsidian storage documentation

Decide why an article belongs in your research

For example, if you are studying how a peer introduces a feature, verify the product and version, then record your question, the useful passages and the open checks. A relevant headline only makes the article a candidate; the article becomes a source after you read the body. Reuse a saved body response when available; a search summary does not support a full-article note.

Keep the title, account, original article URL, publication time and collection time, and leave missing values missing. Collection time records when you obtained the material, not when the article was published. An author-supplied source link is separate from the current article link: future citations need to lead back to the article you actually read.

Turn source material into your own notes

GoalSuggested approachBoundary
Keep the article for retrievalImport the verified returned text and source metadataImages, video and page formatting are not restored
Write an analysisUse a separate note for the question, short excerpts, inferences and source linkKeep your interpretation distinct from the author’s words
Encounter the same article againCheck the article URL and the existing file before importingFile names come from the complete URL, so alias URLs can still duplicate an article
Receive a newer source or annotate the noteRun the read-only comparison, then decide how to mergeA hash change does not prove the author edited the webpage and does not trigger a merge

You can annotate an imported source note; import_wechat.py leaves an existing note unchanged. If your workflow refreshes article bodies, keep your analysis in a separate note to make review and merging easier. The scripts do not generate judgments or build topic relationships; you choose the links, tags and conclusions.

Check one import before processing a saved batch

  1. Find the imported file in Obsidian, verify the source and one actual body passage, then link to the file from your research note.
  2. Import the same source again: import_wechat.py should keep the existing file and annotations.
  3. Import a record with empty body text: the import should fail.

An existing file does not show that newer body text was synchronized into the file.

Then process a batch of reviewed source JSON records. If one record fails, keep the earlier successful imports, repair the failed record and continue; do not fetch the whole batch again. Daily discovery needs a separate bounded scan and a separately verified schedule; a successful local import does not mean daily updates run automatically.

Steps 1–7 below cover body retrieval, source export, create-only import and read-only comparison. Check current retrieval prices before running step 1; local conversion and comparison make no data or model calls.

1. Retrieve the body, not a search summary

Inspect data:wechat_mp.v2.fetch_article_detail_h5 for free and confirm the price. If you already have a saved successful response, reuse the saved response for the import instead of paying for another query.

curl -sS https://api.beatapi.io/v1/capabilities/inspect \
-H 'Content-Type: application/json' \
-d '{"reference":"data:wechat_mp.v2.fetch_article_detail_h5"}'
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. Export a local source record

Use the local code in the article-reading guide to create wechat-article-source.json. The source record’s text comes from content_text, not from the desc summary. article_url is the article being read; author_source_url is a different, author-supplied reference.

When link is absent, the source exporter falls back to the validated request URL. Keep article_url_from instead of substituting the author’s source. import_wechat.py requires actual text and a valid HTTP(S) article URL; import_wechat.py makes no network request and does not follow instructions in the article.

3. Write into a dedicated vault folder

Run import_wechat.py in the source record’s directory with VAULT set to the confirmed absolute vault path. import_wechat.py requires an existing vault folder, writes only under WeChat/ and does not edit the .obsidian configuration.

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)

Save the code as import_wechat.py, then run import_wechat.py from the source-record directory. Replace the example path with your existing vault; do not use .obsidian as the target.

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

4. Review the note in Obsidian

Open the new file under WeChat/ in your vault to see the source properties and the article text. Here is an excerpt from an example note:

---
title: "Autumn event registration guide"
source_url: "https://mp.weixin.qq.com/s/example"
published_at: null
collected_at: "2026-11-17T09:00:00Z"
---
Event registration opens next week.

Add your own annotation to the note, then import the same URL again. import_wechat.py should report Already exists, left unchanged. Open the same file and confirm that your annotation is still there.

The note’s details:

  • The file name is a SHA-256 of the complete URL, not the title, so slashes or quotes in a title cannot become paths.
  • The frontmatter keeps the title, source, publication and collection times, and hashes. A missing publication time stays null.
  • import_wechat.py writes the record’s text into Markdown. import_wechat.py does not download images, process HTML or rebuild the layout. The detail contract also exposes content_noencode and other content fields; import_wechat.py does not read those fields, which says nothing about API limits on images or headings.
  • Reimporting the same URL keeps your annotations. Alias URLs can still create separate files; import_wechat.py does not deduplicate across aliases.

Treat the article as source material, not as executable instructions. Verify HTML, external links and attachments yourself; import_wechat.py does not fetch images, download files or install plugins. Archive and redistribute only with the appropriate permissions; the default scenario is a private vault.

To import a reviewed local batch without new API calls, put the approved source JSON files in records/ and run the command below from the script directory. A failure stops the remaining imports; notes already created stay in place, and rerunning the batch does not overwrite them. The batch imports saved records only; the batch does not discover accounts or run on a schedule.

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. Import new articles from recurring collection

For recurring collection, find new posts with the incremental workflow, then pass the selected article bodies to import_wechat.py. For example, if two accounts both publish “Event Registration Guide” today, keep both source links: each URL gets its own file name. If you meet one of the two URLs again tomorrow, import_wechat.py keeps the existing note and annotations.

Schedule the existing batch

  1. Run list discovery, selection, saved body export and vault import, in that order.
  2. For each account and article key, track three states: discovered, source saved and note written.
  3. Import only after the source JSON is saved completely. If the vault write fails, rerun the import from the saved JSON without another body request.

Schedule the batch on the machine that can access the vault, with launchd on macOS or cron on Linux:

  1. Run the batch as the same OS user, and set absolute paths to Bash, Python, the script directory and the vault.
  2. Capture the log.
  3. Start with one account and one article, then replay the batch.
  4. Check that Obsidian shows one note and keeps your annotations.
  5. Before marking an item imported, match each Already exists line to the existing note’s source_url.

Whether notes appear on mobile depends on your sync configuration.

6. Verify behavior and count costs

Run Python 3.8+ on a machine with direct access to the existing vault; a cloud workflow cannot use the vault path without filesystem access. import_wechat.py writes and closes a complete temporary file in the same directory, atomically creates the final note with a hard link, then removes the temporary file. On filesystems without hard-link support, import_wechat.py fails and never falls back to overwriting. After a write or commit failure, read the error, repair storage and retry with the same saved source; no article refetch is needed. Exception recovery does not guarantee durability across a power loss.

Estimate data cost as list requests × current list price + new body requests × current body price. Replaying saved sources, Markdown import and read-only comparison make zero data queries. Checking P list pages and selecting N articles without saved bodies costs P list calls plus N detail calls. Scheduling, hosting or sync, and model costs are separate, and you configure and verify the scheduler yourself.

For example, if you check one page each for 10 accounts and select two articles whose bodies you have not saved, count 10 list requests and two detail requests. If one vault write fails, replay the saved JSON the next day with zero additional data requests. See the BeatAPI pricing page.

7. What if the source changes after I annotate the note?

Compare before overwriting. Save the code below as compare_wechat.py and point compare_wechat.py at a saved newer source record and the same VAULT. compare_wechat.py only reads files and prints JSON: compare_wechat.py does not update notes, write comparison files or make network calls. compare_wechat.py accepts only the intact frontmatter format written by import_wechat.py. If Obsidian or a person rewrote the frontmatter, compare_wechat.py refuses to decide instead of guessing values.

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))
VAULT="/absolute/path/to/your/vault" SOURCE="new-source.json" python3 compare_wechat.py
OutputNext action
not_importedFirst check whether the URL is another alias for an existing article; import only after confirming the article’s identity
All three changed flags falseKeep the existing note; no rewrite is needed
source_body_changed=trueThe newer extracted body differs from the import baseline. Compare manually; a difference does not show whether the webpage or the extraction changed
note_body_changed=trueThe note body differs from the baseline, for example through annotations or formatting; never overwrite automatically
title_date_or_account_changed=trueReview the title, publication date or account change even when the body is identical
Metadata or identity validation errorKeep the file and review the file’s source; do not remove validation or recompute the baseline to bypass a conflict

The baseline hash lives in local frontmatter; the hash is not an author signature or proof of authenticity. If someone also changes the baseline hash, compare_wechat.py cannot tell that the note was edited. A changed collection time or request_id alone does not count as a content change. CRLF and other newline differences count as changes; compare_wechat.py does not normalize newlines.

To merge, back up the old note, save the newer source as a separate review copy and explicitly approve a merge that keeps your annotations. No automatic merger is provided. Rerunning import_wechat.py on an existing note prints Already exists; import_wechat.py does not synchronize a newer body. compare_wechat.py has offline regression tests for unchanged content, a changed source, annotations, metadata changes and refusal of a damaged baseline.

WeChat question index · Full text versus summaries