zengen 0.1.35 → 0.1.36

package/src/template.ts

@@ -268,6 +268,35 @@ export class TemplateEngine {
 </body>
 </html>`;
 
+  /**
+   * 生成语言切换器 HTML
+   */
+  private generateLanguageSwitcher(currentLang: string, availableLangs: string[]): string {
+    const langNames: Record<string, string> = {
+      'zh-Hans': '简体中文',
+      'en-US': 'English',
+      'ja-JP': '日本語',
+      'ko-KR': '한국어',
+    };
+
+    const items = availableLangs
+      .map(lang => {
+        const langName = langNames[lang] || lang;
+        const isCurrent = lang === currentLang;
+        const activeClass = isCurrent ? 'active' : '';
+
+        return `<li class="lang-item ${activeClass}">
+        <a href="?lang=${lang}" 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
    */
@@ -306,6 +335,21 @@ export class TemplateEngine {
     result = result.replace(/{{title}}/g, data.title || 'Untitled');
     result = result.replace(/{{{content}}}/g, data.content || '');
 
+    // 替换元数据变量
+    if (data.metadata) {
+      result = result.replace(/{{summary}}/g, data.metadata.summary || '');
+      result = result.replace(/{{tags}}/g, data.metadata.tags?.join(', ') || '');
+      result = result.replace(/{{inferred_date}}/g, data.metadata.inferred_date || '');
+      result = result.replace(/{{inferred_lang}}/g, data.metadata.inferred_lang || '');
+    }
+
+    // 替换语言相关变量
+    result = result.replace(/{{lang}}/g, data.lang || '');
+    if (data.availableLangs && data.availableLangs.length > 0 && data.lang) {
+      const langSwitcher = this.generateLanguageSwitcher(data.lang, data.availableLangs);
+      result = result.replace('{{language_switcher}}', langSwitcher);
+    }
+
     return result;
   }
 
@@ -332,23 +376,39 @@ export class TemplateEngine {
   /**
    * 从文件信息生成模板数据
    */
-  generateTemplateData(fileInfo: FileInfo, navigation: NavigationItem[]): TemplateData {
+  generateTemplateData(
+    fileInfo: FileInfo,
+    navigation: NavigationItem[],
+    lang?: string,
+    availableLangs?: string[]
+  ): TemplateData {
+    // 优先使用 AI 元数据中的标题，其次使用文件元数据，最后使用文件名
+    const title = fileInfo.aiMetadata?.title || fileInfo.metadata?.title || fileInfo.name;
+
     return {
-      title: fileInfo.metadata?.title || fileInfo.name, // 优先使用提取的标题，如果没有则使用文件名
+      title,
       content: fileInfo.html || '',
       navigation,
-      metadata: fileInfo.metadata,
-      currentPath: `/${fileInfo.relativePath.replace(/\.md$/, '.html')}`,
+      metadata: fileInfo.aiMetadata, // 使用完整的 AI 元数据
+      currentPath: `/${fileInfo.path.replace(/\.md$/, '.html')}`,
+      lang,
+      availableLangs,
     };
   }
 
   /**
    * 生成输出文件路径
    */
-  getOutputPath(fileInfo: FileInfo, outDir: string): string {
-    const htmlFileName = `${fileInfo.name}.html`;
-    const relativeDir = path.dirname(fileInfo.relativePath);
-    return path.join(outDir, relativeDir, htmlFileName);
+  getOutputPath(fileInfo: FileInfo, outDir: string, lang?: string, hash?: string): string {
+    if (lang && hash) {
+      // 多语言模式：.zen/dist/{lang}/{hash}.html
+      return path.join(outDir, lang, `${hash}.html`);
+    } else {
+      // 传统模式：保持目录结构
+      const htmlFileName = `${fileInfo.name}.html`;
+      const relativeDir = path.dirname(fileInfo.path);
+      return path.join(outDir, relativeDir, htmlFileName);
+    }
   }
 
   /**

package/src/translation-service.ts

@@ -0,0 +1,350 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as crypto from 'crypto';
+import { AIMetadata, FileInfo } from './types';
+import { AIService } from './ai-service';
+
+/**
+ * 翻译缓存项
+ */
+export interface TranslationCache {
+  sourceHash: string;      // 源文件hash
+  sourceLang: string;      // 源语言
+  targetLang: string;      // 目标语言
+  translatedContent: string; // 翻译后的内容
+  lastUpdated: string;     // 最后更新时间
+}
+
+/**
+ * 翻译服务配置
+ */
+export interface TranslationConfig {
+  enabled: boolean;
+  apiKey: string;
+  baseUrl: string;
+  model: string;
+  temperature: number;
+  maxTokens: number;
+}
+
+/**
+ * 翻译服务类
+ */
+export class TranslationService {
+  private config: TranslationConfig;
+  private aiService: AIService;
+  private translationCachePath: string;
+
+  constructor(config: Partial<TranslationConfig> = {}) {
+    // 从环境变量读取配置
+    const apiKey = process.env.OPENAI_API_KEY || '';
+    const baseUrl = process.env.OPENAI_BASE_URL || 'https://api.openai.com/v1';
+
+    // 配置优先级：构造函数参数 > 环境变量 > 默认值
+    const model = config.model || process.env.OPENAI_MODEL || 'gpt-3.5-turbo';
+
+    this.config = {
+      enabled: config.enabled ?? apiKey !== '',
+      apiKey,
+      baseUrl,
+      model,
+      temperature: 0, // 总是设置为 0，翻译不需要随机性
+      maxTokens: config.maxTokens || 2000,
+    };
+
+    this.aiService = new AIService();
+    this.translationCachePath = path.join(process.cwd(), '.zen', 'translations.json');
+  }
+
+  /**
+   * 检查是否启用翻译功能
+   */
+  isEnabled(): boolean {
+    const enabled = this.config.enabled && this.config.apiKey !== '';
+    if (!enabled && this.config.enabled) {
+      console.warn(
+        '⚠️ Translation is enabled but API key is missing. Please set OPENAI_API_KEY environment variable.'
+      );
+    }
+    return enabled;
+  }
+
+  /**
+   * 加载翻译缓存
+   */
+  async loadTranslationCache(): Promise<TranslationCache[]> {
+    try {
+      await fs.access(this.translationCachePath);
+      const content = await fs.readFile(this.translationCachePath, 'utf-8');
+      return JSON.parse(content);
+    } catch (error) {
+      // 如果文件不存在，返回空数组
+      return [];
+    }
+  }
+
+  /**
+   * 保存翻译缓存
+   */
+  async saveTranslationCache(cache: TranslationCache[]): Promise<void> {
+    // 确保 .zen 目录存在
+    const zenDir = path.dirname(this.translationCachePath);
+    await fs.mkdir(zenDir, { recursive: true });
+
+    // 保存文件
+    await fs.writeFile(this.translationCachePath, JSON.stringify(cache, null, 2), 'utf-8');
+  }
+
+  /**
+   * 获取缓存的翻译
+   */
+  async getCachedTranslation(
+    sourceHash: string,
+    sourceLang: string,
+    targetLang: string
+  ): Promise<string | null> {
+    if (!this.isEnabled()) {
+      return null;
+    }
+
+    try {
+      const cache = await this.loadTranslationCache();
+      const cachedTranslation = cache.find(
+        item =>
+          item.sourceHash === sourceHash &&
+          item.sourceLang === sourceLang &&
+          item.targetLang === targetLang
+      );
+
+      if (cachedTranslation) {
+        console.log(`📚 Using cached translation for ${sourceHash} (${sourceLang} → ${targetLang})`);
+        return cachedTranslation.translatedContent;
+      }
+    } catch (error) {
+      console.warn(`⚠️ Failed to load translation cache:`, error);
+    }
+
+    return null;
+  }
+
+  /**
+   * 缓存翻译结果
+   */
+  async cacheTranslation(
+    sourceHash: string,
+    sourceLang: string,
+    targetLang: string,
+    translatedContent: string
+  ): Promise<void> {
+    if (!this.isEnabled()) {
+      return;
+    }
+
+    try {
+      const cache = await this.loadTranslationCache();
+
+      // 查找是否已存在相同翻译
+      const existingIndex = cache.findIndex(
+        item =>
+          item.sourceHash === sourceHash &&
+          item.sourceLang === sourceLang &&
+          item.targetLang === targetLang
+      );
+
+      if (existingIndex >= 0) {
+        // 更新现有缓存
+        cache[existingIndex] = {
+          sourceHash,
+          sourceLang,
+          targetLang,
+          translatedContent,
+          lastUpdated: new Date().toISOString(),
+        };
+      } else {
+        // 添加新缓存
+        cache.push({
+          sourceHash,
+          sourceLang,
+          targetLang,
+          translatedContent,
+          lastUpdated: new Date().toISOString(),
+        });
+      }
+
+      await this.saveTranslationCache(cache);
+      console.log(`💾 Cached translation for ${sourceHash} (${sourceLang} → ${targetLang})`);
+    } catch (error) {
+      console.warn(`⚠️ Failed to cache translation:`, error);
+    }
+  }
+
+  /**
+   * 使用AI翻译内容
+   */
+  async translateWithAI(
+    content: string,
+    sourceLang: string,
+    targetLang: string
+  ): Promise<string> {
+    if (!this.isEnabled()) {
+      throw new Error('Translation service is not enabled');
+    }
+
+    const prompt = `请将以下${sourceLang}文本翻译成${targetLang}。保持Markdown格式不变，只翻译文本内容：
+
+${content}
+
+翻译结果（保持原格式）：`;
+
+    try {
+      const response = await fetch(`${this.config.baseUrl}/chat/completions`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${this.config.apiKey}`,
+        },
+        body: JSON.stringify({
+          model: this.config.model,
+          messages: [
+            {
+              role: 'system',
+              content: '你是一个专业的翻译助手，擅长将文档翻译成不同语言，同时保持原有的格式和结构。'
+            },
+            {
+              role: 'user',
+              content: prompt
+            }
+          ],
+          temperature: this.config.temperature,
+          max_tokens: this.config.maxTokens,
+        }),
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`Translation API error: ${response.status} ${errorText}`);
+      }
+
+      const data = await response.json();
+      const translatedContent = data.choices[0]?.message?.content?.trim() || '';
+
+      if (!translatedContent) {
+        throw new Error('Empty translation response');
+      }
+
+      return translatedContent;
+    } catch (error) {
+      console.error(`❌ Translation failed:`, error);
+      throw error;
+    }
+  }
+
+  /**
+   * 翻译文件
+   */
+  async translateFile(
+    fileInfo: FileInfo,
+    sourceLang: string,
+    targetLang: string
+  ): Promise<string> {
+    const sourceHash = fileInfo.hash || this.aiService.calculateFileHash(fileInfo.content);
+
+    // 检查缓存
+    const cachedTranslation = await this.getCachedTranslation(sourceHash, sourceLang, targetLang);
+    if (cachedTranslation) {
+      return cachedTranslation;
+    }
+
+    // 如果目标语言与源语言相同，直接返回原内容
+    if (sourceLang === targetLang) {
+      console.log(`📝 Skipping translation (same language): ${sourceLang} → ${targetLang}`);
+      await this.cacheTranslation(sourceHash, sourceLang, targetLang, fileInfo.content);
+      return fileInfo.content;
+    }
+
+    // 使用AI翻译
+    console.log(`🌐 Translating from ${sourceLang} to ${targetLang}...`);
+    const translatedContent = await this.translateWithAI(fileInfo.content, sourceLang, targetLang);
+
+    // 缓存结果
+    await this.cacheTranslation(sourceHash, sourceLang, targetLang, translatedContent);
+
+    return translatedContent;
+  }
+
+  /**
+   * 生成翻译后的文件路径
+   */
+  getTranslatedFilePath(
+    originalPath: string,
+    targetLang: string,
+    nativeHash: string
+  ): string {
+    const zenSrcDir = path.join(process.cwd(), '.zen', 'src');
+    const langDir = path.join(zenSrcDir, targetLang);
+    const fileName = `${nativeHash}.md`;
+    return path.join(langDir, fileName);
+  }
+
+  /**
+   * 确保翻译文件存在
+   */
+  async ensureTranslatedFile(
+    fileInfo: FileInfo,
+    sourceLang: string,
+    targetLang: string,
+    nativeHash: string
+  ): Promise<string> {
+    const translatedFilePath = this.getTranslatedFilePath(fileInfo.path, targetLang, nativeHash);
+
+    try {
+      // 检查文件是否已存在
+      await fs.access(translatedFilePath);
+      console.log(`📄 Translation file already exists: ${translatedFilePath}`);
+
+      // 读取现有内容
+      const existingContent = await fs.readFile(translatedFilePath, 'utf-8');
+      return existingContent;
+    } catch (error) {
+      // 文件不存在，需要翻译
+      console.log(`🔄 Creating translation file: ${translatedFilePath}`);
+
+      // 翻译内容
+      const translatedContent = await this.translateFile(fileInfo, sourceLang, targetLang);
+
+      // 确保目录存在
+      const dirPath = path.dirname(translatedFilePath);
+      await fs.mkdir(dirPath, { recursive: true });
+
+      // 保存翻译文件
+      await fs.writeFile(translatedFilePath, translatedContent, 'utf-8');
+
+      return translatedContent;
+    }
+  }
+
+  /**
+   * 清理过期的翻译缓存
+   */
+  async cleanupCache(maxAgeDays: number = 30): Promise<void> {
+    try {
+      const cache = await this.loadTranslationCache();
+      const cutoffTime = Date.now() - maxAgeDays * 24 * 60 * 60 * 1000;
+      const originalCount = cache.length;
+
+      // 过滤掉过期的缓存
+      const filteredCache = cache.filter(item => {
+        const itemTime = new Date(item.lastUpdated).getTime();
+        return itemTime >= cutoffTime;
+      });
+
+      const cleanedCount = originalCount - filteredCache.length;
+      if (cleanedCount > 0) {
+        await this.saveTranslationCache(filteredCache);
+        console.log(`🧹 Cleaned ${cleanedCount} expired translation cache entries`);
+      }
+    } catch (error) {
+      console.warn(`⚠️ Failed to cleanup translation cache:`, error);
+    }
+  }
+}

package/src/types.ts

@@ -8,16 +8,38 @@ export interface BuildOptions {
   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;
-  relativePath: string;
+  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字以内
+  tags: string[]; // AI 提取的关键字
+  inferred_date?: string; // 正文中隐含的文档创建日期，没有就留空
+  inferred_lang: string; // 文章使用的语言，例如 zh-Hans 或者 en-US
+  tokens_used?: {
+    prompt: number;
+    completion: number;
+    total: number;
+  }; // tokens 使用情况
 }
 
 export interface NavigationItem {
@@ -30,8 +52,10 @@ export interface TemplateData {
   title: string;
   content: string;
   navigation: NavigationItem[];
-  metadata?: { title: string }; // 简化，只保留标题
+  metadata?: AIMetadata; // 使用完整的 AI 元数据
   currentPath?: string;
+  lang?: string; // 当前语言
+  availableLangs?: string[]; // 可用的语言列表
 }
 
 export interface MarkdownProcessor {
@@ -49,7 +73,19 @@ export interface ZenConfig {
     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/test-multilang.js

@@ -0,0 +1,44 @@
+const { ZenBuilder } = require('./dist/builder');
+
+async function testMultiLangBuild() {
+  console.log('Testing multi-language build...\n');
+
+  const builder = new ZenBuilder();
+
+  try {
+    await builder.buildMultiLang({
+      srcDir: './docs',
+      outDir: './.zen/dist',
+      langs: ['zh-Hans', 'en-US'],
+      verbose: true,
+      useMetaData: true,
+      filterOrphans: true,
+    });
+
+    console.log('\n✅ Multi-language build test completed successfully!');
+
+    // 检查生成的文件
+    const fs = require('fs');
+    const path = require('path');
+
+    const distDir = './.zen/dist';
+    if (fs.existsSync(distDir)) {
+      console.log('\n📁 Generated files:');
+      const listFiles = (dir, indent = '') => {
+        const items = fs.readdirSync(dir, { withFileTypes: true });
+        for (const item of items) {
+          console.log(`${indent}${item.name}${item.isDirectory() ? '/' : ''}`);
+          if (item.isDirectory()) {
+            listFiles(path.join(dir, item.name), indent + '  ');
+          }
+        }
+      };
+      listFiles(distDir);
+    }
+  } catch (error) {
+    console.error('\n❌ Multi-language build test failed:', error);
+    process.exit(1);
+  }
+}
+
+testMultiLangBuild();

package/docs/ci/github-ci-cd.md

@@ -1,127 +0,0 @@
-# GitHub CI/CD 配置指南
-
-本文档描述了如何为 zengen 项目配置 GitHub Actions 进行可信发布。
-
-## 概述
-
-我们配置了三个 GitHub Actions workflows：
-
-1. **CI** (`ci.yml`) - 代码质量检查和测试
-2. **Version Management** (`version.yml`) - 版本管理和自动创建 Release
-3. **Publish to npm** (`publish.yml`) - 可信发布到 npm registry
-
-## 配置步骤
-
-### 1. 设置 npm 认证令牌
-
-由于 npm 经典令牌已被撤销，需要使用新的认证方式：
-
-#### 选项 A: 使用细粒度访问令牌（推荐）
-
-1. 登录 [npmjs.com](https://www.npmjs.com)
-2. 进入 Account Settings → Access Tokens
-3. 点击 "Create New Token"
-4. 选择 "Automation" 类型
-5. 配置权限：
-   - 读取和写入包
-   - 绕过 2FA（用于自动化工作流）
-6. 设置有效期（最长 90 天）
-7. 复制生成的令牌
-
-#### 选项 B: 使用 OIDC 可信发布
-
-1. 确保在 GitHub 仓库设置中启用了 OIDC
-2. 配置 npm 以信任 GitHub Actions 的 OIDC 令牌
-
-### 2. 配置 GitHub Actions 权限
-
-确保仓库有以下权限设置：
-
-- Settings → Actions → General
-- Workflow permissions: 选择 "Read and write permissions"
-- 确保启用了 OIDC 支持
-
-**注意**：对于 npm OIDC 发布，不需要配置 `NPM_TOKEN` secret。GitHub Actions 会自动使用 OIDC 令牌进行认证。
-
-## 工作流程
-
-### CI 流程
-
-1. 当有 push 到 main 分支或创建 PR 时触发
-2. 在多个 Node.js 版本上运行测试
-3. 执行代码质量检查
-4. 构建包并验证
-
-### 版本管理流程
-
-1. 当 package.json 版本变更时触发
-2. 自动创建 GitHub Release
-3. 生成基于提交历史的 changelog
-
-### 发布流程
-
-1. 当创建 GitHub Release 时触发
-2. 使用 OIDC 进行可信认证
-3. 构建并发布到 npm
-4. 生成来源证明（provenance）
-
-## 手动发布
-
-如果需要手动发布：
-
-1. 更新 `package.json` 中的版本号
-2. 提交并推送到 main 分支
-3. 版本管理 workflow 会自动创建 Release
-4. 发布 workflow 会自动发布到 npm
-
-或者使用 workflow_dispatch：
-
-1. 前往 Actions → Publish to npm
-2. 点击 "Run workflow"
-3. 选择分支并运行
-
-## 安全注意事项
-
-1. **令牌安全**：
-   - 永远不要在代码中硬编码令牌
-   - 使用 GitHub Secrets 存储敏感信息
-   - 定期轮换令牌
-
-2. **OIDC 优势**：
-   - 消除长期令牌的管理
-   - 自动化的短期会话令牌
-   - 更好的安全审计
-
-3. **来源证明**：
-   - 使用 `--provenance` 标志发布
-   - 验证包的构建环境和来源
-   - 增加用户信任
-
-## 故障排除
-
-### 常见问题
-
-1. **认证失败**：
-   - 确保仓库启用了 OIDC 支持
-   - 检查 workflow 中设置了 `permissions: id-token: write`
-   - 验证 npm 版本是否支持 OIDC（需要 npm 9.0.0+）
-
-2. **版本检测失败**：
-   - 确保 `fetch-depth: 0` 以获取完整历史
-   - 检查 package.json 格式是否正确
-
-3. **构建失败**：
-   - 检查 Node.js 版本兼容性
-   - 验证 TypeScript 配置
-   - 确保所有依赖项已安装
-
-### 调试
-
-- 查看 GitHub Actions 日志
-- 启用调试日志：在仓库 Settings → Actions → Runner 中设置 secret `ACTIONS_STEP_DEBUG` 为 `true`
-
-## 相关链接
-
-- [npm 认证变更公告](https://github.blog/changelog/2025-12-09-npm-classic-tokens-revoked-session-based-auth-and-cli-token-management-now-available/)
-- [GitHub Actions npm 发布文档](https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages)
-- [npm 可信发布文档](https://docs.npmjs.com/trusted-publishing-with-oidc)