codebee 0.1.12 → 0.1.14

package/CHANGELOG.md

@@ -4,6 +4,19 @@ CodeBee 的用户可感知变更记录。发布新版时：最上面加一节，
 `<!-- relnotes:start -->…<!-- relnotes:end -->` 段（那段会被 `npm view` 的
 README 元数据带回，供老版本在「发现新版本」时展示新版更新内容）。
 
+## v0.1.14（2026-09-19）
+
+- 新任务类型「扫榜选材」：抓取七猫排行榜公开数据，AI 提炼热门题材 Top3/高频人设套路/差异化切入建议，直出选题洞察报告
+- 运行结果群推送：设置群机器人 webhook（钉钉/飞书/企微自动适配），任务跑完自动汇报状态与评分
+
+## v0.1.13（2026-09-19）
+
+- 封面图生成：连载任务建书面板新增「生成封面」——调编排者供应商图像 API（cogview 候选，竖版优先）产出 cover.png 到运行目录，SSRF 边界校验 + curl 子进程落盘（Python 不经手图像字节）
+- 需求拷问采访态：目标描述过短时先问 1-3 个澄清问题（选项芯片点选），创建更准
+- 代码任务 Best-of-N：单路实现失败后多候选 worktree 隔离赛马择优
+- 计划落盘任务档案：.codebee/ 三件套（spec.md 意图 / task_plan.md 计划 / evidence.md 验证证据）
+- 步骤卡「实际派发模型」徽章 + 类型菜单成本预估行
+
 ## v0.1.12（2026-09-19）
 
 - 代码任务计划落盘：每次运行把编排计划写进工作目录 .codebee/task_plan.md，与任务规格（spec.md）、验证证据（evidence.md）同居「任务档案」，断点续跑/复盘全程可查

package/README.md

@@ -136,6 +136,27 @@ codebee
 数据存放在用户目录（Windows `%APPDATA%\CodeBee`，macOS/Linux `~/.codebee`），
 升级/重装不影响；老版本 Tutti 目录（`%APPDATA%\Tutti`）会被自动沿用，无需迁移。
 
