oh-my-muse/design-docs/架构-03-关键决策与原则(ADR).md

架构-03：关键决策与原则（架构决策记录(ADR)）

• 版本：v13
• 更新日期：2026-07-09
• 目标读者：架构/前端/后端/产品
• 阅读时间：30-45 分钟
• 边界说明：这里只收敛架构原则和 ADR；工程结构、表结构、接口、状态机分别归属 后端-02、后端-04、后端-05 和 架构-04。本文件描述目标架构决策，不代表当前代码都已实现。
• 变更记录：v13（2026-07-09）新增 ADR-022（系统功能链定义归属元引擎·案 A）与 ADR-023（双轨 Canonical 入口增补·管理员确认系统级知识草稿），并更新 §2 结论段。

1. 架构原则（可执行）

1.1 模块化单体优先，边界先于服务拆分

• 默认采用模块化单体：清晰边界、本地事务、低部署成本、可调试。
• 只有当痛点真实且可量化时才拆服务，例如 AI 能力独立扩展、团队边界稳定或外部依赖需要隔离。
• 即使拆外部服务，Muse 的业务事实源和用户确认边界仍必须回到 Muse。

1.2 管理员控制系统能力，普通用户控制作品事实

• 管理员(Admin)通过管理员控制台(Admin Console)治理系统模板、Prompt、Agent、全局知识和权限。
• 普通用户(User)通过用户工作区(User Workspace)写作、规划、确认知识和查看用量。
• 管理员不替用户做单个作品的创作取舍；普通用户不直接操作系统后台配置。

1.3 数据主权：待审层(Shadow)先行，规范数据(Canonical)后置

• 人工智能(AI)只产出待审层(Shadow)，用户决定是否进入规范数据(Canonical)。
• 系统可以提示风险、冲突和参考来源，但不能替用户做不可逆决定。
• 来源快照(Source Snapshot)、归档层(Archive)和审计记录是用户可撤销、可追溯的基础。

1.4 数据结构优先，不按 UI 面板造模型

• 先定义模型边界、不变式和状态机，再设计页面流程。
• 作品规划台(Planning Desk)是产品入口，不是每个面板一张表。
• 规划能力应复用管理员治理的元结构定义(MetaSchema)、世界状态(World State)、叙事状态(Narrative State)、作品(Work)、章节(Chapter)和文本块(Block)边界。

2. ADR 索引

每条 架构决策记录(ADR)都必须包含：上下文(Context) / 决策(Decision) / 替代方案(Alternatives) / 后果(Consequences)。这里只保留决策要点，细节不要复制到各处。

ADR-001：模块化单体 vs 微服务

• 上下文(Context)：早期阶段、团队小、边界仍在探索，部署与调试成本必须低。
• 决策(Decision)：采用模块化单体，内部通过模块边界、接口隔离和事件解耦维护职责。
• 替代方案(Alternatives)：直接微服务化会放大部署、事务、观测和跨服务调试成本。
• 后果(Consequences)：开发和事务更简单；代价是必须持续维护边界，不能把模块化单体写成大泥球。
• 参考落地：后端-02-工程结构与模块职责.md

ADR-002：AI 能力通过外部 Agent 服务提供

• 上下文(Context)：文本生成、实体提取、知识校验、规划和检索等能力需要快速演进，完全放在 Java 内部会限制生态和迭代速度。
• 决策(Decision)：AI 能力通过受控接入的外部 Agent runtime provider 提供。Muse 后端负责权限、上下文组装、Agent 调用、结果消费和待审层(Shadow)写入。
• 替代方案(Alternatives)：全部写入 Muse Java 进程会降低灵活性；让 Agent 服务直接写数据库会破坏事实源和权限边界。
• 后果(Consequences)：AI 能力可独立演进；代价是新增外部运行时边界，provider 输出只能经 Muse adapter、审计、质量门控和 Shadow 流程消费，不能被视为可直接写事实源的可信服务。
• 参考落地：后端-03-关键流程实现与接口契约.md

ADR-003：动态属性采用 JSONB，而不是 EAV

