mikupad：单文件AI写作前端，兼容多后端与深度创作控制

1. 项目概述：一个单文件全能的AI写作前端

如果你和我一样，经常折腾各种本地大语言模型，那你一定对“前端界面”这件事深有体会。Oobabooga的WebUI功能强大但略显臃肿，KoboldCPP的界面简洁但可定制性有限，而各种API调用又离不开写代码或者用Postman。有没有一个工具，能像记事本一样轻便打开，又能集成所有主流后端，还具备专业写作辅助功能？这就是我今天要详细拆解的mikupad。

简单来说，mikupad是一个完全运行在浏览器里的AI写作与对话界面。它的核心魅力在于“单文件”和“全兼容”。你下载一个HTML文件，双击用浏览器打开，就能立刻连接到你本机或远程的llama.cpp、KoboldCPP、AI Horde，或者任何提供OpenAI兼容API的服务（比如Ollama、LM Studio、vLLM等）。它没有复杂的安装过程，不依赖特定操作系统，却提供了会话持久化、概率查看、Logit Bias微调、世界信息注入等深度功能。对于创作者、开发者，或者任何想高效、专注地与AI模型交互的人来说，它就像一个为你量身定制的数字写作台。

2. 核心设计思路与架构解析

2.1 为什么是“单文件”架构？

mikupad最颠覆性的设计就是其“单文件”形态。整个应用，包括ReactJS构建的用户界面、状态管理、网络请求逻辑，全部被编译、打包进一个独立的mikupad.html文件里。这带来了几个关键优势：

极致的便携性与零部署成本：你不需要安装Node.js、配置Nginx，或者处理任何后端依赖。只需将这个HTML文件复制到任何地方——U盘、云盘、甚至通过聊天软件发送——在任何有现代浏览器的设备上都能立即运行。这对于在不同机器间同步工作环境，或者在受限环境（如公司电脑）下使用，是无可比拟的便利。

完全离线的安全感：编译后的单文件包含了所有静态资源。这意味着一旦你下载了mikupad_compiled.html，你的所有操作（除了调用后端API）都完全在本地浏览器中完成。你的提示词、会话历史等敏感数据不会上传到任何第三方服务器，隐私性得到最大保障。这对于处理机密内容或单纯不想依赖网络稳定性的用户至关重要。

降低使用门槛：这个设计直接瞄准了非技术用户的最大痛点：环境配置。许多优秀的开源工具止步于“需要运行几条命令”，而mikupad做到了“双击即用”。它巧妙地将复杂性转移到了应用内部，对外只呈现一个简单的入口。

注意：虽然前端是单文件，但它仍然需要与一个“后端”AI模型服务进行通信。这个后端可以是运行在你本机的llama.cpp服务器，也可以是局域网内另一台电脑的KoboldCPP，甚至是互联网上的兼容API。mikupad本身不包含模型，它是一个卓越的“客户端”。

2.2 技术栈选型：ReactJS与无构建服务器

项目选用ReactJS作为前端框架是经过深思熟虑的。React的组件化特性非常适合构建mikupad这种拥有复杂交互状态（如会话管理、主题切换、实时概率显示）的应用。虚拟DOM机制也能保证在频繁更新文本和界面元素时的性能。

更精妙的是其“无构建服务器”的开发模式。项目提供了compile脚本，其作用是将开发阶段分散的JSX、CSS模块等源代码，通过打包工具（如esbuild或webpack）全部编译、压缩、并内联到一个HTML文件中。最终产物mikupad_compiled.html是一个完全自包含的单元。在开发时，开发者享受React完整的生态和热更新；在交付时，用户获得一个毫无依赖的绿色软件。这种设计在开源前端工具中并不常见，体现了开发者对用户体验的极致追求。

2.3 多后端兼容性设计解析

支持从轻量级本地推理到云端大型API的多种后端，是mikupad的核心竞争力。其兼容层设计逻辑如下：

