配置说明

系统的所有配置文件统一存放在用户主目录的 ~/.purrcat/ 文件夹下。首次启动时系统会自动生成默认模板，无需手动初始化；也可以在前端界面编辑后保存。

所有配置文件均为 JSON 格式，编辑后保存即可生效（部分配置需重启）。

目录结构

~/.purrcat/
├── model.json               # 模型 API Key 与速率限制
├── activate_sensor.json     # 传感器激活配置（默认空，市场安装后自动写入）
├── file.json                # 文件系统权限模型
├── mcp_config.json          # MCP 服务器扩展配置
├── app_config.json          # 应用快捷配置
├── settings.json            # 全局设置（data_root 等）
└── core/
    ├── MEMORY.md            # 核心通用记忆（用户画像/工作经验）
    ├── SOUL.md              # Agent 人格定义（灵魂注入）
    ├── GOAL.md              # 待办目标（心跳注入驱动）
    ├── PARADIGM.yaml        # Agent 执行范式（触发器/钩子/工具检查）
    ├── cron.json            # 定时任务列表
    ├── heartbeat.json       # 心跳配置（间隔/开关）
    └── info.json            # 已安装技能/工作坊索引

1. 模型配置 (`model.json`)

配置模型 API Key、Base URL、速率限制等。

json

{
  "embedding": "embedding",
  "main": {
    "openai:deepseek-v4-flash": {
      "api_keys": ["sk-your-first-api-key-here"],
      "base_url": "https://api.deepseek.com",
      "description": "LLM worker",
      "rpm": 60,
      "tpm": 1000000,
      "concurrency": 3,
      "max_token": 500000
    }
  },
  "task": {},
  "vision": {}
}

字段说明

字段	说明
`embedding`	嵌入模型路径或 HuggingFace 模型名，默认读取本地 `embedding/` 文件夹
`main`	全局 Agent 使用的主模型。键名为 `{适配器}:{模型名}` 格式
`task`	后台子任务使用的模型（可选，为空则复用 `main`）
`vision`	多模态视觉模型配置（可选，为空则不启用）
`api_keys`	列表，支持填入多个 Key，系统自动选择最空闲的 Key 调度
`rpm` / `tpm`	每分钟请求数 / Token 上限
`concurrency`	最大并发数
`max_token`	记忆窗口 Token 上限

多 Key 负载均衡

api_keys 列表支持多个 Key，系统通过 APIKeyManager 自动选择当前最空闲的 Key。

2. 传感器激活配置 (`activate_sensor.json`)

定义哪些传感器被激活及其运行参数。PurrCat 采用配置即安装的拓展模式：传感器脚本默认不预装，通过 UI 市场的「传感器」页一键安装后自动写入此文件；也可手动添加配置，系统启动时若发现本地缺失对应脚本，会自动从云端（GitHub）拉取并运行。所有传感器默认关闭，需将 enabled 设为 true 才能激活。

json

{
  "feishu_bot": {
    "enabled": false,
    "env": {
      "FEISHU_APP_ID": "",
      "FEISHU_APP_SECRET": "",
      "FEISHU_CHAT_ID": ""
    },
    "capabilities": { "observe": true, "express": true }
  },
  "system_clock": {
    "enabled": true,
    "env": {
      "INTERVAL": "1800",
      "CRON_FILE": ".purrcat/core/cron.json"
    },
    "capabilities": { "observe": true, "express": false }
  },
  "rss_watcher": {
    "enabled": false,
    "env": {
      "INTERVAL": "1800",
      "RSS_SUBSCRIPTIONS_JSON": "[{\"name\":\"Lilian Weng's Blog\",\"rss_url\":\"https://lilianweng.github.io/lil-log/feed.xml\"}]"
    },
    "capabilities": { "observe": true, "express": false }
  },
  "audio_assistant": {
    "enabled": false,
    "env": {
      "WHISPER_MODEL": "small",
      "LANGUAGE": "zh",
      "TTS_RATE": "150",
      "TTS_VOLUME": "1.0"
    },
    "capabilities": { "observe": true, "express": true }
  }
}

传感器列表

