astro-best
BEST 数据库数据源主理 skill —— 访问 nadc.china-vo.org/data/best 真实 REST API。
- License 许可
- MIT
- 所属仓库
- LL-LK/BEST
- 最近更新
- 2026-11-11
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- astro-best
- role
- data-source
- gates
- { "http_status": { "cmp": "==", "unit": "count", "value": 200 }, "checksum_match": { "cmp": "==", "unit": "bool", "value": true } }
- author
- LL-LK
- license
- MIT
- in_scope
- [ "NADC BEST REST 两阶段异步查询 (POST 表单 → sqlid → 分页 GET)", "12 张可查星表的锥形检索 / 批量交叉匹配 / 标准星 / 多波段测光", "流式下载 + 校验和 + 断点续传 (后台下载栈)", "IVOA TAP 1.1 适配面 (src/tap/, stdlib 零依赖传输)", "NADC OAuth2.0 身份层 (公开数据面免登录, 仅 /jobs 需要)" ]
- manifest
- manifest.yaml
- maturity
- alpha
- strength
- S2
- out_scope
- [ "通用星表检索/交叉匹配主理 → astro-catalog (球面 KD-Tree 锥搜; BEST 自身数据仍归本 skill)", "原始数据清洗 (2D 校准/剔除) → astro-clean" ]
- standalone
- true
- description
- BEST 数据库数据源主理 skill —— 访问 nadc.china-vo.org/data/best 真实 REST API。
- architecture
- architecture.md
- pipeline_stage
- collection
- redirect_policy
- table
02 资源文件 119
- 参考文档agents/openai.yaml1.2 KB
- 参考文档architecture.md9.9 KB
- 参考文档contracts/envelope.contract.yaml4.4 KB
- 参考文档contracts/error-codes.contract.yaml5.8 KB
- 参考文档contracts/fields/data.contract.yaml415 B
- 参考文档contracts/fields/sql.contract.yaml416 B
- 参考文档contracts/fields/status.contract.yaml427 B
- 参考文档contracts/fields/token.contract.yaml591 B
- 参考文档contracts/input.contract.yaml2.3 KB
- 参考文档contracts/io-contract.md4.8 KB
- 参考文档contracts/measurements/sort-columns.yaml6.0 KB
- 参考文档contracts/oauth.contract.yaml3.8 KB
- 参考文档contracts/output.contract.yaml1.1 KB
- 参考文档contracts/pipeline-stage.contract.yaml1.5 KB
- 参考文档contracts/provenance.contract.yaml1.1 KB
- 参考文档manifest.yaml5.5 KB
- 脚本rag/astro_rag.py31.1 KB
- 参考文档rag/knowledge/best_practices.yaml9.5 KB
- 参考文档rag/knowledge/citations.yaml7.2 KB
- 参考文档rag/knowledge/domain_rules.yaml3.2 KB
- 参考文档rag/knowledge/known_issues.yaml9.7 KB
- 参考文档rag/knowledge/lessons_learned.yaml27.4 KB
- 参考文档README.md34.4 KB
- 参考文档references/ALGORITHM-SPEC.md12.1 KB
- 参考文档references/auth-and-oauth.md11.1 KB
- 参考文档references/best-database-guide.md14.0 KB
- 参考文档references/client-api-reference.md12.3 KB
- 参考文档references/data-formats.md17.9 KB
- 参考文档references/download-playbook.md15.5 KB
- 参考文档references/fallback-protocols.md4.8 KB
- 参考文档references/llms.txt5.3 KB
- 参考文档references/photometric-systems.md7.7 KB
- 参考文档references/scientific-client-defenses.md19.4 KB
- 参考文档references/site-endpoints-and-interactions.md69.9 KB
- 参考文档references/skills-spec.local.yaml7.3 KB
- 参考文档references/tools.schema.json11.5 KB
- 脚本src/__init__.py4.3 KB
- 脚本src/__main__.py26.5 KB
- 脚本src/_paths.py4.3 KB
- 脚本src/ai_tools_envelope.py19.5 KB
- 脚本src/ai_tools.py50.8 KB
- 脚本src/auth/__init__.py7.0 KB
- 脚本src/auth/nadc_oauth.py41.8 KB
- 脚本src/auth/session.py13.4 KB
- 脚本src/best_export.py15.9 KB
- 脚本src/client_paging.py39.9 KB
- 脚本src/client_phase1.py24.0 KB
- 脚本src/client_query.py45.2 KB
- 脚本src/client_resolve.py6.1 KB
- 脚本src/client.py57.3 KB
- 脚本src/core/__init__.py14.7 KB
- 脚本src/core/pipeline.py6.4 KB
- 脚本src/core/processor.py773 B
- 脚本src/core/source_postprocess.py19.2 KB
- 脚本src/crossmatch_jobs.py20.6 KB
- 脚本src/crossmatch.py46.8 KB
- 脚本src/csv_safety.py5.0 KB
- 脚本src/download_artifacts.py43.5 KB
- 脚本src/download_hooks.py28.1 KB
- 脚本src/download_manager.py58.7 KB
- 脚本src/download_precise.py26.1 KB
- 脚本src/download_progress.py36.0 KB
- 脚本src/download_region.py15.6 KB
- 脚本src/download_sqlid.py20.5 KB
- 脚本src/downloader.py57.8 KB
- 脚本src/http_session.py4.5 KB
- 脚本src/kb/__init__.py3.7 KB
- 脚本src/knowledge_slots.py15.0 KB
- 脚本src/lightcurve.py961 B
- 脚本src/models/__init__.py43.1 KB
- 脚本src/models/input.py12.1 KB
- 脚本src/models/output.py16.3 KB
- 脚本src/multiband_photometry.py28.1 KB
- 脚本src/protocol_catalog_tables.py47.8 KB
- 脚本src/protocol.py83.1 KB
- 脚本src/provenance.py13.7 KB
- 其他src/py.typed—
- 脚本src/query_builder.py16.4 KB
- 脚本src/query.py708 B
- 脚本src/scripts/__init__.py5.7 KB
- 脚本src/scripts/best_cone_search.py3.6 KB
- 脚本src/scripts/best_crossmatch_pipeline.py10.4 KB
- 脚本src/scripts/best_multiband_export.py6.1 KB
- 脚本src/scripts/checkpoint.py6.7 KB
- 脚本src/scripts/config.py20.9 KB
- 脚本src/scripts/context.py5.7 KB
- 脚本src/scripts/guards.py24.6 KB
- 脚本src/scripts/io.py3.4 KB
- 脚本src/serialization.py37.4 KB
- 脚本src/tap/__init__.py4.1 KB
- 脚本src/tap/adql.py35.5 KB
- 脚本src/tap/client.py18.1 KB
- 脚本src/tap/executor.py17.3 KB
- 脚本src/tap/formats.py19.2 KB
- 脚本src/tap/jobs.py27.5 KB
- 脚本src/tap/response.py4.9 KB
- 脚本src/tap/service.py39.1 KB
- 脚本src/tap/uws_service.py33.0 KB
- 脚本src/task_log.py16.6 KB
- 参考文档static/core/output-format.md2.1 KB
- 参考文档static/core/stance.md1.0 KB
- 参考文档static/core/workflow.md971 B
- 参考文档static/fragments/algo_mode/best_auth_mode.yaml795 B
- 参考文档static/fragments/algo_mode/best_two_phase.yaml1.2 KB
- 参考文档static/fragments/algo_mode/two_stage_async_mode.yaml838 B
- 参考文档static/fragments/data_source/best_catalogs.md28.9 KB
- 参考文档static/fragments/data_source/nadc_endpoints.md9.6 KB
- 参考文档static/fragments/target_type/best_ttype.md802 B
- 参考文档static/fragments/target_type/photometry_region.md428 B
- 参考文档static/fragments/target_type/standard_star.md280 B
- 参考文档templates/best-config.yaml4.3 KB
- 参考文档templates/gen_case_prep_sql.yaml593 B
- 参考文档templates/gen_case_prep_token.yaml592 B
- 参考文档templates/gen_config_template.yaml1.7 KB
- 参考文档templates/gen_report_appendix.yaml1.1 KB
- 参考文档templates/gen_result_field_data.yaml573 B
- 参考文档templates/gen_result_field_status.yaml595 B
- 参考文档templates/gen_result_summary.yaml609 B
- 参考文档templates/report_template.yaml1.8 KB
03 SKILL.md 正文
astro-best — BEST 数据源主理 Skill
定位: BEST 数据库的唯一数据源主理方。 全 ecosystem 只有本 skill 能访问
nadc.china-vo.org/data/best(Django form 两阶段协议, 站点无 TAP/ADQL/REST-JSON 端点); astro-catalog 不具备 BEST 访问能力。
主理/委派边界契约
主理 In-Scope (本 skill 100% 负责, 不委派): NADC BEST REST 认证 (Django session + CSRF, src.auth.session/src.client)、两阶段异步查询 (POST 表单→sqlid→分页 GET) 与 12 张可查星表锥形检索/列约束 (src.client/src.protocol/src.query_builder/src.protocol_catalog_tables)、BEST 自身数据批量交叉匹配 (src.crossmatch.BestCrossMatch.crossmatch_batch 服务端 proximity 一次提交)、流式下载+校验和+断点续传 (src.downloader + src.download_manager 下载栈)、输出落盘 csv/txt/json/votable/fits (src.serialization)、标准星/多波段静态测光容器 (src.multiband_photometry/src.models)、IVOA TAP 1.1/UWS 适配 (src.tap)、NADC OAuth2.0 身份层 (src.auth.nadc_oauth)。
委派 Out-of-Scope (越界即转承接方): 通用星表检索与坐标交叉匹配 (SIMBAD/VizieR/Gaia/TNS, 球面 KD-Tree 锥搜) → astro-catalog; 原始数据清洗 (2D 校准/剔除) → astro-clean; NADC BEST 表单/两阶段异步客户端为外部数据源驱动, 不委派 (BEST 无 TAP/ADQL 端点, 仍归本 skill)。
第一步(强制)
阅读 README.md —— 逐文件能力边界表 + 文件树 SSOT + 治理规则; 未读 README 不得猜测目录用途或改动文件树结构。
治理铁律(人与 AI 同等约束)
- 禁版本号: 全仓不得出现发布版本号; 变更历史只记
CHANGELOG.md(已入版本控制)。 - 临时文件只进
temp/(gitignored); 其他位置出现临时文件即违规。 - 结构变更需批准, 内容编辑自由: 被跟踪文件/目录的新增/删除/移动/重命名、
.gitignore增删、README 树清单变更必须经用户明确同意 (批准后python ops/verify_tree_integrity.py --write重新生成树清单); 既有文件修 bug/补断言/补注释/改文档不需请示。 - 注释必须中文: 每个 class/function/method 都要有中文 docstring; import 组要有中文说明;
#注释行中文为主 (白名单: shebang /# noqa/# pragma: no cover/# legacy-import-guard/ 分隔线)。规范见docs/architecture/file-size-budget.md§4。 - 400 行预算: 单个
.py的净代码行 (总行 − 空行 −#注释 − docstring) 非必要不超过 400 行; 超限文件必须在docs/architecture/file-size-budget.md§3 登记必要性论证与拆分预案。度量:python ops/audit/count_code_lines.py。
API 快查 (模块 → 关键符号; 完整逐文件边界见 README src/ 表)
- 客户端/查询/下载/编排:
src.client(BestAuth/BestClient) ·src.query_builder(BestQuery) ·src.models(BestQueryResult) ·src.downloader(BestDownloader) ·src.crossmatch(BestCrossMatch) ·src.multiband_photometry(BestMultiBandPhotometry) ·src.core.source_postprocess(BestProcessor) ·src.core(QualityGate/BestSkillClient) ·src.core.pipeline(AstroBestPipeline) - 脚本入口:
src.scripts.best_cone_search(cone_search) ·src.scripts.guards(validate_adql_query) ·src.scripts.best_crossmatch_pipeline(crossmatch_with_gaia/batch_crossmatch) - 适配面/工具栈:
src.tap(IVOA TAP 1.1, stdlib 零依赖; 站点本身无 TAP 端点) ·src.ai_tools(ToolBox 7 原子工具 + 统一信封) ·src.auth.nadc_oauth· 下载栈 (download_manager/hooks/progress/precise/task_log)
质量门禁 (阻断性, 不足即 needs_review)
| 门禁 | 判定 | 阈值 | 单位 |
|---|---|---|---|
| http_status | == | 200 | count |
| checksum_match | == | True | bool |
接线状态 (未接线, 见 Q-08): 上述两条 blocking 门禁当前在生产链路没有填充点 —— 唯一求值实现
src/models/output.py的BestResultSet.gates_passed()本身正确且 fail-closed (缺省即判否), 但BestResultSet在src/内零生产构造点 (H6-02 与 V1 复扫 一致: 13 处构造全在test/unit/models/), 缺的只是构造链。故不要凭空声称这两条已判过: 无门可判时按agents/openai.yaml的honesty_stance显式记not_computable并转 needs_review。
场景路由
| 场景 | 入口 |
|---|---|
| 星表查询 / 锥搜 / 交叉匹配 / 标准星 / 多波段测光 | src/ (模块→类映射见 API 快查与 README src/ 表) |
| 本地冒烟/自检 | python ops/astro_best_cli.py doctor |
| 知识检索 (BM25+词桶+RRF 本地混合) | python ops/astro_best_cli.py rag "..." |
| 知识片段定向获取 (A· 编号) | python ops/astro_best_cli.py slots "..." |
| 实时记录 → 可选知识库主题 (离线可用) | python ops/astro_best_cli.py capture "..." |
| 配置查看/参考条目 | python ops/astro_best_cli.py config [--json] / refs |
| OAuth 授权 (仅 /jobs 需要) | python ops/astro_best_cli.py oauth |
| 下载管理 (后台/进度/取消/续传) | python ops/astro_best_cli.py download ... |
| 任务日志 | python ops/astro_best_cli.py log problems|tail |
| 工程命令 (test/test-cov/lint/lint-fix/install/distclean 等) | make help (目标清单见 Makefile) |
| 文件树校验 | python ops/verify_tree_integrity.py |
组件地图 (十二位一体)
- 加载地图
manifest.yaml(data-source 主理声明) · 架构规范architecture.md(五状态机 + 12 横切治理面 + 4 附加结构治理面) · 入口文档README.md(逐文件能力边界 + 文件树 SSOT + 治理规则) - 领域 RAG
rag/astro_rag.py+rag/knowledge/五件套 (best_practices/citations/domain_rules/known_issues/lessons_learned) · 白盒references/ALGORITHM-SPEC.md(G7 五要素, DOI 逐条核验) · 静态规则static/core/三件 +static/fragments/ - 角色
agents/openai.yaml(Persona) · 权重weights/README.md(无二进制权重声明) · 工具ops/astro_best_cli.py(env 驱动/零凭据) · 树门禁ops/verify_tree_integrity.py(README 树清单 SSOT 校验) · 实现与测试src/+test/
完成自检
- [ ] BEST 数据查询路由到本 skill, 未误转到 astro-catalog (后者无 BEST 端点)
- [ ] 旧调用路径全部保留,
python -m pytest test -q0 failed - [ ] SKILL.md ≤100 行 (G6), 长知识下沉 references/ 与 rag/
- [ ] 注释全中文 (零违规,
python ops/audit/comment_audit.py) + 超 400 净行已在docs/architecture/file-size-budget.md§3 登记 - [ ] 凭据只在 env, 路径锚定数据根 (
resolve_within) 无 ../ 逃逸; 临时文件只在temp/; 无版本号字段; 文件树与 README 清单一致 (verify 绿)
04 同仓库更多 Skills
astro-best
BEST 数据库数据源主理 skill —— 访问 nadc.china-vo.org/data/best 真实 REST API。
model_root_with_evals
暂无简介
model_root_with_doc
暂无简介
model_root_clean
暂无简介
astro-best
BEST 数据库数据源主理 skill —— 访问 nadc.china-vo.org/data/best 真实 REST API。
astro-best
BEST 数据库数据源主理 skill —— 访问 nadc.china-vo.org/data/best 真实 REST API。