# 🧩 PRD: Agent Skill 接入与管理

> 状态: Draft
> 负责人: 待确认
> 更新时间: 2026-03-18

---

## 📌 1. 背景（Background）

- 当前现状：
  - 执行工厂当前已具备 `operator`、`toolbox`、`mcp` 等资源接入与管理能力，但缺少针对外部 Skill 的统一接入、管理和运行时读取能力。
  - 当前外部 Skill 若要在执行工厂中被使用，缺乏标准化的注册入口、统一元数据管理方式和受控文件访问机制。

- 存在问题：
  - 外部 Skill 接入路径不统一，导致 Skill 提供方和使用方难以通过标准方式完成接入与使用。
  - Skill 内容既包含 `SKILL.md` 指令正文，也包含内部附属文件，如果一次性加载全部内容，会造成上下文冗余和运行时读取成本过高。
  - Skill 生命周期管理缺少统一产品约束，容易出现“可注册但不可管理”“可删除但对象残留”这类不一致问题。
  - Skill 与后续权限体系、业务域体系、版本管理体系之间的边界尚未产品化定义，容易导致实现提前绑定错误约束。

- 触发原因 / 业务背景：
  - 执行工厂需要支持外部 Skill 作为独立能力包接入，以便统一服务于 Agent 执行链路。
  - 首版目标是先建立 Skill 的可接入、可管理、可按需读取能力，为后续权限治理、版本治理、自动绑定和运行沙箱扩展提供基础。
  - 该需求需要形成可评审、可联调、可验收的统一口径，供执行工厂平台研发、测试及相关模块对接人员协作落地。

---

## 🎯 2. 目标（Objectives）

- 业务目标：
  - 在首版中建立执行工厂对外部 Skill 的统一接入、管理与市场展示能力，支持 Skill 提供方、Agent 配置方和平台运行链路以标准方式完成接入、检索、读取、下载和删除。
  - 将 Skill 的内容读取方式从“一次性全量加载”收敛为“渐进式加载”，降低运行时不必要的上下文装载和文件读取开销。

- 产品目标：
  - Skill 注册成功率 ≥ 95%。
  - Skill 查询与读取成功率 ≥ 99%。
  - Skill 删除完成后对象存储残留率 ≤ 0.1%。
  - “列表匹配 -> 内容下载地址获取 -> 文件下载地址获取”渐进式加载链路平均响应时间目标：
    - 列表查询 P95 ≤ 300 ms
    - 内容下载地址获取 P95 ≤ 500 ms
    - 单文件读取 P95 ≤ 800 ms
  - 上述指标口径、采集方式与验收周期：待确认。

---

## 👤 3. 用户与场景（Users & Scenarios）

### 3.1 用户角色

| 角色 | 描述 |
|------|------|
| Skill 提供方 | 负责提供外部 Skill 包或 `SKILL.md` 内容，将 Skill 接入执行工厂。 |
| Agent/Agent 配置方 | 在 Agent 运行链路中选择、使用 Skill，并按需读取 `SKILL.md` 与内部文件。 |
| 平台运行链路 | 执行工厂内部运行时链路，负责在 Agent 执行过程中按需挂载、读取和校验 Skill 内容。 |

---

### 3.2 用户故事（User Story）

- 作为 Skill 提供方，我希望通过统一接口注册外部 Skill，从而让 Skill 能被执行工厂标准化接入。
- 作为 Agent 配置方，我希望先匹配候选 Skill，再按需获取 `SKILL.md` 和内部文件的下载地址，从而避免一次性加载过量内容。
- 作为平台运行链路，我希望 Skill 的读取和删除过程具备明确状态与访问约束，从而保证运行时一致性和安全性。

---

### 3.3 使用场景

