a1-yandex-kit-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

A1 Yandex KIT Setup

A1 Yandex KIT 设置

Communication

沟通规范

Before producing any user-facing message, read and apply

../a1-yandex-kit/references/merchant-communication.md

completely.

Make setup a concierge flow for typed requests and voice transcriptions alike. Start from the branch that invoked it:

For the short orientation request

Связь с магазином

, ask one question:

Что сделать: подключить магазин или переподключить его с новым токеном?

A concrete request to connect or reconnect authorizes updating the selected client's user-level MCP configuration after the required inputs are collected and the candidate token passes validation. Reinstalling the connection and changing the token are both reconnection requests.

A project-local skill installation does not limit the configuration to that project.

Use

scripts/setup.mjs

for configuration and the direct read-only smoke test. Resolve every relative path from this skill directory, not from the user's project.

在生成任何面向用户的消息之前，请完整阅读并应用

../a1-yandex-kit/references/merchant-communication.md

中的内容。

为打字请求和语音转录请求都设置管家式流程。从触发该流程的分支开始：

对于简短的导向性请求

Связь с магазином

（连接商店），询问一个问题：

您需要执行什么操作：连接商店还是使用新Token重新连接？

明确的连接或重新连接请求，在收集完必要输入且候选Token通过验证后，授权更新所选客户端的用户级MCP配置。重新建立连接和更换Token均属于重新连接请求。

项目本地的Skill安装不会将配置限制在该项目内。

使用

scripts/setup.mjs

进行配置和直接只读冒烟测试。所有相对路径均从本Skill目录解析，而非用户项目目录。

1. Identify the client and prerequisite

1. 识别客户端与前置条件

Infer the current client from the host when it is clear. Otherwise ask one short question:

В каком приложении вы сейчас хотите подключить Яндекс KIT?

Normalize the answer to one of:

claude-code

claude-desktop

cursor

codex

vscode

kimi

kimi-desktop

hermes

openclaw

Treat Kimi Code and Kimi Desktop as different clients. Use

kimi

only for the Kimi Code CLI and

kimi-desktop

for the Kimi Work desktop application. When the user says only “Kimi” and the host does not disambiguate it, ask:

Вы используете приложение Kimi на компьютере или Kimi Code в терминале?

For a tested client, run:

bash

node "<skill-directory>/scripts/setup.mjs" status --client <client> --json

status

verifies both Node.js 20+ and an executable

npx

before any token is requested or any config is changed. If either prerequisite is unavailable, give one exact Node.js installation link or instruction appropriate to the operating system and stop. Leave installation to that operating-system installer. For another client, run the independent preflight and continue to the compatibility ladder in step 2:

For Claude Code, Cursor, VS Code and Kimi Code,

status

also checks whether a known project- or local-scope server named

yandex-kit

would override the user-level entry. On an exact-name collision it selects the managed fallback name

a1-yandex-kit-global

. It ignores every differently named MCP server. A previously configured canonical fallback stays selected on later runs.

bash

node "<skill-directory>/scripts/setup.mjs" preflight --json

Run

status

later only when the ladder establishes a supported format and path. This step is complete when Node.js 20+,

npx

and one client are identified.

当主机信息明确时，从中推断当前客户端。否则询问一个简短问题：

您现在想要在哪个应用中连接Yandex KIT？

将答案标准化为以下选项之一：

claude-code

claude-desktop

cursor

codex

vscode

kimi

kimi-desktop

hermes

openclaw

。

将Kimi Code和Kimi Desktop视为不同的客户端。

kimi

仅用于Kimi Code CLI，

kimi-desktop

用于Kimi Work桌面应用。当用户仅提及“Kimi”且主机未明确区分时，询问：

您使用的是电脑上的Kimi应用还是终端中的Kimi Code？

对于已测试的客户端，运行：

bash

node "<skill-directory>/scripts/setup.mjs" status --client <client> --json

status

命令会在请求Token或修改任何配置之前，验证Node.js 20+版本和可执行的

npx

是否存在。如果任一前置条件不可用，提供一个适合操作系统的Node.js安装链接或具体指令，然后停止流程。将安装操作交由对应操作系统的安装程序处理。对于其他客户端，运行独立的预检命令，然后进入步骤2的兼容性阶梯：

