用户使用说明（MyZ 高亮智能助理）

本文档面向终端用户，介绍 MyZ 高亮智能助理 的核心功能、AI 智能助理（SidePanel）与 Dashboard 设置项的使用方法。

重要提示（AI / 网络功能）

• 扩展不提供任何远程服务。所有可选网络请求均由你的浏览器直接发送到你配置或正在访问的第三方服务（例如自定义 AI Provider、MCP Server、S3 兼容对象存储、X/Mastodon、YouTube）。
• 自定义 AI Provider 可能消耗大量 token 并产生高额收费；请务必了解计费规则并自行承担费用。
• 加密同步为端到端加密（E2EE）：云端仅存储密文与必要元信息，同步密钥只保存在本地设备。
• 请谨慎处理隐私数据与敏感信息，避免在不确定第三方服务数据处理策略的情况下发送内容。

1. 安装与入口

• 安装后建议把扩展固定在浏览器工具栏，便于快速打开。
• Popup：点击浏览器工具栏上的扩展图标打开，适合快速查看当前页面标注与操作入口。
• Dashboard（设置与管理）：在 Popup 右上角点击“打开 Dashboard”按钮进入（也可在扩展管理页打开“选项/Options”）。
• SidePanel（AI 智能助理）：用于基于网页上下文与模型对话；可由工具条按钮/右键菜单/页面内入口打开。

2. 基础标注（高亮 / 下划线 / 波浪线）

1. 在网页中用鼠标选中一段文本。
2. 选区附近会出现浮动工具条：
   • “添加标注”：创建可回放的高亮类标注（可选颜色与样式）。
   • “保存文字”：把选中文本保存为纯文本收藏（不在页面上生成高亮 DOM）。
   • “截取选区截图”：截图并保存（会在截图前暂时清除系统选中态以避免截图带蓝色高亮）。
3. 保存后，扩展图标角标会显示当前页面标注数量（用于快速确认是否已采集）。

3. 管理与整理（Popup / Dashboard）

3.1 Popup：快速查看当前页面

• 展示当前页面的标注/收藏列表，支持快速定位、编辑与删除等操作。
• 右上角按钮可打开 Dashboard。

3.2 Dashboard：全局管理与设置

在 Dashboard 顶部导航进入“设置”，主要包括：

• 导入标注：导入 JSON 文件，并选择冲突处理策略（跳过/覆盖/保留最新）。
• 社区导入：从 X（Twitter）或 Mastodon 抓取导入内容（无需官方 API；通常需要你已登录对应账号；存在风控/条款/页面结构变化带来的不确定性）。
• AI 智能助理：配置 AI Provider、模型能力、SidePanel 对话模型、MCP Server、本地 tools、向量检索（Vectoria）等。
• Agent Skills：导入/启用技能包，支持自动或手动启用技能。
• 加密同步：配置 S3 兼容存储与同步密钥，启用端到端加密同步。

4. AI 智能助理（SidePanel）配置

AI 能力需要你在 Dashboard → 设置中完成配置。建议按以下顺序：

4.1 启用 AI 智能助理

• 在“AI 智能助理”区域打开“启用智能助理”。

4.2 配置 Provider（OpenAI 兼容）

在 Providers 中配置：

• Base URL：例如 https://api.openai.com/v1（需为 OpenAI 兼容接口）
• API Key：由你所使用的服务提供
• Headers（可选）：逐行 Key: Value（用于自定义鉴权/路由）
• 测试连接：选择一个模型进行测试，通过后才能启用 Provider

4.3 配置模型能力（Capabilities）

每个模型可配置能力（会直接影响 UI 与可用功能）：

• 支持 Vision：允许在对话中发送图片/截图，并启用“解读图片内容”等入口
• 支持 Tool Calling：允许模型调用 tools（MCP / 本地 tools）
• 支持 Reasoning：用于启用/处理推理相关能力（若模型支持）

同时可配置 token 限制（Context Window、Max Output Tokens、输出参数名等）。

