chill/chill_notes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update from Sync Service

Browse Source
This commit is contained in:
FNS Service
2026-04-21 22:38:06 +08:00
parent a662bc8e0a
commit 8a31c681ac
6 changed files with 780 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
参考资料/AgenticSE_智能体软件工程/AgenticSE_Book_CN_完整版.pdf Executable file
View File

Binary file not shown.

48
参考资料/语义数字化建设体系/INDEX_参考资料.md Executable file
View File

@@ -0,0 +1,48 @@
---
title: 参考资料 - 语义引领的下一代数字化建设体系
tags:
- 参考资料
- 数字化转型
- AI
- 语义智能
created: 2026-04-21
updated: 2026-04-21
---
# 语义引领的下一代数字化建设体系 参考资料
> Of AI, By AI, For AI
>
> 整理日期：2026-04-21
---
## 原始文档
| 文件 | 说明 |
|------|------|
| [[语义引领的下一代数字化建设体系_Of_AI_By_AI_For_AI_speech---536fc7e0-3df5-45fe-a904-cea4691bf074.pdf]] | 完整报告 |
---
## 核心主题
| 主题 | 说明 |
|------|------|
| Of AI | AI 赋能的数字化 |
| By AI | AI 驱动的数字化 |
| For AI | AI 原生的数字化 |
---
## 核心理念
**语义引领**：以语义理解为核心，构建下一代数字化建设体系
- 从数据驱动到语义驱动
- AI 作为建设主体
- 智能化原生架构
---
*整理：知识库管理员 | 归档：2026-04-21*

134
导航网站/bookmarks/README.md Executable file
View File

