magicmd 0.1.0__tar.gz

magicmd-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Run tests
+        run: uv run pytest -q
+
+      - name: Run ruff
+        run: uv run ruff check .
+
+      - name: Build package
+        run: uv build

magicmd-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.DS_Store
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+output/
+debug.html
+.magicmd.toml

magicmd-0.1.0/.magicmd.example.toml

@@ -0,0 +1,41 @@
+[output]
+directory = "output"
+overwrite = false
+save_debug_html = "on_failure"
+
+[markdown]
+template = "default"
+front_matter = "yaml"
+include_source_block = true
+heading_offset = 0
+
+[images]
+download = true
+directory = "images"
+filename_pattern = "img_{index:03d}.{ext}"
+concurrency = 5
+
+[fetch]
+timeout_seconds = 20
+browser_timeout_seconds = 15
+browser_attempts = 2
+user_agent = "default"
+
+[platforms.wechat]
+enabled = true
+browser = "camoufox"
+wait_selector = "#js_content"
+
+[platforms.juejin]
+enabled = true
+browser = "camoufox"
+wait_selector = "article"
+
+[platforms.csdn]
+enabled = true
+browser = "camoufox"
+wait_selector = "#content_views"
+
+[platforms.generic]
+enabled = true
+browser = "http"

magicmd-0.1.0/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+## v0.1.0 - 2026-06-06
+
+### 中文
+
+MagicMD v0.1.0 固化为可用的独立 CLI 基线，重点覆盖公开文章链接到 Markdown 内容包的转换流程。
+
+- 支持单篇 URL 转换和批量 URL 转换。
+- 支持微信公众号、掘金、CSDN 和通用公开文章页面。
+- 微信公众号解析已覆盖视频占位与本地下载、图片懒加载、动图占位过滤、富文本加粗清洗、非代码 `pre` 文本、块级链接边界、推荐阅读区等真实样例问题。
+- 掘金解析已覆盖真实首页样本和复杂技术文章样本，包含图片下载、外链还原、代码块保留和标题层级归一化。
+- CSDN 解析已覆盖 10 篇复杂真实样本，并人工确认代码块错位、孤立数字、Mermaid/SVG 图、站内目录死链和代码控件噪声等问题。
+- 输出 `article.md`、`metadata.json`、`extraction-report.json` 和本地媒体目录。
+- 平台注册表集中管理 URL 匹配、默认抓取方式、等待选择器和解析器入口，便于后续扩展新站点。
+- 浏览器抓取配置已真实生效，支持通过配置控制 Camoufox 等待超时和最大尝试次数。
+- 平台通用转换逻辑已从 `platforms/base.py` 拆分到 `platforms/shared/`，并保留 `base.py` 兼容入口，降低后续维护成本。
+- 平台测试已按 WeChat、Juejin、CSDN 和 Generic 拆分，便于单站点回归和定位问题。
+- 批量转换后自动生成 `batch-report.json` 和 `batch-report.md`，用于快速定位失败链接、解析 warning 和 Markdown 质量疑点。
+- 批量报告补充 `platform`、`fetcher`、`stage`、`elapsed_ms`、`max_attempts` 和 `retry_enabled` 等诊断字段，方便定位失败阶段和抓取上下文。
+- 批量命令新增 `--skip-existing` 和 `--overwrite`，支持重复跑回归集时跳过已有内容包，或显式覆盖同名输出包。
+- 浏览器抓取层会对瞬时 Camoufox/Playwright 失败自动重试一次，降低批量转换中的偶发中断。
+- `magicmd doctor` 已升级为环境诊断命令，可检查 Python 版本、MagicMD 版本、配置解析、输出目录可写性、Camoufox 可用性和平台默认抓取方式。
+- 根命令新增 `--version`，方便安装后快速确认当前 CLI 版本。
+- 建立微信公众号回归样本清单：`tests/fixtures/wechat_regression_manifest.json`。
+- 建立跨站点验证清单：`tests/fixtures/site_validation_manifest.json`。
+- 发布前构建检查通过：`uv build`、wheel/sdist 内容检查、临时 wheel 安装 smoke test 和 `twine check` 均已验证。
+
+### English
+
+MagicMD v0.1.0 is the first usable standalone CLI baseline for converting public article URLs into Markdown content packages.
+
+- Supports single URL conversion and batch URL conversion.
+- Supports WeChat public account articles, Juejin, CSDN, and generic public article pages.
+- The WeChat parser covers real-world formatting issues around video placeholders and local downloads, lazy images, decorative GIF filtering, rich-text bold cleanup, non-code `pre` text, block-link boundaries, and recommendation sections.
+- The Juejin parser has been validated against live homepage samples and complex technical articles, covering image download, external-link restoration, code blocks, and heading-depth normalization.
+- The CSDN parser has been validated against ten complex live samples, with manual review for code-block collisions, stray numeric markers, Mermaid/SVG diagrams, generated table-of-contents links, and code-widget noise.
+- Outputs `article.md`, `metadata.json`, `extraction-report.json`, and local media directories.
+- Centralizes URL matching, default fetch mode, wait selectors, and parser entrypoints in a platform registry to make new-site support easier to add.
+- Browser fetch configuration is now effective, allowing Camoufox wait timeouts and maximum attempts to be controlled from config.
+- Shared platform conversion logic has been split from `platforms/base.py` into `platforms/shared/`, while `base.py` remains as a compatibility entrypoint.
+- Platform tests are now split by WeChat, Juejin, CSDN, and Generic coverage to make site-specific regression easier.
+- Batch conversion now generates `batch-report.json` and `batch-report.md` for failed URLs, extraction warnings, and Markdown quality signals.
+- Batch reports now include diagnostic fields such as `platform`, `fetcher`, `stage`, `elapsed_ms`, `max_attempts`, and `retry_enabled` to make failures easier to locate.
+- The batch command now supports `--skip-existing` and `--overwrite` for repeated regression runs and explicit output replacement.
+- Browser fetching now retries transient Camoufox/Playwright failures once, reducing intermittent interruptions during batch conversion.
+- `magicmd doctor` is now a real runtime diagnostic command that checks Python version, MagicMD version, config parsing, output writability, Camoufox availability, and platform defaults.
+- Adds a root `--version` option so installed CLI environments can quickly confirm the active MagicMD version.
+- Adds the WeChat regression corpus manifest: `tests/fixtures/wechat_regression_manifest.json`.
+- Adds the cross-site validation manifest: `tests/fixtures/site_validation_manifest.json`.
+- Pre-release build checks passed: `uv build`, wheel/sdist content inspection, temporary wheel-install smoke tests, and `twine check` have all been verified.

