hunjing/docs/operations/rewrite-plan.md

重写执行计划

状态：执行中（rewrite/1.0 分支主线） 职责：记录本次全量重写的范围决策、退役与复用清单、里程碑划分与验收门。本文件是临时治理文档：重写完成、能力矩阵接棒后删除。 决策依据：2026-08-21 与执镜者确认的九条决策（架构基准=AGENTS.md 完整技术栈、领域重写+基础设施复用、旧码退役、重写期间新建 Go 神识、Fastify BFF、最小镜匣壳、全量 1.0 规划、文档主线化改写、运行时插件化+硬核例外）。

1. 执行原则

1. 每个里程碑是可独立验收的纵向闭环（端到端可运行），不做孤立页面或孤立接口；
2. 先写失败测试再实现（Kernel 不变量、镜树不变量、记忆分级是最高优先级测试对象）；
3. 新领域模块落地的同时删除对应旧模块（不做长期共存）；
4. 每个里程碑完成时更新能力矩阵证据。

2. 复用清单（保留改造）

资产	处置
backend/app auth / RBAC / audit / event_store / idempotency / SSE 网关 / core 配置框架	保留，重组入 infra/，对接六域
乾坤沙箱（sandbox/，Rust）	保留；HMAC 授契流程对接司命
博闻（mcp/web-search/，Go）	保留；登记为百工 MCP 能力
天目（tianmu/）	保留；P1 通感期接入
元炁（yuanqi/）	保留；作为神识 type=local Endpoint
frontend/design/ 设计体系与 styles/tokens	保留；新页面沿用
docker 基础设施编排（docker/docker-compose.infra.yml）	保留；应用编排新增照壁/神识/删除玄关
现有测试基建（pytest / vitest / pre-commit / husky）	保留

3. 退役清单（删除，不留兼容层）

3.1 backend 旧领域模块 → 新去处

旧模块	新去处
modules/chat + models/chat（线性会话）	镜树域（mirror_trees/tree_nodes/citations/canonizations）
modules/memory + models/memory（旧记忆）	息壤（memories/triggers/embeddings/factual_records）
modules/personality / personality_emotion + models	灵核插件（道体锚点+调节层），情绪状态并入调节层参数
modules/drive + models	太一插件（目标）
modules/evolution + models	铸魂/正影流程（characters + confirmations）
modules/goal_orchestrator / planner + models(goals/plans)	太一/洛书插件
modules/big_cycle + models	删除（后台整理并入息壤维护任务）
modules/time_sense + time_anniversary	辰正（M8 重实现为横切能力）
modules/knocking	叩心枢（M8 重实现）
modules/extraction	息壤提取管线（M3 重写）
modules/reflection / perception	烛照插件（M6/M8）
modules/agent	天工阁插件（M8）
modules/safety + models/safety	司命插件（M5 重写，四维裁决）
modules/skills / tool_runtime + models/skills	百工插件（M5 重写）
modules/mcp + models/mcp_servers	百工 MCP Client（mcp_servers 表保留）
modules/runtime	Kernel + 运行时（M0 重写）
modules/imports / character_import	导入域（M2 改造对接灵胚+世谱）
modules/lorebook + models/lorebook	世谱（表保留，接入河图激活管线）
modules/macros	符文引擎（提示词组装期展开，M2）
modules/world + models/world	河图（persistent_worlds/world_entities，M6 重建）
services/avatar / models 相关	形仪域（M7）
services/ai_provider + admin	删除：神识 Go 网关接管（M4），配置文件移交神识
玄关（旧 Go MCP 网关，如有独立工程）	删除：MCP 登记并入百工

3.2 数据库

• 丢弃 Alembic 4 个旧迁移与 db/hunjing.db 开发数据；按数据模型 §9 清单重建基线 000（三位顺序编号，经 make db-revision 生成）。
• 表处置以该清单为准（保留改造 / 新建 / 退役删除三列）。

3.3 frontend 旧页面 → 新去处