@@ -0,0 +1,134 @@
# MeNav 书签目录
## 目录
- [目录概述](#目录概述)
- [书签导入功能](#书签导入功能)
- [配置加载优先级（完全替换）](#配置加载优先级完全替换)
- [MarksVault 扩展集成](#marksvault-扩展集成)
- [书签导入流程](#书签导入流程)
- [确定性输出](#确定性输出)
- [支持的浏览器](#支持的浏览器)
- [书签格式要求](#书签格式要求)
- [文件处理机制](#文件处理机制)
## 目录概述
`bookmarks` 目录是 MeNav 项目中用于存放浏览器导出的书签文件的专用目录。该目录与书签导入功能直接关联，用于自动将浏览器书签转换为 MeNav 配置文件，从而快速生成个人导航站点。
## 书签导入功能
书签导入功能允许用户：
- 从浏览器导出书签为 HTML 文件
- 将书签文件放入此目录
- 通过自动处理将书签转换为网站配置
- 无需手动编辑即可批量导入网站链接
这一功能极大简化了网站内容的初始设置过程，特别适合需要迁移大量书签的用户。
## 配置加载优先级（完全替换）
书签页配置同样遵循项目的“完全替换”策略：系统只会选择一套配置目录加载，不会把 `user` 与 `_default` 混合合并。
- 若存在 `config/user/`：书签页配置应位于 `config/user/pages/bookmarks.yml`（通常由导入脚本生成）
- 否则：使用 `config/_default/pages/bookmarks.yml`（默认示例）
> 提示：一旦创建 `config/user/`，`config/_default/` 会被完全忽略，因此不要指望从默认配置“兜底补齐缺失项”。
## MarksVault 扩展集成
[MarksVault](https://github.com/rbetree/MarksVault) 浏览器扩展可与 MeNav 集成，实现书签自动同步：
- **一键推送书签**：扩展将书签 HTML 文件推送到仓库的 `bookmarks/` 目录
- **自动化处理**：GitHub Actions 检测到书签文件后自动运行导入脚本生成配置
- **自动清理**：处理完成后会删除已导入的 HTML 文件，避免重复处理
## 书签导入流程
完整的书签导入流程如下：
1. 在浏览器中导出书签为 HTML 文件
2. 将导出的书签文件放入 `bookmarks` 目录
3. 运行书签处理工具：
```bash
npm run import-bookmarks
```
- 若 `config/user/` 不存在，导入脚本会先从 `config/_default/` 初始化一份用户配置（因为配置采用“完全替换”策略，需要完整配置才能正常生成站点）。
（可选）若希望生成结果保持确定性（便于版本管理，减少时间戳导致的无意义 diff）：
```bash
MENAV_BOOKMARKS_DETERMINISTIC=1 npm run import-bookmarks
```
4. 系统自动解析书签文件内容
5. 根据书签文件夹结构生成分类
6. 生成配置文件保存到 `config/user/pages/bookmarks.yml`
7. 构建网站应用新配置：
```bash
npm run build
```
> **重要说明**：在本地开发中，`npm run dev` 命令**不会**自动处理书签文件。您必须先手动运行 `npm run import-bookmarks` 命令处理书签，然后再运行 `npm run dev` 查看效果。这与 GitHub Actions 中的自动处理流程不同，请务必注意。
## 确定性输出
默认情况下，导入脚本会在生成的 `bookmarks.yml` 顶部写入时间戳注释，导致每次导入都会产生 diff。
若你希望生成结果尽量稳定（只有书签内容变化才产生 diff），可使用环境变量开启确定性输出：
```bash
MENAV_BOOKMARKS_DETERMINISTIC=1 npm run import-bookmarks
```
## 支持的浏览器
MeNav 书签导入功能支持从以下浏览器导出的书签文件：
- **Chrome** - 通过书签管理器导出
- **Firefox** - 通过书签库导出
- **Edge** - 通过收藏夹导出
- **Safari** - 通过书签菜单导出
- 其他支持标准 HTML 书签格式的浏览器
## 书签格式要求
导入的书签文件需满足以下要求：
- 文件格式：HTML（标准网络书签格式）
- 文件编码：UTF-8
- 文件结构：包含 `<DL>`、`<DT>` 和 `<A>` 标签的标准书签结构
- 文件大小：建议不超过 5MB（约数千个书签）
- 支持处理位于文件夹内的书签
- 支持处理不在任何文件夹内的根路径书签（自动归入"根目录书签"分类）
- 空文件夹会被忽略
## 文件处理机制
书签处理器 (`src/bookmark-processor.js`) 对书签文件进行以下处理：
1. **解析文件结构**：
- 读取书签 HTML 文件
- 解析 DOM 结构获取书签层次
- 提取文件夹和链接信息
2. **分类提取**：
- 将书签文件夹转换为网站分类
- 提取链接URL、标题和添加日期
3. **根路径书签处理**：
- **自动分类**：根路径书签会被自动归入名为"根目录书签"的特殊分类
- **显示位置**：该分类始终位于所有其他分类之前（第一位）
- **图标标识**：使用星标图标（fas fa-star）
- **条件生成**：只有存在根路径书签时才会创建该分类
- **自动映射**：根路径书签同样支持基于URL的自动图标映射功能
4. **图标分配**：
- 根据URL自动匹配合适的 Font Awesome 图标
- 为每个链接和分类分配图标
- 当 `icons.mode: favicon` 时，页面通常会优先显示站点 favicon；配置里的 `icon` 主要用于回退显示或在 `icons.mode: manual` 时使用（详见 `config/README.md`）
5. **配置生成**：
- 创建符合 MeNav 配置格式的 YAML 文件
- 按层级组织分类和链接
- 应用自动生成的元数据
将书签放入此目录后，您可以立即利用 MeNav 的书签处理功能，快速将书签转化为个性化导航站点。

382
导航网站/config/README.md Executable file
View File

@@ -0,0 +1,382 @@
# MeNav 配置目录
## 目录
- [目录概述](#目录概述)
- [配置目录结构](#配置目录结构)
- [配置加载机制](#配置加载机制)
- [推荐用法](#推荐用法)
- [模块化配置文件](#模块化配置文件)
- [网站基础配置](#网站基础配置)
- [页面配置](#页面配置)
- [配置详解](#配置详解)
- [site.yml 常用字段](#siteyml-常用字段)
- [pages/ 页面配置](#pages-页面配置)
- [多层级嵌套配置（2-4层）](#多层级嵌套配置2-4层)
- [配置优先级](#配置优先级)
- [配置示例](#配置示例)
- [最佳实践](#最佳实践)
## 目录概述
`config` 目录包含 MeNav 项目的所有配置文件，采用模块化的 YAML 格式组织。这些配置文件定义了网站的内容、结构、布局和功能，是定制个人导航站的核心。
## 配置目录结构
配置系统采用分层结构，清晰分离默认配置和用户配置：
```
config/
├── _default/ # 默认配置目录
│ ├── site.yml # 默认网站基础配置（含导航配置）
│ └── pages/ # 默认页面配置
│ ├── common.yml # 示例：默认首页（navigation 第一项）
│ ├── projects.yml # 项目页
│ ├── articles.yml # 文章页
│ └── bookmarks.yml # 书签页
└── user/ # 用户配置目录（覆盖默认配置）
├── site.yml # 用户自定义网站配置（含导航配置）
└── pages/ # 用户自定义页面配置
├── common.yml # 示例：与 navigation 第一项对应
└── ...
```
## 配置加载机制
MeNav 配置系统采用“完全替换”策略（不合并），按以下优先级选择**唯一**的一套配置目录：
1. 若存在 `config/user/`，则只加载该目录下的配置，并**完全忽略** `config/_default/`
2. 否则加载 `config/_default/` 作为默认配置
也就是说：`config/user/` 一旦存在，就需要包含一套完整的配置（例如 `site.yml` 与必要的 `pages/*.yml`），系统不会把缺失部分从默认配置补齐。
## 推荐用法
为避免文档与配置字段长期不同步，建议按以下方式使用与维护：
1. **首次使用**：完整复制 `config/_default/` 到 `config/user/`，再按需修改。
2. **字段与结构的权威参考**：
- 全局配置：[`_default/site.yml`](_default/site.yml)
- 页面配置：[`_default/pages/`](_default/pages/)
3. **多层级嵌套书签示例**：[`_default/pages/bookmarks.yml`](_default/pages/bookmarks.yml)（包含2层、3层、4层结构示例；`subgroups` 可参考下方说明或由导入脚本生成）
## 模块化配置文件
### 网站基础配置
`site.yml` 定义网站的基本信息和全局设置：
- 网站标题、描述和关键词
- 作者信息和版权声明
- 字体配置、图标模式等全局设置
- 全局元数据和站点参数
- 个人资料和社交媒体链接
- 导航菜单配置（侧边栏导航项、页面标题和图标、页面顺序和可见性）
> **注意**：导航配置仅支持写在 `site.yml` 的 `navigation` 字段中。
### 页面配置
`pages/` 目录下的配置文件定义各个页面的内容：
- `common.yml`: 示例首页（本质上是普通页面；首页由 navigation 第一项决定，不要求必须叫 home）
- `projects.yml`: 项目展示配置
- `articles.yml`: 文章列表配置
- `bookmarks.yml`: 书签页面配置
- 其他自定义页面配置（可按需新增/删除；与 `site.yml -> navigation[].id` 对应）
## 配置详解
本章节用于补齐“怎么配才是对的”这类细节说明。为了避免示例长期过时，字段与结构的权威参考始终以默认配置为准：
- 全局配置：[`_default/site.yml`](_default/site.yml)
- 页面配置：[`_default/pages/`](_default/pages/)
### site.yml 常用字段
`site.yml` 中字段较多，以下是常用项的解释与注意点（完整字段请以默认配置为准）：
1. **基础信息**
- `title`：站点标题
- `description`：站点描述（SEO/分享）
- `author`：作者/署名
- `favicon`、`logo_text`：站点图标与左上角 Logo 文本
2. **图标模式（隐私相关）**
- `icons.mode: favicon | manual`
- `favicon`：会请求第三方服务（Google）获取站点 favicon，失败自动回退到 Font Awesome 图标
- `manual`：完全使用手动 Font Awesome 图标，不发起外部请求（适合内网/离线/隐私敏感场景）
- `icons.region: com | cn`（默认 `com`）
- `com`：优先使用 `gstatic.com`（国际版），失败后回退到 `gstatic.cn`（中国版）
- `cn`：优先使用 `gstatic.cn`（中国版），失败后回退到 `gstatic.com`（国际版）
- 说明：如果你在中国大陆且访问 gstatic.com 较慢，建议设置为 `cn` 以提升图标加载速度
- 站点级覆盖（可选，写在 `pages/*.yml` 的每个 `sites[]` 节点上）：
- `faviconUrl`：为单个站点指定图标链接（可远程或本地相对路径；本地建议以 `assets/` 开头，构建会复制到 `dist/` 同路径），优先级最高
- `forceIconMode: favicon | manual`：强制该站点使用指定模式（不设置则跟随全局 `icons.mode`）
- 优先级：`faviconUrl` > `forceIconMode` > 全局 `icons.mode`
- 示例：
```yml
sites:
- name: 'Ant Design'
url: 'https://ant.design/'
icon: 'fas fa-th'
forceIconMode: manual # 强制使用手动图标，绕过 favicon 默认"地球"图标
- name: 'Example'
url: 'https://example.com/'
faviconUrl: 'https://example.com/favicon.png' # 单站点自定义 favicon
```
3. **安全策略（链接白名单）**
- `security.allowedSchemes`：允许在页面中渲染为可点击链接的 URL scheme 白名单
- 默认仅允许：`http/https/mailto/tel` + 所有相对链接（`#`、`/`、`./`、`../`、`?` 开头）
- 其他 scheme 会被安全降级为 `#` 并输出告警；如需支持 `obsidian://`、`vscode://` 等协议，可在此显式放行
4. **字体**
- `fonts`：单一字体配置项，用于设置全站基础字体（`body` 等）
- 支持 `source: css | google | system`（分别表示第三方 CSS、Google Fonts、系统字体）
- 可选 `fonts.preload: true`：用 `preload + onload` 的方式非阻塞加载外链字体 CSS（更利于首屏性能）
- 首页副标题（渐变发光样式）使用全站基础字体（跟随 `fonts` 配置）
5. **主题（默认明暗模式）**
- `theme.mode: dark | light | system`
- `dark/light`：首屏默认主题；用户点击按钮切换后会写入 localStorage 并覆盖该默认值
- `system`：跟随系统 `prefers-color-scheme`；用户手动切换后同样会写入 localStorage 并停止跟随
6. **顶部欢迎信息与社交链接**
- `profile`：首页顶部欢迎信息
- `social`：侧边栏底部社交链接
- `profile.title` / `profile.subtitle`：分别对应首页顶部主标题与副标题
7. **导航**
- `navigation[]`：页面入口列表，`id` 需唯一，并与 `pages/<id>.yml` 对应（例如 `id: common` 对应 `pages/common.yml`）
- 默认首页由 `navigation` 数组顺序决定：**第一项即为首页（默认打开页）**，不再使用 `active` 字段
- 图标使用 Font Awesome 类名字符串（例如 `fas fa-home`、`fab fa-github`）
- 导航显示顺序与数组顺序一致，可通过调整数组顺序改变导航顺序
8. **RSS（articles Phase 2）**
- `rss.*`：仅用于 `npm run sync-articles`（联网抓取 RSS/Atom 并写入缓存）
- `npm run build` 默认不联网；无缓存时 `articles` 页面会回退到 Phase 1 的站点入口展示
- articles 页面会按 `articles.yml` 的分类进行聚合展示：某分类下配置的来源站点，其文章会显示在该分类下
- 抓取条数默认：每个来源站点抓取最新 8 篇（可通过 `site.yml -> rss.articles.perSite` 或 `RSS_ARTICLES_PER_SITE` 调整）
- 默认配置已将 `rss.cacheDir` 设为 `dev`（仓库默认 gitignore），避免误提交缓存文件；可按需改为自定义目录
- GitHub Pages 部署工作流会在构建前自动执行 `npm run sync-articles`，并支持定时触发（默认每天 UTC 02:00；可在 `.github/workflows/deploy.yml` 调整）
9. **GitHub（projects 热力图，可选）**
- `github.username`：你的 GitHub 用户名（用于 projects 页面标题栏右侧贡献热力图）
- `github.heatmapColor`：热力图主题色（不带 `#`，例如 `339af0`）
- `github.cacheDir`：projects 仓库元信息缓存目录（默认 `dev`，仓库默认 gitignore）
- projects 仓库统计信息（language/stars/forks）由 `npm run sync-projects` 自动抓取并写入缓存；`npm run build` 默认不联网
- GitHub Pages 部署工作流会在构建前自动执行 `npm run sync-projects`，并支持定时触发（默认每天 UTC 02:00；可在 `.github/workflows/deploy.yml` 调整）
### pages/ 页面配置
页面配置位于 `pages/*.yml`，每个文件对应一个页面内容，文件名与导航 `id` 对应：
- `pages/common.yml`：示例首页（通常是 `categories -> sites`）
- `pages/projects.yml` / `articles.yml`：示例页面（可按需删改）
- `pages/bookmarks.yml`：书签页（通常由导入脚本生成，也可以手动维护）
> 提示：自定义页面时，先在 `site.yml` 的 `navigation` 中增加一个 `id`，再创建同名的 `pages/<id>.yml`。
>
> 支持“可删除”：如果 `navigation` 中存在某个页面 `id`，但 `pages/<id>.yml` 不存在，构建仍会生成该页面（标题回退为导航名称、分类为空、模板默认使用通用 `page`）。
>
> 站点描述建议简洁（例如不超过 30 个字符），以保证卡片展示更美观。
#### 通用 page 页面配置（推荐，用于 friends 等普通页面）
对不需要特殊渲染的页面（例如“友链/朋友”页），建议使用通用 `page` 模板，并保持 `categories -> sites`（可选更深层级）：
```yaml
title: 示例页面
subtitle: 示例副标题
template: page
categories:
- name: 示例分类
icon: fas fa-folder
sites:
- name: 示例站点
url: https://example.com
icon: fas fa-link
description: 示例描述
```
兼容说明：
- 若历史配置仍使用顶层 `sites`（旧结构），系统会自动映射为一个分类容器以保持页面结构一致（当前仅对 friends/articles 提供该兼容）。
#### 内容页（template: content）
内容页用于承载“关于 / 帮助 / 使用说明 / 更新日志 / 迁移指南 / 隐私说明”等纯文本内容。
配置要点：
- `template: content`
- `content.file`：指向本地 Markdown 文件路径（推荐放在 `content/` 下）
- Markdown 会在**构建期**渲染为 HTML（不是运行时 fetch）
- 当前约束：
- 禁止 raw HTML（避免 XSS）
- 禁止图片（`![]()` 不会输出 `<img>`；本期不支持图片/附件）
- 链接会按 URL scheme 白名单策略处理：
- 默认允许：`http/https/mailto/tel` + 所有相对链接（`#`、`/`、`./`、`../`、`?` 开头）
- 其他 scheme 会被安全降级为 `#`（可用 `site.yml -> security.allowedSchemes` 显式放行）
示例（以 about 页面为例）：
```yml
# config/user/pages/about.yml
title: 关于
subtitle: 项目说明
template: content
content:
file: content/about.md
```
对应内容文件：
```text
content/about.md
```
### 多层级嵌套配置（2-4层）
书签与分类支持 2~4 层嵌套，用于更好组织大量站点。建议直接参考默认示例：
- 多层级结构示例：[`_default/pages/bookmarks.yml`](_default/pages/bookmarks.yml)（包含2层、3层、4层结构示例）
层级命名约定（自顶向下）：
1. `categories`：顶层分类
2. `subcategories`：子分类
3. `groups`：分组
4. `subgroups`：子分组
5. `sites`：站点（叶子节点）
若你需要第 4 层（`subgroups`），结构示例（片段）：
```yaml
categories:
- name: 示例分类
subcategories:
- name: 示例子分类
groups:
- name: 示例分组
subgroups:
- name: 示例子分组
sites:
- name: 示例站点
url: https://example.com
```
#### 向后兼容性
- 原有二层结构（`categories -> sites`）无需修改即可继续使用
- 系统会自动识别层级结构并匹配对应的模板/样式
- 允许在同一份配置中混用不同层级（例如某些分类是二层，某些分类是三/四层）
## 配置优先级
MeNav 配置系统采用“完全替换”策略：只会选择一套目录加载，不会把 `user` 与 `_default` 混合合并。
- 若存在 `config/user/`：只加载 `config/user/`，并**完全忽略** `config/_default/`
- 否则：加载 `config/_default/`
在“同一套目录”内，各文件的关系是：
- `site.yml`：站点全局配置（包含 `navigation` 等）
- `pages/*.yml`：各页面配置（文件名需与 `navigation.id` 对应）
## 配置示例
### 网站配置示例 (site.yml)
```yaml
# 网站基本信息
title: '我的个人导航'
description: '个人收藏的网站导航页'
keywords: '导航,网址,书签,个人主页'
# 个人资料配置
profile:
title: '个人导航站'
subtitle: '我收藏的精选网站'
# 字体：全站基础字体
fonts:
source: css
cssUrl: 'https://fontsapi.zeoseven.com/292/main/result.css'
preload: true
family: 'LXGW WenKai'
weight: normal
# 社交媒体链接
social:
- name: 'GitHub'
url: 'https://github.com/username'
icon: 'fab fa-github'
- name: 'Twitter'
url: 'https://twitter.com/username'
icon: 'fab fa-twitter'
# 导航配置
navigation:
- name: '常用'
icon: 'fas fa-star'
id: 'common'
- name: '项目'
icon: 'fas fa-project-diagram'
id: 'projects'
- name: '文章'
icon: 'fas fa-book'
id: 'articles'
- name: '书签'
icon: 'fas fa-bookmark'
id: 'bookmarks'
```
### 通用页面配置示例（例如 common.yml）
```yaml
# 页面分类配置
categories:
- name: '常用工具'
icon: 'fas fa-tools'
sites:
- name: 'Google'
url: 'https://www.google.com'
description: '全球最大的搜索引擎'
icon: 'fab fa-google'
- name: 'GitHub'
url: 'https://github.com'
description: '代码托管平台'
icon: 'fab fa-github'
- name: '学习资源'
icon: 'fas fa-graduation-cap'
sites:
- name: 'MDN Web Docs'
url: 'https://developer.mozilla.org'
description: 'Web开发技术文档'
icon: 'fab fa-firefox-browser'
```
## 最佳实践
1. **目录结构**:
- 总是在 `user/` 目录下创建您的配置
- 不要直接修改 `_default/` 中的文件
2. **文件命名**:
- 遵循现有的文件命名约定
- 自定义页面配置应使用有意义的名称
3. **配置管理**:
- 利用模块化结构分类管理配置
- 首次使用建议先完整复制 `config/_default/` 到 `config/user/`，再按需修改
- 定期备份您的用户配置
4. **配置验证**:
- 修改配置后运行 `npm run check`（语法检查 + 单测 + 构建）
- 需要本地预览时运行 `npm run dev`（命令入口见 [`../README.md#快速开始`](../README.md#快速开始)）
- 确保 YAML 语法正确无误

114
导航网站/config/update-instructions-20251227.md Executable file
View File

@@ -0,0 +1,114 @@
# 更新说明（2025-12-27）
本文档用于说明“页面模板差异化改进”相关改动中，**配置层面的新增字段、减少字段与迁移要点**。内容与 [`README.md`](../README.md) 的“2025/12/27 更新记录”保持一致。
最后更新：2025-12-27
---
## 1. 新增/扩展的配置字段
### 1.1 `site.rss.*`（articles RSS 聚合 / 缓存）
用途：为 `articles` 页面提供 RSS/Atom 文章聚合数据，供 `npm run sync-articles` 联网抓取并写入缓存；`npm run build` 默认不联网，只读取缓存渲染。
关键字段（默认示例见 `config/_default/site.yml`）：
- `site.rss.enabled`：是否启用 RSS 抓取能力
- `site.rss.cacheDir`：缓存目录（建议 `dev/`，仓库默认 gitignore）
- `site.rss.fetch.*`：抓取参数（超时、并发、重试、重定向等）
- `site.rss.articles.*`：抓取条数与摘要长度（例如每站点最多 8 篇）
说明：
- RSS 抓取只影响 `articles` Phase 2（文章条目只读展示），不会影响扩展对“来源站点（sites）”的写回能力（构建会保留影子写回结构）。
---
### 1.2 `site.github.*`（projects 仓库元信息 + 热力图）
用途：
- projects 卡片可展示仓库元信息（language/stars/forks 等，只读），由 `npm run sync-projects` 联网抓取并写入缓存。
- projects 标题区右侧可选展示 GitHub 贡献热力图。
关键字段（默认示例见 `config/_default/site.yml`）：
- `site.github.username`：GitHub 用户名；为空则不展示热力图
- `site.github.heatmapColor`：热力图主题色（不带 `#`，如 `339af0`）
- `site.github.cacheDir`：仓库元信息缓存目录（建议 `dev/`）
说明：
- 仓库元信息来自 GitHub API，属于“时效性数据”，不会写回到 `pages/projects.yml`。
---
### 1.3 `pages/<id>.yml -> template`（页面模板选择）
用途：指定页面使用的模板（对应 `templates/pages/<template>.hbs`，不含扩展名）。
行为规则：
- 若 `template` 缺省：优先尝试同名模板（`templates/pages/<pageId>.hbs`），不存在则回退到通用 `page` 模板。
- `bookmarks/projects/articles` 等特殊页建议显式配置 `template`，以减少误解。
---
## 2. 减少/不再支持的配置方式（Breaking）
### 2.1 根目录单文件配置 `config.yml` / `config.yaml`
当前版本不再回退读取根目录 `config.yml`/`config.yaml`。
迁移要点：
- 使用模块化配置目录：`config/user/`（优先级最高，完全替换）或 `config/_default/`（默认示例）。
- 推荐迁移方式：复制 `config/_default/` → `config/user/`，再按需修改 `site.yml` 与 `pages/*.yml`。
---
### 2.2 独立 `navigation.yml`
当前版本仅从 `site.yml -> navigation` 读取导航配置，不再读取 `navigation.yml`。
迁移要点：
- 将原 `navigation.yml` 的数组内容移动到 `config/user/site.yml` 的 `navigation:` 字段下。
---
### 2.3 `pages/home.yml -> 顶层 categories` 与 `home` 子菜单特例
当前版本不再维护“首页固定叫 `home`”的遗留逻辑（例如把 `pages/home.yml` 的分类提升到顶层 `config.categories`）。
迁移要点：
- 不要依赖固定页面 id `home`。
- 首页始终由 `site.yml -> navigation` 的**第一项**决定；其分类内容应写在对应的 `pages/<homePageId>.yml` 中。
---
### 2.4 `navigation[].active` 不再生效（首页不再靠 active 指定）
历史版本可能通过 `navigation[].active` 指定“默认打开页/首页”。
当前版本：
- 首页/默认打开页始终由 `site.yml -> navigation` 的**第一项**决定
- `active` 字段将被忽略（即使写了也不会生效）
迁移要点：
- 通过调整 `navigation` 数组顺序来设置首页（把希望作为首页的页面放到第一项）。
---
## 3. 与更新记录的对应关系（快速索引）
- 首页判定规则：`site.yml -> navigation` 第一项
- 模板体系：`pages/<id>.yml -> template`（缺省回退 `page`）
- bookmarks 更新时间：构建期注入（不需要新增配置字段）
- articles RSS：`site.rss.*` + `npm run sync-articles`
- projects 元信息/热力图：`site.github.*` + `npm run sync-projects`
- 兼容清理：移除 `config.yml/config.yaml`、`navigation.yml`、`home` 特例

102
导航网站/config/update-instructions-20260102.md Executable file
View File

@@ -0,0 +1,102 @@
# 更新说明（2026-01-02）
本文档用于说明 Issue #30（外部资源/图标/嵌套交互）相关改动中，**配置层面的新增字段、行为变更与迁移要点**。
关联 Issue：https://github.com/rbetree/menav/issues/30
最后更新：2026-01-02
---
## 1. 新增/扩展的配置字段
### 1.1 `site.yml -> icons.mode`（站点卡片图标模式 / 隐私）
用途：控制“站点卡片图标”的全局渲染方式。
取值：
- `favicon`：根据站点 URL 通过第三方服务加载站点 favicon（失败时回退到 Font Awesome 图标）
- `manual`：始终使用配置中的 Font Awesome 图标类名（不发起 favicon 外部请求）
注意：
- 该配置位于 `site.yml` 的 `icons:` 节点下（默认示例见 `config/_default/site.yml`）。
- 配置目录采用“完全替换”策略：若启用 `config/user/`，需要在 `config/user/site.yml` 中设置该字段才会生效。
- 切换后需要重新生成页面（`npm run build` / `npm run dev`）才能影响生成的 HTML。
示例：
```yml
# config/user/site.yml
icons:
mode: manual
```
---
### 1.2 `pages/*.yml -> sites[].faviconUrl`（站点级自定义图标链接）
用途：为单个站点指定图标链接（可远程或本地相对路径），用于兜底“favicon 服务返回默认图标/网络不可达”等情况。
说明：
- `faviconUrl` 优先级最高：一旦设置，将直接使用该图片链接渲染图标。
- 本地路径建议以 `assets/` 开头；构建时会复制到 `dist/` 同路径，便于离线/内网使用。
示例：
```yml
sites:
- name: '内部系统'
url: 'https://intranet.example/'
faviconUrl: 'assets/icons/intranet.png'
```
---
### 1.3 `pages/*.yml -> sites[].forceIconMode`（站点级强制图标模式）
用途：强制该站点使用指定模式（不设置则跟随全局 `icons.mode`）。
取值：
- `favicon`：强制走 favicon（外部请求）
- `manual`：强制走手动图标（不发起 favicon 外部请求）
优先级：
- `faviconUrl` > `forceIconMode` > 全局 `icons.mode`
示例：
```yml
sites:
- name: 'Ant Design'
url: 'https://ant.design/'
icon: 'fas fa-th'
forceIconMode: manual
```
---
## 2. 行为变更与修复要点（无需迁移字段）
### 2.1 `icons.mode` 全局切换修复
修复点：此前 `site.yml` 中的 `icons` 没有被提升为顶层 `icons`，导致模板与运行时读取到的仍是默认 `favicon`。本次已修复，`site.yml -> icons.mode` 会被模板/运行时统一读取生效。
### 2.2 favicon 双域名回退（`.com` → `.cn`）
修复点：favicon 默认使用 `t3.gstatic.com`，失败时自动切换 `t3.gstatic.cn` 重试一次，提升国内网络可用性。
### 2.3 多级结构站点新标签页打开一致性
修复点：多级结构（`subcategories/groups/subgroups`）下站点默认值未递归补齐，导致 `external` 为 `undefined` 时不输出 `target="_blank"`。本次已在生成阶段递归补齐 `sites[].external` 默认 `true`（显式 `external: false` 保持同页打开）。
---
## 3. 迁移建议（从旧版本升级）
1. 若使用 `config/user/`：请在 `config/user/site.yml` 中设置 `icons.mode`，然后执行 `npm run build` 重新生成页面。
2. 若遇到某些站点 favicon 始终显示默认图标：建议对该站点配置 `forceIconMode: manual`（使用 Font Awesome）或提供 `faviconUrl` 指向可靠图片（远程或本地 `assets/`）。