verify-10x-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Verify 10x-cli

验证10x-cli

The surface is a short-lived CLI (

10x <command>

), not a server. Every run gets its own fake delivery API on an OS-assigned free port, its own

XDG_CONFIG_HOME

, and its own throwaway project dir — so several agents can verify in parallel on one machine and nothing touches production, real email, your

~/.config/10x-cli

or this checkout's

.claude/

Everything goes through one helper (run from the repo root):

bash

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

其表层是一个短期运行的CLI（

10x <command>

），而非服务器。每次运行都会在操作系统分配的空闲端口上启动专属的模拟交付API，拥有独立的

XDG_CONFIG_HOME

和临时项目目录——因此多个Agent可以在同一台机器上并行执行验证，且不会影响生产环境、真实邮箱、你的

~/.config/10x-cli

或当前检出代码的

.claude/

目录。

所有操作都通过一个辅助脚本完成（在仓库根目录运行）：

bash

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

Launch

启动

bash

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

is ready when it prints

run=…

scripts/fake-api.ts

only writes

api.json

after it is listening. It generates a fresh Ed25519 key; the CLI accepts it through

BUNDLE_PUBLIC_KEYSET

, which

src/lib/signing.ts

honours only when

API_BASE_URL

localhost

127.0.0.1

. The CLI runs from source (

bun run src/index.ts

); to prove the shipped Node bundle instead,

bun run build

and prefix commands with

VERIFY_ENTRY=dist

Fixture served by the fake API (course

10xdevs3

, id

10xdevs-3

Lesson	Module state	Content
`m1l1`	unlocked	skill `verify-fixture-skill` , prompt `verify-fixture-prompt` , rule, config `verify-fixture.json`
`m1l2`	unlocked	skill `verify-m1l2-skill`
`m2l1`	locked (403)	—

$V bump <lessonId>

publishes a new upstream version (

v1

→

v2

in every file and a new catalog

contentHash

) — use it to prove

sync

and conflict handling.

bash

bun install --frozen-lockfile        # 每个检出版本只需执行一次
$V up                                # 输出 run=<id> api=http://127.0.0.1:<port> pid=<pid> project=<dir> evidence=<dir>
$V seed-auth                         # 可选：无需驱动登录流程即可获得已登录状态

当

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包，请先执行

bun run build

，并在命令前加上

VERIFY_ENTRY=dist

前缀。

模拟API提供的测试固件（课程

10xdevs3

，ID为

10xdevs-3

）：

课时	模块状态	内容
`m1l1`	已解锁	skill `verify-fixture-skill` 、prompt `verify-fixture-prompt` 、规则、配置 `verify-fixture.json`
`m1l2`	已解锁	skill `verify-m1l2-skill`
`m2l1`	已锁定（403）	—

$V bump <lessonId>

会发布新的上游版本（所有文件从

v1

升级到

v2

，并生成新的目录

contentHash

）——可用于验证

sync

命令和冲突处理逻辑。

Doctor

诊断

bash

$V doctor        # exit 0 = worth driving

Read-only. Checks: the fake API pid is alive and was started by this run,

/health

answers, the URL is loopback, config/project dirs are this run's, the checkout revision has not changed since

up

(rebuild/re-

up

if it did), and the CLI starts (

--version

). Run it first, and again whenever output looks wrong. Not the same as

10x doctor

(a feature, see the map).

bash

$V doctor        # 退出码0 = 可正常驱动验证

只读操作。检查项包括：模拟API的pid仍在运行且由本次运行启动、

/health

接口可正常响应、URL为回环地址、配置/项目目录属于本次运行、自

up

执行以来检出的代码版本未发生变化（若有变化需重新构建/重新执行

up

），以及CLI可正常启动（

--version

命令）。请先运行此命令，当输出看起来有问题时也可再次运行。它与

10x doctor

不同（后者是一项功能，详见功能地图）。

Drive

驱动操作

Non-TTY (JSON envelope mode — the CLI implies

--json

when stdout is not a TTY):

bash

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

Runs in the run's project dir; saves

NN-<label>.cmd|stdout|stderr|exit

; prints them. The helper always exits 0 — the CLI's exit code is data (

ok,

error,

usage,

auth,

forbidden,

not found). Always pass

--tool claude-code

get

sync

in a fresh project, or tool detection prompts / fails.

TTY (human output,

@clack/prompts

menus) in a private tmux server (

-L 10x-verify-<run>

, never your default tmux):

bash

$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

Fake-world actions:

$V click

(the learner clicks the newest magic link),

$V bump <lesson>

$V changelog release|off|on

(publish a newer toolkit release; remove / restore the changelog route). State proof:

$V snapshot <label>

(sha256 of every file in project + config dirs). Narrative:

$V note "<text>"

appends to the run's

notes.md

The feature map in

features/

has the exact recipe per feature. Read its README first; a proof that drives one convenient entry point is incomplete when the map lists others.

