From 7c3054f14aefaa7f577583fae47713230b88e5e3 Mon Sep 17 00:00:00 2001
From: HomeDash Bot <bot@jianfgit.xyz>
Date: Sat, 12 Sep 2026 12:22:01 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=98=8E=E7=A1=AE=20=E5=B8=B8=E7=94=A8?=
 =?UTF-8?q?=E6=9C=8D=E5=8A=A1/=E5=8E=86=E5=8F=B2=E8=AE=BF=E9=97=AE=20?=
 =?UTF-8?q?=E6=98=AF=E7=B3=BB=E7=BB=9F=E7=AE=A1=E7=90=86=E5=88=86=E7=BB=84?=
 =?UTF-8?q?=EF=BC=8C=E7=A6=81=E6=AD=A2=E6=89=8B=E5=B7=A5=E5=8A=A0=E6=9D=A1?=
 =?UTF-8?q?=E7=9B=AE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

用户指出：常用服务应当是按访问频次自动排序取前五，不该手工塞条目。
我部署 it-tools 时正是这么错的（把新项直接写进了 常用服务，污染频次榜）。

- AGENTS.md：写入导航条目示例前加警示（两个系统分组 + navSection 必须指向用户分组
  + 实测教训：塞进常用服务会被下次重建挤掉）
- README：配置接口章节加同样说明
现场已修正：IT Tools 移入「AI & 工具」，路由 navSection 同步改为该分组，
常用服务恢复为 4 项（系统按频次维护）。
---
 AGENTS.md | 7 +++++++
 README.md | 4 ++++
 2 files changed, 11 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index e9a7986..f429ea9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -180,6 +180,13 @@ curl -s -X POST -H "Authorization: Bearer $TOK" "$A/gateway/apply"
 # 导航分组 / 条目
 curl -s -X POST -H "Authorization: Bearer $TOK" -H 'Content-Type: application/json' \
   -d '{"name":"常用服务"}' "$A/section"
+> ⚠️ **两个分组是系统管理的，不要往里手工加条目**：
+> - `常用服务`：按**访问频次**自动取前 5（Gitea 固定置顶），服务端重建
+> - `历史访问`：按浏览器同步的浏览记录重建（安装入口由它自己放在首位）
+>
+> 因此 `navEnabled` 的 `navSection` 必须指向**用户分组**（如 `AI & 工具`、`系统管理`）。
+> 实测教训：把新服务直接塞进 `常用服务` 会污染频次榜，且该条目会被下一次重建挤掉。
+
 # 导航条目是**嵌套形状**（实测：扁平 {"name","url"} 会返回 "title and url required"）：
 #   先查分组下标，再提交 {"sectionIndex":N,"item":{...}}
 IDX=$(curl -s -H "Authorization: Bearer $TOK" "$A/sections" | \
diff --git a/README.md b/README.md
index b44d06c..3f54db9 100644
--- a/README.md
+++ b/README.md
@@ -642,6 +642,10 @@ curl -s http://127.0.0.1:18080/api/schema | jq        # 人读：items + resourc
    echo "$code"
    ```
 
+> **注意 `常用服务` 与 `历史访问` 是系统管理的分组**：前者按访问频次自动取前 5（Gitea 置顶），
+> 后者按浏览记录重建。新增服务要放进用户分组（如 `AI & 工具`）；`navEnabled` 的 `navSection`
+> 若指向 `常用服务`，条目会在下次重建时被挤掉。
+
 **示例：让 agent 一次性把站点改成你要的样子**
 
 ```bash