Vs Search

Viking Search

When to Use

Use this skill for:

• search query verification
• search scene inspection and updates
• online result checks
• recall or ranking issue diagnosis
• separating persistent scene config from request-only runtime parameters
• fine-grained operations / serving-controls updates, including query-specific search rules

If the user wants automated batch evaluation or similarity tuning across many queries and strategies, use vs-search-tuning instead.

Preconditions

• an application-id is available
• if you will edit a scene, you should preferably know the scene-id
• for fresh apps, be prepared for the runtime not to be ready yet
• the agent should treat the installed CLI behavior as authoritative when help text, skill text, and runtime behavior disagree

Scope

Before changing anything, decide whether the user wants:

• a persistent search strategy change
• a temporary runtime verification
• a readiness diagnosis for a failing app

This skill stays at the search workflow level. Do not embed low-level API field mappings, payload design, or enum interpretation here. When a concrete command needs exact parameters, first consult vs-product-qa.

Commands

• search run: send a production-style search request
• search scene create / search scene list / search scene get: manage search scenes
• search scene update: update scene configuration
• app status / app diagnose: inspect readiness before blaming the query

Workflow

1. Start by determining whether the user wants:

• a persistent search strategy change
• a temporary runtime verification
• a readiness diagnosis for a failing app

2. If the request is a persistent search strategy change, use search scene list/get first and inspect the current scene before mutating it. 3. Before running any concrete command, consult vs-product-qa to confirm the current command behavior and the exact parameter requirements. 4. Use search run for verification requests and search scene update for persistent scene changes. 5. After every scene mutation, immediately read the scene back with search scene get and verify that the intended change is visible online. 6. If a fresh app fails, check app status and then app diagnose. 7. Only after readiness is clear should you focus on recall quality or scene configuration. 8. If the command behavior conflicts with the skill text or --help, trust the installed CLI behavior first, and only then inspect repository code when needed to explain or fix the gap.

References

• references/search-scene-natural-language-routing.md: workflow-oriented mapping from natural-language search-scene requests to the first config area or workflow you should inspect

Customer Environment Principle

• In customer environments, assume repository source code is unavailable.
• Execute tasks using only the installed skills, the packaged vs CLI surface (--help, command output, and observed runtime behavior), and explicit user-provided information.
• Do not rely on reading local repository source files, generated repo snapshots, or implementation details to decide runtime actions.
• If the installed CLI behavior conflicts with a skill, trust the installed CLI behavior first.
• If the skills and the packaged CLI still do not provide enough information to proceed safely, stop and ask the user instead of searching source code.

Constraints

• Before executing any concrete vs ... command in this search workflow, first consult vs-product-qa to verify the current command surface, required flags, payload fields, input format, and allowed values. Only after that check may you finalize parameters and run the command.
• Field name case sensitivity: All dataset field names (used in ShuffleConfig.Rules[].FieldName, ShuffleExpr.field, BoostBuryCondConfig.Rules[].Config.field, FilterConfig.Config.field, AuxiliaryPools[].Filter.field, etc.) are case-sensitive. Never infer or normalize field name casing from the user's natural-language description. Before writing any field name into a config, first look up the exact field name from the dataset schema or data-config via dataset get --id <dataset-id> --full or app dataset-config get --application-id <id> --dataset-id <id> --full, and copy the field name exactly as it appears there (case-for-case). If the field name you have doesn't match any field in the schema, stop and ask the user to confirm which field they mean instead of guessing.
• When an app is bound to exactly one dataset, the CLI can infer dataset-id
• For fresh apps, treat readiness as the first hypothesis before blaming the query
• Prefer public vs search ... commands over bypassing the CLI and calling lower-level APIs directly
• Use search scene update for persistent search behavior and do not invent low-level API mappings inside this skill
• For natural-language scene-change requests, use references/search-scene-natural-language-routing.md as the routing layer; if the target is a rule-resource workflow such as filter-item-scope, do not reduce it to a single inline scene field edit
• Do not assume --help, skill text, and the installed command implementation are perfectly aligned; verify the actual command behavior before making high-risk scene changes
• For scene updates, prefer a readback check after mutation instead of assuming the write succeeded
• If a scene update unexpectedly fails or appears to no-op, verify the accepted command behavior and parameter requirements before retrying
• If a command failure or user follow-up turns into a product concept, capability, API field, purchase, billing, or general troubleshooting question outside this search workflow, temporarily hand off to vs-product-qa; return to this workflow only after the grounded product answer is complete.

Search Scene Natural-Language Routing

