dp-cli 0.1.0__py3-none-any.whl

dp_cli/__init__.py

@@ -0,0 +1 @@
+# -*- coding:utf-8 -*-

dp_cli/commands/__init__.py

@@ -0,0 +1,12 @@
+# -*- coding:utf-8 -*-
+from dp_cli.commands import (
+    browser, snapshot_cmd, element, keyboard,
+    page, tab, storage, network, misc,
+)
+
+_MODULES = [browser, snapshot_cmd, element, keyboard, page, tab, storage, network, misc]
+
+
+def register_all(cli):
+    for mod in _MODULES:
+        mod.register(cli)

dp_cli/commands/_utils.py

@@ -0,0 +1,107 @@
+# -*- coding:utf-8 -*-
+"""所有命令模块共享的工具函数和装饰器"""
+import io
+import csv
+import click
+
+from dp_cli.session import get_browser, load_refs, load_session, save_session
+from dp_cli.output import error
+
+
+def normalize_url(url: str) -> str:
+    """补全 URL scheme，支持省略 http:// / https://"""
+    if not url:
+        return url
+    if not url.startswith(('http://', 'https://', 'file://')):
+        return 'https://' + url
+    return url
+
+
+def session_option(f):
+    return click.option('-s', '--session', default='default',
+                        help='会话名称，默认 default', show_default=True)(f)
+
+
+def _get_page(session: str, raw: bool = False):
+    """获取页面对象，失败则 error 退出。
+
+    :param raw: True 时始终返回 ChromiumPage（用于浏览器级操作如标签页管理）。
+                False 时返回绑定的标签页 ChromiumTab（如有），否则返回 ChromiumPage。
+    """
+    try:
+        page = get_browser(session)
+    except Exception as e:
+        error(f'无法连接浏览器会话 [{session}]，请先执行 dp open',
+              code='SESSION_NOT_FOUND', detail=str(e))
+        return
+
+    if raw:
+        return page
+
+    # 检查是否有绑定的标签页
+    sess = load_session(session)
+    tab_id = sess.get('active_tab')
+    if tab_id:
+        try:
+            tab = page.get_tab(tab_id)
+            return tab
+        except Exception:
+            # 标签页可能已关闭，清除绑定
+            sess.pop('active_tab', None)
+            save_session(session, sess)
+
+    return page
+
+
+def resolve_locator(locator: str, session: str = 'default') -> str:
+    """解析定位器，支持 ref:N 语法。
+
+    如果 locator 以 'ref:' 开头，从 session 的 refs 映射中查找真实定位器。
+    否则原样返回。
+    """
+    if not locator.startswith('ref:'):
+        return locator
+
+    ref_id = locator[4:]
+    refs = load_refs(session)
+    if not refs:
+        error(f'没有可用的 ref 映射，请先执行 dp snapshot',
+              code='NO_REFS')
+        raise SystemExit(1)
+
+    ref_data = refs.get(ref_id)
+    if not ref_data:
+        available = sorted(refs.keys(), key=lambda x: int(x) if x.isdigit() else 0)
+        hint = f"可用范围: ref:1 ~ ref:{available[-1]}" if available else ""
+        error(f'ref:{ref_id} 不存在。{hint}',
+              code='REF_NOT_FOUND')
+        raise SystemExit(1)
+
+    real_loc = ref_data.get('locator')
+    if real_loc and not real_loc.startswith('t:'):
+        return real_loc
+
+    # locator 不可用时（如 t:p），尝试用 name 作为 text 定位器
+    name = ref_data.get('name', '')
+    if name and len(name) <= 50:
+        return f'text:{name}'
+
+    error(f'ref:{ref_id} 无法解析为有效定位器 (role={ref_data.get("role")})',
+          code='REF_UNRESOLVABLE')
+    raise SystemExit(1)
+
+
+def records_to_csv(records: list) -> str:
+    """将记录列表转为 CSV 字符串（含 BOM，Excel 直接打开不乱码）"""
+    if not records:
+        return ''
+    fields = list(records[0].keys())
+    buf = io.StringIO()
+    writer = csv.DictWriter(buf, fieldnames=fields, extrasaction='ignore',
+                            lineterminator='\n')
+    writer.writeheader()
+    for row in records:
+        clean = {k: ('|'.join(str(i) for i in v) if isinstance(v, list) else v)
+                 for k, v in row.items()}
+        writer.writerow(clean)
+    return buf.getvalue()

