verify-10x-cli

验证 10x-cli

该界面是一个短生命周期的 CLI（10x <command>），不是服务。每次运行都有自己的 模拟投递 API（使用操作系统分配的空闲端口）、自己的 XDG_CONFIG_HOME 和自己的 临时项目目录——因此多个 Agent 可以在同一台机器上并行验证，且不会触及生产环境、真实邮件、 你的 ~/.config/10x-cli 或此检出目录的 .claude/。

所有操作都通过一个辅助程序完成（从仓库根目录运行）：

V=.claude/skills/verify-10x-cli/scripts/verify.sh
$V help

启动

bun install --frozen-lockfile        # once per checkout
$V up                                # prints run=<id> api=http://127.0.0.1:<port> pid=<pid> project=<dir> evidence=<dir>
$V seed-auth                         # optional: logged-in state without driving the login flow

当 up 打印 run=… 时，即表示已就绪：scripts/fake-api.ts 只会在开始监听后才写入 api.json。 它会生成一个新的 Ed25519 密钥；CLI 通过 BUNDLE_PUBLIC_KEYSET 接受该密钥，而 src/lib/signing.ts 仅在 API_BASE_URL 为 localhost/127.0.0.1 时才会使用它。CLI 从源码运行（bun run src/index.ts）；若要验证 发布的 Node bundle，则运行 bun run build，并在命令前加上 VERIFY_ENTRY=dist。

模拟 API 提供的测试数据（课程 10xdevs3，id 为 10xdevs-3）：

课程	模块状态	内容
m1l1	已解锁	技能 verify-fixture-skill、提示词 verify-fixture-prompt、规则、配置 verify-fixture.json
m1l2	已解锁	技能 verify-m1l2-skill
m2l1	已锁定（403）	—

$V bump <lessonId> 会发布一个新的上游版本（每个文件从 v1 → v2，并生成新的目录 contentHash）——可用它验证 sync 和冲突处理。

诊断

$V doctor        # exit 0 = worth driving

只读。检查内容：模拟 API 的 pid 仍在运行，且由此次运行启动；/health 能够响应；URL 是环回地址；配置目录和项目目录属于此次运行；检出版本自 up 后 未发生变化（若有变化，则重新构建并再次运行 up）；CLI 能够启动（--version）。先运行此检查， 每当输出看起来不对时也再次运行。它不同于 10x doctor（这是一项功能，见功能 映射）。

操作

非 TTY（JSON 信封模式——stdout 不是 TTY 时，CLI 会自动启用 --json）：

$V cli <label> -- <10x args>         # e.g. $V cli get -- get m1l1 --tool claude-code

在此次运行的项目目录中执行；保存 NN-<label>.cmd|stdout|stderr|exit；并打印这些文件。辅助程序始终以 0 退出——CLI 的退出代码作为数据提供（0 正常，1 错误，2 用法错误，3 身份验证错误， 4 禁止访问，5 未找到）。在全新的项目中，调用 get/sync 时始终传入 --tool claude-code， 否则工具检测会提示操作或失败。

TTY（面向用户的输出，@clack/prompts 菜单）运行于私有 tmux 服务中（-L 10x-verify-<run>， 绝不会使用你的默认 tmux）：

$V tty <label> -- <10x args>         # start
$V wait-screen '<regex>' [seconds]   # wait for a prompt string, never a fixed sleep
$V keys Down Enter                   # tmux key names, or literal text
$V screen <label>                    # save the screen as evidence
$V wait-screen '10x exited'          # the PTY prints "[10x exited <code>]" when done

模拟环境操作：$V click（学习者点击最新的魔法链接）、$V bump <lesson>、 $V changelog release|off|on（发布较新的工具包版本；移除/恢复更新日志路由）。 状态证明：$V snapshot <label>（计算项目目录和配置目录中每个文件的 sha256）。 叙述记录：$V note "<text>" 会将内容追加到此次运行的 notes.md。

features/ 中的功能映射为每项功能列出了精确的操作流程。 请先阅读其 README；如果映射列出了其他入口，只验证一个方便的入口是不完整的。

证据

所有证据都保存在 .quality-local/verify-10x-cli/<run>/ 中（已加入 gitignore，执行 down 后仍会保留）： 带编号的 .cmd/.stdout/.stderr/.exit、.screen.txt、.tree.txt、notes.md、 fake-api.log 和 requests.log（CLI 发出的每个 HTTP 请求；执行 down 时复制）。

证据标准：

• 通过真实用户路径进行操作（在项目目录中运行 10x …）。不要导入 src/ 函数，也不要手动编写清单。seed-auth 是唯一允许的捷径，且仅适用于身份验证以外的功能。
• 捕获操作及其结果状态：命令输出以及显示写入、保留或删除内容的 snapshot（或文件内容）。
• 验证副作用，而不只是检查外层结果：磁盘上的文件、.claude/.10x-cli-manifest.json、.10x-cli.json、CLAUDE.md 规则块、auth.json，以及记录所调用端点的 requests.log。
• 已观察到 --dry-run 不会写入任何内容（比较前后 snapshot），但仍会通过网络获取数据（参见 requests.log）。更改后请重新检查；不要仅凭标志名称判断。
• 将跳过的入口点报告为已跳过，并说明未满足的前置条件。

清理

$V down

仅终止 up 记录的 fake API 进程 ID（先确认其命令行包含本次运行的临时目录）以及本次运行专用的 tmux 服务，然后删除临时目录（$TMPDIR/10x-verify-<run>.*），并保留证据目录。绝不要运行 pkill bun/pkill tmux：这台机器上还有其他会话。即使尝试失败，也要运行 down。要指定较早的一次运行：VERIFY_RUN=<id> $V down。

辅助工具

脚本	调用方式
scripts/verify.sh	$V <command> — 执行以上所有操作；$V help 会列出命令
scripts/fake-api.ts	由 $V up 启动；独立运行：bun .claude/skills/verify-10x-cli/scripts/fake-api.ts <dir> [port]

两者都是验证脚手架，不是产品代码。当 API 契约发生变化（bun run generate-types 会更新 src/generated/api-types.ts）时，请同步更新 fake-api.ts，否则验证结果会失真。