From 2e451911602444441c1a4c04819f320652fc87b9 Mon Sep 17 00:00:00 2001 From: zizi Date: Tue, 7 Jul 2026 14:28:04 +0800 Subject: [PATCH] docs(agent-specs): add 2.0.0 solo execution plan --- .../2026-07-07-2.0.0单人版改造-execution.md | 273 +++++++++++++ .../2026-07-07-2.0.0单人版改造-review.html | 255 ++++++++++++ .../2026-07-07-2.0.0单人版改造-review.md | 378 ++++++++++++++++++ 3 files changed, 906 insertions(+) create mode 100644 docs/agent-specs/2026-07-07-2.0.0单人版改造-execution.md create mode 100644 docs/agent-specs/2026-07-07-2.0.0单人版改造-review.html create mode 100644 docs/agent-specs/2026-07-07-2.0.0单人版改造-review.md diff --git a/docs/agent-specs/2026-07-07-2.0.0单人版改造-execution.md b/docs/agent-specs/2026-07-07-2.0.0单人版改造-execution.md new file mode 100644 index 00000000..1a5c0910 --- /dev/null +++ b/docs/agent-specs/2026-07-07-2.0.0单人版改造-execution.md @@ -0,0 +1,273 @@ +# 2.0.0 单人版改造执行计划(执行版) + +- 版本:v1.0 +- 日期:2026-07-07 +- 承接:[评审版方案 v0.2](2026-07-07-2.0.0单人版改造-review.md)(已经 Codex + Opus 双对抗评审,P0×3/P1×8 全部吸收,见其 §13)。**设计意图、事实基线、风险与验收总纲以 review v0.2 为准,本文只做任务级拆解**;两文冲突时以 review v0.2 为准并回改本文。 +- 读者:执行 agent(每个 S 步可独立派工)与项目所有者(里程碑验收)。 + +--- + +## 0. 执行纪律(硬约束,每个 S 步适用) + +1. **完成=机械验证**:每步的「验收」命令必须真跑并留输出证据;默认 skipped / mock-only / 台账门禁不得作为完成证据。改动后按依赖链全量回归(local 必跑;涉库涉外部再跑 real-PG / live)。 +2. **契约先行**:DDL 只走 `sql/muse/V__*.sql`(编号取当前最大+1);OpenAPI 不删端点、不动 market 契约参数(dormant 只允许 `x-` 扩展);接口变更先改 `docs/api-contracts/*` 再实现。 +3. **最小改动**:只动本步清单内文件;禁止顺手重构;代码全中文注释,外部交互与失败路径必须有可追溯日志。 +4. **原子提交**:S3 的「pom 注释 + 兜底 Bean + 测试排除生效 + 台账 dormant」必须同一提交生效,避免中间态红门(S2 只交付机制,S3 拨开关)。 +5. **回写**:每步完成回写 `docs/mvp/进度总账.md` + 涉及模块 `.agent`;不新增过程状态文档。 +6. **环境与坑**:内网凭据按 `~/.config/muse-repo/infra.env` 与 `muse-cloud/scripts/dev/p1r-external-acceptance.env`;JVM/Maven 必须按 `.agents/knowledge/external-deps-and-gotchas.md` §四清理 SOCKS/HTTP 代理与陈旧增量编译(`rm -rf /target/maven-status` 或 clean),否则出现假红/假绿。 +7. **派工分档**:各 S 步执行子代理默认 `opus`;纯机械批量(改配置值、菜单 SQL、批量 hideInMenu)可 `haiku`;S7.0 裁决结论与全文通路设计评审升 `fable`(或主会话终裁)。 + +--- + +## 1. 步骤总图 + +```mermaid +flowchart LR + S0[S0 门禁基线修复] --> S2[S2 门禁/测试树机制] + S2 --> S3[S3 market 摘装配] + S3 --> S4[S4 配置与治理收口] + S4 --> S5[S5 studio 裁剪] + S1[S1 Dify 部署+契约钉死] --> S6[S6 知识运行时切换] + S1 --> S70[S7.0 输出契约裁决] + S70 --> S7[S7 生成主链切 Dify] + S7 --> S8[S8 导入解析切 Dify] + S5 & S6 & S8 --> S9[S9 部署收口+黄金旅程] + S9 --> S10[S10 文档沉淀归档] +``` + +两条线并行:**隔离线** S0→S2→S3→S4→S5(全在 market/member/前端/门禁面);**Dify 线** S1→(S6 ∥ S7.0→S7→S8)(全在 ai/knowledge 面)。S9 汇合。S0 与 S1 可同日启动。 + +--- + +## S0 坐实并修复门禁基线 + +| | | +|---|---| +| 前置 | 无(一切工作的地基) | +| 预估 | 0.5 天 | + +**动作** +1. 真跑 `bash muse-cloud/scripts/run-p1r-verification.sh local`,记录全部红项清单。 +2. 修已静态坐实的红:`muse-server/src/test/java/cn/iocoder/muse/server/framework/api/P1rMarketRealApiGateTest.java` 断言 `summary.completedOperations==241`、`ai==47`,而台账 `docs/superpowers/reports/p1r-api-coverage.json` 为 242/48。**修法=对齐现实**:先核对新增端点(2026-06-27 admin AI 写链路)在台账中确有 `testFiles` 真实证据锚点,再把断言改为 242/48;若发现台账证据缺失,按反假绿规则先补证据再改数,不许直接拨数字。 +3. 顺带核查同文件其他域计数断言(knowledge/content/meta/account)与台账一致性。 +4. 复跑 local 至全绿。 + +**验收**:`run-p1r-verification.sh local` BUILD SUCCESS,输出留档进度总账。 +**回滚**:纯测试断言修正,revert 即可。 + +--- + +## S1 部署 Dify + 契约钉死 + +| | | +|---|---| +| 前置 | 无;宿主待用户确认(review §12.1,默认 mini-infra) | +| 预估 | 1 天 | + +**动作** +1. 按 Dify 官方 docker-compose 在内网宿主部署,**钉死版本号**(镜像 tag 记入凭据文档与 compose;禁 latest)。 +2. Dify 控制台初始化:创建工作区;建两个 app——「muse-写作透传」chat app(prompt 极简透传、创作温度、绑定模型 provider,上游可配自有 New-API 网关)、「muse-全书解析」app/workflow(低温、要求严格 JSON 输出);生成 app 级 API key ×2 与工作区级**知识库 API key**(两类 key 不同,不可混用)。 +3. 凭据落位:`muse-cloud/scripts/dev/p1r-external-acceptance.env` 新增 `MUSE_AI_DIFY_*`(base-url/credentials/console-base-urls)与 `MUSE_KNOWLEDGE_DIFY_*`(base-url/dataset-api-key)样例;地址与 key 按内网惯例记入项目凭据文档;**移除该文件中 RAGFlow 条目**(与 S6 同步生效亦可)。 +4. **Datasets contract test(写业务 adapter 前钉契约)**:新增 opt-in live IT(对齐既有 `P1r*LiveAcceptanceIT` 模式,`MUSE_P1R_EXTERNAL_ACCEPTANCE=true` 才真跑)`P1rDifyDatasetsContractLiveIT`,实测并断言:`POST /v1/datasets` 建库字段、`document/create-by-file` 响应含 document.id 与 batch、`documents/{batch}/indexing-status` 状态枚举、`POST /v1/datasets/{id}/retrieve` 响应结构(records[].segment.content/score)。留 `dify-contract-<日期>` dataset 不删(对齐 RAGFlow smoke 惯例)。 +5. chat-messages smoke:用既有 `RealDifyMuseAiRuntimeClient` 配置真打「写作透传」app 一次(可借既有 Dify 单测/新增最小 live 用例),证明 app 级 key 与网络通。 + +**验收**:contract live IT 全绿输出留档;Dify 控制台两 app 可用;检索 smoke 返回结构与 §S6 映射表一致(不一致→先改 review v0.2 映射表再动工)。 +**回滚**:纯新增测试与外部部署,无代码风险。 + +--- + +## S2 门禁与测试树适配(机制就绪,不拨开关) + +| | | +|---|---| +| 前置 | S0 | +| 预估 | 1~1.5 天 | + +**动作** +1. **测试树 profile 机制**:`muse-cloud/muse-server/pom.xml` 增加 maven profile ——默认 profile 通过 maven-compiler-plugin `testExcludes` + surefire excludes 排除下列 **14 个文件**(全部位于 `muse-server/src/test/java/cn/iocoder/muse/server/framework/api/`),`market-assembled` profile 激活时不排除: + `P1rMarketAdminAppealCompletedApprovalIT`、`P1rMarketAdminAssetReadsCompletedApprovalIT`、`P1rMarketAdminPublishReviewCompletedApprovalIT`、`P1rMarketDiscoveryFavoriteCompletedApprovalIT`、`P1rMarketEventsPublishEndToEndTest`、`P1rMarketGovernanceWriteCompletedApprovalIT`、`P1rMarketHandoffClusterCompletedApprovalIT`、`P1rMarketKbForkMaterializationIT`、`P1rMarketLicenseInstallCompletedApprovalIT`、`P1rMarketProducerAppealCompletedApprovalIT`、`P1rMarketPublishProducerCompletedApprovalIT`、`P1rMarketplaceDiscoveryReadsCompletedApprovalIT`、`P1rAccountAdminPurchaseRecordsCompletedApprovalIT`、`P1rAccountMarketRecordsCompletedApprovalIT`(后两个是 Account 侧混合测试,一并排除并在台账登记)。`P1rMarketRealApiGateTest` 一并纳入排除清单(它虽不 import market-server,但其断言语义=market 装配态)。**本步排除默认不生效**(profile 缺省仍编译全量),S3 原子拨开关。 +2. **覆盖门 dormant 口径**:改造 `P1rApiCoverageReportTest`——断言从硬编码常量改为**按域派生**;引入 `dormant` 完成状态口径(dormant 域豁免 completed 计数与 testFiles 强制,总量 242 不变);台账 JSON 的 market 32 条置 dormant 的数据变更**本步只准备 patch 不提交生效**。 +3. **admin 侧隔离机制**:market/account 治理相关 Playwright spec(`muse-admin-governance.spec.ts` 中 market/account 用例)与 `global-setup.ts` 的 market fixture 加环境开关(如 `MUSE_ADMIN_E2E_MARKET=false` 跳过);`muse.test.ts` 确认不需改(hideInMenu 方案不删路由)。 +4. **dry-run 验证机制有效**:本地临时注释 market-server pom 依赖(不提交)→ 应用步骤 1/2 的开关 → `run-p1r-verification.sh local` 全绿 → 还原。此绿仅证明机制,正式生效在 S3。 + +**验收**:dry-run local 全绿记录;还原后 local 仍全绿;`-Pmarket-assembled` 下 14 文件回编译成功。 +**回滚**:机制未启用,revert 即可。 + +--- + +## S3 market 摘装配(原子生效) + +| | | +|---|---| +| 前置 | S2 | +| 预估 | 1 天 | + +**动作(同一提交)** +1. **兜底 Bean**:muse-server 侧新增 `MarketFacadeFallbackAutoConfiguration`(仿既有 `MonolithFacadeFallbackAutoConfiguration`,`@AutoConfiguration` + `@Bean @ConditionalOnMissingBean`),为三个抽象方法接口提供**真实 fail-closed 方法体**(不能用空匿名类):`MarketHandoffTokenApi`(verify/consume → token 无效/false)、`MarketAssetSourceApi`(→ not found 语义响应)、`MarketAssetForkApi`(recordPublicFork → false)。中文注释写明「market 未装配的单人形态兜底;装配后真实现优先」,首个调用打一次 warn 日志。 +2. `muse-server/pom.xml` 注释 `muse-module-market-server` 依赖(保留 `muse-module-market-api`);S2 的 testExcludes 默认生效;台账 JSON market 32 条 dormant patch 生效。 +3. **市场语义端点核验(不改代码,补断言)**:新增/扩展 IT 断言 knowledge 侧市场语义端点在无 market 形态下的行为——`AppMuseKnowledgePublishController` 的 `POST /{kbId}/publish-prechecks|publish-snapshots|publish-readiness` 与 `AppMuseInstalledKnowledgeBaseController`:返回 fail-closed/空结果、无副作用(不产生任何 publish/installed 数据)。 +4. 全量回归:`local` + `real-pg`(专属 `_test` 库)。 + +**验收**:local + real-PG 全绿;MockMvc 或活体证明 `/app-api/market/**`、`/admin-api/market/**` 404;步骤 3 断言绿;单体启动日志无 UnsatisfiedDependency。 +**回滚**:revert 本提交(机制随开关一起回)。 + +--- + +## S4 配置与治理收口(member / 租户 / worker / yudao 脚手架 / admin) + +| | | +|---|---| +| 前置 | S3 | +| 预估 | 1~1.5 天 | + +**动作** +1. **yudao 厂商脚手架关停(review §5.1.5)**:`muse-module-ai-server/src/main/resources/application.yaml` 中 gemini/doubao/hunyuan/siliconflow/xinghuo/baichuan/midjourney/suno/web-search 九项 `enable: true` 全部改 `false`,**明文 API key 全部移除**改 `${ENV:}` 占位(注意脚手架是 `.enable`,newApi/dify 是 `.enabled`,勿混);向用户提示自查轮换已入 git 历史的 key。 +2. **启动断言**:新增 `SoloExternalAiProviderGateTest`(muse-server 测试,进 local 层):断言 ApplicationContext 中不存在 gemini/doubao 等厂商 ChatModel/客户端 Bean(白名单仅 Dify 与保留未配置的 New-API adapter 壳),防配置回漂。 +3. **member 固化**:核对并把「`muse.account.new-api.enabled=false`、全部多用户 worker enabled=false(默认值)」写入单人部署配置样例(S9 的 compose env)与部署手册;代码不动;entitlement/投影/导出的 `@ConditionalOnMissingBean` 兜底行为各补一条现状断言(有则免)。 +4. **租户与登录**:确认 `muse.tenant.enable: true` 不动、部署固定 `tenant-id=1`;核查 studio `LoginPage` 无注册/找回等多用户入口(有则随 S5 移除)。 +5. **admin 前端**:`muse-admin/apps/web-antd/src/router/routes/modules/muse.ts` 给「市场治理」「用户与权限」两条加 `hideInMenu: true`;`views/muse/newapi/index.vue` 移除网关绑定与额度配置两个写命令表单(保留本地用量只读观测),补「无写入口」测试断言;核查 yudao demo 静态路由模块(`leave.ts/pay.ts/ai.ts/bpm.ts/member.ts`)是否有顶级菜单漏出,漏则一并 hideInMenu。 +6. **system_menu 数据脚本**:产出幂等 SQL(停用 用户/角色/租户/部门/岗位(保留菜单管理与 admin 自身账号改密)、会员中心、支付、公众号、BPM、yudao-AI 娱乐面菜单;含反向恢复脚本),存 `muse-cloud/sql/solo/`,随部署手册引用,**不直接执行到共享 dev 库**(部署期动作)。 + +**验收**:local 全绿(含新增门禁);`grep -rn "api-key: sk-\|api-key: AIza" muse-cloud/**/application*.yaml` 零命中;admin `vitest/typecheck` 绿 + newapi 页无写入口断言绿 + 菜单隐藏断言绿。 +**回滚**:逐项 revert;menu SQL 有反向脚本。 + +--- + +## S5 studio 前端裁剪 + +| | | +|---|---| +| 前置 | S3(后端 market 已 404,避免删 UI 后留活后端);可与 S4 并行 | +| 预估 | 1 天 | + +**动作** +1. `src/app/routes/index.tsx`:删 4 条 market 路由、`/handoff/land/:targetOwner` 路由、`/works/:workId/editor/:chapterId`(EditorPage)路由;删除 `pages/EditorPage.tsx` 与 `features/handoff/` 下仅服务市场落地的组件(`AgentHandoffLanding` 等,先 grep 确认无创作主线引用)。 +2. `components/layout/Sidebar.tsx`:navItems 删「市场」「治理」。 +3. `features/account/components/PersonalCenter.tsx`:保留 资料 header + `UsageStats`,删 购买/授权/发布/安全事件/New-API 绑定 5 个 section 及其死 import。 +4. 知识页(`features/knowledge/`):删「从市场安装的」tab、「发布到市场」入口与预检 Modal;智能体页核实市场 handoff 入口随路由移除后无残留死链。 +5. 规划候选/文风检查:**无前端动作**(现状无 UI 入口,review §2.9);1b 再建。 +6. e2e:market 相关 spec(含 `market-install-kb-retrieval.spec.ts` 的 fixme)加 skip tag 隔离;MSW handlers 保留(DEV only);创作主线 spec 全量复跑。 + +**验收**:`tsc -b`、`vitest run`、`vite build` 绿;MSW-off Playwright 创作主线 spec(候选采纳/导入向导/导出下载/知识草稿/图谱/绑定/agent 生命周期)全绿;手输 `/market`、`/handoff/land/x` 落 404/重定向;隔离 spec 计数留档。 +**回滚**:revert 提交(文件在 git 历史)。 + +--- + +## S6 知识运行时切换 Dify Datasets + +| | | +|---|---| +| 前置 | S1(contract test 钉死契约);与隔离线并行 | +| 预估 | 2~3 天 | + +**动作** +1. **端口改造**(定性:重命名+操作裁剪+配置/审计/测试迁移):`RagFlowKnowledgeRuntimeClient` → `KnowledgeRuntimeClient`,裁掉 7 个无生产调用操作(`updateDatasetConfig/listDatasets/listChunks/runGraphRag/traceGraphRag/getKnowledgeGraph/health`);`MuseKnowledgeAuditService.recordRagflowCall` 更名 `recordRuntimeCall`(表 `muse_knowledge_ragflow_call` 不动,注释订正);同步全部实现/单测/调用方(机械 rename,IDE 级)。 +2. **新 adapter**:`DifyKnowledgeRuntimeClient`(实现 5 操作,HTTP 范式对齐 `RealDifyMuseAiRuntimeClient`:JDK HttpClient + 直连 ProxySelector + Bearer + 脱敏 fail-closed);`UnavailableKnowledgeRuntimeClient` 桩;装配类读 `muse.knowledge.dify.*`(base-url/dataset-api-key/timeout-seconds/retry-budget),缺任一装 Unavailable。API 映射按 review §5.2 表,以 S1 contract test 实测为准。 +3. **DDL**:`sql/muse/V__knowledge_runtime_batch.sql` 给 `muse_knowledge_processing_task` 加 `runtime_batch_id VARCHAR(160)`(注释:Dify 索引批次);上传链写入 batch,`MuseKnowledgeParseStatusPollWorker` 轮询主键 document_id→batch;绑定表 `ragflow_dataset_id` 列存 Dify dataset id(列注释订正,命名债登记)。 +4. **检索**:`MuseKnowledgeRetrievalApiImpl` 的 chunks 解析适配 Dify 响应;多授权 dataset **并行**检索 + 按 score 合并 topK;耗时与 score 分布打日志(观测跨库可比性)。 +5. **删除 RAGFlow**:`HttpRagFlowKnowledgeRuntimeClient`、其装配与配置类、`P1rRagFlowLiveAcceptanceIT`、`P1rKnowledgeRuntimeEndToEndLiveAcceptanceIT` 的 RAGFlow 形态、env 样例条目;全仓 grep `ragflow`(代码层)清零(表名/列名/迁移历史除外)。 +6. **worker 开启**:单人配置样例 `muse.knowledge.parse-poll-worker.enabled=true`。 +7. **live IT**:新 `P1rDifyKnowledgeRuntimeEndToEndLiveAcceptanceIT`:建库→上传→轮询至 completed→检索命中→授权门阻断路径;fail-closed 反向(无配置→CONFIG_MISSING)。 +8. **检索质量 smoke**:用真实创作素材(设定集/章节)建库检索,人工比对相关性并记录结论;不达标调 Dify 分块参数复测。 + +**验收**:knowledge 模块单测 + local + real-PG 全绿;live IT 全绿留档;质量 smoke 结论入总账;`grep -ri ragflow --include='*.java'` 仅剩 DO/表注释白名单。 +**回滚**:revert;RAGFlow 代码经 git 历史可回(review §10 口径:退役不承诺兼容)。 + +--- + +## S7.0 输出契约裁决(独立小步,先于 S7 开发) + +| | | +|---|---| +| 前置 | S1;建议在 S6 进行中穿插完成 | +| 预估 | 0.5 天(裁决)+ 用户确认 | + +**动作** +1. 按 `.agents/knowledge/external-deps-and-gotchas.md` §六配方起活体单体,用现有 New-API 配置真实生成一次(WorkspacePage AIPanel 触发)。 +2. 记录三件事:SSE 事件流各事件的实际载荷(chunk/done 里有没有正文全文)、AIPanel/CandidatePanel 给用户看到的内容、`muse_ai_suggestion.content_snapshot.content` 落库值。 +3. 出裁决备忘(执行报告,不新增过程文档,写入总账条目):**分支①**(现状无全文通路→立「运行时全文实时通路」工作项,方案骨架见 S7)或**分支②**(有全文通路→S7 收敛为 adapter 对齐)。 +4. 把备忘交项目所有者确认(review §12.4 预设倾向分支①)。 + +**验收**:裁决备忘含三件事的原始证据(SSE 抓包/截图/DB 查询);用户确认记录。 + +--- + +## S7 生成主链切 Dify + +| | | +|---|---| +| 前置 | S7.0 裁决确认;S6 不阻塞本步 | +| 预估 | 分支① 3~4 天 / 分支② 1~2 天 | + +**动作(分支①骨架,以裁决为准)** +1. **全文实时通路(不推翻数据主权)**:runtime 内部结果结构增加**不落库**的正文载荷字段(内存传递;候选表仍只存脱敏摘要+三审);executor 拿到全文后经任务事件/SSE 链路把正文推给前端(chunk 事件正文不持久化或仅落脱敏摘要,**不破坏 OpenAPI 已声明的 SSE 事件契约**——chunk.data 字段语义先查契约再定);两个 adapter(Dify/NewApi)把 provider 全文透出到该字段。 +2. **完整性护栏**:Dify chat 成功响应 finishReason 为常量不可用作完整性信号——按输出合同做结构化 envelope/长度合理性校验,疑似截断→失败可重试,不得静默进候选。 +3. **provider 切换**:在用系统 Agent 版本 `runtimeProvider` 配为 `dify` + `providerRef.dify`(app=「muse-写作透传」,credentialRef 指 S1 凭据);`muse.ai.dify.enabled=true` 进单人配置;`non-stream-read-timeout-seconds` 上调对齐 180s 总预算;**New-API 配置此步保留**(S8 验收后才摘)。 +4. **验证**:三审字段落库链已 provider 无关(现状),补 Dify 形态断言;live IT:Dify 生成→Shadow 候选(三审齐)→前端全文可见→`merge_after_edit` 采纳写 Canonical;fail-closed 反向(dify 未配/凭据错→拒绝,不回退 New-API)。 + +**验收**:live 生成链全绿;MSW-off 候选链 e2e 复跑绿(真 Dify);local+real-PG 全绿;fail-closed 反向绿。 +**回滚**:agent 版本 `runtimeProvider` 拨回 `new-api`(兼容逻辑未动)即回,代码 revert 独立。 + +--- + +## S8 导入解析切 Dify + +| | | +|---|---| +| 前置 | S7(共用 Dify 生成通路经验);**本步是 New-API 配置摘除的完成门** | +| 预估 | 1.5~2 天 | + +**动作** +1. **provider 选择机制**:`MuseAiImportParseService` 从单点注入 `NewApiMuseAiImportLlmParser` 改为按 `muse.ai.import.provider`(缺省 `dify`)选择 parser;来源标识按 provider 落(`dify_import_llm`/`new_api_import_llm`)。 +2. **Dify parser**:`DifyMuseAiImportLlmParser` 走「muse-全书解析」app,消费完整 JSON;语义与 New-API 版逐条对齐(401/403 fail-closed、408/429/5xx 重试退避、脱敏摘要);截断检测=JSON 完整性校验+章节数合理性检查(解析失败→可重试 bad response,job 诚实置 failed)。 +3. **反向测试**:`muse.ai.new-api.*` 缺失时 New-API parser fail-closed(`AI_IMPORT_LLM_UNAVAILABLE`)断言;Dify 未配同理。 +4. **摘 New-API 配置**:单人配置样例移除 `MUSE_AI_NEW_API_*`(adapter 代码保留);复跑全链确认无隐性依赖。 +5. **验证**:parser 单测;real-PG 导入链 IT(对齐 `P1rContentImportWizardCompletedApprovalIT` 模式换 Dify);live 全书解析;浏览器 MSW-off `import-wizard.spec.ts` 复跑(真 Dify)。 + +**验收**:上述四层证据全绿;New-API 配置移除后 local+real-PG+创作主线 e2e 全绿。 +**回滚**:`muse.ai.import.provider=new-api` + 恢复 env 即回。 + +--- + +## S9 部署收口 + 黄金旅程 + +| | | +|---|---| +| 前置 | S5、S6、S8 全部完成 | +| 预估 | 1~2 天 | + +**动作** +1. `docker-compose.solo.yml`(muse-server + PostgreSQL + Redis;env 指向 Dify 与两类 key;`tenant-id=1`;parse-poll worker 开、多用户 worker 全关、`muse.tenant.enable=true`);Dify 沿用 S1 官方 compose 独立部署。 +2. 新库 provision:沿用「`sql/dev/yudao-base-*-postgres.sql` 基座 + Flyway V1-V」配方,执行 S4 的 system_menu solo SQL。 +3. **无 Nacos 干净启动验证**:无 Nacos 环境起单体,日志无持续报错;有噪声则 `spring.cloud.nacos.discovery.enabled=false` 进 solo 配置。 +4. **黄金旅程 smoke(全程真后端真库真 Dify,`curl --noproxy` + 浏览器)**:登录→建作品→写正文→AI 候选(全文可见)→采纳(revision 递增+归因落库)→上传资料→索引 completed→检索命中→导出下载文件内容含真实正文;隔离核验:`/app-api/market/**` 404、knowledge 市场语义端点 fail-closed、studio 无市场入口、`SELECT` 确认无多用户 worker 活动痕迹。 +5. 部署手册(docs 内,含:compose 双栈、凭据表指引、菜单 SQL、回滚步骤、Dify 版本升级前须跑 live 验收的约定)。 + +**验收**:review v0.2 §9 全部 7 条判据逐条留证(这是 1a 的总验收门)。 +**回滚**:部署层面独立,不影响代码。 + +--- + +## S10 文档沉淀与归档 + +| | | +|---|---| +| 前置 | S9 | +| 预估 | 1 天 | + +**动作**:按 review v0.2 §11 表逐项执行——专题-05 v0.2(§1.5/§2/§7/§8 + S7.0 裁决结果)、架构-03(ADR-005/021 superseded、ADR-006 订正、新增单人阶段 ADR)、根 CLAUDE.md 决策表、1.0.0 缺口清单 P0-11 表述订正、`.agents/knowledge/` 三文件(external-deps 换 Dify 事实与新坑:两类 key/`.enable` vs `.enabled`/testExcludes profile 模式/Dify 版本钉死)、`docs/mvp/2.0.0-单人版交付计划.md` 新建、总览 2.0.0 口径改版、本 spec 与 review 归档 `docs/agent-specs/archive/`。 + +**验收**:`AgentsInfraIntegrityTest` 绿(README 索引/`.agent`/总账完整性);交叉引用抽查无断链;文档修订均带版本号与日期递增。 + +--- + +## 2. 阶段 1b 立项占位(1a 验收后逐项独立立项) + +按序:**P0-11 规划候选生成**(后端真实现走 Dify + studio 规划台新建候选 UI;验收=缺口清单标准,外呼换 Dify)→ **P0-12 文风检查**(同上)→ **P0-06 知识处理失败恢复 UI**(基于 Dify indexing-status 失败态;重试/删除/重传入口)→ **P0-03 版本恢复写入**(Content 写边界+新 revision+归因审计+旧草稿失效)→ **P1-11 SSE 统一客户端接组件**(首选场景:知识处理进度,与 P0-06 联动)。每项立项时先出小评审版(沿用本流程),不合并进 1a。 + +--- + +## 3. 全局完成判据与里程碑 + +- **1a 完成 = review v0.2 §9 七条判据全部机械证据齐备**(S9 汇总留档),缺一不得声称完成。 +- 里程碑顺序建议:M1=S0+S1(地基与外部实例就绪)/ M2=S3(market 摘除生效且全绿)/ M3=S6(知识链切换)/ M4=S8(New-API 退出)/ M5=S9(单机黄金旅程)。每个 M 点回写总账并可暂停评估。 diff --git a/docs/agent-specs/2026-07-07-2.0.0单人版改造-review.html b/docs/agent-specs/2026-07-07-2.0.0单人版改造-review.html new file mode 100644 index 00000000..061d4b56 --- /dev/null +++ b/docs/agent-specs/2026-07-07-2.0.0单人版改造-review.html @@ -0,0 +1,255 @@ + + + + + +Muse 2.0.0 单人版改造 · 一页边界图 + + + +
+ +
+

