zengen 0.1.36 → 0.2.0

package/src/process/extractMetadataByAI.ts

@@ -0,0 +1,29 @@
+import { readFile } from 'fs/promises';
+import { extractMetadataFromMarkdown } from '../ai/extractMetadataFromMarkdown';
+import { MetaData } from '../metadata';
+
+/**
+ * 运行 AI 元数据提取
+ */
+export async function extractMetadataByAI(): Promise<void> {
+  const { files } = MetaData;
+
+  if (MetaData.options.verbose) console.log(`🤖 Running AI metadata extraction...`);
+  console.log(`🤖 Processing ${files.length} files with AI...`);
+
+  for (const file of files) {
+    try {
+      if (file.metadata) {
+        console.info(`ℹ️ Skipping ${file.path}, already has metadata`);
+        continue;
+      }
+      const content = await readFile(file.path, 'utf-8');
+      file.metadata = await extractMetadataFromMarkdown(content);
+      console.log(`✅ Extracted AI metadata for ${file.path}`, file.metadata.tokens_used);
+    } catch (error) {
+      console.error(`⚠️ Failed to process file ${file.path}:`, error);
+    }
+  }
+
+  console.log(`✅ AI processing completed for ${files.length} files`);
+}

package/src/process/template.ts

@@ -0,0 +1,201 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { MetaData } from '../metadata';
+import { ZEN_DIST_DIR, ZEN_SRC_DIR } from '../paths';
+import { MetaDataStore } from '../types';
+import { convertMarkdownToHtml } from '../utils/convertMarkdownToHtml';
+import { parseFrontmatter } from '../utils/frontmatter';
+
+const langNames: Record<string, string> = {
+  'zh-Hans': '简体中文',
+  'en-US': 'English',
+  'ja-JP': '日本語',
+  'ko-KR': '한국어',
+};
+/**
+ * 生成语言切换器 HTML
+ * @param currentLang 当前语言
+ * @param availableLangs 可用语言列表
+ * @returns 语言切换器 HTML 字符串
+ */
+function generateLanguageSwitcher(templateData: TemplateData): string {
+  const {
+    options: { langs = [], baseUrl = '/' },
+  } = MetaData;
+
+  const items = langs
+    .map(lang => {
+      const langName = langNames[lang] || lang;
+      const isCurrent = lang === templateData.lang;
+      const activeClass = isCurrent ? 'active' : '';
+
+      return `<li class="lang-item ${activeClass}">
+        <a href="${path.join(baseUrl, lang, templateData.file.hash + '.html')}" class="lang-link">${langName}</a>
+      </li>`;
+    })
+    .join('');
+
+  return `<div class="language-switcher">
+    <span class="lang-label">Language:</span>
+    <ul class="lang-list">${items}</ul>
+  </div>`;
+}
+
+/**
+ * 生成导航 HTML
+ * @param navigation 导航树
+ * @param currentPath 当前路径（可选，用于高亮当前页面）
+ * @returns 导航 HTML 字符串
+ */
+async function generateNavigationHtml(data: TemplateData): Promise<string> {
+  const {
+    files,
+    options: { baseUrl = '/' },
+  } = MetaData;
+
+  const navigation = await Promise.all(
+    files.map(async file => {
+      const content = await fs.readFile(
+        path.join(ZEN_SRC_DIR, data.lang, file.hash + '.md'),
+        'utf-8'
+      );
+      const { frontmatter } = parseFrontmatter(content);
+      const title = frontmatter.title || file.metadata?.title || file.path; // 优先使用提取的标题
+
+      return {
+        title,
+        path: path.join(baseUrl, data.lang, file.hash + '.html'),
+        isActive: data.file.hash === file.hash,
+      };
+    })
+  );
+  navigation.sort((a, b) => a.title.localeCompare(b.title));
+
+  return `<ul class="nav-list">${navigation
+    .map(item => {
+      const activeClass = item.isActive ? 'active' : '';
+
+      let html = `<li class="nav-item">`;
+      html += `<a href="${item.path}" class="nav-link ${activeClass}">${item.title}</a>`;
+
+      html += `</li>`;
+      return html;
+    })
+    .join('')}</ul>`;
+}
+
+interface TemplateData {
+  file: MetaDataStore['files'][0];
+  content: string;
+  lang: string;
+}
+
+/**
+ * 简单的模板变量替换
+ * @param template 模板字符串
+ * @param data 模板数据
+ * @returns 渲染后的 HTML 字符串
+ */
+async function renderTemplate(template: string, data: TemplateData): Promise<string> {
+  const {
+    options: { langs = [] },
+  } = MetaData;
+  const markdownContent = data.content;
+  const { frontmatter, body } = parseFrontmatter(markdownContent);
+
+  const htmlContent = convertMarkdownToHtml(body);
+
+  let result = template;
+
+  // 替换导航
+  const navigationHtml = await generateNavigationHtml(data);
+  result = result.replace(/{{navigation}}/g, navigationHtml);
+
+  // 替换其他变量 - 使用全局替换
+  result = result.replace(/{{title}}/g, frontmatter.title || 'Untitled');
+  result = result.replace(/{{content}}/g, htmlContent);
+
+  // 替换元数据变量
+  if (frontmatter) {
+    result = result.replace(/{{summary}}/g, frontmatter.summary || '');
+    result = result.replace(/{{tags}}/g, frontmatter.tags?.join(', ') || '');
+    result = result.replace(/{{inferred_date}}/g, frontmatter.inferred_date || '');
+    result = result.replace(/{{inferred_lang}}/g, frontmatter.inferred_lang || '');
+  }
+
+  // 替换语言相关变量
+  result = result.replace(/{{lang}}/g, data.lang || '');
+  if (langs && langs.length > 1 && data.lang) {
+    const langSwitcher = generateLanguageSwitcher(data);
+    result = result.replace('{{language_switcher}}', langSwitcher);
+  }
+
+  return result;
+}
+
+const renderRedirectTemplate = async (from: string, to: string): Promise<void> => {
+  const {
+    options: { baseUrl = '/' },
+  } = MetaData;
+  const toURL = path.join(baseUrl, to);
+  const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta http-equiv="refresh" content="0; url=${toURL}">
+    <title>Redirecting...</title>
+</head>
+<body>
+    <p>Redirecting to <a href="${toURL}">${toURL}</a></p>
+</body>
+</html>`;
+  const targetPath = path.join(ZEN_DIST_DIR, from);
+  await fs.mkdir(path.dirname(targetPath), { recursive: true });
+  await fs.writeFile(targetPath, html, 'utf-8');
+};
+
+/**
+ * 渲染模板并保存文件
+ */
+export async function renderTemplates(): Promise<void> {
+  const {
+    files,
+    options: { langs, verbose },
+  } = MetaData;
+
+  if (verbose) console.log(`⚡ Processing files...`);
+  const layoutTemplate = await fs.readFile(
+    path.join(__dirname, '../../assets/templates/default/layout.html'),
+    'utf-8'
+  );
+
+  for (const file of files) {
+    for (const lang of langs || []) {
+      console.info(`📄 Preparing file for language: ${file.path} [${file.hash}] [${lang}]`);
+      const targetPath = path.join(ZEN_DIST_DIR, lang, file.hash + '.html');
+      const content = await fs.readFile(path.join(ZEN_SRC_DIR, lang, file.hash + '.md'), 'utf-8');
+      try {
+        const html = await renderTemplate(layoutTemplate, {
+          file,
+          content,
+          lang,
+        });
+        await fs.mkdir(path.dirname(targetPath), { recursive: true });
+        await fs.writeFile(targetPath, html, 'utf-8');
+        if (verbose) console.log(`✅ Rendered: ${targetPath}`);
+      } catch (error) {
+        console.error(`❌ Failed to render ${file.path}:`, error);
+      }
+    }
+  }
+
+  for (const lang of langs || []) {
+    await renderRedirectTemplate(
+      path.join(lang, 'index.html'),
+      path.join(lang, files[0].hash + '.html')
+    );
+  }
+  await renderRedirectTemplate('index.html', path.join(langs?.[0] || 'en-US', 'index.html'));
+}

package/src/scan/files.ts

@@ -0,0 +1,17 @@
+import * as crypto from 'crypto';
+import * as fs from 'fs/promises';
+
+/**
+ * 计算文件内容的 SHA256 哈希值
+ * @param filePath 文件路径
+ * @returns 文件的哈希值，如果读取失败则返回空字符串
+ */
+export async function calculateFileHash(filePath: string): Promise<string> {
+  try {
+    const content = await fs.readFile(filePath, 'utf-8');
+    return crypto.createHash('sha256').update(content).digest('hex');
+  } catch (error) {
+    console.warn(`⚠️ Failed to calculate hash for ${filePath}:`, error);
+    return '';
+  }
+}

package/src/services/openai.ts

@@ -0,0 +1,92 @@
+/**
+ * OpenAI 消息接口
+ */
+export interface OpenAIMessage {
+  role: 'system' | 'user' | 'assistant';
+  content: string;
+}
+
+/**
+ * OpenAI 响应接口
+ */
+export interface OpenAIResponse {
+  id: string;
+  object: string;
+  created: number;
+  model: string;
+  choices: Array<{
+    index: number;
+    message: {
+      role: string;
+      content: string;
+    };
+    finish_reason: string;
+  }>;
+  usage: {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+  };
+}
+
+/**
+ * 使用 OpenAI API 补全消息
+ * @param messages 消息数组
+ * @param options 可选配置
+ * @returns Promise<OpenAIResponse> 返回完整的OpenAI响应
+ */
+export const completeMessages = async (
+  messages: OpenAIMessage[],
+  options?: {
+    response_format?: { type: 'json_object' | 'text' };
+  }
+): Promise<OpenAIResponse> => {
+  // 从环境变量读取配置
+  const apiKey = process.env.OPENAI_API_KEY || '';
+  const baseUrl = process.env.OPENAI_BASE_URL || 'https://api.openai.com/v1';
+  const model = process.env.OPENAI_MODEL || 'gpt-3.5-turbo';
+
+  if (!apiKey) {
+    throw new Error('OPENAI_API_KEY environment variable is not set');
+  }
+
+  try {
+    const requestBody: any = {
+      model,
+      messages,
+      temperature: 0, // 总是设置为 0，提取内容不需要随机性
+      // 不设置 max_tokens，让API自动决定
+    };
+
+    // 添加可选的response_format
+    if (options?.response_format) {
+      requestBody.response_format = options.response_format;
+    }
+
+    const response = await fetch(`${baseUrl}/chat/completions`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${apiKey}`,
+      },
+      body: JSON.stringify(requestBody),
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      throw new Error(`OpenAI API error (${response.status}): ${errorText}`);
+    }
+
+    const data: OpenAIResponse = await response.json();
+
+    // 验证响应
+    if (!data.choices?.[0]?.message?.content?.trim()) {
+      throw new Error('Empty response from OpenAI API');
+    }
+
+    return data;
+  } catch (error) {
+    console.error('❌ Failed to call OpenAI API:', error);
+    throw error;
+  }
+};

