chore: auto release commit (2026-09-15 00:32:44)

scripts/cli/app.py

@@ -279,6 +279,72 @@ def cmd_parse_materials(args: argparse.Namespace) -> int:
         conn.close()
 
 
+def cmd_import_input(_args: argparse.Namespace) -> int:
+    """扫描 data/input/{contracts,materials}/ 自动入库。
+
+    约定：
+      input/contracts/*.csv         → contracts 表 upsert
+      input/materials/{cid}__{f}.pdf → materials_content (parse_method='pending')
+    """
+    from service.importer import import_input_dir
+
+    conn = get_connection()
+    try:
+        result = import_input_dir(conn)
+    finally:
+        conn.close()
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+def cmd_download_materials(args: argparse.Namespace) -> int:
+    """处理 download_tasks 队列：抓 pending 任务的材料 → 落库。
+
+    --ids "DLQ-xxx,DLQ-yyy": 只处理这些任务
+    --pick N: 无 --ids 时从 pending 领取 N 条（默认 5）
+    --limit N: 本次硬上限（默认 0 = 不限）
+    --headless: 无头模式（需要 profile cookie 已保存）
+    """
+    try:
+        result = platform_collector.process_queue(
+            limit=args.limit or args.pick,
+            ids_filter=args.ids,
+            headless=args.headless,
+            human_wait_timeout=args.human_wait_timeout or HUMAN_WAIT_TIMEOUT,
+        )
+    except platform_collector.RPAError as e:
+        print(json.dumps({
+            "error": e.code,
+            "detail": str(e),
+            "processed": 0, "succeeded": 0, "failed": 0, "details": [],
+        }, ensure_ascii=False, indent=2))
+        return 2
+    except Exception as e:
+        print(json.dumps({"error": "exception", "detail": str(e)},
+                         ensure_ascii=False, indent=2))
+        return 1
+
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
+def cmd_show_config(_args: argparse.Namespace) -> int:
+    """查看 .env 非空配置（敏感字段自动脱敏）。"""
+    from service.config_viewer import read_env_config
+
+    print(json.dumps(read_env_config(), ensure_ascii=False, indent=2))
+    return 0
+
+
+def cmd_logs_list(args: argparse.Namespace) -> int:
+    """读取日志末尾 N 行（默认 200）。"""
+    from service.logs_viewer import tail_log_file
+
+    result = tail_log_file(tail=args.tail, min_level=args.level)
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    return 0
+
+
 # ---------- argparse ----------
 
 def _parse_thresholds(s: str) -> tuple[int, int, int]:
@@ -360,6 +426,41 @@ def build_parser() -> argparse.ArgumentParser:
                     help="仅解析该合同（留空=处理所有 pending）")
     sp.set_defaults(handler=cmd_parse_materials)
 
+    sp = sub.add_parser(
+        "download-materials",
+        help="处理材料下载队列（pending 任务 → 浏览器抓取 → 落库）",
+    )
+    sp.add_argument("--limit", type=int, default=0, help="本次最多处理任务数（0 = 用 --pick）")
+    sp.add_argument("--ids", default="", help="逗号分隔 task_id 列表（仅处理这些 pending 任务）")
+    sp.add_argument("--pick", type=int, default=5, help="无 --ids 时从 pending 领取条数（默认 5）")
+    sp.add_argument("--headless", action="store_true", help="无头模式（需已保存 profile）")
+    sp.add_argument("--show-browser", dest="headless", action="store_false",
+                    help=argparse.SUPPRESS)
+    sp.add_argument("--human-wait-timeout", type=int, default=None,
+                    help="手工登录 fallback 等待秒数（默认 180 = HUMAN_WAIT_TIMEOUT）")
+    sp.set_defaults(headless=False, handler=cmd_download_materials)
+
+    sp = sub.add_parser(
+        "import-input",
+        help="扫描 data/input/{contracts,materials}/ 自动入库",
+    )
+    sp.set_defaults(handler=cmd_import_input)
+
+    sp = sub.add_parser(
+        "show-config",
+        help="查看 .env 配置（敏感字段自动脱敏）",
+    )
+    sp.set_defaults(handler=cmd_show_config)
+
+    sp = sub.add_parser(
+        "logs-list",
+        help="查看运行日志末尾 N 行",
+    )
+    sp.add_argument("--tail", type=int, default=200, help="末尾行数（默认 200）")
+    sp.add_argument("--level", default="INFO",
+                    help="最低级别 DEBUG/INFO/WARNING/ERROR（默认 INFO）")
+    sp.set_defaults(handler=cmd_logs_list)
+
     return p
 
 
@@ -370,7 +471,8 @@ def main(argv: Optional[List[str]] = None) -> int:
         print("Commands: health, version, config-path, init-db, "
               "scan-expiring-contracts, generate-renewal-task, "
               "dispatch-task-notice, mark-contract-renewed, render-html, "
-              "collect-from-platform, parse-materials")
+              "collect-from-platform, parse-materials, download-materials, "
+              "import-input, show-config, logs-list")
         return 1
 
     setup_skill_logging()

scripts/db/connection.py

