Preserve valuable single Xiaohongshu (rednote) notes into an Obsidian vault to build a searchable knowledge asset. Video/image binary files do not go into the vault; only a local path is recorded in the note.
Customer-readable description
What this skill can do
Archive a single Xiaohongshu note (image-text or video) to an Obsidian vault: scrape the title, body, author, publish time, engagement data, and topic tags, and download videos/images locally; generate a lightweight Markdown note in the vault.
| What the customer wants | What the skill does | What the customer can see |
|---|---|---|
| Archive a Xiaohongshu note | Parse the share link → scrape the note detail page → extract metadata and body → write to the vault | A Markdown note with frontmatter + a terminal receipt |
| Keep the videos/images in the note | Download locally ~/Downloads/soia-pkm-clip-rednote/<note_id>/ |
Local file path (recorded in the note's media_local_path field; the vault itself does not store binaries) |
| First check whether the link can be parsed | Add --metadata-only, only write metadata + body, do not download media |
The note file will still be generated, and the media candidate direct links will be listed in the file for later manual/re-run downloads |
| Notes that have already been archived | Deduplicate by note_id in url: , skip by default |
SKIP: <路径> prompt, do not overwrite |
How the customer uses it
- Open the target note from the Xiaohongshu App → "Share" → "Copy Link" to get the full share link (must include the
xsec_tokenparameter; manually typed or truncated links cannot properly render the note content). - Send the link to the Agent and say "archive this Xiaohongshu" or directly call
python3 scripts/archive_rednote.py <URL>。 - The Agent runs the script in the vault root directory (or the specified
--vault); the script first checks for duplicates, then scrapes, downloads media, and writes Markdown. - After execution, the Agent completes the
## 摘要、topics/peopledouble links;## 我的看法is always left empty for the user.
Dependencies and installation
Install this skill (single skill):
npx skills add soia-team/soia-open-skills -g -a '*' -s soia-pkm-clip-rednote -y
| Dependency | Type | Install / configure | What to do if missing |
|---|---|---|---|
Python 3(stdlib:urllib、re、html、json) |
Hard dependency | Built into the system | Cannot run; prompt to install Python 3 |
| Obsidian vault | Hard dependency | Any existing local vault | Prompt --vault <path> or set OBSIDIAN_VAULT |
XHS_COOKIE(optional) |
Optional enhancement | Copy cookies from the browser login state and write them to a private config.yml or process environment |
Most public notes can be scraped without login; only needed when the page prompts for a login state |
Configuration conventions:
~/.config/soia-skills/soia-open-skills/soia-pkm/soia-pkm-clip-rednote/config.yml
SOIA_PKM_CLIP_REDNOTE_CONFIG_FILE=<custom-config-path>
- If private configuration is not needed (most public notes), you can skip creating
config.yml。 XHS_COOKIEcan only be placed in a privateconfig.yml、process environment, cannot be written into the repository, vault body, or logs; the script never prints its value. To prevent a configuredXHS_COOKIEfrom being tricked by malicious/forged links into sending to a third-party host, the script only accepts links under thexiaohongshu.com/xhslink.comdomain, and rejects all others.- Reference config.example.yml。
Logs and completion receipts
Every execution must let the client see the process and results. Minimum receipt format:
完成:<一句话说明本次完成了什么>。
日志摘要:
- started: <检查到的 vault / articles-dir / 是否配置 XHS_COOKIE,不打印秘密值>
- processed: <笔记 ID / 类型>
- created/updated: <笔记文件路径>
- skipped/failed: <数量和原因>
文件变化:
- <vault 内 Markdown 笔记的绝对路径>
- <本地媒体目录路径,或"未下载">
验证:
- <脚本 stdout 回执 / 人工核对点>
问题与下一步:
- <缺配置 / 媒体下载失败 / 需要客户确认;没有则写“无”>
Locating
The native Xiaohongshu App is not conducive to long-term retrieval: content only exists in the feed, notes may be deleted or set to private, and cross-device lookup is difficult. This skill fully preserves a note into Obsidian:
- Title, body (including original topic tag markers
#tag[话题]#, no secondary processing) - Author, publish time, interaction data (likes/favorites/comments/shares)
- Topic tag list
- Videos/images are downloaded locally, and only the paths are recorded in the note
- The frontmatter structure is consistent with other
clipseries in this repository, making unified MOC aggregation convenient
Prerequisites
- Obsidian vault (any structure)
- Python 3, pure stdlib (
urllib.request/re/html/json), no third-party dependencies - Vault locating priority:
- Command line
--vault <path> - Environment variable
OBSIDIAN_VAULT - Automatically discover the vault upward from the current working directory (look for
AGENTS.md/.obsidian)
- Command line
- Article directory locating priority:
- Command line
--articles-dir <subdir> - Environment variable
OBSIDIAN_ARTICLES - Fall back to the generic default
Articles; the script prints a warning to stderr, and the exit code remains 0:WARN: 未找到 articles 目录配置(--articles-dir / OBSIDIAN_ARTICLES / config.yml),已落默认 Articles/——该目录不是本 vault 的正式归档位,请确认或配置
- Command line
Note: tools such as Claude Code / Codex / Gemini CLI / opencode often execute commands in non-login shells and may not inherit the
exportfrom shell startup files. The script first loads the privateconfig.yml, then automatically discovers the vault from cwd; if the agent is already in the vault directory, just run it directly.
-
Private
config.yml(optional,do not place in the vault or an open-source skill repository):Priority:
$SOIA_PKM_CLIP_REDNOTE_CONFIG_FILE(or compatible alias$SOIA_PKM_CLIP_REDNOTE_ENV_FILE)>~/.config/soia-skills/soia-open-skills/soia-pkm/soia-pkm-clip-rednote/config.yml。Supported variable names:
OBSIDIAN_VAULT、OBSIDIAN_ARTICLES、XHS_COOKIE(optional, only needed for login-gated notes). The real value is only written in the privateconfig.ymland is not written into this file.
Fetch method: parse the note detail page's window.__INITIAL_STATE__
The Xiaohongshu note detail page is server-side rendered, and the body embeds a JS object literal of window.__INITIAL_STATE__ = {...}; . Script flow:
- Use
urllib.requestwith a real desktop Chrome UA to directly GET the share link (The complete query string must be preserved, includingxsec_token, removing the token will most likely get an incomplete/intercepted page). - Use a regex to locate the text between
window.__INITIAL_STATE__\s*=\s*and the next</script>, and remove the trailing semicolon. html.unescape()Process HTML entities, then replace bareundefinedkeywords withnull(common in JS object literals, not valid JSON).json.loads()to obtain the note state tree, recursively find the dictionary containing thenoteDetailMapkey, and retrieve bynote_idfrom{"note": {...}}。- Extract fields from
note:title/desc/type(video/normal)/user.nickname/time(millisecondstimestamp) /tagList/interactInfo(string typecounting fields, requireint()conversion) /imageList/video.media.stream.h264[0].masterUrl(direct video URL,signed URL, cannot be truncated)。
On failure, do not write a partial file; report an error and exit directly (non-zero exit code): when __INITIAL_STATE__ cannot be found, or the target note_id data cannot be found, prompt "The note may require a valid logged-in state, or the xsec_token has expired", and suggest setting XHS_COOKIE and retrying.
Trigger words
| User says | Call |
|---|---|
| "Archive this RedNote: URL" / "clip this RedNote note" / "archive this RedNote: URL" | Run in the vault root directory archive_rednote.py <URL>; when not inside the vault, add --vault <path> |
| "First see whether this link can be parsed" / "No need to download the video" | Add --metadata-only: only write metadata + body text, record candidate direct media URLs in the file, do not download |
| "Re-archive this one (content has updates)" | Add --force: overwrite the already archived same note_id, keep existing topics/people/## 摘要 |
Workflow (default archive)
- Parse the share link → use regex to try in order
/explore/([id])、/discovery/item/([id])、[?&]note_id=([id])to extractnote_id - Call script
archive_rednote.py <URL> - The script checks whether the vault has already archived it (by whether the frontmatter
url:field contains thatnote_id)- Already exists and
--forcewas not added → outputSKIP: <路径>, exit code 0 - Otherwise → fetch the note detail page, download media (unless
--metadata-only), write into the vault
- Already exists and
- AI later adds:
- 1 sentence in Chinese
## 摘要 - 1-3
topicsdouble links +peopledouble links
- 1 sentence in Chinese
- The "My thoughts" section is always left blank for the user
Media storage (not into the vault)
Videos/images are downloaded to ~/Downloads/soia-pkm-clip-rednote/<note_id>/(videos are stored as video.mp4, images are stored in images/<序号>.<扩展名>),Do not write into the vault(the vault is a git-tracked Markdown knowledge base, not suitable for storing large binary files). The note frontmatter's media_local_path field records the absolute path of this local directory;--metadata-only or when download fails, this field is left blank, and the original direct media URLs are recorded in the body text's ## 媒体候选(未下载) section, making it convenient to manually download later or rerun the script.
File naming
<YYYY-MM-DD>-rednote-<作者前 20 字>-<标题前 50 字>.md
Multiple entries with the same date, same author, and same title → add at the end -<note_id 后 6 位>。
Output frontmatter
---
tags: [视频摘抄]
source: 小红书
url: <完整分享链接,原样保留>
author: <昵称>
published_at: YYYY-MM-DD HH:mm
captured_at: YYYY-MM-DD HH:mm
language: zh
type: video / image
topics: [] # AI 填
people: [] # AI 填
media_local_path: "<本地绝对路径,未下载则为空字符串>"
content_complete: true
metrics:
likes: N
collects: N
comments: N
shares: N
---
Boundaries and exceptions
| Scenario | Handling |
|---|---|
Link is not xiaohongshu.com/xhslink.com domain |
Refuse to fetch, report an error and exit directly——the script will include XHS_COOKIE(if configured) in the HTML request headers; without host validation, the logged-in state would be sent to any domain; this validation is executed first before parsing the URL |
Share link is missing xsec_token or is a manually typed short link |
Most likely an incomplete/intercepted page will be obtained; prompt the user to get it again from the App's "Share" → "Copy Link" |
Cannot find in the page window.__INITIAL_STATE__ |
Report an error and exit, do not write a file; prompt that a logged-in state may be required or the token has expired, and suggest setting XHS_COOKIE |
| Direct video URL download 403 / timeout | The direct URL carries a time-limited signature (t= parameter); candidates (masterUrl + backupUrls, h264→h265→av1) try each one in turn; if all fail, skip the download but still write the note body + candidate direct links, and it does not count as a script failure |
interactInfo all count fields are empty/0 |
frontmatter marks "interaction data not public", not presented as a real 0 |
--metadata-only |
only write metadata + body, do not download media; candidate direct links are recorded in the body ## 媒体候选 section |
the same note_id already archived, without adding --force |
SKIP: <路径>, do not overwrite |
--force overwrite |
keep the existing topics/people/## 摘要, only update the remaining fields and the body |
| the note itself is login-restricted content | set XHS_COOKIE(only added to HTML request headers, not added to media download requests) |
command-line reference
python3 scripts/archive_rednote.py <URL>
python3 scripts/archive_rednote.py <URL> --force # 覆盖已归档(保留人工填写字段)
python3 scripts/archive_rednote.py <URL> --vault /path/to/vault # 覆盖环境变量
python3 scripts/archive_rednote.py <URL> --articles-dir <articles-subdir>
python3 scripts/archive_rednote.py <URL> --metadata-only # 只写元数据+正文,不下载媒体
verification and testing
fixed after three-lens independent adversarial review (2026-07-21): ① (security, blocking level)fetch_note_html previously, for args.url made a request directly without host validation and attached XHS_COOKIE—forging a non-Xiaohongshu link that matches the note_id regex is enough to send the user's login state to any third-party host; added validate_host(), only allowing xiaohongshu.com/xhslink.com(including subdomains, to prevent bypass via concatenation), executed first before parsing the URL. ② (correctness)clip_rednote_env.py when run standalone would print XHS_COOKIE in plaintext to stdout, contradicting its own "never prints" claim; COOKIE/TOKEN/SECRET/KEY-type fields are now redacted. ③ (correctness)--force on rerun, if the video direct link fails to download again because the signature has expired,media_local_path would be cleared, even if the file from the previous successful download is still on disk; changed so that on download failure it first checks whether a local file already exists before deciding whether to clear.
real end-to-end verification (not mock/fixture, 2026-07-21, real Xiaohongshu note):
- fully archive a real video note: video download 30MB,
fileconfirmed as a valid MP4, frontmatter like/favorite/comment/share counts consistent with the real-time numbers manually checked in the browser - rerun the same link (without adding
--force): correctlySKIP, no repeated download - CLI-layer measured security fix: forged
https://evil.example/explore/x1y2z3?note_id=x1y2z3was rejected byvalidate_hostbefore any network request was sent (exit code 1), did not reachfetch_note_html clip_rednote_env.pystandalone run: after configuring a realXHS_COOKIEoutputexport XHS_COOKIE='<redacted>', no longer leaking plaintextmedia_local_pathfallback logic: construct a scenario wherevideo.mp4already exists on disk but this download is judged failed, confirm the path is still correctly retained rather than cleared
completion receipt
delivery order: first write the files to disk, then output the receipt below, not the other way around; uncertain metadata (such as failure to parse the author nickname) must be explicitly marked "unverified" in the receipt, do not fabricate.
after executingmustoutput to the user (do not do it silently):
- what was done — a one-sentence summary of the completed work.
- file changes — list the newly created / modified vault note paths, as well as the local media directory path (or "not downloaded").
- the receipt must include the actual on-disk directory; if the
Articles/fallback was used, it must explicitly note that this directory is not the official archive location of this vault, and recommend the user configure--articles-dir、OBSIDIAN_ARTICLESor privateconfig.ymlthen relocate.
- the receipt must include the actual on-disk directory; if the
- Next steps — optional follow-up suggestions (add summary/topics/people, retry failed media downloads, etc.).