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.

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.

   For multi_modal only — Theme resolution (mandatory) — the backend requires a valid Theme. Ask the user to pick one:

   • e_commerce — e-commerce products (with images, price, brand, tags)
   • long_video — long-form video (movies, series; with cover image, language, category)
   • content — general short-form content (posts, news articles with thumbnails, tags, categories)
   • general — other / generic multi-modal (default) If the user cannot decide, default to general. Record the chosen theme in a local variable and pass it to every subsequent command that accepts --theme.

   Source identification:

   • If the user provided a database connection or table name → MySQL.
   • If the user provided a file path ending in .jsonl or described a line-delimited/append-only file → JSONL.
   • If the user provided a file path ending in .json (JSON array) or .csv → JSON/CSV (one-time only).
   • If the source is unclear, ask the user which source type they want to onboard from before proceeding.

   Language: ask for language if the user has not already stated it (zh / en / ko / ja / hi); default to zh for Chinese-speaking users, en otherwise.

   Import mode selection:

   • For MySQL and JSONL, resolve whether the user wants one-time import or one-time + ongoing sync. Only skip the question when the request contains an explicit, unambiguous signal for one side (apply this detection to whatever language the user is writing in — English, Chinese, etc.):
     • Explicit one-time: phrases carrying "once", "one-time", "snapshot only", "just this time", or equivalent single-import semantics.
     • Explicit ongoing: phrases carrying "sync", "keep in sync", "auto-import", "scheduled", "incremental", "keep updated", or equivalent recurring-sync semantics.
   • If the request is neutral — e.g. "import this file", "import this data", bare "import", mentions only a file path with an import verb but says nothing about scheduling/increment/once — you MUST ask the user to choose. The bare import verb is NOT a one-time signal; it is ambiguous. Never silently default to one-time.
   • For JSON (array) and CSV, only one-time import is supported. No question needed.

   After the dataset type, source type, theme (if multi_modal), language, and mode are confirmed, follow the matching branch:

   • MySQL — one-time import: identify the table name, infer dataset name and primary key, and require explicit confirmation before any real write. Continue at step 2.
   • MySQL — ongoing sync: same as above, plus the user must explicitly confirm the incremental cursor field itself. After step 10 continue at step 11.
   • MySQL — existing dataset — ongoing sync: validate the dataset with vs dataset get --id <DatasetId> --full, confirm the source config (especially the incremental cursor field), then jump directly to step 11.
   • JSONL file — one-time import: confirm the file path. Continue at step 2.
   • JSONL file — ongoing sync: confirm the file path. You MUST also interactively ask the user to confirm that new records will only be appended to the end of the file (append-only). Present the constraint clearly — sync only supports files that grow by adding new lines; edits or deletions of existing lines are not tracked and may cause duplicate or missing records. Wait for explicit user confirmation before proceeding. After step 10 continue at step 11.
   • JSON (array) or CSV file — one-time import: confirm the file path. These formats are one-time import only; ongoing sync is not supported because they do not provide a stable append-only cursor. Convert the input to JSONL (one JSON object per line) before continuing. Continue at step 2.
   • Existing dataset + one-time source import: not supported as a single workflow. Explain that the current CLI split supports either source export → new dataset onboarding for a one-time import, or background sync for ongoing updates, then let the user choose which branch to switch to.

   Source environment configuration (applies to MySQL branches only; local files require no credentials):

   • MySQL uses these environment variables by default: MYSQL_HOST, MYSQL_PORT, MYSQL_USER, MYSQL_PASSWORD, MYSQL_DATABASE (optional: MYSQL_CHARSET).
   • Render a bash export template snippet with placeholder values (for example MYSQL_PASSWORD=your_password) and ask the user to fill in real values in their own terminal or shell session, then run export on each variable.
   • Never display actual database credential values in chat. Never ask the user to paste or submit database credentials into the chat dialog.
   • Never list "connection config" / "连接配置" blocks with concrete host/user/password values inside the chat. The only allowed format is a bash template with placeholder values.
   • The export, init, and run commands read MySQL credentials only from environment variables. They do not accept credentials via flags or chat input.
   • This is a human checkpoint. Wait for explicit confirmation that the local source environment is configured before proceeding.

