@lyra_wang/chrome-frequent-pages 0.0.0-stage → 0.5.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wang Ying (LyraWang)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,189 @@
-# Temporary Holding Version
+# chrome-frequent-pages
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**把 Chrome 里高频访问的网页收录进飞书「常用网页」表，并生成可导入 Chrome 的书签 HTML。**
+
+只读 Chrome History（复制到临时目录后再读，不锁 Chrome），归一化 URL 后按
+「域名 + 路径」聚合访问次数，过滤登录页 / 搜索页 / 本地地址。
+
+## 安装（npm，推荐）
+
+```bash
+npm install -g --prefix ~/.local @lyra_wang/chrome-frequent-pages
+chrome-frequent-pages --dry-run
+```
+
+## 用法（仓库目录直接跑）
+
+```bash
+# 配置（默认 ~/.config/chrome-frequent-pages/config.json）
+cp config.example.json ~/.config/chrome-frequent-pages/config.json
+
+python3 main.py --dry-run                     # 只看结果
+python3 main.py --write                       # 写/更新飞书表
+python3 main.py --html ~/Desktop/常用网页.html  # 导出可导入 Charter 的书签 HTML
+python3 main.py --days 30 --min-visits 5      # 临时调窗口与阈值
+```
+
+## 统计窗口
+
+`days` 决定"最近多少天内访问过的页面才参与统计"：
+
+| 值 | 效果 |
+|---|---|
+| 7 | 只看最近一周（最灵敏，候选最少）|
+| **10** | **当前设置** |
+| 30 | 一个月 |
+| 90 | 一个季度（旧默认）|
+
+改法：编辑 `~/.config/chrome-frequent-pages/config.json` 的 `days`，
+或临时用 `python3 main.py --days 7 --dry-run`。
+
+## 配置字段
+
+| 字段 | 说明 |
+|---|---|
+| `chrome_profile_dir` | Chrome profile 目录（默认 `~/Library/Application Support/Google/Chrome/Default`）|
+| `days` | 统计窗口（可配置；当前设为 **10 天**）|
+| `min_visits` | 最少访问次数（当前设为 **5**）|
+| `limit` | 最多收录条数（默认 60，`0` = 不限）|
+| `exclude_hosts` | 排除的域名（邮箱、登录等）|
+| `base_token` / `table_id` | 目标飞书表坐标 |
+| `identity` | `user`（默认）或 `bot` |
+| `ignored_urls_file` | 忽略清单（一行一个 URL）；表里删掉的行会写进这里，避免下次重新收录 |
+| `rules.drop_hosts` | 整站丢弃（娱乐视频站等）|
+| `rules.drop_url_contains` | URL 含指定片段即丢弃（开发者后台、PR/Releases、OAuth、支付等）|
+| `rules.root_only_hosts` | 只保留站点根域名（如 `github.com` 只留首页）|
+| `rules.drop_titles` | 标题命中即丢（失效/无权限文档）|
+| `rules.keep_urls` | 白名单，优先级最高 |
+| `rules.one_per_host` | 每个域名只保留访问最多的一页 |
+
+## 规则（0.4.0：根域名级）
+
+```
+最近 10 天 → 按「根域名」加总访问次数 → 超过 5 次 → 只排除影视娱乐与本地页 → 一行一个根域名
+```
+
+| 项 | 当前值 |
+|---|---|
+| `days` | 10 |
+| `min_visits` | 5（**严格超过**，即 6 次起）|
+| 统计口径 | 该根域名下**所有页面**的访问次数之和（不是单页）|
+| 协议 | 只统计 `https://` |
+| 排除 | 影视娱乐（yfsp / iyf / yifan / tv.cctv）+ 本地页（localhost / 127.0.0.1 / file）|
+| 输出 | `https://<根域名>/` 一行；标题取 `domain_labels`，缺省用域名 |
+| 黑名单 | 无（只有影视娱乐与本地页被排除）|
+
+## 表结构（域名级）
+
+0.3.1 起写入适配「一行一个域名」的表：
+
+| 字段 | 写入内容 |
+|---|---|
+| `域名` | host（判重键）|
+| `标题` | 取 `domain_labels` 里的中文说明；没有配置时退回域名 |
+| `访问次数` | 该域名所有页面的访问次数之和 |
+| `状态` | `已收录` |
+
+`收录时间`、`分类` 由表自己维护，脚本不写。
+
+## 写入策略
+
+- 以 `URL` 去重：已存在则更新访问次数/最近访问，不存在才新建；
+- 同一页面不同 query/fragment 会归一化成同一条（飞书 `/base/<token>`、`/wiki/<token>` 按 token 聚合）；
+- 状态默认「已收录」，方便你之后标「已加入书签」或「忽略」；
+- 忽略清单：`~/.config/chrome-frequent-pages/ignored_urls.txt`，一行一个 URL，命中即跳过；
+  在表里删掉的页面记得同步进这个文件（或让工具写）。
+
+## 书签替换（安全流程）
+
+1. 先备份 Chrome 当前书签：
+   `cp "~/Library/Application Support/Google/Chrome/Default/Bookmarks" ~/Desktop/Bookmarks-backup-$(date +%F).json`
+2. 跑 `--html` 生成新书签 HTML；
+3. Chrome → 书签管理器 → 删除旧书签 → 导入 HTML；
+4. 不建议直接改 `Bookmarks` JSON：Chrome 运行时会覆盖，写坏会丢全部书签。
+
+## 定时（可选）
+
+```bash
+bash install.sh   # 生成 ~/.local/bin/chrome-frequent-pages 并注册每周一 09:30 的 launchd 任务
+```
+
+## 中文标签（domain_labels）
+
+```json
+"domain_labels": {
+  "meeting.bamamei.online": "组队会议分析",
+  "github.com": "GitHub"
+}
+```
+
+表里的 `标题` 列与导出的书签名称都优先用这里的文字；没配置的域名退回域名本身。
+
+## 书签：按分类子文件夹导出（0.4.1）
+
+```bash
+python3 main.py --bookmarks-from-table ~/Desktop/常用网页书签.html
+```
+
+按表里的 `分类` 列生成**同级**文件夹（都在书签栏一层）：
+
+```
+书签栏
+├── 常用网页   （全部 27 条，平铺）
+├── 工作       （9 条）
+├── 学习       （3 条）
+└── 工具       （15 条）
+```
+
+没填分类的域名会进「其他」。
+
+## 书签：按「域名」导出
+
+```bash
+python3 main.py --bookmarks-from-table ~/Desktop/常用网页书签.html
+```
+
+读取飞书表每个唯一「域名」，生成 `https://<域名>/` 书签 HTML（Chrome 书签管理器导入）。
+
+---
+
+## 开机触发（每周一次）+ 投递到收件箱
+
+数据在本机 Chrome 里，所以执行必须在 Mac 上。定时不用时钟，用**开机作为触发点**：
+
+- `run-if-due.sh`：launchd 的 `RunAtLoad` 调用；读状态文件判断本周是否已跑，
+  没跑则执行 `chrome-frequent-pages --write`，跑完写状态（失败不写，下次开机重试）。
+- `inbox-deliver-mac.py`：把结果写进飞书「任务收件箱」，DSH 收件箱面板会显示为「待读」。
+- `table_snapshot.py`：执行前后各取一次「常用网页」表快照，diff 出本周**新增了哪些页面**，
+  摘要里带上「标题（域名）→ 书签「分类」」；未分类的页面导出书签时归入「其他」。
+
+### 安装
+
+```bash
+npm i -g @lyra_wang/chrome-frequent-pages@0.5.2   # 或 npm i -g file:$PWD
+bash "$(dirname "$(readlink -f "$(command -v chrome-frequent-pages)")")/../install.sh"
+```
+
+`install.sh` 会把 `main.py` / `run-if-due.sh` / `inbox-deliver-mac.py` / `table_snapshot.py`
+复制到 `~/.local/share/chrome-frequent-pages/`，并注册 `RunAtLoad` 的 LaunchAgent（无定时时刻）。
+
+### 必需的 macOS 权限（否则读不到 Chrome 历史）
+
+「完全磁盘访问权限」里需要加入三项（后台进程按二进制逐个鉴权）：
+
+| 加入项 | 作用 |
+|---|---|
+| `/bin/bash` | 启动脚本 |
+| `/usr/local/bin/node` | npm CLI 需要 |
+| `/usr/bin/python3` | 实际读 History 的进程 |
+
+### 行为
+
+| 场景 | 结果 |
+|---|---|
+| 本周第一次开机/登录 | 执行一次 |
+| 同周再次开机 | 状态文件命中，跳过 |
+| 执行失败 | 不写状态，下次开机重试；失败结果也会写收件箱 |
+
+状态文件：`~/.config/chrome-frequent-pages/last-run.json`（`{"week":"2026-43","at":"..."}`）
+日志：`~/.config/chrome-frequent-pages/run-if-due.log`

