技能包（Skill Manager）

License 提示

基础功能（创建 / 编辑 / 列表）需要 skill.basic (STANDARD)；导入 / 导出需要 skill.import_export (PROFESSIONAL)；版本回滚需要 skill.version_history (PROFESSIONAL)。

技能包（Skill） 是一个版本化的 Markdown 剧本目录——每个技能由若干文件（SKILL.md + 脚本 + 参考资料）打包，挂到 DeepAgents 智能体的沙箱里，让 AI 像"读说明书 + 执行步骤"一样工作。

例：把"如何处理新员工入职"写成一个 Markdown 教程加几个 SQL 模板，技能包就完成了。Agent 加载它后会按文档照做，无需改代码、无需调 prompt。

数据模型

每个 Skill 是一个数据库行，包含：

字段	说明
name	英文标识（同组织内不重复，应用层校验）
display_name / description / category / tags	元数据
status	派生状态 草稿 / 已发布 / 未发布——由"草稿是否与线上一致"推导。有真正的发布闸 + 可选的组织级审批工作流（见下方安全扫描 / 审批门），不是自由设置
files	JSON 数组：[{path, content, type}]，线上已发布的文件；编辑写入 draft_config，发布时才落到这里
meta	YAML front-matter 解析结果（仅 ZIP 导入时填充）
version	当前版本号；发布时 +1 并写入历史快照（保存草稿不动它）

文件类型由后缀自动识别：markdown / code / binary / unknown。

当前限制

• 没有 DB-level 唯一约束：name 唯一性靠应用层检查，并发创建可能撞名
• 没有大小 / 数量上限：文件数、单文件字节数、Skill 总大小均不强制
• 没有跨组织共享：所有读取按 organization_id 过滤
• 没有 marketplace / 公共商店：所有路由都是组织内
• 没有 Skill 测试 / lint 工具：但发布前有内容安全扫描（默认关闭，可由组织开启）；保存只写草稿，发布才挂载到沙箱

在 Web UI 中使用

列表页 /skills

• 卡片式布局，筛选 = 搜索框（按 name 模糊匹配）+ 分类（横向 chips）；无状态下拉、无排序下拉
• 有未发布草稿的卡片显示「草稿」角标
• 操作：刷新、导入（接受 .md / .zip）、创建技能包
• 删除走软删除（deleted_at 标记）

创建 /skills/new

表单字段：

• name（必填，英文 slug）
• display_name（中文展示名）
• description、category（下拉：assistant / productivity / developer / custom）
• 内容：默认会预填一个 SKILL.md 模板，提供 Markdown 编辑器 + 实时预览

详情页 /skills/[id]

三栏布局：

┌─────────────┬──────────────────────────┬─────────────┐
│ FileBrowser │  Editor / Preview / Diff │  SkillMeta  │
│  256 px     │  flex                    │  256 px     │
└─────────────┴──────────────────────────┴─────────────┘

• 左：文件树。可新增、删除、单文件导入、单文件导出
• 中：可切换"编辑 / 预览 / 历史"标签。Markdown 自带格式工具栏；二进制 / 未知类型只读
• 右：元数据（name / display_name / category / tags / status）
• 自动保存（写草稿）：编辑停顿 2 秒触发保存（debounce），只写 draft_config，不生成版本快照、不挂载到沙箱
• 发布 / 提交审核：顶栏 ApprovalActionBar。点「发布」才把草稿推到线上（触发安全扫描并生成版本快照）；开启审批门时按钮变「提交审核」，审核中编辑器锁定（PUT / discard 返回 409）

版本历史

history 标签里：

• 列出所有版本（包含编辑者、时间、可选 comment）
• 任意两版本可视化 diff（客户端计算，无服务端 diff API）
• 回滚：点"还原"会以旧快照创建新版本（不覆盖、不删除中间历史）

回滚 API 受 skill.version_history 授权约束。

安全扫描 / 审批门

Skill 文件会被挂进沙箱当 AI 忠实执行的 runbook，因此在唯一的上线闸（publish） 上有一道内容级安全门。

• 内容安全扫描（默认关闭，组织级开关）：发布时检测提示注入 / 凭证窃取指令 / 危险 shell / 数据外传。命中阈值 → 拦截发布 + 返回结构化 findings（HTTP 422），修正后重新发布。
  • 开关与阈值：organizations.settings.skill_security_scan（block_on = critical|high|medium|low；fail_open 控制扫描器不可用时放行/拒绝）。
  • 草稿优先：所有写入只动 draft_config，扫描只在 publish 闸跑——编辑器 autosave / 对话挂载都零扫描开销，且线上挂载的 files 必然"发布时扫过"。
