四元数
Quaternion 是用于 Matrix 协议的跨平台桌面即时通讯客户端。您可以在此找到有关应用程序使用和设置的一般信息。请参见 BUILDING.md 以获取编译说明。
联系方式
关于 Quaternion 的讨论大多数发生在其母项目 Quotient 的房间:quotient:matrix.org。您可以在 项目的问题跟踪器 中提交问题。如果您发现看起来像是安全问题,请按照 特别说明 进行处理。
下载与安装
建议按照下列方式安装 Quaternion(请根据您的环境阅读以下说明):
- 在 GNU/Linux - 使用您的发行版的软件包管理器;
- 在 macOS - 从 Homebrew 安装;
- 在 Windows - 从项目的 GitHub 发布页面 下载压缩包。
源代码托管在 GitHub.
系统要求
Quaternion 0.0.96 需要 Qt 版本 6.2 或更高,提供 5.15 作为兼容中介(不支持 6.0 和 6.1)。
Linux
Quaternion 已打包适用于许多发行版,包括各种版本的 Debian、Ubuntu 和 OpenSUSE 以及 Arch Linux、NixOS 和 FreeBSD。可以在 Repology 上找到相当全面的列表。满足上述 Qt 要求的常用发行版有 Debian 11 (Bullseye)、Ubuntu 22.04 (jammy)、Fedora 35、OpenSUSE Leap 15.4,更新版本也应该没问题。
在 Flathub 上有适用于 Quaternion 的 flatpak。安装命令如下:
flatpak install https://flathub.org/repo/appstream/com.github.quaternion.flatpakref
这些包是使用合适的 KDE 运行时构建的。您可以在任何带有 Flatpak 的发行版上安装它们——甚至是早于上述版本的。如果您认为有特定于 Quaternion 的 Flatpak 软件包的问题,请在 https://github.com/flathub/com.github.quaternion 提出。
Windows
由于 Windows 上没有已建立的软件包管理机制来解决依赖项,所有需要的库和 C++ 运行时都与 Quaternion 一起打包/安装——除了 OpenSSL。如果您没有安装 OpenSSL(例如,它是任何 Qt 开发安装的一部分),应该自己安装。 OpenSSL 的 Wiki 列出了一些 OpenSSL 安装包的链接。它们有不同的构建配置;当前 Quaternion 构建需要 OpenSSL 3.x,使用/为 Visual Studio 构建(不是 MinGW)。
macOS
如果您使用 Homebrew(您应该使用!),brew install quaternion
会安装 Quaternion 及其依赖项。否则,从 GitHub 发布页面 上发布的包已经包含所有必要的组件。
开发版本
感谢 Cloudsmith 这些慷慨而支持开源项目的人们为 OSS 项目提供免费的托管服务,那些想要查看最新(不一定是最好的,见下文)代码的人可以在 Quaternion 仓库 中找到由持续集成(CI)生产的包。
以下是关于这些包的重要说明,以防您不熟悉它们:
- 它们都捆绑了相当新的(不一定是最新的)Qt 6。
- 它们仅供测试使用;欢迎对任何版本的反馈,只要您知道是运行哪个构建;但不要指望开发人员解决除最新快照之外的任何问题。
- 如果仍不清楚:这些构建默认是不稳定的;有些可能根本无法运行,如果运行了,可能会以您本地语言对您进行谩骂,窃取您的智能手机,并分享您的私人照片,打乱您发送的消息,干扰甚至破坏包括 Element 在内的其他客户端,并以意想不到且难以修复的方式腐化您的账户(这些在过去实际上都发生过)。如果您不准备处理这些问题,请不要运行这些构建。
- 如果您理解上述内容,备份已就绪并仍愿意尝试或一般性帮助项目——请确保
/join #quotient:matrix.org
,并手头有您下载 Quaternion 的 URL。如果遇到问题,请将 URL 发送到您使用的二进制文件中进行聊天(您可能需要使用另一个客户端或 Quaternion 版本),描述发生了什么,我们会尽力帮您解决。
如果您想从源代码构建 Quaternion,请参见 BUILDING.md。
运行
只需以您最喜欢的方式启动可执行文件——无论是从构建目录还是从安装位置。如果您有兴趣进行超出 UI 所提供的调优配置,请阅读下面的“配置”部分。
翻译
Quaternion 使用 Lokalise.co 进行翻译工作。参与很简单: join the project at Lokalise.co, 要求添加您的语言(在 quotient:matrix.org 或 Lokalise 项目聊天中),并开始翻译!许多语言仍然需要贡献者。
配置
目前唯一非平常的命令行选项是 --locale
- 它允许您重写 Quaternion 使用的区域设置(等同于在 UNIX 系统上设置 LC_ALL
变量)。版本 0.0.96 提供了德语、俄语、波兰语和西班牙语翻译。
Quaternion 以 Qt 应用程序的标准方式存储其配置,如下所述。它将在用户特定位置读取和写入配置(如果不存在则会创建),且如果在用户特定的位置找不到配置,则只会从系统范围的位置读取合理默认值。
- Linux:
- 用户特定:
$HOME/.config/Quotient/quaternion.conf
- 系统范围:
$XDG_CONFIG_DIR/Quotient/quaternion
或/etc/xdg/Quotient/quaternion
- 用户特定:
- macOS:
- 用户特定:
$HOME/Library/Preferences/im.quotient.quaternion.plist
- 系统范围:
/Library/Preferences/im.quotient.quaternion.plist
- 用户特定:
- Windows: 注册表项在
- 用户特定:
HKEY_CURRENT_USER\Software\Quotient\quaternion
- 系统范围:
HKEY_LOCAL_MACHINE\Software\Quotient\quaternion
- 用户特定:
所有列在下面的设置都位于配置文件(或 Windows 的)注册表中的 UI
部分。
一些在用户界面(设置和视图菜单)中暴露的设置包括:
-
notifications
- 是否允许 Quaternion 打扰用户并如何打扰的通用设置。none
完全抑制通知(房间和消息仍被高亮显示,但托盘图标被静音);non-intrusive
允许托盘图标显示弹出通知;intrusive
(默认)除此之外还激活 Quaternion 窗口(即应用程序在任务栏中闪烁,或被提升,或以环境特定的方式引起注意)。
-
timeline_layout
- 允许选择时间线布局。如果设置为 "xchat",Quaternion 会以 xchat/hexchat 的样式在每条消息的左侧显示作者。任何其他值将选择 "default" 布局,作者标签位于消息块上方。 -
use_shuttle_dial
- Quaternion 会使用拨盘而不是经典的滚动条来进行时间线的垂直滚动控制。要开始滚动,将拨盘从中间的中立位置移开;越远离中立位置,滚动方向的速度越快。释放拨盘会将其重新设置为中立位置并停止滚动。如果您需要在不知边缘相对位置的情况下移动,这更方便,因为矩阵时间线的情况就是这样;然而,这种控制相对不常见,并非所有人都喜欢它。默认情况下启用拨盘;设置为 false(或 0)以使用经典滚动条。 -
autoload_images
- 一旦消息在屏幕上显示,是否自动加载全尺寸图片。默认是自动加载全尺寸图片;设置为 false(或 0)以禁用此功能,仅在时间线中加载缩略图(在您单击“另存为”或上下文菜单中的“打开”后再下载全尺寸图片)。查看 https://github.com/quotient-im/Quaternion/issues/601 以了解警告。 -
show_spammy
(菜单中的 "Show no-effect activity") - 当设置为 false 时,此设置尝试清理时间线中对对话没有任何有意义贡献的事件。 -
RoomsDock/tags_order
- 允许更改房间列表中标签的顺序。这是一个逗号分隔的标签/命名空间列表;在右边有一些字符具有特殊含义。如果一个标签未被提及且不适合任何命名空间,它将按字典顺序放在房间列表的末尾。相同命名空间的标签也按字典顺序排列。.*
(仅在字符串末尾识别)表示整个命名空间;不以此结尾的字符串被视为完全指定的标签。标签/命名空间前的
-
表示不应将其用于分组;例如,如果您不希望 People 组,可以在列表中的任何位置添加-im.quotient.direct
。im.quotient.none
("Rooms")始终存在且不能被禁用,只考虑其在列表中的位置。默认的标签顺序如下:
m.favourite,u.*,im.quotient.direct,im.quotient.none,m.lowpriority
, 意思是:最爱,然后是所有用户自定义标签,然后是 People,未启用标签的房间("Rooms" 组),最后是低优先级房间。如果 Quaternion 在配置中找不到设置,它会将这一行写入配置,您无需从头开始输入。
未在 UI 中暴露的设置:
show_author_avatars
- 设置为 1(或 true)以在时间线中显示作者头像(默认情况下,如果时间线布局设置为 default);设置为 0(或 false)将抑制头像(XChat 时间线布局的默认设置)。suppress_local_echo
- 设置为 1(或 true)以抑制显示本地回显(从当前应用程序发送但尚未被服务器确认的事件)。默认情况下显示本地回显。animations_duration_ms
- 定义时间线中动画效果的基准持续时间(以毫秒为单位)。默认是 400;设置为 0 以禁用动画。outgoing_color
- 设置您发送文本的首选颜色;支持 HTML 颜色名称和 SVG#代码
;默认是#204A87
(藏青色)。highlight_color
- 设置您偏好的高亮房间/消息颜色;支持 HTML 颜色名称和 SVG#代码
;默认是orange
。highlight_mode
- 如果您偏好使用文字颜色进行高亮显示,请设置为text
;默认是使用背景进行高亮显示。use_human_friendly_dates
- 如果不希望在 UI 中使用人性化日期("今天"、"星期一" 代替标准的日-月-年三联体),请设置为 false(或 0);默认是 true。show_noop_events
- 设置为 1 以显示不会改变状态的状态事件(您会看到 "(repeated)" 在大多数这些事件旁边)。quote_style
- 引用模板。\\1
表示引用的字符串。默认是> \\1\n
。quote_regex
- 设置为^([\\s\\S]*)
以仅在引用的开头和末尾添加UI/quote_style
。默认是(.+)(?:\n|$)
。Fonts/render_type
- 选择在 Quaternion 时间线中渲染字体的方法;可能的值是 "NativeRendering"(默认)和 "QtRendering"。Fonts/family
- 覆盖整个应用程序的字体系列。如果未指定,则使用您环境的默认字体。Fonts/pointSize
- 覆盖整个应用程序的字体大小(以点数计)。如果未指定,则使用您环境的默认大小。Fonts/timeline_family
- 用于在时间线上显示消息的字体家族(例如Monospace
)。如果未指定,则使用全应用程序的字体系列。Fonts/timeline_pointSize
- 在时间线上显示消息的字体大小(以点数计)。如果未指定,则使用全应用程序的字体大小。maybe_read_timer
- 以毫秒为单位定义显示消息被视为已读的阈值时间间隔。hyperlink_users
- 如果不希望在消息中超链接矩阵用户 ID,请设置为 false(或 0)。默认是 true。auto_markdown
(实验性) - 自版本 0.0.95 起,Quaternion 在输入消息时实验性支持 Markdown。Quaternion 仅在消息以/md
命令开头时视消息为 Markdown(在发送前删除命令本身)。将auto_markdown
设置为true
会在所有 不以/plain
开头的消息中启用 Markdown 解析。默认情况下,此设置为false
因为 Qt 目前对 Markdown 的支持存在缺陷,而 Quaternion 中的实现在此基础上有其自身的怪异。如果您启用了此功能(或使用/md
命令),请随时在常规位置提交错误报告。paste_plaintext_by_default
- 如果您希望默认粘贴格式化文本,请将此设置为 false(或 0)。 四元数使用Qt Keychain存储访问令牌和数据库腌制。如果Qt Keychain支持的安全存储不可用,四元数将无法存储您的访问令牌和腌制,并将自动禁用E2EE以避免无法恢复的加密消息。四元数0.0.96之前使用的后备文件不再使用。
四元数将房间状态和用户/房间头像缓存到文件系统中,在您的平台上指定位置,如下所示:
- Linux:
$HOME/.cache/Quotient/quaternion
- macOS:
$HOME/Library/Cache/Quotient/quaternion
- Windows:
%LOCALAPPDATA%/Quotient/quaternion/cache
缓存文件可以随时安全删除,但四元数仅在启动时查找它们,并在运行时定期覆盖它们;所以仅在四元数未运行时删除缓存文件才有意义。如果四元数在启动时未找到或无法完全加载缓存文件,它会从Matrix服务器下载整个状态。如果服务器支持惰性加载房间成员,它会尝试优化此过程;在服务器不支持惰性加载的情况下,初步同步可能需要很长时间(最多一分钟甚至更长,具体取决于房间和用户的数量)。
删除缓存文件可能有助于解决诸如缺少头像、房间处于错误状态等问题。
故障排除
四元数在底层使用libQuotient;某些四元数的问题实际上是libQuotient的问题。如果您没有在下面找到您的情况,也请查看libQuotient README.md中的故障排除部分。
无E2EE支持
如果您在登录窗口中看不到“启用E2EE(BETA)”框,这意味着您的四元数构建根本不支持E2EE。如果您使用的是软件包,请与打包者联系,或者使用E2EE支持构建四元数(请参见BUILDING.md)。
E2EE房间中的旧消息无法解密
遗憾的是,这是当前libQuotient代码中的一个限制:它不请求旧密钥,因此无法解密旧消息。查看问题608以了解进展。
时间轴中没有消息
如果四元数运行但您在聊天中看不到任何消息(尽管您可以输入它们)- 这可能是因为您没有安装Qt Quick库和/或插件。在Linux上,这种情况可能发生在您没有使用官方软件包时。检查stdout/stderr日志,它们在这种情况下非常明确。在Windows,Mac和使用Flatpak时,请打开一个问题(请参见本文件开头的“联系方式”),因为很可能并非所有必要的Qt部分都与四元数一起打包。
SSL问题
尤其是在Windows上,如果四元数启动但在尝试连接时返回类似“无法创建SSL上下文”的消息 - 四元数二进制文件无法访问正确的SSL库。重新阅读本文件开头的“要求”一章的“Windows”部分,并按照建议进行操作(特别确保您使用的是正确版本的OpenSSL - 应该是3.x而不是1.x)。
日志记录
如果您想在命令行控制台中查看日志消息(默认情况下,它们被发送到Windows和一些,但不是所有使用journald的Linux系统的系统日志中),设置QT_ASSUME_STDERR_HAS_CONSOLE=1
以强制将输出重定向到控制台。
在追逐错误和调查崩溃时,最好从命令行以增加的日志记录级别运行四元数。libQuotient和(自0.0.96 beta 4起)四元数使用logging categories以允许对代码的特定部分进行细粒度的日志切换。四元数和libQuotient使用不同的类别;本文只描述了四元数的那些,请确保也检查lib/README.md以了解libQuotient的日志记录类别。配置日志记录以调试问题的最实用方法是通过QT_LOGGING_RULES
环境变量;Qt文档(参见上面的链接)列出了几种其他方法。在所有情况下,您需要提供一个或几个如下所示的条款:
quaternion.<category>.<level>=<flag>
其中
<category>
是以下之一(另见client/logging_categories.h
):main
accountselector
models
(四元数用户和房间列表的后台)models.events
(同样适用于事件)timeline
(时间轴视觉的C++代码 - 很少的日志行,除非您知道要查找哪些内容,否则不太有用)timeline.qml
(时间轴视觉的QML代码 - 这是您可能需要找出时间轴显示不正确的原因)htmlfilter
(在Qt和Matrix的HTML子集之间进行转换,以及从其他应用程序导入HTML)messageinput
(消息输入框)thumbnails
(为时间轴提供图像的代码)
<level>
是debug
,info
, 和warning
之一;<flag>
为true
或false
。
请记住,所有四元数的日志记录类别都以quaternion
开头,而libQuotient的日志记录类别总是以quotient
开头。
您可以使用*
(星号)作为两个点之间任何部分的通配符,并使用分号作为分隔符。后面的语句会覆盖前面的语句,因此,如果您想打开所有调试日志,除了timeline.qml
,您可以设置
QT_LOGGING_RULES="quaternion.*.debug=true;quaternion.timeline.qml.debug=false"
您可能还希望设置QT_MESSAGE_PATTERN
以使日志稍微更具信息量(请参见https://doc.qt.io/qt-6/qtlogging.html#qSetMessagePattern查看格式描述)。我的(@kitsune的)`QT_MESSAGE_PATTERN`如下所示:
`%{time h:mm:ss.zzz}|%{category}|%{if-debug}D%{endif}%{if-info}I%{endif}%{if-warning}W%{endif}%{if-critical}C%{endif}%{if-fatal}F%{endif}|%{message}`
(可怕的%{if}
仅仅是将日志级别编码为其首字母)。
截图