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

41 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（PUT /ai-steward/llm-engines/settings）

2.2 AI Steward / Training / Mounted Runtime

  • 项目创建接口：参考 backend/app/api/ai_steward_api/routes_capture.py
  • 模型路由配置接口：参考 backend/app/api/model_routing.py
  • 回复质量闭环接口：参考 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 这组运行时真源，不再输出/持久化 subject_focus / query_profile.referenced_objects
  • 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，供 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/）；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 消息台列表接口：参考 GET /ai-pmo/work-items
  • 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

  • 需求点落信号源：参考 backend/app/services/signal/signal_source_orchestration/mixin_registry_execute.py
  • 飞书捕获模拟接口：POST /ai-steward/signal/capture-feishu
  • 项目删除接口：参考 backend/app/api/projects.py
  • 项目成员分配接口：参考 backend/app/api/projects.py + backend/app/services/project_member/service.py
  • 通用任务拆解接口：参考 POST /tasks/breakdown
  • 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 routing：参考 backend/app/api/pmflow_os_api/、backend/app/services/pmflow_os_projection_service.py、backend/app/services/pmflow_change_review_service.py、backend/app/schemas/pmflow_os.py；只读提供 GET /pmflow-os/projects/{project_id}/truth-state 与 GET /pmflow-os/projects/{project_id}/execution-summary，复用 truth_nodes / tasks / semantic_facts / ai_project_control / dev_sync，并读取 pmflow_threads / pmflow_thread_messages / pmflow_change_sets / pmflow_change_items / pmflow_approvals / pmflow_evidence_links；truth-state.reviewerRouting 是 {status, warningCode, summary, items} 读模型，会从 open/pending ChangeSet、待审 item 风险、跨对象类型、evidence source、项目成员与 OWNER / REVIEWER 角色生成 sourceType / riskLevel / priority / suggestedReviewer / fallbackReviewerRole / targetUrl，只读展示，不写 approval、不自动 assign reviewer；C1 写 API 包括 thread message、proposed_items extraction、ChangeSet detail、ChangeItem accept/edit/defer；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；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 / recommendations 与 release gate / validation run 关系；Iteration Loop P1 新增 POST /pmflow-os/projects/{project_id}/iteration-recommendations/{recommendation_id}/change-set-drafts，把真实 IterationRecommendation 转为 open ChangeSet、pending_review Requirement/Task/Risk/Decision items 与 iteration evidence，重复调用复用既有 draft；Iteration Loop P2 新增 POST /pmflow-os/projects/{project_id}/iteration-recommendation-groups/{group_key}/change-set-drafts，并在 execution-summary.releaseSignals.recommendations 补 groupKey / duplicateOf / mergedCount / impactLevel / riskLevel / suggestedChangeTypes / reviewPriority，在 recommendationGroups 聚合同组建议，支持同组 recommendation 批量生成一个可复用 ChangeSet draft 与 iteration_recommendation_group evidence；这些步骤均不执行发布命令、外部支付、真实推送、自动 Project Memory commit 或正式 Task 创建
  • Project Launch 真实创建链：参考 backend/app/api/pmflow_launch_api/、backend/app/services/pmflow_launch_service.py、backend/app/schemas/pmflow_launch.py 与模型 backend/app/models/pmflow_launch.py；接口为 POST /pmflow-launch/drafts 与 POST /pmflow-launch/drafts/{draft_id}/confirm，draft 只写 pmflow_launch_drafts，confirm 在同一事务内创建 projects / user_projects / pmflow_threads / pmflow_thread_messages / truth_nodes / tasks / semantic_facts seed / operation_logs
  • 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 当前推荐任务：参考 docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md 第 7 节；P7 与 Team Review P1 已完成，下一步从 truth-state.reviewerRouting 只读建议推进到 review request -> reviewer decision -> approval audit -> personal attention 的 Review Decision Loop；建议并行推进 main-flow-p8-review-decision-loop、space-p7-review-attention-queue、account-p8-review-decision-preference，再由 big-module-integration-p8 收口；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，不写 Project Memory、ChangeSet 状态、ProgressEvent 或 ReleaseValidationRun；Space P6 的 nextActionQueue 在 Space 本地读模型内把高风险待确认、发布阻塞/失败证据、handoff consumed 后缺少后续 progress、下一轮 draft、发布后 feedback/revenue/compliance 信号统一排序为“我的下一步”，所有 item 只跳 /change-review、/execution-bridge 或 /release-growth；Space P3 的 releaseAttention 优先从 truth-state.releases 的 release validation 投影生成“发布验证阻塞 / 发布验证待确认”，没有发布验证投影时才回落到 PMFlowExecutionSummary.releaseGate 的“发布候选 / 发布门禁阻塞”，所有动作只跳转 /release-growth?projectId=<id>；PMFlow OS 真实接入参考 frontend/src/api/pmflowOs.ts 的 getPMFlowTruthState(projectId)、getPMFlowExecutionSummary(projectId)、createPMFlowExecutionHandoff、consumePMFlowExecutionHandoff、createPMFlowExecutionProgressEvent、createPMFlowReleaseValidationRun、createPMFlowReleaseFeedbackIngest、createPMFlowIterationRecommendationChangeSetDraft、createPMFlowIterationRecommendationGroupChangeSetDraft、createPMFlowThreadMessage、createPMFlowExtraction、getPMFlowChangeSet、acceptPMFlowChangeItem、editPMFlowChangeItem、deferPMFlowChangeItem、commitPMFlowChangeSet；PMFlowExecutionSummary.releaseGate 是 ReleaseGrowth 真实发布门禁前端合同，releaseGate.latestValidationRun 是最新发布验证记录前端合同，execution-summary.releaseSignals 是 Release/Growth 发布后 feedback/revenue/recommendation 信号、recommendation quality grouping 与下一轮 ChangeSet draft 状态前端合同；Project Launch 创建链参考 frontend/src/api/pmflowLaunch.ts 的 createPMFlowLaunchDraft 与 confirmPMFlowLaunchDraft
  • AI Steward 页面入口：参考 frontend/src/pages/ai-steward/
  • AI Steward 问答浮窗与上下文显性化组件：参考 frontend/src/components/ai-steward/FloatingQAChat.tsx、frontend/src/components/ai-steward/QAConversationStatusBar.tsx、frontend/src/components/ai-steward/QAResponseMetaCard.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/
  • 个人空间首页 / 空间层入口前端产品域：参考 frontend/src/features/personal-space/、frontend/src/api/space.ts 与薄入口 frontend/src/pages/PersonalSpacePage.tsx；本地预览路由入口为 /space，首屏以 nextActionQueue 展示“我的下一步”，并保留继续推进、待我确认、发布关注、发布后反馈关注、下一轮迭代草稿关注、执行中 / AI 正在推进、暂存想法、草案箱与最近项目明细；点击项目主动作进入 /pmflow-os?projectId=<id>，待确认项进入 /change-review?projectId=<id>&changeSetId=<id>，执行中项进入 /execution-bridge?projectId=<id>，发布关注和发布后反馈关注项进入 /release-growth?projectId=<id>，已生成 ChangeSet draft 的下一轮建议进入 /change-review?projectId=<id>&changeSetId=<id>；Space 只读聚合项目摘要、PMFlow OS truth-state.releases / execution-summary.releaseGate / execution-summary.releaseSignals，发布验证、发布后信号或 iteration draft 缺失时显示明确空态，不虚构验证、反馈、收入、ROI、合规、iteration recommendation 或 ChangeSet draft，不直接写 Project Memory、ChangeSet 状态、execution event、ReleaseValidationRun、FeedbackIngest、RevenueEvent 或 ComplianceCheckRun；暂存想法后端只读聚合尚未接入时必须显示 empty/warning，不得用 mock 数据冒充真实内容；空间层共享左侧栏、顶部条与空间用量组件在 frontend/src/features/personal-space/components/SpaceChrome.tsx，/project-launch 桌面首次新建壳也复用该组件
  • 新项目启动台 / 首次进入页前端产品域：参考 frontend/src/features/project-launch/ 与薄入口 frontend/src/pages/ProjectLaunchPage.tsx；真实模式默认通过 frontend/src/api/pmflowLaunch.ts 调用后端 draft/confirm API，只有显式 ?demo=1 或 ?dataSource=demo 才启用 mockData.ts 本地演示状态机；本地预览路由入口为 /project-launch
  • PMFlow OS 共享 truth store 与主链状态动作：参考 frontend/src/features/pmflow-os/store.tsx；当前支持 ?projectId=<id> 走 React Query 读取真实 truth-state 与 execution-summary，真实模式下 thread message、proposed_items extraction、ChangeItem accept/edit/defer、ChangeSet commit、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、不伪造 execution event、发布验证记录、发布后信号或下一轮 draft；?demo=1 才启用本地 mock 演示状态机和本地动作；项目内 AI 结构化闭环状态机为 command_idle / ai_extracting / extraction_ready / review_open / writeback_success
  • Account Settings / /me 前端产品域与 P1-P7 偏好合同：参考 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；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；TeamLayerPage.tsx 真实模式读取 state.reviewerRouting 展示 ready/empty/warning、待审 ChangeSet、来源（下一轮迭代 / AI 提取 / 手动）、风险等级、建议审查人或 fallback role、审查原因、待审 item 数、证据数，并只跳转 /change-review?projectId=<id>&changeSetId=<id>，不自动分派 reviewer；ReleaseGrowthPage.tsx 真实模式展示 execution-summary.releaseGate、execution evidence、阻塞原因、下一步动作、latestValidationRun 和 releaseSignals，缺证据或缺发布后信号时显示 empty/warning，不展示 mock 发布结果；页面可调用真实 API 创建 release validation run、摄取 release feedback，从真实 recommendation 单条或同组批量生成下一轮待确认 ChangeSet draft，并解释 iteration_recommendation_group evidence 的组、反馈、风险、影响和审查优先级；生成后仍进入 Change Review accept/edit/defer，不自动 commit、不写 Project Memory、不执行部署命令、不接外部支付；同时消费 Account notification preference helper，releaseGate 关闭时静默发布门禁强调提醒，failureAlert 关闭时静默失败强调提醒，所有真实证据和审计状态仍可见；静态高保真发布/增长数据仅保留在显式 demo 模式
  • 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 通知消费合同、失败事件映射和缺字段 fallback。
  • 网页问答显式锚点与 AI Steward URL 构造：参考 frontend/src/components/ai-steward/qaPageAnchor.ts
  • Inbox 页面入口：参考 frontend/src/pages/inbox/
  • Inbox plan_mode 展开卡片与映射：参考 frontend/src/components/inbox/InboxListItem.tsx、frontend/src/lib/inbox.ts、frontend/src/api/aiPmo.ts
  • 登录页/营销页的共享视觉基线：参考 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/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 tab 级懒加载入口：参考 frontend/src/pages/ai-steward/AIStewardPage.tsx
  • AI Config section 级懒加载入口：参考 frontend/src/pages/ai-config/AIConfigPage.tsx
  • 项目看板控制面/对话框懒加载入口：参考 frontend/src/pages/project-board/ProjectBoardPage.tsx
  • 用户页对话框懒加载入口：参考 frontend/src/pages/users/UsersPage.tsx
  • 图表二级 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/
  • Model Routing 页面：参考 frontend/src/pages/model-routing-config/
  • MCP 模板接入页：参考 frontend/src/pages/ai-config/mcp-config/
  • Route / Context 治理页：参考 frontend/src/pages/query-route-governance/
  • Semantic facts 治理页：参考 frontend/src/pages/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 Config 治理工具入口：参考 frontend/src/pages/ai-config/constants.ts 与 frontend/src/router/index.tsx

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
  • 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
  • 若某条参考入口已经下线，应直接从本文档移除，不保留历史死链