feat: add endpoint to fetch marketplace plugin README

astrbot/dashboard/api/plugins.py

@@ -773,6 +773,24 @@ async def get_plugin_readme_by_id(
     )
 
 
+@router.get("/plugins/market/readme")
+async def get_plugin_market_readme(
+    repo: str = Query(..., description="Full GitHub repo URL"),
+    ref: str | None = Query(None, description="Git ref"),
+    proxy: str | None = Query(None, description="Optional GitHub proxy URL prefix"),
+    _auth: AuthContext = Depends(require_plugin_scope),
+    service: PluginService = Depends(get_service),
+):
+    return await _run_service(
+        service.get_market_plugin_readme(
+            repo=repo,
+            ref=ref,
+            proxy=proxy,
+        ),
+        log_label="/api/plugin/market_readme",
+    )
+
+
 @router.get("/plugins/changelog")
 async def get_plugin_changelog_by_id(
     plugin_id: str = Query(...),

astrbot/dashboard/services/plugin_service.py

@@ -5,6 +5,7 @@
 import json
 import os
 import ssl
+import time
 from collections.abc import Awaitable, Callable
 from dataclasses import dataclass
 from datetime import datetime, timezone
@@ -29,6 +30,7 @@
     PluginVersionUnsupportedError,
 )
 from astrbot.core.utils.astrbot_path import get_astrbot_data_path, get_astrbot_temp_path
+from astrbot.core.zip_updator import RepoZipUpdator
 
 PLUGIN_UPDATE_CONCURRENCY = 3
 PLUGIN_OPERATION_FAILED_MESSAGE = "插件操作失败，请查看服务端日志。"
@@ -55,6 +57,11 @@ class RegistrySource:
     md5_url: str | None
 
 
