npm - zengen - Versions diffs - 0.1.34 → 0.1.36 - Mend

zengen 0.1.34 → 0.1.36

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (70) hide show

package/.github/workflows/bump-version.yml +112 -0
package/.github/workflows/ci.yml +2 -2
package/.github/workflows/pages.yml +1 -7
package/.zen/meta.json +57 -0
package/.zen/translations.json +51 -0
package/dist/ai-client.d.ts +34 -0
package/dist/ai-client.d.ts.map +1 -0
package/dist/ai-client.js +180 -0
package/dist/ai-client.js.map +1 -0
package/dist/ai-processor.d.ts +51 -0
package/dist/ai-processor.d.ts.map +1 -0
package/dist/ai-processor.js +215 -0
package/dist/ai-processor.js.map +1 -0
package/dist/ai-service.d.ts +79 -0
package/dist/ai-service.d.ts.map +1 -0
package/dist/ai-service.js +257 -0
package/dist/ai-service.js.map +1 -0
package/dist/builder.d.ts +26 -2
package/dist/builder.d.ts.map +1 -1
package/dist/builder.js +420 -9
package/dist/builder.js.map +1 -1
package/dist/cli.js +45 -3
package/dist/cli.js.map +1 -1
package/dist/gitignore.d.ts +2 -1
package/dist/gitignore.d.ts.map +1 -1
package/dist/gitignore.js +21 -3
package/dist/gitignore.js.map +1 -1
package/dist/gitignore.test.js +82 -17
package/dist/gitignore.test.js.map +1 -1
package/dist/markdown.d.ts +6 -1
package/dist/markdown.d.ts.map +1 -1
package/dist/markdown.js +31 -9
package/dist/markdown.js.map +1 -1
package/dist/navigation.js +5 -5
package/dist/navigation.js.map +1 -1
package/dist/scanner.d.ts +26 -0
package/dist/scanner.d.ts.map +1 -0
package/dist/scanner.js +190 -0
package/dist/scanner.js.map +1 -0
package/dist/template.d.ts +6 -2
package/dist/template.d.ts.map +1 -1
package/dist/template.js +58 -9
package/dist/template.js.map +1 -1
package/dist/translation-service.d.ts +72 -0
package/dist/translation-service.d.ts.map +1 -0
package/dist/translation-service.js +291 -0
package/dist/translation-service.js.map +1 -0
package/dist/types.d.ts +35 -4
package/dist/types.d.ts.map +1 -1
package/docs/advanced-usage.md +39 -0
package/docs/getting-started.md +26 -0
package/docs/guides/best-practices.md +0 -113
package/docs/guides/config.md +0 -233
package/package.json +3 -2
package/src/ai-client.ts +227 -0
package/src/ai-processor.ts +243 -0
package/src/ai-service.ts +281 -0
package/src/builder.ts +543 -10
package/src/cli.ts +49 -3
package/src/gitignore.test.ts +82 -17
package/src/gitignore.ts +23 -3
package/src/markdown.ts +39 -11
package/src/navigation.ts +5 -5
package/src/scanner.ts +180 -0
package/src/template.ts +69 -9
package/src/translation-service.ts +350 -0
package/src/types.ts +39 -3
package/test-multilang.js +44 -0
package/docs/ci/github-ci-cd.md +0 -127
package/docs/guides/api.md +0 -277

package/docs/guides/config.md CHANGED Viewed

@@ -19,9 +19,6 @@ npx zengen build --watch --serve
 # 自定义端口
 npx zengen build --watch --serve --port 8080
-# 使用配置文件
-npx zengen build --config zen.config.json
 # 清理输出目录
 npx zengen build --clean
@@ -49,238 +46,8 @@ npx zengen
 | `--serve`    | `-s` | 启动开发服务器（需要 `--watch`） | `false`     |
 | `--port`     | `-p` | 开发服务器端口                   | `3000`      |
 | `--host`     |      | 开发服务器主机                   | `localhost` |
-| `--template` | `-t` | 自定义模板文件路径               | 内置模板    |
-| `--config`   | `-c` | 配置文件路径                     | 无          |
 | `--verbose`  | `-v` | 显示详细日志                     | `false`     |
 | `--clean`    |      | 清理输出目录                     | `false`     |
 | `--base-url` |      | 站点基础 URL                     | 无          |
 | `--help`     | `-h` | 显示帮助信息                     | 无          |
