AgentPlaybooks

AgentPlaybooks

一本手册，适用于所有 Agent。 为 AI Agent 打造的便携式运行环境——将角色设定、技能、MCP 服务、项目指令和记忆整合到一个可信信息源中。

让 Agent 始终由你掌控。AgentPlaybooks 将技能、角色设定、MCP 服务、项目指令和记忆存储在一本便携式手册中，让你可以切换平台、同时使用多个平台，或自行托管，而不受供应商锁定。

你的 Agent 配置可在 Claude、ChatGPT、Cursor、Codex、Gemini、本地模型及未来平台之间保持同步。这本手册是便携式可信信息源，而不是某个特定供应商或编辑器。

它不是另一个技能商店或 MCP 注册表。技能和 MCP 连接都是手册的一部分；手册涵盖的是完整任务。对于拥有实体身体的 Agent 来说也是如此：技能可以包含演示，即按照机器人执行任务的顺序录制的记录。

亮点

剧本包含什么

• 角色设定：每个剧本 1 个，直接存储在剧本记录中
• 指令：始终生效的项目规则，即 AGENTS.md / CLAUDE.md 的内容
• 技能：采用 Agent Skills 格式的 SKILL.md 文档，前置元数据在每个客户端中都会保留
• 技能附件：随附的脚本、参考资料和模板，可通过 CLI 往返同步
• 演示：技能执行过程的录制内容，可来自 YouTube、固定 URL 或 LeRobot 数据集，并包含带时间戳的片段，供通过观察学习的 Agent 使用
• MCP 服务：采用 Model Context Protocol 格式的工具和资源
• 记忆：带标签和描述的键值存储，并提供原生 Hermes 记忆提供程序
• Hermes Tools 插件：连接剧本技能、MCP/OpenAPI 工具和凭据
• 画布：按版本管理的 Markdown 工作文档，限定在一次剧本运行中，让多个团队执行同一剧本，而无需共享工作成果

凭据，无需交出

• 密钥库：采用 AES-256-GCM，并为每位用户派生独立密钥。Agent 按名称引用密钥，平台在服务端注入密钥（use_secret），因此密钥值不会进入 Agent 的上下文。每个密钥还可选用主机允许列表，并设置强制执行的过期时间：密钥过期后，所有尝试使用它的路径都会拒绝请求。
• 联邦：其他 MCP 服务和 OpenAPI 服务可成为剧本上的工具，其凭据按名称从同一密钥库中解析
• 审计跟踪：记录每次联邦调用和每项密钥库操作，包括拒绝的请求

接入工具

• Claude：一个插件即可将账户中的所有剧本接入 claude.ai、Claude Desktop、Cowork、Claude Code 和移动端，通过 OAuth 登录，无需 API 密钥。也可以将单个剧本添加为自定义连接器。请参阅 AgentPlaybooks in Claude。
• Cursor 和 VS Code：为整个账户或单个剧本提供一键安装链接，可在每个剧本的 Integrations 标签页和 MCP 集成中找到。
• CLI + 可移植 Agent 插件：审查本地 Agent 配置，然后将一个剧本同步到 Claude Code、Cursor、ChatGPT/Codex、Google Antigravity、Grok Bot 和 Hermes
• Agent Plugins 1.0：安装项目插件，或将单个剧本导出为 plugin.json、mcp.json 和完整的 Agent Skills 目录。兼容的 MCP 宿主还可通过 MCP Skills 扩展发现托管的剧本技能。
• 私有的版本化中央备份与可安装的插件导出相互独立；软件包不包含密钥库中的密钥值。
• 发布：公共剧本的技能以纯 Markdown 格式通过 HTTP 发布于 /.well-known/skills/，可从 URL 安装，无需注册，也无需注册账号
• 导出格式：Agent Plugin ZIP、JSON、OpenAPI、MCP、Anthropic、Markdown

与他人协作

