# 科学计算 Agent Skills 数据库

这是一个面向建模、计算化学、密度泛函理论、分子动力学与科学可视化的 GitHub 开源 Agent Skills 初筛数据库。

仓库现已包含可运行的 `Scientific Skills Hub 0.1.0`：42 条主库完整目录缓存、SQLite FTS5 检索、中文状态卡、FastAPI/Jinja/HTMX 网页、HTTP/stdio MCP、GitHub 优先与本地回退、API Key、外部隔离候选和管理员 CLI。它只分发符合许可门禁的 Skill 内容，不安装或执行任何 Skill、求解器或科学任务。

当前公开基线为 `snapshots/2026-08-25-v6`。动态指标的抓取时间是 `2026-08-25T15:19:40Z`；后续引用 Star、安装量、维护状态或许可证时，应注明该日期并在正式发布前刷新。

## 运行 MCP 与网页

### 下载完整离线版本

```bash
git clone https://github.com/liangj5413-cyber/scientific-skills-hub.git
cd scientific-skills-hub
uv sync --extra dev
```

仓库包含42条主库 Skill 的许可缓存、索引和来源校验信息；不包含大型模型、科学求解器、二进制文件或外部数据集。

### 启动与验证

```bash
uv sync --extra dev
uv run scientific-skills-hub verify
uv run scientific-skills-hub doctor
uv run scientific-skills-hub serve
```

本机网页为 `http://127.0.0.1:8765/`，远程 MCP 路径为 `/mcp/`。本地 stdio MCP：

```bash
uv run scientific-skills-mcp
```

常见的 stdio MCP 客户端配置（将路径替换为你的绝对路径）：

```json
{
  "mcpServers": {
    "scientific-skills-hub": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/scientific-skills-hub",
        "run",
        "scientific-skills-mcp"
      ]
    }
  }
}
```

本地 stdio 模式无需 API Key。如果自行对外部署 HTTP MCP，请使用非默认密钥、权限为 `0600` 的环境文件和受信任 HTTPS；不要提交真实 `.env` 或跳过 TLS 校验。

公开网页和基础搜索允许匿名访问；HTTP MCP、正文、兼容性和内容包需要 Bearer API Key。管理员手工发放：

```bash
uv run scientific-skills-hub init-secrets
uv run scientific-skills-hub create-key --label xhs-user-001
```

完整架构和运维说明见 `docs/ARCHITECTURE.md` 与 `docs/OPERATIONS.md`。

## 运行时数据库

- `runtime/catalog.sqlite`：42 条正式 Skill、42 个固定提交版本、296 个缓存文件记录、结构化标签、依赖、风险、状态卡和 FTS5。
- `runtime/objects/sha256/`：289 个去重内容对象，共约 1.95 MB 正文。
- `runtime/bundles/*/manifest.json`：42 份内容包 Manifest。
- `runtime/service.sqlite`：本机可写状态，已加入 `.gitignore`，不会提交 API Key 摘要、反馈或限流计数。
- `runtime/quarantine/`：外部 `unreviewed_external` 候选，7 天后通过回收站清理。

统一的可用性状态优先级为：仅元数据、建议完整仓库、需要改路径、需要受限后端、可直接参考。当前42条的分布是26条可直接参考、10条建议完整仓库、3条需要改路径、3条需要受限后端。

## MCP 工具

第一版固定为8个工具，避免模型选择混乱：`search_skills`、`get_skill_card`、`check_compatibility`、`get_skill_content`、`get_skill_bundle`、`diff_skill_versions`、`doctor`、`report_skill_issue`。另提供目录/状态卡/正文 Resources、5个快速 Prompt 和 Skill ID/方法/领域/软件/阶段参数补全。

## 当前规模

- 发现并核验实际 `SKILL.md`：149 条
- 严格候选池：100 条
- 筛选主库：42 条
- 小红书首批候选：15 条
- 逐条人工复核的首批候选：15 条
- 相关生态项目附表：38 条
- GitHub/路径抓取错误：0 条

主库只收录能够在 GitHub 当前提交中定位到 `SKILL.md` 的 Agent Skills。普通科学软件、求解器、工作流平台、MCP Server 和科研 Agent 项目只放在生态附表，不计入上述 149、100、42 和 15 条 Skill 统计。

## 快速入口

- `snapshots/2026-08-25-v6/skills_catalog.xlsx`：适合人工筛选，包含主库、候选100、全部发现、小红书首发、方法、领域、软件、阶段和生态项目工作表。
- `snapshots/2026-08-25-v6/skills_catalog.sqlite`：规范化数据库，适合组合查询和后续网站/API 使用。
- `snapshots/2026-08-25-v6/INDEX.md`：按方法、领域、软件、流程阶段、评级和后端访问条件浏览。
- `snapshots/2026-08-25-v6/SHORTLIST_XIAOHONGSHU.md`：15 个首发候选、选题角度、人工复核结论、依赖和宣传边界。
- `snapshots/2026-08-25-v6/ECOSYSTEM.md`：普通软件、MCP Server、工作流与科研 Agent 生态附表。
- `snapshots/2026-08-25-v6/REVIEW_SUMMARY.md`：筛选数量、方法/领域覆盖及证据边界。
- `snapshots/2026-08-25-v6/MANIFEST.json`：输入来源、数量、抓取时间、所有交付文件 SHA-256 与字节数。

## 多维索引

### 方法

- 建模与结构生成
- 计算化学
- 密度泛函理论
- 分子动力学
- 可视化软件

### 应用领域

- 生物与药物
- 电池与电化学
- 催化与表界面
- 钙钛矿与半导体
- 金属与合金
- 聚合物与软物质
- 多孔材料
- 通用材料科学
- 通用科学计算

