navcli 0.2.0__tar.gz → 0.2.2__tar.gz

{navcli-0.2.0 → navcli-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: navcli
-Version: 0.2.0
+Version: 0.2.2
 Summary: 可交互、可探索的浏览器命令行工具，专为 AI Agent 设计
 Author: NavCLI Team
 License: MIT
@@ -76,4 +76,6 @@ Become the **standard browser interaction layer** for AI Agents, enabling any Ag
 
 ## Related Documentation
 
+- [Skill File Download](https://github.com/wumu2013/navcli/blob/main/docs/skill.md)
+- [Project Homepage](https://make.datavoid.fun/navcli/)
 - [PRD Product Requirements](./NAVCLI_PRD.md)

navcli-0.2.2/README.md

@@ -0,0 +1,180 @@
+# NavCLI - Browser Automation CLI for AI Agents
+
+[![PyPI Version](https://img.shields.io/pypi/v/navcli)](https://pypi.org/project/navcli/)
+[![GitHub](https://img.shields.io/badge/GitHub-wumu2013/navcli-blue)](https://github.com/wumu2013/navcli)
+
+**Enable AI Agents to browse the web like humans.**
+
+## What is NavCLI?
+
+NavCLI is an interactive, explorable browser CLI designed for AI Agents. Unlike HTTP APIs or headless browser scripts, NavCLI provides:
+
+- **Full SPA Support** - JavaScript-rendered pages work seamlessly
+- **Session Persistence** - Cookies and login sessions maintained across requests
+- **Interactive CLI** - Agents can explore and interact dynamically
+- **Token Optimization** - Lightweight element queries with on-demand content
+
+## Quick Start
+
+```bash
+pip install navcli
+```
+
+### Start Server
+
+```bash
+nav-server
+```
+
+### Use CLI
+
+```bash
+nav
+```
+
+Or run commands directly:
+
+```bash
+nav g https://example.com
+nav tables
+nav paragraphs
+```
+
+## Data Extraction
+
+> **IMPORTANT**: For data extraction, focus on `tables` and `paragraphs`.
+
+| Command | Description |
+|---------|-------------|
+| `nav tables` | Extract all `<table>` elements with structured data |
+| `nav paragraphs` | Extract large text paragraphs (200+ chars) |
+| `nav g <url>` | Navigate + auto-fetch paragraphs on first call |
+
+## Core Commands
+
+### Navigation
+
+```bash
+nav g <url>       # Navigate to URL
+nav b             # Go back
+nav f             # Go forward
+nav r             # Reload
+```
+
+### Interaction
+
+```bash
+nav c <sel> [--force]       # Click element
+nav t <sel> <txt>            # Type text
+nav clear <sel>              # Clear input
+nav upload <sel> <path>     # Upload file
+```
+
+### Query
+
+```bash
+nav elements              # Interactive elements
+nav text                  # Page text content
+nav html                  # Page HTML
+nav screenshot            # Screenshot (base64)
+nav state                 # Full page state
+nav url                   # Current URL
+nav title                 # Page title
+nav tables                # All tables with data
+nav paragraphs [len]      # Large text paragraphs
+nav links                 # All hyperlinks
+nav forms                 # All forms
+```
+
+### Explore
+
+```bash
+nav find <text>           # Find element by text
+nav findall <text>        # Find all elements by text
+nav inspect <sel>         # Inspect element details
+nav wait_idle [sec]       # Wait for network idle
+nav scroll top|bottom|up|down  # Scroll page
+```
+
+### Session
+
+```bash
+nav cookies              # Show cookies
+nav save_session [name]  # Save session
+nav load_session [name]  # Load session
+```
+
+### Control
+
+```bash
+nav quit    # Close browser
+nav exit    # Exit CLI
+```
+
+## Agent Workflow
+
+```
+Navigate → Observe → Interact → Feedback → Continue
+```
+
+```bash
+# 1 Navigate - Go to target page
+nav g https://example.com/data-page
+
+# 2 Observe - Check what data is available
+nav tables         # Extract tabular data
+nav paragraphs     # Extract text content
+
+# 3 Interact - Navigate/paginate if needed
+nav find "Next"
+nav c a.next-page
+nav wait_idle
+
+# 4 Feedback - Verify data extraction
+nav tables
+nav paragraphs
+
+# 5 Continue - Proceed to next data source
+nav g https://example.com/page2
+```
+
+## API
+
+NavCLI uses a client-server architecture with HTTP API:
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/cmd/goto?url=<url>` | Navigate to URL |
+| POST | `/cmd/click?selector=<s>` | Click element |
+| GET | `/query/tables` | Get all tables |
+| GET | `/query/paragraphs` | Get large text paragraphs |
+| GET | `/query/elements` | Get interactive elements |
+| POST | `/cmd/session/save?name=<n>` | Save session |
+| POST | `/cmd/session/load?name=<n>` | Load session |
+
+See [docs/skill.md](docs/skill.md) for complete API reference.
+
+## Session Persistence
+
+Save login sessions for authenticated access:
+
+```bash
+# Save after login
+nav save_session jisilu
+
+# Load session for future headless access
+nav load_session jisilu
+```
+
+Sessions are stored in `~/.navcli/sessions/`.
+
+## Documentation
+
+- [CLI & API Reference](docs/skill.md)
+- [Skill File Download](https://github.com/wumu2013/navcli/blob/main/docs/skill.md)
+- [Project Homepage](https://make.datavoid.fun/navcli/)
+- [Product Requirements](docs/NAVCLI_PRD.md)
+
+## License
+
+MIT

{navcli-0.2.0 → navcli-0.2.2}/docs/README.md

@@ -43,4 +43,6 @@ Become the **standard browser interaction layer** for AI Agents, enabling any Ag
 
 ## Related Documentation
 
+- [Skill File Download](https://github.com/wumu2013/navcli/blob/main/docs/skill.md)
+- [Project Homepage](https://make.datavoid.fun/navcli/)
 - [PRD Product Requirements](./NAVCLI_PRD.md)

{navcli-0.2.0 → navcli-0.2.2}/navcli/server/__init__.py

@@ -22,13 +22,15 @@ _NAVCLI_SESSIONS_DIR = os.path.join(_NAVCLI_HOME, "sessions")
 _server: Optional[uvicorn.Server] = None
 
 
-async def start_server(host: str = "127.0.0.1", port: int = 8765, headless: bool = True) -> uvicorn.Server:
+async def start_server(host: str = "127.0.0.1", port: int = 8765, headless: bool = True,
+                       browser_args: Optional[list] = None) -> uvicorn.Server:
     """Start the browser server.
 
     Args:
         host: Host to bind
         port: Port to listen
         headless: Run browser in headless mode (default: True)
+        browser_args: Additional browser launch arguments
 
     Returns:
         Uvicorn server instance
@@ -36,7 +38,7 @@ async def start_server(host: str = "127.0.0.1", port: int = 8765, headless: bool
     global _server
 
     # Start browser
-    await start_browser(headless=headless)
+    await start_browser(headless=headless, args=browser_args)
 
     # Create app
     app = create_app()
@@ -80,9 +82,20 @@ def main():
                         help="Run in headless mode (default)")
     parser.add_argument("--no-headless", dest="headless", action="store_false",
                         help="Run with GUI (non-headless)")
+    parser.add_argument("--memory-limit", type=int, default=None,
+                        help="Browser memory limit in MB (e.g., --memory-limit 512)")
 
     args = parser.parse_args()
 
+    # Build browser args for memory limit
+    browser_args = None
+    if args.memory_limit:
+        browser_args = [
+            f"--js-flags=--max-old-space-size={args.memory_limit}",
+            "--disable-dev-shm-usage",
+        ]
+        print(f"Memory limit: {args.memory_limit}MB")
+
     print(f"Starting NavCLI Browser Server on {args.host}:{args.port}...")
     print(f"Headless: {args.headless}")
     print("-" * 60)
@@ -117,7 +130,7 @@ def main():
     print("-" * 60)
 
     try:
-        asyncio.run(start_server(args.host, args.port, headless=args.headless))
+        asyncio.run(start_server(args.host, args.port, headless=args.headless, browser_args=browser_args))
     except KeyboardInterrupt:
         print("\nShutting down...")
         sys.exit(0)

{navcli-0.2.0 → navcli-0.2.2}/navcli/server/browser.py

@@ -25,11 +25,12 @@ _NAVCLI_SESSIONS_DIR = os.path.join(_NAVCLI_HOME, "sessions")
 _storage_state_path: str = os.path.join(_NAVCLI_SESSIONS_DIR, "session.json")  # Default session file
 
 
-async def start_browser(headless: bool = True):
+async def start_browser(headless: bool = True, args: Optional[list] = None):
     """Start the browser.
 
     Args:
         headless: Whether to run in headless mode (default: True)
+        args: Additional browser launch arguments
     """
     global _browser, _context, _page
 
@@ -43,6 +44,8 @@ async def start_browser(headless: bool = True):
     user_data_dir = os.environ.get("NAVCLI_USER_DATA_DIR")
 
     launch_kwargs = {"headless": headless}
+    if args:
+        launch_kwargs["args"] = args
     if executable_path:
         launch_kwargs["executable_path"] = executable_path
 

{navcli-0.2.0 → navcli-0.2.2}/navcli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: navcli
-Version: 0.2.0
+Version: 0.2.2
 Summary: 可交互、可探索的浏览器命令行工具，专为 AI Agent 设计
 Author: NavCLI Team
 License: MIT
@@ -76,4 +76,6 @@ Become the **standard browser interaction layer** for AI Agents, enabling any Ag
 
 ## Related Documentation
 
+- [Skill File Download](https://github.com/wumu2013/navcli/blob/main/docs/skill.md)
+- [Project Homepage](https://make.datavoid.fun/navcli/)
 - [PRD Product Requirements](./NAVCLI_PRD.md)

{navcli-0.2.0 → navcli-0.2.2}/navcli.egg-info/SOURCES.txt

@@ -1,3 +1,4 @@
+README.md
 pyproject.toml
 docs/README.md
 navcli.egg-info/PKG-INFO

{navcli-0.2.0 → navcli-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "navcli"
-version = "0.2.0"
+version = "0.2.2"
 description = "可交互、可探索的浏览器命令行工具，专为 AI Agent 设计"
 readme = "docs/README.md"
 requires-python = ">=3.9"