Complete Example

complete_example Skill - AI 增强版 LaTeX 示例智能生成器

简介

complete_example 是一个充分发挥 AI 优势的 LaTeX 示例智能生成器，实现 AI 与硬编码的有机融合。

核心设计理念：AI 做"语义理解"，硬编码做"结构保护"

版本信息

• 版本号: 1.1.0
• 创建日期: 2026-01-07
• 更新日期: 2026-01-07
• 作者: ChineseResearchLaTeX Project

功能特性

核心能力

用户提示机制（🆕）

支持用户自定义叙事提示（narrative_hint），AI 根据提示编造合理的示例内容：

• 🏥 医疗影像：深度学习在医疗影像分析中的应用
• 🔬 材料科学：新型纳米材料合成与表征
• 🧪 临床试验：多中心临床试验设计
• 🤖 传统 ML：支持向量机分类方法

使用方法

基本语法

/complete_example <project_name> [options]

参数说明

必需参数

可选参数

使用示例

示例 1：基本使用（AI 自动推断）

/complete_example NSFC_Young --content-density moderate --output-mode preview

示例 2：使用用户提示

/complete_example NSFC_Young --narrative-hint "生成一个关于深度学习在医疗影像分析中应用的示例，重点关注 CNN 架构和数据增强策略"

示例 3：材料科学场景

/complete_example NSFC_Young --narrative-hint "创建一个关于新型纳米材料合成与表征的示例，包括 XRD、SEM 等表征方法"

示例 4：临床试验场景

/complete_example NSFC_Young --narrative-hint "模拟一个多中心临床试验的设计与分析流程，重点描述随机化和盲法实施"

输出说明

运行目录结构

所有运行输出都保存在 skills/complete_example/runs/<run_id>/ 中，不污染项目目录：

runs/<run_id>/
├── backups/           # 备份文件
├── logs/              # 日志文件
├── analysis/          # AI 分析结果
├── output/            # 生成内容
└── metadata.json      # 运行元数据

质量报告

AI 会自动评估生成内容的质量，包括：

• 连贯性评分（0-1）
• 学术风格评分（0-1）
• 资源整合评价
• 改进建议

工作流程

1. 🔍 扫描阶段
   └─ 扫描 figures/、code/、references/ 资源

2. 🧠 分析阶段
   └─ AI 分析章节主题、关键概念、写作风格

3. 💡 推理阶段
   └─ AI 推理资源相关性并给出理由

4. ✍️ 生成阶段
   └─ AI 生成连贯的叙述性内容（支持用户提示）

5. 🎨 包装阶段
   └─ 硬编码包装为 LaTeX 代码

6. 🔍 优化阶段
   └─ AI 自我审查和优化

7. ✅ 验证阶段
   └─ 格式验证、编译验证

8. 📊 报告阶段
   └─ 生成质量报告

架构设计

AI 与硬编码职责分工

分层架构

┌─────────────────────────────────────────────────────────┐
│                        用户接口层                        │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │  CLI 命令    │  │  Skill 调用  │  │  Python API  │ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│                     AI 增强工作流层                      │
│  ┌─────────────────────────────────────────────────┐   │
│  │  CompleteExampleSkill (主控制器)                │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│                   AI 智能层（Semantic Layer）             │
│  ┌──────────────────┐  ┌──────────────────┐            │
│  │ SemanticAnalyzer │  │ AIContentGenerator│            │
│  └──────────────────┘  └──────────────────┘            │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│                 硬编码保护层（Structure Layer）           │
│  ┌──────────────────┐  ┌──────────────────┐            │
│  │  ResourceScanner │  │   FormatGuard    │            │
│  └──────────────────┘  └──────────────────┘            │
└─────────────────────────────────────────────────────────┘

配置文件

配置文件位于 skills/complete_example/config.yaml，包含：

• LLM 配置（provider、model、temperature 等）
• 参数定义（content_density、output_mode 等）
• 运行管理配置（runs_root、retention、backup 等）
• 资源扫描配置
• 内容生成配置
• 格式保护配置
• AI 提示词模板
• 质量评估标准

安全机制

🔒 分层安全保护（v1.1.0 增强）

Layer 1: 系统文件保护（黑名单）

绝对禁止修改的文件：

