harveyz-skill 0.26.0 → 0.27.0

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.27.0] - 2026-08-13
+
+### Added
+- `clip-url`：新增 browser-fetch-mcp 前置可用性检测，抓取前先确认 MCP 可用，避免执行到中途才发现环境问题
+- `clip-url`：正文开头新增流程概览（路线图），列出各步骤编号，减少多步骤执行时的偏差
+
+### Changed
+- `clip-url`：优化 description 触发文案，定位为 extract-url 的通用替代品参与触发竞争，覆盖更多保存/归档/翻译存档场景
+
+### Fixed
+- `clip-url`：chrome_profile 询问从「可能每次任务都问」改为「只在首次使用本 skill 时问一次」，无论用户当时是否设置了值，都会记住已经问过
+
+## [0.26.1] - 2026-08-13
+
+### Fixed
+- `clip-url`：MCP 抓取脚本此前写死仓库内相对路径来定位 `browser-fetch-mcp`，在任何非源码 checkout 的已安装环境下都会 `FileNotFoundError`；改为 dev-mode（仓库内）优先、已安装模式（`~/.local/bin/browser-fetch-mcp`）兜底的探测逻辑，并把 `browser-fetch-mcp` 注册进 `skills-index.json` 的 `tools[]`（新增 `research-tools` bundle），使其首次可通过 `hskill install --tool browser-fetch-mcp` 安装
+
 ## [0.26.0] - 2026-08-12
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "harveyz-skill",
-  "version": "0.26.0",
+  "version": "0.27.0",
   "description": "Skill manager for Claude Code, Cursor, Codex, OpenClaw, Hermes, OpenCode, and Pi",
   "type": "module",
   "bin": {
@@ -57,6 +57,7 @@
     "skills/coding/handoff/",
     "tools/hub/",
     "tools/sync-agent/",
+    "tools/browser-fetch-mcp/",
     "hooks/check-similar-branch/"
   ],
   "engines": {

package/skills/research/clip-url/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: clip-url
-version: "0.7.0"
-description: "Fetches a URL through browser-fetch-mcp's fetch_article (site-aware extraction: generic/wechat/arxiv/xcom, with image download and a persisted default chrome_profile), tags against extract-url's shared fixed-tag vocabulary, translates, and saves origin + translation into extract-url's real shared Obsidian Vault (VAULT_PATH) with cross-skill URL dedup. Not extract-url's full equivalent yet (no frontmatter auto-repair), but writes real vault content, not a validation-only test directory."
+version: "0.7.5"
+description: "Use this the instant a URL is shared with any intent to save, archive, clip, or translate-and-keep it in Obsidian — a bare link with no comment, \"save this\", \"archive this\", \"clip this\", \"add to obsidian\", \"存一下\", \"存到 vault/obsidian\", \"留个档\", \"翻译一下存\", \"帮我存/抓一下这个链接\", or a request to fetch a page via browser-fetch-mcp. Covers arXiv papers, WeChat/公众号 posts, X/Twitter threads, Hacker News links, blog posts, news articles, and general webpages — including sites needing special handling (login walls, images, JS-rendered content). Do not use for translate-or-summarize-only requests with no save intent, in-page actions like clicking buttons or filling forms, retagging or fixing metadata on an article already saved, links shared purely for reaction or jokes, or topic searches with no specific URL given."
 user_invocable: true
 ---
 
@@ -9,6 +9,8 @@ user_invocable: true
 
 这是 [browser-fetch-mcp](../../../tools/browser-fetch-mcp/) 的验证性消费者，跟 extract-url 的 Subagent 1/2 结构对齐，做"抓取（MCP，经 fetch_article 做站点感知抽取）→ 打标 + 翻译 → 存文件"两阶段流程。URL 去重和固定标签词表与 extract-url 共用同一份 `~/.hskill/url-extract/config.json`（`VAULT_PATH`）和 `fixed_tags.txt`，两边抓过的文章互相认得出"已抓取"。仍不是 extract-url 的完全等价替代（例如没有 `validate_article.py` 那样的 frontmatter 自动修复），只用于验证 MCP 抓取链路能否支撑一个完整的两阶段 skill 流程并逐步对齐生产行为。抓取产出的原文文件名与 extract-url 一致，按标题命名（`Origin/<标题>.md`，Translation 沿用同一文件名），两者共存于同一个 `<hash8>/` 目录下，去重判定只看 `meta.json` 的 `source_url`，不受文件名影响。
 
+**依赖**：本 skill 的 MCP 抓取脚本（`scripts/mcp_fetch_client.py` 等）依赖 `browser-fetch-mcp`。在本仓库 checkout 内直接运行时会自动找到 `tools/browser-fetch-mcp/browser-fetch-mcp.sh`；若这个 skill 是通过 `hskill install` 安装到别处运行的（`~/.claude/skills/`、`~/.pi/agent/skills/` 等），需要额外单独运行 `hskill install --tool browser-fetch-mcp` 装好 launcher（落到 `~/.local/bin/browser-fetch-mcp`）。步骤 1.5 会在流程一开始就检测这个依赖是否满足。
+
 ## 路径变量
 
 ```
@@ -17,6 +19,17 @@ SkillDir: skills/research/clip-url
 
 ## 执行流程
 
+流程概览（各步骤的判断条件和细节以下方对应小节为准，这里只做路线图）：
+
+1. 净化 URL
+2. 确认默认 chrome_profile（只在第一次使用本 skill 时问一次）
+2.5. 确认共享配置存在（VAULT_PATH / 固定词表）
+3. 派发 Subagent 1：MCP 抓取
+4. 判断抓取结果，决定是否需要自优化
+4.5. 派发 Subagent 3：自优化（仅在步骤 4 判定需要时）
+5. 派发 Subagent 2：打标 + 翻译
+6. 向用户输出结果卡片
+
 ### 步骤 1：净化 URL
 
 ```python
@@ -24,16 +37,26 @@ import re
 url_safe = re.sub(r'[\x00-\x1f\x7f]', '', url).strip()[:2048]
 ```
 
-### 步骤 2：确认默认 chrome_profile（首次使用时设置一次，之后不再询问）
+### 步骤 1.5：确认 browser-fetch-mcp 可用
+
+运行 `python3 SkillDir/scripts/browser_fetch_mcp_locate.py`。
+
+- 若输出 `FOUND: <path>`：继续步骤 2。
+- 若输出 `NOT_FOUND: <error>`（exit code 1）：向用户报告"browser-fetch-mcp 未安装或未找到：{error}。若在本仓库 checkout 内运行，请确认 `tools/browser-fetch-mcp/browser-fetch-mcp.sh` 存在；若是通过 `hskill install` 安装的 skill 副本，请先运行 `hskill install --tool browser-fetch-mcp`"，流程终止，不再执行后续步骤。
+
+### 步骤 2：确认默认 chrome_profile（只在第一次使用本 skill 时问一次，之后不再询问）
 
 运行 `python3 SkillDir/scripts/chrome_profile_config.py get`。
 
-- 若输出 `CONFIGURED: <path>`：已经配置过默认 profile，跳过下面的检测和提问，直接进入步骤 3。
-- 若输出 `NOT_CONFIGURED`（不论当前 URL 是什么网站，只要还没配置过就会命中这一分支）：
-  1. 运行 `python3 SkillDir/scripts/detect_xcom_chrome_profile.py`，把完整输出（对比表 + `RECOMMENDED_PROFILE:` 那行）原样展示给用户。
-  2. 向用户提问：把推荐的 profile 设为以后的默认值？或输入一个替代路径？也可以选择这次先不设置。
-  3. 若用户提供了 profile 路径（推荐的或自己输入的）：运行 `python3 SkillDir/scripts/chrome_profile_config.py set <path>` 持久化。此后所有网站的抓取都不会再触发这个设置流程。
-  4. 若用户选择不设置：不持久化任何值，本次继续（x.com 的 URL 会在 Subagent 1 里因为 browser-fetch-mcp 的 `fetch_article` 报错而失败——x.com 没有匿名抓取选项；非 x.com 的 URL 正常匿名抓取，不受影响）。
+- 若输出 `CONFIGURED: <path>`：已经配置过默认 profile，跳过下面的检测和提问，直接进入步骤 2.5。
+- 若输出 `NOT_CONFIGURED`：运行 `python3 SkillDir/scripts/chrome_profile_config.py prompted`。
+  - 若输出 `YES`（之前已经问过一次，不管当时用户是设置了值还是选择不设置）：跳过检测和提问，直接进入步骤 2.5。
+  - 若输出 `NO`（第一次遇到这个状态，不论当前 URL 是什么网站都会命中）：
+    1. 运行 `python3 SkillDir/scripts/detect_xcom_chrome_profile.py`，把完整输出（对比表 + `RECOMMENDED_PROFILE:` 那行）原样展示给用户。
+    2. 向用户提问：把推荐的 profile 设为以后的默认值？或输入一个替代路径？也可以选择不设置。
+    3. 不论用户如何回答，运行 `python3 SkillDir/scripts/chrome_profile_config.py mark-prompted`，记录"已经问过一次"——此后所有网站的抓取都不会再触发这个设置流程（包括用户当时选择不设置的情况）。
+    4. 若用户提供了 profile 路径（推荐的或自己输入的）：运行 `python3 SkillDir/scripts/chrome_profile_config.py set <path>` 持久化。
+    5. 若用户选择不设置：不持久化 profile 值，本次继续（x.com 的 URL 会在 Subagent 1 里因为 `fetch_article` 报错而失败——x.com 没有匿名抓取选项；非 x.com 的 URL 正常匿名抓取，不受影响）。用户之后可随时手动运行 `chrome_profile_config.py set <path>` 补配置。
 
 **不允许**：跳过展示直接把探测到的 profile 设为默认值——必须等用户明确回答，且只有用户确认后才能调用 `chrome_profile_config.py set`。
 
@@ -132,6 +155,7 @@ result = subprocess.run(
 | `references/subagent1-fetch-prompt.md` | Subagent 1（MCP 抓取）派发 prompt 模板，含去重检查 |
 | `references/subagent2-tag-translate-prompt.md` | Subagent 2（两阶段打标 + 翻译）派发 prompt 模板 |
 | `references/subagent-self-optimize-prompt.md` | Subagent 3（自优化，抓取失败/过薄时触发）派发 prompt 模板 |
+| `scripts/browser_fetch_mcp_locate.py` | 步骤 1.5 前置检测：定位 browser-fetch-mcp launcher（dev-mode 优先，已安装模式兜底），也被下面几个 MCP client 脚本共用 |
 | `scripts/vault_config.py` | 读共享 `VAULT_PATH`（`~/.hskill/url-extract/config.json`），计算文章路径 |
 | `scripts/dedup_check.py` | URL 去重检查（读 `<hash8>/meta.json`） |
 | `scripts/article_meta.py` | 去重索引写入 + 固定词表兜底移位（纯函数库） |
@@ -139,4 +163,4 @@ result = subprocess.run(
 | `scripts/mcp_fetch_client.py` | 核心脚本：真实 MCP client，调用 browser-fetch-mcp 的 `fetch_article`，`fetch_and_report` 额外返回诊断字段 |
 | `scripts/mcp_debug_client.py` | 自优化 subagent 用的调试客户端，包装 browser-fetch-mcp 的 `fetch_page`/`evaluate_js` |
 | `scripts/detect_xcom_chrome_profile.py` | 通过 browser-fetch-mcp 的 `list_chrome_profiles` MCP 工具检测哪些 Chrome profile 登录了 x.com，仅供用户确认用，不自动使用检测结果 |
-| `scripts/chrome_profile_config.py` | 读写 browser-fetch-mcp 持久化的默认 chrome_profile（`get`/`set` 子命令） |
+| `scripts/chrome_profile_config.py` | 读写 browser-fetch-mcp 持久化的默认 chrome_profile（`get`/`set` 子命令），以及本地记录"是否已问过一次"的标记（`prompted`/`mark-prompted` 子命令） |

package/skills/research/clip-url/scripts/browser_fetch_mcp_locate.py

@@ -0,0 +1,48 @@
+"""Locates the browser-fetch-mcp launcher for clip-url's MCP client scripts.
+
+Two supported layouts:
+- Dev mode: this skill runs from inside a harveyz-skill git checkout, where
+  tools/browser-fetch-mcp/browser-fetch-mcp.sh sits four directories above
+  scripts/ (skills/research/clip-url/scripts -> repo root).
+- Installed mode: this skill was installed via `hskill install` (to
+  ~/.claude/skills, ~/.pi/agent/skills, etc.), and browser-fetch-mcp was
+  separately installed as a tool — its launcher lands at
+  ~/.local/bin/browser-fetch-mcp (see tools/browser-fetch-mcp/tool.json).
+"""
+import shutil
+import sys
+from pathlib import Path
+
+
+def find_browser_fetch_mcp() -> str:
+    dev_path = Path(__file__).resolve().parents[4] / "tools" / "browser-fetch-mcp" / "browser-fetch-mcp.sh"
+    if dev_path.exists():
+        return str(dev_path)
+
+    on_path = shutil.which("browser-fetch-mcp")
+    if on_path:
+        return on_path
+
+    installed_path = Path.home() / ".local" / "bin" / "browser-fetch-mcp"
+    if installed_path.exists():
+        return str(installed_path)
+
+    raise FileNotFoundError(
+        "browser-fetch-mcp launcher not found. Run clip-url from a harveyz-skill "
+        "git checkout, or run `hskill install` and select the browser-fetch-mcp tool."
+    )
+
+
+def main():
+    """CLI preflight check for SKILL.md: prints FOUND/NOT_FOUND instead of
+    letting the FileNotFoundError surface as a raw traceback from whichever
+    client script happens to import this module first."""
+    try:
+        print(f"FOUND: {find_browser_fetch_mcp()}")
+    except FileNotFoundError as e:
+        print(f"NOT_FOUND: {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/skills/research/clip-url/scripts/chrome_profile_config.py

@@ -4,13 +4,23 @@ default Chrome profile (get_default_chrome_profile / set_default_chrome_profile
 tools). Written from scratch, same stdio_client pattern as mcp_fetch_client.py
 and detect_xcom_chrome_profile.py.
 
+Also tracks, purely locally (no MCP call involved), whether clip-url has
+already asked the user about chrome_profile once — so SKILL.md's step 2
+only prompts on the very first run, regardless of whether the user set a
+profile or declined, instead of re-prompting on every run until a profile
+happens to get set.
+
 Usage:
   python3 chrome_profile_config.py get
   python3 chrome_profile_config.py set <profile_path>
+  python3 chrome_profile_config.py prompted
+  python3 chrome_profile_config.py mark-prompted
 
 get prints "CONFIGURED: <path>" or "NOT_CONFIGURED".
 set prints "OK" on success; on failure, prints the error to stderr and
 exits 1 (e.g. profile_path doesn't exist or isn't a directory).
+prompted prints "YES" or "NO".
+mark-prompted records that the user has been asked and prints "OK".
 """
 import asyncio
 import json
@@ -21,9 +31,25 @@ from pathlib import Path
 from mcp import ClientSession, StdioServerParameters
 from mcp.client.stdio import stdio_client
 
-BROWSER_FETCH_MCP_SH = (
-    Path(__file__).resolve().parents[4] / "tools" / "browser-fetch-mcp" / "browser-fetch-mcp.sh"
-)
+from browser_fetch_mcp_locate import find_browser_fetch_mcp
+
+BROWSER_FETCH_MCP_SH = find_browser_fetch_mcp()
+
+
+def _prompted_marker_path() -> Path:
+    env_dir = os.environ.get("HSKILL_CLIP_URL_DATA_DIR")
+    base = Path(env_dir) if env_dir else Path.home() / ".hskill" / "clip-url"
+    return base / "chrome_profile_prompted"
+
+
+def get_prompted() -> bool:
+    return _prompted_marker_path().exists()
+
+
+def mark_prompted() -> None:
+    marker = _prompted_marker_path()
+    marker.parent.mkdir(parents=True, exist_ok=True)
+    marker.write_text("", encoding="utf-8")
 
 
 async def _get() -> str:
@@ -57,14 +83,27 @@ async def _set(profile_path: str) -> str:
 
 
 def main():
-    if len(sys.argv) < 2 or sys.argv[1] not in ("get", "set"):
-        print("Usage: chrome_profile_config.py get | set <profile_path>", file=sys.stderr)
+    valid = ("get", "set", "prompted", "mark-prompted")
+    if len(sys.argv) < 2 or sys.argv[1] not in valid:
+        print(
+            "Usage: chrome_profile_config.py get | set <profile_path> | prompted | mark-prompted",
+            file=sys.stderr,
+        )
         sys.exit(1)
 
     if sys.argv[1] == "get":
         print(asyncio.run(_get()))
         return
 
+    if sys.argv[1] == "prompted":
+        print("YES" if get_prompted() else "NO")
+        return
+
+    if sys.argv[1] == "mark-prompted":
+        mark_prompted()
+        print("OK")
+        return
+
     if len(sys.argv) < 3:
         print("Usage: chrome_profile_config.py set <profile_path>", file=sys.stderr)
         sys.exit(1)

package/skills/research/clip-url/scripts/detect_xcom_chrome_profile.py

@@ -23,14 +23,13 @@ isError/structuredContent), same as mcp_fetch_client.py.
 import asyncio
 import json
 import os
-from pathlib import Path
 
 from mcp import ClientSession, StdioServerParameters
 from mcp.client.stdio import stdio_client
 
-BROWSER_FETCH_MCP_SH = (
-    Path(__file__).resolve().parents[4] / "tools" / "browser-fetch-mcp" / "browser-fetch-mcp.sh"
-)
+from browser_fetch_mcp_locate import find_browser_fetch_mcp
+
+BROWSER_FETCH_MCP_SH = find_browser_fetch_mcp()
 
 HOST_KEYS = [".x.com", ".twitter.com"]
 COOKIE_NAMES = ["auth_token", "ct0", "twid"]

package/skills/research/clip-url/scripts/mcp_debug_client.py

@@ -10,15 +10,14 @@ mcp 1.28.1 camelCase note as mcp_fetch_client.py).
 """
 import json
 import os
-from pathlib import Path
 from typing import Optional
 
 from mcp import ClientSession, StdioServerParameters
 from mcp.client.stdio import stdio_client
 
-BROWSER_FETCH_MCP_SH = (
-    Path(__file__).resolve().parents[4] / "tools" / "browser-fetch-mcp" / "browser-fetch-mcp.sh"
-)
+from browser_fetch_mcp_locate import find_browser_fetch_mcp
+
+BROWSER_FETCH_MCP_SH = find_browser_fetch_mcp()
 
 
 async def _call_tool(tool_name: str, tool_args: dict) -> dict:

package/skills/research/clip-url/scripts/mcp_fetch_client.py

@@ -33,10 +33,9 @@ from mcp import ClientSession, StdioServerParameters
 from mcp.client.stdio import stdio_client
 
 import vault_config
+from browser_fetch_mcp_locate import find_browser_fetch_mcp
 
-BROWSER_FETCH_MCP_SH = (
-    Path(__file__).resolve().parents[4] / "tools" / "browser-fetch-mcp" / "browser-fetch-mcp.sh"
-)
+BROWSER_FETCH_MCP_SH = find_browser_fetch_mcp()
 
 
 async def fetch_and_report(url: str, chrome_profile: Optional[str] = None) -> dict:

package/skills/research/clip-url/tests/test_browser_fetch_mcp_locate.py

@@ -0,0 +1,83 @@
+"""Unit tests for browser_fetch_mcp_locate.py's dev-mode / installed-mode
+fallback — never touches a real browser-fetch-mcp installation."""
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "scripts"))
+
+import browser_fetch_mcp_locate  # noqa: E402
+from browser_fetch_mcp_locate import find_browser_fetch_mcp, main  # noqa: E402
+
+
+def test_prefers_dev_mode_path_when_it_exists(monkeypatch, tmp_path):
+    dev_sh = tmp_path / "tools" / "browser-fetch-mcp" / "browser-fetch-mcp.sh"
+    dev_sh.parent.mkdir(parents=True)
+    dev_sh.write_text("#!/usr/bin/env bash\n", encoding="utf-8")
+
+    fake_module_path = tmp_path / "skills" / "research" / "clip-url" / "scripts" / "browser_fetch_mcp_locate.py"
+    monkeypatch.setattr(browser_fetch_mcp_locate, "__file__", str(fake_module_path))
+
+    assert find_browser_fetch_mcp() == str(dev_sh)
+
+
+def test_falls_back_to_path_lookup_when_dev_path_missing(monkeypatch, tmp_path):
+    fake_module_path = tmp_path / "skills" / "research" / "clip-url" / "scripts" / "browser_fetch_mcp_locate.py"
+    monkeypatch.setattr(browser_fetch_mcp_locate, "__file__", str(fake_module_path))
+    monkeypatch.setattr(browser_fetch_mcp_locate.shutil, "which", lambda name: "/usr/local/bin/browser-fetch-mcp")
+
+    assert find_browser_fetch_mcp() == "/usr/local/bin/browser-fetch-mcp"
+
+
+def test_falls_back_to_local_bin_when_not_on_path(monkeypatch, tmp_path):
+    fake_module_path = tmp_path / "skills" / "research" / "clip-url" / "scripts" / "browser_fetch_mcp_locate.py"
+    monkeypatch.setattr(browser_fetch_mcp_locate, "__file__", str(fake_module_path))
+    monkeypatch.setattr(browser_fetch_mcp_locate.shutil, "which", lambda name: None)
+
+    fake_home = tmp_path / "home"
+    installed = fake_home / ".local" / "bin" / "browser-fetch-mcp"
+    installed.parent.mkdir(parents=True)
+    installed.write_text("#!/usr/bin/env bash\n", encoding="utf-8")
+    monkeypatch.setattr(browser_fetch_mcp_locate.Path, "home", classmethod(lambda cls: fake_home))
+
+    assert find_browser_fetch_mcp() == str(installed)
+
+
+def test_raises_actionable_error_when_nothing_found(monkeypatch, tmp_path):
+    fake_module_path = tmp_path / "skills" / "research" / "clip-url" / "scripts" / "browser_fetch_mcp_locate.py"
+    monkeypatch.setattr(browser_fetch_mcp_locate, "__file__", str(fake_module_path))
+    monkeypatch.setattr(browser_fetch_mcp_locate.shutil, "which", lambda name: None)
+    monkeypatch.setattr(browser_fetch_mcp_locate.Path, "home", classmethod(lambda cls: tmp_path / "empty-home"))
+
+    with pytest.raises(FileNotFoundError, match="hskill install"):
+        find_browser_fetch_mcp()
+
+
+def test_main_prints_found_and_exits_zero(monkeypatch, tmp_path, capsys):
+    dev_sh = tmp_path / "tools" / "browser-fetch-mcp" / "browser-fetch-mcp.sh"
+    dev_sh.parent.mkdir(parents=True)
+    dev_sh.write_text("#!/usr/bin/env bash\n", encoding="utf-8")
+
+    fake_module_path = tmp_path / "skills" / "research" / "clip-url" / "scripts" / "browser_fetch_mcp_locate.py"
+    monkeypatch.setattr(browser_fetch_mcp_locate, "__file__", str(fake_module_path))
+
+    main()
+
+    captured = capsys.readouterr()
+    assert captured.out.strip() == f"FOUND: {dev_sh}"
+
+
+def test_main_prints_not_found_and_exits_one(monkeypatch, tmp_path, capsys):
+    fake_module_path = tmp_path / "skills" / "research" / "clip-url" / "scripts" / "browser_fetch_mcp_locate.py"
+    monkeypatch.setattr(browser_fetch_mcp_locate, "__file__", str(fake_module_path))
+    monkeypatch.setattr(browser_fetch_mcp_locate.shutil, "which", lambda name: None)
+    monkeypatch.setattr(browser_fetch_mcp_locate.Path, "home", classmethod(lambda cls: tmp_path / "empty-home"))
+
+    with pytest.raises(SystemExit) as exc_info:
+        main()
+
+    assert exc_info.value.code == 1
+    captured = capsys.readouterr()
+    assert captured.out.startswith("NOT_FOUND: ")
+    assert "hskill install" in captured.out

package/skills/research/clip-url/tests/test_chrome_profile_config.py

@@ -44,3 +44,31 @@ def test_set_rejects_nonexistent_path(tmp_path):
     result = _run(["set", str(tmp_path / "DoesNotExist")], data_dir)
     assert result.returncode == 1
     assert result.stderr.strip() != ""
+
+
+def _run_prompted(args: list[str], data_dir: Path, clip_url_dir: Path) -> subprocess.CompletedProcess:
+    return subprocess.run(
+        [sys.executable, str(SCRIPT), *args],
+        env={
+            **os.environ,
+            "BROWSER_FETCH_MCP_DATA_DIR": str(data_dir),
+            "HSKILL_CLIP_URL_DATA_DIR": str(clip_url_dir),
+        },
+        capture_output=True, text=True, timeout=30,
+    )
+
+
+def test_prompted_reports_no_initially(tmp_path):
+    result = _run_prompted(["prompted"], tmp_path / "data", tmp_path / "clip-url")
+    assert result.returncode == 0, result.stderr
+    assert result.stdout.strip() == "NO"
+
+
+def test_mark_prompted_then_prompted_reports_yes(tmp_path):
+    clip_url_dir = tmp_path / "clip-url"
+    mark_result = _run_prompted(["mark-prompted"], tmp_path / "data", clip_url_dir)
+    assert mark_result.returncode == 0, mark_result.stderr
+    assert mark_result.stdout.strip() == "OK"
+
+    prompted_result = _run_prompted(["prompted"], tmp_path / "data", clip_url_dir)
+    assert prompted_result.stdout.strip() == "YES"

package/skills-index.json

@@ -1,6 +1,7 @@
 {
   "toolBundleMeta": {
-    "tools": "开发者 OS 工具（hub — 项目管理 + git 状态 + 任务跟踪；sync — Syncthing 守护进程管理）"
+    "tools": "开发者 OS 工具（hub — 项目管理 + git 状态 + 任务跟踪；sync — Syncthing 守护进程管理）",
+    "research-tools": "研究抓取后端（browser-fetch-mcp — clip-url/extract-url 共用的认证浏览器抓取 MCP server）"
   },
   "tools": [
     {
@@ -14,6 +15,11 @@
       "path": "tools/sync-agent",
       "bundle": "tools",
       "installScope": "global"
+    },
+    {
+      "name": "browser-fetch-mcp",
+      "path": "tools/browser-fetch-mcp",
+      "bundle": "research-tools"
     }
   ],
   "bundleMeta": {
@@ -93,8 +99,8 @@
       "path": "research/clip-url",
       "bundle": "research",
       "installScope": "project",
-      "contentHash": "23eae79c7c7f2908",
-      "contentVersion": "0.7.0"
+      "contentHash": "46e5edd59daaa755",
+      "contentVersion": "0.7.5"
     },
     {
       "path": "creative/capture-todo",

package/tools/browser-fetch-mcp/browser-fetch-mcp.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Auto-detect dev mode: script is running from the source tree
+if [ -d "${SCRIPT_DIR}/browser_fetch_mcp" ] && [ -f "${SCRIPT_DIR}/pyproject.toml" ]; then
+  DEV_VENV="${SCRIPT_DIR}/.venv"
+  if [ ! -x "${DEV_VENV}/bin/browser-fetch-mcp" ]; then
+    python3 -m venv "${DEV_VENV}"
+    "${DEV_VENV}/bin/pip" install -q -e "${SCRIPT_DIR}"
+    "${DEV_VENV}/bin/python3" -m playwright install chromium
+  fi
+  exec "${DEV_VENV}/bin/browser-fetch-mcp" "$@"
+fi
+
+VENV_DIR="${HOME}/.hskill/tools/browser-fetch-mcp/venv"
+INSTALL_DIR="${HOME}/.hskill/tools/browser-fetch-mcp"
+HASH_FILE="${VENV_DIR}/.installed_hash"
+
+_hash_source() {
+  find "${INSTALL_DIR}" -type f \( -name "*.py" -o -name "*.toml" -o -name "*.json" \) \
+    ! -path "*/__pycache__/*" ! -path "*/venv/*" \
+    | sort | xargs sha256sum 2>/dev/null | sha256sum | awk '{print $1}'
+}
+
+CURRENT_HASH=$(_hash_source)
+
+if [ ! -x "${VENV_DIR}/bin/browser-fetch-mcp" ] || [ "$(cat "${HASH_FILE}" 2>/dev/null)" != "${CURRENT_HASH}" ]; then
+  python3 -m venv "${VENV_DIR}"
+  "${VENV_DIR}/bin/pip" install -q --upgrade "${INSTALL_DIR}"
+  "${VENV_DIR}/bin/python3" -m playwright install chromium
+  echo "${CURRENT_HASH}" > "${HASH_FILE}"
+fi
+
+exec "${VENV_DIR}/bin/browser-fetch-mcp" "$@"

package/tools/browser-fetch-mcp/browser_fetch_mcp/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

package/tools/browser-fetch-mcp/browser_fetch_mcp/config.py

@@ -0,0 +1,25 @@
+"""Persisted default Chrome profile — a single JSON file in the server's
+data dir, {"default_chrome_profile": "<path>"}. Read/write here is pure
+I/O; the caller (server.py) owns resolving `data_dir` (BROWSER_FETCH_MCP_DATA_DIR
+override for tests) and validating the path before calling set().
+"""
+import json
+from pathlib import Path
+from typing import Optional
+
+
+def _config_file(data_dir: Path) -> Path:
+    return data_dir / "config.json"
+
+
+def get_default_chrome_profile(data_dir: Path) -> Optional[str]:
+    path = _config_file(data_dir)
+    if not path.exists():
+        return None
+    data = json.loads(path.read_text(encoding="utf-8"))
+    return data.get("default_chrome_profile")
+
+
+def set_default_chrome_profile(data_dir: Path, profile_path: str) -> None:
+    path = _config_file(data_dir)
+    path.write_text(json.dumps({"default_chrome_profile": profile_path}), encoding="utf-8")

package/tools/browser-fetch-mcp/browser_fetch_mcp/cookies.py

@@ -0,0 +1,35 @@
+"""Chrome profile cookie extraction.
+
+Mirrors docs/explanation/chrome-profile-cookie-injection.md's pattern:
+copy the Cookies DB to a temp file first (Chrome holds an exclusive lock
+on the original while running), then let pycookiecheat decrypt it. This
+module only extracts plaintext cookies — injecting them into a browser
+context happens in server.py, which owns the browser lifecycle.
+"""
+import os
+import shutil
+import tempfile
+from pathlib import Path
+
+import pycookiecheat
+
+
+def extract_cookies(url: str, chrome_profile: str) -> dict[str, str]:
+    """Return {cookie_name: plaintext_value} for `url`'s domain from the
+    given Chrome profile.
+
+    Returns {} if the profile has no Cookies file, or if pycookiecheat
+    finds no matching cookies — this is a normal "not logged in" result,
+    not an error condition, so it never raises for that case.
+    """
+    cookies_src = Path(chrome_profile) / "Cookies"
+    if not cookies_src.exists():
+        return {}
+
+    fd, tmp_path = tempfile.mkstemp(suffix=".db")
+    os.close(fd)
+    try:
+        shutil.copy2(cookies_src, tmp_path)
+        return pycookiecheat.chrome_cookies(url, cookie_file=tmp_path) or {}
+    finally:
+        os.unlink(tmp_path)