JustZix — 使用手册

向任意网页注入自定义 CSS 样式、JavaScript 代码和操作按钮

概念与核心术语

JustZix 让你可以自动向选定网页注入自己的 CSS 和 JavaScript，并定义操作按钮（按需执行代码片段的快捷方式）。

数据层级

集合和分组级别的 URL 模式

每个集合以及每个分组都可以拥有自己的附加 URL 模式列表（chip-input）。列表为空时 —— 元素在目录模式匹配的所有地方生效。当你设置如 https://justzix.com/admin/* 时 —— 元素仅在 admin 子页面上生效。

教程 —— 交互式入门

对于新用户，JustZix 内置了交互式教程，带你一步步构建一个完整的方案 —— 从 folder，经过 group 和 rule 集，到 CSS/JS 代码和一个操作按钮。提示以气泡形式出现在面板的相应元素旁边。

如何启动：

• 自动 —— 首次打开面板、还没有任何 folder 时。
• 手动 —— 任何时候，从设置菜单 → 教程。

在「教程中心」窗口中选择一个教程并点击开始。教程过程中：

• 上一步和下一步按钮在步骤间切换；气泡底部的进度条显示进度。
• 有些步骤会等待你执行指定操作 —— 例如点击高亮的按钮。
• 带示例代码的步骤有复制按钮。
• Esc 键或 × 按钮可随时关闭教程。

界面与导航

编辑模式

通过右键点击扩展图标 → 「选项」，或点击图标 → 「编辑面板」按钮进入。

• 侧栏顶部的 logo —— 完整的 justzix logo（标志 + Inter wordmark）。会根据应用模式在 light 和 dark 变体间自动切换（内联 SVG + CSS variables，无需替换文件）。点击 logo 会打开仪表板。
• 「目录」区域 —— logo 下方：label「KATALOGI」+ 添加目录按钮、搜索框、「仅激活」过滤器。
• 目录树 —— folder ▶ 分组 ▶ 集合。展开箭头切换。点击集合进入仅编辑该集合。
• 设置菜单（侧栏底部的 drop-up）—— 单个按钮打开带选项的面板：深色模式、使用手册、导出设置、导入设置、从 URL 导入、云同步、我的 share、AI Helper、项目网站、语言选择、Storage quota 指示器以及扩展版本号。通过 Escape 或点击面板外部关闭。
• 目录栏 —— 按钮标签（3 个字母）、颜色、名称、URL 模式、操作面板选项、导出/导入、删除。
• 集合卡片 —— 每个有 3 个标签页：CSS JavaScript 操作。
• 面包屑栏 —— 在目录、分组和集合编辑器中显示导航路径；最左侧是「主页」图标 —— 快速返回仪表板。
• 编辑器调整大小 —— 每个编辑器（CSS 和 JS）下方的栏可以向下拖动以扩大工作区域。
• 侧栏切换 —— 侧栏与编辑器之间的垂直条隐藏左侧面板以获得更多空间。

浮动按钮（在匹配的页面上）

小圆形按钮自动出现在与任何目录匹配的页面上。默认显示文字 ZIX，但每个目录可以有自己的标签。

目录标签：在目录栏最左侧（color picker 旁边）有一个用于按钮标签的文本字段。强制限制：最多 3 个字符，始终大写（输入时立即转为大写）。该字段接受字母和数字 —— 示例：ZIX、QA、DEV、ADM、X。多个目录匹配时取第一个设置了标签的目录的标签；其余被忽略（空字段 = fallback 到 ZIX）。

颜色状态（品牌调色板）：

• Inject Green（如果设置了则为目录颜色）—— 所有匹配的目录已启用
• Syntax Orange（或柔化的目录颜色）—— 部分启用，部分禁用
• Muted Gray —— 全部禁用
• Halt Red（opacity 0.7）—— 扩展全局禁用

目录颜色：如果在目录上设置了 color picker，匹配页面上的浮动按钮会采用该颜色。「mixed」和「off」状态会自动调节饱和度。多个目录匹配时取第一个设置了颜色的目录的颜色。

仪表板

进入编辑面板后，扩展会打开仪表板 —— 一个带有库概览和快捷入口的主页。此前面板会自动选中列表中的第一个目录；现在取而代之的是一个总览。

仪表板可通过侧栏中的点击 logo，以及通过每个编辑器（目录、分组、集合）面包屑栏上的「主页」图标进入。仪表板本身的标题也有一个「主页」图标 —— 点击它会刷新数据（从 storage 重新加载库并重新渲染仪表板）。

仪表板采用固定行的卡片布局：

• 库 —— 清单：目录、分组、集合、操作、操作栏、前端窗口的数量，以及含 CSS 的集合和含 JS 的集合。
• 使用统计 —— 实际计数器：操作点击、CSS 应用、JS 执行和窗口显示。数值会汇总自所有已配对的设备（通过云同步）。
• 最近编辑的集合 —— 最多 6 个最近集合的列表（按修改日期排序）；点击会在编辑器中打开该集合。
• 提示 —— 来自手册的随机建议；提示池共 30 条提示，可通过「上一条」/「下一条」按钮切换。旁边有指向完整手册的链接。
• 最新示例 —— 来自 justzix.com 库的最新示例（带分类和添加日期）。
• 来自博客 —— 来自项目网站的最新博客文章。
• 扩展状态 —— 一行三张卡片：已安装版本（含是否有更新版本的信息）、chrome.storage.local 内存占用，以及最近一次云备份的日期。

「最新示例」和「来自博客」卡片从项目网站获取内容；当 endpoint 不可用时（例如离线），这两张卡片会被隐藏。每次进入仪表板时都会重新检查扩展版本。

目录树（侧栏）

编辑模式下的左侧面板以层级显示目录 —— 可以展开每个目录查看其集合并进入编辑特定集合。

导航

更改顺序（drag & drop）

将鼠标悬停在目录、分组或集合上 —— 左侧会出现 drag&drop 句柄。用鼠标抓取并拖动：

目录

• 目录 → 目录 —— 更改顺序（蓝线显示插入位置：元素上方或下方）

分组

• 分组 → 分组（同一目录） —— 更改目录内的顺序
• 分组 → 分组（不同目录） —— 在目录间移动分组
• 分组 → 目录名称 —— 将分组移到目标目录的末尾

集合

• 集合 → 集合（同一分组） —— 更改分组内的顺序
• 集合 → 集合（不同分组） —— 在分组间移动集合并保留位置
• 集合 → 分组名称 —— 将集合移到目标分组的末尾
• 集合 → 目录名称 —— 将集合移到目录的第一个分组（当目录有多个分组时）

侧栏切换

侧栏与编辑器之间的垂直条隐藏左侧面板 —— 当你需要更多编辑器空间时很有用。状态在会话间记住。显示/隐藏后 CodeMirror 自动更新其宽度。

编辑器调整大小

每个编辑器（CSS、JS、操作代码）下方有一个带垂直拖动句柄的水平条。用鼠标抓取并向下拖动以扩大编辑器。最小高度 80px，最大不限 —— 页面随内容自然滚动。

代码编辑器中的搜索

在每个 CodeMirror 代码编辑器上方 —— 集合卡片中的 CSS 和 JavaScript 以及操作编辑器中的「JS 代码」—— 都有一个搜索栏：文本字段和带放大镜图标的按钮。

• 启动搜索后，所有找到的片段都被高亮 —— 当前匹配为黄色（黑色文本），其余为蓝色（白色文本）。
• 字段旁出现 n / 共计 格式的匹配计数器。
• 当匹配多于一个时，出现 ▲ ▼ 箭头以在结果间切换。当前匹配会滚动到视图中。
• 编辑代码使结果失效 —— 需要重新搜索。

快捷键

URL 模式

URL 模式定义目录在哪些页面上激活。

集合状态（激活 / 启用）

每个集合有两个独立的标志：

开关级联

切换目录  →  改变其分组中所有 active rule 的 enabled
切换分组  →  改变该分组所有 active rule 的 enabled
切换集合  →  仅改变该集合的 enabled

带 激活：否（badge ○）的规则在级联中被跳过 —— 你只能手动控制它们，与 folder 和分组的状态无关。

实用示例

浮动按钮与面板

在展开的面板（右键）中你可以：

• 启用/禁用各个目录
• 启用/禁用各个分组（当 folder 有多于一个分组时）
• 启用/禁用目录中的单个集合
• 启用/禁用操作栏 —— 集合列表下方的「操作栏」区域，每个栏一个复选框，修改 actionBar.enabled（持久，传播到编辑面板）
• 断开栏的连接 —— 当浮动按钮与栏吸附（snap & connect）时出现「连接」区域，带按钮「断开与：X」+「断开全部」

面板仅显示激活的集合（●）—— 独立的（○）为求简洁被隐藏。当 folder 只有一个名为「默认」的分组时，分组标题被省略 —— 只见集合。

