dp-cli 0.1.0__py3-none-any.whl

dp_cli/commands/tab.py

@@ -0,0 +1,203 @@
+# -*- coding:utf-8 -*-
+"""标签页管理命令: tab-list / tab-new / tab-select / tab-close"""
+import click
+
+from dp_cli.output import ok, error
+from dp_cli.session import load_session, save_session
+from dp_cli.commands._utils import session_option, _get_page, normalize_url
+
+
+def register(cli):
+
+    @cli.command('tab-list')
+    @session_option
+    def tab_list(session):
+        """列出所有标签页。
+
+        \b
+        绑定的标签页会显示 [pinned] 标记，后续所有 dp 命令只在该标签页中执行。
+        """
+        page = _get_page(session, raw=True)
+        if not page:
+            return
+        try:
+            sess = load_session(session)
+            pinned_id = sess.get('active_tab')
+            tabs = []
+            for i, tab_id in enumerate(page.tab_ids):
+                tab = page.get_tab(tab_id)
+                entry = {
+                    'index': i,
+                    'id': tab_id,
+                    'url': tab.url,
+                    'title': tab.title,
+                }
+                if tab_id == pinned_id:
+                    entry['pinned'] = True
+                tabs.append(entry)
+            ok({'tabs': tabs, 'count': len(tabs),
+                'pinned': pinned_id or '(none)'})
+        except Exception as e:
+            error(f'获取标签页列表失败', code='TAB_FAILED', detail=str(e))
+
+    @cli.command('tab-new')
+    @click.argument('url', required=False)
+    @session_option
+    @click.option('--background', is_flag=True, help='在后台打开（不绑定）')
+    @click.option('--new-window', is_flag=True, help='在新窗口中打开')
+    def tab_new(url, session, background, new_window):
+        """新建标签页并自动绑定。
+
+        \b
+        新标签页会自动绑定到当前会话，后续 dp 命令在该标签页中执行。
+        使用 --background 时不绑定。
+        使用 --new-window 在独立窗口中打开（适合自动化与手动浏览分离）。
+
+        \b
+        示例:
+          dp tab-new https://example.com
+          dp tab-new https://example.com --new-window
+          dp tab-new https://example.com --background
+        """
+        page = _get_page(session, raw=True)
+        if not page:
+            return
+        try:
+            new_tab = page.new_tab(url=normalize_url(url) if url else '',
+                                   new_window=new_window,
+                                   background=background)
+            new_tid = new_tab.tab_id
+            msg = '新标签页已创建'
+
+            # 非 background 时自动绑定
+            if not background:
+                sess = load_session(session)
+                sess['active_tab'] = new_tid
+                save_session(session, sess)
+                msg += '（已绑定，dp 命令将在此标签页执行）'
+
+            ok({'id': new_tid, 'url': new_tab.url,
+                'title': new_tab.title, 'pinned': not background},
+               msg=msg)
+        except Exception as e:
+            error(f'创建标签页失败', code='TAB_FAILED', detail=str(e))
+
+    @cli.command('tab-select')
+    @click.argument('target')
+    @session_option
+    def tab_select(target, session):
+        """绑定到指定标签页，后续 dp 命令在该标签页中执行。
+
+        \b
+        TARGET 支持：
+          序号    dp tab-select 0        （按标签页序号）
+          tab_id  dp tab-select ABC123   （按标签页 ID）
+          URL     dp tab-select zhipin   （按 URL 关键词匹配）
+          none    dp tab-select none     （解除绑定，恢复默认行为）
+        """
+        # 解除绑定
+        if target.lower() == 'none':
+            sess = load_session(session)
+            old = sess.pop('active_tab', None)
+            save_session(session, sess)
+            if old:
+                ok(msg='已解除标签页绑定，后续命令将在浏览器活跃标签页执行')
+            else:
+                ok(msg='当前没有绑定的标签页')
+            return
+
+        page = _get_page(session, raw=True)
+        if not page:
+            return
+        try:
+            tab_id = _resolve_tab_target(page, target)
+            if not tab_id:
+                return
+
+            tab = page.get_tab(tab_id)
+            tab.set.activate()
+            sess = load_session(session)
+            sess['active_tab'] = tab_id
+            save_session(session, sess)
+            ok({'id': tab_id, 'url': tab.url, 'title': tab.title},
+               msg='已绑定，dp 命令将在此标签页执行')
+        except Exception as e:
+            error(f'切换标签页失败', code='TAB_FAILED', detail=str(e))
+
+    @cli.command('tab-close')
+    @click.argument('index_or_id', required=False)
+    @session_option
+    def tab_close(index_or_id, session):
+        """关闭标签页（默认关闭绑定的标签页，无绑定则关闭当前页）。"""
+        page = _get_page(session, raw=True)
+        if not page:
+            return
+        try:
+            sess = load_session(session)
+            pinned_id = sess.get('active_tab')
+
+            if index_or_id is None:
+                # 优先关闭绑定的标签页
+                if pinned_id:
+                    tab = page.get_tab(pinned_id)
+                    tab.close()
+                    sess.pop('active_tab', None)
+                    save_session(session, sess)
+                    ok({'id': pinned_id}, msg='绑定的标签页已关闭（绑定已解除）')
+                else:
+                    page.close()
+                    ok(msg='当前标签页已关闭')
+            else:
+                tab_id = _resolve_tab_target(page, index_or_id)
+                if not tab_id:
+                    return
+                tab = page.get_tab(tab_id)
+                tab.close()
+                # 如果关闭的是绑定的标签页，清除绑定
+                if tab_id == pinned_id:
+                    sess.pop('active_tab', None)
+                    save_session(session, sess)
+                ok({'id': tab_id}, msg='标签页已关闭')
+        except Exception as e:
+            error(f'关闭标签页失败', code='TAB_FAILED', detail=str(e))
+
+
+def _resolve_tab_target(page, target: str) -> str:
+    """将 target（序号/tab_id/URL关键词）解析为 tab_id"""
+    tab_ids = page.tab_ids
+
+    # 1. 尝试按序号
+    try:
+        idx = int(target)
+        if 0 <= idx < len(tab_ids):
+            return tab_ids[idx]
+        error(f'标签页序号越界: {idx}（共 {len(tab_ids)} 个）',
+              code='TAB_NOT_FOUND')
+        return ''
+    except ValueError:
+        pass
+
+    # 2. 尝试按 tab_id 精确匹配
+    if target in tab_ids:
+        return target
+
+    # 3. 按 URL 关键词模糊匹配
+    for tid in tab_ids:
+        try:
+            tab = page.get_tab(tid)
+            if target.lower() in (tab.url or '').lower():
+                return tid
+        except Exception:
+            continue
+
+    # 4. 按 title 关键词模糊匹配
+    for tid in tab_ids:
+        try:
+            tab = page.get_tab(tid)
+            if target.lower() in (tab.title or '').lower():
+                return tid
+        except Exception:
+            continue
+
+    error(f'未找到匹配 "{target}" 的标签页', code='TAB_NOT_FOUND')
+    return ''

