7155285940
将 P1R-5 Knowledge 59 个 operation 从合同兜底推进到专用 Knowledge controller/service/DAL/DDL 与 gate 测试，状态保持 dedicated / needs_verification，不标记 completed。
240 lines
9.3 KiB
Markdown
240 lines
9.3 KiB
Markdown
# P1R5 Knowledge RAGFlow 规格计划
|
||
|
||
日期：2026-06-01
|
||
|
||
## 背景
|
||
|
||
本次进入 P1R-5 Knowledge / RAGFlow 的规格与计划阶段，只完成事实盘点、规格、执行计划和阶段留痕，不进入代码实现。
|
||
|
||
真实工作面：
|
||
|
||
```text
|
||
/Users/qingse/.config/superpowers/worktrees/oh-my-muse/dev-1.0.0
|
||
```
|
||
|
||
分支：
|
||
|
||
```text
|
||
dev/1.0.0
|
||
```
|
||
|
||
## 已执行同步
|
||
|
||
本轮开始时发现本地 `dev/1.0.0` ahead 1，最新提交为：
|
||
|
||
```text
|
||
4f38bf0 feat(p1r): 实现 AI 真实 API dedicated gate
|
||
```
|
||
|
||
已执行：
|
||
|
||
```bash
|
||
git push origin dev/1.0.0
|
||
git pull --ff-only origin dev/1.0.0
|
||
git status --short --branch
|
||
git log --oneline -3
|
||
```
|
||
|
||
当前状态：
|
||
|
||
```text
|
||
## 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：
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
输出：
|
||
|
||
```text
|
||
generic_persistence/incomplete 59
|
||
```
|
||
|
||
`targetStage` 实际为：
|
||
|
||
```text
|
||
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`
|
||
|
||
已验证命令：
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
输出：
|
||
|
||
```text
|
||
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 已验证：
|
||
|
||
```bash
|
||
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"
|
||
```
|
||
|
||
验证结果：
|
||
|
||
```text
|
||
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 已验证：
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
验证结果：
|
||
|
||
```text
|
||
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 已验证：
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
验证结果：
|
||
|
||
```text
|
||
muse-module-knowledge-server: 194 tests, 0 failures, 0 errors
|
||
```
|
||
|
||
完整性检查：
|
||
|
||
```bash
|
||
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，不得伪造成功。
|