常见校验错误
读清报错位置，再修正输入或模板配置。
怎么读报错
先找三个信息：错误位置、具体问题、修正建议。位置可能是工作簿行列，也可能是模板步骤或输入连接。
根据错误原文解释问题，定位到输入行或配置位置，给出修改方案。先不要创建或运行。
输入类型、必填项与允许值
| 现象 | 原因方向 | 修改位置 | 重新检查 |
|---|---|---|---|
| 必填项缺失 | 必填输入没有内容 | 工作簿对应列 | 补齐后校验 |
| 输入类型不匹配 | 文本、文件等形式不同 | 输入值及字段定义 | 对照当前说明校验 |
| 选项不允许 | 值不在允许集合中 | 指定选项列 | 使用当前允许值 |
步骤依赖与输入输出连接
检查引用步骤是否存在、依赖顺序是否正确、输入是否连接到兼容输出。让 Agent 根据当前配置定位，不能靠改步骤显示名称解决引用错误。
模型、能力与契约
核对当前绑定方式、端口和模型选择。没有固定模型契约时，还需检查标准能力 Profile，不能直接判断所有文本模型不可用，见 模型与编写能力说明。
版本与工作簿
工作簿来自其他版本时，重新下载匹配版本。旧定义保存失败时，按当前 v2 流程建立新版本并核对语义。
模板定义报错原文与改法
下面是在正式环境运行 loomloom template-spec check 时实际返回的报错。这类报错的格式是：
request failed: status=400 body={"error":"rpc error: code = InvalidArgument desc = invalid canonical_spec_v2: proto: (line 1:903): unknown field \"operator\""}
invalid canonical_spec_v2 表示模板定义没通过服务端校验；(line 1:903) 是出错位置，指压缩成一行后的第 903 个字符附近；最后一段是具体问题。
| 报错原文（最后一段） | 原因 | 怎么改 |
|---|---|---|
unknown field "specVersion"，位置 (line 1:2) |
把带 specVersion、canonicalSpecV2 的外层包装一起提交了 |
只提交 canonicalSpecV2 里面的内容，即以 meta、templateInputs、steps、workbook 开头的对象 |
unknown field "operator" 或 unknown field "operation" |
composeValue 写法不对，把拼接方式直接写在了绑定上 |
写成 {"source":"composeValue","compose":{"kind":"concat","separator":"","parts":[...]}}；parts 里的固定文字用 {"source":"literal","literal":"…"} |
syntax error … unexpected token "每行填写一个商品：……" |
workbook.instructions 写成了一段字符串，服务端要求是数组 |
改成数组，例如 "instructions": ["每行填写一个商品：商品名称和卖点。"] |
unknown field "<字段名>"（其他字段） |
字段名拼错，或用了当前版本不支持的字段 | 运行 loomloom template-spec docs 查看当前版本支持的字段，按原文里的字段名逐个核对 |
根据这条报错原文，找到模板定义里出错的字段，按当前 loomloom template-spec docs 的写法改好，再运行 loomloom template-spec check 确认通过。先不要创建或运行。
修正后检查，仍失败时反馈
重新校验，再通过 试运行与调试私有模板 检查真实输出。无法解决时保留版本、工作簿、错误原文和复现步骤，分享前移除凭证与敏感输入。