zizi-al/oh-my-muse
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
oh-my-muse/docs/memorys/2026-06-01-P1R5KnowledgeRAGFlow规格计划.md
zizi 7155285940 feat(p1r): 实现 Knowledge RAGFlow dedicated gate 
将 P1R-5 Knowledge 59 个 operation 从合同兜底推进到专用 Knowledge controller/service/DAL/DDL 与 gate 测试，状态保持 dedicated / needs_verification，不标记 completed。
2026-06-02 19:36:02 +08:00

9.3 KiB
Raw Blame History

P1R5 Knowledge RAGFlow 规格计划

日期：2026-06-01

背景

本次进入 P1R-5 Knowledge / RAGFlow 的规格与计划阶段，只完成事实盘点、规格、执行计划和阶段留痕，不进入代码实现。

真实工作面：

/Users/qingse/.config/superpowers/worktrees/oh-my-muse/dev-1.0.0

分支：

dev/1.0.0

已执行同步

本轮开始时发现本地 dev/1.0.0 ahead 1，最新提交为：

4f38bf0 feat(p1r): 实现 AI 真实 API dedicated gate

已执行：

git push origin dev/1.0.0
git pull --ff-only origin dev/1.0.0
git status --short --branch
git log --oneline -3

当前状态：

## dev/1.0.0...origin/dev/1.0.0
4f38bf0 feat(p1r): 实现 AI 真实 API dedicated gate
7f5553d docs(p1r): 补记 Account 数据库迁移验收
7c92a49 docs(p1r): 记录 Account 真实 API 收口

上述是产出本阶段文档前的同步快照。规格、计划和本 memory 产出后，工作树会出现这三份 P1R-5 文档未跟踪；进入实现前必须重新检查状态，并确认只存在这些 review 文档或已完成提交。

已验证事实

P1R-5 preflight：

jq -r '[.operations[] | select(.targetStage == "P1R-5 Knowledge / RAGFlow Real API" or .domain == "knowledge")] | group_by(.implementationStatus + "/" + .completionStatus)[] | [(.[0].implementationStatus + "/" + .[0].completionStatus), length] | @tsv' docs/superpowers/reports/p1r-api-coverage.json

输出：

generic_persistence/incomplete	59

targetStage 实际为：

P1R-5 Knowledge Real API

