oh-my-muse/docs/agent-specs/2026-07-07-2.0.0单人版改造-review.md

2.0.0 单人版改造方案(评审版)

• 版本:v0.2(v0.1 经 Codex + Opus 双对抗评审后修订;修订记录见 §13)
• 日期:2026-07-07
• 目标读者:项目所有者(唯一评审人)/ 后续执行 agent
• 边界说明:本文是 2.0.0 阶段一「单人版改造」的整体方案,覆盖范围界定、目标架构、改造分块、功能清单、步骤与验证。它修订(supersede)专题-05 与 ADR 的若干结论(见 §3),不改变 Shadow→Canonical 双轨主权、Accept Suggestion 唯一入口、fail-closed 等最高不变式。
• 配套:执行计划 · HTML 一页图(边界与节奏概览,细节以本文为准)

---

一、意图与目标

Muse 1.0.0 按「多角色资产流通平台」的完整设计推进,后端已达 ~80% 真实实现,但代价是:三个外部 AI 服务(New-API、RAGFlow、Dify)、市场/会员/治理等大量多用户面,而唯一的真实用户只有项目所有者本人。剩余缺口(市场生产端、个人中心深面、admin e2e、meta all-real)恰好也集中在多用户向——继续按原范围推进,是在为不存在的用户还债。

阶段一(2.0.0)把产品目标收缩为:单人自用的长篇创作工具。三个子目标:

1. 外部依赖收敛:Muse 代码只直连 Dify 一个外部服务(生成、导入解析、Agent 运行时、知识库检索全走 Dify;模型 provider 配在 Dify 内,上游可指向现有 New-API 网关,对 Muse 透明)。基础设施收敛为 PostgreSQL + Redis + Dify。收敛对象包含 yudao 继承的 9 个厂商 AI 脚手架(见 §2.10,当前默认全开,必须显式关闭)。
2. 多用户/平台功能隔离:市场、会员权益/配额、市场治理、多租户治理等一律搁置——后端从单体装配中摘除(market)或用既有机制关闭(member 子域),前端删除入口;代码保留在仓库,恢复走 git 与装配回滚。
3. 打磨单人创作体验:先把地基收干净(1a),再按优先级补齐单人主线缺口(1b:规划候选、文风检查、知识失败恢复、版本恢复、SSE 接组件)。

非目标(阶段一明确不做):多用户/多租户产品化、支付/会员商业化、市场任何一端、gateway/Nacos 微服务化部署、GraphRAG、AgentScope 接入、统一横切 Schema(P2-06)。

---

二、已验证事实基线

以下事实经代码级盘点核对至 dev/2.0.0 HEAD(0d4dbe64),并经双评审复核订正;与旧文档冲突时以本节为准。

外部服务现状(实际 3+9,非 2 个):

服务	承担	现状
New-API	AI 生成主链(RealNewApiMuseAiRuntimeClient)、导入全书解析(NewApiMuseAiImportLlmParser,唯一 parser 实现)、账户配额管理口(RealNewApiAccountFacade)、用量归因真源	生产在用
RAGFlow	知识运行时:建库/上传/解析/状态轮询/检索	生产在用;GraphRAG 生产零调用(接口三方法无生产调用点,graph_status 恒 not_ready,attribution 默认 fail-closed)
Dify	Agent 运行时(chat/workflow,blocking)	2026-06-30 新接,仅代码层;muse.ai.dify.enabled 默认 false,infra 主机尚未部署 Dify
yudao 厂商脚手架 ×9	gemini/doubao/hunyuan/siliconflow/xinghuo/baichuan/midjourney/suno/web-search 的 ChatModel/Job/控制器	application.yaml 中 9 个 enable: true 且携带明文 API key 提交在仓(疑似上游 demo 配置);会真实创建 Bean,不经统一路由治理

对改造有决定性影响的代码事实:

1. 知识运行时有干净端口:业务只依赖接口 RagFlowKnowledgeRuntimeClient,唯一 HTTP adapter 是 HttpRagFlowKnowledgeRuntimeClient;12 个声明操作中生产只用 5 个(建库、上传、触发解析、状态轮询、检索),updateDatasetConfig 等 7 个从未被生产调用。替换=新写一个 adapter,调用方零改动。
2. 知识图谱可视化与 RAGFlow 无关:图谱读 Muse 自有 Canonical 表(muse_knowledge_entity/relation,草稿确认流写入)。去 RAGFlow 不影响图谱功能;放弃 GraphRAG 零功能损失。
3. market 摘除不是零改动:MarketHandoffTokenApi/MarketAssetSourceApi/MarketAssetForkApi 三个接口(market-api 恰好只有这 3 个对外接口,MECE)被 content(MuseContentAssetUseService)、ai(MuseAgentSlotServiceImpl)、knowledge(MuseKnowledgeBindingService/KnowledgeMarketForkService)以 @Resource 强注入且无兜底——直接摘 pom 会启动崩。member 侧投影(MarketAccountProjectionFacade)已有 Unavailable 兜底,自动 fail-closed。market 事件消费者(knowledge 两个 Consumer)只依赖 market-api 事件类型,不崩但被架空:发布方随 market-server 消失,事件永不触发(市场隔离的预期后果,非缺陷)。
4. muse-server 测试树对 market-server 有编译期硬依赖(摘除的最大障碍):muse-server/src/test 下 14 个测试文件 import market,其中 13 个直接 import market-server 内部类(P1rMarket* 12 个 + P1rAccountAdminPurchaseRecordsCompletedApprovalIT、P1rAccountMarketRecordsCompletedApprovalIT 两个 Account 侧混合测试;另 P1rMarketKbForkMaterializationIT 仅 import api 但运行需 market Bean)。run-p1r-verification.sh 的 local/real-pg/external-live 三层全部走 mvn -pl muse-server -am test,test-compile 先编译整棵测试树——只摘 pom 不处理测试树,三层验证当天全部编译失败。运行期 tag 分组解决不了编译期问题。
5. 模块摘除有现成模式:pay/bpm/mp/report 就是「muse-server pom 注释掉不装配」;MonolithFacadeFallbackAutoConfiguration 是兜底样板(注意:market 三接口是抽象方法接口,兜底 Bean 须写真实 fail-closed 方法体,不能照抄该样板中全 default 接口的空匿名类写法)。
6. 多用户 worker 默认全关:全部 outbox/quota/attribution/fork/parse-poll worker 默认 disabled(机制是 @Scheduled 每 tick + 方法内读配置的 enabled 守卫,不是 @ConditionalOnProperty);常开的只有 AI dispatcher(无开关)与质量评估 worker(默认 true,本地确定性、不调外部模型)。member 的 New-API 管理口默认即 Unavailable(muse.account.new-api.enabled 默认 false)。
7. 租户红线:业务大量调 TenantContextHolder.getRequiredTenantId()(无值即抛异常),不能关 muse.tenant.enable;单人形态=保持租户开启、固定 tenant=1(现状零改动)。
8. gateway 无耦合:muse-server 单体自服务 /app-api 与 /admin-api,gateway 是独立应用、pom 无依赖,可整体不部署;openfeign 已排除。
9. 前端切分面:studio 唯一导航是 Sidebar.tsx 硬编码数组(6 项),市场相关路由 5 条;EditorPage 是无导航可达的废弃 demo 壳;PersonalCenter 是纵向 7 段混合面(资料+用量该留,购买/授权/发布/安全事件/New-API 绑定 5 段属多用户);智能体市场 handoff 落地在 features/handoff/owners/AgentHandoffLanding.tsx(随 handoff 路由一并移除)。规划候选与文风检查在 studio 无任何 UI 入口(仅 OpenAPI 生成类型,无组件/hook 引用)——1.0.0 缺口清单 P0-11「studio 有入口却点不动」表述不准,须订正(§11)。admin 的 Muse 菜单来自前端静态 muse.ts(隐藏改代码),yudao 标准菜单来自部署库 system_menu 数据(隐藏改数据);muse.test.ts 路由测试只断言路由注册存在,hideInMenu 方案下不受影响。
10. 生成主链的输出口径(v0.1 的错误前提,已订正):两个 provider 都只回脱敏摘要——New-API 60 字(OUTPUT_SNIPPET_LIMIT=60)、Dify 80 字;共享契约 RuntimeResult 无完整正文字段;投影层 MuseAiRuntimeProjectionService 注释明写「完整 provider 原文按数据主权不落库」,候选 content_snapshot.content 取自摘要;三审(输出合规/静态检查/许可快照)与候选落库链 provider 无关、对 Dify 已等价可用。真实生成候选的采纳按既有设计走 merge_after_edit(用户回传所审终稿)。不存在「New-API 完整输出口径」可供对齐;「单人版候选是否必须全文可见、全文经什么通路到前端」是一个未决的产品/架构裁决,列为 S7.0(§5.1)。
11. 覆盖门现状疑似已红(执行前必须坐实):P1rMarketRealApiGateTest 硬断言 summary.completedOperations==241、ai 域 completed==47,而台账 JSON 实为 242/48(疑似 2026-06-27 admin AI 写链路提交增补端点后未同步该测试)。S0 先真跑 local 门禁坐实并修红,再谈摘除适配。
12. Flyway 轴安全(评审确认,不要动):market 全部 7 个迁移脚本集中在 sql/muse/(filesystem 加载),market-server classpath 侧零迁移——摘除不触发「applied 但 not resolved」,表保留无害,恢复安全。

---

三、范围决策与设计修订

三个已拍板决策(2026-07-07,项目所有者确认):

决策点	结论
外部服务终态	Muse 只直连 Dify。生成主链、导入解析、Agent 运行时、知识检索全走 Dify;模型 provider 配在 Dify 内(上游可指向自有 New-API,不属 Muse 依赖);账户配额/归因随多用户搁置;yudao 厂商脚手架显式全关
隔离机制	后端摘装配 + 前端删入口。market 从 muse-server pom 摘除(先补 3 个 fail-closed 兜底 Bean + 处理测试树编译依赖);member 多用户子域按 §5.3 三类机制收口;studio/admin 删路由与菜单,代码保留仓库
缺口纳入	分两波:1a=服务收敛+隔离+部署收口;1b=按优先级补单人主线缺口(P0-11→P0-12→P0-06→P0-03→P1-11)

由此产生的正式设计文档修订清单(执行时随代码同步,完整动作见 §11;v0.2 补全了 v0.1 遗漏的三处):

• 专题-05 §1.5 与 §7「RAG 仍走 RAGFlow、Dify 知识库不作 Muse 知识运行时」、§2 非目标「Muse 授权知识检索仍由 Knowledge facade / RAGFlow 负责」 → 修订为:知识运行时切换为 Dify Datasets API。修订不违反其本意——该条真正要守的是「Dify app 内部黑盒知识不可成为 Muse 知识事实源」,这一条继续有效;Muse 知识事实源本就在自有 PG 表,RAGFlow 与 Dify Datasets 同为「可替换的检索运行时」,经显式 retrieve 端点返回 chunks 的检索结果仍由 Muse 组装上下文,溯源语义不变。
• 专题-05 §8「用量归属仍靠 New-API 归属链」→ 降级为:单人阶段 Dify usage 摘要只作本地用量观测与审计事实,不做网关对账;requires_new_api_attribution 语义冻结为历史标记。
• 架构-03:ADR-005「向量检索采用 RAGFlow」、ADR-021 后果段「RAGFlow 仍是检索基座」标注 superseded-by 新 ADR;ADR-006 与根 CLAUDE.md 决策表「图查询:依赖 RAGFlow GraphRAG」订正为 GraphRAG 放弃(生产零调用,零损失);增补 2.0.0 单人阶段 ADR(服务收敛 Dify、market 摘装配、多用户面搁置、恢复路径)。

---

四、目标架构

外部依赖终态:

