Mastra Code 技能实战用 herdr-manager-query 安全查询 Herdr Review/Work Manager 库存并推荐 PR 工作【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra本文基于 Mastra 仓库 .mastracode/skills/herdr-manager-query/SKILL.md 编写。该技能是 Mastra Code.mastracode内置的 Agent 技能之一用于在 Herdr 会话中通过herdr-kit插件的稳定公共 CLI以只读方式查询权威的 Review Manager 与 Work Manager 全局库存、推荐可执行的 PR 工作并在用户明确确认后物化materialize远程独有的 Review Manager 记录。读完本文你将掌握该技能的安全边界、完整调用链插件发现 → 能力协商 → 库存查询 → 本地过滤 → 推荐排序 → 显式物化以及所有可复制的命令行与 JSON 请求模板。技能定位仓库无关的权威数据源herdr-manager-query技能的核心主张是以已启用的herdr-kit插件作为仓库无关repository-independent的权威来源用于获取 Review Manager 与 Work Manager 数据。它适用于以下场景的激活用户请求评审review用户自己提交的 PRauthored PRs被托管的 checkoutmanaged checkoutsHerdr 工作区workspacesManager 的评审 / CI / 活动 / 新鲜度 / 清理状态查询工作推荐work recommendations显式的 Review Manager 物化materialization。与配套的 .mastracode/skills/herdr-kit-workflows/SKILL.md 相比后者负责 Herdr Kit 的安装、配置、同步与工作树生命周期materialize/dematerialize 的完整运维流程而本技能专注于查询、推荐与 Review Manager 的显式物化这一条只读为主的工作流。安全边界与权威性约束技能首先定义了不可逾越的安全与真相来源source of truth规则查询与推荐是只读的。任何manager query与推荐行为都不得写回库存。Manager 库存是权威的。绝不使用直接 GitHub /gh、当前目录 Git、TUI 抓取、原始 manager 状态文件或其他库存来替代。出错即停绝不降级回退。若发现discovery、能力协商capability negotiation、查询执行、JSON 解析、schema 校验或相关来源报错必须停止并报告确切问题。禁止的操作禁止同步synchronize、去物化dematerialize、清理clean up、直接创建 Git worktree以及物化 Work Manager 记录。唯一允许的变更通过插件公共 CLI对权威的、仅远程存在remote-only的 Review Manager 记录进行用户明确确认后的显式物化。协议与 schema 版本是兼容性边界不要对不支持的版本做任何猜测。从源码结构看这条唯一可变更是 Review 物化的约束与 herdr-kit-workflows 中所有生命周期变更必须走公共 CLI、绝不手工操作 Git worktree的原则一致二者共同构成 Herdr Kit 的安全操作模型。发现已安装的接口技能要求通过 Herdr而不是当前仓库解析已启用插件的根目录。核心命令如下plugin_file$(mktemp) if ! herdr plugin list --plugin herdr-kit --json $plugin_file; then exit 1 fi if ! plugin_root$(python3 - $plugin_file PY import json, sys plugins json.load(open(sys.argv[1]))[result][plugins] plugin next((p for p in plugins if p.get(plugin_id) herdr-kit), None) if not plugin or not plugin.get(enabled) or not plugin.get(plugin_root): raise SystemExit(Enabled herdr-kit plugin root is unavailable) print(plugin[plugin_root]) PY ); then exit 1 fi manager_cli$plugin_root/herdr-kit要点解读输出写入mktemp临时文件避免大型 JSON 通过 shell 命令替换传递这也是后续所有查询的通用模式通过result.plugins列表定位plugin_id herdr-kit的条目并要求其enabled为真且存在plugin_root最终得到公共 CLI 的完整路径$manager_cli。技能明确提示绝不要直接运行裸herdr不带子命令做发现——那会启动或附加交互式 TUI 并挂起非交互会话见 herdr-kit-workflows 的说明必须始终使用显式子命令如herdr plugin list。协商能力协议版本是兼容性边界在任何查询或变更之前必须先协商能力capabilitiescapabilities_file$(mktemp) $manager_cli capabilities $capabilities_file python3 - $capabilities_file PY import json, sys p json.load(open(sys.argv[1])) if p.get(protocol_version) ! 1: raise SystemExit(fUnsupported herdr-kit protocol: {p.get(protocol_version)}) if not p.get(operations, {}).get(manager_query, {}).get(available): raise SystemExit(herdr-kit manager query is unavailable) PY关键校验逻辑检查顶层protocol_version必须等于1检查operations.manager_query.available必须为真。herdr-kit-workflows 中还进一步要求凡是使用--request的命令还必须校验对应操作的request_schema与请求文件的schema_version本文中均为1。若缺少必需能力、协议/请求 schema 不受支持或命令缺失应将其视为插件版本过旧的更新信号而不是调用私有脚本或自行发明回退方案的许可。查询工作流读取权威库存查询同样通过临时文件传递输出data_file$(mktemp) $manager_cli manager query $data_file python3 - $data_file PY import json, sys p json.load(open(sys.argv[1])) if p.get(protocol_version) ! 1: raise SystemExit(fUnsupported manager protocol: {p.get(protocol_version)}) inventory p.get(inventory, {}) if inventory.get(schema_version) ! 1: raise SystemExit(fUnsupported manager inventory schema: {inventory.get(schema_version)}) errors inventory.get(summary, {}).get(errors, []) if errors: raise SystemExit(Manager inventory error: ; .join(map(str, errors))) print(json.dumps(inventory.get(summary, {}), indent2)) PY查询结果的校验链路为protocol_version 1→inventory.schema_version 1→summary.errors为空 → 输出summary。库存条目inventory.items的结构技能规定在本地过滤inventory.items。每个条目都标识其来源 manager并包含以下维度的数据仓库 / PR 身份repository/PR identity与状态statecheckout 位置checkout locationHerdr 状态Herdr state评审reviews、CI、活动activity、新鲜度freshness、变更changes与清理cleanup数据。Review Manager 记录额外包含head_sha当前 HEAD 提交materialization.target_path物化目标路径diff下的 PR 差异统计如diff.changed_files、diff.total_changes。Review 元数据的结构化推理技能特别强调推理初始评审与后续跟进工作时应使用结构化的 review 元数据而不是笼统的活动时间戳reviews.your_latest_review_at与reviews.your_latest_review_sha标识用户最近一次提交的评审及被评审的提交reviews.events已提交的评审事件包含参与者actors、状态、时间戳、提交 SHA 与紧凑正文compact bodiesreviews.comments与reviews.unresolved_threads可用的评论与未解决讨论的时间信息。将每个条目自身的时间戳与reviews.your_latest_review_at比较只有更晚的条目才是后续反馈任一时间戳缺失时结果应视为未知reviews.commits_since_your_review用户最近一次评审之后提交的提交。技能还给出一个重要的时间推理准则比较事件时间戳而不是假设 PR 级别的activity_at一定发生在用户评审之后时间戳或事件缺失一律按未知处理。总体原则是缺失值按未知处理绝不视为有利默认值favorable defaults。推荐工作流对权威结果排序当被问及接下来评审或做什么时只对权威查询返回的记录排序。技能给出的优先级从高到低开放的 Review Manager PR用户被请求评审或已参与、且仍有可执行的评审工作的 PR同类可评审项中的小快赢quick wins按更少的diff.changed_files与更低的diff.total_changes优先然后考虑近期活动与通过的 CI开放的 Work Manager 条目存在可执行的作者跟进、评审、CI 或本地开发工作新鲜、无阻塞且下一步明确的记录具有清晰的下一步行动与安全的 checkout 状态。同时需要降级以下记录仅清理类cleanup-only、已合并/关闭/完成、陈旧/不可用、被阻塞blocked或本地有风险locally hazardous的记录。不要把缺失 diff 元数据当成小 PR。每条推荐都应包含仓库 / PR 与标题来源 managerReview 还是 Work推荐理由与规模rationale and size评审 / CI 状态远程独有remote only还是已物化materialized状态Herdr 状态警告warnings具体的下一步行动。技能还提醒一个认知陷阱remote only并不能证明记录是从未物化还是后来被去物化除非库存证据能区分两者。显式物化 Review Manager 记录物化是整套技能中唯一允许的变更操作因此约束最严格。前置条件与确认只有权威查询识别出manager: review且location: remote only的记录且用户明确确认了确切的仓库/PR 目标后才能物化当前用户消息若毫不含糊地请求这些确切目标可视为确认否则必须先询问询问前必须向用户展示每个目标仓库与 PR 编号/标题、不可变的 manager key、当前head_sha、materialization.target_path以及相关的新鲜度、资格、checkout 或冲突警告。冻结确认值并提交请求确认后将 key 与 head SHA冻结在请求文件中绝不刷新或静默替换已确认的 headrequest_file$(mktemp) cat $request_file JSON {schema_version:1,items:[{key:OWNER/REPO#NUMBER,head_sha:CONFIRMED_HEAD_SHA}]} JSON result_file$(mktemp) $manager_cli review materialize --request $request_file $result_file python3 - $result_file PY import json, sys p json.load(open(sys.argv[1])) if p.get(protocol_version) ! 1 or p.get(schema_version) ! 1: raise SystemExit(Unsupported materialization result schema) print(json.dumps(p, indent2)) PY注意请求文件的 schemaschema_version: 1items数组中每项包含key格式为OWNER/REPO#NUMBER与head_sha。CLI 的行为保证技能明确描述了公共 CLI 在变更前的校验与执行行为批量支持多个已确认的评审应放在同一请求文件中逐项校验CLI 会针对权威的当前库存校验每个条目拒绝陈旧的 head并将新鲜度/资格/head/仓库/路径安全性检查委托给 Review Manager容错单个条目失败后继续处理其余条目返回结构化的逐项结果per-item outcomes成功判定只有在 CLI重新查询权威 manager 状态并验证记录已物化含 checkout 路径之后才报告成功后端行为后端创建规范的 review worktree 并打开/聚焦其 Herdr 工作区无需 Sync All。失败后的纪律逐字报告每个结果绝不在 head 已变化的情况下重试陈旧/失败条目——除非展示新的库存状态并获得用户新的确认绝不回退到手工创建 Git worktree。响应指南技能对 Agent 的最终响应提出了明确要求同样适用于任何集成该技能的自动化流程回答具体问题除非被要求否则不要倾倒整个库存清晰区分 Review Manager 与 Work Manager 记录对 PR 支撑的条目包含仓库与 PR 编号明确提示remote-only 状态、关闭的 Herdr 工作区、脏/未推送的变更、陈旧元数据、阻塞性 CI/评审、清理警告解释不确定性与排序权衡而不是臆造上下文。与配套技能的分工.mastracode目录下的技能体系将查询与推荐本技能与安装、同步与生命周期运维.mastracode/skills/herdr-kit-workflows/SKILL.md分离。二者共享相同的安全内核通过herdr plugin list --plugin herdr-kit --json发现插件绝不假设当前仓库包含插件以capabilities与protocol_version: 1作为兼容性边界以manager query作为 manager key、revision、head、checkout generation、路径、警告与后置条件的权威来源所有变更sync、materialize、dematerialize、scope 管理只走公共 CLI绝不调用私有脚本、编辑 manager 状态或手工操作 Git worktree。因此在实际的 Herdr Mastra Code 工作流中推荐的做法是先激活本技能完成只读查询与推荐待用户确认目标后若需要同步或管理工作树生命周期再切换到 herdr-kit-workflows 的对应流程如manager sync review/work、review materialize --request、review/work dematerialize --request并在每次变更后用一次新鲜的manager query验证后置条件fail closed。这一查询 → 确认 → 变更 → 复核的闭环正是 Herdr Kit 技能体系保障仓库与工作区安全的核心设计。【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考