用您自己的智能体自动更新持仓

流水线做什么

润玉有效期间，您自己的智能体可将金融机构导出的持仓转为 Portfonia 中更新后的当前持仓簿。它检查来源、读取持仓簿、准备并校验变更、写入，再查看变更记录。机构访问、导出及定时运行由您自己的智能体和工具负责。Portfonia 不登录机构、不下载对账单，也不安排这些运行；它保存和更新持仓记录，不执行交易。

一次性设置

在 AI智能体页面，为要更新持仓的智能体创建持仓写入 token；只读取持仓的智能体使用只读 token。将 token 和 https://portfonia.com/llms.txt 交给智能体。它先调用 GET /agent/v1/token（验证令牌权限）。要更新持仓的智能体在 capabilities.holdings_write 为 false 时停下；只读智能体在 capabilities.holdings_read 为 false 时停下。

每次运行的步骤

  1. 检查机构导出是否涵盖该机构的每个账户，以及持仓截至日期是否符合预期。导出不完整或已过时，就跳过本次运行。
  2. 调用 GET /agent/v1/holdings，保留返回的 version 和每条持仓的 id。
  3. 用稳定的持仓 ID 匹配已有行，不能只按 ticker 匹配。同一标的在两个账户中是两条持仓。
  4. 只修改属于本次机构的行。用 POST /agent/v1/holdings 新增、PATCH /agent/v1/holdings/{holding_id} 修改，或 DELETE /agent/v1/holdings/{holding_id} 删除。单行 DELETE 删除路径中 ID 对应的持仓。也可用 PUT /agent/v1/holdings 提交整本持仓簿，但必须原样列出其他所有行：保留的已有行列入 holdings，删除的 ID 明确列入 delete_ids。已有行若在两个列表中都遗漏，整次请求失败。
  5. 新增、整本替换、单行替换或 PATCH 前，先调用 POST /agent/v1/holdings/validate，operation 分别为 create、replace_all、replace 或 patch，相关字段见 agent.md。仅在 valid 为 true 时继续，再用当前 version 写入。单行替换使用 PUT /agent/v1/holdings/{holding_id}。删除没有校验步骤；将当前版本加双引号放入 If-Match 请求头，不发送 JSON 正文。校验不预留版本，也不保证之后的写入成功。
  6. 遇到 409 version_conflict，重新读取持仓簿并重新计算预期变更，不能只替换旧正文中的 version 就重发。后续每次写入使用上次返回的版本。
  7. 通过 POST 新增时发送 Idempotency-Key。超时后，在 24 小时内使用相同的键和相同正文（包括原版本）重试，取得首次结果。再次写入前重新读取。
  8. 之后调用 GET /agent/v1/holdings/changes，用最近 30 天内的美东 start、end 日期确认变更，包含首尾两天。truncated 为 true 时缩小日期范围。无变化写入和幂等重放不生成变更记录组。

限制与保护措施

润玉最多保存 100 条持仓，现金和观察中的持仓也计入。所有 token 的单行写入共用每分钟 30 次、每小时 100 次额度。读取、整本 PUT 和校验使用一般读取额度。重型定时任务开始前五分钟至结束后五分钟暂停请求；请求被拒绝时按 Retry-After 等待。不能通过 API 删除最后一条持仓；清空整个持仓簿只能在网页操作。成功读取当前持仓、变更记录、快照和润玉风险结果共用每个美东日期最多一次的读取提示。成功写入可能触发单独的每日修改提示；校验和幂等重放不发送数据提示。提示中的链接会一次吊销账户的全部 token，包括其他智能体使用的 token，阻止后续访问，但不会撤销已保存的修改。 智能体写入或文件上传若导致持仓行数大幅减少或总价值大幅变化，可能触发单独的告警邮件，每个写入发生的美东日期最多一封。

Portfonia 中会发生什么变化

写入会更新 Portfonia 保存的当前持仓簿。之后的简报和润玉工具——持仓回放、尾部风险、历史情景压力测试、风格敞口和跟踪——使用更新后的持仓簿。每次请求都会记入审计日志；审计只保存请求元数据，不保存持仓正文或完整 token。