package/src/types.ts

@@ -1,34 +1,28 @@
+/**
+ * 单个文件的元数据缓存项
+ */
+export interface FileMetaData {
+  hash: string;
+  path: string;
+  metadata?: AIMetadata;
+}
+
+/**
+ * .zen/meta.json 文件结构
+ */
+export interface MetaDataStore {
+  version: string;
+  options: BuildOptions;
+  files: FileMetaData[];
+}
+
 export interface BuildOptions {
-  srcDir: string;
-  outDir: string;
   template?: string;
-  watch?: boolean;
   verbose?: boolean;
-  serve?: boolean;
-  port?: number;
-  host?: string;
   baseUrl?: string;
   langs?: string[]; // 目标语言数组
 }
 
-export interface ScannedFile {
-  path: string; // 相对路径
-  name: string;
-  ext: string;
-  hash?: string; // 文件内容的 sha256 hash
-}
-
-export interface FileInfo {
-  path: string; // 相对路径
-  name: string;
-  ext: string;
-  content: string;
-  html?: string;
-  metadata?: { title: string }; // 简化，只保留标题
-  hash?: string; // 文件内容的 sha256 hash
-  aiMetadata?: AIMetadata; // AI 提取的元数据
-}
-
 export interface AIMetadata {
   title: string; // AI 提取的标题
   summary: string; // AI 提取的摘要，控制在 100字以内
@@ -41,51 +35,3 @@ export interface AIMetadata {
     total: number;
   }; // tokens 使用情况
 }
