twill-cloud-coding-agent

Twill 云端编码 Agent

使用此技能，通过公共 v1 API 运行 Twill 工作流。

设置

设置 API 密钥和可选的基础 URL：

export TWILL_API_KEY="your_api_key"
export TWILL_BASE_URL="${TWILL_BASE_URL:-https://twill.ai}"

所有 API 调用均使用：

Authorization: Bearer $TWILL_API_KEY

使用以下辅助函数，减少重复操作：

api() {
  curl -sS "$@" -H "Authorization: Bearer $TWILL_API_KEY" -H "Content-Type: application/json"
}

API 密钥属于云工作区，且只能访问该工作区的云端任务。个人工作区的密钥会被拒绝；本地项目聊天（Twill Desktop）无法通过 API 查看：请求会返回 404，或在列表中被省略。

错误为 JSON { "error": { "code", "message", "details"? } }。每个密钥的速率限制为每分钟 100 次、每小时 1,000 次；429 响应包含 Retry-After。

端点覆盖范围（公共 v1）

• GET /api/v1/auth/me
• GET /api/v1/repositories
• POST /api/v1/tasks
• GET /api/v1/tasks
• GET /api/v1/tasks/:taskIdOrSlug
• POST /api/v1/tasks/:taskIdOrSlug/messages
• GET /api/v1/tasks/:taskIdOrSlug/jobs
• POST /api/v1/tasks/:taskIdOrSlug/cancel
• POST /api/v1/tasks/:taskIdOrSlug/archive
• GET /api/v1/tasks/:taskIdOrSlug/teleport/claude
• GET /api/v1/jobs/:jobId/logs/stream
• POST /api/v1/jobs/:jobId/cancel
• GET /api/v1/scheduled-tasks
• POST /api/v1/scheduled-tasks
• GET /api/v1/scheduled-tasks/:scheduledTaskId
• PATCH /api/v1/scheduled-tasks/:scheduledTaskId
• DELETE /api/v1/scheduled-tasks/:scheduledTaskId
• POST /api/v1/scheduled-tasks/:scheduledTaskId/pause
• POST /api/v1/scheduled-tasks/:scheduledTaskId/resume

没有计划审批端点。计划和原生权限问题会在 Twill 任务聊天中处理。

身份验证与发现

验证密钥和工作区上下文：

curl -sS "$TWILL_BASE_URL/api/v1/auth/me" -H "Authorization: Bearer $TWILL_API_KEY"

返回 workspaceId、userId、apiKeyId、workspaceName、workspaceSlug。

列出工作区可用的 GitHub 仓库：

curl -sS "$TWILL_BASE_URL/api/v1/repositories" -H "Authorization: Bearer $TWILL_API_KEY"

返回 { repositories: [{ fullName, defaultBranch, description }] }。

任务

创建任务

api -X POST "$TWILL_BASE_URL/api/v1/tasks" -d '{"command":"Fix flaky tests in CI"}'

请求正文不接受仓库和分支。Agent 会在运行时从工作区已连接的仓库中选择。

必填字段：

• command

可选字段：

• agent：完整的 provider/model ID，例如 claude-code/sonnet、claude-code/opus、codex/gpt-5.5、open-code/openai/gpt-5.4。不接受仅包含提供方的值，例如 codex。省略此字段时，将使用工作区的路由默认值。
• userIntent（SWE、DEV_ENVIRONMENT、SCHEDULE）：默认为 SWE。仍接受旧版的 PLAN、ASK 和 GOAL，但会按 SWE 运行。
• reasoningEffort（low、medium、high、xhigh、max、ultra）
• parentId（要基于其创建此任务的现有任务 ID）
• title
• files（由 { filename, mediaType, url } 组成的数组，其中 url 必须是 data: URL，例如 data:text/plain;base64,...；不接受远程 http(s): URL）

如需让 Agent 先制定计划，请以 /plan 开始 command。用户会在 Twill 任务聊天中审阅并批准计划。

响应（201）为 { task: { id, slug, title, url }, job: { id, status } }。务必将 task.url 返回给用户。

列出任务

curl -sS "$TWILL_BASE_URL/api/v1/tasks?limit=20&cursor=BASE64_CURSOR" -H "Authorization: Bearer $TWILL_API_KEY"

支持通过 limit（默认值为 20，最大值为 100）和 cursor 进行游标分页。响应为 { tasks, nextCursor }；每个任务都包含 id、slug、title、url、createdAt、latestJobStatus 和 prs（由 { repoFullName, prNumber, prUrl, title, state } 组成的数组，其中 state 为 open、merged 或 closed）。

获取任务详情

curl -sS "$TWILL_BASE_URL/api/v1/tasks/TASK_ID_OR_SLUG" -H "Authorization: Bearer $TWILL_API_KEY"

返回 task（id、slug、title、url、createdAt、updatedAt、prs）和 latestJob（id、status、type、agentProvider、startedAt、completedAt、plan、planOutcome、finalAnswer），或 latestJob: null。

发送后续消息

api -X POST "$TWILL_BASE_URL/api/v1/tasks/TASK_ID_OR_SLUG/messages" -d '{"message":"Please prioritize login flow first"}'

发送消息会取消该任务当前正在运行的作业，并使用这条消息启动新一轮运行。响应为 { job: { id, status } }。

可选字段：userIntent、reasoningEffort、files（规则与创建时相同）和 agent。agent 可以更改模型，但不能更改执行环境：从 claude-code/... 切换到 codex/... 会返回 400。要使用其他执行环境，请启动新任务。

