dsh-visual-workbench

Readme

# DSH Visual Workbench

一个面向 DeepSeek Harness（DSH）的本地优先可视化工作台插件：把 Obsidian-style 知识空间、ComfyUI 工作流货架和执行前安全检查放到同一个 DSH conversation view 中。

> 当前状态：`v0.2.0` 源码已按开源项目形态落盘。除工作流运行闭环外，工作台现在提供本地 Comfy MCP 的可视化配置、连接测试、ComfyUI 启动、workflow 预检、节点与模型读取入口。静态 `dsh-std` v0.15 清单和离线门禁可运行；真实 DSH Web profile、ComfyUI、GPU 和生成结果尚未在本机现场签核。

## 这是什么

插件提供三个层次：

- `dsh-plugin.json`：按 `dsh-std` Community Draft v0.15 描述 host facet、权限、命令、来源和可选 browser UI contract。
- DSH host：导出 Cordis `apply(ctx)`，注册 `dsh_visual_workbench_status` 和 `dsh_visual_workbench_run` 两个模型工具，并提供同源 loopback state / preview / run 路由。
- DSH browser client：通过 `conversation.view` slot 注入工作台 tab，展示 Obsidian-style facets、bounded wikilink graph、JSON workflow shelf、Comfy MCP 状态、可视化本地连接配置和 run guard。

Comfy MCP 是独立的本地 stdio MCP server。插件只使用官方 TypeScript MCP client 启动/连接 `comfy-mcp`，按 `server_info → run_workflow → fetch_outputs` 调用，并把 `server_info`、`launch_comfyui`、`validate_workflow`、`nodes`、`search_models` 等本地动作映射到工作台按钮；不复制 Comfy MCP 源码。

## 架构

```mermaid
flowchart LR
  UI[DSH Web Client\nVisual Workbench] -->|same-origin GET/POST| Host[DSH Host Plugin\nCordis apply(ctx)]
  Host -->|read bounded metadata| Vault[Configured workspace\nObsidian-style facets]
  Host -->|stdio MCP client| MCP[comfy-mcp\nlocal subprocess]
  MCP -->|comfy CLI| Comfy[Local ComfyUI]
  Host -->|preflight then run| Guard[Preview token\npath boundary\nconfirm_spend]
  Guard --> MCP
```

## 快速开始

### 1. 准备 Comfy MCP

