CSTAR 研究平台整体改造蓝图

文档性质：设计蓝图（本次仅产出文档，未改动任何代码） 版本：v1.0 · 2026-11-11 状态：待评审 研究基线：《研究计划.md》2026-11-02 定稿（单中心平行两臂随机准实验） 适用范围：urdoc 平台从「AI 内容生成工具」升级为「可承载多项教改研究的平台」的总体设计依据

0. 阅读指引

本蓝图采用「一份主蓝图 + 两份专题附录」的单一事实源结构。主文档承载结论、决策与总体设计；附录承载可逐项核对的明细。章节之间以交叉引用代替复制，避免多份文档口径漂移。

引用规则：正文给出结论与决策，附录 A 给出「数据怎么存、怎么流转」，附录 B 给出「差什么、何时做、如何验收」。三者冲突时以主蓝图结论为准，并应回写修订附录。

1. 目的、范围与边界

1.1 本蓝图要回答的问题

1. 三个 project 页面各自承担什么角色——整体叙事医学、教师教学研究、学生学习与答题如何分工而不重复建设？
2. Case / Story / Test / Act / Rate 五环节与多模态的图像、视频、声音，分别应做哪些改造才能适配定稿研究计划？
3. 需要怎样的平台化底座，才能让当前课题（省教改课题）与将来更多研究共用同一套能力、同一份数据底座？
4. 现有代码哪些可复用、哪些必须改造、哪些在方法学约束下明确不做？

1.2 本次交付边界

• 本次只新增三份 Markdown 文档，不改任何 .vue / .ts / .json 业务代码，不改配置、依赖、docNav 导航，不执行提交。
• 三份文档置于既有站内文档体系 app/assets/docs/research/ 下，与 app/utils/docs.ts 的 globalThis._importMeta_.glob('~/assets/docs/**/*.md') 加载规则天然兼容；是否纳入站内导航属于后续实施事项，注册方式见附录 B。
• 文档描述的是目标状态与未来实施建议，不是已实现功能。

1.3 表述约定

• 全文统一术语：分配臂 A/B、练习库 / 入科 X / 出科 Y 三库、W1 诊断决策 / W2 心理社会识别 / W3 沟通策略适配、vOSCE、JSE-HPS、盲态双评、反思叙事档案、scaffolding（脚手架）、human-in-the-loop（人工在环审核）。完整术语表见第 10 章。
• 所有路径均相对仓库根 d:/Projects/GitHub/urdoc/；Markdown 内的 Mermaid 图仅用于说明设计关系，不代表已部署的数据流。

1.4 与课题里程碑的关系

本蓝图服务于《研究计划.md》§13 的三个关键节点：2027.06（M2） 手册与量规冻结、2027.12（M3） 平台 v2 上线 + 师资培训 + pilot（n≈10）、2028 年正式采集并按月导出数据 / 2028.08 数据锁定。阶段划分与可勾选验收项见附录 B。

2. 依据与唯一基线

2.1 五份参考材料及其用法

2.2 冲突登记与取舍

材料之间存在版本与场景差异。下表逐项登记，凡与定稿研究计划冲突者一律以后者为准。

保留而非废弃：评分手册的 A/B 病例样例、格式等价红线、rubric criterion 分值、三类评分通道、置信度校准与一致性门控，都是可直接转化为平台题库与量规配置的素材；只是其「分组—统计」框架不采用。

2.3 定稿研究事实摘要

后续各章的设计均以以下事实为约束，不再重复论证。

2.4 本蓝图的派生原则

由上述事实派生出五条不可让渡的设计约束，展开见第 8 章：

1. 无真人患者：凡需真实患者、真实 SP、真实经管病例的能力，本期不实现。
2. 格式等价：A/B 题型组合与 rubric 必须一致，唯一系统差异是 B 多 Story 叙事层与线上闭环。
3. 干预与测评分离：B 臂必须真实经历完整闭环；出科 Y 必须是未在任何训练 / 基线中出现的新题。
4. 测评独立：vOSCE 患者人格独立于训练引擎，评分留人在环，AI 不单独作为确证证据。
5. 答题即数据：过程性事件是主要证据来源，数据必须落库、可审计、可按月导出。

3. 现状诊断

3.1 一句话结论

urdoc 目前是单机、单人、浏览器本地的 AI 内容生成工具：八个内容节点由 AI 生成或简单选择题判分，数据主要驻留 localStorage；已具备登录接口直连 Turso，但尚未形成任何研究域能力。

