Patricia

[!NOTE] Kho lưu trữ này được tạo từ bettergroupinc/patricia-monorepo tại plugins/patricia/. Tự động hóa đồng bộ bản sao công khai này. Commit nguồn: df2bda0088e804342599b2b58d411e65a4cfd8d7. Mở yêu cầu kéo và vấn đề trong kho đơn khối.

Plugin Claude Code patricia

Cài đặt một lần, tác nhân sẽ sử dụng đúng máy chủ MCP của Patricia mà không cần được nhắc lại.

Plugin này bao gồm ba thành phần.

1. Hướng dẫn. Năm kỹ năng bao quát kiến thức cơ bản về Patricia, quy trình làm quen, công việc được ủy quyền, tích hợp và cầu nối bộ nhớ.
2. Kết nối MCP. Quá trình cài đặt cấu hình máy chủ Streamable HTTP của Patricia để đăng nhập OAuth.
3. Năm hook cục bộ. Chúng hướng dẫn làm quen với dự án, truy xuất bộ nhớ, kiểm tra tích hợp trước và đề xuất đẩy bộ nhớ. Chúng không bao giờ ghi vào Patricia.

Đây là plugin Claude Code có thể phân phối. Một người cài đặt plugin trên máy của họ, và plugin chạy trong phiên Claude Code của người đó. Đây không phải danh mục kỹ năng sản phẩm của Patricia, và không có thành phần nào trong plugin chạy bên trong Patricia.

Cài đặt

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

Sau đó, bắt đầu phiên mới hoặc chạy /reload-plugins.

Marketplace đó là https://github.com/patricia-app/patricia-plugin. Tự động hóa tạo mọi tệp trong đó từ kho đơn khối của Patricia.

Lưu ý cho người đóng góp: kho đơn khối là riêng tư. Người đóng góp có quyền truy cập có thể thêm chính kho đơn khối làm marketplace, vì tệp gốc .claude-plugin/marketplace.json trỏ plugin patricia đến ./plugins/patricia.

Hãy cài đặt plugin. Đừng tải plugin bằng --plugin-dir. Plugin được tải từ thư mục sẽ có các kỹ năng nhưng không có hook, vì vậy hướng dẫn vẫn hoạt động nhưng cầu nối bộ nhớ sẽ không bao giờ chạy. Điều này đã được đo kiểm chứ không phải giả định: một hook thăm dò được tải qua --plugin-dir không bao giờ chạy, trong khi cùng hook đó được khai báo trong cài đặt dự án lại chạy khi ghi cùng nội dung ở cùng chế độ không giao diện. Claude Code chỉ đăng ký hooks/hooks.json của plugin khi plugin đã được cài đặt và bật.

claude plugin details patricia báo cáo những gì đã được cài đặt:

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

Đăng nhập vào máy chủ MCP

Plugin cấu hình máy chủ MCP mà không lưu tiêu đề. Khi sử dụng lần đầu, chạy /mcp và chọn Patricia. Bạn cũng có thể bắt đầu quy trình OAuth từ terminal:

claude mcp login plugin:patricia:patricia

Đăng nhập MCP OAuth và mã thông báo cá nhân pat_mcp_ của các hook là hai thông tin xác thực riêng biệt. Chỉ OAuth thôi sẽ không kích hoạt các hook phụ thuộc vào mã thông báo.

Hãy dùng mã thông báo thay thế nếu OAuth không phù hợp:

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

Mã thông báo cá nhân pat_mcp_ xác định người chịu trách nhiệm và có thể ghi dữ liệu. Khóa API tenant pat_live_ không xác định danh tính ai, nên chỉ có quyền đọc và không thể trả lời list_skills hoặc list_integrations.

Cung cấp mã thông báo cá nhân cho các hook cục bộ

Các hook cục bộ cần Python 3 khả dụng thông qua lệnh python3.

