尧图网站建设 
Gtars Refget 实战指南序列摘要、序列存储与 BEDbase 缓存的安全使用【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills本文围绕 Gtars 的 refget 组件gtars-refget0.9.1Python 侧gtars0.9.2CLI 侧gtars-cli0.9.0展开讲解 GA4GH refget 序列摘要sequence digest的术语与计算方式、RefgetStore存储类的内存/磁盘/远程三种模式、远程存储的网络审批门禁、只读并发转换、gtars refget build命令行建库以及独立的 BEDbasebbcache缓存命令。你读完可以立即在自己的流程中计算并校验序列摘要、构建和复用本地 refget 存储并清楚远程存储与 BEDbase 下载在何种前提与限制下才能安全使用。验证快照与版本基线本文所有事实均以仓库文档记录的2026-07-23验证快照为准Python 绑定gtars0.9.2PyPIRequires-Python 3.10包含 PyO3 原生扩展Rust 直接组件gtars-refget0.9.1CLI 包gtars-cli0.9.0安装后的二进制名为gtars。Gtars 上游有意对工作区各 crate、Python 绑定和 CLI 独立编号因此数字相同不代表构件相同例如gtars0.9.0这个 meta-crate 自身固定的是 refget 0.9.0而直接依赖gtars-refget则是 0.9.1两者在补丁行为上不应假设一致。具体可对照 技能主文档 中的版本说明。由于仓库与上游文档可能存在漂移实践前应以安装后的签名冒烟测试和带版本 tag 的源码为准。序列摘要术语与计算refget 是 GA4GH 定义的按内容寻址检索参考序列的规范核心思想是用序列内容本身计算出的摘要digest作为序列的稳定标识符。摘要变了意味着序列内容变了摘要稳定就可以跨数据库、跨工具、跨环境地标识同一条参考序列。当前 Python 函数集中在gtars.refget子模块from gtars.refget import ( compute_fai, digest_fasta, digest_sequence, load_fasta, md5_digest, sha512t24u_digest, ) digest sha512t24u_digest(ACGT) assert digest aKF498dAxcJAqme6QYQ7EZ07-fiw8Kw2 assert md5_digest(ACGT) f1f8f4bf413b16ad135722aa4591043e几点必须澄清的术语事实sha512t24u的形态Gtars 返回的是32 字符、不带SQ.前缀的字符串。GA4GH refget 规范推荐的序列标识符还要加上SQ.前缀SQ.aKF498dAxcJAqme6QYQ7EZ07-fiw8Kw2在仓库的离线校验脚本 refget_digest_plan.py 中该摘要的实现是hashlib.sha512(sequence.upper()).digest()[:24]再经 URL-safe Base64 编码并去掉填充——也就是说先对序列做全大写规范化再取 SHA-512 截断的前 24 字节最后 Base64URL 编码这与_SHA512T24U re.compile(r^[A-Za-z0-9_-]{32}$)的形状校验脚本第 30 行完全吻合。MD5 的定位md5_digest仅为遗留系统查询保留它不是抗碰撞的来源完整性哈希。需要独立保存一条 SHA-256 用于制品完整性校验——这与仓库技能一贯的“SHA-256 记录 refget 域摘要”双轨策略一致。摘要计算的输入必须是规范化后的序列GA4GH refget 在计算序列标识符之前会对序列内容做规范化。绝不能直接把原始 FASTA 字节丢进哈希函数就称为“序列摘要”。FASTA 头header、行折叠line wrapping、压缩方式和序列规范化属于不同层次头信息不参与序列内容\n折叠不该改变生物学序列.gz压缩更是与序列内容无关。所以digest_sequence会先对序列字节做大写处理。辅助函数的分工digest_sequence(data: bytes, nameNone, descriptionNone)——对序列字节做大写规范化返回包含元数据与序列数据的SequenceRecorddigest_fasta(path)——计算一个SequenceCollectionload_fasta(path)——把序列数据载入内存compute_fai(path)——针对未压缩FASTA 计算索引.fai。摘要正确性的可验证锚点仓库测试 tests/gtars/test_scripts.py 中test_refget_digest_validation_uses_known_acgt_digest验证了 “ACGT” 这一已知摘要测试构造了包含chr1 synthetic与acgt的小型 FASTA用sha512t24u(bACGT)测试内与脚本内相同的实现生成期望值再调用refget_digest_plan.py校验最终断言result[fasta][all_sequence_digests_match]为真且contract[store_opened]为假。这证明同样的规范化规则在技能脚本与 Gtars 运行时之间保持一致且校验过程完全离线、不打开任何存储。RefgetStore当前 Python 存储类运行时类名是RefgetStore而不是旧教程里的GlobalRefgetStorefrom gtars.refget import RefgetStore已验证的构造函数RefgetStore.in_memory() RefgetStore.on_disk(cache_path) RefgetStore.open_local(path) RefgetStore.open_remote(cache_path, remote_url) RefgetStore.store_exists(path)在设计上SKILL.md 明确建议优先使用in_memory()或open_local(path)open_remote会联网并产生缓存副作用必须走审批门禁见下文。迁移陷阱列表SKILL.md 的 “Migration traps” 一节也强调不要再使用过时的gtars.RefgetStore顶层导入形式。内存模式与本地持久化from gtars.refget import RefgetStore store RefgetStore.in_memory() metadata, was_new store.add_sequence_collection_from_fasta( reviewed-reference.fa, forceFalse, namespaces[refseq], ) store.write_store_to_dir(approved-store) reopened RefgetStore.open_local(approved-store)各模式/方法的副作用边界in_memory()——不写任何文件纯内存构造on_disk(path)——打开已有存储或新建一个磁盘后端存储open_local(path)——读取存储的元数据/索引惰性加载本地序列数据write_store_to_dir与enable_persistence——会创建/写入文件forceTrue——可以替换已有的 collection/sequence 条目。操作前应先store_exists(path)判断选择“新建”还是“打开”。仓库的安全约定还要求拒绝符号链接、意外文件、输出冲突和未获批的存储目录该约定与 scripts/_common.py 中local_path严格拒绝 URL、~展开、..穿越与符号链接的本地路径策略一致。批量导入results store.add_sequence_collections_from_fastas( [ref-a.fa.gz, ref-b.fa.gz], file_listNone, jobs1, forceFalse, namespaces[refseq], )fastas参数还可以接受glob 或目录jobs0表示自动并发。对于受控运行应显式枚举已审查的文件并设置一个正数、有界的作业数避免通配符意外扩展到未审查文件。元数据访问与序列访问的区分RefgetStore刻意区分两类方法元数据方法不加载完整序列内容collections_page store.list_collections(page0, page_size100) sequence_metadata store.list_sequences() one_metadata store.get_sequence_metadata(sequence_digest) collection_metadata store.get_collection_metadata(collection_digest)数据方法record store.get_sequence(sequence_digest) by_name store.get_sequence_by_name(collection_digest, chr1) piece store.get_substring(sequence_digest, 100, 200) pieces store.get_substrings(sequence_digest, [(100, 200), (500, 550)]) for chunk in store.stream_sequence( sequence_digest, start0, end1_000_000, chunk_size65_536, ): consume_bounded(chunk)关键语义子串区间是0 基、半开区间[start, end)务必校验0 start end lengthstream_sequence能约束峰值结果内存按chunk_size分块但如果下游把每个 chunk 都累积起来流式依然可能被打败——所以仍要给下游累积设定显式预算0.9.2 运行时还暴露load_sequence、load_collection、load_all_sequences、load_all_collections。这些方法会实体化更多数据load_all_*尤其危险没有显式的字节/内存预算就绝不调用。远程存储必须经过审批门禁# Network cache side effects: do not call before approval. remote RefgetStore.open_remote( approved_cache_path, approved_https_base_url, )open_remote只接受缓存路径和基础 URL 两个参数。它会拉取远程元数据、创建/复用本地缓存状态并且默认启用持久化。在 0.9.2 中get_substring可以发起远程字节区间读取range read而不必下载整条序列stream_sequence可以流式读取远程区间load_sequence是整条序列路径并可能将其持久化。重要限制open_remote之后调用disable_persistence()并不能撤销已经执行的元数据/缓存工作而且该构造器没有任何参数用于指定 revision、端点白名单、校验清单checksum manifest、字节配额或离线模式。换句话说远程模式的所有防护都必须由调用方在调用之前完成。在调用open_remote之前文档要求完成 7 项审批动作对确切的 HTTPS 主机/路径和缓存目录取得显式批准拒绝 URL 中携带的凭据以及未经审查的重定向固定一个不可变的服务器/存储 revision 或内容寻址标识符记录期望的 collection/sequence 摘要并在适用时记录独立的 SHA-256对元数据、单区间、总传输量、序列长度、缓存、重试、并发和时间设定上限披露请求坐标/摘要和网络元数据会离开当前环境在科学使用之前校验返回的长度与摘要。需要注意即使公共参考基因组本身不敏感定制/患者特异性组装体和请求区间也可能是敏感的。这与 SKILL.md 的“网络与缓存门禁”一节一致——所有网络能力调用前都要记录不可变 revision、期望 SHA-256、域摘要、组装号、大小配额与出处并把下载内容当作不可信数据处理。只读并发存储into_readonlyreadonly store.into_readonly()into_readonly()把可变存储转换为ReadonlyRefgetStore用于并发读取。它有两条硬约束它消耗/替换原可变存储对象它不能惰性加载那些转换前未准备的 collections。因此转换之前只应加载所需的、有界的数据不要反射性地使用load_all_*否则会把超出预算的数据带入只读并发场景。CLI 建库gtars refget build当前 refget 唯一的 CLI 子命令是本地存储构建没有digest、verify或远程查询子命令gtars refget build reference.fa reference-alt.fa.gz \ --output approved-store \ --jobs 1选项--file-list/-f PATH一个文件内含路径/glob/目录列表--output/-o DIR必填--jobs/-j N并发处理的 FASTA 文件数默认0自动--raw使用原始存储而不是默认的编码 2-bit 存储--force覆盖已有条目。注意--jobs 0是自动并发与add_sequence_collections_from_fastas的jobs0语义一致。旧技能中存在的gtars refget digest/verifyCLI 在当前版本不存在需要摘要计算时请使用 Python 摘要函数、直接 Rust API或在 preflight 之后做一次本地存储构建。CLI 层面也没有全局线程/内存/缓冲参数cli.md 确认 0.9.0 无--threads、--memory-limit等全局选项并发控制全部是命令级。离线元数据/摘要计划refget_digest_plan.py技能附带了一个离线辅助脚本接受一份保守的本地策略清单manifest。这是一份skill 策略清单并非上游 refget 线上 schema{ schema_version: 1.0, assembly: GRCh38.p14, coordinate_system: 0-based-half-open, collection_digest: 32-char sha512t24u-like value, sequences: [ { name: chr1, length: 248956422, sha512t24u: 32-char digest, md5: 32 lowercase hex } ] }运行方式可选用本地 FASTA 重算序列级摘要python3 -B scripts/refget_digest_plan.py \ --metadata refget-metadata.json \ --fasta reference.fa.gz \ --assembly GRCh38.p14从源码refget_digest_plan.py可以确认其行为边界它不会重算 collection 摘要collection_digest只做形状校验32 字符[A-Za-z0-9_-]并输出警告collection_digest_shape_only_not_recomputed第 162-168 行它校验清单结构与期望组装号/坐标系统schema_version必须为1.0、assembly必须与--assembly完全一致、coordinate_system必须为0-based-half-open否则报错逐条序列校验长度、sha512t24u 与 MD5提供--fasta时按名称比对报告缺失序列、意外序列、长度不一致、sha512t24u 不一致与 MD5 不一致五类错误码并输出 FASTA 文件的 SHA-256 与字节数不联网、不开存储、不写输出、不 import gtars报告的contract明确列出network_used: false、store_opened: false、cache_written: false、packages_imported: false第 271-279 行硬上限内置默认--max-bytes 2 GiB、--max-records 5,000,000且受 scripts/_common.py 中HARD_MAX_BYTES 8 GiB、HARD_MAX_RECORDS 10,000,000的硬边界约束输出的approved_execution_plan是一组固定建议文本如“优先RefgetStore.open_local”、“新存储用in_memory验证后再显式持久化”、“open_remote前记录白名单/固定 revision/期望摘要/缓存路径/字节配额/审批”等。最终 collection 的权威验证仍应使用Gtars 固定版本的 collection 实现即实际调用gtars的 seqcol 逻辑。测试 tests/gtars/test_scripts.py 还验证了该脚本即使校验失败也只输出 JSON、不泄漏本地绝对路径默认--path-mode redacted并验证了 URL 形式路径会被拒绝。BEDbase 缓存bbcache与 refget 的区分BEDbase 缓存独立于 refget它处理的是 BED 区间文件与 BED set 的缓存。CLI 0.9.0 中gtars bbcache cache-bed gtars bbcache cache-bedset gtars bbcache seek gtars bbcache inspect-bedfiles gtars bbcache inspect-bedsets gtars bbcache rm标签源码中的默认值API 端点环境变量BEDBASE_API否则https://api.bedbase.org缓存目录环境变量BBCLIENT_CACHE否则$HOME/.bbcache/或/tmp/.bbcache/已缓存 BED 文件bedfiles/first/second/id.bed.gzBED setbedsets/first/second/id.txt缓存元数据包含经缓存依赖维护的 SQLite 状态。重要副作用构造BBClient就会创建根目录以及 BED/BED-set 子目录——即使只是 inspect/seek 也会产生目录副作用SKILL.md 的“网络和缓存门禁”一节同样提示这一点。cache-bed接受本地文件/目录、URL 或预期的 BEDbase 标识符cache-bedset接受本地目录/列表或预期的 BEDbase IDrm删除文件与缓存记录并且可以连带删除 BED set 的成员 BED。已知的 ID-only 下载缺陷源码研究发现v0.9.0 的BBClient.load_bed(id)会把裸 ID 委托给RegionSet::try_from而核心源码中的“裸 BEDbase-ID 回退”已被注释掉。因此在本版本中仅凭 ID 执行cache-bed/BED-set 下载可能失败尽管公开文档宣称支持。文档明确要求不要用猜测 URL 的方式绕过。应先在非敏感的已审批测试上验证安装后的实际帮助/行为或通过已审查的 BEDbase 元数据解析出明确的官方文件 URL。把下载当不可信数据对待bbcache源码没有暴露期望 SHA-256/revision 参数因此必须把每次下载都当作不可信输入分别审批并白名单api.bedbase.org以及任何确切的数据主机记录 BEDbase 记录 ID、API 响应 revision/时间、明确文件 URL、期望标识符/摘要和 SHA-256使用有配额限制的缓存文件夹索引之前校验 BED 的组装、边界和内容绝不把一次成功的缓存写入当作完整性证明。rm会删除本地内容使用前同样要确认删除范围缓存目录、SQLite 状态与输出路径都是需要外部管理的副作用。Rust 依赖固定直接使用最新 refget 组件时[dependencies] gtars-refget 0.9.1使用 0.9.0 包装层发布集合时[dependencies] gtars { version 0.9.0, default-features false, features [refget] }不要假设这两者暴露的 refget 补丁行为一致0.9.0 meta-crate 固定的组件集合包含 refget 0.9.0。技能主文档 SKILL.md 进一步建议完整功能面使用features [core, overlaprs, uniwig, tokenizers, refget]并强调不要用 Git 分支或未经审查的发布版替换这些精确 pin。一条完整的安全工作流综合以上各节推荐的安全流程是审查与固定按 SKILL.md 的原生代码信任门禁审查并固定gtars0.9.2/gtars-refget0.9.1/gtars-cli0.9.0在隔离环境中安装验证离线预检用refget_digest_plan.py校验策略清单与本地 FASTA 的摘要一致性不联网、不开存储本地建库RefgetStore.in_memory()加载并验证必要时write_store_to_dir持久化或直接gtars refget build --output approved-store --jobs 1构建磁盘存储只读复用后续读取用open_localinto_readonly()仅加载有界数据远程/BEDbase 仅在审批后先完成 7 项审批动作主机白名单、不可变 revision、期望摘要与 SHA-256、各项配额、泄露披露、返回校验再调用open_remote或gtars bbcache并把所有下载内容当不可信数据对待。这套流程把“refget 内容寻址的便利性”与“网络/缓存副作用的可审计性”绑定在一起摘要计算和本地存储可以完全离线、有界、可复现地完成而任何离开本地环境的读取都必须在显式审批和记录留痕之后进行。更多细节可继续阅读 refget.md 本身以及同一技能包下的 SKILL.md、cli.md 和 python-api.md。【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Gtars Refget 实战指南：序列摘要、序列存储与 BEDbase 缓存的安全使用
Gtars Refget 实战指南序列摘要、序列存储与 BEDbase 缓存的安全使用【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills本文围绕 Gtars 的 refget 组件gtars-refget0.9.1Python 侧gtars0.9.2CLI 侧gtars-cli0.9.0展开讲解 GA4GH refget 序列摘要sequence digest的术语与计算方式、RefgetStore存储类的内存/磁盘/远程三种模式、远程存储的网络审批门禁、只读并发转换、gtars refget build命令行建库以及独立的 BEDbasebbcache缓存命令。你读完可以立即在自己的流程中计算并校验序列摘要、构建和复用本地 refget 存储并清楚远程存储与 BEDbase 下载在何种前提与限制下才能安全使用。验证快照与版本基线本文所有事实均以仓库文档记录的2026-07-23验证快照为准Python 绑定gtars0.9.2PyPIRequires-Python 3.10包含 PyO3 原生扩展Rust 直接组件gtars-refget0.9.1CLI 包gtars-cli0.9.0安装后的二进制名为gtars。Gtars 上游有意对工作区各 crate、Python 绑定和 CLI 独立编号因此数字相同不代表构件相同例如gtars0.9.0这个 meta-crate 自身固定的是 refget 0.9.0而直接依赖gtars-refget则是 0.9.1两者在补丁行为上不应假设一致。具体可对照 技能主文档 中的版本说明。由于仓库与上游文档可能存在漂移实践前应以安装后的签名冒烟测试和带版本 tag 的源码为准。序列摘要术语与计算refget 是 GA4GH 定义的按内容寻址检索参考序列的规范核心思想是用序列内容本身计算出的摘要digest作为序列的稳定标识符。摘要变了意味着序列内容变了摘要稳定就可以跨数据库、跨工具、跨环境地标识同一条参考序列。当前 Python 函数集中在gtars.refget子模块from gtars.refget import ( compute_fai, digest_fasta, digest_sequence, load_fasta, md5_digest, sha512t24u_digest, ) digest sha512t24u_digest(ACGT) assert digest aKF498dAxcJAqme6QYQ7EZ07-fiw8Kw2 assert md5_digest(ACGT) f1f8f4bf413b16ad135722aa4591043e几点必须澄清的术语事实sha512t24u的形态Gtars 返回的是32 字符、不带SQ.前缀的字符串。GA4GH refget 规范推荐的序列标识符还要加上SQ.前缀SQ.aKF498dAxcJAqme6QYQ7EZ07-fiw8Kw2在仓库的离线校验脚本 refget_digest_plan.py 中该摘要的实现是hashlib.sha512(sequence.upper()).digest()[:24]再经 URL-safe Base64 编码并去掉填充——也就是说先对序列做全大写规范化再取 SHA-512 截断的前 24 字节最后 Base64URL 编码这与_SHA512T24U re.compile(r^[A-Za-z0-9_-]{32}$)的形状校验脚本第 30 行完全吻合。MD5 的定位md5_digest仅为遗留系统查询保留它不是抗碰撞的来源完整性哈希。需要独立保存一条 SHA-256 用于制品完整性校验——这与仓库技能一贯的“SHA-256 记录 refget 域摘要”双轨策略一致。摘要计算的输入必须是规范化后的序列GA4GH refget 在计算序列标识符之前会对序列内容做规范化。绝不能直接把原始 FASTA 字节丢进哈希函数就称为“序列摘要”。FASTA 头header、行折叠line wrapping、压缩方式和序列规范化属于不同层次头信息不参与序列内容\n折叠不该改变生物学序列.gz压缩更是与序列内容无关。所以digest_sequence会先对序列字节做大写处理。辅助函数的分工digest_sequence(data: bytes, nameNone, descriptionNone)——对序列字节做大写规范化返回包含元数据与序列数据的SequenceRecorddigest_fasta(path)——计算一个SequenceCollectionload_fasta(path)——把序列数据载入内存compute_fai(path)——针对未压缩FASTA 计算索引.fai。摘要正确性的可验证锚点仓库测试 tests/gtars/test_scripts.py 中test_refget_digest_validation_uses_known_acgt_digest验证了 “ACGT” 这一已知摘要测试构造了包含chr1 synthetic与acgt的小型 FASTA用sha512t24u(bACGT)测试内与脚本内相同的实现生成期望值再调用refget_digest_plan.py校验最终断言result[fasta][all_sequence_digests_match]为真且contract[store_opened]为假。这证明同样的规范化规则在技能脚本与 Gtars 运行时之间保持一致且校验过程完全离线、不打开任何存储。RefgetStore当前 Python 存储类运行时类名是RefgetStore而不是旧教程里的GlobalRefgetStorefrom gtars.refget import RefgetStore已验证的构造函数RefgetStore.in_memory() RefgetStore.on_disk(cache_path) RefgetStore.open_local(path) RefgetStore.open_remote(cache_path, remote_url) RefgetStore.store_exists(path)在设计上SKILL.md 明确建议优先使用in_memory()或open_local(path)open_remote会联网并产生缓存副作用必须走审批门禁见下文。迁移陷阱列表SKILL.md 的 “Migration traps” 一节也强调不要再使用过时的gtars.RefgetStore顶层导入形式。内存模式与本地持久化from gtars.refget import RefgetStore store RefgetStore.in_memory() metadata, was_new store.add_sequence_collection_from_fasta( reviewed-reference.fa, forceFalse, namespaces[refseq], ) store.write_store_to_dir(approved-store) reopened RefgetStore.open_local(approved-store)各模式/方法的副作用边界in_memory()——不写任何文件纯内存构造on_disk(path)——打开已有存储或新建一个磁盘后端存储open_local(path)——读取存储的元数据/索引惰性加载本地序列数据write_store_to_dir与enable_persistence——会创建/写入文件forceTrue——可以替换已有的 collection/sequence 条目。操作前应先store_exists(path)判断选择“新建”还是“打开”。仓库的安全约定还要求拒绝符号链接、意外文件、输出冲突和未获批的存储目录该约定与 scripts/_common.py 中local_path严格拒绝 URL、~展开、..穿越与符号链接的本地路径策略一致。批量导入results store.add_sequence_collections_from_fastas( [ref-a.fa.gz, ref-b.fa.gz], file_listNone, jobs1, forceFalse, namespaces[refseq], )fastas参数还可以接受glob 或目录jobs0表示自动并发。对于受控运行应显式枚举已审查的文件并设置一个正数、有界的作业数避免通配符意外扩展到未审查文件。元数据访问与序列访问的区分RefgetStore刻意区分两类方法元数据方法不加载完整序列内容collections_page store.list_collections(page0, page_size100) sequence_metadata store.list_sequences() one_metadata store.get_sequence_metadata(sequence_digest) collection_metadata store.get_collection_metadata(collection_digest)数据方法record store.get_sequence(sequence_digest) by_name store.get_sequence_by_name(collection_digest, chr1) piece store.get_substring(sequence_digest, 100, 200) pieces store.get_substrings(sequence_digest, [(100, 200), (500, 550)]) for chunk in store.stream_sequence( sequence_digest, start0, end1_000_000, chunk_size65_536, ): consume_bounded(chunk)关键语义子串区间是0 基、半开区间[start, end)务必校验0 start end lengthstream_sequence能约束峰值结果内存按chunk_size分块但如果下游把每个 chunk 都累积起来流式依然可能被打败——所以仍要给下游累积设定显式预算0.9.2 运行时还暴露load_sequence、load_collection、load_all_sequences、load_all_collections。这些方法会实体化更多数据load_all_*尤其危险没有显式的字节/内存预算就绝不调用。远程存储必须经过审批门禁# Network cache side effects: do not call before approval. remote RefgetStore.open_remote( approved_cache_path, approved_https_base_url, )open_remote只接受缓存路径和基础 URL 两个参数。它会拉取远程元数据、创建/复用本地缓存状态并且默认启用持久化。在 0.9.2 中get_substring可以发起远程字节区间读取range read而不必下载整条序列stream_sequence可以流式读取远程区间load_sequence是整条序列路径并可能将其持久化。重要限制open_remote之后调用disable_persistence()并不能撤销已经执行的元数据/缓存工作而且该构造器没有任何参数用于指定 revision、端点白名单、校验清单checksum manifest、字节配额或离线模式。换句话说远程模式的所有防护都必须由调用方在调用之前完成。在调用open_remote之前文档要求完成 7 项审批动作对确切的 HTTPS 主机/路径和缓存目录取得显式批准拒绝 URL 中携带的凭据以及未经审查的重定向固定一个不可变的服务器/存储 revision 或内容寻址标识符记录期望的 collection/sequence 摘要并在适用时记录独立的 SHA-256对元数据、单区间、总传输量、序列长度、缓存、重试、并发和时间设定上限披露请求坐标/摘要和网络元数据会离开当前环境在科学使用之前校验返回的长度与摘要。需要注意即使公共参考基因组本身不敏感定制/患者特异性组装体和请求区间也可能是敏感的。这与 SKILL.md 的“网络与缓存门禁”一节一致——所有网络能力调用前都要记录不可变 revision、期望 SHA-256、域摘要、组装号、大小配额与出处并把下载内容当作不可信数据处理。只读并发存储into_readonlyreadonly store.into_readonly()into_readonly()把可变存储转换为ReadonlyRefgetStore用于并发读取。它有两条硬约束它消耗/替换原可变存储对象它不能惰性加载那些转换前未准备的 collections。因此转换之前只应加载所需的、有界的数据不要反射性地使用load_all_*否则会把超出预算的数据带入只读并发场景。CLI 建库gtars refget build当前 refget 唯一的 CLI 子命令是本地存储构建没有digest、verify或远程查询子命令gtars refget build reference.fa reference-alt.fa.gz \ --output approved-store \ --jobs 1选项--file-list/-f PATH一个文件内含路径/glob/目录列表--output/-o DIR必填--jobs/-j N并发处理的 FASTA 文件数默认0自动--raw使用原始存储而不是默认的编码 2-bit 存储--force覆盖已有条目。注意--jobs 0是自动并发与add_sequence_collections_from_fastas的jobs0语义一致。旧技能中存在的gtars refget digest/verifyCLI 在当前版本不存在需要摘要计算时请使用 Python 摘要函数、直接 Rust API或在 preflight 之后做一次本地存储构建。CLI 层面也没有全局线程/内存/缓冲参数cli.md 确认 0.9.0 无--threads、--memory-limit等全局选项并发控制全部是命令级。离线元数据/摘要计划refget_digest_plan.py技能附带了一个离线辅助脚本接受一份保守的本地策略清单manifest。这是一份skill 策略清单并非上游 refget 线上 schema{ schema_version: 1.0, assembly: GRCh38.p14, coordinate_system: 0-based-half-open, collection_digest: 32-char sha512t24u-like value, sequences: [ { name: chr1, length: 248956422, sha512t24u: 32-char digest, md5: 32 lowercase hex } ] }运行方式可选用本地 FASTA 重算序列级摘要python3 -B scripts/refget_digest_plan.py \ --metadata refget-metadata.json \ --fasta reference.fa.gz \ --assembly GRCh38.p14从源码refget_digest_plan.py可以确认其行为边界它不会重算 collection 摘要collection_digest只做形状校验32 字符[A-Za-z0-9_-]并输出警告collection_digest_shape_only_not_recomputed第 162-168 行它校验清单结构与期望组装号/坐标系统schema_version必须为1.0、assembly必须与--assembly完全一致、coordinate_system必须为0-based-half-open否则报错逐条序列校验长度、sha512t24u 与 MD5提供--fasta时按名称比对报告缺失序列、意外序列、长度不一致、sha512t24u 不一致与 MD5 不一致五类错误码并输出 FASTA 文件的 SHA-256 与字节数不联网、不开存储、不写输出、不 import gtars报告的contract明确列出network_used: false、store_opened: false、cache_written: false、packages_imported: false第 271-279 行硬上限内置默认--max-bytes 2 GiB、--max-records 5,000,000且受 scripts/_common.py 中HARD_MAX_BYTES 8 GiB、HARD_MAX_RECORDS 10,000,000的硬边界约束输出的approved_execution_plan是一组固定建议文本如“优先RefgetStore.open_local”、“新存储用in_memory验证后再显式持久化”、“open_remote前记录白名单/固定 revision/期望摘要/缓存路径/字节配额/审批”等。最终 collection 的权威验证仍应使用Gtars 固定版本的 collection 实现即实际调用gtars的 seqcol 逻辑。测试 tests/gtars/test_scripts.py 还验证了该脚本即使校验失败也只输出 JSON、不泄漏本地绝对路径默认--path-mode redacted并验证了 URL 形式路径会被拒绝。BEDbase 缓存bbcache与 refget 的区分BEDbase 缓存独立于 refget它处理的是 BED 区间文件与 BED set 的缓存。CLI 0.9.0 中gtars bbcache cache-bed gtars bbcache cache-bedset gtars bbcache seek gtars bbcache inspect-bedfiles gtars bbcache inspect-bedsets gtars bbcache rm标签源码中的默认值API 端点环境变量BEDBASE_API否则https://api.bedbase.org缓存目录环境变量BBCLIENT_CACHE否则$HOME/.bbcache/或/tmp/.bbcache/已缓存 BED 文件bedfiles/first/second/id.bed.gzBED setbedsets/first/second/id.txt缓存元数据包含经缓存依赖维护的 SQLite 状态。重要副作用构造BBClient就会创建根目录以及 BED/BED-set 子目录——即使只是 inspect/seek 也会产生目录副作用SKILL.md 的“网络和缓存门禁”一节同样提示这一点。cache-bed接受本地文件/目录、URL 或预期的 BEDbase 标识符cache-bedset接受本地目录/列表或预期的 BEDbase IDrm删除文件与缓存记录并且可以连带删除 BED set 的成员 BED。已知的 ID-only 下载缺陷源码研究发现v0.9.0 的BBClient.load_bed(id)会把裸 ID 委托给RegionSet::try_from而核心源码中的“裸 BEDbase-ID 回退”已被注释掉。因此在本版本中仅凭 ID 执行cache-bed/BED-set 下载可能失败尽管公开文档宣称支持。文档明确要求不要用猜测 URL 的方式绕过。应先在非敏感的已审批测试上验证安装后的实际帮助/行为或通过已审查的 BEDbase 元数据解析出明确的官方文件 URL。把下载当不可信数据对待bbcache源码没有暴露期望 SHA-256/revision 参数因此必须把每次下载都当作不可信输入分别审批并白名单api.bedbase.org以及任何确切的数据主机记录 BEDbase 记录 ID、API 响应 revision/时间、明确文件 URL、期望标识符/摘要和 SHA-256使用有配额限制的缓存文件夹索引之前校验 BED 的组装、边界和内容绝不把一次成功的缓存写入当作完整性证明。rm会删除本地内容使用前同样要确认删除范围缓存目录、SQLite 状态与输出路径都是需要外部管理的副作用。Rust 依赖固定直接使用最新 refget 组件时[dependencies] gtars-refget 0.9.1使用 0.9.0 包装层发布集合时[dependencies] gtars { version 0.9.0, default-features false, features [refget] }不要假设这两者暴露的 refget 补丁行为一致0.9.0 meta-crate 固定的组件集合包含 refget 0.9.0。技能主文档 SKILL.md 进一步建议完整功能面使用features [core, overlaprs, uniwig, tokenizers, refget]并强调不要用 Git 分支或未经审查的发布版替换这些精确 pin。一条完整的安全工作流综合以上各节推荐的安全流程是审查与固定按 SKILL.md 的原生代码信任门禁审查并固定gtars0.9.2/gtars-refget0.9.1/gtars-cli0.9.0在隔离环境中安装验证离线预检用refget_digest_plan.py校验策略清单与本地 FASTA 的摘要一致性不联网、不开存储本地建库RefgetStore.in_memory()加载并验证必要时write_store_to_dir持久化或直接gtars refget build --output approved-store --jobs 1构建磁盘存储只读复用后续读取用open_localinto_readonly()仅加载有界数据远程/BEDbase 仅在审批后先完成 7 项审批动作主机白名单、不可变 revision、期望摘要与 SHA-256、各项配额、泄露披露、返回校验再调用open_remote或gtars bbcache并把所有下载内容当不可信数据对待。这套流程把“refget 内容寻址的便利性”与“网络/缓存副作用的可审计性”绑定在一起摘要计算和本地存储可以完全离线、有界、可复现地完成而任何离开本地环境的读取都必须在显式审批和记录留痕之后进行。更多细节可继续阅读 refget.md 本身以及同一技能包下的 SKILL.md、cli.md 和 python-api.md。【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考