3.2 现状能力盘点

3.3 三个关键结构性判断

1. record.order 是内容流程编排，不是实验流程。它表达「哪个节点内容变化后需要重新生成」，没有受试者、分配臂、测评窗口、题库标签或会话状态；研究流程必须由可配置的 Study / Protocol 驱动（附录 A）。
2. 三个 project 页面是入口与视图，不是能力层。Case / Story / Test / Act / Rate 与多模态应作为被协议调用的能力，避免在三个页面重复实现同一功能（第 5 章）。
3. 数据尚未进入研究数据底座。绝大多数状态只在浏览器本地；唯一的服务端连接是登录。研究计划 §5.3 要求的答题日志库、评分库、量表库、审计日志均不存在（附录 A）。

3.4 已核验的「不存在」清单

3.5 与既有「文档规划」的关系（防误读）

以下均为文档中的规划文字，不是已实现能力，引用时必须标注：

• app/assets/docs/development/database-plan.md:6 写「当前完全基于 localStorage」、:14 写「当前使用 Turso」，两处表述并存；:417-437 规划统一 execute() 驱动接口与 server/db/drivers/edgeone.ts，:509、:511 把数据导出与权限细化列为后续扩展。本蓝图复用其驱动抽象与渐进迁移思路，但不把规划当作现状。
• app/assets/docs/development/data-architecture.md:3,10,18,28 规划 Record → flat nodes + parentId 的树形节点模型与 8 种 ContentType；它与现行 app/utils/recordContent.ts:12 的 8 步线性 order 并不相同。两者是不同层次的设计，不可混称「已实现」。
• app/assets/docs/project.md:113-135 的多模态方向、学习分析看板、协作讨论 / 同侪互评属于发展路线愿景，可作为本蓝图的需求印证，但同样不是现状。

3.6 差距矩阵

逐项差距（已有 / 需新增 / 需改造 / 明确不做）、代码位置与对应研究计划条款，见附录 B 第 2 章；核验证据清单见附录 B 第 3 章。

4. 总体定位

4.1 目标定位

把平台从「教师或学生单人使用、一次生成一份内容、数据留在本机」的工具，升级为「由研究协议驱动、按角色分入口、五环节与多模态为可复用能力、全过程数据落库且可审计」的研究平台。当前课题是首个内置协议，后续研究通过配置接入，而不是重新开发一套页面。

4.2 三层结构

4.3 目标架构（设计关系，非已部署数据流）

flowchart TB
  subgraph ENTRY["研究入口（三个 project 页面）"]
    NM["叙事医学：理论框架与研究总览"]
    PR["教法研究：教师端设计·审核·复盘"]
    CS["临床实战：学生端学习与答题"]
  end
  subgraph LOOP["CSTAR 教学闭环（能力层）"]
    C["Case 结构化病例"]
    S["Story 叙事摩擦"]
    T["Test 形成性答题（主要数据来源）"]
    A["Act 1 至 2 轮对话子题"]
    R["Rate 双维报告·教师脚手架·同伴协商·反思档案"]
  end
  subgraph MM["多模态标准化刺激"]
    IMG["图像：患者形象与影像资料"]
    VID["视频：vOSCE 触发器与回应录制"]
    AUD["声音：AI 患者语音与转录存档"]
  end
  subgraph CORE["研究平台底座"]
    PROTO["Study 协议·随机化·三套隔离题库"]
    SCALE["量表·冻结量规·盲态双评·一致性门控"]
    LOG["过程事件·审计日志·按月导出"]
  end
  subgraph DATA["数据层（统一访问抽象）"]
    ABS["驱动工厂与 Repository"]
    TURSO["当前：Turso libSQL"]
    EODB["演进：EdgeOne Makers 数据库"]
    BLOB["演进：Blob 存素材与转录"]
    KV["演进：KV 存会话与配置"]
  end
  NM --> PROTO
  PR --> PROTO
  CS --> PROTO
  PROTO --> LOOP
  LOOP --> MM
  MM --> SCALE
  LOOP --> SCALE
  SCALE --> LOG
  LOG --> ABS
  ABS --> TURSO
  ABS -.-> EODB
  ABS -.-> BLOB
  ABS -.-> KV

关系说明：三页面按角色调用同一协议；Case + Story 为内层、Test 与 Act 为中层、Rate 为外层社会建构闭环；多模态作为标准化刺激同时服务训练与 vOSCE，其中测评人格与训练引擎解耦、评分由盲态教师完成；所有过程数据经事件日志进入统一数据层，学生轨与教师轨并列采集。

