用您自己的智能體自動更新持倉

流水線做什麼

潤玉有效期間，您自己的智能體可將金融機構匯出的持倉轉為 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。