技能安装与调用
概述
技能（Skill） 用于扩展 MaiPlat Agent 的可执行能力与领域知识。本平台提供集中的技能管理界面，并在 权限隔离、依赖安装 与 启用策略 上做统一管控，以降低「任意扩展脚本」带来的稳定性与安全风险。
本节说明技能的可见范围与分级、上传与安装流程、调用方式，以及技能包内 SKILL.md 的 YAML frontmatter 编写规范。
权限分级与可见范围
相较传统 Agent「单一技能列表」的模式，本平台将技能按组织维度划分为四级，用于控制「谁能看见、谁能使用」：
| 级别 | 可见范围 |
|---|---|
| 用户技能 | 仅创建该技能的用户本人可见。 |
| 部门技能 | 同一部门成员可见。 |
| 公司技能 | 全组织成员可见。 |
| 内置技能 | 平台官方内置，全组织可见（内容与更新节奏由平台维护）。 |
安全与稳定性策略
为兼顾自动化与安全边界，技能模块强调以下几点（具体策略以当前版本为准）：
- 禁止 Agent 自行安装技能包依赖：依赖安装通过平台提供的校验与安装入口完成，避免对话过程中静默改写运行环境。
- 一键依赖检查与安装：界面提供依赖检测与安装能力，直观展示技能是否可用，降低脚本型技能的运维成本。
- 依赖按技能隔离：同一环境中的不同技能依赖相互隔离，降低包版本冲突概率。
界面入口与列表
技能管理以页面 右侧抽屉 形式呈现，与 定时任务 等区域并列入口（参见 基础对话与交互 中的侧栏说明）。
上传、检测与安装
上传方式与包类型
您可将技能包（通常为 .zip）通过 拖拽 上传至指定区域。上传后平台会自动检测技能包结构与类型，常见包括：
| 类型 | 说明 |
|---|---|
| 说明类技能 | 无脚本，以 Markdown 等内容为主，用于指引 Agent 的行为或领域知识。 |
| Python 技能 | 包含 Python 脚本；可按引导配置 requirements.txt 等依赖。 |
| Node 技能 | 包含 JavaScript 脚本；可按引导配置 package.json 等依赖。 |
依赖安装与启用开关
- 安装：检测通过后，可使用界面提供的 安装 操作触发依赖的自动化安装流程（具体步骤与日志展示以产品为准）。
- 启用：每个技能可通过 开关 单独启用或停用。MaiPlat 与每个AIAI AI AI 数字员工各有一套开关——同一技能可对 MaiPlat 开启、对某AIAI AI AI 数字员工关闭（详见 AIAI AI AI 数字员工）。
调用方式
技能完成安装后，默认启用。在与 MaiPlat Agent 的对话中：
- 由 Agent 自行选用：Agent 可根据当前任务与技能描述，在授权范围内决定是否调用某项技能。
- 由您显式指定：可在对话中说明要用的技能；或输入
@从列表选择当前对话对象已启用的技能（参见 基础对话与交互）。
实际路由与工具暴露策略受模型能力、平台策略与权限配置共同影响。
技能创建与规范优化（内置能力）
平台内置官方技能 技能工厂，提供面向技能的辅助能力，典型包括：
- 技能创建：您可通过 自然语言 描述需求，由 Agent 协助生成符合场景的技能骨架与说明，便于快速沉淀个人或团队的可复用能力。
- 技能规范优化：业界 Skill 写法多样，不利于共享与复用。MaiPlat 对技能
SKILL.md采用统一的 frontmatter 约定（见下文），用于指导 Agent 选型与依赖安装。若您从外部来源（如 Skill Hub、Claw Hub 等）获得技能包，可将相关材料提供给 Agent，由其协助改写为符合本平台校验规则的SKILL.md。
外部技能的脚本路径、入口约定可能与平台不一致；建议在改写后在本环境中做一次 上传检测 → 依赖安装 → 小规模试用，确认行为符合预期后再扩大启用范围。
SKILL.md 元数据（YAML frontmatter）
技能包内的 SKILL.md 若在正文 最上方 使用 YAML 描述元数据，须放置在 一对 --- 分隔符之间。下列字段为平台识别的关键要素（与创建技能时配置的 JSON 元数据语义对齐）。
字段一览
| 字段 | 是否必填 | 含义 |
|---|---|---|
name | 必填 | 技能名称（展示与检索用）。请勿使用外部格式中的 display_name 等别名字段；统一写入 name。 |
description | 必填 | 一句话说明技能用途，便于检索与 Agent 选型。 |
version | 选填 | 版本号，例如 1.0.0。 |
author | 选填 | 作者或团队标识。 |
tags | 选填 | 字符串标签列表，用于分类与检索。 |
requires | 选填 | 运行前提，通常通过子字段声明依赖文件名或环境约束（仅可使用下文列出的子键，勿自定义任意键名）。 |
requires 允许的子字段
以下子字段均为 选填，按脚本类型与实际环境按需填写：
| 子字段 | 含义 |
|---|---|
python | Python 依赖清单路径，通常为 requirements.txt（脚本型 Python 技能需要）。 |
node | Node 依赖说明，对应包内 package.json（脚本型 Node 技能需要）。 |
os / bins / any_bins / env | 操作系统、命令行工具、任选工具、环境变量等约束，按实际需要填写。 |
完整示例（按需改写）
纯说明型技能（无脚本）：
---
name: Excel 分析指导
description: 指导如何根据用户上传的 Excel 分析问题并给出分析步骤与代码思路
version: 1.0.0
author: 你的名字
tags:
- 办公
- 数据分析
---
# Excel 分析指导
（以下为正文 Markdown……）
带 Python 脚本且需安装依赖：
---
name: Excel 问答分析器
description: 上传 Excel 后用自然语言提问，自动生成分析结果
version: 1.0.0
tags:
- 办公
- Excel
requires:
python: requirements.txt
---
# Excel 问答分析器
（以下为正文 Markdown……）
必填字段仅为 name 与 description。 脚本型技能请按需补充 requires.python 或 requires.node。请勿在 frontmatter 中写入平台未支持的字段（例如 eligible、platform、allowed-tools、model 等），否则可能导致校验失败、无法安装或产生不可预期的解析行为。
小结
技能安装与调用 的核心脉络是：四级权限 控制可见范围；通过 抽屉界面 完成上传、检测、依赖安装与 启用开关 管理；对话中可由 Agent 自主选用 或由 您明确指定。编写 SKILL.md 时，请严格遵循 requires 子键白名单，避免混入平台不识别的元数据字段。