user-research-skill 量化调查 JSON Schema 指南：多语言问卷与条件逻辑完全参考

user-research-skill是 Cookiy AI 为 AI 智能体（Claude、Codex、Cursor、OpenClaw）提供的全链路用户调研技能，支持 AI 访谈、合成用户、量化问卷和受访者招募。做量化调查（Survey）时，真正的"设计图纸"是一份 JSON Schema：它用一套简洁的结构定义了多语言问卷（I18nText）和条件逻辑（基于 LimeSurvey Expression Manager 的 relevance 表达式），让 AI 智能体可以替你完成问卷设计、创建、投放和报告。

Schema 的三层结构：Top-Level → Group → Question

整份问卷 JSON 自上而下分三层，理解这个骨架，剩下的只是填字段：

题目级常用可选字段：help（帮助文案）、mandatory（是否必答，默认false）、relevance（条件显示，默认"1"即始终显示）、allow_other（仅list_radio可用，追加自由文本"其他"选项）。

💡 完整字段表见 cookiy-quant-schema.md，它也是智能体执行问卷设计前必读的文件。

多语言问卷：I18nText 一个字段搞定翻译

Schema 中最优雅的设计是I18nText：所有标记为 I18nText 的字段（标题、题干、选项标签……），既可以写纯字符串（即基准语言），也可以写成逐语言映射对象：

"text": "What is your age?" "text": { "en": "What is your age?", "zh-Hans": "您的年龄？" }

两种写法混用没问题——没写语言映射的字段直接用基准语言。实际配置中英文双语问卷时，只需在languages里声明语言顺序，再给关键字段附上映射即可：

{ "survey_title": { "en": "Customer Feedback", "zh-Hans": "客户反馈问卷" }, "languages": ["en", "zh-Hans"] }

这样一份 Schema 就能同时服务多个语种市场，受访者看到自己语言的题干和选项，你不需要维护两份问卷。

条件逻辑：relevance 表达式让问卷"会思考"

条件逻辑的载体是relevance字段，它接受LimeSurvey Expression Manager表达式，可以写在两个层级：

• 组级：Group.relevance—— 决定整个分组是否对当前受访者可见；
• 题级：Question.relevance—— 决定单个题目是否显示。

默认值"1"表示"永远显示"。表达式的威力在于可以直接引用其他题目的答案做判断，例如S1 == 'Y'（筛选题选"是"）、Q1 <= 6（NPS 分数低于 7）。

下面是一个"筛选 + 反馈"双组的完整示例：只有 30 天内用过产品的受访者才会进入反馈组；而"想改进什么"这道开放题，只在 NPS 打低分时才出现：

{ "survey_title": "Product Research", "groups": [ { "title": "Screening", "questions": [{ "code": "S1", "type": "yes_no", "text": "Have you used our product in the last 30 days?", "mandatory": true }] }, { "title": "Feedback", "relevance": "S1 == 'Y'", "questions": [ { "code": "Q1", "type": "numeric", "text": "How likely are you to recommend us? (0–10)", "mandatory": true }, { "code": "Q2", "type": "long_text", "text": "What would you improve?", "relevance": "Q1 <= 6" } ] } ] }

这种"筛查题 → 条件分组 → 条件追问题"的结构，能显著降低受访者的回答负担，也是专业问卷设计的标配思路。

12 种题目类型：从单选到隐藏计算字段

Question.type决定了题目的 UI 形态和必填子字段：

其中equation类型值得多看一眼：它不向受访者展示，而是按公式自动计算出一个隐藏字段——结合relevance表达式，可以实现"自动计分、按分跳转"这类较复杂的数据处理。

选项（Option）、子行（Subrow）、量表（Scale）三种子结构的字段规则相同：

• label（I18nText）必填，同样支持多语言映射；
• code对 Option 可选（自动按 A1、A2… 生成），对 Subrow 和 Scale 必填。

校验规则：提交前避免踩坑的三个约束

Schema 内置了明确校验，quant create前值得自查一遍：

1. allow_other只能配list_radio——复选框等其他题型不要加；
2. options/array_subrows/array_scale各归其位——只能出现在各自对应的题型上，且数量不少于 2；
3. code全卷唯一——编码是条件逻辑的引用锚点，重复会导致表达式歧义。

另外注意：quant update只支持修改顶层字段（如survey_title、survey_format），分组和题目一旦创建就不能再改。所以智能体工作流（见 cookiy-quant.md）强调：先和用户共创定稿，再执行quant create。

工作流速览：从设计到出报告的 4 步

Schema 不是孤立的 JSON，它嵌在 Cookiy 的量化调研工作流里：

1. 阅读 cookiy-quant-schema.md，与用户共创问卷设计并定稿；
2. 与用户确认languages支持的语言；
3. 执行scripts/cookiy.sh quant create --json '<obj>'（CLI 位于 scripts/cookiy.sh），立即创建并激活问卷；
4. 招募受访者 → 拉取报告（quant status/quant report/quant raw-response）。

对于新手，最省事的方式其实是：直接对 AI 智能体描述你的调研目标（比如"调查 200 名用户对功能的满意度，要中英文双语"），智能体会自动加载这份 Schema 参考完成设计，你只需审核问卷内容和语言映射。

小结

回到核心：I18nText让一份问卷天生支持多语言，relevance表达式让问卷具备条件分支能力，而三层结构（Top-Level → Group → Question）+ 12 种题型 + 三条校验规则构成了完整的设计空间。把 cookiy-quant-schema.md 当作字段速查表放在手边，配合 cookiy-quant.md 的 CLI 命令，你就能用 user-research-skill 快速搭出一份专业级量化问卷。