Muse 2.0.0 单人版改造 · 一页边界图

+
目标:单人自用创作工具 —— 外部依赖收敛到 Dify 一个服务,多用户/平台功能整体隔离,先收地基(1a)再打磨体验(1b)。评审版 v0.1 · 2026-07-07 · 详见同名 .md
+
+ +
+

1外部服务终态:3 个 → 1 个

+
+
+
改造前(1.0.0)
+
Muse
+
New-API生成主链 · 导入解析 · 账户配额管理
+
+
RAGFlow知识运行时(建库/上传/检索);GraphRAG 生产零调用
+
+
DifyAgent 运行时(刚接入,未部署)
+
+
yudao 厂商脚手架 ×9gemini/doubao/mj/suno… enable:true + 明文 key 在仓(须显式关停)
+
+
➜
+
+
改造后(2.0.0 单人版)
+
+
Muse
+
+ Dify(唯一外部依赖) +
+ chat/workflow:生成主链 + Agent 运行时 + chat/workflow:导入全书解析 + Datasets API:知识库 上传/索引/检索 +
+
模型 provider 配在 Dify 内,上游可指向自有 New-API 网关(对 Muse 透明)。Prompt 组装与知识授权过滤仍在 Muse 侧 —— Dify 只是运行时,不是事实源。
+
+
+
基础设施:PostgreSQL + Redis + Dify · RAGFlow(退役删除) · New-API 直连(代码保留,不再配置) · yudao 脚手架×9(enable→false+启动断言+key 出仓) · gateway/Nacos(不部署)
+
+
+
+ +
+