• 上下文(Context)：实体属性高度动态，但查询、变更追溯和投影仍必须可用。
• 决策(Decision)：用 二进制 JSON(JSONB) 当前快照 + 属性级变更日志表达动态属性。
• 替代方案(Alternatives)：实体属性值模型(EAV)会让查询和约束复杂度失控。
• 后果(Consequences)：查询与演进成本更低；代价是更依赖数据库能力和索引策略。
• 参考落地：后端-04-统一数据库Schema-v1.md

ADR-004：富文本编辑器选择以 Block 级自定义能力优先

• 上下文(Context)：Muse 需要段落级文本块(Block)，并携带 id、revision、状态、实体高亮和标注。
• 决策(Decision)：选择支持结构定义(Schema)和节点扩展能力强的编辑器体系。
• 替代方案(Alternatives)：纯 Markdown 或普通富文本编辑器难以承载块级冲突、候选合并和知识标注。
• 后果(Consequences)：可实现强结构与扩展；代价是基础复杂度和学习成本更高。
• 参考落地：前端-02-编辑器与影子层交互.md

ADR-005：向量检索采用 RAGFlow，替代 pgvector

• 上下文(Context)：上下文组装需要文档管理、分块策略、混合检索和语义检索能力，简单向量相似度不足。
• 决策(Decision)：使用 检索引擎(RAGFlow)作为语义检索基座，PostgreSQL 不保存 embedding 作为主检索方案。
• 替代方案(Alternatives)：pgvector 方案部署简单，但检索能力不足；完全自建检索引擎成本过高。
• 后果(Consequences)：检索质量与灵活性提升；代价是新增外部依赖，必须有降级和重建投影路径。
• 参考落地：muse-cloud/muse-module-knowledge（RAGFlow 真实集成，见 ADR-006 与知识模块 .agent；原 doc/dev/03 规划未落地）

ADR-006：图查询依赖 RAGFlow GraphRAG，不自建图存储（已决策）

• 上下文(Context)：需要判断 RAGFlow GraphRAG 是否足以覆盖时间线、因果链、实体演变等查询。
• 决策(Decision)：依赖 RAGFlow GraphRAG 提供图查询能力，不自建 Neo4j 或其他独立图存储。
• 替代方案(Alternatives)：引入 Neo4j 会增加运维和同步复杂度；完全放弃图查询会削弱长篇一致性检查。
• 后果(Consequences)：减少运维复杂度和外部依赖；代价是图查询能力受限于 RAGFlow GraphRAG 的演进节奏。如未来 RAGFlow GraphRAG 能力不足，可重新评估独立图存储方案。
• 参考落地：muse-cloud/muse-module-knowledge（RAGFlow 真实集成，见 ADR-006 与知识模块 .agent；原 doc/dev/03 规划未落地）

ADR-007：Block 使用 UUID

• 上下文(Context)：文本块(Block)需要为离线、多端、复制粘贴、候选合并和未来协作预留空间。
• 决策(Decision)：使用 唯一标识(UUID)作为 Block 的全局标识。
• 替代方案(Alternatives)：自增 ID 更省空间，但客户端生成和离线合并能力更弱。
• 后果(Consequences)：同步与合并更简单；代价是索引和存储上不如自增友好。
• 参考落地：架构-02-核心数据结构与双轨模型.md

ADR-008：管理员控制台是独立系统入口

• 上下文(Context)：新产品形态明确拆分管理员(Admin)和普通用户(User)。管理员负责系统能力治理，普通用户负责作品创作。
• 决策(Decision)：管理员控制台(Admin Console)作为独立上层入口存在，承载模板、Prompt、Agent、全局知识库、访问策略、New-API 同步、任务治理、质量评估、用户与审计。
• 替代方案(Alternatives)：把这些能力塞进普通用户作品工作台会暴露后台概念，破坏低认知负担，也会让权限边界难以验证。
• 后果(Consequences)：前端信息架构、权限模型、审计视图必须分角色；管理员配置影响普通用户生成链路时必须通过可追溯配置快照生效。
• 参考落地：架构-01-系统全貌与边界上下文.md、流程-02A-管理员系统处理流程(系统视角).md、流程-02B-普通用户系统处理流程(系统视角).md

ADR-009：模型网关 New-API 职责边界

