mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
locadex-agent[bot]
54bfe783e3
Co-authored-by: locadex-agent[bot] <217277504+locadex-agent[bot]@users.noreply.github.com>
440 lines
17 KiB
Plaintext
440 lines
17 KiB
Plaintext
---
|
||
title: "教程：代码变更时自动更新文档"
|
||
sidebarTitle: "文档更新自动化"
|
||
description: "使用代理 API 自动更新文档。"
|
||
keywords: ["agent automation", "n8n", "GitHub Actions", "automatic doc updates"]
|
||
---
|
||
|
||
<div id="what-you-will-build">
|
||
## 你将构建的内容
|
||
</div>
|
||
|
||
一个自动化流程：当代码推送到主 branch 时自动更新文档。该工作流可在多个平台上搭建，包括 GitHub Actions 和 n8n。它会监控你的代码存储库，然后调用代理 API，在单独的文档存储库中更新文档。
|
||
|
||
此工作流连接两个独立的存储库：
|
||
|
||
* **代码存储库**：用于存放应用程序代码。你将在此存储库上设置自动化触发器。示例包括后端 API、前端应用、SDK，或命令行界面（CLI）工具。
|
||
* **文档存储库**：用于存放文档并连接到你的 Mintlify 项目。代理会在此存储库中创建包含文档更新的拉取请求（PR；亦称“合并请求”/Merge Request）。
|
||
|
||
本教程假设你的文档与应用程序代码位于不同的存储库中。如果你使用 monorepo，请修改工作流以定位存放文档的目录。
|
||
|
||
<div id="workflow-overview">
|
||
### 工作流概览
|
||
</div>
|
||
|
||
1. 有人将代码推送到你的主分支。
|
||
2. 工作流被触发。
|
||
3. 工作流调用代理的 API 来更新你的文档。
|
||
4. 代理在你的文档存储库中创建一个包含文档更新的拉取请求（PR）。
|
||
|
||
<div id="choose-your-platform">
|
||
## 选择你的平台
|
||
</div>
|
||
|
||
<Tabs>
|
||
<Tab title="GitHub Actions">
|
||
如果您的代码已在 GitHub 上,GitHub Actions 是最简单的选择。无需额外服务。
|
||
|
||
## 前提条件
|
||
|
||
* 已在代码和文档仓库中启用 GitHub Actions
|
||
* 已在代码和文档仓库中安装 [Mintlify GitHub 应用](/zh/deploy/github)
|
||
* [Mintlify 管理 API 密钥](https://dashboard.mintlify.com/settings/organization/api-keys)
|
||
* [Mintlify 项目 ID](https://dashboard.mintlify.com/settings/organization/api-keys)
|
||
* [Mintlify Enterprise 方案](https://mintlify.com/pricing)
|
||
* 对存放您代码和文档的 GitHub 仓库拥有管理员权限
|
||
|
||
### 在代码存储库中安装 Mintlify 应用
|
||
|
||
必须在您的代码存储库中安装 Mintlify 应用,以便 agent 能够从代码库获取上下文信息。要将应用添加到新存储库:
|
||
|
||
1. 在 Mintlify 控制台中打开 Agent 面板。
|
||
|
||
<Frame>
|
||
<img src="/images/agent/dashboard-light.png" alt="浅色模式下的 Agent 面板。" className="block dark:hidden" />
|
||
|
||
<img src="/images/agent/dashboard-dark.png" alt="深色模式下的 Agent 面板。" className="hidden dark:block" />
|
||
</Frame>
|
||
2. 点击 **Settings** 按钮。
|
||
|
||
<Frame>
|
||
<img src="/images/agent/dashboard-settings-light.png" alt="浅色模式下的设置按钮。" className="block dark:hidden" />
|
||
|
||
<img src="/images/agent/dashboard-settings-dark.png" alt="深色模式下的设置按钮。" className="hidden dark:block" />
|
||
</Frame>
|
||
3. Click **Add to New Organization**。这会打开 GitHub 上的应用安装页面。
|
||
4. 从列表中选择要授予访问权限的仓库。
|
||
5. 保存更改。
|
||
|
||
### 获取管理员 API 密钥
|
||
|
||
1. 在控制台中打开 [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) 页面。
|
||
2. 选择 **Create Admin API Key**。
|
||
3. 将该密钥复制并安全保存。
|
||
|
||
## 构建工作流
|
||
|
||
### 创建工作流文件
|
||
|
||
1. 在代码仓库中创建一个新文件：`.github/workflows/update-docs.yml`
|
||
2. 添加以下工作流：
|
||
|
||
```yaml
|
||
name: Update Docs
|
||
|
||
on:
|
||
push:
|
||
branches:
|
||
- main
|
||
|
||
jobs:
|
||
update-docs:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- uses: actions/github-script@v8
|
||
env:
|
||
MINTLIFY_API_KEY: ${{ secrets.MINTLIFY_API_KEY }}
|
||
PROJECT_ID: ${{ secrets.MINTLIFY_PROJECT_ID }}
|
||
with:
|
||
script: |
|
||
const { owner, repo } = context.repo;
|
||
const projectId = process.env.PROJECT_ID;
|
||
const apiKey = process.env.MINTLIFY_API_KEY;
|
||
|
||
if (!projectId || !apiKey) {
|
||
core.setFailed('Missing MINTLIFY_PROJECT_ID or MINTLIFY_API_KEY secrets');
|
||
return;
|
||
}
|
||
|
||
const url = `https://api.mintlify.com/v1/agent/${projectId}/job`;
|
||
const payload = {
|
||
branch: `mintlify/docs-update-${Date.now()}`,
|
||
messages: [
|
||
{
|
||
role: 'system',
|
||
content: '你是一个根据代码变更自动更新文档的操作执行器。你不应该提出任何问题。如果无法访问存储库,请报告错误并退出。'
|
||
},
|
||
{
|
||
role: 'user',
|
||
content: `Update the documentation for our recent pushes to main:\n\nRepository: ${owner}/${repo}`
|
||
}
|
||
],
|
||
asDraft: false
|
||
};
|
||
|
||
try {
|
||
const response = await fetch(url, {
|
||
method: 'POST',
|
||
headers: {
|
||
'Authorization': `Bearer ${apiKey}`,
|
||
'Content-Type': 'application/json'
|
||
},
|
||
body: JSON.stringify(payload)
|
||
});
|
||
|
||
if (!response.ok) {
|
||
throw new Error(`API request failed with status ${response.status}: ${await response.text()}`);
|
||
}
|
||
|
||
const reader = response.body.getReader();
|
||
const decoder = new TextDecoder();
|
||
let buffer = '';
|
||
|
||
while (true) {
|
||
const { done, value } = await reader.read();
|
||
if (done) break;
|
||
buffer += decoder.decode(value, { stream: true });
|
||
const lines = buffer.split('\n');
|
||
buffer = lines.pop() || '';
|
||
for (const line of lines) {
|
||
if (line.trim()) {
|
||
console.log(line);
|
||
}
|
||
}
|
||
}
|
||
if (buffer.trim()) {
|
||
console.log(buffer);
|
||
}
|
||
|
||
core.notice(`Documentation update job triggered for ${owner}/${repo}`);
|
||
} catch (error) {
|
||
core.setFailed(`Failed to create documentation update job: ${error.message}`);
|
||
}
|
||
```
|
||
|
||
### 添加密钥
|
||
|
||
1. 在代码存储库中，依次点击 **Settings** → **Secrets and variables** → **Actions**。
|
||
2. 点击 **New repository secret** 按钮。
|
||
3. 添加以下机密：
|
||
* 名称：`MINTLIFY_API_KEY`，Secret：您的 Mintlify 管理员 API 密钥
|
||
* 名称：`MINTLIFY_PROJECT_ID`，Secret：您的 Mintlify 项目 ID（可在仪表盘的 [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) 页面找到）
|
||
|
||
更多信息请参阅 GitHub 文档中的[在 GitHub Actions 中使用密钥](https://docs.github.com/en/actions/how-tos/write-workflows/choose-what-workflows-do/use-secrets)。
|
||
|
||
## 测试自动化
|
||
|
||
1. 在你的代码仓库中做一个小改动，并推送到 main 分支：
|
||
```bash
|
||
git add .
|
||
git commit -m "测试:触发文档自动化"
|
||
git push origin main
|
||
```
|
||
|
||
2. 在代码仓库中打开 **Actions** 选项卡，查看工作流的运行情况。
|
||
|
||
3. 工作流运行完成后，查看你的文档仓库中是否已创建包含文档更新的新分支和拉取请求（pull request）。
|
||
|
||
## 故障排除
|
||
|
||
### 工作流未运行
|
||
|
||
* 请确认你的代码仓库已启用 GitHub Actions。
|
||
* 在 **Actions** 标签页中查看错误信息。
|
||
* 确保工作流文件位于 `.github/workflows/` 目录下，且文件扩展名为 `.yml`。
|
||
|
||
### 代理 API 返回 401 错误
|
||
|
||
* 请确认你的 API 密钥以 `mint_` 开头。
|
||
* 检查 Authorization 请求头的格式是否为 `Bearer mint_yourkey`。
|
||
* 确认该 API 密钥对应的是正确的 Mintlify 组织。
|
||
|
||
### 文档更新未显示
|
||
|
||
* 确认文档仓库已连接到你的 Mintlify 项目。
|
||
* 确认代理对文档存储库拥有写入权限。
|
||
* 在工作流日志中检查来自代理的错误信息。
|
||
</Tab>
|
||
|
||
<Tab title="n8n">
|
||
n8n 提供可视化工作流编辑器,并可与多种服务集成。
|
||
|
||
## 前提条件
|
||
|
||
* n8n 工作区
|
||
* [Mintlify Enterprise 方案](https://mintlify.com/pricing)
|
||
* 已在你的代码仓库中安装 Mintlify 应用
|
||
* Mintlify 管理 API 密钥
|
||
* 对用于存放您代码和文档的 GitHub 仓库具有管理员权限
|
||
* GitHub 个人访问令牌
|
||
|
||
### 在代码存储库中安装 Mintlify 应用
|
||
|
||
必须在您的代码存储库中安装 Mintlify 应用,以便 agent 能够从代码库获取上下文信息。要将应用添加到新存储库:
|
||
|
||
1. 在 Mintlify 控制台中打开 agent 面板。
|
||
|
||
<Frame>
|
||
<img src="/images/agent/dashboard-light.png" alt="浅色模式下的 Agent 面板。" className="block dark:hidden" />
|
||
|
||
<img src="/images/agent/dashboard-dark.png" alt="深色模式下的 Agent 面板。" className="hidden dark:block" />
|
||
</Frame>
|
||
2. 点击 **Settings** 按钮。
|
||
|
||
<Frame>
|
||
<img src="/images/agent/dashboard-settings-light.png" alt="浅色模式下的设置按钮。" className="block dark:hidden" />
|
||
|
||
<img src="/images/agent/dashboard-settings-dark.png" alt="深色模式下的设置按钮。" className="hidden dark:block" />
|
||
</Frame>
|
||
3. 点击 **Add to New Organization**。这会打开 GitHub 上的应用安装页面。
|
||
4. 从列表中选择要授予访问权限的仓库。
|
||
5. 保存更改。
|
||
|
||
### 获取管理员 API 密钥
|
||
|
||
1. 在控制台中打开 [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) 页面。
|
||
2. 选择 **Create Admin API Key**。
|
||
3. 将该密钥复制并安全保存。
|
||
|
||
### 获取 GitHub 个人访问令牌
|
||
|
||
1. 在 GitHub 中，进入 **Settings**。
|
||
2. 点击 **Developer settings**。
|
||
3. 点击 **Personal access tokens**（个人访问令牌）。
|
||
4. 点击 **Tokens (classic)**。
|
||
5. 点击 **Generate new token (classic)** 按钮。
|
||
6. 选择以下权限范围：
|
||
* `repo`（对私有仓库拥有完全控制权限）
|
||
* `admin:repo_hook`（如果你希望由 n8n 自动创建 webhooks）
|
||
7. 生成令牌并妥善保存。
|
||
|
||
更多信息请参阅 GitHub 文档中的[创建个人访问令牌(经典版)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens?versionId=free-pro-team%40latest\&productId=account-and-profile#creating-a-personal-access-token-classic)。
|
||
|
||
## 构建工作流
|
||
|
||
### 创建 webhook 触发器
|
||
|
||
1. 在 n8n 中创建一个新工作流。
|
||
2. 添加一个 Webhook 节点。
|
||
3. 配置 webhook：
|
||
* HTTP 方法：`POST`
|
||
* 路径：`auto-update-documentation`（或任何唯一路径）
|
||
* 认证：无
|
||
* 响应：立即返回
|
||
4. 保存工作流。
|
||
5. 复制生产环境的 webhook URL，其格式类似于：`https://your-n8n-instance.app.n8n.cloud/webhook/auto-update-documentation`
|
||
|
||
<Frame>
|
||
<img
|
||
src="/images/guides/n8n/webhook-node.png"
|
||
alt="Webhook 节点配置截图。"
|
||
style={{
|
||
width: 'auto',
|
||
height: '700px',
|
||
}}
|
||
/>
|
||
</Frame>
|
||
|
||
### 设置 GitHub webhook
|
||
|
||
1. 在 GitHub 上打开你的代码存储库。
|
||
2. 点击 **Settings**。
|
||
3. 点击 **Webhooks**。
|
||
4. 点击 **Add webhook**。
|
||
5. 配置 webhook：
|
||
* Payload URL：在此粘贴你的 n8n webhook URL
|
||
* Content type：`application/json`
|
||
* Which events would you like to trigger this webhook?（希望由哪些事件来触发该 webhook？）
|
||
* 选择 **Let me select individual events.**
|
||
* 仅选择 **Push events**。
|
||
* 选择 **Active**
|
||
6. 点击 **Add webhook**。
|
||
|
||
### 筛选主 branch 推送
|
||
|
||
在 webhook 之后添加代码节点,以筛选推送到 main 分支的事件并提取相关信息。
|
||
|
||
1. 添加一个 Code 节点。
|
||
2. 将其命名为 "Filter main pushes."
|
||
3. 将模式设置为 **Run Once for All Items**（对所有条目仅运行一次）。
|
||
4. 添加以下 JavaScript 代码：
|
||
|
||
```javascript
|
||
const webhookData = $input.first().json.body;
|
||
|
||
// Only continue if this is a push to main
|
||
if (webhookData.ref !== "refs/heads/main") {
|
||
return [];
|
||
}
|
||
|
||
// Extract information
|
||
const repository = webhookData.repository;
|
||
const pusher = webhookData.pusher;
|
||
|
||
// Build message for agent
|
||
const agentMessage = `更新 ${repository.name} 中推送到 main 分支的变更文档。始终编辑文件并创建拉取请求（PR；亦称"合并请求"/Merge Request）。`;
|
||
|
||
return {
|
||
json: {
|
||
codeRepoName: repository.full_name,
|
||
codeRepoShortName: repository.name,
|
||
agentMessage: agentMessage
|
||
}
|
||
};
|
||
```
|
||
|
||
<Frame>
|
||
<img src="/images/guides/n8n/filter-merged-PRs-node.png" alt="“Filter main pushes” 节点配置截图。" />
|
||
</Frame>
|
||
|
||
此代码会在推送不是到 main 分支时停止工作流,从 GitHub webhook 中提取所有相关信息,并为 agent API 创建消息。
|
||
|
||
### 调用 Agent API
|
||
|
||
添加 HTTP 请求节点以创建文档任务。
|
||
|
||
1. 添加一个 HTTP 请求节点。
|
||
2. 将其命名为“Create agent job.”。
|
||
3. 配置请求：
|
||
|
||
* 方法：`POST`
|
||
* URL：`https://api.mintlify.com/v1/agent/YOUR_PROJECT_ID/job`（将 `YOUR_PROJECT_ID` 替换为你在 [API keys](https://dashboard.mintlify.com/settings/organization/api-keys) 页面中的项目 ID）
|
||
* 认证：Generic Credential Type → Header Auth
|
||
* 创建一个新的凭证：
|
||
* Name：`Authorization`
|
||
* Value：`Bearer mint_YOUR_API_KEY`（替换为你的 API 密钥）
|
||
* Send Body：On（启用请求体）
|
||
* Body Content Type：JSON（请求体内容类型）
|
||
* Specify Body：Using JSON（使用 JSON 指定请求体）
|
||
* 添加以下 JSON：
|
||
|
||
```json
|
||
{
|
||
"branch": "docs-update-from-{{ $json.codeRepoShortName }}-{{ $now.toISOString() }}",
|
||
"messages": [
|
||
{
|
||
"role": "system",
|
||
"content": "{{ $json.agentMessage }}"
|
||
}
|
||
],
|
||
"asDraft": false
|
||
}
|
||
```
|
||
|
||
<Frame>
|
||
<img
|
||
src="/images/guides/n8n/create-agent-job-node.png"
|
||
alt="“Create agent job” 节点配置界面的截图。"
|
||
style={{
|
||
width: 'auto',
|
||
height: '700px',
|
||
}}
|
||
/>
|
||
</Frame>
|
||
|
||
代理会在您的文档存储库中创建一个拉取请求（PR；亦称"合并请求"/Merge Request），使用包含源存储库名称和时间戳的描述性 branch 名称。
|
||
|
||
### 激活工作流
|
||
|
||
1. 保存工作流。
|
||
2. 将其设为激活状态。
|
||
|
||
您的工作流现在正在监控代码存储库向 main 分支的推送。
|
||
|
||
<Frame>
|
||
<img src="/images/guides/n8n/workflow.png" alt="n8n 编辑器中自动化工作流界面的截图。" />
|
||
</Frame>
|
||
|
||
## 测试自动化
|
||
|
||
1. 在代码仓库中创建测试分支：
|
||
```bash
|
||
git checkout -b test-docs-automation
|
||
```
|
||
|
||
2. 做一个小改动并提交：
|
||
```bash
|
||
git add .
|
||
git commit -m "测试:触发文档自动化"
|
||
git push origin test-docs-automation
|
||
```
|
||
|
||
3. 在 GitHub 上创建一个拉取请求（PR；亦称“合并请求”/Merge Request）。
|
||
|
||
4. 合并该拉取请求（PR；亦称“合并请求”/Merge Request）。
|
||
|
||
### 验证自动化
|
||
|
||
您应该会看到一个新的 n8n 执行记录,其中所有节点都已成功完成,同时在您的文档存储库中会创建一个新 branch 和拉取请求(PR;亦称"合并请求"/Merge Request)。
|
||
|
||
## 故障排除
|
||
|
||
### Webhook 未触发
|
||
|
||
* 确认该工作流在 n8n 中处于激活状态。
|
||
* 在 GitHub 仓库的“Settings → Webhooks → Recent Deliveries”中查看响应状态码。
|
||
* 确保 webhook URL 与你的 n8n webhook URL 完全一致。
|
||
|
||
### 代理 API 返回 401 错误
|
||
|
||
* 请确认你的 API 密钥以 `mint_` 开头。
|
||
* 检查 Authorization 请求头的格式是否为 `Bearer mint_yourkey`。
|
||
* 确认该 API 密钥属于正确的 Mintlify 组织。
|
||
|
||
### GitHub 401 错误
|
||
|
||
* 确认你的令牌已包含 `repo` 权限范围。
|
||
* 确认该 token 尚未过期。
|
||
* 请确认你在发往 GitHub 的请求中包含了 `User-Agent` 请求头。
|
||
</Tab>
|
||
</Tabs> |