magicmd-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MagicMD Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

magicmd-0.1.0/PKG-INFO

@@ -0,0 +1,315 @@
+Metadata-Version: 2.4
+Name: magicmd
+Version: 0.1.0
+Summary: Convert public article links into configurable Markdown packages.
+Author: MagicMD Contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: article,crawler,juejin,markdown,wechat
+Requires-Python: >=3.11
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: camoufox[geoip]>=0.4
+Requires-Dist: chardet>=5.2
+Requires-Dist: httpx>=0.27
+Requires-Dist: markdownify>=0.13
+Requires-Dist: pydantic>=2.8
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# MagicMD
+
+中文 | [English](./README_EN.md)
+
+把散落在网页里的好文章，变成你仓库里的 Markdown。
+
+MagicMD 是一个面向公开文章链接的 Markdown 转换工具。你给它一条 URL，或者一整个 URL 列表，它把文章正文、图片、来源信息和转换报告整理成一个可长期保存的内容包。
+
+```bash
+magicmd "https://mp.weixin.qq.com/s/example"
+magicmd batch urls.txt -o output/
+```
+
+输出不是一段临时文本，而是一份可以直接进入内容工作流的目录：
+
+```text
+output/article-title/
+├── article.md
+├── metadata.json
+├── extraction-report.json
+└── images/
+    ├── img_001.png
+    └── img_002.png
+```
+
+MagicMD 可以当 CLI 用，也可以作为 Agent Skill 使用。人负责给链接，工具负责落盘；Agent 负责批量整理时，也走同一套规则。
+
+## 适合做什么
+
+- 把微信公众号文章保存为 Markdown。
+- 把掘金、CSDN 技术文章沉淀到本地知识库。
+- 把公开文章批量整理到 GitHub、Hugo、Docusaurus、HaoGit 或自己的站点。
+- 给 Agent 一个稳定的“文章链接转 Markdown”能力，而不是每次重新写提示词。
+
+MagicMD 不是浏览器收藏夹，也不是通用爬虫框架。它的目标更窄：**把公开文章页面尽量干净、可追踪、可复用地转成 Markdown 内容包。**
+
+## 和同类工具有什么不同
+
+很多工具可以把网页或文件转成 Markdown。MagicMD 更关心另一个问题：**中文内容平台里的文章，怎么稳定变成能长期维护的 Markdown。**
+
+| 类型 | 常见特点 | MagicMD 的差异 |
+| --- | --- | --- |
+| 通用网页转 Markdown 工具 | 更适合标准网页、文档页、英文站点或 LLM 输入清洗。 | MagicMD 针对微信公众号、掘金、CSDN 做平台适配，重点处理中文内容平台常见的富文本、跳转链接、代码控件和编辑器噪声。 |
+| 微信文章转换脚本 | 往往能抓正文和图片，但配置、批量、报告和多平台扩展有限。 | MagicMD 不只转微信，还保留 `metadata.json`、`extraction-report.json`、批量报告和可配置 Markdown 输出，方便后续发布或自动化处理。 |
+| 爬虫框架 | 能力强，但通常需要自己写解析逻辑、清洗规则和输出结构。 | MagicMD 直接给文章采集场景一个可用 CLI：链接进去，内容包落盘。 |
+| 手动复制到 Markdown | 可控，但慢，图片、链接、代码块和来源信息很容易丢。 | MagicMD 自动处理图片本地化、标题层级、代码块、链接、来源信息和失败 warning。 |
+
+MagicMD 的优势不是“抓全网”，而是把中文技术内容归档这件事做细：微信视频会提取链接并尝试下载；掘金外链会尽量还原真实目标地址；CSDN 代码块会清理复制按钮、行号和编辑器控件；批量转换会留下报告，方便你知道哪篇文章需要人工复核。
+
+## 安装
+
+当前 v0.1 推荐从源码安装或开发安装。Clone 仓库后运行：
+
+```bash
+cd magicmd
+uv sync --extra dev
+uv run magicmd doctor
+```
+
+安装成全局命令后，可以直接运行 `magicmd`：
+
+```bash
+uv tool install --editable .
+magicmd doctor
+```
+
+如果你习惯 `pipx`：
+
+```bash
+pipx install .
+```
+
+还没有全局安装时，把下面命令里的 `magicmd` 换成 `uv run magicmd` 即可。
+
+```bash
+uv run magicmd batch urls.txt -o output/
+```
+
+### PyPI 和 npm
+
+MagicMD 目前还没有发布到 PyPI，所以暂时不能直接运行：
+
+```bash
+uv tool install magicmd
+```
+
+MagicMD 目前也不是 npm 包，所以暂时不支持：
+
+```bash
+npm install -g magicmd
+npx magicmd
+```
+
+npm 入口适合后续做成轻量 wrapper：用户通过 npm 安装，底层仍调用 MagicMD CLI。v0.1 先把 Python CLI 稳住，再评估这个入口。
+
+## 快速使用
+
+转换单篇文章：
+
+```bash
+magicmd "https://mp.weixin.qq.com/s/example"
+```
+
+指定输出目录：
+
+```bash
+magicmd convert "https://juejin.cn/post/example" -o output/
+```
+
+批量转换：
+
+```bash
+magicmd batch urls.txt -o output/
+```
+
+`urls.txt` 一行一个链接：
+
+```text
+https://mp.weixin.qq.com/s/example
+https://juejin.cn/post/example
+https://blog.csdn.net/user/article/details/123
+```
+
+重复跑同一批链接时，跳过已经生成过的内容包：
+
+```bash
+magicmd batch urls.txt -o output/ --skip-existing
+```
+
+确认要重新生成时，覆盖同名输出包：
+
+```bash
+magicmd batch urls.txt -o output/ --overwrite
+```
+
+只要正文，不下载图片：
+
+```bash
+magicmd convert "https://blog.csdn.net/user/article/details/123" --no-images
+```
+
+## 支持站点
+
+| 站点 | 状态 | 默认抓取 | 说明 |
+| --- | --- | --- | --- |
+| 微信公众号 `mp.weixin.qq.com` | 稳定主目标 | `camoufox` | v0.1 最主要的验证对象，已做多轮真实样本格式修复。 |
+| 掘金 `juejin.cn` | 实验支持 | `camoufox` | 已验证首页样本和复杂技术文章，重点看图片、代码块、外链和标题层级。 |
+| CSDN `blog.csdn.net` | 实验支持 | `camoufox` | 已人工检查 10 篇复杂样本，重点修过代码块、Mermaid/SVG、目录链接和控件噪声。 |
+| 通用网页 | 尽力支持 | `http` | 对标准 `article`、`main` 或 Open Graph 元信息页面做基础提取。 |
+
+更多站点说明见 [docs/supported-sites.md](./docs/supported-sites.md)。
+
+## MagicMD 会生成什么
+
+单篇文章会生成一个内容包：
+
+```text
+output/
+└── article-title/
+    ├── article.md              # Markdown 正文
+    ├── metadata.json           # 标题、作者、时间、来源、hash 等
+    ├── extraction-report.json  # 抓取、解析、媒体和 warning
+    └── images/                 # 下载后的本地图片
+```
+
+批量转换会额外生成：
+
+```text
+output/
+├── batch-report.json           # 适合程序读取
+└── batch-report.md             # 适合人工检查
+```
+
+默认的 `article.md` 类似这样：
+
+```md
+---
+title: "Example Article"
+author: "Example Author"
+platform: "wechat"
+source_url: "https://mp.weixin.qq.com/s/example"
+---
+
+# Example Article
+
+> Source: wechat
+> Author: Example Author
+> Original: https://mp.weixin.qq.com/s/example
+
+正文内容...
+```
+
+## CLI 和 Skill
+
+MagicMD 有两个入口。
+
+第一个是给人用的 CLI：
+
+```bash
+magicmd batch urls.txt -o output/
+```
+
+第二个是给 Agent 用的 [SKILL.md](./SKILL.md)。Skill 把“什么时候使用 MagicMD、怎么运行、检查哪些文件、遇到失败看什么报告”写成固定流程。这样 Agent 不需要每次猜命令，也不会把登录页、付费墙、验证码页面当成正常文章处理。
+
+如果你未来要把 MagicMD 接入 HaoGit，建议让 Agent 先调用 Skill 完成采集和转换，再把 `article.md`、`metadata.json` 和图片交给发布流程。
+
+## 配置
+
+生成配置文件：
+
+```bash
+magicmd config init
+```
+
+配置文件示例见 [.magicmd.example.toml](./.magicmd.example.toml)。
+
+常用配置：
+
+```toml
+[output]
+directory = "output"
+overwrite = false
+save_debug_html = "on_failure"
+
+[markdown]
+template = "default"
+front_matter = "yaml"
+include_source_block = true
+heading_offset = 0
+
+[images]
+download = true
+directory = "images"
+filename_pattern = "img_{index:03d}.{ext}"
+
+[fetch]
+timeout_seconds = 20
+browser_timeout_seconds = 15
+browser_attempts = 2
+```
+
+常见选项：
+
+| 配置 | 说明 |
+| --- | --- |
+| `output.directory` | 默认输出目录。 |
+| `output.overwrite` | 是否覆盖同名内容包。 |
+| `output.save_debug_html` | `always`、`on_failure`、`never`，控制是否保存 `debug.html`。 |
+| `markdown.front_matter` | `yaml` 或 `none`。 |
+| `markdown.template` | `default` 或 `clean`。 |
+| `markdown.heading_offset` | 统一调整 Markdown 标题层级。 |
+| `images.download` | 是否下载图片。 |
+| `fetch.browser_attempts` | 浏览器模式失败后的总尝试次数。 |
+| `platforms.<name>.browser` | 使用 `http` 或 `camoufox`。 |
+| `platforms.<name>.wait_selector` | 浏览器抓取时等待的选择器。 |
+
+检查环境：
+
+```bash
+magicmd doctor
+```
+
+`doctor` 会检查 Python 版本、MagicMD 版本、配置文件解析、输出目录可写性、Camoufox 是否可用，以及各平台默认抓取方式。
+
+## 使用前知道
+
+MagicMD 只处理公开文章页面。它不会绕过登录、付费墙、私有内容、验证码或平台访问限制。
+
+如果遇到 403、验证码、登录限制、视频防盗链或动态资源失效，MagicMD 会尽量保留已经能提取的内容，并在报告里记录 warning 或失败原因。
+
+如果某个平台的页面结构变化导致转换效果下降，建议先保留输出目录里的 `extraction-report.json`，再用同一链接复现问题。真实样本记录放在 [docs/wechat-regression-corpus.md](./docs/wechat-regression-corpus.md) 和 [tests/fixtures/site_validation_manifest.json](./tests/fixtures/site_validation_manifest.json)，不放在首页展开。
+
+## 开发文档
+
+- [docs/development.md](./docs/development.md)：项目结构、核心模块、转换流程和验证命令。
+- [docs/supported-sites.md](./docs/supported-sites.md)：当前支持站点和注意事项。
+- [docs/wechat-regression-corpus.md](./docs/wechat-regression-corpus.md)：微信公众号真实样本回归说明。
+- [docs/MagicMD-v0.1-design.md](./docs/MagicMD-v0.1-design.md)：v0.1 设计说明。
+
+## 接下来
+
+- 发布到 PyPI，支持 `uv tool install magicmd`。
+- 评估 npm wrapper，支持 `npm install -g magicmd` 或 `npx magicmd`。
+- 增加 Markdown 模板系统。
+- 增加 GitHub 发布能力。
+- 增加 HaoGit 导入能力。
+- 扩充微信公众号、掘金、CSDN 真实样本回归集。
+- 增加更多站点适配器。
+
+## License
+
+[MIT](./LICENSE)