OpenScience Dispatcher

把 314 个科研子技能当作可检索的能力库（312 个上游按需下载 + 2 个本包自研随包），把 7 个 MCP 连接器当作按需安装的外部工具，由本调度器统一路由、加载、执行。

本文件所在目录记作 $OSD（即本包根目录）。安装到 Agent 平台后通常位于 <用户目录>/.workbuddy/skills/openscience-dispatcher。
所有命令都在 $OSD 内执行；不要把 $OSD/skills/**/SKILL.md 当作顶层技能去调用——它们只能经调度器访问。

> ⚠️ 312 个上游子技能不随包分发。 本包为投稿 skillhub / clawhub 做过瘦身：包内只有索引
> （registry.json）与文件清单（manifest.json），没有子技能正文——整包解压 1.0 MB，而带全部
> 子技能要 21 MB，远超投稿平台的上传上限。用户真正要用到某个子技能时：
> dispatch.py plan <名称> 预估体积 → 问用户要不要下载 → 同意后 dispatch.py fetch <名称> --yes，
> 只拉这一次任务需要的文件（单个子技能通常几万字节）。
> 本包自研的 2 个技能（unified-research-finder、meta-analysis-figures）随包分发、开箱即用。
> 完整规则见第五节「按需下载协议」。

一、四层调度模型

用户任务
   │
   ├─ 0. workflow orchestration  dispatch.py workflow show sci-paper  → 拿到阶段、门控与产物规范
   ├─ 1. capability routing      dispatch.py query "<关键词>"          → 命中哪几个子技能
   ├─ 2. skill loading           dispatch.py load <name>               → 拿到 SKILL.md 正文 + 基础目录 + 资源清单
   └─ 3. tool provisioning       dispatch.py mcp install <id>          → 需要外部系统时按需装 MCP

第 0 层是可选的编排层。 当任务是"从零写一篇论文"这类跨越多个子技能的长流程时，先取工作流定义，
它规定了下游阶段顺序、每阶段的准入与门控、产物文件，以及必须遵守的铁律。单点任务（"帮我把这个蛋白质结构预测一下"）
不需要第 0 层，直接从第 1 层检索入手。

子技能是能力（知道怎么做科研），MCP 是工具（能碰到外部系统）。两者职责不重叠：
子技能告诉你"用什么方法、跑什么代码、如何解读结果"；MCP 让你"真的去 GitHub / 云存储 / GPU 集群上动手"。

二、端到端工作流

