twill-cloud-coding-agent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Twill Cloud Coding Agent

Use this skill to run Twill workflows through the public

v1

API.

使用此技能通过公开的

v1

API运行Twill工作流。

Setup

配置

Set API key and optional base URL:

bash

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

All API calls use:

Authorization: Bearer $TWILL_API_KEY

Use this helper to reduce repetition:

bash

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

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

bash

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

所有API调用均使用：

Authorization: Bearer $TWILL_API_KEY

使用以下辅助工具减少重复代码：

bash

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

Endpoint Coverage (Public v1)

端点覆盖范围（公开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/approve-plan

```
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

```
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/approve-plan

```
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

Auth and Discovery

身份验证与发现

Validate key and workspace context:

bash

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

List available GitHub repositories for the workspace:

bash

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

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

bash

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

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

bash

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

Tasks

任务

Create Task

创建任务

bash

api -X POST "$TWILL_BASE_URL/api/v1/tasks" \
  -d '{"command":"Fix flaky tests in CI","repository":"owner/repo","userIntent":"SWE"}'

Required fields:

```
command
```
```
repository
```
(
```
owner/repo
```
or full GitHub URL)

Optional fields:

```
branch
```
```
agent
```
(provider or provider/model, for example
```
codex
```
or
```
codex/gpt-5.2
```
)
```
userIntent
```
(
```
SWE
```
,
```
PLAN
```
,
```
ASK
```
,
```
DEV_ENVIRONMENT
```
) — defaults to
```
SWE
```
```
title
```
```
files
```
(array of
```
{ filename, mediaType, url }
```
)

Always report

task.url

back to the user.

bash

api -X POST "$TWILL_BASE_URL/api/v1/tasks" \
  -d '{"command":"Fix flaky tests in CI","repository":"owner/repo","userIntent":"SWE"}'

必填字段：

```
command
```
```
repository
```
（
```
owner/repo
```
格式或完整GitHub URL）

可选字段：

```
branch
```
```
agent
```
（提供商或提供商/模型，例如
```
codex
```
或
```
codex/gpt-5.2
```
）
```
userIntent
```
（
```
SWE
```
、
```
PLAN
```
、
```
ASK
```
、
```
DEV_ENVIRONMENT
```
）——默认值为
```
SWE
```
```
title
```
```
files
```
（
```
{ filename, mediaType, url }
```
构成的数组）

请始终将

task.url

返回给用户。

List Tasks

列出任务

bash

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

Supports cursor pagination via

limit

and

cursor

bash

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

支持通过

limit

和

cursor

进行游标分页。

Get Task Details

获取任务详情

bash

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

Returns task metadata plus

latestJob

including status, type, plan content, and plan outcome when available.

bash

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

返回任务元数据以及

latestJob

（包括状态、类型、计划内容和可用的计划结果）。

Send Follow-Up Message

发送跟进消息

bash

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

userIntent

and

files

are optional.

bash

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

userIntent

和

files

为可选参数。

List Task Jobs

列出任务作业

bash

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

Supports cursor pagination:

```
limit
```
defaults to
```
30
```
(max
```
100
```
)
```
cursor
```
fetches older pages
response includes
```
jobs
```
and
```
nextCursor
```

bash

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
```

Approve Plan

批准计划

Use when the latest plan job is completed and ready for approval.

bash

api -X POST "$TWILL_BASE_URL/api/v1/tasks/TASK_ID_OR_SLUG/approve-plan" \
  -d '{}'

当最新的计划作业完成并准备好批准时使用。

bash

api -X POST "$TWILL_BASE_URL/api/v1/tasks/TASK_ID_OR_SLUG/approve-plan" \
  -d '{}'

Cancel Task

取消任务

bash

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

bash

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

Archive Task

归档任务

bash

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

bash

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

Jobs

作业

Stream Job Logs (SSE)

流式传输作业日志（SSE）

bash

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

Stream emits JSON payloads in

data:

lines and terminates with a

complete

event.

bash

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

流会在

data:

行中发送JSON负载，并在

complete

事件时终止。

Cancel Job

取消作业

bash

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

bash

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

Scheduled Tasks

定时任务

List and Create

列出与创建

bash

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",
  "repositoryUrl":"https://github.com/org/repo",
  "baseBranch":"main",
  "cronExpression":"0 9 * * 1-5",
  "timezone":"America/New_York",
  "agentProviderId":"claude-code/sonnet"
}'

Required:

title

message

repositoryUrl

baseBranch

cronExpression

Optional:

timezone

(defaults to

"UTC"

agentProviderId

(provider/model override).

bash

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",
  "repositoryUrl":"https://github.com/org/repo",
  "baseBranch":"main",
  "cronExpression":"0 9 * * 1-5",
  "timezone":"America/New_York",
  "agentProviderId":"claude-code/sonnet"
}'

必填项：

title

、

message

、

repositoryUrl

、

baseBranch

、

cronExpression

。

可选项：

timezone

（默认值为

"UTC"

）、

agentProviderId

（覆盖提供商/模型）。

Read, Update, Delete

读取、更新、删除

bash

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.2"
}'

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

bash

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.2"
}'

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

Pause and Resume

暂停与恢复

bash

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 '{}'

bash

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 '{}'

Behavior

行为规范

Use
```
userIntent
```
(
```
SWE
```
,
```
PLAN
```
,
```
ASK
```
,
```
DEV_ENVIRONMENT
```
) when calling API endpoints directly.
Create task, report
```
task.url
```
, and only poll/stream logs when requested.
Ask for
```
TWILL_API_KEY
```
if missing.
Do not print API keys or other secrets.

直接调用API端点时，请使用
```
userIntent
```
（
```
SWE
```
、
```
PLAN
```
、
```
ASK
```
、
```
DEV_ENVIRONMENT
```
）。
创建任务后，返回
```
task.url
```
，仅在用户请求时轮询/流式传输日志。
如果缺少
```
TWILL_API_KEY
```
，请询问用户。
请勿打印API密钥或其他敏感信息。