- 场景1：Skill 提供方通过 zip 包上传一个外部 Skill，系统解析 `SKILL.md`、建立元数据和文件索引，完成 Skill 注册。
- 场景2：Agent 配置方通过列表接口筛选可用 Skill，确认目标 Skill 后，再调用内容接口获取 `SKILL.md` 下载地址。
- 场景3：运行时根据 `SKILL.md` 中的使用说明，进一步按需读取 Skill 内部参考文件、模板文件或脚本文件。
- 场景4：Skill 提供方或平台管理流程删除一个 Skill，系统先将 `f_is_deleted=1`，在当前请求内同步清理对象存储和索引，并由后台任务兜底继续补偿删除，整个过程中对外不可见。

---

## 📦 4. 需求范围（Scope）

### ✅ In Scope

- 支持外部 Skill 通过 zip 包注册到执行工厂。
- 支持外部 Skill 通过 `SKILL.md` 内容直接注册到执行工厂。
- 支持 Skill 的查询、详情查看、内容下载地址获取、文件下载地址获取、zip 下载和删除。
- 支持 Skill 元数据管理，包括名称、描述、版本、来源、扩展信息、依赖信息等。
- 支持 Skill 附属文件索引、存储和受控读取。
- 支持 Skill 市场接口，用于按市场视角提供 Skill 列表、详情展示和检索能力。
- 支持 Skill 对接统一权限体系与业务域体系。
- 支持 Skill “渐进式加载”能力：
  - 先通过列表接口匹配候选 Skill
  - 再按需读取 `SKILL.md`
  - 再按需访问 Skill 内部文件
- 支持通过 `f_is_deleted=1` 表示删除中/待补偿，并对外视为不可见。
- 首版同时提供 Skill 管理接口和 Skill 市场接口，两类接口需明确分层。

### ❌ Out of Scope

- Skill 编辑与在线修改。
  - 首版仅提供设计方案或后续实现规划，当前版本不支持在线编辑。
- Skill 版本对比与回滚。
  - 首版仅保留后续设计空间，本版本不支持。
- Agent 与 Skill 的自动推荐或自动绑定。
  - 首版仅保留思路或预研方向，本版本不支持。
- Skill 运行沙箱执行能力。
  - 首版仅完成 Skill 管理与运行时读取，不负责 Skill 沙箱执行。

---

## ⚙️ 5. 功能需求（Functional Requirements）

### 5.1 功能结构

    Skill 接入与管理
    ├── Skill 注册
    │   ├── zip 包注册
    │   └── SKILL.md 内容注册
    ├── Skill 管理
    │   ├── 列表查询
    │   ├── 详情查询
    │   ├── zip 下载
    │   └── 删除
    ├── Skill 市场
    │   ├── 市场列表
    │   ├── 市场详情
    │   └── 市场检索
    └── Skill 使用
        ├── 内容下载地址获取
        └── 内部文件下载地址获取

---

### 5.2 详细功能

#### 【FR-1】Skill 注册

**描述：**
系统支持外部 Skill 通过 zip 包或 `SKILL.md` 内容两种方式注册到执行工厂，并完成解析、元数据保存、文件索引建立及内容存储。


**用户价值：**
降低外部 Skill 接入门槛，形成统一接入标准，减少 Skill 提供方的接入成本。

**交互流程：**
1. 调用方提交注册请求，指定 `file_type` 为 `zip` 或 `content`。
2. 系统解析 `SKILL.md`，提取名称、描述、版本、扩展信息和依赖信息。
3. 若为 zip 包，系统建立附属文件索引并写入对象存储。
4. 系统创建 Skill 记录并返回注册结果。

**业务规则：**
- `SKILL.md` 必须包含 `name` 和 `description`。
- 支持 `zip` 与 `content` 两种注册入口。
- zip 注册时必须存在 `SKILL.md`。
- Skill 文件路径必须标准化，禁止路径穿越和非法路径。
- 注册前需通过统一权限体系校验创建权限，并完成 Skill 与业务域的资源绑定。

**边界条件：**
- 超大 zip 包、异常文件数或非法路径时，系统应拒绝注册。
- frontmatter 缺少关键字段时，系统应返回参数错误。

**异常处理：**
- 解析失败时返回明确错误信息，不创建 Skill 记录。
- 附件入库或对象存储写入失败时，注册整体失败并回滚。