旧页面	新去处
chat	镜树（当前路径阅读 + 局部树图 + 候答切换/采用/归真）
characters	人物（灵胚→启镜→魂籍→缘契→记忆→形仪分区）
memory	记忆治理（三级记忆/候选箱/撤销/删除）
models	神识阁（偏好/BYOK/用量）
tools	百工（能力目录/授契/行契）
settings / login / register / admin	保留改造
world	世界（境界/世谱，M6 重建）
cosmos / drive / evolution / personality / time / wuxing / runs	删除（runs 并入镜树/天工阁轨迹视图，其余旧模型页面随模块退役）
archive	并入镜树抽屉（归档树列表）

4. 里程碑

编号为实施顺序；每个里程碑末尾的"验收"是进入下一个的硬门。

M0 地基（骨架先行）— ✅ 已完成（2026-08-21）

• 交付：Kernel 骨架（不变量裁决器/命台控制/事件日志接口/循环骨架）、事件总线与插件加载、shenshi_client 边界（先指向临时 stub）、BFF 骨架（鉴权透传+SSE 代理）、神识骨架（ingress/transform 占位实现 + 元炁 endpoint）、Alembic 新基线、Compose 更新（+hunjing-bff/+hunjing-shenshi）。
• 验收：登录（复用 auth）→ 创建占位 Run → SSE 端到端流到浏览器（经照壁）；"模型可见即可重建"断言在 stub 上可跑；旧 chat/memory 模块仍可用但不再新增调用。
• 证据：backend/tests/test_kernel.py 5 用例（事件序列/命台串行/否决/不变量/流式）；shenshi go test 5 用例；bff vitest 4 用例；三服务（照壁 18100 / 灵台 18000 / 神识 18081）真实进程 E2E 冒烟：注册→登录→POST /api/v1/runs→SSE 流读至 run.finished，模型流经 Go 神识 stub（"【神识回声桩】"前缀可证）；全量后端回归 925 passed（另有 20 个预存失败，根因本地缺 config/models.yaml，与本次改动无关，stash 验证）；Alembic 基线合并为单一迁移（41 表，空库 upgrade 干净）。

M1 镜生闭环（灵胚→启镜→魂籍→命台）— ✅ 后端闭环已完成（2026-08-21）

• 交付：embryo_drafts/custodianships/runtime_seats/identity_records 表与 API（迁移 001，顺序编号）；灵胚创建（原创/领养/导入来源受理）、照心试演（run.kind=rehearsal，幻境 Run、无人物、不产生经历）、启镜（原子闸门）、放弃；死亡请求/撤销/落定与冷静期；魂籍版本化导出与校验；命台租约 API（冲突留痕、过期接管、epoch 递增）。
• 验收：启镜前无正式人物 ID；同一人物并发启镜/命台抢占被拒且留痕；魂籍导出可验证、复制不能冒充（签名摘要校验用例）。
• 证据：backend/tests/test_jingsheng.py 7 用例全绿；全量回归 932 passed（20 个预存失败与 M0 时相同，缺 config/models.yaml）；make db-upgrade 空库 000→001 干净应用（含 SQLite batch alter）。
• 遗留到 M2：随缘灵胚候选生成、角色卡导入对接灵胚、Kernel 前台串行接入 DB 租约（多进程一致）、前端人物页。

M2 镜树闭环（核心主线）

• 交付：mirror_trees/tree_nodes/citations/canonizations/transplants 全量 API；另答/续思/续生/编辑分叉/采用/归真（三界 scope）/移栽/引文锚；SSE 芽体→固化；前端镜树页（当前路径+局部树图+抽屉）；导入改造（角色卡 V2/V3→灵胚+世谱）+ 符文引擎/眉批/火候接入组装管线；删除旧 chat 模块与 chat 页面。
• 验收：镜树 PRD §14 十个验收场景全部自动化通过（三候答保留、归真不回滚、分叉可达、幻境不入真界记忆、残答续生、引文快照、移栽谱系、归真冲突暂停、移动端可完成、轨迹可读）。

M3 记忆闭环（息壤）

• 交付：三级记忆管线（提取/分级落位/去重合并/版本链/删除墓碑）；双路检索+RRF+召回预算；微痕激活管线（时序效果/次级键/递归/预算）+ 世谱激活共用；召回审计与透明展示；前端记忆治理页；删除旧 memory/extraction 模块。
• 验收：未归真旁枝自动入忆率=0；重忆未确认写入被拒（HJ-1201）；deny 两次退出检索；正影后旧版停止普通召回；删除后全链路停用；召回带来源可展开。