+### macOS：npm 全局安装报 EACCES（permission denied）
+
+官方 pkg 安装的 Node，全局目录 `/usr/local/lib/node_modules` 归 root，直接
+`npm install -g codebee` 会报
+`EACCES: permission denied, mkdir '/usr/local/lib/node_modules/codebee'`。
+**不要用 sudo 装**：装完目录归 root，应用内「一键升级」（以普通用户跑
+`npm install -g codebee@latest`）之后每次都会撞同样的权限错误。
+正确做法是把 npm 全局目录改到用户目录下，一次配好、安装与自动升级都畅通：
+
+```bash
+mkdir -p ~/.npm-global
+npm config set prefix "~/.npm-global"
+echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+npm install -g codebee
+```
+
+默认 shell 是 bash 的话，把第 3 行的 `~/.zshrc` 换成 `~/.bash_profile`。
+用 Homebrew 装的 Node（prefix 在 `/opt/homebrew`）没有这个问题，可直接安装。
+验证 `which codebee` 指向 `~/.npm-global/bin/codebee` 即配置成功。
+
 **方式二：源码运行（开发者）**
 
 ```bat

package/app/core/covergen.py

@@ -0,0 +1,200 @@
+# -*- coding: utf-8 -*-
+"""封面图生成：调供应商图像 API 产出竖版封面插画，curl 直接落盘到运行目录。
+
+接口形状：OpenAI 兼容 POST {base}/images/generations（Z.ai cogview 系列、
+多数聚合网关都支持，默认返回图片 URL）。模型解析：环境变量
+CODEBEE_IMAGE_MODEL 优先，否则逐个试候选（cogview-3-flash → cogview-4），
+第一个 2xx 的胜出；同一模型先试竖版尺寸再回落方图。
+状态机与建书生成同款（running/done/failed 写任务 cover_gen 字段，
+bump_state 推 SSE）。仅支持 openai 协议供应商。
+
+安全边界：
+- 图像 URL 仅接受 https，解析后 IP 命中私网/环回/链路本地一律拒绝
+  （防 SSRF 打内网与云元数据）；禁用重定向（curl -L 不加）。
+- Python 不经手图像字节：下载与落盘由 curl 子进程 -o 一步完成。
+- 产物只落 paths.RUNS_DIR 受管路径（与 report.md 同款），不写任务工作目录。
+"""
+from __future__ import annotations
+
+import logging
+import os
+import socket
+import threading
+import time
+from pathlib import Path
+
+log = logging.getLogger(__name__)
+
+_IMAGE_CANDIDATES = ("cogview-3-flash", "cogview-4")
+_SIZES = ("768x1344", "1024x1024")   # 竖版优先，方图兜底
+
+
+def _cover_prompt(task):
+    """从任务与建书资料拼图像提示词：场景氛围向，不要文字（平台会自行压字）。"""
+    bm = ((task.get("book_meta") or {}).get("fanqie") or {}).get("data") or {}
+    if not isinstance(bm, dict):
+        bm = {}
+    title = bm.get("书名") or task.get("title") or ""
+    genre = bm.get("类型") or bm.get("分类") or ""
+    brief = (bm.get("一句话简介") or bm.get("简介") or task.get("goal") or "")
+    return ("竖版小说封面插画，画面中不要出现任何文字。题材：%s %s。故事梗概：%s。"
+            "商业网文封面质感：主体人物或核心场景突出，色彩浓郁有冲击力，"
+            "构图上方留白便于后期压标题。" % (genre, title, str(brief)[:300]))
+
+
+def _pick_key(prov):
+    from . import modelhub
+    keys = modelhub._chain_keys(prov) or []
+    if keys and keys[0].get("key"):
+        return keys[0]["key"]
+    return prov.get("api_key") or ""
+
+
+def _safe_image_url(url):
+    """SSRF 校验：仅 https；解析主机全部 IP，私网/环回/链路本地/保留段拒绝。"""
+    import ipaddress
+    from urllib.parse import urlparse
+    u = urlparse(url)
+    if u.scheme != "https":
+        raise ValueError("仅允许 https 图像地址")
+    host = u.hostname or ""
+    if not host:
+        raise ValueError("图像地址缺少主机")
+    infos = socket.getaddrinfo(host, u.port or 443, proto=socket.IPPROTO_TCP)
+    if not infos:
+        raise ValueError("图像主机无法解析")
+    for info in infos:
+        ip = ipaddress.ip_address(info[4][0])
+        if (ip.is_private or ip.is_loopback or ip.is_link_local
+                or ip.is_reserved or ip.is_multicast or ip.is_unspecified):
+            raise ValueError("图像主机解析到受限地址，已拒绝")
+    return url
+
+
+def _curl_to(url, out_path):
+    """curl 子进程下载落盘（Python 不经手图像字节；不加 -L 禁重定向）。"""
+    from . import runner
+    r = runner.run_process(
+        argv=["curl", "-sS", "--max-time", "180",
+              "--proto", "=https", "--fail",
+              "-o", str(out_path), url],
+        timeout=200)
+    if not r["ok"]:
+        raise RuntimeError((r.get("stderr") or r.get("stdout") or "下载失败")[:200])
+    p = Path(out_path)
+    if not p.is_file() or p.stat().st_size < 1024:
+        raise RuntimeError("下载内容过小或为空")
+
+
+def _call_images(base, key, model, prompt, size, allow_private):
+    """POST /images/generations。返回 (data_item dict, 错误串)；data_item 含 url 或 b64_json。"""
+    from . import builtin_agent
+    url = base.rstrip("/") + "/images/generations"
+    status, data, err = builtin_agent._post_json(
+        url,
+        {"Authorization": "Bearer " + key, "Content-Type": "application/json"},
+        {"model": model, "prompt": prompt, "size": size},
+        allow_private, 180)
+    if status == 0:
+        return None, err or "网络错误"
+    if 200 <= status < 300:
+        items = (data or {}).get("data") or []
+        if items and isinstance(items[0], dict):
+            return items[0], ""
+        return None, "响应缺少 data[0]"
+    last = str((data or {}).get("error", {}).get("message", "") if isinstance(data, dict) else "") \
+        or err or ("HTTP %s" % status)
+    return None, last
+
+
+def make_cover(run_id, task):
+    """同步生成封面到运行目录。成功/失败返回 entry dict（写任务 cover_gen 用）。"""
+    from . import builtin_agent, modelhub, paths
+    try:
+        orch = modelhub.resolve_orchestrator()
+        if not orch:
+            raise RuntimeError("未配置编排者供应商（编排设置）")
+        prov, _m = orch
+        if str(prov.get("protocol") or "openai") not in ("openai", ""):
+            raise RuntimeError("封面生成仅支持 openai 协议供应商")
+        base = str(prov.get("base_url") or "").rstrip("/")
+        key = _pick_key(prov)
+        if not base or not key:
+            raise RuntimeError("供应商缺少 base_url 或密钥")
+        allow_private = bool(prov.get("allow_private"))
+        prompt = _cover_prompt(task)
+        models = []
+        env_model = os.environ.get("CODEBEE_IMAGE_MODEL", "").strip()
+        if env_model:
+            models.append(env_model)
+        models.extend(m for m in _IMAGE_CANDIDATES if m not in models)
+        last_err = ""
+        for model in models:
+            for size in _SIZES:
+                item, err = _call_images(base, key, model, prompt, size, allow_private)
+                if item is None:
+                    last_err = err
+                    continue
+                img_url = str(item.get("url") or "")
+                if not img_url:
+                    last_err = "该供应商未返回图片 URL（仅内嵌数据），暂不支持"
+                    continue
+                try:
+                    safe_url = _safe_image_url(img_url)
+                except ValueError as e:
+                    last_err = str(e)
+                    continue
+                out_dir = paths.RUNS_DIR / str(run_id)
+                out_dir.mkdir(parents=True, exist_ok=True)
+                out = out_dir / "cover.png"
+                try:
+                    _curl_to(safe_url, out)
+                except RuntimeError as e:
+                    last_err = str(e)
+                    continue
+                return {"status": "done", "file": "cover.png", "run_id": str(run_id),
+                        "model": model, "size": size,
+                        "at": time.strftime("%Y-%m-%d %H:%M:%S")}
+        raise RuntimeError(last_err or "图像接口无可用模型")
+    except Exception as e:
+        return {"status": "failed", "error": str(e)[:300],
+                "at": time.strftime("%Y-%m-%d %H:%M:%S")}
+
+
+def generate_async(run_id, task_id, task):
+    """后台线程入口：生成封面并把终态写回任务 cover_gen（仿建书 generate_async）。"""
+    from . import store
+    if not store.get_task(task_id):
+        return
+    entry = make_cover(run_id, task)
+    cur = store.get_task(task_id)
+    if not cur:
+        return
+    prev = cur.get("cover_gen") or {}
+    if prev.get("status") != "running":   # 期间被删/重置：丢弃结果
+        return
+    store.set_cover_gen(task_id, entry)
+
+
+def start(task_id, run_id=None):
+    """起后台封面生成线程。run_id 缺省用该任务最近一次 run。返回 (ok, err)。running 幂等拒绝。"""
+    from . import store
+    task = store.get_task(task_id)
+    if not task:
+        return False, "任务不存在"
+    cur = task.get("cover_gen") or {}
+    if cur.get("status") == "running":
+        return True, ""
+    rid = run_id
+    if not rid:
+        runs = store.task_runs(task_id)
+        rid = (runs[-1].get("id") if runs else "")
+    if not rid:
+        return False, "没有可归属的运行记录（先跑一次任务再生成封面）"
+    if not store.set_cover_gen(task_id, {"status": "running",
+                                         "at": time.strftime("%Y-%m-%d %H:%M:%S")}):
+        return False, "任务不存在"
+    task = dict(task, cover_gen={"status": "running"})
+    threading.Thread(target=generate_async, daemon=True,
+                     name="cover-gen-%s" % task_id, args=(rid, task_id, task)).start()
+    return True, ""

package/app/core/flows.py

@@ -74,6 +74,9 @@ BUILTIN_FLOWS = [
      "threshold": 7.0, "rounds": 2,
      "goal_hint": "翻译什么（源文本位置 / 目标语言 / 要求）",
      "note": "起草 → 多维评审 → 修订循环 → 发布门禁"},
+    {"id": "rank_scan", "name": "扫榜选材", "icon": "i-chart", "engine": "direct", "builtin": True,
+     "goal_hint": "想写哪个方向（一句话，可留空默认分析总榜热门题材）",
+     "note": "抓取七猫排行榜公开数据 → AI 提炼热门题材/人设/差异化切入点（快档直出报告）"},
     {"id": "research", "name": "调研报告", "icon": "i-file-search", "engine": "review", "builtin": True,
      "manuscript": "report.md",
      "rubric": ["全面性", "深度", "论据可靠", "可读性", "结论质量"],

package/app/core/goal_service.py

@@ -86,9 +86,18 @@ def get(goal_id: str):
         return dict(g) if g else None
 
 
-def create(title: str, description: str = "", *, rounds_max: int = 5,
+def create(title: str, description: str = "", *, rounds_max: int | None = None,
            metadata: dict | None = None) -> dict:
-    """创建新 goal。已有未完结 goal 时拒绝（单一当前目标，仿 dsh）。"""
+    """创建新 goal。已有未完结 goal 时拒绝（单一当前目标，仿 dsh）。
+
+    rounds_max 缺省读 settings_v2 orchestrator.max_goal_rounds（读不到回落 5）。"""
+    if rounds_max is None:
+        try:
+            from .settings_schema import get as ss_get, register_default_namespaces
+            register_default_namespaces()
+            rounds_max = int(ss_get("orchestrator", "max_goal_rounds") or 5)
+        except Exception:
+            rounds_max = 5
     with _LOCK:
         cur = current()
         if cur is not None:

package/app/core/jobs.py

@@ -449,6 +449,11 @@ def _worker():
                         _maybe_auto_resume(run_id)   # 连载失败自动续跑（继承已完成章）
                     except Exception:
                         pass
+                    try:
+                        from . import notify
+                        notify.push_run_async(run_id)   # 结果推群（借鉴 agency-orchestrator --notify）
+                    except Exception:
+                        pass
                 _QUEUE.task_done()
     finally:
         with _pool_lock:

package/app/core/market_remote.py

@@ -36,7 +36,7 @@ import zipfile
 from pathlib import Path
 from urllib.parse import urlparse
 
-from . import market
+from . import market, tlsctx
 
 _LOCK = market._LOCK   # 安装/记账与 market 共用一把锁，避免交叉写 market.json
 
@@ -157,10 +157,13 @@ def _fetch(url, cap=_CAP_MANIFEST):
         return b"".join(chunks)
 
     try:
-        return _read(lambda: urllib.request.urlopen(req, timeout=30))   # 默认 opener：含系统代理
+        return _read(lambda: urllib.request.urlopen(
+            req, timeout=30, context=tlsctx.context()))   # 默认 opener：含系统代理
     except (urllib.error.HTTPError, urllib.error.URLError):
         # 直连重试：ProxyHandler({}) 显式清空代理
-        opener = urllib.request.build_opener(urllib.request.ProxyHandler({}))
+        opener = urllib.request.build_opener(
+            urllib.request.ProxyHandler({}),
+            urllib.request.HTTPSHandler(context=tlsctx.context()))
         return _read(lambda: opener.open(req, timeout=30))
 
 

package/app/core/modelhub.py

@@ -41,7 +41,7 @@ import threading
 import time
 import urllib.request
 
-from . import paths
+from . import paths, tlsctx
 
 
 class _NoRedirect(urllib.request.HTTPRedirectHandler):
@@ -50,6 +50,13 @@ class _NoRedirect(urllib.request.HTTPRedirectHandler):
     def redirect_request(self, req, fp, code, msg, headers, newurl):
         return None
 
+
+def _opener():
+    """出站 opener：禁重定向 + tlsctx 兜底 CA（macOS python.org 版 Python
+    缺系统证书，默认上下文验证必挂——见 tlsctx 模块 docstring）。"""
+    return urllib.request.build_opener(
+        _NoRedirect, urllib.request.HTTPSHandler(context=tlsctx.context()))
+
 _LOCK = threading.RLock()
 _FILE = paths.DATA_DIR / "models.json"
 
@@ -206,11 +213,11 @@ def _fetch_models_http(base_url, api_key, protocol, allow_private=False):
     else:
         urls = std
     last_err = ""
-    opener = urllib.request.build_opener(_NoRedirect)
+    opener = _opener()
     for url in urls:
-        host_info = _validate_host(url, allow_private)
-        if host_info is None:
-            last_err = host_info[1]
+        host, herr = _validate_host(url, allow_private)
+        if host is None:
+            last_err = herr
             continue
         # auto 不知道是哪条 wire，鉴权头也按两种都试（google 那种单独补上）
         hdrs = _auth_header_variants(api_key, protocol)
@@ -237,6 +244,14 @@ def _fetch_models_http(base_url, api_key, protocol, allow_private=False):
                 if names:
                     return names, ""
                 last_err = url + " 返回 200 但未解析到模型"
+            except urllib.error.HTTPError as e:
+                if e.code == 404:
+                    # zcode-plan / open.bigmodel.cn 等 anthropic 形网关没有
+                    # GET /models——404 与密钥无关，模型以导入/手填为准
+                    last_err = (url + " 无模型列表接口（HTTP 404）——"
+                                "模型以导入/手动添加为准，不影响对话调用")
+                else:
+                    last_err = "%s → HTTP %s" % (url, e.code)
             except Exception as e:
                 last_err = "%s → %r" % (url, e)
     return None, last_err
@@ -1512,6 +1527,7 @@ def _src_zcode():
     default_model = str(d.get("model") or "")
     tail = default_model.split("/", 1)[1] if "/" in default_model else default_model
     bad = []
+    nokey = []
     for pid, p in (d.get("provider") or {}).items():
         if not isinstance(p, dict):
             continue
@@ -1523,13 +1539,23 @@ def _src_zcode():
                    "zcode", "zcode:%s" % pid,
                    model=(tail if tail in names else ""), models=names)
         if pr:
+            if not pr.get("api_key"):
+                nokey.append(str(p.get("name") or pid))
             out["providers"].append(pr)
         else:
             bad.append(str(p.get("name") or pid))
+    notes = []
     if bad:
-        out["note"] = "跳过 {0} 个（缺合法 baseURL）：{1}".format(
-            len(bad), "、".join(bad[:4]))
-        out["note_args"] = [len(bad), "、".join(bad[:4])]
+        notes.append("跳过 {0} 个（缺合法 baseURL）：{1}".format(
+            len(bad), "、".join(bad[:4])))
+    if nokey:
+        # ZCode 的 builtin Plan 条目（zcode.z.ai/api/v1/zcode-plan 等）密钥不入
+        # config.json（实测 credentials.json 里的 OAuth token 也不能直接当 API
+        # key 用）——静默导入空密钥条目只会让用户在拉列表/适配测试时一头雾水
+        notes.append("{0} 个未带出密钥——请在「模型接入」页手填：{1}".format(
+            len(nokey), "、".join(nokey[:4])))
+    if notes:
+        out["note"] = "；".join(notes)
     return out
 
 
@@ -2368,14 +2394,14 @@ def _post_json_http(url, headers, body, allow_private, timeout=20):
     p = urllib.parse.urlsplit(url)
     if p.scheme not in ("http", "https"):
         return 0, None, "协议必须是 http/https"
-    host_info = _validate_host(url, allow_private)
-    if host_info is None:
-        return 0, None, host_info[1]
+    host, herr = _validate_host(url, allow_private)
+    if host is None:
+        return 0, None, herr
     try:
         req = urllib.request.Request(url, method="POST",
                                      headers=dict(headers, **{"Content-Type": "application/json"}),
                                      data=json.dumps(body).encode("utf-8"))
-        with urllib.request.build_opener(_NoRedirect).open(req, timeout=timeout) as resp:
+        with _opener().open(req, timeout=timeout) as resp:
             raw = resp.read(1024 * 1024)
         return resp.status, json.loads(raw.decode("utf-8", "replace")), ""
     except Exception as e:
@@ -2440,15 +2466,16 @@ def _post_sse_http(url, headers, body, allow_private, timeout, proto, on_delta):
     p = urllib.parse.urlsplit(url)
     if p.scheme not in ("http", "https"):
         return 0, "", None, "协议必须是 http/https"
-    if _validate_host(url, allow_private) is None:
-        return 0, "", None, "目标地址校验未通过"
+    host, herr = _validate_host(url, allow_private)
+    if host is None:
+        return 0, "", None, herr
     parts, usage = [], {}
     resp_status = 0
     try:
         req = urllib.request.Request(url, method="POST",
                                      headers=dict(headers, **{"Content-Type": "application/json"}),
                                      data=json.dumps(body).encode("utf-8"))
-        with urllib.request.build_opener(_NoRedirect).open(req, timeout=timeout) as resp:
+        with _opener().open(req, timeout=timeout) as resp:
             resp_status = resp.status
             if not 200 <= resp.status < 300:
                 raw = resp.read(65536).decode("utf-8", "replace")

package/app/core/notify.py

@@ -0,0 +1,96 @@
+# -*- coding: utf-8 -*-
+"""运行结果群推送（借鉴 agency-orchestrator 的 --notify）：任务跑完把结果摘要
+推到钉钉/飞书/企业微信群机器人，配合定时自动化就是「AI 团队每天定点交活」。
+
+webhook 一个地址全包——按域名自动适配三种机器人格式（同 agency-orchestrator
+思路）；也接受任意 https 地址（按钉钉 text 形状发，自建 n8n 等自选）。
+推送在后台线程、失败只记日志——通知永远不影响任务本身。
+"""
+from __future__ import annotations
+
+import logging
+
+log = logging.getLogger(__name__)
+
+
+def _payload_for(webhook, text):
+    """按 webhook 域名适配群机器人消息体。返回 None = 无法识别的地址。"""
+    from urllib.parse import urlparse
+    host = (urlparse(webhook).hostname or "").lower()
+    if "dingtalk" in host:
+        return {"msgtype": "text", "text": {"content": text}}
+    if "feishu" in host or "larksuite" in host:
+        return {"msg_type": "text", "content": {"text": text}}
+    if "weixin" in host or "wechat" in host or "work.weixin" in host:
+        return {"msgtype": "text", "text": {"content": text}}
+    if host:
+        return {"msgtype": "text", "text": {"content": text}}   # 未知域名按钉钉形状
+    return None
+
+
+def _webhook():
+    try:
+        from . import settings
+        return str(settings.load().get("notify_webhook") or "").strip()
+    except Exception:
+        return ""
+
+
+def _post(hook, text):
+    """curl 子进程 POST（Python 不经手响应体）；网络失败只记日志。"""
+    from . import runner
+    import json as _json
+    body = _json.dumps(_payload_for(hook, text), ensure_ascii=False)
+    r = runner.run_process(
+        argv=["curl", "-sS", "--max-time", "20",
+              "-H", "Content-Type: application/json",
+              "-d", body, hook],
+        timeout=30)
+    return bool(r["ok"])
+
+
+def push_text(text):
+    """推一条文本到群。配置了 webhook 才推；失败返回 False 不抛错。"""
+    hook = _webhook()
+    if not hook:
+        return False
+    if not hook.startswith("https://"):
+        log.warning("notify webhook 必须是 https")
+        return False
+    try:
+        return _post(hook, text)
+    except Exception as e:
+        log.warning("notify push failed: %s", e)
+        return False
+
+
+def push_run_async(run_id):
+    """任务收尾后异步推送结果摘要（jobs 层调用；绝不阻塞/影响任务）。"""
+    threading.Thread(target=push_run, daemon=True,
+                     name="notify-%s" % run_id, args=(run_id,)).start()
+
+
+def push_run(run_id):
+    """组装 run 结果摘要并推送（webhook 未配置时静默跳过）。"""
+    hook = _webhook()
+    if not hook:
+        return False
+    from . import store
+    run = store.get_run(run_id) or {}
+    if not run:
+        return False
+    status = str(run.get("status") or "")
+    mark = {"done": "✅", "failed": "❌", "cancelled": "⚪"}.get(status, "🔔")
+    lines = ["%s CodeBee 任务%s" % (mark, {"done": "完成", "failed": "失败",
+                                           "cancelled": "已取消"}.get(status, status))]
+    lines.append("任务：%s" % (run.get("title") or run_id))
+    if run.get("error"):
+        lines.append("错误：%s" % str(run["error"])[:200])
+    v = run.get("verdict") or {}
+    if v.get("overall") is not None:
+        lines.append("综合评分 %.1f（%s）" % (
+            float(v["overall"]), "达标" if v.get("publishable") else "未达标"))
+    return push_text("\n".join(lines))
+
+
+import threading  # noqa: E402  （push_run_async 依赖；置底避免顶部循环导入）

package/app/core/paihang.py

@@ -0,0 +1,65 @@
+# -*- coding: utf-8 -*-
+"""扫榜选材：抓取七猫排行榜公开页，产出选题分析素材。
+
+数据源：www.qimao.com/paihang/（公开可抓，2026-09-19 实测 200/106KB，
+书名与分类在 a 标签中文文本里）。下载走 curl 子进程（与 covergen 同款，
+Python 不经手响应体以外的东西），解析用宽松正则——页面结构变了宁可
+返回空（调用方回落普通直连提示词），不做脆弱的强解析。
+"""
+from __future__ import annotations
+
+import logging
+import re
+
+log = logging.getLogger(__name__)
+
+RANK_URL = "https://www.qimao.com/paihang/"
+_UA = ("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 "
+       "(KHTML, like Gecko) Chrome/126 Safari/537.36")
+
+# 页面 UI 噪音词（非书目/分类）
+_NOISE = {"加入书架", "立即阅读", "开始阅读", "免费阅读", "全部", "分类", "排行",
+          "排行榜", "完本", "连载中", "阅读", "书城", "男生", "女生"}
+
+
+def fetch_rank_items(limit=40):
+    """抓七猫排行榜页并提取中文元素材（书名/分类混排，去 UI 噪音）。
+
+    返回元素列表（保序去重，最多 limit 个）；抓取失败返回 []——调用方
+    回落普通直连提示词，扫榜永远不挡任务。"""
+    from . import runner
+    try:
+        r = runner.run_process(
+            argv=["curl", "-sS", "--max-time", "20", "-A", _UA, RANK_URL],
+            timeout=30)
+    except Exception:
+        return []
+    if not r.get("ok"):
+        return []
+    items, seen = [], set()
+    for t in re.findall(r">([\u4e00-\u9fa5]{2,12})<", r.get("stdout") or ""):
+        if t in _NOISE or t in seen:
+            continue
+        seen.add(t)
+        items.append(t)
+        if len(items) >= limit:
+            break
+    return items
+
+
+def rank_scan_prompt(goal):
+    """组装扫榜选材分析提示词。榜单抓取失败返回 None（调用方回落直连提示词）。"""
+    items = fetch_rank_items()
+    if not items:
+        return None
+    material = "、".join(items)
+    return (
+        "你是网文选题分析师。以下是刚刚抓取的七猫排行榜页面的书目与分类素材：\n\n"
+        "## 榜单元素材\n%s\n\n"
+        "## 用户想写的方向\n%s\n\n"
+        "## 你的产出（Markdown 报告）\n"
+        "1. **热门题材 Top3**：各自的共同特征与上榜代表书目\n"
+        "2. **高频人设/套路总结**：3-5 条，点名反复出现的元素\n"
+        "3. **差异化切入建议**：2-3 个，结合用户方向给出「题材+人设」组合与一句话理由\n"
+        "直接输出分析报告，不要复述素材清单，不要输出与报告无关的内容。"
+        % (material, goal or "（用户未指定方向，按大盘热门分析）"))