内容
# 🐾 Paw
**自主托管的 AI 代理平台，用于运行 Barefoot Digital 的日常运营** — CRM 自动化、调度、研究和客户工作流程，已于 2025 年投入生产。
Paw 是专有、源代码开放的软件（参见 [LICENSE](LICENSE.md)）：我们相信证据胜过言辞，因此代码是公开的。它由 [Barefoot Digital](https://www.barefootdigital.dev) 构建和运营，Barefoot Digital 是一家 AI 采用咨询公司 — 我们向客户推荐的系统是我们自己运行的系统。
**功能：** 多提供商 LLM 支持、持久内存（混合向量 + 全文搜索）、沙盒化技能/插件系统、多传输 MCP 客户端、定时作业、加密凭证库、白标品牌套件和具有 Web UI 的操作控制台。
**状态：** 活跃，生产就绪。目前不接受外部贡献。
> 对此类系统在您的公司中能做什么感兴趣？这正是我们的业务：[barefootdigital.dev/audit](https://www.barefootdigital.dev/audit)
## 信任与自主
Paw 构建为安全可靠的运行**无人值守**。三层机制确保其诚实：
- **目标账本 + 证据门控** (`/tasks`) — 工作以看板卡片跟踪，任务**必须有证据才能标记为完成**（重新查询、差异、URL）。没有沉默的“我做到了。”
- **运行判决** (`/runs`) — 每次运行后，Paw 会根据自己的工具日志进行评分，并标记“声称成功，实际无工作”。
- **批准-牵引 + 批准后执行** — 具有副作用的操作会等待人类批准；批准后，Paw 会运行**确切**的批准操作并记录结果。提出 → 您批准 → 它继续。
总结：Paw 不能默默地错误报告自己的工作，每次运行都会显示以供验证，人类会批准每次有影响的操作。
## 快速入门
```bash
# 安装依赖
bun install
# 交互式设置（配置提供商 + 凭证）
bun run bin/paw.ts init
# 启动
bun start
# 开发模式（自动重新加载）
bun run dev
```
## 功能
- **目标账本 + 看板** (`/tasks`) — 工作以看板卡片跟踪；任务必须有证据才能达到*完成*状态。Cron 运行显示为同一看板上的持久卡片。
- **运行判决** (`/runs`) — 每次运行都会根据自己的工具日志进行评分，并在声称成功但无实际工作时标记（幻成功检测）。
- **批准-牵引** — 具有副作用的操作会等待人类批准；批准后，Paw 会重新运行**确切**的批准操作并记录结果（执行-批准）。
- **多提供商 AI** — Claude、OpenAI、Ollama、Gemini。通过配置切换提供商。可选的视觉路由将带有图像的回合发送到配置的视觉模型。
- **内存系统** — 混合向量 + 全文搜索。自动从对话中提取事实。跨会话持久化。
- **技能生态系统** — 工具分组为技能，按需加载，减少令牌使用。通过 `/skills` Web UI 管理。
- **插件架构** — 内置 Slack 和 Web Pilot（Playwright）插件。从 `plugins/` 目录进行插件发现。`skill_scaffold` 工具生成新的（惰性，审查后重启）插件。
- **原生集成** — 一流的、具有凭证库的集成，开箱即用：GitHub（应用）、Strapi、HubSpot、Supabase、WordPress、n8n。
- **MCP 支持** — 通过 stdio、SSE 或 HTTP 传输（承载者/头部身份验证，JSON 粘贴导入）连接外部工具服务器。在 `/mcp` 管理。
- **Cron 调度器** — 在 cron 表达式上调度提示、工具调用或事件。
- **实时画布** — 代理驱动的视觉工作区，具有实时预览 iframe；以及带有每空间 CSP 的 auth `apps/<space>/` 生产应用表面。在 `/chat` 中切换画布模式。
- **聊天** — 所有文件类型的附件（PDF 文本提取、内联预览）和浏览器语音（语音转文本/文本转语音）。
- **品牌套件** — 一个品牌配置文件库（一个活动），对代理、画布输出和整个控制台进行白标。
- **凭证库** — 加密的、Web 管理的秘密（AES-256-GCM）；在服务器端解析，永远不会暴露给模型。
- **代理操作控制台** — `/` 仪表盘：实时操作提要（流 + 群集镜头，覆盖实时工具流）带有飞行中跟踪和会话归属。
- **Web UI** — 代理操作仪表盘、聊天 + 画布、内存浏览器、会话历史、配置编辑器、品牌/凭证/GitHub 管理以及技能/cron/MCP 管理。
- **安全** — 分级速率限制、用户允许列表/阻止列表、配对代码批准、可选 TOTP 2FA、沙盒化工具执行和不受信任的工具结果框架（外部工具输出被限制为数据，永远不是指令）。
## 配置
Paw 从多个来源加载配置（优先级最高优先）：
1. 运行时覆盖
2. `~/.paw/config.json`（通过 Web UI 或 CLI 保存）
3. 环境变量
4. 凭证存储 (`bun run bin/paw.ts auth login`)
5. 内置默认值
### 环境变量
```bash
# AI 提供商（claude, ollama, openai, gemini）
PAW_PROVIDER=claude
ANTHROPIC_API_KEY=sk-ant-...
# Ollama
PAW_OLLAMA_BASE_URL=http://localhost:11434
PAW_OLLAMA_MODEL=llama3.1
# OpenAI
OPENAI_API_KEY=sk-...
PAW_OPENAI_MODEL=gpt-4o
# Gemini
GEMINI_API_KEY=...
PAW_GEMINI_MODEL=gemini-2.0-flash
# Web UI
PAW_WEB_ENABLED=true
PAW_WEB_PORT=3000
# Slack
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...
SLACK_SIGNING_SECRET=...
# 日志记录
PAW_LOG_LEVEL=info
# 访问控制 — 持久所有者/允许/阻止 ID（逗号或空格分隔）。
# 与大多数 PAW_* 变量（config.json 覆盖）不同，这些变量在
# 文件合并后应用，因此在启动时识别环境变量化的所有者
# 不依赖 config.json 或 DB 状态 — 免疫 config writer。所有者
# ID 无需批准用户行或配对代码。
PAW_SECURITY_OWNER_USER_IDS=U0XXXXXXXXX
PAW_SECURITY_ALLOWED_USERS=
PAW_SECURITY_BLOCKED_USERS=
```
> **注意优先级：** 环境变量通常位于 `config.json` **以下**
> 在级联中，但 infra 路径 (`PAW_DB_PATH`, `PAW_CANVAS_ROOT`) 和 `PAW_SECURITY_*`
> ID 列表在文件合并**后**应用，因此过时或清除的
> `config.json` 不能遮蔽它们。安全列表 **联合** （从不替换）
> 已经识别的 config/DB。
### 配置文件
Web UI 配置页面写入 `~/.paw/config.json`。架构中的任何键都可以覆盖：
```json
{
"provider": "claude",
"ai": { "model": "claude-sonnet-4-5-20250929", "maxTokens": 4096 },
"agent": { "name": "Paw", "systemPrompt": "You are a marketing assistant." },
"web": { "enabled": true, "port": 3000 },
"memory": { "enabled": true, "autoExtract": true },
"skills": {
"slack": { "alwaysActive": true }
}
}
```
## Web UI
使用 `PAW_WEB_ENABLED=true` （或在配置中设置）启动。默认：`http://127.0.0.1:3000`
| 页面 | 路径 | 描述 |
|------|------|-------------|
| 代理操作 | `/` | 实时操作提要（流 + 群集镜头），飞行中跟踪，会话归属 |
| 聊天 | `/chat` | 交互式聊天，带有会话持久性；切换画布模式以获取实时视觉工作区 |
| 任务 | `/tasks` | 目标账本看板；工作仅在有证据时才推进 |
| 运行 | `/runs` | 按运行判决（幻成功检测） |
| 内存 | `/memory` | 浏览、搜索和管理存储的内存 |
| 会话 | `/sessions` | 查看过去的对话会话 |
| 技能 | `/skills` | 查看/切换/编辑技能组及其工具 |
| Cron | `/cron` | 创建和管理定时作业 |
| MCP | `/mcp` | 连接和管理 MCP 工具服务器 |
| 品牌 | `/brand` | 管理品牌配置文件并激活白标主题 |
| 凭证库 | `/vault` | 存储和轮换加密凭证 |
| GitHub | `/github` | GitHub 应用状态，PR，批准 inbox，活动提要 |
| 提交 | `/submissions` | 画布表单提交的持久 inbox |
| 配置 | `/config` | 实时编辑所有配置 |
可选 HTTP 基本身份验证：在配置中设置 `web.password`。
## 技能
工具根据其源插件自动分组为技能。只有始终激活的技能（默认为内存）才会随每个 AI 请求发送。其他技能仅在 AI 调用 `activate_skill` 时按需加载。
这将输入令牌从 ~15-25k 减少到 ~1k 每请求。
在 Web UI 中 `/skills` 管理技能：切换始终激活，编辑描述，查看工具列表。
## 画布
实时画布（在 `/chat` 中切换画布模式）是一个分窗工作区，AI 在其中生成 HTML/CSS/JS，结果在实时预览 iframe 中渲染。
- **工作原理** — 发送提示（例如“为汽车经销商创建一个着陆页”），AI 使用 `canvas_write` 在 `./data/canvas/` 中创建文件，预览自动刷新。
- **持久性** — 画布文件在服务器重启时存活。使用工具栏中的垃圾箱图标清除所有文件并重新开始。
- **工具** — `canvas_write`, `canvas_read`, `canvas_list` — 沙盒化到画布根目录。
- **配置** — `web.canvas.enabled` （默认：true），`web.canvas.root` （默认：`./data/canvas` ）。
## 插件
内置插件位于 `plugins/`：
- **slack** — 通过 Socket Mode 的 Slack 集成。发布消息和反应。
- **web-pilot** — 使用 Playwright 的浏览器自动化。导航、点击、填写表单、截图。
插件通过 `manifest.json` 注册工具并声明权限。内核强制执行沙盒化执行。
### MCP 服务器
在配置中添加外部工具服务器：
```json
{
"mcpServers": {
"n8n": {
"command": "npx",
"args": ["-y", "@n8n/mcp-server"],
"transport": "stdio"
}
}
}
```
## CLI 命令
```bash
bun run bin/paw.ts init # 交互式设置
bun run bin/paw.ts start # 启动内核
bun run bin/paw.ts auth login # 配置凭证
bun run bin/paw.ts auth status # 检查身份验证状态
bun run bin/paw.ts config # 显示当前配置
bun run bin/paw.ts status # 插件健康检查
bun run bin/paw.ts cron list # 列出 cron 作业
bun run bin/paw.ts cron add # 添加 cron 作业
bun run bin/paw.ts cron remove # 删除 cron 作业
```
## 开发
```bash
bun test # 运行测试
bun run dev # 启动并自动重新加载
bun run lint # 使用 Biome 检查
bun run format # 使用 Biome 格式化
```
## 架构
```
bin/paw.ts CLI 入口点
src/
kernel/ 内核，事件总线，沙盒，插件加载器
ai/ 提供商（Claude，OpenAI，Ollama，Gemini），工具注册表，技能
memory/ 向量 + FTS 内存存储，自动提取
store/ SQLite 数据库，会话，消息，代理工作账本
observability/ 运行判决（幻成功检测），工具日志，日志记录
config/ 模式验证（Zod），配置加载器/写入器
auth/ 每个提供商的凭证存储
cron/ 带有表达式解析器的 cron 调度器
heartbeat/ 系统健康监测
security/ 访问控制，速率限制，不受信任的工具结果框架
mcp/ MCP 客户端管理器（stdio，SSE，HTTP）
web/ Hono Web 服务器，JSX 视图，REST API
tools/ 内置文件，exec 和画布工具
types/ TypeScript 接口
plugins/
slack/ Slack 频道插件
web-pilot/ Playwright 浏览器插件
tests/ 测试套件（Bun 测试运行器）
```
## 要求
- [Bun](https://bun.sh) v1.0+
- AI 提供商 API 密钥（Anthropic、OpenAI 或 Gemini）或本地 Ollama 实例
## 许可证
Paw 是专有、源代码开放的软件 — © Astral Events Miami LLC d/b/a Barefoot Digital，所有权利保留。源代码公开用于透明度、评估和教育阅读；不授予使用、部署或重新分发权限。有关完整条款，请参见 [LICENSE.md](./LICENSE.md)。
商务许可、合作伙伴或部署查询：info@barefootdigital.dev · [barefootdigital.dev](https://www.barefootdigital.dev)