• API 密钥：基于角色的访问控制（Viewer、Coworker、Admin）
• 团队协作：通过一次性编辑者邀请协作，无需共享个人凭据或 Agent API 密钥
• 探索：实用案例、设置指南和精选的 AgentPlaybooks 入门内容
• 共享：公开或不公开剧本；在私有副本中保留项目上下文
• 主题：支持适配系统设置的 Light 和 Dark 模式

技术栈

类别	技术	用途
框架	Next.js 16 + React 19	App Router、SSR
样式	Tailwind CSS 4	实用优先的 CSS
动画	Framer Motion	UI 动画
图标	Lucide React	图标库
API	Hono	边缘 API 路由
数据库	Supabase	Postgres + Auth + RLS
i18n	next-intl	本地化（en、hu、de、es）
文档	public/docs 中的纯 Markdown	在客户端获取并渲染
托管	Cloudflare Workers	边缘部署
适配器	@opennextjs/cloudflare	在 Workers 上运行 Next.js

在线演示

• 网站：https://agentplaybooks.ai — 官方主域名；https://apbks.com 是用于链接的短域名
• 文档：https://agentplaybooks.ai/docs
• 发布分发清单：npm、MCP registry、插件商店、技能发现、Hermes memory 和验证
• GitHub：https://github.com/matebenyovszky/agentplaybooks

开始使用

先决条件

• Node.js 22+（package.json 中的 engines；CI 使用 22）
• npm 11+ — npm 10 会写入锁文件，但随后 npm ci 会拒绝执行
• Supabase 项目
• Cloudflare 账户（部署时可选）

安装

git clone https://github.com/matebenyovszky/agentplaybooks.git
cd agentplaybooks
npm install

入门模板

examples/ 下的可移植 playbook — persona、指令、 技能、MCP、记忆和保险库，均位于由你掌控的目录树中。小巧的 MIT 示例， 可供克隆或使用 cp -R 复制。不是市场。

入门模板	简介
coding-agent-baseline	编码 Agent playbook：指令、两个技能、安全的 MCP stub
doctor-drift-demo	带有主机文件夹漂移的审查 playbook；可移植存储始终是规范来源
skills-only-starter	最小 playbook：三个技能 + 指令；不含 MCP
cursor-hermes-starter	为 Cursor 和 Hermes 主机提供 persona、指令和技能的 playbook

安装到主机（可选先运行 doctor 检查，再运行 sync）：

npx @agentplaybooks/cli@latest doctor examples/coding-agent-baseline
npx @agentplaybooks/cli@latest sync examples/coding-agent-baseline --target=claude,cursor --apply

请参阅 examples/README.md、CLI 文档 和 Agent Plugins 规范。

环境变量

创建 .env.local 文件并添加：

NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_anon_key
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key

# Required for the secrets vault. 32 bytes as 64 hex characters:
#   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
# Losing it means losing every stored secret — no vault operation can decrypt
# without it, and rotating it invalidates everything already encrypted.
SECRETS_ENCRYPTION_KEY=

可选：

变量	作用
NEXT_PUBLIC_APP_URL	用于 canonical 标签、站点地图和 robots 的规范源站。默认值为 https://agentplaybooks.ai。
ALLOWED_ORIGINS	以逗号分隔的 CORS 允许列表。会完全替换托管环境的默认值 — 在可自托管实例上设置此项，以免信任项目自身的域名。
SECRETS_REQUIRE_ALLOWED_HOSTS	设为 true 时，密钥必须配置主机允许列表：未固定主机的密钥完全不能用于出站请求。

开发

npm run dev

打开 http://localhost:3000

Cloudflare 部署

npm run build:worker
npm run preview
npx wrangler deploy

CLI、ChatGPT/Codex 插件和 Claude Code 插件（packages/cli）

