zizi-al/oh-my-muse

Fork 0

zizi e50aa02b41 提交整体设计文档一致性修复

2026-05-24 01:14:34 +08:00

26 KiB

Raw Blame History

专题-03：AI 编排、上下文与质量评测实现规范

版本：v2
更新日期：2026-05-23
目标读者：产品 / 架构 / 后端 / 前端 / 测试
阅读时间：30-45 分钟
边界说明：本文件承接阶段 1~5，定义 AI 编排、上下文组装、检索、运行权限、来源追踪、风险路由和质量评测的产品架构合同。它不定义精确数据库表、后端 endpoint、前端组件和运维门禁；这些由后续前端/后端阶段承接。

1. 归属范围

本文件回答 AI 链路“谁能读什么、怎么组上下文、哪些节点不可替换、结果如何进入 Shadow、风险和质量如何解释”。

主题	本文件负责	不负责
AI 任务编排	系统功能链路、保护节点、开放替换槽位、失败边界	具体服务类、队列实现、接口路径
运行时权限	Agent Runtime Permission Envelope 的语义和校验点	权限表结构、鉴权框架实现
上下文组装	Layer、授权快照、来源状态、Token 预算和用户可解释摘要	Prompt 具体全文、前端调试面板
检索和图查询	RAG / Graph Provider 的事实边界、降级和来源要求	向量库或图数据库选型细节
风险路由	合规、来源、权限、质量风险对候选状态的影响	安全模型供应商实现
质量评测	质量结果如何绑定候选、上下文和配置快照	质量门控 UI 与策略细则，见 `专题-04`

核心 owner：

对象	Owner BC	本专题中的使用方式
AI Task / Context Snapshot / Quality Result	AI Orchestration BC	创建、运行、归档和解释 AI 任务
Agent / Agent Version / Agent Runtime Permission Envelope	Agent BC	提供可运行能力和权限包
Work / Chapter / Block / Block Source Attribution	Work/Content BC	提供正文事实、写入锚点和来源归因
Local KB / Knowledge Draft / Knowledge Source Binding	Knowledge BC	提供正式知识、待确认草稿和知识来源状态
Marketplace Asset / License / Install / Source Status Event	Marketplace/Asset BC	提供市场授权、安装和召回事件
New-API Binding / Integration Call Log	Integration BC	执行模型网关调用和最小调用摘要

2. 系统功能链路

Muse 的 AI 能力不是“前端按钮直接调某个智能体”，而是系统预编排功能链路。用户只能在开放槽位中替换子智能体，不能替换保护节点。

2.1 标准链路

用户意图
-> 输入合规
-> 权限和来源预检
-> Agent Runtime Permission Envelope
-> 上下文组装
-> 开放槽位子智能体运行
-> AI Task Result
-> Provisional AI Suggestion / Shadow Candidate
-> 静态检查和来源状态校验
-> 质量门控与有限重写
-> 输出合规
-> Candidate Decision Envelope
-> 可展示的 Shadow 对象
-> 用户决策

任何链路都必须满足：

运行前固化 actor、work、chapter/block、agent version、slot、tool grant、context scope、egress policy、budget、authorization snapshot 和 trace。
任务成功只能先生成 Provisional AI Suggestion、Knowledge Draft、Planning Candidate、Risk Marker、Quality Result 或记录，经静态检查、来源状态校验、质量门控、输出合规和风险路由后，才成为可展示或可接受的 Shadow 对象。
任务失败不能静默降级为“低质量但可接受候选”。
用户接受候选只写正文和候选归档，不写 Local KB。

2.2 不可替换保护节点

以下节点属于系统保护节点，用户智能体、市场智能体和工作流智能体都不能替换：

