关键技术概念

本文档把 Monkeys 中稳定的产品概念映射到跨仓库的技术含义。它补充 产品开发哲学 和 模块架构。

它不是完整 API 文档。它的用途是为产品设计、实现、重构和 Agent 辅助开发提供一套共享词汇。

概念图

数据概念

Global Data

产品含义： Global Data 是组织级全量历史事实层。它保证事实数据统一、可治理、可查询，并能跨产品界面、工作流和 Agent 复用。

技术含义： Global Data 应被视为系统级数据层，而不是某个界面专属模型。产品界面可以暴露数据仓库、数据集、视图、工作区、任务或结果等用户可理解的概念，但底层仍然依赖 Global Data。

使用方：

• 数据服务和后端 API
• Kernel 的数据治理和配置
• Studio 的数据视图和工作流应用
• 工作流执行和 Agent 工具

避免：

• 把 Global Data 当成每个界面都必须展示的 UI 标签
• 在孤立功能状态里重复保存业务事实
• 在被持久化为产品数据之前，把 Global Data 与任务上下文、运行状态或生成结果混在一起

Ontology

产品含义： Ontology 定义业务语义。它描述 Monkeys 理解哪些业务对象，以及这些对象的字段、关系和行为如何组织。

技术含义： Ontology 应该是业务对象的稳定抽象。它比表、bucket 或存储命名空间更高一层。新的产品行为应该优先在 ontology 层建模，而不是硬编码功能专属 schema。

使用方：

• 数据建模和数据治理
• 数据导入和标准化
• 视图和筛选定义
• 工作流输入和输出
• Agent 可读取的数据契约

避免：

• 只把 ontology 当成存储 bucket 的别名
• 把业务专属 ontology 行为直接写进 UI 组件
• 在已有 ontology 可以表达同一对象时创建新的数据概念

Entity And Record

产品含义： Entity 是由 ontology 定义的业务对象类型。Record 是这个业务对象的具体实例。

技术含义： Entity 和 record 契约应该足够明确，以支持 UI 渲染、工作流执行、工具调用和 Agent 操作。Record 应该携带足够的身份、schema 和血缘信息，使其能在最初出现的界面之外复用。

使用方：

• 数据表格和详情视图
• 导入和导出流程
• 工作流载荷
• Agent 读写操作

避免：

• 在 record 实际表达业务对象时，把它当成匿名 JSON
• 在导入、转换或生成过程中丢失稳定标识
• 让 record 形状绑定到某一个页面布局

Field And Schema

产品含义： Field 定义业务对象的结构。Schema 定义字段如何组合成一致的对象模型。

技术含义： Field 和 schema 定义应该支持校验、渲染、筛选、导入、导出和 Agent 使用。Schema 应尽可能声明式，使产品行为可以通过配置变化。

使用方：

• 表单生成
• 表格和卡片渲染
• 数据校验
• 查询和筛选构建
• 工作流输入和输出契约

避免：

• 在前端、后端和工作流代码中重复定义同一个字段
• 把校验规则藏在页面级条件分支里
• 把展示标签当成稳定技术标识

Filter

产品含义： Filter 定义一组数据如何被选中。

技术含义： Filter 是访问和查询契约的一部分。它可以组合搜索、字段谓词、带权限感知的数据选择和产品特定约束。Filter 应该能跨 view、workflow 和 Agent 工具复用。

使用方：

• 数据视图
• 搜索和查询 API
• 工作流输入
• Agent 数据访问

避免：

• 在每个界面里重复实现同一套选择逻辑
• 把 filter 只当成视觉控件
• 让 Agent 工具绕过产品级筛选规则

View

产品含义： View 是用户或 Agent 检视和操作数据的方式。

技术含义： View 不是数据本身，而是覆盖在数据之上的访问、布局和交互契约。多个 view 可以为不同工作流展示同一批底层事实。

使用方：

• Studio 工作流应用
• Kernel 配置界面
• 数据仓库和数据集体验
• Agent 可读取的产品界面

避免：

• 只把业务事实保存在 view 专属状态里
• 把 view 当成数据模型的拥有者
• 为每一种视觉变化创建新的后端概念

Artifact

产品含义： Artifact 是生成或上传的结果，例如文件、图片、文档、模型结果、工作流结果或结构化记录。

技术含义： Artifact 只有在被持久化、索引、连接到 ontology，并可被 view、workflow 或 Agent 使用时，才真正成为产品数据。

使用方：

• 工作流执行
• Agent 输出
• Studio 应用
• 数据导入和生成流程
• 对象存储和元数据服务

避免：

• 让生成结果脱离追踪
• 丢失 artifact 与其来源数据、工作流或工具之间的关系
• 在文件承载业务含义时，把文件和产品数据模型割裂开

工作流概念

Workflow

产品含义： Workflow 是数据变化被产生、验证和沉淀的可执行路径。

技术含义： Workflow 不只是自动化 UI。它是连接数据、工具、任务、状态、artifact，以及用户或 Agent 行动的执行契约。

使用方：

• 工作流应用
• Conductor 支撑的执行流程
• 长时间运行任务
• 工具编排
• Agent 触发的操作

避免：

• 只把 workflow 当成可视化流程图
• 在 task 代码里隐藏数据变更却没有清晰契约
• 创建无法回写为产品数据的 workflow 输出

Task

产品含义： Task 是 workflow 中可执行的步骤。

技术含义： Task 应该有清晰的输入、输出、重试、状态、错误和职责边界。它应该足够小，便于理解，也足够可靠，能够在后台执行中运行。

