docyrus-architect

Docyrus Architect

使用 docyrus-architect MCP 工具在 Docyrus 中管理和查询数据源的指南。

工具概览

发现工具

• get_apps — 列出租户应用。调用 create_data_source 前，先使用此工具查找目标 tenantAppId。
• get_data_source_list — 按名称、描述或应用 ID 搜索数据源。
• get_data_source_list_with_fields — 与上方相同，但包含字段名称和类型。
• get_data_source_metadata — 获取数据源的完整元数据（包含字段的 ID、类型、slug、枚举和关系）。查询前务必调用此工具，以查明字段 slug 和关系目标。
• get_enums_by_field_id — 获取 select/status/tagSelect 字段的枚举选项。
• read_current_user / read_tenant_user — 获取用户信息。

数据源 CRUD

• create_data_source — 创建新的数据源（表）。自动创建的默认字段：id、autonumber_id、name、record_owner、created_on、created_by、last_modified_by、last_modified_on。
• create_data_sources_batch — 在单个原子事务中创建多个数据源及其字段和枚举选项。对于 field-relation 类型，支持通过 slug 在批次内交叉引用数据源。每批最多 20 个数据源。
• update_data_source — 更新数据源属性。
• delete_data_source — 删除数据源及其所有数据。

字段管理

• create_fields — 批量创建字段。对于 field-relation 类型，设置 relationDataSourceId。
• update_fields — 批量更新字段。非 CUSTOM 字段会生成自定义记录。
• delete_fields — 按 ID 批量删除字段。

枚举管理

• create_enums — 为 select/tagSelect/status 字段创建枚举选项。针对字段专属枚举传入 fieldId，针对共享枚举集传入 enumSetId。
• update_enums — 更新枚举选项的名称、slug、颜色或图标。
• delete_enums — 删除枚举选项。

OpenAPI 规范

• regenerate_openapi_spec — 在数据源或字段变更后，重新生成并上传租户的 OpenAPI 规范。可传入可选的 dataSourceSlugs（字符串数组）来限制范围；省略时会包含所有数据源。返回已上传规范的 publicUrl。执行任何 create_data_source、update_data_source、delete_data_source、create_fields、update_fields 或 delete_fields 操作后，都要调用此工具，以保持规范同步。

查询与计算

• query_data_source — 通过筛选、排序、聚合、公式、透视和子查询读取数据。完整查询语法请参阅 references/data-source-query-guide.md。
• evaluate_jsonata — 测试 JSONata 表达式。可用于验证计算字段公式。

自定义查询

• get_custom_queries — 列出租户中未归档的自定义查询。
• get_custom_query_by_id — 读取完整的自定义查询定义（name、description、query、filters）。
• create_custom_query — 使用 Handlebars 变量和可选筛选器定义创建已保存的 SQL 模板。
• update_custom_query — 更新现有自定义查询的指定字段（部分更新）。
• delete_custom_query — 软删除（归档）自定义查询。
• run_custom_query — 使用运行时筛选器、分页偏移量和可选的模拟模式执行已保存的自定义查询。

常见工作流

创建包含字段和枚举的数据源

单个数据源方式：

1. 调用 get_apps 查找目标应用 ID
2. 调用 create_data_source，并指定 title（复数）、name（单数）和 slug（单数 snake_case）
3. 调用 create_fields 添加所有自定义字段（默认字段已存在）
4. 对于 select/tagSelect/status 字段，调用 create_enums，并使用步骤 3 中的字段 ID
5. 调用 regenerate_openapi_spec 更新 OpenAPI 规范

批量方式（推荐用于多个数据源）：

1. 调用 get_apps 查找目标应用 ID（可选，默认为 "Default Customizations App"）
2. 调用 create_data_sources_batch，并传入数据源定义数组（最多 20 个）
   • 每个数据源包含 title、name、slug 和 fields 数组
   • select/status/tagSelect 字段可包含内联 enumOptions
   • 使用 slug 引用同一批次中其他数据源的 relationDataSourceId
   • 所有数据源、字段和枚举都将在单个原子事务中创建
3. 调用 regenerate_openapi_spec 更新 OpenAPI 规范

查询数据

1. 调用 get_data_source_metadata，了解字段 slug、类型和关联关系
2. 调用 query_data_source，并指定适当的列、筛选条件和排序方式
3. 对于高级查询（聚合、公式、数据透视、子查询），请阅读 references/data-source-query-guide.md

修改现有数据源

1. 调用 get_data_source_metadata 查看当前字段
2. 根据需要使用 create_fields / update_fields / delete_fields
3. 对于枚举变更，先使用 get_enums_by_field_id，然后使用 create_enums / update_enums / delete_enums
4. 调用 regenerate_openapi_spec 更新 OpenAPI 规范

管理自定义查询的生命周期

1. 调用 get_custom_queries 查找现有查询或确认命名
2. 调用 create_custom_query，并指定 name、query 以及可选的 description/filters
3. 调用 get_custom_query_by_id，验证已保存的模板和筛选条件定义
4. 使用 update_custom_query 进行针对性编辑（重命名、修订 SQL 模板、更新筛选条件定义）
5. 仅在明确要求归档时使用 delete_custom_query

运行和调试自定义查询