popup 小部件（扩展图标）

点击 Chrome 扩展栏中的 JustZix 图标会打开 popup 小部件 —— 当前标签页的紧凑控制面板。自上而下：

• 编辑面板 —— 在新标签页中打开编辑模式（选项页面）的按钮。
• Plugin enabled —— 扩展的全局开关大型切换器（绿色 = 启用，灰色 = 禁用）。
• 栏编辑模式 —— 当前标签页的操作栏编辑模式切换器。
• AI Helper —— 在当前标签页上打开/关闭 AI 助手窗口的切换器。
• 当前标签页的 URL 地址。
• 与页面匹配的目录列表 —— 启用/禁用每个目录的复选框以及为该页面隐藏浮动按钮的「eye-off」图标。
• 操作栏 —— 每个栏带复选框的区域（持久 actionBar.enabled）。
• 恢复浮动按钮 —— 当按钮已为当前页面隐藏时出现的链接。

操作栏（ActionBars）

在一个 workspace 中你可以有多个操作栏 —— 每个有自己的名称、方向、背景色、自己的按钮集和按浏览器窗口独立的位置。栏可以分配给folder、分组或单个集合（决定可见性和级联）。

创建和编辑栏

在目录、分组或集合的编辑器中有一个按钮 「操作栏 (N)」。点击打开栏管理 modal。在 modal 中：

• 添加栏 —— 你选择分配级别（当前上下文的 folder / 分组 / 集合）
• 名称（最多 6 个大写字符）—— 带名称的可选 tab 从栏边缘突出
• 方向 —— 水平或垂直
• 背景色 —— color picker（JustZix 品牌调色板）
• 启用 —— 取消勾选时，栏完全不渲染（不只是视觉隐藏）。状态保存在 storage 中，独立于按窗口位置

向下继承的可见性

• folder 栏对该 folder 的所有激活集合可见（通过 barId 聚合它们的操作）。
• 分组 栏 —— 仅对该分组的集合可见。
• 集合 栏 —— 仅当集合激活时可见。
• 在某分支中没有任何可见且启用的操作的栏完全不渲染。

将操作分配到栏

集合卡片「操作」标签页中的每个操作都有一个下拉框 「操作栏」 —— 你从该集合可见的栏列表（集合自有的栏 + 分组的栏 + folder 的栏）中选择目标栏。

栏的吸附（snap & connect）

拖动栏时，扩展会检测相邻栏和浮动按钮在 ≤ 12 px 距离内的边缘。会出现 sticky 视觉指示器，松开后栏会连接成一个连接组。之后：

• 连接的栏一起移动（group drag）。
• JustZix 浮动按钮也可以参与连接（__float 作为 pseudo-bar）。
• 连接按窗口记在会话内存中。

右键点击栏的 drag handle → context menu：

• 隐藏此栏（到 reload） —— 按浏览器窗口的 runtime hide。栏在 F5 / URL 更改 / 关闭并打开标签页后恢复。永久禁用：见下方 显示/隐藏栏。
• 断开与：X（）—— 为每个相邻连接出现。
• 断开所有连接（）—— 当栏与多于一个连接时。

在栏编辑模式下此菜单被静音；此时在标签上右键会给出「删除标签」选项。

显示/隐藏栏 —— 来自 3 个地方

对于操作栏的永久启用/禁用（无需 F5），扩展提供三个入口，全部映射到 storage 中相同的 actionBar.enabled —— 从一个地方更改会传播到编辑面板和其他 UI：

1. Floating panel（右键点击主 JustZix 浮动按钮）—— folder/分组/集合列表下方的「操作栏」区域。每个栏的复选框显示持久状态。点击 → 切换 actionBar.enabled。
2. popup 小部件（点击地址栏旁的扩展图标）—— folder 列表下方的「操作栏」区域。加上每个 folder 的小「eye-off」图标 —— 为当前页面隐藏浮动按钮（用「恢复浮动按钮」链接恢复）。
3. chrome.contextMenus（页面上右键 → JustZix → 操作栏）—— 每个栏带复选框的动态子菜单。列表按活动标签页和每次状态更改重建。

栏编辑模式 —— 自由布局

操作栏编辑模式可通过三种方式开启：快捷键 Ctrl+Alt+S（从页面任意位置生效）、扩展 popup 小部件中的切换器，以及 Chrome context menu（右键 →「操作栏编辑模式」）。屏幕顶部会出现一个信息栏；再次使用任一切换器退出该模式。

在编辑模式下，元素的正常工作被暂停（点击不触发代码，字段不接受焦点）—— 取而代之，元素可以排布和缩放：

• 选择 —— 点击 = 单个元素；Ctrl+点击 = 添加/取消选择；点击空白区域或 Esc = 取消全选。Shift+在空白区域拖动 = 范围选择（矩形）。
• 移动 —— 用鼠标拖动选择。多个选中的元素一起移动。
• 调整元素大小 —— 单个选择时会出现带 8 个句柄的框（4 个角 + 4 条边）。
• 调整栏大小 —— 栏在右边缘、下边缘和角上有句柄（更改画布大小）。
• 标签 —— 栏上方的 「+ Label」 按钮在第一个空闲位置添加一个静态文本标签。双击标签打开编辑器（文本、字体、大小、颜色、「删除」）。标签像操作元素一样移动和缩放。
• 删除标签 —— Delete 键一次删除所有选中的标签；在标签上右键给出「删除标签」选项；标签编辑器中也有「删除」按钮。操作元素在编辑面板中删除（它们属于规则）。
• 重置栏 —— 栏上方的 「重置栏」 按钮恢复默认布局（flow）：移除元素的自定义位置和大小以及所有标签（带确认）。
• 撤销 —— Ctrl+Z 撤销最后一次更改（移动、调整大小、添加/编辑/删除标签、重置）。历史涵盖当前编辑会话。

编辑模式是「硬性」的：移动和调整大小会对齐到 8 px 网格，元素无法拖出栏或放在另一个元素上 —— 碰撞时两个元素（移动的和它下面的）都获得红色边框，松开后元素回到先前的位置。栏无法缩小到使元素位于外部；当新元素或标签不适合栏时，栏画布会自动扩大。在编辑模式下右键点击栏不显示「隐藏/断开栏」菜单。

栏布局模式：栏以 flow 模式启动（经典 flexbox —— 元素一个接一个，垂直或水平）。第一次移动或缩放元素会将栏转换为 custom 模式（自由定位的画布）—— 视觉上无变化，因为当前布局被快照为起点。

操作类型：BUTTON / SELECT / INPUT / SLIDER / TEXTAREA / TOGGLE3

每个操作都有一个类型 —— 由集合卡片中每个操作开头的下拉框选择。有 6 种类型可用：

静态文本标签不是操作类型 —— 在编辑模式下直接在栏上添加（见「栏编辑模式」→ 标签）。

共有字段

• Label —— 最多 6 个字符（大写，等宽）。显示在按钮上、作为 INPUT/TEXTAREA 的 placeholder，或作为 SELECT/SLIDER/TOGGLE3 上方的 tab。
• 颜色 —— color picker（元素背景；对 TOGGLE3 = 活动状态的背景）。
• 第二种颜色（colorText） —— 第一个旁边的 picker，外加带原生 ctrl+C/V 的 hex 字段。每种类型的语义：
  • BUTTON / SELECT（face）/ INPUT / TEXTAREA —— 文本颜色
  • SLIDER —— 滑块颜色（滑块的 accent-color）；label 和值的文本是单独的字段（见下方「细粒度颜色」）
  • TOGGLE3 —— 活动状态的文本颜色
  每个 picker 都有一个 × 按钮恢复默认（空 = 渲染器 fallback 到 CSS 默认 —— 通常为白色）。
• 操作栏 —— 将操作分配到特定 ActionBar 的下拉框。
• 可见性 —— 「可见」复选框允许快速隐藏而不删除。
• 键盘快捷键 —— 点击并按下组合（Chrome 保留的快捷键会被警告）。
• JS 代码 —— 激活时执行。可用变量：value、$el（DOM 元素）、$action（{ id, label, type, el }）；对 TOGGLE3 额外有 stateIdx（0-2）和 stateLabel。

SELECT —— 选项 modal

点击 SELECT 类型操作卡片中的 「选项 (N)」 打开 modal：

• Variant：static（选项在此配置）或 js（代码填充原生 <select>）。
• static 的选项列表：每行是 { name, value }。name = 用户看到的，value = 作为变量 value 进入 JS 的。
• 细粒度下拉框颜色 —— 两个 variant 共有：
  • colorDropdownBg —— popup 面板的背景（static）+ <option> 的背景（js variant）
  • colorOption —— 下拉框中选项名称的文本颜色
  • colorSelected —— 选中选项的背景（static；在 js 中为浏览器特定的原生）
  • colorHover —— 光标下选项的背景（static）
