mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
f09bcffa35
* docs: document deployment branch lock in editor settings * docs: mirror deployment branch lock translations (fr, es, zh) * docs: warn that locking discards unpublished editor changes * Apply suggestions from code review Co-authored-by: Denzell <32852291+cdxker@users.noreply.github.com> * Apply suggestion from @ethanpalm --------- Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com> Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Co-authored-by: Denzell <32852291+cdxker@users.noreply.github.com>
174 lines
7.3 KiB
Plaintext
174 lines
7.3 KiB
Plaintext
---
|
||
title: "用于 AI 与发布的编辑器设置"
|
||
description: "配置 AI 指令、pull request 默认值、草稿行为以及默认合并方式，以控制 Mintlify Web 编辑器发布变更的方式。"
|
||
keywords: ["编辑器", "设置", "ai", "指令", "发布", "pull request", "草稿", "合并", "锁定分支"]
|
||
---
|
||
|
||
Web 编辑器有两层设置：
|
||
|
||
- **个人设置**仅对你生效，控制编辑器的 AI 在你编辑时如何提供协助。
|
||
- **发布设置**对部署中的所有人生效，决定变更在被提交并转换为 pull request 时如何处理。
|
||
|
||
你可以在编辑器的 **Settings** 菜单中配置这两项。
|
||
|
||
<div id="ai-instructions">
|
||
## AI 指令
|
||
</div>
|
||
|
||
AI 指令是编辑器随你的请求一起发送给 AI 的持续生效指令。用它来固定你不想在每次提示中都重复的风格和语气规则，例如语气、术语或格式约定。
|
||
|
||
你的指令适用于：
|
||
|
||
- 对选中文本的 **Edit with AI** 操作，如改写、扩写或修正。
|
||
- 从编辑器中启动的 **agent 会话**。
|
||
|
||
指令的作用范围是你的用户账号，因此每位团队成员维护各自的指令。
|
||
|
||
<div id="when-to-use-ai-instructions">
|
||
### 何时使用 AI 指令
|
||
</div>
|
||
|
||
当你发现自己在提示中反复给出相同的指引时，就应该添加 AI 指令，例如：
|
||
|
||
- 强制使用第二人称或句首大写式的标题。
|
||
- 优先使用特定的产品名称或术语。
|
||
- 禁用营销用语或填充性短语。
|
||
- 要求使用特定组件，例如始终使用 `<Note>` 表示提示。
|
||
|
||
保持指令简短而具体。AI 会在每次请求时遵循它们，模糊或相互矛盾的规则会降低效果。
|
||
|
||
<div id="configure-ai-instructions">
|
||
### 配置 AI 指令
|
||
</div>
|
||
|
||
1. 打开编辑器，点击工具栏中的头像。
|
||
2. 选择 **Settings**。
|
||
3. 在 **AI instructions** 字段中输入希望 AI 遵循的指令。
|
||
4. 保存更改。
|
||
|
||
示例：
|
||
|
||
```text
|
||
- Use second person ("you") and active voice.
|
||
- Use sentence case for all headings.
|
||
- Refer to the product as "Acme" — never "Acme Inc." or "the platform".
|
||
- Wrap notes and warnings in <Note> or <Warning> components.
|
||
- Do not add introductory filler like "In this guide" or "Let's explore".
|
||
```
|
||
|
||
将该字段留空以移除你的指令。
|
||
|
||
<div id="publishing-settings">
|
||
## 发布设置
|
||
</div>
|
||
|
||
发布设置按部署进行配置，对所有从编辑器发布的人都生效。它们控制 pull request 和提交的生成、打开和合并方式。
|
||
|
||
你需要拥有 Mintlify 部署的管理员权限才能更改发布设置。
|
||
|
||
<div id="lock-the-deployment-branch">
|
||
### 锁定部署分支
|
||
</div>
|
||
|
||
启用此选项可将你的部署分支（通常是 `main`）在编辑器中设为只读。分支被锁定后：
|
||
|
||
- 对于查看部署分支的所有人，编辑器和源代码视图都变为只读。
|
||
- `docs.json` 配置面板停止保存更改。
|
||
- 导航编辑（添加页面、重新排序和拖放）会被隐藏。
|
||
- 横幅会提示贡献者先创建草稿分支再进行编辑。
|
||
|
||
你的部署分支仍与 Git 保持同步，因此从仓库推送仍会更新线上站点。锁定只影响在编辑器中所做的更改。
|
||
|
||
<Warning>
|
||
开启锁定会丢弃部署分支上所有未发布的编辑器更改，并强制将编辑器与你的 Git 仓库重新同步。在开启锁定之前，请先发布待处理的编辑，或将其移动到草稿分支。
|
||
</Warning>
|
||
|
||
在锁定开启期间，向部署分支推送的 Git 提交会覆盖编辑器的实时状态，因此该分支上任何进行中的编辑都会被最新的提交替换。
|
||
|
||
当你的团队希望 Git 继续作为线上站点的唯一可信来源，并让所有编辑器更改都通过从草稿分支发起的 pull request 提交时，可使用此设置。
|
||
|
||
在部署分支被锁定时进行编辑，请使用顶栏中的分支选择器创建或切换到草稿分支。像其他编辑器分支一样，从你的草稿分支发起 pull request 即可发布这些更改。
|
||
|
||
<div id="pull-request-instructions">
|
||
### Pull request 指令
|
||
</div>
|
||
|
||
Pull request 指令用于在 AI 生成 pull request 标题和描述时进行引导。每当编辑器代你打开 pull request 时都会应用，包括 **Create pull request** 和 **Merge and publish** 流程。
|
||
|
||
使用 pull request 指令来标准化审阅者看到的内容，例如：
|
||
|
||
- 必需的小节，如 **Summary** 和 **Changes**。
|
||
- 链接到跟踪系统的描述模板。
|
||
- 对标题的语气或长度要求。
|
||
|
||
示例：
|
||
|
||
```text
|
||
Title: imperative mood, under 70 characters, no trailing period.
|
||
Description: include a "## Summary" section (one sentence) and a
|
||
"## Changes" section as a bulleted list. Link any referenced page
|
||
using its relative path.
|
||
```
|
||
|
||
<div id="create-pull-requests-as-drafts-by-default">
|
||
### 默认以草稿形式创建 pull request
|
||
</div>
|
||
|
||
开启该选项后，编辑器会以草稿状态打开每个新的 pull request。在将草稿 pull request 标记为可审阅之前，无法将其合并。该功能在以下场景中很有用：
|
||
|
||
- 你的团队要求在 pull request 开放审批前先进行一次人工审阅。
|
||
- 你希望分享预览 URL，但不希望传递"已准备好合并"的信号。
|
||
|
||
你仍然可以在 Git 提供商中将 pull request 标记为可审阅。
|
||
|
||
<div id="default-merge-method">
|
||
### 默认合并方式
|
||
</div>
|
||
|
||
选择在你点击 **Merge and publish** 时编辑器使用的合并方式：
|
||
|
||
- **Merge**：创建一个合并提交，保留分支的完整历史。
|
||
- **Squash**：将分支上的所有提交合并为部署分支上的单个提交。
|
||
- **Rebase**：将分支上的每个提交逐个重放到部署分支，不产生合并提交。
|
||
|
||
所选方式将作为默认值。如果你通过 API 或 Git 提供商的界面显式传入合并方式，那种方式将优先生效。
|
||
|
||
<Tip>
|
||
请让默认合并方式与 Git 提供商的分支保护设置一致。如果你的部署分支只允许 squash 合并，请将默认值设为 **Squash**，以避免从编辑器合并失败。
|
||
</Tip>
|
||
|
||
<div id="danger-zone">
|
||
## Danger zone
|
||
</div>
|
||
|
||
编辑器设置面板中的 **Danger zone** 区域包含无法撤销的操作。点击编辑器工具栏中的 <Icon icon="settings" /> 设置图标打开设置，然后滚动到 **Danger zone**。
|
||
|
||
<div id="reset-editor">
|
||
### Reset editor
|
||
</div>
|
||
|
||
**Reset editor** 会强制编辑器丢弃其本地状态并从你的 Git 仓库重新同步。当编辑器与仓库出现同步问题时使用它 —— 例如，文件树为空，或者即使文件确实存在于你的部署分支上、线上站点也在正常构建，编辑器仍显示类似 `Unable to find docs.json or mint.json` 的错误。
|
||
|
||
<Warning>
|
||
重置编辑器会丢弃任何尚未提交到 Git 的未发布更改。如果你有想要保留的待处理编辑，请先发布它们。
|
||
</Warning>
|
||
|
||
重置编辑器的步骤：
|
||
|
||
1. 点击编辑器工具栏中的 <Icon icon="settings" /> 设置图标。
|
||
2. 滚动到 **Danger zone**。
|
||
3. 点击 **Reset editor** 并确认。
|
||
|
||
编辑器会重新加载并从你的仓库拉取最新状态。
|
||
|
||
<Tip>
|
||
**Reset editor** 操作位于编辑器的设置面板中，而不是控制台设置的 [Danger zone](https://app.mintlify.com/settings/organization/danger-zone) 中。控制台的 Danger zone 仅用于[删除部署](/zh/deploy/deployments#delete-a-deployment)。
|
||
</Tip>
|
||
|
||
<div id="related">
|
||
## 相关内容
|
||
</div>
|
||
|
||
- [发布](/zh/editor/publish)
|
||
- [配置](/zh/editor/configurations)
|