---

#### 【FR-2】Skill 管理接口

**描述：**
系统支持 Skill 的注册后管理，包括列表查询、详情查询、zip 下载和删除，形成完整的 Skill 生命周期管理能力。

**用户价值：**
让 Skill 提供方和 Agent 使用链路能够统一查看和管理 Skill，降低接入、定位和排障成本。

**交互流程：**
1. 调用方通过列表接口查询候选 Skill。
2. 调用方通过详情接口查看 Skill 元数据。
3. 调用方可通过下载接口导出指定 Skill。
4. 调用方通过删除接口删除指定 Skill。

**业务规则：**
- 列表接口仅返回轻量摘要，不返回 `SKILL.md` 正文和文件清单。
- 详情接口仅返回元数据，不返回 `SKILL.md` 正文和文件清单。
- 管理接口面向资源维护，不等同于市场展示接口。
- 管理接口需接入统一权限体系，按资源操作类型校验访问、删除、下载等权限。
- 删除成功后，Skill 主记录、文件索引和对象存储内容应被清理。
- 删除过程中使用 `f_is_deleted=1` 作为中间补偿态，对外不可见。

**边界条件：**
- `f_is_deleted=1` 的 Skill 不允许重复作为可用 Skill 访问。
- 删除过程中若对象存储或索引清理失败，应保留补偿线索。

**异常处理：**
- 查询不存在 Skill 时返回未找到。
- 删除失败时保留补偿状态，避免误判为已清理完成。

---

#### 【FR-3】Skill 市场接口

**描述：**
系统支持从市场视角提供 Skill 列表、详情展示和检索能力，用于让 Agent 配置方或相关使用方发现可用 Skill。

**用户价值：**
让 Skill 使用方能够通过统一市场入口发现和选择 Skill，而不必直接使用资源管理接口。

**交互流程：**
1. 调用方通过市场列表接口获取可展示的 Skill 摘要。
2. 调用方通过市场检索能力按名称、标签、来源等条件筛选 Skill。
3. 调用方通过市场详情接口查看 Skill 的展示信息和基础元数据。

**业务规则：**
- 市场接口与管理接口必须区分开，避免职责混乱。
- 市场接口仅暴露用于发现和选择 Skill 的展示字段，不直接暴露管理侧重字段。
- `f_is_deleted=1` 的 Skill 不允许出现在市场接口结果中，且市场侧仅展示 `published`。
- 市场接口需接入统一权限体系与业务域体系，按公开可见性和业务域可见性过滤资源。

**边界条件：**
- 首版市场接口不包含上架/下架运营能力。
- 首版市场接口不包含推荐排序、评分、评论等市场化扩展能力。

**异常处理：**
- 不存在或不可见的 Skill 在市场详情中返回未找到。
- 过滤条件非法时返回参数错误。

---

#### 【FR-4】Skill zip 下载

**描述：**
系统支持将已注册的 Skill 按 zip 包形式导出，便于 Skill 分发、备份和跨环境流转。

**用户价值：**
让 Skill 提供方能够从执行工厂中完整取回已注册 Skill，形成“注册进入平台”和“从平台导出”的闭环。

**交互流程：**
1. 调用方指定 `skill_id` 发起下载请求。
2. 系统读取 Skill 元数据、`SKILL.md` 正文和已登记文件索引。
3. 系统按标准结构生成 zip 包。
4. 系统返回下载流或下载地址。

**业务规则：**
- 下载包必须包含 `SKILL.md`。
- 下载包应包含已登记且允许打包的内部文件。
- `f_is_deleted=1` 的 Skill 不允许下载。
- 下载能力属于 Skill 管理接口，不属于 Skill 市场接口。

**边界条件：**
- 索引存在但对象缺失时，不生成不完整下载包。
- 文件数量或包体积超出限制时，应拒绝下载并返回明确信息。

**异常处理：**
- Skill 不存在或状态不可下载时返回未找到或状态错误。
- 打包过程中若存在对象缺失或读取失败，返回下载失败并记录日志。

