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

将 P1R-4 AI 41 个 operation 推进到 dedicated / needs_verification，退役 AI contract fallback，并补齐 runtime、SSE、job、audit、source、coverage 与 PostgreSQL/Flyway 门禁。

保留 completedOperations=0；真实 New-API chat、Security owner、Knowledge/RAGFlow、Market 和统一 events 仍留在后续验收。

2026-06-01 00:37:29 +08:00

20 KiB

Raw Blame History

P1R4 AI 真实 API 规格计划

日期：2026-05-30

背景

本次进入 P1R-4 AI Real API spec + implementation plan + review gate 阶段，只完成 AI 域真实 API 的事实盘点、规格、执行计划和阶段留痕，不进入代码实现。

P1R-4 的核心不是继续增强 MuseContractPersistenceService，也不是把 streamAiTask 的占位 SSE 事件包装成真实结果，而是设计如何把 AI 41 个 operation 推进到 dedicated / needs_verification。

执行位置

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

分支：

dev/1.0.0

开始时已执行：

git status --short --branch
git pull --ff-only origin dev/1.0.0

结果：

## dev/1.0.0...origin/dev/1.0.0
Already up to date.
HEAD 7f5553d

已验证事实

P1R 覆盖矩阵中 AI 域当前状态：

generic_persistence / incomplete    40
sse_placeholder / incomplete        1

同时保持：

completed operations = 0
Content 51 个 operation 为 dedicated / needs_verification
Meta 16 个 operation 为 dedicated / needs_verification
Account 33 个 operation 为 dedicated / needs_verification

当前代码事实：

AI 合同入口仍是 AdminMuseAiContractController 和 AppMuseAiContractController。
40 个非 SSE operation 仍通过 MuseContractPersistenceService 通用持久化处理 AI 路由，不是 P1R 完成证据。
streamAiTask 当前只发送一次固定摘要 muse ai task stream ready 的 done 事件后立即完成，被 scanner 识别为 sse_placeholder / incomplete。
muse-module-ai-server 已有 Yudao AI 基础服务、Spring AI model factory 和 provider tests，但没有持有 AI OpenAPI 41 个 operation 的 Muse dedicated controller / DTO / 状态机 / P1R 门禁。

当前 DDL 事实：

V4 已有 muse_ai_generation、muse_ai_suggestion、muse_agent、muse_agent_version、muse_agent_slot_binding、muse_prompt、muse_prompt_version、muse_quality_policy、muse_quality_policy_version、muse_tool_grant。
V7 已有 muse_domain_operation_record。
V8 已有 muse_domain_workflow_task。
这些表不能直接证明 AI task runtime、New-API correlation、SSE event replay、job state、source status、API access log 和 business audit 的真实闭环。

P1R-3 数据库验收事实：

flyway_success=true
migrations_executed=11
target_schema_version=11
flyway_latest=11:extend account real api schema
v11_tables=12

因此 P1R-4 如新增或修改 DDL，阶段收口前必须继续在同一 PostgreSQL 实例 _test 数据库跑真实 Flyway。

本阶段产物

规格：docs/superpowers/specs/2026-05-30-P1R-4-ai-real-api-design.md
计划：docs/superpowers/plans/2026-05-30-P1R-4-ai-real-api.md
留痕：docs/memorys/2026-05-30-P1R4AI真实API规格计划.md

Review 结果

本阶段按要求使用 fresh subagent 做了两轮文档 review，review 子代理均使用 gpt-5.5 + xhigh。

Spec compliance review 最终结果：

PASS

Quality / feasibility review 最终结果：

PASS

已按首轮 quality review 的阻塞意见补齐：

muse-server 当前只依赖 muse-module-ai-contract-server 的运行时装配风险，计划已要求实现阶段显式引入 muse-module-ai-server 或证明短期双依赖下合同兜底精确避让。
P1R-4 新增或修改 DDL 时的真实 PostgreSQL / Flyway _test 验收步骤，计划已补可复制命令、隔离 test DB、filesystem:sql/muse locations、V12 成功断言和失败处理。
New-API runtime 最小契约，计划已补 RuntimeCommand、RuntimeResult、RuntimeFailure、timeout 默认值、retry budget/backoff、错误分类、事务边界、correlation、失败状态映射和脱敏要求。

quality review 仍给出两条非阻塞建议：

实现阶段建议在 Task 2 产出 V12 后立即提前跑一次真实 Flyway _test，最终 Task 11 再复核。
Task 10 / Task 11 的 Maven gate 建议显式确认目标测试类和非零测试数，避免 -Dsurefire.failIfNoSpecifiedTests=false 被误用。