4.4 配置 Agent 模型（Conversation / Insights）

• Conversation：SidePanel 主对话使用的 Provider+Model 与温度（temperature）
  • 可选：发送前压缩图片（最长边 ≤ 640px），会按等比例缩小图片后再发送（原图本身小于 640px 不压缩）
• Insights：自动总结/要点等分析功能使用的 Provider+Model 与温度

4.5 配置 MCP Server（可选）

用于接入外部 tools：

• 添加 MCP Server URL，必要时配置 Headers
• 先“测试连接”，通过后再“启用”

4.6 配置 Agent Skills（可选）

Agent Skills 是可复用的“指令包/流程包”，会在对话前注入到模型提示中。你可以选择手动启用，或用“选择器模型”自动挑选适合的技能。

• 内置技能：随扩展提供，无法删除，但可启用/禁用。
• 自定义技能：在 Dashboard → AI 设置 → Agent Skills 中导入 Zip 或文件夹。
• 显式调用：在对话输入中使用 @skill-name 精确启用指定技能。
• 自动模式：开启“自动”并选择“选择器模型”，每次发送前会从已启用技能中挑选要使用的技能。
• 编辑能力：可在技能编辑器中修改 UTF-8 文本文件（如 SKILL.md）；二进制文件仅可查看。

实用建议

将团队流程、输出格式、写作规范整理成独立 Skill，配合 @skill-name 或“自动”模式复用。

4.7 配置本地 Tools（可选）

本地 tools 会访问扩展内的数据（例如你保存的标注）。你可以选择启用哪些工具以降低信息暴露风险。

• 手动模式：对话时暴露所有已启用的本地 tools
• 自动：选择一个“选择器模型”，它会在每次发送前根据“本次用户输入 + 候选工具列表”决定本次可用的工具子集

常见本地 tools（示例）包括：搜索本地标注、列出常用标签、网页搜索、访问网页详情提取正文等。

4.8 向量检索（Vectoria，可选）

用于从你的历史标注中检索语义相似内容（页面内浮窗与 SidePanel“相关标注”）。

• 选择 embeddings 模型（Provider+Model）并测试连接
• 启用后建议点击“重建索引”（首次启用或更换模型时尤为必要）
• 可设置 匹配阈值（40% - 100%）：只有 score ≥ 阈值的匹配才会展示（默认 50%）

5. 加密同步（E2EE Sync）

加密同步使用你自己的 S3 兼容对象存储；我们不提供任何线上服务。云端仅存储密文与必要的元信息，密钥始终保存在本地设备中。同步密钥由你输入的密码派生，我们不保存你的密码。

推荐的对象存储：AWS S3、Cloudflare R2，或其他国内 S3 兼容对象存储服务。

5.1 配置步骤

1. 进入 Dashboard → 设置 → 加密同步。
2. 填写 S3 配置：
   • Endpoint：对象存储的 S3 兼容接口地址
   • Region / Bucket
   • Access Key ID / Secret Access Key
   • Session Token（可选）
   • Prefix（可选）：用于隔离不同设备/项目的前缀
3. 点击 保存设置，然后 测试连接。
4. 设置 同步密钥：仅保存在本地，建议使用高强度口令。
5. 开启 启用同步，并点击 立即同步 执行一次手动同步。

同步状态区域会显示 KeyId、Manifest 版本、上次同步时间与密钥更新时间，便于确认同步是否生效。

重要提示

同步密钥不可找回。若遗失密码，新的客户端将无法解密旧数据，需要重新全量加密并同步；旧密文无法解密。

端到端加密公开审阅

加密同步实现可公开审阅，代码位于 https://github.com/myz-suite/sync/。

6. 使用 AI 智能助理（SidePanel）

6.1 打开 SidePanel 的方式

你可以通过以下方式进入 SidePanel：

• 浮动工具条：选中文本后点击“发送到AI助理”
  • 会打开 SidePanel，并把选中文本作为“上下文”放进输入区
  • 如果选区包含图片，会自动截取选区截图，并按你的压缩设置处理后作为图片上下文附上
