tacbench-editor-architecture-planner

name	tacbench-editor-architecture-planner
description	Plan Tacbench architecture and execution work. Use when deciding repo structure, module boundaries, desktop versus web layering, ADRs, implementation phases, or how new features should fit the Tacbench workbench-first architecture.

Tacbench Editor Architecture Planner

适用于 Tacbench 的架构规划和任务拆解。

Use this skill when

• 要新增模块、页面或底层能力。
• 要检查 desktop/web/core 分层是否被破坏。
• 要输出 ADR、实施计划、任务拆分或边界约束。
• 要评审“这个功能该放在 Rust、共享 TypeScript、模块插件还是 UI 壳”。

Read first

• AGENTS.md
• Tacbench V1 plan
• Workbench ADR

Decision rules

• 共享 TypeScript 领域层是业务真源。
• Rust 只做原生能力、文件系统、watch、IPC、压缩包和性能敏感工作。
• apps/desktop 与未来 apps/web 必须能共享 workbench、领域逻辑和验证逻辑。
• gun 是内建一方模块，melee 只能按插件模块接入。
• 新需求默认优先接入 packages/*，不要直接堆到应用壳里。
• 优先使用成熟现成库或官方插件；只有现成方案缺能力或会破坏边界时，才补最小自定义桥。

Current settings architecture rules

当需求涉及“设置页/偏好体系/设置模板迁移”时，优先按这些边界执行：

1. packages/core 维护偏好类型、默认值、normalize/migration 真源。
2. apps/desktop/src/stores/app-preferences.ts 维护持久化与更新流程。
3. apps/desktop/src/App.vue 只负责设置页视图切换与事件透传，不承载设置业务逻辑。
4. apps/desktop/src/components/AppSettingsEditor.vue 负责设置内容区 UI 编排。
5. 若用户要求“仅改设置内容区样式”，禁止改动宿主最左 ActivityBar/顶部/底部壳层。

Current implementation preference (user locked)

近期用户已锁定这些偏好，规划与实现默认按此执行：

1. Demo-first：优先复刻 docs/demo/*.html 的层级与节奏。
2. Minimal-adaptation：只有现有数据链承载不了时才做最小适配。
3. No shell duplication：禁止在现有 IDE 壳内再叠一套完整外壳。
4. End-to-end closure：每次改动都要说明“已接通能力/预留能力/验证结果”。

Current gun visual editor architecture rules

当任务涉及 guns 主视窗、字段独立编辑 tab、schema 覆盖和字段写回能力时，默认按下面的结构规划，不要再只做局部 UI 打补丁：

1. docs/demo/可视化区域.html 决定独立编辑 tab 的结构参考；data/tacz/data/guns/ak47_data.json 决定字段覆盖参考。
2. 主视窗和独立编辑 tab 是两层不同职责：
   • 主视窗负责 section 化浏览与常用字段
   • 独立编辑 tab 负责复杂对象的高密度 IDE 编辑体
3. 不要再把“复杂对象编辑”压回通用 StructuredObjectEditor 兜底；高频复杂字段应优先演进为专用 editor 组件。
4. 本地化能力的真源应来自当前语言切换状态，而不是组件内部写死 zh_cn / en_us。
5. 资源引用字段（弹药、表现层资源、附件、配方材料等）架构上应统一走“可搜索输入 + 候选选择”的共享控件，不要每个页面各写一套 select。
6. 字段覆盖范围不能只依赖当前枪支实际启用字段；架构上应允许把“注释掉但 schema 支持”的字段纳入可选能力。
7. 说明文案属于编辑器能力的一部分，不是装饰；规划 GUI 时要给复杂字段预留用途说明位置。
8. 对独立编辑 tab，一旦新样式接管某个字段，旧表格/旧卡片实现应视为迁移目标，而不是长期双存。

Current performance planning rules

当需求涉及“卡顿”“启动慢”“树很大时掉帧”“工作台像 IDE 但不顺”时，优先按下面这些架构规则规划，不要直接先改样式或打零散补丁：

1. 大列表不是普通组件问题，而是架构问题：
   • explorer
   • 文件树
   • 问题 / 输出 / 调试
   • 终端 transcript 都应优先规划虚拟化或窗口化，不允许默认全量 v-for 当最终解法。
2. 主线程只负责交互和轻量状态合成；重任务应优先放到：
   • Rust / Tauri
   • worker
   • 异步批处理 不要把整包校验、整树拍平、整项目诊断排序长期放在 Vue computed 里做真源。
3. 编辑器和重组件必须按需加载：
   • Monaco
   • 复杂 visual editor
   • 缩略图或预览流水线 不应在空工作台首屏一次性全吞。
4. 诊断与日志必须分流：
   • 问题 = 可行动诊断
   • 输出 = 工作流状态
   • 调试 = F12 / Vue / Window / native 调试流
   • 终端 = shell transcript 规划时不要再把这些重新混成一份通用日志数组。
5. 空工作台默认应是轻壳，不要在软件启动时自动把 explorer、bottom panel、工作区扫描和重建流程全拉起来。

Planning workflow

1. 先判断问题属于产品边界、领域模型、文件适配、验证体系、模块系统还是 GUI。
2. 指定改动应落在哪些目录，并说明为什么不放在别处。
3. 给出风险、依赖和验证方式。
4. 如果是大改，先写 ADR 或计划文档，再进入实现。
5. 输出实施顺序时，优先保证 core -> validation -> module -> ui/workbench -> app shell 的层次。

Current workspace-session planning rules

当需求涉及工作区打开、最近打开、缓存、会话恢复或 desktop/web 壳协同时，优先按这些边界规划：

1. 共享 TypeScript 决定“路径被解析成工作区根还是子枪包焦点”，应用壳只消费结果，不在页面层各自猜规则。
2. Rust / desktop-client 负责偏好、会话、缓存文件的持久化，不负责业务判定。
3. workspace store 负责：
   • 加载状态
   • 会话恢复
   • 缓存命中 / 回退
   • 运行日志
4. 首页和设置页只是入口，不应该各自维护一套最近工作区数据结构。
5. “缓存做完”的验收标准不是有代码就算，而是：
   • 数据目录里真的写出了缓存文件
   • 第二次打开同一工作区时能证明命中缓存
   • 前台不会因为缓存落盘卡在 100%
6. 子枪包目录选择不是错误场景，而是正式支持的入口；架构上必须提升到父工作区加载，不允许继续把子枪包当独立工作区真源。

Current diagnostics / terminal architecture rules

当规划调试工作台、终端、编码扫描或 native bridge 时，优先按这些边界判断：

1. packages/core 真源应定义：
   • DiagnosticRecord
   • OutputEvent
   • DebugEvent
   • WorkspaceEncodingObservation
   • terminal 共享类型
2. apps/desktop/src/desktop-client.ts 只负责包裹官方能力，不把插件 API 直接暴露给组件。
3. debug-bridge 负责前端 / native 采集，不把监听逻辑堆回 App.vue。
4. terminal 是独立工作台能力，不属于 输出 或 调试 子集；默认按工作区级单 session 规划，除非任务明确要求多 session。
5. 编码探测属于工作区级诊断输入，不应混成文件编辑器里的零散提示。

Current verbose logging architecture rules

当任务涉及“详细工作台日志 (Verbose Logging)”“调试模式”“想让 Codex 更快查 UI / 状态 bug”时，默认按这些边界执行：

1. workspace.logRuntimeEvent(...) 记录功能层与工作流层日志：
   • 工作区加载
   • 会话恢复
   • 缓存命中 / 回退
   • 文件操作
   • 诊断 / 发布工作流
2. workspace.logDebugEvent(...) 记录 GUI / 宿主 / 桥接 / 运行时诊断：
   • console / window / vue / native 捕获
   • 布局状态
   • 当前 tab / group / drawer / output panel
   • diagnostics state / background activity
3. console、window、Vue error、native log 的镜像采集继续放在 debug-bridge，不要分散进页面组件。
4. Verbose Logging 下的 store / GUI 状态快照应放进独立 logging service，例如：
   • services/workbench-verbose-logging-service.ts 不要把一堆 watch 直接堆回 App.vue。
5. App.vue 只允许保留与当前组件强绑定、且无法离开 DOM ref 的极少数本地性能日志；凡是 store 状态、布局状态、工作流状态，都优先由 service 采集。
6. 新增一条工作台交互链路时，如果它可能导致“页面黑了 / 侧栏没了 / tab 跑错组 / drawer 状态错乱”，默认要补：
   • 功能层 runtime log
   • GUI 状态 debug log
   • 失败时可定位的上下文 snapshot
7. 详细日志的目标不是“记录更多废话”，而是让 Codex 能只看日志就还原：
   • 当前工作区
   • 当前 bundle / tab / group
   • 当前 explorer / drawer / output 状态
   • 当前 diagnostics / background task 状态
8. 如果某个新功能只在 App.vue 里藏状态、又没有进 verbose logs，视为架构不完整；后续排障成本会失控。
9. 一键导出调试快照属于调试基础设施，应优先复用独立 logging service 的 snapshot builder，不要在多个组件里各拼一份状态快照。
10. 桌面壳不是浏览器表单页；beforeunload 这类浏览器式未保存提示默认只允许留在纯 web 场景，Tauri desktop 禁止继续挂载。

Current diagnostics / release architecture rules

当规划诊断中心、发布检查或右侧抽屉状态时，优先按这些边界判断：

1. editor-shell 必须显式区分：
   • 诊断中心
   • 发布流程
   • 单条诊断详情 不要继续用一个 diagnostic panel 承载三种语义。
2. App.vue 可以编排抽屉切换和返回上下文，但诊断结果模型应是共享的、按范围键存储的，而不是每个抽屉各藏一份临时状态。
3. “范围选择”属于 UI 工作流状态，不应再退回只靠设置项决定真实扫描范围。
4. 单条详情的返回目标不是视觉细节，而是工作流状态；规划时必须把来源抽屉、筛选和目标范围一并考虑。
5. 发布流程默认是 选枪包 -> 发布前检查 -> 发布确认 三步，不要把发布管线和诊断管线混成一个页面块。

Current runtime storage / distribution rules

当需求涉及安装目录、portable 分发、缓存根、系统盘提醒或启动性能时，优先按这些边界规划：

1. TacBench 默认按 安装版 + 便携版 双模式规划：
   • 安装版：安装根只读，数据根可迁移
   • 便携版：exe 旁 data 承载偏好、缓存、索引与会话
   • 默认目录命名统一按 tacbench/data 语义，不再额外发明 TacBench Data 这种平行根名
2. 安装根不是缓存根；工作区缓存、会话、预览缓存、全局索引都必须进入数据根。
3. Rust / desktop-client 负责：
   • 软件根目录识别
   • 数据根识别
   • portable / install 模式识别
   • 数据根迁移
   • 打开软件根目录 / 数据目录
4. App.vue 不应继续直接承载存储根判定与迁移细节；这些逻辑应进入独立 runtime storage store / service。
5. 若数据根位于 C:，这是正式产品行为而不是调试提示：启动后必须提醒用户迁移，且优先推荐非系统盘。

Current frontend structure rules

当规划前端拆分、共用组件或页面迁移时，默认按这些结构边界执行：

1. 共享能力优先沉淀到：
   • stores/*：运行时状态与工作流状态
   • components/*：可复用 UI 骨架
   • src-tauri/src/lib.rs：原生目录识别、迁移、打开目录等宿主能力 不要把这三类职责重新混回 App.vue。
2. App.vue 现在仍是大壳，但后续新增能力必须优先放到独立 store / service / 子组件，不允许继续把新业务直接缝进根文件。
3. UI 复用优先级是“和现有页面长得一致”优先，不是“抽象层数更多”优先。
4. 对设置页、欢迎页、工作台壳这类高频宿主界面：
   • 先看项目里已有的视觉语言和 spacing
   • 再决定是否抽共用骨架
   • 不允许为了单块功能临时长出另一套背景卡、摘要卡、面板系统
5. 当前 Storage Root、guns、ammo、gunpack 已经形成“先复用现有壳，再补结构”的方向；后续 attachment / block / 其他资源页也必须遵守这条路线。

Anti-compression rule

当一个功能已经连续出现“压缩 3-4 次、每次只修一截”的情况时，后续实施必须改成 end-to-end 收口，不允许继续分裂成交叉半成品。

具体要求：

1. 先列出这个功能的完整闭环。
2. 没把闭环跑通前，不要宣称功能已完成。
3. 对工作区能力，闭环至少包含：
   • 入口
   • 状态存储
   • 错误反馈
   • 可见调试
   • UI 验收

Output expectations

• 给明确的架构决定，不给空泛建议。
• 给目录级落点、依赖关系和非目标。
• 给迭代顺序与验收标准。
• 如果发现现有实现偏离计划，要直接指出偏差和修正路线。