agentplaybooks doctor <project> 会审查本地 Agent 配置 （指令、Agent Skills、自定义 Agent、MCP 服务、可能硬编码的密钥、偏差），而 agentplaybooks sync <project> 会创建规范的 agentplaybook.json，以及启用的目标平台中缺失的平台文件： Claude Code、Cursor、ChatGPT/Codex、GitHub Copilot、Gemini CLI、Google Antigravity（.agents/skills）、Grok Bot（.agents/skills，它会与 AGENTS.md 一起原生发现这些文件），以及 Hermes Agent（在 ~/.hermes/config.yaml 中注册的 .agents/skills，以及该文件中的 mcp_servers: 和 SOUL.md）。 agentplaybooks plugin export|import 可往返转换 Agent Plugins 1.0 软件包； 唯一的清单扩展包含密钥引用和绑定，绝不包含密钥值。 login / playbooks / pull / push 使用用户 API 密钥将技能、MCP 服务和清单 与托管的 playbook 同步。push 还会创建私有、带版本的跨平台 AI Agent 配置备份， 其中包含完整的 Agent Skills 文件夹和可移植的自定义 Agent。backups 会列出修订版本；pull --snapshot 可恢复较早的版本。密钥值绝不会传输，只会传输 spec.secrets 中声明的引用。变更命令会先显示计划，并要求使用 --apply、--yes，或在支持时进行交互式确认。请参阅 packages/cli/README.md 和 备份与迁移指南。

同一软件包也是 ChatGPT/Codex 和 Cursor 插件（技能 + 账户 MCP）。 准确的 API 密钥设置和安装命令请参阅 packages/cli/README.md。

Claude 插件是一个独立、精简的文件夹 plugins/agentplaybooks：账户 MCP 连接器（OAuth，无需密钥）、可在聊天和 Cowork 中使用的 playbooks 技能，以及通过固定版本的 npx 运行已发布 CLI 的 doctor / sync 命令。它没有 bin/ 目录，因为 claude.ai 和 Cowork 会拒绝包含该目录的 插件。在 claude.ai 中，通过 Customize → Plugins → Add marketplace 添加 matebenyovszky/agentplaybooks，或在 Claude Code 中执行：

/plugin marketplace add matebenyovszky/agentplaybooks
/plugin install agentplaybooks@agentplaybooks

API 概览

公开和未列出的 playbook 访问权限

公开的 playbook 对所有人可见。未列出的 playbook 可通过 GUID 访问，但不会出现在搜索结果中。

GET /api/playbooks/:guid
GET /api/playbooks/:guid?format=openapi
GET /api/playbooks/:guid?format=mcp
GET /api/playbooks/:guid?format=anthropic
GET /api/playbooks/:guid?format=markdown

GET /api/playbooks/:id/personas
GET /api/playbooks/:id/skills
GET /api/playbooks/:guid/memory

注意：对于 persona 和技能，:id 同时支持 UUID 和 GUID。

已认证的 playbook CRUD（会话身份验证）

GET    /api/playbooks
POST   /api/playbooks
PUT    /api/playbooks/:id
DELETE /api/playbooks/:id

Persona（所有者或编辑者）

POST   /api/playbooks/:id/personas
PUT    /api/playbooks/:id/personas/:pid
DELETE /api/playbooks/:id/personas/:pid

技能（所有者或编辑者）

POST   /api/playbooks/:id/skills
PUT    /api/playbooks/:id/skills/:sid
DELETE /api/playbooks/:id/skills/:sid

记忆写入（API 密钥或所有者）

PUT    /api/playbooks/:guid/memory/:key
DELETE /api/playbooks/:guid/memory/:key

Canvas 工作文档

Canvas 文档属于相互隔离的工作流运行，因此多个团队可以执行同一个 playbook，而不共享工作成果。它们是长篇 Markdown 产物，Agent 可以随时间不断修订。持久事实和结构化状态应使用 memory；交付成果则应使用 canvas，例如 PR 审查、 研究报告、实施计划，或可逐段编辑的草稿。

