toy
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chinesetoy: Toy 平台创作者 CLI
toy: Creator CLI for Toy Platform
通过 二进制(cobra CLI,服务端 OAuth 登录)完成 Toy 平台的创作者侧操作:打包发布、更新、预览、查询。本 skill 不写命令矩阵 —— CLI 自描述足够,写死字段名只会与代码漂移。Skill 只承载工作流和铁律。
toyComplete creator-side operations on the Toy platform via the 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.
toy何时使用
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 CLI.
toy - The old script-based publishing pipeline — this skill replaces it, and all operations should go through the official binary.
toy
前置条件
Prerequisites
- 已安装。检测
toy,没装时引导安装(参见command -v toy)。references/installation.md - 已登录。任意 API 命令首次跑可能报「登录态已失效,请执行 」,按铁律 4 处理。
toy login - 面向线上,没有环境切换选项(不暴露
toy),不要试图构造--env。全局 flag 以--env实际输出为准。--help-json
- is installed. Check with
toy; if not installed, guide the user to install it (seecommand -v toy).references/installation.md - Logged in. The first run of any API command may report "Login session expired, please run ", follow Rule 4 to handle this.
toy login - targets the production environment, with no environment switching option (do not expose
toy). Global flags are subject to the actual output of--env.--help-json
发现机制(关键)
Discovery Mechanism (Key)
不要凭记忆构造命令。第一次用某个子命令前,跑:
bash
toy --help-json输出是结构化 JSON,包含全部命令树、位置参数、flag、 标记、 取值。需要单个子树时跑 。
writeschoicestoy <cmd> --help-jsonJSON 字段语义:
| 字段 | 用途 |
|---|---|
| 命令路径数组,如 |
| 位置参数 |
| 本层 flag 列表,每条含 |
| true 表示业务写操作(如 |
| 全局 flag(如 |
Do NOT construct commands from memory. Before using a subcommand for the first time, run:
bash
toy --help-jsonThe output is structured JSON, including the full command tree, positional parameters, flags, markers, and values. For a single subtree, run .
writeschoicestoy <cmd> --help-jsonJSON Field Semantics:
| Field | Purpose |
|---|---|
| Command path array, e.g., |
| Positional parameters |
| List of flags at this level, each with |
| |
| Global flags (e.g., |
缺功能时尝试升级
Try Upgrading When Features Are Missing
用户要的能力在 里确实找不到(命令/flag 不存在,而非拼错或记错),可能是本地 太旧、新功能还没到。这时可以升一次级(命令见 )再重查 。升级失败(dev 构建、未配置分发地址、离线)属正常,直接照现有能力回复用户"当前版本不支持",别卡住或反复重试。
--help-jsontoyreferences/installation.md--help-jsonIf the capability the user needs is truly not found in (the command/flag does not exist, not a typo or misremembering), the local version may be outdated with new features not yet available. In this case, upgrade once (see for the command) and recheck . 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.
--help-jsontoyreferences/installation.md--help-json铁律
Iron Rules
按以下顺序优先级执行:
Execute in the following priority order:
1. AI 调用一律 --json
--json1. Always Use --json
for AI Calls
--json不管读还是写,AI 调 都加 。读命令(//)的表格输出会因列宽/超链接渲染变化而崩;写命令的中文成功提示也不如结构化响应好解析。 是唯一稳定契约。
toy--jsonmyliststatshistory--jsonWhether for read or write operations, AI must add when calling . Table outputs of read commands (//) may break due to column width/hyperlink rendering changes; Chinese success prompts of write commands are not as easy to parse as structured responses. is the only stable contract.
--jsontoymyliststatshistory--json2. 发布/更新是「预览 → 确认 → 提交审核」两段式,不是一步到位
2. Publish/Update is a Two-Step Process: "Preview → Confirm → Submit for Review", Not One-Step
createupdatewrites:true--yesAI 的正确姿势:
- 先不加 跑(带
--yes)。CLI 只回--json,不提交。{"preview_url": "..."} - 把 原样给用户,让用户在浏览器里检查。
preview_url - 主动发起一次显式确认(AskUserQuestion 或等价的明确询问),别只被动说「看完告诉我」。把「即将提交审核」+ 改动摘要(目标 Toy 的 /
id/title、这次改了什么、slug 保持不变)一起摆出来,请用户明确回「提交 / 不提交」。只有拿到明确肯定答复,才用同样的参数重跑并加slug。 用户没回、回得含糊(如「嗯」「好」不指向提交动作)或说要再改,都不加--yes。--yes - 提交成功后 会返回
--json,把{id, status, preview_url}/id给用户。status
铁律细节:
- 非交互场景(AI 调用)下,不带
--json= 只预览不提交;带--yes= 直接提交。绝不在用户看过预览并明确确认前加--yes。给出预览后要主动问一次「是否提交审核」,而不是被动等用户开口——弱提示(「看完告诉我」)容易让用户以为已经在走审核。--yes - 纯改标题/封面/可见性(不带 path)没有预览链接,是直接提交审核。这种也要先 AskUserQuestion 告知「即将提交审核:<改动摘要>」再加
update。--yes - 必须配
--visibility password(4-32 字符);只传--access-password会按 password 档处理。具体取值/约束以--access-password的--help-json为准。choices
When / (with ) 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 , which is the real confirmation gate (no client-side risk annotation, preview serves as the gate).
createupdatewrites:true--yesCorrect AI Workflow:
- Run without first (with
--yes). The CLI only returns--jsonand does not submit.{"preview_url": "..."} - Provide the to the user as-is, asking them to check it in a browser.
preview_url - 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, what was changed, slug remains unchanged) and ask the user to explicitly reply "Submit / Do not submit". Only addslugand 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.--yes - After successful submission, will return
--json, provide the{id, status, preview_url}/idto the user.status
Rule Details:
- In non-interactive scenarios (AI calls), without
--json= preview only, no submission; with--yes= submit directly. Never add--yesbefore 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.--yes - Purely modifying title/cover/visibility (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
update.--yes - must be paired with
--visibility password(4-32 characters); passing only--access-passwordwill be treated as the password tier. Specific values/constraints are subject to--access-passwordinchoices.--help-json
3. 带包体发布前先过内容自检
3. Perform Content Self-Check Before Publishing with Packages
toy/toy/<slug>/href="#section"references/content-checklist.mdcreateupdatereferences/content-checklist.md<path>详见 (已用官方 FAQ 校准)。
references/content-checklist.mdtoy/toy/<slug>/href="#section"references/content-checklist.mdBefore running / with a path, perform content pre-check on according to :优先 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.
createupdate<path>references/content-checklist.mdSee (calibrated with official FAQs) for details.
references/content-checklist.md4. 登录态失效是「重新 login」
4. Re-login When Login Session Expires
错误信息含「登录态已失效」「请执行 」或 envelope 为会话失效码时:
toy logincodebash
toy logintoy login--no-openreferences/error-codes.mdWhen error messages contain "Login session expired" "Please run " or the envelope is a session expiration code:
toy logincodebash
toy logintoy login--no-openreferences/error-codes.md5. 破坏性本地操作要确认
5. Confirm Destructive Local Operations
history clear--yes--yesmyliststatswhoamihistoryhistory clear--yes--yesmyliststatswhoamihistory典型工作流
Typical Workflows
工作流只锚定命令名 + 业务步骤,具体参数 / flag / 取值都用 取,避免与 CLI 漂移。
--help-jsonWorkflows only anchor command names + business steps; specific parameters / flags / values are retrieved via to avoid drifting from the CLI.
--help-jsonA. 首次发布一个本地项目
A. First-Time Publishing of a Local Project
- 确认登录态(必要时 )。
toy login - 内容预检:按铁律 3 对 做内容预检(参考
<path>),有 ERROR 先修。references/content-checklist.md - 跑 (带
create <path>,不带--json),--yes可以是目录 / 单个 HTML / 现成 zip。可按需带<path>/--title/--slug/--poster(不传 title/slug 会从路径名推导)。--visibility - 拿到 ,原样给用户,请用户在浏览器检查。
preview_url - 按铁律 2 主动发起显式确认(摆出改动摘要、请用户明确回「提交」),拿到肯定答复后再 同参数 + 重跑,提交审核。
--yes - 解析返回的 /
id给用户。status
- Confirm login status (run if necessary).
toy login - Content Pre-check: Perform content pre-check on according to Rule 3 (refer to
<path>), fix any ERRORs first.references/content-checklist.md - Run (with
create <path>, without--json),--yescan be a directory / single HTML / existing zip. Optionally add<path>/--title/--slug/--poster(if title/slug are not passed, they will be derived from the path name).--visibility - Obtain the , provide it to the user as-is, and ask them to check it in a browser.
preview_url - 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 + to submit for review after receiving an affirmative response.
--yes - Parse the returned /
idand provide them to the user.status
B. 更新已有 Toy
B. Update an Existing Toy
- 需要先知道 id:跑 (带
mylist)列出我的 Toy,从中选出目标--json。id - 带包体更新:先按铁律 3 对 做内容预检,再
<path>(不带update <id> <path>)→ 拿--yes→ 按铁律 2 主动发起显式确认 → 拿到肯定答复后同参数 +preview_url提交。保留原 slug,别为改地址走删除-重建(slug 发布后不可改)。--yes - 只改元信息(标题/封面/可见性/密码):(无预览链接,直接提交),按铁律 2 先告知再加
update <id> --title ...。--yes - 改密码档:;给现有密码档改密只传
--visibility password --access-password ...。具体看--access-password。--help-json
- Need to know the id first: Run (with
mylist) to list your Toys, select the target--json.id - Update with package: First perform content pre-check on according to Rule 3, then run
<path>(withoutupdate <id> <path>) → obtain--yes→ proactively initiate explicit confirmation according to Rule 2 → re-run with the same parameters +preview_urlto 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).--yes - Only modify metadata (title/cover/visibility/password): Run (no preview link, submit directly), inform the user first according to Rule 2 then add
update <id> --title ....--yes - Modify password tier: ; to change the password for an existing password tier, only pass
--visibility password --access-password .... See--access-passwordfor details.--help-json
C. 查看我的 Toy 与统计
C. View My Toys and Statistics
- (带
mylist,可--json/--page)看列表与可见性。--size - 单 Toy 统计 ,默认近 7 天(截至昨天,当天未结算);区间用
stats <id>或--days N(YYYY-MM-DD,最长 90 天),具体看--start/--end。脚本/JSON 务必显式传--help-json(不传会进交互选择,AI 环境会失败)。id
- Run (with
mylist, can use--json/--page) to view the list and visibility.--size - View statistics for a single Toy with , default to the last 7 days (up to yesterday, current day not settled); use
stats <id>or--days N(YYYY-MM-DD, maximum 90 days) for custom intervals, see--start/--endfor details. Scripts/JSON must explicitly pass--help-json(if not passed, it will enter interactive selection which will fail in AI environments).id
D. 用发布记录推断「新发布 vs 更新」
D. Infer "New Publish vs Update" Using Publish Records
用户给一个本地路径说「发布到 toy」时,往往没说清是首发还是更新。先查发布记录消歧,别上来就 :
create- 跑 (带
history <path>)查这个目录/文件过去有没有发过。记录按登录账号隔离,存的是历次成功--json/create的快照(含update/id/源路径等)。title - 判断:
- 查到记录(有对应 )→ 大概率是更新。用
id核对该mylist仍存在,然后走工作流 B(id)。先跟用户确认是更新这条而不是新发。update <id> <path> - 没查到记录 → 可能是首发,也可能是换了机器/换了账号/换了路径发过。别只凭本地记录拍板:可跑 看线上有没有同名/同 slug 的 Toy,再跟用户确认走
mylist(工作流 A)还是create(工作流 B)。update
- 查到记录(有对应
- 旧 只当只读补充线索(老发布链路的遗留物,不是本 skill 维护的文件)。
toy.yaml查不到、又想再确认时,可以读目录里的history,取其中的toy.yaml/id/slug当作推测线索——但必须用title核对该mylist --json在当前账号下仍存在,别直接拿来当事实。它可能过期、可能指向别人的项目。不要凭里面的id/owner_mid判断账号。uid - 和
history都只是本机线索(不影响线上、可能不全/过期),不是事实源。线上真实状态以toy.yaml为准;拿不准就让用户选。mylist
清空记录用 (破坏性,按铁律 5 确认后 )。
history clear--yesWhen 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- Run (with
history <path>) to check if this directory/file has been published before. Records are isolated by login account, storing snapshots of successful--json/createoperations (includingupdate/id/source path, etc.).title - Judgment:
- Records found (with corresponding ) → most likely an update. Verify that the
idstill exists viaid, then follow Workflow B (mylist). First confirm with the user that they want to update this Toy instead of publishing a new one.update <id> <path> - 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 to check if there is a Toy with the same name/slug online, then confirm with the user whether to use
mylist(Workflow A) orcreate(Workflow B).update
- Records found (with corresponding
- Old is only read-only supplementary clue (legacy from the old publishing pipeline, not a file maintained by this skill). If
toy.yamlfinds nothing and you want to confirm further, you can readhistoryin the directory, take thetoy.yaml/id/slugas speculative clues — but must verify that thetitlestill exists under the current account viaid, do not directly treat it as fact. It may be outdated or point to someone else's project. Do not usemylist --json/owner_midin it to judge the account.uid - and
historyare only local clues (do not affect online status, may be incomplete/outdated), not sources of truth. The real online status is subject totoy.yaml; if unsure, let the user choose.mylist
To clear records, use (destructive, add after confirmation according to Rule 5).
history clear--yes错误处理优先级
Error Handling Priority
- 登录态失效(「登录态已失效」/ 会话失效 code)→ ,重试一次,不循环。
toy login - 业务错误(envelope 的 message)→ 直接把 message 给用户,不要二次解释。
code != 0 - 非交互环境报「需要加 --yes」类提示 → 说明这是预览/提交闸门,按铁律 2 走预览-确认流程,不要无脑加 绕过。
--yes - flag/参数错误(cobra 报 /
unknown flag)→ 重新跑accepts N arg(s)对齐参数形态。--help-json没有toy,别构造它。--env
- Login session expired ("Login session expired" / session expiration code) → run , retry once, do not loop.
toy login - Business errors (envelope message) → directly provide the message to the user, do not re-interpret.
code != 0 - 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 to bypass.
--yes - Flag/parameter errors (cobra reports /
unknown flag) → re-runaccepts N arg(s)to align parameter formats.--help-jsondoes not havetoy, do not construct it.--env
不要做的事
Things NOT to Do
- 不要解析人类 help 文本(给用户看,AI 用
toy -h)。--help-json - 不要凭记忆构造 flag(命令可能升级,每次都验);没有
toy,别构造它。--env - 不要在用户看过预览并明确确认前给 /
create加update;也不要被动等用户开口,要按铁律 2 主动问一次「是否提交审核」。--yes - 不要跳过内容预检就发包(绝对路径/根绝对跳转坑会让页面打开是坏的);页内锚点 现已支持、不再报错,别再当成坑(见
href="#section"第 2 节)。references/content-checklist.md - 不要为改 slug 走「删除-重建」,除非用户明确要换地址(slug 发布后不可改,更新时保留)。
- 不要默认创建/写入/维护 (本 skill 走官方 CLI 本地记录,
toy.yaml只做只读兼容);也别把toy.yaml打进上传包。toy.yaml - 不要循环重试登录态失效;不要把 session token 写进任何输出。
- 不要对 这类破坏性命令未经确认就加
history clear。--yes
- Do not parse human-readable help text (is for users, AI uses
toy -h).--help-json - Do not construct flags from memory (commands may be upgraded, verify every time); does not have
toy, do not construct it.--env - Do not add to
--yes/createbefore 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.update - Do not skip content pre-check before uploading packages (absolute path/root absolute redirect pitfalls will break the page when opened); in-page anchors are now supported and no longer an issue, do not treat them as pitfalls (see Section 2 of
href="#section").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 by default (this skill uses official CLI local records,
toy.yamlis only for read-only compatibility); also do not includetoy.yamlin the uploaded package.toy.yaml - Do not loop retry when login session expires; do not write session tokens into any output.
- Do not add to destructive commands like
--yeswithout confirmation.history clear