flowchart LR
  subgraph before["改造前(1.0.0)"]
    M1[muse-server] --> NA[New-API<br/>生成/导入/配额]
    M1 --> RF[RAGFlow<br/>知识运行时]
    M1 -.刚接入.-> DF1[Dify<br/>Agent运行时]
    M1 -.enable:true×9.-> YD["yudao 厂商脚手架<br/>(gemini/doubao/…)"]
  end
  subgraph after["改造后(2.0.0 单人版)"]
    M2[muse-server] --> DF2[Dify]
    DF2 --> C1[chat/workflow<br/>生成主链+Agent运行时+导入解析]
    DF2 --> C2[Datasets API<br/>知识库 建库/上传/索引/检索]
    DF2 -. Dify 内配置模型 provider,<br/>上游可指向自有 New-API .-> UP[(模型上游)]
  end
  before ==> after

单体装配边界(muse-server):

flowchart TB
  subgraph in["装配保留"]
    content[content 作品/正文]
    ai[ai 编排/生成/Agent]
    knowledge[knowledge 知识库]
    meta[meta 元引擎]
    member["member 登录/资料/用量<br/>(多用户子域按三类机制收口)"]
    base[system/infra 平台底座]
  end
  subgraph out["不装配(pom 注释,同 pay/bpm/mp/report)"]
    market[market 市场]
    pay["pay/bpm/mp/report(维持现状)"]
  end
  subgraph fb["muse-server 兜底(新增,真实 fail-closed 方法体)"]
    f1[MarketHandoffTokenApi→token 无效]
    f2[MarketAssetSourceApi→not found]
    f3[MarketAssetForkApi→false]
  end
  content & ai & knowledge -->|@Resource 注入| fb
  member -->|既有 Unavailable 兜底| out
  gw[gateway/Nacos 不部署] ~~~ out

关键架构口径(防误解,执行时不得偏离):

• Prompt 主权在 Muse。切 Dify 不是把提示词工程搬进 Dify:生成主链仍由 Muse 组装 prompt 与上下文(含知识检索结果、权限包裁剪),Dify 侧建「透传型」app(prompt 极简、固定模型参数),Muse 把组装结果作为 query/inputs 发送。Dify 承担的是模型接入与(可选的)复杂工作流编排;工作流型智能体的深编辑正是放在 Dify 控制台完成(承接 P1-02,Muse 不自建工作流编辑器)。
• 知识溯源不因换运行时而丢失。Muse 经 Datasets retrieve 显式检索、自己组装上下文,来源快照/授权双门全在 Muse 侧;untraceable_provider_context 只描述 Dify app 内部黑盒知识,与本方案的检索路径无关。
• 数据主权口径未经裁决不得推翻:「完整 provider 原文不落库」是既有明写设计;若 S7.0 裁决需要全文通路,走「实时通道不持久化正文」路径,不动候选表摘要设计(§5.1)。
• 所有 fail-closed 语义保持:Dify 未配置/凭据缺失/引用不完整时拒绝服务,不回退、不伪造成功。

---

五、改造方案

5.1 AI 运行时收敛 Dify

现状 RoutingMuseAiRuntimeClient 已按 agent 版本 runtimeProvider 路由,Dify adapter 已具备 chat/workflow blocking 调用、错误映射、凭据脱敏,且三审+候选落库链 provider 无关、对 Dify 已可用(§2.10)。收敛工作是五件事:

1. S7.0 输出契约裁决(前置,防止在错误路径上开发)。v0.1「补完整输出通路对齐 New-API 口径」的锚点不存在(两 provider 均摘要级)。先以活体运行证据坐实:真实生成一次,观察前端(AIPanel/CandidatePanel)实际可见的候选内容与 SSE 事件载荷。然后二选一:
   • 分支①(预期,推荐):单人创作工具的候选必须全文可见 → 立「运行时全文实时通路」为独立工作项:executor 拿到 provider 全文后经 SSE 实时推送(正文不持久化或仅落脱敏摘要,守住数据主权不变式),候选表维持摘要 + 三审,采纳沿用 merge_after_edit(前端把用户所审终稿回传)。涉及 runtime 内部结果结构扩展(增加不落库的正文载荷字段)、事件推送链、两个 adapter 的全文透出;工期按横切项独立评估。
   • 分支②:若活体证明现状已有全文通路(存在本轮盘点未见的路径),则 Dify adapter 对齐该通路即可,规模回落为 adapter 内改动。
2. 系统 Agent 版本切 provider。在用系统 Agent 版本的 runtimeProvider 配为 dify + providerRef.dify(appId/credentialRef);Dify 侧预建两个 app:「写作透传」chat app(创作温度)与「全书解析」app/workflow(低温、JSON 输出)。旧版本缺省 new-api 的兼容逻辑保留不动(恢复路径)。
3. 导入解析新写 Dify parser。现状 NewApiMuseAiImportLlmParser 是唯一实现且被服务单点注入——在 New-API 配置移除前必须先完成 provider 选择机制 + Dify parser + New-API 缺失时 fail-closed 的反向测试(S8 完成门,否则导入功能直接不可用)。语义与 New-API 版逐条对齐(完整 JSON 消费、401/403 fail-closed、408/429/5xx 重试、脱敏摘要);截断检测:Dify 无 finish_reason=length 等价信号,以 JSON 完整性校验 + 章节数合理性检查兜底(解析失败=可重试的 bad response)。
4. 生成链完整性护栏。Dify chat 成功响应的 finishReason 恒为常量,不能作为完整性信号;生成链按 S7.0 裁决的通路补完整性校验(结构化 envelope/长度合理性),截断不得静默进入候选。
5. New-API 与 yudao 脚手架退出。muse.ai.new-api.* 不再配置(adapter 代码保留,未配置即 Unavailable fail-closed);member 管理口/配额 worker 维持默认关闭;usage 归因语义按 §3 降级。yudao 厂商脚手架 9 项 enable: true 全部改 false、明文 API key 从 yaml 移除(换 env 占位),并加启动断言「除 Dify 外无外部 AI provider Bean」;泄露过的 key 提示用户自查轮换(疑似上游 demo key,不由 agent 代决)。注意两套开关命名不同:厂商脚手架是 .enable(String),newApi/dify 是 .enabled(boolean),配置时勿混。

