1. 项目概述一个纯粹、强大的本地化AI对话与创作客户端如果你和我一样厌倦了各种AI聊天工具繁琐的登录、复杂的订阅、以及令人不安的数据上传一直在寻找一个能完全掌控在自己手里同时又足够强大的AI对话与创作工具那么你找对地方了。今天要聊的这个项目viyiviyi/AI-Assistant-ChatGPT它不是一个简单的“套壳”应用而是一个理念非常清晰的纯前端Web客户端。它的核心目标就一个让你能通过一个简洁、强大的界面自由、安全地连接到你自己的AI模型API无论是OpenAI的ChatGPT、Anthropic的Claude还是开源的ChatGLM甚至是阿里云百炼、Kimi、DeepSeek只要它们提供兼容OpenAI的API接口。这个工具最吸引我的地方在于它的“纯粹性”。它没有后端服务器所有数据——你的对话记录、角色设定、配置——都只存在于你的浏览器本地存储中。这意味着没有数据同步到云端没有隐私泄露的风险清除浏览器数据一切归零干净利落。同时它提供了远超基础聊天的创作级功能超长上下文管理、任意位置编辑与插入消息、Markdown导出、以及通过外部执行器调用系统能力。你可以把它看作一个本地的、功能增强版的“记事本AI引擎”专门为深度对话、长文创作和自动化任务而设计。2. 核心设计思路为何选择纯前端架构与上下文驱动2.1 架构选择纯前端的利与弊这个项目选择纯前端Next.js静态导出作为技术栈是一个经过深思熟虑的取舍。我们来拆解一下背后的逻辑。优势方面极致隐私与数据主权所有数据存储在用户的localStorage或IndexedDB中项目作者或任何第三方都无法触及。这对于处理敏感工作内容、创作私人稿件或进行深度思考对话的用户来说是首要的安心保障。零部署成本与高可用性用户可以直接访问官方提供的https://eaias.com使用无需任何安装。对于想自部署的用户可以一键部署到Cloudflare Pages、Vercel等静态托管服务几乎是免费的并且拥有极高的可用性。无状态服务的简洁性没有用户系统、没有数据库、没有复杂的后端逻辑。整个应用就是一个功能丰富的界面其复杂性全部集中在如何高效地组织对话、管理上下文和调用API上这使得代码更易于理解和二次开发。规避平台风险作为一个静态页面它几乎不会因为内容问题被托管平台下架只要不违反基本法规因为它本身不产生内容内容由用户自己的API密钥和模型生成。需要接受的妥协无跨设备同步这是最大的“缺点”但也是设计使然。数据在本地换一台电脑或手机记录就没了。解决方案是频繁使用其“导出为JSON”功能进行手动备份或者通过一些浏览器插件同步本地存储数据有风险。API密钥前端暴露你的API密钥和代理地址是保存在浏览器本地并直接从前端发起的请求。这意味着如果你使用的代理服务不安全或者访问了恶意网站导致XSS攻击密钥有泄露风险。因此强烈建议为这个客户端单独创建一个API密钥并设置较低的额度与频率限制不要使用你的主账号密钥。功能受限于浏览器一些高级的、需要后端持久化进程的功能如定时任务、复杂文件处理队列无法实现。不过项目通过“外部执行器”巧妙地扩展了这部分能力。实操心得关于API密钥安全无论使用哪个AI客户端只要它需要你填入API Key都请务必在对应的AI服务商后台如OpenAI平台为该密钥设置用量限制和权限范围。例如在OpenAI中可以为这个客户端创建一个仅具有chat.completions权限的密钥并设置每月消费上限。这样即使密钥意外泄露损失也可控。2.2 上下文管理会话与话题的双层设计项目的对话管理逻辑是其作为“创作工具”的核心。它没有采用常见的扁平化聊天列表而是设计了“会话(Session)” - “话题(Topic)”的两级结构。会话 (Session)可以理解为一个独立的工作区或项目。例如你可以创建一个“技术博客写作”会话一个“小说角色构思”会话一个“日常闲聊”会话。每个会话拥有完全独立的配置不同的API密钥、模型选择、系统提示词助理设定、上下文长度等。这实现了完美的环境隔离避免工作流互相干扰。话题 (Topic)存在于一个会话内的具体对话线程。比如在“技术博客写作”会话中你可以有“Docker网络原理详解”、“如何优化React性能”等多个话题。每个话题内的对话记录是连续的。这种设计的好处是巨大的配置隔离在“工作”会话里用GPT-4和严谨的提示词在“娱乐”会话里用便宜的模型和角色扮演提示词互不干扰。内容聚焦每个话题围绕一个主题展开方便后期查找和管理。结合“内容导航”功能动态提取对话中的标题生成目录在生成长篇内容时可以快速跳转定位。资源优化可以为不同会话设置不同的上下文长度。创作时可能只需要关注最近几条消息上下文设为1-3而角色扮演聊天则需要更长的记忆上下文设为10-30分开设置能优化token消耗节省成本。3. 核心功能深度解析与配置实战3.1 助理配置系统从基础提示词到角色卡导入助理配置是整个工具的灵魂它决定了AI的“人格”和输出风格。项目将其做成了一个可分组、可灵活启用的强大系统。基础配置结构在设置界面你可以创建多个“分组”例如“写作风格”、“技术专家”、“创意脑暴”。每个分组下可以创建多条“提示词”。你可以自由调整分组和提示词的顺序因为提示词在上下文中的排列顺序会影响AI的优先级。一个实战配置案例创作技术教程假设我要配置一个用于编写Python入门教程的助理。创建分组“Python导师风格”。添加提示词1角色定位你是一位经验丰富的Python开发者和教师擅长用通俗易懂的比喻和循序渐进的例子讲解概念。你的回答结构清晰总会先给出核心要点再展开详细说明并在最后附上一个简单实用的代码示例。添加提示词2内容格式请使用Markdown格式输出。主要标题用##小节用###。代码块请指定语言为python。对于关键术语请使用**加粗**强调。在解释复杂概念时请使用“就像...”这样的生活化类比。添加提示词3安全与质量你提供的所有代码示例必须是完整、可运行且符合Python最新稳定版PEP 8规范的。如果问题涉及不确定或过时的知识请诚实地说明不要编造。在实际对话时我可以只启用“Python导师风格”这个分组。当需要切换为更随意的风格时我可以禁用这个分组启用另一个比如“简洁问答”分组。高级功能后置提示词与角色卡导入后置提示词这是一个非常巧妙的设计。通常系统提示词会放在上下文最前面。但后置提示词会放在用户最后一条消息的后面再让AI生成回复。这有什么用比如我可以在后置提示词里写“请将以上回答翻译成日语。” 这样我正常的对话流程不受干扰只在需要特定后处理时才触发避免了将翻译指令混入主对话历史导致上下文混乱。导入Chub角色卡这是对角色扮演爱好者的福音。你可以直接从 Chub.ai 这个流行的角色卡社区下载角色的JSON文件然后在工具的“更多-导入酒馆角色卡json”中导入。工具会解析JSON中的description、personality等字段自动生成对应的系统提示词分组。这大大简化了复杂角色设定的配置过程。注意事项提示词冲突与权重当启用多个分组或提示词时它们会被拼接起来发送给AI。如果提示词之间存在指令冲突比如一个要求详细一个要求简洁AI可能会感到困惑。建议一次只启用一个核心的“人格”分组其他分组作为可开关的“技能”或“格式要求”补充。另外越靠前的提示词通常对AI的影响权重越大。3.2 对话与编辑超越线性聊天的创作画布大多数聊天工具是线性的你一言我一语只能在后端追加。而这个工具将对话界面变成了一个可自由编辑的“画布”。核心操作解析任意位置插入将鼠标悬停在任意一条历史消息上会出现操作按钮。你可以选择在该消息之前或之后插入一条新消息。这意味着你可以回溯到对话的早期补充一个提问或设定然后基于这个修改后的历史重新生成后续对话。这对于迭代式创作至关重要。任意角色编辑双击任何消息或点击编辑按钮你可以修改这条消息的内容和发送者角色。你可以把AI的回复改成用户说的或者把用户的话改成系统指令。这打破了角色的壁垒允许你手动“导演”一段对话用于构建完美的示例或训练数据。仅添加上下文当你发送新消息时有一个“仅添加到上下文”的选项。选中后这条消息会加入对话历史但不会触发AI回复。这用于静默地向上下文注入一些背景信息、规则或示例而不打断当前的对话流。实战场景小说对话打磨假设我在创作一段小说对话AI生成的角色A的回应感觉不够犀利。旧有线性工具我只能回复说“请让角色A的回答更讽刺一些”然后AI基于整个历史生成一个新的回复。但这样可能会影响后续对话的整体走向而且无法精准控制。使用本工具我可以直接编辑角色A的那条消息手动将其改得更讽刺。然后我在修改后的消息后插入一条用户消息角色B的下一句台词再让AI继续生成。这样我精确地修正了历史节点后续的对话都能基于我满意的版本展开控制力极强。3.3 外部执行器连接AI与真实世界的桥梁这是项目最具前瞻性和风险性的功能。通过集成一个独立的外部执行器如项目推荐的aias-executer你可以授权AI模型在受控环境下访问本地文件系统、执行命令行指令、调用HTTP API甚至操作浏览器。工作原理你需要单独运行一个执行器服务通常是一个本地运行的进程如http://localhost:3001。在AI助手的设置中配置该执行器的地址并选择暴露哪些工具给AI如“文件读取”、“命令运行”。当你在对话中向AI提出涉及外部操作的需求时例如“请总结当前目录下report.txt文件的内容”AI会生成一个结构化的工具调用请求。前端将该请求发送给你的本地执行器。执行器安全地执行操作如读取文件并将结果返回给前端前端再展示给AIAI根据结果生成最终回复。风险与安全须知警告此功能能力强大风险极高。请务必在完全理解后果后在安全隔离的环境中谨慎使用。最小权限原则在执行器中严格限制AI可访问的目录如仅限某个工作文件夹禁止访问系统关键路径如/etc,C:\Windows。命令白名单如果开启命令执行务必设置命令白名单只允许ls,cat,python script.py等无害或预审过的命令。绝对禁止开放rm -rf,format等危险命令。网络隔离确保执行器运行的网络环境是隔离的避免AI通过HTTP工具访问内部网络或危险网站。人工监督工具调用请求和结果会在页面完整显示。切勿开启“自动执行”模式务必手动审核每一个工具调用请求确认无误后再批准执行。一个安全的使用场景在一个专用于代码项目的会话中你可以配置执行器仅能读取/my_project/src目录。然后你可以对AI说“帮我看看utils.py文件里calculate函数的逻辑并建议如何优化。” AI会请求读取该文件你批准后它就能基于代码内容给出具体建议。这实现了AI与开发环境的深度结合。4. 自部署与高级配置指南4.1 快速部署到Cloudflare Pages官方提供的eaias.com已经非常方便但如果你想自定义比如修改默认API端点、调整UI或确保长期可用自部署是最佳选择。Cloudflare Pages是最简单的途径。详细步骤Fork项目访问项目GitHub仓库viyiviyi/AI-Assistant-ChatGPT点击右上角的Fork按钮将其复制到你自己的GitHub账号下。登录Cloudflare访问 Cloudflare Dashboard 进入“Workers Pages”服务。创建Pages应用点击“创建应用程序” - “Pages” - “连接到Git”。授权并选择仓库授权Cloudflare访问你的GitHub然后选择你刚刚Fork过来的仓库。配置构建设置框架预设选择“Next.js”。构建命令保持默认的npm run build即可。构建输出目录保持默认的.next可能不行。Next.js静态导出后输出目录是out。因此这里需要手动填写out。根目录保持默认/。环境变量可选本项目是纯前端通常无需环境变量。但如果你在代码中硬改了某些默认配置比如默认代理地址可以在这里添加。点击“保存并部署”Cloudflare会自动开始构建和部署。首次构建可能需要几分钟。访问与绑定域名部署成功后你会获得一个*.pages.dev的临时域名。你可以在Pages设置的“自定义域”中绑定自己的域名。部署完成后你的独立AI助手就上线了。所有数据依然存储在访问者的浏览器本地你的服务器只提供静态文件没有任何负载压力。4.2 修改源码以适配自定义后端如果你想彻底替换掉默认的OpenAI API地址指向自己搭建的免费或内部模型API就需要修改源码。核心修改文件AiService/ServiceProvider.ts这个文件是AI服务的工厂类负责根据配置创建不同的服务实例。// 假设你有一个兼容OpenAI API的本地模型服务地址是 http://localhost:8080/v1 // 你需要修改或添加一个服务类型 export class CustomLocalAiService implements IAiService { baseUrl: string http://localhost:8080/v1; // 你的后端地址 // ... 实现其他必要方法如 chat(), models() 等 // 这些方法需要将请求转发到你的 baseUrl } // 然后在 ServiceProvider 的 getService 方法中注册它 export class ServiceProvider { static getService(type: string, config: any): IAiService { switch (type.toLowerCase()) { case openai: return new OpenAiService(config); case claude: // 假设原有Claude return new ClaudeService(config); // 添加你的自定义服务 case mylocalai: return new CustomLocalAiService(config); default: return new OpenAiService(config); } } }修改默认配置为了让所有新会话默认使用你的服务你还需要找到设置默认值的代码可能在config或初始状态中将默认的apiType和apiHost修改为你的mylocalai和http://localhost:8080/v1。二次开发提示项目使用TypeScript和Next.js结构清晰。如果你想增加新功能如语音输入输出、更多导出格式熟悉React/Next.js开发流程即可。UI组件库可能是自定义的或简单的Tailwind CSS修改样式前请先查看相关CSS文件。数据持久化全部通过前端状态管理如Zustand、Redux或Context配合浏览器API实现逻辑集中在store或hooks目录下。4.3 配置反向代理以解决跨域与访问问题由于项目是纯前端直接由浏览器向AI API发起请求会遭遇两个问题1.跨域(CORS)错误2. 某些API服务如OpenAI在国内直接访问不稳定。解决方案是使用一个反向代理。项目文档提供了一个通用的Cloudflare Worker代理脚本。它的原理是浏览器请求你的Worker地址如https://myproxy.yourdomain.com/https://api.openai.com/v1/chat/completionsWorker再去请求真实的OpenAI API并将结果返回给浏览器从而绕过跨域限制并可能改善网络连接。部署你自己的Cloudflare Worker代理登录Cloudflare Dashboard进入“Workers Pages”。点击“创建应用程序” - “Worker”。给Worker起个名字如ai-api-proxy。点击“快速编辑”将文档中提供的完整JavaScript代码替换掉默认代码。点击“保存并部署”。部署后你会得到一个Worker域名如ai-api-proxy.yourusername.workers.dev。在AI助手中配置在工具的“会话配置”中找到“接口代理地址”。填入你的Worker地址格式为https://ai-api-proxy.yourusername.workers.dev/注意末尾的斜杠很重要。当工具需要调用https://api.openai.com/v1/chat/completions时它会将请求发送到https://你的worker地址/https://api.openai.com/v1/chat/completions。重要提醒使用公共代理或自建代理时你的API密钥会经过代理服务器。请仅使用你绝对信任的代理服务。自建是最安全的方式。同时Cloudflare Worker有每日免费请求次数限制10万次对于个人使用通常足够但需留意。5. 常见问题与故障排查实录在实际使用和部署过程中我遇到了一些典型问题以下是排查思路和解决方案。5.1 网络与API连接问题问题配置好API密钥和代理后一直显示“网络错误”或“连接超时”。检查代理地址格式确保代理地址以https://开头并且末尾有斜杠/。错误的格式如http://proxy.com或https://proxy.com会导致拼接出的URL错误。验证代理本身是否可用打开浏览器新标签页尝试直接访问你的代理地址/https://api.openai.com/v1/models并附上正确的Authorization: Bearer sk-xxx请求头可以使用Postman或浏览器插件如ModHeader添加。如果返回401错误说明代理通但密钥错如果返回404或跨域错误说明代理脚本未正常工作如果连接失败说明代理服务器网络有问题。检查Cloudflare Worker脚本如果你用的是自建的Cloudflare Worker确保代码已正确部署且没有语法错误。Worker的免费套餐有请求数限制超限也会失败。前端跨域问题即使代理配置正确如果代理返回的响应头没有包含Access-Control-Allow-Origin: *浏览器依然会拦截。文档提供的Worker脚本已包含这些CORS头但如果你用其他代理工具如Nginx需要手动配置。API密钥额度或过期登录OpenAI平台检查密钥是否有效、是否有余额、是否被禁用。5.2 数据丢失与备份恢复问题清理了浏览器缓存或者换了一台电脑所有对话记录都没了。这是纯前端应用的特性并非bug。必须建立手动备份习惯。定期导出在每个重要的会话或话题结束后使用话题顶部的“导出”功能选择“导出为JSON”。这个文件包含了该话题的所有消息、角色、时间戳等完整信息。会话级备份目前工具似乎没有提供整个会话包含所有话题的一键导出。变通方法是进入每个话题逐一导出JSON然后手动管理这些文件。恢复数据在需要恢复的会话中创建一个新话题点击“导入”按钮通常与导出在一起选择之前备份的JSON文件即可。注意导入会覆盖当前话题的现有内容。浏览器数据同步高级用户可以考虑使用浏览器的同步功能如Chrome Sync同步“扩展程序数据”或“本地存储数据”但这并非百分百可靠且可能在不同浏览器间不兼容。最可靠的还是手动导出JSON文件。5.3 上下文长度与Token消耗异常问题AI突然忘记了很早的对话内容或者API调用费用比预期高很多。确认上下文数量设置检查当前会话的“上下文数量”配置。这个数字决定了发送给AI的历史消息条数而非Token数。如果你设为5那么只有最新的5条消息用户和AI交替会被送入模型。早期的内容会被“遗忘”。理解Token与消息条数的关系一条消息可能包含几十个Token短问题也可能包含数千个Token长文回复。模型有上下文窗口限制如GPT-3.5-turbo是16K Token。即使你设置上下文数量为50如果总Token数超过窗口限制API调用也会失败或者模型会自动从前面开始“遗忘”。工具本身可能不会做精确的Token计数和截断。监控与优化创作时建议将上下文数量设为1-3并使用“插入消息”功能来提供必要的背景。这样可以精准控制送入模型的Token避免为无关历史付费。长对话时如果需要长记忆就调高上下文数量。但要注意成本GPT-4等模型的输入Token很贵。可以定期使用“总结之前对话”的功能让AI将长历史压缩成一条摘要消息然后开始新话题将摘要作为背景信息插入。检查提示词长度你配置的“助理设定”提示词在每次请求中都会发送。如果提示词非常长比如导入了一个超详细的角色卡它会占用大量固定Token。考虑精简提示词。5.4 外部执行器连接失败或执行错误问题配置了外部执行器地址但工具调用时显示“连接失败”或执行没有反应。执行器服务是否运行确认你本地的aias-executer或其他执行器进程已经启动并在监听指定的端口如http://localhost:3001。跨域问题执行器服务必须配置CORS允许前端网页的域名如https://eaias.com或你的自部署域名进行跨域访问。检查执行器服务的代码确保它返回了Access-Control-Allow-Origin等头部。网络策略如果前端页面是通过HTTPS访问的而你的本地执行器是HTTP现代浏览器可能会因为混合内容策略而阻止请求。尝试让执行器也通过HTTPS运行例如使用自签名证书并信任它或者通过一个支持HTTPS的反向代理来访问本地HTTP执行器。执行器日志查看执行器服务的控制台输出日志看是否收到了请求请求内容是什么执行过程中是否有错误抛出。工具权限在执行器的配置界面确认你希望AI使用的工具如file_read,command_run已经被勾选并暴露。这个工具代表了一种趋势将AI能力作为一种纯粹的、本地化的生产力工具来使用强调用户对数据、流程和成本的控制。它可能没有那些一体化SaaS产品华丽但其在灵活性、隐私性和深度工作流支持上的优势对于开发者、写作者和任何希望将AI深度融入个人工作流的人来说具有不可替代的价值。它的学习曲线稍陡需要你愿意花时间去配置提示词、理解上下文管理、甚至折腾一下代理和部署。但一旦你熟悉了它它就会成为一个无比趁手、完全听命于你的数字伙伴。