SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场knock-cli

knock-cli

部署与运维

查看项目

更新于 10-15 16:22

技能介绍

用途

Knock CLI 技能提供了一套完整的使用规范，用于通过 Knock CLI 管理 Knock 项目中的工作流、模板及其他通知资源。它覆盖从初始安装认证到日常资源同步的全流程指导，帮助开发者与自动化智能体以一致、安全的方式操作 Knock 资源。

主要能力

技能包含多份规则文档，分别覆盖以下主题：

  • CLI 安装与认证（rules/cli-installation-authentication.md）：如何安装并认证 Knock CLI。
  • Knock 目录结构（rules/knock-directory-structure.md）：理解 knock 目录布局与配置，包括 knock.json 与资源组织方式。
  • CLI 命令参考（rules/cli-commands-reference.md）：pull、push 及资源管理命令。
  • 工作流与模板（rules/workflow-templates.md）：工作流与模板的结构、模式与最佳实践。
  • 指南与消息类型（rules/guides-and-message-types.md）：面向生命周期消息的应用内指南，以及作为其 schema 的消息类型。
  • Partials（rules/partials.md）：用于邮件设计系统的可复用模板构建块。

使用方式

初始设置：从安装与认证开始，确认 CLI 已安装，使用服务令牌或仪表盘账号完成认证，然后运行 knock init 初始化项目（会提示填写资源目录），并理解 knock.json 配置与资源组织方式。

管理资源：使用命令参考从 Knock 拉取资源到本地项目，或将变更推送回 Knock。遵循工作流与模板规范，理解模板模式与结构，避免文件路径和变量方面的常见错误。

管理指南与消息类型：指南用于生命周期消息（横幅、模态框、公告），与工作流相互独立。消息类型定义 schema，指南通过 schema_key 和 schema_variant_key 引用它们。优先使用内置类型（banner、modal、card），需要时再创建自定义消息类型。创建前先运行 knock message-type list 和 knock guide list 发现可用的 key，并在创建新指南时使用输出中的精确 key。

使用 Partials：构建可复用邮件组件（标注、引用块、评论卡片）时，先了解 partial 文件结构与 partial.json schema。为块编辑器字段定义 input_schema（格式与消息类型变体字段相同），对于要出现在邮件可视化块编辑器中的 partial 使用 visual_block_enabled: true。可通过 knock partial new -k <key> -n "Name" -t html --force 脚手架创建，添加 input_schema 并编辑内容后，使用 knock partial push <key> 验证并推送。

修改工作流与模板：始终先读取再写入，在修改前理解现有结构；新邮件默认使用 visual blocks 模式，仅在明确要求时使用 HTML 模式；使用正确的变量命名空间——data 用于触发负载，vars 用于环境变量；验证文件路径引用（路径相对于包含该引用的文件）；修改后必须 push，本地文件变更在推送前不会同步到 Knock。

常用命令

# 初始化新项目（交互式；提示填写资源目录）
knock init

# 从 Knock 拉取所有资源（--force 跳过确认提示）
knock pull --force

# 拉取指定工作流
knock workflow pull <workflow-key> --force

# 推送所有资源到 Knock（push 不会提示）
knock push

# 推送指定工作流
knock workflow push <workflow-key>

# 推送指定邮件布局
knock layout push <layout-key>

# 列出渠道（创建消息类型前发现有效 channel_key 值）
knock channel list

# 指南与消息类型命令
knock message-type list          # 发现消息类型 key
knock guide list                 # 列出已有指南
knock guide push <guide-key>     # 修改后推送指南
knock message-type push <key>    # 修改后推送消息类型

# Partial 命令（邮件设计系统构建块）
knock partial list               # 列出已有 partial
knock partial new -k <key> -n "Name" -t html --force   # 创建新 partial
knock partial pull <key> --force # 从 Knock 拉取 partial
knock partial push <key>         # 修改后推送 partial
knock partial validate <key>     # 本地验证 partial

# 仅提交并提升指定资源（当其他资源有未提交变更时更安全）
knock commit -m "message" --resource-type=workflow --resource-id=<key> --force
knock commit list --resource-type=workflow --resource-id=<key>   # 获取 commit ID
knock commit promote --only=<commit-id> --force

关键概念

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

重要模式与最佳实践

  • 对带提示的命令使用 --force：pull、commit、promote、activate 等许多命令会显示交互式确认提示，在自动化/智能体场景中应始终传入 --force 跳过。
  • 每次修改后推送：本地编辑在推送前始终停留在本地，不 push 则 Knock 端不会更新。
  • 文件路径引用使用 @ 后缀，例如 "content@": "visual_blocks/1.content.md"。
  • 路径相对于包含该引用的文件，不要重复 step 目录。
  • 触发负载值始终使用 data.，而不是 vars.。
  • 修改前读取现有文件以保留结构。
  • 创建消息类型前先用 knock channel list 发现有效的 channel_key。
  • 创建指南前先用 knock message-type list 发现有效的消息类型 key。
  • 处理单个资源时限定 commit 与 promote 范围：knock commit promote --to=<env> 会提升所有资源中所有未提升的提交；处理单个资源时应使用 --resource-type 和 --resource-id 只提交该资源，再用 knock commit promote --only=<commit-id> 只提升该提交。

适用场景与限制

该技能适用于需要以代码方式管理 Knock 通知资源的开发与自动化场景，例如同步工作流、模板、指南、消息类型与 partials。遵循其规范可减少数据丢失和同步错误。资料中说明的命令与模式均需在已安装并认证 Knock CLI 的前提下使用；本地改动只有在 push 后才会生效，且在自动化上下文中需注意命令的确认提示与提交提升的作用范围。