1. OpenAI兼容API作为通用层：这是设计的基石。OpenAI的Chat Completions API格式事实上已成为行业标准。mikupad将内部的所有请求，无论是聊天还是补全模式，都优先转化为符合此标准的格式。这意味着任何声明支持OpenAI API的服务（如Ollama、text-generation-webui的--api模式、cloudflare workers AI等）都能即插即用。

2. llama.cpp与KoboldCPP的适配：llama.cpp的server示例和KoboldCPP都提供了自己的REST API，但与OpenAI格式不完全一致。mikupad并未要求这些项目修改接口，而是在前端内部做了一个“适配器”。当用户选择llama.cpp或koboldcpp作为后端类型时，mikupad会自动将生成的OpenAI格式请求，映射到对应后端能理解的端点（endpoint）和请求体（body）格式。例如，它将messages数组转换为prompt字符串，并调整参数名（如temperature对应temp）。

3. AI Horde的特殊集成：AI Horde是一个分布式、免费的开源AI集群，其API结构独树一帜。mikupad为其编写了专门的客户端逻辑，处理复杂的任务提交、状态轮询和结果获取流程，将这种异步的、队列式的服务封装成与本地模型类似的同步交互体验。

这种设计的好处是，无论后端技术如何迭代，只要它提供或兼容上述几种API之一，mikupad就能与之对话。前端保持了稳定，而兼容性的扩展可以通过更新适配器逻辑来完成。

3. 深度功能拆解与实操指南

3.1 会话持久化：不只是保存文本

很多AI工具都有“保存”功能，但mikupad的会话持久化做得更深入。它利用浏览器的localStorage或可选的服务器端数据库，保存的不仅仅是你最后输入的提示词，而是整个会话的完整上下文状态。

具体保存的内容包括：

• 完整的对话历史/补全文本：所有你发送和接收的消息或生成的文本块。
• 当前上下文设置：包括“记忆”（Memory）、“作者笔记”（Author‘s Note）的内容和深度、“世界信息”（World Info）的条目。
• 模型参数：如温度（temperature）、重复惩罚（repeat penalty）、生成长度等。
• 后端连接配置：API地址、模型名称等。

这意味着你可以周一晚上写了一半的小说，直接关闭浏览器。周二在公司电脑上打开同一个HTML文件，加载会话，所有设定和内容都原封不动，可以直接继续。**“导入/导出会话”**功能更是将这一点发挥到极致：你可以将当前会话导出为一个JSON文件，分享给朋友协作，或者作为备份存档。这个JSON文件包含了重现当前会话所需的一切。

实操心得：我习惯为每个不同的创作项目（如技术博客、小说章节、头脑风暴）创建独立的会话并导出保存。文件名加上日期，例如科幻故事大纲_20231027.json。这样不仅版本清晰，也便于在多个创意项目间快速切换，而无需重新配置复杂的上下文指令。

3.2 高级上下文控制：记忆、作者笔记与世界信息

这是将mikupad从“聊天工具”变为“创作助手”的关键功能组。它们共同解决了大语言模型上下文窗口有限且容易遗忘前文信息的问题。

记忆（Memory）：相当于在每次请求的系统提示词（system prompt）最前面永久插入一段文本。这里是放置核心设定、角色性格、故事背景、写作风格要求的最佳位置。例如，你可以写入：“你是一位资深网络安全专家，语气专业且略带讽刺。以下对话中，你将帮助用户分析代码漏洞。”这段文字会持续影响模型的每一次回复。

作者笔记（Author‘s Note）：这是一个更动态的工具。它被插入到上下文的末尾，也就是模型最可能“记住”的位置。其“深度”参数控制它影响前面多少 tokens 的文本。假设深度设为2，那么它会影响它前面的两段（或一定token数）内容。我常用它来注入当前场景的即时信息，比如：“[当前场景：咖啡馆内，雨声淅沥，两人对话因误会而充满张力]”。通过调整深度，你可以控制这个“即时提示”的影响力范围。

