linyuhang
/
PMFlow
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
PMFlow/docs/architecture/CODE_REFERENCE_INDEX.md

83 KiB
Raw Blame History

CODE REFERENCE INDEX

1. 目的

  • 本文档承接 PMFlow 的“新增代码参考模式”与高频代码入口索引。
  • CLAUDE.md 只保留摘要与跳转入口；详细的接口、页面、服务参考清单统一维护在这里。
  • 当新增 API、关键页面入口、工作流入口或参考样式发生变化时，应同步更新本文档。

2. 后端接口参考

2.1 通用与基础

  • 新增后端接口：参考 backend/app/api/sstc_api/ 的结构
  • 新增数据库表：参考 alembic/versions/ 最新 migration
  • 新增飞书事件处理：参考 backend/app/services/integrations/feishu_integration_service/
  • 飞书卡片动作回调：参考 backend/app/api/feishu_api/card_action_routes.py 与 backend/app/services/integrations/feishu_integration_service/mixin_card_action.py
  • 用户管理接口：参考 backend/app/api/users_api/（统一前缀 GET /users/、GET /users/me、GET /users/available、GET /users/{user_id}）
  • 审计查询接口：参考 backend/app/api/audit.py（GET /audit/operations）
  • 配置读取类接口：参考 backend/app/api/llm_providers.py（GET /ai-steward/llm/providers）
  • LLM 引擎与供应商连接接口：参考 backend/app/api/llm_engines.py（GET/POST /ai-steward/llm-engines、PUT/DELETE /ai-steward/llm-engines/{engine_id}、PUT /ai-steward/llm-engines/{engine_id}/enabled、POST /ai-steward/llm-engines/{engine_id}/default-fallback、POST /ai-steward/llm-engines/{engine_id}/test、POST /ai-steward/llm-engines/{engine_id}/capability-probe、POST /ai-steward/llm-engines/{engine_id}/capability-attest、PUT /ai-steward/llm-engines/settings）；该接口属于 PMFlow platform AI Ops，要求 platform.ai_routing.manage，并由 backend/app/api/router.py 核心路由加载，API_ROUTE_PROFILE=lean 下也必须可用；供应商连接支持多个同时启用，default_fallback_engine_id 只表示无规则命中时的兜底运行时，旧 active_engine_id 仅兼容历史返回；平台供应商配置固定读取内部平台运行作用域（默认 PMFLOW_PLATFORM_RUNTIME_TENANT_ID=1），不随客户 workspace tenant 切换；供应商 runtime 在 integrations(type='llm_engine').config.engines[*].capabilities 分层保存声明能力、capability_probe 探测证据和后端派生 effective_capabilities，并同步兼容 capability_evidence；能力探测按目标 registry 执行 basic_chat/model_self_report/structured_output/json_schema/tool_calling/streaming/long_context_32k 等，JSON Schema 独立于普通 JSON 输出；streaming 是 stream=true 增量响应的传输/运行特性，不属于供应商编辑弹窗中的声明能力矩阵，供应商页只可在“探测明细”和独立“运行特性”区域展示，禁止混入“已验证可用”模型能力列表；声明能力必须完整展示，不得用固定数量截断；任一声明能力缺少 live/provider_contract/operator_verified 证据时，能力状态不得显示为 passed；model_self_report 是低成本真实上游调用的自报参考，只作为 evidence_strength=model_self_report 辅助证据，不满足 protected slot 发布，也不参与能力总状态聚合，供应商页只能在独立“模型自报参考”块展示，不得作为“探测明细”能力项 pill；长上下文按配置窗口记录，已知官方模型规格（如 DashScope qwen-plus）可作为 provider_contract verified evidence，未知供应商声明窗口只记录 declared_only；高成本长上下文可由平台操作人在供应商页“确认长上下文”写入 operator_verified/operator_attestation 证据，必须带确认窗口和来源元数据，满足发布校验但不写 AI 调用审计，因为没有真实上游 endpoint 交互；已确认的高窗口覆盖低阈值展示，1024K 不再额外展示 128K；旧数据由服务层按 provider/model 归一化默认能力但不会冒充 probe evidence；DashScope/Qwen 的 provider code 统一为配置值 dashscope，旧内部 code glm 已物理移除，不得在 API、前端、审计或路由 fallback 中恢复；列表响应返回 available_actions 作为前端行操作真源，后端同时阻止未连通设为兜底、未连通能力探测、停用连接测试、启用中删除和兜底默认删除
  • AI 路由与供应商产品化控制台接口：参考 backend/app/api/ai_routing.py（GET /ai-routing/overview、GET/PUT /ai-routing/team-policy、GET /ai-routing/admin-console、GET/PUT/POST /ai-routing/capability-slots*、POST /ai-routing/diagnostics/run）；team policy 属于客户空间 AI 使用设置，overview/admin-console/diagnostics/capability-slots 属于 /platform/* AI Operations Console；admin-console.providers[] 返回脱敏供应商状态和 available_actions，前端只渲染当前单据状态可执行的操作；能力槽位发布校验读取 SLOT_REQUIREMENTS、供应商 capabilities 与 capability_probe evidence，draft 不满足要求、缺 verified evidence 或 evidence 过期时返回 critical 并阻止 protected slot publish；operator_verified 只作为长上下文等高成本能力的人工确认发布证据，过期后视为 stale；low 缺 probe 只 warning；structured/tool/long_context/external_query 均为正式 configurable 槽位，可保存 draft 并通过 validate/publish/rollback 控制上线；structured 槽只有 publish 后才会被 llm_service.generate_structured_object 运行时消费，未发布 draft 不生效，active structured runtime 选择会跳过 disabled/deleted runtime 和缺 structured_output/json_schema 能力的 runtime，primary 失败后只走同一 slot 的 fallback chain，全部失败则显式失败，active slot 已配置但无可用 runtime 时保护结构化函数显式失败、非保护函数带 slot_degraded=true 降级；long_context active slot 只在 routing meta 显式请求长上下文槽时消费，tool active slot 只在 routing meta 显式请求工具槽或 execution_mode=local_planner|local_worker 时消费，二者都会跳过 disabled/deleted runtime 和能力不足 runtime；external_query active slot 绑定 external provider registry/MCP adapter/bounded live search fallback，而不是普通 LLM engine，只在 route_mode=external 后由 external_query_service 消费，internal query 和 draft 不生效，provider/verifier/source filtering 不满足时 publish 被阻止；private/multimodal 仍是不可配置候选槽；admin-console.scene_slot_matrix 由 AIRoutingGovernanceService._build_scene_slot_matrix() 聚合业务场景、required/current slot、active/draft slot runtime、active version、draft dirty、capability gap、近期失败计数、影响摘要、能力覆盖和保护场景风险；admin-console.slot_observability 按 active low/high/structured/long_context/tool/external_query 槽位从 ai_call_logs 聚合 24h/7d 调用、失败、fallback、degraded、成本估算、延迟估算和脱敏失败样本；该接口由 backend/app/api/router.py 核心路由加载，API_ROUTE_PROFILE=lean 下也必须可用
  • Function Runtime Profile 接口：参考 backend/app/api/ai_routing.py、backend/app/config/ai_function_runtime_profiles.py 与 backend/app/services/ai_function_runtime_profile_service.py（GET /ai-routing/function-runtime-profiles、PUT /ai-routing/function-runtime-profiles/{function_name}/draft、POST /ai-routing/function-runtime-profiles/validate、POST /ai-routing/function-runtime-profiles/{function_name}/smoke、POST /ai-routing/function-runtime-profiles/publish）；该能力归属 /platform/* AI Operations Console，要求 platform.ai_routing.manage，配置保存到 integrations(type='ai_function_runtime_profiles')。业务场景路由通过 admin-console.scene_slot_matrix[].function_runtime_profiles 展示场景内生成运行合同、active/draft token 预算、冒烟状态和 7d 观测；运行时只消费 active profile，draft 仅用于编辑、校验、真实 smoke 和发布门禁。当前 pmflow_launch_draft_v1 使用 active profile 控制 max_tokens / repair_max_tokens / temperature / response_mode，并在 routing_meta 写入 function_runtime_profile_version / function_runtime_max_tokens / function_runtime_repair_max_tokens。
  • AI 调用审计接口：参考 backend/app/api/ai_call_traces_api.py 与 backend/app/services/ai_call_trace_service.py（GET /ai-call-traces、GET /ai-call-traces/{trace_id_or_log_id}）；该接口属于 /platform/* AI Operations Console，要求 platform.ai_routing.manage，由 backend/app/api/router.py 核心路由加载，API_ROUTE_PROFILE=lean 下也必须可用；数据源是 ai_call_logs，追踪字段 trace_id / user_id / provider / model / latency_ms / routing_meta / prompt_key / prompt_release_id / prompt_source 与真实上游 provider payload 字段 provider_request_payload / provider_response_payload / provider_attempts 由 llm_service 写入；能力探测日志必须带 direct_operation/probe_run_id/probe_target/probe_method/evidence_strength/failure_code，审计列表默认展示真实上游 probe_capability_* 调用行，不再写入或默认展示额外 probe_engine_capabilities 汇总行；probe_capability_model_self_report 属于真实上游短调用但只表示自报参考；非上游声明/合同检查只进入能力证据，不进入 AI 调用审计；详情页展示探测元数据而不是误标为主槽位路由；列表支持 prompt_key/source/release 过滤；接口必须区分 raw provider code 与面向运营展示的 provider_label/runtime_label/engine_name，DashScope 供应商编码统一为 dashscope，不得恢复旧 provider code；接口返回 function_label/scene_label 作为中文展示字段，raw function/provider/routing key 只作为诊断信息；structured_timeout 必须独立展示为“模型超时”并返回 error_diagnosis/runtime_policy，不得与 JSON 无效、空响应、HTTP 异常混为同一种结构化失败；详情可返回完整脱敏 provider 请求/响应 payload 与尝试链，不返回明文 key、bearer、手机号、邮箱、原始 provider headers 或未脱敏 raw payload。
  • Prompt 资产运营接口：参考 backend/app/api/prompt_assets_api.py、backend/app/services/prompt_assets_service.py、backend/app/services/prompt_runtime_service.py 与 backend/app/config/ai_prompt_eval_rubrics.py（GET /prompt-assets、GET /prompt-assets/{prompt_key}、GET /prompt-assets/{prompt_key}/quality-summary、GET/POST /prompt-assets/{prompt_key}/golden-cases*、POST /prompt-assets/{prompt_key}/releases*、GET/POST /prompt-assets/{prompt_key}/releases/{release_id}/checks*、GET/POST /prompt-assets/{prompt_key}/releases/{release_id}/replay-runs、GET /prompt-assets/{prompt_key}/replay-runs/{run_id}、GET /prompt-assets/{prompt_key}/releases/{release_id}/watch-summary）；该接口属于 /platform/* AI Operations Console，要求 platform.ai_routing.manage，聚合 backend/app/config/ai_prompt_registry.py、backend/app/config/ai_prompts.py 默认 seed、prompt_releases active/draft 状态、prompt_release_checks 门禁状态、分层 prompt_golden_cases、prompt_replay_runs / prompt_replay_case_results、ai_call_logs 质量摘要、跨客户空间 PMFlow OS pmflow_ai_feedback_events 用户反馈和 optimizer_candidates 优化候选，返回 prompt family、业务场景、调用点、风险等级、发布策略、默认模板 hash/预览/正文、模板变量、PMFlow 赞同/不赞同信号、负反馈原因分布和迁移状态；managed_release 可创建草稿、激活和回滚，guarded_release 可创建候选版本但激活必须通过门禁，golden_replay 无 active golden case 或无最新 replay run 时保持阻塞。release replay 支持 contract_smoke 与 llm_compare：LLM replay 必须经 llm_service 和显式 routing_meta 走本地路由层，不硬编码模型，case result 记录 baseline/candidate AI call log、judge score/label/reason；blocking golden case 失败阻塞发布，important/observation 失败降为 warning 进入人工复核。PMFlow OS 负反馈只自动生成待复核 JudgeRun / OptimizerCandidate，不得直接改 active prompt 或自动发布。inline_discovered 只表示已梳理到代码散落 prompt，运行时尚未迁移到 release 读取，不能在 UI 或运营说明中表达为已生效配置。
  • AI readiness / Project Launch 草案门禁接口：参考 backend/app/api/ai_readiness_api/ 与 backend/app/services/ai_readiness_service.py（GET /ai-readiness/project-launch、POST /ai-readiness/project-launch/check）；readiness 由后端从平台运行租户供应商配置、published active structured 槽、Project Launch scene registry、结构化能力证据和租户最近 24h pmflow_launch_draft_v1 调用日志实时推导；单次最近生成失败只进入平台 warning，若 24h 内已有成功且连续失败少于 3 次，用户端仍保持可生成，连续失败达到阈值才进入 recovering；前端 localStorage 只允许作为 VITE_AI_READINESS_LOCAL_OVERRIDE=true 或 test 模式覆盖；平台 smoke check 复用 PMFlowLaunchService.generate_draft_payload_for_readiness_check()，调用真实结构化链但不写 draft/project/task/Project Memory。
  • Space AI Concierge 产品接口：参考 backend/app/api/space_api/（GET /space/ai-concierge/status、POST /space/ai-concierge/ask、GET /space/ai-concierge/sessions、GET /space/ai-concierge/sessions/{session_id}）；该接口是个人空间 AI 管家的前端产品边界，由 core space_api 在 API_ROUTE_PROFILE=lean 下加载，内部复用 AIPMOKernelService.process_ingress 与 AdaptiveRAGService 的 QA session 读模型。前端 SpaceAIConcierge 不直接依赖 optional /rag/* 路由；历史读取失败只影响历史视图，不得阻断当前新会话提问。
  • 手机号登录/自注册/邀请绑定接口：参考 backend/app/api/auth.py（POST /auth/phone/send-code、POST /auth/phone/verify）、backend/app/services/phone_auth_service.py、backend/app/models/phone_verification_code.py 与 backend/alembic/versions/20260428_add_phone_auth_identity.py；手机号身份统一写入 users.phone_e164，同一手机号只允许一个全局账号
  • 平台账号权限平面：参考 backend/app/models/platform_membership.py、backend/app/services/platform_access_service.py 与 backend/alembic/versions/20260428_add_platform_memberships.py；platform_memberships 只给 PMFlow 内部人员发放 platform.* capability，登录响应和 /users/me 会返回 platform_context，客户空间 OWNER/REVIEWER 不自动拥有平台权限

2.2 AI Steward / Training / Mounted Runtime

  • 项目创建接口：参考 backend/app/api/ai_steward_api/routes_capture.py
  • 模型路由配置接口：参考 backend/app/api/model_routing.py；作为 platform AI Operations Console 隐藏 Route Lab 的诊断接口，要求 platform.ai_routing.manage，API_ROUTE_PROFILE=lean 下也必须由核心路由加载；运营导航不暴露函数级编辑入口
  • AI 路由治理聚合服务：参考 backend/app/services/ai_routing_governance_service.py；聚合 integrations(type='llm_engine'|'model_routing'|'ai_team_policy'|'ai_capability_slots'|'ai_function_runtime_profiles')、ai_call_logs 与 backend/.control_plane/pmflow-routing-rules.json，维护 SLOT_REQUIREMENTS、SCENE_DEFAULT_SLOT、槽位能力覆盖、函数运行 profile 摘要、缺能力/缺证据发布阻塞项、scene-slot matrix、active slot observability 和函数级输出 token 观测；函数运行 profile 摘要必须包含 token 预算、temperature、前台等待、provider/job 超时、最大重试和大输入策略，用于 /platform/ai-routing-scenes 右侧“生成运行合同”编辑；观测聚合只输出产品化状态、fallback/degraded 计数、估算成本/延迟来源、输出 token p95、截断/结构化失败计数与脱敏失败样本，只返回中文展示字段、能力标签、probe status、last verified 与 masked key，不返回明文 key、api_env、prompt、raw error 或 raw routing meta
  • AI Routing Governance P5 验收锁定：backend/tests/test_ai_routing_governance_service.py 覆盖 OWNER/REVIEWER 访问边界、OWNER 保存团队策略审计、admin console 敏感字段脱敏、recent failure 不泄露 prompt/key；frontend/src/pages/ai-routing/AIRoutingPages.test.tsx 覆盖 /ai-config/team-ai-policy 负责人视图不出现 provider/model、/platform 与 AI 运营中心入口存在、平台管理视图默认隐藏 function_name。
  • 回复质量闭环接口：参考 backend/app/api/ai_steward_api/routes_reply_iteration.py
  • 训练/微调管线接口：参考 backend/app/api/ai_steward_api/routes_training_pipeline.py
  • Mounted Runtime 控制台接口：参考 backend/app/api/ai_steward_api/routes_mounted_ai.py
  • 老板晨报接口：参考 backend/app/api/ai_steward_api/routes_executive_briefing.py
  • 每日简报 v2 接口：参考 backend/app/api/ai_steward_api/routes_brief_blockers.py
  • 脏数据修复接口：参考 backend/app/api/ai_steward.py（POST /ai-steward/signal-sources/repair-dirty）
  • AI Steward 指挥规划接口已移除：POST /ai-steward/command/dispatch

2.3 RAG / AI PMO / Knowledge Graph

  • RAG 问答主入口：参考 backend/app/api/rag_api/ 与 backend/app/api/rag_ask_contract.py
  • /rag/ask richer response contract、QA session detail 与 state replay：参考 backend/app/api/rag_ask_contract.py、backend/app/services/adaptive_rag_service/mixin_qa_session_list_ops_p1.py
  • Unified Project Operating Context 合同与 builder：参考 backend/app/schemas/project_operating_context.py、backend/app/services/ai_pmo/project_operating_context_builder.py
  • Four-level interaction boundary 合同与冷启动 answer control：参考 backend/app/services/ai_pmo/semantic_context/decision_schema.py、backend/app/services/ai_pmo/workflow_semantic_planner/service.py、backend/tests/test_semantic_decision_service.py、backend/tests/test_workflow_semantic_planner.py；interaction_boundary 负责表达本轮允许做到 status / recommendation / draft / execute 哪一挡以及禁止升级到哪一挡，answer_control 负责把识别出的 workflow 真正过滤成最终可执行 bundle，并把 requested_level / forbidden_levels / effective_level / blocked_workflows 挂进 diagnostics
  • Analysis packet family 合同与 builder：参考 backend/app/schemas/analysis_packets.py、backend/app/services/analysis_packet_builder.py、backend/app/services/analysis_project_snapshot_loader.py；当前 project_fit_analysis / external_impact_analysis / internal_explain_analysis 已显式带 current_subject / candidate_position / rejected_position / reason_chain，共享 richer project snapshot 由 loader 统一补 tasks/signals + description/summary + analysis_object_refs；但 loader 现已 fail-closed，没有真实结构锚点时不再从 task/signal 标题描述推导 object refs。builder 只消费显式 object ref、精确文本绑定和唯一候选这三类非语义结构证据；direct_match 若缺 dependent task ref，就只保留 anchor signal，不再硬挂任务；internal_explain 若缺 target_resolution，也只允许精确文本绑定，不再做 partial-name/overlap 反绑。
  • sparse project-fit 降级规则也在 backend/app/services/analysis_packet_builder.py：当前若 preferred/rejected 结构对象缺失，会直接按“结构对象缺失”降级，不再靠“解释层/当前主链”占位词表、token-overlap 或 partial-name match 决定 fallback 分支。
  • Query 路由网关与显式来源回复合同：参考 backend/app/services/adaptive_rag_service/mixin_query_route_gateway.py
  • query semantics 真源与 business-frame 输出：参考 backend/app/config/ai_prompts.py、backend/app/services/adaptive_rag_service/mixin_core_intent.py、backend/app/services/ai_pmo/semantic_context/business_frame_schema.py；当前 query semantics 上游只保留 query_profile(needs_private_context, needs_freshness, confidence) 与 business_frame 这组运行时真源，不再输出/持久化 query_profile.referenced_objects；subject_focus 只允许作为旧结构化输入在 shared_utils.py 做实体归一化兼容，不得重新进入 route snapshot 或 session 二次拍板
  • ProjectFitBrief 构建与 external handoff 接缝：参考 backend/app/services/adaptive_rag_service/mixin_project_fit_brief.py、backend/app/services/adaptive_rag_service/mixin_answer_retrieval.py；formal signal_source_anchors 与当前项目任务目标 signal_source_objectives 都在这里生成
  • execution_recipe / fit_brief / external_recommendation / analysis_packet / recommended_next_step / handoff_mode 回答接缝：参考 backend/app/services/adaptive_rag_service/mixin_query_route_gateway.py、mixin_answer_mainline.py、mixin_answer_payload.py
  • follow-up session rewrite gate 与“新项目/新业务 scope reset”判定：参考 backend/app/services/adaptive_rag_service/mixin_session_state.py 与 mixin_answer_mainline.py；当前实现会先比对上一轮 QARecord.routing_snapshot 的 project_id / target_resolution / business_frame binding 与当前原始问句解析出的同组结构，再决定是否允许 state_subject/state_entities 重写，避免在 session_state 里靠项目名/正则延续旧主题
  • follow-up anchor / pending clarification 结构化恢复：参考 backend/app/services/adaptive_rag_service/mixin_followup_anchor.py 与 mixin_answer_mainline.py；当前 query_route_selection / followup_anchor_selection 都先经过统一结构化澄清解析，再把选中的 source_policy_hint / query_semantics_overrides / selected_qa_id 透回主链。selected_qa_id 会继续传给 follow-up anchor resolver，避免“第二条/那条”澄清后又回到最近回复词面重猜
  • Internal Query Operation Contract / Target Resolver 的 business-frame-first 入口：参考 backend/app/services/adaptive_rag_service/mixin_target_resolution.py；当前 goal_kind / target_scope / resource_role / project_binding / object_binding / expected_answer_shape 会先被收进 operation contract，再由 target resolution 直接据此判定 project / task / signal / config / feature / doc / user 绑定，不再靠 subject_focus / referenced_objects 这类 coarse 字段补拍对象
  • AdaptiveRAG read-side business-frame-first 归一化入口：参考 backend/app/services/adaptive_rag_service/shared_utils.py；_structured_runtime_entity_type / _structured_project_requested 会把 business_frame + target_resolution + query_plan 合成统一 entity/project binding，并只在该单点兼容旧 subject_focus 实体字段，供 mixin_deterministic_query_core.py、mixin_fast_answer_project_main.py、mixin_fast_answer_semantic_p1.py、mixin_deterministic_query_count.py、mixin_deterministic_query_list.py、mixin_retrieval_router_db.py、mixin_deep_guard_answer.py、mixin_answer_mainline.py、mixin_manifest_feature_p2.py 复用；这些 read-side consumer 不得分散读取 subject_focus / referenced_objects 做 project / task / signal / config / feature / doc / user 的快答、检索和 deep guard 分流
  • unified handoff rollback guard：参考 backend/app/services/adaptive_rag_service/shared_utils.py（env flags）、mixin_query_route_gateway.py、mixin_answer_retrieval.py、mixin_answer_payload.py
  • QA session detail 对 handoff 元数据的持久化/回放：参考 backend/app/services/adaptive_rag_service/mixin_core_intent.py、mixin_qa_session_list_ops_p1.py
  • Feishu QA 文本呈现与 action card 分流：参考 backend/app/services/integrations/feishu_integration_service/mixin_receive_routing.py、mixin_card_action.py、backend/tests/test_feishu_card_action_contract.py；当前实现为“共享 analysis_packet -> 受控改写 -> blocked-entity 校验 -> deterministic fallback”的两段式 presenter，相关 prompt 在 backend/app/config/ai_prompts_catalog/part_01.py。qa_direct 还额外承担中文化 presentation policy：原始 answer 若泄出 Project database / signal_total / 当前盘面 / 建议动作 / External Freshness Guard 等英文或内部术语，或自然化结果直接复述 分析包 / analysis_packet / missing_mapping / next_step / focus_objects / reason_chain 这类内部 packet jargon，会优先压回 packet 文本，并最多只补一行中文来源说明；命中外部信号源 recommendation 呈现时，现在优先吃 rag_result.external_query_plan/query_semantics 里的结构化 interaction_level=recommendation，不再靠 Feishu 本地问句 cue list 决定是否直出推荐正文。对 sparse project-fit fallback，当前 deterministic reply 也会被重写成业务中文，不再原样暴露 packet 缺口字段
  • Query route governance 只读审计接口：参考 backend/app/api/rag_api/routes_route_governance.py 与 backend/app/services/adaptive_rag_service/mixin_query_route_governance.py
  • External Query Service 主链：参考 backend/app/services/external_query_service/（planner.py、gateway.py、registry.py、schemas.py、presenter.py、adapters/）；registry.py 暴露 external-query slot 使用的受控 provider 状态（MCP adapter、bounded live search fallback、verifier、fail-closed source filtering）。planner.py 当前会对“推荐外部信号源”问法优先补 signal_source_objectives / signal_source_anchors 驱动的项目锚点查询，并在 structured plan 返回过泛 query 时仍把这些项目锚点 seed queries 保留在前面；同时 ExternalQueryPlan.interaction_level 会承接统一语义规划层透传下来的 recommendation 层级，供后续 presenter 分支消费。schemas.py 现在还定义了 recommendation 内容层的 SignalSourceRecommendationPacket / SignalSourceRecommendationCandidate，presenter.py 会先生成这层结构化候选，再渲染成业务中文的 top-N candidate + why；recommendation 分支现在优先看 plan.interaction_level 与结构化 recommendation goal/anchors，不再靠 presenter 本地问题 cue list 拍板。当前 presenter 仍保留 overclaim guard：若候选里出现百分比、已确认、无需验证或内部术语，会 fail-closed 回退到 customer-safe fallback candidate，而不是继续把高确定性或架构腔文本吐给用户
  • non-plan 外部推荐 -> signal source 直写链：参考 backend/app/services/ai_pmo/ai_pmo_typed_executor_execute/mixin_execute_signal_source.py、backend/app/services/ai_pmo/ai_pmo_kernel/mixins/ingress/ai_pmo_kernel_mixins_ingress_storage.py、backend/app/services/ai_pmo/ai_pmo_kernel/mixins/followup/ai_pmo_kernel_mixins_followup_project_signal_resume.py、backend/app/services/ai_pmo/ai_pmo_kernel/mixins/followup/ai_pmo_kernel_mixins_followup_verification.py、backend/app/services/ai_pmo/ai_pmo_kernel/ai_pmo_reply_renderer.py；这条链当前会把 recommendation candidate set 经 reply_anchor_qa_context + action_contract 沉到执行结果，再在后续 把推荐的写进系统 / 确认入库 时复用 candidate_set_binding + candidate_refs + project_binding 继续 prepare_write -> confirm_write -> execute_write，非 plan mode 不再默认 requirement draft，且一旦 signal 已 materialize 并写入项目，用户可见结果视为成功，后续 onboarding/manual 状态只通过 post_process_status 暴露
  • requirement-plan / draft confirm 协议优先级与碎片化收敛主链：参考 backend/app/services/ai_pmo/ai_pmo_typed_executor_execute/mixin_execute_query_project.py、backend/app/services/ai_pmo/ai_pmo_kernel_ingress_flow/mixin_entry.py、backend/tests/test_ai_pmo_ingress_mainline.py；当前实现明确把 raw A/B/C/确认/取消/重出/修改 协议放在 semantic backfill 之前，active requirement 的碎片化短回复优先留在 collect / contextual promotion 主链，且 ready / draft_pending_confirm 状态下无锚点单句不再劫持旧草稿确认链
  • 去 lexical fallback 的运行时入口：backend/app/services/adaptive_rag_service/mixin_fast_answer_project_main.py 里的 project progress fast answer bypass 现在只吃结构化 interaction_level / goal_kind / resource_role / expected_answer_shape；backend/app/services/ai_pmo/ai_pmo_typed_executor_execute/mixin_execute_query_project.py 的 casual chat 直答只吃 message_intent=casual_chat，project_lookup shortcut 只吃结构化 message_intent=project_lookup(_question) + query_semantics，不再靠问句词面、项目列表/项目清单 正则或 extract_project_lookup_keyword 提前抢答；backend/app/services/ai_pmo/ai_pmo_kernel/ai_pmo_typed_executor_mixins_parse.py 与 backend/app/services/ai_pmo/ai_pmo_typed_executor_discovery/mixin_analysis.py 的 signal 数量/strict analysis 也只消费结构化 requested_count / analysis_mode / operation_intent_contract，不再从自由文本里解析“3个信号”“先分析后入库”
  • internal config/domain clarify 与 fast answer 真源：backend/app/services/adaptive_rag_service/internal_domain_catalog.py、mixin_target_resolution.py、mixin_followup_anchor.py、mixin_answer_precheck.py、mixin_answer_payload.py、mixin_deep_guard_answer.py。当前 internal domain catalog 已覆盖 project / task / signal / config / feature / doc / user；其中 config 主链只认 business_frame.object_binding（如 config:model_routing、config:mcp_template_center）做直答，task/signal/feature/doc/user 则优先走 domain-first target resolution 与受控 retrieval。若只确认了大域但还没唯一落到子对象，则先从 internal domain catalog 产出 internal_target_selection 澄清协议，pending clarification follow-up 会把选中的 query_semantics_overrides 回填主链后再继续往里查，而不是重复旧答案。
  • 项目化 impact_judgment 快答主链：backend/app/services/adaptive_rag_service/mixin_fast_answer_project_main.py。当 business_frame.goal_kind=impact_judgment 或 expected_answer_shape=impact_chain 时，会把项目影响判断接到 project progress fast answer 主链，并在没有外部实时条目时仍保留结构化 external_impact 结论
  • Feishu signal pipeline 的结构化 intake 主链：参考 backend/app/services/integrations/feishu_signal_pipeline/mixin_process_message_core.py、mixin_process_message_default.py、mixin_item_processing.py、mixin_extraction.py、mixin_item_finalize_routing.py、mixin_core_base.py；当前 default capture 会把 intent_gate 透给后续 signal_intake_hint，extraction 失败时统一回落到低置信 degraded payload（不再使用 _is_simple_signal_source_request / _heuristic_*_fallback / regex 项目命名猜测），core dedupe intent fragment 也只保留标准化片段，不再本地推导 external_integration / project_setup / feature_change
  • Feishu project.create 的结构化预填链：参考 backend/app/services/integrations/feishu_signal_pipeline/mixin_intent_gate_core.py、mixin_context_prefill_a.py、mixin_context_prefill_b.py、mixin_serialization.py、mixin_extraction.py；当前项目字段预填统一依赖 _extract_project_prefill() 产出的 suggested_name / suggested_description / suggested_scope，不再使用 _extract_project_scope / _extract_project_intent_fields / _is_contextual_project_request / heuristic_* 这类词面推断。
  • external route 回答接缝与回归：参考 backend/app/services/adaptive_rag_service/mixin_answer_retrieval.py、mixin_deep_guard_answer.py、backend/tests/test_mcp_external_query_bridge.py、backend/tests/test_adaptive_rag_mainline_contract.py
  • 运行时语义守门与回归：参考 scripts/semantic_lint.py、backend/tests/test_semantic_lint.py、backend/tests/test_external_query_planner.py
  • MCP backend-direct runtime / Microsoft Learn bridge：参考 backend/app/services/mcp_config/runtime.py 与 backend/app/services/mcp_config/service.py
  • 路由记忆样本模型：参考 backend/app/models/query_route_memory.py
  • Internal Query Operation Contract / Target Resolver / DSL / InternalContextPacket / verifier 主链：参考 backend/app/services/adaptive_rag_service/internal_query_context.py、mixin_target_resolution.py、mixin_answer_mainline.py、mixin_deterministic_query_core.py、mixin_answer_payload.py
  • Semantic facts 读模型与抽取服务：参考 backend/app/models/semantic_fact.py、backend/app/models/semantic_fact_extraction_run.py、backend/app/services/semantic_fact_service/
  • Semantic facts 自动入队钩子：参考 backend/app/services/semantic_fact_service/hooks.py
  • Semantic facts 异步事件消费：参考 backend/app/services/project_knowledge_graph_service/mixin_event_queue.py
  • Semantic facts 治理后台接口：参考 backend/app/api/semantic_facts_api/routes.py
  • KG 上下文闭环接口：参考 backend/app/api/knowledge_graph.py
  • 任务包中心接口：参考 backend/app/api/task_briefs.py
  • MCP 模板接入中心接口：参考 backend/app/api/mcp_api/routes.py
  • AI PMO 恢复接口：参考 POST /ai-pmo/work-items/{work_item_id}/resume
  • AI PMO 草稿决策接口：参考 POST /ai-pmo/work-items/{work_item_id}/draft-decision
  • AI PMO 审批接口：参考 POST /ai-pmo/work-items/{work_item_id}/decision
  • AI PMO legacy 工作项列表接口：参考 GET /ai-pmo/work-items；当前只作为 Space legacy adapter 输入，独立收件页已退场；OWNER/REVIEWER 可看租户级 legacy 工作项，其他角色只看本人 owner_user_id 或自己参与项目绑定的工作项
  • AI PMO process-text/work-item 的 plan_mode / plan_status / requirement_plan_context_summary 投影：参考 backend/app/api/ai_pmo_api/helpers_inbox_payload.py 与 backend/app/api/ai_pmo_api/routes_core.py
  • /rag/ask 与 /ai-pmo/process-text 注入 project_operating_context：参考 backend/app/api/rag_ask_contract.py 与 backend/app/api/ai_pmo_api/routes_core.py

2.4 Signal / Project / SSTC

  • Workspace / Membership 兼容层：参考 backend/app/models/tenant.py、backend/app/models/tenant_membership.py、backend/app/models/tenant_invitation.py、backend/app/services/workspace_service.py、backend/app/api/workspaces_api.py 与 frontend/src/api/workspaces.ts；产品语义为个人空间/团队空间，数据库沿用 tenants，手机号邀请按 tenant_id + phone_e164 幂等刷新 pending invitation，验证手机号后绑定或创建账号并加入团队空间；邀请进入团队空间不迁移账号所有权，退出团队空间后回到个人空间。历史账号空间修复参考 backend/alembic/versions/20260428_repair_admin_yangyu_workspace_state.py：补回 tenant_id=1 旧团队空间，并把 admin/yangyu 当前激活空间切到各自个人空间。
  • 需求点落信号源：参考 backend/app/services/signal/signal_source_orchestration/mixin_registry_execute.py
  • 飞书捕获模拟接口：POST /ai-steward/signal/capture-feishu
  • 项目列表/创建/删除接口：参考 backend/app/api/projects_api/；GET /projects/ 与 GET /projects/{project_id} 是 Space、/space/projects 所有项目视图和项目选择器的项目可见性真源，OWNER/REVIEWER 看当前租户全量项目，其他角色只看 owner_id 或 user_projects 绑定项目；POST /projects/ 只负责创建正式项目壳，重复标题返回 409，项目启动台不再提供未配置 AI 时的空项目创建入口；旧 /projects 前端路由只做兼容跳转，不再作为一级产品入口。
  • 项目成员分配接口：参考 backend/app/api/projects_api/ + backend/app/services/project_member/service.py
  • 通用任务拆解接口：参考 POST /tasks/breakdown
  • SSTC 项目级读接口均需先通过项目成员或 OWNER/REVIEWER 可见性校验；非成员不可读取项目总览、链路、信号、宪章、任务、发布、复盘或模型上下文。
  • SSTC 总览接口：参考 GET /projects/{project_id}/sstc/overview
  • SSTC 信号列表接口：参考 GET /projects/{project_id}/signals
  • SSTC 宪章详情接口：参考 GET /projects/{project_id}/charters/{charter_id}
  • SSTC 宪章 AI 预填充接口：参考 POST /projects/{project_id}/charters/{charter_id}/ai-prefill
  • SSTC AI 拆解接口：参考 POST /projects/{project_id}/charters/{charter_id}/tasks/ai-breakdown
  • SSTC 发布验证生成接口：参考 POST /projects/{project_id}/releases/{release_node_id}/verification/generate
  • SSTC 负责人推荐接口：参考 POST /projects/{project_id}/tasks/{task_id}/recommend-assignee
  • SSTC 任务更新接口：参考 PATCH /projects/{project_id}/tasks/{task_id}
  • SSTC 发布创建接口：参考 POST /projects/{project_id}/releases
  • PMFlow OS 真实读路径、C1 Change Review API、C2 backend commit、Execution Handoff、Release Evidence Gate、Release Validation Run、Release Feedback Signal、Iteration Loop draft、Team reviewer decision loop、Execution Capability Graph 与 Team Feed 只读动态流：参考 backend/app/api/pmflow_os_api/、backend/app/services/pmflow_os_projection_service.py、backend/app/services/pmflow_change_review_service.py、backend/app/services/pmflow_ai_feedback_service.py、backend/app/services/team_execution_capability_service.py、backend/app/schemas/pmflow_os.py；只读提供 GET /pmflow-os/projects/{project_id}/truth-state、GET /pmflow-os/projects/{project_id}/execution-summary 与 GET /pmflow-os/projects/{project_id}/execution-capabilities，复用 truth_nodes / tasks / semantic_facts / ai_project_control / dev_sync / users / user_projects / user_workloads / user_skill_bindings；truth-state.aiFeedback 返回当前用户对 AI chat answer / structured extraction / copilot answer 的反馈事件，底表为 pmflow_ai_feedback_events，用于按 scene_key / prompt_key / prompt_release_id / runtime_profile_id 汇总 prompt 质量信号；负反馈会归因到真实 prompt_key 并生成待平台 AI Ops 复核的 JudgeRun / OptimizerCandidate，用户改回赞同时挂起此前候选，不直接改 active prompt；execution-capabilities 只输出执行模式、个人执行准备度、成员执行能力与容量信号、warning，不自动分配任务、不自动请求审查、不写 ChangeSet；D4 后前端 /execution-bridge 将该快照作为主动作 gate 的输入，技术审查责任缺失时阻止 handoff，缺 repo 时只能表达交接草案，不声称真实推送；truth-state.reviewerRouting 是 {status, warningCode, summary, items} 读模型，会从 open/pending ChangeSet、待审 item 风险、跨对象类型、evidence source、项目成员与 OWNER / REVIEWER 角色生成 sourceType / riskLevel / priority / suggestedReviewer / fallbackReviewerRole / targetUrl，并返回 reviewDecision / approvalState / requestedAt / decidedAt / decisionReason 审查决策只读字段；truth-state.feed 是 Team Feed 只读动态流，从 review request / review decision / ChangeSet 状态 / ProgressEvent / release gate 聚合，不写审批、不写 ChangeSet、不写通知；P8 新增 POST /pmflow-os/change-sets/{change_set_id}/review-decisions，支持 request_review / approve / request_changes / reject，复用 PMFlowApproval 写审计，approve 满足 high-risk C2 approval gate 但不自动 commit，request_changes / reject 不写 Project Memory；C1 写 API 包括 thread message、POST /pmflow-os/projects/{project_id}/extractions 的真实 AI extraction 或显式 proposed_items draft、ChangeSet detail、ChangeItem accept/edit/defer、POST /pmflow-os/projects/{project_id}/ai-feedback 记录 AI 回答赞同/不赞同与原因标签；AI extraction 复用 llm_service.generate_structured_object 与 PMFlow prompt/config/routing 层，成功时生成 open ChangeSet + pending_review ChangeItems + thread message evidence，失败时返回 ai_extraction_failed / extraction_evidence_insufficient 且不创建模板假结果；C2 backend 已实现 POST /pmflow-os/change-sets/{change_set_id}/commit，默认 mode=atomic，将 Requirement / Decision / Risk 写入 truth_nodes，将 Task 写入 truth_nodes(node_type='task') + tasks，高风险项强制 approval gate；commit 会持久化 pmflow_change_sets.committed_by 并在 commit result、truth-state 与 Project Memory writebacks 中返回 committedBy/committedById，写入结果页不得再用前端硬编码人员；D.2 已实现 POST /pmflow-os/projects/{project_id}/execution-handoffs，对已确认任务生成/复用 PromptPackage 并创建 ProgressEvent(event_type='handoff_created') 起点；P1 已实现 POST /pmflow-os/projects/{project_id}/execution-handoffs/{prompt_package_id}/consume，记录运行端领取、更新 PromptPackage.package_payload.latest_handoff.handoff_state=consumed 并创建 ProgressEvent(event_type='handoff_consumed', derived_task_status='coding')；Release Growth P1 已在 execution-summary.releaseGate 中从 branch / commit / PR / test_passed / checks_passed / failed / blocked 等 ProgressEvent 推导 ready / blocked / needs_confirmation / empty；Release Validation P1 新增 POST /pmflow-os/projects/{project_id}/release-validation-runs，从当前 releaseGate 固化 ReleaseValidationRun 快照并在 releaseGate.latestValidationRun 返回最新记录，无 evidence 时返回 release_validation_evidence_empty；Release Feedback P1 新增 POST /pmflow-os/projects/{project_id}/release-feedback-ingests，复用 FeedbackIngest / IterationRecommendation 写入真实发布后反馈，并在 execution-summary.releaseSignals 投影真实 feedback / revenueEvents / roiSnapshots / complianceChecks / recommendations、风险计数与 release gate / validation run / business signal types 关系；Iteration Loop P1/P2 支持 recommendation 单条或同组生成 ChangeSet draft；这些步骤均不执行发布命令、外部支付、真实推送、自动 Project Memory commit 或正式 Task 创建。
  • Execution Result Protocol P1：POST /pmflow-os/projects/{project_id}/execution-progress-events 的最小协议在 backend/app/schemas/pmflow_os.py 与 backend/app/services/pmflow_os_projection_service.py，写入 ProgressEvent.payload.protocol_version='execution_result_protocol_v1' 和 execution_result={eventType, source, status, branchName, commitSha, prNumber, testSummary, blockerSummary, repositoryFullName}；前端合同位于 frontend/src/api/pmflowOs.ts，手动回写入口位于 frontend/src/features/pmflow-os/pages/ExecutionBridgePage.tsx。该协议只记录 Codex/IDE/Local Bridge/GitHub agent 已产生的 branch/commit/PR/test/blocker/status，不执行命令、不创建正式任务、不发布；ExecutionSummary.releaseGate 与 Team Feed 继续从 ProgressEvent 只读投影。
  • Project Knowledge Hub / 项目记忆读模型：参考 backend/app/api/pmflow_os_api/、backend/app/services/pmflow_os_projection_service.py、frontend/src/api/pmflowOs.ts、frontend/src/features/pmflow-os/pages/ProjectMemoryPage.tsx、frontend/src/features/pmflow-os/pages/ProjectMemoryCollectionPages.tsx 与 frontend/src/features/pmflow-os/projectMemoryUtils.ts；只读接口为 GET /pmflow-os/projects/{project_id}/project-memory/overview、items、items/{item_id}、assets、context-packs、writebacks。首页只做知识库雷达，二级页承接全部记忆、项目资产库、上下文包、写入与版本记录，writeback 行展示真实写入人 committedBy 与时间；时间展示统一走 formatProjectMemoryTime，列表短格式、抽屉完整格式并标注北京时间；items 支持类型/阶段/来源/状态/搜索筛选，assets 支持资产类型/来源/状态/搜索筛选；单条点击打开右侧抽屉展示来源证据、影响对象和 AI 可执行跳转。资产可自动索引，但进入项目真相层仍必须经 Change Review 或可信规则确认。
  • Adaptive Human Capacity：参考 backend/app/services/adaptive_capacity_service.py、backend/app/models/human_capacity_override.py、backend/alembic/versions/20260427_add_human_capacity_overrides.py、frontend/src/api/pmflowOs.ts、frontend/src/api/space.ts、frontend/src/features/pmflow-os/pages/TeamLayerPage.tsx 与 frontend/src/features/personal-space/PersonalSpacePage.tsx；接口为 GET /pmflow-os/projects/{project_id}/capacity-plan、POST /pmflow-os/projects/{project_id}/capacity-overrides/simulate、POST /pmflow-os/projects/{project_id}/capacity-overrides、GET /pmflow-os/projects/{project_id}/capacity-overrides，并在 execution-capabilities.adaptiveCapacitySummary 返回今日容量摘要。每日计划由当前任务池实时计算，不持久化固定基线；human_capacity_overrides 只存负责人手工调整、原因、过期时间和审计；写接口不自动派任务、不请求审查、不写 ChangeSet；旧 /workloads* 前端路由只兼容跳转到 /team-layer?view=capacity，传统工时明细不再作为用户可见一级入口。
  • Project Launch 真实创建链：参考 backend/app/api/pmflow_launch_api/、backend/app/services/pmflow_launch_service.py、backend/app/services/ai_scene_runtime_policy.py、backend/app/services/ai_function_runtime_profile_service.py、backend/app/schemas/pmflow_launch.py 与模型 backend/app/models/pmflow_launch.py；任务化生成接口为 POST /pmflow-launch/draft-jobs、GET /pmflow-launch/draft-jobs/{job_id}、POST /pmflow-launch/draft-jobs/{job_id}/cancel 与 POST /pmflow-launch/drafts/{draft_id}/revise，任务状态落 pmflow_launch_draft_jobs(job_id/revision_id/status/result_draft_id/changed_fields)，补充一句或重新生成会 supersede 同用户运行中的旧 job；兼容同步接口 POST /pmflow-launch/drafts 仍只写 pmflow_launch_drafts，POST /pmflow-launch/drafts/{draft_id}/confirm 在同一事务内创建 projects / user_projects / pmflow_threads / pmflow_thread_messages / truth_nodes / tasks / semantic_facts seed / operation_logs；生成入口在调用 LLM 前会拦截低信息输入并返回 input_needs_more_info 422，避免纯问候或无产品线索输入生成空草案；draft prompt 通过 PROMPT_PMFLOW_LAUNCH_DRAFT 和 PromptRuntimeService 优先读取平台 Prompt 运营中心 active release，生成预算、修复预算、temperature、响应模式、前台等待、provider/job 超时、最大重试和大输入策略通过 Function Runtime Profile active 版本读取；provider_timeout_seconds 进入 provider HTTP client，job_timeout_seconds 包住结构化生成任务，max_retries 覆盖 transient retry budget，large_input_policy=preprocess_then_generate 在 large 桶压缩材料后再渲染 prompt，draft job response 返回 runtime_policy 供前端按 foreground_wait_seconds 调整等待状态；默认按可变现 MVP 闭环生成 7-10 条 requirements、10-16 条 tasks、4-7 条 risks、3-6 条 decisions，数量或商业闭环不足时写入 warnings；调用 LLM 前必须先按输入规模写入 Project Launch 场景 timeout 默认策略，再由已发布 Function Runtime Profile 覆盖可运营字段，超时显式落 structured_timeout/draft_job_timeout，禁止冒充成功。
  • Personal Space 暂存想法闭环：参考 backend/app/api/space_api/、backend/app/services/space_saved_idea_service.py、backend/app/schemas/space.py、backend/app/models/saved_idea.py、backend/alembic/versions/20260428_add_saved_ideas.py 与 backend/alembic/versions/20260428_add_saved_idea_enrichment.py；结构化提示词在 backend/app/config/ai_prompts_catalog/part_scenes_06.py 的 PROMPT_SAVED_IDEA_ENRICHMENT，运行时通过 PromptRuntimeService 优先读取平台 Prompt 运营中心 active release 并向 ai_call_logs 写入 prompt_key / prompt_release_id / prompt_source 归因。接口为 GET/POST/PATCH /space/saved-ideas、POST /space/saved-ideas/{idea_id}/archive、POST /space/saved-ideas/{idea_id}/promote。saved_ideas 是 pre-project idea seed，只保存未成型想法、原始输入、来源、准备度、缺失问题、结构化 enrichment 元数据和 draft 关联；创建/编辑原始输入时尝试 space_saved_idea_enrichment_v1，问候/测试/无实质想法输入必须判为 needs_more_info 和 0 准备度，AI 失败显式落 ai_failed/system_baseline；promote 只生成 Project Launch 草案并回到 human review，确认前不创建项目、不写 Project Memory、不写 ChangeSet。
  • Legacy project create 410 路由：参考 backend/app/api/legacy_ai_steward_api.py；该模块在 CORE_ROUTE_MODULES 中始终挂载，只保留 POST /ai-steward/project-from-text 的 410 包络响应，避免 lean profile 下未知外部调用落成 404。
  • PMFlow Change Review 模型与 migration：参考 backend/app/models/pmflow_change_review.py 与 backend/alembic/versions/20260426_add_pmflow_change_review_tables.py；只包含 pmflow_change_sets / pmflow_change_items / pmflow_approvals / pmflow_evidence_links，本阶段不得新增或依赖 /commit

3. 前端参考

  • PMFlow UI 契约真源：先读 docs/PMFLOW_UI_CONTRACT.md，再修改 project-launch、personal-space、pmflow-os 相关页面；该文档锁定 Logo、色彩、移动端底部导航、状态标签、AI 操作/用户动作/待确认视觉语法和核心功能 canonical 契约
  • PMFlow 大模块并行公共壳：参考 docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md 的 4.4.1-4.4.3 与 frontend/src/router/index.tsx、frontend/src/main.tsx、frontend/src/features/pmflow-os/components/MobileBottomNav.tsx、frontend/src/features/pmflow-os/components/PMFlowOsFrame.tsx；/space 归 Space lane，/pmflow-os / /command-center / /change-review / /execution-bridge / /release-growth 归 Main Flow lane，/me 归 Account Settings lane，/settings 当前仅为 reserved route，新增或改动必须由 Shell / Integration owner 串行处理
  • PMFlow P8 Review Decision Loop 已集成收口：参考 docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md 第 7 节和 big-module-integration-p8 台账；Main Flow 以 truth-state.reviewerRouting 和 POST /pmflow-os/change-sets/{change_set_id}/review-decisions 提供 reviewer decision / approval audit 合同，Space 只读消费为 /space 的 review_attention 下一步队列，Account 只提供 review decision / high-risk approval 页面内提醒偏好；P8 不新增战略页面、不改 router/nav、不接真实通知中心，继续使用既有 /change-review / /team-layer / /space / /me 表面
  • PMFlow OS 产品合同真源：先读 docs/architecture/PMFLOW_OS_PRODUCT_CONTRACT.md，再实现 pmflow-os 真实后端接入；该文档锁定 ProjectTruthState / Thread / ChangeSet / ChangeItem / Evidence / Approval / Project Memory / ExecutionContext 与 truth_nodes / tasks / semantic_facts / ai_project_control / dev_sync 的复用边界和后续 API 草案
  • 新增前端 API 调用：参考 frontend/src/api/sstc.ts；Space 工作面聚合参考 frontend/src/api/space.ts，消费项目摘要、PMFlow OS truth-state / execution-summary / execution-capabilities 与 GET /space/saved-ideas。Space 不写 Project Memory、ChangeSet 状态、PMFlowApproval、ProgressEvent、ReleaseValidationRun、FeedbackIngest、RevenueEvent、ROISnapshot 或 ComplianceCheckRun；唯一 Space 写入是 saved_ideas pre-project seed，createSavedIdea 保存未成型想法，archiveSavedIdea 归档，promoteSavedIdea 只生成 Project Launch draft 并通过 project_launch_draft pending intent 进入 /project-launch human review，不自动确认或创建项目。Space 的 nextActionQueue 在 Space 本地读模型内把 AI extraction 生成的 ChangeSet 待确认、review attention、execution failed/blocked/delivery failed、发布阻塞、handoff consumed 后缺少后续 progress、发布后 feedback/revenue/ROI/compliance 信号和下一轮 draft 统一排序为“我的下一步”，所有 item 只跳 /change-review、/execution-bridge 或 /release-growth；Space 的 executionReadiness 只读展示工具连接、待确认、待审查、待验收和阻塞原因；PMFlow OS 真实接入参考 frontend/src/api/pmflowOs.ts 的 getPMFlowTruthState(projectId)、getPMFlowExecutionSummary(projectId)、getPMFlowExecutionCapabilities(projectId)、createPMFlowExecutionHandoff、consumePMFlowExecutionHandoff、createPMFlowExecutionProgressEvent、createPMFlowReleaseValidationRun、createPMFlowReleaseFeedbackIngest、createPMFlowIterationRecommendationChangeSetDraft、createPMFlowIterationRecommendationGroupChangeSetDraft、createPMFlowReviewDecision、createPMFlowThreadMessage、createPMFlowExtraction、getPMFlowChangeSet、acceptPMFlowChangeItem、editPMFlowChangeItem、deferPMFlowChangeItem、commitPMFlowChangeSet；PMFlowExecutionSummary.releaseGate 是 ReleaseGrowth 真实发布门禁前端合同，execution-summary.releaseSignals 是 Release/Growth 发布后信号与下一轮 ChangeSet draft 状态前端合同；Project Launch 创建链参考 frontend/src/api/pmflowLaunch.ts。
  • Legacy AI Steward route：/ai-steward 不再作为产品页；参考 frontend/src/router/index.tsx 的 getLegacyAIStewardRedirectPath，tab=create 迁到 /project-launch，tab=engine 迁到 /ai-config，tab=feedback-center 有项目参数时迁到 /release-growth?projectId=<id>、否则迁到 /space，其它 legacy tab 迁到 /space；frontend/src/pages/ai-steward/ 仅保留迁移占位和已断链的历史 tab 壳，不作为新功能入口。
  • AI Steward 问答共享展示与旧浮窗兼容组件：参考 frontend/src/components/ai-steward/FloatingQAChat.tsx、frontend/src/components/ai-steward/QAConversationStatusBar.tsx、frontend/src/components/ai-steward/QAResponseMetaCard.tsx；FloatingQAChat 当前不再由全局 Layout 挂载，空间入口由 frontend/src/features/personal-space/components/SpaceAIConcierge.tsx 承接。
  • AI Steward QA contract 前端类型（含 analysis_packet）：参考 frontend/src/api/aiSteward.ts
  • AI Steward handoff 元卡片回归：参考 frontend/src/components/ai-steward/FloatingQAChat.test.tsx、frontend/src/components/ai-steward/QAResponseMetaCard.test.tsx
  • AI Steward / QA session 前端 contract：参考 frontend/src/api/aiSteward.ts
  • PMFlow OS 前端 MVP 产品域：参考 frontend/src/features/pmflow-os/
  • AI readiness / 空间级 AI 能力门禁：参考 frontend/src/features/ai-readiness/、frontend/src/api/aiReadiness.ts、frontend/src/pages/ai-config/components/AISetupWizard.tsx、frontend/src/features/personal-space/components/SpaceChrome.tsx、frontend/src/features/pmflow-os/components/PMFlowOsFrame.tsx 与 frontend/src/features/project-launch/components/LaunchCanvases.tsx；useAIReadiness() 是 Space 顶部状态、AI 可用状态页、项目级 AI 副驾状态和 Project Launch 未就绪分流的共享前端合同，默认读取后端 GET /ai-readiness/project-launch，本机状态只允许在 test 或 VITE_AI_READINESS_LOCAL_OVERRIDE=true 时覆盖。该合同必须输出双层表达：用户端默认消费 customerState / title / summary / blockers / customerActions / workspaceOwnerActions，只表达业务影响、可继续动作和保护规则；平台人员进入用户端也先看客户视图，只有显式 platformDiagnostic 卡或 /platform/* 才展示 causeCode / causeOwner / rawStatus / affectedScenes / platformActions。普通成员不得看到供应商、路由、连接测试、模型槽位、trace 或函数名；空间负责人只看到空间 AI 状态、团队策略和工具连接入口；平台 AI Ops 在 /platform/* 默认看到具体诊断和 CTA，并可在运行总览触发 POST /ai-readiness/project-launch/check 草案 smoke。
  • 个人空间首页 / 空间层入口前端产品域：参考 frontend/src/features/personal-space/、frontend/src/api/space.ts 与薄入口 frontend/src/pages/PersonalSpacePage.tsx；登录后路由入口为 /space，未登录由 frontend/src/auth/RouteBoundary.tsx 跳转 /login?redirect=/space；首屏以 nextActionQueue 展示“我的下一步”，并保留执行准备度、继续推进、待我确认、发布关注、发布后反馈关注、下一轮迭代草稿关注、执行中 / AI 正在推进、暂存想法、草案箱、缺项目归属补全与最近项目明细；红框三块在首页只作为工作雷达预览，暂存想法、草案箱、最近项目均最多露出少量高优先级条目，完整处理分别进入 /space/ideas、/space/drafts 与 /space/projects?view=recent。frontend/src/features/personal-space/SpaceCollectionPages.tsx 承载二级页：/space/ideas 支持暂存想法筛选、搜索、补充、归档与转 Project Launch 草案，/space/drafts 支持待确认草案筛选、搜索与回主流程确认；这些页面仍使用空间壳，不直接写项目真相层。Space 同时展示 AI readiness 客户视图卡片，管理员可从侧边栏或顶部状态进入 /ai-config?tab=setup。空间级 AI 管家在 frontend/src/features/personal-space/components/SpaceAIConcierge.tsx，入口只挂 /space，向现有 /rag/ask 注入个人空间上下文包并复用 QA session 历史能力；它只能围绕个人空间、跨项目下一步、待确认、执行中、草案、暂存想法和 AI 能力状态工作，真实写操作必须回主流程确认或跳转，不得声称已执行。全局 Layout 不再挂载旧 FloatingQAChat 悬浮球，普通后台页不显示无上下文聊天球，项目页继续使用项目级 AI 副驾。Space 左侧导航只承载稳定空间目的地，当前保留“空间首页”“暂存想法”“草案箱”“所有项目”和管理员“AI 使用设置”。点击项目主动作进入 /pmflow-os?projectId=<id>，待确认项进入 /change-review?projectId=<id>&changeSetId=<id>，review attention 待审项进入 /change-review?projectId=<id>&changeSetId=<id>，reviewer 缺失 warning 进入已有 /team-layer?projectId=<id>，执行中与执行准备度项进入 /execution-bridge?projectId=<id>，发布关注和发布后反馈关注项进入 /release-growth?projectId=<id>；执行失败和回写失败项进入 /execution-bridge?projectId=<id>；Space 聚合项目摘要、PMFlow OS truth-state.reviewerRouting / truth-state.releases / execution-summary.releaseGate / execution-summary.releaseSignals / execution-summary.recentProgressEvents / execution-summary.recentDeliveries / execution-capabilities 和真实 GET /space/saved-ideas，并兼容读取旧 AI PMO waiting_manual / draft_pending_confirm 工作项；missing_project_scope 仅在 Space 选择项目后复用 POST /ai-pmo/work-items/{id}/decision，不新增旁路接口，不直接写项目真相层。缺数据时显示明确空态或 warning，不虚构 reviewer、审查意见、待审 ChangeSet、执行能力、工具连接、验证、反馈、收入、ROI、合规、iteration recommendation 或 ChangeSet draft；暂存想法是唯一允许 Space 写入的 pre-project seed，保存原始输入、来源、状态、准备度和 draft 关联，生成草案只进入 Project Launch human review；除此之外不直接写 Project Memory、ChangeSet 状态、PMFlowApproval、execution event、ReleaseValidationRun、FeedbackIngest、RevenueEvent 或 ComplianceCheckRun；空间层共享左侧栏、顶部条与空间用量组件在 frontend/src/features/personal-space/components/SpaceChrome.tsx，/project-launch 桌面首次新建壳也复用该空间 Chrome
  • 新项目启动台 / 首次进入页前端产品域：参考 frontend/src/features/project-launch/ 与薄入口 frontend/src/pages/ProjectLaunchPage.tsx；真实模式登录后路由入口为 /project-launch，默认通过 frontend/src/api/pmflowLaunch.ts 调用后端 taskized draft job/confirm API；AI 草案创建链路是 POST /pmflow-launch/draft-jobs -> GET /pmflow-launch/draft-jobs/{job_id} -> POST /pmflow-launch/drafts/{draft_id}/confirm，补充一句走 POST /pmflow-launch/drafts/{draft_id}/revise 或创建新的 merge_supplement job，旧 POST /ai-steward/project-from-text 只返回 410 迁移错误；只有显式 ?demo=1 或 ?dataSource=demo 才允许匿名并启用 mockData.ts 本地演示状态机，真实模式的操作流、生成过程、审查建议、附件引用和计数从当前输入、job 状态与后端返回草案派生，不再使用周报 demo 文案兜底；真实模式下 AI 未就绪时先渲染 AISetupRequiredPanel，按权限展示记录想法、查看空间状态或平台 AI 能力处理 CTA，不提供空项目创建入口，避免在缺少结构化上下文时提前创建项目壳。401/无 token 通过 frontend/src/lib/apiError.ts 归一为 auth_required/session_expired，通过 frontend/src/lib/pendingIntent.ts 保留输入；input_needs_more_info 422 归一为 input_invalid 并停在补充输入失败态，用户可见失败态不得展示 Request failed with status code 401 或把 401 归为网络异常
  • 前端身份边界与产品化错误：参考 frontend/src/auth/RouteBoundary.tsx、frontend/src/lib/rbac.ts、frontend/src/lib/apiError.ts、frontend/src/lib/pendingIntent.ts；/space、真实 /project-launch、/me、主链 standalone、空间管理入口与平台运营入口均在前端边界收口。空间管理入口使用 workspace role，/platform/* 和平台治理入口使用 platform_context.capabilities，后端 JWT/RBAC 仍是最终校验；pending intent 只能恢复 project launch 输入或承接已经生成好的 Project Launch draft，不允许登录后自动重放真实写请求
  • PMFlow OS 共享 truth store 与主链状态动作：参考 frontend/src/features/pmflow-os/store.tsx；当前支持 ?projectId=<id> 走 React Query 读取真实 truth-state、execution-summary 与 execution-capabilities，真实模式下 sendMessage 会先写 thread message，再调用 createPMFlowExtraction 触发后端真实 AI extraction，成功后 refetch 出 open ChangeSet / pending_review ChangeItems；显式 proposed_items extraction 仍保留给受控 draft 场景；ChangeItem accept/edit/defer、ChangeSet commit、review decision、AI feedback、Execution Handoff create/consume、execution progress writeback、release validation run create、release feedback ingest、单条 iteration recommendation -> ChangeSet draft 与同组 iteration recommendation 批量 -> ChangeSet draft 均调后端并 refetch，不本地 promote 入 Project Memory、不伪造 approval、execution event、发布验证记录、发布后信号或下一轮 draft；D4 后 createExecutionHandoff 除正式 Task gate 外会读取 execution-capabilities，在技术审查责任缺失时阻止 handoff，避免把 agent 执行绕过 reviewer gate；D4.5 后 /execution-bridge 的主按钮由页面级 Run 状态模型消费 store 数据统一推导，不再散落在上下文包、回写视图和 AI 副驾卡片里；D4.6 后 /execution-bridge 额外消费 truth-state.requirements/tasks 与 execution-summary.activeDevTasks 形成前端只读开发范围模型，按 Requirement 聚合任务、展示未归属任务并支持切换选中 Run；AI feedback 通过 createPMFlowAIFeedback 写入 pmflow_ai_feedback_events 并在 truth-state.aiFeedback 恢复当前用户选择；AI extraction 失败在 CommandCenter / StructuredExtraction 显示“结构化失败/待补充”，不展示模板假候选；?demo=1 才启用本地 mock 演示状态机和本地动作；项目内 AI 结构化闭环状态机为 command_idle / ai_extracting / extraction_ready / review_open / writeback_success
  • Account Settings / /me 前端产品域与 P1-P8 偏好合同：参考 frontend/src/features/account-settings/AccountSettingsPanel.tsx、frontend/src/features/pmflow-os/pages/AccountPage.tsx、frontend/src/api/accountSettings.ts、backend/app/api/account_settings_api/、backend/app/schemas/account_settings.py 与 backend/app/services/account_settings_service.py；当前覆盖个人资料、默认语言、AI 回答深度、证据展示偏好、待确认、执行回写、发布门禁和失败提醒通知偏好，移动端使用分组列表与 bottom sheet，账户退出仍复用 AccountControls.tsx，不改 OAuth/JWT/auth core；P1 后端合同提供 GET /account-settings/me 与 PUT /account-settings/me，已由 backend/app/api/router.py 挂入核心路由组，按当前 tenant_id + user_id 保存账号偏好，前端有 token 时优先账号同步，后端不可用时明确回落 仅本机暂存 / 保存失败；P2 在 frontend/src/api/accountSettings.ts 提供 shouldShowAccountNotification 与 getAccountNotificationConsumption，把通知偏好映射为页面内提醒消费模型；P3 新增 getReleaseGateNotificationPreference(settings, event) 供 Release/Growth 后续消费：release_gate_* 与 release_validation_* 使用 releaseGate 偏好，failed_event 使用 failureAlert 偏好；P5/P6 的 getPostReleaseNotificationPreference(settings, event) 供发布后反馈与下一轮待确认消费：feedback_received / revenue_signal / compliance_blocked 使用 releaseGate 偏好，iteration_recommendation / next_change_review 使用 pendingConfirmation 偏好并落到 change_review surface；P7 将每类通知偏好扩展为 reminderIntensity=silent|normal|prominent 与 evidenceDisplay=compact|expanded，并新增 getAccountReminderConsumption(settings, event) 覆盖 change_review_high_risk / iteration_draft_ready / release_blocked / execution_stalled，稳定返回 notificationTransport=in_app_only / evidencePolicy=preserve_business_evidence / auditPolicy=preserve_audit_state；P8 新增 getReviewDecisionNotificationPreference(settings, event) 覆盖 review_requested / review_approved / review_changes_requested / review_rejected / high_risk_approval_required，统一使用 pendingConfirmation 偏好和 change_review surface，返回 reviewerRoutingPolicy=preserve_reviewer_routing / approvalPolicy=preserve_approval_state，偏好关闭只静默页面内提醒，不隐藏 reviewerRouting、approval、evidence 或 audit state；ReleaseGrowthPage 当前消费 releaseGate 与 failureAlert 两个偏好，只静默强调型提醒，不隐藏 release evidence、阻塞原因、审计状态、validation run、releaseSignals 或下一轮 ChangeSet draft；这些 helper 只控制本地 UI 提醒消费合同，不代表真实邮件、桌面推送或系统通知中心已接入
  • PMFlow OS 产品页入口：参考 frontend/src/features/pmflow-os/pages/CommandCenterPage.tsx、StructuredExtractionPage.tsx、ChangeReviewPage.tsx、MemoryWritebackResultPage.tsx、WorkGraphPage.tsx、ExecutionBridgePage.tsx、ReleaseGrowthPage.tsx、TeamLayerPage.tsx、ProjectMemoryPage.tsx、AccountPage.tsx；StructuredExtractionPage.tsx 根据 origin=change_review / returnTo=change_review / changeSetId / itemId 区分指挥台读取检查、待确认证据检查和已写入快照，从待确认进入时主动作必须返回 /change-review 原轮次，不把用户强制带回指挥台；ChangeReviewPage.tsx 真实模式可对当前变更集请求审查、通过、要求修改或拒绝，展示审查状态、建议审查人、审查意见和高风险审批门禁，但不自动 commit，且在确认写入 Project Memory 前允许 pending_review / accepted / edited / deferred ChangeItem 继续 accept/edit/defer；ExecutionBridgePage.tsx 真实模式读取 execution-summary 与 execution-capabilities，D4.6 后页面形态为开发范围总览 + 需求执行队列 + 选中 Run 工作台：首屏展示本轮已确认需求、正式任务、执行中、待生成包、待测试/审查与阻塞数量，左侧按 Requirement 聚合任务、列出未归属任务并允许切换选中任务；选中任务详情继续展示 Run Header、已确认需求 / 上下文包 / 开发 / 测试 / 审查合并 / 回写 阶段 rail、当前阶段工作台、执行源包、AI 阶段决策面板和底部证据流水；主动作由单点 Run 状态模型推导，必须受正式 Task、待确认范围、repo/prompt package 与 reviewer gate 约束，缺 repo 只能生成交接草案，技术审查责任缺失时不能发起 handoff；手动回写在 drawer 内记录已发生的 branch/commit/PR/test/blocker/status，不执行命令；执行结果只汇总运行端、PR/commit、测试、阻塞和下一步，不把测试通过自动视为验收完成；TeamLayerPage.tsx 真实模式读取 state.reviewerRouting、state.feed 与 execution-capabilities，以 团队动态 / 决策台 / 角色收件箱 / 智能体工位 / AI 副驾 展示团队协作态势、待审变更责任路由、执行能力与容量信号、个人执行准备度和工具准备度，只给责任建议、阻塞解释与跳转，不自动分派、不自动审查、不写 ChangeSet 或 Project Memory；决策台与待审路由卡片不得预留独立空白操作列，正文应使用完整卡片宽度，1-2 条路由按双列或单列密度展示；ReleaseGrowthPage.tsx 真实模式展示 execution-summary.releaseGate、execution evidence、阻塞原因、下一步动作、latestValidationRun 和 releaseSignals，缺证据或缺发布后信号时显示 empty/warning，不展示 mock 发布结果；页面可调用真实 API 创建 release validation run、摄取 release feedback，并展示真实 feedback、revenue、ROI、compliance 与 recommendation 风险态，从真实 recommendation 单条或同组批量生成下一轮待确认 ChangeSet draft；生成后仍进入 Change Review accept/edit/defer，不自动 commit、不写 Project Memory、不执行部署命令、不接外部支付、不接真实合规平台；所有真实证据和审计状态仍可见，静态高保真发布/增长数据仅保留在显式 demo 模式
  • 团队层只读动态与协作态势：TeamLayerPage.tsx 直接消费 ProjectTruthState.feed 聚合的 review request、review decision、变更集状态、execution progress 与 release gate 事件，并结合 reviewerRouting、execution-capabilities 和容量计划生成首屏摘要；前端只做空态、摘要、中文化展示和跳转，不写审批、不写 ChangeSet、不写通知，也不在真实模式 fallback 到 mock 动态。
  • PMFlow OS 行为组件：参考 frontend/src/features/pmflow-os/components/ProjectStructuredLoop.tsx、ProjectStageRail.tsx、ThreadComposer.tsx、ExtractionRail.tsx、ChangeGroupPanel.tsx、ObjectGraphSection.tsx、ContextPacketPanel.tsx、ExecutionTimeline.tsx、ReleaseGatePanel.tsx、TeamFeedPanel.tsx、ChangeReviewGroup.tsx、WorkbenchPanel.tsx、ExecutionBridgeCards.tsx、PMFlowOsFrame.tsx、AccountControls.tsx、FeedbackPrimitives.tsx、MobileBottomNav.tsx；其中 ProjectStructuredLoop.tsx 承接 StatusLabel / EvidenceSnippet / ObjectChangeCard / ProjectConversationPanel / StructuredExtractionPanel / ProjectAICopilotPanel，PMFlowOsFrame.tsx 承接项目内面包屑和项目切换器，AccountControls.tsx 承接桌面头像菜单、退出登录确认与移动端 bottom sheet，FeedbackPrimitives.tsx 承接 PageBanner / InlineNotice / HumanDecisionBar / ConfirmDialog / MobileBottomSheet，MobileBottomNav.tsx 承接正式应用壳移动端固定底部导航
  • PMFlow OS 原型状态回归测试：参考 frontend/src/features/pmflow-os/store.test.ts；真实 API 动作回归参考 frontend/src/features/pmflow-os/store.api.test.tsx
  • Space 工作面回归测试：参考 frontend/src/features/personal-space/PersonalSpacePage.test.tsx，覆盖空态、导航只读约束、执行准备度、发布/反馈/迭代草案队列，以及 reviewerRouting -> review_attention 的 next action 聚合排序与 /change-review、/team-layer 跳转合同。
  • Project Launch 真实/演示分支回归测试：参考 frontend/src/features/project-launch/useProjectLaunchState.test.ts
  • Account Settings 前端合同回归测试：参考 frontend/src/features/account-settings/accountSettings.test.ts，覆盖默认偏好、账号同步 fallback、通知偏好消费模型、提醒强度/证据展示合同、Release/Growth 通知消费合同、review decision / reviewer request / high-risk approval 偏好合同、失败事件映射和缺字段 fallback。
  • 网页问答显式锚点与 Space AI 历史 URL 构造：参考 frontend/src/components/ai-steward/qaPageAnchor.ts；新生成的 QA 锚点进入 /space?view=ai-history，函数仍能解析 legacy /ai-steward URL 以兼容历史链接
  • 登录页/营销页的共享视觉基线：参考 frontend/src/components/marketing/MarketingFrame.tsx 与 frontend/src/components/marketing/MarketingVisuals.tsx
  • 公开登录页入口：参考 frontend/src/pages/login/LoginPage.tsx、frontend/src/components/login/LoginExperience.tsx、frontend/src/components/login/LoginForm.tsx、frontend/src/components/login/LoginWorkflowVisual.tsx、frontend/src/components/login/loginScene.ts、frontend/src/components/login/loginMath.ts 与 frontend/src/router/index.tsx；默认手机号验证码登录/自注册，用户名密码仅作为兼容入口
  • 登录页分级验证：参考 frontend/package.json 中的 verify:login-fast / verify:login-responsive / verify:login-full、capture:login:matrix、frontend/scripts/login-live-check.mjs 与 frontend/src/pages/login/LoginPage.test.tsx
  • 顶层路由懒加载与统一 fallback：参考 frontend/src/router/index.tsx 与 frontend/src/components/layout/LazyBoundary.tsx
  • 顶层前端 Provider 入口：参考 frontend/src/main.tsx（PMFlowOsProvider + RouterProvider）
  • AI Steward legacy redirect 入口：参考 frontend/src/router/index.tsx 与 frontend/src/pages/ai-steward/AIStewardPage.tsx；不再新增 tab 级业务入口
  • AI 使用设置 section 级懒加载入口：参考 frontend/src/pages/ai-config/AIConfigPage.tsx 与 frontend/src/components/layout/Layout.tsx；/ai-config 技术路由保留，但它是空间级 AI 使用设置入口，必须渲染空间配置壳 SpaceSidebar(activeLabel="AI 使用设置") + SpaceTopBar，不得显示项目工作台侧栏；首页按状态 / 连接 / 知识 / 策略组织客户空间 AI 使用能力，平台供应商、全局路由、route/context 与 semantic facts 不在普通客户空间暴露。
  • Space 项目集合与旧项目路由兼容：所有项目视图参考 frontend/src/pages/projects/ProjectsPage.tsx，新入口为 /space/projects 并使用空间壳 SpaceSidebar(activeLabel="所有项目") + SpaceTopBar；从空间首页最近项目进入时可带 /space/projects?view=recent，页面内支持“全部 / 最近 / 待处理 / AI 进行中 / 已归档”筛选，承接首页最近项目二级查看，不单独新增最近项目页；旧 /projects 只在 frontend/src/router/index.tsx 中重定向到 /space/projects，旧 /projects/:id/board 重定向到 /pmflow-os?projectId=:id，旧 /projects/:id/charter/:charterId 重定向到 /project-memory?projectId=:id；frontend/src/pages/project-board/ 仅保留为待物理删除的 legacy 代码，不再作为新产品实现参考。
  • 空间成员与权限入口：参考 frontend/src/pages/users/UsersPage.tsx、frontend/src/pages/user-profile/UserProfilePage.tsx 与 frontend/src/components/users/UserFormDialog.tsx；新入口为 /space/settings/members 和 /space/settings/members/:id，旧 /users* 路由只做兼容跳转；成员新增的用户可见动作是“按手机号邀请成员”，不是后台直接创建密码账号。
  • 图表二级 chunk 入口：参考 frontend/src/pages/user-skills/components/UserSkillsRadarPanel.tsx 与 frontend/src/pages/workload-detail/components/WorkloadTrendChart.tsx
  • Vite chunk 分组与 watch 忽略策略：参考 frontend/vite.config.ts
  • Scheduler Center / Mounted AI Console：参考 frontend/src/pages/scheduler-center/
  • SSTC 工作流组件：参考 frontend/src/components/sstc/
  • Platform AI Operations Console 专属壳与首页：参考 frontend/src/pages/platform/PlatformChrome.tsx 与 frontend/src/pages/platform/PlatformConsolePage.tsx，入口为 /platform；/platform/* 必须使用平台专属 PlatformSidebar + PlatformTopBar，不得复用旧项目工作台侧栏/顶部条，侧栏按“运行总览 / AI 运行层 / 工具与外部能力层 / 上下文与语义层 / 质量与事件层”组织；旧 /ai-config/* 平台诊断路径只做兼容跳转。
  • Model Routing / Route Lab 页面：参考 frontend/src/pages/model-routing-config/ 与 backend/app/services/model/model_routing/service.py，隐藏入口为 /platform/route-lab；旧 /platform/model-routing-config、/ai-config/model-routing-config 和裸 /model-routing-config 仅兼容跳转。当前 UI 只读展示函数级规则命中、最近执行与历史 override 痕迹，不提供保存入口；服务端写接口仍只接受 low/high 槽位别名，并阻止保护 high 场景函数降级到 low，后续若重新开放编辑必须补修改原因、TTL、dry-run、审计和自动过期。
  • AI 路由与供应商控制台页面：参考 frontend/src/pages/ai-routing/、frontend/src/api/aiRouting.ts、backend/app/services/ai_routing_governance_service.py 与 backend/app/services/ai_routing_scene_contracts.py；TeamAIPolicyPage.tsx 是客户空间负责人策略视图，平台 AI Ops 运行总览合并进 /platform，旧 /platform/ai-routing-console 仅兼容跳转；AI 运行层共享实现为 AIRoutingOperationsPages.tsx，并拆分为 /platform/ai-routing-providers 供应商与凭据、/platform/ai-routing-slots 能力槽位、/platform/ai-routing-scenes 业务场景路由、/platform/ai-routing-costs 成本/配额/缓存、/platform/ai-routing-failures 失败诊断；供应商页可执行 capability probe 并展示 capability source、last verified、probe status 与阻塞原因；能力槽位页负责从已启用供应商连接中选择 primary runtime 与 fallback chain，保存到 integrations(type='ai_capability_slots') 的 draft 后必须经过 validate/publish 才会变成 runtime active slots，结构化/工具/长上下文槽位发布必须区分缺能力与缺证据，槽位详情弹层必须展示该 slot 影响的业务场景和 24h/7d 运行观测；主矩阵展示 7d 失败率与 fallback 命中摘要，无样本时显示“暂无运行样本”；场景路由页消费 scene_slot_matrix[].scene_contract / scene_health / release_gate / function_runtime_profiles，定位为 Scene Contract & Impact Console：展示业务目标、输入对象、输出合同、成功标准、失败/确认/证据策略、active/draft runtime、能力缺口、发布影响、健康度、发布门禁、场景内生成运行合同、筛选排序和确定性修复动作，不展示 raw 函数名、规则名或 override 来源；sceneContracts.ts 仅作为后端合同缺失时的前端 fallback；修复动作 deep-link 到槽位、供应商和失败诊断页并自动聚焦 scene/slot/capability；旧裸路径和 /ai-config/ai-routing-* 仅做兼容跳转。
  • AI 路由与供应商前端 API：参考 frontend/src/api/aiRouting.ts
  • AI 调用审计页面：参考 frontend/src/pages/platform/AICallTracesPage.tsx 与 frontend/src/api/aiCallTraces.ts；入口 /platform/ai-call-traces 位于平台 Console 的“质量与事件层”，要求 platform.ai_routing.manage；页面提供按状态、供应商、模型、函数、业务场景、能力槽位、prompt key、trace id、时间窗口和关键词过滤，列表默认只展示真实上游调用记录，能力探测按 probe_capability_* 单项上游调用显示，不额外展示汇总行；列表展示触发预览、runtime label/model/slot/routing/tokens/cost/latency，并优先用上游 usage 展示 prompt_tokens / completion_tokens / total_tokens，同时展示请求 max_tokens、finish_reason 与 Function Runtime Profile 版本，便于区分模型空响应、JSON 无效、截断和 HTTP 异常；详情只展示完整脱敏 provider 请求 payload、响应 payload、上游尝试链和触发/路由/探测元数据，不展示兼容 prompt/response 字段以免误导；详情必须展示 runtime_policy 中的场景 timeout 策略、输入规模桶、provider/job timeout 和建议动作；内部 provider code 只作为详情诊断字段展示；带 prompt_key 的详情可直接生成 Golden case。客户空间 AI 使用设置、Space、Project Launch 和项目级 AI 副驾不得暴露该入口。
  • Prompt 运营中心页面：参考 frontend/src/pages/platform/PromptAssetsPage.tsx 与 frontend/src/api/promptAssets.ts；入口 /platform/prompt-assets 位于平台 Console 的“质量与事件层”，要求 platform.ai_routing.manage；页面展示 prompt key、业务场景、family、风险等级、发布策略、默认模板、active release、draft 数、门禁状态、最新 replay、调用点和迁移缺口，详情弹层提供基础信息、模板 Diff、版本历史、发布门禁、回放评审、质量归因和运行信息；managed_release 可创建草稿、激活和回滚，guarded_release 可创建候选版本、运行契约回放或 LLM 回放并通过门禁后激活；回放评审页展示 run mode、judge 评分/标签/理由、关联 AI call log 与风险标记，发布概览展示 release watch；质量归因页展示 7 天调用、失败率、默认回退、成本、PMFlow 用户赞同/不赞同反馈、负反馈原因、优化候选、失败样本和 active golden cases，并可 deep-link 到 AI 调用审计或从失败调用生成带 case_type / priority / scenario_key / tags 的 golden case。客户空间 AI 使用设置、Space、Project Launch 和项目级 AI 副驾不得暴露该入口或 prompt body。
  • MCP 模板接入页：参考 frontend/src/pages/ai-config/mcp-config/
  • Contract Sync 看板：参考 frontend/src/pages/contract-sync-board/，入口为 /platform/contract-sync-board；旧 /ai-config/contract-sync-board 和裸 /contract-sync-board 只做兼容跳转。
  • Route / Context 治理页：参考 frontend/src/pages/query-route-governance/，入口为 /platform/query-route-governance
  • Knowledge Graph 治理页：参考 frontend/src/pages/knowledge-graph-context-board/，入口为 /platform/knowledge-graph-board；旧裸 /knowledge-graph-board 只做兼容跳转。
  • Semantic facts 治理页：参考 frontend/src/pages/semantic-facts-board/，入口为 /platform/semantic-facts-board
  • MCP 前端 API：参考 frontend/src/api/mcp.ts
  • Route / Context 治理前端 API：参考 frontend/src/api/queryRouteGovernance.ts
  • Semantic facts 前端 API：参考 frontend/src/api/semanticFacts.ts
  • AI 使用设置与平台工具入口：参考 frontend/src/pages/ai-config/constants.ts 与 frontend/src/router/index.tsx；GOVERNANCE_TOOL_GROUPS 是客户空间 AI 使用设置首页分组真源，平台诊断组仅对有 platform_context 的账号展示，GOVERNANCE_TOOLS 保留给既有测试与入口兼容

4. 模型与配置真源

  • 模型配置唯一来源：参考 backend/app/services/model/model_config.py
  • 路由规则真源：backend/.control_plane/pmflow-routing-rules.json
  • Prompt 聚合：backend/app/config/ai_prompts.py
  • Prompt 场景化分片：backend/app/config/ai_prompts_catalog/
  • Prompt registry：backend/app/config/ai_prompt_registry.py（静态 catalog + guarded runtime prompts + semantic fact prompts + inline discovered inventory；editable_policy=needs_migration 不代表运行时已可配置）
  • External Query Planner Prompt：backend/app/config/ai_prompts.py 中的 PROMPT_EXTERNAL_QUERY_PLAN
  • External Answer Presenter Prompts：backend/app/config/ai_prompts.py 中的 PROMPT_EXTERNAL_DIRECT_FACT_QA、PROMPT_EXTERNAL_SUMMARY_WITH_SOURCES_QA、PROMPT_EXTERNAL_COMPARE_WITH_SOURCES_QA
  • 开发轻启动配置：参考 backend/app/core/config.py、backend/app/main.py、backend/app/api/router.py 与 docker-compose.dev.yml

5. 维护建议

  • 新增接口时：先更新本文档，再同步 API_CONTRACTS.md
  • 新增页面/关键入口时：同步本文档与 ARCHITECTURE_INVENTORY.md
  • 若某条参考入口已经下线，应直接从本文档移除，不保留历史死链