列出任务作业

curl -sS "$TWILL_BASE_URL/api/v1/tasks/TASK_ID_OR_SLUG/jobs?limit=30&cursor=BASE64_CURSOR" -H "Authorization: Bearer $TWILL_API_KEY"

支持游标分页：

• limit 默认为 30（最大 100）
• cursor 用于获取较早的页面
• 响应为 { jobs, nextCursor }；每个作业包含 id、status、type、agentProvider、finalAnswer、plan、planOutcome、error、createdAt、completedAt

取消任务

api -X POST "$TWILL_BASE_URL/api/v1/tasks/TASK_ID_OR_SLUG/cancel" -d '{}'

归档任务

api -X POST "$TWILL_BASE_URL/api/v1/tasks/TASK_ID_OR_SLUG/archive" -d '{}'

导出 Claude Teleport 会话

curl -sS "$TWILL_BASE_URL/api/v1/tasks/TASK_ID_OR_SLUG/teleport/claude" -H "Authorization: Bearer $TWILL_API_KEY" -o session.tar

返回任务的 Claude Code 会话 JSONL 文件的 tar 包（标头为 X-Twill-Session-Id、X-Twill-Job-Id、X-Twill-File-Count）。仅当任务使用 Claude Code 且任务沙箱仍在运行时可用；否则会返回 400、404 或 409。

作业

流式传输作业日志（SSE）

curl -N "$TWILL_BASE_URL/api/v1/jobs/JOB_ID/logs/stream" -H "Authorization: Bearer $TWILL_API_KEY" -H "Accept: text/event-stream"

每个 data: 行都是一个包含 type 的 JSON 对象：

• connected：第一个事件。
• 已完成的作业：trace_url（url、expiresAt），这是用于下载完整跟踪记录的短时有效签名 URL；随后是 historical_complete 和 complete（status：completed、failed 或 cancelled）。
• 正在运行的作业：trace_chunks（签名分块 URL）和用于历史记录的 trace_records；随后是 historical_complete，再之后是实时日志和状态事件，直到 complete。
• error：流传输失败。

如需在不解析跟踪记录的情况下获取作业结果，请优先使用“获取任务详情”或“列出任务作业”中的 finalAnswer。

取消作业

api -X POST "$TWILL_BASE_URL/api/v1/jobs/JOB_ID/cancel" -d '{}'

定时任务

创建定时任务需要付费套餐（Pro 或 Max）；否则 API 会返回 403。

列出并创建

curl -sS "$TWILL_BASE_URL/api/v1/scheduled-tasks" -H "Authorization: Bearer $TWILL_API_KEY"

api -X POST "$TWILL_BASE_URL/api/v1/scheduled-tasks" -d '{
  "title":"Daily triage",
  "message":"Review urgent issues and open tasks",
  "cronExpression":"0 9 * * 1-5",
  "timezone":"America/New_York",
  "agentProviderId":"claude-code/sonnet"
}'

必填项：title（最多 200 个字符）、message、cronExpression。

可选项：timezone（IANA 名称，默认为 "UTC"）、agentProviderId（完整的 provider/model 覆盖值，例如 claude-code/sonnet、codex/gpt-5.5）。保存时服务器不会验证 agentProviderId，因此只有在定时任务运行时才会发现无效 ID。

仓库和分支不属于定时任务载荷的一部分。每次运行都会在派发时选择仓库，与一次性任务相同。

响应为 { scheduledTask: { id, workspaceId, createdById, title, message, cronExpression, timezone, nextRunAt, lastRunAt, enabled, agentProviderId, createdAt, updatedAt } }。

读取、更新、删除

curl -sS "$TWILL_BASE_URL/api/v1/scheduled-tasks/SCHEDULED_TASK_ID" -H "Authorization: Bearer $TWILL_API_KEY"

api -X PATCH "$TWILL_BASE_URL/api/v1/scheduled-tasks/SCHEDULED_TASK_ID" -d '{
  "message":"Updated instructions",
  "cronExpression":"0 10 * * 1-5",
  "agentProviderId":"codex/gpt-5.5"
}'

curl -sS -X DELETE "$TWILL_BASE_URL/api/v1/scheduled-tasks/SCHEDULED_TASK_ID" -H "Authorization: Bearer $TWILL_API_KEY"

PATCH 接受 title、message、cronExpression、timezone、agentProviderId 的任意子集（传入 null 可清除覆盖值）。DELETE 返回 { "success": true }。

暂停和恢复

api -X POST "$TWILL_BASE_URL/api/v1/scheduled-tasks/SCHEDULED_TASK_ID/pause" -d '{}'
api -X POST "$TWILL_BASE_URL/api/v1/scheduled-tasks/SCHEDULED_TASK_ID/resume" -d '{}'

行为

• 将 userIntent 设为 SWE（默认值）、DEV_ENVIRONMENT 或 SCHEDULE。如需规划，请在命令前加上 /plan，而不是发送 PLAN。
• 在任务中不要发送 repository / branch，也不要在定时任务中发送 repositoryUrl / baseBranch。Twill 会在运行时根据工作区上下文选择仓库和分支。
• 始终将 agent / agentProviderId 设为完整的 provider/model ID。
• 将附件内联为 data: URL。
• 创建任务，报告 task.url，并仅在用户请求时轮询或流式传输日志。
• 计划审批和权限问题会在 Twill 任务聊天中处理。后续消息无法回答这些问题。
• 如果缺少 TWILL_API_KEY，请向用户索取。
• 不要打印 API 密钥或其他机密。