2功能边界:留什么 / 隔离什么 / 退役什么 / 打磨什么

+
+
+

保留单人创作主线

+
    +
  • 作品列表 + 写作台(编辑器/章节/AI 候选采纳/版本 diff/导入导出)
    • +
  • 智能体工作台(自建 Agent 生命周期、槽位绑定、沙盒试用)
    • +
  • 知识库(上传索引、草稿确认、实体关系图谱、授权检索)
    • +
  • 元引擎 MetaSchema(admin 定义 → 动态表单)
    • +
  • 单账号登录 + 用量观测
    • +
  • admin 治理核心(元结构/功能编排/AI 配置/全局知识库/任务/审计)
    • +
+
+
+

隔离搁置多用户 / 平台面(代码保留,装配摘除/开关关闭/入口删除)

+
    +
  • 市场全链(发现/详情/发布/审核/申诉/handoff/物化/召回)—— 后端摘装配
    • +
  • member 多用户子域(权益/配额/归因/New-API 绑定/安全深面/偏好通知)—— 既有开关
    • +
  • admin:市场治理、用户与权限(muse.ts 隐藏);yudao 用户/角色/租户/会员/支付/公众号/BPM 菜单(菜单数据停用);newapi 页禁写降只读
    • +
  • studio:市场 5 路由、个人中心 5 段、市场耦合入口
    • +
  • meta 影响预览 all-real(P0-09)、admin e2e(P0-10)划归多用户线
    • +
