产品数据装配手册

本文档说明如何在 Monkeys 中装配一个数据驱动的产品体验。它把产品使用流程和 关键技术概念 连接起来。

目标不是逐个配置页面，而是装配一套产品系统：数据可以被配置、归集、交互、编辑，并被工作流、工具、Compute 和 Agent 主动复用。

适用场景

当你需要做这些事情时，可以使用本文档：

• 为 Studio 应用准备数据。
• 把业务对象转成 ontology 支撑的数据模型。
• 配置数据交互所需的 view 和 filter。
• 把数据连接到 workflow 和 tool。
• 把生成结果沉淀回产品数据。
• 检查一个功能是否围绕稳定数据契约装配。

本文档只使用 Monkeys 公开产品概念，不描述部署形态相关隔离、专属企业打包或非公开服务线细节。

装配流程

1. 数据建模

先定义产品需要理解哪些业务对象。

需要回答的问题

• 核心业务对象是什么？
• 哪些对象需要作为 record 存储？
• 哪些字段是必填、选填、派生或生成字段？
• 哪些字段会用于筛选、排序、分组或搜索？
• 哪些对象由 workflow 或 Agent 产生？
• 哪些文件或生成结果承载业务含义，应该成为 artifact？

推荐输出

在做界面前，先写一段简短的数据模型说明：

## Data Model

Object: Product Idea
Purpose: Store design inspiration and structured product planning inputs.

Fields:
- title: text, required
- description: rich text, optional
- category: enum, required
- source_images: artifact list, optional
- tags: tag list, optional
- status: enum, generated or user-edited
- created_from_workflow_id: reference, optional

Primary views:
- All ideas
- Ideas by category
- Ideas ready for workflow

好的信号

• 不依赖某个页面也能解释这个对象。
• 字段同时有稳定技术标识和友好展示名称。
• 生成结果有 artifact 处理策略。
• 同一模型可以被 Studio、Kernel、workflow、tool、Compute 和 Agent 使用。

常见错误

• 先从页面布局开始，而不是先定义 record。
• 为导入、展示、workflow 输入、Agent 输出各写一套 schema。
• 把展示名称当成稳定标识。
• 把生成文件当成和数据模型无关的外部结果。

2. 定义 Ontology 和 Schema

Ontology 赋予数据业务含义。Schema 定义对象结构。

需要定义的内容

每个由 ontology 支撑的对象都应该定义：

• 对象名称： 稳定的产品概念。
• 字段： 技术标识、展示名称、类型、是否必填、默认值。
• 关系： 与其他 record、artifact、workflow、tool 或用户的连接。
• 生命周期状态： draft、ready、running、generated、approved、archived，或其他有业务含义的状态。
• 校验规则： 必填字段、允许值、文件限制、数值范围。
• 派生字段： 由其他字段或外部执行计算出的值。

常见字段类型

装配规则

如果某个字段会控制 workflow 行为、Agent 行为、权限、筛选或生成结果，就应该显式建模。不要只把它藏在 prompt、页面组件或 task 脚本里。

3. 配置数据仓库

数据仓库是用户管理一组 record 的产品入口。它在用户侧应该好理解，在系统侧仍然遵循 ontology 和 Global Data 契约。

配置检查清单

• 选择或创建对象对应的数据仓库。
• 将数据仓库绑定到目标 ontology。
• 确认哪些字段可见、可编辑、只读、派生或隐藏。
• 决定 artifact 如何上传、展示和关联。
• 定义默认排序和分组。
• 定义搜索行为。
• 确认哪些 record 可以被 workflow 和 Agent 使用。

数据仓库设计建议

让数据仓库对用户好理解：

• 使用业务名称，不使用系统术语。
• 只展示能帮助当前工作流的字段。
• 高级配置放在 Kernel 相关界面。
• 让生成 artifact 靠近产生它们的 record。

让数据仓库对系统保持稳定：

• 业务事实沉淀到共享数据契约里。
• 不要只在 view 的局部 UI 状态中保存业务状态。
• 在导入、生成和编辑过程中保持 record 标识稳定。

4. 配置 View 和 Filter

View 定义数据如何被检视和操作。Filter 定义数据如何被选中。

View 类型

Filter 设计

每个可复用 filter 应该定义：

• 来源对象或数据仓库。
• 字段谓词。
• 搜索行为。
• 标签匹配行为。
• 带权限感知的数据选择规则。
• 默认排序。
• 空状态行为。

好的 View 设计

一个好的 view 应该回答：

• 我正在看什么数据？
• 这条 record 为什么会出现在这里？
• 我可以对它做什么？
• 操作之后会发生什么？
• 结果会去哪里？

常见错误

• 把 view 当成数据的拥有者。
• 在 Studio、Kernel、API 和 Agent 工具里分别实现同一套 filter 逻辑。
• 为每一种视觉变化创建新的后端概念。
• 把 workflow 状态藏在触发它的 record 之外。

