1. 约束先行：这个系统必须在什么条件下工作
   架构是被约束逼出来的。动手之前先明确六条硬约束，后面的每个设计决策都能回溯到其中一条：
   编号 约束 对架构的直接要求
   C1 眼镜端算力与联网受限，呈现以"当前页"为界 重活必须上云，端侧只做渲染与交互
   C2 课堂进行中，培训师不能停下来操作设备 交互入口与状态机必须外移到手机
   C3 佩戴者视线要留在学员一侧 信息必须"扫一眼读完"，排版是硬约束
   C4 培训内容涉及操作规程与安全规范 高风险内容必须显式确认，且确认状态可失效
   C5 企业知识有归属，资料不能越界 多租户隔离 + 设备级授权 + 审计留痕
   C6 终端会换（Rokid / 讯飞 / 后续机型） 显示层与智能层解耦，换终端只改页面层
   

场景本身也决定了产品形态。我们在调研里记录过一个典型片段：印度古吉拉特邦的光伏车间，培训师讲 reflection，班长笔记上拼成了 refraction，两个词都跟光学有关、发音只差一个音节，双方围绕这一个词对齐了整整七分钟。类似的误听还有 proof 听成 flame（培训师第一反应是去找灭火器）、doping 被学员理解成违禁药。
这些片段的共性是：误听发生在高频术语与安全关键词上，而现场没有任何可以即时调用的组织知识。 这就是系统的设计目标——把"企业已发布的知识"在佩戴者视野里变成一句可读、可核对、可追溯的话。
2. 总体架构：四层 + 一条状态总线
层级 职责 与上下层的连接
管理后台（Web） 知识生产 · 审核发布 · 版本修订 · 设备授权 / 审计日志 发布状态 = 课堂唯一可见边界
云端 知识通道（检索）＋ 对话通道（生成）→ 三项准入校验 → 独立翻译接口；另有幂等任务队列、提示词版本、配额与超时 课程状态（课程 · 页码 · 模块 · 角色）
手机端（控制中枢） 课程选择 · 模式切换 · 翻页 · 语音入口 · HUD 实时预览 · 课堂记录草稿 只下发「当前页」
眼镜端（哑终端） 第一视角渲染：讲述模式 / 问答模式；顶部模块+页码，底部课程位置+操作提示 —

这个结构里有两个词最关键：“当前页” 和 “课程状态”。
云端到眼镜只下发当前页，不下发整份课件。眼镜不需要理解课程，它只需要把这一页画对。
手机、眼镜、云端、后台共享同一份课程状态（课程、页码、模块、角色、记录），所以培训师在手机预览里看到的画面，和佩戴者眼前看到的画面，来自同一个状态源。
2.1 为什么手机必须是主控
这是最有争议的一个决策，一开始我们想的是"眼镜是主设备"。但 C1 和 C2 直接否掉了这个方案：

1. 状态机需要持久会话。 课程切换、资料选择、记录归档都跨越整个课堂，而眼镜端的联网与算力都不支持长期持有状态。手机天然具备持久会话能力。
2. 操作必须脱离视线。 翻页与模式切换如果放在眼镜上，佩戴者要么抬手、要么转眼，讲解动作就断了。放在手机上，视线保持在学员一侧，翻页成为一个盲操作。
3. 需要"导演监视器"。 手机持有实时 HUD 预览，培训师随时知道佩戴者当前看到什么，这在第一次试讲时救过场。
   代价当然有：多一个设备、多一条连接、多一份电量焦虑。但把复杂度收在手机上，比把复杂度摊到眼镜里要好——眼镜是"哑终端"，坏了换一台，逻辑一行不用改。
   2.2 显示层与智能层解耦
   C6 决定了页面层必须独立。我们的做法是：星火与星辰的调用全部集中在云端，页面层只负责按终端尺寸与协议渲染。
   结果就是那句我们最想在架构评审里说的话：
   更换终端只需要调整页面层，服务地址、工作区凭据、知识库、智能体配置全部照旧。
   对 B 端交付来说，这把"硬件选型"从技术风险降成了配置问题。同一套云端能力，Rokid 走双语课堂与标准培训，讯飞 AI 眼镜走多语种与离线场景，企业按语言复杂度与现场网络条件选。