• 稳定的操作 ID —— 完整的 action.id，带复制按钮 + 示例 JS selector。

INPUT —— 配置 modal

• Placeholder —— 输入前可见的文本。
• Default value —— 初始值（memory 中无条目时）。
• colorPlaceholder —— placeholder 文本颜色（通过 CSS variable，因为伪元素 ::placeholder 不可内联设置样式）。
• 稳定的操作 ID + 示例 JS selector。

SLIDER —— 配置 modal

• Min / Max —— 数字范围（如 0–100）。要求：min < max。
• Step —— 步长（如 1、5、0.1）。默认 1。
• Default value —— 初始值（无 memory 时）。默认 (min+max)/2。
• Unit —— 显示在值后面的单位（如「px」「%」）。可选。
• colorLabel —— 滑块左侧 label 的颜色。
• colorValue —— 右侧数字+单位的颜色。
• JS 代码 —— 在 change（松开鼠标 / Tab / Enter）时执行。value = 数字值。

TEXTAREA —— 配置 modal

• Placeholder / Default value —— 类似 INPUT（初始值可包含 \n 表示换行）。
• Rows —— 可见行数（1-20，默认 3）。控制字段高度。
• colorPlaceholder —— 类似 INPUT。
• JS 代码 —— 在 change（blur，不是 Enter —— textarea 中的 Enter 是正常换行）时执行。用户离开字段 → 保存值并触发代码。value = 含换行符的 string。

TOGGLE3 —— 配置 modal

• 3 个状态 —— 恰好 3 个，每个带字段 label（最多 5 个字符，大写）和 value（作为 value 传给代码的 string）。默认 label：OFF / MID / ON。
• Default state —— 每个状态旁的 radio button 指示哪个是初始状态（无 memory 时）。默认 0。
• colorBg —— wrap container 的背景（整个 segmented control）。
• colorHover —— 非活动按钮上的 hover 背景。
• colorInactiveText —— 非活动状态的文本颜色（活动状态使用 colorText）。
• JS 代码 —— 每次状态更改（点击非活动项）时执行。变量：value（state.value，fallback 到 state.label）、stateIdx（0-2）、stateLabel、$el（容器 div）。

持久 memory（SELECT、INPUT、SLIDER、TEXTAREA、TOGGLE3）

选择 / 值 / 滑块位置 / textarea 内容 / toggle3 活动状态会按操作自动记住。F5 后值恢复；关闭标签页并重新打开它后（在与规则匹配的页面上）也恢复。每个 action.id 单例 —— 一个值，与具体 URL 无关。

每种类型 memory 中的值格式：

• SELECT（两个 variant）、INPUT、TEXTAREA → string
• SLIDER → number（或经过 storage 往返后的 string-numeric）
• TOGGLE3 → 整数 0-2（活动状态的 INDEX，不是 value）

Storage：

• Primary：sessionStorage —— 同步、F5-safe、每个标签页。
• Backup：chrome.storage.local.actionMemory[id] —— 跨标签页、durable。

无跨设备同步：memory 保留在本地。两台电脑可以有不同的值（如每个用户不同的过滤器）。

稳定的操作 ID

每个操作都有不变的 action.id（格式 a_<base36>_<random>）。在集合卡片中，每个操作旁有一个带行号的 badge —— 点击将完整 ID 复制到剪贴板，tooltip 显示完整 ID。

在用户 JS 中通过 data-jz-action-id 引用：

const el = document.querySelector('[data-jz-action-id="a_mp1deeq3_uimd8l"]');
el.value = 'nowa wartość';
el.dispatchEvent(new Event('change'));

或通过 window.JZ helper —— 见从 JS 编程式调用操作。

Chrome context menu

在任意页面上右键 → JustZix：

• 为此页面启用/禁用浮动按钮 —— 切换主浮动按钮的可见性（类似 popup 中的「eye-off」）。
• 操作栏编辑模式（启用/禁用） —— 在活动标签页上切换栏编辑模式；快捷键 Ctrl+Alt+S 和 popup 中切换器之外的第三个入口。
• AI Helper（启用/禁用） —— 在活动标签页上打开或关闭 AI 助手窗口。
• 操作栏 ▸ —— 每个栏带复选框的子菜单。仅列出与活动标签页相关的栏。复选框 = 持久 actionBar.enabled 状态。
• CSS 窗口 ▸ / JS 窗口 ▸ / JS 控制台 ▸ / Output 控制台 ▸ —— 对 4 种前端窗口类型中每一种的类似子菜单（见下方部分）。复选框 = 每个窗口的 enabled 状态。
• 临时窗口（TEMP）▸ —— 带 4 个项的子菜单：TEMP CSS pane / TEMP JS pane / TEMP JS Console / TEMP Output Console。点击 = 切换（创建或关闭）。在任意页面上有效，与 folder 匹配无关。

窗口子菜单在以下情况重建：tabs.onActivated、tabs.onUpdated（URL 更改）和 folders/groups/rules/actionBars/cssPanes/jsPanes/jsConsoles/outputConsoles/floatingHidden 的 storage.onChanged。TEMP 子菜单是静态的（始终 4 个项）。

前端窗口（CSS / JS / 控制台）

扩展提供四种类型的浮动窗口，注入到页面上，与操作栏并列。每个窗口分配给 folder、分组或集合（像操作栏一样级联继承可见性），并出现在 URL 匹配的页面上。

管理：在 folder / 分组 / 集合的编辑器中你会找到一个按钮 「窗口 ▾ (N)」。点击展开带 4 种类型的菜单 —— 你选择类型，打开带该级别窗口列表的 modal（加上从上层继承的窗口）。你添加、命名、上色、删除。

CSS pane

带 CSS 文本字段的浮动窗口。每次更改（短暂停顿后）都会更新注入的 <style> —— 你实时看到效果。内容按浏览器标签页记住（在 F5 后存活，关闭标签页时消失）。适合在不保存到规则中的情况下快速测试 CSS。

JS pane

在页面上下文中执行的 JavaScript 文本字段。代码在变化后（带延迟）或手动用 ▶ Run 按钮 / 快捷键 Ctrl+Enter 运行。执行错误显示在代码下方的红色条中。当代码自上次运行以来已更改时，Run 按钮亮黄色（「dirty」状态）。

JS Console（REPL）

页面中完整的控制台。你在底部字段输入代码，Ctrl+Enter（或 ▶）执行，结果追加到上方的日志区域。功能：

• 命令历史 —— input 第一行/最后一行的 ↑/↓ 箭头滚动先前的命令（像终端一样）。
• Ctrl+L —— 清除 output。
• console.* 捕获 —— 执行期间的 console.log/warn/error/info 调用显示在日志中（按类型着色）。
• 着色的行：命令（蓝色）、结果（浅色）、错误（红色）、console.log（灰色）、console.warn（黄色）。

Input、output 和历史按标签页记住。控制台在页面的 MAIN world 中执行代码 —— 你可以访问页面的所有变量和函数。

Output Console

只读的日志查看 —— 自动捕获页面上发生的所有事情：console.log/warn/error/info/debug、未捕获的异常、未处理的 Promise rejection、网络流量以及对 dataLayer 的 push，还有你自己的 logger window.JUSTZIX.*。与 JS Console（你自己输入代码）不同 —— 这里日志自己流入。

带计数器的六个标签页

窗口分为 6 个标签页，每个带条目计数器（badge）：

上下文过滤器栏

标签页和搜索字段之间有一个过滤器栏，它根据选定的标签页变化：

• All —— 无附加过滤器。
• JZconsole / Console —— 级别选择框：log、info、warn、error、debug。取消勾选级别 → 行从预览中消失。
• Network —— 三行：资源类型（document、script、stylesheet、image、xhr/fetch、font、…）、HTTP 状态类（2xx/3xx/4xx/5xx）以及大小和时间的范围滑块（0–100000 ms）加上按域名过滤的字段。复选框行有全选 / 全不选快捷方式。
• Errors —— 无复选框；展开每个错误以查看详情。
• DataLayer —— 窗口分为两半（见下文）。

搜索

过滤器栏下方有一个始终可见的搜索字段。实时过滤活动标签页的条目（片段匹配，不区分大小写）。Esc 清除字段。

控制台日志 —— 像 DevTools 一样可折叠

console.* 条目默认折叠 —— 显示缩短的预览（如 [PickupMap][2026-05-16T15:25Z] AUTO_SELECTION_SKIPPED: {reason: 'Lower priority source', …}）。点击展开完整参数（对象/数组作为可展开的 JSON 树），类似 DevTools 控制台。

Network 标签页

