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

255 lines
64 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/INBOX_INLINE_OPS_3_PHASE_CHECKLIST.md`：消息台内联操作执行清单
- `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/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/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/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 开销。
### 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/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` 写回运行时，`subject_focus / query_profile.referenced_objects` 已从 production backend 移除，不再参与 route snapshot、session scope continuity 或任何 read-side 分流。
- `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 / 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、GLM 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/inbox/`
- `frontend/src/pages/ai-steward/`
- `frontend/src/pages/scheduler-center/`
- `frontend/src/pages/project-board/`
- `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/`
- `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/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/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` 锁定。
- 登录页与营销页仍共享 `frontend/src/components/marketing/` 的部分视觉基线；公开登录页现改由 `frontend/src/components/login/` 目录承载，其中 `LoginExperience.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`。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` 提供可直接打开的入口；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 副驾”的全局骨架，同时承接项目内 `个人空间 / 当前项目名` 面包屑和项目切换器；账号退出登录由 `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`。
- 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` 生成 `nextActionQueue` 我的下一步队列、继续推进、待确认、发布关注、发布后反馈关注、下一轮迭代草稿关注、执行中 / AI 正在推进、暂存想法、草案箱、最近项目摘要；Space P6 的 `nextActionQueue` 按高风险 ChangeSet 待确认、release blocked / failed evidence、handoff consumed 但无后续 progress、iteration draft 待确认、feedback/revenue/compliance 信号待处理排序，并只提供 `/change-review`、`/execution-bridge`、`/release-growth` 跳转。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>`；暂存想法后端只读聚合尚未接入时只显示 empty/warning，不使用 mock 数据冒充真实内容；移动端为空间首页独立 App 布局，不直接压缩桌面卡片，并保留最近项目区块；`frontend/src/pages/PersonalSpacePage.tsx` 是薄入口。该域只表达个人空间和主流程导航，不做团队空间强切换、企业组织管理、Project Memory 写入、ChangeSet 状态写入、ProgressEvent 写入、ReleaseValidationRun 写入、FeedbackIngest 写入或发布执行。
- 前端主包治理已切到“同步首屏最小集 + 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` 提供可直接打开的入口；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` 现在可以请求审查、通过、要求修改或拒绝当前 ChangeSet，并展示审查状态、审查意见与 high-risk approval gate；`TeamLayerPage.tsx` 现在消费 `ProjectTruthState.reviewerRouting(status/summary/items)` 展示待审 ChangeSet、来源、风险等级、建议审查人或 fallback role、审查原因、待审 item 数、证据数、warning、审查状态、审查意见和请求/决策时间，动作跳 `/change-review?projectId=<id>&changeSetId=<id>`；账号退出登录由 `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` 生成 `nextActionQueue` 我的下一步队列、继续推进、待确认、发布关注、发布后反馈关注、下一轮迭代草稿关注、执行中 / AI 正在推进、暂存想法、草案箱、最近项目摘要；Space P6 的 `nextActionQueue` 按高风险 ChangeSet 待确认、release blocked / failed evidence、handoff consumed 但无后续 progress、iteration draft 待确认、feedback/revenue/compliance 信号待处理排序，并只提供 `/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>`。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、发布验证、发布后信号或下一轮 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>`；暂存想法后端只读聚合尚未接入时只显示 empty/warning，不使用 mock 数据冒充真实内容；移动端为空间首页独立 App 布局，不直接压缩桌面卡片，并保留最近项目区块；`frontend/src/pages/PersonalSpacePage.tsx` 是薄入口。该域只表达个人空间和主流程导航，不做团队空间强切换、企业组织管理、Project Memory 写入、ChangeSet 状态写入、PMFlowApproval 写入、ProgressEvent 写入、ReleaseValidationRun 写入、FeedbackIngest 写入或发布执行。
- 前端主包治理已切到“同步首屏最小集 + 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` 提供可直接打开的入口；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)` 展示待审 ChangeSet、来源、风险等级、建议审查人或 fallback role、审查原因、待审 item 数、证据数和 warning，动作只跳 `/change-review?projectId=<id>&changeSetId=<id>`，不自动 assign reviewer；账号退出登录由 `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/project-launch/types.ts`、`mockData.ts`、`useProjectLaunchState.ts` 是新项目启动台状态层；默认真实模式通过 `frontend/src/api/pmflowLaunch.ts` 生成草案并确认创建真实项目，API 失败进入明确失败态，不静默 fallback 成 mock 成功；`mockData.ts` 仅在显式 `?demo=1` 或 `?dataSource=demo` 下作为演示状态机使用。`components/LaunchShell.tsx` 负责桌面/移动分流，桌面端复用 `frontend/src/features/personal-space/components/SpaceChrome.tsx` 的空间左侧栏和顶部条，`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`，真实模式下项目内 message、`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 成功。
- `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` 是决策与待确认中心，`MemoryWritebackResultPage.tsx` 是项目记忆写入结果页，`WorkGraphPage.tsx` 是项目工作台关系总览与对象投影视图，`ExecutionBridgePage.tsx` 是执行桥上下文包、交接按钮、运行端领取确认、PR/测试与回写状态页；`ReleaseGrowthPage.tsx` 真实模式读取 `execution-summary.releaseGate`、`latestValidationRun` 与 `releaseSignals`，从 branch、commit、PR、test、failed evidence 展示 `可发布 / 阻塞 / 需要人工确认 / 缺少证据` 判断、阻塞原因、下一步动作、发布验证记录和发布后 feedback/revenue/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 提取，不把 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` 表达“未确认不得写入”的局部提示。
- `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`，真实模式下项目内 message、`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 均调用 `/pmflow-os` 后端并 refetch；只有显式 `?demo=1` 或 `?dataSource=demo` 时才启用本地 mock 演示状态机。真实读取/动作失败会进入错误/空态，不静默 fallback 成 mock 成功。
- `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` 是决策与待确认中心，`MemoryWritebackResultPage.tsx` 是项目记忆写入结果页，`WorkGraphPage.tsx` 是项目工作台关系总览与对象投影视图，`ExecutionBridgePage.tsx` 是执行桥上下文包、交接按钮、运行端领取确认、PR/测试与回写状态页；`ReleaseGrowthPage.tsx` 真实模式读取 `execution-summary.releaseGate`、`latestValidationRun` 与 `releaseSignals`，从 branch、commit、PR、test、failed evidence 展示 `可发布 / 阻塞 / 需要人工确认 / 缺少证据` 判断、阻塞原因、下一步动作、发布验证记录和发布后 feedback/revenue/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 提取，不把 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`，Change Review / commit / review decision 服务位于 `backend/app/services/pmflow_change_review_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` 对应真实表。`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、`proposed_items` extraction、ChangeSet detail、ChangeItem `accept/edit/defer`；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 和 iteration recommendation 读模型；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。
- 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。
- `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` 现补了固定 vendor chunk 分组（`framework / state-query / ui-radix / icons / charts / markdown`）与业务 chunk 分组（`ai-steward / sstc / governance`），目标是让登录页与基础导航不再背 AI Steward、SSTC、治理页和图表代码。
- 旧登录残留 `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/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/inbox/`
- `frontend/src/components/sstc/`
- `frontend/src/pages/scheduler-center/components/`
- `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 -> Governance Tools` 现新增 `/ai-config/mcp-config`、`/ai-config/query-route-governance` 与 `/ai-config/semantic-facts-board` 入口；三类治理页都只对 `BOSS/ADMIN` 开放。MCP 页负责模板化配置、后端直连/Local Bridge 状态展示、runtime probe、命令预览与本机确认；route/context 页负责 mismatch、clarify-heavy 与 negative feedback 样本排查；semantic facts 页负责 KPI、队列、对象表与详情抽屉。
- 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` 的只读聚合并跳回主流程；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