# Moi Storybook > 创建、补全、审查或更新一个用于 MOI 客户业务 Storybook、产品用户旅程、端到端走查、生成式 AI、事件驱动、定时任务、人工审批或工作流验收的 GitHub 单 Issue。当用户要求整理 Storybook Issue、客户场景、User Journey、业务走查或验收故事时使用。所有 Scene、实际结果、证据、验收项和问题跟踪必须放在同一个 Issue 中。不要用于前端组件开发工具 Storybook。 - Skill: `matrixorigin/moi-storybook` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add matrixorigin/moi-storybook` - Raw SKILL.md: https://api.skillmd.com/api/skills/matrixorigin/moi-storybook/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: matrixorigin (https://skillmd.com/u/matrixorigin) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/matrixorigin/moi-storybook --- # MOI 业务 Storybook 围绕一个客户场景或一条完整业务主线，产出一个容易理解、可继续细化，并在需要时可执行验收的 GitHub 单 Issue。 ## 基本规则 - 一个 Storybook 只使用一个 Issue，不创建 Scene 或 User Story 子 Issue；只有确需独立研发 owner 和排期时才链接外部 Bug、Feature 或 PR。 - [单 Issue Storybook 模版](references/single-issue-template.md) 是标题、章节、表格和验收附录的唯一格式来源。 - 默认先讲需求来源、客户或内部发起方、用户目标、业务流程、期望结果和当前问题，再写产品或验收细节。 - 不得虚构客户背景、样例、环境、输入、ID、实际结果、证据、Issue、owner 或结论。 - 用户明确提供给当前 Storybook 的样例文件必须逐个原样保存到 IDC MinIO 的独立 Storybook 目录，并全部列入 Issue；小文件可以同时直接附到 Issue，大文件必须使用 S3。详细目录、凭据、上传和核对规则见 [样例数据存储规范](references/sample-data-storage.md)。 - Storybook 的 S3 目录按 `#--样例数据` 命名；测试新构造的样例文件也使用该前缀。用户提供的原始文件不得为满足命名规范而改名。 - 未经用户明确同意，不得裁剪、抽样、脱敏、改名、拆分、合并、解压、重新压缩或用自制代表集替代。 - 只有用户明确要求时，才创建或编辑 GitHub Issue；发现已有 Issue 时不得擅自改写。 - 实际创建 Storybook Issue 时，必须加入 Project `New MatrixOne Intelligence`，添加 Label `storybook`，并默认 Assign 给 `gavin-wang-note`。 - 客户需求还必须添加 Label `customer/<客户名称>`；非客户需求不得添加 `customer/*`。 ## 角色分工 - **提报模式（默认）**：面向非专业提报人，只收集需求来源、具体客户或内部发起方、业务目标、使用场景、业务流程、期望结果和样例状态。 - **测试模式**：仅在用户明确要求测试、走查、验收或自动化时启用；由测试补充测试夹具、环境、精确步骤、断言、实际结果和证据。 - 提报人不需要填写 Fixture ID、文件哈希、Step ID、Result ID、断言、自动化入口或运行参数。 ## 执行流程 ### 1. 确定模式与边界 - 默认使用提报模式；只有明确进入测试工作时才使用测试模式。 - 一个 Storybook 对应一个客户场景或一条逻辑完整的业务旅程。 - 请求包含互不相关的业务主线时，先说明建议边界，不要静默混在一个 Issue 中。 ### 2. 询问样例 如果当前对话没有可访问样例，且用户尚未回答是否有样例，先问： > 这个场景有能说明业务的样例文件吗？如果有，请上传获准使用的原始或脱敏文件，或提供可访问链接；如果没有，请直接说明，我会记录是否需要由测试后续构造样例。 - 提报模式下，用户有样例时只需上传并说明样例代表的业务；明确提供给当前 Storybook 的多个文件默认都要上传，不得只选择其中一部分。用户没有样例时，询问是否授权测试后续构造合成样例并记录选择，不要求提报人设计测试数据。 - 测试模式下，实际读取已有样例并记录文件名、格式、版本或哈希、规模、代表性内容、权限和脱敏要求。没有样例但已获授权构造时，用一至三个简短问题确认： 1. 业务种类、目标和需要提取的字段或内容。 2. 文件格式、数据类型，以及单文件或批量文件。 3. 页数、行数或记录数、语言、边界情况，以及是否需要标准答案。 - 测试负责提出最小可用方案并生成合成样例；全部内容使用虚构信息，明确标记为“合成测试数据”，按照 [样例数据存储规范](references/sample-data-storage.md) 命名，并记录生成规格、字段说明、标准答案、版本或哈希和适用范围。 - 暂无样例且未授权构造时，提报仍可继续，但必须记录为“待测试补充”。 - 已经上传或回答过时，不重复询问。敏感资料只使用获准版本；是否脱敏、裁剪或转换必须由用户决定，不能因判断文件敏感而自行加工。 #### 样例附件完整性 - 上传前列出用户提供的全部原始文件，核对文件名、数量和大小；用户提供压缩包时，该压缩包本身就是原始文件，不得自行解压或重新打包。 - 完整读取并执行 [样例数据存储规范](references/sample-data-storage.md)：一个 Storybook 创建一个以 Issue 编号和名称命名的独立目录，全部原始文件都保存到该目录，不能与其他 Storybook 共用。 - 在 `5.1 业务样例` 中写明 S3 Bucket、Storybook 目录和每个原始文件的对象位置；不能只写本地路径，也不能只上传一个自制汇总包。 - 小文件在 S3 保存后，可以再将同一原文件直接附到 Issue；超过 GitHub 当前附件限制或直接上传失败的文件不得压缩规避，必须以 S3 位置交付。 - S3、权限或网络问题导致原文件无法保存时，记录具体文件和阻塞原因并立即向用户说明；不得把样例状态写成“已全部提供”。 - 未经用户明确授权，不得通过压缩、拆分、裁剪、抽样、脱敏、转换格式或提交到代码仓库、Release、LFS 等方式绕过上传限制。 - 交付前逐项比对“用户提供的文件清单”“S3 对象清单”和“Issue 中记录的文件清单”；缺少任何原始文件时，只能报告为未完整上传。 ### 3. 确认需求来源并检索背景 - 每个 Storybook 必须注明需求来源类型：`客户需求`、`内部产品需求`、`市场共性需求` 或 `探索验证`。用户未说明时先询问，不能自行归类。 - 客户需求必须记录具体客户全称、需求提出人或角色、来源证据、提出或确认时间及确认状态；缺失项写“待确认”，不能用公开背景代替客户确认。 - 内部产品需求、市场共性需求或探索验证应记录内部发起方或 owner、提出依据和相关证据。 - 再搜索目标仓库中的客户项目、讨论、相关文档和 Storybook，并按需搜索官网或其他权威公开来源；只保留与当前用户、数据、流程或下游用途直接相关的背景。 - 在正文中链接来源，并区分已确认事实、仓库记录和推断。 ### 4. 检查重复 Issue - 创建前同时搜索 Open 和 Closed Issue，组合使用客户名称、项目名、业务目标、输入类型、下游用途及 Storybook 常见标识。 - 打开最相关候选阅读正文，不能只看标题。 - 同一客户、同一用户目标且流程基本相同时，停止创建，返回已有 Issue、重复依据和“未创建”的结论。 - 部分重合时说明差异。只有新需求确属独立业务主线时才新建；补充已有 Issue 需要用户明确授权。 - 新建 Storybook 时，先完成查重并确认需要创建；创建 Issue 获得编号后，再按 `#--样例数据` 建立 S3 目录和上传样例，最后回填 Issue，避免目录缺少可追溯的 Issue 编号。 ### 5. 选择内容深度并收集证据 - 提报模式只使用模板中的“业务 Storybook”，不要求填写验收附录。 - 测试模式在已有业务 Storybook 后追加“可执行验收附录”，不重写提报人已经确认的业务内容。 - 优先使用样例、源文档、权威判定基准、产品实际状态和日志；保留准确的环境、工作区、对象、文件、模型、执行 ID、产物路径和错误文本。 - 没有实际证据时，只写预期和待确认内容，不把目标行为写成已经实现或验证。 ### 6. 编写或更新 Issue - 完整读取模板，删除不适用章节，不保留空表格、模板说明或大量无意义 `TODO`。 - 新建 Issue 时，先用完整业务正文创建 Issue 并获得编号；样例位置可暂记为“创建后上传并回填”，但不得把它当作最终交付。 - 按 Issue 编号和最终标题创建 S3 独立目录，将用户提供的全部原始样例逐个保存；测试构造的文件使用规范名称。 - 上传完成后立即更新 `5.1 业务样例`，列出目录、每个对象位置和可访问方式；小文件可额外附到 Issue。存在阻塞时保留原文件名和未上传原因，不得替换为自制样例。 - Issue、评论、日志和正文中不得出现 MinIO 密码、访问密钥、Session、Cookie 或其他凭据。 - 使用客户业务语言；开头应让非技术读者快速理解谁要做什么、为什么、如何完成、得到什么以及当前卡点。 - 预期结果、实际观察和证据分开记录；明确“已证明”和“尚未证明”。 - 走查发现的问题默认留在同一个 Storybook Issue 中；只有确需独立修复或排期时才链接外部 Issue。 - 创建后立即确认 Project 为 `New MatrixOne Intelligence`、Label 包含 `storybook`、Assignee 为 `gavin-wang-note`；用户明确指定其他 Assignee 时以用户要求为准。 - 客户需求还要确认 Label 包含与具体客户全称一致的 `customer/<客户名称>`；非客户需求确认没有 `customer/*`。 - 如果 Project、Label 或 Assignee 因权限、字段、标签或账号不存在而未成功设置，明确报告未完成项，不得把 Issue 视为完整交付。 ## 测试补充与验收门槛 - 以下内容由测试负责，不要求 Storybook 提报人提供。 - 提报完成但尚未经过测试补充时，内容状态最多为 `READY FOR REVIEW`，执行结果保持 `NOT RUN`。 - 每个必须验收的 Scene 只有同时具备以下内容，才可标记 `READY FOR TEST`： 1. 可访问的真实样例，或用户确认规格和标准答案的可复现测试夹具。 2. 另一名执行者可以照做的精确操作、输入、配置和顺序。 3. 可观察、可判定的预期结果、验证方法和证据来源。 - 合成样例只能证明相应功能路径；除非客户明确认可其代表性，否则不能替代真实客户数据的最终验收。 - 只有实际执行、按判定标准核对并保留证据后，才能写 `PASS`。创建成功、HTTP 200、绿色状态或任务完成本身不能证明业务结果正确。 - 生成式 AI 或定性结果必须使用关键事实、禁止项、可接受答案集合、引用覆盖或评分量表，不能只写“回答正确”。 ## 输出 提报模式未命中重复 Issue 时，输出推荐标题和元数据、易读的业务 Storybook、需求来源与背景证据、样例状态、查重结果，以及少量待确认项；不输出专业测试表格。 测试模式更新同一个 Issue，追加测试夹具、精确操作、预期结果、实际结果和证据，不要求提报人补写这些内容。 命中重复 Issue 时，不生成新的完整正文；输出已有 Issue 链接、重复或部分重合依据、本次未创建的结论，以及需要用户授权后才能执行的补充建议。 交付前确认：角色分工正确、需求来源和业务流程清楚、Open/Closed 已查重；每个 Storybook 使用符合 `#--样例数据` 规则的独立 S3 目录，用户提供的全部原始样例均已逐个原样保存，测试构造文件命名合规，并已在 Issue 中写明位置，或已明确报告阻塞；实际创建的 Issue 已加入 `New MatrixOne Intelligence`、已添加 Label `storybook`、默认已 Assign 给 `gavin-wang-note`，客户需求已添加 Label `customer/<客户名称>`、非客户需求没有 `customer/*`；只有测试模式才要求验收夹具、精确步骤和证据。