getxuui/present

在 xuui 中展示

将当前对话中的工作转化为一个可运行、可审查的 xuui 研究。交付的成果是一个经过验证的本地 URL、一段简短的设计问题说明，以及值得审查的差异点。交付之后，持续倾听用户的审查意见。

保持在 xuui 中

xuui 是此项工作的展示层。一旦某个设计进入 xuui，就一直在此展示。

• 当同时涉及其他技能或工作流时，使用该技能的方法选择方向，但将这些方向构建为 xuui 变体。绝不要构建该技能的选择器、应用程序内部的切换器或单独的预览页面。
• “在整个页面中展示”、“在网站中展示”或“在上下文中展示”意味着一个更大的 xuui 研究：围绕设计渲染周围的页面或布局，并附上相同的变体。
• 仅在用户要求实现或交付某个方向时，才修改真正的应用程序。保留研究，以便选择仍可审查。

确定要展示的内容

将用户请求的 UI、参考或近期工作作为简要说明。忠实地呈现现有实现。当简要说明要求提供替代方案时，让它们的差异点来回答设计问题；根据简要说明和有用的比较来决定数量。仅当对话和工作区无法明确主题时才进行询问。

从当前项目中找到研究工作区：已安装的工作区包含 xuui.studies.ts 文件和本地的 xuui 依赖。阅读该版本的 README、docs/authoring.md 和导出的类型，以及附近的注册文件。使用已安装的 CLI，而不是将更新的 alpha 版本下载到现有工作区中。如果使用 xuui 源代码签出，则改用 examples/studies.ts、src/xuui/model.ts 和 src/xuui/parameters.ts；并阅读 CONTEXT.md。不要通过从已安装的技能向上遍历来推断消费者工作区。

alpha 版本在独立工作区中呈现已注册的 React 组件。如果需要新工作区，运行 npx --package @getxuui/[email protected] xuui init <directory>，然后使用其固定的安装版本。对于来自其他代码库的工作，检查其令牌、相邻 UI、响应式约束、提供者和数据。适配相关组件和必要的依赖项，但不要静默地重新设计它。当隔离会扭曲审查时，包含一个上下文包装器，并披露模拟数据或不可用的后端行为。

构建探索框架

当需要替代方案时，说明设计问题，命名主要变量，并说明哪些保持不变。规划能够回答该问题的方向。以匹配的内容、有意义的状态、视口宽度和缩放比例开始。对于要求忠实地呈现现有设计的请求，不要生成替代方案。让简要说明和有用的比较来决定数量。

注册研究

将设计及其适配器放在研究注册旁边，遵循现有研究的模式。将研究添加到中央注册表中，或者当工作探索相同的问题时，扩展现有的相关研究。

• 使用产品术语：研究、变体、画布、图层 和 指南。使用 defineStudy 注册研究并列出其 variants。
• 为每个变体提供一个稳定、描述性的 ID，该 ID 在所有已注册的研究中唯一。当推进一个应保持可审查性的方向时，添加一个新的 ID。保留早期的实现；共享一个可变的组件不会冻结其历史。
• 为每个变体编写有用的名称、描述和理论依据。
• 注册普通的 React 组件。xuui 提供导航、平移、缩放、检查、比较和评论功能；研究提供设计及其所需的提供者或数据。
• 限定研究的 CSS 范围，使其不会重新设置工作室视图或其他无关变体的样式。为设计提供有意义的尺寸；在没有包含块的情况下，百分比宽度可能会在画布上折叠。
• 在 DOM 本身无法提供有用图层名称的地方，添加 data-xuui-layer-name。

暴露状态和控件

侧边栏显示变体声明的控件，审查者对其渲染的任何内容发表评论。选择与设计匹配的控件类型：

• machine 用于设计的独特状态以及在状态之间流转的事件：空、加载、加载完成和错误；关闭和打开；表单或流程的各个步骤。审查者可以从侧边栏跳转到任何状态，并在“播放”模式下跟随转换，以便每个状态都能被评判和评论。按照产品的命名方式命名状态和事件。从 machine.value 渲染，并将设计的真实交互连接到 machine.send(event)，以便在“播放”模式下点击时遵循同一个状态机。
• state 用于设计所反应的独立值，例如收藏切换开关或项目计数。
• props 用于值得比较的设计参数，例如文案、圆角或宽度。

当设计具有超出正常路径的有意义状态时，使用状态机而不是只呈现一个状态。不要发明设计中不存在的状态。仅暴露会改变渲染设计的控件，并检查每个状态都能正常渲染。有关确切形状，请参阅已安装的 docs/authoring.md。

仅修改被请求的研究以及展示它所需的注册。展示请求不授权重新设计工作室本身。

“完成”意味着请求的设计从已注册的变体中渲染出来，并且其暴露的控件能够工作。

运行并验证

在已安装的工作区中，使用 npx --no-install xuui dev；在源代码签出中，使用其包脚本。首先检查是否存在已有的预览，并在其服务于预期工作区时重复使用。不要干扰无关的进程。保持本地服务器运行以供审查者使用，并使用实际打印的源地址。

使用实际的服务器源地址和已注册的 ID 打开 URL：

• 聚焦的变体：/?study=<study-id>&variant=<variant-id>
• 比较：相同的 URL，带有 &view=all

验证渲染的变体身份，而不是将 HTTP 200 当作证据：未知 ID 会回退到已有的研究。检查 UI，在“播放”模式下执行重要的交互，并尝试每个暴露的控件。对每个方向应用相同的可用性标准：键盘访问、可见的完整控件焦点、可读的文本、适当的减少动效，以及真实的内容、状态和宽度。运行相关的项目检查，并准确报告失败或不可用的检查。

使用隔离的测试存储进行提交检查。保持审查者的真实草稿评论和已提交记录不变。

“完成”意味着链接打开预期的设计，有意义的交互能够工作，并且审查边界清晰。

交付

返回聚焦的链接，并在有用时返回比较链接。用几句话说明需要评判的内容，并命名重要的限制，例如模拟数据。审查者使用“播放”进行交互，使用“C”进行评论，使用“提交审查”进行交付。最后说明您正在等待他们的审查，并且他们可以继续聊天。

对于替代方案，添加一个简要表格，说明发生了变化、每个方向适合的场景以及其主要成本。说明审查的宽度和状态。不要静默地选择获胜者。当被要求推进某个选择时，验证被提升的设计在其源上下文中的效果，并保留其可审查的研究；保留旧的实现并为进一步的可比较工作添加稳定的 ID。

监听反馈

在交付后，无需提示即可等待审查。

• 如果 xuui MCP 工具可用，使用 xuui_wait_for_review 并传入研究的 studyId。每次调用在 50 秒内返回。使用返回的 knownReviewIds 再次调用，直到收到审查或用户要求您停止。
• 如果不可用，说明工作区的 MCP 服务器未连接。主动建议连接它，按照已安装的 docs/mcp.md 进行操作，并说明主机是否需要重启才能加载。在此之前，如果您的宿主环境可以运行一个在完成时通知您的后台命令，则使用它来等待 .xuui/reviews/ 中出现新文件。否则，请用户提交时通知您。

当审查到达时，阅读完整的包，然后使用 xuui_acknowledge_review 进行确认。确认表示您已阅读，而非其请求已完成。浏览器草稿不构成已提交的反馈。根据评论采取行动：将更改作为具有新 ID 的新变体进行，验证它们，交付新的链接，然后再次监听。