weclio-cli

科学评估命令行套件；当前提供基于 PubChem、ECHA 与 CPDB 的科学搜索。使用 TypeScript/Node.js 实现。

安装

要求 Node.js 20+：

npm install -g weclio-cli
weclio --help

也可在项目中作为依赖安装，通过 weclio 可执行文件以子进程调用。

命令

weclio search substance resolve
weclio search cpdb <CAS-or-exact-name>
weclio search toc list
weclio search docs list
weclio search docs get

推荐顺序：resolve → toc list → docs list → docs get。

1. 解析 PubChem 物质

仅支持 --source pubchem。建议使用 CID、CAS 或足够唯一的名称。

weclio search substance resolve --source pubchem --query "50-78-2"
weclio search substance resolve --source pubchem --query aspirin --property "MolecularWeight,SMILES"

--property 接受一个或多个逗号分隔的 PubChem PUG REST property 名称，不在 CLI 中枚举。

输出示例：

{"cid":"2244","properties":{"Title":"Aspirin"},"cas_number":"50-78-2","citation":{"source":"PubChem","url":"..."}}

CPDB 致癌效力数据

CPDB 接受有效 CAS 号或归一化后的精确 chemical name；不做模糊匹配。优先使用 CAS。每个 formulation 返回一个标准 document result，内部保留全部 species results，并通过 blocks[].citation 标注数据来源。

weclio search cpdb 50-00-0
weclio search cpdb "Alkyldimethylamine oxides, commercial grade"

2. 列出来源 TOC

PubChem 的 --source-id 是 CID；ECHA 的 --source-id 是 EC number。无 --toc：顶层。传入返回路径：直接子节点。

weclio search toc list --source pubchem --source-id 2244
weclio search toc list --source pubchem --source-id 2244 \
  --toc "Chemical and Physical Properties"

{
  "toc": [
    ["Chemical and Physical Properties", "Computed Properties"],
    ["Chemical and Physical Properties", "Experimental Properties"]
  ]
}

3. 列出实际可读文档

--toc 每次传递一个层级，必须按路径顺序重复传递。该命令可能透明访问上游并物化文档。

weclio search docs list --source pubchem --source-id 2244 \
  --toc "Chemical and Physical Properties" \
  --toc "Experimental Properties"

{
  "docs": [
    {
      "toc": ["Chemical and Physical Properties", "Experimental Properties", "Melting Point"],
      "doc": "Melting Point"
    }
  ]
}

4. 读取文档

将 docs list 返回的 toc 与 doc 原样复制。定位基于完整 locator，不是仅按文件名匹配。

weclio search docs get --source pubchem --source-id 2244 \
  --toc "Chemical and Physical Properties" \
  --toc "Experimental Properties" \
  --toc "Melting Point" \
  --doc "Melting Point"

{
  "identifier": {
    "RecordType": "CID",
    "RecordNumber": 2244,
    "RecordTitle": "Aspirin"
  },
  "blocks": [
    {"content": "## Solubility"},
    {
      "content": "10 mg/mL",
      "citation": {
        "source": "DrugBank",
        "source_id": "36",
        "url": "https://go.drugbank.com/drugs/DB00945"
      }
    }
  ]
}

顶层字段标识物质：PubChem 为 CID / CID / 名称，ECHA 为 EC number / EC number / 名称；CPDB 有 CAS 时为 CAS Registry Number / CAS / formulation 名称，无 CAS 时为 Chemical name / 名称 / 名称。每个 block 是一个 Markdown 片段；有来源的 block 附带 citation。PubChem source_id 是 PUG-View reference number；ECHA source_id 是 dossier document ID；CPDB source_id 优先使用 CAS，无 CAS 时使用 chemical name。

进程与 JSON 契约

| 情况 | stdout | stderr | 退出码 | | --- | --- | --- | --- | | 成功 | 一个 JSON object | 空 | 0 | | 参数/用法错误 | 空 | 一个 JSON error object | 2 | | 运行错误 | 空 | 一个 JSON error object | 1 | | --help | 人类/agent 可读 help | 空 | 0 |

错误格式：

{
  "error": {
    "code": "TOC_NOT_FOUND",
    "message": "TOC path was not found.",
    "suggested_action": "Copy --toc exactly from weclio search toc list."
  }
}

suggested_action 给出下一步；无额外结构。

稳定错误码：INVALID_ARGUMENT、SOURCE_NOT_SUPPORTED、SUBSTANCE_NOT_FOUND、TOC_NOT_FOUND、DOC_NOT_FOUND、UPSTREAM_ERROR、INTERNAL_ERROR。

缓存

可通过 WECLIO_CACHE_DIR 覆盖缓存根目录：

WECLIO_CACHE_DIR=/tmp/weclio-cache weclio search toc list --source pubchem --source-id 2244

默认目录：

• Linux：$XDG_CACHE_HOME/weclio，否则 ~/.cache/weclio
• macOS：$XDG_CACHE_HOME/weclio，否则 ~/.cache/weclio
• Windows：%LOCALAPPDATA%\weclio\cache

缓存内部分为：

<cache-root>/
├── sources/      # HTTP/source cache
└── documents/    # 文档 JSON 与 manifest

每篇逻辑文档保存为一个以 TOC 节点命名的 JSON 文件，内容为 { blocks }。manifest 显式保存完整 locator 到文件的映射；写入采用临时文件与原子 rename。

开发与验证

npm ci
npm run lint
npm run typecheck
npm run test:unit
npm run test:contract
npm test
npm run build
npm pack

默认测试只使用确定性离线 fixtures。真实上游网络测试需显式启用：

WECLIO_LIVE_TESTS=1 npm run test:live

发布

发布由 GitHub Actions 与 npm Trusted Publisher 自动完成。更新 package.json 版本并提交后，推送匹配的 tag：

git tag v0.1.0
git push origin v0.1.0

Tag 版本必须与 package.json 的 version 一致。