环境能力清单 oliblue-evan/dsh-cli-inventory

dsh-cli-inventory 🧰

英文快速开始 —— 一个 DSH 插件，回答“这个 agent 实际能操作什么？”
它会在设置中增加一个页面：工具注册表（真正交给模型的工具）、技能注册表、MCP 服务器及其贡献的工具，然后是机器侧（PATH 上的 CLI、捆绑运行时、折叠起来的系统命令）。一切都是只读且容错的；命令列表只枚举 PATH 目录，并执行一个内置允许列表来读取版本。无网络、无凭据、无遥测。
安装：plugin_manager(action: "install_bundle", target: "github:oliblue-evan/dsh-cli-inventory")，
然后重启 DSH 并重新加载页面。MIT。

DSH 的设置里只有账户 / 通用 / 模型 / 插件 / 智能体预设五页 —— 它不会告诉你这个 Agent 手里有什么。
这个插件补上那一页：设置 → 环境与能力。

这一页的定位改过一次，缘由值得写下来。 第一版做的是“这台机器上装了哪些命令行工具”，结果列出 1270 个命令、其中 1263 个是 macOS 内部工具（AssetCacheLocatorUtil、BTLEServer…），既没用也没信息量。而清单本来就不是能力边界 —— 有 bash 就能跑 PATH 里任何东西，真正的边界是权限策略。所以改成先答“我能操作什么”（工具 / 技能 / MCP），机器清单退到后面，系统目录干脆不列（占了实测里 96% 的条目，却毫无参考价值）。

版式照官方「内置插件」页做（见下一节）：带放大镜的搜索框 → 可折叠的组 → 两列卡片网格。

🔍 搜索工具、技能、命令…
──────────────────────────────────────────────────────────

▾ 工具 40 来自宿主工具注册表 ┌───────────────────────┐ ┌───────────────────────┐ │ bash │ │ read │ │ 执行 bash 命令（bash… │ │ 读取 UTF-8 文本文件… │ └───────────────────────┘ └───────────────────────┘ ┌───────────────────────┐ ┌───────────────────────┐ │ grep │ │ write │ │ 用 ripgrep 正则搜索… │ │ 创建或完整替换文本… │ └───────────────────────┘ └───────────────────────┘ …

▾ 技能 0 来自 ~/.dsh/skills 与技能提供者还没有技能。把技能放到 ~/.dsh/skills//SKILL.md 就会出现。

▾ MCP 0 未配置服务器还没有配置 MCP 服务器；配置后它们贡献的工具会出现在这里。

▾ DSH 自带运行时 2 由 harness 自带 ┌──────────────────────────────────────────────────┐ │ node │ │ v24.18.1 │ │ ╭──────────────────────────────────────────────╮ │ │ │ /Applications/DeepSeek Harness.app/…/node │ │ ← 等宽「身份标签」放路径 │ ╰──────────────────────────────────────────────╯ │ └──────────────────────────────────────────────────┘

▾ 你自己安装的 7 扫了 PATH 中 7/12 个目录 · 取到版本 4 个 gh · uv · dsh · tailscale · uvx · …

版式与交互照官方「内置插件」页

照的是 DSH 开源仓库里的真源码（不是打包产物反推）：

- packages/client/ui-settings-plugin-inventory/src/client/PluginInventorySettingsTab.tsx
- 同目录 PluginInventorySettingsTab.module.css

对齐的东西（前两版做过两处明显错处，都在这里修掉了）：

| 要素 | 具体做法 |
| 顶部标题区 | section 自己渲染（框架不代劳）：h2.heading（margin:0;18px;600）+ p.intro（margin:0;13px;三级色）。缺了它顶部就是一片空白 |
| 层级与间距 | 根 .section（gap 12、max-width 760）→ heading / intro / .panel（padding-top:2px）→ .catalog（gap 12、container）→ 搜索框与各组 |
| 搜索框 | 外层是 （点标签即聚焦），内嵌放大镜（absolute;left:12px）、visuallyHidden 文案、36px 高、.5px 描边、color-mix 焦点环 |
| 组 | .groupTitleRow（min-height:36px，chevron + 标题）+ p.groupSub（若干 用 · 分隔，计数也是其中一项）+ .groupBody |
| 卡片可点击展开 | li.card[data-open] 内是 button.cardContent（aria-expanded + aria-controls），右侧 .cardTrailing 放 chevron（展开时 rotate(180deg)）；同时只展开一张卡（官方 expanded: string | null） |
| 展开后的详情 | .cardDetails 里： + 键值表（grid-template-columns:76px minmax(0,1fr)、div{display:contents}、dt 11px 三级色 / dd 12px 二级色） |
| 卡片内容 | 标题是 （14/20、500）、描述 （12/18、两行截断，展开后不再截断）、等宽身份标签是 （--dsw-alias-bg-module-platform + --ds-font-family-code） |
| 加载/错误 | 骨架卡用同一个 .cards 网格（4 张）+ visuallyHidden 文案；错误态给「重试」按钮（官方也只有这里才有重试按钮） |

