a1-yandex-kit-setup

A1 Yandex KIT 设置

沟通

在生成任何面向用户的消息之前，请完整阅读并遵循 ../a1-yandex-kit/references/merchant-communication.md。

无论用户输入的是文字还是语音转写，都应将设置流程设计为专人协助式流程。 从触发此流程的分支开始：

• 对于简短的引导请求 Связь с магазином，只问一个问题： Что сделать: подключить магазин или переподключить его с новым токеном?
• 明确提出连接或重新连接请求，即表示用户授权：在收集所需输入且候选令牌通过验证后，更新所选客户端的用户级 MCP 配置。重新安装连接和更改令牌都属于重新连接请求。

在项目本地安装技能，不会将配置限制在该项目中。

使用 scripts/setup.mjs 配置并直接执行只读冒烟测试。 所有相对路径都从此技能目录解析，而不是从用户的项目解析。

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

如果可以明确判断，则根据宿主推断当前客户端。否则，只问一个简短的问题：В каком приложении вы сейчас хотите подключить Яндекс 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 в терминале?

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

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

在请求任何令牌或更改任何配置之前，status 会同时验证 Node.js 20+ 和可执行的 npx。如果任一前置条件不可用，请提供一个适用于该操作系统的准确 Node.js 安装链接或说明，然后停止。将安装交由该操作系统的安装程序处理。对于其他客户端，运行独立的预检，并继续执行第 2 步中的兼容性流程：

对于 Claude Code、Cursor、VS Code 和 Kimi Code，status 还会检查是否存在已知的项目级或本地级服务器，其名称为 yandex-kit，并且可能覆盖用户级条目。遇到名称完全相同的冲突时，它会选择托管备用名称 a1-yandex-kit-global。它会忽略名称不同的所有 MCP 服务器。后续运行时，先前已配置的规范备用名称会继续保持选中状态。

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

只有在兼容性流程确认支持的格式和路径后，才再次运行 status。 如果 status 报告现有文件无法解析，请保留该文件并继续执行第 2 步；兼容性流程可能会在本次运行的剩余步骤中选择原生 CLI。 当 Node.js 20+、npx 和一个客户端均已确认后，此步骤即完成。

2. 验证兼容性配置

阅读所选客户端对应的 references/client-profiles.md。如果客户端的 CLI 可用，请检查已安装客户端的版本或 MCP 帮助信息，并确认解析出的用户级路径和配置结构与本地安装相符。

这些信号一致时，使用已测试的配置。如果配置无法解析，则视为不匹配：保持不变，并继续执行兼容性流程。对于任何其他不匹配、未知客户端或上述列表中未列出的客户端，请完整阅读 references/compatibility.md，并执行其中的兼容性流程。该流程会为设置的其余步骤选择一个适配器：要么是具有已验证格式和绝对路径的文件适配器，要么是带有文档说明的添加命令和验证命令的原生 CLI。将此选择用于第 3、4 和 5 步；如果已知客户端的文件无法解析，也应采用原生 CLI 备用方案。当所选适配器有本地证据或当前官方供应商文档支持后，此步骤即完成。

3. 获取令牌

使用选定的适配器证据和任何 status 结果，但不要读取或显示已存储的令牌。对于没有受支持文件适配器的原生 CLI，使用其文档所述的 list/show 命令：将现有的托管 yandex-kit 或 a1-yandex-kit-global 条目视为 configured: true，无需尝试读取其中的令牌。

每次实际连接或重新连接都会运行 token-route，并执行相同的获取流程。已有令牌时，在本地文件适配器路由上，受保护页面会选择 replace 模式；这不会转而使用聊天，也不会使受保护页面变为可选。该路由上的重新连接始终会先获取新的单次使用页面 URL，再进行任何替换写入。原生 CLI 和托管路由使用其文档所述的安全输入或密钥机制，只有在用户明确选择后才使用聊天。