对于Claude Code、Cursor、VS Code和Kimi Code，

status

命令还会检查是否存在名为

yandex-kit

的项目级或本地作用域服务器，该服务器可能会覆盖用户级条目。如果存在完全同名的冲突，将选择托管备用名称

a1-yandex-kit-global

。忽略所有名称不同的MCP服务器。之前配置的标准备用名称在后续运行中会保持选中状态。

bash

node "<skill-directory>/scripts/setup.mjs" preflight --json

仅当兼容性阶梯确定了受支持的格式和路径后，才会再次运行

status

命令。当Node.js 20+、

npx

和一个客户端均已识别完成时，本步骤结束。

2. Validate the compatibility profile

2. 验证兼容性配置文件

Read

references/client-profiles.md

for the selected client. Check the installed client's version or MCP help when its CLI is available, and check that the resolved user-level path and configuration shape match the local installation.

Use the tested profile when those signals agree. On a mismatch, an unknown client, or a client not listed above, read

references/compatibility.md

completely and run its compatibility ladder. This step is complete when the chosen adapter is supported by local evidence or current official vendor documentation.

为所选客户端阅读

references/client-profiles.md

。当客户端CLI可用时，检查已安装客户端的版本或MCP帮助信息，并确认解析后的用户级路径和配置结构与本地安装匹配。

当这些信号一致时，使用已测试的配置文件。如果出现不匹配、未知客户端或上述未列出的客户端，请完整阅读

references/compatibility.md

并运行其兼容性阶梯。当所选适配器得到本地证据或当前官方供应商文档支持时，本步骤结束。

3. Obtain the token

3. 获取Token

Use the

status

result without reading or displaying the stored token. For a native CLI without a supported file adapter, use its documented list/show command: treat an existing managed

yandex-kit

a1-yandex-kit-global

entry as

configured: true

without attempting to read its token.

When

configured

is false, ask:

Для настройки потребуется токен Яндекс KIT. Чтобы его получить, зайдите в кабинет Яндекс KIT: Настройки → API и скопируйте ключ. Вставьте его сюда — я привяжу его к приложению и не буду повторять в ответе. Токен останется в истории этого чата и будет сохранён в пользовательском конфиге приложения.

When

configured

is true, continue from the selected branch:

For reconnection, including reinstallation or token replacement, ask:

Пришлите новый токен из **Настройки → API** — я обновлю подключение и не буду повторять его в ответе. Новый токен останется в истории этого чата и будет сохранён в пользовательском конфиге приложения.

For a first-connection request when a token is already configured, ask:

Токен Яндекс KIT уже сохранён в настройках. Хотите переподключить магазин с новым токеном?

For

нет

, finish with:

Принято! Оставляем действующий токен Яндекс KIT без изменений. Всё работает в прежнем режиме.

For
```
да
```
, use the reconnection prompt above.

Accept the token in chat. Do not echo, summarize, quote, log or interpolate it into a shell command. Pass a new token only through stdin to

setup.mjs

: write the token followed by one newline. The first newline terminates the input, so the helper starts immediately and never waits for the stdin pipe to close; closing stdin after the newline is also safe.

Before writing any new or replacement token, validate it with the direct read-only MCP smoke test:

bash

node "<skill-directory>/scripts/setup.mjs" smoke-token --token-stdin --json

smoke-token

and

smoke

require external network access: the helper reaches the npm registry to start

mcp-yandex-kit@latest

and the Yandex KIT API for

get_store

. In a host that sandboxes shell commands, such as Codex, run these commands with network access granted on the first attempt — request the network-enabled or escalated execution mode instead of trying an isolated sandbox first. The helper probes connectivity before starting the server and fails fast with

code: "NETWORK_UNAVAILABLE"

when the network is blocked; re-run the same command with network access instead of treating it as a token problem. The whole smoke run shares one wall-clock deadline, so it either finishes or fails within about a minute.

If authentication fails (

code: "SMOKE_AUTH"

), ask for another token with the replacement-token prompt and repeat this validation until it succeeds or the user explicitly cancels. Do not impose a retry limit. Because configuration has not started, cancellation leaves the current client settings unchanged. Treat other smoke failures as their own diagnostics instead of asking for a different token.

This step is complete when one candidate token has passed

get_store

. The explicit

нет

