GPT Academic 自定义快捷按钮实战：从界面配置到 core_functional.py 源码解析

本篇指南讲解 GPT Academic 的自定义快捷按钮机制：如何将高频使用的提示词模板固化为一键触发的界面按钮。文章覆盖"界面配置"与"代码修改"两条创建路径的完整操作步骤与参数说明，并结合 core_functional.py、shared_utils/cookie_manager.py、config.py 等源码，剖析按钮从点击到提示词拼接发送的完整执行链路。读完后，你既能零代码创建个人专属按钮，也能在 core_functional.py 中添加带颜色、预处理、模型覆盖等高级能力的基础功能按钮。

两种创建方式总览

GPT Academic 中"按钮"本质上都是一种"提示词包装器"：点击按钮时，系统按 Prefix（前缀）+ 用户输入 + Suffix（后缀） 的顺序拼接出最终提示词并发送给当前模型。创建方式分两种，各有适用场景：

方式	配置位置	持久化方式	可用高级参数	适用场景
界面配置	主界面左下角"界面外观"菜单	浏览器本地存储	仅标题、前缀、后缀	个人快速创建、单机使用
代码修改	core_functional.py	随仓库/代码分发	颜色、可见性、自动清史、预处理、模型覆盖	团队共享、需要高级功能

两种方式的最终执行路径是统一的，都由 handle_core_functionality 函数完成提示词拼接，区别只在于按钮配置来自浏览器端 cookie 还是来自 Python 字典。

方式一：通过界面添加按钮

这是最便捷的方式，无需修改任何代码，配置会自动保存在浏览器的本地存储中。

打开自定义菜单

在 GPT Academic 主界面的左下角，找到 界面外观 下拉菜单并点击展开。在弹出的浮动面板中选择 自定义菜单 选项，即可打开按钮配置界面。

配置按钮参数

自定义菜单面板包含四个核心配置项。首先，在最上方的下拉框中选择要配置的按钮槽位——系统默认预留了 4 个自定义按钮槽位（自定义按钮1~4），您也可以选择覆盖现有的基础功能按钮（如"学术润色"等）。

接下来填写三个文本框：

• 按钮名称：显示在界面上的按钮文字，建议简短明了，如"论文翻译"、"代码审查"
• 提示前缀：添加在用户输入内容之前的提示词，用于描述任务要求
• 提示后缀：添加在用户输入内容之后的补充说明

点击自定义按钮时，系统会将这三部分按"前缀 + 用户输入 + 后缀"的顺序拼接后发送给 AI。

从源码可以确认这一结构：shared_utils/cookie_manager.py 中的 assign_btn 回调在保存时只写入三个字段——Title（按钮名称）、Prefix、Suffix，因此界面方式确实无法设置颜色、预处理等高级参数。

保存并使用

配置完成后点击 确认并保存 按钮，新按钮会立即出现在基础功能区。此时在输入框中输入需要处理的文本，点击自定义按钮，AI 就会按预设的提示词模板进行处理。

如果需要恢复默认设置，点击 恢复默认 按钮即可清除所有自定义配置（对应 assign_btn 中 clean_up=True 的分支，会把自定义字典整体置空，见 cookie_manager.py）。

界面按钮的持久化机制（源码解读）

界面按钮配置走的是 Gradio 的隐藏组件 + 持久化 cookie 机制：

1. 槽位初始化：toolbox.py 的 load_chat_cookies() 读取 NUM_CUSTOM_BASIC_BTN 配置，按数量生成形如 自定义按钮1 … 自定义按钮4 的默认占位配置（Title 为空、前缀/后缀为提示占位文本）。
2. 按钮渲染：main.py 中为每个槽位创建 gr.Button("自定义按钮N", visible=False, variant="secondary")，默认全部隐藏，存入 customize_btns 字典。
3. 恢复显示：页面加载时执行 load_web_cookie_cache，从持久化 cookie 的 custom_bnt 键读出已保存的按钮配置；凡 Title 非空的条目，就把对应按钮更新为 visible=True, value=Title。若配置键名指向基础功能按钮（覆盖场景），则更新 predefined_btns 中对应按钮的文案。
4. 写入存储：保存时，配置被序列化进 make_cookie_cache 返回的隐藏文本框 web_cookie_cache（elem_id="web_cookie_cache"），由浏览器本地存储持久化，下次访问时自动回填。

!!! tip "配置持久化" 通过界面创建的自定义按钮配置保存在浏览器的 localStorage 中。在同一浏览器中再次访问时，配置会自动恢复；但更换浏览器或清除浏览器数据后配置将丢失。需要长期保存或跨设备共享时，请采用下方的代码方式。

方式二：通过代码添加按钮

代码方式提供了更强大的功能控制，包括按钮颜色、自动清除历史、文本预处理、指定模型等高级选项。所有预设的基础功能按钮都定义在 core_functional.py 中。

