/build-product-and-tool-interfaces

name: build-product-and-tool-interfaces
description: "为浏览器内需要持续操作对象、推进多步状态并产生可检查结果的产品与专业工具设计、实现、重构或诊断完整界面。用于运营与审核工作台、任务流业务产品、创作与编辑工具、分析与管理工具、资产或文件处理器、监控处置台及其目标环境工作流；核心覆盖对象模型、状态机、真实输入输出、专业引擎、错误恢复、信息密度与任务连续性。不用于主要供阅读的内容网站、只展示组件与 token 的设计系统样张、单张数据图或以理解模型为目的的交互演示。"

构建产品与工具界面

成功定义

让目标角色把真实输入或对象推进到可核验结果；需要持久化、权限、批量或协作时，这些能力也必须形成真实闭环。完成态不是“页面已经画完”，而是适用于当前子型的输入、命令、状态变化、反馈、恢复与输出成立；不适用的能力应明确记为 `N/A`，不能用假数据或假控件补齐产品外观。

本 Skill 拥有产品领域判断，并保留介质中立的真实标杆、视觉理由、素材来源与许可和目标环境验收。 最终消费者或合同交付确为 Web 时，再与 `$build-polished-visual-frontends` 组合；对象模型、迁移报告或 内部状态检查器本身不触发组合。组件系统风格合同和代表性非空方向帧只适用于含可视界面的 Create/Edit；纯对象建模和 Diagnose 记为 `N/A + 原因`。Diagnose 可只读检查组件语言与渲染证据， 不得借检查改写视觉方向。详细状态矩阵、批量作用域、恢复策略和环境转换模式见 [references/patterns.md](references/patterns.md)。

组合时以对象模型、命令关系、任务密度和状态风险决定视觉优先级，不套用“简单、干净、中性”的 默认皮肤。主题材料与标志性表达不得压过主工作对象，除非用户要求、已接受参考或品牌系统明确授权。

选择主要产品循环

按用户反复完成的工作选择主型，不按“有侧栏”“像后台”或采用的框架分类。混合产品只保留一个主要循环，其他能力围绕它服务。

| 主型 | 核心对象 | 高频循环 | 完成证据 | | --- | --- | --- | --- | | 运营与审核工作台 | 案例、记录、请求、任务 | 定位、判断、分派、批量处置、追踪 | 状态去向、责任人、审计记录 | | 创作与编辑工具 | 文档、素材、场景、版本 | 选择、编辑、预览、比较、保存、发布 | 可恢复版本或真实产物 | | 分析与管理工具 | 数据集、查询、配置、项目、资源 | 查询、比较、解释、配置、处置 | 可追溯决策、配置或报告 | | 任务流产品 | 申请、订单、工单、审批、作业 | 受理、校验、交接、批准、完成、重开 | 生命周期变化与交接记录 |

页面主要用于发现和阅读内容时，路由到内容网站；交付物主要是跨产品复用的组件、状态与 token 时，路由到 UI 组件与设计系统。单张图的重点是解释数据时属于数据可视化；只有当查询、筛选、告警和处置组成持续工作时，完整界面才属于本领域。操纵变量只为理解规律时属于交互解释器，不要套用业务工作流。

登录、侧栏、搜索、图表或 AI 摘要不自动构成产品工具。混合站点按任务面拆分：发现与阅读仍按内容网站设计；只有反复操作稳定对象、推进持久生命周期或生成可继续使用结果的工作区才应用本 Skill，不把整个站点强行包装成 dashboard。

先定工作模式与适用能力

先根据请求选择工作模式，不能把 Create 的流程机械套到 Edit 或 Diagnose：

| 模式 | 目标 | 硬边界 | | --- | --- | --- | | **Create** | 从需求建立新的对象、命令与工作面 | 只实现有真实输入、状态和结果的承诺；未要求的企业能力不补齐 | | **Edit** | 修改现有产品而不破坏既有任务、数据与交互契约 | 先审计不可破坏行为、数据迁移和回归证据，再做最小必要改动 | | **Diagnose** | 定位现有界面的行为、状态、性能或可用性问题 | 默认零写入：不改源码、配置、权威数据或产品状态；只做只读复现、追踪和证据归因，修复需用户另行授权 |

再按产品子型建立适用性表，并为每项写 `required / optional / N/A + 原因`：

