feat(docs): build maintainable documentation site

2026-08-15 21:04:50 +00:00 · 2026-07-13 15:38:47 +08:00
parent 72bfba2d4d
commit d2f810e9fe
52 changed files with 2380 additions and 2224 deletions
--- a/website/.vitepress/config.ts
+++ b/website/.vitepress/config.ts
@@ -0,0 +1,142 @@
+/** VitePress configuration for the locally projected documentation site. */
+
+import type { DefaultTheme, PageData } from 'vitepress'
+import type { ViteDevServer } from 'vite'
+import { withMermaid } from 'vitepress-plugin-mermaid'
+import { docsPages, type DocsPage } from '../docs.ts'
+import { docsSourceFiles, projectDocs } from '../../scripts/project-doc-site.ts'
+
+projectDocs()
+
+const sectionOrder = [
+  '入门',
+  '基础',
+  '框架能力',
+  '实战',
+  'Concepts',
+  'Generated reference',
+  'Data structures',
+  'Cookbook',
+]
+
+function sidebar(collection: DocsPage['sidebar']): DefaultTheme.SidebarItem[] {
+  const pages = docsPages.filter(page => page.sidebar === collection && page.route !== 'index.md')
+  const sections = new Map<string, DocsPage[]>()
+  for (const page of pages) {
+    const entries = sections.get(page.section) ?? []
+    entries.push(page)
+    sections.set(page.section, entries)
+  }
+  return [...sections.entries()]
+    .sort(([left], [right]) => sectionOrder.indexOf(left) - sectionOrder.indexOf(right))
+    .map(([text, entries]) => ({
+      text,
+      items: entries
+        .sort((left, right) => left.order - right.order)
+        .map(page => ({ text: page.label, link: `/${page.route.replace(/(?:index)?\.md$/, '')}` })),
+    }))
+}
+
+function watchCanonicalDocs(server: ViteDevServer): void {
+  const sources = docsSourceFiles()
+  server.watcher.add(sources)
+  server.watcher.on('change', (changed) => {
+    if (!sources.includes(changed)) return
+    projectDocs()
+  })
+}
+
+function escapeVueInterpolation(html: string): string {
+  return html.replaceAll('{{', '&#123;&#123;').replaceAll('}}', '&#125;&#125;')
+}
+
+const sharedTheme: Pick<DefaultTheme.Config, 'search' | 'socialLinks' | 'editLink'> = {
+  search: { provider: 'local' },
+  socialLinks: [
+    { icon: 'github', link: 'https://github.com/deepseek-harness/deepseek-harness' },
+  ],
+  editLink: {
+    pattern: ({ frontmatter }: PageData) => {
+      const data: unknown = frontmatter
+      const editSource: unknown = typeof data === 'object' && data !== null ? Reflect.get(data, 'editSource') : undefined
+      if (typeof editSource !== 'string') throw new Error('Projected documentation page has no editSource frontmatter.')
+      return `https://github.com/deepseek-harness/deepseek-harness/edit/master/${editSource}`
+    },
+    text: '在 GitHub 上编辑此页',
+  },
+}
+
+export default withMermaid({
+  title: 'DeepSeek Harness',
+  description: '用于构建 Agent Harness 的插件化 SDK',
+  cleanUrls: true,
+  srcDir: '.generated',
+  cacheDir: '.cache',
+  outDir: '.dist',
+  locales: {
+    root: {
+      label: '简体中文',
+      lang: 'zh-CN',
+      themeConfig: {
+        nav: [
+          { text: '入门', link: '/guide/', activeMatch: '^/guide/' },
+          { text: '开发', link: '/develop/basic/', activeMatch: '^/develop/' },
+          { text: 'Reference', link: '/en/', activeMatch: '^/en/' },
+        ],
+        sidebar: {
+          '/guide/': sidebar('zh-guide'),
+          '/develop/': sidebar('zh-develop'),
+        },
+        outline: { label: '本页目录' },
+        docFooter: { prev: '上一篇', next: '下一篇' },
+      },
+    },
+    en: {
+      label: 'English',
+      lang: 'en-US',
+      link: '/en/',
+      themeConfig: {
+        nav: [
+          { text: 'Concepts', link: '/en/' },
+          { text: 'Reference', link: '/en/config-catalog' },
+          { text: '中文指南', link: '/guide/' },
+        ],
+        sidebar: {
+          '/en/': sidebar('en-docs'),
+        },
+        editLink: {
+          pattern: ({ frontmatter }: PageData) => {
+            const data: unknown = frontmatter
+            const editSource: unknown = typeof data === 'object' && data !== null ? Reflect.get(data, 'editSource') : undefined
+            if (typeof editSource !== 'string') throw new Error('Projected documentation page has no editSource frontmatter.')
+            return `https://github.com/deepseek-harness/deepseek-harness/edit/master/${editSource}`
+          },
+          text: 'Edit this page on GitHub',
+        },
+        outline: { label: 'On this page' },
+        docFooter: { prev: 'Previous', next: 'Next' },
+      },
+    },
+  },
+  vite: {
+    plugins: [
+      {
+        name: 'deepseek-harness-doc-projector',
+        configureServer: watchCanonicalDocs,
+      },
+    ],
+  },
+  markdown: {
+    config(md) {
+      const renderText = md.renderer.rules.text
+      const renderCode = md.renderer.rules.code_inline
+      if (renderText === undefined || renderCode === undefined) {
+        throw new Error('VitePress Markdown renderer is missing its text or inline-code rule.')
+      }
+      md.renderer.rules.text = (...args) => escapeVueInterpolation(renderText(...args))
+      md.renderer.rules.code_inline = (...args) => escapeVueInterpolation(renderCode(...args))
+    },
+  },
+  mermaid: {},
+  themeConfig: sharedTheme,
+})
--- a/website/.vitepress/config/index.ts
+++ b/website/.vitepress/config/index.ts
@@ -1,17 +0,0 @@
-import { defineConfig } from 'vitepress'
-import { zhCN } from './zh-CN'
-
-export default defineConfig({
-  title: 'DeepSeek Harness',
-  description: '插件化 Agent 开发框架',
-
-  locales: {
-    'zh-CN': zhCN,
-  },
-
-  themeConfig: {
-    socialLinks: [
-      { icon: 'github', link: 'https://github.com/deepseek-harness/deepseek-harness' },
-    ],
-  },
-})
--- a/website/.vitepress/config/zh-CN.ts
+++ b/website/.vitepress/config/zh-CN.ts
@@ -1,99 +0,0 @@
-import type { DefaultTheme, LocaleSpecificConfig } from 'vitepress'
-
-const guideSidebar: DefaultTheme.SidebarItem[] = [
-  {
-    text: '入门',
-    items: [
-      { text: '介绍', link: '/zh-CN/guide/' },
-      { text: '快速开始', link: '/zh-CN/guide/quickstart' },
-      { text: '配置文件', link: '/zh-CN/guide/config' },
-    ],
-  },
-]
-
-const developSidebar: DefaultTheme.SidebarItem[] = [
-  {
-    text: '基础',
-    items: [
-      { text: '第一个插件', link: '/zh-CN/develop/basic/' },
-      { text: '开发一个 Tool', link: '/zh-CN/develop/basic/tool' },
-      { text: '插件配置', link: '/zh-CN/develop/basic/config' },
-    ],
-  },
-  {
-    text: '框架能力',
-    items: [
-      { text: '插件与生命周期', link: '/zh-CN/develop/framework/' },
-      { text: '服务与依赖', link: '/zh-CN/develop/framework/service' },
-      { text: '事件系统', link: '/zh-CN/develop/framework/events' },
-    ],
-  },
-  {
-    text: '实战',
-    items: [
-      { text: '能力的三层拆分', link: '/zh-CN/develop/practice/' },
-      { text: 'LLM 适配器', link: '/zh-CN/develop/practice/llm-adapter' },
-    ],
-  },
-]
-
-const apiSidebar: DefaultTheme.SidebarItem[] = [
-  {
-    text: '框架 API',
-    items: [
-      { text: '总览', link: '/zh-CN/api/' },
-      { text: 'Context', link: '/zh-CN/api/cordis/context' },
-      { text: 'Events', link: '/zh-CN/api/cordis/events' },
-      { text: 'Fiber', link: '/zh-CN/api/cordis/fiber' },
-      { text: 'Registry', link: '/zh-CN/api/cordis/registry' },
-      { text: 'Service', link: '/zh-CN/api/cordis/service' },
-    ],
-  },
-  {
-    text: 'Harness API',
-    items: [
-      { text: 'Tools (dsh-tools)', link: '/zh-CN/api/harness/tools' },
-      { text: 'LLM (dsh-llm)', link: '/zh-CN/api/harness/llm' },
-      { text: 'Session (dsh-session)', link: '/zh-CN/api/harness/session' },
-      { text: 'Agent (dsh-agent)', link: '/zh-CN/api/harness/agent' },
-      { text: 'Bash (dsh-bash)', link: '/zh-CN/api/harness/bash' },
-      { text: 'Filesystem (dsh-fs)', link: '/zh-CN/api/harness/fs' },
-      { text: 'Subagent (dsh-subagent)', link: '/zh-CN/api/harness/subagent' },
-    ],
-  },
-]
-
-const designSidebar: DefaultTheme.SidebarItem[] = [
-  {
-    text: '系统设计',
-    items: [
-      { text: '概述', link: '/zh-CN/design/' },
-      { text: '可组合性与插件系统', link: '/zh-CN/design/composability' },
-      { text: '作用与余作用', link: '/zh-CN/design/effects-coeffects' },
-      { text: '可逆作用', link: '/zh-CN/design/revertible-effects' },
-      { text: '响应式余作用', link: '/zh-CN/design/reactive-coeffects' },
-      { text: '上下文模型', link: '/zh-CN/design/context-model' },
-    ],
-  },
-]
-
-export const zhCN: LocaleSpecificConfig<DefaultTheme.Config> = {
-  label: '简体中文',
-  lang: 'zh-CN',
-  themeConfig: {
-    nav: [
-      { text: '入门', link: '/zh-CN/guide/', activeMatch: '/zh-CN/guide/' },
-      { text: '开发', link: '/zh-CN/develop/basic/', activeMatch: '/zh-CN/develop/' },
-      { text: 'API', link: '/zh-CN/api/', activeMatch: '/zh-CN/api/' },
-      { text: '设计', link: '/zh-CN/design/', activeMatch: '/zh-CN/design/' },
-    ],
-    sidebar: {
-      '/zh-CN/guide/': guideSidebar,
-      '/zh-CN/develop/': developSidebar,
-      '/zh-CN/api/': apiSidebar,
-      '/zh-CN/design/': designSidebar,
-    },
-    outline: { label: '本页目录' },
-    docFooter: { prev: '上一篇', next: '下一篇' },
-  },
-}