Network 通过 chrome.webRequest 捕获请求（manifest 中的 webRequest 权限）。每个条目显示方法、URL、状态、资源类型、大小、持续时间、远程地址（Remote address）和发起者（Initiator）等。请求缓冲区在后台维护，因此窗口打开前的条目也会出现。

DataLayer 标签页

DataLayer 窗口分为两列：

• 左 —— 新 push：后续 dataLayer.push(...) 调用按事件顺序的流。
• 右 —— 当前状态：window.dataLayer 对象的实时内容，作为索引化（0:、1:、…）的可展开 JSON 树 —— 你深入嵌套数据，类似 DevTools 中的对象检查器。快照在每次 push 后更新。右列标题中有展开全部 / 折叠全部按钮 —— 递归作用于整棵树。

对 JustZix 自身 UI 的点击（展开树节点、窗口按钮）不会进入此标签页。如果页面收集 click 事件（例如 GTM auto-event），点击窗口会生成对 dataLayer 的 push 并重置树的展开状态 —— 扩展会识别此类 push 并不予报告（页面真实的 window.dataLayer 保持不变）。

自有 logger —— window.JUSTZIX

Output Console 提供从你的代码（JS pane、操作、页面代码）记录日志的全局 API：

JUSTZIX.log('zwykły log');
JUSTZIX.warn('ostrzeżenie');
JUSTZIX.error(new Error('błąd'));   // 显示 stack trace
JUSTZIX.info({ obj: 1, arr: [2,3] });
JUSTZIX.debug('szczegóły');          // 默认隐藏（过滤器）

可用别名：

• window.JUSTZIX —— 主要的，始终可用
• window.__JUSTZIX__ —— 始终可用的别名
• window.JZ —— 别名，仅当页面没有自己的 window.JZ 时（某些页面，如 Google Ads，占用了这个名称）

Output Console 出现后，你会在日志中看到一行欢迎消息，告知该页面上哪个别名可用。

捕获的内容

• 页面的 console.log/warn/error/info/debug(...) —— 也透传到正常的 DevTools 控制台（我们不阻止）
• window.JUSTZIX.*(...) —— 你的专用通道（不进入 DevTools）
• 未捕获的异常（throw new Error(...)）—— 显示为带错误位置的红色
• 未处理的 Promise rejection —— 没有 .catch 的 Promise.reject(...)

fetch/XHR 请求错误不进入 Errors 标签页（它们不是 JS 异常）—— 你会在状态 4xx/5xx 后的 Network 标签页中找到它们。我们不捕获 CSP 违规或 Chrome 内部警告。

快速帮助 —— Ctrl+Shift+H

Ctrl+Shift+H 打开一个可移动的快速帮助窗口 —— 在页面上使用 JustZix 的指南：全局快捷键、窗口内快捷键、Output Console、用鼠标操作窗口、操作栏编辑模式以及记录到 Output Console。它在任意页面都有效。抓住标题栏拖动窗口；Esc / 点击外部 / × / 再次 Ctrl+Shift+H 关闭。

自定义窗口外观

颜色：在管理 modal（编辑面板）中，每个窗口都有 color picker —— 标题圆点、标题背景和文本、body 背景和文本、操作按钮颜色。

字体和大小：右键点击窗口的标题栏 → 带字体选择（Consolas、Menlo、Monaco、Courier New 和其他等宽字体）和大小（10–24 px）的菜单。

拖动、吸附和连接

你抓住标题栏拖动每个窗口。当边缘靠近另一个窗口 / 操作栏 / 浮动按钮（≤ 12 px）时，会出现磁性吸附 —— 窗口连接成一个组。拖动连接的组会一起移动所有元素。位置按浏览器窗口记住。

调整窗口大小

每个窗口有 8 个 resize 句柄：4 个在角上（同时改变宽度和高度）以及 4 个在边缘上（仅改变一个轴）。被拖动的句柄保持对边不动。范围：宽度 180–1200 px，高度 120–900 px。新尺寸（pane.size）会被保存 —— 对持久窗口在设备间同步，对 TEMP 窗口按标签页。

窗口内滚动

在窗口内用鼠标滚轮滚动只会滚动该窗口的内容 —— 下方的页面不会滚动。当窗口区域到达滚动末端，或光标位于不可滚动的部分（标题、过滤栏）上时，同样如此。

右键点击窗口标题

• 上移一层 / 下移一层 —— 在窗口重叠时更改顺序（一次性跳转到所有重叠邻居之上 / 之下）。
• 断开与：X / 断开所有连接 —— 当窗口已连接时。
• 关闭窗口 [类型] —— 隐藏窗口（可从面板 / popup 重新启用）。
• 字体 / 大小 —— 选择文本字体和大小。

关闭按钮和标题双击

每个窗口（无论是临时 TEMP 还是持久窗口）在标题栏右角都有一个× 关闭按钮。TEMP 被隐藏（从页面上下文菜单或快捷键重新打开），持久窗口 —— 被禁用（用 popup 中的复选框重新启用）。在标题栏双击：

• 持久窗口（CSS pane / JS pane / JS Console / Output Console） —— 将窗口折叠 / 展开到仅标题。状态被记住。
• TEMP —— 在记住的大小 ↔ 默认之间切换。
• AI Helper —— 在记住的大小 ↔ 默认之间切换。

吸附和边缘高亮

当窗口边缘靠近另一个 JustZix 窗口（12 px 阈值）时，在吸附侧（两个窗口上）出现红色边缘。在此位置释放光标执行 snap —— 窗口随后作为一组移动。扩展的所有窗口都参与此机制：操作栏、FAB、持久面板（CSS/JS/Console/Output）、TEMP 和 AI Helper。

TEMP pane — 临时窗口

你可以在任意页面上创建临时窗口 —— 即使是你没有任何 folder 的页面。TEMP pane 是快速的 ad-hoc 工具：在陌生页面上测试 CSS/JS 而无需配置规则。

TEMP pane 的特性：

• 在每个页面上有效（绕过 folder 匹配）
• 按标签页记住 —— 在 F5 后存活，关闭标签页时消失。不在设备间同步。
• 不同于标准窗口的颜色 —— 橙色（CSS）、红色（JS）、粉色（JS Console）、青色（Output）—— 整个窗口边框为该颜色。
• 名称中带 「TEMP」。
• 标题右上角的红色叉号 × —— 关闭窗口。数据（代码、日志、几何）保留在会话中——重新打开相同类型的窗口可恢复。仅在关闭标签页时消失。
• 垃圾桶图标位于 TEMP CSS / TEMP JS 的标题栏——一键清空编辑器内容。清空会进入浏览器的撤销历史（Ctrl+Z 可恢复）。对于 CSS，实时 <style> 会立即更新。
• 每种类型最多一个 —— 第二次按下快捷键会关闭现有窗口；第三次按下会重新打开，并保留之前的内容。
• 尺寸记忆（按设备） —— TEMP 窗口被调整大小后，其最后尺寸会按每种类型（CSS / JS / JS Console / Output）分别记入设备存储。它在浏览器重启后仍保留，且不在设备间同步。新打开的 TEMP 窗口以默认尺寸（380×240）启动。
• 双击标题栏 = 尺寸切换 —— 双击 TEMP 窗口的标题栏会在默认尺寸与记住的尺寸之间切换。

创建 / 关闭（切换）：

• Ctrl+Alt+G —— TEMP CSS pane
• Ctrl+Alt+H —— TEMP JS pane
• Ctrl+Alt+J —— TEMP JS Console
• Ctrl+Alt+K —— TEMP Output Console
• 或：页面上右键 → JustZix → 临时窗口（TEMP）▸

AI Helper — AI 助手

AI Helper 是内置于扩展的 AI 助手，帮助为当前页面上的具体任务准备并部署 CSS/JS 方案。模型可以检查页面、在 TEMP 窗口中实时测试代码，并且 —— 经你批准后 —— 创建现成的目录、分组和集合。

API 密钥配置

侧栏设置菜单中的 「AI Helper」 项打开配置 modal：

• 三个提供商的 API 密钥：OpenAI、Anthropic 和 Gemini（Google）。只需一个提供商的密钥即可使用助手。
• 默认提供商和默认模型 —— 打开聊天窗口时使用（模型也可以自动获取 —— 此时选择最高的可用模型）。
• 每个密钥旁都有一个 「同步」 复选框（默认关闭）。

聊天窗口

AI Helper 窗口是浮动窗口（每个标签页，像 TEMP 窗口 —— 可拖动、用 8 个句柄缩放、带关闭叉号、一个实例）。你打开 / 关闭它：

• 用快捷键 Ctrl+Alt+\，
• 用 popup 小部件中的 「AI Helper」 切换器，
• 从 Chrome context menu → JustZix → AI Helper。

