Patricia

[!NOTE] 此儲存庫是從 bettergroupinc/patricia-monorepo 於 plugins/patricia/ 產生的。 自動化會同步此公開鏡像。 來源提交：df2bda0088e804342599b2b58d411e65a4cfd8d7。 請在 monorepo 中建立提取要求和議題。

patricia Claude Code 外掛程式

安裝一次後，代理程式就能正確使用 Patricia 的 MCP 伺服器，不必再提醒。

它包含三項內容。

1. 指引。 五個技能涵蓋 Patricia 基礎知識、入門、委派工作、整合，以及記憶橋接。
2. MCP 連線。 安裝時會設定 Patricia 的 Streamable HTTP 伺服器，以供 OAuth 登入。
3. 五個本機掛鉤。 它們會引導專案入門、回想記憶、優先檢查整合，並提議推送記憶。它們絕不會寫入 Patricia。

這是可散布的 Claude Code 外掛程式。使用者在自己的電腦上安裝，並在該使用者的 Claude Code 工作階段中執行。它不是 Patricia 的產品技能目錄，其中也沒有任何內容會在 Patricia 內執行。

安裝

claude plugin marketplace add patricia-app/patricia-plugin
claude plugin install patricia@patricia

接著啟動新的工作階段，或執行 /reload-plugins。

該市集是 https://github.com/patricia-app/patricia-plugin.。自動化會從 Patricia 的 monorepo 產生其中的每個檔案。

貢獻者注意事項：monorepo 是私有的。具有存取權的貢獻者可以將 monorepo 本身新增為市集，因為其根目錄中的 .claude-plugin/marketplace.json 會將 patricia 外掛程式指向 ./plugins/patricia。

請安裝，不要使用 --plugin-dir 載入。 以目錄載入的外掛程式會載入技能，但不會載入掛鉤，因此指引會生效，而記憶橋接永遠不會觸發。這是經過實測而非假設：透過 --plugin-dir 載入的探測掛鉤從未執行，而在相同無頭模式下，於專案設定中宣告的相同掛鉤則在同一次寫入時執行。Claude Code 只會為已安裝且已啟用的外掛程式註冊其 hooks/hooks.json。

claude plugin details patricia 會回報已載入的內容：

Component inventory
  Skills (5)  delegating-work, integrations, memory-bridge, onboard, using-patricia
  MCP servers (1)  patricia
  Hooks (5)  SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop

登入 MCP 伺服器

此外掛程式會設定 MCP 伺服器，不使用已儲存的標頭。首次使用時，請執行 /mcp 並選取 Patricia。你也可以從終端機啟動 OAuth 流程：

claude mcp login plugin:patricia:patricia

MCP OAuth 登入與掛鉤使用的 pat_mcp_ 個人權杖是不同的憑證。 僅有 OAuth 不會啟用依賴權杖的掛鉤。

若 OAuth 不適用，也可以改用權杖：

claude mcp add --transport http patricia https://api.patricia.app/v1/mcp \
  --header "Authorization: Bearer $PATRICIA_MCP_TOKEN"

pat_mcp_ 個人權杖會標示負責人，並具有寫入權限。pat_live_ 租用戶 API 金鑰不會標示任何人，因此只有讀取權限，也無法回答 list_skills 或 list_integrations。

為本機掛鉤提供個人權杖

本機掛鉤需要透過 python3 命令使用 Python 3。

在 Patricia 的 Settings > AI tools > Advanced > API keys 中建立 pat_mcp_ 個人金鑰。接著 選擇一種設定方式：

export PATRICIA_MCP_TOKEN="pat_mcp_..."

或在 ~/.claude/patricia.json 建立此檔案：

{
  "token": "pat_mcp_..."
}

PATRICIA_MCP_TOKEN 的優先順序高於檔案。空白的 PATRICIA_MCP_TOKEN 會停用檔案備援。 這是刻意設計的行為，讓使用者無須移動檔案，就能暫停需要驗證的掛鉤。

傳輸工作區檔案

伺服器提供 39 個工具。檔案傳輸會在 create_file、update_file 和 read_file 上使用不同模式。

