Skip to content

template-ai.zh-CN.md

Latest commit

 

History

History
326 lines (195 loc) · 12.9 KB

template-ai.zh-CN.md

File metadata and controls

326 lines (195 loc) · 12.9 KB
Raw

English | 简体中文

AI 模板编辑

SublinkPro 为模板编辑器提供 AI 辅助编辑会话工作流。您用自然语言描述想改什么，AI 给出结构化编辑操作，服务端生成并校验预览，然后您再决定是否接受到普通编辑器中。

这个功能始终把控制权留给用户。AI 不再把完整模板作为输出返回。它只返回精确的 replace、insert、delete 操作。服务端将这些操作应用到当前模板，完成预览校验，并显示只读对比视图。

✨ 核心功能

功能 说明
🧠 自然语言改模板 直接输入想怎么改，AI 会基于当前模板提出结构化操作
🪟 编辑器内浮动命令栏 AI 指令输入框悬浮在代码编辑区上方，不会打断正常编辑流程
🔍 只读预览对比 接受前先并排审阅原始模板和服务端生成的候选预览
✅ 接受到编辑器 接受预览会把候选内容复制到编辑器，但不会自动保存模板
⚠️ 校验警告 校验错误会阻止接受；警告用于提示需要关注的内容，不需要额外确认
🧹 丢弃预览 当预览不合适或会话过期时，可以丢弃编辑会话
⚙️ 系统级设置接入 模板 AI 使用系统中的 设置 -> AI 助手 作为配置入口

🧭 适用场景

AI 模板编辑特别适合下面这些任务：

  • 为现有模板补充新的代理组、规则段或注释
  • 在不大改整体结构的前提下，优化模板可读性
  • 在长模板中做定向修改，而不是要求模型重写整份文件
  • 在编辑器内容改变前，通过对比视图审阅精确变更

它更适合“基于已有模板，通过可审阅操作进行编辑”，而不是完全替代您的审阅过程。

🚀 开始前需要准备什么

要使用模板 AI，您需要先完成 AI 助手设置。

进入：

设置 -> AI 助手

至少需要完成这些配置：

  • Base URL
  • 模型名称
  • API Key

请根据服务商能力选择 接口类型：

  • Responses API 调用 /responses。
  • Chat Completions API 调用 /chat/completions。

可选的 Max Tokens 默认值为 400000；如果在设置页填写 0，系统会使用该服务端默认值。

Tip

模板编辑器中的 AI 功能使用的是 设置 -> AI 助手 中保存的系统级配置。建议先完成配置并测试连接，再回到模板编辑器。

如果模板页提示：

  • AI 助手当前不可用
  • AI 设置不完整

请前往：

设置 -> AI 助手

检查是否已启用 AI，并确认 Base URL、模型名称和 API Key 已正确填写。

同时请确认该 Base URL 对应的 AI 服务实际支持当前选择的接口类型。

📝 使用流程

1. 打开模板编辑器

进入模板管理页面后，您可以：

  • 新建模板
  • 编辑已有模板

在编辑器中先准备一份基础模板内容，再输入 AI 指令会更稳定。

2. 输入 AI 指令

在编辑器上方的浮动 AI 命令栏中，用自然语言描述您希望的改动。

例如：

  • 保留现有结构，增加一个自动选择香港节点的策略组
  • 不要移除注释，帮我把规则段整理得更清晰
  • 只替换 DNS 注释块，保持代理组不变
  • 删除所有美国节点条目

3. 启动编辑会话

点击 生成 后，系统会通过下面的接口创建一个短期编辑会话：

  • POST /api/v1/template/ai/edit-sessions/stream

请求会包含当前模板正文、文件名、分类、规则来源、代理选项、include-all 设置以及您的提示词。模型会获得足够上下文来提出定向操作，尤其适合长模板；但候选预览始终以服务端生成和校验的结果为准。

模型只返回操作列表。v1 支持的操作是：

  • replace：用 newString 替换精确匹配的 oldString
  • insert：在精确匹配的 anchor 之前或之后插入 newString
  • delete：删除精确匹配的 oldString