4.4 设计原则

4.5 两条并列采集轨

4.6 数据落库立场与待决事项索引

• 立场：研究数据全部落库。当前以 Turso / libSQL 为实现，沿用 database-plan.md 的统一 execute() 驱动接口与驱动工厂思路；结构化数据入数据库，多模态素材 / 转录 / 录像入 Blob，会话 / 缓存 / 配置入 KV，为 EdgeOne Makers 原生存储预留切换路径（附录 A 第 8 章）。
• 待决：《研究计划.md》§5.2、§7.8 要求院内本地化部署与敏感数据合规，而 Turso / EdgeOne 属云端形态；两者取舍、正式采集期的部署形态与数据驻留边界，列为待决事项 D1（第 9 章、附录 A 第 9 章）。本蓝图不擅自替课题方决定。

5. 三个研究入口的信息架构

5.1 分工原则

三个页面是按角色划分的入口与视图，不是三套独立功能：它们通过同一个 Study 协议调用同一组能力（第 6、7 章）。分工依据《研究计划.md》§5.3 的用户层——教师端（参数设定 / 内容审核 / 线下复盘）与学生端（读病历 / 答题 / 对话 / 查看报告），另加一个面向全体角色的理论与研究总览入口。

导航现状见 app/components/App/Sidebar.vue:48-72（projects 组）、:73-109（CSTAR 组）、:110-134（多模态组）；三个页面 UDashboardPanel 的 id 重复问题列入附录 B 的 P-05。响应式与触摸友好按 AGENTS.md 要求（移动端纵向堆叠、桌面端横向排列、输入控件 size="lg" 或 size="xl"）。

5.2 叙事医学：整体理论框架与研究总览

现有页面是「疾病输入 → AI 生成叙事单页 → 模板 / 设定 → 截屏」的生成器（app/pages/project/narrative-medicine.vue:20,36-69,88），改造时保留它作为「叙事素材创作与反思写作」子能力，不推倒重来。

设计边界：本页不生成实验数据、不呈现个体作答明细；研究进度与汇总数据只显示脱敏后的聚合视图。

5.3 教法研究：教师的教学研究工作台

该页当前为 30 行空壳（app/pages/project/pedagogical-research.vue:3,6-17），需从零建设，对应论文 C 与《研究计划.md》§11「教师角色转型」。

两条重要的视图分离：

1. 教师轨与学员轨并列：教师数据不依赖「入科 → 出科」流程是否完成，独立采集、独立导出（§7.7、§11）。
2. 盲态评分视图独立：主观题 / 对话子题 / vOSCE 的评分由非授课教师在系统内网络双评，界面必须隐藏臂别、学员身份、题库标签与 pre/post 时点；评分者视图不得复用教师工作台的学情信息（§9、分析 §8.4）。

5.4 临床实战：学生学习与答题闭环

该页当前同为 30 行空壳（app/pages/project/clinical-simulation.vue:3,6-17），需建设为学生端唯一入口，按测评窗口而非按功能模块组织。

flowchart LR
  PRE["入科 PRE（两组均测）"] --> CONSENT["知情同意与脱敏 ID"]
  CONSENT --> X["入科基线 X"]
  CONSENT --> JSE1["JSE-HPS 前测"]
  CONSENT --> V1["vOSCE 入科站"]
  X --> ROT["轮转期"]
  JSE1 --> ROT
  V1 --> ROT
  ROT --> ARM{"分配臂"}
  ARM -->|"A 臂"| NOINT["常规轮转·不干预"]
  ARM -->|"B 臂"| LOOPS["10 至 20 套 CSTAR 完整闭环"]
  NOINT --> POST["出科 POST（两组同测）"]
  LOOPS --> POST
  POST --> Y["出科全新 Y"]
  POST --> JSE2["JSE-HPS 后测"]
  POST --> V2["vOSCE 出科站·平行等价剧本"]

盲态与防污染约束：学生端不显示分配臂、题库标签、标准答案、AI 辅助评分与其他学员作答；B 臂练习库不进入任何测评窗口；讨论区按批次隔离（§7.3、R3、R10）。

5.5 入口与能力层的调用关系

