diff --git a/design-docs/00-文档大纲.md b/design-docs/00-文档大纲.md index 083bc07c..14f43d77 100644 --- a/design-docs/00-文档大纲.md +++ b/design-docs/00-文档大纲.md @@ -100,6 +100,7 @@ - [专题-02-Sudowrite对标与Muse产品取舍](专题-02-Sudowrite对标与Muse产品取舍.md) - [专题-03-AI编排上下文与质量评测实现规范](专题-03-AI编排上下文与质量评测实现规范.md) - [专题-05-AI统一交互协议与外部AgentAdapter设计](专题-05-AI统一交互协议与外部AgentAdapter设计.md) +- [专题-06-元数据驱动的智能体架构](专题-06-元数据驱动的智能体架构.md)——收束「agent = f(作品 + 元数据 + 知识库)」横切架构：元引擎与功能链双枢、三体关系、target type 20 型结构本体、统一创作数据读取器、base 内置机制与拆书通用抽取。 说明：专题文档只负责跨文档收束，不抢走 Schema、状态机和统一 API 的单一归属。 diff --git a/design-docs/专题-06-元数据驱动的智能体架构.md b/design-docs/专题-06-元数据驱动的智能体架构.md new file mode 100644 index 00000000..b372be3a --- /dev/null +++ b/design-docs/专题-06-元数据驱动的智能体架构.md @@ -0,0 +1,285 @@ +# 专题-06：元数据驱动的智能体架构 + +- 版本：v1 +- 更新日期：2026-07-09 +- 目标读者：架构 / 后端 / 前端 / 产品 +- 边界说明：本册是「元数据驱动的智能体架构」这条横切主线的单一 owner，收束四件此前散落无主的事——元引擎与功能链如何共同驱动智能体、拆书作为通用抽取智能体的两处用场、target type 结构本体的全清单与分层判据、统一创作数据读取器与 base 内置机制。术语与双轨不变式的权威在 [架构-02-核心数据结构与双轨模型](架构-02-核心数据结构与双轨模型.md)（MetaSchema、Canonical/Shadow、domain/scope）；AI 链路合同与 Context Assembly 在 [专题-03-AI编排上下文与质量评测实现规范](专题-03-AI编排上下文与质量评测实现规范.md)；外部 Agent 协议在 [专题-05-AI统一交互协议与外部AgentAdapter设计](专题-05-AI统一交互协议与外部AgentAdapter设计.md)；表结构与字段合同在 [后端-04-统一数据库Schema-v1](后端-04-统一数据库Schema-v1.md)。上述对象本册只链接、不重复定义。 +- 变更记录：v1（2026-07-09）定稿自 2026-07-08 架构评审，将「agent = f(作品 + 元数据 + 知识库)」主线、三体关系、20 型结构本体、统一读取器与 base 机制蒸馏为 canonical。 + +--- + +## 1. 中枢：元引擎与功能链双枢 + +理解本册全部内容的钥匙是一句话：**Muse 不是「一个功能挂一个外部 app」，而是一套元数据驱动的智能体编排**。它的中枢在 muse-cloud 的元结构模块里，由两套彼此正交的东西组成。 + +**元引擎（MetaSchema）是结构模具**。它定义一个角色有哪些属性、一段文风从哪些维度刻画、一次转折由哪些要素构成，以及每个字段是否可见、可编辑、可检索、是否可进入 AI 上下文。它约束的是智能体「读哪些字段、抽哪些实体、产出什么结构」。其权威定义见 [架构-02 §9 MetaSchema 与配置模型](架构-02-核心数据结构与双轨模型.md)。 + +**功能链（FunctionChain）是流程骨架**。一条链由若干节点串成，节点分两种：开放槽位允许替换子智能体，保护节点不可替换。它约束的是「智能体按什么次序跑、哪一步不能外包」。功能链的节点/开放槽位/保护节点语义见 [专题-03 §2 系统功能链路](专题-03-AI编排上下文与质量评测实现规范.md)，落地的槽位模型见 [架构-02 §5.2 系统功能编排与槽位](架构-02-核心数据结构与双轨模型.md)。 + +一句话区分：**MetaSchema 定义「结构」，FunctionChain 定义「流程」**。二者同住元引擎（Meta BC）——功能链的定义、版本、节点、槽位与 MetaSchema 是一族数据，表结构见 [后端-04 §7.2 系统功能链路和槽位](后端-04-统一数据库Schema-v1.md)。AI runtime 不自持一套编排，而是经 `FunctionChainQueryApi` 读端口取激活的功能链，据此解析节点序列与开放槽位再做运行编排。这样「谁来定义能力怎么串」与「谁来执行这次编排」分属两个 BC，定义在 Meta、执行在 AI，避免编排逻辑在两处各写一份而漂移。 + +由这两枢得到本架构最重要的性质：**每个智能体都是 `f(作品 + 元数据 + 知识库)`**。任何智能体运行时同时结合三样输入——作品提供「写什么/改什么/查什么」的对象与近邻语境，元数据决定「读哪些字段、抽哪些实体、产出什么结构」（它是产出结构的模具），知识库提供「作品事实」与「公共参考」两类支撑。因此**智能体的类型是固定的产品功能（写死在功能链节点上），但产出是元数据驱动的动态结果**：管理员在元引擎里给「世界设定」加一个字段「金手指类型」，或给「文风」加一个维度「反转密度」，不改一行智能体代码，拆书就会多抽这个属性、规划会多生成这个字段、检测会多查这个维度。这就是「类型固定、元数据变则产出变」。 + +```mermaid +flowchart TB + subgraph Meta["元引擎 MetaSchema（结构模具）"] + MS["target type / 字段 / 枚举 / 校验
aiContext 开关 / 输出合同"] + end + subgraph Chain["功能链 FunctionChain（流程骨架 · 经 FunctionChainQueryApi 激活）"] + direction LR + N1["保护节点
输入合规 / 权限过滤"] --> SLOT["开放槽位
能力子智能体"] --> N2["保护节点
质量门控 / 输出合规"] + end + W["作品 Content"] --> SLOT + K["知识库 Knowledge"] --> SLOT + MS -. 约束读入与产出结构 .-> SLOT + MS -. 定义可入 AI 字段 .-> W + SLOT -->|候选| Shadow["Shadow 待审"] + Shadow -->|用户确认| Canonical["Canonical 正式事实"] +``` + +--- + +## 2. 三体关系：muse-cloud / dify-agent / dify-rag / New-API + +先破一个误解：**dify-agent 与 dify-rag 不是两套部署，而是同一个 Dify 实例的两个功能平面**，靠两类 API key 区分——app key 只能打 app/workflow，dataset key 只能打 datasets，混用即被拒。四方职责如下。 + +| 角色 | 是什么 | 持有什么 | 边界 | +|---|---|---|---| +| **muse-cloud** | 大脑与主权 | 元引擎、功能链、运行权限包、双轨（Shadow/Canonical）、审计、用量归属、编排 | 业务事实源与权限裁判；绝不让外部写 Canonical | +| **dify-agent** | 开放槽位的能力执行 | Dify chat/workflow app | 只是能力节点，只返回候选，不是可入库事实 | +| **dify-rag** | 检索基座 | Dify Datasets（每知识库一物理库） | 检索基座不等于事实源；缺来源/授权的结果不进上下文 | +| **New-API** | 底层模型网关 | 真实模型与向量/重排 | 用量、成本、归属的权威；Dify 用量仅作脱敏审计 | + +主权原则一句话：**Muse 编排，Dify 执行，Muse 裁判**。两个 Dify 平面都是可替换的外部底座——指定了 Dify 却未配置时失败关闭，绝不回退 New-API 伪装成功；Dify 全挂时 Muse 也只失败关闭，用户读写 Canonical 不受影响。外部运行时接入的统一协议与 adapter 边界见 [专题-05](专题-05-AI统一交互协议与外部AgentAdapter设计.md)。 + +一次生成的完整数据流由 muse-cloud 全程编排，外部两平面只在「检索」与「能力执行」两处被调用，产出一律以候选身份回到 Muse 的保护节点。 + +```mermaid +sequenceDiagram + participant U as Studio 用户 + participant M as muse-cloud（编排 + 主权） + participant R as dify-rag（检索） + participant A as dify-agent（能力执行） + participant N as New-API（模型网关） + U->>M: 续写请求 + M->>M: 生成运行权限包 + 按 MetaSchema 组装上下文 + M->>R: 按授权检索绑定库 + R->>N: 向量检索 / 重排 + R-->>M: 授权片段（带来源 / 状态） + M->>A: 组装后的上下文 + A->>N: 模型推理 + A-->>M: 候选（仅候选） + M->>M: 保护节点：静态检查 / 质量门控 / 输出合规 + M-->>U: Shadow 候选 + 创作健康度解释 + U->>M: 接受 / 改后合并 / 丢弃 + M->>M: 写 Canonical 正文 + 来源归因 +``` + +--- + +## 3. 智能体三层清单 + +按主权边界，智能体分三层，**只有第一层可以挂 Dify app**。这样切分有三个理由：主权（Shadow→Canonical 的裁决不能被外部替换）、可替换性（同一开放槽位可在 Dify、New-API、未来 AgentScope 之间换而不动主链）、可解释与可审计（保护节点必须产出 Muse 可追溯的结论）。 + +**第一层 · 开放能力子智能体**（可挂 Dify app/workflow 或 New-API，也是用户/市场智能体的插入点）： + +| 智能体 | 做什么 | 依赖（作品 + 元数据 + 知识库） | 产出与边界 | +|---|---|---|---| +| **写作** | 续写/改写/扩写/润色/纠错/去 AI 味/角色声音 | 近邻正文 + `style`/`pacing`/`craft` + Local KB 与检索片段 | 只进 Shadow；不写 Canonical，不替换保护节点 | +| **拆书/分析** | 按 MetaSchema 从文本抽实体/关系；全书解析、章节抽取、结构拆解 | 源文本 + 实体类 target type + 目标库（Global/Local） | 章节审阅后才建草稿；系统级只产抽象范式、不留原文 | +| **检测** | 一致性/角色声音/文风/风险/语义偏离检查 | 候选或正文 + 检查约束 target type + Local KB Canonical | 只产解释与定位，不直接改正文或知识 | +| **规划** | 生成大纲/世界设定/人设 | 作品方向 + `work_core`/`outline`/`world`/`character` + Local KB | 规划候选只进 Shadow；未确认不得进后续生成上下文 | + +**第二层 · 保护节点智能体**（Muse 自持，即使调用 LLM 也不外包为可配置 Dify app，只走受控内部路径）：质量门控与 LLM-Judge 在候选交付前按质量维度评分并做 Shadow 内有限重写；合规与语义围栏对输入输出做失败关闭的合规裁决，不可被质量分放开；离线质量评估对智能体/Prompt/策略跑评估集回归，不影响用户当前候选。它们是「先审后入」主权的执行者，质量维度的定义见 [专题-04-生成质量门控与创作健康度设计方案](专题-04-生成质量门控与创作健康度设计方案.md)。 + +**第三层 · 知识基座**（不是「app」）：RAG 检索按授权从绑定库的 Dify dataset 循环检索合并，返回带来源/授权/状态的片段；切块、入 RAG、索引是资料摄入的保护节点，处理未过不得进生成上下文。 + +三层与功能链节点一一对应：生成链对应写作智能体，分析/导入解析链对应拆书智能体，检测链对应检测智能体，规划链对应规划智能体，知识处理链对应拆书入库与 RAG，质量链与合规链落在保护节点智能体上。功能链是编排骨架，智能体是槽位里的能力。 + +--- + +## 4. target_type 结构本体 + +### 4.1 元数据用途类与本体分组的分层 + +元数据不是一张平表。它按用途分五个**元数据用途类**，其中只有第一类是「实体有哪些属性」、被拆书与生成直接消费；其余四类各有独立 owner，本册只在此定位、不重复定义。 + +| 元数据用途类 | 管什么 | 载体与 owner | +|---|---|---| +| **① 结构本体** | 实体有哪些属性（拆书抽、生成写、检测查的结构模具） | MetaSchema target types（本册 §4.2 起） | +| **② 质量维度** | 怎么评判好坏 | Quality Policy（[专题-04](专题-04-生成质量门控与创作健康度设计方案.md)） | +| **③ 编排** | 智能体怎么串 | FunctionChain（本册 §1，落地见 [后端-04 §7.2](后端-04-统一数据库Schema-v1.md)） | +| **④ 智能体配置** | 每个能力怎么配（prompt/模型绑定/工具授权/输出合同） | Agent Version（[专题-05](专题-05-AI统一交互协议与外部AgentAdapter设计.md)） | +| **⑤ 可见与策略** | 每字段的权限行为与灰度 | MetaVisibilityPolicy（[架构-02 §9](架构-02-核心数据结构与双轨模型.md)） | + +为免「大类」串词，下文一律称这一层切分为**元数据用途类**（五类），称结构本体内部的分组为**本体分组**（作品骨架/世界设定/人物/画像/技法，加容器、系统侧、配套三个附组）。「固定」的是这几个用途类；类型与属性是开放集——管理员可增类型、用户可在作品级扩字段。 + +### 4.2 前置地基：domain 与 scope 两轴 + +结构本体的每个 target type 先由两根正交的轴定位。这两轴的概念权威在 [架构-02 §9](架构-02-核心数据结构与双轨模型.md)，此处给的是面向本体分类的应用视图。 + +**domain 描述语义域，不描述存储 BC**——它回答「这块结构属于哪个意义世界」，与实例落在哪个 Bounded Context 无关；例如 Local KB 实体的实例存 Knowledge BC，但其 schema 多属 world 或 narrative 域。**scope 恒等于实例对象的粒度**，取值是 work/chapter/block/entity/relation/event/agent 之一；系统级与作品级之分不占 scope 轴，由 `effective_scope` 承载（见 §5）。 + +| domain | 一句话判据 | 承载 | +|---|---|---| +| `content` | 作者对作品的戏外承诺与计划，角色感知不到 | 作品容器、创作定位、大纲 | +| `world` | 角色可感知的戏内世界事实 | 世界观、地点、组织、力量体系、物品、事件、角色、关系 | +| `narrative` | 只关「怎么讲」、不关「讲什么」的叙事表达层 | 文风、节奏、技法、桥段、套路 | +| `knowledge` | 知识库域自身的资料资产结构（非知识实体的内容结构） | 参考作品档案 | +| `ai_context` | AI 上下文组装与输出合同的结构 | 生成上下文快照模具 | + +有一处同词须点明：target type `world`（世界观总纲，一个具体结构型）与 domain `world`（世界事实语义域）字面相同却分属两轴，前者是「型」、后者是「域」，不是一回事。 + +### 4.3 结构本体全清单（20 型） + +下表是与两轴对齐后的 target type 全清单，给的是归属、粒度与本体分组的总览；落地节奏由执行计划承载，本表只陈述设计本身。 + +| # | domain | scope | target_type | 中文名 | 本体分组 | +|---|---|---|---|---|---| +| 1 | content | work | `novel_work` | 作品容器 | 容器 | +| 2 | content | work | `work_core` | 作品核心 | 作品骨架 | +| 3 | content | work | `outline` | 大纲 | 作品骨架 | +| 4 | world | work | `world` | 世界观总纲 | 世界设定 | +| 5 | world | entity | `location` | 地点 | 世界设定 | +| 6 | world | entity | `faction` | 组织阵营 | 世界设定 | +| 7 | world | entity | `power_system` | 力量体系 | 世界设定 | +| 8 | world | entity | `item` | 物品 | 世界设定 | +| 9 | world | event | `event` | 事件 | 世界设定 | +| 10 | world | entity | `character` | 角色 | 人物 | +| 11 | world | relation | `character_relation` | 角色关系 | 人物 | +| 12 | narrative | work | `style` | 文风画像 | 画像 | +| 13 | narrative | work | `pacing` | 节奏画像 | 画像 | +| 14 | narrative | entity | `craft` | 叙事技法 | 技法 | +| 15 | narrative | entity | `combat` | 打斗桥段 | 技法 | +| 16 | narrative | entity | `emotion` | 情感桥段 | 技法 | +| 17 | narrative | entity | `scene_pattern` | 通用桥段 | 技法 | +| 18 | narrative | entity | `trope` | 套路 | 技法 | +| 19 | knowledge | entity | `reference_work` | 参考作品档案 | 系统侧 | +| 20 | ai_context | agent | `generation_context` | 生成上下文 | 配套 | + +scope 落座有两处最易被误判，须点明。`outline` 取 `work` 而非 chapter：scope 是实例集合的聚合归属粒度，大纲是全书单一计划，其内部的全书/卷/章三层用字段表达层级，不改 scope。`world` 取 `work`：按边界判据它不可数、无法单章出场，是每作品一份的单例总纲，故归 work 而非 entity。 + +### 4.4 精炼原则与拆分判据 + +**一型一格位、一概念一 owner**。一个候选要挣得独立 target type，须同时占据「它是什么（实体/计划/画像/装置/范式）× 谁在何时消费（规划/写作/检查期）」平面上的一个空格位，且承载邻接型收编不了的字段合同；否则按三条规则降级：差异只能举例、给不出判据的**变体收进枚举**（如拍卖会、比武会）；属性可由他型查询导出的**投影收进读模型**（如时间线、关系网、伏笔看板）；离开某型无独立生命的**附属收进字段**（如金手指例外）。这条准绳兑现「类型可更多但边界必清晰」——品类增型走同一判据，判据说不出一句就降级，杜绝为拆而拆。 + +判断「一个概念落一个还是多个 target type」用四条判据，与上面三条降级规则叠加使用。**粒度判据**：两个用场里实例挂靠的粒度不同（work 级单例画像 vs entity 级多条目），倾向拆。**字段合同判据**：字段交集不足一半、或校验规则互斥，拆。**消费判据**：仅消费链路不同而字段相同，不拆，消费差异走可见性策略。**写入路径判据**：进 Canonical 的入口不同（用户直接命令 vs 确认链），倾向拆。四判据回答「拆不拆」，三条降级规则回答「不拆时降到哪一级」。 + +17 个结构骨架型（容器、系统侧、配套三个附组不计入）的边界判据如下，每型给最锋利的一句「纳入 / 排除去向」；完整字段合同落 [后端-04](后端-04-统一数据库Schema-v1.md)，管理面见 [产品-02B-管理员控制台功能规格](产品-02B-管理员控制台功能规格.md)。 + +| target_type | 层次 | 边界判据（纳入 ‖ 排除→归哪） | +|---|---|---| +| `work_core` | 骨架 | 只有作者读者知、角色感知不到的作品级承诺 ‖ 角色可感知世界事实→`world`；逐章安排→`outline` | +| `outline` | 骨架 | 对「接下来写什么」的计划（全书/卷/章任一层级）‖ 戏内已定事实→`event`；跨作品公式→`trope` | +| `world` | 骨架 | 角色可感知但不可数、无法单章出场的世界级规则格局 ‖ 可指名出场者→`location`/`faction`/`item`；决定强弱排序→`power_system` | +| `location` | 骨架 | 可到达、可发生场景的具名空间 ‖ 弥漫地理→`world`；空间上的组织→`faction` | +| `faction` | 骨架 | 有宗旨/层级/成员的具名集体（含组织化种族、朝廷）‖ 无组织的文明背景→`world`；成员个体→`character` | +| `power_system` | 骨架 | 直接决定角色强弱排序的规则（可多套并存）‖ 约束所有人而不排序→`world`；具体功法技能→品类开放集增型 | +| `item` | 骨架 | 可持有可流转的具名物件（含秘籍载体）‖ 「怎么描写」的笔法→`style` 公共层 | +| `event` | 骨架 | 戏内时间轴上有参与者与因果的已定/预定事实（时间线=event 有序投影，不另设型）‖ 作者写作安排→`outline`；节奏分布→`pacing` | +| `character` | 双层 | 具名/可指认的行动主体，说话方式即该角色语言指纹 ‖ 作者全书指纹→`style`；关系→`character_relation`；集体→`faction` | +| `character_relation` | 骨架 | 演变轨迹本身就是剧情、值得立传的关系 ‖ 只更新当前值的结构性从属→Knowledge Relation 边+枚举；推进公式→`trope` | +| `style` | 双层 | 与章序无关的语言表层指纹（打乱章序不变）‖ 顺序敏感分布→`pacing`；单角色语言→`character` 说话方式 | +| `pacing` | 双层 | 顺序敏感的分布（值是曲线/比率，打乱章序即毁）‖ 单个爽点构成→`craft`；逐章安排→`outline` | +| `craft` | 双层 | 单点装置——删去它场景仍成立、读者体验变平；台账只收有跨章履约的装置 ‖ 承载整场戏→桥段三型；跨章公式→`trope` | +| `combat` | 公共 | 以武力/超自然力分胜负的对抗场景 ‖ 非武力博弈（商战/权谋/斗嘴）→`scene_pattern`；情绪弧主导→`emotion` | +| `emotion` | 公共 | 以情绪弧为主体的场景（告白/离别/爆发）‖ 武力分胜负→`combat`；关系实体本身→`character_relation` | +| `scene_pattern` | 公共 | 有「目标-推进-收束」完整结构的场景范式，枚举显式排除打斗与情感 ‖ 点装置→`craft`；跨场景公式→`trope` | +| `trope` | 公共 | 规定「这条线接下来几章怎么走」的公式 ‖ 单场景流程→`scene_pattern`；本作品自己的计划→`outline`（挂引用） | + +四条外边界与型内判据同等效力：质量维度不进本体（模具与检尺分立，见 [专题-04](专题-04-生成质量门控与创作健康度设计方案.md)，两者单向咬合、不共享定义）；叙事运行态不进本体（Narrative State 是独立事实载体，见 [架构-02 §3 作品内容模型](架构-02-核心数据结构与双轨模型.md)，本体只提供其字段模具）；RAG 文档面不进本体（上传的百科语料是检索素材，非实例，除非经确认链落成作品实体）；品类特化与作品私有字段不进基础层，走开放集增型与作品级 override。 + +### 4.5 三层浇铸与双层型 + +结构本体按浇铸去向分三层：**结构骨架**只浇作品事实实例，入 Local KB 或规划；**公共参考**只浇跨作品范式，由系统级拆书入 Global KB，只存抽象范式与脱敏例证、不留原文；**双层**两处都浇。所有型共享名称/别名/摘要/标签等基础字段，各型只在此之上标注特有字段。 + +`character`、`style`、`pacing`、`craft` 四型是双层型。主案取**单模具双库**——一型一 schema，作品面实例与公共范式共用同一字段合同，公共面实例落 Global KB。是否为公共面另立独立的 `*_paradigm` 型，留待三样本实测（拆书产出的公共范式能否无损写进同一字段合同）再定：能无损写入则不拆，字段合同不同构才拆。在此之前 W1 先落作品面种子，不被这个开放问题阻塞。 + +--- + +## 5. 作品容器与 base 内置机制 + +### 5.1 作品容器 novel_work 与 work_core 拆两 schema + +作品容器不是新造的抽象。`muse_content_work` 已有一批固定列——归属用户、书名、品类、简介、状态、字数、章节数、导入与解析状态，并已预留可选关联 MetaSchema 的钩子；作品动态字段的修改入口也已预设校验 schemaVersion，表与接口见 [后端-04](后端-04-统一数据库Schema-v1.md) 与 [后端-05 §4.3 作品和正文](后端-05-统一API契约-v1.md)。容器 schema 化是给这批既有固定列补上元描述，不是无中生有。 + +容器（`novel_work`）与作品核心（`work_core`）拆成两个 schema，依据是四判据的字段合同与写入路径两条。字段合同不同构：容器承载书名、简介、封面、状态、字数、时间这类运营与结构身份，`work_core` 承载题材、主题立意、基调、禁区、结局方向这类创作承诺。写入路径不同：容器走用户直接修改加系统回算，`work_core` 走规划确认链。消费面不同：容器喂列表、卡片、导出与市场快照，`work_core` 喂全部开放智能体的上下文。 + +### 5.2 同体加投影，storage_binding + +容器 schema 与 Work 聚合的关系是**同体加投影，不派生**——不另建实例表，避免双写漂移。schema 是对 Work 固定列的元描述与读投影模具：字段合同为每字段标注落点，`native_column`（物理列）、`extension_json`（扩展字段）或 `computed`（回算字段，用户不可编辑），这就是 `storage_binding` 机制，由 `muse_meta_field` 承载对固定列的元描述（属性落点见 [后端-04](后端-04-统一数据库Schema-v1.md)）。它与「MetaSchema 不替代事实载体」一致（[架构-02 §9](架构-02-核心数据结构与双轨模型.md)）。卷章结构不进容器字段合同，按「投影收进读模型」降级，由 §7 统一读取器的作品分区输出。 + +### 5.3 base 是全局 active schema，叠加与继承 + +`base` 不是新机制：**base 就是 `effective_scope=全局` 的 active schema 版本**，「内置」就是系统出厂 seed 的那批全局 schema。一个作品能看到的结构，是三层叠加：全局 active ⊕ 类型灰度版本 ⊕ 作品级 override。**override 只增不改**——只能扩展字段，不能删改全局字段的定义与可见性；这是 [架构-01](架构-01-系统全貌与边界上下文.md) BC 边界的推论，全局定义的主权不因作品扩展而被作品侧改写。 + +继承靠动态合成、不靠复制：系统不落 per-work schema 实例，读取时按投影版本动态合成。新作品开箱即有全部结构，因为全局 schema 天然生效、零初始化；容器上预留的品类包钩子默认空，即纯继承。 + +系统内置的 base schema 出厂全集是 20 项，分四档，每档的开箱形态与可见性基线如下。 + +| 档 | 开箱形态 | schema | 可见性基线 | +|---|---|---|---| +| 作品身份档 | 开箱即有 | `novel_work`、`work_core` | 可见、可编辑（容器回算字段除外）、可进 AI 上下文（禁区/结局方向按需） | +| 创作骨架档 | 开箱即有、空实例 | `outline`、`world`、`location`、`faction`、`power_system`、`item`、`event`、`character`、`character_relation` | 可见/可编辑/可检索三者全开 | +| 画像与技法档 | 开箱即有画像；公共范式随 Global KB 绑定进入 | `style`、`pacing`、`craft`、`combat`、`emotion`、`scene_pattern`、`trope` | 作品面全开；公共面例证与出处字段的可见性待例证口径 | +| 系统侧档 | 用户不可见 | `reference_work`（仅管理面）、`generation_context`（运行时） | 不可见、不可编辑 | + +--- + +## 6. 拆书与参考作品 + +### 6.1 一套模具，两处浇铸 + +拆书不是管理员专用的一次性管线，而是一个**通用抽取智能体**：给定文本、MetaSchema 与目标库，按 target type 定义的实体类型解析出实体并入库（经 Shadow→Canonical）。同一个智能体有两个用场，产出结构都由 MetaSchema 决定，因此系统级参考库与作品级实体库天然共用一套结构。 + +- **系统级（管理员）**：把几十上百本参考书拆成小说公共属性范式，沉淀进全局知识库。产出的是抽象属性与技法范式，不是逐字原文（版权约束，且 [专题-03](专题-03-AI编排上下文与质量评测实现规范.md) 禁「作品资产模板化」）。 +- **作品级（用户）**：每确认一章正文，拆本章新实体与关系入局域知识库的确认链；质量校验智能体同时查与既有事实的一致性。 + +拆书的入库不越过双轨——系统级入 Global KB 与作品级入 Local KB 都走 Draft→确认→Canonical，接受 AI 候选只写正文、不自动确认知识（不变式见 [架构-02 §1 双轨模型](架构-02-核心数据结构与双轨模型.md)）。全局公共库作为每个作品的默认可检索来源，但走**显式绑定、不自动注入**：用户或管理员把公共属性库绑定到作品后才进入检索选库集，用量归系统、口径可控。 + +### 6.2 参考作品档案 reference_work + +系统级拆书要吃进的参考书本身得有个落处，即 `reference_work`（domain=knowledge、scope=entity）——一份系统侧的资料资产档案，不是用户创作事实。它不复用作品表：参考作品的 owner 是系统、生命周期是「采购→拆解→归档」，与用户创作的「起草→连载→完结」是两码事，塞进 Content 会违反「Content 只拥有正文和作品结构」的边界。库位落 Global KB 的 document 特化（Knowledge BC），复用既有的资料、版本与处理任务链（表见 [后端-04](后端-04-统一数据库Schema-v1.md)，知识库治理面见 [产品-02E-知识库工作台功能规格](产品-02E-知识库工作台功能规格.md)）；拆书任务本身归 AI BC，是一类新的抽取任务 `reference_extraction`。 + +字段合同分四组。**标识**：书名、作者、品类、别名。**来源**：上传、公开语料或授权采购。**版权授权状态**：`licensed`、`public_domain`、`research_only`、`unauthorized` 四值，其中 `unauthorized` 失败关闭，不进任何拆书任务。**拆书处理状态**：`pending`、`parsing`、`extracted`、`curated`、`failed`。 + +### 6.3 范式溯源与版权传播 + +范式的溯源不新设 target type、不新建表，复用知识域既有的来源 lineage、快照与状态事件机制（见 [架构-02 §4.3 来源和 lineage](架构-02-核心数据结构与双轨模型.md)）。每条进 Global KB 的范式 Canonical 记录带上来源快照引用与 lineage 载荷，指向它的 `reference_work`、拆书任务与章节定位摘要——**只存定位摘要，不存原文段落**（版权约束）。「某本书贡献了哪些范式」不是一张新表，而是按 lineage 的读模型投影。 + +当某参考作品的版权状态收紧，走既有的来源状态变化传播（[架构-02 §11.3 来源状态变化](架构-02-核心数据结构与双轨模型.md)）：**阻断该来源派生范式的新使用，但不回滚已确认的 Canonical**，与知识域现有来源传播语义一致，不引入新机制。 + +系统级范式的入库走一条专门入口——「管理员确认系统级知识草稿 → Global KB 范式 Canonical」，确认人是管理员，产出走 Draft→确认→Canonical 同构链。该入口是双轨 Canonical 封闭枚举的一项，权威登记见 [架构-02 §1.2 进入 Canonical 的入口](架构-02-核心数据结构与双轨模型.md)。 + +--- + +## 7. 统一创作数据读取器 + +`f(作品 + 元数据 + 知识库)` 里「读入」这一半，落在一个专门的读取层上。它**不是第四套读设施**，而是把既成的 Context Assembly（[专题-03 §4 上下文组装](专题-03-AI编排上下文与质量评测实现规范.md)）的取数面，显式分层为 AI Orchestration 内部的服务端读取器。它按 actor、作品与分区请求及授权上下文，经各 owner 的 facade-api 拉数——Content 出作品容器、章节、正式规划与叙事状态，Knowledge 出 Local KB 实体、关系、事件与绑定库检索，Meta 出模具投影——再对每条数据套上该 target type 的 active MetaSchema 投影，做字段级 `aiContext` 裁剪、按 target type 结构化、附来源标注。Context Assembly 消费它完成分层组装与 Token 预算（分层定义见 [专题-03 §4.2 四层上下文](专题-03-AI编排上下文与质量评测实现规范.md)）；检测、导出预检等非生成链路复用同一读取器，不各自重写取数与裁剪。 + +它与用户面的 meta-projections **同源不同面**：共享模具投影的计算，不共享裁剪策略——用户面按 `uiVisible`/`userEditable` 裁，AI 面按 `aiContext` 裁，两者互不蕴含（[架构-02 §9](架构-02-核心数据结构与双轨模型.md)）。一条负约束必须写死：读取器只作为服务端内部端口存在，**不暴露为通用 app API**，否则它会成为与「通用写 SDK」对称的滥用面。 + +读统一、写各 owner。写侧零新设计——动态字段没有跨 owner 的通用写接口，前端禁通用写 SDK（[前端-03 §5.2](前端-03-元引擎与动态表单.md)），Canonical 入口是封闭枚举，智能体产出只进 Shadow，这些约束一条不改。统一读取器对写的唯一贡献，是沿用动态字段校验接口「校验加路由建议、不写入」的语义，把「智能体想改哪个字段」翻译成「该走哪个 owner 的命令」。 + +**最小读合同**： + +- **输入**六项：actor；workId；分区请求集（作品容器 / 规划 / 按 target_type 与 scope 过滤的 Local KB 实体 / 仅限已绑定的 Global KB 公共范式，对齐「显式绑定不自动注入」）；运行权限包引用（其分区许可上限只能收紧不能放宽）；purpose（generation/detection/planning/parse，授权按用途裁，对齐 [专题-03 §4.3 来源和授权](专题-03-AI编排上下文与质量评测实现规范.md) 的「允许阅读不等于允许进 AI 上下文」）；期望 schemaVersion（可选，防任务中途版本漂移）。 +- **输出**：分区化的结构块列表，每块含 `targetType`、`schemaKey`、`schemaVersion`、已按 `aiContext` 裁剪的结构化字段值、`dataRevision`、来源标注（对齐 [专题-03 §5.3 检索结果合同](专题-03-AI编排上下文与质量评测实现规范.md)），以及 `omittedFields` 及原因。 + +裁剪分三级、同时生效：**字段级**（`aiContext=false` 的字段剔除）、**来源级**（状态受限的来源整块不进）、**用途级**（`allowedPurpose` 不含本次 purpose 的剔除）。任一级判定剔除，数据即不进上下文。受限来源整块进 `omittedSources`，失败关闭并留痕可审计。 + +--- + +## 8. 关联阅读 + +| 主题 | 权威文档 | +|---|---| +| MetaSchema、domain/scope、双轨不变式、来源 lineage、Canonical 入口枚举 | [架构-02-核心数据结构与双轨模型](架构-02-核心数据结构与双轨模型.md) | +| BC 边界与协作规则、override 只增不改的边界推论 | [架构-01-系统全貌与边界上下文](架构-01-系统全貌与边界上下文.md) | +| AI 编排、Context Assembly、检索合同、质量评测 | [专题-03-AI编排上下文与质量评测实现规范](专题-03-AI编排上下文与质量评测实现规范.md) | +| 质量维度定义与创作健康度 | [专题-04-生成质量门控与创作健康度设计方案](专题-04-生成质量门控与创作健康度设计方案.md) | +| 外部 Agent 统一协议与 adapter | [专题-05-AI统一交互协议与外部AgentAdapter设计](专题-05-AI统一交互协议与外部AgentAdapter设计.md) | +| MetaSchema 表、功能链表、reference_work 表、storage_binding 落点 | [后端-04-统一数据库Schema-v1](后端-04-统一数据库Schema-v1.md) | +| 作品与动态字段接口契约 | [后端-05-统一API契约-v1](后端-05-统一API契约-v1.md) | +| 拆书公共属性本体管理面与参考作品治理 | [产品-02B-管理员控制台功能规格](产品-02B-管理员控制台功能规格.md) | +| 知识库三库两面与全局库绑定 | [产品-02E-知识库工作台功能规格](产品-02E-知识库工作台功能规格.md) | diff --git a/design-docs/产品-02B-管理员控制台功能规格.md b/design-docs/产品-02B-管理员控制台功能规格.md index 4bb90267..bdc4f97f 100644 --- a/design-docs/产品-02B-管理员控制台功能规格.md +++ b/design-docs/产品-02B-管理员控制台功能规格.md @@ -1,10 +1,11 @@ # 产品-02B：管理员控制台功能规格 -- 版本：v5 -- 更新日期：2026-05-22 +- 版本：v6 +- 更新日期：2026-07-09 - 目标读者：产品 / 交互 / 前端 / 后端 / 测试 - 阅读时间：45-65 分钟 - 边界说明：本文件承接 `产品-01`、`产品-02` 和 `产品-02A`，只定义管理员控制台(Admin Console)的详细功能规格、页面内容、可见数据、用户操作、权限边界和产品接口。本文不写代码级 API、数据库字段、前端路由或具体 UI 组件；不替代智能体工作台、知识库工作台、市场、个人中心和作品工作台的详细规格。 +- 变更记录：v6（2026-07-09）新增 §3.9A 拆书公共属性本体与参考作品治理——20 型 target_type 作为元结构管理面、参考作品档案（`reference_work`）版权授权与拆书处理状态治理、系统级拆书任务与管理员确认队列，细节链接 `专题-06`。 ## 0. 前序继承 @@ -284,6 +285,14 @@ | 埋点与审计 | 记录授权范围、外发允许、版本变化、停用理由。 | | 验收要点 | 授权必须区分可见、可检索、可生成和可进入模型上下文；外发必须可解释和可审计。 | +### 3.9A 拆书公共属性本体与参考作品治理 + +系统级拆书把管理员维护的属性本体、参考书档案与拆书产出统一收在治理面。这里只给管理入口与边界，属性本体的 20 型 target type 全清单、逐型字段合同与范式 lineage 读模型见 `专题-06-元数据驱动的智能体架构.md`。 + +- **拆书公共属性本体管理**：文风、节奏、技法、桥段、套路等小说公共属性以 MetaSchema 的 target type 承载，管理员在元结构定义（§3.3、§3.4）里增删类型、扩字段、调可见性；本体一变，拆书多抽、生成多用、检测多查。这 20 型四档（作品身份／创作骨架／画像技法／系统侧）是元结构管理面的固定内容，不新起页面。 +- **参考作品治理**：参考作品档案（`reference_work`，落全局知识库 document 特化）登记书名、作者、品类等标识，维护版权授权状态（`licensed`／`public_domain`／`research_only`／`unauthorized`，其中 `unauthorized` 失败关闭、不进任何拆书任务）与拆书处理状态（`pending`／`parsing`／`extracted`／`curated`／`failed`）；每条进全局库的范式可按 lineage 查“某本书贡献了哪些范式”，版权收紧时经来源状态传播阻断派生范式的新使用、不回滚已确认。 +- **系统级拆书任务与管理员确认队列**：管理员发起参考书拆书任务后，按公共属性 target type 抽出的范式先入待确认队列（Shadow）；管理员逐条确认后，经「管理员确认系统级知识草稿 → 全局知识库范式 Canonical」入口落库（见 `架构-02 §1.2`），成为可被作品显式绑定的系统来源。 + ### 3.10 质量门控策略 | 项目 | 内容 | diff --git a/design-docs/内容映射表.md b/design-docs/内容映射表.md index 85d99e70..11530f31 100644 --- a/design-docs/内容映射表.md +++ b/design-docs/内容映射表.md @@ -184,6 +184,13 @@ - 产品旅程与决策点：主文档 `产品-03-用户旅程与操作流程.md`（步骤细化在 `流程-01A/01B`） - 系统处理模型：主文档 `流程-02A-管理员系统处理流程(系统视角).md` / `流程-02B-普通用户系统处理流程(系统视角).md` - AI 编排、检索上下文和质量评测合同：主文档 `专题-03-AI编排上下文与质量评测实现规范.md` +- 元数据驱动的智能体架构（横切）：主文档 `专题-06-元数据驱动的智能体架构.md`，owns 六个概念—— + - 元数据驱动的智能体架构：agent = f(作品 + 元数据 + 知识库)，元引擎 + 功能链双枢 + - 三体关系：muse-cloud（主权）/ dify-agent（能力执行）/ dify-rag（检索基座）/ New-API（模型网关） + - target type 结构本体：20 型清单 + domain 逐值语义 + 拆分判据（术语权威仍在 `架构-02` §9） + - 统一创作数据读取器：AI 上下文的服务端读合同（三级裁剪、fail-closed omittedSources） + - base 内置种子清单：20 项四档全局 schema 的叠加与继承机制 + - 拆书通用抽取与参考作品：`reference_work` 档案 + 范式 lineage（Global/Local KB 两处浇铸） - 状态机与约束：主文档 `架构-04-状态机与约束清单.md` - 后端模块职责：主文档 `后端-02-工程结构与模块职责.md` - 统一数据库表结构：主文档 `后端-04-统一数据库Schema-v1.md` diff --git a/design-docs/后端-02-工程结构与模块职责.md b/design-docs/后端-02-工程结构与模块职责.md index d5fab4de..f41d6d5b 100644 --- a/design-docs/后端-02-工程结构与模块职责.md +++ b/design-docs/后端-02-工程结构与模块职责.md @@ -1,10 +1,11 @@ # 后端-02：工程结构与模块职责 -- 版本：v8 -- 更新日期：2026-05-24 +- 版本：v9 +- 更新日期：2026-07-09 - 目标读者：后端 / 架构 / 平台 / 测试 - 阅读时间：25-40 分钟 - 边界说明：本文件只定义后端工程基线、Yudao Cloud fork 保留/裁剪模块、Muse 业务模块职责和模块协作边界。领域模型看 `后端-01`，关键流程看 `后端-03`，Schema 看 `后端-04`，API 契约看 `后端-05`。本文描述目标工程形态，不代表当前仓库所有模块都已实现。 +- 变更记录：v9（2026-07-09）§3.4 Governance Facade 落点表补系统功能链路一行——逻辑写入 authority 为 Governance facade、物理落 `yudao-module-meta`，与 MetaSchema 同模式（案 A，见 `架构-03` ADR-022）。 ## 1. 工程基线 @@ -212,6 +213,7 @@ Governance facade 是 MetaSchema、保护节点、系统功能链路、Tool Gran | 职责 | 物理位置 | 说明 | |---|---|---| | MetaSchema 全部能力 | `yudao-module-meta`（独立模块） | admin 写入 + 用户作品级覆盖 + facade-api 只读消费；Content、Knowledge、AI 等模块通过 `meta-api` 只读依赖消费 active/gray 投影 | +| 系统功能链路定义与版本 | `yudao-module-meta`（独立模块） | 与 MetaSchema 同模式（案 A）：Governance facade 为逻辑写入 authority、物理落 meta 模块；`meta-api` 增 `FunctionChainQueryApi` 只读端口，AI runtime 按激活功能链解析节点序列与开放槽位 | | Protection Node + Quality Policy | `yudao-module-ai-server/application/grant/` | AI grant 包承载保护节点和质量策略的写入服务，只暴露给 admin-api | | Tool Grant authority 实现 | `yudao-module-ai-server/application/grant/` | 写入入口只接受 Governance/Security facade 调用 | | 市场治理 | `yudao-module-market-server/controller/admin/` | 市场资产下架、召回、封禁、申诉处理等治理动作归 market admin 包 | diff --git a/design-docs/后端-04-统一数据库Schema-v1.md b/design-docs/后端-04-统一数据库Schema-v1.md index f8dc82c6..26db5cc1 100644 --- a/design-docs/后端-04-统一数据库Schema-v1.md +++ b/design-docs/后端-04-统一数据库Schema-v1.md @@ -1,10 +1,11 @@ # 后端-04：统一数据库 Schema(结构定义)-v1 -- 版本：v10 -- 更新日期：2026-05-24 +- 版本：v11 +- 更新日期：2026-07-09 - 目标读者：后端 / 架构 / 前端 / 数据库维护者 / 测试 - 阅读时间：35-55 分钟 - 边界说明：本文件定义 Muse 在 `YunaiV/yudao-cloud` fork 上新增或二开的业务 Schema 目标。Yudao 原生 `system`、`infra`、`member`、`pay`、`bpm`、`report`、`mp` 表结构由对应 Yudao 模块负责，本文不重复定义。接口契约见 `后端-05-统一API契约-v1.md`，状态机见 `架构-04-状态机与约束清单.md`，工程模块见 `后端-02-工程结构与模块职责.md`。 +- 变更记录：v11（2026-07-09）功能链定义表订正为 `muse_meta_function_chain/_version/_node/_slot` 归 meta（案 A，见 `架构-03` ADR-022），逻辑写入 authority 为 Governance facade 经 meta admin service；MetaSchema `target_type` 示例去粒度后缀收敛为 `character`；`muse_meta_field` 增 `storage_binding` 存储映射；base 种子目标清单引用 `专题-06`。 ## 1. 目标 @@ -162,11 +163,11 @@ API 层 ID 规则： | `muse_ai_prompt_version` | ai | ai | content / market | 版本激活、下架写 outbox | | `muse_ai_agent` | ai | ai | content / market / account | agent 状态变化影响 slot binding 和市场资产 | | `muse_ai_agent_version` | ai | ai | content / market / account | 版本下架触发绑定重验 | -| `muse_ai_system_function_chain` | ai | ai admin service | content / knowledge | 链路激活、停用写 outbox | -| `muse_ai_system_function_chain_version` | ai | ai admin service | content / knowledge | function chain 版本激活写 outbox | -| `muse_ai_chain_node` | ai | ai admin service | content / knowledge | 节点配置随 chain version 发布 | +| `muse_meta_function_chain` | meta | meta admin service（Governance facade） | ai / content / knowledge | 链路激活、停用写 outbox；AI runtime 经 `FunctionChainQueryApi` 读激活链 | +| `muse_meta_function_chain_version` | meta | meta admin service（Governance facade） | ai / content / knowledge | function chain 版本激活写 outbox | +| `muse_meta_function_chain_node` | meta | meta admin service（Governance facade） | ai / content / knowledge | 节点配置随 chain version 发布 | | `muse_ai_protected_node_registry` | ai | ai admin service | content / knowledge / audit | 保护节点变更写审计和 outbox | -| `muse_ai_override_slot` | ai | ai admin service | content / market | 槽位变更触发 slot binding 重验 | +| `muse_meta_function_chain_slot` | meta | meta admin service（Governance facade） | ai / content / market | 槽位定义变更触发 slot binding 重验 | | `muse_ai_agent_slot_binding` | ai | content + ai binding service | market / account / source | 仅 active 绑定唯一；授权撤销或版本下架触发失效 | | `muse_ai_agent_slot_precheck` | ai | ai target owner service | market / source / account | 槽位绑定目标预检或签名消费凭证，原子消费后写 binding | | `muse_ai_tool_grant` | ai | governance/security facade -> ai grant service | content / account / audit | 工具授权变更写审计；AI runtime 只能消费授权投影 | @@ -328,7 +329,7 @@ MetaSchema 是独立模块 `yudao-module-meta` 的元结构定义，由管理后 | 表 | 职责 | |---|---| | `muse_meta_schema` | 元结构根对象，包含 schema_key、domain、scope、target_type、当前激活版本和适用范围 | -| `muse_meta_field` | 字段定义、类型、必填、枚举、引用、排序和校验规则 | +| `muse_meta_field` | 字段定义、类型、必填、枚举、引用、排序、校验规则和 `storage_binding` 存储映射 | | `muse_meta_visibility_policy` | `uiVisible`、`aiContext`、`userEditable`、`userSearchable`、`exportable` 等可见性策略 | | `muse_meta_schema_version` | 发布版本、激活状态、灰度、回滚和影响预览摘要 | @@ -339,7 +340,7 @@ MetaSchema 是独立模块 `yudao-module-meta` 的元结构定义，由管理后 | `schema_key` | 稳定业务键，同一 domain / scope / target_type 下唯一 | | `domain` | `content` / `world` / `narrative` / `knowledge` / `ai_context` | | `scope` | `work` / `chapter` / `block` / `entity` / `relation` / `event` / `agent` | -| `target_type` | 目标对象类型，例如 `novel_work`、`character_entity`、`generation_context` | +| `target_type` | 目标对象类型，例如 `novel_work`、`character`、`generation_context` | | `active_version_id` | 当前激活版本，可为空但不能指向 disabled / archived 版本 | | `effective_scope` | 适用范围摘要，至少能表达全局、租户、用户、作品、类型灰度 | | `projection_version` | 当前读模型或运行时缓存使用的投影版本 | @@ -361,6 +362,8 @@ MetaSchema 是独立模块 `yudao-module-meta` 的元结构定义，由管理后 | `published_by` / `published_at` | 发布人和发布时间 | | `activated_by` / `activated_at` | 激活人和激活时间 | +`muse_meta_field` 的 `storage_binding` 存储映射（DDL 随 W1 迁移落地）标注每个字段的物理落点：`native_column`（映射 Work 等聚合的固定列，如 `novel_work` 容器 schema 对 `muse_content_work` 的 title / genre / status 等列）、`extension_json`（扩展字段落 jsonb）、`computed`（回算字段，`userEditable=false`）。它承载容器 schema 对既有固定列的元描述，使 MetaSchema 不复制事实载体（对齐 `架构-02 §9`）。系统内置 base schema 的种子目标清单（20 项四档：作品身份 / 创作骨架 / 画像技法 / 系统侧）由 `专题-06-元数据驱动的智能体架构.md` 定义，本册不复制清单。 + 约束： - MetaSchema 写入入口只能是 `/admin-api/muse/governance/**` 经 `yudao-module-meta`；Content 等模块只能通过 meta facade-api 消费只读投影。 @@ -695,16 +698,18 @@ SourceEventType 到状态策略的默认映射： ### 7.2 系统功能链路和槽位 +功能链定义（chain / version / node / slot）与 MetaSchema 同住 `yudao-module-meta`（案 A，见 `架构-03` ADR-022），逻辑写入 authority 为 Governance facade、经 meta admin service；AI runtime 经 `FunctionChainQueryApi` 只读激活链做运行编排。`muse_ai_protected_node_registry`（保护节点注册表实例）与 `muse_ai_agent_slot_binding`（运行时槽位绑定）仍归 AI。 + | 表 | 职责 | |---|---| -| `muse_ai_system_function_chain` | 生成、分析、检测、导入解析、知识处理等系统预编排链路 | -| `muse_ai_system_function_chain_version` | 功能链路版本，记录 chain definition、激活状态、回滚来源和兼容范围 | -| `muse_ai_chain_node` | 链路节点，标记 protected / open_slot / internal | +| `muse_meta_function_chain` | 生成、分析、检测、导入解析、知识处理等系统预编排链路 | +| `muse_meta_function_chain_version` | 功能链路版本，记录 chain definition、激活状态、回滚来源和兼容范围 | +| `muse_meta_function_chain_node` | 链路节点，标记 protected / open_slot / internal | | `muse_ai_protected_node_registry` | 不可替换保护节点注册表 | -| `muse_ai_override_slot` | 可替换子智能体槽位定义 | +| `muse_meta_function_chain_slot` | 可替换子智能体槽位定义 | | `muse_ai_agent_slot_binding` | 作品级槽位绑定，记录用户选择的 Agent Version | -`muse_ai_system_function_chain_version` 字段合同： +`muse_meta_function_chain_version` 字段合同： | 字段语义 | 要求 | |---|---| @@ -1034,7 +1039,7 @@ Owner 约束： | 市场购买、授权、安装和绑定不写作品事实 | `muse_market_authorization` / `install` / `bind_precheck` / `handoff` 与 Content / Knowledge Canonical 分离 | | Market 不写目标预检事实 | `muse_market_bind_precheck` 只保存来源侧摘要；目标凭证分别落 `muse_ai_agent_slot_precheck`、`muse_knowledge_bind_precheck`、`muse_content_work_asset_use_precheck` 或目标 owner 签名凭证 | | 市场收藏不代表授权或安装 | `muse_market_collection` 只保存用户市场行为 | -| 用户只替换开放槽位 | `muse_ai_override_slot` / `muse_ai_agent_slot_binding`，保护节点在 `muse_ai_protected_node_registry` | +| 用户只替换开放槽位 | `muse_meta_function_chain_slot` / `muse_ai_agent_slot_binding`，保护节点在 `muse_ai_protected_node_registry` | | AI 不能自授工具或外发权限 | `muse_ai_tool_grant.authority_owner` 必须来自 Governance / Security facade，运行时只消费 `muse_ai_runtime_permission_envelope` | | 入 RAG 不反写事实 | `muse_knowledge_processing_job` / `muse_projection_task` 只产投影和索引 | | 导出必须重验来源许可 | Export Task + Download Credential + Authorization Snapshot | @@ -1078,7 +1083,7 @@ Owner 约束： - `muse_source_snapshot(source_owner_module, source_type, source_object_id, source_version, source_hash)`。 - `muse_source_status_event(event_key)`。 - `muse_source_propagation_target(event_key, target_owner, target_type, target_id, target_version)`。 -- `muse_ai_system_function_chain_version(chain_id, version_no)`。 +- `muse_meta_function_chain_version(chain_id, version_no)`。 - `muse_ai_quality_policy_version(policy_id, version_no)`。 - `muse_ai_agent_slot_binding(work_id, slot_key)` 仅约束 `active_flag = true` 的 active 记录；inactive 历史允许多条。 - `muse_ai_agent_slot_precheck(precheck_id)`。 @@ -1097,7 +1102,7 @@ Owner 约束： 激活唯一约束： - MetaSchema：同一 `schema_key + effective_scope` 仅一条 `active_flag = true` 的 `muse_meta_schema_version`。 -- Function Chain：同一 `chain_id + effective_scope` 仅一条 `active_flag = true` 的 `muse_ai_system_function_chain_version`。 +- Function Chain：同一 `chain_id + effective_scope` 仅一条 `active_flag = true` 的 `muse_meta_function_chain_version`。 - Quality Policy：同一 `policy_id + effective_scope` 仅一条 `active_flag = true` 的 `muse_ai_quality_policy_version`。 ### 12.3 JSON 查询 diff --git a/design-docs/架构-01-系统全貌与边界上下文.md b/design-docs/架构-01-系统全貌与边界上下文.md index 33305a0c..ff802e5c 100644 --- a/design-docs/架构-01-系统全貌与边界上下文.md +++ b/design-docs/架构-01-系统全貌与边界上下文.md @@ -1,10 +1,11 @@ # 架构-01：系统全貌与边界上下文 -- 版本：v9 -- 更新日期：2026-05-24 +- 版本：v10 +- 更新日期：2026-07-09 - 目标读者：架构 / 后端 / 前端 / 产品 / 测试 - 阅读时间：25-35 分钟 - 边界说明：本文件只定义系统边界、有界上下文(Bounded Context, BC)、权威归属和跨上下文协作规则；不定义页面字段、数据库表结构、后端接口或完整状态机。精确模型约束见 `架构-02-核心数据结构与双轨模型.md`，精确生命周期见 `架构-04-状态机与约束清单.md`，产品功能见 `产品-02-核心功能与交互边界.md` 和 `产品-02A~02G`，流程链路见 `流程-01A/01B/02A/02B`。 +- 变更记录：v10（2026-07-09）§3.3 BC 落地矩阵订正系统功能链路归属——功能链定义与版本归 MetaSchema 模块、管理界面在 muse-admin、运行编排归 AI Orchestration runtime（案 A，见 `架构-03` ADR-022）。 ## 1. 系统边界（一句话） @@ -79,7 +80,7 @@ Muse 是面向长篇小说创作的多角色 AI 创作与资产流通系统。 | BC | 目标后端 owner | 聚合 / 模型 owner | Facade / API 分组 | 异步 worker | 审计 owner | |---|---|---|---|---|---| | Identity/Auth | `muse-auth` | 用户、角色、权限组、会话、安全事件 | Auth / Admin Permission / Personal Security | 会话清理、安全事件通知 | Account/Usage/Audit | -| Admin/Governance | `muse-admin` | 保护节点注册表（仅注册，实例归 AI）、系统功能链路、全局治理配置 | Admin Console | 配置影响预览 | Account/Usage/Audit | +| Admin/Governance | `muse-admin` | 保护节点注册表（仅注册，实例归 AI）、系统功能链路治理面（链路定义与版本归 `muse-meta-schema`、管理界面在 `muse-admin`、运行编排归 `muse-ai` AI runtime）、全局治理配置 | Admin Console | 配置影响预览 | Account/Usage/Audit | | MetaSchema | `muse-meta-schema` | MetaSchema 全局定义、字段类型、校验、枚举、引用、领域、范围、目标类型、可见性、AI 上下文、导出语义；admin 写入全局定义，用户可在作品级覆盖扩展字段 | Admin Console（全局定义）/ facade-api（只读消费） | MetaSchema 版本影响预览 | Account/Usage/Audit | | Work/Content | `muse-content` | Work、Chapter、Block、Block Source Attribution、Planning Item、Narrative State、Work Export Job | User Workspace / Work Workspace | 导入、作品导出、正文投影 | Account/Usage/Audit | | Knowledge | `muse-knowledge` | Local KB、User KB、Knowledge Draft、Knowledge Source Binding、Knowledge Export Job、投影和索引任务 | Knowledge Workspace / Work Knowledge | 资料处理、入 RAG、投影、知识导出 | Account/Usage/Audit | diff --git a/design-docs/架构-02-核心数据结构与双轨模型.md b/design-docs/架构-02-核心数据结构与双轨模型.md index e8c65a28..820b7b1a 100644 --- a/design-docs/架构-02-核心数据结构与双轨模型.md +++ b/design-docs/架构-02-核心数据结构与双轨模型.md @@ -1,10 +1,11 @@ # 架构-02：核心数据结构与双轨模型 -- 版本：v9 -- 更新日期：2026-06-19 +- 版本：v10 +- 更新日期：2026-07-09 - 目标读者：架构 / 后端 / 前端 / 产品 / 测试 - 阅读时间：35-50 分钟 - 边界说明：本文件定义核心模型、模型归属、双轨边界和跨模型不变式；不定义数据库字段、索引、接口路径或完整状态机。BC 边界见 `架构-01-系统全貌与边界上下文.md`，生命周期见 `架构-04-状态机与约束清单.md`，精确表结构和 API 由后端阶段承接。 +- 变更记录：v10（2026-07-09）§1.2 Canonical 入口封闭枚举增补「管理员确认系统级知识草稿 → Global KB 范式」；§2 订正功能链归属（定义归元引擎 Meta BC、运行编排归 AI runtime、Governance 为逻辑治理面）；§9 补 domain 逐值语义、base 与叠加（override 只增不改）与 target_type 命名规则，本体全清单 owner 指向专题-06。 ## 1. 双轨模型 @@ -26,6 +27,7 @@ | 用户接受 AI 候选 | 正文 Canonical 和候选 Archive | 不自动确认知识草稿；不绕过来源撤权和合规阻断 | | 用户确认规划候选 | 正式规划项或叙事状态 | 不把未确认候选送入后续生成上下文 | | 用户确认知识草稿 | 局域知识库(Local KB)正式知识 | 来源失效、撤权、下架、召回或冲突未解决时不能来源型确认 | +| 管理员确认系统级知识草稿 | 全局知识库(Global KB)范式 Canonical | 只确认管理员经拆书产出的公共范式草稿，走 Draft→确认→Canonical 同构链；不写用户私有作品事实或 Local KB，来源受限时不确认 | | 用户维护用户知识库 | 用户知识库(User KB)资料和版本 | 不自动绑定作品，不自动进入任何作品事实 | | 管理员发布系统配置 | 系统配置版本 | 不修改用户私有正文、用户智能体或用户知识库内容 | | 市场授权或安装 | License、Install、授权快照 | 不自动写作品事实、不自动关联作品、不转移所有权 | @@ -45,7 +47,7 @@ | 模型分区 | 归属 BC | 负责什么 | 不负责什么 | |---|---|---|---| | 账号、权限与安全 | Identity/Auth | 用户、管理员、角色、权限组、菜单、操作、数据范围、会话、安全事件 | 作品事实、市场授权事实、外部网关权威日志 | -| 系统治理配置 | Admin/Governance | 系统功能链路、开放槽位、系统 Prompt、系统智能体默认链路 | 用户私有作品内容和用户私有资产内容 | +| 系统治理配置 | Admin/Governance | 系统功能链路的逻辑治理面（发布/激活 authority；功能链定义与版本物理落元引擎 Meta BC、与 MetaSchema 同住，运行编排归 AI Orchestration runtime）、开放槽位、系统 Prompt、系统智能体默认链路 | 用户私有作品内容和用户私有资产内容 | | 元结构定义 | MetaSchema BC | MetaSchema 全局定义、字段类型、校验、枚举、引用、领域、范围、目标类型；admin 写入全局定义，用户可在作品级覆盖扩展字段，业务模块通过 facade-api 只读消费 | 用户私有作品内容和用户私有资产内容 | | 作品内容 | Work/Content | 作品、章节、文本块、正文版本、正文来源归因、导入正文、正式规划项、叙事状态和作品导出任务 | 系统配置、市场资产记录、用户知识库资料 | | 知识体系 | Knowledge | 局域知识库、用户知识库、全局知识资料处理、知识草稿、知识来源绑定、索引和投影 | 市场授权交易、智能体槽位、正文编辑事实 | @@ -253,6 +255,30 @@ MetaSchema 不负责： `uiVisible=false` 不等于不能参与 AI；`aiContext=true` 不等于用户可见；`exportable=true` 仍必须受 owner、授权、来源状态和导出许可约束。 +MetaSchema 的结构本体按 `domain` 与 `scope` 两根正交轴定位每个目标类型；下面三小节补齐此前 canonical 未写明的语义地基。结构本体的 20 型 target type 全清单（两轴对齐）、逐型字段合同与统一创作数据读取器合同，owner 在 `专题-06-元数据驱动的智能体架构.md`，本节只定义语义与叠加规则，不复制清单。 + +**domain 逐值语义** + +`domain` 描述结构所属的语义域，回答“这块结构属于哪个意义世界”，与实例落在哪个 BC 无关；`scope` 恒等于实例对象的粒度（work / chapter / block / entity / relation / event / agent）。 + +| domain | 一句话判据 | 承载 | +|---|---|---| +| content | 作者对作品的戏外承诺与计划，角色感知不到 | 作品容器、创作定位、大纲 | +| world | 角色可感知的戏内世界事实 | 世界观、地点、组织、力量体系、物品、事件、角色、关系 | +| narrative | 只关“怎么讲”、不关“讲什么”的叙事表达层 | 文风、节奏、技法、桥段、套路 | +| knowledge | 知识库域自身的资料资产结构，非知识实体的内容结构 | 参考作品档案、范式库目录 | +| ai_context | AI 上下文组装与输出合同的结构 | 生成上下文快照模具 | + +两条解耦判据：domain 只描述语义域、不描述存储 BC（Local KB 实体物理落 Knowledge BC，但其 schema 多属 world 或 narrative 域）；scope 恒为对象粒度、不承载系统级与作品级之分，后者走 `effective_scope`。 + +**base 与叠加** + +`base` 不是新机制：base = `effective_scope=全局` 的 active schema 版本（admin 全局定义），“内置”即系统 seed 出厂的那批全局 schema。一个作品可见的结构是三层叠加——全局 active ⊕ 类型灰度版本 ⊕ 作品级 override。**override 只增不改**：作品级只能扩展字段，不能删改全局字段的定义与可见性。继承靠动态合成、不靠复制：系统不落 per-work schema 实例，读取时按 projectionVersion 动态合成投影，新作品天然继承全部全局结构。 + +**target_type 命名规则** + +target_type 命名不带粒度后缀：同一概念在不同粒度出现时由 scope 轴表达粒度，type 名保持洁净，示例用 `character` 而非 `character_entity`。 + ## 10. 规划维度到模型边界 作品规划台(Planning Desk)是产品入口，不是新的模型集合。 diff --git a/design-docs/架构-03-关键决策与原则(ADR).md b/design-docs/架构-03-关键决策与原则(ADR).md index 23555746..4fd03d38 100644 --- a/design-docs/架构-03-关键决策与原则(ADR).md +++ b/design-docs/架构-03-关键决策与原则(ADR).md @@ -1,10 +1,11 @@ # 架构-03：关键决策与原则（架构决策记录(ADR)） -- 版本：v12 -- 更新日期：2026-06-29 +- 版本：v13 +- 更新日期：2026-07-09 - 目标读者：架构/前端/后端/产品 - 阅读时间：30-45 分钟 - 边界说明：这里只收敛架构原则和 ADR；工程结构、表结构、接口、状态机分别归属 `后端-02`、`后端-04`、`后端-05` 和 `架构-04`。本文件描述目标架构决策，不代表当前代码都已实现。 +- 变更记录：v13（2026-07-09）新增 ADR-022（系统功能链定义归属元引擎·案 A）与 ADR-023（双轨 Canonical 入口增补·管理员确认系统级知识草稿），并更新 §2 结论段。 ## 1. 架构原则（可执行） @@ -204,9 +205,25 @@ - 后果(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。 +需要。双角色入口、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. 关联阅读 diff --git a/docs/agent-specs/2026-07-08-AI能力与元数据驱动智能体架构-设计评审.md b/docs/agent-specs/2026-07-08-AI能力与元数据驱动智能体架构-设计评审.md new file mode 100644 index 00000000..1c6b5b51 --- /dev/null +++ b/docs/agent-specs/2026-07-08-AI能力与元数据驱动智能体架构-设计评审.md @@ -0,0 +1,568 @@ +# 系统 AI 能力全景 · 元数据驱动的智能体架构（设计 · 评审版） + +- 版本：v0.2（评审版，未执行） +- 更新日期：2026-07-08 +- 目标读者：创始人 / 架构 / 后端 / 前端 / 产品 +- 边界说明：本文回答四个悬而未决的架构问题——系统需要多少个 LLM 智能体、它们与 Dify 的关系、知识库如何分层、拆书如何完善系统级知识。术语以 `架构-02-核心数据结构与双轨模型.md` 为准；BC 边界见 `架构-01`；AI 链路合同见 `专题-03`；外部适配见 `专题-05`。本文是**评审版**：讲清 WHAT 与 WHY，供拍板；执行版与 canonical 落点见第八节，评审通过后再动代码与正式分册。 +- 事实基线：结论区分「已验证事实（读到代码/文档）/ 设计意图 / 待决策」。代码现状来自 2026-07-08 对 `muse-module-ai`、`muse-module-knowledge`、`muse-module-meta` 的只读盘点。 +- 变更记录：v0.2（2026-07-08）整合 Fable 边界分析与创始人三项材料级拍板（功能链归属案 A、双轨 Canonical 入口增补、参考作品库位案 A）及四项默认落定；补 domain 逐值语义与对齐后 20 型本体清单，新增统一创作数据读取器、作品容器建模、base 叠加与 storage_binding 存储映射；执行计划 W1 种子扩为 20 项四档、W8 双轨入口标记解锁。 + +--- + +## 0. 结论先行 + +一句话：**Muse 不是"一个功能挂一个 Dify app"，而是"一套元数据驱动的智能体编排"**。中枢是 muse-cloud 里的**元引擎（MetaSchema）+ 功能链（FunctionChain）**；每个智能体都是 `f(作品 + 元数据 + 知识库)` 的固定产品功能，元数据一变，同一个智能体的读入与产出就变。Dify 只是这套编排在"能力执行"与"检索基座"两处的可替换外部底座。 + +> **两条口径（贯穿全文）**：① **设计为 SoT，代码为辅**——凡代码与设计不符，是代码待修正（见第七节），不是弯设计迁就代码。② 本轮的硬产出是**三张咬合的权威清单**：Agent 清单、元数据类型清单、知识库清单，及三者对应矩阵（第六节）。 +> +> **一句话点出最大偏差**：设计里"元数据驱动智能体产出"这条主线，代码目前**是断的**——MetaSchema 只喂了 Content 动态表单、没喂 AI；功能链是治理台账、AI 不按它编排；AI 另走一套 `MuseAgentSlotBinding` 直连 Dify。要落地本设计，核心工作就是把这条线接通。 + +五问速答： + +1. **需要多少个 LLM 智能体？** 产品设计上是 **4 类开放能力智能体 ×（多场景）+ 3 类保护节点智能体 + 2 类知识基座**，远不止 3 个；当前**代码里真正发起 LLM 推理的只有 3 处**（写作生成、Agent 试运行、全书导入解析），检测/质检等仍是规则桩。差距在第三、七节。 +2. **每个功能都是一个 Dify workflow/app/agent 吗？** **不是，且是刻意的**。只有**开放槽位的能力子智能体**可以挂 Dify app/workflow（当前 2 个：写作、解析）；**保护节点**（质量门控、合规、静态检查、Shadow→Canonical）必须 Muse 自持，不能外包给 Dify；**检索**走 Dify Datasets（另一平面）。理由是主权（先审后入）与可替换性。 +3. **知识库分几库、怎么提供系统级能力？** 三库——**全局知识库（Global）/ 用户知识库（User）/ 局域知识库（Local）**；每库又有**两个正交面**——实体/图谱 Canonical 面（MetaSchema 结构化，存 PG）与文档/RAG 面（Dify dataset 检索）。系统级能力 = **全局知识库作为每个作品的默认可检索来源**，其内容由拆书喂养。 +4. **拆书是什么、怎么完善系统级知识？** 拆书是**元数据驱动的通用实体抽取智能体**：按 MetaSchema 定义的实体/属性类型，从文本"解析出对应实体 → 入库"。管理员用它拆几十上百本参考书 → 沉淀为全局知识库的**小说公共属性参考**（文风/叙事/节奏/转折/反转/抓手/打斗/情感/人设/物品描述…）；用户每确认一章，同一个拆书智能体 + 质量校验智能体也会跑，把本章实体入**局域知识库**。 +5. **dify-agent / dify-rag / muse-cloud 三体关系？** muse-cloud = 大脑与主权（元引擎/功能链/权限/双轨/编排）；dify-agent = 开放槽位的能力执行（app/workflow）；dify-rag = 检索基座（datasets）；底层模型统一经 New-API。见第二节。 + +> **本轮已拍板（2026-07-08）**：① **全量接通**元数据驱动主线（结构性重构，见第八节执行计划）；② 元数据结构本体经 Fable 边界精炼、并与 domain/scope 两轴对齐后**定稿 20 型（分 5 个本体分组，每型带一条 MECE 边界判据）**（第 6.2 A；剩余待确认见 6.2 D），全落为 MetaSchema target types；③ Local KB 实体强绑 schema_key；④ 全局库**显式绑定**检索。执行计划待创始人过审后再动代码。 +> +> **本轮新落定（2026-07-08，创始人材料级拍板）**：三项归属决策已定，驱动下方 §6.2、§7.2、第八、九节同步—— +> ① **功能链归属取案 A**：功能链定义与 MetaSchema 同住元引擎（Meta BC），表名 `muse_meta_function_chain/_version/_slot/_node` 不动；AI runtime 经 `FunctionChainQueryApi` 读激活链做运行编排。已验真——V3/V10 迁移建的就是这批 `muse_meta_function_chain*` 表、代码全在 muse-module-meta，落地零数据迁移。 +> ② **双轨 Canonical 入口增补获批**：`架构-02 §1.2` 的封闭枚举新增「管理员确认系统级知识草稿 → Global KB 范式 Canonical」一条，确认人是管理员，产出走 Draft→确认→Canonical 同构链；拆书系统级链路（W8）由此解锁。 +> ③ **参考作品库位取案 A**：`reference_work` 落 Global KB document 特化（Knowledge BC），复用 `muse_knowledge_document/_version/_processing_job` 既有资料处理链；拆书任务归 AI BC（新任务类型 reference_extraction）；版权受限经既有 Source Status Event→Propagation 阻断派生新使用、不回滚已确认。 +> +> **默认落定（主会话据 Fable 建议定，有异议可翻）**：④ 命名统一——示例 `character_entity` 收敛为 `character`（target_type 不带粒度后缀）、`relation` 更名 `character_relation`、测试 fixture `setting` 收编进 `world`；⑤ 双层型（style/pacing/craft）取单模具双库主案——一型一 schema，公共面实例落 Global KB 共用同一 schema，是否再拆 `*_paradigm` 由 W4 三样本"能否无损写进同一字段合同"实测终裁，W1 先落作品面种子不阻塞；⑥ `generation_context` 保留为 Context Assembly Snapshot 的字段模具（domain=ai_context、scope=agent），消费者是质量评测输入与审计；⑦ `storage_binding` 存储映射随 W1 落——`muse_meta_field` 增 native_column / extension_json / computed 属性，承载容器 schema 对 Work 固定列的元描述。 + +--- + +## 1. 中枢：元数据驱动的智能体架构 + +这是理解全部问题的钥匙，先讲清楚，后面四问都是它的推论。 + +### 1.1 两个中枢：元引擎与功能链 + +muse-cloud 的 `muse-module-meta` 里有两套东西，它们是所有 AI 能力的骨架（已验证：建表与 DO 齐全）： + +- **元引擎 / MetaSchema**（`muse_meta_schema / _field / _version / _visibility / _gray_rule / _validation`）：可配置的**创作域本体**。它定义"一个人物有哪些属性、一个设定有哪些字段、一段文风从哪些维度刻画、一次转折由哪些要素构成"，以及每个字段是否可见、可编辑、可检索、**是否可进入 AI 上下文（`aiContext`）**。按 `架构-02 §9`，MetaSchema 的职责就是"**约束提取、规划、检查、投影和上下文组装**"——这正是智能体的读入与产出。 +- **功能链 / FunctionChain**（`muse_meta_function_chain / _node / _slot / _node_protection`）：**系统预编排的能力链路**。一条链由若干节点组成，节点分两种——**开放槽位（Override Slot）**允许替换子智能体，**保护节点（Protection Node）**不可替换。这就是 `专题-03` 说的"系统功能编排 + 开放替换槽位 + 不可替换保护节点"落到数据模型。 + +一句话区分：**MetaSchema 定义"结构"，FunctionChain 定义"流程"**。 + +### 1.2 每个智能体 = f(作品 + 元数据 + 知识库) + +这是创始人本轮点明、且被 `架构-02` 证实的核心论断。任何一个智能体运行时，都同时结合三样东西： + +| 输入维度 | 来自 | 作用 | +|---|---|---| +| **作品（Content）** | Work/Content BC：当前正文、章节、近邻 Block、正式规划、叙事状态 | 提供"写什么/改什么/查什么"的对象与近邻语境 | +| **元数据（MetaSchema）** | Meta BC：实体类型、字段、枚举、校验、`aiContext` 开关、输出合同 | 决定"读哪些字段、抽哪些实体、产出什么结构"——**是产出结构的模具** | +| **知识库（Knowledge）** | Knowledge BC：局域知识库 Canonical 实体、授权的全局/用户知识库检索片段 | 提供"作品事实"与"公共参考"两类支撑 | + +由此得到本架构最重要的性质：**智能体"类型"是固定的产品功能（功能链节点写死），但产出是元数据驱动的动态结果**。管理员在元引擎里给"设定"实体加一个字段"金手指类型"，或给"文风"加一个维度"反转密度"——不改一行智能体代码，拆书就会多抽这个属性、规划会多生成这个字段、质检会多查这个维度。这就是"固定类型 + 元数据变则产出变"。 + +```mermaid +flowchart TB + subgraph Meta["元引擎 MetaSchema（结构模具）"] + MS["实体类型/字段/枚举/校验
aiContext 开关/输出合同"] + end + subgraph Chain["功能链 FunctionChain（流程骨架）"] + direction LR + N1["保护节点
输入合规/权限过滤"] --> SLOT["开放槽位
能力子智能体"] --> N2["保护节点
质量门控/输出合规/Shadow→Canonical"] + end + subgraph Ctx["三结合上下文"] + W["作品 Content"] + K["知识库 Knowledge"] + end + MS -.约束读入与产出结构.-> SLOT + MS -.定义可入AI字段.-> Ctx + W --> SLOT + K --> SLOT + SLOT -->|候选/草稿/风险| Shadow["Shadow 待审"] + Shadow -->|用户确认| Canonical["Canonical 正式事实"] +``` + +--- + +## 2. 三体关系：dify-agent / dify-rag / muse-cloud（Q5） + +先破一个误解：**dify-agent 与 dify-rag 不是两套部署，而是同一个 Dify 实例的两个功能平面**，靠两类 API key 区分（已验证：app key 前缀 `app-` 只能打 app/workflow；dataset key 前缀 `dataset-` 只能打 datasets，混用 401）。三者关系如下： + +| 角色 | 是什么 | 持有什么 | 访问方式 | 边界 | +|---|---|---|---|---| +| **muse-cloud** | 大脑与主权 | 元引擎、功能链、权限包（RPE）、双轨（Shadow/Canonical）、审计、用量归属、datasetId 映射、编排 | —— | **业务事实源与权限裁判**；绝不让外部写 Canonical | +| **dify-agent** | 开放槽位的能力执行 | Dify chat/workflow app（当前 2 个：`dify-writing-s1` 写作、`dify-parser-s1` 解析） | app key（`MUSE_AI_DIFY_*`），端点 `/chat-messages`、`/workflows/{id}/run` | 只是"能力节点"，只返回**候选**，不是可入库事实 | +| **dify-rag** | 检索基座 | Dify Datasets（当前"每 KB 一库"物理隔离） | dataset key（`MUSE_KNOWLEDGE_DIFY_*`），端点 `/datasets/*/retrieve` 等 | 检索基座**≠事实源**；缺来源/授权的结果不进上下文 | +| **New-API** | 底层模型网关 | 真实模型（MiniMax-M2.5 + Qwen 向量/重排） | Dify 经 openai_api_compatible 插件连它；muse-cloud 也可直连 | **用量/成本/归属的权威**；Dify 用量只作脱敏审计 | + +主权原则一句话：**Muse 编排，Dify 执行，Muse 裁判**。Dify（两个平面）都是可替换外部底座——指定 Dify 却未配置时 fail-closed（已验证：绝不回退 New-API 伪成功）；Dify 全挂时 Muse 也只失败关闭，但用户读/存 Canonical 不受影响。 + +一次生成的完整数据流： + +```mermaid +sequenceDiagram + participant U as Studio 用户 + participant M as muse-cloud（编排+主权） + participant R as dify-rag（检索） + participant A as dify-agent（写作app） + participant N as New-API（模型） + U->>M: 续写请求 + M->>M: 生成运行权限包 RPE + 按 MetaSchema 组装上下文（作品+元数据） + M->>R: 按授权检索（全局+作品+绑定KB 的 dataset） + R->>N: 向量检索/重排 + R-->>M: 授权片段（带来源/状态） + M->>A: 组装后的上下文 → 写作 app + A->>N: 模型推理 + A-->>M: 候选（仅候选） + M->>M: 保护节点：静态检查/质量门控/输出合规 → Shadow 候选 + M-->>U: 候选 + 创作健康度解释 + U->>M: 接受/改后合并/丢弃 + M->>M: 写 Canonical 正文 + 来源归因 +``` + +--- + +## 3. 系统 LLM 能力全景：多少个智能体、是否都是 Dify app（Q1） + +### 3.1 不是"每功能一个 Dify app"——三层智能体 + +按主权边界，智能体分三层，**只有第一层可以挂 Dify app**： + +- **第一层 · 开放能力子智能体（可替换，可挂 Dify app/workflow / New-API / 用户/市场智能体）**：写作、分析/拆书、检测、规划。这是用户和市场能插入自定义能力的地方，也是 dify-agent 的落点。 +- **第二层 · 保护节点智能体（Muse 自持，即使用 LLM 也不外包为可配置 Dify app）**：质量门控 / LLM-Judge、输入输出合规与语义围栏、知识入库校验。它们是"先审后入"主权的执行者，若需 LLM 只走受控内部路径（直连 New-API 或一个**受限**评测 app），绝不做成用户可替换的能力槽位。 +- **第三层 · 知识基座（非"app"）**：RAG 检索走 dify-rag；切块/入 RAG/索引是保护节点。 + +这样切分的原因有三：**主权**（Shadow→Canonical 不能被外部替换）、**可替换性**（同一开放槽位可在 Dify↔New-API↔AgentScope 间换而不动主链）、**可解释与可审计**（保护节点必须产出 Muse 可追溯的结论）。 + +### 3.2 设计全集 vs 代码现状 + +| 智能体（能力目标 × 场景） | 层 | provider 落点 | 设计 | 代码现状（2026-07-08，已验证） | +|---|---|---|---|---| +| 写作：续写/改写/扩写/润色/纠错/去AI味/角色声音 | 开放 | Dify 写作 app 或 New-API（按 Agent 版本 `runtimeProvider`） | ✅ | ✅ 已接（一条通用生成链 + 场景参数；`dify-writing-s1`/New-API） | +| 分析/拆书：全书解析/章节实体抽取/摘要/结构拆解 | 开放 | Dify 解析 app 或 New-API（按 `import.provider`，缺省 Dify） | ✅ | 🟡 仅"全书导入解析"接了 LLM（`dify-parser-s1`）；**按元数据抽实体、每确认章跑拆书**未接 | +| 检测：一致性/角色声音/文风/风险/语义偏离 | 开放 | Dify/New-API | ✅ | 🔴 **规则桩**（候选轻量审=纯字符串扫描，非 LLM） | +| 规划：大纲/世界设定/人设生成 | 开放 | Dify/New-API | ✅ | 🔴 未见独立 LLM 规划链 | +| 质量门控 / LLM-Judge | 保护 | Muse 内部（New-API/受限 app） | ✅ | 🔴 **确定性 hash 打分桩**（注释明写"后续接 LLM judge"） | +| 输入输出合规 / 语义围栏（Moderation） | 保护 | Muse 内部 | ✅ | 🟡 规则扫描桩 | +| 离线质量评估 | 保护 | Muse 内部 | ✅ | 🔴 确定性打分桩 | +| RAG 检索 | 基座 | dify-rag（datasets） | ✅ | ✅ 已接（每 KB 一库循环检索合并） | +| 知识抽取入库（拆书的入库端） | 保护 | Muse 内部 | ✅ | 🟡 草稿→确认→Canonical 机制在，LLM 抽取未接 | + +**结论**：真正在跑 LLM 的是 3 处（写作生成、Agent 试运行、全书解析）；产品设计的智能体全集约 9 类，多数当前是规则桩或未接。所以"当前 3 个"是**代码进度**，不是**产品应有的智能体数**。 + +--- + +## 4. 知识库分层：三库 × 两面（Q2 前半 + Q3） + +### 4.1 三库（已验证：`架构-02 §4`、代码 KB_TYPE） + +| 库 | 归属 | 用途 | 进入作品的方式 | 对应用户说法 | +|---|---|---|---|---| +| **全局知识库 Global KB** | 平台/管理员 | 写作方法、公共资料、**拆书产出的小说公共属性参考** | 管理员授权后作为可见/可检索/可生成的**系统默认来源** | "系统级/公共知识库参考" | +| **用户知识库 User KB** | 普通用户 | 跨作品复用的个人资料资产 | 用户显式绑定到作品 | 用户自建可复用库 | +| **局域知识库 Local KB** | 单个作品 | **当前作品的正式知识、世界状态、叙事状态** | 只能由用户确认知识草稿或手动修正写入 | "作品私有知识库，维护作品内所有内容" | + +### 4.2 两个正交面（本轮盘点最关键的澄清） + +每个库其实横跨两条**机制不同**的数据面，不能混谈： + +- **实体/图谱 Canonical 面**（存 PG，MetaSchema 结构化）：`muse_knowledge_draft`（Shadow）→ 用户确认 → `muse_knowledge_entity / _relation`（Canonical）+ 属性变更历史。这是"故事圣经"——角色/地点/组织/物品/事件及其关系与时间线。图查询直接读本地 PG。**这才是"维护作品内所有内容"的载体**。 +- **文档/RAG 面**（存 Dify dataset）：上传的参考资料文档 → 切块索引 → 语义检索。它只是**喂生成的语料**，不是结构化事实。（已验证：草稿确认入库**不进** Dify dataset；实体/关系落 PG。） + +```mermaid +flowchart LR + subgraph LocalKB["局域知识库 Local KB（作品私有）"] + direction TB + subgraph Fact["实体/图谱 Canonical 面（PG · MetaSchema 结构化）"] + D["知识草稿 Shadow"] -->|用户确认| E["实体/关系/时间线 Canonical"] + end + subgraph Rag["文档/RAG 面（Dify dataset）"] + Doc["上传资料"] --> Idx["切块索引 → 语义检索"] + end + end + Chapter["用户确认的章节正文"] -->|拆书智能体抽实体| D + Chapter -->|质量校验智能体查一致性| RM["风险/一致性结果"] + E -->|一致性检查来源| RM +``` + +### 4.3 作品级知识库的创建与维护（Q3） + +Local KB **不在知识库工作台直接编辑**，只通过作品工作台的 Shadow→Canonical 确认链维护。三条产知识的入口： + +1. **导入旧稿**：上传 → 全书解析（拆书智能体）→ 章节解析结果 → 用户逐章审阅 → 知识草稿 → 确认 → Local KB。 +2. **写作过程**：用户每确认一章正文，**拆书智能体**按 MetaSchema 抽本章新实体/关系 → 知识草稿；**质量校验智能体**同时查与既有 Local KB 的一致性 → 风险标记。（这正是创始人本轮点明的"每个用户确认的章节，也会走拆书智能体和质量校验智能体"。） +3. **手动修正**：用户直接改实体/关系（走确认链，留 change log）。 + +核心不变式（`架构-02 §1`）：**接受 AI 候选只写正文，不自动确认知识草稿**；知识入 Local KB 必须用户单独确认。冲突时人工、默认自动（核心架构决策）。 + +### 4.4 统一创作数据读取器（AI 上下文的服务端读 facade） + +`f(作品 + 元数据 + 知识库)` 里"读入"这一半，落在一个专门的读取层上。它不是第四套读设施，而是把既成的 Context Assembly（`专题-03 §4`）取数面显式分层为 AI Orchestration 内部的**服务端读取器**：按 actor、作品、分区请求与授权上下文，经各 owner 的 facade-api 拉数——Content 出作品容器/章节/正式规划/叙事状态，Knowledge 出 Local KB 实体、关系、事件与绑定库检索，Meta 出模具投影——再对每条数据套上该 target type 的 active MetaSchema 投影，做字段级 `aiContext` 裁剪、按 target type 结构化、附来源标注。Context Assembly 消费它完成 L0–L3 组装与 Token 预算；检测、导出预检等非生成链路复用同一读取器，不各自重写取数与裁剪。 + +它与用户面的 meta-projections **同源不同面**：共享模具投影的计算，不共享裁剪策略——用户面按 `uiVisible`/`userEditable` 裁，AI 面按 `aiContext` 裁，两者互不蕴含（`架构-02 §9`）。一条负约束必须写死：读取器只作为服务端内部端口存在，**不暴露为通用 app API**，否则它会成为与"通用写 SDK"对称的滥用面。 + +读统一、写各 owner。写侧零新设计——动态字段没有跨 owner 通用写接口（`后端-05 §4.3`）、禁通用写 SDK（`前端-03 §5.2`）、Canonical 入口是封闭枚举、agent 产出只进 Shadow，这些约束一条不改。统一读取器对写的唯一贡献，是沿用 `/dynamic-fields/validate` 的"校验 + 路由建议、不写入"语义，把"agent 想改哪个字段"翻译成"该走哪个 owner 的命令"。 + +**最小读合同**—— + +- **输入**：actor；workId；分区请求集（作品容器 / 规划 / 按 target_type + scope 过滤的 Local KB 实体 / 仅限已绑定 Global KB 的公共范式，对齐"显式绑定不自动注入"）；`runtimePermissionEnvelope` 引用（`allowedContextScopes` 是分区许可上限，只能收紧不能放宽）；purpose（generation/detection/planning/parse，授权按用途裁，对齐 `专题-03 §4.3`"允许阅读 ≠ 允许进 AI 上下文"）；期望 schemaVersion（可选，防任务中途版本漂移）。 +- **输出**：分区化的结构块列表，每块含 `targetType`、`schemaKey`、`schemaVersion`、已按 `aiContext` 裁剪的结构化字段值、`dataRevision`、来源标注七要素（`sourceOwner`/`sourceObject`/`sourceVersion`/`sourceStatus`/`authorizationSnapshotId` 等，对齐 `专题-03 §5.3`）、`omittedFields` 及原因；受限来源整块进 `omittedSources`（fail-closed，原因枚举复用 `专题-03 §4.2` 六值）。 + +裁剪分三级、同时生效：**字段级**（`aiContext=false` 的字段剔除）、**来源级**（状态受限的来源整块不进）、**用途级**（`allowedPurpose` 不含本次 purpose 的剔除）。任一级判定剔除，数据即不进上下文，并在 `omittedFields`/`omittedSources` 留痕可审计。 + +--- + +## 5. 拆书：元数据驱动的实体抽取智能体（Q2 后半） + +### 5.1 拆书的正确定位（按创始人本轮澄清） + +拆书**不是**管理员专用的一次性管线，而是一个**通用智能体**：`拆书(文本, MetaSchema, 目标库) → 按 MetaSchema 定义的实体类型解析出实体 → 入库（Shadow→Canonical）`。同一个智能体，两个用场： + +- **系统级（管理员）**：把几十上百本参考书拆成**小说公共属性/关键属性参考**，沉淀进**全局知识库**。产出的是**抽象属性与技法范式**，不是逐字原文（版权 + `专题-03` 禁"作品资产模板化"）。 +- **作品级（用户）**：每确认一章，拆本章实体入**局域知识库**。 + +一个拆书智能体、两处用、产出结构都由 MetaSchema 决定——这就是"元数据驱动"的价值：管理员维护一套属性本体，系统级参考库与作品级实体库共用同一套结构，天然对齐。 + +### 5.2 拆书的目标本体 = MetaSchema 的实体/属性类型 + +创始人列的属性（文风/叙事/文采/转折/节奏/反转/抓手/打斗/情感/人设/物品描述…）应落为 MetaSchema 的 target type 与字段。建议的分类树（**待评审，非最终**）： + +```text +小说公共属性本体（MetaSchema target types） +├── 文风类 style +│ ├── 句式/用词/视角/语气/文采 +│ └── 文风指纹（用于风格对标/漂移检查） +├── 叙事结构类 narrative +│ ├── 节奏/张力曲线/信息密度 +│ ├── 转折·反转（类型/铺垫/触发/效果） +│ └── 抓手·钩子（开篇钩/章末钩/悬念） +├── 桥段·套路类 trope +│ ├── 打斗（招式/节奏/伤亡/场面调度） +│ ├── 情感（情绪弧/关系张力/爆发点） +│ └── 爽点/伏笔（埋设/回收） +├── 人物类 character +│ └── 人设（外貌/性格/动机/弱点/弧光/说话方式） +├── 世界设定类 world +│ └── 世界观/力量体系/金手指类型/组织/地点/规则 +└── 物品类 item + └── 物品描述（外观/功能/来历/象征） +``` + +现有设计已有"文风/叙事/节奏/伏笔"等**高层概念散落**在质量维度（`专题-04`）与作品设定属性里，但**没有**一套结构化的"拆书公共属性参考库"；而 MetaSchema 的生产种子实为空——生产迁移 V1–V37 零 seed INSERT，`work_core`/`setting` 只存在于测试 fixture 与文档示例（详见 §6.2 base 清单的现状纠正）。所以这是**真实缺口**，也印证了创始人"设计里应有类似内容"的直觉——概念在、结构化本体不在，起点比原以为的更低。 + +### 5.3 拆书如何提供"系统级能力" + +全局知识库作为**每个作品的默认可检索来源**：写作/规划智能体在组装上下文时，除了作品自身的 Local KB，还会检索全局属性参考库（例如"写打斗桥段时，检索公共库里的打斗节奏范式"）。这就是"提供每个作品都需要的公共知识库参考"。 + +**已决策（2026-07-08 创始人拍板）**：全局公共库**走显式绑定，不自动注入**。用户/管理员把全局公共属性库绑定到作品后才进入检索选库集；沿用当前 binding 机制，用量归系统、口径可控。拆书系统级产出入全局库后，作为**可绑定的系统来源**供作品选用。 + +### 5.4 参考作品档案与范式溯源（2026-07-08 落定） + +系统级拆书要吃进几十上百本参考书，这些书本身得有个落处。它就是 `reference_work`（domain=knowledge、scope=entity）——一份**系统侧的资料资产档案**，不是用户创作事实。字段合同分四组：**标识**（书名、作者、品类、别名）、**来源**（上传 / 公开语料 / 授权采购）、**版权授权状态**（`licensed`/`public_domain`/`research_only`/`unauthorized`，其中 `unauthorized` fail-closed，不进任何拆书任务）、**拆书处理状态**（`pending`/`parsing`/`extracted`/`curated`/`failed`）。 + +它**不复用 `muse_content_work` 表**：参考作品的 owner 是系统、生命周期是"采购→拆解→归档"，与用户创作的"起草→连载→完结"是两码事；塞进 Content 会违反"Content 只拥有正文和作品结构"的边界。但字段层可以经 MetaField 引用**复用容器 schema 的公共字段组**（书名/作者/品类这类标识字段无须重定义）。库位取案 A：落 Knowledge BC 的 document 特化，复用 `muse_knowledge_document/_version/_processing_job` 既有资料处理链；拆书任务本身归 AI BC（新任务类型 reference_extraction）。 + +范式的溯源（lineage）**不新设 target_type、不新建表**。每条进 Global KB 的范式 Canonical 记录带上 `source_snapshot_id` 与 `lineage_payload`，指向它的 `reference_work` + 拆书 job + 章节定位摘要——**只存定位摘要，不存原文段落**（版权 + `专题-03` 禁"作品资产模板化"）。"某本书贡献了哪些范式"不是一张新表，而是**按 lineage 的读模型投影**。当某参考作品版权状态收紧，走既有 Source Status Event → Source Propagation：**阻断该来源派生范式的新使用，但不回滚已确认的 Canonical**——与知识域现有来源传播语义一致，零新机制。 + +--- + +## 6. 三张权威清单：Agent × 元数据类型 × 知识库（本轮确定） + +本节是本轮要"定下来"的核心。三张清单以**设计文档为 SoT**（代码为辅、可能需改）；它们相互咬合——每个 Agent 都是 `f(作品 + 元数据 + 知识库)`，用哪些**元数据类型**、读写哪些**知识库**在 6.4 对应矩阵里定死。 + +### 6.1 Agent 清单 + +统一口径：agent = 使用大模型的能力节点。**类型固定（对应系统功能链的节点/槽位），产出由元数据驱动**。分三层，只有第一层可挂 Dify app。 + +#### 6.1.1 开放能力子智能体（可挂 Dify / New-API / 用户/市场智能体） + +| Agent | 做什么 | 依赖（作品+元数据+知识库） | 产出 | 目标与边界 | +|---|---|---|---|---| +| **写作 Agent** | 续写/改写/扩写/润色/纠错/去AI味/角色声音 | 近邻正文 + MetaSchema(style/narrative) + Local KB & 检索片段 | AI 候选（Shadow） | 只进 Shadow；不写 Canonical；不替换保护节点 | +| **拆书/分析 Agent** | 按 MetaSchema 从文本抽实体/关系；全书解析/章节抽取/摘要/结构拆解 | 文本 + MetaSchema(实体类型) + 目标库（Global/Local） | 知识草稿（Shadow）/ 章节解析结果 | 不写 Canonical 知识；章节审阅后才建草稿；系统级只产抽象属性不留原文 | +| **检测 Agent** | 一致性/角色声音/文风/风险/语义偏离检查 | 候选或正文 + MetaSchema(检查约束) + Local KB Canonical | 一致性结果/风险标记/建议 | 不直接改正文或知识；只产解释与定位 | +| **规划 Agent** | 生成大纲/世界设定/人设 | 作品方向 + MetaSchema(world/character/outline) + Local KB | 规划候选（Shadow） | 未确认候选不得进后续生成上下文 | + +#### 6.1.2 保护节点智能体（Muse 自持，不可外包为可配置 Dify app） + +| Agent | 做什么 | 依赖 | 产出 | 目标与边界 | +|---|---|---|---|---| +| **质量门控 / LLM-Judge** | 候选交付前按 MetaSchema 质量维度评分 + Shadow 内有限重写 | 候选 + 质量策略版本 + 上下文快照 + Local KB | Candidate Quality Result（qualityState） | 只处理 Shadow；硬阻断优先级高于叙事评分；不写正文 | +| **合规/语义围栏（Moderation）** | 输入输出合规、隐私、prompt 注入 | 输入/输出文本 + 合规策略 | 合规结论（hardBlock） | fail-closed；不可被质量分放开 | +| **离线质量评估** | 对智能体/Prompt/策略跑评估集回归 | 评估集 + 脱敏样本 | 评估报告（发布建议） | 不影响用户当前候选；禁用私有正文全文 | + +#### 6.1.3 知识基座 + +| 组件 | 做什么 | 依赖 | 产出 | 边界 | +|---|---|---|---|---| +| **RAG 检索** | 按授权从 Global+作品+绑定库的 Dify dataset 循环检索合并 | binding + 授权快照 + dify-rag | 检索片段（带来源/授权/状态） | 检索基座≠事实源；缺来源/授权不进上下文 | +| **切块/入 RAG/索引** | 资料摄入与索引 | 上传资料 | dataset 索引 | 保护节点；处理未过不得进生成上下文 | + +> 命名与"功能链节点"的对应：`生成链→写作Agent`、`分析/导入解析链→拆书Agent`、`检测链→检测Agent`、`规划链→规划Agent`、`知识处理链→拆书入库+RAG`、`质量链/合规→保护节点智能体`。功能链是编排骨架，Agent 是槽位里的能力。 + +### 6.2 元数据类型清单（多类多层，非平铺） + +元数据**不是一张 11 项的平表**。它按**用途分 5 个元数据用途类**，其中只有第一类（结构本体）是"实体有哪些属性"、被拆书/生成直接消费；结构本体本身又是 **本体分组 → target type → 属性** 三层，且是**开放集**（管理员可增类型、用户可在作品级扩字段，`架构-02 §9`）。所以"固定"的是**几个用途类**，类型与属性可增长。为免两处"大类"串词，下文一律称第一层切分为**元数据用途类**（5 类），称结构本体内部的分组为**本体分组**（骨架作品/骨架世界/人物/画像/技法）。 + +**5 个元数据用途类：** + +| 大类 | 管什么 | 载体 | 谁用 | +|---|---|---|---| +| **① 结构本体** | 实体有哪些属性（拆书抽/生成写/检测查的结构模具） | MetaSchema target types（下表 A） | 拆书/写作/规划/检测 | +| **② 质量维度** | 怎么评判好坏 | Quality Policy（下表 B，`专题-04`） | 质量门控/离线评估 | +| **③ 编排** | 智能体怎么串 | FunctionChain：链/节点/开放槽位/保护节点 | AI runtime 编排 | +| **④ 智能体配置** | 每个能力怎么配 | Agent Version：prompt/模型绑定/工具授权/输出合同/槽位兼容 | 各 Agent | +| **⑤ 可见与策略** | 每字段的权限行为 | MetaVisibilityPolicy（`aiContext`/`uiVisible`/`userEditable`/`userSearchable`/`exportable`）+ 灰度 + 校验 | 上下文组装/授权 | + +**前置地基：domain 与 scope 两轴** + +结构本体的每个 target type 先由两根正交的轴定位；`canonical` 此前从未把它们讲清，这里补成地基。**domain 描述语义域，不描述存储 BC**——它回答"这块结构属于哪个意义世界"，与实例落在哪个 Bounded Context 无关（Local KB 实体存 Knowledge BC，但其 schema 多属 world 或 narrative 域）。**scope 恒等于实例对象的粒度**，取值是 work/chapter/block/entity/relation/event/agent 之一；系统级与作品级之分不占 scope 轴，走 `effective_scope`。 + +五个 domain 的判据： + +| domain | 一句话判据 | 承载 | +|---|---|---| +| `content` | 作者对作品的**戏外**承诺与计划，角色感知不到 | 作品容器、创作定位、大纲 | +| `world` | 角色可感知的**戏内**世界事实 | 世界观/地点/组织/力量体系/物品/事件/角色/关系 | +| `narrative` | 只关"怎么讲"、不关"讲什么"的叙事表达层 | 文风/节奏/技法/桥段/套路 | +| `knowledge` | 知识库域自身的资料资产结构（非知识实体的内容结构） | 参考作品档案、范式库目录 | +| `ai_context` | AI 上下文组装与输出合同的结构 | 生成上下文快照模具 | + +一处同词提醒：target type `world`（世界观总纲，一个具体的结构型）与 domain `world`（世界事实语义域）字面相同却分属两轴——前者是"型"、后者是"域"，不是一回事。 + +**A. 结构本体（对齐后 20 型 · domain/scope 两轴 · Fable 边界精炼）** + +下表是与两轴对齐后的 target type 全清单，给的是归属、粒度与落地状态的总览；逐型的字段合同与边界判据见其后的分组详表。 + +| # | domain | scope | target_type | 中文名 | 本体分组 | 状态 | +|---|---|---|---|---|---|---| +| 1 | content | work | `novel_work` | 作品容器 | 容器 | 既成表实体 + 既成示例；schema 化是本轮新增 | +| 2 | content | work | `work_core` | 作品核心 | 骨架·作品 | 已拍板；fixture 既有 | +| 3 | content | work | `outline` | 大纲 | 骨架·作品 | 已拍板待落 | +| 4 | world | work | `world` | 世界观总纲 | 骨架·世界 | 已拍板待落（fixture `setting` 收编至此） | +| 5 | world | entity | `location` | 地点 | 骨架·世界 | 已拍板待落 | +| 6 | world | entity | `faction` | 组织阵营 | 骨架·世界 | 已拍板待落 | +| 7 | world | entity | `power_system` | 力量体系 | 骨架·世界 | 已拍板待落 | +| 8 | world | entity | `item` | 物品 | 骨架·世界 | 已拍板待落 | +| 9 | world | event | `event` | 事件 | 骨架·世界 | 已拍板待落；`muse_knowledge_event` 表既有 | +| 10 | world | entity | `character` | 角色 | 人物 | 已拍板待落；统一自示例 `character_entity` | +| 11 | world | relation | `character_relation` | 角色关系 | 人物 | 已拍板待落；自 `relation` 更名 | +| 12 | narrative | work | `style` | 文风画像 | 画像 | 已拍板待落 | +| 13 | narrative | work | `pacing` | 节奏画像 | 画像 | 已拍板待落 | +| 14 | narrative | entity | `craft` | 叙事技法 | 技法 | 已拍板待落 | +| 15 | narrative | entity | `combat` | 打斗桥段 | 技法 | 已拍板待落 | +| 16 | narrative | entity | `emotion` | 情感桥段 | 技法 | 已拍板待落 | +| 17 | narrative | entity | `scene_pattern` | 通用桥段 | 技法 | 已拍板待落 | +| 18 | narrative | entity | `trope` | 套路 | 技法 | 已拍板待落 | +| 19 | knowledge | entity | `reference_work` | 参考作品档案 | 系统侧 | 本轮新增（见 §5.4） | +| 20 | ai_context | agent | `generation_context` | 生成上下文 | 配套 | 既成示例，语义已钉（快照模具） | + +scope 落座有两处最容易被误判，须点明。`outline` 取 `work` 而非 chapter：scope 是实例集合的聚合归属粒度，大纲是全书单一计划，其内部的全书/卷/章三层用字段表达层级，不改 scope。`world` 取 `work`：按既有边界判据它"不可数、无法单章出场"，是每作品一份的单例总纲，故归 work 而非 entity。 + +**精炼原则——一型一格位、一概念一 owner**：一个候选挣得独立 target type，须同时占据"它是什么（实体/计划/画像/装置/范式）× 谁在何时消费（规划/写作/检查期）"平面上的一个空格位，且承载邻接型收编不了的字段合同；否则按三规则降级——**变体收进枚举**（差异只能举例、给不出判据的，如拍卖会/比武会）、**投影收进读模型**（属性可由他型查询导出的，如时间线/关系网/伏笔看板）、**附属收进字段**（离开某型无独立生命的，如金手指例外）。这条准绳兑现"**类型可更多**（格位平面开放、品类增型走同一判据）但**边界必清晰**（判据说不出一句就降级为枚举，杜绝为拆而拆）"。 + +**"一个概念落一个还是多个 target type"的四判据**（与上面三条降级规则叠加使用）：① **粒度判据**——两个用场里实例挂靠的粒度不同（work 级单例画像 vs entity 级多条目），倾向拆；② **字段合同判据**——字段交集不足一半、或校验规则互斥，拆；③ **消费判据**——仅消费链路不同而字段相同，不拆，消费差异走可见性策略；④ **写入路径判据**——进 Canonical 的入口不同（用户直接命令 vs 确认链），倾向拆。四判据回答"拆不拆"，三条降级规则回答"不拆时降到哪一级"。 + +**三层浇铸**：结构骨架=只浇作品事实实例（入 Local KB/Planning）；公共参考=只浇跨作品范式（系统级拆书入 Global KB，只存抽象范式+脱敏例证、不留原文）；双层=两处都浇。所有型共享基础字段（名称/别名/摘要/标签），下列只标特有字段。 + +**第 1 组 · 作品骨架（戏外：作者对作品的承诺与计划）** + +| key·中文 | 关键字段（特有） | 层次 | 边界判据（纳入 ‖ 排除→归哪） | +|---|---|---|---| +| `work_core` 作品核心 | 题材/主题立意/基调/禁区/结局方向 | 骨架 | 只有作者读者知、**角色感知不到**的作品级承诺 ‖ 角色可感知世界事实→`world`；逐章安排→`outline` | +| `outline` 大纲 | 层级+父级引用/目标/摘要/主支线/情节节拍/伏笔引用 | 骨架 | 对"接下来写什么"的**计划**（全书/卷/章任一层级）‖ 戏内已定事实→`event`；跨作品公式→`trope`；伏笔定义→`craft`（只挂引用） | + +**第 2 组 · 世界设定（戏内：角色可感知的世界事实）** + +| key·中文 | 关键字段（特有） | 层次 | 边界判据 | +|---|---|---|---| +| `world` 世界观总纲 | 时代文明/地理格局/法则总纲/社会秩序 | 骨架 | 角色可感知但**不可数、无法单章出场**的世界级规则格局 ‖ 可指名出场者→`location`/`faction`/`item`；决定强弱排序→`power_system`；作者层定位→`work_core` | +| `location` 地点 | 地理环境/势力归属/功能氛围/主线关联 | 骨架 | **可到达、可发生场景**的具名空间 ‖ 弥漫地理→`world`；空间上的组织→`faction` | +| `faction` 组织阵营 | 宗旨立场/层级/核心成员引用/资源/对主角态度 | 骨架 | 有宗旨/层级/成员的具名集体（含组织化种族、朝廷）‖ 无组织的文明背景→`world`；成员个体→`character` | +| `power_system` 力量体系 | 等级阶梯/晋升条件/代价限制/金手指例外 | 骨架 | **直接决定角色强弱排序**的规则（可多套并存）‖ 约束所有人而不排序→`world`；具体功法技能→品类开放集增型 | +| `item` 物品 | 外观材质/功能规则/来历归属/象征 | 骨架 | 可持有可流转的具名物件（含秘籍载体）‖ "怎么描写"的笔法→`style` 公共层；无实体抽象能力→`power_system` | +| `event` 事件 | 时间地点/参与者引用/因果链/长期影响/时间线位置 | 骨架 | 戏内时间轴上有参与者与因果的已定/预定事实（**时间线=event 有序投影，不另设型**）‖ 作者写作安排→`outline`；节奏分布→`pacing` | + +**第 3 组 · 人物** + +| key·中文 | 关键字段（特有） | 层次 | 边界判据 | +|---|---|---|---| +| `character` 角色 | 外貌/性格动机/弱点秘密/说话方式/弧光 | **双层** | 具名/可指认的行动主体；**说话方式=该角色语言指纹，挂角色不挂作品** ‖ 作者全书指纹→`style`；有自身故事的角色间连接→`character_relation`；集体→`faction` | +| `character_relation` 角色关系 | 关系类型/双方引用/张力来源/当前状态/演变轨迹 | 骨架 | **演变轨迹本身就是剧情**、值得立传的关系 ‖ 只更新当前值的结构性从属（属组织/持物/位于）→Knowledge Relation 边+枚举（枚举是元数据但非 target type）；推进公式→`trope`；场景写法→`emotion` | + +**第 4 组 · 文风与节奏画像（全书连续特征；应然基准+公共范式，双层）** + +| key·中文 | 关键字段（特有） | 层次 | 边界判据 | +|---|---|---|---| +| `style` 文风 | 视角人称/句式用词/语气文采/对白叙述比/描写范式/禁用风格/文风指纹 | **双层** | **与章序无关**的语言表层指纹（打乱章序不变）‖ 顺序敏感分布→`pacing`；单角色语言→`character.说话方式` | +| `pacing` 节奏 | 快慢配比/张力曲线/爽点密度间隔/信息释放速率 | **双层** | **顺序敏感**的分布（值是曲线/比率，打乱章序即毁）‖ 单个爽点构成→`craft`（pacing 以 craft 枚举为统计口径）；逐章安排→`outline` | + +**第 5 组 · 技法与桥段范式（可复用写法；点→场景→情节 粒度阶梯）** + +| key·中文 | 关键字段（特有） | 层次 | 边界判据 | +|---|---|---|---| +| `craft` 叙事技法 | 技法类型(枚举:转折/反转/悬念/钩子/伏笔/爽点构成)/构成要素/适用位置/回收状态 | **双层** | 单点装置——**删去它场景仍成立、读者体验变平**；台账只收有跨章履约的装置(伏笔/悬念) ‖ 承载整场戏→桥段三型；密度分布→`pacing`；跨章公式→`trope` | +| `combat` 打斗桥段 | 交战双方与实力差/招式(引`power_system`)/节奏调度/伤亡/爽点触发 | 公共 | **以武力/超自然力分胜负**的对抗场景 ‖ 非武力博弈(商战/权谋/斗嘴)→`scene_pattern`；情绪弧主导→`emotion` | +| `emotion` 情感桥段 | 情绪类型/情绪弧/张力来源(引`character_relation`)/爆发点/铺垫释放 | 公共 | **以情绪弧为主体**的场景(告白/离别/爆发)‖ 武力分胜负→`combat`；关系实体本身→`character_relation` | +| `scene_pattern` 通用桥段 | 桥段类型(枚举:拍卖/比武/夺宝/审判/博弈…)/场景目标/参与者配置/推进结构/变体 | 公共 | 有"目标-推进-收束"完整结构的场景范式；**枚举显式排除打斗与情感**(互斥闭合)‖ 点装置→`craft`；跨场景公式→`trope` | +| `trope` 套路 | 流派归属/前提公式/结构节拍/爽点逻辑/变体雷点 | 公共 | 规定"这条线接下来几章怎么走"的公式 ‖ 单场景流程→`scene_pattern`；本作品自己的计划→`outline`（挂引用） | + +**四条外边界**（与型内判据同等效力）：质量维度（`专题-04` 11 维）不进本体——模具↔检尺，见 §6.2 C，不共定义；Narrative State 不进本体——运行态是独立事实载体（`架构-02 §3`），本体只提供其字段模具；RAG 文档面不进本体——上传的百科语料是检索素材，非 faction/event 实例（除非经确认链落成作品实体）；品类特化与作品私有不进基础层。 + +**MECE 自检结论**：修复 6 处重叠（scene_pattern 枚举排除打斗/情感、爽点按值类型劈、打脸戏机制归 craft/流程归 scene_pattern 双面正交、物品描述档案归 item/笔法归 style、说话方式/文风按归属主体劈、character_relation/Knowledge-Relation 物化判据钉死）+ 堵 5 处缺口（卷级大纲→outline 分层字段、描写素材范式→style 公共层、非武力对抗→scene_pattern 博弈类、种族血脉按判据裁决、功法技能=开放集首验件不进基础层）；显式封死伪型候选（时间线/关系网/势力地图/伏笔看板=投影，代入感/爽感=效果词，字数/更新/书名=运营面）。**层次全景（结构本体骨架 17 型）：结构骨架 9（work_core/outline/world/location/faction/power_system/item/event/character_relation）+ 双层 4（character/style/pacing/craft）+ 公共参考 4（combat/emotion/scene_pattern/trope）**；对齐 domain/scope 后再并入容器 `novel_work`、系统侧 `reference_work`、配套 `generation_context`，合计 20 型（见上文 A 表）。 + +> **你点名的 15 维度全部有归属**：文风→`style`；叙事→`style`(视角)+`pacing`+`trope`；文采→`style`；转折/反转→`craft`枚举；节奏→`pacing`；抓手→`craft`(钩子)；套路→`trope`；打斗→`combat`；情感→`emotion`；人设→`character`；物品描述→`item`(档案)+`style`公共层(笔法)；伏笔→`craft`定义(+`outline`引用)；爽点→`craft`(构成)+`pacing`(分布)；桥段→`scene_pattern`(+combat/emotion 特化)。 + +**作品容器（`novel_work`）的建模** + +作品容器不是新造的抽象。`muse_content_work` 已有固定列——owner_user_id/title/genre/summary/status/word_count/chapter_count/import_status/parse_status，且已预留 `work_schema_id` 可选关联 MetaSchema；`后端-05 §4.3` 已预设 `PATCH /works/{workId}` 修改动态字段时须校验 schemaVersion/projectionVersion。容器 schema 化早有伏笔，不是无中生有。`产品-02C` 有"封面"而表合同无 cover 列，这类缺口随容器 schema 落地一并收编。 + +**容器与 `work_core` 拆成两个 schema**，依据是四判据的第 2、4 条：字段合同不同构（容器承载书名/简介/封面/状态/字数/时间这类运营与结构身份，`work_core` 承载题材/主题立意/基调/禁区/结局方向这类创作承诺），写入路径不同（容器走用户直接 PATCH + 系统回算，`work_core` 走 Planning 确认链），消费面不同（容器喂列表/卡片/导出/市场快照，`work_core` 喂全部开放 agent 的上下文）。 + +**容器 schema 实例与 Work 聚合的关系是"同体 + 投影"，不派生**——不另建实例表，避免双写漂移。schema 是对 Work 固定列的**元描述与读投影模具**：字段合同为每字段标注落点，`native_column`（物理列）、`extension_json`（扩展字段）或 `computed`（回算字段，`userEditable=false`），这就是 `storage_binding` 机制。与 `架构-02 §9`"MetaSchema 不替代事实载体"一致。卷章结构不进字段合同，按"投影收进读模型"降级，由统一读取器的作品分区输出。 + +**base 与内置：全局 schema 的叠加与继承** + +`base` 不是新机制：**base = `effective_scope=全局` 的 active schema 版本**（admin 全局定义），"内置"就是系统 seed 出厂的那批全局 schema。一个作品能看到的结构，是三层叠加：全局 active ⊕ 类型灰度版本（active 唯一约束按 schema_key + effective_scope 分桶，既有）⊕ 作品级 override。**override 只增不改**——只能扩展字段，不能删改全局字段的定义与可见性；这是 `架构-01 §4` 的推论，canonical 此前未写明，须补写。 + +继承靠动态合成、不靠复制：系统**不落 per-work schema 实例**，读取时按 projectionVersion 动态合成投影。新作品开箱即有全部结构，因为全局 schema 天然生效、零初始化；`work_schema_id` 保留为品类包钩子，默认空即纯继承。 + +**seed 现状要如实纠正（反假绿）**：生产迁移 V1–V37 **零 MetaSchema seed INSERT**（已验真），`work_core`/`setting` 只存在于测试 fixture 与文档示例——评审稿此前"当前 seed 仅 work_core + setting"的说法要弱化到这一格，W1 的真实起点比原以为的更低。 + +**系统内置 base schema 清单（W1 种子目标全集 = 20 项四档）**——这也修正了评审稿 W1 原列 11 类与本节型清单的内部不一致： + +| 档 | 开箱形态 | schema | 可见性基线 | +|---|---|---|---| +| 作品身份档 | 开箱即有 | `novel_work`、`work_core` | uiVisible=true、userEditable=true（容器回算字段除外）、aiContext=true（禁区/结局方向按需） | +| 创作骨架档 | 开箱即有、空实例 | `outline`、`world`、`location`、`faction`、`power_system`、`item`、`event`、`character`、`character_relation` | 三可见全开 | +| 画像与技法档 | 开箱即有画像；公共范式随 Global KB 绑定进入 | `style`、`pacing`、`craft`、`combat`、`emotion`、`scene_pattern`、`trope` | 作品面全开；公共面例证/出处字段 uiVisible 待例证可见性口径 | +| 系统侧档 | 用户不可见 | `reference_work`（仅 admin 面）、`generation_context`（运行时） | uiVisible=false、userEditable=false | + +**B. 质量维度（Quality Dimensions，`专题-04` 已定，勿与结构本体重复定义）** + +| 组 | 维度 key | +|---|---| +| 硬阻断 | `source_safety`、`output_compliance`、`static_contract` | +| 叙事关键 | `canon_compliance`、`character_voice`、`scene_structure` | +| 非关键 | `style_fit`、`pacing_tension`、`information_density`、`emotional_continuity`、`readability` | + +**C. "同名不同角色"辨析（结构本体 vs 质量维度，勿混）** + +原则：**结构本体定"应然基准"（模具），质量维度量"候选与基准的偏离"（检尺）**。归属不同（本体归 MetaSchema `架构-02 §9`，维度归 Quality Policy `专题-04 §4`），单向咬合、不共享定义、key 无字面冲突。典型对：`pacing`（本作节奏基准）↔ `pacing_tension`（候选是否维持）；`style`（声音画像）↔ `style_fit`（候选贴合度）；`character.说话方式`（角色声音定义）↔ `character_voice`（候选对白是否符合）；大类 2 全部实体（Local KB Canonical）↔ `canon_compliance`（候选是否与已确认事实冲突）。**推论**：管理员给 `pacing` 加"反转密度"字段，拆书会多抽、写作会多用，但**是否据此评分是 Quality Policy 的独立决策**，本体扩字段不自动等于质量维度扩检查项。 + +**D. 边界裁决与待确认（2026-07-08 更新）** + +上一版 5 处待确认经边界精炼**全部裁决"维持"**：world 拆 4 型（"可数出场"+"排序"双测试反证拆分线真实）；scene_pattern 独立（场景单元 vs 情节公式，格位与消费时机不同）；范式为主例证为辅；character_relation 收窄（物化判据）；伏笔不升型（升型触发明确=未回收伏笔看板成一级能力时枚举迁 schema_key，路径无损）。 + +**本轮已移入已决策**（不再挂起，见 §0 决策面与 §7.2）：`combat` 语义钉死为"武力/超自然对抗"、非武力对抗归 `scene_pattern` 博弈类；命名统一（`character_entity`→`character`、`relation`→`character_relation`、`setting`→`world`）；`generation_context` 保留为快照模具；`storage_binding` 存储映射随 W1 落；连同功能链归属（案 A）、双轨 Canonical 入口增补（批准）、`reference_work` 库位（案 A）。 + +**仍保持开放的待拍板：** + +1. **双层型公共面是否独立 `*_paradigm`**：style/pacing/craft 的公共面暂与作品面共用同一 schema（单模具双库主案），是否需拆出 `*_paradigm` 独立型，由 **W4 三样本投递**用"拆书产出能否无损写进同一字段合同"实测终裁；不同构再拆，W1 先落作品面种子不阻塞。 +2. **公共范式例证的用户可见性口径**：范式挂的脱敏例证 + 书目出处是否对普通用户展示（版权观感），与公共面字段基线联动，待定口径。 +3. **`character_relation` 公共层关闭**（Fable 加严裁决）：现钉为结构骨架型、不开公共层，关系可复用面由 `trope`（关系推进公式）与 `character` 原型承载。现在关、以后按判据开顺滑；若判言情品类"关系流派库"要成一级资产则开。 +4. **`outline` 卷层字段是否随 W1 落库**：Fable 建议落（长篇必有卷纲）；若砍须在 W1 台账记明缺口。 +5. **玄幻品类包（功法/技能等开放集增型）排期**：基础层已按硬约束排除，作为开放集机制"首个验证件"，只关排期不关边界。 + +> 边界判据的真验证点在 **W4 拆书元数据化**：用《凡人修仙传》学艺章、言情先婚后爱名场面、玄幻拍卖会打脸戏三样本投递拆书，检查是否出现"一实例两型争抢"或"元素无家可归"（Fable 已桌面推演通过，建议纳入 W4 抽取评估集）。 + +### 6.3 知识库清单 + +| 库 | 归属 | 实体/图谱面（PG，MetaSchema 结构化） | 文档/RAG 面（Dify dataset） | 谁读/写 | +|---|---|---|---|---| +| **全局知识库 Global KB** | 平台/管理员 | 拆书公共属性参考（craft/combat/emotion/trope/style 范式实例） | 写作方法/平台规范/公共资料语料 | 拆书(系统级)写；写作/规划读（系统默认来源） | +| **用户知识库 User KB** | 普通用户 | —（以资料为主） | 用户上传的可复用资料语料 | 用户维护；绑定后写作/规划读 | +| **局域知识库 Local KB** | 单作品 | **作品故事圣经**：角色/物品/世界设定/事件/关系/时间线/叙事状态 | 作品参考资料语料 | 拆书(作品级)写草稿→用户确认；写作/检测读 | + +> 授权态（已安装 Installed / 账户可用 Account-Available）与市场公开副本（D0-fork dataset）是 User/Global 库的**授权与隔离形态**，不新增独立库。 + +### 6.4 对应关系矩阵（Agent × 元数据 × 知识库） + +这是三清单咬合的锚。读=消费为上下文，写=产出落库。 + +| Agent | 用哪些元数据类型 | 读哪些库 | 写哪些库/去向 | +|---|---|---|---| +| **写作 Agent** | style、character(voice)、outline、craft/combat/emotion | Local KB(实体) + Global KB(公共属性) + 检索 | → Shadow 候选（不直接写库） | +| **拆书 Agent** | 全部实体本体（world/character/item/event/style/craft…） | 源文本（书 or 已确认章节） | 系统级→Global KB；作品级→Local KB（经 Draft→确认→Canonical） | +| **检测 Agent** | canon_compliance、character_voice、style、outline | Local KB(实体) | → Risk Marker / 一致性结果 | +| **规划 Agent** | work_core、outline、world、character | 作品方向 + Local KB | → Planning 候选（Shadow） | +| **质量门控/LLM-Judge** | 质量维度（6.2 B） | 候选 + Local KB | → Candidate Quality Result | +| **合规/围栏** | output_compliance、source_safety | 输入/输出文本 | → 合规结论（hardBlock） | +| **RAG 检索** | style/craft（决定检索什么维度） | Global+User+Local dataset | → 检索片段 | + +--- + +## 7. 代码现状与设计的偏差（设计为准，偏差即代码待修正项） + +口径：**设计文档是 SoT，下表"应然"列不可动；"现状"是代码偏差，需要改代码向设计对齐，不是弯设计迁就代码。**（现状均为 2026-07-08 只读盘点已验证。） + +### 7.1 五处关键偏差（代码待修正） + +| 主题 | 应然（设计 SoT） | 现状（代码偏差） | 修正方向 | +|---|---|---|---| +| **元数据驱动产出** | MetaSchema 约束提取/规划/检查/产出（`架构-02 §9`） | MetaSchema **只接通 Content**（动态表单/规划字段）；**AI runtime 零消费**（`AiContextUsageContributor` 自证 `verifiedZero`，`aiContext` 开关不被裁剪） | 把 MetaSchema projection 接进 AI 上下文组装与输出合同，让产出结构随 schema 变 | +| **功能链编排** | FunctionChain 定义节点/开放槽位/保护节点，AI 按链编排 | FunctionChain/ProtectionNode 是**纯治理台账**：无 meta-api 读端口、AI 零引用、激活不发事件 | 建 facade-api + 激活发事件；AI runtime 按激活功能链解析节点与槽位 | +| **两套 slot 命名空间** | 一套槽位：功能链开放槽 ← 用户/市场 Agent 绑定 | **两套并行**：meta `FunctionChainSlot`（治理，slotKey 如 `content-ingest`）与 AI `MuseAgentSlotBinding`（运行时，slotKey 如 `writer`）无映射 | 收敛为一套：AI 槽位绑定引用功能链槽位合同 | +| **拆书元数据化** | 拆书按元数据实体类型抽人设/物品/文风入库；每确认章都跑 | 解析产物仅"章节切分（title+content+字数）"（V34）；非实体抽取；每确认章跑拆书未接 | 拆书按 MetaSchema target type 产结构化实体草稿；接"确认章→拆书+质检"触发 | +| **检测/质检用 LLM** | LLM 检测 + LLM-Judge 质量门控 | 候选轻量审=规则桩、质量评测=hash 打分桩 | 接真 LLM（走保护节点内部受控路径） | + +补充偏差（次要）：知识库"全局公共作系统默认来源"设计有、代码需显式 binding 无自动注入；图查询 GraphRAG 构图链占位未接。 + +### 7.2 已决策（2026-07-08 创始人拍板） + +| 决策 | 结论 | +|---|---| +| **落地深度与节奏** | **全量接通**：本轮把 MetaSchema + FunctionChain 真正接进 AI runtime（生成/拆书/质检按 schema 定产出、按功能链编排、两套槽位收敛）一次到位，不分期。这是跨 meta+ai+knowledge 的结构性改造，执行计划见第八节。 | +| **元数据类型清单（6.2）** | **认可全量**：结构本体经 Fable 边界精炼、并与 domain/scope 两轴对齐后定稿 **20 型**（分 5 个本体分组，每型带 MECE 边界判据），全落为 MetaSchema target types（剩余待确认见 6.2 D）；质量维度沿用 `专题-04`；两类不重复定义。元数据整体按用途分 5 个**元数据用途类**（结构本体/质量维度/编排/智能体配置/可见策略）。 | +| **拆书公共属性 SoT 归属** | 落为 MetaSchema target types（管理员在 `产品-02B` 元结构台维护）+ 收口时新建 `专题-06` 定义本体（见第九节）。 | +| **全局库检索方式** | **显式绑定**，不自动注入（见 5.3）。 | +| **知识实体强绑 MetaSchema** | **强绑**：`muse_knowledge_entity.entity_type` 改为引用 schema_key（target type），实体字段按 MetaField 结构存——这样"元数据变→实体结构变"才真正闭环（纳入第八节工作项）。 | +| **功能链归属** | **取案 A**：功能链定义与 MetaSchema 同住元引擎（Meta BC），表名 `muse_meta_function_chain*` 不动；AI runtime 经 `FunctionChainQueryApi` 读激活链做运行编排。已验真零数据迁移（V3/V10 迁移即建此表、代码全在 muse-module-meta）。 | +| **双轨 Canonical 入口增补** | **批准**：`架构-02 §1.2` 封闭枚举新增「管理员确认系统级知识草稿 → Global KB 范式 Canonical」，确认人=管理员，走 Draft→确认→Canonical 同构链；解锁 W8 拆书系统级链路。 | +| **参考作品库位** | **取案 A**：`reference_work` 落 Global KB document 特化（Knowledge BC），复用 `muse_knowledge_document/_version/_processing_job`；拆书任务归 AI BC（新类型 reference_extraction）；版权受限走 Source Status Event→Propagation 阻断新使用、不回滚已确认。 | +| **默认落定（有异议可翻）** | 命名统一（`character_entity`→`character`、`relation`→`character_relation`、`setting`→`world`）；双层型取单模具双库（一型一 schema、公共面实例落 Global KB 共用同一 schema，是否拆 `*_paradigm` 由 W4 终裁）；`generation_context` 保留为快照模具；`storage_binding` 随 W1 落（`muse_meta_field` 增 native_column/extension_json/computed）。 | + +--- + +## 8. 执行计划：全量接通（创始人已定，待过审后动代码） + +目标态：**每个 Agent = f(作品 + 元数据 + 知识库)，按功能链编排，元数据变则产出变**。这是跨 `meta + ai + knowledge` 三模块的结构性重构。按工程红线，本节是执行版预案，创始人过审后再落代码；每步都要真 PG IT + 活体证据，不假绿。 + +### 8.1 工作分解（8 项，按依赖排序） + +| # | 工作项 | 模块 | 做什么 | 依赖 | +|---|---|---|---|---| +| W1 | **元数据本体落库** | meta | 落 20 项 target type 的生产种子（四档全集见 §6.2 base 清单：作品身份档 novel_work/work_core、创作骨架档 outline/world/location/faction/power_system/item/event/character/character_relation、画像技法档 style/pacing/craft/combat/emotion/scene_pattern/trope、系统侧档 reference_work/generation_context）+ 字段/枚举/校验；并入 `storage_binding`——`muse_meta_field` 增 native_column/extension_json/computed 属性，描述容器 schema 对 Work 固定列的落点 | — | +| W2 | **MetaSchema → AI 上下文** | meta→ai | AI 上下文组装消费 `MetaProjection`：按 `aiContext` 裁字段、按 target type 定输出合同；`AiContextUsageContributor` 的 `verifiedZero` 改真实消费 | W1 | +| W3 | **Local KB 实体强绑 schema** | knowledge+meta | `muse_knowledge_entity.entity_type` 引用 schema_key；实体字段按 MetaField 结构存（jsonb + schema 校验） | W1 | +| W4 | **拆书元数据化** | ai+knowledge | 拆书 Agent 按 target type 产**结构化实体草稿**（替代现 title+content 章节切分）；接"每确认章 → 拆书抽实体 + 质检一致性"触发 | W2,W3 | +| W5 | **FunctionChain → AI 编排** | meta→ai | 案 A：功能链定义留在 Meta BC（表名/归属不动、零数据迁移），meta-api 增 `FunctionChainQueryApi` 读端口 + 激活发事件；AI runtime 按激活功能链解析节点序列与开放槽位 | W2 | +| W6 | **两套 slot 收敛** | meta+ai | `MuseAgentSlotBinding.slotKey` 引用 `FunctionChainSlot` 合同（requiredNodeType 兼容校验）；统一命名空间 + 历史数据迁移 | W5 | +| W7 | **检测/质检接 LLM** | ai | 候选轻量审→LLM 检测；质量评测→LLM-Judge（走保护节点内部受控路径，非可配置 Dify app） | W2 | +| W8 | **拆书系统级入全局库**（双轨入口已批准 2026-07-08，解锁） | ai+knowledge | 管理员拆参考书 → 按公共属性 target type 抽 → 经「管理员确认草稿→Global KB 范式 Canonical」新入口入库（供作品显式绑定）；参考作品档案落 `reference_work`，范式带 lineage 溯源 | W4 | + +### 8.2 顺序、验证、风险 + +- **顺序**：`W1 → W2 →（W3,W4 并）→（W5,W6 并）→（W7,W8 并）`。 +- **闭环验证**（最关键的真验证）：一个端到端证明"**加字段 → 拆书多抽该字段 → 生成多用该字段**"——在 world schema 加"金手指类型"字段，重跑拆书应多抽该属性、写作上下文应可见，全程真 PG + 活体，不用桩。 +- **各步验证**：真 PG IT（每模块）+ MSW-off 活体 e2e；两套 slot 收敛须有历史 binding 迁移测试。 +- **风险**：① AI runtime 大改，须保留"功能链未激活→回退现有固定链"的兜底；② slot 收敛涉及历史数据迁移；③ MetaSchema 版本切换与 AI 上下文一致性（版本漂移）；④ 拆书产出结构变更冲击既有 parse IT（须同步更新台账）。 +- **回滚**：各步 git 可回；W5/W6 未激活功能链时运行时行为等价现状。 + +--- + +## 9. SoT 落地建议（评审已通过，canonical 落地开工） + +三项材料级决策与默认落定已拍（§0、§7.2），评审核心结论通过，canonical 分册可开工。按单一归属把内容蒸馏进正式分册，并在 `00-文档大纲.md` 与 `内容映射表.md` 注册。目标改动清单： + +- **新增 `专题-06-元数据驱动的智能体架构.md`**：owner 收口这套横切架构——元引擎 + 功能链驱动智能体、拆书通用抽取、三体关系、**target type 本体（对齐后 20 型 + domain/scope 两轴）、统一创作数据读取器、base 种子清单**（当前散落在专题-03/05、架构-02，需一个 owner）。 +- **修订 `架构-02`**：§1.2 双轨 Canonical 入口封闭枚举 +1（管理员确认系统级知识草稿→Global KB 范式）；分区表补功能链行（定义归 Meta、运行编排归 AI）；§9 补 domain 逐值语义与 **override 只增不改** 推论。 +- **修订 `后端-04`**：功能链表名与归属订正为 `muse_meta_function_chain*` 归 meta；示例 `character_entity`→`character`；`muse_meta_field` 增 `storage_binding`（native_column/extension_json/computed）；补 base 种子清单。 +- **修订 `架构-01 §3.3`**：功能链落地矩阵行（定义归 Meta、AI runtime 经 `FunctionChainQueryApi` 读激活链编排）。 +- **修订 `后端-02 §3.4`**：Governance Facade 落点表补功能链行（`FunctionChainQueryApi` 读端口）。 +- **扩写 `产品-02B`**：拆书公共属性本体作为 MetaSchema target types 的管理面 + 参考作品治理（`reference_work` 档案、版权授权状态、拆书处理状态）。 +- **扩写 `产品-02E`**：知识库三库 × 两面正交结构、全局库作系统默认来源、拆书产出入全局库。 +- **扩写 `专题-04`**：质量维度与拆书属性本体对齐（同一"节奏/文风"不两处定义）。 +- **不新增**过程状态文档；进度只进 `docs/mvp/进度总账.md`。 + +> 术语与不变式仍以 `架构-02` 为唯一权威；本文所有结构定义在落 canonical 时须回指其术语，不另造词。