# Clip2MD Desktop Tools

[中文](#中文) | [English](#english)

## 中文

### Clip2MD 是什么

[Clip2MD 官网](https://clip2.md)把网页、微信分享、图片和文档等内容整理为可检索的 Markdown 知识。你可以从浏览器插件、微信服务号和企业微信剪藏助手提交内容，在网页或小程序查看任务，再同步到 Obsidian。

```text
浏览器插件 / 微信分享 / 文件上传
               ↓
Clip2MD 云端：提取内容、生成智能笔记、管理任务
               ↓
网页 / 小程序管理 → Clip2MD 主插件 → Obsidian 知识库
                                      ↑
                       本地剪藏扩展：正文、图片、媒体、字幕、评论
```

| 入口 | 用途 |
| --- | --- |
| [官网](https://clip2.md) | 了解产品、网页剪藏及任务管理 |
| [微信服务号与企业微信助手](https://clip2.md/mobile#mobile-guide) | 关注服务号，按欢迎指引添加助手，向助手发送支持的分享内容 |
| [打开小程序](https://clip2.md/mobile#miniapp-launch) | 在微信内启动或扫码，查看任务、账号和设置 |
| [用户群](https://clip2.md/mobile#community) | 产品交流与反馈；剪藏内容应发送给助手 |

| 关注 Clip2MD 服务号 | 加入用户群 |
| --- | --- |
| ![Clip2MD 服务号二维码](https://static.clip2md.cn/wechat/service-account-follow.jpg) | ![Clip2MD 用户群二维码](https://static.clip2md.cn/wecom/contact_group_qr.png) |

二维码无法显示或失效时，请打开对应的[官网微信入口](https://clip2.md/mobile)。小程序入口使用官网启动页，不是插件绑定码；GitHub 页面无需执行微信脚本。

### 两个插件与分发渠道

- [Clip2MD 主插件](https://github.com/clip2md/clip2md-plugin)：ID `clipmd`，支持桌面和移动端，负责账号绑定、云端任务同步、模板、图片本地化与博主订阅归档。
- [本地剪藏扩展](https://github.com/clip2md/clip2md-desktop-tools)：ID `clipmd-desktop-tools`，仅桌面端，依赖主插件，补充原站正文、来源属性、音视频、字幕、图片和评论。原站权限与工具条件会影响可用能力。
- 市场渠道分别安装两个插件，安装和更新由 Obsidian 管理；两个入口共用本地剪藏设置和状态。手机端仅使用主插件，不显示本地剪藏入口。
- 网站渠道将桌面能力整合进一个主插件，桌面使用相同功能界面；手机保留云端同步。网站整合版无需再启用独立扩展。

### 知识星球本地剪藏

市场版扩展和网站整合版共用知识星球适配器，仅处理用户提交的单条主题，不批量采集星球。内置浏览器扫码登录，收到 `/v3/users/self` 的账号确认后自动保存 Cookie/localStorage 到本机 SecretStorage，并恢复等待任务；仍可手动检查登录状态。

知识星球提供来源属性、正文图文、封面／原图、文件附件、视频／音频、字幕与本地转写、评论七项开关。新增文件、音视频和字幕能力升级后默认关闭，登录不会自动开启。普通主题、问答、作业、作业答案及关联长文章按原站 ID 核对，预览和无阅读权限不算完整正文。

普通文件按原文件名显示本地链接；音视频附件归音视频开关，避免与普通文件重复下载。只读取目标主题及长文章中实际加载的播放器资源；无法取得下载原件会显示缺失。多项媒体独立保存、独立转写并保留标题，绝不作为同一作品分段拼接。字幕依次尝试原站关联字幕、内嵌字幕和本机 Whisper。评论按配置数量分页、去重，文件中说明实际覆盖范围，不承诺未返回的回复。

成功素材和摘要写入本机资料目录、任务资源检查点；部分失败会显示原因且任务保持可重试，取消／重启后复用已成功且未被修改的文件。临时地址过期只重新获取一次。文件型及纯媒体主题无需文字正文。`local_assets` 包含普通附件，`local_media` 包含音视频，`local_gallery` 包含图片，字幕沿用转写变量。

真实账号验收和当前限制见 [知识星球调研与验收记录](https://static.clip2md.cn/docs/product-guide-for-ai-agents.md)。

### 通用网页正文剪藏

市场版扩展和网站整合版均使用 Defuddle 提取通用网页正文图文及标题、作者、发布时间。公开网页无需添加域名或登录；仅正文被登录拦截时弹出原站窗口，完成后点击“我已登录，保存登录态”，域名自动加入设置并继续任务。也可在设置点击“添加并登录”主动保存登录态。取消或登录后仍无法访问时暂停该域名任务，可手动重试，不影响其他网页。

通用网页只提供正文图文、基础来源属性和正文图片，不采集额外封面、互动数据、音视频、评论或字幕。凭据按域名隔离，仅存储于本机 SecretStorage。升级会停用旧的额外采集任务并保留已有素材。

### 淘宝/天猫商品剪藏

淘宝与天猫共用隔离的本机登录会话。首次在原站窗口人工登录后，扩展检测有效买家登录态，自动保存并关闭窗口；也可手动检查并保存。已有会话遇到滑块或验证码时交由用户完成，旧 Cookie 未变化不会提前关闭验证窗口。

支持 HTTPS 商品详情链接和 `e.tb.cn`、`m.tb.cn` 分享短链接，保存标题、当前显示价格、店铺、已选规格、参数、详情图文及图片。分享地址只解析可信商品目标，不执行分享页脚本。图片懒加载有次数及时间上限，到时读取已渲染内容，缺标题或访问受限时明确失败。价格以当前页面和规格为准，不遍历 SKU、不批量采集评论。

云端失败后，已开启自动本地解析且本机就绪时，可下发本地采集并通过主插件提交云端生成；原文中的本地图片会先上传至 TOS，缺图时暂停提交；Cookie 和原始页面不上传。使用方式与限制见[本地剪藏功能总览](https://static.clip2md.cn/docs/product-guide-for-ai-agents.md#淘宝天猫详情页)。

### 账号、收费和额度

两个插件免费安装，无独立插件费用。云端功能需要 Clip2MD 账号或有效 API Key、网络连接。免费账号有额度和内容类型限制，完整云端权益需要付费：Plus / Pro 会员提供相应权益，也可购买永久额度。收藏导入创建云端任务、本地失败恢复提交按账号规则使用额度；博主订阅需要有效 Pro 并另扣永久额度。具体价格、权益及扣额规则见[方案与价格](https://clip2.md/pricing)，以当前账号和功能页为准。

### 隐私、网络与文件访问

- 主插件通过 `https://api.clip2md.cn/api/v1` 绑定设备、验证凭据、获取任务与图片、同步回执、提交收藏链接、协调失败恢复及用户反馈。官网入口为 `https://clip2.md`；使用说明与公开资源来自 `https://static.clip2md.cn`。
- 普通同步把云端内容写入知识库，更新时保护用户批注。普通本地素材补充访问用户选择的原站、登录页面、接口及媒体 CDN，将结果保存在本地。短链接可能重定向到原站。
- 在 Web 端开启自动本地解析、且本机扩展已启用并授权、工具就绪时，云端失败恢复会上传来源标题、提取或转写的 Markdown、提取方式及任务版本，用于云端生成智能笔记。版本、执行实例、可用/忙碌状态用于任务分配和恢复。原始媒体文件、原站 Cookie 不上传；关闭 Web 自动本地解析或本机扩展可停止后续自动处理。
- 收藏清单及导入进度保存在本地；用户点击导入后，主插件提交选中的作品链接。它不上传原站 Cookie 或原始页面响应。
- 云端 API Key 和原站授权保存在本机 Obsidian SecretStorage，扩展不接收云端 API Key。普通配置保留在 `<configDir>/clip2md/settings/`，同步进度按设备隔离。历史版本遗留凭据应在各设备迁移后清理。
- 本地工具从用户安装路径读取并运行，工具和固定 Whisper 模型可位于 Vault 外的系统 PATH 或本机 `Clip2MD/tools/v1/<平台-架构>/`。传给 yt-dlp 的临时 Cookie 文件位于 Vault 外的系统临时目录，权限为 0600，正常结束会删除。强制退出后可能残留，重新启用时清理可确认归属且进程已退出的缓存。
- 素材位于知识库内配置的目录；缓存、转写检查点及插件配置目录可能被用户的同步工具同步。卸载插件不会清除保留的偏好或素材；设置中的显式清除操作仅清理对应配置。
- 插件没有客户端遥测或广告。诊断日志默认保留 72 小时、每插件最多 10 MiB，不记录凭据或正文。反馈仅在用户提交时上传，可预览或取消诊断附件；没有后台日志上传。导出报告、失败附件缓存保存在知识库配置目录。
- 服务端账号、任务内容和反馈数据处理见[隐私政策](https://clip2.md/privacy)。请勿在 Issue、日志或截图中公开 API Key、Cookie 或私人内容。

### 使用限制

需要 Obsidian 1.13.1 或更高版本。本地能力主要面向 macOS 与 Windows x64；真实站点、账号权限和跨平台宿主需分别验收。完整媒体可能受原站权限、DRM 或播放方式限制，不能取得时明确失败。评论是原站可获取的样本，不承诺全量。市场版不安装或更新自身、另一个插件或外部依赖。
### 安装与使用

1. 在 Obsidian 社区插件中安装并启用 **Clip2MD** 和 **Clip2MD Desktop Tools**。缺少主插件时，扩展设置提供“安装 Clip2MD 主插件”按钮；已安装时可打开社区插件设置启用。
2. 在主插件中绑定账号，再从任一插件设置打开“本地剪藏扩展”。开启后按平台登录并选择补充能力；默认关闭，不自动扫描历史笔记。历史笔记可通过“为已有剪藏补充素材”处理。
3. 市场版由用户手动安装 FFmpeg、yt-dlp、whisper-cli 及固定多语言 base 模型，再点击工具检查。设置可复制带固定地址、SHA-256 和检查要求的 Agent 修复说明；[完整使用说明](https://static.clip2md.cn/docs/product-guide-for-ai-agents.md)。网站版自动准备工具。
4. 配置资料目录、下载与评论上限、平台开关，使用队列停止或重试。B站、小红书和抖音支持用户主动读取收藏并选择导入；提交前检查云端额度和重复任务，可暂停和恢复。
5. 原站授权按平台、Vault 和绑定作用域隔离，可随时撤销。关闭扩展会停止任务；通过主插件统一清理桌面模板变量，同时保留工具、授权和历史素材。

手动安装时，从同一个 Release 下载三个文件放入 `<configDir>/plugins/clipmd-desktop-tools/`：`main.js`、`manifest.json`、`styles.css`，然后启用插件。连接状态会区分未安装、等待连接、协议不兼容和未绑定；按提示安装、启用、更新或绑定。

### 开发、验证与反馈

使用 Node.js 24（最低 20.19），运行 `npm ci && npm run verify`，包括类型检查、测试、Lint、构建和产物验证。产物为 `dist/main.js`, `dist/manifest.json`, `dist/styles.css`。源码不提交构建文件、凭据或运行数据。Release tag 必须与 manifest 版本完全一致，并上传三个安装文件。版本发布与市场审核是独立步骤；构建通过不代表已经上架。

许可证：[MIT](LICENSE)，[第三方许可](THIRD_PARTY_NOTICES.md)。通过[GitHub Issues](https://github.com/clip2md/clip2md-desktop-tools/issues)反馈问题，或在插件内预览并提交诊断。

## English

### What is Clip2MD?

[Clip2MD](https://clip2.md) turns web pages, WeChat shares, images and documents into searchable Markdown knowledge. Capture through the browser extension, the WeChat service account / WeCom assistant, or file uploads. The cloud extracts content and generates notes; the website and mini program manage tasks; the main Obsidian plugin syncs results to your vault. The desktop companion supplements notes with locally extracted text, metadata, images, media, subtitles and comments.

| Entry | Purpose |
| --- | --- |
| [Website](https://clip2.md) | Product overview, web clipping and task management |
| [WeChat service account / WeCom assistant](https://clip2.md/mobile#mobile-guide) | Follow the service account, add the assistant using its welcome instructions, and send supported shares to the assistant |
| [Open the mini program](https://clip2.md/mobile#miniapp-launch) | Launch inside WeChat or scan the code to manage tasks, your account and settings |
| [User community](https://clip2.md/mobile#community) | Discussion and feedback; send clipping content to the assistant instead |

| Follow the service account | Join the community |
| --- | --- |
| ![Clip2MD service account QR code](https://static.clip2md.cn/wechat/service-account-follow.jpg) | ![Clip2MD community QR code](https://static.clip2md.cn/wecom/contact_group_qr.png) |

If an image is unavailable or expires, use the [official WeChat guide](https://clip2.md/mobile). The mini-program link opens the official launch page, not a plugin binding code; GitHub does not need to execute WeChat scripts.

### Plugins and distribution channels

- [Clip2MD main plugin](https://github.com/clip2md/clip2md-plugin), ID `clipmd`: desktop and mobile cloud synchronization, account binding, templates, local images and creator subscription archives.
- [Local clipping extension](https://github.com/clip2md/clip2md-desktop-tools), ID `clipmd-desktop-tools`: desktop only, requires the main plugin, and supplements notes with source text, metadata, media, subtitles, images and comments. Source permissions and local tools determine available capabilities.
- Community-market users install and update the two plugins separately through Obsidian. Their local clipping settings share the same UI and state. Mobile uses only the main plugin and has no local clipping entries.
- Website downloads integrate the desktop runtime into one main plugin with the same feature UI. Mobile retains cloud sync; website users do not also enable the separate companion.

### Account, payment and quotas

Both plugins are free to install and have no separate plugin fee. Cloud features require a Clip2MD account or valid API Key and an internet connection. Free accounts have usage and content-type limits. Full cloud access requires paid entitlements: Plus/Pro plans provide additional benefits, and permanent credits can be purchased. Favorite imports that create cloud tasks and local-recovery submissions use account quotas. Creator subscriptions require active Pro and permanent credits. See [plans and pricing](https://clip2.md/pricing); current account entitlements and feature pages determine charges.

### Privacy, networking and file access

- The main plugin uses `https://api.clip2md.cn/api/v1` for device binding, authentication, tasks/images, sync acknowledgements, selected favorite links, recovery coordination and user-submitted feedback. Website links use `https://clip2.md`; public documentation and assets use `https://static.clip2md.cn`.
- Normal synchronization writes cloud content to the vault and protects user annotations. Local supplementation accesses selected source sites, login pages, APIs and media CDNs and saves results locally. Short links may redirect to the source site.
- When automatic local parsing is enabled on the website and the authorized desktop extension is enabled and ready, recovery uploads source titles, extracted/transcribed Markdown, extraction metadata and task versions for cloud note generation. Version, instance and readiness/busy status coordinate jobs. Original media files and source cookies are not uploaded. Disable website automatic local parsing or the local extension to stop further automatic processing.
- Favorite lists and progress stay local. Importing sends selected work URLs through the main plugin, without source cookies or raw page responses.
- API Keys and site authorization use device-local Obsidian SecretStorage. The companion never receives the cloud API Key. Preferences remain in `<configDir>/clip2md/settings/`; sync progress is device-specific. Remove legacy credentials after migrating every device.
- The extension reads and executes user-installed tools outside the vault, from system PATH or the machine-local `Clip2MD/tools/v1/<platform-architecture>/` directory, which can also contain the fixed Whisper model. Temporary yt-dlp cookie files use a private system temporary directory outside the vault with 0600 permissions and are removed after normal completion. Forced termination can leave files; startup cleans only attributable caches whose owning process has exited.
- Materials are saved inside the vault. Caches, transcription checkpoints and configuration files may be copied by your vault-sync service. Uninstalling retains preferences and materials; explicit settings-clear actions remove only the corresponding configuration.
- No client-side telemetry or advertisements. Local diagnostics retain up to 72 hours / 10 MiB per plugin and exclude credentials and content. Feedback uploads only when submitted by the user, with preview and an option to omit diagnostic attachments. Reports and pending attachment caches remain in the vault configuration directory; logs are not uploaded in the background.
- See the [privacy policy](https://clip2.md/privacy) for server-side handling of account, task and feedback data. Never post API Keys, cookies or private content in issues, logs or screenshots.

### Requirements and limitations

Requires Obsidian 1.13.1 or later. Local capabilities primarily target macOS and Windows x64; live sites, account permissions and platforms need separate acceptance testing. Source permissions, DRM or playback formats may prevent media downloads; failures are reported explicitly. Comments are available samples, not guaranteed complete datasets. Market builds never install or update themselves, another plugin or external dependencies.
### Installation and usage

1. Install and enable **Clip2MD** and **Clip2MD Desktop Tools** in Obsidian Community plugins. The extension provides an install button for a missing main plugin and access to community settings for enabling it.
2. Bind your account in the main plugin. Open local clipping settings from either plugin, enable processing, authorize source sites and select capabilities. Processing defaults to off and does not scan historical notes automatically; use the supplement-existing-note command for old notes.
3. Market users manually install FFmpeg, yt-dlp, whisper-cli and the fixed multilingual base model, then run the tool check. Settings can copy repair instructions including fixed download URLs, SHA-256 and capability checks. See the [full guide](https://static.clip2md.cn/docs/product-guide-for-ai-agents.md). Website builds prepare tools automatically.
4. Configure material folders, media/comment limits and platform switches; stop or retry queue items. Bilibili, Xiaohongshu and Douyin favorites can be read on request and selected for import, with cloud quota/duplicate checks and pause/resume.
5. Site authorization is isolated by platform, vault and binding and can be revoked. Disabling stops work and uses the main plugin to clean desktop template variables while retaining tools, authorization and existing materials.

For manual installation, place `main.js`, `manifest.json` and `styles.css` from one Release in `<configDir>/plugins/clipmd-desktop-tools/`, then enable it. Connection guidance distinguishes missing, waiting, incompatible and unbound states and directs you to install, enable, update or bind.

### Development, verification and support

Use Node.js 24 (minimum 20.19) and run `npm ci && npm run verify` for type checking, tests, lint, build and artifact validation. Outputs: `dist/main.js`, `dist/manifest.json`, `dist/styles.css`. Do not commit build outputs, credentials or runtime data. Release tags must exactly match the manifest version and contain all three installation files. Publishing a Release and community review are separate steps; a successful build does not mean the plugin is listed.

License: [MIT](LICENSE), with [third-party notices](THIRD_PARTY_NOTICES.md). Report problems through [GitHub Issues](https://github.com/clip2md/clip2md-desktop-tools/issues) or preview and submit diagnostics from plugin settings.