如果用户首次请求连接，但已配置令牌，请询问： Токен Яндекс KIT уже сохранён в настройках. Хотите переподключить магазин с новым токеном?

• 如果回答 нет，请以此结束： Принято! Оставляем действующий токен Яндекс KIT без изменений. Всё работает в прежнем режиме.
• 如果回答 да，请继续执行下文的重新连接流程。

获取令牌前先介绍

在每次对话中、首次请求令牌之前，先发送一条简短的介绍消息，无论使用哪种路由。使用店主的业务语言（merchant-communication.md），列出连接商店后可以交由你处理的三四项工作，并说明令牌是最后一步。例如：

После подключения мне можно будет поручать дела магазина: обновлять цены и остатки, следить за заказами, запускать акции и промокоды, наводить порядок в каталоге. Остался один шаг — токен магазина.

让环境决定路由

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

• route: "web" — 桌面环回可用。如果选定的适配器是已验证的文件适配器，则每次连接或重新连接都使用下方的本地单次使用页面。仅凭环境结果无法证明应用内浏览器能够访问该辅助程序：请确认浏览器和 shell 在同一台桌面设备上运行。
• route: "hosted" — 会话位于远程环境（reason 会标明 SSH、容器或无头环境标记），因此浏览器无法访问本地页面。使用下方的托管路由，并将其作为此环境的常规受支持路由；完全跳过页面，以免用户收到无法打开的链接。

原生 CLI 适配器

当兼容性阶梯选中原生 CLI 时，在所有环境路由上都使用此适配器，包括已知客户端因配置无法解析而回退的情况。原生 CLI 目前没有受支持的页面适配器：在可用时，使用客户端文档所述的安全输入或原生凭据设置。在托管路由上，使用优先考虑环境的分支。除非店主明确选择，否则不要在聊天中索取令牌。对于通过聊天收到的令牌，使用 smoke-token --token-stdin 验证，并在第 4 步通过 native-configure 配置；然后在第 5 步，使用 references/compatibility.md 中确定的原生 list/show 或 test 命令进行验证。如果托管环境提供令牌，则改用客户端文档所述的环境变量暴露方式和只读验证。对于没有文件适配器的原生 CLI，配置前的直接 smoke 就是聊天路径的 smoke 证明。此适配器不得选择本地页面，也不得选择基于文件的 status、client-check 或 smoke 命令。

本地单次使用页面（route: "web" + 文件适配器）

仅当 token-route 报告 route: "web"，且兼容性阶梯选中了已验证的文件适配器时，才选择此分支。启动页面，并将其作为长时间运行的后台进程；传入兼容性阶梯为该适配器确定的相同 --format、--config、--project-dir 和 --server-name 标志：

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

对于动态文件适配器，请显式包含这些标志。保留选定的服务器名称；如果发生精确名称冲突，则使用 a1-yandex-kit-global。 第一行标准输出是 {"url": …, "expires_in_seconds": …}。读取 expires_in_seconds 中的有效期（默认五分钟），并立即检查当前宿主实际公开的能力。为用户在宿主自有的浏览器界面中持久打开此页面：

• 在 Codex 中，如果 mcp__codex_app__open_in_codex 可用，请使用 target: { type: "browser", url: <url> } 调用它（如果支持，请将页面放置在右侧）。这是持久的 Codex 浏览器面板。请勿使用 cua_repl、createBrowserTab、browser-use 或通过计算机控制创建标签页的方式打开此页面：这些受活动范围限制的标签页可能会在助手轮次结束时关闭。
• 在 Claude Code 或 Claude Desktop 中，请在当前会话中使用客户端原生的 Browser 或预览面板。请勿用临时的 browser-use 或屏幕控制标签页替代。如果原生面板不可用、无法访问本地页面，或无法为用户持久保留页面，请使用操作系统的打开方式，然后采用下方可点击的 URL 后备方案。

