一、项目定位
Paperclip 是一个 AI Agent 公司的运营控制平面（Control Plane）。
用一句话概括：如果 OpenClaw/Claude Code 是"员工"，Paperclip 就是"公司"。
它不是 Agent 框架，不是聊天机器人，不是工作流引擎——它是一个让你像管理公司一样管理一组 AI Agent 的操作系统：组织架构、任务分配、预算控制、审批治理、成本追踪，全部在一个 Dashboard 里完成。
二、解决什么问题
痛点 | Paperclip 的解法 |
|---|---|
20 个 Claude Code 终端同时开，分不清谁在干什么 | 任务工单化，会话线程化，跨重启持久化 |
手动拼凑上下文提醒 Agent 做什么 | 上下文从任务→项目→公司目标自动向上流动 |
Agent 配置散落各处，重复造轮子 | 组织架构、工单、委派、治理开箱即用 |
Agent 跑飞了，几百美元 token 费用没了 | 成本追踪 + 预算硬止损 + 超支自动暂停 |
定期任务要手动触发 | Heartbeat 定时唤醒 + 定例调度 |
没有审批，Agent 直接上线 | 审批门控 + 治理流程 + 变更审计 |
三、四大支柱
支柱 | 服务对象 | 覆盖范围 |
|---|---|---|
| Agentic Task Manager — 声明意图，Agent 执行，你验收 | 所有人，日常使用 | 任务、审批与评审门控 · 主动 Agent 协作 · 可审计的例行工作流 · 通过 diff/截图/测试验证产出 |
| Org Chart for Agents — 角色、权限与边界 | 管理者 | 人+Agent 混合组织架构 · 职责划分与委派 · 治理：谁能做什么 · 限定范围的密钥与公司边界 |
| Agent Employee Training — 设计、训练与评估 AI 员工 | 赋能者 | Skill Studio 与组织级共享技能 · 评估与测试运行 · 主动学习循环与质量指标 · Agent 绩效评审 |
| Agentic OS — 让工作运转的基础设施 | IT 与平台 | 跨 Provider 运行时 · 沙箱、集成与 MCP 服务器 · SSO/GRC/RBAC 与成本控制 · 数据隐私与追溯 |
四、技术架构
4.1 技术栈
层 | 技术 |
|---|---|
后端 | Node.js + Express + TypeScript |
数据库 | Drizzle ORM + PostgreSQL（开发用嵌入式 PGlite） |
前端 | React 19 + Vite + Tailwind v4（CSS 自定义属性 Token 体系） |
测试 | Vitest（单元）+ Playwright（E2E）+ Storybook（视觉回归） |
包管理 | pnpm monorepo |
部署 | Docker / 本地自托管 |
4.2 Monorepo 结构
paperclip-master/ ├── server/ # Express REST API + 编排服务 │ └── src/routes/ # 58 个路由模块（agents, issues, goals, costs...） ├── ui/ # React + Vite 前端 │ └── src/pages/ # 133 个页面组件 ├── packages/ │ ├── db/ # Drizzle schema + 迁移（111 张表） │ ├── shared/ # 共享类型、常量、校验器 │ ├── adapters/ # Agent 适配器实现 │ │ ├── claude-local/ # Claude Code 本地适配 │ │ ├── codex-local/ # Codex 本地适配 │ │ ├── cursor-local/ # Cursor 本地适配 │ │ ├── cursor-cloud/ # Cursor 云端适配 │ │ ├── gemini-local/ # Gemini 本地适配 │ │ ├── grok-local/ # Grok 本地适配 │ │ ├── hermes/ # Hermes 适配 │ │ ├── hermes-gateway/ # Hermes Gateway 适配 │ │ ├── openclaw-gateway/# OpenClaw Gateway 适配 │ │ ├── opencode-local/ # OpenCode 本地适配 │ │ └── pi-local/ # Pi 本地适配 │ ├── adapter-utils/ # 适配器共享工具 │ ├── plugins/ # 插件系统 │ ├── skills-catalog/ # 应用内置技能目录 │ └── teams-catalog/ # 应用内置团队目录 ├── cli/ # paperclipai CLI 包 ├── skills/ # 运行时/运维技能 ├── .agents/skills/ # 20 个 Agent 技能 └── doc/ # 产品与运维文档4.3 代码规模
指标 | 数值 |
|---|---|
TypeScript 源文件 | 1,333 个（不含 node_modules） |
总代码行数 | ~111 万行 |
数据库表 | 111 张 |
API 路由模块 | 58 个 |
UI 页面组件 | 133 个 |
Agent 适配器 | 11 种 |
内置 Agent 技能 | 20 个 |
五、核心系统详解
5.1 十二大子系统
系统 | 职责 |
|---|---|
| Identity & Access | 双模式部署（可信本地/认证模式）、Board 用户、Agent API Key、短期运行 JWT、公司成员、邀请流 |
| Org Chart & Agents | Agent 角色/职级/汇报线/权限/预算，适配多种 Agent 运行时 |
| Work & Task System | 任务带公司/项目/目标/父级链接，原子 checkout + 执行锁，阻塞依赖，评论/文档/附件/工作产出 |
| Heartbeat Execution | 数据库唤醒队列 + 合并，预算检查，工作空间解析，密钥注入，技能加载，适配器调用，孤立运行自动恢复 |
| Workspaces & Runtime | 项目工作空间，隔离执行空间（git worktree），运行时服务（dev server、preview URL） |
| Governance & Approvals | Board 审批流，执行策略 + 审批阶段，决策追踪，预算硬止损，Agent 暂停/恢复/终止 |
| Budget & Cost Control | 按公司/Agent/项目/目标/任务/Provider/模型追踪 Token 和成本，告警阈值 + 硬止损，超支自动暂停 |
| Routines & Schedules | Cron/Webhook/API 触发的定例任务，并发与补赶策略，每次执行创建追踪任务并唤醒 Agent |
| Plugins | 实例级插件系统，进程外 Worker，能力门控宿主服务，Job 调度，工具暴露，UI 贡献 |
| Secrets & Storage | 实例和公司密钥，加密本地存储，Provider 对象存储，敏感值不出现在 Prompt 中除非明确需要 |
| Activity & Events | 变更操作、Heartbeat 状态变化、成本事件、审批、评论、工作产出全部记录为持久化活动 |
| Company Portability | 导入/导出整个组织（Agent、技能、项目、定例、任务），密钥脱敏，冲突处理 |
5.2 Agent 适配器体系
Paperclip 的核心设计理念是"Bring Your Own Agent"——任何能接收 Heartbeat 的 Agent 都可以被雇佣：
Agent 适配器架构 ┌─────────────────────────────────────────────┐ │ Paperclip Server │ │ │ │ 统一适配器接口 │ │ ├── heartbeat() ← 定时唤醒 │ │ ├── assignTask() ← 分配任务 │ │ ├── checkStatus() ← 检查状态 │ │ └── collectResult() ← 收集结果 │ │ │ └──────────┬──────────────────────────────────┘ │ ┌─────┴─────┬──────────┬──────────┬──────────┐ │ │ │ │ │ ┌───┴───┐ ┌───┴───┐ ┌──┴───┐ ┌──┴───┐ ┌──┴───┐ │Claude │ │Codex │ │Cursor│ │Gemini│ │OpenClaw│ │Code │ │ │ │ │ │ │ │ │ └───────┘ └───────┘ └──────┘ └──────┘ └───────┘ 本地CLI 本地CLI 本地/云 本地CLI Gateway5.3 Heartbeat 机制
Heartbeat 是 Paperclip 的核心调度模式：
数据库维护唤醒队列，按调度时间排序
到时间后唤醒 Agent，合并同一 Agent 的多个唤醒请求
检查预算 → 解析工作空间 → 注入密钥 → 加载技能 → 调用适配器
运行产生结构化日志、成本事件、会话状态、审计轨迹
孤立运行（crash 后无人认领）自动恢复
六、设计理念
6.1 核心设计原则
- 原子执行
：任务 checkout 和预算执行是原子的，不会重复工作，不会失控花费
- 持久化 Agent 状态
：Agent 跨 Heartbeat 恢复同一任务上下文，而非从头开始
- 运行时技能注入
：Agent 可以在运行时学习 Paperclip 工作流和项目上下文，无需重训练
- 治理与回滚
：审批门控强制执行，配置变更有版本，坏变更可以安全回滚
- 目标感知执行
：任务携带完整目标链，Agent 始终看到"为什么"，而不仅是标题
- 可移植公司模板
：导入/导出组织、Agent、技能，密钥脱敏，冲突处理
- 真正的多公司隔离
：每个实体都限定在公司范围内，一个部署可运行多个公司
6.2 UI 设计系统
- Token-only 规则
：所有颜色、间距、圆角、字号、阴影、动效值来自
ui/src/index.css的 Token 层 - 三层 Token 体系
：语义层（shadcn 核心）→ 品牌层（Agent 渐变/状态色）→ 领域层（匹配芯片/标注高亮）
- 操作面板定位
：每个屏幕回答三个问题：发生了什么？需要我吗？我该做什么？密度服务于扫描，而非美学
- Lint 门控
：
check-token-gates脚本在提交前拒绝任何硬编码值
七、与同类项目对比
维度 | Paperclip | OpenClaw | Claude Code | Cursor |
|---|---|---|---|---|
定位 | Agent 公司运营控制平面 | AI 编码 Agent | AI 编码 Agent | AI 编码 IDE |
类比 | 公司 | 员工 | 员工 | 工位 |
管理多个 Agent | ✅ 核心能力 | ❌ 单 Agent | ❌ 单会话 | ❌ 单窗口 |
组织架构 | ✅ 原生支持 | ❌ | ❌ | ❌ |
预算控制 | ✅ 原生支持 | ❌ | ❌ | ❌ |
审批治理 | ✅ 原生支持 | ❌ | ❌ | ❌ |
定时调度 | ✅ Heartbeat | ❌ | ❌ | ❌ |
成本追踪 | ✅ 多维度 | ❌ | ❌ | ❌ |
Agent 框架 | ❌ 不是 | ✅ 是 | ✅ 是 | ✅ 是 |
编码能力 | 依赖接入的 Agent | ✅ 核心能力 | ✅ 核心能力 | ✅ 核心能力 |
八、项目成熟度评估
维度 | 状态 | 说明 |
|---|---|---|
代码规模 | ⭐⭐⭐⭐⭐ | 111 万行 TS，111 张数据库表，工程量巨大 |
功能完整度 | ⭐⭐⭐⭐⭐ | 四大支柱全部实现，20+ 已完成里程碑 |
架构设计 | ⭐⭐⭐⭐⭐ | Monorepo 清晰，适配器体系解耦，Token 体系规范 |
Agent 生态 | ⭐⭐⭐⭐ | 11 种适配器覆盖主流 Agent，可扩展 |
测试覆盖 | ⭐⭐⭐⭐ | 单元(Vitest) + E2E(Playwright) + 视觉回归(Storybook) |
文档 | ⭐⭐⭐⭐⭐ | SPEC/DESIGN/AGENTS/DEVELOPING/DATABASE 等齐全 |
社区 | ⭐⭐⭐ | MIT 开源，Discord 社区，插件生态起步 |
生产就绪 | ⭐⭐⭐ | 支持 Docker 自托管，但云部署仍在进行中 |
九、总结
Paperclip 是目前少见的从"公司运营"视角而非"Agent 开发"视角构建的 AI Agent 编排平台。它的核心价值不是教你怎么造 Agent，而是教你怎么管 Agent 组成的公司——组织架构、任务分配、预算控制、审批治理、成本追踪、定期调度，这些是 20 个 Agent 同时运行时真正需要的东西。
技术上有三个亮点值得借鉴：
- 适配器体系
：BYOA（Bring Your Own Agent）设计，任何能接收 Heartbeat 的 Agent 都可接入，11 种适配器覆盖主流 Agent
- Heartbeat 调度
：数据库驱动的唤醒队列 + 原子 checkout + 预算检查 + 自动恢复，解决了多 Agent 协调的核心问题
- Token 设计系统
：严格的 CSS 变量 Token 体系 + Lint 门控，确保 UI 一致性和可维护性
来自微信公众号：LLM&Agent技术分享