Skip to content

Preview CLI

不运行服务器即可验证配置和预览标注模式。

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

模式渲染错误

如果模式渲染失败，输出将包含错误消息。请检查模式配置是否完整。

延伸阅读

有关实现细节，请参阅源代码文档。