非TTY模式（JSON封装模式——当stdout不是TTY时，CLI会默认启用

--json

参数）：

bash

$V cli <label> -- <10x args>         # 例如 $V cli get -- get m1l1 --tool claude-code

在本次运行的项目目录中执行；保存

NN-<label>.cmd|stdout|stderr|exit

文件；并打印这些内容。辅助脚本始终以0退出——CLI的退出码会作为数据记录（

成功，

错误，

用法错误，

认证错误，

禁止访问，

未找到）。在新项目中执行

get

sync

命令时请务必传入

--tool claude-code

，否则工具检测会提示/失败。

TTY模式（人类可读输出，

@clack/prompts

菜单）运行在私有tmux服务器中（

-L 10x-verify-<run>

，绝不会使用你的默认tmux）：

bash

$V tty <label> -- <10x args>         # 启动
$V wait-screen '<regex>' [seconds]   # 等待提示字符串出现，不要使用固定时长等待
$V keys Down Enter                   # tmux 按键名称，或直接输入文本
$V screen <label>                    # 保存当前屏幕作为证据
$V wait-screen '10x exited'          # 执行完成时PTY会输出 "[10x exited <code>]"

模拟场景操作：

$V click

（模拟学习者点击最新的魔法链接）、

$V bump <lesson>

、

$V changelog release|off|on

（发布更新的工具包版本；移除/恢复更新日志接口）。状态证明：

$V snapshot <label>

（项目+配置目录中所有文件的sha256哈希）。记录说明：

$V note "<text>"

会将内容追加到本次运行的

notes.md

文件中。

features/

目录下的功能地图包含每个功能的具体验证流程。请先阅读其README；如果功能地图列出了多个入口点，仅验证一个便捷入口点的证明是不完整的。

Evidence

证据

All proof lands in

.quality-local/verify-10x-cli/<run>/

(gitignored, survives

down

): numbered

.cmd/.stdout/.stderr/.exit

.screen.txt

.tree.txt

notes.md

fake-api.log

, and

requests.log

(every HTTP request the CLI made, copied at

down

Proof standards:

Drive the real user path (
```
10x …
```
in a project dir). No importing
```
src/
```
functions, no writing the manifest by hand.
```
seed-auth
```
is the one allowed shortcut, and only for features other than auth.
Capture the action and the resulting state: the command output and a
```
snapshot
```
(or file contents) showing what was written, kept or removed.
Verify side effects, not just the envelope: files on disk,
```
.claude/.10x-cli-manifest.json
```
,
```
.10x-cli.json
```
,
```
CLAUDE.md
```
rule block,
```
auth.json
```
, and
```
requests.log
```
for which endpoints were hit.
```
--dry-run
```
was observed to write nothing (compare
```
snapshot
```
before/after) but still fetch over the network (see
```
requests.log
```
). Re-check that when you change it; do not trust the flag name.
```
10x doctor
```
calls the real npm registry (
```
registry.npmjs.org
```
, read-only GET) for its version check. Everything else stays on the fake API.
Report skipped entry points as skipped, with the unmet precondition.

所有证明材料都存放在

.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
```
）。修改该功能时请重新验证此行为；不要仅凭参数名称判断其作用。
```
10x doctor
```
会调用真实的npm registry（
```
registry.npmjs.org
```
，只读GET请求）进行版本检查。其余所有请求都指向模拟API。
对于跳过的入口点，需明确标注为已跳过，并说明未满足的前置条件。

Cleanup

清理

bash

$V down

Kills only the fake API pid recorded by

up

(after checking its command line contains this run's scratch dir) and this run's private tmux server, deletes the scratch dir (

$TMPDIR/10x-verify-<run>.*

), and keeps the evidence dir. Never

pkill bun

pkill tmux

: other sessions run on this machine. After a failed attempt, still run

down

. To target an older run:

VERIFY_RUN=<id> $V down

bash

$V down

仅会终止

up

记录的模拟API pid（会先检查其命令行包含本次运行的临时目录）和本次运行的私有tmux服务器，删除临时目录（

$TMPDIR/10x-verify-<run>.*

），并保留证据目录。切勿使用

pkill bun

pkill tmux

：机器上可能还有其他会话在运行。即使验证失败，也请执行

down

命令。若要清理旧的运行实例：

VERIFY_RUN=<id> $V down

。

Helpers

辅助脚本

Script	Invocation
`scripts/verify.sh`	`$V <command>` — all of the above; `$V help` lists commands
`scripts/fake-api.ts`	started by `$V up` ; standalone: `bun .claude/skills/verify-10x-cli/scripts/fake-api.ts <dir> [port]`

Both are verification scaffolding, not product code. When the API contract changes (

bun run generate-types

updates

src/generated/api-types.ts

), update

fake-api.ts

to match or verification will lie.

脚本	调用方式
`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

以保持一致，否则验证结果会失真。