窗口中：提供商选择（当你有多于一个密钥时）和模型（实时获取的列表）、对话历史、清除对话按钮以及文本字段（用按钮或 Ctrl+Enter 发送）。模型自动获得当前页面的上下文 —— URL、标题和 HTML 片段。

Agent 工作流

AI Helper 按既定工作流引导对话：

1. 询问细节 —— URL 范围、folder/分组/集合名称、颜色、确切目标。
2. 在编写代码前用工具 query_page 检查页面（selector、DOM 结构）。
3. 将准备好的 CSS/JS 代码插入临时 TEMP 窗口，你在页面上实时看到。
4. 自行验证错误 —— 用工具 read_temp_pane 和 read_console 检查被测代码是否报错，然后再向你展示结果。
5. 请你检查效果并直接询问测试是否成功。
6. 测试不成功时 —— 修正代码并重新测试。
7. 仅在你确认后固化方案：创建目录 → 分组 → 集合，如有需要还会创建操作栏和操作。每次创建实体都需要在扩展中单独确认。

模型通过简单的文本协议（块 @@JZ_TOOL@@ … @@END@@）使用工具，对 OpenAI、Anthropic 和 Gemini 的工作方式相同。工具调用及其结果在窗口中显示为单独的「chip」。可用工具：

AI Helper 窗口外观

在 AI Helper 窗口的标题栏上右键点击会打开一个菜单，其中有「上移一层」 / 「下移一层」选项（在 JustZix 窗口重叠时更改顺序），「断开与：X」（当 AI Helper 与另一个窗口连接时）以及「外观…」。「外观…」面板可分别对对话中的四个角色设置样式：你的消息、AI 回复、工具结果、内嵌表单 —— 每个都有自己的字体、大小、文字颜色和背景。值按设备保存。

与其他窗口的吸附和顺序（Z-order）

AI Helper 窗口参与与操作栏、持久窗口（CSS / JS / Console / Output）和 TEMP 窗口相同的吸附机制。将边缘拖到另一个 JustZix 窗口附近（12 px 阈值）→ 磁性吸引，红色边缘在两个窗口上指示吸附侧。连接的窗口作为一组移动。

当窗口重叠时，每个窗口的上下文菜单中的「上移一层」 / 「下移一层」选项（在标题栏右键）会进行一次性跳转 —— 窗口移到所有重叠邻居之上 / 之下，不需要多次点击。

页面截图（用于视觉模型）

screenshot_page 工具捕获当前页面视图并作为图像发送给模型。整个 JustZix 界面在捕获之前自动隐藏（FAB、操作栏、AI Helper、持久面板、TEMP）。最近 3 个截图的缓冲区，一次性附加到下一个请求（发送后从缓冲区中删除，以节省 token）。需要支持视觉的模型（例如 gpt-4o、claude-3+/4、gemini-1.5+/2）。在聊天结果芯片下方显示缩略图 —— 点击打开全屏视图。

键盘快捷键

全局（从页面任意位置生效）

窗口内部（当它有焦点时）

代码编辑器（编辑面板）

导出与导入

扩展提供五种导出格式（完整、部分、目录、分组、集合），导入时自动检测文件类型，以避免意外覆盖。

导出 —— 完整或选定的元素

在侧栏设置菜单中： 导出设置。modal 打开两种模式：

• 全部 —— 导出所有目录、分组、集合和全局设置（浮动按钮、隐藏面板等）
• 选定 —— 显示带复选框的 folder → 分组 → 集合 树：
  • 目录 / 分组的复选框选中其下方所有元素
  • indeterminate 状态（横线）显示每个级别的部分选择
  • 全选 / 全不选按钮便于快速操作
  • 底部的实时摘要显示将导出什么

部分导出文件的名称为 justzix-partial-DATA.json（vs. 完整导出的 justzix-backup-DATA.json），内部带标志 partial: true 和字段 groups[]。

单个目录导出（带选择）

在目录栏中： 导出 —— 打开带分组和集合树的 modal（类似部分导出，但限制到此目录）。仅导出选定的集合以及它们所属的分组 —— 空分组不进入文件。

格式 justzix-folder —— 文件包含带目录分组和集合层级的字段 groups[]。

分组导出

在分组栏中： 导出 —— 带分组集合列表（复选框）的 modal。文件：justzix-grupa-<名称>-<日期>.json，格式 justzix-group。

单个集合导出

在集合视图中： 导出集合 —— 立即下载文件（无 modal）。格式 justzix-rule，名称：justzix-zestaw-<名称>-<日期>.json。

导入 —— 自动类型检测（完整导入 modal）

加载文件/粘贴 JSON 后，扩展自动识别类型并显示彩色检测面板：

部分导入模式（紫色面板）

• 与现有内容合并（默认）—— 按 ID 匹配目录，添加新的；现有设置中的其余目录保持不动。
  ID 冲突时出现带 3 个选项的 prompt：
  • 1 / nadpisz —— 覆盖现有目录（会删除其分组和集合）
  • 2 / kopia（默认）—— 作为带新 ID 的副本导入，folder 名称中带 "(import)"，不丢失现有数据
  • 取消 —— 中止导入
• 替换现有内容 —— 清除所有内容并仅插入文件中选定的元素。

单个目录导入

在目录栏中： 导入。按 ID 和名称检查冲突：

• 作为新内容导入 —— 名称中带 "(import)" 后缀
• 覆盖 —— 删除目录的旧分组和集合并插入新的
• 合并 —— 向现有目录添加新分组 / 集合（保留两者）

分组导入

在分组栏中： 导入 —— 接受 3 种格式：

• justzix-group —— 插入文件中分组的所有集合
• justzix-folder —— 插入 folder 所有分组的所有集合
• justzix-rule —— 插入一个集合

文件中的所有集合以新 ID 进入当前分组（操作始终为「添加副本」类型 —— 无冲突）。

单个集合导入

在集合视图中： 导入集合 —— 仅接受 justzix-rule。带 3 个选项的 prompt：

• 1 / zastap —— 替换当前集合的内容（id 和 groupId 保留）
• 2 / kopia（默认）—— 作为新集合添加到当前集合旁，在同一分组中，带 "(import)" 后缀
• 取消 —— 中止

部分导出的实用应用

• 与团队共享 —— 导出 2-3 个带项目配置的目录，同事以「合并」模式导入它们而不丢失自己的设置
• 仅备份重要配置 —— 如保留生产环境，跳过实验
• 部分迁移 —— 在设备间仅转移一个集合
• 版本管理 —— 将特定目录连同项目文档一起导出到 git

云同步

设置 → 云同步会打开同步账户 modal。扩展将你的库（目录、分组、集合、操作、操作栏、前端窗口）保存在 justzix.com 云中，并在各设备间保持一致。同步仅在登录后工作 —— 没有账户时扩展只在本地工作。

账户与同步密钥

• 注册 —— 扩展生成一个同步密钥（账户的唯一 secret）。请妥善保存 —— 这是在另一台设备上登录的唯一方式。
• 登录 —— 你粘贴同步密钥以及可选的设备标签（如「工作笔记本」）。你可以决定密钥是保存在扩展的存储中，还是仅保留到本次会话。
• 可以为账户附加一个电子邮件（通过链接验证）—— 它用于恢复访问。

首次同步 —— 冲突解决

登录时，扩展将本地数据与云中的数据进行比较：

• 只有云中有数据 → 它被下载到本设备。
• 只有设备上有数据 → 它被发送到云。
• 两边都有数据 → 出现冲突 modal，提供三种策略：

你也可以取消 —— 扩展随即注销并不做任何更改。

持续同步

首次对账之后，同步在后台运行：扩展大约每分钟推送一次更改并拉取新实体。在一台设备上做的更改会在短时间后出现在其他设备上。「云同步」项旁边的状态点显示账户是否已连接。

状态标签页 —— 云端库、历史、操作

同步模态框的状态标签页显示账户状态并提供操作按钮：

• 立即同步 —— 立即 push 更改并 pull 新实体。
• 完整快照 —— 从账户获取库的快照。
• 刷新账户数据 —— 刷新账户信息和活动会话列表。
• 与账户完整重新同步 —— 双向：先从账户获取整个库，然后发送账户中缺失的本地实体。修复本地「卡住」的实体 —— 即那些从未到达服务器（push 被拒绝、不在首次转储中）且常规同步因其未发生变化而无法捕获的实体。非破坏性：账户中已存在的实体会被跳过（不覆盖更新的版本），在另一台设备上删除的实体不会被复活。

云端库

账户中实体的计数：目录、分组、集合、操作、操作栏、前端窗口。仅统计树中可达的实体（分组必须有存在的目录，集合必须有分组，栏/窗口必须有存在的父级）—— 与仪表板的计数保持一致。在打开面板时以及手动同步后刷新。

同步历史