package/bin/cli.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// npm bin shim: run the Python collector that ships in this package.
+import { spawn } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const script = join(here, '..', 'main.py');
+const child = spawn('/usr/bin/python3', [script, ...process.argv.slice(2)], { stdio: 'inherit' });
+child.on('exit', (code, signal) => {
+  if (signal) process.kill(process.pid, signal);
+  else process.exit(code ?? 0);
+});

package/config.example.json

@@ -0,0 +1,35 @@
+{
+  "chrome_profile_dir": "~/Library/Application Support/Google/Chrome/Default",
+  "days": 10,
+  "min_visits": 5,
+  "limit": 60,
+  "exclude_hosts": [
+    "mail.google.com",
+    "accounts.google.com",
+    "localhost",
+    "127.0.0.1"
+  ],
+  "base_token": "<feishu-base-token>",
+  "table_id": "<table-id>",
+  "identity": "user",
+  "rules": {
+    "drop_hosts": [
+      "yfsp.tv",
+      "iyf.tv",
+      "yifan.tv",
+      "tv.cctv.com"
+    ],
+    "drop_url_contains": [],
+    "root_only_hosts": [],
+    "drop_titles": [],
+    "keep_urls": [],
+    "one_per_host": false
+  },
+  "ignored_urls_file": "",
+  "domain_labels": {
+    "meeting.bamamei.online": "组队会议分析",
+    "eos.douyin.com": "抖音生活服务 · 直播",
+    "github.com": "GitHub",
+    "platform.deepseek.com": "DeepSeek 开放平台"
+  }
+}

