Skip to content

Preview CLI

不執行伺服器即可驗證配置和預覽標註模式。

Preview CLI 可以驗證標註配置並預覽模式的渲染效果，無需執行完整伺服器。這對於快速原型設計、除錯和 CI/CD 驗證非常有用。

概述

Preview CLI 提供：

  • 配置驗證：在部署前檢查錯誤和警告
  • 模式預覽：檢視標註模式將如何渲染為 HTML
  • 快捷鍵衝突檢測：識別衝突的鍵盤快捷鍵
  • 多種輸出格式：摘要、HTML、JSON 或僅佈局片段

基本用法

bash
# Default summary output
python -m potato.preview_cli config.yaml
 
# Or using the module directly
python -m potato.preview_cli path/to/your/config.yaml

輸出格式

摘要（預設）

顯示配置的文本摘要：

bash
python -m potato.preview_cli config.yaml

輸出：

text
============================================================
ANNOTATION TASK PREVIEW
============================================================
Task Name: Sentiment Annotation
Task Directory: ./my_task

Validation: PASSED

ANNOTATION SCHEMAS (2 total):
----------------------------------------
  [radio] sentiment
          Select the sentiment of the text...
          Labels: 3
          Keybindings: 3

  [multiselect] topics
          Select all relevant topics...
          Labels: 5
          Keybindings: 0

============================================================

HTML 輸出

生成完整的 HTML 頁面預覽：

bash
python -m potato.preview_cli config.yaml --format html > preview.html

在瀏覽器中開啟 preview.html 檢視標註模式的外觀。

JSON 輸出

生成結構化 JSON 輸出用於程式設計處理：

bash
python -m potato.preview_cli config.yaml --format json

僅佈局 HTML

僅生成標註模式的 HTML 片段：

bash
python -m potato.preview_cli config.yaml --layout-only > task_layout.html

這對於嵌入自定義模板或單獨測試模式渲染非常有用。

命令列選項

選項簡寫描述
--format-f輸出格式：summary、html 或 json
--layout-only-l僅輸出任務佈局 HTML 片段
--verbose-v啟用詳細/除錯輸出

配置驗證

Preview CLI 驗證你的配置並報告問題：

錯誤（阻塞性）

text
ERROR: Missing required field 'annotation_task_name'
ERROR: Must have either 'data_files' or 'data_directory'

警告（非阻塞性）

text
WARNING: No annotation schemes found in configuration
WARNING: Key '1' used by both 'schema1:Label1' and 'schema2:Label2'

退出碼

  • 0：配置有效
  • 1：配置有錯誤

在 CI/CD 管道中使用退出碼：

bash
python -m potato.preview_cli config.yaml || echo "Config validation failed"

使用場景

快速原型設計

快速迭代模式設計：

bash
# Edit config, then preview immediately
python -m potato.preview_cli config.yaml --format html > preview.html && open preview.html

CI/CD 整合

在部署管道中驗證配置：

yaml
# .github/workflows/validate.yml
- name: Validate Potato Config
  run: python -m potato.preview_cli configs/production.yaml

模板開發

生成佈局片段用於自定義模板整合：

bash
python -m potato.preview_cli config.yaml --layout-only > templates/includes/schemas.html

API 參考

Preview CLI 函式也可以程式設計方式使用：

python
from potato.preview_cli import (
    load_config,
    validate_config,
    get_annotation_schemes,
    detect_keybinding_conflicts,
    generate_preview_html,
)
 
# Load and validate
config = load_config("config.yaml")
issues = validate_config(config)
 
# Extract schemes and check for conflicts
schemes = get_annotation_schemes(config)
conflicts = detect_keybinding_conflicts(schemes)
 
# Generate output
html = generate_preview_html(schemes)

故障排除

"Module not found" 錯誤

確保已安裝 Potato：

bash
pip install potato-annotation

模式渲染錯誤

如果模式渲染失敗，輸出將包含錯誤訊息。請檢查模式配置是否完整。

延伸閱讀

有關實現細節，請參閱原始碼文件。