-
-export interface NavigationItem {
-  title: string;
-  path: string;
-  children?: NavigationItem[];
-}
-
-export interface TemplateData {
-  title: string;
-  content: string;
-  navigation: NavigationItem[];
-  metadata?: AIMetadata; // 使用完整的 AI 元数据
-  currentPath?: string;
-  lang?: string; // 当前语言
-  availableLangs?: string[]; // 可用的语言列表
-}
-
-export interface MarkdownProcessor {
-  beforeParse?(content: string, fileInfo: FileInfo): string | Promise<string>;
-  afterParse?(html: string, fileInfo: FileInfo): string | Promise<string>;
-}
-
-export interface ZenConfig {
-  srcDir?: string;
-  outDir?: string;
-  template?: string;
-  baseUrl?: string;
-  i18n?: {
-    sourceLang: string;
-    targetLangs: string[];
-    apiKey?: string;
-  };
-  ai?: {
-    enabled?: boolean;
-    model?: string;
-    temperature?: number;
-    maxTokens?: number;
-  };
-  processors?: MarkdownProcessor[];
-  includePattern?: string;
-  excludePattern?: string;
-}
-
-export interface MultiLangBuildOptions extends BuildOptions {
-  langs: string[]; // 必须指定目标语言
-  useMetaData?: boolean; // 是否使用 meta.json 中的元数据
-  filterOrphans?: boolean; // 是否过滤孤儿文件
-}