• 上下文(Context)：New-API 已负责模型供应商、模型路由、用户分组限流、成本策略和模型消耗日志。Muse 需要和自身用户、作品、授权和配额联动。
• 决策(Decision)：New-API 继续负责模型供应商、路由、分组、限流、成本和消耗日志；Muse 只负责用户生命周期相关同步，以及必要的分组、配额、套餐和绑定状态调整入口。
• 替代方案(Alternatives)：Muse 重复实现模型网关会扩大系统复杂度；完全不记录同步状态会让失败不可恢复。
• 后果(Consequences)：New-API 同步必须幂等、可重试、可审计；Muse 的普通用户用量反馈和管理员审计可以引用同步结果，但不把 New-API 成本日志复制成新的权威来源。
• 参考落地：流程-02A-管理员系统处理流程(系统视角).md、流程-02B-普通用户系统处理流程(系统视角).md、架构-04-状态机与约束清单.md

ADR-010：全局知识库与局域知识库分层

• 上下文(Context)：管理员维护的写作方法、体裁规则、平台规范和公共资料，与单个作品沉淀的人物、关系、事件和叙事状态不是同一类资产。
• 决策(Decision)：全局知识库(Global Knowledge Base)归管理员维护和授权；局域知识库(Local Knowledge Base)归单个作品自动维护。普通用户看到的是用户可见投影(User-visible Projection)，不是系统内部完整知识。
• 替代方案(Alternatives)：混成一个知识库会导致普通用户误改系统资料，也会让全局资料未经授权进入作品生成或检索。
• 后果(Consequences)：生成、检索、导出和一致性检查必须标明来源；全局资料不自动进入作品正式知识，局域知识不跨作品共享正式事实。
• 参考落地：架构-01-系统全貌与边界上下文.md、架构-02-核心数据结构与双轨模型.md

ADR-011：作品规划台复用已有模型边界

• 上下文(Context)：作品规划台需要支持作品方向、作品结构、世界实体、事件时间线、角色弧光、剧情结构、章节叙事规划、张力节奏、叙事策略、文风与质量检查。
• 决策(Decision)：这些规划维度映射到元结构定义(MetaSchema)、世界状态(World State)、叙事状态(Narrative State)、作品(Work)、章节(Chapter)和文本块(Block)，不为每个 UI 面板新建孤立模型。
• 替代方案(Alternatives)：按 UI 面板建模会形成重复事实源，导致规划、正文、知识和生成上下文互相打架。
• 后果(Consequences)：前端可以按创作语言组织入口，但后端和架构文档必须保持模型归属；新增规划维度先判断落点，而不是先建表。
• 参考落地：架构-02-核心数据结构与双轨模型.md

ADR-012：小说场景(Scene)暂不作为独立一级模型

• 上下文(Context)：产品可以使用情节节拍、场景推进、章节目标等作者语言，但当前正式模型更稳定的骨架是作品、章节、文本块、世界状态和叙事状态。
• 决策(Decision)：当前阶段不引入小说场景(Scene)作为独立一级模型，也不采用 Outline / Scene 作为并列一级模型。近程叙事控制归入章节叙事规划，并由 Chapter、Block 上下文和 Narrative State(chapter)承载。
• 替代方案(Alternatives)：直接引入 Scene 会带来章节顺序、文本块归属、解析确认、导出和知识追溯的连锁改造；继续使用章节叙事规划可以先满足产品语言和生成约束。
• 后果(Consequences)：所有文档可以写“情节节拍 / 场景推进”，但不能假定已有 Scene 表、Scene API 或 Scene 状态机。未来若需要独立模型，必须新增 ADR 并同步后端、前端和状态机。
• 参考落地：架构-02-核心数据结构与双轨模型.md

ADR-013：Sa-Token 作为认证授权基座

