Sira AI

主题

1.2 技能包(Skills) ​

技能包 = 一组 Markdown 文件,运行时挂到沙箱里供 AI 当"操作手册"查阅。这是把企业内部 SOP / 规范 / 知识"外挂"给 AI 的最直接方式。

进入路径:左侧主导航 → 技能包(/skills)。

⚠️ 生效条件:技能包只在以下两种路径下生效:

  • DeepAgents 编排器 — 主智能体的 deep_agents_config.skill_ids
  • 任意智能体被作为 DeepAgents 的 SubAgent 使用,且配了 agent.skill_ids
  • SINGLE 编排器 + 配了 skill_ids 的智能体(系统自动升级走 DeepAgents 路径)

普通 SINGLE / Supervisor / Collaboration / Workflow 等编排器,不会读取技能包。

1.2.1 技能包列表 [U] ​

截图:技能包列表

布局 ​

  • 顶部操作栏:刷新、管理分类(仅管理员可见)、导入、创建技能包
  • 筛选栏:搜索框 + 分类(横向 chips,「全部」在最前,点中即筛选,无状态下拉)
  • 主体:3 列卡片网格,每卡片显示:
    • 技能包显示名
    • 描述(最多 2 行)
    • 分类徽章
    • 版本号
    • 作者
    • 创建时间
    • 草稿角标:有未发布草稿的技能包,卡片右上角显示「草稿」角标
  • 分页器

主要操作 ​

操作行为
搜索按名称模糊匹配
分类 chips点中某个分类只看该类;点「全部」清空筛选
创建技能包跳转 /skills/new
导入弹文件选择器,接受 .zip 或 .md
卡片点击 / 编辑跳转 /skills/{id}
卡片删除二次确认 → 若被引用返回 409,弹冲突对话框
管理分类跳转 /admin/skill-categories(仅管理员)

删除冲突对话框 ​

截图:技能包删除冲突

如果某个技能包被智能体或编排器引用,首次删除返回 HTTP 409。对话框列出引用方,可选「强制删除」(引用方下次执行时会找不到该技能包并报错)。

1.2.2 创建技能包 [U] ​

路径:/skills/new

表单字段 ​

字段类型必填说明
nametext✓唯一标识符,组织内不重复,小写英文+下划线
displayNametextUI 显示名称,留空时用 name
descriptiontext简短描述
categoryselect分类(管理员维护,可见 技能分类管理)

Markdown 编辑器 ​

截图:技能包创建页

表单下方是一个 Markdown 编辑器,带「编辑」/「预览」两个 Tab。新建时会自动填充一个模板骨架,包含:

markdown
---
name: my_skill
description: 技能包简介
version: 1.0.0
---

# 技能名

## 用途
描述这个技能包解决什么问题。

## 触发场景
什么时候用这个技能包?

## 操作步骤
1. ...
2. ...

## 注意事项
- ...

YAML front-matter 会被后端解析到 skill.meta,可用于运行时元信息。

提交 ​

  1. 填好基本信息
  2. 编辑 Markdown 内容
  3. 点击「创建技能包」 → 成功后跳转到详情/编辑页

💡 创建只是写了一份草稿。要让 AI 真正用上,还需要在详情页点「发布」(详见 草稿与发布)。

1.2.3 技能包详情与编辑 [U] ​

路径:/skills/{id}

技能包不只是一个文件,而是一个多文件包(主 Markdown + 子文档 + 引用资源)。详情页提供完整的文件浏览器、编辑器、预览、版本历史。

页面布局 ​

截图:技能包详情编辑模式

顶部栏:

  • 返回按钮
  • 标题 + 状态徽章(草稿 / 已发布 / 未发布)
  • 模式切换:「编辑」/「预览」/「历史版本」
  • 「保存」按钮(只写草稿)
  • 「发布」/「提交审核」按钮(ApprovalActionBar):
    • 组织未开审批门时:按钮是「发布」,点击后做安全扫描并推到线上
    • 组织开了审批门时:按钮是「提交审核」,提交后变为「审核中」并出现「撤回」入口,编辑器锁定(PUT / 丢弃草稿都返回 409),审核通过才生效
  • 「导出」/「导入」按钮

编辑模式(默认) ​

三分屏:

左侧 — 文件浏览器:

  • 当前技能包包含的所有文件(支持多级目录)
  • 操作:点击切换文件、右键删除/重命名、底部「新建文件」按钮
  • 切换文件时自动保存当前文件

中间 — 编辑器:

  • Markdown 编辑器,语法高亮
  • 顶部显示「已保存 X 分钟前」或「有未保存修改」
  • 自动保存:停止输入 2 秒后触发(只写草稿)
  • 手动保存:Ctrl+S 或顶部保存按钮
  • 保存成功后 toast 提示:「草稿已保存 … 点 '发布' 才会推到线上 (发布时做安全扫描)」(审批门开启时文案变为「点 '提交审核'」)

右侧 — 元信息面板:

字段说明
display_nameUI 名称
description描述
category分类
tags标签(逗号分隔)
status草稿 / 已发布 / 未发布(派生状态,见 草稿与发布)

预览模式 ​

把当前编辑的文件渲染成 HTML,所见即所得。