请勿编造特定于客户端的浏览器 API、工件 iframe 或截图工作流，也绝不要检查已填入令牌的表单。内置浏览器可用，并不能证明此 Shell 的回环地址属于同一台桌面设备（浏览器可能运行在云会话或虚拟机中）。如果没有合适的持久化应用内能力，请使用操作系统的默认浏览器打开方式：

node "<skill-directory>/scripts/setup.mjs" open-token-page --url <url> --json

如果宿主策略不允许启动操作系统的打开程序，请跳过该命令，直接将 URL 作为可点击的后备链接发送给用户。

该命令只接受 token-web 发出的回环一次性 URL，不经过 Shell 使用操作系统的打开程序；如果打开程序缺失或失败，则返回 opened: false。打开程序失败不会停止正在运行的 token-web 进程。如果返回 opened: false，请保持页面运行，并将其返回的 URL 作为可点击的后备链接发送给用户。打开成功后，请告知用户一次性页面已打开，并说明 expires_in_seconds 中的实际有效期。一次性页面 URL 中的秘密信息不是存储令牌；绝不要记录、回显或索取存储令牌本身。

在用户输入令牌期间，该命令会持续提供页面服务。写入任何内容之前，它会执行与 smoke-token 相同的只读 get_store 验证——需要相同的外部网络访问权限；如果令牌被拒绝，则会重新显示表单，且不限制重试次数；成功后会执行步骤 4 中完全相同的 configure 写入。其最终 JSON 包含 configure 字段及 smoke：当报告 configured: true 时，步骤 3 和 4 即已完成——保留其回滚值（changed、backupPath、backupHash、 configHash），并继续步骤 5。

显示的有效期限制了等待验证和开始配置写入的时间。一旦验证通过并开始持久化提交，即使有效期已过或浏览器已关闭，提交也会完成，并返回实际的成功结果或错误以及完整元数据。如果持久化尚未开始而有效期已过，token-web 会返回 TOKEN_WEB_TIMEOUT，且不会执行写入。

如果 token-web 在持久化前以 TOKEN_WEB_TIMEOUT 结束，请丢弃已过期的 URL，并重新启动一次 token-web。使用新 URL，按照相同顺序重新打开浏览器；绝不要重新打开已过期的 URL。在此期间保持当前配置不变。如果它以 TOKEN_WEB_UNAVAILABLE 或 TOKEN_WEB_ABUSE 结束，请说明诊断信息，并保持当前配置不变。如果有已记录的安全输入方式或机密信息处理途径可用，请使用该方式。默认情况下不要要求或建议用户在聊天中粘贴令牌；只有用户明确选择后才能使用聊天。重新连接时也要遵循相同的新建一次性页面流程。

托管路由（route: "hosted"）

先提示用户使用客户端的会话环境或密钥设置——存储在其中的令牌不会进入对话：

助手在远程会话中运行，因此这里不会打开本地令牌输入页面——这是正常且预期的路由。最可靠的做法是在此会话的环境或密钥设置中设置环境变量 YANDEX_KIT_TOKEN：这样令牌就不会进入聊天记录。

用户在这些设置中存储令牌后，按照客户端文档将该变量暴露给托管服务，然后在第 5 步验证连接。如果用户无法访问这些设置，询问他们是否明确希望使用聊天路由。等待用户选择后再索取令牌，然后继续使用所选的适配器分支：原生 CLI 使用 native-configure，文件适配器使用 configure。完成所请求的工作后，提醒用户一次：

此令牌曾出现在本次聊天记录中。任务完成后，可以在 Яндекс KIT 账户中撤销它：设置 → API；如有需要，也可以重新生成一个。

明确选择聊天路由（仅在用户选择后）

