装完一个插件，命令成功退出，但 Agent 没有出现新能力。先别重装，回答两个问题：包装在哪个 profile 里，它有没有进入实际加载的 bundle 列表？
本文以 CLI 0.2.0-rc.2 为准。命令注册与安装后的处理分别见固定版本的 args.ts 和 plugin.ts。本轮实际检查了 profile 初始化与配置导出；第三方插件的运行效果需要按社区插件篇另行验证。
一个 profile 是一套独立运行方案
按照安装篇设置 DSH_HOME 后，主要配置位于：
$DSH_HOME/profiles/<name>/
├── package.json 依赖清单与 dsh.profile.bundles
├── cordis.patch.yml 你自己的覆盖层
├── pnpm-workspace.yaml
└── node_modules/
web、headless、sdk 是不同的 profile 名称。它们可以共享 Harness 数据目录，但插件安装目标和运行方案需要分别确认。不要在 web 里装完包，再用 headless 的任务判断它是否生效。
先复制一份能运行任务的方案
第一次试插件，建议从内置模板创建独立 profile。例如，准备一份脚本任务的试验方案：
npx --no-install dsh --profile tutorial-ci \
--from-default-profile headless --dump-config
这个命令会初始化 tutorial-ci 并导出配置。后续运行它时使用 --profile tutorial-ci，不要又切回 headless。
模板决定了运行入口。单纯对一个新名字执行 plugin add，可能得到只有 base bundle 的自定义 profile；“目录建好了”并不等于已经获得 headless 或 Web 的入口。模板与默认值可在profile 声明核对。
分清依赖清单与运行清单
package.json 里的两处信息用途不同：
| 位置 | 回答的问题 |
|---|---|
dependencies |
包管理器安装了哪些依赖 |
dsh.profile.bundles |
哪些包作为配置层参与运行方案 |
dsh plugin 把包管理参数转交给 pnpm，在目标 profile 目录里执行；因此还需要可用的 pnpm。它随后按安装状态核对 bundle 声明，符合条件的包才会加入运行层。
普通依赖没有声明 dsh.bundle.patch 时，可能安装成功但不作为 bundle 激活。这个警告不是依赖丢失，而是在说明它没有贡献运行层。反过来，有 bundle 声明也只证明能被识别，不能证明版本兼容、插件启动成功或工具被模型调用。
常用操作，始终带上目标 profile
查看当前试验 profile 的依赖：
npx --no-install dsh plugin --profile tutorial-ci list
安装、更新、卸载的结构如下，尖括号部分需要替换成你审核过的包与精确版本，不能直接执行这份语法示意：
dsh plugin --profile tutorial-ci add <package>@<exact-version>
dsh plugin --profile tutorial-ci update <package>
dsh plugin --profile tutorial-ci remove <package>
安装前核对包版本和 peer 依赖；安装后检查 pnpm 输出及 dsh 的警告，再导出配置：
npx --no-install dsh --profile tutorial-ci --dump-config > tutorial-ci.yml
更新也要走这套检查。新版本可能增加或移除 bundle 声明，也可能改变条目 ID 和配置字段。“上一次安装成功”不能替代升级后的核对。
本地路径相对于哪里
包管理器在 profile 目录里运行，但你写的 . 往往指当前插件源码目录。dsh 会对相对路径参数做锚定，避免把 add . 理解成 profile 自己。
项目内安装 CLI 时，还有一层容易忽略的问题：切到插件仓库后，npx --no-install 未必还能找到原项目的二进制。先在 dsh-lab 保存绝对路径，再切目录：
DSH_BIN="$PWD/node_modules/.bin/dsh"
cd /path/to/your/plugin-checkout
"$DSH_BIN" plugin --profile tutorial-ci add .
这里 /path/to/your/plugin-checkout 是你自己的路径。这个例子用于安装已有插件源码，不会把任意目录自动变成合法插件。
安装脚本报错，要改哪份配置
git 来源的依赖与 registry 已构建发布包，可能有不同的构建要求。若 pnpm 因安装脚本或构建审批拒绝继续，先读当前 pnpm 版本的报错，再确认它指出的 workspace 配置是否位于目标 profile 目录。
不要看到一篇旧教程提到 allowBuilds，就往业务仓库根目录随手补配置。不同 pnpm 版本的设置和默认行为会变化；要允许某个构建脚本，也应先确认它实际执行什么。
怎样算完成一次插件变更
检查顺序可以固定下来：依赖版本正确 → bundle 层存在 → 目标条目进入组合配置 → 启动时没有相关错误 → 触发目标行为 → 卸载或回退后行为消失。
前三步主要是配置和安装检查，后几步才是运行验证。想看一个具体的兼容性筛选例子，接着读社区插件篇；只想关闭某个已有能力，不需要安装新包，直接看配置覆盖层。