coral-review-source-spec

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Review Source Spec

源规范审查

Review Goal

审查目标

Review the source as product surface. Do not spend the review mainly restating CI, schema validation, or YAML lint results unless those failures are visible and relevant. Focus on whether the source will be understandable, useful, safe, and consistent for Coral users and agents.

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

Workflow

工作流程

Identify the target source directory or PR changes.
- For a path request, inspect
```
manifest.yaml
```
  , any README, and related source docs or tests.
- For a PR request, find changed files under
```
sources/core/
```
  or
```
sources/community/
```
  . If the PR does not add or update a source, say the skill is not applicable and review normally.
Read guidance in the Coral repo before judging style:
- ```
CONTRIBUTING.md
```
  , especially "Source contributions".
- The repo
```
AGENTS.md
```
  and any nearer
```
AGENTS.md
```
  .
- Similar existing sources in
```
sources/core/
```
  and the community example in
```
sources/community/hn/
```
  .
Compare against existing source patterns, not a generic API-wrapper ideal. Look at nearby sources with similar shape: public no-auth APIs, token APIs, GraphQL APIs, search-heavy APIs, log/time-series APIs, or generated large API sources.
Produce a code-review style result: findings first, ordered by severity, with file and line references. Include open questions only after findings. If there are no substantive issues, say so and mention residual risks or review gaps.

确定目标源目录或PR变更内容。
- 若为路径请求，检查
```
manifest.yaml
```
  、任何README文件及相关源文档或测试。
- 若为PR请求，查找
```
sources/core/
```
  或
```
sources/community/
```
  下的变更文件。若PR未添加或更新源，请说明本技能不适用，并按常规方式进行审查。
在判断风格前，阅读Coral仓库中的指南：
- ```
CONTRIBUTING.md
```
  ，尤其是「Source contributions」部分。
- 仓库中的
```
AGENTS.md
```
  及任何就近的
```
AGENTS.md
```
  文件。
- ```
sources/core/
```
  中的现有同类源，以及
```
sources/community/hn/
```
  中的社区示例源。
与现有源模式对比，而非通用API包装器的理想模式。查看具有相似类型的同类源：无认证公共API、令牌API、GraphQL API、搜索密集型API、日志/时间序列API，或生成式大型API源。
生成代码审查风格的结果：先列出发现的问题，按严重程度排序，并标注文件和行号引用。仅在问题之后列出开放性问题。若无实质性问题，请明确说明，并提及潜在风险或审查空白。

Review Checklist

审查检查清单

These checks should be based on the authoritative API docs for the API the source exposes.

这些检查应基于源所暴露API的官方API文档。

Scope and Fit

范围与适配性

Source belongs in the right tree:
```
sources/community/
```
for community sources; new
```
sources/core/
```
additions need prior discussion per
```
CONTRIBUTING.md
```
. PRs from external contributors should almost always be in
```
sources/community
```
.
If reviewing a new source, ensure it doesn't replicate the functionality of an existing source.
Source name is clear, stable, lowercase, and matches the SQL schema users will type.
Scope is narrow enough to be coherent. A small source should expose the main user workflows, not every marginal endpoint.
No real credentials, customer data, internal fixtures, or private URLs are committed.
Updated sources bump
```
version
```
when user-visible behavior, tables, columns, inputs, or semantics change.

源归属正确目录：社区源放在
```
sources/community/
```
；新增
```
sources/core/
```
源需先根据
```
CONTRIBUTING.md
```
进行讨论。外部贡献者的PR几乎应全部放在
```
sources/community
```
目录下。
若审查新源，确保其未复制现有源的功能。
源名称清晰、稳定、小写，且与用户将输入的SQL schema匹配。
范围足够窄，保证连贯性。小型源应暴露主要用户工作流，而非每个边缘端点。
提交内容中无真实凭证、客户数据、内部测试数据或私有URL。
当源的用户可见行为、表、列、输入或语义发生变化时，更新源需升级
```
version
```
版本号。

Setup and Documentation

设置与文档

Top-level
```
description
```
says what a user can query, not just what vendor API is wrapped.
```
inputs
```
distinguish secrets from variables correctly, use clear environment-style names, and include enough hints for first success. Environment-style names are prefixed with a service-specific prefix (e.g.
```
GITHUB_API_TOKEN
```
, not
```
API_TOKEN
```
.)
Auth docs mention required token type, scopes or permissions, and where to get credentials.
Non-trivial sources include README or manifest guides with setup, schema orientation, and example queries.
Behavior changes, setup changes, source semantics, and examples are documented in the same PR.

顶级
```
description
```
说明用户可查询的内容，而非仅说明封装了哪个厂商API。
```
inputs
```
正确区分密钥与变量，使用清晰的环境风格名称，并包含足够提示以帮助首次成功使用。环境风格名称需带有服务特定前缀（例如
```
GITHUB_API_TOKEN
```
，而非
```
API_TOKEN
```
）。
认证文档提及所需令牌类型、权限范围，以及获取凭证的位置。
非简单源需包含README或清单指南，涵盖设置、schema说明及示例查询。
行为变更、设置变更、源语义及示例需在同一PR中完成文档更新。

Query Ergonomics

查询易用性

