complete-example

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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

complete_example Skill - AI-Enhanced LaTeX Example Intelligent Generator

简介

Introduction

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

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

complete_example is an AI-powered LaTeX example intelligent generator that achieves organic integration of AI and hard-coding.

Core Design Philosophy: AI handles "semantic understanding", while hard-coding is responsible for "structure protection"

功能特性

Features

核心能力

Core Capabilities

能力维度	说明
语义理解	AI 理解章节主题，智能判断需要什么类型的资源
智能推理	AI 推断资源与章节的相关性，并给出理由
连贯生成	AI 生成自然流畅的叙述性文本，而非模板拼接
上下文感知	根据上下文调整描述风格
自我优化	AI 自我审查并优化生成内容
格式安全	🔒 硬编码严格保护格式设置，哈希验证防篡改，访问控制

Capability Dimension	Description
Semantic Understanding	AI understands chapter themes and intelligently determines what types of resources are needed
Intelligent Inference	AI infers the relevance between resources and chapters, and provides reasons
Coherent Generation	AI generates natural and fluent narrative text, rather than template splicing
Context Awareness	Adjusts description style based on context
Self-Optimization	AI self-reviews and optimizes generated content
Format Security	🔒 Hard-coding strictly protects format settings, with hash verification to prevent tampering and access control

用户提示机制

User Prompt Mechanism

支持用户自定义叙事提示（

narrative_hint

），AI 根据提示编造合理的示例内容：

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

Supports user-defined narrative hints (

narrative_hint

), and AI generates reasonable example content based on the hints:

🏥 Medical Imaging: Applications of deep learning in medical image analysis
🔬 Materials Science: Synthesis and characterization of new nanomaterials
🧪 Clinical Trials: Multi-center clinical trial design
🤖 Traditional ML: Support Vector Machine classification method

使用方法

Usage

基本语法

Basic Syntax

/complete_example <project_name> [options]

/complete_example <project_name> [options]

参数说明

Parameter Description

必需参数

Required Parameters

参数	类型	说明
`project_name`	string	项目名称（如 `NSFC_Young` ）或项目路径

Parameter	Type	Description
`project_name`	string	Project name (e.g., `NSFC_Young` ) or project path

可选参数

Optional Parameters

参数	类型	默认值	说明
`--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/2.1.研究内容.tex"]` ），null 表示自动检测
`--narrative-hint`	string	`null`	用户自定义叙事提示，指导 AI 生成特定风格的示例内容

Parameter	Type	Default Value	Description
`--content-density`	string	`moderate`	Content density: `minimal` (2 resources/200 words) / `moderate` (4 resources/300 words) / `comprehensive` (6 resources/500 words)
`--output-mode`	string	`preview`	Output mode: `preview` (Preview) / `apply` (Apply) / `report` (Report)
`--target-files`	array	`null`	List of target files (e.g., `["extraTex/2.1.研究内容.tex"]` ), null means automatic detection
`--narrative-hint`	string	`null`	User-defined narrative hint to guide AI in generating example content with specific styles

使用示例

Usage Examples

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

Example 1: Basic Usage (AI Automatic Inference)

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

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

示例 2：使用用户提示

Example 2: Using User Prompt

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

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

示例 3：材料科学场景

Example 3: Materials Science Scenario

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

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

示例 4：临床试验场景

Example 4: Clinical Trial Scenario

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

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

输出说明

Output Description

运行目录结构

Runtime Directory Structure

所有运行输出都保存在 目标项目的隐藏目录

{project_path}/.complete_example/<run_id>/

中，不污染项目目录：

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

设计原理：

✅ 项目隔离：每个项目都有独立的
```
.complete_example
```
目录
✅ 隐藏保护：使用点号前缀（
```
.
```
）使目录在常规文件列表中隐藏
✅ 硬编码保证：所有中间文件路径都通过硬编码方式确保存放在此目录中
✅ 可追溯性：每次运行都有唯一的
```
run_id
```
（格式：
```
v{timestamp}_{hash}
```
）
✅ 便于清理：可直接删除
```
.complete_example
```
目录清理所有中间文件

All runtime outputs are stored in the hidden directory of the target project

{project_path}/.complete_example/<run_id>/

, which does not pollute the project directory:

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

Design Principles:

✅ Project Isolation: Each project has an independent
```
.complete_example
```
directory
✅ Hidden Protection: Uses a dot prefix (
```
.
```
) to hide the directory in regular file lists
✅ Hard-Coded Guarantee: All intermediate file paths are ensured to be stored in this directory via hard-coding
✅ Traceability: Each run has a unique
```
run_id
```
(format:
```
v{timestamp}_{hash}
```
)
✅ Easy Cleanup: You can directly delete the
```
.complete_example
```
directory to clear all intermediate files

质量报告

Quality Report

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

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

AI automatically evaluates the quality of generated content, including:

Coherence Score (0-1)
Academic Style Score (0-1)
Resource Integration Evaluation
Improvement Suggestions

工作流程

Workflow

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

架构设计