保护节点	作用	失败结果
输入合规	检查用户输入、导入文本和上下文请求是否可处理	阻断任务或要求用户修改
权限过滤	校验作品、知识库、市场资产、智能体、工具和外发权限	阻断读取或剔除来源
来源状态校验	校验 active / stale / revoked / delisted / recalled / blocked / owner_missing / unauthorized 等状态	禁用旧来源的新使用
拆分切块	对导入、解析、入 RAG 的文本做系统级分块	任务失败或等待重试
入 RAG	将已确认内容投影到检索索引	异步失败，不反写 Canonical
语义安全围栏	限制越界、违规、隐私和 prompt 注入风险	阻断或生成风险标记
静态检查	检查输出结构、字段、schema 和必要来源	失败不得进入可接受候选
Shadow -> Canonical	用户确认和正文保存的唯一正式入口	不允许智能体绕过
质量门控	对候选做关键维度评分和有限重写	不合格候选不得伪装为通过
输出合规	检查交付给用户前的文本、来源和安全状态	阻断展示或要求重生成

2.3 开放替换槽位

开放槽位只能替换“能力子智能体”，不能改变系统链路控制权。

槽位	允许替换	不允许替换
Writing Agent	生成、续写、扩写、润色、纠错、去 AI 味的子智能体	输入/输出合规、质量门控、Shadow 写入规则
Analysis Agent	目标分析、实体解析、候选草稿提取的子智能体	拆分切块、入 RAG、来源状态校验
Detection Agent	风险识别、一致性检查、角色声音检查的子智能体	语义安全围栏、静态检查、权限过滤

3. Agent Runtime Permission Envelope

每次试用、生成、解析、检测和质量评测都必须有运行时权限包。前端、Prompt、模型输出和智能体自述权限无效。

最小语义：

字段语义	要求
actor	用户、管理员或系统服务身份
work / chapter / block	当前任务作用范围
slot	本次调用使用的能力槽位
agentVersion	实际运行的智能体版本
toolGrantSet	可调用工具授权集合，逐项约束动作、目的、输入、输出和副作用
allowedContextScopes	可读上下文范围，包括正文、Local KB、用户知识库、全局知识库、市场资产
egressPolicy	是否允许外发、允许外发到哪些集成、是否需要脱敏
budget	Token、重试、时间和费用预算
authorizationSnapshot	本次读取和外发使用的授权快照
sourceSnapshot	本次上下文来源摘要和版本
auditRequirement	是否必须记录、脱敏或进入高危审计

执行要求：

所有工具调用、上下文读取、检索和外部请求必须经过服务端 tool broker 或等价执行边界校验。
权限包只能收紧，不能被用户智能体、市场智能体或工作流步骤扩大。
任务中途来源撤权、召回、owner 缺失或安全阻断时，任务进入 needs_recheck、failed 或候选 invalidated，不得继续消费旧权限包。
权限包摘要进入任务记录和质量评测输入，便于复盘。

3.1 Tool Grant 语义

工具授权不是简单的工具名 allowlist。每个可调用工具必须绑定：

语义	要求
tool / action	允许调用的工具和动作，不能用通配符扩大权限
purpose	本次调用目的，例如检索、切块、入 RAG、评估、导出预检
inputSources	工具可读取的来源范围和来源状态
outputSinks	工具结果允许写入的位置，例如 Shadow、任务记录、投影索引、审计摘要
sideEffectPolicy	是否允许副作用；允许时必须说明幂等键、补偿或回滚方式
egressDestination	是否外发，以及允许的集成目标
budget	单工具 token、次数、时间和费用预算
approval	是否需要管理员、用户或系统预检批准
auditClass	普通审计、敏感审计或高危审计

配置型智能体和工作流型智能体只能消费已授予的 Tool Grant，不能在 Prompt、市场描述或工作流节点中自声明新增工具权限。

4. 上下文组装

上下文组装(Context Assembly)是 AI Orchestration 的核心内部合同。它只能读取 owner BC 暴露的正式数据、授权资料和明确允许的待审对象。

4.1 请求语义

上下文组装输入至少包含：

语义	要求
actor / work / target	当前用户、作品、章节、Block 或任务目标
scenario	continuation / rewrite / expansion / polish / extraction / full_parse / planning / validation / consistency_check / quality_gate
userIntent	用户当前意图或系统任务目标
agentSlot	本次使用的能力槽位
runtimePermissionEnvelope	运行时权限包引用
tokenBudget	输入输出预算和截断策略
requiredSources	必须读取的正文、规划、知识或外部资料范围
forbiddenSources	已撤权、下架、召回、blocked、owner_missing 或未授权来源
debugVisibility	是否允许返回调试快照

