navcli 0.1.0__tar.gz

navcli-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: navcli
+Version: 0.1.0
+Summary: 可交互、可探索的浏览器命令行工具，专为 AI Agent 设计
+Author: NavCLI Team
+License: MIT
+Project-URL: Homepage, https://github.com/navcli/navcli
+Project-URL: Repository, https://github.com/navcli/navcli
+Project-URL: Issues, https://github.com/navcli/navcli/issues
+Keywords: browser,cli,automation,ai-agent,playwright
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: playwright>=1.40.0
+Requires-Dist: cmd2>=2.4.0
+Requires-Dist: fastapi>=0.109.0
+Requires-Dist: uvicorn<1.0.0,>=0.25.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: cssify>=1.0.0
+Requires-Dist: aiohttp>=3.9.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.8.0; extra == "dev"
+
+# NavCLI - 目标与愿景
+
+## 核心目标
+
+**让 AI Agent 能够像人类一样浏览网页。**
+
+现有方案（HTTP API、无头浏览器脚本、Playwright MCP）存在局限：
+- 不支持 JS 渲染的 SPA
+- 无会话状态持久化
+- 缺乏交互式探索能力
+
+NavCLI 的定位：**可交互、可探索的浏览器命令行工具**
+
+## 核心价值
+
+| 特性 | NavCLI 解决的问题 |
+|------|------------------|
+| JS 渲染支持 | 完整支持 SPA 应用 |
+| 会话持久化 | cookies、session 保持 |
+| 交互式 CLI | Agent 可边探索边操作 |
+| Token 优化 | 轻量 elements + 按需 text/html |
+
+## 典型工作流
+
+```bash
+> g https://example.com          # 导航
+> elements                       # 查看可操作元素
+> c .btn-login                   # 点击登录
+> t #email "test@example.com"    # 输入邮箱
+> t #password "123456"           # 输入密码
+> c button[type="submit"]        # 提交
+> text                           # 确认结果
+```
+
+Agent 可以：**导航 → 观察 → 交互 → 反馈 → 继续**
+
+## 愿景
+
+成为 AI Agent 的**标准浏览器交互层**，让任何 Agent 都能通过命令式界面控制浏览器，完成：
+- 表单填写、登录认证
+- 信息抓取、内容探索
+- 复杂多步业务流程
+
+## 相关文档
+
+- [PRD 产品需求文档](./NAVCLI_PRD.md)

navcli-0.1.0/docs/README.md

@@ -0,0 +1,46 @@
+# NavCLI - 目标与愿景
+
+## 核心目标
+
+**让 AI Agent 能够像人类一样浏览网页。**
+
+现有方案（HTTP API、无头浏览器脚本、Playwright MCP）存在局限：
+- 不支持 JS 渲染的 SPA
+- 无会话状态持久化
+- 缺乏交互式探索能力
+
+NavCLI 的定位：**可交互、可探索的浏览器命令行工具**
+
+## 核心价值
+
+| 特性 | NavCLI 解决的问题 |
+|------|------------------|
+| JS 渲染支持 | 完整支持 SPA 应用 |
+| 会话持久化 | cookies、session 保持 |
+| 交互式 CLI | Agent 可边探索边操作 |
+| Token 优化 | 轻量 elements + 按需 text/html |
+
+## 典型工作流
+
+```bash
+> g https://example.com          # 导航
+> elements                       # 查看可操作元素
+> c .btn-login                   # 点击登录
+> t #email "test@example.com"    # 输入邮箱
+> t #password "123456"           # 输入密码
+> c button[type="submit"]        # 提交
+> text                           # 确认结果
+```
+
+Agent 可以：**导航 → 观察 → 交互 → 反馈 → 继续**
+
+## 愿景
+
+成为 AI Agent 的**标准浏览器交互层**，让任何 Agent 都能通过命令式界面控制浏览器，完成：
+- 表单填写、登录认证
+- 信息抓取、内容探索
+- 复杂多步业务流程
+
+## 相关文档
+
+- [PRD 产品需求文档](./NAVCLI_PRD.md)

navcli-0.1.0/navcli/cli/__init__.py

