📖 My SW 使用文档

欢迎使用 My SW！这是一个完全运行在浏览器本地的 AI 角色聊天应用，所有数据（聊天记录、角色、自定义内容）都保存在你的设备上，不会上传到任何服务器。本文档将带你从零开始，即使是第一次接触 AI 的真新手，也能顺利配置并开始使用。

🚀 快速开始（5 分钟）

如果你是急性子，只想立刻开始聊天，按下面三步走即可：

1. 注册一个 API 平台账号并充值 推荐从 OpenRouter、硅基流动、DeepSeek 官方 等平台开始，注册简单、支持支付宝/微信。
2. 在 API 平台创建一个 Key 进入「API Keys」页面，点击「Create new key」，复制以 sk- 开头的那串字符。
3. 回到本应用，依次填入 API 地址、Key、模型 点右下角齿轮 ⚙️ →「AI 配置」标签 → 填好三项 → 点「保存设置」。

看到这里已经够了，下面是更详细的手把手教学，强烈建议新手通读。

⚙️ 初次配置步骤（手把手）

第一次打开应用时，由于没有配置 AI 接口，发送消息会提示 ❌ 请先在设置中配置 API 地址和 Key！。这是正常现象，请按下面的步骤配置：

第 1 步：打开「系统设置」

在聊天界面左下角（或移动端右上角）找到 齿轮按钮，点击它。会弹出一个标题为「系统设置」的模态框。模态框顶部有多个标签页：AI 配置 / 界面外观 / 聊天设置 / 导入导出 / 知识库 / 长期记忆 / 世界书 / 快捷键 / 插件 / 实验室 / 更多 / 插件 / 实验室。第一次使用我们只需要关注 「AI 配置」 即可。

第 2 步：填写「API 调用地址」

这是你的 AI 服务提供商的接口根地址。本应用兼容所有遵循 OpenAI Chat Completions 协议 的服务，所以你只需要填到域名部分，/v1/chat/completions 系统会自动补全。

常见平台的地址示例：

第 3 步：填入 API Key

在「API Key」输入框中粘贴你从平台复制的密钥，格式通常为：

sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

输入框默认为密码模式（••••••••），点击右侧的小眼睛图标可以临时查看明文。填写后请妥善保管，不要截图发到公开群聊。

没有 API Key？往下看 什么是 API Key 章节。

第 4 步：选择模型

在「模型名称」框中填入你想用的模型标识符，例如：

• deepseek-v4-flash（DeepSeek 最新性价比之王，2026 年 8 月发布）
• deepseek-v4-pro（DeepSeek 旗舰版）
• Qwen/Qwen3.8-Flash（通义千问新模型）
• moonshot-v1-8k（Kimi K3）

如果你不确定有哪些模型可用，可以点击旁边的 「获取模型」 按钮，系统会调用平台的 /v1/models 接口列出所有可用模型供你下拉选择。

第 5 步：测试连接 & 保存

填写完三项后，先点一下 「测试连接」 按钮：

• ✅ 看到 连接成功 字样 → 点击右下角 「保存设置」，大功告成！
• ❌ 看到错误提示（Key 无效、地址错误、超时等）→ 根据提示检查对应项后重试。

📌 进阶：生成参数调节

在「AI 配置」页面下方还有几个可选参数，新手可以先保持默认：

• 随机性 (temperature)：0~2 之间。值越大 AI 回复越有创造性、越发散；值越小越稳定、越像标准答案。角色扮演建议 0.8~1.2。
• 核采样 (topP)：0~1 之间。默认 0.9。和 temperature 二选一调即可，不要同时大改。
• 最大上下文 (maxContext)：AI 能「记住」的历史消息轮数。太小会失忆，太大会更贵。
• 单条回复上限 (maxTokens)：限制 AI 单次回复的长度，避免无限生成。

🔑 什么是 API Key？

你可以把 API Key 理解为一把「钥匙」或「通行证」：

当你在本应用里向 AI 提问时，应用会把你的问题通过 HTTPS 加密发送到 AI 服务商（OpenAI、DeepSeek 等）的服务器。服务商怎么知道这次请求是你发出的、应该由谁付费呢？答案就是——靠 API Key。

把它想象成酒店房卡：

• 🔒 私密：谁拿到你的 Key，谁就能冒充你调用 AI，产生的费用全部算到你账上。
• 💳 付费凭证：AI 平台根据你的 Key 记录调用量并从你预充值/绑定的账户里扣款。
• 🪪 可重置：每个平台都允许你随时「作废」旧 Key、生成新 Key（一般在「API Keys」页面）。

API Key 长什么样？

不同平台的 Key 格式略有不同，但通常都是以 sk- 开头的一长串字符：

sk-proj-AbCdEfGhIjKlMnOpQrStUvWxYz1234567890abcdef
sk-7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

API Key 在哪里找？

每家平台大同小异：登录后进入控制台 → 找到「API Keys」或「密钥管理」 → 点击「Create new key」 → 设置名称和限额 → 生成 → 立刻复制保存（多数平台 Key 只显示一次）。

具体的「获取步骤」请参考下面平台介绍章节。

🌐 常见 API 平台推荐

