EyeHermes — AIGC Forensics Agent

An AIGC forensics agent built on Hermes Agent, powered by GLM-5.1 for text reasoning and Qwen3-VL for visual analysis. Integrates with Hermes via native Plugin + Skill architecture. Supports CLI and WebUI.

中文文档

Quick Start

# One-click setup (recommended)
bash setup.sh --profile standard

# Or minimal profile (no model detectors, no VLM, no web search)
bash setup.sh --profile minimal

# Or full profile (all external detectors)
bash setup.sh --profile full

# Legacy one-click deploy (still works)
bash start.sh

# Or start WebUI manually
export HERMES_HOME="$PWD/runtime_data/hermes_home"
export HERMES_WEBUI_DEFAULT_WORKSPACE="$PWD/runtime_data/webui_workspace"
export HERMES_WEBUI_AGENT_DIR="$PWD/external/hermes-agent"
export HERMES_WEBUI_PYTHON="$PWD/.hermes-venv/bin/python3"
cd external/hermes-webui && python3 bootstrap.py --no-browser

See LOCAL_DEPLOYMENT.md for the complete deployment guide, or FIRST_RUN.md for the original setup instructions.

Docker Deployment

For containerized deployment, see docs/76_docker_deployment.md.

cp .env.docker.example .env.docker   # Edit with your API keys
bash scripts/start_product_stack.sh --build

What It Does

Given an image, video, or audio file, the system outputs:

1. Verdict — likely AIGC-generated, authentic, edited/recompressed, or insufficient evidence.
2. Evidence — metadata, C2PA, detector scores, frame/segment location, VLM anomaly descriptions, fact-check results.
3. Reproducible report — tool versions, model versions, input hash, runtime, failed/skipped detectors.

Design Principles

• Evidence-first — All detectors return standardized EvidenceItem; the synthesizer produces conclusions with confidence intervals and counter-evidence.
• Hermes-native orchestration — The MCP server does not route; Hermes Agent autonomously selects tools based on SOUL.md, HERMES.md, SKILL.md, and tool descriptions.
• Separate text/VLM models — GLM-5.1 handles reasoning; Qwen3-VL handles visual analysis. VLM is optional and gracefully skipped when unavailable.
• Pluggable detectors — All tools connect via a unified wrapper contract. Detectors can be enabled/disabled via environment variables.
• Conservative output — AIGC forensics is probabilistic. Reports always preserve "uncertain / needs_human_review".

Architecture

User ──► Hermes Agent (GLM-5.1) ──► MCP Forensics Server ──► Detectors
              │                            │                       │
         SOUL.md                     Atomic Tools              CLIP (subprocess)
         HERMES.md                   + Legacy Tools            ExifTool
         SKILL.md                                              FFprobe
                                                               VLM (Qwen3-VL)
                                                               ELA / Noise
                                                               C2PA
                                                               Evidence Fusion

Three-Layer Prompt System

Layer	File	Purpose
Identity	$HERMES_HOME/SOUL.md	Who the agent is — AIGC forensics analyst principles
Project rules	HERMES.md	Pipeline order, tool availability, prohibited behaviors
Skill behavior	skills/aigc_forensics/SKILL.md	Tool triggers, flow, output template, fallback

Current Status

Component	Status	Notes
Data models	Done	EvidenceItem, MediaCase, ToolRun, AnalyzeMediaInput/Output
CLI	Done	python -m services.forensics_mcp.cli analyze <path> --mode fast
MCP Server	Done	28 tools: 19 atomic + 5 media preprocess + 4 legacy (see below)
Detectors (metadata)	Done	media_probe, exiftool_check, ffprobe_check, c2pa_check
Detectors (image)	Done	ela_analysis, noise_analysis, clip_synthetic_check, frequency_artifact, jpeg_ghost, cfa_demosaic, copy_move, noiseprint, mantranet, face_xray
Detectors (video)	Preprocessing Done	video_keyframe_extract, video_frame_analyze; rPPG (external, disabled)
Detectors (audio)	Preprocessing Done	audio_probe, audio_normalize, audio_segment; AASIST/AudioSeal (external, disabled)
VLM anomaly check	Done	Qwen3-VL via SiliconFlow API; gracefully skipped when unavailable
Detector framework	Done	Base class, registry, adapter pattern for external models
Evidence fusion	Done	Rule-weighted fusion with reasoning chain and override hints
Hermes integration	Verified	GLM-5.1 + CLIP detector E2E, 8 atomic tool calls confirmed
WebUI integration	Verified	Upload → MCP call → report path
Report generation	Done	report.json + report.md + report.zh.md (Hermes-native writing)
Chinese reports	Done	Natural Chinese Markdown written by Hermes
One-click deploy	Done	start.sh + install_hermes_aigc_profile.sh
Secret hygiene	Done	scan_secrets.sh, no keys in git-tracked files
Tests	768+ passing	Schema, atomic tools, fusion, VLM, reports, detectors, provider config, secret hygiene, endpoint config, fact-check, media preprocess
Realtime WorkTrace	Done	SSE/polling progress server + sidecar HTML for live forensics progress
External detector catalog	Done	8 open-source repos synced, 5 new adapters, isolated venvs (all default disabled)
Fact-check & visual search	Done	Hermes-native fact-check via built-in web/browser/vision tools, FactCheckEvidence schema
Fact-check E2E eval	Done	6-case eval corpus, live runtime verification, source citation quality, SKILL v1.2.0
Video/audio preprocess	Done	Keyframe extraction, frame analysis, audio probe/normalize/segment, frame/segment evidence fusion, SKILL v1.3.0