配置键名	传感器	类型	功能
`feishu_bot`	飞书机器人	message	双向 Markdown 卡片通讯
`system_clock`	系统时钟	system	cron 定时闹钟轮询（心跳见 `core/heartbeat.json`）
`rss_watcher`	RSS 订阅	subscribe	定时抓取博客文章更新，订阅源通过 `RSS_SUBSCRIPTIONS_JSON` 传入
`audio_assistant`	语音助手	system	环境语音监听（Whisper + TTS）

每个传感器通过独立子进程运行，由 manager.py 统一管理，崩溃互不影响。

3. 文件系统配置 (`file.json`)

定义 Agent 在宿主机上的文件操作权限边界，采用三级权限模型：

json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$comment": "PurrCat File System Configuration File",
  "default_permission": "readonly",
  "permissions": {
    "blocked": [
      ".git",
      "src",
      "node_modules",
      "miniconda3",
      ".env",
      ".purrcat"
    ],
    "readonly": [],
    "writable": [
      "./agent_vm",
      "./exports",
      "skills",
      "D:/test"
    ]
  }
}

字段说明

字段	说明
`default_permission`	默认权限：`readonly`（只读）或 `writable`（可写）
`permissions.blocked`	隐私黑名单。禁止读取/导入的目录，保护敏感文件
`permissions.readonly`	只读白名单。Agent 可读但不可修改的目录/文件
`permissions.writable`	读写白名单。Agent 可自由读写的目录/文件

权限判断优先级：blocked > readonly > default_permission。若路径不在任何白名单中，则按 default_permission 处理。

4. MCP 扩展配置 (`mcp_config.json`)

配置 Model Context Protocol (MCP) 服务器扩展：

json

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "" }
    },
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    },
    "tradingview": {
      "command": "uvx",
      "args": ["--from", "tradingview-mcp-server", "tradingview-mcp"]
    }
  }
}

系统启动时自动拉取所有 MCP Server 的工具 Schema 并缓存。支持自定义 MCP Server（Python 脚本 / npx 包），配置后即时生效。

5. 应用快捷配置 (`app_config.json`)

为 Agent 的 ComputerUse 工具提供「一键启动」应用的白名单映射，格式为键值对：

json

{
  "微信": "D:\\\\Path\\\\to\\\\WeChat.exe",
  "GitHub": "https://github.com"
}

当 Agent 调用 ComputerUse 的 launch_app 动作时，会查询此映射表。value 支持三种格式：

格式	说明	示例
URL	在默认浏览器中打开	`"https://github.com"`
可执行文件路径	直接启动本地程序	`"D:\\\\Program Files\\\\App\\\\app.exe"`
协议 URL	通过系统协议启动应用	`"obsidian://open?vault=notes"`

6. 核心文件 (`.purrcat/core/`)

文件	用途	说明
`MEMORY.md`	系统级记忆档案	固化用户画像与工作经验，会话启动时注入 System Prompt
`SOUL.md`	Agent 人格定义	定义性格、语气、价值观，从根本上决定 Agent 行为基调
`GOAL.md`	待办目标	记录 Agent 的当前目标与待办，由心跳机制周期性注入；为空时注入兜底提示
`PARADIGM.yaml`	执行范式	声明式定义触发器、生命周期钩子、工具使用检查与循环退出条件
`cron.json`	定时任务	由系统时钟传感器轮询，触发定时唤醒
`heartbeat.json`	心跳配置	空闲时按间隔自动唤醒 Agent（interval / active）
`info.json`	安装索引	记录已安装的技能包与工作坊清单

PARADIGM.yaml：声明式执行范式

~/.purrcat/core/PARADIGM.yaml 以近乎自然语言的规则声明式定义 Agent 主循环的执行行为，修改后重启即可生效，无需改动任何核心代码：

yaml

name: "default"
description: "default system loop"
loop_end_max_retry: 3          # 主循环最大重试次数（防死循环）
trigger:                       # 定时触发器：到点自动唤醒并注入内容
  - cron:
      time: "08:08"
      injection: "【Demo】闹钟响了"
