From 16707bdfabbee671e4b2f47c037c213b5f6f78d1 Mon Sep 17 00:00:00 2001 From: HomeDash Bot Date: Sat, 12 Sep 2026 15:16:57 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=90=8C=E6=AD=A5=E3=80=8C=E5=B8=B8?= =?UTF-8?q?=E7=94=A8=E6=9C=8D=E5=8A=A1=E3=80=8D=E6=96=B0=E6=9C=BA=E5=88=B6?= =?UTF-8?q?=EF=BC=88=E5=AF=BC=E8=88=AA=E9=A1=B9=E7=82=B9=E5=87=BB=E8=AE=A1?= =?UTF-8?q?=E6=95=B0=EF=BC=89=E5=B9=B6=E8=A1=A5=20nav-visit=20=E6=8E=A5?= =?UTF-8?q?=E5=8F=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 审计发现文档仍有旧描述，且新端点完全没写： - README：分组注释/机制说明/系统分组警示/history-server 职责 仍写成泛指的"访问频次"， 容易让人以为常用服务来自浏览器历史。统一改为"导航项点击次数（nav-visits.json）"， 并明确两者数据源互相独立（常用服务不看浏览器历史） - README 接口表 + AGENTS.md §4.2 补 POST /api/history/nav-visit 的可执行示例 - AGENTS.md 已知坑补一条：顺序不像"最常点的"时如何排查 --- AGENTS.md | 8 +++++++- README.md | 10 ++++++---- 2 files changed, 13 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 0ee2a17..99a72a1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -181,7 +181,8 @@ 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（**不置顶任何服务**），服务端重建 +> - `常用服务`：按**导航项点击次数**自动取前 5（**不置顶任何服务**），服务端重建； +> 计数来自 `POST /api/history/nav-visit`（导航页点击自动上报，落盘 `nav-visits.json`），**不使用浏览器历史** > - `历史访问`：按浏览器同步的浏览记录重建（安装入口由它自己放在首位） > > 因此 `navEnabled` 的 `navSection` 必须指向**用户分组**（如 `AI & 工具`、`系统管理`）。 @@ -201,6 +202,10 @@ curl -s -X DELETE -H "Authorization: Bearer $TOK" -H 'Content-Type: application/ > 形状不确定时先取 `GET /api/schema`（§4.1）或读 `admin-server/main.go` 里的处理函数： > 本手册初版就把 `/api/item` 写成了扁平形状，实测被拒——**文档里的示例必须实测过**。 +# 导航项点击计数（「常用服务」排序的唯一依据；前端点击时自动上报，这里用于人工/脚本触发） +curl -s -X POST -H "Authorization: Bearer $TOK" -H 'Content-Type: application/json' \ + -d '{"url":"https://app.example.com/"}' "$A/history/nav-visit" + # 壁纸 / 门户口令 / 历史 curl -s -X POST -H "Authorization: Bearer $TOK" -H 'Content-Type: application/json' -d '{"url":"https://x/bg.jpg"}' "$A/wallpaper" curl -s -X POST -H "Authorization: Bearer $TOK" -H 'Content-Type: application/json' -d '{"username":"admin","password":"<新口令>"}' "$A/portal-auth" @@ -308,6 +313,7 @@ docker start navi | 脚本报 `HOST: unbound variable` | 必填校验写在赋值之前 + `set -u` | 升级脚本（已修）；或先给变量赋值再校验 | | 容器名叫 `navi-next` | 切换中途中断 | 验收通过后 `docker rename navi-next navi` | | `no space left on device` | `/tmp` 是 tmpfs，构建包 ~222M | 构建前 `rm -rf /tmp/homedash-*` | +| `常用服务` 顺序不像"最常点的" | 它只认导航项点击计数，不认浏览器历史 | 用上面的 nav-visit 接口触发/查看；计数文件 `nav-visits.json` | | 照抄验收命令却全是 000 | 文档里的端口写死 3080，而部署用了别的端口 | 用 `PORT=${NAVI_ENTRY_PORT:-3080}`（本手册已改） | | 脱敏自检把文档自己判为"命中" | 自检命令里写了真实值当模式 | 用长度/字符集特征检测，并排除文档自身（本手册已改） | | 部署脚本用 `bash -s` 传参不生效 | 远端 heredoc 是引号形式，不展开本地变量 | 在 ssh 命令行显式传（脚本已处理） | diff --git a/README.md b/README.md index e152917..2eb7e7a 100644 --- a/README.md +++ b/README.md @@ -130,7 +130,7 @@ appConfig: openingMethod: newtab sections: - - name: 常用服务 # 按访问频次自动排序 + - name: 常用服务 # 系统分组：按「导航项点击次数」取前 5（不置顶） icon: fas fa-star collapsed: false items: @@ -209,7 +209,8 @@ icon: fas fa-star # Font Awesome - 每 30 秒检查本地队列，**仅在有新数据时 POST** - 搜索引擎 URL 在本地过滤，不上传 -- 「常用服务」和「历史访问」按总访问频次自动排序 +- 「常用服务」按**导航项点击次数**（`nav-visits.json`）自动取前 5；「历史访问」按浏览器同步的浏览记录重建。 + 两者数据源互相独立：**常用服务不看浏览器历史**（站外浏览再多也不会影响它） - 历史条目的图标由服务端自动抓取并缓存（见下） ### 历史条目的站点图标 @@ -617,6 +618,7 @@ curl -s http://127.0.0.1:18080/api/schema | jq # 人读：items + resourc | 壁纸 | `POST /api/wallpaper` | | 门户口令 | `POST /api/portal-auth` | | 历史记录 | `DELETE /api/history/item?url=…`、`DELETE /api/history` | +| 导航项点击计数 | `POST /api/history/nav-visit` `{"url":"https://…"}`（导航页点击时由前端自动上报；「常用服务」据此排序） | | 图标上传 | `POST /api/icon`（multipart，字段 `file`） | | 重建导航分区 | `POST /api/reload` | @@ -642,7 +644,7 @@ curl -s http://127.0.0.1:18080/api/schema | jq # 人读：items + resourc echo "$code" ``` -> **注意 `常用服务` 与 `历史访问` 是系统管理的分组**：前者按访问频次自动取前 5（**不置顶任何服务**）， +> **注意 `常用服务` 与 `历史访问` 是系统管理的分组**：前者按**导航项点击次数**自动取前 5（**不置顶任何服务**）， > 后者按浏览记录重建。新增服务要放进用户分组（如 `AI & 工具`）；`navEnabled` 的 `navSection` > 若指向 `常用服务`，条目会在下次重建时被挤掉。 @@ -672,7 +674,7 @@ curl -s -X POST -H "Authorization: Bearer $TOK" "$A/api/gateway/apply" | `conf.example.yml` | 首次启动生成 `conf.yml` 的模板（**sections 为空**，分组由后台创建） | | `admin/index.html` | 管理后台单页（站点信息 / 分组 / 服务 / 图标 / 壁纸 / 历史） | | `admin-server/` | Go：站点信息、分组与服务增删改、图标与壁纸上传、历史转发、可内嵌性探测 | -| `history-server/` | Go：浏览历史接收与排序、favicon 抓取、按访问频次重建 Dashy 分组 | +| `history-server/` | Go：浏览历史接收与排序、favicon 抓取、**导航项点击计数**（`/api/history/nav-visit`）、重建 Dashy 分组 | | `web/navi.js` / `web/navi.css` | 门户表现层：搜索球、视图切换、管理入口、收边、工作空间内嵌、页脚 | | `web/patch-index.py` | 幂等地把 `navi.css` / `navi.js` 注入 Dashy 的 index.html | | `web/extension/install.html` | 插件安装引导页（含同步令牌展示） |