技能 Skills

技能是 LoopAgent 专属的能力：一份让模型「读」而不是「调」的说明书（SOP）。它由一份 SKILL.md 正文，加可选的参考文件、脚本组成。模型在需要时把正文读进来，照着里面的步骤办事。

技能是什么、怎么被用

• 一个技能包 = 必需的 SKILL.md + 可选的文本文件、脚本。整包不超过 20MB、单文件不超过 5MB。
• 系统每轮只给模型一份「可用技能清单」，只有名字和简介，不含正文。模型判断某个技能相关后，才把它的完整 SKILL.md 正文读进来。
• 技能包里的文件只能通过技能机制读取，不在任何本地文件系统里（详见下文沙箱说明）。
• 一个 LoopAgent 最多挂载 10 个技能。

三种来源

「移除」的含义按来源不同：组织 / 平台技能点「移除」= 只解绑，技能本体还在；Agent 私有技能点删除 = 连本体一起删。要彻底删除组织技能本体，需去「工具 › 技能」页操作。

草稿、Debug 与 Production

技能正文（SKILL.md）的生效过程和身份提示一样分三态。要注意：技能编辑器只有「保存」按钮、没有「发布」按钮——发布动作在别处。

上线方式按技能来源分两种：

• Agent 私有技能：正文随 LoopAgent 发布。编辑器点保存只对调试版生效，必须再发布这个 LoopAgent，最后保存的版本才带上线（与身份提示同逻辑）。
• 组织 / 平台技能：正文即时全局。点保存后，对所有引用它的智能体（调试版 + 线上）立即生效，无需发布智能体。

最常见的坑：编辑中的草稿连调试聊天都读不到。想在调试聊天里验证改动，必须先点「保存」，否则读到的还是上次保存的正文。

另一个坑：Agent 私有技能只点保存也只到调试版，客户看到的仍是发布版——要上线记得回去发布 LoopAgent。

两个补充：

• 新建即可读：新建技能时会自动写入最小正文（表单新建 = 名称 + 简介合成，带包上传 = 读包里的 SKILL.md），所以首次发布之前就能被模型读到。
• 多人编辑冲突：多人或多标签页同时改同一个技能，保存时可能提示「技能内容已被他人更新」，刷新重新加载后再保存即可。

Python 脚本与执行沙箱

技能包里可以带 Python 脚本（放在 scripts/ 目录只是惯例、不强制），把需要精确计算、格式转换、调用特定库的步骤写成代码，交给模型按需运行。

执行机制：

• 脚本在隔离沙箱里运行（独立的 Linux 环境 + Python 3.11），不在你的服务器、也不在模型本地跑——天然隔离、互不影响。
• 模型在需要时把包内脚本丢进沙箱执行、拿回结果；技能包里的文件也只能经技能机制读取，不能用 bash 去 cat / find（技能包不在本地文件系统里）。

编辑器里的「运行测试」= 真实沙箱执行：

• 在技能编辑器里对 .py 脚本点「运行测试」，是真实的后端沙箱执行，不是前端模拟；它和模型运行时用的是同一个沙箱——编辑器里测通了，模型运行时也能跑通。
• 脚本自身报错 ≠ 接口失败：脚本内部抛错时，会带着输出和错误堆栈正常返回（方便排查），并不代表执行接口挂了；只有沙箱层出问题（如该环境未部署沙箱）才是接口失败。
• 测试时渠道 / 会话变量取不到：编辑期没有真实对话上下文，渠道属性（如 WhatsApp / Telegram 相关）、会话属性会是空值，只有真实对话运行时才有值。所以测试里这些变量为空是正常的。

bash 工具：每个 LoopAgent 都会带一个 bash 工具，用来驱动技能文档里描述的 API 调用（按 SKILL.md 的说明拼命令）；但技能包内的 Python 脚本走沙箱执行，不是 bash。

技能不生效怎么排查

技能要被模型读到，需要逐层过关，按顺序自查：

1. 技能模块总开关是否打开；
2. 该技能的挂载条目是否启用；
3. 技能本身是否启用；
4. 技能正文是否非空（空正文会被丢弃，模型读不到）；
5. 是否与另一个技能同名（技能名区分大小写，同名只保留先挂载的那个）。

改技能挂载开关后，下一条消息就会在可用技能清单里出现 / 消失，不需要重新保存智能体。