简要结论
理解 dsh 启动时如何一层层组合插件树，以及 web 与 headless 的区别。
一个正在运行的 dsh 可以看成启动时组合出来的插件树。Profile 负责描述“使用哪些层”，Bundle 负责分发一组配置和代码。
Profile
Profile 是保存在 Harness Home 中的一套命名组合。官方提供的模板包括 web 与 headless：
web添加浏览器应用与交互界面；headless面向不启动服务器的一次性执行。
Profile 还可以保存外部 Plugin 和用户自己的补丁配置。
Bundle
Bundle 把 Cordis 配置行和对应代码包装在一起。基础 Bundle 会提供模型适配器、工具、持久化、沙箱、审批、设置和凭据等能力；其他 Bundle 再向上叠加 Web 或 Headless 行为。
查看实际启动配置
官方架构文档提供了查看当前配置树的命令：
dsh --profile web --dump-config开发者预览期命令可能变化，执行前请对照当前版本帮助信息。
为什么顺序重要
Bundle、Profile 补丁、Home 补丁和命令行 Overlay 会按顺序应用。后面的层能够替换或增加配置，因此两个 Plugin 竞争同一能力时，加载位置可能决定最终行为。
修改前先导出当前配置，并把自定义内容放在受版本控制或可备份的位置。不要直接改依赖包内部文件。
建立可回滚的配置实验
把一次配置修改当作实验，而不是直接在主环境堆叠补丁：
- 记录当前 dsh 版本、Profile 名称和启动命令。
- 用
--dump-config保存“修改前”的解析结果。 - 一次只增加一个 Plugin 或 Overlay。
- 再次导出配置并比较差异。
- 运行最小健康检查：启动、创建会话、调用一个只读工具、正常退出。
- 移除新增层，确认基础 Profile 能恢复。
PENDING 不一定是启动顺序问题
Cordis 配置项可能并发启动，服务依赖由插件的 inject 决定，而不是 YAML 中的肉眼顺序。一个消费方长期保持 PENDING 时，先检查所需服务的 Provider 是否已包含在组合中，再检查配置项路径和包名。
例如工具插件注入 tools，工具服务又要向系统提示贡献 Schema；若组合缺少对应服务提供方，仅仅把插件行上下移动通常不能解决根因。
变更记录模板
目标：
新增配置层：
预期新增的服务/工具：
解析配置差异：
健康检查结果：
回滚步骤：这个小记录能防止“配置越改越多，但没人知道哪一层真正生效”。进入复杂架构前，先确保每个变化都可观察、可比较、可撤销。