国内外提供兼容 OpenAI 协议的大模型服务商非常多，下面按 「新手友好度」 分类介绍。选一家注册、充值、开用即可。

📦 一、官方直连平台（最稳定）

直接对接模型厂商，数据不经第三方，最安全稳定。

🔁 二、中转 / 代理平台（聚合多模型）

这类平台本身不训练模型，只是把多家厂商的接口汇总到一起，再低价卖给你。一个 Key 通常能调用 GPT-4、Claude、Gemini 等多种模型。

🏠 三、本地部署（完全免费、零费用）

如果你的电脑配置尚可（建议 N 卡 RTX 3060 以上 / 内存 16G+），可以用 Ollama、LM Studio、vLLM 等工具在本地跑开源模型（如 Qwen3.8、Llama3.1、Mistral），完全不花钱、数据不出门。

1. 去 ollama.com 下载并安装。
2. 终端执行 ollama run qwen3.8:7b（自动下载模型）。
3. 本应用 API 地址填 http://localhost:11434，模型填 qwen3.8:7b。

缺点是：模型体积大（几十 GB）、速度比云端慢、显存不够需要量化版。适合玩票和极客，新手慎入。

💰 AI 是怎么收费的？三大计费方式详解

看到这里你可能会有疑问：「我用 AI 聊天，平台按什么标准收我钱？」下面把 最常见的计费方式 用最通俗的语言讲清楚。

一、按 Token 计费（最主流）

这是 OpenAI、DeepSeek、Claude 等绝大多数官方平台采用的方式，用多少付多少。

平台通常按 「每百万 Token 单价」 计费。以下是 截至 2026 年 9 月 各家主流模型的最新公开价格（人民币）：

看不懂？来个真实计算（以 DeepSeek-V4-Flash 空闲时段为例）：

假设你和 AI 聊了 10 轮，每轮输入 200 字（≈300 Token），AI 回复 500 字（≈750 Token），总消耗 = 10 × (300 + 750) = 10,500 Token ≈ 0.0105 百万 Token。

用 DeepSeek-V4-Flash（空闲，缓存未命中）：0.0105 × (1.5 + 4.5) = 约 ¥0.063，不到 7 分钱。

用 GPT-6 Astra：0.0105 × (10 + 50) = 约 $0.63，约 ¥4.5。

二、按次计费

无论你发几个字、AI 回多少字，一次对话 = 一个固定费用。常见于：

• 某些角色扮演 SaaS产品（如 Character.AI 早期、星野）
• 某些中转站套餐，按「次」或「条」出售

举例：商家推出「1000 次对话包 ¥10」，平均每次 1 分钱，看似便宜，但实际单次回复可能限制 Token 长度（比如最长 500 字），超过部分另算。

三、包月 / 订阅制

每月固定费用（如 ¥20、¥80），在额度内随便用。典型代表：

• ChatGPT Plus（$20/月，含 GPT-6 一定额度）
• Claude Pro（$20/月）
• Cursor、Copilot 等 AI 编程工具

缺点：超出额度仍按 Token 加钱，不聊天也照样扣月费。本应用是对接你自己的 API Key，所以默认采用按量付费，没有包月选项（除非你购买平台官方的订阅套餐后获得更高额度）。

四、三种方式对比

📊 快速理解「Token」

看完上面你可能还是有点抽象，这里用三个比喻帮你彻底搞懂：

1. 📞 Token 就像手机话费的「分钟数」：通话时间越长，扣费越多。Token 就是 AI 的「通话时间」。
2. 🛒 Token 就像超市的「斤两」：1 斤米 3 块钱，1 斤面 4 块钱。AI 模型是「商品」，Token 是「重量」。
3. 📖 Token 就像书本的「字数」：一本 10 万字的小说 = 约 15 万 Token。

所以：

• 💬 简单聊天 1 小时 ≈ 几千到几万个 Token ≈ 几分到几毛钱
• 📚 让 AI 写一篇 3000 字文章 ≈ 5000~8000 Token（仅输出）
• 🎬 长篇角色扮演 RP 一晚上 ≈ 几十万 Token ≈ 几毛到几块钱

🎭 创建与编辑角色

本应用的核心玩法就是自定义角色。每个「角色」本质上是一段 系统提示词（System Prompt），告诉 AI「你是谁、应该怎么说话、有什么背景」等。

方式一：点击 ➕ 添加角色

左下角点击 「添加好友」 按钮，会弹出角色编辑窗口。填写以下字段：

写人设的实用技巧

一个高质量的人设通常包含这几部分：

1. 基本信息：年龄、性别、外貌、职业。
2. 性格特征：用具体词汇描述，如「毒舌但关心人」「外冷内热」。
3. 说话风格：举 2~3 个示例句（非常有效！）。
4. 背景故事：来龙去脉、动机、关系网。
5. 行为边界：明确不希望 AI 做什么（如「不要主动结束对话」「不要重复我的话」）。

示例：极简但有效的人设