+# 市场插件 README 的内存缓存：(repo, ref) -> (timestamp, content)
+_MARKET_README_TTL = 600
+_market_readme_cache: dict[tuple[str, str], tuple[float, str]] = {}
+
+
 class PluginServiceError(Exception):
     def __init__(
         self,
@@ -1097,6 +1104,68 @@ def get_plugin_readme_from_dashboard_query(
     ) -> tuple[dict, str]:
         return self.get_plugin_readme(plugin_name)
 
+    async def get_market_plugin_readme(
+        self,
+        *,
+        repo: str | None,
+        ref: str | None,
+        proxy: str | None,
+    ) -> tuple[dict, str]:
+        """从 GitHub 仓库获取市场插件的 README。
+
+        使用 ``commit_sha``（或分支）锁定到用户浏览的版本，避免读取到与市场
+        缓存不一致的文档。raw URL 采用 ``github.com/{a}/{r}/raw/{ref}/{file}``
+        形式，与 gh-proxy 的 ``{proxy}/{url}`` 前缀拼接方式兼容。
+        """
+        if not repo:
+            raise PluginServiceError("repo 参数不能为空")
+        try:
+            author, repo_name, branch = RepoZipUpdator().parse_github_url(repo)
+        except ValueError as exc:
+            raise PluginServiceError(
+                f"无效的 GitHub 仓库地址: {exc}",
+                public_message="无效的 GitHub 仓库地址",
+            ) from exc
+
+        resolved_ref = (ref or branch or "master").strip()
+        cache_key = (f"{author}/{repo_name}", resolved_ref)
+        now = time.time()
+        cached = _market_readme_cache.get(cache_key)
+        if cached and now - cached[0] < _MARKET_README_TTL:
+            return {"content": cached[1]}, "成功获取README内容（缓存）"
+
+        proxy_prefix = (proxy or "").rstrip("/")
+        ssl_context = ssl.create_default_context(cafile=certifi.where())
+        last_status = 0
+        async with aiohttp.ClientSession(
+            trust_env=True,
+            connector=aiohttp.TCPConnector(ssl=ssl_context),
+            timeout=aiohttp.ClientTimeout(total=15),
+        ) as session:
+            for fname in ("README.md", "readme.md", "Readme.md", "README.MD"):
+                raw_url = (
+                    f"https://github.com/{author}/{repo_name}"
+                    f"/raw/{resolved_ref}/{fname}"
+                )
+                fetch_url = f"{proxy_prefix}/{raw_url}" if proxy_prefix else raw_url
+                try:
+                    async with session.get(fetch_url) as resp:
+                        last_status = resp.status
+                        if resp.status != 200:
+                            continue
+                        text = await resp.text()
+                        if text and text.strip():
+                            _market_readme_cache[cache_key] = (now, text)
+                            return {"content": text}, "成功获取README内容"
+                except Exception as exc:
+                    logger.warning(f"获取 {fetch_url} 失败: {exc}")
+                    continue
+
+        raise PluginServiceError(
+            f"未找到 README 文件（最后状态码: {last_status}）",
+            public_message="未找到该插件的 README 文件",
+        )
+
     def get_plugin_changelog(self, plugin_name: str | None) -> tuple[dict, str]:
         logger.debug(f"正在获取插件 {plugin_name} 的更新日志")
         if not plugin_name:

dashboard/src/api/generated/openapi-v1/types.gen.ts

@@ -86,6 +86,9 @@ export type ChatProjectRequest = {
 };
 
 export type ChatRequest = {
+    /**
+     * Caller-declared WebChat sender/session owner. This value is used as the message sender identity and may participate in sender-ID-based command permission checks. Treat chat-scoped API keys as trusted backend credentials and map or validate usernames before accepting end-user input.
+     */
     username?: string;
     session_id?: string;
     /**
@@ -1679,6 +1682,27 @@ export type GetPluginReadmeByIdResponse = (string);
 
 export type GetPluginReadmeByIdError = unknown;
 
+export type GetPluginMarketReadmeData = {
+    query: {
+        /**
+         * Optional GitHub proxy URL prefix (e.g. https://gh-proxy.com).
+         */
+        proxy?: string;
+        /**
+         * Git ref (commit_sha preferred; falls back to master).
+         */
+        ref?: string;
+        /**
+         * Full GitHub repo URL (https://github.com/{author}/{repo}).
+         */
+        repo: string;
+    };
+};
+
+export type GetPluginMarketReadmeResponse = (string);
+
+export type GetPluginMarketReadmeError = unknown;
+
 export type GetPluginChangelogByIdData = {
     query: {
         plugin_id: string;

dashboard/src/api/v1.ts

@@ -1246,6 +1246,11 @@ export const pluginApi = {
       openApiV1.getPluginReadmeById({ query: { plugin_id: pluginId } }),
     );
   },
+  marketReadme(params: { repo: string; ref?: string; proxy?: string }) {
+    return typed<OpenConfig>(
+      openApiV1.getPluginMarketReadme({ query: params }),
+    );
+  },
   changelog(pluginId: string) {
     return typed<OpenConfig>(
       openApiV1.getPluginChangelogById({ query: { plugin_id: pluginId } }),

dashboard/src/views/extension/PluginDetailPage.vue

@@ -610,15 +610,32 @@ const fetchReadme = async () => {
   renderedReadme.value = "";
 
   if (isMarketDetail.value) {
-    const readmeUrl = getDocumentUrl("readme_url");
-    if (!readmeUrl) {
+    const repo = repoUrl.value;
+    if (!repo) {
       readmeEmpty.value = true;
       readmeLoading.value = false;
       return;
     }
+    const ref =
+      props.marketPlugin?.commit_sha || props.marketPlugin?.branch || "";
+    const proxy =
+      props.state?.getSelectedGitHubProxy?.() || undefined;
 
     try {
-      const content = await fetchRemoteMarkdown(readmeUrl);
+      const res = await pluginApi.marketReadme({
+        repo,
+        ref: ref || undefined,
+        proxy: proxy || undefined,
+      });
+
+      if (res.data.status !== "ok") {
+        // Missing README on the repo is a normal outcome — show the empty
+        // state rather than surfacing an error alert.
+        readmeEmpty.value = true;
+        return;
+      }
+
+      const content = res.data.data?.content || "";
       if (!content.trim()) {
         readmeEmpty.value = true;
         return;
@@ -726,7 +743,7 @@ const fetchChangelog = async () => {
 };
 
 const showDocsSection = computed(
-  () => !isMarketDetail.value || !!getDocumentUrl("readme_url"),
+  () => !isMarketDetail.value || !!repoUrl.value,
 );
 
 const showChangelogSection = computed(
@@ -737,7 +754,8 @@ watch(
   () => [
     props.plugin?.name,
     props.sourceTab,
-    props.marketPlugin?.readme_url,
+    props.marketPlugin?.repo,
+    props.marketPlugin?.commit_sha,
     props.marketPlugin?.changelog_url,
   ],
   async () => {

openspec/openapi-v1.yaml

@@ -1862,6 +1862,35 @@ paths:
         "200":
           $ref: "#/components/responses/Text"
 
+  /api/v1/plugins/market/readme:
+    get:
+      tags: [Plugins]
+      summary: Get a marketplace plugin's README from its GitHub repo
+      operationId: getPluginMarketReadme
+      x-astrbot-scope: plugin
+      parameters:
+        - name: repo
+          in: query
+          required: true
+          schema:
+            type: string
+          description: Full GitHub repo URL (https://github.com/{author}/{repo}).
+        - name: ref
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Git ref (commit_sha preferred; falls back to master).
+        - name: proxy
+          in: query
+          required: false
+          schema:
+            type: string
+          description: Optional GitHub proxy URL prefix (e.g. https://gh-proxy.com).
+      responses:
+        "200":
+          $ref: "#/components/responses/Text"
+
   /api/v1/plugins/changelog:
     get:
       tags: [Plugins]

tests/test_fastapi_v1_dashboard.py

@@ -2555,3 +2555,48 @@ async def test_v1_platform_webhook_is_public_route(
         "method": "POST",
         "payload": {"challenge": "ping"},
     }
+
+
+@pytest.mark.asyncio
+async def test_v1_plugin_market_readme_happy_path(
+    asgi_app: FastAPI,
+    asgi_client: httpx.AsyncClient,
+    monkeypatch: pytest.MonkeyPatch,
+):
+    """市场插件 README 接口正常路径：返回 200 + 内容，缓存命中返回缓存版本。"""
+    plugin_service = asgi_app.state.services.plugins
+    call_count = 0
+
+    async def fake_get_market_plugin_readme(*, repo, ref, proxy):
+        nonlocal call_count
+        call_count += 1
+        return {"content": f"# README of {repo}"}, "success"
+
+    monkeypatch.setattr(
+        plugin_service, "get_market_plugin_readme", fake_get_market_plugin_readme
+    )
+
+    headers = _jwt_headers()
+    response = await asgi_client.get(
+        "/api/v1/plugins/market/readme",
+        params={"repo": "https://github.com/a/b", "ref": "main"},
+        headers=headers,
+    )
+
+    assert response.status_code == 200
+    data = response.json()
+    assert data["status"] == "ok"
+    assert data["data"]["content"] == "# README of https://github.com/a/b"
+    assert call_count == 1
+
+
+@pytest.mark.asyncio
+async def test_v1_plugin_market_readme_requires_auth(
+    asgi_client: httpx.AsyncClient,
+):
+    """未经认证的请求应被拒绝（401）。"""
+    response = await asgi_client.get(
+        "/api/v1/plugins/market/readme",
+        params={"repo": "https://github.com/a/b"},
+    )
+    assert response.status_code == 401