mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
b34afc88b6
* docs: fix es/fr/zh translation lag and add missing zh workflows redirects * docs: SEO metadata fixes and HTML entity cleanup in touched locale pages --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
128 lines
6.4 KiB
Plaintext
128 lines
6.4 KiB
Plaintext
---
|
||
title: "使用自动化"
|
||
description: "使用 Mintlify 自动化来自动执行周期性的文档维护：选择合适的触发器、撰写有效的指令，并获得一致的 agent 结果。"
|
||
keywords: ["automations", "automation", "automate", "automation guide", "automation instructions", "agent automation", "self updating"]
|
||
---
|
||
|
||
自动化会自动运行 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>
|
||
```text Less effective
|
||
Review the API reference pages.
|
||
```
|
||
|
||
```text More effective
|
||
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.
|
||
```
|
||
</CodeGroup>
|
||
|
||
**撰写流程。** Agent 遵循按步骤指令比开放式提示词更可靠。
|
||
|
||
```text 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 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="ellipsis" /> 操作菜单按钮并选择 **View run details**，以查看提示词、摘要、文件和 pull request。
|
||
3. 如果结果不一致，请优化你的指令：添加更具体的流程、缩小文件范围或将自动化拆分为更小的任务。
|
||
|
||
启用新自动化后，通常进行几个审查周期就足以微调指令。
|