4. 关键设计决策：星火双通道
   3.1 一条通道为什么不够
   最初的版本只有一个通道：把问题连同检索到的资料一起塞进提示词，让模型直接生成。跑起来很快，但立刻遇到两个说不清的问题：
   说不清这句话从哪来。 模型把"依据"和"补充说明"混在同一段正文里，审核时无法指认某句结论对应哪张卡片、哪个版本。
   说不清授权边界。 资料访问和内容生成走同一次调用，出了问题无法判断是"知识没给对"还是"模型编了"。
   3.2 双通道结构
   通道 接入方式 携带 产出
   对话通道 POST → 智能体地址（官方域名路径） 工作区凭据 · assistantId · 检索结果 · 提示词版本 目标语种正文（内容）
   知识通道 知识库接口 工作区 · 资料库范围 知识卡（条目编号 + 版本号，依据）
   

三条配套规则，缺一不可：

1. 地址与编号自校验。 地址限定为官方域名下的智能体路径，assistantId 从地址解析后与本地配置比对，一致才允许调用。这一条挡掉了很多"配错环境"的低级事故。
2. 授权分别检查、分别记录。 两条通道的授权状态独立校验，失败原因独立落日志。
3. 回答必须携带出处。 召回结果带条目编号与版本，随答案一起返回，界面渲染成可点的资料条目。
   一句话总结这个取舍：通用引擎按公开语料训练，回答以语言概率为依据；场景引擎按企业已发布资料约束，回答以卡片编号与版本为依据。 前者输出停在译名，后者能输出到条款与记录名称。
   3.3 知识分级：两级知识，两种用途
   并不是所有知识都该进课堂。我们把知识按两级管理：
   级别 来源 用途 界面表现
   已发布知识 工作区审核通过的知识卡 课堂问答的默认且唯一依据 返回资料条目 + 版本号
   智能体直答 模型侧直接生成 备课阶段的探索性提问 标注"来源状态：直答"

课堂上只认第一级。这个原则听起来很保守，但它把"现场回答出错"的概率压到了一个可管理的范围——培训师可以指着屏幕说"这是第三版卡片第 12 条"，而不是"AI 说的"。
4. 知识生产：五步流水线与可重试性
4.1 流水线
资料接入（网页上传 / 手机录入）
→ 格式抽取（星火：文本 · 表格 · 图片 OCR）
→ 结构化预整理（星火：切分 + 语境 + 双语/风险标注）
→ 知识卡批量生成（星火：五项哈希幂等）
→ 审核发布（培训部门：逐卡审定后进入课堂可见范围）
① 双入口，同一套规则。
网页端支持文件上传与批量导入，手机端支持教材录入。关键点不是"两个入口"，而是两条入口共用同一套抽取与审核规则——现场新增的素材不该走"二等通道"，否则知识库会分裂成两个质量层。
② 格式抽取，过程必须留痕。
覆盖文本、表格、图片。文本与表格按结构解析，保留标题层级与表格关系；图片经 OCR 后并入正文。抽取结果与原文件并列展示，原文件页数与抽取后的知识单元数量同时可见。
这条是踩坑换来的：不并列展示，就没法回答"这份上百页的手册，为什么只生成了这么几张卡"。
③ 结构化预整理，把风险前移。
按标题层级切分为知识单元，单元携带主题与适用场景等语境信息。这一步还输出结构提示：双语齐备程度、文本风险标注。标注结果直接决定后续生成策略。
我们的经验是：双语不齐是常态，不是异常。 早期在生成阶段校验双语，导致大量任务直接失败；改成预整理阶段标"待补"、发布时按完整性分级，流程才真正跑通。
④ 批量生成，幂等是底线。
后端按文档调用星火接口，逐段生成双语字段。任务携带五项哈希作幂等键：
job_key = sha256(json.dumps({
“doc”: doc_hash, # 文档内容
“source”: source_id, # 资料出处
“assistant”: assistant_id, # 智能体编号
“snapshot”: prompt_version,# 提示词快照
“policy”: publish_policy, # 发布策略
}, sort_keys=True))
同一个 job_key，重复提交只会命中同一个任务。任务状态可查询、可中断、可重试，重试沿用同一任务编号——批量生成是长耗时操作，没有幂等和可中断，重试就是灾难现场。
⑤ 审核发布，状态即边界。
知识卡承载四类字段，这四类字段决定了它能不能被当作资产来管理：
字段组 取值 作用
状态与风险 草稿 / 待审 / 已发布；普通 / 高风险 决定能否进入课堂检索范围
资料完整性 双语齐备 / 待补 决定发布准入
版本与修订 修订序号 + 更新时间 + 操作主体 支撑回滚与追溯
来源依据 资料出处 支撑现场指认