This reference is for the vs-search skill. Use it when a user describes a search-scene change in natural language and you need to decide which persistent search-scene area should be updated.

This is a workflow-oriented routing guide, not an API reference. Exact payload structure, field constraints, and allowed values must still be checked against vs-product-qa and the copied API references before executing a concrete command.

Intent Routing

ServingControls Workflow

If the target is ServingControls[], use this workflow:

1. First configure QueryCondition for the serving-control rule, because ServingControls[] is a conditional override workflow rather than a plain inline config block. 2. Then inspect the user's requested override area and map it back to the matching intent in the Intent Routing table above. 3. If that matched intent already has a dedicated workflow, reuse that workflow, but write the final config under Config.SearchConfig.RetrieveConfigs[].ServingControls[] instead of the top-level retrieve-config path. 4. If that matched intent is a direct inline config edit, keep the same payload shape and field semantics as the top-level config area, but change the final write target to the corresponding nested field under ServingControls[].

Interpretation:

• ServingControls[] should be handled as “configure trigger condition first, then apply an override”, not as a flat bag of unrelated fields.
• Nested fields inside ServingControls[] do not define a new config language; they reuse the same config meaning and workflow as the corresponding top-level areas, with only the final write path changed.

FilterConfig Workflow

If the target is FilterConfig, use this workflow:

1. Run recommend rule upsert with --type search_filter, save the filter configuration as a separate rule resource, and capture the returned RuleID from the response. 2. Run recommend rule get --rule-id <id> to fetch that rule again and verify that the stored Config is correct. 3. If the rule was written correctly, run search scene update and write both RuleID and Config into the corresponding scene FilterConfig object:

• Config.SearchConfig.RetrieveConfigs[].FilterConfig.RuleID — the rule reference ID
• Config.SearchConfig.RetrieveConfigs[].FilterConfig.Config — the full filter rule body (same structure as the rule's Config field returned by the rule-get API/command)
• Also applies to Config.SearchConfig.RetrieveConfigs[].ServingControls[].FilterConfig when the target is a serving-control override

Interpretation:

• FilterConfig is a rule-resource workflow, not just an inline scene payload edit.
• The scene stores a RuleID reference rather than the full filter rule body.

Dictionary Binding Workflow

If the request involves associating/uploading/importing/binding a dictionary (词库/词典/关联词库) for synonyms, query recommendation, query completion, or search-term correction, use this workflow.

First, determine the dictionary Type from the target config area:

Then branch based on whether the user provides a CSV/term file or an existing DictId:

Path A — User provides a CSV/term file (new dictionary):

1. Run dict create --name <name> --type <type> to create the dictionary resource, and capture the returned DictId. Select --type from the table above based on which config area the user is targeting. 2. Run dict get --dict-id <id> to confirm the dictionary was created successfully. 3. Run dict write-terms --dict-id <id> --file <file-path> to import dictionary terms. 4. Run dict bind-scenes --dict-id <id> --scenes @scenes.json to bind the dictionary to the target application scenes. For synonyms and correction dictionaries, include DatasetId in each scene entry ({"AppId":"...","SceneId":"...","DatasetId":"..."}).

Path B — User directly provides an existing `DictId`:

1. Skip steps 1–4. Run dict bind-scenes --dict-id <id> --scenes @scenes.json directly to bind the existing dictionary to target scenes.

Interpretation:

• Dictionary binding is a multi-step resource workflow: create dict → verify → dict write-terms --file ... (internal signature + upload) → bind to scenes.
• Do not reduce this to a single inline search scene update payload edit when the user mentions uploading a file, creating a dictionary, importing a word list, or associating a new dictionary.
• When the user only wants to toggle a feature on/off or adjust numeric parameters (e.g. suggestion count, min prefix length, correction mode) without touching the dictionary itself, use the direct search scene update path instead.

Usage Note

Use this file as a routing layer only. For command execution:

1. identify the target action here, 2. consult vs-product-qa, 3. run the concrete command workflow, 4. read the scene back after mutation.

Field name case sensitivity: For any config area that references dataset field names (e.g. ShuffleConfig.Rules[].FieldName, ShuffleExpr.field, BoostBuryCondConfig.Rules[].Config.field, FilterConfig.Config.field, AuxiliaryPools[].Filter.field), field names are case-sensitive. Never infer casing from the user's natural-language description. Before writing a field name into config, first look up the exact field name from the dataset schema via dataset get --id <dataset-id> --full or app dataset-config get --application-id <id> --dataset-id <id> --full, and copy it exactly as it appears. If the field name doesn't match any schema field, stop and ask the user to confirm instead of guessing.