# New-Design（新设计）V2 文档大纲（入口）

- 版本：v10
- 更新日期：2026-07-17
- 目标读者：产品 / 架构 / 前端 / 后端 / 文档维护者
- 阅读时间：10–20 分钟
- 边界说明：本文件只负责导航、边界和归属，不重复解释概念；概念解释必须落在对应主文档中。
- **设计 ≠ 进度**：design-docs 是**设计意图 SSOT**（要建成什么），**不代表已实现**；实现进度见 [`docs/mvp/进度总账.md`](../docs/mvp/进度总账.md)（进度 SSOT）+ [`docs/项目功能与进度总览.md`](../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-核心功能与交互边界](产品-02-核心功能与交互边界.md)、[架构-01-系统全貌与边界上下文](架构-01-系统全貌与边界上下文.md)、[流程-01A-管理员操作流程](流程-01A-管理员操作流程(操作视角).md)、[流程-02A-管理员系统处理流程](流程-02A-管理员系统处理流程(系统视角).md) | [后端-05-统一API契约-v1](后端-05-统一API契约-v1.md)、[前端-01-工程结构与核心依赖](前端-01-工程结构与核心依赖.md) | 管理系统能力、全局知识、权限、审计和评测，不替普通用户做单作品创作取舍。 |
| 普通用户工作区(User Workspace) | [产品-02-核心功能与交互边界](产品-02-核心功能与交互边界.md)、[产品-03-用户旅程与操作流程](产品-03-用户旅程与操作流程.md)、[流程-01B-普通用户操作流程](流程-01B-普通用户操作流程(操作视角).md)、[流程-02B-普通用户系统处理流程](流程-02B-普通用户系统处理流程(系统视角).md) | [前端-01-工程结构与核心依赖](前端-01-工程结构与核心依赖.md)、[前端-02-编辑器与影子层交互](前端-02-编辑器与影子层交互.md)、[前端-03-元引擎与动态表单](前端-03-元引擎与动态表单.md)、[后端-05-统一API契约-v1](后端-05-统一API契约-v1.md) | 包含我的作品(My Works)、单作品的作品工作台(Work Workspace)、写作台、作品规划台、知识与一致性、导入解析、导出交付、记录与用量；不承载管理员配置。 |
| 个人中心(Personal Center) | [产品-02-核心功能与交互边界](产品-02-核心功能与交互边界.md)、[前端-01-工程结构与核心依赖](前端-01-工程结构与核心依赖.md)、[后端-05-统一API契约-v1](后端-05-统一API契约-v1.md) | — | 管理个人信息、令牌(Token)使用、配额、套餐、生成记录总览和授权摘要；不承载单作品深层创作或系统后台配置。 |

## 快速导航（按文档职责）

### 产品

1. [产品-01-产品定位与核心价值](产品-01-产品定位与核心价值.md)
2. [产品-02-核心功能与交互边界](产品-02-核心功能与交互边界.md)
3. [产品-03-用户旅程与操作流程](产品-03-用户旅程与操作流程.md)
4. 需要按步骤执行时，按角色阅读：[流程-01A-管理员操作流程](流程-01A-管理员操作流程(操作视角).md) / [流程-01B-普通用户操作流程](流程-01B-普通用户操作流程(操作视角).md)

导入与全书解析相关内容只做归属，不多处重写：

- 产品边界：`产品-02-核心功能与交互边界.md`
- 管理员操作步骤：`流程-01A-管理员操作流程(操作视角).md`
- 普通用户操作步骤：`流程-01B-普通用户操作流程(操作视角).md`
- 管理员系统链路：`流程-02A-管理员系统处理流程(系统视角).md`
- 普通用户系统链路：`流程-02B-普通用户系统处理流程(系统视角).md`
- 模型与边界：`架构-02-核心数据结构与双轨模型.md`
- 接口与事务：`后端-05-统一API契约-v1.md`
- 前端一致性：`前端-02-编辑器与影子层交互.md`

### 架构

1. [架构-01-系统全貌与边界上下文](架构-01-系统全貌与边界上下文.md)
2. [架构-02-核心数据结构与双轨模型](架构-02-核心数据结构与双轨模型.md)
3. [架构-03-关键决策与原则(ADR)](架构-03-关键决策与原则(ADR).md)
4. [架构-04-状态机与约束清单](架构-04-状态机与约束清单.md)

### 后端

1. [后端-01-领域模型与聚合设计](后端-01-领域模型与聚合设计.md)
2. [后端-02-工程结构与模块职责](后端-02-工程结构与模块职责.md)
3. [后端-03-关键流程实现与接口契约](后端-03-关键流程实现与接口契约.md)
4. [后端-04-统一数据库Schema-v1](后端-04-统一数据库Schema-v1.md)
5. [后端-05-统一API契约-v1](后端-05-统一API契约-v1.md)
6. 系统链路参考：`流程-02A-管理员系统处理流程(系统视角).md` / `流程-02B-普通用户系统处理流程(系统视角).md`

