coral-create-source-spec

Coral 源规范

在编写或修复 Coral 源规范时使用此技能。

目标

生成有效且可查询的 Coral 源规范，并确保它适用于：

• coral source lint <path>
• coral source add --file <path>
• coral source test <name>
• coral sql
• coral.tables 和 coral.columns
• 用于源变量和密钥的 coral.inputs

默认模式

默认面向外部开发者独立编写源规范。

这意味着：

• 创建 YAML 源规范文件
• 尽早使用 coral source lint <path> 对其进行 lint 检查
• 需要将其作为源进行测试时，使用 coral source add --file <path> 将其添加到 Coral
• 通过查询进行验证
• 反复迭代，直至结构正确

只有当用户明确要编辑 Coral 仓库时，才切换到 Coral 仓库布局。

输出模式

• 外部编写：
  • 创建独立的源规范，例如 ./my-source.yaml
  • 使用 coral source lint ./my-source.yaml 验证结构
  • 需要通过 Coral 查询时，使用 coral source add --file ./my-source.yaml 加载
• 为 Coral 仓库贡献：
  • 将社区源规范写入 sources/community/<name>/manifest.yaml
  • 仅当用户有意修改捆绑的核心源时，才将核心源规范写入 sources/core/<name>/manifest.yaml
  • 添加有代表性的 test_queries，用于对源进行基本的冒烟测试／连接检查
  • 使用 coral source test <name> 和仓库检查进行验证

工作流

1. 阅读提供方 API 文档，或检查本地数据集。
2. 从一张小表和少量列开始。
3. 定义：
   • 源元数据
   • 后端
   • 基础 URL 或文件位置
   • 身份验证
   • 变量和密钥
   • 密钥的凭据获取方式；如果提供方支持基于浏览器的设置，还要包括 OAuth
   • 如果要编写单独的 kind: identity 清单，则定义身份设置输入和 OAuth 方法配置
   • 表
   • 用于源范围内参数化端点的表函数
   • 筛选器
   • 响应提取
   • 分页
   • 类型化列
4. 对源规范运行 lint 检查：
   • coral source lint <path>
5. 在合适的模式下验证源：
   • 独立规范：运行 coral source add --file <path>，并使用 coral sql 检查
   • 默认情况下，coral source add 以非交互方式运行：每个输入 key 都从对应的环境变量读取。运行前请导出必需的变量和密钥，或传入 --interactive 以接受提示。
   • 对于 OAuth 凭据方法，运行 coral source add --interactive --file <path>，且不要为目标密钥设置环境变量，这样 Coral 才会提供编写的凭据选项
   • 仓库源或已有名称的源：运行 coral source test <name>
6. 检查公开的结构：
   • 检查 coral.tables，查看可见表、描述、指南和必需筛选器；使用 LIMIT／OFFSET 限制元数据查询的范围
   • 检查 coral.table_functions，查看源范围内的函数、描述、指南、参数、结果列、类型和搜索限制
   • 检查 coral.columns，查看规范列元数据，包括 is_virtual 和 is_required_filter；按单个表筛选，或对大型列集合分页
   • 检查 coral.filters，查看规范化的表筛选器名称、类型、模式、必需标记和描述
   • 检查 coral.inputs，验证变量、密钥、默认值、提示和必需标记
7. 使用 coral sql 查询有代表性的表。
8. 如果依赖 coral source test，请确保 test_queries 能对源进行基本的冒烟测试／连接检查。
9. 完善规范并重复以上步骤。

编写规则