• 网页右键菜单：
  • 右键页面空白处：打开AI助理 → 打开面板
  • 右键页面：打开AI助理 → 总结页面内容 / 发现关键要点
  • 右键图片：打开AI助理 → 解读图片内容（需要 Conversation 模型启用 Vision）

6.2 输入区（Input Composer）的上下文展示

当你通过上述入口把内容带入 SidePanel 时，会以“类似上传附件”的形式显示在输入区中，包括：

• 选中的文本上下文（会在最终发送的用户消息中以“选中内容（上下文）”展示）
• 附带的图片/截图（可移除、可预览）
• 你自己输入的对话文本（可编辑）

你可以在发送前：

• 自定义要问模型的文字
• 决定是否勾选“页面上下文”（默认不勾选）
• 删除不想发送的上下文/图片

6.3 发送后展示与图片预览

• 若发送内容包含“选中内容（上下文）”，对话气泡会同时展示：
  • 你输入的内容
  • 选中内容（上下文）
• 若发送内容包含图片/截图：
  • 对话中会显示缩略图
  • 点击缩略图会在 SidePanel 弹出预览窗口，并按原始比例展示

6.4 对话线程与历史

• SidePanel 顶部提供：
  • 新对话：为当前页面开启一个新的对话线程（不会清空你的输入草稿/附件状态）
  • 历史：查看对话历史并切换加载
• SidePanel 每次被重新打开/重载时，会创建一个新的对话（避免复用旧线程造成上下文过长）。
• SidePanel 在保持打开的情况下切换浏览器 Tab：
  • 页面标题会随当前 Tab 更新
  • 对话线程仍保持（并通过状态栏提示是否已“跨页面”）

7. 相关标注（Vectoria Interests）

当启用向量检索后，扩展会在页面内根据你正在阅读的段落，匹配你历史标注中的相似内容：

• 页面内会出现“相关标注”浮窗，展示当前视窗内最相关的若干条
• 每条会显示相似度（score）与来源页面信息
• 点击“侧边栏查看全部”会打开 SidePanel 的“相关标注”视图，展示更多匹配结果

提示：

• 若结果过多/过少，可在 Dashboard → 设置 → 向量检索（Vectoria）调整“匹配阈值”
• 更换 embeddings 模型后，建议重建索引以提升匹配质量

8. 社区导入（X / Mastodon）

在 Dashboard → 设置 → 社区导入中，可填写个人主页地址并选择要导入的类型。

使用说明：

• 导入过程会打开新窗口展示抓取流程
• 书签/私密内容通常需要你已在浏览器中登录账号

风险提示：

• 该功能通过页面抓取实现，可能受到第三方网站条款、风控策略与页面结构变化影响
• 你需要自行决定是否启用，并自行承担账号受限、访问受阻、抓取失败、内容不完整等风险与后果

9. 禅定模式（Zen Mode）

在包含文章主体的页面，右键菜单可看到：

• “禅定模式 (仅显示文章)”：进入后仅保留文章主体区域的可读内容（不破坏 DOM 结构，尽量避免影响标注恢复）
• “保存文章为图片”：仅在禅定模式启用后可见，用于导出文章主体截图

若菜单未出现，说明当前页面未检测到可识别的文章主体，可等待页面加载完成后重试，或在后续版本中补充规则。

10. 常见问题排查

10.1 AI 相关入口不可用

• “解读图片内容”呈灰色或提示“需 Vision 模型”：请在 Dashboard → 设置中为 Conversation 模型开启“支持 Vision”
• 模型无法调用工具：请开启“支持 Tool Calling”，并启用 MCP Server 或本地 tools

10.2 向量检索无结果

• 确认已启用向量检索并测试通过
• 首次启用或更换模型后，点击“重建索引”
• 尝试降低“匹配阈值”

10.3 社区导入失败

• 确认已登录账号（尤其是书签等私密页面）
• 第三方网站可能出现风控/限流/页面结构变化，建议稍后重试或减少导入量