4.2 四层上下文

Layer	内容	可省略性	约束
Layer 0 当前输入	用户意图、当前文本、目标章节、目标 Block revision	不可省略	必须与 expectedRevision 或任务版本一致
Layer 1 近邻正文	当前章节、相邻 Block、章节目标、近期叙事状态	续写/改写不可省略	来源必须可追溯到 Work/Content
Layer 2 作品事实	Local KB、正式规划、角色关系、事件时间线、Narrative State	一致性/规划不可省略	只能读取 Canonical
Layer 3 授权资料	用户知识库、全局知识库、已安装知识库、允许的市场资产摘要	可按场景省略	必须绑定 Authorization Snapshot 和来源状态

Token 预算顺序：

保留输出预算。
Layer 0 必须完整保留。
Layer 1 优先于 Layer 2，Layer 2 优先于 Layer 3。
超限时先摘要化低优先级资料，再截断。
被省略资料进入 omittedSources，原因只能是 token_budget、not_authorized、stale_source、low_confidence、not_relevant 或 blocked。

4.3 来源和授权

每个进入上下文的外部或授权来源必须携带 Authorization Snapshot 或等价不可变指纹，最小语义包括：

语义	要求
actor / owner	本次使用者和来源 owner
source object / version	来源对象、版本和类型
license / policy	授权、许可、使用策略和限制
allowedPurpose	允许用途，例如上下文检索、生成参考、绑定、导出、确认知识
forbiddenPurpose	明确禁止用途，例如市场作品资产模板化、受限导出、二次分发
status	active / stale / revoked / delisted / recalled / blocked / owner_missing / unauthorized
checkedAt	校验时间
expiresAt / recheckCondition	过期时间或需要重验的条件
displaySummary	可展示给用户的来源摘要

授权校验必须按用途执行。允许“阅读”的授权不等于允许进入 AI 上下文，允许“上下文检索”的授权不等于允许导出，允许“生成参考”的授权也不等于允许确认知识。

以下结果不得进入 Prompt：

缺来源对象。
缺授权快照。
来源状态为 revoked、delisted、recalled、blocked、owner_missing 或 unauthorized。
检索结果只说明“来自某索引”，但无法回到 owner BC。
市场作品资产在 feature gate 未开启时作为模板、参考来源或 AI 上下文。

4.4 用户可解释响应

普通用户只能看到创作语言摘要，不看到完整 Prompt、密钥、调试层或供应商响应。

AI 结果必须能解释：

使用了哪个智能体或系统链路。
参考了哪些正文、规划、Local KB 或授权知识。
哪些来源因撤权、召回、未授权或预算被排除。
是否触发质量门控、重写、风险标记或输出阻断。
下一步用户可以接受、修改、丢弃、重生成或进入知识确认。

5. 检索和图查询

5.1 RAG 定位

RAG / RAGFlow 是检索基座，不是 Muse 事实源。它只能消费 Work/Content、Knowledge、Marketplace/Asset 等 owner BC 的正式数据或授权资料投影，不能反向决定作品事实。

允许进入正式检索的来源：

来源	是否可进正式检索	约束
当前作品正文 Canonical	是	需要 revision 和 Block Source Attribution
Local KB Canonical	是	需要知识版本和来源状态
正式规划项 / Narrative State	是	需要 Work/Content owner 版本
用户知识库 / 全局知识库 / 已安装知识库	是	需要 Authorization Snapshot
AI Suggestion / Knowledge Draft / Planning Candidate	默认否	只能用于明确标记的预览、校验或审计
市场作品资产	阶段 6 否	feature gate 关闭，只能阅读、收藏和授权记录

5.2 检索失败边界

场景	系统行为
检索不可用、超时或认证失败	阻断依赖检索的生成、提取、规划和一致性检查
单条结果无权限	丢弃并记录摘要
单条结果缺来源	丢弃，不进入上下文
投影落后	尝试 owner BC overlay；仍无法补齐则返回可恢复失败
来源撤权或召回	禁止新使用，相关候选或草稿进入 invalidated / needs_recheck