dp_cli/commands/browser.py

@@ -0,0 +1,159 @@
+# -*- coding:utf-8 -*-
+"""浏览器生命周期命令: open / goto / reload / go-back / go-forward / close / close-all / list / delete-data"""
+import click
+
+from dp_cli.session import (get_browser, close_browser, list_sessions,
+                            delete_session, load_session, save_session)
+from dp_cli.output import ok, error, format_page_info
+from dp_cli.commands._utils import session_option, _get_page, normalize_url
+
+
+def register(cli):
+
+    @cli.command('open')
+    @click.argument('url', required=False)
+    @session_option
+    @click.option('--headless', is_flag=True, help='无头模式')
+    @click.option('--browser', 'browser_path', default=None, help='浏览器可执行文件路径')
+    @click.option('--profile', 'user_data_dir', default=None, help='用户数据目录')
+    @click.option('--proxy', default=None, help='代理服务器，如 http://127.0.0.1:7890')
+    @click.option('--port', type=int, default=None, help='连接指定端口的已有浏览器实例')
+    @click.option('--new', is_flag=True, help='强制创建新实例（不复用已有会话）')
+    def cmd_open(url, session, headless, browser_path, user_data_dir, proxy, port, new):
+        """打开浏览器并可选导航到 URL。
+
+        \b
+        【复用用户自己的浏览器】(最常见场景，保留登录状态/Cookie/历史)
+        第一步：用调试模式启动你自己的 Chrome/Chromium：
+          google-chrome --remote-debugging-port=9222
+        第二步：用 dp 接管：
+          dp open --port 9222
+          dp open https://example.com --port 9222
+        第三步：后续命令无需再指定 --port（会话自动记住端口）：
+          dp snapshot
+          dp click "text:登录"
+
+        \b
+        【dp 自动管理浏览器】
+          dp open
+          dp open https://example.com
+          dp open https://example.com --headless
+          dp -s work open https://github.com
+        """
+        if new:
+            delete_session(session)
+        try:
+            page = get_browser(session, headless=headless, browser_path=browser_path,
+                               user_data_dir=user_data_dir, proxy=proxy, port=port)
+        except Exception as e:
+            error(f'启动浏览器失败: {e}', code='BROWSER_START_FAILED', detail=str(e))
+            return
+        if url:
+            try:
+                page.get(normalize_url(url))
+            except Exception as e:
+                error(f'导航失败: {e}', code='NAVIGATE_FAILED', detail=str(e))
+                return
+        ok(format_page_info(page), msg='浏览器已就绪')
+
+    @cli.command()
+    @click.argument('url')
+    @session_option
+    @click.option('--timeout', default=30, help='超时秒数', show_default=True)
+    @click.option('--retry', default=3, help='重试次数', show_default=True)
+    def goto(url, session, timeout, retry):
+        """导航到指定 URL。
+
+        \b
+        示例:
+          dp goto https://example.com
+          dp goto example.com
+          dp goto example.com --timeout 60
+        """
+        page = _get_page(session)
+        try:
+            page.get(normalize_url(url), timeout=timeout, retry=retry)
+            ok(format_page_info(page))
+        except Exception as e:
+            error(f'导航到 {url} 失败', code='NAVIGATE_FAILED', detail=str(e))
+
+    @cli.command()
+    @session_option
+    def reload(session):
+        """刷新当前页面。"""
+        page = _get_page(session)
+        try:
+            page.get(page.url)
+            ok(format_page_info(page))
+        except Exception as e:
+            error(f'刷新失败', code='RELOAD_FAILED', detail=str(e))
+
+    @cli.command('go-back')
+    @session_option
+    def go_back(session):
+        """浏览器后退。"""
+        page = _get_page(session)
+        try:
+            page.back()
+            ok(format_page_info(page))
+        except Exception as e:
+            error('后退失败', code='NAVIGATE_FAILED', detail=str(e))
+
+    @cli.command('go-forward')
+    @session_option
+    def go_forward(session):
+        """浏览器前进。"""
+        page = _get_page(session)
+        try:
+            page.forward()
+            ok(format_page_info(page))
+        except Exception as e:
+            error('前进失败', code='NAVIGATE_FAILED', detail=str(e))
+
+    @cli.command('close')
+    @session_option
+    @click.option('--del-data', is_flag=True, help='同时删除用户数据目录')
+    @click.option('--force', is_flag=True, help='强制关闭浏览器（user_connected 模式下默认只断开连接）')
+    def cmd_close(session, del_data, force):
+        """关闭浏览器会话。
+
+        如果是通过 --port 连接的用户自己的浏览器，默认只断开连接不关闭浏览器。
+        用 --force 才会真正关闭浏览器进程。
+        """
+        sess = load_session(session)
+        if not sess:
+            error(f'会话 [{session}] 不存在', code='SESSION_NOT_FOUND')
+            return
+        user_connected = sess.get('user_connected', False)
+        if user_connected and not force:
+            delete_session(session)
+            ok(msg=f'已断开与 [{session}] 的连接（浏览器仍运行）。用 --force 关闭浏览器。')
+        else:
+            result = close_browser(session, del_data=del_data)
+            if result:
+                ok(msg=f'会话 [{session}] 已关闭')
+            else:
+                error(f'关闭失败', code='CLOSE_FAILED')
+
+    @cli.command('close-all')
+    def close_all():
+        """关闭所有会话。"""
+        sessions = list_sessions()
+        closed = []
+        for s in sessions:
+            close_browser(s['name'])
+            closed.append(s['name'])
+        ok({'closed': closed}, msg=f'已关闭 {len(closed)} 个会话')
+
+    @cli.command('list')
+    def cmd_list():
+        """列出所有活跃会话。"""
+        sessions = list_sessions()
+        ok({'sessions': sessions, 'count': len(sessions)})
+
+    @cli.command('delete-data')
+    @session_option
+    def delete_data(session):
+        """删除会话的用户数据目录。"""
+        close_browser(session, del_data=True)
+        ok(msg=f'会话 [{session}] 数据已删除')

