9e6f1c4481
- src/muse 新版全模块（装配/共享/上下文/任务运行/作品规划/故事世界/正文写作/审校修订/知识方法/作者经验/效果评测/交付连载/资料研究/正式变更/元数据/接入/基础设施/编排）+ 测试树（单元/契约/集成/架构/迁移/端到端/夹具） - 129 项功能全部实现与自动验证（功能覆盖.json/矩阵），含 W31 补齐的规则与代价/节奏安排/伏笔与承诺 - 旧实现按处置清单退出（702 条中 324 删，保护合同与未迁移条目留存有据）；web/app.py 旧工作台退役，新工作台为唯一写入口 - 数据库/旧库迁移：真实旧库内容批次迁移链（端点守卫/PG作品正文映射/质量资产缺省投影） - 运行手册 docs/运行手册.md；W30 本机服务阶段一已运行（infra PG 为正式内容权威） - R2 执行证据与私有运行材料在 .agents.local/改造/R2-20260909/（不入库）
158 lines
17 KiB
Markdown
158 lines
17 KiB
Markdown
# 迁移与验收
|
||
|
||
本文定义主体替换的顺序、资产承接和退出判据。设计落盘不触发实施、正式数据迁移、旧库删除或部署。
|
||
|
||
具体文件范围以[现有文件处置](现有文件处置.md)及其[逐项清单](现有文件处置清单.json)为准，包含旧路径、源内容基线、替代位置、保留行为和验收入口。下列增改删编号用于解释迁移主题，不代替逐文件清单，也不授权按目录通配删除。实施前源哈希或运行引用发生变化时，必须重新核对该条承接关系。
|
||
|
||
测试以[独立用例](验证设计/测试用例重写.md)为重写单位，允许拆分、合并及有理由退役；旧测试文件只作来源索引。数据转换分别遵守[旧知识记录分流](数据模型/旧知识记录分流.md)与[原文证据生命周期](接口契约/原文证据生命周期.md)，不能用路径映射或行数相等证明语义承接。
|
||
|
||
## 增改删清单
|
||
|
||
### 新增
|
||
|
||
| 编号 | 新增项 | 具体落点与意义 |
|
||
|------|--------|----------------|
|
||
| A01 | 可安装应用包与唯一启动装配 | `pyproject.toml`、`src/muse/启动.py`，统一依赖与资源发现 |
|
||
| A02 | 类型化业务命令与查询接口 | 接入/模块公开接口；HTTP、CLI、Skill 共用行为 |
|
||
| A03 | 统一正式变更机制 | 必需审阅身份、CAS、幂等、依赖复检、回执和派生登记 |
|
||
| A04 | 持久化任务执行 | 步骤、租约、检查点、取消、恢复、事件重连与预算 |
|
||
| A05 | 完整任务范围与依赖模型 | 预组装、工具、回放、采纳共用可检验范围 |
|
||
| A06 | 新版独立数据模型与迁移层 | 承接旧 PG/SQLite 内容，退出主仓列结构的长期捆绑 |
|
||
| A07 | 正文结构及选段协议 | 段落身份、中文位置口径、编辑往返、保护范围 |
|
||
| A08 | 来源及派生影响索引 | 正文、事实、规划、方法、报告和投影的版本依赖 |
|
||
| A09 | 作者工作台与服务端查询视图 | 承接 StoryForge 交互、任务状态与统一写入 |
|
||
| A10 | 可恢复的数据演进与验证入口 | 升级、备份、隔离恢复、数据对账及全旅程验证 |
|
||
| A11 | 元数据能力在新版的完整承接 | S04 类型与字段、结构版本、作品扩展、动态表单、用途投影和升级检查；不是新造第二套实例库 |
|
||
|
||
### 修改 / 重写
|
||
|
||
| 编号 | 现有对象 | 新形态 |
|
||
|------|----------|--------|
|
||
| R01 | `framework/`、`runtime/`、分散 LLM 脚本 | 保留协议与适配代码，收进运行和基础设施职责；不让业务直接构造 Pi |
|
||
| R02 | `muse/flow/dispatch.py` | 任务执行、治理、证据分别内聚，编排只组合公开接口 |
|
||
| R03 | `produce_next_chapter.py` | 通用写作任务，生产与评测分开配置，按明确规则选择必要步骤 |
|
||
| R04 | `write_canonical.py` 与各决策 HTTP 入口 | 完整正文提交用例，共用强制合同，各入口行为一致 |
|
||
| R05 | 规划与知识确认 | 从“翻状态”改为“重验版本、依赖、结构和明确作者选择后提交” |
|
||
| R06 | `read_tools.py` 与检索组装 | 输入范围不可放宽，记录真实读取与来源版本 |
|
||
| R07 | 拆书/抽取 `upgrade.py` | 拆为输入分窗、提取、别名/关系归并、持久化、恢复与维护，保留原有互斥和补偿行为 |
|
||
| R08 | 去味脚本群 | 保留纯规则与 patch，重写入口、报告持久化、任务/经验接线 |
|
||
| R09 | 经验的 PG/SQLite 两路 | 统一提案、实验、目标变更、启用与退役 |
|
||
| R10 | 现有表与 JSON 字段口径 | 稳定业务骨架与动态内容分开；S04 维护类型、字段及结构版本，业务模块拥有实例；旧字段和别名显式映射 |
|
||
| R11 | 原只读看板与分散表单 | 新工作台 + 只读审计查询，独立保留只读职责但不保留多份页面实现 |
|
||
| R12 | Skill 实现与目录 | 方法/操作清晰，代码包独立，清单单源生成 |
|
||
| R13 | 测试清单与门禁 | 依赖显式、离线默认禁外部连接、行为反例覆盖所有实际入口 |
|
||
| R14 | 文档事实源 | 按架构/领域/数据/契约归位；现状、目标、历史与个人草稿清楚区分 |
|
||
|
||
### 替换完成后删除或退出
|
||
|
||
| 编号 | 删除 / 退出对象 | 为什么 | 必需承接条件 |
|
||
|------|-----------------|--------|--------------|
|
||
| D01 | 跨 Skill 的 `sys.path`、父目录猜测与裸文件名导入 | 依赖受物理路径和导入顺序影响 | 任意 cwd 的安装包入口与独立调用通过 |
|
||
| D02 | 作品/章节专用生产门锚、从回放配置读生产设置 | 生产无法泛化且混用评测条件 | 多作品通用链与明确内容门合同通过；样本移入评测 |
|
||
| D03 | SQLite 重复运行/经验/审查写入口及向量镜像逻辑 | 形成两套状态、确认语义和恢复路径 | 数据逐类迁移、仅本地数据保留、历史映射可查、旧写入关闭 |
|
||
| D04 | 旧 `web/app.py`、重复看板模板和候选/lesson 表单路由 | 工作台覆盖后重复维护 | 同一操作的新 UI/CLI/HTTP 行为及审计查询验收 |
|
||
| D05 | Skill 内复制的 SQL、模型重试、预算、raw 写入辅助脚本 | 同一保护在多处漂移 | 共用实现及其真实调用路径覆盖 |
|
||
| D06 | 不再需要的主仓租户、管理、市场列依赖及重复平台治理实现 | 精简单用户不需要的平台机制，保留元数据能力 | 类型、字段、结构版本、动态表单及用途投影由 S04 和各消费模块完整承接；M01—M08 通过，历史映射可查 |
|
||
| D07 | StoryForge 的 Dexie 正式库、独立 AI 调度与浏览器采纳链 | 与新版权威重复 | 这些部分不迁入；必要交互与规则由新主体承接 |
|
||
| D08 | 榜单“最近一次 run”效果归因 | 时间接近不证明因果 | 真实榜单快照与稿件/反馈版本关联替代 |
|
||
| D09 | 只改经验状态但显示“改进已生效”的路径 | 状态无法证明目标已修改且被消费 | 目标 diff/版本、实验、启用与消费记录齐全 |
|
||
| D10 | 运行期读取评测夹具或配置的依赖 | 生产与评测相互污染 | 公共合同放代码，条件与材料保持隔离 |
|
||
| D11 | 源码中连接凭据与隐式正式库默认连接 | 配置不能审计且测试容易误触运行数据 | 受控持久配置、无值示例、测试配置强制独立；实施时核查既有凭据并处理 |
|
||
| D12 | 仅验证文件形状、字符串和固定完成数量的旧测试 | 重构易误报且不能保护业务 | 对应行为测试承接；安全、事务、恢复反例保留 |
|
||
| D13 | 被新文档承接的重复 SoT 正文及失效链接 | 多套现行规则互相覆盖 | 权威文档与上下级目录同步，历史用途已标明 |
|
||
| D14 | 无调用方的空适配器、无实际场景的通用插件骨架 | 增加理解成本而无可观察能力 | 依赖扫描与功能覆盖确认；有对照测试用途的实现移入相应验证目录 |
|
||
|
||
删除对象是被替代实现。正文、原文、历史候选、审查理由、事实、方法、声音、偏好和有效测试不会因改名或换存储丢失。旧库和备份在迁移与回退验证前保留。
|
||
|
||
## 功能承接
|
||
|
||
| 功能组 | 新增的业务语义 | 保留并完善的基础 |
|
||
|--------|----------------|------------------|
|
||
| 创作管理 | 多作品入口、状态与计划、逐步探索页面、近期滚动规划 | 现有阶段 0 方法、规划结构与书/章责任区分 |
|
||
| 故事世界 | 图谱、时间线、人物成长、知情范围、设定使用与修改影响交互 | 现有实体、关系、事实、伏笔与抽取能力 |
|
||
| 扫榜与资料 | 真实榜单快照、选题依据、通用研究资料、私人素材与冲突来源 | 参考书导入、拆解、分窗、来源、范式抽取 |
|
||
| 正文共创 | 完整编辑器、手写保存、自动保存、候选比较、选段和部分采纳 | 两阶段写手、候选、质量检查与正式写入保护 |
|
||
| 上下文 | 混合检索、实际材料展示、统一范围校验、全部读取留档 | 已有冻结、active/绑定过滤及范式版本引用 |
|
||
| 审校去味 | 报告长期保留、版本陈旧、问题单、长文覆盖、有限返修与误杀反馈 | 声音、诊断、授权范围、patch、保真和原文胜出 |
|
||
| 作者经验 | 跨书偏好、冲突撤回、完整方法启用与效果追踪 | lesson 观察、修改对、方法案例与已有评测合同 |
|
||
| 交付连载 | 全书定稿、四类文稿导出、存稿、发布版本及读者反馈 | 现有文本、备份、记录和作者决定基础 |
|
||
| 运行数据 | 任务恢复、断线重连、迁移恢复、查询导航和完整数据带走 | 现有事件、raw、回执、预算和角色策略 |
|
||
|
||
功能广度通过现有十个模块扩大。短篇缩短规划粒度与任务步骤；节点视图编辑同一套规划依赖；二者不新增第二个写作引擎、正文权威或候选状态机。
|
||
|
||
## 实施顺序与退出条件
|
||
|
||
具体执行排程以[完整改造计划](改造计划/总计划.md)及[工作包清单](改造计划/工作包清单.json)为准。32 个工作包分别定义依赖、文件范围、功能与逐例测试安排、验收和回退；[分配索引](改造计划/分配索引.md)可查询每个目标与旧路径的归属。
|
||
|
||
完整终态一次定义，代码按可验收旅程替换。旧实现退出仍须满足本文件与逐项处置的内容/数据条件；计划不授权批量删目录。活跃旧写路径在唯一写入切换后退出，测试按用例判定，W31 进行最终对账。
|
||
|
||
“两部作品各连续两章”是去掉样本依赖的最低工程证据，不是文学质量、多题材效果或规模性能证明。实施顺序不缩小全部 129 项功能范围。
|
||
|
||
### 数据迁移及切换
|
||
|
||
1. 对旧 PG、SQLite、受控 raw/参考文件及私人草稿分别建清单，记录快照与内容校验和；不按表名相似就合并记录。
|
||
2. 在新 schema 或隔离库导入，保存旧系统、旧类型、旧 ID 到新 ID 的映射。PG 正式版本不被 SQLite review 覆盖；SQLite 独有的审查/反馈/经验必须迁入对应历史对象。
|
||
3. 逐类核对正文、原文、类型与字段、结构版本和投影策略、关系、候选、决策、raw、绑定、任务和实验；孤儿引用或无法解释的冲突进入差异报告，不能静默丢弃。
|
||
4. 初次批量导入后，在切换窗口停止旧写入口，迁入增量并核对；启用新版唯一写入，旧系统作为只读回查或保留快照。
|
||
5. 回退必须包含切换后产生的新数据。若未实现反向迁移，就明确只能在新版尚未接受新写入的窗口快速回退；不能承诺切回旧程序自然保住新增稿件。
|
||
6. 只有新旧数据对账、完整恢复和关键旅程通过后，才退出旧写代码；物理删除旧库另按保留与恢复要求处理。
|
||
|
||
## 验证合同
|
||
|
||
| 验证面 | 必须保护的行为 |
|
||
|--------|----------------|
|
||
| 包与依赖 | 安装产物能在无 `.git`、任意 cwd 中启动；移动 Skill 不影响业务；导入不连接网络/数据库 |
|
||
| 模块职责 | 接入不直写正文；模块不导入他模块私有存储；模型工具不能调用正式提交；生产不读取评测配置 |
|
||
| 数据提交 | 过期 revision、源变化、改候选、同命令异参数拒绝；重复请求回同回执；批准增量失败整包回滚 |
|
||
| 分支与快照 | 分支不改主分支事实；合并重验当前版本；跨章快照固定清单，回滚后新增内容和历史证据仍可查 |
|
||
| 上下文 | 其他作品、目标答案、未来章、未确认内容、撤回来源在预组装/探索/回放均受约束 |
|
||
| 任务运行 | 断流无完成信号、结构错误、预算耗尽、取消、重启、租约过期、迟到结果与未知调用结果 |
|
||
| 章后处理 | 正文成功而抽取失败仍可见；重试不重复；旧 revision 不覆盖新投影；事实须另行确认 |
|
||
| 中文编辑 | 输入法组合、表情/组合字符、引号/空行、选段与往返；断网和快速切章不丢稿、不错章 |
|
||
| 拆书与方法 | 原文到结论有版本定位；分窗失败续跑；别名冲突不误合并；绑定改变使旧候选失效 |
|
||
| 审校与去味 | 报告来源漂移、长文覆盖、保护区、数字/引文、声音/视角、不应修改的反例和原文胜出 |
|
||
| 作者经验 | 推断偏好待确认、局部要求不全局化、撤回停止新消费、改进启用必须有目标与验证 |
|
||
| 元数据演进 | 新类型贯通、只增不改、结构/投影/数据版本竞争、必填升级、历史读取、字段用途及备份往返 |
|
||
| 数据演进 | 升级、旧数据映射、完整备份与恢复、切换后新数据的回退条件 |
|
||
| 产品旅程 | 新 UI 和 CLI 调用真后端、隔离 PG；另做真实模型与宿主验证，明确与替身测试的区别 |
|
||
|
||
单元测试默认拒绝网络和数据库访问；集成测试只能使用显式隔离数据库与凭据；真实模型验收单独运行并记录成本。代码库各正式入口均要覆盖，不能只测试底层函数而漏掉作者实际点击的路径。
|
||
|
||
架构检查尽量用导入依赖和可观察行为，不以大文件行数、存在某个函数名或文档包含某个词替代正确性。有效的原子提交、范围拒绝、恢复和保真反例必须承接；仅复述旧实现结构的测试随实现替换退出。
|
||
|
||
|
||
|
||
## 旧结构资产的特别处理
|
||
|
||
原设计的 23 个基础类型、独立 fine_outline 合同、库内激活结构和作品扩展分别盘点。文件种子与库内版本不一致时记录差异，不用文件覆盖运行事实，也不将旧平台表结构照搬为新版设计。
|
||
|
||
字段 key、别名、原文位置、结构与实例版本都保存映射。旧 scene/Block 到新场景与正文段落的映射需保真核对；来源中的章号转稳定章节 ID 时保留旧顺序。保留字段级 AI 用途、演变历程与未来成长计划的区别。
|
||
|
||
## 证据级别
|
||
|
||
每项能力分别记录设计覆盖、实现入口、自动化验证和真实使用证据。离线规则测试、隔离 PG 集成、浏览器真后端旅程、真实模型及恢复演练各自有实际结果。设计文件数量、目录存在或功能矩阵已填不能提升成实现完成。
|
||
|
||
文学改进另需固定条件实验和作者或独立读者判断，不能由两部作品的工程旅程替代。研究材料记录的 56、40 或其他历史测试数量只属于对应参考代码与日期。
|
||
|
||
## 备份与恢复入口
|
||
|
||
完整备份由基础设施的`备份恢复.py`拥有，包含 PostgreSQL custom archive、原文/草稿字节与内容清单；不使用业务文稿导出来代替。备份清单固定程序/资源构建身份、迁移版本与校验和，以及表内容、关系、权限、序列和文件摘要；凭据值与来源绝对路径不进入清单。源表写锁忙时立即拒绝；固定PG快照期间核对文件前后状态，任一失败不生成成功备份。
|
||
|
||
恢复必须使用备份时的程序资源与迁移集，点名backup_id，维护角色连接已配置对应角色的新空库，文件根也必须全新。恢复命令不连接旧源、不启动服务、不重新发送模型请求。`pg_restore`以单事务执行；其失败回滚目标并清理本次文件。提交后的内容复验若失败，保留隔离目标供诊断，不允许将失败当作空库继续覆盖。恢复数据核对后还须运行实际业务旅程。
|
||
|
||
维护机的`PATH`须包含能读取源主版本的`pg_dump`及能读取归档格式的`pg_restore`；应用镜像本身不提供这两个数据库客户端。数据库用途配置、原文根和草稿根均显式给出，不从源码目录或旧默认连接猜测。
|
||
|
||
灾难维护命令独立于S02源库账本：`muse 数据维护 备份 <维护配置> <新目录>`、`核对 <目录>`、`解包 <tar文件> <新目录> --预期备份ID <身份>`、`恢复 <目标维护配置> <备份目录> --预期备份ID <身份>`。备份目录中的清单和归档是中断后重验输入；输出未完成时不会冒充可恢复备份。离线核对/解包无需数据库，恢复仅依赖新目标。
|
||
|
||
正常运行时的`数据维护.yaml`通过S02登记保护步骤“核对维护范围”与执行步骤，接受以下明确请求；CLI为`muse 数据维护 计划 <作者配置> <请求JSON>`，JSON包含非空`command_id`与`request`。推进命令为`muse 数据维护 推进 <作者配置> <任务ID>`；查询和暂停/取消/恢复仍走统一任务入口。
|
||
|
||
| request.action | 其他必填字段 | 所有者与结果 |
|
||
|---|---|---|
|
||
| verify_backup | entry_id、backup_id | 基础设施对已配置目录的具名备份核对字节；不认定已经恢复 |
|
||
| recover_raw | target_task_id | S02只恢复本作者目标任务原文；有效租约保留，migrating先对账 |
|
||
| clean_orphans | 无 | S02按数据库命名空间清理无租约托管对象；未知文件保留，保存清理回执 |
|
||
|
||
任务冻结动作和配置文件根哈希，不接受任意路径或脚本；跨作者、同命令换参数、恢复时目录变化均拒绝。原文归档/清理回执由既有owner保存，部分失败保留检查点并进入失败状态；恢复不重复批准。灾难备份时的表锁与源库停机条件决定其不能依赖被备份库中的S02心跳，因此不将其包装成会死锁的后台任务。
|
||
|
||
作者HTTP只读列出配置目录内备份、核对与下载，不接收任意文件路径或远程恢复请求。工作台明确区分“清单可读”“字节核对”“恢复核验”，下载tar经维护命令安全解包后再恢复。
|