MCP Tools

Atomic Tools (Hermes-native orchestration)

Tool	Purpose
forensics_media_probe	File metadata — always call first
forensics_exiftool_check	EXIF/XMP metadata + AI keyword detection
forensics_ffprobe_check	Video/audio stream metadata
forensics_c2pa_check	C2PA content credential verification
forensics_ela_analysis	Error Level Analysis
forensics_noise_analysis	Noise consistency analysis
forensics_vlm_check	Visual anomaly detection (Qwen3-VL, supports focus param)
forensics_clip_synthetic_check	CLIP-based synthetic image detection (model-level, optional)
forensics_frequency_artifact_check	Frequency domain artifact analysis
forensics_jpeg_ghost_check	JPEG ghost artifact detection
forensics_cfa_demosaic_check	CFA demosaic pattern inconsistency detection
forensics_copy_move_check	Copy-move forgery detection
forensics_noiseprint_check	Noiseprint-based noise inconsistency analysis
forensics_mantranet_check	ManTraNet manipulation localization (external, disabled by default)
forensics_face_xray_check	Face X-Ray face forgery detection (external, disabled by default)
forensics_rppg_video_check	rPPG physiological signal inconsistency (external, disabled by default)
forensics_aasist_audio_check	AASIST speech spoofing detection (external, disabled by default)
forensics_audioseal_check	AudioSeal watermark detection (external, disabled by default)
forensics_fuse_evidence	Evidence fusion → reference verdict

Media Preprocessing Tools

Tool	Purpose
forensics_video_keyframe_extract	FFmpeg keyframe/scene/interval extraction with manifest
forensics_video_frame_analyze	Per-frame forensic analysis (probe+ELA+noise on keyframes)
forensics_audio_probe	Audio stream metadata inspection via ffprobe
forensics_audio_normalize	FFmpeg audio conversion to 16kHz mono WAV
forensics_audio_segment	Audio splitting into fixed-length segments with manifest

Legacy Tools

Tool	Purpose
forensics_analyze_media	One-shot analysis (fallback)
forensics_get_report	Retrieve persisted report
forensics_list_detectors	List available detectors and health status
forensics_fact_check	Fact-checking (placeholder)

Usage

1. Hermes CLI (recommended)

# Chinese natural interaction
hermes -z '这张图是假的嘛？文件路径：/path/to/image.jpg'
hermes -z '只帮我查一下元数据。文件路径：/path/to/image.jpg'
hermes -z '仔细看一下哪里不自然。文件路径：/path/to/image.jpg'

# English
hermes -z 'Analyze /path/to/image.jpg for AIGC evidence in fast mode'

2. Interactive chat

export HERMES_HOME="$PWD/runtime_data/hermes_home"
hermes

3. WebUI (browser)

# One-click WebUI demo
bash scripts/start_webui_demo.sh
# Then open http://127.0.0.1:8787

4. MCP direct call

# Atomic tools (recommended)
python3 -m services.forensics_mcp.cli probe /path/to/image.jpg
python3 -m services.forensics_mcp.cli exiftool /path/to/image.jpg
python3 -m services.forensics_mcp.cli ela /path/to/image.jpg
python3 -m services.forensics_mcp.cli noise /path/to/image.jpg
python3 -m services.forensics_mcp.cli vlm /path/to/image.jpg --focus "AI generation artifacts"
python3 -m services.forensics_mcp.cli clip-synthetic /path/to/image.jpg
python3 -m services.forensics_mcp.cli fuse /path/to/evidence.json