dp_cli/main.py

@@ -0,0 +1,47 @@
+# -*- coding:utf-8 -*-
+"""
+dp-cli —— DrissionPage 命令行工具
+比 playwright-cli 更强大，充分利用 DrissionPage 的独特优势：
+  - 不基于 webdriver，天然反检测
+  - 支持浏览器模式 + HTTP 模式无缝切换
+  - 强大的定位语法（比 a11y ref 更稳定）
+  - lxml 高效批量解析，snapshot 一次 CDP 调用
+  - 支持 shadow-root / iframe 穿透
+  - 内置网络包监听能力
+"""
+import click
+
+from dp_cli.commands import register_all
+
+CONTEXT_SETTINGS = dict(help_option_names=['-h', '--help'], max_content_width=100)
+
+
+@click.group(context_settings=CONTEXT_SETTINGS, invoke_without_command=True)
+@click.version_option(message='%(version)s')
+@click.pass_context
+def cli(ctx):
+    """
+    \b
+    dp-cli —— DrissionPage 命令行工具
+
+    \b
+    快速开始:
+      dp open https://example.com
+      dp snapshot
+      dp click "text:登录"
+      dp fill "@name=username" admin
+      dp close
+    """
+    if ctx.invoked_subcommand is None:
+        click.echo(ctx.get_help())
+
+
+register_all(cli)
+
+
+def main():
+    cli()
+
+
+if __name__ == '__main__':
+    main()

dp_cli/output.py