设备本地的最近同步日志。页面上可见最近 10 条记录；「查看完整历史」按钮会打开一个包含完整列表的窗口（最多 100 条记录）。每条记录包含：

• 时间和发起设备 —— 会话的名称和数字 ID（与「活动会话」中相同）；
• 数字摘要 —— ↑ 已发送、↓ 已接收、✕ 已删除；
• 具体更改 —— 按类型分组并带计数（例如「操作 ×10」），在已知时附带元素名称；
• 同步后库的数量状态（六个计数器）。

该日志是本地的 —— 不在设备之间同步。每次实际改变了某些内容的同步 tick 后都会创建一条记录；手动「立即同步」始终会留下一条记录，即使更改为零。

哪些会同步，哪些不会

• 会同步：目录、分组、集合、操作、操作栏、前端窗口（CSS/JS 窗口、控制台）、主题（浅色/深色）和界面语言，以及 AI Helper 的 API 密钥 —— 但仅限那些在密钥旁勾选了「同步」复选框的（见 AI Helper）。
• 不同步（每设备状态）：浮动窗口和栏的位置、窗口尺寸、SELECT/INPUT 的值 memory、TEMP 窗口、未勾选复选框的 API 密钥。

使用统计（CSS 应用、JS 执行、窗口显示）作为每设备的独立实体进行同步 —— 仪表板的卡片会将其汇总自所有已配对的设备。主题和语言作为账户的共享设置进行同步，并在另一台设备上下次打开面板时应用。

通过链接共享（Shares）

将 JSON 文件发到即时通讯工具的替代方案。你发布一个带生存时间（1h / 6h / 12h / 24h / 48h）的公开链接并交给接收者。justzix.com 后端将 payload 保存在云中直到过期，之后被删除。

需要登录的同步账户（Sync）。token 本身是公开 secret —— 任何有链接的人都能下载，因此如果内容敏感，不要在公开渠道发送。

token 格式

JZS-XXXX-XXXX-XXXX-XXXX（16 个 Crockford base32 字符，~80 位熵）。也接受整个 URL https://www.justzix.com/s/JZS-... —— 扩展会解析并归一化（易混淆的字母 I/L→1、O→0、U→V）。

账户限制

• 每个账户最多 20 个活动链接
• 合计最多 50 MB
• 单个 share 最多 5 MB
• 每小时最多 30 个新链接

超出限制 = 带波兰语消息的错误。在 我的 share 面板中撤销未使用的链接。

创建链接（发送方）

「共享 URL」按钮在四个入口，紧挨「下载文件」：

• 完整导出 —— 设置 → 导出设置 →「共享 URL」按钮（类型 justzix-full）
• 目录 —— 目录栏 → 导出 →「共享 URL」（类型 justzix-folder）
• 分组 —— 分组栏 → 导出 →「共享 URL」（类型 justzix-group）
• 集合 —— 集合视图中的工具栏 →「共享 URL」（在导出 / 导入旁，类型 justzix-rule）

点击打开链接生成 modal：subject + 共享内容的 summary、带 TTL 的 radio（默认 24h）、「生成链接」。成功后 modal 切换到结果视图，带两个可复制的值：

• 完整 URL https://www.justzix.com/s/JZS-... —— 发给没有扩展的人（会显示 landing 页面）
• 纯 token JZS-XXXX-XXXX-XXXX-XXXX —— 在接收者扩展的「从 URL 导入」中粘贴

每个都有自己的「复制」按钮。也显示本地时区的过期时间。

「我的 share」面板

设置 → 我的 share（单独的 modal，不是同步的一部分 —— 这是两个不同的功能）。显示活动链接列表：标题中的计数器 X/20 个活动 · Y MB / 50 MB，以及每个 share 的卡片，带：

• 类型（完整导出 / 目录 / 分组 / 集合）和 ID
• 过期时间（「Xh Ymin 后过期」）以及下载计数器
• 等宽字体的 token（点击 = 选中全部）
• Summary X 个目录 · Y 个分组 · Z 个集合 · N 行 JS · A KB
• 按钮 复制链接 / 复制 token / 撤销

撤销不会撤回已下载的内容。如果有人已经下载了 payload，它在本地存于他那里。Share 是「尽力而为的时间限制」，不是 DRM。

从链接导入（接收方）

设置 → 从 URL 导入（在「导入设置」和「云同步」之间， 链条图标）。modal 有两个步骤：

步骤 1 —— 输入。你粘贴链接或纯 token。客户端校验：从 URL 提取 token，归一化为 Crockford-base32，检查 16 个字符 + 格式。格式错误 → 带正确格式提示的消息。

步骤 2 —— 预览。扩展显示 share 的摘要：

• 发送方（display name 或「匿名」如果未设置）
• 过期时间（相对时间）
• 类型（完整导出 / 目录 / 分组 / 集合）
• payload 大小
• 内容（目录 / 分组 / 集合 / 操作的数量）
• CSS 字符数 / JS 行数
• 下载次数

如果 share 包含 JavaScript（jsLines > 0）—— 会出现带链接 「显示 JavaScript 代码」 的红色警告横幅。它打开一个带每条规则和操作完整 JS 代码的 overlay —— 在导入之前查看它，因为代码会在匹配的页面上执行。

步骤 3 —— 导入。点击「导入」→ 后端返回完整 payload → 扩展以始终全新的 ID 创建新实体（绝不按 ID 覆盖现有的）：

新容器的名称：<发送方名称或 "Import"> <波兰语日期> —— 你之后可以任意重命名 / 移动。

接收方错误

后端不区分 404「从未存在」和 404「已过期 / 已撤销」—— 这是有意的，以免泄露 token 是否曾经存在。

从 JS 编程式调用操作

每个操作（来自集合卡片中的「操作」标签页）都可以从集合的 JS 或另一个操作的代码中编程式调用。全局命名空间 window.JZ 在每次执行用户 JS 前自动安装到 MAIN world。

API —— 操作

示例 —— 读取和设置值

// === 读取 ===
const filter = JZ.value('FILT');           // INPUT/TEXTAREA — string
const opacity = JZ.value('OPAC');          // SLIDER — string numeric ("75")
const mode = JZ.value('MODE');             // SELECT static — string (option.value)
const theme = JZ.value('THM');             // TOGGLE3 — 活动状态的 state.value

// === 设置 ===
JZ.setValue('FILT', 'nowa wartość');       // INPUT/TEXTAREA — string + dispatch input+change
JZ.setValue('OPAC', 75);                   // SLIDER — clamp 到 min/max，dispatch input+change
JZ.setValue('SRT', 'prod');                // SELECT(js) — 原生 select + dispatch change
JZ.setValue('MODE', 'staging');            // SELECT static — content.js 执行流程（memory + UI + 代码）
JZ.setValue('THM', 'dark');                // TOGGLE3 — 按 state.value 查找（fallback 到 label，再到 idx）
JZ.setValue('THM', 2);                     // TOGGLE3 — 等价；数字 idx 也有效

API —— 栏和浮动按钮

操作代码中的上下文变量

在操作的「JS 代码」字段中你自动可用一些变量 —— 由 background service worker 在执行前作为 const 注入：

UI 中的代码片段

在 SELECT 和 INPUT 类型操作的配置 modal 中，「稳定的操作 ID」面板显示完整的 action.id，带复制按钮以及示例 JS selector（document.querySelector('[data-jz-action-id="..."]')）。在 BUTTON 列表下方可见 JZ.click('LBL') chip —— 点击 chip 将代码片段复制到剪贴板。

要求

• 操作元素必须在当前页面上的操作栏中可见（操作有 visible: true，栏在树中可见 + 页面 URL 匹配规则）。
• 操作不可见或栏在该页面上隐藏 → JZ.click() 返回 false，JZ.action() 返回 null。
• 操作上定义的键盘快捷键有自己的机制（content.js 中的 capture-phase keydown 监听器）—— 不需要 JZ.click()。

示例 —— 调用序列的 AUTO 操作

// "AUTO" 操作的代码
JZ.click('LOAD');                          // 点击 LOAD 操作（如加载数据）
setTimeout(() => JZ.click('PROC'), 500);   // 500ms 后 PROC（处理）
setTimeout(() => JZ.click('SAVE'), 1500);  // 1500ms 后 SAVE（保存）

示例 —— 响应 DOM 的集合 JS

动态元素出现后点击删除它的操作：

// 集合 JS 代码 — 对动态出现的 modal 的 observer
const observer = new MutationObserver(() => {
  if (document.querySelector('.cookie-banner')) {
    JZ.click('CCK');  // 点击删除横幅的操作
    observer.disconnect();
  }
});
observer.observe(document.body, { childList: true, subtree: true });

示例 —— 编程式设置 INPUT 值