dp_cli/commands/element.py

@@ -0,0 +1,259 @@
+# -*- coding:utf-8 -*-
+"""元素交互命令: click / dblclick / fill / clear / select / hover / drag / check / upload"""
+import click
+
+from dp_cli.output import ok, error
+from dp_cli.commands._utils import session_option, _get_page, resolve_locator
+
+
+def register(cli):
+
+    @cli.command('click')
+    @click.argument('locator')
+    @session_option
+    @click.option('--index', default=1, help='第几个匹配元素', show_default=True)
+    @click.option('--by-js', is_flag=True, help='使用 JavaScript 点击')
+    @click.option('--timeout', default=10, help='等待超时秒数', show_default=True)
+    def cmd_click(locator, session, index, by_js, timeout):
+        """点击元素。
+
+        \b
+        示例:
+          dp click "text:登录"
+          dp click "#submit-btn"
+          dp click "ref:5"              # 使用快照编号
+          dp click "css:.btn-primary" --by-js
+          dp click "css:li" --index 3
+        """
+        locator = resolve_locator(locator, session)
+        page = _get_page(session)
+        try:
+            ele = page.ele(locator, index=index, timeout=timeout)
+            if not ele or ele.__class__.__name__ == 'NoneElement':
+                error(f'未找到元素: {locator}', code='ELEMENT_NOT_FOUND')
+                return
+            if by_js:
+                ele.click.js()
+            else:
+                ele.click()
+            ok({'locator': locator}, msg='点击成功')
+        except Exception as e:
+            error(f'点击失败: {locator}', code='CLICK_FAILED', detail=str(e))
+
+    @cli.command('dblclick')
+    @click.argument('locator')
+    @session_option
+    @click.option('--index', default=1, help='第几个匹配元素', show_default=True)
+    @click.option('--timeout', default=10, help='等待超时秒数', show_default=True)
+    def dblclick(locator, session, index, timeout):
+        """双击元素。
+
+        \b
+        示例:
+          dp dblclick "#editable-cell"
+          dp dblclick "ref:5"
+        """
+        locator = resolve_locator(locator, session)
+        page = _get_page(session)
+        try:
+            ele = page.ele(locator, index=index, timeout=timeout)
+            if not ele or ele.__class__.__name__ == 'NoneElement':
+                error(f'未找到元素: {locator}', code='ELEMENT_NOT_FOUND')
+                return
+            ele.click(count=2)
+            ok({'locator': locator}, msg='双击成功')
+        except Exception as e:
+            error(f'双击失败: {locator}', code='CLICK_FAILED', detail=str(e))
+
+    @cli.command('fill')
+    @click.argument('locator')
+    @click.argument('value')
+    @session_option
+    @click.option('--index', default=1, help='第几个匹配元素', show_default=True)
+    @click.option('--clear', is_flag=True, default=True, help='填入前清空（默认开启）')
+    @click.option('--by-js', is_flag=True, help='使用 JavaScript 设置值')
+    @click.option('--timeout', default=10, help='等待超时秒数', show_default=True)
+    def fill(locator, value, session, index, clear, by_js, timeout):
+        """向输入框填入文本。
+
+        \b
+        示例:
+          dp fill "@name=username" admin
+          dp fill "ref:15" "Python"     # 使用快照编号
+          dp fill "css:textarea" "多行\\n文本"
+        """
+        locator = resolve_locator(locator, session)
+        page = _get_page(session)
+        try:
+            ele = page.ele(locator, index=index, timeout=timeout)
+            if not ele or ele.__class__.__name__ == 'NoneElement':
+                error(f'未找到元素: {locator}', code='ELEMENT_NOT_FOUND')
+                return
+            ele.input(value, clear=clear, by_js=by_js)
+            ok({'locator': locator, 'value': value}, msg='填入成功')
+        except Exception as e:
+            error(f'填入失败: {locator}', code='FILL_FAILED', detail=str(e))
+
+    @cli.command('clear')
+    @click.argument('locator')
+    @session_option
+    @click.option('--index', default=1, help='第几个匹配元素', show_default=True)
+    @click.option('--timeout', default=10, help='等待超时秒数', show_default=True)
+    def cmd_clear(locator, session, index, timeout):
+        """清空输入框内容。"""
+        locator = resolve_locator(locator, session)
+        page = _get_page(session)
+        try:
+            ele = page.ele(locator, index=index, timeout=timeout)
+            if not ele or ele.__class__.__name__ == 'NoneElement':
+                error(f'未找到元素: {locator}', code='ELEMENT_NOT_FOUND')
+                return
+            ele.clear()
+            ok({'locator': locator}, msg='清空成功')
+        except Exception as e:
+            error(f'清空失败: {locator}', code='CLEAR_FAILED', detail=str(e))
+
+    @cli.command('select')
+    @click.argument('locator')
+    @click.argument('value')
+    @session_option
+    @click.option('--index', default=1, help='第几个匹配 select 元素', show_default=True)
+    @click.option('--by-text', is_flag=True, help='按文本选择（默认按 value）')
+    @click.option('--by-index', 'sel_by_index', default=None, type=int, help='按位置索引选择（从1开始）')
+    @click.option('--timeout', default=10, help='等待超时秒数', show_default=True)
+    def cmd_select(locator, value, session, index, by_text, sel_by_index, timeout):
+        """选择下拉框选项。
+
+        \b
+        示例:
+          dp select "@name=city" beijing
+          dp select "ref:12" admin          # 用快照编号
+          dp select "#size" "" --by-index 2
+        """
+        locator = resolve_locator(locator, session)
+        page = _get_page(session)
+        try:
+            ele = page.ele(locator, index=index, timeout=timeout)
+            if not ele or ele.__class__.__name__ == 'NoneElement':
+                error(f'未找到元素: {locator}', code='ELEMENT_NOT_FOUND')
+                return
+            if sel_by_index is not None:
+                ele.select.by_index(sel_by_index)
+            elif by_text:
+                ele.select.by_text(value)
+            else:
+                ele.select.by_value(value)
+            ok({'locator': locator, 'value': value}, msg='选择成功')
+        except Exception as e:
+            error(f'选择失败: {locator}', code='SELECT_FAILED', detail=str(e))
+
+    @cli.command('hover')
+    @click.argument('locator')
+    @session_option
+    @click.option('--index', default=1, help='第几个匹配元素', show_default=True)
+    @click.option('--offset-x', default=None, type=int, help='X 偏移量（像素）')
+    @click.option('--offset-y', default=None, type=int, help='Y 偏移量（像素）')
+    @click.option('--timeout', default=10, help='等待超时秒数', show_default=True)
+    def hover(locator, session, index, offset_x, offset_y, timeout):
+        """悬停鼠标到元素。
+
+        \b
+        示例:
+          dp hover "css:.menu-item"
+          dp hover "ref:8"                   # 用快照编号
+        """
+        locator = resolve_locator(locator, session)
+        page = _get_page(session)
+        try:
+            ele = page.ele(locator, index=index, timeout=timeout)
+            if not ele or ele.__class__.__name__ == 'NoneElement':
+                error(f'未找到元素: {locator}', code='ELEMENT_NOT_FOUND')
+                return
+            ele.hover(offset_x=offset_x, offset_y=offset_y)
+            ok({'locator': locator}, msg='悬停成功')
+        except Exception as e:
+            error(f'悬停失败: {locator}', code='HOVER_FAILED', detail=str(e))
+
+    @cli.command('drag')
+    @click.argument('from_locator')
+    @click.argument('to_locator')
+    @session_option
+    @click.option('--duration', default=0.5, help='拖拽持续时间（秒）', show_default=True)
+    @click.option('--timeout', default=10, help='等待超时秒数', show_default=True)
+    def drag(from_locator, to_locator, session, duration, timeout):
+        """拖拽元素到另一个元素。
+
+        \b
+        示例:
+          dp drag "#draggable" "#droptarget"
+          dp drag "ref:3" "ref:7"          # 用快照编号
+        """
+        from_locator = resolve_locator(from_locator, session)
+        to_locator = resolve_locator(to_locator, session)
+        page = _get_page(session)
+        try:
+            src = page.ele(from_locator, timeout=timeout)
+            dst = page.ele(to_locator, timeout=timeout)
+            if not src or src.__class__.__name__ == 'NoneElement':
+                error(f'未找到源元素: {from_locator}', code='ELEMENT_NOT_FOUND')
+                return
+            if not dst or dst.__class__.__name__ == 'NoneElement':
+                error(f'未找到目标元素: {to_locator}', code='ELEMENT_NOT_FOUND')
+                return
+            src.drag_to(dst, duration=duration)
+            ok({'from': from_locator, 'to': to_locator}, msg='拖拽成功')
+        except Exception as e:
+            error(f'拖拽失败', code='DRAG_FAILED', detail=str(e))
+
+    @cli.command('check')
+    @click.argument('locator')
+    @session_option
+    @click.option('--check/--uncheck', default=True, help='选中/取消选中')
+    @click.option('--timeout', default=10, help='等待超时秒数', show_default=True)
+    def cmd_check(locator, session, check, timeout):
+        """勾选或取消勾选 checkbox/radio。
+
+        \b
+        示例:
+          dp check "#agree-terms"
+          dp check "ref:10"                  # 用快照编号
+          dp check "@name=remember" --uncheck
+        """
+        locator = resolve_locator(locator, session)
+        page = _get_page(session)
+        try:
+            ele = page.ele(locator, timeout=timeout)
+            if not ele or ele.__class__.__name__ == 'NoneElement':
+                error(f'未找到元素: {locator}', code='ELEMENT_NOT_FOUND')
+                return
+            current = ele.states.is_checked
+            if (check and not current) or (not check and current):
+                ele.click()
+            ok({'locator': locator, 'checked': check}, msg='操作成功')
+        except Exception as e:
+            error(f'checkbox 操作失败: {locator}', code='CHECK_FAILED', detail=str(e))
+
+    @cli.command('upload')
+    @click.argument('locator')
+    @click.argument('file_path')
+    @session_option
+    @click.option('--timeout', default=10, help='等待超时秒数', show_default=True)
+    def upload(locator, file_path, session, timeout):
+        """上传文件到 input[type=file] 元素。
+
+        \b
+        示例:
+          dp upload "@name=avatar" /path/to/image.png
+          dp upload "ref:15" ./document.pdf   # 用快照编号
+        """
+        locator = resolve_locator(locator, session)
+        page = _get_page(session)
+        try:
+            ele = page.ele(locator, timeout=timeout)
+            if not ele or ele.__class__.__name__ == 'NoneElement':
+                error(f'未找到元素: {locator}', code='ELEMENT_NOT_FOUND')
+                return
+            ele.input(file_path)
+            ok({'locator': locator, 'file': file_path}, msg='文件上传成功')
+        except Exception as e:
+            error(f'文件上传失败', code='UPLOAD_FAILED', detail=str(e))