| 能力 | 何时需要 | 何时可为 `N/A` | | --- | --- | --- | | 当前对象、选择与批量 | 多对象列表、集合操作、批处理 | 单对象计算器、一次只处理一个文件或文档的工具 | | 持久化、版本与刷新恢复 | 工作跨会话继续、形成权威记录或可恢复草稿 | 明确的一次性无持久化工具；仍须给真实即时结果或可用输出 | | 权限与审计 | 多角色、受控动作、合规或高影响变更 | 单用户、本地、无角色差异的工具 | | 协作与冲突 | 多人同时或异步编辑、交接、评论、审批 | 单人工作流或只读共享 | | 异步作业与进度 | 导入、计算、上传、发布等确实跨时完成 | 同步且可即时完成的命令 | | 目标环境任务转换 | brief 明确承诺多个环境完成任务 | 明确限定单一环境的专业重型工作面；仍须在合同视口可用 |

所有子型只共享不变量，不共享固定字段：真实输入进入一个权威任务模型；同一命令的不同入口产生相同效果；可见承诺能追溯到真实状态或输出；失败保留仍可恢复的工作；界面不伪造未实现的后端、权限、协作、版本或持久化。

先写产品契约

编码前用一页以内写清以下内容，并让界面结构从契约产生：

• **模式与适用性**：Create、Edit 或 Diagnose；产品主型；选择、批量、持久化、权限、协作、异步和环境转换分别是必需、可选还是 `N/A`。
• **角色与责任（适用时）**：谁可以看、改、批准、撤回或导出；受限动作如何解释原因。单用户本地工具不虚构角色体系。
• **对象/任务模型**：记录完成任务所需的身份、字段、关系、原始值与派生值；只有跨对象引用、持久化、版本或协作需要时才增加稳定 id、所有者与版本。
• **生命周期**：记录当前子型实际存在的业务或工具状态，以及允许的命令转换；一次性同步工具不强造审批生命周期。
• **任务主线**：入口、当前步骤、下一步、适用的交接点、完成定义，以及承诺持久化时的重新打开路径。
• **共视依赖**：完成每个高频判断时必须同时看到的当前对象、主要证据、判断输入、可执行命令与完成证据。
• **命令契约**：目标、适用作用域、前置条件、状态转换、成功证据、失败恢复，以及风险需要时的撤销或确认。
• **输入输出**：输入的真实来源与格式；输出是保存记录、交接、配置、下载文件还是发布结果。
• **状态层次**：把适用的业务状态、界面交互状态、异步作业状态和视图上下文分别建模，不用一个 `status` 混装；不存在的层次标为 `N/A`。
• **组件系统风格合同（仅可视产品界面的 Create/Edit）**：选定组件系统的实际样张；它拥有的字体、密度、间距、圆角、边界、阴影、表面、图标、反馈与动效；项目 token 的一一映射、专属工作面的扩展规则和有证据的例外。纯非可视交付和 Diagnose 记为 `N/A`；Diagnose 只记录现状证据，不建立新合同。
• **持续性（适用时）**：需要保留的草稿、筛选、选中范围、滚动位置、历史、冲突与未完成作业如何恢复。
• **持久化契约（适用时）**：权威存储、schema 版本、hydrate/commit 边界、草稿、作业幂等、迁移，以及配额、损坏或重开失败时如何恢复。无持久化工具明确内存边界和离开后丢失什么。

按能力保留语义不变量，不照抄字段名。多对象产品必须区分当前上下文、显式选择、筛选结果和命令作用域；单对象工具只需一个权威文档/输入及其派生结果，不应为了“像产品”引入空的 selection 或 collection。专业引擎输入、标注/选区、检查器、计数、禁用条件和导出内容必须从同一权威对象或任务状态派生，不能只换标题而继续展示旧对象或全局演示数据。

从共视依赖生成工作空间

产品布局必须由高频判断的依赖关系产生，不能由需求列表、组件目录或“一个需求一个 section”产生。编码前为每个高频判断或命令写一行：`current object / primary evidence / decision input / available command / completion evidence`。

据此建立当前合同环境的工作区拓扑：

• 同一次高频判断需要相互参照的对象，在允许并列的合同视口默认同时可见；
• 主工作对象成为最大的连续区域，强连接对象形成稳定相邻 pane；高频直接呈现、次要一层展开、低频进入次级面板；
• 比较关系可以并列，顺序关系采用步骤，不因“三栏看起来专业”强造并列；
• 空间或输入方式不足以保留并列关系时，转换为明确的列表—详情、任务模式或分步流，并保留对象、

游标、选区和草稿，不机械纵向堆叠全部 pane。

交付范围包含可视产品界面的 Create 与大改先渲染代表性非空工作区；方向检查只看用户请求、外部参考、共视关系与像素，模型解释不能证明布局成立。纯非可视交付和 Diagnose 将方向帧记为 `N/A`。

用命令组织工作流

不要先列页面和卡片，先写一条对象动词路径，例如“受理 → 定位 → 操作 → 校验 → 交接 → 完成或重开”。每个高频动作都实现为统一命令，让按钮、菜单、快捷键和触摸入口调用同一逻辑。

