---
title: '技能包异步同步与沙箱一致性产品说明'
description: '说明智能体技能包同步慢、跨沙箱状态复用和技能文件边界不清时的产品影响、调整目标和验收口径。'
---

# 1. 方案定位

智能体技能包用于给智能体提供专项能力、操作说明和配套文件。

当一个会话启用技能后，系统需要把对应技能包准备到运行时沙箱中，让智能体可以读取 `SKILL.md`、脚本、配置和其他辅助文件。

本次调整面向的是技能包在沙箱中的准备过程。目标不是改变技能内容本身，也不是改变用户选择技能的方式，而是让技能在运行时具备更稳定的可用性：

- 启用技能后，智能体启动不应被大技能包长时间阻塞
- 智能体真正读取技能文件时，必须读到对应沙箱里的最新技能内容
- 不同工作区、项目或沙箱映射之间不能复用错误的同步状态
- 技能包只能同步自身目录内的常规文件和目录，遇到软链接会直接拒绝同步，不能把目录外内容带入沙箱

---

# 2. 问题背景

技能包同步位于用户发起任务和智能体开始执行之间。

当技能包文件较多、目录较深，或包含脚本和资源文件时，同步过程可能变慢。用户侧可能看到：

- 会话进入后等待时间变长
- 智能体开始响应前出现明显卡顿
- 安装或启用新技能后，首次使用体验不稳定

另一个问题来自沙箱状态复用。

不同项目、用户工作区或运行环境可能使用相同的沙箱后端标识，但它们对应的本地目录、挂载路径或工作区根目录并不相同。如果系统只按后端标识判断“技能已经同步过”，就可能出现：

- A 工作区同步完成后，B 工作区被误认为已经同步
- 智能体在 B 工作区读取技能文件时发现文件不存在
- 读到旧技能内容或错误工作区的技能内容
- 同一个技能在不同沙箱中的可用状态不一致

此外，技能包目录需要有清晰边界。技能包应该只代表用户安装或维护的那一组文件，不应通过软链接把其他位置的文件带入运行时沙箱。

---

# 3. 产品目标

本次调整后，技能包同步需要满足以下产品目标。

## 3.1 降低会话启动等待

技能包准备过程不应默认阻塞整个智能体启动流程。

当技能已经被选中，系统可以先把同步任务排入后台，让智能体尽快拿到技能摘要和任务上下文。

只有当智能体需要读取某个技能文件时，才需要确认这个技能对应的同步已经完成。

## 3.2 保证技能读取一致性

异步同步不能牺牲正确性。

智能体读取技能文件时，如果对应技能仍在同步中，系统必须等待这次同步完成，再返回文件内容。

这样可以同时保证：

- 不因同步慢而拖慢所有模型调用
- 不在文件未准备好时返回失败或旧内容
- 不让智能体基于不完整技能包继续执行

## 3.3 隔离不同沙箱和工作区

技能同步状态必须和具体沙箱、工作区映射绑定。

即使两个运行环境看起来使用同一个后端标识，只要它们的工作区目录、挂载路径或映射根目录不同，也应该视为不同同步范围。

这可以避免跨工作区、跨项目、跨用户会话之间误复用同步状态。

## 3.4 明确技能包文件边界

技能包同步只接受技能包目录内的常规文件和子目录。

如果技能包中存在软链接，系统应直接拒绝同步该技能包，不展开或复制软链接目标。

这可以保证技能运行时文件来源清晰，也便于后续审计和排查。

---

# 4. 用户可见流程

## 4.1 用户进入启用技能的会话

用户进入启用技能的智能体会话后，系统会加载技能摘要，并安排技能包进入运行时沙箱。

用户不需要手动触发同步，也不需要理解同步过程。

如果技能包较大，会话启动可以先继续进行，减少启动等待。

## 4.2 智能体读取技能说明

当智能体判断某个技能适用于当前任务时，会读取该技能的完整说明文件。

如果该技能包仍在同步中，读取动作会等待对应同步完成。

用户侧看到的结果应该是：

