# 使用自动化 (/zh/guides/use-automations)

<!-- agent-signals: reading_time_min: 2 · est_tokens: 1273 · updated: 2026-09-23 -->
Related: [构建应用内助手](/zh/guides/assistant-embed.md), [配置 GitHub 应用的自动合并](/zh/guides/configure-automerge.md), [使用 Claude Code 编写文档](/zh/guides/claude-code.md), [使用 Codex 编写文档](/zh/guides/codex.md), [使用 Cursor 编写文档](/zh/guides/cursor.md), [使用 Devin Desktop 编写文档](/zh/guides/devin-desktop.md)

自动化会自动运行 agent，让你的内容无需手动维护就能保持准确。本指南介绍如何选择合适的自动化、有效地配置它，以及撰写能产生一致结果的指令。

<div id="when-to-use-automations">
  ## 何时使用自动化 [#何时使用自动化]
</div>

自动化最适合以下任务：

* **重复性**：相同任务定期在可预测的计划下运行，或每当特定事件发生时运行。
* **耗时**：手动完成需要时间但遵循一致模式的任务。
* **响应式**：应在代码或内容变更时自动发生的任务，例如在功能发布后更新文档。

对于一次性或探索性任务，请直接在[控制台](https://app.mintlify.com)或 Slack 中使用 agent。

<div id="choose-a-trigger">
  ## 选择触发器 [#选择触发器]
</div>

每个自动化都基于四种触发器类型之一运行。选择与你需要的工作完成时机相匹配的触发器。

| 触发器                    | 使用场景                                           |
| ---------------------- | ---------------------------------------------- |
| 内容更新（Content update）   | 任务应在你的项目内容变更时运行——翻译新页面、修复失效链接或审计 SEO 元数据。      |
| 代码变更（Code change）      | 任务应在源代码变更时运行——在 PR 合并后更新 API 规范或文档。            |
| 自定义计划（Custom schedule） | 任务应按固定节奏运行——发布每周更新日志或运行定期的语法检查。                |
| 集成（Integration）        | 任务应在连接的工具中发生事件时运行——响应 Slack 频道中的新消息。适用于自定义自动化。 |

<div id="predefined-automations">
  ## 预定义自动化 [#预定义自动化]
</div>

Mintlify 为最常见的内容维护任务提供了预定义自动化。在控制台的 [Automations](https://app.mintlify.com/products/automations) 页面打开其中任何一个。

详情请参见[预定义自动化](/zh/automations/reference)。

<div id="custom-automations">
  ## 自定义自动化 [#自定义自动化]
</div>

为预定义选项未涵盖的任务创建自定义自动化。自定义自动化让你完全控制触发器、指令和上下文仓库。

设置步骤请参见[创建自定义自动化](/zh/automations/create)。

<div id="write-effective-instructions">
  ### 撰写有效的指令 [#撰写有效的指令]
</div>

自定义自动化指令是 agent 每次运行时遵循的提示词。指令的质量直接影响结果的一致性。

**描述结果，而不仅仅是任务。** 告诉 agent 完成后是什么样子。

<CodeGroup>
  <CodeBlockTabs defaultValue="Less effective" groupId="less-effective+more-effective">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="Less effective">
        Less effective
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="More effective">
        More effective
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="Less effective">
      ```text  
      Review the API reference pages.
      ```
    </CodeBlockTab>

    <CodeBlockTab value="More effective">
      ```text  
      Review every page in the /api-reference directory. For each endpoint, confirm that the request parameters, response fields, and example payloads match the OpenAPI spec in the api/openapi.yaml file. Open a pull request with corrections for any discrepancies you find.
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

**撰写流程。** Agent 遵循按步骤指令比开放式提示词更可靠。

```text title="Example procedure"
1. Read the merged pull request diff from the trigger repository.
2. Identify any changed API endpoints, parameters, or response shapes.
3. Search the documentation for pages that reference those endpoints.
4. Update the affected pages to match the changes in the pull request.
5. Open a pull request with a summary of the pages you changed and why.
```

**保持范围窄。** 一个把单一事情做好的自动化，比一个试图做许多事情的自动化更可靠。将复杂任务拆分到多个自动化中。

**指定文件和目录。** 你对 agent 应查看的位置越精确，它花在搜索上的时间就越少。

```text title="Example with specific paths"
Check every MDX file in the /content directory for broken internal links (links beginning with /). 
For each broken link, either fix the path or remove the link if no replacement exists.
```

<div id="use-context-repositories">
  ### 使用上下文仓库 [#使用上下文仓库]
</div>

对于自定义自动化和部分预定义自动化，你可以添加自动化运行时 agent 会读取的上下文仓库。

在以下情况添加上下文仓库：

* 你的内容引用了存放在独立仓库中的代码、API 或配置。
* 你希望 agent 在决定要更新什么时，将你的内容与源代码进行对比。
* 自动化提示词引用了 Mintlify 项目仓库之外的文件。

每个自动化最多可添加 10 个上下文仓库。

<div id="update-mode">
  ### 更新模式 [#更新模式]
</div>

决定在更改上线前你希望进行多少审查。

* **Update and merge changes**：更改直接合并到你的 Mintlify 项目仓库，无需审查。适用于低风险、高频任务，如翻译、语法检查和链接修复。
* **Modify and wait for review**：agent 打开 pull request，由人工审查后再合并。适用于会改变内容含义的任务，如与代码变更同步或更新 API 参考。

<div id="control-credit-usage">
  ## 控制积分使用量 [#控制积分使用量]
</div>

每次更新文档的自动化运行都消耗 250 个积分，无论 agent 读取多少内容或更改多少页面。未发现需要更新内容的运行不消耗积分。要了解自动化的实际消耗，请查看 [Usage](https://app.mintlify.com/settings/organization/usage) 页面上的 Activity log。

为 cron 任务安排在特定时间运行可以让你更精确地控制积分使用量。例如，让自动化每天或每周运行一次，以限定它每月最多能进行多少次更新。定时安排还会将多个源变更批量合并为一次更新，因此你无需为每个变更单独付费。基于推送触发的自动化在每月之间可能差异更大，因为它们取决于内容或代码变更的频率。

<div id="review-and-improve-automation-results">
  ## 审查并改进自动化结果 [#审查并改进自动化结果]
</div>

自动化是自动运行的，但定期审查会有帮助。

1. 打开 [Automations](https://app.mintlify.com/products/automations) 页面上的 **Runs** 选项卡，查看最近的运行历史和状态。
2. 要查看某次运行的更多信息，请点击 <Icon icon="<svg xmlns=&#x22;http://www.w3.org/2000/svg&#x22; viewBox=&#x22;0 0 24 24&#x22; fill=&#x22;none&#x22;><path d=&#x22;M12 12.002H12.5M19 12.002H19.5M5 12.002H5.5M12 13.002C12.5523 13.002 13 12.5542 13 12.002C13 11.4497 12.5523 11.002 12 11.002C11.4477 11.002 11 11.4497 11 12.002C11 12.5542 11.4477 13.002 12 13.002ZM19 13.002C19.5523 13.002 20 12.5542 20 12.002C20 11.4497 19.5523 11.002 19 11.002C18.4477 11.002 18 11.4497 18 12.002C18 12.5542 18.4477 13.002 19 13.002ZM5 13.002C5.55228 13.002 6 12.5542 6 12.002C6 11.4497 5.55228 11.002 5 11.002C4.44772 11.002 4 11.4497 4 12.002C4 12.5542 4.44772 13.002 5 13.002Z&#x22; stroke=&#x22;currentColor&#x22; stroke-linecap=&#x22;round&#x22; stroke-linejoin=&#x22;round&#x22; stroke-width=&#x22;1.5&#x22;/></svg>" /> 操作菜单按钮并选择 **View run details**，以查看提示词、摘要、文件和 pull request。
3. 如果结果不一致，请优化你的指令：添加更具体的流程、缩小文件范围或将自动化拆分为更小的任务。

启用新自动化后，通常进行几个审查周期就足以微调指令。