系统发育分析 / Phylogenetics

⚠️ 本 Skill 绑定公网 HTTPS 网关，slug 与网关端点一致，勿改动。 This skill is bound to a public HTTPS gateway; the slug matches the gateway endpoint and must not be changed.

概述 / Overview

中文本 Skill 提供一个真实可调用的按次计费生信服务：k-mer 距离矩阵（Jukes-Cantor 校正）+ UPGMA / Neighbor-Joining 建树，输出 Newick 与聚类合并记录。它不是提示词模板，而是对接远程业务接口的客户端说明——计算全部在服务端完成，结果可复现、可验收。

English This skill wraps a real pay-per-call bioinformatics service: k-mer distance matrix (Jukes-Cantor corrected) + UPGMA / Neighbor-Joining tree building, outputting Newick and clustering merge records. It is not a prompt template — it documents how to call a remote business endpoint. All computation happens server-side, so results are reproducible and auditable.

服务配置 / Service configuration

| 项 / Item | 值 / Value | |---|---| | 服务地址 / Service URL | https://47-101-40-133.sslip.io/v1/pay/skills/bio-phylogenetics-integrated/invoke | | 请求方式 / Method | POST，Content-Type: application/json | | 协议 / Protocol | A2M 智能收协议（HTTP 402） | | 单价 / Unit price | ¥0.99 / 次（pay-per-call，按次独立计费） | | 计费资源 / Resource | bio-phylogenetics-integrated（与网关执行器、支付宝登记 serviceId 一致） |

服务地址、单价与支付宝后台登记值必须逐字符一致，否则验付失败。

依赖技能 / Dependencies

中文：买方侧的 402 支付由支付宝官方技能处理，使用前请先安装：

alipay-pay-for-402-service —— 解析 402 账单、发起支付、携凭证重试、发送履约回执
alipay-authenticate-wallet —— 钱包未授权时完成授权
alipay-payment-feedback —— 支付流程异常时的兜底反馈

English: The buyer side of the 402 flow is handled by Alipay's official skills. Install them first:

alipay-pay-for-402-service — parse the 402 bill, pay, retry with proof, send fulfillment receipt
alipay-authenticate-wallet — authorize the wallet when needed
alipay-payment-feedback — fallback feedback when the payment flow fails

前置检查 / Prerequisites

# 1) 检查买方支付 CLI 是否已安装（优先复用，不要重复安装）
which alipay-bot

# 2) 未安装时，先校验完整性再安装固定版本
npm view @alipay/agent-payment@1.0.0 dist.integrity
npm install @alipay/agent-payment@1.0.0 && npx @alipay/agent-payment@1.0.0 install-cli

# 3) 检查钱包授权状态
alipay-bot -- check-wallet

授权返回 access_url 非空时，调用 alipay-authenticate-wallet 完成授权后再继续。

核心付费流程 / Payment flow

中文

直接发起业务请求。服务端因未付款返回 HTTP 402 与 Payment-Needed 头。
把 Payment-Needed 的原始文本完整保存到文件（不要解码、不要改动任何字符）。
调用 alipay-bot -- 402-buyer-pay -f '<402_needed_<timestamp>.txt>' 发起支付，把 CLI 输出原样透传给用户，等待用户完成支付。
用户确认已支付后，调用 alipay-bot 402-query-payment-status -t '<tradeNo>' -r 'https://47-101-40-133.sslip.io/v1/pay/skills/bio-phylogenetics-integrated/invoke' -m POST -d '<原请求体>' 由 CLI 查询支付结果并重新请求资源。
把 resourceResponse.body 原样交付给用户。
调用 alipay-bot -- 402-buyer-fulfillment-ack -t '<tradeNo>' 发送履约回执。

English

