Study Builder
Study Builder
1. 目标 & 范围
目标
让研究人员能在 15 分钟内从零创建一个可运行的 study：填写研究简介、定义 Objectives、配置 Agent 行为、选择交互工具与输出字段、绑定知识库，完成 Preview 试跑后一键发布，生成受访者访谈链接。
范围
本模块（P0）覆盖：
- 9 步 Stepper 向导（Brief → Objectives → Interview Guide → Agent Config → Tools → Output Schema → Knowledge Base → Preview → Publish）
- 每步独立草稿保存
- Objectives 编辑（title / priority / success_criteria / related_output_fields）
- Output Schema Builder（字段类型 / required / evidence_required / confidence_threshold / review_policy）
- Enabled interaction tools 选择与限制配置
- Agent Config（model roles / policy / tool limits）
- Knowledge Base 选择与 retrieval 参数
- Preview 模式（试跑访谈）
- 发布与链接生成
不在本模块范围：
- 受访者访谈运行时（见 04_interview_runtime）
- 交互组件渲染逻辑（见 05_interaction_components）
- 结构化抽取与 evidence（见 06_extraction_evidence）
- 结果查看与修正（见 07_results_review）
- KB 上传与索引（见模块 08，P1）
- 模型 Provider 全局配置（见模块 09，P1）
2. 用户故事
作为研究人员，
- 我希望通过步骤清晰的向导配置 study，以便不遗漏关键配置项并随时保存进度。
- 我希望能在一个界面内定义多个研究 Objectives 并设置优先级，以便 Agent 在访谈中按重要性覆盖目标。
- 我希望能用可视化方式构建 Output Schema 字段并设置证据要求，以便下游抽取结果可信且可审计。
- 我希望能选择并限制 Agent 可使用的交互工具，以便控制访谈体验的复杂度。
- 我希望在正式发布前通过 Preview 模式试跑访谈，以便发现配置问题再修改。
- 我希望保存草稿后随时返回继续配置，以便分多次完成复杂 study 的配置。
- 我希望发布后能获得受访者访谈链接，以便分发给受访者。
3. 功能需求
3.1 Stepper 向导骨架
FR-03-1 P0 — Stepper 骨架与步骤导航
Study Builder 以 9 步 Stepper 向导呈现，步骤顺序为：
- Brief（研究简介）
- Objectives（研究目标）
- Interview Guide（访谈提纲）
- Agent Config（Agent 行为配置）
- Tools（交互工具选择）
- Output Schema（输出字段定义）
- Knowledge Base（知识库绑定）
- Preview（预览试跑）
- Publish（发布）
验收要点：
- 步骤列表常驻左侧或顶部，显示当前步骤高亮及已完成步骤标记
- 用户可直接点击已完成步骤跳转（非线性导航）
- 每步切换前自动触发当前步骤草稿保存
- 前进 / 后退按钮在每步底部可见
- 组件入口：
StudyBuilderShell.tsx，路由/studies/[studyId]/builder
FR-03-2 P0 — 草稿自动保存
每步内容变更后，支持手动保存草稿；切换步骤时自动保存当前步骤。Study 在发布前保持 draft 状态。
验收要点：
- 修改任意字段 30 秒内或切换步骤时，自动触发
PATCH /studies/{studyId}保存草稿 - 保存成功后界面显示「已保存」时间戳，失败时显示明确错误提示
- 草稿保存不触发版本创建；仅 Publish 操作创建 StudyVersion 快照
- 浏览器刷新后恢复草稿内容
3.2 Step 1 — Brief（研究简介）
FR-03-3 P0 — 研究简介编辑
组件：ResearchBriefEditor.tsx
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| title | string | 是 | study 名称，最长 100 字符 |
| description | string | 否 | 研究背景与目的，最长 2000 字符 |
| target_participant | string | 否 | 目标受访者画像描述 |
| research_constraints | string | 否 | 访谈限制说明（敏感话题、时长、禁止问题等） |
| estimated_duration_min | integer | 否 | 预估访谈时长（分钟） |
验收要点：
- title 为空时无法进入下一步，显示 inline 错误提示
- description 超出字符上限时实时显示剩余字数并阻止提交
- 所有字段变更后自动标记为「未保存」
3.3 Step 2 — Objectives（研究目标）
FR-03-4 P0 — Objectives 列表管理
组件：ObjectivesEditor.tsx
每条 Objective 包含：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| title | string | 是 | 目标标题 |
| description | string | 否 | 目标详细说明 |
| priority | enum | 是 | must / should / optional |
| success_criteria | string[] | 否 | 可验证的覆盖标准，至少建议填 1 条 |
| suggested_questions | string[] | 否 | 建议问题（供 Agent 参考） |
| related_output_fields | string[] | 否 | 关联的 Output Schema 字段 ID |
| max_probe_count | integer | 否 | 最大追问次数，默认 3 |
| interaction_tools | string[] | 否 | 本 Objective 建议启用的工具类型 |
对应架构定义：StudyObjective（见 agent_harness）
验收要点：
- 支持新增 / 编辑 / 删除 / 拖拽排序 Objectives
- 至少需要 1 条
must优先级 Objective 才能进入下一步 priority字段以可视化标签（颜色区分 must / should / optional）展示success_criteria支持多条自由文本，可逐条添加删除- 删除 Objective 时弹出二次确认（若已有关联 output fields）
3.4 Step 3 — Interview Guide（访谈提纲）
FR-03-5 P0 — 访谈提纲编辑
组件：InterviewGuideEditor.tsx
验收要点：
- 支持自由文本编辑器（Markdown 格式），用于研究人员编写访谈框架、提示语、特殊指令
- 支持从 Objectives 一键生成提纲草稿（调用 LLM，非必须完成即可保存）
- 提纲内容会注入 Harness Decision Prompt（见 agent_harness）
- 字段为可选；空提纲时 Agent 完全依赖 Objectives 驱动访谈
3.5 Step 4 — Agent Config（Agent 行为配置）
FR-03-6 P0 — Model Roles 配置
组件：AgentConfigEditor.tsx
对应架构定义：StudyModelRoles（见 model_tool_kb_abstraction）
| 配置项 | 说明 | 默认值 |
|---|---|---|
| interviewer_model | 负责对话与工具调用的模型 | 平台默认 |
| extraction_model | 负责结构化抽取的模型 | 平台默认 |
| synthesis_model | 负责总结与跨 session 分析的模型 | 平台默认 |
| temperature | 访谈模型温度参数 | 0.7 |
| max_tokens | 单轮最大输出 token | 1024 |
验收要点：
- Provider 下拉选择（openai / anthropic / google / azure_openai / ollama / custom）
- 每个 model role 可独立指定 provider + model name
- 参数（temperature / max_tokens）超出合法范围时 inline 报错
- MVP 阶段允许使用平台默认配置，不强制要求逐个配置
FR-03-7 P0 — Tool Policy 配置
| 配置项 | 说明 |
|---|---|
| max_interactions_per_session | 每次 session 最多渲染交互组件次数 |
| max_modal_interactions | modal 类型交互次数上限 |
| approval_required | 需要人工审批才能执行的工具列表（P1） |
对应架构定义：StudyToolPolicy（见 model_tool_kb_abstraction）
验收要点：
max_interactions_per_session默认值 10，范围 1–50- 配置值持久化到 StudyConfig，Harness 运行时读取并强制执行
3.6 Step 5 — Tools（交互工具选择）
FR-03-8 P0 — Enabled Interaction Tools 选择
组件：ToolSelector.tsx
研究人员在此步骤勾选 Agent 在访谈中允许使用的交互组件类型。可选工具类型（InteractionType）列表见 05_interaction_components：
| 工具类型 | 说明 | MVP 支持 |
|---|---|---|
| single_choice | 单选 | 是 |
| multiple_choice | 多选 | 是 |
| likert | Likert 量表 | 是 |
| ranking | 排序 | 是 |
| nps | NPS | 否（P1） |
| rating | 评分 | 否（P1） |
| matrix | 矩阵题 | 否（P1） |
| text_input | 文本输入框 | 否（P1） |
| modal_form | 模态表单 | 否（P1） |
| concept_card | 概念卡片 | 否（P1） |
| comparison | 对比卡片 | 否（P1） |
| consent | 同意协议 | 否（P1） |
| file_upload | 文件上传 | 否（P1） |
| image_annotation | 图片标注 | 否（P1） |
验收要点：
- 勾选列表以
enabled_tools数组写入StudyToolPolicy - P1 工具在 UI 显示但以禁用态标注「即将推出」
- 至少勾选 1 个工具；全部取消勾选时给出警告（访谈将无结构化交互）
- 勾选的工具列表在 Preview 步骤中生效
3.7 Step 6 — Output Schema（输出字段定义）
FR-03-9 P0 — Output Schema Builder
组件：OutputSchemaBuilder.tsx
每条字段（OutputSchemaField）可配置：
| 配置项 | 类型 | 必填 | 说明 |
|---|---|---|---|
| name | string | 是 | 字段标识符（snake_case） |
| label | string | 是 | 界面显示名称 |
| description | string | 是 | 字段含义说明，供 Agent 抽取时参考 |
| type | enum | 是 | string / number / integer / boolean / enum / array / object |
| enum_options | array | 条件必填 | type=enum 时必填，每项含 id / label / description |
| required | boolean | 是 | session 完成时是否必须有值 |
| evidence_required | boolean | 是 | 是否要求至少一条 evidence |
| min_evidence_count | integer | 否 | 最少 evidence 条数，默认 1 |
| confidence_threshold | number | 否 | 低于此置信度触发 needs_review，范围 0–1，默认 0.75 |
| review_policy | enum | 否 | always / low_confidence / conflict / never |
| extraction_hint | string | 否 | 供抽取模型参考的额外说明 |
对应架构定义：OutputSchemaField（见 06_extraction_evidence）
验收要点：
- 支持新增 / 编辑 / 删除 / 拖拽排序字段
- type=enum 时界面展示 enum_options 子列表，支持逐项增删
name字段校验：只允许 snake_case，不允许重复，不允许空字符串confidence_threshold超出 0–1 范围时 inline 报错- 至少需要 1 条
required=true的字段才能保存 Schema - Schema 变更后自动递增内部 schema_version_id
3.8 Step 7 — Knowledge Base（知识库绑定）
FR-03-10 P0 — KB 选择与参数配置
组件：KnowledgeBaseSelector.tsx
对应架构定义：KBConfig（见 model_tool_kb_abstraction）
验收要点：
- 展示当前 workspace 和 project 下可用 KB 列表（scope=workspace / project / study）
- 支持多选 KB（Agent 可跨多个 KB 检索）
- 可配置
top_k（默认 5，范围 1–20）和score_threshold（默认 0.7） citation_required开关：开启后 Agent 检索必须附带 citation- MVP 阶段 KB 为空时允许跳过（无 KB 访谈仍可运行）
3.9 Step 8 — Preview（预览试跑）
FR-03-11 P0 — Preview 模式
组件：StudyPreview.tsx
研究人员以「模拟受访者」身份试跑访谈，验证 Agent 行为、工具渲染、追问逻辑。
验收要点：
- Preview 会话使用当前草稿配置运行，不创建正式 StudyVersion
- Preview 界面复用受访者 Interview UI（
InterviewShell.tsx），顶部显示「预览模式」横幅 - Preview 产生的 session 数据标记
is_preview=true，不计入正式统计 - 试跑中可中止会话，返回 Builder 继续修改
- Preview 结束后展示摘要：覆盖的 Objectives、已触发的交互工具、抽取字段的初步值与置信度
- Preview 摘要页提供「返回修改」和「继续发布」两个操作入口
3.10 Step 9 — Publish（发布）
FR-03-12 P0 — 发布前校验
验收要点：
- 发布前执行完整校验，以下任一不满足则阻止发布并展示具体错误列表：
- Brief.title 不为空
- 至少 1 条
mustpriority Objective - Output Schema 至少 1 条 required 字段
- Interviewer model 配置有效（provider 可达）
- 校验通过后创建
StudyVersion快照（含 Objectives / OutputSchema / ToolPolicy / ModelRoles / KBConfig / InterviewGuide 的版本化副本）
FR-03-13 P0 — 发布与链接生成
组件：PublishPanel.tsx
验收要点：
- 发布成功后 study 状态从
draft变更为active - 生成唯一
public_slug，访谈链接格式：/interview/{public_slug} - 链接可一键复制到剪贴板
- 支持链接有效期配置（无限期 / 截止日期）
- 发布后仍可在 Builder 修改配置，再次发布生成新 StudyVersion；老 session 绑定原 version 不受影响
4. 关键流程
4.1 完整创建流程
研究人员进入 /studies/[studyId]/builder -> Step 1 Brief: 填写标题与背景 -> Step 2 Objectives: 添加至少 1 条 must 目标 -> Step 3 Guide: 可选，填写访谈提纲 -> Step 4 Agent Config: 选择模型 roles，可使用平台默认 -> Step 5 Tools: 勾选 enabled 交互工具 -> Step 6 Output Schema: 定义至少 1 条 required 字段 -> Step 7 KB: 选择知识库（可跳过） -> Step 8 Preview: 试跑一次访谈，验证行为 -> Step 9 Publish: 校验通过 -> 创建 StudyVersion -> 生成链接4.2 草稿恢复流程
研究人员从 Projects 列表点击未发布 study -> Builder 加载最新草稿状态 -> Stepper 高亮上次编辑到的步骤 -> 研究人员继续编辑4.3 Preview 流程
进入 Step 8 -> 点击「开始试跑」 -> 以草稿配置初始化 preview session -> 进入受访者 Interview UI（顶部标注预览模式横幅） -> 完成或中止访谈 -> 返回 Preview 摘要页 -> 点击「继续发布」进入 Step 9，或「返回修改」跳转目标步骤5. 数据
Study Builder 操作的核心实体（详见 data_model）：
| 实体 | 主要字段 | 说明 |
|---|---|---|
| Study | id / title / description / status / current_version_id | 核心 study 记录 |
| StudyVersion | id / study_id / objectives / output_schema / tool_policy / model_roles / kb_config / interview_guide / created_at | 发布时的不可变快照 |
| StudyObjective | id / study_id / title / priority / success_criteria / suggested_questions / related_output_fields / max_probe_count | 研究目标 |
| OutputSchemaField | id / study_id / schema_version_id / name / label / type / required / evidence_required / confidence_threshold / review_policy | 输出字段定义 |
| KBConfig | id / scope / name / retrieval_enabled / top_k / score_threshold / citation_required | 知识库配置 |
| StudyModelRoles | study_id / interviewer_model / extraction_model / synthesis_model | 模型角色映射 |
| StudyToolPolicy | study_id / enabled_tools / max_interactions_per_session / max_modal_interactions | 工具策略 |
6. 接口
详见 api_contracts，Study Builder 涉及以下端点：
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /studies/{studyId} | 加载 study 草稿 |
| PATCH | /studies/{studyId} | 保存草稿（逐步自动保存） |
| POST | /studies/{studyId}/objectives | 新增 Objective |
| PUT | /studies/{studyId}/objectives/{objectiveId} | 更新 Objective |
| DELETE | /studies/{studyId}/objectives/{objectiveId} | 删除 Objective |
| PUT | /studies/{studyId}/output-schema | 保存 Output Schema 字段列表 |
| PUT | /studies/{studyId}/tool-policy | 保存 Tool Policy |
| PUT | /studies/{studyId}/model-roles | 保存 Model Roles |
| PUT | /studies/{studyId}/kb-config | 保存 KB 配置 |
| POST | /studies/{studyId}/preview | 创建 preview session |
| POST | /studies/{studyId}/publish | 执行发布校验 + 创建 StudyVersion + 生成 slug |
| GET | /knowledge-bases?scope=workspace,project&projectId={id} | 获取可用 KB 列表 |
AG-UI 事件（Preview 试跑）：协议见 interactive_ui_protocol，Preview session 复用 Interview Runtime 的 AG-UI SSE 事件流。
7. 验收标准
AC-03-1 研究人员从空白开始，在 15 分钟内完成「填写 Brief → 添加 1 条 must Objective → 选择 4 种交互工具 → 定义 2 个输出字段 → 发布」全流程，成功获得可访问的访谈链接。
AC-03-2 切换步骤时，当前步骤内容自动保存；刷新浏览器后重新打开 Builder，内容与保存前完全一致。
AC-03-3 Brief.title 为空时，点击「下一步」触发 inline 错误提示，无法进入 Step 2。
AC-03-4 Objectives 页面，优先级设置为 must / should / optional 的条目以不同颜色标签区分，可拖拽排序，删除含关联字段的 Objective 时弹出二次确认。
AC-03-5 Output Schema Builder 中，name 字段非 snake_case 或重复时，保存按钮灰态并展示具体错误；type=enum 时必须填写至少 1 条 enum_option。
AC-03-6 Tools 步骤中，仅 MVP 支持的 4 种工具（single_choice / multiple_choice / likert / ranking）可勾选并写入 enabled_tools；P1 工具显示但无法勾选。
AC-03-7 Preview 试跑中，Agent 仅可调用 enabled_tools 中已勾选的工具类型；调用未启用工具时 Harness 应拒绝并记录 decision log。
AC-03-8 Preview 会话的 session 记录 is_preview=true，在 Results 页面的正式 session 列表中不显示。
AC-03-9 发布前校验：Brief.title 为空、无 must Objective、Output Schema 无 required 字段，三种情况各自触发阻止发布并展示对应错误说明。
AC-03-10 发布成功后，生成的 /interview/{public_slug} 链接可由浏览器直接访问并进入受访者访谈界面。
AC-03-11 发布后修改配置并再次发布，生成新 StudyVersion；原有 session 仍绑定旧 version，不受新配置影响。
AC-03-12 confidence_threshold 输入 1.5 时，OutputSchemaBuilder 显示范围错误提示，保存被阻止。
8. 边界 & 非目标
- 不做：拖拽式可视化 Workflow Builder（见 00_overview 非目标）
- 不做：多人同时编辑同一 study（MVP 无协同编辑）
- 不做：study 模板市场与模板导入（P1）
- 不做：Preview 结果的正式统计与 insight（仅摘要展示，正式分析见 07_results_review）
- 不做：KB 文件上传（本模块只做选择已有 KB，上传见模块 08）
- 不做：全局 Provider 级别模型密钥配置（见模块 09）
- 边界：Agent Config 的模型 provider 必须已在平台层完成密钥配置，Builder 仅选择不维护密钥
9. 依赖 & 风险
依赖
| 依赖模块 | 说明 |
|---|---|
| 02_projects_studies | study 必须归属于某个 project；Builder 从 project 上下文继承 KB scope |
| 04_interview_runtime | Preview 模式复用 Interview Runtime 的 Harness 与 AG-UI 事件流 |
| 05_interaction_components | Tools 步骤枚举的交互类型与前端组件须保持同步 |
| 06_extraction_evidence | Output Schema 字段定义直接驱动抽取逻辑，字段 schema 须一致 |
| agent_harness | Objectives 结构（StudyObjective）须与 Harness 读取的配置格式完全对齐 |
| model_tool_kb_abstraction | ModelRoles / ToolPolicy / KBConfig 字段定义须与架构文档保持同步 |
风险
| 风险 | 影响 | 缓解措施 |
|---|---|---|
| Preview 试跑依赖 Harness 稳定 | Preview 步骤阻塞发布流程 | Preview 为可跳过步骤，校验仅在 Publish 步骤强制执行 |
| Output Schema 字段频繁变更 | 已有 session 的抽取结果与新 schema 不兼容 | 发布时生成 schema_version_id，session 绑定版本快照 |
| 模型 Provider 不可达 | Agent Config 步骤无法验证连通性 | 发布前校验 provider 可达；Preview 阶段提前暴露连通问题 |
| 15 分钟内完成配置 UX 目标 | 步骤过多导致流失 | 每步提供「跳过」或默认值，仅 Brief + Objectives + OutputSchema 强制填写 |