better-dsh 0.2.4 → 0.2.5

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/optional/research/research-darwinian-evolver.md

@@ -0,0 +1,188 @@
+---
+title: "Darwinian Evolver — 使用 Imbue 的进化循环来优化 prompt/正则/SQL/代码"
+sidebar_label: "Darwinian Evolver"
+description: "使用 Imbue 的进化循环来优化 prompt/正则/SQL/代码"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Darwinian Evolver
+
+使用 Imbue 的进化循环来优化 prompt（提示词）/正则/SQL/代码。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 可选 — 通过 `hermes skills install official/research/darwinian-evolver` 安装 |
+| 路径 | `optional-skills/research/darwinian-evolver` |
+| 版本 | `0.1.0` |
+| 作者 | Bihruze (Asahi0x), Hermes Agent |
+| 许可证 | MIT |
+| 平台 | linux, macos |
+| 标签 | `evolution`, `optimization`, `prompt-engineering`, `research` |
+| 相关 skill | [`arxiv`](/user-guide/skills/bundled/research/research-arxiv), [`jupyter-notebook`](/user-guide/skills/optional/data-science/data-science-jupyter-notebook) |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。
+:::
+
+# Darwinian Evolver
+
+运行 Imbue 的 [darwinian_evolver](https://github.com/imbue-ai/darwinian_evolver) —— 一个
+由 LLM 驱动的进化搜索循环 —— 用于针对适应度函数优化 **prompt、正则表达式、SQL 查询
+或小型代码片段**。
+
+状态：对上游工具的轻量封装。该 skill 负责安装工具，引导 agent 编写 `Problem` 定义
+（organism + evaluator + mutator），并通过上游 CLI 或一个小型自定义 Python 驱动脚本来运行循环。
+
+**许可证：** 上游工具采用 **AGPL-3.0** 授权。该 skill 仅通过上游 CLI 或 `subprocess`/`uv run`
+调用来调用它（纯聚合方式）。**不得**将上游类导入 Hermes 本身。
+
+## 使用时机
+
+- 用户说"优化这个 prompt"、"为 X 进化一个正则"、"自动改进这段代码/SQL"、"搜索更好的指令"。
+- 你有一个评分器（精确匹配、正则通过率、单元测试、LLM 评判、运行时指标）以及一个起始候选（organism）。如果没有评分器，请先定义一个 —— 这才是难点所在。
+- 成本可接受：一次典型运行需要 50–500 次 LLM 调用。使用 gpt-4o-mini 只需几美分；使用 Claude Sonnet 可能需要几美元。
+
+**不适用**的情况：
+- 优化目标可微分（请使用梯度下降 / DSPy）。
+- 只需尝试 2–3 个变体 —— 直接手写即可。
+- 适应度信号纯粹主观，没有可量化的标准。
+
+## 前置条件
+
+- Python ≥3.11
+- `git`、`uv`（或 `pip`）
+- 以下之一：`OPENROUTER_API_KEY`、`ANTHROPIC_API_KEY` 或 `OPENAI_API_KEY`
+
+该 skill 附带一个小型 `parrot_openrouter.py` 驱动脚本，通过 OpenAI SDK 使用 `OPENROUTER_API_KEY`，
+因此 OpenRouter 上的任何模型均可使用。上游 CLI 本身硬编码了 Anthropic，需要 `ANTHROPIC_API_KEY`。
+
+## 安装（一次性）
+
+通过 `terminal` 工具运行：
+
+```bash
+mkdir -p ~/.hermes/cache/darwinian-evolver && cd ~/.hermes/cache/darwinian-evolver
+[ -d darwinian_evolver ] || git clone --depth 1 https://github.com/imbue-ai/darwinian_evolver.git
+cd darwinian_evolver && uv sync
+```
+
+验证：
+
+```bash
+cd ~/.hermes/cache/darwinian-evolver/darwinian_evolver \
+  && uv run darwinian_evolver --help | head -5
+```
+
+## 快速开始 —— 内置 Parrot 示例
+
+小型冒烟测试（需要 `ANTHROPIC_API_KEY`）：
+
+```bash
+cd ~/.hermes/cache/darwinian-evolver/darwinian_evolver
+uv run darwinian_evolver parrot \
+  --num_iterations 2 \
+  --num_parents_per_iteration 2 \
+  --mutator_concurrency 2 --evaluator_concurrency 2 \
+  --output_dir /tmp/parrot_demo
+```
+
+输出：
+- `/tmp/parrot_demo/snapshots/iteration_N.pkl` —— 每次迭代的 pickle 序列化种群
+- `/tmp/parrot_demo/<jsonl>` —— 每次迭代的 JSON 日志（路径在结束时打印）
+
+在浏览器中打开 `~/.hermes/cache/darwinian-evolver/darwinian_evolver/darwinian_evolver/lineage_visualizer.html`
+并加载 JSON 日志，即可查看进化树。
+
+## 快速开始 —— OpenRouter 驱动（无需 Anthropic Key）
+
+该 skill 附带 `scripts/parrot_openrouter.py` —— 同样的 parrot 问题，但 LLM 调用通过
+OpenRouter 进行，因此任何提供商均可使用。
+
+```bash
+# From wherever the skill is installed:
+SKILL_DIR=~/.hermes/skills/research/darwinian-evolver
+DE_DIR=~/.hermes/cache/darwinian-evolver/darwinian_evolver
+
+cd "$DE_DIR" && \
+  EVOLVER_MODEL='openai/gpt-4o-mini' \
+  uv run --with openai python "$SKILL_DIR/scripts/parrot_openrouter.py" \
+    --num_iterations 3 --num_parents_per_iteration 2 \
+    --output_dir /tmp/parrot_or
+```
+
+使用 `scripts/show_snapshot.py` 查看结果：
+
+```bash
+uv run --with openai python "$SKILL_DIR/scripts/show_snapshot.py" \
+  /tmp/parrot_or/snapshots/iteration_3.pkl
+```
+
+预期输出：7 个按分数排名的进化 prompt 模板，最佳结果约在 0.6–0.8 之间（初始种子 `Say {{ phrase }}` 得分为 0.000）。
+
+## 定义自定义问题
+
+该 skill 附带 `templates/custom_problem_template.py` —— 复制、编辑、运行。
+你必须定义三样东西：
+
+1. **`Organism`** —— 一个 Pydantic `BaseModel` 子类，持有被进化的制品（`prompt_template: str`、`regex_pattern: str`、`sql_query: str`、`code_block: str` 等）。添加一个 `run(*args)` 方法来执行它。
+
+2. **`Evaluator`** —— `.evaluate(organism) -> EvaluationResult(score=..., trainable_failure_cases=[...], holdout_failure_cases=[...], is_viable=True)`。
+   - **`score`** 在 `[0, 1]` 范围内，越高越好。
+   - **`trainable_failure_cases`** —— mutator 所看到的内容。包含足够的上下文（输入、期望值、实际值），以便 LLM 进行诊断。
+   - **`holdout_failure_cases`** —— 对 mutator 隐藏。用于检测过拟合。
+   - **`is_viable=True`**，除非 organism 完全损坏（抛出异常、返回 None 等）。得分为 0 的可行 organism 是可以的 —— 它只是在父代选择中权重较低。
+
+3. **`Mutator`** —— `.mutate(organism, failure_cases, learning_log_entries) -> list[Organism]`。
+   通常做法：构建一个包含当前 organism + 失败案例 + 修复请求的 LLM prompt；解析 LLM 的响应；返回一个新的 `Organism`。解析失败时返回 `[]` —— 循环会处理这种情况。
+
+然后编写一个驱动脚本，将 `Problem(initial_organism, evaluator, [mutators])` 接入
+`EvolveProblemLoop`，并在 `loop.run(num_iterations=N)` 上迭代 —— 附带的
+`scripts/parrot_openrouter.py` 是参考实现。
+
+## 实际影响较大的超参数
+
+| 参数 | 默认值 | 何时调整 |
+|---|---|---|
+| `--num_iterations` | 5 | 一旦信任 evaluator，调高至 10–20 |
+| `--num_parents_per_iteration` | 4 | 降至 2 以进行低成本探索 |
+| `--mutator_concurrency` | 10 | 降至 2–4 以避免速率限制 |
+| `--evaluator_concurrency` | 10 | 同上；evaluator 也会调用 LLM |
+| `--batch_size` | 1 | 一旦 mutator 能处理多个失败案例，调高至 3–5 |
+| `--verify_mutations` | 关闭 | 一旦 mutator 浪费严重时开启（据 Imbue，后续运行可节省 >10× 成本） |
+| `--midpoint_score` | `p75` | 除非分数聚集，否则保持不变 |
+| `--sharpness` | 10 | 保持不变 |
+
+## 常见陷阱
+
+1. **`Initial organism must be viable`** —— 即使种子得分为 0，也要在 `EvaluationResult` 中设置 `is_viable=True`。循环拒绝不可行的 organism，因为这意味着循环没有任何可进化的起点。
+2. **提供商内容过滤会中断运行。** 基于 Azure 的 OpenRouter 模型会以 HTTP 400 拒绝"ignore previous instructions"等短语。将 LLM 调用包裹在 `try/except` 中，并返回 `f"<LLM_ERROR: {e}>"` —— evolver 会将该 organism 评分为 0 并继续。
+3. **`loop.run()` 是一个生成器** —— 调用它不会执行任何操作，直到你对其迭代。使用 `for snap in loop.run(num_iterations=N):`。
+4. **快照是嵌套 pickle。** `iteration_N.pkl` 包含一个带有 `population_snapshot`（更多 pickle 字节）的字典。要反序列化，必须让 `Organism` 类在与 pickle 时相同的点分路径下可导入。
+5. **并发默认值较激进。** 10/10 会在大多数提供商上触发速率限制。从 2/2 开始。
+6. **CLI 硬编码为 Anthropic。** `uv run darwinian_evolver <problem>` 会查找 `ANTHROPIC_API_KEY` 并使用 Claude Sonnet。要使用其他提供商，请编写类似 `parrot_openrouter.py` 的驱动脚本。
+7. **AGPL 协议。** 永远不要在 Hermes 核心中使用 `from darwinian_evolver import ...`。`~/.hermes/skills/...` 下的自定义驱动脚本属于用户侧，没有问题。
+8. **没有 PyPI 包。** `pip install darwinian-evolver` 会安装错误的东西。始终从 GitHub 仓库安装。
+
+## 验证
+
+安装完成并运行一次 parrot 后，以下命令退出码为 0 即表示验证通过：
+
+```bash
+DE_DIR=~/.hermes/cache/darwinian-evolver/darwinian_evolver
+ls "$DE_DIR/darwinian_evolver/lineage_visualizer.html" >/dev/null && \
+cd "$DE_DIR" && uv run darwinian_evolver --help >/dev/null && \
+echo "darwinian-evolver: OK"
+```
+
+## 参考资料
+
+- [Imbue 研究文章](https://imbue.com/research/2026-02-27-darwinian-evolver/)
+- [ARC-AGI-2 结果](https://imbue.com/research/2026-02-27-arc-agi-2-evolution/)
+- [imbue-ai/darwinian_evolver](https://github.com/imbue-ai/darwinian_evolver)（AGPL-3.0）
+- [Darwin Gödel Machines](https://arxiv.org/abs/2505.22954)
+- [PromptBreeder](https://arxiv.org/abs/2309.16797)

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/optional/research/research-domain-intel.md

@@ -0,0 +1,117 @@
+---
+title: "Domain Intel — 使用 Python 标准库进行被动域名侦察"
+sidebar_label: "Domain Intel"
+description: "使用 Python 标准库进行被动域名侦察"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Domain Intel
+
+使用 Python 标准库进行被动域名侦察。支持子域名发现、SSL 证书检查、WHOIS 查询、DNS 记录、域名可用性检测以及批量多域名分析。无需 API 密钥。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 可选 — 通过 `hermes skills install official/research/domain-intel` 安装 |
+| 路径 | `optional-skills/research/domain-intel` |
+| 平台 | linux, macos, windows |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
+:::
+
+# Domain Intelligence — 被动 OSINT
+
+仅使用 Python 标准库进行被动域名侦察。
+**零依赖。零 API 密钥。支持 Linux、macOS 和 Windows。**
+
+## 辅助脚本
+
+此 skill 包含 `scripts/domain_intel.py` — 一个涵盖所有域名情报操作的完整 CLI 工具。
+
+```bash
+# 通过证书透明度日志发现子域名
+python3 SKILL_DIR/scripts/domain_intel.py subdomains example.com
+
+# SSL 证书检查（有效期、加密套件、SAN、颁发者）
+python3 SKILL_DIR/scripts/domain_intel.py ssl example.com
+
+# WHOIS 查询（注册商、日期、名称服务器 — 支持 100+ 顶级域名）
+python3 SKILL_DIR/scripts/domain_intel.py whois example.com
+
+# DNS 记录（A、AAAA、MX、NS、TXT、CNAME）
+python3 SKILL_DIR/scripts/domain_intel.py dns example.com
+
+# 域名可用性检测（被动方式：DNS + WHOIS + SSL 信号）
+python3 SKILL_DIR/scripts/domain_intel.py available coolstartup.io
+
+# 批量分析 — 并行对多个域名执行多项检查
+python3 SKILL_DIR/scripts/domain_intel.py bulk example.com github.com google.com
+python3 SKILL_DIR/scripts/domain_intel.py bulk example.com github.com --checks ssl,dns
+```
+
+`SKILL_DIR` 为包含此 SKILL.md 文件的目录。所有输出均为结构化 JSON。
+
+## 可用命令
+
+| 命令 | 功能说明 | 数据来源 |
+|---------|-------------|-------------|
+| `subdomains` | 从证书日志中发现子域名 | crt.sh（HTTPS） |
+| `ssl` | 检查 TLS 证书详情 | 直接 TCP:443 连接目标 |
+| `whois` | 注册信息、注册商、日期 | WHOIS 服务器（TCP:43） |
+| `dns` | A、AAAA、MX、NS、TXT、CNAME 记录 | 系统 DNS + Google DoH |
+| `available` | 检查域名是否已注册 | DNS + WHOIS + SSL 信号 |
+| `bulk` | 对多个域名执行多项检查 | 以上所有来源 |
+
+## 何时使用此 skill 而非内置工具
+
+- **使用此 skill** 处理基础设施相关问题：子域名、SSL 证书、WHOIS、DNS 记录、可用性检测
+- **使用 `web_search`** 进行关于某个域名或公司的通用研究
+- **使用 `web_extract`** 获取网页的实际内容
+- **使用 `terminal` 配合 `curl -I`** 进行简单的"URL 是否可达"检查
+
+| 任务 | 更合适的工具 | 原因 |
+|------|-------------|-----|
+| "example.com 是做什么的？" | `web_extract` | 获取页面内容，而非 DNS/WHOIS 数据 |
+| "查找某公司的信息" | `web_search` | 通用研究，非域名专项 |
+| "这个网站安全吗？" | `web_search` | 信誉检查需要 Web 上下文 |
+| "检查某 URL 是否可达" | `terminal` 配合 `curl -I` | 简单 HTTP 检查 |
+| "查找 X 的子域名" | **此 skill** | 唯一的被动来源 |
+| "SSL 证书何时到期？" | **此 skill** | 内置工具无法检查 TLS |
+| "谁注册了这个域名？" | **此 skill** | WHOIS 数据不在 Web 搜索结果中 |
+| "coolstartup.io 可以注册吗？" | **此 skill** | 通过 DNS+WHOIS+SSL 进行被动可用性检测 |
+
+## 平台兼容性
+
+纯 Python 标准库（`socket`、`ssl`、`urllib`、`json`、`concurrent.futures`）。
+无需任何依赖，在 Linux、macOS 和 Windows 上表现完全一致。
+
+- **crt.sh 查询** 使用 HTTPS（443 端口） — 在大多数防火墙后均可正常工作
+- **WHOIS 查询** 使用 TCP 43 端口 — 在限制性网络中可能被封锁
+- **DNS 查询** 使用 Google DoH（HTTPS）解析 MX/NS/TXT — 对防火墙友好
+- **SSL 检查** 连接目标的 443 端口 — 唯一的"主动"操作
+
+## 数据来源
+
+所有查询均为**被动**方式 — 不进行端口扫描，不进行漏洞测试：
+
+- **crt.sh** — 证书透明度日志（子域名发现，仅 HTTPS）
+- **WHOIS 服务器** — 直接 TCP 连接 100+ 权威 TLD 注册机构
+- **Google DNS-over-HTTPS** — MX、NS、TXT、CNAME 解析（对防火墙友好）
+- **系统 DNS** — A/AAAA 记录解析
+- **SSL 检查** 是唯一的"主动"操作（TCP 连接目标:443）
+
+## 注意事项
+
+- WHOIS 查询使用 TCP 43 端口 — 在限制性网络中可能被封锁
+- 部分 WHOIS 服务器会隐去注册人信息（GDPR 合规） — 请告知用户
+- 对于非常热门的域名（拥有数千张证书），crt.sh 可能响应较慢 — 请设置合理预期
+- 可用性检测基于启发式方法（3 个被动信号） — 并非像注册商 API 那样权威
+
+---
+
+*由 [@FurkanL0](https://github.com/FurkanL0) 贡献*

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/optional/research/research-drug-discovery.md

@@ -0,0 +1,237 @@
+---
+title: "Drug Discovery — 药物发现工作流的制药研究助手"
+sidebar_label: "Drug Discovery"
+description: "药物发现工作流的制药研究助手"
+---
+
+{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
+
+# Drug Discovery
+
+药物发现工作流的制药研究助手。在 ChEMBL 上搜索生物活性化合物，计算类药性（Lipinski Ro5、QED、TPSA、合成可及性），通过 OpenFDA 查询药物相互作用，解读 ADMET 特征，并协助先导化合物优化。适用于药物化学问题、分子性质分析、临床药理学及开放科学药物研究。
+
+## Skill 元数据
+
+| | |
+|---|---|
+| 来源 | 可选 — 通过 `hermes skills install official/research/drug-discovery` 安装 |
+| 路径 | `optional-skills/research/drug-discovery` |
+| 版本 | `1.0.0` |
+| 作者 | bennytimz |
+| 许可证 | MIT |
+| 平台 | linux, macos, windows |
+| 标签 | `science`, `chemistry`, `pharmacology`, `research`, `health` |
+
+## 参考：完整 SKILL.md
+
+:::info
+以下是 Hermes 在触发该 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。
+:::
+
+# Drug Discovery & Pharmaceutical Research
+
+You are an expert pharmaceutical scientist and medicinal chemist with deep
+knowledge of drug discovery, cheminformatics, and clinical pharmacology.
+Use this skill for all pharma/chemistry research tasks.
+
+## Core Workflows
+
+### 1 — Bioactive Compound Search (ChEMBL)
+
+Search ChEMBL (the world's largest open bioactivity database) for compounds
+by target, activity, or molecule name. No API key required.
+
+```bash
+# Search compounds by target name (e.g. "EGFR", "COX-2", "ACE")
+TARGET="$1"
+ENCODED=$(python3 -c "import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))" "$TARGET")
+curl -s "https://www.ebi.ac.uk/chembl/api/data/target/search?q=${ENCODED}&format=json" \
+  | python3 -c "
+import json,sys
+data=json.load(sys.stdin)
+targets=data.get('targets',[])[:5]
+for t in targets:
+    print(f\"ChEMBL ID : {t.get('target_chembl_id')}\")
+    print(f\"Name      : {t.get('pref_name')}\")
+    print(f\"Type      : {t.get('target_type')}\")
+    print()
+"
+```
+
+```bash
+# Get bioactivity data for a ChEMBL target ID
+TARGET_ID="$1"   # e.g. CHEMBL203
+curl -s "https://www.ebi.ac.uk/chembl/api/data/activity?target_chembl_id=${TARGET_ID}&pchembl_value__gte=6&limit=10&format=json" \
+  | python3 -c "
+import json,sys
+data=json.load(sys.stdin)
+acts=data.get('activities',[])
+print(f'Found {len(acts)} activities (pChEMBL >= 6):')
+for a in acts:
+    print(f\"  Molecule: {a.get('molecule_chembl_id')}  |  {a.get('standard_type')}: {a.get('standard_value')} {a.get('standard_units')}  |  pChEMBL: {a.get('pchembl_value')}\")
+"
+```
+
+```bash
+# Look up a specific molecule by ChEMBL ID
+MOL_ID="$1"   # e.g. CHEMBL25 (aspirin)
+curl -s "https://www.ebi.ac.uk/chembl/api/data/molecule/${MOL_ID}?format=json" \
+  | python3 -c "
+import json,sys
+m=json.load(sys.stdin)
+props=m.get('molecule_properties',{}) or {}
+print(f\"Name       : {m.get('pref_name','N/A')}\")
+print(f\"SMILES     : {m.get('molecule_structures',{}).get('canonical_smiles','N/A') if m.get('molecule_structures') else 'N/A'}\")
+print(f\"MW         : {props.get('full_mwt','N/A')} Da\")
+print(f\"LogP       : {props.get('alogp','N/A')}\")
+print(f\"HBD        : {props.get('hbd','N/A')}\")
+print(f\"HBA        : {props.get('hba','N/A')}\")
+print(f\"TPSA       : {props.get('psa','N/A')} Ų\")
+print(f\"Ro5 violations: {props.get('num_ro5_violations','N/A')}\")
+print(f\"QED        : {props.get('qed_weighted','N/A')}\")
+"
+```
+
+### 2 — Drug-Likeness Calculation (Lipinski Ro5 + Veber)
+
+Assess any molecule against established oral bioavailability rules using
+PubChem's free property API — no RDKit install needed.
+
+```bash
+COMPOUND="$1"
+ENCODED=$(python3 -c "import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))" "$COMPOUND")
+curl -s "https://pubchem.ncbi.nlm.nih.gov/rest/pug/compound/name/${ENCODED}/property/MolecularWeight,XLogP,HBondDonorCount,HBondAcceptorCount,RotatableBondCount,TPSA,InChIKey/JSON" \
+  | python3 -c "
+import json,sys
+data=json.load(sys.stdin)
+props=data['PropertyTable']['Properties'][0]
+mw   = float(props.get('MolecularWeight', 0))
+logp = float(props.get('XLogP', 0))
+hbd  = int(props.get('HBondDonorCount', 0))
+hba  = int(props.get('HBondAcceptorCount', 0))
+rot  = int(props.get('RotatableBondCount', 0))
+tpsa = float(props.get('TPSA', 0))
+print('=== Lipinski Rule of Five (Ro5) ===')
+print(f'  MW   {mw:.1f} Da    {\"✓\" if mw<=500 else \"✗ VIOLATION (>500)\"}')
+print(f'  LogP {logp:.2f}       {\"✓\" if logp<=5 else \"✗ VIOLATION (>5)\"}')
+print(f'  HBD  {hbd}           {\"✓\" if hbd<=5 else \"✗ VIOLATION (>5)\"}')
+print(f'  HBA  {hba}           {\"✓\" if hba<=10 else \"✗ VIOLATION (>10)\"}')
+viol = sum([mw>500, logp>5, hbd>5, hba>10])
+print(f'  Violations: {viol}/4  {\"→ Likely orally bioavailable\" if viol<=1 else \"→ Poor oral bioavailability predicted\"}')
+print()
+print('=== Veber Oral Bioavailability Rules ===')
+print(f'  TPSA         {tpsa:.1f} Ų   {\"✓\" if tpsa<=140 else \"✗ VIOLATION (>140)\"}')
+print(f'  Rot. bonds   {rot}           {\"✓\" if rot<=10 else \"✗ VIOLATION (>10)\"}')
+print(f'  Both rules met: {\"Yes → good oral absorption predicted\" if tpsa<=140 and rot<=10 else \"No → reduced oral absorption\"}')
+"
+```
+
+### 3 — Drug Interaction & Safety Lookup (OpenFDA)
+
+```bash
+DRUG="$1"
+ENCODED=$(python3 -c "import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))" "$DRUG")
+curl -s "https://api.fda.gov/drug/label.json?search=drug_interactions:\"${ENCODED}\"&limit=3" \
+  | python3 -c "
+import json,sys
+data=json.load(sys.stdin)
+results=data.get('results',[])
+if not results:
+    print('No interaction data found in FDA labels.')
+    sys.exit()
+for r in results[:2]:
+    brand=r.get('openfda',{}).get('brand_name',['Unknown'])[0]
+    generic=r.get('openfda',{}).get('generic_name',['Unknown'])[0]
+    interactions=r.get('drug_interactions',['N/A'])[0]
+    print(f'--- {brand} ({generic}) ---')
+    print(interactions[:800])
+    print()
+"
+```
+
+```bash
+DRUG="$1"
+ENCODED=$(python3 -c "import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))" "$DRUG")
+curl -s "https://api.fda.gov/drug/event.json?search=patient.drug.medicinalproduct:\"${ENCODED}\"&count=patient.reaction.reactionmeddrapt.exact&limit=10" \
+  | python3 -c "
+import json,sys
+data=json.load(sys.stdin)
+results=data.get('results',[])
+if not results:
+    print('No adverse event data found.')
+    sys.exit()
+print(f'Top adverse events reported:')
+for r in results[:10]:
+    print(f\"  {r['count']:>5}x  {r['term']}\")
+"
+```
+
+### 4 — PubChem Compound Search
+
+```bash
+COMPOUND="$1"
+ENCODED=$(python3 -c "import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))" "$COMPOUND")
+CID=$(curl -s "https://pubchem.ncbi.nlm.nih.gov/rest/pug/compound/name/${ENCODED}/cids/TXT" | head -1 | tr -d '[:space:]')
+echo "PubChem CID: $CID"
+curl -s "https://pubchem.ncbi.nlm.nih.gov/rest/pug/compound/cid/${CID}/property/IsomericSMILES,InChIKey,IUPACName/JSON" \
+  | python3 -c "
+import json,sys
+p=json.load(sys.stdin)['PropertyTable']['Properties'][0]
+print(f\"IUPAC Name : {p.get('IUPACName','N/A')}\")
+print(f\"SMILES     : {p.get('IsomericSMILES','N/A')}\")
+print(f\"InChIKey   : {p.get('InChIKey','N/A')}\")
+"
+```
+
+### 5 — Target & Disease Literature (OpenTargets)
+
+```bash
+GENE="$1"
+curl -s -X POST "https://api.platform.opentargets.org/api/v4/graphql" \
+  -H "Content-Type: application/json" \
+  -d "{\"query\":\"{ search(queryString: \\\"${GENE}\\\", entityNames: [\\\"target\\\"], page: {index: 0, size: 1}) { hits { id score object { ... on Target { id approvedSymbol approvedName associatedDiseases(page: {index: 0, size: 5}) { count rows { score disease { id name } } } } } } } }\"}" \
+  | python3 -c "
+import json,sys
+data=json.load(sys.stdin)
+hits=data.get('data',{}).get('search',{}).get('hits',[])
+if not hits:
+    print('Target not found.')
+    sys.exit()
+obj=hits[0]['object']
+print(f\"Target: {obj.get('approvedSymbol')} — {obj.get('approvedName')}\")
+assoc=obj.get('associatedDiseases',{})
+print(f\"Associated with {assoc.get('count',0)} diseases. Top associations:\")
+for row in assoc.get('rows',[]):
+    print(f\"  Score {row['score']:.3f}  |  {row['disease']['name']}\")
+"
+```
+
+## 推理指南
+
+在分析类药性或分子性质时，始终遵循以下步骤：
+
+1. **先列出原始数值** — MW、LogP、HBD、HBA、TPSA、可旋转键数
+2. **应用规则集** — Ro5（Lipinski）、Veber、Ghose 过滤器（视情况而定）
+3. **标记风险点** — 代谢热点、hERG 风险、CNS 穿透的高 TPSA
+4. **提出优化建议** — 生物等排体替换、前药策略、环截断
+5. **注明数据来源 API** — ChEMBL、PubChem、OpenFDA 或 OpenTargets
+
+对于 ADMET（吸收、分布、代谢、排泄、毒性）问题，需系统性地逐项推理。详细指导请参阅 references/ADMET_REFERENCE.md。
+
+## 重要说明
+
+- 所有 API 均免费、公开，无需身份验证
+- ChEMBL 速率限制：批量请求之间请添加 `sleep 1`
+- FDA 数据反映已报告的不良事件，不一定代表因果关系
+- 临床决策请务必咨询持牌药剂师或医生
+
+## 快速参考
+
+| 任务 | API | 端点 |
+|------|-----|------|
+| 查找靶点 | ChEMBL | `/api/data/target/search?q=` |
+| 获取生物活性数据 | ChEMBL | `/api/data/activity?target_chembl_id=` |
+| 分子性质 | PubChem | `/rest/pug/compound/name/{name}/property/` |
+| 药物相互作用 | OpenFDA | `/drug/label.json?search=drug_interactions:` |
+| 不良事件 | OpenFDA | `/drug/event.json?search=...&count=reaction` |
+| 基因-疾病关联 | OpenTargets | GraphQL POST `/api/v4/graphql` |