@@ -90,6 +90,25 @@ DDL_STATEMENTS: tuple[str, ...] = (
     );
     """,
     "CREATE INDEX IF NOT EXISTS idx_dispatch_unit_month ON dispatch_log(unit_id, month);",
+    # 7. download_tasks (v1.1.18)
+    """
+    CREATE TABLE IF NOT EXISTS download_tasks (
+        task_id      TEXT PRIMARY KEY,
+        contract_id  TEXT NOT NULL,
+        kind         TEXT NOT NULL DEFAULT 'platform_button',
+        status       TEXT NOT NULL DEFAULT 'pending',
+        attempts     INTEGER NOT NULL DEFAULT 0,
+        error_msg    TEXT,
+        enqueued_at  TEXT NOT NULL,
+        started_at   TEXT,
+        finished_at  TEXT,
+        source_path  TEXT,
+        result_path  TEXT,
+        FOREIGN KEY (contract_id) REFERENCES contracts(contract_id)
+    );
+    """,
+    "CREATE INDEX IF NOT EXISTS idx_dlq_status ON download_tasks(status);",
+    "CREATE INDEX IF NOT EXISTS idx_dlq_contract ON download_tasks(contract_id);",
 )
 
 
@@ -131,6 +150,7 @@ def init_db(db_path: Path | None = None) -> dict[str, int]:
             "renewal_tasks": conn.execute("SELECT COUNT(*) AS n FROM renewal_tasks").fetchone()["n"],
             "dispatch_log": conn.execute("SELECT COUNT(*) AS n FROM dispatch_log").fetchone()["n"],
             "materials_content": conn.execute("SELECT COUNT(*) AS n FROM materials_content").fetchone()["n"],
+            "download_tasks": conn.execute("SELECT COUNT(*) AS n FROM download_tasks").fetchone()["n"],
         }
         return counts
     finally:
@@ -140,5 +160,5 @@ def init_db(db_path: Path | None = None) -> dict[str, int]:
 def table_names() -> Iterable[str]:
     return (
         "contracts", "performance_records", "alerts", "renewal_tasks",
-        "dispatch_log", "materials_content",
+        "dispatch_log", "materials_content", "download_tasks",
     )

scripts/db/repository.py

@@ -294,6 +294,59 @@ def list_dispatch_logs(conn: sqlite3.Connection) -> list[sqlite3.Row]:
 
 # ---------- materials_content（v1.1.1 新增） ----------
 
+def upsert_contract_from_csv_row(
+    conn: sqlite3.Connection, row: dict[str, str]
+) -> None:
+    """从 CSV 字典 upsert 一份合同。CSV 列名必须与 contracts 表列一致（或常见别名）。
+
+    缺字段兜底值：
+      employee_id      = contract_id
+      teacher_name     = ""
+      unit_id          = "U-UNKNOWN"
+      unit_name        = ""
+      position         = ""
+      contract_type    = ""
+      contract_start   = "1970-01-01"
+      contract_end     = "2099-12-31"
+      trial_period_end = contract_end
+      status           = "可续聘"
+    """
+    cid = row.get("contract_id") or row.get("合同ID") or ""
+    if not cid:
+        raise ValueError("CSV row missing contract_id / 合同ID")
+    conn.execute(
+        """
+        INSERT INTO contracts
+            (contract_id, employee_id, teacher_name, unit_id, unit_name,
+             position, contract_type, contract_start, contract_end,
+             trial_period_end, status, last_material_id, renewed_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, NULL)
+        ON CONFLICT(contract_id) DO UPDATE SET
+            teacher_name     = excluded.teacher_name,
+            unit_name        = excluded.unit_name,
+            position         = excluded.position,
+            contract_type    = excluded.contract_type,
+            contract_start   = excluded.contract_start,
+            contract_end     = excluded.contract_end,
+            trial_period_end = excluded.trial_period_end,
+            status           = excluded.status
+        """,
+        (
+            cid,
+            row.get("employee_id") or row.get("工号") or cid,
+            row.get("teacher_name") or row.get("教职工姓名") or "",
+            row.get("unit_id") or row.get("单位ID") or "U-UNKNOWN",
+            row.get("unit_name") or row.get("单位") or "",
+            row.get("position") or row.get("岗位") or "",
+            row.get("contract_type") or row.get("合同类型") or "",
+            row.get("contract_start") or row.get("合同起始日") or "1970-01-01",
+            row.get("contract_end") or row.get("合同到期日") or "2099-12-31",
+            row.get("trial_period_end") or row.get("试用期截止") or row.get("contract_end") or "2099-12-31",
+            row.get("status") or "可续聘",
+        ),
+    )
+
+
 def list_materials_for_contract(
     conn: sqlite3.Connection, contract_id: str
 ) -> list[sqlite3.Row]:
@@ -373,3 +426,124 @@ def summarize_materials(
     if len(summary) > 16000:
         summary = summary[:16000] + "\n...(材料过长已截断)"
     return (summary, file_names)
+
+
+# ---------- download_tasks（v1.1.18 新增） ----------
+
+
+def enqueue_download_task(
+    conn: sqlite3.Connection,
+    contract_id: str,
+    kind: str = "platform_button",
+) -> str:
+    """入队一个下载任务，返回 task_id。
+
+    已存在 (contract_id, kind, status ∈ {pending, running}) 时跳过（返回已存在的 task_id）。
+    """
+    import uuid
+
+    existing = conn.execute(
+        """SELECT task_id FROM download_tasks
+           WHERE contract_id = ? AND kind = ? AND status IN ('pending', 'running')
+           LIMIT 1""",
+        (contract_id, kind),
+    ).fetchone()
+    if existing:
+        return existing["task_id"]
+    task_id = f"DLQ-{uuid.uuid4().hex[:12]}"
+    conn.execute(
+        """
+        INSERT INTO download_tasks
+            (task_id, contract_id, kind, status, attempts, enqueued_at)
+        VALUES (?, ?, ?, 'pending', 0, ?)
+        """,
+        (task_id, contract_id, kind, datetime.now().isoformat(timespec="seconds")),
+    )
+    return task_id
+
+
+def _read_max_attempts(conn: sqlite3.Connection) -> int:
+    """读 DOWNLOAD_QUEUE_MAX_ATTEMPTS env（默认 3）。"""
+    import os
+    return int(os.environ.get("DOWNLOAD_QUEUE_MAX_ATTEMPTS", "3"))
+
+
+def claim_pending_tasks(
+    conn: sqlite3.Connection, limit: int, ids_filter: list[str] | None = None,
+) -> list[sqlite3.Row]:
+    """原子领取一批 pending 任务，标记为 running。
+
+    - limit: 最多领取条数
+    - ids_filter: 若给出，仅从这些 task_id 中领
+    """
+    max_attempts = _read_max_attempts(conn)
+    if ids_filter:
+        placeholders = ",".join("?" for _ in ids_filter)
+        rows = conn.execute(
+            f"""SELECT * FROM download_tasks
+                WHERE status = 'pending' AND attempts < ?
+                AND task_id IN ({placeholders})
+                ORDER BY enqueued_at ASC LIMIT ?""",
+            [max_attempts, *ids_filter, limit],
+        ).fetchall()
+    else:
+        rows = conn.execute(
+            """SELECT * FROM download_tasks
+               WHERE status = 'pending' AND attempts < ?
+               ORDER BY enqueued_at ASC LIMIT ?""",
+            (max_attempts, limit),
+        ).fetchall()
+    if not rows:
+        return []
+    now = datetime.now().isoformat(timespec="seconds")
+    for r in rows:
+        conn.execute(
+            "UPDATE download_tasks SET status = 'running', started_at = ? WHERE task_id = ?",
+            (now, r["task_id"]),
+        )
+    conn.commit()
+    return rows
+
+
+def mark_task_success(
+    conn: sqlite3.Connection, task_id: str, result_path: str,
+) -> None:
+    conn.execute(
+        """UPDATE download_tasks
+           SET status = 'success', result_path = ?, finished_at = ?
+           WHERE task_id = ?""",
+        (result_path, datetime.now().isoformat(timespec="seconds"), task_id),
+    )
+
+
+def mark_task_failed(
+    conn: sqlite3.Connection, task_id: str, error_msg: str,
+) -> None:
+    """失败一次：attempts+1，未超 max_attempts 则回退 pending，否则标 failed。"""
+    max_attempts = _read_max_attempts(conn)
+    now = datetime.now().isoformat(timespec="seconds")
+    conn.execute(
+        """UPDATE download_tasks
+           SET status = CASE WHEN attempts + 1 >= ? THEN 'failed' ELSE 'pending' END,
+               attempts = attempts + 1,
+               error_msg = ?,
+               finished_at = ?
+           WHERE task_id = ?""",
+        (max_attempts, error_msg, now, task_id),
+    )
+
+
+def list_recent_tasks(
+    conn: sqlite3.Connection, limit: int = 50
+) -> list[sqlite3.Row]:
+    return conn.execute(
+        "SELECT * FROM download_tasks ORDER BY enqueued_at DESC LIMIT ?",
+        (limit,),
+    ).fetchall()
+
+
+def count_tasks_by_status(conn: sqlite3.Connection) -> dict[str, int]:
+    rows = conn.execute(
+        "SELECT status, COUNT(*) AS n FROM download_tasks GROUP BY status"
+    ).fetchall()
+    return {r["status"]: r["n"] for r in rows}

scripts/service/config_viewer.py

@@ -0,0 +1,77 @@
+"""读取并脱敏 .env 配置供 UI 查看（v1.1.18）。
+
+仅显示 .env 文件中的非空 key；命中 (TOKEN|SECRET|KEY|PASSWORD) 的字段自动脱敏为 ***。
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from util.runtime_paths import get_env_path
+
+
+# 匹配任一含 TOKEN / SECRET / KEY / PASSWORD 的 key 名（不区分大小写）
+_SECRET_PATTERN = re.compile(r"(TOKEN|SECRET|KEY|PASSWORD)", re.IGNORECASE)
+
+
+def _parse_env_file(path: Path) -> dict[str, str]:
+    """手动解析 .env（避免依赖 python-dotenv）。
+
+    - 跳过空行 / 注释（# 开头）
+    - 支持 KEY=VALUE 格式
+    - 自动去除包裹的 "..." 或 '...'
+    """
+    if not path.exists():
+        return {}
+    result: dict[str, str] = {}
+    with open(path, "r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if not line or line.startswith("#"):
+                continue
+            if "=" not in line:
+                continue
+            k, _, v = line.partition("=")
+            k = k.strip()
+            v = v.strip()
+            # 去掉行尾注释（不处理引号内的 #，简单实现）
+            if " #" in v:
+                v = v.split(" #", 1)[0].strip()
+            if v.startswith('"') and v.endswith('"') and len(v) >= 2:
+                v = v[1:-1]
+            elif v.startswith("'") and v.endswith("'") and len(v) >= 2:
+                v = v[1:-1]
+            result[k] = v
+    return result
+
+
+def _mask_secret(value: str) -> str:
+    if not value:
+        return ""
+    if len(value) <= 4:
+        return "***"
+    return value[:2] + "***" + value[-2:]
+
+
+def read_env_config() -> dict:
+    """读取 .env 中的非空 key，敏感 key 脱敏为 ***。
+
+    Returns:
+        {
+            "env_path": str,
+            "exists": bool,
+            "config": {key: value_or_masked_value, ...}
+        }
+    """
+    path = get_env_path()
+    parsed = _parse_env_file(path)
+    out: dict[str, str] = {}
+    for k, v in sorted(parsed.items()):
+        if not v:
+            continue
+        if _SECRET_PATTERN.search(k):
+            out[k] = _mask_secret(v)
+        else:
+            out[k] = v
+    return {"env_path": str(path), "exists": path.exists(), "config": out}

scripts/service/importer.py

@@ -0,0 +1,111 @@
+"""主动扫描 data/input/{contracts,materials}/：CSV → contracts 表，PDF/Word → materials_content 表。
+
+对 sandbox 用户尤其重要：HR API 拿不到时，把材料直接丢进 input/materials/ 即可被自动识别。
+
+约定：
+  - input/contracts/*.csv
+      列名与 contracts 表一致（contract_id / teacher_name / unit_name / contract_end / ...）
+      也兼容中文别名（合同ID / 教职工姓名 / 单位 / 合同到期日 / 工号 / 岗位 / 合同类型）
+  - input/materials/{contract_id}__{filename}.{pdf|docx|doc}
+      文件名 __ 之前是 contract_id；无 __ 时回退 parent dir 名
+      拷贝到 data/materials/ + insert materials_content(parse_method='pending')
+"""
+
+from __future__ import annotations
+
+import csv
+import shutil
+import sqlite3
+from pathlib import Path
+
+from db import repository as repo
+from db.migrations import ensure_materials_content_schema
+from util.logging_setup import get_skill_logger
+from util.runtime_paths import (
+    get_data_dir,
+    get_input_contracts_dir,
+    get_input_materials_dir,
+)
+
+logger = get_skill_logger()
+
+MATERIAL_EXTS = {".pdf", ".docx", ".doc"}
+
+
+def _derive_contract_id_from_filename(mat_path: Path) -> str:
+    """从文件名推导 contract_id。约定：{contract_id}__{filename}.{ext}。"""
+    parts = mat_path.stem.split("__", 1)
+    if len(parts) == 2 and parts[0]:
+        return parts[0]
+    # 兜底：parent dir 名
+    return mat_path.parent.name or "UNKNOWN"
+
+
+def import_input_dir(conn: sqlite3.Connection) -> dict:
+    """扫描 input 目录 → 入库。返回统计 dict。
+
+    Returns:
+        {
+            "contracts_added": int,
+            "materials_added": int,
+            "files_scanned": int,
+            "errors": [str, ...],
+        }
+    """
+    ensure_materials_content_schema(conn)
+
+    contracts_dir = get_input_contracts_dir()
+    materials_dir = get_input_materials_dir()
+
+    contracts_added = 0
+    materials_added = 0
+    files_scanned = 0
+    errors: list[str] = []
+
+    # 1. CSV → contracts（contract_id 重复 → upsert 覆盖）
+    for csv_path in sorted(contracts_dir.glob("*.csv")):
+        files_scanned += 1
+        try:
+            with open(csv_path, "r", encoding="utf-8", newline="") as f:
+                reader = csv.DictReader(f)
+                for row in reader:
+                    if not row.get("contract_id") and not row.get("合同ID"):
+                        errors.append(f"{csv_path.name}: row 缺 contract_id 跳过")
+                        continue
+                    repo.upsert_contract_from_csv_row(conn, row)
+                    contracts_added += 1
+        except Exception as e:
+            errors.append(f"{csv_path.name}: {e}")
+            logger.warning("importer: CSV 解析失败 %s: %s", csv_path, e)
+
+    # 2. PDF/Word → materials_content（parse_method='pending'），文件拷贝到 data/materials/
+    materials_target_dir = get_data_dir() / "materials"
+    materials_target_dir.mkdir(parents=True, exist_ok=True)
+    for mat_path in sorted(materials_dir.iterdir()):
+        if not mat_path.is_file() or mat_path.suffix.lower() not in MATERIAL_EXTS:
+            continue
+        files_scanned += 1
+        try:
+            contract_id = _derive_contract_id_from_filename(mat_path)
+            target = materials_target_dir / mat_path.name
+            if not target.exists():
+                shutil.copy2(mat_path, target)
+            repo.insert_material(
+                conn, contract_id, mat_path.name, str(target),
+                None, "pending",
+            )
+            materials_added += 1
+            logger.info(
+                "importer: 入库 %s → contract_id=%s", mat_path.name, contract_id,
+            )
+        except Exception as e:
+            errors.append(f"{mat_path.name}: {e}")
+            logger.warning("importer: 材料导入失败 %s: %s", mat_path, e)
+
+    conn.commit()
+    return {
+        "contracts_added": contracts_added,
+        "materials_added": materials_added,
+        "files_scanned": files_scanned,
+        "errors": errors,
+    }

scripts/service/logs_viewer.py

@@ -0,0 +1,86 @@
+"""读取日志文件末尾 N 行（v1.1.18）。
+
+按 level 过滤：默认 INFO+。适用于 RotatingFileHandler 落地的日志文件。
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from util.runtime_paths import get_logs_dir
+
+
+DEFAULT_TAIL = 200
+_LEVEL_ORDER = {
+    "DEBUG": 10, "INFO": 20, "WARNING": 30, "ERROR": 40, "CRITICAL": 50,
+}
+
+
+def _resolve_log_path() -> Path:
+    """解析日志文件路径。
+
+    优先级：
+      1. LOG_FILE env（绝对路径直接用，相对路径走 get_logs_dir()）
+      2. 默认 get_logs_dir() / LOG_FILE_DEFAULT_NAME
+    """
+    raw = os.environ.get("LOG_FILE", "")
+    if raw:
+        p = Path(raw)
+        if not p.is_absolute():
+            p = get_logs_dir() / raw
+        return p
+    from util.constants import LOG_FILE_DEFAULT_NAME
+    return get_logs_dir() / LOG_FILE_DEFAULT_NAME
+
+
+def tail_log_file(tail: int = DEFAULT_TAIL, min_level: str = "INFO") -> dict:
+    """读日志文件末尾 tail 行，过滤 level >= min_level。
+
+    Returns:
+        {
+            "log_file": str,
+            "exists": bool,
+            "total_lines": int,
+            "returned_lines": int,
+            "lines": [str, ...],
+            "min_level": str,
+        }
+    """
+    log_path = _resolve_log_path()
+    if not log_path.exists():
+        return {
+            "log_file": str(log_path),
+            "exists": False,
+            "total_lines": 0,
+            "returned_lines": 0,
+            "lines": [],
+            "min_level": min_level,
+        }
+
+    text = log_path.read_text(encoding="utf-8", errors="replace")
+    all_lines = text.splitlines()
+    last_n = all_lines[-tail:] if tail > 0 else all_lines
+    threshold = _LEVEL_ORDER.get(min_level.upper(), 20)
+
+    filtered: list[str] = []
+    for line in last_n:
+        # 格式: "2026-09-15 12:34:56 [alert-contract-expiring-hr] INFO message"
+        # 取第 4 个 token (INFO/DEBUG/...)
+        parts = line.split()
+        if len(parts) >= 4 and parts[1].count(":") >= 2 and parts[3] in _LEVEL_ORDER:
+            line_level = parts[3]
+            if _LEVEL_ORDER.get(line_level, 0) >= threshold:
+                filtered.append(line)
+        else:
+            # 非标准行 / 解析不到 level：保留
+            filtered.append(line)
+
+    return {
+        "log_file": str(log_path),
+        "exists": True,
+        "total_lines": len(all_lines),
+        "returned_lines": len(filtered),
+        "lines": filtered,
+        "min_level": min_level,
+    }

scripts/service/platform_collector.py

@@ -865,11 +865,265 @@ def _persist_contracts(contracts: list[dict]) -> int:
                                 datetime.now().isoformat(timespec="seconds"),
                             ),
                         )
+                # v1.1.18：每个合同入队 download_tasks（即使已抓到卡片也入队，
+                # process_queue 失败时可用作重试锚点；enqueue_download_task 幂等）
+                repo.enqueue_download_task(conn, c["contract_id"], "platform_button")
         return len(contracts)
     finally:
         conn.close()
 
 
+def _download_materials_for_row(
+    page, row_idx: int, contract_id: str, mat_btn_count: int,
+) -> list[dict]:
+    """点续聘材料包按钮抓卡片文本（与 v1.1.17 collect_all 内联逻辑等价）。
+
+    返回 materials 列表（kind=sandbox_card，含 file_name + text）。
+    """
+    if mat_btn_count == 0:
+        return []
+    materials: list[dict] = []
+    try:
+        btn = page.locator("table tbody tr").nth(row_idx).locator(
+            "button:has-text('续聘材料包')"
+        )
+        btn.click()
+        page.wait_for_timeout(CARD_APPEAR_WAIT_MS)
+        cards_text = page.locator(
+            "main .grid > div, main > div > div > div"
+        ).all_inner_texts()
+        materials_text = "\n\n".join(t.strip() for t in cards_text if t.strip())
+        if materials_text:
+            materials.append({
+                "kind": "sandbox_card",
+                "file_name": f"{contract_id}_materials.txt",
+                "text": materials_text,
+            })
+            logger.info(
+                "platform_collector: 抓到卡片文本 %d 字 (%s)",
+                len(materials_text), contract_id,
+            )
+    except Exception as e:
+        logger.warning("抓卡片失败 %s: %s", contract_id, e)
+    return materials
+
+
+def _find_row_for_contract(page, contract_id: str) -> int | None:
+    """在 hr/contracts 表格中找 contract_id 所在行号。
+
+    支持 7 列（用 teacher_name 派生 contract_id）与 10 列（用 emp_id）。
+    不匹配返回 None（调用方 mark_task_failed）。
+    """
+    rows = page.eval_on_selector_all(
+        "table tbody tr",
+        "rs => rs.map(r => Array.from(r.querySelectorAll('td')).map(td => td.innerText))",
+    )
+    for i, r in enumerate(rows):
+        ncols = len(r)
+        if ncols < 6:
+            continue
+        first_col = r[0].strip()
+        is_emp_id = bool(re.match(r"^[A-Za-z]?\d+$", first_col))
+        if is_emp_id and ncols >= 9:
+            emp_id, contract_end = first_col, r[5].split("~")[-1].strip()
+        elif ncols >= 6:
+            emp_id, contract_end = first_col, r[2].strip()
+        else:
+            continue
+        candidate = _gen_contract_id(emp_id, contract_end)
+        if candidate == contract_id:
+            return i
+    return None
+
+
+def process_queue(
+    limit: int = 5,
+    headless: bool = True,
+    human_wait_timeout: int = HUMAN_WAIT_TIMEOUT,
+    ids_filter: str = "",
+) -> dict:
+    """从 download_tasks 队列取 pending 任务，对每个合同重新走材料抓取。
+
+    与 collect_all 重复登录流程，但每行只点「续聘材料包」按钮抓卡片，不重新抓合同表。
+
+    参数：
+      limit: 本次最多处理任务数（0 = 不限）
+      ids_filter: 逗号分隔 task_id 列表（只处理这些 pending）
+      headless: 无头模式（需要 profile cookie 已保存）
+      human_wait_timeout: 手工登录 fallback 等待秒数
+
+    返回 {processed, succeeded, failed, details}。
+    """
+    try:
+        from playwright.sync_api import sync_playwright
+    except ImportError:
+        logger.error("playwright 未安装，跳过队列处理")
+        return {"processed": 0, "succeeded": 0, "failed": 0, "details": [],
+                "error": "playwright_not_installed"}
+
+    from db.connection import get_connection
+
+    # 1. 领取一批任务
+    ids_list = [s.strip() for s in ids_filter.split(",") if s.strip()] if ids_filter else None
+    conn = get_connection()
+    try:
+        tasks = repo.claim_pending_tasks(
+            conn,
+            limit=limit if limit > 0 else 999,
+            ids_filter=ids_list,
+        )
+    finally:
+        conn.close()
+
+    if not tasks:
+        return {"processed": 0, "succeeded": 0, "failed": 0, "details": []}
+
+    profile_dir = _safe_getenv_dir("SMARTCAMPUS_PROFILE_DIR", "playwright-profile")
+    download_dir = _safe_getenv_dir("MATERIALS_DOWNLOAD_DIR", "materials")
+    profile_dir.mkdir(parents=True, exist_ok=True)
+    download_dir.mkdir(parents=True, exist_ok=True)
+
+    details: list[dict] = []
+    succeeded = 0
+    failed = 0
+
+    with sync_playwright() as p:
+        ctx = p.chromium.launch_persistent_context(
+            user_data_dir=str(profile_dir),
+            headless=headless,
+            accept_downloads=True,
+            viewport={"width": 1440, "height": 900},
+            channel="msedge" if not headless else None,
+        ) if not headless else p.chromium.launch_persistent_context(
+            user_data_dir=str(profile_dir),
+            headless=True,
+            accept_downloads=True,
+            viewport={"width": 1440, "height": 900},
+        )
+        try:
+            page = ctx.new_page()
+            page.set_default_timeout(DEFAULT_PAGE_TIMEOUT_MS)
+
+            # 登录：复用 v1.1.17 collect_all 的探针 + 自动 fill + 手工 fallback 流程
+            logger.info("platform_collector.process_queue: 启动 profile=%s headless=%s 待处理 %d",
+                        profile_dir, headless, len(tasks))
+            _goto(page, SPA_HOME_URL)
+            page.wait_for_timeout(SPA_HYDRATION_MS)
+            if _is_logged_in(page):
+                logger.info("platform_collector.process_queue: ✅ 已登录态")
+            else:
+                _goto(page, SPA_LOGIN_URL)
+                page.wait_for_timeout(SPA_HYDRATION_MS)
+                if not _fill_spa_login(page):
+                    if not headless:
+                        _wait_for_manual_login(page, wait_sec=human_wait_timeout)
+                    else:
+                        raise LoginTimeoutError("process_queue headless 自动 fill 失败")
+                else:
+                    page.wait_for_timeout(POST_LOGIN_SETTLE_MS)
+
+            # 强制 goto SPA_HOME + 侧边栏 hr/contracts
+            for _ in range(SPA_HOME_RETRY_MAX):
+                if _is_logged_in(page):
+                    break
+                _goto(page, SPA_HOME_URL)
+                page.wait_for_timeout(SPA_HOME_RETRY_DELAY_MS)
+                if _fill_spa_login(page):
+                    page.wait_for_timeout(POST_LOGIN_SETTLE_MS)
+            if not _is_logged_in(page):
+                raise LoginTimeoutError("process_queue 仍未登录")
+
+            # 等表格
+            page.wait_for_timeout(TABLE_INITIAL_WAIT_MS)
+            found_table = False
+            for _attempt in range(TABLE_POLL_MAX_ATTEMPTS):
+                page.wait_for_timeout(TABLE_POLL_INTERVAL_MS)
+                try:
+                    page.wait_for_selector(
+                        "table tbody tr", timeout=TABLE_TR_TIMEOUT_MS,
+                    )
+                    found_table = True
+                    break
+                except Exception:
+                    pass
+            if not found_table:
+                raise TableNotFoundError("process_queue 表格未找到")
+
+            mat_btn_count = page.locator(
+                "table tbody tr button:has-text('续聘材料包')"
+            ).count()
+
+            # 2. 逐任务处理
+            for t in tasks:
+                contract_id = t["contract_id"]
+                task_id = t["task_id"]
+                conn = get_connection()
+                try:
+                    row_idx = _find_row_for_contract(page, contract_id)
+                    if row_idx is None:
+                        repo.mark_task_failed(conn, task_id, "contract_not_found_in_table")
+                        failed += 1
+                        details.append({"task_id": task_id, "contract_id": contract_id,
+                                        "error": "contract_not_found_in_table"})
+                        conn.commit()
+                        continue
+                    materials = _download_materials_for_row(
+                        page, row_idx, contract_id, mat_btn_count,
+                    )
+                    from db.migrations import ensure_materials_content_schema
+                    ensure_materials_content_schema(conn)
+                    for m in materials:
+                        if isinstance(m, dict) and m.get("kind") == "sandbox_card":
+                            conn.execute(
+                                """
+                                INSERT OR REPLACE INTO materials_content
+                                    (contract_id, file_name, file_path, extracted_text,
+                                     parse_method, parsed_at)
+                                VALUES (?, ?, ?, ?, 'sandbox_card', ?)
+                                """,
+                                (
+                                    contract_id, m["file_name"],
+                                    f"sandbox://hr/contracts/{contract_id}",
+                                    m["text"],
+                                    datetime.now().isoformat(timespec="seconds"),
+                                ),
+                            )
+                            repo.parse_sandbox_card_performance(conn, contract_id, m["text"])
+                    result_path = (
+                        f"sandbox://hr/contracts/{contract_id}"
+                        if materials else "no_materials_captured"
+                    )
+                    repo.mark_task_success(conn, task_id, result_path)
+                    succeeded += 1
+                    details.append({
+                        "task_id": task_id,
+                        "contract_id": contract_id,
+                        "ok": True,
+                        "materials_count": len(materials),
+                    })
+                    conn.commit()
+                except Exception as e:
+                    repo.mark_task_failed(conn, task_id, str(e))
+                    failed += 1
+                    details.append({
+                        "task_id": task_id, "contract_id": contract_id,
+                        "error": str(e),
+                    })
+                    conn.commit()
+                    logger.warning("process_queue: task=%s 失败: %s", task_id, e)
+                finally:
+                    conn.close()
+        finally:
+            ctx.close()
+
+    return {
+        "processed": len(tasks),
+        "succeeded": succeeded,
+        "failed": failed,
+        "details": details,
+    }
+
+
 def _error_result(reason: str, fetched: int) -> dict:
     return {
         "platform_url": PLATFORM_URL,

scripts/util/constants.py

@@ -6,7 +6,7 @@
 """
 
 SKILL_SLUG = "alert-contract-expiring-hr"
-SKILL_VERSION = "1.1.17"
+SKILL_VERSION = "1.1.18"
 LOG_LOGGER_NAME = "openclaw.skill.alert_contract_expiring_hr"
 PLATFORM_KIT_MIN_VERSION = "1.2.11"
 
@@ -87,3 +87,13 @@ CARD_APPEAR_WAIT_MS = 3_000       # 「续聘材料包」click 后等卡片出
 
 # dump
 DUMP_PATH_PARENT_MKDIR = True     # _dump_page 是否自动创建父目录
+
+# ----- v1.1.18：日志落文件 -----
+LOG_FILE_DEFAULT_NAME = "alert-contract-expiring-hr.log"
+LOG_MAX_BYTES_DEFAULT = 5 * 1024 * 1024   # 5MB
+LOG_BACKUP_COUNT_DEFAULT = 5
+
+# ----- v1.1.18：材料下载队列 -----
+DOWNLOAD_QUEUE_MAX_ATTEMPTS_DEFAULT = 3
+DOWNLOAD_QUEUE_KINDS = ("platform_button", "local_upload")
+DOWNLOAD_QUEUE_STATUSES = ("pending", "running", "success", "failed")

scripts/util/logging_setup.py

@@ -1,20 +1,35 @@
 """logging 配置：降级到 stderr，避免污染 stdout（stdout 留给结构化输出如 JSON）。
 
 优先用 jiangchang_skill_core 提供的 logging；本地无该包时降级到 stderr。
+
+v1.1.18：本地降级路径追加 RotatingFileHandler（按 LOG_FILE env 决定是否落文件）。
 """
 
 from __future__ import annotations
 
 import logging
+import logging.handlers
+import os
 import sys
+from pathlib import Path
 
-from util.constants import LOG_LOGGER_NAME, SKILL_SLUG, SKILL_VERSION
+from util.constants import (
+    LOG_LOGGER_NAME,
+    SKILL_SLUG,
+    SKILL_VERSION,
+)
 
 _configured = False
 
 
 def setup_skill_logging() -> logging.Logger:
-    """初始化 skill logger（幂等）。"""
+    """初始化 skill logger（幂等）。
+
+    本地降级行为（无 jiangchang_skill_core 时）：
+      - 若 LOG_FILE 已设：追加 RotatingFileHandler（LOG_MAX_BYTES × LOG_BACKUP_COUNT）
+      - 始终追加 StreamHandler(sys.stderr)
+      - logger level 取自 LOG_LEVEL（默认 INFO）
+    """
     global _configured
     logger = logging.getLogger(LOG_LOGGER_NAME)
     if _configured:
@@ -30,15 +45,38 @@ def setup_skill_logging() -> logging.Logger:
     except ImportError:
         pass
 
-    # 本地降级：基础 stderr handler，UTF-8 safe
-    handler = logging.StreamHandler(sys.stderr)
-    handler.setFormatter(
-        logging.Formatter(
-            fmt=f"%(asctime)s [{SKILL_SLUG}] %(levelname)s %(message)s",
-            datefmt="%Y-%m-%d %H:%M:%S",
-        )
+    # logger 级别
+    level_name = os.environ.get("LOG_LEVEL", "INFO").upper()
+    logger.setLevel(getattr(logging, level_name, logging.INFO))
+
+    formatter = logging.Formatter(
+        fmt=f"%(asctime)s [{SKILL_SLUG}] %(levelname)s %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
     )
-    logger.setLevel(logging.INFO)
+
+    # 本地降级：可选 RotatingFileHandler
+    log_file_str = os.environ.get("LOG_FILE")
+    if log_file_str:
+        log_path = Path(log_file_str)
+        if not log_path.is_absolute():
+            from util.runtime_paths import get_logs_dir
+
+            log_path = get_logs_dir() / log_file_str
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+        max_bytes = int(os.environ.get("LOG_MAX_BYTES", str(5 * 1024 * 1024)))
+        backup_count = int(os.environ.get("LOG_BACKUP_COUNT", "5"))
+        file_handler = logging.handlers.RotatingFileHandler(
+            log_path,
+            maxBytes=max_bytes,
+            backupCount=backup_count,
+            encoding="utf-8",
+        )
+        file_handler.setFormatter(formatter)
+        logger.addHandler(file_handler)
+
+    # 始终保留 stderr handler
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(formatter)
     logger.addHandler(handler)
     logger.propagate = False
     _configured = True
@@ -51,3 +89,19 @@ def get_skill_logger() -> logging.Logger:
     if not _configured:
         return setup_skill_logging()
     return logging.getLogger(LOG_LOGGER_NAME)
+
+
+def reset_for_tests() -> None:
+    """测试用：重置 _configured flag，让 setup_skill_logging 重新初始化。
+
+    必须在每个修改日志配置的测试 fixture 里调用，否则 env 改动不会生效。
+    """
+    global _configured
+    logger = logging.getLogger(LOG_LOGGER_NAME)
+    for h in list(logger.handlers):
+        try:
+            h.close()
+        except Exception:
+            pass
+        logger.removeHandler(h)
+    _configured = False

scripts/util/runtime_paths.py

@@ -66,6 +66,30 @@ def get_dispatch_dir() -> Path:
     return get_data_dir() / "dispatch"
 
 
+def get_logs_dir() -> Path:
+    """返回日志目录（RotatingFileHandler 默认落地点）。"""
+    env_dir = os.environ.get("JIANGCHANG_LOGS_DIR")
+    if env_dir:
+        return Path(env_dir)
+    return get_data_dir() / "logs"
+
+
+def get_input_dir() -> Path:
+    """返回用户主动投放的输入目录（含 contracts/*.csv + materials/*.{pdf,docx,doc}）。"""
+    env_dir = os.environ.get("INPUT_DIR")
+    if env_dir:
+        return Path(env_dir)
+    return get_data_dir() / "input"
+
+
+def get_input_contracts_dir() -> Path:
+    return get_input_dir() / "contracts"
+
+
+def get_input_materials_dir() -> Path:
+    return get_input_dir() / "materials"
+
+
 def get_examples_dir() -> Path:
     """返回样例数据目录。"""
     return get_skill_root() / "examples"
@@ -78,5 +102,13 @@ def get_templates_dir() -> Path:
 
 def ensure_dirs() -> None:
     """确保所有需要的目录存在。"""
-    for d in (get_data_dir(), get_output_dir(), get_dispatch_dir()):
+    for d in (
+        get_data_dir(),
+        get_output_dir(),
+        get_dispatch_dir(),
+        get_logs_dir(),
+        get_input_dir(),
+        get_input_contracts_dir(),
+        get_input_materials_dir(),
+    ):
         d.mkdir(parents=True, exist_ok=True)