kingai-browser 0.3.0__tar.gz

kingai_browser-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KingAI Browser contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kingai_browser-0.3.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE
+include THIRD_PARTY_NOTICES.txt
+include README.zh-CN.md
+recursive-include tests *.py

kingai_browser-0.3.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: kingai-browser
+Version: 0.3.0
+Summary: Python code API for the installed KingAI stdio MCP server
+License-Expression: MIT
+Project-URL: Homepage, https://www.kingaibrowser.cn
+Project-URL: Repository, https://github.com/KingOX-cpp/KingAIBrowser
+Project-URL: Issues, https://github.com/KingOX-cpp/KingAIBrowser/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.txt
+Dynamic: license-file
+
+# KingAI Browser Python SDK
+
+Python 3.10+ client for KingAI Browser's installed stdio MCP server. Manage saved fingerprint environments and automate pages without Playwright or a separate HTTP service.
+
+[Website](https://www.kingaibrowser.cn/) · [Alternative website](https://kingaibrowser.ccwu.cc/) · [Source and examples](https://github.com/KingOX-cpp/KingAIBrowser) · [Browser releases](https://github.com/KingOX-cpp/KingAIBrowser/releases)
+
+## Install the SDK
+
+```shell
+python -m pip install kingai-browser
+```
+
+The Python runtime library uses only the standard library. Browser installation and account login are separate from installing the SDK.
+
+## Download the browser
+
+```shell
+python -m kingai_browser install
+```
+
+Supports Windows Intel/AMD x64 and Apple Silicon macOS only. The explicit install command downloads and opens the Windows installer or macOS DMG; complete the installation UI yourself. It is not a silent installer. Open KingAI Manager and sign in after installation.
+
+For download only:
+
+```python
+from kingai_browser import install
+result = install(download_only=True)
+print(result["status"], result["installerPath"])
+```
+
+Windows downloads default to D:\code\KingAIBrowser-downloads; macOS uses ~/Downloads/KingAIBrowser. Set download_dir to an absolute path to change installer storage. It does not select the browser installation folder. HTTPS certificate verification remains enabled; IP certificate mismatches fail. Optional sha256 compares the installer to a trusted checksum supplied by the caller. A calculated hash alone is not authenticity verification.
+
+## Locate MCP and diagnose
+
+The SDK finds MCP using an explicit mcp_executable option, KINGAI_MCP_EXECUTABLE, or the per-user installation record written by a compatible Manager. KingAIMcpServer and KingAIRuntime must be installed together. The browser executable is not the MCP server.
+
+```shell
+python -m kingai_browser doctor
+```
+
+Doctor reports installation discovery, MCP version and available tools without launching a browser. It does not verify Runtime compatibility or account login. Native stderr is forwarded to your terminal; redact sensitive information before sharing it.
+
+## Open a saved environment
+
+```python
+from kingai_browser import launch
+
+with launch() as browser:
+    browser.new_tab("https://example.com")
+    print(browser.read())
+```
+
+The default is the existing unique saved profile named 默认环境. If it does not exist, explicitly select a saved profile with launch(profile_id="actual-profile-id") or create one using the management API. No temporary fallback is created.
+
+Context exit detaches and releases the owned MCP connection while preserving the browser window. Explicit close_browser() closes the browser. After detaching, the original session cannot continue controlling that window; use Manager or explicitly attach a new authorized client to the active session.
+
+## Profiles, DOM and input
+
+```python
+from kingai_browser import KingAI
+
+with KingAI() as api:
+    print(api.profiles())
+    created = api.create_profile("My unique profile", language="en-US")
+    profile_id = created["profileId"]
+    api.update_profile(profile_id, name="My configured profile")
+    browser = api.start(profile_id=profile_id)
+    try:
+        browser.new_tab("https://example.com")
+        print(browser.snapshot(mode="interactive", limit=30))
+        print(browser.query(role="link", include_html=True, limit=10))
+    finally:
+        browser.detach()
+```
+
+On a page containing your target input/button, query its DOM and use a freshly observed ref:
+
+```python
+matches = browser.query(selector="#name", limit=2)["elements"]
+if len(matches) != 1:
+    raise RuntimeError("Expected one input")
+browser.fill(ref=matches[0]["ref"], text="KingAI", humanize=False)
+```
+
+This last fragment requires a live session and a page containing #name; example.com does not contain that input. Full runnable form examples and a local playground are in the source repository.
+
+All installed MCP tools remain available through api.tools() and api.call(name, arguments). AsyncKingAI provides the async interface; BrowserAutomation provides an optional Agent action facade.
+
+## Important behavior
+
+- Update closed profiles only. Deletion requires explicit confirmation and removes saved data.
+- Sessions operate on a selected tab. Serialize multi-step input workflows.
+- Humanize requires valid account entitlement. Limits apply to concurrent open environments, not individual clicks.
+- PAGE_NOT_VISIBLE requires restoring the window and activating the intended tab.
+- A dispatched action is not proof of business completion. Independently observe the page result.
+- Timeouts and observation errors do not automatically retry side effects.
+- evaluate_preview provides bounded output and may truncate results.
+
+Browser download/installation and real-site automation have not been validated as part of the first package publication. Installation/import checks do not establish browser compatibility or anti-detection performance.
+
+## 中文说明
+
+本包提供 Python 同步、异步调用，以及保存环境管理、DOM 观察、点击输入和通用 MCP 工具调用。先安装 SDK，再显式下载并完成浏览器安装、打开管理器登录。默认启动使用已存在的唯一“默认环境”，不会自动创建临时环境。with launch() 退出保留窗口；显式 close_browser() 才关闭浏览器。
+
+完整中英文使用说明、示例和问题反馈请访问上述 GitHub 仓库。Windows 仅支持 Intel/AMD x64，Mac 仅支持 Apple 芯片。
+
+## License
+
+MIT. Retain copyright, license and applicable third-party notices. This package contains client SDK code; third-party notices are included in the distribution.

kingai_browser-0.3.0/PYPI_README.md

@@ -0,0 +1,109 @@
+# KingAI Browser Python SDK
+
+Python 3.10+ client for KingAI Browser's installed stdio MCP server. Manage saved fingerprint environments and automate pages without Playwright or a separate HTTP service.
+
+[Website](https://www.kingaibrowser.cn/) · [Alternative website](https://kingaibrowser.ccwu.cc/) · [Source and examples](https://github.com/KingOX-cpp/KingAIBrowser) · [Browser releases](https://github.com/KingOX-cpp/KingAIBrowser/releases)
+
+## Install the SDK
+
+```shell
+python -m pip install kingai-browser
+```
+
+The Python runtime library uses only the standard library. Browser installation and account login are separate from installing the SDK.
+
+## Download the browser
+
+```shell
+python -m kingai_browser install
+```
+
+Supports Windows Intel/AMD x64 and Apple Silicon macOS only. The explicit install command downloads and opens the Windows installer or macOS DMG; complete the installation UI yourself. It is not a silent installer. Open KingAI Manager and sign in after installation.
+
+For download only:
+
+```python
+from kingai_browser import install
+result = install(download_only=True)
+print(result["status"], result["installerPath"])
+```
+
+Windows downloads default to D:\code\KingAIBrowser-downloads; macOS uses ~/Downloads/KingAIBrowser. Set download_dir to an absolute path to change installer storage. It does not select the browser installation folder. HTTPS certificate verification remains enabled; IP certificate mismatches fail. Optional sha256 compares the installer to a trusted checksum supplied by the caller. A calculated hash alone is not authenticity verification.
+
+## Locate MCP and diagnose
+
+The SDK finds MCP using an explicit mcp_executable option, KINGAI_MCP_EXECUTABLE, or the per-user installation record written by a compatible Manager. KingAIMcpServer and KingAIRuntime must be installed together. The browser executable is not the MCP server.
+
+```shell
+python -m kingai_browser doctor
+```
+
+Doctor reports installation discovery, MCP version and available tools without launching a browser. It does not verify Runtime compatibility or account login. Native stderr is forwarded to your terminal; redact sensitive information before sharing it.
+
+## Open a saved environment
+
+```python
+from kingai_browser import launch
+
+with launch() as browser:
+    browser.new_tab("https://example.com")
+    print(browser.read())
+```
+
+The default is the existing unique saved profile named 默认环境. If it does not exist, explicitly select a saved profile with launch(profile_id="actual-profile-id") or create one using the management API. No temporary fallback is created.
+
+Context exit detaches and releases the owned MCP connection while preserving the browser window. Explicit close_browser() closes the browser. After detaching, the original session cannot continue controlling that window; use Manager or explicitly attach a new authorized client to the active session.
+
+## Profiles, DOM and input
+
+```python
+from kingai_browser import KingAI
+
+with KingAI() as api:
+    print(api.profiles())
+    created = api.create_profile("My unique profile", language="en-US")
+    profile_id = created["profileId"]
+    api.update_profile(profile_id, name="My configured profile")
+    browser = api.start(profile_id=profile_id)
+    try:
+        browser.new_tab("https://example.com")
+        print(browser.snapshot(mode="interactive", limit=30))
+        print(browser.query(role="link", include_html=True, limit=10))
+    finally:
+        browser.detach()
+```
+
+On a page containing your target input/button, query its DOM and use a freshly observed ref:
+
+```python
+matches = browser.query(selector="#name", limit=2)["elements"]
+if len(matches) != 1:
+    raise RuntimeError("Expected one input")
+browser.fill(ref=matches[0]["ref"], text="KingAI", humanize=False)
+```
+
+This last fragment requires a live session and a page containing #name; example.com does not contain that input. Full runnable form examples and a local playground are in the source repository.
+
+All installed MCP tools remain available through api.tools() and api.call(name, arguments). AsyncKingAI provides the async interface; BrowserAutomation provides an optional Agent action facade.
+
+## Important behavior
+
+- Update closed profiles only. Deletion requires explicit confirmation and removes saved data.
+- Sessions operate on a selected tab. Serialize multi-step input workflows.
+- Humanize requires valid account entitlement. Limits apply to concurrent open environments, not individual clicks.
+- PAGE_NOT_VISIBLE requires restoring the window and activating the intended tab.
+- A dispatched action is not proof of business completion. Independently observe the page result.
+- Timeouts and observation errors do not automatically retry side effects.
+- evaluate_preview provides bounded output and may truncate results.
+
+Browser download/installation and real-site automation have not been validated as part of the first package publication. Installation/import checks do not establish browser compatibility or anti-detection performance.
+
+## 中文说明
+
+本包提供 Python 同步、异步调用，以及保存环境管理、DOM 观察、点击输入和通用 MCP 工具调用。先安装 SDK，再显式下载并完成浏览器安装、打开管理器登录。默认启动使用已存在的唯一“默认环境”，不会自动创建临时环境。with launch() 退出保留窗口；显式 close_browser() 才关闭浏览器。
+
+完整中英文使用说明、示例和问题反馈请访问上述 GitHub 仓库。Windows 仅支持 Intel/AMD x64，Mac 仅支持 Apple 芯片。
+
+## License
+
+MIT. Retain copyright, license and applicable third-party notices. This package contains client SDK code; third-party notices are included in the distribution.

kingai_browser-0.3.0/README.md

@@ -0,0 +1,138 @@
+# KingAI Python SDK guide
+
+English | [简体中文](README.zh-CN.md) | [Project / 项目](../README.md)
+
+**SDK 0.3.0 · MIT · Python 3.10+**
+
+Calls the installed KingAI MCP over stdio. No HTTP service or Playwright is required. Install the browser, sign in and use matching MCP/Runtime components first.
+
+Lifecycle update: Python launch contexts and Java automatic Session resource cleanup detach and preserve windows. Explicit browser shutdown uses Python close()/close_browser(), Node close()/closeBrowser(), Java closeBrowser(), or Go Close()/CloseBrowser(). New ownership cases and launch/doctor changes are unexecuted; the historical 17-test result does not cover them.
+
+After disconnecting, the original Session can no longer operate the retained window. Close it in Manager, or discover the real active session through a new client and explicitly attach if authorized. No automatic reconnection occurs. Java closeBrowser() throws SESSION_DISCONNECTED if its client is closed.
+
+## Download the browser installer
+
+Supports Windows Intel/AMD x64 and Apple Silicon macOS only, not Windows ARM, 32-bit Windows or Intel Mac. Each language has a native downloader. Explicit install calls can download and open the installer/DMG; finish its UI steps yourself. This is not silent installation.
+
+```powershell
+python -m kingai_browser install --download-only
+# Download and open the installer UI
+python -m kingai_browser install
+```
+
+```python
+from kingai_browser import install
+result = install(download_only=True)
+print(result["status"], result["installerPath"])
+```
+
+Windows downloads default to D:. The download directory is not the browser installation directory. TLS verification stays enabled; invalid/mismatched IP certificates fail. Supply a trusted SHA-256 to verify the payload. After installation, open Manager, sign in and run doctor. No installer was downloaded or executed, and no build/check/test was run in this change.
+
+[Full installation guide](../INSTALLATION.md)
+
+## Quick entry: launch
+
+After installation and login, this entry discovers/connects MCP and starts a saved profile. The default must already exist; no missing-profile fallback is created.
+
+```python
+from kingai_browser import launch
+
+browser = launch()  # Existing unique default environment
+try:
+    browser.new_tab("https://example.com")
+    print(browser.read())
+finally:
+    browser.detach()
+```
+
+The returned session owns its new client. Close closes the browser and releases MCP; detach preserves the browser and releases MCP; disconnect only releases the connection. Explicit-client APIs remain available.
+
+[Troubleshooting / 故障排查](../TROUBLESHOOTING.md)
+
+```powershell
+python -m kingai_browser doctor
+```
+
+Read-only diagnostics do not launch browsers. Login is unknown and Runtime unverified. MCP stderr is forwarded to the terminal, not stored in the report. CLI info falls back to basic metadata on older MCP versions.
+
+## Installation and discovery
+
+```powershell
+python -m pip install --cache-dir D:/code/kingai-sdk-cache/pip ./python
+```
+
+```powershell
+$env:KINGAI_MCP_EXECUTABLE = 'D:\Apps\KingAIBrowser\KingAIMcpServer.exe'
+```
+
+Replace the example path. Discovery uses an explicit SDK option, then the environment variable, then the Manager record. Do not pass the main browser executable. Keep caches, temporary files and outputs on D:. Public registry packages are not published.
+
+## Start with a complete example
+
+[Examples and prerequisites / 示例与前提](../examples/README.md) · [API recipes / 接口调用手册](../docs/API_EXAMPLES.md)
+
+```powershell
+# From repository root / 在仓库根目录，另开终端启动演示网页
+python -m http.server 8765 --bind 127.0.0.1 --directory examples
+# Then run in another terminal / 然后另开终端执行
+python python/examples/browser_form_automation.py --live
+```
+
+The complete workflow lists/creates/configures profiles, inspects DOM, queries refs, fills fields, clicks and independently confirms the result. Keep the window visible. Newly created profiles are retained.
+
+## Calling pattern and results
+
+```python
+from kingai_browser import KingAI
+
+with KingAI() as api:
+    profiles = api.profiles()  # Saved environment summaries / 环境摘要
+    print(profiles)
+    profile = api.create_profile("My unique environment", language="en-US")
+    profile_id = profile["profileId"]
+    api.update_profile(profile_id, name="My configured environment")
+    browser = api.start(profile_id=profile_id)
+    try:
+        browser.new_tab("http://127.0.0.1:8765/demo.html")
+        browser.wait(selector="#name", state="visible")
+        print(browser.query(selector="#name", include_html=True))
+        browser.fill("#name", "KingAI", humanize=False)
+        print(browser.read())
+    finally:
+        browser.detach()  # Keep window / 保留窗口
+```
+
+`profileId` identifies saved environments; `sessionId` identifies a running session; `targetId` identifies a tab; `ref` identifies an observed element. / 四类 ID 分别代表环境、会话、标签和已观察元素，不可混用。
+
+## API category map
+
+| Category / 类别 | MCP tools / 工具 | Usage / 用途 |
+| --- | --- | --- |
+| Profiles / 环境 | `profiles_list`, `profiles_get`, `profiles_create`, `profiles_update`, `profiles_delete` | List summaries; create, inspect, configure a closed profile, explicitly delete. / 获取摘要、创建、读取、修改已关闭环境、显式删除。 |
+| Sessions / 会话 | `browser_start`, `browser_sessions_list`, `browser_attach`, `browser_detach`, `browser_close` | Start by profile ID, discover active sessions, attach or detach. Close is destructive. / 按环境 ID 启动、查找和接入会话，区分断开与关闭。 |
+| Tabs / 标签页 | `tabs_list`, `tabs_new`, `tabs_activate`, `tabs_close`, `browser_navigate` | Use returned targetId; activate before input. / 使用返回的 targetId，输入前激活目标标签。 |
+| DOM / 页面 | `browser_read`, `browser_snapshot`, `browser_query`, `browser_wait` | Read text, inspect bounded DOM, obtain refs, wait for explicit conditions. / 读取文本、观察 DOM、取得 ref、等待明确条件。 |
+| Input / 输入 | `browser_click`, `browser_fill`, `browser_type`, `browser_key`, `browser_scroll`, `browser_hover` | Fill replaces text; type appends. Query refs before action. / fill 替换，type 追加；先查询再操作。 |
+| JavaScript / 求值 | `browser_evaluate` | Raw evaluation preserves results; preview is bounded and may truncate. / 原始求值与显式预览不同，预览可能截断。 |
+| Artifacts / 产物 | `browser_screenshot`, `browser_pdf`, `browser_upload`, `browser_download` | Configure artifact/download roots and permitted upload paths. / 配置产物目录、下载目录和上传权限。 |
+| State / 状态 | `cookies_list`, `storage_get` | Inspect local site state; never publish cookies or secrets. / 查看站点状态，不公开 Cookie 或秘密。 |
+| Skills / 工作流 | `skills_list`, `skill_describe`, `skill_run`, `skill_status`, `skill_cancel`, `skill_runs_list` | Discover parameters before starting; poll returned run ID. / 先发现参数，启动后用真实 run ID 查询。 |
+| Discovery / 工具发现 | `sdk_info`, `tools/list`, `runtime_request_status` | Installed schemas are authoritative; Runtime IDs are not JSON-RPC IDs. / 以安装版 schema 为准，区分 Runtime ID 与 JSON-RPC ID。 |
+
+Every installed tool is available through generic `call` / `Call`; convenience methods differ by language. Use the recipes for exact argument examples and inspect `tools/list` for required fields. / 所有安装版工具都能经通用调用访问，便利方法并非每种语言完全相同；参数示例见手册，必填项以安装版 schema 为准。
+
+## Lifecycle, errors and permissions
+
+- Client close disconnects MCP; session close closes the browser. Detach keeps the browser available. / 客户端关闭、会话断开和浏览器关闭含义不同。
+- Default start requires an existing unique 默认环境; it does not create one. / 默认启动不会自动创建缺失环境。
+- Update only closed profiles; deletion requires explicit confirmation and removes persistent data. / 更新前关闭环境；删除需确认且会移除持久数据。
+- Side effects are not automatically retried after timeout or observation failure. / 超时和观察失败不自动重放输入。
+- Humanize needs valid entitlement; examples explicitly use false for basic form interaction. / 拟人化需要有效权益，演示显式关闭。
+- PAGE_NOT_VISIBLE requires restoring the window and selecting the intended tab. / 页面不可见时恢复窗口并激活标签。
+- Call sequences use one selected tab; serialize multi-step workflows. / 多步操作串行，不是 Playwright 多 Page 模型。
+
+## Test scope and license
+
+[SAMPLES.md](../SAMPLES.md) records earlier fixture tests. New examples, documentation and renames have not been built, checked or tested in this task. / 旧模拟测试不代表新增示例已实机验证；本轮未运行构建、检查或测试。
+
+MIT: retain copyright/license and applicable third-party notices. / 允许传播、修改与商用，保留版权、许可及适用的第三方声明。

kingai_browser-0.3.0/README.zh-CN.md

@@ -0,0 +1,138 @@
+# KingAI Python 使用说明
+
+[English](README.md) | 简体中文 | [Project / 项目](../README.md)
+
+**SDK 0.3.0 · MIT · Python 3.10+**
+
+本库通过 stdio 调用已安装的 KingAI MCP，不需要 HTTP 服务或 Playwright。先安装浏览器并登录，MCP/Runtime 必须支持所需工具。
+
+生命周期更新：Python launch 上下文和 Java Session 自动资源退出会 detach 并保留窗口。显式关闭分别使用 Python close()/close_browser()、Node close()/closeBrowser()、Java closeBrowser()、Go Close()/CloseBrowser()。新增 ownership、launch、doctor 均未执行验证，历史 17 项测试不覆盖这些改动。
+
+连接释放后，原 Session 对象不能继续操作保留窗口。可在 Manager 中关闭，或由新客户端发现真实会话、在授权允许时显式 attach 后关闭；SDK 不自动重连。Java closeBrowser() 在客户端已关闭时抛 SESSION_DISCONNECTED。
+
+## 浏览器下载安装
+
+支持 Windows Intel/AMD x64 和 Apple 芯片 Mac，不支持 Windows ARM、32 位 Windows 或 Intel Mac。四语言均提供原生下载实现；显式安装命令可下载并打开安装向导/DMG，仍需用户完成安装，不是静默安装。
+
+```powershell
+python -m kingai_browser install --download-only
+# Download and open the installer UI
+python -m kingai_browser install
+```
+
+```python
+from kingai_browser import install
+result = install(download_only=True)
+print(result["status"], result["installerPath"])
+```
+
+Windows 默认下载到 D 盘；下载目录不是浏览器安装目录。证书校验保持开启，IP 证书不可信或不匹配会失败；可传可信 SHA-256 校验文件。安装后打开 Manager 登录并运行 doctor。新增下载/安装入口本轮未下载或执行安装包，未运行构建、检查或测试。
+
+[完整安装说明](../INSTALLATION.zh-CN.md)
+
+## 快速入口：launch
+
+完成安装和登录后，下面的入口负责定位 MCP、连接并启动环境。默认只打开已有的唯一“默认环境”，不会自动创建缺失环境。
+
+```python
+from kingai_browser import launch
+
+browser = launch()  # Existing unique default environment
+try:
+    browser.new_tab("https://example.com")
+    print(browser.read())
+finally:
+    browser.detach()
+```
+
+返回的会话拥有新客户端。close 关闭浏览器并释放 MCP；detach 保留浏览器并释放 MCP；disconnect 仅释放连接。原有显式客户端 API 保持可用。
+
+[Troubleshooting / 故障排查](../TROUBLESHOOTING.md)
+
+```powershell
+python -m kingai_browser doctor
+```
+
+只读诊断不启动浏览器；登录态显示 unknown，Runtime 未验证。MCP stderr 转发至终端，不存入报告。旧 MCP 缺少 sdk_info 时 CLI info 仍返回基础信息。
+
+## 安装与定位
+
+```powershell
+python -m pip install --cache-dir D:/code/kingai-sdk-cache/pip ./python
+```
+
+```powershell
+$env:KINGAI_MCP_EXECUTABLE = 'D:\Apps\KingAIBrowser\KingAIMcpServer.exe'
+```
+
+示例路径需替换。定位顺序为显式 SDK 参数、环境变量、管理器登记。不能把浏览器主程序当 MCP。依赖、临时文件、缓存与构建输出放 D 盘。公共包尚未发布。
+
+## 从完整示例开始
+
+[Examples and prerequisites / 示例与前提](../examples/README.md) · [API recipes / 接口调用手册](../docs/API_EXAMPLES.md)
+
+```powershell
+# From repository root / 在仓库根目录，另开终端启动演示网页
+python -m http.server 8765 --bind 127.0.0.1 --directory examples
+# Then run in another terminal / 然后另开终端执行
+python python/examples/browser_form_automation.py --live
+```
+
+完整流程展示环境列表、创建与设置、DOM 快照、元素查询、输入、点击、等待并核对结果。窗口需可见；生成的新环境在结束后保留。
+
+## 调用结构与返回值
+
+```python
+from kingai_browser import KingAI
+
+with KingAI() as api:
+    profiles = api.profiles()  # Saved environment summaries / 环境摘要
+    print(profiles)
+    profile = api.create_profile("My unique environment", language="en-US")
+    profile_id = profile["profileId"]
+    api.update_profile(profile_id, name="My configured environment")
+    browser = api.start(profile_id=profile_id)
+    try:
+        browser.new_tab("http://127.0.0.1:8765/demo.html")
+        browser.wait(selector="#name", state="visible")
+        print(browser.query(selector="#name", include_html=True))
+        browser.fill("#name", "KingAI", humanize=False)
+        print(browser.read())
+    finally:
+        browser.detach()  # Keep window / 保留窗口
+```
+
+`profileId` identifies saved environments; `sessionId` identifies a running session; `targetId` identifies a tab; `ref` identifies an observed element. / 四类 ID 分别代表环境、会话、标签和已观察元素，不可混用。
+
+## 接口类别导航
+
+| Category / 类别 | MCP tools / 工具 | Usage / 用途 |
+| --- | --- | --- |
+| Profiles / 环境 | `profiles_list`, `profiles_get`, `profiles_create`, `profiles_update`, `profiles_delete` | List summaries; create, inspect, configure a closed profile, explicitly delete. / 获取摘要、创建、读取、修改已关闭环境、显式删除。 |
+| Sessions / 会话 | `browser_start`, `browser_sessions_list`, `browser_attach`, `browser_detach`, `browser_close` | Start by profile ID, discover active sessions, attach or detach. Close is destructive. / 按环境 ID 启动、查找和接入会话，区分断开与关闭。 |
+| Tabs / 标签页 | `tabs_list`, `tabs_new`, `tabs_activate`, `tabs_close`, `browser_navigate` | Use returned targetId; activate before input. / 使用返回的 targetId，输入前激活目标标签。 |
+| DOM / 页面 | `browser_read`, `browser_snapshot`, `browser_query`, `browser_wait` | Read text, inspect bounded DOM, obtain refs, wait for explicit conditions. / 读取文本、观察 DOM、取得 ref、等待明确条件。 |
+| Input / 输入 | `browser_click`, `browser_fill`, `browser_type`, `browser_key`, `browser_scroll`, `browser_hover` | Fill replaces text; type appends. Query refs before action. / fill 替换，type 追加；先查询再操作。 |
+| JavaScript / 求值 | `browser_evaluate` | Raw evaluation preserves results; preview is bounded and may truncate. / 原始求值与显式预览不同，预览可能截断。 |
+| Artifacts / 产物 | `browser_screenshot`, `browser_pdf`, `browser_upload`, `browser_download` | Configure artifact/download roots and permitted upload paths. / 配置产物目录、下载目录和上传权限。 |
+| State / 状态 | `cookies_list`, `storage_get` | Inspect local site state; never publish cookies or secrets. / 查看站点状态，不公开 Cookie 或秘密。 |
+| Skills / 工作流 | `skills_list`, `skill_describe`, `skill_run`, `skill_status`, `skill_cancel`, `skill_runs_list` | Discover parameters before starting; poll returned run ID. / 先发现参数，启动后用真实 run ID 查询。 |
+| Discovery / 工具发现 | `sdk_info`, `tools/list`, `runtime_request_status` | Installed schemas are authoritative; Runtime IDs are not JSON-RPC IDs. / 以安装版 schema 为准，区分 Runtime ID 与 JSON-RPC ID。 |
+
+Every installed tool is available through generic `call` / `Call`; convenience methods differ by language. Use the recipes for exact argument examples and inspect `tools/list` for required fields. / 所有安装版工具都能经通用调用访问，便利方法并非每种语言完全相同；参数示例见手册，必填项以安装版 schema 为准。
+
+## 生命周期、错误与权限
+
+- Client close disconnects MCP; session close closes the browser. Detach keeps the browser available. / 客户端关闭、会话断开和浏览器关闭含义不同。
+- Default start requires an existing unique 默认环境; it does not create one. / 默认启动不会自动创建缺失环境。
+- Update only closed profiles; deletion requires explicit confirmation and removes persistent data. / 更新前关闭环境；删除需确认且会移除持久数据。
+- Side effects are not automatically retried after timeout or observation failure. / 超时和观察失败不自动重放输入。
+- Humanize needs valid entitlement; examples explicitly use false for basic form interaction. / 拟人化需要有效权益，演示显式关闭。
+- PAGE_NOT_VISIBLE requires restoring the window and selecting the intended tab. / 页面不可见时恢复窗口并激活标签。
+- Call sequences use one selected tab; serialize multi-step workflows. / 多步操作串行，不是 Playwright 多 Page 模型。
+
+## 测试范围与许可
+
+[SAMPLES.md](../SAMPLES.md) records earlier fixture tests. New examples, documentation and renames have not been built, checked or tested in this task. / 旧模拟测试不代表新增示例已实机验证；本轮未运行构建、检查或测试。
+
+MIT: retain copyright/license and applicable third-party notices. / 允许传播、修改与商用，保留版权、许可及适用的第三方声明。

kingai_browser-0.3.0/THIRD_PARTY_NOTICES.txt

@@ -0,0 +1,33 @@
+Third-party and retained notices
+
+The following Chromium BSD notice was included in the previous SDK distribution.
+It is retained for any material to which it applies; it does not replace the MIT license for KingAI SDK code.
+
+// Copyright 2015 The Chromium Authors
+// Copyright 2026 KingAI Browser contributors
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are
+// met:
+//
+//    * Redistributions of source code must retain the above copyright
+// notice, this list of conditions and the following disclaimer.
+//    * 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.
+//    * Neither the name of Google LLC 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
+// OWNER 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.