hooks:
- - docs/overrides/hooks/ai_summary.py # 添加AI摘要hook
- - docs/overrides/hooks/reading_time.py # 添加统计阅读时间hook
-
-# 可选：Material主题配置
-theme:
- name: material
- custom_dir: docs/overrides #一定要有！！
- features:
- - content.code.copy
- - content.code.select
+步骤2: 本地配置
+根目录下创建 .env 文件存放密钥（记得添加到 .gitignore）：
+ | # .env 文件内容
+DEEPSEEK_API_KEY=your_deepseek_api_key_here
+OPENAI_API_KEY=your_openai_api_key_here
|
2. 在ai_summary.py中配置需要AI摘要的目录
| # 📂 可自定义的文件夹配置
-self.enabled_folders = [
- 'blog/', # blog文件夹
- 'develop/', # develop文件夹
- # 在这里添加您想要启用AI摘要的文件夹
-]
+12
| #.gitignore 文件内容
+# 环境变量文件（敏感信息）
+.env
+.env.local
+.env.*.local
+*.key
-# 📋 排除的文件和文件夹
-self.exclude_patterns = [
- 'waline.md', 'link.md', '404.md', 'tag.md', 'tags.md',
- '/about/', '/search/', '/sitemap', 'index.md', # 根目录index.md
-]
-
-# 📋 排除的特定文件
-self.exclude_files = [
- 'blog/index.md',
- 'blog/indexblog.md',
- 'docs/index.md',
- 'develop/index.md',
-]
+# MkDocs 构建输出目录
+site/
+
+# AI 摘要缓存目录（项目根目录）- 需要被提交
+!.ai_cache/
|
3. 在ai_summary.py中设置DeepSeek API(默认是OpenAI)
- | # 在ai_summary.py中修改API配置
-'deepseek': {
- 'url': 'https://api.deepseek.com/v1/chat/completions',
- 'model': 'deepseek-chat',
- 'api_key': os.getenv('DEEPSEEK_API_KEY', 'your-azure-api-key'),
- 'max_tokens': 150,
- 'temperature': 0.3
-},
-
|
4. 运行MkDocs
-第一次运行时，可能需要等待一段时间，因为系统会自动生成摘要。后续运行时，系统会使用缓存数据，加快生成速度。
+
到这里检查下目录树状图:
+
| $ tree -a
+文件名
+├── .github
+│ ├── .DS_Store
+│ └── workflows
+│ └── ci.yml
+├── docs
+│ └── index.md
+| └── overrides
+│ └── hooks
+│ └── ai_summary.py
+├── .env
+├──.gitignore
+├── README.md
+└── mkdocs.yml
+
|
2. 配置AI服务
+选择AI服务提供商：
+- 🌟 DeepSeek（推荐）：性价比高，中文表现优秀
+- 🔥 OpenAI：功能强大，广泛支持
+- ⚡ Claude：逻辑清晰，文本理解佳
+- 🧠 Gemini：Google出品，多语言支持
+获取API密钥：
+- DeepSeek - 注册获取API密钥
+- ChatAnywhere - 免费OpenAI额度
+获取的密钥存放于上一步创建的.env 文件中！！！
+3. 设置参数
+在 ai_summary.py 中配置需要AI摘要的目录：
| #依次运行命令
-mkdocs build
-mkdocs serve
-
|
-📖 使用指南
-AI摘要配置
-文件夹级别控制
- | # 启用特定文件夹
-configure_ai_summary(['blog/', 'docs/', 'tutorials/'])
-
-# 全局启用（除排除项）
-configure_ai_summary([''])
-
|
页面级别控制(推荐)
-在Markdown文件的YAML front matter中：
- | ---
-title: 文章标题
-ai_summary: true # 启用AI摘要
----
-
|
- | ---
-title: 文章标题
-ai_summary: false # 禁用AI摘要
-description: 手动摘要 # 可选
----
+3
+4
+5
| # 📂 启用AI摘要的文件夹
+self.enabled_folders = [
+ 'blog/', # 博客文章
+ # 添加更多文件夹...
+]
|
阅读时间配置
-排除特定页面
- | # 在页面的YAML front matter中
----
-title: 页面标题
-hide_reading_time: true # 隐藏阅读时间
----
+4. 本地运行和测试
+
-🎨 显示效果
-AI摘要显示
+5. 部署配置
+ | #ci.yml
+name: ci
+on:
+ push:
+ branches:
+ - master
+ - main
+ # 禁止从 fork 仓库访问 secrets
+ pull_request:
+ types: [closed]
+ branches: [main, master]
+permissions:
+ contents: write
+jobs:
+ deploy:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ with:
+ fetch-depth: 0
+ sparse-checkout: |
+ docs
+ includes
+ requirements.txt
+ .ai_cache
+ - uses: actions/setup-python@v4
+ with:
+ python-version: 3.x
+ - name: Set cache ID
+ run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+ - uses: actions/cache@v3
+ with:
+ key: mkdocs-material-${{ github.run_number }}
+ path: .cache
+ restore-keys: |
+ mkdocs-material-
+ - run: pip install mkdocs-git-revision-date-localized-plugin
+ - run: pip install mkdocs-git-authors-plugin
+ - run: pip install mkdocs-git-committers-plugin-2
+ - run: pip install markdown-callouts
+ - run: pip install mkdocs-rss-plugin
+ - run: pip install requests>=2.25.0
+ - run: pip install python-dateutil>=2.8.0
+ - run: pip install cachetools>=4.2.0
+ - run: pip install python-dotenv>=0.19.0
+ - run: pip install pymdown-extensions
+ - run: pip install mkdocs-material
+ - run: pip install --upgrade --force-reinstall mkdocs-material
+ - name: Deploy with AI Summary
+ env:
+ # AI摘要开关控制
+ AI_SUMMARY_CI_ENABLED: 'true' # CI部署环境启用AI摘要 (true=在CI中为文章生成AI摘要)
+ AI_SUMMARY_CI_ONLY_CACHE: 'true' # CI部署不生成新摘要 (true=使用本地部署过的摘要缓存，不再重复调用API)
+ AI_SUMMARY_CI_FALLBACK: 'true' # CI部署启用备用摘要 (true=API失败时生成离线基础摘要)
+ # AI_SUMMARY_LOCAL_ENABLED: 'false' # 本地部署环境禁用AI摘要 (true=本地开发时也生成摘要)（不需要管这条）
+ # AI_SUMMARY_CACHE_ENABLED: 'true' # 本地启用缓存功能 (true=缓存摘要避免重复生成)（不需要管这条）
+ # API密钥配置
+ DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
+ OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+ run: mkdocs gh-deploy --force
+
+ # 自动提交新生成的AI缓存文件
+ - name: Auto-commit AI cache (if any new files)
+ run: |
+ if [ -d ".ai_cache" ] && [ "$(ls -A .ai_cache 2>/dev/null)" ]; then
+ git config --local user.email "action@github.com"
+ git config --local user.name "GitHub Action"
+ git add .ai_cache/
+ if ! git diff --cached --quiet; then
+ git commit -m "🤖 Auto-update AI summary cache [skip ci]"
+ git push
+ echo "✅ 自动提交了新的 AI 缓存文件"
+ else
+ echo "ℹ️ 没有新的缓存文件需要提交"
+ fi
+ else
+ echo "ℹ️ 没有找到缓存目录或缓存为空"
+ fi
+
|
| # ai_summary.py 中配置
+# AI摘要本地环境配置
+self.ci_config = {
+ # CI部署环境开关 (不用管，只在ci.yml中设置有效)
+ 'enabled_in_ci': os.getenv('AI_SUMMARY_CI_ENABLED', 'true').lower() == 'true',
+
+ # 本地部署环境开关 (true=本地开发时启用AI摘要)
+ 'enabled_in_local': os.getenv('AI_SUMMARY_LOCAL_ENABLED', 'true').lower() == 'true',
+
+ # CI部署仅缓存模式(不用管，只在ci.yml中设置有效)
+ 'ci_only_cache': os.getenv('AI_SUMMARY_CI_ONLY_CACHE', 'false').lower() == 'true',
+
+ # 本地部署缓存功能开关 (true=启用缓存避免重复生成, false=总是生成新摘要)
+ 'cache_enabled': os.getenv('AI_SUMMARY_CACHE_ENABLED', 'true').lower() == 'true',
+
+ # CI部署备用摘要开关 (不用管，只在ci.yml中设置有效)
+ 'ci_fallback_enabled': os.getenv('AI_SUMMARY_CI_FALLBACK', 'true').lower() == 'true',
+}
+
|
几种运行模式：
+1. 完全禁用: 本地和CI部署都不运行摘要生成
+2. 仅CI部署启用: 本地禁用，CI部署生成新摘要
+3. 缓存模式：本地已经生成过摘要，CI部署使用缓存（推荐。上方配置项中已默认CI部署的缓存模式，可自行搭配选择）
+4. 完全启用: 本地和CI部署都运行(API消耗会更多)
+6. GitHub Secrets配置
+步骤1: 设置Repository Secrets
+1. 进入GitHub仓库 → Settings → Secrets and variables → Actions
+2. 点击 New repository secret 添加：
+ | DEEPSEEK_API_KEY=your_deepseek_api_key_here
+OPENAI_API_KEY=your_openai_api_key_here
+
|
+
+然后部署到GitHub Pages或其他平台即可。
+有报错可以去问ChatGPT或者在Issues中提问。
+📖 使用指南
+AI摘要控制
+方法1: 页面级控制（推荐）
+在Markdown文件最上面的yaml meta中：
+启用AI摘要：
| !!! info "🤖 AI智能摘要"
- 本文详细介绍了MkDocs hooks的开发和使用方法，涵盖AI摘要生成、阅读时间统计等功能实现。通过DeepSeek API集成和智能缓存机制，为技术文档提供自动化的内容增强服务。
-
-# 您的文章标题
-文章内容...
-
|
阅读信息显示
+4
| ---
+title: 文章标题
+ai_summary: true # 启用AI摘要
+---
+
|
禁用AI摘要：
| !!! info "📖 阅读信息"
- 阅读时间：**3** 分钟 | 中文字符：**1247** | 有效代码行数：**45**
-
-# 您的文章标题
-文章内容...
+5
| ---
+title: 文章标题
+ai_summary: false # 禁用AI摘要
+description: 自定义摘要内容 # 可选手动摘要
+---
+
|
方法2: 文件夹级控制
+ | # 在 ai_summary.py 中配置
+# 📂 可自定义的文件夹配置
+self.enabled_folders = [
+ 'blog/', # blog文件夹
+ 'index.md',
+ # 'develop/', # develop文件夹
+ # 'posts/', # posts文件夹
+ # 'trip/', # trip文件夹
+ # 'about/', # about文件夹
+]
+
+# 📋 Excluded files and folders
+self.exclude_patterns = [
+ '404.md', 'tag.md', 'tags.md',
+]
+
+# 📋 Excluded specific files
+self.exclude_files = [
+ 'blog/index.md',
+]
|
实际效果：
-
-API花费
-一次大约0.03-0.05元（中大型文档）
-可以说相当经济实惠了！
-免费openai额度获取
-推荐使用：chatanywhere
-申请好后得到sk-开头的密钥，在ai_summary.py的多AI服务配置部分替换为以下内容：
- | 'openai': {
- 'url': 'https://api.chatanywhere.tech/v1/chat/completions',
- 'model': 'gpt-3.5-turbo', # 或 'gpt-4', 'gpt-4-turbo'
- 'api_key': os.getenv('OPENAI_API_KEY', 'your_openai_api_key'),
- 'max_tokens': 150,
- 'temperature': 0.3
-},
+
+🎨 显示效果
+AI摘要显示
+实际效果预览：
+
+💰 成本说明
+
+- 单次费用: 约0.03-0.05元（中大型文档）
+- 月度预估: 普通博客约1-5元
+- 免费额度: 多数AI服务商提供新用户免费额度
+
+
+⚙️ 高级配置
+自定义AI服务
+ | # 添加新的AI服务
+self.ai_services = {
+ 'your_service': {
+ 'url': 'https://api.yourservice.com/v1/chat/completions',
+ 'model': 'your-model',
+ 'api_key': os.getenv('YOUR_API_KEY'),
+ 'max_tokens': 150,
+ 'temperature': 0.3
+ }
+}
+
+# 默认使用的AI服务
+self.default_service = 'your_service'
+
+# 服务优先级（按顺序尝试）
+self.service_fallback_order = ['openai', 'deepseek', 'claude', 'gemini'] # 按顺序尝试
|
| # 默认使用的AI服务
-self.default_service = 'openai'
+自定义提示词
+ | def generate_ai_summary(self, content, page_title=""):
+ prompt = f"""请为以下技术文档生成一个简洁的中文摘要（80-120字）：
+
+ 文章标题：{page_title}
+ 文章内容：{content[:2500]}
+
+ 要求：
+ 1. 突出核心技术要点
+ 2. 使用简洁专业的语言
+ 3. 长度控制在80-120字
+ """
|
但是我这里也推荐使用DeepSeek API，额度充足且性能优秀。
-⚙️ 高级配置
-自定义API服务
- | # 支持其他AI服务
-self.api_config = {
- 'url': 'https://your-api-endpoint.com/v1/chat/completions',
- 'model': 'your-model',
- 'headers': {
- 'Content-Type': 'application/json',
- 'Authorization': 'Bearer YOUR_API_KEY'
- }
-}
-
|
自定义提示词
+缓存配置
| # 修改AI摘要的提示词
-def generate_ai_summary(self, content, page_title=""):
- prompt = f"""您的自定义提示词...
-
- 文章标题：{page_title}
- 文章内容：{content[:2500]}
- """
+4
| # 修改缓存过期时间
+cache_time = datetime.fromisoformat(cache_data.get('timestamp', '1970-01-01'))
+if (datetime.now() - cache_time).days < 30: # 改为30天
+ return cache_data
|
缓存配置
-1
+
+🌍 多语言支持
+语言配置
+ | # 修改缓存过期时间（天数）
-cache_time = datetime.fromisoformat(cache_data.get('timestamp', '1970-01-01'))
-if (datetime.now() - cache_time).days < 30: # 改为30天
- return cache_data
+4
| # 在 ai_summary.py 中设置
+self.summary_language = 'zh' # 中文摘要
+# self.summary_language = 'en' # 英文摘要
+# self.summary_language = 'both' # 双语摘要
|
-切换api服务后，要删除site/.ai_cache这个缓存文件，才可以重新生成摘要！！！(这个问题已经解决了，切换api服务后，会自动删除缓存文件，无需手动删除)
- |
|
|