[mantoujun12]

本 PR 实现 Issue #10763 中插件详情和市场详情的 README 查看能力。README 会跟随 WebUI 语言选择，并提供默认文档和单一本地化文档回退。

Close #10763

Modifications / 改动点

• 已安装插件 README 支持完整 locale、短语言、常见分隔符和大小写不敏感匹配，最终回退默认 README。
• 新增市场 README API，由后端从市场记录的 GitHub 仓库读取默认分支，避免浏览器跨域；非 GitHub 仓库支持显式 readme_url。
• 远程读取增加 HTTPS、公网地址、重定向、15 秒超时和 1 MiB 上限保护。
• README 对话框和详情页在语言切换后重新加载，并复用现有 Markdown + DOMPurify 安全渲染链路。
• 更新 OpenAPI、生成客户端、中英文用户文档与插件 i18n 文档，并增加 README 服务和 API 路由测试。
• This is NOT a breaking change. / 这不是一个破坏性变更。

Screenshots or Test Results / 运行截图或测试结果

未附界面截图；已完成以下自动化验证：

tests/test_plugin_readme.py + test_fastapi_v1_dashboard.py + test_plugin_manager.py
312 passed

恢复最小 diff 后的 README/API 关键测试
11 passed

pnpm run typecheck   PASS
pnpm run i18n:check  PASS
pnpm run build       PASS
pnpm run docs:build  PASS
git diff --check     PASS

pnpm generate:api 的脚本包含 Windows 不兼容的 rm -rf，因此使用同一 openapi-ts 工具链直接生成客户端。

---

Checklist / 检查清单

• 😊 If there are new features added in the PR, I have discussed it with the authors through issues/emails, etc.
  / 如果 PR 中有新加入的功能，已经通过 Issue / 邮件等方式和作者讨论过。

• 👀 My changes have been well-tested, and "Verification Steps" and "Screenshots" have been provided above.
  / 我的更改经过了良好的测试，并已在上方提供了“验证步骤”和“运行截图”。

• 📚 I checked the affected WebUI instructions and screenshots in docs/zh and docs/en against the changed navigation, page structure, and labels, and updated them in this PR (or explained why no documentation update is needed). For renamed, moved, or merged entry points, I included an old entry → new entry mapping in the documentation and changelog.
  / 我已对照变化后的 WebUI 入口、页面结构和术语，核对并在本 PR 中更新 docs/zh 和 docs/en 的相关操作说明与截图（或说明无需更新文档的原因）。入口改名、移动或合并时，已在文档和 changelog 中补充 旧入口 → 新入口 对照。

• 🤓 I have ensured that no new dependencies are introduced, OR if new dependencies are introduced, they have been added to the appropriate locations in requirements.txt and pyproject.toml.
  / 我确保没有引入新依赖库，或者引入了新依赖库的同时将其添加到 requirements.txt 和 pyproject.toml 文件相应位置。

• 😮 My changes do not introduce malicious code.
  / 我的更改没有引入恶意代码。

Summary by Sourcery

Enable locale-aware README previews for installed and marketplace plugins with secure remote retrieval and documented API support.

New Features:

• Add localized README previews for installed plugins and marketplace plugins, following the WebUI locale with sensible fallback behavior.
• Expose a marketplace README API that retrieves documentation from GitHub repositories or explicitly configured README URLs.

Bug Fixes:

• Prevent unsafe remote README access by enforcing HTTPS, public address resolution, bounded redirects, request timeouts, and size limits.

Enhancements:

• Refresh README content when the WebUI language changes and retain safe Markdown rendering for local and remote documentation.
• Extend plugin README APIs with locale support and regenerate the OpenAPI client definitions.

Documentation:

• Document localized plugin README naming, fallback behavior, marketplace support, and user-facing README previews in English and Chinese documentation.

Tests:

• Add service and API route coverage for localized selection, fallback behavior, marketplace sources, URL validation, and size limits.

[sourcery-ai]

Hey - I've found 3 issues

