每次发版都会把 @viztor/dsh-tinyfish 镜像到 GitHub Packages——npmjs.org 连不上时的第二来源，也是仓库侧边栏的数据来源。只有带作用域的名字会镜像：GitHub 按所有者作用域把软件包关联到仓库。与 npmjs 不同，GitHub Packages 连公开包也要认证：未认证的请求会 404，且不告诉你这个包是否存在。用带有 read:packages 权限的 token：

# project-local .npmrc is better than global for a token
@viztor:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=ghp_xxx

之后 npm install @viztor/dsh-tinyfish 就会从镜像解析。除非 npmjs 宕机，一律优先用它：不用 token，也不用额外配置。

全都住在同一行 dsh-tinyfish 里。该行带校验，越界值会被带着报错信息拒绝，而不是悄悄钳制。

关掉一个报的是“不可用”而非“缺失”——harness 分得清这两者，只有后者意味着“安装坏了”。但“不可用”也不会悄悄 fallback：如果 searchProvider/fetchProvider 还写着 TinyFish，调用会失败。想用另一个提供方，就把对应工具指向它。

- id: dsh-tinyfish
  config:
    search: true
    fetch: false # TinyFish stays registered but unavailable for fetch; point fetchProvider elsewhere to use another fetch

Manifest 元数据，而非配置

manifest 里还带着 dsh.compatibility：显式声明的 Node 与 DSH 范围，外加每个发版的实测结论——compatible、incompatible 或 unknown——供目录核验各 DSH 版本。

**DSH 本体从不读它。**harness 里没有任何代码读 dsh.compatibility，dshReleases 映射也全无引用，所以这些字段改变不了插件的加载、注册与行为。DSH 自己的兼容机制是另一回事：loader 检查的是 peerDependencies，豁免记录在 profile 的 compatibility.json 里。这些字段的存在，是让列表页能如实写清“哪些已被验证”，这里的结论也的确是实测而非期望：0.2.0-rc.2 是本仓库每次构建与测试所跑的版本，0.2.0-rc.1 虽在 peer 范围内但从未实际跑过，0.1.7-rc.2 则低于下限。0.2.0-rc.1 以同样方式验证过（把五个 harness devDependencies 全部钉到该版本并跑门禁）；0.2.1-alpha.1 记为 incompatible，因为 peer 范围并不接受它 —— semver 只在范围本身带有同一 major.minor.patch 的预发布版本时才放行预发布版，因此 loader 在该 alpha 主机上会拒绝加载本插件。

过滤器与抓取选项写在补丁文件里

filters 与 fetchOptions 是嵌套对象，而设置表单一个字段只对应一个扁平键——所以搜索与抓取调优留在运维层面：

- id: dsh-tinyfish
  config:
    channel: monid
    filters:
      domainType: research_paper
      language: zh
      includeDomains: arxiv.org,openreview.net
      pubYearMin: 2023
    fetchOptions:
      ttl: 0 # force a live fetch instead of accepting a cached page
      excludeSelectors: nav, .cookie-banner

两个分组永远有解析结果：没设就是空分组，不给请求加任何东西；不可用的成员退化为未设置，绝不发往上游。三条上游注意事项按文档行为原样透出，不做强制：

• recencyMinutes 与 afterDate 在 TinyFish API 里互斥；一行里两个都写就两个都发。
• excludeSelectors 对直接下载的 PDF/CSV 无效，带上它会答 selector_unsupported。
• 上游会按 domainType 交叉核验每个日期边界：recencyMinutes 与 afterDate 不接受 research_paper，pubYearMin 只属于它，配错任一一对都会让整个搜索被拒绝。

凭证从哪里来

每次调用现解析——轮换密钥下次搜索即生效，不用重启。先命中先生效：

1. 行里的 apiKey 字面量（写在配置里的秘密；优先用 2–3）
2. 凭证服务——apiKeyEnv（直连）或 monidKeyEnv（Monid），从设置界面保存
3. 启动环境（DSH 启动前 export 的）
4. 实时环境——先读配置的引用名（apiKeyEnv / monidKeyEnv，可以是你自己的变量名），再读 MONID_API_KEY / MONID_MCP_TOKEN / TINYFISH_API_KEY（任一 Monid 变量都覆盖 monid 通道）
5. 各通道的 CLI 存储（monid keys add / tinyfish auth login）

凭证服务挂了就落到下一个来源，而不是让搜索失败。

端点从哪里来

行配置优先，其次环境变量，最后内置默认——测试环境不用改补丁就能换向：

• **404 是结果，不是错误。**单个 URL 抓取失败会带着状态码回来，因为那是模型需要的资源状态。
• **publishedAt 诚实。**TinyFish 报的是人类日期（"Apr 30, 2026"、"1 year ago"）。能解析的转成 ISO-8601，解析不了的直接丢掉，绝不编造。只有不含时刻、也不带时区的日期按 UTC 读，所以同一页面在全球报的是同一天；带时刻的值按原样解析。
• **空搜索会重试。**上游大约三跑空一——对合法查询也可能什么都不回；在认定之前，会一直重试到用尽尝试预算（attempts，总尝试次数）。
• **被拦的 run 是终态。**若 Monid 工作区控制拦停一次运行，错误里会写原因并附充值链接。永不重试。
• **关闭意味着“不可用”，不是“没了”。**关掉的种类保持注册、只是谢绝。若 profile 还把对应工具钉在 Tinyfish 上，调用会大声失败，而不会悄悄改道——想用别的提供方就把工具指向它。什么都没钉时，退出的 Tinyfish 只管让路：自动选择用剩下的人选，关掉其中一种正是把“多提供方歧义”收敛到唯一候选的办法。
• **“不可用”三种成因、一种面孔。**seam 只看到一个布尔值，所以“开关关了”“没凭证”“base URL 写错”在下游读起来一模一样。卡片分得清——去看卡片上的开关和密钥徽标，端点覆盖则在行里或环境里看。
• **purpose 是每次请求的一句话。**seam 的请求没有目标槽位——搜索只有 {query}，抓取只有 {url}——不动 harness 就不可能有按调用的目标。配置里的那句话会逐字跟随每次搜索与抓取：常驻偏置，而非按任务指令。

TinyFish 的 agent 与 browser 界面没有暴露：按量计费、走钱包，既不是搜索也不是抓取。页面真需要开浏览器时，直接用 tinyfish CLI。

工具链是 Vite+：vp pack 用 tsdown 构建，vp test 跑 Vitest，vp lint / vp fmt 即 Oxlint 与 Oxfmt，且是类型感知的。Lint 与格式配置住在 vite.config.ts 里——Vite+ 会忽略独立配置文件。

pnpm install
pnpm test               # hermetic — no network, no credential
pnpm run check          # format + lint + types
pnpm run release:gate   # build, then the full gate incl. the package checks
pnpm run test:live      # the real APIs, still $0, needs credentials

需要 DSH ^0.2.0-rc.1（0.2.0-rc.1 及之后、0.3.0 之前）与 Node 24+。完整流程与不变量：AGENTS.md。参与贡献：CONTRIBUTING.md。