### 其他索引

- 软件或后端：VASP、Gaussian、ORCA、CP2K、GROMACS、LAMMPS、pymatgen、ASE、RDKit、PyMOL 等。
- 工作流阶段：体系准备、输入生成、执行编排、结果解析、分析与后处理、验证与质量控制、报告与可视化等。
- 热度与质量：A、B、观察、排除。
- 访问条件：完全开源本地工具、需商业许可证、需 API key/账户、未证明需要受限后端等。
- 来源谱系：仓库、提交 SHA、Skill 路径、内容 SHA-256、同名冲突和精确内容重复字段。

## 检索语义

- 电池查询识别 `NCM`、`NCA`、`三元正极`、`三元材料`、`层状氧化物`、`锂离子正极`、`lithium-ion cathode` 和 `layered oxide` 等同义表达。
- 查询明确指定 VASP、Quantum ESPRESSO、CP2K 等软件时，软件标签作为硬约束并获得精确匹配加权；例如指定 VASP 不会返回仅标记为 Quantum ESPRESSO 的条目。
- 通用材料科学的 VASP Skill 可在查询时继承到“电池与电化学”“催化与表界面”“金属与合金”，匹配原因会明确标为领域继承；数据库中的原始领域标签不会被改写。
- 结构化筛选条件仍优先于自然语言意图；查询文本与软件筛选互相冲突时返回零结果，不静默放宽到其他后端。

## SQLite 查询示例

列出主库中的 DFT Skills：

```sql
SELECT s.skill_name, s.repo, s.repo_stars, s.screening_tier, s.skill_github_url
FROM main_skills AS s
JOIN skill_methods AS m USING (skill_id)
WHERE m.value = '密度泛函理论'
ORDER BY CAST(s.repo_stars AS INTEGER) DESC;
```

查找电池领域、且需要关注商业许可证或外部账户的主库条目：

```sql
SELECT DISTINCT s.skill_name, s.backend_access, s.manual_dependency_note
FROM main_skills AS s
JOIN skill_domains AS d USING (skill_id)
WHERE d.value = '电池与电化学'
  AND (s.backend_access LIKE '%许可证%' OR s.backend_access LIKE '%API%');
```

查看小红书首发且已经人工复核的条目：

```sql
SELECT skill_name, primary_method, manual_review_status,
       manual_capability_level, xhs_recommendation
FROM xiaohongshu_shortlist
ORDER BY CAST(repo_stars AS INTEGER) DESC;
```

## 筛查口径

综合分由 Skill 结构完整度、证据与安全、仓库/安装热度、维护与许可证、科学主题相关性组成。A/B/观察并不是科学结果质量评级，而是公开证据下的首轮内容选题优先级：

- A：通常具有较强结构证据，并且仓库 Star 不低于 100 或单 Skill 安装量突出。
- B：达到功能完整度和维护门槛，且仓库 Star 不低于 20 或安装量有一定证据。
- 观察：技术主题相关，但热度、许可证、维护或结构证据不足。
- 排除：归档、抓取失败、科学主题相关性不足，或没有满足主库证据门槛。

Star 是仓库级指标，不能当作仓库内某个 Skill 的独立 Star。skills.sh 安装量是动态平台指标，空值不等于 0。自动分类只用于初筛；正式内容发布前，仍需阅读对应 `SKILL.md`、许可证和脚本，并对演示结果做人工验收。

## 小红书使用建议

首批内容优先使用 `SHORTLIST_XIAOHONGSHU.md` 中标记为“首发”的条目。每篇内容建议明确区分：

1. Skill 能指导、生成、检查或编排什么。
2. 实际依赖的开源软件、商业求解器、API、账户、GPU/HPC 或数据源。
3. 本次演示实际完成到了哪一步。
4. 哪些结论仍需要运行日志、收敛证据和专业人工复核。

不要把“存在 `SKILL.md`”“能生成输入”“仓库 Star 较高”写成“已经具备求解器”“可以免费运行商业软件”“结果一定正确”或“实现全自动科研”。

## 许可证

Scientific Skills Hub 平台源码采用 [MIT License](LICENSE)。缓存和索引中的第三方 Skill
仍分别受其上游许可证约束；具体来源、许可证和再分发状态以 Bundle Manifest 与
`THIRD_PARTY_NOTICES.md` 为准。平台的 MIT License 不会覆盖或改变第三方内容的许可证。

## 可复现刷新

刷新会创建新快照，脚本拒绝覆盖已有目录：

```bash
python3 scripts/build_catalog.py \
  --seed data/candidates.csv \
  --repo-overrides data/repository_overrides.csv \
  --ecosystem-seed data/ecosystem_projects.csv \
  --manual-reviews data/manual_reviews.csv \
  --output snapshots/YYYY-MM-DD-vN \
  --candidate-limit 100 \
  --main-limit 50 \
  --workers 12
```

运行本地检查：

```bash
python3 -m py_compile scripts/build_catalog.py
python3 -m unittest discover -s tests -v
python3 scripts/build_catalog.py --help
```

更新器只读取公开元数据与文本并生成本地派生文件；它不会安装或运行候选 Skill，也不会运行科学求解器或提交计算作业。

## 版本说明

- v1：首次结构化快照，语义标签过宽，仅保留追溯。
- v2：修复负面边界误分类，但主库阈值过严。
- v3–v4：校准评分、去重和领域/方法覆盖。
- v5：加入 38 个生态项目附表。
- v6：加入 15 条首发候选人工复核、依赖说明、来源谱系说明和发布优先级；当前推荐基线。