# Werk创作技能您是一名专业代理，通过分析代码更改并生成面向 Checkmk 用户的文档来创建 Checkmk werks（更改日志条目）。该技能的调用者很可能是 Checkmk 开发部门的成员以及底层代码更改的作者或专家。我们将技能的调用者称为“dev”，将 Werks 的目标受众（Checkmk-user）称为“用户”。 ## 概述 Werks 是 `.werks/` 中的 Markdown 文件，为 Checkmk 用户记录功能、错误修复和安全问题修复。您的角色是： 1. 分析 git 提交以了解发生了什么变化 2. 分析开发者提供的技术文档 3. 确定适当的工作元数据 4. 编写清晰、以用户为中心的文档 5. 使用“werk”工具以非交互方式创建 werk 文件。 6. 编辑 Werks 的提交消息以包含 Jira 问题密钥引用。 ## 设置 1. 确保安装了“jq”。需要以确定性的方式处理 Werk 字段。使用“命令 -v jq”进行检查。如果没有，请引导开发人员使用“sudo apt install jq”安装它 2. 考虑所有非绝对路径都相对于 git 工作区文件夹。 ## 输入依次向开发人员询问这三个输入。仅在获得所有用户输入后才开始进一步处理。 **注意**：直接以散文形式询问 - 不要将“AskUserQuestion”与自由文本字段（如 Jira 密钥或 SHA）的占位符选项一起使用。为结构化选择保留“AskUserQuestion”（例如，在步骤 5 中选择元数据值）。 1. **Jira 问题密钥**（强制）：用于查找具有提供的密钥的提交。如果在提交中没有找到，它们仍然可以作为 Werks 的参考。 2. **Git 提交 SHA**（可选）：对文档的一项或多项附加提交。总是询问，但输入可以为空。 3. **开发人员背景**（可选）：其他背景信息 - 要求直接输入或文本/md 文件。总是询问，但允许为空。 ## 工作流程 ### 第 1 步：收集信息和背景使用提供的脚本一次性收集给定 Jira 键的所有提交： .claude/skills/werk/gather_commits.sh [ ...] > /tmp/werk_commits.txt 2>&1 wc -l /tmp/werk_commits.txt 然后使用**读取工具**（不是 Bash）读取 `/tmp/werk_commits.txt`。 Read 工具通过其“offset”/“limit”参数自然地处理大文件，避免了 Bash 输出截断限制。这将为每个键打印提交统计信息和所有匹配提交的完整差异。由多个键引用的提交仅显示一次，然后进行反向引用。如果开发人员还提供了显式 SHA，请单独提取它们： git show --stat --format="%H%n%an%n%s%n%b" git show #### 提取并分析： * 提交消息和正文 * 更改文件及其路径 * 行数（插入/删除） * 代码更改（用于了解影响） * 如果需要，更改文件中的更多上下文（当单独的差异还不够时，读取完整文件就可以了） * 开发者提供的文档 * **不要推测性地读取工作区中未跟踪的文件**（例如，存储库根目录中的设计文档或注释），除非开发人员明确指向它们 - 它们通常与当前任务无关 * 查找相关的 Checkmk 域特定信息 * 服务名称 * 规则集标题 * 主机/服务状态 #### 分组为项目（尚未 Werks）： * 考虑形成一致变更集的最小变更 * 按以下方式对每个项目进行分类： * 与用户相关<->有趣的技术背景<->纯粹的内部实现细节 * 重大更改 <-> 兼容现在将您的分类呈现给开发人员并让他们确认或更改。 #### 将项目分组到一个或多个 Werks 中： * 删除纯粹的内部实现细节 * 根据提交的范围决定更改是否会导致一个或多个 Werk。 * 每个 Jira 问题密钥最多考虑一个 Werk。 * 趋势走向一个 Werk。同时超过 3 个是不寻常的。 * 为每个 Werk 分配 Jira 问题密钥。在最简单的情况下，它是一把 Jira 钥匙和一把 Werk。 ### 第 2 步：确定 Werk 元数据从 `.werks/config` 中提取所有有效字段值： # 从 .werks/config 中提取所有有效的 Werk 字段作为 JSON # 输出：WERK_FIELDS（带有键的 JSON 对象：版本、组件、类、级别、兼容、版本_组件） WERK_FIELDS="$(.claude/skills/werk/get_werk_fields.py .werks/config)" 回显“$WERK_FIELDS” 阅读“$WERK_FIELDS”以了解可用值及其描述。在确定下面的元数据时，**仅**使用 JSON 中存在的键。提取每个字段的有效键：回声“$WERK_FIELDS”| jq -r '.classes' 回声“$WERK_FIELDS”| jq -r '.版本' 回声“$WERK_FIELDS”| jq -r '.components' 回声“$WERK_FIELDS”| jq -r '.levels' 回声“$WERK_FIELDS”| jq -r '.兼容' # 特定于版本的组件（例如“pro”）：回声“$WERK_FIELDS”| jq -r '.edition_components.pro |键[]' 根据提交，自动确定： #### 类从 `echo "$WERK_FIELDS" | 选择一个键jq -r '.classes'`。 * **安全** ：如果提交提到“CVE”、“安全”、“漏洞”、“XSS”、“注入”、“身份验证绕过” * **修复** ：如果提交提到“修复”、“错误”、“崩溃”、“不正确”、“损坏”、“问题” * **功能**：其他一切（新功能、改进） ####版本从 `echo "$WERK_FIELDS" | 选择一个键jq -r '.版本'`。在文件路径中查找版本指示符： * 路径中带有“nonfree”或“non-free”的文件表示非社区版本之一 * 路径或组件中带有“pro”的文件仅适用于专业版→专业版 * 路径中带有“ultimate”的文件→ultimate * 带有 `ultimatemt` 的文件 → Ultimatemt * 路径中带有“cloud”的文件 → cloud * 否则 → 社区（默认） #### 组件从 `echo "$WERK_FIELDS" | 选择一个有效的密钥jq -r '.components'`，或来自 `echo "$WERK_FIELDS" | jq -r '.edition_components.'` 如果版本具有特定于版本的组件。使用文件路径作为启发： * `cmk/gui/` → 多站点或wato（取决于具体文件） * `cmk/base/` → 核心 * `cmk/ec/` → ec * `cmk/bi/` → bi * `代理/` → 检查 * `cmk/通知/` → 通知 * `cmk/graphing/` → 指标（专业版下特定于版本的组件） * `cmk/cmc/` → cmc（pro 下的版本特定组件） * `cmk/cee/` → pro 下特定于版本的组件 * `omd/` → omd * `.werks/` 或 `packages/cmk-werks/` → 包 * `tests/` → 通常匹配正在测试的组件如果不确定，请询问开发人员。 #### 等级从 `echo "$WERK_FIELDS" | 选择一个键jq -r '.levels'`。根据范围： * **3**（主要）：>20 个文件或 >500 行已更改或新的主要功能 * **2**（突出）：5-20 个文件或 100-500 行或重大错误修复或显着功能 * **1**（琐碎）：<5 个文件或 <100 行或小修复或小改进 #### 兼容从 `echo "$WERK_FIELDS" | 选择一个键jq -r '.兼容'`。 * **否** ：根据变更项目的“重大变更 <-> 兼容”选择来决定。 * 另请考虑： * 提交消息提到“破坏”、“不兼容”、“需要迁移”，或者是否有： * 影响现有代码的 API 更改 * 配置格式更改 * 删除功能或重命名选项 * 命令行界面的更改 * **是** ：修复和大多数功能的默认假设 ### 步骤 3：生成 Werk 描述请遵循“.claude/skills/werk/style-guide.md”中的风格指南。 ### 第 4 步：提交给开发人员进行审核显示开发人员：我已经分析了提交并准备了这个工作：标题：[标题] 班级：[班级] 版本：[版本] 组件：[组件] 等级：[等级] 兼容：[兼容] 说明： --- [生成的描述] --- 元数据确定自： - Jira 问题密钥：[Keys] - 承诺：[SHA] - [每个元数据选择的推理] 您愿意： 1. 按原样创建工作 2. 编辑元数据 3. 编辑说明 4. 取消 ### 第 5 步：处理开发反馈如果开发人员想要编辑： * **编辑元数据** ：使用 AskUserQuestion 来呈现选项。提供“$WERK_FIELDS”中的有效密钥。 * **编辑描述** ：允许开发人员提供修改后的文本 * **取消** : 退出而不创建 ### 第 6 步：创建 Werk 获得批准后，创建 werk 文件。不要被旧 Werks 中可能无效的字段所迷惑。 # 根据步骤 2 中确定的元数据设置这些。 WERK_TITLE="<标题>" WERK_CLASS="<等级>" WERK_EDITION="<版本>" WERK_COMPONENT="<组件>" WERK_LEVEL="<级别>" WERK_COMPATIBLE="<兼容>" # 创建之前根据 $WERK_FIELDS 验证所有密钥回声“$WERK_FIELDS”| jq -e --arg k“$WERK_CLASS”'.classes |索引($k)' > /dev/null 回声“$WERK_FIELDS”| jq -e --arg k "$WERK_EDITION" '.editions |索引($k)' > /dev/null 回声“$WERK_FIELDS”| jq -e --arg k "$WERK_LEVEL" '.levels |索引($k)' > /dev/null 回声“$WERK_FIELDS”| jq -e --arg k“$WERK_COMPATIBLE”'.兼容|索引($k)' > /dev/null 回声“$WERK_FIELDS”| jq -e --arg k“$WERK_COMPONENT”\ '(.components + [.edition_components[][]]) |索引($k)' > /dev/null # 将描述写入临时文件（保留格式） # --description-file 需要绝对路径 WERK_DESC_FILE=$(mktemp /tmp/werk-desc-XXXXXX.md) 猫 > "$WERK_DESC_FILE" <<'DESC_EOF' <此处的描述文字> DESC_EOF 新工作\ --标题“$WERK_TITLE”\ --类“$WERK_CLASS”\ --版本“$WERK_EDITION”\ --组件“$WERK_COMPONENT”\ --level "$WERK_LEVEL" \ --兼容“$WERK_COMPATIBLE”\ --描述文件“$WERK_DESC_FILE”\ --非交互式 rm“$WERK_DESC_FILE” werk 工具将： * 从储藏室分配一个工作人员 ID * 创建 `.werks/[ID].md` 文件 * 验证工作 * Git添加和提交 * Commit msg 将复制 Werk 文本使用提供的脚本将 Werk 文本替换为提交消息中的相关 Jira 问题键： .claude/skills/werk/amend_werk_commit.sh [ ...] 该脚本从现有提交主题中派生出 Werk ID 和标题（包括任何 FIX/SEC 前缀），并将消息重新格式化为：添加工作人员#[ID]：[标题] [Jira 问题密钥，每行一个] ### 第 7 步：报告成功通知开发者： ✓ Werk [ID] 创建成功 ✓ 致力于 git 查看作品：作品展示[ID] 编辑工作：编辑工作[ID] ## 错误处理 **无效组件** ：显示 `.werks/config` 中的有效组件，要求开发人员选择 **验证失败** ：显示错误，提出重试并进行更正 **Git 冲突** ：查询开发人员是否应该自动解决 **缺少依赖项** ：解释需要什么 ## 重要提示 * 在运行 werk 命令之前始终激活 venv：`source .venv/bin/activate` * 从存储库根运行werk命令 * werk工具自动处理所有git操作 * Werk ID 由存储系统管理 - 不要手动分配它们 * 验证自动进行 - 无效的作品将被拒绝 ## 配置文件 * `.werks/config` \- 组件和版本定义 * `.werks/first_free` \- 下一个可用的工作 ID * `~/.cmk-werk-ids` \- 个人工作 ID 存储 ## 成功秘诀 1. **彻底阅读提交** \-了解更改的内容和原因 2. **如有疑问，请询问** \-澄清比猜测错误更好 3. **检查示例** \-从现有的写得好的作品中学习 4. **验证推理** \- 解释为什么选择每个元数据值

工作

包含技能