Skip to content

refactor: 统一品牌为 Nolook，并按扩展上下文重组项目结构 #3

New issue
New issue
Open
Open
refactor: 统一品牌为 Nolook，并按扩展上下文重组项目结构#3
@ooooo-create

Description

@ooooo-create
ooooo-create
opened on Mar 27, 2026

背景

当前项目在命名和结构上都有明显的历史混用问题，已经开始影响后续迭代效率。

1. 品牌命名混乱

仓库当前同时出现了 Nolo / Nolook / nolo：

  • manifest.json 的 name / action.default_title 还是 Nolo
  • manifest.json 的 description 又写成了 Nolook: Use URL filter syntax to block webs for nolook
  • README.md 标题是 Nolo (Nolook)
  • package.json 的包名还是 nolo
  • 代码内部还存在 globalThis.NoloRuleUtils、[Nolo] 日志前缀等耦合命名

这会带来两个问题：

  • 用户侧品牌识别不稳定
  • 开发侧内部符号和产品命名绑得过紧，后续再改名成本高

2. 项目结构已经开始不适合继续扩展

当前仓库几乎所有运行时文件都平铺在根目录：

  • background
  • popup
  • blocked page
  • shared utils
  • tests
  • icons

这在功能少的时候还能接受，但后续准备继续做：

  • allow 例外规则
  • 更完整的规则管理界面
  • 更清晰的设置能力
  • 可能的 options page / 高级规则能力

继续保持根目录平铺，会让职责边界越来越模糊。

这件事要解决什么

本 issue 的目标不是“单纯改个名字”，而是做一次面向后续功能演进的基础治理：

官方技术调研结论

1. 官方对命名字段有明确约束

Chrome 官方 manifest 文档说明：

  • name 是扩展的主标识文本，最大 75 个字符
  • description 是纯文本，最大 132 个字符，且应同时适合 chrome://extensions 和 Chrome Web Store
  • short_name 是可选字段，官方建议最长 12 个字符，用于空间不足时显示

这意味着当前这种 Nolo / Nolook 混用，以及不自然的 description，确实应该尽快统一和修正。

2. 官方没有规定唯一的目录树，但明确规定了“上下文角色”

Chrome 官方并没有强制要求扩展必须采用某一种固定目录结构；它强调的是：

  • manifest.json 必须位于扩展根目录
  • 扩展由多个“承担不同角色”的部分组成
  • 这些部分包括 manifest、service worker、popup、content scripts、extension pages 等

换句话说，官方关注的是“按运行上下文清晰分工”，而不是“必须叫 src / app / lib 中的哪一个”。

因此，对这个项目来说，更合理的组织方式不是继续平铺，而是按上下文拆分：

  • background
  • popup
  • blocked
  • options
  • shared/core
  • assets
  • tests

3. Popup 不是长期承载复杂设置的理想位置

Chrome 官方 popup 文档明确指出：

  • popup 会在用户点击到外部区域后自动关闭
  • 没有办法在用户点击离开后继续保持 popup 打开
  • popup 的 JavaScript 也应放在单独文件中

这说明：

  • popup 适合做“快速操作”
  • 不适合承载越来越复杂的完整设置界面

随着 Nolo... 不，应该说 Nolook 后续会继续增加规则能力，完整规则管理更适合迁到 options page，而 popup 保持轻量。

4. Options page 才是官方定义的“扩展设置入口”

Chrome 官方 options page 文档明确表示：

  • options page 用来让用户启用功能、选择和调整扩展能力
  • 可以声明为 options_page 或 options_ui
  • 页面路径相对于扩展根目录声明
  • popup 内还可以通过 chrome.runtime.openOptionsPage() 跳转过去

这非常适合 Nolook 的未来方向：

  • popup 负责快速开关和快捷入口
  • options page 负责规则列表、规则类型、未来的 allow 例外规则、高级说明等

5. Background Service Worker 支持模块化组织

Chrome 官方 service worker 文档说明：

  • background 通过 manifest 的 background.service_worker 注册
  • 既可以继续用 importScripts()
  • 也可以把 service worker 声明为 type: "module"，使用标准 import

这意味着当前项目如果要做结构治理，完全可以顺手把背景脚本和共享逻辑切到更清晰的模块化结构，减少 globalThis.NoloRuleUtils 这类全局耦合。

6. web_accessible_resources 应保持最小暴露面

Chrome 官方文档说明：

  • 默认情况下，扩展资源不是 web accessible
  • 只有显式声明的资源才可被网页访问
  • 导航到扩展资源也要求该资源在 web_accessible_resources 中声明

这说明在结构重组时，仍应继续坚持最小暴露面原则，不因为目录移动而扩大资源暴露范围。

7. 图标和 manifest 元数据最好一并整理到统一品牌下

Chrome 官方图标文档建议：

  • 提供 128x128、48x48 等 PNG 图标
  • action.default_icon 建议提供多尺寸

现在图标体系已经相对规范，这次治理应该把它和 Nolook 品牌命名一起统一，而不是只改文案不改 manifest 元数据。

需求定义

目标

  1. 将项目所有用户可见品牌统一为 Nolook
  2. 将项目目录按扩展上下文重新组织，降低根目录平铺度
  3. 为未来复杂规则管理预留 options 分层
  4. 降低内部代码对品牌命名的耦合度
  5. 不改变当前扩展的核心行为闭环：
    • popup 快速配置
    • background 规则同步
    • blocked page 展示拦截详情

非目标

当前项目的主要结构问题

1. 根目录职责过多

