From c9dbd51ed1ea017ec10e912758962cc0b5e76431 Mon Sep 17 00:00:00 2001 From: lili Date: Wed, 8 Jul 2026 10:26:05 -0700 Subject: [PATCH] =?UTF-8?q?docs(agents):=20=E8=92=B8=E9=A6=8F=20S9=20?= =?UTF-8?q?=E9=83=A8=E7=BD=B2=E6=94=B6=E5=8F=A3=204=20=E5=9D=91=E5=85=A5?= =?UTF-8?q?=20knowledge=20gotchas=20=C2=A7=E5=85=AB?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit sql/muse compose 挂载 / 覆盖台账 JSON 是 SoT 别重生成 / 加 service @Resource 依赖须真跑跨模块 IT / 全新作品 AI 需 muse_tool_grant authz 种子 Co-Authored-By: Claude Opus 4.8 (1M context) --- .agents/knowledge/external-deps-and-gotchas.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/.agents/knowledge/external-deps-and-gotchas.md b/.agents/knowledge/external-deps-and-gotchas.md index 81c65c80..dde13f43 100644 --- a/.agents/knowledge/external-deps-and-gotchas.md +++ b/.agents/knowledge/external-deps-and-gotchas.md @@ -177,3 +177,12 @@ bash muse-cloud/scripts/verify-openapi-diff.sh # → 5 场景全绿即门禁 - **坑4:跨文件 `$ref` 靠目录结构**:events 契约 `$ref: '../openapi-base.yaml'`,故 base/head 必须各自保留 `docs/api-contracts/` 完整目录(workflow 用 `git worktree` 检出整树、脚本用 `cp -R` 整目录),单独拷 `openapi.yaml` 会解析失败。 - 实证(oasdiff v1.19.1,全部 7 域真实契约,5/5):无变更/新增可选参数/新增端点→**放行**(rc=0);参数变必填(`request-parameter-became-required`)/删端点(`api-path-removed-without-deprecation`)→**拦截**(rc=1)。 - **残留(脚本覆盖不到)**:远端 Gitea Actions 触发管道(`pull_request` paths 触发、`base.sha` worktree、docker 镜像拉取)须一次真实 PR(改 `docs/api-contracts/**`)首跑确认。未首跑前不得宣称"CI 已实拦破坏性变更",只能称"检测逻辑+循环逻辑已本地实证、root workflow 已接线"。 + +## 八、2.0.0 单人版(1a)S9 部署收口坑(2026-07-08 实证) + +单人版 solo 栈从零部署 + 全程真后端真库真 Dify 黄金旅程活体验收(review v0.2 §9 判据 0–7 全留证,commit `7a6e46b2`+`1c2d51bf`)暴露四坑: + +- **坑1:solo compose 必须挂 `sql/muse` 给 muse-server**。muse 业务表的 36 个 Flyway 迁移在 `sql/muse/`、**未打进 jar**(`application.yaml` 的 `flyway.locations` 含 `filesystem:sql/muse`、相对容器 WORKDIR `/muse-server`);`docker-compose.solo.yml` 须 `- ./sql/muse:/muse-server/sql/muse:ro`,漏挂则 Flyway "No migrations found"、muse 表全缺、AI worker 每秒 `relation "muse_ai_job" does not exist`。yudao 基座走 PG initdb(`sql/dev/yudao-base-*`)。mini-infra 从零真验才抓得到(桩掩盖)。部署 SSOT=`docs/mvp/2.0.0-单人版部署手册.md`。 +- **坑2:覆盖台账 `docs/superpowers/reports/p1r-api-coverage.json` 是 SoT、别重生成**。它含 32 个 market operation 的 `dormant` 人工口径(2.0.0 单人版 market 摘装配),但生成器 `p1r-audit-api-coverage.py` 只产 completed/needs_verification、**不产 dormant**;跑生成器会把 dormant 冲回 completed(210→242)摧毁口径、`P1rApiCoverageReportTest` 反而红。改台账须**手改 JSON**(外科手术式、往返序列化保最小 diff),别重生成。长期收敛(生成器支持 dormant 或明确 JSON 为 SoT)是开放债。 +- **坑3:给 service 加 `@Resource` 依赖后必须真跑跨模块 IT**。S8 给 `MuseAiImportParseService` 加 `@Resource MuseAiProperties`,muse-server 极简上下文 IT(`P1rContentImportWizardCompletedApprovalIT` 的 `ImportWizardConfiguration`)缺该 bean → ApplicationContext 加载失败;**只编译修复不够**(S8 当轮只编译修没真跑、漏了运行时),真跑 IT 才暴露,修=IT 上下文补对应 @Bean。教训:改 service 依赖图后 per-task 只测本模块会漏,收口须整分支跑跨模块 real-PG IT(跑法见 §四)。 +- **坑4:全新作品跑 AI 需库内 authz 种子**。当前 P1R-4 切片不接 Security 主流程创建 AI 运行时授权,唯一成功路径是预置 `muse_tool_grant` 投影(与 work1 grant id=1 同口径)。对全新作品跑 AI 黄金旅程须先按 grant id=1 模板 INSERT 一行 `muse_tool_grant`(scope 指向目标 work),否则 AI 生成秒失败于授权缺失。既有架构状态、非 Dify 迁移引入。