• 上下文(Context)：管理员控制台需要稳定的登录认证、角色权限、接口鉴权、会话与 Token 生命周期、当前用户上下文和基础审计上下文。现有自研 Bearer Token 能力已经能支撑局部 current user，但继续扩展会导致认证、权限和当前用户解析散落在多处。
• 决策(Decision)：引入 Sa-Token 作为 Muse 的认证授权基座；现有自研 Bearer Token 能力逐步收敛为 Sa-Token 适配层。Sa-Token 负责 Authentication(登录认证)、RBAC(角色权限)、接口鉴权、会话、Token 生命周期、管理员接口保护、当前用户上下文和基础审计上下文。
• 替代方案(Alternatives)：继续扩展自研 Token 会重复造轮子；引入 Yudao / RuoYi 完整后台系统会把通用平台能力带进 Muse，扩大边界并冲击现有产品架构。
• 后果(Consequences)：Muse 需要补最小 RBAC 数据模型、默认超级管理员初始化、登录/登出/刷新/me API、前端登录状态管理和权限测试；但 Sa-Token 不决定作品正文、知识草稿或 AI 候选是否进入 Canonical(规范数据)，这些仍由 Muse 的 Shadow -> Canonical 业务规则控制。系统任务必须用明确服务身份，不复用普通用户权限绕过确认。
• 更新说明(Update)：阶段 7 已选择 yudao-cloud fork 作为后端工程基座时，关于“不引入 Yudao / RuoYi 完整后台系统”的实现取舍由 ADR-014 supersede；本 ADR 保留为认证授权边界的历史背景和 Sa-Token 约束。
• 参考落地：后端-04-统一数据库Schema-v1.md、后端-05-统一API契约-v1.md、前端-01-工程结构与核心依赖.md

ADR-014：阶段 7 后端基座采用 yudao-cloud fork，但 Muse 领域 owner 不跟随 Yudao 模块

• 上下文(Context)：阶段 7 需要承接后台工程结构、权限基座、代码生成、审计、任务和通用管理能力。yudao-cloud fork 可以降低基础设施成本，但其通用后台模块不等于 Muse 的产品领域边界。
• 决策(Decision)：允许以 yudao-cloud fork 作为工程基座和过渡物理模块来源；Muse 的逻辑 owner、facade、状态机和写入边界仍以 架构-01/02/04 定义的 BC 为准。物理表或代码暂落 yudao-module-ai、yudao-module-system、Content 旧模块时，必须写明过渡映射，不能改变 MetaSchema、Agent、Handoff、Parse Job、Source / Authorization 的 authority。
• 替代方案(Alternatives)：完全不用 yudao-cloud 会增加基础能力建设成本；反向让 Yudao/RuoYi 通用后台模型接管 Muse 领域，会制造普通后台表 owner 与 Muse 创作领域 owner 的冲突。
• 后果(Consequences)：后端文档必须区分”物理模块落点”和”逻辑 owner”。MetaSchema 独立为 MetaSchema BC（见 ADR-016）；Agent、Tool Grant、Runtime Permission Envelope 仍由 Agent authority 与 Security facade 控制；AI runtime 不得自授权；Market 只发起来源侧 handoff；Parse Job / Chapter Parse Result 归 AI Orchestration；Knowledge Draft 只在章节审阅确认后由 Knowledge 创建。
• Supersedes：仅 supersede ADR-013 中“避免引入 Yudao / RuoYi full backend”的工程基座取舍，不 supersede Sa-Token、Shadow -> Canonical 和系统任务服务身份约束。

ADR-015：逻辑 owner 优先于物理表、代码模块和页面入口

• 上下文(Context)：阶段 7 以后同一对象可能因为 yudao-cloud fork、旧模块兼容或读模型性能，被临时放在非目标模块；页面也会跨多个 BC 组合能力。
• 决策(Decision)：Muse 以逻辑 owner 作为唯一写入 authority。物理表、代码包、worker、页面入口和读模型只能承载、投影或消费 owner 数据，不能反向获得写入权。
• 替代方案(Alternatives)：按物理表所在模块决定 owner 会让 Content 接管 MetaSchema、AI runtime 自批 Tool Grant、Market 持有目标 Precheck、Personal Center 反写资产事实，最终形成多事实源。
• 后果(Consequences)：所有跨 BC 写入必须走 owner facade。Source / Authorization 必须通过事件、快照和传播状态连接各 BC；来源状态变化不得自动改写 Canonical。后端阶段如采用过渡模块，必须在 Schema/API 文档中标注逻辑 owner、写入 facade、消费方和迁移路径。

ADR-016：Governance 拆散——按消费者归属拆散，不保留 Governance 聚合模块