branch for an existing first connection finishes the skill without reaching this point.

使用

status

命令的结果，无需读取或显示已存储的Token。对于没有受支持文件适配器的原生CLI，使用其文档中列出的查看命令：将已存在的托管

yandex-kit

或

a1-yandex-kit-global

条目视为

configured: true

，无需尝试读取其Token。

当

configured

为false时，询问：

配置需要Yandex KIT Token。获取方式：登录Yandex KIT后台 → 设置 → API，复制密钥。请在此处粘贴Token，我会将其绑定到应用中，且不会在回复中重复显示。Token将保留在此聊天记录中，并保存到应用的用户配置中。

当

configured

为true时，根据所选分支继续：

对于重新连接请求（包括重新建立连接或更换Token），询问：

请发送来自**设置 → API**的新Token，我会更新连接，且不会在回复中重复显示。新Token将保留在此聊天记录中，并保存到应用的用户配置中。

对于首次连接请求但Token已配置的情况，询问：
```
Yandex KIT Token已保存到设置中。是否要使用新Token重新连接商店？
```
- 如果用户回复
```
нет
```
  （否），结束流程并回复：
```
已确认！保留当前Yandex KIT Token不变，所有功能将正常运行。
```
- 如果用户回复
```
да
```
  （是），使用上述重新连接提示。

在聊天中接收Token。不要回显、总结、引用、记录或将其插入到shell命令中。仅通过标准输入（stdin）将新Token传递给

setup.mjs

：写入Token后换行。第一个换行符将终止输入，因此助手会立即启动，无需等待stdin管道关闭；换行后关闭stdin也是安全的。

在写入任何新Token或替换Token之前，通过直接只读MCP冒烟测试验证其有效性：

bash

node "<skill-directory>/scripts/setup.mjs" smoke-token --token-stdin --json

smoke-token

和

smoke

命令需要外部网络访问：助手会访问npm registry以启动

mcp-yandex-kit@latest

，并访问Yandex KIT API执行

get_store

操作。在对shell命令进行沙箱隔离的主机（如Codex）中，首次尝试运行这些命令时需授予网络访问权限——请求启用网络或提升执行模式，而非先尝试隔离沙箱。助手会在启动服务器前探测连接性，当网络被阻止时会快速失败并返回

code: "NETWORK_UNAVAILABLE"

；此时应重新运行带网络访问权限的相同命令，而非将其视为Token问题。整个冒烟测试共享一个时钟截止时间，因此会在约一分钟内完成或失败。

如果验证失败（

code: "SMOKE_AUTH"

），使用替换Token提示请求新的Token，并重复此验证步骤直到成功或用户明确取消。不要设置重试次数限制。由于配置尚未开始，取消操作不会改变当前客户端设置。将其他冒烟测试失败视为独立诊断问题，而非请求不同Token。

当一个候选Token通过

get_store

验证时，本步骤结束。对于已存在Token的首次连接请求，用户回复

нет

的分支会在到达此点前结束Skill流程。

4. Configure the user-level client

4. 配置用户级客户端

For a new or replacement token, run the helper in an interactive process and write the token followed by a newline to its stdin; the newline completes the input, so the helper does not wait for the pipe to close:

bash

node "<skill-directory>/scripts/setup.mjs" configure --client <client> --token-stdin --json

For a dynamically discovered native CLI, follow

references/compatibility.md

and run

native-configure

. The helper reads the token from stdin, substitutes it into the documented child-process arguments, keeps it out of the agent-issued shell command and shell history, and redacts it from output.

For a dynamically discovered file adapter, also pass its verified capability and path:

bash

node "<skill-directory>/scripts/setup.mjs" configure --client <label> --format <format> --config <absolute-path> --token-stdin --json

In either route, the canonical server is always:

text

npx -y mcp-yandex-kit@latest

Only add or update the selected managed entry. Preserve every differently named MCP server and every unrelated client setting. Do not remove, rename, disable or rewrite another server. When an exact project/local

yandex-kit

entry shadows the user-level name, leave that entry unchanged and configure

a1-yandex-kit-global

instead.

Use the concrete setup request selected at the start as the configuration authorization and surface only the host application's unavoidable filesystem approval. If an existing config cannot be parsed safely, leave it unchanged and return to the compatibility ladder to try the client's documented native CLI. Give the technical handoff only when the native route is also unavailable or fails.