dp_cli/commands/keyboard.py

@@ -0,0 +1,126 @@
+# -*- coding:utf-8 -*-
+"""键盘与滚动命令: press / type / scroll / scroll-to"""
+import click
+
+from dp_cli.output import ok, error
+from dp_cli.commands._utils import session_option, _get_page, resolve_locator
+
+
+def register(cli):
+
+    @cli.command('press')
+    @click.argument('key')
+    @session_option
+    def cmd_press(key, session):
+        """模拟键盘按键。
+
+        \b
+        支持的按键: Enter, Tab, Escape, Space, Backspace,
+                   ArrowUp/Down/Left/Right, F1-F12,
+                   Control+A, Shift+Enter, Alt+F4 等组合键。
+
+        \b
+        示例:
+          dp press Enter
+          dp press "Control+A"
+          dp press Escape
+        """
+        page = _get_page(session)
+        try:
+            from DrissionPage._functions.keys import Keys
+            key_map = {
+                'enter': '\ue007', 'tab': '\ue004', 'escape': '\ue00c', 'esc': '\ue00c',
+                'backspace': '\ue003', 'delete': '\ue017', 'space': ' ',
+                'arrowup': '\ue013', 'arrowdown': '\ue015',
+                'arrowleft': '\ue012', 'arrowright': '\ue014',
+            }
+            k = key.lower()
+            if '+' in key:
+                parts = key.split('+')
+                modifier = parts[0].lower()
+                main_key = parts[1]
+                mod_map = {'control': Keys.CTRL, 'ctrl': Keys.CTRL,
+                           'shift': Keys.SHIFT, 'alt': Keys.ALT}
+                if modifier in mod_map:
+                    page.actions.key_down(mod_map[modifier]).type(main_key).key_up(mod_map[modifier])
+                else:
+                    page.actions.type(key)
+            else:
+                actual_key = key_map.get(k, key)
+                page.actions.type(actual_key)
+            ok({'key': key}, msg='按键成功')
+        except Exception as e:
+            error(f'按键失败: {key}', code='KEY_FAILED', detail=str(e))
+
+    @cli.command('type')
+    @click.argument('text')
+    @session_option
+    def cmd_type(text, session):
+        """输入文本（当前焦点元素）。
+
+        \b
+        示例:
+          dp type "hello world"
+          dp type "search query"
+        """
+        page = _get_page(session)
+        try:
+            page.actions.type(text)
+            ok({'text': text}, msg='输入成功')
+        except Exception as e:
+            error(f'输入失败', code='TYPE_FAILED', detail=str(e))
+
+    @cli.command('scroll')
+    @click.option('--x', default=0, type=int, help='水平滚动像素')
+    @click.option('--y', default=300, type=int, help='垂直滚动像素')
+    @click.option('--locator', default=None, help='滚动特定元素（而非页面）')
+    @session_option
+    def cmd_scroll(x, y, locator, session):
+        """滚动页面或元素。
+
+        \b
+        示例:
+          dp scroll --y 300
+          dp scroll --y -200
+          dp scroll --locator "css:.scroll-container" --y 100
+        """
+        page = _get_page(session)
+        try:
+            if locator:
+                ele = page.ele(locator)
+                ele.scroll.down(y) if y > 0 else ele.scroll.up(abs(y))
+            else:
+                if y > 0:
+                    page.scroll.down(y)
+                elif y < 0:
+                    page.scroll.up(abs(y))
+                if x > 0:
+                    page.scroll.right(x)
+                elif x < 0:
+                    page.scroll.left(abs(x))
+            ok({'x': x, 'y': y}, msg='滚动成功')
+        except Exception as e:
+            error(f'滚动失败', code='SCROLL_FAILED', detail=str(e))
+
+    @cli.command('scroll-to')
+    @click.argument('locator')
+    @session_option
+    def scroll_to(locator, session):
+        """滚动页面直到元素可见。
+
+        \b
+        示例:
+          dp scroll-to "#footer"
+          dp scroll-to "ref:20"
+        """
+        locator = resolve_locator(locator, session)
+        page = _get_page(session)
+        try:
+            ele = page.ele(locator)
+            if not ele or ele.__class__.__name__ == 'NoneElement':
+                error(f'未找到元素: {locator}', code='ELEMENT_NOT_FOUND')
+                return
+            ele.scroll.to_see()
+            ok({'locator': locator}, msg='已滚动到元素')
+        except Exception as e:
+            error(f'滚动失败', code='SCROLL_FAILED', detail=str(e))