README

Mastobot是Mastodon的简单计划发布机器人。它旨在用于单用户环境，其中有人希望自托管Mastodon自动化。它旨在通过cron任务运行。

常见用例包括从集合中发布每日引语，或一个缓慢序列化（但自动化）的故事。

安装

安装Mastobot并保持其更新的最简单方法是克隆Git存储库，然后检出最新的标签。

然后运行composer install安装必要的依赖项。

最后，设置cron（或您选择的调度工具）以频繁运行以下命令

php run.php

Mastobot仅在cron运行时发布消息，因此，例如，如果机器人每小时运行一次，则所有帖子都会在每小时发生。如果您希望有一个看似随机的计划，请使用质数分钟（例如，每13或17分钟一次）。

配置

Mastobot通过项目根目录中的mastobot.yaml文件进行控制。以下列出了可用的键。

app_name（必需）

您的机器人的名称。应该是一个简短、半唯一的可读名称。"Mastobot"是一个合理的默认值。

accounts（必需）

这是一个命名字典，包含账户连接信息。有四个属性，都是必需的。每个账户定义的名称将用于下面的posters列表，但否则是任意字符串。

app_instance（必需）

机器人将发布的Mastodon实例。它应该是域名，没有http或任何内容。所以mastodon.social，phpc.social等。

身份验证信息（必需）

您需要从您的个人资料中获取三个标识符来认证任何Mastodon机器人。Mastobot没有包含自动为您生成这些标识符的机制，这是设计上的考虑，但它们可以通过UI简单地生成。

在您的“设置”页面上，选择“开发”选项卡。点击“新建应用程序”按钮。为您的应用程序提供一个特定的名称。

您可以将其余的设置保留为默认值。或者，如果您想限制机器人的访问权限，则write:statuses和write:media是唯一必需的权限。

完成设置后，点击“保存更改”。

下一页将显示三个哈希值：“客户端密钥”、“客户端密钥”和“您的访问令牌”。这些是我们需要的三个值。将它们分别复制到mastobot.yaml中的client_key、client_secret和token中。

默认值

此可选数组属性允许您为每条帖子设置默认配置值。它们可以根据帖子进行覆盖（见下文）。

以下属性在这里设置是有意义的。

• visibility - 每条帖子的可见性。合法值是public、unlisted、private（即仅关注者可见）和direct。Direct几乎很少使用。默认值为unlisted，这意味着帖子是公开的，但不会显示在您的实例的本地时间线中。请检查您实例的策略，以确定机器人是否有任何具体要求。
• language - 一个ISO 639语言代码，用于指定帖子使用的语言，例如en、de或fr。
• spoiler_text - 也称为“内容警告”。

state_file

Mastobot 在每次运行后都会将应用程序状态存储在磁盘上的 JSON 文件中。默认情况下，会使用项目根目录下名为 mastobot_state.json 的文件。如果你的项目根目录不可写（出于安全考虑通常是好事），你也可以指定任何其他文件名（只要该文件可写）的相对或绝对路径。

在大多数情况下，你可以跳过这个字段。

海报

这是一个数组属性，定义了将运行的自动发布服务。你可以有任意数量的海报（尽管 0 个可能没什么意义）。每个海报使用不同的 strategy，这可能有自己的配置。

目前有两个可用的 strategy：random 和 sequence。

• random - 每次发布时，将从目录中随机选择一条状态消息。没有“记忆”从一个运行到下一个；值每次都会重新随机化。
• sequence - 这将从目录中以字典顺序发布状态消息。一旦发布，将不会再次发布。

两种策略都有三个必需的配置参数

• account - 该海报应使用的凭据名称，来自 accounts 部分。定义多个账户允许单个 Mastobot 实例为任意数量的自动发布账户供电。
• directory - 在磁盘上从该目录中抽取发布的目录。如果是相对路径，它将在项目根目录相对于评估。它也可以是一个指向你希望指向的任何位置的绝对路径。该 directory 必须在所有列出的 posters 中是唯一的。
• minHours - 两次连续发布将至少相隔这么多小时。
• maxHours - 两次连续发布将最多相隔这么多小时，从 Mastobot 下次运行时起。