2. Export source snapshot to JSONL — run vs connector export for the selected source to produce a bootstrap JSONL file:

   • MySQL: vs connector export --source mysql --source-table <table> --id-field <field> --cursor-field <field> [other flags]
   • Local file: vs connector export --source jsonl --file <path/to/items.jsonl> [other flags] (convert JSON arrays or CSV to JSONL first if needed)

   The bootstrap file is always written to /tmp/viking/connector/<job>/bootstrap/items.jsonl. Do not use --output to try to override that path; --output only redirects the rendered command result. After export, use the emitted items.jsonl as the input file and continue at step 3.

3. Get upload URL — vs dataset import-url --file-name <basename>. Capture Result.FileUrl and Result.FileKey. Keep FileKey for step 5.

4. PUT upload — upload the raw item file to FileUrl (e.g. curl -X PUT --data-binary "@<local-path>" "<FileUrl>"). Expect HTTP 200 with empty body. Do not add an Authorization header — FileUrl is already presigned.

5. Submit inference task — vs dataset infer-schema --tos-key <FileKey> --type <multi_modal|user_event> --theme <general|e_commerce|content|long_video> --language <lang> --name <dataset-name>. For user_event, omit --theme. For multi_modal, --theme is required (default general). Theme values accept alias normalization: ecommerce/e-commerce → e_commerce, long-video/longvideo → long_video, common/default → general. Capture Result.TaskId.

6. Poll inference result + persist locally — vs dataset infer-result --task-id <TaskId> until Result.Status === "succeeded" (poll roughly every 5s, max ~3 minutes). Then write Result verbatim to a workspace-relative artifact file so the rest of the workflow can read from it.

   Plan directory rules (important):

   • Must write to the workspace-relative path: ./.viking/item-plans/<dataset-name>/infer-result.json (i.e. <cwd>/.viking/item-plans/<dataset-name>/...).
   • Forbidden to write anywhere under ~/.viking/ (i.e. $HOME/.viking/). ~/.viking/ is the vs CLI's private config / credentials directory (config.json, credentials.json.enc), not a plan dir. Many agent hosts place ~/ outside the sandbox, so writes there fail with EPERM: operation not permitted; even when they succeed, your plan files end up mixed with the CLI's private files.
   • If the workspace root is not writable (e.g. the sandbox only allows temp dirs), fallback priority is ${WORKSPACE_DIR}/.viking/item-plans/<dataset-name>/ → ${TMPDIR}/viking-item-plans/<dataset-name>/ → ./viking-item-plans/<dataset-name>/. Never redirect to the home directory ~/.viking/.
   • Once the plan dir is decided, store it in a local variable (e.g. WORK) and reuse the same path across steps 8/9/10/13. Do not switch plan dirs between steps.

   This single artifact is the source-of-truth for every subsequent step. Do not regenerate it; do not edit BizAttr (those drive PK / title / URL detection on the backend). If the user requests semantic edits (e.g. tweak a FieldDescMap description, reorder IndexFields), edit this file in place and reuse it.

