README.zh.md 6.5 KB
description: "当前 Cordis Loader 插件状态的只读投影，并附带每个 agent preset（智能体预设）的组合：面向 web GUI 宿主客户端的 pluginInventory 服务及其 pluginInventory/list Remote。"
kind: "package-reference"
@deepseek-ai/dsh-host-plugin-inventory
English | 中文
概述
客户端调用 pluginInventory/list，读取非 group Loader 条目的只读快照，包括来源、有效启用状态、运行阶段和当前失败。包含 agent-preset 目录的部署还报告各预设的元信息与组合。快照不提供持久历史或变化订阅。
目录
使用本包
当客户端或设置页需要展示宿主当前组合了什么——哪些插件已加载、已启用、是否存活，以及每个 agent preset 会给会话什么——时调用 pluginInventory/list。Remote 是唯一入口：该服务仅供 Remote 使用，刻意不声明同进程 Cordis Context 合并。
快照包含什么
每一行是一个非组 Loader 条目：其条目 id、精确模块标识、有效启用状态（含被禁用的祖先组）与当前根 Fiber 阶段。pending 表示条目等待加载，loading 表示正在读取，active 表示正在运行，failed 表示其 fiber 被拒绝，unloading 表示正在拆除；null 表示完全不存在存活的根 Fiber。结构性的 group 行会被跳过。
trust 标识提供该行的组合包，package 给出包名与版本，disabledBy 区分用户覆盖与组合条件。显式行 id 保持不变。失败条目留在 Loader 树中；failure 报告导入、激活、更新、disabled 表达式或缺失服务问题。active fiber 也可能更新失败，并继续运行先前的有效配置。加载前因冲突被排除的行从 ProfileRuntime.conflicts 投影。没有 profile 来源时，行不携带 package。
每个预设的组合
组合了 roster 时，agentPresets 按 roster 顺序携带每个预设一组：其 id、随部署内置还是用户自建（trust，客户端据此本地化内置预设名）、发布的显示名、未指名预设的会话是否组合它，以及压平后的插件行——条目 id（文件行未声明时为 null）、模块标识、有效启用状态、行自带的 !!js disabled 表达式（如有）、组合存活时的根 Fiber 阶段、该行来自预设的组合文件还是其用户补丁层（source），以及被关掉的行是组合还是补丁层关掉的（disabledBy）。已有会话组合过的预设由其最新仍存续的世代作答——即使其文件事后损坏也是如此，因为挂载才是这些会话实际运行的组合；开机以来从未被组合的预设由其组合文件作答，disabled 门用 Loader 上下文求值，且读取从不挂载预设。conditional 表示宿主无法求值的门；无人组合的坏预设保留在列表中，携带原因且没有行。没有 roster 时该字段缺席。
你能用它做什么、不能做什么
该清单是供展示与诊断的快照：客户端可以渲染名单、标出失败条目，并通过比较快照检测变化。它不能启用、停用、添加或移除插件，也不携带历史——已经失败并被移除的 fiber 缺席。由于服务每次调用都读取 Loader，答案总是反映当前组合，而不是缓存视图。
理解实现
实现细节——点击展开
### 设计理念 网关是一层没有第二个生命周期真源的直接投影：每次 `list()` 调用都读取 `ctx.loader.entries()`，并把每个非组条目映射为公共行。Cordis 内部的 `plugin/status` 事件已经维护了 `Entry.fiber` 与 `Fiber.state`，因此再加缓存只会多出一个需要同步的生命周期真源。agent preset roster 是每次调用经 `ctx.get('agentPresets')` 解析的可选伙伴：所有预设读取都由它的 `compositionInventory()` 负责，本包只把根 Fiber 状态映射到公共阶段词汇。 ### 阶段映射 Fiber 状态映射为公开阶段，其中 `disposed` 映射为 `null`。启用但没有 fiber 且存在失败记录的条目报告 `failed`；正常禁用且没有活跃 fiber 的条目报告 `null`。 ### 源码地图 | 文件 | 职责 | |---|---| | [`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 影响
无；该包既不组装也不发送提供方请求。
已知限制与延期工作
这些限制说明即时清单无法向客户端提供哪些信息。它们是当前包约束，不是任务积压。
- 仅提供当前状态——结果不包含持久失败历史或订阅；移除条目也会移除其诊断。
- 无修改能力——服务不能在任一平面启用、停用、添加或移除插件；来源只追溯到组合包层，用户 patch 或
--patchoverlay 插入的行不带 package。 - 预设仅随 roster 出现——未装
dsh-agent-presets的部署只提供 Loader 条目；agentPresets字段缺席而非为空。