# 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`。 ## 执行位置 ```text /Users/qingse/.config/superpowers/worktrees/oh-my-muse/dev-1.0.0 ``` 分支： ```text dev/1.0.0 ``` 开始时已执行： ```bash git status --short --branch git pull --ff-only origin dev/1.0.0 ``` 结果： ```text ## dev/1.0.0...origin/dev/1.0.0 Already up to date. HEAD 7f5553d ``` ## 已验证事实 P1R 覆盖矩阵中 AI 域当前状态： ```text 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 数据库验收事实： ```text 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 最终结果： ```text PASS ``` Quality / feasibility review 最终结果： ```text 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 执行： ```text /Users/qingse/.config/superpowers/worktrees/oh-my-muse/dev-1.0.0 ``` 分支： ```text dev/1.0.0 ``` 实现阶段按 `docs/superpowers/plans/2026-05-30-P1R-4-ai-real-api.md` 执行 Task 1-12，并使用 fresh subagent 落地；每个 implementation task 后按计划执行两类 review： 1. spec compliance review。 2. quality / feasibility review。 Task 1-12 覆盖范围： 1. Preflight 与覆盖基线冻结。 2. AI 基础设施与 V12 DDL。 3. Prompt / Quality Policy / Evaluation Run。 4. Agent / Tool Grant / Agent Slot。 5. AI Task / Runtime / Suggestion 创建基础。 6. AI Task SSE Stream。 7. Suggestion / Source Status / Source Event。 8. Job Admin/App Query、Cancel、Retry。 9. API Access Log / Business Audit。 10. Retire AI 合同兜底与覆盖门禁。 11. PostgreSQL / Flyway `_test` 迁移验收。 12. 最终验证、报告对账与 memory。 这些 review 和门禁只证明当前仓库内 dedicated 入口、状态机边界、报告和测试门禁符合 P1R-4 规格计划；没有真实端到端验收前，不代表 AI runtime、New-API、Security、Knowledge、Market 或统一事件流已经完成。 ### Coverage 最终状态 2026-05-31 Task 12 fresh 验证后的 coverage 对账： ```text 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`： ```text 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`： ```text muse-cloud/muse-server/pom.xml:109 muse-module-ai-server ``` 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： ```text 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 全量迁移。关键表： ```text 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 ``` 关键索引： ```text 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 验证命令和结果 ```bash python3 muse-cloud/scripts/p1r-audit-api-coverage.py --check ``` 结果：通过，重新生成 `docs/superpowers/reports/p1r-api-coverage.json` 和 `docs/superpowers/reports/p1r-api-coverage.md`。 ```bash 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 ``` 结果： ```text dedicated/needs_verification 41 content dedicated/needs_verification:51 meta dedicated/needs_verification:16 account dedicated/needs_verification:33 0 1 ``` ```bash 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。 ```bash 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，不是测试失败。 ```bash 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。 ### 最终验证命令和结果 ```bash 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 对账： ```text 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： ```bash 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： ```bash 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`： ```bash 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 全量迁移成功。 ```text 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 ``` 其他最终检查： ```text 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 `。 - 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 中断能力仍是后续验收项。