7. Schema Confirmation (mandatory) — show the persisted artifact to the user using the CLI's deterministic renderer, then surface it verbatim. (Historically called "Stage A".)

   vs dataset validate-schema --input ./.viking/item-plans/<dataset-name>/infer-result.json --dataset-type <multi_modal|user_event>
   

   The CLI emits a fixed block (Metadata / Fields / Field Roles / Warnings for multi_modal; Metadata / Fields / Warnings for user_event) wrapped between <!-- vs-schema-confirm: BEGIN --> and <!-- vs-schema-confirm: END --> markers. It uses a real markdown table for fields (with backticked types like `array<string>` so chat UIs do not eat the angle brackets), and fenced code blocks for the other sections. The output tolerates Name/FieldName, Type/FieldType, missing Required/BizAttr/Description, and missing or incomplete DataFieldConfig. The output is byte-stable: re-running the same file with the same --dataset-type always produces identical bytes.

   Your message to the user MUST be exactly this template (BEGIN/END markers included, three parts only):

   Dataset <Name> · type=<multi_modal|user_event> · <theme=<Theme> if multi_modal>
   
   <verbatim CLI stdout from the BEGIN marker through the END marker, character-for-character>
   
   <one-line confirmation prompt, written in the user's language — see Language Matching above and the templates below>
   

   Confirmation prompt — pick the template matching the user's most recent message language. Do not paste the English template verbatim if the user is writing in Chinese.

   • 中文（用户说中文时使用，默认）： 以上是 Schema 确认块。回复 \yes` 继续，或说明需要调整的字段（例如：把 `description` 加入文本检索字段、把 `brand` 加入 SuggestFields）。`
   • English (when the user is writing in English): This is the Schema Confirmation block. Reply \yes` to continue, or describe which fields to adjust (e.g. "make `description` searchable", "add `brand` to SuggestFields").`
   • 日本語 / その他言語：translate the same intent, keep the token `yes` verbatim and keep field names / JSON keys (description, SuggestFields, ...) in English.

   You MUST:

   • Copy the CLI stdout between (and including) the <!-- vs-schema-confirm: BEGIN --> and <!-- vs-schema-confirm: END --> markers character-for-character.
   • Surface the one-line metadata header above, the verbatim CLI block in the middle, and the one-line confirmation prompt at the bottom — exactly three parts, in that order.
   • Wrap type values in backticks if you ever need to mention them outside the CLI block (e.g. `array<string>`). Chat UIs treat unwrapped <…> as HTML and silently drop them.

   You MUST NOT:

   • Re-render the field table yourself (no hand-typed markdown table, no bullet list of fields).
   • Replace the CLI block with a summary like "see CLI output above" / "tool result has full details". Tool-call output is collapsed by default in most chat clients — the user only sees what is in your own message.
   • Add extra commentary, bullet lists, "key fields are …" highlights, or any interpretation between the BEGIN/END markers.
   • Drop or trim the **Warnings (N)** section even when N is 0; deterministic structure beats brevity.

   Wait for an explicit positive confirmation (yes or equivalent) before moving to step 8. If the user requests changes, edit the persisted infer-result.json in place (do not re-run inference) and re-run vs dataset validate-schema --input ./.viking/item-plans/<dataset-name>/infer-result.json --dataset-type <type>, then re-emit the same three-part template so the user sees the same deterministic structure.