关键设计结论

P1R-4 目标状态只能是 dedicated / needs_verification，不能写成 completed。
AI owner 采用 muse-module-ai，新增 Muse 合同专用 Controller / Application Service / DTO / DAL / DDL，不复用通用持久化完成口径。
推荐新增 V12__extend_ai_real_api_schema.sql，扩展 V4 AI 表并补齐 AI command、runtime call、task event、job、source event、source status projection、evaluation run、API access log projection 和 business audit event。
createAiTask 只接受任务意图和可验证引用；source snapshot 和 runtime permission envelope 必须由服务端生成。
New-API runtime 必须有 timeout、失败分类、重试预算、correlation、脱敏 request/response summary；不可用时 fail closed，不能 fake success。
streamAiTask 属于 P1R-4，但只能实现 AI task 级 SSE；统一 /app-api/muse/events 留给 P1R-7。
Tool Grant 只能消费 Security facade 批准结果；AI runtime 不得自授权或扩权。
Knowledge / RAGFlow 和 Market 主流程不属于 P1R-4；不可用时使用合同内 source status / action policy 表达阻断或重验。
API access log / business audit 必须脱敏；敏感详情读取本身必须写入审计。
OpenAPI 未声明字段不得添加到响应，未声明 response status 不得泄露到响应。

当前阶段边界

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

未修改：

