AgentSkillsCN

pubfi-dsl-server-contract

在定义或验证 PubFi DSL 请求的服务器端合约时，可使用此技能，包括模式验证、聚合映射、限制条件以及响应封装等环节。

SKILL.md
--- frontmatter
name: pubfi-dsl-server-contract
description: Use when defining or validating the server-side contract for PubFi DSL requests, including schema validation, aggregation mapping, limits, and response envelopes.

PubFi DSL Server Contract

Overview

This skill defines the server-side contract for executing PubFi DSL requests. The server only accepts structured DSL and maps requests to a fixed, audited OpenSearch query shape. The server does not accept SQL, OpenSearch DSL, or natural language compilation.

When To Use

  • •You are implementing the DSL validation layer.
  • •You are defining or auditing the allowed query templates.
  • •You are designing the response envelope and error model.

Core Rules

  • •Reject any request that includes SQL, OpenSearch DSL, or unknown fields.
  • •Validate against the schema before execution.
  • •Enforce hard limits for time window, top-k, fields, and aggregation sizes.
  • •Only execute allowed aggregation primitives (terms, date_histogram, cooccurrence).
  • •Do not compute business metrics server-side. Return documents and aggregation results only.

Required Server Behaviors

  • •Provide a schema endpoint that lists allowed fields, aggregation kinds, and hard limits.
  • •Provide a query endpoint that accepts DSL and returns a deterministic response envelope.
  • •Log request metadata for audit and billing reconciliation.

Error Model

The server returns errors using ApiEnvelope codes and English messages.

  • •ERR_INVALID_PAYLOAD: The request violates schema or limits.
  • •ERR_INTERNAL: The service failed unexpectedly.

Rate limiting and quota enforcement are out of scope for this contract draft and should be implemented at the gateway layer.

References

  • •See references/contract.md for endpoint definitions, response envelopes, and template mappings.