工作流定义放在 $OSD/workflows/*.md，由 dispatch.py workflow 读取（文件名即 id，无需额外登记）。

已有工作流

sci-paper 的完整定义见 workflows/sci-paper.md，执行前必须完整读一遍。它规定了：

• 六条铁律：绝不编造文献、绝不编造数据、先查证再动笔、全程留痕、每步说人话、不确定就问
• 三条路线：系统综述 / Meta 分析（默认推荐）、叙述性综述、公开数据库二次分析
• 十个阶段（Stage 0–9）：Intake 信息采集 → 可行性查证 → 检索 → PRISMA 筛选 → 数据提取 → 统计 → 图表 → 英文稿 → 反造假审计 → 投稿准备
• 每阶段的准入条件、要调用的子技能、产物文件、门控条件
• 分轮提问设计（一轮不超过 4 个问题）与"信息已足够"的判据
• 产物目录规范与中断恢复方式
• 每阶段结束的固定四段话术：做了什么 / 为什么 / 说明什么 / 需要你确认什么

这条工作流的价值不在于"生成文本"，而在于先问清楚、再查证、最后才动笔。
缺少必要信息时必须停下来问用户（一轮 ≤4 个问题）；信息足够（PICO 明确 + 路线确定 + 主要结局明确）
之后才开始检索。阶段之间可以有简短对话确认方向，但不许跳过门控。

三、检索引擎

统一入口，零第三方依赖，需 Python 3.8+。

调用方式（任选其一）：

> 若 python 不在 PATH，可用 Windows 的 py -3，或任何绝对路径的解释器。

query 的排序依据：名称精确匹配 > 名称包含 > 标签 > 描述 > 功能摘要 > 分类。
匹配按词边界进行（meta 不会命中 metabolomics），而非裸子串。
中文查询会先做术语展开（如「分子对接 打分」→ molecular docking + scoring）再打分，因为上游技能名与描述是英文优先的。
展开出的英文短语若整体命中某技能的元数据，会获得远高于其组成单词的权重——这保证「meta 分析」命中
literature-review 这类真正相关的技能，而不会被名字里恰好含 -analysis 的无关技能挤掉。

中文标签按命中方式分两档：技能自己声明的中文标签（如自研技能 unified-research-finder 的「找文献」）
命中时权重最高；仅作为某个更长标签的子串命中时权重很低。中文没有词边界，若不区分，
查询「我要找文献」里的「文献」会误命中 literature-review 的别名标签「文献综述」，把用户的学术搜索技能挤到第二。

⚠️ 上游技能多为英文元数据、且常常没有标签，中文查询因此天然搜不到它们（「科研绘图」匹配不了
publication-ready figures）。本包用 tools/aliases.json 在构建期为这些技能补上中文触发词
（如 scientific-visualization ← 科研绘图 / 绘图 / 图表；statistical-analysis ← 样本量 / 敏感性分析；
venue-templates ← 投稿），由 rebuild.py 合并进 registry.json——这样修复是持久的，
不会因为下一次重建覆盖上游目录而丢失。

⚠️ 检索只索引技能元数据（名称 / 描述 / 功能 / 标签 / 分类），不索引 references/ 与 assets/ 正文。
因此只写在正文里的概念（如 publication bias）可能查不到——这是设计边界而非故障：
此时用 category 浏览该领域分类，或直接 load 语义相邻的技能（循证写作 → clinical-decision-support、statistical-analysis）。
若某个上游技能对中文查询反复搜不到，最干净的修法是往 tools/aliases.json 给它加一条中文别名，而不是改上游文件。

query 无命中时，先用 category 浏览，或换用更贴近上游命名的英文术语。

四、路由表（16 分类 / 314 子技能：上游 312 + 本包自研 2）

> 自研子技能（origin: local，位于 local-skills/）在表中以 (自研) 标出——它们随包分发。
> 其余 312 个上游子技能按需下载：下表是它们的分类与规模，不代表它们已经在本地。

五、执行协议

1. 判流程：任务是长流程（写论文、完整分析管线）还是单点问题？长流程先 workflow show <id> 取编排定义。
2. 提关键词：从任务里抽出领域词 + 动作词（如 single-cell + integration、分子对接 + 打分）。
3. 检索：跑 query。命中不理想就换英文术语或加 --category。
4. 选 1–3 个：只挑真正要用的。子技能之间常有明确分工（例如 anndata 管数据结构、scanpy 管分析流程）。
5. 载入：load <name>。返回的 Base directory 就是该子技能的根，其 scripts/、references/、assets/ 都在那里。
   若返回「尚未下载到本地」（退出码 4），说明该子技能不在包内——按下方「按需下载协议」先问用户再 fetch。
6. 执行：严格按子技能正文的步骤走；需要跑脚本时，在该 Base directory 内用 Bash 运行。
   子技能目录视为只读——不要往里写文件；产物写到用户工作目录或临时目录。
7. 补外部工具：任务需要触达外部系统（GitHub、云存储、托管 GPU、ELN）时，才走第六节的 MCP 流程。
8. 自检（可选）：交付前沿用 research 类的 peer-review / scholar-evaluation 做一轮质量复核。

按需下载协议（先问，再下）

skills/ 下的 312 个上游子技能不在包里。包内只有 registry.json（有什么）与 manifest.json
（每个子技能由哪些文件组成、各多大、去哪里取）。用到时才下载，且只下载这一次任务需要的文件。

dispatch.py status                            # 我现在有什么
dispatch.py plan pubmed-database              # ← 先预览：几个文件、多大（离线，不联网、不写盘）
dispatch.py fetch pubmed-database             # 不加 --yes：只打印计划，一个字节都不写
dispatch.py fetch pubmed-database --yes       # 用户同意之后才执行
dispatch.py plan --workflow sci-paper         # 整条工作流需要哪些、共多大
dispatch.py fetch --workflow sci-paper --yes  # 一次拉齐该工作流 requires 里列的全部子技能
dispatch.py plan --all                        # 全量 312 个技能要多大（离线预估）
dispatch.py fetch --all --yes                 # 需要离线全量使用时一次拉完（约 19.6 MB）

六条规则：

1. 绝不静默下载。 fetch 不加 --yes 永远只打印计划。你要先把「名称 + 文件数 + 体积」告诉用户，
   得到明确同意后再加 --yes 重跑。
2. 只下这次任务需要的。 单点任务下 1–3 个；长流程用 fetch --workflow <id>。
   没有理由为了一次检索把 19.6 MB 全拉下来。
3. 退出码 4 = 需要下载，不是「技能不存在」。 load 遇到未下载的子技能会返回 4 并打印下载指引；
   此时不要凭名字猜它的内容，也不要假装读过了。
4. 源只有一个：https://gitee.com/georgechou17/open-science-dispatcher 的 raw 端点，逐文件直连，
   不需要 git、不需要令牌。要换 fork / 镜像用 OSD_SOURCE_HOME 与 OSD_SOURCE_REF 覆盖。
5. 可续传、可重复。 每个文件按 manifest.json 里的字节数校验；已下好且大小相符的自动跳过，
   中断后重跑同一条命令即可。大小不符会被当作失败丢弃，不会留下半个假技能。
6. 离线环境先备齐。 若用户网络受限或要求断网可用，先 fetch --all --yes 一次性备齐
   （312 个技能 / 1615 个文件）。

委派：当流程够长（多子技能串联，或需要读大量数据库）时，把子技能执行丢给子代理，只让主上下文接收结论。这样能避免把每个子技能的全文都堆进主上下文。

六、MCP 按需安装协议

原则：用户不需要，就不装。 MCP 只在任务确实要触达外部系统时才引入。

dispatch.py mcp config                 # 先确认目标配置文件在哪
dispatch.py mcp list                   # 看有哪些、各自能读能写什么、有什么前置条件
dispatch.py mcp install <id>           # 生成方案：网络判定 + 镜像选择 + 配置片段
dispatch.py mcp install <id> --write   # 真正写入配置文件（自动备份原文件）

配置文件位置：默认 <用户目录>/.workbuddy/mcp.json。
若平台不同或想放别处，用环境变量 OSD_MCP_CONFIG 覆盖，或调用时加 --config <路径>：

# Windows (cmd)
set OSD_MCP_CONFIG=D:\ai\my-agent\mcp.json

# Windows (PowerShell) / macOS / Linux
$env:OSD_MCP_CONFIG = "D:\ai\my-agent\mcp.json"     # PowerShell
export OSD_MCP_CONFIG="$HOME/my-agent/mcp.json"     # bash

网络分流（按 IP 自动判定）

mcp install / net 会自动判定所在区域并选择下载源：

判定失败时保守默认中国大陆镜像。可用环境变量 OPENSCIENCE_REGION=CN|INTL 强制覆盖。

七个连接器

> 为什么选 meteor0620/spss-mcp 而不是 Exekiel179/SPSS-MCP：前者用 pyreadstat 做 .sav 即时读写、
> 单个持久 SPSS 引擎跨调用保持数据集、工具面收敛（7 个），且仍在维护；后者的 configure-claude
> 会改写 Claude Code 专属的 ~/.claude.json，不适配通用 mcpServers 模型，且已久未更新。
> 两者都只支持 Windows + 已装 SPSS，故一律登记为 manual_review，不会自动克隆或安装。
> spss 的配置命令含 <安装目录> 占位符——本工具检测到占位符时会拒绝写入，避免登记一个永远连不上的服务器。

注意：远程连接器只需登记 URL，不涉及下载，因此网络分流对它们不生效；网络分流只在本地进程类（如 Dropbox 的 git/uv 安装）和用户自定义 MCP 上起作用。

安装后的两步（缺一不可）

1. 写入 mcpServers 后，不会自动激活——必须到平台的连接器管理页对该服务器点「信任」/启用。
2. 点信任前，先核对它暴露的工具清单与 OAuth 授权范围。

七、安全边界

• 写操作默认关闭。上游 catalog 中 writes_enabled_by_catalog 全为 false；任何写操作（创建/删除 GPU、改 Issue、动 S3、改文件）都必须先向用户说明再执行。
• 不代跑未审代码。manual_review 类连接器（Benchling / Dropbox / SPSS）本包不会自动克隆或执行上游仓库——Dropbox 必须固定并审阅 commit 后手工登记；SPSS 需用户自装 SPSS 并替换配置里的真实路径。
• 不猜凭据、不存凭据。Benchling 的租户地址需用户提供；OAuth 走浏览器回环，本包不接触 token 明文。
• 不预授权。每次 MCP 工具调用都过一次权限边界；不要为了省事批量批准。
• 计费资源需显式确认。GPU 类连接器在批准前先确认计费上限。
• skills/ 子技能目录只读（重建会覆盖），要修上游内容走 tools/patches/；local-skills/ 可直接编辑。整体以 Apache-2.0 分发，见 LICENSE.md、NOTICE.md、ATTRIBUTION.md 与 THIRD-PARTY-NOTICES.md。
• 注意：子技能 frontmatter 里的 license: 字段描述的是它所讲授的第三方库的许可（如 etetoolkit → GPL-3.0 指 ETE 工具包），不是该技能或本仓库的许可声明；本包未内嵌任何 GPL/LGPL/CeCILL 源码。

八、目录结构

openscience-dispatcher/
├── SKILL.md            ← 本文件（调度协议）
├── dispatch.py         ← 检索引擎（list / category / query / load / status / plan / fetch / mcp / net / workflow）
├── dispatch.cmd        ← Windows 启动器（自动探测 Python；仅完整包——平台拒收 .cmd，投稿包不含）
├── registry.json       ← 314 条子技能索引（名称/分类/描述/功能/标签/路径/origin）
├── manifest.json       ← 312 个上游子技能的文件清单 + 字节数 + Gitee 源（按需下载的依据）
├── workflows/          ← 端到端工作流定义（文件名即 id，无需登记）
│   └── sci-paper.md    ← 从零写 SCI 论文：10 阶段 + 门控 + 铁律 + 产物规范
├── skills/             ← 312 个**上游**子技能，按 16 分类分层（每次重建覆盖，勿手改）
│   │                     投稿包**不含**此目录，由 dispatch.py fetch 从 Gitee 按需下载回来
│   └── <category>/<name>/{SKILL.md, scripts/, references/, assets/}
├── local-skills/       ← 2 个**本包自研**子技能（手动维护，重建不覆盖）
│   ├── research/unified-research-finder/    ← 学术搜索（PubMed / Google 学术 / 镜像 / 影响因子）
│   └── visualization/meta-analysis-figures/ ← 森林图 / 漏斗图 / PRISMA 2020 / 偏倚风险红绿灯
├── mcp/
│   ├── catalog.json    ← 7 个连接器元数据（转录自上游 catalog.ts + 社区 SPSS）
│   └── INSTALL.md      ← 安装与网络分流详解
├── tools/              ← 维护脚本
│   ├── rebuild.py      ← 重建 skills/ 与 registry.json（含 local-skills 合并 + 别名覆盖）
│   ├── aliases.json    ← 给英文元数据的上游技能补中文触发词
│   ├── patches/        ← 对上游 bug 的最小修复（重建后自动回填）
│   ├── gen_readme.py   ← 生成 README.md
│   ├── make_demo_figures.py ← 重建 README 效果图到 docs/figures/
│   ├── package.py      ← 打包：投稿精简包（无 skills/，扁平根）与自用全量包
│   └── sources.py      ← 源仓库映射（上游 / 自研 / MCP）
├── docs/figures/       ← README 顶部效果图（森林图 / 漏斗图 / PRISMA / RoB 2 / KM；仅完整包——平台拒收图片，投稿包改用 Gitee 链接）
├── README.md
├── CHANGELOG.md
├── ATTRIBUTION.md           ← 署名与著作权人分布
├── THIRD-PARTY-NOTICES.md   ← 第三方作品清单（MIT / LPPL 等）
├── NOTICE.md
└── LICENSE.md               ← Apache-2.0（上游）

子技能保持上游 <分类>/<技能>/ 的原始分层，因此可以直接与上游做目录级 diff 或整目录替换。
两类目录的维护方式不同：skills/ 每次重建都会被上游覆盖，要修就改 tools/patches/；
local-skills/ 是自研内容，直接编辑即可。二者最终都汇入 registry.json，
并由 rebuild.py 汇总成 manifest.json（按需下载的文件清单）。

两种发行形态（tools/package.py 一次产出）：

Gitee 主仓库始终保留 skills/——它正是按需下载的源，删掉就没得下了。

九、失败与回退