• 上下文(Context)：原 Admin/Governance BC 聚合了 MetaSchema、保护节点、质量策略、市场治理等多种职责，消费者分散在不同模块。聚合导致模块边界模糊，变更影响面过大。
• 决策(Decision)：按消费者归属拆散原 Governance 聚合模块：MetaSchema 独立为 MetaSchema BC；Protection Node 和 Quality Policy 归入 AI Orchestration BC（grant 包）；市场治理（下架/召回/申诉）归入 Marketplace/Asset BC（admin 包）。Admin/Governance 只保留系统功能链路、开放槽位和系统 Prompt 等纯系统配置职责。
• 替代方案(Alternatives)：保留 Governance 聚合模块会让不同消费者的变更耦合在一起，增加协调成本；完全打散到各消费者模块会丢失系统配置的统一治理入口。
• 后果(Consequences)：MetaSchema 有独立演进节奏，admin 写入全局定义，用户可在作品级覆盖扩展字段，业务模块通过 facade-api 只读消费。AI 模块通过包级隔离（grant 包 + ArchUnit）管理 Protection Node 和 Quality Policy，grant 包只暴露给 admin-api 调用链路，runtime 包只读。市场治理由 Marketplace/Asset 的 admin 包承载，与市场资产生命周期紧密关联。

ADR-017：Source 传播模式——事件驱动各模块自治，预留集中式演进

• 上下文(Context)：来源状态变化（撤权、下架、召回、版本变化等）需要传播到候选、草稿、绑定、安装、运行任务、导出和个人中心等多个消费方。需要选择传播架构。
• 决策(Decision)：采用事件驱动 + 各模块自治模式。来源 owner 发出 Source Status Event，各消费模块监听事件并自行处理反应逻辑（标记 disabled、作废未确认对象、失效凭证等）。不需要独立 source 模块。预留集中式 worker 演进路径。
• 替代方案(Alternatives)：集中式 worker 统一处理所有传播目标，优点是传播逻辑集中可观测，缺点是 worker 需要了解所有消费方的业务语义，形成上帝模块。独立 source 模块会增加模块间调用复杂度。
• 后果(Consequences)：各模块对来源变化的响应逻辑内聚在自身边界内，降低耦合。Source Snapshot 存储在独立 source_snapshot 表，各模块分散写入，DDL 放 infra 层统一管理。来源变化时各模块直接决策 active 或 disabled，不使用中间 needs_recheck 状态。未来如传播可观测性不足或一致性要求提高，可演进为集中式 worker + 事件溯源。

ADR-018：Candidate Envelope 简化——去掉独立 Envelope 概念

• 上下文(Context)：原设计中 Candidate Decision Envelope 封装了来源、权限、合规、质量和风险路由结果的决策快照，作为候选接受的硬闸门。实践中 Envelope 增加了概念复杂度和实现成本。
• 决策(Decision)：去掉独立 Candidate Decision Envelope 概念。候选表直接记录创建时的来源版本（source version、authorization snapshot），接受时实时对比当前来源状态即可。质量门控、输出合规、静态检查等校验在接受时同步执行，不需要预先封装为独立 Envelope 对象。
• 替代方案(Alternatives)：保留 Envelope 可以缓存决策结果避免重复计算，但增加了过期管理、版本匹配和重算逻辑的复杂度。
• 后果(Consequences)：候选接受流程简化为：校验候选存在且未过期 -> 实时对比来源版本与当前状态 -> 执行质量/合规/静态检查 -> 写入正文。减少一个中间概念和对应的状态管理。代价是每次接受都需要实时校验，不能复用缓存的决策结果。

ADR-019：导出/导入文件交付——稳定存储路径字节代理 + 失败关闭安全姿态

• 上下文(Context)：导出包(Export Package)、导入文件存放在私有对象存储桶。私有桶签发的签名 URL 会过期、随配置漂移，且把可被外部猜测/枚举的对象标识暴露给客户端，存在 IDOR 与跨主体越权读取风险。导入解析允许用户提供外部文件来源，存在 SSRF 风险；阶段内尚未接入扫描器，但不能因此默认放行未扫描文件。
• 决策(Decision)：
  • 导出/导入文件下载一律走后端字节代理(byte-proxy)，并以**稳定存储路径(stable storage path)**作为取流键，不向客户端签发签名 URL。存储对象按租户/用户命名空间隔离，下载凭证只解析 owner 范围内的稳定路径。
  • 导入解析(import inspect)对外部来源强制 SSRF 白名单(allowlist)，并以**服务端权威的扫描状态(server-authoritative scanStatus)**为准、失败关闭(fail-closed)；扫描器未接入前，所有导入按 scan_blocked 处理，不创建后续解析任务。
  • 账户导出(Account export)在 Account BC 内组装本人数据，按脱敏级别(standard / strict)处理；未知级别按 strict 失败关闭，再经字节代理下载。