用的是设置页专用 token（--dsw-alias-settings-card-stroke/-fill、--dsw-alias-bg-module-platform、 --dsw-radius-、--ds-font-family-code），所以它在设置里看起来是原生的。

展开看什么：折叠时描述被截成两行，展开时取消截断（官方原样：.card[data-open='true'] .cardDescription{display:block}），
所以完整说明本来就出现在卡体里 —— 详情区因此只放卡片上看不到的事实：

| 卡片 | 展开后的详情 |
| 工具 | 无额外事实（展开即读完整说明） |
| 技能 | 提供者、何时使用 |
| MCP | 服务器、原始工具名 |
| 命令行 / 运行时 | 完整路径（顶部那个等宽芯片会截断，展开行不截断 —— 官方也是「chip 安静 / 展开行醒目」的分工） |

不许重复：详情里不能再放说明或版本（版本就是命令卡的描述行）。早先两处都放了，结果同一段话在展开后出现两遍。现在有专门的门禁盯着这件事（test/client-logic.test.mjs）。

一个事后拿到官方背书的巧合：官方注入样式的方式是「按 data-plugin-css 键 querySelector，已存在就复用、从不移除」。这与我在 dsh-usage-pill 上修完「组件还在、样式没了」那个 bug 之后改成的写法完全一致 —— 当时是从失败模式反推出来的，现在算是确认了这是官方约定。

为什么不列系统目录

一开始我把整条 PATH 都列出来，结果是 1270 个命令里 1263 个来自系统目录（/usr/bin 932 个、/usr/sbin 222 个…），全是 AssetCacheLocatorUtil、BTLEServer 这类 macOS 内部工具 —— 既没有实用价值，也把真正要看的那几个（gh / uv / dsh）淹掉了。

所以现在宿主直接跳过系统目录。这带来两个结果：

- 页面只剩“你自己装的”那几行，不再有上千行；
- 扫描从 ~800 ms 降到 ~40 ms（少掉 96% 的 stat）—— 顺带把 15 秒缓存和「重新扫描」按钮都变成了多余机关，于是也一并删掉了。

需要看某个系统命令时用终端 which / command -v 即可，那不是这一页的职责。

界面上做的几件事

| 做法 | 为什么 |
| 能力段排在最前 | 工具 / 技能 / MCP 才是“我能操作什么”；机器清单退到后面 |
| 空段给出“怎么才会有” | 技能与 MCP 现在多半是 0，直接写清放哪里、配了就会出现在这里 |
| 有版本的排前面 | 有版本信息的更能说明“它是什么”，没取到版本的一律注明「未取版本」 |
| 每段独立限流 | 某一段再长也不会挤掉别的段 |
| 摘要分两行 | 一行能力计数、一行机器计数，各自一眼可读 |

分类规则（lib/path-scan.js 的 classifyDir）：

| 归类 | 目录 | 处理 |
| 你自己安装的 | ~/（含 ~/.local/bin、~/.cargo/bin）、/usr/local/bin、/opt/（含 /opt/homebrew/bin） | 扫描并列出 |
| 系统自带 | /bin、/sbin、/usr/bin、/usr/sbin、/usr/libexec、/System/、/Library/Apple/、/usr/lib/ | 跳过，不列（classifyDir 仍在，将来想列回随时可以） |

路径会缩掉家目录前缀（/Users/you/.local/bin/gh → ~/.local/bin/gh）—— 界面更短，你分享截图时也不会顺带暴露用户名。

安全边界（这一节最重要）

枚举 PATH 只是读目录，安全。取版本需要执行二进制，风险就在这里，所以：

- 只对 lib/allowlist.js 里写死的清单执行（约 40 个常见工具：git / gh / node / python3 /
uv / jq / docker / …），参数固定、不带任何用户输入、单次超时 5 秒、并发上限 6、
只取第一条输出行并去掉 ANSI 颜色；
- 白名单之外的命令照常列出名称与路径，但绝不执行；
- 宿主半边不写文件、不联网、不读凭据；
- 数据路由带来源守卫：非回环 Host、跨站（Sec-Fetch-Site: cross-site）一律 403，非 GET 405。
想加白名单条目？必须是“会打印版本后退出、无副作用”的命令，直接在 lib/allowlist.js 里加一行，
npm test 会检查清单结构（名称唯一、参数非空、白名单里不得出现 rm / bash 这类）。

