10x-cli-guide

10x-cli：下载、使用和更新

运行命令前，请先阅读随附的兼容性和通道参考。 其中包含固定的运行器设置、版本检查、两个辅助工具通道和所有权保护措施。命令使用已发布的、限定课程的技能筛选器；使用前请核实实际选中的软件包和内容。本地构建或源代码中包含某项功能，都不能证明该功能已发布。

下一个 CLI 版本还将支持仅安装到项目中的捆绑安装方式：10x helpers install --tool <chosen-profile>。此命令尚未发布，且不在 1.21.0/1.22.0 的主线基准版本中：请先查看实际运行器的 helpers --help。请按照本地参考中的捆绑公共副本部分操作，确保文件完整、目标明确并妥善处理冲突；如果运行器不支持，请继续使用现有的固定公共渠道。

环境

沿用设置交接信息：项目根目录、课程、工具、语言、运行器/版本、身份验证/访问状态、更新方式以及辅助工具通道/路径。如果缺少任何信息，只检查相应项目。已安装且可正常工作的 CLI 无需重新安装。如果需要设置，请找到实际的 SKILL.md 及其参考资料，或通过公共渠道安装该辅助工具；不要按名称调用不存在的同级工具。

引导式验收环境为 macOS/zsh、Claude Code、10xdevs4 和 Polish。根据环境确定实际的操作系统和 shell，不要使用会把所有失败都标记为 Windows 的 POSIX 命令。执行任何写入前，先选定目标项目根目录。对于 v4，请保留现有的 v3 项目并使用单独目录；常规的 get、sync 和配置文件更改不会迁移版本。若 .10x-cli.json 和所有清单中的版本/课程不一致，请予以保留。

使用参考资料中定义的、已验证的 10x_cli 运行器，或用户明确提供且已验证的全局/独立可执行文件：

10x_cli --version
10x_cli get --help
10x_cli sync --help
10x_cli auth --status
10x_cli list

这些命令中不要使用 --course：如果目录已绑定，CLI 会从 .10x-cli.json 读取版本；否则会使用实时 API 推荐的版本（账户可访问的最高版本）。get 会输出 Course: <slug> (<reason>)；首次写入前检查一次。只有在有意检查其他有权访问的版本时才使用 --course <slug>——已绑定的项目不能改写为其他版本（course_mismatch），因此 v4 必须在新的空目录中开始。

检查课程参考、技能筛选器和限定课程的 sync 的源代码/发布证据，然后使用下方经过筛选的预览检查端点。不要将 help 命令成功退出视为功能可用的证明。区分不支持的 CLI 语法、未发布/缺失的内容、锁定的模块、会员资格拒绝和网络故障。缺少最终发布证据不一定会妨碍准备公共辅助工具或练习文件。

只从 config.json 中读取必要的非敏感偏好设置。在 macOS/Linux 上，基础路径为非空的 $XDG_CONFIG_HOME，否则为 ~/.config；在 Windows 上为 %APPDATA%，否则为用户的 AppData/Roaming。在其后追加 10x-cli/config.json。不要打印 auth.json、丢弃 stderr、截断 doctor JSON，也不要通过清除配置来修复未知问题。在本流程中，明确指定的课程/工具/语言对相应命令优先于已保存的默认值。

会话管理

需要登录时，让用户选择交付渠道并完成登录：

10x_cli auth                  # Interactive: choose email or Circle
10x_cli auth --method email   # Email magic link; default for piped/JSON output
10x_cli auth --method circle  # One-time approval link delivered in Circle
10x_cli auth --status
10x_cli auth --logout

如果收不到邮件，Circle 会很有用。批准链接在 15 分钟后过期；CLI 不会自动重新发送。在非交互模式下，使用 --email 提供用户的邮箱，并明确选择 --method circle。只有用户请求进行身份验证后，才发送登录消息。会话会自动刷新；只有在无法通过刷新恢复会话时才需要重新登录。

下载

启动练习沿用第 1 课“从创意到 PRD”中的现有 10xCards 示例。10x-plan 不属于本次启动演示。 准备好第 1 课的全部四项技能：10x-idea-check、10x-init、10x-shape 和 10x-prd。创意评估可以选择不运行；准备第 1 课时仍应提供其文件。 如果用户只请求特定技能，则保留这一较窄的范围。检查每个名称对应的能力和可用性后， 分别下载四个完整的已选技能目录树。在执行相应写入操作前，先检查每次试运行：

