complete_example Skill - AI-Enhanced LaTeX Example Intelligent Generator

Introduction

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

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

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]

Parameter Description

Required Parameters

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

Optional Parameters

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

Example 1: Basic Usage (AI Automatic Inference)

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

Example 2: Using User Prompt

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

Example 3: Materials Science Scenario

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

Example 4: Clinical Trial Scenario

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

Output Description

Runtime Directory Structure

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 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. 📊 报告阶段
   └─ 生成质量报告

Architecture Design

Division of Responsibilities Between AI and Hard-Coding

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    │            │
│  └──────────────────┘  └──────────────────┘            │
└─────────────────────────────────────────────────────────┘

Configuration File

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: System File Protection (Blacklist)

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

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

Layer 2: Chapter Level Specifications (Structure Protection)

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: User Content File Protection (Whitelist)

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: Content Security Scanning

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

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

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 Dependencies

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

LaTeX Dependencies

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

Best Practices

1. Prioritize Preview Mode

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. Make Full Use of User Prompts

Specify research topics via

--narrative-hint

to get examples that better meet your expectations:

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

3. Choose Appropriate Content Density

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. Regularly Clean Up Runtime Records

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

Issue 1: Format Accidentally Modified

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

Issue 2: Compilation Failure

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

Issue 3: Unsatisfactory Generation Quality

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

Consistent with the main project.

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

complete-example

NPX Install

Tags

SKILL.md Content (Chinese)

complete_example Skill - AI-Enhanced LaTeX Example Intelligent Generator

Introduction

Features

Core Capabilities

User Prompt Mechanism

Usage

Basic Syntax

Parameter Description

Required Parameters

Optional Parameters

Usage Examples

Example 1: Basic Usage (AI Automatic Inference)

Example 2: Using User Prompt

Example 3: Materials Science Scenario

Example 4: Clinical Trial Scenario

Output Description

Runtime Directory Structure

Quality Report

Workflow

Architecture Design

Division of Responsibilities Between AI and Hard-Coding

Layered Architecture

Configuration File

Security Mechanisms

🔒 Layered Security Protection

Layer 1: System File Protection (Blacklist)

Layer 2: Chapter Level Specifications (Structure Protection)

Layer 3: User Content File Protection (Whitelist)

Layer 4: Content Security Scanning

Format Protection

Compilation Verification

Dependencies

Python Dependencies

LaTeX Dependencies

Best Practices

1. Prioritize Preview Mode

2. Make Full Use of User Prompts

3. Choose Appropriate Content Density

4. Regularly Clean Up Runtime Records

Troubleshooting

Issue 1: Format Accidentally Modified

Issue 2: Compilation Failure

Issue 3: Unsatisfactory Generation Quality

License