hooks:                         # 生命周期钩子：在关键节点挂载动作
  on_build_system_prompt:      # 构建 System Prompt 时
    - file_operation:
        path: "@RULES"
        action: "read"
  on_loop_end:                 # 循环结束前
    - tool_use_check:          # 工具使用检查：未达标则注入提醒
        name: "Memo"
        parameter_check:
          - action: "add"
        failed_prompt: "检查到本轮对话你未调用 Memo 工具进行记忆总结"

关键字段：

字段	说明
`trigger`	cron 定时触发与注入内容，让 Agent 到点自动被唤醒
`hooks.on_build_system_prompt`	构建提示词时挂载文件读取、记忆注入等
`hooks.on_loop_start` / `on_loop_epoch`	循环开始/每轮迭代时的提示注入
`hooks.on_loop_end`	循环退出前的检查（如强制归档记忆）
`hooks.on_tool_calling`	工具调用时的检查与提示
`loop_end_max_retry`	主循环退出条件（最大重试次数）

@符号 可引用系统文件（如 @RULES、@SOUL、@MEMORY），默认模板位于源码 src/agent/system_rules/PARADIGM.yaml。

7. CLI 命令参考

命令	用途	示例
`purrcat setup`	一键部署（沙盒构建 + Python 依赖安装 + 嵌入模型）	`purrcat setup`
`purrcat install`	安装扩展（skill / graph / mcp / sensor）	`purrcat install mcp tradingview`
`purrcat help`	显示帮助菜单（含 ASCII 猫猫 Logo）	`purrcat help`

启动 PurrCat 请使用：Electron 桌面端 npm run dev；Web UI uv run python main.py --api --headless。配置文件由系统首次启动时自动生成，无需 CLI 初始化。

扩展安装详解

bash

# 安装社区 Skill（任意 GitHub 仓库的子目录）
purrcat install skill https://github.com/user/repo/tree/main/path/to/skill

# 从官方 Registry 安装 MCP 服务器
purrcat install mcp tradingview

# 安装传感器
purrcat install sensor feishu_bot

# 安装官方 Graph（自动解析其 MCP/Skill 依赖）
purrcat install graph daily_summary

版本更新

bash

# 拉取最新代码并同步依赖
git pull
uv sync

# 如需安装指定版本
git checkout <tag>
uv sync

辅助配置

容器引擎

purrcat setup 会自动检测 Docker 引擎（当前版本仅支持 Docker，不再兼容 Podman），引擎偏好保存至 ~/.purrcat/settings.json。

前端界面（Electron 桌面端 / Web UI）

purrcat setup 可选安装前端依赖（npm install），用于构建 Electron 桌面端或 Web UI 界面。

Electron 桌面端（推荐）：

bash

npm install                 # 根目录依赖（Electron 等）
npm install --prefix ui     # 前端依赖
npm run dev                 # 一键拉起 后端 + 前端 + Electron 桌面窗口

Web UI（轻量，无桌面端）：

bash

npm install --prefix ui
npm run build:ui                            # 构建前端静态文件
uv run python main.py --api --headless      # 浏览器打开 http://localhost:8000

配置说明 ​

目录结构 ​

1. 模型配置 (model.json) ​

字段说明 ​

多 Key 负载均衡 ​

2. 传感器激活配置 (activate_sensor.json) ​

传感器列表 ​

3. 文件系统配置 (file.json) ​

字段说明 ​

4. MCP 扩展配置 (mcp_config.json) ​

5. 应用快捷配置 (app_config.json) ​

6. 核心文件 (.purrcat/core/) ​

PARADIGM.yaml：声明式执行范式 ​

7. CLI 命令参考 ​

扩展安装详解 ​

版本更新 ​

辅助配置 ​

容器引擎 ​

前端界面（Electron 桌面端 / Web UI） ​

配置说明

目录结构

1. 模型配置 (`model.json`)

字段说明

多 Key 负载均衡

2. 传感器激活配置 (`activate_sensor.json`)

传感器列表

3. 文件系统配置 (`file.json`)

字段说明

4. MCP 扩展配置 (`mcp_config.json`)

5. 应用快捷配置 (`app_config.json`)

6. 核心文件 (`.purrcat/core/`)

PARADIGM.yaml：声明式执行范式

7. CLI 命令参考

扩展安装详解

版本更新

辅助配置

容器引擎

前端界面（Electron 桌面端 / Web UI）