10x_cli get m1l1 --type skills --name 10x-idea-check --tool claude-code --lang pl --dry-run
10x_cli get m1l1 --type skills --name 10x-idea-check --tool claude-code --lang pl
10x_cli get m1l1 --type skills --name 10x-init --tool claude-code --lang pl --dry-run
10x_cli get m1l1 --type skills --name 10x-init --tool claude-code --lang pl
10x_cli get m1l1 --type skills --name 10x-shape --tool claude-code --lang pl --dry-run
10x_cli get m1l1 --type skills --name 10x-shape --tool claude-code --lang pl
10x_cli get m1l1 --type skills --name 10x-prd --tool claude-code --lang pl --dry-run
10x_cli get m1l1 --type skills --name 10x-prd --tool claude-code --lang pl

检查每份报告和完整的支持目录树，而不只是 SKILL.md。在选定的 macOS/zsh 练习目录中， 使用前必须确保以下每项检查都成功（任何一项失败都要停止；不能仅根据最后一项检查推断成功）：

test -s .claude/skills/10x-idea-check/SKILL.md
test -s .claude/skills/10x-idea-check/references/examples.md
test -s .claude/skills/10x-idea-check/references/assessment-guide.md
test -s .claude/skills/10x-idea-check/references/10xdevs-4-dates.md
test -s .claude/skills/10x-idea-check/references/10xdevs-4-certification.md
test -s .claude/skills/10x-init/SKILL.md
test -s .claude/skills/10x-shape/SKILL.md
test -s .claude/skills/10x-shape/references/prd-schema.md
test -s .claude/skills/10x-prd/SKILL.md
test -s .claude/skills/10x-prd/../10x-shape/references/prd-schema.md

PRD 入口点会相对于自身目录解析 ../10x-shape/references/prd-schema.md。 单独的 PRD 目录树并不充分。读取所有已安装的入口点及其所需的每个参考文件； 上述路径是已知的最低源文件要求，并不意味着可以丢弃已发布软件包中的额外文件。 还要检查 .claude/.10x-cli-manifest.json：lessons.m1l1.skills 必须包含全部四个名称， 并且 files.skills 中必须包含文件哈希。这些是课程所属的部分下载，并非独立所有者。 检查 .10x-cli.json 中的课程绑定；部分下载不会建立完整课程发布版本的身份信息。

CLI 1.21.0 已发布，支持 v4 和筛选技能下载；生产环境中的 m1l1 EN/PL 包含 idea-check/init/shape/prd 及其参考文件。这些修订后的辅助工具属于单独的 源代码更改，并不能证明它们的课程副本已发布。 根据实际选定的发布版本核实全部四个名称。如果缺少或不匹配任何名称、架构、所有者或发布版本， 请保留准确错误信息并停止练习；切勿悄悄替换为完整课程、其他课程或筛选式 get。

CLAUDE-m1l1 是单独的课程规则，不会通过这些筛选技能下载提供。 经检查的 init/shape/prd 源文件不要求运行此链时使用该规则。 这并不能证明完整课程的每个步骤都能在没有该规则的情况下运行。 使用学习者现有的第 1 课输入和说明：如果其中要求该规则，请检查现有项目规则及其来源。 如果缺少该规则，请报告缺失的前置条件，并在执行该步骤前向课程/发布版本所有者确认受支持的途径。 不要编造规则命令，也不要下载完整课程来绕过这一要求。不要覆盖现有项目规则。

浏览内容请使用 10x_cli list m1。上述命令按技能名称筛选单节课程；不支持 get 10x-init。 --print 用于检查： TTY Markdown 输出可能仅包含 SKILL.md；非 TTY 输出为 JSON 封装。绝不要将 print 输出重定向到 SKILL.md，作为软件包安装。

用途：10xCards，从创意到 PRD

下载这些目录树只是准备工作。请使用现有的 10xCards 示例和学习者在第 1 课中的实际回答。如果缺少这些输入，请向他们索取；不要编造产品需求、替代版 task.md 或现成计划。不要将私密课程文本放入公开的固定数据和对话记录中。 不要假设可以通过原生斜杠命令／$ 发现功能，也不要假设 npm install 会自动激活。请向 Agent 提供明确的本地路径。如果学习者想评估某个创意是否符合自己的经验、时间和课程目标，请先阅读 .claude/skills/10x-idea-check/SKILL.md 及其参考资料，并遵循该技能。学习者准备好梳理创意时，不要把评估设为前置条件。 然后分别完成以下步骤：