执行补充(2026-07-08):Spring AI Alibaba/DashScope 不是 yudao 九项脚手架的一部分,只清 .enable 与明文 key 不足以证明「除 Dify 外无外部 AI provider Bean」。S4 必须显式关闭 spring.ai.dashscope.agent.enabled,并把 spring.ai.model.chat/embedding/image/rerank/video/audio.* 设为 none;启动断言必须覆盖 DashScope 自装配,否则 live 后端可能在无 New-API/yudao key 的情况下仍触发 DashScope agent Bean。

超时口径:Dify blocking 读超时(现 90s)对长章节生成偏紧,1a 上调至与 New-API 同档(180s 总预算内),provider 级 streaming 留到后续(协议已预留,不进 1a)。

5.2 知识运行时切换 Dify Datasets

契约先行:S1 部署 Dify 后、写业务 adapter 前,先做最小 Datasets contract test(live,opt-in):钉死版本、路径、请求/响应字段、indexing-status 状态枚举、batch/document 语义。§本节 API 映射是按公开文档的推断,以 contract test 实测为准,防在适配层返工。

端口改造(不是纯 rename,如实定性为「端口重命名 + 操作裁剪 + 配置/审计/测试迁移」):接口 RagFlowKnowledgeRuntimeClient 更名为 KnowledgeRuntimeClient(名字即契约,保留旧名会让后续 agent 误判现状),裁掉生产从未调用的 7 个操作(含 GraphRAG 三方法);随之迁移的还有审计服务的调用记录口径(recordRagflowCall 语义改为记录当前 runtime)、配置装配、相关单测。HttpRagFlowKnowledgeRuntimeClient 及其装配、env 样例、live 验收 IT 删除(git 可回;与市场「搁置待恢复」不同,RAGFlow 是拍板退役不回)。

新 adapter DifyKnowledgeRuntimeClient 实现 5 个生产操作:

Muse 端口操作	Dify Datasets API(以 contract test 实测为准)	适配要点
createDataset	POST /v1/datasets	固定传 name + permission(only_me)+ indexing_technique(high_quality)
uploadDocuments	POST /v1/datasets/{id}/document/create-by-file	multipart 重组;process_rule 用 automatic;响应取 document.id 与 batch
startParseDocuments	无独立对应	Dify 上传即索引,该操作降级为 no-op(保留审计记录)
pollDocumentStatuses	GET /v1/datasets/{id}/documents/{batch}/indexing-status	轮询主键从 document_id 变 batch;状态映射 waiting/parsing/…/error→Muse 归一状态
retrieveChunks	POST /v1/datasets/{id}/retrieve	单库端点→按授权 dataset 并行循环检索,合并按 score 取 topK;响应结构在 adapter 内归一,调用方不变

Dataset 拓扑口径(2026-07-08 裁决):工作区级 Datasets API key 是管理钥匙,不代表生产只使用一个 dataset。生产运行时至少区分全局公共 dataset 与作品独立 dataset;Muse 本地保存 datasetId 映射,检索时按授权选择公共 + 当前作品 dataset 循环检索并合并排序。禁止把公共资料和作品私有资料混进单一 dataset 后仅靠 metadata 当安全边界。S1 的 dify-contract-* dataset 只作为 live contract 验收证据,不是生产唯一知识库。

数据与配置落点:

• muse_knowledge_processing_task 新增列 runtime_batch_id VARCHAR(160)(取 sql/muse 当前最大版本+1 的迁移)承载 Dify batch;muse_knowledge_ragflow_binding 等三表表名列名不动,ragflow_dataset_id 列直接存 Dify dataset id,列注释订正——显式命名债,留待 P2-06 统一 Schema 收口。
• 新配置前缀 muse.knowledge.dify.*(base-url/dataset-api-key/timeout/retry-budget),缺任一即装 Unavailable 桩 fail-closed(沿用现模式)。Dify 两类凭据不同:Datasets API 用工作区级知识库 API key,chat/workflow 用 app 级 key,不可混用(同构「New-API 令牌≠RAGFlow key」既有坑)。
• MuseKnowledgeParseStatusPollWorker 默认关,S6 起须在单人配置显式开启(否则上传后状态永不推进)。
• 授权过滤不受影响:检索前的用途门/来源状态门/授权快照门全是 Muse 应用层逻辑,metadata_condition 现状本就传 null,无迁移面。
• 存量数据:RAGFlow 内网实例里只有验收产物,无生产存量,不做数据迁移;素材经 Muse 重新上传索引(假设,S1 部署时复核)。

市场 fork 簇随隔离整体停用:KnowledgeMarketForkService、fork 兜底 worker、安装侧物化、kb_id 去污染属市场链路,随 §5.3 摘除后不可达,不参与运行时迁移。

5.3 多用户/平台功能隔离(后端)

按依赖方向分五步,每步独立可验证:

1. 补兜底再摘除:在 muse-server 侧为 MarketHandoffTokenApi(verify→invalid)、MarketAssetSourceApi(→not found)、MarketAssetForkApi(→false)提供 @ConditionalOnMissingBean 的兜底 Bean(三接口均为抽象方法接口,须写真实 fail-closed 方法体);然后 muse-server pom 注释 muse-module-market-server 依赖(market-api 纯接口依赖保留)。market 装回时真实现自动优先,兜底让位。
2. 测试树编译处置(与 1 同步,见 §5.5):14 个 market 依赖测试文件不迁移、不删除,用 maven profile 化的 testExcludes 从默认编译中排除(恢复=激活 profile),其中 2 个 Account 侧混合测试一并排除并在台账登记。
3. 市场语义端点收口(不随 market 模块消失的部分):knowledge 模块自带的市场语义端点分两类处理。AppMuseKnowledgePublishController 的 publish-prechecks/publish-snapshots/publish-readiness 三个 POST 保留为 Knowledge 本域预检/快照能力,允许写本域 readiness/snapshot/command 记录,但不得产生 market 资产、安装、授权事实;前端发布入口在 S5 删除。AppMuseInstalledKnowledgeBaseController 与 market_kb binding/handoff/fork 路径依赖 market 兜底,必须 fail-closed/空结果。S3 验收断言 market API fallback、installed 空结果、market route 404;不要求 publish 三端点零本域副作用,也不新增 dormant 机制。
4. member 子域收口(v0.2 订正口径:三类机制,不是「全走开关」):保留 登录/会话(member_user + system oauth2)、profile、命令幂等、审计、usage 只读观测。多用户子域的实际关闭机制分三类——① 真配置开关仅一个:muse.account.new-api.enabled=false(默认已关);② worker enabled 属性:quota/attribution/事件发布 worker(默认已关,配置文档固化);③ @ConditionalOnMissingBean 兜底:市场记录投影、账户导出的 FileService 依赖(market/真实 provider 缺席自动 Unavailable,无开关可设也无需设);entitlement 为本地常开纯读逻辑,无外部副作用,不动。yudao 会员商城子域(积分/等级/签到/标签)不动,仅菜单隐藏。
5. 租户/登录/worker 核对:租户保持 enable、固定 tenant=1(禁止关 muse.tenant.enable,§2.7 红线);studio 仅保留单账号登录,不暴露注册/多用户入口;确认多用户向 worker 全部处于关闭,AI dispatcher 与质量评估 worker 保留。

