使用与排查工作台
查看依赖、定位启动和更新失败，以及部署 Workbench 时的连接要求。
本页说明工作台的导航、布局、配置和故障排查。插件异常时，先确认当前状态，再查看更新记录、依赖和日志。 给 Plugin 编写页面请从 Content 或 View 开始。
从现象定位问题
| 现象 | 下一步 |
|---|---|
| 插件没有运行 | 查看自动启动策略、配置校验和必须依赖 |
| 修改源码后出现错误 | 对照当前状态与最近更新，确认是保留旧定义还是新实例启动失败 |
| 自定义页面显示构建中 | 等待构建完成；失败时按该页面显示的错误修复 renderer |
| 页面提示会话失效 | 更新引起的失效会自动整页刷新；认证失效或连续刷新暂停时按提示处理 |
| 保存配置后行为未变 | 检查保存结果；未注册在线更新处理时需要显式重启 |
工作区标签与布局
找到并打开内容
官方入口栏提供首页、应用、插件管理、日志、安全、审计与依赖图，可切换图标或图标加文字。 “应用”列出业务入口；“插件管理”使用左侧唯一插件目录，选择后在中央编辑配置。 分组、排序、多选、拖动与搜索规则见插件分组。
顶部“查找入口”搜索官方页面、插件和全部已发布页面，包括未加入常用导航的路由。 参数化路由需要输入具体路径；标记“独立页面”的入口离开工作区打开完整页面。
普通入口在当前活动标签内导航；没有文档时才新建。活动标签后面的“+”和标签菜单的复制操作， 打开当前地址的独立副本，沿用当前名称，重新读取数据，不复制未保存草稿。离开有未保存内容的页面需先处理草稿。 每个文档拥有独立导航与输入，地址栏跟随活动文档；工具获得焦点不会改变文档地址。
插件详情标签显示插件名称，业务页面使用声明标题，未声明标签时使用入口 key。
F2 可重命名；查询、锚点、后台刷新与重新激活不会覆盖手工名称，切到不同页面身份时使用新页面名称。
展开和收起工具
顶部中央的三个布局按钮控制左、右、底部区域。
| 区域 | 内容与恢复方式 |
|---|---|
| 左侧 | 插件管理目录，以及当前插件已打开的独立左侧面板；无内容不占位 |
| 右侧 | 官方“插件面板”内部切换信息与最近日志；插件扩展各自使用独立原生标签 |
| 底部 | 当前插件已打开的底部面板，没有默认内置工具 |
从“插件信息”的扩展列表或顶部“查找入口”打开当前插件的面板，重复打开会聚焦已有标签。插件面板可关闭、在声明区域内排序；不能跨区域或拖到中央。关闭后仍可通过这两个入口重新打开。官方工具保持固定，不能关闭或拖动。
收起区域保留标签条；关闭插件面板移除其标签。切换文档时，面板跟随当前插件实例，包括 fork：旧内容释放，返回时恢复该插件未关闭标签的布局；已关闭的面板不会因切回或刷新自动重开。没有内容的区域不占位。已保存而撤回的面板显示不可用，可关闭。
右侧“最近日志”独立于“插件信息”；标题、日志级别和查看完整页入口固定，记录区域单独滚动。切换标签、隐藏右侧或更换所属插件时停止订阅；完整日志文档使用自己的筛选与订阅。插件扩展面板的输入与释放规则见面板。
整理文档
中央标签支持原生拖动、分屏、调整尺寸、最大化、固定与分组；插件面板仅在各自边栏内排序。 标签右键菜单可改名、分组、复制、移动和关闭。标签组只整理已打开文档，与插件目录分组无关。 固定标签移到容器固定区，取消固定不会自动返回原组。
关闭操作有明确范围：
- “关闭可见且可关闭标签”“关闭其他可见标签”“关闭右侧可见标签”只处理当前标签栏可见候选，不包含折叠组成员。
- 关闭整个容器会检查折叠组成员；固定、不可关闭标签及受保护分组会保留，容器可能因此继续存在。
- “关闭分组内全部标签”“关闭所有文档”和恢复默认布局要求先解除目标的固定或关闭保护。
未保存输入会请求处理；取消或保存失败保留文档。批量删除被守卫拒绝时保留全部目标，已完成的业务保存不会回滚。
保存和恢复布局
当前布局存储使用第 7 版，新面板结构从默认布局开始；旧版布局数据仍保留，插件配置和分组数据不受影响。
工作区菜单提供恢复默认布局。布局保存标签、分组、尺寸、地址、入口栏显示模式和导航视图，不保存未提交表单草稿。 窄窗口首次默认收起左侧，之后尊重已保存布局；可使用标签溢出菜单、边栏按钮和最大化找回内容。
布局恢复失败时可重试或显式重置；原布局在重置前保留。存储失败不阻止继续使用，但本次布局变化可能无法在下次打开时恢复。 恢复默认布局不修改插件分组或业务配置。
键盘操作
Mod 表示 Windows/Linux 的 Ctrl 或 macOS 的 ⌘。顶部工作区菜单也提供“键盘操作”帮助。
| 按键 | 操作 |
|---|---|
Mod+P | 查找页面、插件入口和当前插件面板 |
Mod+B | 显示或收起左侧边栏 |
Mod+W | 关闭活动文档，遵守固定和未保存保护 |
Mod+Shift+[ / Mod+Shift+] | 按原生布局顺序切换上一个或下一个文档 |
Mod+Shift+M | 最大化或还原活动文档所在的中央容器 |
Shift+F10 / 菜单键 | 打开所聚焦标签、分组或容器的菜单 |
F2 | 重命名所聚焦标签 |
Ctrl+Delete | 关闭所聚焦标签 |
F6 | 在所选标签和内容间切换焦点 |
Ctrl+F6 / Ctrl+Shift+F6 | 聚焦下一个或上一个标签容器 |
工作区命令在文本输入和菜单打开时暂停；查找入口可在输入时使用。原生标签和菜单保留自己的箭头键、确认与退出操作。
配置页面的 Mod+S 保存当前配置，Mod+Shift+S 保存当前插件的全部脏配置；保存结果由业务 API 决定。
内置依赖管理
插件概览用同一张「依赖管理」卡片展示必须依赖、可选集成、提供的能力和被依赖关系。依赖抽象能力时，
依赖行同时显示需求与实际实现，例如 Cache → CachePlugin。
- 当前插件使用：只设置当前插件的这条必须依赖。具体插件的「默认实例」使用该插件的默认节点； 抽象能力的「跟随全局默认」使用该能力的全局默认实现。手动指定实现或 Fork 后，显示「当前插件指定」。
- 提供的能力 / 全局默认实现：设置该抽象能力的默认提供者，影响所有未单独指定实现的消费者。 当前插件就是该默认实现时，显示「全局默认提供者」。
单独指定的实现优先于默认选择；恢复默认会移除当前插件的覆盖。修改依赖可能重启受影响的插件及其下游。 修改后，工作台刷新依赖图和已打开的依赖编辑器，未打开的编辑器在下次打开时读取最新设置。
内置 Plugin 目录诊断
目录行以名称为主，小圆点表示运行状态，小菱形表示更新类别，异常保留警告图标。提示可通过悬浮或键盘聚焦查看。 插件详情提供来源和可复制的插件引用；需要排错时展开“调试信息”，查看执行方式、启动策略、制品和最近更新。 “复制诊断信息”汇总引用、状态、执行与更新事实，不包含本机绝对路径或安装目录。
顶部更新指示器展示最新批次，点击查看阶段、触发文件、原因摘要和可用的导入链。失败的新插件即使尚未进入目录，也可在这里找到原因。
判断问题时区分三件事：
- 当前状态：插件现在是否运行，以及当前阻塞它的配置或依赖问题。
- 本插件上次更新：历史生命周期结果；已修复的问题不会改写历史，不同 fork 分别记录。
- 所属更新批次：整体更新结果。批次已提交时，仍可能有部分插件启动或清理失败。
“未报告生命周期”不代表启动成功。提交前失败会说明保留旧定义；应用重载失败后恢复成功，会说明使用上一应用定义恢复。 “目录 HMR”“入口 HMR”“源码 HMR”说明实际监听范围；“未报告”表示缺少相应事实，不能据此判断插件已停止。
目录搜索的多个 token 使用 AND：
- 普通关键词：名称、定义位置、导出名、插件引用和执行信息；
@包名：只匹配包名；ref:关键词：只匹配插件引用；exec:关键词：只匹配制品、更新方式和最近结果，例如hmr、next-start、bundle、restored-previous或“失败”。
开发自定义客户端时，管理入口和快照契约见 Management，更新订阅和批次字段的实现约束见工程文档中的更新状态。
生命周期和故障
普通导航只切换当前文档。单个页面渲染失败时，该文档显示错误与“重试”，其他文档仍可使用。 插件停止、替换或发布更新可能使工作台会话失效并触发完整刷新；认证失效时需重新登录。完整刷新不会保存未提交草稿。 页面关闭或刷新也不表示已提交的业务操作被撤销，重试写入前先确认结果。
开发时，自定义页面可以先显示“构建中”；失败后原位置保留错误，修复源码并保存后会再次构建。 定义文件删除后重新创建也可触发更新。插件初始化因更新失败后，有效更新会恢复仍需运行的插件及其依赖方；手动停止的插件保持停止。 具体恢复流程见 HMR 失败与自动恢复。
启停命令被接受不等于插件已经达到目标状态。操作后查看当前状态和生命周期问题；若提示“运行状态仍未收敛”，继续检查依赖和日志。 页面作者需要处理订阅、待完成请求或取消时，参见页面资源清理。
Vite 与反向代理
开发时 Workbench 使用现有 Vite 端口，无需另外启动服务或配置代理。
生产反向代理只需保留同源路径并正确转发 WebSocket Upgrade：Workbench document、/__pluxel/ HTTP endpoints、MF assets
和 /__pluxel/runtime/session 应到达同一个 Runtime deployment。Runtime 不相信 Forwarded / X-Forwarded-* 推断
physical TLS 或 locality。内建 production Node launcher 只监听 HTTP，因此默认只通过 loopback/SSH tunnel 管理，不通过普通
TLS 反代开放 remote Management，反代也不应从 loopback 地址回源。需要 remote Management 的平台集成必须提供自身能证明
HTTPS 的 application carrier。多实例部署还需要让 control socket、OIDC callback 和短期 cookie ticket 命中签发它们的实例。
插件详情与内容目录
中央文档编辑配置，右侧“插件信息”查看状态与依赖，“最近日志”查看最近 10 条记录。点击“查看完整日志”会显式打开独立日志标签，
并按当前插件的 canonical reference 筛选，包括 fork；原配置文档保留。完整日志页地址使用 /logs?plugin=…，
切换其他插件不会改变已打开日志文档的筛选，可用“清除插件筛选”返回全局日志。普通目录入口仍在当前标签导航，查看完整日志是明确的并行排查操作。
完整日志默认使用全部可用宽度，筛选按需展开；修改日志流、名称、上下文或分类后点击“应用筛选”，条件写入当前文档地址，刷新和复制可保留。 “清除附加筛选”保留当前插件，“清除插件筛选”保留其他条件。暂停跟随不会停止收集，返回最新可继续阅读；“清空显示”仅清空当前页面缓存，不删除服务端日志。 选择一条日志可在下方查看完整消息、错误及属性，并复制文本或 JSON。
右侧“最近日志”标题后和完整插件日志页标题后提供相同的日志级别入口，显示有效级别与继承情况；可调整当前插件覆盖、全局默认和已有规则。 修改全局默认会影响未单独覆盖的插件。
配置字段上方的“配置目录”默认折叠，展开后可搜索和跳转。Markdown 标题也可通过内容目录定位。 目录只对应当前文档；没有目录项时不显示空面板。未保存配置的离开和关闭行为见整理文档。
最后更新于