Version Master

Cleanup Review

python scripts/_cache_clear.py is an optional cleanup helper for the Version-Master 2.1.0 skill. It may recursively remove ~/.cache/skill_tmp, ~/.skill_state. Show the exact paths first, explain whether they are skill-private temporary paths or user state, and run the cleanup only after the user confirms.

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. 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. 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

# Save a specific file
save_version(file_path="ai_news_20260324.md", message="Added 11th news item")

Key Parameters:

• file_path: File path (relative to workspace). Optional, but AI should auto-detect from context.
• message: 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 file_path expecting batch save / 禁止不带 file_path 直接调用并期望批量保存

2. List Versions

# List all files with version history
list_versions()

# List version history of a specific file
list_versions(file_path="ai_news_20260324.md")

Output Example:

ai_news_20260324.md (3 versions)
  v3 - Added 11th news item | 2026-03-25 08:08
  v2 - Added 6 tech news items | 2026-03-25 08:05
  v1 - Initial version, 10 AI news items | 2026-03-25 08:03

interesting_news.md (1 version)
  v1 - Tech, sports, military highlights | 2026-03-25 08:10

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

# Restore to a specific version
restore_version(file_path="ai_news_20260324.md", version=2, confirm=True)

# Restore to the latest version
restore_version(file_path="ai_news_20260324.md", confirm=True)

Restoration Features:

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

4. Diff Versions

# Compare two versions of the same file
diff_versions(file_path="ai_news_20260324.md", version1=1, version2=3)

# Compare current file with a historical version
diff_versions(file_path="ai_news_20260324.md", version2=2)

5. Clean Versions

# Delete all versions of a file
clean_versions(file_path="test.txt", confirm=True)

# Delete a specific version of a file
clean_versions(file_path="test.txt", version=1, confirm=True)

Safety Rules / 安全规则

The following operations require explicit user confirmation:

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

Before calling these operations, the AI must:

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

~/.workbuddy/versions/version-master/
├── index.json                                    # Global index (file → version mapping)
├── 20260325084235_ai_news_20260324-md/           # One directory per file (prefixed with workspace ID)
│   ├── v1.json                                  # Version 1 (text content embedded in JSON)
│   ├── v1.md                                    # Version 1 binary reference file (if any)
│   ├── v2.json                                  # Version 2
│   └── v3.json                                  # Version 3
└── 20260325084235_interesting_news-md/
    └── v1.json

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
• . 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)
• index.json can be auto-rebuilt from disk v*.json files if corrupted or lost

Global Index Structure (index.json):

{
  "files": {
    "20260325084235_ai_news_20260324-md": {
      "rel_path": "ai_news_20260324.md",
      "next_version": 4,
      "versions": [
        {
          "version": 1,
          "timestamp": "2026-03-25T08:03:00",
          "content_hash": "abc123...",
          "file_size": 2928,
          "summary": "Initial version, 10 AI news items",
          "version_file": "20260325084235_ai_news_20260324-md/v1.json"
        }
      ]
    }
  }
}

Version File Structure (v1.json)

{
  "version": 1,
  "timestamp": "2026-03-25T08:03:00",
  "content_hash": "abc123...",
  "file_size": 2928,
  "summary": "Initial version, 10 AI news items",
  "message": "Initial version",
  "content": {
    "type": "text",
    "content": "# AI News Briefing\n\n..."
  }
}

File Structure

version-master/
├── SKILL.md              # Skill documentation
├── requirements.txt      # Dependencies
└── scripts/
    ├── __init__.py
    └── version_tool.py   # Core implementation

AI Usage Guide

Key Principles

1. Smart file_path detection / 智能判断 file_path - 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

User: "帮我把 ai_news.md 保存一下" / "Save ai_news.md for me"
AI:
  1. Call list_versions(file_path="ai_news.md") to check existing versions
  2. Analyze current file content changes
  3. Call save_version(file_path="ai_news.md", message="Added 3 new news items")
  4. Show result: "ai_news.md saved as v3"

User: "恢复到上一个版本" / "Restore to previous version"
AI:
  1. Check version history, confirm current is v3, previous is v2
  2. Prompt user: "About to restore ai_news.md to v2 (Added 3 news items → Initial version). Confirm?"
  3. After user confirms, call restore_version(file_path="ai_news.md", version=2, confirm=True)