coral-review-source-spec

Coral Review Source 规范

审核目标

将源视为产品界面进行审核。除非 CI、架构验证或 YAML 检查的失败可见且相关，否则不要将审核重点放在复述这些结果上。重点关注源对 Coral 用户和 Agent 是否易于理解、有用、安全且一致。

工作流

1. 确定目标源目录或 PR 变更。
   • 对于路径请求，检查 manifest.yaml、任何 README，以及相关源文档或测试。
   • 对于 PR 请求，查找 sources/core/ 或 sources/community/ 下的变更文件。如果 PR 没有新增或更新源，请说明此技能不适用，并按常规方式审核。
2. 在判断风格前，阅读 Coral 仓库中的指南：
   • CONTRIBUTING.md，尤其是“Source contributions”。
   • 仓库中的 AGENTS.md 以及更近目录中的任何 AGENTS.md。
   • sources/core/ 中的类似源，以及 sources/community/hn/ 中的社区示例。
3. 与现有源的模式进行比较，而不是套用通用的 API 封装理想。查看形态相似的相邻源：无需身份验证的公共 API、令牌 API、基于 OAuth 的 API、GraphQL API、以搜索为主的 API、日志/时间序列 API，或生成的大型 API 源。
4. 按代码审查风格给出结果：先列问题，按严重程度排序，并注明文件和行号。只有在问题之后才列出未决问题。如果没有实质性问题，请说明这一点，并提及剩余风险或审查盲区。

审核清单

这些检查应以源所公开 API 的权威文档为依据。

范围与适配性

• 源应放在正确的目录中：社区源应放在 sources/community/；新增 sources/core/ 内容需事先按照 CONTRIBUTING.md 进行讨论。外部贡献者提交的 PR 几乎总是应该放在 sources/community。
• 如果审核的是新源，确保它没有重复现有源的功能。
• 源名称应清晰、稳定、使用小写，并与用户将输入的 SQL 架构名称一致。
• 范围应足够聚焦且逻辑连贯。小型源应公开主要用户工作流，而不是覆盖所有边缘端点。
• 不得提交真实凭据、客户数据、内部测试数据或私有 URL。
• 更新源时，如果用户可见行为、表、列、输入或语义发生变化，应递增 version。

设置与文档

• 顶层 description 应说明用户可以查询什么，而不只是说明封装了哪个供应商 API。
• inputs 应正确区分机密与变量，使用清晰的环境变量风格名称，并提供足够的提示，帮助用户首次成功使用。环境变量风格名称应带有服务专属前缀（例如 GITHUB_API_TOKEN，而不是 API_TOKEN）。
• 无论凭据的权限是否为只读，或身份验证模式是否为可选，都应将类似凭据的输入视为机密。名称或描述中包含 API_KEY、TOKEN、ACCESS_TOKEN、PASSWORD、SECRET、APPLICATION_KEY、READ_KEY、ADMIN_KEY、私钥、Bearer 值或授权标头值的输入必须设置为 kind: secret；端点、基础 URL、站点、区域、域、组织、账户、用户或电子邮件值可以设置为 kind: variable。
• 不要将凭据设为带空默认值的变量，以此模拟可选身份验证。对于当前的 source-spec 功能，必须要求提供机密，或明确指出缺少可选身份验证设计；绝不要仅为支持匿名安装而暴露令牌。
• 身份验证文档应说明所需的令牌类型、作用域或权限，以及获取凭据的方式。
• 如果机密声明了 credential.methods，每种方法都必须符合供应商支持的设置路径。OAuth 方法应使用设备代码、授权码或客户端凭据流程。授权码方法必须明确设置 pkce 值和环回重定向 URI，使用正确的重定向端口模式，并支持 SSH、VM 和分离浏览器设置；在 CLI 等待环回回调时，用户可以粘贴最终的本地主机重定向 URL。设备代码方法必须包含 device_authorization_url，不得包含重定向 URI 字段，也不得包含静态客户端机密。客户端凭据方法必须包含 token_url、client.id.input、client.secret.input 和 client.secret.transport，且不得包含重定向 URI 字段、授权端点、设备授权端点、PKCE 或动态客户端注册。所有 OAuth 方法都必须使用正确的端点 URL、适当的客户端 ID／默认值／输入行为、适用时正确的客户端机密传输方式，以及遵循最小权限原则的作用域。对于授权码或设备代码动态客户端注册，Coral 始终注册原生客户端，source spec 无法配置 web 应用类型；只有当供应商支持注册刷新令牌授权时，才应包含 request_refresh_token_grant: true。如果受 OAuth 保护的 Streamable HTTP MCP 源要求资源指示符，则应包含 oauth.resource。OAuth URL 模板只能引用已声明的 kind: variable 输入，用于非机密 URL 组件。
• OAuth 方法不能替代运行时身份验证。供应商需要时，仍须通过 auth、请求标头、查询参数或正文中的字段引用已存储的机密。
• OAuth 设置文档应告知用户是否需要自己的 OAuth 客户端、适用时需要注册哪个重定向 URI、需要授予哪些作用域，以及签发刷新令牌所需的任何供应商／客户端设置。只有当供应商返回可用的 expires_in 元数据时，客户端凭据方法才能依靠重新签发短时有效的访问令牌；否则，令牌过期后用户必须重新连接。对于供应商不会签发刷新令牌的其他方法，也应说明访问令牌过期后用户必须重新连接。
• 同时支持 OAuth 和粘贴令牌设置时，方法的顺序和标签应清楚表明首选路径，通常先列 OAuth，再列 source_config 备用方案。
• 非简单的源应提供 README 或清单指南，说明设置方式、架构概览和查询示例。
• 行为变更、设置变更、源语义和示例都应在同一个 PR 中记录。

