攀岩者

Paperclip：让 AI Agent 组团打工的神器

作者：

climbing

在

攀岩者 | 技术总监 | 19年IT全栈实战

精通网络、安全、云计算、容器、数据库、超算，持证PMP、ITIL、CKA、网络工程师等。主导过多个千万级政务与智慧城市项目，从售前到交付全流程打通。热衷开源，日拱一卒，每天分享AI学习笔记，陪你从零基础到AI达人。

为什么需要 Paperclip？

想象一下这个场景：你手底下有好几个 AI（人工智能） Agent（智能体），比如 Hermes（赫尔墨斯）、Claude Code（克劳德代码）、MiMo Code（小米代码）等等。它们各干各的，互不沟通，就像一群没有项目经理的程序员——每个人都在写代码，但没人知道整体进度。

Paperclip（回形针）就是这个”AI 项目经理”。它把这些 AI Agent（智能体）组织成一家”公司”，有 CEO（首席执行官）、CTO（首席技术官）、工程师，还有任务分配、进度追踪、预算控制。简单说，就是让 AI 也能”上班打卡”。

!Paperclip 仪表盘

一、专业术语大白话讲解 / Terminology in Plain Language

1. Company（公司）

这是 Paperclip（回形针）里的最高组织单位。你可以把它想象成一家真正的公司，所有的 AI Agent（智能体）都在这家公司里”上班”。比如你可以创建一家叫”climbing.top”的公司。

2. Agent（智能体）

就是你的 AI 员工。每个 Agent（智能体）都是一个独立的 AI，可以是 Hermes（赫尔墨斯）、Claude Code（克劳德代码）、MiMo Code（小米代码）等等。它们就像公司的员工，各有各的技能和职责。

!Agent 管理界面

3. CEO（首席执行官）

默认的”老大”。当你第一次运行 Paperclip（回形针）时，它会自动创建一个 CEO Agent（首席执行官智能体）。CEO 可以创建其他 Agent（智能体），分配任务，就像真正的 CEO 一样。

4. Heartbeat（心跳）

Agent（智能体）的”闹钟”。Paperclip（回形针）会定期唤醒 Agent（智能体），让它检查有没有新任务需要执行。就像公司的早会，每天定时开一次。

5. Issue（任务）

就是分配给 Agent（智能体）的工作。比如”修复这个 Bug”、”写一篇文档”、”优化这段代码”。每个 Issue（任务）都可以指定负责人（Agent）和优先级。

6. Org Chart（组织架构图）

公司的组织结构。CEO（首席执行官）在最上面，下面是 CTO（首席技术官）、工程师等等。就像公司的组织架构图，一目了然。

!组织架构图

7. Budget（预算）

控制每个 Agent（智能体）的花费。你可以设置每月最多花多少钱，避免 AI（人工智能）”烧钱”太快。就像公司的预算管理制度。

8. Adapter（适配器）

连接不同 AI（人工智能）服务的”翻译官”。因为不同的 AI（人工智能）服务（如 OpenAI（开放人工智能）、Anthropic（人类学）、Xiaomi（小米））接口都不一样，Adapter（适配器）负责把 Paperclip（回形针）的指令翻译成对应服务能理解的语言。

二、系统界面功能介绍 / System Interface Overview

2.1 仪表盘（Dashboard）

打开浏览器访问 http://localhost:3100，你会看到 Paperclip（回形针）的主界面。仪表盘显示：

  • 公司基本信息
  • Agent（智能体）状态（在线/离线/错误）
  • 最近的任务动态
  • 预算使用情况

2.2 Agent 管理页面

在这里你可以：

  • 查看所有 Agent（智能体）列表
  • 创建新的 Agent（智能体）
  • 暂停/恢复 Agent（智能体）
  • 查看 Agent（智能体）的运行日志

2.3 Issue 管理页面

在这里你可以：

  • 创建新任务
  • 分配任务给 Agent（智能体）
  • 查看任务进度
  • 关闭已完成的任务

2.4 组织架构页面

可视化展示公司的组织结构，可以看到：

  • CEO（首席执行官）在最上面
  • 各个 Agent（智能体）的层级关系
  • 每个 Agent（智能体）的职责

三、如何将现有的 AI Agent 加入系统 / Adding Existing AI Agents

3.1 安装 Paperclip（回形针）

`bash

# 全局安装

npm install -g paperclipai

# 初始化（创建数据库、CEO Agent）

npx paperclipai onboard –yes

# 启动服务

npx paperclipai run

`