@@ -0,0 +1,97 @@
+# -*- coding:utf-8 -*-
+"""
+dp-cli 输出格式化模块
+统一的 JSON 输出格式，便于 AI 工具解析。
+"""
+import json
+import sys
+from typing import Any, Optional
+
+
+def ok(data: Any = None, msg: str = None) -> None:
+    """成功输出"""
+    result = {'status': 'ok'}
+    if msg:
+        result['message'] = msg
+    if data is not None:
+        result['data'] = data
+    _print(result)
+
+
+def error(msg: str, code: str = 'ERROR', detail: str = None) -> None:
+    """错误输出"""
+    result = {'status': 'error', 'code': code, 'message': msg}
+    if detail:
+        result['detail'] = detail
+    _print(result)
+    sys.exit(1)
+
+
+def _print(result: dict) -> None:
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+
+
+def format_element(ele, include_rect: bool = False) -> dict:
+    """格式化单个元素信息"""
+    try:
+        attrs = ele.attrs
+    except Exception:
+        attrs = {}
+
+    info = {
+        'tag': ele.tag,
+        'text': (ele.raw_text or '').strip()[:200],
+        'attrs': attrs,
+        'loc': _suggest_locator(ele, attrs),
+    }
+
+    if include_rect:
+        try:
+            info['rect'] = {
+                'location': list(ele.rect.location),
+                'size': list(ele.rect.size),
+                'midpoint': list(ele.rect.midpoint),
+            }
+        except Exception:
+            pass
+
+    return info
+
+
+def _suggest_locator(ele, attrs: dict) -> str:
+    """为元素生成最优 DrissionPage 定位字符串"""
+    # 优先用 id
+    if attrs.get('id'):
+        return f'#{attrs["id"]}'
+
+    # data-testid / data-qa / aria-label 等语义属性
+    for semantic in ('data-testid', 'data-qa', 'aria-label', 'name', 'placeholder'):
+        if attrs.get(semantic):
+            return f'@{semantic}={attrs[semantic]}'
+
+    # 有唯一 class
+    cls = attrs.get('class', '')
+    if cls:
+        classes = cls.strip().split()
+        if classes:
+            return f'.{classes[0]}'
+
+    # 按文本
+    try:
+        txt = (ele.raw_text or '').strip()
+        if txt and len(txt) <= 30:
+            return f'text:{txt}'
+    except Exception:
+        pass
+
+    # 最后按 tag
+    return f't:{ele.tag}'
+
+
+def format_page_info(page) -> dict:
+    """格式化页面基本信息"""
+    return {
+        'url': page.url,
+        'title': page.title,
+        'ready_state': page.states.ready_state,
+    }

dp_cli/session.py