• 傳送 content 或 content_base64 以進行內嵌寫入。
• 宣告 sha256、byte_size 和 content_type 以直接上傳。
• 使用一次性 upload_id 完成上傳。
• 讀取 read_file(as_download_url=true) 以取得中繼資料和暫時的簽署 GET URL。

建立宣告還需要 name 和 kind。更新宣告則需要 file_id。

將宣告結果 JSON 儲存為 declaration.json，並放在 file.pdf 旁邊。 使用 Bash、jq 和 curl 傳送每個傳回的 upload_headers 項目。 簽章會綁定 byte_size：請使用 Content-Length 傳送完全相同數量的位元組；分塊傳輸會失敗。

declaration=declaration.json
file=file.pdf
mode=$(jq -er '
  if (.upload_id | type == "string" and length > 0) and has("upload_url") then
    if .upload_url == null and .already_stored == true then "reuse"
    elif (.upload_url | type == "string" and length > 0) and .already_stored == false
      and (.upload_headers | type == "object" and all(.[]; type == "string")) then "put"
    else error("Invalid upload declaration") end
  else error("Invalid upload declaration") end
' "$declaration") || { printf 'Invalid upload declaration.\n' >&2; exit 1; }
upload_id=$(jq -r '.upload_id' "$declaration") || exit 1
if [[ "$mode" == put ]]; then
  upload_url=$(jq -r '.upload_url' "$declaration") || exit 1
  headers=()
  while IFS= read -r header; do
    headers+=(--header "$header")
  done < <(jq -r '.upload_headers | to_entries[] | "\(.key): \(.value)"' "$declaration")
  status=$(curl --silent --show-error --output /dev/null --write-out '%{http_code}' \
    --request PUT "$upload_url" "${headers[@]}" --data-binary "@$file") || exit 1
  case "$status" in
    2??|412) ;;
    *) printf 'Upload refused: HTTP %s\n' "$status" >&2; exit 1 ;;
  esac
fi
# A null upload_url skips the PUT and goes straight to completion.
printf 'Complete with upload_id %s before its expiry.\n' "$upload_id"

412 表示位元組已經上傳至此金鑰。請在到期前呼叫 complete，並提供 upload_id。 收到 412 後，完成時的 [invalid_arguments] 代表終止狀態：請內嵌傳送內容，或請擁有者分享；不要重新宣告。

校驗和是 SHA-256 摘要原始位元組的 base64 編碼。 若上傳 URL 為 null，表示 Patricia 可以透過此使用者可讀取的有效檔案重用位元組。 完成時會再次檢查存取權，並確認儲存的位元組。 建立檔案時，完成操作只需 upload_id。更新檔案時，完成操作需要 file_id 和 upload_id。 請將內嵌欄位、宣告欄位和完成欄位分開。

完成操作會傳回 id、version、byte_size、sha256，以及可用的 console_url。 建立檔案的完成操作也會傳回 sharing_note。 下載模式會傳回 id、version、byte_size、sha256、content_type、download_url 和到期欄位。 使用簽署 GET URL 在對話之外下載位元組。 下載回應不包含文字或 base64 內容欄位。 舊版資料庫內容會傳回 [download_unavailable]；一般文字讀取仍可使用。

本機掛鉤

五個掛鉤預設全都啟用。若設定檔不存在，或缺少某個掛鉤的索引鍵，該掛鉤仍會啟用。設定檔格式錯誤或無法讀取時，掛鉤會停用。若要只停用某個掛鉤，請在 ~/.claude/patricia-plugin.json 中將其列出的索引鍵設為字面值 false。

入門引導

• 時機與動作： 新工作階段或恢復的工作階段會執行 SessionStart。它會向已連線的使用者致意，並在每個專案中提供一次入門技能。
• 成本： 若有權杖，會進行一次 whoami 呼叫。網路逾時為 3 秒，掛鉤逾時為 10 秒。
• 停用方式： 將 hooks.onboarding.enabled 設為 false。
• 隱私： 若有權杖，只有經驗證的 whoami 請求會離開電腦。此掛鉤不會傳送提示、逐字稿或專案內容。

回想

