delivery-desk/.agents/skills/upload-delivery-desk-work/SKILL.md

---
name: upload-delivery-desk-work
description: Safely locate the exact Delivery Desk operation group and project, then create a work or submit one new review round through the current API. Use for requests such as 上传作品、新增作品、提交新一轮、更新作品, or any agent upload where group/project/work identity may be ambiguous and a wrong target must be prevented.
---

# Upload Delivery Desk Work

Use a two-phase plan/apply workflow. Optimize for correct placement, not speed.

## Non-negotiable rules

- Treat the product hierarchy as `operation group -> project -> work -> review round`.
- Never use a collection/delivery-set identifier. `collections`, `notes`, and `versions` are legacy compatibility names.
- Never infer a project or work from a partial name, page position, recent activity, or a remembered ID.
- Never create a work until the operator confirms the resolved group, project, content, image order, and confirmation code.
- Never create a new round until the operator confirms the resolved work and current round.
- Never retry a timed-out create request. First inspect current server state; otherwise a retry can create a duplicate round.
- Require `externalId` for every agent-created work. Reuse the same value for safe retries.
- Accept 1-30 public `http`/`https` image URLs. Preserve their order; the first image is the cover.
- Require an active Tencent COS configuration. URLs already using its public or CDN origin are reused; other public images are downloaded and stored in that COS by the API.
- Put API keys only in `DELIVERY_DESK_API_KEY`. Do not paste keys into chat, plans, source files, or command history.
- Prefer a project-scoped API key. A platform key has a wider blast radius and always requires explicit group verification.
- Stop on any mismatch, ambiguity, changed project/work state, or missing input. Ask the operator instead of guessing.

## 1. Classify the operation

Determine exactly one operation:

- `create_work`: create a new work in a project.
- `create_round`: submit the next review round for an existing work.

If the request says “update”, “new version”, or “upload again” without identifying whether it is a new work or a new round, ask which operation is intended.

Do not create groups, projects, API keys, feedback, or review decisions with this skill.

## 2. Collect required information

For both operations, require:

- Delivery Desk base URL. Default to `DELIVERY_DESK_BASE_URL` or `http://127.0.0.1:3010` only for local development.
- A valid API key in `DELIVERY_DESK_API_KEY`.
- Exact target project, resolved to group ID/name and project ID/name/slug.
- Ordered public image URLs.
- Confirmation that the source URLs are reachable until the API finishes importing them. After a cross-origin import succeeds, Delivery Desk uses the resulting COS URL.

For `create_work`, also require:

- A stable caller-generated `externalId` matching `[A-Za-z0-9._:-]{1,128}`.
- Title. Description and tags may be empty only when the operator explicitly intends that.

For `create_round`, also require:

- Work ID. If only an `externalId` is known, discover the work inside the confirmed project first.
- Whether title, description, and tags should be replaced or retained from the current round. Omitted values are retained by the planning script and must be visible in the confirmation summary.

When information is missing, ask one concise question listing only the missing fields. Do not proceed to mutation.

## 3. Discover authoritative IDs

Use the bundled script from the skill directory:

```powershell
$skillScript = ".agents/skills/upload-delivery-desk-work/scripts/delivery_desk_upload.py"
python $skillScript projects
python $skillScript works --project-id 12
python $skillScript inspect-work --project-id 12 --work-id 34
```

Resolution rules:

1. Match IDs first.
2. Validate the project ID against its returned group ID, group name, project name, and slug.
3. If the operator supplied only names, list exact matches with IDs and ask the operator to choose when zero or multiple matches exist.
4. Even with one match, show the resolved identity before creating the plan.
5. For a new round, verify the work belongs to the confirmed project.

Do not silently choose the only project merely because an API key currently exposes one.

## 4. Generate a read-only plan

Create a new work plan:

```powershell
python $skillScript plan-work `
  --project-id 12 `
  --external-id client-2026-001 `
  --title "作品标题" `
  --description "正文" `
  --tag "#夏日" `
  --image-url "https://cdn.example.com/01.jpg" `
  --image-url "https://cdn.example.com/02.jpg" `
  --output tmp/delivery-plan.json
```

Create a new round plan:

```powershell
python $skillScript plan-round `
  --project-id 12 `
  --work-id 34 `
  --image-url "https://cdn.example.com/round-2-01.jpg" `
  --output tmp/delivery-plan.json
```

Optional `plan-round` content flags:

- `--title`, `--description`, and repeated `--tag` replace current values.
- `--clear-description` or `--clear-tags` intentionally clear those fields.
- If omitted, the current round value is retained.

The plan contains no credentials and performs no mutation.

## 5. Obtain explicit confirmation

Show the plan summary exactly, including:

- Operation.
- Group name and ID.
- Project name, ID, and slug.
- Work ID and current/next round for `create_round`.
- `externalId` for `create_work`.
- Title, complete description, complete tag list.
- Ordered image URLs with `1` marked as the cover.
- Confirmation code.

Ask: `确认按以上目标和内容执行吗？请回复“确认 <confirmation_code>”。`

Accept only an explicit confirmation containing the current code. Any content or target change invalidates the old plan; regenerate it and ask again.

## 6. Apply and verify

After exact confirmation:

```powershell
python $skillScript apply `
  --plan tmp/delivery-plan.json `
  --confirm ABCD1234EF56
```

The script re-fetches the project/work, checks for state drift, performs one POST, and reads the created resource back. Treat only a successful verification result as complete.

Report group, project, work ID, `externalId`, created round number, title, image count, and whether the server returned an existing idempotent work.

If the result is `state_unknown`, do not rerun `apply`. Run `inspect-work` and compare server state to the plan. If the result still cannot be proven, ask the operator before any retry.

## API troubleshooting

Read [references/api-contract.md](references/api-contract.md) before calling an endpoint directly, interpreting an error, or changing this skill for a new API version.