插件扩展体系Extension model

PurrCat 通过「插件」扩展能力。除社区通用的 Skill（技能包）与 MCP（外部工具服务）外，另有四类专属插件，分别对应 Agent 的感官、编排、主循环与界面。 PurrCat extends itself through plugins. Beyond the community-standard skill and MCP extension points, there are four PurrCat-specific types, one for each of the agent's senses, orchestration, main loop, and interface.

类型Type	定位Role	形态Form	落地目录Runtime directory
`sensor`	感官中枢：把外部事件推给 Agent，并把回复送回外部渠道 Senses: push outside events to the agent and carry replies back out	单文件 Python 常驻子进程 Single-file long-running Python subprocess	`~/.purrcat/sensor/`
`graph`	任务编排中枢：用节点 + 边描述多步骤工作流 Orchestration: a multi-step workflow as nodes and edges	文件夹（`graph.json` + `asset/`） Folder (`graph.json` + `asset/`)	`~/.purrcat/graph/<name>/`
`agentloop`	主循环范式：声明每轮循环在哪些阶段注入什么、检查什么 Main loop: what each stage injects and checks every round	单个 YAML 文件A single YAML file	`~/.purrcat/paradigms/`
`plugin`	UI 插件：极简模式（`web-minimal`）的界面插件 UI plugin: an interface plugin for minimal mode (`web-minimal`)	文件夹（`plugin.json` + `index.html`） Folder (`plugin.json` + `index.html`)	`~/.purrcat/webmin-plugins/`

依赖机制Dependencies

除 Sensor 外，其余三类的清单文件都支持 dependency 声明数组。元素固定形如 { "type": "<类型>", "id": "<安装标识>" }，type 白名单为 skill / plugin / mcp / agentloop / sensor / graph，无依赖时写 []。用户从市场安装某插件时，其 dependency 里声明的依赖会被自动一并安装。 Every manifest except a sensor supports a dependency array. Each entry is { "type": "<type>", "id": "<install id>" }, where type is one of skill, plugin, mcp, agentloop, sensor, or graph. Use [] when there are none. Installing a plugin from the market pulls its declared dependencies in automatically.

"dependency": [
  { "type": "skill",     "id": "my-skill" },
  { "type": "agentloop", "id": "my-loop" },
  { "type": "graph",     "id": "my-graph" },
  { "type": "sensor",    "id": "my-sensor" },
  { "type": "plugin",    "id": "my-ui-plugin" },
  { "type": "mcp",       "id": "my-mcp" }
]

生效位置Where plugins live

插件只有放进下列目录才会被加载，各类型的清单与配置文件也写在这些目录内（从市场安装时会自动落到位）。 A plugin is only loaded once it sits in the directory below; each type's manifest and config files live there too (installing from the market places them for you).

插件类型Type	生效目录Runtime directory	清单 / 配置文件Manifest / config
`skill`	`~/.purrcat/skills/<name>/`	技能包本体（`SKILL.md` 及随附文件） The skill folder itself (`SKILL.md` plus bundled files)
`mcp`	`~/.purrcat/mcps/<name>/`	`~/.purrcat/mcp_config.json`
`sensor`	`~/.purrcat/sensor/<name>.py`	同目录的 `config.json`；启用开关与凭证写入 `~/.purrcat/activate_sensor.json` `config.json` beside it; the enable switch and credentials are written to `~/.purrcat/activate_sensor.json`
`graph`	`~/.purrcat/graph/<name>/`	`graph.json`（+ `asset/` 资源）
`agentloop`	`~/.purrcat/paradigms/<name>.yaml`	即该 YAML 本体；默认范式为 `PARADIGM.yaml` The YAML file itself; the default loop is `PARADIGM.yaml`
`plugin`	三处根目录，优先级 user > sandbox > builtin（见下） Three roots, priority user > sandbox > builtin (see below)	`plugin.json` + `index.html`

UI Plugin 的三种生效位置：同一个 id 出现在多处时，优先级最高的那份生效。 UI plugins have three roots: when the same id appears in more than one, the highest-priority copy wins.

~/.purrcat/webmin-plugins/<id>/       用户（优先级最高）
agent_vm/ui-plugin/<id>/             沙盒（Agent 开发区）
ui/web-minimal/plugins/builtin/<id>/ 内置（随分发，只读）

安装 UI 插件时，其注册表条目的 root 字段（user / sandbox / builtin）决定它落到上面哪一处。 When installing a UI plugin, the root field of its registry entry (user / sandbox / builtin) decides which root it lands in.

组合关系How they combine

外部渠道 ─▶ Sensor ─┐
                    ├──▶ Agent ◀── UI Plugin ◀── 用户
                    │
   AgentLoop ───────┼─▶ 注入引导信息 · 必要节点审批 / 打回
   原生工具 ────────┴─▶ 发现并调用 Graph / MCP / Skill

Sensor → Agent（注入信息）：外部世界通过 Sensor 向 Agent 注入信息，Sensor 可接社交媒体等外部渠道。 Sensor → Agent (inject input): the outside world pushes information into the agent through a sensor, which can tap social channels and other external sources.
UI Plugin → Agent（注入指令）：用户通过 UI Plugin 向 Agent 注入指令。 UI Plugin → Agent (inject commands): the user sends commands into the agent through a UI plugin.
AgentLoop（引导 + 审批）：Agent 收到信息后，系统按 AgentLoop 的规定注入引导信息，并在必要节点进行审批与打回（如记忆归档检查）。 AgentLoop (guidance + approval): once the agent receives input, the system injects guidance as the loop declares, and triggers approvals or send-backs at key checkpoints (memory-archiving checks, for example).
原生工具：Agent 通过原生工具，可以发现和调用 Graph、MCP 工具、Skill，或是直接使用原生工具完成任务。 Native tools: through its native tools the agent discovers and calls graphs, MCP tools, and skills, or simply completes the task with those tools directly.

通用开发约定Conventions

命名一致性：安装标识（id / name）必须与文件夹名或文件名（去掉扩展名）严格一致，CI 会校验。 Naming: the install id must match the folder or file name exactly. CI checks it.
必填元数据：每个清单文件都要有英文 description 与中文 description-zh（AgentLoop 为 description / description-en）。 Metadata: every manifest carries both an English and a Chinese description (description-zh for plugins and graphs, description-en for agent loops).
热更新：安装/更新后一般无需重启——Sensor 走 /api/config/sensor/reload；UI 插件与 Graph/范式走内存热更新或前端 Ctrl+R。 Hot reload: installing or updating usually needs no restart. Sensors reload through /api/config/sensor/reload; UI plugins, graphs, and loops hot-swap from disk or with a Ctrl+R in the front end.