5.4 前端裁剪

muse-studio(全部为删除/裁剪,文件保留在 git 历史):

• 路由:删 4 条 market 路由 + handoff 落地页路由(含 AgentHandoffLanding 等 owner 落地组件)+ 废弃 EditorPage 路由及文件。
• 导航 Sidebar.tsx:删「市场」「治理」两项,保留 作品/知识库/智能体/个人。
• PersonalCenter:保留 资料 header + 用量权益(UsageStats),删 购买/授权/发布/安全事件/New-API 绑定 5 段。
• 知识页:删「从市场安装的」tab 与「发布到市场」入口(含预检 Modal);保留 我创建的/全局公共授权。
• 智能体页:自建 Agent 全生命周期与槽位绑定保留(市场 handoff 入口随 handoff 路由移除,页面本身无需改动,执行时核实)。
• 规划候选/文风检查:studio 现状无 UI 入口(§2.9),1a 无前端动作;1b 实现后端时一并新建 UI。1.0.0 缺口清单 P0-11 的「studio 有死入口」表述在 S10 订正。
• market 相关 e2e spec 与 MSW handlers:标记隔离(skip/tag),不删。

执行交接(2026-07-08):本轮 studio 路由/侧栏/account/knowledge 裁剪已经落地,route-only Playwright 可证明市场与 handoff 入口不可达;但这不是 S5 完成证据。S5 的完成门仍是 MSW-off 创作主线 e2e 全绿,当前受标准后端启动的 Flyway V1 function owner mismatch 阻塞,需在下一轮修复 live 后端启动口径后补跑。

muse-admin:

• muse.ts 静态菜单:「市场治理」「用户与权限」加 hideInMenu(不删路由,故 muse.test.ts 路由注册断言不受影响)。
• 「New-API 与用量」页(views/muse/newapi):后端管理口已关,页面现含网关绑定/额度配置写命令表单,1a 须移除/禁用写入口,降级为本地用量只读观测;补断言(无写按钮、无写 API 调用)。
• yudao 标准菜单(用户/角色/租户/部门/会员/支付/公众号/BPM/yudao-AI 娱乐面):在部署库 system_menu 数据停用,产出幂等 SQL 脚本随部署文档管理。注意菜单双源:前端 muse.ts 管 Muse 组,「基础设施」「系统管理」等属 system_menu 数据侧;另核查 admin 前端 yudao demo 静态路由模块(leave.ts/pay.ts 等)在菜单合并机制下是否漏出,漏出则一并 hideInMenu。
• 保留菜单:元结构定义、功能编排、AI 配置、全局知识库、任务治理、日志审计、基础设施、菜单管理。

5.5 验证门禁体系适配(先于摘除执行)

本项目的脊柱规则是机械门禁反假绿,摘除 market 必须先让门禁体系「诚实变化」而非变红或假绿。v0.2 按评审补全清单:

• S0 先坐实现状:真跑 run-p1r-verification.sh local。已静态坐实 P1rMarketRealApiGateTest 硬断言(241/47)与台账 JSON(242/48)矛盾,先修现红门再动别的(对齐现实计数,并查随附域计数)。
• 测试树编译处置:14 个 market 依赖测试文件(§2.4 清单)通过 maven-compiler-plugin testExcludes + surefire excludes 的 market-assembled profile(默认排除、激活即回)从默认构建剥离。不迁移(它们依赖 muse-server 全栈上下文,迁到 market-server 跑不起来)、不降 test-scope(会造成 prod/test 装配分叉:测试上下文装配 market 而生产不装)。代价:排除期间这些 IT 零维护漂移,恢复时可能需修,登记在案。
• 接口覆盖门:改造涉及两个测试与一份台账——P1rMarketRealApiGateTest 整体随 profile 剥离;P1rApiCoverageReportTest 为 market 域引入显式 dormant 口径(dormant 域豁免 completed 计数与 testFiles 强制,总量 242 不变、completed 分母降为 210),断言从硬编码常量改为按域派生,恢复时激活 profile 自动回门。禁止直接删台账条目。
• admin 侧:market/account 治理相关 Playwright spec 与 globalSetup 的 market fixture 标记隔离(RC 本就未把 admin Playwright 纳入门禁,不新增强制门);muse.test.ts 不受影响(hideInMenu 方案)。
• Flyway:market 表迁移脚本保留照迁(§2.12,评审确认安全)。
• ArchUnit:market 不在 muse-server classpath 后,BC 边界规则对其暂不生效属预期,记录在案;AgentsInfraIntegrityTest 是文件级检查,不受影响。
• OpenAPI 契约:docs/api-contracts 的 market 契约原地保留——双重理由:ContractFirstGateTest(local 层)硬要求 market 契约目录存在;删端点会触发 openapi-diff 拦截。如需标注 dormant,只允许加纯增量元数据(x- 扩展/description),不得动端点与参数。

5.6 部署收口