RAG 不可用不得阻止用户保存正文、查看已确认正文、查看已确认知识或处理本地 UI 状态。

5.3 检索结果合同

阶段 6 不规定具体图数据库、Graph Provider、queryType 或 fallback 实现。后续后端阶段可以选择 RAGFlow GraphRAG、图数据库或混合检索，但交给 AI Orchestration 的检索结果合同必须稳定。

每条检索结果至少包含：

语义	要求
sourceOwner	来源 owner BC
sourceObject / sourceVersion	来源对象、版本和类型
evidence	证据摘要、定位和可解释引用
confidence	置信度与计算来源
authorizationSnapshot	本次用途的授权快照
sourceStatus	active / stale / revoked / delisted / recalled / blocked / owner_missing / unauthorized
allowedPurpose	当前结果允许参与的用途

缺 source、version、evidence、confidence、authorizationSnapshot 或 sourceStatus 的结果不得进入上下文。检索层不能把“查到了”解释成“可使用”。

6. 生成、解析和检测结果

6.1 生成结果

生成任务只能输出：

AI Suggestion。
Candidate Quality Result。
Risk Marker。
Source Summary。
可选 Knowledge Draft。

硬约束：

AI Suggestion 进入 Shadow，等待用户接受、修改后合并或丢弃。
接受 AI Suggestion 只写正文和候选归档，不自动确认 Knowledge Draft。
如果候选使用外部或授权来源，接受后必须写 Block Source Attribution。
候选来源撤权、召回、owner 缺失、版本冲突或合规阻断时，候选进入 invalidated，不能继续接受。

6.2 解析结果

全书解析(Full Parse)必须按阶段 4 和架构 04 的章节审阅边界处理：

Parse Job -> Chapter Parse Result -> Chapter Review -> Knowledge Draft

约束：

AI Orchestration 拥有 Parse Job 和 Chapter Parse Result。
用户确认章节审阅只表示“这一章解析结果可进入后续知识草稿处理”。
Knowledge BC 在章节审阅确认后创建或更新 Knowledge Draft。
章节审阅不写 Canonical 知识，不写 Narrative State。
拆分切块、静态检查和入 RAG 是保护节点，用户智能体不可替换。

6.3 检测结果

检测类任务可以输出：

Consistency Check Result。
Risk Marker。
Source Conflict。
Quality Dimension Result。
修复建议摘要。

检测结果不直接改正文、知识、规划或市场资产。用户必须在对应 owner 空间中决策。

7. Risk Routing

风险路由决定 AI 结果是否可展示、可接受、需重验或阻断。

风险类型	例子	系统行为
source_stale	来源版本变化、source hash 不匹配	禁用确认或要求重新生成
source_revoked	来源主动撤权	禁止新生成、新绑定、新来源型确认和受限导出
authorization_revoked	授权撤销	禁止继续使用该授权快照，相关候选、绑定、导出和下载凭证进入阻断或重验
asset_recalled	市场召回	禁止新生成、新绑定、新来源型确认和受限导出，并传播到已安装、已绑定、运行任务和未确认对象
source_delisted	市场下架	禁止新获取、新安装、新绑定和新导出，已授权阅读按治理策略限制
permission_denied	用户无权读取作品、知识库或智能体	阻断任务
safety_blocked	输入/输出合规失败、语义安全围栏阻断	阻断候选展示或接受
schema_invalid	输出结构不符合合同	重试或失败
quality_critical_failed	叙事质量关键维度不达标	在 Shadow 内有限重写；仍失败则标记高风险、需修改或按策略阻断
low_confidence	证据不足或置信度低	展示风险，由用户判断

风险等级：

等级	展示	是否允许用户接受
info	可解释提示	是
warning	明确展示风险和来源	是
high	要求显式确认或修改后合并	视场景
critical	阻断接受、绑定、导出或确认	否

风险标记属于 Shadow 解释，不是 Canonical 事实。风险、来源证据和用户决策必须进入 Archive 或审计摘要。

