ForcePilot/docs/latest/advanced/skills-management.md

Skills 管理

Skills 管理模块用于集中维护可供 Agent 只读引用的技能包。
本期采用“文件系统存内容，数据库存索引”模式：

1. 技能目录存储在 /app/saves/skills（本地 save_dir/skills）。
2. 技能元数据（slug/name/description/dir_path）存储在 skills 表。
3. Agent 配置通过 context.skills 选择技能，运行时挂载到 /skills 且只读。

权限与入口

1. 系统设置中新增 Skills 管理 页签（仅 superadmin 可见）。
2. admin 仅可调用列表接口（用于 Agent 配置选择 skills）。
3. user 无 skills 管理权限。

导入规范（ZIP）

1. 单包单技能，且必须包含一个 SKILL.md。
2. SKILL.md 必须包含 frontmatter，且 name、description 必填。
3. name 需满足 slug 规则：小写字母/数字/短横线。
4. 导入时执行路径安全校验，拒绝绝对路径与 .. 路径穿越。
5. slug 冲突时自动追加 -v2/-v3...，并自动改写 SKILL.md 中 name 为最终 slug。
6. 导入采用临时目录 + 原子替换，避免半成品落盘。

在线管理能力

1. Skills 列表：来自数据库，避免全量目录扫描。
2. 目录树：按原生目录结构展示。
3. 文件级 CRUD：支持新建文件/目录、编辑文本文件、删除文件/目录。
4. 文件编辑仅允许文本类型（如 md/py/js/ts/json/yaml/toml/txt 等）。
5. SKILL.md 保存后会重新解析，并同步更新数据库中的 name/description。
6. 支持导出单个 skill 为 ZIP。
7. 删除 skill 时会同时删除目录与数据库记录（硬删除）。

Agent 运行时行为

1. context.skills 用于配置技能 slug 列表。
2. 运行时按会话构建 SkillResolver 快照（同一会话首次构建，后续复用）。
3. 运行时仅暴露快照中的可见 skills 到 /skills/<slug>/...。
4. /skills 路径只读，不允许写入、编辑、上传。
5. 同会话内若 context.skills 变化会触发快照重建。
6. 后台修改 skills 内容后，已有会话不会自动刷新，需新会话或调整 context.skills 才生效。

依赖类型说明

每个 skill 支持三类依赖，均在 Skills 管理页维护：

1. tool_dependencies：该 skill 需要的内置工具名列表。
2. mcp_dependencies：该 skill 需要的 MCP 服务器名列表。
3. skill_dependencies：该 skill 依赖的其他 skill slug 列表。

约束与语义：

1. 依赖在保存时做合法性校验，不允许引用不存在的工具/MCP/skill。
2. skill_dependencies 不允许包含自身。
3. skill_dependencies 按递归闭包生效，自动去重、去环、保序。

渐进式加载流程

系统不会在会话开始时一次性加载全部依赖，而是按阶段渐进加载：

阶段 1：会话启动前（构建 skill 可见集）

1. 读取 context.skills 作为用户显式选择的 skills（selected）。
2. SkillResolver 递归展开 skill_dependencies，得到 visible_skills（selected + 依赖闭包）。
3. 把快照写入 runtime.context.skill_session_snapshot。
4. 基于 visible_skills 构建 skills prompt 段，并在 abefore_agent 预拼接到 system_prompt。
5. /skills 只挂载 visible_skills，所以被依赖 skill 从会话首轮起即可被读取。

结论：skill_dependencies 是“会话启动即生效”的。

阶段 2：技能激活时（按需激活）

1. Agent 通过 read_file 读取 /skills/<slug>/SKILL.md 时，视为激活该 skill。
2. 仅当 <slug> 在 skill_session_snapshot.visible_skills 内，激活才被接受。
3. 激活结果写入 activated_skills（去重保序）。

结论：只有“真正被读取并使用”的 skill 才会进入后续依赖注入计算。

阶段 3：后续模型轮次（注入工具与 MCP 依赖）

1. 在 awrap_model_call 中，基于 activated_skills 计算依赖闭包。
2. 聚合闭包内 skill 的 tool_dependencies 与 mcp_dependencies。
3. 仅把这些依赖工具/MCP 合并进本轮可用工具集。

结论：tool_dependencies 与 mcp_dependencies 是“激活后按需加载”的，不会在会话首轮全量注入。