diff --git a/design-docs/memorys/2026-05-24-整体文档一致性修复.md b/design-docs/memorys/2026-05-24-整体文档一致性修复.md index 305d201c..82b1d9af 100644 --- a/design-docs/memorys/2026-05-24-整体文档一致性修复.md +++ b/design-docs/memorys/2026-05-24-整体文档一致性修复.md @@ -31,7 +31,7 @@ 3. Market 只负责市场资产、授权、安装记录、来源侧 handoff、授权摘要和跳转审计。目标 owner 自己创建和消费 target precheck/session，Market 不写目标事实。 4. Import task/context 归 Work/Content；Parse Job、Chapter Parse Result、Chapter Review 归 AI Orchestration；Knowledge 只在章节审阅确认后创建或更新 Knowledge Draft。 5. 动态字段没有跨 owner 的通用写接口。`/dynamic-fields/validate` 只做校验和路由建议，正式写入必须回到 Content、Planning、Knowledge、Agent 等 owner action。 -6. Accept / Merge 写 Canonical 前必须消费或重算 Candidate Decision Envelope。硬闸门必须覆盖输出合规、静态检查、质量结果版本、来源状态、授权快照、作品资产 feature gate、`expectedRevision` 和幂等结果。 +6. Accept / Merge 写 Canonical 前必须消费或重算 Candidate Decision Envelope。硬闸门必须覆盖输出合规、静态检查、质量结果版本、来源状态、授权快照、作品资产 feature gate、`expectedRevision` 和幂等结果。（ADR-018 已决策去掉独立 Candidate Decision Envelope 概念封装，改为接受时实时对比来源状态；Agent Runtime Permission Envelope 仍保留，两者是不同概念。专题文档已同步更新。） 7. 作品资产当前只允许阅读、收藏和授权记录。模板化、参考来源写入、AI 上下文绑定必须等待后续 feature gate、作品 owner 入口、使用检查、来源谱系、API/Schema 和失败回退闭合。 8. SourceStatus、SourceEventType、SourceActionPolicy 必须分层表达。SourceStatus 包含 `delisted`；SourceActionPolicy 包含 `read_only`，不能把 `allowed/blocked/needs_recheck` 当成来源事实状态。 9. 来源撤权、召回、下架、阻断、owner 缺失和授权失效会影响候选接受、Local KB 来源型确认、生成上下文、绑定、导出任务和已签发下载凭证，但不能自动回滚已确认 Canonical。 @@ -44,7 +44,7 @@ 1. `design-docs/临时-产品形态阶段化重设计计划.md` 中 D-045 和 C-006。 2. `产品-02C/02F/03` 中作品资产是否仍保持只读/收藏/授权记录的默认 gate。 3. `后端-05` 中动态字段是否仍没有跨 owner 泛写接口。 -4. `专题-01`、`流程-02B` 和 `前端-02` 是否仍要求 Candidate Decision Envelope 硬闸门。 +4. `专题-01`、`流程-02B` 和 `前端-02` 是否仍要求 Candidate Decision Envelope 硬闸门。（ADR-018 已决策去掉独立 Candidate Decision Envelope，改为实时对比；Agent Runtime Permission Envelope 仍保留。） 5. `架构-01/02/04`、`后端-03/04/05`、`专题-03` 是否仍统一 SourceStatus / SourceEventType / SourceActionPolicy。 6. 阶段 8 已在 D-046 开始补 `00-文档大纲.md` 和 `内容映射表.md` 的四仓工程架构索引；后续仍需继续复核其他过期引用和 owner 映射。 diff --git a/design-docs/专题-01-正文建议接受(Accept Suggestion)实现规范.md b/design-docs/专题-01-正文建议接受(Accept Suggestion)实现规范.md index db256249..2ef89178 100644 --- a/design-docs/专题-01-正文建议接受(Accept Suggestion)实现规范.md +++ b/design-docs/专题-01-正文建议接受(Accept Suggestion)实现规范.md @@ -115,7 +115,7 @@ Accept 命令必须携带以下语义： | acceptMode | `accept_as_is` 或 `merge_after_edit` | | finalContent | 仅 `merge_after_edit` 需要，表示用户确认写入正文的最终内容 | | decisionContext | UI 决策来源、候选版本、质量结果版本和必要审计摘要 | -| candidateDecisionEnvelope | 候选决策快照或重算请求，必须覆盖输出合规、静态检查、质量结果版本、来源状态、来源事件影响、Action Policy、授权快照、作品资产 feature gate、`expectedRevision` 和幂等结果 | +| acceptPreconditionContext | 接受前置校验上下文，必须覆盖输出合规、静态检查、质量结果版本、来源状态、来源事件影响、Action Policy、授权快照、作品资产 feature gate、`expectedRevision` 和幂等结果；系统在接受时实时校验，不封装为独立对象 | 命令结果至少返回以下语义： @@ -143,21 +143,21 @@ Reject 不得修改正文，不得触发新的提取。 - 已成功接受的命令必须返回同一 Block revision、Archive 结果和 followupTask 摘要。 - 已失败且可重试的命令必须说明失败原因和当前可恢复动作。 - 已失败且不可重试的命令不得创建新的正文 revision。 -- 同一幂等键携带不同 actor、work、targetBlock、suggestion、`expectedRevision`、授权快照或候选决策输入时，必须返回幂等冲突，不得复用旧结果。 +- 同一幂等键携带不同 actor、work、targetBlock、suggestion、`expectedRevision`、授权快照或接受前置校验输入时，必须返回幂等冲突，不得复用旧结果。 - Archive、change log、audit log 和 outbox 必须能通过命令幂等语义去重。 ## 6. 接受前置条件 Accept 在任何写正文动作前必须完成前置校验。前置校验失败时，候选不能被接受，正文不能写入。 -服务端必须消费 Candidate Decision Envelope；如果 Envelope 缺失、过期、质量结果版本不匹配、`expectedRevision` 不匹配、授权快照变化、来源状态变化、作品资产 feature gate 变化或幂等结果不可复用，必须在写正文前重算。重算结果不是提示文案，而是写 Canonical 的硬闸门。 +服务端必须在接受时实时校验候选来源版本和授权状态；如果校验缺失、过期、质量结果版本不匹配、`expectedRevision` 不匹配、授权快照变化、来源状态变化、作品资产 feature gate 变化或幂等结果不可复用，必须在写正文前重算。重算结果不是提示文案，而是写 Canonical 的硬闸门。 | 校验 | 失败结果 | |---|---| | actor 对作品、Block、Suggestion 有操作权限 | `PERMISSION_DENIED`，不写正文 | | Suggestion 仍处于 Active / Shadow，未过期、未失效 | `SUGGESTION_NOT_ACCEPTABLE`，不写正文 | | expectedRevision 匹配目标 Block 当前 revision | `REVISION_CONFLICT`，进入显式冲突处理 | -| Candidate Decision Envelope 允许接受，且包含输出合规、静态检查、质量结果版本、来源状态、授权快照、作品资产 feature gate、expectedRevision 和幂等结果 | 按决策结果阻断、需重验或要求显式确认 | +| 接受前置校验通过（实时校验来源版本和授权状态），且覆盖输出合规、静态检查、质量结果版本、来源状态、授权快照、作品资产 feature gate、expectedRevision 和幂等结果 | 按校验结果阻断、需重验或要求显式确认 | | 输出合规、语义安全围栏和静态检查通过 | `OUTPUT_COMPLIANCE_BLOCKED` 或 `STATIC_CHECK_FAILED`，不写正文 | | 候选正文 lineage 中所有来源有有效 Authorization Snapshot | `SOURCE_AUTH_INVALID`，候选 invalidated / blocked | | 候选正文 lineage 不含 revoked / recalled / delisted / blocked / owner_missing / unauthorized 来源 | `SOURCE_BLOCKED`，候选 invalidated / blocked | @@ -173,7 +173,7 @@ Accept 在任何写正文动作前必须完成前置校验。前置校验失败 1. 加载 Active Suggestion 并校验归属、状态与过期时间。 2. 加载目标 Block，并用 `expectedRevision` 做并发保护。 -3. 消费或重算 Candidate Decision Envelope，校验候选来源、授权快照、市场作品资产 feature gate、质量门控、输出合规、静态检查、质量结果版本、幂等结果和当前 Block revision。 +3. 实时校验候选来源版本和授权状态（校验清单：候选来源、授权快照、市场作品资产 feature gate、质量门控、输出合规、静态检查、质量结果版本、幂等结果和当前 Block revision）。 4. 更新 Block 内容与 revision。 5. 如果候选包含 AI、市场、外部知识或授权知识来源，写 Block Source Attribution。 6. 将 Suggestion 迁入候选归档(disposition=accepted)。 @@ -189,7 +189,7 @@ Accept 在任何写正文动作前必须完成前置校验。前置校验失败 1. 加载 Active Suggestion 并校验归属、状态与过期时间。 2. 加载目标 Block，并用 `expectedRevision` 做并发保护。 -3. 消费或重算 Candidate Decision Envelope，校验候选来源、授权快照、市场作品资产 feature gate、质量门控、输出合规、静态检查、质量结果版本、幂等结果和最终正文内容。 +3. 实时校验候选来源版本和授权状态（校验清单：候选来源、授权快照、市场作品资产 feature gate、质量门控、输出合规、静态检查、质量结果版本、幂等结果和最终正文内容）。 4. 用 `contentOverride` 更新 Block 内容与 revision。 5. 默认继承上游候选的 lineage、授权快照、许可限制、召回状态和风险标记，并写 Block Source Attribution。 6. 将 Suggestion 迁入候选归档(disposition=accepted)，必要时记录 `final_content`。 @@ -305,7 +305,7 @@ Reject 不得更新 Block，不得创建重新提取链路。 10. 候选正文 lineage 中存在 revoked、recalled、delisted、blocked、owner_missing、unauthorized 或无效授权快照时，Accept 必须失败。 11. 候选使用市场作品资产时，必须经过作品资产使用预检和 feature gate；否则不能接受。 12. 修改后合并默认继承上游 lineage 和许可限制，不能用 `contentOverride` 洗白来源。 -13. Accept / Merge 写 Canonical 前必须消费或重算 Candidate Decision Envelope，且 Envelope 必须包含输出合规、静态检查、质量结果版本、来源状态、授权快照、作品资产 feature gate、expectedRevision 和幂等结果。 +13. Accept / Merge 写 Canonical 前必须实时校验来源版本和授权状态，校验清单必须覆盖输出合规、静态检查、质量结果版本、来源状态、授权快照、作品资产 feature gate、expectedRevision 和幂等结果。 ### Should-Have（P1） diff --git a/design-docs/专题-03-AI编排上下文与质量评测实现规范.md b/design-docs/专题-03-AI编排上下文与质量评测实现规范.md index ba80d01b..fde36fb0 100644 --- a/design-docs/专题-03-AI编排上下文与质量评测实现规范.md +++ b/design-docs/专题-03-AI编排上下文与质量评测实现规范.md @@ -48,7 +48,7 @@ Muse 的 AI 能力不是“前端按钮直接调某个智能体”，而是系 -> 静态检查和来源状态校验 -> 质量门控与有限重写 -> 输出合规 --> Candidate Decision Envelope +-> 候选可接受性实时校验 -> 可展示的 Shadow 对象 -> 用户决策 ``` @@ -329,11 +329,11 @@ Parse Job -> Chapter Parse Result -> Chapter Review -> Knowledge Draft 风险标记属于 Shadow 解释，不是 Canonical 事实。风险、来源证据和用户决策必须进入 Archive 或审计摘要。 -### 7.1 Candidate Decision Envelope +### 7.1 候选可接受性实时校验 -候选是否可展示、可接受、需重验或阻断，必须由 Candidate Decision Envelope 合并判断。它不是新的事实 owner，而是 AI Orchestration 对来源、权限、合规、质量和风险路由结果的决策快照。 +候选是否可展示、可接受、需重验或阻断，必须由系统在接受时实时校验来源版本和授权状态来合并判断。校验逻辑不封装为独立对象，而是作为接受链路的内联前置条件执行。 -最小输入： +最小校验输入： - Source Status / Authorization Snapshot / Work Asset feature gate。 - 输入合规、输出合规、语义安全围栏和静态检查结果。 @@ -341,7 +341,7 @@ Parse Job -> Chapter Parse Result -> Chapter Review -> Knowledge Draft - Risk Marker。 - 目标 Block `expectedRevision`、候选版本和命令幂等上下文。 -最小输出： +校验输出： | 语义 | 要求 | |---|---| @@ -349,11 +349,11 @@ Parse Job -> Chapter Parse Result -> Chapter Review -> Knowledge Draft | acceptability | 可接受、只能修改后合并、需重验、不可接受 | | blockingReasons | 阻断原因和来源摘要 | | userActions | 接受、修改后合并、丢弃、重生成、重验来源等可用动作 | -| auditSummary | 决策输入版本、质量结果版本、授权快照、来源状态、expectedRevision 和幂等摘要 | +| auditSummary | 校验输入版本、质量结果版本、授权快照、来源状态、expectedRevision 和幂等摘要 | ### 7.2 决策优先级 -Candidate Decision Envelope 按以下优先级合并，前面的硬阻断不能被后面的质量评分放开： +候选可接受性实时校验按以下优先级合并，前面的硬阻断不能被后面的质量评分放开： 1. 合规、安全、语义围栏、静态检查硬阻断。 2. 来源 revoked、recalled、delisted、blocked、owner_missing、unauthorized 或授权快照无效。 @@ -494,7 +494,7 @@ Source Status Event 必须幂等处理，传播失败时要可重试；在传播 5. 任何含 AI、市场、外部知识或授权知识来源的正文写入，都能落到 Block Source Attribution。 6. New-API 只作为外部网关，不成为 Muse 本地模型路由和成本 authority。 7. 质量评测结果能被 `专题-04` 的质量门控和创作健康度直接消费。 -8. Candidate Decision Envelope 能统一合并来源、权限、合规、质量和风险路由结果。 +8. 候选可接受性实时校验能统一合并来源、权限、合规、质量和风险路由结果。 ## 12. 关联阅读 diff --git a/design-docs/专题-04-生成质量门控与创作健康度设计方案 b/design-docs/专题-04-生成质量门控与创作健康度设计方案 index b95d8ba2..0ff2e368 100644 --- a/design-docs/专题-04-生成质量门控与创作健康度设计方案 +++ b/design-docs/专题-04-生成质量门控与创作健康度设计方案 @@ -35,7 +35,7 @@ | 对象 | Owner BC | 说明 | |---|---|---| -| Quality Policy | Admin/Governance BC | 管理员配置质量维度、阈值、重写次数、展示规则和评估集 | +| Quality Policy | AI BC (grant 包) | 管理员配置质量维度、阈值、重写次数、展示规则和评估集 | | Candidate Quality Result | AI Orchestration BC | 单次候选的质量评分、风险、重写和展示摘要 | | AI Suggestion | AI Orchestration BC | 质量门控作用对象，仍属于 Shadow | | Block / Block Source Attribution | Work/Content BC | 候选被用户接受后才写正文和来源归因 | @@ -95,7 +95,7 @@ AI Suggestion 生成 -> 必要时 Shadow 内有限重写 -> 非关键维度评分 -> Candidate Quality Result --> Candidate Decision Envelope +-> 候选可接受性实时校验 -> 创作健康度展示 -> 用户决策 ``` @@ -109,7 +109,7 @@ AI Suggestion 生成 5. 重写只能在 Shadow 内替换候选版本，并保留 rewrite trail。 6. 输出合规、来源安全、静态结构和授权状态的阻断优先级高于叙事质量评分。 7. 用户最终看到的是候选和解释，不是内部评测 prompt、完整上下文或供应商响应。 -8. Candidate Quality Result 只给出质量和风险事实；候选最终是否可接受由 `专题-03` 的 Candidate Decision Envelope 合并判断。 +8. Candidate Quality Result 只给出质量和风险事实；候选最终是否可接受由 `专题-03` 的候选可接受性实时校验合并判断。 ## 6. Candidate Quality Result @@ -148,7 +148,7 @@ AI Suggestion 生成 ### 6.2 与风险路由的优先级 -质量门控不能单独决定候选可接受性。最终动作由 Candidate Decision Envelope 合并： +质量门控不能单独决定候选可接受性。最终动作由候选接受时实时校验合并： 1. 合规、安全、来源、授权、静态结构硬失败直接 blocked / invalidated。 2. 市场作品资产 feature gate、owner 预检、`workAssetUsePrecheckId` 缺失直接 blocked。 @@ -156,7 +156,7 @@ AI Suggestion 生成 4. 硬阻断检查可用且通过后，叙事关键维度才参与 pass / rewritten_pass / high_risk 判断。 5. 非关键维度只影响展示建议，不单独阻止接受。 -Candidate Decision Envelope 消费 Candidate Quality Result 时必须校验 `qualityPolicyVersion`、质量结果版本、评分时间、来源状态、授权快照、作品资产 feature gate、目标 `expectedRevision` 和命令幂等上下文；任一输入变化都必须重算或进入 needs_recheck，不能用旧质量结果放行 Accept / Merge。 +候选接受时实时校验消费 Candidate Quality Result 时必须校验 `qualityPolicyVersion`、质量结果版本、评分时间、来源状态、授权快照、作品资产 feature gate、目标 `expectedRevision` 和命令幂等上下文；任一输入变化都必须重算或进入 needs_recheck，不能用旧质量结果放行 Accept / Merge。 ## 7. 创作健康度 diff --git a/design-docs/产品-02C-用户工作区与作品工作台功能规格.md b/design-docs/产品-02C-用户工作区与作品工作台功能规格.md index c4cc8f1c..df344746 100644 --- a/design-docs/产品-02C-用户工作区与作品工作台功能规格.md +++ b/design-docs/产品-02C-用户工作区与作品工作台功能规格.md @@ -38,7 +38,19 @@ no-config 不是“没有系统能力”，而是“不要求用户先配置资 写作台的 AI 动作前置条件应理解为“作品默认生成能力可用，且被选用的智能体、来源和权限当前有效”。用户未绑定任何外部知识来源时，系统使用默认系统能力、当前正文、规划摘要和已确认作品知识生成候选。 -### 0.2 作品工作台信息架构合同 +### 0.2 UX 复杂度解决策略 + +产品范围不变，复杂度通过 UX 设计解决： + +| 策略 | 说明 | 影响范围 | +|---|---|---| +| 简单模式 | 只暴露正文编辑 + AI 续写 + 自动知识管理，不展示智能体/知识库/市场入口 | 新用户默认体验、轻度使用场景 | +| 渐进式披露 | 用户首次使用时只看到核心功能，随使用深度逐步解锁高级功能（智能体关联、知识来源绑定、导出交付等） | 功能入口可见性、导航层级 | +| 概念隐藏 | Shadow/Canonical/Archive 等技术概念不暴露给用户，用产品语言替代：Shadow → "AI 建议"、Canonical → "正式内容"、Archive → "历史记录" | 全部用户可见文案、状态标签、帮助文本 | + +简单模式下的自动知识管理：系统对满足自动确认条件的知识草稿（来源为用户自有正文 + 无冲突 + 无外部来源 + 置信度超阈值）自动确认入库，用户无需手动处理。不满足条件的草稿仍进入待确认队列。 + +### 0.3 作品工作台信息架构合同 作品工作台不是把所有功能平铺成同级导航。前端原型和后续实现必须按以下层级组织： @@ -212,16 +224,31 @@ no-config 不是“没有系统能力”，而是“不要求用户先配置资 | 使用角色 | 普通用户。 | | 入口来源 | 作品工作台二级导航、候选知识状态、冲突风险提示、规划项关联知识。 | | 返回规则 | 知识确认或忽略后回到列表并刷新待确认数量；从问题定位返回时保留筛选。 | -| 页面区域 | 知识分类、待确认草稿、冲突问题、来源追溯、最近使用、手动修正入口。 | -| 可见数据 | 人物、关系、事件、地点、物品、组织、规则、时间线、叙事状态、来源、确认时间、相关章节、风险标记。 | -| 主操作 | 确认知识草稿、忽略草稿、重新提取、发起一致性检查。 | -| 次操作 | 搜索知识、按实体/来源/风险筛选、定位正文、查看来源、手动修正。 | +| 页面区域 | 知识分类、自动确认记录、待确认草稿、冲突问题、来源追溯、最近使用、手动修正入口。 | +| 可见数据 | 人物、关系、事件、地点、物品、组织、规则、时间线、叙事状态、来源、确认时间、确认方式（自动/手动）、相关章节、风险标记。 | +| 主操作 | 确认知识草稿、忽略草稿、重新提取、发起一致性检查、撤回自动确认。 | +| 次操作 | 搜索知识、按实体/来源/风险筛选、定位正文、查看来源、手动修正、查看自动确认记录。 | | 危险操作 | 删除或修改正式知识、批量确认草稿；必须显示来源和影响范围。 | -| 状态 | 无知识、待确认、已确认、冲突、来源失效、草稿过期、检查中。 | +| 状态 | 无知识、待确认、已自动确认、已手动确认、冲突、来源失效、草稿过期、检查中。 | | 权限 | 需要 `knowledge_confirm` 才能确认或修改正式知识；只读用户只能查看摘要。 | -| 产品接口 | 查询作品知识、查询知识草稿列表、确认知识草稿、忽略知识草稿、重新提取知识草稿、发起一致性检查、保存作品知识修正。 | -| 埋点与审计 | 记录知识确认、忽略、重新提取、手动修正和一致性检查。 | -| 验收要点 | 未确认草稿不能进入正式检索、图查询、生成事实或局域知识库；来源失效草稿不能确认。 | +| 产品接口 | 查询作品知识、查询知识草稿列表、确认知识草稿、忽略知识草稿、重新提取知识草稿、发起一致性检查、保存作品知识修正、撤回自动确认知识。 | +| 埋点与审计 | 记录知识确认（含自动确认）、忽略、重新提取、撤回自动确认、手动修正和一致性检查。 | +| 验收要点 | 未确认草稿不能进入正式检索、图查询、生成事实或局域知识库；来源失效草稿不能确认；自动确认的知识用户可随时在知识面板查看和撤回。 | + +知识自动确认策略： + +| 条件 | 说明 | +|---|---| +| 来源为用户自有正文 | 草稿提取自当前作品用户保存的正文，非外部来源派生 | +| 无冲突 | 草稿内容与现有正式知识无矛盾或重复 | +| 无外部来源 | 草稿 lineage 中不包含市场资产、授权知识库或其他外部来源 | +| 置信度超阈值 | 系统提取置信度达到自动确认阈值 | + +以上四个条件同时满足时，系统自动确认草稿进入局域知识库。自动确认后： +- 用户可在知识面板查看自动确认记录，了解哪些知识被自动入库 +- 用户可随时撤回自动确认的知识，撤回后知识退出局域知识库 +- 不满足自动确认条件的草稿进入待确认队列，用户手动处理 +- 批量确认：低风险草稿（无冲突、无外部来源、置信度高）支持批量确认 ### 3.8 知识草稿详情 diff --git a/design-docs/产品-03-用户旅程与操作流程.md b/design-docs/产品-03-用户旅程与操作流程.md index c84dbc21..4d5c23f1 100644 --- a/design-docs/产品-03-用户旅程与操作流程.md +++ b/design-docs/产品-03-用户旅程与操作流程.md @@ -164,16 +164,19 @@ no-config 旅程的目标是让普通用户在最低认知负担下完成一次 ### 3.6 知识确认旅程 -1. 用户从写作台候选面板、知识与一致性、导入解析审阅或风险提示进入知识草稿处理。 -2. 用户查看草稿的来源、上游 lineage、差异、风险、冲突、来源快照和授权状态。 -3. 用户可以确认来源事实、修改来源事实后确认、改写为用户自有事实、忽略或重新提取。 -4. 只有来源仍有效、授权未撤销、未被下架或召回、且无阻断冲突的来源型知识草稿，才能以来源事实进入局域知识库。 -5. 如果用户要把外部来源内容改写为用户自有事实，必须走独立确认路径，显示会断开或改变的来源关系、保留审计和用户意图，不能通过“修改后确认”绕过撤权、下架或召回限制。 -6. 已确认知识进入 Canonical，后续检索、图查询、质量门控和生成上下文才能使用。 +1. 大部分知识草稿会自动进入知识库：系统对满足自动确认条件（来源为用户自有正文 + 无冲突 + 无外部来源 + 置信度超阈值）的草稿自动确认入库，用户无需逐条手动处理。 +2. 自动确认后，用户可在知识面板查看自动确认记录，了解哪些知识被自动入库，可随时撤回。 +3. 不满足自动确认条件的草稿（存在冲突、包含外部来源、置信度不足）进入待确认队列。 +4. 用户从写作台候选面板、知识与一致性、导入解析审阅或风险提示进入待确认知识草稿处理。 +5. 用户查看草稿的来源、上游 lineage、差异、风险、冲突、来源快照和授权状态。 +6. 用户可以确认来源事实、修改来源事实后确认、改写为用户自有事实、忽略或重新提取。 +7. 只有来源仍有效、授权未撤销、未被下架或召回、且无阻断冲突的来源型知识草稿，才能以来源事实进入局域知识库。 +8. 如果用户要把外部来源内容改写为用户自有事实，必须走独立确认路径，显示会断开或改变的来源关系、保留审计和用户意图，不能通过”修改后确认”绕过撤权、下架或召回限制。 +9. 已确认知识（含自动确认和手动确认）进入 Canonical，后续检索、图查询、质量门控和生成上下文才能使用。 -成功终态：用户确认的知识进入局域知识库；忽略的草稿归档；重提取生成新的待确认草稿。 +成功终态：自动确认的知识直接进入局域知识库；用户手动确认的知识进入局域知识库；忽略的草稿归档；重提取生成新的待确认草稿。 -失败回退：来源失效、授权撤销、市场下架、召回或冲突未解决时，来源型确认动作禁用。用户可以定位来源、重提取、忽略、保留待处理状态，或在允许时走“改写为用户自有事实”的独立路径。 +失败回退：来源失效、授权撤销、市场下架、召回或冲突未解决时，来源型确认动作禁用。用户可以定位来源、重提取、忽略、保留待处理状态，或在允许时走”改写为用户自有事实”的独立路径。 ### 3.7 导入解析旅程 diff --git a/design-docs/前端-01-工程结构与核心依赖.md b/design-docs/前端-01-工程结构与核心依赖.md index 694d3c9a..e32fc08e 100644 --- a/design-docs/前端-01-工程结构与核心依赖.md +++ b/design-docs/前端-01-工程结构与核心依赖.md @@ -13,7 +13,7 @@ Muse 前端拆为两个项目，不能再用一套 Next.js 应用同时承载管 | 目标仓库 | 来源 / 形态 | 定位 | 技术栈 | 接口前缀 | |---|---|---|---|---| | `muse-admin/` | fork `yudao-ui-admin-vben`，主应用路径 `apps/web-antd` | 管理后台(Admin Console) | Vue 3 + Vite + Ant Design Vue + TypeScript | `/admin-api/**` | -| `muse-studio/` | 自研用户端 | 用户端创作产品(User Workspace / Agent Workspace / Knowledge Workspace / Marketplace / Personal Center) | 建议 Next.js / React / TypeScript | `/app-api/**` | +| `muse-studio/` | 自研用户端 | 用户端创作产品(User Workspace / Agent Workspace / Knowledge Workspace / Marketplace / Personal Center) | React + Vite + TypeScript | `/app-api/**` | 核心原则： @@ -89,7 +89,7 @@ Vben Admin 的页面入口由后台菜单和权限点驱动。Muse 后续新增 | 边界 | 管理后台要求 | |---|---| -| 路由 | 使用 Vben 路由、菜单、面包屑和权限守卫；不复用 `muse-studio` 的 Next.js 路由 | +| 路由 | 使用 Vben 路由、菜单、面包屑和权限守卫；不复用 `muse-studio` 的 React Router 路由 | | 状态 | 使用 Vben 既有 API 请求、表格、表单、弹窗和菜单状态；不保存用户端作品编辑器状态 | | 权限 | 使用 `system` 菜单、按钮、角色、数据范围和高危动作复核；后端仍必须校验业务 owner | | API | 只访问 `/admin-api/**`；不从后台页面调用用户端 `/app-api/**` 完成用户创作决策 | @@ -99,9 +99,9 @@ Vben Admin 的页面入口由后台菜单和权限点驱动。Muse 后续新增 `muse-studio/` 是普通用户使用的创作产品，不走 Vben。 -建议技术栈： +技术栈： -- Next.js App Router / React / TypeScript +- React + Vite + TypeScript（SPA，不使用 Next.js；后续文档已全部按纯 React 栈编写） - Tiptap / ProseMirror：正文编辑、Block 级操作和候选合并 - TanStack Query：服务器状态、轮询、失效刷新 - Zustand 或等价轻量 store：工作台 UI 状态 @@ -182,11 +182,46 @@ muse-studio/ | 表单状态 | Ant Design Vue Form | React Hook Form / local form state | | UI 临时态 | Vben route/menu/modal state | Zustand / component state | | 权限可见性 | 后端菜单和权限点驱动 | `/app-api/muse/me` 权益摘要 + 业务接口结果 | -| 待确认内容 | 管理后台只查看、治理或异常处理 | 用户端决策：接受、修改后合并、丢弃、确认知识 | +| 待确认内容 | 管理后台只查看、治理或异常处理 | 用户端决策：接受、修改后合并、丢弃、确认知识、规划候选确认 | 正式事实来自后端 Canonical，待确认内容来自 Shadow，历史来自 Archive。前端不能把本地缓存伪造成正式事实。 -## 6. 接口边界 +## 6. 实时通信策略 + +用户端使用 SSE（Server-Sent Events）作为实时通信方案，分为两类连接： + +### 6.1 AI 生成 streaming 端点 + +- 路径：`POST /app-api/muse/ai/generate/stream` +- 生命周期：per-request，请求发起时建立 SSE 连接，生成完成后连接关闭。 +- 用途：AI 正文生成、候选生成等需要流式输出的场景。 +- 结束信号：服务端发送 `event: done`，payload 包含候选 ID。前端收到后用候选 ID 调用 REST 接口（`GET /app-api/muse/suggestions/{suggestionId}`）获取完整结构化结果（质量评分、来源标注等元数据）。 +- 错误处理：服务端发送 `event: error` 时，前端展示错误原因并关闭连接。 + +### 6.2 统一事件 stream + +- 路径：`GET /app-api/muse/events/stream` +- 生命周期：长连接，用户登录后建立，页面关闭时断开。 +- 用途：接收服务端推送的异步事件通知，前端按 event type 分发到对应处理器。 + +事件类型枚举： + +| event type | 含义 | 前端处理 | +|---|---|---| +| `candidate.arrived` | 新候选到达 | 刷新候选列表，展示新候选提示 | +| `task.completed` | 异步任务成功完成 | 停止轮询，刷新任务结果 | +| `task.failed` | 异步任务失败 | 停止轮询，展示失败原因 | +| `source.changed` | 来源状态变化 | 刷新来源状态，按需禁用操作 | +| `knowledge.auto_confirmed` | 知识自动确认 | 刷新知识草稿列表 | + +### 6.3 断线重连策略 + +- 重连机制：使用 `lastEventId` 续传。每次收到事件时记录 `lastEventId`，断线重连时通过 `Last-Event-ID` header 告知服务端续传位置。 +- 服务端保留策略：服务端保留最近 N 分钟事件。重连时如果 `lastEventId` 仍在保留窗口内，从该位置补发后续事件。 +- resync 降级：如果 `lastEventId` 已过期（超出保留窗口），服务端返回 `event: resync`。前端收到 `resync` 后，放弃增量补发，改为 refetch 当前页面所有相关状态（通过 TanStack Query 的 `invalidateQueries` 批量刷新）。 +- 退避策略：重连间隔使用指数退避（1s → 2s → 4s → 8s → 最大 30s），连接成功后重置。 + +## 7. 接口边界 - 管理后台只调用 `/admin-api/**`。 - 用户端只调用 `/app-api/**`。 @@ -197,7 +232,7 @@ muse-studio/ - 前端禁止绕过接口直接访问数据库、对象存储私有地址、RAGFlow、New-API 或内部模型服务。 - 导出和下载前端必须承接服务端返回的导出清单(included/excluded manifest)：展示已包含内容、已排除内容、排除原因、下载凭证有效期和来源/授权重验状态。下载凭证过期、来源被召回或授权被撤销时，用户端必须重新检查或重新生成，不能继续显示单一“成功下载”态。 -## 7. 权限与导航边界 +## 8. 权限与导航边界 - Vben 管理后台的菜单、按钮和页面权限来自 `system` 菜单权限体系。 - `muse-studio` 的导航可见性来自用户权益、授权、作品权限和业务状态。 @@ -206,7 +241,43 @@ muse-studio/ - 用户端不允许通过 URL 进入管理后台配置。 - 用户端市场购买、安装、绑定成功后，只刷新授权、安装状态、可用动作和来源授权快照；不会把市场资产内容自动写入作品正文、Local KB 或规划正式事实。 -## 8. 关联阅读 +## 9. 跨空间跳转与 Handoff 前端消费 + +市场购买、安装或绑定资产后，用户需要从市场空间跳转到目标空间（知识库工作台、智能体工作台或作品工作台）完成绑定或使用。Handoff token 是跨空间跳转的前端传递机制。 + +### 9.1 Handoff token 前端生命周期 + +创建： + +- 市场购买/安装成功后，前端调用 `POST /app-api/muse/marketplace/handoffs` 创建 handoff token。 +- 服务端返回 `handoffToken`、过期时间和目标 owner 消费入口。 + +传递方式： + +- Handoff token 通过 URL query parameter 传递到目标空间页面，例如 `/works/[workId]/knowledge?handoffToken=xxx`。 +- 前端路由守卫在目标页面解析 `handoffToken` 参数。 +- 传递后立即从 URL 中移除 `handoffToken`（使用 `replaceState`），避免刷新重复消费。 + +目标空间消费： + +- 知识库绑定：目标页面解析 handoff token 后，调用 `POST /app-api/muse/works/{workId}/knowledge-bindings/prechecks` 传入 handoff 信息，获取 `kbBindPrecheckId`，再调用绑定接口完成绑定。 +- 智能体槽位替换：目标页面调用 `POST /app-api/muse/works/{workId}/agent-slots/{slotKey}/prechecks` 传入 handoff 信息，获取 `agentSlotPrecheckId`，再调用绑定接口完成槽位替换。 +- 前端不能自造 precheck，必须由目标 owner 基于 handoff token 生成。 + +过期/取消处理： + +- Handoff token 有短期时效（服务端定义）。 +- 过期时前端展示"跳转授权已过期，请返回市场重新操作"，引导用户回到市场空间。 +- 用户可主动取消（`POST /app-api/muse/marketplace/handoffs/{handoffToken}/cancel`）。 +- 已消费的 handoff 不可重复使用；重复消费返回 `MARKET_HANDOFF_INVALID`，前端提示并引导刷新。 + +### 9.2 Handoff 状态查询 + +- 前端可调用 `GET /app-api/muse/marketplace/handoffs/{handoffToken}` 查询 handoff 当前状态。 +- 状态包括：有效、已消费、已过期、已取消。 +- 目标页面在消费前应先查询状态，避免对已失效 handoff 发起无效请求。 + +## 10. 关联阅读 - 产品定位：`产品-01-产品定位与核心价值.md` - 功能总纲：`产品-02-核心功能与交互边界.md` diff --git a/design-docs/前端-02-编辑器与影子层交互.md b/design-docs/前端-02-编辑器与影子层交互.md index 46e8328f..381f32fb 100644 --- a/design-docs/前端-02-编辑器与影子层交互.md +++ b/design-docs/前端-02-编辑器与影子层交互.md @@ -48,7 +48,65 @@ muse-studio | 本地继续编辑后服务端失败 | 禁止静默覆盖新输入，进入显式冲突态 | | 来源或授权变化 | 拦截接受/确认动作，引导重验或重新生成 | -## 4. 待确认对象分组 +## 4. 正文持久化与恢复 + +### 4.1 自动保存 + +编辑器内容变化后 debounce 2s 触发保存到服务端（`PUT /app-api/muse/works/{workId}/blocks/{blockId}`），携带 `expectedRevision` 做乐观并发控制。 + +保存状态指示器： + +| 状态 | UI 展示 | 说明 | +|---|---|---| +| 已保存 | "已保存" + 时间戳 | 最近一次保存成功 | +| 保存中 | "保存中..." + loading | debounce 触发后等待响应 | +| 保存失败 | "保存失败（点击重试）" + 错误色 | 网络异常或 revision 冲突 | + +### 4.2 IndexedDB 安全网 + +- 每次编辑变化同步写入 IndexedDB，key 为 `workId + blockId`，value 包含内容、本地时间戳和最后已知 revision。 +- IndexedDB 写入不依赖服务端响应，作为崩溃恢复安全网。 +- 正常情况下用户无感知 IndexedDB 的存在。 + +### 4.3 恢复入口 + +- 页面加载时对比 IndexedDB 版本与服务端版本（通过本地时间戳和服务端 `updatedAt` 比较）。 +- 如果 IndexedDB 内容比服务端更新（说明上次保存未成功提交），展示恢复提示："检测到未保存的本地修改，是否恢复？" +- 用户选择恢复：将 IndexedDB 内容加载到编辑器，触发一次保存。 +- 用户选择放弃：清除 IndexedDB 中该 Block 的本地缓存，使用服务端版本。 +- 保存成功后清除对应 IndexedDB 条目（或更新为与服务端一致）。 + +## 5. Block 模型与编辑器映射 + +### 5.1 Block 粒度 + +Block 粒度为场景/小节级。一个 Block 对应正文中一个相对独立的叙事单元（如一个场景、一个小节）。 + +### 5.2 分割点识别 + +- 自动识别：标题模式自动识别分割点，匹配 `##` 或「第X节」「第X章」等模式。 +- 手动标记：用户可在编辑器中手动插入或移除分割标记。 +- 编辑器中分割点可见（如水平分隔线 + 标签），但不干扰正常阅读和编辑。 + +### 5.3 Block 与 ProseMirror 的映射 + +- 每个 Block 对应一个独立的 ProseMirror Document（或顶级 Node）。 +- 编辑器加载时按 Block 顺序拼装为完整文档视图，Block 边界以不可编辑的分隔节点标识。 +- 每个 Block 独立维护 revision 和保存状态。 + +### 5.4 跨 Block 操作 + +- 选中跨 Block 文本时，操作拆分为对两个 Block 的独立修改，分别提交各自的 `expectedRevision`。 +- 跨 Block 删除、粘贴等操作在前端拆分为多个 Block 级 Transaction，按顺序提交。 +- 如果其中一个 Block 提交失败（revision 冲突），前端回滚该 Block 的本地变更并进入冲突处理。 + +### 5.5 AI 候选合并 + +- 接受候选时，通过 ProseMirror Transaction 替换目标 Block 内容。 +- Transaction 保留 undo history，用户可撤销合并操作（本地撤销不影响服务端已提交的 revision）。 +- 合并后立即触发保存，携带候选接受接口返回的新 revision。 + +## 6. 待确认对象分组 | 用户语言 | 底层对象 | 用户动作 | |---|---|---| @@ -64,7 +122,7 @@ muse-studio 规划候选的接受、修改后保存和丢弃必须走规划 owner 的 `/app-api/**` 决策接口，由后端写入或拒绝写入规划正式事实。前端不得复用 AI Suggestion 的 accept 接口，也不得把规划确认塞进动态表单的通用保存动作。 -## 5. AI 候选卡 +## 7. AI 候选卡 候选卡至少展示： @@ -73,10 +131,9 @@ muse-studio - 创作健康度和质量维度摘要。 - 风险标记。 - 使用和排除的来源。 -- 服务端候选决策包(Candidate Decision Envelope)的用户可读摘要；用户界面不显示内部合同名。 -- 可用动作。 +- 可用动作和硬闸门状态摘要（用户可读语言，不显示内部合同名）。 -动作展示必须等待服务端返回最新 Candidate Decision Envelope 和硬闸门结果。前端可以展示本地草稿、质量摘要和加载态，但不能基于本地评分、本地 Zod 校验或按钮可见性自行允许接受或合并。 +动作展示必须等待服务端返回最新硬闸门结果。前端可以展示本地草稿、质量摘要和加载态，但不能基于本地评分、本地 Zod 校验或按钮可见性自行允许接受或合并。 动作约束： @@ -117,7 +174,16 @@ muse-studio - “引用来源已被召回，当前候选不能继续接受” - “安装成功，可在作品中选择使用” -## 6. 创作健康度展示 +### 7.1 候选接受与来源校验 + +接受时前端调用接口（`POST /app-api/muse/suggestions/{suggestionId}/accept`），后端实时校验来源版本和授权状态。前端不在本地缓存或判定来源有效性，每次接受操作由服务端做最终决策。 + +- 接受前：前端调用候选详情接口获取最新可用动作和硬闸门状态。 +- 接受请求：传入 `suggestionId`、`expectedRevision` 和 `commandId`。 +- 版本不匹配：服务端返回 `STATE_CONFLICT`，前端刷新候选卡状态和可用动作。 +- 来源失效：服务端返回阻断原因，前端展示用户可理解的阻断说明。 + +## 8. 创作健康度展示 创作健康度是候选解释，不是作品排名。 @@ -130,10 +196,149 @@ muse-studio - 下一步动作：接受、修改后合并、丢弃、重生成、重验来源。 前端不能绕过 blocked / invalidated / needs_recheck 接受候选。 + + +候选状态 `invalidated` 的 UI 处理：展示"已失效，不可接受"，禁用接受和合并按钮，允许用户触发重新生成。候选失效原因（来源撤权、授权过期、质量结果过期等）必须以产品语言展示。 用户可以选择开放槽位中的智能体或知识库，但不能替换输入输出合规、拆分切块、RAG 入库、语义安全围栏、静态检查、质量门控、权限、审计和 Shadow -> Canonical 等保护节点。写作台只展示可选项和不可用原因，不暴露底层 Pipeline 控制权。 -## 7. 同步与恢复 +### 8.1 Source Status 前端处理策略 + +来源状态(Source Status)是候选、知识草稿、绑定和导出动作的前置条件。前端必须统一处理来源状态到 UI 的映射（参见 `后端-05-统一API契约-v1.md` §4.2 Source Status 定义）。 + +来源状态到 UI 映射表： + +| sourceStatus | UI 展示 | 接受/确认按钮 | 用户可用动作 | +|---|---|---|---| +| `active` | 来源正常（默认不额外提示） | 启用 | 正常操作 | +| `stale` | "来源版本已更新，建议刷新" | 启用（带警告） | 刷新来源、继续操作 | +| `needs_recheck` | "来源需要重新验证" | 禁用 | 触发重验 | + +| `revoked` | "来源授权已撤销" | 禁用 | 查看原因、替换来源 | +| `recalled` | "来源已被召回" | 禁用 | 查看原因、替换来源 | +| `delisted` | "来源已下架" | 禁用 | 查看原因、替换来源 | +| `blocked` | "来源已被阻断" | 禁用 | 查看原因、替换来源 | +| `owner_missing` | "来源归属缺失" | 禁用 | 联系支持、替换来源 | +| `unauthorized` | "来源授权不足" | 禁用 | 重新授权、替换来源 | + +查询时机： + +- 候选展示时：候选详情接口返回 `sourceSnapshot` 包含当前来源状态。 +- 定期轮询：对处于 `needs_recheck` 或 `stale` 的来源，前端按 TanStack Query 的 `refetchInterval` 定期刷新状态（建议 30s-60s）。 + +- 用户主动刷新：提供"刷新来源状态"按钮。 + +重验触发和结果展示： + +- 用户点击"重新验证"调用 `POST /app-api/muse/source-status/recheck`，返回 `jobId`。 +- 重验是异步任务，前端进入轮询等待。 +- 重验完成后刷新来源状态；如果恢复为 `active`，重新启用接受/确认按钮。 +- 重验失败或来源仍不可用时，展示失败原因和下一步建议。 + +来源失效时的 UI 降级： + +- 禁用接受、确认、绑定和导出按钮。 +- 展示失效原因（使用产品语言，不暴露技术状态码）。 +- 候选卡标记为"来源不可用"，视觉降级（灰色或警告色）。 +- 已展示的候选内容保留可读，但不可操作。 + +## 9. 作品规划台交互 + +作品规划台(Planning Desk)是用户打开某个作品后的规划入口，与写作台平级。 + +### 9.1 一级入口切换 + +规划台包含五个一级入口，以 Tab 或侧边导航切换： + +| 入口 | 内容 | 切换逻辑 | +|---|---|---| +| 作品设定 | 题材、类型、主题、基调、禁区、结局方向 | 默认入口；切换时拉取最新投影和已确认数据 | +| 章节大纲 | 章节顺序、摘要、目标、主线、支线、伏笔、情节节拍 | 切换时加载章节列表和大纲结构 | +| 世界设定 | 角色、地点、物品、组织、规则、事件、时间线 | 切换时加载世界设定投影 | +| 角色关系 | 角色档案、目标、动机、弱点、秘密、弧光、关系变化 | 切换时加载角色列表和关系图数据 | +| 文风检查 | 作者声音、句式、节奏、视角、风格漂移 | 切换时加载最近检查结果或空态 | + +切换逻辑约束： + +- 每次切换调用 `/app-api/muse/works/{workId}/meta-projections/{projectionKey}` 获取当前 section 的可见结构和数据。 +- 切换不丢弃用户未提交的本地草稿；离开时提示保存或放弃。 +- 各 section 的表单渲染由 MetaSchema 动态表单驱动（参见 `前端-03-元引擎与动态表单.md` §5.2 用户端渲染链路）。 + +### 9.2 规划候选展示与确认 + +用户触发 AI 生成、补全或整理后，结果以规划候选卡展示： + +- 候选卡展示候选方案、来源摘要、质量结果和 diff（与当前正式规划的差异）。 +- 可用动作：接受为规划项、修改后保存、丢弃。 +- 接受调用 `POST /app-api/muse/works/{workId}/planning/candidates/{candidateId}/confirm`。 +- 丢弃调用 `POST /app-api/muse/works/{workId}/planning/candidates/{candidateId}/discard`。 +- 修改后保存：用户编辑候选内容后调用 confirm，传入修改后的数据。 +- 候选确认必须带 `commandId`、`expectedRevision`、`sourceSnapshot`、`authorizationSnapshotId`。 + +多组候选时以列表或对比视图展示，用户逐一确认或丢弃。 + +### 9.3 文风检查结果展示 + +文风检查是异步任务： + +1. 用户点击"文风检查"触发 `POST /app-api/muse/works/{workId}/planning/style-checks`，返回 `jobId`。 +2. 前端进入轮询或通知等待。 +3. 完成后调用 `GET /app-api/muse/works/{workId}/planning/style-checks/{jobId}` 获取结果。 +4. 展示内容：风格漂移标记、句式分析、节奏评估、视角一致性、禁用风格命中和建议入口。 +5. 检查结果只读展示，不直接修改正文或规划；用户可据此手动调整或触发重新生成。 + +### 9.4 动态表单渲染 + +规划台各 section 的表单字段、校验规则、可见性和可编辑状态均由后端投影返回，前端按 MetaSchema 动态表单渲染（参见 `前端-03-元引擎与动态表单.md` §3 用户端创作表单和 §5.2 用户端渲染链路）。 + +提交时必须带 `expectedSchemaVersion`、`expectedProjectionVersion` 和 `expectedDataRevision`，走 planning owner 的 `PUT /app-api/muse/works/{workId}/planning/{sectionKey}` 接口。 + +## 10. 知识与一致性工作面 + +知识与一致性工作面是用户在作品工作台中管理局域知识、处理知识草稿和检查一致性的入口。 + +### 10.1 局域知识库浏览 + +- 入口：作品工作台的"知识"Tab 或侧边导航。 +- 调用 `GET /app-api/muse/works/{workId}/local-knowledge` 获取当前作品 Local KB 内容。 +- 展示已确认知识条目列表，支持按类型（角色、地点、物品、规则等）筛选。 +- 每条知识展示来源归因、确认时间和关联章节。 +- 只读浏览；修正入口见 §8.4。 + +### 10.2 知识草稿处理 + +知识草稿(Knowledge Draft)来自 AI 提取、导入解析或正文候选合并后的重新提取。 + +列表展示： + +- 调用 `GET /app-api/muse/works/{workId}/knowledge-drafts` 获取待确认草稿列表。 +- 每条草稿展示：提取内容摘要、来源章节/Block、来源状态、风险标记。 +- 状态标记：`pending`（待确认）、`confirmed`（已确认）、`ignored`（已忽略）、`invalidated`（已失效）、`needs_reextract`（需重新提取）。 + +详情与动作： + +- 点击草稿进入详情，展示完整提取内容、来源 lineage 和授权快照。 +- 可用动作：确认（`POST /app-api/muse/knowledge-drafts/{draftId}/confirm`）、忽略（`POST /app-api/muse/knowledge-drafts/{draftId}/ignore`）、重验来源（`POST /app-api/muse/knowledge-drafts/{draftId}/recheck`）。 +- `invalidated` 状态展示"已失效，不可接受"，允许触发重新生成。 +- `needs_reextract` 状态展示"需重新提取，原草稿已过时"，引导用户触发重新提取或等待系统自动重新提取。 + +### 10.3 一致性检查结果展示 + +一致性检查由 AI 任务产生，结果展示： + +- 设定冲突列表：冲突的知识条目对、冲突类型和严重性。 +- 角色失声提醒：长期未出现的角色或关系停滞。 +- 时间线矛盾：事件顺序或时间跨度不一致。 +- 每条结果关联到具体章节和知识条目，支持跳转定位。 +- 结果只读展示，不自动修正。 + +### 10.4 手动修正入口 + +- 用户可从一致性检查结果或局域知识浏览中发起手动修正。 +- 修正走规划 owner 或知识 owner 的对应命令接口，不走通用动态字段保存。 +- 修正后相关知识草稿可能失效，需重新提取。 + +## 11. 同步与恢复 服务器状态建议由 TanStack Query 管理： @@ -160,22 +365,29 @@ muse-studio 3. 不可重试失败禁用动作并解释原因。 4. 任务型操作进入轮询或通知，不阻塞正文已成功保存的主事务。 -## 8. 导入解析与导出 UI +## 12. 导入解析与导出 UI - 导入入口属于作品工作台，不属于作品列表深层弹窗。 - 导入正文可初始化章节和 Block。 - 全书解析必须展示章节级进度、失败原因和章节审阅入口。 - 章节审阅确认只推进到 Knowledge Draft 处理，不直接写 Local KB。 - 详情页负责解释，不提供逐条绕过章节边界的确认。 +全书解析审阅交互： + +- 章节级确认/驳回：每个 Chapter Parse Result 独立展示，用户可逐章确认（`POST /app-api/muse/chapter-parse-results/{resultId}/confirm`）或驳回（`POST /app-api/muse/chapter-parse-results/{resultId}/reject`）。 +- 一键确认可确认章节：对所有状态为可确认且无高风险标记的章节，提供批量确认入口（`POST /app-api/muse/parse-jobs/{jobId}/chapters/batch-confirm`）。批量确认以章节为事务边界，允许部分失败。 +- 高风险冲突处理：高风险章节（来源状态异常、质量阻断、revision 冲突）标记为不可批量确认，必须逐章审阅后单独处理。 +- 部分失败展示：批量确认响应返回 `confirmedChapterResultIds`、`failedChapters`、`skippedChapters` 和 `partialFailure` 标记。前端按逐章结果展示成功、失败原因和可重试项；某章失败不影响已成功章节。 + - 导出入口属于作品工作台，必须展示服务端返回的已包含/已排除导出清单(included/excluded manifest)、排除原因和可恢复动作。 - 下载凭证有时效和授权快照；凭证过期、来源被召回、授权被撤销或任务进入需重验时，前端必须禁用下载并引导重新检查或重新导出。 - 导出成功态不能压扁成单一“下载成功”；页面还要保留导出记录、下载状态、凭证失效、来源撤销后重验和部分内容被排除的说明。 -## 9. 与管理后台关系 +## 13. 与管理后台关系 管理后台可以查看内容异常、导入导出记录、任务失败和治理摘要，但不承载普通用户写作台。管理员不能通过后台替用户接受 AI 候选、保存正文或确认作品知识。 -## 10. 关联阅读 +## 14. 关联阅读 - 用户工作区规格：`产品-02C-用户工作区与作品工作台功能规格.md` - 普通用户操作流程：`流程-01B-普通用户操作流程(操作视角).md` diff --git a/design-docs/前端-03-元引擎与动态表单.md b/design-docs/前端-03-元引擎与动态表单.md index 40cf0067..69f71c37 100644 --- a/design-docs/前端-03-元引擎与动态表单.md +++ b/design-docs/前端-03-元引擎与动态表单.md @@ -119,7 +119,7 @@ 用户确认必须走对应业务入口：规划候选进入规划正式事实，Knowledge Draft 进入 Local KB，正文候选进入正文 Block。规划候选的接受、修改后保存和丢弃必须走 planning owner 的 `/app-api/**` 决策接口，不得复用 AI Suggestion accept，也不得通过动态表单通用保存写入规划正式事实。 -前端不得把 `PUT /dynamic-fields/{targetType}/{targetId}` 封装成可写任意目标事实的通用 SDK。即使后端接口路径包含 dynamic-fields，也必须由当前 owner 投影限定 targetType、targetId、可编辑字段、版本和动作语义；规划、知识、正文的正式事实仍分别通过 Planning / Knowledge / Content owner action 进入。 +前端禁止封装通用动态字段写入 SDK。动态字段没有跨 owner 的通用写接口（参见 `后端-05-统一API契约-v1.md` §4.3 作品和正文中的投影说明）；正式写入必须回到目标 owner 命令路径：规划写 `PUT /app-api/muse/works/{workId}/planning/{sectionKey}`，正文写 `PUT /app-api/muse/blocks/{blockId}`，知识写 Knowledge Draft confirm/ignore 命令，Agent 写 Agent 配置命令。前端只能调用 `/app-api/muse/works/{workId}/dynamic-fields/validate` 做校验和路由建议，不能据此直接写入任何 Canonical fact。 ### 5.3 版本兼容和提交合同 diff --git a/design-docs/前端-04-市场与个人中心交互.md b/design-docs/前端-04-市场与个人中心交互.md new file mode 100644 index 00000000..a034797e --- /dev/null +++ b/design-docs/前端-04-市场与个人中心交互.md @@ -0,0 +1,840 @@ +# 前端-04：市场与个人中心交互 + +- 版本：v1 +- 更新日期：2026-05-24 +- 目标读者：前端开发者 +- 阅读时间：40-60 分钟 +- 归属仓库：`muse-studio/`（用户端）+ `muse-admin/`（管理端市场治理） +- 边界说明：本文件定义市场空间和个人中心空间在 `muse-studio` 用户端的前端交互设计，包括页面结构、组件职责、API 调用、状态管理、Handoff 消费和错误处理。精确 API 看 `后端-05`，产品功能规格看 `产品-02F` 和 `产品-02G`，Handoff 机制看 `架构-01`。 + +--- + +## 1. 路由结构 + +基于 `前端-01` 的路由约定，市场和个人中心在 `muse-studio/` 中的路由组织如下： + +```text +muse-studio/ + app/ + (user)/ + marketplace/ + page.tsx # 市场首页与发现 + categories/ + page.tsx # 分类推荐与曝光 + assets/ + [assetId]/ + page.tsx # 资产详情 + acquire/page.tsx # 获取授权确认 + install/page.tsx # 安装与跳转授权入口 + records/page.tsx # 资产级记录 + governance/page.tsx # 治理结果与申诉 + publish/ + page.tsx # 发布者资产与提交状态 + [draftId]/page.tsx # 发布提交 + profile/ + page.tsx # 账户总览 + info/page.tsx # 个人资料与账号信息 + security/page.tsx # 安全与登录 + preferences/page.tsx # 偏好与通知 + usage/page.tsx # Token 与用量总览 + entitlements/page.tsx # 权益与配额 + authorizations/page.tsx # 授权获取记录 + purchases/page.tsx # 购买记录 + installations/page.tsx # 安装与绑定摘要 + publications/page.tsx # 发布记录总览 + components/ + marketplace/ + personal-center/ +``` + +## 2. 市场空间 + +### 2.1 页面结构总览 + +| 页面 | 路由 | 核心组件 | 主要 API | +|---|---|---|---| +| 市场首页与发现 | `/marketplace` | `MarketSearch`, `AssetTypeTab`, `RecommendSection`, `AssetList` | `GET /app-api/muse/marketplace/assets`, `GET /app-api/muse/marketplace/categories` | +| 分类推荐与曝光 | `/marketplace/categories` | `CategoryTree`, `TopicCard`, `ExposureSummary` | `GET /app-api/muse/marketplace/categories` | +| 资产详情 | `/marketplace/assets/[assetId]` | `AssetHeader`, `LicensePanel`, `VersionInfo`, `GovernanceAlert`, `ActionBar` | `GET /app-api/muse/marketplace/assets/{assetId}` | +| 获取授权确认 | `/marketplace/assets/[assetId]/acquire` | `LicenseConfirm`, `RestrictionList`, `ExternalAuthRef` | `POST /app-api/muse/marketplace/assets/{assetId}/purchase` | +| 安装与跳转授权 | `/marketplace/assets/[assetId]/install` | `InstallPanel`, `TargetSelector`, `HandoffGenerator` | `POST /app-api/muse/marketplace/assets/{assetId}/install`, `POST /app-api/muse/marketplace/handoffs` | +| 发布者资产 | `/marketplace/publish` | `PublisherAssetList`, `StatusFilter`, `ExposureBadge` | `GET /app-api/muse/marketplace/my-publish-records` | +| 发布提交 | `/marketplace/publish/[draftId]` | `PublishForm`, `CheckRunner`, `SubmitConfirm` | `POST /app-api/muse/marketplace/publish-drafts`, `POST /app-api/muse/marketplace/publish-drafts/{draftId}/checks`, `POST /app-api/muse/marketplace/publish-requests` | +| 治理结果与申诉 | `/marketplace/assets/[assetId]/governance` | `GovernanceResult`, `ImpactList`, `AppealForm` | `GET /app-api/muse/marketplace/assets/{assetId}/governance-impact`, `POST /app-api/muse/marketplace/appeals` | +| 资产级记录 | `/marketplace/assets/[assetId]/records` | `RecordTimeline`, `RecordFilter` | 资产级记录通过详情页内嵌展示 | + +### 2.2 资产发现交互 + +#### 2.2.1 搜索与筛选 + +```typescript +// lib/queries/marketplace.ts +// 市场资产列表查询 hook +export function useMarketplaceAssets(params: MarketplaceAssetsParams) { + return useQuery({ + queryKey: ['marketplace', 'assets', params], + queryFn: () => fetchMarketplaceAssets(params), + // 保持搜索词、分类、筛选和滚动位置 + // 注意：keepPreviousData 是 TanStack Query v4 写法，v5 改用 placeholderData: keepPreviousData（从 @tanstack/react-query 导入） + keepPreviousData: true, + }); +} + +interface MarketplaceAssetsParams { + keyword?: string; // 搜索关键词 + assetType?: 'work' | 'agent' | 'knowledge_base'; // 资产类型 + categoryId?: string; // 分类 ID + licenseType?: string; // 许可类型筛选 + status?: string; // 状态筛选 + sortBy?: 'relevance' | 'newest' | 'popular'; // 排序 + pageNo: number; + pageSize: number; +} +``` + +交互规则： + +- 搜索框支持即时搜索（debounce 300ms），按资产类型 Tab 切换不清空搜索词。 +- 筛选条件变化时重置分页到第一页，保留搜索词。 +- 从详情页返回时恢复搜索词、分类、筛选和滚动位置（通过 URL searchParams 持久化）。 +- 未登录用户只能浏览公开摘要，获取、安装、绑定和收藏操作需要登录。 + +#### 2.2.2 推荐位 + +推荐区独立加载，失败不阻断列表渲染： + +```typescript +// 推荐位独立查询，失败时静默降级 +export function useMarketplaceRecommendations() { + return useQuery({ + queryKey: ['marketplace', 'recommendations'], + queryFn: () => fetchCategories(), // GET /app-api/muse/marketplace/categories + retry: 1, + // 注意：useErrorBoundary 是 TanStack Query v4 写法，v5 改用 throwOnError + // 推荐位加载失败不影响主列表 + useErrorBoundary: false, + }); +} +``` + +#### 2.2.3 收藏 + +```typescript +// 收藏/取消收藏 mutation +export function useFavoriteAsset() { + return useMutation({ + mutationFn: ({ assetId, action }: { assetId: string; action: 'add' | 'remove' }) => + action === 'add' + ? postFavorite(assetId) // POST /app-api/muse/marketplace/assets/{assetId}/favorite + : deleteFavorite(assetId), // DELETE /app-api/muse/marketplace/assets/{assetId}/favorite + onSuccess: () => { + queryClient.invalidateQueries(['marketplace', 'assets']); + }, + }); +} +``` + +### 2.3 购买/安装流程 UI + +#### 2.3.1 获取授权确认页 + +获取授权确认页展示许可、版本、限制和外部授权引用状态。核心交互流程： + +1. 进入页面时加载资产详情和获取确认信息。 +2. 展示许可范围、允许用途、禁止用途、有效期。 +3. 用户确认后调用购买接口，必须携带 `commandId` 幂等键。 +4. 获取成功后可选择进入安装页或返回详情。 + +```typescript +// 获取授权 mutation +export function usePurchaseAsset() { + return useMutation({ + mutationFn: (params: { + assetId: string; + commandId: string; // 幂等键，前端生成 UUID + }) => postPurchase(params.assetId, { commandId: params.commandId }), + // POST /app-api/muse/marketplace/assets/{assetId}/purchase + }); +} +``` + +状态管理： + +| 状态 | UI 表现 | 用户动作 | +|---|---|---| +| 可获取 | 主按钮"确认获取"可用 | 点击确认 | +| 需登录 | 主按钮禁用，提示登录 | 跳转登录 | +| 外部授权待确认 | 主按钮禁用，展示外部状态 | 刷新外部授权 | +| 授权失败 | 展示失败原因 | 重试或返回 | +| 已拥有 | 展示"已获取"，引导安装 | 跳转安装页 | +| 资产不可获取 | 展示原因（下架/召回） | 返回列表 | + +#### 2.3.2 安装流程 + +安装只适用于智能体和知识库资产。安装成功只表示资产进入账户可用列表，不等于绑定到作品。 + +```typescript +// 安装 mutation +export function useInstallAsset() { + return useMutation({ + mutationFn: (params: { + assetId: string; + commandId: string; + }) => postInstall(params.assetId, { commandId: params.commandId }), + // POST /app-api/muse/marketplace/assets/{assetId}/install + }); +} +``` + +#### 2.3.3 安装进度与结果 + +安装为同步操作，响应直接返回安装状态。UI 展示： + +- 安装中：按钮 loading 态。 +- 安装成功：展示"已安装"标记，显示可绑定目标摘要和跳转入口。 +- 安装失败：展示失败原因（授权失效、版本不可用、来源下架）。 + +### 2.4 Handoff 机制的前端消费 + +#### 2.4.1 Handoff 概述 + +市场跨空间跳转使用服务端签发的一次性 handoff token。前端职责： + +1. 在市场空间发起 handoff 创建请求。 +2. 获取 handoff token 和目标页 URL。 +3. 携带 token 跳转到目标 owner 空间。 +4. 目标空间落地后消费 token，获取 handoff session。 +5. 基于 session 执行目标 owner 的预检和确认。 + +#### 2.4.2 创建 Handoff + +```typescript +// 创建市场 handoff +export function useCreateHandoff() { + return useMutation({ + mutationFn: (params: CreateHandoffParams) => + postHandoff(params), + // POST /app-api/muse/marketplace/handoffs + }); +} + +interface CreateHandoffParams { + assetId: string; + targetOwner: 'knowledge' | 'agent' | 'content'; + targetAction: 'bind' | 'slot_bind' | 'asset_use'; + targetWorkId?: string; + returnUrl: string; // 返回点 + commandId: string; // 幂等键 +} +``` + +#### 2.4.3 目标空间消费 Handoff + +目标空间（如作品知识来源页）落地时： + +```typescript +// 目标空间消费 handoff token +export function useConsumeHandoff(handoffToken: string | null) { + return useQuery({ + queryKey: ['handoff', handoffToken], + queryFn: () => getHandoffStatus(handoffToken!), + // GET /app-api/muse/marketplace/handoffs/{handoffToken} + enabled: !!handoffToken, + }); +} +``` + +#### 2.4.4 Token 过期处理 + +| 场景 | 错误码 | 前端处理 | +|---|---|---| +| Token 不存在 | `MARKET_HANDOFF_INVALID` | 返回市场刷新状态 | +| Token 已过期 | `PRECHECK_EXPIRED` | 提示过期，引导重新发起 | +| Token 已消费 | `MARKET_HANDOFF_INVALID` | 展示已消费状态 | +| Token 已取消 | `MARKET_HANDOFF_INVALID` | 返回市场 | +| 目标 owner 不匹配 | `MARKET_HANDOFF_INVALID` | 返回市场刷新 | + +#### 2.4.5 Handoff 状态轮询 + +对于需要等待目标空间确认的场景，市场侧可轮询 handoff 状态： + +```typescript +// 轮询 handoff 状态（用户从目标空间返回后刷新） +export function useHandoffStatus(handoffToken: string) { + return useQuery({ + queryKey: ['handoff', 'status', handoffToken], + queryFn: () => getHandoffStatus(handoffToken), + // GET /app-api/muse/marketplace/handoffs/{handoffToken} + refetchOnWindowFocus: true, // 用户从目标空间返回时自动刷新 + }); +} +``` + +### 2.5 发布准备 UI + +#### 2.5.1 发布提交流程 + +发布提交页面按资产类型（作品、智能体、知识库）分型展示不同表单字段和检查项。 + +流程步骤： + +1. 保存发布草稿 → `POST /app-api/muse/marketplace/publish-drafts` +2. 运行发布检查 → `POST /app-api/muse/marketplace/publish-drafts/{draftId}/checks` +3. 检查通过后提交审核 → `POST /app-api/muse/marketplace/publish-requests` + +```typescript +// 发布检查 mutation +export function useRunPublishCheck() { + return useMutation({ + mutationFn: (draftId: string) => + postPublishCheck(draftId), + // POST /app-api/muse/marketplace/publish-drafts/{draftId}/checks + }); +} + +// 提交发布申请 mutation +export function useSubmitPublishRequest() { + return useMutation({ + mutationFn: (params: { + draftId: string; + marketPublishCheckId: string; // 消费发布检查结果 + commandId: string; + }) => postPublishRequest(params), + // POST /app-api/muse/marketplace/publish-requests + }); +} +``` + +#### 2.5.2 发布检查状态 + +| 检查状态 | UI 表现 | 用户动作 | +|---|---|---| +| 未检查 | "运行检查"按钮可用 | 点击运行 | +| 检查中 | 按钮 loading，展示进度 | 等待 | +| 检查通过 | 展示通过项，"提交审核"可用 | 提交 | +| 检查失败 | 展示阻断项和警告项 | 修正后重新检查 | +| 检查过期 | 提示过期，需重新检查 | 重新运行 | + +#### 2.5.3 来源状态确认 + +发布前必须确认来源资产状态。前端调用来源状态查询： + +```typescript +// 查询来源状态 +export function useSourceStatus(params: SourceStatusParams) { + return useQuery({ + queryKey: ['source-status', params], + queryFn: () => postSourceStatusQuery(params), + // POST /app-api/muse/source-status/query + }); +} +``` + +来源状态异常时禁用发布提交按钮，展示原因和处理建议。 + +### 2.6 治理结果展示 + +#### 2.6.1 下架/召回通知 + +资产详情页顶部展示治理状态 Alert： + +```typescript +// 治理影响查询 +export function useGovernanceImpact(assetId: string) { + return useQuery({ + queryKey: ['marketplace', 'governance-impact', assetId], + queryFn: () => getGovernanceImpact(assetId), + // GET /app-api/muse/marketplace/assets/{assetId}/governance-impact + enabled: !!assetId, + }); +} +``` + +UI 展示规则： + +| 治理状态 | Alert 类型 | 展示内容 | 可用动作 | +|---|---|---|---| +| 已下架 | warning | 下架原因、影响范围 | 查看替代、申诉 | +| 召回中 | error | 召回原因、影响范围、处理期限 | 停用安装、申诉 | +| 授权撤销 | error | 撤销原因、影响绑定 | 重新获取、替代 | +| 申诉中 | info | 申诉进度、预计处理时间 | 补充材料、撤回 | + +#### 2.6.2 违规说明 + +违规说明展示在治理结果页，包含： + +- 结果类型和原因摘要 +- 生效时间 +- 影响范围（新获取、新安装、新绑定、生成使用是否停止） +- 替代方案建议 +- 申诉入口和期限 + +### 2.7 来源状态反馈 + +#### 2.7.1 来源失效 UI + +当资产来源失效时，前端根据 `sourceStatus` 和 `actionPolicy` 展示不同 UI： + +| sourceStatus | actionPolicy | UI 表现 | +|---|---|---| +| `active` | `allowed` | 正常展示，所有操作可用 | +| `stale` | `needs_recheck` | 黄色提示条，建议重验，提供重验按钮 | +| `revoked` | `blocked` | 红色提示，禁用绑定/生成 | +| `recalled` | `blocked` | 红色提示，展示召回说明 | +| `delisted` | `blocked` | 灰色提示，展示下架原因 | + +#### 2.7.2 授权变化展示 + +授权状态变化时，资产详情页和安装页实时反映： + +```typescript +// 资产详情页监听授权状态 +// 通过 refetchOnWindowFocus 和 refetchInterval 保持最新 +export function useAssetDetail(assetId: string) { + return useQuery({ + queryKey: ['marketplace', 'asset', assetId], + queryFn: () => getAssetDetail(assetId), + // GET /app-api/muse/marketplace/assets/{assetId} + refetchOnWindowFocus: true, + staleTime: 30_000, // 30 秒内不重复请求 + }); +} +``` + +### 2.8 错误处理和边界情况 + +#### 2.8.1 通用错误处理策略 + +```typescript +// lib/api/error-handler.ts +// 市场空间错误处理映射 +const marketplaceErrorHandlers: Record = { + UNAUTHENTICATED: () => redirectToLogin(), + FORBIDDEN: (ctx) => showNoPermissionToast(ctx.msg), + RESOURCE_NOT_FOUND: () => redirectToMarketplaceHome(), + SOURCE_NEEDS_RECHECK: (ctx) => showRecheckPrompt(ctx.data), + SOURCE_BLOCKED: (ctx) => showBlockedAlert(ctx.data), + PRECHECK_EXPIRED: (ctx) => showExpiredPrompt(ctx.data), + MARKET_HANDOFF_INVALID: () => redirectToMarketplaceWithRefresh(), + IDEMPOTENCY_CONFLICT: (ctx) => showConflictToast(ctx.msg), + FEATURE_DISABLED: (ctx) => hideOrDisableEntry(ctx.data), +}; +``` + +#### 2.8.2 边界情况处理 + +| 边界情况 | 处理方式 | +|---|---| +| 资产在浏览过程中被下架 | 详情页展示下架提示，禁用获取/安装按钮 | +| 获取过程中授权失效 | 中断获取流程，展示失效原因 | +| Handoff 跳转后目标空间不可用 | 展示错误页，提供返回市场按钮 | +| 发布检查过程中资产版本变化 | 检查结果标记为过期，需重新检查 | +| 网络中断 | TanStack Query 自动重试，展示离线提示 | +| 分页加载失败 | 保留已加载数据，展示重试按钮 | + +--- + +## 3. 个人中心空间 + +### 3.1 页面结构总览 + +| 页面 | 路由 | 核心组件 | 主要 API | +|---|---|---|---| +| 账户总览 | `/profile` | `OverviewCard`, `SecurityCard`, `UsageCard`, `AssetSummaryCard`, `AlertBar` | `GET /app-api/muse/me`, `GET /app-api/muse/account/entitlements`, `GET /app-api/muse/account/usage` | +| 个人资料 | `/profile/info` | `ProfileForm`, `ContactVerification`, `AvatarUpload` | `GET /app-api/muse/profile`, `PATCH /app-api/muse/profile` | +| 安全与登录 | `/profile/security` | `PasswordSection`, `MFASection`, `SessionList`, `SecurityEventList` | `GET /app-api/muse/account/security-events` | +| 偏好与通知 | `/profile/preferences` | `PreferenceForm`, `NotificationSettings` | 偏好相关接口（复用 Yudao 基础能力） | +| Token 与用量 | `/profile/usage` | `UsageTrend`, `UsageTable`, `AttributionDetail` | `GET /app-api/muse/account/usage`, `GET /app-api/muse/account/entitlements` | +| 权益与配额 | `/profile/entitlements` | `EntitlementCard`, `QuotaProgress`, `ChangeLog` | `GET /app-api/muse/account/entitlements` | +| 授权获取记录 | `/profile/authorizations` | `AuthRecordTable`, `SnapshotDrawer` | `GET /app-api/muse/account/licenses` | +| 购买记录 | `/profile/purchases` | `PurchaseTable`, `ReceiptDrawer` | `GET /app-api/muse/account/purchases` | +| 安装与绑定摘要 | `/profile/installations` | `InstalledList`, `BindingAnomalyList` | 通过 `/app-api/muse/me` 和相关接口聚合 | +| 发布记录总览 | `/profile/publications` | `PublishRecordTable`, `StatusBadge` | `GET /app-api/muse/account/publish-records` | + +### 3.2 权益摘要展示 + +#### 3.2.1 `/app-api/muse/me` 数据消费 + +应用入口初始化时调用 `/app-api/muse/me`，获取当前用户权益摘要和可见产品空间： + +```typescript +// lib/queries/me.ts +// 当前用户信息和权益摘要 +export function useCurrentUser() { + return useQuery({ + queryKey: ['me'], + queryFn: () => fetchMe(), + // GET /app-api/muse/me + staleTime: 5 * 60 * 1000, // 5 分钟缓存 + refetchOnWindowFocus: true, + }); +} + +// 返回数据结构（前端类型定义） +interface MeResponse { + userId: string; + nickname: string; + avatar: string; + entitlementSummary: { + planName: string; + tokenQuota: number; + tokenUsed: number; + expiresAt: string | null; + isLimited: boolean; + }; + visibleSpaces: string[]; // 可见产品空间列表 + defaultEntry: string; // 默认入口 + securityRisk: boolean; // 是否有安全风险 + pendingAlerts: number; // 待处理提醒数 +} +``` + +#### 3.2.2 账户总览页数据聚合 + +账户总览页并行加载多个摘要接口： + +```typescript +// 账户总览页数据加载 +export function useProfileOverview() { + const me = useCurrentUser(); + const entitlements = useEntitlements(); + const usage = useUsageSummary(); + const securityEvents = useSecurityEvents({ limit: 5 }); + + return { + me, + entitlements, + usage, + securityEvents, + isLoading: me.isLoading || entitlements.isLoading, + }; +} + +// 权益与配额查询 +function useEntitlements() { + return useQuery({ + queryKey: ['account', 'entitlements'], + queryFn: () => fetchEntitlements(), + // GET /app-api/muse/account/entitlements + }); +} + +// 用量摘要查询 +function useUsageSummary() { + return useQuery({ + queryKey: ['account', 'usage'], + queryFn: () => fetchUsage(), + // GET /app-api/muse/account/usage + }); +} +``` + +### 3.3 配额和用量可视化 + +#### 3.3.1 配额进度条 + +权益与配额页使用进度条可视化展示额度消耗： + +```typescript +// components/personal-center/QuotaProgress.tsx +interface QuotaProgressProps { + label: string; // 配额名称 + total: number; // 总额度 + used: number; // 已用 + unit: string; // 单位（如 "Token"） + expiresAt?: string; // 到期时间 + isLimited?: boolean; // 是否被限流 +} +``` + +展示规则： + +- 使用率 < 70%：绿色进度条 +- 使用率 70%-90%：黄色进度条 + 提醒文案 +- 使用率 > 90%：红色进度条 + 额度不足警告 +- 已过期：灰色进度条 + 过期提示 +- 被限流：红色进度条 + 限流原因和恢复路径 + +#### 3.3.2 用量趋势图 + +Token 与用量页展示近 30 天用量趋势： + +```typescript +// 用量趋势数据 +export function useUsageTrend(params: { days: number; groupBy: 'day' | 'week' }) { + return useQuery({ + queryKey: ['account', 'usage', 'trend', params], + queryFn: () => fetchUsage(), + // GET /app-api/muse/account/usage（带时间范围参数） + }); +} +``` + +用量明细表支持按来源筛选： + +| 筛选维度 | 说明 | +|---|---| +| 时间范围 | 近 7 天 / 30 天 / 自定义 | +| 归属对象 | 作品 / 智能体 / 知识库 | +| 状态 | 已归属 / 待归属 / 异常 | + +#### 3.3.3 跳转来源记录 + +用量明细中的归属对象支持跳转到对应 owner 空间： + +```typescript +// 跨空间跳转（从个人中心到作品/智能体/知识库记录） +function handleJumpToSource(record: UsageRecord) { + const targetUrl = buildSourceUrl(record.sourceType, record.sourceId); + // 使用 router 跳转，携带返回点 + router.push(`${targetUrl}?returnTo=/profile/usage`); +} +``` + +### 3.4 安全事件列表和处理交互 + +#### 3.4.1 安全事件列表 + +```typescript +// 安全事件查询 +export function useSecurityEvents(params: { pageNo: number; pageSize: number }) { + return useQuery({ + queryKey: ['account', 'security-events', params], + queryFn: () => fetchSecurityEvents(params), + // GET /app-api/muse/account/security-events + }); +} +``` + +安全事件列表展示： + +| 字段 | 说明 | +|---|---| +| 事件类型 | 异地登录、密码修改、二次验证变更、会话异常 | +| 时间 | 事件发生时间 | +| 设备/地点 | 脱敏展示 | +| 风险等级 | 高/中/低 | +| 处理状态 | 未处理、已确认本人、已处理 | + +#### 3.4.2 确认非本人操作 + +高风险安全事件支持"确认本人操作"交互： + +```typescript +// 确认安全事件为本人操作 +export function useAcknowledgeSecurityEvent() { + return useMutation({ + mutationFn: (params: { + eventId: string; + confirmation: string; // 确认说明 + commandId: string; + }) => postAcknowledgeSecurityEvent(params), + // POST /app-api/muse/account/security-events/{eventId}/acknowledge + onSuccess: () => { + queryClient.invalidateQueries(['account', 'security-events']); + }, + }); +} +``` + +交互流程： + +1. 用户点击"这是我本人"按钮。 +2. 高风险事件触发 step-up 验证（二次验证或密码确认）。 +3. step-up 通过后展示事件摘要和确认影响。 +4. 用户确认后追加处置标记。 +5. 刷新安全事件列表和风险提示。 + +如果用户认为非本人操作，引导：修改密码 → 撤销可疑会话 → 联系客服。 + +### 3.5 购买/发布记录的分页和筛选 + +#### 3.5.1 购买记录 + +```typescript +// 购买记录查询 +export function usePurchaseRecords(params: PurchaseRecordParams) { + return useQuery({ + queryKey: ['account', 'purchases', params], + queryFn: () => fetchPurchases(params), + // GET /app-api/muse/account/purchases + // 注意：keepPreviousData 是 TanStack Query v4 写法，v5 改用 placeholderData: keepPreviousData（从 @tanstack/react-query 导入） + keepPreviousData: true, + }); +} + +interface PurchaseRecordParams { + pageNo: number; + pageSize: number; + status?: 'completed' | 'processing' | 'failed'; + assetType?: 'work' | 'agent' | 'knowledge_base'; + startTime?: string; + endTime?: string; +} +``` + +购买记录表格列： + +| 列 | 数据 | 操作 | +|---|---|---| +| 时间 | 购买时间 | - | +| 资产 | 资产名称和类型 | 跳转市场详情 | +| 来源 | 购买/免费/管理员授权 | - | +| 金额 | 金额或"免费" | - | +| 状态 | 已完成/处理中/失败 | 查看凭证 | +| 授权结果 | 是否已生成授权 | 跳转授权记录 | + +#### 3.5.2 发布记录 + +```typescript +// 发布记录查询 +export function usePublishRecords(params: PublishRecordParams) { + return useQuery({ + queryKey: ['account', 'publish-records', params], + queryFn: () => fetchPublishRecords(params), + // GET /app-api/muse/account/publish-records + // 注意：keepPreviousData 是 TanStack Query v4 写法，v5 改用 placeholderData: keepPreviousData（从 @tanstack/react-query 导入） + keepPreviousData: true, + }); +} + +interface PublishRecordParams { + pageNo: number; + pageSize: number; + assetType?: 'work' | 'agent' | 'knowledge_base'; + reviewStatus?: 'draft' | 'submitted' | 'reviewing' | 'needs_supplement' | 'approved' | 'rejected'; + marketStatus?: 'listed' | 'delisted' | 'recalled'; +} +``` + +#### 3.5.3 通用分页组件 + +所有记录页使用统一分页组件，支持： + +- 页码切换和每页条数选择 +- URL searchParams 持久化（刷新不丢失筛选） +- 加载中保留上一页数据（`keepPreviousData`） +- 空态展示和跳转入口 + +### 3.6 跳转规则 + +#### 3.6.1 从个人中心跳转到其他空间 + +个人中心是 read model 和跳转入口，所有业务处理必须跳转到对应 owner 空间。 + +| 来源页面 | 跳转目标 | 触发条件 | 携带参数 | +|---|---|---|---| +| 授权获取记录 | 市场资产详情 | 点击资产名称 | `assetId`, `returnTo` | +| 授权获取记录 | 智能体已安装页 | 点击"去安装" | `assetId`, `returnTo` | +| 授权获取记录 | 知识库已安装页 | 点击"去安装" | `assetId`, `returnTo` | +| 安装与绑定摘要 | 作品智能体关联 | 点击异常处理 | `workId`, `slotKey`, `returnTo` | +| 安装与绑定摘要 | 作品知识来源 | 点击异常处理 | `workId`, `bindingId`, `returnTo` | +| 发布记录总览 | 市场发布提交 | 点击"去补充" | `draftId`, `returnTo` | +| 发布记录总览 | 智能体发布准备 | 点击"去处理" | `agentId`, `returnTo` | +| 发布记录总览 | 知识库发布准备 | 点击"去处理" | `kbId`, `returnTo` | +| Token 与用量 | 作品记录与用量 | 点击归属作品 | `workId`, `returnTo` | +| 权益与配额 | 市场（补充权益） | 点击"补充权益" | `returnTo` | + +#### 3.6.2 返回规则 + +所有跳转携带 `returnTo` 参数，目标空间处理完成后通过该参数返回个人中心并刷新对应数据： + +```typescript +// 跳转工具函数 +function navigateToOwnerSpace(target: string, returnTo: string) { + const url = new URL(target, window.location.origin); + url.searchParams.set('returnTo', returnTo); + router.push(url.pathname + url.search); +} + +// 返回个人中心时刷新数据 +function handleReturnFromOwnerSpace() { + const returnTo = searchParams.get('returnTo'); + if (returnTo?.startsWith('/profile')) { + // 失效相关查询缓存，触发重新加载 + queryClient.invalidateQueries(['account']); + router.push(returnTo); + } +} +``` + +--- + +## 4. 状态管理策略 + +### 4.1 市场空间状态分层 + +| 状态类型 | 管理方式 | 示例 | +|---|---|---| +| 服务器数据 | TanStack Query | 资产列表、详情、授权状态、治理结果 | +| 搜索/筛选状态 | URL searchParams | 搜索词、分类、排序、分页 | +| UI 临时态 | React useState | 弹窗开关、表单编辑中、loading | +| 跨页面共享 | Zustand store | 当前 handoff session、返回点 | + +### 4.2 个人中心状态分层 + +| 状态类型 | 管理方式 | 示例 | +|---|---|---| +| 服务器数据 | TanStack Query | 权益、用量、记录列表、安全事件 | +| 筛选/分页 | URL searchParams | 时间范围、状态筛选、页码 | +| 表单状态 | React Hook Form | 个人资料编辑、偏好设置 | +| step-up 状态 | Zustand store | 二次验证流程状态 | + +### 4.3 缓存失效策略 + +```typescript +// 市场操作后的缓存失效 +const marketplaceMutationConfig = { + // 购买成功后失效资产详情和授权记录 + onPurchaseSuccess: () => { + queryClient.invalidateQueries(['marketplace', 'asset']); + queryClient.invalidateQueries(['account', 'licenses']); + queryClient.invalidateQueries(['me']); // 权益可能变化 + }, + // 安装成功后失效安装状态 + onInstallSuccess: () => { + queryClient.invalidateQueries(['marketplace', 'asset']); + queryClient.invalidateQueries(['account', 'installations']); + }, + // 发布提交后失效发布记录 + onPublishSuccess: () => { + queryClient.invalidateQueries(['account', 'publish-records']); + queryClient.invalidateQueries(['marketplace', 'my-publish-records']); + }, +}; +``` + +--- + +## 5. 管理端市场治理（muse-admin） + +管理端市场治理页面在 `muse-admin/` 中实现，使用 Vben Admin 框架，调用 `/admin-api/**`。 + +### 5.1 管理端市场页面 + +| 页面 | API | 说明 | +|---|---|---| +| 市场资产列表 | `GET /admin-api/muse/market/assets` | 查看所有市场资产和治理摘要 | +| 发布申请审核 | `GET /admin-api/muse/market/publish-requests` | 审核发布申请 | +| 审核通过/拒绝 | `POST /admin-api/muse/market/publish-requests/{id}/approve` | 审核决策 | +| 资产下架 | `POST /admin-api/muse/market/assets/{id}/delist` | 下架资产 | +| 资产召回 | `POST /admin-api/muse/market/assets/{id}/recall` | 召回资产 | +| 申诉处理 | `GET /admin-api/muse/market/appeals` | 查看和处理申诉 | + +管理端不承载普通用户的市场发现、购买、安装或绑定流程。 + +--- + +## 6. 关联阅读 + +| 文档 | 关联内容 | +|---|---| +| `产品-02F-市场功能规格.md` | 市场产品定义、页面规格、操作规格、跨空间跳转 | +| `产品-02G-个人中心功能规格.md` | 个人中心产品定义、页面规格、权限和安全规则 | +| `后端-05-统一API契约-v1.md` | 所有 API 路径、请求响应格式、错误码定义 | +| `架构-01-系统全貌与边界上下文.md` | Handoff 机制、BC 边界、Source/Authorization 横切契约 | +| `前端-01-工程结构与核心依赖.md` | 工程结构、路由约定、状态分层、接口边界 | +| `前端-02-写作台与候选交互.md` | 写作台交互模式参考 | +| `前端-03-元引擎与动态表单.md` | MetaSchema 消费和动态表单渲染 | +| `架构-04-状态机与约束清单.md` | 资产状态机、授权状态机 | + diff --git a/design-docs/前端-05-智能体与知识库工作台交互.md b/design-docs/前端-05-智能体与知识库工作台交互.md new file mode 100644 index 00000000..adfbaa48 --- /dev/null +++ b/design-docs/前端-05-智能体与知识库工作台交互.md @@ -0,0 +1,1024 @@ +# 前端-05：智能体与知识库工作台交互 + +- 版本：v1 +- 更新日期：2026-05-24 +- 目标读者：前端开发者 +- 归属仓库：muse-studio（用户端） +- 阅读时间：45-65 分钟 +- 边界说明：本文件定义智能体工作台和知识库工作台在 `muse-studio` 中的页面结构、组件交互、状态管理和 API 调用。产品功能规格见 `产品-02D/02E`，API 契约见 `后端-05`，工程结构见 `前端-01`，动态表单见 `前端-03`。 + +## 1. 总体定位 + +智能体工作台和知识库工作台是 `muse-studio` 的两个顶级产品空间，与用户工作区、市场、个人中心平级。 + +核心原则： + +1. 普通作者不需要先配置智能体或创建知识库即可完成 no-config 创作主路径。 +2. 两个工作台只调用 `/app-api/**`，不调用管理后台接口。 +3. 前端只展示后端返回的状态和可用动作，不自行推断授权、处理状态或兼容性。 +4. 跨空间跳转必须基于服务端 handoff token/session，不能用 URL 参数直接执行高影响动作。 +5. 所有高影响操作（绑定、替换、发布、停用）必须消费服务端预检快照，过期时禁用确认。 + +## 2. 路由结构 + +```text +muse-studio/ + app/ + (user)/ + agents/ # 智能体工作台入口 + page.tsx # agent-list 智能体列表 + create/page.tsx # agent-create-entry 新建入口 + [agentId]/ + page.tsx # agent-detail-version 详情与版本 + edit/page.tsx # agent-config-editor 配置型编辑器 + workflow/page.tsx # agent-workflow-editor 工作流编辑器 + test/page.tsx # agent-test-bench 试用与评估 + slots/page.tsx # agent-slot-compatibility 槽位兼容性 + publish/page.tsx # agent-publish-prep 发布准备 + records/page.tsx # agent-records-usage 运行与用量 + installed/page.tsx # agent-installed-library 已安装与授权 + slot-selector/page.tsx # agent-work-slot-selector 作品槽位候选选择 + knowledge-bases/ # 知识库工作台入口 + page.tsx # knowledge-list 知识库列表 + create/page.tsx # knowledge-create-entry 新建入口 + [kbId]/ + page.tsx # knowledge-detail-version 详情与版本 + materials/page.tsx # knowledge-material-manager 资料管理 + processing/page.tsx # knowledge-processing-status 处理状态 + bind/page.tsx # knowledge-work-bind-selector 作品绑定选择 + publish/page.tsx # knowledge-publish-prep 发布准备 + records/page.tsx # knowledge-records-usage 使用记录 + installed/page.tsx # knowledge-installed-library 已安装与授权 + global/page.tsx # global-knowledge-view 全局知识库视图 +``` + +## 3. 状态管理策略 + +### 3.1 分层原则 + +| 状态类型 | 技术选型 | 适用场景 | +|---|---|---| +| 服务器事实 | TanStack Query | 列表、详情、版本、授权、处理状态等后端数据 | +| 表单状态 | React Hook Form + Zod | 创建向导、配置编辑器、发布材料表单 | +| UI 临时态 | Zustand / component state | 筛选条件、页签、滚动位置、弹窗开关 | +| 跨页面上下文 | Zustand store | handoff session、预检快照、返回点 | + +### 3.2 缓存与失效 + +- 列表页使用 `staleTime: 30s`，返回时自动 refetch。 +- 详情页使用 `staleTime: 0`，每次进入重新拉取。 +- 高影响操作（绑定、替换、停用）成功后，invalidate 相关 query key。 +- handoff session 和预检快照存入 Zustand，页面卸载或过期时清除。 +- 轮询场景（处理状态、试用运行）使用 TanStack Query 的 `refetchInterval`，任务终态后停止。 + +### 3.3 乐观更新与回滚 + +- 列表筛选、排序使用乐观 UI，失败时回滚。 +- 高影响命令（绑定、替换、发布提交）不做乐观更新，等待服务端确认后刷新。 +- 表单保存使用 debounce 自动保存 + 手动保存按钮，冲突时展示本地未保存提示。 + +## 4. 通用错误处理 + +| 错误码 | 前端处理 | +|---|---| +| `UNAUTHENTICATED` | 跳转登录页 | +| `FORBIDDEN` | 展示无权限说明，禁用操作按钮 | +| `RESOURCE_NOT_FOUND` | 返回列表页 | +| `STATE_CONFLICT` | 刷新对象状态和可用动作 | +| `SOURCE_NEEDS_RECHECK` | 展示来源重验入口 | +| `SOURCE_BLOCKED` | 禁用确认/绑定/生成，展示原因归因 | +| `PRECHECK_EXPIRED` | 清除本地预检快照，引导重新预检 | +| `PRECHECK_REQUIRED` | 返回来源空间刷新预检 | +| `REVISION_CONFLICT` | 拉取最新数据，展示冲突提示 | +| `FEATURE_DISABLED` | 隐藏或禁用对应入口 | + +所有错误展示使用产品语言，不暴露技术术语（如 handoff session、precheckId）。 + +--- + +# 第一部分：智能体工作台 + +## 5. 智能体列表（agent-list） + +### 5.1 页面结构 + +```text +┌─────────────────────────────────────────────────┐ +│ 顶部：新建智能体按钮（按权限显示） │ +├─────────────────────────────────────────────────┤ +│ 页签：我创建的 | 已安装 | 系统默认 │ +├─────────────────────────────────────────────────┤ +│ 搜索筛选栏：关键词、来源、形态、能力目标、状态 │ +├─────────────────────────────────────────────────┤ +│ 授权异常提示条（有异常时显示） │ +├─────────────────────────────────────────────────┤ +│ 智能体卡片列表（分页） │ +│ - 名称、类型、能力目标、版本、状态 │ +│ - 可编辑性、兼容槽位摘要、最近使用 │ +│ - 授权状态标记 │ +└─────────────────────────────────────────────────┘ +``` + +### 5.2 API 调用 + +| 时机 | API 路径 | 说明 | +|---|---|---| +| 页面加载 | `GET /app-api/muse/agents` | 智能体列表，带筛选和分页 | +| 页签切换 | `GET /app-api/muse/agents` | 切换 source 参数 | +| 授权异常 | 列表响应中的 `authorizationAlerts` 字段 | 展示异常数量和处理入口 | + +### 5.3 交互规则 + +- 新建按钮：无创建权限时隐藏；有权限时跳转 `agent-create-entry`。 +- 卡片点击：跳转 `agent-detail-version`。 +- 筛选保持：从详情返回时恢复筛选条件和滚动位置（Zustand 持久化）。 +- 空态：无智能体时展示系统默认能力摘要和"去市场安装"入口。 +- 加载失败：保留旧列表数据，展示刷新时间和重试按钮。 + +### 5.4 跳转关系 + +- → `agent-create-entry`：新建 +- → `agent-detail-version`：卡片点击 +- → `agent-installed-library`：已安装页签 +- ← 作品智能体关联页：完成槽位替换后返回 + +## 6. 新建智能体入口（agent-create-entry） + +### 6.1 页面结构 + +```text +┌─────────────────────────────────────────────────┐ +│ 形态选择：配置型 | 工作流型（按权限灰度） │ +├─────────────────────────────────────────────────┤ +│ 能力目标选择：写作 | 分析 | 检测 │ +├─────────────────────────────────────────────────┤ +│ 模板选择（可选） │ +├─────────────────────────────────────────────────┤ +│ 创建限制提示（配额不足、工作流未开放） │ +├─────────────────────────────────────────────────┤ +│ 创建按钮 / 返回列表 │ +└─────────────────────────────────────────────────┘ +``` + +### 6.2 API 调用 + +| 时机 | API 路径 | 说明 | +|---|---|---| +| 页面加载 | `GET /app-api/muse/agents/create-options` | 查询可创建形态、模板、配额 | +| 创建 | `POST /app-api/muse/agents` | 创建草稿，带幂等键 | + +### 6.3 交互规则 + +- 工作流型未开放时：选项置灰，展示"需要高级权限"说明。 +- 配额不足：禁用创建按钮，展示个人中心权益入口。 +- 创建成功：跳转对应编辑器（配置型 → `agent-config-editor`，工作流型 → `agent-workflow-editor`）。 +- 创建失败：不生成草稿，保留用户选择，允许重试。 + +## 7. 配置型智能体编辑器（agent-config-editor） + +### 7.1 页面结构 + +```text +┌─────────────────────────────────────────────────┐ +│ 顶部：智能体名称 / 保存状态 / 操作按钮 │ +├──────────────────────┬──────────────────────────┤ +│ 左侧编辑区 │ 右侧预览/校验区 │ +│ - 基础信息 │ - 输出合同预览 │ +│ - 能力目标 │ - 兼容槽位摘要 │ +│ - Prompt 模板编辑 │ - 校验结果 │ +│ - 变量说明 │ - 敏感信息提示 │ +│ - 模型档位选择 │ │ +│ - 参数配置 │ │ +│ - 上下文策略 │ │ +├──────────────────────┴──────────────────────────┤ +│ 底部：保存草稿 | 校验 | 试用 | 启用版本 │ +└─────────────────────────────────────────────────┘ +``` + +### 7.2 API 调用 + +| 时机 | API 路径 | 说明 | +|---|---|---| +| 页面加载 | `GET /app-api/muse/agents/{agentId}` | 加载草稿详情 | +| 模型选项 | 详情响应中的模型绑定选项 | 平台开放模型档位 | +| 保存草稿 | `POST /app-api/muse/agents/{agentId}/versions/draft` | 带幂等键 | +| 校验 | `POST /app-api/muse/agents/{agentId}/versions/{versionId}/validate` | 返回 validationId | +| 启用版本 | `POST /app-api/muse/agents/{agentId}/versions/{versionId}/activate` | 消费 validationId | + +### 7.3 状态管理 + +- 表单状态：React Hook Form 管理 Prompt、参数、上下文策略。 +- 自动保存：debounce 3s 后自动调用保存草稿，展示"已保存"/"未保存"状态。 +- 校验快照：校验成功后将 `validationId` 存入组件 state，过期时清除并要求重新校验。 +- 启用前置：启用按钮仅在 `validationId` 有效时可点击。 + +### 7.4 错误处理 + +- 保存失败：保留本地未保存提示，允许重试。 +- 校验失败：定位到具体字段，展示输出不合约、Prompt 注入风险等原因。 +- 启用失败：不改变当前版本，展示影响范围和失败原因。 +- 敏感信息命中：阻断保存或强提示，要求用户移除。 + +## 8. 工作流型智能体编辑器（agent-workflow-editor） + +### 8.1 页面结构 + +```text +┌─────────────────────────────────────────────────┐ +│ 顶部：名称 / 保存状态 / 操作按钮 │ +├──────────────────────┬──────────────────────────┤ +│ 左侧工具面板 │ 中央画布 │ +│ - 可用工具列表 │ - 步骤节点（拖拽） │ +│ - 可用子智能体 │ - 连线（输入输出映射） │ +│ - 步骤模板 │ - 条件分支节点 │ +│ │ - 循环节点 │ +│ │ - 错误处理节点 │ +├──────────────────────┼──────────────────────────┤ +│ 右侧属性面板 │ │ +│ - 步骤配置 │ │ +│ - 输入来源 │ │ +│ - 输出去向 │ │ +│ - 超时/失败策略 │ │ +│ - 外发范围说明 │ │ +├──────────────────────┴──────────────────────────┤ +│ 底部：保存 | 校验 | 试用 | 启用版本 │ +└─────────────────────────────────────────────────┘ +``` + +### 8.2 API 调用 + +| 时机 | API 路径 | 说明 | +|---|---|---| +| 工具目录 | `GET /app-api/muse/agents/{agentId}/tools` | 授权工具列表 | +| 子智能体 | 详情响应中的可用子智能体选项 | 可组合子能力 | +| 保存 | `POST /app-api/muse/agents/{agentId}/versions/workflow-draft` | 步骤和工具配置 | +| 校验 | `POST /app-api/muse/agents/{agentId}/versions/{versionId}/validate` | 工作流校验 | + +### 8.3 交互规则 + +- 节点拖拽：从左侧工具面板拖入画布创建步骤节点。 +- 连线：从节点输出端口拖到另一节点输入端口建立数据流。 +- 条件分支：双击条件节点配置分支条件。 +- 循环：支持 for-each 和 while 两种循环模式，必须有终止条件。 +- 工具无权：工具列表中未授权工具置灰，展示"需要授权"说明。 +- 外发提示：使用外发工具时，右侧面板展示外发范围和确认要求。 +- 校验失败：画布中高亮错误节点，右侧展示具体原因（循环无终止、输出不合约等）。 + +## 9. 智能体试用与评估（agent-test-bench） + +### 9.1 页面结构 + +```text +┌─────────────────────────────────────────────────┐ +│ 左侧：测试上下文选择 │ +│ - 手动输入片段 │ +│ - 作品样例选择（有权作品） │ +│ - 授权知识摘要 │ +│ - 模型档位和 Token 预估 │ +├─────────────────────────────────────────────────┤ +│ 中央：运行控制 │ +│ - 运行按钮 / 停止按钮 │ +│ - 外发范围提示 │ +│ - 用量预估 │ +├─────────────────────────────────────────────────┤ +│ 右侧：输出结果 │ +│ - 任务状态（排队/运行中/成功/失败/超时） │ +│ - 输出文本 │ +│ - 质量评分和风险标记 │ +│ - 失败原因（权限/授权/合同/超时） │ +│ - 保存为样例按钮 │ +└─────────────────────────────────────────────────┘ +``` + +### 9.2 API 调用 + +| 时机 | API 路径 | 说明 | +|---|---|---| +| 上下文选项 | `GET /app-api/muse/agents/{agentId}/test-context` | 可用样例和输入选项 | +| 运行试用 | `POST /app-api/muse/agents/{agentId}/test` | 返回 testRunId | +| 轮询结果 | `GET /app-api/muse/jobs/{jobId}` | 轮询任务状态 | +| 取消 | `POST /app-api/muse/jobs/{jobId}/cancel` | 取消运行中任务 | + +### 9.3 状态管理 + +- 运行状态：使用 TanStack Query 的 `refetchInterval: 2000` 轮询，终态后停止。 +- 输出展示：成功时渲染输出文本和质量评分；失败时展示分类原因。 +- 用量提示：运行前展示预估 Token 消耗；运行后展示实际用量。 + +### 9.4 关键约束 + +- 试用输出没有候选 ID，不能被作品候选接受/合并接口消费。 +- 使用作品样例时必须提示"不会写作品事实，但会产生模型调用和用量"。 +- 市场智能体按许可和信任合同决定是否允许试用。 + +## 10. 可替换槽位与兼容性（agent-slot-compatibility） + +### 10.1 页面结构 + +```text +┌─────────────────────────────────────────────────┐ +│ 筛选：能力目标、槽位状态 │ +├─────────────────────────────────────────────────┤ +│ 槽位列表 │ +│ - 槽位名称、能力目标 │ +│ - 允许输入/输出摘要 │ +│ - 兼容状态标记（兼容/部分兼容/阻断） │ +│ - 保护节点说明（只读） │ +├─────────────────────────────────────────────────┤ +│ 槽位合同详情抽屉 │ +│ - 允许输入类型 │ +│ - 允许输出类型 │ +│ - 允许工具 │ +│ - 失败策略 │ +│ - 不兼容原因（如有） │ +└─────────────────────────────────────────────────┘ +``` + +### 10.2 API 调用 + +| 时机 | API 路径 | 说明 | +|---|---|---| +| 页面加载 | `GET /app-api/muse/agents/{agentId}/slot-compatibility` | 兼容槽位列表 | +| 合同详情 | 详情响应中的槽位合同字段 | 展示合同摘要 | + +### 10.3 交互规则 + +- 该页面只读，无写操作。 +- 阻断状态：展示具体不兼容原因，引导跳转编辑器修正。 +- 保护节点：只展示说明文字，不提供修改入口。 + +## 11. 作品槽位候选选择与替换（agent-work-slot-selector） + +### 11.1 页面结构 + +```text +┌─────────────────────────────────────────────────┐ +│ 顶部：作品名 / 槽位名 / 跳转授权状态 / 过期 │ +├─────────────────────────────────────────────────┤ +│ 当前绑定：当前智能体名称和版本 │ +├─────────────────────────────────────────────────┤ +│ 候选列表 │ +│ - 智能体名称、版本、兼容性 │ +│ - 授权状态、来源 │ +│ - 试用入口 │ +├─────────────────────────────────────────────────┤ +│ 预检结果区 │ +│ - 兼容性结论 │ +│ - 阻断原因 │ +│ - 回退策略 │ +├─────────────────────────────────────────────────┤ +│ 操作区：确认替换 | 回退系统默认 | 返回作品 │ +└─────────────────────────────────────────────────┘ +``` + +### 11.2 API 调用 + +| 时机 | API 路径 | 说明 | +|---|---|---| +| 落地 | `POST /app-api/muse/works/{workId}/agent-slots/{slotKey}/prechecks` | 消费 handoff token，获取 session | +| 候选列表 | `GET /app-api/muse/works/{workId}/agent-slots` | 兼容智能体列表 | +| 预检 | `POST /app-api/muse/works/{workId}/agent-slots/{slotKey}/prechecks` | 返回 precheckId | +| 确认替换 | `POST /app-api/muse/works/{workId}/agent-slots/{slotKey}/bind` | 消费 session + precheckId | +| 回退默认 | `POST /app-api/muse/works/{workId}/agent-slots/{slotKey}/reset` | 清除作品级替换 | + +### 11.3 Handoff 流程 + +1. 从作品智能体关联页跳转时，URL 携带 `handoffToken` 参数。 +2. 页面加载时立即调用 handoff 消费接口，将 token 交换为 session。 +3. session 存入 Zustand store，后续预检和确认都基于该 session。 +4. session 过期时：禁用确认按钮，展示"授权已过期，请返回作品重新发起"。 +5. 浏览器后退/重复加载：返回同一 session 状态，不扩大动作范围。 + +### 11.4 错误处理 + +- handoff token 过期：展示过期提示，只提供"返回作品"按钮。 +- 预检失败：展示具体原因（输出不合约、授权失效），禁用确认。 +- 替换失败：保持原绑定，展示"事实未改变"和失败原因。 + +## 12. 已安装智能体与授权（agent-installed-library） + +### 12.1 页面结构 + +```text +┌─────────────────────────────────────────────────┐ +│ 页签：可安装 | 已安装 │ +├─────────────────────────────────────────────────┤ +│ 智能体列表 │ +│ - 名称、发布者、许可摘要 │ +│ - 版本、安装状态、到期时间 │ +│ - 可升级标记、下架标记 │ +├─────────────────────────────────────────────────┤ +│ 操作：安装 | 停用 | 升级 | 固定版本 │ +├─────────────────────────────────────────────────┤ +│ 异常提示（授权失效、已下架） │ +└─────────────────────────────────────────────────┘ +``` + +### 12.2 API 调用 + +| 时机 | API 路径 | 说明 | +|---|---|---| +| 可安装列表 | `GET /app-api/muse/marketplace/assets?assetType=agent` | 已授权未安装 | +| 已安装列表 | `GET /app-api/muse/agents/installed` | 已安装智能体 | +| 安装 | `POST /app-api/muse/marketplace/assets/{assetId}/install` | 带许可确认 | +| 停用 | `POST /app-api/muse/agents/{agentId}/installed/disable` | 展示影响作品 | +| 升级 | `POST /app-api/muse/agents/{agentId}/installed/upgrade` | 展示变更和影响 | + +### 12.3 交互规则 + +- 安装前：展示许可、版本、风险等级、可读上下文、工具和外发范围。 +- 停用确认：二次确认弹窗，展示影响哪些作品槽位。 +- 升级确认：展示变更说明和影响作品，已固定绑定不静默变化。 +- 授权失效：保留只读摘要，禁用新增绑定，展示处理路径。 + +## 13. 智能体发布准备（agent-publish-prep） + +### 13.1 页面结构 + +```text +┌─────────────────────────────────────────────────┐ +│ 待提交版本选择 │ +├─────────────────────────────────────────────────┤ +│ 商品信息表单 │ +│ - 名称、描述、封面/图标 │ +│ - 能力目标、许可范围 │ +│ - 禁止用途、是否可复制 │ +├─────────────────────────────────────────────────┤ +│ 权利声明 │ +├─────────────────────────────────────────────────┤ +│ 安全检查结果 │ +│ - Prompt 注入检查 │ +│ - 敏感信息检查 │ +│ - 兼容槽位摘要 │ +├─────────────────────────────────────────────────┤ +│ 操作：保存草稿 | 运行检查 | 提交审核 | 撤回 │ +└─────────────────────────────────────────────────┘ +``` + +### 13.2 API 调用 + +| 时机 | API 路径 | 说明 | +|---|---|---| +| 加载状态 | `GET /app-api/muse/agents/{agentId}/publish-status` | 发布准备状态 | +| 保存草稿 | `POST /app-api/muse/marketplace/publish-drafts` | 保存发布材料 | +| 运行检查 | `POST /app-api/muse/marketplace/publish-drafts/{draftId}/checks` | 返回 publishCheckId | +| 提交审核 | `POST /app-api/muse/marketplace/publish-requests` | 消费 publishCheckId | +| 撤回 | `POST /app-api/muse/marketplace/publish-requests/{requestId}/withdraw` | 撤回申请 | + +### 13.3 交互规则 + +- 提交按钮：仅在检查通过且 `publishCheckId` 未过期时可点击。 +- 检查失败：展示阻断项（权利不清、安全阻断），禁用提交。 +- 提交成功：返回详情页，展示"审核中"状态。 +- 重复提交：幂等返回当前申请状态。 + +## 14. 智能体运行与用量记录（agent-records-usage） + +### 14.1 页面结构 + +```text +┌─────────────────────────────────────────────────┐ +│ 筛选：时间范围、来源类型、状态、失败类型 │ +├─────────────────────────────────────────────────┤ +│ 运行记录列表 │ +│ - 时间、来源（试用/作品调用） │ +│ - 槽位、版本、状态 │ +│ - Token 摘要、失败原因 │ +├─────────────────────────────────────────────────┤ +│ 用量摘要卡片 │ +│ - 总调用次数、成功率 │ +│ - Token 消耗、待归属 │ +├─────────────────────────────────────────────────┤ +│ 详情抽屉（点击记录展开） │ +│ - 脱敏输入输出摘要 │ +│ - 授权快照摘要 │ +│ - 失败详情和可行动建议 │ +└─────────────────────────────────────────────────┘ +``` + +### 14.2 API 调用 + +| 时机 | API 路径 | 说明 | +|---|---|---| +| 记录列表 | `GET /app-api/muse/agents/{agentId}/run-records` | 带筛选和分页 | +| 用量摘要 | `GET /app-api/muse/account/usage?dimension=agent` | Token 和调用摘要 | +| 失败原因 | 记录详情中的失败字段 | 分类和建议 | + +### 14.3 权限规则 + +- 使用者：可看自己的作品调用详情。 +- 发布者：只能看达到最小样本阈值的脱敏聚合，不能看单次运行详情。 + +--- + +# 第二部分：知识库工作台 + +## 15. 知识库列表（knowledge-list） + +### 15.1 页面结构 + +```text +┌─────────────────────────────────────────────────┐ +│ 顶部摘要：可用总数 / 我创建 / 已安装 / 全局 │ +│ 新建知识库按钮（按权限显示） │ +├─────────────────────────────────────────────────┤ +│ 页签：我创建的 | 已安装 | 全局授权 │ +├─────────────────────────────────────────────────┤ +│ 搜索筛选栏：关键词、来源、类型、处理状态、授权 │ +├─────────────────────────────────────────────────┤ +│ 授权异常提示条 / 处理失败提示条 │ +├─────────────────────────────────────────────────┤ +│ 知识库卡片列表（分页） │ +│ - 名称、来源类型、所有权 │ +│ - 版本、处理状态、授权状态 │ +│ - 可编辑性、可绑定作品数、最近命中 │ +│ - 风险摘要 │ +└─────────────────────────────────────────────────┘ +``` + +### 15.2 API 调用 + +| 时机 | API 路径 | 说明 | +|---|---|---| +| 页面加载 | `GET /app-api/muse/knowledge-bases` | 知识库列表，带筛选和分页 | +| 已安装 | `GET /app-api/muse/installed-knowledge-bases` | 已安装知识库 | +| 授权异常 | 列表响应中的 `authorizationAlerts` 字段 | 异常数量和处理入口 | + +### 15.3 交互规则 + +- 卡片必须让用户一眼区分"我创建 / 已安装 / 全局授权 / 账户可用"。 +- 处理状态使用用户语言展示（"处理中""可检索""可生成"），不暴露 worker 或 Pipeline。 +- 筛选保持：从详情返回时恢复筛选条件和滚动位置。 +- 空态：无知识库时展示全局授权摘要和"创建知识库"/"去市场"入口。 +- 普通作者：新建入口可按权限折叠，不强制展示。 + +### 15.4 跳转关系 + +- → `knowledge-create-entry`：新建 +- → `knowledge-detail-version`：卡片点击 +- → `knowledge-installed-library`：已安装页签 +- → `global-knowledge-view`：全局页签 +- ← 作品知识来源页：完成绑定后返回 + +## 16. 新建知识库入口（knowledge-create-entry） + +### 16.1 页面结构 + +```text +┌─────────────────────────────────────────────────┐ +│ 类型选择：空白创建 | 文件导入 | 模板创建 │ +├─────────────────────────────────────────────────┤ +│ 用途选择（可选） │ +├─────────────────────────────────────────────────┤ +│ 模板预览（选择模板时展示） │ +├─────────────────────────────────────────────────┤ +│ 导入限制说明（文件类型、大小、数量） │ +├─────────────────────────────────────────────────┤ +│ 创建配额提示 │ +├─────────────────────────────────────────────────┤ +│ 创建按钮 / 返回列表 │ +└─────────────────────────────────────────────────┘ +``` + +### 16.2 API 调用 + +| 时机 | API 路径 | 说明 | +|---|---|---| +| 页面加载 | `GET /app-api/muse/knowledge-bases/create-options` | 可创建类型、模板、配额 | +| 创建 | `POST /app-api/muse/knowledge-bases` | 创建草稿，带幂等键 | + +### 16.3 交互规则 + +- 页面让用户理解知识库是可复用资料资产，不是作品正式知识，也不是写作前置条件。 +- 全局知识库创建入口只显示"去管理员控制台"（普通用户不可见）。 +- 创建成功：跳转 `knowledge-material-manager` 进入资料管理。 +- 配额不足：禁用创建，展示个人中心权益入口。 + +## 17. 知识库详情与版本（knowledge-detail-version） + +### 17.1 页面结构 + +```text +┌─────────────────────────────────────────────────┐ +│ 顶部摘要 │ +│ - 名称、来源、所有权、版本 │ +│ - 处理状态、授权状态、发布状态 │ +│ - 风险摘要 │ +├─────────────────────────────────────────────────┤ +│ Tab：资料概览 | 版本历史 | 绑定作品 | 使用摘要 │ +├─────────────────────────────────────────────────┤ +│ 资料概览 Tab │ +│ - 资料数量、处理状态分布 │ +│ - 进入资料管理入口 │ +├─────────────────────────────────────────────────┤ +│ 版本历史 Tab │ +│ - 版本列表、变更摘要、回退限制 │ +│ - 影响作品数量 │ +├─────────────────────────────────────────────────┤ +│ 操作区 │ +│ - 编辑资料 | 绑定作品 | 发布准备 │ +│ - 复制为个人副本 | 导出 │ +│ - 停用 | 重新启用 | 删除（危险操作） │ +└─────────────────────────────────────────────────┘ +``` + +### 17.2 API 调用 + +| 时机 | API 路径 | 说明 | +|---|---|---| +| 详情加载 | `GET /app-api/muse/knowledge-bases/{kbId}` | 基础信息、版本、处理状态 | +| 版本历史 | 详情响应中的版本列表 | 版本和变更摘要 | +| 影响范围 | 详情响应中的绑定摘要 | 绑定作品数、安装影响 | +| 停用 | `POST /app-api/muse/knowledge-bases/{kbId}/disable` | 带 commandId | +| 删除 | `DELETE /app-api/muse/knowledge-bases/{kbId}` | 带 commandId | +| 恢复 | `POST /app-api/muse/knowledge-bases/{kbId}/restore` | 可取消期内 | +| 导出预检 | `POST /app-api/muse/knowledge-bases/{kbId}/export-tasks/precheck` | 返回导出范围 | +| 导出 | `POST /app-api/muse/knowledge-bases/{kbId}/export-tasks` | 创建导出任务 | + +### 17.3 交互规则 + +- 市场安装知识库：默认只读，不展示不可见资料全文。 +- 停用/删除：二次确认弹窗，展示影响作品、绑定、运行任务和后续生成。 +- 版本回退：展示影响范围，已固定绑定不静默变化。 +- 导出：展示导出范围、脱敏要求和下载有效期。 + +## 18. 资料管理与导入（knowledge-material-manager） + +### 18.1 页面结构 + +```text +┌─────────────────────────────────────────────────┐ +│ 上传区（拖拽上传） │ +│ - 支持格式说明 │ +│ - 上传进度条 │ +│ - 文件大小限制提示 │ +├─────────────────────────────────────────────────┤ +│ 手写条目编辑入口 │ +├─────────────────────────────────────────────────┤ +│ 资料列表 │ +│ - 文件名、类型、大小、来源 │ +│ - 扫描状态、处理状态 │ +│ - 可检索/可生成标记 │ +│ - 失败原因（如有） │ +├─────────────────────────────────────────────────┤ +│ 处理操作栏 │ +│ - 运行处理检查 | 发起处理 │ +│ - 处理状态入口 │ +├─────────────────────────────────────────────────┤ +│ 风险提示（隔离资料、扫描阻断） │ +└─────────────────────────────────────────────────┘ +``` + +### 18.2 API 调用 + +| 时机 | API 路径 | 说明 | +|---|---|---| +| 资料列表 | `GET /app-api/muse/knowledge-bases/{kbId}/documents` | 资料和处理状态 | +| 上传 | `POST /app-api/muse/knowledge-bases/{kbId}/documents` | 返回 documentId 和处理任务 | +| 删除资料 | `DELETE /app-api/muse/knowledge-bases/{kbId}/documents/{documentId}` | 带影响确认 | +| 处理状态 | `GET /app-api/muse/knowledge-bases/{kbId}/processing-tasks/{taskId}` | 轮询处理进度 | +| 重建索引 | `POST /app-api/muse/knowledge-bases/{kbId}/reindex` | 返回任务 | + +### 18.3 上传交互 + +1. 拖拽或点击选择文件。 +2. 前端校验文件类型和大小（MIME 白名单、最大单文件大小）。 +3. 上传中展示进度条。 +4. 上传完成后资料进入"待扫描"状态。 +5. 扫描通过后进入"待处理"状态。 +6. 扫描隔离：展示隔离原因，禁用处理和下载。 + +### 18.4 处理状态轮询 + +- 资料上传后自动开始轮询处理状态（`refetchInterval: 5000`）。 +- 状态流转：待扫描 → 扫描中 → 待处理 → 处理中 → 可检索/可生成。 +- 失败时停止轮询，展示失败原因和重试入口。 +- 所有状态使用用户语言展示，不暴露 worker 或底层日志。 + +## 19. 处理状态与失败恢复（knowledge-processing-status） + +### 19.1 页面结构 + +```text +┌─────────────────────────────────────────────────┐ +│ 任务时间线 │ +│ - 排队 → 扫描 → 清洗 → 解析 → 索引 → 完成 │ +│ - 当前阶段高亮 │ +│ - 失败阶段标红 │ +├─────────────────────────────────────────────────┤ +│ 资料分组 │ +│ - 成功资料数量 │ +│ - 失败资料列表 │ +│ - 失败原因和可行动建议 │ +├─────────────────────────────────────────────────┤ +│ 操作区 │ +│ - 重试失败任务 │ +│ - 取消可取消任务 │ +│ - 跳转资料管理 │ +└─────────────────────────────────────────────────┘ +``` + +### 19.2 API 调用 + +| 时机 | API 路径 | 说明 | +|---|---|---| +| 任务列表 | `GET /app-api/muse/knowledge-bases/{kbId}/processing-tasks/{taskId}` | 处理任务状态 | +| 重试 | `POST /app-api/muse/knowledge-bases/{kbId}/reindex` | 重试失败资料 | +| 取消 | `POST /app-api/muse/jobs/{jobId}/cancel` | 取消可取消任务 | + +### 19.3 交互规则 + +- 处理阶段用用户语言表达，不暴露 worker、Pipeline、向量库或底层日志。 +- 失败原因要可行动：例如"删除隔离资料""重新上传""稍后重试"。 +- 取消处理：展示当前知识库是否仍可用于已有绑定。 +- 轮询：处理中状态使用 `refetchInterval: 3000`，终态后停止。 + +## 20. 已安装知识库与授权（knowledge-installed-library） + +### 20.1 页面结构 + +```text +┌─────────────────────────────────────────────────┐ +│ 页签：可安装 | 已安装 │ +├─────────────────────────────────────────────────┤ +│ 知识库列表 │ +│ - 名称、发布者、许可摘要 │ +│ - 版本、安装状态、到期时间 │ +│ - 处理状态、可用于检索/生成 │ +│ - 下架标记、可升级标记 │ +├─────────────────────────────────────────────────┤ +│ 操作：安装 | 停用 | 升级 | 固定版本 │ +├─────────────────────────────────────────────────┤ +│ 异常提示（授权失效、已下架、处理需重验） │ +└─────────────────────────────────────────────────┘ +``` + +### 20.2 API 调用 + +| 时机 | API 路径 | 说明 | +|---|---|---| +| 可安装 | `GET /app-api/muse/marketplace/assets?assetType=knowledge_base` | 已授权未安装 | +| 已安装 | `GET /app-api/muse/installed-knowledge-bases` | 已安装知识库 | +| 安装 | `POST /app-api/muse/marketplace/assets/{assetId}/install` | 带许可确认 | +| 停用 | `POST /app-api/muse/installed-knowledge-bases/{installId}/disable` | 展示影响 | +| 升级 | 版本升级接口 | 展示变更和影响 | + +### 20.3 交互规则 + +- 安装不自动绑定作品；升级不静默改变已固定版本的作品绑定。 +- 安装前展示许可、版本、可读范围、可检索/可生成、外发范围。 +- 停用确认：展示影响哪些作品绑定和是否需要降权或解绑。 +- 授权失效或下架：保留只读摘要，不允许新增绑定。 + +## 21. 作品绑定选择与用途（knowledge-work-bind-selector） + +### 21.1 页面结构 + +```text +┌─────────────────────────────────────────────────┐ +│ 顶部：知识库名 / 版本 / 跳转授权状态 / 过期 │ +├─────────────────────────────────────────────────┤ +│ 作品选择 │ +│ - 可绑定作品列表（有 source_manage 权限） │ +│ - 现有绑定状态 │ +├─────────────────────────────────────────────────┤ +│ 用途开关 │ +│ - 检索 | 生成 | 检查 | 导出 | 只读参考 │ +│ - 外发范围说明 │ +│ - 冲突策略 │ +├─────────────────────────────────────────────────┤ +│ 预检结果区 │ +│ - 许可范围、处理状态 │ +│ - 阻断原因 │ +│ - 过期时间 │ +├─────────────────────────────────────────────────┤ +│ 操作：确认绑定 | 解绑 | 调整用途 | 返回 │ +└─────────────────────────────────────────────────┘ +``` + +### 21.2 API 调用 + +| 时机 | API 路径 | 说明 | +|---|---|---| +| 落地 | `POST /app-api/muse/works/{workId}/knowledge-bindings/prechecks` | 消费 handoff token | +| 可绑定作品 | 预检响应中的可绑定作品 | 有 source_manage 的作品 | +| 预检 | `POST /app-api/muse/works/{workId}/knowledge-bindings/prechecks` | 返回 kbBindPrecheckId | +| 绑定 | `POST /app-api/muse/works/{workId}/knowledge-bindings` | 消费 session + precheckId | +| 解绑 | `DELETE /app-api/muse/works/{workId}/knowledge-bindings/{bindingId}` | 展示影响 | +| 调整用途 | `PATCH` 绑定用途接口 | 扩大用途需确认 | + +### 21.3 Handoff 流程 + +1. 从作品知识来源页或知识库详情跳转时，URL 携带 `handoffToken`。 +2. 页面加载时调用预检接口消费 token，获取 handoff session。 +3. session 存入 Zustand store。 +4. 选择作品和用途后执行绑定预检，获取 `kbBindPrecheckId`。 +5. 确认绑定时原子消费 session 和预检快照。 +6. 成功后返回作品知识来源页并刷新绑定。 + +### 21.4 用途开关交互 + +- 默认只开启"检索"和"只读参考"。 +- 开启"生成"或"导出"需要二次确认，展示外发范围。 +- 许可不允许的用途：开关置灰，展示"许可不允许"。 +- 扩大用途必须有有效预检，过期时禁用确认。 + +## 22. 知识库发布准备（knowledge-publish-prep） + +### 22.1 页面结构 + +```text +┌─────────────────────────────────────────────────┐ +│ 待提交版本 │ +├─────────────────────────────────────────────────┤ +│ 商品信息表单 │ +│ - 名称、描述、封面 │ +│ - 资料摘要 │ +│ - 许可范围、禁止用途 │ +│ - 是否可复制、是否可用于生成 │ +├─────────────────────────────────────────────────┤ +│ 权利声明 │ +├─────────────────────────────────────────────────┤ +│ 发布检查结果 │ +│ - 处理状态检查 │ +│ - 隐私/密钥/版权检查 │ +│ - 阻断项列表 │ +├─────────────────────────────────────────────────┤ +│ 操作：保存草稿 | 运行检查 | 提交审核 | 撤回 │ +└─────────────────────────────────────────────────┘ +``` + +### 22.2 API 调用 + +| 时机 | API 路径 | 说明 | +|---|---|---| +| 加载状态 | `GET /app-api/muse/knowledge-bases/{kbId}/publish-status` | 发布准备状态 | +| 保存草稿 | `POST /app-api/muse/marketplace/publish-drafts` | 保存发布材料 | +| 运行检查 | `POST /app-api/muse/knowledge-bases/{kbId}/publish-prechecks` | 返回 kbPublishCheckId | +| 生成快照 | `POST /app-api/muse/knowledge-bases/{kbId}/publish-snapshots` | 固化版本和来源 | +| 提交审核 | `POST /app-api/muse/knowledge-bases/{kbId}/publish-requests` | 消费检查和快照 | +| 撤回 | `POST /app-api/muse/marketplace/publish-requests/{requestId}/withdraw` | 撤回申请 | + +### 22.3 交互规则 + +- 非自有、全局、局域、市场安装资产默认不可提交。 +- 检查过期或资料变化时要求重新检查。 +- 提交成功后返回详情，展示"审核中"。 +- 页面只做发布准备和提交，不处理市场审核结论。 + +## 23. 知识库使用与命中记录（knowledge-records-usage） + +### 23.1 页面结构 + +```text +┌─────────────────────────────────────────────────┐ +│ 筛选：时间范围、作品、用途、状态 │ +├─────────────────────────────────────────────────┤ +│ 绑定列表 │ +│ - 作品名、绑定版本、用途 │ +│ - 最近命中数量 │ +│ - 授权状态 │ +├─────────────────────────────────────────────────┤ +│ 命中摘要 │ +│ - 命中章节、用途、冲突摘要 │ +├─────────────────────────────────────────────────┤ +│ 用量摘要 │ +│ - 处理用量、生成引用用量 │ +│ - 待归属、异常 │ +├─────────────────────────────────────────────────┤ +│ 失败摘要 │ +│ - 失败分类、可行动建议 │ +└─────────────────────────────────────────────────┘ +``` + +### 23.2 API 调用 + +| 时机 | API 路径 | 说明 | +|---|---|---| +| 使用记录 | `GET /app-api/muse/knowledge-bases/{kbId}/usage-records` | 绑定和命中 | +| 用量摘要 | `GET /app-api/muse/account/usage?dimension=knowledge` | 处理和生成用量 | + +### 23.3 权限规则 + +- 使用者：可看自己的作品绑定和命中。 +- 发布者：只能看达到最小样本阈值的脱敏聚合（同一时间桶不少于 10 个使用者且不少于 3 个作品来源），未达阈值隐藏或合并维度。 +- 不展示他人作品正文、检索片段或生成输入输出。 + +## 24. 全局知识库视图（global-knowledge-view） + +### 24.1 页面结构 + +```text +┌─────────────────────────────────────────────────┐ +│ 全局知识库列表 │ +│ - 名称、版本、授权范围 │ +│ - 处理状态、可绑定性 │ +│ - 管理员公告 │ +├─────────────────────────────────────────────────┤ +│ 授权摘要 │ +│ - 可检索/可生成/可导出 │ +│ - 到期时间、限制 │ +├─────────────────────────────────────────────────┤ +│ 操作：查看详情 | 按授权绑定到作品 │ +│ （管理员维护动作跳回管理员控制台） │ +└─────────────────────────────────────────────────┘ +``` + +### 24.2 API 调用 + +| 时机 | API 路径 | 说明 | +|---|---|---| +| 列表 | `GET /app-api/muse/knowledge-bases?scope=global` | 全局知识库可见列表 | +| 详情 | `GET /app-api/muse/knowledge-bases/{kbId}` | 全局知识库详情 | + +### 24.3 交互规则 + +- 普通用户只读；创建、导入、维护、停用和授权策略回到管理员控制台。 +- 按授权绑定：跳转 `knowledge-work-bind-selector`，走标准绑定流程。 +- 授权不可用时：展示原因，禁用绑定入口。 + +--- + +# 第三部分：跨空间跳转与市场关系 + +## 25. 跨空间跳转设计 + +### 25.1 智能体工作台跳转矩阵 + +| 来源 | 目标 | 触发 | handoff 内容 | 完成后 | +|---|---|---|---|---| +| 作品智能体关联页 | agent-work-slot-selector | 选择槽位替换 | 作品、槽位、当前智能体、授权 | 返回作品刷新槽位 | +| 写作台候选面板 | agent-detail-version | 查看智能体详情 | 只读返回点 | 返回写作台 | +| agent-work-slot-selector | agent-test-bench | 试用候选 | 候选智能体、槽位合同 | 返回候选选择 | +| agent-detail-version | agent-publish-prep | 发布准备 | 版本、所有者 | 返回详情 | +| 市场获取完成 | agent-installed-library | 安装 | 资产、许可、版本 | 安装后回市场或作品 | + +### 25.2 知识库工作台跳转矩阵 + +| 来源 | 目标 | 触发 | handoff 内容 | 完成后 | +|---|---|---|---|---| +| 作品知识来源页 | knowledge-work-bind-selector | 绑定知识库 | 作品、当前来源、用途 | 返回作品刷新绑定 | +| 写作台候选面板 | knowledge-detail-version | 查看来源详情 | 只读返回点 | 返回写作台 | +| knowledge-detail-version | knowledge-work-bind-selector | 绑定到作品 | 知识库、版本、授权 | 返回详情或作品 | +| knowledge-detail-version | knowledge-publish-prep | 发布准备 | 版本、所有者 | 返回详情 | +| 市场获取完成 | knowledge-installed-library | 安装 | 资产、许可、版本 | 安装后回市场或作品 | + +### 25.3 前端 Handoff 实现 + +```typescript +// Zustand store 定义 +interface HandoffStore { + // 当前 handoff session + session: HandoffSession | null; + // 预检快照 + precheckId: string | null; + precheckExpiry: number | null; + // 返回点 + returnUrl: string | null; + + // 动作 + consumeToken: (token: string) => Promise; + clearSession: () => void; + setPrecheckId: (id: string, expiry: number) => void; + isSessionValid: () => boolean; + isPrecheckValid: () => boolean; +} +``` + +规则： +- handoff token 从 URL searchParams 获取，消费后从 URL 移除。 +- session 过期检查：每次操作前校验 `session.expiresAt > Date.now()`。 +- 页面卸载时不清除 session（支持浏览器后退恢复）。 +- 并发打开同一 handoff：返回同一 session 状态，不扩大范围。 + +## 26. 市场安装后的槽位替换流程 + +从市场安装智能体后，用户需要手动关联到作品槽位： + +1. 市场安装完成 → 跳转 `agent-installed-library`。 +2. 用户在已安装列表看到新智能体。 +3. 用户进入作品工作台 → 智能体关联页 → 选择槽位。 +4. 系统生成 handoff token → 跳转 `agent-work-slot-selector`。 +5. 消费 token → 展示候选（包含新安装的智能体）。 +6. 预检 → 确认替换 → 返回作品。 + +关键约束：安装不等于自动关联作品，必须经过槽位预检和用户确认。 + +--- + +## 27. 关联阅读 + +| 文档 | 关联内容 | +|---|---| +| `产品-02D-智能体工作台功能规格.md` | 智能体工作台完整产品定义、页面规格、操作规格 | +| `产品-02E-知识库工作台功能规格.md` | 知识库工作台完整产品定义、页面规格、操作规格 | +| `后端-05-统一API契约-v1.md` | API 路径、请求响应格式、错误码、幂等规则 | +| `架构-01-系统全貌与边界上下文.md` | BC 边界、权威归属、跨上下文协作 | +| `架构-02-核心数据结构与双轨模型.md` | 双轨模型、Shadow/Canonical 边界 | +| `前端-01-工程结构与核心依赖.md` | 工程结构、路由约定、状态分层、技术栈 | +| `前端-02-写作台与候选交互.md` | 作品工作台交互，候选接受/合并流程 | +| `前端-03-元引擎与动态表单.md` | MetaSchema 投影消费、动态表单渲染 | +| `前端-04-市场与个人中心交互.md` | 市场购买/安装流程、个人中心跳转 | + + + diff --git a/design-docs/后端-01-领域模型与聚合设计.md b/design-docs/后端-01-领域模型与聚合设计.md index 4d4f7d1d..fae6ae6f 100644 --- a/design-docs/后端-01-领域模型与聚合设计.md +++ b/design-docs/后端-01-领域模型与聚合设计.md @@ -1,7 +1,7 @@ # 后端-01：领域模型与聚合设计 -- 版本：v6 -- 更新日期：2026-05-23 +- 版本：v7 +- 更新日期：2026-05-24 - 目标读者：后端 / 架构 / 产品 - 阅读时间：30-45 分钟 - 边界说明：本文件只定义 Muse 领域模型、聚合职责、owner module 和不变式；工程结构看 `后端-02`，流程看 `后端-03`，Schema 看 `后端-04`，API 看 `后端-05`。 @@ -37,17 +37,17 @@ |---|---|---|---|---| | Auth / Permission | `yudao-module-system` | 用户、角色、权限、权限组、菜单、登录日志、操作日志 | Yudao 原生 admin/app 认证与权限接口 | 作品级事实确认、知识确认、市场授权事实 | | Infra | `yudao-module-infra` | 文件、配置、字典、定时任务、API 日志、监控 | Yudao 原生 infra 接口 | Muse 业务领域事实 | -| Governance / Admin Control | 逻辑 owner；物理表按对象落到 `content` / `ai` | MetaSchema、系统功能链路、保护节点、质量策略、影响预览和发布审计 | `/admin-api/muse/governance/**` | 用户私有正文、Local KB Canonical、候选确认、市场目标事实 | -| Content BC | `yudao-module-content` | Work、Chapter、Block、正文版本、Planning Canonical、Block Source Attribution、导入导出任务、作品设置、MetaSchema 版本化投影的物理承载 | `/admin-api/muse/content/**`、`/app-api/muse/works/**` | Prompt、Agent、知识确认、市场交易、MetaSchema 治理写入 | +| MetaSchema BC | `yudao-module-meta`（独立模块） | MetaSchema、元结构版本、字段定义、可见性策略、影响预览和发布审计 | `/admin-api/muse/governance/meta-schemas/**`（admin 写）、facade-api 只读消费 | 用户私有正文、Local KB Canonical、候选确认、市场目标事实、保护节点、质量策略 | +| Content BC | `yudao-module-content` | Work、Chapter、Block、正文版本、Planning Canonical、Block Source Attribution、导入导出任务、作品设置 | `/admin-api/muse/content/**`、`/app-api/muse/works/**` | Prompt、Agent、知识确认、市场交易、MetaSchema 治理写入 | | Knowledge BC | `yudao-module-knowledge` | User KB、Local KB、Knowledge Draft、Knowledge Entity/Relation/Event、Knowledge Source Binding、投影状态 | `/admin-api/muse/knowledge/**`、`/app-api/muse/knowledge-*/**` | 正文写入、市场资产授权、模型路由 | | AI Orchestration BC | `yudao-module-ai` 二开 | Prompt、Agent、Agent Slot、Tool Grant 投影、Runtime Permission Envelope、AI Task、Parse Job、Chapter Parse Result、Suggestion、Planning Candidate、Quality Result、Evaluation Dataset/Run | `/admin-api/muse/ai/**`、`/app-api/muse/ai/**`、`/app-api/muse/suggestions/**` | New-API 模型 Provider/供应商路由、分组限流、成本策略、原始调用日志 authority、用户权益账本、正文 Canonical、Tool Grant authority 自授权 | | Marketplace/Asset BC | `yudao-module-market` | Marketplace Asset、Listing、License、Authorization、Install、Publish Request、Appeal、Governance Result、来源侧 Handoff Token、授权摘要、跳转审计、Source Status Event | `/admin-api/muse/market/**`、`/app-api/muse/marketplace/**` | 正文事实、知识正式确认、Agent Slot Binding、Knowledge Source Binding、Block Source Attribution、目标 owner precheck/session、支付清结算底层 | -| Account / Entitlement BC | 逻辑 `account`，物理为 `yudao-module-account` 或 `member` 二开二选一 | Profile、Entitlement、Quota、Usage Summary、Purchase/Auth/Publish Summary、Personal Center Summary | `/admin-api/muse/account/**`、`/app-api/muse/account/**`、`/app-api/muse/me` | 作品事实、市场 asset owner、New-API 原始调用日志或成本账本 authority | +| Account / Entitlement BC | `yudao-module-member`（已决策：member 模块承载端侧用户 Account 功能） | Profile、Entitlement、Quota、Usage Summary、Purchase/Auth/Publish Summary、Personal Center Summary | `/admin-api/muse/account/**`、`/app-api/muse/account/**`、`/app-api/muse/me` | 作品事实、市场 asset owner、New-API 原始调用日志或成本账本 authority | | Source / Authorization Context | 来源对象 owner + outbox 协作 | Source Snapshot、Authorization Snapshot、Source Status Event、Source Propagation Target | 通过 Content / Knowledge / AI / Market / Account 的 owner API 和 `/admin-api/muse/source-events/**` 暴露 | 业务 Canonical 写入、支付清结算、权限菜单 | | Payment BC | `yudao-module-pay` | 充值、支付、交易流水、退款基础能力 | Yudao 原生 pay 接口，Muse 只引用交易结果 | 市场资产 owner、作品事实 | | Workflow BC | `yudao-module-bpm` | 复杂审核、申诉、合规流程 | Yudao 原生 bpm 接口或 Muse 流程回调 | 简单资产状态机的唯一 owner | -`account` 的逻辑 owner 必须固定：如果后续选择在 `member` 内二开，也只能由 `member` 内的 Muse account 包写 Profile、Entitlement、Quota 和个人中心聚合；不能再并行新增另一个 `account` 模块写同一批事实。 +Account BC 物理落点已决策：`yudao-module-member`。member 模块承载端侧用户的 Profile、Entitlement、Quota、Usage、Security Event 和 New-API Binding 聚合。不新增 `yudao-module-account`；`member` 内的 Muse account 包是唯一写入 authority，不允许并行新增另一个模块写同一批事实。 ## 3. 核心聚合 @@ -61,7 +61,7 @@ | Block Source Attribution | 正文 revision 的来源归因 | 候选使用 AI、市场、外部或授权知识来源时必须写入 lineage、授权快照和召回状态 | | Import / Export Task | 导入解析和导出交付任务 | 外部文件处理异步化；导出前必须重验权限、来源和许可 | | Planning Canonical | 用户确认或手动保存后的正式规划项 | 规划候选不能自动进入正式规划；进入 AI 上下文前必须校验来源、版本和可见性 | -| MetaSchema Projection | 作品和知识表达结构的系统级版本化投影 | 逻辑 owner 是 Admin/Governance；若物理表放在 Content，也只能由治理 facade / admin-api 写入，Content 和 app API 只能消费 active/gray 版本投影 | +| MetaSchema Projection | 作品和知识表达结构的系统级版本化投影 | 逻辑 owner 是 `yudao-module-meta`（独立模块）；Content 和 app API 只能消费 active/gray 版本投影 | Content 只拥有正文和作品结构。知识、AI 候选、市场授权都通过公开接口或事件协作。 @@ -91,7 +91,7 @@ Content 只拥有正文和作品结构。知识、AI 候选、市场授权都通 | Parse Job / Chapter Parse Result | 导入解析和全书解析的 AI Shadow 结果 | AI 拥有任务、章节解析结果、质量和失败状态；章节审阅通过后只请求 Knowledge 生成 Knowledge Draft | | AI Suggestion | 正文候选 | 只能进入 Shadow，不能直接写正文 | | Planning Candidate | 规划候选 | 只能进入 Shadow，必须经用户确认或手动保存后才成为正式规划 | -| Candidate Quality Result | 候选质量结果 | 质量结果不单独决定可接受性，最终由 Candidate Decision Envelope 合并 | +| Candidate Quality Result | 候选质量结果 | 质量结果不单独决定可接受性，接受时实时校验来源版本、质量结果和合规状态 | | Evaluation Dataset / Run | 质量评估集和评估运行 | 默认不得使用用户私有正文、私人候选全文、完整 Prompt/Response 或完整上下文 | AI 模块负责 Muse 侧编排、智能体、任务和待审对象。Yudao 原生 `ai` 能力只是可复用底座；一旦二开为 Muse AI owner，仍不得拥有 New-API 模型 Provider、供应商路由、分组限流、成本策略、原始调用日志 authority 或正文/知识 Canonical。 diff --git a/design-docs/后端-02-工程结构与模块职责.md b/design-docs/后端-02-工程结构与模块职责.md index 12982b2f..d5fab4de 100644 --- a/design-docs/后端-02-工程结构与模块职责.md +++ b/design-docs/后端-02-工程结构与模块职责.md @@ -1,7 +1,7 @@ # 后端-02：工程结构与模块职责 -- 版本：v6 -- 更新日期：2026-05-23 +- 版本：v8 +- 更新日期：2026-05-24 - 目标读者：后端 / 架构 / 平台 / 测试 - 阅读时间：25-40 分钟 - 边界说明：本文件只定义后端工程基线、Yudao Cloud fork 保留/裁剪模块、Muse 业务模块职责和模块协作边界。领域模型看 `后端-01`，关键流程看 `后端-03`，Schema 看 `后端-04`，API 契约看 `后端-05`。本文描述目标工程形态，不代表当前仓库所有模块都已实现。 @@ -22,7 +22,7 @@ muse-cloud/ # fork YunaiV/yudao-cloud 2. `/admin-api/**` 和 `/app-api/**` 只是入口不同，不是两套领域事实。 3. 同一个领域事实只能有一个 owner module。 4. 优先复用 Yudao 的 system、infra、framework、gateway、job、log、file、config、dict 等平台能力。 -5. Muse 业务模块只补创作系统需要的 content、knowledge、ai、market、account 能力。 +5. Muse 业务模块只补创作系统需要的 content、knowledge、ai、market、meta 能力，account 功能由 `yudao-module-member` 承载。 6. `yudao-server` 只负责启动装配、配置聚合和模块引入，不放 use case、领域规则、mapper 拼装或跨模块写入脚本。 ## 2. 当前保留模块 @@ -36,7 +36,7 @@ muse-cloud/ # fork YunaiV/yudao-cloud | `yudao-module-system` | 用户、角色、权限、菜单、登录日志、操作日志 | 保留并作为后台权限、菜单和用户基础能力 owner | | `yudao-module-infra` | 文件、字典、配置、定时任务、API 日志、监控 | 保留并作为基础设施能力 owner | | `yudao-module-ai` | Yudao AI 基础能力 | 保留，默认隐藏；后续二开为 Muse AI/Agent 能力载体 | -| `yudao-module-member` | 会员/账户基础能力 | 保留，默认隐藏；后续评估改造成账户/权益或被 `account` 替代 | +| `yudao-module-member` | 会员/账户基础能力；**已决策为 Muse Account BC 物理承载** | 保留并启用；承载端侧用户 Profile、Entitlement、Quota、Usage、Security Event 和 New-API Binding | | `yudao-module-pay` | 支付、充值、交易基础能力 | 保留，默认隐藏；市场交易、套餐、充值时启用 | | `yudao-module-bpm` | 工作流审批 | 保留，默认隐藏；审核、申诉、合规流程复杂后启用 | | `yudao-module-report` | 报表大屏 | 保留，默认隐藏；运营报表、质量大屏时启用 | @@ -56,8 +56,8 @@ muse-cloud/ # fork YunaiV/yudao-cloud 保留模块分层： - `gateway/dependencies/framework/server` 是工程底座。 -- `system/infra/member/pay/bpm/report/mp` 是 Yudao 平台和可选业务底座。 -- `content/knowledge/ai/market/account` 是 Muse 创作业务 owner。 +- `system/infra/member/pay/bpm/report/mp` 是 Yudao 平台和可选业务底座；其中 `member` 同时承载 Muse Account BC。 +- `content/knowledge/ai/market/meta` 是 Muse 创作业务 owner。 - `pay/bpm/report/mp` 在阶段 7 可以默认隐藏，但不能因为隐藏就删除依赖、菜单扩展点或后续接入边界。 ## 3. Muse 核心业务模块 @@ -66,15 +66,38 @@ muse-cloud/ # fork YunaiV/yudao-cloud | Muse 模块 | 职责 | 不负责 | |---|---|---| -| `yudao-module-content` | 作品、章节、文本块、正文版本、作品设置、导入任务、导入文件、章节上下文、导出、Block Source Attribution、MetaSchema 物理表和版本化投影消费 | Prompt、Agent、市场授权、知识确认、MetaSchema 治理写入、Parse Job / Chapter Parse Result | +| `yudao-module-content` | 作品、章节、文本块、正文版本、作品设置、导入任务、导入文件、章节上下文、导出、Block Source Attribution | Prompt、Agent、市场授权、知识确认、MetaSchema 治理写入、Parse Job / Chapter Parse Result | | `yudao-module-knowledge` | 用户知识库、局域知识、知识草稿确认、知识来源、投影、检索来源、知识库绑定 | 正文写入、市场交易、模型调用 | -| `yudao-module-ai` 二开 | Prompt、Agent、槽位、运行时权限包、生成任务、Parse Job、Chapter Parse Result、候选、质量门控、评测、Tool Grant 投影、Context Assembly、Candidate Decision Envelope / Archive | New-API 模型 Provider/供应商路由、成本策略、原始调用日志 authority、正文或知识 Canonical、Tool Grant authority 自授权 | -| `yudao-module-market` | 市场资产、授权、安装、来源侧 Handoff Token、授权摘要、跳转审计、发布申请、申诉、治理结果 | 作品正文事实、知识正式确认、Agent Slot Binding、Knowledge Source Binding、Block Source Attribution、目标 owner precheck/session、支付清结算底层 | -| `yudao-module-account` 或改造 `member` | 个人资料、权益、配额、用量、购买/授权/发布记录总览 | 作品事实、市场资产 owner、New-API 原始调用日志或成本账本 authority | +| `yudao-module-ai` 二开 | Prompt、Agent、槽位、运行时权限包、生成任务、Parse Job、Chapter Parse Result、候选、质量门控、评测、Tool Grant 投影、Context Assembly、Candidate Archive | New-API 模型 Provider/供应商路由、成本策略、原始调用日志 authority、正文或知识 Canonical、Tool Grant authority 自授权 | +| `yudao-module-meta` | MetaSchema 元结构定义、字段、可见性策略、版本发布、激活、回滚和影响预览 | 用户作品正文、Local KB、候选确认、市场目标事实 | +| `yudao-module-market` | 市场资产、授权、安装、来源侧 Handoff Token、授权摘要、跳转审计、发布申请、申诉、治理结果（含市场治理） | 作品正文事实、知识正式确认、Agent Slot Binding、Knowledge Source Binding、Block Source Attribution、目标 owner precheck/session、支付清结算底层 | +| `yudao-module-member` | 个人资料、权益、配额、用量、安全事件、New-API 绑定、购买/授权/发布记录总览（Account BC 物理承载） | 作品事实、市场资产 owner、New-API 原始调用日志或成本账本 authority | -建议决策：业务语义上使用 `account` 承载权益、配额、用量、授权和发布记录；`member` 先作为 Yudao 可复用底座保留隐藏。是否物理新增 `yudao-module-account`，还是在 `member` 内二开，需要在后端落地前单独确认。 +Account BC 物理落点已决策：使用现有 `yudao-module-member` 模块承载端侧用户（Account）功能，不新增 `yudao-module-account`。member = 端侧用户，语义等同于 Account BC 的物理承载。 -物理落地约束：`account` 与 `member` 只能二选一承载 Muse 账户权益事实。选择前，文档和 API 使用逻辑名 `account`；选择后，另一个模块只能作为依赖或适配层，不得并行写 Profile、Entitlement、Quota、Usage Summary 或 Personal Center Summary。 +member 模块扩展职责：除 Yudao 原有会员基础能力外，新增 Muse 的权益（Entitlement）、配额（Quota）、用量（Usage）、安全事件（Security Event）和 API 绑定（New-API Binding）。 + +包结构建议： + +```text +yudao-module-member/ + yudao-module-member-api/ + admin/ + app/ + event/ + yudao-module-member-server/ + controller/admin/ + controller/app/ + application/ + domain/ + profile/ # 用户画像/偏好 + entitlement/ # 权益 + quota/ # 配额 + usage/ # 用量 + security/ # 安全事件 + binding/ # New-API 绑定 + infrastructure/ +``` ### 3.2 标准模块结构 @@ -122,6 +145,103 @@ yudao-module-content/ 禁止出现 `yudao-server/src/main/java/.../muse/...` 这类承载业务用例的过渡目录；如果为了启动聚合需要配置 Bean，只能在 `yudao-server` 做模块装配。 +## 3.3 Agent BC 与 AI Orchestration BC 包级隔离策略 + +`yudao-module-ai` 在同一物理模块内承载 Agent BC（智能体配置、版本、槽位）和 AI Orchestration BC（任务编排、候选生成、质量门控、上下文组装）。为防止职责混淆和越权调用，必须在包级别做隔离： + +```text +yudao-module-ai-server/ + domain/ + agent/ # Agent BC：Agent、AgentVersion、Slot、SlotBinding + orchestration/ # AI Orchestration BC：Task、Candidate、QualityGate、ContextAssembly、ParseJob + grant/ # Tool Grant 投影消费（只读）+ Protection Node + Quality Policy 写入服务 + application/ + agent/ # Agent 配置用例 + orchestration/ # 编排运行用例 + grant/ # Grant/Governance 包：Tool Grant、Runtime Permission Envelope、Protection Node 写入服务，只暴露给 admin-api + controller/ + admin/ + grant/ # /admin-api/muse/ai/tool-grants/**、/admin-api/muse/governance/protection-nodes/** + app/ + runtime/ # /app-api/muse/ai/** +``` + +AI 授权隔离（grant vs runtime）： + +| 包 | 职责 | 暴露入口 | +|---|---|---| +| `ai.grant`（`application/grant` + `domain/grant`） | Tool Grant 写入、Runtime Permission Envelope 签发、Protection Node 写入服务 | 只暴露给 admin-api（Governance facade 调用） | +| `ai.runtime`（`application/orchestration` + `domain/orchestration`） | AI 任务执行、候选生成、上下文组装 | 只能读取 grant 包签发的 envelope，不能调用 grant 写入接口 | + +ArchUnit 规则： + +```java +// 禁止 runtime 包调用 grant 包的写入接口 +noClasses() + .that().resideInAPackage("..ai.application.orchestration..") + .or().resideInAPackage("..ai.domain.orchestration..") + .should().accessClassesThat() + .resideInAPackage("..ai.application.grant..") + .orShould().callMethodWhere( + target(nameMatching(".*Write.*|.*Create.*|.*Update.*|.*Delete.*|.*Publish.*")) + .and(target(owner(resideInAPackage("..ai.domain.grant..")))) + ); +``` + +依赖方向约束： + +| 包 | 允许依赖 | 禁止依赖 | +|---|---|---| +| `domain/agent` | 自身聚合、`domain/grant`（只读投影） | `domain/orchestration` 内部实现 | +| `domain/orchestration` | 自身聚合、`domain/agent`（只读版本查询）、`domain/grant`（只读投影） | `domain/grant` 写入方法 | +| `domain/grant` | 无外部领域依赖 | `domain/agent`、`domain/orchestration` | +| `application/grant` | `domain/grant`（读写）、外部 Governance/Security facade | `application/orchestration`、`domain/orchestration` | +| `application/orchestration` | `domain/orchestration`、`domain/agent`（只读 facade）、`domain/grant`（只读） | `application/grant` 写入用例 | + +Tool Grant 写入约束： + +- Tool Grant 的创建、审批、变更和版本发布只能通过 `governance/security facade` 包路径完成，物理入口在 Governance/Admin facade 或 Security facade。 +- `domain/grant` 包内只暴露只读投影查询接口（`ToolGrantProjectionQuery`），不暴露任何写入方法。 +- AI runtime（`domain/orchestration`、`application/orchestration`）只能调用 `domain/grant` 的只读投影生成 Runtime Permission Envelope，不能直接调用 grant 写入方法。 +- 违反此约束的代码在 code review 和 ArchUnit 规则中必须被拦截。 + +### 3.4 Governance Facade 工程落点 + +Governance facade 是 MetaSchema、保护节点、系统功能链路、Tool Grant 和质量策略的逻辑写入 authority。工程落点已明确拆分： + +| 职责 | 物理位置 | 说明 | +|---|---|---| +| MetaSchema 全部能力 | `yudao-module-meta`（独立模块） | admin 写入 + 用户作品级覆盖 + facade-api 只读消费；Content、Knowledge、AI 等模块通过 `meta-api` 只读依赖消费 active/gray 投影 | +| 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 包 | + +`yudao-module-meta` 模块结构： + +```text +yudao-module-meta/ + yudao-module-meta-api/ + admin/ # MetaSchema 管理 DTO、facade 接口 + app/ # 用户作品级覆盖 DTO + facade/ # 只读消费 facade（供 content/knowledge/ai 依赖） + yudao-module-meta-server/ + controller/admin/ # /admin-api/muse/governance/meta-schemas/** + controller/app/ # /app-api/muse/works/{workId}/meta-projections/** + application/ + domain/ + schema/ # MetaSchema、MetaField、VisibilityPolicy + version/ # 版本发布、激活、回滚、灰度 + projection/ # 投影计算和缓存 + infrastructure/ +``` + +约束： + +- `yudao-module-meta` 是 MetaSchema 唯一写入 authority。 +- Content、Knowledge、AI 等模块只能通过 `meta-api/facade` 只读消费 active/gray 投影。 +- 用户作品级覆盖（work-level override）通过 app 入口提交，但仍由 meta 模块校验和存储。 +- Content 模块不再物理承载 MetaSchema 表。 + ## 4. 模块边界 ### 4.1 owner 边界 @@ -130,14 +250,21 @@ yudao-module-content/ |---|---|---| | 用户、角色、权限、菜单 | `yudao-module-system` | 全部模块通过权限摘要或用户上下文读取 | | 文件、配置、字典、任务、API 日志 | `yudao-module-infra` | 全部模块按 Yudao 基础设施方式调用 | -| 作品、章节、Block、正文版本、MetaSchema 物理表和版本化投影 | `yudao-module-content`；MetaSchema 逻辑 owner 是 Governance/Admin facade | knowledge、ai、market、account | +| 作品、章节、Block、正文版本 | `yudao-module-content` | knowledge、ai、market、account | +| MetaSchema、元结构版本、字段定义、可见性策略 | `yudao-module-meta` | content、knowledge、ai、market、account | | 用户知识库、局域知识、知识草稿、来源绑定 | `yudao-module-knowledge` | content、ai、market | -| Prompt、Agent、Parse Job、Chapter Parse Result、任务、候选、质量门控、评测、Candidate Decision Archive | `yudao-module-ai` | content、knowledge、market、account | +| Prompt、Agent、Parse Job、Chapter Parse Result、任务、候选、质量门控、评测、Candidate Archive | `yudao-module-ai` | content、knowledge、market、account | | 市场资产、授权、安装、发布、申诉、治理、来源侧 Handoff Token、授权摘要、跳转审计 | `yudao-module-market` | content、knowledge、ai、account | -| 权益、配额、用量、购买/授权/发布记录总览 | `yudao-module-account` 或 `member` | market、ai、personal center read model | +| 权益、配额、用量、购买/授权/发布记录总览 | `yudao-module-member` | market、ai、personal center read model | | Source Snapshot、Authorization Snapshot、Source Status Event、Source Propagation Target | 来源对象 owner + 授权签发 owner；横切表级 owner 跟随来源 owner，不归入 Knowledge 单模块 | content、knowledge、ai、market、account | -Source / Authorization Context 是横切上下文：来源 owner 负责发布 Source Status Event，受影响对象 owner 负责幂等消费、禁用新使用、标记需重验或刷新自己的读模型。Knowledge 只拥有知识来源绑定和知识投影，不拥有所有来源授权事实。 +Source / Authorization Context 是横切上下文：来源 owner 负责发布 Source Status Event，受影响对象 owner 负责幂等消费、禁用新使用或刷新自己的读模型。Knowledge 只拥有知识来源绑定和知识投影，不拥有所有来源授权事实。 + +Source / Authorization 物理归属： + +- `source_snapshot` 表 DDL 归 `yudao-module-infra` 模块（横切基础设施）。 +- 各业务模块（content、knowledge、ai、market、account）分散写入 source_snapshot 记录。 +- 传播模式为事件驱动自治：通过 Spring Event 或 MQ 发布来源状态事件，各模块自行监听并处理自己 owner 范围内的传播目标。 ### 4.2 跨模块调用规则 @@ -146,7 +273,7 @@ Source / Authorization Context 是横切上下文：来源 owner 负责发布 So | 查询摘要 | 通过 `api` facade、只读 query service 或事件投影读取 | 直接跨模块读写对方表并推断状态 | | 写入事实 | 回到 owner module 的 application use case | 在调用方 mapper 里直接写对方事实 | | 异步协作 | outbox event + 幂等 consumer + 可重试任务 | MQ 消费端无幂等直接改 Canonical | -| MetaSchema 治理 | `/admin-api/muse/governance/**` 经 Governance/Admin facade 写 MetaSchema 草稿、发布、激活、回滚和影响预览 | Content app/admin controller 任意写字段结构或让用户端绕过治理改 Schema | +| MetaSchema 治理 | `/admin-api/muse/governance/**` 经 `yudao-module-meta` 写 MetaSchema 草稿、发布、激活、回滚和影响预览 | Content app/admin controller 任意写字段结构或让用户端绕过治理改 Schema | | Tool Grant | Governance / Security facade 发布授权，AI runtime 只消费授权投影生成权限包 | `yudao-module-ai` 按 Prompt、模型输出或 Agent 自述给自己增加工具、上下文、外发或预算 | | Handoff | market 只写 Authorization / Install / 来源侧 handoff token / 授权摘要 / 跳转审计，目标 owner 生成并消费自己的 precheck/session | 市场模块直接写槽位、知识绑定、正文归因、作品正文或目标预检结果 | | Source Status Event | 来源 owner 发布事件，影响对象 owner 幂等处理 | 查询时临时拼状态但不落传播结果 | @@ -156,7 +283,7 @@ Source / Authorization Context 是横切上下文：来源 owner 负责发布 So - 不按 `admin` 和 `app` 复制两套领域服务。 - 不让管理后台 controller 直接写用户作品正文、知识事实或候选确认结果。 - 不让用户端 controller 直接修改 MetaSchema、系统 Prompt、系统 Agent、质量策略、Tool Grant 或市场治理结果。 -- 不让 Content controller 把 MetaSchema 当普通作品表单结构随意更新；MetaSchema 写入只能经 Governance/Admin facade、影响预览、版本发布和审计。 +- 不让 Content controller 把 MetaSchema 当普通作品表单结构随意更新；MetaSchema 写入只能经 `yudao-module-meta`、影响预览、版本发布和审计。 - 不让 `yudao-module-ai` 自授工具、上下文、外发目标、预算或来源访问权限；运行时只能消费服务端签发的 Runtime Permission Envelope。 - 不让 `yudao-server` 聚合层承载业务逻辑。 - 不让 `infra`、`system` 成为 Muse 业务事实的万能容器。 @@ -182,11 +309,12 @@ yudao-gateway -> yudao-server -> yudao-module-system -> yudao-module-infra + -> yudao-module-meta # MetaSchema 独立模块 -> yudao-module-content -> yudao-module-knowledge -> yudao-module-ai -> yudao-module-market - -> yudao-module-account/member + -> yudao-module-member # 承载 Account BC ``` 可以按模块边界演进到微服务，但阶段 7 文档不要求立即拆成多进程。无论单体聚合还是微服务，领域 owner、API 前缀、权限边界和事件合同保持不变。 diff --git a/design-docs/后端-03-关键流程实现与接口契约.md b/design-docs/后端-03-关键流程实现与接口契约.md index 1b1e3b34..378c0917 100644 --- a/design-docs/后端-03-关键流程实现与接口契约.md +++ b/design-docs/后端-03-关键流程实现与接口契约.md @@ -1,7 +1,7 @@ # 后端-03：关键流程实现与接口契约 -- 版本：v7 -- 更新日期：2026-05-23 +- 版本：v9 +- 更新日期：2026-05-24 - 目标读者：后端 / 前端 / 架构 / 测试 - 阅读时间：30-50 分钟 - 边界说明：本文件只讲关键链路、事务边界、失败模式和后端职责归属；精确路径、请求响应和错误码看 `后端-05`，状态机看 `架构-04`，工程模块看 `后端-02`。 @@ -70,7 +70,7 @@ Accept Suggestion 是正文候选进入正文 Canonical 的唯一合法入口。 1. 校验用户对 Work / Chapter / Block / Suggestion 的权限。 2. 校验 Suggestion 仍处于 Active Shadow，未过期、未失效、未 blocked。 3. 校验 expectedRevision。 -4. 消费或重算 Candidate Decision Envelope，包含 `qualityResultVersion`、输出合规结果、静态检查结果、Authorization Snapshot、Source Snapshot、Source Status、market feature gate、`workAssetUsePrecheckId`、`expectedRevision` 和 `idempotencyKey`。 +4. 实时校验来源版本：比对候选记录的 `source_version` 与当前来源实际版本，校验 `qualityResultVersion`、输出合规结果、静态检查结果、Authorization Snapshot、Source Snapshot、Source Status、market feature gate、`workAssetUsePrecheckId` 和 `idempotencyKey`。 5. 写 Block 新 revision。 6. 写 Block Source Attribution。 7. 将 Suggestion 迁入 Archive。 @@ -95,10 +95,43 @@ Accept Suggestion 是正文候选进入正文 Canonical 的唯一合法入口。 - 来源 revoked / recalled / blocked / owner_missing / unauthorized：候选 blocked 或 invalidated，不写正文。 - 市场作品资产缺 `workAssetUsePrecheckId` 或 feature gate：不写正文。 - revision 冲突：返回可恢复冲突信息，不静默覆盖。 -- Candidate Decision Envelope 过期、质量结果版本不匹配、输出合规或静态检查 blocked：返回阻断原因、来源归因和可重算入口，不写正文。 +- 来源版本不匹配、质量结果版本不匹配、输出合规或静态检查 blocked：返回阻断原因、来源归因和可重试入口，不写正文。 - 失败响应必须保留 `blockSourceAttribution`、`blockedReasons`、`sourceStatusReasons`、`reasonAttributions`、`authorizationSnapshotId`、`qualityResultVersion` 和 `nextActions`，不能把 stale / revoked / unauthorized 来源压缩成普通失败。 - outbox 或投影失败：不得回滚已成功的正文主事务，但必须可重试、可观察、可审计。 +## 4A. 正文保存后知识提取 + +正文保存成功后，系统可触发知识提取链路，将正文变更转化为知识草稿供用户确认。 + +```text +Block 保存成功（Content owner） +-> AFTER_COMMIT 写 outbox 事件（BlockSavedEvent） +-> AI/Knowledge 消费事件 +-> AI 创建知识提取任务（extraction task） +-> AI 调用模型提取实体/关系/事件 +-> AI 生成 Knowledge Draft（Shadow） +-> 用户在知识草稿入口确认 +-> Knowledge 写 Local KB Canonical +``` + +流程职责拆分： + +| 阶段 | Owner | 说明 | +|---|---|---| +| Block 保存和 outbox 事件 | `content` | 正文保存主事务成功后，AFTER_COMMIT 写 `BlockSavedEvent` 到 outbox，包含 `workId`、`chapterId`、`blockId`、`revision`、`changeSource` | +| 事件消费和提取任务创建 | `ai` | 消费 `BlockSavedEvent`，按策略判断是否需要提取（例如 revision 变化量、章节完成度、用户配置），创建 extraction task | +| 知识提取执行 | `ai` | 调用模型提取实体、关系、事件，生成 Shadow 结果 | +| Knowledge Draft 生成 | `knowledge` | AI 提取完成后，通过 Knowledge facade 请求创建或刷新 Knowledge Draft | +| 用户确认 | `knowledge` | 用户在知识草稿入口确认后写 Local KB Canonical | + +约束： + +- 正文保存主事务不等待知识提取完成；提取是异步 followup task。 +- 提取失败不回滚已保存正文。 +- 提取结果只能进入 Knowledge Draft（Shadow），不能直接写 Local KB Canonical。 +- 提取任务按 `workId + chapterId + blockId + revision` 幂等；同一 revision 不重复提取。 +- Block 保存响应可包含 `followupTasks` 字段，告知前端有知识提取任务已触发（见 `后端-05` 4.3 节 `PUT /blocks/{blockId}` 响应说明）。 + ## 5. Knowledge Draft 确认 知识草稿确认由 `yudao-module-knowledge` owner 执行。 @@ -178,8 +211,8 @@ AI 链路由 `yudao-module-ai` 二开承载。 -> 静态检查 / 来源状态校验 -> Quality Gate -> Output Compliance --> Candidate Decision Envelope --> 用户决策 +-> Shadow Candidate（记录 source_version） +-> 用户决策（接受时实时对比来源版本） ``` 后端职责： @@ -275,8 +308,8 @@ Account/Member 只提供用户可见权益和汇总，不替代业务 owner。 | `eventId` | 幂等事件 ID | | `sourceType` / `sourceId` / `sourceVersion` | 来源对象和版本 | | `eventType` | SourceEventType，例如 `source_updated`、`source_revoked`、`asset_recalled`、`asset_delisted`、`asset_blocked`、`owner_missing`、`authorization_revoked`、`authorization_expired`、`license_changed`、`processing_failed`、`recheck_required` | -| `sourceStatus` | SourceStatus，例如 `active`、`stale`、`revoked`、`recalled`、`delisted`、`blocked`、`owner_missing`、`unauthorized`、`needs_recheck` | -| `actionPolicy` | SourceActionPolicy：`allowed`、`read_only`、`blocked`、`needs_recheck` | +| `sourceStatus` | SourceStatus，例如 `active`、`stale`、`revoked`、`recalled`、`delisted`、`blocked`、`owner_missing`、`unauthorized` | +| `actionPolicy` | SourceActionPolicy：`allowed`、`read_only`、`blocked`、`needs_recheck`（注：needs_recheck 是 ActionPolicy 层面的动作策略结论，不是 SourceStatus 枚举值） | | `reasonCode` | 治理、授权、版本、权利、合规或处理失败原因 | | `reasonAttribution` | reasonCode 对应的来源 owner、授权快照、治理动作或处理任务 | | `affectedScopes` | 候选、草稿、绑定、安装、运行任务、导出、下载、个人中心记录等影响范围 | @@ -293,17 +326,17 @@ Account/Member 只提供用户可见权益和汇总，不替代业务 owner。 | 市场资产下架但历史授权可读 | `asset_delisted` | `delisted` | `read_only` | | 治理封禁 | `asset_blocked` | `blocked` | `blocked` | | owner 缺失或不可见 | `owner_missing` | `owner_missing` | `blocked` | -| 版本、许可或处理状态变化 | `license_changed` / `processing_failed` / `recheck_required` | `stale` 或 `needs_recheck` | `needs_recheck` | +| 版本、许可或处理状态变化 | `license_changed` / `processing_failed` / `recheck_required` | `stale` | `needs_recheck` | 处理结果不得改写已确认 Canonical。允许的动作是禁用新使用、标记需重验、作废未确认对象、取消或阻断运行中任务、失效下载凭证、刷新个人中心摘要和写审计。 ## 12. P1 跨模块补充契约 -- Candidate Decision Archive owner 单一化：AI 拥有归档表和 Decision Envelope 版本，Content Accept 只能通过 AI decision facade 消费或重算后拿 `decisionArchiveId` 引用，不在 Content 表复制候选决策事实。 -- Download Credential 必须承载来源传播结果：来源 revoked / recalled / blocked / unauthorized 后，已签发凭证进入 disabled 或 needs_recheck，下载时再次校验授权快照和 source event version。 +- Candidate Decision Archive owner 单一化：AI 拥有归档表，Content Accept 只能通过 AI decision facade 消费后拿 `decisionArchiveId` 引用，不在 Content 表复制候选决策事实。接受时实时校验来源版本，不再依赖预计算的 Envelope。 +- Download Credential 必须承载来源传播结果：来源 revoked / recalled / blocked / unauthorized 后，已签发凭证进入 disabled 状态，下载时再次校验授权快照和 source event version。 - Local KB entity / relation / event 必须保存来源快照、授权快照和 source status 摘要；来源事件不删除正式知识，但阻断新检索、新生成、新确认和受限导出。 - New-API binding、quota request、call attribution 必须有本地幂等记录、correlationId、重试组和用户可见归属状态；Muse 不复制 Provider、路由、成本和原始日志 authority。 -- Pay callback / refund 只通过支付引用和幂等事件传播到 account entitlement ledger；退款、撤销和补偿都用 append-only 反向流水，不覆盖原权益流水。 +- Pay callback / refund 只通过支付引用和幂等事件传播到 account entitlement 可变表和审计日志；退款、撤销和补偿通过反向变更更新可变表并写审计日志记录。 - 文件上传必须绑定 owner、用途、大小、MIME、hash、扫描状态、保留期、清理策略和来源快照；Yudao infra 只提供文件能力，不拥有导入、知识资料或市场素材的业务事实。 ## 13. 关联阅读 diff --git a/design-docs/后端-04-统一数据库Schema-v1.md b/design-docs/后端-04-统一数据库Schema-v1.md index f925ff80..d70a1fe2 100644 --- a/design-docs/后端-04-统一数据库Schema-v1.md +++ b/design-docs/后端-04-统一数据库Schema-v1.md @@ -1,7 +1,7 @@ # 后端-04：统一数据库 Schema(结构定义)-v1 -- 版本：v8 -- 更新日期：2026-05-23 +- 版本：v10 +- 更新日期：2026-05-24 - 目标读者：后端 / 架构 / 前端 / 数据库维护者 / 测试 - 阅读时间：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`。 @@ -50,7 +50,7 @@ Muse 新业务表建议使用统一前缀： | 知识 | `muse_knowledge_` | `muse_knowledge_draft` | | AI / Agent | `muse_ai_` | `muse_ai_candidate` | | 市场 | `muse_market_` | `muse_market_asset` | -| 账户 | `muse_account_` | `muse_account_usage_record` | +| 账户 | `muse_member_` | `muse_member_usage_record` | | 来源与授权 | `muse_source_` / `muse_authorization_` | `muse_source_status_event` / `muse_authorization_snapshot` | | 审计 | `muse_audit_` | `muse_audit_event` | | Outbox | `muse_outbox_` | `muse_outbox_event` | @@ -60,11 +60,11 @@ Muse 新业务表建议使用统一前缀： Owner 约定： -- `content` 拥有作品、章节、Block、正文版本、Block Source Attribution、Planning Canonical、导入任务、导入文件、章节上下文、导出和下载凭证；MetaSchema 可以物理承载在 content 表，但逻辑 owner 是 Admin/Governance。 +- `content` 拥有作品、章节、Block、正文版本、Block Source Attribution、Planning Canonical、导入任务、导入文件、章节上下文、导出和下载凭证。 - `knowledge` 拥有 User KB、Local KB、Knowledge Draft、Knowledge Entity/Relation/Event 和知识来源绑定。 -- `ai` 拥有 Prompt、Agent、Protected Node Registry、Override Slot、Tool Grant 投影、Runtime Permission Envelope、AI Task、Parse Job、Chapter Parse Result、Candidate、Quality Result 和 Candidate Decision Archive。 +- `ai` 拥有 Prompt、Agent、Protected Node Registry、Override Slot、Tool Grant 投影、Runtime Permission Envelope、AI Task、Parse Job、Chapter Parse Result、Candidate、Quality Result 和 Candidate Decision Archive。候选记录 `source_version`，接受时实时对比来源版本。 - `market` 拥有 Market Asset、License、Authorization、Install、来源侧 Handoff Token、授权摘要、跳转审计、Publish、Review、Governance 和 Appeal；不拥有目标 owner precheck/session。 -- `account` 拥有 Muse 创作权益、Usage、Entitlement、个人中心读模型、安全事件和账户导出。 +- `account`（物理承载于 member 模块）拥有 Muse 创作权益、Usage、Entitlement、个人中心读模型、安全事件和账户导出。 - `source/authorization` 是横切来源与授权快照 owner：由来源 owner 生成或引用，负责不可变来源快照、授权快照、来源状态事件和传播目标。 - `audit/outbox/integration` 是横切 owner：由触发动作的业务模块写入业务审计、领域事件和外部调用摘要，不接管 Content / Knowledge / AI / Market / Account 的 Canonical 事实。 @@ -110,12 +110,13 @@ API 层 ID 规则： | 分区 | Owner 模块 | 核心表 | |---|---|---| -| Content | `yudao-module-content` | Work、Chapter、Block、Block Revision、Block Source Attribution、Planning、MetaSchema 物理表、Import、Import File、Chapter Context、Export | +| Content | `yudao-module-content` | Work、Chapter、Block、Block Revision、Block Source Attribution、Planning、Import、Import File、Chapter Context、Export | +| MetaSchema | `yudao-module-meta` | MetaSchema、MetaField、MetaVisibilityPolicy、MetaSchemaVersion | | Knowledge | `yudao-module-knowledge` | Knowledge Base、Document、Chunk、Processing Job、Local KB、Knowledge Draft、Knowledge Source Binding | | AI / Agent | `yudao-module-ai` 二开 | Prompt、Agent、System Function Chain、Protected Node、Override Slot、Tool Grant、Runtime Envelope、AI Task、Parse Job、Chapter Parse Result、Candidate、Quality Policy、Evaluation | | Marketplace | `yudao-module-market` | Asset、Listing、License、Purchase/Authorization、Install、Collection、Publish、Review、Governance、Appeal、Source-side Handoff | -| Account | `yudao-module-account` 或 `member` 二开 | Profile Extension、Preference、Entitlement Snapshot、Entitlement Ledger、Quota Adjustment、Usage Record、Asset Summary、Security Event、Account Export | -| Source / Authorization | 来源对象 owner + outbox 协作 | Source Snapshot、Authorization Snapshot、Source Status Event、Source Propagation | +| Account | `yudao-module-member`（已决策） | Profile Extension、Preference、Entitlement Snapshot、Entitlement（可变表）、Entitlement Audit Log、Quota Adjustment、Usage Record、Asset Summary、Security Event、Account Export | +| Source / Authorization | `yudao-module-infra`（DDL） + 各业务模块分散写入 | Source Snapshot、Authorization Snapshot、Source Status Event、Source Propagation | | Audit / Outbox / Integration | Muse 业务模块 + Yudao infra | High-risk Audit、Outbox、Projection、Integration Call Log | ### 3.1 表级 Owner 矩阵 @@ -132,10 +133,10 @@ API 层 ID 规则： | `muse_content_planning_item` | content | content | ai / knowledge | planning 变化写 outbox，供 AI 上下文投影消费 | | `muse_content_narrative_state` | content | content | ai / knowledge | narrative state 变化写 outbox | | `muse_content_work_asset_use_precheck` | content | content target owner service | market / ai / source | 作品资产用于参考、模板或 AI 上下文的目标预检；阶段 7 默认 feature disabled | -| `muse_content_meta_schema` | content | governance/admin facade -> content meta service | ai / knowledge / market / account | 激活、停用、回滚写 outbox，供投影和运行时缓存刷新 | -| `muse_content_meta_field` | content | governance/admin facade -> content meta service | ai / knowledge | 随 MetaSchema 版本发布传播 | -| `muse_content_meta_visibility_policy` | content | governance/admin facade -> content meta service | ai / knowledge / account | 随 MetaSchema 版本发布传播 | -| `muse_content_meta_schema_version` | content | governance/admin facade -> content meta service | ai / knowledge / market / account | 发布、激活、回滚和影响预览写 outbox | +| `muse_meta_schema` | meta | `yudao-module-meta` admin service | ai / knowledge / market / account / content | 激活、停用、回滚写 outbox，供投影和运行时缓存刷新 | +| `muse_meta_field` | meta | `yudao-module-meta` admin service | ai / knowledge / content | 随 MetaSchema 版本发布传播 | +| `muse_meta_visibility_policy` | meta | `yudao-module-meta` admin service | ai / knowledge / account / content | 随 MetaSchema 版本发布传播 | +| `muse_meta_schema_version` | meta | `yudao-module-meta` admin service | ai / knowledge / market / account / content | 发布、激活、回滚和影响预览写 outbox | | `muse_content_import_task` | content | content | knowledge / ai | 导入完成触发 AI parse job 或正文初始化事件 | | `muse_content_import_file` | content | content + infra file facade | ai / knowledge / source | 上传文件 owner、hash、扫描、保留期和清理策略写 outbox | | `muse_content_import_chapter_context` | content | content | ai / knowledge | 章节拆分上下文供 AI Parse Job 读取，不保存解析结果 | @@ -153,7 +154,7 @@ API 层 ID 规则： | `muse_knowledge_draft` | knowledge | knowledge | content / ai / source | draft stale、invalidated、needs_reextract 写 outbox | | `muse_knowledge_source_binding` | knowledge | knowledge | content / ai / market / source | 绑定状态受来源事件传播，阻断新检索或生成 | | `muse_knowledge_bind_precheck` | knowledge | knowledge target owner service | market / source / account | 知识绑定目标预检或签名消费凭证，原子消费后写 source binding | -| `muse_source_snapshot` | source/authorization | 来源 owner 或 source facade | content / knowledge / ai / market / account | 创建后不可变，通过引用传播 | +| `muse_source_snapshot` | infra（DDL owner） | 各业务模块分散写入 | content / knowledge / ai / market / account | 创建后不可变，通过引用传播 | | `muse_authorization_snapshot` | source/authorization | authorization facade | content / knowledge / ai / market / account | 创建后不可变，过期或撤权触发重验 | | `muse_source_status_event` | source/authorization | 来源 owner + market governance | content / knowledge / ai / market / account | `event_key` 幂等进入 outbox 并展开传播目标 | | `muse_source_propagation_target` | source/authorization | source propagation worker | content / knowledge / ai / market / account | 逐目标记录 pending / applied / blocked / failed / skipped | @@ -197,18 +198,19 @@ API 层 ID 规则： | `muse_market_review_submission` | market | market | audit / bpm | 审核状态写 outbox | | `muse_market_governance_action` | market | market governance | source / authorization / audit | 下架、召回、blocked 必须写 Source Status Event | | `muse_market_appeal` | market | market | audit / bpm | 申诉状态写 outbox | -| `muse_account_profile_ext` | account | account | market / content | 个人资料变化写账户读模型事件 | -| `muse_account_preference` | account | account | content / ai | 偏好变化刷新运行时默认值 | -| `muse_account_new_api_binding` | account | account integration service | ai / audit | 网关用户绑定摘要和重验状态，不保存 token 或 provider authority | -| `muse_account_entitlement_snapshot` | account | account entitlement service | ai / market | 权益快照变化写 outbox | -| `muse_account_entitlement_ledger` | account | account entitlement service | ai / market / audit | append-only 权益流水写审计 | -| `muse_account_quota_request` | account | account integration service | ai / audit | New-API 额度配置请求、correlationId、幂等和补偿状态 | -| `muse_account_quota_adjustment` | account | admin account service | ai / audit | 管理员调额 append-only，按幂等键去重 | -| `muse_account_usage_record` | account | account usage service | ai / content / knowledge / market | usage 摘要写个人中心读模型 | -| `muse_account_call_attribution_job` | account | account attribution service | ai / integration / audit | 调用归属、补偿和用户可见解释任务 | -| `muse_account_asset_summary` | account | account projection worker | market / ai / knowledge | 只做读模型投影 | -| `muse_account_security_event` | account | account / audit | content / market | 安全事件 append-only | -| `muse_account_export_task` | account | account | content / market / source / authorization | API 应承接导出任务创建、轮询和下载审计 | +| `muse_member_profile_ext` | member | member | market / content | 个人资料变化写账户读模型事件 | +| `muse_member_preference` | member | member | content / ai | 偏好变化刷新运行时默认值 | +| `muse_member_new_api_binding` | member | member integration service | ai / audit | 网关用户绑定摘要和重验状态，不保存 token 或 provider authority | +| `muse_member_entitlement_snapshot` | member | member entitlement service | ai / market | 权益快照变化写 outbox | +| `muse_member_entitlement` | member | member entitlement service | ai / market / audit | 可变权益表，变更时同步写审计日志 | +| `muse_member_entitlement_audit_log` | member | member entitlement service | ai / market / audit | 权益变更审计日志，append-only | +| `muse_member_quota_request` | member | member integration service | ai / audit | New-API 额度配置请求、correlationId、幂等和补偿状态 | +| `muse_member_quota_adjustment` | member | admin member service | ai / audit | 管理员调额 append-only，按幂等键去重 | +| `muse_member_usage_record` | member | member usage service | ai / content / knowledge / market | usage 摘要写个人中心读模型 | +| `muse_member_call_attribution_job` | member | member attribution service | ai / integration / audit | 调用归属、补偿和用户可见解释任务 | +| `muse_member_asset_summary` | member | member projection worker | market / ai / knowledge | 只做读模型投影 | +| `muse_member_security_event` | member | member / audit | content / market | 安全事件 append-only | +| `muse_member_export_task` | member | member | content / market / source / authorization | API 应承接导出任务创建、轮询和下载审计 | | `muse_audit_event` | audit | 动作 owner | 全模块 | append-only，不反写业务事实 | | `muse_outbox_event` | outbox | 事实 owner | 全模块 | `event_key` 幂等消费 | | `muse_projection_task` | integration/outbox | 投影 owner | 全模块 | 投影失败可重试，不反写 Canonical | @@ -297,7 +299,7 @@ Block revision 历史。 | `source_object_id` / `source_version` | 来源对象和版本 | | `lineage_payload` | 派生链路摘要 | | `authorization_snapshot_id` | 授权快照 | -| `source_status` | SourceStatus：`active` / `stale` / `revoked` / `recalled` / `delisted` / `blocked` / `owner_missing` / `unauthorized` / `needs_recheck` | +| `source_status` | SourceStatus：`active` / `stale` / `revoked` / `recalled` / `delisted` / `blocked` / `owner_missing` / `unauthorized` | | `license_restriction_snapshot` | 导出、二次分发、AI 上下文等限制 | 约束： @@ -319,18 +321,18 @@ Block revision 历史。 - 规划候选未确认前不得进入正式生成上下文。 - Narrative State 需要真实持久化载体，不能只靠 MetaSchema 表达。 -### 4.7 MetaSchema 表 +### 4.7 MetaSchema 表（归属 `yudao-module-meta` 独立模块） -MetaSchema 是 Admin/Governance 逻辑 owner 的元结构定义，由管理后台配置、影响预览、发布、激活和回滚，但它不是管理员私有数据，也不是某个页面表单的临时状态。阶段 7 可以由 `yudao-module-content` 物理承载基础表，按 `domain / scope / target_type` 服务作品、规划、知识和 AI 上下文；物理表放在 content 不代表 Content app/admin API 可以任意改结构。 +MetaSchema 是独立模块 `yudao-module-meta` 的元结构定义，由管理后台配置、影响预览、发布、激活和回滚，但它不是管理员私有数据，也不是某个页面表单的临时状态。`yudao-module-meta` 按 `domain / scope / target_type` 服务作品、规划、知识和 AI 上下文；Content、Knowledge、AI 等模块通过 facade-api 只读消费。 | 表 | 职责 | |---|---| -| `muse_content_meta_schema` | 元结构根对象，包含 schema_key、domain、scope、target_type、当前激活版本和适用范围 | -| `muse_content_meta_field` | 字段定义、类型、必填、枚举、引用、排序和校验规则 | -| `muse_content_meta_visibility_policy` | `uiVisible`、`aiContext`、`userEditable`、`userSearchable`、`exportable` 等可见性策略 | -| `muse_content_meta_schema_version` | 发布版本、激活状态、灰度、回滚和影响预览摘要 | +| `muse_meta_schema` | 元结构根对象，包含 schema_key、domain、scope、target_type、当前激活版本和适用范围 | +| `muse_meta_field` | 字段定义、类型、必填、枚举、引用、排序和校验规则 | +| `muse_meta_visibility_policy` | `uiVisible`、`aiContext`、`userEditable`、`userSearchable`、`exportable` 等可见性策略 | +| `muse_meta_schema_version` | 发布版本、激活状态、灰度、回滚和影响预览摘要 | -`muse_content_meta_schema` 字段合同： +`muse_meta_schema` 字段合同： | 字段语义 | 要求 | |---|---| @@ -342,11 +344,11 @@ MetaSchema 是 Admin/Governance 逻辑 owner 的元结构定义，由管理后 | `effective_scope` | 适用范围摘要，至少能表达全局、租户、用户、作品、类型灰度 | | `projection_version` | 当前读模型或运行时缓存使用的投影版本 | -`muse_content_meta_schema_version` 字段合同： +`muse_meta_schema_version` 字段合同： | 字段语义 | 要求 | |---|---| -| `schema_id` | 关联 `muse_content_meta_schema` | +| `schema_id` | 关联 `muse_meta_schema` | | `schema_key` | 冗余稳定键，便于审计和跨版本查询 | | `version_no` | 单调递增版本号，同一 `schema_key` 下唯一 | | `status` | `draft` / `reviewing` / `published` / `active` / `disabled` / `archived` / `rolled_back` | @@ -361,13 +363,13 @@ MetaSchema 是 Admin/Governance 逻辑 owner 的元结构定义，由管理后 约束： -- MetaSchema 写入入口只能是 `/admin-api/muse/governance/**` 经 Governance/Admin facade；Content 只提供受控的 meta application service 和版本化投影。 +- MetaSchema 写入入口只能是 `/admin-api/muse/governance/**` 经 `yudao-module-meta`；Content 等模块只能通过 meta facade-api 消费只读投影。 - Content / app API 只能读取 active/gray 投影并在目标 owner 命令中校验，不能创建、发布、激活、回滚或废弃 Schema。 - 管理员配置 MetaSchema 不等于修改用户作品内容、Local KB 或用户知识库资料。 - MetaSchema 不能把系统保护节点重新分类为开放槽位。 - `uiVisible=false` 不等于不能进 AI 上下文；`aiContext=true` 不等于用户可见；`exportable=true` 仍必须受 owner、授权、来源状态和导出许可约束。 - 后端必须在可见投影、保存、检索、AI 上下文组装和导出预检中重复校验 MetaSchema 策略，不能只靠前端隐藏字段。 -- 唯一键：`muse_content_meta_schema(domain, scope, target_type, schema_key)`；版本唯一键：`muse_content_meta_schema_version(schema_key, version_no)`。 +- 唯一键：`muse_meta_schema(domain, scope, target_type, schema_key)`；版本唯一键：`muse_meta_schema_version(schema_key, version_no)`。 - 激活唯一约束：同一 `schema_key + effective_scope` 仅允许一条 `active_flag = true` 的版本；物理库不支持部分唯一索引时，由状态机事务和唯一辅助列共同保证。 - 发布前必须写 `impact_preview_snapshot`；回滚必须保留 from / to 版本，不能覆盖原版本记录。 @@ -444,8 +446,28 @@ MetaSchema 是 Admin/Governance 逻辑 owner 的元结构定义，由管理后 | `muse_knowledge_chunk` | 系统拆分切块结果 | | `muse_knowledge_processing_job` | 解析、切块、索引、入 RAG、重建投影任务 | +`muse_knowledge_document_version` 字段合同： + +| 字段语义 | 要求 | +|---|---| +| `document_id` | 关联 `muse_knowledge_document` | +| `version_no` | 同一 document 下单调递增版本号 | +| `content_hash` | 版本内容 hash，用于 stale 检测和去重 | +| `source_snapshot_id` | 来源快照 | +| `processing_status` | `pending` / `processing` / `completed` / `failed` | +| `previous_version_id` | 前版本引用（BIGINT），指向同一 document 的上一个版本记录，首版本为空 | +| `change_summary` | 变更摘要（JSON），记录与前版本的差异概要，包含 `addedSections`、`removedSections`、`modifiedSections`、`diffStats` 等结构化信息 | +| `change_reason` | 变更原因（VARCHAR(500)），记录本次版本变更的业务原因，例如"修正角色设定冲突"、"补充第三章背景资料"等 | + 约束： +- `previous_version_id` 必须指向同一 `document_id` 下已存在的版本记录，或为空（首版本）。 +- `change_summary` 在非首版本时建议必填，由处理任务自动生成或用户手动填写。 +- `change_reason` 在非首版本时建议必填，便于审计和版本回溯。 +- 版本差异追踪不替代 chunk 级别的增量重建策略；处理任务可基于 `change_summary` 优化增量切块和索引。 + +通用约束： + - 拆分切块和入 RAG 是系统保护节点，不允许用户智能体替换。 - 处理失败的资料不得进入正式检索和生成上下文。 - Chunk 只服务检索和解释，不是正式作品事实。 @@ -464,13 +486,18 @@ Local KB Canonical 必要来源字段： | 字段语义 | 要求 | |---|---| | `work_id` | 所属作品 | +| `entity_type` | 实体类型，例如 `character` / `location` / `item` / `concept` | +| `normalized_name` | 标准化名称 | +| `scope` | 作用域，例如 `global` / `chapter:{chapterId}` / `arc:{arcId}`，用于区分同名实体在不同范围的含义 | | `source_snapshot_id` | 最近一次确认或修正所依据的来源快照 | | `authorization_snapshot_id` | 确认时的授权快照 | -| `source_status` | `active` / `stale` / `revoked` / `recalled` / `blocked` / `owner_missing` / `unauthorized` / `needs_recheck` | -| `source_action_policy` | `allowed` / `blocked` / `needs_recheck` | +| `source_status` | `active` / `stale` / `revoked` / `recalled` / `blocked` / `owner_missing` / `unauthorized` | +| `source_action_policy` | `allowed` / `read_only` / `blocked` / `needs_recheck`（注：needs_recheck 是 ActionPolicy 层面的动作策略结论，表示"下次使用时需要重新校验"，不是 SourceStatus 枚举值。SourceStatus 不含 needs_recheck，来源变化时直接决策 active 或 disabled） | | `source_event_version` | 最近已消费的来源事件版本 | | `lineage_payload` | 派生链路摘要，不保存敏感全文 | +唯一键：`(work_id, entity_type, normalized_name, scope)`。 + 约束： - Local KB 不需要单独容器表，由 `work_id` 归属表达。 @@ -512,7 +539,7 @@ Local KB Canonical 必要来源字段： | `source_snapshot_id` | 绑定时的来源快照 | | `authorization_snapshot_id` | 绑定时的授权快照 | | `binding_scope` | `read` / `generation_context` / `parse_context` / `export` | -| `binding_status` | SourceStatus / binding 状态投影：`active` / `stale` / `revoked` / `recalled` / `delisted` / `blocked` / `owner_missing` / `unauthorized` / `needs_recheck` / `disabled` | +| `binding_status` | SourceStatus / binding 状态投影：`active` / `stale` / `revoked` / `recalled` / `delisted` / `blocked` / `owner_missing` / `unauthorized` / `disabled` | | `target_version` | 绑定目标版本，供来源事件传播和幂等重验 | 约束： @@ -523,7 +550,13 @@ Local KB Canonical 必要来源字段： ## 6. Source / Authorization Schema -Source / Authorization 是独立一级 Schema，不属于 Knowledge 子章节。它承接跨 Content、Knowledge、AI、Market、Account 的来源快照、授权快照、来源状态事件和传播目标，避免每个业务模块各自保存一份“当前授权通过”的临时布尔值。 +Source / Authorization 是独立一级 Schema，不属于 Knowledge 子章节。它承接跨 Content、Knowledge、AI、Market、Account 的来源快照、授权快照、来源状态事件和传播目标，避免每个业务模块各自保存一份”当前授权通过”的临时布尔值。 + +物理归属： + +- `source_snapshot` 表 DDL 归 `yudao-module-infra` 模块（横切基础设施表）。 +- 各业务模块（content、knowledge、ai、market、account）分散写入 source_snapshot 记录。 +- 传播模式为事件驱动自治：通过 Spring Event 或 MQ 发布来源状态事件，各模块自行监听并处理自己 owner 范围内的传播目标。 ### 6.1 `muse_source_snapshot` @@ -536,7 +569,7 @@ Source / Authorization 是独立一级 Schema，不属于 Knowledge 子章节。 | `source_object_id` | 来源对象 ID | | `source_version` | 来源版本，例如 Block revision、资料版本、资产版本或候选版本 | | `source_hash` | 来源内容 hash，用于 stale 检测 | -| `source_status` | SourceStatus：`active` / `stale` / `revoked` / `recalled` / `delisted` / `blocked` / `owner_missing` / `unauthorized` / `needs_recheck` | +| `source_status` | SourceStatus：`active` / `stale` / `revoked` / `recalled` / `delisted` / `blocked` / `owner_missing` / `unauthorized` | | `owner_user_id` / `tenant_id` | 来源 owner 上下文；系统或全局来源可以为空但必须有系统 owner 标记 | | `lineage_payload` | 派生链路摘要，不保存敏感全文 | | `evidence_payload` | 权利声明、导入材料、检查摘要或外部引用摘要 | @@ -558,7 +591,7 @@ Source / Authorization 是独立一级 Schema，不属于 Knowledge 子章节。 | `actor_user_id` | 发起用户或系统服务身份 | | `authorization_purpose` | `read` / `generate` / `bind` / `confirm_draft` / `accept_candidate` / `export` / `download` / `publish` / `evaluate` | | `authorization_scope` | 可用范围摘要，至少表达 work / chapter / kb / asset / account 范围 | -| `authorization_status` | `allowed` / `denied` / `expired` / `revoked` / `needs_recheck` | +| `authorization_status` | `allowed` / `denied` / `expired` / `revoked` | | `expires_at` | 授权过期时间；长期授权也必须明确策略来源 | | `license_restriction_snapshot` | 导出、二次分发、AI 上下文、市场发布等限制 | | `policy_version` | 授权策略版本 | @@ -581,7 +614,7 @@ Source / Authorization 是独立一级 Schema，不属于 Knowledge 子章节。 | `source_snapshot_id` | 受影响来源快照 | | `event_type` | SourceEventType：`source_updated` / `source_revoked` / `asset_recalled` / `asset_delisted` / `asset_blocked` / `owner_missing` / `license_changed` / `authorization_expired` / `authorization_revoked` / `processing_failed` / `recheck_required` | | `source_status_after` | 本事件应用后的 SourceStatus，不得只用 event type 推断 | -| `action_policy_after` | SourceActionPolicy：`allowed` / `read_only` / `blocked` / `needs_recheck` | +| `action_policy_after` | SourceActionPolicy：`allowed` / `read_only` / `blocked` / `needs_recheck`（注：needs_recheck 是 ActionPolicy 层面的动作策略结论，不是 SourceStatus 枚举值） | | `event_version` | 同一来源事件版本，单调递增 | | `event_status` | `pending` / `propagating` / `completed` / `partially_failed` / `failed` | | `reason_code` / `reason_message` | 状态变化原因摘要 | @@ -606,7 +639,7 @@ SourceEventType 到状态策略的默认映射： | `asset_blocked` | `blocked` | `blocked` | | `owner_missing` | `owner_missing` | `blocked` | | `authorization_expired` / `authorization_revoked` | `unauthorized` | `blocked` | -| `license_changed` / `processing_failed` / `recheck_required` | `needs_recheck` | `needs_recheck` | +| `license_changed` / `processing_failed` / `recheck_required` | `stale` | `needs_recheck` | ### 6.4 `muse_source_propagation_target` @@ -813,7 +846,7 @@ SourceEventType 到状态策略的默认映射： - Candidate Decision Archive 只证明用户对候选的处理，不证明知识草稿已确认。 - 质量门控可以在 Shadow 内有限重写候选，但不能替用户确认正文或知识。 -`muse_ai_candidate_decision_archive` 必须由 AI decision archive service 单一写入，字段至少包含 `candidate_id`、`decision_envelope_version`、`decision_type`、`quality_result_version`、`output_compliance_result_id`、`static_check_result_id`、`source_snapshot_id`、`authorization_snapshot_id`、`source_status`、`market_feature_gate`、`work_asset_use_precheck_id`、`expected_revision`、`idempotency_key`、`blocked_reason_payload` 和 `audit_event_id`。Content Accept 成功后只保存 `decision_id` 引用；失败时不得创建可误认为已接受的归档。 +`muse_ai_candidate_decision_archive` 必须由 AI decision archive service 单一写入，字段至少包含 `candidate_id`、`decision_type`、`quality_result_version`、`output_compliance_result_id`、`static_check_result_id`、`source_snapshot_id`、`source_version`、`authorization_snapshot_id`、`source_status`、`market_feature_gate`、`work_asset_use_precheck_id`、`expected_revision`、`idempotency_key`、`blocked_reason_payload` 和 `audit_event_id`。候选记录 `source_version`，接受时实时对比当前来源版本。Content Accept 成功后只保存 `decision_id` 引用；失败时不得创建可误认为已接受的归档。 ## 8. Marketplace Schema @@ -891,34 +924,35 @@ SourceEventType 到状态策略的默认映射： - 下架、召回、blocked 必须产生 Source Status Event。 - 管理员拥有系统级治理能力，但不替用户修改已购买或私有资产内容。 -## 9. Account Schema +## 9. Account Schema（物理承载：`yudao-module-member`） -是否新增 `yudao-module-account`，还是改造 `member`，后端落地前需要单独决策。无论物理模块如何选择，账户相关 Schema 只保存 Muse 创作系统所需的权益、用量和聚合视图。 +已决策：Account BC 由 `yudao-module-member` 承载，不新增 `yudao-module-account`。表前缀统一使用 `muse_member_`，与 member 模块对齐。 | 表 | 职责 | |---|---| -| `muse_account_profile_ext` | Muse 展示名、创作偏好入口等扩展资料 | -| `muse_account_preference` | 用户偏好、通知偏好、创作辅助偏好 | -| `muse_account_new_api_binding` | Muse 用户和 New-API 网关用户绑定摘要 | -| `muse_account_entitlement_snapshot` | 套餐、配额、余额或外部网关权益的本地快照 | -| `muse_account_entitlement_ledger` | 权益变更 append-only 流水，承接购买、赠送、到期、撤销和管理员调额结果 | -| `muse_account_quota_request` | 向 New-API 或本地权益服务发起的额度配置/同步请求 | -| `muse_account_quota_adjustment` | 管理员调额请求记录，支持幂等、原因、前后值和审计 | -| `muse_account_usage_record` | 生成、检索、评估、导出等任务级用量归属摘要 | -| `muse_account_call_attribution_job` | New-API 调用归属、补偿和用户可见解释任务 | -| `muse_account_asset_summary` | 个人中心资产摘要读模型 | -| `muse_account_security_event` | 登录、敏感导出、凭证失效、异常访问等安全事件摘要 | -| `muse_account_export_task` | 个人资料、安全事件或账户记录导出任务 | +| `muse_member_profile_ext` | Muse 展示名、创作偏好入口等扩展资料 | +| `muse_member_preference` | 用户偏好、通知偏好、创作辅助偏好 | +| `muse_member_new_api_binding` | Muse 用户和 New-API 网关用户绑定摘要 | +| `muse_member_entitlement_snapshot` | 套餐、配额、余额或外部网关权益的本地快照 | +| `muse_member_entitlement` | 用户当前权益可变表，直接更新当前状态；所有变更写入 `muse_member_entitlement_audit_log` 审计日志 | +| `muse_member_entitlement_audit_log` | 权益变更审计日志，记录每次变更的操作者、原因、前后值和来源，用于追溯和合规 | +| `muse_member_quota_request` | 向 New-API 或本地权益服务发起的额度配置/同步请求 | +| `muse_member_quota_adjustment` | 管理员调额请求记录，支持幂等、原因、前后值和审计 | +| `muse_member_usage_record` | 生成、检索、评估、导出等任务级用量归属摘要 | +| `muse_member_call_attribution_job` | New-API 调用归属、补偿和用户可见解释任务 | +| `muse_member_asset_summary` | 个人中心资产摘要读模型 | +| `muse_member_security_event` | 登录、敏感导出、凭证失效、异常访问等安全事件摘要 | +| `muse_member_export_task` | 个人资料、安全事件或账户记录导出任务 | New-API 绑定、额度和调用归属最小字段： | 表 | 必要字段 | |---|---| -| `muse_account_new_api_binding` | `account_user_id`、`gateway_user_ref`、`binding_status`、`last_recheck_at`、`correlation_id`、`idempotency_key`、`failure_code` | -| `muse_account_quota_request` | `account_user_id`、`request_type`、`requested_value_snapshot`、`correlation_id`、`idempotency_key`、`request_status`、`retry_group`、`failure_code` | -| `muse_account_call_attribution_job` | `account_user_id`、`ai_task_id`、`gateway_request_id`、`correlation_id`、`source_owner`、`source_id`、`attribution_status`、`retry_group`、`compensation_status`、`failure_code` | +| `muse_member_new_api_binding` | `account_user_id`、`gateway_user_ref`、`binding_status`、`last_recheck_at`、`correlation_id`、`idempotency_key`、`failure_code` | +| `muse_member_quota_request` | `account_user_id`、`request_type`、`requested_value_snapshot`、`correlation_id`、`idempotency_key`、`request_status`、`retry_group`、`failure_code` | +| `muse_member_call_attribution_job` | `account_user_id`、`ai_task_id`、`gateway_request_id`、`correlation_id`、`source_owner`、`source_id`、`attribution_status`、`retry_group`、`compensation_status`、`failure_code` | -`muse_account_quota_adjustment` 字段合同： +`muse_member_quota_adjustment` 字段合同： | 字段语义 | 要求 | |---|---| @@ -927,32 +961,39 @@ New-API 绑定、额度和调用归属最小字段： | `idempotency_key` | 管理员调额幂等键，同一管理员动作唯一 | | `reason_code` / `reason_message` | 调整原因，必须可审计 | | `before_value_snapshot` / `after_value_snapshot` | 调整前后权益或配额摘要 | -| `ledger_entry_id` | 调整落账后的权益流水引用 | +| `ledger_entry_id` | 调整落账后的审计日志引用 | | `status` | `pending` / `applied` / `rejected` / `canceled` | | `approved_by` / `applied_by` | 审批人和执行人 | | `audit_event_id` | 高危动作审计引用 | -`muse_account_entitlement_ledger` 字段合同： +`muse_member_entitlement_audit_log` 字段合同： | 字段语义 | 要求 | |---|---| | `account_user_id` | 账户 owner | -| `ledger_type` | `purchase` / `admin_adjustment` / `usage_debit` / `refund` / `expiration` / `revoke` / `sync_correction` | +| `change_type` | `purchase` / `admin_adjustment` / `usage_debit` / `refund` / `expiration` / `revoke` / `sync_correction` | | `source_owner` / `source_id` | 来源 owner 和来源记录，例如支付订单、调额记录或外部同步记录 | -| `idempotency_key` | 落账幂等键 | +| `idempotency_key` | 变更幂等键 | | `before_value_snapshot` / `delta_value_snapshot` / `after_value_snapshot` | 前值、变更值和后值 | | `reason_code` / `reason_message` | 业务原因 | +| `operator_user_id` | 操作者（系统、管理员或用户自身） | | `audit_event_id` | 审计事件引用 | +Entitlement 存储模式说明： + +- `muse_member_entitlement` 是可变表，直接反映用户当前权益状态（套餐、配额、余额等），支持高效查询和前置检查。 +- `muse_member_entitlement_audit_log` 是审计日志表，记录每次权益变更的完整上下文，用于追溯、合规和争议处理。 +- 不采用 append-only ledger 模式；错误调整通过反向变更 + 审计日志记录，直接更新可变表状态。 + 约束： -- `muse_account_usage_record` 不是 New-API 成本账本 authority。 -- `muse_account_entitlement_ledger` 和 `muse_account_quota_adjustment` 均为 append-only；错误调整必须用反向流水或撤销记录补偿，不能覆盖原记录。 +- `muse_member_usage_record` 不是 New-API 成本账本 authority。 +- `muse_member_entitlement` 是可变表，`muse_member_entitlement_audit_log` 记录所有变更历史；`muse_member_quota_adjustment` 记录管理员调额请求。 - 管理员调额必须写幂等键、原因、前后值、操作者和审计事件。 -- Pay callback、refund、套餐撤销和市场补偿必须按 `source_owner + source_id + idempotency_key` 落到 entitlement ledger；重复回调返回同一处理结果，退款或补偿用反向流水，不覆盖原流水。 +- Pay callback、refund、套餐撤销和市场补偿必须按 `source_owner + source_id + idempotency_key` 写入审计日志并更新可变表；重复回调返回同一处理结果。 - New-API binding、quota request 和 call attribution 只保存 Muse 任务、用户权益和失败恢复需要的引用、correlationId、幂等键和状态，不保存 Provider、供应商路由、成本账本或原始调用日志 authority。 - 个人中心是 read model 和跳转入口，不反写作品、知识、市场资产或 AI 任务事实。 -- 账户导出只能导出个人中心 owner 范围内的数据，并记录下载审计；`muse_account_export_task` 是 API 必须承接的 Schema 落点，接口层应提供创建、轮询、取消和下载凭证领取。 +- 账户导出只能导出个人中心 owner 范围内的数据，并记录下载审计；`muse_member_export_task` 是 API 必须承接的 Schema 落点，接口层应提供创建、轮询、取消和下载凭证领取。 ## 10. Audit、Outbox 与 Integration @@ -993,7 +1034,7 @@ Owner 约束： | 入 RAG 不反写事实 | `muse_knowledge_processing_job` / `muse_projection_task` 只产投影和索引 | | 导出必须重验来源许可 | Export Task + Download Credential + Authorization Snapshot | | 管理员不替用户确认私有事实 | Admin 接口只写配置、治理和审计；Content/Knowledge 决策命令必须校验 owner 用户 | -| 管理员调额必须可追溯 | `muse_account_quota_adjustment` + `muse_account_entitlement_ledger` append-only，保留幂等键、原因、前后值和审计 | +| 管理员调额必须可追溯 | `muse_member_quota_adjustment` + `muse_member_entitlement_audit_log`，保留幂等键、原因、前后值和审计 | ## 12. 索引策略 @@ -1008,14 +1049,14 @@ Owner 约束： - 解析结果：`parse_job_id + chapter_id + review_status`。 - 当前候选：`work_id + status + create_time`。 - 知识草稿：`work_id + status + update_time`。 -- Local KB 检索：`work_id + entity_type + name`。 +- Local KB 检索：`work_id + entity_type + normalized_name + scope`。 - 用户知识库：`owner_user_id + status + update_time`。 - 来源传播：`event_key`、`target_owner + target_type + target_id + propagation_status`。 - 市场资产：`asset_type + listing_status + category + update_time`。 - 市场收藏：`user_id + status + update_time`、`user_id + asset_id`。 - 授权/安装：`user_id + asset_type + status`。 - 任务轮询：`actor_user_id + task_type + status + update_time`。 -- 账户权益流水：`account_user_id + create_time`、`idempotency_key`。 +- 账户权益审计日志：`account_user_id + create_time`、`idempotency_key`。 ### 12.2 唯一性 @@ -1026,9 +1067,9 @@ Owner 约束： - `muse_content_block_revision(block_id, revision)`。 - `muse_ai_parse_job(idempotency_key)`。 - `muse_ai_chapter_parse_result(parse_job_id, chapter_id, result_type)`。 -- `muse_content_meta_schema(domain, scope, target_type, schema_key)`。 -- `muse_content_meta_schema_version(schema_key, version_no)`。 -- `muse_knowledge_entity(work_id, entity_type, normalized_name)`。 +- `muse_meta_schema(domain, scope, target_type, schema_key)`。 +- `muse_meta_schema_version(schema_key, version_no)`。 +- `muse_knowledge_entity(work_id, entity_type, normalized_name, scope)`。 - `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)`。 @@ -1041,16 +1082,16 @@ Owner 约束： - `muse_market_install(user_id, asset_id, asset_version_id)`。 - `muse_market_collection(user_id, asset_id)` 仅约束 `status = active` 的收藏记录。 - `muse_market_bind_precheck(precheck_id)`。 -- `muse_account_new_api_binding(account_user_id)`。 -- `muse_account_quota_request(idempotency_key)`。 -- `muse_account_call_attribution_job(correlation_id, gateway_request_id)`。 -- `muse_account_quota_adjustment(idempotency_key)`。 -- `muse_account_entitlement_ledger(idempotency_key)`。 +- `muse_member_new_api_binding(account_user_id)`。 +- `muse_member_quota_request(idempotency_key)`。 +- `muse_member_call_attribution_job(correlation_id, gateway_request_id)`。 +- `muse_member_quota_adjustment(idempotency_key)`。 +- `muse_member_entitlement_audit_log(idempotency_key)`。 - `muse_outbox_event(event_key)`。 激活唯一约束： -- MetaSchema：同一 `schema_key + effective_scope` 仅一条 `active_flag = true` 的 `muse_content_meta_schema_version`。 +- 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`。 - Quality Policy：同一 `policy_id + effective_scope` 仅一条 `active_flag = true` 的 `muse_ai_quality_policy_version`。 @@ -1058,6 +1099,26 @@ Owner 约束： 结构化 JSON 字段默认不作为复杂查询主路径。凡是进入筛选、排序、权限、状态机或审计的字段，必须提取成显式列或读模型字段。 +### 12.4 Archive 存储策略 + +候选归档（Candidate Decision Archive）、知识草稿归档和任务归档采用同表 + status 模式： + +- 归档记录与活跃记录存储在同一张表中，通过 `status` 字段区分（例如 `active` / `archived` / `expired` / `invalidated`）。 +- 不单独创建 archive 表或分区表。 +- 热路径查询通过 `status` 索引过滤归档记录，保证活跃数据查询性能。 +- 归档记录保留完整上下文（来源快照、授权快照、质量结果、决策类型），用于审计和追溯。 +- 数据量增长后可通过数据库分区（按时间或状态）优化，但逻辑上仍是同一张表。 + +### 12.5 API 版本策略 + +API 版本通过 HTTP Header 传递，路由路径不变： + +- Header：`X-API-Version: 1`（当前版本为 1）。 +- 服务端根据 header 值返回对应版本的响应结构。 +- 未传 header 时默认使用最新稳定版本。 +- Deprecation Policy：旧版本至少保留 6 个月，期间返回 `Deprecation` 响应头提示迁移；到期后返回 `API_VERSION_DEPRECATED` 错误码。 +- 版本变更只影响响应结构和字段语义，不影响路由路径和认证方式。 + ## 13. 迁移与 SQL 文件口径 ### 13.1 迁移策略 @@ -1076,7 +1137,7 @@ Owner 约束： 目标 SQL 必须等以下事项确认后重新生成： -1. `account` 是新增模块还是改造 `member`。 +1. `account` 模块选择：已决策，使用 `yudao-module-member` 承载。 2. 目标数据库类型和 Yudao migration 方式。 3. 是否启用 Yudao 多租户字段。 4. 物理外键策略。 diff --git a/design-docs/后端-04a-完整建表SQL.sql b/design-docs/后端-04a-完整建表SQL.sql index fccfb047..290549a2 100644 --- a/design-docs/后端-04a-完整建表SQL.sql +++ b/design-docs/后端-04a-完整建表SQL.sql @@ -1,35 +1,334 @@ -- ============================================================ --- Muse 后端-04a：完整建表 SQL（历史快照说明） --- 更新日期：2026-05-23 --- 状态：阶段 7 已废弃为目标建表 SQL，禁止直接执行 +-- Muse 后端-04a：核心业务建表 SQL（第一批） +-- 更新日期：2026-05-24 +-- 目标数据库：MySQL 8.0+ +-- 状态：需要与后端-04 Schema 文档对齐，当前为旧实现快照 -- ============================================================ -- --- 重要结论： --- 1. 本文件原内容来自旧 `services/muse-engine` Flyway V1-V18 合并快照， --- 使用 UUID、BIGSERIAL、PostgreSQL JSONB、S0-ID 和旧自研单体口径。 --- 2. 阶段 7 的后端工程基线已调整为 `YunaiV/yudao-cloud` fork： --- - 后端复用 Yudao Cloud 的 gateway、system、infra、framework、job、log、file、config 等能力。 --- - 管理后台调用 `/admin-api/**`。 --- - 用户端 `muse-studio` 调用 `/app-api/**`。 --- - Muse 业务表按 content、knowledge、ai、market、account 等模块新增。 --- 3. 因此，旧 SQL 不再是目标库的完整建表 SQL，也不能直接搬到 `yudao-cloud`。 +-- !! 重要说明 !! +-- 本文件当前内容为旧实现快照，尚未与最新的后端-04 Schema 文档对齐。 +-- 已知差异包括但不限于： +-- 1. Entitlement 模型已改为可变表 + 审计日志（非 append-only ledger） +-- 2. MetaSchema 表已迁移至独立 yudao-module-meta 模块（表前缀改为 muse_meta_） +-- 3. 知识实体唯一键已加 scope 字段 +-- 4. Candidate Decision Envelope 已去掉，简化为候选记录 source_version +-- 5. needs_recheck 已从 SourceStatus 枚举中移除 +-- 6. source_snapshot 表 DDL 归属已改为 infra 模块 +-- 7. API 版本策略已确定为 X-API-Version header 方式 +-- 请勿直接执行到 yudao-cloud 目标库，需等后端-04 完全确认后重新生成。 -- --- 禁止用途： --- - 不允许把本文件作为 `yudao-cloud` 目标库初始化脚本执行。 --- - 不允许以本文件的 UUID/BIGSERIAL/JSONB/S0-ID 设计反向覆盖 `后端-04`。 --- - 不允许在本文件上继续补旧 `muse-engine` 风格 DDL，然后声称已适配 Yudao。 --- --- 允许用途： --- - 作为旧实现快照的迁移对照。 --- - 用于检查哪些旧字段语义需要在新 `后端-04` 中被保留、改名或废弃。 --- - 用于后续生成 Yudao migration 时做差异提醒。 --- --- 新目标 SQL 生成前置条件： --- 1. `后端-04-统一数据库Schema-v1.md` 的模块 owner 和表清单确认。 --- 2. 确认 account 是新增 `yudao-module-account`，还是改造 `yudao-module-member`。 --- 3. 确认目标数据库类型、Yudao migration 工具、物理外键策略和多租户字段策略。 --- 4. 确认 JSON 字段的物理类型和 MyBatis TypeHandler。 --- 5. 按 Yudao 模块分别生成 migration，不再维护一个跨模块手写大 SQL。 --- --- 当前文件刻意不保留任何可执行 DDL，避免误建旧库。 -- ============================================================ + +-- ============================================================ +-- 一、Member 模块（Account BC 物理承载）的 Muse 扩展表 +-- ============================================================ + +-- 用户画像/偏好扩展 +CREATE TABLE `muse_member_profile` ( + `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键', + `user_id` BIGINT NOT NULL COMMENT '用户ID，引用 Yudao system_users', + `display_name` VARCHAR(100) DEFAULT NULL COMMENT 'Muse 展示名', + `avatar_url` VARCHAR(500) DEFAULT NULL COMMENT '头像URL', + `bio` VARCHAR(500) DEFAULT NULL COMMENT '个人简介', + `writing_preference` JSON DEFAULT NULL COMMENT '创作偏好（JSON）', + `notification_preference` JSON DEFAULT NULL COMMENT '通知偏好（JSON）', + `creator` VARCHAR(64) DEFAULT '' COMMENT '创建者', + `create_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + `updater` VARCHAR(64) DEFAULT '' COMMENT '更新者', + `update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + `deleted` BIT(1) NOT NULL DEFAULT b'0' COMMENT '是否删除', + `tenant_id` BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + PRIMARY KEY (`id`), + UNIQUE KEY `uk_user_id` (`user_id`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='Muse 用户画像扩展（member 模块）'; + +-- 用户权益 +CREATE TABLE `muse_member_entitlement` ( + `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键', + `user_id` BIGINT NOT NULL COMMENT '用户ID', + `plan_type` VARCHAR(50) NOT NULL COMMENT '套餐类型：free/basic/pro/enterprise', + `plan_started_at` DATETIME DEFAULT NULL COMMENT '套餐开始时间', + `plan_expires_at` DATETIME DEFAULT NULL COMMENT '套餐过期时间', + `ai_call_quota` INT NOT NULL DEFAULT 0 COMMENT 'AI 调用配额（次/月）', + `ai_call_used` INT NOT NULL DEFAULT 0 COMMENT 'AI 调用已用量', + `storage_quota_mb` BIGINT NOT NULL DEFAULT 0 COMMENT '存储配额（MB）', + `storage_used_mb` BIGINT NOT NULL DEFAULT 0 COMMENT '存储已用量（MB）', +-- PLACEHOLDER_SQL_PART2 + `kb_count_quota` INT NOT NULL DEFAULT 0 COMMENT '知识库数量配额', + `work_count_quota` INT NOT NULL DEFAULT 0 COMMENT '作品数量配额', + `export_quota` INT NOT NULL DEFAULT 0 COMMENT '导出配额（次/月）', + `features_json` JSON DEFAULT NULL COMMENT '功能开关集合（JSON）', + `creator` VARCHAR(64) DEFAULT '' COMMENT '创建者', + `create_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + `updater` VARCHAR(64) DEFAULT '' COMMENT '更新者', + `update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + `deleted` BIT(1) NOT NULL DEFAULT b'0' COMMENT '是否删除', + `tenant_id` BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + PRIMARY KEY (`id`), + UNIQUE KEY `uk_user_id` (`user_id`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='Muse 用户权益（member 模块）'; + +-- 用户配额 +CREATE TABLE `muse_member_quota` ( + `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键', + `user_id` BIGINT NOT NULL COMMENT '用户ID', + `quota_type` VARCHAR(50) NOT NULL COMMENT '配额类型：ai_call/storage/kb_count/work_count/export', + `total_amount` BIGINT NOT NULL DEFAULT 0 COMMENT '总配额', + `used_amount` BIGINT NOT NULL DEFAULT 0 COMMENT '已使用量', + `reset_cycle` VARCHAR(20) DEFAULT NULL COMMENT '重置周期：monthly/yearly/never', + `last_reset_at` DATETIME DEFAULT NULL COMMENT '上次重置时间', + `next_reset_at` DATETIME DEFAULT NULL COMMENT '下次重置时间', + `creator` VARCHAR(64) DEFAULT '' COMMENT '创建者', + `create_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + `updater` VARCHAR(64) DEFAULT '' COMMENT '更新者', + `update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + `deleted` BIT(1) NOT NULL DEFAULT b'0' COMMENT '是否删除', + `tenant_id` BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + PRIMARY KEY (`id`), + UNIQUE KEY `uk_user_quota_type` (`user_id`, `quota_type`), + KEY `idx_user_id` (`user_id`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='Muse 用户配额（member 模块）'; + +-- 用量记录 +CREATE TABLE `muse_member_usage_record` ( + `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键', + `user_id` BIGINT NOT NULL COMMENT '用户ID', + `usage_type` VARCHAR(50) NOT NULL COMMENT '用量类型：ai_generation/ai_parse/retrieval/export/evaluation', + `work_id` BIGINT DEFAULT NULL COMMENT '关联作品ID', + `task_id` BIGINT DEFAULT NULL COMMENT '关联任务ID', + `token_input` INT DEFAULT 0 COMMENT '输入 token 数', + `token_output` INT DEFAULT 0 COMMENT '输出 token 数', + `cost_reference` VARCHAR(100) DEFAULT NULL COMMENT '成本参考（非 authority，仅摘要）', + `gateway_request_id` VARCHAR(200) DEFAULT NULL COMMENT 'New-API 网关请求ID', +-- PLACEHOLDER_SQL_PART3 + `correlation_id` VARCHAR(200) DEFAULT NULL COMMENT '关联ID，用于去重和归属', + `status` VARCHAR(20) NOT NULL DEFAULT 'completed' COMMENT '状态：completed/failed/compensated', + `creator` VARCHAR(64) DEFAULT '' COMMENT '创建者', + `create_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + `updater` VARCHAR(64) DEFAULT '' COMMENT '更新者', + `update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + `deleted` BIT(1) NOT NULL DEFAULT b'0' COMMENT '是否删除', + `tenant_id` BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + PRIMARY KEY (`id`), + KEY `idx_user_create_time` (`user_id`, `create_time`), + KEY `idx_correlation_id` (`correlation_id`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='Muse 用量记录（member 模块）'; + +-- 安全事件 +CREATE TABLE `muse_member_security_event` ( + `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键', + `user_id` BIGINT NOT NULL COMMENT '用户ID', + `event_type` VARCHAR(50) NOT NULL COMMENT '事件类型：login_anomaly/credential_expired/sensitive_export/access_denied_burst/device_change/permission_escalation', + `severity` VARCHAR(20) NOT NULL DEFAULT 'info' COMMENT '严重级别：info/warning/critical', + `occurred_at` DATETIME NOT NULL COMMENT '事件发生时间', + `source_ip` VARCHAR(50) DEFAULT NULL COMMENT '来源IP', + `device_info` JSON DEFAULT NULL COMMENT '设备信息（JSON）', + `affected_scope` VARCHAR(200) DEFAULT NULL COMMENT '影响范围描述', + `description` VARCHAR(500) DEFAULT NULL COMMENT '事件描述', + `suggested_actions` JSON DEFAULT NULL COMMENT '建议处理措施（JSON数组）', + `acknowledged_at` DATETIME DEFAULT NULL COMMENT '用户确认时间', + `acknowledged_action` VARCHAR(50) DEFAULT NULL COMMENT '用户确认动作：acknowledged/password_changed/session_revoked/false_positive', + `acknowledge_note` VARCHAR(500) DEFAULT NULL COMMENT '用户确认备注', + `creator` VARCHAR(64) DEFAULT '' COMMENT '创建者', + `create_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + `updater` VARCHAR(64) DEFAULT '' COMMENT '更新者', + `update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + `deleted` BIT(1) NOT NULL DEFAULT b'0' COMMENT '是否删除', + `tenant_id` BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + PRIMARY KEY (`id`), + KEY `idx_user_occurred` (`user_id`, `occurred_at`), + KEY `idx_user_severity` (`user_id`, `severity`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='Muse 安全事件（member 模块）'; + +-- New-API 绑定 +CREATE TABLE `muse_member_api_binding` ( + `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键', + `user_id` BIGINT NOT NULL COMMENT '用户ID', + `gateway_user_ref` VARCHAR(200) NOT NULL COMMENT 'New-API 网关用户引用（不存明文 token）', + `binding_status` VARCHAR(20) NOT NULL DEFAULT 'active' COMMENT '绑定状态：active/expired/revoked/recheck_needed', +-- PLACEHOLDER_SQL_PART4 + `last_recheck_at` DATETIME DEFAULT NULL COMMENT '上次重验时间', + `correlation_id` VARCHAR(200) DEFAULT NULL COMMENT '关联ID', + `idempotency_key` VARCHAR(200) DEFAULT NULL COMMENT '幂等键', + `failure_code` VARCHAR(50) DEFAULT NULL COMMENT '失败错误码', + `failure_message` VARCHAR(500) DEFAULT NULL COMMENT '失败原因', + `creator` VARCHAR(64) DEFAULT '' COMMENT '创建者', + `create_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + `updater` VARCHAR(64) DEFAULT '' COMMENT '更新者', + `update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + `deleted` BIT(1) NOT NULL DEFAULT b'0' COMMENT '是否删除', + `tenant_id` BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + PRIMARY KEY (`id`), + UNIQUE KEY `uk_user_id` (`user_id`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='Muse New-API 绑定（member 模块）'; + +-- ============================================================ +-- 二、Content 模块核心表 +-- ============================================================ + +-- 作品 +CREATE TABLE `muse_content_work` ( + `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键', + `owner_user_id` BIGINT NOT NULL COMMENT '所属用户ID', + `title` VARCHAR(200) NOT NULL COMMENT '作品标题', + `genre` VARCHAR(50) DEFAULT NULL COMMENT '作品类型/体裁', + `summary` TEXT DEFAULT NULL COMMENT '作品简介', + `status` VARCHAR(20) NOT NULL DEFAULT 'writing' COMMENT '状态：writing/completed/archived', + `work_schema_id` BIGINT DEFAULT NULL COMMENT '关联 MetaSchema ID', + `import_status` VARCHAR(20) DEFAULT NULL COMMENT '导入摘要状态', + `parse_status` VARCHAR(20) DEFAULT NULL COMMENT '全书解析摘要状态', + `word_count` INT NOT NULL DEFAULT 0 COMMENT '总字数（读模型）', + `chapter_count` INT NOT NULL DEFAULT 0 COMMENT '章节数（读模型）', + `creator` VARCHAR(64) DEFAULT '' COMMENT '创建者', + `create_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + `updater` VARCHAR(64) DEFAULT '' COMMENT '更新者', + `update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + `deleted` BIT(1) NOT NULL DEFAULT b'0' COMMENT '是否删除', + `tenant_id` BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + PRIMARY KEY (`id`), + KEY `idx_owner_update` (`owner_user_id`, `update_time`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='Muse 作品（content 模块）'; + +-- 章节 +CREATE TABLE `muse_content_chapter` ( + `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键', + `work_id` BIGINT NOT NULL COMMENT '所属作品ID', + `title` VARCHAR(200) NOT NULL COMMENT '章节标题', + `order_no` INT NOT NULL COMMENT '章节排序', +-- PLACEHOLDER_SQL_PART5 + `status` VARCHAR(20) NOT NULL DEFAULT 'draft' COMMENT '状态：draft/writing/completed/archived', + `goal_snapshot` JSON DEFAULT NULL COMMENT '已确认规划摘要', + `outline_snapshot` JSON DEFAULT NULL COMMENT '大纲摘要', + `parse_review_status` VARCHAR(20) DEFAULT NULL COMMENT '全书解析章节审阅状态', + `creator` VARCHAR(64) DEFAULT '' COMMENT '创建者', + `create_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + `updater` VARCHAR(64) DEFAULT '' COMMENT '更新者', + `update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + `deleted` BIT(1) NOT NULL DEFAULT b'0' COMMENT '是否删除', + `tenant_id` BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + PRIMARY KEY (`id`), + UNIQUE KEY `uk_work_order` (`work_id`, `order_no`), + KEY `idx_work_id` (`work_id`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='Muse 章节（content 模块）'; + +-- 正文块 +CREATE TABLE `muse_content_block` ( + `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键', + `work_id` BIGINT NOT NULL COMMENT '所属作品ID', + `chapter_id` BIGINT NOT NULL COMMENT '所属章节ID', + `order_no` INT NOT NULL COMMENT '章节内排序', + `content_doc` JSON DEFAULT NULL COMMENT '富文本结构化内容（JSON）', + `revision` INT NOT NULL DEFAULT 1 COMMENT '乐观锁版本，保存正文必须带 expectedRevision', + `word_count` INT NOT NULL DEFAULT 0 COMMENT '当前字数', + `creator` VARCHAR(64) DEFAULT '' COMMENT '创建者', + `create_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + `updater` VARCHAR(64) DEFAULT '' COMMENT '更新者', + `update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + `deleted` BIT(1) NOT NULL DEFAULT b'0' COMMENT '是否删除', + `tenant_id` BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + PRIMARY KEY (`id`), + UNIQUE KEY `uk_chapter_order` (`chapter_id`, `order_no`), + KEY `idx_work_id` (`work_id`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='Muse 正文块（content 模块）'; + +-- 叙事运行态 +CREATE TABLE `muse_content_narrative_state` ( + `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键', + `work_id` BIGINT NOT NULL COMMENT '所属作品ID', + `chapter_id` BIGINT DEFAULT NULL COMMENT '章节ID（章节维度时填写）', + `entity_id` BIGINT DEFAULT NULL COMMENT '实体ID（实体维度时填写）', + `scope` VARCHAR(20) NOT NULL COMMENT '维度：work/chapter/entity', + `state_payload` JSON NOT NULL COMMENT '叙事运行态数据（JSON）', + `revision` INT NOT NULL DEFAULT 1 COMMENT '版本', + `creator` VARCHAR(64) DEFAULT '' COMMENT '创建者', + `create_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + `updater` VARCHAR(64) DEFAULT '' COMMENT '更新者', + `update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + `deleted` BIT(1) NOT NULL DEFAULT b'0' COMMENT '是否删除', + `tenant_id` BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + PRIMARY KEY (`id`), + KEY `idx_work_scope` (`work_id`, `scope`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='Muse 叙事运行态（content 模块）'; + +-- ============================================================ +-- 三、AI 模块核心表 +-- ============================================================ +-- PLACEHOLDER_SQL_PART6 + +-- AI 任务 +CREATE TABLE `muse_ai_task` ( + `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键', + `work_id` BIGINT DEFAULT NULL COMMENT '关联作品ID', + `chapter_id` BIGINT DEFAULT NULL COMMENT '关联章节ID', + `actor_user_id` BIGINT NOT NULL COMMENT '发起用户ID', + `task_type` VARCHAR(50) NOT NULL COMMENT '任务类型：generation/continuation/expansion/polish/detection/planning/parse/evaluation', + `agent_version_id` BIGINT DEFAULT NULL COMMENT '使用的 Agent 版本ID', + `runtime_envelope_id` BIGINT DEFAULT NULL COMMENT '运行时权限包ID', + `status` VARCHAR(20) NOT NULL DEFAULT 'queued' COMMENT '状态：queued/running/completed/failed/canceled', + `idempotency_key` VARCHAR(200) NOT NULL COMMENT '幂等键', + `input_snapshot` JSON DEFAULT NULL COMMENT '输入上下文摘要（不含敏感全文）', + `output_summary` JSON DEFAULT NULL COMMENT '输出摘要', + `error_code` VARCHAR(50) DEFAULT NULL COMMENT '失败错误码', + `error_message` VARCHAR(500) DEFAULT NULL COMMENT '失败原因', + `retry_count` INT NOT NULL DEFAULT 0 COMMENT '重试次数', + `started_at` DATETIME DEFAULT NULL COMMENT '开始执行时间', + `finished_at` DATETIME DEFAULT NULL COMMENT '完成时间', + `creator` VARCHAR(64) DEFAULT '' COMMENT '创建者', + `create_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + `updater` VARCHAR(64) DEFAULT '' COMMENT '更新者', + `update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + `deleted` BIT(1) NOT NULL DEFAULT b'0' COMMENT '是否删除', + `tenant_id` BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + PRIMARY KEY (`id`), + UNIQUE KEY `uk_idempotency_key` (`idempotency_key`), + KEY `idx_work_status` (`work_id`, `status`, `update_time`), + KEY `idx_actor_status` (`actor_user_id`, `task_type`, `status`, `update_time`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='Muse AI 任务（ai 模块）'; + +-- AI 候选 +CREATE TABLE `muse_ai_candidate` ( + `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键', + `work_id` BIGINT NOT NULL COMMENT '关联作品ID', + `chapter_id` BIGINT DEFAULT NULL COMMENT '关联章节ID', + `block_id` BIGINT DEFAULT NULL COMMENT '目标 Block ID', + `task_id` BIGINT NOT NULL COMMENT '来源任务ID', + `candidate_type` VARCHAR(50) NOT NULL COMMENT '候选类型：suggestion/planning_candidate', + `content_snapshot` JSON DEFAULT NULL COMMENT '候选内容快照', + `status` VARCHAR(20) NOT NULL DEFAULT 'pending' COMMENT '状态：pending/accepted/rejected/expired/invalidated', + `quality_result_id` BIGINT DEFAULT NULL COMMENT '质量门控结果ID', + `source_snapshot_id` BIGINT DEFAULT NULL COMMENT '来源快照ID', + `authorization_snapshot_id` BIGINT DEFAULT NULL COMMENT '授权快照ID', +-- PLACEHOLDER_SQL_PART7 + `source_status` VARCHAR(30) DEFAULT NULL COMMENT '来源状态', + `decision_archive_id` BIGINT DEFAULT NULL COMMENT '决策归档ID', + `creator` VARCHAR(64) DEFAULT '' COMMENT '创建者', + `create_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + `updater` VARCHAR(64) DEFAULT '' COMMENT '更新者', + `update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + `deleted` BIT(1) NOT NULL DEFAULT b'0' COMMENT '是否删除', + `tenant_id` BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + PRIMARY KEY (`id`), + KEY `idx_work_status` (`work_id`, `status`, `create_time`), + KEY `idx_task_id` (`task_id`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='Muse AI 候选（ai 模块）'; + +-- AI Agent +CREATE TABLE `muse_ai_agent` ( + `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键', + `agent_key` VARCHAR(100) NOT NULL COMMENT '智能体稳定业务键', + `agent_name` VARCHAR(200) NOT NULL COMMENT '智能体名称', + `agent_type` VARCHAR(20) NOT NULL COMMENT '类型：system/user/market_installed', + `owner_user_id` BIGINT DEFAULT NULL COMMENT '所属用户（user 类型时填写）', + `description` VARCHAR(500) DEFAULT NULL COMMENT '描述', + `status` VARCHAR(20) NOT NULL DEFAULT 'active' COMMENT '状态：active/disabled/archived', + `current_version_id` BIGINT DEFAULT NULL COMMENT '当前激活版本ID', + `creator` VARCHAR(64) DEFAULT '' COMMENT '创建者', + `create_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + `updater` VARCHAR(64) DEFAULT '' COMMENT '更新者', + `update_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + `deleted` BIT(1) NOT NULL DEFAULT b'0' COMMENT '是否删除', + `tenant_id` BIGINT NOT NULL DEFAULT 0 COMMENT '租户ID', + PRIMARY KEY (`id`), + UNIQUE KEY `uk_agent_key` (`agent_key`), + KEY `idx_type_status` (`agent_type`, `status`) +) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='Muse 智能体（ai 模块）'; diff --git a/design-docs/后端-05-统一API契约-v1.md b/design-docs/后端-05-统一API契约-v1.md index 52ff3a8d..2329812a 100644 --- a/design-docs/后端-05-统一API契约-v1.md +++ b/design-docs/后端-05-统一API契约-v1.md @@ -1,6 +1,6 @@ # 后端-05：统一 API(接口) 契约-v1 -- 版本：v6 +- 版本：v8 - 更新日期：2026-05-24 - 目标读者：前端 / 后端 / 架构 / 测试 - 阅读时间：35-55 分钟 @@ -35,7 +35,7 @@ Muse API 分组与 owner： | Knowledge | `/admin-api/muse/knowledge/**`、`/app-api/muse/knowledge-*/**` | `yudao-module-knowledge` | 全局/用户/局域知识库、草稿、绑定、投影 | | AI / Agent | `/admin-api/muse/ai/**`、`/app-api/muse/ai/**`、`/app-api/muse/agents/**` | `yudao-module-ai` 二开 | Prompt、Agent、任务、候选、质量门控、评估 | | Market | `/admin-api/muse/market/**`、`/app-api/muse/marketplace/**` | `yudao-module-market` | 市场资产、授权、安装、handoff、发布、治理 | -| Account | `/admin-api/muse/account/**`、`/app-api/muse/account/**`、`/app-api/muse/me` | 逻辑 `account` | 权益、配额、用量、授权/购买/发布摘要 | +| Account | `/admin-api/muse/account/**`、`/app-api/muse/account/**`、`/app-api/muse/me` | `yudao-module-member`（已决策：member 模块实现 account API 路径） | 权益、配额、用量、授权/购买/发布摘要 | | Jobs / Events | `/admin-api/muse/jobs/**`、`/app-api/muse/jobs/**`、`/admin-api/muse/source-events/**` | 各 owner + outbox | 异步任务状态、来源事件传播和重试入口 | ## 2. 通用约定 @@ -128,6 +128,26 @@ API 响应遵循 Yudao 风格的统一响应壳。产品语义字段可以在 `d 管理员可见摘要不等于可见私有正文。需要查看用户私有内容时，必须另有合规访问接口、最小字段、原因、时效、分权和审计；不得用通用内容列表绕过。 +### 2.7 API 版本策略 + +API 版本通过 HTTP Header 传递，路由路径不变： + +| 项目 | 说明 | +|---|---| +| Header | `X-API-Version: 1`（当前版本为 1） | +| 默认行为 | 未传 header 时使用最新稳定版本 | +| 版本影响范围 | 响应结构和字段语义；不影响路由路径和认证方式 | +| Deprecation Policy | 旧版本至少保留 6 个月；期间响应头返回 `Deprecation: true` 和 `Sunset: ` 提示迁移 | +| 到期行为 | 到期后返回 `API_VERSION_DEPRECATED` 错误码，HTTP 410 Gone | +| 版本变更触发条件 | 响应字段删除、字段语义不兼容变更、枚举值语义变化 | +| 非破坏性变更 | 新增可选字段、新增枚举值、新增接口不触发版本升级 | + +客户端集成要求： + +- 前端 SDK 和 API 客户端必须显式传递 `X-API-Version` header。 +- 后端网关层解析 header 并注入请求上下文，各模块 controller 按版本返回对应响应结构。 +- 版本不匹配或已废弃时，响应 body 必须包含 `currentVersion`、`supportedVersions` 和 `migrationGuide` 字段。 + ## 3. Admin APIs ### 3.1 治理和元结构 @@ -274,9 +294,9 @@ Tool Grant 写入必须经 Governance / Security facade 校验审批、用途、 支付底层交易、退款和充值能力优先复用 `yudao-module-pay`。 -Quota adjustment ledger 是账户侧 append-only 语义：每次人工调整、套餐变更、市场补偿、导出扣减回滚或 New-API 配置请求回填都必须记录 `commandId`、`correlationId`、调整原因、前后权益快照、操作者、审批或复核信息和幂等状态。ledger 不是 New-API 成本账本 authority，也不能被 AI 管理接口用来推断供应商路由或底层成本。 +Quota adjustment 是账户侧审计语义：每次人工调整、套餐变更、市场补偿、导出扣减回滚或 New-API 配置请求回填都必须记录 `commandId`、`correlationId`、调整原因、前后权益快照、操作者、审批或复核信息和幂等状态。权益审计日志不是 New-API 成本账本 authority，也不能被 AI 管理接口用来推断供应商路由或底层成本。 -Pay callback、refund、套餐撤销和市场补偿必须通过 account entitlement ledger 幂等传播：以支付订单、退款单、市场授权或调额请求作为 `sourceOwner/sourceId`，以回调或补偿事件作为 `idempotencyKey`。重复回调返回同一 ledger 结果；退款和撤销使用反向流水或补偿流水，不覆盖原流水。 +Pay callback、refund、套餐撤销和市场补偿必须通过 account entitlement 可变表 + 审计日志幂等传播：以支付订单、退款单、市场授权或调额请求作为 `sourceOwner/sourceId`，以回调或补偿事件作为 `idempotencyKey`。重复回调返回同一处理结果；退款和撤销使用反向变更更新可变表并写审计日志。 ### 3.7 任务、来源事件和审计 @@ -325,7 +345,7 @@ Source Status 请求必须带业务上下文，不能只用 `sourceType + source | `sourceVersion` | 调用方当前持有的来源版本 | | `authorizationSnapshotId` | 调用方当前持有的授权快照 | -Source Status 响应必须返回 `sourceStatus`、`actionPolicy`、`blockedReasons`、`needsRecheckReasons`、`reasonAttributions`、`sourceEvents`、`nextActions`、`currentSourceVersion`、`currentAuthorizationSnapshotId` 和可选 `jobId`。`sourceStatus` 使用 SourceStatus：`active`、`stale`、`revoked`、`recalled`、`delisted`、`blocked`、`owner_missing`、`unauthorized`、`needs_recheck`；`actionPolicy` 使用 SourceActionPolicy：`allowed`、`read_only`、`blocked`、`needs_recheck`。API 不能只返回一个 `blocked=true`，必须保留 revoked / recalled / delisted / unauthorized / processing_failed 等原因和归因；`read_only` 只允许历史查看或授权记录展示，不允许写入、绑定、生成、接受候选或受限导出；`needs_recheck` 不等于允许继续写入，目标 owner 必须在自己的命令接口重新校验。 +Source Status 响应必须返回 `sourceStatus`、`actionPolicy`、`blockedReasons`、`needsRecheckReasons`（注：needsRecheckReasons 是 ActionPolicy 层面的补充信息，说明为何 actionPolicy=needs_recheck，不是 SourceStatus 枚举值）、`reasonAttributions`、`sourceEvents`、`nextActions`、`currentSourceVersion`、`currentAuthorizationSnapshotId` 和可选 `jobId`。`sourceStatus` 使用 SourceStatus：`active`、`stale`、`revoked`、`recalled`、`delisted`、`blocked`、`owner_missing`、`unauthorized`；`actionPolicy` 使用 SourceActionPolicy：`allowed`、`read_only`、`blocked`、`needs_recheck`。API 不能只返回一个 `blocked=true`，必须保留 revoked / recalled / delisted / unauthorized / processing_failed 等原因和归因；`read_only` 只允许历史查看或授权记录展示，不允许写入、绑定、生成、接受候选或受限导出；`needs_recheck` 不等于允许继续写入，目标 owner 必须在自己的命令接口重新校验。 ### 4.3 作品和正文 @@ -341,6 +361,26 @@ Source Status 响应必须返回 `sourceStatus`、`actionPolicy`、`blockedReaso | POST | `/app-api/muse/chapters/{chapterId}/blocks` | 新建 Block | | PUT | `/app-api/muse/blocks/{blockId}` | 保存 Block，必须带 expectedRevision | | GET | `/app-api/muse/blocks/{blockId}/source-attribution` | 查看当前 Block revision 来源归因 | + +Block 保存（`PUT /blocks/{blockId}`）响应除返回新 revision 外，可包含 `followupTasks` 字段： + +| 字段 | 类型 | 说明 | +|---|---|---| +| `revision` | int | 保存成功后的新 revision | +| `wordCount` | int | 当前字数 | +| `followupTasks` | array | 可选，保存后触发的异步任务摘要列表，例如知识提取任务 | + +`followupTasks` 数组元素结构： + +| 字段 | 类型 | 说明 | +|---|---|---| +| `taskType` | enum | `knowledge_extraction` / `source_recheck` / `projection_refresh` | +| `jobId` | string | 异步任务 ID，可用于轮询 | +| `status` | enum | `queued` / `skipped` | +| `reason` | string | 若 skipped，说明跳过原因（例如无变更、策略未启用） | + +前端可基于 `followupTasks` 展示知识提取进度提示或刷新知识草稿列表。`followupTasks` 为空或不返回时表示无后续异步任务。 + | GET | `/app-api/muse/works/{workId}/meta-projections` | 查询作品维度用户可见 MetaSchema 投影 | | GET | `/app-api/muse/works/{workId}/meta-projections/{projectionKey}` | 查询指定投影结构、字段数据和版本 | | POST | `/app-api/muse/works/{workId}/dynamic-fields/validate` | 校验动态字段数据，不写入 | @@ -357,6 +397,23 @@ Source Status 响应必须返回 `sourceStatus`、`actionPolicy`、`blockedReaso 动态字段没有跨 owner 的通用写接口。`/dynamic-fields/validate` 只做校验和路由建议，不写入任何 Canonical fact；正式写入必须回到目标 owner API，例如规划写 `PUT /works/{workId}/planning/{sectionKey}`，正文写 `PUT /blocks/{blockId}`，知识写 Knowledge Draft / Local KB 命令，Agent 写 Agent 配置命令。Owner 命令必须校验 `schemaVersion`、`projectionVersion`、`expectedDataRevision`、字段 allowlist、来源状态和目标 owner 权限。Schema 过期返回 `SCHEMA_STALE`；字段已废弃返回 `FIELD_DEPRECATED`；投影过期返回 `PROJECTION_STALE`；字段试图写 Canonical fact 但没有 owner 命令时返回 `FORBIDDEN` 或 `FEATURE_DISABLED`。 +各 owner 命令版本校验要求： + +| Owner 命令 | `expectedSchemaVersion` | `expectedProjectionVersion` | `expectedDataRevision` | 说明 | +|---|---|---|---|---| +| `PUT /blocks/{blockId}` | 可选（正文保存不依赖动态字段 Schema） | 不要求 | 必须（即 `expectedRevision`） | 正文保存以 Block revision 为乐观锁 | +| `PUT /works/{workId}/planning/{sectionKey}` | 必须 | 必须 | 必须 | 规划保存必须确保 Schema 和投影未过期 | +| `POST /knowledge-drafts/{draftId}/confirm` | 可选 | 不要求 | 必须（即 draft version） | 知识确认以 draft 状态和来源为准 | +| `POST /works/{workId}/agent-slots/{slotKey}/bind` | 不要求 | 不要求 | 必须（即 `expectedSlotRevision`） | 槽位绑定以 slot revision 为乐观锁 | +| `PATCH /works/{workId}` | 必须（若修改动态字段） | 必须（若修改动态字段） | 必须 | 作品基础信息修改涉及动态字段时校验 | +| `POST /agents/{agentId}/versions` | 不要求 | 不要求 | 不要求 | Agent 版本创建不涉及动态字段 | + +规则： + +- 涉及 MetaSchema 管控的动态字段写入时，`expectedSchemaVersion` 和 `expectedProjectionVersion` 必须校验；不匹配时分别返回 `SCHEMA_STALE` 和 `PROJECTION_STALE`。 +- 所有写入命令必须校验目标对象的 `expectedDataRevision`（或等价乐观锁字段）；不匹配时返回 `REVISION_CONFLICT` 或 `DATA_REVISION_CONFLICT`。 +- 不涉及动态字段的纯正文或纯配置命令可以不要求 `expectedSchemaVersion`，但必须保留 `expectedRevision` 乐观锁。 + ### 4.4 作品规划 作品规划台面向作品设定、章节大纲、世界设定、角色关系、情节节拍和文风检查。规划正式数据由用户确认后进入 `content` owner；AI 只能产生 Planning Candidate，不直接写正式规划。 @@ -405,12 +462,10 @@ Accept 请求语义： | `expectedRevision` | 目标 Block revision | | `acceptMode` | `accept_as_is` / `merge_after_edit` | | `finalContent` | 修改后合并时必填 | -| `candidateDecisionEnvelopeId` | 调用方持有的 Candidate Decision Envelope；后端必须消费或重算 | -| `decisionEnvelopeVersion` | envelope 版本，防止 stale 决策进入正文 | | `qualityResultVersion` | 候选质量结果版本 | | `outputComplianceResultId` | 输出合规结果 | | `staticCheckResultId` | 静态检查结果 | -| `sourceSnapshotId` / `sourceVersion` | 候选来源快照和来源版本 | +| `sourceSnapshotId` / `sourceVersion` | 候选来源快照和来源版本；接受时实时对比当前来源版本 | | `authorizationSnapshotId` | 接受时使用的授权快照 | | `workAssetUsePrecheckId` | 使用市场作品资产作为参考或上下文时必填；feature gate 未开启默认返回 `FEATURE_DISABLED` | | `auditReason` | 用户接受、修改后合并或覆盖原因 | @@ -419,7 +474,7 @@ Accept 响应语义： - Block 新 revision。 - Suggestion 归档结果。 -- Candidate Decision Archive 引用和 envelope 消费结果。 +- Candidate Decision Archive 引用。 - Block Source Attribution 写入结果，包含 source status、authorization snapshot、lineage 和许可限制。 - Knowledge Draft 结果：原样接受保持待确认；修改后合并让旧草稿失效。 - followup task：投影刷新或重新提取。 @@ -465,7 +520,7 @@ Accept / Merge 失败必须返回 `blockedReasons`、`sourceStatusReasons`、`re 知识绑定预检和绑定写入都属于 Knowledge owner。Market 只能提供来源侧 handoff token、授权摘要和跳转审计；Knowledge 预检接口必须重新校验 work owner、目标对象、来源版本、授权快照、来源状态、许可范围和幂等键，生成 `kbBindPrecheckId` 或签名消费凭证。知识绑定命令必须消费 `kbBindPrecheckId`，并显式传入 `commandId`、`workId`、`targetOwner=knowledge`、`targetId`、`sourceType`、`sourceId`、`sourceVersion`、`authorizationSnapshotId` 和 `expectedBindingRevision`。 -资料上传、删除、重建索引、停用、恢复和发布提交都必须写审计。资料处理任务失败时返回 `jobId`、`retryable`、`failedStage`、`blockedReason` 和 `nextActions`；删除或停用资料必须触发来源事件，让绑定、检索、生成、导出和个人中心摘要进入 blocked 或 needs_recheck。 +资料上传、删除、重建索引、停用、恢复和发布提交都必须写审计。资料处理任务失败时返回 `jobId`、`retryable`、`failedStage`、`blockedReason` 和 `nextActions`；删除或停用资料必须触发来源事件，让绑定、检索、生成、导出和个人中心摘要进入 blocked 或 stale 状态。 资料上传必须带 owner、用途、文件名、大小、MIME、hash 和幂等键；服务端必须写扫描状态、存储引用、保留期和清理策略。扫描 blocked / failed 或 MIME、大小、扩展名不匹配时，资料不得进入切块、索引、AI 上下文或市场发布。 @@ -483,6 +538,37 @@ Accept / Merge 失败必须返回 `blockedReasons`、`sourceStatusReasons`、`re 用户只能替换开放槽位，不能替换输入输出合规、拆分切块、入 RAG、语义安全围栏、静态检查、质量门控等保护节点。 +智能体试用接口（`POST /app-api/muse/agents/{agentId}/test`）详情： + +试用请求字段： + +| 字段 | 类型 | 要求 | +|---|---|---| +| `workId` | string | 可选，关联作品上下文；不传时使用沙箱上下文 | +| `contextScope` | enum | `none` / `work` / `chapter`；决定试用时可读取的上下文范围 | +| `usagePolicy` | enum | `charge` / `free_trial`；决定本次试用是否计费 | +| `outputTarget` | enum | `preview_only` / `shadow`；`preview_only` 只返回预览不落库，`shadow` 写入 Shadow Candidate 供后续决策 | +| `input` | object | 试用输入内容，包含 prompt 或指令 | +| `commandId` | string | 幂等键 | + +试用响应字段： + +| 字段 | 类型 | 说明 | +|---|---|---| +| `trialSessionId` | string | 本次试用会话 ID，用于关联后续查询和审计 | +| `outputPreview` | object | 智能体输出预览内容 | +| `usageCharged` | boolean | 本次试用是否实际计费 | +| `outputDestination` | string | 输出实际落点：`preview_only` / `shadow_candidate` | +| `jobId` | string | 若异步执行，返回任务 ID 供轮询 | + +约束： + +- `contextScope=work` 或 `chapter` 时，必须校验用户对 `workId` 的访问权限。 +- `usagePolicy=free_trial` 受账户免费试用额度限制；额度耗尽时返回 `QUOTA_EXCEEDED`。 +- `outputTarget=shadow` 时，输出进入 Shadow Candidate 状态，用户可后续接受或丢弃。 +- 试用不写正文 Canonical、Local KB 或正式规划。 +- Runtime Permission Envelope 由服务端按试用场景生成，scope 受限于试用上下文。 + 槽位绑定命令必须显式声明： | 字段 | 要求 | @@ -503,6 +589,7 @@ Accept / Merge 失败必须返回 `blockedReasons`、`sourceStatusReasons`、`re |---|---|---| | GET | `/app-api/muse/marketplace/assets` | 市场资产列表 | | GET | `/app-api/muse/marketplace/categories` | 分类曝光、推荐位、排序和可见性摘要 | +| GET | `/app-api/muse/marketplace/recommendations` | 个性化推荐资产列表 | | GET | `/app-api/muse/marketplace/assets/{assetId}` | 资产详情 | | POST | `/app-api/muse/marketplace/assets/{assetId}/favorite` | 收藏资产 | | DELETE | `/app-api/muse/marketplace/assets/{assetId}/favorite` | 取消收藏 | @@ -510,8 +597,8 @@ Accept / Merge 失败必须返回 `blockedReasons`、`sourceStatusReasons`、`re | POST | `/app-api/muse/marketplace/assets/{assetId}/install` | 安装智能体或知识库 | | POST | `/app-api/muse/marketplace/assets/{assetId}/bind-precheck` | 创建来源侧授权摘要和 handoff 准备，不返回目标 owner 写入凭证 | | POST | `/app-api/muse/marketplace/handoffs` | 创建市场 handoff，只返回短期 handoff 和目标 owner 消费入口 | -| GET | `/app-api/muse/marketplace/handoffs/{handoffId}` | 查询 handoff 状态、过期时间和目标 owner | -| POST | `/app-api/muse/marketplace/handoffs/{handoffId}/cancel` | 取消市场 handoff | +| GET | `/app-api/muse/marketplace/handoffs/{handoffToken}` | 查询 handoff 状态、过期时间和目标 owner | +| POST | `/app-api/muse/marketplace/handoffs/{handoffToken}/cancel` | 取消市场 handoff | | POST | `/app-api/muse/marketplace/publish-drafts` | 保存发布草稿 | | POST | `/app-api/muse/marketplace/publish-drafts/{draftId}/checks` | 发布检查，生成 marketPublishCheckId | | POST | `/app-api/muse/marketplace/publish-requests` | 提交发布申请，消费 marketPublishCheckId 和发布快照 | @@ -524,6 +611,27 @@ Accept / Merge 失败必须返回 `blockedReasons`、`sourceStatusReasons`、`re 作品资产 feature gate 未开启前，只允许阅读、收藏和授权记录，不允许模板化、参考写入或进入 AI 上下文；相关 target owner 预检和绑定/使用命令默认返回 `FEATURE_DISABLED`，直到 Content / AI owner、API、Schema、lineage 和导出限制闭合。 +市场资产列表查询（`GET /app-api/muse/marketplace/assets`）排序和筛选参数： + +| 参数 | 类型 | 说明 | +|---|---|---| +| `sortBy` | enum | `popularity` / `newest` / `rating` / `relevance`；默认 `relevance` | +| `assetType` | enum | `work` / `agent` / `knowledge_base`；可选筛选 | +| `category` | string | 分类筛选 | +| `keyword` | string | 关键词搜索 | +| `pageNo` / `pageSize` | int | 分页参数 | + +个性化推荐接口（`GET /app-api/muse/marketplace/recommendations`）参数： + +| 参数 | 类型 | 说明 | +|---|---|---| +| `recommendationContext` | enum | 可选，`home` / `after_install` / `similar_to_asset` / `work_context`；决定推荐策略 | +| `referenceAssetId` | string | 可选，`similar_to_asset` 时必填，基于该资产推荐相似资产 | +| `workId` | string | 可选，`work_context` 时可填，基于作品上下文推荐适配的智能体或知识库 | +| `limit` | int | 推荐数量上限，默认 10 | + +推荐响应返回 `assets` 列表和 `recommendationId`（用于后续点击归因和推荐效果追踪）。推荐不暴露用户私有正文或知识内容作为推荐依据。 + 市场接口的返回必须区分 `licenseStatus`、`installStatus`、`bindStatus`、`sourceStatus` 和 `nextAction`。购买或安装成功只表示账户可用资产变化；绑定或使用必须由目标 owner 自己生成并消费预检后完成。 Market 只负责资产、授权、安装记录、发布申请、申诉、来源侧授权摘要、handoff token 和跳转审计。Market API 可以生成、查询、取消 handoff，但不能写作品正文、正式规划、Local KB、Agent Slot Binding、目标 precheck/session 或动态字段数据；目标 owner API 必须基于 handoff token 或授权摘要自行生成并消费 `kbBindPrecheckId`、`agentSlotPrecheckId`、`workAssetUsePrecheckId` 或签名消费凭证，并重新校验 owner、目标对象、来源版本、授权快照、状态机和幂等键。 @@ -569,6 +677,8 @@ Import task、import file 和 chapter context owner 是 `content`；Parse Job | GET | `/app-api/muse/account/licenses` | 授权记录 | | GET | `/app-api/muse/account/publish-records` | 发布记录 | | GET | `/app-api/muse/account/security-events` | 安全事件摘要 | +| GET | `/app-api/muse/account/security-events/{eventId}` | 安全事件详情，返回事件类型、发生时间、来源 IP、设备信息、影响范围和处理建议 | +| POST | `/app-api/muse/account/security-events/{eventId}/acknowledge` | 确认/处理安全事件，标记用户已知晓或已采取措施 | | POST | `/app-api/muse/account/export-tasks` | 创建个人资料、账户记录或安全事件导出任务 | | GET | `/app-api/muse/account/export-tasks/{taskId}` | 查询个人中心导出任务 | | GET | `/app-api/muse/account/downloads/{credentialId}` | 下载个人中心导出包 | @@ -577,6 +687,37 @@ Import task、import file 和 chapter context owner 是 `content`；Parse Job 个人中心账户接口只返回当前用户可见的摘要和下载凭证，不暴露 New-API token、provider authority、供应商路由、底层成本账本、完整 Prompt/Response 或私有审计字段。`correlationId` 查询只能查本人可见调用，重复请求必须返回同一重试组和归属状态，不能重复扣减、重复补偿或重复归属。 +安全事件详情接口（`GET /app-api/muse/account/security-events/{eventId}`）响应字段： + +| 字段 | 类型 | 说明 | +|---|---|---| +| `eventId` | string | 安全事件 ID | +| `eventType` | enum | `login_anomaly` / `credential_expired` / `sensitive_export` / `access_denied_burst` / `device_change` / `permission_escalation` | +| `severity` | enum | `info` / `warning` / `critical` | +| `occurredAt` | datetime | 事件发生时间 | +| `sourceIp` | string | 来源 IP 地址 | +| `deviceInfo` | object | 设备信息摘要（UA、平台、地理位置） | +| `affectedScope` | string | 影响范围描述 | +| `description` | string | 事件描述 | +| `suggestedActions` | array | 建议处理措施列表 | +| `acknowledgedAt` | datetime | 用户确认时间，未确认为空 | +| `acknowledgedAction` | string | 用户确认时选择的处理措施 | + +安全事件确认接口（`POST /app-api/muse/account/security-events/{eventId}/acknowledge`）请求字段： + +| 字段 | 类型 | 要求 | +|---|---|---| +| `commandId` | string | 幂等键 | +| `action` | enum | `acknowledged` / `password_changed` / `session_revoked` / `false_positive` | +| `note` | string | 可选，用户备注 | + +约束： + +- 安全事件只能由事件所属用户查看和确认。 +- 确认操作是 append-only，不删除安全事件记录。 +- `action=session_revoked` 时，后端应联动 session 管理服务使相关会话失效。 +- 安全事件确认写审计。 + ## 5. 通用错误码 | 错误码 | 语义 | 前端建议 | @@ -586,6 +727,9 @@ Import task、import file 和 chapter context owner 是 `content`；Parse Job | `RESOURCE_NOT_FOUND` | 资源不存在或不可见 | 返回列表或刷新 | | `VALIDATION_ERROR` | 请求字段不合法 | 定位字段并提示 | | `REVISION_CONFLICT` | Block revision 冲突 | 展示冲突恢复信息和当前 revision | +| `DATA_REVISION_CONFLICT` | 动态字段数据 revision 冲突（expectedDataRevision 不匹配），语义覆盖所有 owner 命令中的 expectedRevision / expectedDataRevision 冲突场景 | 展示当前 dataRevision 和冲突字段，引导用户刷新后重试 | +| `QUOTA_EXCEEDED` | 账户配额已用尽，例如 AI 调用次数、存储空间、知识库数量等 | 展示当前配额和升级/购买入口 | +| `BUDGET_EXCEEDED` | 单次任务或会话预算超限，例如 token 预算、调用次数预算 | 展示预算限制和调整建议 | | `SCHEMA_STALE` | 调用方持有的 MetaSchema 版本已过期 | 刷新 Schema 和投影后重试 | | `FIELD_DEPRECATED` | 动态字段已废弃或不再允许保存 | 显示迁移提示或隐藏保存入口 | | `PROJECTION_STALE` | 用户可见投影版本已过期 | 重新拉取投影和字段数据 | @@ -602,6 +746,7 @@ Import task、import file 和 chapter context owner 是 `content`；Parse Job | `TASK_FAILED` | 异步任务失败 | 展示失败原因、重试或取消 | | `PARTIAL_FAILURE` | 批量操作部分成功、部分失败 | 展示逐项结果和可重试项 | | `UPSTREAM_UNAVAILABLE` | New-API、检索、文件或通知服务不可用 | 展示稍后重试，不暴露密钥或内部响应 | +| `API_VERSION_DEPRECATED` | 请求的 API 版本已废弃（X-API-Version header 指定的版本已过期） | 展示迁移指引，升级到最新版本 | 错误响应 `data` 可以按场景携带 `currentRevision`、`currentState`、`currentSchemaVersion`、`currentProjectionVersion`、`currentDataRevision`、`requiredPrecheckType`、`sourceStatus`、`actionPolicy`、`reasonAttributions`、`correlationStatus`、`retryable`、`jobId`、`partialResults`、`nextActions` 等可恢复字段，但不得返回密钥、完整 Prompt/Response、私有正文全文或越权来源全文。 diff --git a/design-docs/架构-01-系统全貌与边界上下文.md b/design-docs/架构-01-系统全貌与边界上下文.md index 449fd9e8..33305a0c 100644 --- a/design-docs/架构-01-系统全貌与边界上下文.md +++ b/design-docs/架构-01-系统全貌与边界上下文.md @@ -1,6 +1,6 @@ # 架构-01：系统全貌与边界上下文 -- 版本：v8 +- 版本：v9 - 更新日期：2026-05-24 - 目标读者：架构 / 后端 / 前端 / 产品 / 测试 - 阅读时间：25-35 分钟 @@ -29,7 +29,7 @@ Muse 是面向长篇小说创作的多角色 AI 创作与资产流通系统。 | 产品空间 | 使用角色 | 架构定位 | 禁止承担的职责 | |---|---|---|---| -| 管理员控制台(Admin Console) | 管理员 | 系统治理入口，调用 Admin/Governance、Identity/Auth、Marketplace/Asset、Account/Usage/Audit、Integration 等能力 | 替用户修改私有作品、用户智能体、用户知识库或确认作品事实 | +| 管理员控制台(Admin Console) | 管理员 | 系统治理入口，调用 Admin/Governance、MetaSchema、Identity/Auth、Marketplace/Asset、Account/Usage/Audit、Integration 等能力 | 替用户修改私有作品、用户智能体、用户知识库或确认作品事实 | | 用户工作区(User Workspace) | 普通用户 | 我的作品和作品工作台入口，调用 Work/Content、Knowledge、AI Orchestration、Agent、Account/Usage/Audit | 系统后台配置、全局授权治理、市场审核、保护节点配置 | | 智能体工作台(Agent Workspace) | 管理员 / 普通用户 | 智能体资产和槽位配置入口，调用 Agent BC、Marketplace BC、Admin/Governance 的保护节点注册表 | 替换系统保护节点、扩大工具权限、绕过输出合同 | | 知识库工作台(Knowledge Workspace) | 管理员 / 普通用户 | 全局知识、用户知识库、已安装知识库、处理状态和作品绑定入口，调用 Knowledge BC 和 Marketplace BC | 把绑定知识自动写入局域知识库；让普通用户治理全局知识 authority | @@ -40,7 +40,7 @@ Muse 是面向长篇小说创作的多角色 AI 创作与资产流通系统。 | 产品空间 | 主要调用 BC | 关键协作点 | |---|---|---| -| 管理员控制台 | Identity/Auth、Admin/Governance、Knowledge、Agent、Marketplace/Asset、Account/Usage/Audit、Integration | 分权校验、配置版本、影响预览、高危复核、审计 | +| 管理员控制台 | Identity/Auth、Admin/Governance、MetaSchema、Knowledge、Agent、Marketplace/Asset、Account/Usage/Audit、Integration | 分权校验、配置版本、影响预览、高危复核、审计 | | 用户工作区 | Identity/Auth、Work/Content、Knowledge、AI Orchestration、Agent、Marketplace/Asset、Account/Usage/Audit | 作品 owner、来源状态、候选决策、知识确认、导出预检 | | 智能体工作台 | Identity/Auth、Agent、Marketplace/Asset、Admin/Governance、Account/Usage/Audit | 智能体版本、工具授权、槽位合同、安装授权、运行记录 | | 知识库工作台 | Identity/Auth、Knowledge、Marketplace/Asset、Work/Content、Account/Usage/Audit | 用户知识库、资料处理、安装授权、作品绑定、来源传播 | @@ -54,12 +54,13 @@ Muse 是面向长篇小说创作的多角色 AI 创作与资产流通系统。 | BC | 核心职责 | 主写入边界 | 对外输出 | |---|---|---|---| | Identity/Auth BC | 登录认证、角色权限、权限组、菜单/页面/操作/数据范围、会话、安全事件 | 账户、角色、权限组、会话、安全状态 | 鉴权结果、数据范围、风险状态 | -| Admin/Governance BC | MetaSchema、模板、系统功能编排、保护节点注册表、系统级 Prompt、系统级智能体默认链路、质量策略、全局治理规则 | MetaSchema authority、系统级配置版本、保护节点 allowlist、开放槽位合同、质量策略版本 | 配置快照、影响预览、可回滚版本、治理决策 | +| Admin/Config BC | 系统级配置、租户管理、权限管理、审计日志（注：MetaSchema 已独立为 MetaSchema BC，Protection Node 和 Quality Policy 已归入 AI BC，市场治理已归入 Market BC） | 系统级配置版本、保护节点 allowlist、开放槽位合同 | 配置快照、影响预览、可回滚版本、治理决策 | +| MetaSchema BC | 元结构定义（字段类型、校验、枚举、引用、领域、范围、目标类型、可见性、AI 上下文、导出语义） | MetaSchema authority、MetaSchema 版本 | MetaSchema 投影、字段定义快照；admin 写入全局定义，用户可在作品级覆盖扩展字段，业务模块通过 facade-api 只读消费 | | Work/Content BC | 作品、章节、文本块、正文版本、正文来源归因、导入正文、作品级正式规划、作品导出任务 | Work / Chapter / Block 的 Canonical 正文、Block Source Attribution、规划正式项、作品导出任务 | 正文事实、章节结构、修订号、来源归因、导入状态 | | Knowledge BC | 局域知识库、用户知识库、全局知识资料处理、知识草稿、知识来源绑定、投影和索引状态 | Local KB、User KB、Knowledge Draft、Knowledge Source Binding、投影事件 | 已确认作品知识、授权知识来源、用户知识资产、检索输入 | | Agent BC | 系统智能体版本、用户智能体版本、智能体资产、安装智能体、作品智能体组合、开放槽位绑定、工具授权上限 | Agent、Agent Version、Tool Grant、Agent Set、Agent Slot Binding、Installed Agent、Agent Runtime Permission Envelope authority | 可运行智能体快照、槽位兼容结果、运行权限上限、运行记录输入 | -| AI Orchestration BC | 系统功能链路编排、上下文组装、生成/分析/检测任务、全书解析任务、章节解析结果、质量门控、候选、风险标记 | AI Task、Parse Job、Chapter Parse Result、Suggestion、Planning Candidate、Risk Marker、Quality Result | 待审对象、候选解释、章节解析结果、任务状态、质量结果；只消费运行权限包，不自授权 | -| Marketplace/Asset BC | 市场资产、发布草稿、发布检查快照、审核提交、许可、购买/获取、安装、绑定 handoff、下架、召回、申诉、治理结果 | Marketplace Asset、Publish Draft、Publish Check Snapshot、Review Submission、Listing、License、Purchase、Install、Governance Action | 授权快照、安装记录、治理状态、来源状态事件 | +| AI Orchestration BC | 系统功能链路编排、上下文组装、生成/分析/检测任务、全书解析任务、章节解析结果、质量门控、候选、风险标记、Protection Node（约束 AI 行为）、Quality Policy（AI 质量门控配置） | AI Task、Parse Job、Chapter Parse Result、Suggestion、Planning Candidate、Risk Marker、Quality Result、Protection Node、Quality Policy | 待审对象、候选解释、章节解析结果、任务状态、质量结果；只消费运行权限包，不自授权 | +| Marketplace/Asset BC | 市场资产、发布草稿、发布检查快照、审核提交、许可、购买/获取、安装、绑定 handoff、下架、召回、申诉、治理结果、市场治理（下架/召回/申诉） | Marketplace Asset、Publish Draft、Publish Check Snapshot、Review Submission、Listing、License、Purchase、Install、Governance Action | 授权快照、安装记录、治理状态、来源状态事件 | | Account/Usage/Audit BC | 用量归属、调用归属、账户权益快照、个人中心聚合、业务审计、接口调用日志、下载凭证和下载审计 | Usage Record、Entitlement Snapshot、Personal Center Summary、Audit Log、Download Credential、Download Audit | 用量视图、权益视图、审计视图、异常归属、个人中心聚合 | | Integration BC | New-API、模型网关、RAG / 向量检索、文件存储、通知等外部服务执行适配 | 外部绑定、凭据引用、correlationId、idempotencyKey、重试组、外部调用摘要 | 外部调用结果、归属待处理状态、失败原因、可重试信号 | @@ -78,28 +79,30 @@ 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` | MetaSchema、保护节点、系统功能链路、质量策略、全局治理配置 | Admin Console | 配置影响预览、质量评估 | Account/Usage/Audit | +| Admin/Governance | `muse-admin` | 保护节点注册表（仅注册，实例归 AI）、系统功能链路、全局治理配置 | 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 | | Agent | `muse-agent` | Agent、Agent Version、Tool Grant、Agent Runtime Permission Envelope authority、Agent Slot Binding、Installed Agent | Agent Workspace / Security Facade | 试用、槽位重验、运行权限包签发、运行记录归属 | Account/Usage/Audit | -| AI Orchestration | `muse-ai` | AI Task、Suggestion、Planning Candidate、Parse Job、Chapter Parse Result、Quality Result、Runtime Execution Record | AI / Work Workspace | 生成、分析、检测、全书解析、质量门控；只消费运行权限包 | Account/Usage/Audit | -| Marketplace/Asset | `muse-marketplace` | Marketplace Asset、Publish Draft、Publish Check Snapshot、Review Submission、Listing、License、Purchase、Install、Governance Action | Marketplace / Admin Marketplace | 发布检查、召回传播、申诉通知 | Account/Usage/Audit | +| AI Orchestration | `muse-ai` | AI Task、Suggestion、Planning Candidate、Parse Job、Chapter Parse Result、Quality Result、Runtime Execution Record、Protection Node（grant 包，约束 AI 行为）、Quality Policy（AI 质量门控配置） | AI / Work Workspace | 生成、分析、检测、全书解析、质量门控；只消费运行权限包；grant 包只暴露给 admin-api 调用链路，runtime 包只读 | Account/Usage/Audit | +| Marketplace/Asset | `muse-marketplace` | Marketplace Asset、Publish Draft、Publish Check Snapshot、Review Submission、Listing、License、Purchase、Install、Governance Action（admin 包：下架/召回/申诉） | Marketplace / Admin Marketplace | 发布检查、召回传播、申诉通知、市场治理 | Account/Usage/Audit | | Account/Usage/Audit | `muse-account` | Usage Record、Entitlement Snapshot、Personal Center Summary、Audit Log、Download Credential、Download Audit | Personal Center / Audit | 用量归属、审计导出、下载凭证失效 | Account/Usage/Audit | | Integration | `muse-integration` | External Binding、Credential Reference、Integration Call Log、correlationId、idempotencyKey | Internal Integration Facade | New-API 归属、外部重试、通知回执 | Account/Usage/Audit | 物理落点兼容规则： -- 逻辑 owner 优先于物理表或代码模块。阶段 7 如因 yudao-cloud fork 过渡，把 MetaSchema 物理表暂放 `muse-content` 或旧 Content 模块，也不能改变 Admin/Governance 的逻辑 authority。 -- MetaSchema 写入只能通过 Admin/Governance facade、治理版本、影响预览和审计发布；Content 只能承载或消费 MetaSchema 投影，不能把 MetaSchema 当普通内容字段管理。 +- 逻辑 owner 优先于物理表或代码模块。阶段 7 如因 yudao-cloud fork 过渡，把 MetaSchema 物理表暂放 `muse-content` 或旧 Content 模块，也不能改变 MetaSchema BC 的逻辑 authority。 +- MetaSchema 写入只能通过 MetaSchema facade-api、治理版本、影响预览和审计发布；Content 只能承载或消费 MetaSchema 投影，不能把 MetaSchema 当普通内容字段管理。admin 写入全局定义，用户可在作品级覆盖扩展字段，业务模块通过 facade-api 只读消费。 - Agent、Tool Grant 和 Agent Runtime Permission Envelope 的逻辑 authority 归 Agent BC 与安全 facade。即使执行代码或物理表暂落 `yudao-module-ai` / `muse-ai`，AI runtime 也只能消费服务端签发的权限包，不能给自己授权、扩权或绕过 owner 校验。 -- Source / Authorization 是横切架构契约，不是某个后端表的私有实现。来源 owner 发事件，目标 owner 消费快照和状态，Account/Usage/Audit 记录传播与审计。 +- AI 模块 Protection Node 和 Quality Policy 采用包级隔离 + ArchUnit 强制：grant 包只暴露给 admin-api 调用链路，runtime 包只读消费。 +- Source / Authorization 是横切架构契约，不是某个后端表的私有实现。来源 owner 发事件，目标 owner 消费快照和状态，Account/Usage/Audit 记录传播与审计。Source Snapshot 存储在独立 `source_snapshot` 表，各模块分散写入，DDL 放 infra 层统一管理。 ## 4. 关键权威归属 | 对象 / 能力 | 权威 BC | 允许写入入口 | 不能发生什么 | |---|---|---|---| -| MetaSchema / 字段可见性 | Admin/Governance | 管理员控制台治理 facade；必要时由 Content 承载只读投影 | 普通用户、市场资产、Content 普通内容接口不能修改系统元结构 | -| 保护节点注册表 | Admin/Governance | 管理员控制台高危发布 | 不能把输入输出合规、权限过滤、拆分切块、入 RAG、语义围栏、静态检查、Shadow -> Canonical、质量门控开放为用户槽位 | +| MetaSchema / 字段可见性 | MetaSchema BC | admin 通过 MetaSchema facade 写入全局定义；用户可在作品级覆盖扩展字段；业务模块通过 facade-api 只读消费 | 普通用户、市场资产、Content 普通内容接口不能修改系统元结构全局定义 | +| 保护节点注册表 | Admin/Governance（注册）+ AI Orchestration（实例，grant 包） | 管理员控制台高危发布注册；AI 模块 grant 包管理实例 | 不能把输入输出合规、权限过滤、拆分切块、入 RAG、语义围栏、静态检查、Shadow -> Canonical、质量门控开放为用户槽位 | | 正文 Canonical | Work/Content | 用户保存正文、接受候选、导入正文初始化 | AI 或市场资产不能直接写正文事实 | | 规划 Canonical | Work/Content | 用户确认规划、手动保存规划 | 规划候选不能自动进入后续生成上下文 | | 局域知识库(Local KB) | Knowledge | 用户确认知识草稿或手动知识修正 | 全书解析章节确认、知识库绑定、市场授权不能直接写 Local KB | @@ -121,13 +124,14 @@ Muse 是面向长篇小说创作的多角色 AI 创作与资产流通系统。 ### 4.1 Source / Authorization 横切 owner -Source / Authorization 是贯穿市场、知识、智能体、作品、AI 任务、导出和个人中心的横切 owner 契约。 +Source / Authorization 是贯穿市场、知识、智能体、作品、AI 任务、导出和个人中心的横切 owner 契约。采用事件驱动 + 各模块自治模式：来源 owner 发出状态变化事件，各消费模块监听事件并自行处理反应逻辑，预留集中式演进路径。不需要独立 source 模块。 - 来源 owner 负责发出 Source Status Event，事件必须包含 source id、source version、事件类型、原因、幂等键和影响范围。 - Marketplace/Asset 负责市场资产的 listing、license、install 和治理事件，但不替源作品、源智能体或源知识库改事实。 -- Authorization Snapshot 在每次生成、绑定、导出、确认、安装或工具运行前固化；下游对象必须保存快照 id 或不可变指纹，不能只保存“授权通过”。 -- Work/Content、Knowledge、Agent、AI Orchestration、导出任务和 Personal Center 只消费来源状态和授权快照，并把本地对象标记为 active、stale、needs_recheck、revoked、recalled、delisted、blocked 或 owner_missing。 +- Authorization Snapshot 在每次生成、绑定、导出、确认、安装或工具运行前固化；下游对象必须保存快照 id 或不可变指纹，不能只保存”授权通过”。 +- Work/Content、Knowledge、Agent、AI Orchestration、导出任务和 Personal Center 只消费来源状态和授权快照，并把本地对象标记为 active、stale、revoked、recalled、delisted、blocked 或 owner_missing。来源变化时各模块直接决策 active 或 disabled，不使用中间 needs_recheck 状态。 - SourceStatus 变化不得自动污染或回滚 Canonical，只能限制后续使用、作废未确认对象、要求重验、失效下载凭证或暴露治理入口。 +- Source Snapshot 存储：独立 `source_snapshot` 表，各模块分散写入，DDL 放 infra 层统一管理。 ## 5. 系统输入与输出 @@ -135,7 +139,7 @@ Source / Authorization 是贯穿市场、知识、智能体、作品、AI 任务 | 来源 | 输入 | 进入边界 | |---|---|---| -| 管理员 | MetaSchema、系统功能编排、保护节点、系统智能体、全局知识、质量策略、市场治理、权限、New-API 权益配置请求 | Admin/Governance、Knowledge、Agent、Marketplace/Asset、Account/Usage/Audit、Integration | +| 管理员 | MetaSchema、系统功能编排、保护节点、系统智能体、全局知识、质量策略、市场治理、权限、New-API 权益配置请求 | Admin/Governance、MetaSchema、Knowledge、Agent、AI Orchestration（Protection Node / Quality Policy）、Marketplace/Asset、Account/Usage/Audit、Integration | | 普通用户 | 正文编辑、作品规划、导入文稿、AI 请求、候选决策、知识确认、智能体配置、知识库绑定、市场获取、导出请求 | Work/Content、Knowledge、AI Orchestration、Agent、Marketplace/Asset、Account/Usage/Audit | | 系统任务 | 资料处理、索引、质量评估、来源传播、召回传播、导出、用量归属、重试和补偿 | 对应 owner BC + Account/Usage/Audit | | 外部服务 | 模型结果、网关日志、检索结果、文件处理结果、通知结果 | Integration、AI Orchestration、Knowledge、Account/Usage/Audit | @@ -159,7 +163,7 @@ Source / Authorization 是贯穿市场、知识、智能体、作品、AI 任务 | Sa-Token | 登录认证、会话、RBAC 基座 | 负责认证授权基座；作品 owner、知识来源、市场授权、Shadow -> Canonical 仍由 Muse 业务规则强制校验 | | New-API | 外部 LLM Gateway | 权威负责模型供应商路由、网关调用和底层成本日志；Muse 只保存绑定、配置请求、调用归属、correlationId、幂等和异常状态。New-API 服务凭据必须只保存为密钥管理引用，按环境隔离和最小权限配置，禁止进入日志、Prompt、候选、导出包或用户可见错误 | | RAG / 向量检索服务 | 检索增强生成基础设施 | 消费 Muse 授权后的投影或索引任务；不是 Canonical 事实源 | -| 图查询 / GraphRAG 服务 | 关系查询和一致性检查基础设施 | 只能读取授权投影和快照；不得反向覆盖作品事实 | +| 图查询 / GraphRAG 服务 | 关系查询和一致性检查基础设施（依赖 RAGFlow GraphRAG，不自建图存储） | 只能读取授权投影和快照；不得反向覆盖作品事实 | | 文件存储 | 导入文件、资料文件、导出包和临时下载凭证 | 必须受 owner、来源授权、导出许可、短期凭证和下载审计约束；导出包必须加密、按 owner 隔离、通过服务端代理下载，并在过期、撤权、取消或销毁策略触发时失效或删除 | | 通知服务 | 任务结果、市场治理、来源异常和安全事件通知 | 只发送状态和摘要；不承载事实写入或权限判断 | diff --git a/design-docs/架构-02-核心数据结构与双轨模型.md b/design-docs/架构-02-核心数据结构与双轨模型.md index 3737fde6..70167b1a 100644 --- a/design-docs/架构-02-核心数据结构与双轨模型.md +++ b/design-docs/架构-02-核心数据结构与双轨模型.md @@ -1,6 +1,6 @@ # 架构-02：核心数据结构与双轨模型 -- 版本：v7 +- 版本：v8 - 更新日期：2026-05-24 - 目标读者：架构 / 后端 / 前端 / 产品 / 测试 - 阅读时间：35-50 分钟 @@ -14,7 +14,7 @@ |---|---|---|---| | 规范数据 | Canonical | 用户确认、用户保存或 owner 规则明确写入后的正式事实 | 正文、正式规划项、局域知识库事实、用户知识库资料、智能体版本、市场授权记录 | | 待审层 | Shadow | AI、解析、检测、外部资产或系统处理产生的待确认对象，默认不可信 | AI 候选、规划候选、知识草稿、解析结果、风险标记、质量结果 | -| 归档层 | Archive | 待审对象或版本对象进入终态后的历史记录 | 已接受候选、已丢弃候选、已过期草稿、已停用版本、失败任务摘要 | +| 归档层 | Archive | 待审对象或版本对象进入终态后的历史记录。存储策略：先同表 + status 过滤，后续按数据量到阈值再分离归档表，预留分离路径 | 已接受候选、已丢弃候选、已过期草稿、已停用版本、失败任务摘要 | 一句话：AI 和外部资产只能产生候选、草稿、风险、快照或任务结果；正式作品事实必须由用户确认、用户保存或目标 owner 的显式规则写入。 @@ -45,12 +45,13 @@ | 模型分区 | 归属 BC | 负责什么 | 不负责什么 | |---|---|---|---| | 账号、权限与安全 | Identity/Auth | 用户、管理员、角色、权限组、菜单、操作、数据范围、会话、安全事件 | 作品事实、市场授权事实、外部网关权威日志 | -| 系统治理配置 | Admin/Governance | MetaSchema、系统功能链路、保护节点、开放槽位、系统 Prompt、系统智能体默认链路、质量策略 | 用户私有作品内容和用户私有资产内容 | +| 系统治理配置 | Admin/Governance | 系统功能链路、开放槽位、系统 Prompt、系统智能体默认链路 | 用户私有作品内容和用户私有资产内容 | +| 元结构定义 | MetaSchema BC | MetaSchema 全局定义、字段类型、校验、枚举、引用、领域、范围、目标类型；admin 写入全局定义，用户可在作品级覆盖扩展字段，业务模块通过 facade-api 只读消费 | 用户私有作品内容和用户私有资产内容 | | 作品内容 | Work/Content | 作品、章节、文本块、正文版本、正文来源归因、导入正文、正式规划项、叙事状态和作品导出任务 | 系统配置、市场资产记录、用户知识库资料 | | 知识体系 | Knowledge | 局域知识库、用户知识库、全局知识资料处理、知识草稿、知识来源绑定、索引和投影 | 市场授权交易、智能体槽位、正文编辑事实 | | 智能体体系 | Agent | 智能体、版本、工具授权(Tool Grant)、权限上限、试用、安装、作品槽位绑定、运行权限包 authority | 系统保护节点的最终 authority、作品正文写入、运行时自授权 | -| AI 编排与待审对象 | AI Orchestration | 生成、分析、检测、上下文组装、质量门控、候选、风险标记、运行执行记录 | Canonical 事实写入、市场治理、账户安全、智能体运行权限签发 | -| 市场资产 | Marketplace/Asset | 市场对象、发布、审核、许可、获取、安装、治理、申诉、来源状态事件 | 源作品、源智能体、源知识库的事实 owner | +| AI 编排与待审对象 | AI Orchestration | 生成、分析、检测、上下文组装、质量门控、候选、风险标记、运行执行记录、Protection Node（grant 包，约束 AI 行为）、Quality Policy（AI 质量门控配置） | Canonical 事实写入、市场治理、账户安全、智能体运行权限签发 | +| 市场资产 | Marketplace/Asset | 市场对象、发布、审核、许可、获取、安装、治理（admin 包：下架/召回/申诉）、来源状态事件 | 源作品、源智能体、源知识库的事实 owner | | 账户用量与审计 | Account/Usage/Audit | 用量归属、权益快照、个人中心聚合、业务审计、接口调用日志、下载凭证和下载审计 | 业务事实写入、owner 导出内容和外部网关权威成本 | | 外部集成 | Integration | New-API、文件、检索、通知等外部绑定、幂等、重试、correlation | Muse 内部事实 owner | @@ -109,9 +110,9 @@ | 模型 | 说明 | |---|---| | Source Lineage | 原始来源、派生路径、用户动作、AI 候选、市场资产、知识库、版本和许可链路 | -| Source Snapshot | 生成候选或草稿时的正文、规划、资料、授权和版本快照 | +| Source Snapshot | 生成候选或草稿时的正文、规划、资料、授权和版本快照。存储：独立 `source_snapshot` 表，各模块分散写入，DDL 放 infra 层统一管理 | | Authorization Snapshot | 某次生成、绑定、导出或确认时的许可、用途、权限、状态和限制 | -| Source Status | active、stale、needs_recheck、revoked、recalled、delisted、blocked、owner_missing 等统一来源状态 | +| Source Status | active、stale、revoked、recalled、delisted、blocked、disabled、owner_missing 等统一来源状态；来源变化时直接决策 active 或 disabled，不使用中间 needs_recheck 状态 | | Source Status Event | 来源状态变化事件 | 由来源 owner 或 Marketplace/Asset 发起，带幂等键、来源版本、影响范围和传播原因 | | Source Propagation Job | 来源状态传播任务 | 按目标对象记录 pending / applied / failed / skipped，失败时默认禁用新使用 | | Risk Marker | 冲突、重复、低置信、权利不清、隐私、安全、合规或来源不可用风险 | @@ -124,10 +125,11 @@ Source Status Event 由来源 owner 发出，Source Propagation Job 负责传播 横切责任边界： +- Source 传播采用事件驱动 + 各模块自治模式：来源 owner 发出状态变化事件，各消费模块监听事件并自行处理反应逻辑，预留集中式演进路径。不需要独立 source 模块。 - Source owner 负责发出来源状态事件；Marketplace/Asset 只对市场 listing、license、install、governance action 发权威事件，不接管源作品、源智能体或源知识库事实。 - Authorization Snapshot 由目标 owner 或 Security facade 在使用时固化；Work/Content、Knowledge、Agent、AI Orchestration、导出和个人中心只能消费快照。 - Source Status Event 和 Authorization Snapshot 可以物理落在不同 owner 表、事件表或审计表，但语义上必须保留 owner、版本、状态、用途和不可变指纹。 -- 来源状态传播不得自动改写 Canonical，只能限制后续使用、标记需重验、作废未确认对象或失效下载凭证。 +- 来源状态传播不得自动改写 Canonical，只能限制后续使用、标记需重验、作废未确认对象或失效下载凭证。来源变化时各模块直接决策 active 或 disabled，不使用中间 needs_recheck 状态。 ## 5. 智能体体系模型 @@ -225,7 +227,7 @@ Handoff 不能成为绕过权限、预检、确认、审计和 owner 写入边 ## 9. MetaSchema 与配置模型 -MetaSchema 是管理员治理的结构定义，不是作品事实，也不是 UI 面板模型。MetaSchema 的逻辑 owner 固定为 Admin/Governance；后端阶段如因 yudao-cloud fork 或旧模块兼容把物理表落到 Content，也只能通过治理 facade 写入，Content 只承载/消费投影，不能把 MetaSchema 当普通内容 owner。 +MetaSchema 是独立模块管理的结构定义，不是作品事实，也不是 UI 面板模型。MetaSchema 的逻辑 owner 固定为 MetaSchema BC（独立模块）；admin 写入全局定义，用户可在作品级覆盖扩展字段，业务模块通过 facade-api 只读消费。后端阶段如因 yudao-cloud fork 或旧模块兼容把物理表落到 Content，也只能通过 MetaSchema facade-api 写入，Content 只承载/消费投影，不能把 MetaSchema 当普通内容 owner。 MetaSchema 负责： @@ -275,7 +277,8 @@ MetaSchema 不负责： 1. 对象存在、未过期、未被替代、未撤权、未召回。 2. actor、owner、对象、动作、版本和授权快照匹配。 -3. 来源快照仍匹配当前来源，或用户选择了允许的独立确认路径。 +3. 候选记录创建时的来源版本，接受时实时对比当前来源状态；来源不匹配时阻断或要求用户选择允许的独立确认路径。不使用独立 Envelope 概念封装决策。 + 4. 写入目标 owner BC 的前置条件满足。 5. 成功后待审对象迁出活跃区，进入 Archive 或保留为已处理历史。 diff --git a/design-docs/架构-03-关键决策与原则(ADR).md b/design-docs/架构-03-关键决策与原则(ADR).md index 454670e3..db8e5125 100644 --- a/design-docs/架构-03-关键决策与原则(ADR).md +++ b/design-docs/架构-03-关键决策与原则(ADR).md @@ -1,6 +1,6 @@ # 架构-03：关键决策与原则（架构决策记录(ADR)） -- 版本：v7 +- 版本：v8 - 更新日期：2026-05-24 - 目标读者：架构/前端/后端/产品 - 阅读时间：30-45 分钟 @@ -76,12 +76,12 @@ - 后果(Consequences)：检索质量与灵活性提升；代价是新增外部依赖，必须有降级和重建投影路径。 - 参考落地：`doc/dev/03-S1-RAGFlow集成与知识检索基座.md` -### ADR-006：Neo4j vs RAGFlow GraphRAG 职责分工（待 S1-B 后补完） +### ADR-006：图查询依赖 RAGFlow GraphRAG，不自建图存储（已决策） - 上下文(Context)：需要判断 RAGFlow GraphRAG 是否足以覆盖时间线、因果链、实体演变等查询。 -- 决策(Decision)：暂不把 Neo4j 固定为必选事实；S1-B benchmark 后决定是否引入独立图查询 provider。 -- 替代方案(Alternatives)：现在直接引入 Neo4j 会增加运维和同步复杂度；完全放弃图查询会削弱长篇一致性检查。 -- 后果(Consequences)：保留条件交付空间；正式决策必须由 benchmark 支撑。 +- 决策(Decision)：依赖 RAGFlow GraphRAG 提供图查询能力，不自建 Neo4j 或其他独立图存储。 +- 替代方案(Alternatives)：引入 Neo4j 会增加运维和同步复杂度；完全放弃图查询会削弱长篇一致性检查。 +- 后果(Consequences)：减少运维复杂度和外部依赖；代价是图查询能力受限于 RAGFlow GraphRAG 的演进节奏。如未来 RAGFlow GraphRAG 能力不足，可重新评估独立图存储方案。 - 参考落地：`doc/dev/03-S1-RAGFlow集成与知识检索基座.md` ### ADR-007：Block 使用 UUID @@ -146,7 +146,7 @@ - 上下文(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 仍归 Admin/Governance；Agent、Tool Grant、Runtime Permission Envelope 仍由 Agent authority 与 Security facade 控制；AI runtime 不得自授权；Market 只发起来源侧 handoff；Parse Job / Chapter Parse Result 归 AI Orchestration；Knowledge Draft 只在章节审阅确认后由 Knowledge 创建。 +- 后果(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 优先于物理表、代码模块和页面入口 @@ -156,9 +156,30 @@ - 替代方案(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)：候选接受流程简化为：校验候选存在且未过期 -> 实时对比来源版本与当前状态 -> 执行质量/合规/静态检查 -> 写入正文。减少一个中间概念和对应的状态管理。代价是每次接受都需要实时校验，不能复用缓存的决策结果。 + ## 3. 本次是否需要新增 ADR 的结论 -需要。双角色入口、New-API 职责边界、全局/局域知识库分层、作品规划台模型复用、小说场景(Scene)暂不升一级模型、Sa-Token 认证授权基座、yudao-cloud fork 工程基座、逻辑 owner 优先原则，都会影响跨文档边界和后续实现，因此已补 ADR-008 到 ADR-015。 +需要。双角色入口、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。 ## 4. 关联阅读 diff --git a/design-docs/架构-04-状态机与约束清单.md b/design-docs/架构-04-状态机与约束清单.md index 80417742..18d92240 100644 --- a/design-docs/架构-04-状态机与约束清单.md +++ b/design-docs/架构-04-状态机与约束清单.md @@ -1,6 +1,6 @@ # 架构-04：状态机与约束清单 -- 版本：v5 +- 版本：v6 - 更新日期：2026-05-24 - 目标读者：架构 / 后端 / 前端 / 测试 / 产品 - 阅读时间：45-60 分钟 @@ -29,8 +29,7 @@ | 状态 | 含义 | 允许离开方式 | 约束 | |---|---|---|---| | queued | 已创建，等待执行 | running / canceled | 必须有 owner、任务类型、幂等键或去重上下文 | -| running | 执行中 | succeeded / failed / canceled / needs_recheck | 必须记录配置快照和授权快照 | -| needs_recheck | 权限、授权、来源、版本或 owner 状态变化，需重验 | running / failed / canceled | 重验前不得继续写事实或生成可下载结果 | +| running | 执行中 | succeeded / failed / canceled | 必须记录配置快照和授权快照 | | partial_completed | 批量任务部分子任务完成 | running / succeeded / failed / canceled | 只允许作为父任务聚合视图；子任务仍必须有各自终态 | | succeeded | 成功完成 | 终态 | 必须满足对应后置条件 | | failed | 失败 | 终态或新任务重试 | 失败不得静默写 Canonical | @@ -57,18 +56,20 @@ | delisted | 市场下架 | 禁止新获取和新安装；已授权使用按治理策略限制 | | recalled | 召回 | 影响已安装、已绑定、运行中任务、导出和未确认对象 | | owner_missing | 源 owner 缺失或权限转移不明 | 禁止模板化、参考写入、AI 上下文绑定和高风险使用 | -| needs_recheck | 版本、许可或权利状态变化 | 进入重验，不得继续消费旧快照 | +| disabled | 来源变化后直接停用 | 禁止继续使用，等待恢复或终态 | | blocked | 合规、安全、侵权或隐私阻断 | 禁止继续使用，保留审计和申诉路径 | +来源变化时直接决策 active 或 disabled，不使用中间 needs_recheck 状态。 + ### 2.4 MetaSchema 与配置版本写入约束 -MetaSchema 是 Admin/Governance 的治理版本，不是 Content 普通内容状态。 +MetaSchema 是 MetaSchema BC（独立模块）的治理版本，不是 Content 普通内容状态。 硬约束： -- MetaSchema 发布、回滚、停用和影响预览只能由 Admin/Governance facade 写入，并进入高危审计。 -- 如果物理表因 yudao-cloud fork 或旧模块兼容暂落 Content，Content 也只能承载/消费投影，不能绕过治理 facade 修改字段结构、可见性、AI 上下文或导出语义。 -- MetaSchema 版本变化只能让投影、任务、上下文组装、导出和知识确认进入 stale 或 needs_recheck，不能自动改写正文、知识、规划或 Narrative State Canonical。 +- MetaSchema 发布、回滚、停用和影响预览只能由 MetaSchema facade-api 写入，并进入高危审计。admin 写入全局定义，用户可在作品级覆盖扩展字段，业务模块通过 facade-api 只读消费。 +- 如果物理表因 yudao-cloud fork 或旧模块兼容暂落 Content，Content 也只能承载/消费投影，不能绕过 MetaSchema facade-api 修改字段结构、可见性、AI 上下文或导出语义。 +- MetaSchema 版本变化只能让投影、任务、上下文组装、导出和知识确认进入 stale 或 disabled，不能自动改写正文、知识、规划或 Narrative State Canonical。 ## 3. 账号、权限和安全状态 @@ -148,7 +149,7 @@ MetaSchema 是 Admin/Governance 的治理版本，不是 Content 普通内容状 硬约束： - 删除章节必须处理 Block、候选、知识草稿、章节解析结果、规划项、叙事状态和投影影响。 -- 已确认知识不自动回滚；如果来源章节被删除，相关来源快照进入 stale 或 needs_recheck，后续来源型确认和导出按来源状态限制。 +- 已确认知识不自动回滚；如果来源章节被删除，相关来源快照进入 stale 或 disabled，后续来源型确认和导出按来源状态限制。 ### 4.3 正式规划项与叙事状态生命周期 @@ -216,8 +217,7 @@ MetaSchema 是 Admin/Governance 的治理版本，不是 Content 普通内容状 ```text queued -> running -> succeeded -> terminal queued -> canceled -> terminal -running -> failed / canceled / needs_recheck -needs_recheck -> running / failed / canceled +running -> failed / canceled ``` 硬约束： @@ -345,9 +345,8 @@ parse_job:succeeded | 状态 | 含义 | 允许离开方式 | |---|---|---| | prechecking | 绑定前校验 | active / rejected / canceled | -| active | 可作为作品知识来源 | disabled / needs_recheck / revoked | -| needs_recheck | 来源版本、许可、处理状态或 owner 变化 | active / disabled / revoked | -| disabled | 用户停用或系统停用 | active / revoked | +| active | 可作为作品知识来源 | disabled / revoked | +| disabled | 用户停用或系统停用（来源变化时直接决策） | active / revoked | | revoked | 授权撤销、下架或召回 | 终态或重新授权新绑定 | | rejected | 预检失败 | 终态 | | canceled | 用户取消 | 终态 | @@ -386,10 +385,9 @@ parse_job:succeeded |---|---|---| | using_default | 使用系统默认子智能体 | prechecking_override | | prechecking_override | 校验用户智能体或市场智能体是否兼容槽位 | active_override / rejected / canceled | -| active_override | 使用用户选择的子智能体 | needs_recheck / using_default / disabled | -| needs_recheck | 授权、版本、工具、输出合同或来源状态变化 | active_override / using_default / disabled | +| active_override | 使用用户选择的子智能体 | using_default / disabled | | rejected | 预检失败 | using_default | -| disabled | 撤权、越权、输出不合约或安全阻断 | using_default | +| disabled | 撤权、越权、输出不合约或安全阻断（来源变化时直接决策） | using_default | | canceled | 用户取消替换 | using_default | 硬约束： @@ -408,7 +406,7 @@ parse_job:succeeded - Agent 版本只能声明需要的工具、上下文和外发范围；Tool Grant 由 Agent authority 与 Security facade 计算权限上限。 - 运行任务启动时，Security facade 必须结合 actor、owner、slot、agentVersion、来源状态、授权快照、预算和风险状态签发不可变 Agent Runtime Permission Envelope。 - AI Orchestration、Integration 和 tool broker 只能校验并消费运行时权限包，不能自行新增工具、扩大上下文、改变外发策略或复用旧权限包。 -- Tool Grant、授权快照、来源状态、槽位版本或保护节点规则变化后，相关运行任务和槽位绑定必须进入 needs_recheck、回退默认或阻断。 +- Tool Grant、授权快照、来源状态、槽位版本或保护节点规则变化后，相关运行任务和槽位绑定必须进入 disabled、回退默认或阻断。 ## 9. 市场资产、授权、安装和治理状态 @@ -447,10 +445,9 @@ parse_job:succeeded |---|---|---| | available | 可获取 | authorized / unavailable | | authorized | 用户已获得许可 | installed（仅智能体和知识库）/ revoked / expired | -| installed | 智能体或知识库已加入账户可用资产 | linked_or_bound / disabled / revoked / needs_recheck | -| linked_or_bound | 已关联作品槽位或绑定知识来源 | disabled / revoked / needs_recheck | -| disabled | 用户停用或系统停用 | installed / revoked | -| needs_recheck | 许可、版本、来源或 owner 变化 | installed / linked_or_bound / revoked | +| installed | 智能体或知识库已加入账户可用资产 | linked_or_bound / disabled / revoked | +| linked_or_bound | 已关联作品槽位或绑定知识来源 | disabled / revoked | +| disabled | 用户停用或系统停用（来源变化时直接决策） | installed / revoked | | revoked | 授权撤销、下架或召回限制 | 终态或重新授权 | | expired | 授权到期 | 重新授权或终态 | | unavailable | 不可获取 | available | @@ -509,11 +506,10 @@ parse_job:succeeded | 状态 | 含义 | 允许离开方式 | |---|---|---| | active | 目标空间落地 | prechecked / canceled / expired | -| prechecked | 目标 owner 完成预检 | confirmed / rejected / needs_recheck / canceled | +| prechecked | 目标 owner 完成预检 | confirmed / rejected / canceled | | confirmed | 用户确认，准备原子消费 | consumed / failed | | consumed | 写入目标 owner 事实成功 | 终态 | -| needs_recheck | 权限、授权、对象、版本或来源变化 | prechecked / rejected / canceled | -| rejected | 预检失败 | 终态 | +| rejected | 预检失败或权限/授权/对象/版本/来源变化导致不可继续 | 终态 | | failed | 写入失败 | 终态或重新发起 | | canceled | 用户取消 | 终态 | | expired | 超时 | 终态 | @@ -566,10 +562,10 @@ parse_job:succeeded | AI 候选 / 规划候选 | 标记来源不可用，禁用接受或确认 | 自动删除正文 | | 知识草稿 | 禁用来源型确认，保留只读摘要和 lineage | 删除 prior lineage | | 章节解析结果 | 标记需重验或阻断章节确认 | 部分确认 | -| 作品知识来源绑定 | needs_recheck / disabled / revoked | 继续用于新生成 | -| Agent Slot Binding | needs_recheck / 回退默认 / disabled | 扩大权限继续运行 | -| 已安装智能体 / 知识库 | 停用、只读或需重验 | 自动迁移为用户自有资产 | -| 运行中任务 | 取消、阻断或 needs_recheck | 继续消费旧授权快照 | +| 作品知识来源绑定 | disabled / revoked | 继续用于新生成 | +| Agent Slot Binding | 回退默认 / disabled | 扩大权限继续运行 | +| 已安装智能体 / 知识库 | 停用、只读或 disabled | 自动迁移为用户自有资产 | +| 运行中任务 | 取消或阻断 | 继续消费旧授权快照 | | 导出任务 / 下载凭证 | 失败、过滤、重验或失效 | 下载受限内容 | | 个人中心记录 | 展示异常、治理结果和 owner 跳转 | 替 owner 空间写事实 | | 市场记录和发布者记录 | 更新治理结果、申诉入口和影响摘要 | 隐藏审计 | @@ -589,8 +585,7 @@ parse_job:succeeded | draft | 用户选择导出范围 | prechecking / canceled | | prechecking | 权限、owner、来源、许可、导出范围校验 | queued / rejected / canceled | | queued | 已创建导出任务 | running / canceled | -| running | 生成导出包 | ready / failed / canceled / needs_recheck | -| needs_recheck | 完成前状态变化 | running / failed / canceled | +| running | 生成导出包 | ready / failed / canceled | | ready | 导出包生成，等待下载 | downloaded / expired / revoked | | downloaded | 用户已下载 | 终态 | | rejected | 预检失败 | 终态或重新选择范围 | @@ -630,9 +625,8 @@ parse_job:succeeded |---|---|---| | unbound | Muse 用户未绑定网关用户 | binding_requested | | binding_requested | 绑定请求已发起 | bound / binding_failed | -| bound | 绑定有效 | disabled / needs_recheck | -| needs_recheck | 网关状态、权益、配额或归属异常 | bound / disabled / binding_failed | -| disabled | 停用 | bound | +| bound | 绑定有效 | disabled | +| disabled | 停用（网关状态、权益、配额或归属异常时直接停用） | bound | | binding_failed | 绑定失败 | binding_requested | 调用归属状态： diff --git a/design-docs/流程-01B-普通用户操作流程(操作视角).md b/design-docs/流程-01B-普通用户操作流程(操作视角).md index 960a40e4..2ae6aa1f 100644 --- a/design-docs/流程-01B-普通用户操作流程(操作视角).md +++ b/design-docs/流程-01B-普通用户操作流程(操作视角).md @@ -20,7 +20,7 @@ 6. 智能体、知识库和市场是增强路径，不能成为写作前置条件。 7. 用户可替换的是开放槽位中的子智能体，不能替换系统保护节点。 8. 市场资产获取不等于安装；安装不等于绑定作品；绑定不等于写入作品事实。 -9. 接受或合并 AI 候选前，系统必须消费或重算 Candidate Decision Envelope；来源撤权、召回、下架、阻断、owner 缺失或未授权时，候选不能进入正文规范数据(Canonical)。 +9. 接受或合并 AI 候选前，系统必须实时校验来源版本和授权状态；来源撤权、召回、下架、阻断、owner 缺失或未授权时，候选不能进入正文规范数据(Canonical)。 ## 2. 普通用户总流程 @@ -135,7 +135,7 @@ | 修改后合并 | 编辑候选后合并 | 用户修改后的文本进入正文，旧草稿失效并重新提取 | 不继续使用旧知识草稿 | | 丢弃当前建议 | 点击丢弃 | 候选和关联草稿退出当前待处理视图 | 不改正文、不改知识 | -接受和修改后合并不是纯前端动作。用户点击后，系统必须重新确认输出合规、静态检查、质量结果版本、来源状态、授权快照、作品资产 feature gate、目标正文 `expectedRevision` 和幂等结果；任一硬闸门失败时，用户只看到需重验、已阻断或来源不可用，不会写入正文。 +接受和修改后合并不是纯前端动作。用户点击后，系统必须实时校验来源版本和授权状态，包括输出合规、静态检查、质量结果版本、来源状态、授权快照、作品资产 feature gate、目标正文 `expectedRevision` 和幂等结果；任一硬闸门失败时，用户只看到需重验、已阻断或来源不可用，不会写入正文。 辅助动作包括查看来源、展开质量详情、重新生成、取消生成。这些动作不改变正文或知识事实。 @@ -165,10 +165,24 @@ ### 6.1 处理待确认知识 -1. 用户在写作台、候选详情、导入解析或知识与一致性中看到待确认知识提示。 -2. 打开知识草稿详情。 -3. 查看来源、上游来源链路、差异、风险、冲突、来源快照和授权状态。 -4. 用户选择确认来源事实、修改来源事实后确认、改写为用户自有事实、忽略或重新提取。 +知识草稿分为两条路径： + +自动确认路径： + +1. 系统对满足自动确认条件的草稿（来源为用户自有正文 + 无冲突 + 无外部来源 + 置信度超阈值）自动确认入库。 +2. 大部分来自用户正文保存的知识草稿会自动进入局域知识库，用户无需逐条处理。 +3. 用户可在知识面板查看自动确认记录，了解哪些知识被自动入库。 +4. 用户可随时撤回自动确认的知识。 + +手动确认路径： + +1. 不满足自动确认条件的草稿（存在冲突、包含外部来源、置信度不足）进入待确认队列。 +2. 用户在写作台、候选详情、导入解析或知识与一致性中看到待确认知识提示。 +3. 打开知识草稿详情。 +4. 查看来源、上游来源链路、差异、风险、冲突、来源快照和授权状态。 +5. 用户选择确认来源事实、修改来源事实后确认、改写为用户自有事实、忽略或重新提取。 + +批量确认：低风险草稿（无冲突、无外部来源、置信度高）支持批量确认。 成功终态：用户确认后的知识进入正式作品知识，可参与检索、图查询、质量门控和后续生成。 diff --git a/design-docs/流程-02B-普通用户系统处理流程(系统视角).md b/design-docs/流程-02B-普通用户系统处理流程(系统视角).md index 3e332558..5c1365a9 100644 --- a/design-docs/流程-02B-普通用户系统处理流程(系统视角).md +++ b/design-docs/流程-02B-普通用户系统处理流程(系统视角).md @@ -20,13 +20,13 @@ 6. 市场授权、安装、绑定、用于生成和写入事实必须分层。 7. 来源撤权、下架、召回、版本变化和 owner 缺失必须传播到所有引用位置。 8. 跨空间 handoff 不能成为绕过权限、预检、确认和审计的通道。 -9. Accept / Merge 写入 Canonical 前必须消费或重算 Candidate Decision Envelope，硬闸门失败时不能只靠前端提示放行。 +9. Accept / Merge 写入 Canonical 前必须实时校验候选记录的 source_version 与当前来源状态，硬闸门失败时不能只靠前端提示放行。 ## 2. 普通用户系统总链路 用户创作和资产使用的通用链路： -`认证会话 -> 对象权限校验 -> owner 校验 -> 授权快照 -> 来源状态校验 -> 任务或候选创建 -> Shadow 写入 -> 用户决策 -> 决策 Envelope 重验 -> Canonical / Archive 写入 -> 投影和记录 -> 用量归属 -> 失败反馈` +`认证会话 -> 对象权限校验 -> owner 校验 -> 授权快照 -> 来源状态校验 -> 任务或候选创建 -> Shadow 写入 -> 用户决策 -> 来源版本实时校验 -> Canonical / Archive 写入 -> 投影和记录 -> 用量归属 -> 失败反馈` 系统处理分层： @@ -100,7 +100,9 @@ 系统链路： -`用户意图 -> 权限校验 -> 来源状态校验 -> 上下文组装 -> 输入合规 -> 写作子智能体执行 -> 质量门控 -> 输出合规 -> Shadow 候选写入 -> 用量归属 -> 返回候选` +`用户意图 -> 权限校验 -> 来源状态校验 -> 上下文组装 -> 输入合规 -> 写作子智能体执行 -> 质量门控 -> 输出合规 -> Shadow 候选写入（记录 source_version） -> 用量归属 -> 返回候选` + +候选创建时必须记录当前使用的各来源版本（source_version），用于接受时实时校验来源是否已变化。 上下文只允许使用： @@ -135,14 +137,14 @@ 系统链路： -`查询候选 -> 消费或重算 Candidate Decision Envelope -> 校验候选状态 -> 校验文本块 expectedRevision -> 校验来源状态和授权快照 -> 写 Canonical 正文 -> 候选进入 Archive -> 关联草稿保持待确认 -> 写记录和投影事件` +`查询候选 -> 校验候选 source_version 与当前来源状态 -> 校验候选状态 -> 校验文本块 expectedRevision -> 校验来源状态和授权快照 -> 写 Canonical 正文 -> 候选进入 Archive -> 关联草稿保持待确认 -> 写记录和投影事件` 处理规则： 1. 接受只改变正文事实。 2. 关联知识草稿不自动进入正式知识。 3. 如果候选带有外部或市场来源，正文保存后的重提取必须继承 lineage。 -4. Candidate Decision Envelope 必须覆盖输出合规、静态检查、质量结果版本、SourceStatus、SourceEventType 影响、Action Policy、Authorization Snapshot、作品资产 feature gate、`expectedRevision` 和命令幂等结果。 +4. 接受时系统实时校验：候选记录的 source_version 与当前来源状态对比，同时校验输出合规、静态检查、质量结果版本、SourceStatus、Authorization Snapshot、作品资产 feature gate、`expectedRevision` 和命令幂等结果。如果来源已变化，返回错误，前端提示用户重新生成。 5. 候选正文 lineage 中存在 revoked、recalled、delisted、blocked、owner_missing 或 unauthorized 来源时，必须阻断进入 Canonical。 失败处理：候选过期、文本冲突、来源失效或合规阻断时，接受禁用。 @@ -151,7 +153,7 @@ 系统链路： -`用户编辑最终文本 -> 消费或重算 Candidate Decision Envelope -> 校验候选和文本块 expectedRevision -> 校验最终正文输出合规、静态检查、来源和授权 -> 写 Canonical 正文 -> 旧知识草稿失效 -> 发布重提取事件 -> 候选进入 Archive` +`用户编辑最终文本 -> 校验候选 source_version 与当前来源状态 -> 校验候选和文本块 expectedRevision -> 校验最终正文输出合规、静态检查、来源和授权 -> 写 Canonical 正文 -> 旧知识草稿失效 -> 发布重提取事件 -> 候选进入 Archive` 处理规则： @@ -189,7 +191,26 @@ 3. 来源快照：生成草稿时的正文片段、版本、章节和授权状态。 4. 风险标记：冲突、重复、低置信、来源不可用、合规风险。 -确认规则： +自动确认判定逻辑： + +草稿生成后，系统立即执行自动确认判定： + +| 条件 | 判定规则 | +|---|---| +| 来源为用户自有正文 | 草稿提取自当前作品用户保存的正文，lineage 中不包含外部来源 | +| 无冲突 | 草稿内容与现有正式知识无矛盾或重复 | +| 无外部来源 | 草稿 lineage 中不包含市场资产、授权知识库或其他外部来源 | +| 置信度超阈值 | 系统提取置信度达到自动确认阈值 | + +四个条件同时满足时，系统自动将草稿确认进入 Canonical 知识（局域知识库），标记确认方式为"自动确认"。不满足任一条件时，草稿进入待确认队列等待用户手动处理。 + +自动确认后的处理： +- 写入 Canonical 知识，标记 `confirm_mode = auto`。 +- 用户可在知识面板查看自动确认记录。 +- 用户可随时撤回自动确认的知识，撤回后知识退出局域知识库，草稿回到已归档状态。 +- 自动确认不适用于包含外部来源 lineage 的草稿，这类草稿必须由用户手动确认。 + +手动确认规则： | 用户动作 | 系统处理 | 限制 | |---|---|---| @@ -390,8 +411,8 @@ | 层级 | 含义 | 示例 | |---|---|---| | SourceStatus | 来源当前事实状态，由来源 owner 维护 | active、stale、revoked、delisted、recalled、owner_missing、blocked、unauthorized | -| SourceEventType | 导致状态或策略变化的事件类型 | source_updated、source_revoked、asset_delisted、asset_recalled、asset_blocked、owner_missing、authorization_revoked、authorization_expired、license_changed、processing_failed、recheck_required | -| Action Policy | 针对某个用途的动作结论，不是来源事实本身 | allowed、read_only、needs_recheck、blocked | +| SourceEventType | 导致状态或策略变化的事件类型 | source_updated、source_revoked、asset_delisted、asset_recalled、asset_blocked、owner_missing、authorization_revoked、authorization_expired、license_changed、processing_failed | +| Action Policy | 针对某个用途的动作结论，不是来源事实本身 | allowed、read_only、blocked | 同一 SourceStatus 在不同用途下可以得到不同 Action Policy。例如 delisted 可能允许已授权阅读记录继续展示，但阻断新获取、新生成、新绑定、来源型确认、受限导出和候选接受。 @@ -410,21 +431,27 @@ | 目标 | 系统处理 | 事实影响 | |---|---|---| -| 未确认 AI 候选 / 规划候选 | 标记来源不可用，禁用接受或确认，并让 Candidate Decision Envelope 失效或需重算 | 正式事实不变 | +| 未确认 AI 候选 / 规划候选 | 标记来源不可用，禁用接受或确认 | 正式事实不变 | | 知识草稿 / Local KB 来源型确认 | 禁用来源型确认，保留只读摘要、lineage、授权快照和证明链 | 正式知识不变 | | 生成上下文 / Context Assembly Snapshot | 从后续上下文中剔除或要求重验 | 新生成受限 | -| 作品知识来源绑定 | 进入需重验、停用或只读 | 新生成受限 | -| 账户授权记录 / 安装记录 | 标记撤权、召回、下架或需重验 | 新安装、新绑定和新调用受限 | -| 已安装智能体 / 知识库 | 停用安装、进入只读或需重验 | 已绑定槽位或知识来源待刷新 | -| 作品智能体槽位绑定 | 进入需重验、停用或回退系统默认子智能体 | 新生成受限或回退默认能力 | -| 知识库来源绑定 | 进入需重验、停用或只读 | 检索、生成和导出受限 | +| 作品知识来源绑定 | 来源仍可用 → 保持 active；来源不可用 → 转 disabled | 新生成受限 | +| 账户授权记录 / 安装记录 | 标记撤权、召回或下架 | 新安装、新绑定和新调用受限 | +| 已安装智能体 / 知识库 | 来源仍可用 → 保持 active；来源不可用 → 停用安装 | 已绑定槽位或知识来源待刷新 | +| 作品智能体槽位绑定 | 来源仍可用 → 保持 active；来源不可用 → 停用或回退系统默认子智能体 | 新生成受限或回退默认能力 | +| 知识库来源绑定 | 来源仍可用 → 保持 active；来源不可用 → 转 disabled | 检索、生成和导出受限 | | 运行中任务 / 排队任务 | 取消、阻断或重新校验上下文 | 未完成任务不写事实 | -| 导出任务 / download credential 下载凭证 | 重新校验导出范围和许可；已签发但未使用或未过期的下载凭证必须作废或进入需重验 | 导出包可能失败、过滤或禁止下载 | +| 导出任务 / download credential 下载凭证 | 重新校验导出范围和许可；已签发但未使用或未过期的下载凭证必须作废 | 导出包可能失败、过滤或禁止下载 | | 个人中心记录 | 刷新授权和治理状态 | 只更新展示和跳转 | | 用户通知 / 治理结果投影 | 展示管理员治理结论、影响范围和可用动作 | 只更新用户可见状态 | 已确认 Canonical 不自动回滚；受限来源不得继续进入后续生成上下文、绑定、导出许可范围、已签发下载凭证、候选接受或新的来源型知识确认。 +来源变化时的直接决策逻辑（不经过中间状态）： + +1. 来源变化事件到达时，查询所有依赖该来源的活跃绑定（知识来源绑定、智能体槽位绑定、安装记录等）。 +2. 对每个绑定直接判定：来源仍可用（授权有效、未下架、未召回、版本兼容）→ 保持 active；来源不可用 → 转 disabled。 +3. 通知用户受影响的绑定状态变化，展示具体原因和可用动作。 + ## 15. 个人中心、账户安全和用量归属链路 ### 15.1 用量归属和 owner 跳转 @@ -476,7 +503,7 @@ 3. 导出任务必须生成 included/excluded manifest，列出包含内容、排除内容、排除原因、来源状态、授权快照和用户确认记录。 4. 来源撤权、下架、召回、合规阻断或权限变化时，导出任务失败、过滤受限内容或要求用户重新选择范围；受限来源被过滤时不能静默导出。 5. 用户取消导出只取消未完成任务；已经生成的导出包必须进入过期或作废状态。 -6. 已签发但未使用或未过期的下载凭证遇到权限、来源、任务状态或授权快照变化时必须 revoked / needs_recheck。 +6. 已签发但未使用或未过期的下载凭证遇到权限、来源、任务状态或授权快照变化时必须 revoked。 7. 管理员只能看到脱敏导出摘要和失败原因，不能通过任务治理下载用户导出包。 失败处理：下载凭证过期、重复使用、actor 不匹配、任务已作废或授权快照不匹配时，拒绝下载并写安全审计。