世界信息（World Info）：这是最强大的功能，灵感来源于AI写作工具Clover。你可以创建多个条目，每个条目包含一组“关键词”和对应的“内容”。当模型生成或你输入的文本中出现了这些关键词时，对应的“内容”会被动态地插入到当前上下文的特定位置（通常是靠近末尾）。例如，你创建一个角色条目，关键词为[约翰， 警探]，内容为“约翰，45岁，不苟言笑，左脸有一道旧伤疤，习惯性摸下巴思考”。当对话或故事中提到“约翰警探”时，这条人物设定就会被自动注入，确保角色特征在长文中保持一致。

3.3 预测、概率与Logit Bias：精细控制生成过程

预测撤销/重做（Undo/Redo）：这个看似简单的功能极大地改变了工作流。每次你点击“生成”，产生的文本不是一个不可变的终点，而是一个可以回退的“分支点”。你可以不断尝试不同的生成方向，通过撤销回到上一个决策点，然后生成新的变体。这就像为AI写作提供了“多步撤销历史”，鼓励探索性创作。

Token概率查看：将鼠标悬停在生成的任何一个词（token）上，会弹出该词生成时，模型认为最可能的10个候选词及其概率。这不仅仅是一个炫酷的监控窗口，更是一个强大的调试和学习工具。

• 理解模型“思维”：你可以看到模型在某个位置为什么选择了“高兴”而不是“快乐”，它们的概率相差多少。
• 即时纠偏：如果你发现模型在一个关键情节点选了一个离谱的词（概率很低但被抽中了），你可以立刻利用接下来的Logit Bias功能进行纠正。
• 后端要求：此功能需要后端支持返回logprobs或token_logprobs数据。对于Oobabooga，需使用_HF系列的采样器（如mirostat）。对于KoboldCPP，需在启动时或设置中禁用Token Streaming。

Logit Bias（对数概率偏置）：这是高级用户的终极微调旋钮。Logit是模型输出层在Softmax之前的原始分数。Bias就是直接给特定token的分数加上或减去一个值，从而极大地提高或降低它被选中的概率。在mikupad中，你可以直接悬停在一个token上，点击概率列表旁的“+/-”按钮来快速应用偏置。

• 应用场景1：禁止重复：如果你发现模型总爱重复使用某个词，可以找到该词的token ID（通常可以从概率窗口或请求日志中看到），给它一个很大的负偏置（如-100），这个词就几乎不会被生成了。
• 应用场景2：强化关键词：在写技术文章时，你需要确保“Python”这个词在特定段落出现，可以给它一个正偏置（如+2），增加其出现几率，但又不至于完全确定。
• 操作要点：偏置值通常在-100到+100之间，绝对值越大影响越强。调整后通常需要从应用点之后重新生成文本才能看到效果。这是一个需要反复试验才能掌握的工具，但用好了能对生成内容进行外科手术式的精确控制。

3.4 补全模式与聊天模式详解

mikupad巧妙地统一了“补全”和“聊天”两种范式。

补全模式（Completion）：这是最原始、最自由的模式。你将整个上下文（包括记忆、对话历史等）作为一个连续的文本流发送给模型，让它直接续写。这非常适合创意写作、代码生成、长文续写等场景。在此模式下，你看到的是一个完整的、不断增长的文档。

聊天模式（Chat）：此模式专为指令微调（Instruct）模型设计。它自动将交互结构化为“消息”数组，每条消息有“角色”（user, assistant, system）。当你选择了一个聊天模板（如Alpaca、Vicuna、ChatML等），mikupad会在你按下“生成”时，自动在用户消息前后添加该模板要求的指令标记（如### Instruction:和### Response:），并在模型生成结束后自动补上结束标记。对于支持OpenAI Chat API的后端，它直接发送标准的messages数组。