@@ -0,0 +1,5 @@
+"""NavCLI - Browser automation CLI client."""
+
+from navcli.cli.app import NavCLI, main
+
+__all__ = ["NavCLI", "main"]

navcli-0.1.0/navcli/cli/app.py

@@ -0,0 +1,84 @@
+"""NavCLI - Browser automation command line interface."""
+
+import cmd2
+from navcli.cli.client import NavClient
+from navcli.cli.commands.navigation import NavigationCommands
+from navcli.cli.commands.interaction import InteractionCommands
+from navcli.cli.commands.query import QueryCommands
+from navcli.cli.commands.explore import ExploreCommands
+from navcli.cli.commands.control import ControlCommands
+
+
+class NavCLI(
+    NavigationCommands,
+    InteractionCommands,
+    QueryCommands,
+    ExploreCommands,
+    ControlCommands,
+    cmd2.Cmd
+):
+    """NavCLI main application class."""
+
+    def __init__(self):
+        super().__init__(client=NavClient())
+        self.prompt = "(navcli) "
+        self.doc_header = "Available commands"
+
+    def do_help(self, args):
+        """Show help or help for specific command.
+
+        Usage: help [command]
+        """
+        if args:
+            # Show help for specific command
+            super().do_help(args)
+        else:
+            # Show categorized help
+            self.poutput("\nNavigation Commands:")
+            self.poutput("  goto <url>    Navigate to URL")
+            self.poutput("  back          Go back in history")
+            self.poutput("  forward       Go forward in history")
+            self.poutput("  reload        Reload current page")
+
+            self.poutput("\nInteraction Commands:")
+            self.poutput("  click <sel> [--force]   Click element")
+            self.poutput("  type <sel> <text>       Type text into input")
+            self.poutput("  clear <sel>             Clear input field")
+            self.poutput("  upload <sel> <path>      Upload file")
+
+            self.poutput("\nQuery Commands:")
+            self.poutput("  elements      Get interactive elements")
+            self.poutput("  text          Get page text content")
+            self.poutput("  html          Get page HTML content")
+            self.poutput("  screenshot    Take page screenshot")
+            self.poutput("  state         Get full page state")
+            self.poutput("  url           Get current URL")
+            self.poutput("  title         Get page title")
+
+            self.poutput("\nExplore Commands:")
+            self.poutput("  find <text>        Find element by text")
+            self.poutput("  findall <text>     Find all elements by text")
+            self.poutput("  inspect <sel>      Inspect element details")
+            self.poutput("  wait [--sel/--sec] Wait for selector or timeout")
+            self.poutput("  wait_idle [sec]    Wait for network idle")
+
+            self.poutput("\nControl Commands:")
+            self.poutput("  quit        Close browser")
+            self.poutput("  shutdown    Shutdown server")
+            self.poutput("  exit        Exit CLI")
+            self.poutput("")
+
+
+def main():
+    """Entry point for navcli command."""
+    import sys
+    cli = NavCLI()
+    # Run command if provided as argument
+    if len(sys.argv) > 1:
+        cli.onecmd(" ".join(sys.argv[1:]))
+    else:
+        cli.cmdloop()
+
+
+if __name__ == "__main__":
+    main()

navcli-0.1.0/navcli/cli/client.py

