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.
- At the start of every invocation, discover and explicitly ask the operator to confirm the exact operation group and project. A target confirmation from an earlier invocation cannot be reused.
- 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 either 1-30 public `http`/`https` image URLs or 1-30 local image files. Never mix both modes in one plan. Preserve 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.
- Upload local files as `multipart/form-data` from the bundled script. Never read image bytes into the conversation, print Base64, or put binary data in the plan.
- 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:

- Use the fixed Delivery Desk API address `http://192.168.30.90:3010`. Do not ask the operator to configure it. Use `--base-url` only when the operator explicitly instructs you to migrate or test another environment.
- 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 or ordered local image paths.
- For URL mode, confirmation that source URLs remain reachable until import finishes.
- For file mode, confirmation that files remain unchanged until apply. The plan records absolute path, byte size, SHA-256, and content type; it never records image bytes.

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 and confirm the authoritative target

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 when the request already names a target or only one project is accessible, show the resolved group name/ID and project name/ID/slug and ask: `本次操作目标是否为：运营组「<group_name>」(ID <group_id>) / 项目「<project_name>」(ID <project_id>, slug <slug>)？请回复“确认目标”。`
5. Accept only an explicit target confirmation given during the current invocation. Do not generate `plan-work` or `plan-round` before it.
6. 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
```

Use local files instead of URLs:

```powershell
python $skillScript plan-work `
  --project-id 12 `
  --external-id client-2026-002 `
  --title "本地生成作品" `
  --image-file "D:\generated\01.png" `
  --image-file "D:\generated\02.png" `
  --output tmp/delivery-plan.json
```

Use repeated `--image-url` or repeated `--image-file`, never both. Local files must be JPEG, PNG, GIF, WebP, or AVIF, each no larger than 20 MB.

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, or local file path/name/size/SHA-256, 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, revalidates local file hashes when applicable, performs one POST, and reads the created resource back. Local files are streamed by the script as multipart and never enter model context. 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.

## Failure actions

On failure, the script exits with code `1` and writes one JSON object to stderr:

```json
{"success": false, "action": "revise", "error": "...", "next_step": "..."}
```

Follow `action` exactly:

- `retry`: Retry only the same read-only command, with the same target and parameters, after completing `next_step`. Never reinterpret this as permission to retry `apply`.
- `revise`: Change only the invalid input identified by `error`, regenerate the plan, show the full changed plan, and obtain a new confirmation code before `apply`.
- `ask_operator`: Stop. Show the exact target, `error`, and `next_step` to the operator or administrator. Do not change targets, permissions, project state, or credentials yourself.

If output is `state_unknown`, it is always `ask_operator`: inspect current server state first and never automatically repeat the write.

## 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.