3.2 创建新的 Agent（智能体）

假设你已经有一个 Hermes（赫尔墨斯） Agent（智能体），想把它加入 Paperclip（回形针）：

`bash

# 创建 Agent

npx paperclipai agent create -C –payload-json ‘{

“name”: “Hermes-Home”,

“role”: “engineer”,

“adapter”: “hermes_local”

}’

# 输出类似：

# Agent created: ID=abc123, Name=Hermes-Home

`

3.3 配置 Agent（智能体）的 AI（人工智能）服务

`bash

# 设置 Agent 使用的 AI 模型

npx paperclipai agent update –payload-json ‘{

“adapterConfig”: {

“model”: “xiaomi/mimo-v2.5-pro”,

“provider”: “xiaomi”,

“timeoutSec”: 300,

“persistSession”: true

}

}’

`

3.4 连接本地 Agent（智能体）

如果你的 Agent（智能体）运行在另一台电脑上，需要连接到 Paperclip（回形针）服务器：

`bash

# 在 Agent 所在的电脑上运行

npx paperclipai agent local-cli –api-base http://:3100

`

四、如何创建任务以及后续使用流程 / Creating Tasks and Workflow

4.1 创建任务

`bash

# 创建一个简单任务

npx paperclipai issue create -C –payload-json ‘{

“title”: “修复登录页面的 Bug”,

“priority”: “high”,

“assigneeAgentId”: “”

}’

# 输出类似：

# Issue created: ID=issue456, Title=修复登录页面的 Bug

`

4.2 任务分配策略

Paperclip（回形针）支持多种任务分配方式：

手动分配：你指定具体的 Agent（智能体）来处理任务。

`bash

npx paperclipai issue create -C –payload-json ‘{

“title”: “写一篇技术文档”,

“assigneeAgentId”: “”

}’

`

自动分配：让 CEO（首席执行官） Agent（智能体）自动决定谁来处理。

`bash

npx paperclipai issue create -C –payload-json ‘{

“title”: “优化数据库查询”,

“priority”: “medium”

}’

`

4.3 设置 Heartbeat（心跳）

让 Agent（智能体）自动检查并执行任务：

`bash

# 启用 Heartbeat（心跳），每 5 分钟检查一次

npx paperclipai agent update –payload-json ‘{

“runtimeConfig”: {

“heartbeat”: {

“enabled”: true,

“intervalSec”: 300,

“cooldownSec”: 10,

“maxConcurrentRuns”: 5

}

}

}’

`

4.4 查看任务进度

`bash

# 列出所有任务

npx paperclipai issue list -C

# 查看具体任务详情

npx paperclipai issue get

# 查看 Agent 状态

npx paperclipai agent get

`

4.5 预算控制

`bash

# 设置 Agent 每月预算为 100 元

npx paperclipai agent update –payload-json ‘{

“budgetMonthlyCents”: 10000

}’

`

五、日常使用注意事项 / Daily Usage Tips

5.1 定期检查 Agent（智能体）状态

`bash

# 查看所有 Agent 状态

npx paperclipai agent list -C

# 查看 Agent 运行日志

npx paperclipai agent get | grep -A 10 “runtime”

`

5.2 处理 Agent（智能体）错误

如果 Agent（智能体）状态显示 error：

`bash

# 1. 重置 Agent 会话

npx paperclipai agent runtime-state:reset-session

# 2. 恢复 Agent

npx paperclipai agent resume

# 3. 手动触发一次 Heartbeat（心跳）测试

npx paperclipai agent heartbeat:invoke

`

5.3 查看活动日志

`bash

# 查看最近 20 条活动

npx paperclipai activity list –limit 20

`

5.4 健康检查

`bash

# 检查 Paperclip 服务是否正常

curl http://localhost:3100/api/health

`

六、安全防护策略 / Security Protection Strategies

6.1 访问控制

  • 默认模式为 local_trusted（本地信任），仅允许本机访问
  • 如果需要远程访问，必须改为 authenticated（认证）模式
  • 配置 allowedHostname（允许的主机名）限制访问来源

6.2 预算控制

  • 为每个 Agent（智能体）设置合理的月度预算
  • 监控预算使用情况，避免意外超支

6.3 API Key 管理

  • 定期轮换 API Key（应用程序编程接口密钥）
  • 不同的 Agent（智能体）使用不同的 API Key（应用程序编程接口密钥）
  • 不要在代码中硬编码 API Key（应用程序编程接口密钥）