Call the endpoint directly. The server replies HTTP 402 with a Payment-Needed header because the call is unpaid.
Save the Payment-Needed value verbatim to a file — do not decode it, do not alter a single character.
Run alipay-bot -- 402-buyer-pay -f '<402_needed_<timestamp>.txt>', relay the CLI output to the user unchanged, and wait for payment.
After the user confirms payment, run alipay-bot 402-query-payment-status -t '<tradeNo>' -r 'https://47-101-40-133.sslip.io/v1/pay/skills/bio-phylogenetics-integrated/invoke' -m POST -d '<original-body>' — the CLI verifies the payment and re-requests the resource.
Deliver resourceResponse.body to the user unchanged.
Run alipay-bot -- 402-buyer-fulfillment-ack -t '<tradeNo>' to send the fulfillment receipt.

输入 / Input

请求体示例：

{
  "sequences": [
    {
      "id": "A",
      "seq": "ATGGCCATTGTAATGGGCCGCTGAAAGGGTGCCCGA"
    },
    {
      "id": "B",
      "seq": "ATGGCCATTGTAATGGGCCGCTGAAAGGGTGCCCGT"
    },
    {
      "id": "C",
      "seq": "ATGGCCATTGTAATGGGCTGCAGAAAGGGTGCCCGA"
    }
  ],
  "method": "nj"
}

| 字段 / Field | 类型 / Type | 必填 / Required | 说明 / Description | |---|---|---|---| | sequences | [{id, seq}, ...] | 是 | 各分类单元的序列 | | method | string | 否 | upgma 或 nj（默认 nj） |

请求体占位模板：

{
  "sequences": [
    {
      "id": "<taxon>",
      "seq": "<序列>"
    }
  ],
  "method": "nj"
}

输出 / Output

交付成功后响应带 Payment-Validation 头；content 字段为结果。字段：method、distanceMatrix、newick、root、merges。

示例 content：

{ "ok": true, "method": "nj", "distanceMatrix": [[0,0.02,0.03]], "newick": "(B:0.01,A:0.01):0.0,C:0.02;", "root": "C", "merges": [] }

| 字段 / Field | 含义 / Meaning | |---|---| | method | 建树方法 | | distanceMatrix | 距离矩阵 | | newick | Newick 树文本 | | root | 根节点 | | merges | 聚类合并记录 |

错误处理 / Error handling

| 情况 / Case | 表现 / Behavior | 处理 / Action | |---|---|---| | 未付款 / unpaid | 402 + Payment-Needed | 按上述流程付款 / follow the payment flow | | 400 请求体非法 | code: bad_request | 修正请求体后重试 / fix the body and retry | | 500 EXECUTION_FAILED | 已扣款但执行失败 | 用原 out_trade_no 查单，不要重复付款 / query the order by out_trade_no, do not pay again | | 502 FULFILLMENT_CONFIRM_FAILED | 资源已生成但履约确认失败 | 用同一份 Payment-Proof 重试原请求 / retry the same request with the same Payment-Proof | | 404 skill_not_found | 服务地址写错 | 核对服务地址 / verify the service URL |

异常时先查单：GET https://47-101-40-133.sslip.io/v1/pay/orders/<out_trade_no>。

关键约束 / Constraints

中文

不重新下单：付款后必须复用原订单与原请求参数，重新下单会重复扣费。
不篡改账单：Payment-Needed 必须原样保存与传递，任何字符改动都会导致支付失败。
不伪造凭证：不得构造或复用他人的 Payment-Proof，也不得凭历史支付记录伪造成功。
不自行实现支付：支付与签名全部由官方 alipay-bot 完成，本包不含任何密钥。

English

Never re-order: after payment, reuse the original order and the original request parameters. Re-ordering causes double charging.
Never alter the bill: Payment-Needed must be saved and forwarded verbatim; any change breaks payment.
Never forge proofs: do not construct or reuse someone else's Payment-Proof, and do not fake success from past payment records.
Never implement payment yourself: all payment and signing is done by the official alipay-bot. No keys are stored in this package.

限制 / Limitations

中文：按次计费，不提供订阅、退款、对账与发票；单次请求体上限 1MB；金额单位为元、币种固定 CNY。 English: Pay-per-call only — no subscriptions, refunds, reconciliation, or invoicing. Request body is capped at 1MB. Amounts are CNY only.