GET    /api/playbooks/:guid/runs
POST   /api/playbooks/:guid/runs
GET    /api/playbooks/:guid/canvas?runId=:runId
POST   /api/playbooks/:guid/canvas
GET    /api/playbooks/:guid/canvas/:slug?runId=:runId
PUT    /api/playbooks/:guid/canvas/:slug?runId=:runId
PATCH  /api/playbooks/:guid/canvas/:slug?runId=:runId
DELETE /api/playbooks/:guid/canvas/:slug?runId=:runId

PUT 会替换文档字段，并要求提供 expectedVersion。PATCH 会执行增量 append、prepend 或精确的 replace 操作，同样要求提供 expectedVersion。版本过期时会返回 HTTP 409，防止两个 Agent 在不知情的情况下互相覆盖对方的工作。

curl -X PATCH 'https://your-domain.com/api/playbooks/abc123/canvas/pr-review?runId=RUN_UUID' \
  -H "Authorization: Bearer apb_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "replace",
    "search": "## Security review\nPending.",
    "content": "## Security review\nNo blocking issues found.",
    "expectedVersion": 3
  }'

Playbook API 密钥（仅所有者）

GET    /api/playbooks/:id/api-keys
POST   /api/playbooks/:id/api-keys
DELETE /api/playbooks/:id/api-keys/:kid

人类协作（会话身份验证；由所有者管理访问权限）

通过一次性链接邀请人类编辑者。他们可以编辑 playbook 内容，但只有所有者可以管理所有权控制权限。

GET    /api/playbooks/:id/collaborators
POST   /api/playbooks/:id/collaborators
DELETE /api/playbooks/:id/collaborators/:collaboratorId

GET    /api/collaboration-invites/:token
POST   /api/collaboration-invites/:token

邀请链接会在 72 小时后过期，且只能接受一次。完整的权限模型和安全说明请参阅团队协作。

Playbook 密钥（所有者或 API 密钥）

密钥使用 AES-256-GCM 加密。Agent 可以使用 use_secret MCP 工具或代理端点，在 HTTP 请求中使用密钥，而无需读取明文值。

GET    /api/playbooks/:guid/secrets          # List metadata only
POST   /api/playbooks/:guid/secrets          # Create encrypted secret
PUT    /api/playbooks/:guid/secrets/:name    # Update/rotate secret
DELETE /api/playbooks/:guid/secrets/:name    # Delete secret

# Dashboard only
GET    /api/playbooks/:guid/secrets/reveal/:name

# Proxy external requests using a secret
POST   /api/playbooks/:guid/secrets/proxy

# Audit trail — shared with federated MCP calls
GET    /api/playbooks/:guid/audit?operation=secret.

每次保险库操作都会被记录，包括拒绝操作：执行了什么操作、涉及哪个密钥、操作方是所有者还是哪个 API 密钥前缀；对于 secret.use，还会记录目标主机。记录不会包含密钥值、完整的出站 URL 或密钥。仅所有者可访问记录——Playbook API 密钥可以执行保险库操作，但无法读取这些操作的记录。

用户个人资料和用户 API 密钥（管理）

GET    /api/user/profile
PUT    /api/user/profile

GET    /api/user/api-keys
POST   /api/user/api-keys
DELETE /api/user/api-keys/:kid

公开发现和已保存的收藏

这些 API 支持公开读取、在仪表盘中发现技能/MCP，以及读取已有收藏。Explore 是一份由服务器渲染的用例指南，提供精选的第一方入门链接；它不会加载这些目录，也不会自动推荐公开 Playbook。

GET /api/public/playbooks
GET /api/public/skills
GET /api/public/skills/:id
GET /api/public/mcp
GET /api/public/mcp/:id

GET  /api/playbooks/:id/star
POST /api/playbooks/:id/star
GET  /api/user/starred

记忆回写（Playbook API 密钥或所有者）

GET    /api/playbooks/:guid/memory
PUT    /api/playbooks/:guid/memory/:key
DELETE /api/playbooks/:guid/memory/:key

MCP 端点

对于需要本地 stdio 进程的客户端，请参阅本地 MCP 传输。 它使用相同的账户工具和授权处理程序；协议发现无需凭据即可启动，而数据操作则需要配置你的实例。