• main.tex - 项目入口文件
• extraTex/@config.tex - 格式配置文件
• @config.tex - 格式配置文件（别名）

保护机制：

• ✅ 黑名单访问控制：任何对系统文件的修改尝试都会被拒绝
• ✅ SHA256 哈希校验：检测文件是否被外部篡改
• ✅ 自动初始化：首次运行时自动生成哈希指纹

# 示例：尝试修改系统文件会抛出异常
try:
    skill.generate_content("main.tex", "...")
except SystemFileModificationError as e:
    print(e)  # 🚨 禁止访问系统文件：main.tex

Layer 2: 用户内容文件保护（白名单）

允许编辑的文件模式：

editable_patterns:
  - "^extraTex/\\d+\\.\\d+.*\\.tex$"  # 1.1.xxx.tex, 2.3.xxx.tex 等
  - "^references/reference\\.tex$"

保护机制：

• ✅ 白名单模式匹配：只允许编辑符合正则表达式的文件
• ⚠️ 警告机制：编辑白名单之外的文件会触发警告

Layer 3: 内容安全扫描

格式注入检测：

• 扫描生成内容中的格式关键词（如 \geometry、\setlength）
• 自动注释掉危险行（可选）
• 二次验证确保清理成功

黑名单关键词：

format_keywords_blacklist:
  - "\\geometry{"
  - "\\setlength{"
  - "\\definecolor{"
  - "\\setCJKfamilyfont"
  - "\\setmainfont"
  - "\\titleformat{"
  - "\\usepackage{"
  - "\\documentclass"

格式保护

• 受保护的文件：extraTex/@config.tex、main.tex 等
• 受保护的命令：\setlength、\geometry、\definecolor 等
• 哈希验证：计算关键格式文件的 SHA256 哈希值，防止篡改
• 自动备份：修改前自动备份到 runs/<run_id>/backups/
• 自动回滚：格式保护失败或编译失败时自动回滚
• 🆕 访问控制：黑名单 + 白名单双重保护（v1.1.0）
• 🆕 格式注入扫描：自动检测并清理危险的格式指令（v1.1.0）

编译验证

• 修改文件后自动执行 xelatex 编译
• 编译失败则自动回滚
• 编译日志保存在 runs/<run_id>/logs/compile.log

依赖要求

Python 依赖

- anthropic (Claude API)
- openai (OpenAI API)
- PIL (图片元数据提取)
- pyyaml (配置文件解析)
- jinja2 (模板引擎)

LaTeX 依赖

- xelatex (编译引擎)
- ctex (中文支持)
- listings (代码清单)
- graphicx (图片支持)

最佳实践

1. 优先使用预览模式

首次使用时，建议使用 --output-mode preview 查看生成效果：

/complete_example NSFC_Young --output-mode preview

2. 充分利用用户提示

通过 --narrative-hint 指定研究主题，可以获得更符合预期的示例：

/complete_example NSFC_Young --narrative-hint "生成一个关于 XXX 的示例"

3. 选择合适的内容密度

根据章节重要性选择密度：

• minimal：快速填充，适合次要章节
• moderate：平衡选择，适合大多数章节
• comprehensive：详细示例，适合核心章节

4. 定期清理运行记录

使用 --auto-cleanup 配置自动清理过期运行记录：

run_management:
  retention:
    max_runs: 50
    max_age_days: 30
    auto_cleanup: true

故障排除

问题 1：格式被意外修改

原因：AI 生成内容时破坏了格式定义

解决方案：

1. 检查 runs/<run_id>/logs/format_check.log
2. 查看备份文件 runs/<run_id>/backups/
3. 手动恢复或调整提示后重试

问题 2：编译失败

原因：生成的 LaTeX 代码有语法错误

解决方案：

1. 检查 runs/<run_id>/logs/compile.log
2. 查看具体错误信息
3. 调整 AI 温度参数或修改提示

问题 3：生成质量不理想

原因：AI 理解偏差或温度参数过高

解决方案：

1. 使用更明确的 --narrative-hint
2. 降低 temperature 参数
3. 使用更强大的 LLM 模型

更新日志

版本变更历史记录在项目根目录的 CHANGELOG.md 中。

许可证

与主项目保持一致。

提示：详细的设计文档请参考 plans/v202601071300.md