x-bookmark-to-obsidian

KO | EN

gitlite — search

#javascript #llm #machine-learning #rust #linux #nodejs #java #cli #awesome-list #security #pytorch #mcp #ios #open-source

x-bookmark-to-obsidian

(★ 99)

Chrome extension that saves X bookmarks to Obsidian

x-bookmark-to-obsidian 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# X Bookmark to Obsidian

A Chrome extension + bundled macOS installer for saving X bookmarks into Obsidian.

你在 `x.com` 点击收藏后，插件会自动抓取帖子内容，并把它保存成 Markdown 笔记写入 Obsidian。

这个仓库适合想要实现下面这类工作流的人：

- 在 X 上看到值得留存的内容，顺手点收藏
- 不想再手动复制链接、贴进 Obsidian
- 希望收藏内容自动进入自己的收件箱或待整理目录
- 希望保留帖子正文、作者、发布时间、媒体链接和原帖 URL

## 项目来源说明

这个项目不是从零开始新写的。

它是基于已有仓库 [iamzifei/bookmark-is-learned](https://github.com/iamzifei/bookmark-is-learned) 继续改造出来的。

原项目更偏向“收藏内容的 AI 摘要和整理”，这次改造的重点则是把它收敛成一个更直接的工作流工具：

- 在 `x.com` 点击收藏
- 自动抓取帖子内容
- 自动保存到 Obsidian

这次新增和重构的重点主要包括：

- 把主流程改成“X 收藏即保存到 Obsidian”
- 引入基于 Native Host 的本地落盘链路
- 将单帖抓取能力内置进发行包
- 增加抓取失败时的占位笔记降级
- 增加按 `url:` 去重
- 增加自定义 Obsidian 绝对路径设置

感谢原项目提供了一个可继续演化的基础版本，也感谢原作者把早期的扩展结构、设置页和 Native Host 方案铺出来，让这次改造可以把精力集中在“X 收藏 -> Obsidian”这条链路本身。

如果你想区分哪些能力来自原项目、哪些能力是这次新增的，可以结合 Git 历史查看本轮新增提交。

## 功能概览

- 监听 `x.com` 上的收藏动作，只在确认收藏成功后触发保存
- 支持在书签页手动触发批量同步，自动估算滚动深度并向后加载更多帖子
- 使用发行包内置的抓取脚本获取帖子正文
- 抓取失败时自动降级为占位笔记，避免收藏动作丢失
- 支持图片和视频封面链接写入 Markdown
- 通过 `url:` 字段去重，避免重复创建同一条帖子笔记
- 支持在插件弹窗中自定义保存到任意 Obsidian 绝对路径

## 工作流

1. 你在 X 上点击收藏。
2. `content.js` 检测按钮状态已经变成“已收藏”。
3. `background.js` 提取帖子 URL 和最小页面信息，并转发给 Native Host。
4. Native Host 调用发行包内置抓取脚本获取完整内容。
5. 成功时生成完整 Markdown；失败时生成包含原帖链接的降级笔记。
6. 写入你配置好的 Obsidian 目录，并根据 `url:` 做去重。

## 书签页批量同步

除了“点收藏即保存”，现在也支持在 `x.com/i/bookmarks` 页面执行一次批量同步。

使用方式：

1. 打开 X 书签页 `https://x.com/i/bookmarks`
2. 点击扩展弹窗中的“同步当前书签页”
3. 设置“目标同步条数”
4. 插件会自动估算滚动深度，从顶部开始向后滚动加载更多帖子
5. 每轮收集新出现的帖子 URL，并沿用现有单帖保存链路写入 Obsidian
6. 同步和清除进行中，X 书签页右上角会显示常驻进度面板
7. 如果失败，弹窗会显示最近一次批量同步的主要失败原因
8. 连续几轮没有发现新内容后自动停止，并返回同步统计
9. 同步完成后，如果存在“新保存 + 去重确认已存在”的帖子，可在弹窗里选择继续清除这批 X 书签

默认参数：

- 单次最多尝试同步 80 条
- 内部会按“目标条数”自动估算滚动深度
- 连续 3 轮没有新内容就停止

你可以在弹窗中修改：

- `目标同步条数`：本轮最多希望同步多少条帖子

说明：

- 同步过程中仍会按 `url:` 去重
- 已在当前页面刚保存过的帖子，也会被前端短时间内跳过，避免重复提交
- 这不是 X 官方 API 同步，所以仍然依赖书签页懒加载和 DOM 结构稳定
- 如果你在书签页中段才开始同步，插件会先回到顶部再开始滚动
- 批量同步结果会记录在弹窗里，包括最近一次主要失败原因
- 页面右上角的常驻进度面板会显示同步/清除的实时进度、失败和停止原因
- 清除书签是手动第二步，不会默认自动执行
- 只有“新保存 + 去重确认已存在”的条目才会进入可清除列表；失败和降级保存不会被清除

## 系统要求

- macOS
- Chrome 浏览器
- 本机已安装 Python 3
- 已有一个 Obsidian vault，并且你知道要保存到哪个绝对路径

## 安装

最简单的使用方式是从 GitHub Release 下载：

- `x-bookmark-to-obsidian-extension.zip`

这个压缩包里已经包含：

- 浏览器扩展目录
- `install.command`
- `native-host` 运行时文件

如果你只想单独分发安装器，也可以额外使用：

- `x-bookmark-to-obsidian-installer.zip`

### 1. 加载 Chrome 扩展

1. 打开 `chrome://extensions`
2. 开启开发者模式
3. 点击“加载已解压的扩展程序”
4. 选择你解压后的扩展目录

### 2. 运行安装器

解压后，直接双击：

```bash
install.command
```

这一步会自动完成：

- 安装本机 Native Host
- 安装内置抓取运行时
- 写入 Chrome 所需的 host manifest

### 3. 重启 Chrome

重启后，扩展弹窗里应该能看到 Native Host 已连接。

### 4. 重新加载扩展时

这个项目使用固定扩展 ID，因此重新“加载已解压的扩展程序”后，不需要再去复制新的扩展 ID。

如果你怀疑本机安装状态失效，直接重新运行一次 `install.command` 即可。

## 配置保存路径

打开插件弹窗，在“保存路径”区域：

- 手动输入你的 Obsidian 绝对路径
- 或点击“选择文件夹”
- 点击保存

示例：

```text
/Users/yourname/Documents/YourVault/1-输入/01-待整理
```

要求：

- 必须是绝对路径
- 建议使用收件箱、待整理区或输入区
- 目录必须真实存在

## 输出格式

生成的 Markdown 默认会保留这些信息：

- 原帖 URL
- 作者名和 handle
- 发布时间
- 正文内容
- 互动信息
- 图片链接或视频封面
- 抓取失败时的说明信息

示例 frontmatter：

```yaml
---
aliases: []
tags: []
up:
url: https://x.com/user/status/123
author: [作者名 @handle]
published: 2026-03-20
source: X (Twitter)
fetch_method: x_bookmark_helper
创建时间: 2026-03-20
修改时间: 2026-03-20
---
```

## 使用方式

1. 打开 `x.com`
2. 找到想保存的帖子
3. 点击收藏
4. 插件会提示“正在保存到 Obsidian...”
5. 成功后笔记会出现在你配置的目录里

如果你想把已有书签批量导入：

1. 打开 `x.com/i/bookmarks`
2. 点开插件弹窗
3. 点击“同步当前书签页”
4. 如有需要，先调整“目标同步条数”
5. 等待弹窗或页面 toast 显示同步结果

## 常见问题

### 1. 显示 Native Host 未连接

检查：

- Chrome 扩展是否已重新加载
- 是否已经运行过 `install.command`
- Chrome 是否已重启
- 如果之前装过旧版本，尝试重新运行一次安装器

### 2. 纯文字帖子能保存，图片帖子失败

这是早期版本出现过的问题，当前版本已经兼容了多种 `media` 结构。如果还出现异常，请查看日志。

### 3. 图片链接写进去了，但在 Obsidian 里消失了

这通常不是插件问题，而是你的 Markdown 清理规则误删了 `![](https://raw.githubusercontent.com/zhaoscsc/x-bookmark-to-obsidian/main/...)` 图片语法。请检查 Linter 或自定义正则。

### 4. 保存失败但又不想丢链接

插件会自动生成占位笔记，至少保留原帖 URL 和失败时间，方便后续补抓。

## 调试

- 扩展弹窗会显示 Native Host 状态和最近一次保存结果
- Native Host 日志路径：

```text
~/Library/Logs/x-bookmark-to-obsidian/native-host.log
```

- 如果 X 页面结构变化，优先检查：
  - 收藏按钮是否仍然使用 `data-testid="bookmark"` / `removeBookmark"`
  - 帖子链接是否仍能从时间戳链接提取
  - 收藏成功后按钮状态是否仍按预期切换

## 当前限制

- 不依赖 X 官方 API，但因此更依赖 X 页面结构稳定性
- 当前不处理“取消收藏后删除笔记”
- 目前主要针对 macOS + Chrome 工作流
- 不直接调用 Obsidian Web Clipper 内部接口
- 当前仍需要本机安装器，不支持“只加载扩展 ZIP 就完整可用”
- 书签页批量同步目前是手动触发，不会后台持续自动跑完整历史

## 版本说明

`v2.4.0` 的核心能力：

- 点收藏即自动保存到 Obsidian
- 支持书签页批量同步和自动估算滚动深度
- 支持页面右上角常驻进度面板，实时显示同步/清除状态
- 支持在弹窗中设置目标同步条数，并显示最近一次失败原因
- 支持同步完成后手动清除本轮成功或已去重书签
- 支持带图片的帖子
- 支持自定义保存绝对路径
- 支持抓取失败降级和 URL 去重
- 使用固定扩展 ID，免去手动复制扩展 ID
- 使用内置抓取脚本，不依赖外部 `~/.agents` 环境

## Acknowledgements

- 原始项目基础：[iamzifei/bookmark-is-learned](https://github.com/iamzifei/bookmark-is-learned)
- 感谢原作者提供了可继续改造的扩展基础，让这次工作可以更聚焦在 Obsidian 工作流集成上

## License

This project is licensed under the MIT License.

x-bookmark-to-obsidian

x-bookmark-to-obsidian 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

x-bookmark-to-obsidian

x-bookmark-to-obsidian 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README