toy

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

toy: Toy 平台创作者 CLI

toy: Creator CLI for Toy Platform

通过
toy
二进制(cobra CLI,服务端 OAuth 登录)完成 Toy 平台的创作者侧操作:打包发布、更新、预览、查询。本 skill 不写命令矩阵 —— CLI 自描述足够,写死字段名只会与代码漂移。Skill 只承载工作流和铁律。
Complete creator-side operations on the Toy platform via the
toy
binary (cobra CLI, server-side OAuth login): package and publish, update, preview, query. This skill does not include a command matrix — the CLI is self-descriptive enough, and hardcoding field names will only drift from the code. The skill only carries workflows and iron rules.

何时使用

When to Use

用户提到把本地项目/HTML/zip 发布到 toy、更新已有 Toy、看自己的 Toy 列表或访问统计、查发布记录等创作者场景。
不要用于:
  • Toy 平台运营/后台操作(版本审核、白名单、检索删除别人的 Toy、大盘统计)—— 这些不在创作者
    toy
    的能力范围内。
  • 老的脚本式发布链路 —— 本 skill 取代它,统一走官方
    toy
    二进制。
Use this skill when users mention scenarios like publishing local projects/HTML/zip to Toy, updating existing Toys, viewing their Toy list or access statistics, checking publish records, etc.
Do NOT use for:
  • Operation/backend operations on the Toy platform (version review, whitelist, retrieving and deleting others' Toys, overall statistics) — these are beyond the capabilities of the creator
    toy
    CLI.
  • The old script-based publishing pipeline — this skill replaces it, and all operations should go through the official
    toy
    binary.

前置条件

Prerequisites

  1. toy
    已安装。检测
    command -v toy
    ,没装时引导安装(参见
    references/installation.md
    )。
  2. 已登录。任意 API 命令首次跑可能报「登录态已失效,请执行
    toy login
    」,按铁律 4 处理。
  3. toy
    面向线上,没有环境切换选项(不暴露
    --env
    ),不要试图构造
    --env
    。全局 flag 以
    --help-json
    实际输出为准。
  1. toy
    is installed. Check with
    command -v toy
    ; if not installed, guide the user to install it (see
    references/installation.md
    ).
  2. Logged in. The first run of any API command may report "Login session expired, please run
    toy login
    ", follow Rule 4 to handle this.
  3. toy
    targets the production environment, with no environment switching option (do not expose
    --env
    ). Global flags are subject to the actual output of
    --help-json
    .

发现机制(关键)

Discovery Mechanism (Key)

不要凭记忆构造命令。第一次用某个子命令前,跑:
bash
toy --help-json
输出是结构化 JSON,包含全部命令树、位置参数、flag、
writes
标记、
choices
取值。需要单个子树时跑
toy <cmd> --help-json
JSON 字段语义:
字段用途
commands[].path
命令路径数组,如
["create"]
["history","clear"]
commands[].args
位置参数
{min, max, names, variadic}
commands[].flags
本层 flag 列表,每条含
type/default/choices/required
commands[].writes
true 表示业务写操作(如
create
/
update
global_flags
全局 flag(如
--json
Do NOT construct commands from memory. Before using a subcommand for the first time, run:
bash
toy --help-json
The output is structured JSON, including the full command tree, positional parameters, flags,
writes
markers, and
choices
values. For a single subtree, run
toy <cmd> --help-json
.
JSON Field Semantics:
FieldPurpose
commands[].path
Command path array, e.g.,
["create"]
,
["history","clear"]
commands[].args
Positional parameters
{min, max, names, variadic}
commands[].flags
List of flags at this level, each with
type/default/choices/required
commands[].writes
true
indicates a business write operation (e.g.,
create
/
update
)
global_flags
Global flags (e.g.,
--json
)

缺功能时尝试升级

Try Upgrading When Features Are Missing

用户要的能力在
--help-json
里确实找不到(命令/flag 不存在,而非拼错或记错),可能是本地
toy
太旧、新功能还没到。这时可以升一次级(命令见
references/installation.md
)再重查
--help-json
。升级失败(dev 构建、未配置分发地址、离线)属正常,直接照现有能力回复用户"当前版本不支持",别卡住或反复重试。
If the capability the user needs is truly not found in
--help-json
(the command/flag does not exist, not a typo or misremembering), the local
toy
version may be outdated with new features not yet available. In this case, upgrade once (see
references/installation.md
for the command) and recheck
--help-json
. Upgrade failures (dev build, no distribution address configured, offline) are normal; directly inform the user "Current version does not support this" instead of getting stuck or retrying repeatedly.

铁律

Iron Rules

按以下顺序优先级执行:
Execute in the following priority order:

1. AI 调用一律
--json

1. Always Use
--json
for AI Calls

不管读还是写,AI 调
toy
都加
--json
。读命令(
mylist
/
stats
/
history
)的表格输出会因列宽/超链接渲染变化而崩;写命令的中文成功提示也不如结构化响应好解析。
--json
是唯一稳定契约。
Whether for read or write operations, AI must add
--json
when calling
toy
. Table outputs of read commands (
mylist
/
stats
/
history
) may break due to column width/hyperlink rendering changes; Chinese success prompts of write commands are not as easy to parse as structured responses.
--json
is the only stable contract.

2. 发布/更新是「预览 → 确认 → 提交审核」两段式,不是一步到位

2. Publish/Update is a Two-Step Process: "Preview → Confirm → Submit for Review", Not One-Step

create
/
update
writes:true
)带包体时,CLI 先上传打包、生成 preview_url默认不提交审核。提交审核由
--yes
触发,是真正的确认闸门(client 侧没有 risk 注解,预览即闸门)。
AI 的正确姿势:
  1. 先不加
    --yes
    (带
    --json
    )。CLI 只回
    {"preview_url": "..."}
    ,不提交。
  2. preview_url
    原样给用户,让用户在浏览器里检查。
  3. 主动发起一次显式确认(AskUserQuestion 或等价的明确询问),别只被动说「看完告诉我」。把「即将提交审核」+ 改动摘要(目标 Toy 的
    id
    /
    title
    /
    slug
    、这次改了什么、slug 保持不变)一起摆出来,请用户明确回「提交 / 不提交」。只有拿到明确肯定答复,才用同样的参数重跑并加
    --yes
    用户没回、回得含糊(如「嗯」「好」不指向提交动作)或说要再改,都不加
    --yes
  4. 提交成功后
    --json
    会返回
    {id, status, preview_url}
    ,把
    id
    /
    status
    给用户。
铁律细节:
  • 非交互场景(AI 调用)下,
    --json
    不带
    --yes
    = 只预览不提交;带
    --yes
    = 直接提交。绝不在用户看过预览并明确确认前加
    --yes
    。给出预览后要主动问一次「是否提交审核」,而不是被动等用户开口——弱提示(「看完告诉我」)容易让用户以为已经在走审核。
  • 纯改标题/封面/可见性(
    update
    不带 path)没有预览链接,是直接提交审核。这种也要先 AskUserQuestion 告知「即将提交审核:<改动摘要>」再加
    --yes
  • --visibility password
    必须配
    --access-password
    (4-32 字符);只传
    --access-password
    会按 password 档处理。具体取值/约束以
    --help-json
    choices
    为准。
When
create
/
update
(with
writes:true
) includes a package, the CLI first uploads and packages it, generates a preview_url, and does not submit for review by default. Submitting for review is triggered by
--yes
, which is the real confirmation gate (no client-side risk annotation, preview serves as the gate).
Correct AI Workflow:
  1. Run without
    --yes
    first
    (with
    --json
    ). The CLI only returns
    {"preview_url": "..."}
    and does not submit.
  2. Provide the
    preview_url
    to the user as-is, asking them to check it in a browser.
  3. Initiate an explicit confirmation proactively (AskUserQuestion or equivalent clear inquiry), instead of just passively saying "Let me know when you're done viewing". Present "About to submit for review" + change summary (target Toy's
    id
    /
    title
    /
    slug
    , what was changed, slug remains unchanged) and ask the user to explicitly reply "Submit / Do not submit". Only add
    --yes
    and re-run with the same parameters after receiving a clear affirmative response
    . If the user does not reply, gives an ambiguous answer (e.g., "Hmm" "Okay" that does not indicate submission) or says they need to modify further, do not add
    --yes
    .
  4. After successful submission,
    --json
    will return
    {id, status, preview_url}
    , provide the
    id
    /
    status
    to the user.
Rule Details:
  • In non-interactive scenarios (AI calls),
    --json
    without
    --yes
    = preview only, no submission; with
    --yes
    = submit directly. Never add
    --yes
    before the user has viewed the preview and explicitly confirmed
    . After providing the preview, proactively ask "Whether to submit for review" instead of waiting passively — weak prompts ("Let me know when you're done") may make users think the review process has already started.
  • Purely modifying title/cover/visibility (
    update
    without path) has no preview link and is submitted for review directly. In this case, also use AskUserQuestion to inform "About to submit for review: <change summary>" before adding
    --yes
    .
  • --visibility password
    must be paired with
    --access-password
    (4-32 characters); passing only
    --access-password
    will be treated as the password tier. Specific values/constraints are subject to
    choices
    in
    --help-json
    .

3. 带包体发布前先过内容自检

3. Perform Content Self-Check Before Publishing with Packages

toy
只打包上传,不校验包内容。toy 页面跑在
/toy/<slug>/
子路径下,绝对路径资源、根绝对跳转等会让页面白屏 / 404 / 链接错乱——包能传、审核可能也过,但打开是坏的。(注:页内锚点
href="#section"
现已支持,不再是坑,见
references/content-checklist.md
§2。)
create
/
update
带 path 前,按
references/content-checklist.md
<path>
做内容预检:优先用清单里提供的自动化预检手段,跑不了再照清单 §1–§6 人肉过一遍高频坑(绝对路径、hash 路由 vs history 路由、构建产物 vs 源码、封面、slug 不可改)。有 ERROR 先给用户、修完再传,别硬传。
详见
references/content-checklist.md
(已用官方 FAQ 校准)。
toy
only packages and uploads, does not validate package content. Toy pages run under the
/toy/<slug>/
subpath; absolute path resources, root absolute redirects, etc., will cause white screens / 404 / link errors — the package can be uploaded and may pass review, but the page will be broken when opened. (Note: In-page anchors
href="#section"
are now supported and no longer a pitfall, see §2 of
references/content-checklist.md
.)
Before running
create
/
update
with a path, perform content pre-check on
<path>
according to
references/content-checklist.md
:优先 use the automated pre-check methods provided in the checklist; if unavailable, manually check high-frequency pitfalls (absolute paths, hash routing vs history routing, build artifacts vs source code, cover image, slug cannot be changed) in §1–§6 of the checklist. If there are ERRORs, inform the user first and fix them before uploading, do not force upload.
See
references/content-checklist.md
(calibrated with official FAQs) for details.

4. 登录态失效是「重新 login」

4. Re-login When Login Session Expires

错误信息含「登录态已失效」「请执行
toy login
」或 envelope
code
为会话失效码时:
bash
toy login
toy login
会走浏览器 OAuth(会自动开浏览器,
--no-open
可关)。登录后重试原命令一次。仍失败则停下报告用户,不要循环。详见
references/error-codes.md
When error messages contain "Login session expired" "Please run
toy login
" or the envelope
code
is a session expiration code:
bash
toy login
toy login
will use browser OAuth (automatically opens a browser,
--no-open
can disable this). Retry the original command once after login. If it still fails, stop and report to the user, do not loop. See
references/error-codes.md
for details.

5. 破坏性本地操作要确认

5. Confirm Destructive Local Operations

history clear
会删除本机全部发布记录(仅本地流水,不影响线上 Toy)。它带
--yes
跳过确认。AI 要执行时必须先 AskUserQuestion 确认,再加
--yes
。其余只读命令(
mylist
/
stats
/
whoami
/
history
查看)直接跑。
history clear
will delete all local publish records (only local logs, does not affect online Toys). It has
--yes
to skip confirmation. When AI needs to execute this, it must first use AskUserQuestion to confirm, then add
--yes
. Other read-only commands (
mylist
/
stats
/
whoami
/
history
view) can be run directly.

典型工作流

Typical Workflows

工作流只锚定命令名 + 业务步骤,具体参数 / flag / 取值都用
--help-json
取,避免与 CLI 漂移。
Workflows only anchor command names + business steps; specific parameters / flags / values are retrieved via
--help-json
to avoid drifting from the CLI.

A. 首次发布一个本地项目

A. First-Time Publishing of a Local Project

  1. 确认登录态(必要时
    toy login
    )。
  2. 内容预检:按铁律 3 对
    <path>
    做内容预检(参考
    references/content-checklist.md
    ),有 ERROR 先修。
  3. create <path>
    (带
    --json
    不带
    --yes
    ),
    <path>
    可以是目录 / 单个 HTML / 现成 zip。可按需带
    --title
    /
    --slug
    /
    --poster
    /
    --visibility
    (不传 title/slug 会从路径名推导)。
  4. 拿到
    preview_url
    ,原样给用户,请用户在浏览器检查。
  5. 按铁律 2 主动发起显式确认(摆出改动摘要、请用户明确回「提交」),拿到肯定答复后再 同参数 +
    --yes
    重跑,提交审核。
  6. 解析返回的
    id
    /
    status
    给用户。
  1. Confirm login status (run
    toy login
    if necessary).
  2. Content Pre-check: Perform content pre-check on
    <path>
    according to Rule 3 (refer to
    references/content-checklist.md
    ), fix any ERRORs first.
  3. Run
    create <path>
    (with
    --json
    , without
    --yes
    ),
    <path>
    can be a directory / single HTML / existing zip. Optionally add
    --title
    /
    --slug
    /
    --poster
    /
    --visibility
    (if title/slug are not passed, they will be derived from the path name).
  4. Obtain the
    preview_url
    , provide it to the user as-is, and ask them to check it in a browser.
  5. Proactively initiate explicit confirmation according to Rule 2 (present the change summary, ask the user to explicitly reply "Submit"), then re-run with the same parameters +
    --yes
    to submit for review after receiving an affirmative response.
  6. Parse the returned
    id
    /
    status
    and provide them to the user.

B. 更新已有 Toy

B. Update an Existing Toy

  1. 需要先知道 id:跑
    mylist
    (带
    --json
    )列出我的 Toy,从中选出目标
    id
  2. 带包体更新:先按铁律 3 对
    <path>
    做内容预检,再
    update <id> <path>
    (不带
    --yes
    )→ 拿
    preview_url
    按铁律 2 主动发起显式确认 → 拿到肯定答复后同参数 +
    --yes
    提交。保留原 slug,别为改地址走删除-重建(slug 发布后不可改)。
  3. 只改元信息(标题/封面/可见性/密码):
    update <id> --title ...
    (无预览链接,直接提交),按铁律 2 先告知再加
    --yes
  4. 改密码档:
    --visibility password --access-password ...
    ;给现有密码档改密只传
    --access-password
    。具体看
    --help-json
  1. Need to know the id first: Run
    mylist
    (with
    --json
    ) to list your Toys, select the target
    id
    .
  2. Update with package: First perform content pre-check on
    <path>
    according to Rule 3, then run
    update <id> <path>
    (without
    --yes
    ) → obtain
    preview_url
    proactively initiate explicit confirmation according to Rule 2 → re-run with the same parameters +
    --yes
    to submit after receiving an affirmative response. Keep the original slug, do not use delete-recreate to change the address (slug cannot be changed after publishing).
  3. Only modify metadata (title/cover/visibility/password): Run
    update <id> --title ...
    (no preview link, submit directly), inform the user first according to Rule 2 then add
    --yes
    .
  4. Modify password tier:
    --visibility password --access-password ...
    ; to change the password for an existing password tier, only pass
    --access-password
    . See
    --help-json
    for details.

C. 查看我的 Toy 与统计

C. View My Toys and Statistics

  1. mylist
    (带
    --json
    ,可
    --page
    /
    --size
    )看列表与可见性。
  2. 单 Toy 统计
    stats <id>
    ,默认近 7 天(截至昨天,当天未结算);区间用
    --days N
    --start/--end
    (YYYY-MM-DD,最长 90 天),具体看
    --help-json
    。脚本/JSON 务必显式传
    id
    (不传会进交互选择,AI 环境会失败)。
  1. Run
    mylist
    (with
    --json
    , can use
    --page
    /
    --size
    ) to view the list and visibility.
  2. View statistics for a single Toy with
    stats <id>
    , default to the last 7 days (up to yesterday, current day not settled); use
    --days N
    or
    --start/--end
    (YYYY-MM-DD, maximum 90 days) for custom intervals, see
    --help-json
    for details. Scripts/JSON must explicitly pass
    id
    (if not passed, it will enter interactive selection which will fail in AI environments).

D. 用发布记录推断「新发布 vs 更新」

D. Infer "New Publish vs Update" Using Publish Records

用户给一个本地路径说「发布到 toy」时,往往没说清是首发还是更新。先查发布记录消歧,别上来就
create
  1. history <path>
    (带
    --json
    )查这个目录/文件过去有没有发过。记录按登录账号隔离,存的是历次成功
    create
    /
    update
    的快照(含
    id
    /
    title
    /源路径等)。
  2. 判断:
    • 查到记录(有对应
      id
      )→ 大概率是更新。用
      mylist
      核对该
      id
      仍存在,然后走工作流 B(
      update <id> <path>
      )。先跟用户确认是更新这条而不是新发。
    • 没查到记录 → 可能是首发,也可能是换了机器/换了账号/换了路径发过。别只凭本地记录拍板:可跑
      mylist
      看线上有没有同名/同 slug 的 Toy,再跟用户确认走
      create
      (工作流 A)还是
      update
      (工作流 B)。
  3. toy.yaml
    只当只读补充线索
    (老发布链路的遗留物,不是本 skill 维护的文件)。
    history
    查不到、又想再确认时,可以读目录里的
    toy.yaml
    ,取其中的
    id
    /
    slug
    /
    title
    当作推测线索——但必须用
    mylist --json
    核对该
    id
    在当前账号下仍存在,别直接拿来当事实。它可能过期、可能指向别人的项目。不要凭里面的
    owner_mid
    /
    uid
    判断账号。
  4. history
    toy.yaml
    都只是本机线索(不影响线上、可能不全/过期),不是事实源。线上真实状态以
    mylist
    为准;拿不准就让用户选。
清空记录用
history clear
(破坏性,按铁律 5 确认后
--yes
)。
When a user provides a local path and says "Publish to Toy", they often do not clarify whether it is a first-time publish or an update. First check publish records to disambiguate, do not start with
create
:
  1. Run
    history <path>
    (with
    --json
    ) to check if this directory/file has been published before. Records are isolated by login account, storing snapshots of successful
    create
    /
    update
    operations (including
    id
    /
    title
    /source path, etc.).
  2. Judgment:
    • Records found (with corresponding
      id
      ) → most likely an update. Verify that the
      id
      still exists via
      mylist
      , then follow Workflow B (
      update <id> <path>
      ). First confirm with the user that they want to update this Toy instead of publishing a new one.
    • No records found → may be a first-time publish, or may have been published on another machine/account/path. Do not rely solely on local records: run
      mylist
      to check if there is a Toy with the same name/slug online, then confirm with the user whether to use
      create
      (Workflow A) or
      update
      (Workflow B).
  3. Old
    toy.yaml
    is only read-only supplementary clue
    (legacy from the old publishing pipeline, not a file maintained by this skill). If
    history
    finds nothing and you want to confirm further, you can read
    toy.yaml
    in the directory, take the
    id
    /
    slug
    /
    title
    as speculative clues — but must verify that the
    id
    still exists under the current account via
    mylist --json
    , do not directly treat it as fact. It may be outdated or point to someone else's project. Do not use
    owner_mid
    /
    uid
    in it to judge the account.
  4. history
    and
    toy.yaml
    are only local clues (do not affect online status, may be incomplete/outdated), not sources of truth. The real online status is subject to
    mylist
    ; if unsure, let the user choose.
To clear records, use
history clear
(destructive, add
--yes
after confirmation according to Rule 5).

错误处理优先级

Error Handling Priority

  1. 登录态失效(「登录态已失效」/ 会话失效 code)→
    toy login
    ,重试一次,不循环。
  2. 业务错误(envelope
    code != 0
    的 message)→ 直接把 message 给用户,不要二次解释。
  3. 非交互环境报「需要加 --yes」类提示 → 说明这是预览/提交闸门,按铁律 2 走预览-确认流程,不要无脑加
    --yes
    绕过。
  4. flag/参数错误(cobra 报
    unknown flag
    /
    accepts N arg(s)
    )→ 重新跑
    --help-json
    对齐参数形态。
    toy
    没有
    --env
    ,别构造它。
  1. Login session expired ("Login session expired" / session expiration code) → run
    toy login
    , retry once, do not loop.
  2. Business errors (envelope
    code != 0
    message) → directly provide the message to the user, do not re-interpret.
  3. Non-interactive environment reports prompts like "Need to add --yes" → this indicates a preview/submit gate, follow Rule 2 to go through the preview-confirmation process, do not mindlessly add
    --yes
    to bypass.
  4. Flag/parameter errors (cobra reports
    unknown flag
    /
    accepts N arg(s)
    ) → re-run
    --help-json
    to align parameter formats.
    toy
    does not have
    --env
    , do not construct it.

不要做的事

Things NOT to Do

  • 不要解析人类 help 文本(
    toy -h
    给用户看,AI 用
    --help-json
    )。
  • 不要凭记忆构造 flag(命令可能升级,每次都验);
    toy
    没有
    --env
    ,别构造它。
  • 不要在用户看过预览并明确确认前给
    create
    /
    update
    --yes
    ;也不要被动等用户开口,要按铁律 2 主动问一次「是否提交审核」。
  • 不要跳过内容预检就发包(绝对路径/根绝对跳转坑会让页面打开是坏的);页内锚点
    href="#section"
    现已支持、不再报错,别再当成坑(见
    references/content-checklist.md
    第 2 节)。
  • 不要为改 slug 走「删除-重建」,除非用户明确要换地址(slug 发布后不可改,更新时保留)。
  • 不要默认创建/写入/维护
    toy.yaml
    (本 skill 走官方 CLI 本地记录,
    toy.yaml
    只做只读兼容);也别把
    toy.yaml
    打进上传包。
  • 不要循环重试登录态失效;不要把 session token 写进任何输出。
  • 不要对
    history clear
    这类破坏性命令未经确认就加
    --yes
  • Do not parse human-readable help text (
    toy -h
    is for users, AI uses
    --help-json
    ).
  • Do not construct flags from memory (commands may be upgraded, verify every time);
    toy
    does not have
    --env
    , do not construct it.
  • Do not add
    --yes
    to
    create
    /
    update
    before the user has viewed the preview and explicitly confirmed; also do not wait passively for the user to speak, proactively ask "Whether to submit for review" according to Rule 2.
  • Do not skip content pre-check before uploading packages (absolute path/root absolute redirect pitfalls will break the page when opened); in-page anchors
    href="#section"
    are now supported and no longer an issue, do not treat them as pitfalls (see Section 2 of
    references/content-checklist.md
    ).
  • Do not use "delete-recreate" to change the slug unless the user explicitly wants to change the address (slug cannot be changed after publishing, keep it during updates).
  • Do not create/write/maintain
    toy.yaml
    by default (this skill uses official CLI local records,
    toy.yaml
    is only for read-only compatibility); also do not include
    toy.yaml
    in the uploaded package.
  • Do not loop retry when login session expires; do not write session tokens into any output.
  • Do not add
    --yes
    to destructive commands like
    history clear
    without confirmation.