• 替代方案(Alternatives)：直接返回对象存储签名 URL 部署简单，但在私有桶下会过期/漂移并暴露可枚举对象标识，扩大 IDOR 面；信任客户端自报扫描结果或默认放行未扫描文件会破坏内容安全边界；导出时跨 BC 直接读取他人原始数据会破坏 owner 隔离与脱敏边界。
• 后果(Consequences)：下载链路必须由后端持有存储凭据并按路径取流，运维需保证字节代理可用与限流；扫描器接入前导入默认阻断，需向用户解释 scan_blocked 并提供后续放行路径；脱敏级别必须显式声明，未知即按最严处理。模型不变式见 架构-02-核心数据结构与双轨模型.md（Download Credential / Export Package）。
• 参考落地：后端-03-关键流程实现与接口契约.md、后端-05-统一API契约-v1.md

ADR-020：授权快照 id 承载类型——统一为跨系统稳定字符串标识(VARCHAR)

• 上下文(Context)：ADR-018 确定候选表直接记录创建时的 authorization snapshot、接受时实时对比，但没有就该快照 id 的物理承载类型拍板。实现中两阶段发生漂移：AI 候选表(muse_ai_suggestion)与内容归因表(muse_content_block_source_attribution)的 authorization_snapshot_id 列早期建为 BIGINT；而 Agent Runtime Permission Envelope（ADR-016 保留的概念，区别于 ADR-018 去掉的 Candidate Decision Envelope）自本地安全投影(LocalSecurity)起，其标识即为字符串形态(rpe-local-<uuid>)。BIGINT 列承载不了字符串 envelope，导致真实生成的候选该列恒空、接受门禁恒拒，AI 生成→采纳链路在采纳段断裂。后端-04 已明确"业务 ID 对外按 string、不得把数据库主键当产品合同、需跨系统稳定暴露则补 public_id/biz_no"，但对外契约一度出现 string 与 integer 并存的分歧。
• 决策(Decision)：授权快照 id（及同源 source snapshot id）的业务标识语义统一为跨系统稳定字符串标识(biz_no 形态)，物理列类型 VARCHAR(128)，承载 runtime permission envelope 等字符串授权快照标识。这不与"物理主键用 Long/雪花"冲突：物理自增主键仍是 Long，授权快照 id 是被业务表引用的业务标识/外键语义，本就应对外按 string——VARCHAR 是对该约定的落地而非违背。各业务表(AI 候选、内容归因、知识草稿/绑定等)的 authz/source 快照列统一收敛到 VARCHAR。
• 替代方案(Alternatives)：① 为 envelope 建独立授权快照表换取数值 id，最贴一级表概念建模，但实现仓至今未建出该表、envelope 已是字符串、仓内 authz 业务键已普遍字符串化，新建带传播/重验的重表工程量与回归面最大；② 把字符串 envelope 哈希/映射成数值落 BIGINT，违背稳定标识约定、引入碰撞风险、丢失可审计追溯。相比之下统一为字符串标识与既有迁移趋势(知识库相关表已先行改 VARCHAR)、对外契约 string 口径、后端-04 业务 ID 约定三者自洽，是最小且正确的收口。
• 后果(Consequences)：真实生成的 AI 候选可被正常采纳，AI 生成→采纳→正文写入全链打通。接受路径对授权快照只做"存在且非空"校验，移除"必须为数值"的降级门禁。对外契约中授权快照业务标识一律按 string 暴露(envelope/biz_no 形态)。Market 的 authorizationSnapshotId(integer) 经核是 snapshot/summary 表主键 ID 引用、非业务标识(其业务标识字段 authorizationSnapshot 已是 string),符合本 ADR"物理主键 Long"故不在本次对齐范围;market 对外 openapi 暴露主键 ID 是否违后端-04"不得把主键当合同"属独立契约议题、与本 ADR 不同源。历史数据通过迁移以 ::text 就地转换。详情读侧本已按字符串透出 envelope，类型统一后模块内自洽。未来以外部 Security 替换本地安全投影时，envelope 标识仍按字符串承载，无需再改列类型。
• 参考落地：后端-04-数据库设计.md（业务 ID 对外 string 约定）、迁移 sql/muse/V30、架构-02-核心数据结构与双轨模型.md（Runtime Permission Envelope）

