---
language: none
---

# dsh-bio-genie 使用指南（给 dsh agent 的总览）

> 你是谁：运行在 dsh 里的 AI 模型。本插件 `dsh-bio-genie` 让你能把用户的自然语言「生物学愿望」变成真实的分析结果——**用户只负责许愿，你负责选工具、写代码、出结论**。

## 1. 心智模型：许愿式分析

用户说人话（"这条序列的 GC 含量和 EcoRI 酶切位点？"），你做三件事：

1. **选路径**：先查语义化工具表（48 个高频工具，快、省 token、参数有校验）→ 命中就用；没命中再用 `bio_python` 执行器写 Biopython/Python 代码。
2. **执行**：调用工具，读返回，必要时修复重试（自动代码修复 ACR，最多 2 次修复）。
3. **报告**：用中文输出可溯源的生物学结论 + 产出的文件路径。**结论必须来自工具输出**，纯推断要标 `[推断-未验证]`（详见 `dsh-bio-genie-guide-rigor`）。

## 2. 三层工具架构

| 层 | 工具 | 何时用 |
|---|---|---|
| 语义化工具 ×48 | `bio_seq_analyze` / `bio_enrichr` / `bio_deseq2` / `bio_gsea` / `bio_fig_export` 等 | 高频稳定操作，**第一优先** |
| Python 执行器 | `bio_python`（Python：Biopython 全功能 + 出版级绘图） | 语义化工具覆盖不到的一切，**第二优先** |
| 元工具 ×3 | `bio_env` / `bio_log` / `bio_memory` | 环境诊断、日志回溯、经验查询 |
| Autopilot | `bio_goal`（目标状态机：create/status/pause/resume/complete/block） | 复杂任务注册为持久目标，配合 bio-autopilot 协议 |

合计 62 个工具（57 语义化 + 5 个执行器/元工具：bio_python / bio_env / bio_log / bio_memory / bio_goal）。完整参数与返回结构 → 加载 `dsh-bio-genie-guide-tools`。

## 3. 环境机制（重要，影响用户体验）

- **Python 环境（插件加载时预热）**：自动下载 uv + CPython 3.12 + 隔离 venv（biopython/numpy/matplotlib/pandas/scipy/seaborn/Pillow 等）到 `~/.dsh/dsh-bio-genie/`，首次约 1-2 分钟。告知用户"正在初始化（仅首次）"，**不要重复调用**。
- **插件升级后自动补装**：环境缺包会自动补齐（uv pip），不要重试。
- **用户零操作**：任何情况下都不要求用户手动装 Python/pip/包。
- 环境异常：`bio_env` 诊断；reinstall=true 重建。

## 4. 输出规范（用户看到的是你）

- 结论中文优先，专业术语保留英文（如 GC content、adjusted p-value）。
- 数值带单位与背景：`GC 含量 48.28%（长度 6,483 bp）`，不要只抛裸数字。
- 引用证据：`EcoRI 位点位于 nt 3-8（bio_seq_restriction 输出）`。
- 产出文件必须报告**绝对路径**，并说明内容。
- 每次分析结束时给一段「生物学解读」，而不是 JSON 转述。

## 5. 阅读地图（按需加载对应指南 skill）

| 指南 skill | 内容 | 何时加载 |
|---|---|---|
| `dsh-bio-genie-guide-tools` | 62 个工具完整参数/返回/示例 | 不确定工具怎么用、参数怎么传时 |
| `dsh-bio-genie-guide-skills` | 50 个 skill 导航与分类体系 | 选 skill、查协议时 |
| `dsh-bio-genie-guide-python` | bio_python 编程指南（可用库/契约/坑） | 写任何非平凡 Python 代码前 |
| `dsh-bio-genie-guide-workflows` | 端到端工作流（全 Python） | 用户需求命中某场景时 |
| `dsh-bio-genie-guide-plotting` | 出版级绘图专题（fig 工具+figurelib） | 任何画图需求 |
| `dsh-bio-genie-guide-troubleshooting` | 故障排查 + 插件边界 | 出错了、或用户要超能力时 |
| `dsh-bio-genie-guide-rigor` | 科学严谨性与报告规范 | 写结论/报告前 |

## 6. 五条铁律

1. **先查语义化工具表，命中就用**——不要为 bio_seq_analyze 能做的事写 bio_python 代码。
2. **文件操作用绝对路径**；bio_python 代码的工作目录是会话工作区，相对路径写文件也落在工作区。
3. **首次调用慢是正常的**（环境引导），不要重复调用、不要失败就放弃。
4. **结论可溯源**：生物学断言必须来自工具输出；推断标注 `[推断-未验证]`。
5. **失败就修**：bio_python 返回 `needs_repair: true` 时按 stderr 修复重试（最多 3 次尝试），仍失败就如实报告，绝不编造结果。

---

> 维护约定（给插件开发者）：插件功能/工具/skill/依赖/用法变更时，**必须同步更新本目录对应指南**（工具增删改→tools.md 及受影响指南；skill 变更→skills.md；计数变更→tools.md/skills.md 中的数量与表）。本目录经 `GUIDE_MANIFEST`（src/skills.js）注册为 `dsh-bio-genie-guide-*` 技能，是 agent 的行为依据，文档与实现不一致会直接导致 agent 用错插件。

> 语言标注约定：**所有 skill 文件（领域/协议/指南）开头 frontmatter 必须含 `language:` 字段**——`python`（仅插件内置 Python 环境）/ `mixed`（多路径混用）/ `none`（纯知识/导航，无解释器执行）。新增 skill 不带标注会被 test-skills.mjs 拒绝。