查询体验

• 表应体现有用的用户概念：用户、项目、频道、服务、团队、代码库或元数据等维度表都是不错的起点。
• 高基数或开销较大的端点必须要求筛选条件，或设置较保守的 fetch_limit_default 值。
• 必需的筛选条件应明确列出，并在表的 description 或 guide 中说明。
• 指南应告知用户如何开始、通过哪些 ID 进行关联，以及任何特定于提供方的时间戳或查询语法陷阱。
• 接受查询文本并返回排序候选项的提供方端点，应使用带有 search_limits、稳定结果标识符和实用候选项元数据的 kind: search 表函数。非检索型表函数应保留默认类型，用于带参数的操作，例如限定范围的子集合、时间范围日志、指标查询或详情操作。普通表筛选条件用于精确查找、限定范围或提供方端筛选；mode: contains 仅用于子串匹配。如果将提供方原生搜索建模为筛选条件，应标记出来并要求改用 kind: search 函数。
• 表、表函数和列的名称应采用 snake_case，保持稳定且一目了然。 表名和表函数名在源的 不区分大小写的关系命名空间内必须唯一。表函数名必须符合 SQL 标识符语法：以 ASCII 字母或下划线开头，之后仅使用 ASCII 字母、数字或下划线。表名优先使用普通的 snake_case；为兼容性而使用带引号的 SQL 表名也有效，但除非该源有意通过生成方式创建，否则不应暴露奇特的提供方操作名称。

HTTP 和 API 语义

• base_url 和基于输入生成的 URL 应能处理托管版、云端、区域版或企业版等变体，同时避免让常见使用场景变得繁琐。
• 身份验证标头和请求标头应符合提供方要求，必要时包括 API 版本或 Accept 标头。
• 分页模式、游标路径、页面大小限制和结果路径应反映 API 的实际响应，而非猜测的模式。
• 如果提供方的 API 行为有此需求，应提供 ok_path、error_path、allow_404_empty 和速率限制提示。
• 所需的 API 权限不应超出已公开的只读功能范围。

列设计

• 列应保留稳定标识符，并在可用时包含便于人类阅读的名称。
• 不透明 ID 和非常大的数值 ID 通常应使用 Utf8；对于用户应进行数值比较或聚合的值，则使用数值类型。
• 对于重要时间，如果 Coral 能够可靠地解析或推导，应公开为 Timestamp 列；仅在有用时才保留原始提供方时间戳字段。
• nullable 应符合提供方的实际情况。不要仅仅因为示例中包含某些字段，就将其标记为非空。
• 仅当嵌套对象中的字段普遍有用时才将其扁平化；否则应公开 JSON/文本列，避免创建脆弱且价值低的列。
• 列描述应简洁，并面向用户。

风格一致性

• YAML 应易于阅读，并遵循现有清单的顺序：标识信息、输入/身份验证/基础 URL、测试查询、函数/表。
• 现有核心源使用简短的表描述，并通过 guide 块提供使用建议；优先采用这种拆分方式。
• 如果提供 README，其结构应与现有源 README 相似：身份验证、相关时的速率限制、表类别或架构概览，以及示例。
• 表述应让新用户也能理解。除非 Coral 内部实现术语属于面向用户的源规范接口，否则应避免使用。

输出格式

先列出具体发现。仅在有帮助时使用严重程度标签，不要把问题埋在摘要之下。优先采用：

Findings
- High: `sources/community/foo/manifest.yaml:42` marks `created_at` non-null, but the provider omits it for imported records...
- Medium: `sources/community/foo/README.md:18` shows setup but never states the required token scope...

Open questions
- Is endpoint X intentionally omitted from the first version?

Review notes
- I treated CI lint/schema checks as out of scope unless visible in the diff.

如果没有发现问题，应直接说明，并列出任何限制，例如没有实时凭据或未检查 CI 日志。

指出源与 API 文档之间的差异时，始终附上指向确切 API 文档页面的链接。