Yuriyagn · Yuriyagn · Aug 2, 2026 · Aug 2, 2026 · Aug 2, 2026 · Aug 2, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -13,12 +13,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
-          node-version: 20
+          node-version: 24
           cache: npm
 
       - name: Install dependencies

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -15,12 +15,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check out repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v6
         with:
-          node-version: 20
+          node-version: 24
           cache: npm
 
       - name: Install dependencies

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,30 @@
 
 All notable changes to Controlled Tagger are documented in this file.
 
+## [0.5.0] - 2026-08-02
+
+### Added
+
+- Added a persistent tag semantic library derived from the existing relationships between tags and tagged notes.
+- Added incremental fingerprints so unchanged tags reuse cached semantics instead of consuming repeated model requests.
+- Added semantic-library status, searchable inspection, manual refresh, and opt-in daily, weekly, or monthly refresh schedules.
+- Added the cached meaning, usage conditions, and boundaries of tags to recommendation prompts for more substantive explanations.
+
+### Privacy
+
+- Semantic refreshes send at most three recent note titles and 800-character excerpts per changed tag directly to the configured model provider.
+- Only generated semantic summaries and fingerprints are persisted; sampled note excerpts are not stored in plugin settings.
+
+## [0.4.2] - 2026-08-02
+
+### Fixed
+
+- Restored the settings page on Obsidian versions before 1.13 while retaining searchable settings on Obsidian 1.13 and later.
+- Restored the actual minimum supported Obsidian version to 1.5.0 for manual installations and upgrades.
+- Replaced the unlabeled recommendation-count slider with a validated numeric input from 1 to 20.
+- Requests now target the exact configured tag count and automatically retry once when model output contains too few valid tags.
+- Removed horizontal scrolling from the tag manager and kept rename/delete actions visible at narrow window widths.
+
 ## [0.4.1] - 2026-08-01
 
 ### Changed

diff --git a/README.md b/README.md
@@ -35,7 +35,7 @@
 
 The plugin can initialize its controlled registry from tags already used in your Vault. It also supports adding tags manually, importing newly discovered tags, and renaming or deleting tags across matching Markdown notes. Vault-wide operations always show the number of affected notes before you confirm them. Back up your Vault before a bulk rename or deletion.
 
-Network access occurs only when you explicitly test a connection or request tag suggestions. The request is sent directly to the OpenAI-compatible endpoint that you configure; it may contain your API key, model ID, active note title, up to 20,000 characters from the note, and the allowed tag list. Controlled Tagger has no telemetry, advertising, author-operated proxy, or hidden network service. Your API key is stored as plaintext in the plugin's local `data.json` file.
+Network access occurs when you test a connection, request tag suggestions, manually refresh the tag semantic library, or enable its opt-in refresh schedule. Requests go directly to the OpenAI-compatible endpoint that you configure. Semantic refreshes send at most three recent note titles and 800-character excerpts per changed tag; excerpts are not persisted. Controlled Tagger has no telemetry, advertising, author-operated proxy, or hidden network service. Your API key and generated semantic summaries are stored in the plugin's local `data.json` file.
 
 To provide tag counts, imports, and Vault-wide rename or deletion, the plugin enumerates Markdown file paths and reads Obsidian's local metadata cache. It reads note contents only for the active suggestion request or for locally confirmed tag updates. Vault data is never sent to the plugin author.
 
@@ -54,6 +54,8 @@ For complete English installation, usage, privacy, and development documentation
 - 🔄 **全库维护** — 重命名或删除标签时显示影响篇数，并同步更新属性标签与正文标签
 - 🌳 **层级标签** — 支持 `领域/人工智能` 形式的 Obsidian 层级标签
 - 🛡️ **本地校验** — 模型输出与受控标签库取交集，不接受模型自行创造的标签
+- 🧭 **标签内涵库** — 从已有标签与笔记的对应关系中提炼实际语义、适用条件和判断边界
+- ⚡ **增量缓存** — 未变化的标签复用已有内涵，可手动更新或选择每日、每周、每月更新
 - 🚫 **无遥测** — 不收集使用统计，不包含广告，不连接作者服务器
 
 ## 📸 界面与流程