• 核心便利性：你无需手动记忆和输入那些复杂的提示词格式。你只需要在“系统”消息里写要求，在“用户”消息里写问题，就像和ChatGPT对话一样简单。mikupad在背后帮你处理了所有格式封装，让与本地Instruct模型的对话变得无比顺畅。

4. 从零开始：部署与连接实战

4.1 获取与运行mikupad

你有三种方式获得mikupad：

1. 直接使用在线版（最快体验）：访问其GitHub Pages页面。这适合快速体验功能，但所有数据都保存在你当前浏览器的本地存储中。
2. 下载单文件便携版（推荐）：前往项目的Release页面，下载最新的mikupad_compiled.html文件。双击即可在浏览器中打开使用。这是最主流的方式。
3. 克隆与编译开发版（适合开发者）：如果你想研究代码或贡献，可以克隆仓库并运行npm run compile来自己生成编译后的文件。

4.2 连接本地llama.cpp后端

这是最常见的用法。假设你已经在本地用llama.cpp运行了一个模型。

1. 启动llama.cpp服务器：在你的模型目录下，使用类似以下的命令启动服务器。关键是要启用-ngl（GPU层数）加速和--log-disable（可选，让日志更干净）。

   ./server -m your_model.gguf -c 4096 -ngl 99 --host 0.0.0.0 --port 8080

   • -m: 指定模型文件路径。
   • -c: 上下文长度，根据你的模型能力和内存设置。
   • -ngl: 卸载到GPU的层数，99代表全部卸载，显著提升速度。
   • --host 0.0.0.0: 允许来自局域网内其他设备的连接（如果需要在其他设备上用mikupad访问）。
   • --port: 设置端口，默认为8080。

2. 配置mikupad：

   • 在mikupad界面左侧，找到“后端”设置。
   • “后端类型”选择llama.cpp。
   • “API URL”填写你的服务器地址，例如http://localhost:8080（如果mikupad和服务器在同一台电脑）或http://192.168.1.100:8080（局域网访问）。
   • “模型”字段可以留空，因为llama.cpp服务器通常只加载一个模型。如果服务器加载了多个模型，可能需要指定模型名。
   • 点击“连接”或“测试连接”，如果成功，下方状态会显示模型信息。

4.3 连接本地KoboldCPP后端

KoboldCPP是一个集成了llama.cpp且功能更丰富的AI写作前端，它也提供了优秀的API。

1. 启动KoboldCPP：通常通过可执行文件或命令行启动，确保开启了--api选项。

   koboldcpp.exe --model your_model.gguf --port 5001 --api

2. 配置mikupad：

   • “后端类型”选择koboldcpp。
   • “API URL”填写KoboldCPP的地址，如http://localhost:5001。
   • 连接即可。注意，如需使用Token概率功能，需在KoboldCPP启动参数中加入--nostream或在UI设置中关闭流式传输。

4.4 连接Ollama或其他OpenAI兼容API

Ollama是目前非常流行的本地模型管理工具，它原生提供OpenAI兼容API。

1. 启动Ollama并拉取模型：

   ollama run llama3.2:1b # 这会自动启动服务并运行模型 # Ollama服务默认运行在 http://localhost:11434

2. 配置mikupad：

   • “后端类型”选择OpenAI Compatible。
   • “API URL”填写http://localhost:11434/v1。注意，Ollama的OpenAI端点路径是/v1。
   • “API Key”可以留空（除非你配置了Ollama的密钥）。
   • “模型”字段填写你在Ollama中使用的模型名称，如llama3.2:1b。
   • 连接测试。

对于任何其他宣称兼容OpenAI API的服务（如本地部署的vLLM、FastChat，或一些云服务），配置方法都与此类似：类型选OpenAI Compatible，填入正确的Base URL和模型名即可。

4.5 可选：部署Node.js服务器以实现数据持久化与远程访问

单文件模式的数据保存在浏览器的localStorage里，换台电脑或清空浏览器数据就没了。如果你希望会话数据能保存在服务器上，实现多设备同步或团队共享，可以部署其可选的Node.js服务器。

