创建并发布 Coursmith 课程
您将课程编写为一个包含 course.json 和 assets/ 目录的文件夹，使用 coursmith CLI 检查，然后提交。门户网站上的审核代理会批准、要求修订或拒绝该课程。当课程获得批准，或者您向用户解释了审核结果后，您的工作即告结束。
以 npx --yes coursmith@latest <command> --json 格式运行 CLI。公共 npm 包中包含 CLI 和本技能；无需 GitHub 访问或全局安装。如果缺少 npx，请要求用户安装 Node.js 20 或更新版本，并按照 /install 的指南操作。使用 --json 时，每个命令会打印一个 JSON 文档；请读取该文档，不要猜测。
在此技能文件夹中引用文件（在到达相应步骤时读取它们）：
| 文件 | 用途 |
|---|---|
references/course.schema.json | course.json 的确切结构。未知键将被拒绝。 |
references/block-catalog.md | 每个内容块和视觉元素，附带有效的 JSON 示例和规则。 |
references/animation-presets.md | 7 个动画预设及其使用场景。 |
references/writing-guide.md | 如何编写能通过审核的步骤、词汇表和测验。 |
references/content-policy.md | 不允许的内容以及如何处理敏感话题。 |
examples/sample-course/ | 一个能通过验证的完整课程。请仿照其结构。 |
1. 登录
- 运行
npx --yes coursmith@latest whoami --json。如果打印出username，则继续步骤 2。 - 否则运行
npx --yes coursmith@latest login --no-wait --json。向用户显示verificationUri和userCode，并要求他们打开链接、检查代码并点击批准。 - 当用户确认后，运行
npx --yes coursmith@latest login --resume --json并检查是否打印出logged_in。
2. 与用户商定课程内容
在一次消息中，询问用户尚未提供的所有信息：
- 主题，以及（如有用）角度或受众。
- 课程的语言（任何语言；你需要其 BCP-47 代码，例如
it、en、pt-BR）。 - 难度：
beginner、intermediate或advanced。 - 可选：期望时长（默认约 30 分钟）、先决条件、需要包含或避免的内容。
对照 references/content-policy.md 检查主题。如果不允许，则说明并停止。如果是敏感话题（健康、法律、金融、政治、宗教……），则计划中立的处理方式和免责声明。
3. 提出大纲并获得批准
向用户展示：
- 标题、一行副标题、2-6 个学习目标；
- 3-6 个章节，每个章节包含一行摘要和 2-5 个步骤标题；
- 针对每个步骤，你计划的视觉元素（图表、图示、动画预设、图片或无）；
- 计划的问题数量（至少 10 题，覆盖所有章节）。
不断修改直到用户同意。在此之前不要编写 course.json。
4. 编写课程
创建一个以课程名称命名的新文件夹（kebab-case），其中包含 course.json 和 assets/。严格遵循 references/course.schema.json 并仿照 examples/sample-course/course.json 的结构。
验证器强制执行的规则（详情见 references/block-catalog.md）：
schemaVersion为"1.0"。不要编写courseId：CLI 会管理它。- 所有 id 均为小写字母、数字和短横线，在整个课程中唯一（章节、步骤、资源、测验问题）。
- 每个步骤都有
title和至少一个块；大多数步骤也有visual。 - 词汇表：每个章节都有一个
glossary，定义该章节引入的所有概念及其使用的所有技术或领域术语。在文本中，将每个术语标记为[[term]]，或当措辞不同时标记为[[term|text shown]]（使用aliases表示复数形式和词形变化）。标记的术语必须在同一章节或之前的章节中定义。定义应自包含，并使用课程语言编写。 - 视觉元素：图表是内联
data.values的 Vega-Lite 规范（无 URL）；图示是 Mermaid，不包含click或%%{init}%%；动画使用 7 种预设之一；图片通过 id 引用资源。 - Markdown：无原始 HTML，无 Markdown 图片（使用图片块），链接必须是
https://。 - 最终测验：至少 10 个问题；每个章节至少被一个问题覆盖（
sectionRef）；每个问题都有explanation。类型：single、multiple、true_false、ordering（排序项按正确顺序列出；门户网站会打乱它们）。 - 可选的
check问题位于步骤末尾，为学习者提供快速反馈，不计分。
逐个章节编写，并保持语言、难度和术语在整个课程中一致（参见 references/writing-guide.md）。
5. 创建资源
- 需要封面图片（
meta.coverImage），理想尺寸为 1200×630。 - 如果你有图像生成工具，可生成 PNG、JPEG 或 WebP 文件。否则手动编写干净的 SVG：简单的形状、清晰的调色板、设置
viewBox，不含脚本、外部链接或字体、嵌入式图片。 - 对于
highlight-svg动画，为需要高亮的元素赋予id属性。 - 将每个文件直接放入
assets/目录，并在assets[]中声明，包含kind（image或svg）、file（assets/<name>）和有意义的alt文本。为 AI 生成的图像填写generatedBy。 - 每个文件必须小于 3 MB；整个包小于 25 MB。
6. 验证直到无误
运行 npx --yes coursmith@latest validate <folder> --json。它会打印 { "ok": ..., "issues": [...] }；每个 issue 都有 severity、code、path（例如 sections[1].steps[0].blocks[2]）和 message。
修复所有 error，然后再次运行。重复直到 ok 为 true。当警告修复成本较低时也修复它们（例如 glossary.unreferenced：在使用该术语的地方用 [[...]] 标记）。
7. 提交并跟踪审核
- 运行
npx --yes coursmith@latest submit <folder> --json。它会上传课程并打印status: "in_review"和submissionId。CLI 会在文件夹中写入.coursmith.json；请保留它，因为后续提交会将同一课程关联起来。 - 运行
npx --yes coursmith@latest status --dir <folder> --wait --json（它会等待最多 10 分钟；如果状态仍为in_review，请再次运行）。 - 根据
status进行操作：approved：向用户提供courseUrl。提及review.issues中的任何可选建议。needs_revision：针对review.issues中的每个问题，打开path处的元素，应用suggestion（或修复message描述的问题），然后再次验证并提交。告知用户你做了哪些更改。严重程度为warning的问题是可选修改的。rejected：向用户解释review.summary。不要重新提交相同的内容。
如果 submit 报告 review_in_progress，先使用 status --wait 等待当前审核完成。
更新已发布的课程
编辑同一文件夹（保留 .coursmith.json）并再次提交。新版本会经过审核，而当前版本保持在线；保持步骤 id 稳定以便学习者能继续其进度。
故障排除
| CLI 输出 | 应对措施 |
|---|---|
not_logged_in / 退出码 3 | 返回步骤 1。 |
client_outdated | 使用 npx --yes coursmith@latest 重试，以便 npm 获取最新的 CLI。 |
submit 返回 validation_failed | 运行 validate 并修复其列出的问题。 |
rate_limited | 用户已达到每日提交上限；请明天再试。 |
assets.content_type / assets.invalid | 文件内容与其扩展名不匹配，或文件已损坏。重新导出。 |
animation.unknown_element | SVG 缺少具有该 id 的元素（id 被保留，但脚本和外部链接被移除）。 |