| name | complete-example |
| description | AI 增强版 LaTeX 示例智能生成器，实现 AI 与硬编码的有机融合。AI 做"语义理解"（分析章节主题、推理资源相关性、生成连贯叙述），硬编码做"结构保护"（格式验证、哈希校验、访问控制）。用于用户要求"填充示例内容/生成示例/补充 LaTeX 示例"等场景。 |
| metadata | {"short-description":"AI 增强版 LaTeX 示例智能生成器","keywords":["latex","示例生成","AI 增强","格式保护","语义理解","资源整合","nsfc"],"triggers":["填充示例","生成示例","complete example","补充示例内容"]} |
| config | skills/complete_example/config.yaml |
complete_example Skill - AI 增强版 LaTeX 示例智能生成器
简介
complete_example 是一个充分发挥 AI 优势的 LaTeX 示例智能生成器，实现 AI 与硬编码的有机融合。
核心设计理念：AI 做"语义理解"，硬编码做"结构保护"
版本信息
- 版本号: 1.1.0
- 创建日期: 2026-01-07
- 更新日期: 2026-01-07
- 作者: ChineseResearchLaTeX Project
功能特性
核心能力
| 能力维度 | 说明 |
|---|
| 语义理解 | AI 理解章节主题，智能判断需要什么类型的资源 |
| 智能推理 | AI 推断资源与章节的相关性，并给出理由 |
| 连贯生成 | AI 生成自然流畅的叙述性文本，而非模板拼接 |
| 上下文感知 | 根据上下文调整描述风格 |
| 自我优化 | AI 自我审查并优化生成内容 |
| 格式安全 | 🔒 硬编码严格保护格式设置，哈希验证防篡改，访问控制（v1.1.0） |
用户提示机制（🆕）
支持用户自定义叙事提示（narrative_hint），AI 根据提示编造合理的示例内容：
- 🏥 医疗影像：深度学习在医疗影像分析中的应用
- 🔬 材料科学：新型纳米材料合成与表征
- 🧪 临床试验：多中心临床试验设计
- 🤖 传统 ML：支持向量机分类方法
使用方法
基本语法
/complete_example <project_name> [options]
参数说明
必需参数
| 参数 | 类型 | 说明 |
|---|
project_name | string | 项目名称（如 NSFC_Young）或项目路径 |
可选参数
| 参数 | 类型 | 默认值 | 说明 |
|---|
--content-density | string | moderate | 内容密度：minimal(2资源/200字) / moderate(4资源/300字) / comprehensive(6资源/500字) |
--output-mode | string | preview | 输出模式：preview(预览) / apply(应用) / report(报告) |
--target-files | array | null | 目标文件列表（如 ["extraTex/1.2.内容目标问题.tex"]），null 表示自动检测 |
--narrative-hint | string | null | 用户自定义叙事提示，指导 AI 生成特定风格的示例内容 |
使用示例
示例 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 与硬编码职责分工
| 任务类型 | AI 负责 | 硬编码负责 |
|---|
| 文件扫描 | - | ✅ 文件系统操作、元数据提取 |
| 语义分析 | ✅ 章节主题理解、关键概念提取 | - |
| 资源选择 | ✅ 推理相关性、给出理由 | ✅ 评分排序、Top-K 选择 |
| 文本生成 | ✅ 叙述性内容生成 | - |
| LaTeX 包装 | - | ✅ 语法正确性、格式规范 |
| 格式保护 | ✅ 解释修改意图、诊断问题 | ✅ 严格验证、哈希校验 |
分层架构
┌─────────────────────────────────────────────────────────┐
│ 用户接口层 │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 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)
Layer 2: 用户内容文件保护（白名单）
允许编辑的文件模式：
editable_patterns:
- "^extraTex/\\d+\\.\\d+.*\\.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 生成内容时破坏了格式定义
解决方案：
- 检查
runs/<run_id>/logs/format_check.log
- 查看备份文件
runs/<run_id>/backups/
- 手动恢复或调整提示后重试
问题 2：编译失败
原因：生成的 LaTeX 代码有语法错误
解决方案：
- 检查
runs/<run_id>/logs/compile.log
- 查看具体错误信息
- 调整 AI 温度参数或修改提示
问题 3：生成质量不理想
原因：AI 理解偏差或温度参数过高
解决方案：
- 使用更明确的
--narrative-hint
- 降低
temperature 参数
- 使用更强大的 LLM 模型
更新日志
版本变更历史记录在项目根目录的 CHANGELOG.md 中。
许可证
与主项目保持一致。
提示：详细的设计文档请参考 plans/v202601071300.md