Architecture Design

AI 与硬编码职责分工

Division of Responsibilities Between AI and Hard-Coding

任务类型	AI 负责	硬编码负责
文件扫描	-	✅ 文件系统操作、元数据提取
语义分析	✅ 章节主题理解、关键概念提取	-
资源选择	✅ 推理相关性、给出理由	✅ 评分排序、Top-K 选择
文本生成	✅ 叙述性内容生成	-
LaTeX 包装	-	✅ 语法正确性、格式规范
格式保护	✅ 解释修改意图、诊断问题	✅ 严格验证、哈希校验

Task Type	AI's Responsibility	Hard-Coding's Responsibility
File Scanning	-	✅ File system operations, metadata extraction
Semantic Analysis	✅ Chapter theme understanding, key concept extraction	-
Resource Selection	✅ Inferring relevance and providing reasons	✅ Scoring and sorting, Top-K selection
Text Generation	✅ Narrative content generation	-
LaTeX Wrapping	-	✅ Syntax correctness, format specification
Format Protection	✅ Explaining modification intentions, diagnosing issues	✅ Strict validation, hash verification

分层架构

Layered Architecture

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

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

配置文件

Configuration File

配置文件位于

skills/complete_example/config.yaml

，包含：

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

The configuration file is located at

skills/complete_example/config.yaml

, which includes:

LLM configurations (provider, model, temperature, etc.)
Parameter definitions (content_density, output_mode, etc.)
Runtime management configurations (runs_root, retention, backup, etc.)
Resource scanning configurations
Content generation configurations
Format protection configurations
AI prompt templates
Quality evaluation standards

安全机制

Security Mechanisms

🔒 分层安全保护

🔒 Layered Security Protection

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

Layer 1: System File Protection (Blacklist)

绝对禁止修改的文件：

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

保护机制：

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

python

undefined

Files that are absolutely prohibited from modification:

```
main.tex
```
- Project entry file
```
extraTex/@config.tex
```
- Format configuration file
```
@config.tex
```
- Format configuration file (alias)

Protection Mechanisms:

✅ Blacklist access control: Any attempt to modify system files will be rejected
✅ SHA256 hash verification: Detects whether files have been tampered with externally
✅ Automatic initialization: Automatically generates hash fingerprints on first run

python

undefined

示例：尝试修改系统文件会抛出异常

try: skill.generate_content("main.tex", "...") except SystemFileModificationError as e: print(e) # 🚨 禁止访问系统文件：main.tex

undefined

try: skill.generate_content("main.tex", "...") except SystemFileModificationError as e: print(e) # 🚨 禁止访问系统文件：main.tex

undefined

Layer 2: 章节层级规范（结构保护）

Layer 2: Chapter Level Specifications (Structure Protection)

核心规则：不同文件类型使用不同的章节层级

文件类型	允许的层级	禁止的层级
`main.tex`	`\section` 、 `\subsection`	-
`extraTex/*.tex` （input 类）	`\subsubsection` 、 `\subsubsubsection`	`\section` 、 `\subsection`

双层级生成要求：

每个正文类的 input tex 文件必须同时使用两个层级：

yaml

generation_requirement:
  require_both_levels: true  # 必须同时使用两个层级
  min_subsubsection: 1       # 每个文件至少 1 个 subsubsection
  min_subsubsubsection: 1    # 每个 subsubsection 下至少 1 个 subsubsubsection

示例结构：

latex

\subsubsection{研究背景}
\subsubsubsection{国内研究现状}
...内容...
\subsubsubsection{国外研究现状}
...内容...

\subsubsection{研究意义}
\subsubsubsection{理论意义}
...内容...
\subsubsubsection{实践意义}
...内容...

设计原理：

```
main.tex
```
作为项目入口，负责顶层结构（section/subsection）
```
input
```
类 tex 文件作为内容模块，使用 subsubsection + subsubsubsection 双层级
这种分离确保结构清晰、层次丰富、职责明确

检查模式：

yaml

enforcement:
  enabled: true
  mode: "strict"  # strict: 拒绝违规 / warn: 警告但允许 / off: 关闭
  auto_fix: false  # 是否自动修正（建议关闭）

Core Rules: Different file types use different chapter levels

File Type	Allowed Levels	Prohibited Levels
`main.tex`	`\section` , `\subsection`	-
`extraTex/*.tex` (input type)	`\subsubsection` , `\subsubsubsection`	`\section` , `\subsection`

Two-Level Generation Requirements:

Each input-type tex file for the main body must use two levels simultaneously:

yaml

generation_requirement:
  require_both_levels: true  # 必须同时使用两个层级
  min_subsubsection: 1       # 每个文件至少 1 个 subsubsection
  min_subsubsubsection: 1    # 每个 subsubsection 下至少 1 个 subsubsubsection

Example Structure:

latex

\subsubsection{研究背景}
\subsubsubsection{国内研究现状}
...内容...
\subsubsubsection{国外研究现状}
...内容...