package/src/utils/convertMarkdownToHtml.ts

@@ -0,0 +1,32 @@
+import { marked } from 'marked';
+import hljs from 'highlight.js';
+
+// 配置 marked 使用 highlight.js 进行代码高亮
+marked.setOptions({
+  highlight: function (code: string, lang: string) {
+    if (lang && hljs.getLanguage(lang)) {
+      try {
+        return hljs.highlight(code, { language: lang }).value;
+      } catch (err) {
+        console.warn(`Failed to highlight code with language ${lang}:`, err);
+      }
+    }
+    return hljs.highlightAuto(code).value;
+  },
+  pedantic: false,
+  gfm: true,
+  breaks: false,
+  sanitize: false,
+  smartLists: true,
+  smartypants: false,
+  xhtml: false,
+} as any);
+
+/**
+ * 将 Markdown 内容转换为 HTML
+ * @param mdContent Markdown 内容字符串
+ * @returns 转换后的 HTML 字符串
+ */
+export const convertMarkdownToHtml = (mdContent: string): string => {
+  return marked.parse(mdContent) as string;
+};

package/src/utils/frontmatter.ts

@@ -0,0 +1,18 @@
+import { parse, stringify } from 'yaml';
+
+export const parseFrontmatter = (content: string): { frontmatter: any; body: string } => {
+  const frontmatterRegex = /^---\n([\s\S]*?)\n---/;
+  const match = content.match(frontmatterRegex);
+  if (match) {
+    const frontmatterContent = match[1];
+    const body = content.slice(match[0].length).trim();
+    return { frontmatter: parse(frontmatterContent.trim()), body };
+  }
+  return { frontmatter: {}, body: content };
+};
+
+export const updateFrontmatter = (content: string, newFrontmatter: any): string => {
+  const { body } = parseFrontmatter(content);
+  const frontmatterContent = `---\n${stringify(newFrontmatter)}---\n\n`;
+  return frontmatterContent + body;
+};

package/.zen/translations.json

