Pok'em

使用 CLI 或 HTTP PUT/POST 请求发送 Matrix 消息。它旨在支持轻松的脚本，以便通过 Matrix 发送通知给自己或团队。

它运行一个 Matrix 机器人账户，当被调用时在 Matrix 上向您发送提醒。它可以独立运行，也可以作为守护进程运行并监听 HTTP 请求。

就这些。

如果您想使用我在 pokem.dev 上的默认实例，您不需要安装任何东西。

它使用 headjack 构建，headjack 是一个 Rust 机器人框架。

如果您觉得这很熟悉，那是因为它是 ntfy.sh 的核心功能的克隆，但仅限于使用 Matrix。我鼓励您查看该项目，看看它是否更适合您的需求。

获取帮助

有一个公共 Matrix 房间可供使用，链接为 #pokem:jackson.dev

用法

使用公共服务器

我在 pokem.dev 上运行一个端点和相关机器人账户，该机器人运行在我位于 jackson.dev 上的 homeserver 上。如果没有配置服务器设置，pokem 将默认使用该实例。

您可以运行自己的实例（使用 pokem --daemon），但在这里我将描述使用 pokem.dev。

1. 在 Matrix 上创建一个房间，并邀请机器人账户 @pokem:jackson.dev。
2. 从欢迎消息或您的客户端中获取 Matrix 房间别名或 ID。
3. 运行 curl --fail -d "备份成功 😀" pokem.dev/<房间 ID>。或者使用 pokem <房间 ID> <消息>。
4. curl 或 pokem 命令会在消息发送完成之前阻塞，如果出现错误将返回错误。

pokem，像 ntfy，监听 HTTP PUT/POST 请求，因此发送消息非常容易。如果您想了解更多发送消息的示例，请查看 ntfy 文档，并用 Matrix 房间 ID 替换 ntfy 的 "topic"。

如果您使用 pokem CLI，可以在配置文件中设置默认房间，然后不需要在命令中指定它。pokem Backup Successful 😀 就足够了。

守护程序还提供了一个网页，可以帮您发送消息，例如 pokem.dev。为了方便使用，您可以使用带有房间 ID 的 URL，以便生成简单的链接。

试试看！发送消息到 https://pokem.dev/pokem-example:jackson.dev，您可以在 #pokem-example:jackson.dev 中看到它。

您还可以使用唯一的房间 ID： https://pokem.dev/!JYrjsPjErpFSDdpwpI:jackson.dev，或者 URI 编码的房间别名（使用 Matrix 标准 '#'） https://pokem.dev/%23pokem-example:jackson.dev。'#' 是一个特殊的 URL 字符，您需要将其 URI 编码（作为 "%23"）或从请求中删除，因为我们将支持 "pokem-example:jackson.dev" 作为房间名。

@pokem:jackson.dev 的限制

1. 您不应该依赖于它具有超过 1 个 9 的可靠性。
2. 未来可能会有使用限制。

CLI 使用方法

pokem 工具包含一些方便的功能，可以帮助发送消息。

您可以配置默认房间，并设置简短的房间名称，以便更容易使用。

以下是一些示例调用

# These three commands are all equivalent
pokem !RoomID:jackson.dev Backup failed!
pokem --room !RoomID:jackson.dev Backup failed!
curl --fail -d "Backup failed!" pokem.dev/!RoomID:jackson.dev

pokem Backup failed! # Will send to your configured default room
pokem error Backup failed! # Will send to your configured room named "error"
pokem --room error Backup failed! # Same as above

# It also accepts stdin as the room message
echo "Backup failed!" | pokem error # Sends to the room named "error"
cat README.md | pokem # Send the contents of a file to the default room

请参阅 设置 部分，了解配置选项。

运行私人机器人账户

如果您不想使用 @pokem:jackson.dev，有 2 种方法仍然可以使用 Pok'em。

您可以

1. 使用 pokem --daemon 运行自己的机器人，并像上面描述的那样访问。
2. 使用配置了机器人登录的 Pok'em CLI。应用将登录到 Matrix 机器人账户并在本地发送 ping。

以守护程序方式运行 Pok'em 有几个优点，但仅使用本地登录也可以完全使用。

1. 守护程序将更加响应，因为它需要一些时间来登录和同步 Matrix。
2. 它也将持续可用以响应房间邀请和帮助请求消息。
3. 您可以跳过安装 pokem，这对于从 CI 作业中接收 ping 特别有用。

安装

