zizi-al/oh-my-muse
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
oh-my-muse/.agents/knowledge/external-deps-and-gotchas.md
lili e181669197 chore(agent-infra): 建立 agent 开发基建、清理历史 churn 并以 BC 违例整改验证 
本会话三部分交付,均经 JDK21 真实构建验证(非退出码,读 BUILD SUCCESS + Tests run):

1) Agent 开发基建(机械门禁优先)
- 入口与中枢:AGENTS.md、.agents/{knowledge,rules,skills,workflows}、CLAUDE.md 订正
- 订正 .gitignore:移除对 .agent/.agents 的忽略——它们是版本化 agent 基建,须入库(此前被忽略致克隆即缺)
- 机械门禁:CI 真跑测试(maven.yml JDK21、去 -Dmaven.test.skip)、覆盖台账去硬编码、
  BC 边界 ArchUnit 门(BcBoundaryArchTest)、契约先行门(ContractFirstGateTest:Flyway 卫生 + OpenAPI 结构)
- 单一进度源 docs/mvp/进度总账.md + 7 个 BC per-module .agent + mise.toml(锁 JDK21)
- P1 增量:AiSuggestionMergeProjectionFacade(Gap A)、ContentSourceServiceImpl 事务化 outbox 回流(Gap B)

2) 过期历史文档清理(97 份 churn,git 可恢复)
- 删 docs/memorys(34)、agent-specs 审阅/执行版+迁移review(34)、superpowers/plans+specs(25)、
  design-docs/临时+memorys(4);保留 superpowers/reports/coverage(门禁依赖)
- 唯一干货蒸馏入 .agents/knowledge/external-deps-and-gotchas.md;订正大纲/映射表/基线悬空引用

3) P1 harness 验证:消除已登记 BC 违例 ContentMuseWorkOwnerFacade
- content-api 新增只读端口 MuseContentWorkOwnerApi + content-server 实现(读自有 DAL);
  AI 适配器改消费该端口、移除全部 content.dal 依赖,AI 业务规则与 4 消费者不变
- 删除 ArchUnit 豁免 → 门禁收紧(反向红 31 例 / 正向绿;适配器单测 13/0F、端口实现 7/0F)

注:muse-studio/src(SSE 相关 4 文件)与 muse-module-ai/pom.xml(移除孤儿 contract-server)
为本会话之前已存在的未提交改动,非本次工作,未纳入本提交。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-14 04:38:07 -07:00

3.5 KiB
Raw Blame History

knowledge:外部依赖、验收环境与工程坑(蒸馏自历史 memorys)

蒸馏自 2026-06-14 已清理的过程文档(外部验收留痕、P1 收口、studio/admin 搭建),只保留"删了会真丢"的操作事实与踩坑。凭据只记来源文件,不记明文。过时即更。

一、外部依赖与验收环境

依赖 地址 关键事实
New-API(LLM 网关) http://100.64.0.8:3000,OpenAI 兼容 /v1/chat/completions 已验收模型 MiniMax-M2.5;容器 new-api 端口 3000;其 DB 在 infra-postgres(宿主 100.64.0.8:5433)
RAGFlow(知识运行时) http://100.64.0.8(及 :9380) /api/v1/datasets、/api/v1/retrieval;健康检查 /v1/system/healthz
开发 PG / Redis 见下方凭据来源 远端 PG 15(用户确认可用,不强制 PG16);Redis 100.64.0.8:6379

凭据来源(明文不入库,只记位置):

  • 外部验收:muse-cloud/scripts/dev/p1r-external-acceptance.env(set -a; . 该文件; set +a 加载;含 New-API base/token、MUSE_AI_NEW_API_DEFAULT_MODEL_KEY=MiniMax-M2.5、RAGFlow base/key、GraphRAG 开关)。
  • 开发基础设施:~/.config/muse-repo/infra.env(PG/Redis 连接 + 真实凭据)。
  • ⚠️ 安全:上述令牌仅限当前内网验收上下文;仓库若同步到更大范围,必须先轮换 New-API 令牌。

Live 验收 harness(opt-in,默认跳过,MUSE_P1R_EXTERNAL_ACCEPTANCE=true 才真跑):

  • muse-module-ai/.../application/muse/facade/P1rNewApiLiveAcceptanceIT.java(New-API)
  • muse-module-knowledge/.../application/muse/facade/P1rRagFlowLiveAcceptanceIT.java(RAGFlow)
  • 另:muse-server/.../framework/api/P1rAiRuntimeEndToEndLiveAcceptanceIT.java、P1rKnowledgeRuntimeEndToEndLiveAcceptanceIT.java
  • 输出脱敏(只打 endpoint/模型/id/状态/耗时/usage/key 长度 + sha256 前 12);RAGFlow smoke 会留存 p1r-live-<时间戳> dataset 不删。
  • runtime client live ≠ coverage completed:仍需 Muse API 触发 + 落库 + 审计 + 失败路径证据(见 golden-journey)。

二、外部集成兼容坑(实证)

  • New-API 系统管理令牌 ≠ RAGFlow key:用前者打 RAGFlow /api/v1/datasets 返回 code=109 Authentication error,必须用独立 ragflow-* key。
  • RAGFlow 建数据集:POST /api/v1/datasets 带 config:{} 返回 code=101 Extra inputs are not permitted;只发 name 才 code=0。adapter 已改为 createDataset 只发 name,config 走独立 updateDatasetConfig。
  • RAGFlow 文档状态轮询:用真实支持的 ?id=<docId>(单个);多 id 在 adapter 内 fail-closed 为 VALIDATION_ERROR。
  • GraphRAG attribution:默认 fail-closed(ATTRIBUTION_NOT_CONFIGURED);真跑需 MUSE_KNOWLEDGE_RAGFLOW_GRAPHRAG_ATTRIBUTION_READY=true + ..._GRAPHRAG_DATASET_ID。

三、前端 / 构建坑速查

  • studio(Vite + React + TS6.0):erasableSyntaxOnly 禁用 constructor 参数属性;exactOptionalPropertyTypes 下可选属性需规避写法;采纳/Diff 用 Coarse-to-Fine 分级 Diff 规避 3000+ 字正文上 O(N×M) LCS 性能爆炸;MSW 仅 import.meta.env.DEV 启用。
  • admin(Vben):museAdminApi 只拼 /muse/**(baseURL 已是 /admin-api,否则双前缀 /admin-api/admin-api);路由测试不能放 src/router/routes/modules/**(会被 Vite 动态路由 glob 当业务路由);Opsera pre-commit 缺失时跳过用 touch /tmp/.opsera-pre-commit-scan-passed。
  • git 边界(未决):muse-admin/ 经 .gitignore 作"独立子仓库边界",源码靠 git add -f 纳入——长期纳管方式待定(见进度总账 TODO)。