Tag Regulator

Purpose

Normalize Zotero item tags based on a controlled vocabulary, and use AI to infer possible new tags.

This workflow calls the tag-regulator skill on the Skill-Runner backend to check whether tags comply with the vocabulary and recommend relevant tags.

Use Cases

• Batch clean up non-standard tags
• Automatically recommend tags for items based on an existing controlled vocabulary
• Maintain continuous updates and refinement of the controlled vocabulary

Input Constraints

Constraint Type	Description
Input Unit	Parent item
Data Source	Obtained from the parent item: current tags, metadata (title, authors, abstract, etc.)

If a digest markdown embedded payload generated by literature-analysis exists, the workflow will automatically upload it as optional context to improve inference quality.

Trigger Methods

• Directly select one or more Zotero items (parent items)
• After selecting items, choose "Tag Regulator" from the context menu

Execution Flow

1. Load Controlled Vocabulary
   └── Read tagVocabularyJson from Zotero preferences
       └── Parse the list of valid tags in the vocabulary

2. Build Request
   └── Collect parent item metadata and current tag list
       └── Write the controlled vocabulary to a temporary YAML file
       └── Upload to Skill-Runner

3. Skill-Runner Processing
   └── Invoke skill_id: "tag-regulator"
       └── Check tag compliance
       └── Generate suggested tags (suggest_tags)

4. Return Results
   └── Apply tag changes (remove non-compliant tags, add recommended tags)
       └── Reconcile suggested tags against the current local vocabulary
       └── Process suggested tags (popup interaction)

Tag Processing Logic

• remove_tags: Current tags not in the controlled vocabulary will be removed
• add_tags: Tags inferred from metadata, added directly to the item
• suggest_tags: New tags suggested by AI, requiring user confirmation
• digest_markdown: Optional enrichment context, only uploaded when a digest markdown embedded payload exists

Real-time Sync Rules

When results are returned, the latest local state is read:

• If a suggest_tag has already entered the controlled vocabulary, no popup is shown; it participates in the item update with add_tags semantics
• If a suggest_tag is already in the staging area, it will not be written to the staging area again
• Only suggestions that remain unprocessed will enter the popup

Estimated Duration

Scenario	Estimated Time per Paper
No digest (Literature Analysis not run)	Approximately 1 minute
With digest (Literature Analysis already run)	1-3 minutes

If the item already has a digest, AI will use the summary as additional context, resulting in more precise but longer inference.

Suggested Tag Popup

For suggest_tags, a dialog prompts the user to choose how to handle them:

• Add: Add directly to the controlled vocabulary
• Stage: Place in the staging area for later review
• Reject: Ignore the suggestion
• Add All / Stage All / Reject All: Batch processing

The dialog has a 10-second auto-stage countdown; if timed out, suggestions are automatically staged.

Outputs

1. Tag Changes

• remove_tags: Remove tags not in the vocabulary from the item
• add_tags: Add recommended tags to the item
• Directly applied to the selected Zotero items

2. Suggested Tag Processing

• User chooses how to handle via popup
• Accepted tags: Added to tagVocabularyJson preference
• Staged tags: Added to tagVocabularyStagedJson preference

Model Recommendation

🟢 A lightweight model is sufficient — tag regulation is essentially a simple classification and matching task that doesn't require the strongest model.

Parameters

Parameter	Type	Description	Default
infer_tag	boolean	Whether to enable tag inference	true
valid_tags_format	string	Vocabulary format	yaml
tag_note_language	string	Language for suggestion descriptions	zh-CN

valid_tags_format Available Values

• yaml: Use YAML format
• json: Use JSON format
• auto: Automatically detect

Dependencies

• Controlled Vocabulary: A controlled vocabulary must be created first; see Tags Management
• Backend: Skill-Runner service
• Backend Configuration: Configure a Skill-Runner type backend in Backend Manager
• Skill: The tag-regulator skill must be deployed on the Skill-Runner

Related Workflows

• Tags Management — Manage the controlled tag vocabulary