一、上岗三步

• 发现：仓库里找得到这个包吗？——找不到就免谈。
• 装载：依赖齐不齐、声明合不合法？——不过关则装载失败。
• 启动：运行条件给了吗（上下文、配置、权限）？——不过关就挂着但不干活。

三步各自可能失败，失败的原因和处置完全不同——混在一起排查就是灾难。

二、实测：挂着但不干活的样子

tool-plugin-manager 在配置里这样写：

disabled: !!js '!ctx.get('profileContext')'

包一直在仓库里（发现没问题），装载也正常——但只要没有会话上下文，它就不具备运行条件。

这不是故障，是设计：条件不满足就安静待命，条件满足自动上岗。

三、为什么要把三步分开

• 排查时：【找不到包】查仓库与网络；【装载失败】查依赖与声明；【挂着不干】查上下文与条件——三把钥匙开三把锁。
• 设计时：发现层不用懂依赖，装载层不用懂权限——每层只管自己那步。
• 实验时：4.1.2 停掉的是【启动】这一层——包还在、装载还在，能力没了。

四、对写插件的人意味着什么

• 装不上时先分清卡在哪一步：报错的措辞就是路标。
• 别在实现里偷偷做【发现】——包该不该在场是系统的事。
• 运行条件尽量声明而不是硬编码判断——让系统的挂载机制替你管。

五、动手 Demo：被发现，不等于已经具备运行条件

上岗三步与各自的失败方式：

steps = [
    ("发现", "包在不在", "仓库/网络问题"),
    ("装载", "依赖齐不齐", "依赖/声明问题"),
    ("启动", "条件给没给", "上下文/权限问题"),
]
for a, b, c in steps:
    print("  %-4s %-12s 失败原因: %s" % (a, b, c))
print()
print("  例: tool-plugin-manager 包一直在, 无会话上下文就不挂")

实跑输出：

--------------------------------------------------------------------
被发现，不等于已经具备运行条件
--------------------------------------------------------------------
  从【有个包】到【它真的在跑】，中间隔着三步：

  步骤     问的问题                           不过关会怎样
  -----------------------------------------------------------
  发现     包在不在（仓库里找得到吗）         后面免谈
  装载     依赖齐不齐、声明合不合法           装载失败，警告
  启动     运行条件给了吗（上下文、配置）     挂着但不干活
  -----------------------------------------------------------

  实测证据——`tool-plugin-manager` 在配置里是这样写的：

        - id: tool-plugin-manager
          name: '@deepseek-ai/dsh-plugin-manager/tools'
          disabled: !!js '!ctx.get(''profileContext'')'

  包一直在仓库里（发现没问题），但没有会话上下文就不挂——
  **发现和运行条件是两码事**。

三把钥匙开三把锁——排查时先分清卡在哪一步，别一上来翻代码。 【挂着但不干活】不是故障是设计——条件满足自动上岗。 4.1.2 的实验停的就是【启动】层——包与装载都在。

30 秒实验

1. 在配置树里再找一个带条件的 disabled，说出它的运行条件是什么。
2. 回忆一次【装不上】的经历，判断它卡在三步中的哪一步。
3. 说说为什么【发现层不用懂依赖】是好设计。

常见误区

1. 错误：包在仓库里就等于能力可用。——纠正：中间还有装载与启动两步——依赖、上下文、权限都可能拦住它。
2. 错误：挂着但不干活是 bug。——纠正：是设计——条件不满足就待命，条件满足自动上岗。
3. 错误：排查装不上要通读插件源码。——纠正：先分步——发现查仓库、装载查依赖、启动查条件。

• ☐ 下一节（5.5.1 Fiber：记录插件实例的一段生命周期）

相关笔记

• 动手实验：删除 Skill，观察能力是否还在 —— 停的就是启动层
• 注册也有生命周期 —— 注册期是三步里的装载
• Spatial Composability：当能力环境变化时，插件还能不能运行 —— 运行条件的空间面
• 🐳 DeepSeek Harness · 索引