@@ -1,51 +0,0 @@
-[
-  {
-    "sourceHash": "1b798c44a4f353e47296ca83d5905e37e6aba3e90bbd9bc3b3d34fc12059a2ca",
-    "sourceLang": "zh-Hans",
-    "targetLang": "en-US",
-    "translatedContent": "# ZEN - A Minimalist Markdown Documentation Site Builder\n\n> 📖 **Reading Note**: This README is the Chinese version. The English version will be automatically generated by AI translation.\n\n## Project Motivation\n\n### Return to Content\n\nI enjoy contemplation, but I don't want to deal with complex build tools, fiddle with intricate documentation configurations, or navigate complicated structures.\n\n### Return to Native Language\n\nLife is short, I use AI for translation. Stay connected with the world.\n\n## Core Features\n\n1.  **Static Site Generation**\n    *   Builds any folder containing Markdown files into a static HTML site.\n\n2.  **Intelligent Navigation**\n    *   Generates a site map and navigation automatically, without requiring you to maintain the original directory structure of your Markdown source files.\n\n3.  **Incremental i18n Translation**\n    *   Utilizes LLMs for incremental internationalization (i18n) translation. Write your Markdown in your native language, while your audience can be multilingual.\n\n## Design Philosophy\n\n*   **Minimalism**: Minimal configuration, maximum flexibility.\n*   **Content-First**: Focus on writing, not tool configuration.\n*   **AI-Powered**: Leverage AI for translation and content organization.\n*   **Cross-Language**: Supports multilingual content creation and presentation.\n\n## Quick Start\n\n### Recommended Usage\n\n**It is recommended to switch to the directory containing your Markdown files and start building directly with the following command:**\n\n```bash\nnpx zengen build\n```\n\n### Other Usages\n\n1.  **Live Preview (Watch for file changes)**:\n\n```bash\nnpx zengen build --watch\n```\n\n2.  **View more parameters or help**:\n\n```bash\nnpx zengen\n```\n\n**Note**: ZEN enforces using the current directory as the source directory and outputs to the `.zen/dist` directory. Specifying source and output directory parameters is no longer supported.\n\n---\n\n**ZEN** - Return documentation to its essence, return writing to tranquility.",
-    "lastUpdated": "2026-01-05T14:12:28.056Z"
-  },
-  {
-    "sourceHash": "5ec990146b35e00de2630559126ee07f7cdcddeb23b0e8cab3d85b4181353e26",
-    "sourceLang": "zh-Hans",
-    "targetLang": "en-US",
-    "translatedContent": "# Advanced Usage\n\nIn-depth introduction to ZEN's advanced features and configuration options.\n\n## Custom Templates\n\nZEN supports custom HTML templates:\n\n```bash\nzengen build --src ./docs --out ./dist --template ./custom-template.html\n```\n\n## Configuration Options\n\nCan be configured in the `.zenrc` file:\n\n```json\n{\n  \"srcDir\": \"./docs\",\n  \"outDir\": \"./dist\",\n  \"template\": \"./template.html\",\n  \"baseUrl\": \"https://example.com\",\n  \"i18n\": {\n    \"sourceLang\": \"zh-Hans\",\n    \"targetLangs\": [\"en-US\", \"ja-JP\"]\n  }\n}\n```\n\n## Plugin System\n\nZEN supports plugin extensions:\n\n```typescript\ninterface MarkdownProcessor {\n  beforeParse?(content: string, fileInfo: FileInfo): string | Promise<string>;\n  afterParse?(html: string, fileInfo: FileInfo): string | Promise<string>;\n}\n```",
-    "lastUpdated": "2026-01-05T14:12:35.392Z"
-  },
-  {
-    "sourceHash": "d49012f98c4367b34034063400e2f7826bf0615952210c82396920172d468e2c",
-    "sourceLang": "zh-Hans",
-    "targetLang": "en-US",
-    "translatedContent": "# GitHub Pages Deployment Configuration\n\nThis directory contains the GitHub Pages deployment configuration for the ZEN project documentation site.\n\n## Workflow\n\n### `pages.yml`\n\nThis workflow automatically builds the ZEN project documentation site and deploys it to GitHub Pages.\n\n**Triggers:**\n\n- Push to the `main` branch (when changes occur in `demo/src/`, `package.json`, or workflow files)\n- Pull Request targeting the `main` branch\n- Manual trigger\n\n**Workflow Steps:**\n\n1.  **Checkout code**: Check out code from the remote branch to ensure code synchronization.\n2.  **Set up Node.js**: Configure the Node.js 20.x environment.\n3.  **Install dependencies**: Install project dependencies using `npm ci`.\n4.  **Build zengen**: Build the local zengen package.\n5.  **Install zengen**: Install the locally built zengen as a global tool.\n6.  **Test zengen CLI**: Verify the CLI tool functions correctly.\n7.  **Build documentation site**: Build the documentation using `cd demo/src && zengen build`, outputting to the `.zen/dist` directory.\n8.  **Configure Pages**: Set up GitHub Pages.\n9.  **Upload artifact**: Upload the built documentation site as a Pages artifact.\n10. **Deploy to GitHub Pages**: Automatically deploy to GitHub Pages.\n\n## Accessing the Documentation Site\n\nAfter successful deployment, the documentation site will be accessible at the following URL:\n\n```\nhttps://[username].github.io/[repository-name]/\n```\n\n## Custom Configuration\n\n### Custom Domain\n\nIf you need to use a custom domain, you can add a CNAME file after the build step:\n\n```yaml\n# Create CNAME file (if a custom domain is needed)\necho \"docs.example.com\" > docs-dist/CNAME\n```\n\n### Build Options\n\nThe currently used build command:\n\n```bash\ncd demo/src\nzengen build --clean --verbose\n```\n\nAvailable options:\n\n- `--clean`: Clean the output directory before building.\n- `--verbose`: Show verbose output.\n- `--watch`: Watch mode (not suitable for CI/CD).\n- `--template`: Specify a custom template file.\n- `--config`: Specify a configuration file.\n\n### Environment Variables\n\nThe workflow uses the following environment variables:\n\n- `GITHUB_TOKEN`: Automatically provided GitHub token.\n- `NODE_VERSION`: Node.js version (defaults to 20.x).\n\n## Troubleshooting\n\n### Build Failures\n\n1.  **Check Node.js version**: Ensure a supported Node.js version is used.\n2.  **Verify dependency installation**: Ensure `npm ci` executes successfully.\n3.  **Check build output**: Review the verbose output of `zengen build`.\n4.  **CLI output directory issue**: ZEN now enforces output to the `.zen/dist` directory and no longer supports the `--out` parameter.\n\n### Deployment Failures\n\n1.  **Check permissions**: Ensure the workflow has correct write permissions for Pages.\n2.  **Verify artifact**: Ensure the `.zen/dist` directory contains valid HTML files.\n3.  **Review logs**: Check GitHub Actions logs for detailed error messages.\n\n### Documentation Not Updating\n\n1.  **Check triggers**: Ensure files in the `demo/src/` directory were modified.\n2.  **Wait for deployment completion**: GitHub Pages deployment may take a few minutes.\n3.  **Clear browser cache**: The browser might be caching an old version.\n\n## Manual Trigger\n\nDeployment can be manually triggered via the GitHub Actions interface:\n\n1.  Go to the repository's \"Actions\" tab.\n2.  Select the \"Deploy to GitHub Pages\" workflow.\n3.  Click the \"Run workflow\" button.\n4.  Select the branch and run.\n\n## Related Files\n\n- `demo/src/`: Documentation source files (Markdown format).\n- `package.json`: Project configuration and dependencies.\n- `src/cli.ts`: zengen CLI tool implementation.\n- `src/builder.ts`: Documentation builder implementation.",
-    "lastUpdated": "2026-01-05T14:13:01.694Z"
-  },
-  {
-    "sourceHash": "f0c2799126931ccd113a0c45b1e623870b0d4f4f400becf6dd877da8f1011517",
-    "sourceLang": "zh-Hans",
-    "targetLang": "en-US",
-    "translatedContent": "# Quick Start Guide\n\nThis document explains how to quickly get started with the ZEN documentation generator.\n\n## Installation\n\n```bash\nnpm install -g zengen\n```\n\n## Basic Usage\n\n1. Create a documentation directory\n2. Write Markdown files\n3. Run the build command\n\n```bash\nzengen build --src ./docs --out ./dist\n```\n\n## Features\n\n- Minimal configuration\n- Built-in responsive templates\n- AI-assisted metadata extraction\n- Multi-language support",
-    "lastUpdated": "2026-01-05T14:13:05.710Z"
-  },
-  {
-    "sourceHash": "6ad8db715a1b60613fe934fefb29fa981ecad9b63145593accff144d73b44bde",
-    "sourceLang": "zh-Hans",
-    "targetLang": "en-US",
-    "translatedContent": "# Best Practices\n\nThis document introduces best practices for building documentation sites using ZEN.\n\n## Multilingual Management\n\n### Translation Strategy\n\n1. **Primary Language First**: Write the complete documentation in the native language first.\n2. **Incremental Translation**: Only translate modified parts after each update.\n3. **Terminology Consistency**: Create a glossary to maintain translation consistency.\n4. **Manual Review**: It is recommended to manually review AI translations.\n\n## Performance Optimization\n\n### Build Optimization\n\n1. **Incremental Builds**: Use `--watch` mode for development.\n2. **Cache Utilization**: ZEN automatically caches processing results.\n3. **Parallel Processing**: Automatically processes files in parallel on multi-core CPUs.\n\n### Development Workflow\n\n```bash\n# Watch for changes during development\ncd docs\nnpx zengen build --watch\n\n# Start development server\nnpx zengen build --watch --serve\n\n# Production build\nnpx zengen build --clean\n```\n\n## Deployment Strategy\n\n### CI/CD Integration\n\n#### GitHub Actions Example\n\n```yaml\nname: Build and Deploy Documentation\non:\n  push:\n    branches: [main]\n    paths:\n      - 'docs/**'\n      - '.github/workflows/docs.yml'\n\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout repository\n        uses: actions/checkout@v4\n\n      - name: Setup Node.js\n        uses: actions/setup-node@v4\n        with:\n          node-version: '20.x'\n\n      - name: Build documentation\n        run: |\n          cd docs\n          npx zengen build --clean --base-url /my-docs\n\n      - name: Deploy to GitHub Pages\n        uses: peaceiris/actions-gh-pages@v3\n        with:\n          github_token: ${{ secrets.GITHUB_TOKEN }}\n          publish_dir: docs/.zen/dist\n```\n\n#### Custom Deployment Script\n\n```bash\n#!/bin/bash\n# deploy-docs.sh\n\n# Switch to the documentation directory\ncd docs\n\n# Clean and build\nnpx zengen build --clean\n\n# Sync to server\nrsync -avz .zen/dist/ user@server:/var/www/docs/\n\n# Clean cache\nrm -rf .zen/cache\n```\n\n### Cloud Deployment Options\n\n- **GitHub Pages**: Free hosting for documentation.\n- **Vercel**: Automatic deployment of static sites.\n- **Netlify**: Supports form handling and redirects.\n- **AWS S3 + CloudFront**: Enterprise-grade static hosting.\n\n## Maintenance Recommendations\n\n### Regular Updates\n\n1. **Content Review**: Check documentation accuracy monthly.\n2. **Link Checking**: Regularly check for broken links.\n3. **Performance Monitoring**: Monitor page load speed.\n4. **User Feedback**: Collect user feedback to improve documentation.\n\n### Version Control\n\n1. **Document Versioning**: Synchronize with software versions.\n2. **Change Log**: Record documentation update history.\n3. **Rollback Mechanism**: Support quick rollback to previous versions.\n\n## Frequently Asked Questions\n\n### Slow Build Speed\n\n**Solutions:**\n\n- Reduce unnecessary images and resources.\n- Use `--watch` mode for incremental development.\n- Split large documents into multiple smaller files.\n- Disable unnecessary processors.\n\n### Poor Translation Quality\n\n**Solutions:**\n\n- Provide context for AI translation.\n- Create a glossary to improve consistency.\n- Manually review critical content.\n- Adjust translation prompts.\n\n### Complex Navigation Structure\n\n**Solutions:**\n\n- Maintain a flat directory structure.\n- Use clear heading hierarchies.\n- Provide search functionality.\n- Use sidebar navigation appropriately.\n\n### High Memory Usage\n\n**Solutions:**\n\n- Reduce the number of files processed simultaneously.\n- Disable caching (not recommended).\n- Increase system memory.\n- Process large documents in batches.\n\n## Advanced Techniques\n\n### Custom Template Tips\n\n1. **Responsive Design**: Ensure templates display correctly on mobile devices.\n2. **Theme Switching**: Implement dark/light themes.\n3. **Syntax Highlighting**: Integrate highlight.js or other highlighting libraries.\n4. **Search Functionality**: Add client-side search.\n\n### Integrating Other Tools\n\n1. **Image Optimization**: Use sharp or imagemin to optimize images.\n2. **SEO Optimization**: Add meta tags and structured data.\n3. **Analytics Integration**: Integrate Google Analytics or Plausible.\n4. **CDN Acceleration**: Use a CDN to accelerate static resources.\n\n### Monitoring and Logging\n\n1. **Build Logs**: Use `--verbose` to view detailed logs.\n2. **Error Monitoring**: Set up error monitoring and alerts.\n3. **Performance Monitoring**: Monitor build time and resource usage.\n4. **User Analytics**: Analyze documentation usage.",
-    "lastUpdated": "2026-01-05T14:13:35.974Z"
-  },
-  {
-    "sourceHash": "a1580f71c6c6c1ff4a314be72d410a8507af2f087d56360c7f5048d349c21953",
-    "sourceLang": "zh-Hans",
-    "targetLang": "en-US",
-    "translatedContent": "# Configuration Guide\n\nZEN's design philosophy is minimalism, so configuration is very simple.\n\n## Command Line Usage\n\n### Basic Commands\n\n```bash\n# Build documentation (recommended usage)\nnpx zengen build\n\n# Live preview (watch for file changes)\nnpx zengen build --watch\n\n# Start development server (requires --watch)\nnpx zengen build --watch --serve\n\n# Custom port\nnpx zengen build --watch --serve --port 8080\n\n# Clean output directory\nnpx zengen build --clean\n\n# Show verbose logs\nnpx zengen build --verbose\n\n# Set base URL\nnpx zengen build --base-url /my-docs\n\n# View help\nnpx zengen\n```\n\n**Important Notes:**\n\n- ZEN enforces the current directory as the source directory and outputs to the `.zen/dist` directory\n- Specifying source and output directories via command-line arguments is no longer supported\n- When using `--watch` mode, modifying files triggers automatic rebuilds\n\n### Command Line Options\n\n| Option         | Short | Description                             | Default     |\n| -------------- | ----- | --------------------------------------- | ----------- |\n| `--watch`      | `-w`  | Watch for file changes and auto-rebuild | `false`     |\n| `--serve`      | `-s`  | Start dev server (requires `--watch`)   | `false`     |\n| `--port`       | `-p`  | Development server port                 | `3000`      |\n| `--host`       |       | Development server host                 | `localhost` |\n| `--verbose`    | `-v`  | Show verbose logs                       | `false`     |\n| `--clean`      |       | Clean output directory                  | `false`     |\n| `--base-url`   |       | Site base URL                           | None        |\n| `--help`       | `-h`  | Show help information                   | None        |",
-    "lastUpdated": "2026-01-05T14:13:50.036Z"
-  },
-  {
-    "sourceHash": "fdfca9b960d0eaa8b2b96fe988ead7481d2c0b16f66ebc94fb477139b4178cdc",
-    "sourceLang": "zh-Hans",
-    "targetLang": "en-US",
-    "translatedContent": "# ZEN Documentation Site Example\n\nWelcome to the ZEN documentation builder! This is a minimalist Markdown documentation site generator.\n\n## Features\n\n- **Minimal Configuration**: No complex configuration files required\n- **Content-First**: Focus on writing, not tool configuration\n- **Smart Navigation**: Automatically generates site maps and navigation\n- **Multi-Language Support**: Supports incremental i18n translation\n\n## Quick Start\n\n```bash\n# Build documentation using npx (recommended)\nnpx zengen build\n\n# Live preview (watch for file changes)\nnpx zengen build --watch\n\n# View more parameters or help\nnpx zengen\n```\n\n**Note**: ZEN enforces the use of the current directory as the source directory and outputs to the `.zen/dist` directory. Specifying source and output directory parameters is no longer supported.\n\n## Code Examples\n\n```javascript\n// This is a JavaScript example\nconst zen = require('zengen');\n\nasync function buildDocs() {\n  await zen.build({\n    // ZEN now enforces using the current directory as the source\n    // Outputs to the .zen/dist directory\n  });\n}\n```\n\n```python\n# This is a Python example\ndef hello_world():\n    print(\"Hello from ZEN!\")\n```\n\n## Next Steps\n\n1. Read the [API Documentation](./api.md)\n2. Check the [Configuration Guide](./config.md)\n3. Learn about [Best Practices](./best-practices.md)",
-    "lastUpdated": "2026-01-05T14:14:00.234Z"
-  }
-]