flowchart TB
  NM["叙事医学：理论与研究总览"] --> PROTO["Study 协议"]
  PR["教法研究：教师工作台"] --> PROTO
  CS["临床实战：学生端"] --> PROTO
  PROTO --> CAP["能力层：Case / Story / Test / Act / Rate + 图像 / 视频 / 声音"]
  PROTO --> SCALE["量表与量规：JSE-HPS / rubric / vOSCE"]
  CAP --> EVENT["研究事件日志"]
  SCALE --> EVENT
  EVENT --> DB["统一数据访问抽象（当前 Turso）"]

6. CSTAR 五模块改造规格

6.0 通用改造项

五个模块在现有实现上是彼此独立的生成页面，改造后须共同满足以下底座要求（均为未来实施建议）：

AI 能力现状（已核验）：服务端 server/api/chat/providers/aisdk.ts:1-7,32-49 使用 streamText（流式）、generateText（非流式）、convertToModelMessages、toUIMessageStream、createUIMessageStreamResponse，provider 由 createOpenAICompatible 构造；前端 app/composables/useChatApi.ts:1-28 使用 @ai-sdk/vue 的 Chat 类 + DefaultChatTransport + UIMessage，统一走 /api/chat（server/api/chat/index.ts:8-24）。结构化输出可基于 generateText 的 output: Output.object(...) 配合 Zod（见 node_modules/ai/docs/03-ai-sdk-core/10-generating-structured-data.mdx:14-45）；转录能力由 AI SDK Core 的 transcribe 提供（同目录 36-transcription.mdx:8-31），实际可用性取决于所选 provider 是否提供转录模型。注意：AGENTS.md 记载的 server/api/aisdk/text/index.ts 在当前仓库不存在，实际路径为 server/api/chat/，维护时以此为准。

6.1 Case（内层 · 结构化病例）

6.2 Story（内层 · 叙事摩擦）

6.3 Test（中层 · 核心 · 主要数据来源）

这是改造幅度最大的模块。核心修正是：Test 不是前测，而是 Case+Story 之后循环内的形成性评估与主要数据来源（§2.3、§10.1、§18）。

答题即数据：逐题事件是主要结局、置信度校准、学习投入与机制分析的共同来源，不得以截屏、本地缓存或事后补录替代（§6.1 步骤 4、§7.7）。

6.4 Act（中层 · 对话子题）

6.5 Rate（外层 · 社会建构闭环）

现有 Rate 仅生成 / 展示 AI Markdown 报告（app/components/Rate/index.vue:24,71），必须拆成四个可采集动作：

闭环完成后回到下一教学单元；B 臂需累计 10 至 20 套完整闭环（§7.2）。Rate 不可纯算法评分是本课题最重要的模型修正之一（§2.3、§18）。

6.6 五模块数据流

flowchart LR
  P["教师设参"] --> C["Case 结构化病历"]
  C --> S["Story 叙事摩擦"]
  S --> T["Test 形成性答题"]
  T --> A["Act 1 至 2 轮对话子题"]
  A --> R["Rate 四动作"]
  R --> N["下一教学单元"]
  T -.->|"逐题事件"| EV["研究事件日志"]
  A -.->|"对话与转录"| EV
  R -.->|"报告·复盘·讨论·反思"| EV
  EV --> DB["统一数据层"]

6.7 模块与研究数据字典的映射

7. 多模态改造规格

7.1 总体定位

