zengen 0.1.35 → 0.2.0

package/docs/guides/best-practices.md

@@ -2,95 +2,6 @@
 
 本文档介绍使用 ZEN 构建文档站点的最佳实践。
 
-## 文件组织
-
-### 推荐的文件结构
-
-```
-project/
-├── docs/                    # 文档源文件
-│   ├── index.md            # 首页
-│   ├── getting-started.md  # 入门指南
-│   ├── api/                # API 文档目录
-│   │   ├── overview.md
-│   │   ├── core-api.md
-│   │   └── plugins.md
-│   ├── guides/             # 指南目录
-│   │   ├── installation.md
-│   │   └── configuration.md
-│   └── resources/          # 资源文件
-│       └── images/
-└── package.json
-```
-
-**注意**: ZEN 强制使用当前目录作为源目录，所以应该切换到 `docs/` 目录下运行构建命令：
-
-```bash
-cd docs
-npx zengen build
-```
-
-### 命名约定
-
-- 使用小写字母和连字符：`getting-started.md`
-- 避免特殊字符和空格
-- 主要页面使用简短名称：`index.md`, `api.md`
-- 分类页面使用目录组织
-
-## 写作规范
-
-### Markdown 语法
-
-**推荐:**
-
-````markdown
-# 一级标题
-
-## 二级标题
-
-### 三级标题
-
-使用 **粗体** 和 _斜体_ 强调重要内容。
-
-- 列表项 1
-- 列表项 2
-  - 子列表项
-
-1. 有序列表项 1
-2. 有序列表项 2
-
-> 引用重要的说明或提示。
-
-`行内代码` 用于技术术语。
-
-```javascript
-// 代码块示例
-console.log('Hello ZEN!');
-```
-````
-
-````
-
-**避免:**
-- 过多的标题层级（超过 4 级）
-- 复杂的表格（考虑使用简单列表替代）
-- 过长的行（建议 80-100 字符换行）
-
-### 元数据使用
-
-在每个 Markdown 文件顶部添加 frontmatter：
-
-```yaml
----
-title: 页面标题
-description: 简洁的页面描述
-keywords: [关键词1, 关键词2]
-author: 作者名
-date: 2024-01-01
-last_modified: 2024-01-15
----
-````
-
 ## 多语言管理
 
 ### 翻译策略
@@ -100,30 +11,6 @@ last_modified: 2024-01-15
 3. **术语一致**: 建立术语表保持翻译一致性
 4. **人工校对**: AI 翻译后建议人工校对
 
-### 翻译文件管理
-
-```
-docs/
-├── index.zh-CN.md      # 中文源文件
-├── index.en-US.md      # 英文翻译
-├── api/
-│   ├── overview.zh-CN.md
-│   └── overview.en-US.md
-└── glossary.json       # 术语表
-```
-
-### 配置示例
-
-```json
-{
-  "i18n": {
-    "sourceLang": "zh-CN",
-    "targetLangs": ["en-US", "ja-JP"],
-    "apiKey": "your-openai-api-key"
-  }
-}
-```
-
 ## 性能优化
 
 ### 构建优化
@@ -143,7 +30,7 @@ npx zengen build --watch
 npx zengen build --watch --serve
 
 # 生产构建
-npx zengen build --clean
+npx zengen build
 ```
 
 ## 部署策略
@@ -176,7 +63,7 @@ jobs:
       - name: Build documentation
         run: |
           cd docs
-          npx zengen build --clean --base-url /my-docs
+          npx zengen build --base-url /my-docs
 
       - name: Deploy to GitHub Pages
         uses: peaceiris/actions-gh-pages@v3
@@ -194,8 +81,8 @@ jobs:
 # 切换到文档目录
 cd docs
 
-# 清理并构建
-npx zengen build --clean
+# 构建文档
+npx zengen build
 
 # 同步到服务器
 rsync -avz .zen/dist/ user@server:/var/www/docs/

package/docs/guides/config.md

@@ -19,12 +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
-
 # 显示详细日志
 npx zengen build --verbose
 
@@ -49,238 +43,6 @@ 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

@@ -1,6 +1,6 @@
 {
   "name": "zengen",
-  "version": "0.1.35",
+  "version": "0.2.0",
   "description": "ZEN - A minimalist Markdown documentation site builder",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -10,6 +10,7 @@
   "scripts": {
     "build": "npx rimraf dist && tsc",
     "dev": "ts-node src/cli.ts",
+    "build:doc": "npm run build && node dist/cli.js build --lang zh-Hans --lang en-US --verbose",
     "test": "npm run build && node --test dist/**/*.test.js",
     "test:types": "tsc --noEmit",
     "test:build": "npm run build && test -f dist/index.js && test -f dist/cli.js",
@@ -54,9 +55,11 @@
   "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",
-    "minimatch": "^10.1.1"
+    "minimatch": "^10.1.1",
+    "yaml": "^2.8.2"
   }
 }

package/src/ai/extractMetadataFromMarkdown.ts

@@ -0,0 +1,95 @@
+import { completeMessages, OpenAIMessage } from '../services/openai';
+import { AIMetadata } from '../types';
+
+/**
+ * 从 markdown 内容中提取 metadata
+ * @param content Markdown 内容
+ * @returns Promise<AIMetadata> 提取的元数据，失败时抛出错误
+ */
+export async function extractMetadataFromMarkdown(content: string): Promise<AIMetadata> {
+  const prompt = buildMetadataPrompt(content);
+  const messages: OpenAIMessage[] = [
+    {
+      role: 'system',
+      content:
+        '你是一个专业的文档分析助手，擅长从文档中提取结构化信息。请严格按照要求的 JSON 格式返回结果。',
+    },
+    {
+      role: 'user',
+      content: prompt,
+    },
+  ];
+
+  const response = await completeMessages(messages, {
+    response_format: { type: 'json_object' },
+  });
+
+  const metadata = 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,
+  };
+
+  return metadata;
+}
+
+/**
+ * 构建提取 metadata 的 prompt
+ */
+function 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"
+}`;
+}
+
+/**
+ * 解析 AI 返回的 metadata
+ */
+function 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);
+    throw error;
+  }
+}

package/src/ai/translateMarkdown.ts

@@ -0,0 +1,29 @@
+import { completeMessages, OpenAIMessage } from '../services/openai';
+
+/**
+ * 将 markdown 翻译为指定的语言
+ * @param content Markdown 内容
+ * @param targetLang 目标语言代码（例如：zh-Hans, en-US）
+ * @returns Promise<string> 翻译后的 Markdown 内容
+ */
+export async function translateMarkdown(content: string, targetLang: string): Promise<string> {
+  const messages: OpenAIMessage[] = [
+    {
+      role: 'system',
+      content: `你是一个专业的翻译助手，擅长将文档翻译成不同语言，同时保持原有的格式和结构。请将用户输入翻译成 ${targetLang}，注意保持 Markdown 格式不变，链接不变，不要翻译代码，但是可以翻译代码中的注释。`,
+    },
+    {
+      role: 'user',
+      content: content,
+    },
+  ];
+
+  const response = await completeMessages(messages);
+  const translatedContent = response.choices[0]?.message?.content?.trim() || '';
+
+  if (!translatedContent) {
+    throw new Error('Empty translation response');
+  }
+
+  return translatedContent;
+}