• Dify 部署是 1a 的第一步(现在还没有实例):按官方 docker-compose 钉版本部署于内网(mini-infra 或 mini-desktop,执行时定),建两个 app(写作透传/全书解析)与知识库 API key;凭据与地址按内网惯例记入项目凭据文档与 p1r-external-acceptance.env(新增 MUSE_AI_DIFY_*/MUSE_KNOWLEDGE_DIFY_* 样例),RAGFlow 条目移除。
• Muse 侧单机编排:产出单人版 docker-compose(muse-server + PostgreSQL + Redis),Dify 用官方 compose 独立部署、以 env 指向(升级互不牵连);新库 provision 复用「yudao 基座 SQL + Flyway 迁移」既有配方。
• 无 Nacos 干净启动验证:确认单体在无 Nacos 环境启动无阻塞、日志无持续报错,必要时显式关闭服务发现注册。
• 验收:单机 compose 从零起全栈,黄金旅程 smoke 全绿(见 §9)。

---

六、单人创作功能清单(边界 / 要求 / 目标)

阶段一后的产品形态,按六个功能块定义。「1a 后」指精简收敛完成时的状态,「1b」指打磨波次的目标。

6.1 作品与写作台(content)

• 边界:含 作品列表(建/删/进入)、WorkspacePage 写作台(章节大纲 + Tiptap 编辑器 + 块结构条 + 右侧 AI/规划/来源/历史 Tab + 导入/导出/知识/记录入口)、IndexedDB 自动保存安全网、版本历史与任意两版 diff、txt/md/docx/epub 导入向导、范围/格式导出下载。不含:协作、分享、发布。
• 要求:正文 Canonical 唯一写入方不变;Block 写入带 expectedRevision 乐观锁;Accept Suggestion 是候选进正文唯一入口;导出走真实 FileService。
• 目标:1a 全量保留现状能力(已真验证),删除废弃 EditorPage;1b 补版本恢复写入(P0-03:从历史版本恢复走 Content 写边界,产新 revision + 来源归因 + 审计 + 旧草稿失效)。

6.2 AI 辅助创作(ai)

• 边界:含 候选生成→SSE→Diff→采纳/拒绝全链、智能体工作台(自建 Agent 增删改/版本/归档/沙盒试用)、作品槽位绑定/替换/解绑、质量评估(本地确定性执行器)。工作流型智能体的「深编辑」定位为 Dify 控制台能力,Muse 只保存引用并受控调用。不含:LLM judge、AgentScope、市场 Agent 安装。
• 要求:AI 只产 Shadow 候选,绝不直写 Canonical;「完整 provider 原文不落库」的数据主权口径未经 S7.0 裁决不得推翻;Dify 未配置 fail-closed;凭据不落库不进日志;usage 摘要落本地用量记录。
• 目标:1a 生成主链与试运行全走 Dify(按 S7.0 裁决的输出通路交付,候选对用户全文可见、可审可采纳),导入解析走 Dify parser;1b 补规划候选生成(P0-11,规划台新建 UI + 真实生成)与文风检查(P0-12,可追踪结果、缺 AI 诚实降级)。

6.3 知识库(knowledge)

• 边界:含 我创建的知识库 + 全局公共授权库、资料上传→索引→状态轮询、知识草稿(确认/忽略/重验)、实体关系 CRUD 与图谱可视化(Muse 自有 Canonical 数据)、作品级来源绑定与读回、授权过滤检索供 AI 上下文。不含:市场安装库、前端发布入口(后端 publish 预检/快照保留为 Knowledge 本域能力,market 装配相关路径 fail-closed/空结果,见 §5.3.3)、GraphRAG、recheck 外部校验 worker。
• 要求:进 Local KB 唯一入口=用户确认草稿;检索前授权双门全在 Muse 侧;运行时故障检索降级为空、不阻断生成、不伪造结果;parse-poll worker 单人配置显式开启。
• 目标:1a 运行时切 Dify Datasets(上传/轮询/检索三链真验证);1b 补处理状态与失败恢复 UI(P0-06:失败原因、重试/删除/重新上传入口,基于 Dify indexing-status 的失败态)。

6.4 元引擎(meta)

• 边界:含 admin 侧 MetaSchema 定义/版本/发布回滚、字段预校验、用户作品级覆盖读端。不含:可视化 schema 编辑器(P2-05)、影响预览 all-real 用量建模(P0-09)。
• 要求:发布链保持现有校验;影响预览维持现状口径(planning 真实计数,其余维度诚实标注),单人自担风险,不伪造 0 影响为「已验证」。
• 目标:阶段一维持现状,不投入;P0-09 划归多用户线。

6.5 账户(member 最小面)

• 边界:含 单账号登录/会话、个人资料、用量观测(Token 用量,数据源为本地用量记录)。不含:注册、权益/配额管理、购买/授权/发布记录、安全深面(2FA/改密/会话吊销)、偏好通知、New-API 绑定。
• 要求:认证仍是服务端可信边界(不做免登);多用户子域按 §5.3.4 三类机制收口后对应 API fail-closed。
• 目标:1a 完成裁剪;P0-07/P0-08 划归多用户线。

6.6 治理端(admin,单人自治理)

• 边界:含 元结构定义、功能编排、AI 配置(系统 Agent/Prompt 模板/Tool Grant/质量门控 + Dify 引用录入与控制台跳转)、全局知识库、任务治理、日志审计、基础设施运维、菜单管理;「New-API 与用量」降级为本地用量只读观测。不含:市场治理、用户与权限治理、会员/支付/公众号/BPM、网关绑定与额度写命令。
• 要求:AI 配置页的 Dify 引用录入沿用专题-05 的控制台跳转与 credentialRef 约定;质量策略回滚死入口(P1-17)在 1a 保持诚实提示,不纳入阶段一实现。
• 目标:1a 完成菜单裁剪、newapi 页禁写与 Dify 配置面可用。

---

七、阶段划分与步骤计划

