PeerBerry SDK 技能

TL;DR 快速入门

• 优先使用只读调用（get_profile、get_overview、get_loans）。
• 金额与利率一律使用 Decimal 类型，**禁止使用** float。
• 将 purchase_loan 视为真实资金操作，并通过 DRY_RUN 和 MAX_ORDERS 进行严格管控。
• 优先使用 SDK 提供的过滤参数（如 min_interest_rate、countries、loan_types），而非在本地进行二次过滤。
• 捕获具体的认证/资金类异常，再统一回退至 PeerberryException。

只读模式快速启动示例：

from peerberry_sdk import PeerberryClient

with PeerberryClient(email="YOUR_EMAIL", password="YOUR_PASSWORD") as api:
    profile = api.get_profile()
    overview = api.get_overview()
    loans = api.get_loans(quantity=5)

    print(profile.public_id)
    print(overview.data.get("availableMoney", overview.data.get("items", {}).get("availableMoney")))
    print([loan.loan_id for loan in loans])

安全投资模式快速启动示例：

from decimal import Decimal
from peerberry_sdk import PeerberryClient

DRY_RUN = True
MAX_ORDERS = 10
TICKET_SIZE = Decimal("10.00")

with PeerberryClient(email="YOUR_EMAIL", password="YOUR_PASSWORD") as api:
    loans = api.get_loans(quantity=50, min_interest_rate=Decimal("9.5"), exclude_invested_loans=True)

    for idx, loan in enumerate(loans):
        if idx >= MAX_ORDERS or loan.loan_id is None:
            break

        if DRY_RUN:
            print(f"[DRY_RUN] would invest {TICKET_SIZE} in loan {loan.loan_id}")
            continue

        api.purchase_loan(loan_id=loan.loan_id, amount=TICKET_SIZE)

核心目标

peerberry-sdk 是 PeerBerry 投资者 API 的 Python 封装库。在 P2P 借贷中，投资者将资金分散配置于多笔贷款（或贷款份额），随时间逐步收回本金与利息，并通过分散投资与持续监控来管理风险。PeerBerry 为投资者提供接入该类市场流程的渠道，而本 SDK 则将这些流程转化为可编程的 Python 接口，支持分析、自动化及运营控制。

适用范围 / 非目标

在范围内：

• 以通俗语言解释 PeerBerry 及 P2P 借贷基本概念。
• 基于 SDK 实际公开方法签名生成并调试 Python 代码。
• 构建只读监控脚本与受控的投资自动化逻辑。
• 协助处理筛选、分页、导出及认证/令牌生命周期等常见模式。

不在范围内：

• 提供金融建议、适配性建议，或承诺收益保障。
• 保证盈利性、安全性或未来表现。
• 虚构 SDK 中不存在的方法。

请求分类器

对用户输入请求进行分类，并按匹配类型响应：

1. educational：用户初次接触 P2P 或 PeerBerry。
   • 先讲解基础概念，再提供只读演示代码。
   • 加载参考文档：references/p2p-primer.md。
2. read_only_coding：用户需要组合投资组合或贷款数据分析。
   • 提供可直接运行的代码片段，并包含类型化模型处理逻辑。
   • 加载参考文档：references/api-quickref.md。
3. real_money_automation：用户需要实现买入/投资流程。
   • 必须加入 DRY_RUN、MAX_ORDERS、可用资金校验，并明确标注风险提示。
   • 加载参考文档：references/api-quickref.md 与 references/task-recipes.md。
4. debugging：用户遇到错误或异常。
   • 按优先级排查：认证问题 → 枚举型参数输入 → 过滤元数据 → 请求体结构。
   • 加载参考文档：references/api-quickref.md。

前提条件

• 在 PeerBerry 官方网站（https://peerberry.com/）注册并验证投资者账户。
• 使用有效的 PeerBerry 凭据（email 与 password）。
• 若账户启用了 TOTP 两步验证（2FA），需提供 tfa_secret 并安装 otp 扩展依赖。
• 所有购买操作均应视为真实资金操作，需谨慎对待。

关键概念与对象

主要入口点：

