tacbench-ui-workbench-spec-writer

name	tacbench-ui-workbench-spec-writer
description	Specify Tacbench's IDE-style GUI. Use when designing or refining the workbench layout, panel responsibilities, inspector behavior, diagnostics flows, layout presets, or reusable UI conventions for Tacbench.

Tacbench UI Workbench Spec Writer

适用于 Tacbench 的 IDE 式 GUI 规范编写。

Use this skill when

• 要设计或调整 workbench 布局。
• 要新增 explorer、inspector、tabs、diagnostics、layout preset 等交互。
• 要统一组件职责、页面结构和设计系统约束。
• 要避免页面各做各的、风格漂移或状态流散乱。

Read first

• Tacbench V1 plan
• Workbench ADR
• AGENTS.md
• ../../../packages/workbench/src/
• ../../../packages/ui-kit/src/
• ../../../packages/theme-tokens/src/

GUI rules

• V1 固定是单主窗口 + 内部多面板工作台。
• 有工作区时固定采用 IDE 壳：左侧 explorer，中间 tab 工作区，右侧 inspector，底部 diagnostics / debug / terminal。
• 空工作台是特例：默认收起侧栏与底栏，只展示轻量欢迎页，不强撑完整 IDE chrome。
• 高级模式是二级入口，不取代基础模式。
• 问题、日志、发布检查统一往底部收口，不滥发 toast。
• 页面必须复用 ui-kit 与 design tokens，不允许临时拼另一套视觉。
• 当项目里已经有抽出的工作台骨架组件时，后续页面必须先复用这些骨架，再考虑新增样式；不要在页面里重新手搓一份近似结构。

资源编辑器工作台模板

当任务是 guns / ammo / attachments / blocks / gunpack 这类资源 GUI 编辑页时，默认使用统一的 资源编辑器模板：

• 顶部：资源标题、逻辑路径、状态摘要、保存状态。
• 主区 / 主视窗：当前主任务的核心字段 section。
• 右栏 / detail pane：复杂结构、集合、曲线、声音、配方、脚本参数、扩展表现字段或补充源码。
• 底栏：问题 / 输出 / 调试 / 终端 四条独立职责链；数据语法 优先表示当前激活文件的问题列表。

面板职责锁定

• 主区 承载当前主任务，不承载“顺手塞进去的所有字段”。
• 右栏 承载 drill-down 和补充上下文，不抢主任务源码。
• 主任务源码 默认进入主区。
• 补充源码 才适合进入右栏。
• 如果主区入口已经通过勾选控制某个结构块是否启用，右栏不要重复再放一个总开关；右栏默认只负责编辑该结构内部字段。
• 只有明确的 bundle / resource 导航才打开资源 GUI 页；源码导航不要先偷开 GUI 页。

资源编辑页分层模板

• 主区：资源概览 + 核心字段 section。
• 右栏：复杂对象/集合/曲线/声音/配方/脚本参数等专用编辑体。
• 源码：主区优先承载直接源码任务，右栏仅承载补充源码。
• 页面内部禁止再复制一套局部侧栏、workbench slogan、实施说明卡或提示词卡。
• 当 ammo 对齐 guns 母版时，以 AK47 -> tacz:762x39 作为字段覆盖与视觉一致性的基准样本。
• 当 gunpack 对齐工作台模板时，以 Minecraft/tacz/tacz_default_gun/gunpack.meta.json 与 assets/tacz/gunpack_info.json 作为字段与说明真源。

输入控件与保存策略

• 资源引用统一优先 可输入 + 搜索 + 选择。
• tag/列表字段的添加入口统一是尾部小按钮，不回退满宽入口条。
• 数值密集对象优先响应式双栏；长文本、JSON、脚本优先单列。
• 默认采用 本地草稿 + 显式保存 + 显式重置。
• 主区与右栏共享同一资源级 dirty 语义与 flush/discard 节奏。
• 如果项目里已经存在可复用的顶部头壳、资源引用字段壳、section 内容壳，迁移页面时先抽共用件再铺页面，避免继续重复造轮子。

