Files

- 标准化 SKILL.md、资源模型、校验规则与安全限额

- 支持流式内容存储和单、多 Skill ZIP 双向编解码

2026-07-27 18:53:24 +08:00

3.5 KiB

Raw Blame History

Easy-Agents Skill

easy-agents-skill 提供标准 Agent Skills 包的领域模型、安全校验、通用资源存储，以及 ZIP 双向编解码能力。模块只负责 Skill 定义和包处理，不执行 scripts/，也不绑定具体智能体 Runtime。

标准包结构

Codec 支持根目录单 Skill、单目录 Skill 和多目录 Skill 三种输入布局。标准输出使用 name/SKILL.md，并保留以下可移植资源：

references/
scripts/
assets/
examples/
其他安全相对路径资源

SKILL.md 使用 YAML frontmatter 与 Markdown 正文。未知字段、嵌套 Map/List、布尔值和数字会保留；语义校验通过结构化 issue 返回路径、行列、错误码与修复建议。

推荐调用方式

无参 ZipSkillPackageCodec 使用实例级临时文件存储，适合一次性导入导出。它拥有临时目录，必须关闭：

try (ZipSkillPackageCodec codec = new ZipSkillPackageCodec()) {
    SkillPackageReadResult result = codec.decode(
            inputStream,
            SkillPackageReadOptions.defaults());
    SkillPackage skillPackage = result.getSkillPackage();
}

生产系统需要让二进制资源跨请求存活时，应注入持久化的 SkillContentStore。注入存储的生命周期由调用方负责，关闭 Codec 不会关闭外部存储：

ZipSkillPackageCodec codec = new ZipSkillPackageCodec(contentStore);
SkillPackageReadResult result = codec.decode(inputStream, readOptions);
codec.encode(result.getSkillPackage(), outputStream, writeOptions);

成功解码的二进制资源通过 contentRef 引用已提交内容。业务侧丢弃包或删除资源时，应按持久化策略调用 release；复制引用时调用 retain。REPORT_ONLY 模式会回滚暂存内容，只用于检查诊断，不应持久化其资源引用。

校验上下文

校验通过 SkillValidationMode 区分两个明确上下文：

DRAFT_IMPORT：ZIP 导入和兼容预检使用；历史下划线名称保留为 warning，允许先进入草稿修复。
STANDARD：正式新建、发布校验和标准 ZIP 导出使用；下划线名称等互操作问题作为 error。

SkillFactory.createStrict、SkillFactory.createWithResourcesStrict、DefaultSkillValidator.validate 与 ZipSkillPackageCodec.encode 执行 STANDARD 校验。为保持旧调用兼容，SkillFactory.create 仍可构建导入草稿，原有 validateReport(skill) 与 validateReport(skill, limits) 继续使用 DRAFT_IMPORT；新调用方需要显式上下文时使用三参数 validateReport。

安全边界

默认 Codec 对读写两端执行统一限制：

严格 UTF-8 文本和 ZIP entry 名称
Zip Slip、符号链接、路径大小写/Unicode 冲突与层级冲突防护
entry 数量、路径长度/深度、单文件、总解压大小、压缩包大小和压缩比限制
CRC、声明大小与实际流量复核
安全 YAML 构造、重复 key、alias、深度和 code point 限制
stage / commit / rollback，失败时清理暂存内容

限额通过 SkillPackageLimits 配置，并由 SkillPackageReadOptions、SkillPackageWriteOptions 传入单次操作。

从旧接口迁移

importZip(InputStream) 为兼容入口，现已废弃。新调用方应使用 decode，以获得：

包布局 SkillPackageLayout
标准化 SkillPackage
包哈希
聚合校验报告
STRICT 或 REPORT_ONLY 读取模式

写出统一使用 encode。自定义校验器是附加业务校验，不能替代 Codec 内置的标准安全校验。

3.5 KiB Raw Blame History Unescape Escape