# Wechat To Obsidian

> >

- **Type:** Skill
- **Install:** `agentstack add skill-qisehong-wechat-to-obsidian-skill-wechat-to-obsidian`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [qisehong](https://agentstack.voostack.com/s/qisehong)
- **Installs:** 0
- **Category:** [Productivity](https://agentstack.voostack.com/c/productivity)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [qisehong](https://github.com/qisehong)
- **Source:** https://github.com/qisehong/wechat-to-obsidian-skill/tree/main/skills/wechat-to-obsidian

## Install

```sh
agentstack add skill-qisehong-wechat-to-obsidian-skill-wechat-to-obsidian
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Save WeChat Articles to Obsidian

Download a WeChat official account article and save it as a Markdown note in an
Obsidian vault. A single command handles download, extraction, conversion, and
cleanup. Optionally auto-syncs to a Git remote.

## Quick Start

```bash
python scripts/save_wechat.py "https://mp.weixin.qq.com/s/xxxxx"

# With Git auto-sync (commit + push after saving)
python scripts/save_wechat.py --git-sync "https://mp.weixin.qq.com/s/xxxxx"
```

The script saves to the vault inbox configured via one of these methods (highest
priority first):

1. `--vault-path` command-line argument
2. `OBSIDIAN_VAULT_INBOX` environment variable
3. `~/.wechat-to-obsidian.conf` configuration file
4. Interactive prompt on first run

See `references/configuration.md` for detailed setup instructions.

## What the Script Does

1. Downloads the article HTML via curl (iOS Safari User-Agent for WeChat compatibility)
2. Extracts title, account name, and publish date from the page metadata
3. Extracts the article body using **JsContentExtractor** (HTMLParser depth tracking — see [Why not regex?](#why-not-regex))
4. Converts the body HTML to Markdown (preserves images, links, headings, code blocks, lists)
5. Writes a `.md` file with Obsidian frontmatter to the vault inbox
6. Optionally commits and pushes to a Git remote (`--git-sync`)
7. Removes temporary files

### Why not regex?

> ⚠️ **Pitfall: regex-based `js_content` extraction fails silently on WeChat HTML.**
>
> WeChat HTML frequently has `` attributes that span multiple lines:
> ```html
>    js_underline_content"
>   id="js_content">
> ```
> A regex like `id="js_content"(.*?)` will **not** match this — the
> `id` attribute is on a different line from the tag opening. The result is
> a silently empty body with no error message.
>
> **JsContentExtractor** uses Python's `HTMLParser` to track tag nesting depth
> and reliably captures the full body regardless of attribute formatting.
> Regex is kept only as a last-resort fallback.

## Output Format

```markdown
---
title: "Article Title"
author: "Account Name"
date: 2026-05-25
source: https://mp.weixin.qq.com/s/xxxxx
tags:
  - wechat
---

# Article Title

Content in Markdown...

```

## Git Auto-Sync

When `--git-sync` is passed, the script automatically syncs to a Git remote
after saving. The vault directory must be a Git repository.

```bash
# Set the vault inbox path
export OBSIDIAN_VAULT_INBOX="$HOME/.obsidian-vault/Inbox"

# Save with auto-sync
python scripts/save_wechat.py --git-sync "https://mp.weixin.qq.com/s/xxxxx"
```

The sync workflow is: `git pull --rebase` → `git add ` → `git commit` → `git push`.
This handles cases where other devices (e.g., Obsidian on Windows/macOS) have
also pushed changes.

To make Git push work without password prompts, use a GitHub PAT in the remote URL:

```bash
cd ~/.obsidian-vault
git remote set-url origin https://username:TOKEN@github.com/username/repo.git
```

## Prerequisites

- Python 3.8 or later (standard library only, no pip installs needed)
- `curl` available on PATH
- An Obsidian vault directory writable by the current user
- (Optional) Git, for `--git-sync` mode

## Configuration

Set the vault inbox path before first use. The recommended way is an environment
variable:

```bash
# Windows PowerShell
$env:OBSIDIAN_VAULT_INBOX = "D:\MyVault\Inbox"

# macOS / Linux
export OBSIDIAN_VAULT_INBOX="$HOME/Documents/MyVault/Inbox"
```

To make it permanent, add the export line to `~/.bashrc`, `~/.zshrc`, or set it
as a system environment variable.

See `references/configuration.md` for alternative methods and platform-specific
instructions.

## Supported URL Types

| URL Pattern | Handler | Notes |
|---|---|---|
| `mp.weixin.qq.com/s/...` | Built-in parser | Full HTML→Markdown conversion |
| Other web pages | `defuddle` CLI (if installed) | Clean content extraction |
| Any URL | Plain text fallback | Title + URL saved as note |

## Limitations

- **Images**: WeChat image URLs (mmbiz.qpic.cn) are preserved as remote links;
  images may not display outside WeChat due to hotlink protection.
- **Video/audio**: Embedded media is not extracted.
- **Rich formatting**: Complex CSS layouts may be simplified.
- **Paywalled articles**: Only publicly accessible portions are captured.
- **Image extraction**: WeChat `` tags often lack direct `src` attributes;
  image URLs are scattered in JS code. The script extracts `mmbiz.qpic.cn` URLs
  via regex and maps them to `` tags in order.
- **HTML entities**: WeChat articles use extensive `&#xxxx;` numeric entities
  (e.g., `’` → `'`, `“` → `"`). The script decodes 18 common
  entities explicitly and falls back to `html.unescape()`.

## Troubleshooting

| Issue | Likely Cause | Fix |
|---|---|---|
| "下载内容过小" | WeChat anti-scraping | Retry once; the second attempt usually succeeds |
| Empty body | js_content div attributes span lines | Script uses HTMLParser; if still empty, check page source |
| Garbled title | HTML entities | `html.unescape()` is applied automatically |
| Python not found | Missing install | Install Python 3.8+ from python.org |
| curl not found | Missing tool | Install curl via your OS package manager |
| Git push fails (--git-sync) | No credentials | Set up GitHub PAT in remote URL or use SSH |
| Merge conflict (--git-sync) | Concurrent edits on other devices | Resolve manually, then re-run with `--git-sync` |

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [qisehong](https://github.com/qisehong)
- **Source:** [qisehong/wechat-to-obsidian-skill](https://github.com/qisehong/wechat-to-obsidian-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-qisehong-wechat-to-obsidian-skill-wechat-to-obsidian
- Seller: https://agentstack.voostack.com/s/qisehong
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.