nonebot-plugin-htmlrender 0.7.1__tar.gz → 0.7.2__tar.gz

{nonebot_plugin_htmlrender-0.7.1 → nonebot_plugin_htmlrender-0.7.2}/.github/workflows/docs.yml

@@ -18,11 +18,11 @@ on:
         type: boolean
 
 permissions:
-  contents: write
+  contents: read
 
 jobs:
-  deploy:
-    name: Build & Deploy Docs
+  build:
+    name: Build Docs
     runs-on: ubuntu-latest
     timeout-minutes: 20
     env:
@@ -68,38 +68,3 @@ jobs:
           path: ${{ env.DOCS_LOG }}
           if-no-files-found: warn
           retention-days: 14
-
-      - name: Configure git
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-
-      - name: Configure authenticated origin
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          git remote set-url origin "https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
-
-      - name: Get project version
-        id: version
-        run: |
-          VERSION=$(uv version --short)
-          echo "version=${VERSION}" >> "${GITHUB_OUTPUT}"
-
-      - name: Deploy versioned docs
-        env:
-          VERSION: ${{ steps.version.outputs.version }}
-        run: |
-          uv run mike deploy --push --update-aliases "${VERSION}" latest
-
-      - name: Set default version
-        run: |
-          uv run mike set-default --push latest
-
-      - name: Show docs url
-        env:
-          DOCS_OWNER: ${{ github.repository_owner }}
-          DOCS_REPO: ${{ github.event.repository.name }}
-          VERSION: ${{ steps.version.outputs.version }}
-        run: |
-          echo "Docs deployed: https://${DOCS_OWNER}.github.io/${DOCS_REPO}/${VERSION}/"

nonebot_plugin_htmlrender-0.7.2/.github/workflows/publish.yml