你是「银狼」，19 岁天才黑客少女，崩坏：星穹铁道角色。
性格：毒舌、慵懒、惜字如金，但内心重情义。
口头禅：「啧，太简单了」「一群菜鸟」。
说话风格：短句、夹带电子游戏术语和表情包。
示例：
- 用户：「在吗？」 → 银狼：「有事说事，别浪费我挂游戏的时间。」
- 用户：「我今天心情不好」 → 银狼：「……要黑客进你的仇人系统吗？免费的。」
请永远以银狼的第一人称视角回复，不要用敬语。

方式二：导入 JSON 角色卡

如果你从 SillyTavern、酒馆、Character.AI 等平台获取了角色 JSON，可以直接导入：

1. 点击左下角 「批量编辑」。
2. 选择「导入 JSON / PNG 角色卡」。
3. 选择本地文件即可（支持 .json 和 .png 内嵌的角色卡）。

编辑 / 删除 / 导出

右键点击（移动端长按）任意角色头像，会弹出操作菜单：编辑信息、设置备注、导出角色、清空聊天记录、删除等。

同时选中多个角色后，可以批量导出为 ZIP 文件，方便迁移或备份。

📚 世界书（Lorebook）

「世界书」位于 设置 → 世界书 标签页，功能类似「酒馆（SillyTavern）」的世界书 / Lorebook：它是一份背景知识集合，AI 聊天时会根据对话内容动态挑选相关条目注入提示词，让 AI 了解世界观、地名、人物关系等设定，而不必把所有设定一股脑塞进角色提示词。

核心概念

两种激活策略（灯色）

• 🔵 蓝灯（Constant，常驻）：无论聊什么，条目内容始终注入提示词。适合核心世界观、重要人物关系等必须让 AI 时刻知道的设定。蓝灯条目可以不填关键词。
• 🟢 绿灯（Normal，关键词触发）：只有当关键词出现在最近 N 条消息中时才注入。适合不会每轮都用到的细节设定，按需激活可以显著节省 token。

四种生效范围（Scope）

创建与编辑

1. 创建世界书在「设置 → 世界书」中点击「创建世界书」，填写名称并选择生效范围与绑定目标。
2. 进入编辑界面点击世界书卡片上的「编辑条目」，会打开一个独立的全屏弹窗编辑器（与编辑角色的弹窗风格一致），在这里管理全部条目。
3. 添加条目点击「添加条目」，为每个条目填写：关键词（逗号分隔）、条目内容、激活策略（蓝灯/绿灯）、插入位置、扫描深度。所有修改即时自动保存，无需手动点保存。
4. 完成编辑点击「完成并关闭」或右上角 ✕ 返回列表，所有修改已生效。

导入 / 导出

• 导入 txt / md：按空行或 Markdown 标题自动切分为条目；首行若是 关键词：xxx 或 【xxx】 会自动解析为关键词，有关键词的条目设为绿灯，没有的设为蓝灯。
• 导入 JSON：直接兼容酒馆（SillyTavern）世界书 JSON，关键词、灯色、插入位置、扫描深度、启用状态都会自动转换。
• 导出：每本世界书可单独导出为 JSON 文件备份或分享。

用户人设（Persona）

世界书标签页底部可以管理用户人设：

• 多个人设：可以创建多份不同身份的人设（如「冒险者·夜羽」「星际商人·老周」），用顶部的下拉框随时切换当前使用的人设。
• 注入对话：当前人设的描述会作为上下文注入对话，让 AI 知道「你是谁」。
• 重命名自动迁移：修改当前人设的名称再保存，会自动迁移描述，并且绑定到旧人设名的世界书也会跟着更新绑定。
• 绑定世界书：生效类型选「🎭 人设」的世界书，会在你切换到对应人设时生效。

🎬 视觉小说模式（Galgame）

把聊天界面变成 Galgame：沉浸式背景 + 角色立绘，对话以底部对话框逐句呈现，并按 AI 回复的情绪自动切换对应立绘。舞台只覆盖消息区，底部输入框照常可用，随时可以返回普通聊天。想要更纯粹的体验可以打开全屏舞台（见下文），让画面铺满整个屏幕。

进入与退出

• 三个入口：聊天头部右上角的 按钮、「设置 → 界面外观 → 视觉小说模式」里的进入按钮（面板中还会实时显示当前角色配了几张立绘），或在输入框里输入 /vn（/vn on 进入、/vn off 退出）。/立绘 则直接打开立绘与背景设置。
• 退出：点舞台右上角「退出 VN」，或按 Esc。退出后自动把普通聊天滚到最新一句。
• 模式状态会被记住，刷新页面后仍保持上次的模式；退出后马上再进来会停在你刚读的那一句并整句落定，不会把那句话重新打一遍。
• 分段回复不再被重放：开了「分段显示」时长回复会拆成多条气泡，回复刚落库时舞台会自动跟进到这批分段的第一段（而不是末段），并且这一段会从第一页开始整段落定 —— 你在流式阶段已经读完的内容不会被打字机重新敲一遍，接着往后读即可。
• 回复正在生成时切进舞台，会立刻接上已经出现的文字继续看，不用等这条回复说完。

立绘与背景素材

