docs: add architecture and RAG refactor goal prompt

2026-10-01 01:22:52 +08:00
parent b7634c8374
commit 29c95ce5ad
2 changed files with 242 additions and 0 deletions
@@ -0,0 +1,241 @@
 # WiseGrade 架构规范化、中文检索与章节切块：Codex Goal 模式提示词
 在支持 Goal 模式的 Codex 中启用 `/goal`，将下方代码块中的正文作为目标提示词。正文授权修改仓库源码、依赖与隔离测试环境，并在完成备份、隔离演练和验收后部署到当前正式业务环境，执行必要迁移和索引重建。历史评分及会话内容须保留。目标未设定 token 或时间预算。
 提示词按 [OpenAI 官方提示词说明](https://learn.chatgpt.com/docs/prompting) 组织为目标、上下文、边界和验证要求。本文件描述后续任务，不代表任务已经完成。
 ~~~text
 你是 WiseGrade（智评）项目的开发代理。请在 /home/sky/files/Agent/WiseGrade 完成一次架构规范化和 RAG 改造：统一业务对象和各层契约，收敛运行路径中的旧格式兼容，使用 PostgreSQL 扩展 pg_jieba 实现中文分词与词项索引，将检索切块升级为章节约束下的段落切块，并贯通评分、教师复核、Agent、API、前端和导出。完成验证后实际部署到当前正式业务环境，使业务服务使用新代码、新数据库结构和新索引。
 持续推进到下述开发、隔离验证、正式部署及上线验收条件全部满足。交付实际代码、迁移、测试、评估和部署记录，不能只提交架构分析、文件搬移、设计方案或待执行的部署清单。遇到错误要定位并修复；确实依赖外部条件的验证须单独标明，不得写成通过。未经请求，不设置额外预算，不创建其他 Codex 用户聊天。
 ## 一、工作边界
 1. 允许修改本仓库源码、测试、依赖锁文件、数据库 Dockerfile、Compose、迁移和文档，允许创建与使用隔离 PostgreSQL + pgvector + pg_jieba、Redis、处理目录和导出目录。
 2. 正式部署已获授权：在隔离验收通过、业务备份已验证可恢复之后，允许对当前业务库执行所需迁移、页面/块/章节分类与来源元数据转换、学生及公共资料索引重建，允许通过业务队列提交并跟踪这些任务。不得清空数据库、Redis 或任务队列，不得重跑既有评分批次。批次 3 及其他既有批次的分数、教师复核、修改历史、快照与项目范围必须保留；会话 6 及其他既有会话的消息正文和历史工具记录必须保留。必要的历史引文来源元数据转换可执行，但原始引文、实际来源和链接可核对性不得丢失。
 3. 允许构建并更新正式数据库、API、worker、Web 和本次确有必要更新的相关服务，将 pg_jieba 及领域词典纳入可复现的数据库镜像；保留 PostgreSQL 16 主版本、现有端口、挂载、模型配置、密钥及持久卷。正式 API 启动会自动应用迁移，首次启动新正式镜像必须在备份与隔离还原演练完成后；测试服务始终使用隔离连接，不能借正式服务启动做迁移试验。当前提示词即为执行正式部署的授权，前置验收通过后继续部署，无须再次请求同一操作的确认。
 4. 不修改学生原件和仓库课程报告；测试生成的文件放在临时目录。不要提交 .env、模型权重、数据库备份、学生材料、生成的成绩和缓存。
 5. 保留工作区已有改动，不删除不属于本任务的文件。不自动创建、推送或合并 PR。
 6. 常规实现选择和可逆修复自主完成。规则含义或历史范围确实无法确定时，记录具体待确认事项并继续其他工作，不能用静默猜测消除歧义。
 7. 开发阶段使用模型替身及真实本地嵌入模型。为上线验收，授权使用当前已配置的真实评分/会话模型，在正式环境以仓库四份课程报告为来源的新验证项目、新规则版本、新批次和独立验证会话执行一轮完整评分及必要的引用校验重试、一次只读 Agent 检索回答，并生成该验证批次的 Excel/PDF。验证记录明确标记，不使用批次 3 或会话 6，不对其他业务项目发起批量模型调用，不自动删除验收记录。汇报实际调用范围与结果；模型配置不可用时明确报告未通过的上线验收，不以替身结果代替真实模型结果。
 ## 二、先核对当前实现
 检查 Git 状态与提交，阅读 AGENTS.md（如有）、README.md、HANDOFF.md、docs/GUIDE.md、docs/EVIDENCE_POLICY_BATCH3.md 及相关测试。此前证据治理提交为 b7634c8；以当前源码为准，不假定以下问题仍原样存在。旧提示词或文档中的“仅隔离测试、不部署”是历史任务边界；本提示词已明确授权本次正式部署，不能将旧边界当作需要再次确认的理由。
 重点检查：
 - backend/wisegrade 下的 models.py、rules.py、evidence.py、pages.py、parsing.py、knowledge_pages.py、rag.py、indexing.py、scoring.py、services.py、api.py、agent_tools.py、chat_api.py、exports.py、actions.py、materialized.py、seed.py、db.py；
 - backend/migrations、backend/tests、backend/pyproject.toml、backend/uv.lock、compose.yaml；
 - frontend/src/App.tsx、Chat.tsx、api.ts 及浏览器测试。
 先建立一份简明的模块依赖和数据来源清单，再按后续阶段实现。确认并补回归验证的已知问题：
 - rules.Criterion.required_evidence 仍是 list[str]，而 evidence.py 已读取对象；新规则无法贯通创建、编辑与发布。
 - rag.py 重复定义 _keyword_query；page_text、relative_image_path 在不同模块重复；found、audit 也存在重复。不要把同名路由与服务函数机械地判为重复。
 - 索引任务依赖评分模块中的解析逻辑；reindex_stale 从 services 导入不存在的 parse_submission，会在访问数据库前抛出 ImportError。
 - 混合页的正文块仍继承 toc 页面类型，内容检索会排除它；评分阶段重读整页类型也会覆盖块的用途。
 - 检索没有完整限制文档就绪状态和索引版本，也没有可靠排除 legacy 片段。
 - 评分校验只检查每条引文是否合法，正分结果仍可能只引用结构证据而没有内容证据；未知 target_id 还会被默认目标接收。
 - 模型返回 null 的分支未统一生成缺证据记录；完成最后一项教师复核后未重新计算批次状态。
 - Agent 的引用筛选只按引文前缀或页号猜测，不能区分不同文档的同页号；Chat.tsx 未贯通来源类型和历史引用标签。
 - search_document 在项目级候选截断后才过滤指定文档，可能漏掉文档内正文；get_document_pages 从片段而不是完整资料页生成清单。
 - 中文关键词检索逐片段扫描字符二元组，没有分词后的倒排索引；ASCII 匹配缺少词项边界。
 - 章节只是页面标签，切块仍按页内字符窗口；同页多个小节、跨页段落和表格来源没有统一表达。
 - 课程与规则既有 JSON 又有关系表投影，权威来源和投影用途需要明确。
 - 初始迁移读取当前 ORM metadata 建表，迁移重放结果可能随模型变化；文档索引版本的 ORM 默认值、数据库默认值和当前索引版本不一致。
 ## 三、阶段 1：统一对象、规则和状态契约
 先明确对象的不变量和各层输入输出，再让现有调用迁移到同一契约。采用现有 Pydantic、SQLAlchemy 和 TypeScript 工具，不引入与任务无关的框架。
 ### 1. 文档与来源
 区分并连接文档、页面、文本块、章节、检索片段、来源范围和引文：
 - 页面保存完整提取文字、图片链接及页面概览分类；原始解析产物与规范资料页的职责要明确。
 - 文本块保存实质来源类型和位置；混合页的内容权限以具体块为依据，不能仅由整页 toc 标签否决正文块。
 - 章节有稳定标识、父子关系和完整路径，不能只靠标题字符串判定同一章节。
 - 检索片段可包含多个来源范围；引文能定位到实际原文页及块。
 - 明确原文、清理后检索文本和索引词项的用途，保持可验证的来源映射。
 - 缺字段或未知分类不得自动当作正文。
 使用统一的类型化数据契约。数据库实体、检索结果和 API 展示可以有不同对象，但转换边界明确，禁止各模块重复拼出不一致的证据字典。测试替身也要实现正式契约。
 ### 2. required_evidence
 将其定义为评分项要求检查的证据目标清单，与具体检索实现分开：
 - target_id：在所属评分项内唯一且稳定；系统可以生成，但生成后持久保存，不随数组重排变化。
 - label：明确描述要检查的证据目标，非空。
 - use：显式、严格校验的 structure 或 content；正式规则不根据措辞猜用途。
 - allowed_page_types：可选的收窄约束；默认权限由 use 和证据政策推导，配置不得扩大内容权限或让 unknown 成为内容证据。
 - query：可选的检索词覆盖；缺省从目标描述构建查询，不要求教师重复填写。
 - 删除重复保存的 index；text/name 等历史别名仅在受控转换边界处理。
 统一规则 API、发布校验、种子规则、批次快照、评分、Agent 和前端的目标模型。空目标清单的含义显式定义，不自动制造一个含糊的正文目标。非法用途、重复标识、非法来源约束应报明确错误。
 新批次冻结规范规则与解析后的证据政策，避免把原始规则和可独立修改的执行计划变成两个权威来源。记录政策及相关检索配置版本；不能只有版本号而实际执行始终套用当前政策。
 ### 3. 评分状态
 集中定义评分项和批次状态及转换规则，统一 API、Agent、前端、导出标签。保留 needs_review 与 failed、unscorable 的区别。教师分优先形成最终分，模型分和原始缺证据记录保持可追查；null 与 0 不能互相替代。
 ## 四、阶段 2：规范依赖方向和权威数据来源
 按职责收敛现有单体：
 - 文档处理负责解析、清理、页面、块、章节和来源定位；
 - 索引与检索负责切块、分析词项、嵌入、索引、范围过滤和召回排序；
 - 证据政策与评分负责来源权限、目标覆盖、模型输出校验和评分状态；
 - 应用服务负责编排导入、索引、评分、复核和结果查询；
 - REST、Agent、前端与导出使用应用服务和统一展示契约。
 索引和评分都调用文档处理服务；索引不能依赖评分内部函数。评分结果查询移到独立于导出格式的服务，Excel/PDF、API、Agent 共用它。共享页文字、图片路径、引文链接、状态定义只实现一次。避免用局部导入掩盖不合理的相互依赖。
 根据实际读路径，为课程和规则选择唯一权威存储。若保留关系表投影，须有明确查询用途且只能由权威数据重建；若删除无用途投影，提供兼容已部署库的迁移并调整业务测试。批次的不可变快照属于审计记录，应保留。
 项目正式部署和测试统一为 PostgreSQL 16 + pgvector + pg_jieba；正式数据库、test-db 和隔离还原副本使用同一数据库镜像及词典版本。清理无法完整支持的 SQLite 运行路径，错误配置要明确失败。检查依赖版本兼容分支，仅保留实际支持、可测试的范围。
 收敛旧接口、前端旧参数恢复和旧字符串规则处理。历史记录只读转换集中在边界，不参与新规则执行。无法还原的旧批次范围保持未知，不能用当前项目清单声称恢复历史范围。不要删除历史数据或无依据地重写旧快照。涉及旧接口停用须列出当前调用方、转换方式与影响。
 修复迁移重放的不确定性，固定各迁移对应的结构；修改既有迁移文件时明确已部署库与新库的不同路径，不重排已有 revision 或假设旧库会重新执行它们。用隔离旧版本数据库验证升级，不能仅用新 ORM 自动建表代替升级验证。
 ## 五、阶段 3：实现章节约束下的段落切块
 先完善来源对象，再替换切块策略：
 1. 从真实正文块的标题提取章节树，正确处理层级、同页多个小节、跨页延续、重复标题、编号列表与公式。目录辅助导航和确认，不直接当作正文。
 2. 同一小节内按完整段落合并跨页文本；长度预算内保留语义连续性。以所用嵌入模型的实际 tokenizer 计算预算，不仅按中文字数计算，也不硬编码未知模型容量。
 3. 长小节按段落与句子边界细分。表格及其必要标题、条件说明优先作为完整单元；超长表格按行组切分并保留表头和来源。避免重复拼入表格或丢失表格结构。
 4. 目录、摘要、参考文献等保持各自来源类型。混合页的目录块与正文块分别参与相应检索。
 5. 每个片段关联稳定章节标识和逐页来源范围。跨页引文应拆分或记录多个范围，教师能看到各自实际原文和图像；不能仅用片段首页或模糊起止页代替定位。
 6. 小片段用于召回；需要时按同节邻接关系补充受控上下文。所有扩展上下文仍执行来源权限、项目范围和模型输入预算。
 章节标签要落到块和片段，不能将页面上最后出现的小节标题赋给整页所有文本。切块、来源映射和引文校验共同更新，不留下仍假设一个 chunk 只有一个 page 的评分、工具或导出路径。
 ## 六、阶段 4：使用 pg_jieba 实现中文分词与词项索引
 中文分词方案已确定：直接使用 PostgreSQL 扩展 pg_jieba，并通过 PostgreSQL tsvector/tsquery 和 GIN 索引实现关键词召回。应用负责文档处理、章节切块和检索编排，中文词语切分统一由数据库执行。不要另行实现 Python Jieba 主路径或双套分词，不替换为 zhparser、独立搜索服务或字符扫描回退。无需比较分词器后再决定是否使用 pg_jieba。
 以 pg_jieba 上游实现（https://github.com/jaiminpan/pg_jieba）为起点，固定扩展与 cppjieba 子模块的版本或提交，实际在 PostgreSQL 16 上构建并验证。安装问题应定位和修复；确有必要的构建适配或补丁纳入仓库并记录依据。若仍无法解决，报告具体阻塞并保持任务未完成，不能静默换回应用层分词。
 要求：
 - 在仓库维护数据库 Dockerfile，基于固定的 PostgreSQL 16/pgvector 基础镜像安装 pg_jieba，固定源码、子模块和词典版本；使用多阶段构建或清理构建依赖。不能仅在运行中的容器里手工安装，也不能替换成未经核对的第三方集成镜像。
 - 在每个目标数据库及测试临时数据库中创建 pg_jieba 扩展和课程专用全文检索配置，明确 schema 和配置名称。入库与查询显式引用该配置，不依赖会话默认配置或修改整个数据库的默认全文检索行为。
 - 入库与查询采用同一版本的 pg_jieba 分词规则；验证并选择扩展提供的混合/搜索分词配置，统一词典和规范化处理，确保查询词项可匹配索引词项。实际验证 Unicode、英文大小写、标点、数字、英文整词和中英文混合技术术语。
 - 在仓库维护 pg_jieba 格式的课程领域词典，将其部署到数据库可读取的位置，至少验证 文献调研、技术现状、串级PID、视觉伺服、闭环控制、Otsu 等词，不靠针对某一测试报告的特判。记录词典文件校验和、扩展版本、分词配置及必要的加载/重启步骤，更新词典后重建受影响的词项索引。
 - 对完整术语和合理子词的召回、停用词及同义词策略明确说明，用评估确认精度与召回，不盲目删除数字和技术词。
 - 索引词项与原文分开，分词结果不能替代教师核对的原文。
 - 由 pg_jieba 全文检索配置生成并持久化 tsvector，建立 GIN 索引；生成 tsquery 时使用安全的参数化查询，明确多词匹配和排名策略。不能继续以逐片段 generate_series、strpos 或 Python 全表扫描作为主路径，也不能在扩展缺失时静默启用旧字符二元组召回。
 - 语义召回与关键词召回各自取候选，以排名融合合并；不把不同量纲的原始分数直接相加。不要把 PostgreSQL ts_rank/ts_rank_cd 宣称为 BM25。
 - 在实际 PostgreSQL 上验证 CREATE EXTENSION、中文解析、领域词典加载、词项匹配、词边界、GIN 索引及查询计划，覆盖容器重建/数据库重启后配置仍有效。说明小数据集可能选择顺序扫描，不用强制索引开关冒充真实查询性能。
 - 数据库镜像、扩展、全文配置与词典是备份恢复和部署依赖，须一并记录和演练；pg_dump 不包含扩展二进制与词典文件，不能把数据库备份当作完整的运行环境备份。扩展或配置缺失时明确失败，禁止把数据库故障表现为没有搜索结果。
 ## 七、阶段 5：贯通检索、评分、Agent、前端和导出
 ### 检索与证据
 所有入口共用统一检索服务和范围对象。课程版本、学生项目、公共资料、指定文档、材料类别、允许来源及文档就绪/索引版本过滤，必须在候选上限之前完成。新索引构建失败不得把未完成文档标为 ready，也不得静默读取旧片段。
 每个证据目标独立检索并保存检索结果。候选分配在受控总量内兼顾目标覆盖、页面和章节分散；同一片段可以支持多个目标，不因按 chunk_id 去重而丢掉目标关联。章节软上限以稳定章节标识和文档范围计数。
 检索命中并不等于证据足以支持判断。目录导航应匹配实际正文标题，再补检该节和相邻正文块；没有 admissible 且相关的内容证据时，不因语义召回总能返回一些片段就视为目标已覆盖。
 ### 评分与复核
 逐条校验目标标识、引文原文、来源范围和来源权限，拒绝未知 target_id，不用默认目标悄悄接收。内容判断不能由目录、摘要或单独章节标题支撑。正分结果必须包含支持内容判断的合法内容引文，不能只给结构目标引文；内容目标的覆盖或不足要显式报告。模型可理解证据并说明不足，代码负责权限、覆盖一致性和状态转换。
 统一检索不足和模型返回 null 的处理：记录缺失目标、实际检索范围、补检过程和不足原因，模型分为 null，相关总分待处理。不要把没有查到解释为学生没有写，也不要把 lack of evidence 自动折算为 0。合法的明确 0 分不能被展示成空值。
 教师复核保留原始模型记录与缺证据记录，保存修改历史并更新评分项状态；当最后一项复核结束时重新计算批次状态。重试保留已评分项和教师复核。项目事实抽取也遵循来源政策。
 ### Agent、API、UI、导出
 - 内容搜索与结构查询共用政策；get_document_pages 从规范页面数据取得完整清单，search_document 在数据库候选截断前限定文档。
 - 使用稳定 citation_id 和结构化引用协议，最终回答只附实际使用且可定位的来源。验证文档、来源范围与用途，不能仅按页号或引文前缀猜关联；保留面向教师的正常自然语言回答。
 - 评分详情和会话引用卡片贯通来源类型、证据目标、正文/目录区别及历史评分引用标签。历史引文保持原内容，不能自动充当新内容证据。
 - 前端使用统一接口类型，清理本次涉及的数据链路中的 any 和重复状态映射；不得以类型断言掩盖缺字段。
 - 教师评分框无分时为空，已有合法 0 分正常显示；复核后的最终分与批次状态同步。
 - Excel/PDF 共用结果查询，实际生成并解析验证文件；保留 0、null、待复核状态、来源位置、跨页引文、历史标记和原始不足记录的正确含义。
 - API 文档与实现一致，旧接口和数据转换边界在文档中列明。
 ## 八、阶段 6：隔离迁移、重建与评估
 提升索引版本，统一相关默认值，并记录切块策略、分词器/词典和嵌入配置版本。实现可重试、可审计的重建：优先复用已保存解析结果，课程公共资料按规范入库路径处理；源文件哈希变化要报告，不改原件。不能因错误地重设 parse_status 而无必要地重新解析材料。
 重建可重复执行，成功文档跳过，失败文档可重试，进度、失败原因和剩余旧索引数量准确。处理学生资料与公共资料，不能在任务显示成功后悄悄留下未处理资料。旧评分保存的引文不能因片段重建而失去原始来源关联。
 本阶段测试使用专用 PostgreSQL/pgvector/pg_jieba、专用 Redis 和临时文件目录，明确确认连接和任务队列隔离；开发测试不向业务环境写入。业务变更在下一阶段按已验证的部署流程执行。
 ### 必须实际验证的验收条件
 1. 规则对象从 API 创建、编辑、发布到批次快照和评分完整贯通；显式 use 生效，非法目标和来源配置被拒绝；稳定标识不随重排变化。
 2. 阶段报告 1 的第 2–3 页目录与第 6–7 页文献调研正文区分正确，文献分析目标可召回真实正文。
 3. 阶段报告 3 的第 2–3 页目录与第 11–12 页系统测试正文区分正确，测试目标可召回正文；召回这些页不能直接等同于应得某个分数。
 4. 最终报告第 2–3 页摘要、4–5 页目录、6 页起正文、49 页参考文献、50–53 页附录区分正确；阶段报告 2 也纳入分类和切块检查。
 5. 合成混合页的正文实际进入内容检索，并通过合法评分引用校验，目录块仍被拒绝；检查完整链路，不能只断言正文块已保存。
 6. 同页多小节、跨页段落、重复标题、长章节、表格和编号列表正确处理；跨页片段的引文落到准确原文页，文字和图片均可核对。
 7. pg_jieba 在 PostgreSQL 16 的正式同版测试镜像中实际安装并运行，领域词典生效；文献调研、串级PID 结构、视觉伺服与闭环控制等查询命中正文，ASCII 词项边界正确，GIN 词项索引真实存在。容器重建/数据库重启、备份还原及扩展缺失报错路径均验证。
 8. 内容评分拒绝目录、摘要、单独标题、未知目标和伪造来源；混合结构/内容评分项的正分结果不能只引用结构证据。
 9. 检索不足和模型返回 null 均进入待教师复核，缺证据记录完整，总分待处理；教师可录入 0 或其他合法分，记录保留，最后一项复核后批次状态正确。
 10. 指定文档检索在其他文档高排名候选挤占名额时仍能找到该文档正文；旧版本、legacy、非 ready 文档不参与新检索；学生与课程版本隔离及公共资料权限正确。
 11. Agent 引用能区分不同文档的同页号、改写回答与实际使用来源；工具查到但回答未使用的片段不被附上；评分界面和会话界面的历史标签实际可见。
 12. 重建入口实际执行成功，失败后重试和重复执行有效；学生及公共资料均覆盖，历史引文仍可核对。迁移在新库与旧版本隔离库均验证，升降级及再次升级范围如实记录。
 13. 实际生成并解析 Excel/PDF，验证 0 分、待复核、复核后成绩、跨页来源和历史引用；不是仅检查代码可以 import。
 14. 前端类型检查、生产构建和相关浏览器流程通过，涵盖证据标签、无分输入框、0 分、复核和会话引用；模拟 API 的浏览器测试不能宣称真实后端端到端通过。
 ### 检索质量评估
 在改造前保存可比较基线，再以相同语料、查询和预算比较改造后结果。至少使用四份真实课程报告，覆盖明确术语、宽泛问题、结构查询和指定报告查询。
 用固定查询集记录 top-k 正文召回、目标覆盖、重复片段占比、无关候选、片段与 token 数量、查询延迟和数据库查询计划。关键词路径可用固定向量隔离测试；语义与混合检索质量须用可用的真实本地嵌入模型单独评估，不能由固定向量测试代替。
 将章节切块与中文分词的影响尽可能分别比较，不把所有改动合并后一次通过当成各自有效的证明。核心回归不得退化；出现退化要分析和修正，不仅扩大候选量掩盖问题。记录模型、语料和参数，保证结果可复现，不虚构性能提升百分比。
 ## 九、阶段 7：实际部署到正式业务并验收
 ### 1. 记录基线并验证备份
 - 确认当前正式 Compose 项目、镜像标识、服务状态、数据库迁移版本、业务队列、持久卷和挂载路径；记录可恢复的旧镜像与旧配置，不输出密钥或密码。
 - 对既有批次、评分、教师复核、历史消息和工具记录建立部署前基线，尤其核对批次 3、会话 6。必要元数据转换与原始业务内容分开比较，不能用只比较记录数量证明内容未变。
 - 备份业务 PostgreSQL，并保留索引重建涉及的处理资产及必要部署配置；记录包含 pgvector/pg_jieba 的新旧数据库镜像、扩展版本、领域词典及配置校验和。备份使用受限权限和校验记录，不提交 Git。
 - 实际将业务备份还原到隔离副本，验证关键记录与历史链接；在副本执行最终迁移、学生及公共资料重建和查询验收，记录耗时与失败情况。只运行 pg_dump 而没有验证恢复不算完成。
 - 先构建新镜像并完成必要构建检查，保留旧镜像；制定与当前数据库变更兼容的回滚路径，并在隔离副本验证。不能把未经验证的 downgrade 当成回滚保证。
 ### 2. 执行迁移和服务更新
 - 检查正在执行的评分、索引与 Agent 任务；先阻止接收新的相关写任务，等待现有任务正常结束，再暂停会写入不兼容结构的旧服务。不能中断正在执行的教师业务、取消既有作业或清队列。若有长期任务无法自然结束，继续准备可独立完成的工作，并准确说明上线阻塞。
 - 在写任务排空后取得最终一致的业务备份；若数据自演练备份后变化，核对变化对迁移的影响，必要时补做演练。
 - 按已演练顺序更新正式数据库为包含 pgvector/pg_jieba 的同主版本镜像，保留现有数据卷；验证数据库恢复健康、领域词典可读、必要扩展与配置可创建，再执行正式迁移。考虑 API 自动迁移，避免多个进程并发迁移及新旧 worker 同时写入。不得重建空库代替升级，也不得在扩展尚未可用时启动新检索业务。
 - 更新正式 API、worker、Web，恢复必要队列消费。确保服务使用同一版源码、迁移和依赖，数据库和模型挂载保持正确；不删除持久卷、不重新初始化种子业务数据。
 - 对正式学生和公共资料执行已验证的索引重建，跟踪到结束并处理失败项。源文件变化等不可重建项逐项报告，不修改原件，也不能在尚有未处理旧索引时宣称全量升级成功。
 - 在索引重建完成并通过关键查询之前，不把检索服务宣称为可用；如需维护状态，给出真实进度并在验收后恢复正常入口。不得通过启用旧片段回退来掩盖重建缺口。
 ### 3. 正式上线验收
 通过实际 Web 入口和正式 API 验证，不仅检查容器处于 running：
 1. 数据库、API、worker、Web 健康，迁移版本和镜像一致；正式 PostgreSQL 16 的 pgvector/pg_jieba、课程全文配置、领域词典与 GIN 索引实际生效，日志无新增启动、任务或查询错误，真实后台作业可完成。
 2. 页面/块/章节清单、正文检索、指定文档查询和历史引文文字/图片链接正常；业务旧索引清单已处理完或明确报告剩余项及其影响。
 3. 批次 3 的分数、复核及快照，与会话 6 的正文/工具记录和其他保护数据符合部署前基线；允许转换的来源元数据按转换规则核对，原始引用仍可定位。
 4. 在业务环境创建明确标记的新验证项目、规范规则版本和新批次，使用仓库真实课程报告执行已授权的一轮真实模型评分。缺证据转复核与合法引用按新政策工作；不要为了让所有项得分而放宽校验或伪造教师复核分。
 5. 通过独立验证会话执行已授权的真实只读检索回答，在浏览器确认引用来源、页面文字/图像、结构与内容标签。新记录 ID 和用途写入交接记录。
 6. 实际生成、下载并解析新验证批次的 Excel/PDF；存在待复核项时保持空分与状态正确，不能把仍待处理的批次记作完整评分成功。
 7. 浏览器检查评分页、复核输入框、历史标签、会话引用和移动端布局；仅在隔离或验收记录上测试写入，不能为 UI 测试修改真实教师评分。
 上述验收失败时修复具体问题并重验受影响部分；不要在反复调用模型中掩盖检索或协议缺陷。正式环境缺少关键外部能力时，将服务部署情况和未通过验收分别报告，Goal 保持未完成。
 ### 4. 失败处理与回滚
 出现严重迁移或上线失败，停止继续扩大业务变更，按已验证方案恢复服务。应用旧镜像前核对数据库兼容性；数据库恢复镜像必须包含恢复目标所依赖的 pg_jieba 扩展及词典，不能将含扩展依赖的库直接交给不含扩展的旧镜像。需要恢复备份时先停止相关写入并保存故障现场。
 若上线后已有新的教师业务写入，不能直接覆盖还原而丢失这些数据：先保存并核对新增写入，采用已验证的保留方案；没有可保证数据保留的恢复路径时，准确说明具体阻塞并请求该恢复动作所需决定。原有部署授权不包含丢弃部署后教师数据。
 回滚后验证业务入口、任务队列、保护数据和历史链接，并记录失败原因、采取的动作和当前运行版本。回滚恢复可用不等于本次改造部署成功，不得据此将 Goal 标记完成。
 ## 十、最终交付
 1. 提交前核对差异和工作区，按清晰阶段组织改动，不夹带无关重构。
 2. 更新 docs/GUIDE.md、HANDOFF.md 和必要的业务上线清单；历史验证记录保留，新记录注明当前范围。
 3. 给出改造后的模块职责、对象关系、权威数据来源和主要调用链，列出已删除或收敛的兼容逻辑及仍保留的原因。
 4. 列出新增迁移、索引版本、pg_jieba/cppjieba 固定版本、全文检索配置、数据库 Dockerfile 和领域词典校验和，以及隔离库中的升级、重建和回滚验证结果；记录正式部署前后迁移版本、数据库及应用镜像标识与各服务健康状态。
 5. 给出实际测试命令、通过/失败/跳过数量、真实本地检索评估、生成导出的检查结果与尚未验证部分。不能用旧测试记录证明新代码通过。
 6. 汇报实际执行的正式部署步骤、备份路径与恢复验证、学生和公共资料重建数量及剩余项、真实模型验收批次/项目/会话 ID、导出检查和业务入口地址。批次 3 的教师复核仍由教师决定，只提供正文定位与复核清单，不自动改分。
 7. 明确业务库实际变更范围及保护数据对比结果：哪些结构、索引和来源元数据已更新，哪些验收记录已新增，批次 3 的原始评分/复核/快照及会话 6 的历史内容是否保持。若发生意外修改，立即说明实际影响和证据，不能隐瞒或把“记录数相同”当作未改写证明。
 只有代码、迁移、必需的隔离验收、正式部署、索引重建及上述真实上线验收实际完成后，才将 Goal 标记完成；不得停在“等待部署确认”或“建议后续上线”。当前正式环境以外的 Windows 实机等验证如未运行，可注明边界；当前业务上线必需验收未通过则仍未完成。
 ~~~
@@ -8,5 +8,6 @@
 | [业务 Agent](CODEX_CHAT_AGENT_GOAL_PROMPT.md) | 会话、业务工具、操作确认与自动索引的阶段任务。 |
 | [会话界面](CODEX_SESSION_UI_GOAL_PROMPT.md) | 草稿、范围、历史会话、Markdown、工具记录和后台运行的增量任务。 |
 | [目录、摘要与正文证据治理](CODEX_EVIDENCE_RAG_GOAL_PROMPT.md) | 页面分类、检索与评分证据治理任务，包含业务数据库不可改写的明确边界。 |
 | [架构规范化、中文检索与章节切块](CODEX_ARCHITECTURE_RAG_REFACTOR_GOAL_PROMPT.md) | 按阶段统一对象和依赖、实现章节切块与 pg_jieba 中文词项索引；隔离验收后实际部署正式业务、迁移和重建索引，并保留历史评分与会话。 |
 提示词记录任务要求，不代表功能已经完成或通过验证。应用运行时的评分 Prompt 由课程版本管理，不在本目录维护。