• 从小处着手，逐步扩展表覆盖范围。
• 将源清单架构既用作编写灵感，也用作结构验证依据：https://github.com/withcoral/coral/blob/main/crates/coral-spec/src/schema/source_manifest.schema.json
• 使用源变量配置非机密设置。
• 使用源密钥存储凭据。
• 对于基于 OAuth 的服务，使用 inputs.<TOKEN>.credential.methods[] 并设置 type: oauth 来建模设置流程；运行时的 auth 或请求标头应指向同一个密钥输入。
• OAuth 凭据方法支持设备码、授权码和客户端凭据流程。对于授权码流程，设置 flow.type: authorization_code，明确将 flow.pkce 设置为 required 或 disabled，使用 http://127.0.0.1 或 http://localhost 环回重定向 URI；对于允许使用可变 localhost 端口的提供商应用或动态客户端注册端点，选择 redirect_uri_port_mode: random；仅当用户可以注册确切的非零重定向 URI 时，才选择 fixed。如果浏览器无法访问运行 Coral 的机器，CLI 也接受用户粘贴到终端中的最终环回重定向 URL，因此不要仅因用户可能通过 SSH、在 VM 中或在浏览器与运行环境分离的环境中运行 Coral，就拒绝授权码 OAuth。对于设备码流程，声明 flow.type: device_code、endpoints.device_authorization_url、endpoints.token_url，以及公共客户端 ID 或 client.dynamic_registration；省略重定向 URI 字段，也不要声明静态客户端密钥。对于客户端凭据流程，声明 flow.type: client_credentials、endpoints.token_url、client.id.input、client.secret.input 和 client.secret.transport；省略重定向 URI 字段、授权端点、设备授权端点、PKCE 和动态客户端注册。
• 如果授权码或设备码提供商支持 OAuth 动态客户端注册，优先使用 client.dynamic_registration.registration_url，而不是硬编码共享的公共客户端 ID。Coral 始终注册原生客户端；源规范无法配置 web 类型的动态客户端注册应用。将 token_endpoint_auth_method 设置为 none、client_secret_basic 或 client_secret_post，以匹配注册的客户端类型。仅当提供商支持为客户端注册刷新令牌授权时，才将 request_refresh_token_grant: true。对于受 OAuth 保护的 Streamable HTTP MCP 服务，如果提供商要求资源指示符，则将 oauth.resource 设置为 MCP 服务 URL。
• OAuth URL 字段可以使用 {{input.KEY}} 模板化已声明的 kind: variable 输入，用于租户 ID 或域名等非机密端点组件。这包括 endpoints.*、resource 和 client.dynamic_registration.registration_url。不要在 OAuth URL 中引用密钥输入、筛选器、函数参数、状态或内联默认值。
• 如果提供商也支持手动粘贴令牌，则在 OAuth 方法后添加 type: source_config 回退方法。当提供商的令牌端点要求使用客户端密钥进行客户端身份验证时，请提示用户提供两个 OAuth 客户端值：声明 client.id.input、client.secret.input 和 client.secret.transport（basic_auth 或 request_body）。
• 不要仅为 OAuth 客户端凭据添加顶层源输入；client.id.input 和 client.secret.input 会在 OAuth 设置期间收集。
• 在 kind: identity 清单中，将提供商 issuer、身份 type、设置输入、OAuth URL、客户端 ID 和客户端密钥放在身份规范本身中。身份 OAuth client.id 可以使用 default、变量 input，或两者兼用；client.secret.input 必须引用已声明的密钥输入。OAuth URL 模板只能引用已声明的变量输入。身份输入不得声明源凭据方法。
• 每种凭据方法都可以选择性地包含 label、description 和 hint 字段，这些字段会在交互式安装期间以及生成的源文档中展示。当某个输入提供多种方法时，应将获取方式说明放在每种方法各自的 hint 中（显示在该方法的字段旁），而不是放在一个冗长的输入级 hint 中，并且每条提示都应仅针对该方法收集的输入。
• 对于有效期较短的 OAuth 访问令牌，请确保授权码或设备码方法在提供商支持时能够获取刷新令牌，并记录获取刷新令牌所需的任何范围、许可提示或客户端设置。当提供商返回可用的 expires_in 元数据时，客户端凭据方法会根据存储的客户端元数据重新签发访问令牌；如果没有此元数据，用户必须在令牌过期后重新连接。如果其他 OAuth 方法不会签发刷新令牌，请指出访问令牌过期后用户必须重新连接，除非该源支持其他长期有效的凭据途径。
• 表和表函数名称应保持稳定、符合 SQL 命名习惯，并且在源的大小写不敏感关系命名空间中唯一。优先使用普通的 snake_case 表名。表函数名称必须以 ASCII 字母或下划线开头，后续只能使用 ASCII 字母、数字或下划线。
• 仅当 API 确实要求时，才将筛选器标记为必需。
• 对于带参数的非检索操作（例如限定范围的子集合、时间范围日志、指标查询，或无法清晰映射到稳定表的详情操作），使用默认表函数。
• 对于接受查询文本并返回排序候选项的提供商端点，使用 kind: search 表函数。
• 如果提供商参数的类型不是字符串，则设置表函数参数的 type；省略参数类型时，默认使用 Utf8。
• 不要将提供商搜索建模为表筛选器。仅对普通的提供商端子串筛选使用 mode: contains。提供商排序检索应使用 kind: search 函数。
• 为每个 kind: search 函数添加 search_limits，并公开稳定的结果标识符，以供后续详情查询使用。
• API 结构已知时，优先使用显式分页。
• 使用实际行获取来验证分页，而不仅仅依赖 COUNT(*)。
• 需要让 coral source test 执行基本的冒烟测试或连接检查时，添加或更新 test_queries。

