10x-cli-setup

10x-cli 设置

准备用户的 CLI 和项目，然后将工作上下文传递给 guide。选择版本、安装辅助工具或运行课程命令之前，请阅读兼容性参考。使用实际运行器的帮助信息及其对应的已发布源代码；不断更新的 master README 不能证明已安装的 CLI 支持哪些功能。

下一个 CLI 版本还将支持仅针对项目的捆绑安装，命令为 10x helpers install --tool <chosen-profile>。此命令尚未发布，也不在 1.21.0/1.22.0 master 基线中：请先检查实际运行器的 helpers --help。如需完整文件、明确的目标位置和冲突处理方式，请遵循本地参考中的捆绑公共副本；如果运行器不支持该方式，请保留现有固定的公共途径。

1. 确定项目和现有安装

根据用户的请求和现有会话上下文，确定目标项目目录、shell 和 AI 工具，然后再写入文件。对于 10xDevs4 引导练习，环境为 macOS/zsh、10xdevs4、claude-code、pl；不要默默将这些设置应用到 v3 项目或选择了其他配置的用户。

在 POSIX shell 中检查运行器，不要隐藏失败信息：

pwd
command -v 10x

如果找到运行器，请运行 10x --version 以及 --help、get --help、sync --help 和 auth --help。记录可执行文件路径和安装方式。现有且能正常工作的安装无需重新安装或重新登录。如果可执行文件存在但运行失败，请保留错误信息，并排查其运行时、PATH 或权限问题；这与命令缺失不同。在其他系统上，请使用对应 shell 的可执行文件查找方式，不要使用 POSIX 检测代码片段。

检查项目的 .10x-cli.json 和现有配置清单，将其视为本地元数据，不要编辑。课程绑定在各配置间共享；更改 --tool 不能将 v3 切换为 v4。对于绑定了 v3 项目的 v4 练习，请使用单独的目录并保留 v3 项目。保留损坏、未知或相互冲突的绑定和配置清单以供诊断；不要删除它们来强行访问。

2. 选择兼容的运行器，仅在需要时安装

遵循本地参考中的版本和功能检查。记录实际的软件包版本、源代码修订版本和支持的语法。已发布的语法为 get m1l1 --type skills --name NAME；位置参数是课程引用，而不是技能名称。请在内容中核实对应的课程和技能。本地构建或更高的版本号都不能证明二者均受支持。如果不支持技能筛选，请继续准备项目和公共辅助工具，并在下载前报告具体尚待支持的功能。不要擅自替换为完整课程或其他课程。

对于 npm/npx，请根据对应软件包的 engines 要求核实 Node 版本（经检查的基线要求 Node 20+）。没有合适的全局 CLI 时，本地参考中固定版本的 npx 运行器可避免全局安装。尊重用户要求的全局或独立安装方式，并使用相应的安装或更新流程。安装时沿用现有授权。遇到权限错误时，不要自动使用 sudo、重置全局配置或删除凭据。

安装或更新后，请重新运行版本和帮助检查。在整个设置和 guide 过程中始终使用同一个确定的运行器，避免 PATH 中较旧的 10x 替换已验证的 npx 版本。没有网络时，请检查可用的本地版本、帮助信息及对应的打包文档；将发布、访问和下载检查标记为未经验证。不要仅凭离线版本检查就声称设置已完成。

3. 将身份验证与课程可用性分开检查

运行所选运行器的 auth --status。该命令可以联系课程 API，但不会请求登录邮箱。检查会话是否有效以及实时访问状态：令牌有效或命令成功退出，并不能证明 access_checked 或 v4 访问权限有效。保留无法检查访问权限时的错误信息。

只有在需要登录时，才让用户在交互式终端中运行已验证的 auth 命令，并完成命令显示的流程。检查的版本使用通过电子邮件或 Circle 消息发送的魔法链接（--method email / --method circle）；请遵循所选版本的帮助说明。未经用户授权，不要索要邮箱、打开魔法链接或代替用户登录。切勿读出 auth.json、令牌、魔法链接 URL 或邮件内容。只概述会话和访问状态。

然后运行所选运行器的裸 list 命令：不带 --course 时，CLI 会采用项目 .10x-cli.json 绑定的版本；如果当前目录尚未绑定，则采用实时 API 推荐的版本（账户可访问的最高版本）。只有在有意检查其他已授权版本时，才添加 --course <slug>。区分无会员资格、课程尚未发布、模块已锁定和网络故障。重新安装 CLI 或选择其他工具都不会授予访问权限。后续的下载/同步命令中，明确指定 --tool 和 --lang，并省略 --course，确保所有下载都使用项目绑定的版本。

4. 诊断就绪状态，不要人为创建工具目录

运行所选运行器的 doctor --json；检查完整的 data.checks 和 data.overall，以及退出状态。外层的 status: "ok" 只是输出封装，并不表示所有检查都已通过。Doctor 使用已配置的配置文件（或其默认配置文件），因此请将报告的工具与预期工具进行比较；在检查的基线版本中，它没有 --tool 标志。其身份验证检查还会报告解析出的版本和选择原因（details.course、details.selectionReason）——将此作为首次下载前的自检。项目首次写入时会绑定到一个版本；之后要使用其他版本，需要新建一个空目录，因为在已绑定的项目中写入其他版本会导致 course_mismatch。

在新项目中首次下载之前，缺少 .claude/（或报告中显示的配置文件目录）可能是正常的。如果这是唯一的失败项，而且这是正确且可写的项目，请说明首次成功下载时会创建该目录。不要为了让检查通过而创建虚假目录。分别保留并处理任何身份验证、访问、API、绑定或写入权限失败。离线时跳过更新检查，并不能证明 CLI 已是最新版本。

5. 交接给实际指南副本

定位项目已安装的 10x-cli-guide/SKILL.md 及其自身的 references/compatibility.md。添加或更新前，先根据该参考文件检查安装渠道和所有者。如果文件不存在，请通过选定的公开按需渠道或兼容的 CLI 渠道安装指南；并验证生成的文件。仅安装 npm CLI 并不会在 Agent 中启用这两个辅助工具。不要声称不存在的指南可用，也不要依赖未经验证的斜杠命令发现机制。告诉 Agent 阅读确切的已落盘指南路径及其本地参考文件。

在对话中传递以下简要上下文，不包含机密信息：

Project: absolute cwd; course binding or unbound
Course / tool / requested language: 10xdevs4 / claude-code / pl (or user's choice)
Runner: exact executable or pinned npx command; observed version and source ref
CLI install/update method: npx pin / npm global / standalone asset
Auth: valid / login required / unknown; live course access and module state
Setup helper: actual path, public or CLI owner, observed source ref if known
Guide helper: actual path, owner and source ref if known; full reference present
Readiness: verified checks; remaining release/network/access issues, if any
Next task: guide's lesson setup (idea-check/init/shape/prd) → use → sync journey, or the user's narrower request

对于第 1 课的设置，在交接时带上全部四项技能及其参考文件：10x-idea-check、10x-init、10x-shape 和 10x-prd。是否运行创意评估是可选的，但不能因此在课程设置时省略其文件。针对某一项具体技能的请求，仍应只下载该技能。将已落盘文件与原生命令斜杠发现机制分开验证。

准备就绪后，直接在指南中继续，不要重新运行安装，也不要要求用户重复已提供的选择。如果下载暂时无法运行，请准确说明剩余的阻碍；不要把准备工作说成已完成的真实历程。