dp-cli 0.6.3__tar.gz → 0.8.0__tar.gz

dp_cli-0.8.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, mofanx
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

dp_cli-0.8.0/MANIFEST.in

@@ -0,0 +1 @@
+graft skills

{dp_cli-0.6.3 → dp_cli-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dp-cli
-Version: 0.6.3
+Version: 0.8.0
 Summary: A powerful CLI for DrissionPage — browser automation, structured data extraction, network listening and more.
 License: BSD-3-Clause
 Project-URL: Homepage, https://github.com/mofanx/dp-cli
@@ -13,16 +13,23 @@ Classifier: Topic :: Utilities
 Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
+License-File: LICENSE
 Requires-Dist: DrissionPage>=4.0
 Requires-Dist: click>=8.0
 Requires-Dist: aiohttp>=3.9
 Requires-Dist: websockets>=12
 Requires-Dist: requests>=2.28
+Provides-Extra: tls
+Requires-Dist: curl_cffi>=0.7.0; extra == "tls"
+Provides-Extra: extract
+Requires-Dist: trafilatura>=1.6.0; extra == "extract"
+Requires-Dist: readability-lxml>=0.8.1; extra == "extract"
 Provides-Extra: test
 Requires-Dist: pytest>=7.4.0; extra == "test"
 Requires-Dist: pytest-cov>=4.1.0; extra == "test"
 Requires-Dist: pytest-timeout>=2.1.0; extra == "test"
 Requires-Dist: pytest-mock>=3.11.0; extra == "test"
+Dynamic: license-file
 
 # dp-cli
 
@@ -52,6 +59,18 @@ pip install dp-cli
 dp --help
 ```
 
+### Agent skill（可选，推荐）
+
+为 AI agent 安装完整使用指南（全部命令参考 + 工作流 playbook）：
+
+```bash
+dp install --skills                        # 装到 agent 的 skill 目录
+npx skills add mofanx/dp-cli               # 或走 skills CLI 渠道
+claude plugin marketplace add mofanx/dp-cli  # 或 Claude Code 插件市场
+```
+
+未安装也能用——skill 只是文档层；agent 可直接读 `dp --help` 或 `python -m dp_cli.catalog` 自举。
+
 ## Quick Start
 
 ```bash
@@ -278,7 +297,8 @@ dp_cli/
     ├── snapshot_cmd.py  # snapshot / extract / query / find / inspect
     ├── element.py       # click / fill / select / hover / drag / check / upload / count
     ├── keyboard.py      # press / type / scroll / scroll-to / autoscroll
-    ├── page.py          # screenshot / pdf / eval / wait (idle/loaded/url/title) / dialog
+    ├── page.py          # screenshot / pdf / eval / wait / console / dialog
+    ├── assert_cmd.py    # assert-text / assert-url / assert-visible / assert-count
     ├── tab.py           # tab-list / tab-new / tab-select / tab-close
     ├── storage.py       # cookie-* / localstorage-* / sessionstorage-*
     ├── network.py       # listen / listen-stop / http-get / http-post
@@ -287,7 +307,7 @@ dp_cli/
 
 ## Documentation
 
-See [`skills/SKILL.md`](skills/SKILL.md) for full workflow guide and [`skills/references/commands.md`](skills/references/commands.md) for complete command reference.
+See [`skills/dp-cli/SKILL.md`](skills/dp-cli/SKILL.md) for full workflow guide and [`skills/dp-cli/references/commands.md`](skills/dp-cli/references/commands.md) for complete command reference. Exit-code contract: [`ERROR_CODES.md`](ERROR_CODES.md).
 
 ## License
 

{dp_cli-0.6.3 → dp_cli-0.8.0}/README.md

@@ -26,6 +26,18 @@ pip install dp-cli
 dp --help
 ```
 
+### Agent skill（可选，推荐）
+
+为 AI agent 安装完整使用指南（全部命令参考 + 工作流 playbook）：
+
+```bash
+dp install --skills                        # 装到 agent 的 skill 目录
+npx skills add mofanx/dp-cli               # 或走 skills CLI 渠道
+claude plugin marketplace add mofanx/dp-cli  # 或 Claude Code 插件市场
+```
+
+未安装也能用——skill 只是文档层；agent 可直接读 `dp --help` 或 `python -m dp_cli.catalog` 自举。
+
 ## Quick Start
 
 ```bash
@@ -252,7 +264,8 @@ dp_cli/
     ├── snapshot_cmd.py  # snapshot / extract / query / find / inspect
     ├── element.py       # click / fill / select / hover / drag / check / upload / count
     ├── keyboard.py      # press / type / scroll / scroll-to / autoscroll
-    ├── page.py          # screenshot / pdf / eval / wait (idle/loaded/url/title) / dialog
+    ├── page.py          # screenshot / pdf / eval / wait / console / dialog
+    ├── assert_cmd.py    # assert-text / assert-url / assert-visible / assert-count
     ├── tab.py           # tab-list / tab-new / tab-select / tab-close
     ├── storage.py       # cookie-* / localstorage-* / sessionstorage-*
     ├── network.py       # listen / listen-stop / http-get / http-post
@@ -261,7 +274,7 @@ dp_cli/
 
 ## Documentation
 
-See [`skills/SKILL.md`](skills/SKILL.md) for full workflow guide and [`skills/references/commands.md`](skills/references/commands.md) for complete command reference.
+See [`skills/dp-cli/SKILL.md`](skills/dp-cli/SKILL.md) for full workflow guide and [`skills/dp-cli/references/commands.md`](skills/dp-cli/references/commands.md) for complete command reference. Exit-code contract: [`ERROR_CODES.md`](ERROR_CODES.md).
 
 ## License
 

{dp_cli-0.6.3 → dp_cli-0.8.0}/dp_cli/bridge.py

@@ -97,14 +97,14 @@ class CDPBridge:
             for ws in list(self._browser_clients):
                 try:
                     await ws.close(code=1011, message=b'upstream closed')
-                except Exception:
-                    pass
+                except Exception as e:
+                    log.debug('close downstream ws failed: %s', e)
             self._browser_clients.clear()
             for sid, ws in list(self._session_to_client.items()):
                 try:
                     await ws.close(code=1011, message=b'upstream closed')
-                except Exception:
-                    pass
+                except Exception as e:
+                    log.debug('close session ws failed: %s', e)
             self._session_to_client.clear()
             self.ws = None
             self._connected_evt.clear()
@@ -144,8 +144,8 @@ class CDPBridge:
             try:
                 if not client_ws.closed:
                     await client_ws.send_str(json.dumps(ev))
-            except Exception:
-                pass
+            except Exception as e:
+                log.debug('forward event to client failed: %s', e)
             return
 
         if not sess_id:
@@ -154,8 +154,8 @@ class CDPBridge:
                 try:
                     if not c.closed:
                         await c.send_str(ev_str)
-                except Exception:
-                    pass
+                except Exception as e:
+                    log.debug('broadcast event failed: %s', e)
 
     async def call(self, method: str, params: dict | None = None,
                    session_id: str | None = None) -> dict:
@@ -200,8 +200,8 @@ class CDPBridge:
                 err = {'id': client_id, 'error': {'code': -32000, 'message': str(e)}}
                 try:
                     await client_ws.send_str(json.dumps(err))
-                except Exception:
-                    pass
+                except Exception as e2:
+                    log.debug('send error reply failed: %s', e2)
 
     async def attach_page_client(self, target_id: str,
                                  client_ws: web.WebSocketResponse) -> str | None:
@@ -386,8 +386,8 @@ async def handle_ws(request: web.Request) -> web.StreamResponse:
                 try:
                     payload = json.loads(msg.data)
                     await bridge.forward_from_client(payload, client_ws, session_id)
-                except Exception:
-                    pass
+                except Exception as e:
+                    log.debug('forward client message failed: %s', e)
             elif msg.type in (aiohttp.WSMsgType.CLOSE, aiohttp.WSMsgType.CLOSED,
                               aiohttp.WSMsgType.ERROR):
                 break
@@ -479,14 +479,14 @@ async def main_async(user_data_dir: Path, host: str, port: int) -> None:
                 continue
             try:
                 signal.signal(sig, _win_signal_handler)
-            except (ValueError, OSError):
-                pass
+            except (ValueError, OSError) as e:
+                log.debug('register signal handler failed: %s', e)
     else:
         for sig in (signal.SIGINT, signal.SIGTERM):
             try:
                 loop.add_signal_handler(sig, stop_evt.set)
-            except NotImplementedError:
-                pass
+            except NotImplementedError as e:
+                log.debug('add_signal_handler unsupported: %s', e)
     try:
         await stop_evt.wait()
     finally:

{dp_cli-0.6.3 → dp_cli-0.8.0}/dp_cli/bridge_manager.py

@@ -24,6 +24,8 @@ import sys
 import time
 from pathlib import Path
 
+from dp_cli.logs import debug
+
 IS_WINDOWS = sys.platform == 'win32'
 
 
@@ -74,8 +76,8 @@ def _win_terminate(pid: int) -> None:
             check=False,
             timeout=5,
         )