• 审批门（默认关闭，组织级 publish_approval）：开启后「发布」变「提交审核」，审批通过才真正上线；审核期间草稿锁定（PUT / discard 返回 409）。

zip 防御始终生效

zip-bomb / 路径遍历防御是独立的一道，在 ZIP 解析时始终生效，不受草稿 / 发布开关影响。

导入 / 导出

单文件 .md 导入

直接上传一个 Markdown，自动作为单文件 Skill（path: "SKILL.md"）。

.zip 导入

ZIP 包结构（约定俗成，未强制）：

my-skill/
├── SKILL.md        # 必需，文件名固定
├── scripts/
├── references/
└── assets/

• SKILL.md 必须存在，否则 400
• 顶级目录前缀（my-skill/）会自动剥离
• SKILL.md 的 YAML front-matter 提供 name / display_name / description / category / tags / status，会写入 Skill 的 meta 字段
• Skill 的 name：先取 front-matter name，否则取 ZIP 根目录名

URL 导入

POST /skills/import/url 支持从 HTTP(S) 拉取 .md 或 .zip。HTTP 请求超时 30 秒。

导出

任一 Skill 可下载 {skill.name}.zip，包含全部 files，按 path 写入，不加顶级前缀目录。

命令行工具（siracli）

siracli 提供完整的 Skill 命令组：

命令	用途
siracli skill list	分页列表，支持 --status / --category 过滤
siracli skill search <kw>	关键词搜索
siracli skill info <id>	查看详情 + 每个文件前 100 字符预览
siracli skill create -n <name> [-f <md_or_dir>]	从单个 .md 或目录递归创建（二进制文件 base64 编码）
siracli skill update <id> [-f <file>] [-s <status>]	更新元数据 / 单文件内容
siracli skill delete <id>	软删除（带确认）
siracli skill versions <id>	列出版本历史
siracli skill restore <id> <version>	回滚到指定版本（带确认）
siracli skill import-file <path>	.md / .zip 创建为新 Skill
siracli skill import-into <id> <path>	把 .zip/.md 合并进现有 Skill
siracli skill import-url <url>	URL 导入
siracli skill export <id> [-o <out>]	下载 ZIP
siracli skill install <id> -p claude|openclaw	下载并解压到本地 .claude/skills/（自动检测平台）

详见 siracli/README.md（仓库内）。

与智能体 / 编排器的连接关系

Skill 本身只是数据。真正生效需要挂到 DeepAgents 类型的执行流程。

主智能体挂载

在 DeepAgents 编排器 配置 deep_agents_config.skill_ids = [...]：

{
  "main_agent_id": "...",
  "skill_ids": ["skill-uuid-1", "skill-uuid-2"],
  "backend_config": { "type": "sandpod", "mode": "user_sandbox" }
}

执行时，所有指定 Skill 的文件会写入沙箱的 /skills/{skill.name}/ 目录。

SubAgent 挂载

在 Agent 表的 skill_ids 字段：

• 如果该 Agent 作为 DeepAgents SubAgent：Skill 写入 /skills/{subagent_name}/
• 如果作为 SINGLE 编排器的主 Agent：引擎会自动透明地切到 DeepAgents 执行器（参见 Single 模式说明），同样把 Skill 挂到沙箱

文件挂载机制

挂载逻辑由 deep_agents_executor 完成，按选择的 Backend 写入对应位置：

Backend	挂载根
filesystem	后端容器内虚拟 FS：/skills/{namespace}/
local_shell	同 filesystem
sandpod	沙箱内 {work_dir}/skills/{namespace}/，回退 /skills/{namespace}/

namespace 是主智能体或 SubAgent 的名字。文件按 skill.files[].path 原样写入。

使用建议

1. 从默认模板开始：UI 创建时自带的 SKILL.md 模板包含目标、输入、步骤、约束、示例几节，按它写就够用
2. 保持原子性：一个 Skill 只解决一类任务。"如何创建工单"和"如何关闭工单"分两个 Skill 比合在一起更易维护
3. 善用 SubAgent：复杂任务交给一个 SubAgent + 它自己的 Skill，主智能体只负责调度
4. 版本注释：保存时填 comment，回滚时方便定位
5. CLI 适合批量管理：把 Skill 定义放到本地 git 仓库，用 siracli skill import-file 同步，比 UI 编辑更可控