• PeerberryClient：用于身份认证、数据获取与购买操作的高层客户端。

核心模型对象：

• Profile、Overview、Loan、LoanPage、InvestmentPage、Transaction、AccountSummary、PurchaseOrder。

领域语义说明：

• loan：可在市场上投资的贷款标的（列表项）。
• investment：已持有的某笔贷款中的投资头寸。
• purchase order：已被接受的订单结果，含 order_id（非最终结算确认）。

安装与认证

安装命令：

pip install peerberry-sdk

启用两步验证（2FA）支持的安装命令：

pip install "peerberry-sdk[otp]"

认证示例：

from peerberry_sdk import PeerberryClient

with PeerberryClient(email="YOUR_EMAIL", password="YOUR_PASSWORD") as api:
    print(api.get_profile().public_id)

核心函数与常见工作流

方法映射参考：

• 个人资料与投资组合： get_profile、get_overview、get_loyalty_tier
• 贷款发现： get_loans、get_loans_page、get_loan_details
• 购买操作： purchase_loan
• 持仓查询： get_investments
• 现金流与报表： get_transactions、get_account_summary
• 批量导出： get_mass_investments、get_mass_transactions
• 元数据辅助： get_countries、get_originators

关于方法签名、枚举值及异常模式，请查阅 references/api-quickref.md。 关于可直接复制粘贴的用户提示词与意图路由逻辑，请查阅 references/task-recipes.md。

安全默认值（真实资金流程）

除非用户显式覆盖，否则始终启用以下防护措施：

• 默认优先走只读路径。
• 首次运行时设 DRY_RUN = True。
• 设置硬性上限 MAX_ORDERS。
• 跳过 loan_id 缺失的记录。
• 当字段存在时，校验 available_to_invest >= ticket_size。
• 遇到 InsufficientFunds 异常立即中止。
• 记录每笔成功下单后返回的 order_id。

已知 SDK 特性与注意事项

• get_overview 返回的 payload 结构可能为扁平格式，也可能嵌套在 items 字段下。
• get_loans 内部采用分页机制，单页最大容量为 40。
• get_loans 默认启用 group_guarantee=True。
• 国家/发起机构（originator）筛选需使用元数据辅助方法返回的显示名称（display name）。
• 导出类方法（如 get_mass_investments）返回原始 bytes 数据，而非类型化行对象。

参考文档（渐进式加载）

按需加载对应文档：

• references/p2p-primer.md
  • 适用于新手教育、通俗概念讲解及“信任优先”的沟通规范。
• references/api-quickref.md
  • 适用于查阅方法签名、允许取值、参数语义、异常类型及调试指南。
• references/task-recipes.md
  • 适用于查找常见投资者意图所对应的可复用提示词模板。

维护契约

当 SDK 发生变更时，按如下顺序更新本技能：

1. 核对方法签名与允许参数值，依据来源包括：
   • src/peerberry_sdk/client.py
   • docs/api/client.md
2. 首先更新 references/api-quickref.md。
3. 其次更新 references/task-recipes.md 中受影响的模板。
4. 保持本根文件 SKILL.md 简洁、聚焦于路由逻辑。
5. 重新检查任意新增写入类方法的安全默认策略。

项目资源

• 代码仓库：https://github.com/FortressQuant/peerberry-sdk
• 文档索引：https://github.com/FortressQuant/peerberry-sdk/tree/main/docs
• 客户端 API 参考：https://github.com/FortressQuant/peerberry-sdk/blob/main/docs/api/client.md
• 问题反馈：https://github.com/FortressQuant/peerberry-sdk/issues

技能编写参考（2026 年 3 月）

• OpenAI Academy 技能开发指南：https://academy.openai.com/public/clubs/work-users-ynjqu/resources/how-to-build-and-use-skills
• Anthropic 内存使用指引：https://docs.anthropic.com/en/docs/claude-code/memory
• GitHub Copilot 自定义指令说明：https://docs.github.com/en/copilot/how-tos/custom-instructions/adding-custom-instructions-for-github-copilot?tool=vscode
• OpenAI AGENTS.md 规范：https://github.com/openai/agents.md