Tạo khóa cá nhân pat_mcp_ trong Patricia tại Settings > AI tools > Advanced > API keys. Sau đó chọn một cách thiết lập:

export PATRICIA_MCP_TOKEN="pat_mcp_..."

Hoặc ghi tệp này tại ~/.claude/patricia.json:

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

PATRICIA_MCP_TOKEN được ưu tiên hơn tệp. PATRICIA_MCP_TOKEN rỗng sẽ vô hiệu hóa phương án dự phòng dùng tệp. Đây là hành vi có chủ đích. Nhờ vậy, người dùng có thể tạm ngưng các hook đã xác thực mà không cần di chuyển tệp.

Truyền tệp không gian làm việc

Máy chủ cung cấp 39 công cụ. Việc truyền tệp sử dụng các chế độ trên create_file, update_file và read_file.

• Gửi content hoặc content_base64 để ghi nội tuyến.
• Khai báo sha256, byte_size và content_type để tải lên trực tiếp.
• Hoàn tất tải lên bằng upload_id chỉ dùng một lần.
• Đọc read_file(as_download_url=true) để lấy siêu dữ liệu và URL GET có chữ ký tạm thời.

Khai báo tạo mới cũng cần name và kind. Khai báo cập nhật cần file_id.

Lưu JSON kết quả khai báo dưới tên declaration.json bên cạnh file.pdf. Dùng Bash, jq và curl để gửi mọi mục upload_headers được trả về. Chữ ký ràng buộc byte_size: gửi chính xác số byte đó cùng Content-Length; truyền theo kiểu chunked sẽ thất bại.

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 nghĩa là các byte đã được tải lên khóa này. Gọi complete với upload_id trước khi hết hạn. Sau 412, [invalid_arguments] tại bước hoàn tất là trạng thái cuối: gửi nội dung nội tuyến hoặc nhờ chủ sở hữu chia sẻ; không khai báo lại.

Checksum là biểu diễn base64 của các byte thô trong giá trị băm SHA-256. URL tải lên null nghĩa là Patricia có thể dùng lại byte thông qua một tệp đang hoạt động mà người này có thể đọc. Bước hoàn tất kiểm tra lại quyền truy cập đó và xác nhận các byte đã lưu. Hoàn tất thao tác tạo mới chỉ với upload_id. Hoàn tất thao tác cập nhật với file_id và upload_id. Giữ riêng các trường nội tuyến, trường khai báo và trường hoàn tất.

Bước hoàn tất trả về id, version, byte_size, sha256 và console_url nếu có. Bước hoàn tất tạo mới cũng trả về sharing_note. Chế độ tải xuống trả về id, version, byte_size, sha256, content_type, download_url và các trường thời hạn. Dùng URL GET có chữ ký để tải byte xuống bên ngoài cuộc hội thoại. Phản hồi tải xuống không chứa trường nội dung văn bản hoặc base64. Nội dung cơ sở dữ liệu cũ trả về [download_unavailable]; vẫn có thể đọc văn bản thông thường.

Hook cục bộ

Cả năm hook đều được bật theo mặc định. Tệp cấu hình không tồn tại hoặc thiếu khóa hook thì hook vẫn bật. Cấu hình sai định dạng hoặc không đọc được sẽ tắt các hook. Đặt khóa được liệt kê của một hook thành giá trị nguyên văn false trong ~/.claude/patricia-plugin.json để chỉ tắt hook đó.

Làm quen

• Thời điểm và hành động: SessionStart chạy khi bắt đầu phiên mới hoặc tiếp tục phiên. Hook chào người đã kết nối và đề xuất kỹ năng làm quen một lần cho mỗi dự án.
• Chi phí: Khi có mã thông báo, hook thực hiện một lệnh gọi whoami. Thời gian chờ mạng là 3 giây, thời gian chờ của hook là 10 giây.
• Cách tắt: Đặt hooks.onboarding.enabled thành false.
• Quyền riêng tư: Khi có mã thông báo, chỉ yêu cầu whoami đã xác thực mới rời khỏi máy. Hook này không gửi prompt, bản ghi hội thoại hay nội dung dự án ra ngoài.