按照 [Comfy-Org/comfy-mcp](https://github.com/Comfy-Org/comfy-mcp) 的官方说明安装 `comfy-mcp` 与 `comfy-cli`，启动本地 ComfyUI，并确认 `server_info` 可用。插件默认启动命令是 `comfy-mcp`，不会自动替你安装 ComfyUI、模型或依赖。

### 2. 配置 DSH profile

至少设置一个绝对路径工作区：

```text
DSH_WORKBENCH_ROOT=/absolute/path/to/your/workspace
```

可选配置：

```text
DSH_WORKFLOWS_DIR=/absolute/path/to/your/workspace/workflows
COMFY_BIN=/absolute/path/to/comfy
COMFY_PROJECT=/absolute/path/to/your/comfy-project
COMFY_LOCAL_URL=http://127.0.0.1:8188
DSH_COMFY_MCP_COMMAND=comfy-mcp
DSH_COMFY_MCP_ARGS=[]
```

`DSH_COMFY_MCP_ARGS` 必须是最多 8 个字符串组成的 JSON 数组。插件使用 `spawn` 的参数形式，不经过 shell；不接受整段 shell 命令。

### 3. 在工作台中可视化配置本地连接

用户提供的 Bilibili 短链所概括的入口是：让 Agent 按 Comfy 官方“Local Comfy MCP connection”指南配置本地连接。这里把同一个流程做成了工作台操作：

1. 安装 `comfy-mcp` 与 `comfy-cli`，并先按官方要求启动本地 ComfyUI。
2. 打开 DSH 的 `Visual Workbench`，在 `Local Comfy MCP Setup` 中填写绝对路径和可选的本地端口覆盖。
3. 点击“应用配置并连接”，再点击“测试连接”；连接成功后即可在 `Local Operations` 中点击“启动 ComfyUI”、预检 workflow、读取节点目录和读取模型文件。

界面配置只保存在当前 DSH 进程内：它不会把 `COMFY_API_KEY` 回显，也不会替用户写入长期凭据文件。需要长期保存时，仍应按 [Comfy 官方本地连接文档](https://docs.comfy.org/zh/agent-tools/mcp) 或 DSH/MCP profile 的机制手动配置。`COMFY_LOCAL_URL` 只接受 `localhost`、`127.0.0.1` 或 `::1` 的 HTTP loopback 地址。

### 4. 安装并构建

```bash
pnpm install
pnpm check
pnpm build
```

将包安装到 DSH Web profile 后，`package.json` 中的 `dsh.bundle.patch` 会让 DSH loader 插入 `cordis.patch.yml`，`dsh.client` 会提供浏览器端 `lib/client.js`。不同 DSH 发行 profile 的依赖版本可能不同，按宿主实际包版本调整 peer dependencies。

## 运行闭环

1. 工作台只读刷新：读取配置 workspace 的固定 facet、最多 120 个 Markdown 文件的 bounded wikilink graph 和最多 40 个 workflow JSON。
2. 生成预览：校验 workflow 与 output directory 都是绝对路径、真实存在，并解析后仍在 `DSH_WORKBENCH_ROOT` 内；预览 token 10 分钟过期且只能消费一次。
3. 可视化本地操作：工作台的连接按钮调用 `server_info`；启动、预检、节点和模型按钮分别调用已 allowlist 的 Comfy MCP 工具；工具结果原样显示在 `Last Result`，不伪造成功状态。
4. 显式运行：浏览器确认后，host 先调用 `server_info`，再调用 `run_workflow`，最后用 `fetch_outputs` 把结果复制到已确认的 output directory。
5. 花费保护：默认传 `confirm_spend=false`。只有用户明确在界面或模型工具参数中给出 `true`，才允许 Comfy MCP 放行可能收费的 partner nodes；插件不把 Agent 自己填写的布尔值包装成“人类已同意”。

模型工具也遵循同一边界：不设置 `DSH_WORKBENCH_ROOT`、路径越界、文件不存在、Comfy MCP 不可连接，调用直接失败并给出下一步，而不是猜测路径或静默降级。

## 开源说明

- 本插件源代码、规范清单、测试和文档采用 MIT，见 [LICENSE](LICENSE)。
- `schemas/dsh-plugin-0.15.schema.json` 是来自 [dsh-std](https://github.com/Yan-Zero/dsh-std) 的 MIT schema 副本，来源说明见 [NOTICE](NOTICE)。
- 本仓库不包含 `niuma-engine`、`obsidian-ai-toolkit` 或 `comfy-mcp` 源码；它们分别作为工程纪律参考、Obsidian-style 信息架构参考和 MCP 协议互操作对象。
- Comfy MCP 本身是独立项目，当前许可证边界以其仓库为准。若未来把 Comfy MCP 源码一起打包，不能继续把整包简单标成 MIT。

## 目录

```text
dsh-plugin.json                  # dsh-std v0.15 static manifest
package.json                     # DSH bundle/client metadata
cordis.patch.yml                 # DSH loader overlay
src/index.ts                     # DSH host tools + secure routes
src/comfy-mcp.ts                 # official MCP TypeScript client bridge
src/workspace.ts                 # bounded workspace summary and graph
src/local-security.ts            # loopback, token, path and body guards
src/client/index.tsx             # DSH browser workbench tab
schemas/                         # vendored dsh-std v0.15 schema
scripts/                         # offline manifest/source hygiene checks
tests/                           # deterministic tests without live DSH/ComfyUI
docs/                            # design/research/provenance notes
.github/                         # contribution, security, issue and CI templates
```

## 验证口径

本仓库的 `pnpm check` / `npm run check` 只能证明：JSON manifest 形状、来源卫生、TypeScript 静态类型和确定性测试通过。它不能证明：

- DSH 当前某个 Web profile 已经接受这个第三方 bundle；
- `@modelcontextprotocol/client` 能在你的 Node/DSH 发行版中成功启动 `comfy-mcp`；
- 本地 ComfyUI 的模型、节点、GPU、VRAM 或工作流实际可运行；
- 任何生成图像、模型下载或 partner credits 的真实结果。

真实环境验收建议固定为：同一 DSH profile、同一 `DSH_WORKBENCH_ROOT`、同一 workflow JSON，先 `server_info`，再 `run_workflow`，最后 `fetch_outputs`，并保留命令输出与生成文件路径。

## 参考来源

- [niuma-engine](https://github.com/Destined-at-Dawn/niuma-engine)：no-blind-overwrite、脚本安全、负结果和证据边界的工程纪律参考。
- [obsidian-ai-toolkit](https://github.com/Destined-at-Dawn/obsidian-ai-toolkit)：Vault facet、graph、MOC、Templates 和 AI 工作流的信息架构参考。
- [dsh-std](https://github.com/Yan-Zero/dsh-std)：互操作 manifest、core meta-protocol 和 browser UI extension lane。
- [DeepSeek Harness 文档](https://deepseek-harness.github.io/deepseek-harness/en/develop/basic/)：Cordis plugin、inject、effect、host/client 装载边界。
- [Comfy MCP](https://github.com/Comfy-Org/comfy-mcp)：本地 stdio MCP、`server_info → run_workflow → fetch_outputs` 和 `confirm_spend` 语义。
- [用户提供的 Bilibili 视频](https://b23.tv/GsYG8b3)：用户补充的主要内容是“让 Agent 按 Comfy 官方 Local Comfy MCP connection 指南完成本地配置”；本插件把该入口落实为 DSH 工作台中的可视化配置与操作卡片。视频本身未在本轮独立解析，接口事实以 [Comfy 官方本地 MCP 文档](https://docs.comfy.org/zh/agent-tools/mcp) 和 [Comfy MCP 官方 README](https://raw.githubusercontent.com/Comfy-Org/comfy-mcp/main/README.md) 为准。