GET  /api/mcp/:guid                    # MCP manifest
POST /api/mcp/:guid                    # MCP JSON-RPC
POST /api/mcp/:guid/tools/:tool        # Call one tool over plain HTTP

POST /api/mcp/manage                   # MCP management server (user API key)

GET    /api/mcp/config/:serverId       # Federated server config (owner)
POST   /api/mcp/config/:serverId
PUT    /api/mcp/config/:serverId
DELETE /api/mcp/config/:serverId
POST   /api/mcp/config/:serverId/test  # Try the connection before saving it

GET  /api/mcp-registry/search          # Search the public MCP registry
GET  /.well-known/mcp-registry-auth    # Registry ownership verification

Playbook 暴露的每个工具也都可以通过普通 HTTP 调用访问，因此无法使用 MCP 的客户端也能使用：

POST /api/playbooks/:guid/operations/:operation
POST /api/control/:operation           # Account-level operations

通过 HTTP 发布技能

技能以普通 Markdown 提供——包含一个索引以及每个技能各自的 SKILL.md，无需凭据，CORS 开放。任何客户端都可以通过基础 URL 安装，无需注册表，也无需注册账号。仅提供公开 Playbook；未列出和私有 Playbook 仍可通过 apb pull 访问。

GET /.well-known/skills/                    # Site-wide: every public playbook's skills
GET /playbooks/:guid/.well-known/skills/    # One playbook

hermes skills install well-known:https://agentplaybooks.ai/.well-known/skills/<name>

连接目录

GET /api/connections

用于连接联邦 MCP 服务或 OpenAPI 服务的精选模板。模板公开，因为模板不是凭据：每个条目只会按名称引用所需密钥，并从 Playbook 的保险库中解析这些密钥。

管理

GET  /api/manage/openapi.json
GET  /api/manage/playbooks
POST /api/manage/playbooks

健康检查

GET /api/health

API 密钥用法

Playbook API 密钥允许 Agent 读取和写入单个 Playbook 的记忆。

curl -X PUT https://your-domain.com/api/playbooks/abc123/memory/user_preferences \
  -H "Authorization: Bearer apb_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"value": {"theme": "dark"}}'

用户 API 密钥用于管理端点和 MCP 管理服务：

curl -X POST https://your-domain.com/api/mcp/manage \
  -H "Authorization: Bearer apb_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"list_playbooks","params":{}}'

项目结构

agentplaybooks/
  src/
    app/
      .well-known/skills/  # Public skill publishing (site-wide)
      api/
        _shared/           # auth.ts, guards.ts — where authorization lives
        [[...route]]/      # Hono catch-all for most endpoints
        mcp/               # MCP manifest, JSON-RPC, federation config
        playbooks/         # Per-playbook routes (secrets, canvas, audit, …)
      dashboard/           # Authenticated UI
      enterprise/          # Self-hosting landing page
      explore/             # Use cases, setup guidance, curated starters
      login/               # Auth pages
      page.tsx             # Marketing home
    components/
      playbook/            # Editor components
      ui/                  # UI primitives
    i18n/
      messages/            # Translation files (en, hu, de, es)
      request.ts           # Server-side locale resolution
    lib/
      mcp/                 # Federation, secret references
      storage/             # Storage adapters
      supabase/            # Supabase client and types
      crypto.ts            # Secrets vault encryption
  packages/
    cli/                   # AgentPlaybooks CLI + Codex/Cursor plugin
  plugins/
    agentplaybooks/        # Claude plugin (claude.ai, Cowork, Claude Code)
  .claude-plugin/          # Plugin marketplace manifest
  docs/                    # Contributor-facing notes
    security/              # Supplier-assessment pack (HU + EN)
  examples/                # Starter playbooks (fork/clone/sync)
  public/
    blog/  docs/           # Markdown served to the client
  schemas/                 # JSON schemas (agentplaybook.json, …)
  scripts/                 # Seed and build scripts
  supabase/
    migrations/            # Database migrations
  tests/                   # Vitest suites
  open-next.config.ts
  wrangler.jsonc