Truy xuất

• Thời điểm và hành động: UserPromptSubmit chạy trước mỗi prompt được gửi. Hook bỏ qua lệnh, câu trả lời ngắn, xác nhận và đầu vào chỉ có mã. Hook bổ sung bộ nhớ liên quan vào các prompt đủ điều kiện.
• Chi phí: Khi có mã thông báo và prompt đủ điều kiện, hook thực hiện một lệnh gọi search_memory. Thời gian chờ mạng là 3 giây, thời gian chờ của hook là 8 giây.
• Cách tắt: Đặt hooks.recall.enabled thành false.
• Quyền riêng tư: Hook gửi tối đa 300 ký tự của prompt đã được gộp khoảng trắng đến Patricia. Chỉ gửi văn bản đó khi đã cấu hình mã thông báo.

Ưu tiên tích hợp

• Thời điểm và hành động: UserPromptSubmit kiểm tra prompt. PreToolUse kiểm tra đầu vào WebFetch, WebSearch và Bash trước khi công cụ chạy. Danh mục cục bộ nhận diện các nhà cung cấp đã biết.
• Chi phí: Hook không gọi MCP hay mạng và không cần mã thông báo. Thời gian chờ của hook là 8 giây đối với prompt và 5 giây trước khi gọi công cụ.
• Cách tắt: Đặt hooks.integrations_first.enabled thành false.
• Quyền riêng tư: Không có dữ liệu nào rời khỏi máy. Hook kiểm tra prompt hoặc đầu vào công cụ cục bộ.

Cầu nối bộ nhớ

• Thời điểm và hành động: PostToolUse chạy sau Write, Edit hoặc MultiEdit. Hook phát hiện ghi chú bộ nhớ cục bộ đã lưu và đề xuất remember với phạm vi rõ ràng.
• Chi phí: Hook không gọi MCP hay mạng. Thời gian chờ của hook là 5 giây.
• Cách tắt: Đặt hooks.memory_bridge.enabled thành false. Tệp cũ ~/.claude/patricia-memory-bridge.json cũng có thể đặt enabled thành false.
• Quyền riêng tư: Tập lệnh đọc ghi chú đã lưu cục bộ và không gửi gì qua mạng. Tập lệnh trả về đường dẫn ghi chú và lời nhắc cho Claude Code, không kèm nội dung ghi chú.

Nhắc đẩy bộ nhớ

• Thời điểm và hành động: Stop chạy khi tác nhân hoàn tất. Hook đề xuất remember sau khi ghi bộ nhớ cục bộ hoặc sau một phiên sử dụng công cụ đáng kể mà không ghi bộ nhớ vào Patricia.
• Chi phí: Hook không gọi MCP hay mạng. Thời gian chờ của hook là 8 giây.
• Cách tắt: Đặt hooks.push_reminder.enabled thành false.
• Quyền riêng tư: Hook đọc tối đa 5 MB bản ghi phiên cục bộ và không gửi gì đi. Hook chỉ chạy khi đã cấu hình mã thông báo, để lệnh gọi bộ nhớ được đề xuất có thể thành công sau khi người dùng đồng ý.

Mạng và thông tin xác thực

Plugin này kết nối với https://api.patricia.app/v1/mcp qua Streamable HTTP.

Patricia sử dụng OAuth 2.1 với PKCE S256. Quy trình OAuth hoàn tất sẽ cấp cho ứng dụng khách mã thông báo bearer cá nhân pat_mcp_.

Tệp kê khai plugin không chứa thông tin xác thực. Sau khi đăng nhập, ứng dụng khách gửi mã thông báo bearer đến api.patricia.app.

Các marketplace khác

