zizi-al/oh-my-muse
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(agents): 蒸馏 S9 部署收口 4 坑入 knowledge gotchas §八

Browse Source 
sql/muse compose 挂载 / 覆盖台账 JSON 是 SoT 别重生成 / 加 service @Resource 依赖须真跑跨模块 IT / 全新作品 AI 需 muse_tool_grant authz 种子

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
lili 2026-07-08 10:26:05 -07:00
parent 1c2d51bfd4
commit c9dbd51ed1
1 changed files with 9 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
.agents/knowledge/external-deps-and-gotchas.md
View File

@ -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` 会解析失败。 - **坑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)。 - 实证(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 已接线"。 - **残留(脚本覆盖不到)**:远端 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 迁移引入。