工作区当前有效知识卡 78 项、分 7 页呈现，清单同时显示完整性与最近修订时间。发布与修订动作全部进入版本序列，课程资料的验收动作从"翻文件"变成了"看状态"。
4.2 提示词也是被治理的资产
提示词以修订序列保存，保留历史版本与回滚入口，修订动作记录操作主体与时间。更关键的是：把输出协议写进系统提示词，约束结构化返回与语种字段，让答案的语种、正文、出处按约定结构返回。
不这么做的话，前端就要写一堆防御性解析代码；写进协议之后，解析失败本身就是一个可告警的信号。
5. 一次课堂问答的完整链路
这是整个系统最长的一条链路，也是最容易出问题的地方：

1. 学员提问。

2. 手机麦克风收音（点击开始 / 点击结束）；音频经后端转发讯飞听写，文本回填问题框。

3. 提交 → 后端校验设备授权（设备密钥 + 有效期 + 可见资料库范围）。

4. 知识通道：在选定资料库内检索已发布知识卡，命中后返回条目编号 + 版本号。

5. 对话通道：携带工作区凭据 + assistantId + 检索结果调用智能体，生成目标语种正文。

6. 三项准入校验（见 5.1）。

7. 独立翻译接口：术语按原文保留，格式按目标语种归一。

8. 双屏下发：眼镜当前页 + 手机 HUD 预览（同一状态源）。

9. 课堂记录草稿：问答原文 / 译文 / 所属模块 / 待补资料。

10. 课后归档 → 整理审核 → 成为下一版知识卡。
    注意链路末端的闭环：课堂记录以草稿形态回流后台，经整理与审核后成为新一版知识。 这是整个架构里唯一能让知识库"越用越厚"的机制，也是它区别于翻译工具的地方。
    5.1 三项准入校验：把不确定性挡在屏幕之外
    回答不是"生成完就上屏"。三项要素齐备才进入呈现：
    def accept(answer) -> Present | Reject:

    1) 助手状态：非完成态直接拒（超时、中断、审核拦截都落在这里）

    if answer.status != “completed”:
    return Reject(“assistant_not_completed”)

    2) 调用编号：必须回传，用于审计与追溯

    if not answer.call_id:
    return Reject(“missing_call_id”)

    3) 目标语种正文：归一化后为空即失败

    body = normalize(answer.body, lang=answer.lang)
    if not body:
    return Reject(“empty_body”)

    return Present(
    text=body,
    sources=answer.source_cards, # [(card_id, version)]
    lang=answer.lang,
    )
    这三条看起来平淡，但它们的价值在于：把"没生成好"和"生成了不该显示的东西"统一归入失败路径，而不是让前端去猜。 任一字段为空即按失败返回，界面走统一的失败态，而不是显示半句话。
    5.2 高风险内容的状态机
    C4 要求高风险内容必须显式确认。设计的重点不在"加一个弹窗"，而在状态失效：
    状态 ① 未确认　仅显示提示，不显示正文
    ↓ 培训师确认
    状态 ② 已确认　呈现正文 + 写入课堂记录，留下责任主体
    ↓ 切换模块 / 切换功能 / 更换语种
    状态 ③ 回到「未确认」　确认状态必须失效
    三条规则：

11. 高风险卡在确认前只显示提示，不显示正文；

12. 确认后呈现，并写入课堂记录（留责任主体）；

13. 任何上下文变更（切模块 / 切功能 / 换语种）都重新进入未确认态。
    第 3 条最容易漏，也最要命：一次确认被复用一整天，等于没有确认。

14. 呈现层：4 槽 × 4 行的容量工程
    眼镜的画面不是"把文字画上去"那么简单。C3 决定了它是一个排版问题，而排版在可穿戴设备上是硬约束。
    6.1 行槽布局
    区域 内容 约束
    顶部 当前模块名 · 页码（如 3/7） 固定两段，不换行
    外语区 slot 01–04，每槽 4 行，各配语言标签 超容量由容量规划器自动续页
    中文区 与外语逐槽对照，占用同一组槽位 与外语同槽位对齐
    底部 课程位置 · 操作提示 与翻页控件分离