flowchart LR
  subgraph 1a["阶段 1a:地基(服务收敛+隔离+部署)"]
    S0[S0 坐实并修复<br/>现红门禁基线] --> S2[S2 门禁与测试树适配<br/>profile 剥离/覆盖门 dormant]
    S1[S1 部署 Dify<br/>app/凭据 + contract test] --> S6[S6 知识运行时<br/>Dify adapter]
    S1 --> S70[S7.0 输出契约裁决<br/>活体实测定分支]
    S2 --> S3[S3 market 摘装配<br/>兜底 Bean+pom+语义端点核验]
    S3 --> S4[S4 member/租户/worker<br/>yudao 脚手架关停/admin 收口]
    S4 --> S5[S5 studio 裁剪]
    S70 --> S7[S7 生成主链切 Dify]
    S7 --> S8[S8 导入解析 Dify parser<br/>含 provider 选择机制]
    S5 & S6 & S8 --> S9[S9 部署收口<br/>compose+黄金旅程 smoke]
    S9 --> S10[S10 文档沉淀<br/>专题-05/ADR/缺口清单订正/总账]
  end
  1a --> 1b["阶段 1b:打磨<br/>P0-11 规划候选 → P0-12 文风检查<br/>→ P0-06 知识失败恢复 → P0-03 版本恢复<br/>→ P1-11 SSE 接组件"]

说明:S0 是一切的前置(基线必须绿);S2 先于 S3(门禁与编译处置先行,保证摘除当天三层验证可跑且不假绿);S1→S6/S7 的 Dify 线与 S2→S5 的隔离线分属不同模块,可并行推进;S7.0 裁决若走分支①(全文通路立项),S7 工期按横切项重估,且其结果决定 S9 黄金旅程「候选可采纳」判据的具体口径。每个 S 都要独立可验证并回写总账。1b 各项按序独立立项,验收判据沿用缺口清单的「最小验收标准」并把外部模型调用替换为 Dify。任务级拆解见执行计划。

---

八、风险与兜底

风险	影响	兜底
门禁基线现红(242/241 矛盾)未先处理	后续所有「全绿」验收失去基线意义	S0 首事项真跑坐实并修复,之后才动摘除
muse-server 测试树编译依赖处理不当	摘除当天三层验证全部编译失败	S2 profile 化 testExcludes 先行;每步全量 local/real-PG 回归后再进下一步
S7.0 裁决走分支①时全文通路是横切开发	S7 工期被低估,反噬 S9 判据	裁决前置、独立立项估期;未达标前生成主链不切换,New-API 配置保留到 S7 验收通过
Dify Datasets 检索质量与 RAGFlow 不同(分块/embedding 差异)	AI 上下文相关性下降	S6 用真实创作素材做检索对比 smoke;不满意调 Dify 分块(父子分块/高质量索引);检索失败降级为空的既有语义保底
跨 dataset score 可比性(单库端点循环合并隐含同源假设)	多库 topK 合并排序失真	单人库数个位数;统一 embedding 模型;观测日志留存 score 分布,失真再做归一化
Dify API 版本漂移 / 映射假设不实	适配层返工	S1 contract test 钉版本先行;compose 钉版本;升级前先跑 live 验收
Dify blocking 长文生成超时	长章节生成失败	1a 上调读超时;生成失败可重试(既有 RetryPolicy);streaming 已预留,列为后续项
导入解析截断/JSON 不严格	全书解析静默截断	JSON 完整性校验 + 章节数合理性检查;解析失败可重试且 job 诚实置 failed;S8 完成门含 New-API 缺失反向测试
yudao 脚手架关停遗漏	「只直连 Dify」名存实亡,外呼出口失控	9 项逐一改 false + 启动断言兜底;.enable/.enabled 双命名坑写入配置文档
明文 key 已入 git 历史	凭据泄露面	1a 从 yaml 移除并提示用户自查轮换(多为上游 demo key);不由 agent 代决轮换
market 语义端点(knowledge 侧)漏收口	验收只看 /market 路径会假绿	§5.3.3 显式行为断言纳入 S3 验收
排除期 market IT 漂移	恢复 market 时测试红	登记在案,恢复 checklist 含「激活 profile 修红」

---

九、验证计划(1a 验收判据)

完成=以下全部机械证据齐备,任何一项缺失不得声称 1a 完成:

0. 基线:S0 后 run-p1r-verification.sh local 全绿(修复 242/241 矛盾后的真实基线)。
1. local 门禁:摘除与收敛完成后 local 全绿(覆盖门 market 域 dormant、断言域派生化后分母自洽,无 catch_all/missing)。
2. real-PG 层:非 live IT 在专属 _test 库全绿(含新增迁移、market 摘除形态下的全量回归)。
3. Dify live 层(opt-in,对齐既有 live IT 模式):Datasets contract test;知识链(建库→上传→索引状态→检索);生成主链(按 S7.0 裁决口径:候选产出→三审→用户可见全文→可采纳);导入解析(全书 JSON)。RAGFlow live IT 已退役。
4. fail-closed 反向证据:Dify 未配置/凭据错误时,生成、检索、导入均拒绝服务且错误码正确;New-API parser 在无配置时 fail-closed;启动断言证明无 yudao 厂商 provider Bean。
5. 前端:studio tsc/vitest/build 绿;MSW-off Playwright 创作主线 spec(候选采纳、导入向导、导出下载、知识草稿/图谱/绑定、agent 生命周期)全绿;market spec 已隔离不再计入。admin:muse.test.ts 绿,「市场治理/用户与权限」菜单不可见断言,newapi 页无写入口断言。
6. 单机活体:单人版 compose 从零起全栈(基座 SQL + Flyway provision),黄金旅程 smoke:登录→建作品→写正文→AI 候选(全文可见)→采纳→上传资料→检索命中→导出下载,全程真后端真库真 Dify。
7. 隔离核验:/app-api/market/**、/admin-api/market/** 物理 404;knowledge 侧 market_kb binding/handoff/fork/installed 路径 fail-closed/空结果;publish-prechecks/publish-snapshots/publish-readiness 只保留 Knowledge 本域预检/快照记录,不得产生 market 资产、安装、授权事实;studio 无市场入口;多用户 worker 无一运行。

---

十、恢复路径(多用户回归时,checklist)

market 恢复不是「取消 pom 注释」一行,按此清单执行:

1. muse-server pom 取消 market-server 注释(真实现 Bean 自动优先于兜底,接口级无冲突);
2. 激活 market-assembled maven profile(14 个测试文件回编译,修排除期漂移的红);
3. 覆盖门 market 域退出 dormant(域派生断言自动回门,核对 completed 分母回 242 口径);
4. admin/studio 前端:revert 裁剪提交或按届时 UI 重做入口;admin Playwright market spec 解除隔离;
5. 部署库 system_menu 恢复对应菜单数据(幂等 SQL 反向脚本);
6. OpenAPI market 契约一直原地未动,无动作;Flyway market 表一直在,无动作。

member 子域:打开对应 enabled 开关即回(quota/归因/绑定 worker 与管理口);账户配额如需网关对账,再评估恢复 New-API 直连或改走 Dify 侧核算。权限收口:多用户化时在服务端补 AOP/权限切面统一鉴权(届时新 ADR),本阶段不预建。New-API/RAGFlow:adapter 代码分别为「保留未配置」/「已删除(git 可回)」;恢复 RAGFlow 需按新集成重走契约与验收,不承诺兼容。

---

十一、文档与沉淀影响清单(S10 交付)

文档	动作
专题-05-AI统一交互协议与外部AgentAdapter设计.md	v0.2:修订 §1.5、§2 非目标、§7 知识运行时、§8 用量归属;登记单人阶段口径与 S7.0 裁决结果
架构-03-关键决策与原则(ADR).md	ADR-005、ADR-021 标注 superseded-by;ADR-006(GraphRAG)订正;增补 2.0.0 单人阶段 ADR
根 CLAUDE.md 决策表	「图查询依赖 RAGFlow GraphRAG」订正
docs/mvp/1.0.0-产品功能缺口待办清单.md	P0-11 表述订正(studio 无 UI 入口,非「有入口点不动」)
.agents/knowledge/external-deps-and-gotchas.md	RAGFlow 条目退役;Dify 部署事实、两类凭据坑、.enable/.enabled 命名坑写入
.agents/knowledge/tech-decisions.md、project-and-architecture.md	同步收敛决策与 knowledge BC 运行时表述
docs/mvp/	新增 2.0.0-单人版交付计划.md(承接进度口径,1a/1b 里程碑);总账逐任务回写
docs/项目功能与进度总览.md	2.0.0 口径改版(功能清单以本文 §6 为准)
docs/api-contracts/market/*	原地保留(ContractFirstGateTest 依赖其存在);dormant 标注仅限 x- 扩展元数据
本文	评审通过后按执行计划推进;完成后归档 docs/agent-specs/archive/

---

十二、评审待确认项

1. Dify 部署宿主选 mini-infra(与 PG/Redis 同机)还是 mini-desktop(与构建/e2e 同机)?——影响 S1,倾向 mini-infra。
2. RAGFlow 现有实例在 Muse 退役后是否整体下线(其上仅验收产物)?——不影响本方案,只影响 infra 清理。
3. §5.2 端口改名(RagFlowKnowledgeRuntimeClient→KnowledgeRuntimeClient)与「表列名不动」的取舍是否接受。
4. S7.0 若坐实现状无全文通路,是否同意按分支①立项「运行时全文实时通路」(推荐:单人创作工具候选必须全文可见;正文不持久化,守住数据主权不变式)。
5. yudao 脚手架 yaml 中的明文 key(疑似上游 demo key)是否需要你自查轮换。

---

十三、v0.1→v0.2 修订记录(2026-07-07,Codex + Opus 双对抗评审)

级别	评审发现	v0.2 处置
P0	muse-server 测试树 14 文件编译期硬依赖 market-server,三层验证全走 -pl muse-server -am test,「运行期分组」方案不成立(Opus,已核实)	§2.4 新增事实;§5.5 改为 profile 化 testExcludes 编译期方案;§10 恢复 checklist 化
P0	「补完整输出通路对齐 New-API 口径」前提错误:两 provider 均摘要级,完整原文不落库是明写数据主权设计,三审链 provider 无关已通(Opus+Codex,已核实)	§2.10 订正事实;§5.1 改为 S7.0 裁决 + 两分支;§4 增数据主权口径红线;§12.4 增待确认项
P0	yudao 厂商脚手架 9 项 enable: true 且明文 key 在仓,违背「只直连 Dify」(Codex,已核实且比评审所述更重)	§2 表格新增第 4 行;§5.1.5 显式关停+启动断言+key 处置;§8 风险
P1	覆盖门硬编码 241/47 与台账 242/48 矛盾,local 门禁疑现红(Opus,静态坐实)	§2.11 新增;S0 立为首步
P1	门禁清单遗漏:P1rMarketRealApiGateTest、coverage testFiles/summary 连带、ContractFirstGateTest 要求 market 契约存在(Opus/Codex,已核实)	§5.5 重写补全
P1	市场语义端点不随 market 模块消失(knowledge publish 三端点、installed KB),按路径验收会假绿(Codex,已核实;2026-07-08 已裁决 publish 三端点保留 Knowledge 本域能力,market 装配路径 fail-closed)	§5.3.3 新增;§9.7 断言扩
P1	admin newapi 页含写命令,与「只读保留」冲突(Codex,已核实)	§5.4/§6.6 明确禁写+断言
P1	导入解析是单实现单点注入,New-API 退出前须先具备 provider 选择与反向测试(Codex,已核实)	§5.1.3 完成门
P1	Dify Datasets 映射是假设,须 contract test 前置钉版本(Codex)	§5.2 契约先行
P1	member「全走既有开关」口径失真(仅 1 个真开关+worker 属性+兜底;entitlement 常开)(Opus,采信)	§5.3.4 重写
P1	supersede 清单漏 专题-05 §2 非目标、ADR-005、ADR-021(Opus,已核实)	§3/§11 补全
P2	studio 规划/文风无 UI 入口,缺口清单 P0-11 表述不准(Opus,已核实);兜底 Bean 须真实方法体;事件消费者「架空」措辞;parse-poll worker 需显式开;跨库 score 风险;.enable/.enabled 命名坑;端口改名定性;恢复路径 checklist;admin 菜单双源与 demo 路由核查;AgentHandoffLanding 位置	§2.9/§5.2/§5.3/§5.4/§8/§10 逐条吸收
降级	「admin muse.test.ts 会红」(Codex)——实测其仅断言路由注册,hideInMenu 方案下不红	§2.9/§5.5 记录为不受影响