• 按「角色 × 情绪」绑定，共 12 种情绪（default / happy / sad / angry / shy / surprised / neutral / love / excited / thinking / laugh / cry）。未设置的自动回退 default，再回退角色头像。
• 每张立绘都支持本地上传与图片直链两种方式；本地大图会自动压缩（立绘 1000px、背景 1600px），超出 localStorage 的部分存入 IndexedDB。
• 背景可按角色单独设置，也可设置全局背景兜底；还可以给某个情绪单独配一张背景（如「生气」时切到雷雨场景），情绪切换时背景会交叉淡入。
• 批量导入：一次选择多张图片，按文件名自动匹配情绪（happy.png、立绘-开心.jpg；bg-happy.png / 背景-开心.jpg 为该情绪背景）。
• 跨设备迁移请用弹窗底部的「导出 / 导入配置」（JSON）。

情绪识别优先级

逐句手动覆盖（点对话框上的情绪徽标）> [emo:xxx] 显式标签 > 关键词打分 > 默认。在外观面板勾选「要求 AI 标注情绪」后，会在系统提示中要求 AI 每次回复先给出 [emo:happy] 一行，立绘切换最准确（会改变提示词）。

其它渲染细节：长句会自动分页（一屏读不完时按句切页，点击 / 滚轮 / 按 → 翻页）；背景支持缓慢推移（Ken Burns）、压暗与虚化；情绪还会给背景叠一层极淡的氛围光染色，无需额外素材。

舞台上的对话不会出现 [emo:happy] 这类内部控制标记：即便你没开「显示思考过程」相关的其它设置，普通聊天气泡里也会一并剥离。等待 AI 开口时，对话框上会显示「正在组织语言」的跳动小点；说话人名字旁带一枚小头像，群聊里每个角色还会各自主配色（含群头衔），方便分辨谁在说话。

全屏舞台（界面铺满整个屏幕）

舞台工具条上的 按钮、按 F、或在「设置 → 界面外观 → 视觉小说模式」里勾选「全屏舞台」，都能让 Galgame 界面占满整个屏幕：聊天头部、免责声明、左侧角色栏全部收起，并同步进入浏览器原生全屏（隐藏标签栏与地址栏）。

• 输入框仍然可用：输入区被搬成一枚悬浮在对话框上方的浮条，打字、发图、语音、表情、快捷指令全部照旧，功能与快捷键没有任何削减。
• 立绘与对话框自动让位：抬升量按悬浮条的实测高度计算（CSS 变量 --vn-fs-lift），输入框撑高到多行也不会盖住台词。
• 长句分页会重新计算：舞台变高后一屏能放下的行数变了，会自动重新分页并停在原句，不会把已读的内容重打一遍。
• 退出方式：再按一次 F、点同一个按钮、或按 Esc。注意浏览器会先吃掉第一次 Esc 用来退出原生全屏（舞台随之退回窗口内），再按一次 Esc 才返回普通聊天。直接用 F11 / 浏览器菜单退出原生全屏时，舞台样式与偏好会同步跟随，不会残留隐藏状态。
• 状态会被记住：偏好随 VN 设置一起保存，下次进入视觉小说模式仍是全屏。「移动视图」下全屏只占满那个 430×844 的手机外框，不会把手机预览撑成浏览器窗口。

快捷键

移动端可左右滑动翻页与切换句子。

✨ 功能介绍

本应用提供了丰富的功能，下面按模块分组介绍：

💬 聊天核心功能

🎨 角色扮演辅助

🚀 高级 / 实验性功能

在「设置 → 实验室」中可开关：

💾 数据管理

在「设置 → 导入导出」标签中：

• 导出设置：只导出 AI 配置、界面设置等，体积小，适合分享配置模板。
• 导出全部数据：完整备份（包含聊天记录、角色、知识库等），换设备必用。
• 导入数据：恢复备份，可选「合并」或「覆盖」。
• 自动备份：开启后定期自动导出 JSON 文件到下载目录。
• 查看存储使用情况：就在这几个按钮下面，展开后能看清空间都被谁用掉了（见下一节）。

🧭 查看存储使用情况

位置在「设置 → 导入导出」标签的导入导出按钮下方：点「查看存储使用情况」打开面板明细；边上的「重新统计」只重算体积、不重建面板，所以不会把你已经勾选的项清掉，统计期间的瞬时建库也不会留下空壳数据库。

• 一眼看总量：顶部进度条与四张卡片给出「浏览器统计的总占用 / 本站可用配额 / IndexedDB 合计 / localStorage 合计」，以及各类缓存（Cache Storage，主要就是离线资源）占了多少。
• 按用途分列：下面按库分组列出 localStorage、主数据库 MySW_Storage、以及知识库 / 实验室 / 论坛 / 启动画面等独立 IndexedDB 库，每个库再展开到具体条目，条目同时给出「存了哪些 key」。
• 标出「可再生」与「不可再生」：聊天记录、角色数据、论坛内容、知识库这类删了就回不来的条目会打上红色的「不可再生」标签；提示词分块缓存、折叠状态、商店缓存这类随时能重建的才是「可再生」。
• 两道确认，删不掉聊天记录：勾选条目后点「清理选中」，可再生项只要确认一次；只要列表里含不可再生项，就必须在弹出的框里手动输入 DELETE 才会执行，防止顺手把聊天记录清空。想更保险，可以先把「导出全部数据」存一份再动手。
• 一键清理可再生数据：一次清掉所有「可再生」条目并顺带清空 Service Worker 缓存刷新页面，绝不会碰不可再生条目。