• Cursor đọc plugin.json và mcp.json từ gói này.
• OpenAI Codex và ChatGPT đọc .codex-plugin/plugin.json.
• Mục nguồn từ xa không cần tệp kê khai. xAI đọc .claude-plugin/plugin.json nếu có.

Tất cả gói marketplace đều trỏ đến cùng một cây skills/ trong gói này.

assets/icon.png là tài sản thương hiệu chính thức của Patricia.

Cầu nối bộ nhớ chỉ đề xuất, không bao giờ ghi

Hook là một lệnh shell. Hook không có ứng dụng khách MCP, không được ai đồng ý và không thể đọc ghi chú để phân biệt thông tin của nhóm với thông tin riêng tư. Một hook gửi mọi ghi chú cục bộ đến không gian làm việc dùng chung sẽ âm thầm đưa các ghi chú riêng của máy, tạm thời và riêng tư đến toàn nhóm. Cầu nối được xây dựng để tránh chính tình huống đó, chứ không phải để trì hoãn tính năng này.

Vì vậy, hook chỉ làm một việc: chèn hookSpecificOutput.additionalContext để cho tác nhân biết ghi chú chỉ nằm cục bộ và remember cần có scope. Tác nhân quyết định phạm vi, hỏi người dùng và thực hiện lệnh gọi. Việc đánh giá và ghi dữ liệu vẫn diễn ra cùng một nơi.

Bốn điều kiện giúp hook không làm phiền:

Điều kiện	Tác động
Một trong hai cấu hình được hỗ trợ đặt giá trị enabled của cầu nối thành false	Im lặng. Nếu không có giá trị đó, cầu nối được bật.
Đường dẫn đã ghi nằm ngoài thư mục bộ nhớ	Im lặng.
Thao tác ghi không thành công hoặc tệp trống	Im lặng.
Phần đầu tệp của ghi chú có patricia: skip	Im lặng.

Hook cũng chỉ đề xuất một ghi chú tối đa một lần mỗi phiên, vì vậy một lần Write rồi đến một loạt lệnh gọi Edit chỉ tạo ra một lời nhắc thay vì bốn. Bản ghi đó nằm trong ~/.claude/patricia-memory-bridge-state/, mỗi phiên một tệp và được dọn sau bảy ngày.

Hook không dùng CLAUDE_PLUGIN_DATA cho việc này. Biến đó có trong môi trường của hook nhưng không phải lúc nào cũng trỏ đến thư mục của chính plugin đang chạy: một hook cấp dự án trên máy này thấy biến được đặt thành ~/.claude/plugins/data/codex-openai-codex, thư mục dữ liệu của một plugin không liên quan.

Công cụ thực sự được dùng để ghi bộ nhớ