// JZ.click 在 INPUT 上不改变值 — 使用带 dispatch 'change' 的模式：
const el = JZ.action('SRCH');           // 或 JZ.actionById('a_mp1deeq3_uimd8l')
if (el) {
  el.value = 'nowy filtr';
  el.dispatchEvent(new Event('change'));
}

通过 DOM 直接访问

如果你更喜欢直接处理 DOM（如改变样式而非调用）：

// 按稳定 ID 查找（推荐 — 对 label 更改有抵抗力）：
const el = document.querySelector('[data-jz-action-id="a_mp1deeq3_uimd8l"]');

// 按 label 查找（大小写不敏感 — data-jz-key 中为大写）：
const btn = document.querySelector('[data-jz-key="MYBT"]');
btn.style.opacity = '0.5';      // 调暗
btn.dataset.busy = 'true';      // 自有属性

操作元素在 DOM 中的位置：

所有元素都有属性 data-jz-action-id（唯一的稳定标识符）。Selector .jz-actions-bar 是安全的 —— 不与页面 DOM 冲突。

精选功能

侧栏搜索

「搜索」字段过滤目录树。匹配逻辑：

• 按目录名称或 URL 匹配 → 整个目录连同所有集合保持可见并自动展开
• 按集合名称、标签或 CSS/JS 内容匹配 → 仅显示目录中匹配的集合，目录自动展开
• 无结果 → 消息「无 [查询] 的结果」

匹配不区分大小写，黄色高亮显示匹配位置。

全局开关

点击 Chrome 工具栏中的扩展图标后会出现带大型绿/灰切换器「Plugin enabled」的 popup 小部件。在禁用模式下，任何页面上都不注入任何 CSS/JS，与目录设置无关。此时浮动按钮被禁用（Halt Red，opacity 0.7）。状态在 Chrome 重启后存活。

从标签页插入 URL

URL 模式字段旁的按钮 —— 从活动标签页插入 protocol://host/*。2 秒创建目录。扩展选项页面的地址被跳过 —— 取最新的外部标签页。

实时 URL 校验

URL 字段右侧内联出现信息「匹配 X 个打开的标签页」或警告。立即捕获拼写错误。

集合更改历史

CSS 和 JS 的快照在最后一次编辑后 3 秒创建（debounce）。限制 5 个版本 —— 最旧的被挤出。恢复版本时，当前内容作为最新快照添加到历史中，因此你总能撤销撤销。

标签和按标签搜索

集合卡片标题中有一个标签字段 —— 用逗号分隔输入。它们作为侧栏中集合名称旁的小标签出现。搜索也能按标签找到。

目录标签和颜色

每个目录可以在浮动按钮上有自己的标签（最多 3 个字母，大写）和颜色（color picker）。标签和颜色帮助视觉识别哪个项目在给定页面上激活。

操作点击统计

每个操作按钮都计数它被点击了多少次。帮助看到哪些真正被使用。

CSS 校验

CSS 编辑器下方显示带语法问题列表的栏：

• 未闭合的注释 /* ... */
• 未闭合的大括号（缺少 }）
• 多余的闭合大括号 }（带行号）

这是简单的语法校验 —— 不检查 properties/values 的正确性。带错误的 CSS 仍会注入（浏览器只是跳过错误的规则）。

导入时的 JS 预览

在单个目录导入 modal 中，加载文件后出现带度量的集合列表：

文件内容（3 个集合）：
  Auto-login              CSS: 0L • JS: 4L                    JS
  Ukryj banner cookie     CSS: 8L • JS: 0L
  Debug GTM               CSS: 0L • JS: 12L • 2 akcji (8L)    JS

如果存在任何 JS 行，会有带行数的警告。点击 JS 按钮显示完整代码以便导入前查看。

Try/catch JS 隔离

每个 JS 集合都单独以自己的 try/catch 执行。一个集合中的错误不会阻塞其他集合的执行。错误以集合/操作名称和完整 stack trace 记录到控制台。

Storage quota

侧栏设置菜单中的内存使用指示器（如 1.2 MB / 10 MB）。超过 80% 为红色。

「仅激活」过滤器

列表上方的复选框 —— 隐藏标记为独立（○）的集合，只显示目录中激活的（●）。当目录有很多集合时帮助筛掉「手动」集合。对开关更改立即响应。

扩展更新

扩展在 manifest 中有固定的 key（Firefox 构建 —— 固定的 gecko.id），这意味着扩展的 ID 在更新间不变 —— 数据（目录、集合、设置）得以保留。JustZix 面向四种浏览器发布：Chrome、Edge、Opera 和 Firefox。

新版本通知

当服务器发布了比已安装版本更新的包时，设置菜单中（版本号旁边）会出现一条绿色的「有新版本可用」横幅。横幅包含一个下载链接。该检查是静默的 —— 没有网络时横幅就不显示。

更新步骤（Chrome / Edge / Opera）

1. 下载带更新的新 ZIP
2. 解压时覆盖之前版本所在的同一文件夹
3. 在 chrome://extensions/（Edge：edge://extensions/）中找到扩展并点击卡片上的刷新图标
4. 扩展用新文件重新加载，数据保留

Firefox

Firefox 构建通过 about:debugging → 「此 Firefox」 → 「临时载入附加组件」加载（指向 justzix_firefox/ 文件夹中的 manifest.json）。更新 = 覆盖文件后重新载入。

CSS 示例

/* Ukryj typowe reklamy */
.ad, .ads, .advertisement,
.banner-ad, [class*="ad-banner"],
[id*="google_ads"] {
  display: none !important;
}

/* Ukryj cookie banner */
.cookie-banner, #cookie-notice {
  display: none !important;
}

html {
  filter: invert(0.92) hue-rotate(180deg);
}
img, video, picture, iframe, [style*="background-image"] {
  filter: invert(1) hue-rotate(180deg);
}

/* Pokoloruj wszystkie elementy z data-testid */
[data-testid] {
  outline: 2px dashed #f59e0b !important;
  outline-offset: -2px;
}
[data-testid]::before {
  content: attr(data-testid);
  position: absolute;
  background: #f59e0b;
  color: white;
  font-size: 10px;
  padding: 2px 4px;
  z-index: 9999;
}

/* Zwiększ czytelność tabel admina */
table.admin-list td, table.admin-list th {
  padding: 8px 12px !important;
  font-size: 14px !important;
}

/* Sticky header tabeli */
table.admin-list thead {
  position: sticky;
  top: 0;
  background: white;
  z-index: 10;
}

/* Naprzemienne wiersze */
table.admin-list tbody tr:nth-child(odd) {
  background: #f9fafb;
}

/* Często strony mają sztywne max-width 1200px - wymuś szerokość */
.container, .main-content, main {
  max-width: 95% !important;
  width: 95% !important;
}

body::before {
  content: "ŚRODOWISKO DEV";
  position: fixed;
  top: 0;
  left: 0;
  right: 0;
  background: #dc2626;
  color: white;
  text-align: center;
  padding: 4px;
  font-weight: bold;
  z-index: 999999;
  font-family: 'Roboto Mono', ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
}
body { padding-top: 28px !important; }

JavaScript 示例

// Tylko dla dev! Nigdy nie zapisuj prawdziwych haseł
window.addEventListener('load', () => {
  const login = document.querySelector('input[name="login"]');
  const pass = document.querySelector('input[name="password"]');
  if (login) login.value = 'admin@dev.local';
  if (pass) pass.value = 'devpass123';
});

// Przechwyć dataLayer.push (GTM)
const origPush = window.dataLayer?.push;
if (origPush) {
  window.dataLayer.push = function(...args) {
    console.log('%c[GTM]', 'color:#16a34a;font-weight:bold', args);
    return origPush.apply(window.dataLayer, args);
  };
}

// Przechwyć gtag
const origGtag = window.gtag;
if (origGtag) {
  window.gtag = function(...args) {
    console.log('%c[GA4]', 'color:#2563eb;font-weight:bold', args);
    return origGtag.apply(window, args);
  };
}

// Co 500ms przez 10s sprawdzaj i klikaj przyciski "Akceptuj"
let attempts = 0;
const interval = setInterval(() => {
  if (++attempts > 20) return clearInterval(interval);

  const buttons = [...document.querySelectorAll('button, a')];
  const target = buttons.find(b =>
    /akceptuj|zgoda|accept all/i.test(b.textContent || '')
  );
  if (target) {
    target.click();
    clearInterval(interval);
  }
}, 500);

document.addEventListener('keydown', (e) => {
  // Ctrl+Shift+S - zapisz formularz
  if (e.ctrlKey && e.shiftKey && e.key === 'S') {
    e.preventDefault();
    document.querySelector('button[type="submit"]')?.click();
  }
  // Ctrl+Shift+E - przejdź do edycji (nieprzetestowany przykład)
  if (e.ctrlKey && e.shiftKey && e.key === 'E') {
    e.preventDefault();
    document.querySelector('a.edit-link')?.click();
  }
});

