技能管理机制

数据与文件

Skill 领域位于 ai/skill，核心实体包括：

• Skill：名称、描述、类型、来源、启用状态和版本。
• SkillFile：Skill 包中的文件。
• SkillVersion：可发布版本。
• SkillPackageChange：官方包或本地包的变更记录。

Skill 的正文通常以 SKILL.md 为入口，也可以附带 scripts、references 和 assets。数据库保存元数据和路径，文件内容由技能文件服务和官方仓库服务管理。

生命周期

1. 创建 Skill 时校验名称唯一性，默认来源为 CUSTOM、状态为 DRAFT。
2. 导入 Markdown 时先解析和验证 Skill 内容，再写入数据库和文件。
3. 官方 Skill 由 OfficialSkillRepositoryService 下载、校验、解压并记录版本。
4. 发布前确认包文件完整；官方 Skill 必须完成首次导入，状态为 PUBLISHED 才能启用。
5. Agent 房间通过 AgentRoomSkillRuntimeService 解析挂载配置，把启用的 Skill 提供给运行时。

接口入口

SkillController 的基础路径为 /v1/skill，覆盖分页、详情、按名称读取、创建、更新、删除、启用、禁用、Markdown/ZIP 导入导出和校验。官方仓库文件管理路径为 /v1/skill-repository，支持目录、上传、编辑、删除和下载。

运行时约束

• Skill 是否存在与 Skill 是否启用是两个判断。
• Skill 内容不应在每轮对话中重复拼接全部文件；应由运行时按需读取入口和引用文件。
• Skill 中的脚本和外部资源必须结合沙箱权限执行。
• 更新 Skill 版本后，需要检查已有 Agent 的挂载配置是否仍指向有效版本。