feat(docs): build maintainable documentation site

website/docs.ts

@@ -0,0 +1,213 @@
+/**
+ * Canonical publication manifest for the documentation website.
+ *
+ * Markdown stays in its owning repository tier. This manifest only maps a
+ * source file to its public route and navigation placement.
+ */
+
+/** A page projected into the VitePress source tree. */
+export interface DocsPage {
+  /** Repository-relative canonical Markdown source. */
+  source: string
+  /** VitePress route, including the `.md` suffix. */
+  route: string
+  /** Navigation label shown in the sidebar. */
+  label: string
+  /** Sidebar collection that owns the page. */
+  sidebar: 'zh-guide' | 'zh-develop' | 'en-docs'
+  /** Section label within the sidebar. */
+  section: string
+  /** Stable order within the section. */
+  order: number
+  /** Additional repository paths that resolve to this page. */
+  sourceAliases?: string[]
+}
+
+const zhGuide: DocsPage[] = [
+  {
+    source: 'docs/user/zh-CN/index.md',
+    route: 'index.md',
+    label: 'DeepSeek Harness',
+    sidebar: 'zh-guide',
+    section: '入门',
+    order: 0,
+  },
+  {
+    source: 'docs/user/zh-CN/guide/index.md',
+    route: 'guide/index.md',
+    label: '介绍',
+    sidebar: 'zh-guide',
+    section: '入门',
+    order: 1,
+    sourceAliases: ['docs/user/zh-CN/guide'],
+  },
+  {
+    source: 'docs/user/zh-CN/guide/quickstart.md',
+    route: 'guide/quickstart.md',
+    label: '快速开始',
+    sidebar: 'zh-guide',
+    section: '入门',
+    order: 2,
+  },
+  {
+    source: 'docs/user/zh-CN/guide/config.md',
+    route: 'guide/config.md',
+    label: '配置文件',
+    sidebar: 'zh-guide',
+    section: '入门',
+    order: 3,
+  },
+]
+
+const zhDevelop: DocsPage[] = [
+  {
+    source: 'docs/user/zh-CN/develop/basic/index.md',
+    route: 'develop/basic/index.md',
+    label: '第一个插件',
+    sidebar: 'zh-develop',
+    section: '基础',
+    order: 1,
+    sourceAliases: ['docs/user/zh-CN/develop/basic'],
+  },
+  {
+    source: 'docs/user/zh-CN/develop/basic/tool.md',
+    route: 'develop/basic/tool.md',
+    label: '开发一个 Tool',
+    sidebar: 'zh-develop',
+    section: '基础',
+    order: 2,
+  },
+  {
+    source: 'docs/user/zh-CN/develop/basic/config.md',
+    route: 'develop/basic/config.md',
+    label: '插件配置',
+    sidebar: 'zh-develop',
+    section: '基础',
+    order: 3,
+  },
+  {
+    source: 'docs/user/zh-CN/develop/framework/index.md',
+    route: 'develop/framework/index.md',
+    label: '插件与生命周期',
+    sidebar: 'zh-develop',
+    section: '框架能力',
+    order: 1,
+    sourceAliases: ['docs/user/zh-CN/develop/framework'],
+  },
+  {
+    source: 'docs/user/zh-CN/develop/framework/service.md',
+    route: 'develop/framework/service.md',
+    label: '服务与依赖',
+    sidebar: 'zh-develop',
+    section: '框架能力',
+    order: 2,
+  },
+  {
+    source: 'docs/user/zh-CN/develop/framework/events.md',
+    route: 'develop/framework/events.md',
+    label: '事件系统',
+    sidebar: 'zh-develop',
+    section: '框架能力',
+    order: 3,
+  },
+  {
+    source: 'docs/user/zh-CN/develop/practice/index.md',
+    route: 'develop/practice/index.md',
+    label: '能力的三层拆分',
+    sidebar: 'zh-develop',
+    section: '实战',
+    order: 1,
+    sourceAliases: ['docs/user/zh-CN/develop/practice'],
+  },
+  {
+    source: 'docs/user/zh-CN/develop/practice/llm-adapter.md',
+    route: 'develop/practice/llm-adapter.md',
+    label: 'LLM 适配器',
+    sidebar: 'zh-develop',
+    section: '实战',
+    order: 2,
+  },
+]
+
+const enOverview: DocsPage[] = ([
+  ['docs/architecture.md', 'en/index.md', 'Architecture'],
+  ['docs/cordis-primer.md', 'en/cordis-primer.md', 'Cordis primer'],
+  ['docs/capability-seams.md', 'en/capability-seams.md', 'Capability services'],
+  ['docs/agent-lifecycle.md', 'en/agent-lifecycle.md', 'Agent lifecycle'],
+  ['docs/tool-execution-pipeline.md', 'en/tool-execution-pipeline.md', 'Tool execution'],
+] as const).map(([source, route, label], order) => ({
+  source,
+  route,
+  label,
+  sidebar: 'en-docs',
+  section: 'Concepts',
+  order,
+}))
+
+const enCatalogs: DocsPage[] = ([
+  ['docs/config-catalog.md', 'en/config-catalog.md', 'Plugin configuration'],
+  ['docs/tool-catalog.md', 'en/tool-catalog.md', 'Tool schemas'],
+  ['docs/cordis-catalog/services.md', 'en/cordis-catalog/services.md', 'Services'],
+  ['docs/cordis-catalog/events.md', 'en/cordis-catalog/events.md', 'Events'],
+  ['docs/persistence-catalog.md', 'en/persistence-catalog.md', 'Persistence events'],
+] as const).map(([source, route, label], order) => ({
+  source,
+  route,
+  label,
+  sidebar: 'en-docs',
+  section: 'Generated reference',
+  order,
+}))
+
+const corePages = [
+  ['core.md', 'Core data structures'],
+  ['session.md', 'Sessions'],
+  ['tools.md', 'Tools'],
+  ['llm-streaming.md', 'LLM streaming'],
+  ['bash.md', 'Bash execution'],
+  ['filesystem.md', 'Filesystem'],
+  ['code-runtime.md', 'Code runtime'],
+  ['compaction.md', 'Compaction'],
+  ['subagent.md', 'Subagents'],
+  ['workflow.md', 'Workflows'],
+  ['skills.md', 'Skills'],
+  ['approval.md', 'Approvals'],
+  ['user-interaction.md', 'User interaction'],
+  ['sandbox.md', 'Sandboxing'],
+  ['web.md', 'Web access'],
+  ['persistence.md', 'Session persistence'],
+] as const
+
+const enCore: DocsPage[] = corePages.map(([file, label], order) => ({
+  source: `docs/core-data-structures/${file}`,
+  route: `en/core-data-structures/${file}`,
+  label,
+  sidebar: 'en-docs',
+  section: 'Data structures',
+  order,
+  ...(file === 'core.md' ? { sourceAliases: ['docs/core-data-structures'] } : {}),
+}))
+
+const enCookbook: DocsPage[] = ([
+  ['adding-a-package.md', 'Adding a package'],
+  ['adding-a-tool.md', 'Adding a tool'],
+  ['adding-an-llm-adapter.md', 'Adding an LLM adapter'],
+  ['extension-cookbook.md', 'Extension patterns'],
+] as const).map(([file, label], order) => ({
+  source: `docs/cookbook/${file}`,
+  route: `en/cookbook/${file}`,
+  label,
+  sidebar: 'en-docs',
+  section: 'Cookbook',
+  order,
+}))
+
+/** Every canonical page published by the documentation website. */
+export const docsPages: DocsPage[] = [
+  ...zhGuide,
+  ...zhDevelop,
+  ...enOverview,
+  ...enCatalogs,
+  ...enCore,
+  ...enCookbook,
+]