docs/api-contracts/ai/openapi.yaml
docs/superpowers/reports/p1r-api-coverage.*
muse-cloud/scripts/**
muse-cloud/muse-module-ai/** 实现代码
muse-cloud/sql/muse/**

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

下一步

进入 P1R-4 实现前，应从 docs/superpowers/plans/2026-05-30-P1R-4-ai-real-api.md Task 1 开始，按 fresh subagent + spec compliance review + quality / feasibility review 执行。

实现阶段完成口径：

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

2026-05-31 实现阶段收口更新

实现任务范围

本轮实现阶段继续在以下真实 worktree 执行：

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

分支：

dev/1.0.0

实现阶段按 docs/superpowers/plans/2026-05-30-P1R-4-ai-real-api.md 执行 Task 1-12，并使用 fresh subagent 落地；每个 implementation task 后按计划执行两类 review：

spec compliance review。
quality / feasibility review。

Task 1-12 覆盖范围：

Preflight 与覆盖基线冻结。
AI 基础设施与 V12 DDL。
Prompt / Quality Policy / Evaluation Run。
Agent / Tool Grant / Agent Slot。
AI Task / Runtime / Suggestion 创建基础。
AI Task SSE Stream。
Suggestion / Source Status / Source Event。
Job Admin/App Query、Cancel、Retry。
API Access Log / Business Audit。
Retire AI 合同兜底与覆盖门禁。
PostgreSQL / Flyway _test 迁移验收。
最终验证、报告对账与 memory。

这些 review 和门禁只证明当前仓库内 dedicated 入口、状态机边界、报告和测试门禁符合 P1R-4 规格计划；没有真实端到端验收前，不代表 AI runtime、New-API、Security、Knowledge、Market 或统一事件流已经完成。

Coverage 最终状态

2026-05-31 Task 12 fresh 验证后的 coverage 对账：

AI       41 dedicated / needs_verification
Content  51 dedicated / needs_verification
Meta     16 dedicated / needs_verification
Account  33 dedicated / needs_verification
completedOperations = 0

ssePlaceholderOperations = 1 仍存在，但对应的是 P1R-7 streamEvents：

events streamEvents GET /app-api/muse/events P1R-7 End-to-End Acceptance incomplete

P1R-4 的 streamAiTask 已退出 sse_placeholder，但仍是 needs_verification，不能写成 completed。

运行态装配事实

muse-server 当前使用 muse-module-ai-server：

muse-cloud/muse-server/pom.xml:109 <artifactId>muse-module-ai-server</artifactId>

P1R-4 不再依赖运行时 muse-module-ai-contract-server 作为 41 个 AI 路由的兜底入口；旧合同 Controller 文件已从 contract server 删除，route ownership gate 证明 AI 路由由 dedicated Controller 持有。

V12 PostgreSQL / Flyway `_test` 证据

2026-05-31 Task 12 已重新使用 ~/.config/muse-repo/infra.env 中的 PostgreSQL 凭据，在同实例隔离库运行 Flyway IT：

Database: jdbc:postgresql://100.64.0.8:5433/muse_local_p1r4_test (PostgreSQL 17.10)
flyway_success=true
migrations_executed=12
target_schema_version=12
flyway_latest=12:extend ai real api schema

P1rAiFlywayMigrationIT 使用 filesystem:sql/muse，先清理隔离 _test 库的 public schema，再执行 V1-V12 全量迁移。关键表：

muse_ai_command
muse_ai_runtime_call
muse_ai_task_event
muse_ai_job
muse_ai_source_event
muse_ai_source_status_projection
muse_ai_evaluation_run
muse_api_access_log_projection
muse_business_audit_event

关键索引：

uk_muse_ai_job_active_retry_group
idx_muse_api_access_log_tenant_time
idx_muse_api_access_log_actor_time
idx_muse_business_audit_tenant_time

Task 12 fresh 验证命令和结果

python3 muse-cloud/scripts/p1r-audit-api-coverage.py --check

结果：通过，重新生成 docs/superpowers/reports/p1r-api-coverage.json 和 docs/superpowers/reports/p1r-api-coverage.md。

jq -r '[.operations[] | select(.targetStage == "P1R-4 AI Real API" or .domain == "ai")] | group_by(.implementationStatus + "/" + .completionStatus)[] | [(.[0].implementationStatus + "/" + .[0].completionStatus), length] | @tsv' docs/superpowers/reports/p1r-api-coverage.json
jq -r '["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 41
content dedicated/needs_verification:51
meta dedicated/needs_verification:16
account dedicated/needs_verification:33
0 1

cd muse-cloud
JAVA_HOME=$(/usr/libexec/java_home -v 21) PATH="$JAVA_HOME/bin:$PATH" \
  mvn -o test -pl muse-server -am \
  -Dtest=P1rApiCoverageReportTest,P1rContentRealApiGateTest,P1rMetaRealApiGateTest,P1rAccountRealApiGateTest,P1rAiMigrationSqlTest,P1rAiRouteOwnershipTest,P1rAiRealApiGateTest \
  -Dsurefire.failIfNoSpecifiedTests=false

结果：通过；P1rApiCoverageReportTest、P1rContentRealApiGateTest、P1rMetaRealApiGateTest、P1rAccountRealApiGateTest、P1rAiMigrationSqlTest、P1rAiRouteOwnershipTest、P1rAiRealApiGateTest 共 35 tests，0 failures，0 errors，0 skipped。

cd muse-cloud
JAVA_HOME=$(/usr/libexec/java_home -v 21) PATH="$JAVA_HOME/bin:$PATH" \
  mvn -o test -pl muse-module-ai/muse-module-ai-server -am \
  -Dtest=AdminMuseAuditControllerAnnotationTest,MuseApiAccessLogQueryServiceTest,MuseApiAccessLogProjectionMapperTest,MuseBusinessAuditQueryServiceTest,MuseAiAuditServiceTest,MuseAiTaskStreamServiceTest,MuseJobServiceTest,MuseAiRuntimeProjectionServiceTest,MuseAiJobMapperTest \
  -Dsurefire.failIfNoSpecifiedTests=false

结果：通过；9 个目标测试类共 66 tests，0 failures，0 errors，0 skipped。输出中存在 Mockito 动态 agent 预警；MuseAiTaskStreamServiceTest 覆盖失败路径时有预期 WARN，不是测试失败。

cd muse-cloud
JAVA_HOME=$(/usr/libexec/java_home -v 21) PATH="$JAVA_HOME/bin:$PATH" \
  mvn -o test -pl muse-server -am \
  -Dtest=P1rAiFlywayMigrationIT \
  -Dp1r.flyway.url="jdbc:postgresql://${MUSE_POSTGRES_HOST}:${MUSE_POSTGRES_PORT}/muse_local_p1r4_test" \
  -Dp1r.flyway.user="$MUSE_POSTGRES_USERNAME" \
  -Dp1r.flyway.password="$MUSE_POSTGRES_PASSWORD" \
  -Dp1r.flyway.locations="filesystem:sql/muse" \
  -Dsurefire.failIfNoSpecifiedTests=false

结果：通过；1 test，0 failures，0 errors，0 skipped；PostgreSQL 17.10，V1-V12 全量迁移成功。

未验证和 residual risk

当前状态仍是 needs_verification，没有任何 operation 标记为 completed。
尚未完成真实端到端 acceptance；coverage 与 Maven gate 不能替代真实用户流、真实 New-API runtime、Security owner、Knowledge / RAGFlow、Market owner 和生产式事件链路验收。
P1R-7 统一 /app-api/muse/events 的 streamEvents placeholder 仍然存在，明确不属于 P1R-4 范围。
本轮 Task 12 已成功重跑 Flyway IT；如果后续环境缺少 MUSE_POSTGRES_PASSWORD 等凭据，只能引用本段 surefire / Flyway 输出作为既有证据，并重新运行非凭据 gates。

变更面记录

OpenAPI：未修改 docs/api-contracts/ai/openapi.yaml。
Scanner：未修改 muse-cloud/scripts/p1r-audit-api-coverage.py。
Coverage：更新 docs/superpowers/reports/p1r-api-coverage.json 和 docs/superpowers/reports/p1r-api-coverage.md，不包含 completed 状态。
SQL：新增 muse-cloud/sql/muse/V12__extend_ai_real_api_schema.sql。
Java：muse-server 装配 muse-module-ai-server；删除 AI contract server 旧兜底 Controller；新增 AI dedicated Controller / Application Service / DTO / DAL / Mapper / Facade / Guard / SSE / audit / job / source / task 相关代码与 P1R gate tests。

2026-06-01 P1R-4 review blocker 修复与最终验证

本轮继续 P1R-4 实现阶段，针对 fresh spec / quality review 暴露的阻塞问题做了三轮修复和复审；最终两类 fresh review 均 PASS。

已验证事实

P1rAiRouteOwnershipTest 已从纯静态扫描增强为 Spring RequestMappingHandlerMapping / HandlerMethod 运行态归属门禁，验证 AI 41 个 route 由 dedicated AI Controller 持有，不属于旧 *MuseAiContractController。
新增 muse-cloud/sql/muse/V13__add_ai_runtime_payload_store.sql，为 createAiTask 的短生命周期 provider payload 提供数据库恢复路径；payload 使用 EncryptTypeHandler，不进入 job.input_summary、runtime_call.request_summary、audit summary 或 coverage。
MuseAiRuntimePayloadStore 从单机内存 TTL 改为 DB backed short TTL store；runtime 成功、不可重试失败、异常无 response、cancelled 终态都会按 tenantId + job DB pk 删除 runtime payload；仅 retryable failure 保留 payload 给下一轮 attempt。
adminRetryJob 对带 userInstructionLength/hash 的失败 AI task job，会在 active payload 存在时复制 payload 到 retry job；payload 缺失或过期时不创建必然失败的 retry job。
MuseAiRuntimeClient.RuntimeCommand.toString() 已覆盖 Java record 默认输出，只输出脱敏排障字段和 hasProviderPayload，不输出 providerExecutionPrompt、inputSummary、prompt 字段名或用户指令正文。
cancelJob 对 queued/running/streaming job 推进到 cancelled 后，同步删除 runtime payload；对应 admin/user cancel、linked task、tenant fallback 均有测试覆盖。
V13 cleanup SQL 覆盖 expired、consumed、soft-deleted 残留；mapper 测试已断言 deleted = TRUE 分支。

fresh review gate

最终 fresh spec compliance review：PASS。

最终 fresh quality / feasibility review：PASS。

非阻塞风险：

cancel running/streaming 只能保证本地 job/task 状态、payload 删除和 runtime 结果不覆盖 cancelled；无法中断已经发出的 provider HTTP 调用，仍可能产生外部调用成本。
idx_muse_ai_runtime_payload_cleanup 对 expired/consumed 有帮助；pure deleted=true 且未过期的行主要靠 DELETE 条件扫到，索引不是最优形态。
Maven 默认 Java 可能是 17；P1R-4 验证必须显式使用 Java 21。

最终验证命令和结果

python3 muse-cloud/scripts/p1r-audit-api-coverage.py --check

结果：通过，重新生成 docs/superpowers/reports/p1r-api-coverage.json 和 docs/superpowers/reports/p1r-api-coverage.md。

coverage 对账：

AI       41 dedicated / needs_verification
Content  51 dedicated / needs_verification
Meta     16 dedicated / needs_verification
Account  33 dedicated / needs_verification
completedOperations = 0
ssePlaceholderOperations = 1

唯一剩余 sse_placeholder 是 events / streamEvents / P1R-7 End-to-End Acceptance / incomplete，不属于 P1R-4。

AI module focused tests：

cd muse-cloud
JAVA_HOME=$(/usr/libexec/java_home -v 21) mvn -o test \
  -pl muse-module-ai/muse-module-ai-server -am \
  -Dtest=MuseAiRuntimeJobDispatcherTest,MuseAiJobMapperTest,MuseAiTaskServiceTest,MuseAiRuntimeClientTest,MuseAiRuntimeProjectionServiceTest,MuseAiTaskStreamServiceTest,MuseJobServiceTest,MuseAiAuditServiceTest \
  -Dsurefire.failIfNoSpecifiedTests=false

结果：通过；114 tests, 0 failures, 0 errors, 0 skipped。

P1R AI gate tests：

cd muse-cloud
JAVA_HOME=$(/usr/libexec/java_home -v 21) mvn -o test \
  -pl muse-server -am \
  -Dtest=P1rAiRealApiGateTest,P1rAiRouteOwnershipTest,P1rAiMigrationSqlTest \
  -Dsurefire.failIfNoSpecifiedTests=false

结果：通过；20 tests, 0 failures, 0 errors, 0 skipped。

真实 PostgreSQL / Flyway _test：

cd muse-cloud
set -a
. ~/.config/muse-repo/infra.env
set +a
P1R4_TEST_DB="${P1R4_TEST_DB:-muse_local_p1r4_test}"
JAVA_HOME=$(/usr/libexec/java_home -v 21) PATH="$JAVA_HOME/bin:$PATH" \
  mvn -o test -pl muse-server -am \
  -Dtest=P1rAiFlywayMigrationIT \
  -Dp1r.flyway.url="jdbc:postgresql://${MUSE_POSTGRES_HOST}:${MUSE_POSTGRES_PORT}/${P1R4_TEST_DB}" \
  -Dp1r.flyway.user="$MUSE_POSTGRES_USERNAME" \
  -Dp1r.flyway.password="$MUSE_POSTGRES_PASSWORD" \
  -Dp1r.flyway.locations="filesystem:sql/muse" \
  -Dsurefire.failIfNoSpecifiedTests=false

结果：通过；PostgreSQL 17.10，同实例隔离库 muse_local_p1r4_test，V1-V13 全量迁移成功。

flyway_success=true
migrations_executed=13
target_schema_version=13
flyway_latest=13:add ai runtime payload store
v13_tables=muse_ai_command,muse_ai_runtime_call,muse_ai_task_event,muse_ai_job,muse_ai_source_event,muse_ai_source_status_projection,muse_ai_evaluation_run,muse_api_access_log_projection,muse_business_audit_event,muse_ai_runtime_payload
v13_indexes=uk_muse_ai_job_active_retry_group,idx_muse_api_access_log_tenant_time,idx_muse_api_access_log_actor_time,idx_muse_business_audit_tenant_time,uk_muse_ai_runtime_payload_job,idx_muse_ai_runtime_payload_active,idx_muse_ai_runtime_payload_cleanup

其他最终检查：

git diff --check                         PASS，无输出
git diff -- docs/api-contracts/ai/openapi.yaml muse-cloud/scripts/p1r-audit-api-coverage.py  PASS，无输出

New-API 探索事实和缺口

New-API 只读探索确认：

Base URL：http://100.64.0.8:3000
Health：GET /api/status 可用，返回 200。
OpenAI-compatible endpoints：GET /v1/models、POST /v1/chat/completions。
Auth：Authorization: Bearer <token>。
Muse internal sync：POST /api/internal/muse/users/sync，需要 X-Muse-Service-Secret。
GET /v1/models 使用 Muse token 返回 200，模型数 23。
POST /v1/chat/completions smoke 在 qwen3.5-plus、doubao-seed-2.0-lite 上出现超时；因此不能把真实 New-API 端到端验收写成已完成。

当前完成口径

P1R-4 本阶段 dedicated gate 已达成：

AI 41 个 operation 全部为 dedicated / needs_verification。
streamAiTask 已退出 sse_placeholder，改为 task 级 SSE dedicated 实现。
completedOperations = 0。
Content 51、Meta 16、Account 33 保持 dedicated / needs_verification。
未修改 AI OpenAPI 合同，未修改 coverage scanner 掩盖缺口。

仍不能写成 completed：

真实 New-API chat completions 端到端尚未跑通。
Security owner 仍是 facade / projection / unavailable 边界，未做完整外部 owner 验收。
Knowledge / RAGFlow、Market、统一 /app-api/muse/events 仍不属于 P1R-4，本轮未验收。
真实用户流、生产式事件链路、provider 已发出请求的 cancel 中断能力仍是后续验收项。

20 KiB Raw Blame History Unescape Escape

P1R4 AI 真实 API 规格计划

背景

执行位置

已验证事实

本阶段产物

Review 结果

关键设计结论

当前阶段边界

下一步

2026-05-31 实现阶段收口更新

实现任务范围

Coverage 最终状态

运行态装配事实

V12 PostgreSQL / Flyway _test 证据

Task 12 fresh 验证命令和结果

未验证和 residual risk

变更面记录

2026-06-01 P1R-4 review blocker 修复与最终验证

已验证事实

fresh review gate

最终验证命令和结果

New-API 探索事实和缺口

当前完成口径

20 KiB

Raw Blame History

V12 PostgreSQL / Flyway `_test` 证据