🔌 插件编写指南

My SW 自带一个轻量插件系统：一个插件就是一个 JavaScript 文件，通过全局对象 window.MySWPlugins.register() 注册自己。插件能改你发出去的文字、能给 AI 追加提示词、 能在聊天界面里挂一个面板，也能借用你配置的 API 发请求 —— 但每一项都必须你显式授权，插件本身永远拿不到 API Key 明文。

最小可用插件

新建一个 .js 文件，内容如下，然后在「设置 → 插件」里把这个文件导入即可：

// hello-plugin.js
MySWPlugins.register({
    id: 'hello-shout',
    name: '喊话器',
    description: '把你发出的每条消息都变成全大写（英文）并在结尾加感叹号。',
    permissions: [],           // 只做文本变换，不需要任何权限
    params: [
        { key: 'mark', label: '结尾标记', type: 'text', value: '！' }
    ],
    // 文本变换钩子：用户按发送 → 先过这里 → 再存进聊天记录并发给 AI
    transformText(text, params) {
        const mark = String(params.mark || '！');
        const upper = String(text || '').toUpperCase();
        return upper.endsWith(mark) ? upper : upper + mark;
    }
});

保存后导入，插件会出现在列表里但默认是未启用状态，勾上「启用」才开始生效。

register() 的字段

权限系统（两级授权）

权限只有在总开关与该插件的独立授权同时打开时才生效，两者是 AND 关系。

• 总开关：设置 → 插件 → 插件权限。默认关闭，关掉即对所有插件生效。
• 插件授权：每个插件卡片上的勾选框，默认已勾选 —— 所以你只需要拨一次总闸，插件立即可用；想只信任某一个插件时，把其它插件的授权单独收回即可。

插件内部可用 MySWPlugins.hasPermission('useApi') 查总开关，用 MySWPlugins.canPluginUse('my-id', 'useDom') 查最终生效结果，做优雅降级而不是直接抛错。

四种钩子：什么时候会被调用

transformPrompt(text, params) {
    const extra = String(params.prompt || '').trim();
    if (!extra) return text;
    const base = String(text || '');
    if (base.includes(extra)) return base;   // 幂等：只追加一次
    return base + '\n\n' + extra;
}

任何钩子里抛出的异常都会被捕获并记录到控制台，不会影响正常对话 —— 单个插件写崩了最多是自己不生效。

受控 API 通道：借用接口但不接触密钥

ctx.api 是唯一允许插件发起模型请求的入口，每次调用都会实时校验权限，你在设置里一关就立刻失效。

async activate(params, plugin, ctx) {
    if (!ctx.api.available) {
        // 没授权 / 没配置接口 → 优雅降级，别报错吓用户
        ctx.toast('本插件需要「使用 API 配置」权限');
        return;
    }
    const info = ctx.api.getInfo();
    console.log('使用模型：', info.model, '端点：', info.endpoint);

    const answer = await ctx.api.chat([
        { role: 'system', content: '你是一个简洁的翻译助手，只输出译文。' },
        { role: 'user', content: '把下面这句话译成英文：今天天气不错。' }
    ], { max_tokens: 200 });
    console.log(answer);
}

受控 DOM 通道：挂界面能被统一回收

不要直接 document.body.appendChild()。用 ctx.dom.mount(node, container) 挂载， 系统会登记这个节点，在插件停用或权限被收回时自动移除，界面能干净复原。

permissions: ['useDom'],

activate(params, plugin, ctx) {
    if (!ctx.dom.available) return;
    if (document.getElementById('my-clock-panel')) return;  // 幂等：避免重复挂载

    const panel = document.createElement('div');
    panel.id = 'my-clock-panel';
    panel.style.cssText = 'position:absolute;right:16px;top:16px;padding:8px 12px;border-radius:10px;' +
                          'background:rgba(20,22,30,.86);border:1px solid rgba(230,199,138,.4);color:#e6c78a;font-size:.82rem;z-index:20';
    panel.textContent = new Date().toLocaleTimeString();

    const timer = setInterval(() => { panel.textContent = new Date().toLocaleTimeString(); }, 1000);
    panel._timer = timer;

    ctx.dom.mount(panel);              // 交给系统登记，停用时会被自动移除
},
deactivate() {
    // 定时器必须自己清：系统只负责移除元素，不会管你开的计时器
    const panel = document.getElementById('my-clock-panel');
    if (panel?._timer) clearInterval(panel._timer);
}

导入、调试与本地存储

