Host Integration Guide

面向宿主集成方的接入说明。

1. 推荐接入方式

宿主优先使用：

plugins：覆盖 builtin 层
optionalPlugins：追加 object / ui / workflow plugin families
uiComponents：把 leftDock / slots 里的组件 ID 解析成真实 Vue 组件
options.readonly：控制是否只读
组件事件与文档快照 API：同步宿主业务状态

如果你只需要接一个上传服务，也可以继续使用 uploadService 便捷 prop；它会被包装为 workflow plugin。但对外推荐入口仍是 direct WorkflowServicePlugin。

2. 最小示例

import {
  EDITOR_COMMANDS,
  MolEditor,
  type UIContributionPlugin,
  type WorkflowServicePlugin,
} from '@shangchien/molio'
import HostInspectorPanel from './HostInspectorPanel.vue'
import HostStatusHud from './HostStatusHud.vue'

const INSPECTOR_ICON = '<svg viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M4 5.5C4 4.67 4.67 4 5.5 4H18.5C19.33 4 20 4.67 20 5.5V18.5C20 19.33 19.33 20 18.5 20H5.5C4.67 20 4 19.33 4 18.5V5.5Z" stroke="currentColor" stroke-width="1.8"/><path d="M8 9H16" stroke="currentColor" stroke-width="1.8" stroke-linecap="round"/><path d="M8 12H16" stroke="currentColor" stroke-width="1.8" stroke-linecap="round"/><path d="M8 15H13" stroke="currentColor" stroke-width="1.8" stroke-linecap="round"/></svg>'

const hostUiPlugin: UIContributionPlugin = {
  manifest: {
    id: 'host:ui.viewport',
    name: 'Host Viewport Actions',
    version: '1.0.0',
  },
  toolbar: [
    {
      id: 'host:ui.viewport.autofit',
      slot: 'top-utility',
      label: '重置视图',
      commandId: EDITOR_COMMANDS.viewAutofit,
    },
  ],
  leftDock: [
    {
      id: 'host:ui.inspector',
      label: 'Inspector',
      iconKey: INSPECTOR_ICON,
      panelComponent: 'host:inspector-panel',
    },
  ],
  slots: [
    {
      id: 'host:ui.status-hud',
      slot: 'hud',
      component: 'host:status-hud',
    },
  ],
}

const hostWorkflowPlugin: WorkflowServicePlugin = {
  manifest: {
    id: 'host:workflow.upload',
    name: 'Host Upload Workflow',
    version: '1.0.0',
  },
  upload: {
    id: 'host:upload',
    accept: ['image/*'],
    async upload(file) {
      const formData = new FormData()
      formData.append('file', file, 'image.png')
      const res = await fetch('/api/upload', { method: 'POST', body: formData })
      const data = await res.json()
      return { url: data.url }
    },
  },
}

const uiComponents = {
  'host:inspector-panel': HostInspectorPanel,
  'host:status-hud': HostStatusHud,
}

vue

<template>
  <MolEditor
    :optional-plugins="[hostUiPlugin, hostWorkflowPlugin]"
    :ui-components="uiComponents"
    :options="{ width: 960, height: 640, readonly: false }"
    @document-change="onDocumentChange"
  />
</template>

3. 宿主能控制什么

能力	当前状态	推荐入口
保留默认 builtin 层	已支持	不传 `plugins`
覆盖 builtin 层	已支持	`plugins`
追加宿主扩展	已支持	`optionalPlugins`
leftDock / slots 组件解析	已支持	`uiComponents`
只读模式	已支持	`options.readonly`
上传服务	已支持	推荐 direct `WorkflowServicePlugin.upload`
文档快照	已支持	`getDocumentSnapshot()` / `restoreDocumentSnapshot()`
项目文件	已支持	`.mpz`，内部为 `gzip(JSON(DocumentSnapshot))`
文档事件	已支持	`select` / `update` / `document-change`

4. 宿主不应做什么

不要绕过 transaction 直接操作内部 store
不要直接依赖 useEditor.ts 的内部编排细节
不要把业务态塞进 object controllers 或 kernel services
不要直接依赖内部 molDataStore、RDKit 运行时实例或 registryBridge 适配细节

5. 当前可用的 UI 扩展面

宿主 today 可以通过 UIContributionPlugin 扩展：

toolbar
context menu
selection bar
leftDock
shortcuts
commands
slots

其中 leftDock.panelComponent 与 slots.component 需要由宿主通过 uiComponents 提供组件映射。渲染出的组件会收到 editor 与 contribution 两个 prop。

6. 当前可用的 workflow 扩展面

当前 workflow registry 已经是宿主覆盖与扩展边界：

upload
layout
persistence
share
clipboard
importers
exporters

更准确的消费边界是：

layout、persistence、share、clipboard、upload 已由 kernel 主路径直接读取 workflow registry
importers、exporters 通过 workflow registry 注册，再由 shell 或 workflow helper 在需要时查询调用
builtin 层提供默认实现，宿主可在 optional 层覆盖

7. 建议的宿主分工

宿主负责

路由与 URL 状态
草稿、持久化与远端服务
鉴权与能力裁剪
外部 inspector、表单、数据关系视图

编辑器负责

文档编辑内核
对象、UI、workflow registry runtime
交互、命中、历史与场景同步

8. 下一阶段你应该关注什么

如果你只需要自定义按钮、菜单、快捷键，今天已经可以直接写 UI family
如果你要自定义对象，今天应使用 ObjectTypePlugin + createRuntime(ctx)
如果你要接 leftDock 或 overlay/hud slot，补一份 uiComponents 映射即可
如果你准备接入更完整的 I/O 工作流，优先按 WorkflowServicePlugin 组织宿主服务；其中 upload / layout / persistence / share / clipboard 今天已能直接进入主路径，import / export 则按 registry 查询路径组织即可

Host Integration Guide ​

1. 推荐接入方式 ​

2. 最小示例 ​

3. 宿主能控制什么 ​

4. 宿主不应做什么 ​

5. 当前可用的 UI 扩展面 ​

6. 当前可用的 workflow 扩展面 ​

7. 建议的宿主分工 ​

宿主负责 ​

编辑器负责 ​

8. 下一阶段你应该关注什么 ​