ipelago (in Python)
CLI personal microblog (命令行个人微博客)
纯命令行操作,包括两方面功能:
- 写微博客并生成静态网站 (HTML 和 RSS)
- 订阅别人的 RSS
ipelago 之名
ipelago 源于群岛的英文 archipelago, 如果我们每一个人是一座孤岛,那么当我们搭建自己的微博客,大家的微博客聚在一起就可以形成群岛。
主要功能 (写微博客、订阅 RSS)
写自己的微博客
- 多种方式方便写博文(包括命令行输入、获取剪贴板内容、获取文件内容、通过简陋的 GUI 窗口输入)。
- 可生成静态网站 (包括 HTML 和 RSS), 这些静态文件可通过 GitHub Pages 或类似的免费服务搭建你的私人微博客供别人浏览、订阅。
- 生成 HTML 的模板、样式可以自定义(自带一个简单模板)。
- 可区分公开消息与隐私消息,只有公开消息才会对外发布,隐私消息只能本地浏览。
- 有简单的 #标签 功能与搜索功能。
订阅别人的微博客
- 可通过 RSS 订阅别人的微博客。
- 只支持微博客(一条消息只有一两句话),不支持正常博客(长文章),因此数据库体积不会暴涨,长期使用也能一直保持很小的体积。
- 有限订阅(意思是不保存全部订阅消息,看到特别喜欢的内容可执行收藏命令,收藏的消息才会永久保存)。有限订阅可避免储存大量无用信息,避免数据库体积暴涨,减少信息焦虑。
- 可设置 proxy, 方便与翻墙软件搭配使用。
减少烦躁和焦虑
一般通过 App 或网页浏览消息时,会一目十行,快速上下滑动消息列表,这种操作有可能使烦躁和焦虑感变得更严重。
ipelago 也可一次列举多条消息,但更提倡使用逐条浏览功能,每次只显示一条消息,并且可以记住位置,随时离开去做别的事情,回头继续从上次中断的地方接着阅读。
因此,有助于减少烦躁与焦虑。
安装与初始化
ipelago 使用了 Python 3.10 的新特性,比如 type union operator, pattern matching 等,因此,如果你的系统中未安装 Python 3.10, 推荐使用 pyenv 或 miniconda 来安装最新版本的 Python。
例如,安装 miniconda 后,可以这样创建 3.10 环境:
$ conda create --name py310 python=3.10
$ conda activate py310
安装非常简单,只要
pip install ipelago
即可。安装后,第一次正式使用前,必须执行 'ago init name' 进行初始化,其中 name 是你的微博客名称,对外发布时别人可以看到。
帮助
ago -h
(查看帮助消息)
ago post -h
(每个子命令也有详细的帮助消息)
初始化
ago init 别有洞天
(初始化,设定微博客名称为“别有洞天”)
写博文
ago post Hello World!
(写一条公开消息, 可通过 HTML 及 RSS 对外发布)
ago post -pri/--private My password is abcd
(写一条隐私消息, 仅本地可见)
ago post
(发送剪贴板的内容)
ago post -g/-gui
(弹出一个简陋的 GUI 窗口方便输入)
ago post -f/--file ./abc.txt
(发送文件 abc.txt 的内容)
切换与删除
ago toggle id
(切换公开/隐私,其中 id 是消息的 id)
ago delete id
(删除一条消息)
注意,切换公开/隐私、或删除消息后,要重新 publish 发布消息,才能反映到静态网站中(关于发布静态网站,请看后面关于 publish 的章节)。
Timeline (阅读自己微博客)
ago tl
(阅读下一条消息, 完全等同于ago tl -next
)
ago tl -zen
(阅读下一条消息,专注模式)
ago tl -first
(阅读最新一条消息)
ago tl -next
(阅读下一条消息)
ago tl -go/--goto 2022-03-15
(跳到 2022年3月15日 或最接近这天的消息)
ago copy id
(复制指定 id 的博文内容)
以上命令包括(且只包括)公开消息与隐私消息。
以下命令可区分公开/隐私/收藏 (其中 '-today' 与 '-yesterday' 不可与 '-fav' 搭配使用) ('-date' 与 'count' 可与 '-fav' 搭配使用)。
ago tl -today
(阅读今天的消息,包括公开与隐私,不包括收藏)
ago tl -yesterday
(阅读昨天的消息,包括公开与隐私,不包括收藏)
ago tl -today -pub/--public
(阅读今天的消息, 限定公开消息)
ago tl -today -pri/--private
(阅读今天的消息, 限定隐私消息)
ago tl -fav/--favorite
(阅读最近几条收藏消息)
ago tl -date 2022-03-15
(阅读 2022年3月15日 的消息, 默认上限 9 条)
ago tl -date 2022-03
(阅读 2022年3月 的消息, 默认上限 9 条)
ago tl -date 2022 -pri -limit 20
(阅读 2022年 的隐私消息, 最多只显示上限 20 条)
ago tl -count 2022-03
(统计 2022年3月 的消息条数)
ago tl -count all
(统计全部消息条数,包括公开与隐私,不包括收藏)
ago tl -count all -pub
(统计公开消息的条数)
订阅 RSS
ago news -follow https://douchi.space/@mtfront.rss
(订阅长毛象)
ago news -follow https://m.cmx.im/@guobetty.rss
(一般来说,长毛象的 rss 地址就是在用户地址后面直接加 '.rss' 即可) (注意,这个源要翻墙,可参考下面 Proxy 章节设置代理)
ago news -follow https://v2ex.com/feed/create.xml -p HasTitle
(订阅V站的“分享创造”节点)
ago news -follow https://geeknote.net/Rei/feed.atom -p HasSummary
(订阅 geeknote)
ago news -follow https://sspai.com/feed --parser HasTitle
(订阅少数派)
ago news -l/--list
(查看已订阅的 RSS 列表)
ago search -feeds
(完全等同ago news -l
)
ago search -feeds keyword
(查找源标题里包含 keyword 的源)
关于 parser
默认采用 '--parser Base' 解析 RSS 内容,舍弃每篇博文的 title (因为有时 title 与正文重复)。
建议先看看 RSS 源文件,看 title 有没有必要显示,如果需要保留 title, 可使用以下命令订阅:
ago news -follow [url] -p/--parser HasTitle
在订阅后,也可更改解析器:
ago news -u/--update [id] -p/--parser HasTitle
有的 RSS 源文件在提供
<content>
的同时也提供 <summary>
, 对于这种情况,建议采用 '--parser HasSuammry'。Proxy (代理)
ago -i/--info
查看当前 proxy 设定。
ago --set-proxy [url]
设置代理网址(有些 rss feed 需要翻墙才能订阅)
ago --set-proxy true
启用代理。
ago --set-proxy false
不使用代理。
例如:
ago --set-proxy http://127.0.0.1:1081
(注意网址要以 http 开头)改名
改名可以让消息看起来更清晰(显示每条消息时,都会注明源的名称)。
$ ago news -follow https://v2ex.com/feed/create.xml -p HasTitle
[R9DX70] 分享创造
https://v2ex.com/feed/create.xml
$ ago news -feed r9dx70 --set-name 分享创造-V2EX
[R9DX70] 分享创造-V2EX
https://v2ex.com/feed/create.xml
改 ID
改 ID 可以方便后续操作(比如指定阅读一个源的消息、强制更新指定的源,都需要用到 ID)。
$ ago news -follow https://sspai.com/feed -p HasTitle
[R9ELEZ] 少数派
https://sspai.com/feed
ago news -feed r9elez --set-id sspai
[sspai] 少数派
https://sspai.com/feed
更新
默认每个源每 24 小时只能更新一次,可使用 '-force' 参数强制更新,但为了尊重源站节约资源及减少焦虑,建议不要频繁更新。
每次只能强制更新一个源,不可强制批量更新
而且也不是自动更新,需要手动执行以下命令才会更新
一旦更新,未收藏的消息就会被新消息覆盖(即,不保留旧消息)。
遇到特别喜欢的消息可使用命令 'ago like id' 收藏,永久保存。
ago news -u/--update all
(批量更新全部源)ago news -u sspai
(更新 feed id 为 sspai 的源)ago news -force -u id
(强制更新指定 id 的源)阅读消息
ago news
(阅读下一条消息, 完全等同 ago news --next
)ago news -first
(阅读最新一条消息)ago news -next
(阅读下一条消息)ago news -zen
(阅读下一条消息, 专注模式)ago news -go/--goto 2022-03
(跳到 2022年3月1日 或最接近这天的消息)ago news -feed id
(阅读指定 id 的源的消息,默认上限 9 条)ago news -feed id -limit 3
(阅读指定 id 的源的消息,最多显示 3 条)ago news -like id
(收藏指定 id 的消息)ago like id
(完全等同于 ago news -like id
)ago news --toggle-link
(显示/隐藏消息本身的链接)ago copy id -link
(复制指定 id 的消息的链接)删除(源/消息)
ago news -delete id
(删除一个源及与其相关的消息,已收藏的消息不会被删除,其中 id 是指用 'ago news -l' 看到的 id)
ago delete id
(删除一条消息,其中 id 是指 消息的 id)
发布微博客
使用 'ago publish' 命令可生成 HTML 文件及 RSS 文件,通过 GitHub Pages 或类似的免费服务即可创建你的个人微博客网站。
第一次发布时,需要填写微博客名称、作者名称等信息。
ago publish -info
(显示微博客信息)ago publish -g
(打开 GUI 窗口填写微博客信息)ago publish --set-title
([必填] 设置 RSS 的标题,即你的微博客名称)ago publish --set-author
([必填] 设置作者名)ago publish --set-link
([必填] 设置 RSS 的链接)ago publish --set-website
([选填] 设置任意网址, 通常是你的个人网站或博客的网址)ago publish
(默认输出静态文件到当前目录的 'public' 文件夹,默认每页 50 条消息)ago publish -out /path/to/dir -n 25
(输出静态文件到指定文件夹, 每页显示 25 条消息)title, author, link 这三项信息都必须有内容,才能执行
ago publish
命令生成网站文件。但可以先随便填,生成后看看效果,以后可以随时修改这些信息。其中 link 是指别人通过 RSS 订阅这个微博客的网址,请务必后续发布到到网上后找到正确的网址,再回头修改。
生成文件后,双击其中的 'index.html' 即可预览效果(我用了很简单的样式,懂前端的朋友可自行修改样式)。
自定义模板
由于 ipelago 只处理微博客(每篇博文一两句话),不处理正常博客(长文章),因此 HTML 模板可以非常简单,自带的模板一共只有 62 行。可见,这个模板是非常容易看懂的,如果有不满意的地方,也就非常容易修改。
执行 'ago publish' 命令,可以看到默认模板 (Templates) 文件夹的位置,把这个文件夹复制粘贴到另一个地方,就可以自由修改了。修改后,使用参数 '-tmpl' (或 '--templates') 指定 templates 文件夹的位置:
ago publish -tmpl ..my_tmpl
('-tmpl' 后面的文件夹可以使用相对路径、也可以使用绝对路径)
注意,模板文件夹内必须包含 'index.html' 和 'atom.xml' 这两个模板文件,内容采用 Jinja2 语法。
Tags and Search (标签与搜索)
标签必须以“井号”开头,以空格结尾,并且不超过 TagSizeLimit
(注意:并不是加了井号就一定能形成标签,必须以 "#" 开头,以空格结尾,并且不超过长度上限才能形成标签。)
例:以下命令发表了一条消息,同时关联了标签 'cde', 由于 '#' 是特殊字符,因此消息内容需要用半角双引号括住。推荐使用 'ago post -g' 打开 GUI 窗口方便输入(在 GUI 窗口中不需要用双引号括住内容,可随意输入任何特殊字符)。
ago post "abc #cde efg"
ago search keyword
(自动优先采用 '-tag' 方式搜索,如果没有结果再自动改成 '-contain' 方式搜索)
ago search -tag/--by-tag [tag]
(通过标签搜索消息,效率较高)
ago search -contain keyword
(搜索内容包含 keyword 的消息,效率较低)
以上命令默认包括 公开(public)/隐私(private)/收藏(fav)/订阅(news) 四种消息,但都可以加 '-bucket' 参数限定只搜索其中一的消息,例如:
ago search abc -bucket fav
(在收藏消息中查找包含 'abc' 的消息)
ago search cde -bucket public
(在我的公开消息在查找包含 'cde' 的消息)
以上命令默认最多列出 9 条结果,可加参数 '-limit' 更改上限,例如:
ago search keyword -limit 30
以上命令是搜索消息内容的,以下命令可搜索源与标签本身。
ago search --all-tags
列出全部标签 ago search --all-tags keyword
在全部标签中查找包含 keyword 的标签名 ago search --all-feeds
列出全部已订阅的源,等同 ago news --list
ago search --all-feeds keyword
查找源名称中包含 keyword 的源例如
ago search --all-tags java
可以找到标签 'Java' 和 'JavaScript', 而不是查找与这些标签关联的消息。特殊技巧
特殊的订阅方法
我遇到了一些 rss feed 受到 Cloudflare 的保护而无法通过 python requests 访问,但可以用浏览器直接访问,比如这个 https://mstdn.jp/@nekodayo.rss
对于这种情况,可以用浏览器访问,按 Ctrl+S 保存 rss 到本地,建议保存到一个固定的文件夹,比如我保存在 D:\rss_feeds 里。
然后就可以这样订阅
ago news -follow D:\rss_feeds\@nekodayo.rss
但问题也很明显,后续需要手动下载 rss 覆盖同名文件才能更新内容,先这样应付吧,以后再想别的办法。
Zen Mode (专注模式)
我自己很喜欢这个模式,简单来说只是自动清屏而已,效果是减少浮躁,使人宁静。 'ago tl' 系列命令与 'ago news' 系列命令可使用专注模式,例如:
ago tl -zen
ago news -zen
也可以使用命令 'ago -zen/--toggle-zen' 切换默认开启/默认关闭 zen mode。
Info (软件信息)
使用命令 'ago -i/--info' 可查看程序位置、版本、数据库文件位置、zen mode 是否默认打开、代理 等信息,例如:
$ ago -i/--info
[ago] D:\ComputerScience\Python\myprojects\pypelago\src\ipelago\main.py
[version] 0.0.1
[database] C:\Users\ahui\AppData\Local\github-ahui2016\pypelago\pypelago.db
[Zen Mode Always ON] False
[http_proxy] http://127.0.0.1:1081
[use_proxy] False
[repo] https://github.com/ahui2016/pypelago
参考:我的微博客
我用这个程序生成的微博客,采用自带的极简模板(我实在不擅长前端,但懂前端的人可以看上面 "自定义模板" 的章节,很容易修改)。
更新日志
v0.0.6
- feature 新增了
ago tl -count all -pub
统计公开消息的条数,方便使用ago publish
命令时决定每页显示多少条消息。
v0.0.5
- fix 修复了订阅 news.ycombinator.com/rss 时解析日期格式失败的问题。
- fix 修复了 'ago search -feeds' 无结果时提示消息的一个小 bug。
v0.0.4
- fix 在订阅某个博客时 (https://blog.gimo.me/index.xml) 发现了
<a>
链接的文字描述里含有<svg>
并因此导致提取纯文本后产生多个换行符的问题,已修复。
v0.0.3
- fix 修复了 HTML 与 atom.xml 的更新日期问题(原本以执行 'ago publish' 命令的时间为准,现在以最新一条公开消息的发表日期为准)