From db1ece26911ba33da86c61be6f58a6ddcf8bd1b7 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 8 Feb 2026 11:19:06 +0000 Subject: [PATCH 1/6] Initial plan From 54bdab99c5cc3fc8b2ddcb388be18e7be3de0acd Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 8 Feb 2026 11:27:50 +0000 Subject: [PATCH 2/6] docs: add design document, packages overview, and update development roadmap with progress Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com> --- content/docs/design.cn.mdx | 300 ++++++++++++++++++++++++++ content/docs/design.mdx | 301 +++++++++++++++++++++++++++ content/docs/development-plan.cn.mdx | 274 ++++++++++++++++++++++++ content/docs/development-plan.mdx | 156 ++++++++------ content/docs/meta.json | 2 + content/docs/packages.cn.mdx | 290 ++++++++++++++++++++++++++ content/docs/packages.mdx | 290 ++++++++++++++++++++++++++ 7 files changed, 1553 insertions(+), 60 deletions(-) create mode 100644 content/docs/design.cn.mdx create mode 100644 content/docs/design.mdx create mode 100644 content/docs/development-plan.cn.mdx create mode 100644 content/docs/packages.cn.mdx create mode 100644 content/docs/packages.mdx diff --git a/content/docs/design.cn.mdx b/content/docs/design.cn.mdx new file mode 100644 index 0000000..b1d8fda --- /dev/null +++ b/content/docs/design.cn.mdx @@ -0,0 +1,300 @@ +--- +title: 系统设计 +description: ObjectDocs 完整系统设计文档 — 架构、技术决策和组件概览。 +--- + +import { FileJson, Layers, Cpu, Zap, GitBranch, Package, Globe, Code } from 'lucide-react'; + +# 系统设计文档 + +本文档提供 ObjectDocs 的完整技术设计概览，涵盖系统架构、包结构、数据流和关键设计决策。 + +**版本**: v0.2.12 | **最后更新**: 2026-02-08 + +## 1. 系统概述 + +ObjectDocs 是一个基于 Next.js 和 Fumadocs 构建的**元数据驱动文档引擎**，专为 ObjectStack 低代码生态系统设计。它遵循严格的**配置即代码**理念，文档结构由数据（JSON）定义，而非代码（React）。 + +### 设计目标 + + +} title="元数据驱动"> +导航、侧边栏和页面排序完全通过 `meta.json` 文件和 `docs.site.json` 配置定义。内容创作者无需接触 React 代码。 + +} title="关注点分离"> +系统严格分离三个层次：**展示层**（React/Next.js 站点引擎）、**配置层**（JSON 文件）和**内容层**（MDX 文档）。 + +} title="Monorepo 架构"> +项目组织为 pnpm 工作区 monorepo，包含两个核心包（`@objectdocs/cli` 和 `@objectdocs/site`）以及共享的内容层。 + +} title="国际化优先"> +多语言支持内置于核心架构中，支持语言特定的 MDX 文件和 6 种语言的预置 UI 翻译。 + + + +## 2. 架构概览 + +### 2.1 高层架构 + +```text +┌─────────────────────────────────────────────────────────┐ +│ ObjectDocs 系统 │ +├──────────────┬──────────────────┬───────────────────────┤ +│ @objectdocs │ @objectdocs │ 内容层 │ +│ /cli │ /site │ │ +│ │ │ │ +│ 命令: │ Next.js 16 + │ content/ │ +│ • init │ Fumadocs 16 │ ├── docs.site.json │ +│ • dev │ │ ├── docs/ │ +│ • build │ App Router │ │ ├── meta.json │ +│ • start │ React Server │ │ ├── index.mdx │ +│ • translate │ Components │ │ └── ... │ +│ │ │ └── public/ │ +├──────────────┼──────────────────┼───────────────────────┤ +│ CLI 层 │ 展示层 │ 数据层 │ +│ (工具链) │ (渲染) │ (配置 + 内容) │ +└──────────────┴──────────────────┴───────────────────────┘ +``` + +### 2.2 包依赖关系图 + +```text +根工作区 (objectdocs v1.0.0) +├── @objectdocs/cli (v0.2.12) +│ ├── 依赖: @objectdocs/site (workspace:*) +│ ├── cac (CLI 框架) +│ ├── openai (AI 翻译) +│ └── dotenv (环境配置) +└── @objectdocs/site (v0.2.12) + ├── next (^16.1.2) + ├── fumadocs-core (^16.4.7) + ├── fumadocs-ui (^16.4.7) + ├── fumadocs-mdx (^14.2.5) + ├── react (^19.2.3) + ├── tailwindcss (^4.1.18) + └── typescript (^5.9.3) +``` + +## 3. 核心组件 + +### 3.1 CLI 包 (`@objectdocs/cli`) + +CLI 是 ObjectDocs 的主要开发者接口。基于 [CAC](https://github.com/cacjs/cac) 框架构建，提供 5 个命令： + +| 命令 | 用途 | 关键行为 | +|------|------|---------| +| `init` | 初始化新文档项目 | 将 `@objectdocs/site` 复制到 `content/.fumadocs`，安装依赖，更新 `.gitignore` | +| `dev` | 启动开发服务器 | 运行在端口 7777，监听 `docs.site.json` 变更，同步公共资源 | +| `build` | 生产环境构建 | 支持静态导出（`out/`）和动态独立（`.next/`）两种模式 | +| `start` | 启动生产服务器 | 静态模式使用 `serve`，动态模式使用 Next.js 服务器 | +| `translate` | AI 驱动的翻译 | 使用 OpenAI API，支持 `--all` 参数，生成语言特定的 `.mdx` 文件 | + +**设计决策**：CLI 在初始化时将整个 `@objectdocs/site` 包复制到 `content/.fumadocs`，而不是作为运行时依赖使用。这确保了文档引擎和用户内容之间的完全隔离，允许自定义站点而不影响包本身。 + +### 3.2 站点包 (`@objectdocs/site`) + +站点包是一个完整的 Next.js 应用模板，作为文档渲染引擎。 + +**核心组件**: + +| 组件 | 文件 | 职责 | +|------|------|------| +| 根布局 | `app/layout.tsx` | HTML 外壳、Provider、全局样式 | +| 语言路由 | `app/[lang]/layout.tsx` | i18n 布局与 Fumadocs Provider | +| 文档页面 | `app/[lang]/docs/[[...slug]]/page.tsx` | MDX 渲染、TOC、导航 | +| 搜索 API | `app/api/search/route.ts` | 全文搜索端点 | +| i18n 配置 | `lib/i18n.ts` | 语言定义和 UI 翻译 | +| 站点配置 | `lib/config.ts` | 加载并合并 `docs.site.json` | +| 内容加载器 | `lib/source.ts` | 带 i18n 的 Fumadocs 内容源 | + +### 3.3 内容层 + +内容层是定义文档站点的用户数据： + +```text +content/ +├── docs.site.json # 全局站点配置 +│ ├── branding # Logo、名称、主题颜色 +│ ├── links # 导航栏链接 +│ ├── sidebar # 侧边栏行为配置 +│ ├── toc # 目录设置 +│ ├── footer # 页脚版权文本 +│ ├── page # 页面功能（编辑链接、最后更新） +│ ├── content # 内容功能（数学公式、代码主题） +│ ├── i18n # 语言配置 +│ └── build # 构建模式（export/standalone） +├── public/ # 静态资源（图片、字体） +└── docs/ + ├── meta.json # 根导航结构 + ├── index.mdx # 首页（英文） + ├── index.cn.mdx # 首页（中文） + └── getting-started/ + ├── meta.json # 章节页面排序 + ├── index.mdx # 章节首页 + └── ... +``` + +## 4. 数据流 + +### 4.1 构建时数据流 + + + +### 内容发现 +Fumadocs MDX 源加载器扫描 `DOCS_DIR` 目录中的所有 `.mdx` 文件和 `meta.json` 文件。文件按语言后缀组织（如 `.cn.mdx` 为中文）。 + +### 配置合并 +站点从内容目录读取 `docs.site.json` 并与 `lib/config.ts` 中的默认配置值合并，生成完整的站点配置。 + +### 导航树构建 +每个目录中的 `meta.json` 文件定义页面排序和章节标题。Fumadocs 从这些文件构建层次化的导航树。 + +### MDX 编译 +每个 `.mdx` 文件通过 Fumadocs MDX 管道（含 remark/rehype 插件）编译，生成 React Server Components。 + +### 静态生成 +Next.js App Router 为每个路由生成静态页面。在独立模式下，页面可以通过 ISR 进行服务端渲染。 + + + +### 4.2 运行时数据流 + +```text +用户请求 → Next.js 路由 → 语言检测 → 页面解析 + → MDX 内容渲染 (RSC) → Fumadocs UI 布局 → HTML 响应 +``` + +### 4.3 翻译数据流 + +```text +源 MDX → CLI translate 命令 → OpenAI API → 翻译后的 MDX + → 语言特定文件 (如 .cn.mdx) → 内容发现 +``` + +## 5. 配置系统设计 + +### 5.1 `docs.site.json` 模式 + +站点配置文件支持以下部分： + +```json +{ + "site": { + "title": "站点标题", + "description": "站点描述", + "url": "https://example.com", + "favicon": "/favicon.ico" + }, + "branding": { + "name": "品牌名称", + "logo": { "light": "/logo-light.svg", "dark": "/logo-dark.svg" }, + "themeColor": "#7c3aed", + "borderRadius": "0.5rem" + }, + "links": [{ "text": "首页", "url": "/" }], + "sidebar": { "collapsible": true, "defaultOpenLevel": 1 }, + "toc": { "enabled": true, "depth": 3 }, + "footer": { "copyright": "© 2026" }, + "page": { + "lastUpdate": true, + "editOnGithub": { "owner": "org", "repo": "repo" } + }, + "content": { "codeTheme": "vesper", "imageZoom": true }, + "i18n": { + "defaultLanguage": "en", + "languages": ["en", "cn"] + }, + "build": { "mode": "export" } +} +``` + +### 5.2 `meta.json` 模式 + +每个目录可以包含 `meta.json` 来控制导航： + +```json +{ + "title": "章节标题", + "pages": ["page-a", "page-b", "sub-directory"] +} +``` + +**关键规则**：侧边栏导航**永远不**在 React 组件中定义。所有导航结构变更通过 `meta.json` 文件进行。 + +## 6. 国际化架构 + +### 6.1 支持的语言 + +| 代码 | 语言 | UI 翻译 | +|------|------|---------| +| `en` | English | ✅ 完整 | +| `cn` | 中文 | ✅ 完整 | +| `ja` | 日本語 | ✅ 完整 | +| `fr` | Français | ✅ 完整 | +| `de` | Deutsch | ✅ 完整 | +| `es` | Español | ✅ 完整 | + +### 6.2 内容翻译策略 + +- **基于文件**：每种语言有独立的 MDX 文件（如英文 `index.mdx`，中文 `index.cn.mdx`） +- **回退机制**：如果翻译文件不存在，使用默认语言版本 +- **AI 翻译**：`translate` CLI 命令使用 OpenAI 自动生成翻译 +- **URL 路由**：URL 路径中的语言前缀（`/en/docs/...`、`/cn/docs/...`） + +## 7. 部署设计 + +### 7.1 构建模式 + +| 模式 | 输出 | 使用场景 | +|------|------|---------| +| `export`（静态） | `out/` 目录（HTML/CSS/JS） | CDN 托管、GitHub Pages、Vercel 静态 | +| `standalone`（动态） | `.next/`（Node.js 服务器） | ISR、SSR、API 路由、Vercel Serverless | + +### 7.2 Vercel 部署 + +```text +GitHub 推送 → Vercel 构建钩子 → pnpm build → Next.js 构建 + → 静态资源 + Serverless 函数 → 边缘 CDN 分发 +``` + +**关键设计决策**： +- 独立输出模式，优化 Vercel serverless 支持 +- 符号链接感知的构件复制，处理 monorepo 结构 +- `vercel.json` 路由配置，支持简洁 URL +- 通过 GitHub Actions 工作流实现预览部署 + +### 7.3 CI/CD 流水线 + +| 工作流 | 触发器 | 用途 | +|--------|--------|------| +| `ci.yml` | Push/PR | 构建验证 | +| `release.yml` | Push to main | Changesets NPM 发布 | +| `preview.yml` | PR | Vercel 预览部署 | +| `test-lifecycle.yml` | Push/PR | 全面生命周期测试 | +| `link-check.yml` | PR | 内容链接验证 | + +## 8. 技术栈 + +| 层级 | 技术 | 版本 | +|------|------|------| +| 运行时 | Next.js (App Router) | ^16.1.2 | +| UI 框架 | React (Server Components) | ^19.2.3 | +| 文档引擎 | Fumadocs | ^16.4.7 | +| 样式 | Tailwind CSS | ^4.1.18 | +| 语言 | TypeScript | ^5.9.3 | +| 包管理器 | pnpm | 工作区 monorepo | +| AI 集成 | OpenAI API | ^4.0.0 | +| CLI 框架 | CAC | ^6.7.14 | +| 内容格式 | MDX | 通过 fumadocs-mdx | +| 部署 | Vercel | Serverless/Edge | + +## 9. 安全考虑 + +- **无硬编码密钥**：所有 API 密钥（如 OpenAI）通过环境变量加载 +- **默认 Server Components**：最小化客户端 JavaScript 暴露 +- **内容隔离**：文档内容与渲染引擎分离 +- **依赖管理**：通过 Changesets 自动化管理，锁定版本 + + +本设计文档反映了 ObjectDocs v0.2.12 的当前状态。随着系统演进将持续更新。功能路线图请参阅[开发路线图](/docs/development-plan)。 + diff --git a/content/docs/design.mdx b/content/docs/design.mdx new file mode 100644 index 0000000..12b5450 --- /dev/null +++ b/content/docs/design.mdx @@ -0,0 +1,301 @@ +--- +title: System Design +description: Complete system design document for ObjectDocs — architecture, technical decisions, and component overview. +--- + +import { FileJson, Layers, Cpu, Zap, GitBranch, Package, Globe, Code } from 'lucide-react'; + +# System Design Document + +This document provides a comprehensive technical design overview of ObjectDocs, covering the system architecture, package structure, data flow, and key design decisions. + +**Version**: v0.2.12 | **Last Updated**: 2026-02-08 + +## 1. System Overview + +ObjectDocs is a **metadata-driven documentation engine** built on Next.js and Fumadocs, designed for the ObjectStack low-code ecosystem. It follows a strict **Configuration as Code** philosophy where documentation structure is defined by data (JSON), not code (React). + +### Design Goals + + +} title="Metadata-Driven"> +Navigation, sidebars, and page ordering are defined entirely through `meta.json` files and `docs.site.json` configuration. Content creators never need to touch React code. + +} title="Separation of Concerns"> +The system strictly separates three layers: **Presentation** (React/Next.js site engine), **Configuration** (JSON files), and **Content** (MDX documents). + +} title="Monorepo Architecture"> +The project is organized as a pnpm workspace monorepo with two core packages (`@objectdocs/cli` and `@objectdocs/site`) plus a shared content layer. + +} title="i18n-First"> +Multi-language support is built into the core architecture, with language-specific MDX files and pre-built UI translations for 6 languages. + + + +## 2. Architecture Overview + +### 2.1 High-Level Architecture + +```text +┌─────────────────────────────────────────────────────────┐ +│ ObjectDocs System │ +├──────────────┬──────────────────┬───────────────────────┤ +│ @objectdocs │ @objectdocs │ Content Layer │ +│ /cli │ /site │ │ +│ │ │ │ +│ Commands: │ Next.js 16 + │ content/ │ +│ • init │ Fumadocs 16 │ ├── docs.site.json │ +│ • dev │ │ ├── docs/ │ +│ • build │ App Router │ │ ├── meta.json │ +│ • start │ React Server │ │ ├── index.mdx │ +│ • translate │ Components │ │ └── ... │ +│ │ │ └── public/ │ +├──────────────┼──────────────────┼───────────────────────┤ +│ CLI Layer │ Presentation │ Data Layer │ +│ (Tooling) │ Layer │ (Configuration + │ +│ │ (Rendering) │ Content) │ +└──────────────┴──────────────────┴───────────────────────┘ +``` + +### 2.2 Package Dependency Graph + +```text +Root Workspace (objectdocs v1.0.0) +├── @objectdocs/cli (v0.2.12) +│ ├── depends on: @objectdocs/site (workspace:*) +│ ├── cac (CLI framework) +│ ├── openai (AI translation) +│ └── dotenv (environment config) +└── @objectdocs/site (v0.2.12) + ├── next (^16.1.2) + ├── fumadocs-core (^16.4.7) + ├── fumadocs-ui (^16.4.7) + ├── fumadocs-mdx (^14.2.5) + ├── react (^19.2.3) + ├── tailwindcss (^4.1.18) + └── typescript (^5.9.3) +``` + +## 3. Core Components + +### 3.1 CLI Package (`@objectdocs/cli`) + +The CLI is the primary developer interface for ObjectDocs. Built with the [CAC](https://github.com/cacjs/cac) framework, it provides 5 commands: + +| Command | Purpose | Key Behavior | +|---------|---------|-------------| +| `init` | Initialize a new docs project | Copies `@objectdocs/site` to `content/.fumadocs`, installs deps, updates `.gitignore` | +| `dev` | Start development server | Runs on port 7777, watches `docs.site.json` for changes, syncs public assets | +| `build` | Build for production | Supports both static export (`out/`) and dynamic standalone (`.next/`) modes | +| `start` | Start production server | Static mode uses `serve`, dynamic mode uses Next.js server | +| `translate` | AI-powered translation | Uses OpenAI API, supports `--all` flag, generates language-specific `.mdx` files | + +**Design Decision**: The CLI copies the entire `@objectdocs/site` package into `content/.fumadocs` during init rather than using it as a runtime dependency. This ensures complete isolation between the documentation engine and user content, and allows the site to be customized without affecting the package. + +### 3.2 Site Package (`@objectdocs/site`) + +The site package is a complete Next.js application template that serves as the documentation rendering engine. + +**Key Components**: + +| Component | File | Responsibility | +|-----------|------|---------------| +| Root Layout | `app/layout.tsx` | HTML shell, providers, global styles | +| Language Router | `app/[lang]/layout.tsx` | i18n layout with Fumadocs provider | +| Docs Pages | `app/[lang]/docs/[[...slug]]/page.tsx` | MDX rendering, TOC, navigation | +| Search API | `app/api/search/route.ts` | Full-text search endpoint | +| i18n Config | `lib/i18n.ts` | Language definitions and UI translations | +| Site Config | `lib/config.ts` | Loads and merges `docs.site.json` | +| Source Loader | `lib/source.ts` | Fumadocs content source with i18n | + +### 3.3 Content Layer + +The content layer is the user-facing data that defines the documentation site: + +```text +content/ +├── docs.site.json # Global site configuration +│ ├── branding # Logo, name, theme colors +│ ├── links # Navbar navigation links +│ ├── sidebar # Sidebar behavior config +│ ├── toc # Table of contents settings +│ ├── footer # Footer copyright text +│ ├── page # Per-page features (edit link, last update) +│ ├── content # Content features (math, code theme) +│ ├── i18n # Language configuration +│ └── build # Build mode (export/standalone) +├── public/ # Static assets (images, fonts) +└── docs/ + ├── meta.json # Root navigation structure + ├── index.mdx # Homepage (English) + ├── index.cn.mdx # Homepage (Chinese) + └── getting-started/ + ├── meta.json # Section page ordering + ├── index.mdx # Section landing page + └── ... +``` + +## 4. Data Flow + +### 4.1 Build-Time Data Flow + + + +### Content Discovery +Fumadocs MDX source loader scans the `DOCS_DIR` directory for all `.mdx` files and `meta.json` files. Files are organized by language suffix (e.g., `.cn.mdx` for Chinese). + +### Configuration Merge +The site reads `docs.site.json` from the content directory and merges it with default configuration values in `lib/config.ts`. This produces the complete site configuration. + +### Navigation Tree Construction +`meta.json` files in each directory define the page ordering and section titles. Fumadocs builds a hierarchical navigation tree from these files. + +### MDX Compilation +Each `.mdx` file is compiled through the Fumadocs MDX pipeline with remark/rehype plugins, producing React Server Components. + +### Static Generation +Next.js App Router generates static pages for each route. In standalone mode, pages can be server-rendered with ISR support. + + + +### 4.2 Runtime Data Flow + +```text +User Request → Next.js Router → Language Detection → Page Resolution + → MDX Content Rendering (RSC) → Fumadocs UI Layout → HTML Response +``` + +### 4.3 Translation Data Flow + +```text +Source MDX → CLI translate command → OpenAI API → Translated MDX + → Language-specific file (e.g., .cn.mdx) → Content Discovery +``` + +## 5. Configuration System Design + +### 5.1 `docs.site.json` Schema + +The site configuration file supports the following sections: + +```json +{ + "site": { + "title": "Site title", + "description": "Site description", + "url": "https://example.com", + "favicon": "/favicon.ico" + }, + "branding": { + "name": "Brand Name", + "logo": { "light": "/logo-light.svg", "dark": "/logo-dark.svg" }, + "themeColor": "#7c3aed", + "borderRadius": "0.5rem" + }, + "links": [{ "text": "Home", "url": "/" }], + "sidebar": { "collapsible": true, "defaultOpenLevel": 1 }, + "toc": { "enabled": true, "depth": 3 }, + "footer": { "copyright": "© 2026" }, + "page": { + "lastUpdate": true, + "editOnGithub": { "owner": "org", "repo": "repo" } + }, + "content": { "codeTheme": "vesper", "imageZoom": true }, + "i18n": { + "defaultLanguage": "en", + "languages": ["en", "cn"] + }, + "build": { "mode": "export" } +} +``` + +### 5.2 `meta.json` Schema + +Each directory can contain a `meta.json` to control navigation: + +```json +{ + "title": "Section Title", + "pages": ["page-a", "page-b", "sub-directory"] +} +``` + +**Key Rule**: Sidebar navigation is **never** defined in React components. All navigation structure changes go through `meta.json` files. + +## 6. i18n Architecture + +### 6.1 Supported Languages + +| Code | Language | UI Translations | +|------|----------|----------------| +| `en` | English | ✅ Complete | +| `cn` | 中文 (Chinese) | ✅ Complete | +| `ja` | 日本語 (Japanese) | ✅ Complete | +| `fr` | Français (French) | ✅ Complete | +| `de` | Deutsch (German) | ✅ Complete | +| `es` | Español (Spanish) | ✅ Complete | + +### 6.2 Content Translation Strategy + +- **File-based**: Each language has its own MDX file (e.g., `index.mdx` for English, `index.cn.mdx` for Chinese) +- **Fallback**: If a translated file doesn't exist, the default language version is used +- **AI Translation**: The `translate` CLI command uses OpenAI to generate translations automatically +- **URL Routing**: Language prefix in URL path (`/en/docs/...`, `/cn/docs/...`) + +## 7. Deployment Design + +### 7.1 Build Modes + +| Mode | Output | Use Case | +|------|--------|----------| +| `export` (Static) | `out/` directory with HTML/CSS/JS | CDN hosting, GitHub Pages, Vercel static | +| `standalone` (Dynamic) | `.next/` with Node.js server | ISR, SSR, API routes, Vercel serverless | + +### 7.2 Vercel Deployment + +```text +GitHub Push → Vercel Build Hook → pnpm build → Next.js Build + → Static Assets + Serverless Functions → Edge CDN Distribution +``` + +**Key Design Decisions**: +- Standalone output mode for optimal Vercel serverless support +- Symlink-aware artifact copying to handle monorepo structures +- `vercel.json` routing configuration for clean URLs +- Preview deployments via GitHub Actions workflow + +### 7.3 CI/CD Pipeline + +| Workflow | Trigger | Purpose | +|----------|---------|---------| +| `ci.yml` | Push/PR | Build validation | +| `release.yml` | Push to main | Changesets NPM publishing | +| `preview.yml` | PR | Vercel preview deployment | +| `test-lifecycle.yml` | Push/PR | Full lifecycle testing | +| `link-check.yml` | PR | Content link validation | + +## 8. Technology Stack + +| Layer | Technology | Version | +|-------|-----------|---------| +| Runtime | Next.js (App Router) | ^16.1.2 | +| UI Framework | React (Server Components) | ^19.2.3 | +| Documentation Engine | Fumadocs | ^16.4.7 | +| Styling | Tailwind CSS | ^4.1.18 | +| Language | TypeScript | ^5.9.3 | +| Package Manager | pnpm | Workspace monorepo | +| AI Integration | OpenAI API | ^4.0.0 | +| CLI Framework | CAC | ^6.7.14 | +| Content Format | MDX | Via fumadocs-mdx | +| Deployment | Vercel | Serverless/Edge | + +## 9. Security Considerations + +- **No hardcoded secrets**: All API keys (e.g., OpenAI) are loaded via environment variables +- **Server Components by default**: Minimizes client-side JavaScript exposure +- **Content isolation**: Documentation content is separated from the rendering engine +- **Dependency management**: Automated via Changesets with locked versions + + +This design document reflects the current state of ObjectDocs v0.2.12. It will be updated as the system evolves. For the feature roadmap, see the [Development Roadmap](/docs/development-plan). + diff --git a/content/docs/development-plan.cn.mdx b/content/docs/development-plan.cn.mdx new file mode 100644 index 0000000..281d901 --- /dev/null +++ b/content/docs/development-plan.cn.mdx @@ -0,0 +1,274 @@ +--- +title: 开发路线图 +description: ObjectDocs 开发计划和功能路线图，基于 GitHub 的文档系统与 Vercel 部署集成 +--- + +import { Code, Sparkles, Globe, Shield, GitBranch, Rocket, CheckCircle } from 'lucide-react'; + +# ObjectDocs 开发路线图 + +本文档概述了 ObjectDocs 的开发计划和功能路线图。ObjectDocs 是一个面向 GitHub 的文档引擎，针对 Vercel 部署进行了优化。 + +**当前版本**: v0.2.12 | **最后更新**: 2026-02-08 + +## 🎯 核心使命 + +ObjectDocs 专为 **基于 GitHub 的仓库文档** 构建，与 **Vercel 部署** 无缝集成。核心目标： + +1. **Git 原生工作流**: 利用 GitHub 的协作功能（PR、Review、Issues）作为内容管理系统 +2. **零配置部署**: 推送到 GitHub，自动部署到 Vercel，享有最优的缓存和 CDN 分发 +3. **开发者优先**: 将文档视为代码——版本控制、同行评审、CI/CD 集成 + +## 📊 整体进度概览 + +| 软件包 | 版本 | 状态 | +|--------|------|------| +| `@objectdocs/cli` | v0.2.12 | ✅ 稳定 | +| `@objectdocs/site` | v0.2.12 | ✅ 稳定 | +| 根工作区 | v1.0.0 | ✅ 活跃 | + +| 阶段 | 状态 | 进度 | +|------|------|------| +| 第一阶段：核心平台与部署 | ✅ 基本完成 | ~80% | +| 第二阶段：开发者体验 | 🟡 进行中 | ~30% | +| 第三阶段：高级功能 | ⬚ 规划中 | ~0% | + +## 📅 开发路线图 + +### 第一阶段：核心平台与部署（2025 Q4 – 2026 Q1） + + +} title="GitHub 原生功能"> + +**目标**: 与 GitHub 仓库工作流深度集成 + +- [x] GitHub Actions 自动化构建和检查工作流（CI、发布、预览、测试、链接检查） +- [x] 通过 Vercel 集成的 PR 预览部署（`preview.yml` 工作流） +- [x] 基于 Changesets 的版本化发布和自动 NPM 发布 +- [ ] 用于自动文档同步的 GitHub App +- [ ] 用于文档反馈的 GitHub Issues 集成 +- [ ] 基于分支的文档版本管理 + +**已实现**: +- CI 工作流 (`ci.yml`)：push/PR 时的构建验证 +- 发布工作流 (`release.yml`)：基于 Changesets 的语义化版本管理 +- 预览工作流 (`preview.yml`)：PR 预览部署 +- 测试工作流 (`test-lifecycle.yml`)：全面测试 +- 链接检查工作流 (`link-check.yml`)：内容验证 + + + +} title="Vercel 部署流水线"> + +**目标**: 针对 Vercel 的边缘网络和构建系统优化 + +- [x] 独立输出模式支持 Vercel/Docker 部署 +- [x] 通过 GitHub Actions 实现生产部署自动化 +- [x] `vercel.json` 路由优化配置 +- [x] 每个 PR 的预览部署 +- [x] Monorepo 感知的构建配置 +- [ ] ISR（增量静态再生成）配置 +- [ ] 用于动态内容的 Edge Functions +- [ ] 用于 A/B 测试的 Edge Middleware + +**已实现**: +- `next.config.mjs` 独立输出模式 +- 符号链接感知的构件复制，兼容 Vercel +- 静态导出和动态（独立）两种构建模式 +- `vercel.json` 部署配置 + + + + +### 第二阶段：增强开发者体验（2026 Q1 – Q2） + + +} title="CLI 与自动化工具"> + +**目标**: 简化从仓库到文档的工作流 + +- [x] 功能完整的 ObjectDocs CLI，包含 5 个命令（init、dev、build、start、translate） +- [x] 零配置项目初始化（`objectdocs init`） +- [x] 支持配置监听的热重载开发服务器 +- [x] 静态和动态两种构建模式 +- [ ] 从 README 文件自动迁移内容 +- [ ] 从仓库文件提取代码片段 +- [ ] 从源代码生成 API 文档 +- [ ] 从提交记录自动生成更新日志 + +**已实现**: +- `init` — 复制站点模板、安装依赖、配置 `.gitignore` +- `dev` — 在端口 7777 启动开发服务器，监听 `docs.site.json` 并同步资源 +- `build` — 静态/动态构建及构件处理 +- `start` — 生产服务器（静态用 `serve`，动态用 Next.js） +- `translate` — OpenAI 驱动的批量翻译，支持 `--all` 参数 + + + +} title="AI 驱动的文档助手"> + +**目标**: 利用 AI 提升文档质量 + +- [x] 基于 OpenAI 集成的自动翻译支持 +- [x] 多语言文件生成（`.cn.mdx`、`.ja.mdx` 等） +- [x] CI 兼容的翻译支持（环境变量配置） +- [ ] 基于语义理解的 AI 搜索 +- [ ] 从代码注释自动生成文档 +- [ ] 基于仓库的智能内容建议 +- [ ] 文档质量评分和改进建议 + +**已实现**: +- `translate` 命令中的 OpenAI API 集成 +- 支持 `--all` 参数翻译所有内容 +- CI 流水线的环境变量配置 + + + + +### 第三阶段：协作与高级功能（2026 Q3+） + + +} title="多仓库文档中心"> + +**目标**: 跨多个 GitHub 仓库的统一文档 + +- [ ] 跨仓库搜索和导航 +- [ ] 组织级别的文档门户 +- [ ] 仓库级别的访问控制 +- [ ] 从多个来源自动聚合 +- [ ] 跨仓库的统一版本管理 + +**技术规划**: +- GitHub Organization API 集成 +- 仓库发现和索引 +- GitHub Teams 访问控制支持 +- 聚合搜索索引 + + + +} title="GitHub 企业级功能"> + +**目标**: 支持 GitHub Enterprise 和高级工作流 + +- [ ] 兼容 GitHub Enterprise Server +- [ ] 通过 GitHub 的 SAML/SSO 集成 +- [ ] 细粒度仓库权限管理 +- [ ] 文档变更审计日志 +- [ ] GitHub Advanced Security 集成 + +**技术规划**: +- 支持 GitHub Enterprise API 端点 +- 集成 GitHub OIDC 提供者 +- 使用 GitHub 权限模型进行访问控制 +- 基于 Webhook 的审计追踪 + + + + +## 🔧 技术基础设施 + +### GitHub 工作流优化 +- [x] GitHub Actions 持续部署（CI、发布、预览） +- [x] PR 检查和状态徽章 +- [x] 基于 Changesets 的自动发布流程 +- [ ] 通过 Dependabot 自动更新依赖 +- [ ] 从 git 标签自动生成发布说明 +- [ ] 文档请求的 Issue 模板 + +### 内容与国际化系统 +- [x] 完整的 i18n 支持，6 种语言（EN、CN、JA、FR、DE、ES） +- [x] 语言特定的 MDX 文件路由（`.en.mdx`、`.cn.mdx`） +- [x] 所有支持语言的预置 UI 翻译 +- [x] 可配置的默认语言 +- [x] AI 驱动的翻译 CLI 命令 + +### Vercel 平台功能 +- [x] 独立输出模式用于无服务器部署 +- [x] 搜索 API 端点（`/api/search`） +- [ ] Edge Config 动态功能标志 +- [ ] Vercel KV 缓存层 +- [ ] Web Analytics 集成 +- [ ] Edge Middleware A/B 测试 + +### 性能与 SEO +- [x] React Server Components 优化性能 +- [x] MDX 静态编译 +- [ ] Lighthouse 评分优化（目标 95+） +- [ ] Core Web Vitals 监控 +- [ ] 自动 Sitemap 生成 +- [ ] OpenGraph 元数据自动化 +- [ ] 搜索引擎结构化数据 + +## 🚀 部署架构 + +### 推荐配置 +```yaml +仓库结构: +├── content/ # 文档 MDX 文件 +│ ├── docs/ # MDX 页面和 meta.json +│ └── docs.site.json # 站点配置 +├── .github/ +│ └── workflows/ # CI/CD 自动化 +├── vercel.json # 部署配置 +└── package.json # 根工作区 +``` + +### CI/CD 流水线 +1. **推送到 GitHub** → 触发 CI 构建验证 +2. **创建 PR** → 通过 Vercel 生成预览部署 +3. **合并到 main** → 自动部署到生产环境 +4. **Changeset 合并** → 自动 NPM 发布 + +## 🎯 当前工作重点（2026 Q1） + +### 活跃开发任务 + +1. **设计文档 (✅ 已完成)** + - 目标：2026 年 2 月 + - 状态：已完成 + - 交付物：系统设计文档、软件包概览、更新后的路线图 + +2. **ISR 和 Edge Functions (🟡 进行中)** + - 目标：2026 年 3 月 + - 状态：规划中 + - 交付物：ISR 配置、Edge 中间件、缓存策略 + +3. **内容迁移工具 (🟡 规划中)** + - 目标：2026 年 Q2 + - 状态：规划中 + - 交付物：README 迁移、代码片段提取、API 文档生成 + +4. **GitHub App 开发 (⬚ 规划中)** + - 目标：2026 年 Q3 + - 状态：未开始 + - 交付物：OAuth 应用、Webhook 处理器、API 集成 + +## 💡 社区与贡献 + +### GitHub 优先的协作方式 +- 提交 Issue 进行功能请求和 Bug 报告 +- 创建 Pull Request 改进文档 +- 参与 GitHub Discussions +- Star 和 Watch 仓库获取更新 + +### 集成示例 +- [GitHub Actions 工作流模板](https://github.com/objectstack-ai/objectdocs/tree/main/.github/workflows) +- [Vercel 配置示例](https://github.com/objectstack-ai/objectdocs/blob/main/vercel.json) +- [一键部署](https://vercel.com/new/clone?repository-url=https://github.com/objectstack-ai/objectdocs) + + +此路线图是动态的，将根据社区反馈和 GitHub/Vercel 平台更新进行调整。通过 GitHub Projects 面板跟踪进度。 + + +## 🔄 更新日志 + +| 日期 | 变更内容 | 作者 | +|------|---------|------| +| 2026-02-08 | 更新进度状态，标记已完成功能，新增软件包概览 | 团队 | +| 2026-01-18 | 创建以 GitHub-Vercel 集成为重点的开发路线图 | 团队 | + +--- + + +**注意**：时间线和功能可能会根据团队资源、社区需求和平台能力进行调整。关注仓库获取实时更新。 + diff --git a/content/docs/development-plan.mdx b/content/docs/development-plan.mdx index 996fcef..5645cf0 100644 --- a/content/docs/development-plan.mdx +++ b/content/docs/development-plan.mdx @@ -3,12 +3,14 @@ title: Development Roadmap description: ObjectDocs development plan and feature roadmap for GitHub-based documentation with Vercel deployment --- -import { Code, Sparkles, Globe, Shield, GitBranch, Rocket } from 'lucide-react'; +import { Code, Sparkles, Globe, Shield, GitBranch, Rocket, CheckCircle } from 'lucide-react'; # ObjectDocs Development Roadmap This document outlines the development plan and feature roadmap for ObjectDocs, a GitHub-native documentation engine optimized for Vercel deployment. +**Current Version**: v0.2.12 | **Last Updated**: 2026-02-08 + ## 🎯 Core Mission ObjectDocs is purpose-built for **GitHub-based repository documentation** with seamless **Vercel deployment integration**. Our core objectives: @@ -17,26 +19,42 @@ ObjectDocs is purpose-built for **GitHub-based repository documentation** with s 2. **Zero-Config Deployment**: Push to GitHub, auto-deploy to Vercel with optimal caching and CDN distribution 3. **Developer-First**: Treat documentation as code—version controlled, peer-reviewed, and CI/CD integrated +## 📊 Overall Progress Summary + +| Package | Version | Status | +|---------|---------|--------| +| `@objectdocs/cli` | v0.2.12 | ✅ Stable | +| `@objectdocs/site` | v0.2.12 | ✅ Stable | +| Root Workspace | v1.0.0 | ✅ Active | + +| Phase | Status | Progress | +|-------|--------|----------| +| Phase 1: Core Platform & Deployment | ✅ Mostly Complete | ~80% | +| Phase 2: Developer Experience | 🟡 In Progress | ~30% | +| Phase 3: Advanced Features | ⬚ Planned | ~0% | + ## 📅 Development Roadmap -### Phase 1: GitHub Integration & Vercel Optimization (Q1 2026) +### Phase 1: Core Platform & Deployment (Q4 2025 – Q1 2026) -} title="GitHub-Native Features"> +} title="GitHub-Native Features"> **Goal**: Deep integration with GitHub repository workflows +- [x] GitHub Actions workflows for automated builds and checks (CI, release, preview, test-lifecycle, link-check) +- [x] PR preview deployments via Vercel integration (`preview.yml` workflow) +- [x] Changesets-based versioned releases with automated NPM publishing - [ ] GitHub App for automated documentation syncing -- [ ] PR preview deployments via Vercel integration - [ ] GitHub Issues integration for documentation feedback -- [ ] GitHub Actions workflows for automated builds and checks - [ ] Branch-based documentation versioning -**Technical Implementation**: -- Use GitHub REST/GraphQL APIs for content fetching -- Implement Vercel Git integration hooks -- Create reusable GitHub Actions for linting and validation -- Support monorepo documentation with git submodules +**Implemented**: +- CI workflow (`ci.yml`) for build validation on push/PR +- Release workflow (`release.yml`) with Changesets for semantic versioning +- Preview workflow (`preview.yml`) for PR preview deployments +- Test lifecycle workflow (`test-lifecycle.yml`) for comprehensive testing +- Link check workflow (`link-check.yml`) for content validation @@ -44,40 +62,46 @@ ObjectDocs is purpose-built for **GitHub-based repository documentation** with s **Goal**: Optimize for Vercel's edge network and build system +- [x] Standalone output mode for Vercel/Docker support +- [x] Production deployment automation via GitHub Actions +- [x] `vercel.json` configuration for optimal routing +- [x] Preview deployments for every PR +- [x] Monorepo-aware build configuration - [ ] ISR (Incremental Static Regeneration) configuration - [ ] Edge Functions for dynamic content -- [ ] Optimal caching strategies (stale-while-revalidate) -- [ ] Preview deployments for every PR -- [ ] Production deployment automation +- [ ] Edge Middleware for A/B testing -**Technical Implementation**: -- Configure `vercel.json` for optimal routing -- Implement edge middleware for A/B testing -- Use Vercel Analytics for performance monitoring -- Integrate Vercel Image Optimization -- Set up custom domains with SSL automation +**Implemented**: +- `next.config.mjs` with standalone output mode +- Symlink-aware artifact copying for Vercel compatibility +- Both static export and dynamic (standalone) build modes +- Vercel deployment configuration in `vercel.json` -### Phase 2: Enhanced Developer Experience (Q2 2026) +### Phase 2: Enhanced Developer Experience (Q1 – Q2 2026) } title="CLI & Automation Tools"> **Goal**: Streamline repository-to-documentation workflow -- [ ] Enhanced ObjectDocs CLI with GitHub integration +- [x] Full-featured ObjectDocs CLI with 5 commands (init, dev, build, start, translate) +- [x] Zero-config project initialization (`objectdocs init`) +- [x] Hot-reload development server with config watching +- [x] Static and dynamic build modes - [ ] Automated content migration from README files - [ ] Code snippet extraction from repository files - [ ] API documentation generation from source code - [ ] Automated changelog generation from commits -**Technical Implementation**: -- Extend `@objectdocs/cli` with GitHub API features -- Use TypeScript AST parsing for API extraction -- Integrate conventional commits for changelog -- Support multi-repo documentation aggregation +**Implemented**: +- `init` — Copies site template, installs dependencies, configures `.gitignore` +- `dev` — Dev server on port 7777 with `docs.site.json` watching and asset sync +- `build` — Static/dynamic builds with artifact handling +- `start` — Production server (static via `serve` or dynamic via Next.js) +- `translate` — OpenAI-powered batch translation with `--all` flag @@ -85,22 +109,23 @@ ObjectDocs is purpose-built for **GitHub-based repository documentation** with s **Goal**: Leverage AI to enhance documentation quality +- [x] Automated translation support via OpenAI integration +- [x] Multi-language file generation (`.cn.mdx`, `.ja.mdx`, etc.) +- [x] CI-compatible translation with environment variables - [ ] AI-powered search with semantic understanding - [ ] Auto-generate documentation from code comments - [ ] Intelligent content suggestions based on repository - [ ] Documentation quality scoring and recommendations -- [ ] Automated translation support -**Technical Implementation**: -- Integrate OpenAI API or local LLM models -- Use vector databases (Pinecone/Weaviate) for semantic search -- Implement Markdown AST analysis for content quality -- Support embeddings for documentation similarity +**Implemented**: +- OpenAI API integration in `translate` command +- Support for `--all` flag to translate all content +- Environment variable configuration for CI pipelines -### Phase 3: Collaboration & Advanced Features (Q3 2026) +### Phase 3: Collaboration & Advanced Features (Q3 2026+) } title="Multi-Repository Documentation Hub"> @@ -113,7 +138,7 @@ ObjectDocs is purpose-built for **GitHub-based repository documentation** with s - [ ] Automated aggregation from multiple sources - [ ] Unified version management across repos -**Technical Implementation**: +**Technical Plan**: - GitHub Organization API integration - Implement repository discovery and indexing - Support GitHub Teams for access control @@ -131,7 +156,7 @@ ObjectDocs is purpose-built for **GitHub-based repository documentation** with s - [ ] Audit logging for documentation changes - [ ] GitHub Advanced Security integration -**Technical Implementation**: +**Technical Plan**: - Support GitHub Enterprise API endpoints - Integrate with GitHub's OIDC provider - Use GitHub's permission model for access control @@ -143,24 +168,35 @@ ObjectDocs is purpose-built for **GitHub-based repository documentation** with s ## 🔧 Technical Infrastructure ### GitHub Workflow Optimization +- [x] GitHub Actions for continuous deployment (CI, release, preview) +- [x] Pull request checks and status badges +- [x] Automated release process via Changesets - [ ] Automated dependency updates via Dependabot -- [ ] GitHub Actions for continuous deployment -- [ ] Pull request checks and status badges - [ ] Automated release notes from git tags - [ ] Issue templates for documentation requests +### Content & i18n System +- [x] Full i18n support with 6 languages (EN, CN, JA, FR, DE, ES) +- [x] Language-specific MDX file routing (`.en.mdx`, `.cn.mdx`) +- [x] Pre-built UI translations for all supported languages +- [x] Configurable default language +- [x] AI-powered translation CLI command + ### Vercel Platform Features +- [x] Standalone output mode for serverless deployment +- [x] Search API endpoint (`/api/search`) - [ ] Edge Config for dynamic feature flags - [ ] Vercel KV for caching layer -- [ ] Serverless Functions for API endpoints - [ ] Web Analytics integration - [ ] A/B testing with Edge Middleware ### Performance & SEO +- [x] React Server Components for optimal performance +- [x] MDX static compilation - [ ] Lighthouse score optimization (95+ target) - [ ] Core Web Vitals monitoring -- [ ] Automatic sitemap generation from git history -- [ ] OpenGraph metadata from repository info +- [ ] Automatic sitemap generation +- [ ] OpenGraph metadata automation - [ ] Structured data for search engines ## 🚀 Deployment Architecture @@ -169,44 +205,43 @@ ObjectDocs is purpose-built for **GitHub-based repository documentation** with s ```yaml Repository Structure: ├── content/ # Documentation MDX files +│ ├── docs/ # MDX pages and meta.json +│ └── docs.site.json # Site configuration ├── .github/ │ └── workflows/ # CI/CD automation ├── vercel.json # Deployment configuration -└── docs.site.json # Site metadata +└── package.json # Root workspace ``` ### CI/CD Pipeline -1. **Push to GitHub** → Triggers Vercel build -2. **PR Created** → Generates preview deployment +1. **Push to GitHub** → Triggers CI build validation +2. **PR Created** → Generates preview deployment via Vercel 3. **Merge to main** → Auto-deploys to production -4. **Git Tag** → Creates versioned documentation - -## 📊 Priority Matrix - -| Priority | Description | Target | -|----------|-------------|--------| -| 🔴 Critical | GitHub integration, Vercel deployment | Q1 2026 | -| 🟡 High | Developer tools, performance optimization | Q2 2026 | -| 🟢 Medium | Advanced features, enterprise support | Q3 2026+ | +4. **Changeset merged** → Automated NPM release ## 🎯 Current Focus (Q1 2026) ### Active Development Tasks -1. **Vercel Deployment Optimization (🔴 Critical)** +1. **Design Documentation (✅ Complete)** - Target: February 2026 - - Status: In Progress - - Deliverables: ISR configuration, edge functions, caching strategy + - Status: Complete + - Deliverables: System design document, package overview, updated roadmap -2. **GitHub App Development (🔴 Critical)** +2. **ISR & Edge Functions (🟡 In Progress)** - Target: March 2026 - Status: In Planning - - Deliverables: OAuth app, webhook handlers, API integration + - Deliverables: ISR configuration, edge middleware, caching strategy -3. **CLI Enhancement (🟡 High)** - - Target: March 2026 +3. **Content Migration Tools (🟡 Planned)** + - Target: Q2 2026 - Status: In Planning - - Deliverables: GitHub integration commands, automation scripts + - Deliverables: README migration, code snippet extraction, API doc generation + +4. **GitHub App Development (⬚ Planned)** + - Target: Q3 2026 + - Status: Not Started + - Deliverables: OAuth app, webhook handlers, API integration ## 💡 Community & Contribution @@ -229,6 +264,7 @@ This roadmap is dynamic and will evolve based on community feedback and GitHub/V | Date | Changes | Author | |------|---------|--------| +| 2026-02-08 | Updated progress status, marked completed features, added package overview | Team | | 2026-01-18 | Created development roadmap focused on GitHub-Vercel integration | Team | --- diff --git a/content/docs/meta.json b/content/docs/meta.json index a5bc454..5ac96cc 100644 --- a/content/docs/meta.json +++ b/content/docs/meta.json @@ -3,6 +3,8 @@ "pages": [ "index", "getting-started", + "packages", + "design", "components", "integrations", "development-plan" diff --git a/content/docs/packages.cn.mdx b/content/docs/packages.cn.mdx new file mode 100644 index 0000000..1794e18 --- /dev/null +++ b/content/docs/packages.cn.mdx @@ -0,0 +1,290 @@ +--- +title: 软件包概览 +description: ObjectDocs 软件包完整概览，包含功能、开发状态和版本历史。 +--- + +import { Package, Terminal, Layout, Zap, CheckCircle, Clock } from 'lucide-react'; + +# 软件包概览 + +ObjectDocs 以 **pnpm 工作区 monorepo** 组织，包含两个核心软件包。本文档详细介绍每个软件包的功能、当前状态和开发历史。 + +**当前版本**: v0.2.12 | **最后更新**: 2026-02-08 + +## 软件包概要 + +| 软件包 | 版本 | 描述 | 状态 | +|--------|------|------|------| +| `@objectdocs/cli` | v0.2.12 | 构建和管理文档的命令行工具 | ✅ 稳定 | +| `@objectdocs/site` | v0.2.12 | Next.js 文档站点模板和渲染引擎 | ✅ 稳定 | + +## @objectdocs/cli + + +} title="CLI 工具"> + +ObjectDocs 的主要开发者接口。提供初始化、开发、构建和部署文档站点的命令。 + +- **框架**: CAC（命令行框架） +- **语言**: JavaScript/Node.js (ESM) +- **入口**: `bin/cli.mjs` + + + + +### 命令 + + + +### `objectdocs init` + +通过复制站点模板并设置开发环境来初始化新的文档项目。 + +**功能**: +- 将 `@objectdocs/site` 包复制到 `content/.fumadocs` +- 创建 `content/package.json`，包含 dev/build/start 脚本 +- 在 `content/.fumadocs` 中安装依赖 +- 更新 `.gitignore` 排除生成的文件 + +### `objectdocs dev [docsDir]` + +启动带热重载的开发服务器。 + +**功能**: +- 默认端口：7777（可配置） +- 监听 `docs.site.json` 变更并自动重启 +- 同步公共资源到站点引擎 +- 设置 `DOCS_DIR` 环境变量 + +### `objectdocs build [docsDir]` + +构建文档站点用于生产环境。 + +**功能**: +- 支持静态导出（`out/` 目录）和动态独立（`.next/`）模式 +- 复制配置和公共资源 +- 符号链接感知的构件复制，兼容 Vercel + +### `objectdocs start` + +启动生产服务器。 + +**功能**: +- 静态模式：使用 `serve` 从 `out/` 目录提供服务 +- 动态模式：运行 Next.js 生产服务器 +- 可配置端口 + +### `objectdocs translate` + +使用 OpenAI 的 AI 驱动内容翻译。 + +**功能**: +- 将 MDX 内容翻译为配置的语言 +- `--all` 参数用于批量翻译 +- CI 兼容，支持环境变量配置 +- 生成语言特定文件（如 `.cn.mdx`、`.ja.mdx`） + + + +### 依赖 + +| 依赖 | 版本 | 用途 | +|------|------|------| +| `@objectdocs/site` | workspace:* | 初始化用的站点模板 | +| `cac` | ^6.7.14 | CLI 框架 | +| `openai` | ^4.0.0 | AI 驱动的翻译 | +| `dotenv` | ^16.4.5 | 环境变量加载 | +| `typescript` | ^5.9.3 | TypeScript 支持 | + +### 功能状态 + +| 功能 | 状态 | 备注 | +|------|------|------| +| 项目初始化 | ✅ 已完成 | 完整的 `init` 工作流 | +| 开发服务器 | ✅ 已完成 | 热重载、配置监听 | +| 生产构建 | ✅ 已完成 | 静态 + 动态模式 | +| 生产服务器 | ✅ 已完成 | 静态 + 动态服务 | +| AI 翻译 | ✅ 已完成 | OpenAI 集成 | +| GitHub 集成 | ⬚ 规划中 | 第二阶段 | +| README 迁移 | ⬚ 规划中 | 第二阶段 | +| API 文档生成 | ⬚ 规划中 | 第二阶段 | + +--- + +## @objectdocs/site + + +} title="站点模板"> + +完整的 Next.js 应用模板，作为文档渲染引擎。基于 Fumadocs 构建，完整支持国际化。 + +- **框架**: Next.js 16 (App Router) + Fumadocs 16 +- **样式**: Tailwind CSS 4 +- **语言**: TypeScript +- **React**: v19 (Server Components) + + + + +### 核心功能 + + +} title="内容渲染"> + +- MDX 编译，支持 remark/rehype 插件 +- 代码语法高亮（Vesper 主题） +- 图片缩放功能 +- 内置组件：Callout、Card、Cards、Steps、Step +- 自动生成目录 + + +} title="站点引擎"> + +- 基于文件系统的路由 +- 全文搜索 API 端点 +- `meta.json` 驱动的导航树 +- 可配置的侧边栏、导航栏和页脚 +- 深色模式支持 + + + + +### 架构 + +| 组件 | 路径 | 描述 | +|------|------|------| +| 根布局 | `app/layout.tsx` | HTML 外壳、全局 Provider | +| 语言路由 | `app/[lang]/layout.tsx` | i18n 布局与 Fumadocs | +| 文档页面 | `app/[lang]/docs/[[...slug]]/page.tsx` | 动态 MDX 页面渲染 | +| 首页重定向 | `app/[lang]/page.tsx` | 重定向到文档根路径 | +| 搜索 API | `app/api/search/route.ts` | 全文搜索端点 | +| i18n 系统 | `lib/i18n.ts` | 6 语言支持及 UI 翻译 | +| 配置加载器 | `lib/config.ts` | `docs.site.json` 解析和默认值 | +| 源管理器 | `lib/source.ts` | 带 i18n 的 Fumadocs 内容源 | +| MDX 组件 | `mdx-components.tsx` | 自定义组件注册表 | +| 源配置 | `source.config.ts` | 内容目录和 MDX 插件配置 | + +### 国际化支持 + +6 种语言的预置 UI 翻译： + +| 语言 | 代码 | 目录标签 | 搜索 | 最后更新 | +|------|------|---------|------|---------| +| English | `en` | "On this page" | "Search" | "Last updated on" | +| 中文 | `cn` | "目录" | "搜索" | "最后更新于" | +| 日本語 | `ja` | "目次" | "検索" | "最終更新" | +| Français | `fr` | "Sur cette page" | "Rechercher" | "Dernière mise à jour" | +| Deutsch | `de` | "Auf dieser Seite" | "Suchen" | "Zuletzt aktualisiert am" | +| Español | `es` | "En esta página" | "Buscar" | "Última actualización" | + +### 配置选项 + +站点从 `docs.site.json` 读取配置，支持： + +- **站点元数据**：标题、描述、URL、图标 +- **品牌**：名称、Logo（明/暗）、主题色、边框圆角 +- **导航**：导航栏链接，含文本、URL、图标、外部标记 +- **侧边栏**：可折叠、预加载、默认展开层级、标签 +- **目录**：启用、深度 +- **页脚**：版权文本 +- **页面功能**：最后更新时间戳、在 GitHub 上编辑链接 +- **内容**：代码主题、图片缩放、数学公式支持 +- **国际化**：默认语言、语言列表 +- **构建**：模式（export/standalone） + +### 依赖 + +| 依赖 | 版本 | 用途 | +|------|------|------| +| `next` | ^16.1.2 | 应用框架 | +| `react` / `react-dom` | ^19.2.3 | UI 渲染 | +| `fumadocs-core` | ^16.4.7 | 文档引擎核心 | +| `fumadocs-ui` | ^16.4.7 | 文档 UI 组件 | +| `fumadocs-mdx` | ^14.2.5 | MDX 内容处理 | +| `tailwindcss` | ^4.1.18 | 实用优先 CSS | +| `typescript` | ^5.9.3 | 类型安全 | +| `openai` | ^4.0.0 | AI 功能 | +| `lucide-react` | ^0.562.0 | 图标库 | + +### 功能状态 + +| 功能 | 状态 | 备注 | +|------|------|------| +| MDX 渲染 | ✅ 已完成 | 完整的 Fumadocs 管道 | +| 国际化（6 种语言） | ✅ 已完成 | 基于文件 + UI 翻译 | +| 全文搜索 | ✅ 已完成 | API 端点 | +| 深色模式 | ✅ 已完成 | 通过 Fumadocs UI | +| 代码高亮 | ✅ 已完成 | Vesper 主题 | +| 图片缩放 | ✅ 已完成 | 可配置 | +| 独立输出 | ✅ 已完成 | Vercel/Docker 就绪 | +| 静态导出 | ✅ 已完成 | CDN 可部署 | +| 配置系统 | ✅ 已完成 | `docs.site.json` | +| ISR 支持 | ⬚ 规划中 | 第一阶段 | +| Edge Functions | ⬚ 规划中 | 第一阶段 | +| 数学渲染 | ⬚ 规划中 | 配置已存在，未启用 | + +--- + +## 版本历史 + +### v0.2.12（最新） +- 维护更新补丁发布 + +### v0.2.11 +- 修复：处理构建复制过程中的断裂符号链接，防止 Vercel 上的 ENOENT 错误 + +### v0.2.10 +- 新增：启用独立输出模式，更好支持 Vercel/Docker 部署 + +### v0.2.9 +- 修复：在 `tsconfig.json` 中添加 `.source` 路径别名以解析生成的文件 + +### v0.2.8 +- 修复：复制 `.next` 目录时使用 `dereference: true` 展开所有符号链接 + +### v0.2.7 +- 修复：使用相对导入替代生成内容的别名，避免 monorepo 中的别名解析问题 + +### v0.2.6 +- 修复：复制 `.next` 目录替代符号链接，支持 Vercel 部署 + +### v0.2.5 +- 优化：添加 `transpilePackages` 配置修复 monorepo 模块解析 + +### v0.2.4 +- 修复：重命名 `proxy.ts` 为 `middleware.ts`，修复 Next.js 16 构建错误 + +### v0.2.3 +- 修复：更新包元数据用于发布 + +### v0.2.2 +- 文档：更新 README，修正配置文件名称 + +### v0.2.1 +- Bug 修复和改进 + +### v0.2.0 +- 首次发布：基于 Next.js 14 和 Fumadocs 构建的现代文档引擎 + +### v0.1.0 +- 首次发布，包含元数据驱动架构、低代码组件嵌入、企业级 UI、多产品支持 + +--- + +## 入门模板 + +`examples/starter/` 中提供了示例入门模板： +- 预配置的 `docs.site.json`，ObjectStack 品牌 +- 示例文档结构 +- 带有 `meta.json` 导航的可直接运行的内容 + +```bash +# 使用入门模板快速开始 +cp -r examples/starter my-docs +cd my-docs +npm init @objectdocs +``` + + +详细技术架构请参阅[系统设计](/docs/design)文档。功能路线图请参阅[开发路线图](/docs/development-plan)。 + diff --git a/content/docs/packages.mdx b/content/docs/packages.mdx new file mode 100644 index 0000000..ef05ec2 --- /dev/null +++ b/content/docs/packages.mdx @@ -0,0 +1,290 @@ +--- +title: Packages Overview +description: Complete overview of ObjectDocs software packages, their features, development status, and version history. +--- + +import { Package, Terminal, Layout, Zap, CheckCircle, Clock } from 'lucide-react'; + +# Packages Overview + +ObjectDocs is organized as a **pnpm workspace monorepo** with two core packages. This document provides a detailed overview of each package, its features, current status, and development history. + +**Current Version**: v0.2.12 | **Last Updated**: 2026-02-08 + +## Package Summary + +| Package | Version | Description | Status | +|---------|---------|-------------|--------| +| `@objectdocs/cli` | v0.2.12 | Command-line tool for building and managing documentation | ✅ Stable | +| `@objectdocs/site` | v0.2.12 | Next.js documentation site template and rendering engine | ✅ Stable | + +## @objectdocs/cli + + +} title="CLI Tool"> + +The primary developer interface for ObjectDocs. Provides commands for initializing, developing, building, and deploying documentation sites. + +- **Framework**: CAC (Command-line framework) +- **Language**: JavaScript/Node.js (ESM) +- **Entry Point**: `bin/cli.mjs` + + + + +### Commands + + + +### `objectdocs init` + +Initializes a new documentation project by copying the site template and setting up the development environment. + +**What it does**: +- Copies `@objectdocs/site` package to `content/.fumadocs` +- Creates `content/package.json` with dev/build/start scripts +- Installs dependencies in `content/.fumadocs` +- Updates `.gitignore` to exclude generated files + +### `objectdocs dev [docsDir]` + +Starts the development server with hot reload. + +**Features**: +- Default port: 7777 (configurable) +- Watches `docs.site.json` for changes and auto-restarts +- Syncs public assets to site engine +- Sets `DOCS_DIR` environment variable + +### `objectdocs build [docsDir]` + +Builds the documentation site for production. + +**Features**: +- Supports static export (`out/` directory) and dynamic standalone (`.next/`) modes +- Copies configuration and public assets +- Handles symlink-aware artifact copying for Vercel compatibility + +### `objectdocs start` + +Starts the production server. + +**Features**: +- Static mode: Serves from `out/` directory using `serve` +- Dynamic mode: Runs Next.js production server +- Configurable port + +### `objectdocs translate` + +AI-powered content translation using OpenAI. + +**Features**: +- Translates MDX content to configured languages +- `--all` flag for batch translation +- CI-compatible with environment variable configuration +- Generates language-specific files (e.g., `.cn.mdx`, `.ja.mdx`) + + + +### Dependencies + +| Dependency | Version | Purpose | +|-----------|---------|---------| +| `@objectdocs/site` | workspace:* | Site template for initialization | +| `cac` | ^6.7.14 | CLI framework | +| `openai` | ^4.0.0 | AI-powered translation | +| `dotenv` | ^16.4.5 | Environment variable loading | +| `typescript` | ^5.9.3 | TypeScript support | + +### Feature Status + +| Feature | Status | Notes | +|---------|--------|-------| +| Project initialization | ✅ Complete | Full `init` workflow | +| Development server | ✅ Complete | Hot reload, config watching | +| Production build | ✅ Complete | Static + dynamic modes | +| Production server | ✅ Complete | Static + dynamic serving | +| AI translation | ✅ Complete | OpenAI integration | +| GitHub integration | ⬚ Planned | Phase 2 | +| README migration | ⬚ Planned | Phase 2 | +| API doc generation | ⬚ Planned | Phase 2 | + +--- + +## @objectdocs/site + + +} title="Site Template"> + +A complete Next.js application template that serves as the documentation rendering engine. Built on Fumadocs with full i18n support. + +- **Framework**: Next.js 16 (App Router) + Fumadocs 16 +- **Styling**: Tailwind CSS 4 +- **Language**: TypeScript +- **React**: v19 (Server Components) + + + + +### Core Features + + +} title="Content Rendering"> + +- MDX compilation with remark/rehype plugins +- Code syntax highlighting (Vesper theme) +- Image zoom capability +- Built-in components: Callout, Card, Cards, Steps, Step +- Table of contents generation + + +} title="Site Engine"> + +- File-system based routing +- Full-text search API endpoint +- `meta.json`-driven navigation tree +- Configurable sidebar, navbar, and footer +- Dark mode support + + + + +### Architecture + +| Component | Path | Description | +|-----------|------|-------------| +| Root Layout | `app/layout.tsx` | HTML shell, global providers | +| Language Router | `app/[lang]/layout.tsx` | i18n layout with Fumadocs | +| Docs Pages | `app/[lang]/docs/[[...slug]]/page.tsx` | Dynamic MDX page rendering | +| Home Redirect | `app/[lang]/page.tsx` | Redirects to docs root | +| Search API | `app/api/search/route.ts` | Full-text search endpoint | +| i18n System | `lib/i18n.ts` | 6-language support with UI translations | +| Config Loader | `lib/config.ts` | `docs.site.json` parsing and defaults | +| Source Manager | `lib/source.ts` | Fumadocs content source with i18n | +| MDX Components | `mdx-components.tsx` | Custom component registry | +| Source Config | `source.config.ts` | Content directory and MDX plugin config | + +### i18n Support + +Pre-built UI translations for 6 languages: + +| Language | Code | TOC Label | Search | Last Update | +|----------|------|-----------|--------|-------------| +| English | `en` | "On this page" | "Search" | "Last updated on" | +| 中文 | `cn` | "目录" | "搜索" | "最后更新于" | +| 日本語 | `ja` | "目次" | "検索" | "最終更新" | +| Français | `fr` | "Sur cette page" | "Rechercher" | "Dernière mise à jour" | +| Deutsch | `de` | "Auf dieser Seite" | "Suchen" | "Zuletzt aktualisiert am" | +| Español | `es` | "En esta página" | "Buscar" | "Última actualización" | + +### Configuration Options + +The site reads from `docs.site.json` with support for: + +- **Site metadata**: title, description, URL, favicon +- **Branding**: name, logo (light/dark), theme color, border radius +- **Navigation**: navbar links with text, URL, icon, external flag +- **Sidebar**: collapsible, prefetch, default open level, tabs +- **Table of Contents**: enabled, depth +- **Footer**: copyright text +- **Page features**: last update timestamps, edit on GitHub links +- **Content**: code theme, image zoom, math support +- **i18n**: default language, language list +- **Build**: mode (export/standalone) + +### Dependencies + +| Dependency | Version | Purpose | +|-----------|---------|---------| +| `next` | ^16.1.2 | Application framework | +| `react` / `react-dom` | ^19.2.3 | UI rendering | +| `fumadocs-core` | ^16.4.7 | Documentation engine core | +| `fumadocs-ui` | ^16.4.7 | Documentation UI components | +| `fumadocs-mdx` | ^14.2.5 | MDX content processing | +| `tailwindcss` | ^4.1.18 | Utility-first CSS | +| `typescript` | ^5.9.3 | Type safety | +| `openai` | ^4.0.0 | AI features | +| `lucide-react` | ^0.562.0 | Icon library | + +### Feature Status + +| Feature | Status | Notes | +|---------|--------|-------| +| MDX rendering | ✅ Complete | Full Fumadocs pipeline | +| i18n (6 languages) | ✅ Complete | File-based + UI translations | +| Full-text search | ✅ Complete | API endpoint | +| Dark mode | ✅ Complete | Via Fumadocs UI | +| Code highlighting | ✅ Complete | Vesper theme | +| Image zoom | ✅ Complete | Configurable | +| Standalone output | ✅ Complete | Vercel/Docker ready | +| Static export | ✅ Complete | CDN-deployable | +| Config system | ✅ Complete | `docs.site.json` | +| ISR support | ⬚ Planned | Phase 1 | +| Edge Functions | ⬚ Planned | Phase 1 | +| Math rendering | ⬚ Planned | Config exists, not enabled | + +--- + +## Version History + +### v0.2.12 (Latest) +- Patch release for maintenance updates + +### v0.2.11 +- Fix: Handle broken symlinks during build copy to prevent ENOENT errors on Vercel + +### v0.2.10 +- Feat: Enable standalone output mode for better Vercel/Docker support + +### v0.2.9 +- Fix: Add `.source` path alias to `tsconfig.json` for generated file resolution + +### v0.2.8 +- Fix: Use `dereference: true` when copying `.next` directory to expand all symlinks + +### v0.2.7 +- Fix: Use relative import for generated content to avoid alias resolution issues in monorepos + +### v0.2.6 +- Fix: Copy `.next` directory instead of symlinking to support Vercel deployment + +### v0.2.5 +- Chore: Add `transpilePackages` configuration for monorepo module resolution + +### v0.2.4 +- Fix: Rename `proxy.ts` to `middleware.ts` to fix Next.js 16 build error + +### v0.2.3 +- Fix: Update package metadata for publishing + +### v0.2.2 +- Docs: Updated README with corrected configuration file names + +### v0.2.1 +- Bug fixes and improvements + +### v0.2.0 +- Initial release: Modern documentation engine built on Next.js 14 and Fumadocs + +### v0.1.0 +- Initial release with metadata-driven architecture, low-code component embedding, enterprise-grade UI, and multi-product support + +--- + +## Starter Template + +An example starter template is available in `examples/starter/` with: +- Pre-configured `docs.site.json` with ObjectStack branding +- Sample documentation structure +- Ready-to-run content with `meta.json` navigation + +```bash +# Quick start with the starter template +cp -r examples/starter my-docs +cd my-docs +npm init @objectdocs +``` + + +For detailed technical architecture, see the [System Design](/docs/design) document. For the feature roadmap, see the [Development Roadmap](/docs/development-plan). + From a7a2275ff526c02849ebf7f4e8225aceee0eef54 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Sun, 8 Feb 2026 11:29:38 +0000 Subject: [PATCH 3/6] docs: finalize documentation updates Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com> --- pnpm-lock.yaml | 30 +++++++++++++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 4ab03ca..6484f9e 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -1,7 +1,7 @@ lockfileVersion: '9.0' settings: - autoInstallPeers: false + autoInstallPeers: true excludeLinksFromLockfile: false importers: @@ -413,89 +413,105 @@ packages: resolution: {integrity: sha512-excjX8DfsIcJ10x1Kzr4RcWe1edC9PquDRRPx3YVCvQv+U5p7Yin2s32ftzikXojb1PIFc/9Mt28/y+iRklkrw==} cpu: [arm64] os: [linux] + libc: [glibc] '@img/sharp-libvips-linux-arm@1.2.4': resolution: {integrity: sha512-bFI7xcKFELdiNCVov8e44Ia4u2byA+l3XtsAj+Q8tfCwO6BQ8iDojYdvoPMqsKDkuoOo+X6HZA0s0q11ANMQ8A==} cpu: [arm] os: [linux] + libc: [glibc] '@img/sharp-libvips-linux-ppc64@1.2.4': resolution: {integrity: sha512-FMuvGijLDYG6lW+b/UvyilUWu5Ayu+3r2d1S8notiGCIyYU/76eig1UfMmkZ7vwgOrzKzlQbFSuQfgm7GYUPpA==} cpu: [ppc64] os: [linux] + libc: [glibc] '@img/sharp-libvips-linux-riscv64@1.2.4': resolution: {integrity: sha512-oVDbcR4zUC0ce82teubSm+x6ETixtKZBh/qbREIOcI3cULzDyb18Sr/Wcyx7NRQeQzOiHTNbZFF1UwPS2scyGA==} cpu: [riscv64] os: [linux] + libc: [glibc] '@img/sharp-libvips-linux-s390x@1.2.4': resolution: {integrity: sha512-qmp9VrzgPgMoGZyPvrQHqk02uyjA0/QrTO26Tqk6l4ZV0MPWIW6LTkqOIov+J1yEu7MbFQaDpwdwJKhbJvuRxQ==} cpu: [s390x] os: [linux] + libc: [glibc] '@img/sharp-libvips-linux-x64@1.2.4': resolution: {integrity: sha512-tJxiiLsmHc9Ax1bz3oaOYBURTXGIRDODBqhveVHonrHJ9/+k89qbLl0bcJns+e4t4rvaNBxaEZsFtSfAdquPrw==} cpu: [x64] os: [linux] + libc: [glibc] '@img/sharp-libvips-linuxmusl-arm64@1.2.4': resolution: {integrity: sha512-FVQHuwx1IIuNow9QAbYUzJ+En8KcVm9Lk5+uGUQJHaZmMECZmOlix9HnH7n1TRkXMS0pGxIJokIVB9SuqZGGXw==} cpu: [arm64] os: [linux] + libc: [musl] '@img/sharp-libvips-linuxmusl-x64@1.2.4': resolution: {integrity: sha512-+LpyBk7L44ZIXwz/VYfglaX/okxezESc6UxDSoyo2Ks6Jxc4Y7sGjpgU9s4PMgqgjj1gZCylTieNamqA1MF7Dg==} cpu: [x64] os: [linux] + libc: [musl] '@img/sharp-linux-arm64@0.34.5': resolution: {integrity: sha512-bKQzaJRY/bkPOXyKx5EVup7qkaojECG6NLYswgktOZjaXecSAeCWiZwwiFf3/Y+O1HrauiE3FVsGxFg8c24rZg==} engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0} cpu: [arm64] os: [linux] + libc: [glibc] '@img/sharp-linux-arm@0.34.5': resolution: {integrity: sha512-9dLqsvwtg1uuXBGZKsxem9595+ujv0sJ6Vi8wcTANSFpwV/GONat5eCkzQo/1O6zRIkh0m/8+5BjrRr7jDUSZw==} engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0} cpu: [arm] os: [linux] + libc: [glibc] '@img/sharp-linux-ppc64@0.34.5': resolution: {integrity: sha512-7zznwNaqW6YtsfrGGDA6BRkISKAAE1Jo0QdpNYXNMHu2+0dTrPflTLNkpc8l7MUP5M16ZJcUvysVWWrMefZquA==} engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0} cpu: [ppc64] os: [linux] + libc: [glibc] '@img/sharp-linux-riscv64@0.34.5': resolution: {integrity: sha512-51gJuLPTKa7piYPaVs8GmByo7/U7/7TZOq+cnXJIHZKavIRHAP77e3N2HEl3dgiqdD/w0yUfiJnII77PuDDFdw==} engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0} cpu: [riscv64] os: [linux] + libc: [glibc] '@img/sharp-linux-s390x@0.34.5': resolution: {integrity: sha512-nQtCk0PdKfho3eC5MrbQoigJ2gd1CgddUMkabUj+rBevs8tZ2cULOx46E7oyX+04WGfABgIwmMC0VqieTiR4jg==} engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0} cpu: [s390x] os: [linux] + libc: [glibc] '@img/sharp-linux-x64@0.34.5': resolution: {integrity: sha512-MEzd8HPKxVxVenwAa+JRPwEC7QFjoPWuS5NZnBt6B3pu7EG2Ge0id1oLHZpPJdn3OQK+BQDiw9zStiHBTJQQQQ==} engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0} cpu: [x64] os: [linux] + libc: [glibc] '@img/sharp-linuxmusl-arm64@0.34.5': resolution: {integrity: sha512-fprJR6GtRsMt6Kyfq44IsChVZeGN97gTD331weR1ex1c1rypDEABN6Tm2xa1wE6lYb5DdEnk03NZPqA7Id21yg==} engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0} cpu: [arm64] os: [linux] + libc: [musl] '@img/sharp-linuxmusl-x64@0.34.5': resolution: {integrity: sha512-Jg8wNT1MUzIvhBFxViqrEhWDGzqymo3sV7z7ZsaWbZNDLXRJZoRGrjulp60YYtV4wfY8VIKcWidjojlLcWrd8Q==} engines: {node: ^18.17.0 || ^20.3.0 || >=21.0.0} cpu: [x64] os: [linux] + libc: [musl] '@img/sharp-wasm32@0.34.5': resolution: {integrity: sha512-OdWTEiVkY2PHwqkbBI8frFxQQFekHaSSkUIJkwzclWZe64O1X4UlUjqqqLaPbUpMOQk6FBu/HtlGXNblIs0huw==} @@ -574,24 +590,28 @@ packages: engines: {node: '>= 10'} cpu: [arm64] os: [linux] + libc: [glibc] '@next/swc-linux-arm64-musl@16.1.2': resolution: {integrity: sha512-Sn6LxPIZcADe5AnqqMCfwBv6vRtDikhtrjwhu+19WM6jHZe31JDRcGuPZAlJrDk6aEbNBPUUAKmySJELkBOesg==} engines: {node: '>= 10'} cpu: [arm64] os: [linux] + libc: [musl] '@next/swc-linux-x64-gnu@16.1.2': resolution: {integrity: sha512-nwzesEQBfQIOOnQ7JArzB08w9qwvBQ7nC1i8gb0tiEFH94apzQM3IRpY19MlE8RBHxc9ArG26t1DEg2aaLaqVQ==} engines: {node: '>= 10'} cpu: [x64] os: [linux] + libc: [glibc] '@next/swc-linux-x64-musl@16.1.2': resolution: {integrity: sha512-s60bLf16BDoICQHeKEm0lDgUNMsL1UpQCkRNZk08ZNnRpK0QUV+6TvVHuBcIA7oItzU0m7kVmXe8QjXngYxJVA==} engines: {node: '>= 10'} cpu: [x64] os: [linux] + libc: [musl] '@next/swc-win32-arm64-msvc@16.1.2': resolution: {integrity: sha512-Sq8k4SZd8Y8EokKdz304TvMO9HoiwGzo0CTacaiN1bBtbJSQ1BIwKzNFeFdxOe93SHn1YGnKXG6Mq3N+tVooyQ==} @@ -1057,24 +1077,28 @@ packages: engines: {node: '>= 10'} cpu: [arm64] os: [linux] + libc: [glibc] '@tailwindcss/oxide-linux-arm64-musl@4.1.18': resolution: {integrity: sha512-1px92582HkPQlaaCkdRcio71p8bc8i/ap5807tPRDK/uw953cauQBT8c5tVGkOwrHMfc2Yh6UuxaH4vtTjGvHg==} engines: {node: '>= 10'} cpu: [arm64] os: [linux] + libc: [musl] '@tailwindcss/oxide-linux-x64-gnu@4.1.18': resolution: {integrity: sha512-v3gyT0ivkfBLoZGF9LyHmts0Isc8jHZyVcbzio6Wpzifg/+5ZJpDiRiUhDLkcr7f/r38SWNe7ucxmGW3j3Kb/g==} engines: {node: '>= 10'} cpu: [x64] os: [linux] + libc: [glibc] '@tailwindcss/oxide-linux-x64-musl@4.1.18': resolution: {integrity: sha512-bhJ2y2OQNlcRwwgOAGMY0xTFStt4/wyU6pvI6LSuZpRgKQwxTec0/3Scu91O8ir7qCR3AuepQKLU/kX99FouqQ==} engines: {node: '>= 10'} cpu: [x64] os: [linux] + libc: [musl] '@tailwindcss/oxide-wasm32-wasi@4.1.18': resolution: {integrity: sha512-LffYTvPjODiP6PT16oNeUQJzNVyJl1cjIebq/rWWBF+3eDst5JGEFSc5cWxyRCJ0Mxl+KyIkqRxk1XPEs9x8TA==} @@ -1733,24 +1757,28 @@ packages: engines: {node: '>= 12.0.0'} cpu: [arm64] os: [linux] + libc: [glibc] lightningcss-linux-arm64-musl@1.30.2: resolution: {integrity: sha512-5Vh9dGeblpTxWHpOx8iauV02popZDsCYMPIgiuw97OJ5uaDsL86cnqSFs5LZkG3ghHoX5isLgWzMs+eD1YzrnA==} engines: {node: '>= 12.0.0'} cpu: [arm64] os: [linux] + libc: [musl] lightningcss-linux-x64-gnu@1.30.2: resolution: {integrity: sha512-Cfd46gdmj1vQ+lR6VRTTadNHu6ALuw2pKR9lYq4FnhvgBc4zWY1EtZcAc6EffShbb1MFrIPfLDXD6Xprbnni4w==} engines: {node: '>= 12.0.0'} cpu: [x64] os: [linux] + libc: [glibc] lightningcss-linux-x64-musl@1.30.2: resolution: {integrity: sha512-XJaLUUFXb6/QG2lGIW6aIk6jKdtjtcffUT0NKvIqhSBY3hh9Ch+1LCeH80dR9q9LBjG3ewbDjnumefsLsP6aiA==} engines: {node: '>= 12.0.0'} cpu: [x64] os: [linux] + libc: [musl] lightningcss-win32-arm64-msvc@1.30.2: resolution: {integrity: sha512-FZn+vaj7zLv//D/192WFFVA0RgHawIcHqLX9xuWiQt7P0PtdFEVaxgF9rjM/IRYHQXNnk61/H/gb2Ei+kUQ4xQ==} From 99b29253972b97ee8075bdf354caac8031ccf5e5 Mon Sep 17 00:00:00 2001 From: Jack Zhuang <50353452+hotlong@users.noreply.github.com> Date: Sun, 8 Feb 2026 19:33:54 +0800 Subject: [PATCH 4/6] =?UTF-8?q?=E5=88=A0=E9=99=A4=20design.cn.mdx?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- content/docs/design.cn.mdx | 300 ------------------------------------- 1 file changed, 300 deletions(-) delete mode 100644 content/docs/design.cn.mdx diff --git a/content/docs/design.cn.mdx b/content/docs/design.cn.mdx deleted file mode 100644 index b1d8fda..0000000 --- a/content/docs/design.cn.mdx +++ /dev/null @@ -1,300 +0,0 @@ ---- -title: 系统设计 -description: ObjectDocs 完整系统设计文档 — 架构、技术决策和组件概览。 ---- - -import { FileJson, Layers, Cpu, Zap, GitBranch, Package, Globe, Code } from 'lucide-react'; - -# 系统设计文档 - -本文档提供 ObjectDocs 的完整技术设计概览，涵盖系统架构、包结构、数据流和关键设计决策。 - -**版本**: v0.2.12 | **最后更新**: 2026-02-08 - -## 1. 系统概述 - -ObjectDocs 是一个基于 Next.js 和 Fumadocs 构建的**元数据驱动文档引擎**，专为 ObjectStack 低代码生态系统设计。它遵循严格的**配置即代码**理念，文档结构由数据（JSON）定义，而非代码（React）。 - -### 设计目标 - - -} title="元数据驱动"> -导航、侧边栏和页面排序完全通过 `meta.json` 文件和 `docs.site.json` 配置定义。内容创作者无需接触 React 代码。 - -} title="关注点分离"> -系统严格分离三个层次：**展示层**（React/Next.js 站点引擎）、**配置层**（JSON 文件）和**内容层**（MDX 文档）。 - -} title="Monorepo 架构"> -项目组织为 pnpm 工作区 monorepo，包含两个核心包（`@objectdocs/cli` 和 `@objectdocs/site`）以及共享的内容层。 - -} title="国际化优先"> -多语言支持内置于核心架构中，支持语言特定的 MDX 文件和 6 种语言的预置 UI 翻译。 - - - -## 2. 架构概览 - -### 2.1 高层架构 - -```text -┌─────────────────────────────────────────────────────────┐ -│ ObjectDocs 系统 │ -├──────────────┬──────────────────┬───────────────────────┤ -│ @objectdocs │ @objectdocs │ 内容层 │ -│ /cli │ /site │ │ -│ │ │ │ -│ 命令: │ Next.js 16 + │ content/ │ -│ • init │ Fumadocs 16 │ ├── docs.site.json │ -│ • dev │ │ ├── docs/ │ -│ • build │ App Router │ │ ├── meta.json │ -│ • start │ React Server │ │ ├── index.mdx │ -│ • translate │ Components │ │ └── ... │ -│ │ │ └── public/ │ -├──────────────┼──────────────────┼───────────────────────┤ -│ CLI 层 │ 展示层 │ 数据层 │ -│ (工具链) │ (渲染) │ (配置 + 内容) │ -└──────────────┴──────────────────┴───────────────────────┘ -``` - -### 2.2 包依赖关系图 - -```text -根工作区 (objectdocs v1.0.0) -├── @objectdocs/cli (v0.2.12) -│ ├── 依赖: @objectdocs/site (workspace:*) -│ ├── cac (CLI 框架) -│ ├── openai (AI 翻译) -│ └── dotenv (环境配置) -└── @objectdocs/site (v0.2.12) - ├── next (^16.1.2) - ├── fumadocs-core (^16.4.7) - ├── fumadocs-ui (^16.4.7) - ├── fumadocs-mdx (^14.2.5) - ├── react (^19.2.3) - ├── tailwindcss (^4.1.18) - └── typescript (^5.9.3) -``` - -## 3. 核心组件 - -### 3.1 CLI 包 (`@objectdocs/cli`) - -CLI 是 ObjectDocs 的主要开发者接口。基于 [CAC](https://github.com/cacjs/cac) 框架构建，提供 5 个命令： - -| 命令 | 用途 | 关键行为 | -|------|------|---------| -| `init` | 初始化新文档项目 | 将 `@objectdocs/site` 复制到 `content/.fumadocs`，安装依赖，更新 `.gitignore` | -| `dev` | 启动开发服务器 | 运行在端口 7777，监听 `docs.site.json` 变更，同步公共资源 | -| `build` | 生产环境构建 | 支持静态导出（`out/`）和动态独立（`.next/`）两种模式 | -| `start` | 启动生产服务器 | 静态模式使用 `serve`，动态模式使用 Next.js 服务器 | -| `translate` | AI 驱动的翻译 | 使用 OpenAI API，支持 `--all` 参数，生成语言特定的 `.mdx` 文件 | - -**设计决策**：CLI 在初始化时将整个 `@objectdocs/site` 包复制到 `content/.fumadocs`，而不是作为运行时依赖使用。这确保了文档引擎和用户内容之间的完全隔离，允许自定义站点而不影响包本身。 - -### 3.2 站点包 (`@objectdocs/site`) - -站点包是一个完整的 Next.js 应用模板，作为文档渲染引擎。 - -**核心组件**: - -| 组件 | 文件 | 职责 | -|------|------|------| -| 根布局 | `app/layout.tsx` | HTML 外壳、Provider、全局样式 | -| 语言路由 | `app/[lang]/layout.tsx` | i18n 布局与 Fumadocs Provider | -| 文档页面 | `app/[lang]/docs/[[...slug]]/page.tsx` | MDX 渲染、TOC、导航 | -| 搜索 API | `app/api/search/route.ts` | 全文搜索端点 | -| i18n 配置 | `lib/i18n.ts` | 语言定义和 UI 翻译 | -| 站点配置 | `lib/config.ts` | 加载并合并 `docs.site.json` | -| 内容加载器 | `lib/source.ts` | 带 i18n 的 Fumadocs 内容源 | - -### 3.3 内容层 - -内容层是定义文档站点的用户数据： - -```text -content/ -├── docs.site.json # 全局站点配置 -│ ├── branding # Logo、名称、主题颜色 -│ ├── links # 导航栏链接 -│ ├── sidebar # 侧边栏行为配置 -│ ├── toc # 目录设置 -│ ├── footer # 页脚版权文本 -│ ├── page # 页面功能（编辑链接、最后更新） -│ ├── content # 内容功能（数学公式、代码主题） -│ ├── i18n # 语言配置 -│ └── build # 构建模式（export/standalone） -├── public/ # 静态资源（图片、字体） -└── docs/ - ├── meta.json # 根导航结构 - ├── index.mdx # 首页（英文） - ├── index.cn.mdx # 首页（中文） - └── getting-started/ - ├── meta.json # 章节页面排序 - ├── index.mdx # 章节首页 - └── ... -``` - -## 4. 数据流 - -### 4.1 构建时数据流 - - - -### 内容发现 -Fumadocs MDX 源加载器扫描 `DOCS_DIR` 目录中的所有 `.mdx` 文件和 `meta.json` 文件。文件按语言后缀组织（如 `.cn.mdx` 为中文）。 - -### 配置合并 -站点从内容目录读取 `docs.site.json` 并与 `lib/config.ts` 中的默认配置值合并，生成完整的站点配置。 - -### 导航树构建 -每个目录中的 `meta.json` 文件定义页面排序和章节标题。Fumadocs 从这些文件构建层次化的导航树。 - -### MDX 编译 -每个 `.mdx` 文件通过 Fumadocs MDX 管道（含 remark/rehype 插件）编译，生成 React Server Components。 - -### 静态生成 -Next.js App Router 为每个路由生成静态页面。在独立模式下，页面可以通过 ISR 进行服务端渲染。 - - - -### 4.2 运行时数据流 - -```text -用户请求 → Next.js 路由 → 语言检测 → 页面解析 - → MDX 内容渲染 (RSC) → Fumadocs UI 布局 → HTML 响应 -``` - -### 4.3 翻译数据流 - -```text -源 MDX → CLI translate 命令 → OpenAI API → 翻译后的 MDX - → 语言特定文件 (如 .cn.mdx) → 内容发现 -``` - -## 5. 配置系统设计 - -### 5.1 `docs.site.json` 模式 - -站点配置文件支持以下部分： - -```json -{ - "site": { - "title": "站点标题", - "description": "站点描述", - "url": "https://example.com", - "favicon": "/favicon.ico" - }, - "branding": { - "name": "品牌名称", - "logo": { "light": "/logo-light.svg", "dark": "/logo-dark.svg" }, - "themeColor": "#7c3aed", - "borderRadius": "0.5rem" - }, - "links": [{ "text": "首页", "url": "/" }], - "sidebar": { "collapsible": true, "defaultOpenLevel": 1 }, - "toc": { "enabled": true, "depth": 3 }, - "footer": { "copyright": "© 2026" }, - "page": { - "lastUpdate": true, - "editOnGithub": { "owner": "org", "repo": "repo" } - }, - "content": { "codeTheme": "vesper", "imageZoom": true }, - "i18n": { - "defaultLanguage": "en", - "languages": ["en", "cn"] - }, - "build": { "mode": "export" } -} -``` - -### 5.2 `meta.json` 模式 - -每个目录可以包含 `meta.json` 来控制导航： - -```json -{ - "title": "章节标题", - "pages": ["page-a", "page-b", "sub-directory"] -} -``` - -**关键规则**：侧边栏导航**永远不**在 React 组件中定义。所有导航结构变更通过 `meta.json` 文件进行。 - -## 6. 国际化架构 - -### 6.1 支持的语言 - -| 代码 | 语言 | UI 翻译 | -|------|------|---------| -| `en` | English | ✅ 完整 | -| `cn` | 中文 | ✅ 完整 | -| `ja` | 日本語 | ✅ 完整 | -| `fr` | Français | ✅ 完整 | -| `de` | Deutsch | ✅ 完整 | -| `es` | Español | ✅ 完整 | - -### 6.2 内容翻译策略 - -- **基于文件**：每种语言有独立的 MDX 文件（如英文 `index.mdx`，中文 `index.cn.mdx`） -- **回退机制**：如果翻译文件不存在，使用默认语言版本 -- **AI 翻译**：`translate` CLI 命令使用 OpenAI 自动生成翻译 -- **URL 路由**：URL 路径中的语言前缀（`/en/docs/...`、`/cn/docs/...`） - -## 7. 部署设计 - -### 7.1 构建模式 - -| 模式 | 输出 | 使用场景 | -|------|------|---------| -| `export`（静态） | `out/` 目录（HTML/CSS/JS） | CDN 托管、GitHub Pages、Vercel 静态 | -| `standalone`（动态） | `.next/`（Node.js 服务器） | ISR、SSR、API 路由、Vercel Serverless | - -### 7.2 Vercel 部署 - -```text -GitHub 推送 → Vercel 构建钩子 → pnpm build → Next.js 构建 - → 静态资源 + Serverless 函数 → 边缘 CDN 分发 -``` - -**关键设计决策**： -- 独立输出模式，优化 Vercel serverless 支持 -- 符号链接感知的构件复制，处理 monorepo 结构 -- `vercel.json` 路由配置，支持简洁 URL -- 通过 GitHub Actions 工作流实现预览部署 - -### 7.3 CI/CD 流水线 - -| 工作流 | 触发器 | 用途 | -|--------|--------|------| -| `ci.yml` | Push/PR | 构建验证 | -| `release.yml` | Push to main | Changesets NPM 发布 | -| `preview.yml` | PR | Vercel 预览部署 | -| `test-lifecycle.yml` | Push/PR | 全面生命周期测试 | -| `link-check.yml` | PR | 内容链接验证 | - -## 8. 技术栈 - -| 层级 | 技术 | 版本 | -|------|------|------| -| 运行时 | Next.js (App Router) | ^16.1.2 | -| UI 框架 | React (Server Components) | ^19.2.3 | -| 文档引擎 | Fumadocs | ^16.4.7 | -| 样式 | Tailwind CSS | ^4.1.18 | -| 语言 | TypeScript | ^5.9.3 | -| 包管理器 | pnpm | 工作区 monorepo | -| AI 集成 | OpenAI API | ^4.0.0 | -| CLI 框架 | CAC | ^6.7.14 | -| 内容格式 | MDX | 通过 fumadocs-mdx | -| 部署 | Vercel | Serverless/Edge | - -## 9. 安全考虑 - -- **无硬编码密钥**：所有 API 密钥（如 OpenAI）通过环境变量加载 -- **默认 Server Components**：最小化客户端 JavaScript 暴露 -- **内容隔离**：文档内容与渲染引擎分离 -- **依赖管理**：通过 Changesets 自动化管理，锁定版本 - - -本设计文档反映了 ObjectDocs v0.2.12 的当前状态。随着系统演进将持续更新。功能路线图请参阅[开发路线图](/docs/development-plan)。 - From 2002e23c9e2cc615eee6500cb79d71d37dda1085 Mon Sep 17 00:00:00 2001 From: Jack Zhuang <50353452+hotlong@users.noreply.github.com> Date: Sun, 8 Feb 2026 19:34:50 +0800 Subject: [PATCH 5/6] =?UTF-8?q?=E5=88=A0=E9=99=A4=20development-plan.cn.md?= =?UTF-8?q?x?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- content/docs/development-plan.cn.mdx | 274 --------------------------- 1 file changed, 274 deletions(-) delete mode 100644 content/docs/development-plan.cn.mdx diff --git a/content/docs/development-plan.cn.mdx b/content/docs/development-plan.cn.mdx deleted file mode 100644 index 281d901..0000000 --- a/content/docs/development-plan.cn.mdx +++ /dev/null @@ -1,274 +0,0 @@ ---- -title: 开发路线图 -description: ObjectDocs 开发计划和功能路线图，基于 GitHub 的文档系统与 Vercel 部署集成 ---- - -import { Code, Sparkles, Globe, Shield, GitBranch, Rocket, CheckCircle } from 'lucide-react'; - -# ObjectDocs 开发路线图 - -本文档概述了 ObjectDocs 的开发计划和功能路线图。ObjectDocs 是一个面向 GitHub 的文档引擎，针对 Vercel 部署进行了优化。 - -**当前版本**: v0.2.12 | **最后更新**: 2026-02-08 - -## 🎯 核心使命 - -ObjectDocs 专为 **基于 GitHub 的仓库文档** 构建，与 **Vercel 部署** 无缝集成。核心目标： - -1. **Git 原生工作流**: 利用 GitHub 的协作功能（PR、Review、Issues）作为内容管理系统 -2. **零配置部署**: 推送到 GitHub，自动部署到 Vercel，享有最优的缓存和 CDN 分发 -3. **开发者优先**: 将文档视为代码——版本控制、同行评审、CI/CD 集成 - -## 📊 整体进度概览 - -| 软件包 | 版本 | 状态 | -|--------|------|------| -| `@objectdocs/cli` | v0.2.12 | ✅ 稳定 | -| `@objectdocs/site` | v0.2.12 | ✅ 稳定 | -| 根工作区 | v1.0.0 | ✅ 活跃 | - -| 阶段 | 状态 | 进度 | -|------|------|------| -| 第一阶段：核心平台与部署 | ✅ 基本完成 | ~80% | -| 第二阶段：开发者体验 | 🟡 进行中 | ~30% | -| 第三阶段：高级功能 | ⬚ 规划中 | ~0% | - -## 📅 开发路线图 - -### 第一阶段：核心平台与部署（2025 Q4 – 2026 Q1） - - -} title="GitHub 原生功能"> - -**目标**: 与 GitHub 仓库工作流深度集成 - -- [x] GitHub Actions 自动化构建和检查工作流（CI、发布、预览、测试、链接检查） -- [x] 通过 Vercel 集成的 PR 预览部署（`preview.yml` 工作流） -- [x] 基于 Changesets 的版本化发布和自动 NPM 发布 -- [ ] 用于自动文档同步的 GitHub App -- [ ] 用于文档反馈的 GitHub Issues 集成 -- [ ] 基于分支的文档版本管理 - -**已实现**: -- CI 工作流 (`ci.yml`)：push/PR 时的构建验证 -- 发布工作流 (`release.yml`)：基于 Changesets 的语义化版本管理 -- 预览工作流 (`preview.yml`)：PR 预览部署 -- 测试工作流 (`test-lifecycle.yml`)：全面测试 -- 链接检查工作流 (`link-check.yml`)：内容验证 - - - -} title="Vercel 部署流水线"> - -**目标**: 针对 Vercel 的边缘网络和构建系统优化 - -- [x] 独立输出模式支持 Vercel/Docker 部署 -- [x] 通过 GitHub Actions 实现生产部署自动化 -- [x] `vercel.json` 路由优化配置 -- [x] 每个 PR 的预览部署 -- [x] Monorepo 感知的构建配置 -- [ ] ISR（增量静态再生成）配置 -- [ ] 用于动态内容的 Edge Functions -- [ ] 用于 A/B 测试的 Edge Middleware - -**已实现**: -- `next.config.mjs` 独立输出模式 -- 符号链接感知的构件复制，兼容 Vercel -- 静态导出和动态（独立）两种构建模式 -- `vercel.json` 部署配置 - - - - -### 第二阶段：增强开发者体验（2026 Q1 – Q2） - - -} title="CLI 与自动化工具"> - -**目标**: 简化从仓库到文档的工作流 - -- [x] 功能完整的 ObjectDocs CLI，包含 5 个命令（init、dev、build、start、translate） -- [x] 零配置项目初始化（`objectdocs init`） -- [x] 支持配置监听的热重载开发服务器 -- [x] 静态和动态两种构建模式 -- [ ] 从 README 文件自动迁移内容 -- [ ] 从仓库文件提取代码片段 -- [ ] 从源代码生成 API 文档 -- [ ] 从提交记录自动生成更新日志 - -**已实现**: -- `init` — 复制站点模板、安装依赖、配置 `.gitignore` -- `dev` — 在端口 7777 启动开发服务器，监听 `docs.site.json` 并同步资源 -- `build` — 静态/动态构建及构件处理 -- `start` — 生产服务器（静态用 `serve`，动态用 Next.js） -- `translate` — OpenAI 驱动的批量翻译，支持 `--all` 参数 - - - -} title="AI 驱动的文档助手"> - -**目标**: 利用 AI 提升文档质量 - -- [x] 基于 OpenAI 集成的自动翻译支持 -- [x] 多语言文件生成（`.cn.mdx`、`.ja.mdx` 等） -- [x] CI 兼容的翻译支持（环境变量配置） -- [ ] 基于语义理解的 AI 搜索 -- [ ] 从代码注释自动生成文档 -- [ ] 基于仓库的智能内容建议 -- [ ] 文档质量评分和改进建议 - -**已实现**: -- `translate` 命令中的 OpenAI API 集成 -- 支持 `--all` 参数翻译所有内容 -- CI 流水线的环境变量配置 - - - - -### 第三阶段：协作与高级功能（2026 Q3+） - - -} title="多仓库文档中心"> - -**目标**: 跨多个 GitHub 仓库的统一文档 - -- [ ] 跨仓库搜索和导航 -- [ ] 组织级别的文档门户 -- [ ] 仓库级别的访问控制 -- [ ] 从多个来源自动聚合 -- [ ] 跨仓库的统一版本管理 - -**技术规划**: -- GitHub Organization API 集成 -- 仓库发现和索引 -- GitHub Teams 访问控制支持 -- 聚合搜索索引 - - - -} title="GitHub 企业级功能"> - -**目标**: 支持 GitHub Enterprise 和高级工作流 - -- [ ] 兼容 GitHub Enterprise Server -- [ ] 通过 GitHub 的 SAML/SSO 集成 -- [ ] 细粒度仓库权限管理 -- [ ] 文档变更审计日志 -- [ ] GitHub Advanced Security 集成 - -**技术规划**: -- 支持 GitHub Enterprise API 端点 -- 集成 GitHub OIDC 提供者 -- 使用 GitHub 权限模型进行访问控制 -- 基于 Webhook 的审计追踪 - - - - -## 🔧 技术基础设施 - -### GitHub 工作流优化 -- [x] GitHub Actions 持续部署（CI、发布、预览） -- [x] PR 检查和状态徽章 -- [x] 基于 Changesets 的自动发布流程 -- [ ] 通过 Dependabot 自动更新依赖 -- [ ] 从 git 标签自动生成发布说明 -- [ ] 文档请求的 Issue 模板 - -### 内容与国际化系统 -- [x] 完整的 i18n 支持，6 种语言（EN、CN、JA、FR、DE、ES） -- [x] 语言特定的 MDX 文件路由（`.en.mdx`、`.cn.mdx`） -- [x] 所有支持语言的预置 UI 翻译 -- [x] 可配置的默认语言 -- [x] AI 驱动的翻译 CLI 命令 - -### Vercel 平台功能 -- [x] 独立输出模式用于无服务器部署 -- [x] 搜索 API 端点（`/api/search`） -- [ ] Edge Config 动态功能标志 -- [ ] Vercel KV 缓存层 -- [ ] Web Analytics 集成 -- [ ] Edge Middleware A/B 测试 - -### 性能与 SEO -- [x] React Server Components 优化性能 -- [x] MDX 静态编译 -- [ ] Lighthouse 评分优化（目标 95+） -- [ ] Core Web Vitals 监控 -- [ ] 自动 Sitemap 生成 -- [ ] OpenGraph 元数据自动化 -- [ ] 搜索引擎结构化数据 - -## 🚀 部署架构 - -### 推荐配置 -```yaml -仓库结构: -├── content/ # 文档 MDX 文件 -│ ├── docs/ # MDX 页面和 meta.json -│ └── docs.site.json # 站点配置 -├── .github/ -│ └── workflows/ # CI/CD 自动化 -├── vercel.json # 部署配置 -└── package.json # 根工作区 -``` - -### CI/CD 流水线 -1. **推送到 GitHub** → 触发 CI 构建验证 -2. **创建 PR** → 通过 Vercel 生成预览部署 -3. **合并到 main** → 自动部署到生产环境 -4. **Changeset 合并** → 自动 NPM 发布 - -## 🎯 当前工作重点（2026 Q1） - -### 活跃开发任务 - -1. **设计文档 (✅ 已完成)** - - 目标：2026 年 2 月 - - 状态：已完成 - - 交付物：系统设计文档、软件包概览、更新后的路线图 - -2. **ISR 和 Edge Functions (🟡 进行中)** - - 目标：2026 年 3 月 - - 状态：规划中 - - 交付物：ISR 配置、Edge 中间件、缓存策略 - -3. **内容迁移工具 (🟡 规划中)** - - 目标：2026 年 Q2 - - 状态：规划中 - - 交付物：README 迁移、代码片段提取、API 文档生成 - -4. **GitHub App 开发 (⬚ 规划中)** - - 目标：2026 年 Q3 - - 状态：未开始 - - 交付物：OAuth 应用、Webhook 处理器、API 集成 - -## 💡 社区与贡献 - -### GitHub 优先的协作方式 -- 提交 Issue 进行功能请求和 Bug 报告 -- 创建 Pull Request 改进文档 -- 参与 GitHub Discussions -- Star 和 Watch 仓库获取更新 - -### 集成示例 -- [GitHub Actions 工作流模板](https://github.com/objectstack-ai/objectdocs/tree/main/.github/workflows) -- [Vercel 配置示例](https://github.com/objectstack-ai/objectdocs/blob/main/vercel.json) -- [一键部署](https://vercel.com/new/clone?repository-url=https://github.com/objectstack-ai/objectdocs) - - -此路线图是动态的，将根据社区反馈和 GitHub/Vercel 平台更新进行调整。通过 GitHub Projects 面板跟踪进度。 - - -## 🔄 更新日志 - -| 日期 | 变更内容 | 作者 | -|------|---------|------| -| 2026-02-08 | 更新进度状态，标记已完成功能，新增软件包概览 | 团队 | -| 2026-01-18 | 创建以 GitHub-Vercel 集成为重点的开发路线图 | 团队 | - ---- - - -**注意**：时间线和功能可能会根据团队资源、社区需求和平台能力进行调整。关注仓库获取实时更新。 - From a5cce6aca300da7f6dd90939f5af8e3ea18c71fc Mon Sep 17 00:00:00 2001 From: Jack Zhuang <50353452+hotlong@users.noreply.github.com> Date: Sun, 8 Feb 2026 19:35:15 +0800 Subject: [PATCH 6/6] =?UTF-8?q?=E5=88=A0=E9=99=A4=20packages.cn.mdx?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- content/docs/packages.cn.mdx | 290 ----------------------------------- 1 file changed, 290 deletions(-) delete mode 100644 content/docs/packages.cn.mdx diff --git a/content/docs/packages.cn.mdx b/content/docs/packages.cn.mdx deleted file mode 100644 index 1794e18..0000000 --- a/content/docs/packages.cn.mdx +++ /dev/null @@ -1,290 +0,0 @@ ---- -title: 软件包概览 -description: ObjectDocs 软件包完整概览，包含功能、开发状态和版本历史。 ---- - -import { Package, Terminal, Layout, Zap, CheckCircle, Clock } from 'lucide-react'; - -# 软件包概览 - -ObjectDocs 以 **pnpm 工作区 monorepo** 组织，包含两个核心软件包。本文档详细介绍每个软件包的功能、当前状态和开发历史。 - -**当前版本**: v0.2.12 | **最后更新**: 2026-02-08 - -## 软件包概要 - -| 软件包 | 版本 | 描述 | 状态 | -|--------|------|------|------| -| `@objectdocs/cli` | v0.2.12 | 构建和管理文档的命令行工具 | ✅ 稳定 | -| `@objectdocs/site` | v0.2.12 | Next.js 文档站点模板和渲染引擎 | ✅ 稳定 | - -## @objectdocs/cli - - -} title="CLI 工具"> - -ObjectDocs 的主要开发者接口。提供初始化、开发、构建和部署文档站点的命令。 - -- **框架**: CAC（命令行框架） -- **语言**: JavaScript/Node.js (ESM) -- **入口**: `bin/cli.mjs` - - - - -### 命令 - - - -### `objectdocs init` - -通过复制站点模板并设置开发环境来初始化新的文档项目。 - -**功能**: -- 将 `@objectdocs/site` 包复制到 `content/.fumadocs` -- 创建 `content/package.json`，包含 dev/build/start 脚本 -- 在 `content/.fumadocs` 中安装依赖 -- 更新 `.gitignore` 排除生成的文件 - -### `objectdocs dev [docsDir]` - -启动带热重载的开发服务器。 - -**功能**: -- 默认端口：7777（可配置） -- 监听 `docs.site.json` 变更并自动重启 -- 同步公共资源到站点引擎 -- 设置 `DOCS_DIR` 环境变量 - -### `objectdocs build [docsDir]` - -构建文档站点用于生产环境。 - -**功能**: -- 支持静态导出（`out/` 目录）和动态独立（`.next/`）模式 -- 复制配置和公共资源 -- 符号链接感知的构件复制，兼容 Vercel - -### `objectdocs start` - -启动生产服务器。 - -**功能**: -- 静态模式：使用 `serve` 从 `out/` 目录提供服务 -- 动态模式：运行 Next.js 生产服务器 -- 可配置端口 - -### `objectdocs translate` - -使用 OpenAI 的 AI 驱动内容翻译。 - -**功能**: -- 将 MDX 内容翻译为配置的语言 -- `--all` 参数用于批量翻译 -- CI 兼容，支持环境变量配置 -- 生成语言特定文件（如 `.cn.mdx`、`.ja.mdx`） - - - -### 依赖 - -| 依赖 | 版本 | 用途 | -|------|------|------| -| `@objectdocs/site` | workspace:* | 初始化用的站点模板 | -| `cac` | ^6.7.14 | CLI 框架 | -| `openai` | ^4.0.0 | AI 驱动的翻译 | -| `dotenv` | ^16.4.5 | 环境变量加载 | -| `typescript` | ^5.9.3 | TypeScript 支持 | - -### 功能状态 - -| 功能 | 状态 | 备注 | -|------|------|------| -| 项目初始化 | ✅ 已完成 | 完整的 `init` 工作流 | -| 开发服务器 | ✅ 已完成 | 热重载、配置监听 | -| 生产构建 | ✅ 已完成 | 静态 + 动态模式 | -| 生产服务器 | ✅ 已完成 | 静态 + 动态服务 | -| AI 翻译 | ✅ 已完成 | OpenAI 集成 | -| GitHub 集成 | ⬚ 规划中 | 第二阶段 | -| README 迁移 | ⬚ 规划中 | 第二阶段 | -| API 文档生成 | ⬚ 规划中 | 第二阶段 | - ---- - -## @objectdocs/site - - -} title="站点模板"> - -完整的 Next.js 应用模板，作为文档渲染引擎。基于 Fumadocs 构建，完整支持国际化。 - -- **框架**: Next.js 16 (App Router) + Fumadocs 16 -- **样式**: Tailwind CSS 4 -- **语言**: TypeScript -- **React**: v19 (Server Components) - - - - -### 核心功能 - - -} title="内容渲染"> - -- MDX 编译，支持 remark/rehype 插件 -- 代码语法高亮（Vesper 主题） -- 图片缩放功能 -- 内置组件：Callout、Card、Cards、Steps、Step -- 自动生成目录 - - -} title="站点引擎"> - -- 基于文件系统的路由 -- 全文搜索 API 端点 -- `meta.json` 驱动的导航树 -- 可配置的侧边栏、导航栏和页脚 -- 深色模式支持 - - - - -### 架构 - -| 组件 | 路径 | 描述 | -|------|------|------| -| 根布局 | `app/layout.tsx` | HTML 外壳、全局 Provider | -| 语言路由 | `app/[lang]/layout.tsx` | i18n 布局与 Fumadocs | -| 文档页面 | `app/[lang]/docs/[[...slug]]/page.tsx` | 动态 MDX 页面渲染 | -| 首页重定向 | `app/[lang]/page.tsx` | 重定向到文档根路径 | -| 搜索 API | `app/api/search/route.ts` | 全文搜索端点 | -| i18n 系统 | `lib/i18n.ts` | 6 语言支持及 UI 翻译 | -| 配置加载器 | `lib/config.ts` | `docs.site.json` 解析和默认值 | -| 源管理器 | `lib/source.ts` | 带 i18n 的 Fumadocs 内容源 | -| MDX 组件 | `mdx-components.tsx` | 自定义组件注册表 | -| 源配置 | `source.config.ts` | 内容目录和 MDX 插件配置 | - -### 国际化支持 - -6 种语言的预置 UI 翻译： - -| 语言 | 代码 | 目录标签 | 搜索 | 最后更新 | -|------|------|---------|------|---------| -| English | `en` | "On this page" | "Search" | "Last updated on" | -| 中文 | `cn` | "目录" | "搜索" | "最后更新于" | -| 日本語 | `ja` | "目次" | "検索" | "最終更新" | -| Français | `fr` | "Sur cette page" | "Rechercher" | "Dernière mise à jour" | -| Deutsch | `de` | "Auf dieser Seite" | "Suchen" | "Zuletzt aktualisiert am" | -| Español | `es` | "En esta página" | "Buscar" | "Última actualización" | - -### 配置选项 - -站点从 `docs.site.json` 读取配置，支持： - -- **站点元数据**：标题、描述、URL、图标 -- **品牌**：名称、Logo（明/暗）、主题色、边框圆角 -- **导航**：导航栏链接，含文本、URL、图标、外部标记 -- **侧边栏**：可折叠、预加载、默认展开层级、标签 -- **目录**：启用、深度 -- **页脚**：版权文本 -- **页面功能**：最后更新时间戳、在 GitHub 上编辑链接 -- **内容**：代码主题、图片缩放、数学公式支持 -- **国际化**：默认语言、语言列表 -- **构建**：模式（export/standalone） - -### 依赖 - -| 依赖 | 版本 | 用途 | -|------|------|------| -| `next` | ^16.1.2 | 应用框架 | -| `react` / `react-dom` | ^19.2.3 | UI 渲染 | -| `fumadocs-core` | ^16.4.7 | 文档引擎核心 | -| `fumadocs-ui` | ^16.4.7 | 文档 UI 组件 | -| `fumadocs-mdx` | ^14.2.5 | MDX 内容处理 | -| `tailwindcss` | ^4.1.18 | 实用优先 CSS | -| `typescript` | ^5.9.3 | 类型安全 | -| `openai` | ^4.0.0 | AI 功能 | -| `lucide-react` | ^0.562.0 | 图标库 | - -### 功能状态 - -| 功能 | 状态 | 备注 | -|------|------|------| -| MDX 渲染 | ✅ 已完成 | 完整的 Fumadocs 管道 | -| 国际化（6 种语言） | ✅ 已完成 | 基于文件 + UI 翻译 | -| 全文搜索 | ✅ 已完成 | API 端点 | -| 深色模式 | ✅ 已完成 | 通过 Fumadocs UI | -| 代码高亮 | ✅ 已完成 | Vesper 主题 | -| 图片缩放 | ✅ 已完成 | 可配置 | -| 独立输出 | ✅ 已完成 | Vercel/Docker 就绪 | -| 静态导出 | ✅ 已完成 | CDN 可部署 | -| 配置系统 | ✅ 已完成 | `docs.site.json` | -| ISR 支持 | ⬚ 规划中 | 第一阶段 | -| Edge Functions | ⬚ 规划中 | 第一阶段 | -| 数学渲染 | ⬚ 规划中 | 配置已存在，未启用 | - ---- - -## 版本历史 - -### v0.2.12（最新） -- 维护更新补丁发布 - -### v0.2.11 -- 修复：处理构建复制过程中的断裂符号链接，防止 Vercel 上的 ENOENT 错误 - -### v0.2.10 -- 新增：启用独立输出模式，更好支持 Vercel/Docker 部署 - -### v0.2.9 -- 修复：在 `tsconfig.json` 中添加 `.source` 路径别名以解析生成的文件 - -### v0.2.8 -- 修复：复制 `.next` 目录时使用 `dereference: true` 展开所有符号链接 - -### v0.2.7 -- 修复：使用相对导入替代生成内容的别名，避免 monorepo 中的别名解析问题 - -### v0.2.6 -- 修复：复制 `.next` 目录替代符号链接，支持 Vercel 部署 - -### v0.2.5 -- 优化：添加 `transpilePackages` 配置修复 monorepo 模块解析 - -### v0.2.4 -- 修复：重命名 `proxy.ts` 为 `middleware.ts`，修复 Next.js 16 构建错误 - -### v0.2.3 -- 修复：更新包元数据用于发布 - -### v0.2.2 -- 文档：更新 README，修正配置文件名称 - -### v0.2.1 -- Bug 修复和改进 - -### v0.2.0 -- 首次发布：基于 Next.js 14 和 Fumadocs 构建的现代文档引擎 - -### v0.1.0 -- 首次发布，包含元数据驱动架构、低代码组件嵌入、企业级 UI、多产品支持 - ---- - -## 入门模板 - -`examples/starter/` 中提供了示例入门模板： -- 预配置的 `docs.site.json`，ObjectStack 品牌 -- 示例文档结构 -- 带有 `meta.json` 导航的可直接运行的内容 - -```bash -# 使用入门模板快速开始 -cp -r examples/starter my-docs -cd my-docs -npm init @objectdocs -``` - - -详细技术架构请参阅[系统设计](/docs/design)文档。功能路线图请参阅[开发路线图](/docs/development-plan)。 -