• 用户明确选择聊天路由且 configured 为 false 后，询问： 需要令牌才能完成设置。要获取令牌，请登录 Яндекс KIT 账户，进入设置 → API 并复制密钥。将它粘贴到这里——我会将它绑定到应用，且不会在回复中重复。令牌会保留在本次聊天记录中，并存储在应用的用户配置中。
• 用户明确选择聊天路由以重新连接时（包括重新安装或替换令牌），询问： 请发送来自 **设置 → API** 的新令牌——我会更新连接，且不会在回复中重复。新令牌会保留在本次聊天记录中，并存储在应用的用户配置中。

接受用户在聊天中提供的令牌。不要回显、概述、引用、记录令牌，也不要将其插入 shell 命令。只能通过 stdin 将新令牌传递给 setup.mjs：写入令牌后再写入一个换行符。第一个换行符会终止输入，因此辅助程序会立即启动，不会等待 stdin 管道关闭；在换行符后关闭 stdin 也安全。

在写入任何新令牌或替换令牌之前，使用直接、只读的 MCP 冒烟测试验证令牌：

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

smoke-token 和 smoke 需要外部网络访问：辅助程序会访问 npm 注册表以启动 mcp-yandex-kit@latest，并访问 Яндекс KIT API 来调用 get_store。如果宿主会沙盒化 shell 命令（例如 Codex），首次尝试时应授予这些命令网络访问权限——请求启用网络或提升权限的执行模式，而不是先尝试隔离沙盒。辅助程序会在启动服务前探测连接；如果网络受阻，会快速失败并返回 code: "NETWORK_UNAVAILABLE"；此时应使用网络访问权限重新运行相同的命令，而不要将其当作令牌问题。整个冒烟测试共用一个实际运行时限，因此会在约一分钟内完成或失败。

如果身份验证失败（code: "SMOKE_AUTH"），使用替换令牌提示词索取另一个令牌，并重复此验证，直到成功或用户明确取消。不要设定重试次数上限。由于配置尚未开始，取消不会更改当前客户端设置。将其他冒烟测试失败视为各自独立的诊断结果，不要因此索取不同的令牌。

当本地页面报告 configured: true，或某个候选令牌通过 get_store 验证时，此步骤即完成。对于已有的首次连接，明确选择 нет 的分支会结束此技能，不会执行到这一步。

4. 配置用户级客户端

通过本地页面保存的令牌已完成配置：token-web 已执行此步骤的写入操作，因此请使用其报告的值继续执行第 5 步。

对于在所选原生 CLI 适配器的聊天中收到的令牌，包括来自已知客户端的原生回退方案，请遵循 references/compatibility.md 并运行 native-configure。该辅助程序从 stdin 读取令牌，将其代入文档中说明的子进程参数，使其不会出现在 Agent 发出的 shell 命令和 shell 历史记录中，并会在输出中对其脱敏。此分支请勿运行文件适配器的 configure 命令。

对于在所选文件适配器的聊天中收到的令牌，请在交互式进程中运行辅助程序，并向其 stdin 写入令牌后接一个换行符；该换行符会完成输入，因此辅助程序无需等待管道关闭。对于已知配置文件，请使用：

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

对于动态文件适配器，如果兼容性阶梯已确认其能力和路径，请传入相应值：

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

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

npx -y mcp-yandex-kit@latest

只添加或更新所选的受管理条目。保留所有名称不同的 MCP 服务以及所有无关的客户端设置。不要移除、重命名、禁用或重写其他服务。如果完全匹配的项目级/本地 yandex-kit 条目遮蔽了用户级名称，请保持该条目不变，改为配置 a1-yandex-kit-global。

将开始时选定的具体设置请求作为配置授权，并且只提示主机应用程序不可避免的文件系统审批。如果现有配置无法安全解析，请保持原样，并返回兼容性阶梯，尝试客户端文档说明的原生 CLI。只有在原生方式也不可用或失败时，才提供技术交接信息。

