diff --git a/README.md b/README.md
index 926c6d65..f4baf508 100644
--- a/README.md
+++ b/README.md
@@ -16,7 +16,7 @@
   <a href="LICENSE"><img alt="License" src="https://img.shields.io/badge/License-Apache--2.0-blue?style=flat" /></a>
 </p>
 
-<p align="center"><a href="public-docs/assets/ksadk-runtime-platform-hero.png"><img alt="KsADK 真实 CLI 截图：agentengine -h" src="public-docs/assets/ksadk-runtime-platform-hero-wide.png" width="860" /></a></p>
+<p align="center"><a href="https://raw.githubusercontent.com/kingsoftcloud/ksadk-python/main/docs-site/public/assets/ksadk-runtime-platform-hero.png"><img alt="KsADK 真实 CLI 截图：agentengine -h" src="https://raw.githubusercontent.com/kingsoftcloud/ksadk-python/main/docs-site/public/assets/ksadk-runtime-platform-hero-wide.png" width="860" /></a></p>
 
 ## 30 秒快速体验
 
@@ -37,9 +37,9 @@ agentengine run -i
 agentengine web . --no-open
 ```
 
-<p align="center"><a href="public-docs/assets/ksadk-web-ui-screenshot.png"><img alt="KsADK 真实 Web UI 调试截图" src="public-docs/assets/ksadk-web-ui-screenshot.png" width="860" /></a></p>
+<p align="center"><a href="https://raw.githubusercontent.com/kingsoftcloud/ksadk-python/main/docs-site/public/assets/ksadk-web-ui-screenshot.png"><img alt="KsADK 真实 Web UI 调试截图" src="https://raw.githubusercontent.com/kingsoftcloud/ksadk-python/main/docs-site/public/assets/ksadk-web-ui-screenshot.png" width="860" /></a></p>
 
-<p align="center"><a href="public-docs/assets/ksadk-local-debugging-demo.gif"><img alt="KsADK 真实本地 Web UI 演示" src="public-docs/assets/ksadk-local-debugging-demo.gif" width="860" /></a></p>
+<p align="center"><a href="https://raw.githubusercontent.com/kingsoftcloud/ksadk-python/main/docs-site/public/assets/ksadk-local-debugging-demo.gif"><img alt="KsADK 真实本地 Web UI 演示" src="https://raw.githubusercontent.com/kingsoftcloud/ksadk-python/main/docs-site/public/assets/ksadk-local-debugging-demo.gif" width="860" /></a></p>
 
 ## 为什么需要 KsADK
 
@@ -53,7 +53,7 @@ agentengine web . --no-open
 
 ## 架构
 
-<p align="center"><a href="public-docs/assets/ksadk-runtime-architecture.png"><img alt="KsADK Agent Runtime Platform 架构" src="public-docs/assets/ksadk-runtime-architecture.png" width="860" /></a></p>
+<p align="center"><a href="https://raw.githubusercontent.com/kingsoftcloud/ksadk-python/main/docs-site/public/assets/ksadk-runtime-architecture.png"><img alt="KsADK Agent Runtime Platform 架构" src="https://raw.githubusercontent.com/kingsoftcloud/ksadk-python/main/docs-site/public/assets/ksadk-runtime-architecture.png" width="860" /></a></p>
 
 ## 文档与样例
 
diff --git a/docs-site/app/[lang]/docs/[[...slug]]/page.tsx b/docs-site/app/[lang]/docs/[[...slug]]/page.tsx
index 982c1746..3066b103 100644
--- a/docs-site/app/[lang]/docs/[[...slug]]/page.tsx
+++ b/docs-site/app/[lang]/docs/[[...slug]]/page.tsx
@@ -36,7 +36,7 @@ export default async function Page({
           <MarkdownCopyButton markdownUrl={markdownUrl} />
           <ViewOptionsPopover
             markdownUrl={markdownUrl}
-            githubUrl={`https://github.com/${gitConfig.user}/${gitConfig.repo}/blob/${gitConfig.branch}/docs-site/content/docs/${page.path}.mdx`}
+            githubUrl={`https://github.com/${gitConfig.user}/${gitConfig.repo}/blob/${gitConfig.branch}/docs-site/content/docs/${page.path}`}
           />
         </div>
       </div>
diff --git a/docs-site/lib/source.ts b/docs-site/lib/source.ts
index 94e65a32..45eb464b 100644
--- a/docs-site/lib/source.ts
+++ b/docs-site/lib/source.ts
@@ -4,7 +4,7 @@ import { docs } from 'collections/server';
 import { loader } from 'fumadocs-core/source';
 import { statusBadgesPlugin } from 'fumadocs-core/source/plugins/status-badges';
 import { i18n } from './i18n';
-import { docsContentRoute, docsImageRoute, docsRoute } from './shared';
+import { docsContentRoute, docsImageRoute, docsRoute, assetPath } from './shared';
 
 // See https://fumadocs.dev/docs/headless/source-api for more info
 export const source = loader({
@@ -47,7 +47,8 @@ export function getPageMarkdownUrl(page: (typeof source)['$inferPage']) {
 
   return {
     segments,
-    url: `${docsContentRoute}/${segments.join('/')}`,
+    // GitHub Pages 在 /<repo> 子路径,markdown URL 需带 basePath,否则复制出来 404。
+    url: assetPath(`${docsContentRoute}/${segments.join('/')}`),
   };
 }
 
diff --git a/tests/test_public_release_positioning.py b/tests/test_public_release_positioning.py
index 3550728b..0425339b 100644
--- a/tests/test_public_release_positioning.py
+++ b/tests/test_public_release_positioning.py
@@ -26,10 +26,10 @@ def test_public_readme_positions_ksadk_as_runtime_platform():
         "文档与样例",
         "相关项目",
         "参与贡献",
-        "public-docs/assets/ksadk-runtime-platform-hero-wide.png",
-        "public-docs/assets/ksadk-web-ui-screenshot.png",
-        "public-docs/assets/ksadk-local-debugging-demo.gif",
-        "public-docs/assets/ksadk-runtime-architecture.png",
+        "ksadk-runtime-platform-hero-wide.png",
+        "ksadk-web-ui-screenshot.png",
+        "ksadk-local-debugging-demo.gif",
+        "ksadk-runtime-architecture.png",
     ):
         assert expected in readme
 
@@ -46,10 +46,10 @@ def test_public_readme_language_variants_keep_homepage_shape():
 
     for text in (zh_readme, en_readme):
         assert "Kingsoft Cloud Agent Development Kit" in text
-        assert "public-docs/assets/ksadk-runtime-platform-hero-wide.png" in text
-        assert "public-docs/assets/ksadk-web-ui-screenshot.png" in text
-        assert "public-docs/assets/ksadk-local-debugging-demo.gif" in text
-        assert "public-docs/assets/ksadk-runtime-architecture.png" in text
+        assert "ksadk-runtime-platform-hero-wide.png" in text
+        assert "ksadk-web-ui-screenshot.png" in text
+        assert "ksadk-local-debugging-demo.gif" in text
+        assert "ksadk-runtime-architecture.png" in text
         assert "发布版本：" not in text
         assert "## 0.6." not in text