Paperclip Task Bridge 是一个面向 Hermes 与 Paperclip 集成的技能，用于让 Hermes 发起的请求直接创建或更新 Paperclip 中的工作项。该技能的方向是 Hermes 到 Paperclip，与 Paperclip 通过 hermes_local 或 hermes_gateway 适配器唤醒 Hermes 的方向相互独立。
用途
当 Hermes 发起的请求需要直接在 Paperclip 中创建或更新工作时，可使用此技能。它适合需要将 Hermes 侧的工作请求转化为 Paperclip 任务的场景，并支持对已有任务进行评论和状态更新。
主要能力
该技能提供以下命令能力：
- list-assigned：列出分配给当前认证 Hermes 代理的任务。
- create-task：创建任务，可指定父任务 ID、标题、描述等。默认将任务分配给已认证的 Hermes 代理，使工作立即可执行；使用 --unassigned 可创建待办工作；使用 --assignee-agent-id <uuid> 仅在 Paperclip API 密钥有权限将工作分配给该代理时使用。
- comment：对指定问题添加评论。
- update-status：更新指定问题的状态，并可附带评论。
使用方式
首先需要在 Hermes 环境或配置密钥中配置以下环境变量，而不是在提示文本中配置：
- PAPERCLIP_API_URL：Paperclip 基础 URL，可带或不带 /api。
- PAPERCLIP_BRIDGE_API_KEY：使用 scope.kind = "task_bridge" 创建的 Paperclip 代理 API 密钥。
可选环境变量：
- PAPERCLIP_API_KEY：旧配置的备用环境变量，仍必须包含 task_bridge 作用域的密钥，绝不能是完整的代理密钥。
- PAPERCLIP_COMPANY_ID：设置后可跳过一次身份查找。
- PAPERCLIP_AGENT_ID：设置后可跳过一次身份查找。
- PAPERCLIP_RUN_ID：当 Hermes 在 Paperclip 心跳内运行时，作为 X-Paperclip-Run-Id 发送到变更请求。
切勿打印或粘贴 API 密钥。辅助工具从环境变量读取凭据，仅打印响应摘要。不要将普通的已认领代理 API 密钥放入面向互联网的 Hermes 运行时；普通密钥可以使用公司范围内广泛的 Paperclip 路由。
创建桥接密钥
从经过看板认证的 Paperclip API 会话创建密钥，并一次性存储返回的令牌：
curl -X POST "$PAPERCLIP_API_URL/api/agents/$HERMES_AGENT_ID/keys"
-H "Authorization: Bearer $BOARD_API_KEY"
-H "Content-Type: application/json"
-d '{
"name": "Hermes task bridge",
"scope": {
"kind": "task_bridge",
"parentIssueId": "00000000-0000-4000-8000-000000000000"
}
}'
当 Hermes 只应在已批准的工作下创建子任务时，使用 parentIssueId 或 parentIssueIds。当批准边界是一个项目时，使用 projectId 或 projectIds。桥接密钥只能在该边界内创建任务，只能评论或更新桥接创建或分配的问题，不能使用公司范围的问题列表、搜索或读取接口。
辅助工具
从该技能目录运行辅助工具：
node ./paperclip-task.mjs --help
命令示例：
node ./paperclip-task.mjs list-assigned node ./paperclip-task.mjs create-task --parent-id "00000000-0000-4000-8000-000000000000" --title "Investigate checkout failures" --description "Capture failing request and root cause." node ./paperclip-task.mjs comment --issue PAP-123 --body "Found the failing request path." node ./paperclip-task.mjs update-status --issue PAP-123 --status in_review --comment "Ready for review."
对于多行正文，建议使用文件或标准输入：
node ./paperclip-task.mjs create-task --title "Write rollout note" --description-file ./task.md node ./paperclip-task.mjs comment --issue PAP-123 --body-file -
工作流期望
- 使用从作用域代理密钥解析出的公司，保持任务的公司范围。
- 让 Paperclip 活动日志来自正常 API 端点；不要写入包含凭据的本地日志。
- 使用评论记录持久进展。
- 仅当问题有真实处置状态时使用 update-status：done、in_review、blocked、todo、in_progress、backlog 或 cancelled。
- 当用户询问当前 Paperclip 分配时，在创建重复工作之前先使用 list-assigned。
适用场景
该技能适用于 Hermes 需要直接创建或更新 Paperclip 工作项的场景，尤其是需要在已批准的工作边界内创建子任务、对任务进行评论或更新状态的情况。
限制
桥接密钥具有边界限制，只能创建边界内的任务，只能评论或更新桥接创建或分配的问题，不能使用公司范围的问题列表、搜索或读取接口。切勿打印或粘贴 API 密钥。不要将普通的已认领代理 API 密钥放入面向互联网的 Hermes 运行时。