7.1 Candidate Decision Envelope

候选是否可展示、可接受、需重验或阻断，必须由 Candidate Decision Envelope 合并判断。它不是新的事实 owner，而是 AI Orchestration 对来源、权限、合规、质量和风险路由结果的决策快照。

最小输入：

Source Status / Authorization Snapshot / Work Asset feature gate。
输入合规、输出合规、语义安全围栏和静态检查结果。
Candidate Quality Result id、qualityPolicyVersion 和评分时间。
Risk Marker。
目标 Block expectedRevision、候选版本和命令幂等上下文。

最小输出：

语义	要求
decisionState	`displayable` / `acceptable` / `requires_explicit_confirm` / `needs_recheck` / `blocked` / `invalidated`
acceptability	可接受、只能修改后合并、需重验、不可接受
blockingReasons	阻断原因和来源摘要
userActions	接受、修改后合并、丢弃、重生成、重验来源等可用动作
auditSummary	决策输入版本、质量结果版本、授权快照、来源状态、expectedRevision 和幂等摘要

7.2 决策优先级

Candidate Decision Envelope 按以下优先级合并，前面的硬阻断不能被后面的质量评分放开：

合规、安全、语义围栏、静态检查硬阻断。
来源 revoked、recalled、delisted、blocked、owner_missing、unauthorized 或授权快照无效。
市场作品资产 feature gate、owner 预检或 workAssetUsePrecheckId 缺失。
Block revision、来源 stale、策略版本变化或授权过期导致的 needs_recheck。
质量门控服务不可用、超时或关键叙事维度无法评估。
叙事质量 high risk、低置信度和普通 warning。
pass / rewritten_pass。

8. 质量评测合同

质量评测分两层：

运行时质量门控：对单次候选交付前做关键维度评分和有限重写。
离线评估：对智能体、Prompt、上下文策略和质量策略版本做评估集回归。

本文件只定义输入和追踪合同，质量门控策略、创作健康度展示和有限重写细则由 专题-04 承接。

质量评测输入必须绑定：

AI Task id。
Candidate id 或评估样本 id。
Agent Version。
Prompt Template / Prompt Version。
Context Assembly Snapshot。
Authorization Snapshot。
Source Summary。
Quality Policy Version。
New-API Binding 摘要。
Runtime Permission Envelope 摘要。

质量评测输出必须至少包含：

结果	要求
hardBlockDimensions	来源安全、输出合规、静态结构等硬阻断结果
criticalDimensions	叙事关键维度评分、是否触发重写、最终状态
nonCriticalDimensions	非关键维度评分和建议
riskMarkers	风险标记和来源摘要
rewriteCount	已触发重写次数
qualityState	pass / rewritten_pass / high_risk / blocked / unavailable / needs_recheck
userExplanation	面向普通用户的创作语言解释

9. New-API 边界

New-API 是外部模型网关 authority。Muse 只保存本地绑定引用、幂等键、调用归属、最小调用摘要和异常状态。

允许保存：

字段语义	说明
newApiBindingRef	Muse 侧绑定引用
newApiCredentialRef	指向密钥管理系统的凭据引用，不含明文
requestTrace	New-API 返回的请求引用或 trace，必须是白名单字段且已脱敏
modelAlias	使用的模型别名或能力标签
tokenSummary	输入/输出 token 摘要
latencyMs	延迟
errorClass	脱敏后的错误分类
taskId / actor / workId	调用归属

禁止保存：

New-API token 明文。
供应商密钥。
请求头、完整请求体、完整响应体。
完整模型供应商路由表。
New-API 成本账本 authority。
未脱敏 Prompt、候选全文、私有正文或外部知识全文。

用户可见错误只能展示分类、可理解摘要和下一步动作，不展示供应商原始错误、密钥、完整 Prompt、请求体、响应体或外部知识全文。

执行链：

AI Orchestration -> Integration Execution Facade -> New-API -> AI Task Result

归属链：

Integration Call Log -> Account/Usage/Audit -> Usage Record / Entitlement Snapshot / Personal Center Summary

10. Source Status Event