当前 Knowledge 实现事实：

  • docs/api-contracts/knowledge/openapi.yaml 存在，声明 59 个 operation。
  • muse-module-knowledge-server 当前只有 Admin/App 合同兜底 Controller 和 package-info.java。
  • 59 个 operation 均走 MuseContractPersistenceService，不能作为真实 API 完成证据。
  • V5 已有知识库、资料、资料版本、实体、关系、草稿和绑定初始表，但没有 RAGFlow 映射、处理任务、GraphRAG、绑定预检、发布快照、source projection、RAGFlow call log 和 draft decision 表。
  • muse-module-ai 下旧 /ai/knowledge/** 是 Yudao AI 管理入口和 Spring AI VectorStore 参考实现，不是 P1R-5 Knowledge owner。

RAGFlow 只读事实：

  • 本地 RAGFlow repo：/Users/qingse/Sync/local-git/ragflow。
  • RAGFlow HTTP API 需要 Authorization: Bearer <YOUR_API_KEY>；文档和日志不得写完整 key。
  • 公开集成面应使用 /api/v1/**，包括 dataset、document、parse/chunk、retrieval、GraphRAG、knowledge graph；UI 内部 /v1/kb、/v1/document、/v1/chunk 不能作为 Muse 后端合同。
  • 2026-06-01 已验证 http://100.64.0.8:9380/v1/system/healthz 返回 200，db/doc_engine/redis/storage/status 均为 ok。
  • 2026-06-01 已验证 http://100.64.0.8/v1/system/healthz 返回 200，db/doc_engine/redis/storage/status 均为 ok。
  • 2026-06-01 已验证 http://100.64.0.11:9380/v1/system/healthz 5 秒超时，不能作为当前默认地址。
  • RAGFlow parse 成功响应没有外部 task id；P1R-5 应用 Muse 内部 processing task/correlation 承接，再轮询 RAGFlow document run/progress/progress_msg 归一状态。
  • RAGFlow 上传只接收 multipart file；Knowledge 的 file、entryContent、linkUrl 必须先经材料化和扫描边界转成 fileRef，FileService/对象存储不可用时只能 blocked/needs_verification 或 failed。
  • GraphRAG 构图依赖 RAGFlow 默认 chat model 和 token 成本；未确认其经 New-API 且可归因前，P1R-5 只实现 GRAPH_NOT_SUPPORTED / ATTRIBUTION_NOT_CONFIGURED / needs_verification 边界，不写真实构图成功。
  • 当前仍未验证可用于 P1R-5 smoke 的 RAGFlow API key、dataset/document/retrieval/GraphRAG smoke，因此不能写 completed。

New-API 只读事实：

  • 本地 new-api repo：/Users/qingse/Sync/local-git/new-api。
  • New-API 提供 /api/status、/v1/models、/v1/chat/completions 和 Muse internal sync/revoke/status 接口。
  • 2026-06-01 已验证 http://100.64.0.8:3000/api/status 返回 200 且 success=true。
  • P1R-5 边界中 New-API 负责 LLM 调用；RAGFlow 负责知识引擎；Knowledge owner 负责 Muse 知识事实和状态机。

本阶段产物

  • 规格：docs/superpowers/specs/2026-06-01-P1R-5-knowledge-ragflow-real-api-design.md
  • 计划：docs/superpowers/plans/2026-06-01-P1R-5-knowledge-ragflow-real-api.md
  • 留痕：docs/memorys/2026-06-01-P1R5KnowledgeRAGFlow规格计划.md

当前阶段边界

本阶段只完成规格、计划、review gate 和 memory 留痕，不实现代码。

未修改：

  • docs/api-contracts/knowledge/openapi.yaml
  • docs/api-contracts/ai/openapi.yaml
  • muse-cloud/scripts/p1r-audit-api-coverage.py
  • muse-cloud/muse-module-knowledge/** 实现代码
  • muse-cloud/sql/muse/**

当前不应把任何 Knowledge operation 标为 completed。

Review gate 状态

待执行：

  1. spec compliance review。
  2. quality / feasibility review。

review 通过前不能进入 P1R-5 实现阶段。

下一步

完成两轮 fresh review 后，如通过，再按 docs/superpowers/plans/2026-06-01-P1R-5-knowledge-ragflow-real-api.md Task 1 开始实现。

实现阶段完成口径：

  • Knowledge 59 个 operation 退出 generic_persistence。
  • Knowledge 59 个 operation 全部为 dedicated / needs_verification。
  • AI 41、Content 51、Meta 16、Account 33 保持 dedicated / needs_verification。
  • completed operations 仍为 0，除非后续有真实端到端验收证据并单独批准。
  • 不修改 OpenAPI 或 scanner 掩盖缺口。
  • 如新增 V14 DDL，阶段收口前必须在同一 PostgreSQL 实例 _test 数据库跑真实 Flyway。

2026-06-02 实现 gate 留痕

本轮已推进到 P1R-5 Knowledge / RAGFlow dedicated gate 验证阶段，当前只允许表述为：

  • Knowledge 59 = dedicated / needs_verification
  • completedOperations = 0
  • ssePlaceholderOperations = 1
  • 唯一剩余 sse_placeholder 仍为 P1R-7 events / streamEvents

已验证命令：

python3 muse-cloud/scripts/p1r-audit-api-coverage.py --check
jq -r '[.operations[] | select(.domain == "knowledge")] | group_by(.implementationStatus + "/" + .completionStatus)[] | [(.[0].implementationStatus + "/" + .[0].completionStatus), length] | @tsv' docs/superpowers/reports/p1r-api-coverage.json
jq -r '["ai","content","meta","account"][] as $d | [$d, ([.operations[] | select(.domain==$d)] | group_by(.implementationStatus + "/" + .completionStatus)[] | (.[0].implementationStatus + "/" + .[0].completionStatus + ":" + (length|tostring)))] | @tsv' docs/superpowers/reports/p1r-api-coverage.json
jq -r '.summary | [.completedOperations,.ssePlaceholderOperations] | @tsv' docs/superpowers/reports/p1r-api-coverage.json

输出：

dedicated/needs_verification	59
ai	dedicated/needs_verification:41
content	dedicated/needs_verification:51
meta	dedicated/needs_verification:16
account	dedicated/needs_verification:33
0	1

PostgreSQL/Flyway _test 迁移 gate 已验证：

cd muse-cloud
set -a
. ~/.config/muse-repo/infra.env
set +a
export P1R_FLYWAY_PASSWORD="$MUSE_POSTGRES_PASSWORD"
P1R5_TEST_DB="${P1R5_TEST_DB:-muse_local_p1r5_test}"
JAVA_HOME=$(/usr/libexec/java_home -v 21) PATH="$JAVA_HOME/bin:$PATH" \
  mvn -o clean install -DskipTests -Dspring-boot.repackage.skip=true -pl muse-server -am
JAVA_HOME=$(/usr/libexec/java_home -v 21) PATH="$JAVA_HOME/bin:$PATH" \
  mvn -o test -pl muse-server \
  -Dtest=P1rKnowledgeFlywayMigrationIT \
  -Dp1r.flyway.url="jdbc:postgresql://${MUSE_POSTGRES_HOST}:${MUSE_POSTGRES_PORT}/${P1R5_TEST_DB}" \
  -Dp1r.flyway.user="$MUSE_POSTGRES_USERNAME" \
  -Dp1r.flyway.locations="filesystem:sql/muse"

验证结果：

P1rKnowledgeFlywayMigrationIT: Tests run: 1, Failures: 0, Errors: 0, Skipped: 0
migrations_executed=14
successful_migration_count=14
target_schema_version=14
flyway_latest=14:extend knowledge ragflow real api schema

最终 Maven gate 已验证：

cd muse-cloud
JAVA_HOME=$(/usr/libexec/java_home -v 21) PATH="$JAVA_HOME/bin:$PATH" \
  mvn -o clean install -DskipTests -Dspring-boot.repackage.skip=true -pl muse-server -am
JAVA_HOME=$(/usr/libexec/java_home -v 21) PATH="$JAVA_HOME/bin:$PATH" \
  mvn -o test -pl muse-server \
  -Dtest=P1rApiCoverageReportTest,P1rKnowledgeRealApiGateTest,P1rKnowledgeRouteOwnershipTest,P1rKnowledgeMigrationSqlTest

验证结果：

P1rKnowledgeRouteOwnershipTest: 6 tests, 0 failures
P1rKnowledgeMigrationSqlTest: 8 tests, 0 failures
P1rKnowledgeRealApiGateTest: 8 tests, 0 failures
P1rApiCoverageReportTest: 5 tests, 0 failures
Total: 27 tests, 0 failures, 0 errors

Knowledge focused tests 已验证：

cd muse-cloud
JAVA_HOME=$(/usr/libexec/java_home -v 21) PATH="$JAVA_HOME/bin:$PATH" \
  mvn -o test -pl muse-module-knowledge/muse-module-knowledge-server -DfailIfNoTests=true

验证结果：

muse-module-knowledge-server: 194 tests, 0 failures, 0 errors

完整性检查：

git diff --check
git diff -- docs/api-contracts/knowledge/openapi.yaml docs/api-contracts/ai/openapi.yaml muse-cloud/scripts/p1r-audit-api-coverage.py

输出均为空。当前仍不能表述为 P1R-5 completed，也不能表述任何 Knowledge operation completed；RAGFlow dataset/document/retrieval/GraphRAG 外部 smoke 仍属于 needs_verification，不得伪造成功。