1. 先调用 get_custom_query_by_id，检查 SQL 模板和可用的筛选条件 slug
2. 构建运行时 filters，其中 rules[].field 的值须与查询的筛选条件 slug 相匹配
3. 对于复杂或不可信的查询，调用 run_custom_query 并设置 simulate: true，以检查计划输出
4. 调用 run_custom_query 并设置 simulate: false（或省略该参数）以获取真实数据
5. 使用 offset 进行分页，并注意每次执行最多返回 50,000 行

关键规则

数据源创建

• title 使用复数（例如，“Sales Orders”），name 使用单数（例如，“Sales Order”），slug 使用单数 snake_case（例如，“sales_order”）
• 复杂表单使用 defaultEditFormTarget: "tab"，简单表单使用 "side"
• 对于 CRM 类型的数据源（潜在客户、联系人、交易），启用 pluginActivityView
• 对于协作型数据源，启用 pluginComments
• 用户需要为记录附加文件时，启用 pluginFile
• 用户需要为每条记录创建富文本文档时，启用 pluginDocyment

字段类型

• field-relation 需要 relationDataSourceId——关联数据源的 ID（UUID）；批量操作时，也可以使用同一批次中另一个数据源的 slug
• field-list 是显示子记录（一对多关系）的虚拟字段——不会存储在数据库中
• field-select / field-tagSelect / field-status 需要枚举选项：
  • 在 create_fields 中：创建字段后调用 create_enums
  • 在 create_data_sources_batch 中：在字段定义中内联包含 enumOptions 数组
• field-formula 使用 JSONata 表达式——请先使用 evaluate_jsonata 测试
• field-inlineData 存储对象数组，field-inlineForm 存储单个嵌套对象
• 字段 slug 必须为 snake_case，并匹配 ^[a-z][a-z0-9_]*$
• 枚举选项的 slug 必须为 snake_case，并匹配 ^[a-z][a-z0-9_]*$（如果未提供，则根据名称自动生成）

批量操作

• create_data_sources_batch 可在单个事务中创建最多 20 个数据源
• 在批次内，使用其他数据源的 slug 作为 relationDataSourceId 的引用
• 对于批次外创建的外部数据源，relationDataSourceId 使用 UUID
• 批次内的数据源 slug 必须唯一（否则会出现验证错误）
• 内联枚举选项按字段使用 enumOptions 数组定义
• enumOptions 中的每个枚举选项可以指定：name、slug、color、icon、sortOrder
• 如果批量操作失败，所有更改都会回滚（原子事务）
• 创建相关数据源时使用批量操作，以避免多次 API 调用并确保一致性

查询

• 使用 dataSourceId（UUID）标识要查询的数据源
• columns 是以逗号分隔的字段 slug 字符串，而非数组
• 对于聚合计算，始终使用 id 字段进行 count 计算
• 关系展开：relation_field(sub_field1, sub_field2) 用于选择嵌套列
• 展开运算符：...relation_field(alias:sub_field) 将字段扁平化到根对象中
• 筛选关联字段：rel_{{relation_slug}}/{{field_slug}}
• 日期筛选器提供 today、this_month、last_30_days 等快捷运算符

query_data_source 必填参数

MCP 工具架构中所有参数均为必填（大多数参数接受 null）：

• dataSourceId：字符串（必填，不能为 null）
• columns：字符串 | null
• filters：对象 | null
• filterKeyword：字符串 | null
• orderBy：数组 | null
• limit：数字 | null（默认值：1000）
• offset：数字 | null
• fullCount：布尔值 | null
• recordId：字符串 | null（按 ID 获取单条记录）
• calculations：数组 | null
• distinctColumns：数组 | null
• formulas：数组 | null
• childQueries：数组 | null
• pivot：对象 | null

自定义查询规则

• 将自定义查询的 query 内容视为 Handlebars SQL 模板，而非静态 SQL。
• 在适用时，在模板中使用内置上下文变量：TENANT_ID、TENANT_SCHEMA、USER_ID、USER_EMAIL、USER_FIRSTNAME、USER_LASTNAME、USER_FULLNAME。
• 使用 {{filter FILTERS.<slug> <column_expression>}} 进行可选的运行时筛选。如果未提供运行时值，该辅助函数会解析为 1=1。
• 确保 create_custom_query / update_custom_query 中的 filters 定义与模板用法保持一致：
  • 模板用法：FILTERS.<slug>
  • 运行时规则字段：<slug>
  • 筛选器定义 slug：<slug>
• 执行开销较大的查询前，优先使用 simulate: true 检查 EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) 输出。
• 遵守 run_custom_query 的运行时限制：最多返回 50,000 行，正常执行超时为 15 秒，模拟模式超时为 30 秒。
• 将 delete_custom_query 用作归档操作（软删除），而非永久删除。
• 对于由 JSONB 支持的简单数据源，使用 (table_alias."data"->>'field-uuid')::type 访问自定义字段。

参考文档

• 数据源查询指南 — 关于 query_data_source 的最新参考文档，涵盖列、筛选条件、orderBy、分页、计算、公式、透视、子查询和运算符详情。
• 公式设计指南（LLM） — 关于设计查询请求中所用公式载荷的最新指南。
• 自定义查询指南 — 涵盖 get_custom_queries、get_custom_query_by_id、create_custom_query、update_custom_query、delete_custom_query 和 run_custom_query 的完整生命周期与执行参考。