为每项可见承诺建立硬映射：`控件 → 命令 → 权威状态变化 → 成功证据 → 重开恢复或导出证据`。缺少任一环的主流程控件不得启用；暂不实现的次要能力应禁用并说明边界。能点击、打开弹层、改变按钮文案或出现 toast 都不等于命令完成。

1. 首屏说明当前范围、当前对象、业务状态和最合理的下一步。 2. 有可视产品界面的 Create/Edit 先用代表性非空状态完成主工作区与核心判断，渲染并修正方向；此时只实现决定视觉方向所需的真实领域引擎和最小交互。纯非可视交付和 Diagnose 跳过本步并记录 `N/A + 原因`。 3. Create/Edit 在适用的方向检查无 blocker 后完成一个纵向闭环：取得真实输入，操作一个对象或任务状态，再产生可检查的即时结果、下载、保存记录或提交结果。Diagnose 只读复现现有路径并收集状态、行为和渲染证据，不执行写命令。 4. 再扩展当前子型确实需要的搜索、筛选、比较、多选、批量、历史、协作与低频设置；适用性表为 `N/A` 的能力不扩展。 5. 为每个异步阶段显示精确语义；读取、校验、保存、提交和导出不能共用模糊的“处理中”。 6. 高影响命令显示目标和作用域；不可逆动作确认，可逆动作优先提供撤销。

让专业能力真实成立

• Web 产品若没有质量合格的既有设计系统，采用稳定现代应用栈，并按 `$build-polished-visual-frontends` 的设计系统路由，从环境实际可用的成熟候选中，以产品气质、任务密度、平台传统、能力覆盖、可访问性、许可与交付证据选择一套主系统。候选清单及其技术边界只由前端路由维护；预装只表示可用，不能自动决定风格。
• 选定一套成熟系统后，把它当作整件产品的视觉语言，而不是按钮和输入框仓库。先观察真实组件样张和关键状态，再让导航、列表、面板、工作画布、空态、通知及自定义组合组件继承其字体、密度、间距、圆角、边界、阴影、图标、反馈与动效；项目只能使用从系统派生或明确映射的 token，不得平行创造另一套 chrome。
• 不要把“单页”“离线”或“交付一个 `index.html`”误判成简单静态产物：只要存在多个相互关联的控件、持久状态、导入/编辑/导出闭环或专业工作面，就应使用框架、组件系统和适用的领域引擎。离线是部署方式，不是放弃成熟能力的理由。
• 文件导入要读取并解析真实 `File`；查询要由用户输入或明确、可追溯的数据源计算；编辑要改变对象模型；导出要从当前状态生成可打开、可下载或可继续使用的结果。文件链路的唯一有效验收是从用户可见入口触发真实 file chooser、选择文件并观察权威状态与输出；测试代码直接给隐藏 `input` 注入文件只能作为下层单测，不能证明入口可用。确定性 synthetic fixture 只能进入自动化测试，或用户明确要求的 demo/mockup；后者必须在画面内和随附 metadata 显著标为 synthetic/demo，不能作为生产事实。
• 浏览器工具必须按最终交付 origin 与容器复验主路径，记录 `isSecureContext`、存储可用性、沙箱和权限边界。局域网 HTTP、iframe 与 localhost 不是等价环境；`randomUUID`、Web Crypto、Clipboard、File System Access、下载、IndexedDB 或媒体解码等能力若依赖安全上下文或顶层文档，必须提供真实兼容路径、明确要求 HTTPS，或在入口前阻止并解释，不能在用户动作后静默失败。
• 用户未提供数据、权威数据源或明确 demo 合同时，最终界面从真实空态、导入或创建入口开始，不预置看似生产的记录、队列、历史、用户、权限、指标或成功结果。离线交付可以使用浏览器存储和客户端生成文件实现真实本地状态，但不得虚构服务器同步、权限校验或后台作业成功。无持久化单对象工具可以只维护内存状态，只要清楚说明离开边界并交付真实即时结果或可用文件；不要为了通过“刷新恢复”而假造存储。无法实现的次要能力应禁用并说明边界。
• 未被需求要求时不要添加 AI 助手、洞察卡或聊天入口。确需 AI 或自动化时，把它建模为真实命令：显示输入范围、来源、执行状态、输出版本与限制，允许接受、拒绝或编辑；接受后的变化进入同一权威任务状态，并在适用时进入持久化、版本和审计链。没有真实推理或自动化能力时禁用并说明，不伪造评分、建议或成功状态。
• 数据表格、树、组合框、日期范围、可调分栏、对话框、菜单和复杂表单优先复用项目已有或新