• 导入：设置 → 插件 → 「导入插件」，选择一个 .js 文件。文件内容会被包进 new Function('MySWPlugins', code) 执行，因此插件里必须用全局的 MySWPlugins.register() 注册，而不是 ES 模块的 export。
• 持久化：导入的插件源码与参数存在 localStorage 的 mySWPlugins 里，刷新后自动重新加载；删除插件后源码一并清除。
• 参数：参数值存在插件记录里，改完要点卡片上的「保存参数」。读取时通过钩子的 params 参数拿到，不要自己去读 localStorage。
• 调试：用 console.log 输出到浏览器控制台；钩子里的异常会以 [插件名] xxx 失败 的形式打印警告，直接搜索插件名就能定位。
• 排查顺序：插件不生效时，先看卡片上有没有黄色提示条（说明权限没给全），再看控制台有没有报错，最后确认 id 是否与已有插件重复。
• 导出：自己导入、或用 AI 写好再导入的插件，卡片上有「导出」。它导出的是当初保存下来的源码，不是运行后的状态。

用 AI 编写插件

位置在「设置 → 插件」，导入按钮下面有一块默认收起的折叠板「用 AI 编写插件」。

• 模型：模型框留空就用当前聊天模型；填了名字则固定用这个模型，不再跟着站点切换。
• 怎么写：用一句话描述想要的效果，点「生成插件」。代码先出现在文本框里，可以手改。
• 确认再导入：看过代码后点「导入到 MySW」。插件进入下面的列表，默认不启用，需要的权限仍要你自己开。
• 导出：文本框里的代码可以直接「导出 JS」；已经导入的插件，在它自己的卡片上也能导出。

自带的几只猫娘插件

完整示例：两个可直接用的插件

示例一：翻译按钮（API + DOM 权限，把最后一条 AI 回复译成中文并弹出来）

MySWPlugins.register({
    id: 'quick-translate',
    name: '一键翻译',
    description: '在聊天界面加一个悬浮按钮，把最后一条 AI 回复翻译成中文。',
    enabled: false,
    permissions: ['useApi', 'useDom'],
    params: [
        { key: 'target', label: '目标语言', type: 'text', value: '简体中文' }
    ],
    activate(params, plugin, ctx) {
        if (!ctx.dom.available) return;
        if (document.getElementById('quick-translate-btn')) return;

        const btn = document.createElement('button');
        btn.id = 'quick-translate-btn';
        btn.type = 'button';
        btn.textContent = '译';
        btn.title = '翻译最后一条 AI 回复';
        btn.style.cssText = 'position:absolute;left:16px;bottom:88px;width:40px;height:40px;border-radius:50%;' +
                            'border:1px solid rgba(230,199,138,.5);background:rgba(20,22,30,.9);color:#e6c78a;' +
                            'cursor:pointer;z-index:20;font-size:1rem';

        btn.addEventListener('click', async () => {
            if (!ctx.api.available) { ctx.toast('需要「使用 API 配置」权限'); return; }

            // 取最后一条 AI 消息（.message.other 里的气泡文本）
            const bubbles = document.querySelectorAll('#chat-messages .message.other .bubble');
            const last = bubbles[bubbles.length - 1];
            const source = last ? last.innerText.trim() : '';
            if (!source) { ctx.toast('还没找到可翻译的 AI 回复'); return; }

            btn.disabled = true;
            btn.textContent = '…';
            try {
                const target = String(params.target || '简体中文');
                const result = await ctx.api.chat([
                    { role: 'system', content: '你是翻译引擎，只输出译文本身，不要任何解释。' },
                    { role: 'user', content: '把下面内容翻译成' + target + '：\n' + source.slice(0, 2000) }
                ], { max_tokens: 800 });
                ctx.toast('译文已输出到控制台');
                console.log('[一键翻译]\n' + result);
            } catch (e) {
                ctx.toast('翻译失败：' + (e.message || e));
            } finally {
                btn.disabled = false;
                btn.textContent = '译';
            }
        });

        ctx.dom.mount(btn);
    },
    deactivate() { /* mount 过的节点由系统统一回收 */ }
});

示例二：风格约束器（零权限，纯提示词注入）

MySWPlugins.register({
    id: 'style-guard',
    name: '回复风格约束',
    description: '给 AI 追加一条固定规则，比如「每次回复不超过 3 句话」。',
    enabled: false,
    permissions: [],           // 纯提示词变换，不需要授权
    params: [
        {
            key: 'rule',
            label: '要追加的规则',
            type: 'textarea',
            value: '【风格约束】请把每次回复控制在 3 句话以内，不要分点罗列，不要输出 Markdown 标题。'
        }
    ],
    transformPrompt(text, params) {
        const rule = String(params.rule || '').trim();
        if (!rule) return text;
        const base = String(text || '');
        if (base.includes(rule)) return base;   // 幂等
        return base + '\n\n' + rule;
    }
});

💗 好感度系统（实验室）

在「设置 → 实验室 → 好感度」开启后，每个角色会单独拥有一条情感进度条。它的作用不只是显示一个数字： 系统会把当前阶段对应的相处准则一并写进发给 AI 的提示词，因此好感度越高，角色确实会对你更亲近、也更愿意接受更深入的互动。

它是怎么涨的

每完成一轮有效互动（你发出消息 → 角色成功回复）结算一次，计算公式为：

本轮增量 = (基础增量 + 随机浮动 × random) × 档位衰减^当前档位序号 × 角色倍率
然后再受「每人每日上限」与「同一角色冷却时间」限制

