内容
# `nsip`
<picture>
<source media="(prefers-color-scheme: dark)" srcset=".github/social-preview-dark.svg">
<source media="(prefers-color-scheme: light)" srcset=".github/social-preview.svg">
<img alt="nsip - 羊遗传评估工具" src=".github/social-preview.svg" width="100%">
</picture>
<!-- 徽章 -->
[](https://github.com/zircote/nsip/actions/workflows/ci.yml)
[](https://crates.io/crates/nsip)
[](https://docs.rs/nsip)
[](https://www.rust-lang.org/)
[](https://github.com/zircote/nsip/blob/main/LICENSE)
[](https://github.com/rust-lang/rust-clippy)
[](https://github.com/EmbarkStudios/cargo-deny)
[](https://github.com/gitleaks/gitleaks)
[](https://docs.github.com/en/code-security/dependabot)
羊遗传评估命令行工具和 MCP 服务器 - 搜索动物，比较 EBV，计划交配，通过 NSIP 数据库对羊群进行排名。
<p align="center">
<img src=".github/readme-infographic.svg" alt="NSIP 架构概述" width="800">
</p>
> **试用：** 克隆 [zircote/nsip-example](https://github.com/zircote/nsip-example) 以获取一个现成的农场仓库，包含 MCP 服务器配置、示例工作流程和 AI 助手说明。
## 功能
- **类型安全的 API 客户端**，具有全面的错误处理
- **搜索功能**，按品种组、状态和其他条件搜索动物
- **详细的动物信息**，包括血统和后代
- **MCP（模型上下文协议）集成**，兼容 AI 助手
- **命令行工具**，具有多个子命令，方便交互
- **异步/等待支持**，使用 tokio 运行时
- **完整的文档**，所有公共 API 都有示例
## 安装
将以下内容添加到您的 `Cargo.toml`：
```toml
[dependencies]
nsip = "0.6"
```
或使用 cargo add：
```bash
cargo add nsip
```
## 快速入门
```rust,no_run
use nsip::{NsipClient, SearchCriteria};
#[tokio::main]
async fn main() -> Result<(), nsip::Error> {
// 创建一个新的客户端
let client = NsipClient::new();
// 列出可用的品种组
let breed_groups = client.breed_groups().await?;
println!("可用品种组：{}", breed_groups.len());
// 搜索动物
let criteria = SearchCriteria::new()
.with_status("CURRENT");
let results = client
.search_animals(0, 15, Some(640), None, None, Some(&criteria))
.await?;
println!("找到 {} 只动物", results.total_count);
// 获取特定动物的详细信息
let animal = client.animal_details("LPN_ID_HERE").await?;
println!("动物：{}", animal.lpn_id);
Ok(())
}
```
## 命令行工具用法
`nsip` 命令行工具提供了多个命令，用于与 NSIP 搜索 API 交互：
```bash
# 获取数据库最后更新日期
nsip date-updated
# 列出品种组
nsip breed-groups
# 列出动物状态
nsip statuses
# 获取品种的性状范围
nsip trait-ranges 640
# 搜索动物
nsip search --breed-id 640 --status CURRENT --page 0 --page-size 15
# 获取动物详细信息
nsip details <lpn-id>
# 获取动物血统
nsip lineage <lpn-id>
# 获取动物后代
nsip progeny <lpn-id>
# 获取完整档案（详细信息 + 血统 + 后代）
nsip profile <lpn-id>
# 比较两个或多个动物
nsip compare <lpn-id-1> <lpn-id-2>
# 生成 shell 补全
nsip completions bash
# 生成 man 页面
nsip man-pages --out-dir ./man/
# 启动 MCP 服务器模式
nsip mcp
```
## API 概述
### 客户端方法
| 方法 | 描述 |
|--------|-------------|
| `date_last_updated()` | 获取数据库最后更新日期 |
| `breed_groups()` | 列出可用的品种组 |
| `statuses()` | 列出可用的动物状态 |
| `trait_ranges(breed_id)` | 获取品种的性状范围 |
| `search_animals(page, page_size, breed_id, sorted_trait, reverse, criteria)` | 搜索动物 |
| `animal_details(search_string)` | 获取动物详细信息 |
| `lineage(lpn_id)` | 获取动物血统 |
| `progeny(lpn_id, page, page_size)` | 获取动物后代 |
| `search_by_lpn(lpn_id)` | 获取完整档案（并发） |
### 数据类型
| 类型 | 描述 |
|------|-------------|
| `NsipClient` | 主要 API 客户端 |
| `SearchCriteria` | 具有构建器模式的搜索参数 |
| `AnimalDetails` | 具有性状和联系信息的详细动物记录 |
| `AnimalProfile` | 组合详细信息 + 血统 + 后代 |
| `Breed` | 品种组中的单个品种 |
| `BreedGroup` | 具有嵌套品种的品种组 |
| `ContactInfo` | 拥有者/羊群联系信息 |
| `DateLastUpdated` | 来自最后更新日期端点的响应 |
| `Lineage` | 动物血统/祖先树 |
| `LineageAnimal` | 谷谱树中的单个节点 |
| `Progeny` | 动物的分页后代 |
| `ProgenyAnimal` | 单个后代记录 |
| `SearchResults` | 分页搜索结果 |
| `Trait` | 具有值和准确性的单个 EBV 性状 |
| `TraitRange` | 品种内性状的最小/最大范围 |
| `TraitRangeFilter` | 性状过滤器的最小/最大边界 |
| `Error` | 操作的错误类型 |
| `Result<T>` | `Result<T, Error>` 的类型别名 |
## MCP 集成
库中包含 MCP（模型上下文协议）支持，用于与 AI 助手集成：
```rust,ignore
use nsip::mcp::{serve_stdio, tool_sets::EnabledToolSets};
// 在 stdio 上启动 MCP 服务器（启用所有 13 个工具）
serve_stdio(EnabledToolSets::all()).await?;
```
MCP 协议在运行 `nsip mcp` 时暴露了以下 13 个工具：
- `search` - 搜索具有品种、性别、状态、日期范围和羊群过滤器的动物
- `details` - 获取动物的详细 EBV 数据、品种、联系信息和状态
- `lineage` - 获取血统/祖先树，包括父母和祖父母
- `progeny` - 获取动物的分页后代列表
- `profile` - 获取完整档案（详细信息 + 血统 + 后代），一步调用
- `breed_groups` - 列出所有品种组和个别品种
- `trait_ranges` - 获取特定品种的最小/最大 EBV 性状范围
- `compare` - 并排比较 2-5 只动物及其 EBV 性状
- `rank` - 按加权 EBV 性状对动物进行排名
- `inbreeding_check` - 计算同父同母配对的 Wright's Coefficient of Inbreeding
- `mating_recommendations` - 查找最佳配对，按性状互补性和 COI 排名
- `flock_summary` - 总结羊群的动物：数量、性别分布和平均 EBV
- `database_status` - 获取最后更新日期和可用的动物状态
## 开发
### 要求
- Rust 1.92+（2024 版）
- [cargo-deny](https://github.com/EmbarkStudios/cargo-deny) 用于供应链安全
### 设置
```bash
# 克隆仓库
git clone https://github.com/zircote/nsip.git
cd nsip
# 构建
cargo build
# 运行测试
cargo test
# 运行 linting
cargo clippy --all-targets --all-features
# 格式化代码
cargo fmt
# 检查供应链安全
cargo deny check
# 生成文档
cargo doc --open
```
### 项目结构
```text
crates/
├── lib.rs # 库入口
├── main.rs # 二进制入口
├── client.rs # NSIP 搜索 API 的 HTTP 客户端
├── models.rs # 数据模型（SearchCriteria、AnimalDetails 等）
├── format.rs # 人类可读的 ASCII 表格格式化
└── mcp/ # MCP 服务器（13 个工具、提示、资源）
tests/
├── integration_test.rs
└── cli_test.rs # 命令行工具集成测试
Cargo.toml # 项目清单
clippy.toml # Clippy 配置
rustfmt.toml # 格式化配置
deny.toml # cargo-deny 配置
CLAUDE.md # AI 助手说明
AGENTS.md # AI 编码代理说明
.editorconfig # 跨编辑器默认值
.devcontainer/ # Codespaces / 开发容器配置
.vscode/ # VS Code 设置和扩展
```
### 代码质量
该项目保持高代码质量标准：
- **Linting**：使用谨慎和苗圃 lint 的 clippy
- **格式化**：使用自定义配置的 rustfmt
- **测试**：单元测试、集成测试和基于属性的测试
- **文档**：所有公共 API 都有示例
- **供应链**：使用 cargo-deny 进行依赖审计
- **CI/CD**：GitHub Actions 用于自动化测试
### 运行检查
> **注意：** [`just check`](https://github.com/casey/just) 是 CI 流水线的规范本地等价物（fmt + clippy + test + doc + deny + coverage）。
> 运行 `just` 以列出所有可用的配方。下面原始的 `cargo` 命令是底层等价物。
```bash
# 运行所有检查
cargo fmt -- --check && \
cargo clippy --all-targets --all-features -- -D warnings && \
cargo test && \
cargo doc --no-deps && \
cargo deny check
# 使用 MIRI 运行，检测未定义行为
cargo +nightly miri test
```
## CI/CD 和部署
该模板包含生产就绪的工作流：
### 持续集成
- **CI** (`.github/workflows/ci.yml`) - 格式化、linting、测试、文档、供应链安全、MSRV 检查、覆盖率
- **安全审计** (`.github/workflows/security-audit.yml`) - 每天的 cargo-audit 扫描
- **机密扫描** (`.github/workflows/secrets-scan.yml`) - Gitleaks 机密扫描（手动；启用推送/PR 触发器以自动化）
- **容器扫描** (`.github/workflows/container-scan.yml`) - Trivy 镜像漏洞扫描
### 发布和部署
- **发布** (`.github/workflows/release.yml`) - 自动化 GitHub 发布，包含多平台二进制文件
- 构建目标：Linux（`x86_64`，ARM64），macOS（`x86_64`，ARM64），Windows（`x86_64`）
- 自动生成变更日志
- 二进制文件上传到发布
- **变更日志** (`.github/workflows/changelog.yml`) - 自动化 CHANGELOG.md 生成
- 使用 git-cliff 和约定提交
- 遵循 Keep a Changelog 格式
- 在版本标签上触发
- **Docker** (`.github/workflows/docker.yml`) - 多平台容器构建
- 平台：linux/amd64，linux/arm64
- 无依赖基础镜像，用于安全
- 发布到 GitHub 容器注册表（ghcr.io）
- 使用版本和“latest”标记
- **发布** (`.github/workflows/publish.yml`) - 自动化 crates.io 发布
- 完整的发布前验证
- 在版本标签上触发
- 受信任发布（OIDC）- 无注册令牌；发布的 crate 是字节验证和证明的
### 创建发布
1. 更新 `Cargo.toml` 中的版本
2. 创建并推送版本标签：
```bash
git tag -a v0.6.0 -m "Release v0.6.0"
git push origin v0.6.0
```
3. 工作流自动：
- 生成变更日志
- 为所有平台构建二进制文件
- 创建包含工件的 GitHub 发布
- 构建和推送 Docker 镜像
- 发布到 crates.io
### AI 编码代理
- **Copilot 设置** (`.github/workflows/copilot-setup-steps.yml`) - GitHub Copilot 编码代理环境
- **代理说明**：`AGENTS.md`，`.github/copilot-instructions.md`，`CLAUDE.md`
- **路径特定说明**：`.github/instructions/` 用于 Rust 代码和测试模式
- **可重用提示**：`.github/prompts/` 用于常见开发任务
### Docker 用法
拉取并运行容器：
```bash
# 拉取最新版本
docker pull ghcr.io/zircote/nsip:latest
# 运行特定版本
docker pull ghcr.io/zircote/nsip:v0.6.0
docker run --rm ghcr.io/zircote/nsip:v0.6.0 --version
```
## MSRV 策略
最低支持的 Rust 版本（MSRV）是 **1.92**。增加 MSRV 被视为次要破坏性变更。
## 贡献
参见 [CONTRIBUTING.md](CONTRIBUTING.md)，了解开发设置、PR 检查清单和编码标准。
请同时查看：
- [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) - 社区指南
- [SECURITY.md](SECURITY.md) - 漏洞报告
- [GOVERNANCE.md](GOVERNANCE.md) - 决策过程
## 许可证
该项目使用 MIT 许可证 - 有关详细信息，请参见 [LICENSE](https://github.com/zircote/nsip/blob/main/LICENSE) 文件。
## 致谢
- [The Rust Programming Language](https://www.rust-lang.org/)
- [Cargo](https://doc.rust-lang.org/cargo/)
- [clippy](https://github.com/rust-lang/rust-clippy)