Tables model useful user concepts: dimension tables such as users, projects, channels, services, teams, repositories, or metadata are easy starting points.
High-cardinality or expensive endpoints require filters or have conservative
```
fetch_limit_default
```
values.
Required filters are explicit and described in table
```
description
```
or
```
guide
```
.
Guides tell users how to start, which IDs to join through, and any provider-specific timestamp or query syntax traps.
Search-like operations use search filters or table functions when that is clearer than pretending the endpoint is a normal list table.
Table and column names are snake_case, stable, and obvious. Avoid leaking odd provider operation names unless the source is intentionally generated.

表对有用的用户概念进行建模：维度表（如用户、项目、渠道、服务、团队、仓库或元数据）是易用的起点。
高基数或高成本端点需设置过滤器，或使用保守的
```
fetch_limit_default
```
值。
必填过滤器需在表的
```
description
```
或
```
guide
```
中明确说明。
指南告知用户如何开始、需关联哪些ID，以及任何供应商特定的时间戳或查询语法陷阱。
类搜索操作应使用搜索过滤器或表函数，而非将端点伪装成普通列表表。
表和列名称采用snake_case格式，稳定且直观。除非源是有意生成的，否则避免暴露供应商特有的操作名称。

HTTP and API Semantics

HTTP与API语义

```
base_url
```
and input-derived URLs handle hosted, cloud, region, or enterprise variants without making the common case painful.
Auth headers and request headers match provider expectations, including API version or Accept headers when needed.
Pagination mode, cursor paths, page size limits, and result paths reflect the actual API response, not a guessed pattern.
```
ok_path
```
,
```
error_path
```
,
```
allow_404_empty
```
, and rate-limit hints are present when the provider's API behavior needs them.
Required API permissions are not broader than needed for the exposed read-only surface.

```
base_url
```
及输入派生的URL可处理托管、云、区域或企业变体，且不会让常见使用场景变得复杂。
认证头和请求头符合供应商预期，必要时包含API版本或Accept头。
分页模式、游标路径、页面大小限制及结果路径反映实际API响应，而非猜测的模式。
当供应商API行为需要时，需包含
```
ok_path
```
、
```
error_path
```
、
```
allow_404_empty
```
及速率限制提示。
所需API权限不应超出暴露的只读界面的需求范围。

Column Design

列设计

Columns preserve stable identifiers and include human-readable names where available.
Opaque IDs and very large numeric IDs are usually
```
Utf8
```
; use numeric types for values users should compare or aggregate numerically.
```
Timestamp
```
columns are exposed for important times when Coral can reliably parse or derive them; keep raw provider timestamp fields only when useful.
```
nullable
```
matches provider reality. Do not mark fields non-null just because examples happened to contain them.
Nested objects are flattened only when the fields are broadly useful; otherwise expose JSON/text columns rather than creating brittle, low-value columns.
Column descriptions are concise and user-facing.

列保留稳定标识符，并在可用时包含人类可读名称。
不透明ID和超大数值ID通常设为
```
Utf8
```
类型；对用户需要进行数值比较或聚合的值使用数值类型。
当Coral可可靠解析或推导时，需暴露重要时间点的
```
Timestamp
```
列；仅在有用时保留原始供应商时间戳字段。
```
nullable
```
属性与供应商实际情况匹配。不要仅因为示例中包含字段就将其标记为非空。
仅当嵌套对象中的字段广泛有用时才进行扁平化处理；否则暴露JSON/文本列，而非创建脆弱、低价值的列。
列描述简洁且面向用户。

Style Consistency

风格一致性

YAML is readable and follows existing manifest ordering: identity, inputs/auth/base URL, test queries, functions/tables.
Existing core sources use short table descriptions plus
```
guide
```
blocks for usage advice; prefer that split.
README structure, when present, should resemble existing source READMEs: authentication, rate limits when relevant, table categories or schema overview, and examples.
Wording should be clear to a new user. Avoid internal Coral implementation terms unless they are part of the user-facing source-spec surface.

YAML格式可读，并遵循现有清单的排序顺序：标识信息、输入/认证/基础URL、测试查询、函数/表。
现有核心源使用简短的表描述加
```
guide
```
块提供使用建议；优先采用这种拆分方式。
若存在README文件，其结构应与现有源README相似：认证、相关速率限制、表类别或schema概述，以及示例。
措辞需对新用户清晰易懂。避免使用Coral内部实现术语，除非它们属于面向用户的源规范界面的一部分。

Output Shape

输出格式

Lead with concrete findings. Use severity labels only when helpful, but do not bury issues under a summary. Prefer:

text

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.

If no issues are found, say that directly and include any limits, such as not having live credentials or not inspecting CI logs.

When highlighting a discrepancy between the source and the API documentation, always include links to the exact API documentation page.

以具体发现的问题开头。仅在有帮助时使用严重程度标签，但不要在总结下隐藏问题。建议格式如下：

text

发现的问题
- 高优先级：`sources/community/foo/manifest.yaml:42` 将`created_at`标记为非空，但供应商对导入记录会省略该字段...
- 中优先级：`sources/community/foo/README.md:18` 展示了设置步骤，但未说明所需令牌权限范围...

开放性问题
- 端点X是否故意在第一版中省略？

审查说明
- 除非在差异中可见，否则我将CI检查/schema验证视为超出审查范围。

若无问题，直接说明，并提及任何限制条件，例如没有可用的真实凭证或未检查CI日志。

当指出源与API文档之间的差异时，务必包含指向具体API文档页面的链接。