+
+
+

退役不再回来(git 可考古)

+
    +
  • RAGFlow adapter + live 验收 IT + env 样例(端口中立化为 KnowledgeRuntimeClient)
    • +
  • GraphRAG 全部脚手架(生产零调用,零损失)
    • +
  • studio 废弃 EditorPage demo 壳
    • +
  • 端口上 7 个从未被生产调用的操作
    • +
+
+
+

1b 打磨单人主线缺口(按序补齐)

+
    +
  • P0-11 规划候选生成(后端空桩→真实现,走 Dify)
    • +
  • P0-12 AI 文风检查(后端空桩→真实现)
    • +
  • P0-06 知识处理失败恢复 UI(基于 Dify indexing-status)
    • +
  • P0-03 版本恢复写入(走 Content 写边界+审计)
    • +
  • P1-11 SSE 统一客户端接业务组件
    • +
+
+
+
+ +
+

3后端装配终态(muse-server 单体)

+
+
+
muse-server(单进程,直服 /app-api 与 /admin-api)
+
+ content 作品/正文 + ai 编排/生成 + knowledge 知识库 + meta 元引擎 + member(仅登录/资料/用量) + system/infra 底座 + market(pom 注释摘除) + pay / bpm / mp / report(维持不装配) +
+
摘除前置:新增 3 个 fail-closed 兜底 Bean(@ConditionalOnMissingBean)—— MarketHandoffTokenApi→token 无效 · MarketAssetSourceApi→not found · MarketAssetForkApi→false。market 装回时真实现自动优先。member 投影已有 Unavailable 兜底。
+
+
+
租户红线保持 muse.tenant.enable=true、固定 tenant=1。关掉会全线 NPE(getRequiredTenantId)。
+
worker 现状多用户向 worker 默认全关;仅 AI dispatcher 与本地质量评估常开。
+
门禁先行覆盖门 market 域标 dormant、market IT 按装配分组;契约文件原地保留不删。
+
+
+
+ +
+