-## 配置文件
-### 配置文件格式
-在项目根目录创建 `zen.config.json` 文件：
-```json
-{
-  "template": "./custom-template.html",
-  "baseUrl": "/my-docs",
-  "i18n": {
-    "sourceLang": "zh-CN",
-    "targetLangs": ["en-US", "ja-JP"],
-    "apiKey": "your-openai-api-key"
-  },
-  "includePattern": "**/*.md",
-  "excludePattern": "**/_*.md"
-}
-```
-### 配置项说明
-#### `template`
-- **类型**: `string`
-- **描述**: 自定义模板文件路径
-- **示例**: `"./templates/custom.html"`
-#### `baseUrl`
-- **类型**: `string`
-- **描述**: 站点基础 URL，用于生成绝对路径
-- **示例**: `"/docs"`, `"/my-project"`
-#### `i18n`
-- **类型**: `object`
-- **描述**: 多语言翻译配置
-- **字段**:
-  - `sourceLang`: 源语言代码（如 `"zh-CN"`）
-  - `targetLangs`: 目标语言代码数组（如 `["en-US", "ja-JP"]`）
-  - `apiKey`: OpenAI API 密钥（可选，从环境变量读取）
-#### `includePattern`
-- **类型**: `string`
-- **描述**: 包含的文件模式（glob 语法）
-- **默认**: `"**/*.md"`
-- **示例**: `"**/*.{md,markdown}"`
-#### `excludePattern`
-- **类型**: `string`
-- **描述**: 排除的文件模式（glob 语法）
-- **默认**: 无
-- **示例**: `"**/_*.md"`, `"**/node_modules/**"`
-## 模板配置
-### 默认模板
-ZEN 使用内置的极简模板，包含：
-- 响应式布局
-- 代码高亮（使用 highlight.js）
-- 导航菜单
-- 深色/浅色主题切换
-### 自定义模板
-创建自定义模板文件 `custom-template.html`：
-```html
-<!DOCTYPE html>
-<html lang="zh-CN">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>{{title}}</title>
-    <link rel="stylesheet" href="/styles.css" />
-  </head>
-  <body>
-    <nav class="sidebar">{{navigation}}</nav>
-    <main class="content">{{content}}</main>
-    <footer>
-      <p>由 ZEN 生成</p>
-    </footer>
-  </body>
-</html>
-```
-**可用模板变量:**
-| 变量              | 描述                      |
-| ----------------- | ------------------------- |
-| `{{title}}`       | 页面标题                  |
-| `{{content}}`     | 转换后的 HTML 内容        |
-| `{{navigation}}`  | 导航菜单 HTML             |
-| `{{metadata}}`    | 页面元数据（JSON 字符串） |
-| `{{currentPath}}` | 当前页面路径              |
-### 模板位置
-1. **命令行指定**: `--template ./my-template.html`
-2. **配置文件指定**: `"template": "./my-template.html"`
-3. **默认模板**: 内置模板
-## 多语言配置
-### 基本配置
-```json
-{
-  "i18n": {
-    "sourceLang": "zh-CN",
-    "targetLangs": ["en-US", "ja-JP"],
-    "apiKey": "sk-..."
-  }
-}
-```
-### 环境变量
-也可以使用环境变量配置 API 密钥：
-```bash
-export OPENAI_API_KEY="sk-..."
-npx zengen build
-```
-### 翻译文件结构
-```
-docs/
-├── index.md           # 源文件（中文）
-├── index.en-US.md     # 英文翻译（自动生成）
-└── index.ja-JP.md     # 日文翻译（自动生成）
-```
-### 翻译流程
-1. **首次构建**: 翻译所有内容
-2. **增量更新**: 只翻译新增或修改的内容
-3. **手动更新**: 可以直接编辑翻译文件
-## 文件处理配置
-### 文件过滤
-```json
-{
-  "includePattern": "**/*.{md,markdown}",
-  "excludePattern": "**/{_*,node_modules}/**"
-}
-```
-### 元数据提取
-在 Markdown 文件顶部添加 YAML frontmatter：
-```yaml
----
-title: 页面标题
-description: 页面描述
-author: 作者名
-date: 2024-01-01
-tags: [文档, 教程]
----
-```
-### 自定义处理器
-通过 API 使用自定义处理器，配置文件不支持直接配置处理器。
-## 开发服务器配置
-### 基本配置
-```bash
-# 启动开发服务器
-npx zengen build --watch --serve
-# 自定义端口和主机
-npx zengen build --watch --serve --port 8080 --host 0.0.0.0
-```
-### 服务器特性
-- 自动重载：文件变化时自动刷新浏览器
-- 静态文件服务：提供构建的文档站点
-- 实时预览：即时查看修改效果
-## 环境配置
-### Node.js 版本
-- **最低版本**: Node.js 16.x
-- **推荐版本**: Node.js 18.x 或更高
-### 内存要求
-- 小型项目：~100MB
-- 大型项目：~500MB（包含翻译）
-### 网络要求
-- 使用 AI 翻译时需要网络连接
-- 纯本地构建无需网络
-## 最佳实践
-### 配置文件管理
-1. **版本控制**: 将 `zen.config.json` 加入版本控制
-2. **环境变量**: 敏感信息（如 API 密钥）使用环境变量
-3. **模板分离**: 自定义模板单独存放
-### 性能优化
-1. **增量构建**: 使用 `--watch` 模式开发
-2. **文件组织**: 合理组织文档结构
-3. **缓存利用**: ZEN 会自动缓存处理结果
-### 错误处理
-1. **详细日志**: 使用 `--verbose` 查看详细错误信息
-2. **配置验证**: ZEN 会自动验证配置
-3. **错误恢复**: 构建失败时会保留上次成功的结果

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "zengen",
-  "version": "0.1.34",
+  "version": "0.1.36",
   "description": "ZEN - A minimalist Markdown documentation site builder",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -25,7 +25,7 @@
     "documentation",
     "cli"
   ],