每次发布时，Mastobot 都会在未来 minHours 和 maxHours 之间生成一个随机的时间戳，并记录该值。下次机器人运行时，它将检查当前时间是否已超过该时间戳。如果没有，则不执行任何操作。如果是，则发布下一条状态消息并重新记录下一个时间戳。

示例配置

为了清晰起见，这里是一个可能的（可能）配置示例

app_name: "Mastobot"
accounts:
  crell:
    app_instance: "phpc.social"
    client_id: "xxxx"
    client_secret: "yyyy"
    token: "zzzz"

defaults:
  language: "en"

posters:
  quotes:
    strategy: "random"
    account: "crell"
    directory: "posts/quotes"
    minHours: 20
    maxHours: 30
  story:
    strategy: "random"
    account: "crell"
    directory: "/home/me/posts/story"
    minHours: 5
    maxHours: 6

在这个例子中，posts/quotes 目录中的随机消息将每隔 20-30 小时发布一次（即发布之间的差距在 72,000 到 108,000 秒之间）。此外，来自 /home/me/posts/story 目录的帖子将按字典顺序发布，它们之间的差距在 18,000 到 21,600 秒之间。两者都将发布到由 crell 账户块定义的 phpc.social 账户上。

发布目录

每个策略都依赖于一个包含要发布的状态消息的目录。Mastobot 支持六种发布格式，包括文件和目录，所有这些都可以混合匹配。对于 sequence 策略，文件和目录将一起包含在相同的字典列表中。

简单消息

对于大多数帖子，一个简单的文本消息（以 .txt 结尾的文件）就足够了。整个文本文件的值将原封不动地作为帖子的主体。

JSON 消息

或者，一个简单的 JSON 消息（以 .json 结尾的文件）允许指定消息主体之外的价值。以下是一个完整的示例，其中包含可能的值

{
  "status": "The body of the status message.",
  "spoiler_text": "The spoiler text or content warning, if any",
  "language": "en",
  "visibility": "unlisted"
}

YAML 消息

状态也可以使用 YAML 定义。上述 YAML 示例将是

status: "The body of the status message.",
spoiler_text: "The spoiler text or content warning, if any",
language: "en",
visibility: "unlisted"

目录定义

状态也可以定义为目录。这允许包含附加的媒体，以及该媒体的元数据。目前仅支持图像，不支持音频或视频。

如果一个目录包含 status.txt、status.json 或 status.yaml 文件（按此顺序检查），它将被解析与独立文件相同的方式。

此外，目录中的任何 .gif、.png、.jpg、.jpeg 或 .webp 文件都将按字典顺序附加到状态消息中。

可选地，您还可以包括一个与图像文件名称匹配的 json 或 yaml 文件。该文件包含图像的附加元数据，例如替代文本。潜在值如下所示。

description: The alt text for this image, which you should always include.
# The position of the image that should be focused on when cropping.
focus:
  x: 0.2
  y: -0.2

强烈建议您至少包含一个描述，以提高可访问性。

为什么不使用计划帖子呢？

ActivityPub 和 Mastodon API 支持计划帖子。然而，大多数 Mastodon UI 都没有包含审查、修改或取消修改后帖子的方式。虽然 Mastobot 可以一次将所有帖子推送到计划时间，但这将无法修改或清理计划帖子，除非将其作为 Mastobot 的一部分构建完整的 UI。

目前这不在范围内，因此它只是正常发布。但是，您可以使用 JSON 帖子中的 scheduled_at 属性来使帖子计划发布而不是立即发布。

贡献

请参阅 CONTRIBUTING 和 CODE_OF_CONDUCT 以获取详细信息。

安全

如果您发现任何与安全相关的问题，请通过电子邮件 larry at garfieldtech dot com 而不是使用问题跟踪器。

致谢

• Larry Garfield
• 所有贡献者

许可协议

Affero GPL 版本 3 或更高版本。有关更多信息，请参阅 许可文件。