使用方：

• Conductor workers
• 工具服务
• 数据处理流程
• 模型和媒体生成流程

避免：

• 构建依赖隐藏页面状态的 task
• 返回没有 schema 或 artifact 元数据的输出
• 在一个 task 中混合不相关职责

Trigger

产品含义： Trigger 启动一个 workflow 或 action。

技术含义： Trigger 可以来自用户操作、Agent 操作、计划任务、webhook、数据变化或系统事件。Trigger 契约应该定义来源、载荷、权限和预期结果。

使用方：

• 工作流应用
• Webhook 服务
• Agent runtime
• 后台 workers

避免：

• 在没有可审计来源的情况下启动 workflow
• 把 trigger 当成无类型事件
• 让 trigger 绕过权限或校验

State

产品含义： State 描述 workflow、task 或产品 action 处于生命周期的哪个阶段。

技术含义： State 应该显式，在需要时可持久化，并能被所属产品界面感知。长时间运行的执行流程应该暴露足够状态，用于恢复、调试和用户反馈。

使用方：

• 工作流执行
• 运行时编排
• Studio 进度 UI
• Kernel 配置校验
• 后端任务追踪

避免：

• 只把关键状态保存在浏览器运行时里
• 把所有失败都压成一个泛化的 failed 状态
• 让状态流转无法审计

Agent 和工具概念

Agent

产品含义： Agent 是能够读取数据、调用工具、触发 workflow、生成 artifact，并推动产品状态变化的行动主体。

技术含义： Agent 行为应该被产品契约约束：ontology、view、权限、工具 schema、workflow 契约和运行时策略。

使用方：

• Agent runtime 服务
• MCP 访问
• 工具调用
• 工作流执行
• 产品自动化

避免：

• 让 Agent 绕过数据契约
• 在应该使用产品数据时，只给 Agent 页面级状态
• 在校验和持久化之前，把 Agent 输出当成有效产品数据

Tool

产品含义： Tool 是可被 workflow、Agent 或产品服务调用的可复用能力。

技术含义： Tool 应该暴露清晰契约：名称、输入 schema、输出 schema、权限、执行行为、错误和 artifact 处理方式。

使用方：

• 工具服务
• Agent 工具包
• 工作流 task
• 产品集成

避免：

• 添加没有类型化输入输出的 tool
• 把原始供应商响应当成稳定产品契约返回
• 对 workflow 或 Agent 调用方隐藏副作用

Context

产品含义： Context 是完成一次产品 action 或 Agent task 所需的范围化信息。

技术含义： Context 应该来自产品数据、用户输入、workflow state 或 tool result。它应该有边界、可解释，并且在被有意持久化之前与事实层分开。

使用方：

• Agent 执行
• 工作流 task 输入
• 工具调用
• 应用状态

避免：

• 把临时 context 当成持久产品事实
• 向工具或 Agent 传入过宽、无边界的 context
• 把重要的 context 构造过程藏在纯 prompt 逻辑里

Action Log

产品含义： Action Log 记录发生了什么、由谁或什么发起，以及改变了什么。

技术含义： 重要的用户、workflow 和 Agent action 应该产生足够的追踪信息，以支持审计、调试、回放和用户信任。

使用方：

• Agent runtime
• 工作流执行
• 后端服务
• 数据治理

避免：

• 在没有可追踪性的情况下执行重要 action
• 在需要结构化字段时只记录文本摘要
• 丢失 action、来源数据、工具和结果 artifact 之间的连接

产品界面概念

Studio

产品含义： Studio 是承载数据驱动工作流创建、操作和消费的产品应用界面。

技术含义： Studio 应该在共享产品数据之上呈现一致的应用和工作流体验。它不应该拥有无法被 Kernel、Compute、workflow 或 Agent 复用的隐藏业务模型。

Kernel

产品含义： Kernel 是核心系统能力、数据能力和工作流能力的配置与治理界面。

技术含义： Kernel 应该暴露稳定的配置概念和数据治理控制。它应该让系统行为显式化，而不是让配置散落在应用代码里。

Compute

产品含义： Compute 是面向执行能力和自动化工作的产品界面。

技术含义： Compute 与共享数据和 workflow 架构相连，但它可以拥有比普通产品 view 更独立的执行概念。当 Compute 读取、写入或触发产品数据时，仍应复用共享数据契约。

代码映射

命名和重构规则

• 在新概念和公开文档中，优先用 Ontology 表达业务语义建模。
• 遇到 bucket 等历史名称时，将其视为兼容别名；不要把它扩展成新的产品概念。
• Global Data 只用于组织级全量历史事实层。
• View 表示数据之上的访问和展示方式，不表示数据本身。
• Workflow 表示可执行的数据变化路径，不只是 UI 流程图。
• Tool 表示类型化能力契约，不是任意辅助函数。
• 面向用户的命名可以友好，代码层概念必须稳定。
• 业务变化应尽可能进入声明式数据和配置。

功能设计检查清单

新增功能前，先问：

• 这是新的数据概念，还是已有数据上的新 view？
• 现有 ontology 是否已经能描述这个对象？
• 这个功能创建、消费、更新或持久化什么数据？
• 这个行为是否应该是配置，而不是代码？
• 哪个产品界面拥有主要体验？
• workflow、tool 或 Agent 是否需要读取、写入或触发它？
• 需要哪些权限、状态流转和 action log？
• 生成的 artifact 应该存在哪里，并如何连接回产品数据？
• 结果能否在首次出现的界面之外复用？