volcengine/searchcli/vs-item-onboarding

Viking Item Onboarding

Language Matching (apply throughout)

Match the language of the user's most recent message in every line of prose you write — confirmation prompts, status notes, hand-off summaries, questions, error explanations, and any internal thinking / reasoning / planning output that the host may surface (e.g. `<thinking>` blocks, "thinking" panels, scratchpad notes, todo descriptions). If the user is writing in Chinese, every prose line and every reasoning line must also be in Chinese; if English, English; same for Japanese, etc. The fact that this skill file is written in English is for documentation only — at runtime translate all prose and reasoning into the user's language. Do not switch back to English mid-flow just because the surrounding skill text is English.

Chinese-user priority (the most common case) — when current_query or the most recent user message is in Chinese:

• All prose you write for the user (confirmation prompts, status notes, error explanations, final hand-off summaries) must be in Chinese.
• All internal thinking / reasoning / planning output (thinking blocks, scratchpad, todo descriptions) must also be in Chinese.
• For workspace artifacts you create, the description / comment portions (excluding CLI-contract English identifiers) should also prefer Chinese.

Do not translate the following — keep them verbatim so the contract stays machine-checkable:

• The verbatim CLI block between <!-- vs-schema-confirm: BEGIN --> and <!-- vs-schema-confirm: END --> (English section labels **Metadata** / **Fields (N)** / **Field Roles** / **Warnings (N)** and English warning text come straight from the CLI).
• CLI command names, flag names, JSON keys, enum values, field names, primary-key BizAttr identifiers (multi_modal_id), dataset IDs / app IDs / TaskIDs, and console URLs.
• The single literal token the user must reply to confirm — write it as ` yes in any language so the contract for advancing to step 8 is unambiguous (you may add a parenthetical native-language hint, e.g. 回复 \yes\（即"确认"）继续`).

If you are unsure which language the user used (e.g. only emoji or only an attachment), default to the language of the very first user turn in the conversation. When the user switches languages mid-flow, switch with them on the next message.

When to Use

Use this skill when the user is operating against the V2 control-plane (/open/*V2) and wants to onboard a dataset (optionally followed by an application) from either:

• a local JSONL file, either as a one-time import or with ongoing incremental sync for append-only files (e.g. crawler output where new lines are continuously appended);
• a local JSON (array) or CSV file, as a one-time import only (ongoing sync is not supported for these formats);
• a MySQL database, either as a one-time snapshot import or with ongoing incremental sync.

Supported dataset types:

• `user_event` — user behavior / event logs (click, view, exposure, collect, etc.) used for recommendation and personalization scenarios.
• `multi_modal` — everything else: records that contain image URLs and/or video URLs alongside text fields (e.g. e-commerce goods with images, short-video posts, content with thumbnails, multimodal search corpora), as well as plain-text corpora without media. If the data is not behavior logs, it goes here.

The hallmark of V2 is that schema inference is fully backend-driven: the CLI uploads the file, the backend infers the Schema (with BizAttr already set on the primary-key / title / URL / event-type fields) plus a per-field FieldDescMap, and the agent's only jobs are to (a) persist that inference artifact locally, (b) render it for one round of human confirmation, and (c) drive the remaining persistence + ingest steps without re-inventing field decisions.

For parent/variant item datasets, schema inference may assign paired ItemType / ParentId BizAttrs such as ImageItemType + ImageParentId or multi_modal_item_type + multi_modal_parent_id. These fields must be treated as a pair: ItemType identifies parent vs variant/child items, and ParentId points a variant/child item to its parent. If the Schema Confirmation warnings report that only one side was inferred, do not patch BizAttrs by hand; fix the source data or field meanings and re-run inference.

Do not use this skill when:

• The customer only wants to ingest more rows into an existing dataset (use vs data write --dataset-id <id> --fields @items.jsonl; --fields accepts a JSON array or a JSONL file directly).

Do NOT be misled by vs --help top-level QUICK START

vs --help still lists vs item profile / plan / apply at the top of QUICK START for backwards compatibility (annotated [Deprecated]). That is the V1 path; this skill does not use it. The only legal path here is V2 — vs dataset import-url → infer-schema → infer-result → dataset create → data write → app create → app attach-dataset — and any check for a V2 command must be confirmed via vs dataset --help, vs dataset infer-schema --help, vs app --help, or vs app attach-dataset --help, never by falling back to vs item .... The workspace path ./.viking/item-plans/<dataset-name>/ is reused for V2 artifacts only because the directory name happens to match; it does not imply V1 or item type. The moment the user's ask is "create a multi-modal dataset / application from a raw JSONL / JSON / CSV / MySQL source", jump straight to the V2 workflow (steps 3–14 below) without detouring through item plan/apply.

Forbidden in this skill: passing any --type other than multi_modal or user_event to dataset onboarding commands.

Version Check

Before starting this skill workflow, run vs version check --json. Continue only when status is up-to-date. If status is update-available, stop and tell the user to update the cloned vs repository, then run git pull --ff-only, bash ./scripts/install.sh, and bash ./scripts/install-skills.sh all --target auto --force (PowerShell: scripts/install.ps1 and scripts/install-skills.ps1). If the status is unknown, stop and report that the CLI version could not be verified.

Preconditions

• vs CLI ≥ 0.2.0 installed, authentication is complete (vs auth status and vs doctor succeed).
• Input file is JSON array, JSONL, or CSV and is readable from a local path.
• The user has stated a business goal (e.g. "Build catalog search", "Build content search").
• The customer's account is provisioned for the V2 control-plane.

Commands

The "All-in-one" shortcut vs dataset ingest --file <path> --type multi_modal --theme <theme> [--abnormal-image-policy skip|block] [--abnormal-video-policy skip|block] [--video-auto-delete] [--post-paid-type <standard|premium>] [--dry-run] orchestrates upload + infer-schema + poll + create + write, without the Schema Confirmation pause. In agent mode you should still drive each step individually so you can pause at step 7 (Schema Confirmation).

Workflow

Run strictly in order. Each step depends on output from the previous one; an inference artifact persisted in step 6 is reused all the way through step 13.

1. Confirm dataset type, input source, and mode — first determine the dataset type, then identify the source type, then explicitly ask the user to choose the import mode when multiple options exist. Do not silently pick any of these.

Dataset type resolution — ask the user which dataset type they want to create:

• `multi_modal` — records with image URLs and/or video URLs plus text fields (e-commerce goods, short-video posts, content with thumbnails, etc.).
• `user_event` — user behavior / event logs (click, view, exposure, collect, etc.) for recommendation and personalization.

If the user's request clearly describes behavior logs / event data / recommendation data → user_event; if it clearly describes goods / content with images or video → multi_modal; if ambiguous, ask.