1. 准备环境：确保你的机器安装了Node.js和npm。
2. 克隆并配置：

   git clone https://github.com/lmg-anon/mikupad.git cd mikupad/server # 进入服务器目录 npm install # 安装依赖

   根据需要修改server.js或配置文件，设置数据库连接（如SQLite）和端口。
3. 运行服务器：

   node server.js

4. 访问：此时，你不再直接打开本地的mikupad.html，而是通过浏览器访问http://你的服务器IP:端口（例如http://localhost:3000）。所有会话数据将保存在服务器端的数据库中。

5. 常见问题排查与性能优化技巧

5.1 连接失败问题排查表

5.2 性能与使用优化建议

1. 上下文长度（Context Length）管理：这是影响速度和内存的最关键参数。在mikupad和后端设置中，不要盲目设置为模型宣称的最大值（如4096）。根据你的实际对话长度设置一个合理的值（如2048）。更长的上下文意味着每次请求都需要处理更多的tokens，会显著拖慢生成速度并增加内存压力。

2. 批处理大小（Batch Size）：在llama.cpp等后端中，适当增加批处理大小（如-b 512）可以利用GPU并行能力，大幅提高生成速度，尤其是在生成较长文本时。但这会增加显存占用，需要根据你的硬件平衡。

3. 使用“只续写”模式：在mikupad的生成设置中，有一个“只续写”选项。当勾选时，它不会将整个历史上下文重新发送，而是只发送最后一部分（具体长度可设置）加上你的新提示。这能极大减少传输和处理的数据量，在长文档创作时提速明显。代价是模型可能会遗忘更早的上下文。

4. 世界信息的优化：避免创建过多或内容过长的世界信息条目，且关键词要精准。每次触发都会向上下文插入文本，无节制地使用会快速耗尽上下文窗口，并降低生成速度。定期清理不再需要的条目。

5. 定期清理浏览器数据：如果你长期使用单文件版，浏览器的localStorage可能会积累大量会话数据。偶尔清理一下或使用“导出会话后删除”的方式，可以保持浏览器运行流畅。

5.3 个人实战心得：创作工作流示例

以我撰写一篇技术博客为例，我的mikupad工作流如下：

1. 建立会话框架：新建一个会话，命名为“博客：理解React Hooks闭包陷阱”。
2. 设置记忆（Memory）：在记忆框中写入：“你是一位经验丰富的React前端开发工程师，擅长用通俗易懂的比喻和实际代码示例讲解复杂概念。请以技术博客的风格进行写作，语言严谨但不死板。”
3. 配置后端：连接到我本地运行的Ollama（使用codellama:7b模型），温度设为0.7，以获得平衡的创造性。
4. 撰写与生成：
   • 我手动写下引言和问题描述。
   • 在需要解释“闭包”概念时，我使用作者笔记临时注入：“[注意：此处需要用‘房间和家具’的比喻来解释闭包的形成]”。
   • 在需要给出代码示例时，我切换到“补全模式”，让模型直接续写代码块。
   • 遇到模型反复使用某个冗余词汇时，我使用Logit Bias给它一个-5的偏置。
5. 利用世界信息：我创建一个世界信息条目，关键词为[useEffect, 依赖数组]，内容为“useEffect的依赖数组决定了该副作用在哪些状态变化后重新执行。空数组[]表示仅挂载时执行一次。”这样，每当文章中提到useEffect，这段精确定义就会被自动插入附近，保持论述的一致性。
6. 保存与迭代：完成一个章节后，我导出会话JSON作为备份。第二天打开，一切如昨，可以无缝继续。

mikupad的强大，在于它将分散的工具和复杂的概念，整合进了一个直观、可掌控的界面里。它不试图替代专业的IDE或完整的写作软件，而是在“人与AI模型高效对话”这个细分场景上做到了极致。无论是快速原型设计、长篇内容创作，还是仅仅是探索模型的能力边界，它都是我工具箱中不可或缺的利器。