4节奏:1a 地基 → 1b 打磨

+
+
阶段 1a · 两条线并行(S0 基线与 S2 机制先于 S3 摘除;S1 是 Dify 线前提)
+
+
S0坐实并修复现红门禁基线
+
S1部署 Dify + contract test 钉契约
+
S2门禁/测试树机制(profile+dormant)
+
S3market 摘装配(兜底 Bean,原子生效)
+
S4member/yudao 脚手架/admin 收口
+
S5studio 前端裁剪
+
+
+
S6知识运行时 Dify adapter(5 操作)
+
S7S7.0 输出契约裁决 → 生成主链切 Dify
+
S8导入解析 Dify parser(New-API 退出门)
+
S9单机 compose + 黄金旅程 smoke
+
S10文档沉淀(专题-05/ADR/缺口清单订正)
+
+
+
+
阶段 1b · 逐项独立立项,真后端 e2e 验收
+
+
P0-11 规划候选规划台可创建/采纳
+
P0-12 文风检查可追踪结果
+
P0-06 知识失败恢复重试/删除/重传
+
P0-03 版本恢复新 revision+归因审计
+
P1-11 SSE 接组件任务进度/通知
+
+
+
+ Dify 迁移线 + 隔离线 + 门禁 + 收口 + 1b 打磨 +
+
1a 验收:local 门禁全绿 · real-PG 全绿 · Dify live 三链真打 · fail-closed 反向证据 · 创作主线 MSW-off e2e 全绿 · 单机 compose 起全栈黄金旅程 smoke · market API 物理 404。
+
+ +
+ + diff --git a/docs/agent-specs/2026-07-07-2.0.0单人版改造-review.md b/docs/agent-specs/2026-07-07-2.0.0单人版改造-review.md new file mode 100644 index 00000000..88e2c7be --- /dev/null +++ b/docs/agent-specs/2026-07-07-2.0.0单人版改造-review.md @@ -0,0 +1,378 @@ +# 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 等最高不变式。 +- 配套:[执行计划](2026-07-07-2.0.0单人版改造-execution.md) · [HTML 一页图](2026-07-07-2.0.0单人版改造-review.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 摘装配、多用户面搁置、恢复路径)。 + +--- + +## 四、目标架构 + +**外部依赖终态:** + +```mermaid +flowchart LR + subgraph before["改造前(1.0.0)"] + M1[muse-server] --> NA[New-API
生成/导入/配额] + M1 --> RF[RAGFlow
知识运行时] + M1 -.刚接入.-> DF1[Dify
Agent运行时] + M1 -.enable:true×9.-> YD["yudao 厂商脚手架
(gemini/doubao/…)"] + end + subgraph after["改造后(2.0.0 单人版)"] + M2[muse-server] --> DF2[Dify] + DF2 --> C1[chat/workflow
生成主链+Agent运行时+导入解析] + DF2 --> C2[Datasets API
知识库 建库/上传/索引/检索] + DF2 -. Dify 内配置模型 provider,
上游可指向自有 New-API .-> UP[(模型上游)] + end + before ==> after +``` + +**单体装配边界(muse-server):** + +```mermaid +flowchart TB + subgraph in["装配保留"] + content[content 作品/正文] + ai[ai 编排/生成/Agent] + knowledge[knowledge 知识库] + meta[meta 元引擎] + member["member 登录/资料/用量
(多用户子域按三类机制收口)"] + 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),配置时勿混。 + +超时口径: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 内归一,调用方不变 | + +**数据与配置落点**: + +- `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 与 `AppMuseInstalledKnowledgeBaseController`(已安装库)——**代码不动**,行为依赖 market 兜底与外部校验器配置,自然 fail-closed/空结果;S3 验收对其行为做显式断言(不可产生副作用),前端入口已删,不新增 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),不删。 + +**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 上下文。不含:市场安装库、发布入口(后端市场语义端点保留但 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 配置面可用。 + +--- + +## 七、阶段划分与步骤计划 + +```mermaid +flowchart LR + subgraph 1a["阶段 1a:地基(服务收敛+隔离+部署)"] + S0[S0 坐实并修复
现红门禁基线] --> S2[S2 门禁与测试树适配
profile 剥离/覆盖门 dormant] + S1[S1 部署 Dify
app/凭据 + contract test] --> S6[S6 知识运行时
Dify adapter] + S1 --> S70[S7.0 输出契约裁决
活体实测定分支] + S2 --> S3[S3 market 摘装配
兜底 Bean+pom+语义端点核验] + S3 --> S4[S4 member/租户/worker
yudao 脚手架关停/admin 收口] + S4 --> S5[S5 studio 裁剪] + S70 --> S7[S7 生成主链切 Dify] + S7 --> S8[S8 导入解析 Dify parser
含 provider 选择机制] + S5 & S6 & S8 --> S9[S9 部署收口
compose+黄金旅程 smoke] + S9 --> S10[S10 文档沉淀
专题-05/ADR/缺口清单订正/总账] + end + 1a --> 1b["阶段 1b:打磨
P0-11 规划候选 → P0-12 文风检查
→ P0-06 知识失败恢复 → P0-03 版本恢复
→ P1-11 SSE 接组件"] +``` + +说明:S0 是一切的前置(基线必须绿);S2 先于 S3(门禁与编译处置先行,保证摘除当天三层验证可跑且不假绿);S1→S6/S7 的 Dify 线与 S2→S5 的隔离线分属不同模块,可并行推进;S7.0 裁决若走分支①(全文通路立项),S7 工期按横切项重估,且其结果决定 S9 黄金旅程「候选可采纳」判据的具体口径。每个 S 都要独立可验证并回写总账。1b 各项按序独立立项,验收判据沿用缺口清单的「最小验收标准」并把外部模型调用替换为 Dify。任务级拆解见[执行计划](2026-07-07-2.0.0单人版改造-execution.md)。 + +--- + +## 八、风险与兜底 + +| 风险 | 影响 | 兜底 | +|---|---|---| +| 门禁基线现红(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 侧市场语义端点(publish-prechecks 等)行为 fail-closed 无副作用;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,已核实) | §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 记录为不受影响 |