From ca4b9c4d85df4f0074419637aabc092490d3b67b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E8=82=96=E6=B3=BD=E6=B6=9B?= <ztxiao@ccitc.net.cn>
Date: Fri, 27 Feb 2026 17:21:33 +0800
Subject: [PATCH] docs(skills): clarify progressive dependency loading

---
 docs/latest/advanced/skills-management.md | 44 +++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/docs/latest/advanced/skills-management.md b/docs/latest/advanced/skills-management.md
index 71228eb6..64b58307 100644
--- a/docs/latest/advanced/skills-management.md
+++ b/docs/latest/advanced/skills-management.md
@@ -40,3 +40,47 @@ Skills 管理模块用于集中维护可供 Agent 只读引用的技能包。
 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` 是“激活后按需加载”的，不会在会话首轮全量注入。