元数据 UX 规则

使用这些规则编写顶层源元数据，以确保源发现和设置过程一致。

description

• 以 Query ... 开头。
• 第一句突出能力：列出用户可以查询的关键实体。
• 建议使用以下模板：
  • Query <entities> from <Provider> (<Cloud or self-hosted when relevant>).
• description 应聚焦数据覆盖范围，而非设置步骤。
• 不要使用含糊的措辞，例如：
  • REST API v3
  • OpenAPI provider
  • ... and more
• 将身份验证、设置和权限详情放到输入提示中，不要写在描述文本里。

输入提示（inputs.<KEY>.hint）

每条提示都应说明：

• 需要什么值
• 如何获取该值
• 最低限度的范围／权限要求
• 适用时提供一个具体格式／示例

具体指导：

• 对于 URL／基础 URL 输入：
  • 说明默认值的含义
  • 至少提供一个具体示例
  • 支持可自托管部署时，提供相关指导
• 对于密钥：
  • 明确凭据的具体类型（API 密钥、PAT、应用密钥等）
  • 适用时说明格式限制（例如令牌前缀）
  • 提供最小权限范围建议
• 对于 OAuth 方法：
  • 使用面向用户的 label，例如 Connect with GitHub
  • description 应为简短的一句话说明；将设置详情放入该方法的 hint
  • 在该方法的 hint 中列出所需的 OAuth 范围，并说明用户是否必须注册固定的回环重定向 URI，或提供自己的 OAuth 客户端 ID／密钥；当该方法收集 client.id.input／client.secret.input 时，说明这些值的获取方式
  • 对于授权码流程，在该方法的 hint 中说明：如果浏览器无法直接访问 Coral 的回环监听器，用户可以将最终的 localhost 重定向 URL 粘贴到终端
  • 当某个密钥提供多种方法时，每种方法的 hint 只应涵盖该方法收集的输入，不要在一个宽泛的输入级提示中混合所有方法的指导
• 优先使用稳定的文档链接。
  • 使用官方文档链接和稳定的设置页面。
  • 避免将容易失效的点击路径说明作为主要指导。

提示应简洁且可直接执行。

验证流程

编写时使用以下流程：

# Export any required inputs first (key matches the input `key` in the spec),
# or pass --interactive to be prompted.
coral source lint ./my-source.yaml
coral source add --file ./my-source.yaml
coral source test my_source
coral sql "SELECT catalog_name, schema_name, table_name, description, required_filters FROM coral.tables WHERE schema_name = 'my_source' OR catalog_name = 'my_source' ORDER BY catalog_name, schema_name, table_name LIMIT 50 OFFSET 0"
coral sql "SELECT function_name, kind, arguments_json, result_columns_json, search_limits_json FROM coral.table_functions WHERE schema_name = 'my_source' ORDER BY function_name LIMIT 50 OFFSET 0"
coral sql "SELECT table_name, filter_name, filter_mode, is_required, data_type, description FROM coral.filters WHERE schema_name = 'my_source' OR catalog_name = 'my_source' ORDER BY table_name, filter_name LIMIT 100 OFFSET 0"
coral sql "SELECT table_name, column_name, data_type, is_virtual, is_required_filter, filter_mode, description FROM coral.columns WHERE schema_name = 'my_source' OR catalog_name = 'my_source' ORDER BY table_name, ordinal_position LIMIT 100 OFFSET 0"
coral sql "SELECT catalog_name, key, kind, value, default_value, hint, required, is_set FROM coral.inputs WHERE schema_name = 'my_source' OR catalog_name = 'my_source' ORDER BY key"