Prompt for AI Agents

Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="dashboard/src/views/extension/PluginDetailPage.vue" line_range="708" />
<code_context>
-
     try {
-      const content = await fetchRemoteMarkdown(readmeUrl);
+      const res = await pluginApi.marketReadme(plugin.name, {
+        locale: locale.value,
+        customRegistry: selectedSource?.value || null,
</code_context>
<issue_to_address>
**Marketplace README lookup fails**

When a marketplace entry's metadata `name` differs from its registry key or canonical ID, `PluginDetailPage.vue` passes `plugin.name` as `plugin_id`, but `get_market_plugin_readme` resolves that value against the exact registry ID; it cannot find the entry, so the README preview is unavailable.

Pass the entry's registry key or canonical marketplace ID to `pluginApi.marketReadme` instead of `plugin.name`.
</issue_to_address>

### Comment 2
<location path="astrbot/dashboard/services/plugin_service.py" line_range="2288" />
<code_context>
+                public_message="该仓库不是 GitHub，无法自动读取 README",
+            )
+
+        github_repository = GitHubRepository.parse(normalized_repo)
+        candidates = self._readme_filename_candidates(locale)
+        candidates.extend(
</code_context>
<issue_to_address>
**SSH repository README fails**

When a marketplace plugin's `repo` uses an SSH or SCP-style GitHub URL, `parse_repository_url` recognizes the GitHub repository, but `GitHubRepository.parse` accepts only HTTP(S) URLs and raises `ValueError`; the marketplace detail cannot load the README.

Parse supported SSH and SCP-style GitHub URLs in `GitHubRepository.parse`.
</issue_to_address>

### Comment 3
<location path="astrbot/dashboard/services/plugin_service.py" line_range="2291-2294" />
<code_context>
+        github_repository = GitHubRepository.parse(normalized_repo)
+        candidates = self._readme_filename_candidates(locale)
+        candidates.extend(
+            filename
+            for filename in ("README_zh.md", "README-zh.md", "README.zh.md")
+            if filename not in candidates
+        )
+        for filename in candidates:
+            content = await self._fetch_remote_readme(
</code_context>
<issue_to_address>
**Wrong-language README is displayed**

When the requested locale and default README are absent, and the repository has a Chinese README alongside another localized README, `get_market_plugin_readme` appends Chinese README candidates for every locale and selects the Chinese file, so users see Chinese documentation instead of the appropriate localized fallback or no-document result.

Only consider Chinese README candidates for Chinese requests, and apply the documented fallback for other locales.
</issue_to_address>

Sourcery assessment

Needs a human reviewer. 3 findings to address first, and the URL is resolved and checked for public IPs, but the HTTP client resolves the hostname again when connecting; a DNS change between those steps could make it fetch an internal address and return its response to the caller. Reverting stops future fetches, but any internal data already exposed cannot be taken back.

Blocking findings: dashboard/src/views/extension/PluginDetailPage.vue:708, astrbot/dashboard/services/plugin_service.py:2288, astrbot/dashboard/services/plugin_service.py:2294

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

[XTsat]

我记得没有指定 README 主语言为中文还是英文

所以是要识别另一个写了语言后缀的版本，然后判断主文件的语言吗

[mantoujun12]

我记得没有指定 README 主语言为中文还是英文

所以是要识别另一个写了语言后缀的版本，然后判断主文件的语言吗

不知道，我自己的插件只有一个README（中文），所以我觉得这个有必要吗？那这样子的话cloud也要改

说明一下：这个pr是根据issue来创建的，你得问提出issue的为什么要搞多语言切换

[mjy1113451]

我记得没有指定 README 主语言为中文还是英文

所以是要识别另一个写了语言后缀的版本，然后判断主文件的语言吗

不知道，我自己的插件只有一个README（中文），所以我觉得这个有必要吗？那这样子的话cloud也要改

说明一下：这个pr是根据issue来创建的，你得问提出issue的为什么要搞多语言切换

现在不是已经插件国际化了吗？但要是只有中文显示的话，系统是英文的话，还得去仓库看，这样可能比较麻烦