Patricia

官方

Patricia将您的AI客户端连接到一个Patricia工作区。读取工作区记忆和文件，检查已集成的连接，并在人工审批控制下将工作委派给Patricia。

你可以用 Patricia MCP 做什么？

安装插件 — 从 patricia-app/patricia-plugin 市场安装 patricia，以便 Claude Code 加载其技能、MCP 服务器和钩子。
登录 MCP 服务器 — 通过 /mcp 使用 OAuth 对 patricia 服务器进行身份验证，或添加带有 pat_mcp_ bearer token 标头的服务器。
传输工作区文件 — 在 create_file 或 update_file 中声明 sha256、byte_size 和 content_type，然后使用其 upload_id 完成上传。
以下载方式读取文件 — 调用 read_file 并设置 as_download_url=true，以获取元数据和临时签名 GET URL。
在提示前检索记忆 — 设置令牌后，记忆检索钩子会通过一次 search_memory 调用，将相关记忆添加到符合条件的提示中。
提议写入记忆 — 记忆桥接和推送提醒会提议使用明确的作用域调用 remember；它们不会自行写入 Patricia。

文档

[!NOTE] 此仓库由 bettergroupinc/patricia-monorepo 在 plugins/patricia/ 生成。自动化会同步此公开镜像。源提交：df2bda0088e804342599b2b58d411e65a4cfd8d7。请在单体仓库中创建拉取请求和问题。

`patricia` Claude Code 插件

安装一次后，代理就能正确使用 Patricia 的 MCP 服务器，无需再次说明。

它包含三项内容。

指导。 五项技能涵盖 Patricia 基础知识、入门、委派工作、集成和记忆桥接。
MCP 连接。 安装会配置 Patricia 的 Streamable HTTP 服务器，以便通过 OAuth 登录。
五个本地钩子。 它们会引导项目入门、回忆记忆、优先检查集成，并建议推送记忆。它们绝不会写入 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 的单体仓库生成其中的每个文件。

贡献者须知：单体仓库是私有的。有访问权限的贡献者可以将单体仓库本身添加为市场，因为其根目录中的 .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 表示字节已上传到此密钥。请在过期前使用 upload_id 调用 complete。收到 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。
隐私： 它会向 Patricia 发送最多 300 个字符的合并提示。只有配置了令牌时才会发送这些文本。

优先检查集成

触发时机和操作： 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 使用带 PKCE S256 的 OAuth 2.1。完成 OAuth 流程后，客户端会获得个人 pat_mcp_ bearer token。

插件清单不包含凭据。登录后，客户端会将 bearer token 发送到 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 份会话记录的扫描发现，Write 有 49 次，Edit 调用 ~/.claude/projects/*/memory/ 有 35 次，而 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 的 monorepo 中，这项检查是 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 已保存审核和审批，可能需要再次进行相同调用。