Mastra 危险天气技能severe-weather灾害阈值参考与文件式技能体系实战【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra导读本文围绕 Mastra 示例仓库中weather-fs文件式 Agent所附带的灾害阈值参考文档展开逐条解读极端高温、极寒、大风与暴雨四类危险天气的判定阈值并深入说明这份thresholds.md如何在 Mastra 的文件式技能File-based Skill体系中被打包、内联、运行时注入给大模型使用。读完本文你将掌握 Mastra 打包技能packaged skill中references/目录的运作原理、阈值数据在源码层面的承载方式createSkill的references机制并能够基于这份示例快速扩展自己的灾害判定与安全提示逻辑。一、灾害阈值参考文档原文解读示例仓库中的weather-fsAgent 在其severe-weather技能目录下维护了一份精简但严谨的灾害判定标准完整内容位于 thresholds.md极端高温Extreme heat气温达到或超过35°C95°F极端低温Extreme cold气温达到或低于-10°C14°F大风High wind持续风速达到或超过60 km/h暴雨Heavy rain24 小时内降水量超过 50 mm这份表格有几点值得注意的设计取向明确的边界语义四条阈值分别使用了at or above≥、at or below≤、at or above≥与more than四种表达其中暴雨阈值与其他三条不同——它是严格的大于而非大于等于。Agent 在判定时不能把临界值含糊处理。温度双单位标注高温与低温阈值同时给出了摄氏与华氏数值35°C/95°F、-10°C/14°F这与weather-fs的另一个技能 units.md 的要求保持一致——该技能规定始终同时报告摄氏与华氏温度摄氏在前使用F C * 9/5 32换算并四舍五入到整数。数据是判定依据而非展示文案这份文档的角色是数据参考真正决定何时触发安全提示的行为规则写在技能主体 SKILL.md 中——它要求 Agent 在天气涉及风暴、洪水、极端高温或低温、大风等危险情况时在预报之前先输出一行安全提示并明确指示查阅references/thresholds.md了解构成危险的具体阈值。二、thresholds.md 在文件式技能体系中的位置在 Mastra 中技能Skill有两种形态扁平技能flat skill如units.md文件名即技能名文件正文即指令与打包技能packaged skill如severe-weather/目录目录内包含SKILL.md与可选的references/、scripts/、assets/等资源目录。weather-fs的目录布局如下详见 examples/agent/src/mastra/agents/weather-fs/README.mdweather-fs/ config.ts # model config overrides instructions.md # the agent instructions memory.ts # default-exported Memory instance tools/ get_weather.ts # default-exported tool, keyed by filename skills/ units.md # flat skill: filename is the name severe-weather/ SKILL.md # packaged skill: frontmatter name/description body references/ thresholds.md # inlined and exposed to the skill at runtime workspace/ cities.json README.md subagents/ forecaster/ ...从该 README 的映射表可以确认skills/severe-weather/SKILL.md是一个打包技能其 frontmatter 提供name/description而references/目录中的文件会在运行时被内联并暴露给该技能inlined and exposed to the skill at runtime。也就是说thresholds.md不是一份仅供人类阅读的备忘录而是会被 Mastra 的构建/代码生成层读取、与SKILL.md一起打包成模型可见内容的正式技能资源。这与weather-fs的整体定位一致该 Agent 是一个完全由文件约定定义的 Agent——不存在new Agent()调用也没有在src/mastra/index.ts中注册mastra dev/mastra build会自动发现它见 config.ts 的注释。config.ts中只显式指定了模型openai/gpt-5.4-mini指令、工具、技能、记忆与工作区全部来自目录约定。三、源码层阈值文件如何被内联进技能references/目录之所以能在运行时被技能引用其底层机制在 Mastra 核心包的createSkill工厂函数中有着清晰定义。查看 packages/core/src/skills/create-skill.tsexport function createSkill(input: InlineSkillInput): InlineSkill { const { name, description, instructions, license, compatibility, metadata, references } input; // Validate metadata (same checks as filesystem-discovered skills) const validation validateSkillMetadata(...); if (!validation.valid) { throw new Error(Invalid skill ${name}: ${validation.errors.join(; )}); } const referenceKeys references ? Object.keys(references) : []; return { __inline: true as const, __referenceContents: references ?? {}, name, description, instructions, license, compatibility, user-invocable: input[user-invocable], metadata, path: inline/${name}, source: { type: local, projectPath: inline/${name} }, references: referenceKeys, scripts: [], assets: [], }; }关键信息如下内联技能inline skill的references参数是一个文件名 → 文件内容的键值映射createSkill会将其保存为__referenceContents并把键列表暴露为references字段注释中的示例展示了典型用法references: { checklist.md: # Review Checklist\n... }——与thresholds.md被内联进severe-weather技能属于同一模式文件系统发现的技能与代码内联技能走同一套元数据校验validateSkillMetadata确保两种来源的技能行为一致。在文件式 Agent 的装配层packages/core/src/agent/fs-routing/index.ts 的注释明确说明文件系统技能发现后代码生成层会通过createSkill将每个SKILL.md及其references/内联the codegen layer inlines eachSKILL.md references viacreateSkill装配为FsAgentEntry.skills字段。因此weather-fs/skills/severe-weather/references/thresholds.md在构建后本质上等同于对severe-weather技能注入了{ thresholds.md: # Hazard thresholds\n- ... }这样的引用内容。四、运行时模型如何看到阈值数据内联后的引用内容不会被动地躺在内存里而是通过 Mastra 的技能工具链暴露给模型。从packages/core的技能处理器与测试可还原出完整的运行时链路技能处理器会在系统提示中注入available_skillsXML 块并自动注入skill、skill_search、skill_read三个工具参见 packages/core/src/loop/test-utils/aimock/README.md 对skills-integration.scenario.test.ts的描述模型在收到天气相关任务并判断触发severe-weather技能后可以调用skill_read读取引用文件——正如 SKILL.md 所指示的查阅references/thresholds.md技能的引用内容还会被索引用于 BM25 检索。在 packages/core/src/skills/agent-skills-resolver.test.ts 的测试中技能引用的references/runbook.md等文件会被索引模型可借助skill_search在技能与引用之间做语义检索测试同时展示了getReference这类按引用键获取内容的读取 API。也就是说thresholds.md中的四行阈值既是给人类维护者看的规范也是构建期被内联、运行期可被模型用skill_read/skill_search精确检索的数据。当用户在 Studio 中询问东京天气如何而结果达到 35°C 时模型会依据该参考判定为极端高温并按SKILL.md的要求先输出一行安全提示。五、完整工作流从提问到安全提示结合weather-fs各文件的职责一次触发灾害提示的完整链路可以还原为指令路由instructions.md 要求 Agent 遇到当前天气提问时调用get_weather工具并一句话汇报且遵守你的技能温度始终同时给出摄氏与华氏条件危险时先给出安全提示工具取数get_weather.ts 以city为入参、返回conditions与temperatureCelsius示例实现为桩数据注释说明生产环境应替换为真实 API技能触发当天气涉及风暴、洪水、高温/低温、大风等场景时模型命中severe-weather技能其 frontmatterdescription写明Use when conditions include storms, flooding, heat waves, or other hazards阈值比对模型读取references/thresholds.md将temperatureCelsius及换算后的华氏值与 35°C/95°F、-10°C/14°F 等阈值比对同时按 units.md 的换算规则输出双单位安全优先SKILL.md规定危险情形下先用一行安全提示开头再给出预报。多日预报场景则由forecaster子代理接管可嵌套historian子代理深度上限为MAX_FS_SUBAGENT_DEPTH见 README.md子代理同样可以按需携带或触发技能。六、实战扩展维护你自己的灾害阈值以thresholds.md为模板扩展其他危险天气判定的做法非常直接——只需在references/目录下维护数据并让SKILL.md的指令指向它增补阈值条目沿用阈值名 边界语义 数值的格式追加例如空气质量AQI、雷暴能见度/闪电密度等注意保持边界词at or above / more than精确避免模型在临界值上摇摆更新技能指令在 SKILL.md 中补充对应新条目的触发条件与安全提示模板保持单位约定若新增温度类阈值务必与units.md的双单位换算规则保持一致在 Agent 指令中回链可在 instructions.md 中显式提到依据技能参考中的阈值判定危险天气增强模型遵循度本地验证在仓库根目录运行pnpm --filter ./examples/agent mastra dev安装步骤见 examples/agent/README.md打开 Studio 选择weather-fs用东京天气如何来一场风暴会怎样等提问验证安全提示是否按要求输出。七、小结thresholds.md虽仅四行却是 Mastra 打包技能中数据与行为分离设计的典型样本阈值数据放在references/行为规则放在SKILL.md二者由构建期代码生成层通过createSkill内联为模型可检索的技能资源。理解这条链路你就能在任意 Mastra 文件式 Agent 中构建数据参考 行为指令 工具取数三层解耦的领域技能——从灾害天气到合规审查、医疗指征、金融风控这套模式都可以直接复用。参考文件索引均位于当前仓库内阈值数据examples/agent/src/mastra/agents/weather-fs/skills/severe-weather/references/thresholds.md技能指令examples/agent/src/mastra/agents/weather-fs/skills/severe-weather/SKILL.md单位约定examples/agent/src/mastra/agents/weather-fs/skills/units.md文件式 Agent 布局说明examples/agent/src/mastra/agents/weather-fs/README.md技能工厂实现packages/core/src/skills/create-skill.ts文件式装配与内联说明packages/core/src/agent/fs-routing/index.ts【免费下载链接】mastraMastra is the modern TypeScript framework for AI-powered applications and agents.项目地址: https://gitcode.com/GitHub_Trending/ma/mastra创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
