Sami/hermes-agent
1
0
Fork 0
forked from Zakaria/hermes-agent
Code Pull Requests Activity

Hermes-agent

Browse Source
This commit is contained in:
Zakaria
2026-06-14 14:30:48 -04:00
commit dac4b88b94
5058 changed files with 1884848 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/research/research-bioinformatics.md
+252
View File
@@ -0,0 +1,252 @@
---
title: "生物信息学 — 来自 bioSkills 和 ClawBio 的 400+ 生物信息学技能网关"
sidebar_label: "生物信息学"
description: "来自 bioSkills 和 ClawBio 的 400+ 生物信息学技能网关"
---
{/* 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. */}
# 生物信息学
来自 bioSkills 和 ClawBio 的 400+ 生物信息学技能网关。涵盖基因组学、转录组学、单细胞分析、变异检测、药物基因组学、宏基因组学、结构生物学等领域。按需获取特定领域的参考资料。
## 技能元数据
| | |
|---|---|
| 来源 | 可选 — 使用 `hermes skills install official/research/bioinformatics` 安装 |
| 路径 | `optional-skills/research/bioinformatics` |
| 版本 | `1.0.0` |
| 平台 | linux, macos |
| 标签 | `bioinformatics`, `genomics`, `sequencing`, `biology`, `research`, `science` |
## 参考：完整 SKILL.md
:::info
以下是 Hermes 在触发该技能时加载的完整技能定义。这是 Agent 在技能激活时所看到的指令内容。
:::
# 生物信息学技能网关
当被问及生物信息学、基因组学、测序、变异检测、基因表达、单细胞分析、蛋白质结构、药物基因组学、宏基因组学、系统发育学或任何计算生物学任务时使用。
本技能是两个开源生物信息学技能库的网关。它不打包数百个特定领域的技能，而是对其建立索引并按需获取所需内容。
## 来源
◆ **bioSkills** — 385 个参考技能（代码模式、参数指南、决策树）
仓库：https://github.com/GPTomics/bioSkills
格式：每个主题一个 SKILL.md，含代码示例。支持 Python/R/CLI。
◆ **ClawBio** — 33 个可运行的流程技能（可执行脚本、可复现性包）
仓库：https://github.com/ClawBio/ClawBio
格式：带演示的 Python 脚本。每次分析导出 report.md + commands.sh + environment.yml。
## 如何获取并使用技能
1. 从下方索引中确定领域和技能名称。
2. 克隆相关仓库（浅克隆以节省时间）：
```bash
# bioSkills（参考资料）
git clone --depth 1 https://github.com/GPTomics/bioSkills.git /tmp/bioSkills
# ClawBio（可运行流程）
git clone --depth 1 https://github.com/ClawBio/ClawBio.git /tmp/ClawBio
```
3. 读取具体技能：
```bash
# bioSkills — 每个技能位于：<category>/<skill-name>/SKILL.md
cat /tmp/bioSkills/variant-calling/gatk-variant-calling/SKILL.md
# ClawBio — 每个技能位于：skills/<skill-name>/
cat /tmp/ClawBio/skills/pharmgx-reporter/README.md
```
4. 将获取的技能作为参考资料使用。这些**不是** Hermes 格式的技能——请将其视为专家领域指南。它们包含正确的参数、合适的工具标志和经过验证的流程。
## 按领域划分的技能索引
### 序列基础
bioSkills:
sequence-io/ — read-sequences, write-sequences, format-conversion, batch-processing, compressed-files, fastq-quality, filter-sequences, paired-end-fastq, sequence-statistics
sequence-manipulation/ — seq-objects, reverse-complement, transcription-translation, motif-search, codon-usage, sequence-properties, sequence-slicing
ClawBio:
seq-wrangler — 序列质控、比对与 BAM 处理（封装 FastQC、BWA、SAMtools）
### 读段质控与比对
bioSkills:
read-qc/ — quality-reports, fastp-workflow, adapter-trimming, quality-filtering, umi-processing, contamination-screening, rnaseq-qc
read-alignment/ — bwa-alignment, star-alignment, hisat2-alignment, bowtie2-alignment
alignment-files/ — sam-bam-basics, alignment-sorting, alignment-filtering, bam-statistics, duplicate-handling, pileup-generation
### 变异检测与注释
bioSkills:
variant-calling/ — gatk-variant-calling, deepvariant, variant-calling (bcftools), joint-calling, structural-variant-calling, filtering-best-practices, variant-annotation, variant-normalization, vcf-basics, vcf-manipulation, vcf-statistics, consensus-sequences, clinical-interpretation
ClawBio:
vcf-annotator — 结合祖先背景的 VEP + ClinVar + gnomAD 注释
variant-annotation — 变异注释流程
### 差异表达（Bulk RNA-seq）
bioSkills:
differential-expression/ — deseq2-basics, edger-basics, batch-correction, de-results, de-visualization, timeseries-de
rna-quantification/ — alignment-free-quant (Salmon/kallisto), featurecounts-counting, tximport-workflow, count-matrix-qc
expression-matrix/ — counts-ingest, gene-id-mapping, metadata-joins, sparse-handling
ClawBio:
rnaseq-de — 含质控、归一化和可视化的完整差异表达流程
diff-visualizer — 差异表达结果的丰富可视化与报告
### 单细胞 RNA-seq
bioSkills:
single-cell/ — preprocessing, clustering, batch-integration, cell-annotation, cell-communication, doublet-detection, markers-annotation, trajectory-inference, multimodal-integration, perturb-seq, scatac-analysis, lineage-tracing, metabolite-communication, data-io
ClawBio:
scrna-orchestrator — 完整 Scanpy 流程（质控、聚类、标记基因、注释）
scrna-embedding — 基于 scVI 的潜在嵌入与批次整合
### 空间转录组学
bioSkills:
spatial-transcriptomics/ — spatial-data-io, spatial-preprocessing, spatial-domains, spatial-deconvolution, spatial-communication, spatial-neighbors, spatial-statistics, spatial-visualization, spatial-multiomics, spatial-proteomics, image-analysis
### 表观基因组学
bioSkills:
chip-seq/ — peak-calling, differential-binding, motif-analysis, peak-annotation, chipseq-qc, chipseq-visualization, super-enhancers
atac-seq/ — atac-peak-calling, atac-qc, differential-accessibility, footprinting, motif-deviation, nucleosome-positioning
methylation-analysis/ — bismark-alignment, methylation-calling, dmr-detection, methylkit-analysis
hi-c-analysis/ — hic-data-io, tad-detection, loop-calling, compartment-analysis, contact-pairs, matrix-operations, hic-visualization, hic-differential
ClawBio:
methylation-clock — 表观遗传年龄估算
### 药物基因组学与临床
bioSkills:
clinical-databases/ — clinvar-lookup, gnomad-frequencies, dbsnp-queries, pharmacogenomics, polygenic-risk, hla-typing, variant-prioritization, somatic-signatures, tumor-mutational-burden, myvariant-queries
ClawBio:
pharmgx-reporter — 基于 23andMe/AncestryDNA 的 PGx 报告（12 个基因、31 个 SNP、51 种药物）
drug-photo — 药物照片 → 个性化 PGx 剂量卡（通过视觉识别）
clinpgx — 用于基因-药物数据和 CPIC 指南的 ClinPGx API
gwas-lookup — 跨 9 个基因组数据库的联合变异查询
gwas-prs — 基于消费者基因数据的多基因风险评分
nutrigx_advisor — 基于消费者基因数据的个性化营养建议
### 群体遗传学与 GWAS
bioSkills:
population-genetics/ — association-testing (PLINK GWAS), plink-basics, population-structure, linkage-disequilibrium, scikit-allel-analysis, selection-statistics
causal-genomics/ — mendelian-randomization, fine-mapping, colocalization-analysis, mediation-analysis, pleiotropy-detection
phasing-imputation/ — haplotype-phasing, genotype-imputation, imputation-qc, reference-panels
ClawBio:
claw-ancestry-pca — 基于 SGDP 参考面板的祖先 PCA 分析
### 宏基因组学与微生物组
bioSkills:
metagenomics/ — kraken-classification, metaphlan-profiling, abundance-estimation, functional-profiling, amr-detection, strain-tracking, metagenome-visualization
microbiome/ — amplicon-processing, diversity-analysis, differential-abundance, taxonomy-assignment, functional-prediction, qiime2-workflow
ClawBio:
claw-metagenomics — 鸟枪法宏基因组分析（分类、耐药组、功能通路）
### 基因组组装与注释
bioSkills:
genome-assembly/ — hifi-assembly, long-read-assembly, short-read-assembly, metagenome-assembly, assembly-polishing, assembly-qc, scaffolding, contamination-detection
genome-annotation/ — eukaryotic-gene-prediction, prokaryotic-annotation, functional-annotation, ncrna-annotation, repeat-annotation, annotation-transfer
long-read-sequencing/ — basecalling, long-read-alignment, long-read-qc, clair3-variants, structural-variants, medaka-polishing, nanopore-methylation, isoseq-analysis
### 结构生物学与化学信息学
bioSkills:
structural-biology/ — alphafold-predictions, modern-structure-prediction, structure-io, structure-navigation, structure-modification, geometric-analysis
chemoinformatics/ — molecular-io, molecular-descriptors, similarity-searching, substructure-search, virtual-screening, admet-prediction, reaction-enumeration
ClawBio:
struct-predictor — 本地 AlphaFold/Boltz/Chai 结构预测与比较
### 蛋白质组学
bioSkills:
proteomics/ — data-import, peptide-identification, protein-inference, quantification, differential-abundance, dia-analysis, ptm-analysis, proteomics-qc, spectral-libraries
ClawBio:
proteomics-de — 蛋白质组学差异表达分析
### 通路分析与基因网络
bioSkills:
pathway-analysis/ — go-enrichment, gsea, kegg-pathways, reactome-pathways, wikipathways, enrichment-visualization
gene-regulatory-networks/ — scenic-regulons, coexpression-networks, differential-networks, multiomics-grn, perturbation-simulation
### 免疫信息学
bioSkills:
immunoinformatics/ — mhc-binding-prediction, epitope-prediction, neoantigen-prediction, immunogenicity-scoring, tcr-epitope-binding
tcr-bcr-analysis/ — mixcr-analysis, scirpy-analysis, immcantation-analysis, repertoire-visualization, vdjtools-analysis
### CRISPR 与基因组工程
bioSkills:
crispr-screens/ — mageck-analysis, jacks-analysis, hit-calling, screen-qc, library-design, crispresso-editing, base-editing-analysis, batch-correction
genome-engineering/ — grna-design, off-target-prediction, hdr-template-design, base-editing-design, prime-editing-design
### 工作流管理
bioSkills:
workflow-management/ — snakemake-workflows, nextflow-pipelines, cwl-workflows, wdl-workflows
ClawBio:
repro-enforcer — 将任意分析导出为可复现性包（Conda 环境 + Singularity + 校验和）
galaxy-bridge — 访问 usegalaxy.org 上的 8,000+ Galaxy 工具
### 专业领域
bioSkills:
alternative-splicing/ — splicing-quantification, differential-splicing, isoform-switching, sashimi-plots, single-cell-splicing, splicing-qc
ecological-genomics/ — edna-metabarcoding, landscape-genomics, conservation-genetics, biodiversity-metrics, community-ecology, species-delimitation
epidemiological-genomics/ — pathogen-typing, variant-surveillance, phylodynamics, transmission-inference, amr-surveillance
liquid-biopsy/ — cfdna-preprocessing, ctdna-mutation-detection, fragment-analysis, tumor-fraction-estimation, methylation-based-detection, longitudinal-monitoring
epitranscriptomics/ — m6a-peak-calling, m6a-differential, m6anet-analysis, merip-preprocessing, modification-visualization
metabolomics/ — xcms-preprocessing, metabolite-annotation, normalization-qc, statistical-analysis, pathway-mapping, lipidomics, targeted-analysis, msdial-preprocessing
flow-cytometry/ — fcs-handling, gating-analysis, compensation-transformation, clustering-phenotyping, differential-analysis, cytometry-qc, doublet-detection, bead-normalization
systems-biology/ — flux-balance-analysis, metabolic-reconstruction, gene-essentiality, context-specific-models, model-curation
rna-structure/ — secondary-structure-prediction, ncrna-search, structure-probing
### 数据可视化与报告
bioSkills:
data-visualization/ — ggplot2-fundamentals, heatmaps-clustering, volcano-customization, circos-plots, genome-browser-tracks, interactive-visualization, multipanel-figures, network-visualization, upset-plots, color-palettes, specialized-omics-plots, genome-tracks
reporting/ — rmarkdown-reports, quarto-reports, jupyter-reports, automated-qc-reports, figure-export
ClawBio:
profile-report — 分析概况报告
data-extractor — 从科学图像中提取数值数据（通过视觉识别）
lit-synthesizer — PubMed/bioRxiv 检索、摘要与引用图谱
pubmed-summariser — 基因/疾病 PubMed 检索与结构化简报
### 数据库访问
bioSkills:
database-access/ — entrez-search, entrez-fetch, entrez-link, blast-searches, local-blast, sra-data, geo-data, uniprot-access, batch-downloads, interaction-databases, sequence-similarity
ClawBio:
ukb-navigator — 跨 12,000+ UK Biobank 字段的语义搜索
clinical-trial-finder — 临床试验发现
### 实验设计
bioSkills:
experimental-design/ — power-analysis, sample-size, batch-design, multiple-testing
### 组学机器学习
bioSkills:
machine-learning/ — omics-classifiers, biomarker-discovery, survival-analysis, model-validation, prediction-explanation, atlas-mapping
ClawBio:
claw-semantic-sim — 疾病文献语义相似度索引（PubMedBERT）
omics-target-evidence-mapper — 跨组学来源的靶点级证据聚合
## 环境配置
这些技能假设在生物信息学工作站上运行。常见依赖项：
```bash
# Python
pip install biopython pysam cyvcf2 pybedtools pyBigWig scikit-allel anndata scanpy mygene
# R/Bioconductor
Rscript -e 'BiocManager::install(c("DESeq2","edgeR","Seurat","clusterProfiler","methylKit"))'
# CLI 工具（Ubuntu/Debian）
sudo apt install samtools bcftools ncbi-blast+ minimap2 bedtools
# CLI 工具（macOS）
brew install samtools bcftools blast minimap2 bedtools
# 或通过 Conda（推荐，便于复现）
conda install -c bioconda samtools bcftools blast minimap2 bedtools fastp kraken2
```
## 注意事项
- 获取的技能**不是** Hermes SKILL.md 格式。它们使用各自的结构（bioSkills：代码模式手册；ClawBio：README + Python 脚本）。请将其作为专家参考资料阅读。
- bioSkills 是参考指南——展示正确的参数和代码模式，但不是可执行的流程。
- ClawBio 技能是可执行的——许多具有 `--demo` 标志，可直接运行。
- 两个仓库均假设已安装生物信息学工具。运行流程前请检查前置条件。
- 对于 ClawBio，请先在克隆的仓库中运行 `pip install -r requirements.txt`。
- 基因组数据文件可能非常大。下载参考基因组、SRA 数据集或构建索引时请注意磁盘空间。
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/research/research-darwinian-evolver.md
+188
View File
@@ -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-live-kernel`](/user-guide/skills/bundled/data-science/data-science-jupyter-live-kernel) |
## 参考：完整 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)
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/research/research-domain-intel.md
+117
View File
@@ -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) 贡献*
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/research/research-drug-discovery.md
+237
View File
@@ -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` |
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/research/research-duckduckgo-search.md
+255
View File
@@ -0,0 +1,255 @@
---
title: "Duckduckgo Search — 通过 DuckDuckGo 免费搜索网络 — 文本、新闻、图片、视频"
sidebar_label: "Duckduckgo Search"
description: "通过 DuckDuckGo 免费搜索网络 — 文本、新闻、图片、视频"
---
{/* 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. */}
# Duckduckgo Search
通过 DuckDuckGo 免费搜索网络 — 文本、新闻、图片、视频。无需 API 密钥。已安装时优先使用 `ddgs` CLI；仅在确认当前运行时中 `ddgs` 可用后，才使用 Python DDGS 库。
## Skill 元数据
| | |
|---|---|
| 来源 | 可选 — 使用 `hermes skills install official/research/duckduckgo-search` 安装 |
| 路径 | `optional-skills/research/duckduckgo-search` |
| 版本 | `1.3.0` |
| 作者 | gamedevCloudy |
| 许可证 | MIT |
| 平台 | linux, macos, windows |
| 标签 | `search`, `duckduckgo`, `web-search`, `free`, `fallback` |
| 相关 skill | [`arxiv`](/user-guide/skills/bundled/research/research-arxiv) |
## 参考：完整 SKILL.md
:::info
以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。
:::
# DuckDuckGo Search
使用 DuckDuckGo 进行免费网络搜索。**无需 API 密钥。**
当 `web_search` 不可用或不适用时（例如未设置 `FIRECRAWL_API_KEY`），优先使用此 skill。也可在明确需要 DuckDuckGo 结果时作为独立搜索路径使用。
## 检测流程
在选择方案前，先检查实际可用的工具：
```bash
# Check CLI availability
command -v ddgs >/dev/null && echo "DDGS_CLI=installed" || echo "DDGS_CLI=missing"
```
决策树：
1. 若 `ddgs` CLI 已安装，优先使用 `terminal` + `ddgs`
2. 若 `ddgs` CLI 未安装，不要假设 `execute_code` 能导入 `ddgs`
3. 若用户明确需要 DuckDuckGo，先在相关环境中安装 `ddgs`
4. 否则回退到内置的 web/browser 工具
重要运行时说明：
- Terminal 与 `execute_code` 是独立的运行时
- shell 中安装成功不代表 `execute_code` 能导入 `ddgs`
- 永远不要假设 `execute_code` 内已预装第三方 Python 包
## 安装
仅在明确需要 DuckDuckGo 搜索且运行时尚未提供时，才安装 `ddgs`。
```bash
# Python package + CLI entrypoint
pip install ddgs
# Verify CLI
ddgs --help
```
若工作流依赖 Python 导入，请在使用 `from ddgs import DDGS` 前，先验证该运行时能否导入 `ddgs`。
## 方法一：CLI 搜索（推荐）
当 `ddgs` 命令存在时，通过 `terminal` 使用它。这是推荐路径，因为它避免了假设 `execute_code` 沙箱中已安装 `ddgs` Python 包。
```bash
# Text search
ddgs text -q "python async programming" -m 5
# News search
ddgs news -q "artificial intelligence" -m 5
# Image search
ddgs images -q "landscape photography" -m 10
# Video search
ddgs videos -q "python tutorial" -m 5
# With region filter
ddgs text -q "best restaurants" -m 5 -r us-en
# Recent results only (d=day, w=week, m=month, y=year)
ddgs text -q "latest AI news" -m 5 -t w
# JSON output for parsing
ddgs text -q "fastapi tutorial" -m 5 -o json
```
### CLI 参数
| 参数 | 说明 | 示例 |
|------|-------------|---------|
| `-q` | 查询词 — **必填** | `-q "search terms"` |
| `-m` | 最大结果数 | `-m 5` |
| `-r` | 地区 | `-r us-en` |
| `-t` | 时间范围 | `-t w`（一周） |
| `-s` | 安全搜索 | `-s off` |
| `-o` | 输出格式 | `-o json` |
## 方法二：Python API（仅在验证后使用）
仅在确认 `ddgs` 已安装于该运行时后，才在 `execute_code` 或其他 Python 运行时中使用 `DDGS` 类。不要默认认为 `execute_code` 包含第三方包。
正确表述：
- "在安装或确认包可用后，在 `execute_code` 中使用 `ddgs`"
避免表述：
- "`execute_code` 包含 `ddgs`"
- "DuckDuckGo 搜索在 `execute_code` 中默认可用"
**重要：** `max_results` 必须始终以**关键字参数**形式传入 — 所有方法中以位置参数传入均会报错。
### 文本搜索
适用场景：通用研究、公司信息、文档查询。
```python
from ddgs import DDGS
with DDGS() as ddgs:
for r in ddgs.text("python async programming", max_results=5):
print(r["title"])
print(r["href"])
print(r.get("body", "")[:200])
print()
```
返回字段：`title`、`href`、`body`
### 新闻搜索
适用场景：时事动态、突发新闻、最新更新。
```python
from ddgs import DDGS
with DDGS() as ddgs:
for r in ddgs.news("AI regulation 2026", max_results=5):
print(r["date"], "-", r["title"])
print(r.get("source", ""), "|", r["url"])
print(r.get("body", "")[:200])
print()
```
返回字段：`date`、`title`、`body`、`url`、`image`、`source`
### 图片搜索
适用场景：视觉参考、产品图片、示意图。
```python
from ddgs import DDGS
with DDGS() as ddgs:
for r in ddgs.images("semiconductor chip", max_results=5):
print(r["title"])
print(r["image"])
print(r.get("thumbnail", ""))
print(r.get("source", ""))
print()
```
返回字段：`title`、`image`、`thumbnail`、`url`、`height`、`width`、`source`
### 视频搜索
适用场景：教程、演示、讲解视频。
```python
from ddgs import DDGS
with DDGS() as ddgs:
for r in ddgs.videos("FastAPI tutorial", max_results=5):
print(r["title"])
print(r.get("content", ""))
print(r.get("duration", ""))
print(r.get("provider", ""))
print(r.get("published", ""))
print()
```
返回字段：`title`、`content`、`description`、`duration`、`provider`、`published`、`statistics`、`uploader`
### 快速参考
| 方法 | 适用场景 | 关键字段 |
|--------|----------|------------|
| `text()` | 通用研究、公司信息 | title, href, body |
| `news()` | 时事动态、最新更新 | date, title, source, body, url |
| `images()` | 视觉内容、示意图 | title, image, thumbnail, url |
| `videos()` | 教程、演示 | title, content, duration, provider |
## 工作流：先搜索后提取
DuckDuckGo 返回标题、URL 和摘要，而非完整页面内容。如需获取完整页面内容，先搜索，再用 `web_extract`、browser 工具或 curl 提取最相关的 URL。
CLI 示例：
```bash
ddgs text -q "fastapi deployment guide" -m 3 -o json
```
Python 示例，仅在确认该运行时已安装 `ddgs` 后使用：
```python
from ddgs import DDGS
with DDGS() as ddgs:
results = list(ddgs.text("fastapi deployment guide", max_results=3))
for r in results:
print(r["title"], "->", r["href"])
```
然后使用 `web_extract` 或其他内容获取工具提取最佳 URL 的内容。
## 限制
- **频率限制**：大量快速请求后，DuckDuckGo 可能进行限流。如有需要，在多次搜索之间添加短暂延迟。
- **无内容提取**：`ddgs` 返回摘要，而非完整页面内容。如需完整文章/页面，请使用 `web_extract`、browser 工具或 curl。
- **结果质量**：总体良好，但可配置性不如 Firecrawl 的搜索。
- **可用性**：DuckDuckGo 可能屏蔽来自部分云 IP 的请求。若搜索返回空结果，请尝试不同关键词或等待几秒后重试。
- **字段可变性**：不同结果或 `ddgs` 版本间返回字段可能有所不同。对可选字段使用 `.get()` 以避免 `KeyError`。
- **独立运行时**：在 terminal 中成功安装 `ddgs` 不代表 `execute_code` 能自动导入它。
## 故障排查
| 问题 | 可能原因 | 处理方式 |
|---------|--------------|------------|
| `ddgs: command not found` | CLI 未安装在 shell 环境中 | 安装 `ddgs`，或改用内置 web/browser 工具 |
| `ModuleNotFoundError: No module named 'ddgs'` | Python 运行时未安装该包 | 在准备好该运行时之前，不要在其中使用 Python DDGS |
| 搜索无结果 | 临时限流或查询词不佳 | 等待几秒后重试，或调整查询词 |
| CLI 正常但 `execute_code` 导入失败 | Terminal 与 `execute_code` 是不同的运行时 | 继续使用 CLI，或单独准备 Python 运行时 |
## 常见陷阱
- **`max_results` 仅支持关键字参数**：`ddgs.text("query", 5)` 会报错，请使用 `ddgs.text("query", max_results=5)`。
- **不要假设 CLI 已存在**：使用前先检查 `command -v ddgs`。
- **不要假设 `execute_code` 能导入 `ddgs`**：除非该运行时已单独准备，否则 `from ddgs import DDGS` 可能抛出 `ModuleNotFoundError`。
- **包名**：该包名为 `ddgs`（原名 `duckduckgo-search`），使用 `pip install ddgs` 安装。
- **不要混淆 `-q` 和 `-m`**（CLI）：`-q` 用于查询词，`-m` 用于最大结果数。
- **空结果**：若 `ddgs` 返回空结果，可能是被限流。等待几秒后重试。
## 验证版本
已针对 `ddgs==9.11.2` 语义验证示例。Skill 指南现将 CLI 可用性与 Python 导入可用性视为独立问题，以确保文档化的工作流与实际运行时行为一致。
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/research/research-gitnexus-explorer.md
+213
View File
@@ -0,0 +1,213 @@
---
title: "Gitnexus Explorer"
sidebar_label: "Gitnexus Explorer"
description: "使用 GitNexus 为代码库建立索引，并通过 Web UI + Cloudflare 隧道提供交互式知识图谱服务"
---
{/* 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. */}
# Gitnexus Explorer
使用 GitNexus 为代码库建立索引，并通过 Web UI + Cloudflare 隧道提供交互式知识图谱服务。
## Skill 元数据
| | |
|---|---|
| 来源 | 可选 — 使用 `hermes skills install official/research/gitnexus-explorer` 安装 |
| 路径 | `optional-skills/research/gitnexus-explorer` |
| 版本 | `1.0.0` |
| 作者 | Hermes Agent + Teknium |
| 许可证 | MIT |
| 平台 | linux, macos, windows |
| 标签 | `gitnexus`, `code-intelligence`, `knowledge-graph`, `visualization` |
| 相关 skill | [`native-mcp`](/user-guide/skills/bundled/mcp/mcp-native-mcp), [`codebase-inspection`](/user-guide/skills/bundled/github/github-codebase-inspection) |
## 参考：完整 SKILL.md
:::info
以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。
:::
# GitNexus Explorer
将任意代码库索引为知识图谱，并提供交互式 Web UI，用于探索符号、调用链、聚类和执行流。通过 Cloudflare 隧道实现远程访问。
## 适用场景
- 用户希望可视化探索代码库架构
- 用户请求生成某个仓库的知识图谱/依赖图
- 用户希望与他人共享交互式代码库浏览器
## 前置条件
- **Node.js**（v18+）— GitNexus 和代理所需
- **git** — 仓库必须包含 `.git` 目录
- **cloudflared** — 用于隧道（如缺失，自动安装至 `~/.local/bin`）
## 规模警告
Web UI 在浏览器中渲染所有节点。文件数不超过约 5,000 的仓库运行良好。大型仓库（30k+ 节点）会导致浏览器标签页卡顿或崩溃。CLI/MCP 工具在任何规模下均可正常工作——仅 Web 可视化存在此限制。
## 步骤
### 1. 克隆并构建 GitNexus（一次性设置）
```bash
GITNEXUS_DIR="${GITNEXUS_DIR:-$HOME/.local/share/gitnexus}"
if [ ! -d "$GITNEXUS_DIR/gitnexus-web/dist" ]; then
git clone https://github.com/abhigyanpatwari/GitNexus.git "$GITNEXUS_DIR"
cd "$GITNEXUS_DIR/gitnexus-shared" && npm install && npm run build
cd "$GITNEXUS_DIR/gitnexus-web" && npm install
fi
```
### 2. 为远程访问修补 Web UI
Web UI 默认使用 `localhost:4747` 进行 API 调用。将其修补为使用同源地址，以便通过隧道/代理正常工作：
**文件：`$GITNEXUS_DIR/gitnexus-web/src/config/ui-constants.ts`**
将：
```typescript
export const DEFAULT_BACKEND_URL = 'http://localhost:4747';
```
改为：
```typescript
export const DEFAULT_BACKEND_URL = typeof window !== 'undefined' && window.location.hostname !== 'localhost' ? window.location.origin : 'http://localhost:4747';
```
**文件：`$GITNEXUS_DIR/gitnexus-web/vite.config.ts`**
在 `server: { }` 块内添加 `allowedHosts: true`（仅在使用开发模式而非生产构建时需要）：
```typescript
server: {
allowedHosts: true,
// ... existing config
},
```
然后构建生产包：
```bash
cd "$GITNEXUS_DIR/gitnexus-web" && npx vite build
```
### 3. 为目标仓库建立索引
```bash
cd /path/to/target-repo
npx gitnexus analyze --skip-agents-md
rm -rf .claude/ # remove Claude Code-specific artifacts
```
添加 `--embeddings` 可启用语义搜索（速度较慢——需要数分钟而非数秒）。
索引存储在仓库内的 `.gitnexus/` 目录中（已自动加入 `.gitignore`）。
### 4. 创建代理脚本
将以下内容写入文件（例如 `$GITNEXUS_DIR/proxy.mjs`）。它提供生产 Web UI 服务，并将 `/api/*` 代理至 GitNexus 后端——同源，无 CORS 问题，无需 sudo，无需 nginx。
```javascript
import http from 'node:http';
import fs from 'node:fs';
import path from 'node:path';
const API_PORT = parseInt(process.env.API_PORT || '4747');
const DIST_DIR = process.argv[2] || './dist';
const PORT = parseInt(process.argv[3] || '8888');
const MIME = {
'.html': 'text/html', '.js': 'application/javascript', '.css': 'text/css',
'.json': 'application/json', '.png': 'image/png', '.svg': 'image/svg+xml',
'.ico': 'image/x-icon', '.woff2': 'font/woff2', '.woff': 'font/woff',
'.wasm': 'application/wasm',
};
function proxyToApi(req, res) {
const opts = {
hostname: '127.0.0.1', port: API_PORT,
path: req.url, method: req.method, headers: req.headers,
};
const proxy = http.request(opts, (upstream) => {
res.writeHead(upstream.statusCode, upstream.headers);
upstream.pipe(res, { end: true });
});
proxy.on('error', () => { res.writeHead(502); res.end('Backend unavailable'); });
req.pipe(proxy, { end: true });
}
function serveStatic(req, res) {
let filePath = path.join(DIST_DIR, req.url === '/' ? 'index.html' : req.url.split('?')[0]);
if (!fs.existsSync(filePath)) filePath = path.join(DIST_DIR, 'index.html');
const ext = path.extname(filePath);
const mime = MIME[ext] || 'application/octet-stream';
try {
const data = fs.readFileSync(filePath);
res.writeHead(200, { 'Content-Type': mime, 'Cache-Control': 'public, max-age=3600' });
res.end(data);
} catch { res.writeHead(404); res.end('Not found'); }
}
http.createServer((req, res) => {
if (req.url.startsWith('/api')) proxyToApi(req, res);
else serveStatic(req, res);
}).listen(PORT, () => console.log(`GitNexus proxy on http://localhost:${PORT}`));
```
### 5. 启动服务
```bash
# Terminal 1: GitNexus backend API
npx gitnexus serve &
# Terminal 2: Proxy (web UI + API on one port)
node "$GITNEXUS_DIR/proxy.mjs" "$GITNEXUS_DIR/gitnexus-web/dist" 8888 &
```
验证：`curl -s http://localhost:8888/api/repos` 应返回已索引的仓库。
### 6. 通过 Cloudflare 建立隧道（可选——用于远程访问）
```bash
# Install cloudflared if needed (no sudo)
if ! command -v cloudflared &>/dev/null; then
mkdir -p ~/.local/bin
curl -sL https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 \
-o ~/.local/bin/cloudflared
chmod +x ~/.local/bin/cloudflared
export PATH="$HOME/.local/bin:$PATH"
fi
# Start tunnel (--config /dev/null avoids conflicts with existing named tunnels)
cloudflared tunnel --config /dev/null --url http://localhost:8888 --no-autoupdate --protocol http2
```
隧道 URL（例如 `https://random-words.trycloudflare.com`）将输出至 stderr。分享该链接——任何拥有链接的人均可探索图谱。
### 7. 清理
```bash
# Stop services
pkill -f "gitnexus serve"
pkill -f "proxy.mjs"
pkill -f cloudflared
# Remove index from the target repo
cd /path/to/target-repo
npx gitnexus clean
rm -rf .claude/
```
## 注意事项
- **`cloudflared` 必须使用 `--config /dev/null`**：若用户在 `~/.cloudflared/config.yml` 中存在已命名的隧道配置，则不加此参数时，配置中的兜底 ingress 规则会对所有快速隧道请求返回 404。
- **隧道必须使用生产构建。** Vite 开发服务器默认阻止非 localhost 主机（`allowedHosts`）。使用生产构建 + Node 代理可完全规避此问题。
- **Web UI 不会创建 `.claude/` 或 `CLAUDE.md`。** 这些文件由 `npx gitnexus analyze` 创建。使用 `--skip-agents-md` 可抑制 markdown 文件的生成，再用 `rm -rf .claude/` 清除其余内容。这些是 Claude Code 集成产物，Hermes Agent 用户无需使用。
- **浏览器内存限制。** Web UI 将整个图谱加载至浏览器内存。文件数超过 5k 的仓库可能出现卡顿，超过 30k 文件的仓库很可能导致标签页崩溃。
- **Embedding（嵌入）为可选项。** `--embeddings` 可启用语义搜索，但在大型仓库上需要数分钟。如需快速探索可跳过；若希望通过 AI 对话面板进行自然语言查询，则可添加此选项。
- **多仓库支持。** `gitnexus serve` 会服务所有已索引的仓库。可先为多个仓库建立索引，再启动一次 serve，Web UI 支持在各仓库间切换。
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/research/research-osint-investigation.md
+243
View File
@@ -0,0 +1,243 @@
---
title: "Osint Investigation"
sidebar_label: "Osint Investigation"
description: "公开记录 OSINT 调查框架 — SEC EDGAR 文件、USAspending 合同、参议院游说、OFAC 制裁、ICIJ 离岸泄露、纽约市房产记录（ACRIS）、OpenCorporates 注册信息、CourtListener 法院记录、Wayback Machine 存档、Wikipedia + Wikidata、GDELT 新闻监控。跨来源实体解析、交叉链接分析、时序关联、证据链。仅使用 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. */}
# Osint Investigation
公开记录 OSINT（开源情报）调查框架 — SEC EDGAR 文件、USAspending 合同、参议院游说、OFAC 制裁、ICIJ 离岸泄露、纽约市房产记录（ACRIS）、OpenCorporates 注册信息、CourtListener 法院记录、Wayback Machine 存档、Wikipedia + Wikidata、GDELT 新闻监控。跨来源实体解析、交叉链接分析、时序关联、证据链。仅使用 Python 标准库。
## Skill 元数据
| | |
|---|---|
| 来源 | 可选 — 通过 `hermes skills install official/research/osint-investigation` 安装 |
| 路径 | `optional-skills/research/osint-investigation` |
| 版本 | `0.1.0` |
| 作者 | Hermes Agent（改编自 ShinMegamiBoson/OpenPlanter，MIT 许可）|
| 平台 | linux, macos, windows |
| 标签 | `osint`, `investigation`, `public-records`, `sec`, `sanctions`, `corporate-registry`, `property`, `courts`, `due-diligence`, `journalism` |
| 相关 skill | [`domain-intel`](/user-guide/skills/optional/research/research-domain-intel), [`arxiv`](/user-guide/skills/bundled/research/research-arxiv) |
## 参考：完整 SKILL.md
:::info
以下是 Hermes 在触发该 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时看到的指令内容。
:::
# OSINT 调查 — 公开记录交叉核查
公开记录 OSINT 调查框架：政府合同、企业文件、游说、制裁、离岸泄露、房产记录、法院记录、网络存档、知识库及全球新闻。跨异构来源解析实体，以显式置信度构建交叉链接，运行统计时序检验，并生成结构化证据链。
**仅使用 Python 标准库。** 零安装。支持 Linux、macOS、Windows。大多数来源无需 API 密钥（OpenCorporates 有可选的免费 token，可提高速率限制）。
改编自 MIT 许可的 ShinMegamiBoson/OpenPlanter 项目；扩展覆盖了原项目未涉及的身份/房产/诉讼/存档/新闻来源。
## 何时使用此 skill
当用户请求以下内容时使用：
- "追踪资金流向" — 政府合同、游说 → 立法、制裁
- 企业尽职调查 — 谁控制公司 X、在哪里注册、谁担任董事会成员、提交了哪些文件
- 制裁筛查 — 实体 X 是否在 OFAC SDN 名单或 ICIJ 离岸泄露中
- 权钱交易调查 — 有离岸关联的承包商、赢得合同的游说客户
- 房产所有权 — 按姓名或地址查找已记录的契约/抵押（纽约市；其他县请用户查阅相关记录机构）
- 诉讼历史 — 查找联邦及州法院意见和 PACER 案卷
- 跨来源实体解析（命名存在差异，如 LLC 后缀、缩写）
- 以显式置信度构建证据链
- "关于 X 有哪些报道" — 国际新闻（GDELT）+ Wikipedia 叙述 + Wayback Machine 恢复失效 URL
**不适用**此 skill 的场景：
- 通用网络研究 → `web_search` / `web_extract`
- 域名/基础设施 OSINT → `domain-intel` skill
- 学术文献 → `arxiv` skill
- 社交媒体账号发现 → `sherlock` skill（可选）
- 美国**联邦**竞选财务 — FEC 在此处有意不覆盖（免费 DEMO_KEY 层级的 API 对临时贡献者姓名查询不可靠）。联邦捐款请直接引导用户访问 https://www.fec.gov/data/。
## 工作流程
Agent 通过 `terminal` 工具运行脚本。`SKILL_DIR` 是存放此 SKILL.md 的目录。
### 1. 确定适用的数据来源
阅读数据来源 wiki 条目以规划调查：
```
ls SKILL_DIR/references/sources/
# 联邦财务 / 监管
cat SKILL_DIR/references/sources/sec-edgar.md # 企业文件
cat SKILL_DIR/references/sources/usaspending.md # 联邦合同
cat SKILL_DIR/references/sources/senate-ld.md # 游说
cat SKILL_DIR/references/sources/ofac-sdn.md # 制裁
cat SKILL_DIR/references/sources/icij-offshore.md # 离岸泄露
# 身份 / 房产 / 诉讼 / 存档 / 新闻
cat SKILL_DIR/references/sources/nyc-acris.md # 纽约市房产记录
cat SKILL_DIR/references/sources/opencorporates.md # 全球企业注册信息
cat SKILL_DIR/references/sources/courtlistener.md # 法院记录（联邦 + 州）
cat SKILL_DIR/references/sources/wayback.md # Wayback Machine 存档
cat SKILL_DIR/references/sources/wikipedia.md # Wikipedia + Wikidata
cat SKILL_DIR/references/sources/gdelt.md # 全球新闻监控
```
每个条目遵循 9 节模板：摘要、访问、schema、覆盖范围、交叉引用键、数据质量、获取方式、法律说明、参考资料。
**交叉引用潜力**部分列出了来源之间的关联键 — 优先阅读这部分以选择合适的配对。
### 2. 获取数据
每个来源在 `SKILL_DIR/scripts/` 中都有仅使用标准库的抓取脚本：
**联邦财务 / 监管**
```bash
# SEC EDGAR 文件（企业披露）
python3 SKILL_DIR/scripts/fetch_sec_edgar.py --cik 0000320193 \
--types 10-K,10-Q --out data/edgar_filings.csv
# USAspending 联邦合同
python3 SKILL_DIR/scripts/fetch_usaspending.py --recipient "EXAMPLE CORP" \
--fy 2024 --out data/contracts.csv
# 参议院 LD-1 / LD-2 游说披露
python3 SKILL_DIR/scripts/fetch_senate_ld.py --client "EXAMPLE CORP" \
--year 2024 --out data/lobbying.csv
# OFAC SDN 制裁名单（完整快照）
python3 SKILL_DIR/scripts/fetch_ofac_sdn.py --out data/ofac_sdn.csv
# ICIJ 离岸泄露 — 首次使用时下载约 70 MB 批量 CSV，
# 之后在本地搜索。缓存 30 天，存储于
# $HERMES_OSINT_CACHE/icij/（默认：~/.cache/hermes-osint/icij/）。
python3 SKILL_DIR/scripts/fetch_icij_offshore.py --entity "EXAMPLE CORP" \
--out data/icij.csv
```
**身份 / 房产 / 诉讼 / 存档 / 新闻**
```bash
# 纽约市房产记录（契约、抵押、留置权）— 通过 Socrata 访问 ACRIS
python3 SKILL_DIR/scripts/fetch_nyc_acris.py --name "SMITH, JOHN" \
--out data/acris.csv
python3 SKILL_DIR/scripts/fetch_nyc_acris.py --address "571 HUDSON" \
--out data/acris_addr.csv
# OpenCorporates — 130+ 司法管辖区企业注册信息
# （需要免费 token；设置 OPENCORPORATES_API_TOKEN 或传入 --token）
python3 SKILL_DIR/scripts/fetch_opencorporates.py --query "Example Corp" \
--jurisdiction us_ny --out data/opencorporates.csv
# CourtListener — 联邦 + 州法院意见、PACER 案卷
python3 SKILL_DIR/scripts/fetch_courtlistener.py --query "Smith v. Example Corp" \
--type opinions --out data/courts.csv
# Wayback Machine — 历史网页快照
python3 SKILL_DIR/scripts/fetch_wayback.py --url "example.com" \
--match host --collapse digest --out data/wayback.csv
# Wikipedia + Wikidata — 叙述性传记 + 结构化事实
# 设置 HERMES_OSINT_UA=your-app/1.0 (your@email) 以标识自身
python3 SKILL_DIR/scripts/fetch_wikipedia.py --query "Bill Gates" \
--out data/wp.csv
# GDELT — 100+ 语言全球新闻，约 2015 年至今
python3 SKILL_DIR/scripts/fetch_gdelt.py --query '"Example Corp"' \
--timespan 1y --out data/gdelt.csv
```
所有输出均为带标题行的标准化 CSV。脚本可幂等重复运行。
当私人个人不会出现在某来源中时（例如非上市公司人员不在 SEC EDGAR 中，非联邦承包商不在 USAspending 中，非游说客户不在参议院 LDA 中），脚本返回 0 行并给出明确警告，而不是静默写入空 CSV。EDGAR 会特别标记公司名称解析器匹配到的是个人 Form 3/4/5 申报人而非企业注册人的情况。
速率限制说明见各来源的 wiki 条目。默认抓取器在分页请求之间会礼貌地休眠。**API 密钥可提高支持它们的来源的速率限制**（`SEC_USER_AGENT`、`SENATE_LDA_TOKEN`、`OPENCORPORATES_API_TOKEN`、`COURTLISTENER_TOKEN`）。所有脚本会立即将 429 响应及上游配额消息呈现给用户，以便用户知道需要降速或提供密钥。
### 3. 跨来源实体解析
规范化名称并在两个 CSV 文件之间查找匹配：
```bash
# 将游说客户（参议院 LDA）与合同受益人（USAspending）进行匹配
python3 SKILL_DIR/scripts/entity_resolution.py \
--left data/lobbying.csv --left-name-col client_name \
--right data/contracts.csv --right-name-col recipient_name \
--out data/cross_links.csv
```
三个匹配层级，附带显式置信度：
| 层级 | 方法 | 置信度 |
|------|--------|------------|
| `exact` | 去除后缀/标点后规范化字符串相等 | 高 |
| `fuzzy` | 排序词元相等（词袋匹配） | 中 |
| `token_overlap` | ≥60% 词元重叠，≥2 个共享词元，词元 ≥4 个字符 | 低 |
输出 `cross_links.csv` 列：`match_type, confidence, left_name, right_name, left_normalized, right_normalized, left_row, right_row`。
### 4. 统计时序关联（可选）
检验两个时间序列是否存在可疑的时间聚集 — 例如游说文件提交时间与合同授予时间接近 — 使用置换检验（permutation test）：
```bash
python3 SKILL_DIR/scripts/timing_analysis.py \
--donations data/lobbying.csv --donation-date-col filing_date \
--donation-amount-col income --donation-donor-col client_name \
--donation-recipient-col registrant_name \
--contracts data/contracts.csv --contract-date-col award_date \
--contract-vendor-col recipient_name \
--cross-links data/cross_links.csv \
--permutations 1000 \
--out data/timing.json
```
脚本的列标志是有意设计为通用的 — 原工具是为捐款与合同授予场景编写的，但它适用于任何通过交叉链接关联的（事件，收款方）时间序列。零假设：事件时序与合同授予日期无关。单尾 p 值 = 置换中平均最近合同距离 ≤ 观测值的比例。每个（付款方，供应商）配对至少需要 3 个事件才能运行检验。
### 5. 构建调查结果 JSON（证据链）
```bash
python3 SKILL_DIR/scripts/build_findings.py \
--cross-links data/cross_links.csv \
--timing data/timing.json \
--out data/findings.json
```
每条调查结果包含 `id, title, severity, confidence, summary, evidence[], sources[]`。每个证据项指向来源 CSV 中的具体行。用户（或后续 agent）可以对照来源验证每项声明。
## 置信度与证据规范
这是该 skill 的核心规则。告知用户：
- 每项声明必须可追溯至具体记录。不得有无依据的断言。
- 置信度层级随声明传递。`match_type=fuzzy` 表示"可能"，而非"已确认"。
- 实体解析产生的是候选结果，而非结论。"ACME LLC"与"Acme Holdings Group"之间的 `fuzzy` 匹配是线索，不是事实。
- 统计显著性 ≠ 违规行为。p &lt; 0.05 意味着该时序模式在零假设下不太可能出现，并不能证明腐败。
- 此处所有数据来源均为公开记录，但仍可能包含不准确信息、过时信息或已编辑内容（GDPR、封存记录）。
## 添加新数据来源
使用模板：
```bash
cp SKILL_DIR/templates/source-template.md \
SKILL_DIR/references/sources/<your-source>.md
```
填写全部 9 个部分。在 `scripts/` 中编写仅使用标准库的 `fetch_<source>.py` 脚本，输出标准化 CSV。在上方"何时使用"部分更新来源列表。
## 工具及其限制
- `entity_resolution.py` 不使用外部模糊匹配库（无 rapidfuzz，无 jellyfish）。词袋匹配是此处的上限。如需 Levenshtein 距离、音译或音素匹配，请单独 pip 安装。
- `timing_analysis.py` 使用 Python 的 `random` 模块进行置换。如需可复现性，请传入 `--seed N`。
- `fetch_*.py` 脚本使用 `urllib.request` 并遵守 `Retry-After` 头。大量批量使用仍可能违反服务条款 — 请先阅读各来源的法律说明部分。
## 法律说明
所有第一阶段来源均为公开记录。根据各自的访问条款（FOIA、公开记录法、ICIJ 明确发布、OFAC 公开数据），允许批量获取。但是：
- 部分来源速率限制较为严格。请遵守其响应头。
- 部分来源会编辑注册人信息（WHOIS 的 GDPR 合规、封存文件）。
- 交叉引用公开记录以识别私人个人可能存在伦理影响。该 skill 生成的是证据链，而非指控。
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/research/research-parallel-cli.md
+411
View File
@@ -0,0 +1,411 @@
---
title: "Parallel Cli"
sidebar_label: "Parallel Cli"
description: "可选的供应商技能，用于 Parallel CLI — 面向 agent 的网络搜索、提取、深度研究、数据丰富、FindAll 和监控"
---
{/* 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. */}
# Parallel Cli
可选的供应商技能，用于 Parallel CLI — 面向 agent 的网络搜索、提取、深度研究、数据丰富、FindAll 和监控。优先使用 JSON 输出和非交互式流程。
## 技能元数据
| | |
|---|---|
| 来源 | 可选 — 使用 `hermes skills install official/research/parallel-cli` 安装 |
| 路径 | `optional-skills/research/parallel-cli` |
| 版本 | `1.1.0` |
| 作者 | Hermes Agent |
| 许可证 | MIT |
| 平台 | linux, macos, windows |
| 标签 | `Research`, `Web`, `Search`, `Deep-Research`, `Enrichment`, `CLI` |
| 相关技能 | [`duckduckgo-search`](/user-guide/skills/optional/research/research-duckduckgo-search), [`mcporter`](/user-guide/skills/optional/mcp/mcp-mcporter) |
## 参考：完整 SKILL.md
:::info
以下是 Hermes 在触发此技能时加载的完整技能定义。这是 agent 在技能激活时所看到的指令内容。
:::
# Parallel CLI
当用户明确要求使用 Parallel，或终端原生工作流能从 Parallel 的供应商专属技术栈中受益时（包括网络搜索、提取、深度研究、数据丰富、实体发现或监控），请使用 `parallel-cli`。
这是一个可选的第三方工作流，不是 Hermes 的核心能力。
重要说明：
- Parallel 是付费服务，提供免费套餐，并非完全免费的本地工具。
- 它与 Hermes 原生的 `web_search` / `web_extract` 存在功能重叠，因此不要在普通查询中优先使用它。
- 当用户明确提及 Parallel，或需要 Parallel 特有的数据丰富、FindAll 或监控工作流时，优先使用此技能。
`parallel-cli` 专为 agent 设计：
- 通过 `--json` 输出 JSON
- 非交互式命令执行
- 使用 `--no-wait`、`status` 和 `poll` 处理异步长时任务
- 通过 `--previous-interaction-id` 进行上下文链式调用
- 在单一 CLI 中集成搜索、提取、研究、数据丰富、实体发现和监控
## 使用时机
在以下情况下优先使用此技能：
- 用户明确提及 Parallel 或 `parallel-cli`
- 任务需要比简单单次搜索/提取更丰富的工作流
- 需要可启动并稍后轮询的异步深度研究任务
- 需要结构化数据丰富、FindAll 实体发现或监控
在未明确要求 Parallel 的情况下进行快速单次查询时，优先使用 Hermes 原生的 `web_search` / `web_extract`。
## 安装
选择当前环境中侵入性最小的安装方式。
### Homebrew
```bash
brew install parallel-web/tap/parallel-cli
```
### npm
```bash
npm install -g parallel-web-cli
```
### Python 包
```bash
pip install "parallel-web-tools[cli]"
```
### 独立安装程序
```bash
curl -fsSL https://parallel.ai/install.sh | bash
```
如果需要隔离的 Python 安装，也可以使用 `pipx`：
```bash
pipx install "parallel-web-tools[cli]"
pipx ensurepath
```
## 认证
交互式登录：
```bash
parallel-cli login
```
无头模式 / SSH / CI：
```bash
parallel-cli login --device
```
API 密钥环境变量：
```bash
export PARALLEL_API_KEY="***"
```
验证当前认证状态：
```bash
parallel-cli auth
```
如果认证需要浏览器交互，请使用 `pty=true` 运行。
## 核心规则
1. 需要机器可读输出时，始终优先使用 `--json`。
2. 优先使用显式参数和非交互式流程。
3. 对于长时任务，使用 `--no-wait`，然后调用 `status` / `poll`。
4. 仅引用 CLI 输出中返回的 URL。
5. 当后续可能有追问时，将大型 JSON 输出保存到临时文件。
6. 仅对真正的长时工作流使用后台进程；否则在前台运行。
7. 除非用户明确要求 Parallel 或需要 Parallel 专属工作流，否则优先使用 Hermes 原生工具。
## 快速参考
<!-- ascii-guard-ignore -->
```text
parallel-cli
├── auth
├── login
├── logout
├── search
├── extract / fetch
├── research run|status|poll|processors
├── enrich run|status|poll|plan|suggest|deploy
├── findall run|ingest|status|poll|result|enrich|extend|schema|cancel
└── monitor create|list|get|update|delete|events|event-group|simulate
```
<!-- ascii-guard-ignore-end -->
## 常用标志与模式
常用标志：
- `--json` 用于结构化输出
- `--no-wait` 用于异步任务
- `--previous-interaction-id <id>` 用于复用早期上下文的后续任务
- `--max-results <n>` 用于限制搜索结果数量
- `--mode one-shot|agentic` 用于控制搜索行为
- `--include-domains domain1.com,domain2.com`
- `--exclude-domains domain1.com,domain2.com`
- `--after-date YYYY-MM-DD`
在方便时从 stdin 读取：
```bash
echo "What is the latest funding for Anthropic?" | parallel-cli search - --json
echo "Research question" | parallel-cli research run - --json
```
## 搜索
用于获取带结构化结果的当前网络查询。
```bash
parallel-cli search "What is Anthropic's latest AI model?" --json
parallel-cli search "SEC filings for Apple" --include-domains sec.gov --json
parallel-cli search "bitcoin price" --after-date 2026-01-01 --max-results 10 --json
parallel-cli search "latest browser benchmarks" --mode one-shot --json
parallel-cli search "AI coding agent enterprise reviews" --mode agentic --json
```
常用约束：
- `--include-domains` 缩小可信来源范围
- `--exclude-domains` 过滤噪声域名
- `--after-date` 按时效性过滤
- `--max-results` 需要更广泛覆盖时使用
如果预计有后续追问，保存输出：
```bash
parallel-cli search "latest React 19 changes" --json -o /tmp/react-19-search.json
```
汇总结果时：
- 以答案开头
- 包含日期、名称和具体事实
- 仅引用返回的来源
- 不得编造 URL 或来源标题
## 提取
用于从 URL 中提取干净内容或 markdown。
```bash
parallel-cli extract https://example.com --json
parallel-cli extract https://company.com --objective "Find pricing info" --json
parallel-cli extract https://example.com --full-content --json
parallel-cli fetch https://example.com --json
```
当页面内容宽泛而只需要其中某一部分信息时，使用 `--objective`。
## 深度研究
用于可能耗时的多步骤深度研究任务。
常用处理器级别：
- `lite` / `base` 用于更快、更经济的处理
- `core` / `pro` 用于更全面的综合分析
- `ultra` 用于最重量级的研究任务
### 同步模式
```bash
parallel-cli research run \
"Compare the leading AI coding agents by pricing, model support, and enterprise controls" \
--processor core \
--json
```
### 异步启动 + 轮询
```bash
parallel-cli research run \
"Compare the leading AI coding agents by pricing, model support, and enterprise controls" \
--processor ultra \
--no-wait \
--json
parallel-cli research status trun_xxx --json
parallel-cli research poll trun_xxx --json
parallel-cli research processors --json
```
### 上下文链式调用 / 后续追问
```bash
parallel-cli research run "What are the top AI coding agents?" --json
parallel-cli research run \
"What enterprise controls does the top-ranked one offer?" \
--previous-interaction-id trun_xxx \
--json
```
推荐的 Hermes 工作流：
1. 使用 `--no-wait --json` 启动
2. 捕获返回的运行/任务 ID
3. 如果用户希望继续其他工作，继续推进
4. 稍后调用 `status` 或 `poll`
5. 使用返回来源中的引用汇总最终报告
## 数据丰富（Enrichment）
当用户有 CSV/JSON/表格输入并希望通过网络研究推断额外列时使用。
### 建议列
```bash
parallel-cli enrich suggest "Find the CEO and annual revenue" --json
```
### 规划配置
```bash
parallel-cli enrich plan -o config.yaml
```
### 内联数据
```bash
parallel-cli enrich run \
--data '[{"company": "Anthropic"}, {"company": "Mistral"}]' \
--intent "Find headquarters and employee count" \
--json
```
### 非交互式文件运行
```bash
parallel-cli enrich run \
--source-type csv \
--source companies.csv \
--target enriched.csv \
--source-columns '[{"name": "company", "description": "Company name"}]' \
--intent "Find the CEO and annual revenue"
```
### YAML 配置运行
```bash
parallel-cli enrich run config.yaml
```
### 状态 / 轮询
```bash
parallel-cli enrich status <task_group_id> --json
parallel-cli enrich poll <task_group_id> --json
```
在非交互式操作时，使用显式 JSON 数组定义列。
在报告成功前验证输出文件。
## FindAll
当用户需要发现数据集而非简短答案时，用于网络规模的实体发现。
```bash
parallel-cli findall run "Find AI coding agent startups with enterprise offerings" --json
parallel-cli findall run "AI startups in healthcare" -n 25 --json
parallel-cli findall status <run_id> --json
parallel-cli findall poll <run_id> --json
parallel-cli findall result <run_id> --json
parallel-cli findall schema <run_id> --json
```
当用户需要一组可供后续审查、过滤或数据丰富的实体集合时，这比普通搜索更合适。
## 监控（Monitor）
用于随时间推移的持续变更检测。
```bash
parallel-cli monitor list --json
parallel-cli monitor get <monitor_id> --json
parallel-cli monitor events <monitor_id> --json
parallel-cli monitor delete <monitor_id> --json
```
创建通常是敏感环节，因为频率和推送方式很重要：
```bash
parallel-cli monitor create --help
```
当用户希望对某个页面或来源进行周期性跟踪而非一次性抓取时使用。
## 推荐的 Hermes 使用模式
### 快速答案与引用
1. 运行 `parallel-cli search ... --json`
2. 解析标题、URL、日期、摘录
3. 仅使用返回的 URL 进行内联引用并汇总
### URL 调查
1. 运行 `parallel-cli extract URL --json`
2. 如有需要，使用 `--objective` 或 `--full-content` 重新运行
3. 引用或汇总提取的 markdown
### 长时研究工作流
1. 运行 `parallel-cli research run ... --no-wait --json`
2. 存储返回的 ID
3. 继续其他工作或定期轮询
4. 使用引用汇总最终报告
### 结构化数据丰富工作流
1. 检查输入文件和列
2. 使用 `enrich suggest` 或提供显式的丰富列定义
3. 运行 `enrich run`
4. 如有需要，轮询等待完成
5. 在报告成功前验证输出文件
## 错误处理与退出码
CLI 文档中定义的退出码：
- `0` 成功
- `2` 输入错误
- `3` 认证错误
- `4` API 错误
- `5` 超时
遇到认证错误时：
1. 检查 `parallel-cli auth`
2. 确认 `PARALLEL_API_KEY` 已设置，或运行 `parallel-cli login` / `parallel-cli login --device`
3. 验证 `parallel-cli` 在 `PATH` 中
## 维护
检查当前认证 / 安装状态：
```bash
parallel-cli auth
parallel-cli --help
```
更新命令：
```bash
parallel-cli update
pip install --upgrade parallel-web-tools
parallel-cli config auto-update-check off
```
## 注意事项
- 除非用户明确要求人类可读格式，否则不要省略 `--json`。
- 不要引用 CLI 输出中未出现的来源。
- `login` 可能需要 PTY/浏览器交互。
- 短时任务优先在前台执行；不要过度使用后台进程。
- 对于大型结果集，将 JSON 保存到 `/tmp/*.json`，而不是将所有内容塞入上下文。
- 当 Hermes 原生工具已经足够时，不要静默地选择 Parallel。
- 请记住，这是一个供应商工作流，通常需要账户认证，且超出免费套餐后需要付费使用。
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/research/research-qmd.md
+435
View File
@@ -0,0 +1,435 @@
---
title: "Qmd"
sidebar_label: "Qmd"
description: "使用 qmd 在本地搜索个人知识库、笔记、文档和会议记录 — 一个集成 BM25、向量搜索和 LLM 重排序的混合检索引擎"
---
{/* 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. */}
# Qmd
使用 qmd 在本地搜索个人知识库、笔记、文档和会议记录 — 一个集成 BM25、向量搜索和 LLM 重排序的混合检索引擎。支持 CLI 和 MCP 集成。
## Skill 元数据
| | |
|---|---|
| 来源 | 可选 — 通过 `hermes skills install official/research/qmd` 安装 |
| 路径 | `optional-skills/research/qmd` |
| 版本 | `1.0.0` |
| 作者 | Hermes Agent + Teknium |
| 许可证 | MIT |
| 平台 | macos, linux |
| 标签 | `Search`, `Knowledge-Base`, `RAG`, `Notes`, `MCP`, `Local-AI` |
| 相关 skill | [`obsidian`](/user-guide/skills/bundled/note-taking/note-taking-obsidian), [`native-mcp`](/user-guide/skills/bundled/mcp/mcp-native-mcp), [`arxiv`](/user-guide/skills/bundled/research/research-arxiv) |
## 参考：完整 SKILL.md
:::info
以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
:::
# QMD — Query Markup Documents
本地设备上的个人知识库搜索引擎。可索引 markdown 笔记、会议记录、文档及任何基于文本的文件，并提供结合关键词匹配、语义理解和 LLM 重排序的混合搜索 — 全部在本地运行，无需云端依赖。
由 [Tobi Lütke](https://github.com/tobi/qmd) 创建。MIT 许可证。
## 使用场景
- 用户要求搜索其笔记、文档、知识库或会议记录
- 用户希望在大量 markdown/文本文件中查找内容
- 用户需要语义搜索（"查找关于 X 概念的笔记"），而非仅仅是关键词 grep
- 用户已设置 qmd 集合并希望查询
- 用户要求搭建本地知识库或文档搜索系统
- 关键词："search my notes"、"find in my docs"、"knowledge base"、"qmd"
## 前置条件
### Node.js >= 22（必需）
```bash
# 检查版本
node --version # must be >= 22
# macOS — install or upgrade via Homebrew
brew install node@22
# Linux — use NodeSource or nvm
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
# or with nvm:
nvm install 22 && nvm use 22
```
### SQLite 扩展支持（仅 macOS）
macOS 系统自带的 SQLite 不支持扩展加载。请通过 Homebrew 安装：
```bash
brew install sqlite
```
### 安装 qmd
```bash
npm install -g @tobilu/qmd
# or with Bun:
bun install -g @tobilu/qmd
```
首次运行会自动下载 3 个本地 GGUF 模型（共约 2GB）：
| 模型 | 用途 | 大小 |
|-------|---------|------|
| embeddinggemma-300M-Q8_0 | 向量 embedding（嵌入） | ~300MB |
| qwen3-reranker-0.6b-q8_0 | 结果重排序 | ~640MB |
| qmd-query-expansion-1.7B | 查询扩展 | ~1.1GB |
### 验证安装
```bash
qmd --version
qmd status
```
## 快速参考
| 命令 | 功能 | 速度 |
|---------|-------------|-------|
| `qmd search "query"` | BM25 关键词搜索（无需模型） | ~0.2s |
| `qmd vsearch "query"` | 语义向量搜索（1 个模型） | ~3s |
| `qmd query "query"` | 混合搜索 + 重排序（全部 3 个模型） | 热启动 ~2-3s，冷启动 ~19s |
| `qmd get <docid>` | 获取完整文档内容 | 即时 |
| `qmd multi-get "glob"` | 批量获取文件 | 即时 |
| `qmd collection add <path> --name <n>` | 将目录添加为集合 | 即时 |
| `qmd context add <path> "description"` | 添加上下文元数据以提升检索效果 | 即时 |
| `qmd embed` | 生成/更新向量 embedding | 不定 |
| `qmd status` | 显示索引健康状态和集合信息 | 即时 |
| `qmd mcp` | 启动 MCP 服务器（stdio） | 持久运行 |
| `qmd mcp --http --daemon` | 启动 MCP 服务器（HTTP，模型保持热启动） | 持久运行 |
## 设置流程
### 1. 添加集合
将 qmd 指向包含文档的目录：
```bash
# Add a notes directory
qmd collection add ~/notes --name notes
# Add project docs
qmd collection add ~/projects/myproject/docs --name project-docs
# Add meeting transcripts
qmd collection add ~/meetings --name meetings
# List all collections
qmd collection list
```
### 2. 添加上下文描述
上下文元数据帮助搜索引擎理解每个集合的内容，可显著提升检索质量：
```bash
qmd context add qmd://notes "Personal notes, ideas, and journal entries"
qmd context add qmd://project-docs "Technical documentation for the main project"
qmd context add qmd://meetings "Meeting transcripts and action items from team syncs"
```
### 3. 生成 Embedding
```bash
qmd embed
```
此命令处理所有集合中的所有文档并生成向量 embedding。添加新文档或集合后需重新运行。
### 4. 验证
```bash
qmd status # shows index health, collection stats, model info
```
## 搜索模式
### 快速关键词搜索（BM25）
适用场景：精确词语、代码标识符、名称、已知短语。
无需加载模型 — 近乎即时返回结果。
```bash
qmd search "authentication middleware"
qmd search "handleError async"
```
### 语义向量搜索
适用场景：自然语言问题、概念性查询。
首次查询时加载 embedding 模型（约 3s）。
```bash
qmd vsearch "how does the rate limiter handle burst traffic"
qmd vsearch "ideas for improving onboarding flow"
```
### 混合搜索 + 重排序（最佳质量）
适用场景：对质量要求最高的重要查询。
使用全部 3 个模型 — 查询扩展、并行 BM25+向量搜索、重排序。
```bash
qmd query "what decisions were made about the database migration"
```
### 结构化多模式查询
在单次查询中组合不同搜索类型以提升精度：
```bash
# BM25 for exact term + vector for concept
qmd query $'lex: rate limiter\nvec: how does throttling work under load'
# With query expansion
qmd query $'expand: database migration plan\nlex: "schema change"'
```
### 查询语法（lex/BM25 模式）
| 语法 | 效果 | 示例 |
|--------|--------|---------|
| `term` | 前缀匹配 | `perf` 匹配 "performance" |
| `"phrase"` | 精确短语 | `"rate limiter"` |
| `-term` | 排除词语 | `performance -sports` |
### HyDE（假设文档 Embedding）
对于复杂主题，可描述你期望答案的样子：
```bash
qmd query $'hyde: The migration plan involves three phases. First, we add the new columns without dropping the old ones. Then we backfill data. Finally we cut over and remove legacy columns.'
```
### 限定集合范围
```bash
qmd search "query" --collection notes
qmd query "query" --collection project-docs
```
### 输出格式
```bash
qmd search "query" --json # JSON output (best for parsing)
qmd search "query" --limit 5 # Limit results
qmd get "#abc123" # Get by document ID
qmd get "path/to/file.md" # Get by file path
qmd get "file.md:50" -l 100 # Get specific line range
qmd multi-get "journals/*.md" --json # Batch retrieve by glob
```
## MCP 集成（推荐）
qmd 提供 MCP 服务器，可通过原生 MCP 客户端直接向 Hermes Agent 提供搜索工具。这是推荐的集成方式 — 配置完成后，agent 无需每次加载此 skill 即可自动获得 qmd 工具。
### 方案 A：Stdio 模式（简单）
在 `~/.hermes/config.yaml` 中添加：
```yaml
mcp_servers:
qmd:
command: "qmd"
args: ["mcp"]
timeout: 30
connect_timeout: 45
```
此配置注册以下工具：`mcp_qmd_search`、`mcp_qmd_vsearch`、`mcp_qmd_deep_search`、`mcp_qmd_get`、`mcp_qmd_status`。
**权衡：** 模型在首次搜索调用时加载（冷启动约 19s），之后在会话期间保持热启动状态。偶尔使用时可接受。
### 方案 B：HTTP Daemon 模式（快速，重度使用推荐）
单独启动 qmd daemon — 它会将模型保持在内存中：
```bash
# Start daemon (persists across agent restarts)
qmd mcp --http --daemon
# Runs on http://localhost:8181 by default
```
然后配置 Hermes Agent 通过 HTTP 连接：
```yaml
mcp_servers:
qmd:
url: "http://localhost:8181/mcp"
timeout: 30
```
**权衡：** 运行时占用约 2GB 内存，但每次查询都很快（约 2-3s）。适合频繁搜索的用户。
### 保持 Daemon 持续运行
#### macOS（launchd）
```bash
cat > ~/Library/LaunchAgents/com.qmd.daemon.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.qmd.daemon</string>
<key>ProgramArguments</key>
<array>
<string>qmd</string>
<string>mcp</string>
<string>--http</string>
<string>--daemon</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
<key>StandardOutPath</key>
<string>/tmp/qmd-daemon.log</string>
<key>StandardErrorPath</key>
<string>/tmp/qmd-daemon.log</string>
</dict>
</plist>
EOF
launchctl load ~/Library/LaunchAgents/com.qmd.daemon.plist
```
#### Linux（systemd 用户服务）
```bash
mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/qmd-daemon.service << 'EOF'
[Unit]
Description=QMD MCP Daemon
After=network.target
[Service]
ExecStart=qmd mcp --http --daemon
Restart=on-failure
RestartSec=10
Environment=PATH=/usr/local/bin:/usr/bin:/bin
[Install]
WantedBy=default.target
EOF
systemctl --user daemon-reload
systemctl --user enable --now qmd-daemon
systemctl --user status qmd-daemon
```
### MCP 工具参考
连接后，以下工具以 `mcp_qmd_*` 形式可用：
| MCP 工具 | 对应命令 | 描述 |
|----------|---------|-------------|
| `mcp_qmd_search` | `qmd search` | BM25 关键词搜索 |
| `mcp_qmd_vsearch` | `qmd vsearch` | 语义向量搜索 |
| `mcp_qmd_deep_search` | `qmd query` | 混合搜索 + 重排序 |
| `mcp_qmd_get` | `qmd get` | 通过 ID 或路径获取文档 |
| `mcp_qmd_status` | `qmd status` | 索引健康状态和统计信息 |
MCP 工具接受结构化 JSON 查询以支持多模式搜索：
```json
{
"searches": [
{"type": "lex", "query": "authentication middleware"},
{"type": "vec", "query": "how user login is verified"}
],
"collections": ["project-docs"],
"limit": 10
}
```
## CLI 用法（不使用 MCP）
未配置 MCP 时，直接通过终端使用 qmd：
```
terminal(command="qmd query 'what was decided about the API redesign' --json", timeout=30)
```
设置和管理任务始终使用终端：
```
terminal(command="qmd collection add ~/Documents/notes --name notes")
terminal(command="qmd context add qmd://notes 'Personal research notes and ideas'")
terminal(command="qmd embed")
terminal(command="qmd status")
```
## 搜索流水线工作原理
了解内部机制有助于选择合适的搜索模式：
1. **查询扩展** — 一个经过微调的 1.7B 模型生成 2 个备选查询。原始查询在融合中获得 2 倍权重。
2. **并行检索** — BM25（SQLite FTS5）和向量搜索跨所有查询变体并行运行。
3. **RRF 融合** — 倒数排名融合（k=60）合并结果。顶部排名加成：第 1 名 +0.05，第 2-3 名 +0.02。
4. **LLM 重排序** — qwen3-reranker 对前 30 个候选结果评分（0.0-1.0）。
5. **位置感知混合** — 排名 1-3：75% 检索 / 25% 重排序。排名 4-10：60/40。排名 11+：40/60（对长尾结果更信任重排序）。
**智能分块：** 文档在自然断点处分割（标题、代码块、空行），目标约 900 个 token，重叠率 15%。代码块不会在中间被截断。
## 最佳实践
1. **始终添加上下文描述** — `qmd context add` 可显著提升检索准确性。描述每个集合包含的内容。
2. **添加文档后重新 embed** — 向集合添加新文件后必须重新运行 `qmd embed`。
3. **速度优先用 `qmd search`** — 需要快速关键词查找（代码标识符、精确名称）时，BM25 即时响应且无需模型。
4. **质量优先用 `qmd query`** — 问题具有概念性或用户需要最佳结果时，使用混合搜索。
5. **优先使用 MCP 集成** — 配置完成后，agent 无需每次加载此 skill 即可获得原生工具。
6. **频繁用户使用 daemon 模式** — 如果用户经常搜索知识库，建议设置 HTTP daemon。
7. **结构化搜索中第一个查询获得 2 倍权重** — 组合 lex 和 vec 时，将最重要/最确定的查询放在首位。
## 故障排查
### "首次运行时模型正在下载"
正常现象 — qmd 首次使用时会自动下载约 2GB 的 GGUF 模型。
这是一次性操作。
### 冷启动延迟（约 19s）
模型未加载到内存时会出现此情况。解决方案：
- 使用 HTTP daemon 模式（`qmd mcp --http --daemon`）保持热启动
- 不需要模型时使用 `qmd search`（仅 BM25）
- MCP stdio 模式在首次搜索时加载模型，会话期间保持热启动
### macOS："unable to load extension"
安装 Homebrew SQLite：`brew install sqlite`
然后确保其在系统 SQLite 之前出现在 PATH 中。
### "未找到集合"
运行 `qmd collection add <path> --name <name>` 添加目录，
然后运行 `qmd embed` 进行索引。
### Embedding 模型覆盖（CJK/多语言）
为非英语内容设置 `QMD_EMBED_MODEL` 环境变量：
```bash
export QMD_EMBED_MODEL="your-multilingual-model"
```
## 数据存储
- **索引与向量：** `~/.cache/qmd/index.sqlite`
- **模型：** 首次运行时自动下载到本地缓存
- **无云端依赖** — 全部在本地运行
## 参考资料
- [GitHub: tobi/qmd](https://github.com/tobi/qmd)
- [QMD 更新日志](https://github.com/tobi/qmd/blob/main/CHANGELOG.md)
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/research/research-scrapling.md
+351
View File
@@ -0,0 +1,351 @@
---
title: "Scrapling"
sidebar_label: "Scrapling"
description: "使用 Scrapling 进行网页抓取——HTTP 获取、隐身浏览器自动化、Cloudflare 绕过及通过 CLI 和 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. */}
# Scrapling
使用 Scrapling 进行网页抓取——HTTP 获取、隐身浏览器自动化、Cloudflare 绕过及通过 CLI 和 Python 进行爬虫抓取。
## Skill 元数据
| | |
|---|---|
| 来源 | 可选——使用 `hermes skills install official/research/scrapling` 安装 |
| 路径 | `optional-skills/research/scrapling` |
| 版本 | `1.0.0` |
| 作者 | FEUAZUR |
| 许可证 | MIT |
| 平台 | linux, macos, windows |
| 标签 | `Web Scraping`, `Browser`, `Cloudflare`, `Stealth`, `Crawling`, `Spider` |
| 相关 skill | [`duckduckgo-search`](/user-guide/skills/optional/research/research-duckduckgo-search), [`domain-intel`](/user-guide/skills/optional/research/research-domain-intel) |
## 参考：完整 SKILL.md
:::info
以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
:::
# Scrapling
[Scrapling](https://github.com/D4Vinci/Scrapling) 是一个具备反机器人绕过、隐身浏览器自动化和爬虫框架的网页抓取框架。它提供三种获取策略（HTTP、动态 JS、隐身/Cloudflare）以及完整的 CLI。
**本 skill 仅供教育和研究目的使用。** 用户必须遵守当地及国际数据抓取法律，并尊重网站服务条款。
## 使用场景
- 抓取静态 HTML 页面（比浏览器工具更快）
- 抓取需要真实浏览器的 JS 渲染页面
- 绕过 Cloudflare Turnstile 或机器人检测
- 使用爬虫抓取多个页面
- 当内置 `web_extract` 工具无法返回所需数据时
## 安装
```bash
pip install "scrapling[all]"
scrapling install
```
最小安装（仅 HTTP，无浏览器）：
```bash
pip install scrapling
```
仅含浏览器自动化：
```bash
pip install "scrapling[fetchers]"
scrapling install
```
## 快速参考
| 方式 | 类 | 使用场景 |
|----------|-------|----------|
| HTTP | `Fetcher` / `FetcherSession` | 静态页面、API、快速批量请求 |
| 动态 | `DynamicFetcher` / `DynamicSession` | JS 渲染内容、SPA |
| 隐身 | `StealthyFetcher` / `StealthySession` | Cloudflare、反机器人保护站点 |
| 爬虫 | `Spider` | 跟随链接的多页面抓取 |
## CLI 用法
### 提取静态页面
```bash
scrapling extract get 'https://example.com' output.md
```
使用 CSS 选择器和浏览器模拟：
```bash
scrapling extract get 'https://example.com' output.md \
--css-selector '.content' \
--impersonate 'chrome'
```
### 提取 JS 渲染页面
```bash
scrapling extract fetch 'https://example.com' output.md \
--css-selector '.dynamic-content' \
--disable-resources \
--network-idle
```
### 提取 Cloudflare 保护页面
```bash
scrapling extract stealthy-fetch 'https://protected-site.com' output.html \
--solve-cloudflare \
--block-webrtc \
--hide-canvas
```
### POST 请求
```bash
scrapling extract post 'https://example.com/api' output.json \
--json '{"query": "search term"}'
```
### 输出格式
输出格式由文件扩展名决定：
- `.html` —— 原始 HTML
- `.md` —— 转换为 Markdown
- `.txt` —— 纯文本
- `.json` / `.jsonl` —— JSON
## Python：HTTP 抓取
### 单次请求
```python
from scrapling.fetchers import Fetcher
page = Fetcher.get('https://quotes.toscrape.com/')
quotes = page.css('.quote .text::text').getall()
for q in quotes:
print(q)
```
### Session（持久化 Cookie）
```python
from scrapling.fetchers import FetcherSession
with FetcherSession(impersonate='chrome') as session:
page = session.get('https://example.com/', stealthy_headers=True)
links = page.css('a::attr(href)').getall()
for link in links[:5]:
sub = session.get(link)
print(sub.css('h1::text').get())
```
### POST / PUT / DELETE
```python
page = Fetcher.post('https://api.example.com/data', json={"key": "value"})
page = Fetcher.put('https://api.example.com/item/1', data={"name": "updated"})
page = Fetcher.delete('https://api.example.com/item/1')
```
### 使用代理
```python
page = Fetcher.get('https://example.com', proxy='http://user:pass@proxy:8080')
```
## Python：动态页面（JS 渲染）
适用于需要执行 JavaScript 的页面（SPA、懒加载内容）：
```python
from scrapling.fetchers import DynamicFetcher
page = DynamicFetcher.fetch('https://example.com', headless=True)
data = page.css('.js-loaded-content::text').getall()
```
### 等待特定元素
```python
page = DynamicFetcher.fetch(
'https://example.com',
wait_selector=('.results', 'visible'),
network_idle=True,
)
```
### 禁用资源以提升速度
阻止字体、图片、媒体、样式表（速度提升约 25%）：
```python
from scrapling.fetchers import DynamicSession
with DynamicSession(headless=True, disable_resources=True, network_idle=True) as session:
page = session.fetch('https://example.com')
items = page.css('.item::text').getall()
```
### 自定义页面自动化
```python
from playwright.sync_api import Page
from scrapling.fetchers import DynamicFetcher
def scroll_and_click(page: Page):
page.mouse.wheel(0, 3000)
page.wait_for_timeout(1000)
page.click('button.load-more')
page.wait_for_selector('.extra-results')
page = DynamicFetcher.fetch('https://example.com', page_action=scroll_and_click)
results = page.css('.extra-results .item::text').getall()
```
## Python：隐身模式（反机器人绕过）
适用于 Cloudflare 保护或高度指纹识别的站点：
```python
from scrapling.fetchers import StealthyFetcher
page = StealthyFetcher.fetch(
'https://protected-site.com',
headless=True,
solve_cloudflare=True,
block_webrtc=True,
hide_canvas=True,
)
content = page.css('.protected-content::text').getall()
```
### 隐身 Session
```python
from scrapling.fetchers import StealthySession
with StealthySession(headless=True, solve_cloudflare=True) as session:
page1 = session.fetch('https://protected-site.com/page1')
page2 = session.fetch('https://protected-site.com/page2')
```
## 元素选择
所有 fetcher 均返回一个 `Selector` 对象，包含以下方法：
### CSS 选择器
```python
page.css('h1::text').get() # 第一个 h1 文本
page.css('a::attr(href)').getall() # 所有链接 href
page.css('.quote .text::text').getall() # 嵌套选择
```
### XPath
```python
page.xpath('//div[@class="content"]/text()').getall()
page.xpath('//a/@href').getall()
```
### Find 方法
```python
page.find_all('div', class_='quote') # 按标签 + 属性查找
page.find_by_text('Read more', tag='a') # 按文本内容查找
page.find_by_regex(r'\$\d+\.\d{2}') # 按正则表达式查找
```
### 相似元素
查找具有相似结构的元素（适用于商品列表等）：
```python
first_product = page.css('.product')[0]
all_similar = first_product.find_similar()
```
### 导航
```python
el = page.css('.target')[0]
el.parent # 父元素
el.children # 子元素
el.next_sibling # 下一个兄弟元素
el.prev_sibling # 上一个兄弟元素
```
## Python：爬虫框架
适用于跟随链接的多页面抓取：
```python
from scrapling.spiders import Spider, Request, Response
class QuotesSpider(Spider):
name = "quotes"
start_urls = ["https://quotes.toscrape.com/"]
concurrent_requests = 10
download_delay = 1
async def parse(self, response: Response):
for quote in response.css('.quote'):
yield {
"text": quote.css('.text::text').get(),
"author": quote.css('.author::text').get(),
"tags": quote.css('.tag::text').getall(),
}
next_page = response.css('.next a::attr(href)').get()
if next_page:
yield response.follow(next_page)
result = QuotesSpider().start()
print(f"Scraped {len(result.items)} quotes")
result.items.to_json("quotes.json")
```
### 多 Session 爬虫
将请求路由到不同的 fetcher 类型：
```python
from scrapling.fetchers import FetcherSession, AsyncStealthySession
class SmartSpider(Spider):
name = "smart"
start_urls = ["https://example.com/"]
def configure_sessions(self, manager):
manager.add("fast", FetcherSession(impersonate="chrome"))
manager.add("stealth", AsyncStealthySession(headless=True), lazy=True)
async def parse(self, response: Response):
for link in response.css('a::attr(href)').getall():
if "protected" in link:
yield Request(link, sid="stealth")
else:
yield Request(link, sid="fast", callback=self.parse)
```
### 暂停/恢复抓取
```python
spider = QuotesSpider(crawldir="./crawl_checkpoint")
spider.start() # 按 Ctrl+C 暂停，重新运行以从检查点恢复
```
## 注意事项
- **需要安装浏览器**：pip 安装后运行 `scrapling install`——否则 `DynamicFetcher` 和 `StealthyFetcher` 将无法使用
- **超时**：DynamicFetcher/StealthyFetcher 的超时单位为**毫秒**（默认 30000），Fetcher 的超时单位为**秒**
- **Cloudflare 绕过**：`solve_cloudflare=True` 会增加 5-15 秒的获取时间——仅在必要时启用
- **资源占用**：StealthyFetcher 运行真实浏览器——限制并发使用量
- **法律合规**：抓取前务必检查 robots.txt 和网站服务条款。本库仅供教育和研究目的使用
- **Python 版本**：需要 Python 3.10+
website/i18n/zh-Hans/docusaurus-plugin-content-docs/current/user-guide/skills/optional/research/research-searxng-search.md
+229
View File
@@ -0,0 +1,229 @@
---
title: "Searxng Search — 通过 SearXNG 免费元搜索 — 聚合 70+ 搜索引擎的结果"
sidebar_label: "Searxng Search"
description: "通过 SearXNG 免费元搜索 — 聚合 70+ 搜索引擎的结果"
---
{/* 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. */}
# Searxng Search
通过 SearXNG 免费元搜索（meta-search）——聚合 70+ 搜索引擎的结果。可自托管或使用公共实例。无需 API 密钥。当 web 搜索工具集不可用时自动回退。
## Skill 元数据
| | |
|---|---|
| 来源 | 可选 — 使用 `hermes skills install official/research/searxng-search` 安装 |
| 路径 | `optional-skills/research/searxng-search` |
| 版本 | `1.0.0` |
| 作者 | hermes-agent |
| 许可证 | MIT |
| 平台 | linux, macos |
| 标签 | `search`, `searxng`, `meta-search`, `self-hosted`, `free`, `fallback` |
| 相关 skill | [`duckduckgo-search`](/user-guide/skills/optional/research/research-duckduckgo-search), [`domain-intel`](/user-guide/skills/optional/research/research-domain-intel) |
## 参考：完整 SKILL.md
:::info
以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 skill 激活时 agent 所看到的指令内容。
:::
# SearXNG Search
使用 [SearXNG](https://searxng.org/) 进行免费元搜索——这是一个注重隐私的自托管搜索聚合器，可同时查询 70+ 搜索引擎。
使用公共实例时**无需 API 密钥**。也可自托管以获得完全控制权。当主 web 搜索工具集（`FIRECRAWL_API_KEY`）未配置时，自动作为回退方案出现。
## 配置
SearXNG 需要一个 `SEARXNG_URL` 环境变量，指向你的 SearXNG 实例：
```bash
# 公共实例（无需任何设置）
SEARXNG_URL=https://searxng.example.com
# 自托管 SearXNG
SEARXNG_URL=http://localhost:8888
```
如果未配置实例，此 skill 不可用，agent 将回退到其他搜索选项。
## 检测流程
在选择方案之前，先检查实际可用的内容：
```bash
# 检查 SEARXNG_URL 是否已设置且实例可访问
curl -s --max-time 5 "${SEARXNG_URL}/search?q=test&format=json" | head -c 200
```
决策树：
1. 如果 `SEARXNG_URL` 已设置且实例响应，则使用 SearXNG
2. 如果 `SEARXNG_URL` 未设置或不可访问，则回退到其他可用搜索工具
3. 如果用户明确需要 SearXNG，帮助他们搭建实例或找到公共实例
## 方法一：通过 curl 使用 CLI（推荐）
通过 `terminal` 使用 `curl` 调用 SearXNG JSON API。这样可以避免假设安装了特定的 Python 包。
```bash
# 文本搜索（JSON 输出）
curl -s --max-time 10 \
"${SEARXNG_URL}/search?q=python+async+programming&format=json&engines=google,bing&limit=10"
# 关闭安全搜索
curl -s --max-time 10 \
"${SEARXNG_URL}/search?q=example&format=json&safesearch=0"
# 指定分类（general、news、science 等）
curl -s --max-time 10 \
"${SEARXNG_URL}/search?q=AI+news&format=json&categories=news"
```
### 常用 CLI 参数
| 参数 | 说明 | 示例 |
|------|-------------|---------|
| `q` | 查询字符串（URL 编码） | `q=python+async` |
| `format` | 输出格式：`json`、`csv`、`rss` | `format=json` |
| `engines` | 逗号分隔的引擎名称 | `engines=google,bing,ddg` |
| `limit` | 每个引擎的最大结果数（默认 10） | `limit=5` |
| `categories` | 按分类过滤 | `categories=news,science` |
| `safesearch` | 0=无，1=适中，2=严格 | `safesearch=0` |
| `time_range` | 过滤：`day`、`week`、`month`、`year` | `time_range=week` |
### 解析 JSON 结果
```bash
# 从 JSON 中提取标题和 URL
curl -s --max-time 10 "${SEARXNG_URL}/search?q=fastapi&format=json&limit=5" \
| python3 -c "
import json, sys
data = json.load(sys.stdin)
for r in data.get('results', []):
print(r.get('title',''))
print(r.get('url',''))
print(r.get('content','')[:200])
print()
"
```
每条结果返回：`title`、`url`、`content`（摘要）、`engine`、`parsed_url`、`img_src`、`thumbnail`、`author`、`published_date`
## 方法二：通过 `requests` 使用 Python API
直接从 Python 使用 `requests` 库调用 SearXNG REST API：
```python
import os, requests, urllib.parse
base_url = os.environ.get("SEARXNG_URL", "")
if not base_url:
raise RuntimeError("SEARXNG_URL is not set")
query = "fastapi deployment guide"
params = {
"q": query,
"format": "json",
"limit": 5,
"engines": "google,bing",
}
resp = requests.get(f"{base_url}/search", params=params, timeout=10)
resp.raise_for_status()
data = resp.json()
for r in data.get("results", []):
print(r["title"])
print(r["url"])
print(r.get("content", "")[:200])
print()
```
## 方法三：searxng-data Python 包
如需更结构化的访问，安装 `searxng-data` 包：
```bash
pip install searxng-data
```
```python
from searxng_data import engines
# 列出可用引擎
print(engines.list_engines())
```
注意：此包仅提供引擎元数据，不提供搜索 API 本身。
## 自托管 SearXNG
运行你自己的 SearXNG 实例：
```bash
# 使用 Docker
docker run -d -p 8888:8080 \
-v $(pwd)/searxng:/etc/searxng \
searxng/searxng:latest
# 然后设置
SEARXNG_URL=http://localhost:8888
```
或通过 pip 安装：
```bash
pip install searxng
# 编辑 /etc/searxng/settings.yml
searxng-run
```
公共 SearXNG 实例可在以下地址找到：
- `https://searxng.example.com`（替换为任意公共实例）
## 工作流：先搜索后提取
SearXNG 返回标题、URL 和摘要——而非完整页面内容。要获取完整页面内容，先搜索，然后使用 `web_extract`、浏览器工具或 `curl` 提取最相关的 URL。
```bash
# 搜索相关页面
curl -s "${SEARXNG_URL}/search?q=fastapi+deployment&format=json&limit=3"
# 输出：包含标题和 URL 的结果列表
# 然后使用 web_extract 提取最佳 URL
```
## 限制
- **实例可用性**：如果 SearXNG 实例宕机或不可访问，搜索将失败。始终检查 `SEARXNG_URL` 已设置且实例可访问。
- **无内容提取**：SearXNG 返回摘要，而非完整页面内容。使用 `web_extract`、浏览器工具或 `curl` 获取完整文章。
- **速率限制**：部分公共实例会限制请求。自托管可避免此问题。
- **引擎覆盖范围**：可用引擎取决于 SearXNG 实例的配置，部分引擎可能被禁用。
- **结果时效性**：元搜索聚合外部引擎——结果时效性取决于这些引擎。
## 故障排查
| 问题 | 可能原因 | 处理方式 |
|---------|--------------|------------|
| `SEARXNG_URL` 未设置 | 未配置实例 | 使用公共 SearXNG 实例或自行搭建 |
| 连接被拒绝 | 实例未运行或 URL 错误 | 检查 URL 是否正确且实例正在运行 |
| 结果为空 | 实例屏蔽了该查询 | 尝试其他实例或自托管 |
| 响应缓慢 | 公共实例负载过高 | 自托管或使用负载较低的公共实例 |
| 不支持 `json` 格式 | SearXNG 版本过旧 | 尝试 `format=rss` 或升级 SearXNG |
## 注意事项
- **务必设置 `SEARXNG_URL`**：没有它，此 skill 无法运行。
- **对查询进行 URL 编码**：curl 中的空格和特殊字符必须进行 URL 编码，或在 Python 中使用 `urllib.parse.quote()`。
- **使用 `format=json`**：默认格式可能不是机器可读的。始终明确请求 JSON。
- **设置超时**：始终使用 `--max-time` 或 `timeout=`，以避免在实例不可访问时挂起。
- **自托管最佳**：公共实例可能宕机、限速或屏蔽请求。自托管实例更可靠。
## 实例发现
如果 `SEARXNG_URL` 未设置且用户询问 SearXNG，帮助他们：
1. 找到公共 SearXNG 实例（搜索"public searxng instance"）
2. 使用 Docker 或 pip 搭建自己的实例
公共实例列表：https://searxng.org/