@@ -0,0 +1,231 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "*"
+  workflow_dispatch:
+    inputs:
+      debug_enabled:
+        description: Enable extra debug diagnostics
+        required: false
+        default: false
+        type: boolean
+      release_tag:
+        description: Tag to publish as GitHub Release when manually triggered (e.g. v0.7.0)
+        required: false
+        default: ""
+        type: string
+
+jobs:
+  pypi-publish:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    outputs:
+      release_tag: ${{ steps.release_tag.outputs.tag }}
+    environment: release
+    permissions:
+      # IMPORTANT: this permission is mandatory for trusted publishing
+      id-token: write
+      contents: write
+    env:
+      BUILD_LOG: publish-build.log
+    steps:
+      - name: Resolve Release Tag
+        id: release_tag
+        shell: bash
+        env:
+          RELEASE_TAG_INPUT: ${{ github.event.inputs.release_tag }}
+        run: |
+          if [[ "${GITHUB_REF_TYPE}" == "tag" ]]; then
+            TAG="${GITHUB_REF_NAME}"
+          elif [[ -n "${RELEASE_TAG_INPUT}" ]]; then
+            TAG="${RELEASE_TAG_INPUT}"
+          else
+            echo "::error::No release tag found. Use a tag push or provide workflow_dispatch input 'release_tag'."
+            exit 1
+          fi
+          echo "tag=${TAG}" >> "${GITHUB_OUTPUT}"
+          echo "Resolved release tag: ${TAG}"
+
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+        with:
+          ref: refs/tags/${{ steps.release_tag.outputs.tag }}
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Verify tagged commit is on master
+        shell: bash
+        env:
+          RELEASE_TAG: ${{ steps.release_tag.outputs.tag }}
+        run: |
+          git fetch --no-tags origin master:refs/remotes/origin/master
+          TAG_COMMIT=$(git rev-list -n 1 "${RELEASE_TAG}")
+          if [[ "$(git rev-parse HEAD)" != "${TAG_COMMIT}" ]]; then
+            echo "::error::Checkout does not match ${RELEASE_TAG}. Refusing to publish."
+            exit 1
+          fi
+          if ! git merge-base --is-ancestor "${TAG_COMMIT}" origin/master; then
+            echo "::error::Tagged commit ${TAG_COMMIT} is not an ancestor of master. Refusing to publish."
+            exit 1
+          fi
+          echo "Tagged commit ${TAG_COMMIT} is on master."
+
+      - name: Install the latest version of uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78
+        with:
+          enable-cache: false
+
+      - name: Set up Python
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405
+        with:
+          python-version-file: ".python-version"
+
+      - name: Show Runner Context
+        run: |
+          echo "Runner: $RUNNER_NAME ($RUNNER_OS/$RUNNER_ARCH)"
+          python --version
+          uv --version
+
+      - name: Verify tag matches package version
+        shell: bash
+        env:
+          RELEASE_TAG: ${{ steps.release_tag.outputs.tag }}
+        run: |
+          VERSION=$(uv version --short)
+          EXPECTED_TAG="v${VERSION}"
+          if [[ "${RELEASE_TAG}" != "${EXPECTED_TAG}" ]]; then
+            echo "::error::Release tag ${RELEASE_TAG} does not match package version ${VERSION}. Expected ${EXPECTED_TAG}."
+            exit 1
+          fi
+          echo "Release tag ${RELEASE_TAG} matches package version ${VERSION}."
+
+      - name: Sync deps
+        run: uv sync
+        shell: bash
+
+      - name: Debug Dependency Snapshot
+        if: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.debug_enabled == 'true' }}
+        run: |
+          uv pip list
+          uv tree
+
+      - name: Build Package
+        run: |
+          set -o pipefail
+          uv build 2>&1 | tee "${BUILD_LOG}"
+
+      - name: Show built distributions
+        run: |
+          ls -la dist
+          sha256sum dist/* || true
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
+        with:
+          name: artifact
+          path: dist/
+
+      - name: Upload build logs
+        if: ${{ always() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
+        with:
+          name: publish-build-logs
+          path: ${{ env.BUILD_LOG }}
+          if-no-files-found: warn
+          retention-days: 14
+
+      - name: pypi-publish
+        uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e
+
+      - name: Publish GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          RELEASE_TAG: ${{ steps.release_tag.outputs.tag }}
+        run: |
+          gh release create "${RELEASE_TAG}" \
+            dist/*.whl \
+            dist/*.tar.gz \
+            --title "${RELEASE_TAG}" \
+            --generate-notes
+
+  docs-deploy:
+    name: Deploy versioned docs
+    needs: pypi-publish
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    permissions:
+      contents: write
+    env:
+      DOCS_LOG: docs-build.log
+      RELEASE_TAG: ${{ needs.pypi-publish.outputs.release_tag }}
+    steps:
+      - name: Checkout release tag
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+        with:
+          ref: refs/tags/${{ needs.pypi-publish.outputs.release_tag }}
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78
+        with:
+          python-version: "3.12"
+          enable-cache: false
+
+      - name: Sync docs deps
+        run: uv sync --locked --group docs
+
+      - name: Verify docs version
+        id: version
+        shell: bash
+        run: |
+          VERSION=$(uv version --short)
+          EXPECTED_TAG="v${VERSION}"
+          if [[ "${RELEASE_TAG}" != "${EXPECTED_TAG}" ]]; then
+            echo "::error::Release tag ${RELEASE_TAG} does not match docs version ${VERSION}."
+            exit 1
+          fi
+          echo "version=${VERSION}" >> "${GITHUB_OUTPUT}"
+
+      - name: Build docs
+        run: |
+          set -o pipefail
+          uv run zensical build --strict 2>&1 | tee "${DOCS_LOG}"
+
+      - name: Upload docs build logs
+        if: ${{ always() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a
+        with:
+          name: release-docs-build-logs
+          path: ${{ env.DOCS_LOG }}
+          if-no-files-found: warn
+          retention-days: 14
+
+      - name: Configure git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Configure authenticated origin
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          git remote set-url origin "https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git"
+
+      - name: Deploy versioned docs
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          uv run mike deploy --push --update-aliases "${VERSION}" latest
+          uv run mike set-default --push latest
+
+      - name: Show docs URL
+        env:
+          DOCS_OWNER: ${{ github.repository_owner }}
+          DOCS_REPO: ${{ github.event.repository.name }}
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          echo "Docs deployed: https://${DOCS_OWNER}.github.io/${DOCS_REPO}/${VERSION}/"

{nonebot_plugin_htmlrender-0.7.1 → nonebot_plugin_htmlrender-0.7.2}/CONTRIBUTING.md

@@ -46,14 +46,11 @@ If docs were changed:
 make docs-build
 ```
 
-## PR Previews
+## PR Documentation Preview
 
-When opening a PR from a branch in this repository (not a fork), the following previews are produced automatically:
+When opening a PR from a branch in this repository (not a fork), documentation changes under `docs/**`, `mkdocs.yml`, or `README.md` are deployed automatically. A sticky comment shows the preview URL under `pr-preview/pr-<NUMBER>/` of the Pages site. The preview is removed automatically when the PR is closed.
 
-- **TestPyPI build**: each push to the PR is published to TestPyPI under a dev-suffixed version. A sticky comment on the PR shows the install command.
-- **Docs preview** (only when `docs/**`, `mkdocs.yml`, or `README.md` change): a sticky comment on the PR shows the preview URL under `pr-preview/pr-<NUMBER>/` of the Pages site. The preview is removed automatically when the PR is closed.
-
-PRs from forks skip both because the workflow tokens cannot write to gh-pages or use TestPyPI trusted publishing.
+PRs from forks skip the deployment because the workflow token cannot write to `gh-pages`. TestPyPI publishing is currently suspended for all PRs.
 
 ## Commit Message Format
 

{nonebot_plugin_htmlrender-0.7.1 → nonebot_plugin_htmlrender-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nonebot-plugin-htmlrender
-Version: 0.7.1
+Version: 0.7.2
 Summary: 通过浏览器渲染图片
 Project-URL: Homepage, https://github.com/kexue-z/nonebot-plugin-htmlrender
 Project-URL: Bug Tracker, https://github.com/kexue-z/nonebot-plugin-htmlrender/issues

{nonebot_plugin_htmlrender-0.7.1 → nonebot_plugin_htmlrender-0.7.2}/docs/maintainers/quality/ci-actions.md

@@ -18,11 +18,11 @@ tags:
 | ------------------ | --------------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------- |
 | CI                 | `.github/workflows/ci.yml`              | lint、类型检查、打包校验、远程浏览器 smoke                               | push master、pull request、手动触发      |
 | Coverage           | `.github/workflows/coverage.yml`        | Python 版本 + CPU 架构覆盖率矩阵                                         | push master、pull request、手动触发      |
-| Docs               | `.github/workflows/docs.yml`            | master 推送时构建文档并执行版本化部署                                    | push master（文档路径）、手动触发        |
+| Docs               | `.github/workflows/docs.yml`            | master 推送时严格构建文档                                                 | push master（文档路径）、手动触发        |
 | Docs PR Preview    | `.github/workflows/docs-pr-preview.yml` | PR 文档预览部署与关闭清理                                                | pull request open/sync/close（文档路径） |
-| Publish (TestPyPI) | `.github/workflows/publish-test.yml`    | PR 注入 dev 版本号发到 TestPyPI 并在 PR 评论安装命令                     | pull request、手动触发                   |
+| Publish (TestPyPI) | `.github/workflows-disabled/publish-test.yml` | 保留 TestPyPI 发布实现，当前挂起                                     | 无                                       |
 | Auto Tag           | `.github/workflows/auto-tag.yml`        | PR 合并到 master 后读取 `pyproject.toml` 版本号自动打 tag 并触发 Publish | pull request closed on master            |
-| Publish            | `.github/workflows/publish.yml`         | 构建分发包、PyPI trusted publishing、GitHub Release                      | tag push、手动触发                       |
+| Publish            | `.github/workflows/publish.yml`         | 构建分发包、PyPI、GitHub Release，并在成功后部署版本化文档                | tag push、手动触发                       |
 
 ## CI
 
@@ -63,15 +63,13 @@ pytest-py<python-version>-<arch>.log
 - `README.md`
 - `.github/workflows/docs.yml`
 
-它会执行严格文档构建并通过 `mike` 部署到 `gh-pages`：
+它只执行严格文档构建：
 
 ```bash
 uv run zensical build --strict
-uv run mike deploy --push --update-aliases <version> latest
-uv run mike set-default --push latest
 ```
 
-版本号从 `pyproject.toml` 的 `project.version` 字段读取。多版本管理细节见 [文档版本管理](versioning.md)。
+版本化部署由 Publish workflow 在正式发布成功后执行，避免未发布版本提前成为 `latest`。多版本管理细节见 [文档版本管理](versioning.md)。
 
 非 master 分支或 PR 上的文档预览由 `Docs PR Preview` 负责，不再走分支名预览。
 
@@ -93,12 +91,9 @@ https://<owner>.github.io/<repo>/pr-preview/pr-<NUMBER>/
 
 ## Publish (TestPyPI)
 
-`Publish (TestPyPI)` workflow 在 PR 上为同仓库分支构建一份带唯一 dev 后缀的包，发布到 TestPyPI，便于评审者快速安装验证。
+TestPyPI 发布当前挂起。完整 workflow 保留在 `.github/workflows-disabled/publish-test.yml`，不位于 GitHub Actions 注册目录，因此没有 PR 或手动触发入口。
 
-- 触发：`pull_request` 的 `opened` / `synchronize` / `reopened` 与 `workflow_dispatch`；
-- fork PR 跳过：trusted publishing 需要 `id-token: write`，fork 不可用；
-- 版本注入：以 `pyproject.toml` 中的当前版本为 base，附加 UTC 时间戳后缀，例如 `0.7.0.dev20260509120000`，保证 TestPyPI 单调递增不撞包；
-- 发布完成后用 `marocchino/sticky-pull-request-comment` 在 PR 上贴一条固定评论，给出装包命令。
+保留实现仍会以 `pyproject.toml` 的当前版本为 base，附加 UTC 时间戳 dev 后缀，构建 wheel 与 sdist，并通过 trusted publishing 上传 TestPyPI。恢复时需将文件移回 `.github/workflows/`，再明确配置所需触发器；不能只修改文档或 environment。
 
 ```bash
 pip install -i https://test.pypi.org/simple/ \
@@ -106,7 +101,7 @@ pip install -i https://test.pypi.org/simple/ \
   nonebot-plugin-htmlrender==<dev-version>
 ```
 
-`environment: testpypi` 与 `https://test.pypi.org/legacy/` 仓库 URL 已在 workflow 中固化。需要在 TestPyPI 与 GitHub 仓库的 `testpypi` environment 上各自完成一次 trusted publisher 配置。
+`environment: testpypi` 与 `https://test.pypi.org/legacy/` 仓库 URL 仍保留在挂起的 workflow 中。
 
 ## Auto Tag
 
@@ -126,11 +121,13 @@ pip install -i https://test.pypi.org/simple/ \
 
 `Publish` workflow 负责正式发布产物：
 
-1. **校验 commit 在 master 历史上**：`git merge-base --is-ancestor` 校验，挡住误从其他分支推 tag 的发布；
+1. 解析并检出待发布 tag；
+1. 校验 tag 指向 `master` 历史、tag 名与包版本完全一致；
 1. 使用 `uv build` 构建 wheel 与 sdist；
 1. 上传构建产物和构建日志 artifact；
 1. 通过 PyPI trusted publishing 发布；
 1. 根据 tag 或 `release_tag` 输入创建 GitHub Release。
+1. GitHub Release 创建成功后严格构建 tag 对应文档，通过 `mike` 部署该版本并更新 `latest`。
 
 触发方式：
 
@@ -138,6 +135,8 @@ pip install -i https://test.pypi.org/simple/ \
 - 也可以维护者手动 push 一个 tag 到 master 上的 commit；
 - 也可以手动 `workflow_dispatch` 并提供 `release_tag` 输入。
 
+无论通过哪种方式触发，Publish 都从 tag 检出源码，不会用 dispatch 所在分支的工作树替代发布内容。Mike 部署是发布的后置 job；PyPI 或 GitHub Release 失败时不会运行。
+
 ## 本地对应命令
 
 | CI 项                  | 本地命令                                  |
@@ -169,5 +168,6 @@ pip install -i https://test.pypi.org/simple/ \
 - 对文档构建失败，下载 `docs-build-logs`；
 - 对打包失败，下载 `package-dist` 与 `package-build-logs`；
 - 对正式发布失败，下载 `publish-build-logs`；
-- 对 TestPyPI 发布失败，下载 `publish-test-build-logs` 与 `artifact-testpypi`；
+- 对正式发布后的文档部署失败，下载 `release-docs-build-logs`；
+- TestPyPI workflow 恢复后若发布失败，下载 `publish-test-build-logs` 与 `artifact-testpypi`；
 - 对 Auto Tag 失败（tag 推送或 publish dispatch 失败），查看 job 日志中的 `gh` 命令输出。

{nonebot_plugin_htmlrender-0.7.1 → nonebot_plugin_htmlrender-0.7.2}/docs/maintainers/quality/versioning.md

@@ -15,7 +15,8 @@ tags:
 
 ## 工作原理
 
-- 推送到 `master` 分支且涉及文档相关路径时，Docs workflow 自动读取 `pyproject.toml` 中的版本号，通过 `mike deploy` 发布到 `gh-pages` 分支
+- 推送到 `master` 分支且涉及文档相关路径时，Docs workflow 只执行严格构建，阻止无效文档进入主分支
+- Publish workflow 完成 PyPI 发布和 GitHub Release 后，才读取 tag 对应版本并通过 `mike deploy` 发布到 `gh-pages` 分支
 - 版本以子目录形式存在，例如 `docs.example.com/0.7.0/`、`docs.example.com/0.8.0/`
 - `latest` 别名始终指向最新版本，根路径自动重定向到 `latest`
 - 旧版本页面顶部会显示过期提醒横幅
@@ -26,9 +27,10 @@ PR 阶段的文档预览由独立的 `Docs PR Preview` workflow 部署到 `gh-pa
 
 发版时不需要手动打 tag。维护者只需在 PR 中改好 `pyproject.toml` 的 `project.version` 后合并到 `master`：
 
-1. 合并到 `master` 触发 `Docs` workflow，将新版本通过 `mike` 部署为版本化文档；
-2. 同时触发 `Auto Tag` workflow，读取版本号自动创建 `v<version>` tag；
-3. `Auto Tag` 通过 `gh workflow run` 调起 `Publish`，完成 PyPI 发布与 GitHub Release。
+1. 合并到 `master` 后，`Auto Tag` workflow 读取版本号并创建 `v<version>` tag；
+2. `Auto Tag` 通过 `gh workflow run` 调起 `Publish`；
+3. `Publish` 检出 tag，校验 tag、包版本和 `master` 祖先关系，再完成 PyPI 发布与 GitHub Release；
+4. 只有前述发布成功后，Publish 的文档 job 才通过 `mike` 部署版本化文档并更新 `latest`。
 
 完整 workflow 触发条件与排障入口见 [CI Actions](ci-actions.md)。
 
@@ -37,7 +39,7 @@ mike deploy --push --update-aliases <version> latest
 mike set-default --push latest
 ```
 
-版本号从 `pyproject.toml` 的 `project.version` 字段读取。
+版本号从 tag 对应提交的 `pyproject.toml` 中读取，且必须与 `v<version>` tag 完全一致。
 
 ## 本地操作
 

{nonebot_plugin_htmlrender-0.7.1 → nonebot_plugin_htmlrender-0.7.2}/docs/users/api.md

@@ -86,6 +86,13 @@ async def render_markdown(
 
 **返回值：** `bytes` — 图片二进制数据
 
+!!! warning "Markdown 中的原始 HTML 会进入页面"
+
+    `render_markdown` 会保留 Markdown 中的原始 HTML，并将转换结果作为 HTML
+    片段插入页面；它不是 HTML 消毒器。若内容来自不可信用户或模型输出，调用方
+    应先按业务需要做标签、属性和 URL 白名单清洗，或在不需要富文本时改用
+    `render_text`。详见[安全须知](security.md)。
+
 ---
 
 ### `render_html`

{nonebot_plugin_htmlrender-0.7.1 → nonebot_plugin_htmlrender-0.7.2}/docs/users/index.md

@@ -67,6 +67,7 @@ tags:
 
 === "迁移旧项目"
 
+    - [v0.7.2 迁移说明](migration-v072.md)：远程 Playwright 的 Markdown 渲染修复
     - [旧版本迁移指南](migration.md)：从旧 API、旧配置和历史行为迁移到新路径
 
 ## 新项目建议

nonebot_plugin_htmlrender-0.7.2/docs/users/migration-v072.md

@@ -0,0 +1,46 @@
+---
+title: v0.7.2 迁移说明
+description: 从 v0.7.1 升级到 v0.7.2 时需要了解的远程 Markdown 修复
+icon: lucide/bug-off
+tags:
+  - Users
+  - Migration
+  - Release
+---
+
+# v0.7.2 迁移说明
+
+v0.7.2 是面向远程 Playwright 部署的兼容性修复版本，不包含公共 API 或配置项变更。
+
+## 修复内容
+
+使用远程 Playwright 渲染 Markdown 时，默认模板此前会让远端浏览器导航到 Bot
+进程所在主机的 `file://` 地址。浏览器与 Bot 不共享文件系统时，该地址不可达，
+渲染会以 `ERR_FILE_NOT_FOUND` 失败。
+
+v0.7.2 在远程模式下直接通过 `page.set_content()` 注入默认 Markdown HTML，
+不再导航到本地模板文件。自定义的 HTTP(S) 基址和显式传入的渲染配置保持原有行为。
+
+## 是否需要修改配置
+
+通常不需要。符合以下条件的部署可直接升级：
+
+- 使用 Playwright WS 或 CDP 连接远端浏览器；
+- 调用 `render_markdown` 或兼容入口 `md_to_pic`；
+- 使用内置 Markdown 模板和样式。
+
+若 Markdown 引用了本地图片、字体或其他静态资源，仍需确保远端浏览器能够访问这些
+资源；本次修复只消除了默认模板文件本身的跨主机 `file://` 导航。
+
+## 升级后验证
+
+在实际远程浏览器环境执行一次最小渲染即可：
+
+```python
+from nonebot_plugin_htmlrender import render_markdown
+
+image = await render_markdown("# remote markdown")
+assert image
+```
+
+本地 Playwright、HTML 渲染和模板渲染行为不受影响。

{nonebot_plugin_htmlrender-0.7.1 → nonebot_plugin_htmlrender-0.7.2}/docs/users/migration.md

@@ -10,6 +10,10 @@ tags:
 
 # 旧版本迁移指南
 
+!!! info "v0.7.2 补丁版本"
+    从 v0.7.1 升级时，请先阅读 [v0.7.2 迁移说明](migration-v072.md)。
+    该版本仅修复远程 Playwright 的 Markdown 模板导航，不改变公共 API 或配置。
+
 新版本将渲染逻辑与底层驱动解耦，引入分层架构（Render / Backend / Runtime / Session / Context）。
 旧 API 仍保留为兼容层，但调用时会触发弃用警告，且不再承载新能力。
 新项目请直接使用新 API；存量项目按本页对照表逐步迁移即可。

{nonebot_plugin_htmlrender-0.7.1 → nonebot_plugin_htmlrender-0.7.2}/docs/users/security.md

@@ -19,6 +19,7 @@ tags:
 | 入口 | 威胁 | 默认行为 | 责任方 |
 | --- | --- | --- | --- |
 | `render_html(...)` | 攻击者构造 HTML/JS 在浏览器进程执行 | 直接装载到 Page | 调用方 |
+| `render_markdown(...)` | Markdown 携带原始 HTML、脚本或外链资源 | 转换后作为 HTML 片段装载到 Page，不做消毒 | 调用方 |
 | `render_template(..., templates=...)` | 模板变量未转义被插入 HTML | Jinja2 `select_autoescape()` 仅对 `.html/.xml` 自动转义 | 调用方 |
 | `capture_html_element(url, ...)` | 任意 URL 被远端浏览器请求 | 直接 `goto(url)` | 调用方 |
 | filehost `/filehost/*` | 浏览器/外部请求读取本地文件 | 路径白名单 + 请求头守卫 | 配置方 |
@@ -35,9 +36,22 @@ tags:
 - 模板内的外链可能拉取攻击者控制的资源；
 - 浏览器进程可对内网发起请求（参考下文 SSRF）。
 
+### Markdown 原始 HTML
+
+`render_markdown` 使用 Python-Markdown 生成 HTML。为了让段落、标题、引用块和
+KaTeX 等转换结果形成真实 DOM，生成的 HTML 片段不会再经过 Jinja2 转义。
+Python-Markdown 会保留输入中的原始 HTML，因此 `render_markdown` **不提供 HTML
+消毒或安全边界**：输入中的 `<script>`、事件处理属性和带外链的元素可能进入页面，
+脚本执行与网络访问风险和 `render_html` 相同。
+
+模型输出也应视为不可信内容。用户可以通过提示词诱导模型输出原始 HTML、脚本或
+指向内网的资源 URL；“内容由模型生成”不能替代输入校验。
+
 建议：
 
-- 业务输入直接走 `render_markdown`（CommonMark 解析过滤大部分原始 HTML）或 `render_template` 配合 Jinja2 变量；
+- 不需要富文本时使用 `render_text`，其文本插槽保持 HTML 转义；
+- 需要 Markdown 时，在调用 `render_markdown` 前按业务需求对原始 HTML 的标签、属性和 URL 做白名单清洗；
+- 不可信数据需要进入自定义布局时，使用 `render_template` 的模板变量，不要拼接模板或 HTML 字符串；
 - 不要拼字符串。`render_template` 默认 `select_autoescape()` 对 `.html/.xml` 后缀模板启用 HTML 转义，模板变量中的 `<` / `>` / `&` 会被转义；
 - 自定义模板后缀（如 `.j2`）时显式开 `autoescape=True`，否则等于零防护；
 - 需要原始 HTML 的字段，明确定义白名单标签集合后再交给模板，不要走 `|safe`。
@@ -53,7 +67,8 @@ env = jinja2.Environment(
 
 ## SSRF 与外部请求
 
-`render_html` / `render_template` / `capture_html_element` 触发的浏览器内网请求不受 NoneBot HTTP 客户端的限制。
+`render_html` / `render_markdown` / `render_template` / `capture_html_element`
+触发的浏览器内网请求不受 NoneBot HTTP 客户端的限制。
 攻击者可以让你的浏览器请求：
 
 - 内网管理界面（`http://10.0.0.1/admin`）；
@@ -172,6 +187,7 @@ await render_template_html(template=user_supplied_template_string)
 部署前快速复核：
 
 - [ ] 渲染入口已与不可信用户输入解耦（用模板变量而非字符串拼接）；
+- [ ] 传给 `render_markdown` 的不可信内容已经过 HTML 标签、属性和 URL 白名单清洗；
 - [ ] 自定义模板后缀时显式开 `autoescape=True`；
 - [ ] 不要使用 `filehost_allow_any_path=true`，除非环境严格隔离；
 - [ ] `filehost_allowed_paths` 显式列出可暴露目录，且不包含 `~`、`/etc`、`/var`、`/srv` 整目录；

{nonebot_plugin_htmlrender-0.7.1 → nonebot_plugin_htmlrender-0.7.2}/mkdocs.yml

@@ -169,6 +169,7 @@ nav:
           - 常见问题: users/faq.md
           - 安全须知: users/security.md
       - 迁移:
+          - v0.7.2 迁移说明: users/migration-v072.md
           - 旧版本迁移指南: users/migration.md
   - 面向开发者:
       - 概览: maintainers/index.md

{nonebot_plugin_htmlrender-0.7.1 → nonebot_plugin_htmlrender-0.7.2}/nonebot_plugin_htmlrender/backend/playwright/operations.py

@@ -110,6 +110,11 @@ def _enum_value(raw: object) -> str:
     return str(getattr(raw, "value", raw))
 
 
+def _should_navigate_to_base_url(base_url: str) -> bool:
+    """判断浏览器是否应先导航到页面的 base URL。"""
+    return base_url != "about:blank"
+
+
 async def read_file(path: str) -> str:
     """异步读取文件内容。"""
     f = await anyio.open_file(path, mode="r", encoding="utf-8")
@@ -264,7 +269,8 @@ async def render_html(
             ),
         ) as page,
     ):
-        if is_remote_playwright_mode() and (
+        remote_mode = is_remote_playwright_mode()
+        if remote_mode and (
             _enum_value(get_playwright_config().remote_local_resource_policy)
             == RemoteLocalResourcePolicy.FILEHOST.value
         ):
@@ -274,7 +280,9 @@ async def render_html(
             )
 
         _setup_page_logging(page)
-        await page.goto(render_request.render.page.base_url)
+        base_url = render_request.render.page.base_url
+        if _should_navigate_to_base_url(base_url):
+            await page.goto(base_url)
         await page.set_content(
             render_request.content.html,
             wait_until=render_request.content.wait_until,
@@ -444,17 +452,16 @@ async def render_markdown(
             )
             css = github_css + pygments_css
 
-        render_request = HtmlRenderRequest(
-            content=ContentConfig(
-                html=await template.render_async(md=md, css=css, extra=extra)
-            ),
-            render=render
-            or RenderConfig(
+        if render is None:
+            base_url = (
+                _path_to_uri(css_path) if css_path else MARKDOWN_TEMPLATE_FILE.as_uri()
+            )
+            if is_remote_playwright_mode():
+                base_url = "about:blank"
+            render = RenderConfig(
                 page=PageConfig(
                     viewport=ViewportConfig(width=width, height=10),
-                    base_url=_path_to_uri(css_path)
-                    if css_path
-                    else MARKDOWN_TEMPLATE_FILE.as_uri(),
+                    base_url=base_url,
                 ),
                 screenshot=_build_screenshot_config(
                     image_type,
@@ -464,7 +471,13 @@ async def render_markdown(
                     full_page=True,
                     wait_before_screenshot=0,
                 ),
+            )
+
+        render_request = HtmlRenderRequest(
+            content=ContentConfig(
+                html=await template.render_async(md=md, css=css, extra=extra)
             ),
+            render=render,
         )
 
         return await render_html(render_request, session=session)