来源状态变化必须通过 Source Status Event 传播到候选、草稿、绑定、安装、运行任务、导出任务、下载凭证、个人中心和市场记录。具体状态机以 架构-04 为准；本专题只规定 AI 编排和质量链路必须消费这些事件，不能继续使用旧来源。

这里必须区分三层语义，不能把 allowed、blocked、needs_recheck 这类动作结论简化成无法解释的来源状态。

层级	归属	含义	示例
SourceStatus	来源 owner / Marketplace/Asset BC	来源对象当前可证明的事实状态	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

同一个 SourceStatus 可以按用途得到不同 Action Policy；例如 delisted 可允许用户查看历史授权记录，但阻断新安装、新绑定、新生成、新导出、来源型确认和候选接受。

事件最小语义：

语义	要求
sourceOwner	来源 owner BC
sourceId / sourceVersion	来源对象和版本
sourceStatus	事件后的 SourceStatus
eventType	SourceEventType，例如 source_updated / source_revoked / authorization_revoked / authorization_expired / asset_delisted / asset_recalled / asset_blocked / owner_missing / license_changed / processing_failed / recheck_required
actionPolicies	按用途计算的 Action Policy，例如 read、generate、bind、confirm_source_fact、accept_candidate、export、download
reason	可解释原因
idempotencyKey	幂等键
impactScope	影响对象范围
emittedAt	事件时间

传播目标：

目标对象	Owner	最小状态变化	失败策略
AI Suggestion / Planning Candidate	AI Orchestration BC	needs_recheck / invalidated / blocked	fail-default 禁用接受或确认
Knowledge Draft	Knowledge BC	needs_recheck / unconfirmable / invalidated	禁用来源型确认
Chapter Parse Result	AI Orchestration BC	needs_recheck / stale	禁用章节审阅确认
Context Assembly Snapshot	AI Orchestration BC	stale / blocked / needs_recheck	后续生成不得继续消费旧上下文
Knowledge Source Binding	Knowledge BC	stale / revoked / blocked	禁用新检索、新绑定或新确认
Agent Slot Binding	Agent BC	needs_recheck / disabled	禁用运行或要求重新预检
Installed Agent / Installed KB	Marketplace/Asset BC	disabled / limited / recalled	禁用新使用，保留授权记录
Running Task	AI Orchestration BC	cancelling / failed / needs_recheck	停止消费旧权限包
Export Task / download credential 下载凭证	Export / Delivery owner	disabled / revoked / needs_recheck	禁用下载或要求导出重验；已签发但未使用或未过期凭证必须作废或重验
Personal Center Summary	Account read model	risk_summary_updated	只展示摘要和跳转，不成为事实 owner
Marketplace / Publisher Record	Marketplace/Asset BC	delisted / recalled / appealable	进入治理、申诉或下架链路

Source Status Event 必须幂等处理，传播失败时要可重试；在传播完成前，新使用一律 fail-default 禁用，并暴露可重试治理入口。

11. 验收清单

阶段 6 后，本专题必须满足：

不出现 AI 绕过用户决策写入 Canonical 的链路。
不出现接受候选同时写入 Local KB 的链路。
不出现用户智能体替换保护节点的链路。
任何外部或授权来源进入上下文时，都有 Authorization Snapshot 和 Source Status。
任何含 AI、市场、外部知识或授权知识来源的正文写入，都能落到 Block Source Attribution。
New-API 只作为外部网关，不成为 Muse 本地模型路由和成本 authority。
质量评测结果能被 专题-04 的质量门控和创作健康度直接消费。
Candidate Decision Envelope 能统一合并来源、权限、合规、质量和风险路由结果。

12. 关联阅读

产品-01-产品定位与核心价值.md
产品-02-核心功能与交互边界.md
产品-03-用户旅程与操作流程.md
流程-01B-普通用户操作流程(操作视角).md
流程-02B-普通用户系统处理流程(系统视角).md
架构-01-系统全貌与边界上下文.md
架构-02-核心数据结构与双轨模型.md
架构-04-状态机与约束清单.md
专题-04-生成质量门控与创作健康度设计方案

26 KiB Raw Blame History Unescape Escape