README.zh.md 7.0 KB
description: "当前 Cordis Loader 插件状态的只读投影，并附带每个 Agent 预设的组合：面向 web GUI 宿主客户端的 pluginInventory 服务及其 pluginInventory/list Remote。"
kind: "package-reference"
@deepseek-ai/dsh-host-plugin-inventory
English | 中文
概述
客户端可以调用 pluginInventory/list，按加载顺序展示宿主的当前插件，包括每个条目的标识符、模块标识、有效启用状态与存活阶段。部署组合了 Agent 预设 roster 时，还会报告各预设的元数据、健康状态与压平后的插件组合；没有 roster 时，预设数据缺席。每次响应都是供展示和诊断使用的只读即时快照：它不能修改插件，也不提供历史、来源信息或变更订阅。
目录
使用本包
当客户端或设置页需要展示宿主当前组合了什么——哪些插件已加载、已启用、是否存活，以及每个 Agent 预设会给会话什么——时调用 pluginInventory/list。Remote 是唯一入口：该服务仅供 Remote 使用，刻意不声明同进程 Cordis Context merge。
快照包含什么
每一行是一个非组 Loader 条目：其条目 id、精确模块标识、有效启用状态（含被禁用的祖先组）与当前根 Fiber 阶段。pending 表示条目等待加载，loading 表示正在读取，active 表示正在运行，failed 表示其 fiber 被拒绝，unloading 表示正在拆除；null 表示完全不存在存活的根 Fiber。结构性的 group 行会被跳过。
当树由 profile launcher 组合时，每一行还会说明是谁提供的：trust 对安装自带组合包的行是 builtin，对用户安装的组合包的行是 external，对用户自己的补丁文件插入却被组合排除的行是 user；package 给出该组合包的名称与版本，对外部行还给出组合包自己的 patch 在 launcher 加前缀之前声明的 id；停用的行带 disabledBy——用户 patch 文件用字面量 disabled: true 停用它、或停用了持有它的组的是 user，组合包自己的门或墓碑是 composition。被隔离的外部组合包启动失败的行已经不在树里；它仍从 launcher 的失败注册表列出，fiberPhase 为 'failed'，并带一个说明阶段与消息的 failure。没有 launcher 时每一行都读作 builtin，也没有 package 或 failure。
每个预设的组合
组合了 roster 时，agentPresets 按 roster 顺序携带每个预设一组：其 id、随部署内置还是用户自建（trust，客户端据此本地化内置预设名）、发布的显示名、未指名预设的会话是否组合它，以及压平后的插件行——条目 id（文件行未声明时为 null）、模块标识、有效启用状态、行自带的 !!js disabled 表达式（如有）、组合存活时的根 Fiber 阶段、该行来自预设的组合文件还是其用户补丁层（source），以及被关掉的行是组合还是补丁层关掉的（disabledBy）。已有会话组合过的预设由其最新 standing 世代作答——即使其文件事后损坏也是如此，因为挂载才是这些会话实际运行的组合；开机以来从未被组合的预设由其组合文件作答，disabled 门用 Loader 上下文求值，且读取从不挂载预设。conditional 表示宿主无法求值的门；无人组合的坏预设保留在列表中，携带原因且没有行。没有 roster 时该字段缺席。
你能用它做什么、不能做什么
该清单是供展示与诊断的快照：客户端可以渲染名单、标出失败条目，并通过比较快照检测变化。它不能启用、停用、添加或移除插件，也不携带历史——已经失败并被移除的 fiber 缺席。由于服务每次调用都读取 Loader，答案总是反映当前组合，而不是缓存视图。
理解实现
实现细节——点击展开
### 设计理念 网关是一层没有第二个生命周期真源的直接投影：每次 `list()` 调用都读取 `ctx.loader.entries()`，并把每个非组条目映射为公共行。Cordis 内部的 plugin/status 事件已经维护了 `Entry.fiber` 与 `Fiber.state`，因此再加缓存只会多出一个需要同步的生命周期真源。Agent 预设 roster 是每次调用经 `ctx.get('agentPresets')` 解析的可选伙伴：所有预设读取都由它的 `compositionInventory()` 负责，本包只把根 Fiber 状态映射到公共阶段词汇。 ### 阶段映射 Fiber 状态映射到公共阶段词汇，其中 `disposed` 折叠为 `null`——fiber 已消失的条目没有可报告的存活根。因此阶段从不区分为什么没有存活根：条目可能从未启动，也可能其 fiber 已被释放。 ### 源码地图 | 文件 | 职责 | |---|---| | [`src/index.ts`](src/index.ts) | `PluginInventoryGateway`：`pluginInventory` Remote 服务与 Loader 投影 | | [`src/types.ts`](src/types.ts) | 公共 payload 类型：`PluginInventoryEntry`、`PluginInventorySnapshot`、`PluginFiberPhase` | | — | 不发布运行时不变式伴生入口；每个快照都投影 Loader 持有的状态。 | Typert 生成由 `./typert` 与 `./remote` 导出的 Host 和 Client Remote 产物。进一步探索
当清单约定不够用时阅读以下内容：先看 Remote 如何到达客户端，再看它所投影的 Loader 与渲染它的界面。
- Remote 组合——客户端如何在不导入 Host 实现的情况下消费
pluginInventory/list。 - Cordis 插件 loader——本包所投影条目的那个 Loader。
模型体验
无。这个仅限 Host 的只读 Loader 投影不注册任何面向模型的内容。
KV Cache 影响
无；该包既不组装也不发送提供方请求。
已知限制与延期工作
这些限制说明一个点时刻清单无法告诉客户端什么。它们是当前包约束，不是任务积压。
- 仅表示调用当下——结果不包含持久的失败历史或订阅；只要不存在存活的根 Fiber，就会报告
null，而不区分其原因。 - 无修改能力——服务不能在任一平面启用、停用、添加或移除插件；来源只追溯到组合包层，用户 patch 或
--patchoverlay 插入的行不带 package。 - 预设仅随 roster 出现——未装
dsh-agent-presets的部署只提供 Loader 条目；agentPresets字段缺席而非为空。