paperclip-create-agent

创建 Paperclip Agent

通过镜像 Paperclip 原生的雇用工作流来创建新的 Paperclip Agent。

这是一项会修改本地环境的操作技能。可以自由检查，但在操作人员批准确切方案之前，不要创建 Agent、提交雇用请求、创建密钥、附加技能或更改权限。

参考资料

请先阅读：

• references/CONTEXT.md
• references/docs/paperclip-operator/control-plane.md
• references/docs/paperclip-operator/workflow.md
• references/docs/paperclip-operator/cli-contract.md
• references/docs/paperclip-operator/integration-matrix.md

从 Paperclip 文档和源代码中发现的实用上游接口：

• GET /api/companies/{companyId}/agents
• GET /api/companies/{companyId}/org
• GET /api/companies/{companyId}/agent-configurations
• GET /api/companies/{companyId}/skills
• GET /llms/agent-configuration.txt
• GET /llms/agent-configuration/{adapterType}.txt
• GET /llms/agent-icons.txt
• POST /api/companies/{companyId}/agent-hires
• POST /api/companies/{companyId}/agents
• POST /api/agents/{agentId}/keys
• POST /api/agents/{agentId}/skills/sync

工作流

1. 确认上下文。

   阅读 CLI 上下文和当前公司信息。确认是否有看板访问权限，或是否有权创建 Agent。如果当前身份无权创建 Agent，应准备招聘提案或审批请求，而不是尝试创建。

2. 检查公司惯例。

   阅读现有 Agent、组织架构图、公司技能和 Agent 配置。记录命名、图标、汇报关系、适配器类型、模型、环境绑定、默认环境、预算惯例、心跳默认值和必需的 Paperclip 技能。

3. 选择途径。

   • 如果需要治理、请求来自其他 Agent 或 issue，或操作员希望通过董事会可见的招聘流程，优先使用 paperclipai agent hire -C <company-id> --payload-json <json> --json。仅当已安装的 CLI 不包含此命令时，才回退到 POST /api/companies/{companyId}/agent-hires。
   • 如果已明确批准直接创建，且公司政策允许，优先使用 paperclipai agent create -C <company-id> --payload-json <json> --json。仅在必要时才回退到 POST /api/companies/{companyId}/agents。
   • 如果没有经过身份验证且可安全创建记录的调用接口，则使用 Paperclip UI 作为备用方案。

4. 起草 Agent。

   包含 name、role、title、icon、reportsTo、capabilities、adapterType、adapterConfig、desiredSkills、受管理的 instructionsBundle、runtimeConfig.heartbeat、defaultEnvironmentId、budgetMonthlyCents、明确的 permissions，以及在招聘来自 Paperclip 工作时提供 sourceIssueId/sourceIssueIds。

5. 起草指令。

   如有可用模板，优先选择特定角色或相近角色的 Paperclip 模板。否则，编写精简的 AGENTS.md，涵盖身份、汇报关系、角色章程、工作流程、领域视角、输出标准、协作、安全与权限，以及完成标准。

   对于以执行为主的 Agent，加入以下约定：在同一心跳周期内开始可执行的工作；除非用户要求规划，否则不要停留在计划阶段；留下可持续追踪的进展和明确的下一步行动；对于耗时较长或可并行的委派工作，使用子 issue，而不是轮询；标记受阻工作时注明负责人和行动；遵守预算、暂停/取消、审批关卡和公司边界。

6. 审批前检查。

   检查是否存在重复 Agent、缺少经理、角色错误、不受支持的适配器/模型、缺少技能、明文机密、权限过宽、不必要的定时器心跳、能力描述含糊，以及与 Paperclip 单一事实来源规则冲突的指令。

7. 请求操作员批准。

   展示提议的途径、载荷摘要、经理、适配器/模型、技能、权限、预算、心跳策略、环境、源 issue 关联，以及任何风险设置。等待批准。

8. 应用并验证。

   优先使用原生 CLI 创建招聘或 Agent，否则使用 API/REST 备用方案。读取创建后的 Agent 和审批记录，并验证状态：

   • 适用治理流程时，状态应为 pending_approval，并且应有 hire_agent 审批
   • 直接创建成功时，状态应为 idle 或公司的默认活跃状态

   确认已持久化的字段：name、role、reportsTo、适配器类型/配置、所需技能、指令包模式/路径、心跳配置、预算、权限、环境和源关联。

9. 仅在创建有效后设置本地 CLI。

   对于可在本地运行的 Agent，使用：

   paperclipai agent local-cli <agentRef> -C <company-id> --json
   

   切勿在聊天中打印长期有效的 API 密钥。概述密钥创建情况，并在需要时告知操作员命令将导出内容输出到何处。

10. 报告结果。

包含 Agent id/url key、审批 id（如有）、状态、经理、适配器、技能、心跳状态、预算以及操作员的下一步行动。

负载说明

当前 Paperclip 源码中的有效角色包括 ceo、cto、cmo、cfo、security、engineer、designer、pm、qa、devops、researcher 和 general。

已知的适配器类型包括 process、http、acpx_local、claude_local、codex_local、cursor_cloud、gemini_local、opencode_local、pi_local、cursor 和 openclaw_gateway。

对于 codex_local，优先使用托管指令，而不是旧版提示词字段。典型的适配器配置包括 cwd、model、env、timeoutSec、graceSec、fastMode，以及仅限明确批准的沙盒／审批绕过设置。

变更规则

创建招聘、创建直接 Agent、附加所需技能、创建 API 密钥、更改权限、设置密钥／环境变量绑定、启用定时心跳或分配工作之前，请先询问。不要手动触发其他 Agent 的心跳；符合条件的分配完成后，Paperclip Agent 会根据自身的心跳策略唤醒。