ADR-021：AI 外部运行时通过统一交互协议与 Adapter 接入

• 上下文(Context)：ADR-002 已确定 AI 能力可由外部 Agent 服务提供，但未定义 Muse 与 Dify、AgentScope、New-API 等运行时之间的统一交互协议。实现层当前已存在 New-API runtime client，系统 Agent 由 Muse 本地表治理；产品上需要“管理员在 Dify 配置受限 agent/workflow，Muse 系统 Agent 引用并受控调用”。如果直接在业务服务中硬接 Dify，会把 provider 契约、凭据、权限、审计、重试和 Shadow 写入混在一起，后续 AgentScope 也会重复造一套。
• 决策(Decision)：AI 外部运行时统一通过 MuseAgentRuntimeProtocol + provider adapter 接入。Muse 保留 Agent owner、版本、槽位、Runtime Permission Envelope、Source Snapshot、审计、用量和 Shadow 写入权；Dify / AgentScope / New-API 只作为可替换 runtime provider。系统 Agent 版本只保存 provider 引用（如 Dify app/workflow id、credentialRef、consoleUrl），真实 API Key 只来自环境变量、密文配置或同等级安全配置。指定 provider 不可用时必须 fail-closed，不能回退到其他 provider 伪成功。
• 替代方案(Alternatives)：① 直接把 Dify 调用写进 AI task service，短期快但会扩大业务服务职责、难以复用和测试；② 完全让 Dify 管理 Agent、知识和工具并直接写 Muse，破坏 Muse 事实源、权限包和 Shadow -> Canonical 边界；③ 继续只用 New-API，把 Dify 配置复制为 Prompt，无法支持 Dify workflow/工具/受限知识能力，也无法跳转 Dify 控制台。
• 后果(Consequences)：需要新增协议 DTO、runtime router、Dify adapter、管理端 providerRef 配置和真验证；长期收益是 provider 可替换、凭据边界清晰、Dify/AgentScope 接入一致。RAGFlow 仍是 Muse Knowledge BC 的检索基座，Dify 内部知识只作为外部 app 的受限能力，不成为 Muse Knowledge Canonical。
• 参考落地：专题-05-AI统一交互协议与外部AgentAdapter设计.md、专题-03-AI编排上下文与质量评测实现规范.md、产品-02B-管理员控制台功能规格.md

ADR-022：系统功能链定义归属元引擎（案 A）

• 上下文(Context)：功能链(FunctionChain)的归属在设计内部三方不一致——架构-02 / 架构-01 把系统功能链路划归 Admin/Governance 治理面，后端-04 把功能链表建为 muse_ai_* 归 AI Orchestration，而实现代码里 V3/V10 迁移实际建的是 muse_meta_function_chain/_version/_slot/_node 一族、全部落在 muse-module-meta。三处设计各执一词且都与已落地代码不符，落地时无从取信。
• 决策(Decision)：取案 A——顺代码收敛设计。功能链定义与 MetaSchema 同住元引擎(Meta BC)，表名 muse_meta_function_chain* 不动，逻辑写入 authority 仍是 Governance facade(物理落点 meta，与 MetaSchema 同模式)。AI runtime 不再拥有功能链定义，改为经 FunctionChainQueryApi 只读激活链做运行编排；muse_ai_protected_node_registry(保护节点实例)与 muse_ai_agent_slot_binding(运行时槽位绑定)仍归 AI。
• 替代方案(Alternatives)：案 B 顺 后端-04 原表述，把功能链定义迁到 AI 模块并重命名为 muse_ai_*。它要改动已验真的迁移与代码、产生数据迁移与回归面，只为迁就一处文档表述；此处恰是代码为既成事实，逆向迁移工作量与风险都更大。
• 后果(Consequences)：修订 后端-04(表名与 owner 订正为 meta)、架构-01 §3.3、架构-02 §2、后端-02 §3.4 的功能链归属表述，零数据迁移。功能链与 MetaSchema 共享版本、灰度与激活基建(同一套 effective_scope + active 唯一约束)。AI 经读端口编排，须保留"功能链未激活→回退现有固定链"的运行时兜底。
• 参考落地：docs/agent-specs/2026-07-08-AI能力与元数据驱动智能体架构-设计评审.md（§7.2、第八节 W5）、专题-06-元数据驱动的智能体架构.md

