# 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，不得伪造成功。