paperclip-monitor

Paperclip 监控

检查活跃的 Paperclip 执行情况，并指出需要操作人员关注的事项。

参考资料

先阅读以下文件：

• 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-setup，根据随附模板生成文档。

只读工作流

1. 检查 CLI 上下文和公司范围。
2. 阅读仪表板摘要。
3. 阅读问题，重点关注：
   • blocked
   • in_review
   • in_progress
   • 长期未更新的 todo
   • 存在未完成子问题的父问题
4. 阅读审批，尤其是待处理和已请求修改的审批。
5. 阅读 Agent，并记录已暂停、出错、正在运行或因预算受阻的状态。
6. 对于活跃或近期分派的问题，在可用时使用 paperclipai issue live-runs、active-run、runs 和 recovery-actions，并添加 --json。区分排队交付、进程恢复、缺少评论的重试和明确的恢复操作，不要将所有后续运行都笼统标记为重试。在较新的环境中，还要检测其他运行存活状态字段。
7. 阅读活动记录，了解近期的重要事件。
8. 对于近期分派的工作，区分正常调度（wake queued、排队或正在运行的 run，或 workspace ready）与跳过或失败的调度。将正常的排队或运行中的接手视为成功，而不是需要干预的目标。
9. 对于处于审核阶段的问题，在可用时检查 executionState.currentStageType、currentParticipant 和 returnAssignee。执行者通常会通过将状态转换为 done 来提交；随后 Paperclip 会负责将问题路由到 Agent 审核者并设为 in_review。如果需要人工最终验收，还要检查问题交互：待处理的 request_confirmation 属于正常等待状态；而已接受或拒绝的交互若恢复失败或审核者未跟进，则需要关注。用户审批阶段的参与者属于流程缺陷，不应因此建议操作人员使用 CLI。
10. 按优先级顺序汇总需关注的事项。只有在报告中列出所有受阻、处于 in_review、待审批、出错 Agent、未解决的恢复操作以及明确跳过或失败的调度，或明确说明这些情况均不存在，才算完成。

报告格式

## Paperclip Monitor Report

### Needs Operator Attention

### Blocked Work

### Pending Reviews And Approvals

### Run And Recovery State

### Agent Health

### Cost And Budget Signals

### Recent Progress

### Recommended Actions

操作建议

仅提出建议，不要执行变更：

• 批准、拒绝或请求修改
• 接受或拒绝待处理的问题 request_confirmation
• 更改问题状态
• 添加评论
• 创建阻塞项
• 调查明确跳过或失败的调度
• 重新分派工作
• 暂停、恢复或终止 Agent

不要仅因唤醒已排队、运行正在进行或工作区已就绪，就建议添加评论、触发心跳或恢复、重新分派、修改工作区或环境，或中断运行。在排队或运行期间添加评论会注入工作。中断可能引发进程恢复；缺少必需评论时，可能会触发一次评论重试。任何纠正计划都必须等到所有仍在运行的 run 和相关恢复操作完成后，才能取消分配或重新分派。

变更规则

默认情况下，监控为只读操作。执行任何 Paperclip 变更前都要先询问。