pokem 仅在crates.io上打包，因此安装需要通过 cargo install pokem 或从git进行。

对于 Nix 用户，此仓库包含一个Nix flake。有关配置的详细信息，请参阅 设置部分。

设置

使用自己的机器人账户需要设置，否则无需设置。

pokem 命令行工具会运行此列表，直到找到要执行的操作

1. pokem --daemon 以守护进程方式运行，监听HTTP消息。
2. 如果没有配置服务器或Matrix登录，它将向 pokem.dev 实例发送请求。
3. 如果配置了服务器，pokem 将向服务器发送PUT请求。
4. 如果配置了Matrix登录，CLI将尝试直接登录到Matrix。

以下是配置文件框架。它可以放置在 $XDG_CONFIG_HOME/pokem/config.yaml 或通过 pokem --config ~/path/to/config.yaml 传递。

# Optional, for creating room shorthands
# These can be used in place of the raw room IDs
# e.g. `pokem error The backup failed!` will send "The backup failed!" to the room named "error"
rooms:
  # Default is a special value, and will be used if no room is specified
  # e.g. `pokem The backup failed!` will send to the default room
  default: "!RoomID:jackson.dev"
  error: "!ErrorRoom:jackson.dev"
  fullteam: "!RoomWithFullTeam:jackson.dev"
  discord: "!RoomBridgedToDiscord:jackson.dev"

# Optional, define the server to send messages to
# If configured, `pokem` will first try to query this server to send" the message
# Will use pokem.dev by default
server:
  url: https://pokem.dev
  # Optional, customize the port if necessary
  port: 80

# Optional, if you want to login to your own Matrix account
# You will need to create the bot account manually
matrix:
  homeserver_url: https://matrix.jackson.dev
  username: "pokem"
  # Optional, will ask on first run
  #password: ""
  # Optional, but necessary for use
  #allow_list: ".*"
  # Optional, the max size of the room to join
  #room_size_limit: 5
  # Optional, customize the state directory for the Matrix login data
  # Defaults to $XDG_STATE_HOME/pokem
  #state_dir:

# Optional, to define the bindings when running as a service
daemon:
  addr: "0.0.0.0"
  port: 80

身份验证

您可以从Matrix端配置密码，这样在戳Matrix房间时就需要密码。

将 !pokem set password pokempassword 发送到Matrix机器人将密码设置为 "pokempassword"。

一旦设置了密码，除非在消息开头提供了密码，否则房间不会收到ping，例如

curl --fail pokem.dev/roomid -d "pokempassword poke the room"

如果密码匹配，它将被从消息中删除，其余消息将被发送到房间。

可以通过发送 !pokem info 让房间内的任何人看到密码，并且可以通过 !pokem set password off 删除密码。

其他想法

以下是一些您可以使用此功能执行的非标准操作

无处不在的警报

1. 在配置了桥接的home服务器上运行机器人账户。
2. 让机器人账户通过桥接登录到任何其他地方（Discord、Slack、IRC、iMessage等）。
3. 使用桥接使用此功能ping Discord/Slack/IRC房间。

编写自己的消息脚本

1. 给 pokem 您的 登录信息。
2. 将任何消息发送到您选择的房间，例如 pokem <room> I'm running late

与ntfy.sh的比较

缺点

1. 功能更少。 pokem 只在Matrix上执行文本ping。
2. 集成较少。 pokem 仅限于Matrix及其桥接到Matrix的事物。

优点

1. 默认情况下加密房间主题。即使有密钥，其他人也无法订阅消息（尽管他们可以 发送 它们）。
2. 您不需要单独的应用程序，只需使用现有的Matrix客户端即可。

Nix

开发正在使用 Nix flake 进行。安装pokem最简单的方法是使用nix flakes。

❯ nix run github:arcuru/pokem

flake包含一个 overlay，以便更容易将其导入到您的flake配置中。要使用，将其添加到您的输入

    inputs.pokem.url = "github:arcuru/pokem";

然后添加overlay inputs.pokem.overlays.default 到您的pkgs。

flake还包含一个home-manager模块，用于将守护进程作为服务安装。将模块导入到您的home-manager配置中，您就可以在nix内部配置 pokem

{inputs, ... }: {
  imports = [ inputs.pokem.homeManagerModules.default ];
  services.pokem = {
    enable = true;
    settings = {
        homeserver_url = "https://matrix.jackson.dev";
        username = "pokem";
        password = "hunter2";
        allow_list = "@me:matrix.org|@myfriend:matrix.org";
    };
  };
}