轻页面例外条件

只有同时满足下面条件的资源，才允许继续保留轻页面：

• 字段很少。
• 没有复杂结构、集合、粒子/声音/脚本等扩展块。
• 不需要右栏 drill-down。
• 不需要独立保存语义。

ammo 已不满足轻页面条件，后续默认按同壳适配版工作台实现。

Current demo replication discipline

当用户提供 docs/demo/*.html 作为 UI 基线时，默认遵守：

1. 先复刻信息层级，再做功能扩展；不要先“自由发挥”。
2. 不新增在线字体/CDN 脚本；只用仓库现有图标、token、组件体系。
3. 可用能力必须接真数据链；未接通项必须显式标记“骨架预留/暂不可用”。
4. UI 不允许“工程味堆叠”：优先单层、紧凑、可读，避免重复状态卡/控制条。
5. 当前资源入口排序默认以 枪包 -> 枪械 -> 弹药 -> 配件 -> 资产 为先，枪包入口放在第一位。

Current visual editor hard rules

当任务涉及 guns 可视化编辑区、字段独立编辑 tab、主视窗 section 或右栏细节编辑时，优先把下面这些规则当成当前用户锁定约束：

同时要把 guns 视为“当前资源编辑器母版”：

• 它定义了壳层分工、诊断跳转优先级、手动保存模型和资源引用输入范式。
• 它不定义其他资源页必须照搬的字段顺序与字段分组。

真源与参考

1. docs/demo/可视化区域.html 是当前视觉与结构参考，不要“理解后再发挥”。
2. data/tacz/data/guns/ak47_data.json 是字段覆盖与语义参考；不仅要看当前启用字段，也要看被注释掉的可选字段。
3. 如果 demo 和现有组件冲突，优先保留 demo 的结构节奏，同时接通仓库真实数据链。

主视窗规则

1. 主视窗顶部导航优先服务“内容 section 跳转”，不要再把源码分类入口占用主导航位。
2. 本地化 区域不应内置写死“中文/英文”两个输入框；应展示“当前选中语言”的内容，并跟语言切换状态联动。
3. 绑定弹药 (ammo) 这类短值字段不应霸占整行，优先用更紧凑的布局。
4. 资源引用类字段默认是“可输入 + 可检索 + 可选择”的 combobox，不是纯下拉。
5. extended_mag_ammo_amount 必须按扩容等级完整展示，例如 1级扩容 / 2级扩容 / 3级扩容，不要擅自截断成两项。
6. bolt 要用明确选项展示：
   • open_bolt = 开膛待机
   • closed_bolt = 闭膛待击
   • manual_action = 手动上膛
7. fire_mode、allow_attachment_types、各类 tag/列表字段的“添加”入口必须是跟随在现有 tag 尾部的小按钮/小触发器，不能吃满整行。
8. display / 表现层与双机 区域里的资源引用同样要支持搜索式选择，不允许退回成纯手选下拉。
9. 布局必须对窄宽度自适应：
   • 文本不能溢出卡片
   • 需要时主动换行或裁断
   • 栅格在宽度不足时要自动切栏，不能固定死列数把内容挤爆

独立编辑 tab 规则

1. 用户点击复杂字段后打开的是“独立编辑 tab 内容区”，当前任务默认只改这一层，不要误改主视窗或右栏头壳。
2. reload、display.sounds、recipe.materials、burst_data 等独立 tab 必须按 demo 重做成高密度 IDE 编辑体，不允许在旧表格/旧卡片样式上继续叠补丁。
3. 一旦重做某个独立 tab，旧版本对应结构要清掉，不要新旧样式并存。
4. builtin_attachments、script_param 等点开后不允许空白：
   • 至少要展示真实字段
   • script_param 要直接承接脚本参数原始字段，不要空壳
5. curve、key-value、structured object 这几类独立编辑体都应贴近 demo 的密度和块状结构，不要回到网页后台表格观感。

字段覆盖规则

1. guns 编辑器不能只覆盖当前样例枪支正在用的字段。
2. 注释掉的字段如果代表“该武器暂未启用但 schema 支持”，也要被纳入 GUI 的能力清单或高级可选区。
3. 字段缺省时至少要做到二选一：
   • GUI 提供可启用/可配置入口
   • 明确标注这是预留/高级字段，并解释用途
4. 字段说明文案不是可有可无；对于复杂字段，需要说明“这个字段是干什么的”。

当前实现方式偏好

1. 优先“专用编辑体”而不是无限扩张的通用表单。
2. 高频复杂字段优先单独组件化，例如：
   • reload
   • burst_data
   • script_param
   • builtin_attachments
   • display.sounds
   • recipe.materials
3. 对资源引用类控件，优先沉淀成统一可搜索 combobox，供主视窗与独立 tab 共用。

Current settings-shell hard rules

当任务是“设置页模板迁移/复刻”时，必须优先遵守：

1. 不改宿主 IDE 外壳：AppHeader / 最左 ActivityBar / StatusBar 由主壳统一管理。
2. 设置页只改内容区内部：左分类导航 + 右侧设置表单流，不重复渲染第二套最左导航。
3. App.vue 只做视图路由与事件透传，不新增设置业务计算。
4. AppSettingsEditor 是设置内容壳，负责内部导航、搜索、分组与行级控件。
5. 快捷键设置默认“功能保留 + 样式压缩”：可编辑、可清空、可冲突提示，同时保持简洁布局。
6. 如果用户明确要求“仅内部样式变更”，禁止切换为“独立全壳替换”方案。

Current settings UI language rules

当任务涉及 AppSettingsEditor、设置页局部排版或工作区/存储设置区时，必须优先遵守：

1. 设置页继续沿用当前 行级设置项 + 右侧控件列 + 少量列表容器 的 UI 语言，不要再单独发明一套高对比卡片背景系统。
2. 如果某块只是为了整理信息层级：
   • 优先用现有 settings-row、分组、分隔线、紧凑 grid
   • 不要默认加新的深色背景卡、渐变卡、营销式摘要卡
3. 视觉复用优先级固定为：
   • 先复用设置页现有样式类
   • 再抽共用 settings 子骨架
   • 最后才允许新增新样式
4. 当用户要求“把某个标签/状态块移动到别处”时，默认理解为“搬已有 UI 元素”，不是“在目标区域再补一份说明卡”。
5. Storage Root 区域当前已锁定：
   • 默认目录文案统一按 tacbench/data
   • “当前模式 / 存储状态”位于右侧动作区下方
   • 顶部不要再重复放这两个状态块
   • 该区域应和其他设置项保持同一家族的平面化样式，而不是独立卡片主题

Current performance UX rules

1. 大型 explorer、文件树、问题面板、日志面板默认按“未来要虚拟化”设计结构，不要继续强化全量渲染依赖。
2. 空工作台欢迎页不能触发重扫描、重缩略图流水线或不必要的编辑器装载。
3. 调试信息默认精简；详细日志关闭时，不要让底部面板被普通 console 噪音刷爆。
4. 欢迎页、最近工作区树、问题列表这类长内容区域，必须明确谁内部滚动，不能靠整页一起顶高。
5. 欢迎页 logo / hero 图必须使用首屏优化资源：
   • 不要直接挂原始宣传大图
   • 优先使用已压缩的本地资产
   • 首屏图默认显式 eager/high priority，避免出现“图像先糊一半再慢慢出来”的网页式加载感

Current workbench recovery rules

当用户反馈 desktop workbench 的布局、分栏或字段编辑行为错乱时，先按下面的硬规则检查，不要继续做局部补丁：

1. 主工作台优先用稳定的 flex 布局做 single / dual / triple，不要把 splitpanes 当主布局真源。
2. guns 的默认交互必须是 Master / Detail：
   • 左栏只放 gui-bundle
   • 右栏只放 gui-field-editor 或 source-document
   • 点击复杂字段编辑时，默认进入右栏
3. 双栏默认是 50 / 50，右栏必须贴到最右边，不能出现空 pane 或 phantom group。
4. 右栏 Visual 模式只保留结构化字段编辑器；不要再塞大块“字段上下文 / 所属文档 / 路由卡片”。
5. 右栏 Data 模式直接展示 Monaco，并高亮当前字段对应的 JSONC/Lua 片段；不要额外再包一层“Monaco source editor”标题卡。
6. 主壳、pane、代码视图默认去圆角，避免 pane 吸附时留下圆角缝。

Current runtime bug checklist

当用户提到“点一下就崩”“右栏没贴边”“又跑回同组 tab”，优先检查这些点：

• apps/desktop/src/App.vue
  • 是否还在主布局里使用 Splitpanes/Pane
  • 是否还会渲染空的 editor group
  • 字段编辑是否真的强制进入右侧 detail group
• apps/desktop/src/desktop-client.ts
  • 不要把图片文件路径直接传给 setIcon，否则会出现 expected RGBA image data, found a file path
• apps/desktop/src/components/GunFieldEditorView.vue
  • 右栏 Visual 模式必须是主编辑优先，不要把说明卡挤在右侧
• apps/desktop/src/components/SourceDocumentEditor.vue
  • 右栏 Data 模式应让 Monaco 贴边占满
• packages/ui-kit/src/MonacoCodeEditor.vue
  • 保持字段代码片段高亮能力

Current debugability hard rules

当任务涉及“以后怎么更快查 workbench bug”时，默认把可调试性视为正式 GUI 规范的一部分：

1. 开启 详细工作台日志 (Verbose Logging) 后，工作台必须持续记录：
   • 当前 view / 当前 bundle / 当前 active tab
   • group layout / group membership / active group
   • explorer collapsed / mode / width
   • detail pane width / output panel open / height
   • right drawer open / panelKind
   • diagnostics state / count / stale state
   • background activity / uiPhase / interactionLocked
2. 这些状态快照应进入 调试 (Debug) 面板语义，不要混回 问题 或普通 输出。
3. GUI 状态日志必须是“可复盘”的，不要只打一条“切换成功”；至少要能看出切换前后承载了什么面板和 tab。
4. 如果一个 UI 功能可能改变壳层结构，就必须让 verbose logs 能还原这次变化；否则默认视为 bug 排查基础设施不合格。
5. 不要把可调试性只做成临时命令或开发者私有知识；应把它固化成：
   • 独立 logging service
   • 稳定的 code / stage / snapshot 约定
   • skills 中可复用的实施规则
6. 调试 (Debug) 面板要保留一键“导出快照”入口；它是正式排障通道，不是开发期临时按钮。
7. 桌面版不要继续挂浏览器式 beforeunload 提示；设置草稿状态应在工作台内表达，不靠系统弹窗打断 reload/热更新。

Current homepage / workspace-shell hard rules

当任务涉及首页空页、最近工作区、工作区加载反馈或 IDE 壳体验时，先按这些硬规则检查：

1. 软件启动只拉起空壳，不在 splash 或初始化阶段强绑扫描本地 tacz/ 工作区。
2. 当“没有工作区且没有打开 tab”时，默认：
   • explorer 收起
   • 底部输出 / 问题 / 调试 / 终端面板收起
   • 中央只保留欢迎页
3. 欢迎页主视觉和右侧操作列应处于同一垂直节奏：
   • 左侧主视觉块垂直居中
   • 右侧操作列整体视觉上居中，不要硬顶到最上方
   • 右列内容过长时只允许右列内部滚动
4. 首页“最近打开”必须按 工作区根目录 -> 子枪包 做树形展示：
   • 顶层是父工作区

Current recent-workspace open rules

当任务涉及 splash / 最近工作区树 / 子枪包快速打开时，继续锁定这些规则：

1. 从“最近打开”点击父工作区时，允许恢复父工作区上下文。
2. 从“最近打开”点击子枪包时，如果交互意图是 single-pack，就必须真的以子枪包路径作为当前工作区作用域：
   • 不要在前台只短暂显示子枪包，然后后台再把整个父工作区并回来。
   • 不要用父工作区的 legacy cache / legacy session 覆盖子枪包当前作用域。
3. single-pack 打开后的项目图只应包含当前子枪包；其余 pack 只能显式再打开，不能偷偷后台补齐。
4. 工作区切换期间，右下角状态条必须跟随前台加载与 UI 同步阶段：
   • workspace.loadState
   • workspaceUiPhase
   • 背景索引状态 三者至少显示其一，不允许“正在卡加载但右下角没反馈”。
   • 左侧箭头只负责展开/折叠
   • 点击父项加载整个工作区
   • 点击子项加载整个工作区并聚焦对应子枪包
5. 最近工作区树默认透明底和轻 hover，高度受限并内部滚动；不要擅自改成大块黑卡片。
6. 首页和软件设置页的最近工作区组件必须共用同一套交互，不允许一边有箭头一边没有。
7. 工作区加载期间必须有明确的壳内 loading 态，并锁住重复打开入口；不能让用户反复点击又没有反馈。
8. 加载失败不能静默消失，必须同时给出：
   • 可见错误文案
   • 底部输出 / debug console 日志
9. 如果用户选择的是 tacz 里的某个子枪包目录，UI 行为必须自动提升到父工作区，而不是闪一下就没了。

Current diagnostics / debug visibility rules

当用户反馈“点了没反应”“闪一下就没了”“没有报错”时，不允许只修行为链，必须同时补全可见调试出口：

1. 底部输出面板是第一调试出口，工作区加载错误和关键阶段日志必须能看到。
2. 关键失败路径至少要记录：
   • 选择了什么路径
   • 被解析成什么工作区选择结果
   • 当前卡在什么阶段
   • 失败原因
3. 问题 / 输出 / 调试 / 终端 是四条不同职责链：
   • 问题 只放可行动诊断
   • 输出 只放工作流状态
   • 调试 只放 F12 / Vue / Window / native 调试事件
   • 终端 只放 shell transcript
4. 对 IDE 风格工作台，静默失败视为功能未完成；没有 debug 可见性就不算修完。

Current problems panel / file-diagnostics rules

当任务涉及底部 问题 (Problems)、单条诊断跳转、当前文件错误定位时，必须优先遵守：

1. Problems 和 数据语法 不是一回事：
   • Problems 保持全局问题入口
   • 数据语法 优先表示“当前激活文件的问题列表”
2. 当前文件问题列表必须只收：
   • 当前文件命中的 syntaxDiagnostics
   • 命中同一路径的 resourceDiagnostics
3. 点击当前文件问题项后，编辑器要立即聚焦并高亮对应位置；不能只改右侧详情抽屉状态。
4. 双击诊断的默认动作必须跟随当前左侧侧栏模式：
   • files 模式优先跳源码
   • resources 模式优先跳资源 / 库定位
   • 导航失败时再自动降级
5. source 导航默认应进入主视窗，不要再默认塞进右栏 detail pane。
6. bundle 导航才允许默认打开资源 GUI 页面；不要在源码导航前先偷偷开一个 gui-bundle。

资源页迁移顺序

当任务是“把成熟编辑页辐射到其他页面”时，默认顺序固定为：

1. 固化 guns 母版规则。
2. ammo 作为第一优先同壳适配版。
3. attachments / blocks 套用同一壳层模板。
4. 其他资源页按复杂度继续迁移。

不要每做一个新资源页就重新发明主副视窗和保存模型。

Current diagnostics drawer rules

当任务涉及“数据诊断 / 发布前检查 / 单条诊断详情”时，必须优先遵守这些边界：

1. 数据诊断中心、打包发布流程、单条诊断详情 是三条独立右侧抽屉链，禁止再共用同一个抽屉身份。
2. 顶部 数据诊断 入口只负责打开诊断中心，不允许点一下就自动开跑。
3. 诊断中心必须先让用户显式选择范围：
   • 当前枪包
   • 指定枪包
   • 整个工作区 然后再点 开始诊断。
4. 打包发布 必须是独立流程，不是“换标题的数据诊断”：
   • 第一步选枪包
   • 第二步手动跑发布前检查
   • 第三步发布参数 / 确认
5. 发布流程里的检查范围固定绑定“本次待发布枪包”，不要提供“整个工作区发布检查”来稀释语义。
6. 单条诊断详情只展示一个问题和它的定位 / 修复动作，不允许再夹带全局诊断摘要卡。
7. 从诊断中心或发布前检查列表进入单条详情时，顶部必须有明确返回按钮，并恢复到原列表和原筛选，而不是回默认页。
8. 诊断结果允许保留上一份，但当范围改变时必须明确标注“结果已过期，需要重新诊断”，不能假装它还是当前结果。

Completion bar for workspace UX tasks

以下任务如果只做了一半，不算完成，不要提前切到别的子问题：

• 最近工作区树形分组
• 子枪包目录提升到父工作区
• 工作区加载反馈与锁定
• 输出 / debug console 可见性
• 首页空页与设置页的一致交互

验收时至少要同时满足：

1. 用户能从首页看见父工作区与可展开子枪包。
2. 点父项和点子项都能成功打开。
3. 失败时不会静默，只会在输出里留下可见日志。
4. 样式不偏离既定 IDE / Explorer 语气。

Current workbench shell defaults

当需求涉及工作台默认打开状态、用户第一眼体验或空页布局时，优先遵守这些默认值：

1. 默认启动页不是“展开但空的 IDE 栅格”，而是“轻量欢迎页”。
2. 只有在打开工作区、恢复会话或显式打开面板后，才展示完整 explorer / editor / bottom panel 组合。
3. 右侧欢迎信息列要有明确 max-width，不能无限拉长。
4. 中央主视觉和右侧欢迎列之间的分割线只作为节奏线，不应把右列推到顶部。

Current known regression signatures

如果看到下面这些报错，优先修主因，不要继续给 UI 打补丁：

• expected RGBA image data, found a file path
• splitpanes.es.js ... Cannot read properties of undefined (reading 'index')
• 字段编辑 tab 打开后回到主组，而不是右侧 detail 组
• 双栏时右侧 pane 没贴边，或出现大块空白

Debug workflow

1. 先看运行时错误和当前 DOM/布局，不要先调样式。
2. 先修分组和布局真源，再修视觉。
3. 先保证：
   • 不崩
   • 左主右详
   • 双栏 50/50
   • 右栏贴边
4. 再处理细节视觉，比如按钮、标题、圆角、状态栏高度。

Current storage-root UX rules

当需求涉及“软件安装在哪、数据根放在哪、系统盘提醒怎么做、设置页如何迁移数据根”时，默认按这些 UX 规则执行：

1. 启动时若数据根位于系统盘，必须通过右下角通知提醒，而不是只留在设置页。
2. 该通知应支持直接动作，至少包括：
   • 去设置迁移
   • 打开当前数据目录
   • 打开软件根目录
3. 设置页里的“全局存储路径”不能只是输入框；它必须展示：
   • 当前软件根目录
   • 当前数据根目录
   • 当前模式（安装版 / 便携版）
   • 推荐迁移路径
   • 打开目录动作
   • 并且默认按 tacbench/data 语义组织文案与推荐路径，不要再漂成 TacBench Data 或别的独立命名
4. 当软件根不在 C: 但数据根在 C: 时，优先推荐迁到软件所在盘的专用目录，而不是继续推荐系统默认目录。
5. 存储迁移是正式工作流，必须保留草稿/保存语义，不允许因为“快速实现”退回即时写入。

Output expectations

• 说明每个面板做什么，不做什么。
• 说明布局预设、焦点模式、键盘流和 dirty state 行为。
• 指出需要新增哪些复用组件或 workbench 能力。
• 如果要实现页面，先给结构与状态流，再给代码任务顺序。