@@ -0,0 +1,271 @@
+"""HTTP client for NavCLI server communication."""
+
+import aiohttp
+from typing import Optional
+from urllib.parse import urljoin
+
+DEFAULT_BASE_URL = "http://127.0.0.1:8765"
+
+
+class NavClient:
+    """Async HTTP client for NavCLI server."""
+
+    def __init__(self, base_url: str = DEFAULT_BASE_URL):
+        self.base_url = base_url.rstrip("/")
+        self.session: Optional[aiohttp.ClientSession] = None
+
+    async def connect(self):
+        """Create aiohttp session."""
+        if self.session is None:
+            self.session = aiohttp.ClientSession()
+
+    async def close(self):
+        """Close aiohttp session."""
+        if self.session:
+            await self.session.close()
+            self.session = None
+
+    async def _request(self, method: str, path: str, **kwargs):
+        """Make HTTP request to server."""
+        if self.session is None:
+            await self.connect()
+
+        url = urljoin(self.base_url + "/", path.lstrip("/"))
+        async with self.session.request(method, url, **kwargs) as response:
+            return await response.json()
+
+    # Navigation commands
+    async def goto(self, url: str, wait_until: str = "networkidle"):
+        """Navigate to URL."""
+        return await self._request("POST", f"/cmd/goto?url={url}&wait_until={wait_until}")
+
+    async def back(self):
+        """Go back in history."""
+        return await self._request("POST", "/cmd/back")
+
+    async def forward(self):
+        """Go forward in history."""
+        return await self._request("POST", "/cmd/forward")
+
+    async def reload(self):
+        """Reload current page."""
+        return await self._request("POST", "/cmd/reload")
+
+    # Interaction commands
+    async def click(self, selector: str, force: bool = False):
+        """Click an element."""
+        return await self._request("POST", f"/cmd/click?selector={selector}&force={force}")
+
+    async def type(self, selector: str, text: str):
+        """Type text into input."""
+        import urllib.parse
+        encoded_text = urllib.parse.quote(text)
+        return await self._request("POST", f"/cmd/type?selector={selector}&text={encoded_text}")
+
+    async def clear(self, selector: str):
+        """Clear input field."""
+        return await self._request("POST", f"/cmd/clear?selector={selector}")
+
+    async def upload(self, selector: str, file_path: str):
+        """Upload file to input."""
+        import urllib.parse
+        encoded_path = urllib.parse.quote(file_path)
+        return await self._request("POST", f"/cmd/upload?selector={selector}&file_path={encoded_path}")
+
+    async def dblclick(self, selector: str):
+        """Double-click an element."""
+        return await self._request("POST", f"/cmd/dblclick?selector={selector}")
+
+    async def rightclick(self, selector: str):
+        """Right-click an element."""
+        return await self._request("POST", f"/cmd/rightclick?selector={selector}")
+
+    # Query commands
+    async def get_elements(self):
+        """Get interactive elements."""
+        return await self._request("GET", "/query/elements")
+
+    async def get_text(self):
+        """Get page text."""
+        return await self._request("GET", "/query/text")
+
+    async def get_html(self):
+        """Get page HTML."""
+        return await self._request("GET", "/query/html")
+
+    async def get_screenshot(self):
+        """Get page screenshot."""
+        return await self._request("GET", "/query/screenshot")
+
+    async def get_state(self):
+        """Get page state."""
+        return await self._request("GET", "/query/state")
+
+    async def get_url(self):
+        """Get current URL."""
+        return await self._request("GET", "/query/url")
+
+    async def get_title(self):
+        """Get page title."""
+        return await self._request("GET", "/query/title")
+
+    async def evaluate(self, expr: str):
+        """Evaluate JavaScript expression."""
+        import urllib.parse
+        encoded = urllib.parse.quote(expr)
+        return await self._request("GET", f"/query/evaluate?expr={encoded}")
+
+    async def get_links(self):
+        """Get all links on the page."""
+        return await self._request("GET", "/query/links")
+
+    async def get_forms(self):
+        """Get all forms on the page."""
+        return await self._request("GET", "/query/forms")
+
+    # Explore commands
+    async def find(self, text: str):
+        """Find element by text."""
+        import urllib.parse
+        encoded_text = urllib.parse.quote(text)
+        return await self._request("GET", f"/explore/find?text={encoded_text}")
+
+    async def findall(self, text: str):
+        """Find all elements by text."""
+        import urllib.parse
+        encoded_text = urllib.parse.quote(text)
+        return await self._request("GET", f"/explore/findall?text={encoded_text}")
+
+    async def inspect(self, selector: str):
+        """Inspect element details."""
+        import urllib.parse
+        encoded_selector = urllib.parse.quote(selector)
+        return await self._request("GET", f"/explore/inspect?selector={encoded_selector}")
+
+    async def wait(self, selector: str = None, seconds: float = None):
+        """Wait for selector or timeout."""
+        if selector:
+            import urllib.parse
+            encoded = urllib.parse.quote(selector)
+            return await self._request("POST", f"/explore/wait?selector={encoded}")
+        elif seconds is not None:
+            return await self._request("POST", f"/explore/wait?seconds={seconds}")
+        else:
+            return await self._request("POST", "/explore/wait")
+
+    async def wait_idle(self, timeout: float = 3.0):
+        """Wait for network idle."""
+        return await self._request("POST", f"/explore/wait/idle?timeout={timeout}")
+
+    async def scroll(self, direction: str = None, x: int = None, y: int = None, selector: str = None):
+        """Scroll the page.
+
+        Args:
+            direction: top, bottom, up, down
+            x, y: coordinates
+            selector: element selector to scroll into view
+        """
+        import urllib.parse
+
+        params = []
+        if direction:
+            params.append(f"direction={direction}")
+        elif x is not None and y is not None:
+            params.append(f"x={x}&y={y}")
+        elif selector:
+            encoded = urllib.parse.quote(selector)
+            params.append(f"selector={encoded}")
+
+        if params:
+            return await self._request("POST", f"/explore/scroll?{'&'.join(params)}")
+        else:
+            return await self._request("POST", "/explore/scroll?direction=down")
+
+    # Control commands
+    async def quit(self):
+        """Quit browser."""
+        return await self._request("POST", "/cmd/quit")
+
+    async def shutdown(self):
+        """Shutdown server."""
+        return await self._request("POST", "/cmd/shutdown")
+
+    # Session commands
+    async def get_cookies(self):
+        """Get all cookies."""
+        return await self._request("GET", "/cmd/cookies")
+
+    async def clear_cookies(self):
+        """Clear all cookies."""
+        return await self._request("DELETE", "/cmd/cookies/clear")
+
+    async def set_cookie(self, name: str, value: str, domain: str, path: str = "/",
+                         expires: int = None, http_only: bool = False,
+                         secure: bool = False, same_site: str = None):
+        """Set a cookie.
+
+        Args:
+            name: Cookie name
+            value: Cookie value
+            domain: Domain for cookie
+            path: Cookie path (default: "/")
+            expires: Expiration timestamp
+            http_only: HttpOnly flag
+            secure: Secure flag
+            same_site: SameSite attribute
+        """
+        import urllib.parse
+        import json
+
+        body = {
+            "name": name,
+            "value": value,
+            "domain": domain,
+            "path": path,
+        }
+        if expires is not None:
+            body["expires"] = expires
+        if http_only:
+            body["httpOnly"] = http_only
+        if secure:
+            body["secure"] = secure
+        if same_site:
+            body["sameSite"] = same_site
+
+        return await self._request("POST", "/cmd/cookies/set", json=body)
+
+    async def save_session(self, path: str = ".navcli_session.json"):
+        """Save session to file.
+
+        Args:
+            path: File path to save session
+        """
+        import urllib.parse
+        encoded_path = urllib.parse.quote(path)
+        return await self._request("POST", f"/cmd/session/save?path={encoded_path}")
+
+    async def load_session(self, path: str = ".navcli_session.json"):
+        """Load session from file.
+
+        Args:
+            path: File path to load session from
+        """
+        import urllib.parse
+        encoded_path = urllib.parse.quote(path)
+        return await self._request("POST", f"/cmd/session/load?path={encoded_path}")
+
+
+async def main():
+    """Test client connection."""
+    client = NavClient()
+    try:
+        await client.connect()
+        result = await client.get_state()
+        print(result)
+    finally:
+        await client.close()
+
+
+if __name__ == "__main__":
+    import asyncio
+    asyncio.run(main())

