[js] 思源 AI 助手（Thpilot），实现划词 AI 解释、翻译、纠错、总结、聊天等

SiYuan Thpilot 使用帮助文档

📖 简介

SiYuan Thpilot 是一个为思源笔记（SiYuan）设计的 AI 增强插件，提供划词解释、翻译、纠错、摘要和智能对话等功能。通过集成大语言模型，帮助您更高效地处理文本内容。

✨ 主要功能

1. AI 解释

• 对选中文本进行全面清晰的解释
• 自动识别并解释复杂术语和概念
• 支持上下文关联（当前块文本）

2. AI 翻译

• 智能识别源语言，自动翻译为目标语言
• 中文 ↔ 英文互译
• 保持原文风格和格式
• 支持 HTML 标签处理

3. AI 纠错

• 检查拼写、语法和标点错误
• 保持原始格式（包括 HTML 标签）
• 提供详细的修改说明
• 一键替换原文

4. AI 摘要

• 快速生成文本摘要
• 提取核心信息
• 支持长文本压缩

5. AI 聊天

• 全能 AI 助手对话
• 支持连续对话
• 可关联文档上下文
• 历史记录保存

🚀 快速开始

安装步骤

1. 复制代码
   • 将完整代码复制到思源笔记的代码片段中
   • 路径：设置 → 外观 → 代码片段 → JS
2. 配置 API
   • 在代码顶部的"用户配置区"找到 models 数组
   • 填入您的 API 密钥和模型信息

基础配置示例

const models = [
    {
        url: 'https://api.example.com/v1',
        model: 'gpt-4',
        modelName: 'GPT-4',
        apiKey: '你的API密钥', // 👈 填写这里
        stream: true,
        temperature: 0.7,
    }
];

⚙️ 配置说明

1. 界面配置

// 对话框尺寸
const width = 420;        // 宽度（像素）
const maxHeight = 468;    // 最大高度（像素）

// 快捷键设置
const shortcut = 'ctrl+alt+z';  // Windows/Linux
// Mac 会自动转换为 'cmd+alt+z'

2. VIP 配置

const vipKey = '你的VIP密钥';  // 用于解锁聊天功能

提示：为避免泄露密钥，可在单独的代码片段中定义：

var thpilotVipKey = '你的VIP密钥';

3. 模型配置

完整参数说明

URL 规则

1. 自动补全：不含 chat/completions 时自动添加
2. 原始 URL：以 # 结尾表示使用原始路径（去掉 #）
3. 完整路径：包含 chat/completions 不做处理

4. 按钮自定义

按钮配置结构

{
    enable: true,                    // 是否启用
    id: 'aiExplain',                // 唯一标识符
    name: 'AI解释',                  // 提示文本
    icon: `...`,         // SVG 图标
    prompt: `提示词模板`,            // AI 提示词
    system: `系统指令`,              // 系统角色设定
    context: 'blockText',           // 上下文类型
    isChat: false,                  // 是否为聊天模式
    isAutoSend: false,              // 是否自动发送
    pin: false,                     // 是否默认固定
    useSelectedHtml: false,         // 是否使用 HTML 选中内容
    replaceCallback: (result, msg) => {} // 替换回调函数
}

上下文类型说明

提示词变量

• {{selection}}：选中的文本内容
• {{context}}：根据 context 配置自动注入的上下文

📱 使用方法

方法一：划词工具栏

1. 选中文本
   • 鼠标拖选文字
   • 或选中多个块（按住 Ctrl 点击）
2. 点击工具栏按钮
   • 工具栏自动出现在选区上方
   • 点击对应功能按钮（解释/翻译/纠错/摘要/聊天）
3. 查看结果
   • AI 对话框弹出显示结果
   • 支持流式输出（实时显示）

方法二：快捷键

1. 按下快捷键
   • Windows/Linux：Ctrl+Alt+Z
   • Mac：Cmd+Alt+Z
2. 自动行为
   • 如果有选中文本：自动发送到聊天助手
   • 如果无选中文本：打开空白聊天窗口

特殊场景

代码块选择

• 在代码块内选择文本
• 工具栏显示在选区上方
• 支持代码解释和翻译

多块选择

• 按住 Ctrl 点击多个块
• 工具栏显示在第一个块上方
• 会将所有块转为 Markdown 发送

🎨 界面操作

对话框功能

顶部按钮

• 📌 固定：窗口置顶，不随点击外部关闭
• 🔄 切换模型：下拉选择不同 AI 模型
• 🗑️ 清空历史：清除当前会话记录
• ❌ 关闭：关闭对话框

消息操作

每条 AI 回复下方包含：

• 复制：复制消息内容
• 替换：用 AI 回复替换原选中文本（如果配置了 replaceCallback）
• 重新生成：重新请求 AI 回答

输入区域

• 文本框：输入消息或问题（Shift+Enter 换行）
• 发送按钮：Enter 或点击发送

🔧 高级功能

1. 自定义替换逻辑

replaceCallback: (replaceResult, aiMessage) => {
    const protyle = getProtyleEl();
    const wysiwyg = protyle.querySelector('.protyle-wysiwyg');
    sendTextToEditable(wysiwyg, replaceResult);
}

• replaceResult：从 AI 回复提取的内容（如 <div class="replace-result"> 包裹部分）
• aiMessage：完整 AI 回复

2. 全局历史记录

所有聊天记录自动保存到：

/data/temp/ai-global-history.json

配置最大历史条数：

const globalHistoryNum = 200;  // 保留最近 200 条

3. 外部变量配置

在其他代码片段中定义：

// 自定义模型
var llmModels = [
    { url: '...', apiKey: '...', ... }
];

// VIP 密钥
var thpilotVipKey = '你的密钥';

4. 深度思考模式

针对 DeepSeek-R1 等模型：

{
    model: 'deepseek-ai/DeepSeek-R1',
    thinking: 'auto',  // 选项：
                       // 'auto' - 自动显示（有内容才显示）
                       // true   - 强制显示（即使为空）
                       // false  - 完全隐藏
}