6.4 网络安全

  • 如果通过 VPN（虚拟专用网络）访问，确保 VPN（虚拟专用网络）连接安全
  • 不要将 Paperclip（回形针）暴露在公网，除非必要

七、疑难问题处理 / Troubleshooting

7.1 Skills Catalog Not Found（技能目录未找到）

症状：Error: Skills catalog manifest not found

解决：

`bash

# 创建空目录

mkdir -p /path/to/paperclipai/node_modules/@paperclipai/packages/skills-catalog/generated

echo ‘{“skills”:[]}’ > /path/to/paperclipai/node_modules/@paperclipai/packages/skills-catalog/generated/catalog.json

`

7.2 Agent Stuck in Error（Agent 卡在错误状态）

症状：Agent 状态一直显示 error

解决：

`bash

# 重置会话

npx paperclipai agent runtime-state:reset-session

# 恢复 Agent

npx paperclipai agent resume

# 测试 Heartbeat（心跳）

npx paperclipai agent heartbeat:invoke

`

7.3 No Anthropic Credentials（没有 Anthropic 凭证）

症状：CEO Agent 报错 “No Anthropic credentials found”

解决：

`bash

# 更新 CEO Agent 的模型配置

npx paperclipai agent update –payload-json ‘{

“adapterConfig”: {

“model”: “xiaomi/mimo-v2.5-pro”,

“provider”: “xiaomi”

}

}’

`

7.4 Connection Refused（连接被拒绝）

症状：curl localhost:3100 返回连接失败

解决：

`bash

# 检查 Paperclip 是否在运行

ps aux | grep paperclip

# 如果没有运行，启动它

npx paperclipai run &

# 等待几秒后测试

sleep 5 && curl -s -o /dev/null -w “%{http_code}” http://localhost:3100/

`

7.5 Hostname Not Allowed（主机名不允许）

症状：远程访问时报错 “Hostname not allowed”

解决：

`bash

# 添加允许的主机名

npx paperclipai allowed-hostname

# 重启 Paperclip

`

八、实战案例：让 AI 帮你写代码 / Practical Example: Let AI Write Code for You

场景描述

你想让 AI（人工智能）帮你写一个 Python（蟒蛇）脚本，自动备份数据库。

步骤 1：创建任务

`bash

npx paperclipai issue create -C –payload-json ‘{

“title”: “编写数据库备份脚本”,

“description”: “编写一个 Python 脚本，每天凌晨 2 点自动备份 PostgreSQL 数据库，并保留最近 7 天的备份”,

“priority”: “high”,

“assigneeAgentId”: “”

}’

`

步骤 2：Agent（智能体）自动执行

当你启用了 Heartbeat（心跳），Agent（智能体）会在下一次心跳时检查到这个任务，并开始执行。它会：

  1. 分析任务需求
  2. 编写 Python（蟒蛇）脚本
  3. 测试脚本是否正常工作
  4. 将结果提交回 Paperclip（回形针）

步骤 3：查看结果

`bash

# 查看任务状态

npx paperclipai issue get

# 查看 Agent 执行日志

npx paperclipai agent get | grep -A 20 “logs”

`

九、Adapters（适配器）详解 / Adapter Deep Dive

Adapters（适配器）是 Paperclip（回形针）连接不同 AI（人工智能）服务的”翻译官”。官方文档显示，Paperclip（回形针）支持 19 种不同的适配器，包括：

9.1 支持的 AI（人工智能）服务

  • Claude（克劳德）：Anthropic（人类学）公司的 AI（人工智能）
  • Codex（代码克斯）：OpenAI（开放人工智能）的代码 AI（人工智能）
  • Gemini（双子座）：Google（谷歌）的 AI（人工智能）
  • Hermes（赫尔墨斯）：Nous Research（诺斯研究）的 AI（人工智能）
  • MiMo（小米）：Xiaomi（小米）的 AI（人工智能）
  • 自定义 HTTP 服务：你可以连接任何 AI（人工智能）服务

9.2 如何选择适配器

`bash

# 查看支持的适配器列表

npx paperclipai adapter list

# 设置 Agent 使用的适配器

npx paperclipai agent update –payload-json ‘{

“adapter”: “hermes_local”,

“adapterConfig”: {

“model”: “xiaomi/mimo-v2.5-pro”,

“provider”: “xiaomi”

}

}’

`

十、Projects & Workflow（项目和工作流） / Projects and Workflow

Paperclip（回形针）支持项目管理和工作流自动化：

