22 KiB
2.0.0 单人版改造执行计划(执行版)
- 版本:v1.0
- 日期:2026-07-07
- 承接:评审版方案 v0.2(已经 Codex + Opus 双对抗评审,P0×3/P1×8 全部吸收,见其 §13)。设计意图、事实基线、风险与验收总纲以 review v0.2 为准,本文只做任务级拆解;两文冲突时以 review v0.2 为准并回改本文。
- 读者:执行 agent(每个 S 步可独立派工)与项目所有者(里程碑验收)。
0. 执行纪律(硬约束,每个 S 步适用)
- 完成=机械验证:每步的「验收」命令必须真跑并留输出证据;默认 skipped / mock-only / 台账门禁不得作为完成证据。改动后按依赖链全量回归(local 必跑;涉库涉外部再跑 real-PG / live)。
- 契约先行:DDL 只走
sql/muse/V<next>__*.sql(编号取当前最大+1);OpenAPI 不删端点、不动 market 契约参数(dormant 只允许x-扩展);接口变更先改docs/api-contracts/*再实现。 - 最小改动:只动本步清单内文件;禁止顺手重构;代码全中文注释,外部交互与失败路径必须有可追溯日志。
- 原子提交:S3 的「pom 注释 + 兜底 Bean + 测试排除生效 + 台账 dormant」必须同一提交生效,避免中间态红门(S2 只交付机制,S3 拨开关)。
- 回写:每步完成回写
docs/mvp/进度总账.md+ 涉及模块.agent;不新增过程状态文档。 - 环境与坑:内网凭据按
~/.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 <module>/target/maven-status或 clean),否则出现假红/假绿。 - 派工分档:各 S 步执行子代理默认
opus;纯机械批量(改配置值、菜单 SQL、批量 hideInMenu)可haiku;S7.0 裁决结论与全文通路设计评审升fable(或主会话终裁)。
1. 步骤总图
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 天 |
动作
- 真跑
bash muse-cloud/scripts/run-p1r-verification.sh local,记录全部红项清单。 - 修已静态坐实的红:
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;若发现台账证据缺失,按反假绿规则先补证据再改数,不许直接拨数字。 - 顺带核查同文件其他域计数断言(knowledge/content/meta/account)与台账一致性。
- 复跑 local 至全绿。
验收:run-p1r-verification.sh local BUILD SUCCESS,输出留档进度总账。
回滚:纯测试断言修正,revert 即可。
S1 部署 Dify + 契约钉死
| 前置 | 无;宿主待用户确认(review §12.1,默认 mini-infra) |
| 预估 | 1 天 |
动作
- 按 Dify 官方 docker-compose 在内网宿主部署,钉死版本号(镜像 tag 记入凭据文档与 compose;禁 latest)。
- Dify 控制台初始化:创建工作区;建两个 app——「muse-写作透传」chat app(prompt 极简透传、创作温度、绑定模型 provider,上游可配自有 New-API 网关)、「muse-全书解析」app/workflow(低温、要求严格 JSON 输出);生成 app 级 API key ×2 与工作区级知识库 API key(两类 key 不同,不可混用)。
- 凭据落位:
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 同步生效亦可)。 - 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 惯例)。 - chat-messages smoke:用既有
RealDifyMuseAiRuntimeClient配置真打「写作透传」app 一次(可借既有 Dify 单测/新增最小 live 用例),证明 app 级 key 与网络通。
验收:contract live IT 全绿输出留档;Dify 控制台两 app 可用;检索 smoke 返回结构与 §S6 映射表一致(不一致→先改 review v0.2 映射表再动工)。 回滚:纯新增测试与外部部署,无代码风险。
S2 门禁与测试树适配(机制就绪,不拨开关)
| 前置 | S0 |
| 预估 | 1~1.5 天 |
动作
- 测试树 profile 机制:
muse-cloud/muse-server/pom.xml增加 maven profile ——默认 profile 通过 maven-compiler-plugintestExcludes+ surefire excludes 排除下列 14 个文件(全部位于muse-server/src/test/java/cn/iocoder/muse/server/framework/api/),market-assembledprofile 激活时不排除:P1rMarketAdminAppealCompletedApprovalIT、P1rMarketAdminAssetReadsCompletedApprovalIT、P1rMarketAdminPublishReviewCompletedApprovalIT、P1rMarketDiscoveryFavoriteCompletedApprovalIT、P1rMarketEventsPublishEndToEndTest、P1rMarketGovernanceWriteCompletedApprovalIT、P1rMarketHandoffClusterCompletedApprovalIT、P1rMarketKbForkMaterializationIT、P1rMarketLicenseInstallCompletedApprovalIT、P1rMarketProducerAppealCompletedApprovalIT、P1rMarketPublishProducerCompletedApprovalIT、P1rMarketplaceDiscoveryReadsCompletedApprovalIT、P1rAccountAdminPurchaseRecordsCompletedApprovalIT、P1rAccountMarketRecordsCompletedApprovalIT(后两个是 Account 侧混合测试,一并排除并在台账登记)。P1rMarketRealApiGateTest一并纳入排除清单(它虽不 import market-server,但其断言语义=market 装配态)。本步排除默认不生效(profile 缺省仍编译全量),S3 原子拨开关。 - 覆盖门 dormant 口径:改造
P1rApiCoverageReportTest——断言从硬编码常量改为按域派生;引入dormant完成状态口径(dormant 域豁免 completed 计数与 testFiles 强制,总量 242 不变);台账 JSON 的 market 32 条置 dormant 的数据变更本步只准备 patch 不提交生效。 - 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 方案不删路由)。 - 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 天 |
动作(同一提交)
- 兜底 Bean:muse-server 侧新增
MarketFacadeFallbackAutoConfiguration(仿既有MonolithFacadeFallbackAutoConfiguration,@AutoConfiguration+@Bean @ConditionalOnMissingBean),为三个抽象方法接口提供真实 fail-closed 方法体(不能用空匿名类):MarketHandoffTokenApi(verify/consume → token 无效/false)、MarketAssetSourceApi(→ not found 语义响应)、MarketAssetForkApi(recordPublicFork → false)。中文注释写明「market 未装配的单人形态兜底;装配后真实现优先」,首个调用打一次 warn 日志。 muse-server/pom.xml注释muse-module-market-server依赖(保留muse-module-market-api);S2 的 testExcludes 默认生效;台账 JSON market 32 条 dormant patch 生效。- 市场语义端点核验(不改代码,补断言):新增/扩展 IT 断言 knowledge 侧市场语义端点在无 market 形态下的行为——
AppMuseKnowledgePublishController的POST /{kbId}/publish-prechecks|publish-snapshots|publish-readiness与AppMuseInstalledKnowledgeBaseController:返回 fail-closed/空结果、无副作用(不产生任何 publish/installed 数据)。 - 全量回归:
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 天 |
动作
- 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。 - 启动断言:新增
SoloExternalAiProviderGateTest(muse-server 测试,进 local 层):断言 ApplicationContext 中不存在 gemini/doubao 等厂商 ChatModel/客户端 Bean(白名单仅 Dify 与保留未配置的 New-API adapter 壳),防配置回漂。 - member 固化:核对并把「
muse.account.new-api.enabled=false、全部多用户 worker enabled=false(默认值)」写入单人部署配置样例(S9 的 compose env)与部署手册;代码不动;entitlement/投影/导出的@ConditionalOnMissingBean兜底行为各补一条现状断言(有则免)。 - 租户与登录:确认
muse.tenant.enable: true不动、部署固定tenant-id=1;核查 studioLoginPage无注册/找回等多用户入口(有则随 S5 移除)。 - 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。 - 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 天 |
动作
src/app/routes/index.tsx:删 4 条 market 路由、/handoff/land/:targetOwner路由、/works/:workId/editor/:chapterId(EditorPage)路由;删除pages/EditorPage.tsx与features/handoff/下仅服务市场落地的组件(AgentHandoffLanding等,先 grep 确认无创作主线引用)。components/layout/Sidebar.tsx:navItems 删「市场」「治理」。features/account/components/PersonalCenter.tsx:保留 资料 header +UsageStats,删 购买/授权/发布/安全事件/New-API 绑定 5 个 section 及其死 import。- 知识页(
features/knowledge/):删「从市场安装的」tab、「发布到市场」入口与预检 Modal;智能体页核实市场 handoff 入口随路由移除后无残留死链。 - 规划候选/文风检查:无前端动作(现状无 UI 入口,review §2.9);1b 再建。
- 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 天 |
动作
- 端口改造(定性:重命名+操作裁剪+配置/审计/测试迁移):
RagFlowKnowledgeRuntimeClient→KnowledgeRuntimeClient,裁掉 7 个无生产调用操作(updateDatasetConfig/listDatasets/listChunks/runGraphRag/traceGraphRag/getKnowledgeGraph/health);MuseKnowledgeAuditService.recordRagflowCall更名recordRuntimeCall(表muse_knowledge_ragflow_call不动,注释订正);同步全部实现/单测/调用方(机械 rename,IDE 级)。 - 新 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 实测为准。 - DDL:
sql/muse/V<next>__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(列注释订正,命名债登记)。 - 检索:
MuseKnowledgeRetrievalApiImpl的 chunks 解析适配 Dify 响应;多授权 dataset 并行检索 + 按 score 合并 topK;耗时与 score 分布打日志(观测跨库可比性)。 - 删除 RAGFlow:
HttpRagFlowKnowledgeRuntimeClient、其装配与配置类、P1rRagFlowLiveAcceptanceIT、P1rKnowledgeRuntimeEndToEndLiveAcceptanceIT的 RAGFlow 形态、env 样例条目;全仓 grepragflow(代码层)清零(表名/列名/迁移历史除外)。 - worker 开启:单人配置样例
muse.knowledge.parse-poll-worker.enabled=true。 - live IT:新
P1rDifyKnowledgeRuntimeEndToEndLiveAcceptanceIT:建库→上传→轮询至 completed→检索命中→授权门阻断路径;fail-closed 反向(无配置→CONFIG_MISSING)。 - 检索质量 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 天(裁决)+ 用户确认 |
动作
- 按
.agents/knowledge/external-deps-and-gotchas.md§六配方起活体单体,用现有 New-API 配置真实生成一次(WorkspacePage AIPanel 触发)。 - 记录三件事:SSE 事件流各事件的实际载荷(chunk/done 里有没有正文全文)、AIPanel/CandidatePanel 给用户看到的内容、
muse_ai_suggestion.content_snapshot.content落库值。 - 出裁决备忘(执行报告,不新增过程文档,写入总账条目):分支①(现状无全文通路→立「运行时全文实时通路」工作项,方案骨架见 S7)或分支②(有全文通路→S7 收敛为 adapter 对齐)。
- 把备忘交项目所有者确认(review §12.4 预设倾向分支①)。
验收:裁决备忘含三件事的原始证据(SSE 抓包/截图/DB 查询);用户确认记录。
S7 生成主链切 Dify
| 前置 | S7.0 裁决确认;S6 不阻塞本步 |
| 预估 | 分支① 3 |
动作(分支①骨架,以裁决为准)
- 全文实时通路(不推翻数据主权):runtime 内部结果结构增加不落库的正文载荷字段(内存传递;候选表仍只存脱敏摘要+三审);executor 拿到全文后经任务事件/SSE 链路把正文推给前端(chunk 事件正文不持久化或仅落脱敏摘要,不破坏 OpenAPI 已声明的 SSE 事件契约——chunk.data 字段语义先查契约再定);两个 adapter(Dify/NewApi)把 provider 全文透出到该字段。
- 完整性护栏:Dify chat 成功响应 finishReason 为常量不可用作完整性信号——按输出合同做结构化 envelope/长度合理性校验,疑似截断→失败可重试,不得静默进候选。
- provider 切换:在用系统 Agent 版本
runtimeProvider配为dify+providerRef.dify(app=「muse-写作透传」,credentialRef 指 S1 凭据);muse.ai.dify.enabled=true进单人配置;non-stream-read-timeout-seconds上调对齐 180s 总预算;New-API 配置此步保留(S8 验收后才摘)。 - 验证:三审字段落库链已 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 天 |
动作
- provider 选择机制:
MuseAiImportParseService从单点注入NewApiMuseAiImportLlmParser改为按muse.ai.import.provider(缺省dify)选择 parser;来源标识按 provider 落(dify_import_llm/new_api_import_llm)。 - Dify parser:
DifyMuseAiImportLlmParser走「muse-全书解析」app,消费完整 JSON;语义与 New-API 版逐条对齐(401/403 fail-closed、408/429/5xx 重试退避、脱敏摘要);截断检测=JSON 完整性校验+章节数合理性检查(解析失败→可重试 bad response,job 诚实置 failed)。 - 反向测试:
muse.ai.new-api.*缺失时 New-API parser fail-closed(AI_IMPORT_LLM_UNAVAILABLE)断言;Dify 未配同理。 - 摘 New-API 配置:单人配置样例移除
MUSE_AI_NEW_API_*(adapter 代码保留);复跑全链确认无隐性依赖。 - 验证:parser 单测;real-PG 导入链 IT(对齐
P1rContentImportWizardCompletedApprovalIT模式换 Dify);live 全书解析;浏览器 MSW-offimport-wizard.spec.ts复跑(真 Dify)。
验收:上述四层证据全绿;New-API 配置移除后 local+real-PG+创作主线 e2e 全绿。
回滚:muse.ai.import.provider=new-api + 恢复 env 即回。
S9 部署收口 + 黄金旅程
| 前置 | S5、S6、S8 全部完成 |
| 预估 | 1~2 天 |
动作
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 独立部署。- 新库 provision:沿用「
sql/dev/yudao-base-*-postgres.sql基座 + Flyway V1-V」配方,执行 S4 的 system_menu solo SQL。 - 无 Nacos 干净启动验证:无 Nacos 环境起单体,日志无持续报错;有噪声则
spring.cloud.nacos.discovery.enabled=false进 solo 配置。 - 黄金旅程 smoke(全程真后端真库真 Dify,
curl --noproxy+ 浏览器):登录→建作品→写正文→AI 候选(全文可见)→采纳(revision 递增+归因落库)→上传资料→索引 completed→检索命中→导出下载文件内容含真实正文;隔离核验:/app-api/market/**404、knowledge 市场语义端点 fail-closed、studio 无市场入口、SELECT确认无多用户 worker 活动痕迹。 - 部署手册(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 点回写总账并可暂停评估。