三个多模态页面目前都是「生成并展示」：图像出头像 / 插图、声音做 TTS 朗读、视频生成短片（app/pages/multimodal/*）。改造方向是把它们纳入标准化刺激素材体系，同时服务两件事：训练期的叙事情境呈现，以及行为层测量 vOSCE 的可复现刺激。约束来自《研究计划.md》§8.1(3) 与分析文档 §8.9——刺激标准化可复现、评分留人在环、全程转录 / 录像存档、如实命名 vOSCE。

7.2 图像

• 复用现有出图链路（app/pages/multimodal/image.vue:56-58、app/stores/image.ts:22-27），新增「素材实体」：与 Case / Story 绑定、记录生成参数与内容哈希、标注训练或测评用途。
• 教师审核后冻结；冻结版本不得在采集期被重新生成覆盖，避免刺激不一致。
• 大体积图片只把元数据、URL 与哈希写入数据库，实际文件归 Blob（附录 A 第 8 章）；现行 store 只存远程 URL 的做法可作为元数据形态参考，但不能作为研究存档依据。

7.3 视频

• 训练短片与测评触发器必须分离：app/pages/multimodal/video.vue:43,106-120,143-171 的生成能力用于训练期叙事素材；vOSCE 触发器是独立、冻结、可复现的标准化刺激。
• 起步方案按分析文档 §8.9 方案②：一次性录制标准化患者片段（演员或 AI 形象），一录多用、全员复用、无持续 SP 成本；学员观看后录制自身告知 / 知情同意回应（视频或音频），由盲态教师评分。
• 入科 / 出科使用平行等价剧本并交叉平衡，防止练习效应；评分对象始终是 rubric 行为，不是剧情记忆（分析 §8.5）。
• 须实现录制与归档能力：当前全库无 getUserMedia / MediaRecorder / 录像存档（附录 B 第 3 章核验 6）。

7.4 声音

• TTS 已有：app/composables/useAudioApi.ts:25-65、server/api/audio/index.ts:9-19、app/components/Button/Audio.vue；可用于 AI 患者的语气与情绪呈现，但须与 vOSCE 人格配置解耦。
• 转录为新增能力：AI SDK Core 提供 transcribe（node_modules/ai/docs/03-ai-sdk-core/36-transcription.mdx:8-31），实际可用性取决于所选 provider 是否提供转录模型；若不可用则需评估外部 ASR 服务，两种路径都须记录模型 / 版本 / 时间戳。当前项目无任何 ASR 代码（含注释），注释掉的是旧 Gitee TTS provider。
• 转录文本、分段时间戳、原始音频引用与哈希一并归档，供盲态教师评转录稿；AI 不自动评分。
• 虚拟社区声音（家属 / 同事 / 社区舆论 / 社区医生多角色 persona）属论文 B 方向，本期「明确不做」，登记为后续可配置能力（第 9 章、附录 B 的 M-08）。

7.5 素材生命周期

flowchart LR
  G["生成（模型·参数·提示词）"] --> M["元数据与内容哈希"]
  M --> REV["教师审核（临床准确性·人文真实性·去标识化）"]
  REV --> F["冻结版本"]
  F --> U["按协议投放（训练或测评）"]
  U --> ARCH["归档：素材引用·转录·录像·时间戳"]
  ARCH --> AUDIT["审计日志与按月导出"]

7.6 与研究数据的关系

8. 合规与质量红线

本章是实施与验收必须满足的设计约束，不是当前已实现状态；对应差距项见附录 B 第 2.5 节 Q-01 至 Q-10，验收清单见附录 B 第 5 章。

8.1 方法学红线

8.2 数据与伦理红线

8.3 门控

8.4 明确不做

「真实 SP 版 mini-CEX、患者版 MSF、CBD、DOPS 整体纳入、SCT 确证化、虚拟社区声音确证测量、AI 自动评分替代人工」等本期排除项，逐条登记在附录 B 第 2.6 节，并注明其后续研究方向归属。

9. 未来研究扩展机制与待决事项

9.1 扩展原则：配置而非改代码

《研究计划.md》§21 要求「一课题多文、共用数据底座」。平台应把研究差异收敛到 study / protocol_version 配置（附录 A 第 2、3 章），能力层保持不变。

9.2 后续研究方向接入

9.3 新研究接入流程

flowchart LR
  A["注册 study"] --> B["定义 protocol 与臂别·窗口"]
  B --> C["冻结量规·权重·统计计划"]
  C --> D["配置题库·量表·素材与 persona"]
  D --> E["伦理与知情同意配置"]
  E --> F["随机分配与数据采集"]
  F --> G["盲态评分与一致性门控"]
  G --> H["按月导出·锁库·归档"]
  H --> I["新增研究仅新增配置与版本"]

9.4 待决事项

四项均为待课题方 / 伦理 / 平台方决策，本蓝图不预设结论；决策结果应回写主蓝图与附录 A、B 对应章节。

9.5 与结题成果的关系

《研究计划.md》§14 要求三类结题硬条件：≥1 篇中文知网收录教改论文、1 项被学校采纳的教学改革方案（2027 年内取得采纳证明以满足应用满 1 年）、1 套优质数字教学资源。本蓝图对应的平台功能包（三个入口 + 五模块闭环 + 多模态刺激 + 数据底座）、病例题库与操作指南，构成「数字教学资源」主体；教师工作台产出《分步实施手册》与培训材料；数据底座产出可复现的实证数据与分析报告。

10. 术语表

文档结构索引

交付边界复核：本次仅新增上述三份 Markdown 文档，未修改 app/utils/docs.ts 的 docNav，未改动任何业务代码、配置或依赖，未执行提交；文中所有「建议 / 需 / 应 / 设计目标」均为未来实施建议。