10.1 Projects（项目）

  • 将相关的 Issue（任务）组织成项目
  • 设置项目目标和里程碑
  • 跟踪项目进度

10.2 Goals（目标）

  • 为 Agent（智能体）设置长期目标
  • Agent（智能体）会自动分解目标为可执行的任务
  • 定期评估目标完成情况

10.3 Routines（例程）

  • 设置 Agent（智能体）的日常工作流程
  • 例如：每天早上 9 点检查邮件，下午 5 点提交日报
  • 自动化重复性工作

10.4 Execution Workspaces（执行工作空间）

  • 为 Agent（智能体）提供独立的执行环境
  • 隔离不同项目的代码和资源
  • 避免项目之间的冲突

十一、高级玩法 / Advanced Tips

11.1 创建 Agent 团队

你可以创建一个完整的团队：

`bash

# 创建 CTO Agent

npx paperclipai agent create -C –payload-json ‘{

“name”: “CTO”,

“role”: “cto”,

“adapter”: “hermes_local”

}’

# 创建前端工程师

npx paperclipai agent create -C –payload-json ‘{

“name”: “Frontend-Engineer”,

“role”: “frontend_engineer”,

“adapter”: “hermes_local”

}’

# 创建后端工程师

npx paperclipai agent create -C –payload-json ‘{

“name”: “Backend-Engineer”,

“role”: “backend_engineer”,

“adapter”: “hermes_local”

}’

`

11.2 设置组织架构

`bash

# CEO 管理 CTO

npx paperclipai agent update –payload-json ‘{

“reportsTo”: null,

“directReports”: [“”]

}’

# CTO 管理工程师

npx paperclipai agent update –payload-json ‘{

“reportsTo”: “”,

“directReports”: [“”, “”]

}’

`

11.3 跨机器协作

如果你有多台电脑，可以通过 VPN（虚拟专用网络）让它们协作：

`bash

# 在服务器上配置 LAN（局域网）访问

# 编辑 ~/.paperclip/instances/default/config.json

{

“server”: {

“deploymentMode”: “authenticated”,

“bind”: “lan”,

“host”: “0.0.0.0”

}

}

# 添加允许的主机名

npx paperclipai allowed-hostname 192.168.1.100

npx paperclipai allowed-hostname 100.76.2.155

# 在其他电脑上连接 Agent

npx paperclipai agent local-cli –api-base http://:3100

`

十二、总结 / Conclusion

Paperclip（回形针）就像是 AI（人工智能） Agent（智能体）的”项目经理”，让多个 AI（人工智能） Agent（智能体）能够协同工作，而不是各干各的。通过本文的指导，你已经掌握了：

  1. 核心概念：Company（公司）、Agent（智能体）、CEO（首席执行官）、Heartbeat（心跳）、Issue（任务）
  2. 界面功能：仪表盘、Agent 管理、Issue 管理、组织架构
  3. Agent 接入：如何将现有的 AI（人工智能） Agent（智能体）加入系统
  4. 任务管理：如何创建、分配、追踪任务
  5. 安全策略：访问控制、预算管理、API Key（应用程序编程接口密钥）管理
  6. 故障排除：常见问题及解决方案

现在，你已经可以让 AI（人工智能） Agent（智能体）们”组团打工”了！想象一下，CEO（首席执行官）分配任务，CTO（首席技术官）监督执行，工程师们各司其职——这就是 AI（人工智能）时代的”公司”运营方式。

附录：常用命令速查 / Appendix: Common Commands

`bash

# 公司管理

npx paperclipai company list # 列出公司

# Agent 管理

npx paperclipai agent list -C # 列出 Agent

npx paperclipai agent get # 获取 Agent 详情

npx paperclipai agent create -C –payload-json ‘{…}’ # 创建 Agent

npx paperclipai agent resume # 恢复 Agent

npx paperclipai agent pause # 暂停 Agent

npx paperclipai agent heartbeat:invoke # 手动触发 Heartbeat（心跳）

# Issue 管理

npx paperclipai issue list -C # 列出 Issue

npx paperclipai issue create -C –payload-json ‘{…}’ # 创建 Issue

# 系统管理

npx paperclipai activity list –limit 20 # 查看活动日志

curl http://localhost:3100/api/health # 健康检查

`

攀岩者 | 技术总监 | 19年IT全栈实战

*日拱一卒，每天分享AI学习笔记，陪你从零基础到AI达人。*

评论

发表回复

您的邮箱地址不会被公开。 必填项已用 * 标注

更多文章