@@ -74,6 +76,16 @@ For complete English installation, usage, privacy, and development documentation
 | :---: | :---: |
 | ![标签建议](docs/screenshots/tag-suggestions.png) | ![标签写入结果](docs/screenshots/applied-tags.png) |
 
+### 4. 建立并查看标签内涵库
+
+| 设置状态、手动与定时更新 | 查看并搜索生成的内涵 |
+| :---: | :---: |
+| ![标签内涵库设置](docs/screenshots/tag-semantic-settings.png) | ![标签内涵库详情](docs/screenshots/tag-semantic-library.png) |
+
+### 5. 获得结合知识库实际用法的推荐理由
+
+![结合标签内涵生成的 AI 标签建议](docs/screenshots/semantic-tag-suggestions.png)
+
 ## 📦 安装
 
 ### 社区插件商店
@@ -106,9 +118,10 @@ Controlled Tagger 已正式发布到 [Obsidian 官方社区插件商店](https:/
 2. 填写 API Key、API 服务地址和模型。
 3. 点击“开始测试”，确认连接成功。
 4. 打开“管理标签”，从 Vault 导入标签或新增允许标签。
-5. 打开一篇 Markdown 笔记。
-6. 点击左侧标签按钮，或从命令面板运行“Controlled Tagger: 为当前笔记推荐标签”。
-7. 勾选需要的标签，然后选择“追加到当前笔记”或“替换当前笔记标签”。
+5. 点击“标签内涵库 → 立即更新”，或在首次推荐时让插件自动初始化内涵库。
+6. 打开一篇 Markdown 笔记。
+7. 点击左侧标签按钮，或从命令面板运行“Controlled Tagger: 为当前笔记推荐标签”。
+8. 勾选需要的标签，然后选择“追加到当前笔记”或“替换当前笔记标签”。
 
 ### 配置项
 
@@ -118,7 +131,9 @@ Controlled Tagger 已正式发布到 [Obsidian 官方社区插件商店](https:/
 | API 服务地址 | OpenAI 兼容 API 的基础地址 | `https://api.siliconflow.cn/v1` |
 | 模型 | 内置预设或自定义模型 ID | `Qwen/Qwen3.5-4B` |
 | 请求超时 | 免费或繁忙模型的最长等待时间 | 90 秒 |
-| 最多推荐数量 | 单篇笔记最多返回的标签数 | 3 |
+| 推荐标签数量 | 单篇笔记期望返回的标签数（1–20） | 3 |
+| 标签内涵库 | 查看状态、内涵内容并手动执行增量更新 | 首次推荐时初始化 |
+| 内涵库定时更新 | 关闭、每天、每周或每月 | 关闭 |
 
 模型是否可用、是否免费及具体价格由服务商决定，可能随时变化。
 
@@ -130,25 +145,45 @@ Controlled Tagger 已正式发布到 [Obsidian 官方社区插件商店](https:/
 - 重命名或删除会修改所有包含该标签的 Markdown 笔记，操作前会显示受影响篇数并要求确认。
 - “替换当前笔记标签”只替换 YAML 属性中的 `tags`；正文内联标签保持不变。
 
+## 🧭 标签内涵库如何工作
+
+标签名称往往很短，无法完整表达它在个人知识库中的真实含义。内涵库会扫描“哪些笔记已经使用了哪些标签”，并为发生变化的标签抽取最多 3 篇近期笔记作为样本。每篇样本只包含标题和最多 800 个字符的正文摘要。
+
+模型为每个标签生成三类缓存信息：核心内涵、适用条件和判断边界。后续推荐只把这些缓存说明提供给模型，不会为了每篇新文章重新扫描和提炼整个 Vault。插件使用标签—笔记关系、文件修改时间和大小生成本地指纹；指纹和模型均未变化时会跳过该标签。
+
+- 首次主动推荐时，如果内涵库尚未建立，会先初始化一次。
+- “立即更新”执行增量检查，只请求发生变化或更换了模型的标签。
+- 定时更新默认关闭；启用后会按每天、每周或每月在后台执行相同的增量检查。
+- 可以在设置中查看并搜索已经生成的标签内涵。
+- 新增但尚未用于任何笔记的标签不会生成虚构内涵，仍可依靠标签名称参与推荐。
+
 > [!WARNING]
 > 全库重命名和删除不是事务操作。请在执行前备份 Vault，或使用 Obsidian Git、文件历史等方式确保可以回滚。
 
 ## 🔐 隐私与安全
 
 Controlled Tagger 不提供模型代理服务，也不会把数据发送给作者。
 
-只有当你点击“测试连接”或“为当前笔记推荐标签”时，插件才会连接你配置的 API 服务。推荐请求可能包含：
+当你点击“测试连接”“为当前笔记推荐标签”“立即更新内涵库”，或主动启用定时更新时，插件会连接你配置的 API 服务。推荐请求可能包含：
 
 - API Key 与所选模型 ID；
 - 当前笔记标题；
 - 当前笔记正文的前 20,000 个字符；
 - 受控标签列表和推荐指令。
 
+内涵库更新请求还可能包含：
+
+- 发生变化标签的名称；
+- 每个标签最多 3 篇近期已标注笔记的标题；
+- 每篇样本最多 800 个字符的正文摘要。
+
+样本正文只用于本次模型请求，不会保存在 `data.json`。本地只持久化模型生成的内涵摘要、适用条件、判断边界、样本数量、更新时间和不可逆的变更指纹。
+
 这些数据由你选择的第三方模型服务商处理，请在使用前阅读相应服务商的隐私政策。标签新增、导入、重命名和删除均在本地完成，不会调用模型。
 
 API Key 由 Obsidian 保存在插件目录的 `data.json` 中，属于明文配置。请勿提交该文件，也不要同步到不受信任的设备。本项目不包含遥测、分析、广告或隐藏网络请求。
 
-为了实现标签统计、从 Vault 导入标签以及全库重命名或删除，插件会在本地枚举 Markdown 文件路径并读取 Obsidian 元数据缓存。只有请求当前笔记的标签建议，或执行你已经确认的标签修改时，插件才会读取相应笔记正文；这些 Vault 数据不会发送给插件作者。
+为了实现标签统计、从 Vault 导入标签、内涵库采样以及全库重命名或删除，插件会在本地枚举 Markdown 文件路径并读取 Obsidian 元数据缓存。它只在推荐当前笔记、提炼发生变化的标签内涵，或执行你已经确认的标签修改时读取所需笔记正文；这些 Vault 数据不会发送给插件作者。
 
 ## 🧩 技术结构
 
@@ -158,12 +193,13 @@ API Key 由 Obsidian 保存在插件目录的 `data.json` 中，属于明文配
 | 模型接口 | OpenAI-compatible Chat Completions |
 | 网络请求 | Obsidian `requestUrl` |
 | 属性更新 | Obsidian `processFrontMatter` |
+| 标签内涵缓存 | 本地增量指纹 + `data.json` 持久化摘要 |
 | 构建 | TypeScript + esbuild |
 | 测试 | Vitest + V8 coverage |
 
 ## 🛠️ 开发
 
-插件要求 Obsidian 1.13.0 或更高版本；开发环境要求 Node.js 20 或更高版本。
+插件要求 Obsidian 1.5.0 或更高版本；Obsidian 1.13.0 以上同时支持设置搜索。开发环境要求 Node.js 20 或更高版本。
 
 ```bash
 git clone https://github.com/Yuriyagn/controlled-tagger.git
@@ -177,7 +213,7 @@ npm run check
 npm run build
 ```
 
-GitHub Actions 会在每次推送和 Pull Request 上运行完整检查。推送与 `manifest.json` 完全一致的版本标签（例如 `0.4.1`）后，Release 工作流会构建、生成来源证明并发布 Obsidian 所需文件。
+GitHub Actions 会在每次推送和 Pull Request 上运行完整检查。推送与 `manifest.json` 完全一致的版本标签（例如 `0.5.0`）后，Release 工作流会构建、生成来源证明并发布 Obsidian 所需文件。
 
 ## 🤝 贡献与反馈
 

diff --git a/README_EN.md b/README_EN.md
@@ -40,6 +40,8 @@
 - 🔄 **Vault-wide maintenance** — Rename or delete a tag after reviewing the number of affected notes
 - 🌳 **Nested tags** — Supports Obsidian tags such as `domain/artificial-intelligence`
 - 🛡️ **Local validation** — Unknown model output is discarded before it can modify a note
+- 🧭 **Tag semantic library** — Learns actual meanings, usage conditions, and boundaries from tagged-note examples
+- ⚡ **Incremental cache** — Reuses unchanged semantics with manual or opt-in scheduled refreshes
 - 🚫 **No telemetry** — No analytics, ads, or author-operated backend
 
 ## 📸 Screenshots and workflow
@@ -60,6 +62,16 @@
 | :---: | :---: |
 | ![Tag suggestions](docs/screenshots/tag-suggestions.png) | ![Applied tags](docs/screenshots/applied-tags.png) |
 
+### 4. Build and inspect the tag semantic library
+
+| Status, manual refresh, and schedule | Searchable generated semantics |
+| :---: | :---: |
+| ![Tag semantic library settings](docs/screenshots/tag-semantic-settings.png) | ![Tag semantic library details](docs/screenshots/tag-semantic-library.png) |
+
+### 5. Receive reasons grounded in your Vault's actual tag usage
+
+![AI tag suggestions informed by cached tag semantics](docs/screenshots/semantic-tag-suggestions.png)
+
 ## 📦 Installation
 
 ### Community plugins
@@ -92,9 +104,10 @@ You can also open the [Controlled Tagger directory page](https://community.obsid
 2. Enter an API key, API base URL, and model.
 3. Test the connection.
 4. Open “Manage tags” and import tags from the Vault or add allowed tags.
-5. Open a Markdown note.
-6. Use the ribbon tag button or run “Controlled Tagger: Suggest tags for the current note”.
-7. Select the suggestions you want, then append them or replace the note's frontmatter tags.
+5. Select “Tag semantic library → Update now”, or let the first suggestion initialize it.
+6. Open a Markdown note.
+7. Use the ribbon tag button or run “Controlled Tagger: Suggest tags for the current note”.
+8. Select the suggestions you want, then append them or replace the note's frontmatter tags.
 
 ### Configuration
 
@@ -104,7 +117,9 @@ You can also open the [Controlled Tagger directory page](https://community.obsid
 | API base URL | Base URL of an OpenAI-compatible API | `https://api.siliconflow.cn/v1` |
 | Model | Built-in preset or custom model ID | `Qwen/Qwen3.5-4B` |
 | Request timeout | Maximum wait for a busy model | 90 seconds |
-| Maximum suggestions | Maximum tags returned per note | 3 |
+| Number of suggestions | Desired tags returned per note (1–20) | 3 |
+| Tag semantic library | Inspect status and run an incremental refresh | Initialized on first suggestion |
+| Semantic refresh schedule | Off, daily, weekly, or monthly | Off |
 
 Model availability, pricing, and free tiers are controlled by the provider and may change at any time.
 
@@ -116,25 +131,45 @@ Model availability, pricing, and free tiers are controlled by the provider and m
 - Renaming or deleting a tag updates matching frontmatter and inline tags after confirmation.
 - “Replace current note tags” replaces only the YAML `tags` property; inline tags remain unchanged.
 
+## 🧭 How the tag semantic library works
+
+A short tag name rarely captures how that tag is actually used in a personal knowledge base. The semantic library examines the existing tag-to-note relationships and samples up to three recently modified tagged notes per changed tag. Each sample contains only the note title and an excerpt of up to 800 characters.
+
+The model produces three cached fields for each tag: its core meaning, when to use it, and its classification boundary. Later suggestions receive these cached descriptions instead of rebuilding the library for every note. A local fingerprint based on tag-to-note relationships and file metadata lets unchanged tags skip model requests.
+
+- The first explicit suggestion initializes the library if it does not exist.
+- “Update now” performs an incremental check and processes only changed tags or tags built with a different model.
+- Scheduled refresh is off by default. You can opt into daily, weekly, or monthly background checks.
+- Generated semantics can be inspected and searched from the settings page.
+- A new tag with no tagged-note examples does not receive an invented meaning; it can still participate by name.
+
 > [!WARNING]
 > Vault-wide rename and delete operations are not transactional. Back up your Vault or use a version-history solution before running them.
 
 ## 🔐 Privacy and security
 
 Controlled Tagger does not operate a model proxy and never sends data to the author.
 
-The plugin contacts your configured API only when you test the connection or request suggestions. A suggestion request may contain:
+The plugin contacts your configured API when you test the connection, request suggestions, manually refresh the semantic library, or opt into scheduled semantic refreshes. A suggestion request may contain:
 
 - Your API key and selected model ID;
 - The active note title;
 - Up to the first 20,000 characters of the active note;
 - The controlled tag list and classification instructions.
 
+A semantic-library refresh may also contain:
+
+- The names of changed tags;
+- Up to three recent tagged-note titles per changed tag;
+- Up to 800 characters of note excerpt per sample.
+
+Sample titles and excerpts are used only for that model request and are not persisted. The local `data.json` stores only generated semantic summaries, usage conditions, boundaries, sample counts, timestamps, and irreversible change fingerprints.
+
 This data is processed by the model provider you choose. Review that provider's privacy policy before use. Tag import, creation, rename, and deletion are local operations and do not call a model.
 
 Obsidian stores the API key in the plugin's plaintext `data.json`. Do not commit that file or sync it to untrusted devices. The plugin contains no telemetry, analytics, advertising, or hidden network requests.
 
-To provide tag counts, imports, and Vault-wide rename or deletion, the plugin enumerates Markdown file paths and reads Obsidian's local metadata cache. It reads note contents only for the active suggestion request or for locally confirmed tag updates. Vault data is never sent to the plugin author.
+To provide tag counts, imports, semantic sampling, and Vault-wide rename or deletion, the plugin enumerates Markdown file paths and reads Obsidian's local metadata cache. It reads note content only for an active suggestion, changed-tag semantic samples, or locally confirmed tag updates. Vault data is never sent to the plugin author.
 
 ## 🧩 Tech stack
 
@@ -144,12 +179,13 @@ To provide tag counts, imports, and Vault-wide rename or deletion, the plugin en
 | Model API | OpenAI-compatible Chat Completions |
 | Networking | Obsidian `requestUrl` |
 | Frontmatter updates | Obsidian `processFrontMatter` |
+| Semantic cache | Local incremental fingerprints and summaries in `data.json` |
 | Build | TypeScript + esbuild |
 | Tests | Vitest + V8 coverage |
 
 ## 🛠️ Development
 
-Obsidian 1.13.0 or later is required. Development requires Node.js 20 or later.
+Obsidian 1.5.0 or later is required; Obsidian 1.13.0 and later also provide settings search. Development requires Node.js 20 or later.
 
 ```bash
 git clone https://github.com/Yuriyagn/controlled-tagger.git
@@ -163,7 +199,7 @@ npm run check
 npm run build
 ```
 
-GitHub Actions runs the full check on every push and pull request. Pushing a version tag that exactly matches `manifest.json` (for example `0.4.1`) builds, attests, and publishes the required Obsidian release assets.
+GitHub Actions runs the full check on every push and pull request. Pushing a version tag that exactly matches `manifest.json` (for example `0.5.0`) builds, attests, and publishes the required Obsidian release assets.
 
 ## 🤝 Contributing and feedback