8. Behavior type confirmation (user_event only) — for multi_modal datasets, skip this step entirely and go straight to step 9.

   For user_event datasets, the event_type field requires an EnumerateMeta array that maps every distinct raw event value found in the data to a standard behavior type (EnumerateBizAttr). Every distinct event_type value present in the data MUST have a corresponding entry in EnumerateMeta (no blanks, no unbound values). Additionally, the backend requires at least one entry mapped to exposure (Required: true) and at least one non-exposure positive behavior. Without this the create call fails validation.

   Every distinct event_type value present in the data MUST have a confirmed mapping before proceeding. The agent infers a best-guess mapping semantically, presents it to the user with a standard-type reference labeled in the user's language, and only proceeds after explicit confirmation.

   Internal standard types reference (agent uses this to convert user-confirmed labels to EnumerateBizAttr codes when serializing the payload):

   中文标签	English label	日本語ラベル	한국어 라벨	हिन्दी लेबल	EnumerateBizAttr (code)	Name handling
   曝光	Exposure / Impression	露出 / インプレッション	노출	इम्प्रेशन / दिखना	exposure	auto — use standard label
   点击	Click	クリック	클릭	क्लिक	click	auto — use standard label
   收藏	Collect / Favorite / Save	お気に入り / 保存	저장 / 즐겨찾기	सेव / पसंद	collect	auto — use standard label
   分享	Share	シェア	공유	शेयर	share	auto — use standard label
   点赞	Like / Thumbs-up	いいね	좋아요	लाइक	like	auto — use standard label
   加购	Add to cart	カート追加	장바구니 추가	कार्ट में जोड़ें	add_to_cart	auto — use standard label
   下单	Place order / Order	注文	주문	ऑर्डर	order	auto — use standard label
   购买	Purchase / Buy / Pay	購入 / 購入完了	구매	खरीद / भुगतान	purchase	auto — use standard label
   访问	Visit / Detail page view	アクセス / 閲覧	방문 / 상세보기	विज़िट / विवरण देखना	visit	auto — use standard label
   自定义	Custom (user-defined)	カスタム	커ス텀	कस्टम	custom	user must provide a display name

   Procedure:

   a. Extract ALL distinct event_type values from the entire bootstrap JSONL file (read the whole file — do NOT sample only the first N lines, every value must be accounted for):

   jq -r '.event_type // empty' <bootstrap.jsonl> | sort -u
   

   b. Infer a best-guess mapping for each distinct raw value to one of the 10 standard types above. Use semantic understanding of the user's language and data context. Negative-feedback values (e.g. 不喜欢, 差评, dislike, 负反馈) should map to custom.

   • Do NOT force a guess. If a value is ambiguous, domain-specific, abbreviated, in an unexpected language, or you are genuinely unsure, mark it as "待确认 / to be confirmed" and leave it for the user to pick — do NOT default it to custom as a lazy fallback. custom is only for values that you are confident represent user-defined or negative-feedback behaviors.
   • It is always better to mark a value as "待确认" and let the user correct it than to force a wrong mapping.

   c. Present the confirmation prompt to the user in their language. When rendering labels, use ONLY the column from the reference table that matches the user's language (do NOT dump all five languages unless the user explicitly asks). The prompt MUST contain:

   (1) The value-to-type mapping table — left column: every distinct event_type value from the data; right column: your suggested standard type label (natural language in the user's language, not code). Every row must show a suggested type or be explicitly marked as "待确认 / to be confirmed" (do NOT silently guess, and do NOT blindly default uncertain values to custom). For values mapped to "自定义 / Custom", include an additional column for the user to specify a custom display name. At least one value must map to the exposure type. Example for Chinese data:

   event_type 行为类型映射确认
   
   从数据中检测到 <N> 个不同的 event_type 值。每个值都需要绑定到一个标准行为类型（全部必填），且至少有一个值映射为「曝光」。映射为「自定义」的值还需要提供一个显示名称。请确认以下映射：
   
   | 数据中的 event_type 值 | 映射到的标准行为类型 | 自定义显示名称（仅自定义类型需要填写） |
   |---|---|---|
   | 曝光    | 曝光 | — |
   | 点击    | 点击 | — |
   | 分享    | 分享 | — |
   | 加购    | 加购 | — |
   | 下单    | 下单 | — |
   | 不喜欢  | 自定义 | 不喜欢 |
   | 点赞    | 点赞 | — |
   | 访问    | 访问 | — |
   | 购买    | 购买 | — |
   | 收藏    | 收藏 | — |
   

   (2) The standard types reference (in the user's language only — Chinese example shown; for English/Japanese/Korean/Hindi users, use the corresponding column from the reference table above). Note: every value in the mapping table must be bound to one of these types (i.e. all rows are required); at least one value must be mapped to 曝光 / Exposure; values mapped to 自定义 / Custom require a user-provided display name:

   标准行为类型	说明
   曝光	内容/商品曝光、展现、PV、impression（至少需要一个）
   点击	点击、tap
   收藏	收藏、favorite、save
   分享	分享、share
   点赞	点赞、like、thumbs-up
   加购	加入购物车、add to cart
   下单	提交订单、order、checkout
   购买	购买、支付、purchase、pay
   访问	访问、浏览详情页、visit、detail view
   自定义	其他自定义行为（包括负反馈如不喜欢/差评/dislike），需要提供显示名称

   End the prompt with: "回复 yes 确认以上映射，或告诉我需要修改的项（例如：'把 不喜欢 改成 点赞'，'xxx 是 曝光'，'yyy 作为自定义，名称为 zzz'）。" (For non-Chinese users, translate the confirmation prompt to their language accordingly.)

   d. Wait for explicit user confirmation. If the user provides corrections (including custom names), update the mapping table and re-present it. Do not proceed until every raw value has a confirmed mapping AND every custom-mapped value has a user-provided display name. If no value maps to exposure after confirmation, remind the user that at least one exposure-mapped value is required and ask them to re-examine their data.

   e. After confirmation, serialize the mapping as the EnumerateMeta array on the event_type field in dataset-create.json (step 9). Convert each confirmed natural language label back to its EnumerateBizAttr code using the internal reference table at the top of this step. Each entry looks like:

   {
     "EnumerateValue": "<raw value from data>",
     "Name": "<display name>",
     "EnumerateBizAttr": "<canonical code>",
     "Required": true
   }
   

   • For the 9 standard types (exposure/click/collect/share/like/add_to_cart/order/purchase/visit), Name is the standard label in the dataset language (e.g. "曝光" for Chinese, "Click" for English).
   • For custom, Name is the user-provided display name (e.g. "不喜欢", "Dislike").
   • The entry with EnumerateBizAttr: "exposure" must have Required: true; all other entries also use Required: true.
   • If multiple raw values map to the same EnumerateBizAttr, include separate entries for each raw value.

9. Dry-run create — build dataset-create.json directly from the persisted artifact: copy Schema as-is (do not flip IsPK; the backend derives PK from BizAttr), copy DataFieldConfig.FieldDescMap as FieldDescMap, fill in Name / Type / Language / Description, then for multi_modal also set Theme and optionally ProcessConfig. For user_event, the event_type Schema entry must include the confirmed EnumerateMeta array from step 8. Set DryRun: true. Run vs dataset create --data @dataset-create.json --dry-run. Surface any validation errors and pause for correction.

   For multi_modal — standard payload shape:

   {
     "Name": "<dataset-name>",
     "Type": "multi_modal",
     "Description": "<one-line description>",
     "Language": "zh",
     "Theme": "<general|e_commerce|content|long_video>",
     "Schema":       <copy from infer-result.json Schema>,
     "FieldDescMap": <copy from infer-result.json DataFieldConfig.FieldDescMap>
   }
   

   For user_event — omit Theme and ProcessConfig. The event_type field in Schema MUST include the confirmed EnumerateMeta array from step 8:

   {
     "Name": "<dataset-name>",
     "Type": "user_event",
     "Description": "<one-line description>",
     "Language": "zh",
     "Schema": [
       ...,
       {
         "Name": "event_type",
         "Type": "string",
         "BizAttr": "user_event_event_type",
         "Required": true,
         "EnumerateMeta": [
           { "EnumerateValue": "<raw-exposure-value>", "Name": "曝光", "EnumerateBizAttr": "exposure", "Required": true },
           { "EnumerateValue": "<raw-click-value>", "Name": "点击", "EnumerateBizAttr": "click", "Required": true },
           ... (one entry per confirmed event type)
         ]
       },
       ...
     ],
     "FieldDescMap": <copy from infer-result.json DataFieldConfig.FieldDescMap>
   }
   

10. Real create — re-run step 9 without DryRun. Capture Result.Dataset.Id as DatasetId and persist it next to the artifact (e.g. ./.viking/item-plans/<dataset-name>/dataset.json).

11. Write data — vs data write --dataset-id <DatasetId> --fields @/tmp/viking/connector/<job>/bootstrap/items.jsonl to push the records from the bootstrap JSONL file. Expect a request_id in the response.

12. (Ongoing sync mode only) Start background incremental sync — run vs connector init --name <job> --source <mysql|jsonl> --dataset-id <DatasetId> ... to persist the job config, then vs connector run --job <job> --daemon to start the background sync. For MySQL, pass --source-table, --id-field, --cursor-field; for local files, pass --file <path>. In the hand-off, surface job, pid, trace.ndjson, imported-records.log, vs connector status --job <job>, and vs connector stop --job <job>. Skip this step for one-time import workflows.

13. Optional: create application — only if the user explicitly asks for app-level setup: vs app create --name <app-name> --description "<text>" --industry <alias> --language <lang>. Capture Result.Application.Id as AppId.

14. Optional: attach dataset — read DataFieldConfig straight from the persisted artifact and assemble:

    {
      "ApplicationId": "<AppId>",
      "DatasetId":     "<DatasetId>",
      "DataConfig":    <copy from infer-result.json DataFieldConfig>
    }
    

    Then call vs app attach-dataset --data @attach.json. Empty Result means success. This is the moment where the IndexFields/FilterFields/etc. captured in step 6 are actually applied — never reinvent these arrays from the schema; always pull them from the persisted artifact.

15. Hand-off — print console links + readiness reminder (mandatory). After the last successful step (data write, background sync start, or attach when the app branch ran), the agent must render a short summary block telling the user (a) where to monitor readiness in the console, and (b) that runtime APIs (search, chat, recommend) can only be exercised once readiness reports OK. Pick the console host from the active profile's baseUrl / controlPlaneBaseUrl, and assemble URLs using these exact path templates (do not invent other paths like /dataset/detail/<id> or /application/detail/<id> — those are wrong):

    • Host contains volcengineapi.com / volces.com → Volc Engine, base = https://console.volcengine.com/aisearch/platform/region:aisearch-platform+<region>. <region> is the active profile region (e.g. cn-beijing).
      • Dataset URL: <base>/home/dataset/<DatasetId>
      • App URL: <base>/app/<AppId>
    • Host contains byteplus.com → BytePlus, base = https://console.byteplus.com/aisearch/region:aisearch+ap-southeast-1 (BytePlus today only exposes the ap-southeast-1 region; do not fabricate other regions).
      • Dataset URL: <base>/home/dataset/<DatasetId>
      • App URL: <base>/app/<AppId>

    Print the URLs only for the resources that actually exist in this run (dataset is always present; app/attach are only present if the user opted in). Render the prose lines (✓ markers, readiness reminder, runtime-API tip) in the user's current language per the Language Matching rule; keep IDs and URLs verbatim.

    Template (translate the labels per the table below; keep DatasetId=..., AppId=..., URLs, and vs ... commands verbatim):

    ✓ <DATASET_LABEL>: DatasetId=<DatasetId>
      <LINK_LABEL>: <dataset console URL>
    
    ✓ <APP_LABEL>: AppId=<AppId>            # only when the app branch ran
      <LINK_LABEL>: <app console URL>       # only when the app branch ran
    
    ✓ <SYNC_LABEL>: job=<job>  pid=<pid>    # only when source-backed sync mode ran
      <TRACE_LABEL>: <trace path>
      <LOG_LABEL>: <import log path>
      <STATUS_CMD>: vs connector status --job <job>
      <STOP_CMD>: vs connector stop --job <job>
    
    <READINESS_NOTE>
    <RUNTIME_NOTE>
    

    Per-language label table:

    Slot	中文 (default)	English	日本語
    <DATASET_LABEL>	数据集已创建	Dataset created	データセットを作成しました
    <APP_LABEL>	应用已创建并绑定数据集	Application created and dataset attached	アプリケーションを作成しデータセットを紐付けました
    <LINK_LABEL>	控制台链接	Console link	コンソールリンク
    <SYNC_LABEL>	后台同步已启动	Background sync started	バックグラウンド同期を開始しました
    <TRACE_LABEL>	trace 文件	trace file	トレースファイル
    <LOG_LABEL>	导入日志	import log	インポートログ
    <STATUS_CMD>	查看状态	check status	ステータス確認
    <STOP_CMD>	停止同步	stop sync	同期停止
    <READINESS_NOTE>	数据需要后台处理后才能查询。请打开上面链接关注数据集 / 应用的「生效状态」（Ready）。	Data must finish backend processing before it is queryable. Open the links above and watch for the "Ready" state on the dataset / application.	データが利用可能になるにはバックエンド処理の完了が必要です。上記リンクからデータセット / アプリケーションの「Ready」状態を確認してください。
    <RUNTIME_NOTE>	生效之后即可使用 `vs search`、`vs chat`、`vs recommend` 等运行时接口进行体验。	Once they report Ready, you can exercise the runtime APIs via `vs search`, `vs chat`, `vs recommend`.	Ready になると `vs search` / `vs chat` / `vs recommend` などのランタイム API を利用できます。

    For other languages, translate the same intent and keep IDs / URLs / vs ... commands verbatim. The agent must surface this block as the final output of the workflow; do not omit it even if the user has not asked. If only the dataset was created (no app branch, no sync), still print the dataset link and the readiness reminder (chat / search will require attaching to an app afterwards).

Enum Reference

enum fields are strings. Pass the CLI alias (case-insensitive) and let the CLI normalize to the backend wire value.

Do not pass numeric codes to any V2 API. The CLI keeps a one-way alias map and an int→string fallback for legacy payloads, but agents should emit strings only.

Backend-driven Primary Key

In V2, the agent does not set the primary key. The backend computes IsPK from BizAttr (truthy when BizAttr ∈ {multi_modal_id}) regardless of the IsPK value on the wire. Schema inference already assigns the right BizAttr, so:

• Forward the inferred Schema to CreateDatasetV2 verbatim. IsPK can stay false everywhere.
• Never strip / rewrite BizAttr. Doing so will cause the backend's pkCount==1 check to fail.
• If inference returned no field with a PK-class BizAttr (very rare; usually means the input file has no obvious identifier column), surface that to the user in the Schema Confirmation block (the CLI's **Warnings (N)** section already calls it out) — they likely need to fix the source data, not patch the schema by hand.

V2 API Surface (reference)

…(truncated)