配置文件结构

打开项目根目录下的 core_functional.py，get_core_functions() 函数（L10-L147）返回一个字典，每个键值对定义一个按钮。以源码中真实存在的"学术语料润色"为例（文档示例做了简化，实际前缀使用了语言自适应函数）：

"学术语料润色": {
    # [1*] 前缀字符串，会被加在你的输入之前
    "Prefix":   build_gpt_academic_masked_string_langbased(
                    text_show_english="Below is a paragraph from an academic paper. Polish the writing...",
                    text_show_chinese="作为一名中文学术论文写作改进助理，你的任务是改进所提供文本的拼写、语法..."
                ) + "\n\n",
    # [2*] 后缀字符串，会被加在你的输入之后
    "Suffix":   r"",
    # [3] 按钮颜色 (可选参数，默认 secondary)
    "Color":    r"secondary",
    # [4] 按钮是否可见 (可选参数，默认 True，即可见)
    "Visible": True,
    # [5] 是否在触发时清除历史 (可选参数，默认 False)
    "AutoClearHistory": False,
    # [6] 文本预处理 （可选参数，默认 None，举例：写个函数移除所有的换行符）
    "PreProcess": None,
    # [7] 模型选择 （可选参数。如设置，则用指定模型覆盖全局模型。）
    # "ModelOverride": "gpt-3.5-turbo",
},

可以看到，源码注释把每个参数的位置语义（[1*]~[7]）标注得很清楚，这正是自定义按钮的"参数手册"。此外，build_gpt_academic_masked_string_langbased 允许同一个按钮根据界面语言（中文/英文）下发不同语言的提示词，运行时由 apply_gpt_academic_string_mask_langbased 还原——如果你要写面向英文用户的按钮，可以复用这个技巧。

添加新按钮

要添加自己的按钮，在 get_core_functions() 返回的字典中增加一个新条目即可。下面是一个完整示例——创建一个将文本翻译为学术英文的按钮：

"学术英译": {
    "Prefix":   "Please translate the following Chinese text into formal academic English. "
                "Maintain the original meaning while using appropriate academic vocabulary and sentence structures. "
                "The text to translate is:\n\n",
    "Suffix":   "\n\nPlease provide only the translation without explanations.",
    "Color":    "primary",
    "Visible":  True,
},

修改完成后保存文件即可。需要说明的是热重载的真实机制：从源码看，handle_core_functionality 在每次处理按钮点击时都会执行 importlib.reload(core_functional) 重新加载该模块（注释标明"热更新prompt"），因此修改基础按钮的提示词后通常无需重启应用即可生效；而 config.py 中的 PLUGIN_HOT_RELOAD（默认 False）控制的是高级功能插件模块的热加载，二者不要混淆。

参数详解

每个按钮支持以下配置参数（默认值依据 core_functional.py 源码注释补充）：

参数	类型	必填	默认值	说明
Prefix	str	是	—	添加在用户输入前的提示词
Suffix	str	是	—	添加在用户输入后的提示词
Color	str	否	secondary	按钮颜色：primary（强调色）、secondary（次要色）、stop（警示色）
Visible	bool	否	True	是否在界面显示。源码中"英译中"、"找图片"、"参考文献转Bib"均用 Visible: False 作为隐藏按钮保留
AutoClearHistory	bool	否	False	点击时是否清除对话历史
PreProcess	callable	否	None	输入预处理函数，如 clear_line_break 可移除换行符
ModelOverride	str	否	无（用全局模型）	强制使用指定模型，覆盖全局选择

!!! info "颜色主题" 按钮颜色与 themes/theme.py 中的主题配置关联（见 core_functional.py 头部注释）：primary 对应 primary_hue，secondary 对应 neutral_hue，stop 对应 color_er（通常是红色系）。因此换主题时按钮颜色会自动跟随。

按钮点击后的执行链路（源码级）

理解按钮机制最有价值的一环，是看点击后到底发生了什么。handle_core_functionality 的完整逻辑如下：

def handle_core_functionality(additional_fn, inputs, history, chatbot):
    import core_functional
    importlib.reload(core_functional)    # 热更新prompt
    core_functional = core_functional.get_core_functions()
    addition = chatbot._cookies['customize_fn_overwrite']
    if additional_fn in addition:
        # 自定义功能（界面方式创建的按钮）
        inputs = addition[additional_fn]["Prefix"] + inputs + addition[additional_fn]["Suffix"]
        return inputs, history
    else:
        # 预制功能（core_functional.py 中定义的按钮）
        if core_functional[additional_fn]["PreProcess"] is not None:
            inputs = core_functional[additional_fn]"PreProcess"
        inputs = apply_gpt_academic_string_mask_langbased(
            string = core_functional[additional_fn]["Prefix"] + inputs
                     + core_functional[additional_fn]["Suffix"],
            lang_reference = inputs,
        )
        if core_functional[additional_fn].get("AutoClearHistory", False):
            history = []
        return inputs, history

