安装
$npx -p @deepseek-ai/dsh dsh plugin --profile web add github:VanillaCreamer/dsh-plugin-visual-composer
DSH Visual Composer
DeepSeek Harness 的可视化 Cordis 插件树编排器
DSH Visual Composer 是一个运行在 DeepSeek Harness Web 界面中的社区插件。它把当前 Profile 的 Cordis 插件树转换成可视化画布，让你查看插件、添加插件或 Group、拖拽 Composer 管理的节点、编辑配置覆盖，并在保存前审阅脱敏后的 YAML Diff。
[!IMPORTANT]
本项目是独立社区原型，不是 DeepSeek AI 官方插件。DeepSeek Harness 目前仍处于 Developer Preview，插件接口可能在后续 RC 版本中变化。
目录
为什么需要它
DeepSeek Harness 采用“万物皆插件”的 Cordis 架构，但 Profile 的最终结构通常由 Bundle、cordis.patch.yml、Group 嵌套和运行时状态共同决定。只阅读 YAML 很难快速回答以下问题：
- 当前实际加载了哪些插件？
- 插件位于哪个 Group 中？
- 哪些节点处于 active、failed、disabled 等状态？
- 某个插件注入或依赖了哪些 Service？
- 一次配置覆盖最终会生成怎样的 Patch？
- 修改失败后能否安全恢复？
Visual Composer 将这些信息集中到 DSH Web 的插件设置页中，同时严格遵循 Cordis Patch 的真实语义，不把插件树伪装成任意连线的工作流引擎。
核心能力
- 读取当前 DSH Web Profile 的真实 Loader 树。
- 展示嵌套 Group、插件状态、模块名、Entry ID、注入信息与配置。
- 从左侧 Palette 添加插件或 Group 草稿。
- 将 Composer 管理的绿色节点拖入 Root 或任意 Group。
- 为现有 Entry 创建
disabled 和完整 config 覆盖。
- 按 ID、模块名或 Label 过滤插件树。
- 保存前展示脱敏后的 Composer 管理块 Diff。
- 使用预览签名保证“审阅的草稿”和“实际写入的草稿”一致。
- 仅维护
cordis.patch.yml 中有明确标记的区域，保留其他文本与注释。
- 通过乐观 Revision、防并发覆盖和原子替换写入配置。
- HMR 可用时等待根 Include 事务真正提交，再报告成功。
- HMR 拒绝或超时时自动恢复修改前文件。
- 自动创建轮换备份，并支持在 Web UI 中一键回滚最近备份。
- 对凭据、认证字段、
!!js 表达式及敏感配置进行脱敏和编辑保护。
兼容性与前置条件
| 项目 | 当前验证版本 |
|---|
| DeepSeek Harness | 0.1.0-rc.6 |
| Node.js | ^22.19.0 或 >=24.0.0 |
| UI | DSH Web Profile |
| 操作系统 | 已在 macOS 验证；实现使用跨平台 Node.js API |
dsh 命令可以正常执行；- 已存在或允许初始化
web Profile；
- DSH Web 通过本机回环地址访问，例如
http://127.0.0.1:4632；
- 需要加入画布的第三方插件已经安装到同一个 Profile。
安装
方式一：安装 Release 中的预构建 tarball（推荐）
dsh-plugin-visual-composer-0.1.0.tgz
dsh plugin --profile web add ./dsh-plugin-visual-composer-0.1.0.tgz
预构建 tarball 已包含 Host 和 Client 产物，安装时不需要在本机执行本项目的构建脚本。
方式二：从源码构建
git clone https://github.com/VanillaCreamer/dsh-plugin-visual-composer.git
cd dsh-plugin-visual-composer
npm ci
npm run pack
dsh-plugin-visual-composer-0.1.0.tgz
dsh plugin --profile web add ./dsh-plugin-visual-composer-0.1.0.tgz
dsh --profile web
从 DeepSeek Harness 源码仓库运行
如果使用的是 DeepSeek Harness 源码 checkout，请在相应工作目录中将 dsh 替换为 pnpm dsh：
pnpm dsh plugin --profile web add /绝对路径/dsh-plugin-visual-composer-0.1.0.tgz
pnpm dsh --profile web
卸载
dsh plugin --profile web remove dsh-plugin-visual-composer
卸载插件不会主动删除其历史备份，也不会移除已经写入 cordis.patch.yml 的 Composer 管理块。建议卸载前先在界面中清除不再需要的草稿和覆盖。
快速开始
- 启动 DSH Web；
- 使用浏览器打开终端中显示的本机地址；
- 进入 设置 → 插件 → Visual Composer；
- 在左侧输入已经安装的模块名，或添加一个 Group；
- 将绿色草稿节点拖到 Root 或目标 Group；
- 点击节点，在右侧 Inspector 中调整禁用状态或 JSON 配置；
- 点击右上角 预览变更；
- 阅读 YAML Diff 与警告；
- 点击 确认并保存；
- HMR 可用时等待界面报告事务提交成功。
建议第一次使用时先添加一个空 Group，以熟悉预览、保存和回滚流程。
界面与操作
Plugin Palette
- 模块名：npm 包名或 Profile 内可解析的相对模块，例如
@scope/plugin、./local-plugin.mjs；
- Entry ID：可选；留空时自动生成唯一 ID；
- 添加插件：创建普通插件草稿；
- 添加 Group：创建
cordis:group 草稿；
- 过滤插件树：按 ID、模块名或 Label 查找节点。
Visual Composer 不负责下载或安装第三方代码。模块必须先安装到当前 Profile，否则预览会被服务端拒绝。
dsh plugin --profile web add
安装完成后重新打开或刷新 Visual Composer，再添加对应模块 Entry。
Effective Cordis Tree
- 绿色节点：由 Visual Composer 管理的草稿节点，可拖拽；
- 普通节点：来自 Bundle 或现有 Profile 配置，只能创建覆盖；
- Group：可接收 Composer 管理的拖拽节点；
- CORE：关键基础节点，受到默认保护；
- 状态标记：显示
pending、loading、active、failed、unloading 或 inactive。
- 拖到画布 Root：移动到根级别；
- 拖到 Group：成为该 Group 的子节点；
- 不允许把 Group 拖入自身或其后代；
- 删除草稿 Group 时，会递归删除其 Composer 管理的后代。
Inspector
- 启用或禁用节点；
- 编辑完整 JSON
config；
- 应用或清除现有节点覆盖；
- 删除 Composer 草稿节点。
如果配置包含密钥、Token、认证字段、!!js 表达式或其他被判定为敏感的值，该配置不会发送到浏览器，也不能在 Inspector 中替换。
YAML Change Preview
- Override 数量；
- Insert 数量；
- Disabled 数量；
- 校验警告；
- 脱敏后的 Composer 管理块 Diff。
预览不会返回完整 cordis.patch.yml，也不会向浏览器暴露管理块之外的用户配置。
Cordis 编辑语义
现有节点为什么不能拖动？
Cordis Patch 可以按 ID 覆盖、禁用或插入 Entry，但不能任意移动 Bundle 已经定义的 Entry。Visual Composer 因此只允许拖动自身管理的 Insert 节点，不会制造无法落盘的“伪排序”。
config 是完整替换，不是深度合并
{
"timeout": 30000,
"retry": 3
}
最终覆盖不会自动保留 retry。请在提交前确认完整配置。
Group 与 Insert
Visual Composer 将新节点转换为 Patch insert：
- id: tools
insert:
- id: my-tool
name: my-tool-package
config: {}
根级节点则生成没有父 ID 的 insert Patch。
Composer 管理块
# >>> dsh-visual-composer managed block
- id: some-plugin
name: package-name
disabled: true
#
保存后没有立即生效
查看页面顶部是否提示 HMR 不可用。如果 HMR 被禁用，需要重启：
提示 Revision Conflict
磁盘上的 cordis.patch.yml 在页面加载后发生了变化。请刷新 Composer，重新检查草稿和 Diff，再保存。
配置编辑器是只读的
该节点的配置包含被脱敏的字段或表达式。Visual Composer 会将真实值保留在 Host 内，但不会允许浏览器替换整段配置。请直接使用本地编辑器修改对应配置。
无法拖动已有节点
这是 Cordis Patch 的语义限制，不是前端缺陷。已有 Bundle Entry 只能覆盖或禁用，不能通过 Patch 任意移动。只有 Composer 管理的绿色 Insert 节点可以拖动。
回滚按钮提示没有备份
只有成功进入正式保存流程后才会产生备份。尚未保存过时没有可回滚内容。
已知限制
- 当前仅验证 DeepSeek Harness
0.1.0-rc.6；后续 RC 可能需要适配。
- 仅允许本机浏览器访问，不支持远程管理和多人协作。
- 不提供插件市场、下载或版本管理能力。
- 不支持移动 Bundle 定义的现有 Entry。
config 使用完整替换语义，不提供深度合并。- 目前配置编辑器使用 JSON，不会根据插件 Schema 自动生成表单。
- 被脱敏的配置只能在本地文件中编辑。
- 当前 Diff 聚焦 Composer 管理块，不展示整个用户 Patch。
- 跨平台实现尚未在 Windows 和 Linux 上完成完整端到端验收。
路线图
- 基于插件 Schema 生成类型安全配置表单；
- 只读展示 Service provide/inject 依赖图；
- 增加备份历史选择和命名快照；
- 增加 Patch 导入、导出和更完整的冲突可视化；
- 为 Linux、Windows 建立端到端测试矩阵；
- 适配 DeepSeek Harness 后续公开版本；
- 增加英文文档和演示视频。
依赖图应由运行时 Service 信息自动推导，而不是允许用户随意连线；插件依赖与工作流边不是同一个概念。
参与贡献
- 可复现的错误报告；
- 不同系统和 DSH 版本的兼容性结果；
- Cordis Patch 边界案例；
- UI/UX 建议；
- 安全问题之外的功能提案。
npm run check
npm test
npm run build
npm run pack:check
- 操作系统与 Node.js 版本；
- DeepSeek Harness 版本；
- 插件版本；
- 使用的 Profile 名称；
- 脱敏后的错误信息和复现步骤。
请勿在公开 Issue 中提交 API Key、Token、Cookie、完整私有配置或未经脱敏的 cordis.patch.yml。
许可证
DeepSeek、DeepSeek Harness 及相关标识属于其各自权利人。本项目与 DeepSeek AI 没有官方隶属、授权或背书关系。