用途
claat-creator 用于把项目素材转换成 Google Codelabs 格式的操作手册（manual.md），并进一步生成 HTML。素材包括项目源代码、README、配置文件、既有文档、步骤备忘、日志、URL 等。整个流程从素材读取开始，经写作、日语检查、lint，到 HTML 生成与报告结束。
核心目标是让读者「中途不停手地走到最后」。读者被设定为「对该领域完全不了解的中学生」，因此写作以可复现、可核对为优先。
主要能力
素材驱动的写作
只写入可从素材确认的命令、路径、版本、输出。无法确认的内容不写；需要写入时先询问用户，或标记为「（未确认）」保留在草稿中。
读者与到达点定义
动笔前先明确三件事：读者是谁（已知什么、不知什么）、到达点（读完能做什么）、前提（需要提前准备的东西）。前提与步骤分开，不混为一谈。
步骤拆分
以「一个步骤 = 一个可确认的状态变化」为唯一标准。第一步骤固定为「目标与前提确认」，最后一步为「成果确认与联系方式」。Duration 用于检查拆分是否合理，超过 15 分钟的步骤通常包含了两个以上的状态变化。
写作规范
- 一句一个动作
- 先写「在哪里」
- 专业术语首次出现时就地解释
- 每个操作后写「成功时的状态」
- 不用「这个」「这里」，直接写名称
- 全程使用敬体（です・ます）
代码与图片的取舍
- 需要复现的内容放进代码块，说明写在正文
- 执行命令用 ```console，一行一条，不加 $ 或 > 提示符
- 输出示例用 ```text
- 不贴长文件全文，只展示要修改的行及其前后 2〜3 行
- 图片只用于「指出点哪个」和「核对是否正确」，保存于 manual.md 同级 images/，用相对路径引用
- 命令、路径、设置值、错误信息不插图
claat 特殊语法
- 注意框：
> aside positive/> aside negative，或直接写<aside class="negative"> - 下载按钮：
<button>[Download SDK](https://example.com)</button> - 清单标题：
### What you'll learn、### What we've covered、### Frequently asked questions下的列表会渲染为清单（仅限英文字符串） - 表格、链接、列表按普通 Markdown 处理
日语检查
先做日语检查，再做 lint。做法：把 Duration: 行替换为空行生成副本，调用 natural-japanese skill 的 quick 模式，文档类型指定「社内指南・手册」、类型指定 tech。Windows 下如出现乱码，加 PYTHONIOENCODING=utf-8。检查结果作为「疑点提示」，逐条判断是修改还是保留并记录理由。
lint 校验
lint 本体包含在技能内（cmd/claat-tools/main.go），只用标准库，无需 go.mod，工作目录不限。命令：
go run <skill>/cmd/claat-tools/main.go lint path/to/manual.md
退出码含义：0 成功；1 输入 lint 错误；2 运行环境问题；其它为 claat 自身失败。需注意经 go run 时 shell 收到的 $? 失败时恒为 1，应读标准错误末行判断。诊断格式为 path:line:column: error CODE message。
HTML 生成
HTML 化委派给 PATH 上的 claat。如未安装，使用已验证版本：
go install github.com/googlecodelabs/tools/claat@v0.0.0-20240220115335-873fe39d02dc
生成命令：
go run <skill>/cmd/claat-tools/main.go build -output output path/to/manual.md
输出结构为 output/<id>/index.html 和 codelab.json。可用 -output / -o 更改输出目录。
报告
完成需满足三点：lint 退出码为 0；output/<id>/index.html 实际存在（如被要求生成 HTML）；剩余待办已列表告知用户。需告知的内容包括：生成文件路径、lint 修改处及原因、未拍摄图片（哪个画面、放到哪个路径）、素材中无法确认而标注为未确认的记述、只能由用户决定的元数据（summary 文案、feedback link、analytics account）。
使用方式
入口选择
- 只有素材（源码、README、备忘、URL）：从 §1 开始
- 手头有 .md（含未完成）：先用 §6 的 lint 把握现状，再决定修补还是重写
- .md 存在且 lint 通过：进入 §7 生成 HTML
- 已有 HTML 但想改内容：改 .md，不动生成物
整体流程
素材 → 写作（§1-4）→ 日语检查（§5）→ lint（§6）→ HTML 生成（§7）→ 报告（§8）。如正文需大量补写，则回到 §4，再经 §5 后返回 §6。
顺序理由
- 日语检查先于 lint：改日语会移动行号，可能破坏图片相对路径与 Duration 位置
- lint 先于 build：build 在 lint 失败时即停止，先看全部诊断再统一修改可减少往返
适用场景
- 从项目仓库素材生成教学式操作手册
- 需要面向零基础读者的步骤文档
- 需要产出 Google Codelabs 格式 HTML 的场合
- 需要 lint 校验格式合规性的文档工程
限制
- 不编造未验证的命令与步骤；无法确认的内容标为「未确认」或向用户询问
- 元数据仅支持 7 个键：summary、id、categories、environments、status、feedback link、analytics account；tags、authors 等会触发 META002
- id 仅允许 [A-Za-z0-9][A-Za-z0-9_-]*
- environments 仅 Web / Kiosk，status 仅 Draft / Published / Deprecated / Hidden
- 不编辑生成物（output/<id>/index.html），修改对象始终是 .md
- 图片未齐时不停工，先完成不需要图片的部分，并附拍摄请求清单
- 同一文档的返工以 2 个来回为上限，第 3 次通常说明问题在素材、环境或步骤本身
- 未被要求时不提交或公开生成物
- 技能信息中暂未提供具体的收费、价格、平台支持范围等细节