由此可以确认三个关键行为：

1. 优先级：customize_fn_overwrite（界面自定义配置，见 toolbox.py 初始化）优先于代码定义的按钮——这意味着如果你在界面上覆盖了某个基础按钮的前缀/后缀，代码里的同名条目会被绕过；
2. PreProcess 仅对代码按钮生效：界面自定义分支不检查 PreProcess，因此"发送前预处理输入"必须走代码方式；
3. AutoClearHistory 的作用：命中时把 history 置为 []，即本次问答不携带任何历史上下文，适合"会议纪要"这类一次性结构化任务。

另外，在 API/FastAPI 服务模式下，customize_fn_overwrite 同样是 cookie 结构的一部分（见 shared_utils/fastapi_stream_server.py），说明该按钮机制在 Web 服务部署形态下也保持同一套数据模型。

实用示例（可直接复制）

以下是几个经过验证的实用按钮配置，可直接加入 get_core_functions() 返回的字典中，或稍作修改后使用。

示例一：代码审查按钮

适合快速审查一段代码，获取改进建议：

"代码审查": {
    "Prefix":   "请以资深软件工程师的角度审查以下代码。分析代码的：\n"
                "1. 潜在的 bug 或逻辑错误\n"
                "2. 性能优化空间\n"
                "3. 代码风格和可读性问题\n"
                "4. 安全隐患\n\n"
                "代码如下：\n```\n",
    "Suffix":   "\n```\n\n请逐项给出分析和改进建议。",
    "Color":    "secondary",
},

示例二：会议纪要生成

将会议录音转写文本整理成结构化的会议纪要（配合 AutoClearHistory 避免历史对话干扰结构输出）：

"会议纪要": {
    "Prefix":   "请将以下会议记录整理成正式的会议纪要，包含以下部分：\n"
                "- 会议要点摘要\n"
                "- 主要讨论事项\n"
                "- 决议与行动项（Action Items）\n"
                "- 待跟进问题\n\n"
                "会议记录原文：\n",
    "Suffix":   "",
    "Color":    "primary",
    "AutoClearHistory": True,
},

示例三：专业术语翻译

保留专业术语原文的翻译按钮：

"术语翻译": {
    "Prefix":   "翻译以下技术文档为中文。对于专业术语，请采用\"中文翻译（English Original）\"的格式。"
                "常见缩写如 API、SDK、HTTP 等保留原样不翻译。\n\n",
    "Suffix":   "",
    "Color":    "secondary",
},

进阶技巧

利用 PreProcess 预处理输入：某些场景下，你可能希望在发送前对用户输入做变换。例如 clear_line_break 会把所有换行符替换为空格（实现即 txt.replace("\n", " ") 并折叠连续空格），适合处理从 PDF 复制的带不规则换行的文本：

from toolbox import clear_line_break

"论文润色": {
    "Prefix":   "请润色以下学术段落：",
    "Suffix":   "",
    "PreProcess": clear_line_break,
},

源码中"查找语法错误"按钮就是这一用法的现成范例（core_functional.py 设置了 "PreProcess": clear_line_break）。你也可以写任意自定义函数，只要签名是"输入字符串、返回字符串"。

使用 ModelOverride 指定模型：对于特定任务，你可能希望始终使用某个模型，例如代码快速问答使用响应更快的轻量模型：

"快速解释代码": {
    "Prefix":   "用简洁的语言解释这段代码的功能：\n",
    "Suffix":   "",
    "ModelOverride": "gpt-3.5-turbo",
},

注意：ModelOverride 的取值必须是当前环境中已接入的模型名（在 config.py 配置或当前模型下拉框中可见的模型），否则会导致模型不可用。

按钮数量限制：通过界面创建的自定义按钮数量由 config.py 中的 NUM_CUSTOM_BASIC_BTN 控制，默认为 4：

# 自定义按钮的最大数量限制
NUM_CUSTOM_BASIC_BTN = 4

load_chat_cookies() 正是按这个数量生成槽位（toolbox.py）。如果需要更多界面槽位，可以调大该值后重启；若要突破限制或加入高级参数，则应直接走代码方式。

小结与延伸阅读

自定义按钮是 GPT Academic 把"提示词工程"落地的轻量入口：界面方式零代码、浏览器本地持久化，适合个人工作流；代码方式以 core_functional.py 的字典为唯一事实来源，支持颜色、可见性、历史清理、预处理、模型覆盖等全部参数，且每次点击都会 importlib.reload 热更新提示词。更复杂的交互流程（带输入表单、多步调用、独立 UI 面板）则应使用插件机制实现。

相关文档：

• 配置详解 — 了解更多配置选项
• 插件开发指南 — 开发更复杂的功能插件
• 基础操作 — 掌握基础功能按钮的使用方式