1. 阅读 .claude/skills/10x-init/SKILL.md，并在选定的项目中遵循该技能。 检查仅在文件不存在时创建的 context/changes、context/archive 和 context/foundation 目录及其 README。保留现有文件。
2. 阅读 .claude/skills/10x-shape/SKILL.md 和 .claude/skills/10x-shape/references/prd-schema.md。按照该技能的发现流程， 使用学习者的 10xCards 输入。让学习者回答并批准检查点；不要代替他们作答。继续之前，请根据这些回答检查 context/foundation/shape-notes.md。
3. 阅读 .claude/skills/10x-prd/SKILL.md 及其同级的 schema，然后根据实际的 context/foundation/shape-notes.md 生成草稿。请根据该输入和已安装的 schema 检查 context/foundation/prd.md；尚未解决的领域选择应保持开放。遵循该技能对现有文件冲突的处理选择（带版本号的文件可能是合适的结果）。

成功的标准是获得学习者的笔记和符合 schema 的 PRD，并明确标出缺口，同时保留原项目工作。仅有下载记录的对话内容并不足够。完成 PRD 审核后即停止；不要继续进行技术栈选择、项目引导或实现。如果读取的是不同的全局／本地技能副本，请先更正路径，再接受结果。记录实际使用的 Agent、配置、语言、输出路径和检查结果；对于两个规范的输出文件名，请使用全新的独立练习目录，而不是强行覆盖。

更新

使用相同的运行器、目录、工具和语言；版本仍采用项目自身的版本，因此 sync 也不需要 --course。Sync 会更新整个已下载的课程，包括这些筛选获取操作之后的 m1l1。其预览可能包含其他技能、提示词、配置和课程规则。检查扩展后的范围，并仅在用户接受后应用；如要只更新一个技能，请再次对其执行筛选预览／获取。不要把 sync 当作隐藏规则的前置依赖变通方案：

10x_cli sync --tool claude-code --lang pl --dry-run
10x_cli sync --tool claude-code --lang pl

常规 sync 会刷新清单中记录的全部课程，而不只是选定的四个技能。--all 会将范围扩展到已解锁的课程，本次操作不需要它。应修复缺失的受管理文件；本地编辑应保留为冲突或保留文件。即使退出码为 0，也要阅读所有报告结果和资源计数：仅有跳过的冲突不属于进程错误。不要把远程摘要未变化等同于本地文件完好无损。

对于一个有冲突的技能，先检查差异并备份本地工作，然后在交互式终端中，从相同目录使用相同工具／语言重试该技能的筛选获取。保留用户的解决选择。如果 CLI 提示省略了上下文，请在你提出的命令中补回这些标志。绝不要运行自动 --force；它可能覆盖本地技能／提示词编辑，也不会绕过受保护规则或安全移除机制。配置模板仍采用仅创建模式。清理会保留已修改／未跟踪的文件以及归属其他位置的文件；sync 后不要手动清理技能目录。

如要查看课程工具包本身的变化，请使用 changelog。此命令尚未发布：请先检查实际运行器的 changelog --help。

10x_cli changelog                      # toolkit releases since this project's last sync
10x_cli changelog --since v2.55.0      # releases after a version
10x_cli changelog --course 10xdevs4    # another course than this project's
10x_cli changelog --since 2026-10-01   # releases from that UTC day on

它会列出工具包的发布说明（每个版本中的技能、提示词、规则、配置模板），而不是本项目的文件：对于将要下载的内容，仍以 sync --dry-run 为准。成功执行 sync（或不带筛选的完整 get）会将最新工具包版本记录为项目清单中的基准；否则，该命令会回退到上次应用课程的日期，或显示最新的 5 个版本。退出码为 0 且显示“No toolkit changes”属于正常情况。它绝不会写入文件。

三种更新彼此独立：更改 npm／二进制文件版本会更新 CLI；重复执行固定版本的公开 skills add，并有意选择新的保留 SHA，会更新公开辅助工具；CLI sync 会更新 CLI 所有的课程技能。它不会更新可执行文件或由公开安装程序管理的辅助工具副本。

渠道：两种辅助工具都可通过两种途径获取

公开的按需途径可在 CLI／身份验证之前使用，并在选定的源 SHA 处安装一个项目辅助工具。当辅助工具内容发布且 m1l1 可访问后，CLI 途径会使用经过身份验证的筛选获取。请遵循 10x-cli-setup 和 10x-cli-guide 参考文档中的确切命令和防护措施；只安装所需内容。两种途径都会提供各自辅助工具的 references/compatibility.md。