---

#### 【FR-5】Skill 渐进式加载

**描述：**
系统需提供符合 Skill 特性的渐进式读取链路，避免在列表或详情阶段一次性加载过量内容。

**用户价值：**
减少无效上下文装载，提升运行时读取效率，符合 Skill “先匹配、再深入”的使用方式。

**交互流程：**
1. 调用方通过列表接口匹配候选 Skill 或绑定的 Skill。
2. 选中目标 Skill 后，通过内容接口获取 `SKILL.md` 下载地址。
3. 根据 `SKILL.md` 内容判断是否需要读取内部文件。
4. 按需调用文件读取接口获取指定文件下载地址。

**业务规则：**
- `GET /skills` 不返回 `skill_content` 和 `files`。
- `GET /skills/{skill_id}` 不返回 `skill_content` 和 `files`。
- `GET /skills/{skill_id}/content` 返回 `SKILL.md` 下载地址和必要文件摘要。
- 文件读取接口返回下载地址，并且必须基于已登记索引定位对象。

**边界条件：**
- 未登记文件不允许读取。
- `f_is_deleted=1` 的 Skill 在整个渐进式加载链路中均视为不存在。

**异常处理：**
- 内容地址或文件地址获取失败时返回未找到、访问受限或地址生成失败等明确信息。

---

#### 【FR-6】Skill 内部文件访问控制

**描述：**
系统需对 Skill 内部文件下载地址获取进行访问边界控制，确保只有已登记、合法、允许读取的文件才能被访问。

**用户价值：**
降低非法路径访问、未登记文件读取和残留对象误读的风险。

**交互流程：**
1. 调用方发起文件读取请求并指定 `skill_id` 和 `rel_path`。
2. 系统查询 Skill 状态和文件索引。
3. 系统校验文件访问级别、存储内容和校验码。
4. 系统返回文件下载地址与元数据。

**业务规则：**
- 文件访问必须经过 Skill 存在性校验和索引登记校验。
- 文件路径必须使用标准化相对路径。
- 文件读取接口需接入统一权限体系，当前实现满足 `execute / public_access / view` 任一权限即可返回下载地址。

**边界条件：**
- 对象存储存在但索引不存在时，不允许返回下载地址。
- 索引存在但对象缺失时，应视为异常数据状态。

**异常处理：**
- 权限不允许时返回访问拒绝。
- 下载地址生成失败时返回读取失败。

---

## 🔄 6. 用户流程（User Flow）

    Skill 提供方 → 注册 Skill → Agent 配置方匹配 Skill → 获取 SKILL.md 下载地址 → 按需获取内部文件下载地址 → 下载或删除 Skill

---

## 🎨 7. 交互与体验（UX/UI）

### 7.1 页面 / 模块
- Skill 注册接口
- Skill 列表接口
- Skill 详情接口
- Skill zip 下载接口
- Skill 内容读取接口
- Skill 文件读取接口
- Skill 删除接口

### 7.2 交互规则
- 点击行为：首版主要为接口交互，不要求新增专门 UI 页面。
- 状态变化：接口需明确返回 `success / error / not_found / access_denied / deleting` 等可判断结果，其中删除中对外通过 `f_is_deleted=1` 按不可见处理。
- 提示文案：错误信息需可用于研发、测试和对接人员定位问题，例如 `SKILL.md not found`、`invalid skill file path`、`checksum mismatch`。

---

## 🚀 8. 非功能需求（Non-functional Requirements）

### 8.1 性能
- 列表查询 P95 ≤ 300 ms
- 内容下载地址获取 P95 ≤ 500 ms
- 单文件读取 P95 ≤ 800 ms

### 8.2 可用性
- Skill 查询与读取成功率 ≥ 99%
- 删除后对象残留率 ≤ 0.1%

### 8.3 安全
- 首版需具备基础访问控制，确保仅能读取已登记且允许访问的 Skill 文件。
- 禁止路径穿越、绝对路径访问和未登记文件读取。
- Skill 需按统一资源类型接入正式权限体系与业务域体系，不允许通过本地字段等值判断替代。