package/inbox-deliver-mac.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""把一条任务结果写进飞书「任务收件箱」（Mac 侧，使用本机 lark-cli 用户身份）。
+
+用法:
+  inbox-deliver-mac.py --task chrome-frequent-pages --result 成功 --summary "本周新增 3 条"
+"""
+import argparse, json, subprocess, sys
+from datetime import datetime
+
+BASE = "NeujbbOfcaPEvMsPIxscaJImn9d"
+INBOX = "tbl9LghPBTjFLH4N"
+TASKS = "tbl4k7ggY1paqoUn"
+LARK = "lark-cli"
+
+def lark(args):
+    cmd = [LARK] + args + ["--as", "user", "--format", "json"]
+    res = subprocess.run(cmd, capture_output=True, text=True, timeout=90)
+    try:
+        payload = json.loads(res.stdout or "{}")
+    except Exception:
+        payload = {}
+    if payload.get("ok") is False:
+        raise SystemExit("lark-cli failed: " + json.dumps(payload.get("error", payload), ensure_ascii=False))
+    if res.returncode != 0:
+        raise SystemExit("lark-cli exited %s: %s" % (res.returncode, (res.stderr or "")[:300]))
+    return payload
+
+def task_record_id(name):
+    payload = lark(["base", "+record-list", "--base-token", BASE, "--table-id", TASKS, "--limit", "200"])
+    meta = payload.get("data") or {}
+    fields = meta.get("fields") or []
+    rows = meta.get("data") or []
+    ids = meta.get("record_id_list") or []
+    if "任务名称" not in fields:
+        return ""
+    idx = fields.index("任务名称")
+    for rid, row in zip(ids, rows):
+        if str(row[idx]).strip() == name:
+            return str(rid)
+    return ""
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--task", required=True)
+    ap.add_argument("--result", required=True, choices=["成功", "失败", "超时"])
+    ap.add_argument("--summary", required=True)
+    args = ap.parse_args()
+    summary = args.summary.strip()
+    if len(summary) > 300:
+        summary = summary[:299] + "…"
+    record = {
+        "结果摘要": summary,
+        "结果": [args.result],
+        "状态": ["未读"],
+        "执行任务": int(datetime.now().timestamp() * 1000),
+    }
+    rid = task_record_id(args.task)
+    if rid:
+        record["关联任务"] = [rid]
+    lark(["base", "+record-batch-create", "--base-token", BASE, "--table-id", INBOX,
+          "--json", json.dumps({"create_records": [record]}, ensure_ascii=False)])
+    print(json.dumps({"ok": True, "task": args.task, "linked": bool(rid)}, ensure_ascii=False))
+
+if __name__ == "__main__":
+    main()

package/install.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+set -eu
+HERE="$(cd "$(dirname "$0")" && pwd)"
+BIN_DIR="$HOME/.local/bin"
+DATA_DIR="$HOME/.local/share/chrome-frequent-pages"
+CONF_DIR="$HOME/.config/chrome-frequent-pages"
+mkdir -p "$BIN_DIR" "$DATA_DIR" "$CONF_DIR"
+
+# launchd 读不了 ~/Documents（TCC），脚本要放到不受保护的位置
+cp "$HERE/main.py" "$HERE/run-if-due.sh" "$HERE/inbox-deliver-mac.py" "$HERE/table_snapshot.py" "$DATA_DIR/"
+chmod +x "$DATA_DIR/main.py" "$DATA_DIR/run-if-due.sh" "$DATA_DIR/inbox-deliver-mac.py" "$DATA_DIR/table_snapshot.py"
+ln -sf "$DATA_DIR/main.py" "$BIN_DIR/chrome-frequent-pages"
+[ -f "$CONF_DIR/config.json" ] || cp "$HERE/config.example.json" "$CONF_DIR/config.json"
+
+PLIST="$HOME/Library/LaunchAgents/com.lyrawang.chrome-frequent-pages.plist"
+cat > "$PLIST" <<EOF
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>com.lyrawang.chrome-frequent-pages</string>
+  <key>ProgramArguments</key><array>
+    <string>/bin/bash</string><string>$DATA_DIR/run-if-due.sh</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>StandardOutPath</key><string>$CONF_DIR/launchd.out.log</string>
+  <key>StandardErrorPath</key><string>$CONF_DIR/launchd.err.log</string>
+  <key>ProcessType</key><string>Background</string>
+</dict></plist>
+EOF
+launchctl bootout "gui/$(id -u)/com.lyrawang.chrome-frequent-pages" 2>/dev/null || true
+launchctl bootstrap "gui/$(id -u)" "$PLIST" 2>/dev/null || launchctl load "$PLIST" 2>/dev/null || true
+echo "✓ 已安装：~/.local/bin/chrome-frequent-pages"
+echo "✓ 已注册开机触发（launchd RunAtLoad，每周首次开机跑一次）"
+cat <<'NOTE'
+
+⚠️ 首次安装需在「系统设置 → 隐私与安全性 → 完全磁盘访问权限」中加入：
+   /bin/bash、/usr/local/bin/node、/usr/bin/python3
+   否则读不到 Chrome History（会写一条「失败」摘要到收件箱）。
+NOTE

package/main.py

@@ -0,0 +1,417 @@
+#!/usr/bin/env python3
+"""把 Chrome 的高频访问页面收录进飞书「常用网页」表，并可导出书签 HTML。
+
+只读 Chrome History（复制到临时目录后再读，不锁 Chrome），归一化 URL 后
+按域名 + 路径聚合访问次数，过滤噪声与隐私站点。
+
+用法：
+    python3 main.py --dry-run            # 只看结果，不写表
+    python3 main.py --write              # 写/更新飞书表
+    python3 main.py --html ~/Desktop/常用网页.html   # 导出可导入 Chrome 的书签 HTML
+"""
+import argparse
+import html
+import json
+import os
+import shutil
+import sqlite3
+import subprocess
+import sys
+import tempfile
+import urllib.parse
+from collections import defaultdict
+from datetime import datetime, timedelta, timezone
+
+HOME = os.path.expanduser("~")
+CONFIG_PATH = os.environ.get("CHROME_PAGES_CONFIG") or os.path.join(HOME, ".config", "chrome-frequent-pages", "config.json")
+DEFAULT_CONFIG = {
+    "chrome_profile_dir": os.path.join(HOME, "Library", "Application Support", "Google", "Chrome", "Default"),
+    "days": 90,
+    "min_visits": 8,
+    "limit": 60,
+    "exclude_hosts": ["mail.google.com", "accounts.google.com", "localhost", "127.0.0.1"],
+    "base_token": "",
+    "table_id": "",
+    "identity": "user",
+    "ignored_urls_file": os.path.join(HOME, ".config", "chrome-frequent-pages", "ignored_urls.txt"),
+    "domain_labels": {},
+    "rules": {
+        # 只保留一条：娱乐影视整站丢弃；其余精细规则已按需求移除
+        "drop_hosts": ["yfsp.tv", "iyf.tv", "yifan.tv", "tv.cctv.com"],
+        "drop_url_contains": [],
+        "root_only_hosts": [],
+        "drop_titles": [],
+        "keep_urls": [],
+        "one_per_host": True,
+    },
+}
+
+# chrome time: microseconds since 1601-01-01
+CHROME_EPOCH_OFFSET = 11644473600
+
+
+def load_config():
+    cfg = dict(DEFAULT_CONFIG)
+    if os.path.exists(CONFIG_PATH):
+        with open(CONFIG_PATH, encoding="utf-8") as fh:
+            cfg.update(json.load(fh))
+    else:
+        print(f"[提示] 没有配置文件，使用默认值；可用 CHROME_PAGES_CONFIG 或 {CONFIG_PATH} 覆盖", file=sys.stderr)
+    for key in ("chrome_profile_dir",):
+        if isinstance(cfg.get(key), str):
+            cfg[key] = os.path.expanduser(cfg[key])
+    return cfg
+
+
+def copy_history(profile_dir):
+    if not os.path.isdir(profile_dir):
+        raise SystemExit(f"找不到 Chrome profile：{profile_dir}")
+    tmp = tempfile.mkdtemp(prefix="chrome-history-")
+    for name in ("History", "History-wal", "History-shm"):
+        src = os.path.join(profile_dir, name)
+        if os.path.exists(src):
+            shutil.copy2(src, os.path.join(tmp, name))
+    target = os.path.join(tmp, "History")
+    if not os.path.exists(target):
+        raise SystemExit("复制 History 失败")
+    return tmp, target
+
+
+def normalize(url):
+    parsed = urllib.parse.urlsplit(url)
+    host = (parsed.hostname or "").lower()
+    if host.startswith("www."):
+        host = host[4:]
+    path = parsed.path.rstrip("/")
+    # 飞书文档/表格按 token 聚合：只认路径开头的 /base/<token> 之类，
+    # 避免把 open.feishu.cn/document/.../docs/bitable-v1 这种开发文档误折叠。
+    import re as _re
+    match = _re.match(r"^/(base|wiki|docx|sheets|docs|mindnote|slides)/([A-Za-z0-9]+)", path)
+    if match:
+        return host, f"/{match.group(1)}/{match.group(2)}"
+    return host, path or "/"
+
+
+def is_noise(url, host, exclude_hosts):
+    # 只看 https；http、file://、localhost 等本地页面一律不看
+    if not url.startswith("https://"):
+        return True
+    if not host:
+        return True
+    if host in exclude_hosts:
+        return True
+    low = url.lower()
+    for bad in ("chrome://", "file://", "chrome-extension://", "/search?q=", "login", "signin", "accounts."):
+        if bad in low:
+            return True
+    return False
+
+
+def load_ignored(cfg):
+    path = cfg.get("ignored_urls_file") or ""
+    if not path:
+        return set()
+    path = os.path.expanduser(path)
+    if not os.path.exists(path):
+        return set()
+    with open(path, encoding="utf-8") as fh:
+        return {line.strip() for line in fh if line.strip()}
+
+
+def apply_rules(url, host, title, rules):
+    """Return None to drop, or the url to keep (root_only may rewrite it)."""
+    keep_urls = set(rules.get("keep_urls") or [])
+    if url in keep_urls:
+        return url
+    low = url.lower()
+    for needle in (rules.get("drop_url_contains") or []):
+        if needle.lower() in low:
+            return None
+    for dropped in (rules.get("drop_hosts") or []):
+        if host == dropped.lower() or host.endswith("." + dropped.lower()):
+            return None
+    clean_title = (title or "").strip()
+    for dead in (rules.get("drop_titles") or []):
+        if clean_title == dead:
+            return None
+    root_only = {h.lower() for h in (rules.get("root_only_hosts") or [])}
+    if host in root_only:
+        from urllib.parse import urlsplit
+        path = urlsplit(url).path or "/"
+        if path.rstrip("/") != "":
+            return None
+        return "https://" + host + "/"
+    return url
+
+
+def collect(cfg):
+    ignored = load_ignored(cfg)
+    rules = cfg.get("rules") or {}
+    tmp, db = copy_history(cfg["chrome_profile_dir"])
+    try:
+        conn = sqlite3.connect(f"file:{db}?mode=ro", uri=True)
+        cutoff_us = int((datetime.now().timestamp() - cfg["days"] * 86400 + CHROME_EPOCH_OFFSET) * 1_000_000)
+        rows = conn.execute(
+            "SELECT url, title, visit_count, last_visit_time FROM urls WHERE last_visit_time > ? AND url LIKE 'http%'",
+            (cutoff_us,),
+        ).fetchall()
+        conn.close()
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+
+    # 按根域名聚合：访问次数 = 该域名下所有页面之和
+    aggregated = {}
+    for url, title, visits, last_us in rows:
+        host, path = normalize(url)
+        if is_noise(url, host, set(cfg["exclude_hosts"])):
+            continue
+        kept = apply_rules(url, host, title, rules)
+        if kept is None:
+            continue
+        key = host
+        last_ts = last_us / 1_000_000 - CHROME_EPOCH_OFFSET
+        entry = aggregated.get(key)
+        if entry is None:
+            aggregated[key] = {
+                "key": key,
+                # 输出根域名，不带路径
+                "url": f"https://{host}/",
+                "title": (title or "").strip(),
+                "host": host,
+                "visits": visits,
+                "last": last_ts,
+            }
+        else:
+            entry["visits"] += visits
+            if last_ts > entry["last"]:
+                entry["last"] = last_ts
+            if not entry["title"] and title:
+                entry["title"] = title.strip()
+
+    # 规则：根域名访问次数「超过」min_visits（严格大于）
+    items = [e for e in aggregated.values() if e["visits"] > cfg["min_visits"] and e["url"] not in ignored]
+    items.sort(key=lambda e: (e["visits"], e["last"]), reverse=True)
+    if False and rules.get("one_per_host"):
+        seen_hosts = set()
+        collapsed = []
+        for item in items:
+            if item["host"] in seen_hosts:
+                continue
+            seen_hosts.add(item["host"])
+            collapsed.append(item)
+        items = collapsed
+    if cfg["limit"]:
+        items = items[: cfg["limit"]]
+    labels = cfg.get("domain_labels") or {}
+    for item in items:
+        item["last_iso"] = datetime.fromtimestamp(item["last"]).strftime("%Y-%m-%d %H:%M")
+        item["title"] = labels.get(item["host"]) or item["host"]
+    return items
+
+
+def lark(args):
+    result = subprocess.run(["lark-cli"] + args + ["--as", "user", "--format", "json"], capture_output=True, text=True, timeout=120)
+    if result.returncode != 0:
+        raise SystemExit("lark-cli 失败：" + (result.stderr or result.stdout).strip()[:400])
+    payload = json.loads(result.stdout or "{}")
+    if payload.get("ok") is False:
+        err = payload.get("error") or {}
+        raise SystemExit("lark-cli 返回失败：" + str(err.get("message") or err)[:400])
+    return payload
+
+
+def existing_domains(cfg):
+    # 表结构是「一行一个域名」；读失败必须中止，避免重复插入。
+    data = lark(["base", "+record-list", "--base-token", cfg["base_token"], "--table-id", cfg["table_id"], "--limit", "200"])
+    meta = data.get("data") or {}
+    cols = meta.get("fields") or []
+    rows = meta.get("data") or []
+    ids = meta.get("record_id_list") or []
+    if "域名" not in cols:
+        raise SystemExit("表里没有「域名」列；请检查表结构")
+    idx = {name: i for i, name in enumerate(cols)}
+    out = {}
+    for rid, row in zip(ids, rows):
+        host = str(row[idx["域名"]] or "").strip()
+        if host:
+            out[host] = rid
+    return out
+
+
+def aggregate_by_host(items, labels=None):
+    """把页面级结果压成域名级：访问次数求和，标题用中文标签（缺省退回域名）。"""
+    labels = labels or {}
+    grouped = {}
+    for item in items:
+        host = item["host"]
+        rec = grouped.get(host)
+        if rec is None:
+            grouped[host] = {
+                "域名": host,
+                "访问次数": item["visits"],
+                "标题": labels.get(host) or host,
+                "_top": item["visits"],
+            }
+        else:
+            rec["访问次数"] += item["visits"]
+            if item["visits"] > rec["_top"]:
+                rec["_top"] = item["visits"]
+                rec["标题"] = labels.get(host) or host
+    rows = sorted(grouped.values(), key=lambda r: r["访问次数"], reverse=True)
+    for row in rows:
+        row.pop("_top", None)
+    return rows
+
+
+def write_table(cfg, items):
+    if not cfg["base_token"] or not cfg["table_id"]:
+        raise SystemExit("配置里缺 base_token / table_id")
+    known = existing_domains(cfg)
+    create, update = [], []
+    for row in aggregate_by_host(items, cfg.get("domain_labels") or {}):
+        record = {
+            "域名": row["域名"],
+            "标题": row["标题"],
+            "访问次数": row["访问次数"],
+            "状态": ["已收录"],
+        }
+        if row["域名"] in known:
+            update.append((known[row["域名"]], record))
+        else:
+            create.append(record)
+
+    if create:
+        lark(["base", "+record-batch-create", "--base-token", cfg["base_token"], "--table-id", cfg["table_id"],
+              "--json", json.dumps({"create_records": create}, ensure_ascii=False)])
+    for record_id, record in update:
+        lark(["base", "+record-upsert", "--base-token", cfg["base_token"], "--table-id", cfg["table_id"],
+              "--record-id", record_id, "--json", json.dumps(record, ensure_ascii=False)])
+    return len(create), len(update)
+
+
+CATEGORY_ORDER = ["工作", "学习", "工具", "内容", "其他"]
+
+
+def bookmarks_from_table(cfg, path):
+    """按飞书表导出书签：常用网页/<分类>/<域名书签>。"""
+    data = lark(["base", "+record-list", "--base-token", cfg["base_token"], "--table-id", cfg["table_id"], "--limit", "200"])
+    meta = data.get("data") or {}
+    cols = meta.get("fields") or []
+    rows = meta.get("data") or []
+    if "域名" not in cols:
+        raise SystemExit("表里没有「域名」列")
+    idx = {name: i for i, name in enumerate(cols)}
+    labels = cfg.get("domain_labels") or {}
+    groups = {}
+    for row in rows:
+        host = str(row[idx["域名"]] or "").strip()
+        if not host:
+            continue
+        cat = "其他"
+        if "分类" in idx:
+            raw = row[idx["分类"]]
+            if isinstance(raw, list) and raw:
+                cat = str(raw[0])
+            elif isinstance(raw, str) and raw.strip():
+                cat = raw.strip()
+        groups.setdefault(cat, []).append({
+            "host": host,
+            "name": str(row[idx["标题"]]).strip() if "标题" in idx and row[idx["标题"]] else labels.get(host) or host,
+        })
+
+    lines = [
+        "<!DOCTYPE NETSCAPE-Bookmark-file-1>",
+        '<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8">',
+        "<TITLE>Bookmarks</TITLE>",
+        "<H1>Bookmarks</H1>",
+        "<DL><p>",
+    ]
+    ordered = [c for c in CATEGORY_ORDER if c in groups] + sorted(c for c in groups if c not in CATEGORY_ORDER)
+
+    def emit_folder(name, entries):
+        lines.append(f"    <DT><H3>{html.escape(name)}</H3>")
+        lines.append("    <DL><p>")
+        for entry in sorted(entries, key=lambda e: e["name"]):
+            lines.append(f'        <DT><A HREF="https://{html.escape(entry["host"])}/">{html.escape(entry["name"])}</A>')
+        lines.append("    </DL><p>")
+
+    # 同级结构：常用网页（全部） + 各分类文件夹，都在书签栏同一层
+    emit_folder("常用网页", [e for cat in ordered for e in groups[cat]])
+    for cat in ordered:
+        emit_folder(cat, groups[cat])
+    lines.append("</DL><p>")
+    with open(os.path.expanduser(path), "w", encoding="utf-8") as fh:
+        fh.write("\n".join(lines) + "\n")
+    return ordered, groups
+
+
+def write_html(items, path):
+    lines = [
+        "<!DOCTYPE NETSCAPE-Bookmark-file-1>",
+        '<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8">',
+        "<TITLE>Bookmarks</TITLE>",
+        "<H1>Bookmarks</H1>",
+        "<DL><p>",
+        '    <DT><H3>常用网页（chrome-frequent-pages）</H3>',
+        "    <DL><p>",
+    ]
+    for item in items:
+        title = html.escape(item["title"] or item["host"])
+        lines.append(f'        <DT><A HREF="{html.escape(item["url"])}">{title}</A>')
+    lines += ["    </DL><p>", "</DL><p>"]
+    with open(os.path.expanduser(path), "w", encoding="utf-8") as fh:
+        fh.write("\n".join(lines) + "\n")
+
+
+def print_table(items):
+    print(f"{'访问':>6}  {'最近访问':<16}  标题 / URL")
+    print("-" * 78)
+    for item in items:
+        print(f"{item['visits']:>6}  {item['last_iso']:<16}  {item['title'][:30]}")
+        print(f"{'':>6}  {'':<16}  {item['url']}")
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--dry-run", action="store_true", help="只打印结果")
+    parser.add_argument("--write", action="store_true", help="写入飞书表")
+    parser.add_argument("--html", metavar="PATH", help="导出可导入 Chrome 的书签 HTML（按页面链接）")
+    parser.add_argument("--bookmarks-from-table", metavar="PATH", help="按飞书表的「域名」列导出书签 HTML")
+    parser.add_argument("--limit", type=int)
+    parser.add_argument("--days", type=int)
+    parser.add_argument("--min-visits", type=int)
+    args = parser.parse_args()
+
+    cfg = load_config()
+    if args.bookmarks_from_table:
+        ordered, groups = bookmarks_from_table(cfg, args.bookmarks_from_table)
+        total = sum(len(v) for v in groups.values())
+        print(f"已导出分类书签：{os.path.expanduser(args.bookmarks_from_table)}（{total} 个域名 / {len(ordered)} 个分类）")
+        for cat in ordered:
+            print(f"  [{cat}]")
+            for entry in sorted(groups[cat], key=lambda e: e["name"]):
+                print("    -", entry["name"], "->", "https://" + entry["host"] + "/")
+        return 0
+    for key in ("limit", "days", "min_visits"):
+        if getattr(args, key) is not None:
+            cfg[key] = getattr(args, key)
+
+    items = collect(cfg)
+    if not items:
+        print("没有满足条件的页面（可调低 --min-visits 或调大 --days）")
+        return 0
+    print(f"共 {len(items)} 个高频页面（窗口 {cfg['days']} 天，最少 {cfg['min_visits']} 次访问）\n")
+    print_table(items)
+    if args.html:
+        write_html(items, args.html)
+        print(f"\n已导出书签 HTML：{os.path.expanduser(args.html)}")
+    if args.write:
+        created, updated = write_table(cfg, items)
+        print(f"\n飞书写入完成：新增 {created} 条，更新 {updated} 条")
+    if not args.write and not args.html:
+        print("\n（dry-run：没有写表；加 --write 写飞书，--html <路径> 导出书签）")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@lyra_wang/chrome-frequent-pages",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.2",
+  "description": "Chrome 高频网页 → 飞书「常用网页」表 + 按分类导出 Chrome 书签（根域名 / 10 天 / >5 次）",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "chrome",
+    "history",
+    "bookmarks",
+    "feishu",
+    "lark",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LyraWang6688/ai-capability-store.git",
+    "directory": "external-capabilities/cli/chrome-frequent-pages"
+  },
+  "bin": {
+    "chrome-frequent-pages": "bin/cli.js"
+  },
+  "files": [
+    "main.py",
+    "run-if-due.sh",
+    "inbox-deliver-mac.py",
+    "table_snapshot.py",
+    "bin/",
+    "config.example.json",
+    "README.md",
+    "LICENSE",
+    "install.sh"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/run-if-due.sh

@@ -0,0 +1,58 @@
+#!/bin/bash
+# 开机触发：每周只跑一次（ISO 周去重）。由 launchd 的 RunAtLoad 调用。
+set -u
+STATE_DIR="$HOME/.config/chrome-frequent-pages"
+STATE="$STATE_DIR/last-run.json"
+LOG="$STATE_DIR/run-if-due.log"
+HERE="$(cd "$(dirname "$0")" && pwd)"
+export PATH="$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+WEEK="$(date +%G-%V)"
+mkdir -p "$STATE_DIR"
+log() { echo "$(date '+%F %T') $*" >> "$LOG"; }
+
+LAST=""
+if [ -f "$STATE" ]; then
+  LAST="$(python3 -c 'import json,sys;print(json.load(open(sys.argv[1])).get("week",""))' "$STATE" 2>/dev/null || true)"
+fi
+if [ "$LAST" = "$WEEK" ]; then
+  log "skip: week $WEEK already ran"
+  exit 0
+fi
+
+SNAP_BEFORE="$(python3 "$HERE/table_snapshot.py" 2>/dev/null || echo '{}')"
+OUT="$(chrome-frequent-pages --write 2>&1)"
+CODE=$?
+if [ $CODE -ne 0 ]; then
+  log "run failed (exit $CODE): $(echo "$OUT" | tail -3 | tr '\n' ' ')"
+  python3 "$HERE/inbox-deliver-mac.py" --task chrome-frequent-pages --result 失败 \
+    --summary "chrome-frequent-pages 执行失败：$(echo "$OUT" | tail -1 | cut -c1-70)" >> "$LOG" 2>&1 || true
+  exit 1
+fi
+
+LINE="$(echo "$OUT" | grep -o '飞书写入完成：.*' | tail -1)"
+[ -z "$LINE" ] && LINE="$(echo "$OUT" | tail -1)"
+SNAP_AFTER="$(python3 "$HERE/table_snapshot.py" 2>/dev/null || echo '{}')"
+DETAIL="$(python3 - "$SNAP_BEFORE" "$SNAP_AFTER" <<'PYD'
+import json, sys
+before = json.loads(sys.argv[1] or "{}")
+after = json.loads(sys.argv[2] or "{}")
+new = [(h, v) for h, v in after.items() if h not in before]
+if not new:
+    print("本周无新增页面")
+else:
+    parts = []
+    for host, v in new[:5]:
+        cat = v.get("cat") or "其他"
+        tag = "未分类→其他" if cat == "其他" else cat
+        parts.append(f"{v.get('title') or host}（{host}）→ 书签「{tag}」")
+    more = "" if len(new) <= 5 else f" 等 {len(new)} 条"
+    print("新增：" + "；".join(parts) + more)
+PYD
+)"
+python3 "$HERE/inbox-deliver-mac.py" --task chrome-frequent-pages --result 成功 \
+  --summary "$DETAIL；$LINE" >> "$LOG" 2>&1 || log "inbox deliver failed"
+python3 - "$STATE" "$WEEK" <<'PY'
+import json, sys, datetime
+json.dump({"week": sys.argv[2], "at": datetime.datetime.now().isoformat(timespec="seconds")}, open(sys.argv[1], "w"), ensure_ascii=False)
+PY
+log "done week=$WEEK result=$LINE"

package/table_snapshot.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""导出「常用网页」表的 域名 -> {标题, 分类} 快照，供 run-if-due.sh 做前后 diff。"""
+import json, subprocess, sys
+
+BASE = "ZNjDb9TrpalLuCsw0macCeVdnld"
+TABLE = "tblDejemWsgqKSA2"
+
+def main():
+    out = subprocess.run(
+        ["lark-cli", "base", "+record-list", "--base-token", BASE, "--table-id", TABLE,
+         "--limit", "200", "--as", "user", "--format", "json"],
+        capture_output=True, text=True, timeout=120)
+    try:
+        data = json.loads(out.stdout)
+    except Exception:
+        print("{}")
+        return 1
+    meta = (data.get("data") or {})
+    cols = meta.get("fields") or []
+    rows = meta.get("data") or []
+    if "域名" not in cols:
+        print("{}")
+        return 1
+    idx = {name: i for i, name in enumerate(cols)}
+    snap = {}
+    for row in rows:
+        host = str(row[idx["域名"]] or "").strip()
+        if not host:
+            continue
+        cat = "其他"
+        if "分类" in idx:
+            raw = row[idx["分类"]]
+            if isinstance(raw, list) and raw:
+                cat = str(raw[0])
+            elif isinstance(raw, str) and raw.strip():
+                cat = raw.strip()
+        title = ""
+        if "标题" in idx and row[idx["标题"]]:
+            title = str(row[idx["标题"]]).strip()
+        snap[host] = {"title": title or host, "cat": cat}
+    print(json.dumps(snap, ensure_ascii=False))
+    return 0
+
+if __name__ == "__main__":
+    sys.exit(main())