每个 WHERE 子句都会同时匹配两个限定字段，因为源通过架构或目录进行寻址。通过架构寻址的源会将源名称存储在 schema_name 中，并将 catalog_name 留空；数据库源则会将源名称存储在 catalog_name 中，其 coral.inputs 行的 schema_name 为空。 对于数据库源，仅按 schema_name 筛选会返回零行而不报告错误，给人的感觉就像“此源未声明任何内容”。

对于仓库源或已命名的源，请添加 test_queries，用于基本的冒烟／连接检查，然后运行：

coral source test my_source

然后运行有针对性的表查询，直到源运行正常。

HTTP 源

对于基于 HTTP 的源：

• 定义 backend: http
• 定义 base_url
• 定义身份验证标头或其他运行时身份验证字段
• 当设置流程应提供 OAuth 或其他凭据获取方式时，为机密输入定义 credential.methods
• 仅在需要时定义请求路径、查询参数和正文
• 为需要调用参数的提供商原生操作定义源级表函数
• 定义响应 rows_path
• 当已知提供商的分页模式时，明确配置分页
• 定义类型化列
• 确定哪些简单查询可以确认源基本正常后，添加 test_queries

需要表结构和分页指南时，请阅读 references/http-source-checklist.md。

如果 HTTP 源使用带前缀的 Authorization 标头（例如 Authorization: Bearer <token>），请将原始令牌设为机密输入，并使用 from: bearer 定义标头：

inputs:
  FOOBAR_API_TOKEN:
    kind: secret
    hint: Bearer token for the Foobar API.
auth:
  type: HeaderAuth
  headers:
    - name: Authorization
      from: bearer
      key: FOOBAR_API_TOKEN

对于由 OAuth 提供凭据的 HTTP 源，请将凭据获取方式添加到同一个机密输入中：

inputs:
  FOOBAR_API_TOKEN:
    kind: secret
    hint: Connect with Foobar OAuth or paste a token with read access.
    credential:
      methods:
        - type: oauth
          label: Connect with Foobar
          description: Open a browser and authorize Coral to read Foobar data.
          hint: |
            Signs you in through Foobar and requests the `read` scope. To
            use your own app, set FOOBAR_OAUTH_CLIENT_ID to its Client ID.
          oauth:
            flow:
              type: authorization_code
              pkce: required
            redirect_uri: http://127.0.0.1:0/oauth/callback
            redirect_uri_port_mode: random
            endpoints:
              authorization_url: https://foobar.example.com/oauth/authorize
              token_url: https://foobar.example.com/oauth/token
            client:
              id:
                input: FOOBAR_OAUTH_CLIENT_ID
            scopes:
              scope:
                delimiter: space
                values:
                  - read
        - type: source_config
          label: Paste token
          hint: Paste a Foobar API token with read access to the data you query.
auth:
  type: HeaderAuth
  headers:
    - name: Authorization
      from: bearer
      key: FOOBAR_API_TOKEN

当提供商接受完整粘贴的 API 密钥标头或 OAuth 访问令牌时，请将两种凭据输入都声明为可选机密，然后使用 from: one_of，并将完整标头值放在首位，后接 from: bearer OAuth 后备方式：

inputs:
  FOOBAR_API_KEY:
    kind: secret
    required: false
  FOOBAR_OAUTH_ACCESS_TOKEN:
    kind: secret
    required: false
auth:
  type: HeaderAuth
  headers:
    - name: Authorization
      from: one_of
      values:
        - from: input
          key: FOOBAR_API_KEY
        - from: bearer
          key: FOOBAR_OAUTH_ACCESS_TOKEN

本地数据源

对于基于本地文件的源：

• 定义文件后端
• 定义源位置
• 如适用，定义文件选择模式
• 定义类型化列

交付内容

报告：

• 源规范路径
• 使用的 lint / add / test 命令
• 运行的验证命令
• 做出的假设
• 受阻或未经验证的端点