For a file adapter, this step is complete when the helper reports

configured: true

, the token is present without being printed, unrelated client settings remain intact, and a backup exists for every changed pre-existing config. On POSIX systems, the changed config and its backup must have mode

. For a native CLI, this step is complete when the documented add command exits successfully; the client owns its configuration mutation.

对于新Token或替换Token，在交互式进程中运行助手，并将Token写入其标准输入后换行；换行符会完成输入，因此助手无需等待管道关闭：

bash

node "<skill-directory>/scripts/setup.mjs" configure --client <client> --token-stdin --json

对于动态发现的原生CLI，请遵循

references/compatibility.md

并运行

native-configure

命令。助手会从stdin读取Token，将其替换为文档化的子进程参数，确保Token不会出现在Agent发出的shell命令和shell历史中，并在输出中对其进行脱敏处理。

对于动态发现的文件适配器，还需传递其已验证的功能和路径：

bash

node "<skill-directory>/scripts/setup.mjs" configure --client <label> --format <format> --config <absolute-path> --token-stdin --json

无论采用哪种方式，标准服务器始终为：

text

npx -y mcp-yandex-kit@latest

仅添加或更新所选的托管条目。保留所有名称不同的MCP服务器和所有无关的客户端设置。不要删除、重命名、禁用或重写其他服务器。当存在完全同名的项目/本地

yandex-kit

条目覆盖用户级名称时，保留该条目不变，转而配置

a1-yandex-kit-global

。

使用流程开始时选择的具体设置请求作为配置授权，仅显示主机应用不可避免的文件系统审批提示。如果现有配置无法安全解析，保留其不变并返回兼容性阶梯，尝试客户端的文档化原生CLI。仅当原生路由也不可用或失败时，才提供技术交接。

对于文件适配器，当助手报告

configured: true

、Token已存在且未被打印、无关客户端设置保持不变、每个已修改的现有配置都有备份时，本步骤结束。在POSIX系统上，修改后的配置及其备份必须具有

权限。对于原生CLI，当文档化的添加命令成功退出时，本步骤结束；客户端负责其配置变更。

5. Prove the connection

5. 验证连接

For a tested client, run the client check:

bash

node "<skill-directory>/scripts/setup.mjs" client-check --client <client> --json

Treat

structural

as the expected client check for GUI clients without a non-interactive MCP diagnostic. For a dynamic adapter, run the client-level verification established from its official documentation.

The client check must verify the effective managed definition, not merely that its name appears in a list. If a locally changed client path or precedence rule still causes

SERVER_SHADOWED

, configure the same validated token once under

a1-yandex-kit-global

by passing

--server-name a1-yandex-kit-global

configure

client-check

and

smoke

. Leave the shadowing project entry and all other MCP servers unchanged.

For a file adapter, then run:

bash

node "<skill-directory>/scripts/setup.mjs" smoke --client <client> --json

Repeat the verified

--format

and

--config

flags for a dynamic adapter. For a native CLI without a supported file adapter, use the successful direct smoke from step 3 and do not run the file-based

smoke --client

command. The smoke test must complete the MCP initialize handshake, list tools, find

get_store

, and call only

get_store

. It must not call any write tool.

If the tested profile fails because its path, schema or client command changed, restore only this run's change when

configure

reported

changed: true

, then execute the dynamic compatibility branch. For a pre-existing config, use every rollback value returned by that configure run:

bash

node "<skill-directory>/scripts/setup.mjs" rollback --config <configPath> --backup <backupPath> --backup-hash <backupHash> --expected-hash <configHash> --json

When this run created the config, use:

bash

node "<skill-directory>/scripts/setup.mjs" rollback --config <configPath> --created --expected-hash <configHash> --json

If the hash check refuses rollback, preserve the newer config and report its path. If a post-write check reports authentication failure, roll back this run's file change when one exists, then return to the unlimited token-validation loop in step 3. If the config is malformed, do not repair it; try the documented native CLI before using the technical handoff.

This step is complete only when the client check passes and the direct MCP smoke test has passed during this run.

对于已测试的客户端，运行客户端检查：

bash

node "<skill-directory>/scripts/setup.mjs" client-check --client <client> --json