• 時機與動作： 每次提交提示前都會執行 UserPromptSubmit。它會略過命令、簡短回覆、確認訊息和純程式碼輸入，並在符合條件的提示中加入相關記憶。
• 成本： 若有權杖且提示符合條件，會進行一次 search_memory 呼叫。網路逾時為 3 秒，掛鉤逾時為 8 秒。
• 停用方式： 將 hooks.recall.enabled 設為 false。
• 隱私： 它會將折疊後提示中最多 300 個字元傳送給 Patricia。只有在設定權杖時才會傳送這段文字。

優先檢查整合

• 時機與動作： UserPromptSubmit 會檢查提示。工具執行前，PreToolUse 會檢查 WebFetch、WebSearch 和 Bash 輸入。本機目錄會識別已知的提供者。
• 成本： 不會進行 MCP 或網路呼叫，也不需要權杖。提示檢查的掛鉤逾時為 8 秒，工具呼叫前的掛鉤逾時為 5 秒。
• 停用方式： 將 hooks.integrations_first.enabled 設為 false。
• 隱私： 不會有任何資料離開電腦。掛鉤會在本機檢查提示或工具輸入。

記憶橋接

• 時機與動作： 在 Write、Edit 或 MultiEdit 之後執行 PostToolUse。它會偵測已儲存的本機記憶筆記，並提議 remember，同時明確指定範圍。
• 成本： 不會進行 MCP 或網路呼叫。掛鉤逾時為 5 秒。
• 停用方式： 將 hooks.memory_bridge.enabled 設為 false。舊版的 ~/.claude/patricia-memory-bridge.json 檔案也可以將 enabled 設為 false。
• 隱私： 指令碼會在本機讀取已儲存的筆記，不會透過網路傳送任何內容。它會將筆記路徑和提醒文字傳回 Claude Code，但不會傳回筆記內容。

推送提醒

• 時機與動作： 代理程式完成時會執行 Stop。若本機記憶已寫入，或使用工具的工作階段內容豐富但未將記憶寫入 Patricia，它會提議 remember。
• 成本： 不會進行 MCP 或網路呼叫。掛鉤逾時為 8 秒。
• 停用方式： 將 hooks.push_reminder.enabled 設為 false。
• 隱私： 它最多會讀取 5 MB 的本機逐字稿，不會傳送任何內容。只有在設定權杖時才會執行，因此使用者同意後，提議的記憶呼叫才能成功。

網路與憑證

此外掛程式會透過 Streamable HTTP 連線至 https://api.patricia.app/v1/mcp。

Patricia 使用 OAuth 2.1 搭配 PKCE S256。完成 OAuth 流程後，用戶端會取得個人 pat_mcp_ bearer 權杖。

外掛程式資訊清單不包含任何憑證。登入後，用戶端會將 bearer 權杖傳送至 api.patricia.app。

其他市集

• Cursor 會從此套件讀取 plugin.json 和 mcp.json。
• OpenAI Codex 和 ChatGPT 會讀取 .codex-plugin/plugin.json。
• 遠端來源項目不需要資訊清單。若有 .claude-plugin/plugin.json，xAI 會讀取它。

所有市集套件都指向此套件中的同一個 skills/ 樹狀目錄。

assets/icon.png 是 Patricia 的官方品牌素材。

記憶橋接只會提出建議，不會寫入

掛鉤是 shell 命令。它不持有 MCP 用戶端，也未取得任何人的同意，而且無法讀取筆記並判斷某項資訊是團隊事實還是私人內容。若掛鉤將每則本機筆記都傳送至共用工作區，就會在無聲無息中把特定電腦專用、臨時和私人筆記呈現在整個團隊面前。記憶橋接的設計目的正是避免這種失誤，而不是把它留待日後處理。

因此，掛鉤只做一件事：注入 hookSpecificOutput.additionalContext，告知代理程式該筆記僅存在於本機，而 remember 需要 scope。代理程式會決定範圍、詢問使用者，然後進行呼叫。判斷和寫入都留在同一處。

四道關卡讓它保持安靜：

關卡	效果
任一支援的設定將橋接的 enabled 值設為 false	保持安靜。若未設定該值，橋接功能就會啟用。
寫入路徑不在記憶目錄中	保持安靜。
寫入未成功，或檔案為空	保持安靜。
筆記的 front matter 含有 patricia: skip	保持安靜。

