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

277 lines
89 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# ARCHITECTURE INVENTORY
## 1. 目的
- 本文档承接 PMFlow 的架构库存与关键入口索引。
- `CLAUDE.md` 保留当前架构说明、运行边界和参考模式。
- 本文档记录当前模块分布、重要子包、关键脚本与前端页面分组，后续架构变更统一在此同步。
## 2. 同步规则
- 任何影响目录结构、主入口、模块归属、前后端页面/API 分组、脚本布局的架构变更，都必须同步更新：
- `CLAUDE.md`
- `docs/architecture/ARCHITECTURE_INVENTORY.md`
- API/Schema 契约变更仍需同步：
- `docs/architecture/API_CONTRACTS.md`
- 对应前端 `types/api` 封装
- 路由/函数名/运行时流向变更仍需同步：
- `docs/architecture/DATAFLOW.md`
- `backend/.control_plane/pmflow-routing-rules.json`
## 3. 顶层库存
- `docs/PMFLOW_PRODUCT_BLUEPRINT.md`：PMFlow 产品蓝图真源；锁定“对话驱动的 AI 产品执行操作系统”、`solo-first, team-ready`、项目真相层、ChangeSet 待确认、Execution Bridge 与人机混编团队方向
- `docs/PMFLOW_PRODUCT_DELIVERY_STANDARD.md`：PMFlow 产品推进执行标准；记录当前进度、Phase A-F/P8 推进顺序、单次任务范围、Codex 并行推进协议、进度台账和新线程接续规则；P8 已完成 Review Decision Loop、Space review attention queue、Account review decision preference 与 integration 收口
- `docs/PMFLOW_UI_CONTRACT.md`：PMFlow UI 契约真源；锁定 Logo、浅色白底 + `#2463EB`、移动端固定底部导航、四类视觉语法、核心功能 canonical 契约和当前前端一致性审计
- `docs/architecture/MASTER_CONTRACT.md`：跨栈主契约
- `docs/architecture/CODE_REFERENCE_INDEX.md`：新增代码参考入口与高频代码索引
- `docs/architecture/PMFLOW_OS_PRODUCT_CONTRACT.md`：PMFlow OS 产品合同真源；锁定前端 `ProjectTruthState / ChangeSet / Evidence / Approval / ExecutionContext` 与后端 `truth_nodes / tasks / semantic_facts / ai_project_control / dev_sync` 的复用边界；Phase C1 已实现 review 表和审查 API，Phase C2 backend/frontend 已实现 atomic commit
- `docs/architecture/RUNTIME_GUARDRAILS.md`：运行边界、守门规则与已知运行假设
- `docs/architecture/API_CONTRACTS.md`：接口/Schema 契约
- `docs/architecture/DATAFLOW.md`：主链与数据流说明
- `docs/architecture/TASK_BRIEF_TEMPLATE.md`：并行安全任务包模板；用于声明 Packet 的 `base_ref / read_scope / write_scope / forbidden_paths / shared_files / verification / docs_to_sync`
- `docs/superpowers/plans/`：实现计划
- `docs/superpowers/specs/`：需求/方案规格
- `docs/task_briefs/`：任务包产物与验收截图
## 4. 后端库存
### 4.1 API 路由分组
- `backend/app/api/ai_steward_api/`
- `backend/app/api/ai_pmo_api/`
- `backend/app/api/feishu_api/`
- `backend/app/api/rag_api/`
- `backend/app/api/sstc_api/`
- `backend/app/api/pmflow_launch_api/`
- `backend/app/api/space_api/`
- `backend/app/api/pmflow_os_api/`
- `backend/app/api/signals_api/`
- `backend/app/api/signal_sources_api/`
- `backend/app/api/semantic_facts_api/`
- `backend/app/api/skill_tags_api/`
- `backend/app/api/ai_logs_api/`
### 4.2 AI PMO 与语义主链
- `backend/app/services/ai_pmo/ai_pmo_kernel/`
- `backend/app/services/ai_pmo/ai_pmo_kernel_ingress_flow/`
- `backend/app/services/ai_pmo/project_operating_context_builder.py`
- `backend/app/services/ai_pmo/ai_pmo_typed_executor_execute/`
- `backend/app/services/ai_pmo/ai_pmo_typed_executor_discovery/`
- `backend/app/services/ai_pmo/semantic_context/`
- `backend/app/services/ai_pmo/workflow_semantic_planner/`
- `backend/app/services/ai_pmo/draft_confirm_handler.py`
### 4.3 问答、模型与生成
- `backend/app/services/adaptive_rag_service/`
- `backend/app/services/adaptive_rag_service/internal_query_context.py`
- `backend/app/services/adaptive_rag_service/mixin_project_fit_brief.py`
- `backend/app/services/adaptive_rag_service/mixin_query_route_gateway.py`
- `backend/app/services/adaptive_rag_service/mixin_query_route_governance.py`
- `backend/app/schemas/project_operating_context.py`
- `backend/app/services/external_query_service/`
- `backend/app/services/semantic_fact_service/`
- `backend/app/services/semantic_fact_service/hooks.py`
- `backend/app/services/llm_service/`
- `backend/app/services/ai_steward_service/`
- `backend/app/services/feedback_center/`
- `backend/app/services/task_brief_service.py`
- `backend/app/config/ai_prompts.py`
- `backend/app/config/ai_prompts_catalog/`
- `backend/app/config/ai_prompt_registry.py`
- `backend/app/services/prompt_assets_service.py`
- `backend/app/services/prompt_runtime_service.py`
- `backend/app/services/model/model_routing/service.py`
- `backend/app/services/model/model_config.py`
### 4.4 集成、信号与运行时
- `backend/app/services/integrations/feishu_integration_service/`
- `backend/app/services/integrations/feishu_outbox/service.py`
- `backend/app/services/integrations/feishu_signal_pipeline/`
- `backend/app/services/signal/signal_capture_service/`
- `backend/app/services/signal/signal_source_orchestration/`
- `backend/app/services/signal/signal_source_repair/`
- `backend/app/services/signal/signal_planner/`
- `backend/app/services/signal/draft_generator_service.py`
- `backend/app/core/startup/`
- `backend/app/utils/thread_context.py`
- `backend/app/utils/timezone.py`
- `backend/app/utils/audited_write.py`
- `backend/alembic/versions/`
- `backend/alembic/versions/20260429_rename_glm_provider_to_dashscope.py` 是供应商编码迁移：把历史 `integrations.config` 与 `ai_call_logs.routing_meta/provider` 中的旧内部 provider code `glm` 迁移为配置化 `dashscope`；后续不得恢复 `glm` provider alias，`glm-5` 只可作为模型名出现。
- `backend/app/main.py` 现已把模型连通性探测、飞书长连接、World Model 预热、调度器与后台队列消费收口为显式环境开关；开发环境可直接通过 `STARTUP_*` / `FEISHU_LONG_CONNECTION_ENABLED` 关闭重型副作用，避免热重载每次都付全量启动成本。
- `backend/app/api/router.py` 现改为按模块路径动态注册路由；默认保持 `full`，并支持通过 `API_ROUTE_PROFILE` 与 `API_OPTIONAL_ROUTE_GROUPS` 在开发场景下裁掉重型 optional route group，减少 eager import 开销。
- `backend/app/api/space_api/` + `backend/app/services/space_saved_idea_service.py` + `backend/app/models/saved_idea.py` 是 Personal Space 暂存想法闭环；`saved_ideas` 作为 pre-project idea seed 保存原始输入、来源、准备度、缺失问题、状态、结构化 enrichment 元数据和 Project Launch draft 关联。创建与编辑原始输入时会尝试 `space_saved_idea_enrichment_v1` 结构化判断目标用户、问题、价值假设、验证信号和补充问题，prompt key 为 `PROMPT_SAVED_IDEA_ENRICHMENT`，运行时经 `PromptRuntimeService` 读取平台 active release 并记录 prompt 归因；问候/测试/无实质想法输入必须判为信息不足与 0 准备度，AI 失败时显式保存 `ai_failed/system_baseline`，不冒充 AI 成功。该链路允许创建、列表、更新、归档和 promote 到 Project Launch 草案，但不写 Project Memory、ChangeSet、执行事件或发布对象。
### 4.5 Mounted Runtime / 训练相关
- `backend/app/models/reply_iteration.py`
- `backend/app/models/training_pipeline.py`
- `backend/app/models/mounted_ai_runtime.py`
- `backend/app/models/query_route_memory.py`
- `backend/app/models/semantic_fact.py`
- `backend/app/models/semantic_fact_extraction_run.py`
- `backend/app/models/pmflow_launch.py`
- `backend/app/models/saved_idea.py`
- `backend/app/models/pmflow_change_review.py`
- `backend/app/api/ai_steward_api/routes_reply_iteration.py`
- `backend/app/api/ai_steward_api/routes_training_pipeline.py`
- `backend/app/api/ai_steward_api/routes_mounted_ai.py`
### 4.6 结构归并结果
- `backend/app/services/` 根目录已目录化收敛，新增服务优先进入对应子包。
- API canonical 入口优先使用 `*_api/` 子包，不再优先引用顶层兼容壳。
- 运行时业务动作归因优先走“对象/上下文绑定 -> `SemanticContextPacket` -> `SemanticDecision` -> gatekeeper”。
- non-plan `query.answer` 现已在 `AdaptiveRAG` 内增加 `Query Route Gateway`：只消费上游单次结构化 `query_profile/source_policy/effective_source_policy` 与显式 hint，结合 `ProjectOperatingContext` 归一化产出 `route_mode / decision_origin / reply_contract / probe_snapshot(contract audit) / execution_recipe`，不再在运行时执行 internal/external probe 或 route memory 强拍板，再进入检索与回答主链。
- query semantics 上游真源也已继续收口：`PROMPT_RAG_QUERY_SEMANTICS` + `mixin_core_intent.py` 现在只把 `query_profile(needs_private_context, needs_freshness, confidence)` 与 `BusinessSemanticFrame` 写回运行时，`query_profile.referenced_objects` 已从 production backend 移除，不再参与 route snapshot、session scope continuity 或任何 read-side 分流；`subject_focus` 只作为历史结构化输入兼容字段进入 `shared_utils.py` 的实体归一化，不得重新作为 route/session 二次拍板来源。
- `WorkflowSemanticPlanner` 冷启动 bundle 现已补上四挡 `interaction_boundary` 合同：`decision_schema.py` 定义 `InteractionBoundaryPacket / AnswerControlDecision / SelfReviewResult`，planner 会把显式 `status / recommendation / draft / execute` 边界与识别出的 `workflow_plans` 合成 `answer_control`，并把 `requested_level / forbidden_levels / effective_level / blocked_workflows` 落进 bundle diagnostics。对“只给建议/先别出草稿”这类 recommendation-only 问法，planner 允许识别到底层 `signal_source_flow`，但最终会按 boundary 把 bundle 降回 `query_flow`，避免误滑到 `draft_pending_confirm`；旧的无 boundary bundle 仍走兼容透传，不会压坏既有写链路。
- `AdaptiveRAG` 与 AI PMO 主链里几个最容易回流硬语义的入口也已继续收口：project progress fast answer 只按结构化 `interaction_level / goal_kind / resource_role / expected_answer_shape` 决定是否绕开 fast path；casual chat 直答只消费 `message_intent=casual_chat` 的结构化结果；typed executor 对 `project_lookup` 直答只认结构化 `message_intent=project_lookup(_question) + query_semantics`，不再被 `项目列表/项目清单/项目#123` 这类词面带偏；signal 数量和“先分析再入库”这类分析模式也只读 `requested_count / analysis_mode / operation_intent_contract`，不再从自然语言里额外解析“3个信号/先分析后入库”。
- internal config 这条 read-side 也继续结构化了：`AdaptiveRAGTargetResolutionMixin` 不再把泛化 `resource_role=config` 自动映射成 `config:system`，必须依赖显式 `object_binding` 区分 `config:model_routing` 与 `config:mcp_template_center`；对应的 deep guard 直答也拆成模型路由和 MCP 配置两个子口径。
- 项目化影响判断不再必须依赖外部实时抓取才能保住“直接影响”那一行：`AdaptiveRAGFastAnswerProjectMainMixin` 现在会根据 `goal_kind=impact_judgment / expected_answer_shape=impact_chain` 保留结构化 `external_impact` 渲染，避免 WMS/税控/评论流这类高频影响问法退回普通项目周报。
- `AdaptiveRAG` 的 follow-up clarification 现在也继续往结构化真源收：`mixin_followup_anchor.py` 不再在 runtime 用“第几条/标签名/最近回复 match_text”去消费 `pending_clarification`；`query_route_selection / followup_anchor_selection` 都先经过统一结构化澄清解析，再把选中的 `source_policy_hint / query_semantics_overrides / selected_qa_id` 透回 `mixin_answer_mainline.py`。这样用户说“内部那个 / 第二条”后，主链会带着明确的 route override 或 anchor QA id 继续，不会再把原问题拿回去后靠最近回复词面重猜。
- internal `Operation Contract / Target Resolver` 已按 business-frame-first 收口：`mixin_target_resolution.py` 现在只消费 `goal_kind / target_scope / resource_role / project_binding / object_binding / expected_answer_shape` 来判定 `project / task / signal / config / feature / doc / user` 绑定，不再让 `subject_focus / referenced_objects` 这类 coarse 字段单独拍板内部对象类型。
- internal object/domain clarify 继续往下一层时，当前由 `backend/app/services/adaptive_rag_service/internal_domain_catalog.py` 提供 catalog 真源；catalog 已覆盖 `project / task / signal / config / feature / doc / user` 这批 internal domain。`mixin_target_resolution.py` 会在只确认大域（如 `resource_role=config` 或 `resource_role=doc`）但尚未唯一落到子对象时生成 `candidate_summary`，`mixin_answer_payload.py` / `mixin_answer_precheck.py` / `mixin_followup_anchor.py` 再把它转成 `internal_target_selection` pending clarification，并在 follow-up 后回填 `query_semantics_overrides` 继续主链。
- `AdaptiveRAG` read-side 那批旧 compatibility consumer 也已一起收口：`shared_utils.py` 统一提供 `BusinessSemanticFrame -> structured 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` 现在只看这层结构化结果决定 `project / task / signal / config / feature / doc / user` 的快答、检索、deep guard 与 internal query plan；`subject_focus` 仅在 `shared_utils.py` 作为上游旧结构化输入的实体类型补充，不允许各 consumer 分散读取或恢复 `referenced_objects` 二次业务分流。
- `ProjectOperatingContext` 当前由 `project_operating_context_builder.py` 统一组装：最小范围固定为“当前项目 + 当前仓库摘要 + 页面/线程锚点”；world model 建完后会回填 `resolved_project_id / repo_scope`，再供 `Query Route Gateway`、`mixin_project_fit_brief.py` 与 answer payload 消费。
- `analysis_packet` 现作为单独的 analysis layer 增量接到问答主链：`analysis_packets.py` 定义 `project_fit_analysis / external_impact_analysis / internal_explain_analysis / followup_explain_analysis` 这组 typed packet，`analysis_packet_builder.py` 只消费 `ProjectOperatingContext / ExecutionRecipe / fit_brief / external_recommendation / InternalContextPacket / clarification` 等 runtime truth 组包，不从回答正文反推。当前 richer packet 会把 `current_subject / candidate_position / rejected_position / reason_chain` 这类对象级分析字段显式落盘，避免 presenter 再用泛句补戏；共享 richer project snapshot 由 `analysis_project_snapshot_loader.py` 统一补 `tasks/signals + description/summary + analysis_object_refs`，供 AdaptiveRAG payload 和 Feishu presenter 复用。最新 snapshot loader 已 fail-closed：没有真实结构锚点时，不再从 task/signal 标题描述推 `fit_candidate_* / fit_rejected_* / primary_*` 关系，也不再生成 `task_signal_scores / signal_task_links` 这类 token-overlap 产物；builder 主路径只消费显式 object ref、精确文本绑定和唯一候选这三类非语义结构证据。
- `analysis_packet_builder.py` 里原来那层“工程任务/信号源占位/展示层”词面 second-guess 已继续收掉：generic fallback、direct-match generic 分支和 internal explain target fallback 现在都不再靠 `_looks_like_engineering_task / _looks_like_signal_placeholder / _task_presentation_hint / token-overlap / partial-name match` 去反驳上游对象关系；没有显式 ref 时只能诚实降级，最多允许“唯一候选”这种纯结构兜底。
- internal `query.answer` 的下一阶段基线已经确认：`Query Route Gateway` 之后不再直接靠快答分支拍板，而是统一进入 `Operation Contract -> Target Resolver -> Query DSL Plan -> InternalContextPacket -> 白名单受控执行器 -> semantic facts 优先 -> verifier` 主链；`InternalContextPacket` 由 `backend/app/services/adaptive_rag_service/internal_query_context.py` 定义，并作为 internal executor / verifier / runtime summary 的运行时单一真源；相关设计规格见 `docs/superpowers/specs/2026-04-15-internal-query-dsl-plan-design.md` 与 `docs/superpowers/specs/2026-04-15-semantic-facts-read-model-design.md`。
- internal 主链现已补上 packet 预检：`mixin_answer_mainline.py` 在组完 `InternalContextPacket` 后，会先拦截 `missing packet / missing operation contract / target clarify / missing query plan contract` 这类上下文不完整场景，再决定是否进入 deterministic fast path、internal model-config fast path、provider-neutral project semantic fast path 或 retrieval；`query_semantics` 对 `operation_contract / target_resolution / query_plan` 的镜像也已收口到单点兼容写回。
- external `query.answer` 已完成 second-pass 收口：`Query Route Gateway` 之后统一进入 `backend/app/services/external_query_service/`，按 `ProjectFitBrief -> External Query Planner -> External Query Gateway -> External Provider Registry -> MCP adapter 优先 -> bounded fallback live search -> external answer verifier -> ExternalContextPacket -> ExternalAnswerPresenter` 执行；planner 会显式消费 `fit_brief_summary / project_scope_hint / recommendation_goal / project_object_anchors / signal_source_objectives`，其中 formal object anchors 优先来自 `ProjectFitBrief.signal_source_anchors`，项目任务目标锚点来自 `ProjectFitBrief.signal_source_objectives`，不再拿 feature capability 名称或固定类别模板直接冒充 formal project object；payload 会拆出 `fit_brief / external_recommendation`，AdaptiveRAG external probe、freshness fetch 与 external route retrieval 已接到这条链上，并对 external sources 执行 fail-closed 过滤。当前 planner 还补了 recommendation query seed guard：命中“推荐外部信号源”问法时，会优先把当前项目任务目标和 formal anchor 驱动的 query 排到 `search_queries` 前面，避免 structured planner 用 `industry best practices / external data sources` 这类泛化词覆盖掉更贴当前项目的 seed query；同时 `interaction_level=recommendation` 会从统一语义规划层经 `answer_control/source_policy_hint` 透传到 `ExternalQueryPlan`，recommendation 分支不再由 presenter 本地 cue list 单独拍板。`presenter.py` 使用独立 external-only prompt 家族，并强制区分 `verifier_blocked / no_relevant_results / retrieval_failed / indirect_only`，不再回流 `industry_trend/external_trend` scene prompt；对 recommendation ask，presenter 现在会先生成 `SignalSourceRecommendationPacket(candidates + caveat)`，再渲染成业务中文的 `1/2/3` 候选建议，确保输出真的贴当前项目对象，而不是只靠自由文本兜一句“先看上游输入”。同时仍保留 overclaim guard：当结构化候选或文本里出现百分比、已确认、无需验证等高确定性措辞时，会 fail-closed 回退到 customer-safe candidate 文案。相关设计规格见 `docs/superpowers/specs/2026-04-15-external-query-gateway-design.md`。
- non-plan recommendation -> signal-source write 当前已补齐结构 carry-over：external recommendation 不再只返回文本，`SignalSourceRecommendationPacket` 里的 candidate set 绑定会经 `reply_anchor_qa_context + action_contract` 一路沉到 `signal_source.onboard` 执行结果，并在 follow-up `把推荐的写进系统 / 确认入库` 时由 `mixin_followup_project_signal_resume.py` 重建回 `operation_intent_contract(candidate_set_binding/candidate_refs/project_binding)`。`signal_source.onboard` 直写链会在 signal 已 materialize 且项目关联成功后把业务结果视为 `succeeded`，同时仅通过 `post_process_status / signal_source_workflow.status` 暴露后续 onboarding/manual 状态；`ai_pmo_reply_renderer.py` 也会把批量 signal source 直写回执渲染成自然业务中文，而不是 requirement draft 或 pending-manual 漂移文案。
- QA session detail 持久化现已补齐 `routing_snapshot.response_payload`：`mixin_core_intent.py` 在写 `QARecord` 时会把 `project_operating_context / execution_recipe / fit_brief / external_recommendation / analysis_packet / handoff_mode / can_enter_plan / recommended_next_step` 一并归档，`mixin_qa_session_list_ops_p1.py` 再将其投影给 AI Steward 历史回放，避免即时回答与 session detail 出现两套合同。
- Feishu QA 呈现现与共享 analysis packet 对齐：`mixin_receive_routing.py` 会先基于 `project_operating_context` 读取当前项目实体快照，再调用 `analysis_packet_builder.py` 生成共享 `analysis_packet`，之后才进入“受控改写 -> blocked-entity 校验 -> deterministic fallback”的渠道 presenter。运行时会同时校验 fixed opener、标签摘要、内部 packet 术语（如 `analysis_packet / missing_mapping / next_step / focus_objects / reason_chain`）以及未入选实体泄漏；若任一条件不满足，则 fail-closed 回退到 packet-based deterministic 文本。同时保留 `draft_pending_confirm / requirement_plan_followup / pending_manual` 优先走 action card，避免把飞书回归修成单纯文案 bypass。最新 `qa_direct` 还新增了一层中文化 presentation policy：内部现状问题若原始 answer 泄出 `Project database / signal_total / 当前盘面 / 建议动作 / External Freshness Guard` 这类英文或内部术语，会优先回退成共享 packet 文本，并最多只追加一行中文来源说明；外部信号源 recommendation ask 若已有推荐正文，则优先直出推荐正文，再补同样的中文来源说明；对 sparse project-fit 这类 packet，deterministic fallback 也会转成人话解释，不再原样暴露 packet 缺口字段。
- Feishu `project.create` 预填与 QA fallback 现继续去 lexical 化：project create 相关字段不再由 `_extract_project_scope / _extract_project_intent_fields / _is_contextual_project_request / heuristic_*` 之类 helper 从用户原话里扣词，而统一消费 `_extract_project_prefill()` 的结构化 `suggested_name / suggested_description / suggested_scope`；QA fallback 也不再用 `_pick_feishu_entity_by_keywords` 按“摘要/拉取/推送”等关键词挑实体，改成只按共享 packet/select entity 的结构顺序兜底。
- `analysis_packet_builder.py` 的 sparse project-fit fallback 也往结构化真源继续收：当前如果 `preferred/rejected` 对象缺失，会直接按“结构对象缺失”降级，不再靠“解释层/当前主链”这类占位词表决定 sparse fallback 分支。
- unified handoff 当前补有最小 rollback guard：`shared_utils.py` 提供 env flag 解析，`mixin_query_route_gateway.py` / `mixin_answer_retrieval.py` / `mixin_answer_payload.py` 分别支持独立关闭 `execution_recipe` 增强、`fit_brief + external_recommendation` 构建、以及默认 `offer_after_answer` 呈现，不需要回退 ingress/context 真源。
- `analysis_packet` 当前也带独立 rollout guard：`PMFLOW_ENABLE_ANALYSIS_PACKET_FAMILY=0` 时，AdaptiveRAG payload / session replay / Feishu presenter 会回退到旧 handoff truth + 旧 presenter，避免影响 `project_operating_context / execution_recipe / fit_brief / external_recommendation` 真源。
- `query.answer` 的客户可见回答展示也已确认独立基线：运行时证据必须拆成 `customer_safe` 与 `admin_debug` 双视图，客户侧统一消费中文化 `display_label`，禁止直接暴露 `raw_source_label`、机器来源或内部术语；external answer presenter 的 prompt 输入也必须保持 external-only，仅允许消费经 verifier 通过的外部证据摘要与计划摘要；相关设计规格见 `docs/superpowers/specs/2026-04-15-answer-presentation-policy-design.md`。
- 下一阶段的全量业务结构化基线已确认：在 `InteractionBoundaryPacket / AnswerControlDecision` 之上继续引入 `BusinessSemanticFrame`、`AnswerShapeContract`、`RecommendationCandidateSet`、`ClarificationDelta / CorrectionDelta` 与 `OperationIntentContract`，把 recommendation、clarification/correction、casual chat、non-planmode direct signal-source write 统一收口到同一语义真源；并以 58 条广覆盖业务语义矩阵作为完整回归基线、以 `docs/superpowers/specs/2026-04-20-business-golden20-refresh.md` 里的 20 条当前项目池黄金案例作为日常 P0/P1 spot check 集。
- `semantic_fact_service` 已升级为统一基线：`semantic_facts / semantic_fact_extraction_runs` 读模型、ORM 提交钩子自动收集对象变更并 upsert `ingest_events(channel=semantic_fact_extract)`、统一 worker 抽取/失活，以及 internal query 的 facts-first 主路径。
- semantic facts 自动抽取覆盖 `project / task / signal / document / user / requirement(charter) / release / review` 八类业务对象；manual retry 与 backfill 走同一队列、同一 worker，不再开旁路。
- MCP 模板接入中心已接入 `backend/app/api/mcp_api/` + `backend/app/services/mcp_config/`：租户内统一保存 MCP 模板 catalog、server 配置 bundle、命令预览、validate 结果、runtime probe 与 `pending_local_apply / user_confirmed / not_required` 状态；`backend_direct` 模板既支持远程 `streamable_http`（如 `microsoft_learn`），也支持后端内建 `backend_adapter` runtime（如 `duckduckgo`），本地 `stdio` 模板只输出 Local Bridge/兼容 host 接入说明，服务端不直写客户机器 `~/.codex/config.toml`。
- `query_route_memories` 作为独立路由记忆表，承接 `QARecord` 的 route audit、feedback 回灌和离线评估样本，不复用原 answer-quality 资产表。
- `query_route_memories` 现已补 manager-only 只读治理入口：`backend/app/api/rag_api/routes_route_governance.py` + `mixin_query_route_governance.py` 负责 `/rag/query-route-governance/summary|items|items/{id}`，统一暴露 `reply_contract / probe_snapshot / query_profile / feedback_outcome` 审计快照，但 v1 不做在线自动调路由。
- `backend/tests/test_runtime_structured_semantics_contract.py` 与 `backend/tests/test_feishu_pipeline_queue_contract.py` 共同守门 runtime 结构化语义收口，锁定飞书入口、signal capture、reply/runtime routing 不得回流旧词法拍板 helper。
- `backend/tests/test_external_query_planner.py` 现已补进 external fallback 回归，锁定 planner fallback 只能产出 generic external plan，不得再根据 `weather/news/public_model/...` 之类对象映射在运行时硬分 query_kind。
## 5. 前端库存
### 5.1 页面分组
- `frontend/src/pages/ai-steward/`（legacy redirect / 迁移占位，不再作为产品页入口）
- `frontend/src/pages/scheduler-center/`
- `frontend/src/pages/project-board/`（legacy 项目控制面，用户入口已下线；旧 `/projects/:id/board` 由 router 重定向到 PMFlow OS 主链，待确认后物理删除）
- `frontend/src/pages/projects/`
- `frontend/src/pages/users/`
- `frontend/src/pages/recipes/`
- `frontend/src/pages/feishu-config/`
- `frontend/src/pages/ai-config/`
- `frontend/src/pages/model-routing-config/`（隐藏 Route Lab，只读函数级路由诊断）
- `frontend/src/pages/ai-config/mcp-config/`
- `frontend/src/pages/query-route-governance/`
- `frontend/src/pages/task-brief-center/`
- `frontend/src/pages/task-brief-runs/`
- `frontend/src/pages/task-brief-template/`
- `frontend/src/pages/charter-detail/`
- `frontend/src/pages/contract-sync-board/`
- `frontend/src/pages/dashboard/`
- `frontend/src/pages/knowledge-graph-context-board/`
- `frontend/src/pages/semantic-facts-board/`
- `frontend/src/pages/login/`
- `frontend/public/brand/`（PMFlow Logo / favicon 源资产）
- `frontend/src/components/brand/`
- `frontend/src/components/login/`
- `frontend/src/features/pmflow-os/pages/`
- `frontend/src/features/pmflow-os/components/`
- `frontend/src/features/account-settings/`
- `frontend/src/features/personal-space/components/`
- `frontend/src/pages/skill-tasks/`
- `frontend/src/pages/skills/`
- `frontend/src/pages/user-profile/`
- `frontend/src/pages/user-skills/`
- `frontend/src/pages/workload-detail/`
- `frontend/src/pages/workloads/`
### 5.2 API 与共享模块
- `frontend/src/api/aiPmo.ts`
- `frontend/src/api/aiSteward.ts`
- `frontend/src/components/brand/PMFlowLogo.tsx` 与 `frontend/src/components/brand/PMFlowUserAvatar.tsx`（PMFlow Logo 与本地品牌头像统一入口；应用壳、营销页、登录视觉和 favicon 读取同一组品牌图，账号头像不依赖随机外链服务）
- `frontend/src/components/marketing/`
- `frontend/src/components/login/`
- `frontend/src/components/layout/LazyBoundary.tsx`
- `frontend/src/components/ai-steward/`
- `frontend/src/components/ai-steward/QAConversationStatusBar.tsx`
- `frontend/src/components/ai-steward/QAResponseMetaCard.tsx`
- `frontend/src/components/ai-steward/QAResponseMetaCard.test.tsx`
- AI Steward 问答展示现分三层显性化：`FloatingQAChat.tsx` 保留为旧浮窗兼容代码并负责即时回答/历史回放归一化能力，`QAConversationStatusBar.tsx` 展示对象/来源/仓库/执行通道/plan handoff，`QAResponseMetaCard.tsx` 展示 `fit_brief / external_recommendation / recommended_next_step`，对应前端回归由 `FloatingQAChat.test.tsx` 与 `QAResponseMetaCard.test.tsx` 锁定；当前产品壳不再全局挂载 `FloatingQAChat`，空间级入口由 `SpaceAIConcierge.tsx` 承接。
- 登录页与营销页仍共享 `frontend/src/components/marketing/` 的部分视觉基线；公开登录页现改由 `frontend/src/components/login/` 目录承载，其中 `LoginExperience.tsx` 负责登录壳层、`LoginForm.tsx` 默认承接手机号验证码登录/自注册，用户名密码仅作为兼容入口，`LoginWorkflowVisual.tsx` 负责左侧场景、`loginScene.ts` / `loginMath.ts` 拆出展示配置与路径几何、`login.css` 负责登录页专属样式边界，`frontend/src/pages/login/LoginPage.tsx` 继续负责真实鉴权、错误态和 redirect 提示；未登录访问 `/` 会经 `frontend/src/router/index.tsx` 直接重定向到 `/login`，无显式 `redirect` 的成功登录现在默认进入 `/command-center`。
- 前端主包治理已切到“同步首屏最小集 + route/page-section lazy + 统一身份边界”模式：`frontend/src/router/index.tsx` 保留 `LoginPage / Layout` 这组同步入口，其余后台重页面通过 `React.lazy + Suspense` 懒加载；统一 fallback 在 `frontend/src/components/layout/LazyBoundary.tsx`，统一身份/权限边界在 `frontend/src/auth/RouteBoundary.tsx`。P0 公共壳冻结后，大模块 route 归属为：`/space` 归 Space lane，真实 `/project-launch` 是启动层入口，`/pmflow-os` 与 `/change-review / /structured-extraction / /memory-writeback-result / /execution-bridge / /release-growth` 归 Main Flow lane，`/me` 归 Account Settings lane，`/ai-config` 是客户空间 AI 使用设置，`/platform/*` 是 PMFlow 平台 AI Operations Console；空间管理入口使用 workspace role，平台运营入口使用 `platform_context.capabilities`，后端 JWT/RBAC 仍是最终校验；`/settings` 当前仅为 reserved route、尚未实现，新增必须由 Shell / Integration owner 串行处理。`/ai-steward` 只做 legacy redirect：`tab=create` 迁到 `/project-launch`，`tab=engine` 迁到 `/ai-config`，`tab=feedback-center` 有 `project_id` 时迁到 `/release-growth?projectId=<id>`、否则迁到 `/space`，其它 legacy tab 迁到 `/space`；导航不再暴露该入口。`/command-center` 保留免登录产品预览壳；`/space`、真实 `/project-launch`、主链 standalone 与 `/me` 均需登录；`/project-launch?demo=1` 或 `?dataSource=demo` 是唯一匿名启动台演示入口。`frontend/src/features/personal-space/` 作为登录后的空间层入口，承载继续推进、待我确认、AI 正在推进、暂存想法、草案箱与新建项目入口。`frontend/src/features/project-launch/` 真实模式默认调用 `pmflow-launch` draft/confirm API，创建成功态主动作跳转后端返回的 `/pmflow-os?projectId=<id>`，401/无 token 必须保存 pending input 并提示重新登录，不展示 Axios 原始错误；只有显式 demo 才启用本地 mock 状态机。`frontend/src/features/account-settings/` 作为登录后的 Account Settings 产品域，通过 `/me` 提供个人资料、默认语言、AI 回答深度、证据展示偏好、待确认/执行回写/发布门禁/失败提醒通知偏好和账户操作入口；该域通过 `frontend/src/api/accountSettings.ts` 建立前端合同，有 token 时优先调用已挂入 `backend/app/api/router.py` 的 `backend/app/api/account_settings_api/` `GET /account-settings/me` / `PUT /account-settings/me` 同步当前账号偏好，后端不可用时明确回落本机暂存，不修改 OAuth/JWT/auth core。`frontend/src/features/pmflow-os/` 作为登录后的真实项目产品域，通过 `PMFlowOsProvider` 在应用根部挂载共享 truth store，并提供 `CommandCenter / ChangeReview / WorkGraph / ExecutionBridge / ReleaseGrowth / TeamLayer / ProjectMemory / Account` 主入口；当前 PMFlow OS 页面已切到专属轻壳，桌面端默认隐藏旧 TopBar，并由 `frontend/src/features/pmflow-os/components/PMFlowOsFrame.tsx` 统一承接“左侧稳定导航 + 顶部上下文条 + 中央视图 + 右侧 AI 副驾”的全局骨架，同时承接项目内 `个人空间 / 当前项目名` 面包屑和项目切换器；账号退出登录由 `frontend/src/features/pmflow-os/components/AccountControls.tsx` 统一承接桌面头像下拉、退出确认与移动端 bottom sheet，正式应用壳移动端底部导航统一由 `frontend/src/features/pmflow-os/components/MobileBottomNav.tsx` 承接。
- PMFlow P8 Review Decision Loop 已由 `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 只提供 `getReviewDecisionNotificationPreference` 页面内提醒偏好；P8 未新增 route/nav，未接真实通知中心，不自动 assign reviewer 或 commit ChangeSet。
- `frontend/src/features/personal-space/PersonalSpacePage.tsx` 是空间首页视图层，`frontend/src/api/space.ts` 是空间工作面只读聚合 API：从 `projects` summary、PMFlow OS `truth-state`、`execution-summary` 与 `execution-capabilities` 生成 `nextActionQueue` 我的下一步队列、执行准备度、继续推进、待确认、发布关注、发布后反馈关注、下一轮迭代草稿关注、执行中 / AI 正在推进、暂存想法、草案箱、最近项目摘要；`frontend/src/features/personal-space/components/SpaceAIConcierge.tsx` 是空间级 AI 管家入口，只挂在 `/space`，通过空间上下文包调用现有 `/rag/ask` 并复用 QA 历史能力，回答范围限定在个人空间、跨项目下一步、待确认、执行中、草案、暂存想法和 AI 能力状态，真实写动作只给跳转或待确认建议。全局 `frontend/src/components/layout/Layout.tsx` 不再挂载旧 `FloatingQAChat` 悬浮球，普通后台页不显示无上下文聊天球。Space 的 `nextActionQueue` 按 AI extraction 生成的 ChangeSet 待确认、review attention、execution failed/blocked/delivery failed、release blocked / failed evidence、handoff consumed 但无后续 progress、feedback/revenue/ROI/compliance 信号待处理和 iteration draft 待确认排序，并只提供 `/change-review`、`/execution-bridge`、`/release-growth` 跳转。执行准备度只表达“我需要判断什么、AI 能继续做什么、工具链缺什么”，动作只跳 `/execution-bridge`、`/change-review`、`/release-growth` 或 `/team-layer`；缺少能力快照、工具连接、执行证据或阻塞数据时显示明确 empty/warning，不用传统技能表或 mock 数据冒充真实能力。Space P3 的 `releaseAttention` 优先消费 `truth-state.releases` 中由 release validation run 投影出的 release 状态与检查项，把“发布验证阻塞 / 发布验证待确认”显示到 `/space`，没有发布验证投影时才回落到 `execution-summary.releaseGate` 的发布候选或发布门禁阻塞；Space P4/P5 的 `feedbackAttention` 只读消费 `execution-summary.releaseSignals`，把发布后 feedback、revenue、ROI、compliance、iteration recommendation 与已生成的下一轮 ChangeSet draft 关注项显示到 `/space`。发布验证、发布后信号或下一轮 draft 缺失时显示明确空态，不虚构验证、反馈、收入、ROI、合规、建议或 ChangeSet draft 结果。项目主动作进入 `/pmflow-os?projectId=<id>`，待确认项进入 `/change-review?projectId=<id>&changeSetId=<id>`，发布关注和发布后反馈关注项进入 `/release-growth?projectId=<id>`，下一轮 draft 关注项进入 `/change-review?projectId=<id>&changeSetId=<id>`，执行中、执行失败和回写失败项进入 `/execution-bridge?projectId=<id>`；暂存想法通过真实 `GET /space/saved-ideas` 聚合，缺数据时显示 empty/warning，不使用 mock 数据冒充真实内容；移动端为空间首页独立 App 布局，不直接压缩桌面卡片，并保留最近项目区块；`frontend/src/pages/PersonalSpacePage.tsx` 是薄入口。该域只表达个人空间和主流程导航，不做团队空间强切换、企业组织管理、Project Memory 写入、ChangeSet 状态写入、PMFlowApproval 写入、ProgressEvent 写入、ReleaseValidationRun 写入、FeedbackIngest 写入、RevenueEvent 写入、ROISnapshot 写入、ComplianceCheckRun 写入或发布执行。
- 前端主包治理已切到“同步首屏最小集 + route/page-section lazy”模式：`frontend/src/router/index.tsx` 保留 `LoginPage / Layout` 这组同步入口，其余后台重页面通过 `React.lazy + Suspense` 懒加载；统一 fallback 在 `frontend/src/components/layout/LazyBoundary.tsx`。P0 公共壳冻结后，大模块 route 归属为：`/space` 归 Space lane，`/project-launch` 是启动层入口，`/pmflow-os` 与 `/command-center / /change-review / /execution-bridge / /release-growth` 归 Main Flow lane，`/me` 归 Account Settings lane，`/settings` 当前仅为 reserved route、尚未实现，新增必须由 Shell / Integration owner 串行处理。`frontend/src/features/personal-space/` 作为空间层入口，通过登录后的 `/space` 提供空间入口，承载继续推进、待我确认、AI 正在推进、暂存想法、草案箱与新建项目入口。`frontend/src/features/project-launch/` 作为首次进入页 / 新项目启动台产品域，通过登录后的真实 `/project-launch` 提供启动入口（显式 `?demo=1` 或 `?dataSource=demo` 可匿名演示）；Phase B 后默认调用真实 `pmflow-launch` draft/confirm API，创建成功态主动作跳转后端返回的 `/pmflow-os?projectId=<id>`，只有显式 `?demo=1` 或 `?dataSource=demo` 才启用本地 mock 状态机。`frontend/src/features/account-settings/` 作为 Account Settings 产品域，通过 `/me` 提供个人资料、默认语言、AI 回答深度、证据展示偏好、待确认/执行回写/发布门禁/失败提醒通知偏好和账户操作入口；该域通过 `frontend/src/api/accountSettings.ts` 建立前端合同，有 token 时优先调用已挂入 `backend/app/api/router.py` 的 `backend/app/api/account_settings_api/` `GET /account-settings/me` / `PUT /account-settings/me` 同步当前账号偏好，后端不可用时明确回落本机暂存，不修改 OAuth/JWT/auth core。`frontend/src/features/pmflow-os/` 作为新产品域，通过 `PMFlowOsProvider` 在应用根部挂载共享 truth store，并提供 `CommandCenter / ChangeReview / WorkGraph / ExecutionBridge / ReleaseGrowth / TeamLayer / ProjectMemory / Account` 主入口；当前 PMFlow OS 页面已切到专属轻壳，桌面端默认隐藏旧 TopBar，并由 `frontend/src/features/pmflow-os/components/PMFlowOsFrame.tsx` 统一承接“左侧稳定导航 + 顶部上下文条 + 中央视图 + 右侧 AI 副驾”的全局骨架，同时承接项目内 `个人空间 / 当前项目名` 面包屑和项目切换器；`ChangeReviewPage.tsx` 现在可以请求审查、通过、要求修改或拒绝当前变更集，并展示审查状态、审查意见与高风险审批门禁；`TeamLayerPage.tsx` 现在消费 `ProjectTruthState.reviewerRouting(status/summary/items)`、`ProjectTruthState.feed` 与 `execution-capabilities`，以 `团队动态 / 决策台 / 角色收件箱 / 智能体工位 / AI 副驾` 组织团队协作态势，展示待审变更责任路由、审查人建议、审查状态、证据数量、执行单元信号和容量调度；动作只跳 `/change-review?projectId=<id>&changeSetId=<id>` 或下方容量区，不自动分派、不自动审查、不写 Project Memory。账号退出登录由 `frontend/src/features/pmflow-os/components/AccountControls.tsx` 统一承接桌面头像下拉、退出确认与移动端 bottom sheet，`frontend/src/features/pmflow-os/pages/AccountPage.tsx` 提供 `/me` 入口并委托 Account Settings 域渲染设置页；正式应用壳移动端底部导航统一由 `frontend/src/features/pmflow-os/components/MobileBottomNav.tsx` 承接，固定为 `空间 / 指挥台 / 待确认 / 动态 / 我的`，其中 `动态` 当前仍是 `/command-center` 占位。`/command-center` 额外提供免登录产品预览壳，`/pmflow-os` 是真实项目上下文 alias。主视觉按 `#2463EB + 白色` 的 Linear-like 高密度原型展开。`UsersPage` 把创建/删除/重置/导入/批量分配对话框拆为按需 chunk，`UserSkillsPage` 与 `WorkloadDetailPage` 的图表也分别拆到了 `frontend/src/pages/user-skills/components/UserSkillsRadarPanel.tsx` 与 `frontend/src/pages/workload-detail/components/WorkloadTrendChart.tsx`。
- `frontend/src/features/personal-space/PersonalSpacePage.tsx` 是空间首页视图层，`frontend/src/api/space.ts` 是空间工作面只读聚合 API：从 `projects` summary、PMFlow OS `truth-state`、`execution-summary` 与 `execution-capabilities` 生成 `nextActionQueue` 我的下一步队列、执行准备度、继续推进、待确认、发布关注、发布后反馈关注、下一轮迭代草稿关注、执行中 / AI 正在推进、暂存想法、草案箱、最近项目摘要；Space 的 `nextActionQueue` 按 AI extraction 生成的 ChangeSet 待确认、review attention、execution failed/blocked/delivery failed、release blocked / failed evidence、handoff consumed 但无后续 progress、feedback/revenue/ROI/compliance 信号待处理和 iteration draft 待确认排序，并只提供 `/change-review`、`/execution-bridge`、`/release-growth` 跳转；Space P7 新增 `review_attention`，只读消费 `truth-state.reviewerRouting`，把高风险待我审、`request_changes / rejected` 后待处理、`reviewer_missing` warning 与普通 pending review 排入“我的下一步”，待审/退回/拒绝项只跳 `/change-review?projectId=<id>&changeSetId=<id>`，reviewer 缺失 warning 只跳已有 `/team-layer?projectId=<id>`。执行准备度只表达“我需要判断什么、AI 能继续做什么、工具链缺什么”，动作只跳 `/execution-bridge`、`/change-review`、`/release-growth` 或 `/team-layer`。Space P3 的 `releaseAttention` 优先消费 `truth-state.releases` 中由 release validation run 投影出的 release 状态与检查项，把“发布验证阻塞 / 发布验证待确认”显示到 `/space`，没有发布验证投影时才回落到 `execution-summary.releaseGate` 的发布候选或发布门禁阻塞；Space P4/P5 的 `feedbackAttention` 只读消费 `execution-summary.releaseSignals`，把发布后 feedback、revenue、ROI、compliance、iteration recommendation 与已生成的下一轮 ChangeSet draft 关注项显示到 `/space`。reviewerRouting、execution-capabilities、发布验证、发布后信号或下一轮 draft 缺失时显示明确空态，不虚构 reviewer、审查意见、待审 ChangeSet、工具连接、执行能力、验证、反馈、收入、ROI、合规、建议或 ChangeSet draft 结果。项目主动作进入 `/pmflow-os?projectId=<id>`，待确认项进入 `/change-review?projectId=<id>&changeSetId=<id>`，发布关注和发布后反馈关注项进入 `/release-growth?projectId=<id>`，下一轮 draft 关注项进入 `/change-review?projectId=<id>&changeSetId=<id>`，执行中、执行失败和回写失败项进入 `/execution-bridge?projectId=<id>`；暂存想法通过真实 `GET /space/saved-ideas` 聚合，缺数据时显示 empty/warning，不使用 mock 数据冒充真实内容；移动端为空间首页独立 App 布局，不直接压缩桌面卡片，并保留最近项目区块；`frontend/src/pages/PersonalSpacePage.tsx` 是薄入口。该域只表达个人空间和主流程导航，不做团队空间强切换、企业组织管理、Project Memory 写入、ChangeSet 状态写入、PMFlowApproval 写入、ProgressEvent 写入、ReleaseValidationRun 写入、FeedbackIngest 写入、RevenueEvent 写入、ROISnapshot 写入、ComplianceCheckRun 写入或发布执行。
- `frontend/src/features/personal-space/SpaceCollectionPages.tsx` 承接空间首页红框区块的二级页面：`/space/ideas` 是暂存想法收集箱，支持状态筛选、搜索、补充、归档与转 Project Launch 草案；`/space/drafts` 是草案箱 / 待确认事项页，支持按待确认、信息不足、冲突、已确认、挂起筛选并回主流程确认。空间首页只预览暂存想法、草案箱和最近项目各少量条目；最近项目完整查看复用 `/space/projects?view=recent`，`ProjectsPage` 内提供“全部 / 最近 / 待处理 / AI 进行中 / 已归档”筛选，不单独新增最近项目页。
- 旧独立收件页已物理删除，`/inbox` route 和侧边栏入口已退场；旧 AI PMO `waiting_manual / draft_pending_confirm` 不再通过独立页面承载，而由 `frontend/src/api/space.ts` 作为 legacy adapter 只读接入 `/space` 的“我的下一步”和草案箱。`missing_project_scope` 只允许在 Space 选择项目后复用 `POST /ai-pmo/work-items/{id}/decision` 继续既有审计链，不新增旁路接口；底层 `notifications` primitive 暂留为未来 in-app reminder/偏好消费基础，不作为真实通知中心暴露。
- 前端主包治理已切到“同步首屏最小集 + route/page-section lazy”模式：`frontend/src/router/index.tsx` 保留 `LoginPage / Layout` 这组同步入口，其余后台重页面通过 `React.lazy + Suspense` 懒加载；统一 fallback 在 `frontend/src/components/layout/LazyBoundary.tsx`。P0 公共壳冻结后，大模块 route 归属为：`/space` 归 Space lane，`/project-launch` 是启动层入口，`/pmflow-os` 与 `/command-center / /change-review / /execution-bridge / /release-growth` 归 Main Flow lane，`/me` 归 Account Settings lane，`/settings` 当前仅为 reserved route、尚未实现，新增必须由 Shell / Integration owner 串行处理。`frontend/src/features/personal-space/` 作为空间层入口，通过登录后的 `/space` 提供空间入口，承载继续推进、待我确认、AI 正在推进、暂存想法、草案箱与新建项目入口。`frontend/src/features/project-launch/` 作为首次进入页 / 新项目启动台产品域，通过登录后的真实 `/project-launch` 提供启动入口（显式 `?demo=1` 或 `?dataSource=demo` 可匿名演示）；Phase B 后默认调用真实 `pmflow-launch` draft/confirm API，创建成功态主动作跳转后端返回的 `/pmflow-os?projectId=<id>`，只有显式 `?demo=1` 或 `?dataSource=demo` 才启用本地 mock 状态机。`frontend/src/features/account-settings/` 作为 Account Settings 产品域，通过 `/me` 提供个人资料、默认语言、AI 回答深度、证据展示偏好、待确认/执行回写/发布门禁/失败提醒通知偏好和账户操作入口；该域通过 `frontend/src/api/accountSettings.ts` 建立前端合同，有 token 时优先调用已挂入 `backend/app/api/router.py` 的 `backend/app/api/account_settings_api/` `GET /account-settings/me` / `PUT /account-settings/me` 同步当前账号偏好，后端不可用时明确回落本机暂存，不修改 OAuth/JWT/auth core。`frontend/src/features/pmflow-os/` 作为新产品域，通过 `PMFlowOsProvider` 在应用根部挂载共享 truth store，并提供 `CommandCenter / ChangeReview / WorkGraph / ExecutionBridge / ReleaseGrowth / TeamLayer / ProjectMemory / Account` 主入口；当前 PMFlow OS 页面已切到专属轻壳，桌面端默认隐藏旧 TopBar，并由 `frontend/src/features/pmflow-os/components/PMFlowOsFrame.tsx` 统一承接“左侧稳定导航 + 顶部上下文条 + 中央视图 + 右侧 AI 副驾”的全局骨架，同时承接项目内 `个人空间 / 当前项目名` 面包屑和项目切换器；`TeamLayerPage.tsx` 现在消费 `ProjectTruthState.reviewerRouting(status/summary/items)`、`ProjectTruthState.feed` 与 `execution-capabilities`，以 `团队动态 / 决策台 / 角色收件箱 / 智能体工位 / AI 副驾` 组织团队协作态势，展示待审变更责任路由、审查人建议、审查状态、证据数量、执行单元信号和容量调度；决策台与待审路由卡片按真实条目密度排布，1-2 条不强行占 3 列，操作按钮不挤压正文宽度；动作只跳 `/change-review?projectId=<id>&changeSetId=<id>` 或下方容量区，不自动分派、不自动审查、不写 Project Memory；账号退出登录由 `frontend/src/features/pmflow-os/components/AccountControls.tsx` 统一承接桌面头像下拉、退出确认与移动端 bottom sheet，`frontend/src/features/pmflow-os/pages/AccountPage.tsx` 提供 `/me` 入口并委托 Account Settings 域渲染设置页；正式应用壳移动端底部导航统一由 `frontend/src/features/pmflow-os/components/MobileBottomNav.tsx` 承接，固定为 `空间 / 指挥台 / 待确认 / 动态 / 我的`，其中 `动态` 当前仍是 `/command-center` 占位。`/command-center` 额外提供免登录产品预览壳，`/pmflow-os` 是真实项目上下文 alias。主视觉按 `#2463EB + 白色` 的 Linear-like 高密度原型展开。`UsersPage` 把创建/删除/重置/导入/批量分配对话框拆为按需 chunk，`UserSkillsPage` 与 `WorkloadDetailPage` 的图表也分别拆到了 `frontend/src/pages/user-skills/components/UserSkillsRadarPanel.tsx` 与 `frontend/src/pages/workload-detail/components/WorkloadTrendChart.tsx`。
- `backend/app/api/ai_readiness_api/` + `backend/app/services/ai_readiness_service.py` + `frontend/src/api/aiReadiness.ts` + `frontend/src/features/ai-readiness/` 是空间级 AI 可用状态与 Project Launch 草案门禁合同：后端 `GET /ai-readiness/project-launch` 从平台运行租户供应商配置、published active `structured` 槽、Project Launch scene registry、结构化能力证据和租户最近 24h `pmflow_launch_draft_v1` 调用日志推导 `ready / blocked / recovering / unknown`；单次最近生成失败只作为平台 warning，若 24h 内已有成功且连续失败少于 3 次，用户端仍保持可生成，连续失败达到阈值才进入 recovering；`POST /ai-readiness/project-launch/check` 仅允许 platform AI Ops 触发真实结构化 smoke，复用 Project Launch 草案生成链但不写 draft/project/task/Project Memory；前端 `useAIReadiness()` 默认消费后端结果，本机 localStorage 只保留 test 或 `VITE_AI_READINESS_LOCAL_OVERRIDE=true` 覆盖。`/space` 顶部与首屏、真实 `/project-launch`、项目级 `ResponsiveAICopilot`、`/ai-config?tab=setup` 和 `/platform/*` 共用该合同；用户端默认只消费客户可理解的业务影响、保护规则和可继续动作，空间负责人额外看到空间 AI 状态、团队策略和工具连接入口，平台 AI Ops 只有在显式诊断卡或 `/platform/*` 才看到 cause、raw status、供应商、路由、诊断、smoke 和 CTA。
- `frontend/src/features/project-launch/types.ts`、`mockData.ts`、`useProjectLaunchState.ts` 是新项目启动台状态层；默认真实模式通过 `frontend/src/api/pmflowLaunch.ts` 创建 `pmflow_launch_draft_jobs`、轮询 job 状态、拿到草案后再确认创建真实项目，API 失败进入明确失败态，不静默 fallback 成 mock 成功；`mockData.ts` 仅在显式 `?demo=1` 或 `?dataSource=demo` 下作为演示状态机使用，真实模式的步骤摘要、操作流、审查建议、附件引用和计数从当前输入、job 状态、真实草案、warnings/evidence 派生。`components/LaunchShell.tsx` 负责桌面/移动分流，桌面端复用 `frontend/src/features/personal-space/components/SpaceChrome.tsx` 的空间左侧栏和顶部条，并通过真实补充输入弹层提交 `merge_supplement` revision，禁止硬编码追加示例文本；`SpaceSidebar` 承载稳定空间目的地（空间首页、暂存想法、草案箱、所有项目和管理配置），不展示最近项目、待我确认或 AI 正在推进等首页工作台区块项；真实模式下若 `AIReadiness.canGenerateProjectDraft=false`，优先渲染 `AISetupRequiredPanel`，普通成员只记录想法，空间负责人查看空间 AI 可用状态，平台 AI Ops 才进入平台 AI 能力处理，不提供空项目创建入口；低信息输入由后端 `input_needs_more_info` 422 拦截并进入补充输入失败态。`LaunchCanvases.tsx` 和 `MobileLaunchLayout.tsx` 承接高保真图中的意图输入、AI 工作、人类确认、草案修改、生成失败、创建成功过渡与移动端 bottom sheet 交互。
- `frontend/src/features/pmflow-os/store.tsx` 当前是 PMFlow OS 共享 truth store：`?projectId=<id>` 时通过 React Query 调用 `frontend/src/api/pmflowOs.ts` 读取真实 `GET /pmflow-os/projects/{project_id}/truth-state` 与 `GET /pmflow-os/projects/{project_id}/execution-summary`，真实模式下项目内 `sendMessage` 会写 thread message 并触发后端真实 AI extraction；显式 `proposed_items` extraction、ChangeItem `accept/edit/defer`、ChangeSet commit、review decision、Execution Handoff create/consume、execution progress writeback、release validation run create、release feedback ingest、单条 iteration recommendation -> ChangeSet draft 与同组 iteration recommendation 批量 -> ChangeSet draft 均调用 `/pmflow-os` 后端并 refetch；只有显式 `?demo=1` 或 `?dataSource=demo` 时才启用本地 mock 演示状态机。真实读取/动作失败会进入错误/空态，不静默 fallback 成 mock 成功；AI extraction 失败显示“结构化失败/待补充”，不创建模板 ChangeSet。
- `frontend/src/features/pmflow-os/store.tsx` 仍保留演示用项目内 AI 结构化闭环状态机：`command_idle / ai_extracting / extraction_ready / review_open / writeback_success`。`frontend/src/features/pmflow-os/pages/StructuredExtractionPage.tsx` 是本轮结构化提取页，也是结构化读取检查层：从指挥台进入时主动作进入待确认或继续补充；从 `ChangeReviewPage.tsx` 进入时通过 `origin=change_review / returnTo=change_review / changeSetId / itemId` 保留审查上下文，主动作返回待确认队列，补充证据才回指挥台；已 committed 的轮次显示为结构化写入快照并转向项目记忆或新变更链路。`ChangeReviewPage.tsx` 是决策与待确认中心，真实模式下顶部识别统计、待确认列表与右侧 AI 副驾评估都只消费后端 `changeSets / changeItems / evidence`，没有真实待审项时显示空态，禁止用 demo 审查项补位；确认写入 Project Memory 前，`pending_review / accepted / edited / deferred` ChangeItem 均可继续 accept/edit/defer，只有 `committed / skipped` 或关闭轮次不可再操作；`MemoryWritebackResultPage.tsx` 是项目记忆写入结果页，`WorkGraphPage.tsx` 是项目工作台关系总览与对象投影视图，`ExecutionBridgePage.tsx` 是执行桥上下文包、交接按钮、运行端领取确认、PR/测试与回写状态页；`ReleaseGrowthPage.tsx` 真实模式读取 `execution-summary.releaseGate`、`latestValidationRun` 与 `releaseSignals`，从 branch、commit、PR、test、failed evidence 展示 `可发布 / 阻塞 / 需要人工确认 / 缺少证据` 判断、阻塞原因、下一步动作、发布验证记录和发布后 feedback/revenue/ROI/compliance/recommendation 信号，缺少发布后信号时显示 empty/warning，不执行发布命令、不展示 mock 发布结果；页面可展示 recommendation quality grouping，把真实 recommendation 单条或同组批量生成下一轮待确认 ChangeSet draft，生成后仍进入 Change Review accept/edit/defer，不自动 commit、不写 Project Memory、不创建正式任务；`ChangeReviewPage.tsx` 会展示 `iteration_recommendation_group` evidence 的来源组、feedback 数、recommendation 数、风险、影响和审查优先级；同时读取 Account notification preference helper，用 `releaseGate` 偏好控制发布门禁强调提醒，用 `failureAlert` 偏好控制失败强调提醒，偏好关闭时只静默提醒表达强度，不隐藏 release evidence、阻塞原因、审计状态、validation run 或 releaseSignals；静态发布/增长原型只保留在显式 demo 模式。A3 已接入后端 truth-state，C1 已接入真实 message/extraction/review 状态机，C2 已接入真实 ChangeSet commit，Phase D 已接入真实 execution-summary/dev-sync，D.2 已接入 `POST /execution-handoffs` 创建 PromptPackage + handoff_created progress event，P1 已接入 `POST /execution-handoffs/{prompt_package_id}/consume` 创建 handoff_consumed progress event 并把 execution status 投影为 coding，Release Growth P1 已接入 execution evidence gate，Release Validation P1 已接入 `POST /release-validation-runs` 创建 `ReleaseValidationRun` 快照，Release Feedback P1 已接入 `POST /release-feedback-ingests` 写入 `FeedbackIngest` 并生成 `IterationRecommendation`，Iteration Loop P1 已接入 `POST /iteration-recommendations/{recommendation_id}/change-set-drafts` 把 recommendation 回流到 Change Review，Iteration Loop P2 已接入 `POST /iteration-recommendation-groups/{group_key}/change-set-drafts` 并在 `releaseSignals.recommendationGroups` 暴露分组/去重/风险/影响合同；真实 AI extraction 已接入独立 `change_review` protected scene、`pmflow_change_review_extraction_v1` 运行合同、`PROMPT_PMFLOW_CHANGE_REVIEW_EXTRACTION` Prompt 资产与后端 `llm_service.generate_structured_object`，成功时生成 open ChangeSet、pending_review ChangeItems 与 thread message evidence，失败时 fail-closed，不把 mock 当真实失败 fallback，也不复用 Project Launch draft prompt/function。`ProjectMemoryPage.tsx` 在真实模式下展示后端 `truth_nodes + semantic_facts` 的 `projectMemory` 投影，accepted/edited ChangeItem 只有 commit 成功后才进入 Project Memory。`frontend/src/features/pmflow-os/components/ProjectStructuredLoop.tsx` 提供 `StatusLabel / EvidenceSnippet / ObjectChangeCard / ProjectConversationPanel / StructuredExtractionPanel / ProjectAICopilotPanel` 等闭环组件，并复用契约化 `InlineNotice` 表达“未确认不得写入”的局部提示。
- Project Knowledge Hub 读模型由 `GET /pmflow-os/projects/{project_id}/project-memory/overview`、`items`、`items/{item_id}`、`assets`、`context-packs`、`writebacks` 承载，后端在 `backend/app/services/pmflow_os_projection_service.py` 从 `truth_nodes / tasks / semantic_facts / pmflow_evidence_links / pmflow_thread_messages / pmflow_change_sets / pmflow_change_items` 聚合首页雷达、全部记忆、项目资产、上下文包和写入版本记录。前端对应 `ProjectMemoryPage.tsx`、`ProjectMemoryCollectionPages.tsx` 与 `projectMemoryUtils.ts`：列表时间使用短格式，抽屉显示完整时间和北京时间；首页卡片与二级列表单条点击打开右侧详情抽屉，展示来源证据、影响对象和 AI 执行动作跳转；全部记忆支持类型、阶段、来源、状态、搜索筛选。该读模型只读，资产可自动索引，进入项目真相层仍必须经过 Change Review 或可信规则确认。
- `frontend/src/features/account-settings/AccountSettingsPanel.tsx` 是 `/me` 设置页实现：桌面端为个人资料摘要 + 分区设置面板，移动端为分组列表 + `MobileBottomSheet` 编辑；当前覆盖个人资料、默认语言、AI 回答深度、证据展示偏好、待确认、执行回写、发布门禁和失败提醒通知偏好，并在通知偏好区展示页面内提醒消费说明、提醒强度和证据展示配置。`frontend/src/api/accountSettings.ts` 是前端合同层；有 token 时优先调用 `backend/app/api/account_settings_api/`，失败时回落浏览器本机暂存；P2 新增 `shouldShowAccountNotification` 与 `getAccountNotificationConsumption`，将四类通知偏好映射为本地 UI 的待确认、Execution Bridge、Release/Growth 和失败提醒显示/静默状态；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，并返回 `spaceReadable / evidencePolicy / reminderPolicy` 供 Main Flow 与 Space 消费；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，并声明 reviewerRouting、approval、evidence、audit state 均必须保留。该合同只控制页面内提醒表达，不代表邮件、桌面推送或系统通知中心已接入；偏好关闭也不得隐藏业务证据、reviewerRouting、approval、recommendation、ChangeSet、执行状态或审计状态。`backend/app/schemas/account_settings.py` 定义账号偏好合同，`backend/app/services/account_settings_service.py` 当前复用既有 `integrations` 表按 `tenant_id + user_id` 保存 `account_settings_preferences` 配置包，`backend/app/api/router.py` 已挂载该 API；未改用户表、OAuth/JWT/auth core 或 PMFlow OS truth store。
- `frontend/src/features/pmflow-os/store.tsx` 当前是 PMFlow OS 共享 truth store：`?projectId=<id>` 时通过 React Query 调用 `frontend/src/api/pmflowOs.ts` 读取真实 `GET /pmflow-os/projects/{project_id}/truth-state` 与 `GET /pmflow-os/projects/{project_id}/execution-summary`，真实模式下项目内 `sendMessage` 会写 thread message 并触发后端真实 AI extraction；显式 `proposed_items` extraction、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 均调用 `/pmflow-os` 后端并 refetch；AI feedback 写入 `pmflow_ai_feedback_events`，在 `truth-state.aiFeedback` 恢复当前用户选择，并由后端按 `prompt_key` 生成待复核 `JudgeRun / OptimizerCandidate` 质量优化候选，用户改回赞同时挂起此前候选，Prompt Asset quality summary 会聚合 PMFlow 反馈与优化候选；只有显式 `?demo=1` 或 `?dataSource=demo` 时才启用本地 mock 演示状态机。真实读取/动作失败会进入错误/空态，不静默 fallback 成 mock 成功；AI extraction 失败显示“结构化失败/待补充”，不创建模板 ChangeSet。
- `frontend/src/features/pmflow-os/store.tsx` 仍保留演示用项目内 AI 结构化闭环状态机：`command_idle / ai_extracting / extraction_ready / review_open / writeback_success`。`frontend/src/features/pmflow-os/pages/StructuredExtractionPage.tsx` 是本轮结构化提取页，`ChangeReviewPage.tsx` 是决策与待确认中心，真实模式下顶部识别统计、待确认列表与右侧 AI 副驾评估都只消费后端 `changeSets / changeItems / evidence`，没有真实待审项时显示空态，禁止用 demo 审查项补位；`MemoryWritebackResultPage.tsx` 是项目记忆写入结果页，`WorkGraphPage.tsx` 是项目工作台关系总览与对象投影视图，`ExecutionBridgePage.tsx` 是执行桥上下文包、交接按钮、运行端领取确认、PR/测试与回写状态页；`ReleaseGrowthPage.tsx` 真实模式读取 `execution-summary.releaseGate`、`latestValidationRun` 与 `releaseSignals`，从 branch、commit、PR、test、failed evidence 展示 `可发布 / 阻塞 / 需要人工确认 / 缺少证据` 判断、阻塞原因、下一步动作、发布验证记录和发布后 feedback/revenue/ROI/compliance/recommendation 信号，缺少发布后信号时显示 empty/warning，不执行发布命令、不展示 mock 发布结果；页面可把真实 recommendation 生成下一轮待确认 ChangeSet draft，生成后仍进入 Change Review accept/edit/defer，不自动 commit、不写 Project Memory、不创建正式任务；同时读取 Account notification preference helper，用 `releaseGate` 偏好控制发布门禁强调提醒，用 `failureAlert` 偏好控制失败强调提醒，偏好关闭时只静默提醒表达强度，不隐藏 release evidence、阻塞原因、审计状态、validation run 或 releaseSignals；静态发布/增长原型只保留在显式 demo 模式。A3 已接入后端 truth-state，C1 已接入真实 message/extraction/review 状态机，C2 已接入真实 ChangeSet commit，Phase D 已接入真实 execution-summary/dev-sync，D.2 已接入 `POST /execution-handoffs` 创建 PromptPackage + handoff_created progress event，P1 已接入 `POST /execution-handoffs/{prompt_package_id}/consume` 创建 handoff_consumed progress event 并把 execution status 投影为 coding，Release Growth P1 已接入 execution evidence gate，Release Validation P1 已接入 `POST /release-validation-runs` 创建 `ReleaseValidationRun` 快照，Release Feedback P1 已接入 `POST /release-feedback-ingests` 写入 `FeedbackIngest` 并生成 `IterationRecommendation`，Iteration Loop P1 已接入 `POST /iteration-recommendations/{recommendation_id}/change-set-drafts` 把 recommendation 回流到 Change Review；真实 AI extraction 已接入后端 `llm_service.generate_structured_object` 与 PMFlow prompt/config/routing 层，成功时生成 open ChangeSet、pending_review ChangeItems 与 thread message evidence，失败时 fail-closed，不把 mock 当真实失败 fallback。`ProjectMemoryPage.tsx` 在真实模式下展示后端 `truth_nodes + semantic_facts` 的 `projectMemory` 投影，accepted/edited ChangeItem 只有 commit 成功后才进入 Project Memory。`frontend/src/features/pmflow-os/components/ProjectStructuredLoop.tsx` 提供 `StatusLabel / EvidenceSnippet / ObjectChangeCard / ProjectConversationPanel / StructuredExtractionPanel / ProjectAICopilotPanel` 等闭环组件，并复用契约化 `InlineNotice` 表达“未确认不得写入”的局部提示。
- PMFlow OS 后端入口位于 `backend/app/api/pmflow_os_api/`，projection service 位于 `backend/app/services/pmflow_os_projection_service.py`，Execution Capability Graph 只读聚合位于 `backend/app/services/team_execution_capability_service.py`，Change Review / commit / review decision 服务位于 `backend/app/services/pmflow_change_review_service.py`，AI feedback 服务位于 `backend/app/services/pmflow_ai_feedback_service.py`，Pydantic 合同位于 `backend/app/schemas/pmflow_os.py`；当前聚合 `truth_nodes / tasks / semantic_facts / ai_project_control / dev_sync`，`Thread / Message` 来自 `pmflow_threads / pmflow_thread_messages`，`ChangeSet / ChangeItem / Approval / EvidenceLink` 来自 `backend/app/models/pmflow_change_review.py` 对应真实表，ChangeSet committer 持久化在 `pmflow_change_sets.committed_by` 并由 `truth-state.lastWritebackBy`、commit result 与 Project Memory writebacks 投影，AI feedback 来自 `pmflow_ai_feedback_events` 并归因到 `scene_key / prompt_key / prompt_release_id / runtime_profile_id`。负反馈只创建待复核 `JudgeRun / OptimizerCandidate`，由 Prompt 资产运营页展示，不直接修改 active prompt 或自动发布；用户改回赞同时自动挂起此前候选。`GET /pmflow-os/projects/{project_id}/execution-capabilities` 返回 `executionModes / personalReadiness / teamSignals / warnings`，复用用户、项目成员、技能绑定、负载、reviewer routing、execution summary 与 workspace binding 数据，只给建议、阻塞和解释，不自动分派任务、不自动请求审查、不写 ChangeSet；缺 repo、工具、测试命令、reviewer 或证据时返回 warning、`blocked` 或 `needs_human_judgement`，不虚构能力结论。`ProjectTruthState.reviewerRouting` 是 Team layer 的 reviewer routing + decision 读模型：从 open/pending ChangeSet、待审 item 风险、跨对象类型、`iteration_recommendation` evidence、项目成员与 `OWNER / REVIEWER` 角色推导 `{status, warningCode, summary, items}`；item 内含 `sourceType / riskLevel / priority / suggestedReviewer / fallbackReviewerRole / targetUrl / reviewDecision / approvalState / requestedAt / decidedAt / decisionReason`；缺成员、缺角色或缺证据时 fail-closed 给 warning，不虚构 reviewer。P8 新增 `POST /pmflow-os/change-sets/{change_set_id}/review-decisions`，支持 `request_review / approve / request_changes / reject`，`approve / request_changes / reject` 写 `PMFlowApproval` 审计，high-risk approve 后才满足 C2 approval gate，所有 decision 都不自动 commit。C1 已实现 message、真实 AI extraction、显式 `proposed_items` extraction、ChangeSet detail、ChangeItem `accept/edit/defer` 与 AI feedback；真实 AI extraction 失败返回 `ai_extraction_failed / extraction_evidence_insufficient` 且不创建模板假结果；C2 backend/frontend 已实现 `POST /pmflow-os/change-sets/{change_set_id}/commit` 与真实模式前端接入，默认 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`，校验 task/repo project 边界，生成/复用 `PromptPackage(package_kind='execution_handoff')` 并写 `ProgressEvent(event_type='handoff_created')` 起点；P1 已实现 `POST /pmflow-os/projects/{project_id}/execution-handoffs/{prompt_package_id}/consume`，校验 execution handoff package 后更新 `PromptPackage.package_payload.latest_handoff.handoff_state=consumed` 并写 `ProgressEvent(event_type='handoff_consumed', derived_task_status='coding')`；Release Growth P1 在 `ExecutionSummaryProjection.releaseGate` 中从 `ProgressEvent` 推导发布门禁状态，失败事件 fail-closed 阻塞发布，无证据返回 empty/warning；Release Validation P1 新增 `POST /pmflow-os/projects/{project_id}/release-validation-runs`，复用现有 `ReleaseValidationRun` 模型固化当前 `releaseGate` 快照、人工决策、证据、阻塞原因和下一步动作，并在 `releaseGate.latestValidationRun` 返回最新记录；Release Feedback P1 新增 `POST /pmflow-os/projects/{project_id}/release-feedback-ingests`，复用现有 `FeedbackIngest / IterationRecommendation`，在 `ExecutionSummaryProjection.releaseSignals` 中返回真实发布后 feedback、revenue event、ROI snapshot、compliance check 和 iteration recommendation 读模型；Release Business Signal Loop P1 已把 RevenueEvent、ROISnapshot 与 ComplianceCheckRun 纳入 `ExecutionSummaryProjection.releaseSignals` 风险读模型；Iteration Loop P1 新增 `POST /pmflow-os/projects/{project_id}/iteration-recommendations/{recommendation_id}/change-set-drafts`，把真实 recommendation 转为 open ChangeSet、pending_review Requirement/Task/Risk/Decision items 与 `iteration_recommendation` evidence，重复调用复用既有 draft 并在 `releaseSignals` 标记 `changeSetCreated/changeSetId`；这些步骤都不直接执行本机命令、真实发布命令、外部支付、真实推送、自动 Project Memory commit 或正式任务创建；`ModelDecision / MetricSignal` 在 C2 V1 仍 fail-closed。
- 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` 与 `backend/app/schemas/pmflow_os.py` 承载；API 位于 `backend/app/api/pmflow_os_api/`：`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` 只写 override 审计，`GET /pmflow-os/projects/{project_id}/capacity-overrides` 返回调整记录；`execution-capabilities` 同步返回 `adaptiveCapacitySummary`。该模型不持久化每日计划快照，不写固定基线，不自动分配任务、不请求审查、不写 ChangeSet；旧 `UserWorkload.workload_ratio` 仅保留为成本参考信号。
- PMFlow Launch 后端 Phase B 创建链位于 `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` 只写 `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`，并把 `launch_draft_id / thread_id / thread_message_id` 写入正式对象 metadata。旧 `POST /ai-steward/project-from-text` 仅由 `backend/app/api/legacy_ai_steward_api.py` 保留 410 响应一个版本周期，且该模块在 lean profile 下也会挂载；禁止绕过草案确认直接创建正式项目。
- `frontend/src/features/pmflow-os/components/ChangeReviewGroup.tsx`、`WorkbenchPanel.tsx`、`ExecutionBridgeCards.tsx`、`PMFlowOsFrame.tsx`、`AccountControls.tsx`、`FeedbackPrimitives.tsx` 是高保真原型新增的行为组件层：分别承载变更 diff 审查块、工作台对象卡组、执行桥上下文/日志卡片、全局上下文条与 AI 副驾、账号菜单/退出登录确认交互，以及 `PageBanner / InlineNotice / HumanDecisionBar / ConfirmDialog / MobileBottomSheet` 这组提示、提醒、确认与移动端 bottom sheet 基础组件，避免再把这些业务片段内联塞回 `pages/`。
- `frontend/vite.config.ts` 保留固定第三方依赖 chunk 分组（`framework / state-query / ui-radix / icons / charts / markdown`）；业务源码不再强制切 `ai-steward / sstc / governance` chunk，避免业务模块循环依赖在生产预览中触发初始化顺序错误。登录页与基础导航的体积治理继续依赖 route/page-section lazy。
- 旧登录残留 `frontend/src/components/ui/sign-in.tsx` 与 `frontend/src/components/ui/demo.tsx` 已删除，`frontend/src/components/login/` 成为唯一登录实现真源。
- 前端开发链路已按职责拆分：`docker-compose.dev.yml` 下的 Vite 热更新开发前端固定占用 `5174`，静态生产预览前端默认改为 `5175`；`frontend/scripts/dev-entrypoint.sh` 避免每次容器启动都执行 `npm ci`，`frontend/scripts/login-live-check.mjs` 与 `package.json` 中的 `verify:login-fast / verify:login-responsive / verify:login-full`、`capture:login:matrix` 作为登录页快回路验证入口，截图产物统一落到 `frontend/output/login/`。
- `frontend/src/api/taskBriefs.ts`
- `frontend/src/api/modelRouting.ts`
- `frontend/src/api/aiRouting.ts`
- `frontend/src/api/mcp.ts`
- `frontend/src/api/knowledgeGraph.ts`
- `frontend/src/api/semanticFacts.ts`
- `frontend/src/api/queryRouteGovernance.ts`
- `frontend/src/api/mountedAi.ts`
- `frontend/src/api/feedbackCenter.ts`
- `frontend/src/api/sstc.ts`
- `frontend/src/components/sstc/`
- `frontend/src/pages/scheduler-center/components/`
- `frontend/src/pages/ai-routing/`（平台 AI 运行层页面；业务场景路由优先消费后端 `scene_contract / scene_health / release_gate`，`sceneContracts.ts` 仅作为前端 fallback）
- `backend/app/services/ai_routing_scene_contracts.py`（业务场景路由合同 registry；active 场景参与健康度和发布门禁，candidate 场景只展示合同）
- `backend/app/config/ai_function_runtime_profiles.py` + `backend/app/services/ai_function_runtime_profile_service.py`（Function Runtime Profile 配置与发布服务；保存场景内生成预算、修复预算、temperature、响应模式、前台等待、provider/job 超时、最大重试、大输入策略、冒烟结果和发布历史到 `integrations(type='ai_function_runtime_profiles')`，当前 Project Launch 草案生成运行时只消费 active profile，draft 只用于平台 AI Ops 校验、冒烟和发布预览；active profile 实际控制 provider HTTP timeout、draft job timeout、transient retry budget、large 输入预处理和前端等待窗口）
- `frontend/src/pages/platform/AICallTracesPage.tsx` + `frontend/src/api/aiCallTraces.ts` + `backend/app/api/ai_call_traces_api.py` + `backend/app/services/ai_call_trace_service.py`（平台 AI 调用审计；只读消费 `ai_call_logs`，按 provider/model/scene/slot/trace/status/time/keyword 过滤，默认只展示真实上游调用记录，能力探测按 `probe_capability_*` 单项上游调用显示，其中 `probe_capability_model_self_report` 是模型自报参考而非 verified 槽位证据；历史 `probe_engine_capabilities` 汇总行默认隐藏；详情只展示完整脱敏 provider 请求/响应 payload、上游尝试链、routing/probe meta、tokens/cost/latency、错误诊断和场景 timeout 策略，不在详情中展示兼容 prompt/response 字段；`structured_timeout` 独立展示为模型超时，不与 JSON 无效/空响应混淆）
- `backend/app/services/ai_scene_runtime_policy.py`（AI 场景运行策略服务；按业务场景、function 和输入规模桶输出 `foreground_wait_seconds / provider_timeout_seconds / job_timeout_seconds / scene_fallback_policy / large_input_policy` 等显式 routing meta。Project Launch draft 当前由该服务提供 small/normal/large 默认策略，再由已发布 Function Runtime Profile 覆盖可运营字段，large 输入标记为预处理/分段生成方向）
- `frontend/src/pages/platform/PromptAssetsPage.tsx` + `frontend/src/api/promptAssets.ts` + `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`（平台 Prompt 运营中心；聚合 prompt registry、默认 seed、`prompt_releases` active/draft、`prompt_release_checks` 门禁状态、分层 `prompt_golden_cases`、`prompt_replay_runs / prompt_replay_case_results`、`ai_call_logs` prompt 质量摘要、跨客户空间 PMFlow OS `pmflow_ai_feedback_events` 用户反馈、`optimizer_candidates` 优化候选、调用点和迁移状态，并对 `managed_release` prompt 提供草稿创建、激活和回滚；`guarded_release` 可创建候选并运行契约回放或 LLM 回放，LLM replay 走 `llm_service` 本地路由层并记录 baseline/candidate call log、judge score/label/reason；PMFlow OS 负反馈只生成待复核 `JudgeRun / OptimizerCandidate`，由平台 AI Ops 人工复核后再进入 release 流程，不直接修改 active prompt；golden replay 无样本或无 replay run 时 fail-closed，blocking 样本失败阻塞发布，important/observation 样本失败进入 warning/人工复核；release watch 汇总 24h/7d 质量、结构化异常、默认回退与健康/复核/回滚建议；`inline_discovered` 只表示已梳理但待迁移的代码散落 prompt）
- `frontend/src/pages/ai-steward/components/`
- `frontend/src/lib/`
### 5.3 前端结构边界
- 页面级编排逻辑优先收敛到 `pages/*/` 子目录。
- API 调用统一走 `frontend/src/api/`，不在页面或组件内直接 `fetch`。
- `frontend/src/components/sstc/` 继续作为 SSTC 共享组件目录维护。
- AI Steward 浮窗的“当前对象/来源模式/证据状态”必须直接消费 `/rag/ask` 与 QA session API 的显式 contract 字段，禁止在前端靠回答正文反推 internal/external 或 plan 状态。
- 网页问答显式锚点 v1 只能消费稳定强锚点：项目页路径中的 `project_id` 与 URL query 中已显式存在的 `project_id/source_chat_id`；前端禁止自行猜测 `source_chat_id`。
- `/ai-config` 是空间级 AI 使用设置，技术路由继续保留但用户可见不再叫“AI 运营中心”“管理后台”或泛化 AI Config；`/ai-config` 及其子路由必须使用空间配置壳 `SpaceSidebar(activeLabel="AI 使用设置") + SpaceTopBar`，让用户仍处在个人空间/团队空间的配置上下文，不得切入项目工作台侧栏；`/ai-config?tab=setup` 由 `AISetupWizard` 承接 AI 可用状态和项目生成能力门禁，只展示空间业务影响、团队策略和连接入口，不展示“启用供应商/路由/连接测试/额度诊断”类平台动作；连接、知识、团队策略、MCP 模板使用和 Prompt 策略继续组织客户空间可控能力，并明确这些配置影响当前团队空间内所有项目。`AIReadiness` 必须遵守双层表达：用户端默认客户视图，平台人员在用户端也只能通过显式 `platformDiagnostic` 查看 cause/CTA；`/platform/*` 默认平台诊断视图，展示供应商、全局路由、模型槽位、诊断、失败样本和处理动作。平台供应商、全局路由、route/context、semantic facts、高级函数路由和跨租户运营诊断不在客户空间暴露，统一进入 `/platform/*`，由 `PlatformBoundary` 和 `platform_context.capabilities` 保护；旧 `/ai-config/contract-sync-board`、`/ai-config/query-route-governance`、`/ai-config/ai-routing-console`、`/ai-config/model-routing-config`、`/ai-config/knowledge-graph-board` 和 `/ai-config/semantic-facts-board` 只做兼容跳转到 `/platform/*`，其中 model routing 旧入口跳到隐藏 `/platform/route-lab`，避免平台页套入空间壳。`/platform/*` 使用 `PlatformSidebar + PlatformTopBar` 专属壳，侧栏按运行总览、AI 运行层、工具与外部能力层、上下文与语义层、质量与事件层组织，不复用旧项目工作台导航；隐藏 Route Lab 不进侧栏，只读展示函数级规则、最近执行与历史 override 痕迹。AI 路由与供应商控制台由 `backend/app/api/ai_routing.py` 与 `backend/app/services/ai_routing_governance_service.py` 提供聚合，客户负责人只看业务场景策略，平台 AI Ops 才看供应商连接、快速/深度槽位、场景路由、诊断和审计提示；平台 AI 运行总览已合并进 `/platform`，旧 `/platform/ai-routing-console` 只做兼容跳转；AI 运行层前端保留 `/platform/ai-routing-providers`、`/platform/ai-routing-slots`、`/platform/ai-routing-scenes`、`/platform/ai-routing-costs`、`/platform/ai-routing-failures` 五个明确子菜单，共享同一脱敏 admin-console 合同；质量与事件层新增 `/platform/ai-call-traces` AI 调用审计，只给平台 AI Ops 查看 `ai_call_logs` 的脱敏出入参、完整脱敏 provider 请求/响应 payload、上游尝试链、provider/model/slot/routing/tokens/cost/latency 和错误摘要，未脱敏 provider payload、headers 与密钥不暴露；团队策略只写 `integrations(type='ai_team_policy')`，供应商连接写 `integrations(type='llm_engine')` 并在 engine config 内分层保存声明 capabilities、`capability_probe` live evidence 与后端派生 `effective_capabilities`，旧 flat `capability_evidence` 只做兼容；能力探测必须按 registry 逐项验证，JSON Schema 独立于普通 JSON 输出，长上下文声明窗口只能作为 `declared_only`；供应商页允许平台操作人对高成本长上下文能力执行“确认长上下文”，写入带来源、确认人和过期时间的 `operator_verified/operator_attestation` 证据，满足发布校验但不进入 AI 调用审计；能力槽位写 `integrations(type='ai_capability_slots')`，但只有发布后的 `active.slots` 会由 `llm_service` low/high/structured tier 解析消费，draft 只用于平台编辑、校验、发布和回滚；能力槽位发布校验按 `SLOT_REQUIREMENTS` 对 draft primary/fallback 的能力矩阵、缺证据和证据过期做阻塞检查，low 缺 probe 只 warning，reserved 槽当前只展示候选/缺口，除非 draft 显式配置运行时，否则不接 runtime 消费；`backend/.control_plane/pmflow-routing-rules.json` 只作为 baseline rule pack 与冷启动 fallback。MCP 页负责模板化配置、后端直连/Local Bridge 状态展示、runtime probe、命令预览与本机确认；contract sync、route/context、knowledge graph 和 semantic facts 页属于平台 AI Ops 排障治理入口。
- `/platform/prompt-assets` 属于平台质量与事件层，不是客户空间 Prompt 策略页。它可展示平台内部 prompt 正文、默认模板 hash、active/draft release、release gate、replay run、质量归因、golden case、调用点和迁移缺口；客户空间、Space、Project Launch 和项目级 AI 副驾不得暴露 prompt body。标记为 `inline_discovered` / `needs_migration` 的资产只代表已完成清单梳理，运行时仍需单独迁移调用点到 PromptRuntimeService/PromptReleaseService 后才算可运营生效；`guarded_release` 可创建候选但激活必须通过 replay/schema/golden case 门禁，当前 golden replay 无 active golden case 或无最新 replay run 时保持阻塞；LLM 回放只允许通过本地路由层和显式 routing_meta 执行，不在运营页硬选模型。
- Workspace / Platform 账号边界：当前新增兼容层 `tenant_memberships / tenant_invitations`，把产品语义从“企业租户账号”收敛到 `solo-first, team-ready` 的个人空间/团队空间。手机号是登录、自注册与邀请绑定的主身份，后端通过 `phone_verification_codes`、`users.phone_e164` 和 `tenant_invitations.phone_e164` 串起“验证手机号 -> 创建或绑定账号 -> 创建个人空间 -> 接受团队邀请”的链路。用户账号不归团队所有；注册或受邀创建账号时必须有个人空间，接受邀请只是增加团队空间 membership，退出团队空间后仍保留个人空间。PMFlow 内部平台身份由 `platform_memberships` 单独承载，并在登录响应和 `/users/me` 返回 `platform_context`，客户空间 `OWNER` 不自动拥有平台能力。历史数据修复由 `backend/alembic/versions/20260428_repair_admin_yangyu_workspace_state.py` 承接：`tenant_id=1` 保留为旧团队空间，admin/yangyu 的当前激活 `users.tenant_id` 分别指向自己的 personal workspace。
- AI 路由与供应商用户可见层必须脱敏并分平面：成员视图不得出现 low/high、provider、model、`function_name`、`api_env`、raw routing meta 或明文 key；客户空间负责人只看“质量优先 / 成本均衡 / 速度优先”和项目启动、需求结构化、任务拆解、人员匹配、内部问答、外部查询、飞书理解、飞书回复等场景策略；平台 AI Ops 的业务场景路由也不展示 `function_name`，函数级路线只允许隐藏 Route Lab 只读诊断。
- 左侧导航不再展示团队负载、能力管理、用户管理或 AI 运营中心作为一级产品入口；旧 `/projects`、`/users`、`/users/:id/profile`、`/users/:id/skills`、`/users/:id/skill-tasks/:skillId`、`/workloads`、`/workloads/:id` 与 `/dashboard` 均只作为兼容入口：`/projects` 跳转 `/space/projects`，用户相关旧路径跳转 `/space/settings/members` 或成员详情，`/workloads*` 跳转 `/team-layer?view=capacity`，`/dashboard` 跳转 `/space`。用户可见语义分别收敛为所有项目、成员与权限、团队今日容量；`/space/projects` 使用空间壳承载项目集合和主流程分流，删除等高风险项目动作只放入高级操作；`/team-layer` 承载 reviewer routing、Team Feed、执行能力、自适应容量、负责人容量模拟/调整与团队空间预留；客户侧 AI 使用设置归入 `/ai-config`，PMFlow 平台 AI 路由、供应商和语义治理归入 `/platform/*`。项目级页面通过顶部/右侧 `AI 副驾` 消费 AI 能力，只展示副驾状态、上下文缺口、待确认和项目流程跳转，不提供供应商、模型、MCP 模板或底层路由配置。
- PMFlow OS 原型页是前端独立产品域，不复用 `AI Steward` / `Project Board` 的旧信息架构；新页面只允许消费 `frontend/src/features/pmflow-os/store.tsx` 的共享状态和行为组件，避免把原型再拖回 SSTC/治理后台语义。个人空间首页、新项目启动台和 Account Settings 同样是独立产品域：Space 只能通过 `frontend/src/api/space.ts` 做项目摘要、PMFlow OS `truth-state / execution-summary / execution-capabilities` 的只读聚合并跳回主流程；Project Launch 默认走真实 draft/confirm 创建链，只有显式 demo 参数才使用本地状态机；Account Settings 只管理个人资料、偏好和通知，不改 OAuth/JWT/auth core、PMFlow OS truth store、Project Memory、ChangeSet 或 Execution Bridge 写回。
## 6. 工具与运行库存
- `backend/scripts/repair_requirement_plan_history.py`
- `scripts/start_model_probe.sh`
- `scripts/model_probe.py`
- `scripts/gen_task_brief.sh`
- `scripts/check_contract_sync.sh`
- `frontend/playwright.config.ts`
- `frontend/vitest.setup.ts`
- `frontend/e2e/feishu-project-full-flow.spec.ts`
- `frontend/scripts/dev-entrypoint.sh`
- `frontend/scripts/login-live-check.mjs`
- 前端到后端访问链路已收敛为同源 `/api`：开发环境由 Vite proxy 转发，生产环境由 nginx `/api` 反代；临时外网访问脚本与浏览器侧绝对 API base 配置已移除。
## 7. 维护建议
- 想看“现在怎么跑、边界怎么定”：先看 `AGENTS.md`，再看 `CLAUDE.md`
- 想看“模块都搬到哪里了、目录怎么分组”：看本文档
- 想看“接口/数据流契约”：看 `docs/architecture/API_CONTRACTS.md` 与 `docs/architecture/DATAFLOW.md`
Reference in New Issue View Git Blame Copy Permalink