c1662fa9d3
- 专题-06 v3:补 chapter(章节容器)/scene(场景卡)/narrative_state(叙事状态模具)三型, 20→23、scope 七值全挂靠;段落不独立建模由 scene 承载(Block=场景/小节级既有拍板); §2.1 检索基座替换合同与演进方向(引擎缝+引擎中立合同,预期纯 Java 自研:PG 向量插件+New-API 嵌入重排); 钉死读取器只依赖 owner api 模块具名端口(服务即 API)与 storage_binding 权力边界(映射非数据通道) - 章节容器证据链:专题-03 L1 早已预设「章节目标」为续写必需输入而章节表无此字段,扩展字段落此欠账 - 架构-02/后端-04/产品-02B/大纲/映射表:引用去硬编码数字防再漂移;评审稿 v0.3 同步 W1=23 项 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
15 KiB
15 KiB
New-Design（新设计）V2 文档大纲（入口）
- 版本：v9
- 更新日期：2026-06-29
- 目标读者：产品 / 架构 / 前端 / 后端 / 文档维护者
- 阅读时间：10–20 分钟
- 边界说明：本文件只负责导航、边界和归属，不重复解释概念；概念解释必须落在对应主文档中。
- 设计 ≠ 进度：design-docs 是设计意图 SSOT（要建成什么），不代表已实现；实现进度见
docs/mvp/进度总账.md（进度 SSOT）+docs/项目功能与进度总览.md（人读全局）+ 覆盖 JSON（接口门机械源）。
目标
- 形成一套按角色拆分、单一归属、可持续维护的设计文档集。
- 明确“产品闭环、系统流程、实现约束”分别由谁负责，不允许多份文档各说各话。
文档集规则（别制造特殊情况）
- 角色前缀 + 扁平结构：文件名即归属，避免目录层级变成垃圾桶。
- 跨文档复用内容只允许“链接 + 一句话摘要”，禁止大段复制粘贴。
- 术语统一：规范数据(Canonical) / 待审层(Shadow) / 作品(Work) / 章节(Chapter) / 文本块(Block) / 元结构定义(MetaSchema) 等，以
架构-02-核心数据结构与双轨模型.md为准。 - 临时改造文档只作为迁移依据；临时文档删除后，正式归属由
产品-*、流程-*、架构-*、前端-*、后端-*承担，不成为长期单一事实源(Single Source of Truth, SSOT)。
工程仓库架构
阶段 7 以后，Muse 工程按四个仓库协作。仓库名是工程落地边界；业务概念、状态机、Schema 和 API 的单一事实源仍按本文档集的 owner 归属执行。
| 仓库 | 来源 / 形态 | 职责 | 主读文档 |
|---|---|---|---|
muse-cloud/ |
fork YunaiV/yudao-cloud |
后端主仓；承接网关、system、infra、framework、任务、文件、权限等 Yudao 基础能力，并补 Muse 的 content、knowledge、ai、market、account 业务模块 | 后端-01、后端-02、后端-03、后端-04、后端-05 |
muse-admin/ |
fork yudao-ui-admin-vben |
管理端；承载 Admin Console 的系统治理、元结构、Prompt / Agent、全局知识、市场治理、用户、权限、审计和质量观察 | 产品-02B、流程-01A、流程-02A、前端-01、后端-05 |
muse-studio/ |
自研用户端，推荐 Next.js / React | 普通用户创作端；承载我的作品、作品工作台、写作台、智能体工作台、知识库工作台、市场和个人中心 | 产品-02C、产品-02D、产品-02E、产品-02F、产品-02G、前端-01、前端-02、前端-03 |
muse-design-docs/ |
当前 design-docs/ 独立化后的设计文档仓 |
产品、架构、流程、前端、后端、专题的设计 SSOT | 00-文档大纲、内容映射表、各正式分册 |
协作约束：
muse-admin/只调用/admin-api/**，不承载普通用户写作台、候选接受或作品知识取舍。muse-studio/只调用/app-api/**，不暴露系统 Prompt、底层 Pipeline、管理员审计或后台配置表。muse-cloud/内部按领域 owner 写事实；/admin-api/**和/app-api/**只是入口不同，不表示两套领域事实。muse-design-docs/只定义目标设计和 owner 归属；实现仓的代码、迁移和测试必须反向对齐这里的正式文档，不能用实现便利反改产品语义。
角色视角导航
| 角色视角 | 先读 | 再读 | 边界 |
|---|---|---|---|
| 管理员控制台(Admin Console) | 产品-02-核心功能与交互边界、架构-01-系统全貌与边界上下文、流程-01A-管理员操作流程、流程-02A-管理员系统处理流程 | 后端-05-统一API契约-v1、前端-01-工程结构与核心依赖 | 管理系统能力、全局知识、权限、审计和评测，不替普通用户做单作品创作取舍。 |
| 普通用户工作区(User Workspace) | 产品-02-核心功能与交互边界、产品-03-用户旅程与操作流程、流程-01B-普通用户操作流程、流程-02B-普通用户系统处理流程 | 前端-01-工程结构与核心依赖、前端-02-编辑器与影子层交互、前端-03-元引擎与动态表单、后端-05-统一API契约-v1 | 包含我的作品(My Works)、单作品的作品工作台(Work Workspace)、写作台、作品规划台、知识与一致性、导入解析、导出交付、记录与用量；不承载管理员配置。 |
| 个人中心(Personal Center) | 产品-02-核心功能与交互边界、前端-01-工程结构与核心依赖、后端-05-统一API契约-v1 | — | 管理个人信息、令牌(Token)使用、配额、套餐、生成记录总览和授权摘要；不承载单作品深层创作或系统后台配置。 |
快速导航（按文档职责）
产品
- 产品-01-产品定位与核心价值
- 产品-02-核心功能与交互边界
- 产品-03-用户旅程与操作流程
- 需要按步骤执行时，按角色阅读：流程-01A-管理员操作流程 / 流程-01B-普通用户操作流程
导入与全书解析相关内容只做归属，不多处重写：
- 产品边界：
产品-02-核心功能与交互边界.md - 管理员操作步骤：
流程-01A-管理员操作流程(操作视角).md - 普通用户操作步骤：
流程-01B-普通用户操作流程(操作视角).md - 管理员系统链路：
流程-02A-管理员系统处理流程(系统视角).md - 普通用户系统链路：
流程-02B-普通用户系统处理流程(系统视角).md - 模型与边界：
架构-02-核心数据结构与双轨模型.md - 接口与事务：
后端-05-统一API契约-v1.md - 前端一致性：
前端-02-编辑器与影子层交互.md
架构
后端
- 后端-01-领域模型与聚合设计
- 后端-02-工程结构与模块职责
- 后端-03-关键流程实现与接口契约
- 后端-04-统一数据库Schema-v1
- 后端-05-统一API契约-v1
- 系统链路参考：
流程-02A-管理员系统处理流程(系统视角).md/流程-02B-普通用户系统处理流程(系统视角).md
前端
流程
专题补充
- 专题-01-正文建议接受(Accept Suggestion)实现规范
- 专题-02-Sudowrite对标与Muse产品取舍
- 专题-03-AI编排上下文与质量评测实现规范
- 专题-05-AI统一交互协议与外部AgentAdapter设计
- 专题-06-元数据驱动的智能体架构——收束「agent = f(作品 + 元数据 + 知识库)」横切架构：元引擎与功能链双枢、三体关系、target type 23 型结构本体、统一创作数据读取器、base 内置机制与拆书通用抽取。
说明：专题文档只负责跨文档收束，不抢走 Schema、状态机和统一 API 的单一归属。
临时件（评审/迁移依据，落定后归并或删除，不作长期 SSOT）
- 临时-01~04（SSE 长任务超时修复 / market-install KB 物化演进）——已于 2026-06-26 归并删除（过程文档落定即清，不作长期 SSOT）：结论落 memory（
muse-ai-generation-sse-timeout-bug、muse-market-kb-d0fork-materialization）+ 各模块.agent+ 1.0.0 交付计划；KB 物化的"共享→D0-fork"决策演进史留 git 历史。 - 临时-05-market-agent物化执行plan（执行版）——临时-04 KB 物化的姊妹方向（agent 版），承临时-02 断点②（智能体 runtime 实体缺失）。拍板已定 ①不 fork、拷配置（agent 无 KB 那类私有泄露向量：version 一经 active 即不可变、运行时不回读发布者私有 prompt、
config即被授权出售的商品本体）②物化成 installed 型独立muse_agent+activemuse_agent_version（config 拷自发布者）+ 改运行时授权门放行。一手代码核验坐实唯一真断点 = 运行时授权门requireVisibleAgent:329-331对 market 来源一律拒（三入口 220/308/315 全经它），槽位闸 A 已放宽（不动）。拆成 A-source（扩临时-04 已落的MarketAssetSourceApi带 config+放行 agent 类型）/ A-materialize（安装侧建 installed agent 拷 config，照搬 KBmaterializeInstalledRefKb形态+幂等+去裸引用+补MuseAgentDO映射 V27 已有source_market_asset_id列）/ A-runtime（改授权门=trust boundary，放行 installed 型+本人+授权有效，他人/无授权/裸引用必拒，负路测命门）/ A-naming（agent_type 命名收口）/ A-verify（真 PG IT+e2e+授权门负路）五单元；含 config 跨 BC 读取途径决策（market 反调 ai vs ai 自读）+ 拷 vs 引用 prompt+命名最终值+DDL 判定（不需新迁移）。待人类拍决策点后执行；配套人读图.html。owner 边界引 临时-02/04/架构-02/ADR-017/020，不重定义。
输入 / 输出闭环（你写的东西要能被别人用）
| 文档 | 输入（来自哪里） | 输出（给谁用） |
|---|---|---|
| 产品-01 | 业务目标 / 用户画像 / 产品战略 | 产品定位、价值主张、产品闭环、非目标 |
| 产品-02 | 需求 / 约束 / 交互取舍 | 功能边界、决策模型、失败反馈边界 |
| 产品-03 | 用户旅程 / 长期使用方式 | 单次创作闭环、长期作品闭环、关键决策点 |
| 架构-01 | 需求边界 / 有界上下文 | 系统全貌、上下文边界、协作规则 |
| 架构-02 | 核心概念 / 数据结构 | 双轨模型、数据不变式、模型级规则 |
| 架构-03 | 关键权衡 | 架构决策记录与原则 |
| 架构-04 | 结构定义 / 接口决策收束 | 生命周期、表级约束、端点前后置条件 |
| 后端-01 | 架构模型 / 有界上下文规则 | 聚合、实体、不变式 |
| 后端-02 | 工程约束 / 交付方式 | 模块职责、目录结构、依赖方向 |
| 后端-03 | 系统流程 / 外部集成 | 事务边界、事件边界、调用链路 |
| 后端-04 | 双轨模型与接口基线 | 数据库表结构、索引、迁移约束 |
| 后端-05 | 统一资源语义 | API 契约、异步模式、错误模型 |
| 前端-01 | 产品边界 / 工程约束 | 前端结构、依赖、目录策略 |
| 前端-02 | 双轨交互规则 | 编辑器与待审层协作、回滚与刷新策略 |
| 前端-03 | 元结构驱动规则 | 动态表单与渲染链路 |
| 流程-01A | 管理员操作步骤 / 决策点 | 管理员配置、治理、审核、回滚、观察和高危处理路径 |
| 流程-01B | 普通用户操作步骤 / 决策点 | 普通用户创作、资产使用、市场获取、账户处理、可观察反馈和恢复路径 |
| 流程-02A | 管理员系统链路 | 管理员配置发布、治理、权限、New-API、任务和审计处理 |
| 流程-02B | 普通用户系统链路 | 普通用户创作、候选、知识、资产、handoff、任务和失败恢复处理 |
| 专题-01 | 已确认的跨文档决策 | Accept Suggestion 的统一收束稿 |
| 专题-02 | 外部竞品调研 / 产品取舍判断 | Sudowrite 对标、Muse 优劣势、该学什么与不该学什么 |
| 专题-03 | 已收敛为目标设计的 AI 编排缺口 | RAGFlow、Graph Query Provider、上下文组装、Agent/Prompt、Risk Routing、质量评测和默认超级管理员初始化的跨文档实现规范 |
| 专题-05 | Dify / AgentScope / New-API 等外部运行时接入诉求 | AI 统一交互协议、provider adapter、系统 Agent 引用 Dify app/workflow、凭据与审计边界 |
| (原 doc/dev/* 规划未落地) | 职责已由实际文档承担 | 路线图/阶段 → docs/mvp/进度总账.md；验收门禁 → 覆盖 JSON + verification 规则；真实现状差距 → docs/项目功能与进度总览.md |
单一归属清单（强制）
- 双轨模型：
架构-02-核心数据结构与双轨模型.md - 有界上下文与协作规则：
架构-01-系统全貌与边界上下文.md - 架构决策记录：
架构-03-关键决策与原则(ADR).md - 生命周期与状态机：
架构-04-状态机与约束清单.md - 后端模块职责：
后端-02-工程结构与模块职责.md - 产品旅程与长期闭环：
产品-03-用户旅程与操作流程.md - 系统处理流程：
流程-02A-管理员系统处理流程(系统视角).md/流程-02B-普通用户系统处理流程(系统视角).md - AI 编排、检索上下文和质量评测跨文档合同：
专题-03-AI编排上下文与质量评测实现规范.md - AI 外部运行时统一协议与 Adapter：
专题-05-AI统一交互协议与外部AgentAdapter设计.md - 统一数据库表结构：
后端-04-统一数据库Schema-v1.md - 统一接口契约：
后端-05-统一API契约-v1.md - 产品形态：
产品-01/02/03+架构-01；阶段路线图/验收门禁：docs/mvp/进度总账.md+ 覆盖 JSON（原doc/dev/01、doc/dev/09规划未落地）
迁移说明
- 映射表：
内容映射表.md - 历史文档源：
doc/new-design/（仅保留参考，不再作为当前设计单一事实源） - 临时改造文档：已于 2026-06-14 完成改造并删除(内容已落入
产品-*/架构-*/流程-*等正式分册;完整历史见 git)。