此外，每個工作階段中，同一則筆記最多只會提示一次，因此一次 Write 後接一連串 Edit 呼叫時，只會產生一則提醒，而不是四則。記錄會存放在 ~/.claude/patricia-memory-bridge-state/，每個工作階段各一個檔案，並在七天後清除。

它不會使用 CLAUDE_PLUGIN_DATA。此變數雖然存在於掛鉤的環境中，但不一定可靠地指向目前執行之外掛程式目錄：此電腦上的專案層級掛鉤發現它被設為 ~/.claude/plugins/data/codex-openai-codex，那是另一個無關外掛程式的資料目錄。

記憶寫入實際使用哪個工具

Claude Code 2.1.238 宣告了名為 memory_list、memory_read 和 memory_write 的工具。在建置所依據的電腦上，記憶筆記並非使用這些工具寫入：掃描最近 120 份工作階段逐字稿後，發現有 49 次 Write 和 35 次 Edit 呼叫 ~/.claude/projects/*/memory/，而 memory_write 呼叫則是零次。

因此，配對器會使用 Write|Edit|MultiEdit。刻意不納入 memory_write。若為尚未驗證負載形狀的工具新增配對器，只會得到一個永遠不會觸發的掛鉤，而且看起來和正常運作的掛鉤一模一樣。等讀取過實際的 memory_write 負載後再新增。

指引與伺服器的既定規則共用同一份內容，不會重複

start_onboarding_import 可能會傳回一個 standing_rule_to_offer，其中包含 ask_first、instruction，以及一段大小適合放入他人 CLAUDE.md 的 markdown 區塊。技能不會重述該區塊，而是告訴代理程式呼叫工具並使用傳回的內容，讓伺服器成為該段文字的唯一維護者。

另一種做法是在安裝時擷取內容，但行不通。外掛程式的 SKILL.md 是內容定址快取中的靜態文字，沒有任何安裝時步驟可以改寫它；而且，負責設定 Patricia 的外掛程式，不能依賴已驗證的 Patricia 連線正常運作，才能產生自己的指示。在使用時讀取工具，就能取得同一份內容，且沒有上述問題。

此處的每個工具名稱都是真實工具

此外掛中每個以反引號括住的工具識別碼，都會與伺服器自己的工具登錄表比對；該清單由伺服器建置而成 tools/list。同一項檢查也會確認找到的識別碼集合非空，因此擷取器故障時，不會因為什麼都沒找到而通過檢查。

貢獻者注意事項：在 Patricia 的單一儲存庫中，這項檢查是 backend/api/tests/test_patricia_claude_plugin.py，而且每次變更此插件時都會執行。

設定與檔案探索

工具	用途
get_settings	列出設定，或讀取選定的索引鍵或群組及其說明、值和權限。兩種憑證都能讀取工作區群組。
update_settings	透過儀表板操作變更一個允許修改的群組。需要個人權杖。
list_files	列出檔案。第一頁包含資料夾和依可見性篩選的計數。
get_brand_kit	讀取品牌色彩、字體排版和標誌。

公司簡介請使用 get_settings(keys=["company_profile"])。 設定工具共用 Patricia 在聊天中使用的目錄和操作。 聊天中的設定變更需要提出請求的人員點擊確認。 核准政策變更會影響主控台執行；重要操作和提供者要求的操作仍保留其核准門檻，而對象和僅限點擊的門檻，則會套用於 Patricia 已詢問的任何操作。

當同一人有其他工作正在執行時，整合讀取會等待。 使用 get_task_status 輪詢該工作，或等待它完成。 直接核准整合後，請遵循 decide_approval 傳回的 next 句子。 使用工作 ID 輪詢 get_task_status 以取得結果。請勿再次呼叫該工具；Patricia 會執行一次已核准的操作。操作完成後再次呼叫即為新請求；目前的核准規則會決定是否需要先詢問。 請遵循 next 指示：Billit 中已儲存的審查和核准若未儲存請求者身分，可能需要再次進行相同呼叫。