四条规则：
外语与中文各设 4 个行槽，每槽 4 行，各配语言标签；
容量规划器按行槽切分正文并生成页码，超出自动续页；
三个字号共用同一套布局参数——改字号时行槽位置保持稳定；
翻页与模式切换分属两组控件：翻页只作用于当前正文，模式切换改变内容类型。
6.2 分页必须确定
这里踩过一个很难 debug 的坑：早期每个字号各算一遍布局，结果调整字号会引发整体重排，同一个课程在不同字号下页数不同、翻页位置漂移，演示时直接翻错页。
解法是把行槽作为唯一布局参数，三个字号共用，容量规划器只负责"切分 + 编页"。布局和字号解耦之后，分页结果就稳定了。
6.3 指纹复用：让分页可复现
语义配对按全文哈希复用：正文哈希与已配对资源比对，一致时直接套用既有配对与分页，长文在容量内续页。
目前已覆盖海事课程与跨境电商课程两类内容，共 506 组配对，对应 442 份有正文的外语版本。
省下的不只是 token。更重要的是——同一段话，今天和明天的分页必须一样。课堂演示对确定性的要求，比对齐成本重要得多。
6.4 语音链路的一个小设计
手机麦克风收音 → 音频经后端转发讯飞听写 → 结果回填问题框 → 提交；
收音按"点击开始 / 点击结束"控制，权限准备与收音动作分两步（避免首次点击只弹了权限框）；
教师 / 学员两种角色标注进入交流记录；
语音覆盖中文与英语，西班牙语与法语的提问走文字输入。
最后一条是刻意在交互层明示的：能力按成熟度分级，而不是假装全能。 用户的挫败感往往来自"以为能用却不能用"，而不是"明确告诉我这里要用键盘"。
7. 治理与多终端：把权限翻译成职责
7.1 四类线索
线索 机制 解决的问题
账号与工作区 工作区与星辰工作区一一对应，凭据按工作区签发，数据按工作区隔离 多项目并行时资料边界清晰
设备与授权 设备密钥 + 有效期，设备仅见获准资料库，吊销即时生效 终端接入与资料授权分离
日志与任务 审计日志（主体/对象/动作/时间）、查询日志（问答/状态/反馈/调用编号）、课堂记录（问答/译文/模块/待补） 事后复盘与责任认定
容量与导出 任务可取消可重试；工作区任务数与智能体数设上限；单次输出长度设区间；超时以失败态返回并记录原因；课堂记录与知识库支持导出 扩张节奏与培训规模同步

四类痕迹——版本痕迹、问答痕迹、审计痕迹、调用痕迹——共同支撑起"培训转化率"的计量。治理不是加功能，是让每一条结论都能被指认。
7.2 终端适配
以 Rokid CXR-L 驱动实现：手机端经授权与连接将当前页送至眼镜，画面与手机预览同步，连接状态与画面状态分别回执。
因为呈现层与生成层已经分离，新增终端的工作量被压缩到"页面层适配 + 显示协议联调"两件事。讯飞 AI 眼镜接入时，沿用同一套服务地址与工作区凭据，知识库与智能体配置照旧。
8. 数据模型与接口抽象
按报告描述归纳，核心实体大约是这样（字段为示意，非最终 schema）：
实体 关键字段 说明
Workspace id, name, credentials, defaultAssistantId 租户边界，凭据按工作区签发
KnowledgeCard id, workspaceId, title, bodyZh, bodyEn, status, riskLevel, completeness, version, sourceRef 最小知识单元，课堂检索的基本单位
Assistant assistantId, workspaceId, promptVersion, modelParams, requireSource 绑定知识库的业务助手
Course id, workspaceId, outline, cardIds, targetLang 一门课程 = 一组已发布知识卡
Session id, courseId, page, module, mode, role 课程状态，各层共享的总线
Device id, keyHash, expiresAt, allowedLibraryIds 设备级授权，吊销即时生效
Task id, jobKey(5 项哈希), status, retriable 批量生成的幂等单位
Record id, sessionId, question, translation, module, gaps 课堂记录，草稿态回流

接口层（抽象，示意）：
接口 说明
POST /v1/sessions 创建/恢复课程状态
GET /v1/sessions/{id}/page 取当前页（下发给手机与眼镜）
POST /v1/sessions/{id}/ask 提问：检索 + 生成 + 校验
POST /v1/asr 语音转写（转发讯飞听写）
POST /v1/knowledge/cards 知识卡批量生成（幂等）
POST /v1/knowledge/cards/{id}/publish 审核发布（进入课堂可见范围）
POST /v1/records/{id}/archive 课堂记录归档