Pylot CLI 是通过命令行操作 Pylot 网关的技能，适用于 dispatch、监控、secrets、assets、workers 与 automations 等操作。
执行模式选择
需要人类参与的工作放在 devbox，而非 mission。Mission 是自主操作员运行（cron、auto-pylot、技能路由任务）。devbox 默认隔离，不需要 Git worktree，应在 devbox 的正常仓库检出中工作，选择目标分支与基线，保留已有变更，并在该检出中验证应用与测试。
当任务契约足够完整、worker 可执行、审查并报告而无需实时操控时，使用自主 mission，交由 factory 拥有实现循环。当工作确实需要实时选择、迭代诊断、跨 worker 中继或频繁用户指导时，使用交互式 devbox。
交互不等于持续操控，优先使用一个自包含提示，让所选技能或运行器拥有其正常阶段，然后等待问题、失败或结果。不要因为可以观察进度就把自主 mission 变成交互式。
认证全新的外部云会话
设备认证 broker 使用环境设置中绑定为 PYLOT_API_TOKEN 的持久 pdab_… 共享密钥认证一次性外部云会话。注册在已登录机器上执行一次 pylot auth broker enroll 并经过一次监督的官方设备批准。后续会话自动使用该绑定，无需自己的 pylot auth login 或复制 ~/.pylot/credentials 目录。broker 在服务器端保留并刷新其授权；30 天未成功刷新需重新注册。
这与 PYLOT_BROKER_TOKEN 不同，后者是限于心跳与 Git-token 铸造的 mission/worker broker JWT。PYLOT_API_TOKEN 也可持有其他令牌类型，应用设备认证 broker 规则前应检查安全身份响应，而非变量内容。
操作仓库前显式使用目标网关与组织：
pylot --version
pylot auth broker --help # 代理注入的云 broker 工作流需要 CLI 0.9.20+
pylot --url https://hooks.fellowship.dev --org <org> auth status
pylot --url https://hooks.fellowship.dev --org <org> devboxes projects
pylot --url https://hooks.fellowship.dev --org <org> devboxes project <org/repo>
pylot --url https://hooks.fellowship.dev --org <org> devboxes list <org/repo>
对于此 broker，auth status 报告 type: device_broker，并在环境绑定时显示 _cli.tokenSource: PYLOT_API_TOKEN。验证目标 org 已授权，再独立验证所需的本机读取。
在托管云中，检查支持的凭据就绪状态，保留继承的代理、TLS 信任与认证守卫。绑定变量可能包含代理占位符而非真实密钥；绝不要打印它、检查凭据文件或用复制的凭据替换它。
broker 对 org 范围读取与 devbox/worker 操作有显式端点允许列表。需区分以下失败：broker_org_required（选择目标 org）、broker_route_not_allowed（操作超出允许列表，停止并报告）、broker_reauth_required / broker_grant_revoked / broker_secret_revoked（按服务器恢复提示处理）。Broker 管理（status、revoke、rotate-secret）需要个人登录，broker 密钥不能管理自身。
云兼容性：使用 CLI 0.9.20+ 与针对 pylot#3988 的网关修复。Org 选择现可用代理占位符，broker 支持只读仓库上下文/playbook 及 org 范围路由与 dispatch（含 --dry-run）。
SSH 不可用并不代表 devbox 执行不可用。当 broker 认证与目标 devbox/worker 读取成功时，使用 workers prompt over HTTPS 在配置的 devbox 中运行远程 LLM。
派发 Mission
CONV_ID=$(ls ~/.claude/session-env/ | head -1)
pylot dispatch "<task>" --agent <team>.<role> --repo <org/repo> --context "conversation_id=$CONV_ID"
始终传递 --context conversation_id=… 以实现 auto-wake。每次 dispatch 载荷必须满足：任务文本以显式 /skill 开头；team.role 以 pylot teams list 为准；提示大小约 2560 字节，完整规格放入 issue 评论；任务契约自包含且不含密钥。跨 org 时，仓库所有者与所选凭据是独立输入，使用全局选项 --org 显式选择凭据。
监控 Mission
pylot missions list # 最近 missions
pylot missions view <job-id> # 完整详情
pylot missions logs <job-id> --follow # 追踪 CloudWatch 日志
终端状态：done、failed、cancelled、timeout。
密钥发现
pylot secrets tree # 完整密钥树
pylot secrets get <path> # bundle 键 + 指纹（无值）
加载到对话：pylot conversations resources-add <conv-id> type=secret ref=pylot/<path>
资产
没有 S3，使用 assets API。任何持久内容（截图、长报告、录制）都必须通过 pylot assets，绝不直接写入或链接到别处。三种生命周期：临时草稿（留在 turn 内）、可恢复检查点（presign --conversation <id> → PUT → finalize）、已发布制品（完整 presign → finalize → publish 流程）。
不要用 publish --conversation <id> 作为检查点的快捷或重试路径，它会设为 visibility: public。检查点保留不绑定 evidence_class。在 staging 中所有资产 30 天后自动过期。
当对话出现上下文容量系统消息（约 90% 上下文触发）时，将该 turn 作为最后机会，先检查点化已有内容。
使用 CLI 完成完整资产生命周期，唯一在 CLI 外的操作是直接 PUT 到短期 presigned URL。
FILE=/path/to/evidence.png
CONTENT_TYPE=image/png
SIZE=$(wc -c < "$FILE" | tr -d ' ')
if command -v sha256sum >/dev/null 2>&1; then
SHA256=$(sha256sum "$FILE" | awk '{print $1}')
else
SHA256=$(shasum -a 256 "$FILE" | awk '{print $1}')
fi
PRESIGN=$(pylot assets presign \
--content-type "$CONTENT_TYPE" --size "$SIZE" \
--repo <org/repo> --filename "$(basename "$FILE")" \
--evidence-class visual --retention-policy <repo-policy>)
ASSET_ID=$(printf '%s' "$PRESIGN" | jq -r '.asset_id')
UPLOAD_URL=$(printf '%s' "$PRESIGN" | jq -r '.upload_url')
curl -fsS -X PUT "$UPLOAD_URL" -H "Content-Type: $CONTENT_TYPE" --data-binary @"$FILE" && \
pylot assets finalize "$ASSET_ID" --sha256 "$SHA256" --size "$SIZE"
finalize 后按目的地选择动词：view（元数据 + 临时 GET URL）、attach --mission（私有 mission 证据）、publish（公开 capability URL）、publish --conversation <id> --alt "description"、unpublish（撤销公开 URL）。所有六个生命周期动作均为网关操作，必须走 pylot assets。
团队设置
pylot teams config <team> deploy.release_mode=ship # 点路径设置 + 回读
pylot teams config <team> budget_daily_usd=600
pylot teams get <team> --fields deploy,cron # 范围读取存储配置
pylot teams update <team> key=value [...] # 多字段 PATCH（无回读打印）
可变字段（服务器验证）：budget_daily_usd enabled org chains provider_chain cron fargate fargate_size deploy operators worker_images repos distill_enabled context_warn_pct context_hard_pct slack_channels。若写入"成功"但回读为 null，属 bug，应报告而非重试。
Runner 契约
技能名以 -runner 结尾者从 devbox 外部运行且需要一个 devbox。runner 从不自行执行引擎，它生成或定位 devbox、发送提示、轮询、验证并报告。runner 依赖引擎技能安装在 devbox 内，当前该依赖仅为 runner 前提中的一行文字，dispatch 前应检查目标仓库的 .claude/skills/。引擎不带后缀，须能在任何检出中工作且无网关访问。pylot skills list --kind runner 是 runner 的过滤契约。
预检与派发
dispatch 前确认：认证 CLI 可达 Pylot；实时团队、角色、技能路由、仓库、worker 镜像与预算支持所选模式；相关自动化不会重复或冲突；任务契约自包含、不含密钥并显式命名目标技能。通过 CLI 派发并保留返回的 mission 或 worker 标识符。对于大量远程工作，预先确定分支/基线、Git 身份与证据可见性。