当前根目录同时包含：

  • manifest
  • 页面 HTML/CSS/JS
  • background worker
  • 图标资源
  • 共享逻辑
  • 测试文件

对于一个还会继续演进的扩展来说，这已经开始影响可读性。

2. 共享逻辑和运行时上下文混在一起

例如：

  • rule-utils.js 是纯逻辑
  • background.js 是 service worker
  • popup.js / blocked.js 是页面交互逻辑

它们本来就属于不同层次，但现在都平铺在同一层，而且共享逻辑通过全局变量暴露，维护成本偏高。

3. popup 承担的职责已经开始过重

当前 popup 已经不只是快速入口，而是主要规则管理入口。继续在 popup 里堆更多能力，会和官方建议的使用方式越来越背离。

推荐技术方案

一、先统一品牌，再做结构重组

建议统一采用：

  • 产品名：Nolook
  • manifest name: Nolook
  • manifest short_name: Nolook
  • popup / blocked / README / 文档 / 标题统一为 Nolook

同时建议把内部代码中的品牌耦合命名弱化，例如：

  • NoloRuleUtils -> 更中性的模块导出
  • [Nolo] -> [Nolook] 或更中性的日志前缀

二、目录按“扩展上下文 + 共享层”组织

推荐的无构建工具目录结构：

/
  manifest.json
  package.json
  README.md
  biome.json

  assets/
    icons/
      icon16.png
      icon24.png
      icon32.png
      icon48.png
      icon128.png
      icon.svg

  src/
    background/
      service-worker.js

    core/
      rules.js
      state.js
      messages.js
      constants.js

    pages/
      popup/
        popup.html
        popup.css
        popup.js

      blocked/
        blocked.html
        blocked.css
        blocked.js

      options/
        options.html
        options.css
        options.js

  tests/
    rule-utils.test.js

说明：

  • manifest.json 保持在根目录，符合官方要求
  • 运行时文件按上下文拆分
  • 纯逻辑沉到 core/
  • 图标资源集中到 assets/icons/
  • 测试与运行时源码分离

三、推荐把 background 与共享逻辑改为模块化

建议将 background 声明为：

"background": {
  "service_worker": "src/background/service-worker.js",
  "type": "module"
}

然后使用标准 import 组织 core/ 逻辑。

页面端也可以逐步采用模块脚本，减少：

  • 全局变量挂载
  • 品牌名绑定到全局 API 名称
  • 共享逻辑多入口维护的隐式耦合

四、重新划分 popup 与 options 的职责

推荐的职责划分：

popup

保留为轻量快速入口：

  • 全局开关
  • 快捷添加一条规则（可选）
  • 最近规则概览 / 规则数量
  • 进入完整设置页按钮

options page

承载完整配置：

  • 全量规则管理
  • 规则启停 / 删除 / 编辑
  • 未来 allow 例外规则
  • 高级说明和帮助文档

blocked page

继续保持单一职责：

  • 只负责展示本次被拦截的命中规则与原始请求信息

五、Manifest 一并规范化

建议在这次治理中同时完成：

  • name 统一为 Nolook
  • 新增 short_name
  • 重写 description，让它更适合 chrome://extensions / Chrome Web Store
  • 继续保持 action.default_icon 和 icons 的官方推荐写法
  • 目录移动后同步更新 default_popup / background.service_worker / web_accessible_resources / 图标路径

六、GitHub 仓库名称可作为后续独立动作

仓库当前叫 Nolo。如果最终也要统一到 Nolook，建议把“GitHub repo slug 改名”作为单独动作处理。

原因：

  • GitHub 虽然会保留重定向，但仍会影响 clone URL、远端配置、PR 链接心智
  • 相比之下，先把代码、文档、manifest、UI 全部统一更稳

验收标准

品牌统一

  • manifest.json、README、popup、blocked、包名、文案统一为 Nolook
  • 不再出现面向用户的 Nolo / Nolook 混用
  • 内部代码中的品牌耦合命名得到清理或收敛

结构治理

  • 根目录仅保留 manifest、配置、文档和高层入口文件
  • 背景脚本、页面脚本、共享逻辑、测试、图标分层清晰
  • manifest 路径全部更新且扩展可正常加载

职责边界

  • popup 保持轻量
  • options page 成为完整设置入口（至少完成基础落位）
  • blocked page 继续保持单一职责

验证

  • npm test 通过
  • Chrome unpacked extension 可正常加载
  • popup / blocked 页面功能不回退
  • 动态规则同步链路不回退

具体实施规划

Phase 1: 品牌与 manifest 清理

  • 统一产品名为 Nolook
  • 更新 manifest 的 name / short_name / description / default_title
  • 更新 README、UI 标题、页面标题、alt 文本、日志前缀
  • 评估并更新 package.json 名称

Phase 2: 目录重组

  • 新建 assets/、src/、tests/ 分层
  • 将 popup / blocked / background / core 文件迁移到新位置
  • 更新所有 HTML 引用路径和 manifest 路径
  • 确认 web_accessible_resources 仍保持最小暴露面

Phase 3: 模块化治理

  • 将 background service worker 切到模块模式
  • 将共享逻辑改为标准模块导出
  • 移除对 globalThis.NoloRuleUtils 的依赖
  • 梳理消息类型、常量、状态处理边界

Phase 4: popup / options 职责重构

  • 为扩展增加 options page 落位
  • popup 中增加“进入完整设置”的入口
  • 将复杂规则管理逐步迁到 options page
  • 保持 popup 的快速操作体验

Phase 5: 验证与文档

建议执行顺序

建议优先完成本 issue，再继续推进 #2。

原因：

参考资料

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions