pylot-api

用途

Pylot API 技能用于与 Pylot 网关交互，充当常驻的 Pylot 专家角色：派发任务、监控任务、维护平台健康。其核心职责包括：开发环境管理（worker 镜像、系统库、devcontainer 配置）、视觉证据流水线（UI 变更的 PR 应附带 GIF 或截图，通过资产后端上传）、技能维护（任务后读日志、发现问题、改进技能或开后续 issue）、PR 管理（派发 → 监控 → 审查 → 合并 → 验证）。

鉴权

所有请求使用 Bearer Token：

curl -sS -H "Authorization: Bearer $PYLOT_API_TOKEN" "$PYLOT_GATEWAY_URL/<endpoint>"

PYLOT_GATEWAY_URL 和 PYLOT_API_TOKEN 从环境变量读取。

主要能力

派发（Dispatch）：发送任务，支持 context.conversation_id 以启用任务完成和 PR 生命周期事件的自动唤醒。
监控（Monitoring）：检查状态、流式读取 CloudWatch 日志、按团队/状态过滤。
唤醒（Wakes）：自我唤醒、完成时自动唤醒、唤醒事件负载与时机指南。
资源（Resources）：加载/卸载 keychain 和技能。
密钥（Secrets）：发现 keychain、指纹、密钥描述。
团队（Crew）：名册、统计、成本、配置。
舰队（Fleet）：Fargate 项目和任务定义。
SDLC：PR 审查流水线、合并策略、唤醒时的操作。
部署（Deploy）：staging/prod 部署通道、POST /admin/deploy、发布 PR 提升。
自动化（Automations）：GET /automations schema、SDLC 自动化链、抑制语义。
资产（Assets）：上传图片/GIF/视频（presign → PUT → publish），用于 PR/issue 视觉证据。
欢迎（Welcome）：面向激活里程碑未完成的组织的首轮引导欢迎。

使用方式

快速开始：派发

始终传入 context.conversation_id，以启用任务完成和 PR 生命周期事件的自动唤醒：

CONV_ID=$(ls /tmp/claude-home/.claude/session-env/ | head -1)
curl -sS -X POST -H "Authorization: Bearer $PYLOT_API_TOKEN" -H "Content-Type: application/json" \
  -d "{\"agent\":\"<team>.<op>\",\"task\":\"<task>\",\"context\":{\"conversation_id\":\"$CONV_ID\"}}" \
  "$PYLOT_GATEWAY_URL/dispatch"

启动 / 定位

首轮时获取实时自动化并逐行渲染（事件 [标签?] → 规则名 excl:[...] repos:[...] skip:[...]）。失败时警告并继续，绝不阻塞启动。

curl -sS -H "Authorization: Bearer $PYLOT_API_TOKEN" "$PYLOT_GATEWAY_URL/automations" \
  | jq -r '.automations[] | "\(.trigger.event) [\(.trigger.match.label // "-")] → \(.name) excl:[\(.trigger.match.labels_exclude // [] | join(","))] repos:[\(.trigger.match.only_repos // [] | join(","))] skip:[\(.trigger.match.skip_repos // [] | join(","))]"' \
  2>/dev/null || echo "[warn] GET /automations unavailable — continuing without live automation summary"

欢迎检查（首轮）

若 $CONV_ORG 已设置，检查组织的激活阶梯：

curl -sS -H "Authorization: Bearer $PYLOT_API_TOKEN" "$PYLOT_GATEWAY_URL/orgs/$CONV_ORG/activation"

若 automations_on 之前的任何里程碑未完成，读取 docs/welcome.md 并遵循欢迎协议。若全部完成或 $CONV_ORG 未设置则跳过。404/错误时使用 docs/welcome.md 中的回退启发式，不要向用户提及此失败。

Worker 环境变量

worker 容器启动时注入的关键环境变量，直接从环境读取，不要向网关查询：

变量	类型	用途
PYLOT_JOB_ID	string	任务 ID，用于所有 worker API 调用
PYLOT_TASK	string	worker 收到的任务提示
PYLOT_REPO	string	worker 运行的 org/repo
PYLOT_REQUESTORS	JSON string \| unset	触发任务的人类请求者
PYLOT_GATEWAY_URL	string	网关基础 URL
PYLOT_DISPATCH_TOKEN	string	worker → 网关调用的 Bearer token

$PYLOT_REQUESTORS 由执行器在派发对话有真人参与者时设置。cron、webhook 或无对话上下文的直接 API 派发时不存在。形状为最多 10 个对象的 JSON 编码数组，字段包括 slack_user_id（始终存在）、github_username（未关联 GitHub 时为 null）、display_name（始终非空）、email（无法解析时为 null）。解析需防御性：缺失、空或格式错误均视为 []。

邮箱回退优先级（用于 git trailer 或其他归属）：

email 非空 → 使用 email
github_username 非空、email 为 null → github_username@users.noreply.github.com
github_username 为 null → slack_user_id@users.noreply.fellowship.dev

何时派发 vs. 本地执行

任务	本地	派发
回答问题、解释代码	✓	—
检查任务状态、读日志	✓	—
查询 API	✓	—
代码变更、PR、审查	—	✓
Docker 构建、部署	—	✓
运行测试套件	—	✓
任何超过 10 分钟的任务	—	✓

关联用户的 GitHub 身份

当用户要求关联 GitHub 时，不要探测鉴权路由或猜测，用一次调用生成自助链接 URL 并返回。这是本地操作（不派发）。

curl -sS -X POST "$PYLOT_GATEWAY_URL/users/link-request" \
  -H "Authorization: Bearer $PYLOT_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"conversation_id\":\"$CONVERSATION_ID\"}"

worker 会话中若安装了 pylot CLI，等价命令：pylot users link slack github --conversation "$CONVERSATION_ID"。

工作原理：网关从对话记录的 Slack 发送者推导身份，不传递身份声明；显式 slack_user_id 必须是已记录的发送者，否则 403。响应包含个人 URL，引导用户完成 GitHub OAuth，本身不授予任何权限，10 分钟后过期。将 URL 返回给请求者（优先 ephemeral/DM，因为是个人链接）。按组织范围隔离。

错误处理（不要盲目重试）：

响应	含义	告知用户
404 无 Slack 发送者记录	对话早于发送者标记	请发送新消息后重试
already_linked	身份已连接	通过 `GET /users?org=<org>` 确认其 github_login
403 on slack_user_id	身份注入被阻止	只有已记录的发送者才能关联，去掉覆盖

适用场景

适用于需要与 Pylot 网关交互的自动化与运维场景：派发代码变更/PR/审查任务、监控任务状态与日志、管理团队与成本、执行部署、上传 PR 视觉证据、维护技能、处理 GitHub 身份关联等。

限制

完整 API 参考位于 docs/ 目录，调用前需阅读相关文件。
部分端点（如 /orgs/$CONV_ORG/activation）可能尚未部署，需使用回退方案。
PYLOT_REQUESTORS 数组上限为 10 个请求者。
身份关联 URL 10 分钟过期，且仅限已记录的 Slack 发送者。
关于收费、价格、平台支持范围等具体信息，资料中暂未提供。