replace 和 delete 还可以带可选的 match。省略 match 时默认是 unique：精确目标必须只出现一次，重复出现仍会以 PATCH_AMBIGUOUS_MATCH 失败。当用户明确要求“全部”“所有”或“每一个”匹配项时，例如“删除所有美国节点条目”，模型可以使用 "match":"all"，让服务端把同一个精确 oldString 应用到所有出现位置。如果没有任何出现位置，预览会以 PATCH_NO_MATCH 失败。insert 不支持 "match":"all"；插入锚点必须保持精确且唯一。

v1 会把操作应用到当前模板中的精确文本目标。服务端根据这些操作生成候选内容，然后先校验候选内容，预览才会进入就绪状态。它不会使用模糊匹配、正则、YAML 路径、AST 编辑或仅基于行号的编辑。

4. 审阅服务端预览

服务端会以原子方式应用操作。如果任意一个操作无法应用，这次预览就不会进入就绪状态。

预览就绪后，编辑器会自动进入 对比模式。这个视图是只读的。左侧显示编辑会话开始时的原始文本，右侧显示服务端生成的候选预览。

5. 接受或丢弃

如果校验有错误，接受会被阻止。如果只有校验警告，您在审阅后仍然可以接受预览。警告是需要关注的元数据，不是额外的确认门槛。

接受预览会把候选内容复制到编辑器。它不会把模板保存到磁盘。完成最终调整后，请使用普通模板保存动作；如果界面显示保存确认，也需要按正常流程确认。

您可以在最终保存前连续接受多个 AI 预览。第一次接受后，下一次编辑会话会基于已经包含未保存接受内容的编辑器正文。接受下一次预览时，客户端会把当前编辑器正文作为 currentText 发送给服务端，用来证明编辑器基准仍然匹配该会话基准。currentText 不会被保存，也不是候选输出；它只用于安全支持连续接受。

丢弃预览会结束编辑会话，不会改变编辑器内容。

🔍 如何审阅 AI 结果

模板编辑器支持两种主视图：

编辑模式

  • 用于直接修改当前模板内容
  • 适合做最终手工微调
  • 只有在编辑模式下才能保存模板

对比模式

  • 左侧显示编辑会话中的原始模板快照
  • 右侧显示服务端生成的候选预览
  • 适合像查看代码变更一样快速确认改动
  • 设计上是只读视图，因此不能直接保存

如果您只是想判断 AI 有没有改对，优先看 对比模式。

如果您已经决定采纳这次结果，再点击 接受预览，将候选内容复制到编辑器。

✅ 接受、丢弃与保存

接受预览

点击浮动命令栏中的 对勾按钮，会接受当前预览。

接受后的特点：

  • 编辑器正文会变成候选预览内容
  • 您可以继续手工修改
  • 您可以在保存前继续生成并接受另一个 AI 预览
  • 之后可以正常保存模板
  • 接受动作本身不会持久化模板

连续接受多个预览时，每次接受仍会检查会话基准是否有效。当提交的 currentText 与会话基准一致时，它可以证明当前编辑器仍基于该会话。如果没有提交 currentText，或内容不匹配，服务端会改为检查已保存的模板文件。如果编辑器不再匹配会话基准，并且磁盘上的模板也已经变化，接受会被 AI_EDIT_STALE_BASE 阻止，避免旧预览覆盖更新内容。

校验警告

当预览可用但需要额外注意时，系统可能给出警告，例如规则来源相关警告。警告用于提示您在接受或保存前重点审阅哪些内容。

警告不会阻止接受。只有校验错误会阻止预览进入编辑器。

丢弃预览

当预览不合适，或您想重新开始时，可以丢弃预览。丢弃会清理编辑会话状态，不会改变编辑器正文。

Important

AI 编辑不会自动写入模板。只有接受预览后，候选内容才会进入编辑器；只有使用普通保存动作后，模板才会保存。

📡 API 合约摘要

编辑会话 API 位于 /api/v1/template/ai 下，并且需要认证。

v1 最终路由：

  • POST /api/v1/template/ai/edit-sessions/stream：创建编辑会话，并流式返回操作生成、服务端补丁应用、预览校验和预览就绪状态
  • GET /api/v1/template/ai/edit-sessions/:sessionId：读取当前会话的预览状态
  • POST /api/v1/template/ai/edit-sessions/:sessionId/accept：接受已就绪预览，并返回要复制到编辑器的候选文本。客户端应提交可选的 currentText，也就是当前编辑器正文，作为基准证明；前面已有未保存接受内容时尤其应该提交
  • POST /api/v1/template/ai/edit-sessions/:sessionId/discard：丢弃会话

