fix: 按 Halo 应用市场审核意见整改外部资源与隐私（v1.2.5 修订）

- 默认零第三方自动请求：移除 21 个模板的 preconnect/dns-prefetch、PrismJS+autoloader、qrcode-generator 及内置一言/IP 定位 API - 一言与代码高亮配色改为自托管；欢迎弹窗自定义 IP 接口改为 opt-in；微信分享改为复制链接；LightGallery 按 GPLv3 使用 - README 新增「外部资源与隐私」「验证与回归测试」章节，修正无效链接并补充字体 OFL 来源；同步 docs 与修正虚构的目录树 - friends 等 12 处 #strings.substring 加空值保护；logo 由两份 1.5MB 压缩去重为单份 146KB - 新增 pnpm audit:external 与打包前置合规审计；制品补齐 34 个 docs 文档与预览图
2026-11-11 14:37:09 +08:00
1 parent c0ad7331d4
commit dda86294b0
@@ -2,7 +2,7 @@

 暖如灯火，静如留白。暖屿以柔和的色调和舒缓的节奏回归内容本身，为记录与阅读留出一方安静从容的角落。

-> 本项目由 AI 开发完成，人工仅进行部分功能测试及问题找寻
+> 本项目使用 AI 辅助开发。开发者已按 Halo 主题规范完成代码审查、构建产物核验、外部资源审计与主要模板的回归检查清单（见[验证与回归测试](#验证与回归测试)）；主题不加载远程脚本、不动态下载代码、不进行未披露的数据收集。

 ## 环境要求

@@ -13,14 +13,59 @@

 1. **响应式设计** — 适配桌面端与移动端，支持暗色模式，移动端使用动态视口单位适配地址栏
 2. **插件兼容性** — 适配 11 款常用 Halo 插件，安装即用；提供页面布局契约，插件前台页面自动复用主题外观
-3. **内置灯箱** — 主题内置 LightGallery 灯箱，支持 EXIF 信息展示；安装 lightgallery.js 插件后自动禁用
+3. **内置灯箱** — 主题内置 LightGallery 灯箱（GPLv3，随主题自托管打包），支持 EXIF 信息展示；安装 lightgallery.js 插件后自动禁用
 4. **可配置性** — 17 个设置分组、122 个配置项，几乎所有模块可独立开关
-5. **性能优化** — 服务端字数统计（API 扩展包）、图片懒加载与响应式缩略图、首屏整屏吸附（仅首屏边界接管，内容区保留原生滚动）、Hero 离屏停绘、CSS/HTML 压缩；详见[开发指南 - 性能与滚动顺滑](docs/customize/development.md)
-6. **页面布局契约** — 提供 `templates/layout.html`，插件页面不再回退到 Halo 内置布局
+5. **性能优化** — 服务端字数统计（API 扩展包）、图片懒加载与响应式缩略图、首屏整屏吸附（仅首屏边界接管，内容区保留原生滚动）、Hero 离屏停绘、CSS/HTML 压缩；详见[开发指南 - 性能与滚动顺滑](https://nxxy335.top/WarmIsland/customize/development.html)
+6. **零默认外部请求** — 所有脚本、样式、字体、图标、句子库、主题图标均随主题自托管，默认不向任何第三方发起自动请求；详见[外部资源与隐私](#外部资源与隐私)
+7. **页面布局契约** — 提供 `templates/layout.html`，插件页面不再回退到 Halo 内置布局

 ## 预览

-![WarmIsland Preview](./WarmIsland%20Preview.webp)
+![WarmIsland Preview](https://git.nxxy335.top/nxxy335/halo-theme-WarmIsland/raw/branch/main/WarmIsland%20Preview.webp)
+
+> 预览图同时随安装包分发（包根目录 `WarmIsland Preview.webp`），离线查看制品时也可打开。
+
+## 外部资源与隐私
+
+本章节对应 [Halo 应用市场审核指南](https://docs.halo.run/developer-guide/app-store/app-review-guidelines) 1.4 / 4.4.4 / 5.1，逐项说明服务名称、用途、数据类型、默认状态与关闭方法。
+
+### 默认行为
+
+**默认配置下，主题不会自动向任何第三方服务发起请求。** 页面加载的 CSS、JS、字体（LXGW WenKai 本地分片）、图标、主题 Logo、一言句子库全部来自站点自身的 `/themes/warm-island/assets/`，不经过 CDN，也不使用 `preconnect` / `dns-prefetch`。已移除的远程依赖见下方[自托管与许可](#自托管与许可)。
+
+### 逐项说明
+
+| 服务 / 资源 | 用途 | 涉及的数据类型 | 默认状态 | 关闭 / 替换方法 |
+| --- | --- | --- | --- | --- |
+| 主题自身静态资源 `/themes/warm-island/assets/*` | 样式、脚本、字体、图标、Logo、内置句子库 | 无（同域请求，不含用户数据） | 始终启用，渲染必需 | 不可关闭；均为随包自托管文件 |
+| 自定义一言 API `hero_hitokoto_api` | Hero 首屏随机句子 | 无请求体；发起 GET 时第三方可见访客 IP / User-Agent | **关闭**：留空，使用 `assets/data/hitokoto.json` 内置本地句子库 | 主题设置 → Hero 首屏 → 清空「自定义一言 API」 |
+| 自定义 IP 定位主 / 备选 API `welcome_popup_api` / `welcome_popup_fallback_api` | 欢迎弹窗显示「欢迎来自 XX 的朋友」 | **访客 IP** 与第三方返回的粗略地理位置 | **关闭**：两项均留空，弹窗只显示本地欢迎语；且欢迎弹窗开关本身默认关闭 | 主题设置 → 欢迎弹窗 → 关闭开关，或清空两个 API 字段 |
+| 分享按钮：QQ / 微博 / X / Facebook / Telegram | 分享文章到对应平台 | 文章 URL 与标题（写在目标站 URL 参数中） | 默认开启 `qq,wechat,weibo`；**仅在访客点击后**跳转，页面加载时不请求 | 主题设置 → 文章 → 关闭「显示分享按钮」，或在「分享渠道」取消勾选 |
+| 微信分享弹层 | 生成并复制文章链接 | 文章 URL（浏览器本地字符串，不发送） | 与分享按钮一致 | 同上；已移除二维码远程库，改为「复制链接」 |
+| 页脚备案 / Halo / 应用市场外链 | 备案信息、致谢、插件安装提示 | 无（访客主动点击才跳转） | 由站点配置决定，默认仅显示 Halo 致谢 | 主题设置 → 页脚 → 关闭对应显示项 |
+| 插件前台页面（豆瓣、Steam、朋友圈、微信读书等） | 展示插件提供的数据 | 由对应插件决定，主题不发起请求 | 安装并启用对应插件后才出现 | 卸载 / 停用对应插件；主题自动降级隐藏 |
+| 内置 LightGallery 灯箱 | 图片放大预览、EXIF 展示 | 无（本地打包，不联网） | 默认启用 | 安装 lightgallery.js 插件后主题自动让位 |
+
+> 自定义 API 属于**站点管理员主动配置**的可选能力：一旦填写，浏览器会按设置向该第三方发起请求。请自行评估服务商的隐私政策，并在站点隐私说明中补充披露；主题不会代替站点做这项声明。
+
+### 隐私说明（5.1）
+
+| 项目 | 说明 |
+| --- | --- |
+| 收集的数据类型 | 默认配置下**无**。主题不读取、不上传用户信息、站点内容、访问日志或订单数据 |
+| 数据用途 | 仅用于页面渲染；自定义 API 场景下由管理员自行决定 |
+| 保存位置与期限 | 主题不写入数据库、不上传数据、不生成服务端日志。前端仅在访客本机使用 `sessionStorage`（欢迎弹窗「同会话仅显示一次」）与 `localStorage`（点赞状态），可随时清除浏览器站点数据 |
+| 是否传输到第三方 | 默认**否**。仅当管理员显式填写「自定义一言 API」或「自定义 IP 定位 API」时才会向该服务发起请求，其中 IP 定位会暴露访客 IP |
+| 关闭 / 撤销方式 | 见上表；清空相应设置项或关闭对应开关即可立即停止，无需重装主题 |
+| 遥测 / 统计 / 崩溃上报 / 广告 / AI 分析 / 跨站追踪 | **均不存在**。主题不含任何埋点、指纹或第三方统计脚本 |
+
+### 自托管与许可
+
+- **已移除的远程依赖**：`cdn.jsdelivr.net` 预连接与预解析（原出现在全部模板）、PrismJS 1.29.0 核心与 `autoloader`（会按代码语言从 CDN 动态拉取并执行组件）、`qrcode-generator`、默认的一言与 IP 定位接口。
+- **代码高亮**：主题不再自带 Prism.js 运行时。语法高亮请安装 Halo 应用市场的代码高亮插件，或启用「API 扩展包」的服务端代码高亮；主题只提供两套自托管的 `.token` 配色（`assets/vendor/prism-warm.css` / `prism-cold.css`），由「文章 → 代码高亮主题」切换。
+- **字体**：[霞鹜文楷 LXGW WenKai](https://github.com/lxgw/LxgwWenKai) 以 [SIL OFL 1.1](https://openfontlicense.org/) 发布，由 `cn-font-split` 切分为本地 woff2 分片随主题分发；字体来源与版权声明保留在 `public/assets/fonts/LXGWWenKai/result.css` 中，无远程字体请求。
+- **灯箱**：LightGallery 2.9.0 以 GPLv3 发布，本主题同样采用 GPL-3.0，按开源许可条款使用（非商业授权）；已去除占位 `licenseKey`，控制台不再出现 `license key is not valid for production use`。
+- **图标**：来源与协议见[图标与字体来源](#图标与字体来源)。

 ## 已适配插件

@@ -29,7 +74,7 @@
 | [瞬间](https://halo.run/store/apps/app-SnwWD) | `PluginMoments` | `/moments` | 瞬间动态页面，支持点赞、评论、标签筛选、顶部封面 |
 | [图库](https://halo.run/store/apps/app-BmQJW) | `PluginPhotos` | `/photos` | 图片展示页面，支持分组、灯箱预览 |
 | [友情链接](https://halo.run/store/apps/app-hfbQg) | `PluginLinks` | `/links` | 友链展示页面，支持随机排列、随机传送门、评论区开关 |
-| [朋友圈](https://github.com/halo-sigs/plugin-friends) | `plugin-friends` | `/friends` | RSS 订阅朋友圈页面 |
+| [朋友圈](https://www.halo.run/store/apps/app-yISsV) | `plugin-friends` | `/friends` | RSS 订阅朋友圈页面 |
 | [装备管理](https://github.com/chengzhongxue/plugin-equipment) | `equipment` | `/equipments` | 装备展示页面，按分组展示，支持封面图 |
 | [豆瓣](https://github.com/chengzhongxue/plugin-douban) | `plugin-douban` | `/douban` | 豆瓣记录页面，支持类型/状态/标签筛选，默认音乐；需插件 **v1.2.6+**（SQLite 数据结构） |
 | [Steam 信息展示](https://github.com/Tim0x0/halo-plugin-steam) | `PluginSteam` | `/steam` | Steam 游戏库页面，含用户资料、统计数据、最近游玩、游戏库分页 |
@@ -54,16 +99,16 @@

 ### 首页

- Hero 首屏：明暗双背景图、大标题/副标题独立配色、一言（支持自动刷新与淡入淡出过渡）、下滑箭头平滑滚动
- 欢迎弹窗：基于访客 IP 地理定位的欢迎提示，支持 5 种位置、自定义 API 与会话去重开关
+- Hero 首屏：明暗双背景图、大标题/副标题独立配色、一言（默认使用内置本地句子库，可选自定义 API 与自动刷新）、下滑箭头平滑滚动
+- 欢迎弹窗：默认显示纯本地静态欢迎语，支持 5 种位置、会话去重开关；仅在显式配置自定义 IP 定位 API 时才显示访客所在地（见[外部资源与隐私](#外部资源与隐私)）
 - 滚动吸附：首屏与内容区之间滚轮/触摸自动吸附，进入内容区后恢复原生自由滚动
 - 文章卡片：可配置显示字数（依赖 API 扩展包）、阅读量、分类、标签、摘要行数

 ### 文章

 - 目录（TOC）：桌面端侧栏 + 移动端抽屉，滚动高亮、展开模式可选
- 上下篇导航：悬停反馈与方向箭头动画
- 相关推荐、分享按钮、赞赏、版权声明可独立开关
+- 代码高亮：由代码高亮插件 / API 扩展包输出，主题提供 Warm / Cold 两套本地配色；主题不加载任何远程高亮脚本
+- 上下篇导航、相关推荐、分享按钮、赞赏、版权声明可独立开关；微信分享改为复制文章链接，无需二维码库
 - 字数与阅读时间：优先使用 API 扩展包的服务端统计，未安装时前端计算兜底

 ### 全局
@@ -76,7 +121,7 @@

 ## 灯箱集成

-主题内置 LightGallery 灯箱，为图片提供放大预览功能，并支持 EXIF 信息展示。
+主题内置 LightGallery 灯箱，为图片提供放大预览功能，并支持 EXIF 信息展示。该库以 GPLv3 发布，本主题以 GPL-3.0 开源，按开源许可条款自托管使用；控制台不会出现商业授权提示。

 ### lightgallery.js 插件兼容

@@ -98,7 +143,7 @@
 3. 安装完成后点击「启用」

 > **升级后首页 404「资源不存在 / Template index was not found」**：说明上传的 ZIP 里没有 `templates/`
-> 模板文件（从源码仓库打包时漏了构建步骤）。请换用完整安装包重新上传，详见 [FAQ 安装相关](docs/faq.md)。
+> 模板文件（从源码仓库打包时漏了构建步骤）。请换用完整安装包重新上传，详见 [FAQ 安装相关](https://nxxy335.top/WarmIsland/faq.html)。
 >
 > **升级后如果整站没了样式**：Halo 页面缓存或前置反向代理里可能还留着上一版本的 HTML，
 > 它引用的 CSS 文件名带内容哈希，升级后已被删除，请求会直接 500。
@@ -107,7 +152,7 @@
 >
 > **升级主题或修改配色后，部分页面不生效**：如果安装了「页面静态缓存」插件，
 > 它只随文章变更自动刷新，主题层的变更需要手动点一次「刷新页面缓存」，
-> 详见 [FAQ：升级主题或修改配色后部分页面不生效](docs/faq.md#升级主题或修改配色后部分页面的新样式配色不生效)。
+> 详见 [FAQ：升级主题或修改配色后部分页面不生效](https://nxxy335.top/WarmIsland/faq.html)。

 或从源码构建：

@@ -115,11 +160,11 @@
 git clone https://git.nxxy335.top/nxxy335/halo-theme-WarmIsland.git
 cd halo-theme-WarmIsland
 pnpm install
-pnpm release    # build → snapshot → package
+pnpm release    # build → snapshot → package（含外部资源审计）
 ```

 `pnpm build` 只生成 `templates/`（模板 + 静态资源），不会产出 ZIP；
-安装包由 `pnpm package` 生成到 `dist/warm-island-<version>.zip`。
+安装包由 `pnpm package` 生成到 `dist/warm-island-<version>.zip`。安装包同时包含 `docs/*.md` 与预览图，便于离线查阅上架说明中引用的文档。

 ## 开发

@@ -136,6 +181,9 @@ pnpm build
 # 把本次构建的哈希资源快照进 compat/assets（发版前必做）
 pnpm snapshot

+# 外部资源 / 隐私 / README 链接审计（打包时也会自动执行）
+pnpm audit:external
+
 # 打包 dist/warm-island-<version>.zip
 pnpm package

@@ -145,7 +193,8 @@ pnpm smoke

 发版流程：`pnpm release`（等价于 `pnpm build` → `pnpm snapshot` → `pnpm package`），
 并把 `compat/assets` 的新增文件一起提交。`pnpm package` 会校验模板、资源目录与版本号一致性，
-产物缺失时直接报错，避免打出不含 `templates/` 的空壳安装包。
+并执行外部资源审计（禁止第三方预连接、远程脚本、动态加载、无效 README 链接、重复大图），
+任一不通过都会直接报错，避免打出不合规或不含 `templates/` 的空壳安装包。

 ### 目录结构

@@ -155,9 +204,13 @@ pnpm smoke
 │   ├── layouts/       # Layout.astro（含页面布局契约渲染模式）
 │   ├── pages/         # 页面模板（构建后输出到 templates/）
 │   └── styles/        # SCSS 样式（正文样式在 _content.scss，全局生效）
-├── compat/
-│   └── assets/        # 历史版本哈希静态资源，构建时合并进 templates/assets
-├── scripts/           # 构建后置、资源快照、打包、冒烟测试
+├── public/
+│   ├── assets/data/      # 内置本地一言句子库（静态 JSON）
+│   ├── assets/fonts/      # LXGW WenKai 本地字体分片
+│   ├── assets/vendor/     # 自托管的代码高亮配色 CSS
+│   └── assets/logo.png    # 主题图标（唯一一份，256×256 压缩版）
+├── compat/assets/     # 历史版本哈希静态资源，构建时合并进 templates/assets
+├── scripts/           # 构建后置、资源快照、打包、外部资源审计、冒烟测试
 ├── templates/         # 构建产物，Halo 实际加载的模板
 ├── settings.yaml      # 后台设置项定义
 └── theme.yaml         # 主题清单与自定义页面模板注册
@@ -167,14 +220,34 @@ pnpm smoke

 - **静态资源文件名带内容哈希**：升级后旧文件被删除，被缓存的 HTML 仍会请求旧文件名并触发 500，
  所以每个版本的哈希文件都要留一份（见 `compat/assets` 与 `pnpm snapshot`）
+- **不得引入远程脚本 / 样式 / 字体 / 预连接**：所有第三方资源必须自托管并标注许可，`pnpm package` 会拦截回归
 - **Thymeleaf 字符串字面量必须加单引号**：`th:text="'文本'"`，裸中文遇到逗号/空格/emoji 会导致页面 500
 - **`th:attr` 只用简单表达式**（取属性、Elvis 默认值、三元、拼接、等值比较），表达式对象方法调用会被受限求值器拒绝
 - **凡是与后台开关绑定的模板表达式都要给默认值**：`?: '默认值'`，配置未落库时属性会被整体移除，功能会静默失效
+- **截取首字符前先判空**：`#strings.substring('', 0, 1)` 会抛字符串越界异常，统一写成 `!#strings.isEmpty(x) ? #strings.substring(x, 0, 1) : '·'`
 - **正文样式必须写在全局样式表**（`src/styles/_content.scss`）：Astro scoped 样式对 Thymeleaf 运行时注入的内容无效
 - **内联脚本统一加 `th:inline="none"`**：避免 Thymeleaf 解析脚本中的 `[[` / `[(` / `${}`
 - **新插入的动画元素要强制回流**（读一次 `offsetWidth`）：否则初态与终态在同一帧被合并，transition 不触发
 - 修改主题外观无需单独维护 `layout.astro`：页面布局契约复用 `Layout.astro`，构建时自动生成

+## 验证与回归测试
+
+自动化覆盖（每次发版执行）：
+
+- `pnpm build` 生成全部 21 个模板，构建后置脚本校验所有静态资源引用真实存在
+- `pnpm audit:external` / `pnpm package` 审计第三方远程加载、预连接、动态加载、README 制品链接、Logo 去重
+- `pnpm smoke` 校验点击特效脚本；安装包内容校验模板数量、`theme.yaml` 版本与元数据一致性
+
+上架前建议在真实 Halo ≥ 2.27 实例上做一次人工回归（主题声明为 AI 辅助开发，此项由站点管理员完成并留存结果）：
+
+| 页面 | 检查要点 |
+| --- | --- |
+| 首页 | Hero、内置一言、滚动吸附、文章卡片、欢迎弹窗（默认本地文案） |
+| 文章 | 正文 / 代码块配色、目录、分享按钮与微信复制链接、灯箱、点赞 |
+| 分类 / 标签 / 归档 | 列表、分页、空状态、暗色模式 |
+| 友链 / 留言板 / 订阅 | 空字段兜底（作者为空不报错）、表单与分页 |
+| 全局 | 导航栏、页脚、移动端抽屉、深浅色切换、控制台无报错 / 无外部请求 |
+
 ## 技术栈

 - [Halo](https://halo.run) 2.27+
@@ -186,13 +259,15 @@ pnpm smoke

 [GPL-3.0](https://www.gnu.org/licenses/gpl-3.0.en.html)

-## 图标来源
+## 图标与字体来源

-本主题使用的图标来自以下开源项目：
+本主题使用的图标与字体来自以下开源项目，均随主题自托管分发、不使用远程 CDN：

 | 来源 | 协议 | 用途 |
 | --- | --- | --- |
+| [霞鹜文楷 LXGW WenKai](https://github.com/lxgw/LxgwWenKai) | [SIL OFL 1.1](https://openfontlicense.org/) | 全站中文字体（本地 woff2 分片，含保留字体名与版权声明） |
 | [Font Awesome](https://fontawesome.com/) Free v7.2.0 | [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) / [SIL OFL 1.1](https://scripts.sil.org/OFL) | QQ 分享图标 |
 | [Simple Icons](https://simpleicons.org/) | [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/) | 微博、X、Facebook、Telegram 分享图标 |
 | [Feather Icons](https://feathericons.com/) | [MIT](https://opensource.org/licenses/MIT) | 导航、界面交互图标 |
 | [Halo](https://halo.run/) | [GPL-3.0](https://www.gnu.org/licenses/gpl-3.0.en.html) | 主题内置图标 |
+| [LightGallery](https://www.lightgalleryjs.com/) 2.9.0 | GPLv3 | 图片灯箱（npm 依赖随构建打包，非远程加载） |