- 智能体能正常读取技能说明
- 不会因为后台同步尚未完成而读到空文件或缺失文件
- 等待只发生在确实需要读取该技能文件时

## 4.3 用户安装或启用新技能

用户安装新技能后，新技能会加入当前会话可用技能列表。

系统会为新技能安排同步，但不会让安装动作无意义地等待全部文件复制完成。

当智能体随后读取这个新技能时，系统会确保读取前该技能已经准备好。

## 4.4 切换项目、工作区或沙箱

当用户切换到不同项目、不同工作区或不同沙箱映射时，技能同步状态不会错误复用上一个环境的结果。

即使技能名称和版本相同，只要运行环境不同，系统也需要确认当前环境中已经具备对应技能文件。

这样可以避免“在一个项目可用，在另一个项目缺文件”的不一致体验。

---

# 5. 行为边界

## 5.1 异步不等于跳过同步

异步同步只改变等待时机，不改变同步要求。

技能被启用后仍然需要准备到运行时沙箱。

智能体读取技能文件前，仍然需要确保对应技能同步完成。

## 5.2 相同环境和相同版本可以跳过重复同步

如果同一个沙箱环境中，某个技能目录已经同步过相同版本，系统可以跳过重复同步。

这个跳过只在同一个沙箱和同一个工作区映射内成立。

不同工作区、不同挂载路径或不同沙箱范围不共享这个结果。

## 5.3 技能包不支持软链接同步

技能包目录中如果存在软链接，系统会拒绝同步该技能包，不会把软链接本身或其目标内容同步进运行时沙箱。

从产品口径看，技能包应该把所需文件明确放在自身目录内。

如果技能确实依赖某个辅助文件，该文件应该作为技能包内容的一部分管理，而不是通过软链接间接引用。

## 5.4 同步失败时不伪装成可用

如果技能包无法同步，系统不应该把该技能伪装成已经准备好。

智能体读取相关技能文件时，应能得到明确失败结果，便于用户或运维定位问题。

---

# 6. 用户价值

## 6.1 启动体验更快

大技能包不再默认拖慢所有模型调用。

用户进入会话后，智能体可以更快开始理解任务和输出响应。

## 6.2 技能使用更稳定

智能体真正使用技能时，会等待对应技能准备完成。

这减少了“技能列表里看得到，但读取文件失败”的体验断层。

## 6.3 多工作区体验更一致

不同项目、工作区和沙箱之间的技能状态互不污染。

用户在多个项目间切换时，不会因为后台缓存复用而看到错误的技能文件状态。

## 6.4 文件边界更清晰

技能包只同步自身目录内的内容。

这降低了意外带入外部文件的风险，也让技能包内容更容易理解、迁移和审计。

---

# 7. 风险与回归点

后续评审和回归时，可以重点检查以下场景：

- 启用多个技能后，会话启动不应被所有技能包同步完全阻塞
- 智能体读取刚安装的技能时，应等待对应技能准备完成
- 同一个技能在不同项目或不同工作区中，不应误用另一个环境的同步结果
- 技能版本变化后，系统应重新准备对应技能内容
- 同一个沙箱中相同版本技能重复使用时，可以跳过重复同步
- 技能包包含子目录和脚本时，应整体可用
- 空目录技能包不应导致同步失败
- 技能包包含软链接时，应明确拒绝同步，不应把软链接目标内容同步进沙箱
- 同步失败时，读取技能文件应给出明确失败，而不是返回旧内容

---

# 8. 验收口径

本方案可以按以下口径验收：

- 大技能包不会让所有会话启动都长时间等待
- 技能文件被读取前，相关技能包已经在当前沙箱准备完成
- 不同工作区和不同沙箱映射之间不会共享错误同步状态
- 同一环境、同一版本的技能包可以避免重复同步
- 技能包目录边界明确，遇到软链接会明确失败，不同步目录外文件
- 用户安装或启用技能后，智能体可以稳定读取该技能说明和辅助文件
- 多项目、多工作区场景下，技能可用性与当前上下文一致