Claude Code 2.1.238 khai báo các công cụ có tên memory_list, memory_read và memory_write. Trên các máy dùng để xây dựng tính năng này, ghi chú bộ nhớ không được ghi bằng các công cụ đó: rà soát 120 bản ghi phiên gần đây nhất tìm thấy 49 lệnh gọi Write và 35 lệnh gọi Edit đến ~/.claude/projects/*/memory/, nhưng không có lệnh gọi memory_write nào.

Vì vậy, bộ so khớp là Write|Edit|MultiEdit. Cố ý không đưa memory_write vào. Thêm bộ so khớp cho một công cụ có cấu trúc tải dữ liệu chưa được xác minh sẽ tạo ra một hook âm thầm không bao giờ chạy, trông chẳng khác gì hook hoạt động bình thường. Hãy thêm công cụ đó khi đã đọc được một tải dữ liệu memory_write thực tế.

Hướng dẫn và quy tắc thường trực của máy chủ dùng chung một bản, không phải hai

start_onboarding_import có thể trả về một standing_rule_to_offer chứa ask_first, instruction và một khối markdown có kích thước phù hợp với CLAUDE.md của người khác. Kỹ năng không nhắc lại khối đó. Kỹ năng hướng dẫn tác nhân gọi công cụ và sử dụng nội dung trả về, nhờ vậy máy chủ vẫn là nơi duy nhất quản lý phần hướng dẫn đó.

Phương án thay thế là lấy nội dung này khi cài đặt, nhưng cách đó không hiệu quả. SKILL.md của plugin là văn bản tĩnh trong bộ nhớ đệm được định địa chỉ theo nội dung, không có bước nào khi cài đặt có thể viết lại nội dung đó, và một plugin có nhiệm vụ thiết lập Patricia không thể phụ thuộc vào kết nối Patricia đã xác thực đang hoạt động để hiển thị hướng dẫn của chính nó. Lấy nội dung từ công cụ khi sử dụng sẽ cho cùng một bản duy nhất mà không gặp những vấn đề đó.

Mọi tên công cụ ở đây đều là công cụ có thật

Mọi mã định danh công cụ được đặt trong dấu backtick trong plugin này đều được đối chiếu với danh mục công cụ riêng của máy chủ, danh sách mà máy chủ tạo tools/list từ đó. Cùng một bước kiểm tra cũng xác nhận rằng đã tìm thấy một tập hợp mã định danh không rỗng, để trình trích xuất bị lỗi không thể vượt qua bằng cách không tìm thấy gì.

Ghi chú cho người đóng góp: bước kiểm tra đó là backend/api/tests/test_patricia_claude_plugin.py trong monorepo của Patricia và chạy mỗi khi plugin này có thay đổi.

Cài đặt và tìm kiếm tệp

Công cụ	Công dụng
get_settings	Liệt kê cài đặt hoặc đọc các khóa hay nhóm được chọn cùng ý nghĩa, giá trị và quyền hạn. Cả hai loại thông tin xác thực đều có thể đọc các nhóm trong không gian làm việc.
update_settings	Thay đổi một nhóm được phép thông qua thao tác trên bảng điều khiển. Cần có token cá nhân.
list_files	Liệt kê tệp. Trang đầu tiên bao gồm các thư mục và số lượng đã lọc theo chế độ hiển thị.
get_brand_kit	Đọc màu sắc thương hiệu, kiểu chữ và logo.

Dùng get_settings(keys=["company_profile"]) cho hồ sơ công ty. Các công cụ cài đặt dùng chung danh mục và thao tác mà Patricia sử dụng trong cuộc trò chuyện. Các thay đổi cài đặt trong cuộc trò chuyện cần người yêu cầu nhấp xác nhận. Thay đổi chính sách phê duyệt ảnh hưởng đến các lần chạy trên bảng điều khiển; các hành động quan trọng và hành động bắt buộc phải được nhà cung cấp phê duyệt vẫn giữ nguyên mức phê duyệt tối thiểu, còn các mức tối thiểu dành cho đối tượng và chỉ cần nhấp xác nhận vẫn được giữ nguyên đối với mọi hành động mà Patricia đã hỏi.

Các thao tác đọc tích hợp sẽ chờ khi có tác vụ khác đang chạy cho cùng một người. Thăm dò tác vụ đó bằng get_task_status, hoặc chờ tác vụ hoàn tất. Sau khi phê duyệt tích hợp trực tiếp, hãy làm theo câu next do decide_approval trả về. Thăm dò get_task_status bằng mã tác vụ để lấy kết quả. Không gọi công cụ lần nữa; Patricia sẽ chạy hành động đã được phê duyệt một lần. Lời gọi sau khi tác vụ hoàn tất là một yêu cầu mới; các quy tắc phê duyệt hiện hành sẽ quyết định liệu yêu cầu đó có cần được phê duyệt trước hay không. Làm theo hướng dẫn next: các đánh giá và phê duyệt đã lưu của Billit không có danh tính người yêu cầu được lưu trữ có thể yêu cầu thực hiện lại cùng một lời gọi.