browscreen 0.2.1__tar.gz

browscreen-0.2.1/.gitignore

@@ -0,0 +1,37 @@
+# Python 环境与缓存
+.venv/
+.uv-cache/
+__pycache__/
+.pytest_cache/
+*.py[cod]
+
+# 构建产物
+build/
+dist/
+*.egg-info/
+
+# 本机编辑器与系统文件
+.idea/
+.DS_Store
+
+# 本机凭据与运行日志
+.env
+.env.*
+!.env.example
+*.log
+*.har
+
+# 工作目录中的运行时交换文件
+.cdp
+.mouse
+
+# 审核、验收记录与证据仅保留在本地
+/doc/design/代码审核报告*.md
+/doc/design/阶段核验清单.md
+/doc/design/review-evidence/
+/doc/project/*验收记录*.md
+/doc/project/审核问题修复记录*.md
+/doc/project/发布前检查记录*.md
+/doc/project/acceptance-evidence/
+/doc/project/review-fix-evidence/
+local/

browscreen-0.2.1/.python-version

@@ -0,0 +1 @@
+3.14

browscreen-0.2.1/AGENTS.md

@@ -0,0 +1,9 @@
+# 版本维护约定
+
+- 在合适的版本提交中同步调整 `pyproject.toml` 的项目版本、`uv.lock` 中 browscreen 的版本和根目录 `changelog.md`，并更新受影响的使用示例。普通过程提交无需逐次升版。
+- `pyproject.toml` 是项目版本的唯一来源；CLI 和 OpenAPI 从已安装包元数据读取，不另行硬编码版本。
+- 兼容的新功能增加次版本号，修复增加补丁版本号；不兼容的行为变更在实施前说明影响并确认版本安排。
+- `changelog.md` 使用简体中文，按版本倒序记录新增、变更和修复；版本日期来自实际环境，补录历史时注明对应基线并使用可核实的 Git 日期。
+- 验证通过并提交版本改动后，为包含该版本号与变更记录的提交添加附注标签 `vX.Y.Z`；标签名必须与提交中的项目版本一致。已有标签不得静默移动或覆盖。
+- 补录历史版本时，核对基线提交中的项目版本和实际改动，在当前变更记录中注明对应基线；不为补录而改写旧提交。
+- 提交和标签默认只在本地创建；获得明确的远程推送授权后才推送，不擅自改写历史。

browscreen-0.2.1/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# 贡献指南
+
+感谢对 browscreen 的改进建议。项目介绍与安装步骤见 [README](README.md)，完整资料见[文档导航](doc/README.md)。
+
+## 报告问题
+
+通过 [GitHub Issues](https://github.com/Pegasus-Yang/Browscreen/issues) 提交问题或功能建议。缺陷报告请提供：
+
+- `browscreen version` 输出，以及 Python、操作系统和 Chrome 版本。
+- 最小复现步骤、启动参数、预期行为和实际结果。
+- 必要的 `-v` 日志片段；提交前移除凭据、私有地址、本机路径和业务画面。
+
+涉及敏感信息的问题可联系维护者 `panesas2@gmail.com`，不要在公开 Issue 中附上敏感值。
+
+## 开发与验证
+
+使用 Python 3.14、`uv` 和项目根目录的 `.venv/`。完整测试还需要 Node.js 22 或更高版本，无需 npm 依赖。
+
+```sh
+uv sync --locked --group dev \
+  -i http://mirrors.aliyun.com/pypi/simple/ \
+  --trusted-host mirrors.aliyun.com
+.venv/bin/python -m pytest -q -W error
+```
+
+代码位于 `src/browscreen/`，使用完整包导入路径。代码注释和文档字符串使用简体中文，文档字符串采用 reStructuredText 格式；保持现有中英文使用文档同步。
+
+## 提交改动
+
+每个 Pull Request 围绕一个明确的问题，只修改必要文件。说明问题、最终行为及验证结果；修复缺陷时补充能够复现问题的回归测试。功能、参数或使用方式变化时，同步更新对应文档。
+
+默认测试不启动真实 Chrome；报告验证结果时区分自动回归与真实浏览器核验。本机调试、日志、审核和验收证据只在本地保留。
+
+## 版本与变更记录
+
+在合适的版本提交中同步修改 `pyproject.toml`、`uv.lock` 中 browscreen 的版本和根目录 [changelog.md](changelog.md)，更新受影响的版本示例。普通过程提交无需逐次升版；兼容的新功能增加次版本号，修复增加补丁版本号，不兼容变更先说明影响并确认安排。
+
+验证完成并提交后，为该版本提交创建附注标签 `vX.Y.Z`。标签名应与该提交中的项目版本一致，不移动或覆盖已有标签。提交和标签默认仅在本地创建，推送远程需要明确授权。自动化维护约定见 [AGENTS.md](AGENTS.md)。
+
+项目采用 [MIT 许可证](LICENSE)。

browscreen-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pegasus-Yang
+
+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.

browscreen-0.2.1/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.5
+Name: browscreen
+Version: 0.2.1
+Summary: 浏览器视口截图与鼠标指针预览服务
+Project-URL: Homepage, https://github.com/Pegasus-Yang/Browscreen
+Project-URL: Documentation, https://github.com/Pegasus-Yang/Browscreen/blob/main/doc/README.md
+Project-URL: Repository, https://github.com/Pegasus-Yang/Browscreen
+Project-URL: Issues, https://github.com/Pegasus-Yang/Browscreen/issues
+Author-email: Pegasus-Yang <panesas2@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.14
+Requires-Dist: fastapi<1,>=0.118
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: pillow<13,>=12
+Requires-Dist: pydantic<3,>=2.12
+Requires-Dist: uvicorn<1,>=0.37
+Requires-Dist: websockets<18,>=15
+Description-Content-Type: text/markdown
+
+# browscreen
+
+[![Python](https://img.shields.io/badge/Python-3.14%2B-blue.svg)](pyproject.toml)
+[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+简体中文 | [English](README.en.md)
+
+浏览器画面与鼠标指针预览服务。browscreen（browser＋screen）通过 Chrome DevTools Protocol（CDP）连接已有 Chrome，将当前视口截图和外部提供的指针坐标合成 PNG，用于网页预览、图片接口和 webhook 推送。
+
+## 功能
+
+- 默认每 300 毫秒采集当前视口，网页、图片接口和 webhook 共用最新帧。
+- 读取工作目录的 `.cdp` 连接浏览器，读取 `.mouse` 在 CSS 视口坐标上合成指针。
+- 浏览器失效后清空旧图，在限定时间内重读端点并恢复采集。
+- 正常退出时清空已有 `.mouse`，保留 `.cdp` 和外部浏览器。
+
+服务采用 Python 3.14、FastAPI 和 Pydantic v2，一个进程运行一个采集循环。浏览器启动、页面导航和环境隔离由调用方管理；预览页只读，不转发鼠标或键盘操作。
+
+## 安装
+
+准备 `uv` 和 Python 3.14，从 GitHub 获取源码后安装：
+
+```sh
+git clone https://github.com/Pegasus-Yang/Browscreen.git
+cd Browscreen
+uv sync --locked --no-dev \
+  -i http://mirrors.aliyun.com/pypi/simple/ \
+  --trusted-host mirrors.aliyun.com
+.venv/bin/browscreen version
+```
+
+需要安装 Python 时先执行 `uv python install 3.14`。当前安装方式为源码或自行构建的 wheel；详见[安装与运行](doc/deployment/安装与运行.md)。
+
+## 快速开始
+
+准备一个已有工作目录，以及启用了远程调试、包含打开页面的 Chrome。将实际调试地址写入 `.cdp`：
+
+```sh
+work_dir="/absolute/path/to/workspace"
+printf '%s\n' 'http://127.0.0.1:9222' > "$work_dir/.cdp"
+uv run --no-sync browscreen --work-dir "$work_dir"
+```
+
+打开 `http://127.0.0.1:8000/` 查看画面。另一个终端向同一目录的 `.mouse` 写入 `320,180`，即可在下一个新帧显示指针。工作目录和 Chrome 由外部系统准备，示例路径和端口需按实际环境替换。
+
+`.cdp` 尚未可用时 HTTP 保持可访问，默认等待 60 秒，等待预算持续到首个有效 PNG 生成。超时后修正端点并重启服务。
+
+## 命令行
+
+安装后提供一个 `browscreen` 命令。在源码安装环境中，可通过 `.venv/bin/browscreen` 或 `uv run --no-sync browscreen` 调用。
+
+| 命令 | 用途 |
+| --- | --- |
+| `browscreen --help` | 查看全部命令与参数 |
+| `browscreen version` / `browscreen --version` | 查询安装版本并退出，无需工作目录 |
+| `browscreen --work-dir <目录>` | 启动服务，默认 INFO 日志 |
+| `browscreen -v --work-dir <目录>` | 启动服务并开启 DEBUG 和 HTTP 访问日志 |
+
+默认省略网页轮询、HTTPX 请求和重复重试细节；状态变化、超时及异常仍会记录。同一 webhook 连续失败仅首次告警，恢复后记录一次；每帧仍按原规则发送。完整参数与日志说明见[命令行参考](doc/reference/命令行.md)。
+
+## HTTP 接口
+
+| 接口 | 用途 |
+| --- | --- |
+| `GET /` | 只读网页预览 |
+| `GET /api/screenshot` | 最新合成 PNG，附带帧编号、UTC 采集开始时间和 `no-store` |
+| `POST /api/webhooks` | 注册 HTTP(S) 接收地址，向后续新帧发送 PNG |
+
+截图与发送顺序执行，每帧向所有接收地址并发尝试一次。慢 webhook 会降低采集频率，每次发送最多等待 3 秒；失败不自动重试、不跟随重定向。注册保留至进程退出。协议与错误码见[使用说明](doc/user-guide/使用说明.md)。
+
+## 文档
+
+- [安装与运行](doc/deployment/安装与运行.md)：环境、安装、启动、退出和构建。
+- [命令行参考](doc/reference/命令行.md)：命令、参数和日志级别。
+- [使用说明](doc/user-guide/使用说明.md)：文件协议、预览、图片和 webhook。
+- [文档导航](doc/README.md)：完整阅读路线和技术设计。
+- [版本变动历史](changelog.md)：各版本的新增、变更和修复。
+
+## 开发与贡献
+
+开发环境需要 Node.js 22 或更高版本，以运行预览脚本回归，无需 npm 依赖：
+
+```sh
+uv sync --locked --group dev \
+  -i http://mirrors.aliyun.com/pypi/simple/ \
+  --trusted-host mirrors.aliyun.com
+.venv/bin/python -m pytest -q -W error
+```
+
+默认测试使用模拟浏览器端点；真实 Chrome 验证需要另行执行。缺少 Node.js 时预览测试会跳过，不代表前端验证通过。
+
+问题和建议请提交到 [GitHub Issues](https://github.com/Pegasus-Yang/Browscreen/issues)。提交改动前请阅读[贡献指南](CONTRIBUTING.md)。项目由 [Pegasus-Yang](https://github.com/Pegasus-Yang) 维护。
+
+## 许可证
+
+项目采用 [MIT 许可证](LICENSE)。

browscreen-0.2.1/README.en.md

@@ -0,0 +1,98 @@
+# browscreen
+
+[![Python](https://img.shields.io/badge/Python-3.14%2B-blue.svg)](pyproject.toml)
+[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+[简体中文](README.md) | English
+
+A browser screenshot and mouse pointer preview service. browscreen (browser + screen) connects to an existing Chrome instance through the Chrome DevTools Protocol (CDP), combines viewport screenshots with externally supplied pointer coordinates, and shares each PNG through a web preview, screenshot API, and webhooks.
+
+## Features
+
+- Capture the current viewport every 300 ms by default, with one shared latest frame.
+- Read the browser endpoint from `.cdp` and overlay CSS viewport coordinates from `.mouse`.
+- Clear stale images and recover browser connections within a bounded waiting budget.
+- Clear an existing `.mouse` during graceful shutdown, preserving `.cdp` and the external browser.
+
+The service uses Python 3.14, FastAPI, and Pydantic v2, with one capture loop per process. The host application manages browser startup, navigation, and environment isolation. The read-only preview does not forward mouse or keyboard input.
+
+## Installation
+
+With `uv` and Python 3.14 available, clone and install the source:
+
+```sh
+git clone https://github.com/Pegasus-Yang/Browscreen.git
+cd Browscreen
+uv sync --locked --no-dev \
+  -i http://mirrors.aliyun.com/pypi/simple/ \
+  --trusted-host mirrors.aliyun.com
+.venv/bin/browscreen version
+```
+
+If needed, install Python first with `uv python install 3.14`. Install from source or a locally built wheel; see [installation and deployment](doc/deployment/安装与运行.en.md) for details.
+
+## Quick start
+
+Prepare an existing working directory and a Chrome instance with remote debugging enabled and an open page. Write its actual debugging address to `.cdp`:
+
+```sh
+work_dir="/absolute/path/to/workspace"
+printf '%s\n' 'http://127.0.0.1:9222' > "$work_dir/.cdp"
+uv run --no-sync browscreen --work-dir "$work_dir"
+```
+
+Open `http://127.0.0.1:8000/`. From another terminal, write `320,180` to the same directory's `.mouse` file to display the pointer in the next frame. Replace the example path and ports with those managed by your application.
+
+HTTP stays available while the browser is unavailable. The default 60-second startup budget includes connection and creation of the first valid PNG. After timeout, correct the endpoint and restart the service.
+
+## Command line
+
+Installation provides one `browscreen` command. For a source installation, use `.venv/bin/browscreen` or `uv run --no-sync browscreen`.
+
+| Command | Purpose |
+| --- | --- |
+| `browscreen --help` | Show all commands and options |
+| `browscreen version` / `browscreen --version` | Print the installed version and exit; no working directory required |
+| `browscreen --work-dir <directory>` | Start the service with INFO logging |
+| `browscreen -v --work-dir <directory>` | Start with DEBUG and HTTP access logs |
+
+Default logs omit preview polling, HTTPX requests, and repeated retry details. State changes, timeouts, and exceptions remain visible. A webhook's consecutive failures produce one warning followed by a recovery message; delivery is still attempted for every frame. See the [command-line reference](doc/reference/命令行.en.md) for all options and logging behavior.
+
+## HTTP interfaces
+
+| Endpoint | Purpose |
+| --- | --- |
+| `GET /` | Read-only web preview |
+| `GET /api/screenshot` | Latest composed PNG, with frame ID, UTC capture start time, and `no-store` |
+| `POST /api/webhooks` | Register an HTTP(S) receiver for subsequent frames |
+
+Each capture waits for concurrent delivery attempts to all registered receivers. Slow receivers reduce the capture rate. Each delivery has a three-second total timeout, with no automatic retries or redirect following. Registrations last until process exit. See the [user guide](doc/user-guide/使用说明.en.md) for protocols and error codes.
+
+## Documentation
+
+- [Installation and deployment](doc/deployment/安装与运行.en.md): prerequisites, installation, startup, shutdown, and building.
+- [Command-line reference](doc/reference/命令行.en.md): commands, options, and logging levels.
+- [User guide](doc/user-guide/使用说明.en.md): exchange files, preview, screenshots, and webhooks.
+- [Documentation index](doc/README.md): reading routes and Chinese technical design documents.
+- [Changelog](changelog.md): additions, changes, and fixes by version, in Simplified Chinese.
+
+The preview UI, CLI help, and runtime messages are currently in Simplified Chinese. Use the stable API error `code` values for programmatic handling.
+
+## Development and contributions
+
+The full suite requires Node.js 22 or later for the preview-script tests; no npm dependencies are needed:
+
+```sh
+uv sync --locked --group dev \
+  -i http://mirrors.aliyun.com/pypi/simple/ \
+  --trusted-host mirrors.aliyun.com
+.venv/bin/python -m pytest -q -W error
+```
+
+Standard tests use simulated browser endpoints. Real-Chrome verification is a separate procedure. Without Node.js, the preview test is explicitly skipped, so the result does not confirm frontend coverage.
+
+Report bugs and suggestions through [GitHub Issues](https://github.com/Pegasus-Yang/Browscreen/issues). Read the [contribution guide](CONTRIBUTING.md) before submitting changes. Maintained by [Pegasus-Yang](https://github.com/Pegasus-Yang).
+
+## License
+
+Licensed under the [MIT License](LICENSE).

browscreen-0.2.1/README.md

@@ -0,0 +1,96 @@
+# browscreen
+
+[![Python](https://img.shields.io/badge/Python-3.14%2B-blue.svg)](pyproject.toml)
+[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+简体中文 | [English](README.en.md)
+
+浏览器画面与鼠标指针预览服务。browscreen（browser＋screen）通过 Chrome DevTools Protocol（CDP）连接已有 Chrome，将当前视口截图和外部提供的指针坐标合成 PNG，用于网页预览、图片接口和 webhook 推送。
+
+## 功能
+
+- 默认每 300 毫秒采集当前视口，网页、图片接口和 webhook 共用最新帧。
+- 读取工作目录的 `.cdp` 连接浏览器，读取 `.mouse` 在 CSS 视口坐标上合成指针。
+- 浏览器失效后清空旧图，在限定时间内重读端点并恢复采集。
+- 正常退出时清空已有 `.mouse`，保留 `.cdp` 和外部浏览器。
+
+服务采用 Python 3.14、FastAPI 和 Pydantic v2，一个进程运行一个采集循环。浏览器启动、页面导航和环境隔离由调用方管理；预览页只读，不转发鼠标或键盘操作。
+
+## 安装
+
+准备 `uv` 和 Python 3.14，从 GitHub 获取源码后安装：
+
+```sh
+git clone https://github.com/Pegasus-Yang/Browscreen.git
+cd Browscreen
+uv sync --locked --no-dev \
+  -i http://mirrors.aliyun.com/pypi/simple/ \
+  --trusted-host mirrors.aliyun.com
+.venv/bin/browscreen version
+```
+
+需要安装 Python 时先执行 `uv python install 3.14`。当前安装方式为源码或自行构建的 wheel；详见[安装与运行](doc/deployment/安装与运行.md)。
+
+## 快速开始
+
+准备一个已有工作目录，以及启用了远程调试、包含打开页面的 Chrome。将实际调试地址写入 `.cdp`：
+
+```sh
+work_dir="/absolute/path/to/workspace"
+printf '%s\n' 'http://127.0.0.1:9222' > "$work_dir/.cdp"
+uv run --no-sync browscreen --work-dir "$work_dir"
+```
+
+打开 `http://127.0.0.1:8000/` 查看画面。另一个终端向同一目录的 `.mouse` 写入 `320,180`，即可在下一个新帧显示指针。工作目录和 Chrome 由外部系统准备，示例路径和端口需按实际环境替换。
+
+`.cdp` 尚未可用时 HTTP 保持可访问，默认等待 60 秒，等待预算持续到首个有效 PNG 生成。超时后修正端点并重启服务。
+
+## 命令行
+
+安装后提供一个 `browscreen` 命令。在源码安装环境中，可通过 `.venv/bin/browscreen` 或 `uv run --no-sync browscreen` 调用。
+
+| 命令 | 用途 |
+| --- | --- |
+| `browscreen --help` | 查看全部命令与参数 |
+| `browscreen version` / `browscreen --version` | 查询安装版本并退出，无需工作目录 |
+| `browscreen --work-dir <目录>` | 启动服务，默认 INFO 日志 |
+| `browscreen -v --work-dir <目录>` | 启动服务并开启 DEBUG 和 HTTP 访问日志 |
+
+默认省略网页轮询、HTTPX 请求和重复重试细节；状态变化、超时及异常仍会记录。同一 webhook 连续失败仅首次告警，恢复后记录一次；每帧仍按原规则发送。完整参数与日志说明见[命令行参考](doc/reference/命令行.md)。
+
+## HTTP 接口
+
+| 接口 | 用途 |
+| --- | --- |
+| `GET /` | 只读网页预览 |
+| `GET /api/screenshot` | 最新合成 PNG，附带帧编号、UTC 采集开始时间和 `no-store` |
+| `POST /api/webhooks` | 注册 HTTP(S) 接收地址，向后续新帧发送 PNG |
+
+截图与发送顺序执行，每帧向所有接收地址并发尝试一次。慢 webhook 会降低采集频率，每次发送最多等待 3 秒；失败不自动重试、不跟随重定向。注册保留至进程退出。协议与错误码见[使用说明](doc/user-guide/使用说明.md)。
+
+## 文档
+
+- [安装与运行](doc/deployment/安装与运行.md)：环境、安装、启动、退出和构建。
+- [命令行参考](doc/reference/命令行.md)：命令、参数和日志级别。
+- [使用说明](doc/user-guide/使用说明.md)：文件协议、预览、图片和 webhook。
+- [文档导航](doc/README.md)：完整阅读路线和技术设计。
+- [版本变动历史](changelog.md)：各版本的新增、变更和修复。
+
+## 开发与贡献
+
+开发环境需要 Node.js 22 或更高版本，以运行预览脚本回归，无需 npm 依赖：
+
+```sh
+uv sync --locked --group dev \
+  -i http://mirrors.aliyun.com/pypi/simple/ \
+  --trusted-host mirrors.aliyun.com
+.venv/bin/python -m pytest -q -W error
+```
+
+默认测试使用模拟浏览器端点；真实 Chrome 验证需要另行执行。缺少 Node.js 时预览测试会跳过，不代表前端验证通过。
+
+问题和建议请提交到 [GitHub Issues](https://github.com/Pegasus-Yang/Browscreen/issues)。提交改动前请阅读[贡献指南](CONTRIBUTING.md)。项目由 [Pegasus-Yang](https://github.com/Pegasus-Yang) 维护。
+
+## 许可证
+
+项目采用 [MIT 许可证](LICENSE)。

browscreen-0.2.1/changelog.md

@@ -0,0 +1,55 @@
+# 版本变动历史
+
+按版本倒序记录对使用者有影响的变动。版本号以 `pyproject.toml` 为准，对应 Git 附注标签使用 `vX.Y.Z`。
+
+## 未发布
+
+尚无未归档变更。
+
+## 0.2.1 — 2026-10-04
+
+### 修复
+
+- 修正 DEBUG 日志回归测试的计数断言，区分模拟连接失败与等待截止时的端点读取超时，避免正常超时日志导致偶发测试失败。
+- 服务运行行为和依赖版本保持不变。
+
+## 0.2.0 — 2026-10-04
+
+### 新增
+
+- `browscreen version` 和 `browscreen --version`：查询安装版本并退出，无需工作目录。
+- `-v` / `--verbose`：开启 DEBUG 诊断日志与 HTTP 访问日志。
+
+### 变更
+
+- CLI 和 OpenAPI 共用安装包元数据中的版本号。
+- 默认 INFO 日志省略网页轮询、HTTPX 请求和重复连接／截图重试细节，保留状态变化、超时和异常。
+- 同一 webhook 连续失败只在首次告警，恢复后记录一次；每帧的发送尝试保持不变。
+
+### 文档与项目维护
+
+- 整理中英文 README、文档导航、安装与使用说明，增加命令行参考和贡献指南。
+- 增加 MIT 许可证及包元数据中的项目链接。
+- 替换公开文档中的本机路径，增加凭据、日志和 HAR 忽略规则；既有 Git 历史未改写。
+- 增加版本号、变更记录及附注标签的维护约定；本轮更新登记为 `0.2.0`。
+
+## 0.1.0 — 2026-10-03（历史基线）
+
+本版本根据已有提交补录，基线为 `32c9bff`，日期来自该提交；`v0.1.0` 为后续补加的标签。
+
+### 新增
+
+- 基于 Chrome CDP 的视口截图、`.cdp` 端点和 `.mouse` 指针坐标协议。
+- 共用最新 PNG 的只读网页预览、截图接口和 webhook 注册与逐帧推送。
+- 有限连接等待、浏览器失效恢复、SIGINT／SIGTERM 优雅退出及 `.mouse` 清空。
+- Python、HTTP、模拟 CDP 和 Node.js 预览脚本回归测试，中英文安装与使用文档。
+
+### 修复
+
+- 首个有效帧之前的连接、截图与合成共用恢复预算，连续失败按间隔重试。
+- 非法端点归一化为适配器错误，后台异常清除旧帧并报告 `capture_failed`。
+- 预览页支持历史缓存恢复、超时取消、Blob URL 清理和重复帧跳过加载。
+
+### 项目维护
+
+- 本机审核、验收记录及证据取消 Git 跟踪并保留在本地；旧历史中的内容仍可追溯。

browscreen-0.2.1/doc/README.md

@@ -0,0 +1,18 @@
+# browscreen 文档导航
+
+English documentation: [Project overview](../README.en.md) · [Installation and deployment](deployment/安装与运行.en.md) · [Command-line reference](reference/命令行.en.md) · [User guide](user-guide/使用说明.en.md)
+
+总览和快速开始见[项目入口](../README.md)。审核、阶段核验、验收记录及其证据仅保留在本地，不纳入 Git 版本管理。
+
+| 分类 | 文档 | 阅读用途 |
+| --- | --- | --- |
+| 安装运行 | [安装与运行](deployment/安装与运行.md) / [English](deployment/安装与运行.en.md) | Python 3.14、uv、启动与构建 |
+| 使用指南 | [使用说明](user-guide/使用说明.md) / [English](user-guide/使用说明.en.md) | 文件、预览、图片接口与 webhook |
+| 命令参考 | [命令行](reference/命令行.md) / [English](reference/命令行.en.md) | 已安装命令、启动参数、版本查询和日志级别 |
+| 技术设计 | [设计方案](design/设计方案.md) | 适配器、状态、坐标和接口契约 |
+| 实施计划 | [具体实施方案](design/具体实施方案.md) | 七阶段实施和本机验收步骤 |
+| 版本历史 | [changelog.md](../changelog.md) | 各版本的新增、变更和修复 |
+
+使用服务先阅读安装、命令行与使用说明；维护代码时阅读设计和实施文档。历史设计与实施过程保留在 `design/`，当前命令和日志行为以命令参考为准。
+
+问题与改进建议见[贡献指南](../CONTRIBUTING.md)，许可条款见 [LICENSE](../LICENSE)。

browscreen-0.2.1/doc/deployment//345/256/211/350/243/205/344/270/216/350/277/220/350/241/214.en.md

@@ -0,0 +1,120 @@
+# Installation and deployment
+
+[简体中文](安装与运行.md) | [English project overview](../../README.en.md) | [User guide](../user-guide/使用说明.en.md)
+
+browscreen connects to a browser supplied by your host application. The host application provides the working directory and CDP endpoint, starts and navigates Chrome, and manages its eventual shutdown. Run one browscreen process with one Uvicorn worker for each instance.
+
+## Prerequisites
+
+- Python 3.14 and `uv` for the project's `.venv/` environment and locked dependencies.
+- An existing Chrome instance with a reachable CDP endpoint and an open page.
+- An existing working directory. browscreen must be able to read `.cdp` and `.mouse`, and truncate an existing `.mouse` during graceful shutdown.
+- Node.js 22 or later for the full development test suite. Node.js is not needed to run browscreen itself.
+
+The commands below are shell examples to run from the repository root. Replace example paths and ports with those managed by your application.
+
+## Install from source
+
+If Python 3.14 is not available, install it with:
+
+```sh
+uv python install 3.14
+```
+
+Create the environment and install the locked runtime dependencies:
+
+```sh
+uv venv --python 3.14 .venv
+uv sync --locked --no-dev \
+  -i http://mirrors.aliyun.com/pypi/simple/ \
+  --trusted-host mirrors.aliyun.com
+.venv/bin/python -V
+.venv/bin/browscreen --help
+.venv/bin/browscreen version
+```
+
+The package uses the `src/browscreen/` layout. Installation makes imports work from the repository root; no `PYTHONPATH` or editor source-root configuration is required. The commands use the project's designated Aliyun package mirror.
+
+If a restricted environment cannot write to the default uv cache, set `UV_CACHE_DIR` to a writable directory when running uv. For example, on macOS:
+
+```sh
+UV_CACHE_DIR=/private/tmp/browscreen-uv-cache uv sync --locked --no-dev \
+  -i http://mirrors.aliyun.com/pypi/simple/ \
+  --trusted-host mirrors.aliyun.com
+```
+
+## Prepare and start an instance
+
+Your host application must first prepare the working directory and browser. A Chrome HTTP debugging root such as `http://127.0.0.1:9222` can be written as the single line in `.cdp`:
+
+```sh
+work_dir="/absolute/path/to/workspace"
+printf '%s\n' 'http://127.0.0.1:9222' > "$work_dir/.cdp"
+uv run --no-sync browscreen \
+  --work-dir "$work_dir" \
+  --adapter chrome-cdp \
+  --interval-ms 300 \
+  --connect-wait-timeout-s 60 \
+  --host 127.0.0.1 \
+  --port 8000
+```
+
+Open `http://127.0.0.1:8000/`. The service provides HTTP immediately, even if `.cdp` is initially missing or the browser is not ready. Endpoint formats and target selection are described in the [user guide](../user-guide/使用说明.en.md#browser-endpoint-cdp).
+
+Installation provides one `browscreen` entry point. See the [command-line reference](../reference/命令行.en.md) for help, version queries, and all startup options. Default INFO logs retain state changes, timeouts, and errors while omitting repeated retries and individual requests. Add `-v` or `--verbose` after `browscreen` to enable DEBUG diagnostics and HTTP access logs.
+
+Separate instances need separately managed browser endpoints, working directories, and HTTP ports. browscreen does not create or isolate Chrome instances.
+
+## Recovery and shutdown
+
+A startup or recovery budget includes endpoint waiting, connection, and creation of the first valid PNG. Successful connection attempts followed by repeated screenshot failures do not reset it. After producing a valid frame, a later browser failure starts a new recovery cycle. Failed attempts respect `--interval-ms`.
+
+During recovery, the latest image is cleared and `.cdp` is reread. You can correct the address while the budget remains. A healthy connection does not switch targets merely because the file changes. When the budget expires, capture and endpoint polling stop while HTTP stays available; correct the problem and restart browscreen.
+
+An unexpected capture-task exception clears the image and returns `503` with `code: "capture_failed"`. Inspect the logged traceback, address the cause, and restart the service.
+
+For normal shutdown, stop external pointer-file updates, send SIGINT or SIGTERM to the browscreen process, and wait for it to exit. The service cancels capture, releases its connections, and truncates an existing `.mouse` to zero bytes. It leaves `.cdp` and the external browser intact. A missing `.mouse` is not created. Forced termination cannot guarantee this cleanup.
+
+## Troubleshooting
+
+| Symptom | Check or action |
+| --- | --- |
+| Startup rejects the working directory | Create it before startup and pass a directory, not a file |
+| `waiting_for_browser` | Check the `.cdp` file, endpoint reachability, and presence of an existing page; correct the file within the waiting budget |
+| `screenshot_not_ready` | The browser is connected but no valid frame has been published yet; inspect logs if this persists |
+| `browser_wait_timeout` | Correct the endpoint or browser state, then restart browscreen |
+| `capture_failed` | Inspect the service traceback and restart after addressing the cause |
+| Pointer does not appear | Check the `.mouse` format and that the coordinates are inside the CSS viewport |
+| Capture is slower than the configured interval | Check capture/composition duration and webhook response times; the next capture waits for all delivery attempts |
+| Chrome exits during separate real-browser verification | Check Chrome's crash report and launch environment; use an isolated temporary browser profile |
+
+The preview UI and runtime messages are currently in Chinese. Use the error `code` field for programmatic handling; English explanations are in the [user guide](../user-guide/使用说明.en.md#screenshot-api).
+
+## Tests and build
+
+```sh
+uv sync --locked --group dev \
+  -i http://mirrors.aliyun.com/pypi/simple/ \
+  --trusted-host mirrors.aliyun.com
+.venv/bin/python -m pytest -q -W error
+uv build \
+  -i http://mirrors.aliyun.com/pypi/simple/ \
+  --trusted-host mirrors.aliyun.com
+```
+
+Building produces a source archive and a wheel. The wheel includes `preview.html`, `assets/cursor.png`, the CLI entry point, and the MIT license. Runtime logs, exchange files, and local review or acceptance evidence are excluded from distribution.
+
+The standard tests use local simulated browser endpoints and a Node-based preview harness. They do not launch Chrome. If Node.js is unavailable, pytest reports a skipped frontend test; install Node.js to obtain full coverage of that suite. Real-Chrome verification is a separate procedure; the [implementation plan](../design/具体实施方案.md#四本机最终验收操作) contains Chinese instructions for isolated browser checks.
+
+To install a built wheel in a deployment directory, create its `.venv/` and provide the actual wheel path:
+
+```sh
+uv venv --python 3.14 .venv
+wheel_file="/absolute/path/to/browscreen-0.2.1-py3-none-any.whl"
+uv pip install --python .venv/bin/python "$wheel_file" \
+  -i http://mirrors.aliyun.com/pypi/simple/ \
+  --trusted-host mirrors.aliyun.com
+.venv/bin/browscreen version
+```
+
+Return to the [English project overview](../../README.en.md), or continue with the [user guide](../user-guide/使用说明.en.md).