历史版本模式 ​

截图:技能包版本历史

  • 「发布」时才创建版本快照(不是每次保存;保存只更新草稿)
  • 列表显示:版本号、时间、备注(可选)、操作人
  • 「恢复」按钮:把当前草稿回滚到该版本(再点发布才真正上线)
  • 「对比」按钮(如已实现):双栏 diff 视图

导入/导出 ​

操作行为
导出下载 .zip,包含技能包所有文件 + meta.json
导入(详情页)上传 .zip,合并到当前技能包(同名文件会覆盖,可在对话框选「跳过」/「覆盖」)
导入(列表页)上传 .zip 或单个 .md → 新建技能包

URL 导入(若启用) ​

部分部署支持从公开 URL 抓取 Markdown 文件作为技能包来源:

  • 列表页「导入」按钮 → 选择「从 URL」
  • 输入 URL → 抓取 → 自动创建技能包

1.2.4 草稿与发布 ​

技能包采用草稿优先模型:

  • 保存 = 写草稿。所有编辑(新建 / 改内容 / 导入 / 恢复版本)都只写入草稿,不会挂载到沙箱,线上正在被 AI 使用的内容不受影响。
  • 发布 = 推到线上。点顶栏的「发布」按钮,平台会先跑内容安全扫描,通过后才把草稿提升为线上版本,并创建一个版本快照。
  • 状态徽章由此派生:草稿(有未发布改动)/ 已发布(草稿与线上一致)/ 未发布(从未发布过)。

审批门(可选,组织级) ​

如果你的组织开启了发布审批(默认关闭):

  • 「发布」按钮文案变为「提交审核」
  • 提交后状态显示「审核中」,并出现「撤回」入口
  • 审核期间编辑器锁定:再次保存草稿 / 丢弃草稿都会返回 409
  • 审核通过 → 自动完成发布;被拒 → 草稿解锁,可改完重新提交

审批流程的完整说明见 发布审批。

1.2.5 内容安全扫描 ​

因为技能包文件会被挂进沙箱当作 AI 忠实执行的操作手册,平台在发布时会对待发布内容做一道内容级安全扫描,检测:

  • 提示注入(prompt injection)
  • 凭证窃取指令
  • 危险 shell 命令
  • 数据外传

命中阈值会拦截本次发布,并返回结构化 findings(HTTP 422)。你需要按提示修正内容后重新发布。

💡 这是组织级开关,默认关闭。老组织行为不变。开启与阈值(critical / high / medium / low)由管理员在「技能安全」设置里配置。

1.2.6 写好一个技能包的建议 ​

💡 这一节是经验沉淀,不是强制规范。

  1. 一个技能包只解决一类问题。不要在一个 skill 里混"客户回访话术"和"财务对账步骤"。
  2. 触发场景写得越具体越好。AI 是从 description + 文件首段判断要不要打开技能包,越精确召回越准。
  3. 每一步可执行。避免"沟通客户"这种抽象动作,改成"打开企业微信 → 找到客户 → 发送话术模板 X"。
  4. 示例 > 抽象。给 1~2 个完整 case 比写一堆理论更有效。
  5. 跨技能包引用:用相对路径 [相关技能](../another-skill/main.md) — 沙箱挂载时会把同组织所有技能包放在 /skills/ 下。
  6. 敏感信息不要写入。技能包会以明文挂到沙箱里,涉及密码/密钥的请用 MCP 工具或环境变量。

1.2.7 常见问题 ​

Q1:我创建了技能包,但 AI 完全没用上? ​

按可能性排序:

  1. 你的智能体是绑定在 SINGLE 编排器上,但智能体本身没配 skill_ids → 编辑智能体的 Step 6 把技能包加上
  2. 编排器类型不支持(Supervisor/Collaboration/Workflow/Conditional/External 都不会读技能包)
  3. DeepAgents 编排器,但技能包配在了智能体的 skill_ids 而不是编排器的 deep_agents_config.skill_ids — 这两个位置语义不同:前者是 SubAgent 才生效,后者是主智能体生效。

Q2:多次发布后版本太多怎么清理? ​

版本快照只在发布时创建(保存草稿不产生版本)。目前版本历史不支持手动清理,但单个技能包总版本数有上限(由部署方设置)。如果碰到上限,最早的版本会被自动归档。

Q3:导入的 ZIP 文件结构是什么样? ​

my-skill.zip
├── meta.json            # name, display_name, description, category, tags
├── main.md              # 主入口文件
├── subdoc-1.md          # 任意附属文档
└── resources/
    └── diagram.png      # 资源文件

最简形式:一个 .md 文件也可以,系统会自动包装成单文件技能包。

Q4:技能包怎么"发布上线"? ​

技能包是草稿优先的:编辑只写草稿,点顶栏「发布」才把草稿推到线上(发布时跑内容安全扫描,通过后创建版本快照)。

  • 如果组织开启了发布审批,按钮变为「提交审核」,审批员通过后才真正发布(见 发布审批)。
  • 跨组织共享仍走导出 ZIP → 对方导入的方式;暂无租户级技能市场。

Apache-2.0 Licensed

Copyright © 2024 Sira AI Inc.