-    except Exception:
-        pass
+    except Exception as e:
+        debug(f'taskkill pid={pid} 失败', e)
 
 
 _READY_RE = re.compile(r'^BRIDGE_READY host=(?P<host>\S+) port=(?P<port>\d+)\s*$')
@@ -113,8 +115,8 @@ def detect_inspect_mode(port: int, timeout: float = 2.0) -> bool:
         # 经典模式 /json/version 返回 dict，含 Browser 字段
         if isinstance(data, dict) and 'Browser' in data:
             return False
-    except Exception:
-        pass
+    except Exception as e:
+        debug(f'/json/version 响应解析失败，按 inspect 模式处理: port={port}', e)
     return True
 
 
@@ -166,8 +168,8 @@ def start_bridge(user_data_dir: str | os.PathLike,
             for line in proc.stderr:
                 with stderr_lock:
                     stderr_buf.append(line)
-        except Exception:
-            pass
+        except Exception as e:
+            debug('bridge stderr 读取线程结束异常', e)
 
     stderr_thread = threading.Thread(target=_read_stderr, daemon=True)
     stderr_thread.start()
@@ -207,8 +209,8 @@ def start_bridge(user_data_dir: str | os.PathLike,
     except Exception:
         try:
             proc.terminate()
-        except Exception:
-            pass
+        except Exception as e:
+            debug('bridge 启动失败后 terminate 失败', e)
         raise
 
     # ready 后让 bridge 的 stdout 继续被 drain，避免管道阻塞。
@@ -217,8 +219,8 @@ def start_bridge(user_data_dir: str | os.PathLike,
         try:
             for _ in stream:
                 pass
-        except Exception:
-            pass
+        except Exception as e:
+            debug('stdout drain 线程结束异常', e)
 
     if proc.stdout:
         threading.Thread(target=_drain, args=(proc.stdout,), daemon=True).start()
@@ -256,8 +258,8 @@ def stop_bridge(pid: int, timeout: float = 2.0) -> bool:
         # 1) 优雅: 给整个进程组发 CTRL_BREAK_EVENT
         try:
             os.kill(pid, signal.CTRL_BREAK_EVENT)
-        except Exception:
-            pass
+        except Exception as e:
+            debug(f'CTRL_BREAK_EVENT pid={pid} 失败', e)
 
         deadline = time.monotonic() + timeout
         while time.monotonic() < deadline:
@@ -276,8 +278,8 @@ def stop_bridge(pid: int, timeout: float = 2.0) -> bool:
     except (ProcessLookupError, PermissionError, OSError):
         try:
             os.kill(pid, signal.SIGTERM)
-        except Exception:
-            pass
+        except Exception as e:
+            debug(f'SIGTERM pid={pid} 失败', e)
 
     deadline = time.monotonic() + timeout
     while time.monotonic() < deadline:
@@ -291,7 +293,7 @@ def stop_bridge(pid: int, timeout: float = 2.0) -> bool:
     except Exception:
         try:
             os.kill(pid, signal.SIGKILL)
-        except Exception:
-            pass
+        except Exception as e:
+            debug(f'SIGKILL pid={pid} 失败', e)
     time.sleep(0.1)
     return not is_bridge_alive(pid)

dp_cli-0.8.0/dp_cli/catalog.py

@@ -0,0 +1,109 @@
+# -*- coding:utf-8 -*-
+"""从 click 命令树机械导出命令元数据。
+
+两类消费方：
+- ``python -m dp_cli.catalog --md``  → 生成 commands.md 风格的命令表
+- ``python -m dp_cli.catalog``       → 输出 MCP 风格 tool schema JSON
+  （未来 mcp-serve 薄壳的上游；schema 由代码生成，不手写，不腐化）
+
+文档腐化守卫见 tests/test_docs.py：commands.md 必须覆盖全部注册命令。
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+import click
+
+from dp_cli.main import cli
+
+# 模块名 → 命令表类别（按模块机械归类，新增模块时在此补一行）
+CATEGORY = {
+    'browser': '浏览器', 'misc': '导航/页面', 'snapshot_cmd': '快照',
+    'element': '提取/交互', 'keyboard': '键盘/滚动', 'network': '网络',
+    'assert_cmd': '断言', 'emulate': '模拟/下载/拦截', 'observe': '观测',
+    'tab': '标签页', 'storage': '存储', 'record': '录制',
+    'page': '页面', 'batch': '批量', 'rpc': '逆向',
+    'extract': '提取', 'hook': '逆向', 'serve': '批量', 'sh': '批量',
+    'meta': '元信息',
+}
+
+
+def _param_schema(p):
+    """click.Param → JSON Schema 片段。"""
+    if isinstance(p, click.Option) and p.is_flag:
+        t = {'type': 'boolean'}
+    elif isinstance(p.type, click.types.IntParamType):
+        t = {'type': 'integer'}
+    elif isinstance(p.type, click.types.FloatParamType):
+        t = {'type': 'number'}
+    elif isinstance(p.type, click.types.BoolParamType):
+        t = {'type': 'boolean'}
+    elif isinstance(p.type, click.types.Choice):
+        t = {'type': 'string', 'enum': list(p.type.choices)}
+    else:
+        t = {'type': 'string'}
+    if getattr(p, 'multiple', False):
+        t = {'type': 'array', 'items': t}
+    if getattr(p, 'help', None):
+        t['description'] = p.help
+    return t
+
+
+def iter_commands():
+    """yield (name, help, input_schema) —— MCP tool 风格。"""
+    for name in sorted(cli.commands):
+        cmd = cli.commands[name]
+        props, required = {}, []
+        for p in cmd.params:
+            props[p.name] = _param_schema(p)
+            if p.required:
+                required.append(p.name)
+        yield {
+            'name': name,
+            'description': (cmd.help or '').strip().splitlines()[0] if cmd.help else '',
+            'inputSchema': {'type': 'object', 'properties': props,
+                            'required': required},
+            '_category': CATEGORY.get(
+                getattr(cmd.callback, '__module__', '').rsplit('.', 1)[-1],
+                '其他'),
+        }
+
+
+def to_markdown(cmds):
+    """生成按类别分组的 markdown 表（含 options 摘要）。"""
+    by_cat = {}
+    for c in cmds:
+        by_cat.setdefault(c['_category'], []).append(c)
+    lines = ['<!-- GENERATED by `python -m dp_cli.catalog --md` —— 勿手改 -->',
+             '', '| 类别 | 命令 | 参数 |', '|------|------|------|']
+    for cat in CATEGORY.values():
+        for c in by_cat.pop(cat, []):
+            params = ', '.join(
+                (f'<{k}>' if k in c['inputSchema']['required'] else f'[{k}]')
+                for k in c['inputSchema']['properties'])
+            lines.append(f"| {cat} | `{c['name']}` | {params} |")
+    for cat, cs in sorted(by_cat.items()):
+        for c in cs:
+            params = ', '.join(c['inputSchema']['properties'])
+            lines.append(f"| {cat} | `{c['name']}` | {params} |")
+    return '\n'.join(lines) + '\n'
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog='dp-cli-catalog')
+    ap.add_argument('--md', action='store_true', help='输出 markdown 命令表')
+    args = ap.parse_args(argv)
+    cmds = list(iter_commands())
+    if args.md:
+        sys.stdout.write(to_markdown(cmds))
+    else:
+        tools = [{k: v for k, v in c.items() if not k.startswith('_')}
+                 for c in cmds]
+        json.dump({'tools': tools}, sys.stdout, ensure_ascii=False, indent=2)
+        sys.stdout.write('\n')
+
+
+if __name__ == '__main__':
+    main()

{dp_cli-0.6.3 → dp_cli-0.8.0}/dp_cli/commands/__init__.py

@@ -2,9 +2,13 @@
 from dp_cli.commands import (
     browser, snapshot_cmd, element, keyboard,
     page, tab, storage, network, record, misc,
+    assert_cmd, emulate, observe, batch, rpc, extract, hook, serve,
+    meta,
 )
 
-_MODULES = [browser, snapshot_cmd, element, keyboard, page, tab, storage, network, record, misc]
+_MODULES = [browser, snapshot_cmd, element, keyboard, page, tab, storage, network, record, misc,
+            assert_cmd, emulate, observe, batch, rpc, extract, hook, serve,
+            meta]
 
 
 def register_all(cli):