# External advanced detectors (require separate setup)
python3 -m services.forensics_mcp.cli mantranet /path/to/image.jpg
python3 -m services.forensics_mcp.cli face-xray /path/to/image.jpg
python3 -m services.forensics_mcp.cli rppg /path/to/video.mp4
python3 -m services.forensics_mcp.cli aasist /path/to/audio.wav
python3 -m services.forensics_mcp.cli audioseal /path/to/audio.wav

# Video/audio preprocessing
python3 -m services.forensics_mcp.cli video-keyframes /path/to/video.mp4
python3 -m services.forensics_mcp.cli video-frame-analyze /path/to/video.mp4
python3 -m services.forensics_mcp.cli audio-probe /path/to/audio.wav
python3 -m services.forensics_mcp.cli audio-normalize /path/to/audio.wav
python3 -m services.forensics_mcp.cli audio-segment /path/to/audio.wav

# Legacy one-shot analysis
python3 -m services.forensics_mcp.cli analyze /path/to/image.jpg --mode fast

Analysis Modes (legacy forensics_analyze_media only)

Mode	Detectors	Use case
metadata_only	media_probe, exiftool, ffprobe, c2pa	Source/provenance only
fast	metadata + ELA + noise + CLIP	Quick screening (default)
vlm	fast + VLM visual anomaly	Visual analysis needed
full	All including legacy stubs	Comprehensive analysis

Model Configuration

Text Model (Hermes Agent)

Variable	Value
Provider	custom
Model	GLM-5.1
Endpoint	openapi-qb-ai endpoint

VLM Model (Visual Anomaly)

Variable	Purpose	Default
VLM_ENABLED	Enable/disable VLM analysis	not set (disabled)
VLM_API_KEY	API key for VLM endpoint	—
VLM_API_BASE	Base URL for VLM endpoint	—
VLM_MODEL	Model name	Qwen/Qwen3-VL-30B-A3B-Instruct
VLM_TIMEOUT_SECONDS	Request timeout	120

When VLM is disabled, the check returns status=skipped — this is a gap, not a negative result. See docs/33_vlm_provider_configuration.md.

CLIP Synthetic Detector

Variable	Purpose	Default
CLIP_SYNTHETIC_ENABLED	Enable/disable CLIP detector	not set (disabled)
CLIP_SYNTHETIC_REPO_DIR	Path to detector repo	—
CLIP_SYNTHETIC_WEIGHTS_PATH	Path to model weights	—
CLIP_SYNTHETIC_PYTHON	Python in detector venv	—
CLIP_SYNTHETIC_DEVICE	cpu or cuda	cpu

Score interpretation:

Score range	Label	Meaning
> 0.7	likely_aigc	Strong signal of AI generation
0.3 – 0.7	inconclusive	No clear signal
< 0.3	likely_authentic	Signal suggests real image

CLIP scores are logits (not probabilities). Always combine with other forensic signals. See docs/34_clip_calibration_findings.md.

Detector Setup

CLIP Synthetic Image Detector

# One-command setup (clones repo, creates venv, installs torch/open_clip)
bash scripts/setup_clip_synthetic_detector.sh

# Verify
bash scripts/verify_clip_synthetic_detector.sh   # 12 checks
bash scripts/verify_clip_enabled_in_hermes.sh     # 4 checks

C2PA Verification

npm install -g @contentauth/c2patool

Verification Scripts