对于没有非交互式MCP诊断功能的GUI客户端，将

structural

视为预期的客户端检查结果。对于动态适配器，运行从其官方文档确定的客户端级验证。

客户端检查必须验证有效的托管定义，而不仅仅是其名称出现在列表中。如果本地修改的客户端路径或优先级规则仍导致

SERVER_SHADOWED

，通过向

configure

、

client-check

和

smoke

命令传递

--server-name a1-yandex-kit-global

，在

a1-yandex-kit-global

下配置相同的已验证Token。保留产生遮蔽的项目条目和所有其他MCP服务器不变。

对于文件适配器，然后运行：

bash

node "<skill-directory>/scripts/setup.mjs" smoke --client <client> --json

对于动态适配器，重复使用已验证的

--format

和

--config

参数。对于没有受支持文件适配器的原生CLI，使用步骤3中成功的直接冒烟测试，无需运行基于文件的

smoke --client

命令。冒烟测试必须完成MCP初始化握手、列出工具、找到

get_store

并仅调用

get_store

。不得调用任何写入工具。

如果已测试的配置文件因路径、架构或客户端命令变更而失败，当

configure

报告

changed: true

时，仅恢复本次运行的变更，然后执行动态兼容性分支。对于预先存在的配置，使用该configure运行返回的所有回滚值：

bash

node "<skill-directory>/scripts/setup.mjs" rollback --config <configPath> --backup <backupPath> --backup-hash <backupHash> --expected-hash <configHash> --json

如果本次运行创建了配置，使用：

bash

node "<skill-directory>/scripts/setup.mjs" rollback --config <configPath> --created --expected-hash <configHash> --json

如果哈希检查拒绝回滚，保留较新的配置并报告其路径。如果写入后检查报告验证失败，当存在本次运行的文件变更时回滚该变更，然后返回步骤3中的无限Token验证循环。如果配置格式错误，不要修复它；在使用技术交接前尝试文档化的原生CLI。

仅当客户端检查通过且直接MCP冒烟测试在本次运行中通过时，本步骤结束。

6. Offer work without host stops

6. 提供无主机中断的工作模式

After the connection is proved, read

references/approval-policies.md

completely. Use the same branch when the user reports repeated

Allow

prompts during an import, even if the store was connected earlier.

Inspect the current client's capability, state that the grant covers every current and future Yandex KIT tool, and ask once whether to enable Работу без остановок on this computer. After

да

, apply the managed server wildcard. The warning must name deletes, orders, promotions and store administration before consent. Do not ask again for individual tools added later.

This step is complete when the helper reports

automatic

guided

unsupported

, and the user knows any remaining restart or UI action before work starts.

连接验证通过后，请完整阅读

references/approval-policies.md

。当用户报告在导入过程中反复出现“Allow”提示时，即使商店之前已连接，也使用相同分支处理。

检查当前客户端的功能，说明授权涵盖所有当前和未来的Yandex KIT工具，并询问一次是否在该计算机上启用无中断工作模式。用户回复

да

（是）后，应用托管服务器通配符。在用户同意前，必须警告该模式涉及删除、订单、促销和商店管理操作。后续添加新工具时无需再次询问。

当助手报告

automatic

、

guided

或

unsupported

，且用户了解工作开始前任何剩余的重启或UI操作时，本步骤结束。

7. Finish simply

7. 简洁收尾

Reload MCP automatically only when the validated client exposes a documented non-interactive reload command. Otherwise give the single restart instruction from

references/client-profiles.md

; do not force-close the application.

End with one short result, for example:

Готово — Яндекс KIT подключён к Cursor. Проверка прошла: вижу магазин «Название».

Do not show configuration contents, token fragments, diagnostic dumps or additional terminal commands. Setup is complete when the user sees the selected client, a successful store check, and at most one necessary restart action.

仅当已验证的客户端提供文档化的非交互式重载命令时，才自动重新加载MCP。否则，提供

references/client-profiles.md

中的单一重启指令；不要强制关闭应用。

以简短结果结束流程，例如：

完成 — Yandex KIT已连接至Cursor。验证通过：已检测到商店«名称»。

不要显示配置内容、Token片段、诊断转储或额外的终端命令。当用户看到所选客户端、成功的商店检查结果以及最多一个必要的重启操作时，设置流程完成。