数据从哪来

宿主半边注册一条只读路由 /api/cli-inventory/list，做四件事：

0. 读能力：工具注册表、技能注册表、以及 MCP。三者全部容错：取不到或抛错只如实显示 0，绝不让整页失败。

工具必须带作用域读 —— 这是这一页准不准的关键。tools.schemas(scope?) 的契约写着 “scope 是 the viewing scope (the agent)；省略 = 全局视图”。实测：

| 视图 | 工具数 | 拿到什么 |
| 省略 scope（全局） | 1 | 只有 load_workspace_dependencies 这类不带作用域的 |
| 预设作用域（acquireScope() 的 generation key） | 26 | 静态组合的那批：read/write/edit/bash/grep/web_search… |

而当前会话实际有 40 个：多出的 14 个是随会话组合的（subagent、spawn_teammate、 team_task_、schedule_、cordis_inspect_、plugin_manager，服务契约原话是 “delegation tools are composed for a Session”）。

那 14 个从插件侧读不到，这条路我试过并撤掉了。源码里 view(scope) 是
this.layers.chainLayers(scope) —— scope 必须是层注册表登记的键。插件能拿到的
只有 agentPresets.acquireScope() 给的 generation key；用 agent/created 事件里的 this（Scoped）当 scope 试过，注册表不认，直接退回全局视图（1 个）。
Tool inspect provider 之所以能看到 40，是因为它运行在请求方 agent 的作用域内。
所以这一页显示的是“该预设给 Agent 的组合”，并在脚注里如实说明会话级工具不在其中。

防退化规则：两个视图都读，取工具更多的那个。作用域解析一旦失配（比如宿主改了 scope 的形状），预设视图会退化成全局视图 —— 那时自动回落，页面绝不会反而变少。
这条规则是实测踩坑（26 → 1）之后加的，冒烟测试有专门用例。

界面上如实标注：按预设 。
MCP 不需要翻配置：dsh-mcp-client 把工具注册成 mcp____，服务器名直接从工具名反推（只按第一个 __ 切 —— 服务器名里出现单个下划线很常见，按最后一段切会把名字拆坏）。

工具参数也一并下发（ToolSchema.parameters 里的 properties 与 required）——折叠时卡片正文就是描述，展开后给“参数 / 必填”才有实质内容，否则说明短的工具点开等于没反应。
1. 按 PATH 顺序读各目录 —— 只读“你自己装的”那些，系统目录直接跳过； stat 跟随符号链接（与 which 语义一致），先出现的目录赢；
2. 对白名单里存在的命令取版本；
3. 报出 DSH 自带的运行时，标为 harness。运行时取两个来源：当前宿主进程自己（process.execPath，桌面版就是 app 内自带的 node），以及
$DSH_HOME/dsh-runtimes//dependencies/{node,python}/bin/（CLI 侧安装的运行时）。

早先只从 process.execPath 旁边推 python 路径（../python/bin/python3）。那在 CLI 启动时成立，但在桌面版下必然失败 —— app 自带的 node 旁边没有 python，界面上于是只有一个 node、
python 凭空消失。改成扫运行时目录后两种启动方式都能列全。

一次扫描只走“你自己装的”那几个目录，实测约 40 ms（跳过系统目录省掉了 96% 的 stat）。
所以这一页没有缓存、也没有刷新按钮：每次打开就是最新的。

文件

index.js 宿主：扫描 + 白名单探测 + 只读路由（零第三方依赖） client.js 客户端：设置页（单文件 bundle，含可测的纯逻辑区块） lib/capabilities.js 工具 / 技能 / MCP 的识别与归一化（纯函数） lib/path-scan.js PATH 解析 / 可执行判定 / 顺序合并 / 版本行清洗 / 目录分类（纯函数） lib/allowlist.js 版本探测白名单（安全边界所在） cordis.patch.yml bundle 层：挂一行宿主条目
locale/{en,zh}.json 插件页标题与简介（官方 meta 约定）
assets/icon.svg 插件图标 test/ 37 项断言 + 宿主冒烟测试

安装 / 卸载

官方 CLI
dsh plugin --profile add github:oliblue-evan/dsh-cli-inventory

或在 DSH 里用 plugin_manager：

plugin_manager(action: "install_bundle", target: "github:oliblue-evan/dsh-cli-inventory")