Script	Checks
scripts/verify_hermes_integration.sh	Full Hermes integration (25 checks)
scripts/verify_clip_synthetic_detector.sh	CLIP detector health (12 checks)
scripts/verify_clip_enabled_in_hermes.sh	CLIP in Hermes runtime (4 checks)
scripts/verify_vlm_provider.sh	VLM provider configuration
scripts/verify_demo_readiness.sh	Demo readiness (11 checks)
scripts/verify_progress_server.sh	Progress server health (8 checks)
scripts/eval_webui_no_stall_ux.sh	No-stall UX metrics (8 checks)
scripts/check_git_hygiene.sh	Git hygiene (9 checks)
scripts/scan_secrets.sh	API key leak scanning
scripts/validate_skill_files.py	SKILL.md version and content validation
scripts/verify_hermes_builtin_research_tools.sh	Hermes built-in research tools verification
scripts/configure_hermes_research_tools.sh	Enable research toolsets in config.yaml
scripts/eval_factcheck_report_quality.sh	Fact-check report quality checks (6 checks)
scripts/verify_round16_factcheck_layer.sh	Full Round 16 verification (8 checks)
scripts/verify_round17_live_factcheck_e2e.sh	Full Round 17 verification (12 checks)
scripts/eval_hermes_factcheck_e2e.sh	Fact-check E2E evaluation (6 cases)
scripts/eval_visual_source_search_e2e.sh	Visual source search E2E evaluation
scripts/eval_source_citation_quality.py	Source citation quality (8 checks)
scripts/run_hermes.sh	Unified Hermes CLI wrapper
scripts/verify_hermes_runtime.sh	Hermes runtime environment verification
scripts/eval_builtin_web_runtime.sh	Live web search eval
scripts/eval_builtin_browser_runtime.sh	Live browser tools eval
scripts/eval_builtin_vision_runtime.sh	Live vision tools eval
scripts/eval_ddgs_image_search.sh	ddgs image search evaluation
scripts/verify_setup.sh	Post-setup verification (12 checks)
setup.sh	One-click setup with profile support
scripts/check_ddgs_image_search.sh	DuckDuckGo image search CLI check (optional)
scripts/verify_catalog_readiness.sh	External detector catalog readiness (8 checks)
scripts/verify_external_detector_submodules.sh	External repo sync verification
scripts/verify_all_advanced_external_detectors.sh	All advanced detector adapters (5 checks)
scripts/eval_external_detector_routing.sh	Modality-specific detector routing
scripts/verify_round15_external_pack.sh	Full Round 15 verification (10 checks)

Project Structure

hermes_detector/
  CLAUDE.md                  # Claude Code implementation rules
  HERMES.md                  # Hermes project-level rules
  FIRST_RUN.md               # Setup guide
  configs/
    hermes-aigc-integration.example.yaml
    hermes-config.example.yaml
    tools.yaml
    profiles/               # Config profile templates
      minimal.yaml          # Metadata + fast analysis only
      standard.yaml         # + CLIP + VLM + web search (default)
      full.yaml             # + all external detectors
  services/
    forensics_mcp/            # MCP server & tools
      server.py               # FastMCP server (28 tools)
      orchestrator.py         # Atomic tool implementations
      progress_server.py      # Realtime worktrace HTTP server
      schemas/models.py       # Pydantic data models
      tools/                  # Individual detector modules
      trace/                  # Progress event writer/reader
      reporting/              # Report formatters (en/zh)
      tests/                  # 768+ tests
    detectors/                # Detector framework
      base.py                 # Abstract base class
      registry.py             # Detector registry
      image/clip_synthetic/   # CLIP adapter
      image/noiseprint/       # Noiseprint adapter (0.2.0)
      image/mantranet/        # ManTraNet adapter
      image/face_xray/        # Face X-Ray adapter
      video/rppg/             # rPPG adapter (DeepFakesON-Phys backend)
      audio/aasist/           # AASIST adapter
      audio/audioseal/        # AudioSeal adapter
  skills/
    aigc_forensics/
      SKILL.md                # Skill definition (v1.3.0)
      references/             # Session recipes
  scripts/                    # Setup, verify, eval scripts
  templates/                  # Report templates, prompts, Docker
  docs/                       # Design docs (00-70)
  progress/                   # Round-by-round progress logs
  external/                   # Hermes Agent, WebUI, detectors (gitignored)
  runtime_data/               # Reports, uploads, traces (gitignored)

Documentation Index

Core Design

• docs/00_vision_scope.md — Vision, scope, threat model
• docs/01_architecture.md — Overall architecture
• docs/02_hermes_integration.md — Hermes Agent integration
• docs/09_api_data_model.md — API and data structures

Detector & Analysis

• docs/04_open_source_tool_survey.md — Open-source tool survey
• docs/05_media_detection_pipeline.md — Detection pipeline
• docs/06_evidence_fusion_explanation.md — Evidence fusion
• docs/27_detector_worker_architecture.md — Detector worker design
• docs/28_first_image_model_detector.md — First model detector
• docs/32_clip_detector_calibration_protocol.md — CLIP calibration
• docs/34_clip_calibration_findings.md — CLIP findings

Configuration & Operations

• docs/03_kimi26_config.md — Endpoint configuration
• docs/10_security_privacy_sandbox.md — Security & privacy
• docs/12_deployment_ops.md — Deployment & operations
• docs/33_vlm_provider_configuration.md — VLM provider config
• docs/35_demo_readiness.md — Demo readiness checklist
• docs/36_demo_report_quality_criteria.md — Report quality criteria
• docs/37_webui_demo_runbook.md — WebUI demo runbook

