knock-cli

Knock CLI 技能

此技能提供使用 Knock CLI 管理工作流、模板及其他通知资源的全面指南。

概述

Knock CLI 技能包含详细的规则集，涵盖：

1. CLI 安装与身份验证 - 如何安装 Knock CLI 并完成身份验证
2. Knock 目录结构 - 了解 knock 目录布局和配置
3. CLI 命令参考 - 拉取、推送和资源管理命令
4. 工作流模板 - 工作流和模板的结构、模式及最佳实践
5. 指南和消息类型 - 使用用于生命周期消息的应用内指南，以及作为其架构的消息类型
6. 局部模板 - 用于电子邮件设计系统的可复用模板构建块

如何使用此技能

初始设置

使用 Knock 设置新项目时：

1. 从安装和身份验证开始（rules/cli-installation-authentication.md）

   • 确认已安装 CLI
   • 使用服务令牌或仪表板账户进行身份验证
   • 使用 knock init 初始化项目

2. 了解目录结构（rules/knock-directory-structure.md）

   • 学习 knock.json 配置
   • 了解资源的组织方式

管理资源

使用 Knock 资源时：

1. 参考 CLI 命令（rules/cli-commands-reference.md）

   • 从 Knock 拉取资源到本地项目
   • 将更改推回 Knock
   • 使用特定类型的资源

2. 遵循工作流和模板指南（rules/workflow-templates.md）

   • 了解模板模式和结构
   • 避免文件路径和变量方面的常见错误
   • 遵循修改工作流的最佳实践

管理指南和消息类型

使用应用内指南（横幅、模态框、公告）时：

1. 从指南和消息类型开始（rules/guides-and-message-types.md）

   • 了解指南与工作流相互独立（生命周期消息与通知）
   • 消息类型定义架构；指南通过 schema_key 和 schema_variant_key 引用消息类型
   • 尽可能使用内置类型（banner、modal、card）；需要时创建自定义消息类型

2. 创建前先查找

   • 运行 knock message-type list 查看可用的消息类型键
   • 运行 knock guide list 查看现有指南
   • 创建新指南时，使用输出中的准确键值

使用局部模板

构建可复用的电子邮件组件（提示框、引用块、评论卡片）时：

1. 从局部模板开始（rules/partials.md）

   • 了解局部模板文件结构和 partial.json 架构
   • 为区块编辑器字段定义 input_schema（格式与消息类型变体字段相同）
   • 对需要显示在电子邮件可视化区块编辑器中的局部模板，使用 visual_block_enabled: true

2. 创建并推送

   • 运行 knock partial new -k <key> -n "Name" -t html --force 来搭建脚手架
   • 添加 input_schema 并编辑内容；验证后使用 knock partial push <key> 推送

修改工作流和模板

更改工作流或模板时：

1. 先阅读，再修改 - 修改前先了解现有结构
2. 新建电子邮件时使用可视化区块 - 默认始终使用可视化区块模式；仅在明确要求时使用 HTML 模式
3. 使用正确的变量命名空间 - 触发负载使用 data，环境变量使用 vars
4. 检查文件路径引用 - 路径相对于包含该引用的文件
5. 修改后推送 - 本地文件更改在推送前不会同步到 Knock。运行 knock workflow push <key>（或其他资源类型对应的命令），使更改生效。

规则文件参考

• rules/cli-installation-authentication.md - 安装和身份验证设置
• rules/knock-directory-structure.md - 目录结构和配置
• rules/cli-commands-reference.md - 用于资源管理的 CLI 命令
• rules/workflow-templates.md - 工作流和模板结构及最佳实践
• rules/guides-and-message-types.md - 生命周期消息的指南和消息类型
• rules/partials.md - 局部模板和可复用的模板构建块

快速参考

常用命令

# Initialize a new project (interactive; prompts for the resources directory)
knock init

# Pull all resources from Knock (--force skips confirmation prompts)
knock pull --force

# Pull a specific workflow
knock workflow pull <workflow-key> --force

# Push all resources to Knock (push never prompts)
knock push

# Push a specific workflow
knock workflow push <workflow-key>

# Push a specific email layout
knock layout push <layout-key>

# List channels (discover valid channel_key values before creating workflows)
knock channel list

# Guide and message type commands
knock message-type list          # Discover message type keys before creating guides
knock guide list                 # List existing guides
knock guide push <guide-key>     # Push a guide after modifying
knock message-type push <key>    # Push a message type after modifying

# Partial commands (email design system building blocks)
knock partial list               # List existing partials
knock partial new -k <key> -n "Name" -t html --force   # Create a new partial
knock partial pull <key> --force # Pull a partial from Knock
knock partial push <key>         # Push a partial after modifying
knock partial validate <key>     # Validate a partial locally

# Commit and promote a specific resource only (safe when other resources have pending changes)
knock commit -m "message" --resource-type=workflow --resource-id=<key> --force
knock commit list --resource-type=workflow --resource-id=<key>   # get the commit ID
knock commit promote --only=<commit-id> --force

核心概念

• knockDir：存储 Knock 资源的目录（在 knock.json 中配置）
• 资源类型：workflows、layouts、guides、message-types、translations、partials、audiences、schemas
• 指南与工作流：指南用于生命周期消息（横幅、模态框）；工作流用于通知
• 模板模式：可视化区块（新建电子邮件时的默认模式）与 HTML（仅在明确要求时使用）
• 变量命名空间：data（触发负载）、vars（环境变量）、recipient、actor、tenant

重要模式

1. 对带提示的命令使用 --force - 许多 CLI 命令（pull、commit、promote、activate）会显示交互式确认提示。在自动化或 Agent 场景中，始终传入 --force 以跳过这些提示。
2. 每次更改后都要推送 - 本地编辑会保留在本地，直到推送为止。不推送 = Knock 中不会更新。
3. 文件路径引用使用 @ 后缀："content@": "visual_blocks/1.content.md"
4. 路径相对于所在文件：不要重复添加步骤目录
5. 触发负载的值始终使用 data.，而不是 vars.
6. 修改前先读取现有文件，以保留其结构
7. 创建工作流前先查找渠道键 - 运行 knock channel list 获取有效的 channel_key 值
8. 创建指南前先查找消息类型键 - 运行 knock message-type list 获取有效的消息类型键
9. 处理单个资源时限定提交和推广的范围 - knock commit promote --to=<env> 会推广所有资源中尚未推广的提交。处理单个资源时，使用 --resource-type 和 --resource-id 仅提交该资源，然后使用 knock commit promote --only=<commit-id> 仅推广该提交。请参阅下方“仅推广特定资源”工作流。

最佳实践总结

1. 编辑前先拉取 - 修改前同步最新更改
2. 修改后推送 - 本地更改只有在明确推送后才会保存到 Knock
3. 先读后写 - 了解现有结构，避免数据丢失
4. 使用正确的命名空间 - 动态负载使用 data，环境常量使用 vars
5. 默认使用可视化区块 - 新建电子邮件时使用可视化区块；编辑时保留现有模式
6. 验证路径 - 文件引用相对于所在文件
7. 测试更改 - 推送更改后验证工作流
8. 限定提交和推广的范围 - 处理单个资源时，提交默认使用 --resource-type/--resource-id，推广默认使用 --only。只有在打算推广所有资源中的所有待处理更改时，才使用 knock commit promote --to=<env>。