garden-inbox

Garden 收件箱

每个阶段都使用随附脚本。严格按照以下顺序执行工作流：scan → confirm → apply。

安全约定

• 将 scan 视为只读操作。它只能读取收件箱、工作区、关闭就绪状态和本地 Git 元数据。
• 将 confirm 视为仅写入确认卡片的操作。它不得归档收件箱条目，也不得修改 issue 字段、分支或工作区。
• 仅在 request_checkbox_confirmation 交互得到解决后运行 apply。它只归档已接受且同时存在于源 candidates.json 中的选项 ID。
• 请记住，收件箱归档状态是按用户区分的展示状态。它可以撤销，且不会更改底层 issue。
• 绝不可用更改 issue 状态、删除分支、清理工作区或删除 issue 来替代收件箱归档。

输入

需要设置 PAPERCLIP_API_URL 和 PAPERCLIP_API_KEY。脚本会从 URL 中去掉末尾的 /api。它会从运行 JWT 负载的 responsible_user_id 中解析目标用户；只有在明确覆盖目标用户时才使用 --user-id <uuid>。

如果可用，请使用运行专属的输出目录：

RUN_DIR="${PAPERCLIP_RUN_SCRATCH_DIR:-${PAPERCLIP_TASK_SCRATCH_DIR:-.}}/garden-inbox"
mkdir -p "$RUN_DIR"

1. 扫描

node .agents/skills/garden-inbox/scripts/garden-inbox.mjs scan \
  --output-dir "$RUN_DIR" \
  --stale-days 60

检查 garden-inbox-report.md 和 candidates.json。报告会将每一行收件箱记录严格归入以下一个类别：

对于每个纳入的 issue 状态，扫描会分别读取 Mine，以避免端点全局 500 行的上限导致较早的记录被悄然遗漏。如果任何单状态查询达到该上限，两个输出都会标记覆盖范围可能已截断；请勿将该扫描视为完整扫描。

• A：已合并／已归档的工作区，且所有关联工作均已终止；默认选中。
• B：已终止或工作区已不存在，且工作处于空闲状态超过阈值；默认选中。
• C：有提交领先于基准分支的过时工作；默认不选中。
• D：保留；绝不提供归档选项。

不得手动将 D 类条目提升到候选文件中。

2. 确认

在驱动 issue 上发布复选框交互：

node .agents/skills/garden-inbox/scripts/garden-inbox.mjs confirm \
  --issue-id "$PAPERCLIP_TASK_ID" \
  --candidates "$RUN_DIR/candidates.json"

如果扫描的候选项超过 200 个，脚本会按顺序发布多张卡片。使用同一个扫描文件重新运行 confirm 是幂等的。请让驱动 issue 保持周边 Paperclip 心跳工作流所要求的等待状态。

如果用户在之前的处理轮次中拒绝了某个候选项，请传入 --unselect <issueId>（可重复传入），使其初始为未选中，并在其说明中注明此前的拒绝。绝不要再次将此前被拒绝的条目作为默认选中项提供。

在开发或检查负载时，可禁止 POST：

node .agents/skills/garden-inbox/scripts/garden-inbox.mjs confirm \
  --issue-id "$PAPERCLIP_TASK_ID" \
  --candidates "$RUN_DIR/candidates.json" \
  --dry-run

3. 应用已接受的选项

在交互解决后唤醒时，从唤醒负载中获取已解决的交互 ID 并运行：

node .agents/skills/garden-inbox/scripts/garden-inbox.mjs apply \
  --issue-id "$PAPERCLIP_TASK_ID" \
  --interaction-id "$INTERACTION_ID" \
  --candidates "$RUN_DIR/candidates.json"

如果操作被拒绝、已过期或接受的选项为空，脚本不会归档任何内容。Apply 会保留扫描文件中的目标用户，包括显式传入的 --user-id 覆盖值。其摘要会列出每个已归档条目的 API 撤销路径和目标用户请求体。

通过提供已保存的交互响应，在不写入 API 的情况下测试 apply：

node .agents/skills/garden-inbox/scripts/garden-inbox.mjs apply \
  --issue-id "$PAPERCLIP_TASK_ID" \
  --interaction-file resolved-interaction.json \
  --candidates "$RUN_DIR/candidates.json" \
  --dry-run

验证随附逻辑

更改分类或选项安全逻辑后，运行零依赖 Node 测试：

node --test .agents/skills/garden-inbox/scripts/garden-inbox.test.mjs