Skip to content

DEVELOPER_API.zh-TW.md

Latest commit

 

History

History
85 lines (63 loc) · 3.13 KB

DEVELOPER_API.zh-TW.md

File metadata and controls

85 lines (63 loc) · 3.13 KB
Raw

CodeCart 思維卡 協議規範 (v2.0)

English | 简体中文 | 繁體中文 | 日本語

目的

本文件定義思維卡的「往返協議」,使任何 AI 產品、Agent 框架、瀏覽器擴充功能或腳本都能讀寫用戶的記憶卡包並保持相容。協議刻意做得極小:它必須能在普通聊天回覆裡被任何大模型可靠輸出。

三個構件

  1. 攜帶區塊——用戶貼給 AI 的內容:有效卡片 + 一段要求模型輸出更新的指令。
  2. codecart 區塊——模型附加在回覆結尾的記憶更新(圍欄程式碼區塊)。
  3. 卡包檔案——匯出的 JSON,保存全部卡片,是用戶可攜帶的權威儲存。

1. 攜帶區塊

[這是我的個人記憶(CodeCart 思維卡卡包,<日期>)。請據此個人化你的所有回答。]
- (preference) 回答簡短,先給結論
- (fact) 我經營一家網店
- (boundary) 不要推薦超過每月 5000 元預算的方案
---
<要求模型附加 codecart 區塊的指令——標準措辭見應用內>

卡片類型:preference(回答偏好)、fact(穩定資訊)、status(當前關注,會變化)、boundary(硬性規則)。

2. codecart 區塊語法

模型在回覆結尾附加:

```codecart
+ <type> | <內容>
~ <照抄過時記憶行中的片段> => <修正後的內容>
- <要退役的記憶行片段>
```
  • + 新增卡片。<type> 為四種類型之一;省略時(+ <內容>)消費方應預設 fact——但僅限圍欄區塊內,以避免誤判。
  • ~ 替代更新:消費方查找文字包含 <片段> 的有效卡片(不分大小寫),將其封存並新增修正卡。這是卡包保持最新而非無限膨脹的關鍵。
  • - 直接退役一張卡,無替代(僅限圍欄區塊內)。
  • 建議的模型規則(攜帶指令中已包含):最多 5 行;只記錄持久的個人資訊;用用戶的語言書寫;無內容時完全省略該區塊。

解析器也應接受圍欄外的這類行,但僅當存在顯式的 <type> | 前綴時。

3. 卡包檔案 (JSON)

{
  "version": 2,
  "cards": [
    {
      "id": "m3k9x1ab2",
      "type": "preference",
      "text": "回答簡短,先給結論",
      "status": "active",
      "created": 1720300000000,
      "updated": 1720300000000
    }
  ]
}

status 為 active 或 archived。消費方必須只攜帶 active 卡片;匯入合併時必須按 text 去重(忽略大小寫與首尾空白)。

參考:在 API 流水線中消費卡包

import json

with open("codecart-wallet.json", encoding="utf-8") as f:
    wallet = json.load(f)

carry = "\n".join(
    f"- ({c['type']}) {c['text']}"
    for c in wallet["cards"] if c["status"] == "active"
)
# 把 carry 拼進 system prompt;按上述語法解析模型輸出中的
# ```codecart``` 區塊並合併回卡包。

相容性承諾

  • 區塊標籤恆為字面量 codecart。
  • 未知卡片類型按 fact 處理;未知 JSON 欄位在往返中必須原樣保留。
  • v1.3 舊版匯出(nodes + +CLAIM/+ANCHOR 語義)映射為:anchor → boundary、claim → fact、isSuperseded → archived。