卸载：

dsh plugin --profile remove dsh-cli-inventory

装完必须重启 DSH：宿主半边不会被热重载（Node 的 ESM 缓存），新路由要重启才注册。
重启后打开 设置 → 环境与 CLI。

本地开发用 link: 安装（改代码即时生效，宿主半边仍需重启）：
plugin_manager(action: "install_bundle", target: "link:/path/to/dsh-cli-inventory")

隐私与数据披露

同样的内容以机器可读形式声明在 package.json 的 disclosure 字段（DSH 插件市场 §9 披露契约）。

| 项 | 声明 |
| 云端依赖 | 无 —— 插件不发起任何网络请求 |
| 完全离线 | 是 |
| 凭据 | 不读取任何凭据 / API Key |
| 权限 | 只读 PATH 目录；对白名单执行 --version 取版本 |
| 数据留存 | 无 —— 不落盘、不外发，也没有缓存（每次请求都是当场扫描） |
| 遥测 / 统计 | 无 |
| 返回内容 | 仅命令名、版本、缩略路径；不含绝对家目录路径 |

测试

npm test # 37 项断言：能力识别 / PATH 解析 / 分类 / 白名单 / 客户端纯逻辑 / 打包契约 / 结构契约
node test/host-smoke.mjs # 宿主冒烟：真的读 PATH、真的取版本、验证来源守卫、只扫用户目录、运行时识别、能力段容错

npm test 是 hermetic 的（不碰文件系统、不拉进程）；冒烟测试单独跑，因为它确实会扫盘。

这些门禁都是踩过坑之后固化下来的：

- 打包契约 —— exports 必须暴露 ./package.json 与 ./locale/.json。宿主读插件页标题/简介走 Node 的 ESM 解析器，exports 没声明就等于"资源不存在"，而且不报错、静默退化成没有标题和图标。
- 结构契约 —— 样式必须插件级注入（塞在组件树里的话，换个槽位渲染就一个样式都拿不到）；宿主半边不得出现裸模块名（link: 安装下解析失败会让整个宿主半边起不来）；用 999px / 50% 做圆角的地方必须写 corner-shape:round（宿主把全局圆角改成超椭圆了，不写就变形）。
- slots.inject 必须由 ctx.effect 管住 —— 否则插件被 dispose 后注册会泄漏，而 已被移除，页面变成「组件还在、样式没了」。（这条在 dsh-usage-pill 上真实爆过一次。）
- 词条与隐私 —— 中英词典必须键一致、且没有声明了却引用不到的词条（写成 t('scope.' + key) 拼字符串会被它抓出来）；冒烟测试检查响应里不得出现绝对家目录，这条当场抓到过一个真 bug：响应里漏了未缩略的 dir 字段。

门禁本身也做了变异测试：把修复回退、看门禁会不会报错。第一版 slots.inject 门禁就是这么被证明是假的（"往前 160 字符里出现过 ctx.effect( 就算过"，多处注入时抓不到漏包的那处）。

已知取舍

- 只扫"你自己装的"那部分 PATH：~/、/usr/local/bin、/opt/。系统目录（/usr/bin 等上千项）不列出 —— 那是实测里 96% 的噪音。要看某个系统命令用终端的 which / command -v；/Applications 里的 GUI 程序也不算 CLI。
- 版本只对白名单取（约 40 个常见工具）。白名单之外一律显示"未取版本" —— 这是有意的安全取舍，不是功能缺失。
- 单次扫描约 40 ms，每次打开这一页都会重新取数（没有缓存这层机关）。
- 每段最多渲染 80 行；现在条目只有十几条，这个上限几乎用不到。
- 白名单是代码里的静态清单，新工具不会自动出现版本；提 issue 或自己加一行都行。
- 技能与 MCP 现在多半是 0（本机既没装技能、也没配 MCP 服务器）。这不是占位符：接口已经接好，~/.dsh/skills/**/SKILL.md 或一个 MCP 服务器一出现，它们就会自动列出来。
- 工具列表是"当前组合"的：换 Agent 预设、加 MCP 服务器、装带工具的插件，这里都会跟着变。
- 没做「斜杠命令」：ctx.commands.list() 的签名要求传入一个 Agent，插件侧没有稳定入口；而且那是你输入的命令，属于用户侧能力，不是 Agent 的。要做的话另开一段更合适。

协作说明

本插件由 李敖（oliblue） 与 DeepSeek（deepseek-flash） 协作完成：需求、设计与逐轮验收由作者负责，代码实现与测试由模型完成；版权归人类作者所有（见 LICENSE）。