流式事件：

  • template.edit.session.created
  • template.edit.model.delta
  • template.edit.operations.ready
  • template.edit.preview.validating
  • template.edit.preview.ready
  • template.edit.warning
  • template.edit.error
  • template.edit.completed

编辑会话是短期状态。v1 TTL 为 15m，系统会定期清理，会话只保存在内存中。它不是持久化编辑历史。会话过期后，请重新生成预览。

旧的完整模板生成合约已经移除。模型输出不能是完整模板 candidateText。新流程中的任何 candidateText 字段都表示服务端根据操作生成并校验后的候选预览，用于复制到编辑器。

💡 实用提示

1. 先给 AI 一个明确边界

比起简单说“帮我优化”，更推荐说明：

  • 要保留什么
  • 想新增什么
  • 哪些段落不要碰

例如：

保留现有注释和节点占位结构，只新增一个手动切换的日本策略组。

2. 长模板建议请求定向修改

如果模板较长，建议一次只处理一个明确目标：

  1. 先调整策略组。
  2. 再整理规则段。
  3. 最后优化注释或命名。

系统会围绕精确文本生成结构化操作，这比要求模型重写整份文件更安全。

3. 先对比，再接受

推荐顺序是：

  1. 输入指令。
  2. 基于操作式模型输出生成编辑会话预览。
  3. 在只读对比模式审阅服务端已校验的差异。
  4. 审阅预览中显示的警告。
  5. 接受预览到编辑器。
  6. 如果需要，可以基于更新后的编辑器正文继续生成并接受另一个预览。
  7. 手工微调，并使用普通模板保存动作。

这也是当前最稳妥、最符合这个功能设计的使用方式。

🛠️ 常见问题

生成时报“AI 助手当前不可用”

说明当前系统中的 AI 助手尚未启用。

请前往：

设置 -> AI 助手

启用 AI 助手并保存设置。

生成时报“AI 设置不完整”

通常说明下列配置至少有一项缺失：

  • Base URL
  • 模型名称
  • API Key

请前往：

设置 -> AI 助手

完成配置后再回来生成。

为什么我不能直接保存对比结果？

因为 对比模式 是只读审阅视图，不是最终编辑态。

请先点击 接受预览，把候选内容复制到编辑器，再切回编辑模式保存。

为什么编辑会话会过期？

编辑会话是服务端持有的短期预览。它会在 15m 后过期，也不会保存成历史记录。

如果会话过期，请基于最新编辑器内容重新生成预览。

为什么接受预览会被阻止？

以下情况会阻止接受：

  • 会话已经过期或已被丢弃
  • 预览尚未就绪
  • 会话创建后基础模板已经变化
  • 编辑器正文不匹配会话基准，并且已保存模板也发生了变化
  • 校验返回错误

为什么会看到 PATCH_AMBIGUOUS_MATCH？

默认操作模式是 unique。如果同一段精确目标文本出现了多次，而指令没有明确要求处理每一个出现位置，服务端会拒绝操作，避免 AI 悄悄改到非预期段落。

对于 删除所有美国节点条目 这类请求，模型可以在 replace 或 delete 操作中使用显式的 "match":"all"，服务端会以原子方式修改所有精确出现位置。如果预览仍然失败，请用 全部、所有、每一个、all 或 every 等更明确的词重新生成，并尽量包含模板里可见的精确目标文本。

AI 还能帮我重写整份模板吗？

新合约不会要求 AI 返回完整替换模板。AI 返回编辑操作，服务端生成候选预览。这样能减少 token 浪费，也让审阅更可靠。

🔐 安全与使用建议

  • 把预览当作候选方案，而不是最终答案
  • 生成后优先查看对比，再决定是否接受
  • 将警告作为审阅提示，它们不会阻止接受
  • 对关键模板建议保留原始版本，逐步调整
  • 如果结果方向不对，丢弃后用更清晰的指令重新生成

Tip

最理想的使用方式不是“让 AI 一次给出最终模板”，而是“让 AI 提出精确编辑，再由您快速审阅、接受并微调”。这样效率更高，也更安全。