对于文件适配器，当辅助程序报告 configured: true、令牌已写入但未打印、无关客户端设置保持完整，且每个发生变更的既有配置文件都有备份时，此步骤即告完成。在 POSIX 系统上，发生变更的配置文件及其备份的权限必须为 0600。对于原生 CLI，当文档说明的添加命令成功退出时，此步骤即告完成；配置变更由客户端负责。

5. 验证连接

对于经过测试的文件适配器，运行辅助客户端检查：

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

对于没有非交互式 MCP 诊断功能的 GUI 客户端，将 structural 视为预期的客户端检查。对于动态文件适配器，使用根据其官方文档确定的客户端级验证，并保留阶梯中验证过的格式和路径；辅助工具 client-check 仅用于经过测试的文件配置。对于选定的原生 CLI 适配器，使用兼容性阶梯中记录的 list/show 或 test 命令，并验证生效的托管定义。原生适配器不使用基于文件的 client-check 命令。

文件适配器的客户端检查必须验证生效的托管定义，而不能只确认其名称出现在列表中。如果本地更改的客户端路径或优先级规则仍导致 SERVER_SHADOWED，请将同一验证过的令牌仅配置一次到 a1-yandex-kit-global 下，并在 configure、client-check 和 smoke 中传入 --server-name a1-yandex-kit-global。保留发生遮蔽的项目条目和所有其他 MCP 服务，不作更改。

对于文件适配器，接着运行：

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

对于动态适配器，重复使用已验证的 --format 和 --config 标志。对于没有受支持文件适配器的选定原生 CLI，不要运行基于文件的 smoke --client 命令，而应使用步骤 3 中成功的直接 smoke 测试。 smoke 测试必须完成 MCP 初始化握手、列出工具、找到 get_store，并且只调用 get_store。不得调用任何写入工具。

如果选定的文件适配器因路径、架构或客户端命令发生变化而失败，且 configure 或 token-web 报告 changed: true，则只还原本次运行所做的更改，然后执行兼容性分支。对于已存在的配置，请使用本次运行返回的所有回滚值——两个辅助工具都会报告相同的字段：

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

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

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

如果哈希检查拒绝回滚，请保留较新的配置并报告其路径。如果写入后的检查报告身份验证失败，且本次运行存在文件更改，则回滚该更改，然后返回步骤 3 中不限次数的令牌验证循环。如果配置格式错误，不要修复；请先尝试文档所述的原生 CLI，再进行技术移交。

当选定适配器的验证通过，且本次运行中的只读 smoke 证明也通过时，此步骤即告完成：经过测试的文件适配器使用 client-check 加基于文件的 smoke；动态文件适配器使用供应商验证加基于文件的 smoke；通过聊天配置的原生 CLI 使用原生验证加配置前成功的 smoke-token 结果；以托管环境优先的原生 CLI 使用其文档所述的只读证明。

6. 提供不中断的工作体验

连接验证通过后，完整阅读 references/approval-policies.md。 如果用户在导入期间报告反复出现 Allow 提示，也使用相同分支，即使此前已连接商店。

检查当前客户端的能力，说明授权涵盖所有当前和未来的 Yandex KIT 工具，并询问一次是否要在这台计算机上启用Работу без остановок。用户回答 да 后，应用托管服务器通配符。在征求同意之前，警告中必须提及删除、订单、促销和商店管理。之后新增单个工具时，不要再询问。

当辅助工具报告 automatic、guided 或 unsupported，且用户了解开始工作前仍需进行的任何重启或 UI 操作时，此步骤即告完成。

7. 简单完成

只有在经过验证的客户端提供了有文档说明的非交互式重载命令时，才自动重新加载 MCP。否则，提供 references/client-profiles.md 中唯一的重启说明；不要强制关闭应用程序。

最后用一句简短的话告知结果，例如：

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

不要显示配置内容、令牌片段、诊断转储或其他终端命令。用户看到所选客户端、成功的商店检查结果，以及至多一个必要的重启操作，即表示设置已完成。