Orchestration & Reports

• docs/23_hermes_native_atomic_orchestration.md — Atomic orchestration
• docs/24_atomic_orchestration_hardening.md — Orchestration hardening
• docs/31_hermes_native_report_writing.md — Hermes-native reports
• docs/38_expert_forensics_tool_contract.md — Expert tool output contract
• docs/48_expert_forensics_tool_pack.md — Expert forensics tool pack
• docs/49_jpeg_cfa_copymove_forensics.md — JPEG Ghost / CFA / Copy-Move
• docs/50_noiseprint_skeleton.md — Noiseprint skeleton
• docs/56_external_detector_submodules.md — External detector submodules
• docs/57_external_detector_workspace.md — External detector workspace
• docs/58_noiseprint_mantranet_face_xray.md — Noiseprint / ManTraNet / Face X-Ray
• docs/59_rppg_video_detectors.md — rPPG video detectors
• docs/60_audio_deepfake_detectors.md — Audio deepfake detectors
• docs/61_external_detector_enablement_runbook.md — External detector enablement runbook

Fact-Check & Source Search

• docs/62_hermes_native_factcheck_visual_search.md — Hermes-native fact-check playbook
• docs/63_factcheck_evidence_schema.md — FactCheckEvidence schema
• docs/64_factcheck_eval_cases.md — Fact-check evaluation cases
• docs/65_factcheck_e2e_eval_corpus.md — E2E eval corpus (6 cases)
• docs/66_live_factcheck_e2e_runbook.md — Live fact-check E2E runbook
• docs/67_resource_requirements.md — Resource requirements and profiles

Video/Audio Preprocessing

• docs/68_video_keyframe_preprocessing.md — Video keyframe extraction & frame analysis
• docs/69_audio_preprocessing_pipeline.md — Audio probe, normalize, segment pipeline
• docs/70_multimodal_routing_policy.md — Image/video/audio routing & multimodal evidence

WebUI

• docs/08_webui_design.md — WebUI design
• docs/20_webui_usage_playbook.md — WebUI usage guide
• docs/22_webui_chinese_natural_usage.md — Chinese WebUI guide
• docs/44_realtime_worktrace_ui.md — Realtime worktrace side-channel
• docs/45_webui_native_worktrace_ux_acceptance.md — Native WorkTrace UX acceptance
• docs/47_webui_direct_native_worktrace.md — Direct WebUI integration (no patches)

Milestone Progress

Milestone	Status	Description
M0	Done	Repo skeleton and contract tests
M1	Done	Metadata and provenance MVP
M2	Done	Image detection MVP (ELA + noise + VLM)
M3	Done	WebUI end-to-end verification
M4	Done	Hermes-native Chinese interaction calibration
M4.5	Done	Atomic tool refactor (9 atomic MCP tools)
M5	Done	Video detection (FFmpeg keyframe extraction + frame analysis)
M6	Partial	Audio preprocessing done (probe/normalize/segment); AASIST/AudioSeal real inference needs weights
M7	Planned	Fact-check and report enhancement
M8	Done	CLIP detector + Hermes/WebUI E2E + git hygiene
M8.5	Done	Demo stabilization (CLIP E2E + VLM graceful degradation + secret hygiene)
UI-3	Done	Realtime worktrace side-channel (SSE/polling progress + sidecar HTML)
M14	Done	Expert forensics tool pack (frequency, JPEG Ghost, CFA, copy-move, noiseprint skeleton)
M15	Done	Catalog-grounded external detectors (8 repos, 5 new adapters, 23 MCP tools, SKILL v1.0.0)
M16	Done	Hermes-native fact-check + visual source search (FactCheckEvidence, built-in tool orchestration, SKILL v1.1.0)
M17	Done	Live fact-check E2E + visual source search eval (6-case corpus, source citation quality, SKILL v1.2.0)
UI-4	Done	Native WorkTrace UX (Chinese tool labels, CLIP scores, no raw JSON)
UI-5	Done	Direct WebUI WorkTrace integration (no patches, native 鉴伪过程 panel)

Disclaimer

AIGC forensics is probabilistic analysis. This system:

• Uses heuristic methods (ELA, noise analysis) that may produce false positives/negatives
• Should not be used as the sole basis for legal, employment, or law enforcement decisions
• Always recommends human expert review for high-stakes scenarios
• "Uncertain" conclusions mean "insufficient evidence", not "authentic"