\subsubsection{研究意义}
\subsubsubsection{理论意义}
...内容...
\subsubsubsection{实践意义}
...内容...

Design Principles:

```
main.tex
```
serves as the project entry, responsible for the top-level structure (section/subsection)
Input-type tex files serve as content modules, using the two-level structure of subsubsection + subsubsubsection
This separation ensures clear structure, rich hierarchy, and clear responsibilities

Check Mode:

yaml

enforcement:
  enabled: true
  mode: "strict"  # strict: Reject violations / warn: Warn but allow / off: Disable
  auto_fix: false  # Whether to automatically fix (it is recommended to disable)

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

Layer 3: User Content File Protection (Whitelist)

允许编辑的文件模式：

yaml

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

保护机制：

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

Allowed File Editing Patterns:

yaml

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

Protection Mechanisms:

✅ Whitelist pattern matching: Only allows editing of files that match regular expressions
⚠️ Warning mechanism: Editing files outside the whitelist will trigger a warning

Layer 4: 内容安全扫描

Layer 4: Content Security Scanning

格式注入检测：

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

黑名单关键词：

yaml

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

Format Injection Detection:

Scans for format keywords in generated content (e.g.,
```
\geometry
```
,
```
\setlength
```
)
Automatically comments out dangerous lines (optional)
Secondary verification ensures successful cleanup

Blacklist Keywords:

yaml

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

格式保护

Format Protection

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

Protected Files:
```
extraTex/@config.tex
```
,
```
main.tex
```
, etc.
Protected Commands:
```
\setlength
```
,
```
\geometry
```
,
```
\definecolor
```
, etc.
Hash Verification: Calculates the SHA256 hash value of key format files to prevent tampering
Automatic Backup: Automatically backs up to
```
.complete_example/<run_id>/backups/
```
before modification
Automatic Rollback: Automatically rolls back if format protection fails or compilation fails
Access Control: Dual protection of blacklist + whitelist
Format Injection Scanning: Automatically detects and cleans up dangerous format commands

编译验证

Compilation Verification

修改文件后自动执行
```
xelatex
```
编译
编译失败则自动回滚

编译日志保存在

.complete_example/<run_id>/logs/compile.log

Automatically executes
```
xelatex
```
compilation after modifying files
Automatically rolls back if compilation fails

Compilation logs are saved in

.complete_example/<run_id>/logs/compile.log

依赖要求

Dependencies

Python 依赖

Python Dependencies

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

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

LaTeX 依赖

LaTeX Dependencies

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

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

最佳实践

Best Practices

1. 优先使用预览模式

1. Prioritize Preview Mode

首次使用时，建议使用

--output-mode preview

查看生成效果：

/complete_example NSFC_Young --output-mode preview

When using it for the first time, it is recommended to use

--output-mode preview

to check the generated results:

/complete_example NSFC_Young --output-mode preview

2. 充分利用用户提示

2. Make Full Use of User Prompts

通过

--narrative-hint

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

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

Specify research topics via

--narrative-hint

to get examples that better meet your expectations:

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

3. 选择合适的内容密度

3. Choose Appropriate Content Density

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

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

Select density based on chapter importance:

```
minimal
```
: Quick filling, suitable for secondary chapters
```
moderate
```
: Balanced choice, suitable for most chapters
```
comprehensive
```
: Detailed examples, suitable for core chapters

4. 定期清理运行记录

4. Regularly Clean Up Runtime Records

使用

--auto-cleanup

配置自动清理过期运行记录：

yaml

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

Use the

--auto-cleanup

configuration to automatically clean up expired runtime records:

yaml

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

故障排除

Troubleshooting

问题 1：格式被意外修改

Issue 1: Format Accidentally Modified

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

解决方案：

检查

.complete_example/<run_id>/logs/format_check.log

查看备份文件
```
.complete_example/<run_id>/backups/
```
手动恢复或调整提示后重试

Cause: AI破坏了格式定义 when generating content

Solutions:

Check

.complete_example/<run_id>/logs/format_check.log

View backup files in
```
.complete_example/<run_id>/backups/
```
Manually restore or retry with adjusted prompts

问题 2：编译失败

Issue 2: Compilation Failure

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

解决方案：

检查

.complete_example/<run_id>/logs/compile.log

查看具体错误信息
调整 AI 温度参数或修改提示

Cause: The generated LaTeX code has syntax errors

Solutions:

Check

.complete_example/<run_id>/logs/compile.log

View specific error messages
Adjust AI temperature parameters or modify prompts

问题 3：生成质量不理想

Issue 3: Unsatisfactory Generation Quality

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

解决方案：

使用更明确的
```
--narrative-hint
```
降低
```
temperature
```
参数
使用更强大的 LLM 模型

Cause: AI understanding deviation or excessively high temperature parameter

Solutions:

Use a more explicit
```
--narrative-hint
```
Reduce the
```
temperature
```
parameter
Use a more powerful LLM model

许可证

License

与主项目保持一致。

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

Consistent with the main project.

Note: For detailed design documents, please refer to plans/v202601071300.md