5. 归集数据

数据可以通过多条路径进入 Monkeys。每条路径最终都应该产生可复用的 record、artifact 或结构化状态。

归集路径

导入前检查

• 将来源列映射到 ontology fields。
• 标准化名称、类别、单位和枚举值。
• 决定如何识别重复数据。
• 决定 artifact 如何关联。
• 有价值时保留来源元数据。
• 在 record 生效前校验必填字段。

导入后检查

• 检查 record 数量。
• 检查失败行或跳过的文件。
• 验证搜索和 filter。
• 至少打开一个 table view、一个 detail view、一个 workflow 输入路径。
• 确认生成或导入的 artifact 已经连接到 record。

6. 与数据交互

交互是用户和 Agent 检视、选择、比较并准备行动的过程。

交互模式

• 通过 table、card、gallery 或 detail view 浏览 record。
• 按字段、标签、状态、阶段、日期或归属筛选。
• 选择 record 作为 workflow 输入。
• 并排比较 record。
• 打开 artifact 和生成结果。
• 查看血缘和 action history。
• 把有用的数据子集保存为 view。

交互设计规则

• 保持用户任务可见。
• 明确展示选择状态。
• 说明 record 为什么出现在当前筛选结果里。
• 展示 record 是否可编辑、由系统生成、被锁定或由其他字段派生。
• 不强迫用户理解内部系统术语。

7. 编辑数据

编辑应该被视为带校验、状态和可追踪性的数据变化。

编辑来源

编辑检查清单

允许编辑前：

• 确认字段在当前上下文可编辑。
• 确认用户或 Agent 有权限。
• 校验类型、范围、枚举、引用和 artifact 限制。
• 判断编辑是否会改变 workflow 可执行条件。
• 判断编辑是否应记录 action log。

编辑后：

• 刷新受影响的 view。
• 必要时更新搜索索引。
• 必要时重新计算派生字段。
• 保留产生这次变化的 workflow run 或 artifact 连接。

8. 主动利用数据

当产品能主动使用数据时，数据价值才会放大。

利用方式

主动利用检查清单

• 输入数据是否来自 view 或 filter？
• 必填字段是否存在且有效？
• Workflow 或 tool 契约是否类型化？
• 执行状态是否可见？
• 输出是否沉淀为 record 或 artifact？
• 是否能从输出追溯到输入？
• 另一个 view、workflow 或 Agent 是否能复用输出？

9. 沉淀结果和血缘

生成结果不应该消失在日志、prompt 或一次性文件中。如果它对产品有价值，就应该被沉淀。

应该沉淀什么

• 由 workflow 或 Agent 创建的最终 record。
• 生成 artifact，例如文件、图片、文档或模型输出。
• 执行状态和最终结果。
• 来源输入和被选中的 record。
• Tool 调用和重要参数。
• 复核、通过或拒绝的决策。

血缘问题

对于任何重要输出，产品应该能回答：

• 哪些输入 record 产生了它？
• 哪个 workflow、tool 或 Agent 创建了它？
• 它什么时候创建？
• 使用的是哪个 workflow 或 tool 版本？
• 生成后是否被编辑过？
• 现在由哪个 view 或数据仓库展示？

端到端示例

下面用一个通用产品灵感工作流做示例。

Step 1: 定义对象

Object: Product Inspiration

Fields:

• title
• description
• category
• source_images
• material_tags
• design_direction
• status
• generated_outputs

Step 2: 配置数据仓库和 Views

创建名为 "Product Inspiration Library" 的数据仓库。

Views:

• "All inspiration": table view，展示 category、status 和 tags。
• "Visual browsing": card view，展示 source images。
• "Ready for generation": 过滤 status 为 ready 的 view。
• "Generated results": 展示带 generated outputs 的 record。

Step 3: 归集输入

输入可以来自：

• 手动上传图片。
• 结构化表单提交。
• 导入表格行。
• 外部研究工具输出。

每个输入最终都成为 record，或成为关联到 record 的 artifact。

Step 4: 触发 Workflow

"Ready for generation" view 成为 workflow 的输入来源。

Workflow 会：

• 读取被选中的 record。
• 调用工具或模型任务。
• 生成 artifact。
• 将状态和输出链接写回原 record。

Step 5: 复核和复用

用户在 Studio 中检查生成结果。Agent 或 workflow 后续可以复用这些结果，用于排序、报告、细化或下一轮生成。

质量检查清单

认为一次数据装配完成前，先确认：

• Ontology 和字段不依赖某一个页面也能解释清楚。
• 数据可以被一致地导入或创建。
• Views 提供了正确的交互模式。
• Filters 可复用且带权限感知。
• Workflows 可以通过稳定契约消费 record。
• 生成 artifact 被持久化并建立连接。
• 编辑动作经过校验且可追踪。
• Agent 能理解数据契约，而不是依赖隐藏 UI 状态。
• 结果可以被另一个 workflow、view 或产品界面复用。