M4 神识完整接管

• 交付：Go 神识全量（transform adaptor：OpenAI 兼容+Anthropic+元炁；路由/冷却/熔断/粘性；BYOK；计量 usage_logs；配额三段式）；灵台切换 shenshi_client；删除 Python ai_provider 与相关配置/页面 models 旧实现；神识阁用户面（偏好/BYOK/用量）。
• 验收：故障注入（首字超时切道、凭证级冷却、熔断恢复）通过；usage_logs 与 Provider 对账抽样一致；灵台内无 Provider SDK import（rg 审计为空）。

M5 百工与司命

• 交付：百工注册表+四维风险标注；授契/行契/请命确认流；乾坤 HMAC 对接与执行审计；博闻登记接入；工具结果净化标证；行动账视图；前端百工页；删除旧 skills/tool_runtime/safety/mcp 网关 remnants。
• 验收：未授契能力调用被拒并留痕；请命超时不执行；禁域规则无法被任何 Profile/插件关闭（专项测试）；工具结果先为观察（不自动成事实/记忆）。

M6 缘契、人格与世界

• 交付：缘契约/问心/铭契/撤回版本链；道体锚点+调节层+铸魂/分灵；河图世界域（persistent_worlds/entities/世谱接入）；正影流程打通记忆与镜树；删除旧 personality/drive/evolution/world/reflection 模块与对应页面。
• 验收：多维关系无单一好感度；边界撤回立即生效；铸魂走确认流而调节层演进有证据；分灵保留谱系；境界正史不进真界本相。

M7 形仪与语音（P1 面）

• 交付：真形锚点/主仪化仪/定相；图像生成候选治理；Live2D（pixi-live2d-display 基座）接入与动作映射；声音三来源与克隆授权；ASR/TTS 异步语音（天目接入）；前端形仪工坊；删除旧 avatar 模块。
• 验收：生成内容未定相不成为正式形仪；克隆授权可撤回；关闭全部多模态后文字相伴完整可用（回归）。

M8 天工阁、叩心与辰正

• 交付：功能 Agent 受托任务（分解/并行/验收，无魂籍）；后台 Run 并发（不占前台槽位）；叩心候选（静默/频率/预算/渠道）；辰正时态感知重实现；删除旧 agent/knocking/time_sense/goal_orchestrator/planner/perception/big_cycle 模块。
• 验收：后台任务不构成第二意识（无身份写入路径）；叩心受总开关与静默约束；不回应不降低关系（无关系副作用断言）。

M9 桌面壳与收口

• 交付：镜匣最小壳（WebView+能力桥+乾坤通道+器谱登记+ updater，tantivy 预留）；Compose/nginx 终态；文档与契约全量核对；发布门证据格式落位（对照发布门与 first-release-scope 逐项检查）。
• 验收：桌面壳零平台密钥、未授契能力被拒、硬急停可用；全量回归（M1–M8 验收自动化套件绿）；docs 五层与代码一致（能力矩阵证据更新完毕）→ 删除本计划文件。

5. 新旧切换纪律

• 旧模块删除时点绑定里程碑（见各条"删除"项），删除前 rg 确认无真实调用点；
• 禁止新旧 API 并存过渡（开发期契约直接重建，无兼容层）；
• 开发数据库随基线重建丢弃，不写数据迁移；
• 每个里程碑一个合并批次，提交信息中文、可追溯到本计划条目（如 M2：镜树归真与采用分离）。

6. 风险与对策

风险	对策
插件化过度设计拖慢主线	Kernel+总线先于插件丰富度；九枢按里程碑逐步装配，M0 只需 stub 插件跑通
神识一次性切换失败	M4 内先双写用量对比再切换；元炁本地端点保证无云密钥也可全链路演示
镜树前端复杂度（局部树图/断线续传）	M2 先交付当前路径阅读流，树图与抽屉分两批；SSE 续传以事件日志重放为保证
全量 1.0 周期长导致中途失衡	里程碑独立验收+能力矩阵滚动更新；任何时点主干可运行
删除旧模块误伤复用资产	删除前核对 §2 复用清单与调用点扫描；infrastructure 资产先重组入 infra/ 再删领域层