ADR-023：双轨 Canonical 入口增补——管理员确认系统级知识草稿

• 上下文(Context)：系统级拆书要把管理员从参考书拆出、并确认过的公共范式草稿写进全局知识库(Global KB)成为正式范式 Canonical，供作品显式绑定检索。但 架构-02 §1.2 的 Canonical 入口是封闭枚举，原有条目只覆盖用户作品级确认与管理员发布系统配置，没有"管理员确认系统级知识草稿→Global KB 范式"这条，系统级拆书链路(W8)因此无合法入口落库。
• 决策(Decision)：在 架构-02 §1.2 封闭枚举增补一条入口「管理员确认系统级知识草稿 → Global KB 范式 Canonical」(2026-07-08)，确认人是管理员，产出走与作品级同构的 Draft→确认→Canonical 链；只确认经拆书产出的公共范式，不写用户私有作品事实或 Local KB，来源受限时不确认。
• 替代方案(Alternatives)：维持封闭枚举、系统级拆书只产 Shadow 不入 Canonical，则全局范式库无正式事实来源、作品无法绑定检索到系统级公共属性参考，拆书的"系统级能力"落空。
• 后果(Consequences)：架构-02 §1.2 修订(+1 入口)，W8 系统级拆书链路解锁；参考作品档案落 reference_work(Global KB document 特化)，范式带 lineage 溯源；确认仍受来源状态与授权约束，与用户级确认共用同一套不变式。
• 参考落地：docs/agent-specs/2026-07-08-AI能力与元数据驱动智能体架构-设计评审.md（§5.4、§7.2、第八节 W8）、架构-02-核心数据结构与双轨模型.md §1.2

3. 本次是否需要新增 ADR 的结论

需要。双角色入口、New-API 职责边界、全局/局域知识库分层、作品规划台模型复用、小说场景(Scene)暂不升一级模型、Sa-Token 认证授权基座、yudao-cloud fork 工程基座、逻辑 owner 优先原则，都会影响跨文档边界和后续实现，因此已补 ADR-008 到 ADR-015。Governance 拆散、Source 传播模式选择、Candidate Envelope 简化和图查询依赖 RAGFlow GraphRAG 的决策已补 ADR-016 到 ADR-018 并更新 ADR-006。导出/导入文件交付改为稳定存储路径字节代理 + 失败关闭安全姿态（字节代理取流、SSRF 白名单、服务端权威扫描状态、账户导出脱敏）已补 ADR-019。AI 生成候选采纳断层修复——授权快照 id 由 BIGINT 收敛为跨系统稳定字符串标识(VARCHAR)、移除数值降级门禁、对齐知识库表既有迁移与后端-04 业务 ID 约定——已补 ADR-020。AI 外部运行时通过统一交互协议与 Adapter 接入，支持 Dify agent/workflow 引用并预留 AgentScope，已补 ADR-021。功能链定义归属元引擎（案 A，顺代码收敛设计、零数据迁移）已补 ADR-022；双轨 Canonical 入口增补「管理员确认系统级知识草稿 → Global KB 范式」、解锁系统级拆书 W8 已补 ADR-023。

4. 关联阅读

• 系统边界与 BC：架构-01-系统全貌与边界上下文.md
• 数据结构与模型规则：架构-02-核心数据结构与双轨模型.md
• 状态机与约束：架构-04-状态机与约束清单.md
• AI 统一运行时协议：专题-05-AI统一交互协议与外部AgentAdapter设计.md
• 管理员系统处理流程：流程-02A-管理员系统处理流程(系统视角).md
• 普通用户系统处理流程：流程-02B-普通用户系统处理流程(系统视角).md