navcli-0.1.0/navcli/cli/commands/base.py

@@ -0,0 +1,46 @@
+"""Base command class for NavCLI commands."""
+
+import cmd2
+from navcli.cli.client import NavClient
+
+
+class BaseBrowserCommand(cmd2.Cmd):
+    """Base class for browser commands with client connection."""
+
+    def __init__(self, client: NavClient):
+        super().__init__()
+        self.client = client
+        self.prompt = "(browser) "
+
+    def connect_client(self):
+        """Ensure client is connected."""
+        return self.client.connect()
+
+    async def run_async_client(self, coro):
+        """Run async client method."""
+        await self.connect_client()
+        try:
+            return await coro
+        finally:
+            await self.client.close()
+
+    def pretty_result(self, result: dict):
+        """Format command result for display."""
+        if result.get("success"):
+            feedback = result.get("feedback", {})
+            self.poutput(f"[OK] {feedback.get('action', 'done')}")
+            if feedback.get("result"):
+                self.poutput(f"  Result: {feedback.get('result')}")
+            state = result.get("state", {})
+            if state.get("url"):
+                self.poutput(f"  URL: {state.get('url')}")
+            if state.get("title"):
+                self.poutput(f"  Title: {state.get('title')}")
+        else:
+            error = result.get("error", "Unknown error")
+            self.perror(f"[FAIL] {error}")
+
+    def complete_url(self, text, line, begidx, endidx):
+        """Complete URL with common prefixes."""
+        urls = ["http://", "https://", "http://www.", "https://www."]
+        return [u for u in urls if u.startswith(text)]

