80 lines
3.4 KiB
Markdown
80 lines
3.4 KiB
Markdown
# 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 返回路径、行列、错误码与修复建议。
|
||
|
||
模块内的可移植模型只有两层：
|
||
|
||
- `SkillDocument`：`SKILL.md` 原文、frontmatter 和 Markdown 正文
|
||
- `SkillResource`：除 `SKILL.md` 外的任意安全相对路径文件
|
||
|
||
Skill 的数据库主键、分类、权限、发布和审批属于上层技能库，不进入标准包模型。
|
||
|
||
## 推荐调用方式
|
||
|
||
无参 `ZipSkillPackageCodec` 使用实例级临时文件存储，适合一次性导入导出。它拥有临时目录，必须关闭：
|
||
|
||
```java
|
||
try (ZipSkillPackageCodec codec = new ZipSkillPackageCodec()) {
|
||
SkillPackageReadResult result = codec.decode(
|
||
inputStream,
|
||
SkillPackageReadOptions.defaults());
|
||
SkillPackage skillPackage = result.getSkillPackage();
|
||
}
|
||
```
|
||
|
||
生产系统需要让二进制资源跨请求存活时，应注入持久化的 `SkillContentStore`。注入存储的生命周期由调用方负责，关闭 Codec 不会关闭外部存储：
|
||
|
||
```java
|
||
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。
|
||
|
||
`DefaultSkillValidator.validate` 与 `ZipSkillPackageCodec.encode` 执行 `STANDARD` 校验。`SkillFactory.create` 构建草稿；需要指定校验上下文时调用三参数 `validateReport`。
|
||
|
||
## 安全边界
|
||
|
||
默认 Codec 对读写两端执行统一限制：
|
||
|
||
- 严格 UTF-8 文本和 ZIP entry 名称
|
||
- Zip Slip、符号链接、路径大小写/Unicode 冲突与层级冲突防护
|
||
- entry 数量、路径长度/深度、单文件、总解压大小、压缩包大小和压缩比限制
|
||
- CRC、声明大小与实际流量复核
|
||
- 安全 YAML 构造、重复 key、alias、深度和 code point 限制
|
||
- stage / commit / rollback，失败时清理暂存内容
|
||
|
||
限额通过 `SkillPackageLimits` 配置，并由 `SkillPackageReadOptions`、`SkillPackageWriteOptions` 传入单次操作。
|
||
|
||
## 编解码结果
|
||
|
||
`decode` 返回：
|
||
|
||
- 包布局 `SkillPackageLayout`
|
||
- 标准化 `SkillPackage`
|
||
- 包哈希
|
||
- 聚合校验报告
|
||
- `COMMIT_ON_VALID` 或 `REPORT_ONLY` 读取模式
|
||
|
||
写出统一使用 `encode`。Codec 始终执行内置标准与安全校验。
|