package/dist/ai-client.d.ts

@@ -1,34 +0,0 @@
-import { AIMetadata } from './types';
-import { AIService } from './ai-service';
-/**
- * AI 客户端类 - 使用 fetch 调用 OpenAI 兼容 API
- */
-export declare class AIClient {
-    private aiService;
-    constructor(aiService: AIService);
-    /**
-     * 调用 AI 模型提取文档 metadata
-     */
-    extractMetadata(content: string, filePath: string): Promise<AIMetadata | null>;
-    /**
-     * 构建提取 metadata 的 prompt
-     */
-    private buildMetadataPrompt;
-    /**
-     * 调用 OpenAI 兼容 API
-     */
-    private callOpenAIAPI;
-    /**
-     * 解析 AI 返回的 metadata
-     */
-    private parseMetadataResponse;
-    /**
-     * 批量处理文件
-     */
-    processFiles(files: Array<{
-        content: string;
-        path: string;
-        hash: string;
-    }>): Promise<Map<string, AIMetadata>>;
-}
-//# sourceMappingURL=ai-client.d.ts.map

package/dist/ai-client.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ai-client.d.ts","sourceRoot":"","sources":["../src/ai-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,SAAS,EAAY,MAAM,cAAc,CAAC;AAyBnD;;GAEG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,SAAS,CAAY;gBAEjB,SAAS,EAAE,SAAS;IAIhC;;OAEG;IACG,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAsCpF;;OAEG;IACH,OAAO,CAAC,mBAAmB;IAgC3B;;OAEG;YACW,aAAa;IAyC3B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA2B7B;;OAEG;IACG,YAAY,CAChB,KAAK,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,GAC5D,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CAmCpC"}