-  "author": "ZEN Team",
+  "author": "zccz14",
   "license": "ISC",
   "repository": {
     "type": "git",
@@ -54,6 +54,7 @@
   "dependencies": {
     "chokidar": "^5.0.0",
     "clipanion": "^4.0.0-rc.4",
+    "dotenv": "^16.4.7",
     "express": "^4.21.2",
     "highlight.js": "^11.11.1",
     "marked": "^17.0.1",

package/src/ai-client.ts ADDED Viewed

@@ -0,0 +1,227 @@
+import { AIMetadata } from './types';
+import { AIService, AIConfig } from './ai-service';
+/**
+ * OpenAI 兼容 API 响应接口
+ */
+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;
+  };
+}
+/**
+ * AI 客户端类 - 使用 fetch 调用 OpenAI 兼容 API
+ */
+export class AIClient {
+  private aiService: AIService;
+  constructor(aiService: AIService) {
+    this.aiService = aiService;
+  }
+  /**
+   * 调用 AI 模型提取文档 metadata
+   */
+  async extractMetadata(content: string, filePath: string): Promise<AIMetadata | null> {
+    const config = this.aiService.getConfig();
+    if (!config.enabled || !config.apiKey) {
+      console.log(`⚠️ AI feature is disabled or API key not configured for: ${filePath}`);
+      return null;
+    }
+    try {
+      console.log(`🤖 Extracting AI metadata for: ${filePath}`);
+      const prompt = this.buildMetadataPrompt(content);
+      const response = await this.callOpenAIAPI(prompt, config);
+      if (!response) {
+        console.warn(`⚠️ Failed to extract metadata for: ${filePath}`);
+        return null;
+      }
+      const metadata = this.parseMetadataResponse(response.choices[0].message.content);
+      // 添加 tokens 使用情况
+      metadata.tokens_used = {
+        prompt: response.usage.prompt_tokens,
+        completion: response.usage.completion_tokens,
+        total: response.usage.total_tokens,
+      };
+      // 打印 tokens 使用情况
+      this.aiService.logTokenUsage(filePath, metadata.tokens_used);
+      return metadata;
+    } catch (error) {
+      console.error(`❌ Failed to extract AI metadata for ${filePath}:`, error);
+      return null;
+    }
+  }
+  /**
+   * 构建提取 metadata 的 prompt
+   */
+  private buildMetadataPrompt(content: string): string {
+    // 限制内容长度以避免 token 超限
+    const maxContentLength = 8000;
+    const truncatedContent =
+      content.length > maxContentLength
+        ? content.substring(0, maxContentLength) + '... [内容已截断]'
+        : content;
+    return `请分析以下文档内容，提取以下信息并返回 JSON 格式：
+文档内容：
+"""
+${truncatedContent}
+"""
+请提取：
+1. title: 文档的标题（简洁明了，不超过 20 个字）
+2. summary: 文档摘要（控制在 100 字以内，概括主要内容）
+3. tags: 关键词列表（3-8 个关键词，使用中文或英文）
+4. inferred_date: 文档中隐含的创建日期（如果有的话，格式：YYYY-MM-DD，没有就留空字符串）
+5. inferred_lang: 文档使用的语言代码（例如：zh-Hans 表示简体中文，en-US 表示美式英语）
+请严格按照以下 JSON 格式返回，不要包含任何其他文本：
+{
+  "title": "文档标题",
+  "summary": "文档摘要...",
+  "tags": ["关键词1", "关键词2", "关键词3"],
+  "inferred_date": "2023-01-01",
+  "inferred_lang": "zh-Hans"
+}`;
+  }
+  /**
+   * 调用 OpenAI 兼容 API
+   */
+  private async callOpenAIAPI(prompt: string, config: AIConfig): Promise<OpenAIResponse | null> {
+    try {
+      const response = await fetch(`${config.baseUrl}/chat/completions`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${config.apiKey}`,
+        },
+        body: JSON.stringify({
+          model: config.model,
+          messages: [
+            {
+              role: 'system',
+              content:
+                '你是一个专业的文档分析助手，擅长从文档中提取结构化信息。请严格按照要求的 JSON 格式返回结果。',
+            },
+            {
+              role: 'user',
+              content: prompt,
+            },
+          ],
+          temperature: config.temperature,
+          max_tokens: config.maxTokens,
+          response_format: { type: 'json_object' },
+        }),
+      });
+      if (!response.ok) {
+        const errorText = await response.text();
+        console.error(`❌ OpenAI API error (${response.status}):`, errorText);
+        return null;
+      }
+      const data: OpenAIResponse = await response.json();
+      return data;
+    } catch (error) {
+      console.error('❌ Failed to call OpenAI API:', error);
+      return null;
+    }
+  }
+  /**
+   * 解析 AI 返回的 metadata
+   */
+  private parseMetadataResponse(responseContent: string): AIMetadata {
+    try {
+      const metadata = JSON.parse(responseContent);
+      // 验证和清理数据
+      return {
+        title: metadata.title?.trim() || '未命名文档',
+        summary: metadata.summary?.trim() || '',
+        tags: Array.isArray(metadata.tags)
+          ? metadata.tags.map((tag: string) => tag.trim()).filter(Boolean)
+          : [],
+        inferred_date: metadata.inferred_date?.trim() || undefined,
+        inferred_lang: metadata.inferred_lang?.trim() || 'zh-Hans',
+      };
+    } catch (error) {
+      console.error('❌ Failed to parse AI response:', error, 'Response:', responseContent);
+      // 返回默认值
+      return {
+        title: '解析失败',
+        summary: 'AI 响应解析失败',
+        tags: ['error'],
+        inferred_lang: 'zh-Hans',
+      };
+    }
+  }
+  /**
+   * 批量处理文件
+   */
+  async processFiles(
+    files: Array<{ content: string; path: string; hash: string }>
+  ): Promise<Map<string, AIMetadata>> {
+    const results = new Map<string, AIMetadata>();
+    const config = this.aiService.getConfig();
+    if (!config.enabled || !config.apiKey) {
+      console.log('⚠️ AI feature is disabled or API key not configured');
+      return results;
+    }
+    console.log(`🤖 Processing ${files.length} files with AI...`);
+    for (const file of files) {
+      try {
+        // 检查缓存
+        const cachedMetadata = await this.aiService.getCachedMetadata(file.hash, file.path);
+        if (cachedMetadata) {
+          results.set(file.path, cachedMetadata);
+          continue;
+        }
+        // 调用 AI 提取 metadata
+        const metadata = await this.extractMetadata(file.content, file.path);
+        if (metadata) {
+          results.set(file.path, metadata);
+          // 缓存结果
+          await this.aiService.cacheMetadata(file.hash, file.path, metadata);
+        }
+      } catch (error) {
+        console.error(`❌ Failed to process file ${file.path}:`, error);
+      }
+    }
+    return results;
+  }
+}