polylane-automations

Polylane 自动化

自动化是无人值守的 Agent 运行：类型化事件触发后，Agent 使用允许的一组技能（工具）执行你的指令，可选的 操作 会产生副作用，目标 则负责传递结果。所有部分都以声明式 JSON 编写。

本文件介绍模型和编写流程，不包含类型目录；这些目录有实时数据源：

来源	获取方式	用途
API 架构	polylane api describe automations.post	已安装 API 版本的权威请求结构，以及所有触发器／操作／目标类型和筛选条件
公共目录	GET /v1/public/automations/{catalog,triggers/catalog,actions/catalog}	无需身份验证即可获取模板和类型列表
文档	https://docs.polylane.com/remediation/automations（以及 /triggers、/actions、/destinations、/templates；原始 Markdown 位于 /raw/...md）	概念、示例、筛选条件语义
模板结构	polylane automation catalog --output json	可供参考的完整请求体
可附加技能	polylane skill list	--tool 可用的 slug

结构

trigger(s) ──▶ [optional delay] ──▶ agent run (instructions + tools) ──▶ actions ──▶ destinations

• 触发器 — 类型化事件：alert、cron、webhook、github.*、<provider>.deployment、slack.message、polylane.*（issue.triaged、change_record.created 等）。平台触发器（cron、webhook、polylane.*）始终可用；提供商触发器需要连接相应的集成。
• 指令 — Agent 执行的纯英文任务说明。
• 工具 — Polylane 技能（按 slug 指定），Agent 可在运行期间加载。
• 操作 — Agent 可执行的副作用：创建问题、评论／合并／提交 PR、回滚部署、排入自动修复队列、移交给外部编码 Agent。
• 目标 — 传递结果的位置：email、slack、webhook。

模式 同时控制操作和目标：always 会在每次运行完成时触发；smart 仅在运行被判定为值得关注时触发，但失败时始终会向目标传递结果。对于影响较大的操作（合并、回滚），优先使用 smart。

每次运行都是一个线程，可检查完整记录。执行状态：pending → delayed → running → completed / failed / skipped。

值得了解的限制

• 每个自动化最多 10 个触发器；每种类型最多一个，但 cron 和 webhook 除外，它们可以重复。
• openIssue 遵循工作区的每日问题数量限制；超出套餐限制的请求会收到 HTTP 426。
• Slack 目标需要 Slack 集成；webhook 目标在 10 s 后超时，非 2xx 响应会将传递记录为失败。
• 回滚操作及其策略因提供商而异；编写前请通过 api describe 查看确切的策略名称。

使用模板还是自定义？

├─ A catalog entry matches as-is → polylane automation from-template <slug>
├─ Close but too broad → crib its body (catalog --output json), narrow the trigger, create custom
└─ Nothing matches → polylane automation create (flags or --body-file)

实例化后的模板会成为完全可编辑的自动化。

CLI 用法

polylane automation catalog                        # browse templates
polylane automation from-template <slug>           # instantiate
polylane automation create \
  --name "Triage Datadog alerts" \
  --trigger '{"type":"alert","filters":{"sources":["datadog"],"severities":["critical"]}}' \
  --instructions "Correlate the alert with recent deploys and open an issue with the findings." \
  --tool investigate-errors \
  --action '{"type":"openIssue","mode":"smart","defaultSeverity":"high"}' \
  --delay 600000                                   # let a deploy settle before judging it

polylane automation trigger <id>                   # manual run
polylane automation executions <id>                # then: execution <id> <execution-id>, rerun

--trigger / --action / --destination 接受 JSON（可重复指定），也可接受不带筛选条件的类型名称（例如 --trigger webhook）。--tool 按 slug 附加技能（可重复指定）。--body-file 传入完整 JSON 请求体（- 表示标准输入）；标志参数会叠加应用。所有标志详见：polylane automation create --help。

编写清单

逐项完成所有内容；手动运行产生预期结果后，自动化才算完成。

1. 先查目录 — 只有找不到合适选项时才自定义。
2. 限定触发条件 — 按环境、来源、严重性或仓库筛选；未筛选的触发器会对所有内容运行。如果自动化应仅处理已确认的问题，优先使用 polylane.issue.triaged，而不是原始 alert。
3. 指令应写成操作手册 — 说明要调查什么、要收集哪些证据，以及什么样的结果才算理想。
4. 仅附加任务所需的技能。
5. 使用 smart 模式限制高风险操作，并在与部署相关的触发器上添加 --delay。
6. 连接目标位置 — 无人查看的结果，也就无人会采取行动。
7. 通过手动运行测试 — 使用 automation trigger，检查执行线程，并不断调整指令，直到运行结果符合用户要求。