数据库架构

• playbooks：核心实体（包括可见性枚举：private、public、unlisted；用于 Agent 身份的角色字段，以及用于常驻项目规则的 instructions）
• secrets：保险库——AES-256-GCM 密文、每个密钥的主机允许列表、显示标记、轮换和使用情况统计
• audit_logs：所有者可读取的审计记录，用于记录联邦 MCP 调用和密钥保险库操作（secret.*）；绝不包含值、完整 URL 或密钥。由 mcp_proxy_audit_logs 重命名而来。
• skills：技能定义及可选的 SKILL.md 内容
• skill_attachments：技能的安全附件存储
• mcp_servers：MCP 工具和资源
• playbook_runs：可复用 Playbook 的隔离执行
• canvas：带版本的 Markdown 工作文档
• memories：键值记忆存储
• api_keys：带 RBAC 角色、限定于 Playbook 的 API 密钥
• user_api_keys：限定于用户的 API 密钥
• playbook_collaborators：已接受邀请的人类编辑成员，以及经哈希处理的一次性邀请
• profiles：公开的用户个人资料数据
• playbook_stars：已保存的 Playbook 收藏

这里有意不设第二个凭据存储。联邦 MCP 和 OpenAPI 服务过去会在 mcp_server_secrets 中各自存储加密密钥；该表已被删除（supabase/migrations/20260820_drop_mcp_server_secrets.sql），因为第二个存储意味着最值得窃取的凭据被放在更薄弱的保险箱中，且无法享有保险库已有的轮换、过期、使用情况统计和审计记录。现在，transport_config.auth.token_secret 用于指定一个保险库条目。

关于行级安全

上述表已启用 RLS，但它在运行时并非主要授权机制。几乎所有 API 路由都使用服务角色密钥进行查询，这会绕过 RLS；授权由应用代码强制执行（src/app/api/_shared/guards.ts）。

对于少数使用 anon 密钥读取公开 playbook 的端点，RLS 确实至关重要——MCP 清单（/api/mcp/:guid）、其工具路由，以及公开的技能/MCP 列表。这些端点依赖于 supabase/migrations/20260107_permissions_refactor.sql 中的 anon SELECT 策略。移除或禁用这些策略会导致端点无法运行，而不仅仅是放宽限制。

针对 auth.uid() 编写的策略目前不起作用，因为没有任何携带 JWT 的客户端会执行表查询——浏览器只会访问 /api/*，不会直接访问 Postgres。

安全

请私下报告漏洞——参阅 SECURITY.md。请勿针对安全缺陷创建公开 issue。

需要准备 NIS2 / 418/2024. 77. § 申报材料的可自托管运营者，可从事件处理手册开始 （HU）。发布版 SBOM 和 cosign verify 说明见 docs/security/supply-chain.md。

贡献

1. Fork 此仓库

2. 创建功能分支（git checkout -b feature/amazing-feature）

3. 按照与 CI 相同的顺序运行相同的检查：

   npm run lint                        # eslint
   npm run test:all                    # vitest + the CLI suite
   npm run prebuild && npx tsc --noEmit
   npm run audit:production
   npm run build
   

4. 提交更改并创建 Pull Request

首次提交 PR 前，有两点值得了解：

• 使用 npm 11 写入锁文件。 npm 10 生成的 package-lock.json 会被 npm ci 直接拒绝，因此 CI 会在安装阶段失败，尚未运行到你的更改。npx npm@11 install 在 Node 20 上也能正常运行。
• 警告可以接受，错误不行。 npm run lint 目前会报告一组已知的 react-hooks 和导航警告，这些问题已在 issues 中跟踪——运行干净意味着错误数为零，而不是没有任何输出。

许可证

MIT——参阅 LICENSE。

可将其用于任何用途，包括商业用途。请在副本或实质性部分中保留版权声明和许可声明。