• 基础增量：每轮固定加多少，默认 2。
• 随机浮动：额外随机加 0 ~ 该值，让进度有一点起伏。
• 档位衰减：默认 0.85。档位越高涨得越慢 —— 调小它会让后期更难涨（更耐玩），调成 1 则每档速度一致。
• 每日上限：防止一口气刷满。设为 0 即不限制。
• 冷却时间：同一角色多久内只结算一次，默认 45 秒。
• 自然衰减：长期不聊会慢慢变淡。默认「1 天不聊后每天掉 1 点」，调成 0 即可完全关闭衰减。
• 角色倍率：只想让某个角色涨快或涨慢时，单独给它设 0.1 ~ 3 的倍率。

档位与相处准则

默认提供五个档位（初识 / 熟识 / 亲近 / 亲密 / 挚爱），每个档位都可以自己改名、改起始值、改准则文本：

建议在准则里写清楚这个阶段允许到什么程度。写得太笼统，角色可能一上来就越界；写得太保守，则会永远停在最拘谨的状态。 准则会随对话动态下发，所以改完保存，下一轮对话立刻生效。

查看与管理

• 聊天界面角色名字旁会显示一枚心形徽标：数字是当前好感度，长按或点击可打开进度面板。
• 面板里可以查看每个角色的进度与最近 10 条变化记录，也能手动 ±5 或重置。
• 群聊中按「成员 × 用户」分别结算 —— 同一个群里，不同角色对你的亲近程度可以完全不同。
• 好感度只保存在本机 localStorage，随「导出全部数据」一起备份。

⚫ 五子棋与围棋（实验室）

在「设置 → 实验室 → 棋局」里可以和当前打开的单个角色下棋。群聊不能直接开始，先切回一个普通角色。

• 左边是聊天。可以边下边说话，角色会按自己的人设接话：人设里爱吐槽的可能会嫌弃你下的那一步，温和的角色就正常聊天。
• 中间是棋盘。空格上标着「列,行」，点一下就是在那里落子；刚下的那颗会多一个红圈。
• 右边有悔棋、再开一局、退出。围棋还多一个「弃权」。

每一局开始都会抛硬币：正面你执黑、先下；反面角色执黑、先下，你执白。黑子先下，之后双方轮流。棋局使用当前聊天已经配置好的 API，不需要再单独填一份。

怎么下五子棋

五子棋使用 15×15 的棋盘，规则只看一件事：谁先把自己的五颗棋子连成一条线，谁赢。

1. 黑棋先在棋盘任意空格放一颗自己的棋子。
2. 白棋再放一颗。已经有棋子的格子不能再放。
3. 横着、竖着、斜着都算。中间不能断开，也不能用对方的棋子顶上。
4. 先出现连续五颗同色棋子的一方获胜。如果棋盘放满还没有人连成五子，就是平局。

怎么下围棋

这里的围棋用的是 9×9 小棋盘，方便快速下完。黑白轮流放棋子，目的不是连成一条线，而是占住更多空位，并吃掉对方没有活路的棋子。

1. 气：一颗棋子上、下、左、右紧挨着的空位就是它的「气」。斜角不算。几颗左右相连的同色棋子算作一块，整块共用这些气。
2. 提子：把对方某一块棋的气全部堵住后，这一块会被一次性拿掉，那些位置重新变成空位。
3. 不能自杀：如果这一步放下后，自己的这块棋没有气，又没有刚好提掉对方，这一步就不允许。
4. 不能立刻还原：刚被提掉的局面不能马上下回原样，避免两个人无限循环。
5. 弃权：觉得没有好位置时，按右边的「弃权」。双方连续弃权，棋局结束并开始数子。
6. 怎么算胜负：数自己的棋子，加上四周都被自己围住的空位。白棋自动加 5.5 目，用来抵消黑棋先下的优势；点数多的一方获胜。

🗨️ 论坛功能

侧边栏的「论坛」入口会打开一个类似贴吧的本地社区，AI 角色会在里面发帖、评论、点赞和私信你。 所有内容都由你的本机 API 配置生成，只存在你自己的浏览器里，不会被其他真实用户看到。

视图与浏览

发帖与互动

• 分区：发帖时可选板块（默认 综合 / 剧情讨论 / 角色日常 / 同人创作 / 求助）。分区名可在「论坛设置」里按行自定义。
• 工具栏：顶部有搜索框（搜标题、正文、作者、分区）、分区筛选与排序方式（最新回复 / 最新发布 / 热度 / 浏览 / 点赞）。
• 楼中楼：评论可以回复某条评论，形成二级回复；顶层评论按时间正序编号为「1 楼、2 楼…」，楼主会带「楼主」标记。
• 评论点赞：每条评论都能单独点赞，只刷新那一条的计数，不会打断你的阅读位置。
• 收藏与置顶：帖子可收藏进「我的收藏」；自己发的帖子还能置顶（排到列表最前）。
• 浏览数：每次打开详情页计一次浏览，列表里会显示浏览数与最后回复时间。

让 AI 动起来