@@ -0,0 +1,201 @@
+# -*- coding:utf-8 -*-
+"""
+dp-cli 会话管理模块
+通过固定端口连接复用已运行的浏览器实例，实现跨命令状态共享。
+"""
+import json
+import os
+import sys
+from pathlib import Path
+from time import sleep, perf_counter
+
+
+# 会话状态文件默认目录
+_SESSION_DIR = Path.home() / '.dp_cli' / 'sessions'
+
+
+def get_session_dir() -> Path:
+    _SESSION_DIR.mkdir(parents=True, exist_ok=True)
+    return _SESSION_DIR
+
+
+def get_session_file(name: str) -> Path:
+    return get_session_dir() / f'{name}.json'
+
+
+def load_session(name: str) -> dict:
+    """读取会话信息"""
+    f = get_session_file(name)
+    if not f.exists():
+        return {}
+    try:
+        return json.loads(f.read_text(encoding='utf-8'))
+    except Exception:
+        return {}
+
+
+def save_session(name: str, data: dict) -> None:
+    """保存会话信息"""
+    get_session_file(name).write_text(
+        json.dumps(data, ensure_ascii=False, indent=2), encoding='utf-8'
+    )
+
+
+def delete_session(name: str) -> bool:
+    """删除会话文件"""
+    f = get_session_file(name)
+    if f.exists():
+        f.unlink()
+        return True
+    return False
+
+
+def list_sessions() -> list:
+    """列出所有会话"""
+    d = get_session_dir()
+    sessions = []
+    for f in d.glob('*.json'):
+        try:
+            data = json.loads(f.read_text(encoding='utf-8'))
+            sessions.append({'name': f.stem, **data})
+        except Exception:
+            pass
+    return sessions
+
+
+def get_browser(session_name: str = 'default', headless: bool = False,
+                browser_path: str = None, user_data_dir: str = None,
+                proxy: str = None, port: int = None):
+    """
+    获取或创建浏览器实例。
+
+    连接优先级：
+    1. 指定 port → 直接连接该端口（失败则报错，不 fallback）
+    2. 已有会话记录的 port → 尝试复用（失败则新建）
+    3. 新建浏览器实例
+    """
+    from DrissionPage import ChromiumPage
+    from DrissionPage._configs.chromium_options import ChromiumOptions
+
+    # === 情况1：用户明确指定端口（连接用户自己的浏览器） ===
+    if port:
+        co = ChromiumOptions(read_file=False)
+        co.set_local_port(port)
+        co.existing_only(True)
+        try:
+            page = ChromiumPage(co)
+        except Exception as e:
+            raise ConnectionError(
+                f'无法连接到端口 {port} 的浏览器实例。\n'
+                f'请确认浏览器已使用 --remote-debugging-port={port} 启动。\n'
+                f'启动命令示例:\n'
+                f'  google-chrome --remote-debugging-port={port}\n'
+                f'  chromium --remote-debugging-port={port}\n'
+                f'原始错误: {e}'
+            ) from e
+        # 记录到会话（后续命令无需再指定端口）
+        save_session(session_name, {
+            'port': port,
+            'headless': headless,
+            'user_data_dir': user_data_dir,
+            'user_connected': True,  # 标记：这是用户自己的浏览器
+        })
+        return page
+
+    # === 情况2：尝试复用已有会话 ===
+    sess = load_session(session_name)
+    saved_port = sess.get('port')
+    if saved_port:
+        try:
+            co = ChromiumOptions(read_file=False)
+            co.set_local_port(saved_port)
+            co.existing_only(True)
+            page = ChromiumPage(co)
+            return page
+        except Exception:
+            # 会话失效，删除记录，继续新建
+            delete_session(session_name)
+
+    # === 情况3：新建浏览器实例 ===
+    co = ChromiumOptions()
+    if browser_path:
+        co.set_browser_path(browser_path)
+    if user_data_dir:
+        co.set_user_data_path(user_data_dir)
+    else:
+        # 每个会话有独立的用户数据目录
+        uid = get_session_dir() / 'profiles' / session_name
+        uid.mkdir(parents=True, exist_ok=True)
+        co.set_user_data_path(str(uid))
+
+    if proxy:
+        co.set_proxy(proxy)
+
+    if headless:
+        co.headless(True)
+
+    co.auto_port(True)
+
+    page = ChromiumPage(co)
+
+    # 保存会话端口
+    port = int(page.browser.address.split(':')[-1])
+    save_session(session_name, {
+        'port': port,
+        'headless': headless,
+        'user_data_dir': str(co.user_data_path) if co.user_data_path else None,
+    })
+
+    return page
+
+
+# ── Ref 映射管理 ─────────────────────────────────────────────────────────────
+
+
+def save_refs(session_name: str, url: str, refs: dict) -> None:
+    """保存快照编号映射到 refs.json"""
+    from datetime import datetime
+    data = {
+        'url': url,
+        'timestamp': datetime.now().isoformat(),
+        'refs': refs,
+    }
+    refs_dir = get_session_dir() / 'refs'
+    refs_dir.mkdir(exist_ok=True)
+    f = refs_dir / f'{session_name}.json'
+    f.write_text(json.dumps(data, ensure_ascii=False), encoding='utf-8')
+
+
+def load_refs(session_name: str) -> dict:
+    """加载快照编号映射，返回 {ref_id: {locator, role, name, backendNodeId}}"""
+    f = get_session_dir() / 'refs' / f'{session_name}.json'
+    if not f.exists():
+        return {}
+    try:
+        data = json.loads(f.read_text(encoding='utf-8'))
+        return data.get('refs', {})
+    except Exception:
+        return {}
+
+
+def close_browser(session_name: str = 'default', del_data: bool = False) -> bool:
+    """关闭指定会话的浏览器"""
+    from DrissionPage import ChromiumPage
+    from DrissionPage._configs.chromium_options import ChromiumOptions
+
+    sess = load_session(session_name)
+    port = sess.get('port')
+    if not port:
+        return False
+
+    try:
+        co = ChromiumOptions(read_file=False)
+        co.set_local_port(port)
+        co.existing_only(True)
+        page = ChromiumPage(co)
+        page.browser.quit(del_data=del_data)
+    except Exception:
+        pass
+
+    delete_session(session_name)
+    return True

dp_cli/snapshot/__init__.py

@@ -0,0 +1,23 @@
+# -*- coding:utf-8 -*-
+"""
+dp-cli snapshot 模块
+
+基于浏览器原生 a11y tree（无障碍树）的页面快照系统。
+通过 CDP Accessibility API 获取，通用性极强，适用于 95%+ 的网站。
+
+模块组成：
+  - a11y.py       核心：a11y tree 获取 + 多模式渲染（full/brief/text）
+  - extract.py    数据提取（extract_structured / query_elements）
+  - utils.py      共享工具（定位器生成等）
+  - js_scripts.py JS 降级脚本（CDP 不可用时的 fallback）
+"""
+from .a11y import take_a11y_snapshot, render_a11y_text, render_a11y_plain_text
+from .extract import extract_structured, query_elements
+
+__all__ = [
+    'take_a11y_snapshot',
+    'render_a11y_text',
+    'render_a11y_plain_text',
+    'extract_structured',
+    'query_elements',
+]