navcli-0.1.0/navcli/cli/commands/control.py

@@ -0,0 +1,119 @@
+"""Control commands: quit, shutdown, save_session, load_session, cookies."""
+
+import cmd2
+from navcli.cli.commands.base import BaseBrowserCommand
+
+
+class ControlCommands(BaseBrowserCommand):
+    """Control command set."""
+
+    def __init__(self, client):
+        super().__init__(client)
+
+    @cmd2.with_argparser(cmd2.Cmd2ArgumentParser())
+    def do_quit(self, _):
+        """Close the browser.
+
+        Usage: quit
+        """
+        import asyncio
+
+        async def _quit():
+            return await self.client.quit()
+
+        result = asyncio.run(self.run_async_client(_quit))
+        self.pretty_result(result)
+
+    @cmd2.with_argparser(cmd2.Cmd2ArgumentParser())
+    def do_shutdown(self, _):
+        """Shutdown the server.
+
+        Usage: shutdown
+        """
+        import asyncio
+
+        async def _shutdown():
+            return await self.client.shutdown()
+
+        result = asyncio.run(self.run_async_client(_shutdown))
+        self.pretty_result(result)
+
+    @cmd2.with_argparser(cmd2.Cmd2ArgumentParser())
+    def do_exit(self, _):
+        """Exit the CLI.
+
+        Usage: exit
+        """
+        self.poutput("Goodbye!")
+        return True
+
+    # Session commands
+
+    save_parser = cmd2.Cmd2ArgumentParser()
+    save_parser.add_argument("path", nargs="?", default=".navcli_session.json",
+                              help="Path to save session file")
+
+    @cmd2.with_argparser(save_parser)
+    def do_save_session(self, args):
+        """Save session (cookies, storage) to file.
+
+        Usage: save_session [path]
+        Example: save_session my_session.json
+        """
+        import asyncio
+
+        async def _save():
+            return await self.client.save_session(args.path)
+
+        result = asyncio.run(self.run_async_client(_save))
+        self.pretty_result(result)
+
+    load_parser = cmd2.Cmd2ArgumentParser()
+    load_parser.add_argument("path", nargs="?", default=".navcli_session.json",
+                              help="Path to load session file from")
+
+    @cmd2.with_argparser(load_parser)
+    def do_load_session(self, args):
+        """Load session (cookies, storage) from file.
+
+        Usage: load_session [path]
+        Example: load_session my_session.json
+        """
+        import asyncio
+
+        async def _load():
+            return await self.client.load_session(args.path)
+
+        result = asyncio.run(self.run_async_client(_load))
+        self.pretty_result(result)
+
+    @cmd2.with_argparser(cmd2.Cmd2ArgumentParser())
+    def do_cookies(self, _):
+        """Show current cookies.
+
+        Usage: cookies
+        """
+        import asyncio
+
+        async def _get():
+            return await self.client.get_cookies()
+
+        result = asyncio.run(self.run_async_client(_get))
+        if result.get("success"):
+            self.poutput("[OK] got cookies")
+        else:
+            self.perror(f"[FAIL] {result.get('error')}")
+
+    @cmd2.with_argparser(cmd2.Cmd2ArgumentParser())
+    def do_clear_cookies(self, _):
+        """Clear all cookies.
+
+        Usage: clear_cookies
+        """
+        import asyncio
+
+        async def _clear():
+            return await self.client.clear_cookies()
+
+        result = asyncio.run(self.run_async_client(_clear))
+        self.pretty_result(result)