每个已安装副本只能有一个所有者。写入前，请检查目标路径／符号链接、CLI 清单和公开安装程序的项目注册信息。如果辅助工具已归 CLI 所有，请使用该副本并执行 sync。若要从公开途径转交给 CLI 管理，请将整个辅助工具和元数据备份到受管理目录之外，使用原始固定版本安装程序的项目／Agent 移除流程仅注销该辅助工具，确认注册信息和目标路径均已不存在，然后再进行筛选获取。请谨慎地从备份合并本地编辑。如果任一所有者仍在，请停止转交。CLI→公开途径没有经过验证的逐技能注销约定：请改用新的隔离项目，而不要手动编辑清单。

配置文件与故障排查

完整技能树会放在所选配置文件的 skills/<canonical-name>/ 下：

配置文件	工具目录	完整课程交付的规则文件
claude-code	.claude/	CLAUDE.md
cursor	.cursor/	.cursor/rules/10x-course.mdc
copilot	.github/	.github/copilot-instructions.md
codex	.agents/	AGENTS.md
devin-desktop	.devin/	AGENTS.md
gemini	.gemini/	GEMINI.md
generic	.ai/	AGENTS.md

更改配置文件时，可能会提供迁移、删除符合条件的托管文件，或同时保留两者的选项； 不提供任何选项并不意味着删除任意用户内容或切换课程版本。 旧版 windsurf 别名和孤立内容的处理方式，应以所选版本的帮助信息/输出为准。这些路径映射并不能证明已完成 Windows 或其他 Agent 的操作演练。将 shell 语法转换为用户实际使用的 shell 语法。

在需要诊断时运行 10x_cli doctor --json；检查完整的 data.overall 和 data.checks，以及退出状态。它检查的是已配置的 配置文件，而不是 --tool 或 --course 参数。其身份验证检查会报告解析出的版本和选择原因（details.course、details.selectionReason）——这是用于自检此目录所用版本的方式。首次执行 get 之前，工具目录不存在可能是预期情况；只说明该项失败，并保留其他失败信息。Doctor 的退出码 78 可能与外层 JSON 的 status: "ok" 同时出现。

症状	后续步骤
身份验证缺失/已过期	检查身份验证状态和实时访问结果；让用户通过设置完成登录。登录可能会发送电子邮件。
未收到邮件	提供 10x_cli auth --method circle 选项；让用户自行请求发送消息。
circle_login_disabled	Circle 不可用；使用 10x_cli auth --method email。
dm_rejected	启用 Circle 私信，或使用电子邮件登录。
circle_login_expired	请用户重新发起 Circle 登录，或使用电子邮件登录；切勿自动重新发送。
课程访问被拒绝	确认所选课程和会员资格；更改工具或重新安装不会授予访问权限。
v4 已锁定或未发布	检查模块可用性/发布依据；不要绕过限制或退回 v3。
不支持的名称/缺少索引	验证确切的 CLI 软件包和内容发布版本；将错误原样保留并交给发布负责人。
changelog_unsupported	后端尚未提供工具包变更日志；sync/get 仍可使用。稍后重试；不要将此视为内容故障。
网络/API 故障	保留诊断信息；服务恢复后在相同上下文中重试；不要重置配置。
设置后缺少 10x-idea-check	较早版本的辅助流程只选择了 init/shape/prd。检查实际执行的命令、所选配置文件路径和清单；使用上文的 idea-check preview/get 添加其完整技能树。如果文件已存在，请读取对应的确切 SKILL.md，并在重新安装前检查 Agent 的发现/重新加载行为。仅缺少斜杠命令并不能证明文件缺失。
目录/配置文件错误	重新检查 cwd 和显式标志；新项目没有工具目录可能完全正常。
签名/发布版本不匹配	保留故障信息和来源标识；不要禁用验证，也不要复用无关数据。
版本/清单冲突	保留绑定信息和清单以便修复；应使用单独的 v4 项目，而不是删除它们。
文件冲突或权限故障	检查受影响的路径和本地编辑，保留备份并解决具体问题。不要进行大范围 chmod/重置/强制操作。

仅在必要时使用 --verbose，分享诊断信息前请删除凭据。 对于 bench 等无关的日常命令，请查看此运行器对应的帮助信息；不要将任意 master README 作为旧版二进制文件的权威依据。