Version-Master 2.1.0

Purpose

Version-Master 2.1.0 is a single-file level version management skill. Unlike full-workspace snapshots, it maintains independent version history for each file, so users can clearly see what changes each document has gone through.

Core Features

1. 1. Single-file versioning - Each file maintains its own version history independently
2. Complete content saving - Saves actual file content (text and binary), supports full restoration
3. Smart summaries - Automatically extracts descriptive summaries from file content (e.g., document titles)
4. Content deduplication - Automatically skips unchanged files to avoid meaningless versions
5. Safe restoration - Auto-backs up current file before restoring, supports rollback
6. Version diff - Compare differences between versions of the same file

When to Use

Activate this skill when the user's request involves any of these scenarios:

1. 1. Save file version / 保存文件版本 - User says "save this file's version", "save current changes"
2. View version history / 查看版本历史 - User says "what versions does this file have", "show version history"
3. Restore old version / 恢复旧版本 - User says "restore to v2", "go back to previous version"
4. Diff versions / 对比版本差异 - User says "compare v1 and v2", "show me what changed"
5. Clean versions / 清理版本 - User says "delete old versions"

How to Use

After loading this skill, the AI uses version management features by calling scripts/version_tool.py.

Core Features

1. Save Version

CODEBLOCK0

Key Parameters:

• - file_path: File path (relative to workspace). Optional, but AI should auto-detect from context.
• INLINECODE2: Version description. AI should auto-generate meaningful descriptions based on user actions.

AI Auto-Detection Rules / AI 自动判断规则:

• - User explicitly specifies a filename → Save that file / 用户明确指定文件名 → 保存该文件
• User says "save it" and context shows a recently edited/generated file → AI auto-fills the file path / 用户说"保存一下"且上下文中有刚编辑/生成的文件 → AI 自动填入该文件路径
• Cannot determine → Ask the user which file to save / 无法判断 → 向用户询问要保存哪个文件
• NEVER call without filepath expecting batch save / 禁止不带 filepath 直接调用并期望批量保存

2. List Versions

CODEBLOCK1

Output Example:
CODEBLOCK2

3. Restore Version (requires user confirmation / 需要用户确认)

CODEBLOCK3

Restoration Features:

• - Auto-backs up current file to INLINECODE3
• Fully restores file content (text and binary)

4. Diff Versions

CODEBLOCK4

5. Clean Versions

CODEBLOCK5

Safety Rules / 安全规则

The following operations require explicit user confirmation:

1. 1. Version restore / 版本恢复 - Will overwrite current file content
2. Version delete / 版本删除 - Permanently deletes snapshot data

Before calling these operations, the AI must:

1. 1. Show operation details and risks / 显示操作详情和风险
2. Wait for explicit user confirmation / 等待用户明确确认
3. Set confirm=True parameter / 设置 confirm=True 参数

Path Security / 路径安全：
All file_path parameters are validated server-side to stay within the workspace boundary. Paths containing ../ or absolute paths outside the workspace are rejected with an error. The AI must never pass system-level paths (e.g., ../../etc/passwd, C:\Windows\...) as file_path.

Technical Implementation

Storage Architecture

CODEBLOCK6

Design Notes:

• - All workspaces share the same storage directory, version snapshots are accessible across workspaces
• Directory names are prefixed with workspace directory name (e.g., 20260325084235) for readability and disambiguation
• INLINECODE12 in filenames is replaced with -, path separators replaced with _ to ensure unique keys
• Text files: Content embedded directly in JSON
• Binary files: Copied to version directory (e.g., v1.png), JSON stores only a file reference (no base64)
• INLINECODE16 can be auto-rebuilt from disk v*.json files if corrupted or lost

Global Index Structure (index.json):
CODEBLOCK7

Version File Structure (v1.json)

File Structure

AI Usage Guide

Key Principles

1. 1. Smart filepath detection / 智能判断 filepath - AI should auto-detect which file to save based on context. When user says "save it", save the file just edited/generated; when user specifies a filename, save that file; when uncertain, ask the user.
2. Auto-generate message / 自动生成 message - AI should auto-generate meaningful version descriptions (e.g., "Added section 3", "Fixed typo").
3. List before save / 先 list 后 save - Check existing version history before saving to avoid duplicating identical content.
4. Clear version display / 清晰展示版本关系 - Display versions grouped by file with clear version numbers and change descriptions.

Example Workflow

CODEBLOCK10