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的文件。如果项目根目录不可写（这对于安全性通常是好事），你也可以指定一个相对或绝对路径到任何其他文件名，只要该文件是可写的。

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

posters

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

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

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

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

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

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

示例配置

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

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

在这个例子中，每20-30小时会发布posts/quotes目录中的一个随机消息（即帖子之间的间隔为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消息

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

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

HTML消息

HTML消息支持帖子。它们必须是有效的HTML内容。整个HTML内容将按原样发布。

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

此外，目录中任何 .gif、.png、.jpg、.jpeg 或 .webp 文件将以词汇顺序附加到状态消息中。

可选地，您还可以包含一个与图像文件名称匹配的 json 或 yaml 文件。该文件包含关于图像的额外元数据，如 alt 文本。潜在值如下。

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 可以一次性在计划的时间推送所有帖子，但这将无法修改或清理计划发布的帖子，除非将其作为一个完整的 UI 集成到 Mastobot 中。

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

贡献

请参阅 CONTRIBUTING 和 CODE_OF_CONDUCT 了解详情。

安全

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

鸣谢

• Larry Garfield
• 所有贡献者

许可

Affero GPL 版本 3 或更高版本。请参阅 许可文件 获取更多信息。