• 论坛角色：勾选参与发帖的角色并调整活跃度。活跃度越高越容易出场；活跃度为最低时不会主动发帖，只会极少回复。
• 让活跃角色逛逛论坛：立即让一个（按活跃度加权随机选出的）角色在随机分区发一帖，并可能触发其他角色的点赞与评论。
• 自由论坛：在「论坛设置」里开启后，每 90 秒会自动走一次 AI 论坛行为。设备吃力或只想安静看帖时建议关闭。
• 肃静：一键停止全部 AI 主动发帖、回复、分享与私信，只保留你自己浏览。
• 你在帖子里 @角色名，被点名的角色会来回一句；被回复的 AI 也会接着说一句。

备份与迁移

• 导出论坛数据：把帖子、评论、私信、关注、收藏与分区设置导出成一个 JSON 文件。
• 导入论坛数据：可选择「合并」（按 id 去重后追加）或「覆盖」（先清空再写入）。合并时会保留互动数更多的那个版本，避免导入把点赞清零。

❓ 常见问题 FAQ

Q1：填写完 API Key 但还是提示「请先配置 API」？

A：检查是否点过 「保存设置」（不是「测试连接」）。保存后会自动关闭弹窗。如仍报错，刷新页面重试。

Q2：AI 回复到一半就断了？

A：通常是触发了 maxTokens 上限。在设置里调大「单条回复上限」即可。

Q3：AI 经常「失忆」忘记前文？

A：调大「最大上下文轮数」。但注意：上下文越大，每次消耗的 Token 越多、费用越高。

Q4：「测试连接」成功，但实际聊天报错？

A：可能是 Key 余额不足、模型名称写错、或平台风控拦截。检查 Key 对应平台的「用量」和「模型名是否含特殊前缀」。

Q5：如何切换不同模型给不同角色？

A：当前版本所有角色共享同一套 API 配置。如需为不同角色指定不同模型，可在使用中临时切换全局设置。

Q6：可以把聊天记录分享给朋友看吗？

A：可以。点击聊天右上角 → 切换到「导入导出」标签 → 导出单角色聊天记录为 JSON 或图片长截图。

Q7：支持语音输入 / 语音回复吗？

A：浏览器原生支持麦克风输入（部分浏览器）。AI 语音播报（TTS）需在插件系统中安装 TTS 扩展。

Q8：能换主题色吗？

A：顶部 按钮可切换深色 / 浅色主题。主题色在 CSS 变量中定义，高级用户可自行修改 style.css。

Q9：AI 会把我的对话拿去训练吗？

A：取决于你使用的 API 平台。多数付费 API 平台明确表示不会用你的 API 调用数据训练模型（详见各平台隐私政策）。本应用本身是纯前端应用，不可能收集你的数据。

Q10：访问 https://mysw-yg.pages.dev 看不到侧边栏角色？

A：首次访问时浏览器会预加载约 900KB 的角色数据，请稍等几秒。如仍为空，按 Ctrl+F5 强制刷新。

Q11：一打开就弹出「欢迎来到 My SW」的弹窗，可以关掉吗？

A：那是首次访问引导，只会在完全没有任何使用痕迹时出现（没配过 API、没有自定义角色、也没有聊天记录）。点「查看使用文档」或「先自己逛逛」都会记住，之后不再打扰。它只提示一件事：可以去 https://mysw-yg.pages.dev/docs 查阅使用文档。

Q12：开了？？？模式还是觉得卡怎么办？

A：按顺序试：① 在「设置 → 界面外观 → 动效等级」里把等级降到「轻量」，只保留弹窗展开与按压反馈；② 关掉「毛玻璃效果」（大面积 backdrop-filter 是低端设备掉帧的主要原因）；③ 仍然卡就切换到「兼容模式」，它会关闭全部动画与过渡。注意旧的？？？模式曾是常驻循环动画（渐变位移 + hue-rotate + 无限旋转），现已完全重写为「播一次就停」的动效，正常情况下不会再持续占用 GPU。

Q13：想固定角色列表的顺序，不想被「最近聊过」打乱？

A：到「设置 → 界面外观」，关掉「最近聊过的角色排在前面」，列表就只按你手动拖出来的顺序排列。这个功能本身也不会影响置顶角色 —— 置顶永远优先。

Q14：好感度会不会太快刷满？

A：「设置 → 实验室 → 好感度」里所有参数都能改。嫌快就把「档位衰减系数」调小（例如 0.7）、把「每人每日上限」调低，或把某个角色的倍率单独调到 0.5。想彻底不看衰减，把「每天自然衰减」设为 0 即可。

Q15：我自己写的插件为什么不生效？

A：按这个顺序检查：① 插件卡片上的「启用」是否勾上；② 卡片上有没有黄色提示条（说明权限没给全，需要先在「插件权限」打开总开关）；③ 控制台有没有 [插件名] xxx 失败 的警告；④ id 是否与已有插件重复（重复会覆盖）。详见 插件编写指南。

Q16：论坛里的数据能备份吗？换设备怎么带过去？

A：可以。右侧栏有「导出论坛数据 / 导入论坛数据」，导出会得到一个包含帖子、评论、私信、关注、收藏与分区设置的 JSON 文件。在另一台设备上导入时可选「合并」（按 id 去重后追加）或「覆盖」。合并导入会保留互动数更多的版本，不会把点赞清零。