Reference Classifier

Use this skill to operate the Reference Classifier workflow through the reference_classifier MCP server.

Core rule

When the reference_classifier MCP tools are available, use them as the execution layer. Do not manually reproduce the visual-classification algorithm or independently inspect the theme references with another vision model unless the user explicitly asks for that.

Choose the smallest correct tool

| User goal | Tool | |---|---| | Inspect themes / validate package without model calls | inspect_theme_package | | Analyze reference images and freeze/cache policy | analyze_theme_package | | Classify explicit image files | classify_images | | Classify an image directory and export results | classify_directory | | Continue an interrupted directory job | resume_classification |

Do not call extra tools merely to be thorough.

Provider and model selection

Reference Classifier is provider-neutral. Do not assume ModelScope or Qwen.

For model-backed tools (analyze_theme_package, classify_images, classify_directory, resume_classification):

1. Prefer the MCP server's provider=auto behavior when the user has not requested a specific provider.
2. The recommended generic configuration is Bring Your Own Model through an OpenAI-compatible multimodal chat/completions endpoint.
3. If the user explicitly names a provider/model, pass the supported provider/model settings instead of replacing their choice.
4. ModelScope is an optional preset / backward-compatible path, not the default product requirement.
5. If the MCP reports that no provider is configured, explain the provider-neutral variables:
   • REFERENCE_CLASSIFIER_PROVIDER
   • REFERENCE_CLASSIFIER_MODEL
   • REFERENCE_CLASSIFIER_BASE_URL (for openai-compatible)
   • REFERENCE_CLASSIFIER_API_KEY
6. Never ask the user to paste an API key into chat. Tell them to configure the secret in their MCP host/environment.

Do not claim that an arbitrary provider is compatible merely because it has an API. The generic path requires a vision-capable endpoint that accepts OpenAI-style multimodal chat messages and returns a compatible chat-completions response.

Frozen Policy reuse

For an unchanged theme package:

1. Analyze it once when needed with analyze_theme_package.
2. Reuse the cached Frozen Policy for later classify_images and classify_directory.
3. Avoid repeating reference-image analysis when policy_cache_hit is true.

Resume behavior

If a directory classification was interrupted and a checkpoint exists, prefer resume_classification instead of restarting the job.

Do not delete checkpoints or completed output merely to force a retry unless the user explicitly approves.

API-call accounting

Treat API call count as the portable accounting unit.

When available, report:

• reference_analysis_calls
• classification_calls
• format_repair_calls
• provider_retry_calls
• actual_total
• minimum_calls_avoided
• policy_cache_hit
• adaptive split count

Do not silently convert API calls into provider-specific points, money, credits, or tokens.

See references/API_CALL_POLICY.md.

Failure handling

When a tool fails:

1. Preserve the MCP error type/message/details.
2. Identify whether the issue is path/input, authentication, network/provider, response parsing, or checkpoint/resume state.
3. Prefer resume when a valid checkpoint exists.
4. Never expose provider secrets such as REFERENCE_CLASSIFIER_API_KEY, OPENAI_API_KEY, or MODELSCOPE_TOKEN.

See references/MCP_TOOLS.md.

Output behavior

For package inspection:

• theme count
• theme names

For policy analysis:

• theme count
• Policy Set ID
• cache status
• API call count

For image classification:

• image name/path
• assigned theme
• highest score
• per-theme scores when requested
• cache/API-call information

For directory classification:

• total images
• count by theme
• output directory
• cache/API-call information

For resume:

• completed before resume
• newly completed
• final total
• API calls
• output directory

Safety and file integrity

• Preserve original images.
• Do not move/delete source images unless explicitly requested and supported.
• Do not overwrite unrelated files.
• Treat .album-theme.zip as a Reference Classifier theme package.
• Never print or persist provider secrets.

Example intent mapping

User: "看看这个 album-theme.zip 有几个分类。" → inspect_theme_package

User: "先学习这组参考图，后面还要继续分类。" → analyze_theme_package

User: "按刚才的标准分类 001.jpg 和 002.jpg。" → classify_images, reusing cached policy when available.

User: "把 test 文件夹按这个主题包整理到 output。" → classify_directory

User: "刚才跑到一半停了，继续。" → resume_classification

Completion check

Before answering, verify:

• smallest correct MCP tool used
• unchanged policy not needlessly re-analyzed
• interrupted work resumed when appropriate
• API calls reported as calls
• paths/output location are clear
• no secrets exposed