### 前端

1. [前端-01-工程结构与核心依赖](前端-01-工程结构与核心依赖.md)
2. [前端-02-编辑器与影子层交互](前端-02-编辑器与影子层交互.md)
3. [前端-03-元引擎与动态表单](前端-03-元引擎与动态表单.md)

### 流程

- [流程-01A-管理员操作流程(操作视角)](流程-01A-管理员操作流程(操作视角).md)
- [流程-01B-普通用户操作流程(操作视角)](流程-01B-普通用户操作流程(操作视角).md)
- [流程-02A-管理员系统处理流程(系统视角)](流程-02A-管理员系统处理流程(系统视角).md)
- [流程-02B-普通用户系统处理流程(系统视角)](流程-02B-普通用户系统处理流程(系统视角).md)

### 专题补充

- [专题-01-正文建议接受(Accept Suggestion)实现规范](专题-01-正文建议接受(Accept%20Suggestion)实现规范.md)
- [专题-02-Sudowrite对标与Muse产品取舍](专题-02-Sudowrite对标与Muse产品取舍.md)
- [专题-03-AI编排上下文与质量评测实现规范](专题-03-AI编排上下文与质量评测实现规范.md)
- [专题-04-生成质量门控与创作健康度设计方案](专题-04-生成质量门控与创作健康度设计方案.md)
- [专题-05-AI统一交互协议与外部AgentAdapter设计](专题-05-AI统一交互协议与外部AgentAdapter设计.md)
- [专题-06-元数据驱动的智能体架构](专题-06-元数据驱动的智能体架构.md)——收束「agent = f(作品 + 元数据 + 知识库)」横切架构：元引擎与功能链双枢、三体关系、target type 23 型结构本体、统一创作数据读取器、base 内置机制与拆书通用抽取。
- [专题-07-知识消费契约与质量闭环](专题-07-知识消费契约与质量闭环.md)——收束「知识效用」横切主线：消费选择契约（按用途默认合同与注入视图）、知识质量三性（可命中/可行动/可持续）、回放评测（参考书=标准答案）、长线进度消费语义（演变历程三期消费）。
- [专题-08-自动化测试方案](专题-08-自动化测试方案.md)——收束「测试可判定性」横切主线：四层测试金字塔、确定性/语义分界判据、语义评测方法论（双盲评委/对照实验 Gate B 范式/回放评测）、测试可判定性合同、已拍决策的测试合同。不重定义状态机/Schema/API/质量维度，只引用各 owner。

说明：专题文档只负责跨文档收束，不抢走 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 交付计划](../../docs/mvp/1.0.0-交付计划.md)；KB 物化的"共享→D0-fork"决策演进史留 git 历史。
- [临时-05-market-agent物化执行plan](临时-05-market-agent物化执行plan.md)（执行版）——临时-04 KB 物化的**姊妹方向（agent 版）**，承临时-02 断点②（智能体 runtime 实体缺失）。拍板已定 **①不 fork、拷配置**（agent 无 KB 那类私有泄露向量：version 一经 active 即不可变、运行时不回读发布者私有 prompt、`config` 即被授权出售的商品本体）**②物化成 installed 型独立 `muse_agent`+active `muse_agent_version`（config 拷自发布者）+ 改运行时授权门放行**。一手代码核验坐实唯一真断点 = 运行时授权门 `requireVisibleAgent:329-331` 对 market 来源一律拒（三入口 220/308/315 全经它），槽位闸 A 已放宽（不动）。拆成 A-source（**扩**临时-04 已落的 `MarketAssetSourceApi` 带 config+放行 agent 类型）/ A-materialize（安装侧建 installed agent 拷 config，照搬 KB `materializeInstalledRefKb` 形态+幂等+去裸引用+补 `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`
- 知识消费选择契约、知识质量三性、回放评测、长线进度消费语义：`专题-07-知识消费契约与质量闭环.md`
- 测试金字塔分层、确定性/语义分界判据、语义评测方法论、测试可判定性合同：`专题-08-自动化测试方案.md`
- AI 外部运行时统一协议与 Adapter：`专题-05-AI统一交互协议与外部AgentAdapter设计.md`
- 统一数据库表结构：`后端-04-统一数据库Schema-v1.md`
- 统一接口契约：`后端-05-统一API契约-v1.md`
- 产品形态：`产品-01/02/03` + `架构-01`；阶段路线图/验收门禁：[`docs/mvp/进度总账.md`](../docs/mvp/进度总账.md) + 覆盖 JSON（原 `doc/dev/01`、`doc/dev/09` 规划未落地）

## 迁移说明

- 映射表：`内容映射表.md`
- 历史文档源：`doc/new-design/`（仅保留参考，不再作为当前设计单一事实源）
- 临时改造文档：已于 2026-06-14 完成改造并删除(内容已落入 `产品-*`/`架构-*`/`流程-*` 等正式分册;完整历史见 git)。