### 8.4 可观测性
- 支持 tracing
- 支持日志
- 支持指标监控
- 需能观测注册失败、删除补偿、文件读取失败和校验失败等关键事件

---

## 📊 9. 埋点与分析（Analytics）

| 事件 | 目的 |
|------|------|
| skill_register_submitted | 统计 Skill 注册请求量 |
| skill_register_succeeded | 统计 Skill 注册成功率 |
| skill_register_failed | 分析注册失败原因 |
| skill_list_queried | 统计 Skill 列表使用频率 |
| skill_content_read | 统计 `SKILL.md` 读取频率 |
| skill_file_read | 统计内部文件读取频率 |
| skill_delete_submitted | 统计 Skill 删除请求量 |
| skill_delete_failed | 分析删除补偿和对象残留问题 |

---

## ⚠️ 10. 风险与依赖（Risks & Dependencies）

### 风险
- Skill 内容与附属文件可能较大，若渐进式加载边界控制不严，会导致运行时一次性读取过量内容。
- Skill 删除链路涉及主表、文件索引和对象存储，若补偿机制不清晰，容易产生对象残留。
- 当前版本未接入正式权限体系和业务域授权，后续对接时可能需要调整访问校验逻辑。
- 当前版本不支持 Skill 编辑、版本对比与回滚，若后续需求快速扩展，可能引入新的数据模型调整。

### 依赖
- 外部系统：对象存储服务；待对接的权限体系；待对接的业务域体系
- 外部系统：对象存储服务；统一权限体系；业务域服务
- 内部服务：执行工厂平台；Skill 相关 DBAccess、Handler、运行时读取链路

---

## 📅 11. 发布计划（Release Plan）

| 阶段 | 时间 | 内容 |
|------|------|------|
| 需求评审 | 待确认 | 明确首版范围、边界与验收口径 |
| 开发 | 待确认 | 完成 Skill 注册、管理、渐进式加载、删除补偿能力 |
| 测试 | 待确认 | 完成接口联调、删除补偿验证、渐进式加载验证 |
| 发布 | 待确认 | 在测试环境验证通过后发布 |

---

## ✅ 12. 验收标准（Acceptance Criteria）

    Given 外部对接方准备了合法的 zip 包或 SKILL.md 内容
    When 调用 Skill 注册接口
    Then 系统成功创建 Skill 记录，并返回 Skill 基本信息

    Given 系统中存在多个 Skill
    When 调用 Skill 列表接口
    Then 返回轻量摘要，不包含 SKILL.md 正文和文件清单

    Given 调用方已确认目标 Skill
    When 调用 Skill 内容接口
    Then 返回该 Skill 的 SKILL.md 下载地址及必要文件摘要

    Given 调用方需要读取 Skill 内部文件
    When 调用文件读取接口且文件已登记、权限允许
    Then 返回正确的文件下载地址和文件元数据

    Given Skill 文件未登记或无读取权限
    When 调用文件读取接口
    Then 系统返回访问拒绝或未找到

    Given 调用方删除一个已存在的 Skill
    When 删除链路正常执行完成
    Then Skill 主记录、文件索引和对象存储内容均被清理，且对外不可见

    Given 删除过程中对象存储或索引清理失败
    When 删除请求返回失败
    Then Skill 保持 `f_is_deleted=1` 补偿标记，避免对外误判为删除完成

---

## 🔗 附录（Optional）

- 相关文档：
  - [Agent Skill 接入与管理设计方案](../../design/features/agent_skill_integration_design.md)
  - [Skill 公共接口文档](../../apis/api_public/skill.yaml)

- 参考资料：
  - 当前分支 Skill 相关实现代码
  - `feature/skill` 分支原型实现思路

- 待确认：
  - 量化指标的统计口径、采样周期和验收周期
- 正式权限体系与业务域体系的对接方案
  - 已部署旧环境的增量 migration 清理方案
  - 本文档阅读对象：执行工厂平台研发、测试及相关模块对接人员