// Pomijaj denerwujące confirm i beforeunload na czas testów
window.confirm = () => true;
window.alert = (msg) => console.log('[stłumiony alert]', msg);
window.onbeforeunload = null;
window.addEventListener('beforeunload', e => {
  e.stopImmediatePropagation();
}, true);

// Pamiętaj - czysty CSS tego nie zrobi gdy rodzic ma display:none
window.addEventListener('load', () => {
  const target = document.querySelector('.important-info');
  const newParent = document.querySelector('.sidebar');
  if (target && newParent) {
    newParent.prepend(target);
  }
});

// Pokaż wszystkie ukryte input type="hidden"
document.querySelectorAll('input[type="hidden"]').forEach(input => {
  const wrapper = document.createElement('div');
  wrapper.style.cssText = 'background:#fef3c7;padding:4px;font-size:11px;font-family:monospace;border:1px dashed #f59e0b;';
  wrapper.innerHTML = `${input.name}: ${input.value}`;
  input.parentNode.insertBefore(wrapper, input);
});

操作按钮示例

document.querySelectorAll('input, textarea, select').forEach(el => {
  if (el.type === 'hidden') return;
  if (el.type === 'checkbox' || el.type === 'radio') {
    el.checked = false;
  } else {
    el.value = '';
  }
  el.dispatchEvent(new Event('change', { bubbles: true }));
});

const data = {
  email: 'test@example.com',
  phone: '600000000',
  firstName: 'Jan',
  lastName: 'Testowy',
  street: 'Testowa 1',
  city: 'Warszawa',
  zip: '00-001'
};
Object.keys(data).forEach(name => {
  const el = document.querySelector(`[name="${name}"]`);
  if (el) {
    el.value = data[name];
    el.dispatchEvent(new Event('input', { bubbles: true }));
    el.dispatchEvent(new Event('change', { bubbles: true }));
  }
});

// Dla typowego sklepu — kliknij pierwszy "dodaj do koszyka"
const btn = document.querySelector('.add-to-cart, [data-action="add-to-cart"]');
if (btn) btn.click();
else alert('Nie znaleziono przycisku dodaj do koszyka');

navigator.clipboard.writeText(location.href).then(() => {
  console.log('Skopiowano:', location.href);
});

// Wyciąga token JWT z localStorage / cookies dla debugowania
const token = localStorage.getItem('authToken')
  || document.cookie.match(/token=([^;]+)/)?.[1];
if (token) {
  navigator.clipboard.writeText(token);
  alert('Token skopiowany. Pierwsze znaki: ' + token.slice(0, 20) + '...');
} else {
  alert('Brak tokena');
}

// Przechwytuj wszystkie fetch i pokaż w konsoli
const origFetch = window.fetch;
window.fetch = async function(...args) {
  console.log('%c[FETCH]', 'color:#2563eb', args[0]);
  const res = await origFetch.apply(this, args);
  return res;
};
console.log('Włączono logowanie fetch. Każde wywołanie pojawi się w konsoli.');

const info = {
  url: location.href,
  userAgent: navigator.userAgent.split(' ').pop(),
  cookies: document.cookie.split(';').length,
  localStorage: Object.keys(localStorage).length,
  framework: window.React ? 'React' : window.Vue ? 'Vue' : window.jQuery ? 'jQuery' : 'unknown'
};
alert(JSON.stringify(info, null, 2));

使用场景

1. 与多个客户 / 项目协作

每个项目有自己的目录，带自己的 URL 模式。你可以有目录：

• justzix.com —— 生产环境的修改
• justzix dev —— 用于 https://dev.justzix.com/*，带红色「DEV」横幅
• 客户 X —— 另一个域名上的修改

在右侧面板上可以快速启用/禁用各个目录。单个目录导出让你能与团队共享配置。

2. 带视觉标记的开发环境

在每个 dev/staging 上添加横幅和自动登录。一个 CSS 集合（横幅）和一个 JS（自动填充）。你为每个环境创建单独的目录，用简单的复选框集中起来。

3. 为 product manager / QA 的工具

带按钮的操作面板：FILL（测试数据）、CART（测试购买）、CLR（清空表单）、STATE（在 alert 中显示应用状态）。无需程序员、无需控制台，一键完成。

4. 修改公开网站

提升喜爱的博客/文档的可读性 —— 更大的容器、字体、深色模式。每个网站在单独的目录中，「激活」永久保持开启。

5. 调试分析 / GTM

每个域名一个带捕获 dataLayer.push 和 gtag 的 JS 集合。当客户报告分析问题时启用它，无需触碰页面代码。

6. 在管理面板上工作

模式 *://*.justzix.com/admin/* 和改进表格、列表、表单的 CSS。加上「测试过滤器」操作，为典型工作流自动设置过滤器。

7. 在生产环境上安全测试

RO（read-only）操作注入隐藏所有「删除」「保存」「发送」按钮的 CSS —— 临时的「只读模式」以免出错。

// Ukryj groźne przyciski
document.querySelectorAll(
  'button[type="submit"], .delete-btn, .danger-btn, [class*="delete"]'
).forEach(b => b.style.display = 'none');
console.warn('TRYB READ-ONLY włączony');

常见问题与解决方案

JavaScript 没有执行

• 检查页面是否匹配模式 —— 浮动按钮应该可见
• JS 在页面生命周期中执行一次 —— 你更改了代码？重新加载页面（F5）
• 检查 DevTools 控制台 —— JS 错误在那里记录为 [JustZix] JS error
• 集合必须被启用 —— 仅「激活」不够

CSS 不工作

• 特异性 —— 页面有自己的样式；使用 !important 或更具特异性的 selector
• 动态类 —— 某些框架生成会变化的 .css-1abcd 类型的类。使用属性（[data-testid]）或稳定的 selector
• Shadow DOM —— 某些元素在 Shadow DOM 中，外部的 CSS 无法访问它们。需要 JS

浮动按钮不出现

• URL 不匹配任何模式
• 按钮此前被隐藏 —— 在 popup 小部件中点击 恢复浮动按钮
• 页面阻止了注入的脚本（罕见）

扩展更新后我丢失了数据

扩展在 manifest 中有固定的 key —— 后续更新保留数据。如果数据仍然消失了：

• 定期导出设置（导出）
• 更新时覆盖同一文件夹 —— 不要更改路径
• 在 chrome://extensions/ 中使用刷新按钮，不要删除并重新安装
• 如果丢失数据，导入之前的导出 —— 只需 1-2 次点击

按钮/面板的位置重置

这是正常的 —— 位置是按浏览器窗口的，存储在会话内存中（chrome.storage.session）。关闭窗口后位置消失，在新窗口中你从默认值开始。位置在同一窗口内标签页间的导航中存活。

部分导出跳过了某些全局设置

是的 —— 部分导出仅包含选定的目录和集合加上与它们相关的可见性设置。它不包含浮动面板的位置（它们是按窗口的）或其他全局偏好。要完整备份请使用 「全部」 模式。

部分导入覆盖了我之前不存在的目录

「合并」模式按 ID 匹配目录。如果导入的文件有与现有目录冲突的 ID（如同一文件已被导入过一次），会出现 prompt：1 覆盖 / 2 副本（默认，安全）/ 取消。选择 2 你会得到带新 ID 和 folder 名称中 "(import)" 后缀的副本 —— 你不会丢失任何东西。

目录树不展开

展开箭头仅在目录有集合时出现。空目录有一个变灰的圆点而非箭头。每个目录的展开状态记在 chrome.storage.local 中。

我看不到目录的导出/导入按钮

这些按钮在目录栏中（编辑区域顶部），紧挨「删除目录」按钮。不要与设置菜单中涉及整个设置的按钮混淆。

AI Helper 不响应

• 无 API 密钥 —— 在设置 → AI Helper 中输入至少一个提供商的密钥（OpenAI / Anthropic / Gemini）。
• 密钥无效 —— 窗口会显示提供商返回的错误；检查密钥和提供商处的账户限制。
• 密钥未同步到第二台设备 —— 同步仅对勾选了「同步」复选框的密钥有效，并需要登录的 JustZix 同步账户。

与 Content Security Policy 冲突

规则和操作的 JS 在页面上下文中通过分层策略执行，可抵御严格的 Content Security Policy 规则。大多数页面——包括 Facebook 等大型站点——无需任何配置即可立即工作。

CSP 极严格的页面（某些银行、企业站点）可能会阻止执行。要让 JS 在每个页面上都能工作，请为 JustZix 启用"允许用户脚本"选项：打开 chrome://extensions，进入 JustZix 详情并打开该开关（较旧的浏览器还需要开发者模式）。当页面阻止执行时，JavaScript 窗口 / JS 控制台会显示相应的提示。

JustZix — 使用手册